@@ -0,0 +1,136 @@
1+# Audit Report — mini-coder v0.2.0
2+
3+**Date:** 2026-03-21
4+**Auditor:** Claude Code (automated audit)
5+**Scope:** Full codebase review + multi-provider interactive testing
6+
7+---
8+
9+## Summary
10+
11+### How I tested
12+
13+- **Code review:** Read every module in `src/` (15k lines across 126 files), ran all static checks (`typecheck`, `lint`, `knip`, `jscpd`, `test`), and compared implementation against the core idea in AGENTS.md.
14+- **Multi-provider testing:** Exercised 5 SDK paths via tmux — one-shot and interactive multi-turn sessions with tool calling:
15+ - `zen/claude-haiku-4-5` — `@ai-sdk/anthropic` via Zen
16+ - `zen/gemini-3-flash` — `@ai-sdk/google` via Zen
17+ - `zen/gpt-5.4-nano` — `@ai-sdk/openai` (responses endpoint) via Zen
18+ - `zen/kimi-k2.5` — `@ai-sdk/openai-compatible` via Zen
19+ - `anthropic/claude-haiku-4-5` — direct Anthropic OAuth
20+- **Static analysis results:** 286 tests pass, 0 lint issues, 0 type errors, 0 unused exports (knip), 2 minor code clones (23 lines, 0.16%).
21+
22+### Overall assessment
23+
24+The codebase is well-structured and clean. All provider paths work correctly for both one-shot and interactive use. The architecture aligns closely with the core idea. The known issues file accurately tracks existing problems. Most findings below are minor.
25+
26+---
27+
28+## Code & Architecture
29+
30+### Correctness issues
31+
32+1. **MCP client reports hardcoded version `0.1.0`** (`src/mcp/client.ts:31`)
33+ The MCP client identifies itself as `version: "0.1.0"` while the package is at `0.2.0`. This should use the actual package version (the same `__PACKAGE_VERSION__` constant used in the banner).
34+
35+2. **`isAbortError` relies on string matching** (`src/agent/agent-helpers.ts:13–17`)
36+ `isAbortError` checks `error.name === "AbortError"` OR `error.message.toLowerCase().includes("abort")`. The message fallback is overly broad — any error mentioning "abort" (e.g. "Transaction aborted by user") would be treated as a cancellation. This hasn't caused issues in practice but is a latent correctness risk.
37+
38+3. **Shell `!` integration silently drops context for empty output** (`src/cli/input-loop.ts:98`)
39+ When a `!` shell command produces no stdout, no stderr, and exits successfully, `buildShellContext` returns an empty string and `addShellContext` is skipped entirely. The user sees the command run but nothing is recorded. For `!ls` in an empty dir this is fine, but for side-effect commands like `!git commit` the exit status context is lost.
40+
41+### KISS / DRY / YAGNI
42+
43+4. **Duplicate frontmatter parsers** (already tracked in KNOWN_ISSUES.md)
44+ `parseFrontmatter` in `cli/frontmatter.ts` and `parseSkillFrontmatter` in `cli/skills.ts` implement the same YAML-like frontmatter parsing with slightly different APIs. The skills variant reads from file descriptors for performance (only reads first 64KB), which is a good optimization, but the parsing logic itself is duplicated.
45+
46+5. **Truncation helpers are scattered** (already tracked in KNOWN_ISSUES.md)
47+ At least 4 independent truncation implementations: `truncate` in `tool-render.ts`, `truncateOneLine` in `tool-result-renderers.ts`, `truncatePlainText` in `status-bar.ts`, and `compactHeadTail` in `turn-context.ts`. The LLM-facing truncation (`compactHeadTail`) is structurally different from the UI-facing ones, so not all can be consolidated, but the three UI truncation functions share the same pattern.
48+
49+6. **`getMessageDiagnostics` builds maps that are only consumed by logging** (`src/llm-api/turn-context.ts`)
50+ The full diagnostics function (`getMessageDiagnostics`) is only called from the API logging path. The lightweight `getMessageStats` exists for the hot path. This is actually good design — no violation — but the `getMessageDiagnostics` function is quite heavyweight for diagnostic-only use; worth noting it's correctly excluded from the critical path.
51+
52+### Idea alignment
53+
54+7. **System prompt doesn't mention file creation workflow**
55+ The system prompt describes `mc-edit` for editing existing files but doesn't mention how to create new files (using shell commands like `cat >` or `printf`). During GPT Nano testing, the model tried `mc-edit` for file creation, got two errors, then self-corrected. Adding a brief note about file creation would save tokens on error recovery.
56+
57+8. **`maxOutputTokens` hardcoded to 16384** (already tracked in KNOWN_ISSUES.md)
58+ The value in `turn-request.ts:82` is a fixed constant. The core idea says to derive from model info. Model data is already available via `resolveModelInfo()`.
59+
60+9. **No conversation summary on max context** (already tracked in KNOWN_ISSUES.md)
61+ The `error-parse.ts` surfaces a "Max context size reached" error with hint "Use /new to start a fresh session". The core idea wants "a conversation summary" instead of just an error.
62+
63+---
64+
65+## UI/UX Alignment
66+
67+### Cross-provider consistency
68+
69+All five tested paths produce visually consistent output:
70+
71+- **Banner** renders correctly with model, cwd, skills count, and toggle states.
72+- **Status bar** shows model, session ID, token counts, context usage, and cwd. Format is consistent across all providers.
73+- **Tool call display** uses correct semantic glyphs (`←` for reads, `✎` for writes, `$` for exec, `?` for search). Truncation at 80 chars works.
74+- **Tool results** show structured output: exit code, stdout/stderr line counts, inline single-line results.
75+- **Assistant text** prefixed with `◆`, user prompts with `›`.
76+- **Spinner** shows during thinking, clears correctly before output.
77+
78+### Provider-specific observations
79+
80+| Provider | One-shot | Interactive | Multi-turn | Notes |
81+| ---------------------------- | -------- | ----------- | ---------- | --------------------------------------------------- |
82+| `zen/claude-haiku-4-5` | ✅ | ✅ | ✅ | Clean tool use, good output |
83+| `zen/gemini-3-flash` | ✅ | ✅ | — | Efficient: combined create+read in one tool call |
84+| `zen/gpt-5.4-nano` | ✅ | ✅ | — | Tried mc-edit for new file, self-corrected (see #7) |
85+| `zen/kimi-k2.5` | ✅ | ✅ | — | Leading whitespace in one-shot output (cosmetic) |
86+| `anthropic/claude-haiku-4-5` | ✅ | ✅ | ✅ | Clean, ESC interrupt works |
87+
88+### UI issues observed
89+
90+10. ~~**Double prompt glyph after ESC interrupt**~~ — Investigated: this is a tmux `capture-pane` rendering artifact, not an actual double prompt. Raw stdout analysis confirms only one `renderPrompt` call. Removed from KNOWN_ISSUES.
91+
92+11. **Token counts not updated after interrupted turn**
93+ After ESC interrupt, the status bar shows stale token counts from the previous completed turn, not from the interrupted one. The interrupted turn's partial usage isn't accumulated because the error path doesn't emit a `turn-complete` event with usage data.
94+
95+12. **Context window disappears from status bar after interrupt**
96+ After an ESC-interrupted turn, the status bar dropped the `ctx X/Y Z%` segment entirely. This is because `lastContextTokens` stays 0 when the turn is interrupted (the complete event is never processed), and `buildContextSegment` returns `null` for `contextTokens <= 0`.
97+
98+13. **`/help` skills section shows full descriptions without truncation**
99+ The ai-sdk skill description wraps across 3 lines in the help output. Skills with long descriptions should be truncated in the help display for consistency with the concise help format.
100+
101+14. **tmux `send-keys` triggers paste detection**
102+ When using `tmux send-keys` with multi-word text (without `-l`), the input handler detects it as a paste and shows `[pasted: "..."]`. Using `-l` (literal) mode for send-keys + separate Enter works correctly. This is technically correct behavior (tmux sends all chars in one burst) but makes automated testing harder. Not a user-facing issue.
103+
104+---
105+
106+## Recommendations
107+
108+### Immediate bugs (should fix)
109+
110+1. **Token count reset after ESC interrupt** — The interrupted turn's `inputTokens`/`outputTokens` from `turnState.getState()` are available in the `turn-error` event's `partialMessages` path, but `session-runner.ts` doesn't accumulate them because the `try` block throws before reaching the accumulation code. Move token accumulation to a `finally` block or accumulate from the error event.
111+
112+2. **Context window vanishing after interrupt** — Related to #1. When `lastContextTokens` is 0, the status bar omits the context segment. Either preserve the last known context tokens across interrupts, or include `contextTokens` in the error event.
113+
114+3. **System prompt: add file creation guidance** — Add one line to the mc-edit description: "To create new files, use shell commands (e.g. `cat > file.txt << 'EOF'`)." This will save tool-call roundtrips for all models.
115+
116+### Code changes (should address)
117+
118+4. **MCP client version** — Use `__PACKAGE_VERSION__` or read from package.json instead of hardcoding `"0.1.0"`.
119+
120+5. **`isAbortError` specificity** — Tighten the message check: look for "aborted" specifically, or check for `err.code === "ABORT_ERR"` instead of substring matching.
121+
122+6. **`!` shell: preserve exit status context** — When `buildShellContext` returns empty, still record something like `"(no output, exit 0)"` so the model knows the command succeeded.
123+
124+### Polish items (nice to have)
125+
126+7. **Consolidate UI truncation helpers** — The three UI-facing `truncate`/`truncateOneLine`/`truncatePlainText` functions can share a single helper.
127+
128+8. **Consolidate frontmatter parsers** — Make `parseSkillFrontmatter` call `parseFrontmatter` after reading the first 64KB chunk, or factor the regex/loop into a shared helper.
129+
130+9. **Help: truncate skill descriptions** — Limit skill descriptions in `/help` output to ~100 chars.
131+
132+10. **Double prompt glyph** — Suppress the extra newline in `stream-render.ts` when the turn was interrupted via ESC.
133+
134+---
135+
136+_This report covers audit findings only. No changes have been made. Review with the user before implementing._