pikiloom 0.4.26 → 0.4.28

package/dist/agent/drivers/claude-tui.js

@@ -1,41 +1,3 @@
-/**
- * Claude TUI driver — runs the interactive `claude` CLI under a PTY so usage
- * counts against the user's Pro/Max subscription instead of the API-priced
- * Agent SDK credit pool. Functionally near-equivalent to the headless -p
- * stream: we tail the JSONL transcript that Claude Code writes incrementally
- * to `~/.claude/projects/<encoded>/<id>.jsonl` and surface tool/text/usage
- * events through the same `claudeParse` parser used by the print-mode driver.
- *
- * Default driver for Claude turns. Set `PIKILOOM_CLAUDE_PRINT=1` (or the
- * legacy `PIKILOOM_CLAUDE_TUI=0`) to force the print-mode driver instead.
- * When any startup prerequisite fails (node-pty missing, prebuilt helper
- * unusable, PTY allocation refused) this function THROWS — the dispatcher in
- * `claude.ts` catches that and falls back to print mode so pikiloom stays
- * working out of the box.
- *
- * How it works:
- *   1. Reserve a session id upfront (random UUID, or the resume target).
- *   2. Drop a temp settings file with `SessionStart` / `Stop` /
- *      `UserPromptSubmit` hooks pointing at a tiny helper script — the script
- *      mutates a shared state JSON file so the parent process learns the real
- *      session id / transcript path / turn-end signal.
- *   3. Spawn `claude` under a real PTY (via `node-pty`) with the prompt as
- *      positional argv. Claude TUI auto-submits the prompt on startup.
- *   4. Poll the transcript JSONL incrementally; feed each line through
- *      `claudeParse`. JSONL records lack `stream_event` / `result` events, so
- *      we patch up the missing `s.text` / `s.thinking` accumulation and
- *      `assistant.message.usage` extraction in the loop.
- *   5. When the `Stop` hook fires (Claude has finished the assistant turn),
- *      SIGTERM the PTY process. The JSONL is fully flushed by then.
- *      Exception — background sub-agents: Claude fires `Stop` whenever the
- *      main loop finishes a response segment, *including* the segment that
- *      launched `run_in_background` agents. Those agents live inside the
- *      claude process, so killing on that first Stop would destroy them
- *      mid-flight. The driver therefore refuses to terminate while launched
- *      background agents haven't reported their `<task-notification>`, and
- *      only accepts a Stop that is "fresh" (fired after the last
- *      notification) — see `decideClaudeTuiStop`.
- */
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -46,31 +8,8 @@ import { createRetainedLogSink } from '../../core/logging.js';
 import { stripAnsiEscapes } from '../../core/utils.js';
 import { AGENT_STREAM_HARD_KILL_GRACE_MS, CLAUDE_TUI_STALL_QUIET_MS, CLAUDE_TUI_STALL_PENDING_TOOL_MS, CLAUDE_TUI_STALL_PTY_DEAD_MS, CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS, CLAUDE_TUI_MODEL_ERROR_SETTLE_MS, } from '../../core/constants.js';
 import { claudeParse, createClaudeStreamState, claudeContextWindowFromModel, claudeEffectiveContextWindow, registerClaudeBackgroundAgentLaunch, pendingClaudeBackgroundAgentCount, registerClaudeBackgroundBashLaunch, pendingClaudeBackgroundBashCount, extractClaudeBackgroundTaskId, extractClaudeWorkflowRunId, claudeEffortAndWorkflowArgs, scrubClaudeSessionContextEnv, } from './claude.js';
-// ---------------------------------------------------------------------------
-// Stall diagnostics (capture-only)
-// ---------------------------------------------------------------------------
-//
-// We instrument the mid-turn freeze before tuning the watchdog: the next pause
-// should be classified from data, not guesswork. Records land append-only in
-// ~/.pikiloom/diagnostics/claude-tui-stall.jsonl across three moments:
-//   - 'quiet'    — heartbeat while a turn has gone silent past the threshold
-//                  (captures the lead-up to a stall, throttled)
-//   - 'stall'    — the watchdog declared the turn dead and SIGTERMed it
-//   - 'resolved' — a turn that went quiet ended (completed / killed / aborted),
-//                  so benign long-thinking is separable from true freezes
-//
-// The decisive field is `ptyQuietMs` vs `quietMs`: a large quietMs (JSONL/hook
-// signals silent) paired with a small ptyQuietMs (PTY still painting frames)
-// means the model stream froze behind a live spinner — which defeats the
-// PTY-dead fast path and forces the slow 10-min quiet threshold. Confirming
-// that pattern (or refuting it) is the whole point of this pass.
-/** Begin recording heartbeats once no live signal has advanced for this long. */
 const STALL_DIAG_QUIET_THRESHOLD_MS = 45_000;
-/** Throttle heartbeats while a turn stays quiet, so a long freeze is sampled
- *  (not logged every 200ms poll tick). */
 const STALL_DIAG_HEARTBEAT_INTERVAL_MS = 30_000;
-// undefined = not yet initialised; null = init failed (give up, never retry);
-// function = ready. Shared across all turns so every session appends to one file.
 let stallDiagSink;
 function writeStallDiag(record) {
     if (stallDiagSink === null)
@@ -91,9 +30,6 @@ function writeStallDiag(record) {
         stallDiagSink = null;
     }
 }
