@@ -1,194 +0,0 @@
1-# Performance Improvement Plan
2-
3-Based on the audit in the previous session. Three high-impact fixes, three medium fixes, four low/deferred items.
4-
5----
6-
7-## High Impact
8-
9-### P1 — Wrap `saveMessages` in a transaction
10-
11-**File:** `src/session/db/message-repo.ts`
12-
13-Each `stmt.run()` without an explicit transaction triggers its own implicit WAL flush.
14-`saveMessages` is called twice per turn (user message + model messages), each time potentially
15-writing multiple rows. `saveSnapshot` already does this correctly with `db.transaction`.
16-
17-**Change:** Wrap the insert loop in `db.transaction(() => { ... })`.
18-
19----
20-
21-### P2 — Cache `buildSystemPrompt` on `SessionRunner`
22-
23-**Files:** `src/agent/session-runner.ts`, `src/agent/system-prompt.ts`
24-
25-`buildSystemPrompt` is called on every `processUserInput`. It does:
26-- Up to 5 `existsSync` + 2 `readFileSync` calls for context files
27-- `loadSkillsIndex` → directory walk (`readdirSync` + `statSync` + `openSync`/`readSync`/`closeSync`) across 4 locations
28-
29-None of these inputs change between turns. The system prompt is fixed for the lifetime of
30-a `SessionRunner` instance (only `extraSystemPrompt` changes, and that has a setter).
31-
32-**Change:**
33-- Compute the prompt once in the `SessionRunner` constructor and store it.
34-- Re-compute only when `extraSystemPrompt` is mutated (already a public setter property).
35-- No change to the `buildSystemPrompt` function signature.
36-
37----
38-
39-### P3 — Remove intermediate diff from `applyFileEdit`
40-
41-**Files:** `src/tools/shared.ts`, `src/tools/write-result.ts`, `src/agent/tools.ts`
42-
43-Current flow for any write tool when hooks are active (the default config):
44-1. `applyFileEdit` writes the file and calls `generateDiff(original, written)` → **diff #1**
45-2. Hook runs (reformatter rewrites the file)
46-3. `finalizeWriteResult` re-reads and calls `generateDiff(original, reformatted)` → **diff #2**
47-
48-Diff #1 is always discarded when a hook fires. `generateDiff` runs an LCS O(m×n) algorithm;
49-computing it twice wastes CPU on every write in a repo with hooks.
50-
51-When no hook fires, `stripWriteResultMeta` is used, which keeps diff #1 — so that path stays correct.
52-
53-**Change:**
54-- Remove `generateDiff` call from `applyFileEdit`; store only `_before` + `_filePath`.
55-- Move diff computation into `finalizeWriteResult` (already reads the post-hook file).
56-- For the no-hook path (`stripWriteResultMeta`), add the diff computation there too so callers still receive a populated `diff` field.
57-- Update `WriteResultMeta` and `applyFileEdit` return type accordingly.
58-
59----
60-
61-## Medium Impact
62-
63-### P4 — Gate `getMessageDiagnostics` behind API log being enabled
64-
65-**File:** `src/llm-api/turn.ts`
66-
67-`getMessageDiagnostics` is called 2–3× per turn. It calls `JSON.stringify` + `Buffer.byteLength`
68-on every message in history. For long sessions (100+ messages) this serialises megabytes of data
69-just to produce numbers for the API log.
70-
71-**Change:**
72-- Check whether the API log is enabled before computing diagnostics.
73-- If disabled, skip all three `getMessageDiagnostics` calls entirely.
74-- `api-log.ts` already has the flag; expose a `isApiLogEnabled()` helper or check the env directly.
75-
76----
77-
78-### P5 — Hoist `db.prepare` to a module-level lazy singleton in `saveMessages`
79-
80-**File:** `src/session/db/message-repo.ts`
81-
82-`db.prepare(...)` compiles the SQL statement on every `saveMessages` call (twice per turn).
83-SQLite statement preparation is cheap but non-trivial; it is unnecessary to repeat it.
84-
85-**Change:**
86-- Store the prepared statement in a module-level `let` variable, initialised lazily on first use
87- (same pattern as `getDb()`).
88-- Apply the same treatment to `addPromptHistory` and `getPromptHistory` if they are on hot paths.
89-
90----
91-
92-### P6 — Avoid object spread in `withCwdDefault` per tool invocation
93-
94-**File:** `src/agent/tools.ts`
95-
96-`withCwdDefault` wraps every tool call in a new object spread:
97-```ts
98-const withDefault = { cwd, ...snapshotCallback ? {snapshotCallback} : {}, ...input };
99-```
100-This allocates a new plain object on every invocation and spreads all tool arguments.
101-
102-**Change:**
103-- Mutate `cwd` as a default on the input object only when absent:
104- ```ts
105- const patched = input as Record<string, unknown>;
106- if (patched.cwd === undefined) patched.cwd = cwd;
107- if (snapshotCallback && patched.snapshotCallback === undefined)
108- patched.snapshotCallback = snapshotCallback;
109- return originalExecute(patched);
110- ```
111-- This avoids the spread allocation entirely.
112-
113----
114-
115-## Low / Deferred
116-
117-### P7 — Replace string concatenation in `consumeTail` with chunk accumulation
118-
119-**File:** `src/agent/subagent-runner.ts`
120-
121-`tail += decoder.decode(...)` in a loop is O(n²) in theory, bounded to ~16 KB by the slicing
122-guard. Still wasteful: each iteration copies the whole accumulated string.
123-
124-**Change:**
125-- Accumulate `Uint8Array` chunks into an array.
126-- After the loop, call `new TextDecoder().decode(Buffer.concat(chunks))` once.
127-- Then slice to `maxBytes` if needed.
128-- Remove the mid-loop `tail.slice(-maxBytes)` guard; it is no longer necessary.
129-
130----
131-
132-### P8 — Replace LCS diff with Myers diff to reduce memory
133-
134-**File:** `src/tools/diff.ts`
135-
136-`lcsTable` allocates a flat `number[]` of `(m+1)*(n+1)` entries. Two 1000-line files produce ~1M
137-entries (~8 MB) per diff call. Every `replace`, `insert`, and `create` invocation pays this cost.
138-
139-**Change:**
140-- Implement Myers diff (Eugene Myers, 1986) in place of `lcsTable` / `editScript`.
141-- Myers requires only O(n·d) space where d is the number of edits — typically a small fraction of
142- file size.
143-- The public API (`generateDiff`) and unified-diff output format are unchanged; only the internal
144- `lcsTable` + `editScript` functions are replaced.
145-
146----
147-
148-### P9 — Combine sequential message-history transforms in `runTurn`
149-
150-**File:** `src/llm-api/turn.ts`
151-
152-Five separate O(n) passes over the full message history per turn:
153-`sanitizeGemini` → `stripGPTCommentary` → `stripOpenAIItemIds` → `applyContextPruning` →
154-`compactToolResultPayloads`. Each allocates a new array even when returning the same messages
155-unchanged.
156-
157-**Change:**
158-- Merge `stripGPTCommentary` and `stripOpenAIItemIds` into a single pass: both are
159- OpenAI-only, both iterate messages looking for assistant content parts to filter. They can share
160- one `messages.map(...)` call with both predicates applied per message.
161-- `sanitizeGemini`, `applyContextPruning`, and `compactToolResultPayloads` operate on different
162- structural concerns and keep their fast-path early exits; leave them as separate named functions
163- but note the combined pass reduces allocations on OpenAI sessions by one full array copy.
164-
165----
166-
167-### P10 — Move `VACUUM` off the synchronous startup path
168-
169-**File:** `src/session/db/connection.ts`
170-
171-`pruneOldData` calls `db.exec("VACUUM;")` synchronously before the CLI prompt is shown. With a
172-large or fragmented DB this can add measurable latency to startup.
173-
174-**Change:**
175-- Replace the synchronous `VACUUM` call with `setImmediate(() => db.exec("VACUUM;"))` so it runs
176- after the event loop yields control back to the CLI render path.
177-- The WAL checkpoint (`wal_checkpoint(TRUNCATE)`) is fast and can remain synchronous.
178-
179----
180-
181-## Execution Order
182-
183-```
184-P1 saveMessages transaction — 5 min, isolated, zero risk
185-P5 hoist db.prepare — 10 min, isolated, zero risk
186-P10 defer VACUUM off startup path — 10 min, isolated, zero risk
187-P7 consumeTail chunk accumulation — 15 min, isolated
188-P3 remove intermediate diff — 30 min, touches shared.ts + write-result.ts + tools.ts
189-P8 Myers diff — 60 min, self-contained in diff.ts, existing tests cover it
190-P2 cache system prompt — 45 min, touches session-runner.ts
191-P6 withCwdDefault spread — 20 min, touches tools.ts
192-P4 gate diagnostics on log flag — 20 min, touches turn.ts
193-P9 merge OpenAI message transforms — 30 min, touches turn.ts
194-```