mini-coder 0.0.8 → 0.0.9

package/codex-lazy-fix.md

@@ -0,0 +1,76 @@
+# Codex Autonomy Issues & Fix Analysis
+
+## Behaviours
+When using `zen/gpt-5.3-codex` as the agent, the model consistently exhibits "lazy" or permission-seeking behaviour. Specifically:
+1. **Initial Compliance**: It starts by reading files or globbing the directory.
+2. **Immediate Stall**: Instead of executing edits or implementing the plan, it outputs a multi-paragraph text explaining what it *plans* to do and ends the turn.
+3. **Permission Seeking**: It explicitly asks the user for permission (e.g., "Reply **'proceed'** and I'll start implementing batch 1").
+4. **Ralph Mode Incompatibility**: In `/ralph` mode, the agent loops continuously. Because it restarts with a fresh context on each loop and stalls after gathering context, it never actually writes any files. It just loops through the same read-and-plan phase until it hits the max iteration limit.
+5. **Model Differences**: Both Claude and Gemini models do not exhibit this behaviour. They are not subjected to the same conversational RLHF that pushes the model to ask the user to double check its work.
+
+## Root Cause Analysis
+An analysis of both OpenAI's open-source `codex-rs` client and `opencode` source code reveals that Codex models (like `gpt-5.3-codex`) are highly RLHF-tuned for safety and collaborative pair-programming. By default, the model prefers to break tasks into chunks and explicitly ask for sign-off.
+
+To override this, the model requires three things which `mini-coder` was failing to provide correctly:
+
+### 1. Dual-Anchored System Prompts (`system` + `instructions`)
+`mini-coder` implemented a check `useInstructions` that placed the system prompt into the `instructions` field of the `/v1/responses` API payload. However, doing so stripped the `system` role message from the conversation context (`input` array).
+
+By looking at `opencode` and `codex-rs`, they both ensure that the context array *also* contains the system prompt:
+- `opencode` maps its environment variables and system instructions to `role: "system"` (or `role: "developer"`) inside `input.messages`, **while also** passing behavioral instructions to the `instructions` field in the API payload.
+- `codex-rs` directly injects `role: "developer"` into the message list (as seen in `codex-rs/core/src/compact.rs` and their memory tracing implementations).
+
+Without the `system` / `developer` message anchored at the start of the `input` array, the AI SDK and the model deprioritized the standalone `instructions` field, allowing the model's base permission-seeking behaviors to take over.
+
+### 2. Explicit "Do Not Ask" Directives
+Both `opencode` and `codex-rs` employ heavy anti-permission prompts.
+- **Opencode** (`session/prompt/codex_header.txt`):
+  > "- Default: do the work without asking questions... Never ask permission questions like 'Should I proceed?' or 'Do you want me to run tests?'; proceed with the most reasonable option and mention what you did."
+- **Codex-RS** (`core/templates/model_instructions/gpt-5.2-codex_instructions_template.md`):
+  > "Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you."
+
+`mini-coder` introduced `CODEX_AUTONOMY` in a previous commit, but because of Issue #1, it was never adequately anchored in the `input` array.
+
+## Evidence & Tests
+We introduced a fetch wrapper interceptor in `src/llm-api/providers.ts` that logs the full outbound API requests to `~/.config/mini-coder/api.log`. 
+
+A test script `test-turn.ts` running a dummy turn showed the exact payload generated by the AI SDK before our fix:
+```json
+    "body": {
+      "model": "gpt-5.3-codex",
+      "input": [
+        {
+          "role": "user",
+          "content": [
+            { "type": "input_text", "text": "hello" }
+          ]
+        }
+      ],
+      "store": false,
+      "instructions": "You are a test agent.",
+      ...
+```
+```json
+    "body": {
+      "model": "gpt-5.3-codex",
+      "input": [
+        {
+          "role": "developer",
+          "content": "You are mini-coder, a small and fast CLI coding agent... [CODEX_AUTONOMY directives]"
+        },
+        {
+          "role": "user",
+          "content": [
+            { "type": "input_text", "text": "hello" }
+          ]
+        }
+      ],
+      "instructions": "You are mini-coder, a small and fast CLI coding agent... [CODEX_AUTONOMY directives]"
+    }
+```
+This perfectly mirrors the behavior seen in `opencode` and `codex-rs`.
+
+## Actions Taken
+1. Added an `api.log` request interceptor in `providers.ts` to capture and inspect the exact JSON payloads sent to the OpenAI/AI SDK endpoints.
+2. Cloned and analyzed both `opencode` and `codex` repos to observe how they communicate with `gpt-5.*` codex endpoints.
+3. Updated `src/llm-api/turn.ts` so `system: systemPrompt` is *always* passed to the AI SDK, guaranteeing a `developer` message anchors the `input` array, even when `instructions` is also used.

