chore: version packages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,34 @@
 # aicodeman
 
+## 1.14.0
+
+### Minor Changes
+
+- Daemon mode and service install, plus subagent hook hardening and terminal/idle-checker fixes.
+
+  **New: run Codeman in the background without a terminal (#239, closes #231)**
+  - `codeman web -d` starts the server detached: it survives closing the shell, logs to `~/.codeman/web.log`, records a pidfile, and only reports success after the server actually answers `/api/status` (a port clash or missing dependency can never read as a clean start). `codeman web --status` and `codeman web --stop` manage it; `--stop` verifies the pid still looks like a Codeman server before signalling, so a recycled pid is never SIGTERMed.
+  - `codeman service install` / `status` / `uninstall`: installs a systemd user unit (Linux) or LaunchAgent (macOS) so the server comes back after reboots. The unit carries the installing shell's PATH (launchd's default PATH finds neither an nvm/Homebrew `node` nor `tmux`/`claude`), never contains `CODEMAN_PASSWORD`, and uses the same instance-scoped unit names as `install.sh` and the self-updater so no second copy can end up supervised.
+  - Both refuse to start a second server on one data dir (pidfile check plus a live probe): two servers on the shared tmux socket would attach to each other's sessions.
+  - Why `-d` exists at all: `nohup` does not protect a Node process, Node re-arms SIGHUP even when it inherits "ignore", so `nohup codeman web &` still dies on HUP. The detached relaunch (setsid) removes the controlling terminal instead.
+
+  **Subagent background-work hooks (#233, thanks @Lint111)**
+  - The background Bash rewake helper now also watches the top-level parent transcript when the hook fires inside a subagent: Claude records a subagent's Bash result in its own `subagents/agent-*.jsonl` but queues the completion in the lead session transcript, so subagents previously never woke. It can also inline a `CODEMAN_RESULT_BEGIN/END` marked report (up to 64 KiB) from the task output file into the wake feedback.
+  - New SubagentStop guard: a subagent that still owns live Monitor or background Bash processes is kept working instead of publishing an intermediate progress line as its final report. Ownership is verified against live process descriptors on `tasks/<id>.output`, so stale transcript text alone never blocks, and the guard fails open on systems without `/proc`.
+  - Existing cases self-heal to the new hooks on next launch.
+
+  **AI idle checker: stderr kept out of the verdict (#234, thanks @Lint111)**
+
+  The `claude -p` verdict command no longer merges stderr into the verdict file, where CLI warnings could turn a valid verdict into a parse error. On failures, the first 200 chars of stderr are attached to the diagnostic instead.
+
+  **Terminal: large final batches drain fully (#235, thanks @Lint111)**
+
+  A render-scheduling flag was cleared after the flush instead of before it, so when a large batch left a remainder behind, the remainder stayed unrendered until unrelated output arrived. This looked like truncated responses or shell commands that never finish. The flush now reschedules itself until the queue is empty.
+
+  **Docs and tests**
+  - README documents daemon mode and service install.
+  - Unique test port for the daemon-control suite.
+
 ## 1.13.0
 
 ### Minor Changes

CLAUDE.md

@@ -74,7 +74,7 @@ When user says "COM":
 
 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.
 
-**Version**: 1.13.0 (must match `package.json`)
+**Version**: 1.14.0 (must match `package.json`)
 
 ## Project Overview
 

README.md

@@ -240,6 +240,8 @@ codeman web                       # localhost:3000 (loopback only — safe defau
 codeman web --port 8080           # custom port (or set CODEMAN_PORT)
 codeman web --https               # self-signed TLS (only needed for remote access)
 codeman web -H 0.0.0.0            # bind LAN — REQUIRES CODEMAN_PASSWORD (see Security)
+codeman web -d                    # detach: survives closing the shell (--status, --stop)
+codeman service install           # systemd/launchd service: comes back after reboots
 ```
 
 Open the printed URL. The page is a single dashboard; everything below happens there.
@@ -288,6 +290,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 ### 7. Operate & maintain
 
 - **App Settings** — model, effort, permission startup mode, theme/skin, notifications, display toggles, per-CLI options, a synced custom display name, and per-device English/Simplified Chinese UI language.
+- **Run it in the background** — `codeman web -d` detaches from your shell (`--status`, `--stop`); `codeman service install` makes it a systemd user unit / macOS LaunchAgent that survives reboots. Both verify the server actually answers before reporting success, and both refuse to start a second server on one data dir. See [Keep it running in the background](#quick-start---installation).
 - **Self-update** — git-clone installs update in place from **Settings → Updates**.
 - **Deploy your own changes** — see [Development](#development).
 
@@ -423,6 +426,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 
 ## More Features
 
+- **Background daemon & service install** — `codeman web -d` runs the server detached with a pidfile, `~/.codeman/web.log`, and verified startup (it polls the server until it answers, so a port clash never reads as success); `codeman service install` writes a systemd user unit (Linux) or LaunchAgent (macOS) with your shell's PATH baked in, so an nvm or Homebrew `node`, `tmux` and `claude` are actually found. Secrets are never written into unit files
 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
 - **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
 - **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)

docs/claude-code-hooks-reference.md

@@ -149,9 +149,17 @@ to Claude as a system reminder. This implies `"async": true`; ordinary async
 hooks do not wake an idle turn, and their output waits for the next interaction.
 
 Codeman uses this on `PostToolUse(Bash)`: a self-contained Node helper extracts
-the background task ID from the Bash result, watches the session transcript for
-the matching completion notification, and exits 2. It does not send terminal
-input, so it cannot submit a user's partially written prompt.
+the background task ID from the Bash result, watches the originating transcript
+and, for subagents, the top-level parent transcript for the matching completion
+notification, and exits 2. Claude records a subagent's Bash result in its
+`subagents/agent-*.jsonl` file but queues completion in the lead session JSONL.
+The task ID keeps each wake targeted. The helper does not send terminal input,
+so it cannot submit a user's partially written prompt.
+
+For script-dispatched Codex work, `codex-run.sh` writes the final response
+between `CODEMAN_RESULT_BEGIN/END` markers in the background task output. The
+rewake helper includes a maximum of 64 KiB of that report in its feedback. UI
+subagent discovery and dispatcher result delivery are separate contracts.
 
 ### Notification
 
@@ -219,6 +227,16 @@ Or to allow exit:
 
 **Use Cases**: Control nested loops, verify subagent output.
 
+The hook input includes `agent_id`, `agent_transcript_path`, and
+`last_assistant_message`. Like `Stop`, a command hook can return
+`{"decision":"block","reason":"..."}` to keep the subagent running and feed
+the reason back to it.
+
+Codeman uses this to prevent premature reports from workers that still own live
+Monitor or background-Bash processes. It derives candidate task IDs from the
+subagent transcript, but requires a matching live Linux process descriptor for
+`tasks/<id>.output`; historical task text by itself is not treated as active.
+
 ### TeammateIdle
 
 **When**: When an agent-team teammate is about to go idle.

docs/terminal-anti-flicker.md

@@ -43,38 +43,22 @@ const syncData = DEC_SYNC_START + data + DEC_SYNC_END;
 this.broadcast('session:terminal', { id: sessionId, data: syncData });
 ```
 
-## Client-Side Implementation (`app.js`)
+## Client-Side Implementation (`terminal-ui.js`)
 
 ### `batchTerminalWrite(data)`
 
 1. Checks if flicker filter is enabled (optional, per-session)
 2. If flicker filter active: buffers screen-clear patterns (`ESC[2J`, `ESC[H ESC[J`, `ESC[nA`)
 3. Accumulates data in `pendingWrites`
-4. Schedules `requestAnimationFrame` if not already scheduled
-5. On rAF callback: checks for incomplete sync blocks (start without end)
-6. If incomplete: waits up to 50ms via `syncWaitTimeout`
-7. Calls `flushPendingWrites()` when complete
-
-### `extractSyncSegments(data)`
-
-- Parses DEC 2026 markers, returns array of content segments
-- Content before sync blocks returned as-is
-- Content inside sync blocks returned without markers
-- Incomplete blocks (start without end) returned with marker for next chunk
+4. Calls `_scheduleTerminalWriteFlush()` if no flush is pending
+5. The yielded callback clears its scheduled flag before calling `flushPendingWrites()`
+6. Large batches schedule their own next chunk until the queue is empty
 
 ### `flushPendingWrites()`
 
-```javascript
-const segments = extractSyncSegments(this.pendingWrites);
-this.pendingWrites = '';  // Clear before writing
-for (const segment of segments) {
-  if (segment && !segment.startsWith(DEC_SYNC_START)) {
-    terminal.write(segment);  // Skip incomplete blocks (start with marker)
-  }
-}
-```
-
-Note: Segments starting with `DEC_SYNC_START` are incomplete blocks awaiting more data. These are skipped (discarded if timeout forces flush).
+- Joins the queued terminal data and passes DEC 2026 markers through to xterm.js 6, which handles synchronized output natively.
+- Writes at most 32KB per yield for Codex and 64KB for other modes.
+- Requeues the remainder and immediately schedules another safe yield. A final large response therefore drains without waiting for another SSE event.
 
 ### `chunkedTerminalWrite(buffer, chunkSize=128KB)`
 
@@ -116,17 +100,15 @@ When detected, buffers 50ms of subsequent output before flushing atomically.
 
 ## Edge Cases
 
-- **Incomplete sync blocks**: 50ms timeout forces flush (content discarded to prevent freeze)
+- **Incomplete sync blocks**: xterm.js retains synchronized output until its closing marker
 - **Large buffers**: Chunked writing prevents UI freeze
 - **Server shutdown**: Skips batching via `_isStopping` flag
 - **Session switch**: Clears flicker filter state, pending writes, and sync timeout (prevents cross-session data bleed)
 - **SSE reconnect**: `handleInit()` clears all pending write state
 
-**Trade-off:** If a sync block is split across SSE packets and the end marker doesn't arrive within 50ms, the incomplete content is discarded. This prioritizes responsiveness over completeness. In practice this is rare since the server always sends complete `SYNC_START...SYNC_END` pairs and SSE typically delivers them atomically.
-
 ## DEC Mode 2026 Compatibility
 
-Terminals that natively support DEC 2026 will buffer and render atomically. Terminals that don't support it ignore the escape sequences harmlessly. xterm.js doesn't support DEC 2026 natively, so the client implements its own buffering by parsing the markers.
+Terminals that natively support DEC 2026 buffer and render atomically. Codeman uses xterm.js 6, so the client passes the markers through instead of parsing or discarding partial blocks.
 
 **Supporting terminals:** WezTerm, Kitty, Ghostty, iTerm2 3.5+, Windows Terminal, VSCode terminal
 
@@ -135,4 +117,4 @@ Terminals that natively support DEC 2026 will buffer and render atomically. Term
 | File | Key Functions |
 |------|---------------|
 | `src/web/server.ts` | `batchTerminalData()`, `flushTerminalBatches()`, `broadcast()` |
-| `src/web/public/app.js` | `batchTerminalWrite()`, `extractSyncSegments()`, `flushPendingWrites()`, `flushFlickerBuffer()`, `chunkedTerminalWrite()` |
+| `src/web/public/terminal-ui.js` | `batchTerminalWrite()`, `_scheduleTerminalWriteFlush()`, `flushPendingWrites()`, `flushFlickerBuffer()`, `chunkedTerminalWrite()` |

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.13.0",
+      "version": "1.14.0",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",

src/ai-checker-base.ts

@@ -135,6 +135,7 @@ export abstract class AiCheckerBase<
   // Active check state
   protected checkMuxName: string | null = null;
   protected checkTempFile: string | null = null;
+  protected checkStderrFile: string | null = null;
   protected checkPromptFile: string | null = null;
   protected checkPollTimer: NodeJS.Timeout | null = null;
   protected checkTimeoutTimer: NodeJS.Timeout | null = null;
@@ -376,6 +377,7 @@ export abstract class AiCheckerBase<
     const shortId = this.sessionId.slice(0, 8);
     const timestamp = Date.now();
     this.checkTempFile = join(tmpdir(), `${this.tempFilePrefix}-${shortId}-${timestamp}.txt`);
+    this.checkStderrFile = join(tmpdir(), `${this.tempFilePrefix}-stderr-${shortId}-${timestamp}.txt`);
     this.checkPromptFile = join(tmpdir(), `${this.tempFilePrefix}-prompt-${shortId}-${timestamp}.txt`);
     this.checkMuxName = `${this.muxNamePrefix}${shortId}`;
 
@@ -386,6 +388,7 @@ export abstract class AiCheckerBase<
 
     // Ensure output temp file exists (empty) so we can poll it
     writeFileSync(this.checkTempFile, '');
+    writeFileSync(this.checkStderrFile, '');
 
     // Write prompt to file to avoid E2BIG error (argument list too long)
     // The prompt can be 16KB+ which exceeds shell argument limits
@@ -396,7 +399,7 @@ export abstract class AiCheckerBase<
     const modelArg = `--model "${this.config.model.replace(/"/g, '\\"')}"`;
     const augmentedPath = getAugmentedPath();
     const claudeCmd = `cat "${this.checkPromptFile}" | claude -p ${modelArg} --output-format text`;
-    const fullCmd = `export PATH="${augmentedPath}"; ${claudeCmd} > "${this.checkTempFile}" 2>&1; echo "${this.doneMarker}" >> "${this.checkTempFile}"; rm -f "${this.checkPromptFile}"`;
+    const fullCmd = `export PATH="${augmentedPath}"; ${claudeCmd} > "${this.checkTempFile}" 2> "${this.checkStderrFile}"; echo "${this.doneMarker}" >> "${this.checkTempFile}"; rm -f "${this.checkPromptFile}"`;
 
     // Spawn tmux session
     try {
@@ -461,18 +464,32 @@ export abstract class AiCheckerBase<
     const output = content.replace(this.doneMarker, '').trim();
 
     if (!output) {
-      return this.createErrorResult(`Empty output from ${this.checkDescription}`, durationMs);
+      const stderr = this.readStderrDiagnostic();
+      const detail = stderr ? `: ${stderr}` : '';
+      return this.createErrorResult(`Empty output from ${this.checkDescription}${detail}`, durationMs);
     }
 
     // Delegate to subclass for verdict parsing
     const parsed = this.parseVerdict(output);
     if (!parsed) {
-      return this.createErrorResult(`Could not parse verdict from: "${output.substring(0, 100)}"`, durationMs);
+      const stderr = this.readStderrDiagnostic();
+      const detail = stderr ? `; stderr: "${stderr}"` : '';
+      return this.createErrorResult(`Could not parse verdict from: "${output.substring(0, 100)}"${detail}`, durationMs);
     }
 
     return this.createResult(parsed.verdict, parsed.reasoning, durationMs);
   }
 
+  private readStderrDiagnostic(): string {
+    if (!this.checkStderrFile || !existsSync(this.checkStderrFile)) return '';
+
+    try {
+      return readFileSync(this.checkStderrFile, 'utf-8').trim().substring(0, 200);
+    } catch {
+      return '';
+    }
+  }
+
   private cleanupCheck(): void {
     // Clear poll timer
     if (this.checkPollTimer) {
@@ -509,6 +526,17 @@ export abstract class AiCheckerBase<
       this.checkTempFile = null;
     }
 
+    if (this.checkStderrFile) {
+      try {
+        if (existsSync(this.checkStderrFile)) {
+          unlinkSync(this.checkStderrFile);
+        }
+      } catch {
+        // Best effort cleanup
+      }
+      this.checkStderrFile = null;
+    }
+
     if (this.checkPromptFile) {
       try {
         if (existsSync(this.checkPromptFile)) {

src/hooks-config.ts

@@ -10,13 +10,15 @@
  * Key exports:
  * - `generateHooksConfig()` — returns hooks object for settings.local.json
  * - `writeHooksConfig(casePath)` — writes hooks + env config to disk
+ * - `ensureCodemanHooks(casePath)` — safely installs/updates hooks for a managed case
  * - `updateCaseEnvVars(casePath, envVars)` — merges env vars into settings
  *
  * Hook events generated: `idle_prompt`, `permission_prompt`, `elicitation_dialog`,
  * `stop`, `teammate_idle`, `task_completed`
  *
- * Hook categories: `Notification` (3 matchers), `Stop` (1), `TeammateIdle` (1),
- * `TaskCompleted` (1), `PostToolUse` (1 self-contained background Bash rewake)
+ * Hook categories: `Notification` (3 matchers), `Stop` (1), `SubagentStop` (1),
+ * `TeammateIdle` (1), `TaskCompleted` (1), `PostToolUse` (1 self-contained
+ * background Bash rewake)
  *
  * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_SECONDS)
  * @consumedby web/server (session creation), session-cli-builder (env setup)
@@ -52,15 +54,19 @@ const BACKGROUND_WAKE_MARKER_PREFIX = 'CODEMAN_BACKGROUND_REWAKE_V';
  * changes: `refreshStaleCodemanHooks` treats the absence of the CURRENT marker as
  * stale, so healed cases pick up the new script on next launch.
  */
-const BACKGROUND_WAKE_MARKER = `${BACKGROUND_WAKE_MARKER_PREFIX}2`;
+const BACKGROUND_WAKE_MARKER = `${BACKGROUND_WAKE_MARKER_PREFIX}3`;
+const SUBAGENT_STOP_GUARD_MARKER_PREFIX = 'CODEMAN_SUBAGENT_STOP_GUARD_V';
+const SUBAGENT_STOP_GUARD_MARKER = `${SUBAGENT_STOP_GUARD_MARKER_PREFIX}1`;
 const BACKGROUND_WAKE_TIMEOUT_SECONDS = 6 * 60 * 60;
 
 /**
  * Inline Node helper for Claude Code's `asyncRewake` hook.
  *
  * A background Bash tool returns immediately with a task ID, then Claude writes
- * its completion as a queue-operation in the transcript. Watching that durable
- * record avoids injecting terminal input (which could submit a user's draft).
+ * its completion as a queue-operation in the top-level transcript. Subagent hooks
+ * receive their own transcript path even though their completion is parent-owned,
+ * so the helper watches both paths. Watching durable records avoids injecting
+ * terminal input (which could submit a user's draft).
  * The helper is embedded in settings via `node -e`, so it has no script path
  * that can go stale after an install or plugin-cache cleanup.
  *
@@ -72,8 +78,12 @@ const BACKGROUND_WAKE_TIMEOUT_SECONDS = 6 * 60 * 60;
 export function generateBackgroundWakeScript(): string {
   return [
     "const fs = require('node:fs');",
+    "const path = require('node:path');",
     `const ${BACKGROUND_WAKE_MARKER} = true;`,
     `const deadline = Date.now() + ${BACKGROUND_WAKE_TIMEOUT_SECONDS} * 1000;`,
+    "const RESULT_BEGIN = '=== CODEMAN_RESULT_BEGIN ===';",
+    "const RESULT_END = '=== CODEMAN_RESULT_END ===';",
+    'const MAX_RESULT_CHARS = 65536;',
     'let input = {};',
     "try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }",
     'function findTaskId(value) {',
@@ -98,46 +108,164 @@ export function generateBackgroundWakeScript(): string {
     'const taskId = findTaskId(input.tool_response);',
     "const transcriptPath = typeof input.transcript_path === 'string' ? input.transcript_path : '';",
     'if (!taskId || !transcriptPath) process.exit(0);',
+    'const transcriptPaths = [transcriptPath];',
+    'const sessionDir = path.dirname(path.dirname(transcriptPath));',
+    "if (typeof input.agent_id === 'string' && path.basename(path.dirname(transcriptPath)) === 'subagents' &&",
+    "    typeof input.session_id === 'string' && path.basename(sessionDir) === input.session_id) {",
+    "  transcriptPaths.push(sessionDir + '.jsonl');",
+    '}',
+    'const transcripts = [...new Set(transcriptPaths)].map((transcript) => {',
     '  let position = 0;',
-    'try { position = Math.max(0, fs.statSync(transcriptPath).size - 262144); } catch { process.exit(0); }',
-    "let carry = '';",
+    '  try { position = Math.max(0, fs.statSync(transcript).size - 262144); } catch {}',
+    "  return { path: transcript, position, carry: '' };",
+    '});',
+    'if (!transcripts.some((transcript) => fs.existsSync(transcript.path))) process.exit(0);',
+    'function readMarkedResult(outputPath) {',
+    "  if (!outputPath || !path.isAbsolute(outputPath) || path.basename(outputPath) !== taskId + '.output') return '';",
+    "  if (path.basename(path.dirname(outputPath)) !== 'tasks') return '';",
+    '  try {',
+    '    const size = fs.statSync(outputPath).size;',
+    '    const length = Math.min(size, MAX_RESULT_CHARS * 2);',
+    '    const buffer = Buffer.allocUnsafe(length);',
+    "    const fd = fs.openSync(outputPath, 'r');",
+    '    const bytes = fs.readSync(fd, buffer, 0, length, size - length);',
+    '    fs.closeSync(fd);',
+    "    const text = buffer.subarray(0, bytes).toString('utf8');",
+    '    const begin = text.lastIndexOf(RESULT_BEGIN);',
+    '    const end = text.indexOf(RESULT_END, begin + RESULT_BEGIN.length);',
+    "    if (begin < 0 || end < 0) return '';",
+    '    let result = text.slice(begin + RESULT_BEGIN.length, end).trim();',
+    "    if (!result) return '';",
+    '    if (result.length > MAX_RESULT_CHARS) {',
+    '      const half = Math.floor(MAX_RESULT_CHARS / 2);',
+    "      result = result.slice(0, half) + '\\n\\n[report truncated by Codeman]\\n\\n' + result.slice(-half);",
+    '    }',
+    "    return '\\n\\nCompleted task report:\\n<codeman-background-result>\\n' + result + '\\n</codeman-background-result>';",
+    "  } catch { return ''; }",
+    '}',
     'function inspect(text) {',
     '  for (const line of text.split(/\\r?\\n/)) {',
     '    if (!line.includes(taskId)) continue;',
     '    let entry;',
     '    try { entry = JSON.parse(line); } catch { continue; }',
-    "    if (entry.type !== 'queue-operation' || typeof entry.content !== 'string') continue;",
+    "    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue' || typeof entry.content !== 'string') continue;",
     "    if (!entry.content.includes('<task-id>' + taskId + '</task-id>')) continue;",
     '    const status = entry.content.match(/<status>(completed|failed|killed|error)<\\/status>/i);',
     '    if (!status) continue;',
     '    const output = entry.content.match(/<output-file>([^<]+)<\\/output-file>/i);',
-    "    const location = output ? ' Read ' + output[1] + ' and' : '';",
-    "    console.error('Background command ' + taskId + ' ' + status[1].toLowerCase() + '.' + location + ' continue the task.');",
+    "    const outputPath = output ? output[1].trim() : '';",
+    "    const location = outputPath ? ' Read ' + outputPath + ' and' : '';",
+    '    const result = readMarkedResult(outputPath);',
+    "    console.error('Background command ' + taskId + ' ' + status[1].toLowerCase() + '.' + location + ' continue the task.' + result);",
     '    process.exit(2);',
     '  }',
     '}',
-    'function poll() {',
-    '  if (Date.now() > deadline || process.ppid === 1) process.exit(0);',
+    'function pollTranscript(transcript) {',
     '  try {',
-    '    const size = fs.statSync(transcriptPath).size;',
-    "    if (size < position) { position = 0; carry = ''; }",
-    '    if (size > position) {',
-    '      const length = Math.min(size - position, 1048576);',
+    '    const size = fs.statSync(transcript.path).size;',
+    "    if (size < transcript.position) { transcript.position = 0; transcript.carry = ''; }",
+    '    if (size > transcript.position) {',
+    '      const length = Math.min(size - transcript.position, 1048576);',
     '      const buffer = Buffer.allocUnsafe(length);',
-    "      const fd = fs.openSync(transcriptPath, 'r');",
-    '      const bytes = fs.readSync(fd, buffer, 0, length, position);',
+    "      const fd = fs.openSync(transcript.path, 'r');",
+    '      const bytes = fs.readSync(fd, buffer, 0, length, transcript.position);',
     '      fs.closeSync(fd);',
-    '      position += bytes;',
-    "      carry = (carry + buffer.subarray(0, bytes).toString('utf8')).slice(-262144);",
-    '      inspect(carry);',
+    '      transcript.position += bytes;',
+    "      transcript.carry = (transcript.carry + buffer.subarray(0, bytes).toString('utf8')).slice(-262144);",
+    '      inspect(transcript.carry);',
     '    }',
     '  } catch {}',
+    '}',
+    'function poll() {',
+    '  if (Date.now() > deadline || process.ppid === 1) process.exit(0);',
+    '  for (const transcript of transcripts) pollTranscript(transcript);',
     '  setTimeout(poll, 1000);',
     '}',
     'poll();',
   ].join('\n');
 }
 
+/**
+ * Keep a Claude subagent alive while its Monitor or background Bash work is live.
+ * Claude otherwise can publish the worker's last progress sentence as an Agent
+ * result when one watcher ends, even if other tracked tasks are still running.
+ */
+export function generateSubagentStopGuardScript(): string {
+  return [
+    "const fs = require('node:fs');",
+    `const ${SUBAGENT_STOP_GUARD_MARKER} = true;`,
+    'let input = {};',
+    "try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }",
+    "const transcriptPath = typeof input.agent_transcript_path === 'string' ? input.agent_transcript_path : '';",
+    'if (!transcriptPath) process.exit(0);',
+    'let text;',
+    'try {',
+    '  const size = fs.statSync(transcriptPath).size;',
+    '  const length = Math.min(size, 16 * 1024 * 1024);',
+    '  const buffer = Buffer.allocUnsafe(length);',
+    "  const fd = fs.openSync(transcriptPath, 'r');",
+    '  const bytes = fs.readSync(fd, buffer, 0, length, size - length);',
+    '  fs.closeSync(fd);',
+    "  text = buffer.subarray(0, bytes).toString('utf8');",
+    '} catch { process.exit(0); }',
+    'const launched = new Set();',
+    'const finished = new Set();',
+    'function inspectToolResult(value) {',
+    "  const serialized = typeof value === 'string' ? value : JSON.stringify(value ?? '');",
+    '  for (const match of serialized.matchAll(/Command running in background with ID:\\s*([A-Za-z0-9_-]+)/gi)) launched.add(match[1]);',
+    '  for (const match of serialized.matchAll(/Monitor started \\(task ([A-Za-z0-9_-]+)/gi)) launched.add(match[1]);',
+    '}',
+    'function inspectNotifications(value) {',
+    "  if (typeof value !== 'string' || !value.includes('<task-notification>')) return;",
+    '  for (const match of value.matchAll(/<task-notification>([\\s\\S]*?)<\\/task-notification>/gi)) {',
+    '    const body = match[1];',
+    '    const id = body.match(/<task-id>([^<]+)<\\/task-id>/i);',
+    '    const status = body.match(/<status>(completed|failed|killed|error)<\\/status>/i);',
+    '    if (id && status) finished.add(id[1].trim());',
+    '  }',
+    '}',
+    'for (const line of text.split(/\\r?\\n/)) {',
+    '  let entry;',
+    '  try { entry = JSON.parse(line); } catch { continue; }',
+    '  const content = entry && entry.message ? entry.message.content : undefined;',
+    '  if (Array.isArray(content)) {',
+    '    for (const block of content) {',
+    "      if (block && block.type === 'tool_result') inspectToolResult(block.content);",
+    "      if (block && block.type === 'text') inspectNotifications(block.text);",
+    '    }',
+    '  } else {',
+    '    inspectNotifications(content);',
+    '  }',
+    '  inspectNotifications(entry && entry.content);',
+    '}',
+    'function findLiveTasks(candidates) {',
+    '  const live = new Set();',
+    "  if (candidates.size === 0 || !fs.existsSync('/proc')) return live;",
+    '  let processIds;',
+    "  try { processIds = fs.readdirSync('/proc').filter((name) => /^\\d+$/.test(name)); } catch { return live; }",
+    '  for (const processId of processIds) {',
+    "    for (const descriptor of ['0', '1', '2']) {",
+    '      let target;',
+    "      try { target = fs.readlinkSync('/proc/' + processId + '/fd/' + descriptor); } catch { continue; }",
+    '      const match = target.match(/[\\/]tasks[\\/]([A-Za-z0-9_-]+)\\.output(?: \\(deleted\\))?$/);',
+    '      if (match && candidates.has(match[1])) live.add(match[1]);',
+    '    }',
+    '    if (live.size === candidates.size) break;',
+    '  }',
+    '  return live;',
+    '}',
+    'const unfinished = new Set([...launched].filter((taskId) => !finished.has(taskId)));',
+    'const active = [...findLiveTasks(unfinished)];',
+    'if (active.length === 0) process.exit(0);',
+    'const shown = active.slice(0, 8);',
+    "const suffix = active.length > shown.length ? ' and ' + (active.length - shown.length) + ' more' : '';",
+    'process.stdout.write(JSON.stringify({',
+    "  decision: 'block',",
+    "  reason: 'You still own active background work (' + shown.join(', ') + suffix + '). Do not return an intermediate progress message as your final report. Process the task notifications or keep actively polling until every task completes, then return one complete summary.',",
+    '}));',
+  ].join('\n');
+}
+
 function withSettingsLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
   const prev = settingsWriteLocks.get(path) ?? Promise.resolve();
   const run = prev.then(fn, fn); // run after the prior writer, regardless of its outcome
@@ -204,6 +332,18 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
           hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
+      SubagentStop: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command: 'node',
+              args: ['-e', generateSubagentStopGuardScript()],
+              timeout: HOOK_TIMEOUT_SECONDS,
+            },
+          ],
+        },
+      ],
       TeammateIdle: [
         {
           hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_SECONDS }],
@@ -235,8 +375,12 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
 function isCodemanHookHandler(value: unknown): boolean {
   try {
     const serialized = JSON.stringify(value);
-    // Prefix, not the versioned marker: older script versions must still be ours.
-    return serialized.includes('/api/hook-event') || serialized.includes(BACKGROUND_WAKE_MARKER_PREFIX);
+    // Prefixes, not versioned markers: older script versions must still be ours.
+    return (
+      serialized.includes('/api/hook-event') ||
+      serialized.includes(BACKGROUND_WAKE_MARKER_PREFIX) ||
+      serialized.includes(SUBAGENT_STOP_GUARD_MARKER_PREFIX)
+    );
   } catch {
     return false;
   }
@@ -430,6 +574,39 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
   });
 }
 
