Merge pull request #305 from Ark0N/docs/skill-hooks-rule

docs(skill): hooks are a setting now, not who created the directory
review fixes: 1.19.0 is the real version boundary, and the preamble stamp matches its bytes again
2026-09-30 20:49:41 +02:00 · 2026-08-16 19:23:17 +02:00 · 2026-08-16 19:16:10 +02:00 · 2026-08-16 19:15:08 +02:00 · 2026-08-16 07:30:10 +02:00 · 2026-08-16 07:05:10 +02:00
31 changed files with 996 additions and 193 deletions
@@ -0,0 +1,80 @@
+# Contributing to Codeman
+
+Thanks for wanting to help! Codeman is a small project with a fast loop: issues usually get a response within a day, good PRs get reviewed quickly, and every release credits its contributors and bug reporters by name in the release notes. This guide gets you from clone to merged PR without stepping on the traps.
+
+## The short version
+
+1. **Bugs**: open an issue with your OS, install method (installer / npm / git clone), browser, and which CLI + version the session was running.
+2. **Questions and ideas**: use [Discussions](https://github.com/Ark0N/Codeman/discussions), not issues.
+3. **Small fixes** (docs, typos, a new skin, a translation): just send the PR.
+4. **Anything bigger**: open an issue or Discussion first and get a nod before building. Codeman has strong architectural invariants, and a design chat up front is what turns a big idea into a merged PR instead of a stalled one. This flow works: features like Clone Repo (#236) went idea, then design discussion, then review, then shipped.
+5. **Security issues**: never a public issue. See [SECURITY.md](SECURITY.md).
+
+## Dev setup
+
+Requirements: Node.js 22+ (see `.nvmrc`), tmux, and at least one supported agent CLI on your PATH (Claude Code is the primary one).
+
+```bash
+git clone https://github.com/Ark0N/Codeman.git
+cd Codeman
+npm install        # postinstall builds the vendored xterm addon bundles
+npm run dev        # dev server on http://localhost:3000
+```
+
+The frontend is plain JS served from `src/web/public/` with no bundler in dev: edit a `.js`/`.css` file and reload the page. The one exception is `index.html`, which is read once at server start, so markup changes need a server restart.
+
+## Before you push
+
+CI runs all of these, so save yourself a round trip:
+
+```bash
+npm run typecheck              # tsc --noEmit, strict mode
+npm run lint
+npm run format:check
+npm run check:frontend-syntax  # syntax-checks the plain-JS frontend modules
+```
+
+### Tests
+
+```bash
+npm test -- test/<file>.test.ts   # one file (the normal way)
+npm run test:ci                    # the full CI sweep
+```
+
+**Never run bare `npm test`.** The default config includes browser-driven Playwright suites that need a live server, Chromium, and environment-specific baselines; they will hang or fail on a normal machine. `test:ci` is the honest "run everything" command, it is exactly what CI runs.
+
+If you add a test that binds a port, pick a unique one at 3150 or above (search the repo for `const PORT =` first). Never 3000.
+
+Tests are tmux-safe by design: under vitest, the tmux layer becomes an in-memory mock, so tests cannot touch real sessions.
+
+## Finding your way around
+
+- Every source file starts with a `@fileoverview` JSDoc block. Read it before diving into the file, it is the map.
+- [`CLAUDE.md`](../CLAUDE.md) at the repo root is the densest architecture primer in the repo. It is written for AI coding agents, but the invariants and gotchas in it apply to humans exactly the same, and most review feedback on PRs traces back to something already written there.
+- Deep mechanisms and the history behind each rule live in [`docs/architecture-invariants.md`](../docs/architecture-invariants.md).
+- Third-party extension surfaces are documented in [`docs/extending-codeman.md`](../docs/extending-codeman.md).
+
+## Great first contributions
+
+These are well-fenced areas where a first PR is genuinely easy to get right:
+
+- **A new theme skin.** A skin is four things kept in sync: the `html[data-skin="…"]` token block in `styles.css`, the xterm ANSI palette in `terminal-ui.js`, the pre-paint allowlist and the settings picker (both in `index.html`). `test/skin-themes.test.ts` statically checks the sync, so if the test passes, your skin works.
+- **A new language.** `src/web/public/i18n.js` is dependency-free, English is the canonical source, and `zh-CN` is a complete example to copy. Add your language's entries and register it in `SUPPORTED_LANGUAGES`.
+- **Docs.** If you got stuck on something and then figured it out, the sentence that would have unstuck you is a PR.
+- Anything labeled [`good first issue`](https://github.com/Ark0N/Codeman/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+
+Bigger extension points worth discussing first: new CLI backends (the pluggable resolver pattern has absorbed six CLIs so far; `docs/extending-codeman.md` and `docs/opencode-integration.md` show the shape), and real-device testing reports, especially mobile, which always find things emulation cannot.
+
+## PR expectations
+
+- **One change per PR.** Small and focused reviews fast; a grab-bag stalls.
+- Target the `master` branch.
+- **Keep your branch mergeable.** A PR with conflicts silently gets no CI runs at all (GitHub quirk), so rebase or merge master when conflicts appear.
+- Include or update tests when you change behavior. Route handlers have a lightweight pattern in `test/routes/` using `app.inject()` (no live server needed).
+- Formatting is Prettier with a deliberately narrow scope (`npm run format`), several frontend files are hand-formatted on purpose and excluded via `.prettierignore`. Don't "fix" a file by adding it back into Prettier's scope.
+- Don't bump versions or touch `CHANGELOG.md`; releases are handled by the maintainer via changesets after merge.
+- AI-assisted contributions are welcome (much of Codeman is built that way), with one condition: you must understand what you're submitting and have actually run it. "The model said it works" is not a test.
+
+## Conduct
+
+Be kind, be direct, assume good faith. Report unacceptable behavior privately via the contact in [SECURITY.md](SECURITY.md).
@@ -1,5 +1,17 @@
 # aicodeman

+## 1.18.4
+
+### Patch Changes
+
+- Faster agent-skill workers, retuned multi-color lineage arcs, a per-tab pop-out option, reliable tab alerts, and the community launch.
+  - Agent skill: SKILL.md now forbids the standalone preamble check and the pre-spawn reconnaissance turns that were costing whole model turns; the same two-worker spawn measured at 28.6s end to end now runs 20.2s cold and 12.8s warm, with the spawn machinery itself unchanged.
+  - Session lineage lines: arcs now hang from the tab strip's bottom edge (dip cap 104px to 64px, no stacked row offsets), fixing the deep bow on wrapped tab strips and keeping same-row arcs off the second row's tab labels; each spawned worker's arc gets its own color (skin blue first, then matrix green, pink, violet, red, turquoise, orange), assigned per child and stable across re-renders.
+  - Session Options > Session: new "Pop-out button on this tab" per-tab override on top of the general App Settings toggle (per-device).
+  - Tab alerts: pending permission/question alerts now survive page reloads regardless of the Approvals Inbox setting (the alert state machine seeds from the server-side approval store on every load), stay visible on the selected tab until the prompt is actually resolved (the alert paints on a ::before overlay the active tab's styling cannot bury), and render as a steady red/yellow ring with glow and a colored status dot instead of a blink that spent half of every cycle looking like a normal tab. The README carries a live capture of the new alerts.
+  - Community launch: README Community section, .github/CONTRIBUTING.md (dev setup, test safety, great first contributions, PR expectations), and GitHub Discussions.
+  - docs: worker warm-pool design sketch with the measured baselines.
+
 ## 1.18.3

 ### Patch Changes
@@ -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.18.3 (must match `package.json`)
+**Version**: 1.18.4 (must match `package.json`)

 ## Project Overview

@@ -204,13 +204,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 **Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)

-**Session lineage lines** (tab → tab it spawned, `sessionLineageLines`, per-device, desktop default ON): a create request may name the session that spawned it, as a `parentSessionId` body field on `POST /api/sessions` / `POST /api/quick-start` or the `X-Codeman-Parent-Session` header (the agent skill sets that once on its shared curl invocation, so every spawn recipe carries it). `resolveParentSessionId()` (route-helpers.ts) **resolves rather than trusts** it: exact id, else a UNIQUE ≥8-char prefix (ids reach agents truncated), it must be a live session the caller can see AND carry the same owner, and **anything unresolvable is DROPPED, never a 400** — a cosmetic field must not be able to fail a worker spawn. It rides `toState()` into `session_created`, so there is no new SSE event. ⚠️ Rendering is an ADDITIONAL LAYER on the existing SVG pass (`_appendLineageConnectionLines` called at the tail of `_updateConnectionLinesImmediate()`, exactly like ultracode), sharing one batched read→write reflow and the `tab:<id>` rect cache; geometry is pure in `computeLineagePath()` (constants.js). ⚠️ **ONE shape, and the second one was the bug**: every pair (flat strip or wrapped) gets a U-bridge hanging below the strip, anchored on both tabs' BOTTOM edges. A wrapped strip used to get a parent-bottom → child-TOP bezier with a ~14px row gap to bend in, which drew a flat line hidden in the gap with siblings overprinting; the dip is also clamped at 104px rather than 44, since a skill worker lands at the END of the strip where the old cap flattened the arc into a straight thread. ⚠️ **Desktop only**: the overlay is `z-index: 999` and the desktop header is 100 (arcs paint over it, which is what lets them touch tab bottoms), but under 1024px mobile.css makes the header `fixed; z-index: 1200` and would bury them. ⚠️ Paths carry `data-agent-id="lineage:<childId>"` because that is what `_applyLineEntrances()` queries — that one attribute is what gives them the entrance animation and its negative-`animation-delay` resume across `svg.innerHTML=''`. ⚠️ `.session-tabs` is `overflow-x: auto`, so a scrolled-out tab still HAS a rect (over the logo); edges with an endpoint outside the strip are skipped, and a passive `scroll` listener re-anchors the rest.
+**Session lineage lines** (tab → tab it spawned, `sessionLineageLines`, per-device, desktop default ON): a create request may name the session that spawned it, as a `parentSessionId` body field on `POST /api/sessions` / `POST /api/quick-start` or the `X-Codeman-Parent-Session` header (the agent skill sets that once on its shared curl invocation, so every spawn recipe carries it). `resolveParentSessionId()` (route-helpers.ts) **resolves rather than trusts** it: exact id, else a UNIQUE ≥8-char prefix (ids reach agents truncated), it must be a live session the caller can see AND carry the same owner, and **anything unresolvable is DROPPED, never a 400** — a cosmetic field must not be able to fail a worker spawn. It rides `toState()` into `session_created`, so there is no new SSE event. ⚠️ Rendering is an ADDITIONAL LAYER on the existing SVG pass (`_appendLineageConnectionLines` called at the tail of `_updateConnectionLinesImmediate()`, exactly like ultracode), sharing one batched read→write reflow and the `tab:<id>` rect cache; geometry is pure in `computeLineagePath()` (constants.js). ⚠️ **ONE shape, and the second one was the bug**: every pair (flat strip or wrapped) gets a U-bridge hanging below the strip, anchored on both tabs' BOTTOM edges. A wrapped strip used to get a parent-bottom → child-TOP bezier with a ~14px row gap to bend in, which drew a flat line hidden in the gap with siblings overprinting. ⚠️ The dip is a **mis-tuned-in-both-directions corridor** (44px cap = straight thread at strip-wide spans, #285; 104px cap + full row offset = ~106px over-bow into the terminal, 2026-08-15): it now hangs from the **STRIP's bottom edge** (fallback: lower tab bottom), capped at 64px, with NO per-row offsets stacked on top — the strip-bottom baseline is also what keeps a row-1 pair's arc from drawing through row 2's tab labels. Colors cycle per CHILD in first-seen order from `CodemanLineage.COLORS` (first entry empty = the skin-tuned `--session-blue`; the rest vivid fixed hexes), set inline as `--lineage-color` so styles.css keeps owning opacity/glow/dash. ⚠️ **Desktop only**: the overlay is `z-index: 999` and the desktop header is 100 (arcs paint over it, which is what lets them touch tab bottoms), but under 1024px mobile.css makes the header `fixed; z-index: 1200` and would bury them. ⚠️ Paths carry `data-agent-id="lineage:<childId>"` because that is what `_applyLineEntrances()` queries — that one attribute is what gives them the entrance animation and its negative-`animation-delay` resume across `svg.innerHTML=''`. ⚠️ `.session-tabs` is `overflow-x: auto`, so a scrolled-out tab still HAS a rect (over the logo); edges with an endpoint outside the strip are skipped, and a passive `scroll` listener re-anchors the rest.

 **Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows fold into their owning session via a `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)

-**Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`.
+**Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`. ⚠️ **Every claude session INSTALLS the hooks block into its workspace** (`applyWorkspaceHooks` in session-routes.ts → `ensureCodemanHooks`, an add-only merge that keeps a user's own handlers), from both create paths and from `restoreMuxSessions()` for sessions recovered on server start. Before 2026-08-15 hooks were written ONLY when Codeman created the case DIRECTORY, so a linked case / cloned repo — where most sessions actually run — had no hooks at all and every hook-driven surface was silently dead there: an AskUserQuestion dialog blocked the pane while the tab and the phone overview both read a calm `idle`, with no Approvals Inbox item, no push, no definitive `stop`/`idle_prompt` for respawn and no `stop`/`blocked` for the wait endpoints. The escape hatch is the synced `workspaceHooksEnabled` setting (App Settings → Agents & CLIs → Claude, **default ON**); OFF restores the old behavior, where a Codeman block that is already there is still refreshed when stale (COD-91) but one is never added. ⚠️ Route the decision through `applyWorkspaceHooks` rather than calling `ensureCodemanHooks` at a new site, or the setting silently stops applying to that path. ⚠️ Claude Code RE-READS `settings.local.json`, so an already-running session starts firing hooks without a restart (measured 2026-08-15) — and the notification for a blocking dialog is delayed by Claude Code (~30s), so the alert trails the dialog. ⚠️ An AskUserQuestion / plan-selection dialog arrives as **`permission_prompt`**, not `elicitation_dialog` (that one is MCP elicitation), so it renders as the RED "needs you" alert, not the yellow idle one.

-**Approvals Inbox** (cross-session queue of prompts waiting on a human; `approvalsInboxEnabled`, SYNCED, default OFF: every surface is opt-in; only the store and answer endpoints run regardless, so flipping it ON shows anything already pending): `web/approval-inbox.ts` is a `sessionWaits`-style singleton fed by `/api/hook-event`, holding at most ONE item per session (a new prompt supersedes), claude-mode only, in-memory. Cards are answered via `POST /api/approvals/:id/answer`, which sends a digit / Esc / idle-prompt text through `writeViaMux` (menu answers never carry `\r`). ⚠️ `option` digits are accepted ONLY when they match options parsed from the captured pane frame, and the answer path RE-CAPTURES the pane first (a dialog that no longer parses on screen means the keystroke would land in the composer, so refuse with 409). ⚠️ Resolution on the heuristic `working` signal is restricted to `idle` items; permission/question items clear only on definitive signals (`stop`, `elicitation_complete`/`elicitation_response`, exit/delete, answer, supersede, 12h TTL). The frontend seeds from `GET /api/approvals` in `handleInit` (which is what makes tab alerts survive reloads), but only with the setting ON; push Approve/Deny buttons are also gated on it (`sendPushNotifications` strips `actions`/`approvalId` when OFF) and are answered from `sw.js` directly so they work with no tab open. Surfaces (all gated on the setting): header bell (marker-hidden until count > 0, phones never show it) + drawer (`approvals-ui.js`), phone overview NEEDS YOU answer strips (`mobile-overview.js`). Design: `docs/approvals-inbox-plan.md`.
+**Approvals Inbox** (cross-session queue of prompts waiting on a human; `approvalsInboxEnabled`, SYNCED, default OFF: every surface is opt-in; only the store and answer endpoints run regardless, so flipping it ON shows anything already pending): `web/approval-inbox.ts` is a `sessionWaits`-style singleton fed by `/api/hook-event`, holding at most ONE item per session (a new prompt supersedes), claude-mode only, in-memory. Cards are answered via `POST /api/approvals/:id/answer`, which sends a digit / Esc / idle-prompt text through `writeViaMux` (menu answers never carry `\r`). ⚠️ `option` digits are accepted ONLY when they match options parsed from the captured pane frame, and the answer path RE-CAPTURES the pane first (a dialog that no longer parses on screen means the keystroke would land in the composer, so refuse with 409). ⚠️ Resolution on the heuristic `working` signal is restricted to `idle` items; permission/question items clear only on definitive signals (`stop`, `elicitation_complete`/`elicitation_response`, exit/delete, answer, supersede, 12h TTL). The frontend seeds from `GET /api/approvals` in `handleInit` **regardless of the setting**: the seed re-arms the tab-alert state machine (`setPendingHook`) unconditionally, and only populating `this.approvals` (the inbox surfaces) is gated — seeding used to be gated wholesale, which left a reloaded page with NO red tab while a permission dialog sat blocking a session (2026-08-15); `_onApprovalResolved` clears the pending-hook alert unconditionally for the same reason. ⚠️ The red/yellow tab alert itself is a STEADY border/background/dot with a pulse on top: the original keyframes swung to transparent at 0%/100%, so half of every cycle looked like a normal tab. Push Approve/Deny buttons stay gated on the setting (`sendPushNotifications` strips `actions`/`approvalId` when OFF) and are answered from `sw.js` directly so they work with no tab open. Surfaces (all gated on the setting): header bell (marker-hidden until count > 0, phones never show it) + drawer (`approvals-ui.js`), phone overview NEEDS YOU answer strips (`mobile-overview.js`). Design: `docs/approvals-inbox-plan.md`.

 **Read My Mind intent profiles** (phase 1 of `docs/readmymind-plan.md`; `readMyMindEnabled`, SYNCED, default OFF): per-CASE profiles (user-stated `goals` + the user's recent real prompts), keyed by owner + realpath(workingDir) so they survive `/clear`/respawns and multi-user scoping is structural. Capture rides the transcript (`transcript:user_prompt` from `transcript-watcher.ts`), NOT the input paths: `POST /input` sees only programmatic prompts and the WS channel is raw keystrokes. The listener lives inside `startTranscriptWatcher()`'s `if (!watcher)` block (outside it would duplicate per hook event) and is claude-only + gated on the setting per event. Store: `src/intent-store.ts` singleton, `intents.json` written 0600 tmp+rename (prompts can contain secrets; never fed to `/api/search`). Endpoints: GET/PUT/DELETE `/api/sessions/:id/intent` + POST `/api/sessions/:id/readmymind` (`readmymind-routes.ts`, ownership via `findSessionOrFail` WITH `req`; registrations stay the bare `app.<method>('path')` shape, the endpoints.md drift scanner cannot see generics). **Phase 2 (predictor + 🧠 button)**: `readmymind-context.ts` is the PURE budgeted assembler (9 ranked sources, drop order siblings→away→workspace→tools, sections 1-4 truncate only); IO lives in `readmymind-collectors.ts` (transcript TAIL read — the live watcher keeps only a 500-char snippet — + git signals, skipped for remote-SSH cases) and the route; `readmymind-predictor.ts` reuses the AiCheckerBase spawn mechanics standalone (verdict-shaped base vs freeform JSON) as a mutable singleton routes call and tests stub. Claude-mode only (400), one in flight per session (409 CONFLICT), model = `readMyMindModel` setting defaulting to `AI_CHECK_MODEL` (opus, decided). Frontend `readmymind-ui.js`: header 🧠 marker-hidden (`btn-readmymind--hidden`) until the setting is ON; phones hide it in mobile.css and get a keyboard-accessory 🧠 key instead (ships in BOTH bar templates, revealed by the `rmm-enabled` class on the BAR element — setMode() rebuilds button innerHTML, so per-key state would be wiped; synced at init + every `applyHeaderVisibilitySettings()`). Alternate suggestions render as tappable rows that swap into the editable field without losing edits; Rethink rejects the whole shown set and carries the optional steer note (`#readMyMindSteer`, sent as `steer`, shown in ready + empty-result phases, cleared on each open). Suggestions render via value/`textContent` ONLY and Send/Insert go through `POST /input` (server-side, so the sendEnterKey/local-echo trap does not apply) — nothing auto-sends, ever. User guide: `docs/readmymind.md`.

@@ -406,6 +406,14 @@ The title is templated into the served HTML on first byte, so it's correct from
 | **110k tokens** | Auto `/compact` | Context summarized, work continues |
 | **140k tokens** | Auto `/clear`   | Fresh start with `/init`           |

+### Tab Alerts
+
+<p align="center">
+  <img src="docs/images/tab-alerts-glow-20260815.gif" alt="Session tabs: a regular active tab beside a yellow waiting-for-input tab and a red needs-decision tab, both with a breathing glow" width="900">
+</p>
+
+Every tab tells you its state at a glance. A running session keeps its green status dot. When a session stops and waits for input, its tab turns **yellow**: steady ring, tinted background, yellow dot, with a slow breathing glow on top. When a permission prompt or question is **blocking** the agent, the tab turns **red** with a faster pulse. The base tint never blinks off, so even a split-second glance (or a screenshot) reads the true state; the ring stays visible while the tab is selected, and a page reload re-arms pending alerts from the server, so a blocked session can never hide behind a fresh-looking tab.
+
 ### Notifications

 Real-time desktop alerts when sessions need attention — `permission_prompt` and `elicitation_dialog` trigger critical red tab blinks, `idle_prompt` triggers yellow blinks. Click any notification to jump directly to the affected session. Hooks auto-configured per case directory.
@@ -1035,6 +1043,12 @@ See [CLAUDE.md](./CLAUDE.md) for full documentation.

 ---

+## Community
+
+Questions, setup help, and ideas live in [GitHub Discussions](https://github.com/Ark0N/Codeman/discussions): the [Q&A section](https://github.com/Ark0N/Codeman/discussions/categories/q-a) answers the most common ones (phone access, overnight runs, updating), and the roadmap gets decided in [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas). Bugs go to [issues](https://github.com/Ark0N/Codeman/issues); reports usually get a response within a day, and every release credits its reporters and contributors by name. Want to contribute? [CONTRIBUTING.md](.github/CONTRIBUTING.md) has the map: skins, translations, and docs make great first PRs, and bigger features start life as a Discussion. And if you're proud of your rig, post it in [Show and tell](https://github.com/Ark0N/Codeman/discussions/300).
+
+---
+
 ## Codebase Quality

 The codebase went through a comprehensive 7-phase refactoring that eliminated god objects, centralized configuration, and established modular architecture:
@@ -0,0 +1,121 @@
+# Warm worker pool: sub-second claude worker spawns
+
+Design sketch. Status: **proposed**, not started. Opt-in (`workerPoolSize`, default 0 = off); a user who touches nothing sees no change at all.
+
+---
+
+## 1. Problem and numbers
+
+Measured against prod 1.18.3 on 2026-08-15, AFTER the SKILL.md fast-path hardening
+(no recon turns), on the identical "spawn two codeman workers" prompt:
+
+- **Cold orchestrator** (fresh session, skill loaded from disk): **20.2 s** prompt to
+  final report. Breakdown: 3.9 s Skill-load turn, 6.4 s generating the one fused Bash
+  call, **4.4 s spawn call**, 5.5 s summary. Tabs appeared at 10.5 s.
+- **Warm orchestrator** (skill already in context, no Skill turn): **12.8 s**, spawn
+  call 6.0 s.
+- Inside the spawn call, session + tmux + case creation is cheap: the workers (and
+  their tabs) appeared 0.2-1.7 s in, both siblings within ~350 ms of each other. The
+  remaining **~4-5 s is claude CLI boot plus the composer-readiness wait**, paid again
+  on every cold spawn. That slice is the pool's entire target.
+
+The honest framing after the hardening: model turns dominate the skill flow (~16 of
+20 cold seconds) and no server feature can shrink those. The pool attacks the
+tool-side floor, and it has two distinct beneficiaries:
+
+- **Skill/API orchestration**: the spawn call drops from ~4.4-6 s to ~1 s. Cold runs
+  land ~16-17 s, warm ~8 s. Tab appearance barely moves for this consumer (it is
+  model-turn-bound at ~10 s cold / ~4 s warm).
+- **The UI Run button and direct quick-start callers**: a click today waits the full
+  boot + readiness before the worker can take a prompt; a pooled claim makes the tab
+  appear and the worker READY sub-second. This is the most visible win, and it
+  involves no skill at all.
+
+Target: hand out an already-ready worker in **under 1 s**.
+
+## 2. Shape
+
+A new `src/worker-pool.ts` singleton service, following the `CronService` pattern: it **reuses the existing session layer** (`SessionManager` create + the normal spawn path) and never rebuilds tmux logic.
+
+A pool member is a real claude `Session`, pre-spawned in a reserved scratch case (`~/codeman-cases/.pool-<n>`, created with the standard scaffold + hooks), already past readiness: composer drawn, hooks installed, preamble file seeded. It sits idle at the composer costing no tokens.
+
+The claim happens **transparently inside `POST /api/quick-start`**: when a request is pool-eligible (§3) and a healthy member is available, quick-start returns that member instead of cold-spawning. The agent skill, the UI Run button, and every existing caller change **nothing**. Ineligible or pool-empty requests cold-spawn exactly as today, so the pool is only ever a fast path, never a behavior change.
+
+## 3. Eligibility gate
+
+Claim only when ALL of these hold; otherwise fall through to a cold spawn:
+
+- `mode === 'claude'` (external CLIs have different readiness semantics and inject secrets via `tmux setenv` at spawn; out of scope).
+- No `envOverrides`, no `CLAUDE_CONFIG_DIR`, and `modelOverride`/`effort` unset or equal to what the pool member was spawned with. Env vars flow at spawn time and cannot be applied to a running CLI.
+- The requested case is **fresh** (does not exist yet). A linked case, an existing directory, a remote-SSH case, or a Docker case means the caller wants a specific workspace; pool members cannot provide one.
+- Single-user mode, or the requester owns the pool (v1 ships single-user only; §11).
+
+## 4. What a claim does (~300 ms)
+
+1. Pop a ready member (in-memory check-and-remove; Node's single thread makes this atomic, so two concurrent quick-starts cannot claim the same member).
+2. Health-probe it: `isPaneDead` (the existing ~750 ms-cached mux probe) plus one `capturePaneText` asserting a clean composer. A dead, limit-paused, or dirty member is recycled, and the claim tries the next member or falls through to cold spawn.
+3. Rename the session to the normal `w<n>-<case>` name, set `parentSessionId` via the existing `resolveParentSessionId()`, clear the pool flag, persist state.
+4. Emit `session_created` **now** (it was suppressed at warm-spawn time, §5). The tab appears here, sub-second after the request.
+5. Return the **pool case** as `casePath`/`workingDir` and do NOT create a directory under the requested name: an empty dir the worker's CLI does not run in is a trap (files written there are invisible to the worker at cwd), and the agent skill greps the RETURNED `casePath` for Codeman hooks before trusting the worker, so the response must point at the directory that really carries them.
+6. Kick a background refill (§6).
+
+**The identity wrinkle, stated honestly:** the session id, `CODEMAN_SESSION_ID` inside the pane, the seeded preamble file, and the CLI's cwd are all fixed at warm-spawn and survive the claim unchanged. So a claimed worker's `workingDir` is the pool dir, not `~/codeman-cases/<requested-name>`; the requested name is a **label**. The API must report the truthful `workingDir`. Transcript projHash, response viewer, subagent windows, and Read My Mind all key off the real path and keep working precisely because we do not lie about it. This is acceptable for the dominant use (ephemeral skill workers that are deleted after answering) and is documented in the skill; a caller that needs the real case as cwd is by definition not pool-eligible.
+
+**Verified skill compatibility (zero preamble changes).** Checked against the shipped 1.18.3 preamble: `spawn_worker`'s readiness probe (`_composer_up`) is a `wait-output` call with `from=buffer`, which scans output that already scrolled past before blocking, so a pooled member's long-since-drawn composer matches instantly instead of stranding a fresh-stream wait. The trust-dialog fallback never fires (members passed the dialog at warm time), and the hooks grep passes because the pool case carries the standard scaffold. Pooled and cold spawns are indistinguishable to the skill except in speed and the additive `pooled: true`.
+
+## 5. Hiding pre-claim members
+
+Pool members must be invisible until claimed or they read as ghost tabs. `Session.isPoolWorker` gates, at minimum:
+
+- `GET /api/sessions` and `GET /api/sessions/unified` (and therefore the Cmd+K palette and the session-history-index snapshot that feeds `/api/search`).
+- `session_created` SSE at warm-spawn (deferred to claim time). All other per-session SSE for a hidden member is suppressed at the broadcast call sites it would reach.
+- Push notifications and the Approvals Inbox (a warm member showing a trust dialog must recycle, not notify).
+- The phone overview / home rail (both render from the session list, so the list filter covers them).
+- The lifecycle log records `pool_warm` / `pool_claim` events rather than user-visible session history.
+
+`maxSessions` (50) **counts** pool members, and the pool refuses to warm within `poolSize + 2` of the cap so it can never starve real session creation.
+
+## 6. Refill, TTL, drain
+
+- **Refill** after each claim, debounced, at most one warm spawn in flight (a claim burst falls back to cold spawns rather than forking N CLIs at once; same reasoning as the document-conversion limiter).
+- **TTL ~30 min**: recycle members older than that so they cannot drift from settings, hooks config, or a self-updated CLI on disk.
+- **Drain and respawn** on: `claudeModel` change, hooks-config regeneration, self-update, and `workerPoolSize` changes. On server shutdown, kill pool sessions (they are stateless and ours). On boot, kill any leftover `.pool-*` tmux sessions found via `mux-sessions.json` rather than adopting them; adoption buys nothing for stateless members.
+
+## 7. Failure modes
+
+| Failure | Handling |
+| --- | --- |
+| Member died idle (PTY exit, crash) | Health probe at claim catches it; recycle + try next; PTY-exit breaker applies unchanged |
+| Member hit a usage limit while idle | `isLimitPaused` members are never handed out; recycle |
+| Composer dirty (stray keystrokes, dialog) | `capturePaneText` probe refuses it; recycle |
+| Claim race | Impossible by construction (synchronous in-memory pop) |
+| Warm spawn itself fails | Log, back off, retry on next refill tick; pool empty just means cold spawns |
+
+## 8. Cost
+
+Each warm member is one tmux session + one idle claude process (order 150-300 MB RSS; **measure before defaulting the size above 0**, including whether an idle CLI makes any background requests via its statusline refresh). Zero token cost while idle. Suggested starting size for users who opt in: 2.
+
+## 9. Settings and API surface
+
+- `workerPoolSize` (int, 0-4, default 0): **synced** setting in `SettingsUpdateSchema`. The watcher that resizes the pool on `PUT /api/settings` must resolve from `merged`, never the raw body (the partial-PUT gotcha in CLAUDE.md).
+- One internal status endpoint, `GET /api/worker-pool` (size, members' ages, claims served, fall-through count), for debugging. No new SSE events: the claim emits the existing `session_created`.
+- No new public API semantics: `/api/quick-start`'s contract is unchanged apart from a `pooled: true` field in the response data, which is additive.
+
+## 10. Considered and rejected
+
+- **Renaming the pool case dir to the requested name at claim.** Linux keeps the process cwd working across the rename (inode-based), but claude computed its transcript projHash from the old path string at boot, so transcripts, subagent windows, and the response viewer go blind, the exact failure mode the `CLAUDE_CONFIG_DIR` docs warn about. Truthful label semantics (§4) beat a clever rename.
+- **A new explicit claim endpoint.** Transparency inside quick-start means the skill, the UI, and every existing script get the speedup with zero changes; a new endpoint means new docs, new drift, and callers that must know the pool exists.
+- **Pooling external CLI modes.** Readiness there is output stabilization, secrets ride `tmux setenv` at spawn, and codex/pi composer semantics differ per CLI. Claude-only until someone measures a need.
+- **Returning quick-start at creation instead of readiness (no pool).** Would move tabs earlier on cold spawns too, but `sendwait` immediately after would then race the composer; readiness is what makes immediate tasking safe, and the pool makes the whole question moot for eligible spawns.
+
+## 11. Phasing
+
+1. **v1**: single-user, claude-only, fixed-size pool, transparent claim, status endpoint. Everything above.
+2. **v2**: per-owner pools for multi-user mode (pool members must carry an owner because ownership scoping is structural); possibly model-matched pools (one warm set per configured `claudeModel`).
+3. **Explicitly out**: warming linked/repo cases (spawning where the work is has no hooks and is the skill's documented costliest mistake; a warm pool must not make it faster to reach).
+
+## 12. Testing
+
+- Unit: pool manager logic pure and mock-driven (eligibility gate, TTL, refill debounce, drain triggers), `MockSession` from `test/mocks/`.
+- Route: `app.inject` on quick-start asserting claim vs cold-spawn per eligibility row in §3, plus the double-claim race (two concurrent injects, one pool member: exactly one `pooled: true`).
+- Live: re-run the pinned baselines against a warmed beta instance. Before (2026-08-15, prod 1.18.3, post-hardening): cold orchestrator **20.2 s** / warm **12.8 s** end to end, spawn call 4.4-6.0 s. Acceptance: spawn call under 1 s, cold ~16-17 s, warm ~8-9 s, and a UI Run click to a READY worker in under 1 s.
@@ -1,12 +1,12 @@
 {
  "name": "aicodeman",
-  "version": "1.18.3",
+  "version": "1.18.4",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "aicodeman",
-      "version": "1.18.3",
+      "version": "1.18.4",
      "hasInstallScript": true,
      "license": "MIT",
      "workspaces": [
@@ -1,6 +1,6 @@
 {
  "name": "aicodeman",
-  "version": "1.18.3",
+  "version": "1.18.4",
  "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
  "type": "module",
  "main": "dist/index.js",
@@ -42,18 +42,22 @@ hundred-odd lines at the top of every call (a half-re-pasted preamble used to be
 single most likely way to break a run).

 **Codeman seeds the preamble file for you** when it spawns a claude session (server
-1.18.3+), so the bootstrap is usually just loading it — the same two lines every later
-call starts with:
+1.18.3+), so the bootstrap is usually nothing at all: these are the two lines every
+later call opens with, and your first REAL call performs them anyway:

 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null
-[ "${CODEMAN_PREAMBLE:-}" = 1.18.3 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.19.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 ```

-If that passed, §0 is done: go straight to your job (§1's block opens with this same
-loader, so when §1 is the job you can simply start there). Only when it reports
-missing or stale, run the full block below once — and run it **verbatim**: paste it
-as-is, never re-type it, trim it, or "extract the parts you need". A hand-assembled
+⚠️ **Never spend a Bash call on this check alone.** §1's block opens with this same
+loader, so when §1 is the job, start there: the check rides the spawn call for free,
+and a standalone "preamble OK" call buys nothing while costing a full model turn
+(measured live: a lone check plus the deliberation around it added ~6 s to a 28 s
+two-worker run). §0 is done the moment any job call passes its opening check. Only
+when a call reports missing or stale, run the full block below once — and run it
+**verbatim**: paste it as-is, never re-type it, trim it, or "extract the parts you
+need". A hand-assembled
 preamble is the documented failure mode of this skill: one live run rebuilt it
 "minimally" and lost the `X-Codeman-Parent-Session` header (every worker spawned with
 no lineage arc in the web UI) and the fast-path functions (the spawn fell back to a
@@ -71,8 +75,8 @@ PRE="${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh"
 mkdir -p "$(dirname "$PRE")"
 # Rewrite unless the file already ends with THIS version's stamp, so a stale or a
 # half-written file self-heals here instead of costing you a round trip to rm it.
-grep -qs '^CODEMAN_PREAMBLE=1.18.3$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
-# ---- Codeman agent preamble 1.18.3 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+grep -qs '^CODEMAN_PREAMBLE=1.19.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.19.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -134,14 +138,14 @@ spawn_worker() {
  # NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
  [ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
  [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; }   # only claude draws a composer
-  # quick-start RESOLVES the name before creating: a linked case or an existing dir
-  # wins over a fresh scratch case, so "created => hooks" is only true after this one
-  # local grep (the same marker the server itself checks for). No marker means sendwait
-  # would false-resolve on flapping idle, possibly inside the user's REAL repo: refuse
-  # rather than run the job there.
+  # The server installs hooks into every claude workspace now, so this grep normally
+  # passes; it stays because the install is gated on a setting the operator can turn
+  # off, remote sessions never get hooks, and a session created by an older server
+  # still has none. No marker means sendwait would false-resolve on flapping idle,
+  # possibly inside the user's REAL repo: refuse rather than run the job there.
  cp=$(jq -r '.data.casePath // empty' <<<"$q")
  grep -qs '/api/hook-event' "$cp/.claude/settings.local.json" || {
-    echo "case '$name' resolved to '$cp', which has no Codeman hooks (linked or pre-existing?): pick an unused name, or work §5.1+§5.5 by hand" >&2
+    echo "case '$name' resolved to '$cp', which has no Codeman hooks (workspaceHooksEnabled off, remote, or an older server?): turn the setting on, or work §5.1+§5.5 by hand with markers" >&2
    delete_session "$sid" >/dev/null; return 1; }
  # Short composer wait FIRST, then the trust-dialog probe: a case still showing the
  # dialog can never pass the composer wait, so probing early keeps a cold case from
@@ -229,10 +233,10 @@ last_text() {
 # The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
 # bare on purpose: the write condition above anchors on it with $, so an inline comment
 # here would fail that match and rewrite this file on every single bootstrap.
-CODEMAN_PREAMBLE=1.18.3
+CODEMAN_PREAMBLE=1.19.0
 PREAMBLE
 )
-. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.18.3 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
+. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.19.0 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
 ```

 Every later Bash call that touches the API starts with the same two loader lines from
@@ -273,14 +277,18 @@ plain-text 401: see §6 and [the symptom gallery](reference/endpoints.md#symptom
 block is the whole thing. Run it, report, and stop reading. §2 onward is for jobs this
 does not cover; you are not being careless by not reading them.**

-Fill in the case names and the prompts. Everything below is `spawn_workers` /
-`sendwait` / `last_text` / `delete_session` from the §0 preamble, so there is nothing
-to assemble and no per-call body to hand-build.
+Fill in the case names and the prompts, then run it as your FIRST Bash call: no
+standalone preamble check before it (line one below IS that check), and no
+reconnaissance. `ls ~/codeman-cases` answers nothing this block needs: invented
+fresh names need no lookup, and `spawn_worker` refuses a name that already exists
+rather than silently reusing it. Everything below is `spawn_workers` / `sendwait` /
+`last_text` / `delete_session` from the §0 preamble, so there is nothing to assemble
+and no per-call body to hand-build.

 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null   # §0 loader
-[ "${CODEMAN_PREAMBLE:-}" = 1.18.3 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
-N=(alpha beta)                                        # one FRESH case name per worker
+[ "${CODEMAN_PREAMBLE:-}" = 1.19.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+N=(alpha beta)                    # INVENT one fresh case name per worker; never list cases first
 T=('reply with one line: the absolute path of your working directory'
   'reply with one line: your model name')            # tasks, same order as N

@@ -307,10 +315,16 @@ done; rm -rf "$D"

 Measured against a live 1.18.0 server: two cold workers spawned and ready in **6.3 s**,
 both turns dispatched and both answers read in **4.0 s** more. If your run takes minutes,
-the time went into deliberation, not the API. The three things that actually cost time:
+the time went into deliberation, not the API. The four things that actually cost time:

 - **Spawning serially.** One worker per Bash call is one model turn per worker. `&` plus
  `wait`, as above, makes N workers cost about what one costs.
+- **Reconnaissance turns before the spawn.** A standalone preamble check, an
+  `ls ~/codeman-cases`, a `list_sessions` "to see what is there": each is a whole
+  model turn spent learning something this block already handles (line one performs
+  the preamble check, invented names need no listing, and `spawn_worker` refuses
+  collisions). A live two-worker run spent ~12 s of its 28 s total on exactly two
+  such turns; the API work in between was under 10 s.
 - **Re-deriving the happy path** from §5.1 + §5.2 + §5.3 + §5.10. That is what the
  preamble functions exist to end. Compose them; do not rebuild them. The tells that
  you are rebuilding anyway: a `for` loop around `quick-start`, a poll on `.data.pid`,
@@ -329,7 +343,8 @@ Four things this block leans on, each one link away, no detour needed to run it:
  `~/codeman-cases/<name>`, not your repo. A name that already means something (a
  linked case, a pre-existing directory) is refused by `spawn_worker` rather than
  silently reused. Spawning where the work actually is (a linked case, a git worktree)
-  is a different call with **no hooks**, and the costliest mistake in this skill: §5.1.
+  is a different call, and picking the wrong one is the costliest mistake in this
+  skill: §5.1. Those workspaces do get hooks now, unless the operator disabled it.
 - `sendwait` supplies the `\r`, picks a fresh `seq`, and self-heals a stranded Enter.
  A prompt without the `\r` is never submitted (§3), a reused `seq` is silently
  swallowed as an already-applied duplicate, and an Enter eaten by an Ink repaint
@@ -344,9 +359,9 @@ One row per job. Acting on this table alone is correct; the §5 links are the de

 | I want to | Call | Detail |
 |-----------|------|--------|
-| start a worker **where the work is** | `POST /api/v1/quick-start {"caseName":…}`, which **creates** `~/codeman-cases/<name>` unless the name is already a case: full signals there. Any other path (a git worktree): `POST /api/v1/sessions {"workingDir":…}` then `POST /api/v1/sessions/:id/interactive`, and expect **no hooks**. N workers means N worktrees | [§5.1](reference/verbs.md#51-where-to-spawn) |
+| start a worker **where the work is** | `POST /api/v1/quick-start {"caseName":…}`, which **creates** `~/codeman-cases/<name>` unless the name is already a case. Any other path (a git worktree): `POST /api/v1/sessions {"workingDir":…}` then `POST /api/v1/sessions/:id/interactive`. Both install hooks by default, so expect full signals in either, and **verify** rather than assume. N workers means N worktrees | [§5.1](reference/verbs.md#51-where-to-spawn) |
 | know a new worker can accept a prompt | `GET .../wait-output?match=shift+tab&from=buffer` (urlencode the `+`) | [§5.2](reference/verbs.md#52-readiness) |
-| deliver a task **and** know when it finished | `POST .../input` with `"input":"…\r"`, `clientId`, `seq`, `"wait":true`. Resolves on `stop`, so it is only trustworthy in a **case Codeman created** (claude mode + hooks present). Costs the worker one billed turn | [§5.3](reference/verbs.md#53-send-a-task-and-wait) |
+| deliver a task **and** know when it finished | `POST .../input` with `"input":"…\r"`, `clientId`, `seq`, `"wait":true`. Resolves on `stop`, so it is trustworthy only where the workspace **has hooks** (claude mode; installed by default, but the operator can disable it and remote sessions never get them). Costs the worker one billed turn | [§5.3](reference/verbs.md#53-send-a-task-and-wait) |
 | know a hook-less worker finished | it has no `stop`, and `wait:true` there resolves on flapping `idle` **without erroring**: make it print a split, unique marker and `wait-output` on that instead | [§5.5](reference/verbs.md#55-markers-for-hook-less-workers) |
 | read the answer | `GET .../last-response`, **polled** (claude/codex only; empty for the other modes) | [§5.4](reference/verbs.md#54-read-the-answer) |
 | know if it is alive | `GET .../wait?until=exit&timeout=1000`: an immediate `signal:"exit"` means dead. `status` and `pid` both lie | [§5.6](reference/verbs.md#56-alive-and-stuck) |
@@ -1,4 +1,4 @@
-# ---- Codeman agent preamble 1.18.3 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# ---- Codeman agent preamble 1.19.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -60,14 +60,14 @@ spawn_worker() {
  # NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
  [ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
  [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; }   # only claude draws a composer
-  # quick-start RESOLVES the name before creating: a linked case or an existing dir
-  # wins over a fresh scratch case, so "created => hooks" is only true after this one
-  # local grep (the same marker the server itself checks for). No marker means sendwait
-  # would false-resolve on flapping idle, possibly inside the user's REAL repo: refuse
-  # rather than run the job there.
+  # The server installs hooks into every claude workspace now, so this grep normally
+  # passes; it stays because the install is gated on a setting the operator can turn
+  # off, remote sessions never get hooks, and a session created by an older server
+  # still has none. No marker means sendwait would false-resolve on flapping idle,
+  # possibly inside the user's REAL repo: refuse rather than run the job there.
  cp=$(jq -r '.data.casePath // empty' <<<"$q")
  grep -qs '/api/hook-event' "$cp/.claude/settings.local.json" || {
-    echo "case '$name' resolved to '$cp', which has no Codeman hooks (linked or pre-existing?): pick an unused name, or work §5.1+§5.5 by hand" >&2
+    echo "case '$name' resolved to '$cp', which has no Codeman hooks (workspaceHooksEnabled off, remote, or an older server?): turn the setting on, or work §5.1+§5.5 by hand with markers" >&2
    delete_session "$sid" >/dev/null; return 1; }
  # Short composer wait FIRST, then the trust-dialog probe: a case still showing the
  # dialog can never pass the composer wait, so probing early keeps a cold case from
@@ -155,4 +155,4 @@ last_text() {
 # The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
 # bare on purpose: the write condition above anchors on it with $, so an inline comment
 # here would fail that match and rewrite this file on every single bootstrap.
-CODEMAN_PREAMBLE=1.18.3
+CODEMAN_PREAMBLE=1.19.0
@@ -251,10 +251,12 @@ that is expected, not a failure: read `terminal?tail=` and strip ANSI instead.
 **It means** that session has no Codeman hooks, so `stop` can never fire and the wait
 silently degraded to `idle`, which flaps mid-turn. Nothing rejected your request:
 `wait:true` (and even an explicit `until=stop`) is accepted because the 400 is about
-session **mode**, and the mode really is `claude`. Hooks are written only when Codeman
-**creates** the directory; a linked case or a raw `workingDir` gets none (an existing
-case that Codeman created earlier keeps the block it was given), see the table under
-[Signals by mode](#signals-by-mode). Measured: on a
+session **mode**, and the mode really is `claude`. Hooks are installed into every
+claude workspace at session create (synced `workspaceHooksEnabled`, default ON) and
+swept across recovered sessions at boot, so a linked case or a raw `workingDir` gets
+them too; with the setting off, on a remote session, or on a session from an older
+server, they are absent, see the table under
+[Signals by mode](#signals-by-mode). Measured before that changed: on a
 linked case whose `.claude/settings.local.json` carries env/model/permissions/statusLine
 and no `hooks` block, a `wait?until=stop,exit` parked for twelve consecutive 60 s rounds
 never resolved although the worker finished its turn.
@@ -360,10 +362,10 @@ loop.
 ⚠️ `caseName` resolves through the linked-cases registry first, so a name that happens
 to match a case the user linked in lands in that **real repo**, not a fresh scratch
 directory. Pick distinctive scratch names, and use a linked name deliberately when you
-do want a worker in an existing checkout. ⚠️ It also decides whether you get hooks:
-Codeman writes them only when it **creates** the directory, so a linked case or a raw
-path gives you a worker with no `stop` signal, while a scratch case Codeman created
-earlier keeps working signals ([Signals by mode](#signals-by-mode)).
+do want a worker in an existing checkout. It no longer decides whether you get hooks:
+every claude create path installs them, so a linked case and a raw path both get a
+`stop` signal unless the operator turned `workspaceHooksEnabled` off
+([Signals by mode](#signals-by-mode)).

 **The two-step alternative, `POST /api/v1/sessions`.** Use it when you need a session in
 a directory that is not a case (body takes `workingDir`, `mode`, `name`, `effort`,
@@ -614,35 +616,27 @@ Three bounded long-polls. Shared semantics:
 | `exit` | PTY exited or session deleted | every mode |

 ⚠️ **`claude` mode is necessary for `stop`/`blocked`, not sufficient. The real
-precondition is that the session's working directory has a Codeman hooks block**, and
-whether it does depends on who created the directory:
+precondition is that the session's working directory has a Codeman hooks block**, which
+is now installed by default rather than depending on who created the directory:

 | The worker's directory | Hooks | `stop` / `blocked` | Synchronize with |
 |------------------------|-------|--------------------|------------------|
-| Codeman created it (`quick-start` with a NEW `caseName`, `POST /api/cases`, clone, docker quickcreate) | written at create | fire | send-and-wait on `stop` |
-| Codeman never created it (a linked case pointing at your own checkout, a raw `workingDir`) | none written | never fire | `wait-output` markers only |
+| any claude workspace, with `workspaceHooksEnabled` ON (the default) | installed at session create, add-only merge | fire | send-and-wait on `stop` |
+| the same, with the setting OFF and no block already on disk | none added | never fire | `wait-output` markers only |
+| a remote SSH session, a docker case that opted out, a workspace Codeman cannot write | none | never fire | `wait-output` markers only |
+| a session created by a pre-1.19.0 server and never restarted since | whatever it had | only if present | check, then choose |

-⚠️ **Docker cases are the one exception.** For a docker case, quick-start writes hooks
-whenever `.claude/settings.local.json` is *missing* (`session-routes.ts:2836-2845`:
-absent means write, present means refresh), regardless of who created that host
-directory. There the discriminator really is "does the settings file exist". No
-downstream advice changes, since docker quickcreate is already on the create side.
+The install is an add-only merge, so a user's own hook entries survive and a malformed
+settings file is left untouched. Sessions recovered at server boot get the same sweep,
+which is what heals sessions created before this behavior existed. When in doubt, test
+it rather than reason about it: grep for `/api/hook-event` in
+`<casePath>/.claude/settings.local.json`.

-⚠️ For every non-docker case the discriminator is **who created the directory, not
-whether it exists now**. A
-scratch case Codeman created last week still has its hooks block on disk, so
-`quick-start` against that existing name gets working `stop` signals. Only a directory
-Codeman never created lacks them. When in doubt, test it rather than reason about it:
-grep for `/api/hook-event` in `<casePath>/.claude/settings.local.json`.
-
-`writeHooksConfig()` runs only on the create paths (`case-routes.ts:341`, `:520`,
-`:869`, `ralph-routes.ts:318`, `session-routes.ts:2799` inside
-`if (!existsSync(resolvedCasePath))`, `:2841` for docker). Quick-start against a
-directory that already exists takes the else-if branch and calls
-`refreshStaleCodemanHooks()`, which returns immediately when there is no
-`settings.local.json` and again when the hooks it finds are not ours
-(`hooks-config.ts:706-731`); it never *adds* a hooks block. `POST /api/cases/link` is
-not on that list at all: it only records a name-to-path entry. See
+Before 1.19.0, `writeHooksConfig()` ran only on the create paths and `quick-start`
+against an existing directory called `refreshStaleCodemanHooks()`, which never *adds* a
+block, so a linked case or a raw `workingDir` had no hooks at all. `POST
+/api/cases/link` still only records a name-to-path entry; what changed is that the
+session-create path installs hooks regardless of how the directory got there. See
 [symptom 8](#8-send-and-wait-resolves-instantly-with-signalidle-and-the-answer-is-last-turns).

 Default `until` set: `stop,idle,exit`. On non-claude modes the server silently drops
@@ -196,12 +196,14 @@ idle:
 The contract an orchestrator follows for any fleet of two or more messaging workers.
 Every topology in the next section is this protocol plus a wiring diagram.

-1. **Spawn with a name, and with hooks.** Use `quick-start` with `sessionName` (the
-   `--name` gate above), and let it **CREATE** the case. ⚠️ Linking does NOT install
-   hooks (`POST /api/cases/link` writes only the name-to-path entry), and neither does a
-   bare `POST /api/sessions`; a worker in a directory Codeman did not create has no
-   `stop`/`blocked` signals at all and every synchronization below degrades to output
-   markers. The discriminator is who created the directory, not whether it exists now.
+1. **Spawn with a name, and confirm hooks.** Use `quick-start` with `sessionName` (the
+   `--name` gate above). Session create installs the hooks block into the workspace
+   whatever kind it is, so a linked case and a raw `POST /api/sessions` path both get
+   `stop`/`blocked` by default. ⚠️ Not unconditionally: the operator can turn
+   `workspaceHooksEnabled` off, remote SSH sessions never get hooks, and a session from
+   an older server may have none, and without them every synchronization below degrades
+   to output markers. Grep `<casePath>/.claude/settings.local.json` for
+   `/api/hook-event` at spawn rather than inferring it from how the directory got there.
 2. **Readiness before addressing.** Flow 1's ladder per worker, then the availability
   probe. A worker that fails the probe is an HTTP worker for the rest of the run; that
   is a routing decision, not an error.
@@ -492,9 +492,9 @@ What breaks if you use send-and-wait anyway: `wait:true` is accepted (the 400 is
 *mode*, not about hooks, and these are claude-mode sessions), so the call falls back to
 the default set's `idle`, which is a heuristic that flaps mid-turn. You get a "finished"
 answer for a turn still running, and `last-response` then hands you the *previous*
-turn's text. The contrast is the lesson: a worker in a case Codeman created (Flow 1) has
-the hooks, so `stop` there is definitive and free. In a worktree you pay one marker per
-worker instead.
+turn's text. The contrast is the lesson: a worker whose workspace carries the hooks
+block (Flow 1, and by default any other workspace too) has a `stop` that is definitive
+and free. Where the block is absent you pay one marker per worker instead.

 ```bash
 declare -A TOK
@@ -30,28 +30,40 @@ wrong directory.** `quick-start` with a new `caseName` does not find your repo:
 | Where the work is | Call | Hooks, and therefore signals |
 |-------------------|------|------------------------------|
 | a fresh scratch dir (throwaway experiments) | `POST /api/v1/quick-start {"caseName":"scratch-1","mode":"claude"}` with a **new** case name | Codeman creates the directory and **writes hooks**: `stop` and `blocked` fire, send-and-wait is trustworthy |
-| a linked case (a real repo in the linked-cases registry) | same call with the linked name | **no hooks**, unless that repo already carries a Codeman hooks block from some earlier path. Check before relying on `stop` |
-| any other absolute path, e.g. a git worktree you made | `POST /api/v1/sessions {"workingDir":"/abs/path","mode":"claude"}` then `POST /api/v1/sessions/:id/interactive` | **no hooks**: no `stop`, no `blocked`, synchronize with markers ([§5.5](#55-markers-for-hook-less-workers)) |
+| a linked case (a real repo in the linked-cases registry) | same call with the linked name | **hooks installed at session create**, so `stop` fires here too. Not guaranteed: the operator can turn it off. Check |
+| any other absolute path, e.g. a git worktree you made | `POST /api/v1/sessions {"workingDir":"/abs/path","mode":"claude"}` then `POST /api/v1/sessions/:id/interactive` | same: **hooks installed at session create**, subject to the same setting. Check |

 Read `.data.casePath` back from the `quick-start` response and check it is where you
 meant. `caseName` accepts letters, digits, `-` and `_` only, and it resolves through
 the linked-cases registry **first**, so a name that collides with something the user
 linked in lands in that real repo rather than a scratch dir.

-**The rule is who created the directory.** Codeman writes hooks only where it created
-the workspace itself: `quick-start` on a NEW case name, `POST /api/cases`, the repo
-clone, the docker quick-create. Those hooks persist, so a scratch case created last
-week still has them today. A directory that already existed when Codeman first pointed
-at it never gets them: `POST /api/cases/link` writes only the name-to-path entry in
-`linked-cases.json`, and quick-start into an existing path runs
-`refreshStaleCodemanHooks()`, which by design returns immediately when there is no
-Codeman hooks block to refresh. Source-verified by exhaustive call-site grep, and
-measured: a worker in a linked case never resolved a parked `wait?until=stop,exit`
-across twelve consecutive 60 s rounds, although it had finished its turn.
+**The rule is a setting, not who created the directory.** Every claude create path
+(`POST /api/sessions`, `POST /api/quick-start`, and quick-start's docker branch) now
+installs the hooks block into the workspace, and the server sweeps the workspaces of
+sessions it recovers at boot. So a linked case, a cloned repo and a hand-made git
+worktree all get `stop`/`blocked`, not just a scratch case Codeman scaffolded. The
+install is an **add-only merge**: a user's own hook entries and every other settings
+key survive, and a malformed settings file is left alone.

-**Check, do not assume.** Read `<casePath>/.claude/settings.local.json` with your own
-file tools and look for `/api/hook-event`. Present means `stop`/`blocked` will fire;
-absent means they never will.
+The gate is the synced **`workspaceHooksEnabled`** setting, **default ON** (an absent
+key counts as ON). Turned OFF, the old behavior returns exactly: an existing Codeman
+block is still refreshed when stale, but one is never added, and the boot sweep is
+skipped. Three cases stay hook-less regardless: **remote SSH sessions** (their
+`workingDir` is a path on another host), **docker cases that opted out**, and any
+workspace Codeman cannot write to.
+
+Until this landed, hooks existed only where Codeman created the directory, and the
+gap was invisible: a worker in a linked case never resolved a parked
+`wait?until=stop,exit` across twelve consecutive 60 s rounds, although it had finished
+its turn. If you are driving an older server, assume that older rule.
+
+**Check, do not assume.** This is now the load-bearing habit, because you cannot tell
+from the call which way the setting is set, and an old session created before the fix
+on a server that has not restarted still has nothing. Read
+`<casePath>/.claude/settings.local.json` with your own file tools and look for
+`/api/hook-event`. Present means `stop`/`blocked` will fire; absent means they never
+will, whatever kind of workspace it is.

 ⚠️ **The hook-less failure is silent, and it is the worst one in this skill.**
 `"wait":true` is still **accepted** on a hook-less claude session: the 400 you may be
@@ -59,9 +71,10 @@ expecting is about session *mode*, not about hooks. With no `stop` to resolve on
 default signal set falls back to the heuristic `idle`, which flaps mid-turn, so
 send-and-wait returns "finished" while the worker is still working, and the
 `last-response` you read next hands you the **previous** turn's text. No error is
-raised anywhere. In any workspace Codeman did not create, use markers
-([§5.5](#55-markers-for-hook-less-workers)) and treat send-and-wait's answer as
-unreliable.
+raised anywhere. Hooks are installed by default now, so this is rarer than it was, but
+the failure is unchanged when it happens: in any workspace whose settings file has no
+`/api/hook-event`, use markers ([§5.5](#55-markers-for-hook-less-workers)) and treat
+send-and-wait's answer as unreliable.

 Spawning at a raw path:

@@ -238,11 +251,13 @@ fi

 ### 5.3 Send a task and wait

-⚠️ **Precondition: this is the call to prefer only for a claude worker in a workspace
-Codeman created**, because it is trustworthy only when the `stop` hook exists. On a
-linked case or a raw path it is accepted, resolves on flapping `idle`, and reports a
-turn as finished while it is still running, with no error anywhere. Check hooks first
-([§5.1](#51-where-to-spawn)); where they are absent, use markers
+⚠️ **Precondition: a claude worker whose workspace has the hooks block**, because
+this is trustworthy only when the `stop` hook exists. Every claude create path installs
+it by default now, so that is the normal case, but where it is absent (the setting off,
+a remote session, an older server) the call is still accepted, resolves on flapping
+`idle`, and reports a turn as finished while it is still running, with no error
+anywhere. Check hooks first ([§5.1](#51-where-to-spawn)); where they are absent, use
+markers
 ([§5.5](#55-markers-for-hook-less-workers)).

 It registers the waiter *before* typing,
@@ -646,22 +646,28 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
 }

 /**
- * Ensures an explicitly managed case has the current Codeman hooks.
+ * Ensures a workspace Codeman is about to run Claude in 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.
+ * Unlike `refreshStaleCodemanHooks`, this may ADD Codeman handlers to a settings
+ * file that has none (a linked case, a cloned repo, any directory Codeman did not
+ * scaffold). It merges rather than replaces, so a user's own hook entries survive,
+ * and a malformed existing file is left untouched rather than replaced.
 *
- * ⚠️ It has NO production call site: PR #233 landed it with the hook scripts and never
- * wired it up, and knip can't flag it (`test/**` are entry points, so its tests count as
- * a use). Kept anyway, because it is redundant with neither sibling: `writeHooksConfig`
- * REPLACES a malformed settings file and rewrites unconditionally, and
- * `refreshStaleCodemanHooks` deliberately never adds hooks to a case that has none. The
- * one place it fits is quick-start's existing-case branch in session-routes.ts, and
- * moving that branch onto this function is a POLICY change (hooks would come back for a
- * user who deleted them from their case, and linked cases would start getting a hooks
- * block they have never had), so that call is left to the owner rather than made here.
+ * ⚠️ That "may add" is a deliberate POLICY, adopted 2026-08-15 after the symptom it
+ * causes was reported: hooks were only ever written when Codeman CREATED a case
+ * directory, so every session in a linked case ran with no hooks at all and each
+ * hook-driven surface was silently dead there — an AskUserQuestion dialog blocking
+ * the pane while the tab and the phone overview both read a calm `idle`, no
+ * Approvals Inbox item, no push, no definitive `stop`/`idle_prompt` for respawn, and
+ * no `stop`/`blocked` for the agent wait endpoints. The cost of the policy is the
+ * other direction: a user who DELETES Codeman's hooks from a workspace gets them
+ * back on the next session create there, because nothing on disk distinguishes
+ * "removed on purpose" from "never had any".
+ *
+ * Called from both session-create paths (`POST /api/sessions`, `POST /api/quick-start`)
+ * for claude mode, and from `restoreMuxSessions()` so sessions that predate this heal
+ * on the next server start. Claude Code re-reads the file, so a session ALREADY running
+ * in the workspace picks the hooks up without a restart (verified live, 2026-08-15).
 */
 export async function ensureCodemanHooks(casePath: string): Promise<void> {
  await withSafeSettingsWrite(casePath, 'hooks (ensure)', async (claudeDir, settingsPath) => {
@@ -19,6 +19,8 @@ export interface ConfigPort {
  getTerminalHistoryConfig(): Promise<TerminalHistoryConfig>;
  /** Synced `agentSkillEnabled` app setting (default OFF); gates per-case agent-skill injection. */
  getAgentSkillEnabled(): Promise<boolean>;
+  /** Synced `workspaceHooksEnabled` app setting (default ON); gates INSTALLING hooks into a session's workspace. */
+  getWorkspaceHooksEnabled(): Promise<boolean>;
  /** Synced `claudeVoiceEnabled` app setting (default OFF); gates the Claude voice dictation relay. */
  getClaudeVoiceEnabled(): Promise<boolean>;
  getDefaultClaudeMdPath(): Promise<string | undefined>;
@@ -3992,7 +3992,7 @@ class CodemanApp {
        ? (session.workingDir ? `${parsedName.prefix} (${session.workingDir})` : parsedName.prefix)
        : (session.workingDir || '');

-      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${loadState ? ' tab-loading' : ''}" data-id="${id}" data-color="${color}" ${loadState ? `data-load-phase="${escapeHtml(loadState.phase)}"` : ''} onclick="app.handleSessionTabClick(event, ${escapeHtml(JSON.stringify(id))})" oncontextmenu="event.preventDefault(); app.startInlineRename(${escapeHtml(JSON.stringify(id))})" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-busy="${loadState ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${tabTooltip ? `title="${escapeHtml(tabTooltip)}"` : ''}>
+      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${loadState ? ' tab-loading' : ''}${this.hasTabDetachOverride(id) ? ' tab-show-detach' : ''}" data-id="${id}" data-color="${color}" ${loadState ? `data-load-phase="${escapeHtml(loadState.phase)}"` : ''} onclick="app.handleSessionTabClick(event, ${escapeHtml(JSON.stringify(id))})" oncontextmenu="event.preventDefault(); app.startInlineRename(${escapeHtml(JSON.stringify(id))})" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-busy="${loadState ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${tabTooltip ? `title="${escapeHtml(tabTooltip)}"` : ''}>
          ${_tabIdx < 9 ? '<span class="tab-number">' + (_tabIdx + 1) + '</span>' : ''}
          ${loadState ? '<span class="tab-load-spinner" aria-hidden="true"></span>' : ''}
          <span class="tab-status ${status}" aria-hidden="true"></span>
@@ -37,13 +37,21 @@ Object.assign(CodemanApp.prototype, {
  async seedApprovals() {
    if (!this.approvals) this.approvals = new Map();
    this.approvals.clear();
-    if (this.approvalsInboxEnabled()) {
-      const data = await this._apiJson('/api/approvals');
-      for (const item of (data && data.approvals) || []) {
-        this.approvals.set(item.id, item);
-        // Re-arm the tab alert state machine (idempotent set-add).
-        this.setPendingHook(item.sessionId, approvalKindToHook(item.kind));
-      }
+    // ⚠ Fetch and re-arm the tab-alert state machine REGARDLESS of the inbox
+    // setting. The server-side approval store runs unconditionally (only the
+    // inbox SURFACES are opt-in), and the red/yellow tab alert predates the
+    // inbox: gating the seed on the setting meant that with the inbox off, a
+    // reload landed with every alert store empty while a permission dialog sat
+    // blocking a session (owner report 2026-08-15: rail said NEEDS YOU from
+    // the live SSE event, the reloaded-elsewhere tab showed a plain green
+    // dot). Only populating `this.approvals` (bell/drawer/answer strips) stays
+    // behind the setting.
+    const data = await this._apiJson('/api/approvals');
+    const inboxOn = this.approvalsInboxEnabled();
+    for (const item of (data && data.approvals) || []) {
+      if (inboxOn) this.approvals.set(item.id, item);
+      // Re-arm the tab alert state machine (idempotent set-add).
+      this.setPendingHook(item.sessionId, approvalKindToHook(item.kind));
    }
    this.renderApprovals();
  },
@@ -68,14 +76,15 @@ Object.assign(CodemanApp.prototype, {
  },

  _onApprovalResolved(info) {
-    if (!info || !info.id || !this.approvals) return;
-    if (this.approvals.delete(info.id)) {
-      // Clear the matching tab alert: the inbox resolves on more signals than
-      // the hook handlers do (superseded, expired, answered from another
-      // device), and clearPendingHooks is a no-op when nothing is set.
-      this.clearPendingHooks(info.sessionId, approvalKindToHook(info.kind));
-      this.renderApprovals();
-    }
+    if (!info || !info.id) return;
+    // Clear the matching tab alert UNCONDITIONALLY: the inbox resolves on more
+    // signals than the hook handlers do (superseded, expired, answered from
+    // another device), clearPendingHooks is a no-op when nothing is set, and
+    // with the inbox setting OFF the item was never stored in `this.approvals`
+    // even though seedApprovals armed the alert — gating the clear on a map hit
+    // would strand that alert forever.
+    this.clearPendingHooks(info.sessionId, approvalKindToHook(info.kind));
+    if (this.approvals?.delete(info.id)) this.renderApprovals();
  },

  // ─── Actions ─────────────────────────────────────────────────
@@ -222,23 +222,35 @@ function computeTabScrollLeft(input) {
 // endpoint scrolled outside the strip. `.session-tabs` is `overflow-x: auto`, so a
 // scrolled-out tab still HAS a rect — one lying over the logo or the header
 // buttons. Skipping is honest; clamping would point at a tab that isn't there.
-// ⚠ THE DIP IS WHAT MAKES THE ARC AN ARC, and the first shipped numbers were tuned
-// against two tabs sitting side by side. A worker the agent skill starts is appended
-// to the END of the strip, so the real span between a lead and its worker is 800-1500px,
-// not 200, and a 44px cap over 1300px of span is a 33px sag, i.e. a line that reads as
-// STRAIGHT and crosses the terminal instead of bracketing under the strip. The dip now
-// keeps growing with the span (0.085/px, ~3x steeper against the old cap) so the bracket
-// survives the distance the feature is actually used at. The ceiling is what keeps a
-// full-width pair out of the terminal's fourth line: 104 + the sibling step lands the
-// deepest sag around y=140 on a 1080 screen, the same proportion two adjacent tabs get.
+// ⚠ THE DIP IS WHAT MAKES THE ARC AN ARC, and it has now been mis-tuned in BOTH
+// directions, so treat these numbers as a corridor rather than a dial to crank:
+// - Too shallow (the first ship, 44px cap): a skill worker is appended to the END of
+//   the strip, so a lead-to-worker span is 800-1500px, and a 44px cap over 1300px is
+//   a 33px sag, a line that reads as STRAIGHT across the terminal (#285).
+// - Too deep (the 104px cap that replaced it): in the wrapped-strip case the cap and
+//   the FULL row offset stacked, bowing the bracket ~106px into the terminal text
+//   (owner screenshot 2026-08-15, "die Linien machen einen grossen Bogen nach unten").
+// The dip is measured from the STRIP'S BOTTOM EDGE (falling back to the lower tab
+// bottom when the strip rect is missing or shorter than its tabs), which buys two
+// things at once: the bow needs no per-row offsets stacked on top, and a same-row
+// arc between ROW-1 tabs of a wrapped strip clears row 2's labels instead of being
+// drawn through them (the retune's own first draft had exactly that regression).
 const LINEAGE_DIP_BASE_PX = 14;
-const LINEAGE_DIP_PER_PX = 0.085;
+const LINEAGE_DIP_PER_PX = 0.06;
 const LINEAGE_DIP_MIN_PX = 22;
-const LINEAGE_DIP_MAX_PX = 104;
+const LINEAGE_DIP_MAX_PX = 64;
 // Siblings nest by this much. Widened with the stroke: at 2.5px plus its glow, arcs 6px
 // apart bled into one thick band instead of reading as three separate lines.
 const LINEAGE_SIBLING_STEP_PX = 8;
 const LINEAGE_STRIP_TOLERANCE_PX = 4;
+// Lineage palette, assigned per CHILD in first-seen order and cycled (session-lineage.js).
+// The empty FIRST entry means "no override": the CSS then falls back to --session-blue,
+// which every skin block tunes for its own background, so a lone arc keeps the
+// skin-aware blue that shipped in 1.18.2. The fixed entries are deliberately vivid
+// (owner call 2026-08-15: matrix green, pinkish, violet, red, turquoise "and so on");
+// they ride the same double glow as the blue, which is what keeps them legible over
+// terminal text on every skin.
+const LINEAGE_COLORS = ['', '#00ff66', '#ff5ea8', '#a78bfa', '#ff5252', '#2dd4bf', '#ffa940'];

 function computeLineagePath(input) {
  const parent = input?.parent;
@@ -269,18 +281,19 @@ function computeLineagePath(input) {
  const cBottom = cTop + ch;
  const sameRow = Math.abs(pTop + ph / 2 - (cTop + ch / 2)) <= Math.min(ph, ch) / 2;

-  // Both ends anchor on the tab BOTTOM, and the control points hang below whichever
-  // row is lower, so one formula covers a flat strip and a wrapped one.
+  // Both ends anchor on the tab BOTTOM, and the control points hang below the WHOLE
+  // strip, so one formula covers a flat strip, a wrapped pair, and a same-row pair
+  // sitting above further rows (see the corridor note above the constants).
  const span = Math.abs(cx - px);
-  const rowDrop = Math.abs(cBottom - pBottom);
-  // ⚠ A wrapped pair needs the dip measured from the LOWER row, or the bracket would
-  // only reach the row gap again. Adding the row offset also keeps the curve clear of
-  // the row it crosses instead of grazing its bottom edge.
+  const stripBottom =
+    strip && Number(strip.height) > 0 && Number.isFinite(Number(strip.top))
+      ? Number(strip.top) + Number(strip.height)
+      : Number.NEGATIVE_INFINITY;
+  const baseline = Math.max(pBottom, cBottom, stripBottom);
  const dip =
    Math.min(LINEAGE_DIP_MAX_PX, Math.max(LINEAGE_DIP_MIN_PX, LINEAGE_DIP_BASE_PX + span * LINEAGE_DIP_PER_PX)) +
-    depth * LINEAGE_SIBLING_STEP_PX +
-    rowDrop;
-  const yc = Math.max(pBottom, cBottom) + dip;
+    depth * LINEAGE_SIBLING_STEP_PX;
+  const yc = baseline + dip;
  const d = `M ${r1(px)} ${r1(pBottom)} C ${r1(px)} ${r1(yc)}, ${r1(cx)} ${r1(yc)}, ${r1(cx)} ${r1(cBottom)}`;
  return { d, endX: cx, endY: cBottom, sameRow };
 }
@@ -441,6 +454,7 @@ if (typeof window !== 'undefined') {
    DIP_MIN_PX: LINEAGE_DIP_MIN_PX,
    DIP_MAX_PX: LINEAGE_DIP_MAX_PX,
    SIBLING_STEP_PX: LINEAGE_SIBLING_STEP_PX,
+    COLORS: LINEAGE_COLORS,
  };
  window.CodemanConnectionLoss = {
    compute: computeConnectionLossUi,
@@ -1211,6 +1211,13 @@
                      </button>
                    </div>
                  </div>
+                  <div class="set-row" data-search="pop out detach tab window this session">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Pop-out button on this tab</span>
+                      <span class="set-row-desc">Show the open-in-a-window button on this tab even while the general App Settings toggle is off.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="sessionOptShowTabDetach" onchange="app.onSessionTabDetachToggle(this.checked)"><span class="slider"></span></label>
+                  </div>
                </div>
              </div>

@@ -1977,6 +1984,13 @@
                    </div>
                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsAgentSkill"><span class="slider"></span></label>
                  </div>
+                  <div class="set-row" data-search="workspace hooks alerts approvals notifications settings.local.json">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Workspace Hooks</span>
+                      <span class="set-row-desc">Install Codeman's hooks in each Claude workspace, so tab alerts, the Approvals Inbox and idle detection also work in linked cases and existing repos. Off leaves your repos untouched.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsWorkspaceHooks"><span class="slider"></span></label>
+                  </div>
                  <div class="set-row" data-search="remote auto reconnect ssh">
                    <div class="set-row-text">
                      <span class="set-row-label">Remote auto-reconnect</span>
@@ -23,7 +23,7 @@
 *
 * @mixin Extends CodemanApp.prototype via Object.assign
 * @dependency subagent-windows.js (_updateConnectionLinesImmediate, #connectionLines)
- * @dependency constants.js (window.CodemanLineage.computePath)
+ * @dependency constants.js (window.CodemanLineage.computePath + .COLORS)
 * @dependency settings-ui.js (loadAppSettingsFromStorage, getDefaultSettings)
 * @loadorder 15.6 (after ultracode-windows.js — appended to the same SVG pass)
 */
@@ -90,6 +90,35 @@ Object.assign(CodemanApp.prototype, {
    return edges;
  },

+  /**
+   * Colour for one child's arc, from CodemanLineage.COLORS, assigned in FIRST-SEEN
+   * order and remembered per child id. First-seen rather than draw-index keeps a
+   * line's colour stable across re-renders, tab reorders and sibling closes (the
+   * SVG is wiped and rebuilt constantly, so an index-based colour would flicker).
+   * An empty string means "no override": the CSS falls back to --session-blue.
+   */
+  _lineageColorFor(childId) {
+    const palette = (window.CodemanLineage && window.CodemanLineage.COLORS) || [];
+    if (palette.length === 0) return '';
+    if (!this._lineageColorByChild) {
+      this._lineageColorByChild = new Map();
+      this._lineageColorNext = 0;
+    }
+    let idx = this._lineageColorByChild.get(childId);
+    if (idx === undefined) {
+      idx = this._lineageColorNext++ % palette.length;
+      this._lineageColorByChild.set(childId, idx);
+      // Bounded: entries for long-gone sessions are pruned once the map is clearly
+      // stale, so a day-long dashboard cannot grow it without limit.
+      if (this._lineageColorByChild.size > 200 && this.sessions) {
+        for (const key of this._lineageColorByChild.keys()) {
+          if (!this.sessions.has(key)) this._lineageColorByChild.delete(key);
+        }
+      }
+    }
+    return palette[idx] || '';
+  },
+
  /**
   * Append the lineage layer to the shared SVG pass.
   *
@@ -137,6 +166,10 @@ Object.assign(CodemanApp.prototype, {
      // the line itself. `status` is the CHILD's, which is the interesting end.
      const working = edge.status === 'working' ? ' lineage-line--working' : '';
      line.setAttribute('class', 'connection-line lineage-line' + working);
+      // Per-child colour rides a CSS custom property so the stylesheet keeps owning
+      // opacity, glow and dash; an empty colour leaves the --session-blue fallback.
+      const color = this._lineageColorFor(edge.childId);
+      if (color) line.style.setProperty('--lineage-color', color);
      // `data-agent-id` is what _applyLineEntrances() queries — see the file header.
      line.setAttribute('data-agent-id', 'lineage:' + edge.childId);
      line.setAttribute('data-parent-tab', edge.parentId);
@@ -153,6 +186,7 @@ Object.assign(CodemanApp.prototype, {
      dot.setAttribute('r', '3.5');
      dot.setAttribute('class', 'lineage-line-dot' + working);
      dot.setAttribute('data-child-tab', edge.childId);
+      if (color) dot.style.setProperty('--lineage-color', color);
      svg.appendChild(dot);
    }
  },
@@ -1283,12 +1283,65 @@ Object.assign(CodemanApp.prototype, {
  // Session Options Modal
  // ═══════════════════════════════════════════════════════════════

+  /**
+   * Per-TAB pop-out button override (Session Options → Session → Identity). The
+   * general `showTabDetachButton` App Setting stays the per-device default for ALL
+   * tabs; this map whitelists single sessions on top of it, so one tab can carry
+   * the ⧉ button while the general toggle stays off. Per-device on purpose, like
+   * the general setting: it is a display choice, so it lives in localStorage and
+   * never touches the server schema. Rendered as the `tab-show-detach` class on
+   * the tab (see _fullRenderSessionTabs), which styles.css exempts from the
+   * global `display: none` gate; the active-tab reveal rules stay shared, so an
+   * overridden tab behaves exactly like a tab under the general toggle.
+   */
+  _tabDetachOverrides() {
+    if (this._tabDetachOverrideMap === undefined) {
+      try {
+        this._tabDetachOverrideMap = JSON.parse(localStorage.getItem('codeman:tab-detach-overrides') || '{}') || {};
+      } catch (_e) {
+        this._tabDetachOverrideMap = {};
+      }
+    }
+    return this._tabDetachOverrideMap;
+  },
+
+  hasTabDetachOverride(sessionId) {
+    return !!this._tabDetachOverrides()[sessionId];
+  },
+
+  onSessionTabDetachToggle(on) {
+    const id = this.editingSessionId;
+    if (!id) return;
+    const map = this._tabDetachOverrides();
+    if (on) map[id] = 1;
+    else delete map[id];
+    // Prune ids whose sessions are gone, so closed sessions cannot grow the map.
+    for (const key of Object.keys(map)) {
+      if (key !== id && this.sessions && !this.sessions.has(key)) delete map[key];
+    }
+    try {
+      localStorage.setItem('codeman:tab-detach-overrides', JSON.stringify(map));
+    } catch (_e) {
+      /* storage full/blocked: the in-memory map still applies this page load */
+    }
+    // Apply to the LIVE tab directly: the debounced render may take the
+    // incremental path (same session set), which patches rather than rebuilds,
+    // so the template's class would only land on the next full render. Future
+    // full renders re-emit it from _fullRenderSessionTabs.
+    const tab = document.querySelector(`.session-tab[data-id="${CSS.escape(id)}"]`);
+    if (tab) tab.classList.toggle('tab-show-detach', !!on);
+  },
+
  openSessionOptions(sessionId) {
    const session = this.sessions.get(sessionId);
    if (!session) return;

    this.editingSessionId = sessionId;

+    // Per-tab pop-out override state (see _tabDetachOverrides above).
+    const detachToggle = document.getElementById('sessionOptShowTabDetach');
+    if (detachToggle) detachToggle.checked = this.hasTabDetachOverride(sessionId);
+
    // Reset to an appropriate tab — Summary for external CLIs (Respawn/Ralph are Claude-only)
    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi';
    this.switchOptionsTab(isAltMode ? 'summary' : 'respawn');
@@ -409,6 +409,9 @@ Object.assign(CodemanApp.prototype, {
    // Claude Permissions settings
    document.getElementById('appSettingsAgentTeams').checked = settings.agentTeamsEnabled ?? false;
    document.getElementById('appSettingsAgentSkill').checked = settings.agentSkillEnabled ?? false;
+    // Default ON: an absent key is a user who has never seen this setting, and OFF
+    // for them means no tab alerts in any workspace Codeman did not scaffold.
+    document.getElementById('appSettingsWorkspaceHooks').checked = settings.workspaceHooksEnabled !== false;
    document.getElementById('appSettingsClaudeModel').value = settings.claudeModel ?? '';
    document.getElementById('appSettingsOpusContext1m').checked = settings.opusContext1mEnabled ?? false;
    document.getElementById('appSettingsRemoteAutoReconnect').checked = settings.remoteAutoReconnect ?? true;
@@ -2017,6 +2020,7 @@ Object.assign(CodemanApp.prototype, {
      // Claude Permissions settings
      agentTeamsEnabled: document.getElementById('appSettingsAgentTeams').checked,
      agentSkillEnabled: document.getElementById('appSettingsAgentSkill').checked,
+      workspaceHooksEnabled: document.getElementById('appSettingsWorkspaceHooks').checked,
      claudeVoiceEnabled: document.getElementById('appSettingsClaudeVoice').checked,
      claudeModel: document.getElementById('appSettingsClaudeModel').value,
      opusContext1mEnabled: document.getElementById('appSettingsOpusContext1m').checked,
@@ -1459,23 +1459,80 @@ html[data-line-anim="packet"] .connection-line.line-enter {
  color: var(--green);
 }

-/* Tab alert animations */
-.session-tab.tab-alert-action {
+/* Tab alerts: a STEADY red/yellow base with a pulse breathing on top.
+   ⚠ The original animation swung background AND border to transparent at its
+   0%/100% keyframes, so for roughly half of every cycle an alerted tab was
+   indistinguishable from a normal one: a glance (or a screenshot, owner report
+   2026-08-15) read "no alert" while the home rail showed a steady NEEDS YOU.
+   A pending permission is BLOCKING the agent, so the tab must look blocked at
+   every instant; only the intensity is allowed to move. The status dot joins
+   in (red/yellow, (0,4,0) so it outranks the skin block's (0,3,1) dot rules),
+   mirroring the phone overview's red-row language. */
+/* The alert paints on ::before, NEVER on the tab element: .session-tab.active
+   forces background/border/box-shadow with !important, and !important beats
+   even a running animation, so an element-level alert vanished the moment the
+   tab was selected. The permission is still blocking while you look at it, so
+   the red ring must survive selection and clear only on resolution (owner call
+   2026-08-15). Same convention as the entrance styles (see the tab-enter block).
+   (0,3,x) via the strip parent on purpose: the non-OG skin block quiets
+   decorative glows (`.tab-glow { box-shadow: none }` lands at (0,2,1)), and an
+   alert halo is signal, not decor, so it must outrank that on every skin.
+   The overlay paints above the tab's inline content (positioned vs flow), which
+   is fine at these alphas and is exactly what keeps it visible over the active
+   tab's opaque-ish background. */
+.session-tabs .session-tab.tab-alert-action::before {
+  content: '';
+  position: absolute;
+  inset: -2px;
+  border-radius: inherit;
+  pointer-events: none;
+  /* Explicit: .tab-enter::before (entrance animations) parks ::before at
+     opacity 0 with fill-mode both, and an alerted tab that is also entering
+     would otherwise inherit that and render an invisible alert. Our animation
+     shorthand already displaces theirs at this specificity; the opacity must
+     be pinned the same way. */
+  opacity: 1;
+  border: 2px solid var(--red);
+  background: rgba(239, 68, 68, 0.12);
+  box-shadow: 0 0 8px rgba(239, 68, 68, 0.4);
  animation: tab-blink-red 2.5s ease-in-out infinite;
 }

-.session-tab.tab-alert-idle {
+.session-tab.tab-alert-action .tab-status.idle,
+.session-tab.tab-alert-action .tab-status.busy,
+.session-tab.tab-alert-action .tab-status {
+  background: var(--red);
+  box-shadow: 0 0 6px rgba(239, 68, 68, 0.7);
+}
+
+.session-tabs .session-tab.tab-alert-idle::before {
+  content: '';
+  position: absolute;
+  inset: -2px;
+  border-radius: inherit;
+  pointer-events: none;
+  opacity: 1; /* see the action variant above */
+  border: 2px solid var(--yellow);
+  background: rgba(234, 179, 8, 0.1);
+  box-shadow: 0 0 8px rgba(234, 179, 8, 0.35);
  animation: tab-blink-yellow 3.5s ease-in-out infinite;
 }

+.session-tab.tab-alert-idle .tab-status.idle,
+.session-tab.tab-alert-idle .tab-status.busy,
+.session-tab.tab-alert-idle .tab-status {
+  background: var(--yellow);
+  box-shadow: 0 0 6px rgba(234, 179, 8, 0.6);
+}
+
@keyframes tab-blink-red {
-  0%, 100% { background: transparent; border-color: transparent; }
-  50% { background: rgba(239, 68, 68, 0.12); border-color: var(--red); }
+  0%, 100% { background: rgba(239, 68, 68, 0.12); box-shadow: 0 0 8px rgba(239, 68, 68, 0.4); }
+  50% { background: rgba(239, 68, 68, 0.3); box-shadow: 0 0 16px rgba(239, 68, 68, 0.75); }
 }

@keyframes tab-blink-yellow {
-  0%, 100% { background: transparent; border-color: transparent; }
-  50% { background: rgba(234, 179, 8, 0.1); border-color: var(--yellow); }
+  0%, 100% { background: rgba(234, 179, 8, 0.1); box-shadow: 0 0 8px rgba(234, 179, 8, 0.35); }
+  50% { background: rgba(234, 179, 8, 0.24); box-shadow: 0 0 14px rgba(234, 179, 8, 0.65); }
 }

@keyframes pulse {
@@ -2081,8 +2138,12 @@ html[data-line-anim="packet"] .connection-line.line-enter {
 /* Pop-out button is opt-in (App Settings → Tab Bar, default off; per-device).
   settings-ui.js mirrors the setting as the tabs-show-detach class on <html>.
   A tab that is ALREADY detached keeps its icon regardless: it is the
-   re-focus affordance for the popped-out window. */
-html:not(.tabs-show-detach) .session-tab:not(.detached) .tab-detach {
+   re-focus affordance for the popped-out window. A SINGLE tab can also opt in
+   via Session Options → Session (`tab-show-detach` on the tab, per-device map
+   in session-ui.js) while the general toggle stays off; the active-tab reveal
+   rules above are shared, so the overridden tab behaves identically. Phones are
+   unaffected either way: mobile.css hides .tab-detach with !important. */
+html:not(.tabs-show-detach) .session-tab:not(.detached):not(.tab-show-detach) .tab-detach {
  display: none;
 }

@@ -9329,11 +9390,15 @@ kbd {
   Deliberately quieter and thinner than the subagent lines above so the two
   layers read as different things in the same SVG.

-   Colour comes from --session-blue, which EVERY skin block already defines and
-   already tunes for its own background, so one rule covers all seven (the four
-   light skins included). Do not add a per-skin `.lineage-line` override inside the
-   html:not([data-skin="og"]) block: a bare class rule in there resolves to (0,2,1)
-   and would outrank this one from a surprising place.
+   Colour: every rule reads --lineage-color, which session-lineage.js sets INLINE
+   per line from the CodemanLineage.COLORS palette (per child, first-seen order,
+   owner call 2026-08-15: several connected tabs must get several colours). The
+   FIRST line gets no override, so it falls through to --session-blue, which EVERY
+   skin block already defines and tunes for its own background; a lone arc therefore
+   still renders the skin-aware blue that shipped in 1.18.2. Do not add a per-skin
+   `.lineage-line` override inside the html:not([data-skin="og"]) block: a bare
+   class rule in there resolves to (0,2,1) and would outrank this one from a
+   surprising place.

   ⚠ BLUE, NOT THE VIOLET THIS SHIPPED WITH (owner call, 2026-08-14: "make these
   lines in blue that they are better visible"). Violet sits close to the terminal's
@@ -9352,13 +9417,13 @@ kbd {
   (4 4 on a 2.5px line reads as a dotted smudge), and `lineage-flow` marches by
   exactly two dash cycles, so it has to move with them. */
 .connection-line.lineage-line {
-  stroke: var(--session-blue, #2b8fd9);
+  stroke: var(--lineage-color, var(--session-blue, #2b8fd9));
  stroke-width: 2.5;
  stroke-dasharray: 5 5;
  stroke-linecap: round;
  opacity: 0.72;
-  filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.7)) drop-shadow(0 0 5px var(--session-blue, #2b8fd9))
-    drop-shadow(0 0 11px var(--session-blue, #2b8fd9));
+  filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.7)) drop-shadow(0 0 5px var(--lineage-color, var(--session-blue, #2b8fd9)))
+    drop-shadow(0 0 11px var(--lineage-color, var(--session-blue, #2b8fd9)));
 }

 /* ⚠ OUTSIDE the reduced-motion block below on purpose. A working child is the case
@@ -9374,9 +9439,10 @@ kbd {
 }

 .lineage-line-dot {
-  fill: var(--session-blue, #2b8fd9);
+  fill: var(--lineage-color, var(--session-blue, #2b8fd9));
  opacity: 0.85;
-  filter: drop-shadow(0 0 4px var(--session-blue, #2b8fd9)) drop-shadow(0 0 9px var(--session-blue, #2b8fd9));
+  filter: drop-shadow(0 0 4px var(--lineage-color, var(--session-blue, #2b8fd9)))
+    drop-shadow(0 0 9px var(--lineage-color, var(--session-blue, #2b8fd9)));
 }

 /* The child end marches while that worker is actually working, so the line
@@ -84,6 +84,7 @@ import {
  applyAgentSkill,
  refreshUserAgentSkill,
  seedAgentSessionPreamble,
+  ensureCodemanHooks,
  refreshStaleCodemanHooks,
 } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
@@ -625,6 +626,32 @@ async function injectAgentSkill(casePath: string): Promise<void> {
  }
 }

+/**
+ * Hooks for the workspace a Claude session is about to run in. ONE decision point,
+ * shared by every create path, so the setting cannot apply to some of them only.
+ *
+ * ON (`workspaceHooksEnabled`, the default): INSTALL Codeman's hooks block, merging
+ * so a user's own hook entries and every other settings key survive. Hooks were
+ * previously written only when Codeman CREATED the case DIRECTORY, so a linked case
+ * or any pre-existing repo — where most sessions actually run — had none, and every
+ * hook-driven surface was silently dead there: no tab alert or phone-overview row
+ * when a dialog blocks the pane, no Approvals Inbox item, no push, no definitive
+ * `stop`/`idle_prompt` for respawn, and no `stop`/`blocked` for the wait endpoints.
+ * Measured 2026-08-15 in a linked case: an AskUserQuestion dialog on screen with the
+ * tab reporting a calm `idle`. Claude Code re-reads the file, so a session already
+ * running in that workspace starts firing hooks without a restart (verified live).
+ *
+ * OFF: the older, narrower behavior. A Codeman block that is already there is still
+ * refreshed when stale (COD-91: a pre-secret block 401s once the hook-secret gate
+ * went unconditional), but one is never added, so Codeman leaves the repo alone.
+ *
+ * Best-effort either way: a refusal or a thrown error must never fail the create.
+ */
+async function applyWorkspaceHooks(ctx: ConfigPort, workspace: string): Promise<void> {
+  const install = await ctx.getWorkspaceHooksEnabled();
+  await (install ? ensureCodemanHooks(workspace) : refreshStaleCodemanHooks(workspace)).catch(() => {});
+}
+
 export function registerSessionRoutes(
  app: FastifyInstance,
  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
@@ -765,11 +792,14 @@ export function registerSessionRoutes(
      await applyStatusLineConfig(workingDir, true);
    }

-    // COD-91 self-heal: refresh a pre-secret hooks block in an existing case so the now
-    // 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 refreshStaleCodemanHooks(workingDir).catch(() => {});
+    // Hooks for the workspace this session runs in (install vs refresh-only is the
+    // `workspaceHooksEnabled` setting; see applyWorkspaceHooks). Never for a remote
+    // attach (workingDir is a user@host:session pseudo-path — mkdir would create it
+    // as a junk local dir), and only when the caller named a workingDir: the
+    // process-cwd fallback is $HOME under installer-created services, and hooks
+    // materializing in ~/.claude/settings.local.json was never asked for.
+    if (!remote && body.workingDir && (body.mode ?? 'claude') === 'claude') {
+      await applyWorkspaceHooks(ctx, workingDir);
      // Agent skill (docs/agent-control-plan.md §2): ADD-ONLY on create, same shared-
      // .claude rationale as the statusLine above: a create must never remove the
      // skill from under other live sessions in the repo. Marker-guarded, so a
@@ -2899,11 +2929,17 @@ export function registerSessionRoutes(
        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
      }
    } else if (!remote && !docker && mode !== 'opencode') {
-      // COD-91 self-heal for an EXISTING case: refresh a pre-secret hooks block so the
-      // 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 refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
+      // EXISTING case directory (a linked case, a cloned repo, anything Codeman did
+      // not scaffold): install-or-refresh per the setting (see applyWorkspaceHooks).
+      // Other modes keep the narrower COD-91 self-heal unconditionally: only claude
+      // reads `.claude` hooks, so a shell/codex quick-start should not author a block
+      // of its own. Skipped for remote cases — resolvedCasePath is a REMOTE path that
+      // doesn't exist on the local filesystem.
+      if (mode === 'claude') {
+        await applyWorkspaceHooks(ctx, resolvedCasePath);
+      } else {
+        await refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
+      }
    }

    // Agent skill injection (docs/agent-control-plan.md §2): ADD-ONLY on create,
@@ -2936,7 +2972,10 @@ export function registerSessionRoutes(
        if (!existsSync(join(resolvedCasePath, '.claude', 'settings.local.json'))) {
          await writeHooksConfig(resolvedCasePath);
        } else {
-          await refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
+          // A settings file with no hooks in it is the same dead-surface case as a
+          // linked case. This branch is already gated on `docker.hooksEnabled`, and
+          // applyWorkspaceHooks adds the user-level gate on top.
+          await applyWorkspaceHooks(ctx, resolvedCasePath);
        }
      } catch {
        /* non-fatal — the session still runs, hooks may be degraded */
@@ -906,6 +906,17 @@ export const SettingsUpdateSchema = z
     * add-only at create; a marker keeps user-authored copies untouched.
     */
    agentSkillEnabled: z.boolean().optional(),
+    /**
+     * Install Codeman's hooks block into the workspace of every Claude session,
+     * not only into cases Codeman scaffolded itself. SYNCED, default ON: without
+     * it a linked case or an existing repo runs with no hooks at all, and each
+     * hook-driven surface is silently dead there (tab alert, Approvals Inbox,
+     * push, respawn's definitive idle signals, the wait endpoints' stop/blocked).
+     * Turning it OFF restores the older, narrower behavior — a Codeman hooks
+     * block that is already present is still refreshed when stale, but one is
+     * never added — for a user who wants Codeman to leave their repos alone.
+     */
+    workspaceHooksEnabled: z.boolean().optional(),
    /**
     * Let browser dictation transcribe through this machine's Claude Code login,
     * the same speech-to-text service the CLI's own `/voice` mode uses
@@ -76,6 +76,7 @@ import { RunSummaryTracker } from '../run-summary.js';
 import { PlanOrchestrator } from '../plan-orchestrator.js';
 import { OrchestratorLoop } from '../orchestrator-loop.js';
 import { getLifecycleLog } from '../session-lifecycle-log.js';
+import { ensureCodemanHooks } from '../hooks-config.js';
 import { PushSubscriptionStore } from '../push-store.js';
 import webpush from 'web-push';
 import { SseStreamManager } from './sse-stream-manager.js';
@@ -636,6 +637,7 @@ export class WebServer extends EventEmitter {
      getClaudeModeConfig: this.getClaudeModeConfig.bind(this),
      getTerminalHistoryConfig: this.getTerminalHistoryConfig.bind(this),
      getAgentSkillEnabled: this.getAgentSkillEnabled.bind(this),
+      getWorkspaceHooksEnabled: this.getWorkspaceHooksEnabled.bind(this),
      getClaudeVoiceEnabled: this.getClaudeVoiceEnabled.bind(this),
      getDefaultClaudeMdPath: this.getDefaultClaudeMdPath.bind(this),
      getLightState: this.getLightState.bind(this),
@@ -1710,6 +1712,16 @@ export class WebServer extends EventEmitter {
    return settings.agentSkillEnabled === true;
  }

+  // Whether a Claude session installs Codeman's hooks block into its workspace
+  // (synced `workspaceHooksEnabled` setting). Default ON — an absent key means a
+  // user who has never seen this setting, and OFF for them would mean no tab
+  // alerts, no Approvals Inbox and no respawn idle signals in every workspace
+  // Codeman did not scaffold itself.
+  private async getWorkspaceHooksEnabled(): Promise<boolean> {
+    const settings = await this.readSettings();
+    return settings.workspaceHooksEnabled !== false;
+  }
+
  // Whether browser dictation may use this machine's Claude Code credentials
  // (synced `claudeVoiceEnabled` setting, default OFF; docs/claude-voice-plan.md).
  // OFF by default because turning it on spends the operator's Claude subscription
@@ -2819,6 +2831,13 @@ export class WebServer extends EventEmitter {
          }
        }

+        // Sessions recovered from a previous run predate the create-path hook
+        // install, and these are long-lived: by the time a server restart comes
+        // round a session may be days old and has been running hook-blind the
+        // whole time. Claude Code re-reads settings.local.json, so writing the
+        // block now arms the RUNNING CLI, no session restart needed.
+        await this.ensureHooksForRecoveredWorkspaces();
+
        // Start stats collection for mux sessions
        this.mux.startStatsCollection(STATS_COLLECTION_INTERVAL_MS);
      }
@@ -2845,6 +2864,37 @@ export class WebServer extends EventEmitter {
    }
  }

+  /**
+   * Install Codeman's hooks into the workspaces of the sessions just recovered.
+   *
+   * Deduped by workspace, because sessions in one repo share a single
+   * `.claude/settings.local.json` and the write is otherwise repeated per tab.
+   * Claude mode only (nothing else reads `.claude` hooks), never for remote
+   * sessions (their `workingDir` is a path on ANOTHER host, so writing it here
+   * would scaffold a stray directory locally), and never for a docker case that
+   * opted out of hooks.
+   *
+   * Failures are swallowed per workspace: `ensureCodemanHooks` already refuses
+   * unsafe targets with a warning, and a workspace we cannot write to must not
+   * stop the rest of recovery.
+   *
+   * Skipped entirely when `workspaceHooksEnabled` is OFF: that setting exists so a
+   * user can keep Codeman out of their repos, and a boot-time sweep is the last
+   * place that should ignore it.
+   */
+  private async ensureHooksForRecoveredWorkspaces(): Promise<void> {
+    if (!(await this.getWorkspaceHooksEnabled())) return;
+    const workspaces = new Set<string>();
+    for (const session of this.sessions.values()) {
+      if (session.mode !== 'claude' || session.remote) continue;
+      if (session.docker && !session.docker.hooksEnabled) continue;
+      if (session.workingDir) workspaces.add(session.workingDir);
+    }
+    for (const workspace of workspaces) {
+      await ensureCodemanHooks(workspace).catch(() => {});
+    }
+  }
+
  /**
   * COD-108 — handle a `remoteSessionDropped` emit from the watcher: reattach
   * the dropped remote session and report the outcome back to the watcher so it
@@ -19,6 +19,7 @@ export function createMockRouteContext(options?: {
  sessionId?: string;
  agentSkillEnabled?: boolean;
  claudeVoiceEnabled?: boolean;
+  workspaceHooksEnabled?: boolean;
 }) {
  const sessionId = options?.sessionId ?? 'test-session-1';
  const session = createMockSession(sessionId);
@@ -96,6 +97,9 @@ export function createMockRouteContext(options?: {
    getAgentSkillEnabled: vi.fn(async () => options?.agentSkillEnabled ?? false),
    // Default OFF mirrors the shipped setting: no test opens a voice relay by accident.
    getClaudeVoiceEnabled: vi.fn(async () => options?.claudeVoiceEnabled ?? false),
+    // Default ON mirrors the shipped setting, so a route test sees what a user sees.
+    // Writes land in the test's temp working dir, never in a real repo.
+    getWorkspaceHooksEnabled: vi.fn(async () => options?.workspaceHooksEnabled ?? true),
    getDefaultClaudeMdPath: vi.fn(async () => undefined),
    getLightState: vi.fn(() => ({ sessions: [], status: 'ok' })),
    getLightSessionsState: vi.fn(() => {
@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Hooks are installed into the workspace a claude session starts in.
+ *
+ * Regression cover for the 2026-08-15 report: a session in a LINKED case (the user's
+ * own repo, where most sessions live) ran with no hooks block at all, because
+ * `writeHooksConfig` only fires when Codeman CREATES a case directory and the old
+ * self-heal call deliberately never ADDED one. The visible symptom was an
+ * AskUserQuestion dialog blocking the pane while the tab and the phone overview both
+ * showed a calm `idle` — no hook event, so no pending-hook state, so no alert.
+ *
+ * Asserts bytes on disk (the real `ensureCodemanHooks`), not a spy call.
+ * Uses app.inject(), so no real HTTP port is needed.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { mkdtemp, rm, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createMockRouteContext } from '../mocks/index.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+import { generateHooksConfig } from '../../src/hooks-config.js';
+import { getDataDir } from '../../src/config/instance.js';
+
+interface HooksFile {
+  hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<{ command?: string }> }>>;
+  permissions?: unknown;
+  model?: unknown;
+}
+
+/**
+ * A faithful PRE-SECRET Codeman hooks block (what a case created before COD-54
+ * contains): it targets /api/hook-event, so it is recognisably ours, but carries
+ * no X-Codeman-Hook-Secret header and no -k. Used to prove the self-heal still
+ * runs with the setting OFF.
+ */
+function staleCodemanHooks() {
+  return {
+    Stop: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command:
+              "HOOK_DATA=$(cat 2>/dev/null || echo '{}'); " +
+              'printf \'{"event":"stop","sessionId":"%s","data":%s}\' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ' +
+              'curl -s -X POST "$CODEMAN_API_URL/api/hook-event" -H \'Content-Type: application/json\' --data @- 2>/dev/null || true',
+            timeout: 5,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe('POST /api/sessions workspace hooks', () => {
+  let app: FastifyInstance;
+  let workingDir: string;
+
+  const settingsPath = () => join(workingDir, '.claude', 'settings.local.json');
+  const readSettings = async (): Promise<HooksFile> => JSON.parse(await readFile(settingsPath(), 'utf-8'));
+
+  const createSession = (payload: Record<string, unknown>) =>
+    app.inject({ method: 'POST', url: '/api/sessions', payload });
+
+  /** Rebuild the app with the `workspaceHooksEnabled` gate in a given position. */
+  const useApp = async (workspaceHooksEnabled: boolean) => {
+    await app?.close();
+    app = Fastify({ logger: false });
+    await app.register(fastifyCookie);
+    registerSessionRoutes(app, createMockRouteContext({ workspaceHooksEnabled }));
+    installRouteErrorHandler(app);
+    await app.ready();
+  };
+
+  beforeEach(async () => {
+    workingDir = await mkdtemp(join(tmpdir(), 'codeman-workspace-hooks-'));
+    app = Fastify({ logger: false });
+    await app.register(fastifyCookie);
+    registerSessionRoutes(app, createMockRouteContext());
+    installRouteErrorHandler(app);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    await rm(workingDir, { recursive: true, force: true });
+  });
+
+  it('installs hooks in a workspace that has none (the linked-case bug)', async () => {
+    const res = await createSession({ name: 'hooks-fresh', mode: 'claude', workingDir });
+    expect(res.statusCode).toBe(200);
+
+    const settings = await readSettings();
+    const matchers = (settings.hooks?.Notification ?? []).map((entry) => entry.matcher);
+    // permission_prompt is the one an AskUserQuestion dialog raises; the
+    // elicitation pair is what CLOSES the resulting Approvals Inbox item.
+    expect(matchers).toEqual(
+      expect.arrayContaining([
+        'idle_prompt',
+        'permission_prompt',
+        'elicitation_dialog',
+        'elicitation_complete',
+        'elicitation_response',
+      ])
+    );
+    expect(settings.hooks?.Stop?.length).toBeGreaterThan(0);
+
+    const serialized = JSON.stringify(settings.hooks);
+    // The two shapes that have historically shipped dead hooks: no secret header
+    // (401 once the gate went unconditional) and no -k (exit 60 on HTTPS installs).
+    expect(serialized).toContain('X-Codeman-Hook-Secret');
+    expect(serialized).toContain('curl -sk -X POST');
+  });
+
+  it('merges into a user-owned settings file without disturbing it', async () => {
+    await mkdir(join(workingDir, '.claude'), { recursive: true });
+    const userHook = { matcher: 'Write', hooks: [{ type: 'command', command: './my-formatter.sh' }] };
+    await writeFile(
+      settingsPath(),
+      JSON.stringify({ model: 'opus[1m]', permissions: { allow: ['Read'] }, hooks: { PostToolUse: [userHook] } })
+    );
+
+    expect((await createSession({ name: 'hooks-merge', mode: 'claude', workingDir })).statusCode).toBe(200);
+
+    const settings = await readSettings();
+    expect(settings.model).toBe('opus[1m]');
+    expect(settings.permissions).toEqual({ allow: ['Read'] });
+    expect(JSON.stringify(settings.hooks)).toContain('./my-formatter.sh');
+    expect((settings.hooks?.Notification ?? []).length).toBeGreaterThan(0);
+  });
+
+  it('leaves a non-claude session alone (only claude reads .claude hooks)', async () => {
+    expect((await createSession({ name: 'hooks-shell', mode: 'shell', workingDir })).statusCode).toBe(200);
+    expect(existsSync(settingsPath())).toBe(false);
+  });
+
+  it('leaves the server cwd alone when workingDir is omitted', async () => {
+    // workingDir falls back to process.cwd(), which is $HOME under installer-created
+    // services — hooks must not materialize in ~/.claude/settings.local.json.
+    const cwdSettings = join(process.cwd(), '.claude', 'settings.local.json');
+    const before = existsSync(cwdSettings) ? await readFile(cwdSettings, 'utf-8') : null;
+
+    expect((await createSession({ name: 'hooks-no-dir', mode: 'claude' })).statusCode).toBe(200);
+
+    const after = existsSync(cwdSettings) ? await readFile(cwdSettings, 'utf-8') : null;
+    expect(after).toBe(before);
+  });
+
+  it('never writes hooks for a remote attach (workingDir is a user@host pseudo-path)', async () => {
+    // A claude-mode attachRemoteSession create overwrites workingDir with
+    // `user@host:session` — locally a RELATIVE path, so a mkdir would create it
+    // as a junk directory under the server cwd.
+    await mkdir(getDataDir(), { recursive: true });
+    await writeFile(
+      join(getDataDir(), 'remote-hosts.json'),
+      JSON.stringify([{ id: 'h1', label: 'box', host: '10.0.0.5', username: 'dev' }])
+    );
+
+    const res = await createSession({
+      name: 'hooks-remote',
+      mode: 'claude',
+      attachRemoteSession: { hostId: 'h1', remoteSessionName: 'codeman-ssh-abc123' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(existsSync(join(process.cwd(), 'dev@10.0.0.5:codeman-ssh-abc123'))).toBe(false);
+  });
+
+  it('leaves a malformed settings file untouched rather than replacing it', async () => {
+    await mkdir(join(workingDir, '.claude'), { recursive: true });
+    await writeFile(settingsPath(), '{ not json');
+
+    expect((await createSession({ name: 'hooks-malformed', mode: 'claude', workingDir })).statusCode).toBe(200);
+    expect(await readFile(settingsPath(), 'utf-8')).toBe('{ not json');
+  });
+
+  it('adds nothing when workspaceHooksEnabled is OFF', async () => {
+    await useApp(false);
+
+    expect((await createSession({ name: 'hooks-off', mode: 'claude', workingDir })).statusCode).toBe(200);
+    expect(existsSync(settingsPath())).toBe(false);
+  });
+
+  it('still heals a stale Codeman block when workspaceHooksEnabled is OFF', async () => {
+    // The setting turns off ADDING hooks, not the COD-91 self-heal: a pre-secret
+    // block 401s against the now-unconditional hook-secret gate, so a workspace that
+    // already opted in must not be left with hooks that silently fail.
+    await useApp(false);
+    await mkdir(join(workingDir, '.claude'), { recursive: true });
+    await writeFile(settingsPath(), JSON.stringify({ model: 'opus', hooks: staleCodemanHooks() }));
+
+    expect((await createSession({ name: 'hooks-off-stale', mode: 'claude', workingDir })).statusCode).toBe(200);
+
+    const settings = await readSettings();
+    expect(settings.model).toBe('opus');
+    expect(JSON.stringify(settings.hooks)).toContain('X-Codeman-Hook-Secret');
+  });
+
+  it('writes the hooks the generator produces, so the two cannot drift', async () => {
+    expect((await createSession({ name: 'hooks-parity', mode: 'claude', workingDir })).statusCode).toBe(200);
+
+    const written = (await readSettings()).hooks ?? {};
+    expect(Object.keys(written).sort()).toEqual(Object.keys(generateHooksConfig().hooks).sort());
+  });
+});
@@ -24,6 +24,7 @@ function loadLineageHelper() {
        DIP_MIN_PX: number;
        DIP_MAX_PX: number;
        SIBLING_STEP_PX: number;
+        COLORS: string[];
      };
    }
  ).CodemanLineage;
@@ -61,8 +62,9 @@ describe('lineage line geometry', () => {
    const near = helper.computePath({ parent: tab(0), child: tab(140), strip: STRIP })!;
    const far = helper.computePath({ parent: tab(0), child: tab(1000), strip: STRIP })!;

-    const nearDip = controlYs(near.d)[0] - 34;
-    const farDip = controlYs(far.d)[0] - 34;
+    // The dip hangs from the STRIP's bottom edge (40), not the tab bottoms.
+    const nearDip = controlYs(near.d)[0] - 40;
+    const farDip = controlYs(far.d)[0] - 40;
    expect(farDip).toBeGreaterThan(nearDip);
    expect(nearDip).toBeGreaterThanOrEqual(helper.DIP_MIN_PX);
    expect(farDip).toBeLessThanOrEqual(helper.DIP_MAX_PX);
@@ -80,15 +82,48 @@ describe('lineage line geometry', () => {
  it('keeps bending at strip-wide spans instead of flattening into a straight line', () => {
    const helper = loadLineageHelper();
    // A worker the agent skill starts is appended to the END of the strip, so this
-    // is the span the feature is actually used at. The first shipped clamp (44px)
-    // turned it into a flat thread across the terminal.
+    // is the span the feature is actually used at. The corridor has failed in BOTH
+    // directions: the first 44px clamp read as a flat thread here (#285), and the
+    // 104px clamp that replaced it bowed deep into the terminal (2026-08-15), so this
+    // pins the cap exactly rather than just a floor.
    const wide = helper.computePath({ parent: tab(0), child: tab(1300), strip: { ...STRIP, width: 1500 } })!;
    const near = helper.computePath({ parent: tab(0), child: tab(140), strip: STRIP })!;

-    const wideDip = controlYs(wide.d)[0] - 34;
-    const nearDip = controlYs(near.d)[0] - 34;
+    const wideDip = controlYs(wide.d)[0] - 40; // from the strip's bottom edge
+    const nearDip = controlYs(near.d)[0] - 40;
    expect(wideDip).toBeGreaterThan(nearDip * 2);
-    expect(wideDip).toBeGreaterThanOrEqual(80);
+    expect(wideDip).toBe(helper.DIP_MAX_PX);
+    expect(helper.DIP_MAX_PX).toBe(64);
+  });
+
+  it('hangs the dip from the STRIP bottom, so no per-row offset ever stacks on it', () => {
+    const helper = loadLineageHelper();
+    const twoRowStrip = { left: 0, top: 0, width: 1200, height: 84 }; // rows at y 4-34 and 48-78
+    // A wrapped pair (row 1 → row 2) and a same-row pair on ROW 1 of the same strip.
+    const wrapped = helper.computePath({ parent: tab(0), child: tab(400, 48), strip: twoRowStrip })!;
+    const row1Pair = helper.computePath({ parent: tab(0), child: tab(400), strip: twoRowStrip })!;
+
+    // Both brackets clear the ENTIRE strip: the wrapped one does not add the row
+    // offset on top (the 2026-08-15 over-bow), and the row-1 pair does not draw
+    // through row 2's tab labels (the retune's own first-draft regression).
+    for (const geom of [wrapped, row1Pair]) {
+      for (const y of controlYs(geom.d)) {
+        expect(y).toBeGreaterThanOrEqual(84 + helper.DIP_MIN_PX);
+        expect(y).toBeLessThanOrEqual(84 + helper.DIP_MAX_PX + helper.SIBLING_STEP_PX);
+      }
+    }
+  });
+
+  it('exposes a colour palette whose first entry defers to the skin blue', () => {
+    const helper = loadLineageHelper();
+    const colors = helper.COLORS;
+    expect(Array.isArray(colors)).toBe(true);
+    // '' = no override: session-lineage.js sets no inline --lineage-color and the
+    // CSS falls back to the skin-tuned --session-blue, so a lone arc stays blue.
+    expect(colors[0]).toBe('');
+    expect(colors.length).toBeGreaterThanOrEqual(6);
+    expect(new Set(colors).size).toBe(colors.length);
+    for (const c of colors.slice(1)) expect(c).toMatch(/^#[0-9a-f]{6}$/i);
  });

  it('brackets a wrapped pair BELOW the lower row rather than inside the row gap', () => {
Author	SHA1	Message	Date
Ark0N	82fe3cf684	Merge pull request #305 from Ark0N/docs/skill-hooks-rule docs(skill): hooks are a setting now, not who created the directory	2026-08-16 19:23:17 +02:00
Codeman maintainer	c8f3981b0c	review fixes: 1.19.0 is the real version boundary, and the preamble stamp matches its bytes again endpoints.md named 1.18.x as the version where workspace hooks became a setting, but 1.18.x servers do NOT have this behavior — an agent driving one would falsely conclude its workspace has hooks. The feature ships in 1.19.0. And preamble.sh changed content this PR without bumping its CODEMAN_PREAMBLE stamp, so a cache stamped 1.18.3 would pass the staleness check while holding old bytes; stamp bumped to 1.19.0 in preamble.sh and the SKILL.md heredoc together (byte-identity pin). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-16 19:16:10 +02:00
Codeman maintainer	499d35566b	review fixes: never install workspace hooks for a remote attach or a cwd-fallback create A claude-mode attachRemoteSession create overwrites workingDir with the user@host:session pseudo-path, which is a RELATIVE path locally — the old refresh-only call no-op'd on it, but ensureCodemanHooks mkdirs, so it created a junk local directory. And with workingDir omitted the cwd fallback reaches the hooks write unvalidated; under installer-created services cwd is $HOME, so hooks materialized in ~/.claude/settings.local.json. Both guarded at the applyWorkspaceHooks call site; regression tests prove the remote attach leaves no junk dir and the no-workingDir create leaves the server cwd untouched. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-16 19:15:08 +02:00
Codeman maintainer	1c94995290	docs(skill): hooks are a setting now, not who created the directory The workspace-hooks install makes the skill's central hooks rule wrong in the cautious direction. Six places told a worker that a linked case or a raw workingDir has no `stop`/`blocked` and that send-and-wait cannot be trusted there, so an agent would hand-roll output-marker synchronization in exactly the workspaces where `wait:true` now works. Rewritten against the setting rather than directory provenance: - verbs.md §5.1: the where-to-spawn table, the rule paragraph (now naming `workspaceHooksEnabled`, default ON, the add-only merge, and the boot sweep of recovered sessions), and the silent-failure warning. The three cases that stay hook-less regardless are called out: remote SSH sessions, docker cases that opted out, and a workspace Codeman cannot write to. - verbs.md §5.3: the send-and-wait precondition is "the workspace has the hooks block", not "a case Codeman created". - endpoints.md: the Signals-by-mode table is now keyed on the setting, with rows for OFF, for remote/docker-opt-out, and for a session from an older server. The old create-path grep list becomes a "before 1.18.x" note. - SKILL.md §2 + the cost list, recipes.md Flow-1 contrast, messaging.md step 1. "Check, do not assume" is kept and promoted to the load-bearing habit, because the setting is not visible from the call and a session created by an older server that has not restarted still has nothing. The `spawn_worker` hooks grep STAYS: it guards the setting being off, remote sessions, and older servers. Only its diagnostic changes, since "pick an unused name" is no longer the fix. That text lives in both the §0 heredoc and `preamble.sh`, which `test/agent-skill.test.ts` pins byte-identical, so both are patched with the same bytes. Docs only, no behavior change. 23 skill tests green, full test:ci 5109 passed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-16 07:30:10 +02:00
Codeman maintainer	f485085174	feat: workspaceHooksEnabled setting as the opt-out for workspace hook installs Installing hooks into any workspace a Claude session runs in is the right default, but it takes a decision away from a user who deliberately removed them: nothing on disk distinguishes "removed on purpose" from "never had any", so they would come back on the next session create. Adds the synced workspaceHooksEnabled setting (App Settings -> Agents & CLIs -> Claude), default ON. OFF restores the older behavior exactly: a Codeman hooks block that is already present is still refreshed when stale (COD-91), but one is never added. Every create path routes through one applyWorkspaceHooks() helper so the gate cannot apply to some paths only, and the boot-time recovery sweep honours it too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-16 07:05:10 +02:00
Codeman maintainer	98fa8c00d1	fix: install Codeman hooks into every claude workspace, not just cases Codeman created A session in a linked case (or any pre-existing repo) ran with no hooks block at all: writeHooksConfig only fires when Codeman CREATES the case directory, and refreshStaleCodemanHooks deliberately never adds one. Every hook-driven surface was therefore dead in exactly the place most sessions run: no tab alert or phone-overview NEEDS YOU row when a dialog blocks the pane, no Approvals Inbox item, no push, no definitive stop/idle_prompt for respawn, and no stop/blocked for the agent wait endpoints. Both session-create paths and restoreMuxSessions() now call ensureCodemanHooks(), an add-only merge that keeps a user's own handlers and leaves a malformed settings file untouched. Claude Code re-reads settings.local.json, so a session already running in the workspace starts firing hooks without a restart. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-16 04:46:01 +02:00
Codeman maintainer	869a507482	chore: version packages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-15 07:18:41 +02:00
Codeman maintainer	854bcb99aa	docs: README Community section + CONTRIBUTING guide Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-15 07:18:18 +02:00
Ark0N	9ee6bf113b	Merge pull request #291 from Ark0N/feat/alerts-lineage-popout Skill fast-path hardening, lineage retune + colors, per-tab pop-out, reliable tab alerts	2026-08-15 07:16:34 +02:00
Codeman maintainer	66d4c483c7	docs: tab alert screenshots and README glow gif Captured live from an isolated instance running this branch: a regular active tab beside a yellow waiting-for-input tab and a red needs-decision tab. The gif covers one full 17.5s loop (LCM of the 2.5s red and 3.5s yellow pulse cycles), so it loops cleanly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-15 07:03:06 +02:00
Codeman maintainer	ff13234b3d	review fixes: pin alert-overlay opacity against tab-enter's ::before, guard stripBottom against a non-finite strip.top Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-15 06:49:39 +02:00
Codeman maintainer	0af80b417c	feat: skill fast-path hardening, lineage retune + colors, per-tab pop-out, reliable tab alerts - SKILL.md: forbid the standalone preamble check and pre-spawn recon turns (measured: two wasted model turns cost ~12s of a 28s two-worker run; the hardened flow measured 20.2s cold / 12.8s warm end to end) - Lineage lines: dip now hangs from the strip's bottom edge (cap 104 -> 64, no stacked row offsets), fixing the deep bow in wrapped strips and keeping row-1 arcs off row-2 tab labels; per-child color palette (skin blue first, then matrix green, pink, violet, red, turquoise, orange) via an inline --lineage-color custom property - Session Options -> Session: per-TAB pop-out (open-in-window) button override on top of the general showTabDetachButton setting; per-device localStorage map rendered as the tab-show-detach class - Tab alerts: seed the pending-hook state machine from GET /api/approvals regardless of the approvals-inbox setting (reloads used to lose the red tab entirely with the inbox off), clear unconditionally on approval_resolved, and repaint the alert as a steady red/yellow ring + glow + status dot on a ::before overlay so it stays visible on the selected (active) tab until the permission is actually resolved - docs: worker warm-pool design sketch (verified numbers baked in) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-15 06:38:26 +02:00