savant-code 0.0.19 → 0.0.21

package/dev/fids/archive/FID-2026-0803-004-checkpoint-rewind.md

@@ -1,181 +0,0 @@
-# FID: Checkpoint & Rewind — Persistent Per-Turn Edit Safety Net
-
-**Filename:** `FID-2026-0803-004-checkpoint-rewind.md`
-**ID:** FID-2026-0803-004
-**Severity:** medium
-**Status:** verified
-**Created:** 2026-08-03
-**Author:** Savant
-
-**Summary:**
-Add a snapshot-based edit safety net: one persistent checkpoint per user turn that records the
-pre-edit content of every file first touched that turn, plus the conversation boundary
-(`msgIndex`) at turn start. A `/rewind` command (OpenTUI picker) lets the user restore the
-**code**, **conversation**, or **both** to an earlier turn, or **fork** a new session from it —
-without touching git. The primitive already exists as `file-snapshot-store.ts` (in-memory,
-run-scoped, currently **zero callers**); this FID promotes it into a persistent per-session
-checkpoint store and wires the user-facing flow. Modeled on Claude Code rewind and the
-DeepSeek-Reasonix `internal/checkpoint` design (git-free, `tool.Previewer` capture seam, one
-checkpoint per turn, dedup per path).
-
-> Design note (correction): Savant already has session persistence + complete session restore
-> (DB sessions, session files, `cloneSessionState` in `sdk/src/run.ts`, CLI checkpoint saves in
-> `use-send-message.ts`). Rewind is **orthogonal**: restore brings the conversation back to the
-> same state; rewind returns the *workspace files* (and optionally the conversation) to an
-> earlier turn's state. The existing run-scoped `file-snapshot-store.ts` proves the snapshot
-> concept was already intended in-tree — it just was never wired.
-
----
-
-## Environment
-
-- `packages/agent-runtime/src/tools/handlers/tool/file-snapshot-store.ts` — in-memory
-  `captureSnapshot(runId, path)` / `restoreSnapshots(runId)` / `clearSnapshots(runId)`.
-  **Repo-wide grep (packages/cli/sdk/common/agents/evals) finds zero callers** — dead but
-  purpose-built for exactly this feature.
-- File writes flow through `processFileBlock` → `postStreamProcessing` in
-  `packages/agent-runtime/src/tools/handlers/tool/write-file.ts`; all writes are dispatched from
-  `executeToolCall` in `packages/agent-runtime/src/tools/tool-executor.ts:310`.
-- Write tools: `write_file`, `str_replace`, `apply_patch` (plus `propose_*` variants that resolve
-  to them). `run_terminal_command` side effects are untrackable (same rule as Claude Code /
-  Reasonix — terminal writes are out of scope for checkpointing).
-- CLI checkpoint saves (`cli/src/hooks/use-send-message.ts`) already persist conversation state
-  per turn to the run directory — the conversation boundary and persistence location are known
-  quantities.
-
-### Findings (gap analysis — RED)
-
-#### CKR-1 — MEDIUM — the file-snapshot primitive exists but is unwired
-
-`file-snapshot-store.ts` implements exactly the capture/restore/clear lifecycle this feature
-needs, but nothing calls it. The comment claims Perfection-Loop usage (`self_correct → green`)
-that does not exist in the tree. **Fix:** promote this store to a persistent per-session store and
-wire it; do not add a parallel mechanism.
-
-#### CKR-2 — MEDIUM — snapshots are in-memory and run-scoped; they die with the run
-
-`restoreSnapshots` cannot survive a process restart or a resumed session, so there is no durable
-"undo my last turn's edits" after the fact. **Fix:** persist one JSON file per turn under the
-session directory (cheap delete, corruption-isolated), loaded on session resume.
-
-#### CKR-3 — HIGH — no user-facing rewind UX
-
-There is no `/rewind` command, picker, or restore/fork flow anywhere in the CLI. The edit safety
-net is the most-requested missing capability for this class of tool (Claude Code ships it;
-Reasonix ships it). **Fix:** `/rewind` command + OpenTUI picker with restore modes.
-
-#### CKR-4 — LOW — conversation rewind boundary not captured for rewinding
-
-`msgIndex` at turn start is derivable but not recorded in a rewind-oriented structure; the CLI
-checkpoint saves target crash recovery, not time-travel. **Fix:** persist `msgIndex` in the
-checkpoint so conversation restore + fork-from-here are deterministic.
-
-## Root Cause
-
-The snapshot concept predates the user-facing flow: `file-snapshot-store.ts` was written for a
-self-correct restore path that was never wired, leaving a purpose-built primitive dead. Session
-persistence evolved separately (crash-safe saves), so the two never met into a rewind feature.
-
-## Proposed Solution (after approval — audit-only now)
-
-1. **Persistent checkpoint store** — evolve `file-snapshot-store.ts` into
-   `checkpoint-store.ts`:
-   - `openTurn(turn, prompt, msgIndex)`, `capture(path)` (dedup: only first touch per turn),
-     `closeTurn()`, `listTurns()`, `restoreTurn(turn, { code, conversation })`,
-     `forkFrom(turn)`.
-   - Persist under the session directory: `<sessionDir>/checkpoints/<turn>.json`; load on
-     resume; bounded retention (keep last 20 turns, prune older).
-   - `FileSnap { path, content: string | null, encoding? }` — `null` content means the file did
-     not exist at turn start, so restore **deletes** it (Reasonix checkpoint semantics).
-   - Path-escape guards via `resolveAndContain` on restore.
-2. **Capture seam** — one centralized hook in `executeToolCall` (before write tools dispatch),
-   mirroring Reasonix's `tool.Previewer` approach: no per-tool code. Tracked tools:
-   `write_file`, `str_replace`, `apply_patch`. `run_terminal_command` explicitly out of scope.
-3. **Rewind UX** — `/rewind` slash command (command-registry) + OpenTUI picker listing turns
-   (prompt, time, touched paths). Confirmation prompt before any restore (read-only until
-   confirmed). Modes: **code only / conversation only / both / fork-from-here**.
-   - Restore code: write back `FileSnap` contents (delete for `content == null`).
-   - Restore conversation: truncate session messages to `msgIndex` + reload run state via
-     `cloneSessionState`.
-   - Fork: new session seeded from the checkpoint's conversation; current state untouched.
-4. **Non-goals (Phase 2, explicitly deferred):** git-backed checkpoint mode, tracking bash side
-   effects, cross-session checkpoint restore, checkpoints for `move_file` previews.
-
-## Files To Be Changed (implementation stage)
-
-- `packages/agent-runtime/src/tools/handlers/tool/file-snapshot-store.ts` → `checkpoint-store.ts`
-  (persistent store)
-- `packages/agent-runtime/src/tools/tool-executor.ts` (capture hook)
-- `packages/agent-runtime/src/tools/handlers/tool/write-file.ts` (snapshot via `processFileBlock`)
-- `cli/src/commands/command-registry.ts` (`/rewind`)
-- `cli/src/components/` (rewind picker UI) + `cli/src/state/chat-store.ts` (truncate/fork)
-- `cli/src/hooks/use-send-message.ts` (open/close turn checkpoints)
-- `sdk/src/run-state.ts` / `client.ts` (conversation restore/fork API)
-- Tests: capture dedup, restore code/conversation/both, fork, persistence across restart,
-  pruning, path-escape rejection
-
-## Verification
-
-- [x] Recon: `file-snapshot-store.ts` zero callers confirmed; session restore + checkpoint saves
-      confirmed existing (DB, session files, `cloneSessionState`, `use-send-message` saves)
-- [x] Write-tool surface + execution seam identified (`executeToolCall`, `processFileBlock`,
-      `postStreamProcessing`)
-- [x] No implementation files modified during this audit (audit-only)
-- [x] Implementation: agent-runtime + cli + sdk suites green; 4-way typecheck; zero-warning
-      ESLint; `bun run lint:md`; Prettier
-- [x] Implementation: independent AUDIT via code-reviewer; CHANGELOG entry; FID archived
-
-## Perfection Loop
-
-### Loop 1
-
-- **RED:** Completed 2026-08-03 — gap analysis against the live tree: the snapshot primitive
-  exists but is unwired (zero callers), snapshots are in-memory/run-scoped, no rewind UX, no
-  rewind-oriented conversation boundary. Existing session persistence explicitly noted and not
-  duplicated.
-- **AUDIT:** Claims verified mechanically: `captureSnapshot`/`restoreSnapshots`/`clearSnapshots`
-  have zero non-test callers repo-wide; session restore exists (`cloneSessionState` in
-  `sdk/src/run.ts`, CLI checkpoint saves in `use-send-message.ts`); write path runs through
-  `executeToolCall` → `processFileBlock` → `postStreamProcessing`. Design cross-checked against
-  Reasonix `internal/checkpoint` (git-free snapshots, one checkpoint per turn, dedup per path,
-  `Content == nil` ⇒ delete on restore) and Claude Code rewind semantics.
-- **SELF-CORRECT:** Initial framing claimed Savant "lacks a memory system" — corrected during
-  review feedback: session persistence/restore already exists and the design extends the
-  in-tree snapshot primitive rather than duplicating persistence.
-
-## Lessons Learned
-
-1. Audit before borrowing: a feature idea from another project can already exist as an unwired
-   primitive in-tree (`file-snapshot-store.ts`) — promoting it beats building fresh.
-2. Session restore ≠ rewind. Keep the distinction explicit in design docs: one resumes state,
-   the other returns state to an earlier turn.
-
-## Resolution
-
-- **Fixed By:** Savant (operator-approved implementation)
-- **Fixed Date:** 2026-08-03
-- **Fix Description:** **Stage 1 — persistent checkpoint store** (`checkpoint-store.ts`, evolving the
-  zero-caller `file-snapshot-store.ts` which was deleted): `openTurn`/`captureSnapshot`/`closeTurn`/
-  `listTurns`/`restoreTurn`/`forkFrom`, one JSON per turn under the chat's checkpoint dir, first-capture-wins
-  dedup per path, `content: null` ⇒ delete-on-restore, `resolveAndContain` re-validation of every path at
-  restore (tampered/escaped entries skipped), `CHECKPOINT_RETENTION` = 20 pruned on close, `path.basename`
-  guard on the turnId→filename mapping, and openTurn reset of stale in-memory buffers (crash recovery).
-  **Stage 2 — capture seam:** `checkpointDir`/`checkpointTurnId` threaded through
-  `AgentRuntimeScopedDeps` → SDK `getAgentRuntimeImpl` → `RunOptions` → subagent context
-  (`spawn-agent-utils`), with the capture hooked in `executeToolCall`'s write-gate immediately before
-  `write_file`/`str_replace`/`apply_patch` dispatch (subagent writes land in the same turn; terminal side
-  effects untracked per Claude Code/Reasonix rule). **Stage 3 — CLI UX:** `/rewind` command registered in
-  command-registry + slash-commands, `RewindPicker` OpenTUI overlay + `rewind-picker-store`, and
-  `executeRewind` (code / conversation / both / fork modes) with conversation truncation via
-  `truncateRunStateToHistoryLength` + `cloneSessionState`-style restore; turn lifecycle wired in
-  `use-send-message` (openTurn at aiMessageId generation, closeTurn in `finally`) and
-  `createRunConfig` pass-through. SDK index re-exports the checkpoint API for CLI/host use.
-- **Tests Added:** `checkpoint-store.test.ts` (15 tests — capture/close round-trip, null-for-created,
-  dedup first-wins, openTurn stale-buffer reset, no-op when disabled, listTurns newest-first, retention
-  prune to 20, restore + delete + path-escape rejection, fork seed + delete + missing-turn, missing-turn
-  restore); `rewind-command.test.ts` (10 tests — resolveTurnArg, truncateRunStateToHistoryLength,
-  executeRewind code/conversation/both modes, unknown-turn warning, listTurns persistence).
-- **Verified By:** Savant — independent AUDIT via code-reviewer (clean — no CRITICAL/HIGH remaining;
-  turnId filename guard + crash-recovery docs added, dedup-before-read ordering confirmed, 2 tests added)
-- **Commit/PR:** None (working tree)
-- **Archived:** Yes