-/** Cheap capture-only label for the last transcript event before a quiet
- *  stretch — the freeze signature is "next assistant never starts after a
- *  tool_result", so the kind of the last event matters. */
 export function classifyClaudeJsonlEvent(ev) {
     const type = typeof ev?.type === 'string' ? ev.type : 'unknown';
     const content = ev?.message?.content;
@@ -110,11 +46,6 @@ export function classifyClaudeJsonlEvent(ev) {
     return type;
 }
 async function loadPty() {
-    // Dynamic import keeps node-pty an optional dependency — if it's not
-    // installed the print-mode dispatcher in claude.ts will catch the throw
-    // and fall back to `-p`. The variable-specifier indirection is required so
-    // TypeScript does not try to resolve `node-pty` at compile time when the
-    // dep is absent.
     const specifier = 'node-pty';
     const mod = await import(/* @vite-ignore */ specifier);
     const api = mod?.default ?? mod;
@@ -123,14 +54,6 @@ async function loadPty() {
     await preflightSpawnHelper();
     return api;
 }
-/**
- * On macOS / Linux, node-pty's prebuilt `spawn-helper` ships without the
- * executable bit set on some npm installs (the npm tarball drops mode bits
- * when extracted under certain umask settings). Without the bit, every
- * `pty.spawn` returns the cryptic `posix_spawnp failed.` because the helper
- * itself can't run. Restore the bit eagerly the first time the driver loads
- * so users don't have to debug this on their own.
- */
 let spawnHelperPreflightDone = false;
 async function preflightSpawnHelper() {
     if (spawnHelperPreflightDone || process.platform === 'win32') {
@@ -139,8 +62,6 @@ async function preflightSpawnHelper() {
     }
     spawnHelperPreflightDone = true;
     try {
-        // Resolve relative to the loaded node-pty package. require.resolve isn't
-        // available in ESM; walk node_modules from this file's URL instead.
         const ptyRoot = await locatePtyPackageRoot();
         if (!ptyRoot)
             return;
@@ -160,9 +81,6 @@ async function preflightSpawnHelper() {
     }
 }
 async function locatePtyPackageRoot() {
-    // Walk up from this file looking for a node_modules/node-pty/package.json.
-    // This is the dist-time layout (compiled to dist/) AND the tsx runtime
-    // layout (running from src/) — both have node_modules at the project root.
     let dir = path.dirname(new URL(import.meta.url).pathname);
     for (let i = 0; i < 8; i++) {
         const candidate = path.join(dir, 'node_modules', 'node-pty');
@@ -175,11 +93,6 @@ async function locatePtyPackageRoot() {
     }
     return null;
 }
-// ---------------------------------------------------------------------------
-// Hook helper script — written to a temp dir per turn. Receives Claude Code
-// hook JSON payloads on stdin and mutates a shared state file so the parent
-// can react to lifecycle events without needing socket / IPC plumbing.
-// ---------------------------------------------------------------------------
 const HOOK_SCRIPT = `#!/usr/bin/env node
 "use strict";
 const fs = require("node:fs");
@@ -239,12 +152,6 @@ function readHookState(statePath) {
         return {};
     }
 }
-/**
- * Incremental JSONL tail. Reads from `fromOffset` to the file's current size,
- * splits on newlines, and stops one line short if the last segment doesn't end
- * with `\n` (so a partially-written final line gets re-read next tick rather
- * than corrupting JSON.parse).
- */
 function readJsonlIncrement(filePath, fromOffset) {
     try {
         const stat = fs.statSync(filePath);
@@ -261,11 +168,9 @@ function readJsonlIncrement(filePath, fromOffset) {
         const endsWithNewline = chunk[chunk.length - 1] === '\n';
         const segments = chunk.split('\n');
         if (endsWithNewline) {
-            // Last segment after split is empty — drop it.
             segments.pop();
             return { offset: stat.size, lines: segments };
         }
-        // Partial last line — keep its bytes unread for the next tick.
         const lastLine = segments.pop() || '';
         const consumed = stat.size - Buffer.byteLength(lastLine, 'utf8');
         return { offset: consumed, lines: segments };
@@ -274,10 +179,6 @@ function readJsonlIncrement(filePath, fromOffset) {
         return { offset: fromOffset, lines: [] };
     }
 }
-// 20 chars / 20 ms = 1000 chars/s. Haiku generates ~150 tok/s (~600 chars/s),
-// Sonnet/Opus are slower. Running ahead of the model keeps the buffer drained
-// during continuous generation. CJK characters render at ~2x ASCII visual
-// width but this rate still feels natural in both scripts.
 const TUI_STREAM_CHUNK_CHARS = 20;
 const TUI_STREAM_CHUNK_INTERVAL_MS = 20;
 function makeTuiStreamBuffer() {
@@ -323,25 +224,6 @@ export function detectClaudeTuiTerminalLimitNotice(msgOrText) {
         return null;
     return limitNoticeFromText(extractTextBlocks(msgOrText.content));
 }
-/**
- * Evidence-based arbitration for a detected limit notice. The banner text is
- * deliberately matched broadly (wording shifts across CLI versions and some
- * notices are informational — "You're now using usage credits · Your session
- * limit resets 3pm" means the turn CONTINUES on extra-usage credits), so a
- * match alone must never fail the turn. What decides the outcome is whether
- * the turn produced anything substantive after the banner:
- *
- *  - 'info'  — assistant text exists, or a substantive signal (non-synthetic
- *              assistant JSONL, hook tool event, sub-agent sidecar) postdates
- *              the notice. The turn is alive; the notice is informational.
- *  - 'fatal' — nothing substantive after the banner. The limit genuinely ate
- *              the turn; surface the banner text as a rate_limit failure.
- *  - 'none'  — no notice was seen.
- *
- * Worst case of the broad matching is therefore an activity line, not a
- * killed turn (the bug this replaced: the credits banner used to SIGTERM the
- * process mid-answer).
- */
 export function resolveClaudeTuiLimitOutcome(input) {
     if (!input.noticeText)
         return 'none';
@@ -349,63 +231,14 @@ export function resolveClaudeTuiLimitOutcome(input) {
         return 'info';
     return 'fatal';
 }
-/**
- * Detect Claude Code's startup "Bypass Permissions mode" confirmation dialog in
- * a slice of (ANSI-stripped) PTY screen output. When pikiloom spawns the TUI
- * with `--permission-mode bypassPermissions` (the default) on a machine that
- * has not yet accepted bypass mode, Claude paints a blocking prompt:
- *
- *     WARNING: Claude Code running in Bypass Permissions mode
- *     ...
- *   ❯ 1. No, exit
- *     2. Yes, I accept
- *
- * The default highlight sits on "No, exit", so the driver's blind prompt-submit
- * Enter nudge would pick *exit* — the message never gets processed and the turn
- * hangs on a pre-prompt. Seeding `bypassPermissionsModeAccepted` in config is
- * not a reliable fix: it is version-fragile (observed no-op on 2.1.169) and
- * gated by org policy (`isBypassPermissionsModeAvailable`). So we detect the
- * dialog on the wire and auto-select "Yes, I accept". Require all three
- * distinctive fragments so ordinary text mentioning "bypass" can't trigger it.
- */
 export function detectClaudeBypassPrompt(screen) {
     if (typeof screen !== 'string' || !screen)
         return false;
-    // Claude's TUI lays words out with cursor-move escapes (`\x1b[<col>G`) rather
-    // than literal spaces, so once ANSI is stripped the on-screen text runs
-    // together — the real dialog reads "BypassPermissionsmode" / "Yes,Iaccept" /
-    // "No,exit", not the spaced form. Collapse all whitespace before matching so
-    // the detector fires on the live PTY screen *and* on space-preserving
-    // renderings. (Verified against claude 2.1.168's actual bypass screen.)
     const t = stripAnsiEscapes(screen).replace(/\s+/g, '').toLowerCase();
     return t.includes('bypasspermissionsmode')
         && t.includes('yes,iaccept')
         && t.includes('no,exit');
 }
-/**
- * Detect Claude Code's *mid-turn* per-command permission confirmation in a slice
- * of (ANSI-stripped) PTY screen output. Even under `--permission-mode
- * bypassPermissions`, an explicit `ask` rule in settings (e.g. `Bash(git tag:*)`,
- * `git commit`, `git push`) is still honoured, so the TUI paints:
- *
- *     Permission rule Bash(git tag:*) requires confirmation for this command.
- *     Do you want to proceed?
- *   ❯ 1. Yes
- *     2. Yes, and don't ask again for: …
- *     3. No
- *     Esc to cancel · Tab to amend · ctrl+e to explain
- *
- * Nothing answers it (detectClaudeBypassPrompt only handles the *startup* bypass
- * dialog), so the turn hangs until the stall watchdog SIGTERMs it and mislabels
- * the block as a "CLI freeze". We detect it on the wire and select "1. Yes" —
- * restoring the bypass intent turn-by-turn without mutating the user's settings
- * (option 2 "don't ask again" would).
- *
- * Thin wrapper over {@link classifyClaudeScreen} (state === 'confirm-prompt') so the in-flight
- * auto-answer and the stall watchdog share ONE verdict. The earlier standalone implementation
- * required the literal footer "esctocancel", which truncates at the 200-col screen edge
- * ("sctocancel") and silently missed real prompts — the structural classifier does not.
- */
 export function detectClaudeProceedPrompt(screen) {
     return classifyClaudeScreen(screen).state === 'confirm-prompt';
 }
@@ -433,44 +266,26 @@ export function classifyClaudeScreen(screen) {
         return { state: 'unknown', affirmativeKey: null, sample: '' };
     const stripped = stripAnsiEscapes(screen);
     const sample = stripped.replace(/\s+/g, ' ').trim().slice(-400);
-    // Claude positions words with cursor moves, so the live screen is spaceless; match against the
-    // despaced form (see detectClaudeBypassPrompt).
     const ds = stripped.replace(/\s+/g, '').toLowerCase();
-    // 1. Startup bypass-permissions dialog (option 1 is "No, exit" — affirmative is option 2).
-    //    Require all three distinctive fragments so ordinary "bypass" prose can't trigger it
-    //    (mirrors detectClaudeBypassPrompt). Checked first: it overlaps the numbered-select shape.
     if (ds.includes('bypasspermissionsmode') && ds.includes('yes,iaccept') && ds.includes('no,exit')) {
         return { state: 'bypass-startup', affirmativeKey: '2', sample };
     }
-    // 2. Selected-model-unavailable banner. Distinctive phrasing; reuse the shared detector so the
-    //    -p and TUI paths stay in lockstep.
     if (detectClaudeModelError(ds))
         return { state: 'model-error', affirmativeKey: null, sample };
     const asksProceed = ds.includes('doyouwanttoproceed') || ds.includes('wouldyouliketoproceed');
-    const hasCursorSelect = ds.includes('❯') && ds.includes('1.'); // a real Ink select, not prose
-    // 3. Plan-approval dialog (ExitPlanMode / Ultraplan). Distinctive option text. NOT auto-answered:
-    //    affirmativeKey stays null so the chokepoint terminates cleanly and asks the user to re-send
-    //    rather than pressing "Yes, and bypass permissions" (standing session bypass).
+    const hasCursorSelect = ds.includes('❯') && ds.includes('1.');
     if ((asksProceed || ds.includes('readytoexecute'))
         && (ds.includes('manuallyapproveedits') || ds.includes('yes,andbypasspermissions'))) {
         return { state: 'plan-approval', affirmativeKey: null, sample };
     }
-    // 4. Mid-turn confirm/select. A proceed/confirm question + a cursor'd numbered select. Bypass and
-    //    plan dialogs are already handled above, so by here option 1 is the "Yes" affirmative.
     if ((asksProceed || ds.includes('requiresconfirmation')) && hasCursorSelect) {
         return { state: 'confirm-prompt', affirmativeKey: '1', sample };
     }
-    // 4b. Standalone interactive prompts distinctive enough to need no numbered select: the
-    //     trust-a-new-folder dialog, and explicit (y/n) confirmations.
     if (ds.includes('trustthisfolder'))
         return { state: 'confirm-prompt', affirmativeKey: '1', sample };
     if ((asksProceed || ds.includes('doyouwant')) && ds.includes('(y/n)')) {
         return { state: 'confirm-prompt', affirmativeKey: 'y', sample };
     }
-    // 5. Idle REPL — claude finished and is back at the input line. Key on the PERSISTENT mode-line
-    //    (real idle screens carry typed-ahead like "/install", so an empty `❯` is unreliable) and
-    //    require the absence of the active "esc to interrupt" hint so a frozen spinner frame that
-    //    happens to still show the mode-line is NOT mistaken for idle.
     if (ds.includes('bypasspermissionson')
         && (ds.includes('shift+tabtocycle') || ds.includes('foragents') || ds.includes('tomanage'))
         && !ds.includes('esctointerrupt')) {
@@ -478,31 +293,12 @@ export function classifyClaudeScreen(screen) {
     }
     return { state: 'unknown', affirmativeKey: null, sample };
 }
-/**
- * Backward-compatible capture-only wrapper retained for the stall-diagnostics heartbeat. A "prompt"
- * is any blocking dialog state (confirm / plan / startup-bypass). Derives from
- * {@link classifyClaudeScreen} so there is one classifier, not two.
- */
 export function classifyStallScreen(screen) {
     const info = classifyClaudeScreen(screen);
     const looksLikePrompt = info.state === 'confirm-prompt'
         || info.state === 'plan-approval' || info.state === 'bypass-startup';
     return { looksLikePrompt, sample: info.sample };
 }
-/**
- * Extract text / thinking blocks from an assistant JSONL event and route them:
- * text → the chunked stream buffer (slow drain), thinking → `s.thinking`
- * directly. Tool uses, stop reasons, sub-agents, etc. are still handled by
- * `claudeParse` once we've stripped the text/thinking blocks out of the event
- * (see `callClaudeParseForTui`) — otherwise `claudeParse`'s "fill if empty"
- * fallback would clobber the buffered streaming.
- */
-/**
- * Pull the server-assigned task id out of a PostToolUse hook's tool_response.
- * Claude Code's hook payload mirrors the JSONL tool_result shape — usually
- * `{ task: { id, subject }, ...}` for TaskCreate. Falls back to scanning the
- * textual response for "Task #N created" when the structured form is missing.
- */
 function readAssignedTaskIdFromHookResponse(toolResponse) {
     const structured = toolResponse?.task?.id;
     if (structured != null && String(structured).trim())
@@ -519,26 +315,11 @@ function readAssignedTaskIdFromHookResponse(toolResponse) {
     }
     return null;
 }
-/**
- * Apply a single PreToolUse / PostToolUse hook event to the parser state.
- * Mirrors what `claudeParse` would do for the matching JSONL tool_use /
- * tool_result, but fires the instant Claude calls the tool — so the IM
- * placeholder card actually updates during the turn instead of staying empty
- * until Stop. Dedup with the eventual JSONL flush is via `tool_use_id`:
- * claudeParse skips tools already in `s.seenClaudeToolIds`, and the new
- * `s.seenClaudeToolResultIds` guards tool_result re-pushes.
- */
 export function applyHookToolEvent(ev, s) {
     const toolUseId = String(ev?.tool_use_id || '').trim();
     const toolName = String(ev?.tool_name || '').trim();
     if (!toolName || !toolUseId)
         return false;
-    // Sub-agent tool calls fire the parent's Pre/PostToolUse hooks too (one
-    // hook pipeline per CLI process). Claude Code tags those payloads with
-    // `agent_id`; route them to the matching sub-agent's tool list instead of
-    // appending to the parent's recentActivity. Without this every Task spawn
-    // floods the parent's 执行 card with the children's tool stream while the
-    // sub-agent cards sit empty until the sidecar JSONL flushes at Stop.
     const subAgentId = typeof ev?.agent_id === 'string' && ev.agent_id ? ev.agent_id : '';
     if (subAgentId) {
         if (ev.event === 'PreToolUse') {
@@ -592,12 +373,6 @@ export function applyHookToolEvent(ev, s) {
             return true;
         }
         if (toolName === 'Task' || toolName === 'Agent') {
-            // Register the sub-agent so `meta.subAgents` lights up the new
-            // Sub-agent preview block. Sub-agents are isolated from parent activity
-            // by design (the dedicated section shows their own tool stream); pushing
-            // into parent recentActivity would re-introduce the noise the isolation
-            // is meant to prevent. Granular sub-agent tool calls land later via the
-            // sidecar pump → `routeClaudeSubAgentEvent`.
             const input = ev.tool_input || {};
             const desc = typeof input.description === 'string' ? input.description.trim() : '';
             const kind = typeof input.subagent_type === 'string' ? input.subagent_type.trim() : '';
@@ -611,27 +386,15 @@ export function applyHookToolEvent(ev, s) {
                     status: 'running',
                 });
             }
-            // Backgrounded launch — track it so the turn doesn't end (and the PTY
-            // doesn't get SIGTERMed) until its <task-notification> arrives. The hook
-            // fires live; the JSONL replay of the same tool_use dedupes via
-            // seenClaudeToolIds, so this is the only registration point in TUI mode.
             if (input.run_in_background === true)
                 registerClaudeBackgroundAgentLaunch(s, toolUseId);
             s.seenClaudeToolIds.add(toolUseId);
             s.claudeToolsById.set(toolUseId, { name: toolName, summary: desc || kind || 'Sub-agent' });
             return true;
         }
-        // Background Bash — register like a backgrounded agent so the turn's Stop
-        // holds the PTY open until its <task-notification> lands, instead of
-        // SIGTERMing the still-running command (and its future report-back turn).
         if (toolName === 'Bash' && ev.tool_input?.run_in_background === true) {
             registerClaudeBackgroundBashLaunch(s, toolUseId);
         }
-        // Workflow → always-backgrounded multi-agent orchestration. Same in-process
-        // lifecycle as a run_in_background Task; register so the turn's Stop holds
-        // the PTY instead of SIGTERMing the in-flight workflow. The hook fires live;
-        // the JSONL replay of the same tool_use dedupes via seenClaudeToolIds, so
-        // this is the only registration point in TUI mode.
         if (toolName === 'Workflow') {
             registerClaudeBackgroundAgentLaunch(s, toolUseId);
         }
@@ -673,13 +436,6 @@ export function applyHookToolEvent(ev, s) {
             return true;
         }
         if (toolName === 'Task' || toolName === 'Agent') {
-            // Sub-agent finished — flip its status so it drops out of the live
-            // Sub-agent preview block. The completion fact itself is implicit: the
-            // block stops listing this entry.
-            // Backgrounded launches are the exception: their PostToolUse fires
-            // immediately with a launch ack while the agent keeps running. Leave the
-            // status alone — applyClaudeTaskNotification flips it when the real
-            // completion lands.
             const sub = s.subAgents.get(toolUseId);
             if (sub) {
                 const isBgLaunchAck = !ev.tool_response?.is_error
@@ -701,16 +457,12 @@ export function applyHookToolEvent(ev, s) {
                 s.activity = s.recentActivity.join('\n');
             }
         }
-        // Background Bash launch ack → map task id → tool_use for notification
-        // resolution (bash notifications usually omit <tool-use-id>).
         if (toolName === 'Bash' && s.bgBashToolUseIds?.has(toolUseId)
             && !s.bgAgentCompletedToolUseIds?.has(toolUseId)) {
             const taskId = extractClaudeBackgroundTaskId(ev.tool_response);
             if (taskId && !s.bgTaskIdToToolUse.has(taskId))
                 s.bgTaskIdToToolUse.set(taskId, toolUseId);
         }
-        // Workflow launch ack → map runId → tool_use for notification resolution
-        // (the workflow's <task-notification> may carry only the task id).
         if (toolName === 'Workflow' && s.bgAgentLaunchedToolUseIds?.has(toolUseId)
             && !s.bgAgentCompletedToolUseIds?.has(toolUseId)) {
             const runId = extractClaudeWorkflowRunId(ev.tool_response);
@@ -722,11 +474,6 @@ export function applyHookToolEvent(ev, s) {
     }
     return false;
 }
-/**
- * Lite TodoWrite parser used by the hook path — avoids pulling parseTodoWriteAsPlan
- * from agent/utils into this file's already-large import surface. Identical
- * semantics for the legacy 1.x plan tool.
- */
 function parseTodoWriteAsPlanLite(input) {
     if (!input || typeof input !== 'object')
         return null;
@@ -750,11 +497,6 @@ function parseTodoWriteAsPlanLite(input) {
         return null;
     return { explanation: null, steps };
 }
-/**
- * Reimplementation of claude.ts's rebuildClaudePlanFromTasks (it's private to
- * that module). Kept tiny and dependency-free so the hook code path stays
- * independent of the JSONL parser's internals.
- */
 function rebuildClaudePlanFromTasksFromState(s) {
     if (!s.claudeTaskOrder?.length)
         return;
@@ -794,14 +536,6 @@ function applyAssistantStreaming(s, msg, buf) {
         s.thinking = s.thinking ? `${s.thinking}\n\n${appendThinking}` : appendThinking;
     }
 }
-/**
- * Hand a JSONL event to the shared `claudeParse`, but for `assistant` events
- * first strip out the text/thinking blocks. Reason: `claudeParse`'s assistant
- * branch contains a `if (tx && !s.text.trim()) s.text = tx` fallback — useful
- * for print mode where deltas may have missed, harmful here because it would
- * dump the entire response into `s.text` in one go, bypassing the simulated
- * stream we just routed into the buffer.
- */
 function callClaudeParseForTui(ev, s) {
     if (ev.type !== 'assistant' || !ev.message) {
         claudeParse(ev, s);
@@ -818,15 +552,6 @@ function callClaudeParseForTui(ev, s) {
     };
     claudeParse(filtered, s);
 }
-/**
- * Set `s.contextWindow` from a model id, the same way the `-p` parser does on
- * each `system` / `stream_event` / `result` event. TUI mode never sees those
- * events (JSONL is the source of truth and only carries `user`/`assistant`/
- * `attachment`/`summary`), so without this call `s.contextWindow` stays null
- * and `computeContext()` returns `contextPercent: null` → the dashboard's
- * `ContextDot` and percent chip both disappear. Guarded by `byokContextWindow`
- * so BYOK Profiles' externally-cached window wins (matches print-mode).
- */
 function applyModelContextWindow(s) {
     if (s.byokContextWindow)
         return;
@@ -835,18 +560,10 @@ function applyModelContextWindow(s) {
     if (effective != null)
         s.contextWindow = effective;
 }
-/** Per-call token usage from an assistant event's `message.usage`. -p mode
- *  derives these from `stream_event/message_delta`; JSONL only carries them
- *  here. Per-call semantics: each assistant event represents one LLM call and
- *  its usage replaces the prior snapshot. */
 function applyAssistantUsage(s, msg) {
     const u = msg?.usage;
     if (!u || typeof u !== 'object')
         return;
-    // JSONL has no message_start marker — a fresh message.id is the per-call
-    // boundary. Fold the finished call's output into the turn-cumulative base
-    // before this call's counters take over (events of the same call share an
-    // id and carry running totals, so only the id transition folds).
     const msgId = typeof msg?.id === 'string' && msg.id ? msg.id : null;
     if (msgId && msgId !== s.turnUsageMsgId) {
         if (s.turnUsageMsgId != null)
@@ -864,47 +581,13 @@ function applyAssistantUsage(s, msg) {
     const total = (s.inputTokens ?? 0) + (s.cachedInputTokens ?? 0) + (s.cacheCreationInputTokens ?? 0) + (s.outputTokens ?? 0);
     s.contextUsedTokens = total > 0 ? total : null;
 }
-// ---------------------------------------------------------------------------
-// Stop-hook gating
-// ---------------------------------------------------------------------------
-/**
- * After the last pending background agent reports its <task-notification>,
- * the harness re-invokes the model (wrap-up segment) and a fresh Stop hook
- * follows. A Stop timestamp that *predates* the latest notification belongs to
- * an earlier segment and must not terminate the turn. If no re-invocation
- * materialises, we accept the stale Stop once the main JSONL has been quiet
- * for this long — the safety valve against waiting forever on a harness that
- * chose not to resume.
- */
 const BG_RESETTLE_QUIET_MS = 30_000;
-/**
- * Decide what a fired Stop hook means for the PTY lifecycle.
- *
- *  - `hold-background`: launched `run_in_background` agents haven't reported
- *    completion. They live inside the claude process — SIGTERM now would
- *    destroy them mid-flight (the "进程退出把子代理打断" failure). Keep the
- *    PTY alive; the harness will deliver <task-notification> events and
- *    re-invoke the model, producing further segments and a later Stop.
- *  - `hold-resettle`: nothing pending, but the Stop predates the latest
- *    notification — the model's post-notification segment (and its own Stop)
- *    is still expected. Hold until a fresh Stop or BG_RESETTLE_QUIET_MS of
- *    JSONL silence.
- *  - `terminate`: the Stop is the genuine end of the turn.
- *
- * The `hold-background` path carries a quiet-TTL: a genuinely-running
- * background agent keeps emitting hook/sidecar/JSONL traffic, so a hold whose
- * every channel has been silent past CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS is a
- * phantom (lost <task-notification> / completion never observed). Releasing
- * it as a normal Stop keeps the turn's clean semantics — letting the stall
- * watchdog reap it instead would mislabel a finished turn 'stalled' and
- * inject a confusing auto-resume prompt into the next turn.
- */
 export function decideClaudeTuiStop(input) {
     if (input.pendingBackgroundAgents > 0) {
         const ttl = input.holdQuietTtlMs ?? CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS;
         const lastActivityAt = Math.max(input.stoppedAt, input.lastJsonlEventAt, input.lastTaskNotificationAt, input.lastHookOrSidecarEventAt ?? 0);
         if (input.now - lastActivityAt > ttl)
-            return 'terminate'; // 幽灵 hold:全通道静默超 TTL
+            return 'terminate';
         return 'hold-background';
     }
     const stopIsStale = input.lastTaskNotificationAt > 0 && input.lastTaskNotificationAt >= input.stoppedAt;
@@ -916,52 +599,11 @@ export function decideClaudeTuiStop(input) {
     }
     return 'terminate';
 }
-/**
- * True for the `im_ask_user` MCP tool in any form — Claude Code names MCP tools
- * `mcp__<server>__<tool>` (here `mcp__pikiloom__im_ask_user`), so match the
- * namespaced suffix as well as the bare name (robust to the server name
- * changing). The driver tails Pre/PostToolUse hooks by id but must also know
- * *which* pending tool is the one that blocks on the user, so the stall
- * watchdog can stay armed for every other tool and disarm only for a live
- * question. See decideClaudeTuiStall(`awaitingUserReply`).
- */
 export function isAskUserToolName(name) {
     if (typeof name !== 'string' || !name)
         return false;
     return name === 'im_ask_user' || name.endsWith('__im_ask_user');
 }
-/**
- * Decide whether the turn has gone dead. claude CLI is known to freeze
- * mid-turn (observed 2026-06-02 on 2.1.160): after a tool_result lands the
- * next assistant segment never starts — the process stays alive, the JSONL
- * goes permanently quiet, no Stop hook ever fires, no error surfaces. Without
- * a watchdog the IM card spins forever.
- *
- * `lastProgressAt` is the freshest of every live signal the driver tracks
- * (main JSONL, hook tool events, sub-agent sidecars, hook lifecycle state).
- * A pending tool (PreToolUse seen, no PostToolUse) extends the threshold:
- * the freeze can also hit mid-execution, but a legitimately long foreground
- * command must not get shot — claude's own Bash timeout fires PostToolUse
- * well inside CLAUDE_TUI_STALL_PENDING_TOOL_MS.
- *
- * Fast path: `lastPtyDataAt` is raw PTY output (any repaint frame counts). A
- * healthy TUI animates continuously mid-turn — spinner, stream ticks, status
- * line — so PTY byte-silence is the cheapest possible "event loop is dead"
- * detector. When BOTH the PTY and all structured signals have been silent
- * past `ptyDeadMs`, declare the stall immediately instead of waiting out the
- * 10/30-minute quiet thresholds. Long thinking and long foreground commands
- * keep painting frames, which routes them to the slow thresholds as before.
- *
- * `awaitingUserReply` is the one state that is quiet BY DESIGN, not because the
- * process froze: an `im_ask_user` MCP call is in flight (PreToolUse seen, no
- * PostToolUse) and the turn is blocked on the user's reply — the `/ask-user`
- * callback never times out. Every signal (JSONL, hooks, PTY) goes silent while
- * the user thinks, which is indistinguishable by timing alone from a freeze, so
- * the watchdog must never stall here. The hard turn deadline remains the
- * backstop if the user never answers; PostToolUse re-arms the watchdog the
- * instant the answer lands. Without this, the last question regularly gets
- * SIGTERMed mid-wait and mislabelled a "CLI freeze".
- */
 export function decideClaudeTuiStall(input) {
     if (input.awaitingUserReply)
         return 'wait';
@@ -976,59 +618,30 @@ export function decideClaudeTuiStall(input) {
         : (input.quietMs ?? CLAUDE_TUI_STALL_QUIET_MS);
     return input.now - input.lastProgressAt > threshold ? 'stall' : 'wait';
 }
-/**
- * Map the screen state at the moment the stall watchdog would fire to what we should actually do.
- * This is the chokepoint the diagnostics proved was missing: today the screen is classified at kill
- * time but the verdict only changes the error STRING, never the action — so confirm-dialog /
- * idle-REPL / model-error turns get SIGTERMed as 'stalled' and auto-resumed into the same wall.
- *
- * Safety (default-deny): a non-'unknown' state may only DOWNGRADE to a still-terminating, non-
- * resuming outcome — it never cancels termination and never waits beyond one bounded retry. Anything
- * ambiguous falls through to 'terminate-stalled' (today's self-healing path), because mislabelling a
- * real freeze as clearable/idle would convert an auto-resumable stall into a silently dropped turn.
- */
 export function decideStallAction(input) {
     if (input.state === 'model-error')
         return 'model-error';
-    // Answerable dialogs (ask-rule confirm / startup bypass). Plan-approval reaches here too but
-    // carries affirmativeKey=null under the current policy → falls straight to unanswered.
     if (input.state === 'confirm-prompt' || input.state === 'plan-approval' || input.state === 'bypass-startup') {
         if (input.affirmativeKey && !input.alreadyTriedAnswer)
             return 'answer-retry';
         return 'terminate-prompt-unanswered';
     }
     if (input.state === 'idle-repl') {
-        // Back at the prompt = the turn ended (Stop hook missed/held). Terminate cleanly ONLY when no
-        // background work is outstanding: a bg agent/bash lives inside the claude process and bg-Bash
-        // is silent by nature, so killing an idle-looking screen with pending bg would abort live work
-        // ("进程退出把子代理打断"). Leave those to the existing Stop-hold / TTL machinery.
         return input.pendingBgAgents > 0 ? 'terminate-stalled' : 'terminate-clean';
     }
     return 'terminate-stalled';
 }
-// ---------------------------------------------------------------------------
-// Main entry
-// ---------------------------------------------------------------------------
 export async function doClaudeTuiStream(opts) {
     const start = Date.now();
     const deadline = start + opts.timeout * 1000;
-    // 0. Probe node-pty FIRST — before any temp-dir creation or session work.
-    // If it's not installed (or its prebuilt helper can't be made executable),
-    // throw so the dispatcher in claude.ts catches the error and falls back to
-    // print mode. No cleanup needed because no resources have been allocated.
     const pty = await loadPty();
-    // 1. Resolve session lifecycle.
     const isFork = !!opts.forkOf;
     const isResume = !isFork && !!opts.sessionId;
     const newSessionId = (isFork || !isResume) ? randomUUID() : opts.sessionId;
     const home = getHome();
     const projectDir = path.join(home, '.claude', 'projects', encodePathAsDirName(opts.workdir));
-    // For resume we know the exact file; for new/fork we either know upfront
-    // (--session-id) or learn it from the SessionStart hook (--fork-session
-    // rotates to a fresh uuid Claude generates on its own).
     let activeSessionId = isResume ? opts.sessionId : newSessionId;
     let activeJsonlPath = path.join(projectDir, `${activeSessionId}.jsonl`);
-    // Resume: skip everything that was already in the transcript before our turn.
     let jsonlReadOffset = 0;
     if (isResume) {
         try {
@@ -1036,7 +649,6 @@ export async function doClaudeTuiStream(opts) {
         }
         catch { }
     }
-    // 2. Temp workspace for hook script + state + settings.
     let workDir;
     try {
         workDir = fs.mkdtempSync(path.join(tmpdir(), 'pikiloom-claude-tui-'));
@@ -1053,25 +665,8 @@ export async function doClaudeTuiStream(opts) {
         fs.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 0o755 });
         fs.writeFileSync(statePath, JSON.stringify({ events: [] }));
         fs.writeFileSync(toolEventsPath, '');
-        // Use the same Node binary that's running pikiloom — `node` may not be on
-        // PATH inside the claude TUI's hook subprocess on every distro.
         const nodeBin = Q(process.execPath);
         const hookCmd = (event) => `${nodeBin} ${Q(hookPath)} ${event} ${Q(statePath)} ${Q(toolEventsPath)}`;
-        // Pre/PostToolUse hooks give us a live tool-event stream. The transcript
-        // JSONL is itself written incrementally (events land ~0.2–1.2s after they
-        // happen — measured on 2.1.173), but the hooks still earn their keep:
-        // PreToolUse fires the instant a tool *starts* (the JSONL tool_use only
-        // proves it was requested; a long-running Bash would otherwise sit
-        // invisible), they carry agent_id for sub-agent attribution, and they are
-        // the registration point for run_in_background launches that the Stop
-        // gating in decideClaudeTuiStop depends on. The hook script writes to
-        // tool-events.jsonl via atomic appends, sidestepping the
-        // read-modify-write race that affects the shared state.json file.
-        // Pre/PostToolUse require an explicit `matcher` field — without it Claude
-        // Code's hook dispatcher silently never fires the hook (the lifecycle
-        // hooks below don't need a matcher because they aren't tool-scoped).
-        // `*` matches every tool. Without this, the entire live-streaming wire-up
-        // is dead code.
         const settings = {
             hooks: {
                 SessionStart: [{ hooks: [{ type: 'command', command: hookCmd('SessionStart'), timeout: 5 }] }],
@@ -1090,7 +685,6 @@ export async function doClaudeTuiStream(opts) {
         catch { }
         return makeErrorResult(opts, start, `Failed to seed hook scaffold: ${e?.message || e}`);
     }
-    // 3. Build the claude argv. Crucially: NO `-p` — that's the whole point.
     const claudeArgs = [];
     if (isFork) {
         claudeArgs.push('--resume', opts.forkOf.parentSessionId, '--fork-session');
@@ -1107,8 +701,6 @@ export async function doClaudeTuiStream(opts) {
         claudeArgs.push('--model', model);
     if (opts.claudePermissionMode)
         claudeArgs.push('--permission-mode', opts.claudePermissionMode);
-    // Effort + Workflow gate — same source of truth as the `claude -p` driver, so
-    // the TUI path drops the Workflow tool unless orchestration was opted in.
     claudeArgs.push(...claudeEffortAndWorkflowArgs(opts));
     if (opts.claudeAppendSystemPrompt)
         claudeArgs.push('--append-system-prompt', opts.claudeAppendSystemPrompt);
@@ -1116,22 +708,12 @@ export async function doClaudeTuiStream(opts) {
         claudeArgs.push('--mcp-config', opts.mcpConfigPath);
     if (opts.claudeExtraArgs?.length)
         claudeArgs.push(...opts.claudeExtraArgs);
-    // Attachments: TUI doesn't accept base64-image stream-json input. Reference
-    // local paths via the @-mention syntax — Claude's TUI reads images from
-    // disk and inlines them into the message.
     let fullPrompt = opts.prompt;
     if (opts.attachments?.length) {
         const refs = opts.attachments.map(p => `@${p}`).join(' ');
         fullPrompt = `${refs}\n\n${opts.prompt}`;
     }
-    // `--mcp-config <configs...>` (and a few other Claude flags) are *variadic*
-    // — without a `--` terminator the positional prompt would be consumed as
-    // another MCP config path. Always end with `--` then the prompt.
     claudeArgs.push('--', fullPrompt);
-    // 4. Honour the existing steer-callback contract — TUI mode can't accept
-    // mid-turn additional input, but callers (bot.ts) always pass onSteerReady
-    // and expect it to be invoked. Give them a no-op so the orchestration doesn't
-    // hang waiting for the callback that never fires.
     try {
         opts.onSteerReady?.(async () => {
             agentWarn('[claude-tui] steer requested but TUI mode does not support mid-turn input — ignored');
@@ -1141,33 +723,13 @@ export async function doClaudeTuiStream(opts) {
     catch (e) {
         agentWarn(`[claude-tui] onSteerReady callback raised: ${e?.message || e}`);
     }
-    // 5. Set up parser state and ensure the bot side has the upfront session id.
     const s = createClaudeStreamState(opts);
-    // Resume: lock in the native id we are resuming. Fork: keep a placeholder until
-    // Claude reports its rotated id via the SessionStart hook. New session: leave
-    // s.sessionId at its initial value (null for a pending session) so the emit
-    // below detects a change and fires the pending→native promotion callback.
     if (isResume || isFork)
         s.sessionId = activeSessionId;
-    // Seed the context window from whatever model is configured up front (e.g.
-    // "haiku" / "opus" / "sonnet" via opts.claudeModel) so the dashboard's
-    // context-percent chip + green-dot indicator can render starting from the
-    // very first emit, before any assistant event has arrived to confirm the
-    // model. Subsequent assistant events with concrete model ids will refresh
-    // s.model + recompute the window via applyModelContextWindow.
     if (!s.model && (opts.claudeModel || opts.model)) {
         s.model = opts.claudeModel || opts.model;
     }
     applyModelContextWindow(s);
-    // A brand-new session uses the id we generated and passed via --session-id, so
-    // it is final the instant we spawn. Emit it now: s.sessionId is still unset
-    // here, so emitSessionIdUpdate fires the onSessionId callback that promotes the
-    // pending pikiloom record (and its in-memory runtime) to the native id. The
-    // prior `s.sessionId = activeSessionId` made this a silent no-op (emit dedups on
-    // `id === s.sessionId`), so the record stayed `pending_*` for the whole run —
-    // and since mergeManagedAndNativeSessions drops pending records, the dashboard
-    // never saw the in-flight session as running on (re)load. Fork waits for the
-    // SessionStart hook to report Claude's rotated id; resume is already native.
     if (!isResume && !isFork)
         emitSessionIdUpdate(s, activeSessionId);
     let stderrCapture = '';
@@ -1203,11 +765,6 @@ export async function doClaudeTuiStream(opts) {
             }
         }, after);
     };
-    // Answer a confirm/select dialog: settle (Ink drops input on the dialog's first frames) → the
-    // affirmative key → a split-out Enter (a combined "1\r" gets swallowed — only the digit lands)
-    // → drop the answered frame from screenTail so re-detection only fires on a genuine repaint, not
-    // the stale text we just answered. Shared by the in-flight onData path and the stall-chokepoint
-    // retry so the keystroke discipline lives in one place.
     const sendConfirmAnswer = (key, settleMs, confirmDelayMs, onConfirmed) => {
         setTimeout(() => {
             if (processExited)
@@ -1228,11 +785,6 @@ export async function doClaudeTuiStream(opts) {
             }, confirmDelayMs);
         }, settleMs);
     };
-    // Record-only: a limit banner is EVIDENCE, not a verdict. Some banners are
-    // informational (extra-usage credits kick in and the turn continues), so
-    // killing here would shoot healthy turns. resolveClaudeTuiLimitOutcome
-    // arbitrates later — at the stall watchdog and at result assembly — based
-    // on whether the turn produced anything substantive after the banner.
     const noteTerminalLimitNotice = (notice) => {
         if (terminalLimitNotice)
             return;
@@ -1243,15 +795,6 @@ export async function doClaudeTuiStream(opts) {
         s.activity = s.recentActivity.join('\n');
         emit();
     };
-    // Selected-model-unavailable notice (404 model_not_found). Unlike the limit
-    // banner this is terminal AND invisible to every structured signal: the TUI
-    // paints it to the PTY screen, writes nothing to the JSONL, and fires no Stop
-    // hook — so the turn would otherwise idle at the REPL until the 3–10 min stall
-    // watchdog kills it with a misleading "CLI freeze" message. We surface the
-    // real reason and end the turn now. The banner is still EVIDENCE, not a bare
-    // verdict: a short settle confirms nothing substantive followed (cross-
-    // validating the screen scrape) before we kill — never granting a lone text
-    // match the authority to shoot a healthy turn.
     const noteTerminalModelError = (notice) => {
         if (terminalModelError)
             return;
@@ -1273,7 +816,6 @@ export async function doClaudeTuiStream(opts) {
             killProc('SIGTERM');
         }, CLAUDE_TUI_MODEL_ERROR_SETTLE_MS);
     };
-    // Simulated streaming. See TuiStreamBuffer / applyAssistantStreaming above.
     const streamBuf = makeTuiStreamBuffer();
     const scheduleStreamTick = () => {
         if (streamBuf.timer)
@@ -1290,7 +832,6 @@ export async function doClaudeTuiStream(opts) {
             streamBuf.displayedLen = next;
             s.text = streamBuf.trueText.slice(0, next);
             emit();
-            // Keep ticking until we catch up — or until flushStream cancels us.
             if (streamBuf.displayedLen < streamBuf.trueText.length)
                 scheduleStreamTick();
         }, TUI_STREAM_CHUNK_INTERVAL_MS);
@@ -1306,9 +847,6 @@ export async function doClaudeTuiStream(opts) {
             emit();
         }
     };
-    // 6. Spawn the TUI under PTY. (node-pty itself was already loaded at step
-    // 0 — see the top of this function. By the time we reach this point the
-    // module is guaranteed to be importable and `spawn-helper` is executable.)
     const spawnEnv = { TERM: 'xterm-256color' };
     for (const [k, v] of Object.entries(process.env)) {
         if (typeof v === 'string')
@@ -1318,25 +856,11 @@ export async function doClaudeTuiStream(opts) {
         if (typeof v === 'string')
             spawnEnv[k] = v;
     }
-    // Strip the session-context markers a parent claude process exports to its
-    // subprocesses (CLAUDECODE, CLAUDE_CODE_CHILD_SESSION, …). Inherited e.g.
-    // when an agent restarted the pikiloom daemon from inside a Claude Code
-    // session, they flip this spawn into child-session mode — the transcript
-    // JSONL (our only text source) is then never written locally and the turn
-    // streams nothing. See CLAUDE_SESSION_CONTEXT_ENV_KEYS in claude.ts.
     scrubClaudeSessionContextEnv(spawnEnv);
-    // Critical: leaving ANTHROPIC_API_KEY set would route TUI through API
-    // billing too, defeating the whole point. Strip it unless the user
-    // explicitly opts back in.
     if (process.env.PIKILOOM_CLAUDE_TUI_KEEP_API_KEY !== '1') {
         delete spawnEnv.ANTHROPIC_API_KEY;
         delete spawnEnv.ANTHROPIC_AUTH_TOKEN;
     }
-    // Resolve `claude` to an absolute path. node-pty's `posix_spawnp` does not
-    // reliably honour PATH on macOS when the lookup happens inside an embedded
-    // libuv worker — passing the absolute path sidesteps cryptic
-    // "posix_spawnp failed" errors. Falls back to the bare name (let
-    // posix_spawnp try) when `which` can't resolve it.
     const claudeBin = whichSync('claude') || 'claude';
     agentLog(`[claude-tui] spawning ${claudeBin} TUI session=${activeSessionId} model=${model || '(default)'} prompt=${fullPrompt.length}ch resume=${isResume} fork=${isFork}`);
     try {
@@ -1349,10 +873,6 @@ export async function doClaudeTuiStream(opts) {
         });
     }
     catch (e) {
-        // Throw rather than return an error result — pty.spawn failures (PTY
-        // allocation refused in sandboxed CI / Docker without /dev/ptmx, etc.)
-        // mean TUI can't run at all, so the dispatcher should fall back to
-        // print mode. Clean up the temp scaffolding before bailing.
         try {
             fs.rmSync(workDir, { recursive: true, force: true });
         }
@@ -1361,38 +881,14 @@ export async function doClaudeTuiStream(opts) {
     }
     agentLog(`[claude-tui] pid=${proc.pid}`);
     const dbg = process.env.PIKILOOM_CLAUDE_TUI_DEBUG === '1';
-    /** Wall-clock of the last raw PTY byte — stall watchdog fast-path signal. */
     let lastPtyDataAt = Date.now();
-    // Startup-dialog auto-answer. Claude's TUI can paint a blocking "Bypass
-    // Permissions mode" confirmation before it accepts our positional prompt
-    // (default highlight = "No, exit"). We keep a bounded ANSI-stripped tail of
-    // the screen, detect that dialog (see detectClaudeBypassPrompt), and select
-    // "Yes, I accept" so the turn never stalls on a pre-prompt.
     const SCREEN_TAIL_MAX = 8192;
     const BYPASS_ACCEPT_MAX_ATTEMPTS = 3;
-    // Settle delay after the dialog first paints before we send any key. Claude's
-    // Ink select drops input aimed at it during the first frames — sending the
-    // digit too early is a no-op. ~500ms is comfortably past readiness in repro.
     const BYPASS_SETTLE_MS = 500;
-    // Gap between the selection key and the confirm Enter. Claude's Ink select
-    // swallows a combined "2\r" (only the digit lands; the Enter is dropped before
-    // the highlight repaints), so the two keystrokes must be split in time —
-    // 600ms is what reproduces reliably against the live 2.1.168 dialog.
     const BYPASS_CONFIRM_DELAY_MS = 600;
-    // How long after the last bypass-dialog repaint we still treat it as on
-    // screen — suppresses the blind prompt-submit Enter nudge across the whole
-    // select→confirm sequence so a stray CR can't land on "No, exit".
     const BYPASS_DIALOG_ACTIVE_WINDOW_MS = 2000;
-    // Mid-turn permission-prompt auto-answer (see detectClaudeProceedPrompt).
-    // Same Ink-select timing as the bypass dialog: settle past the frames where
-    // input is dropped, send the digit, then a split-out Enter to confirm. Unlike
-    // the bypass dialog (fires once at startup), `ask`-rule prompts recur — one
-    // per gated command — so we re-arm after each answer instead of capping at a
-    // few total attempts. PROCEED_ANSWER_MAX is only a runaway backstop.
     const PROCEED_SETTLE_MS = 500;
     const PROCEED_CONFIRM_DELAY_MS = 600;
-    // After confirming, wait before re-arming so a stale dialog frame can't drive
-    // a double "1\r"; a genuine next prompt always trails its command by longer.
     const PROCEED_REARM_MS = 1000;
     const PROCEED_ANSWER_MAX = 40;
     let screenTail = '';
@@ -1402,11 +898,6 @@ export async function doClaudeTuiStream(opts) {
     let proceedAnswerCount = 0;
     let proceedPhase = 'idle';
     proc.onData((data) => {
-        // We deliberately do not parse the TUI screen output. The JSONL is the
-        // canonical source of structured events. Stash bytes only when debugging.
-        // Raw byte arrival doubles as the cheapest liveness signal: a healthy TUI
-        // repaints continuously mid-turn, so PTY silence = event loop dead — feeds
-        // the stall watchdog's fast path (decideClaudeTuiStall.lastPtyDataAt).
         lastPtyDataAt = Date.now();
         if (dbg) {
             try {
@@ -1414,22 +905,12 @@ export async function doClaudeTuiStream(opts) {
             }
             catch { }
         }
-        // Auto-answer the bypass-permissions confirmation. Detect it the moment it
-        // paints (off the raw PTY, not the 200ms poll tick) and arm a short timed
-        // keystroke sequence. Keep a bounded stripped tail across chunks so a dialog
-        // split across reads still matches.
         screenTail = (screenTail + stripAnsiEscapes(data)).slice(-SCREEN_TAIL_MAX);
         if (detectClaudeBypassPrompt(screenTail)) {
             bypassPromptLastSeenAt = Date.now();
             if (bypassPhase === 'idle' && bypassAcceptAttempts < BYPASS_ACCEPT_MAX_ATTEMPTS) {
                 bypassAcceptAttempts++;
                 bypassPhase = 'armed';
-                // Three timed steps — verified 3/3 against the live 2.1.168 dialog:
-                //   settle (dialog ignores input on its first frames)
-                //   → "2"  (jumps to the second option "Yes, I accept"; idempotent —
-                //           re-sending can't overshoot a 2-option menu onto "No, exit")
-                //   → Enter (confirms; must arrive *after* the highlight repaints — a
-                //            combined "2\r" gets swallowed, only the digit lands).
                 agentLog(`[claude-tui] bypass-permissions prompt — auto-accepting "Yes, I accept" (attempt ${bypassAcceptAttempts}/${BYPASS_ACCEPT_MAX_ATTEMPTS})`);
                 setTimeout(() => {
                     if (processExited)
@@ -1447,13 +928,6 @@ export async function doClaudeTuiStream(opts) {
                         catch { }
                         bypassPhase = 'confirmed';
                         agentLog('[claude-tui] bypass-permissions — confirm Enter sent');
-                        // Drop the buffered dialog frame: the post-accept REPL output can be
-                        // tiny (e.g. a "Not logged in" line), so the old dialog text would
-                        // otherwise linger in the 8192-char tail and make the re-arm below
-                        // re-fire on a stale screen — typing "2"/Enter into the live prompt.
-                        // Clearing means the re-arm only sees output that arrives *after*
-                        // the confirm, so it re-fires only on a genuine repaint of the
-                        // dialog (accept didn't take), never on stale bytes.
                         screenTail = '';
                         setTimeout(() => {
                             if (!processExited && detectClaudeBypassPrompt(screenTail))
@@ -1463,11 +937,6 @@ export async function doClaudeTuiStream(opts) {
                 }, BYPASS_SETTLE_MS);
             }
         }
-        // Auto-answer a *mid-turn* permission confirmation. `else if` so the startup bypass dialog
-        // (handled above) never falls through here. The affirmative key comes from the classifier, not
-        // a hard-coded "1": confirm-prompt → "1. Yes", (y/n) → "y". (plan-approval carries no key under
-        // the current policy, so it is not auto-answered here.) These recur (one per ask-gated command),
-        // so we re-arm after each answer rather than cap total attempts.
         else {
             const screenInfo = classifyClaudeScreen(screenTail);
             if (screenInfo.state === 'confirm-prompt' && screenInfo.affirmativeKey
@@ -1483,13 +952,6 @@ export async function doClaudeTuiStream(opts) {
                 });
             }
         }
-        // Capture stderr-ish bytes (TUI startup errors, "claude: command not
-        // found"-style messages) for the final error payload when the run aborts
-        // before any JSONL is written. Strip ANSI on the way in — otherwise the
-        // raw PTY screen (cursor positions, SGR colours, column-aligned reply
-        // rendering) leaks into IM as gibberish like "[3G你把 [8Gsnipe …" when a
-        // user hits Stop before the JSONL has flushed any assistant text. Keep
-        // the buffer bounded after stripping.
         if (stderrCapture.length < 4096) {
             stderrCapture += stripAnsiEscapes(data);
             if (stderrCapture.length > 4096)
@@ -1498,15 +960,10 @@ export async function doClaudeTuiStream(opts) {
             if (notice)
                 noteTerminalLimitNotice(notice);
         }
-        // Selected-model-unavailable notice — see noteTerminalModelError. The TUI
-        // only paints this to the screen (no JSONL, no Stop hook), so the live
-        // screen tail is the sole signal. detectClaudeModelError is whitespace-
-        // insensitive so it survives the TUI's char-by-char paint.
         if (!terminalModelError && detectClaudeModelError(screenTail)) {
             noteTerminalModelError(claudeModelErrorMessage(s.model || opts.claudeModel || null));
         }
     });
-    // 7. Abort handling.
     const abortStream = () => {
         if (interrupted || processExited)
             return;
@@ -1518,7 +975,6 @@ export async function doClaudeTuiStream(opts) {
     if (opts.abortSignal?.aborted)
         abortStream();
     opts.abortSignal?.addEventListener('abort', abortStream, { once: true });
-    // 8. Hard deadline timer.
     const hardTimer = setTimeout(() => {
         if (processExited)
             return;
@@ -1527,75 +983,32 @@ export async function doClaudeTuiStream(opts) {
         agentWarn(`[claude-tui] hard deadline reached (${opts.timeout}s) pid=${proc.pid}`);
         killProc('SIGTERM');
     }, opts.timeout * 1000 + AGENT_STREAM_HARD_KILL_GRACE_MS);
-    // 9. Poll loop — hook state + JSONL tail.
     const POLL_INTERVAL_MS = 200;
-    // After Stop hook fires we give the JSONL ~600ms to settle (matches the
-    // print-mode driver's graceful-abort observation window) so the assistant's
-    // final event lands before we SIGTERM.
     const POST_STOP_DRAIN_MS = 600;
-    // Fallback Enter — most Claude versions auto-submit a positional prompt in
-    // TUI mode, but if UserPromptSubmit hasn't fired by this deadline we type a
-    // carriage return into the PTY in case the prompt is sitting on the input
-    // line waiting for it.
     const PROMPT_SUBMIT_NUDGE_MS = 1500;
-    // After the stall chokepoint fires its affirmative keystroke at a stuck dialog, give the dialog
-    // this long to clear before deciding it's unanswerable. Generous enough to also cover the
-    // in-flight onData answer cycle (settle + confirm + re-arm) so a chained next-prompt isn't
-    // mistaken for a failed answer; short enough that we never re-wait the full 3-min quiet window.
     const CHOKEPOINT_ANSWER_GRACE_MS = 5000;
     let promptNudged = false;
     let pollHandle = null;
     let drainScheduled = false;
-    // Wall-clock of the last parsed main-JSONL line. Feeds the stale-Stop
-    // quiet-window check in decideClaudeTuiStop — sidecar / hook traffic is
-    // deliberately excluded (only main-JSONL activity signals a model segment).
     let lastMainJsonlEventAt = start;
-    // Last pending-background count we logged, so the waiting state logs on
-    // transitions instead of every 200ms poll tick.
     let lastLoggedPendingBg = -1;
-    // Stall-watchdog liveness signals. Together with lastMainJsonlEventAt they
-    // answer "is the claude process still doing anything at all?" — see
-    // decideClaudeTuiStall for why this exists (claude CLI mid-turn freeze).
     let lastToolEventAt = start;
     let lastSidecarEventAt = 0;
-    // Last non-synthetic assistant JSONL event — substantive-progress signal
-    // for the limit-notice arbitration (resolveClaudeTuiLimitOutcome). Distinct
-    // from lastMainJsonlEventAt, which also counts bookkeeping lines (mode,
-    // last-prompt, …) that land right after submit and prove nothing.
     let lastAssistantEventAt = 0;
     let stallKilled = false;
-    // Chokepoint answer-retry: when the watchdog is about to fire on a confirm dialog, send the
-    // affirmative key ONCE against the now-stable (3-min-quiet, fully-painted) screen — the in-flight
-    // onData answer only fires while bytes arrive, so a dialog that paints once then goes silent never
-    // gets a second attempt (the diagnostics showed full-match prompts killed with answer-count 1).
-    // `stallAnswerSentAt` arms a bounded grace check: if the dialog hasn't cleared by then, terminate
-    // without auto-resuming (re-running would just re-paint the same dialog).
     let stallAnswerTried = false;
     let stallAnswerSentAt = 0;
-    // Stall diagnostics (capture-only) — see writeStallDiag.
     let observedClaudeVersion = '';
     let lastMainJsonlType = '';
     let lastStallDiagHeartbeatAt = 0;
     let stallDiagWentQuiet = false;
     let stallDiagMaxQuietMs = 0;
     let stallDiagPtyAliveWhileQuiet = false;
-    /** Last state.stoppedAt for which pendingHookToolIds was reconciled. */
     let lastClearedStopAt = 0;
-    /** Hook-reported tools still executing: PreToolUse seen, no PostToolUse. */
     const pendingHookToolIds = new Set();
-    /** Subset of pendingHookToolIds that are `im_ask_user` calls — the turn is
-     *  intentionally blocked on the user's reply (the /ask-user callback never
-     *  times out), so the stall watchdog must stay disarmed while any are in
-     *  flight. Cleared by the answer (PostToolUse) or the turn ending (Stop). */
     const pendingAskUserToolIds = new Set();
-    /** Edge-logged so the "watchdog disarmed" line fires on transitions only. */
     let loggedAwaitingUser = false;
-    // Incremental main-JSONL drain — the canonical text/thinking/usage feed.
-    // Used by both the 200ms poll tick and the post-exit final drain. Returns
-    // true when any line was consumed so callers can emit().
     const drainMainJsonl = () => {
-        // No existsSync guard: readJsonlIncrement returns no lines (offset unchanged)
-        // for a missing file, so the guard was a redundant extra syscall every tick.
         const inc = readJsonlIncrement(activeJsonlPath, jsonlReadOffset);
         jsonlReadOffset = inc.offset;
         let touched = false;
@@ -1611,16 +1024,10 @@ export async function doClaudeTuiStream(opts) {
             catch {
                 continue;
             }
-            // Ignore sub-agent sidecar events — they belong to a child agent's
-            // stream and would re-enter the parent's accumulator. claudeParse's
-            // own sub-agent routing handles them.
             const isSubAgentEvent = typeof ev.parent_tool_use_id === 'string' && ev.parent_tool_use_id;
             if (!isSubAgentEvent && ev.type === 'assistant') {
                 const notice = detectClaudeTuiTerminalLimitNotice(ev.message);
                 if (notice) {
-                    // A synthetic limit banner is not substantive progress — skip the
-                    // liveness/type bookkeeping below so the limit arbitration and the
-                    // stall watchdog don't mistake it for a live model segment.
                     noteTerminalLimitNotice(notice);
                     touched = true;
                     continue;
@@ -1648,11 +1055,6 @@ export async function doClaudeTuiStream(opts) {
         }
         return touched;
     };
-    // Append-only tool-events log fed by PreToolUse / PostToolUse hooks. We
-    // tail it with the same incremental reader the JSONL transcript uses. Hook
-    // events usually beat their JSONL counterpart by a second or so (and
-    // PreToolUse fires before the tool even runs); whichever feed arrives first
-    // wins, the other dedups via seenClaudeToolIds / seenClaudeToolResultIds.
     let toolEventsReadOffset = 0;
     const drainToolEvents = () => {
         const inc = readJsonlIncrement(toolEventsPath, toolEventsReadOffset);
@@ -1669,17 +1071,11 @@ export async function doClaudeTuiStream(opts) {
             catch {
                 continue;
             }
-            // Stall-watchdog bookkeeping: any hook event is proof of life, and the
-            // Pre/Post pairing tells the watchdog whether a tool is mid-execution
-            // (which extends the stall threshold — long foreground commands are
-            // legitimately silent).
             lastToolEventAt = Date.now();
             const hookToolId = typeof ev?.tool_use_id === 'string' ? ev.tool_use_id : '';
             if (hookToolId) {
                 if (ev?.event === 'PreToolUse') {
                     pendingHookToolIds.add(hookToolId);
-                    // im_ask_user blocks the turn on the user — track it separately so the
-                    // stall watchdog can tell an intentional question-wait from a freeze.
                     if (isAskUserToolName(ev?.tool_name))
                         pendingAskUserToolIds.add(hookToolId);
                 }
@@ -1688,11 +1084,6 @@ export async function doClaudeTuiStream(opts) {
                     pendingAskUserToolIds.delete(hookToolId);
                 }
             }
-            // A Task PreToolUse and the first sub-agent tool PreToolUse can land in
-            // the same tick batch. If the sub-agent's hook arrives before we've
-            // discovered its sidecar (and thus before s.subAgentIdToParent knows
-            // its agent_id), refresh discovery so the hook resolves its parent on
-            // this pass instead of leaking through unattributed.
             const subAgentId = typeof ev?.agent_id === 'string' ? ev.agent_id : '';
             if (subAgentId && !s.subAgentIdToParent?.has(subAgentId))
                 tryDiscoverSubAgents();
@@ -1734,25 +1125,15 @@ export async function doClaudeTuiStream(opts) {
             const parentToolUseId = typeof meta?.toolUseId === 'string' ? meta.toolUseId : '';
             if (!parentToolUseId)
                 continue;
-            // Only start tailing once the parent Task tool_use has been registered
-            // in s.subAgents — otherwise routeClaudeSubAgentEvent silently drops
-            // every event because it can't find the parent.
             if (!s.subAgents.has(parentToolUseId))
                 continue;
             const sidecarPath = path.join(sidecarDir, `${stem}.jsonl`);
             trackedSubAgents.set(stem, { sidecarPath, offset: 0, parentToolUseId });
-            // `stem` is "agent-<id>"; Claude Code's hook payload `agent_id` carries
-            // just the raw id. Keep both keys so applyHookToolEvent can attribute
-            // sub-agent tool hooks to the parent's Task tool_use no matter which
-            // form arrives.
             const rawAgentId = stem.startsWith('agent-') ? stem.slice('agent-'.length) : stem;
             if (!s.subAgentIdToParent)
                 s.subAgentIdToParent = new Map();
             s.subAgentIdToParent.set(rawAgentId, parentToolUseId);
             s.subAgentIdToParent.set(stem, parentToolUseId);
-            // <task-notification> events identify background tasks by this raw id
-            // (and only sometimes carry <tool-use-id>) — keep the mapping so
-            // applyClaudeTaskNotification can resolve them either way.
             if (!s.bgTaskIdToToolUse)
                 s.bgTaskIdToToolUse = new Map();
             s.bgTaskIdToToolUse.set(rawAgentId, parentToolUseId);
@@ -1775,8 +1156,6 @@ export async function doClaudeTuiStream(opts) {
                 catch {
                     continue;
                 }
-                // Inject parent_tool_use_id so claudeParse routes via routeClaudeSubAgentEvent
-                // → updates sub.model + sub.tools on the existing s.subAgents entry.
                 const injected = { ...ev, parent_tool_use_id: tail.parentToolUseId };
                 try {
                     callClaudeParseForTui(injected, s);
@@ -1787,15 +1166,10 @@ export async function doClaudeTuiStream(opts) {
                 any = true;
             }
         }
-        // Stall-watchdog: live sub-agents count as turn progress even while the
-        // parent thread is quietly waiting on them.
         if (any)
             lastSidecarEventAt = Date.now();
         return any;
     };
-    // End a turn that is blocked on a confirm/select dialog the auto-answer could not clear. Unlike a
-    // 'stalled' kill this does NOT auto-resume — re-running the prompt just re-paints the same dialog
-    // (the loop the user kept seeing). The session is intact; the user re-sends to continue.
     const terminatePromptUnanswered = (screenState, sample) => {
         stallKilled = true;
         const nowMs = Date.now();
@@ -1829,14 +1203,11 @@ export async function doClaudeTuiStream(opts) {
             }
             return;
         }
-        // Hook state — pick up real session id / transcript path.
         const state = readHookState(statePath);
         if (state.sessionId && state.sessionId !== activeSessionId) {
             const prevId = activeSessionId;
             activeSessionId = state.sessionId;
             activeJsonlPath = state.transcriptPath || path.join(projectDir, `${activeSessionId}.jsonl`);
-            // For forks Claude rotates to a fresh UUID — start reading the new file
-            // from offset 0 since we haven't read any of it yet.
             if (!isResume)
                 jsonlReadOffset = 0;
             emitSessionIdUpdate(s, activeSessionId);
@@ -1845,11 +1216,6 @@ export async function doClaudeTuiStream(opts) {
         else if (state.transcriptPath && state.transcriptPath !== activeJsonlPath) {
             activeJsonlPath = state.transcriptPath;
         }
-        // Submit nudge — only if UserPromptSubmit hook hasn't fired yet. Suppress
-        // it while the bypass-permissions dialog is (or was just) on screen: a blind
-        // CR there lands on the default "No, exit" and kills the session. The dialog
-        // auto-answer in onData drives that screen instead; once it clears the
-        // prompt submits on its own (or this nudge fires on a later tick).
         const bypassDialogActive = bypassPromptLastSeenAt > 0
             && Date.now() - bypassPromptLastSeenAt < BYPASS_DIALOG_ACTIVE_WINDOW_MS;
         if (!promptNudged && !state.promptSubmittedAt && !bypassDialogActive
@@ -1861,52 +1227,23 @@ export async function doClaudeTuiStream(opts) {
             catch { }
             agentLog(`[claude-tui] prompt-submit nudge sent (no UserPromptSubmit after ${PROMPT_SUBMIT_NUDGE_MS}ms)`);
         }
-        // JSONL tail.
         if (drainMainJsonl()) {
-            // Emit immediately so non-text changes (tool_use, plan, activity,
-            // thinking, usage) reach the dashboard without waiting for the
-            // chunked stream tick. The streaming timer separately advances
-            // s.text from the buffer over the next few ticks.
             emit();
             scheduleStreamTick();
         }
-        // Live tool-events stream — fed by Pre/PostToolUse hooks. Hook and JSONL
-        // feeds race per tool call; both record into seenClaudeToolIds /
-        // seenClaudeToolResultIds so whichever lands first wins and the other
-        // pass dedups naturally.
         if (drainToolEvents())
             emit();
-        // Sub-agent sidecar discovery + pump. Order matters: discovery first so a
-        // newly-spawned sub-agent gets registered for tailing this same tick if
-        // its events have already been written. Skip the readdir + per-meta reads
-        // until a Task tool_use is actually registered — discovery can't succeed
-        // before then anyway (it requires the parent in s.subAgents), so the common
-        // no-subagent turn would otherwise readdir the sidecar dir every 200ms for
-        // nothing.
         if (s.subAgents.size > 0)
             tryDiscoverSubAgents();
         if (pumpSubAgentSidecars())
             emit();
-        // Stop hook handling. A Stop is NOT automatically the end of the turn:
-        // Claude fires it per response segment, including the segment that merely
-        // *launched* run_in_background agents. Those agents run inside the claude
-        // process — terminating here would destroy them (the "进程退出把子代理
-        // 打断" incident). Hold the PTY open until every launched background agent
-        // has reported its <task-notification> AND the latest Stop is fresher than
-        // the latest notification (i.e. the model's wrap-up segment finished).
         if (state.stoppedAt && !stopHookFired) {
-            // A fired Stop means no foreground tool is genuinely mid-flight any
-            // more. Surviving entries in pendingHookToolIds are lost PostToolUse
-            // hook events (MCP flap / hook timeout ate them) — clearing here stops
-            // them from silently pushing the stall watchdog onto the 30-minute
-            // pending-tool threshold for the rest of the turn.
             if (state.stoppedAt !== lastClearedStopAt) {
                 lastClearedStopAt = state.stoppedAt;
                 if (pendingHookToolIds.size) {
                     agentWarn(`[claude-tui] Stop fired with ${pendingHookToolIds.size} unmatched PreToolUse event(s) — clearing (lost PostToolUse hooks)`);
                     pendingHookToolIds.clear();
                 }
-                // A fired Stop ends the turn — any tracked ask-user is moot.
                 pendingAskUserToolIds.clear();
             }
             const pendingBg = pendingClaudeBackgroundAgentCount(s);
@@ -1916,9 +1253,6 @@ export async function doClaudeTuiStream(opts) {
                 lastTaskNotificationAt: s.lastTaskNotificationAt || 0,
                 lastJsonlEventAt: lastMainJsonlEventAt,
                 lastHookOrSidecarEventAt: Math.max(lastToolEventAt, lastSidecarEventAt),
-                // Background *Bash* is silent by nature (no sidecar/hook traffic while
-                // it runs) — give it the long pending-tool budget; agent-only holds
-                // keep the default TTL (live agents emit sidecar events constantly).
                 holdQuietTtlMs: pendingClaudeBackgroundBashCount(s) > 0
                     ? CLAUDE_TUI_STALL_PENDING_TOOL_MS
                     : undefined,
@@ -1928,7 +1262,6 @@ export async function doClaudeTuiStream(opts) {
                 stopHookFired = true;
                 stopHookSeenAt = Date.now();
                 if (pendingBg > 0) {
-                    // 幽灵 hold 释放:计数说还有后台 agent,但所有通道静默已超 TTL。
                     agentWarn(`[claude-tui] releasing phantom hold — ${pendingBg} background agent(s) still counted pending but every channel quiet past TTL; treating Stop as final`);
                 }
                 agentLog(`[claude-tui] Stop hook fired — draining JSONL for ${POST_STOP_DRAIN_MS}ms before SIGTERM`);
@@ -1945,34 +1278,12 @@ export async function doClaudeTuiStream(opts) {
             drainScheduled = true;
             agentLog(`[claude-tui] drain complete, terminating TUI pid=${proc.pid}`);
             killProc('SIGTERM');
-            // Continue polling so any post-Stop JSONL writes still get parsed; the
-            // process will exit shortly and onExit will resolve the wait.
         }
-        // Stall watchdog. claude CLI can freeze mid-turn (observed on 2.1.160):
-        // a tool_result lands, then the next assistant segment never starts — the
-        // process stays alive, every signal goes quiet, no Stop hook ever fires.
-        // When ALL liveness signals have been silent past the threshold, declare
-        // the turn stalled and SIGTERM; doClaudeWithRetry auto-resumes the session
-        // once so the turn continues instead of spinning forever in the IM card.
         if (!stopHookFired && !timedOut && !interrupted && !stallKilled) {
             const lastProgressAt = Math.max(start, lastMainJsonlEventAt, lastToolEventAt, lastSidecarEventAt, state.stoppedAt || 0, state.promptSubmittedAt || 0);
-            // Pending background work (agents + bash) extends the stall budget the
-            // same way a pending foreground tool does: a silent 15-minute background
-            // build must not get shot by the 10-minute quiet threshold. The PTY
-            // fast path still catches true process freezes within minutes.
             const pendingBgForStall = pendingClaudeBackgroundAgentCount(s);
-            // PTY fast path is for *mid-turn* freezes only. While the TUI idles in a
-            // post-Stop background hold it legitimately paints nothing — a static
-            // screen there is healthy, not frozen. Stop being the freshest signal is
-            // exactly that hold state → disarm the fast path (0 = unavailable).
             const nonStopProgressAt = Math.max(start, lastMainJsonlEventAt, lastToolEventAt, lastSidecarEventAt, state.promptSubmittedAt || 0);
             const inPostStopHold = !!state.stoppedAt && state.stoppedAt >= nonStopProgressAt;
-            // An im_ask_user call is in flight → the turn is blocked on the user's
-            // reply, not frozen (the /ask-user callback never times out). Disarm the
-            // stall watchdog AND the freeze diagnostics until the user answers
-            // (PostToolUse clears the id). Otherwise the quiet wait trips
-            // decideClaudeTuiStall, classifies 'unknown', and gets SIGTERMed +
-            // mislabelled a "CLI freeze" — the last-question hang the user reported.
             const awaitingUserReply = pendingAskUserToolIds.size > 0;
             if (awaitingUserReply !== loggedAwaitingUser) {
                 loggedAwaitingUser = awaitingUserReply;
@@ -1980,11 +1291,6 @@ export async function doClaudeTuiStream(opts) {
                     agentLog(`[claude-tui] im_ask_user in flight — stall watchdog disarmed until the user replies pid=${proc.pid}`);
                 }
             }
-            // Chokepoint answer-retry grace. We sent the affirmative key at a stuck dialog; give it time
-            // to clear. If the screen is no longer a blocking dialog, the answer took — disarm and re-arm
-            // so a later prompt in the same turn can also get a chokepoint retry. If it is STILL a dialog
-            // (and the in-flight onData answer didn't clear it either), it is genuinely unanswerable —
-            // end without auto-resume.
             if (stallAnswerSentAt > 0 && Date.now() - stallAnswerSentAt > CHOKEPOINT_ANSWER_GRACE_MS) {
                 const after = classifyClaudeScreen(screenTail);
                 const stillBlocking = after.state === 'confirm-prompt'
@@ -1998,8 +1304,6 @@ export async function doClaudeTuiStream(opts) {
                     stallAnswerTried = false;
                 }
             }
-            // Stall diagnostics: sample the quiet lead-up so the watchdog can later be
-            // tuned from data. Capture-only — changes no control flow.
             if (!stallKilled) {
                 const nowMs = Date.now();
                 const quietMs = nowMs - lastProgressAt;
@@ -2008,15 +1312,10 @@ export async function doClaudeTuiStream(opts) {
                     stallDiagWentQuiet = true;
                     if (quietMs > stallDiagMaxQuietMs)
                         stallDiagMaxQuietMs = quietMs;
-                    // PTY still painting while every structured signal is silent = the
-                    // frozen-stream-behind-a-live-spinner case that defeats the fast path.
                     if (ptyQuietMs < CLAUDE_TUI_STALL_PTY_DEAD_MS)
                         stallDiagPtyAliveWhileQuiet = true;
                     if (nowMs - lastStallDiagHeartbeatAt >= STALL_DIAG_HEARTBEAT_INTERVAL_MS) {
                         lastStallDiagHeartbeatAt = nowMs;
-                        // Snapshot the screen so a quiet stretch can later be classified as a frozen stream vs
-                        // a long think vs a blocking dialog vs an idle hold. Record the full screenState (not
-                        // just looksLikePrompt) so the lead-up to a kill is measurable as claude versions churn.
                         const screenInfo = classifyClaudeScreen(screenTail);
                         const looksLikePrompt = screenInfo.state === 'confirm-prompt'
                             || screenInfo.state === 'plan-approval' || screenInfo.state === 'bypass-startup';
@@ -2053,8 +1352,6 @@ export async function doClaudeTuiStream(opts) {
                 if (stallDecision === 'stall') {
                     const quietMin = Math.round((Date.now() - lastProgressAt) / 60_000);
                     const ptyQuietS = Math.round((Date.now() - lastPtyDataAt) / 1000);
-                    // The screen is ground truth. Classify it, then map to an action — the chokepoint the
-                    // diagnostics proved was missing (the verdict used to change only the error string).
                     const screen = classifyClaudeScreen(screenTail);
                     const action = decideStallAction({
                         state: screen.state,
@@ -2064,8 +1361,6 @@ export async function doClaudeTuiStream(opts) {
                     });
                     const looksLikePrompt = screen.state === 'confirm-prompt'
                         || screen.state === 'plan-approval' || screen.state === 'bypass-startup';
-                    // Diagnostics oracle: record the screen state + chosen action on every kill-point so the
-                    // false-positive rate stays measurable as claude versions churn.
                     const writeStallRecord = () => writeStallDiag({
                         kind: 'stall', sessionId: activeSessionId, version: observedClaudeVersion, model: s.model || null,
                         elapsedTurnMs: Date.now() - start, quietMs: Date.now() - lastProgressAt, ptyQuietMs: Date.now() - lastPtyDataAt,
@@ -2074,18 +1369,12 @@ export async function doClaudeTuiStream(opts) {
                         looksLikePrompt, screenState: screen.state, action, screenSample: screen.sample,
                     });
                     if (action === 'answer-retry' && screen.affirmativeKey) {
-                        // #1 fix: the in-flight onData answer only fires while bytes arrive, so a dialog that
-                        // painted once then went byte-silent never got a retry (full-match prompts were killed
-                        // with answer-count 1). Send the affirmative key now against the stable, fully-painted
-                        // screen (no settle — quiet 3 min) and let the grace check decide the outcome. No kill.
                         stallAnswerTried = true;
                         stallAnswerSentAt = Date.now();
                         agentWarn(`[claude-tui] watchdog hit a ${screen.state} after ${quietMin}m quiet — auto-answering "${screen.affirmativeKey}" against the stable dialog (no kill yet) pid=${proc.pid}`);
                         sendConfirmAnswer(screen.affirmativeKey, 0, PROCEED_CONFIRM_DELAY_MS);
                     }
                     else if (action === 'terminate-clean') {
-                        // Idle REPL, nothing pending — the turn finished and we merely missed/held its Stop hook.
-                        // Hand off to the normal post-Stop drain: clean end, no 'stalled', no auto-resume.
                         writeStallRecord();
                         stopHookFired = true;
                         stopHookSeenAt = Date.now();
@@ -2096,8 +1385,6 @@ export async function doClaudeTuiStream(opts) {
                         terminatePromptUnanswered(screen.state, screen.sample);
                     }
                     else if (action === 'model-error') {
-                        // Selected model unavailable (banner painted to screen only — no JSONL, no Stop hook).
-                        // Surface the real reason; 'model_error' is non-retryable so we never resume into it.
                         stallKilled = true;
                         if (!terminalModelError)
                             terminalModelError = claudeModelErrorMessage(s.model || opts.claudeModel || null);
@@ -2112,9 +1399,6 @@ export async function doClaudeTuiStream(opts) {
                         killProc('SIGTERM');
                     }
                     else {
-                        // terminate-stalled: a genuine freeze candidate (state 'unknown') OR an idle hold with
-                        // pending background work we must not interrupt. Keep the self-healing SIGTERM-as-
-                        // 'stalled' path (auto-resumes once) with the existing model / limit arbitration.
                         stallKilled = true;
                         s.stopReason = 'stalled';
                         writeStallRecord();
@@ -2149,15 +1433,12 @@ export async function doClaudeTuiStream(opts) {
                         emit();
                         killProc('SIGTERM');
                     }
-                    // Keep polling: onExit resolves the wait and the final drains pick up
-                    // whatever the dying process flushes.
                 }
             }
         }
         pollHandle = setTimeout(tick, POLL_INTERVAL_MS);
     };
     pollHandle = setTimeout(tick, POLL_INTERVAL_MS);
-    // 10. Wait for process exit.
     await new Promise(resolve => {
         proc.onExit(({ exitCode: code, signal }) => {
             processExited = true;
@@ -2173,28 +1454,15 @@ export async function doClaudeTuiStream(opts) {
         });
     });
     opts.abortSignal?.removeEventListener('abort', abortStream);
-    // 11. Final drain — pick up anything written between the last poll and
-    // process exit. Claude flushes its remaining JSONL events on shutdown.
     if (drainMainJsonl())
         emit();
-    // Final tool-events drain — any PreToolUse / PostToolUse hooks that fired
-    // between the last poll tick and process exit.
     if (drainToolEvents())
         emit();
-    // Final sub-agent drain. The sub-agent's last events (closing tool_results)
-    // may have landed after our last poll tick; mirror the main JSONL drain to
-    // make sure sub.tools / sub.status carry the complete picture into the
-    // final result.
     if (s.subAgents.size > 0)
         tryDiscoverSubAgents();
     if (pumpSubAgentSidecars())
         emit();
-    // Process has exited and final drain is done — promote whatever is left in
-    // the stream buffer into `s.text` so the final result message carries the
-    // complete reply (not a truncated mid-stream prefix).
     flushStream();
-    // 12. Cleanup temp dir. Keep it around when debugging so users can inspect
-    // the captured PTY bytes + state file.
     if (!dbg) {
         try {
             fs.rmSync(workDir, { recursive: true, force: true });
@@ -2204,15 +1472,7 @@ export async function doClaudeTuiStream(opts) {
     else {
         agentLog(`[claude-tui] debug artifacts retained in ${workDir}`);
     }
-    // 13. Build the StreamResult — mirror the shape and semantics of
-    // doClaudeInteractiveStream so downstream consumers (finalizeStreamResult,
-    // dashboard rendering) cannot tell the two paths apart.
     const cleanStderr = stderrCapture.trim();
-    // Detect Claude Code's synthetic "API Error: …" assistant reply (e.g.
-    // 529 Overloaded). The text gets rewritten so the IM card doesn't surface
-    // the raw "API Error: Overloaded" string to the user, and stopReason is
-    // upgraded so the ClaudeDriver retry wrapper can decide to re-issue the
-    // turn rather than letting the synthetic failure stick.
     const apiErrorReason = detectClaudeApiError(s.text);
     if (apiErrorReason) {
         agentWarn(`[claude-tui] upstream API error detected: ${apiErrorReason}`);
@@ -2221,21 +1481,10 @@ export async function doClaudeTuiStream(opts) {
         if (!s.errors)
             s.errors = [`Anthropic API error: ${apiErrorReason}`];
     }
-    // Model-unavailable arbitration: the TUI painted the "selected model is
-    // unavailable" banner (noteTerminalModelError) and the turn produced nothing
-    // — no JSONL, no Stop hook. The early settle-timer's SIGTERM (or any exit)
-    // brought us here; surface the real reason instead of a bare "(no textual
-    // response)". stopReason 'model_error' is non-retryable (doClaudeWithRetry
-    // only auto-resumes 'stalled'), so we never loop on the same dead model.
     if (!interrupted && !s.errors && terminalModelError && !s.text.trim()) {
         s.stopReason = 'model_error';
         s.errors = [terminalModelError];
     }
-    // Limit-notice arbitration (see resolveClaudeTuiLimitOutcome). Covers the
-    // paths the stall watchdog never reaches: the TUI painted a limit banner,
-    // then Stop fired on an empty turn or the process exited — nothing
-    // substantive ever followed the banner, so the limit ate the turn. A banner
-    // followed by real output stays informational (already in the activity log).
     if (!interrupted && !timedOut && !s.errors) {
         const limitOutcome = resolveClaudeTuiLimitOutcome({
             noticeText: terminalLimitNotice,
@@ -2249,9 +1498,6 @@ export async function doClaudeTuiStream(opts) {
         }
     }
     const errorText = joinErrorMessages(s.errors);
-    // "ok" requires: process exited cleanly (or via our own SIGTERM after Stop
-    // hook fired, which yields a non-zero exit), no errors from the parser, no
-    // user abort, no timeout. SIGTERM-after-Stop is the normal happy path.
     const exitedViaStopHook = stopHookFired && !timedOut && !interrupted;
     const procOk = (exitCode === 0) || exitedViaStopHook;
     const ok = procOk && !s.errors && !timedOut && !interrupted && stopHookFired;
@@ -2265,10 +1511,6 @@ export async function doClaudeTuiStream(opts) {
     const incomplete = !ok || s.stopReason === 'max_tokens' || s.stopReason === 'timeout';
     const elapsedS = (Date.now() - start) / 1000;
     agentLog(`[claude-tui] result ok=${ok} elapsed=${elapsedS.toFixed(1)}s text=${s.text.length}ch thinking=${s.thinking.length}ch session=${s.sessionId || '?'} stop=${stopHookFired}`);
-    // Stall diagnostics: a turn that went quiet has now ended. Recording the
-    // outcome separates benign long-thinking/long-tool (completed) from true
-    // freezes the watchdog had to kill (stalled-killed) — the calibration the
-    // threshold tuning needs.
     if (stallDiagWentQuiet) {
         writeStallDiag({
             kind: 'resolved',
@@ -2288,15 +1530,6 @@ export async function doClaudeTuiStream(opts) {
             ok,
         });
     }
-    // Build the message body. Order:
-    //   1. Any assistant text captured from JSONL (the canonical reply).
-    //   2. Parser-surfaced errors.
-    //   3. For interrupted runs with no text yet, a clear status — never the
-    //      raw PTY scrape (it would be a half-rendered TUI screen with no value
-    //      to the user, and pre-ANSI-strip used to render as garbled gibberish
-    //      in IM).
-    //   4. Fall back to ANSI-stripped stderrCapture for genuine startup
-    //      failures like "claude: command not found".
     const messageBody = s.text.trim()
         || errorText
         || (interrupted ? '(Interrupted before any reply landed.)'