+/**
+ * Ensures an explicitly managed case has the current Codeman hooks.
+ *
+ * Unlike `refreshStaleCodemanHooks`, this may add Codeman handlers to a valid
+ * user-owned settings file. It is therefore reserved for case quick-starts,
+ * where the user has explicitly asked Codeman to manage that workspace. A
+ * malformed existing file is left untouched rather than replaced.
+ */
+export async function ensureCodemanHooks(casePath: string): Promise<void> {
+  const claudeDir = join(casePath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+  await withSettingsLock(settingsPath, async () => {
+    if (!existsSync(claudeDir)) {
+      await mkdir(claudeDir, { recursive: true });
+    }
+
+    let existing: Record<string, unknown> = {};
+    try {
+      const parsed: unknown = JSON.parse(await readFile(settingsPath, 'utf-8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return;
+      existing = parsed as Record<string, unknown>;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return;
+    }
+
+    const generated = generateHooksConfig();
+    const hooks = mergeCodemanHooks(existing.hooks, generated.hooks);
+    if (JSON.stringify(existing.hooks ?? {}) === JSON.stringify(hooks)) return;
+
+    await writeFile(settingsPath, JSON.stringify({ ...existing, hooks }, null, 2) + '\n');
+  });
+}
+
 /**
  * Self-heal a case's Codeman-owned hooks block.
  *
@@ -437,10 +614,11 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
  * X-Codeman-Hook-Secret header was added (COD-54, 2026-06-10) keep hook curls in their
  * settings.local.json that POST to /api/hook-event WITHOUT the secret — which, once the
  * gate requires it unconditionally (COD-91), silently 401 on a password-protected install.
- * Older Codeman blocks also lack the background Bash async-rewake hook. A third stale
- * shape: hook curls without `-k`, which exit 60 on every --https/tailscale install (the
- * cert is self-signed), swallowed by the hooks' own `|| true` — all six hook events die
- * silently. Refresh any of these stale shapes on launch so existing cases heal.
+ * Older Codeman blocks also lack the current background Bash async-rewake hook or the
+ * SubagentStop guard. A further stale shape: hook curls without `-k`, which exit 60 on
+ * every --https/tailscale install (the cert is self-signed), swallowed by the hooks'
+ * own `|| true` — all six hook events die silently. Refresh any of these stale shapes
+ * on launch so existing cases heal.
  *
  * Deliberately surgical: regenerates ONLY when settings.local.json already contains
  * Codeman's own hook curls (they target `/api/hook-event`) and they are stale. No-op
@@ -467,7 +645,8 @@ export async function refreshStaleCodemanHooks(casePath: string): Promise<void>
     // as a substring, so this cleanly identifies hook curls that die with exit 60
     // on a self-signed HTTPS install.
     const hasTlsFlaglessCurl = hooksJson.includes('curl -s -X POST');
-    if (!isOurs || (hasSecret && hasBackgroundWake && !hasTlsFlaglessCurl)) return;
+    const hasSubagentStopGuard = hooksJson.includes(SUBAGENT_STOP_GUARD_MARKER);
+    if (!isOurs || (hasSecret && hasBackgroundWake && hasSubagentStopGuard && !hasTlsFlaglessCurl)) return;
     const generated = generateHooksConfig();
     const merged = {
       ...existing,

src/web/public/terminal-ui.js

@@ -341,7 +341,7 @@ Object.assign(CodemanApp.prototype, {
 
     // WebGL renderer for GPU-accelerated terminal rendering.
     // Previously caused "page unresponsive" crashes from synchronous GPU stalls,
-    // but the 48KB/frame flush cap in flushPendingWrites() now prevents
+    // but the mode-aware 32/64KB frame cap in flushPendingWrites() now prevents
     // oversized terminal.write() calls that triggered the stalls.
     // Disable with ?nowebgl URL param if GPU issues return.
     // Auto-fallback: _initWebGL installs a long-task watchdog that disables
@@ -2349,17 +2349,26 @@ Object.assign(CodemanApp.prototype, {
 
     // Accumulate raw data (may contain DEC 2026 markers)
     this.pendingWrites.push(data);
+    this._scheduleTerminalWriteFlush();
+  },
 
-    if (!this.writeFrameScheduled) {
+  /**
+   * Schedule one render-budgeted terminal flush.
+   *
+   * Clear the scheduled flag before flushing so flushPendingWrites() can queue
+   * another yield when a large final batch leaves bytes behind. Keeping the
+   * flag set through the flush stranded that remainder until unrelated output
+   * arrived, which looked like truncated responses and idle shell commands.
+   */
+  _scheduleTerminalWriteFlush() {
+    if (this.writeFrameScheduled || this.pendingWrites.length === 0) return;
     this.writeFrameScheduled = true;
     this._safeYield(() => {
-        // xterm.js 6.0 handles DEC 2026 sync markers natively — it buffers
-        // content between 2026h/2026l and renders atomically. No need for
-        // client-side incomplete-block detection; just flush every frame.
-        this.flushPendingWrites();
       this.writeFrameScheduled = false;
+      // xterm.js 6.0 handles DEC 2026 sync markers natively — it buffers
+      // content between 2026h/2026l and renders atomically.
+      this.flushPendingWrites();
     });
-    }
   },
 
   /**
@@ -2375,13 +2384,7 @@ Object.assign(CodemanApp.prototype, {
     this.flickerFilterActive = false;
 
     // Trigger a normal flush
-    if (!this.writeFrameScheduled) {
-      this.writeFrameScheduled = true;
-      this._safeYield(() => {
-        this.flushPendingWrites();
-        this.writeFrameScheduled = false;
-      });
-    }
+    this._scheduleTerminalWriteFlush();
   },
 
   /**
@@ -2530,13 +2533,7 @@ Object.assign(CodemanApp.prototype, {
       this.terminal.write(joined.slice(0, MAX_FRAME_BYTES));
       this.pendingWrites.push(joined.slice(MAX_FRAME_BYTES));
       deferred = true;
-      if (!this.writeFrameScheduled) {
-        this.writeFrameScheduled = true;
-        this._safeYield(() => {
-          this.flushPendingWrites();
-          this.writeFrameScheduled = false;
-        });
-      }
+      this._scheduleTerminalWriteFlush();
     }
     if (
       preserveViewportY !== null &&

test/ai-idle-checker.test.ts

@@ -71,7 +71,8 @@ describe('AiIdleChecker', () => {
   describe('Output Parsing', () => {
     it('should parse IDLE verdict', async () => {
       // Set up mock to return IDLE result after polling
-      mockedReadFileSync.mockReturnValueOnce('') // writeFileSync creates empty file
+      mockedReadFileSync
+        .mockReturnValueOnce('') // writeFileSync creates empty file
         .mockReturnValueOnce('IDLE\nSession shows completion message and prompt.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('some terminal output');
@@ -87,7 +88,8 @@ describe('AiIdleChecker', () => {
     });
 
     it('should parse WORKING verdict', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
+      mockedReadFileSync
+        .mockReturnValueOnce('')
         .mockReturnValueOnce('WORKING\nSpinner characters detected, still processing.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('some terminal output');
@@ -100,8 +102,7 @@ describe('AiIdleChecker', () => {
     });
 
     it('should handle lowercase verdict', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('idle\nDone.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('idle\nDone.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(500);
@@ -112,7 +113,8 @@ describe('AiIdleChecker', () => {
     });
 
     it('should return ERROR for unparseable output', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
+      mockedReadFileSync
+        .mockReturnValueOnce('')
         .mockReturnValueOnce('Something unexpected happened.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
@@ -125,8 +127,7 @@ describe('AiIdleChecker', () => {
     });
 
     it('should return ERROR for empty output', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(500);
@@ -175,10 +176,34 @@ describe('AiIdleChecker', () => {
       await vi.advanceTimersByTimeAsync(500);
       await checkPromise;
 
-      expect(mockedWriteFileSync).toHaveBeenCalledWith(
-        expect.stringContaining('codeman-aicheck-'),
-        ''
+      expect(mockedWriteFileSync).toHaveBeenCalledWith(expect.stringContaining('codeman-aicheck-'), '');
+    });
+
+    it('should keep Claude stderr separate from verdict output', async () => {
+      mockedReadFileSync.mockReturnValue('IDLE\n__AICHECK_DONE__');
+
+      const checkPromise = checker.check('output');
+      await vi.advanceTimersByTimeAsync(500);
+      await checkPromise;
+
+      const spawnArgs = mockedSpawn.mock.calls[0]?.[1];
+      const command = spawnArgs?.[spawnArgs.length - 1];
+      expect(command).toEqual(expect.any(String));
+      expect(command).toContain(' 2> "');
+      expect(command).not.toContain('2>&1');
+    });
+
+    it('should include Claude stderr when no verdict is produced', async () => {
+      mockedReadFileSync.mockImplementation((path) =>
+        String(path).includes('-stderr-') ? 'Claude CLI failed to load settings' : '__AICHECK_DONE__'
       );
+
+      const checkPromise = checker.check('output');
+      await vi.advanceTimersByTimeAsync(500);
+
+      const result = await checkPromise;
+      expect(result.verdict).toBe('ERROR');
+      expect(result.reasoning).toContain('Claude CLI failed to load settings');
     });
   });
 
@@ -223,7 +248,7 @@ describe('AiIdleChecker', () => {
 
       // Should have tried to kill the tmux session (initial kill + cleanup kill)
       const killCalls = mockedExecSync.mock.calls.filter(
-        call => typeof call[0] === 'string' && call[0].includes('kill-session')
+        (call) => typeof call[0] === 'string' && call[0].includes('kill-session')
       );
       expect(killCalls.length).toBeGreaterThan(0);
     });
@@ -236,8 +261,7 @@ describe('AiIdleChecker', () => {
 
   describe('Cooldown', () => {
     it('should start cooldown after WORKING verdict', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('WORKING\nStill processing.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('WORKING\nStill processing.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(500);
@@ -250,8 +274,7 @@ describe('AiIdleChecker', () => {
     });
 
     it('should return to ready after cooldown expires', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
@@ -267,8 +290,7 @@ describe('AiIdleChecker', () => {
     });
 
     it('should not start new check during cooldown', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
 
       const firstCheck = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
@@ -283,8 +305,7 @@ describe('AiIdleChecker', () => {
 
   describe('Error Handling', () => {
     it('should start error cooldown after parse error', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('garbage output\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('garbage output\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
@@ -302,8 +323,7 @@ describe('AiIdleChecker', () => {
       const cooldowns = [1100, 2100]; // Wait slightly longer than each cooldown
 
       for (let i = 0; i < 3; i++) {
-        mockedReadFileSync.mockReturnValueOnce('')
-          .mockReturnValueOnce('garbage\n__AICHECK_DONE__');
+        mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('garbage\n__AICHECK_DONE__');
 
         const checkPromise = checker.check('output');
         await vi.advanceTimersByTimeAsync(1000);
@@ -321,8 +341,7 @@ describe('AiIdleChecker', () => {
 
     it('should reset error counter on successful check', async () => {
       // First check: error
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('garbage\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('garbage\n__AICHECK_DONE__');
       const firstCheck = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
       await firstCheck;
@@ -332,8 +351,7 @@ describe('AiIdleChecker', () => {
       await vi.advanceTimersByTimeAsync(1100);
 
       // Second check: success
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('IDLE\nDone.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('IDLE\nDone.\n__AICHECK_DONE__');
       const secondCheck = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
       await secondCheck;
@@ -352,8 +370,7 @@ describe('AiIdleChecker', () => {
 
   describe('Buffer Handling', () => {
     it('should strip ANSI codes from terminal buffer', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('IDLE\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('IDLE\n__AICHECK_DONE__');
 
       const ansiBuffer = '\x1b[1mBold\x1b[0m \x1b[32mGreen\x1b[0m text';
       const checkPromise = checker.check(ansiBuffer);
@@ -365,8 +382,7 @@ describe('AiIdleChecker', () => {
     });
 
     it('should trim buffer to maxContextChars', async () => {
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('IDLE\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('IDLE\n__AICHECK_DONE__');
 
       // Create buffer longer than maxContextChars (1000)
       const longBuffer = 'x'.repeat(2000);
@@ -402,8 +418,7 @@ describe('AiIdleChecker', () => {
   describe('Reset', () => {
     it('should clear all state on reset', async () => {
       // Trigger a WORKING verdict to set state
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
@@ -440,24 +455,24 @@ describe('AiIdleChecker', () => {
       const handler = vi.fn();
       checker.on('checkCompleted', handler);
 
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('IDLE\nAll done.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('IDLE\nAll done.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
       await checkPromise;
 
-      expect(handler).toHaveBeenCalledWith(expect.objectContaining({
+      expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining({
           verdict: 'IDLE',
-      }));
+        })
+      );
     });
 
     it('should emit cooldownStarted event after WORKING', async () => {
       const handler = vi.fn();
       checker.on('cooldownStarted', handler);
 
-      mockedReadFileSync.mockReturnValueOnce('')
-        .mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
+      mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('WORKING\nBusy.\n__AICHECK_DONE__');
 
       const checkPromise = checker.check('output');
       await vi.advanceTimersByTimeAsync(1000);
@@ -477,8 +492,7 @@ describe('AiIdleChecker', () => {
       const cooldowns = [1100, 2100]; // Wait longer than exponential backoff
 
       for (let i = 0; i < 3; i++) {
-        mockedReadFileSync.mockReturnValueOnce('')
-          .mockReturnValueOnce('garbage\n__AICHECK_DONE__');
+        mockedReadFileSync.mockReturnValueOnce('').mockReturnValueOnce('garbage\n__AICHECK_DONE__');
         const checkPromise = checker.check('output');
         await vi.advanceTimersByTimeAsync(1000);
         await checkPromise;

test/daemon-control.test.ts

@@ -16,7 +16,7 @@ import {
   probeServer,
 } from '../src/daemon-control.js';
 
-const PORT = 3212;
+const PORT = 3216;
 
 describe('buildWebArgs', () => {
   it('always passes host and port through explicitly', () => {

test/hook-secret-selfheal.test.ts

@@ -127,7 +127,7 @@ describe('refreshStaleCodemanHooks', () => {
 
     const after = JSON.parse(readFileSync(settingsPath, 'utf-8'));
     expect(JSON.stringify(after.hooks)).toContain(SECRET_HEADER);
-    expect(JSON.stringify(after.hooks)).toContain('CODEMAN_BACKGROUND_REWAKE_V');
+    expect(JSON.stringify(after.hooks)).toContain('CODEMAN_BACKGROUND_REWAKE_V3');
     expect(JSON.stringify(after.hooks.Stop)).toContain('./notify-user.sh');
     expect(after.hooks.PostToolUse).toEqual(expect.arrayContaining([customPostToolUse]));
     expect(after.hooks.CustomEvent).toEqual(customEvent);

test/hooks-config.test.ts

@@ -6,13 +6,15 @@
  */
 
 import { describe, it, expect, beforeAll, beforeEach, afterAll, afterEach } from 'vitest';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawn } from 'node:child_process';
 import {
+  ensureCodemanHooks,
   generateBackgroundWakeScript,
   generateHooksConfig,
+  generateSubagentStopGuardScript,
   refreshStaleCodemanHooks,
   writeHooksConfig,
 } from '../src/hooks-config.js';
@@ -35,6 +37,20 @@ describe('generateHooksConfig', () => {
     expect(config.hooks.Stop).toHaveLength(1);
   });
 
+  it('should guard subagent stops while their background work is active', () => {
+    const config = generateHooksConfig();
+    const subagentHooks = config.hooks.SubagentStop as Array<{
+      hooks: Array<{ type: string; command: string; args: string[]; timeout: number }>;
+    }>;
+
+    expect(subagentHooks).toHaveLength(1);
+    expect(subagentHooks[0].hooks[0]).toMatchObject({
+      type: 'command',
+      command: 'node',
+      args: ['-e', generateSubagentStopGuardScript()],
+    });
+  });
+
   it('should configure a self-contained Bash background-task rewake hook', () => {
     const config = generateHooksConfig();
     const postToolHooks = config.hooks.PostToolUse as Array<{
@@ -210,7 +226,8 @@ describe('writeHooksConfig', () => {
 
     const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
     expect(parsed.hooks.PostToolUse).toHaveLength(1);
-    expect(JSON.stringify(parsed.hooks.PostToolUse)).toContain('CODEMAN_BACKGROUND_REWAKE_V');
+    expect(JSON.stringify(parsed.hooks.PostToolUse)).toContain('CODEMAN_BACKGROUND_REWAKE_V3');
+    expect(JSON.stringify(parsed.hooks.SubagentStop)).toContain('CODEMAN_SUBAGENT_STOP_GUARD_V1');
   });
 
   it('should replace an older rewake script version without duplicating it', async () => {
@@ -242,10 +259,29 @@ describe('writeHooksConfig', () => {
     const serialized = JSON.stringify(parsed.hooks.PostToolUse);
     expect(parsed.hooks.PostToolUse).toHaveLength(1);
     expect(parsed.hooks.PostToolUse[0].hooks).toHaveLength(1);
-    expect(serialized).toContain('CODEMAN_BACKGROUND_REWAKE_V2');
+    expect(serialized).toContain('CODEMAN_BACKGROUND_REWAKE_V3');
     expect(serialized).not.toContain('CODEMAN_BACKGROUND_REWAKE_V1');
   });
 
+  it('replaces the V2 background hook without duplicating it', async () => {
+    const claudeDir = join(testDir, '.claude');
+    const settingsPath = join(claudeDir, 'settings.local.json');
+    mkdirSync(claudeDir, { recursive: true });
+    const oldSettings = JSON.stringify({ hooks: generateHooksConfig().hooks }, null, 2).replaceAll(
+      'CODEMAN_BACKGROUND_REWAKE_V3',
+      'CODEMAN_BACKGROUND_REWAKE_V2'
+    );
+    writeFileSync(settingsPath, oldSettings);
+
+    await refreshStaleCodemanHooks(testDir);
+
+    const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    const postToolUse = JSON.stringify(parsed.hooks.PostToolUse);
+    expect(parsed.hooks.PostToolUse).toHaveLength(1);
+    expect(postToolUse).toContain('CODEMAN_BACKGROUND_REWAKE_V3');
+    expect(postToolUse).not.toContain('CODEMAN_BACKGROUND_REWAKE_V2');
+  });
+
   it('should not add rewake hooks to a user-owned hook configuration', async () => {
     const claudeDir = join(testDir, '.claude');
     const settingsPath = join(claudeDir, 'settings.local.json');
@@ -278,6 +314,35 @@ describe('writeHooksConfig', () => {
     expect(parsed.hooks.Notification).toBeDefined();
   });
 
+  it('should safely add Codeman hooks to an existing managed-case settings file', async () => {
+    const claudeDir = join(testDir, '.claude');
+    const settingsPath = join(claudeDir, 'settings.local.json');
+    mkdirSync(claudeDir, { recursive: true });
+    const userHooks = {
+      PostToolUse: [{ matcher: 'Write', hooks: [{ type: 'command', command: './format.sh' }] }],
+    };
+    writeFileSync(settingsPath, JSON.stringify({ hooks: userHooks, permissions: { allow: ['Read'] } }, null, 2));
+
+    await ensureCodemanHooks(testDir);
+
+    const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    expect(parsed.permissions).toEqual({ allow: ['Read'] });
+    expect(parsed.hooks.PostToolUse).toEqual(expect.arrayContaining(userHooks.PostToolUse));
+    expect(JSON.stringify(parsed.hooks)).toContain('CODEMAN_BACKGROUND_REWAKE_V3');
+    expect(JSON.stringify(parsed.hooks)).toContain('CODEMAN_SUBAGENT_STOP_GUARD_V1');
+  });
+
+  it('should not replace a malformed managed-case settings file', async () => {
+    const claudeDir = join(testDir, '.claude');
+    const settingsPath = join(claudeDir, 'settings.local.json');
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(settingsPath, '{ malformed');
+
+    await ensureCodemanHooks(testDir);
+
+    expect(readFileSync(settingsPath, 'utf-8')).toBe('{ malformed');
+  });
+
   it('should handle malformed existing settings.local.json', async () => {
     const claudeDir = join(testDir, '.claude');
     mkdirSync(claudeDir, { recursive: true });
@@ -370,6 +435,210 @@ describe('background task rewake helper', () => {
     expect(result.stderr).toContain('completed');
     expect(result.stderr).toContain('/tmp/bg-test-1.output');
   });
+
+  it('rewakes a subagent when Claude queues completion in the parent transcript', async () => {
+    const sessionId = '7148e9de-7673-48b8-bf38-6799e52c346a';
+    const sessionDir = join(testDir, sessionId);
+    const subagentDir = join(sessionDir, 'subagents');
+    const parentTranscriptPath = `${sessionDir}.jsonl`;
+    const subagentTranscriptPath = join(subagentDir, 'agent-afacts-class2.jsonl');
+    mkdirSync(subagentDir, { recursive: true });
+    writeFileSync(parentTranscriptPath, '');
+    writeFileSync(subagentTranscriptPath, '');
+
+    const resultPromise = runHelper({
+      session_id: sessionId,
+      agent_id: 'afacts-class2',
+      transcript_path: subagentTranscriptPath,
+      tool_response: {
+        backgroundTaskId: 'bg-subagent-1',
+      },
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    writeFileSync(
+      parentTranscriptPath,
+      JSON.stringify({
+        type: 'queue-operation',
+        operation: 'enqueue',
+        content:
+          '<task-notification>\n<task-id>bg-subagent-1</task-id>\n<status>completed</status>\n' +
+          '<output-file>/tmp/bg-subagent-1.output</output-file>\n</task-notification>',
+      }) + '\n'
+    );
+
+    const result = await resultPromise;
+    expect(result.code).toBe(2);
+    expect(result.stderr).toContain('bg-subagent-1');
+    expect(result.stderr).toContain('/tmp/bg-subagent-1.output');
+  });
+
+  it('includes a marked background report in the wake feedback', async () => {
+    const transcriptPath = join(testDir, 'transcript.jsonl');
+    const tasksDir = join(testDir, 'tasks');
+    const outputPath = join(tasksDir, 'bg-report-1.output');
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(transcriptPath, '');
+    writeFileSync(
+      outputPath,
+      [
+        'launcher output',
+        '=== CODEMAN_RESULT_BEGIN ===',
+        'Summary line',
+        'Detail after the old 30-line preview boundary',
+        '=== CODEMAN_RESULT_END ===',
+      ].join('\n')
+    );
+
+    const resultPromise = runHelper({
+      transcript_path: transcriptPath,
+      tool_response: {
+        stdout: `Command running in background with ID: bg-report-1. Output is being written to: ${outputPath}.`,
+      },
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    writeFileSync(
+      transcriptPath,
+      JSON.stringify({
+        type: 'queue-operation',
+        operation: 'enqueue',
+        content:
+          '<task-notification>\n<task-id>bg-report-1</task-id>\n<status>completed</status>\n' +
+          `<output-file>${outputPath}</output-file>\n</task-notification>`,
+      }) + '\n'
+    );
+
+    const result = await resultPromise;
+    expect(result.code).toBe(2);
+    expect(result.stderr).toContain('<codeman-background-result>');
+    expect(result.stderr).toContain('Summary line');
+    expect(result.stderr).toContain('Detail after the old 30-line preview boundary');
+  });
+});
+
+describe('subagent stop guard helper', () => {
+  const testDir = join(tmpdir(), 'codeman-subagent-stop-guard-test-' + Date.now());
+
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  function runGuard(transcriptLines: unknown[]): Promise<{ code: number | null; stdout: string; stderr: string }> {
+    const transcriptPath = join(testDir, 'agent-test.jsonl');
+    writeFileSync(transcriptPath, transcriptLines.map((line) => JSON.stringify(line)).join('\n') + '\n');
+
+    return new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, ['-e', generateSubagentStopGuardScript()], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      let stdout = '';
+      let stderr = '';
+      child.stdout.setEncoding('utf8');
+      child.stderr.setEncoding('utf8');
+      child.stdout.on('data', (chunk) => {
+        stdout += chunk;
+      });
+      child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+      });
+      child.on('error', reject);
+      child.on('close', (code) => resolve({ code, stdout, stderr }));
+      child.stdin.end(JSON.stringify({ agent_transcript_path: transcriptPath }));
+    });
+  }
+
+  async function withLiveTask<T>(taskId: string, action: () => Promise<T>): Promise<T> {
+    const tasksDir = join(testDir, 'tasks');
+    mkdirSync(tasksDir, { recursive: true });
+    const outputFd = openSync(join(tasksDir, `${taskId}.output`), 'a');
+    const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 10000)'], {
+      stdio: ['ignore', outputFd, outputFd],
+    });
+    await new Promise<void>((resolve, reject) => {
+      child.once('spawn', resolve);
+      child.once('error', reject);
+    });
+    closeSync(outputFd);
+
+    try {
+      return await action();
+    } finally {
+      const closed = new Promise<void>((resolve) => child.once('close', () => resolve()));
+      child.kill();
+      await closed;
+    }
+  }
+
+  const monitorResult = (taskId: string) => ({
+    type: 'user',
+    message: {
+      content: [
+        {
+          type: 'tool_result',
+          content: `Monitor started (task ${taskId}, pid 123).`,
+        },
+      ],
+    },
+  });
+
+  const completion = (taskId: string) => ({
+    type: 'user',
+    message: {
+      content:
+        `<task-notification>\n<task-id>${taskId}</task-id>\n` + '<status>completed</status>\n</task-notification>',
+    },
+  });
+
+  it('blocks an intermediate subagent stop while a sibling monitor is active', async () => {
+    const result = await withLiveTask('monitor-still-live', () =>
+      runGuard([monitorResult('monitor-first'), monitorResult('monitor-still-live'), completion('monitor-first')])
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(JSON.parse(result.stdout)).toMatchObject({ decision: 'block' });
+    expect(result.stdout).toContain('monitor-still-live');
+    expect(result.stdout).not.toContain('monitor-first,');
+  });
+
+  it('allows a subagent to stop after all of its monitored work finishes', async () => {
+    const result = await runGuard([
+      monitorResult('monitor-first'),
+      monitorResult('monitor-second'),
+      completion('monitor-first'),
+      completion('monitor-second'),
+    ]);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toBe('');
+    expect(result.stderr).toBe('');
+  });
+
+  it('also recognizes background Bash task ownership', async () => {
+    const result = await withLiveTask('bash-live-1', () =>
+      runGuard([
+        {
+          type: 'user',
+          message: {
+            content: [
+              {
+                type: 'tool_result',
+                content: 'Command running in background with ID: bash-live-1. Output is being written to a task file.',
+              },
+            ],
+          },
+        },
+      ])
+    );
+
+    expect(JSON.parse(result.stdout)).toMatchObject({ decision: 'block' });
+    expect(result.stdout).toContain('bash-live-1');
+  });
 });
 
 // ========== Hook Event API Integration Tests ==========

test/terminal-flush-budget.test.ts

@@ -47,6 +47,26 @@ function loadTerminalUiHarness(mode: string) {
 }
 
 describe('terminal flush budget', () => {
+  it('drains a large final batch without waiting for unrelated terminal output', () => {
+    const { app, writes } = loadTerminalUiHarness('codex');
+    const scheduled: Array<() => void> = [];
+    app._safeYield = (callback: () => void) => {
+      scheduled.push(callback);
+    };
+    app.isTerminalAtBottom = () => true;
+
+    app.batchTerminalWrite('x'.repeat(96 * 1024));
+    expect(scheduled).toHaveLength(1);
+
+    while (scheduled.length > 0) {
+      scheduled.shift()?.();
+    }
+
+    expect(writes.map((write) => write.length)).toEqual([32 * 1024, 32 * 1024, 32 * 1024]);
+    expect(app.pendingWrites).toEqual([]);
+    expect(app.writeFrameScheduled).toBe(false);
+  });
+
   it('uses a smaller first-frame write budget for Codex output to reduce renderer stalls', () => {
     const { app, writes } = loadTerminalUiHarness('codex');
     app.pendingWrites.push('x'.repeat(96 * 1024));