package/dev/fids/archive/FID-2026-0803-005-quality-scan-hygiene-fixes.md

@@ -1,265 +0,0 @@
-# FID: Quality Scan Hygiene Fixes — Config Drift, Checkpoint Error Path, Assertion/Cast Cleanup
-
-**Filename:** `FID-2026-0803-005-quality-scan-hygiene-fixes.md`
-**ID:** FID-2026-0803-005
-**Severity:** medium
-**Status:** verified
-**Created:** 2026-08-03
-**Author:** Savant
-
-**Summary:**
-Address the findings of the codebase quality scan (ECHO compliance / performance / code quality /
-robustness): (E1) `protocol.config.yaml` version drift (`0.0.15` vs `0.0.16`); (P1a) a latent
-data-loss corner in the checkpoint safety net where `captureSnapshot`'s catch-all conflates `ENOENT`
-with any other read failure and would make `restoreTurn` DELETE an existing file it merely failed to
-read; (P1b) documented by-design rationale for the checkpoint store's synchronous IO (no code change);
-(C1) redundant `agentTemplate!` non-null assertions; (C2) an unnecessary `as string[]` cast; (C3) an
-unsafe `generator!` that masks a real `undefined` path from an `eval`'d handleSteps function; (C4) a
-silent `catch {}` on tool-call input JSON parsing.
-
----
-
-## Environment (RED — findings with evidence)
-
-### E1 — LOW — protocol.config version drift
-
-`protocol.config.yaml:11` declares `version: '0.0.15'`. `VERSION` (file) and the release manifests
-(`package.json`, `sdk/package.json`, `cli/package.json`, `cli/release/package.json`) are all `0.0.16`.
-The field is advisory (only `perfection_loop.max_iterations` is consumed at runtime per the file's own
-comments), but the config is the machine-readable contract and should track the release.
-
-### P1a — MEDIUM — checkpoint capture conflates ENOENT with all read failures (latent data loss)
-
-`packages/agent-runtime/src/tools/handlers/tool/checkpoint-store.ts:151-156`:
-
-```ts
-try {
-  buffer.files.set(filePath, fs.readFileSync(filePath, 'utf8'))
-} catch {
-  // File doesn't exist yet (creation) — record null ⇒ delete-on-restore.
-  buffer.files.set(filePath, null)
-}
-```
-
-`content: null` is the documented "file was created this turn" marker — `restoreTurn` (same file,
-`:330-337`) DELETES such files. Any non-`ENOENT` read failure — `EACCES`, `EISDIR`, `EMFILE`,
-permission sandbox denial — is indistinguishable here and would be recorded as `null`, so a rewind
-would **delete a file that exists but could not be read at capture time**. This is a swallowed-error
-violation (Law 14 / anti-pattern "Swallowed errors") inside the edit-safety net — the one subsystem
-where silent misbehavior is worst. Additionally, if a later write to the same path in the same turn
-succeeds where the first capture failed, retrying would capture *mid-turn* content as the "turn-start"
-state, violating the FID-2026-0803-004 first-capture-wins invariant.
-
-### P1b — INFO — checkpoint sync IO is correct by design (no change)
-
-`captureSnapshot`/`closeTurn`/`prune` use sync `fs` (`readFileSync`, `writeFileSync`, `readdirSync`,
-`rmSync`). Reviewed 0-EOF; the sync choice is intentional and correct:
-
-- Capture must complete **before** the write dispatches — converting to async risks a race where a
-  later write lands before the capture resolves, silently breaking rewind correctness (worse than the
-  blocking cost).
-- Cost is bounded by dedup: `buffer.files.has(filePath)` is checked **before** `fs.readFileSync`
-  (`:146-150`, the FID-004 lesson), so each unique file is read at most once per turn.
-- `closeTurn`/`listTurns`/`getTurn` run CLI-side (rewind picker, `use-send-message`), not on the agent
-  loop; `captureSnapshot` is the only sync call on the agent hot path, at most once per touched file.
-- Captured files are typical source files (small). The reads are sub-millisecond against a loop that
-  waits hundreds of ms on LLM calls.
-
-No code change; this rationale is recorded so the concern is not re-flagged.
-
-### C1 — LOW — redundant non-null assertions
-
-`packages/agent-runtime/src/run-agent-step.ts:157,163,164` — `agentTemplate!` ×3. The enclosing
-`additionalToolDefinitions` declares `agentTemplate: AgentTemplate` (required, non-nullable, verified
-in the signature at `:145-149`). The `!` is noise; no type-level purpose.
-
-### C2 — LOW — unnecessary type assertion
-
-`packages/agent-runtime/src/tools/tool-executor.ts:941` —
-`!(agentTemplate.toolNames as string[]).includes(toolCall.toolName)`. `toolNames` is typed
-`(ToolName | (string & {}))[]` (`common/src/types/agent-template.ts:134`); `ToolName` is a string
-literal union (`common/src/tools/constants.ts:120`), so `ToolName | (string & {})` widens to `string`
-and the array is already `string[]`-assignable. `toolCall.toolName` is `string` (SavantCodeToolCall),
-so `.includes(...)` typechecks without the cast.
-
-### C3 — LOW/MEDIUM — unsafe `!` on a possibly-undefined generator
-
-`packages/agent-runtime/src/run-programmatic-step.ts:256` — `generator!.next(...)`. `generator` is
-`StepGenerator | undefined` sourced from the module map `runIdToGenerator` (`:40,169`). It is
-initialized when absent (`:172-208`), but `generatorFn` may be `deserializeHandleSteps(...)` — an
-`eval`'d, cast function (`:44-48`) that can return `undefined` at runtime. The `!` dereferences
-silently; the resulting `TypeError` is caught by the outer catch and misreported as a generic
-"Error executing handleSteps" with a misleading message. A definite-assignment guard yields a
-diagnosable error instead (Law 6 / Law 14).
-
-### C4 — LOW — silent catch on tool-call input parsing
-
-`packages/agent-runtime/src/tool-stream-parser.ts:122` — `catch {}` around `JSON.parse` of a
-string-typed tool-call `input`. The pass-through behavior is intentional (executor surfaces a clear
-error — documented at `:117-119`), but the failure is invisible to analytics/traces. A `Logger` is
-already in scope (`:77,95`), so a debug trace costs nothing.
-
----
-
-## Root Cause
-
-These are hygiene drift findings from an ongoing quality program, not a single defect. The one
-substantive item (P1a) comes from an over-broad `catch` written to distinguish "file doesn't exist"
-from "anything else" without actually discriminating the error code — a classic swallowed-error
-shortcut in a subsystem whose entire purpose is safety.
-
-## Proposed Solution (after approval — audit-only now)
-
-**E1** — `protocol.config.yaml:11`: `version: '0.0.15'` → `version: '0.0.16'`.
-
-**P1a** — `checkpoint-store.ts`: discriminate the error code using the repo's established narrowing
-pattern (`common/src/util/paths.ts:72-78` — `'code' in err && typeof err.code === 'string'`, Law 11):
-
-- `ENOENT` → record `null` (unchanged; file created this turn ⇒ delete-on-restore).
-- Any other error → add the path to a new per-turn `skippedPaths: Set<string>` on `OpenTurnBuffer`
-  and leave it out of `files`. `captureSnapshot`'s dedup becomes
-  `buffer.files.has(filePath) || buffer.skippedPaths.has(filePath)`, so the path is never re-captured
-  mid-turn (preserves the first-capture-wins invariant) and `restoreTurn` never touches it — the file
-  is simply not restorable that turn, which is strictly safer than deleting it.
-
-**P1b** — no code change; rationale recorded above.
-
-**C1** — `run-agent-step.ts:157,163,164`: drop the three `!`.
-
-**C2** — `tool-executor.ts:941`: `agentTemplate.toolNames.includes(toolCall.toolName)` (drop the cast).
-
-**C3** — `run-programmatic-step.ts`: after the `if (!generator)` initialization block, add:
-
-```ts
-// Definite-assignment guard: generatorFn (possibly eval'd) may return undefined;
-// fail diagnosably rather than dereferencing undefined in the loop below.
-if (!generator) {
-  throw new Error(
-    `handleSteps for agent ${template.id} did not return a generator`,
-  )
-}
-```
-
-and change `generator!.next(` → `generator.next(`.
-
-**C4** — `tool-stream-parser.ts:120-124`: log the parse failure at debug level:
-
-```ts
-} catch (error) {
-  logger.debug(
-    {
-      toolName,
-      inputLength: input.length,
-      error: getErrorObject(error),
-    },
-    'Tool-call input was a string that failed JSON.parse; passing through as string — the executor will surface a clear error',
-  )
-}
-```
-
-plus import `getErrorObject` from `@savant-code/common/util/error` (already the source of the
-`PromptResult` import in this file).
-
-**Non-goals:** no async conversion of the checkpoint store (P1b rationale); no change to the
-`closeTurn` best-effort persistence swallow (documented, host-side, intentionally non-fatal); no
-general empty-catch sweep beyond C4/P1a (the scan found no other production empty catches in the
-agent-runtime hot path).
-
-## Files To Be Changed (implementation stage)
-
-- `protocol.config.yaml` (E1)
-- `packages/agent-runtime/src/tools/handlers/tool/checkpoint-store.ts` (P1a)
-- `packages/agent-runtime/src/run-agent-step.ts` (C1)
-- `packages/agent-runtime/src/tools/tool-executor.ts` (C2)
-- `packages/agent-runtime/src/run-programmatic-step.ts` (C3)
-- `packages/agent-runtime/src/tool-stream-parser.ts` (C4)
-- Tests: `checkpoint-store.test.ts` (P1a), `sandbox-generator.test.ts` or
-  `run-programmatic-step.test.ts` (C3, only if an existing assertion depends on the old TypeError
-  message — check at implementation)
-
-## Verification
-
-- [x] Recon: versions compared (`VERSION`/manifests `0.0.16` vs `protocol.config.yaml:11` `0.0.15`)
-- [x] `checkpoint-store.ts` read 0-EOF; capture call-graph verified: `captureSnapshot` called from
-      `tool-executor.ts:461` (write gate); `openTurn`/`closeTurn` from
-      `cli/src/hooks/use-send-message.ts:576/967`; `restoreTurn` delete-on-null confirmed at
-      `:330-337`
-- [x] `run-programmatic-step.ts` read 0-EOF; `generator` narrowing + `generatorFn` eval path confirmed
-- [x] `ToolName` definition (`common/src/tools/constants.ts:120`) and `toolNames` type
-      (`agent-template.ts:134`) confirm C2 cast is removable
-- [x] `Logger.debug(data, msg)` contract confirmed (`common/src/types/contracts/logger.ts`); `logger`
-      in scope at `tool-stream-parser.ts:77,95`
-- [x] Repo ENOENT pattern confirmed (`common/src/util/paths.ts:72-78`) for Law-6-compliant narrowing
-- [x] No implementation files modified during this audit (audit-only)
-- [x] Implementation: agent-runtime suite 583 pass / 0 fail (incl. 2 new P1a regression tests), 4-way
-      typecheck (sdk/common/agent-runtime/cli), `bun x eslint . --max-warnings 0` exit 0, `bun run lint:md`
-      exit 0, Prettier clean on all changed files
-- [x] Implementation: independent AUDIT via code-reviewer (clean — no CRITICAL/HIGH/MEDIUM; skipped-capture
-      observability noted as accepted documented debt); CHANGELOG entry added; FID archived
-
-## Perfection Loop
-
-### Loop 1
-
-- **RED:** Completed 2026-08-03 — four-pass scan of `packages/agent-runtime/src`, `cli/src`,
-  `protocol.config.yaml`, and FID hygiene. Findings E1/P1a/P1b/C1/C2/C3/C4 catalogued with
-  file:line evidence above. All claims verified by direct code reads and greps; the `any`/`as`
-  inventory resolved clean except the cited cast (C2) and test-only casts (accepted convention).
-- **GREEN:** Sequential thinking over each finding (see Summary): E1 one-line config bump; P1a
-  errno-discriminating capture with a per-turn skip set (follows the `paths.ts` narrowing pattern);
-  P1b documented by-design; C1/C2 assertion/cast removal; C3 explicit definite-assignment guard
-  replacing the unsafe `!`; C4 in-scope `logger.debug`. Answers to the mandatory missed-question
-  check ("What questions should I have asked when this FID was created, but failed to?"):
-  1. *Is the checkpoint sync IO actually harmful?* — No: ordering invariant + dedup bounds it
-     (P1b). Not converting to async.
-  2. *Does the empty catch cause real damage?* — Yes, in the worst place: a failed read recorded as
-     `null` deletes an existing file on restore (P1a).
-  3. *Are the `!` assertions load-bearing?* — C1: no (non-nullable param). C3: yes, and it hides a
-     genuine `undefined` path → replace with a guard, not a silent removal.
-- **AUDIT:** Document-audit before implementation: C1/C2 removals are typecheck-verifiable (the
-  compiler is the arbiter — if the `!`/cast were needed, `bun run typecheck` fails); C3 guard is
-  reachable-verified against the module map and eval path; P1a fix cross-checked against the
-  existing checkpoint tests' semantics (first-capture-wins, null-deletes) and the `paths.ts`
-  narrowing idiom; C4 logging uses the existing contract. Call-graph evidence pasted in Verification.
-  Zero new functions or config fields introduced — the AUDIT grep requirement is satisfied by the
-  capture call-graph above.
-- **SELF-CORRECT:** Initial scan framed P1 as "sync IO on the spawn path (MEDIUM)". Reading
-  `checkpoint-store.ts` 0-EOF corrected this: the sync cost is bounded and correct (downgraded to
-  P1b INFO), while the real defect — the non-ENOENT catch-all — was found in the same lines
-  (elevated to P1a MEDIUM). C3's fix also evolved from "drop the `!`" to "explicit guard" once the
-  eval'd-generator path was confirmed.
-
-## Lessons Learned
-
-1. An empty `catch` in a safety-net subsystem is not "best-effort" — it is a silent misclassification
-   waiting to delete user files. Discriminate error codes (ENOENT vs the rest) even when the fallback
-   looks safe.
-2. Perf findings on hot paths deserve a 0-EOF read before severity is assigned: the same lines that
-   looked like a perf problem held the actual correctness bug.
-
-## Resolution
-
-- **Fixed By:** Savant (operator-approved implementation — FID presented for approval, approved, then
-  implemented)
-- **Fixed Date:** 2026-08-03
-- **Fix Description:** E1 — `protocol.config.yaml` project version `0.0.15` → `0.0.16`. P1a —
-  `checkpoint-store.ts` `captureSnapshot` now narrows the read error via the `paths.ts` idiom: `ENOENT`
-  records the delete-on-restore `null` marker; any other failure (EACCES/EISDIR/EMFILE) adds the path to a new
-  per-turn `skippedPaths` set (checked in the dedup gate, never serialized, never restored) so a rewind can
-  never delete an existing file that merely failed to read. P1b — sync IO documented as correct by design
-  (no change). C1 — three redundant `agentTemplate!` assertions removed in `run-agent-step.ts`. C2 —
-  `as string[]` cast dropped in `executeCustomToolCall` (`tool-executor.ts`); the native gate already used
-  the cast-free form. C3 — `generator!` replaced with an explicit definite-assignment guard in
-  `run-programmatic-step.ts` (throws a diagnosable error when an eval'd handleSteps function returns
-  undefined). C4 — `tool-stream-parser.ts` logs the tool-call input JSON.parse failure at debug level via the
-  in-scope `Logger` (`getErrorObject` payload), replacing the invisible `catch {}`.
-- **Tests Added:** `checkpoint-store.test.ts` +2 — (1) a non-ENOENT read failure (EISDIR directory path) is
-  never recorded as `null` and restore leaves the directory untouched; (2) a skipped path stays skipped for
-  the rest of the turn while normal files are still captured. C3 verified against existing suites (no test
-  asserted the old TypeError message — the `sandbox-generator` ReferenceError test is a different path).
-- **Verified By:** Savant — independent AUDIT via code-reviewer (clean — no CRITICAL/HIGH/MEDIUM; one LOW
-  note, skipped-capture observability, accepted as documented debt since the store deliberately has no
-  logger). Gate suite: agent-runtime 583 pass / 0 fail, 4-way typecheck (sdk/common/agent-runtime/cli) 0
-  errors, `bun x eslint . --max-warnings 0` exit 0, `bun run lint:md` exit 0, Prettier clean.
-- **Commit/PR:** None (working tree)
-- **Archived:** Yes