mini-coder 0.0.10 → 0.0.12

package/dist/mc.js

@@ -23,7 +23,10 @@ import * as c7 from "yoctocolors";
 class TerminalIO {
   cleanupHandlers = new Set;
   rawModeEnabled = false;
-  abortController = new AbortController;
+  interruptHandler = null;
+  setInterruptHandler(handler) {
+    this.interruptHandler = handler;
+  }
   stdoutWrite(text) {
     process.stdout.write(text);
   }
@@ -58,8 +61,12 @@ class TerminalIO {
       process.exit(143);
     });
     process.on("SIGINT", () => {
-      cleanup();
-      process.exit(130);
+      if (this.interruptHandler) {
+        this.interruptHandler();
+      } else {
+        cleanup();
+        process.exit(130);
+      }
     });
     process.on("uncaughtException", (err) => {
       cleanup();
@@ -924,6 +931,8 @@ function fmtTokens(n) {
 function renderStatusBar(opts) {
   const cols = process.stdout.columns ?? 80;
   const left = [c5.cyan(opts.model)];
+  if (opts.thinkingEffort)
+    left.push(c5.dim(`\u2726 ${opts.thinkingEffort}`));
   if (opts.provider && opts.provider !== "zen")
     left.push(c5.dim(opts.provider));
   left.push(c5.dim(opts.sessionId.slice(0, 8)));
@@ -969,7 +978,7 @@ function renderError(err, context = "render") {
 
 // src/cli/output.ts
 var HOME2 = homedir3();
-var PACKAGE_VERSION = "0.0.10";
+var PACKAGE_VERSION = "0.0.12";
 function tildePath(p) {
   return p.startsWith(HOME2) ? `~${p.slice(HOME2.length)}` : p;
 }
@@ -1340,6 +1349,87 @@ var CONTEXT_WINDOW_TABLE = [
   [/^glm-/, 128000],
   [/^qwen3-/, 131000]
 ];
+var REASONING_MODELS = [
+  /^claude-3-5-sonnet/,
+  /^claude-3-7/,
+  /^claude-sonnet-4/,
+  /^claude-opus-4/,
+  /^o1/,
+  /^o3/,
+  /^o4/,
+  /^gpt-5/,
+  /^gemini-2\.5/,
+  /^gemini-3/
+];
+function supportsThinking(modelString) {
+  const { modelId } = parseModelString(modelString);
+  return REASONING_MODELS.some((p) => p.test(modelId));
+}
+var ANTHROPIC_BUDGET = {
+  low: 4096,
+  medium: 8192,
+  high: 16384,
+  xhigh: 32768
+};
+function clampEffort(effort, max) {
+  const ORDER = ["low", "medium", "high", "xhigh"];
+  const i = ORDER.indexOf(effort);
+  const m = ORDER.indexOf(max);
+  return ORDER[Math.min(i, m)];
+}
+function getThinkingProviderOptions(modelString, effort) {
+  if (!supportsThinking(modelString))
+    return null;
+  const { provider, modelId } = parseModelString(modelString);
+  if (provider === "anthropic" || provider === "zen" && modelId.startsWith("claude-")) {
+    const isAdaptive = /^claude-3-7/.test(modelId) || /^claude-sonnet-4/.test(modelId) || /^claude-opus-4/.test(modelId);
+    if (isAdaptive) {
+      const isOpus = /^claude-opus-4/.test(modelId);
+      const mapped = effort === "xhigh" ? isOpus ? "max" : "high" : effort;
+      return { anthropic: { thinking: { type: "adaptive" }, effort: mapped } };
+    }
+    const budget = ANTHROPIC_BUDGET[effort];
+    return {
+      anthropic: {
+        thinking: { type: "enabled", budgetTokens: budget },
+        betas: ["interleaved-thinking-2025-05-14"]
+      }
+    };
+  }
+  if (provider === "openai" || provider === "zen" && (modelId.startsWith("o") || modelId.startsWith("gpt-5"))) {
+    const supportsXhigh = /^gpt-5\.[2-9]/.test(modelId) || /^o4/.test(modelId);
+    const clamped = supportsXhigh ? effort : clampEffort(effort, "high");
+    return { openai: { reasoningEffort: clamped } };
+  }
+  if (provider === "google" || provider === "zen" && modelId.startsWith("gemini-")) {
+    if (/^gemini-3/.test(modelId)) {
+      const level = clampEffort(effort, "high");
+      return {
+        google: {
+          thinkingConfig: {
+            includeThoughts: true,
+            thinkingLevel: level
+          }
+        }
+      };
+    }
+    const GEMINI_BUDGET = {
+      low: 4096,
+      medium: 8192,
+      high: 16384,
+      xhigh: 24575
+    };
+    return {
+      google: {
+        thinkingConfig: {
+          includeThoughts: true,
+          thinkingBudget: GEMINI_BUDGET[effort]
+        }
+      }
+    };
+  }
+  return null;
+}
 function getContextWindow(modelString) {
   const { modelId } = parseModelString(modelString);
   for (const [pattern, tokens] of CONTEXT_WINDOW_TABLE) {
@@ -1691,6 +1781,19 @@ function getPreferredModel() {
 function setPreferredModel(model) {
   setSetting("preferred_model", model);
 }
+function getPreferredThinkingEffort() {
+  const v = getSetting("preferred_thinking_effort");
+  if (v === "low" || v === "medium" || v === "high" || v === "xhigh")
+    return v;
+  return null;
+}
+function setPreferredThinkingEffort(effort) {
+  if (effort === null) {
+    getDb().run("DELETE FROM settings WHERE key = 'preferred_thinking_effort'");
+  } else {
+    setSetting("preferred_thinking_effort", effort);
+  }
+}
 // src/session/db/mcp-repo.ts
 function listMcpServers() {
   return getDb().query("SELECT name, transport, url, command, args, env FROM mcp_servers ORDER BY name").all();
@@ -1779,7 +1882,15 @@ function isOpenAIGPT(modelString) {
   return (provider === "openai" || provider === "zen") && modelId.startsWith("gpt-");
 }
 async function* runTurn(options) {
-  const { model, modelString, messages, tools, systemPrompt, signal } = options;
+  const {
+    model,
+    modelString,
+    messages,
+    tools,
+    systemPrompt,
+    signal,
+    thinkingEffort
+  } = options;
   let stepCount = 0;
   let warningClaimed = false;
   function claimWarning() {
@@ -1798,6 +1909,18 @@ async function* runTurn(options) {
   try {
     const useInstructions = systemPrompt !== undefined && isOpenAIGPT(modelString);
     logApiEvent("turn start", { modelString, messageCount: messages.length });
+    const thinkingOpts = thinkingEffort ? getThinkingProviderOptions(modelString, thinkingEffort) : null;
+    const mergedProviderOptions = {
+      ...useInstructions ? { openai: { instructions: systemPrompt, store: false } } : {},
+      ...thinkingOpts ?? {},
+      ...useInstructions && thinkingOpts?.openai ? {
+        openai: {
+          instructions: systemPrompt,
+          store: false,
+          ...thinkingOpts.openai
+        }
+      } : {}
+    };
     const streamOpts = {
       model,
       messages,
@@ -1822,14 +1945,7 @@ async function* runTurn(options) {
         return;
       },
       ...systemPrompt ? { system: systemPrompt } : {},
-      ...useInstructions ? {
-        providerOptions: {
-          openai: {
-            instructions: systemPrompt,
-            store: false
-          }
-        }
-      } : {},
+      ...Object.keys(mergedProviderOptions).length > 0 ? { providerOptions: mergedProviderOptions } : {},
       ...signal ? { abortSignal: signal } : {}
     };
     const result = streamText(streamOpts);
@@ -2792,7 +2908,7 @@ function createSubagentTool(runSubagent, availableAgents, parentLabel) {
 When the user's message contains @<agent-name>, delegate to that agent by setting agentName to the exact agent name. Available custom agents: ${[...availableAgents.entries()].map(([name, cfg]) => `"${name}" (${cfg.description})`).join(", ")}.` : "";
   return {
     name: "subagent",
-    description: `Spawn a sub-agent to handle a focused subtask. Use this for parallel exploration, specialised analysis, or tasks that benefit from a fresh context window. The subagent has access to all the same tools.${agentSection}`,
+    description: `Spawn a sub-agent to handle a focused subtask. Use this for parallel exploration, specialised analysis, or tasks that benefit from a fresh context window. ${agentSection}`,
     schema: SubagentInput,
     execute: async (input) => {
       return runSubagent(input.prompt, input.agentName, parentLabel);
@@ -2878,7 +2994,7 @@ function buildReadOnlyToolSet(opts) {
 }
 
 // src/agent/subagent-runner.ts
-function createSubagentRunner(cwd, reporter, getCurrentModel) {
+function createSubagentRunner(cwd, reporter, getCurrentModel, getThinkingEffort) {
   let nextLaneId = 1;
   const activeLanes = new Set;
   const runSubagent = async (prompt, depth = 0, agentName, modelOverride, parentLabel) => {
@@ -2901,17 +3017,19 @@ function createSubagentRunner(cwd, reporter, getCurrentModel) {
       onHook: (tool, path, ok) => reporter.renderHook(tool, path, ok),
       availableAgents: allAgents,
       parentLabel: laneLabel
-    });
+    }).filter((tool) => tool.name !== "subagent");
     const subLlm = resolveModel(model);
     let result = "";
     let inputTokens = 0;
     let outputTokens = 0;
+    const effort = getThinkingEffort();
     const events = runTurn({
       model: subLlm,
       modelString: model,
       messages: subMessages,
       tools: subTools,
-      systemPrompt
+      systemPrompt,
+      ...effort ? { thinkingEffort: effort } : {}
     });
     for await (const event of events) {
       reporter.stopSpinner();
@@ -3368,20 +3486,50 @@ async function expandTemplate(template, args, cwd) {
 
 // src/cli/commands.ts
 async function handleModel(ctx, args) {
-  if (args) {
-    let modelId = args;
-    if (!args.includes("/")) {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  if (parts.length > 0) {
+    if (parts[0] === "effort") {
+      const effortArg2 = parts[1] ?? "";
+      if (effortArg2 === "off") {
+        ctx.setThinkingEffort(null);
+        writeln(`${PREFIX.success} thinking effort disabled`);
+      } else if (["low", "medium", "high", "xhigh"].includes(effortArg2)) {
+        ctx.setThinkingEffort(effortArg2);
+        writeln(`${PREFIX.success} thinking effort \u2192 ${c10.cyan(effortArg2)}`);
+      } else {
+        writeln(`${PREFIX.error} usage: /model effort <low|medium|high|xhigh|off>`);
+      }
+      return;
+    }
+    const idArg = parts[0] ?? "";
+    let modelId = idArg;
+    if (!idArg.includes("/")) {
       const models2 = await fetchAvailableModels();
-      const match = models2.find((m) => m.id.split("/").slice(1).join("/") === args || m.id === args);
+      const match = models2.find((m) => m.id.split("/").slice(1).join("/") === idArg || m.id === idArg);
       if (match) {
         modelId = match.id;
       } else {
-        writeln(`${PREFIX.error} unknown model ${c10.cyan(args)}  ${c10.dim("\u2014 run /models for the full list")}`);
+        writeln(`${PREFIX.error} unknown model ${c10.cyan(idArg)}  ${c10.dim("\u2014 run /models for the full list")}`);
         return;
       }
     }
     ctx.setModel(modelId);
-    writeln(`${PREFIX.success} model \u2192 ${c10.cyan(modelId)}`);
+    const effortArg = parts[1];
+    if (effortArg) {
+      if (effortArg === "off") {
+        ctx.setThinkingEffort(null);
+        writeln(`${PREFIX.success} model \u2192 ${c10.cyan(modelId)} ${c10.dim("(thinking disabled)")}`);
+      } else if (["low", "medium", "high", "xhigh"].includes(effortArg)) {
+        ctx.setThinkingEffort(effortArg);
+        writeln(`${PREFIX.success} model \u2192 ${c10.cyan(modelId)} ${c10.dim(`(\u2726 ${effortArg})`)}`);
+      } else {
+        writeln(`${PREFIX.success} model \u2192 ${c10.cyan(modelId)}`);
+        writeln(`${PREFIX.error} unknown effort level ${c10.cyan(effortArg)} (use low, medium, high, xhigh, off)`);
+      }
+    } else {
+      const e = ctx.thinkingEffort ? c10.dim(` (\u2726 ${ctx.thinkingEffort})`) : "";
+      writeln(`${PREFIX.success} model \u2192 ${c10.cyan(modelId)}${e}`);
+    }
     return;
   }
   writeln(`${c10.dim("  fetching models\u2026")}`);
@@ -3408,13 +3556,15 @@ async function handleModel(ctx, args) {
       const isCurrent = ctx.currentModel === m.id;
       const freeTag = m.free ? c10.green(" free") : "";
       const ctxTag = m.context ? c10.dim(` ${Math.round(m.context / 1000)}k`) : "";
+      const effortTag = isCurrent && ctx.thinkingEffort ? c10.dim(` \u2726 ${ctx.thinkingEffort}`) : "";
       const cur = isCurrent ? c10.cyan(" \u25C0") : "";
-      writeln(`    ${c10.dim("\xB7")} ${m.displayName}${freeTag}${ctxTag}${cur}`);
+      writeln(`    ${c10.dim("\xB7")} ${m.displayName}${freeTag}${ctxTag}${cur}${effortTag}`);
       writeln(`      ${c10.dim(m.id)}`);
     }
   }
   writeln();
   writeln(c10.dim("  /model <id>  to switch  \xB7  e.g. /model zen/claude-sonnet-4-6"));
+  writeln(c10.dim("  /model effort <low|medium|high|xhigh|off>  to set thinking effort"));
 }
 function handlePlan(ctx) {
   ctx.setPlanMode(!ctx.planMode);
@@ -3803,20 +3953,25 @@ async function readKey(reader) {
 function watchForInterrupt(abortController) {
   if (!process.stdin.isTTY)
     return () => {};
+  const onInterrupt = () => {
+    cleanup();
+    abortController.abort();
+  };
   const onData = (chunk) => {
     for (const byte of chunk) {
       if (byte === 3) {
-        cleanup();
-        abortController.abort();
+        onInterrupt();
         return;
       }
     }
   };
   const cleanup = () => {
     process.stdin.removeListener("data", onData);
+    terminal.setInterruptHandler(null);
     process.stdin.setRawMode(false);
     process.stdin.pause();
   };
+  terminal.setInterruptHandler(onInterrupt);
   process.stdin.setRawMode(true);
   process.stdin.resume();
   process.stdin.on("data", onData);
@@ -4276,6 +4431,7 @@ class SessionRunner {
   tools;
   mcpTools;
   currentModel;
+  currentThinkingEffort;
   session;
   coreHistory;
   turnIndex = 1;
@@ -4291,6 +4447,7 @@ class SessionRunner {
     this.tools = opts.tools;
     this.mcpTools = opts.mcpTools;
     this.currentModel = opts.initialModel;
+    this.currentThinkingEffort = opts.initialThinkingEffort;
     this.initSession(opts.sessionId);
   }
   initSession(sessionId) {
@@ -4373,7 +4530,8 @@ class SessionRunner {
         messages: this.coreHistory,
         tools: this.planMode ? [...buildReadOnlyToolSet({ cwd: this.cwd }), ...this.mcpTools] : this.tools,
         systemPrompt,
-        signal: abortController.signal
+        signal: abortController.signal,
+        ...this.currentThinkingEffort ? { thinkingEffort: this.currentThinkingEffort } : {}
       });
       const { inputTokens, outputTokens, contextTokens, newMessages } = await this.reporter.renderTurn(events);
       if (newMessages.length > 0) {
@@ -4419,7 +4577,8 @@ class SessionRunner {
 async function runAgent(opts) {
   const cwd = opts.cwd;
   let currentModel = opts.model;
-  const runSubagent = createSubagentRunner(cwd, opts.reporter, () => currentModel);
+  let currentThinkingEffort = opts.initialThinkingEffort;
+  const runSubagent = createSubagentRunner(cwd, opts.reporter, () => currentModel, () => currentThinkingEffort);
   const agents = loadAgents(cwd);
   const tools = buildToolSet({
     cwd,
@@ -4460,6 +4619,7 @@ async function runAgent(opts) {
     tools,
     mcpTools,
     initialModel: currentModel,
+    initialThinkingEffort: opts.initialThinkingEffort,
     sessionId: opts.sessionId
   });
   const cmdCtx = {
@@ -4472,6 +4632,14 @@ async function runAgent(opts) {
       setPreferredModel(m);
       currentModel = m;
     },
+    get thinkingEffort() {
+      return runner.currentThinkingEffort;
+    },
+    setThinkingEffort: (e) => {
+      runner.currentThinkingEffort = e;
+      setPreferredThinkingEffort(e);
+      currentThinkingEffort = e;
+    },
     get planMode() {
       return runner.planMode;
     },
@@ -4515,7 +4683,8 @@ async function runAgent(opts) {
       outputTokens: runner.totalOut,
       contextTokens: runner.lastContextTokens,
       contextWindow: getContextWindow(runner.currentModel) ?? 0,
-      ralphMode: runner.ralphMode
+      ralphMode: runner.ralphMode,
+      thinkingEffort: runner.currentThinkingEffort
     });
   }
   if (opts.initialPrompt) {
@@ -4691,6 +4860,7 @@ async function main() {
     const agentOpts = {
       model,
       cwd: args.cwd,
+      initialThinkingEffort: getPreferredThinkingEffort(),
       reporter: new CliReporter
     };
     if (sessionId)

package/package.json

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

package/codex-lazy-fix.md

@@ -1,76 +0,0 @@
-# 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/plan-code-health.md

@@ -1,169 +0,0 @@
-# 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.