package/dist/mc.js

@@ -94,7 +94,7 @@ function zenEndpointFor(modelId) {
   if (modelId.startsWith("claude-"))
     return zenAnthropic()(modelId);
   if (modelId.startsWith("gpt-"))
-    return zenOpenAI()(modelId);
+    return zenOpenAI().responses(modelId);
   if (modelId.startsWith("gemini-"))
     return zenGoogle()(modelId);
   return zenCompat()(modelId);
@@ -176,6 +176,15 @@ function directGoogle() {
   }
   return _directGoogle;
 }
+function parseModelString(modelString) {
+  const slashIdx = modelString.indexOf("/");
+  if (slashIdx === -1)
+    return { provider: modelString, modelId: "" };
+  return {
+    provider: modelString.slice(0, slashIdx),
+    modelId: modelString.slice(slashIdx + 1)
+  };
+}
 var CONTEXT_WINDOW_TABLE = [
   [/^claude-/, 200000],
   [/^gemini-/, 1e6],
@@ -187,7 +196,7 @@ var CONTEXT_WINDOW_TABLE = [
   [/^qwen3-/, 131000]
 ];
 function getContextWindow(modelString) {
-  const modelId = modelString.includes("/") ? modelString.slice(modelString.indexOf("/") + 1) : modelString;
+  const { modelId } = parseModelString(modelString);
   for (const [pattern, tokens] of CONTEXT_WINDOW_TABLE) {
     if (pattern.test(modelId))
       return tokens;
@@ -208,7 +217,7 @@ function resolveModel(modelString) {
     case "anthropic":
       return directAnthropic()(modelId);
     case "openai":
-      return directOpenAI()(modelId);
+      return modelId.startsWith("gpt-") ? directOpenAI().responses(modelId) : directOpenAI()(modelId);
     case "google":
       return directGoogle()(modelId);
     case "ollama": {
@@ -775,7 +784,7 @@ function renderChunk(text, inFence) {
 
 // src/cli/output.ts
 var HOME = homedir4();
-var PACKAGE_VERSION = "0.0.7";
+var PACKAGE_VERSION = "0.0.8";
 function tildePath(p) {
   return p.startsWith(HOME) ? `~${p.slice(HOME.length)}` : p;
 }
@@ -2401,30 +2410,51 @@ var MAX_STEPS = 50;
 function isZodSchema(s) {
   return s !== null && typeof s === "object" && "_def" in s;
 }
-function toCoreTool(def) {
+function toCoreTool(def, claimWarning) {
   const schema = isZodSchema(def.schema) ? def.schema : jsonSchema(def.schema);
   return dynamicTool({
     description: def.description,
     inputSchema: schema,
     execute: async (input) => {
       try {
-        return await def.execute(input);
+        const result = await def.execute(input);
+        if (claimWarning()) {
+          const warning = `
+
+<system-message>You have reached the maximum number of tool calls. ` + "No more tools will be available after this result. " + "Respond with a status update and list what still needs to be done.</system-message>";
+          const str = typeof result === "string" ? result : JSON.stringify(result);
+          return str + warning;
+        }
+        return result;
       } catch (err) {
         throw err instanceof Error ? err : new Error(String(err));
       }
     }
   });
 }
+function isOpenAIGPT(modelString) {
+  const { provider, modelId } = parseModelString(modelString);
+  return (provider === "openai" || provider === "zen") && modelId.startsWith("gpt-");
+}
 async function* runTurn(options) {
-  const { model, messages, tools, systemPrompt, signal } = options;
+  const { model, modelString, messages, tools, systemPrompt, signal } = options;
+  let stepCount = 0;
+  let warningClaimed = false;
+  function claimWarning() {
+    if (stepCount !== MAX_STEPS - 2 || warningClaimed)
+      return false;
+    warningClaimed = true;
+    return true;
+  }
   const toolSet = {};
   for (const def of tools) {
-    toolSet[def.name] = toCoreTool(def);
+    toolSet[def.name] = toCoreTool(def, claimWarning);
   }
   let inputTokens = 0;
   let outputTokens = 0;
   let contextTokens = 0;
   try {
+    const useInstructions = systemPrompt !== undefined && isOpenAIGPT(modelString);
     const streamOpts = {
       model,
       messages,
@@ -2434,8 +2464,24 @@ async function* runTurn(options) {
         inputTokens += step.usage?.inputTokens ?? 0;
         outputTokens += step.usage?.outputTokens ?? 0;
         contextTokens = step.usage?.inputTokens ?? contextTokens;
+        stepCount++;
+        warningClaimed = false;
       },
-      ...systemPrompt ? { system: systemPrompt } : {},
+      prepareStep: ({ stepNumber }) => {
+        if (stepNumber >= MAX_STEPS - 1) {
+          return { activeTools: [] };
+        }
+        return;
+      },
+      ...systemPrompt && !useInstructions ? { system: systemPrompt } : {},
+      ...useInstructions ? {
+        providerOptions: {
+          openai: {
+            instructions: systemPrompt,
+            store: false
+          }
+        }
+      } : {},
       ...signal ? { abortSignal: signal } : {}
     };
     const result = streamText(streamOpts);
@@ -3694,7 +3740,19 @@ function loadContextFile(cwd) {
   }
   return null;
 }
-function buildSystemPrompt(cwd) {
+var CODEX_AUTONOMY = `
+# Autonomy and persistence
+- You are an autonomous senior engineer. Once given a direction, proactively gather context, implement, test, and refine without waiting for additional prompts at each step.
+- Persist until the task is fully handled end-to-end within the current turn: do not stop at analysis or partial work; carry changes through to implementation and verification.
+- Bias to action: default to implementing with reasonable assumptions. Do not end your turn with clarifications or requests to "proceed" unless you are truly blocked on information only the user can provide.
+- Do NOT output an upfront plan, preamble, or status update before working. Start making tool calls immediately.
+- Do NOT ask "shall I proceed?", "shall I start?", "reply X to continue", or any equivalent. Just start.
+- If something is ambiguous, pick the most reasonable interpretation, implement it, and note the assumption at the end.`;
+function isCodexModel(modelString) {
+  const { modelId } = parseModelString(modelString);
+  return modelId.includes("codex");
+}
+function buildSystemPrompt(cwd, modelString) {
   const contextFile = loadContextFile(cwd);
   const cwdDisplay = tildePath(cwd);
   const now = new Date().toLocaleString(undefined, { hour12: false });
@@ -3709,8 +3767,10 @@ Guidelines:
 - Prefer small, targeted edits over large rewrites.
 - Always read a file before editing it.
 - Use glob to discover files, grep to find patterns, read to inspect contents.
-- Use shell for tests, builds, and git operations.
-- When in doubt, ask the user before making destructive changes.`;
+- Use shell for tests, builds, and git operations.`;
+  if (modelString && isCodexModel(modelString)) {
+    prompt += CODEX_AUTONOMY;
+  }
   if (contextFile) {
     prompt += `
 
@@ -3769,7 +3829,7 @@ async function runAgent(opts) {
       throw new Error(`Unknown agent "${agentName}". Available agents: ${[...allAgents.keys()].join(", ") || "(none)"}`);
     }
     const model = modelOverride ?? agentConfig?.model ?? currentModel;
-    const systemPrompt = agentConfig?.systemPrompt ?? buildSystemPrompt(cwd);
+    const systemPrompt = agentConfig?.systemPrompt ?? buildSystemPrompt(cwd, model);
     const subMessages = [{ role: "user", content: prompt }];
     const laneId = nextLaneId++;
     activeLanes.add(laneId);
@@ -3788,6 +3848,7 @@ async function runAgent(opts) {
     let outputTokens = 0;
     const events = runTurn({
       model: subLlm,
+      modelString: model,
       messages: subMessages,
       tools: subTools,
       systemPrompt
@@ -4003,7 +4064,7 @@ ${out}
 
 <system-message>PLAN MODE ACTIVE: Help the user gather context for the plan -- READ ONLY</system-message>` : ralphMode ? `${resolvedText}
 
-<system-message>RALPH MODE: You are in an autonomous loop. When the task is fully complete (all tests pass, no outstanding issues), output exactly \`/ralph\` as your final message to exit the loop. Otherwise, keep working.</system-message>` : resolvedText;
+<system-message>RALPH MODE: You are in an autonomous loop. You MUST make actual file changes (create, edit, or write files) to complete the requested task before outputting \`/ralph\`. Reading files, running tests, or exploring the codebase does NOT count as doing the work. Only output \`/ralph\` as your final message after all requested changes are implemented and tests pass.</system-message>` : resolvedText;
     const userMsg = allImages.length > 0 ? {
       role: "user",
       content: [
@@ -4017,10 +4078,7 @@ ${out}
     } : { role: "user", content: coreContent };
     if (wasAborted) {
       stopWatcher();
-      const stubMsg = {
-        role: "assistant",
-        content: "[interrupted]"
-      };
+      const stubMsg = makeInterruptMessage("user");
       session.messages.push(userMsg, stubMsg);
       saveMessages(session.id, [userMsg, stubMsg], thisTurn);
       coreHistory.push(userMsg, stubMsg);
@@ -4032,26 +4090,15 @@ ${out}
     saveMessages(session.id, [userMsg], thisTurn);
     coreHistory.push(userMsg);
     const llm = resolveModel(currentModel);
-    const systemPrompt = buildSystemPrompt(cwd);
+    const systemPrompt = buildSystemPrompt(cwd, currentModel);
     let lastAssistantText = "";
-    let turnRolledBack = false;
-    const rollbackTurn = () => {
-      if (turnRolledBack)
-        return;
-      turnRolledBack = true;
-      coreHistory.pop();
-      session.messages.pop();
-      deleteLastTurn(session.id, thisTurn);
-      if (snapped)
-        deleteSnapshot(session.id, thisTurn);
-      snapshotStack.pop();
-      turnIndex--;
-    };
+    let errorStubSaved = false;
     try {
       snapshotStack.push(snapped ? thisTurn : null);
       spinner.start("thinking");
       const events = runTurn({
         model: llm,
+        modelString: currentModel,
         messages: coreHistory,
         tools: planMode ? [...buildReadOnlyToolSet({ cwd }), ...mcpTools] : tools,
         systemPrompt,
@@ -4062,16 +4109,17 @@ ${out}
         coreHistory.push(...newMessages);
         session.messages.push(...newMessages);
         saveMessages(session.id, newMessages, thisTurn);
-      } else if (wasAborted) {
-        const stubMsg = {
-          role: "assistant",
-          content: "[interrupted]"
-        };
+        if (wasAborted) {
+          const note = makeInterruptMessage("user");
+          coreHistory.push(note);
+          session.messages.push(note);
+          saveMessages(session.id, [note], thisTurn);
+        }
+      } else {
+        const stubMsg = makeInterruptMessage("user");
         coreHistory.push(stubMsg);
         session.messages.push(stubMsg);
         saveMessages(session.id, [stubMsg], thisTurn);
-      } else {
-        rollbackTurn();
       }
       lastAssistantText = extractAssistantText(newMessages);
       totalIn += inputTokens;
@@ -4079,7 +4127,13 @@ ${out}
       lastContextTokens = contextTokens;
       touchActiveSession(session);
     } catch (err) {
-      rollbackTurn();
+      if (!errorStubSaved) {
+        errorStubSaved = true;
+        const stubMsg = makeInterruptMessage("error");
+        coreHistory.push(stubMsg);
+        session.messages.push(stubMsg);
+        saveMessages(session.id, [stubMsg], thisTurn);
+      }
       throw err;
     } finally {
       stopWatcher();
@@ -4107,6 +4161,10 @@ ${out}
     });
   }
 }
+function makeInterruptMessage(reason) {
+  const text = reason === "user" ? "<system-message>Response was interrupted by the user.</system-message>" : "<system-message>Response was interrupted due to an error.</system-message>";
+  return { role: "assistant", content: text };
+}
 function extractAssistantText(newMessages) {
   const parts = [];
   for (const msg of newMessages) {

package/hanging-bug.md

@@ -0,0 +1,78 @@
+# Hanging Bug Investigation
+
+## Symptoms
+
+After a shell tool call completes successfully, **SOMETIMES** the app hangs indefinitely instead of
+returning to the prompt. Two observed states:
+
+```
+  $ $ rm src/session/db.ts && bun run test
+⠇ shell
+```
+
+Stayed spinning with shell label for well over the timeout time. I had to kill the app.
+
+Another example with a different shell command:
+```
+  $ $ git diff
+    ✔ 0
+    │ diff --git a/src/cli/tool-render.ts b/src/cli/tool-render.ts
+    │ index f8d33af..e224932 100644
+    │ --- a/src/cli/tool-render.ts
+    │ +++ b/src/cli/tool-render.ts
+    │ @@ -148,21 +148,25 @@ export function renderToolResultInline(
+    │   }
+    │
+    │   if (toolName === "glob") {
+    │ -         const r = result as { files: string[]; truncated: boolean };
+    │ -         const n = r.files.length;
+    │ -         writeln(
+    │ -                 `${indent}${G.info} ${c.dim(n === 0 ? "no matches" : `${n} file${n === 1 ? "" : "s"}${r.truncated ? " (capped)" : ""}`)}`,
+    │ -         );
+    │ -         return;
+    │ +         const r = result as { files?: string[]; truncated?: boolean };
+    │ +         if (Array.isArray(r.files)) {
+    │ +                 const n = r.files.length;
+    │ +                 writeln(
+    │ +                         `${indent}${G.info} ${c.dim(n === 0 ? "no matches" : `${n} file${n === 1 ? "" : "s"}${r.truncated ? " (capped)" : ""}`)}`,
+    │ +                 );
+    │ … +150 lines
+⠦ thinking
+```
+User also had to kill the app.
+
+Only seen with Gemini/Google models.
+Only happens after shell tool calls.
+Other tools calls worked just fine during the same session with the same model and mini-coder version.
+There are no shell tool related hooks configured anywhere.
+
+The expectation was the turn to continue as normal since the tool calls succeded.
+
+Find the root cause, show proof.
+
+## Findings:
+
+Here is the concrete proof I just ran, no edits:
+- I executed renderTurn with an event stream that does:
+  1) tool-call-start(shell)
+  2) tool-result(shell success)
+  3) then never yields again
+- Result: the promise did not resolve within 700ms (timed_out_700ms).
+Then I ran the same sequence but added turn-complete:
+- Result: it resolved immediately (resolved).
+So this is now proven in your codepath:
+- renderTurn waits forever when the upstream async stream goes silent after a shell tool result.
+- This exactly matches the visible hang states.
+
+### Root Cause 1: Hangs spinning on `"shell"`
+**Proof in code:** `src/tools/shell.ts`
+*   When a command times out, `proc.kill("SIGTERM")` only kills the parent process (e.g., `bash`). Any child processes (e.g., `bun`) become orphaned but stay alive, holding the write end of the `stdout`/`stderr` pipes open. 
+*   Because the pipe never closes, `await reader.read()` inside `collectStream()` hangs indefinitely. 
+*   Because `collectStream()` never resolves, the tool execution never finishes, `tool-result` is never yielded, and the stream goes completely silent while the spinner stays stuck on "shell".
+
+### Root Cause 2: Hangs spinning on `"thinking"`
+**Proof in code:** `src/llm-api/turn.ts`
+*   After `git diff` completes, the tool resolves and `renderTurn` switches the spinner to `"thinking"`.
+*   The AI SDK automatically makes a new HTTP request to the Gemini API containing the tool result to generate the next step.
+*   Gemini's API occasionally hangs indefinitely or silently drops connections when receiving certain payloads (like large tool outputs or ANSI color codes, which `git diff` outputs).
+*   Because there is no timeout configured on the `streamText` call in `runTurn` (unless the user manually aborts), the underlying fetch request waits forever. The `result.fullStream` never yields the next chunk, but also never closes or errors.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.8",
+	"version": "0.0.9",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",

package/plan-code-health.md

@@ -0,0 +1,169 @@
+# Code Health Remediation Plan
+
+## Goal
+Address maintainability and reliability issues identified in `code-health.md` with low-risk, incremental refactors that keep behavior stable.
+
+## Constraints
+- Keep `mini-coder-idea.md` and `README.md` unchanged.
+- Prefer small PR-sized changes with passing tests after each step.
+- Preserve current CLI behavior while improving structure.
+
+## Workstreams
+
+### 1) Decompose `src/agent/agent.ts` (High)
+**Outcome:** `runAgent` remains orchestration entrypoint; responsibilities split into focused modules.
+
+**Steps:**
+1. Add `src/agent/reporter.ts` interface (narrow surface for output/status/tool events).
+2. Extract session lifecycle + turn loop into `src/agent/session-runner.ts`.
+3. Extract subagent execution into `src/agent/subagent-runner.ts`.
+4. Extract snapshot/undo helpers into `src/agent/undo-snapshot.ts`.
+5. Extract user input processing into `src/agent/input-loop.ts`.
+6. Keep `agent.ts` as composition/wiring file only.
+
+**Checks:**
+- Add/adjust unit tests around orchestration boundaries.
+- Ensure no behavior regressions in interrupts, resume, and tool-call flows.
+
+---
+
+### 2) Decompose `src/cli/output.ts` (High)
+**Outcome:** Rendering responsibilities isolated and testable.
+
+**Target modules:**
+- `src/cli/spinner.ts`
+- `src/cli/tool-render.ts`
+- `src/cli/stream-render.ts`
+- `src/cli/status-bar.ts`
+- `src/cli/error-render.ts`
+- `src/cli/output.ts` as facade
+
+**Steps:**
+1. Extract pure formatting helpers first (no IO).
+2. Extract spinner lifecycle module.
+3. Extract stream queue/tick/flush behavior.
+4. Keep compatibility exports in `output.ts` to avoid broad callsite churn.
+
+**Checks:**
+- Add focused tests for formatting + stream behavior.
+- Verify terminal rendering remains stable manually.
+
+---
+
+### 3) Introduce `TerminalIO` abstraction (Medium)
+**Outcome:** Centralized process/TTY interactions and signal lifecycle.
+
+**Steps:**
+1. Create `src/cli/terminal-io.ts` with methods for stdout/stderr writes, raw mode, signal subscriptions.
+2. Replace direct `process.*` use in output/input stack with injected `TerminalIO`.
+3. Centralize signal registration/unregistration in one lifecycle owner.
+
+**Checks:**
+- Add unit tests for signal registration cleanup semantics.
+- Confirm no stuck raw-mode edge cases.
+
+---
+
+### 4) Split DB layer by domain (Medium)
+**Outcome:** Reduced blast radius and clearer data ownership.
+
+**Target modules:**
+- `src/session/db/connection.ts`
+- `src/session/db/session-repo.ts`
+- `src/session/db/message-repo.ts`
+- `src/session/db/settings-repo.ts`
+- `src/session/db/mcp-repo.ts`
+- `src/session/db/snapshot-repo.ts`
+- `src/session/db/index.ts` (facade exports)
+
+**Steps:**
+1. Move code without behavior changes.
+2. Keep SQL and schema unchanged initially.
+3. Replace direct `JSON.parse` in message loading with guarded parser:
+   - skip malformed rows
+   - emit diagnostic via logger/reporter
+
+**Checks:**
+- Add tests for malformed payload handling.
+- Validate existing DB tests still pass.
+
+---
+
+### 5) Shared markdown config loader (Medium)
+**Outcome:** Remove duplication across agents/skills/custom-commands.
+
+**Steps:**
+1. Create `src/cli/load-markdown-configs.ts` with parameterized layout strategy.
+2. Migrate:
+   - `src/cli/agents.ts`
+   - `src/cli/skills.ts`
+   - `src/cli/custom-commands.ts`
+3. Keep precedence rules identical (built-in/user/project).
+4. Preserve existing frontmatter semantics.
+
+**Checks:**
+- Reuse/expand existing loader tests to cover parity.
+
+---
+
+### 6) Runtime/UI decoupling via reporter boundary (Medium)
+**Outcome:** Core runtime no longer depends directly on terminal rendering.
+
+**Steps:**
+1. Define domain events or reporter interface in `src/agent/reporter.ts`.
+2. Implement CLI reporter adapter in `src/cli/output-reporter.ts`.
+3. Replace direct output calls in agent runtime with reporter calls.
+
+**Checks:**
+- Add tests using test reporter to assert emitted events.
+
+---
+
+### 7) Error observability and silent catches (Medium)
+**Outcome:** Non-fatal failures become diagnosable without crashing.
+
+**Steps:**
+1. Find empty/broad catches in agent/output/loaders.
+2. Add debug-level diagnostics with contextual metadata.
+3. Keep user-facing behavior unchanged unless critical.
+
+**Checks:**
+- Validate noisy paths are still quiet at normal verbosity.
+
+---
+
+### 8) Startup FS sync usage (Low/Deferred)
+**Outcome:** Optional responsiveness improvement if startup cost grows.
+
+**Steps:**
+1. Measure startup and config-loading time first.
+2. If needed, move high-volume file scanning to async or cache results with invalidation.
+
+---
+
+### 9) Test hygiene cleanup (Low)
+**Outcome:** Cleaner CI output.
+
+**Steps:**
+1. Remove `console.log` skip notices in `src/tools/shell.test.ts`.
+2. Use test-framework-native skip annotations/helpers.
+
+---
+
+## Execution Order (recommended)
+1. Reporter interface (foundation for later decoupling).
+2. `agent.ts` decomposition.
+3. `output.ts` decomposition.
+4. Shared config loader extraction.
+5. DB module split + safe JSON parsing.
+6. TerminalIO + centralized signals.
+7. Silent catch diagnostics.
+8. Test hygiene and any deferred FS optimization.
+
+## Definition of Done
+- `bun run typecheck && bun run format && bun run lint && bun test` passes.
+- No behavior regressions in interactive CLI flows.
+- `agent.ts` and `output.ts` materially reduced in size/responsibility.
+- Config loader duplication removed.
+- Message loading resilient to malformed JSON rows.
+- New abstractions documented in code comments where non-obvious.