chore: version packages

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

.github/workflows/release.yml

@@ -52,12 +52,20 @@ jobs:
           OLD_TAG="aicodeman@${VERSION}"
           NEW_TAG="codeman@${VERSION}"
 
-          # Update the GitHub release BEFORE deleting the old tag
+          # Update the GitHub release BEFORE deleting the old tag.
+          # make_latest pins the "Latest" badge to the Codeman release. This repo
+          # publishes TWO packages (aicodeman + xterm-zerolag-input), changesets
+          # creates a GitHub release for each, and GitHub awards "Latest" to
+          # whichever was published LAST. That is a race: 1.9.2 kept the badge,
+          # 1.9.4 lost it to xterm-zerolag-input@0.1.7 by two seconds. All package
+          # releases already exist by the time this step runs, so setting it here
+          # is deterministic.
           RELEASE_ID=$(gh release view "$OLD_TAG" --json databaseId -q .databaseId 2>/dev/null || true)
           if [ -n "$RELEASE_ID" ]; then
             gh api -X PATCH "repos/${{ github.repository }}/releases/${RELEASE_ID}" \
               -f tag_name="$NEW_TAG" \
-              -f name="$NEW_TAG"
+              -f name="$NEW_TAG" \
+              -f make_latest=true
           fi
 
           # Retag

CHANGELOG.md

@@ -1,5 +1,26 @@
 # aicodeman
 
+## 1.9.6
+
+### Patch Changes
+
+- Two fixes from community PRs (thanks @Lint111):
+  - fix(transcripts): complete tools from user-entry results (#177). Claude transcripts record tool requests in assistant entries but commonly carry their results in user-role entries; the transcript watcher only completed tools from the older assistant-entry path, so Codeman could keep showing a tool as running after it had finished. The watcher now recognizes `tool_result` blocks in user entries, ends the active tool state, and emits `transcript:tool_end` with the correct tool name and error status. Watcher tests also moved from fixed sleeps to condition-based `vi.waitFor` assertions.
+  - fix(notifications): quiet lifecycle hook noise (#178). Notification preferences move to schema version 5: the drawer-only "Response complete" (stop) default is now off, and the migration disables only the legacy drawer-only shape, preserving any explicit browser, audio, or push delivery the user opted into. Teammate-idle and task-completed hooks now map to the existing opt-in subagent categories instead of the broadly enabled idle/stop alerts, so normal agent activity no longer floods the drawer. Local and server-hydrated preferences are normalized through the same migration path (server hydration used to revive the retired default on fresh browsers), and the notification storage key now uses the stable handheld identity so an unfolded foldable keeps its mobile defaults and storage key (tablets and desktops unaffected).
+
+## 1.9.5
+
+### Patch Changes
+
+- Background-Bash rewake hook, hooks self-heal that preserves user hooks, and test-harness isolation.
+  - New `PostToolUse(Bash)` hook (PR #176): a self-contained `node -e` helper watches the session transcript for a background command's completion notification and uses Claude Code's `asyncRewake` to wake an idle agent (exit code 2), without injecting terminal input that could submit a user's draft. Works on Claude Code 2.1.207+; older CLIs strip the fields harmlessly.
+  - Hooks self-heal (`refreshStaleHookSecret` renamed to `refreshStaleCodemanHooks`) now replaces only Codeman-owned handlers, preserving user events, matchers, and sibling handlers in mixed configurations; `writeHooksConfig` merges instead of clobbering the hooks key at case creation (PR #176).
+  - Rewake helper hardening: self-terminates on its own 6h deadline and when orphaned; the marker is versioned (V2) with a version-agnostic ownership prefix so future script updates replace older handlers instead of duplicating them.
+  - Hook timeout units fixed: the hook `timeout` field is seconds (the CLI multiplies by 1000), so `HOOK_TIMEOUT_MS = 10000` gave curl hooks a ~2.8-hour effective timeout; now `HOOK_TIMEOUT_SECONDS = 10`.
+  - Test-harness isolation (PR #175): every test file gets a temporary `HOME`/`USERPROFILE` so tests cannot touch real Codeman state or delete real case directories, and `Session` attaches a raw-mode echo PTY instead of a real tmux client under Vitest. Fixes the quick-start suite deleting the real `~/codeman-cases/testcase`.
+  - CI stability: drain console-log rpc forwards before worker teardown (fixes a run-failing `EnvironmentTeardownError` with all tests passing); `test/webview-proxy.test.ts` no longer accidentally runs under the jsdom environment via a directive named in a comment.
+  - Release workflow pins the GitHub "Latest" badge to the Codeman release.
+
 ## 1.9.4
 
 ### Patch 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.9.4 (must match `package.json`)
+**Version**: 1.9.6 (must match `package.json`)
 
 ## Project Overview
 
@@ -320,7 +320,7 @@ Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pa
 
 **Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s. `config/vitest.ci.config.ts` = same minus the browser/perf excludes — keep the two configs in sync when changing shared options.
 
-**Tmux safety**: under vitest (`VITEST` env var, set automatically), `TmuxManager` no-ops ALL shell commands and becomes a pure in-memory mock — tests physically cannot create/kill/attach real tmux sessions (`IS_TEST_MODE` in `src/tmux-manager.ts`). Every docker IO path is no-op'd the same way. `test/setup.ts` additionally strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME` (so auth state from the running instance can't leak into tests) and `CODEMAN_GESTURE` (a shell-exported gesture flag would flip render-injection assertions).
+**Tmux safety**: under vitest (`VITEST` env var, set automatically), `TmuxManager` no-ops ALL shell commands and becomes a pure in-memory mock — tests physically cannot create/kill/attach real tmux sessions (`IS_TEST_MODE` in `src/tmux-manager.ts`). Every docker IO path is no-op'd the same way. `Session` is test-gated too: instead of attaching a real tmux client, it spawns a raw-mode echo PTY (`TEST_PTY_SCRIPT` in `src/session.ts`), so integration tests get a live input/output loop that echoes each byte exactly once. `test/setup.ts` gives every test file a temporary `HOME`/`USERPROFILE` (all `homedir()`-derived state, `~/.codeman` and `~/codeman-cases` included, resolves into a per-file fixture; the Playwright browser cache path is preserved), and additionally strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME` (so auth state from the running instance can't leak into tests) and `CODEMAN_GESTURE` (a shell-exported gesture flag would flip render-injection assertions). ⚠️ Raw `npx vitest` without `--config` skips `setup.ts` and with it the temp-HOME isolation.
 
 **Ports**: Pick unique ports manually, 3150+. Search `const PORT =` before adding new tests. Never 3000 (the live instance).
 

docs/claude-code-hooks-reference.md

@@ -2,14 +2,18 @@
 
 > Official documentation for Claude Code hooks system, extracted from [code.claude.com](https://code.claude.com/docs/en/hooks).
 
-**Last Updated**: 2026-01-24
+**Last Updated**: 2026-07-25
 **Source**: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
 
+> This is a maintained summary, not an exhaustive copy of the upstream reference.
+> Check the source link for event-specific schemas before adding a new hook.
+
 ---
 
 ## Overview
 
 Hooks are automated scripts that execute at specific events during your Claude Code session. They allow you to:
+
 - Validate, modify, or block tool usage
 - Add context to prompts
 - Implement custom workflows
@@ -21,12 +25,12 @@ Hooks are automated scripts that execute at specific events during your Claude C
 
 Hooks are configured in settings files:
 
-| File | Scope |
-|------|-------|
-| `~/.claude/settings.json` | User (global) |
-| `.claude/settings.json` | Project |
+| File                          | Scope                      |
+| ----------------------------- | -------------------------- |
+| `~/.claude/settings.json`     | User (global)              |
+| `.claude/settings.json`       | Project                    |
 | `.claude/settings.local.json` | Local project (gitignored) |
-| Plugin hook files | Plugin-specific |
+| Plugin hook files             | Plugin-specific            |
 
 ### Basic Structure
 
@@ -49,8 +53,9 @@ Hooks are configured in settings files:
 ```
 
 **Key Fields**:
+
 - `matcher`: Pattern to match tool names (case-sensitive, supports regex like `Edit|Write` or `*` for all)
-- `type`: `"command"` for bash or `"prompt"` for LLM-based evaluation
+- `type`: `"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` where the event supports it
 - `command`: Bash command to execute
 - `prompt`: LLM prompt for evaluation (prompt-based hooks only)
 - `timeout`: Optional timeout in seconds (default: 60)
@@ -59,6 +64,10 @@ Hooks are configured in settings files:
 
 ## Hook Events
 
+Claude Code's current event surface is broader than the detailed subset below. In
+particular, `TeammateIdle` and `TaskCompleted` are supported lifecycle events used
+by Codeman; they are not stale or plugin-defined event names.
+
 ### PreToolUse
 
 **When**: After Claude creates tool parameters, before processing the tool call.
@@ -66,15 +75,17 @@ Hooks are configured in settings files:
 **Use Cases**: Approval, denial, or modification of tool calls.
 
 **Common Matchers**:
+
 - `Bash` - Shell commands
 - `Write` - File writing
 - `Edit` - File editing
 - `Read` - File reading
-- `Task` - Subagent tasks
+- `Agent` - Subagent tasks
 - `WebFetch`, `WebSearch` - Web operations
 - `mcp__<server>__<tool>` - MCP tools
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
@@ -96,13 +107,14 @@ Hooks are configured in settings files:
 **Use Cases**: Auto-approve or deny permissions.
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "PermissionRequest",
     "decision": {
       "behavior": "allow|deny",
-      "updatedInput": { },
+      "updatedInput": {},
       "message": "deny reason",
       "interrupt": false
     }
@@ -117,6 +129,7 @@ Hooks are configured in settings files:
 **Use Cases**: Provide feedback, run formatters/linters, log operations.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -128,15 +141,30 @@ Hooks are configured in settings files:
 }
 ```
 
+#### Asynchronous Rewake
+
+Command hooks can set `"asyncRewake": true` to run asynchronously and wake an
+idle Claude turn when the hook exits with code 2. The hook's stderr is delivered
+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.
+
 ### Notification
 
 **When**: When Claude Code sends notifications.
 
 **Matchers**:
+
 - `permission_prompt`
 - `idle_prompt`
 - `auth_success`
 - `elicitation_dialog`
+- `elicitation_complete`
+- `elicitation_response`
 
 ### UserPromptSubmit
 
@@ -145,6 +173,7 @@ Hooks are configured in settings files:
 **Use Cases**: Add context, validate, or block prompts.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -165,6 +194,7 @@ Hooks are configured in settings files:
 **Use Cases**: **Ralph Wiggum loops** - block exit and refeed prompt.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -173,6 +203,7 @@ Hooks are configured in settings files:
 ```
 
 Or to allow exit:
+
 ```json
 {
   "continue": true,
@@ -184,15 +215,32 @@ Or to allow exit:
 
 ### SubagentStop
 
-**When**: When a subagent (Task tool call) finishes responding.
+**When**: When a subagent (Agent tool call) finishes responding.
 
 **Use Cases**: Control nested loops, verify subagent output.
 
+### TeammateIdle
+
+**When**: When an agent-team teammate is about to go idle.
+
+**Use Cases**: Reassign work, continue a teammate loop, or notify an orchestrator.
+
+**Matcher Support**: None. The hook fires for every occurrence.
+
+### TaskCompleted
+
+**When**: When a task is about to be marked completed.
+
+**Use Cases**: Validate completion or forward team progress to an external UI.
+
+**Matcher Support**: None. The hook fires for every occurrence.
+
 ### PreCompact
 
 **When**: Before a compact operation.
 
 **Matchers**:
+
 - `manual` - Invoked from `/compact`
 - `auto` - Invoked from auto-compact
 
@@ -201,6 +249,7 @@ Or to allow exit:
 **When**: When Claude Code starts or resumes a session.
 
 **Matchers**:
+
 - `startup` - Fresh start
 - `resume` - From `--resume`, `--continue`, or `/resume`
 - `clear` - From `/clear`
@@ -209,6 +258,7 @@ Or to allow exit:
 **Use Cases**: Load development context, set environment variables.
 
 **Persisting Environment Variables**:
+
 ```bash
 #!/bin/bash
 if [ -n "$CLAUDE_ENV_FILE" ]; then
@@ -219,6 +269,7 @@ exit 0
 ```
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
@@ -233,6 +284,7 @@ exit 0
 **When**: When a session ends.
 
 **Reason Values**:
+
 - `clear`
 - `logout`
 - `prompt_input_exit`
@@ -254,7 +306,7 @@ Hooks receive JSON via stdin with common fields:
   "permission_mode": "default",
   "hook_event_name": "PreToolUse",
   "tool_name": "Bash",
-  "tool_input": { },
+  "tool_input": {},
   "tool_use_id": "toolu_01ABC123..."
 }
 ```
@@ -262,6 +314,7 @@ Hooks receive JSON via stdin with common fields:
 ### Tool-Specific Input
 
 **Bash**:
+
 ```json
 {
   "tool_name": "Bash",
@@ -274,6 +327,7 @@ Hooks receive JSON via stdin with common fields:
 ```
 
 **Write**:
+
 ```json
 {
   "tool_name": "Write",
@@ -285,6 +339,7 @@ Hooks receive JSON via stdin with common fields:
 ```
 
 **Edit**:
+
 ```json
 {
   "tool_name": "Edit",
@@ -302,11 +357,11 @@ Hooks receive JSON via stdin with common fields:
 
 ### Exit Codes
 
-| Code | Behavior |
-|------|----------|
-| 0 | Success. `stdout` processed (shown in verbose or added as context) |
-| 2 | Blocking error. Only `stderr` used. Blocks tool/prompt based on event |
-| Other | Non-blocking error. `stderr` shown in verbose, execution continues |
+| Code  | Behavior                                                              |
+| ----- | --------------------------------------------------------------------- |
+| 0     | Success. `stdout` processed (shown in verbose or added as context)    |
+| 2     | Blocking error. Only `stderr` used. Blocks tool/prompt based on event |
+| Other | Non-blocking error. `stderr` shown in verbose, execution continues    |
 
 ### JSON Output (Exit Code 0)
 
@@ -323,7 +378,12 @@ Hooks receive JSON via stdin with common fields:
 
 ## Prompt-Based Hooks
 
-For Stop and SubagentStop events, you can use LLM-based evaluation:
+Prompt and agent handlers are supported by decision-oriented events including
+`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`,
+`PostToolBatch`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `TaskCreated`, and
+`TaskCompleted`. Check the upstream reference before choosing a handler type.
+
+For example, a Stop event can use LLM-based evaluation:
 
 ```json
 {
@@ -344,6 +404,7 @@ For Stop and SubagentStop events, you can use LLM-based evaluation:
 ```
 
 **LLM Response Format**:
+
 ```json
 {
   "ok": true,
@@ -362,17 +423,18 @@ Hooks can be defined in Skills, Agents, and Slash Commands using frontmatter:
 name: secure-operations
 hooks:
   PreToolUse:
-    - matcher: "Bash"
+    - matcher: 'Bash'
       hooks:
         - type: command
-          command: "./scripts/security-check.sh"
+          command: './scripts/security-check.sh'
 ---
 ```
 
 These hooks:
+
 - Are scoped to the component's lifecycle
 - Only run when that component is active
-- Support: PreToolUse, PostToolUse, Stop
+- Support all hook events; a subagent-scoped `Stop` is converted to `SubagentStop`
 
 ---
 
@@ -550,11 +612,11 @@ exit 0
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `CLAUDE_PROJECT_DIR` | Project root directory |
-| `CLAUDE_CODE_REMOTE` | `"true"` for web, empty for CLI |
-| `CLAUDE_ENV_FILE` | Path to write persistent env vars (SessionStart) |
+| Variable             | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `CLAUDE_PROJECT_DIR` | Project root directory                           |
+| `CLAUDE_CODE_REMOTE` | `"true"` for web, empty for CLI                  |
+| `CLAUDE_ENV_FILE`    | Path to write persistent env vars (SessionStart) |
 
 ---
 
@@ -593,4 +655,4 @@ Use `/hooks` command to view registered hooks and make changes.
 
 ---
 
-*Source: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)*
+_Source: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)_

package-lock.json

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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.9.4",
+  "version": "1.9.6",
   "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/config/auth-config.ts

@@ -31,5 +31,10 @@ export const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
 // Hooks
 // ============================================================================
 
-/** Timeout for Claude Code hook curl commands (ms) */
-export const HOOK_TIMEOUT_MS = 10000;
+/**
+ * Timeout for Claude Code hook curl commands, in SECONDS: the hook `timeout`
+ * field is seconds (the CLI multiplies by 1000). The predecessor constant
+ * `HOOK_TIMEOUT_MS = 10000` fed the same field, so those hooks effectively had a
+ * ~2.8-hour timeout; 10 seconds is the originally intended budget.
+ */
+export const HOOK_TIMEOUT_SECONDS = 10;

src/hooks-config.ts

@@ -16,9 +16,9 @@
  * `stop`, `teammate_idle`, `task_completed`
  *
  * Hook categories: `Notification` (3 matchers), `Stop` (1), `TeammateIdle` (1),
- * `TaskCompleted` (1)
+ * `TaskCompleted` (1), `PostToolUse` (1 self-contained background Bash rewake)
  *
- * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_MS)
+ * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_SECONDS)
  * @consumedby web/server (session creation), session-cli-builder (env setup)
  *
  * @module hooks-config
@@ -29,7 +29,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import type { HookEventType } from './types.js';
-import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
+import { HOOK_TIMEOUT_SECONDS } from './config/auth-config.js';
 
 /**
  * Serializes read-modify-write access to a `settings.local.json` path. Every
@@ -40,6 +40,104 @@ import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
  * are independent; the map self-prunes when a path's chain goes idle.
  */
 const settingsWriteLocks = new Map<string, Promise<unknown>>();
+/**
+ * Version-agnostic ownership prefix: every rewake script version embeds a marker
+ * starting with this, and `isCodemanHookHandler` matches on the prefix. That way a
+ * version bump replaces the old handler instead of duplicating it (matching on the
+ * full versioned marker would disown every older script).
+ */
+const BACKGROUND_WAKE_MARKER_PREFIX = 'CODEMAN_BACKGROUND_REWAKE_V';
+/**
+ * Current script version. Bump the suffix whenever `generateBackgroundWakeScript`
+ * 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_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).
+ * 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.
+ *
+ * Self-terminating: Claude Code enforces the hook timeout, but the helper does not
+ * rely on it. It exits on its own deadline (same budget) and when orphaned
+ * (`ppid === 1`), so a dead session cannot leave a poller stat-ing the transcript
+ * forever. The ppid check misses subreaper setups; the deadline is the backstop.
+ */
+export function generateBackgroundWakeScript(): string {
+  return [
+    "const fs = require('node:fs');",
+    `const ${BACKGROUND_WAKE_MARKER} = true;`,
+    `const deadline = Date.now() + ${BACKGROUND_WAKE_TIMEOUT_SECONDS} * 1000;`,
+    'let input = {};',
+    "try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }",
+    'function findTaskId(value) {',
+    "  const idKeys = new Set(['taskId', 'task_id', 'shellId', 'shell_id', 'backgroundTaskId', 'background_task_id']);",
+    '  const stack = [value];',
+    '  const seen = new Set();',
+    '  while (stack.length > 0) {',
+    '    const current = stack.pop();',
+    "    if (!current || typeof current !== 'object' || seen.has(current)) continue;",
+    '    seen.add(current);',
+    '    for (const [key, nested] of Object.entries(current)) {',
+    "      if (idKeys.has(key) && typeof nested === 'string' && /^[A-Za-z0-9_-]+$/.test(nested)) return nested;",
+    "      if (nested && typeof nested === 'object') stack.push(nested);",
+    '    }',
+    '  }',
+    "  const serialized = JSON.stringify(value ?? '');",
+    '  const messageMatch = serialized.match(/Command running in background with ID:\\s*([A-Za-z0-9_-]+)/i);',
+    '  if (messageMatch) return messageMatch[1];',
+    '  const pathMatch = serialized.match(/[\\\\/]tasks[\\\\/]([A-Za-z0-9_-]+)\\.output/i);',
+    '  return pathMatch ? pathMatch[1] : null;',
+    '}',
+    'const taskId = findTaskId(input.tool_response);',
+    "const transcriptPath = typeof input.transcript_path === 'string' ? input.transcript_path : '';",
+    'if (!taskId || !transcriptPath) process.exit(0);',
+    'let position = 0;',
+    'try { position = Math.max(0, fs.statSync(transcriptPath).size - 262144); } catch { process.exit(0); }',
+    "let carry = '';",
+    '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.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.');",
+    '    process.exit(2);',
+    '  }',
+    '}',
+    'function poll() {',
+    '  if (Date.now() > deadline || process.ppid === 1) process.exit(0);',
+    '  try {',
+    '    const size = fs.statSync(transcriptPath).size;',
+    "    if (size < position) { position = 0; carry = ''; }",
+    '    if (size > position) {',
+    '      const length = Math.min(size - position, 1048576);',
+    '      const buffer = Buffer.allocUnsafe(length);',
+    "      const fd = fs.openSync(transcriptPath, 'r');",
+    '      const bytes = fs.readSync(fd, buffer, 0, length, position);',
+    '      fs.closeSync(fd);',
+    '      position += bytes;',
+    "      carry = (carry + buffer.subarray(0, bytes).toString('utf8')).slice(-262144);",
+    '      inspect(carry);',
+    '    }',
+    '  } catch {}',
+    '  setTimeout(poll, 1000);',
+    '}',
+    'poll();',
+  ].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
@@ -86,36 +184,118 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
       Notification: [
         {
           matcher: 'idle_prompt',
-          hooks: [{ type: 'command', command: curlCmd('idle_prompt'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('idle_prompt'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
         {
           matcher: 'permission_prompt',
-          hooks: [{ type: 'command', command: curlCmd('permission_prompt'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('permission_prompt'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
         {
           matcher: 'elicitation_dialog',
-          hooks: [{ type: 'command', command: curlCmd('elicitation_dialog'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('elicitation_dialog'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       Stop: [
         {
-          hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       TeammateIdle: [
         {
-          hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       TaskCompleted: [
         {
-          hooks: [{ type: 'command', command: curlCmd('task_completed'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('task_completed'), timeout: HOOK_TIMEOUT_SECONDS }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: 'node',
+              args: ['-e', generateBackgroundWakeScript()],
+              asyncRewake: true,
+              timeout: BACKGROUND_WAKE_TIMEOUT_SECONDS,
+            },
+          ],
         },
       ],
     },
   };
 }
 
+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);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace only Codeman-owned command handlers while preserving user events,
+ * matcher entries, and sibling handlers in mixed entries.
+ */
+function mergeCodemanHooks(existingValue: unknown, generated: Record<string, unknown[]>): Record<string, unknown[]> {
+  const existing =
+    existingValue && typeof existingValue === 'object' && !Array.isArray(existingValue)
+      ? (existingValue as Record<string, unknown>)
+      : {};
+  const merged: Record<string, unknown[]> = {};
+
+  for (const eventName of new Set([...Object.keys(existing), ...Object.keys(generated)])) {
+    const existingEntries = Array.isArray(existing[eventName]) ? (existing[eventName] as unknown[]) : [];
+    const generatedEntries = generated[eventName];
+    if (!generatedEntries) {
+      merged[eventName] = existingEntries;
+      continue;
+    }
+
+    const entries: unknown[] = [];
+    let insertedGenerated = false;
+    for (const entry of existingEntries) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        if (!isCodemanHookHandler(entry)) entries.push(entry);
+        continue;
+      }
+
+      const record = entry as Record<string, unknown>;
+      if (!Array.isArray(record.hooks)) {
+        if (isCodemanHookHandler(record)) {
+          if (!insertedGenerated) {
+            entries.push(...generatedEntries);
+            insertedGenerated = true;
+          }
+        } else {
+          entries.push(entry);
+        }
+        continue;
+      }
+
+      const retainedHandlers = record.hooks.filter((handler) => !isCodemanHookHandler(handler));
+      const removedCodemanHandler = retainedHandlers.length !== record.hooks.length;
+      if (removedCodemanHandler && !insertedGenerated) {
+        entries.push(...generatedEntries);
+        insertedGenerated = true;
+      }
+      if (retainedHandlers.length > 0 || !removedCodemanHandler) {
+        entries.push(retainedHandlers.length === record.hooks.length ? entry : { ...record, hooks: retainedHandlers });
+      }
+    }
+
+    if (!insertedGenerated) entries.push(...generatedEntries);
+    merged[eventName] = entries;
+  }
+
+  return merged;
+}
+
 /**
  * Remove a subset of env keys from .claude/settings.local.json.env if present.
  * Used during the disk→tmux-setenv migration: when the caller is actively setting
@@ -237,29 +417,31 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
     }
 
     const hooksConfig = generateHooksConfig();
-    const merged = { ...existing, ...hooksConfig };
+    const merged = {
+      ...existing,
+      hooks: mergeCodemanHooks(existing.hooks, hooksConfig.hooks),
+    };
 
     await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
   });
 }
 
 /**
- * Self-heal a case's hooks block so the COD-91 unconditional hook-secret gate keeps
- * accepting its hook events.
+ * Self-heal a case's Codeman-owned hooks block.
  *
  * `writeHooksConfig` only runs when a case is first CREATED. Cases created before the
  * 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. This refreshes the hooks block so those stale curls regain the header.
+ * gate requires it unconditionally (COD-91), silently 401 on a password-protected install.
+ * Older Codeman blocks also lack the background Bash async-rewake hook. Refresh either
+ * stale shape on launch so existing cases gain both current behaviors.
  *
  * Deliberately surgical: regenerates ONLY when settings.local.json already contains
- * Codeman's own hook curls (they target `/api/hook-event`) that lack the secret header.
- * No-op when the file/hooks are absent (we never impose hooks on a user who removed
- * them), when the hooks aren't ours, or when the secret is already present — so it never
- * clobbers a user's customizations and is cheap enough to call on every Claude spawn.
+ * Codeman's own hook curls (they target `/api/hook-event`) and they are stale. No-op
+ * when the file/hooks are absent (we never impose hooks on a user who removed them) or
+ * when the hooks aren't ours, so it is cheap enough to call on every Claude spawn.
  */
-export async function refreshStaleHookSecret(casePath: string): Promise<void> {
+export async function refreshStaleCodemanHooks(casePath: string): Promise<void> {
   const settingsPath = join(casePath, '.claude', 'settings.local.json');
   if (!existsSync(settingsPath)) return;
   await withSettingsLock(settingsPath, async () => {
@@ -274,8 +456,13 @@ export async function refreshStaleHookSecret(casePath: string): Promise<void> {
     // The generated curl carries this header literal (see generateHooksConfig); its
     // absence on our own hooks means they predate COD-54 and need regenerating.
     const hasSecret = hooksJson.includes('X-Codeman-Hook-Secret');
-    if (!isOurs || hasSecret) return;
-    const merged = { ...existing, ...generateHooksConfig() };
+    const hasBackgroundWake = hooksJson.includes(BACKGROUND_WAKE_MARKER);
+    if (!isOurs || (hasSecret && hasBackgroundWake)) return;
+    const generated = generateHooksConfig();
+    const merged = {
+      ...existing,
+      hooks: mergeCodemanHooks(existing.hooks, generated.hooks),
+    };
     await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
   });
 }

src/session.ts

@@ -180,6 +180,13 @@ export function isAltScreenStripMode(mode: SessionMode): boolean {
 const DEFAULT_PTY_COLS = 120;
 const DEFAULT_PTY_ROWS = 40;
 const TMUX_DISPLAY_TIMEOUT_MS = 2000;
+const IS_TEST_MODE = !!process.env.VITEST;
+/**
+ * Echo transport for the test-mode PTY attach. Raw mode disables the tty line
+ * discipline, so each input byte flows back exactly once and immediately; without
+ * it, tty echo doubles every line and canonical buffering holds bytes until Enter.
+ */
+const TEST_PTY_SCRIPT = 'if (process.stdin.isTTY) process.stdin.setRawMode(true); process.stdin.pipe(process.stdout);';
 /** Delay before the in-container Claude CLI version probe (lets the container start). */
 const DOCKER_CLI_VERSION_PROBE_DELAY_MS = 3000;
 
@@ -1248,16 +1255,23 @@ export class Session extends EventEmitter {
       // No extra sleep — createSession() already waits for tmux readiness
     }
 
-    // Attach to the mux session via PTY
-    // Prevent tmux from letting the newest browser attach dictate global window
-    // size; accepted Codeman resize events update it explicitly below.
-    mux.setManualWindowSize?.(this._muxSession!.muxName);
+    // Integration tests need a live input/output transport without attaching to
+    // the host's tmux server or agent CLI. Production still uses the real mux.
+    if (!IS_TEST_MODE) {
+      // Prevent tmux from letting the newest browser attach dictate global window
+      // size; accepted Codeman resize events update it explicitly below.
+      mux.setManualWindowSize?.(this._muxSession!.muxName);
+    }
     // Query existing tmux window size so re-attach matches (avoids flicker from 120x40 default).
     // MUST go through the dedicated socket (mux.muxSocket); a bare `tmux display` hits the
     // default server, always fails for our socketed sessions, and silently falls back to 120x40.
-    const { cols: ptyCols, rows: ptyRows } = queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
+    const { cols: ptyCols, rows: ptyRows } = IS_TEST_MODE
+      ? { cols: DEFAULT_PTY_COLS, rows: DEFAULT_PTY_ROWS }
+      : queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
+    const attachCommand = IS_TEST_MODE ? process.execPath : mux.getAttachCommand();
+    const attachArgs = IS_TEST_MODE ? ['-e', TEST_PTY_SCRIPT] : mux.getAttachArgs(this._muxSession!.muxName);
     try {
-      this.ptyProcess = pty.spawn(mux.getAttachCommand(), mux.getAttachArgs(this._muxSession!.muxName), {
+      this.ptyProcess = pty.spawn(attachCommand, attachArgs, {
         name: 'xterm-256color',
         cols: ptyCols,
         rows: ptyRows,
@@ -2683,7 +2697,7 @@ export class Session extends EventEmitter {
     if (this.ptyProcess && (dimsChanged || options.force)) {
       this._ptyCols = cols;
       this._ptyRows = rows;
-      if (this._mux && this._muxSession) {
+      if (!IS_TEST_MODE && this._mux && this._muxSession) {
         this._mux.resizeWindow?.(this._muxSession.muxName, cols, rows);
       }
       this.ptyProcess.resize(cols, rows);

src/transcript-watcher.ts

@@ -40,6 +40,7 @@ interface TranscriptContentBlock {
   text?: string;
   name?: string;
   input?: Record<string, unknown>;
+  tool_use_id?: string;
   content?: string;
   is_error?: boolean;
 }
@@ -328,10 +329,7 @@ export class TranscriptWatcher extends EventEmitter {
         this.handleResultEntry(entry);
         break;
       case 'user':
-        // User message means new turn, reset some state
-        this.state.isComplete = false;
-        this.state.hasError = false;
-        this.state.errorMessage = null;
+        this.handleUserEntry(entry);
         break;
       case 'system':
         // System messages are informational
@@ -360,23 +358,42 @@ export class TranscriptWatcher extends EventEmitter {
           this.state.currentTool = block.name;
           this.emit('transcript:tool_start', block.name);
         } else if (block.type === 'tool_result') {
-          // Tool completed
-          const wasError = block.is_error === true;
-          const toolName = this.state.currentTool;
-          this.state.toolExecuting = false;
-          this.state.currentTool = null;
-          if (toolName) {
-            this.emit('transcript:tool_end', toolName, wasError);
-          }
-          if (wasError && block.content) {
-            this.state.hasError = true;
-            this.state.errorMessage = String(block.content).slice(0, 200);
-          }
+          this.handleToolResult(block);
         }
       }
     }
   }
 
+  private handleUserEntry(entry: TranscriptEntry): void {
+    // A user-authored prompt starts a turn, while Claude tool results also use
+    // user entries. Reset turn state first, then close any completed tool.
+    this.state.isComplete = false;
+    this.state.hasError = false;
+    this.state.errorMessage = null;
+
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'tool_result') {
+        this.handleToolResult(block);
+      }
+    }
+  }
+
+  private handleToolResult(block: TranscriptContentBlock): void {
+    const wasError = block.is_error === true;
+    const toolName = this.state.currentTool;
+    this.state.toolExecuting = false;
+    this.state.currentTool = null;
+    if (toolName) {
+      this.emit('transcript:tool_end', toolName, wasError);
+    }
+    if (wasError && block.content) {
+      this.state.hasError = true;
+      this.state.errorMessage = String(block.content).slice(0, 200);
+    }
+  }
+
   private handleResultEntry(entry: TranscriptEntry): void {
     // Result entry indicates completion
     this.state.isComplete = true;

src/web/public/index.html

@@ -1848,7 +1848,7 @@
               <input type="checkbox" id="eventIdleAudio">
 
               <div class="event-label">Response complete</div>
-              <input type="checkbox" id="eventStopEnabled" checked>
+              <input type="checkbox" id="eventStopEnabled">
               <input type="checkbox" id="eventStopBrowser">
               <input type="checkbox" id="eventStopPush">
               <input type="checkbox" id="eventStopAudio">

src/web/public/notification-manager.js

@@ -9,7 +9,7 @@
  *   5. Audio alerts (Web Audio API beep, user-opt-in)
  *
  * Features:
- * - Per-event-type preferences (enabled, browser, audio, push) with v1→v4 migration
+ * - Per-event-type preferences (enabled, browser, audio, push) with v1→v5 migration
  * - Device-specific defaults (notifications disabled on mobile by default)
  * - 5s notification grouping window to batch rapid-fire events
  * - 100-notification cap with oldest eviction
@@ -21,7 +21,7 @@
  * @param {CodemanApp} app - Reference to the main app instance
  *
  * @dependency constants.js (STUCK_THRESHOLD_DEFAULT_MS, timing constants)
- * @dependency mobile-handlers.js (MobileDetection.getDeviceType for device-specific defaults)
+ * @dependency mobile-handlers.js (MobileDetection stable handheld identity/device type)
  * @loadorder 4 of 15 — loaded after voice-input.js, before keyboard-accessory.js
  */
 
@@ -65,12 +65,19 @@ class NotificationManager {
     });
   }
 
-  loadPreferences() {
+  _usesMobilePreferences() {
+    return (
+      MobileDetection.isHandheldDevice?.() ??
+      MobileDetection.getDeviceType() === 'mobile'
+    );
+  }
+
+  getDefaultPreferences() {
     const defaultEventTypes = {
       permission_prompt: { enabled: true, browser: true, audio: true, push: false },
       elicitation_dialog: { enabled: true, browser: true, audio: true, push: false },
       idle_prompt: { enabled: true, browser: true, audio: false, push: false },
-      stop: { enabled: true, browser: false, audio: false, push: false },
+      stop: { enabled: false, browser: false, audio: false, push: false },
       session_error: { enabled: true, browser: true, audio: false, push: false },
       respawn_cycle: { enabled: true, browser: false, audio: false, push: false },
       token_milestone: { enabled: true, browser: false, audio: false, push: false },
@@ -80,8 +87,8 @@ class NotificationManager {
     };
 
     // Device-specific defaults: mobile has notifications disabled by default
-    const isMobile = MobileDetection.getDeviceType() === 'mobile';
-    const defaults = {
+    const isMobile = this._usesMobilePreferences();
+    return {
       enabled: !isMobile, // Disabled on mobile by default
       browserNotifications: !isMobile,
       audioAlerts: false,
@@ -92,51 +99,97 @@ class NotificationManager {
       muteInfo: false,
       // Per-event-type preferences
       eventTypes: defaultEventTypes,
-      _version: 4,
+      _version: 5,
     };
+  }
+
+  /**
+   * Apply the complete v1→v5 migration to either local or server-hydrated
+   * preferences. Keeping one normalization path prevents fresh browsers from
+   * reviving retired drawer-only hook defaults.
+   */
+  normalizePreferences(rawPreferences) {
+    const defaults = this.getDefaultPreferences();
+    if (
+      !rawPreferences ||
+      typeof rawPreferences !== 'object' ||
+      Array.isArray(rawPreferences)
+    ) {
+      return defaults;
+    }
+
+    const prefs = {
+      ...rawPreferences,
+      eventTypes:
+        rawPreferences.eventTypes &&
+        typeof rawPreferences.eventTypes === 'object' &&
+        !Array.isArray(rawPreferences.eventTypes)
+          ? Object.fromEntries(
+              Object.entries(rawPreferences.eventTypes).map(([key, value]) => [
+                key,
+                value && typeof value === 'object' ? { ...value } : value,
+              ])
+            )
+          : undefined,
+    };
+    const version = Number.isInteger(prefs._version) ? prefs._version : 0;
+
+    // Migrate: v1 had browserNotifications defaulting to false
+    if (version < 2) {
+      prefs.browserNotifications = true;
+    }
+    // Migrate: v2 -> v3 adds eventTypes
+    if (version < 3) {
+      prefs.eventTypes = { ...defaults.eventTypes };
+    }
+    // Migrate: v3 -> v4 adds push field to all eventTypes
+    if (version < 4 && prefs.eventTypes) {
+      for (const key of Object.keys(prefs.eventTypes)) {
+        if (prefs.eventTypes[key] && prefs.eventTypes[key].push === undefined) {
+          prefs.eventTypes[key].push = false;
+        }
+      }
+    }
+    // Migrate: v4 -> v5 removes the drawer-only Response Complete default.
+    // Preserve users who opted into any external delivery channel.
+    if (version < 5) {
+      const stopPref = prefs.eventTypes?.stop;
+      if (
+        stopPref?.enabled === true &&
+        !stopPref.browser &&
+        !stopPref.audio &&
+        !stopPref.push
+      ) {
+        stopPref.enabled = false;
+      }
+    }
+
+    return {
+      ...defaults,
+      ...prefs,
+      eventTypes: { ...defaults.eventTypes, ...prefs.eventTypes },
+      _version: 5,
+    };
+  }
+
+  loadPreferences() {
     try {
       const storageKey = this.getStorageKey();
       const saved = localStorage.getItem(storageKey);
       if (saved) {
-        const prefs = JSON.parse(saved);
-        // Migrate: v1 had browserNotifications defaulting to false
-        if (!prefs._version || prefs._version < 2) {
-          prefs.browserNotifications = true;
-          prefs._version = 2;
-        }
-        // Migrate: v2 -> v3 adds eventTypes
-        if (prefs._version < 3) {
-          prefs.eventTypes = defaultEventTypes;
-          prefs._version = 3;
-          localStorage.setItem(storageKey, JSON.stringify(prefs));
-        }
-        // Migrate: v3 -> v4 adds push field to all eventTypes
-        if (prefs._version < 4) {
-          if (prefs.eventTypes) {
-            for (const key of Object.keys(prefs.eventTypes)) {
-              if (prefs.eventTypes[key] && prefs.eventTypes[key].push === undefined) {
-                prefs.eventTypes[key].push = false;
-              }
-            }
-          }
-          prefs._version = 4;
-          localStorage.setItem(storageKey, JSON.stringify(prefs));
-        }
-        // Merge with defaults to ensure all eventTypes exist
-        return {
-          ...defaults,
-          ...prefs,
-          eventTypes: { ...defaultEventTypes, ...prefs.eventTypes },
-        };
+        const normalized = this.normalizePreferences(JSON.parse(saved));
+        localStorage.setItem(storageKey, JSON.stringify(normalized));
+        return normalized;
       }
     } catch (_e) { /* ignore */ }
-    return defaults;
+    return this.getDefaultPreferences();
   }
 
   // Get storage key for notification prefs (device-specific)
   getStorageKey() {
-    const isMobile = MobileDetection.getDeviceType() === 'mobile';
-    return isMobile ? 'codeman-notification-prefs-mobile' : 'codeman-notification-prefs';
+    return this._usesMobilePreferences()
+      ? 'codeman-notification-prefs-mobile'
+      : 'codeman-notification-prefs';
   }
 
   savePreferences() {
@@ -163,8 +216,10 @@ class NotificationManager {
       'exit-gate': 'ralph_complete',
       'subagent-spawn': 'subagent_spawn',
       'subagent-complete': 'subagent_complete',
-      'hook-teammate-idle': 'idle_prompt',
-      'hook-task-completed': 'stop',
+      // Team lifecycle hooks are agent activity, not session-idle/stop alerts.
+      // Reuse the existing opt-in agent categories instead of making them noisy.
+      'hook-teammate-idle': 'subagent_spawn',
+      'hook-task-completed': 'subagent_complete',
     };
     const eventTypeKey = categoryToEventType[category] || category;
 

src/web/public/settings-ui.js

@@ -410,7 +410,7 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('eventIdleAudio').checked = idlePref.audio ?? false;
     // Response complete (stop)
     const stopPref = eventTypes.stop || {};
-    document.getElementById('eventStopEnabled').checked = stopPref.enabled ?? true;
+    document.getElementById('eventStopEnabled').checked = stopPref.enabled ?? false;
     document.getElementById('eventStopBrowser').checked = stopPref.browser ?? false;
     document.getElementById('eventStopPush').checked = stopPref.push ?? false;
     document.getElementById('eventStopAudio').checked = stopPref.audio ?? false;
@@ -1589,7 +1589,7 @@ Object.assign(CodemanApp.prototype, {
           audio: document.getElementById('eventSubagentAudio').checked,
         },
       },
-      _version: 4,
+      _version: 5,
     };
     if (this.notificationManager) {
       this.notificationManager.preferences = notifPrefsToSave;
@@ -2295,7 +2295,8 @@ Object.assign(CodemanApp.prototype, {
         if (notificationPreferences && this.notificationManager) {
           const localNotifPrefs = localStorage.getItem(this.notificationManager.getStorageKey());
           if (!localNotifPrefs) {
-            this.notificationManager.preferences = notificationPreferences;
+            this.notificationManager.preferences =
+              this.notificationManager.normalizePreferences(notificationPreferences);
             this.notificationManager.savePreferences();
           }
         }

src/web/routes/session-routes.ts

@@ -65,7 +65,7 @@ import {
   updateCaseModel,
   stripCaseEnvKeys,
   applyStatusLineConfig,
-  refreshStaleHookSecret,
+  refreshStaleCodemanHooks,
 } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { imageWatcher } from '../../image-watcher.js';
@@ -445,7 +445,7 @@ export function registerSessionRoutes(
     // unconditional hook-secret gate keeps accepting its hook events. No-op for fresh
     // cases (writeHooksConfig already wrote the secret) and for non-Codeman/absent hooks.
     if ((body.mode ?? 'claude') === 'claude') {
-      await refreshStaleHookSecret(workingDir).catch(() => {});
+      await refreshStaleCodemanHooks(workingDir).catch(() => {});
     }
 
     // Check OpenCode availability if requested
@@ -2170,7 +2170,7 @@ export function registerSessionRoutes(
       // now-unconditional hook-secret gate keeps accepting its hook events. No-op when
       // the hooks aren't ours or already carry the secret. Skipped for remote cases —
       // resolvedCasePath is a REMOTE path that doesn't exist on the local filesystem.
-      await refreshStaleHookSecret(resolvedCasePath).catch(() => {});
+      await refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
     }
 
     // Docker cases: the workspace is a REAL host dir bind-mounted into the container.
@@ -2186,7 +2186,7 @@ export function registerSessionRoutes(
         if (!existsSync(join(resolvedCasePath, '.claude', 'settings.local.json'))) {
           await writeHooksConfig(resolvedCasePath);
         } else {
-          await refreshStaleHookSecret(resolvedCasePath).catch(() => {});
+          await refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
         }
       } catch {
         /* non-fatal — the session still runs, hooks may be degraded */

test/hook-secret-selfheal.test.ts

@@ -1,10 +1,10 @@
 /**
- * COD-91 — `refreshStaleHookSecret` self-heal.
+ * COD-91 — `refreshStaleCodemanHooks` self-heal.
  *
  * Making the hook-event secret unconditionally required (PR #127) would silently 401 the
  * hook curls baked into cases created before the secret header existed (COD-54). Those
  * curls live in `.claude/settings.local.json` and `writeHooksConfig` only runs at case
- * CREATION, so existing cases never refresh. `refreshStaleHookSecret` regenerates the
+ * CREATION, so existing cases never refresh. `refreshStaleCodemanHooks` regenerates the
  * hooks block on session spawn — but ONLY when the case already holds Codeman's own
  * pre-secret hook curls, never clobbering a user's customizations.
  *
@@ -15,7 +15,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { refreshStaleHookSecret } from '../src/hooks-config.js';
+import { refreshStaleCodemanHooks } from '../src/hooks-config.js';
 
 const SECRET_HEADER = 'X-Codeman-Hook-Secret';
 
@@ -41,7 +41,7 @@ function staleCodemanHooks() {
   };
 }
 
-describe('refreshStaleHookSecret', () => {
+describe('refreshStaleCodemanHooks', () => {
   let dir: string;
   let settingsPath: string;
 
@@ -60,7 +60,7 @@ describe('refreshStaleHookSecret', () => {
       settingsPath,
       JSON.stringify({ env: { CLAUDE_CODE_FOO: '1' }, model: 'opus', hooks: staleCodemanHooks() }, null, 2)
     );
-    await refreshStaleHookSecret(dir);
+    await refreshStaleCodemanHooks(dir);
 
     const after = JSON.parse(readFileSync(settingsPath, 'utf-8'));
     expect(JSON.stringify(after.hooks)).toContain(SECRET_HEADER);
@@ -73,11 +73,11 @@ describe('refreshStaleHookSecret', () => {
   it('leaves a hooks block that already carries the secret unchanged', async () => {
     // Seed with a current block by healing a stale one first, then re-heal: second pass must no-op.
     writeFileSync(settingsPath, JSON.stringify({ hooks: staleCodemanHooks() }, null, 2));
-    await refreshStaleHookSecret(dir);
+    await refreshStaleCodemanHooks(dir);
     const healed = readFileSync(settingsPath, 'utf-8');
     expect(healed).toContain(SECRET_HEADER);
 
-    await refreshStaleHookSecret(dir);
+    await refreshStaleCodemanHooks(dir);
     expect(readFileSync(settingsPath, 'utf-8')).toBe(healed); // byte-identical: no rewrite
   });
 
@@ -88,19 +88,60 @@ describe('refreshStaleHookSecret', () => {
       2
     );
     writeFileSync(settingsPath, foreign);
-    await refreshStaleHookSecret(dir);
+    await refreshStaleCodemanHooks(dir);
     expect(readFileSync(settingsPath, 'utf-8')).toBe(foreign);
   });
 
+  it('preserves user handlers and events in a mixed stale configuration', async () => {
+    const hooks = staleCodemanHooks();
+    hooks.Stop[0].hooks.push({
+      type: 'command',
+      command: './notify-user.sh',
+      timeout: 10,
+    });
+    const customPostToolUse = {
+      matcher: 'Write',
+      hooks: [{ type: 'command', command: './format.sh' }],
+    };
+    const customEvent = [
+      {
+        hooks: [{ type: 'command', command: './audit.sh' }],
+      },
+    ];
+    writeFileSync(
+      settingsPath,
+      JSON.stringify(
+        {
+          hooks: {
+            ...hooks,
+            PostToolUse: [customPostToolUse],
+            CustomEvent: customEvent,
+          },
+        },
+        null,
+        2
+      )
+    );
+
+    await refreshStaleCodemanHooks(dir);
+
+    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.Stop)).toContain('./notify-user.sh');
+    expect(after.hooks.PostToolUse).toEqual(expect.arrayContaining([customPostToolUse]));
+    expect(after.hooks.CustomEvent).toEqual(customEvent);
+  });
+
   it('is a no-op when settings.local.json is absent (does not create one)', async () => {
-    await refreshStaleHookSecret(dir);
+    await refreshStaleCodemanHooks(dir);
     expect(existsSync(settingsPath)).toBe(false);
   });
 
   it('leaves a malformed settings file untouched', async () => {
     const garbage = '{ not valid json';
     writeFileSync(settingsPath, garbage);
-    await refreshStaleHookSecret(dir);
+    await refreshStaleCodemanHooks(dir);
     expect(readFileSync(settingsPath, 'utf-8')).toBe(garbage);
   });
 });

test/hooks-config.test.ts

@@ -9,7 +9,13 @@ import { describe, it, expect, beforeAll, beforeEach, afterAll, afterEach } from
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { generateHooksConfig, writeHooksConfig } from '../src/hooks-config.js';
+import { spawn } from 'node:child_process';
+import {
+  generateBackgroundWakeScript,
+  generateHooksConfig,
+  refreshStaleCodemanHooks,
+  writeHooksConfig,
+} from '../src/hooks-config.js';
 
 describe('generateHooksConfig', () => {
   it('should return an object with hooks key', () => {
@@ -29,6 +35,30 @@ describe('generateHooksConfig', () => {
     expect(config.hooks.Stop).toHaveLength(1);
   });
 
+  it('should configure a self-contained Bash background-task rewake hook', () => {
+    const config = generateHooksConfig();
+    const postToolHooks = config.hooks.PostToolUse as Array<{
+      matcher: string;
+      hooks: Array<{
+        type: string;
+        command: string;
+        args: string[];
+        asyncRewake: boolean;
+        timeout: number;
+      }>;
+    }>;
+
+    expect(postToolHooks).toHaveLength(1);
+    expect(postToolHooks[0].matcher).toBe('Bash');
+    expect(postToolHooks[0].hooks[0]).toMatchObject({
+      type: 'command',
+      command: 'node',
+      asyncRewake: true,
+    });
+    expect(postToolHooks[0].hooks[0].args).toEqual(['-e', generateBackgroundWakeScript()]);
+    expect(postToolHooks[0].hooks[0].timeout).toBeGreaterThanOrEqual(3600);
+  });
+
   it('should configure idle_prompt matcher', () => {
     const config = generateHooksConfig();
     const notifHooks = config.hooks.Notification as Array<{ matcher?: string }>;
@@ -65,10 +95,10 @@ describe('generateHooksConfig', () => {
     expect(notifHooks[0].hooks[0].command).toContain('|| true');
   });
 
-  it('should set timeout to 10000ms', () => {
+  it('should set timeout to 10 seconds (hook timeout fields are seconds)', () => {
     const config = generateHooksConfig();
     const notifHooks = config.hooks.Notification as Array<{ hooks: Array<{ timeout: number }> }>;
-    expect(notifHooks[0].hooks[0].timeout).toBe(10000);
+    expect(notifHooks[0].hooks[0].timeout).toBe(10);
   });
 
   it('should include correct event names in curl payloads', () => {
@@ -157,7 +187,75 @@ describe('writeHooksConfig', () => {
     expect(parsed.hooks).toBeDefined();
   });
 
-  it('should overwrite existing hooks key', async () => {
+  it('should upgrade Codeman-owned hooks that predate background rewake', async () => {
+    const claudeDir = join(testDir, '.claude');
+    const settingsPath = join(claudeDir, 'settings.local.json');
+    mkdirSync(claudeDir, { recursive: true });
+    const oldHooks = generateHooksConfig().hooks;
+    delete oldHooks.PostToolUse;
+    writeFileSync(settingsPath, JSON.stringify({ hooks: oldHooks }, null, 2));
+
+    await refreshStaleCodemanHooks(testDir);
+
+    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');
+  });
+
+  it('should replace an older rewake script version without duplicating it', async () => {
+    const claudeDir = join(testDir, '.claude');
+    const settingsPath = join(claudeDir, 'settings.local.json');
+    mkdirSync(claudeDir, { recursive: true });
+    // Simulate a case healed by the previous release: current curls (secret present)
+    // plus a V1 rewake handler. The version bump must swap the handler in place.
+    const hooks = generateHooksConfig().hooks;
+    hooks.PostToolUse = [
+      {
+        matcher: 'Bash',
+        hooks: [
+          {
+            type: 'command',
+            command: 'node',
+            args: ['-e', 'const CODEMAN_BACKGROUND_REWAKE_V1 = true; process.exit(0);'],
+            asyncRewake: true,
+            timeout: 21600,
+          },
+        ],
+      },
+    ];
+    writeFileSync(settingsPath, JSON.stringify({ hooks }, null, 2));
+
+    await refreshStaleCodemanHooks(testDir);
+
+    const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    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).not.toContain('CODEMAN_BACKGROUND_REWAKE_V1');
+  });
+
+  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');
+    mkdirSync(claudeDir, { recursive: true });
+    const userHooks = {
+      PostToolUse: [
+        {
+          matcher: 'Write',
+          hooks: [{ type: 'command', command: './format.sh' }],
+        },
+      ],
+    };
+    writeFileSync(settingsPath, JSON.stringify({ hooks: userHooks }, null, 2));
+
+    await refreshStaleCodemanHooks(testDir);
+
+    const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    expect(parsed.hooks).toEqual(userHooks);
+  });
+
+  it('should preserve user hook events while installing Codeman hooks', async () => {
     const claudeDir = join(testDir, '.claude');
     mkdirSync(claudeDir, { recursive: true });
     writeFileSync(join(claudeDir, 'settings.local.json'), JSON.stringify({ hooks: { oldHook: [] } }, null, 2));
@@ -165,7 +263,7 @@ describe('writeHooksConfig', () => {
     await writeHooksConfig(testDir);
 
     const parsed = JSON.parse(readFileSync(join(claudeDir, 'settings.local.json'), 'utf-8'));
-    expect(parsed.hooks.oldHook).toBeUndefined();
+    expect(parsed.hooks.oldHook).toEqual([]);
     expect(parsed.hooks.Notification).toBeDefined();
   });
 
@@ -187,6 +285,82 @@ describe('writeHooksConfig', () => {
   });
 });
 
+describe('background task rewake helper', () => {
+  const testDir = join(tmpdir(), 'codeman-background-rewake-test-' + Date.now());
+
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  function runHelper(input: Record<string, unknown>): Promise<{ code: number | null; stderr: string }> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, ['-e', generateBackgroundWakeScript()], {
+        stdio: ['pipe', 'ignore', 'pipe'],
+      });
+      let stderr = '';
+      const timeout = setTimeout(() => {
+        child.kill();
+        reject(new Error('background rewake helper timed out'));
+      }, 5000);
+
+      child.stderr.setEncoding('utf8');
+      child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+      });
+      child.on('error', reject);
+      child.on('close', (code) => {
+        clearTimeout(timeout);
+        resolve({ code, stderr });
+      });
+      child.stdin.end(JSON.stringify(input));
+    });
+  }
+
+  it('exits without waiting for an ordinary Bash result', async () => {
+    const result = await runHelper({
+      transcript_path: join(testDir, 'transcript.jsonl'),
+      tool_response: { stdout: 'ordinary command completed' },
+    });
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  it('exits 2 when the matching background command completes', async () => {
+    const transcriptPath = join(testDir, 'transcript.jsonl');
+    writeFileSync(transcriptPath, '');
+
+    const resultPromise = runHelper({
+      transcript_path: transcriptPath,
+      tool_response: {
+        stdout: 'Command running in background with ID: bg-test-1. Output is being written to: /tmp/bg-test-1.output.',
+      },
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    writeFileSync(
+      transcriptPath,
+      JSON.stringify({
+        type: 'queue-operation',
+        operation: 'enqueue',
+        content:
+          '<task-notification>\n<task-id>bg-test-1</task-id>\n<status>completed</status>\n' +
+          '<output-file>/tmp/bg-test-1.output</output-file>\n</task-notification>',
+      }) + '\n'
+    );
+
+    const result = await resultPromise;
+    expect(result.code).toBe(2);
+    expect(result.stderr).toContain('bg-test-1');
+    expect(result.stderr).toContain('completed');
+    expect(result.stderr).toContain('/tmp/bg-test-1.output');
+  });
+});
+
 // ========== Hook Event API Integration Tests ==========
 // Port 3130 reserved for hooks integration tests
 
@@ -700,7 +874,7 @@ describe('Hook Config Generation - Extended', () => {
       expect(hook.matcher).toBeDefined();
       expect(hook.hooks).toHaveLength(1);
       expect(hook.hooks[0].type).toBe('command');
-      expect(hook.hooks[0].timeout).toBe(10000);
+      expect(hook.hooks[0].timeout).toBe(10);
       expect(hook.hooks[0].command).toBeTruthy();
     }
   });

test/notification-manager-noise.test.ts

@@ -0,0 +1,150 @@
+import { readFileSync } from 'node:fs';
+import { JSDOM } from 'jsdom';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const SOURCE = readFileSync(new URL('../src/web/public/notification-manager.js', import.meta.url), 'utf8');
+
+type EventPreference = {
+  enabled: boolean;
+  browser: boolean;
+  audio: boolean;
+  push: boolean;
+};
+
+type NotificationPreferences = {
+  enabled: boolean;
+  eventTypes: Record<string, EventPreference>;
+  _version: number;
+};
+
+type Manager = {
+  preferences: NotificationPreferences;
+  notifications: unknown[];
+  getStorageKey: () => string;
+  normalizePreferences: (preferences: Record<string, unknown>) => NotificationPreferences;
+  notify: (notification: Record<string, unknown>) => void;
+};
+
+const openWindows: JSDOM[] = [];
+
+function loadManager(
+  saved?: Record<string, unknown>,
+  device: { deviceType?: string; handheld?: boolean } = {}
+): { dom: JSDOM; manager: Manager } {
+  const dom = new JSDOM(
+    '<!doctype html><body><span id="notifBadge"></span><div id="notifList"></div><div id="notifEmpty"></div></body>',
+    {
+      url: 'http://localhost/',
+      runScripts: 'outside-only',
+    }
+  );
+  openWindows.push(dom);
+  const win = dom.window as unknown as Window &
+    typeof globalThis & {
+      MobileDetection: {
+        getDeviceType: () => string;
+        isHandheldDevice?: () => boolean;
+      };
+      STUCK_THRESHOLD_DEFAULT_MS: number;
+      GROUPING_TIMEOUT_MS: number;
+      NOTIFICATION_LIST_CAP: number;
+    };
+  win.MobileDetection = {
+    getDeviceType: () => device.deviceType ?? 'desktop',
+    ...(typeof device.handheld === 'boolean' ? { isHandheldDevice: () => device.handheld === true } : {}),
+  };
+  win.STUCK_THRESHOLD_DEFAULT_MS = 600_000;
+  win.GROUPING_TIMEOUT_MS = 5_000;
+  win.NOTIFICATION_LIST_CAP = 100;
+  win.requestAnimationFrame = ((callback: FrameRequestCallback) => {
+    callback(0);
+    return 1;
+  }) as typeof requestAnimationFrame;
+
+  if (saved) {
+    win.localStorage.setItem('codeman-notification-prefs', JSON.stringify(saved));
+  }
+
+  win.eval(`
+    ${SOURCE}
+    window.__testNotificationManager = NotificationManager;
+  `);
+  const NotificationManager = (
+    win as unknown as {
+      __testNotificationManager: new (app: { sessions: Map<unknown, unknown> }) => Manager;
+    }
+  ).__testNotificationManager;
+  const manager = new NotificationManager({ sessions: new Map() }) as Manager;
+  return { dom, manager };
+}
+
+afterEach(() => {
+  for (const dom of openWindows.splice(0)) dom.window.close();
+});
+
+describe('notification noise defaults', () => {
+  it('keeps response-complete and team lifecycle drawer entries opt-in', () => {
+    const { manager } = loadManager();
+    expect(manager.preferences.eventTypes.stop.enabled).toBe(false);
+
+    for (const category of ['hook-stop', 'hook-teammate-idle', 'hook-task-completed']) {
+      manager.notify({
+        urgency: 'info',
+        category,
+        sessionId: 'session-1',
+        sessionName: 'session',
+        title: category,
+        message: category,
+      });
+    }
+
+    expect(manager.notifications).toHaveLength(0);
+  });
+
+  it('migrates the old drawer-only Stop default but preserves explicit delivery', () => {
+    const quietV4 = {
+      enabled: true,
+      eventTypes: {
+        stop: { enabled: true, browser: false, audio: false, push: false },
+      },
+      _version: 4,
+    };
+    const { manager: quietManager } = loadManager(quietV4);
+    expect(quietManager.preferences.eventTypes.stop.enabled).toBe(false);
+    expect(quietManager.preferences._version).toBe(5);
+
+    const browserV4 = {
+      enabled: true,
+      eventTypes: {
+        stop: { enabled: true, browser: true, audio: false, push: false },
+      },
+      _version: 4,
+    };
+    const { manager: browserManager } = loadManager(browserV4);
+    expect(browserManager.preferences.eventTypes.stop.enabled).toBe(true);
+  });
+
+  it('normalizes server-hydrated v4 preferences through the same quiet migration', () => {
+    const { manager } = loadManager();
+    manager.preferences = manager.normalizePreferences({
+      enabled: true,
+      eventTypes: {
+        stop: { enabled: true, browser: false, audio: false, push: false },
+      },
+      _version: 4,
+    });
+
+    expect(manager.preferences.eventTypes.stop.enabled).toBe(false);
+    expect(manager.preferences._version).toBe(5);
+  });
+
+  it('keeps mobile notification defaults and storage on an unfolded handheld', () => {
+    const { manager } = loadManager(undefined, {
+      deviceType: 'desktop',
+      handheld: true,
+    });
+
+    expect(manager.preferences.enabled).toBe(false);
+    expect(manager.getStorageKey()).toBe('codeman-notification-prefs-mobile');
+  });
+});

test/quick-start.test.ts

@@ -1,11 +1,28 @@
 import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
-import { WebServer } from '../src/web/server.js';
-import { existsSync, rmSync, mkdirSync } from 'node:fs';
+import type { WebServer } from '../src/web/server.js';
+import { existsSync, rmSync, mkdirSync, mkdtempSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { tmpdir } from 'node:os';
 
 const TEST_PORT = 3099;
-const CASES_DIR = join(homedir(), 'codeman-cases');
+const ORIGINAL_HOME = process.env.HOME;
+const TEST_HOME = mkdtempSync(join(tmpdir(), 'codeman-quick-start-'));
+const CASES_DIR = join(TEST_HOME, 'codeman-cases');
+let webServerModule: Promise<typeof import('../src/web/server.js')> | undefined;
+
+process.env.HOME = TEST_HOME;
+
+async function createTestServer(port: number): Promise<WebServer> {
+  webServerModule ??= import('../src/web/server.js');
+  const { WebServer: TestWebServer } = await webServerModule;
+  return new TestWebServer(port, false, true);
+}
+
+afterAll(() => {
+  if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIGINAL_HOME;
+  rmSync(TEST_HOME, { recursive: true, force: true });
+});
 
 describe('Quick Start API', () => {
   let server: WebServer;
@@ -13,7 +30,7 @@ describe('Quick Start API', () => {
   const createdCases: string[] = [];
 
   beforeAll(async () => {
-    server = new WebServer(TEST_PORT, false, true);
+    server = await createTestServer(TEST_PORT);
     await server.start();
     baseUrl = `http://localhost:${TEST_PORT}`;
   });
@@ -147,7 +164,7 @@ describe('Session Management', () => {
   let baseUrl: string;
 
   beforeAll(async () => {
-    server = new WebServer(TEST_PORT + 1, false, true);
+    server = await createTestServer(TEST_PORT + 1);
     await server.start();
     baseUrl = `http://localhost:${TEST_PORT + 1}`;
   });
@@ -206,7 +223,7 @@ describe('Case Management', () => {
   const createdCases: string[] = [];
 
   beforeAll(async () => {
-    server = new WebServer(TEST_PORT + 2, false, true);
+    server = await createTestServer(TEST_PORT + 2);
     await server.start();
     baseUrl = `http://localhost:${TEST_PORT + 2}`;
   });

test/setup.ts

@@ -1,16 +1,36 @@
 /**
  * @fileoverview Global test setup for Codeman tests
  *
- * SAFETY: TmuxManager has built-in test mode detection
- * (via process.env.VITEST) that makes ALL shell commands no-ops.
- * This means tests CANNOT kill, create, or interact with real tmux
- * sessions regardless of what the test code does.
+ * SAFETY: The suite gets a temporary HOME and explicitly enables runtime test
+ * mode before application modules load. Tests therefore cannot touch the real
+ * Codeman state/cases tree or launch external tmux-backed agent sessions.
  *
  * This setup file strips shell-level auth configuration that can leak from a
  * running Codeman instance, then handles mock/timer cleanup between tests.
  */
 
-import { afterEach, vi } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, afterEach, vi } from 'vitest';
+
+const originalHome = process.env.HOME;
+const originalUserProfile = process.env.USERPROFILE;
+const originalVitest = process.env.VITEST;
+const originalPlaywrightBrowsersPath = process.env.PLAYWRIGHT_BROWSERS_PATH;
+const testHome = mkdtempSync(join(tmpdir(), 'codeman-vitest-'));
+
+if (originalPlaywrightBrowsersPath === undefined && originalHome) {
+  process.env.PLAYWRIGHT_BROWSERS_PATH =
+    process.platform === 'darwin'
+      ? join(originalHome, 'Library', 'Caches', 'ms-playwright')
+      : process.platform === 'win32'
+        ? join(process.env.LOCALAPPDATA || join(originalHome, 'AppData', 'Local'), 'ms-playwright')
+        : join(originalHome, '.cache', 'ms-playwright');
+}
+process.env.HOME = testHome;
+process.env.USERPROFILE = testHome;
+process.env.VITEST = 'true';
 
 delete process.env.CODEMAN_PASSWORD;
 delete process.env.CODEMAN_USERNAME;
@@ -23,3 +43,33 @@ afterEach(() => {
   vi.clearAllMocks();
   vi.useRealTimers();
 });
+
+afterAll(async () => {
+  // Let in-flight console-log rpc forwards drain before the worker environment
+  // tears down. On loaded CI runners the channel otherwise closes while the last
+  // "onUserConsoleLog" call is still pending, and that single unhandled
+  // EnvironmentTeardownError fails the run after every test has passed
+  // (observed twice on the PR #175/#176 merge commit; never locally).
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+
+  if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = originalUserProfile;
+
+  if (originalVitest === undefined) delete process.env.VITEST;
+  else process.env.VITEST = originalVitest;
+
+  if (originalPlaywrightBrowsersPath === undefined) delete process.env.PLAYWRIGHT_BROWSERS_PATH;
+  else process.env.PLAYWRIGHT_BROWSERS_PATH = originalPlaywrightBrowsersPath;
+
+  rmSync(testHome, { recursive: true, force: true });
+});
+
+// afterAll never fires for a fully-skipped test file (no tests execute), which
+// would leak the temp home created above. The exit hook is the backstop; rmSync
+// with force is a no-op when afterAll already removed it.
+process.on('exit', () => {
+  rmSync(testHome, { recursive: true, force: true });
+});

test/transcript-watcher.test.ts

@@ -88,14 +88,16 @@ describe('TranscriptWatcher', () => {
       watcher.start(testFile);
 
       // Add user entry
-      const userEntry = { type: 'user', timestamp: new Date().toISOString(), message: { role: 'user', content: 'test' } };
+      const userEntry = {
+        type: 'user',
+        timestamp: new Date().toISOString(),
+        message: { role: 'user', content: 'test' },
+      };
       appendFileSync(testFile, JSON.stringify(userEntry) + '\n');
 
-      // Wait for processing
-      await new Promise(resolve => setTimeout(resolve, 100));
-
-      const state = watcher.getState();
-      expect(state.entryCount).toBeGreaterThanOrEqual(1);
+      await vi.waitFor(() => {
+        expect(watcher.getState().entryCount).toBeGreaterThanOrEqual(1);
+      });
     });
 
     it('should emit transcript:complete on result entry', async () => {
@@ -109,10 +111,9 @@ describe('TranscriptWatcher', () => {
       const resultEntry = { type: 'result', timestamp: new Date().toISOString() };
       appendFileSync(testFile, JSON.stringify(resultEntry) + '\n');
 
-      // Wait for processing
-      await new Promise(resolve => setTimeout(resolve, 200));
-
-      expect(completeHandler).toHaveBeenCalled();
+      await vi.waitFor(() => {
+        expect(completeHandler).toHaveBeenCalled();
+      });
       const state = watcher.getState();
       expect(state.isComplete).toBe(true);
     });
@@ -130,22 +131,62 @@ describe('TranscriptWatcher', () => {
         timestamp: new Date().toISOString(),
         message: {
           role: 'assistant',
-          content: [
-            { type: 'tool_use', name: 'Read', input: { file_path: '/test.txt' } }
-          ]
-        }
+          content: [{ type: 'tool_use', name: 'Read', input: { file_path: '/test.txt' } }],
+        },
       };
       appendFileSync(testFile, JSON.stringify(assistantEntry) + '\n');
 
-      // Wait for processing
-      await new Promise(resolve => setTimeout(resolve, 200));
-
-      expect(toolStartHandler).toHaveBeenCalledWith('Read');
+      await vi.waitFor(() => {
+        expect(toolStartHandler).toHaveBeenCalledWith('Read');
+      });
       const state = watcher.getState();
       expect(state.toolExecuting).toBe(true);
       expect(state.currentTool).toBe('Read');
     });
 
+    it('should complete a tool when Claude writes tool_result in a user entry', async () => {
+      writeFileSync(testFile, '');
+      watcher.start(testFile);
+
+      const toolEndHandler = vi.fn();
+      watcher.on('transcript:tool_end', toolEndHandler);
+
+      appendFileSync(
+        testFile,
+        JSON.stringify({
+          type: 'assistant',
+          timestamp: new Date().toISOString(),
+          message: {
+            role: 'assistant',
+            content: [{ type: 'tool_use', name: 'Bash', input: { command: 'printf done' } }],
+          },
+        }) + '\n'
+      );
+      await vi.waitFor(() => {
+        expect(watcher.getState().toolExecuting).toBe(true);
+      });
+
+      appendFileSync(
+        testFile,
+        JSON.stringify({
+          type: 'user',
+          timestamp: new Date().toISOString(),
+          message: {
+            role: 'user',
+            content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: 'done', is_error: false }],
+          },
+        }) + '\n'
+      );
+
+      await vi.waitFor(() => {
+        expect(toolEndHandler).toHaveBeenCalledWith('Bash', false);
+      });
+      expect(watcher.getState()).toMatchObject({
+        toolExecuting: false,
+        currentTool: null,
+      });
+    });
+
     it('should detect plan mode from AskUserQuestion tool', async () => {
       writeFileSync(testFile, '');
       watcher.start(testFile);
@@ -159,17 +200,14 @@ describe('TranscriptWatcher', () => {
         timestamp: new Date().toISOString(),
         message: {
           role: 'assistant',
-          content: [
-            { type: 'tool_use', name: 'AskUserQuestion', input: { question: 'test?' } }
-          ]
-        }
+          content: [{ type: 'tool_use', name: 'AskUserQuestion', input: { question: 'test?' } }],
+        },
       };
       appendFileSync(testFile, JSON.stringify(assistantEntry) + '\n');
 
-      // Wait for processing
-      await new Promise(resolve => setTimeout(resolve, 200));
-
-      expect(planModeHandler).toHaveBeenCalled();
+      await vi.waitFor(() => {
+        expect(planModeHandler).toHaveBeenCalled();
+      });
       const state = watcher.getState();
       expect(state.planModeDetected).toBe(true);
     });
@@ -182,15 +220,14 @@ describe('TranscriptWatcher', () => {
       const resultEntry = {
         type: 'result',
         timestamp: new Date().toISOString(),
-        error: { type: 'api_error', message: 'Rate limited' }
+        error: { type: 'api_error', message: 'Rate limited' },
       };
       appendFileSync(testFile, JSON.stringify(resultEntry) + '\n');
 
-      // Wait for processing
-      await new Promise(resolve => setTimeout(resolve, 200));
-
+      await vi.waitFor(() => {
+        expect(watcher.getState().hasError).toBe(true);
+      });
       const state = watcher.getState();
-      expect(state.hasError).toBe(true);
       expect(state.errorMessage).toContain('Rate limited');
     });
   });

test/webview-proxy.test.ts

@@ -487,7 +487,10 @@ describe('runtimeUrlShim', () => {
  * 404s on Codeman's own root while the dashboard's fetch-driven data loads fine.
  *
  * Node environment on purpose, like test/markdown-sanitizer.test.ts: a per-file
- * `@vitest-environment jsdom` externalizes node builtins under vite.
+ * jsdom environment directive would externalize node builtins under vite. The
+ * directive is deliberately not written out here, even in prose: vitest scans
+ * comments for it, and naming it flipped this whole file to the jsdom
+ * environment while this comment claimed the opposite.
  */
 describe('runtimeUrlShim DOM sinks', () => {
   const body = runtimeUrlShim(PREFIX)