chore: version packages

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "codeman",
       "source": "./plugins/codeman",
       "description": "Drive Codeman from inside a Claude Code session: spawn worker sessions, prompt them, wait for them, read their answers, clean up. Acts only inside a Codeman-managed session.",
-      "version": "1.41.1",
+      "version": "1.42.0",
       "author": {
         "name": "Ark0N",
         "url": "https://github.com/Ark0N"

CHANGELOG.md

@@ -1,5 +1,40 @@
 # aicodeman
 
+## 1.42.0
+
+### Minor Changes
+
+- 1238316: ### Thanks
+  - @JDProfresh for five PRs: prompt uploads that take documents (#621, from the plan in #553), a video Codeman cannot take refused before it uploads (#622), a prompt-cache readout kept to the CLIs that report one and a statusline report with many cache-miss causes no longer thrown away (#623), and two fixes for Claude's workspace trust dialog in a brand-new folder: idle waits that hold until the dialog is answered (#634) and a dialog that gets answered every time (#635).
+  - @Randalix for Codex prompts that really get submitted, sent as one bracketed paste and a separate Enter (#628), and for the careful measurements in #627 that found the cause.
+  - @ludovicfourrage, a first-time contributor, for reporting (#629) and fixing (#632) the nested tmux status bar colour that leaked into live output after a history reload.
+  - @opticon454 for three PRs: a one-time "what's new" note after each update (#618), Previous and Next Session as rebindable shortcuts that refuse a chord another action already uses (#617), and a DeepSeek install from CLI management that ends with a DeepSeek you can run (#616).
+
+  **Git worktrees for a case (#625).** Give every agent on a repository its own checkout. Pick a case whose folder is a git repository, choose **Git worktrees…** in the case picker (**Worktrees** on the phone's case sheet), type a name and pick the CLI: Codeman creates `<case>/.claude/worktrees/<name>` on a new branch `worktree-<name>` and opens a session there, in a tab named after the worktree. **Open** starts another session in a worktree you already have. Removing one runs plain `git worktree remove`, never `--force`, so uncommitted work stays where it is, and Close Session can kill the session and remove its worktree in one go. The layout is the one Claude Code's own `claude --worktree` uses, so each sees the other's worktrees. To keep the main checkout clean, Codeman lists the worktrees folder and the files it writes for sessions in the repository's local `.git/info/exclude`; your `.gitignore` is never touched.
+
+  **Codex sessions turn red when Codex asks you something (#624).** Codex's command and edit approvals, its question dialogs and the trust prompt on a new repository are read straight off the screen and raised the way a Claude permission prompt is: red tab, desktop notification, push, webhook, the phone's NEEDS YOU row and an Approvals Inbox card that tells you to answer in the terminal. An agent driving a codex worker can now wait for that with `until=blocked`.
+
+  **Prompt uploads take documents (#621).** Attach, drop or paste a PDF, a Word, PowerPoint or Excel file, a zip, or a text file (txt, md, csv, tsv, json, log, yaml, xml) and its path lands on your prompt, ready to send, like a photo or a video does. Every file is checked against its actual bytes on the way in, so a program renamed to `.pdf` is refused, and text files must be UTF-8. The saved name keeps a readable part of the original: `Q3 report.pdf` is saved as `paste-...-Q3-report.pdf`. The button in the Compose and paste dialogs now says Attach.
+
+  **Previous and Next Session are rebindable (#617).** Previous Session (Alt/Option+[) and the alternate Next Session (Alt/Option+]) are now ordinary rows in App Settings > Shortcuts, so you can rebind or switch them off like everything else. Capturing a chord another action already uses is refused with a message naming that action (Alt+1 to 9, Ctrl/Shift+Enter and Ctrl/Cmd+V stay reserved), and re-enabling or resetting a shortcut runs the same check. A chord you rebound no longer also types into the terminal: a rebind to Alt+J used to switch tabs and send ESC j to the session too. Built-in defaults like Ctrl+L still reach the CLI.
+
+  **A note after each update (#618).** The first time a browser loads a newer Codeman, a toast lists that release's headline changes, with a **See what's new** button that opens the full release notes. It shows once per version, and a browser that has never opened Codeman before just records the version and stays quiet, so the first note you will see is the one for the release after this one. The headlines are taken from the changelog when the release is cut.
+
+  **Multi-user mode: only admins change server-wide settings.** In multi-user mode any signed-in regular user could rewrite the server's settings (feature switches, run mode, case order, the default model for cron and the orchestrator, the app config), start a self-update, rotate the tunnel QR code, clear stale session state, and sign every user out with Revoke All, admins included. They could also read the Deepgram API key an admin saved. Those writes and operations now answer 403 to a regular user, Revoke All signs them out of their own logins only, and their settings read leaves out the admin's key and case names. In the browser a regular user's per-device settings still save, a change to a server-wide setting shows one notice that only an admin can change it, instead of pretending it was saved, and their own run mode and respawn presets are kept on their device. Single-user mode is unchanged.
+
+  **Fixes.**
+  - **Codex submits long prompts (#628).** Prompts sent through the API, `codeman agent send`, the MCP server, cron or the agent skill go into the pane as one bracketed paste followed by a separate Enter, so Codex no longer leaves them sitting unsent in its composer. A single character (a menu answer like `3` or `y`) is still typed, so numbered dialogs keep picking the option you sent, and a trailing `;` survives, so `find . -exec rm {} \;` arrives whole.
+  - **New Claude sessions in an untrusted folder (#634, #635).** An agent waiting for a fresh session to go idle no longer gets its answer while the workspace trust dialog is still up, so its first prompt can no longer press Enter on the highlighted "No, exit" and kill the session it just started. And the dialog is now answered every time: a screen read that came too soon after the previous one used to be dropped, which now and then left a new session sitting on the dialog. Deleting a session while the dialog is up also stops Codeman reading its dead pane for seconds afterwards.
+  - **Nested tmux colours after a history reload (#632).** Opening a remote or Docker case, or a shell running tmux inside it, no longer hands the nested tmux status bar's green background to whatever the agent prints next.
+  - **The codeman skill with arguments (#642).** The skill works again when Claude Code loads it with arguments ("use codeman to start 5 claude workers"). Claude Code swaps a skill's `$1` and `$2` for words of your request, which broke the pasted helpers; they now use `${1}` and `${2}`, and a cached copy written by the broken version is rewritten on the next run.
+  - **DeepSeek installs ready to run (#616).** Installing the terminal profile finds the `pnpm` next to `dsh` even when the server's own PATH lacks `~/.local/bin`, and the DeepSeek install command adds `pnpm` when the machine has none.
+  - **Unsupported videos refused up front (#622).** An Android `.3gp` or an `.mkv` gets "Unsupported file type" right away, instead of uploading up to a gigabyte and failing at the end.
+  - **Statusline reports (#623).** The prompt-cache readout is stored only for CLIs whose statusline reports one (Claude today), like the model badge, and a Claude report with more than 20 cache-miss causes keeps the first 20 instead of being refused, which used to blank the footer and the plan-usage chip.
+
+  **Fixes applied while landing.** Removing a worktree that is, sits inside or holds a Docker case's workspace is refused before git runs; it would have deleted the folder a container still mounts (#625). Codex's trust prompt also reads as blocked in the variant reached through its "Update available" screen, which ends in "esc back" (#624). The DeepSeek install only adds `pnpm` when none is on PATH, so a machine with a corepack `pnpm` keeps it instead of the whole install failing (#616). Three statements in the upload docs were corrected: only a local agent and a Docker case share the uploads folder (remote sessions are refused), GIFs keep their frames instead of being re-encoded, and a developer note no longer names a release that never shipped (#621). The update note skips the Thanks list and group labels like "Fixes.", still works for a release with no headlines, and is translated for zh-CN (#618).
+
+  **Docs.** The README and its Chinese translation caught up with 1.41.0 and 1.41.1 and show a sharper hero GIF, the Codeman Skill got a wiki page and two GIFs linked from both READMEs, CLAUDE.md was split into the root file, `src/web/CLAUDE.md` and `docs/releasing.md`, the release steps now include the MCP registry publish, and a new note says where video and GIF masters live (not on GitHub).
+
 ## 1.41.1
 
 ### Patch Changes

CLAUDE.md

@@ -52,7 +52,7 @@ Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@chan
 
 When the user says **COM** (`COM` = patch, `COM minor`, `COM major`): **Read [`docs/releasing.md`](docs/releasing.md) and follow every step in order**; never improvise a release from memory. It covers the changeset, `npm run version-packages`, the `**Version**` line below, the branch check and explicit-path commit, deploy, the getcodeman.com badge, watching BOTH CI workflows, the MCP registry publish, and the Discussions announcement.
 
-**Version**: 1.41.1 (must match `package.json`)
+**Version**: 1.42.0 (must match `package.json`)
 
 ## Project Overview
 
@@ -124,7 +124,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Key Patterns
 
-**Input**: `session.writeViaMux()` for programmatic/curl input via tmux `send-keys -l` + `send-keys Enter`, single-line only. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
+**Input**: `session.writeViaMux()` for programmatic/curl input via one tmux bracketed paste (`paste-buffer -p`) + `send-keys Enter`, single-line only. A single character is typed with `send-keys -l` instead, because selection dialogs ignore a pasted digit. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
 
 **Agent wait primitives**: bounded long-polls: `GET /api/sessions/:id/wait`, `GET .../wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST .../input`. Registry `session-wait-registry.ts` (pure), bounds `config/agent-wait.ts`. ⚠️ A timeout is a 200 (`wait.timedOut`). ⚠️ `stop` exists for `claude` and `deepseek` ONLY (rule lives in `hooksAvailableForMode()`), `blocked` also for a CLI declaring `capabilities.workDetect.blockedLine` (codex, read off the screen; `blockedSignalAvailable()`): explicit request elsewhere is a 400. ⚠️ Send-and-wait registers the waiter BEFORE the write; teardown must `notifySignal('exit')` BEFORE `cancelAll()`; hangup abort listens on `reply.raw` (guarded by `writableFinished`), never `req.raw`; liveness comes from `isPaneDead`, never `session.pid`. ⚠️ Signals are edge-triggered with no history: gather fan-outs via send-and-wait or `wait-output` markers. Packaged as the `skills/codeman` skill (`codeman skill install`, plugin marketplace, or injection behind `agentSkillEnabled`, SYNCED, default OFF, into the directory each CLI scans: `capabilities.agentSkillDir`, `.claude/skills` for claude, `.agents/skills` for the others, none for pi): injection is add-only, marker-owned (`applyAgentSkill`), refuses symlinks, and refreshes a marker-owned user-level copy (`refreshUserAgentSkill`). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
 
@@ -138,7 +138,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
-⚠️ **A `❯` sighting is NOT the end of a turn, and neither is silence.** Claude redraws the composer all through a turn, and its working line (`✻ Actualizing… (13m 23s · …)`) is invisible to `SPINNER_PATTERN`, keyword lists and the raw stream. `_confirmIdle()` (session.ts) requires the pane to go quiet AND the SCREEN (`capturePaneText()` + the working-line pattern) to agree; a sustained run of repaints (`session-activity.ts`) marks a turn as started. ⚠️ The composer glyph and working line are per-CLI registry DATA (`capabilities.workDetect`), never Claude constants; a CLI declaring neither falls back to Claude's pair. ⚠️ `workingLine` is config-supplied and runs on the PTY hot path, so it must compile through `compileVersionRegex()` in BOTH the schema refine and `_workingLinePattern()` (ReDoS guard; null, not throw). → [architecture-invariants#idle-detection-composer-glyph-and-working-line](docs/architecture-invariants.md#idle-detection-composer-glyph-and-working-line)
+⚠️ **A `❯` sighting is NOT the end of a turn, and neither is silence.** Claude redraws the composer all through a turn, and its working line (`✻ Actualizing… (13m 23s · …)`) is invisible to `SPINNER_PATTERN`, keyword lists and the raw stream. `_confirmIdle()` (session.ts) requires the pane to go quiet AND the SCREEN (`capturePaneText()` + the working-line pattern) to agree; a sustained run of repaints (`session-activity.ts`) marks a turn as started. ⚠️ The workspace-trust dialog's `❯` (on `No, exit`) arms the check too, so the same capture holds idle off while `isTrustDialogScreen()` matches inside `TRUST_DIALOG_WINDOW_MS`: an agent that waited for idle and prompted the dialog confirmed `No, exit` and killed the pane. ⚠️ The composer glyph and working line are per-CLI registry DATA (`capabilities.workDetect`), never Claude constants; a CLI declaring neither falls back to Claude's pair. ⚠️ `workingLine` is config-supplied and runs on the PTY hot path, so it must compile through `compileVersionRegex()` in BOTH the schema refine and `_workingLinePattern()` (ReDoS guard; null, not throw). → [architecture-invariants#idle-detection-composer-glyph-and-working-line](docs/architecture-invariants.md#idle-detection-composer-glyph-and-working-line)
 
 ⚠️ **A turn that ENDED waiting for its own workers is working, not idle.** Claude closes such a turn with `✻ Waiting for 1 dynamic workflow to finish` (background agents / ultracode) and resumes by itself; `capabilities.workDetect.awaitingLine` makes the idle probe count it as work. ⚠️ Claude never redraws that row, so it stays on screen after the workers finish: test it ONLY as the newest column-0 row above the composer (`isAwaitingWorkers()`), never pane-wide and never on the stream. → [architecture-invariants#idle-detection-composer-glyph-and-working-line](docs/architecture-invariants.md#idle-detection-composer-glyph-and-working-line)
 
@@ -150,7 +150,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Dead-pane respawn resume pin** (`_buildRespawnPaneOptionsWithResumePin()`, session.ts): recovering a dead pane, like a custom-model `restartCli()`, must pin the conversation or claude refuses the reused `--session-id`. The pin takes the first transcript-backed candidate (chain tail, launch seed, own id), never `_claudeSessionId`, adds nothing when none is backed, and is never applied to remote or docker sessions. → [architecture-invariants#dead-pane-respawn-the-resume-pin](docs/architecture-invariants.md#dead-pane-respawn-the-resume-pin)
 
-**Workspace-trust dialog auto-accept** (`session-trust-dialog.ts`, pure): Claude Code's per-directory trust dialog is always answered yes, or the session is stuck. ⚠️ Match the compacted SCREEN (`compactScreenText()`, all whitespace removed), never the stream (tmux sends words joined by cursor-forwards, not spaces). ⚠️ Never answer with a blind `\r` (newer versions highlight "No, exit" first): `trustDialogNextKey()` returns ONE key per re-read frame (arrow, then Enter only once `❯` is on the trust option), and the LAST marked option wins. ⚠️ All three guards must hold: startup window `TRUST_DIALOG_WINDOW_MS` (90s), two-marker match (`isTrustDialogScreen`), attempt cap `TRUST_DIALOG_MAX_ATTEMPTS` (6). ⚠️ Read `capturePaneText()`; only a direct-PTY session falls back to a SHORT buffer tail. ⚠️ The scan must schedule its own next read (`_trustDialogTimer`, cleared in `_clearAllTimers()`), not rely on PTY output. → [architecture-invariants#workspace-trust-dialog-auto-accept](docs/architecture-invariants.md#workspace-trust-dialog-auto-accept)
+**Workspace-trust dialog auto-accept** (`session-trust-dialog.ts`, pure): Claude Code's per-directory trust dialog is always answered yes, or the session is stuck. ⚠️ Match the compacted SCREEN (`compactScreenText()`, all whitespace removed), never the stream (tmux sends words joined by cursor-forwards, not spaces). ⚠️ Never answer with a blind `\r` (newer versions highlight "No, exit" first): `trustDialogNextKey()` returns ONE key per re-read frame (arrow, then Enter only once `❯` is on the trust option), and the LAST marked option wins. ⚠️ All three guards must hold: startup window `TRUST_DIALOG_WINDOW_MS` (90s), two-marker match (`isTrustDialogScreen`), attempt cap `TRUST_DIALOG_MAX_ATTEMPTS` (6). ⚠️ Read `capturePaneText()`; only a direct-PTY session falls back to a SHORT buffer tail. ⚠️ The scan must schedule its own next read (`_trustDialogTimer`, cleared in `_clearAllTimers()`), not rely on PTY output, and a throttled read is DEFERRED onto that timer, never dropped (the dialog's paint is often the pane's last output); a stopped session never scans. → [architecture-invariants#workspace-trust-dialog-auto-accept](docs/architecture-invariants.md#workspace-trust-dialog-auto-accept)
 
 **Process-tree walks are bounded** (`proc-tree.ts`, pure): `collectDescendants(pid, byParent)` is the ONE descendant traversal, fed by one cached `ps -eo pid=,ppid=` snapshot (`refreshProcSnapshot()` in tmux-manager.ts: async, in-flight-shared, and ANY error discards the result rather than caching a truncated `ps`). ⚠️ Never walk a process tree with per-node `pgrep` or unbounded recursion (the unbounded version took a machine down): the walk must terminate on cycles, cap depth (`PROC_WALK_MAX_DEPTH`) and node count (`PROC_WALK_MAX_NODES`), and never spawn anything. ⚠️ Keep it in its own module so the test exercises the shipped code, and report truncation through `onTruncated` naming both caps, never silently. → [architecture-invariants#process-tree-walks-are-bounded](docs/architecture-invariants.md#process-tree-walks-are-bounded)
 
@@ -215,7 +215,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments)
 
-**Prompt uploads** (`POST /api/sessions/:id/paste-image`: clipboard paste, drop, the Compose Attach key and the phone toolbar's Attach button; client wiring in `image-input.js` and `keyboard-accessory.js`): a pick is written to `<workspace>/.codeman-uploads/` and its path lands on the prompt as unsent text. The folder is IN the workspace because that is the only path identical for a local and a container agent, FLAT because `<workspace>/.codeman/` would BE the data dir when the workspace is the home directory, and self-ignoring through a `.gitignore` of `*` written ONCE with `wx` (a file already there is the user's and is never overwritten; the user's own ignore file is never touched). ⚠️ The directory names live ONLY in `paste-image-gc.ts` (`UPLOAD_DIR_NAMES`): the pre-move `.claude-images/` receives nothing but stays readable for one release, so the GC sweep and the delete cleanup (through `uploadDirs()`) and the image watcher's ignore filter (reading the names) cover BOTH; retire the legacy entry there, never by hand elsewhere. ⚠️ `uploadDirs()` is async and probes the workspace BOUNDED first (`probePathKind()`, the #516 rule: an `unknown` path is skipped, never touched; the sweep keeps the stall cap and the delete passes `pastCap`), then returns only REAL directories (lstat, so a planted symlink is never one), none that is or contains `getDataDir()` (one strictly inside it only holds uploads and is listed), and none for a remote session, since both consumers delete; the check is made at list time, and the same-user race after it is accepted. Images are buffered in memory under `MAX_PASTE_IMAGE_BYTES` (50MB) after a client-side canvas re-encode. A VIDEO is never buffered: `?kind=video` streams it to disk under `MAX_PASTE_VIDEO_BYTES` (1GB, env `CODEMAN_MAX_PASTE_VIDEO_BYTES`), judges the container on the first 12 bytes as they arrive (ISO BMFF / QuickTime atom, EBML for webm, Ogg for ogv; a mislabeled body is drained unwritten from there, never parked on disk first) and unlinks on any failure, a dead transfer included. ⚠️ The flag is the ONLY way onto that path and admits video types alone (the registry's `VIDEO_ATTACHMENT_EXTENSIONS`, single-sourced: mp4/webm/mov/m4v/ogv, so an uploaded video is one the file viewer can also play; 3gp/mkv are out, since a phone's camera roll produces neither and neither previews), so an image can never ride the larger cap through memory; without it the route is byte-identical to the image-only version. Busboy takes its size limit before the part is seen, which is why the choice rides the URL and not the file. ⚠️ A video draws on its OWN per-(IP, session) rate bucket (`consumeVideoToken`, 3/min) beside the image bucket (`consumePasteToken`, 30/min): at 1GB each, 30/min would be 30GB of disk a minute, so the lower rate bounds it to 3GB; the image path keeps the 30/min bucket and is unchanged without the flag. A remote (SSH) session is refused (400) before any disk touch: its `workingDir` is the remote path, so the file would land on THIS host where the agent cannot read it (Docker is fine, the workspace is bind-mounted at the same absolute path). ⚠️ A live session's workspace can still sit on a network mount that stopped answering, so the route probes it BOUNDED (`probePathKind(session.workingDir, { pastCap: true })`, the #516 rule) before the first disk touch and refuses an `unknown` mount through `describeUnknownPath()` (OPERATION_FAILED), the way session create does, so a mount already unreachable cannot freeze a libuv worker on every upload (a mount that dies after the probe is the same residual race create accepts). ⚠️ The client classifies a pick through ONE helper, `_promptAttachKind()` (MIME type first, then the name's extension, because some Android file managers hand over a File with none); every pick and paste filter (Attach, drop, the tile grid's drop in `tile-grid.js`, the Compose and paste-dialog pickers, the clipboard handlers), the flag and the re-encode gate read it, never `file.type` directly. ⚠️ A pick that lands while the tile grid owns the terminal goes to the PTY, never the main terminal's overlay: that terminal is parked and hidden then, and a tile's Enter cannot flush it (`_tilesOwnTerminal()` in the `_attachFromToolbar` guard). Tests: `test/toolbar-attach.test.ts`, `test/mobile-prompt-composer.test.ts`, `test/paste-image-gc.test.ts`, `test/paste-image-dir-shared.test.ts`, the paste-image block of `test/routes/session-routes.test.ts`. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history)
+**Prompt uploads** (`POST /api/sessions/:id/paste-image`: clipboard paste, drop, the Compose Attach key and the phone toolbar's Attach button; client wiring in `image-input.js` and `keyboard-accessory.js`): a pick is written to `<workspace>/.codeman-uploads/` and its path lands on the prompt as unsent text. The folder is IN the workspace because that is the only path identical for a local and a container agent, FLAT because `<workspace>/.codeman/` would BE the data dir when the workspace is the home directory, and self-ignoring through a `.gitignore` of `*` written ONCE with `wx` (a file already there is the user's and is never overwritten; the user's own ignore file is never touched). ⚠️ The directory names live ONLY in `paste-image-gc.ts` (`UPLOAD_DIR_NAMES`): the pre-move `.claude-images/` receives nothing but stays readable for one release, so the GC sweep and the delete cleanup (through `uploadDirs()`) and the image watcher's ignore filter (reading the names) cover BOTH; retire the legacy entry there, never by hand elsewhere. ⚠️ `uploadDirs()` is async and probes the workspace BOUNDED first (`probePathKind()`, the #516 rule: an `unknown` path is skipped, never touched; the sweep keeps the stall cap and the delete passes `pastCap`), then returns only REAL directories (lstat, so a planted symlink is never one), none that is or contains `getDataDir()` (one strictly inside it only holds uploads and is listed), and none for a remote session, since both consumers delete; the check is made at list time, and the same-user race after it is accepted. Images are buffered in memory under `MAX_PASTE_IMAGE_BYTES` (50MB) after a client-side canvas re-encode; a DOCUMENT (pdf, docx, pptx, xlsx, zip and the text family txt/md/csv/tsv/json/log/yaml/yml/xml; the curated `ALLOWED_DOCUMENT_EXTS`, never `SUPPORTED_ATTACHMENT_EXTENSIONS` or `EDITABLE_EXTENSIONS`, which carry sh/py/js/html) is admitted by its name's extension alone, buffered like an image, judged on its bytes by the same fail-closed `imageMagicMatchesExt` (`%PDF-`, `PK\x03\x04` for the OOXML trio and zip, UTF-8 without a NUL byte for text: a SIGNATURE or ENCODING check, never a structure or content check, so generic zip bytes pass as `.docx` and a script renamed `.txt` is text; the sh/py/js/html exclusion is a SCOPE choice by extension, keeping the server from storing what it would serve or run, not a content filter: the agent can already write any of those) and saved as `paste-<ts>-<hex>-<stem><ext>` with a sanitized stem (`[A-Za-z0-9._-]`, 40 chars, a wholly non-ASCII name leaves no stem; the `paste-` prefix is what the GC matches). A VIDEO is never buffered: `?kind=video` streams it to disk under `MAX_PASTE_VIDEO_BYTES` (1GB, env `CODEMAN_MAX_PASTE_VIDEO_BYTES`), judges the container on the first 12 bytes as they arrive (ISO BMFF / QuickTime atom, EBML for webm, Ogg for ogv; a mislabeled body is drained unwritten from there, never parked on disk first) and unlinks on any failure, a dead transfer included. ⚠️ The flag is the ONLY way onto that path and admits video types alone (the registry's `VIDEO_ATTACHMENT_EXTENSIONS`, single-sourced: mp4/webm/mov/m4v/ogv, so an uploaded video is one the file viewer can also play; 3gp/mkv are out, since a phone's camera roll produces neither and neither previews), so an image can never ride the larger cap through memory; without it the route is byte-identical to the image-only version. Busboy takes its size limit before the part is seen, which is why the choice rides the URL and not the file. ⚠️ A video draws on its OWN per-(IP, session) rate bucket (`consumeVideoToken`, 3/min) beside the image bucket (`consumePasteToken`, 30/min): at 1GB each, 30/min would be 30GB of disk a minute, so the lower rate bounds it to 3GB; the image path keeps the 30/min bucket and is unchanged without the flag. A remote (SSH) session is refused (400) before any disk touch: its `workingDir` is the remote path, so the file would land on THIS host where the agent cannot read it (Docker is fine, the workspace is bind-mounted at the same absolute path). ⚠️ A live session's workspace can still sit on a network mount that stopped answering, so the route probes it BOUNDED (`probePathKind(session.workingDir, { pastCap: true })`, the #516 rule) before the first disk touch and refuses an `unknown` mount through `describeUnknownPath()` (OPERATION_FAILED), the way session create does, so a mount already unreachable cannot freeze a libuv worker on every upload (a mount that dies after the probe is the same residual race create accepts). ⚠️ Dispatch mirrors the client: an `image/*` MIME takes the IMAGE path whatever the name says (a GIF named `animation.txt` stays a GIF), a document extension takes the document branch, and anything else takes the image path exactly as before, where the HEIC sniff still recovers a HEIC under a generic name; a foreign extension with no image MIME gets its `Unsupported file type` 400 only AFTER that sLine truncated
 
 **File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND `_linkifyFilePaths()`, a fresh instance per call (`lastIndex`). Both call `findFilePathLinks()`, which adds `~/`, relative and folder paths without overlapping a rooted match or a URL; a relative path resolves against `workingDir` (`resolveLinkedFilePath`), `~/` only server-side on the session's host (attachment route), and `terminalPathLine()` joins a path a program hard-wrapped short of the edge. ⚠️ A folder link opens the **folder grid**: `POST /api/sessions/:id/folders` guards + GRANTS the folder (`folder-listing.ts`, own registry, never the 200-capped attachment registry), files come by bare name via `…/folders/:folderId/files/:name/*` through `resolveServableAttachmentPath` plus the same extension/regular-file gate on the symlink's resolved target, so no browser request carries a path; `~/` is refused in a Docker case (the container's home is not this host's). The chat linkifier walks TEXT NODES with DOM APIs, never rebuilds sanitized markup as a string. ⚠️ An out-of-workspace path goes through the ATTACHMENT routes (`POST /api/sessions/:id/attachments` with `notify: false`), never by widening `file-content`/`file-raw` or `file-stream-manager`'s `tail -f` allowlist. ⚠️ `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (never a second list), and widening READ must never widen RUN: `html`/`htm`/`svg` stay download-only, other text is inert `text/plain`+`nosniff`. ⚠️ The ONE place HTML renders is `/html-view/<cap>/...` (`html-view-routes.ts`, `html-view-capabilities.ts`): `POST /api/sessions/:id/html-view` mints a capability for the file's own directory, every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin` (opaque origin even as a top-level tab, so the page can never read Codeman or drive its API) and with NO fetch directive (open network, owner decision 2026-10-13: never restrict it or add `allow-same-origin` without the owner), and only non-dot, asset-allowlisted files under that directory are served (GET/HEAD only; capabilities revoked with the web-tab ones on logout). That tree is served recursively, so minting is refused for a hidden directory or a broad root (`isBroadHtmlViewRoot`); the preview renders by default and the **Page** pill (or a refused mint) falls through to the source view and its Edit button. Never serve HTML same-origin anywhere else. Tests: `test/routes/html-view-routes.test.ts`. Media extensions are single-sourced in `attachment-registry.ts`. ⚠️ **XLSX previews parse in the BROWSER**, never on the server; the admission limits that keep a hostile workbook from freezing the worker live in `src/web/CLAUDE.md` (Spreadsheet preview). → [architecture-invariants#file-path-links-terminal--response-viewer](docs/architecture-invariants.md#file-path-links-terminal--response-viewer)
 
@@ -233,11 +233,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Clone a repository as a case** (issue #236, Add Case → **Clone Repo**): `POST /api/cases/clone` clones synchronously into the caller's case space (bounded by `GIT_CLONE_TIMEOUT_MS`, no job store); `POST /api/cases/clone-preflight` checks anonymous cloneability and lists refs. Core in `src/git-clone.ts`. ⚠️ **The URL is a code-execution surface**: refuse every `::` form and a leading `-`, spawn only argv arrays with `--` before operands. ⚠️ Stay non-interactive (`gitNonInteractiveEnv()`) or the open request hangs; never collect credentials, refuse `user:password@` URLs. ⚠️ Timeout kills the process GROUP, remove the destination only if this attempt created it, and repo contents win over scaffolding (existing `CLAUDE.md` kept, hooks merged, repo `.claude/settings*` warned about). → [architecture-invariants#clone-a-repository-as-a-case](docs/architecture-invariants.md#clone-a-repository-as-a-case)
 
+**Git worktrees of a case** (case picker → **Git worktrees…**; `src/git-worktrees.ts`, `routes/worktree-routes.ts`): a local repository case keeps worktrees at `<repo>/.claude/worktrees/<name>` on `worktree-<name>`, Claude Code's own `--worktree` layout. ⚠️ Only that managed path is ever created or removed, every component `lstat`ed and realpath-checked (a symlinked `.claude` is refused). ⚠️ git never runs for a Docker or remote case, nor at or inside a Docker workspace (`worktree add` runs hooks and filters on the host). ⚠️ Remove is `git worktree remove` WITHOUT `--force`, refused while a live session is inside; branch delete is `-d`, never `-D`. ⚠️ Sessions start through the existing create paths (quick-start `worktree`, or `POST /api/sessions` `workingDir`), never a new spawn path. → [architecture-invariants#git-worktrees-of-a-case](docs/architecture-invariants.md#git-worktrees-of-a-case)
+
 **Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. PAST sessions (#261) come from `session-history-index.ts`, a capped snapshot of the unified list filled **outside** the request path (`/api/sessions/unified` publishes it; a stale one is rebuilt fire-and-forget), that indirection is what keeps the no-fs property. ⚠️ The snapshot is stored UNSCOPED with a per-row owner and MUST be re-filtered through `canAccessOwned()` on read; history rows carry `jumpTo.kind:'resume-session'`, since a closed session has no tab to select. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
 
 **Web tabs** (dashboard URLs as tabs): a saved URL renders as a tab beside sessions, **NOT a `SessionMode`**, and is proxied through Codeman's own origin (`/webview/<cap>/...`). ⚠️ The proxy is NOT an API surface: its capability-based auth exemption stays fenced to safe methods and non-route paths (`test/webview-auth-exemption.test.ts`). ⚠️ Iframes omit `allow-same-origin` unless `trusted`, and `Authorization`/`codeman_session` are stripped upstream in both modes. ⚠️ **Egress guard**: link-local and cloud-metadata targets are refused at save time, by a sync hostname check at each connect (IP literals skip DNS), AND on the resolved address (`webview-egress.ts`); use the `undici` package's own `fetch` + `Agent`, never Node's global fetch. ⚠️ Loopback links in agent output auto-open as proxied web tabs (`openLinkThroughWebTabIfLoopback`), but never auto-route `*.localhost` (prompt-injectable DNS). Capabilities are revoked on logout (`revokeOwner`). → [architecture-invariants#web-tabs](docs/architecture-invariants.md#web-tabs), `docs/web-tabs.md`
 
-**Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default): named users with scrypt-hashed passwords in `~/.codeman/users.json`. Gated everywhere by `isMultiUserMode()`; when OFF, behavior is byte-identical to single-user because every scoping helper short-circuits. ⚠️ **Not a security boundary at the agent layer**: every session still runs as the SAME OS account. This separates WORKSPACES; it does not sandbox users (Docker cases are the isolation story). Ownership threads through `Session.owner` and is enforced in `findSessionOrFail`, list endpoints, SSE routing (fail-closed), WS, search, and file-preview. → [architecture-invariants#multi-user-mode](docs/architecture-invariants.md#multi-user-mode), `docs/multi-user-plan.md`
+**Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default): named users with scrypt-hashed passwords in `~/.codeman/users.json`. Gated everywhere by `isMultiUserMode()`; when OFF, behavior is byte-identical to single-user because every scoping helper short-circuits. ⚠️ **Not a security boundary at the agent layer**: every session still runs as the SAME OS account. This separates WORKSPACES; it does not sandbox users (Docker cases are the isolation story). Ownership threads through `Session.owner` and is enforced in `findSessionOrFail`, list endpoints, SSE routing (fail-closed), WS, search, and file-preview. ⚠️ `settings.json` is ONE server-wide file, so every write to it is admin-only (`PUT /api/settings`, `/api/execution/model-config`, `/api/cases/order`, plus `PUT /api/config`: 403 `FORBIDDEN` before parsing), a non-admin's quick-start/Ralph start skips `lastUsedCase`, its GET hides `voiceSettings.apiKey`/`caseOrder`/`lastUsedCase` from a non-admin (`settingsForNonAdmin`), and the browser skips those writes for a non-admin via `_settingsReadOnly()` (settings-ui.js; also true once a write came back 403 `FORBIDDEN`, since `/api/me` can be slow or fail; their run mode and respawn presets stay per-device, `_applyOwnSettings`) (`test/routes/system-routes-settings-admin-only.test.ts`). System ops are admin-only too (`/api/system/update`, `/api/system/span-displays`, `/api/tunnel/qr/regenerate`, `/api/cleanup-state`), and a non-admin's `/api/auth/revoke` revokes only their own logins (`test/routes/system-routes-system-ops-admin-only.test.ts`). → [architecture-invariants#multi-user-mode](docs/architecture-invariants.md#multi-user-mode), `docs/multi-user-plan.md`
 
 **Away digest**: `GET /api/away-digest` aggregates what happened while you were away from the lifecycle log, run-summary events, live sessions, token stats, and recent subagents. Pure aggregator in `web/away-digest.ts`. ⚠️ Returns `{success:true,digest}`, a legacy raw-ish shape consistent with the other raw GET handlers in `system-routes.ts`; frontend and tests read `.digest`. → [architecture-invariants#away-digest](docs/architecture-invariants.md#away-digest)
 
@@ -291,7 +293,7 @@ One module per domain in `src/web/routes/` (plus a barrel; `ls src/web/routes/`
 - **API endpoint**: Types in `src/types/` domain file, route in `src/web/routes/*-routes.ts`. Return the `ApiResponse` envelope (`{ success: true, data }`; errors via `createErrorResponse()` with proper status code). Validate with Zod schemas in `schemas.ts`.
 - **SSE event**: Add to `src/web/sse-events.ts` + `SSE_EVENTS` in `constants.js`, emit via `broadcast()`, handle in `app.js` (`addListener(`)
 - **Session setting**: Add to `SessionState`, include in `session.toState()`, call `persistSessionState()`
-- **App setting**: decide per-device vs synced first. Per-device keys go in the `displayKeys` set in settings-ui.js and must NOT be added to `SettingsUpdateSchema` (it is `.strict()`). ⚠️ Anything in `PUT /api/settings` that acts on a setting (the `toggleService` watcher calls) must resolve from **`merged`** (persisted + incoming), never from the raw request body: a partial PUT omits keys it doesn't intend to change, and `body.x ?? default` turns every omission into "apply the default" and silently resets live services. Pinned by `test/routes/system-routes-settings-partial-put.test.ts`.
+- **App setting**: decide per-device vs synced first. Per-device keys go in the `displayKeys` set in settings-ui.js and must NOT be added to `SettingsUpdateSchema` (it is `.strict()`). ⚠️ Anything in `PUT /api/settings` that acts on a setting (the `toggleService` watcher calls) must resolve from **`merged`** (persisted + incoming), never from the raw request body: a partial PUT omits keys it doesn't intend to change, and `body.x ?? default` turns every omission into "apply the default" and silently resets live services. Pinned by `test/routes/system-routes-settings-partial-put.test.ts`. ⚠️ A synced setting is admin-only to write in multi-user mode (the PUT 403s a non-admin, whose browser does not send it): a new route that writes `settings.json` takes the same `isMultiUserMode() && !requireAdmin(req, reply)` gate.
 - **Hook event**: Add to `HookEventType`, add hook in `hooks-config.ts:generateHooksConfig()`, update `HookEventSchema`
 - **Mobile feature**: Add to relevant singleton, guard with `MobileDetection.isMobile()`. New header buttons must stay off phones (`test/mobile-header-buttons-policy.test.ts`).
 - **New test**: a test that constructs `WebServer` itself binds port 0 (`new WebServer(0, …)`, then `server.boundPort`), and a raw `http`/`net`/Fastify/`ws` server listens on `0` and reads `address().port`; mobile tests get theirs from `createTestServer()` and read `boundPort` too. `test/test-ports-guard.test.ts` refuses a fixed port in either. Route tests use `app.inject()` (no port needed); see `test/routes/_route-test-utils.ts`.

README.md

@@ -274,7 +274,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 ### 4. Talk to the agent
 
 - **Type prompts** straight into the terminal — input is delivered exactly-once even across reconnects (a dropped link never loses or double-sends a prompt).
-- **Paste, drop or attach images and videos** directly into the session. They are saved in a hidden `.codeman-uploads/` folder in the workspace (it ignores itself in git and is swept after 7 days), and the file's path lands on your prompt, unsent.
+- **Paste, drop or attach images, videos and documents** (PDF, Office files, zip and plain text) directly into the session. They are saved in a hidden `.codeman-uploads/` folder in the workspace (it ignores itself in git and is swept after 7 days), and the file's path lands on your prompt, unsent.
 - **Voice input** — `Ctrl+Shift+V` (Deepgram Nova-3, or this machine's Claude Code login with no API key; auto-silence stop).
 - **Attachments** — register external files/docs and preview Office/PDF inline; any file path an agent prints is clickable, in the terminal and in the chat view, including `~/` and relative paths and paths broken across lines. An `.html` report opens as a real page, Markdown opens rendered, and a folder opens as a grid of its files.
 - **When it needs you** — the tab turns yellow (waiting for input) or red (a question is blocking). The **Approvals Inbox** _(opt-in)_ queues every pending prompt across sessions, answerable from the header bell or the phone home screen, and 🧠 **Read My Mind** _(opt-in)_ drafts your next prompt from the case's goals and recent work.
@@ -753,7 +753,7 @@ For AI agents and automation that control Codeman without a browser: an agent th
 
 ### The agent skill (start here)
 
-Everything in this section also ships as an **agent skill**, [`skills/codeman`](skills/codeman/SKILL.md), in the `SKILL.md` format Claude Code, Codex, Gemini CLI, OpenCode, Grok, OMP and most other agent CLIs read. Install it once and you never paste API docs into a prompt again. You ask for what you want in plain English, and the agent already sitting inside a Codeman session loads the recipes and drives the API itself.
+Everything in this section also ships as an **agent skill**, [`skills/codeman`](skills/codeman/SKILL.md), in the `SKILL.md` format Claude Code, Codex, Gemini CLI, OpenCode, Grok, OMP and most other agent CLIs read. Install it once and you never paste API docs into a prompt again. You ask for what you want in plain English, and the agent already sitting inside a Codeman session loads the recipes and drives the API itself. Full guide, with every install route, the recordings and what it will and will not do on its own: [The Codeman Skill](https://github.com/Ark0N/Codeman/wiki/Codeman-Skill).
 
 <p align="center">
   <a href="docs/images/codeman-skill-crt-20261010.png"><img src="docs/images/codeman-skill-crt-20261010.gif" alt="A real codeman skill run: one short prompt typed into Claude Code, the tile grid powering on, then a DeepSeek Harness worker on a local qwen model and a Claude Code worker powering on as new tiles, with lineage lines from the lead to both" width="900"></a>
@@ -783,9 +783,19 @@ That is the entire interface. No curl, no endpoint names, no session ids. These
 | _"Have a claude worker on `refactor-auth` summarize `src/session.ts`, then close it."_     | Spawns, runs the readiness ladder (first-run trust dialog included), send-and-wait, reads the clean transcript answer, deletes. |
 | _"Watch session w4 and tell me if it gets stuck on a permission prompt."_                  | Blocks on the `blocked` signal and surfaces the question to **you**. It never answers another session's prompt itself. |
 
+One short line is enough. Here a Claude Code lead gets `use codeman to start 5 claude workers, one per TODO item`, and five real Claude Code workers power on, shown side by side in the tile grid:
+
+<p align="center">
+  <img src="docs/images/codeman-skill-grid-20261015.gif" alt="A real codeman skill run in the tile grid: the lead Claude Code session powers on as the only tile, the prompt use codeman to start 5 claude workers, one per TODO item is typed, then five Claude Code worker sessions power on as new tiles one after another with the CRT animation, and all six agents work at once" width="900">
+</p>
+
 #### Step 3: nothing
 
-The agent deletes every session it started. Watch the tabs appear and disappear in the dashboard while it works.
+The agent deletes every session it started. Watch the tabs appear and disappear in the dashboard while it works. With eight workers, each one gets its own tab, and a lineage line runs back to the lead that spawned it:
+
+<p align="center">
+  <img src="docs/images/codeman-skill-tabs-20261015.gif" alt="A real codeman skill run in the normal view: the prompt use codeman to start 8 claude workers, one per TODO item is typed, eight worker tabs power on left to right while lineage lines draw from the lead to each one, then clicking a worker tab shows a live Claude Code worker receiving its task" width="900">
+</p>
 
 #### A real run, start to finish
 

README.zh-CN.md

@@ -276,7 +276,7 @@ codeman service install           # systemd/launchd 服务：重启后自动回
 ### 4. 与智能体对话
 
 - **直接在终端输入提示** —— 即使跨越重连，输入也是精确一次送达（连接中断绝不会丢失或重复发送提示）。
-- **粘贴、拖放或附加图片和视频**，直接进入会话。它们保存在工作区里一个隐藏的 `.codeman-uploads/` 文件夹中（它在 git 里会忽略自己，7 天后被清理），文件路径会落在你的提示里，但不会自动发送。
+- **粘贴、拖放或附加图片、视频和文档**（PDF、Office 文件、zip 和纯文本），直接进入会话。它们保存在工作区里一个隐藏的 `.codeman-uploads/` 文件夹中（它在 git 里会忽略自己，7 天后被清理），文件路径会落在你的提示里，但不会自动发送。
 - **语音输入** —— `Ctrl+Shift+V`（Deepgram Nova-3，或者直接用这台机器的 Claude Code 登录、不需要任何 API key；自动静音停止）。
 - **附件** —— 注册外部文件/文档，并内联预览 Office/PDF；智能体打印出的任何文件路径都可以点击，终端里和对话视图里都行，包括 `~/` 路径、相对路径和被折成多行的路径。`.html` 报告会以真实网页打开，Markdown 会渲染后打开，文件夹则以其文件的网格打开。
 - **需要你的时候** —— 标签会变黄（等待输入）或变红（有个问题挡住了它）。**审批收件箱（Approvals Inbox）**（可选启用）把所有会话里等着你的提示排成一个队列，可以从页头的铃铛或手机首页直接作答；🧠 **Read My Mind**（可选启用）会根据这个 case 的目标和最近的工作替你起草下一条提示。
@@ -755,7 +755,7 @@ Web UI 仍是主要界面；完整指南见 **[docs/tui.md](docs/tui.md)**（英
 
 ### 智能体技能（从这里开始）
 
-这一节的所有内容也打包成了一个**智能体技能**，位于 [`skills/codeman`](skills/codeman/SKILL.md)，采用 Claude Code、Codex、Gemini CLI、OpenCode、Grok、OMP 以及大多数其他智能体 CLI 都能读取的 `SKILL.md` 格式。装一次，就再也不用把 API 文档粘进提示词。你用大白话说想要什么，已经坐在 Codeman 会话里的智能体会自己加载配方并驱动 API。
+这一节的所有内容也打包成了一个**智能体技能**，位于 [`skills/codeman`](skills/codeman/SKILL.md)，采用 Claude Code、Codex、Gemini CLI、OpenCode、Grok、OMP 以及大多数其他智能体 CLI 都能读取的 `SKILL.md` 格式。装一次，就再也不用把 API 文档粘进提示词。你用大白话说想要什么，已经坐在 Codeman 会话里的智能体会自己加载配方并驱动 API。完整说明（所有安装方式、录屏，以及它会自己做什么、不会做什么）：[The Codeman Skill](https://github.com/Ark0N/Codeman/wiki/Codeman-Skill)（英文）。
 
 <p align="center">
   <a href="docs/images/codeman-skill-crt-20261010.png"><img src="docs/images/codeman-skill-crt-20261010.gif" alt="一次真实的 codeman 技能运行：在 Claude Code 里输入一句简短的提示，平铺网格开机，然后一个跑在本地 qwen 模型上的 DeepSeek Harness 工作会话和一个 Claude Code 工作会话作为新窗格开机，主会话到两者之间画出派生连线" width="900"></a>
@@ -785,9 +785,19 @@ Web UI 仍是主要界面；完整指南见 **[docs/tui.md](docs/tui.md)**（英
 | _「让一个 claude 工作会话在 `refactor-auth` 上总结 `src/session.ts`，然后关掉它。」_  | 拉起、走完就绪阶梯（包括首次运行的信任对话框）、发送并等待、读取干净的 transcript 答案、删除。 |
 | _「盯着会话 w4，如果它卡在权限提示上就告诉我。」_                                      | 阻塞在 `blocked` 信号上，并把问题交给**你**。它绝不会替另一个会话回答提示。                    |
 
+一句简短的话就够了。下面这个 Claude Code 主会话收到 `use codeman to start 5 claude workers, one per TODO item`，五个真实的 Claude Code 工作会话依次开机，并排显示在平铺网格里：
+
+<p align="center">
+  <img src="docs/images/codeman-skill-grid-20261015.gif" alt="一次真实的 codeman 技能运行（平铺网格）：主 Claude Code 会话作为唯一的窗格开机，输入提示 use codeman to start 5 claude workers, one per TODO item，然后五个 Claude Code 工作会话以 CRT 动画依次作为新窗格开机，六个智能体同时工作" width="900">
+</p>
+
 #### 第 3 步：没有了
 
-智能体会删掉它启动的每一个会话。你可以在仪表盘里看着标签出现又消失。
+智能体会删掉它启动的每一个会话。你可以在仪表盘里看着标签出现又消失。起八个工作会话时，每个都有自己的标签，还有一条派生连线连回启动它的主会话：
+
+<p align="center">
+  <img src="docs/images/codeman-skill-tabs-20261015.gif" alt="一次真实的 codeman 技能运行（普通视图）：输入提示 use codeman to start 8 claude workers, one per TODO item，八个工作会话标签从左到右依次开机，主会话到每个标签之间画出派生连线，然后点开一个工作会话标签，看到一个正在接收任务的真实 Claude Code 工作会话" width="900">
+</p>
 
 #### 一次真实的运行，从头到尾
 

config/clis.stock.json

@@ -238,8 +238,8 @@
       },
       "install": {
         "command": {
-          "linux": "npm install -g @deepseek-ai/dsh",
-          "darwin": "npm install -g @deepseek-ai/dsh"
+          "linux": "npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)",
+          "darwin": "npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)"
         },
         "npmPackage": "@deepseek-ai/dsh",
         "docsUrl": "https://github.com/deepseek-ai/deepseek-harness",

config/mcp-registry/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Ark0N/codeman",
   "title": "Codeman",
   "description": "Start, prompt and read AI coding agent sessions (Claude Code, Codex, Gemini CLI and more) in Codeman",
-  "version": "1.41.1",
+  "version": "1.42.0",
   "websiteUrl": "https://getcodeman.com",
   "repository": {
     "url": "https://github.com/Ark0N/Codeman",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "aicodeman",
-      "version": "1.41.1",
+      "version": "1.42.0",
       "transport": {
         "type": "stdio"
       },

config/test-suites.ts

@@ -19,6 +19,7 @@
  * why these are a runnable suite (`npm run test:browser`) rather than skipped.
  */
 export const BROWSER_TEST_GLOBS = [
+  'test/tmux-capture-sgr.browser.test.ts',
   'test/tab-rail-resize.browser.test.ts',
   'test/tab-activation.browser.test.ts',
   'test/tab-layout-editing.browser.test.ts',

docs/api-reference.md

@@ -78,10 +78,15 @@ the HTTP status.
 |-------------|------|---------|
 | `INVALID_INPUT` | 400 | Malformed request / failed validation |
 | `UNAUTHORIZED` | 401 | Authentication required or failed |
+| `FORBIDDEN` | 403 | Signed in, but not allowed (e.g. a non-admin calling an admin-only route in multi-user mode) |
+| `PASSWORD_CHANGE_REQUIRED` | 403 | Multi-user: the user must change their password before anything else |
 | `NOT_FOUND` | 404 | Resource does not exist |
+| `USER_NOT_FOUND` | 404 | Multi-user: no user with that name |
 | `SESSION_BUSY` | 409 | Session is busy |
 | `CONFLICT` | 409 | Conflicts with current state (e.g. already running) |
 | `ALREADY_EXISTS` | 409 | Resource already exists |
+| `USER_EXISTS` | 409 | Multi-user: a user with that name already exists |
+| `LAST_ADMIN` | 409 | Multi-user: refusing to demote, disable or delete the last enabled admin |
 | `OPERATION_FAILED` | 422 | Well-formed but could not be completed |
 | `RATE_LIMITED` | 429 | Too many requests |
 | `INTERNAL_ERROR` | 500 | Unexpected server error |
@@ -252,9 +257,9 @@ the wait promptly instead of burning the caller's whole timeout on something tha
 can no longer happen). On a `claude` worker, prefer an explicit `until=stop,exit`
 once the session is up: the default set's `idle` also resolves on a spinner pause,
 and on a fresh session the **startup** `idle` (emitted when the CLI first comes up)
-can land inside your first wait window and report a turn that never ran. Measured:
-a session parked on the trust dialog emits no *further* `idle`, so it is the
-startup transition, not the dialog, that produces the false success below.
+can land inside your first wait window and report a turn that never ran. That
+startup `idle` is held while Claude's workspace-trust dialog is on screen (inside
+the 90 s startup window), because the dialog's own ❯ is not a composer.
 
 ⚠️ **`exit` means "nothing is running", which includes "not started yet".** The
 server answers from `pid === null` plus a mux-layer pane-death probe, and that
@@ -303,11 +308,11 @@ instead. The same caution applies to the external CLIs.
 Nothing here reports "the agent is ready for a prompt", and no combination of
 `until`/`fresh` synthesizes one. A freshly created session reads as `exit` (above),
 and a `claude` worker in a brand-new case comes up on the CLI's **trust dialog**,
-which contains a ❯ prompt of its own. Send-and-wait posted at that moment types the
-prompt into the dialog, where the `\r` never gets past it, while the session's
-startup `idle` lands inside the wait window: the wait resolves on `idle` in a
-couple of seconds with `timedOut: false`, which looks exactly like a completed
-turn.
+which contains a ❯ of its own. A prompt posted at that moment is typed into the
+dialog, and its `\r` confirms the highlighted `No, exit`: the CLI quits and the
+pane dies, so send-and-wait resolves on `exit`. Codeman holds the session's `idle`
+while the dialog is on screen, so waiting for `idle` before prompting no longer
+clears too early, but that still does not make `idle` a readiness signal.
 
 The reliable sequence is: poll `GET /api/v1/sessions/:id` until `.data.pid` is
 non-null, then `wait-output` for the composer's own marker (`bypass`, the status
@@ -613,6 +618,21 @@ beside the 30 per minute the image path keeps; without the flag the route is
 byte-identical to the image-only version, same 50 MB image cap and same 30/min
 bucket. The response shape is unchanged (`path`, `filename`).
 
+Beyond images, the route also accepts documents a user hands an agent to read,
+admitted by the name's extension (the Content-Type a phone attaches to a `.md`
+or `.csv` is unreliable): the office formats `.pdf`, `.docx`, `.pptx`, `.xlsx`,
+`.zip` and the text family `.txt`, `.md`, `.csv`, `.tsv`, `.json`, `.log`,
+`.yaml`, `.yml`, `.xml`. A document is buffered under the same 50 MB image cap,
+its bytes are checked against the extension (a magic-number signature, or UTF-8
+with no NUL byte for text) and answered 415 on a mismatch, and it is saved under
+a sanitized stem of its name, so `Q3 report.pdf` is findable as
+`paste-<ms>-<hex>-Q3-report.pdf`. A named type that is neither an image nor a
+document (a script, an HTML page, a `.sh`) is refused 400 `Unsupported file
+type`. That refusal is a scope choice, not a security property: `file-raw`
+already serves non-media text inert (`text/plain`, `nosniff`), so this just
+keeps the server from storing what it would serve or an agent could run, and
+html and svg are the ones deliberately kept out.
+
 ## Rendered HTML files
 
 An `.html`/`.htm` file renders as a page in a sandbox, in two steps
@@ -1028,6 +1048,70 @@ Both routes accept two optional query parameters, which the UI sends from its pe
 
 Lists are capped (300 files and 50 commits per repository) while the counts stay exact. A branch with no upstream reports the commits no remote has (`HEAD --not --remotes`); a repository with no remote reports `unpushedCount: 0`, since there is nothing to push to. Concurrent polls of one folder share a single git invocation; `?fresh=1` (what the panel's Refresh button and opening the panel send) skips the short-lived caches, though it still joins a computation already running.
 
+## Git worktrees of a case
+
+A local case whose folder is the top of a git repository can keep **worktrees** at `<case>/.claude/worktrees/<name>`, each on its own branch, so several agents on one repository never share a checkout. This is the layout Claude Code's own `claude --worktree <name>` uses (branch `worktree-<name>`), so either tool finds the other's worktrees. Remote (SSH) and Docker cases are refused with `400 INVALID_INPUT` before git runs, and so is a local case whose folder is at or inside a Docker case workspace: `git worktree add` runs the repository's post-checkout hook and checkout filters on this machine, and a container can write there. A case folder that is not a repository, is a bare repository, or sits below the repository's top level is `400` too. The case resolves the way quick-start resolves it (a linked case is admin-only in multi-user mode, everything else is the caller's own case space; another user's case is `404`), and a case folder on a mount that does not answer is `422 OPERATION_FAILED`, never `404`.
+
+`GET /api/cases/:name/worktrees` lists `git worktree list` for the case's repository:
+
+```json
+{
+  "caseName": "myrepo",
+  "repoRoot": "/home/me/codeman-cases/myrepo",
+  "worktreesDir": "/home/me/codeman-cases/myrepo/.claude/worktrees",
+  "truncated": false,
+  "worktrees": [
+    { "path": "/home/me/codeman-cases/myrepo", "head": "6910cb15…", "branch": "main", "detached": false, "bare": false,
+      "locked": false, "prunable": false, "main": true, "isCase": true, "managed": false, "sessionCount": 0, "sessions": [] },
+    { "path": "/home/me/codeman-cases/myrepo/.claude/worktrees/fix-login", "branch": "worktree-fix-login",
+      "main": false, "isCase": false, "managed": true, "name": "fix-login",
+      "sessionCount": 1, "sessions": [{ "id": "2a568379-…", "name": "w1-fix-login" }] }
+  ]
+}
+```
+
+`managed` is `true` only for `<repoRoot>/.claude/worktrees/<name>`: those are the ones Codeman starts sessions in and removes; any other worktree of the repository is listed for information. `sessionCount` counts live sessions of every owner running in that worktree (a session belongs to the deepest worktree holding its folder), `sessions` lists the ones the caller may see. `lockReason`/`prunableReason` appear when git reports them.
+
+`POST /api/cases/:name/worktrees` with `{ name, branch?, base? }` creates one (`201`, `{ worktree: { name, path, branch, base, head, excludeAdded, warnings } }`):
+
+- `name`: 1 to 64 characters of `A-Z a-z 0-9 . _ -`, starting with a letter or digit, no `..`, not ending in `.` or `.lock`. `400` otherwise.
+- `branch`: the NEW branch, default `worktree-<name>`. Letters, digits, `.`, `_`, `-`, `/`, then `git check-ref-format --branch` must accept it unchanged. An existing branch is `409 ALREADY_EXISTS` (never reset), and so is a name whose folder already exists.
+- `base`: where the branch starts, default `HEAD` (the case's current commit): a branch, tag or commit, resolved before anything is written (`400` when it is not a commit, which includes an empty repository).
+- `excludeAdded` lists the lines appended to the repository's local `info/exclude` (in the real common git dir, never a tracked `.gitignore`) when git did not already ignore them: `/.claude/worktrees/`, so the main checkout does not show the worktrees as untracked, `/.claude/settings.local.json`, the hooks file Codeman writes for every claude session, which would otherwise make `git worktree remove` refuse, and the agent skill copy (`/.claude/skills/codeman/`, `/.agents/skills/codeman/`: every skills folder the CLI registry names) that sessions get while `agentSkillEnabled` is on, for the same reason.
+- A symlinked `.claude` or `.claude/worktrees` directory is refused (`400`): a repository cannot redirect the worktree outside itself.
+
+`DELETE /api/cases/:name/worktrees/:worktree[?deleteBranch=true]` removes a managed worktree with `git worktree remove` **without `--force`**: git refuses a worktree with modified or untracked files (or a locked one), and that refusal is the answer, `409 CONFLICT` with git's own words in `error`. A live session at or inside the worktree is `409` as well. With `deleteBranch=true` the branch is deleted with `git branch -d`, never `-D`, so an unmerged branch is kept: the response is still `200`, with `branchDeleted: false` and git's reason in `branchError`. Response: `{ removed: { name, path, branch, branchDeleted, branchError? } }`. A folder git does not list as a worktree of this repository, or a symlink in its place, is `404`/`400`. A worktree that is, sits inside, or holds a Docker case workspace is `400` too (git would run inside a folder the container writes, and the removal would delete that workspace under it). A managed worktree whose folder is gone (deleted by hand; the list reports it `prunable`) is still removable: git then only drops its record, which is what frees the name for a new worktree. A session never starts in one.
+
+**Starting a session in a worktree** goes through the normal create paths: `POST /api/quick-start` takes `worktree: "<name>"` next to `caseName` and runs the session (and the hooks, the agent skill and `modelOverride`) in the worktree folder; the response adds `worktree` and `workingDir`. It is refused for remote and Docker cases (`400`), for a worktree that is not a registered, managed one (`404`), and for a case that does not exist (`404`: a worktree launch never scaffolds a case). `POST /api/sessions` takes the worktree path as `workingDir` like any other folder.
+
+## Settings
+
+`~/.codeman/settings.json` is one file for the whole server: the synced App Settings (feature switches, the plan-usage collection switch `showPlanUsageLimits`, `runMode`, `respawnPresets`, `tunnelEnabled`, ...), plus `modelConfig`, `caseOrder` and `lastUsedCase`. Reads are open to every signed-in user; in multi-user mode a non-admin reads it without what is the admin's (`voiceSettings.apiKey`, the Deepgram key an admin saved, and the admin's case names in `caseOrder` and `lastUsedCase`). **In multi-user mode every write is admin only:** for a non-admin the routes below answer `403 FORBIDDEN` before the body is even validated, so nothing is written, no watcher is toggled and no tunnel is started. Single-user mode is unaffected.
+
+| Method | Path                          | Body                                 | Notes |
+| ------ | ----------------------------- | ------------------------------------ | ----- |
+| `GET`  | `/api/settings`               | none                                 | The stored settings object. Never writes. For a non-admin in multi-user mode, without `voiceSettings.apiKey`, `caseOrder` and `lastUsedCase`. |
+| `PUT`  | `/api/settings`               | partial settings (strict schema)     | Merged into the stored file; services (watchers, tunnel, tmux history limit) reconcile to the merged result. `403 FORBIDDEN` for a non-admin in multi-user mode. A tunnel enable without `CODEMAN_PASSWORD` is refused separately (`403 OPERATION_FAILED`, resend with `acknowledgeUnauthTunnel: true`). |
+| `GET`  | `/api/execution/model-config` | none                                 | `modelConfig` (cron's and the plan orchestrator's default model). |
+| `PUT`  | `/api/execution/model-config` | `{ defaultModel?, agentTypeOverrides?, ... }` | Replaces `modelConfig`. `403 FORBIDDEN` for a non-admin in multi-user mode. |
+| `PUT`  | `/api/cases/order`            | `{ order: string[] }`                | The one case order every user's `GET /api/cases` is sorted by. `403 FORBIDDEN` for a non-admin in multi-user mode. |
+| `PUT`  | `/api/config`                 | `{ pollIntervalMs?, defaultTimeoutMs?, maxConcurrentSessions?, respawn? }` (strict) | The process-wide app config in `state.json`. `403 FORBIDDEN` for a non-admin in multi-user mode. |
+
+A non-admin's `POST /api/quick-start` and `POST /api/ralph-loop/start` work as before but do not record their case as `lastUsedCase` (a server-wide key).
+
+### System operations
+
+The same multi-user rule covers the operations that act on the whole server. For a non-admin:
+
+| Method | Path                          | Multi-user non-admin |
+| ------ | ----------------------------- | -------------------- |
+| `POST` | `/api/system/update`          | `403 FORBIDDEN` (the update restarts the server under every user) |
+| `POST` | `/api/system/span-displays`   | `403 FORBIDDEN` (opens a window on the server's desktop) |
+| `POST` | `/api/tunnel/qr/regenerate`   | `403 FORBIDDEN` (it clears every user's outstanding QR login code) |
+| `POST` | `/api/cleanup-state`          | `403 FORBIDDEN` (drops every user's stale session records) |
+| `POST` | `/api/auth/revoke`            | Revokes only the caller's own login sessions: the bare form (`{}`) signs them out everywhere, and a `sessionToken` is revoked only when it is theirs. For an admin, and in single-user mode, the bare form still revokes every login session |
+| `GET`  | `/api/tunnel/info`            | `authSessions` lists only the caller's own logins |
+
 ## CLI management
 
 Read and write the CLI registry (`docs/cli-registry.md`). Every **write** route answers `403 FORBIDDEN` while `cliManagementEnabled` is off (the default), and for a non-admin in multi-user mode. A write that would overwrite a `clis.json` which does not parse, or which has group/world permission bits, is refused with `409 CONFLICT` and a message naming the fix; the file is left untouched.

docs/architecture-invariants.md

@@ -119,7 +119,7 @@ Spawn commands are pinned as literal strings in `test/cli-registry-spawn-golden.
 
 ### Input delivery and WS resilience
 
-**Input**: `session.writeViaMux()` for programmatic/curl input — tmux `send-keys -l` (literal) + `send-keys Enter`. Single-line only (fire-and-once). Interactive **browser** input goes through a durable **exactly-once** layer: each frame carries a stable `clientId` + monotonic per-session `seq`, persisted to localStorage until the server ACKs (`{t:'ia',seq}` over WS, or HTTP 2xx), so a dropped link/reconnect can't lose or double-deliver a prompt. A duplicate is ACKed as `{t:'ia',seq,dup:true,last}` so a client whose persisted counter rolled back below the server's watermark can lift itself out instead of typing into a silently dead terminal (`docs/reliable-input-delivery.md`). **WS resilience** (#149): the upgrade URL carries `cid = clientId + ':' + perTabNonce`, and `ws-connection-registry.ts` supersedes only same-TAB reconnects (two tabs on one session coexist; input frames keep the bare `clientId` for seq dedup); reconnects back off exponentially (attempts preserved across `_connectWs`), and the header connection chip renders from a real `_wsState` lifecycle (`connecting`/`connected`/`fallback`/`reconnecting`/`disconnected`).
+**Input**: `session.writeViaMux()` for programmatic/curl input — the text as one tmux bracketed paste (`paste-buffer -p`, so Codex cannot fold the Enter into a paste burst) + `send-keys Enter`. A single character is typed with `send-keys -l` instead (`submitsAsKeys()`): Claude Code's and Codex's selection dialogs ignore a pasted `3`, and the Enter then confirms the highlighted option. Single-line only (fire-and-once). Interactive **browser** input goes through a durable **exactly-once** layer: each frame carries a stable `clientId` + monotonic per-session `seq`, persisted to localStorage until the server ACKs (`{t:'ia',seq}` over WS, or HTTP 2xx), so a dropped link/reconnect can't lose or double-deliver a prompt. A duplicate is ACKed as `{t:'ia',seq,dup:true,last}` so a client whose persisted counter rolled back below the server's watermark can lift itself out instead of typing into a silently dead terminal (`docs/reliable-input-delivery.md`). **WS resilience** (#149): the upgrade URL carries `cid = clientId + ':' + perTabNonce`, and `ws-connection-registry.ts` supersedes only same-TAB reconnects (two tabs on one session coexist; input frames keep the bare `clientId` for seq dedup); reconnects back off exponentially (attempts preserved across `_connectWs`), and the header connection chip renders from a real `_wsState` lifecycle (`connecting`/`connected`/`fallback`/`reconnecting`/`disconnected`).
 
 ### Per-session env overrides: exact-key allowlist and CLAUDE_CONFIG_DIR
 
@@ -270,6 +270,8 @@ Scoping needs no check of its own here: `setPaneExit()` already forces `paneExit
 
 So: `_confirmIdle()` (session.ts) requires the pane to go quiet, and then asks the SCREEN via `capturePaneText()` + `CLAUDE_WORKING_LINE_PATTERN` before believing it; a sustained run of repaints (`session-activity.ts`, pure + unit tested) is what marks a turn as started, with the same screen probe vetoing keystroke echo. Idle now lands ~3-5s after a turn ends instead of 2s into one.
 
+⚠️ **The workspace-trust dialog is not a composer.** Its `❯` sits on `No, exit`, so it arms the confirmation, and the dialog is quiet with no working line, so a fresh case used to be concluded idle about 4 s after launch while the dialog was still up (measured on Claude Code 2.1.294: `GET .../wait?until=idle` answered `idle` at 3.8 s in 6 of 12 fresh-dir launches). An agent that waited for idle and then prompted typed into the dialog, and the prompt's Enter confirmed `No, exit`: the pane died and the wait reported `exit`. `_probePaneWorking()` therefore also records whether its capture shows `isTrustDialogScreen()` (a failed capture keeps the last answer, since it proves nothing), and `_confirmIdle()` re-checks on `PANE_PROBE_RECHECK_MS` instead of concluding while it does, but only inside the auto-accept's own `TRUST_DIALOG_WINDOW_MS`: a later screen that merely quotes the dialog must not hold a session busy. The status is left alone rather than marked working, since nothing is running. Tests: `test/session-trust-dialog.test.ts`.
+
 ⚠️ **The composer glyph and the working line are per-CLI registry DATA** (`capabilities.workDetect`, #385), not Claude constants: claude declares `❯` plus the pattern above, codex declares `›` plus `[Ee]sc to interrupt`, pi declares its composer rule `─` plus the spinner it embeds there, opencode declares its composer bar `┃` plus its 8-cell footer spinner `[⬝■]{8}`, omp declares its input row `╰─` plus the spinner and elapsed time that replace the `π` in its status bar, gemini declares its composer's bottom bar `▀` plus its `(esc to cancel, <n>s)` spinner line, and a CLI that declares neither falls back to Claude's pair, which is what every session used before the registry carried one. Before that, this whole mechanism was gated Claude-mode-only on the reasoning that an external CLI has no `❯`, which was true and still left every Codex session reporting `idle` for its entire life.
 
 ⚠️ `workingLine` is config-supplied (a user `clis.json` can set it) and the compiled pattern runs on the PTY hot path, so it goes through `compileVersionRegex()` in BOTH the schema refine and `_workingLinePattern()`: a nested quantifier there is a ReDoS against the event loop, and the helper returns null rather than throwing so the fallback is structural.
@@ -312,7 +314,7 @@ So: `_confirmIdle()` (session.ts) requires the pane to go quiet, and then asks t
 
 ⚠️ It reads `capturePaneText()` and falls back to a deliberately SHORT tail of the terminal buffer only on a direct-PTY session, which has no pane: that buffer is append-only, so a longer tail would keep re-matching a dialog answered minutes ago.
 
-⚠️ **The scan must schedule its own next read** (`_trustDialogTimer`, cleared in `_clearAllTimers()`): it runs from the PTY `onData` handler, which was enough while one Enter answered the dialog, but the arrow that moves the cursor is the LAST output the pane produces, so a two-keystroke answer waiting on more output parks forever with the cursor sitting on the right option (measured on a live 2.1.252 spawn: cursor moved at 6 s, then nothing).
+⚠️ **The scan must schedule its own next read** (`_trustDialogTimer`, cleared in `_clearAllTimers()`): it runs from the PTY `onData` handler, which was enough while one Enter answered the dialog, but the arrow that moves the cursor is the LAST output the pane produces, so a two-keystroke answer waiting on more output parks forever with the cursor sitting on the right option (measured on a live 2.1.252 spawn: cursor moved at 6 s, then nothing). ⚠️ For the same reason a read the `TRUST_DIALOG_RETRY_MS` throttle refuses is DEFERRED onto that timer, never dropped: the dialog's own paint is often the last output a launching pane produces and lands inside the throttle of the read the blank screen before it triggered, so dropping it left 2 of 12 fresh launches on Claude Code 2.1.294 sitting on the dialog with no keystroke ever sent. And a stopped session never scans: killing the pane produces output, the buffer tail still holds the dialog, and a deleted session went on scanning it and arming the timer for several seconds.
 
 ### Owner tab layouts
 
@@ -460,6 +462,20 @@ Tests: `test/git-clone.test.ts` (pure half exhaustively, plus REAL git against a
 
 Further detail: the synchronous clone request is bounded by `GIT_CLONE_TIMEOUT_MS`.
 
+### Git worktrees of a case
+
+**Git worktrees** (case picker → **Git worktrees…**, the phone case sheet's **Worktrees**, Close Session's **Kill & remove worktree**): a LOCAL case whose folder is the top of a git repository keeps worktrees at `<repo>/.claude/worktrees/<name>` on a new branch (default `worktree-<name>`), so parallel agents each get their own checkout instead of sharing the case folder. That is Claude Code's own `--worktree` layout (measured in 2.1.296: same path, branch `worktree-<name>`, names of `[A-Za-z0-9._-]`, at most 64), and Codeman's names are a strict subset of Claude's. Core in `src/git-worktrees.ts` (pure name/branch gates, `worktree list --porcelain` parsing, exclude text; IO behind an injectable runner); routes in `routes/worktree-routes.ts` (`GET`/`POST /api/cases/:name/worktrees`, `DELETE /api/cases/:name/worktrees/:worktree`).
+
+- ⚠️ **Only `<repo>/.claude/worktrees/<valid-name>` is ever created or removed.** Every component is `lstat`ed (a symlinked `.claude`, `worktrees` or worktree folder is refused, never followed) and the real path must equal the lexical one, so a repository cannot redirect a create or remove outside itself; removal also requires git to list the folder as a worktree of THIS repository. A worktree anywhere else is listed read-only (`managed: false`). A managed worktree whose folder is GONE stays removable (`resolveManagedWorktree({ allowMissing })`, removal only, never a session start: git lists it at exactly the managed path, no component on the way is a symlink, and `git worktree remove` then only drops git's record), since otherwise its name could never be used again.
+- ⚠️ **git never runs for a case at or inside a Docker case workspace** (or whose common git dir is there), and Docker and remote cases are refused with a 400 before any git, the same rule as the git status indicator: `git worktree add` runs the repository's post-checkout hook and checkout filters ON THE HOST. That is acceptable for a local case, where the user's agent already runs code. A managed worktree that is, sits inside, or holds a Docker case workspace (a Docker case linked to the worktree folder) is never removed (400): `git worktree remove` runs a status inside the tree and then deletes it, ignored files included, under the container.
+- ⚠️ **Removal is `git worktree remove` WITHOUT `--force`**, refused (409) while any live session (any owner) runs at or inside the worktree, and git's own refusal (modified or untracked files, a lock) is the answer, shown through `textContent`. The optional branch delete is `git branch -d`, never `-D`: an unmerged branch survives and the response says why (`branchError`).
+- ⚠️ **The main checkout must not see the worktrees.** When `git check-ignore` says they are not ignored, `/.claude/worktrees/` is appended to the repository's LOCAL `<common git dir>/info/exclude` (never a tracked `.gitignore`), and so is `/.claude/settings.local.json`: Codeman writes its hooks there for every claude session, and an untracked copy in a worktree would make `git worktree remove` refuse forever (Claude Code covers that file with the global excludes file, which a machine may not have). The agent skill copy (`<skills dir>/codeman/`, injected while `agentSkillEnabled` is on) gets a line too, for every skills folder the registry names (`capabilities.agentSkillDir`, passed in by the route as data). A symlinked `info` dir or `exclude` file is reported, never written through.
+- **Names are gated before git**: charset and length (Zod and `worktreeNameError()`), then `git check-ref-format --branch`, whose output must EQUAL the input (`--branch` expands `@{-1}`, which the charset gate already refuses). The base is a resolved commit (`rev-parse --verify <base>^{commit}`), passed after `--` with `--no-track`; an existing branch is refused (`-b`, never `-B`, which would reset it). Create and remove are serialized per repository.
+- **Sessions start through the EXISTING create paths**, never a new spawn path: `POST /api/quick-start` with `worktree` (resolved with the same guards; hooks, the agent skill, the model override and the session all target the worktree, and a case that does not exist is a 404, never a scaffold), or `POST /api/sessions` with the worktree as `workingDir` (what the Run button uses for claude and shell). The frontend launches through `run({ worktree })` with a temporary `_runMode` swap, tabs named `w<n>-<worktree>`.
+- The unified session list names a live session's worktree from its folder layout (`worktreeFromPath`), so a codex or shell session gets the worktree pill before (or without) a transcript record.
+
+Tests: `test/git-worktrees.test.ts` (pure half, then REAL git: create, exclude, symlink guards, dirty/live/locked refusals, `branch -d`), `test/routes/worktree-routes.test.ts` (real repository through the routes and quick-start, Docker/remote/ownership refusals), `test/worktree-ui.test.ts`, `test/worktree-modal-i18n.test.ts`.
+
 ### Ultracode and workflow-run visualization
 
 **Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a COMPLETION artifact per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json` (written only at run end); LIVE in-flight runs exist only as transcript dirs at `…/subagents/workflows/wf_<id>/` (journal.jsonl + `agent-*.jsonl`). `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; separate singleton, though it independently reads the same `subagents/workflows/` tree) scans BOTH sources via periodic poll + per-directory chokidar watchers with per-source mtime skip (LRU agentStatCache + journalCache), synthesizing ACTIVE runs (live per-agent tokens/tools/state from transcripts, title/phases from the workflow script) until the completion `wf_*.json` appears and supersedes, and broadcasts SSE `workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is started when **either** `showUltracodeAgents` **or** `ultracodeFloatingWindows` is on (`server.ts` `isWorkflowAgentTrackingEnabled()` returns `(showUltracodeAgents ?? false) || (ultracodeFloatingWindows ?? false)`). Served via `GET /api/workflows` (optional `?minutes=` filter) and `GET /api/workflows/:runId`. Frontend `ultracode-panel.js` renders a docked master-detail view (LEFT: runs + phases; RIGHT: per-agent tokens + tool-calls; click an agent card → its live transcript via client-side `agentId` join). **Additionally**, `ultracode-windows.js` auto-pops a draggable **floating window per active run** (gated on a **DEDICATED** `ultracodeFloatingWindows` toggle, default OFF — independent of the dock panel's `showUltracodeAgents`; see `_ultracodeFloatingEnabled()`), connected by a glowing line to the originating session tab (resolved by `session.claudeSessionId === run.sessionUuid`) — same line idiom as subagent windows, drawn into the shared `#connectionLines` SVG from the tail of `_updateConnectionLinesImmediate`. The window auto-closes ~8s after its run finishes; explicit dismissals are remembered. Clicking an agent card opens an **in-page** connected transcript window (not a browser popup); both run and transcript windows minimize **into** the originating session tab as a merged `ULTRA` badge (🧬 runs / 📄 transcripts) with a restore/dismiss dropdown — minimized runs are skipped by auto-pop. Gesture beta: floating subagent/ultracode windows are pinch-draggable (a `window` grab kind in `entry.ts`). Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
@@ -695,7 +711,7 @@ Matching semantics: a query containing `/` matches the relative path, otherwise
 
 ### Command palette and shortcut registry
 
-**Command palette + shortcut registry** (COD-151/153/157/192, #146): `Ctrl/Cmd/Alt+K` opens the session palette (fuzzy search over live sessions; "Browse all sessions" → the Session Manager modal backed by `GET /api/sessions/unified`); the quick-start case `<select>` is fronted by a searchable picker (`buildCasePickerOptions`/`formatCasePickerLabel` — remote cases render `name @ hostId`). Shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js; overrides persist under `settings.shortcutOverrides` via `saveAppSettingsToStorage`); App Settings → Shortcuts renders capture/disable rows; `Ctrl+?` opens the registry-driven overlay (footer links to the full `#helpModal` reference). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ The global Escape handler (app.js) calls every overlay close method on every Escape, in the capture phase and so before the focused element's own Escape handler, which means a close method with side effects beyond hiding must return early when its overlay is not open: `closeCommandPalette()` and `closeSessionManager()` hand focus back on close (`_restoreOverlayFocus()`, panels-ui.js), and run unconditionally that restore stole focus from split Pane B and from any text field, and turned the inline tab rename's Escape into a commit. ⚠️ `saveAppSettings()` rebuilds settings from the DOM — keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over.
+**Command palette + shortcut registry** (COD-151/153/157/192, #146): `Ctrl/Cmd/Alt+K` opens the session palette (fuzzy search over live sessions; "Browse all sessions" → the Session Manager modal backed by `GET /api/sessions/unified`); the quick-start case `<select>` is fronted by a searchable picker (`buildCasePickerOptions`/`formatCasePickerLabel` — remote cases render `name @ hostId`). Shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js; overrides persist under `settings.shortcutOverrides` via `saveAppSettingsToStorage`); App Settings → Shortcuts renders capture/disable rows; `Ctrl+?` opens the registry-driven overlay (footer links to the full `#helpModal` reference). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ The global Escape handler (app.js) calls every overlay close method on every Escape, in the capture phase and so before the focused element's own Escape handler, which means a close method with side effects beyond hiding must return early when its overlay is not open: `closeCommandPalette()` and `closeSessionManager()` hand focus back on close (`_restoreOverlayFocus()`, panels-ui.js), and run unconditionally that restore stole focus from split Pane B and from any text field, and turned the inline tab rename's Escape into a commit. ⚠️ `saveAppSettings()` rebuilds settings from the DOM — keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. ⚠️ Every xterm key handler (Pane A in terminal-ui.js, Pane B in terminal-tile.js) must call `isUserBoundShortcutEvent(ev)`, which is true only for a chord the user REBOUND a generically dispatched action to: the document capture handler's `preventDefault()` does not stop xterm, so a rebind to e.g. Alt+J would otherwise also type `ESC j` into the PTY. Defaults are deliberately not gated (Ctrl+L must reach the CLI for its redraw), so the gate also skips an entry re-captured onto its own default, `toggleSessionSidebar` (it has its own gate, `shouldToggleSessionSidebarFromShortcut`) and copy-selection. Capturing, re-enabling and Reset all go through `findShortcutConflict`/`findShortcutBindingConflict` (settings-ui.js); Alt+1-9, Ctrl/Shift+Enter and Ctrl/Cmd+V are reserved there.
 
 **A key gate on a chord that can carry Shift alone must swallow the KEYPRESS too** (#520). xterm calls the custom handler from `attachCustomKeyEventHandler` for `keydown`, `keypress` AND `keyup`, and its own `_keyPress` drops a keypress carrying Ctrl, Alt or Meta but not one whose only modifier is Shift. So a gate that returns `false` for `ev.type === 'keydown'` alone is safe for a Ctrl or Alt chord (the palette's Ctrl+K, Alt+B, Ctrl+V, Ctrl+Z and the keydown-only smart copy below) and leaks for a Shift-only one. That is how Shift+Enter submitted the prompt from April to #520: its keypress fell through to `onData` as a bare `\r`, which goes out synchronously over the WebSocket ahead of the async `send-key` fetch, so the CR reached the PTY before the newline did. Ctrl+Enter worked all along only because Chrome fires no keypress for it. ⚠️ The Shift/Ctrl+Enter gate in terminal-ui.js and its twin in Pane B (terminal-split.js) return `false` for EVERY event type and key only the `send-key` POST on `keydown`; never narrow either back to keydown, and give any new Shift-only chord the same shape. Swallowing the keyup as well is harmless (xterm only skips a focus and cursor-style refresh for that one event). Tests: `test/shift-enter-keypress-swallowed.test.ts` (CI gate, a source guard on both files) and `test/shift-enter-keypress.browser.test.ts` (browser suite, which the gate does not run: real keys against both real handlers in the real app). Settings → Terminal & Input → **Key tester** shows what a device reports for each of the three events.
 
@@ -1108,7 +1124,7 @@ Tests: `test/mobile-prompt-composer.test.ts` (in the CI gate, deliberately not u
 
 ### Buffers, uploads, and terminal history
 
-Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). tmux <3.7 allocates history at pane creation, so `createSession()` sets the global default in the same command queue immediately before `new-session`; tmux 3.7+ instead creates the session and targets only that pane, because changing the global option can resize and trim unrelated live panes. A settings change resizes tracked panes only on 3.7+ and otherwise affects future panes; no version can recover lines already evicted. Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. A camera-roll VIDEO (`?kind=video` on the same route, set by the client from the file's MIME type) is never buffered: it streams to disk under `MAX_PASTE_VIDEO_BYTES` 1GB (env `CODEMAN_MAX_PASTE_VIDEO_BYTES`), sniffed from the stream's first bytes (ISO BMFF / QuickTime atom, EBML for webm, Ogg for ogv) and unlinked on any failure. The client keys the flag on the MIME type, falling back to the name's extension because some Android file managers hand over a File with none; that classifier (`_promptAttachKind()`, image-input.js) is the ONE filter every pick and paste surface reads: Attach, drop, the Compose and paste-dialog pickers and the clipboard handlers. ⚠️ The flag is the ONLY way onto that path and admits video types alone (the registry's `VIDEO_ATTACHMENT_EXTENSIONS`, single-sourced so an uploaded video also previews: mp4/webm/mov/m4v/ogv; 3gp/mkv are out), so an image can never ride the larger cap through memory; without it the route is byte-identical to the image-only version. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). tmux <3.7 allocates history at pane creation, so `createSession()` sets the global default in the same command queue immediately before `new-session`; tmux 3.7+ instead creates the session and targets only that pane, because changing the global option can resize and trim unrelated live panes. A settings change resizes tracked panes only on 3.7+ and otherwise affects future panes; no version can recover lines already evicted. Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. A camera-roll VIDEO (`?kind=video` on the same route, set by the client from the file's MIME type) is never buffered: it streams to disk under `MAX_PASTE_VIDEO_BYTES` 1GB (env `CODEMAN_MAX_PASTE_VIDEO_BYTES`), sniffed from the stream's first bytes (ISO BMFF / QuickTime atom, EBML for webm, Ogg for ogv) and unlinked on any failure. The client keys the flag on the MIME type, falling back to the name's extension because some Android file managers hand over a File with none; that classifier (`_promptAttachKind()`, image-input.js) is the ONE filter every pick and paste surface reads: Attach, drop, the Compose and paste-dialog pickers and the clipboard handlers. ⚠️ The flag is the ONLY way onto that path and admits video types alone (the registry's `VIDEO_ATTACHMENT_EXTENSIONS`, single-sourced so an uploaded video also previews: mp4/webm/mov/m4v/ogv; 3gp/mkv are out), so an image can never ride the larger cap through memory; without it the route is byte-identical to the image-only version. A DOCUMENT (the office formats pdf/docx/pptx/xlsx/zip plus the text family txt/md/csv/tsv/json/log/yaml/yml/xml, the curated `ALLOWED_DOCUMENT_EXTS`, never `SUPPORTED_ATTACHMENT_EXTENSIONS` or `EDITABLE_EXTENSIONS`) is admitted by its name's extension and buffered like an image, judged on its bytes by the same fail-closed `imageMagicMatchesExt` (a magic-number signature, or UTF-8 without a NUL byte for the text family) and saved under a sanitized `[A-Za-z0-9._-]` stem of its name; sh/py/js/html are a deliberate SCOPE exclusion by extension (the server declines to store what `file-raw` would serve or an agent could run), not a content filter, since the agent can already write any of them. `_promptAttachKind()` returns `image`, `video` or `document`, and the server's dispatch mirrors it: an image MIME wins whatever the name says, a document extension takes the document branch, and a foreign extension with no image MIME is refused `Unsupported file type` only after the image sniff fails, so nothing the image path accepted by its bytes is lost. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
 
 **Prompt uploads live in `<workspace>/.codeman-uploads/`** (`POST /api/sessions/:id/paste-image`; the names live ONLY in `src/web/paste-image-gc.ts`): IN the workspace because that is the only path that resolves identically for a local agent and a container (only the workspace is bind-mounted, at the same absolute path; `~/.codeman` is not); hidden so it stays out of `git status` and the agent's view of the repository; FLAT because a nested `<workspace>/.codeman/` IS the data dir (`join(homedir(), '.codeman')`, `src/config/instance.ts`) when the workspace is the home directory, which nothing refuses; and self-ignoring through a `.gitignore` of `*` written once with `wx`, so a file already there is the user's and stays. The pre-move `.claude-images/` receives nothing but stays readable for one release: `UPLOAD_DIR_NAMES` lists both, the hourly sweep and the delete cleanup in `cleanupSession()` go through `uploadDirs()`, and the image watcher's ignore filter reads the names. ⚠️ `uploadDirs()` is async: the working directory is a user-chosen path, so it is probed BOUNDED first (`probePathKind()`, the #516 rule; `unknown` is skipped and never touched, the hourly sweep keeps the stall cap and `cleanupSession()` passes `pastCap`, since it acts on one path at the user's request), and the lstat and realpath after it are `fs.promises` calls, never sync, because the sweep runs 30 s after boot and hourly over every live session and a linked case on a dead mount would otherwise freeze the whole server. It returns only REAL directories (lstat at the leaf, so a planted `.codeman-uploads -> /other-case/.codeman-uploads` is never listed: `readdir` follows a link to a directory, and the sweep would otherwise age out the other case's uploads through it), none that is or contains `getDataDir()` (contrived, `CODEMAN_INSTANCE=uploads` makes `~/.codeman-uploads` the data dir of a home workspace and `CODEMAN_DATA_DIR` can point inside one, but it is one check next to a recursive delete; one strictly INSIDE the data dir is listed, since it only ever holds uploads and a workspace like the `~/.codeman/app` that `install.sh` clones would otherwise never have its uploads collected), and nothing for a remote (SSH) session, whose `workingDir` is the remote path and would otherwise name a same-named LOCAL directory for the sweep and the delete. The check is made when the directories are listed: a same-user process that swaps a listed directory for a link during the sweep's awaits is accepted (Node has no `openat()`, and that actor already writes anywhere this process can). The route refuses a remote (SSH) session with 400 before any disk touch: its `workingDir` is the remote path, so the file would land on THIS host where the agent cannot read it. ⚠️ And because a live session's workspace can go onto a network mount that later stops answering, the route probes `session.workingDir` BOUNDED (`probePathKind(..., { pastCap: true })`) before the first disk touch, refusing an `unknown` mount through `describeUnknownPath()` (OPERATION_FAILED) exactly as `POST /api/sessions` does, so a mount already unreachable cannot freeze a libuv worker on every upload (`ensureUploadDir()`'s own lstat/mkdir then start on a reachable path; a mount that dies between the probe and that write is the same residual race `POST /api/sessions` accepts, since a pre-check cannot bound the write that follows it). Tests: `test/paste-image-gc.test.ts`, `test/paste-image-dir-shared.test.ts`, the paste-image block of `test/routes/session-routes.test.ts`, `test/routes/session-create-unreachable-path.test.ts`.
 

docs/cli-registry.md

@@ -142,9 +142,10 @@ with newlines and tested once (`isBlockedScreen()`, `session-activity.ts`), so i
 several markers and anchor the dialog's footer on the END of the window (no `m` flag: `$` is
 the last row). Codex's needs a `› N.` option row and then its key-hint row (`Press enter to
 confirm or esc to cancel`, `tab to add notes | enter to submit answer | esc to interrupt`,
-`enter continue · esc quit` for the startup trust prompt), allowing for that row to wrap
-onto rows of its own below about 60 columns. Measured on codex-cli 0.162.0 at widths 200 down
-to 36: the command, edit and network-escalation approvals, single and multi-question
+`enter continue · esc quit` for the startup trust prompt, `esc back` when it follows the
+update prompt), allowing for that row to wrap onto rows of its own below about 60 columns.
+Measured on codex-cli 0.162.0 at widths 200 down to 36: the command, edit and
+network-escalation approvals, single and multi-question
 `request_user_input` dialogs (notes field open or closed), and the workspace trust prompt
 match; the idle and working views, popups the user opened (`/model`, `/permissions`,
 `/review`), the composer holding the dialogs' words and a transcript quoting them verbatim

docs/cron-guide.md

@@ -204,7 +204,7 @@ trailing carriage return:
 
 | Mode    | Mechanism                                                       | Use when                                         |
 | ------- | --------------------------------------------------------------- | ------------------------------------------------ |
-| `typed` | `session.writeViaMux()` — tmux `send-keys -l` (literal) + Enter | Default; behaves like a human typing the prompt. |
+| `typed` | `session.writeViaMux()` — the text as a tmux bracketed paste + Enter (a single character is typed, so a dialog answer selects) | Default; like a human pasting the prompt and pressing Enter. |
 | `paste` | `session.write()` — writes directly to the PTY/mux              | Bulk paste-style delivery.                       |
 
 > ⚠️ **Single-line only — enforced.** Like all programmatic input in Codeman,

docs/extending-codeman.md

@@ -228,10 +228,10 @@ whether your integration works, and the last one is what actually bites:
 ⚠️ **There is no readiness signal, and skipping readiness is the failure that looks
 like success.** A session reports `idle` before its CLI has spawned, and a `claude`
 worker in a brand-new case comes up on the CLI's **trust dialog**, which has a ❯
-prompt of its own. Prompt it at that moment and the text lands in the dialog, the
-`\r` does not get past it, and the session's startup `idle` lands inside the wait
-window: the wait resolves on `idle` in a couple of seconds with `timedOut: false`,
-indistinguishable from a finished turn. Wait for the pid, then wait for the
+prompt of its own. Prompt it at that moment and the text lands in the dialog,
+whose highlighted option is `No, exit`, so the prompt's `\r` quits the CLI. Codeman
+holds the session's `idle` while the dialog is on screen, which makes waiting for
+`idle` safe but still not a readiness signal. Wait for the pid, then wait for the
 composer, answering the dialog only as the bounded fallback.
 
 ⚠️ **Answering it is not "press Enter".** Claude Code 2.1.252 dropped the options'

docs/media-assets.md

@@ -26,7 +26,9 @@ A GIF that leaves `docs/images/` stays in git history, so removing it does not s
 | `tile-grid-20261009.gif` | README, Tile Grid section | the Tiles button opening six live sessions side by side, and closing them |
 | `zerolag-demo-20260728.gif` | README, wiki `Input-And-Voice`, `packages/xterm-zerolag-input/README.md`, CHANGELOG, getcodeman.com docs | instant local echo next to slow server echo, on two phones |
 | `codeman-tab-states-20261010.gif` | README, Tab Alerts section | annotated tab states: working, blocked on a question, idle |
-| `codeman-skill-crt-20261010.gif` | README, agent skill section | one prompt to Claude Code spawning and driving two worker sessions through the skill |
+| `codeman-skill-crt-20261010.gif` | README, agent skill section; wiki `Codeman-Skill` (getcodeman.com docs show the MP4 cut) | one prompt to Claude Code spawning and driving two worker sessions through the skill |
+| `codeman-skill-grid-20261015.gif` | README, agent skill section (Step 2); wiki `Codeman-Skill` (getcodeman.com docs show the MP4 cut) | one prompt to a Claude Code lead, five Claude Code workers powering on as tiles in the grid |
+| `codeman-skill-tabs-20261015.gif` | README, agent skill section (Step 3); wiki `Codeman-Skill` (getcodeman.com docs show the MP4 cut) | one prompt to a Claude Code lead, eight worker tabs powering on with lineage lines, then a click into a live worker |
 | `subagent-demo-20260724.gif` | the "mission control" article on dev.to, Hashnode and Medium (hotlinked from `master`) | subagent windows fanning out |
 
 Before removing one, search for hotlinks: `README*.md`, `docs/wiki/`, `packages/*/README.md`, `CHANGELOG.md`, the site (`pr/website/`), and published articles, which link `raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/<file>` and break silently.
@@ -36,12 +38,12 @@ On 2026-10-13, seven GIFs that no page embedded left `docs/images/` and moved in
 ### Adding or replacing a README GIF
 
 1. Keep the master (the lossless MP4 or the full-size GIF) in `pr/media/clips/<feature>/`, or in the project folder it came from.
-2. Commit only the size the README shows, named `<feature>-<YYYYMMDD>.gif`, and keep it lean: the current ones are 0.8 to 7 MB.
+2. Commit only the size the README shows, named `<feature>-<YYYYMMDD>.gif`, and keep it lean: the current ones are 0.8 to 10 MB.
 3. A replaced GIF leaves `docs/images/` in the same commit, unless something outside the repo hotlinks it (see above).
 
 ## Website media (getcodeman.com)
 
-The site is built and deployed from `pr/website/` (gitignored) with `pr/deploy-site.sh`. Its videos and GIFs sit in `pr/website/assets/` because that directory is what gets uploaded: they are web cuts (1280 to 1600 px wide, high CRF, posters next to them) derived from masters in the library. `pr/site-notes.md` records how each one was cut and from which master. A few superseded files stay deployed on purpose, so links that point at them keep resolving.
+The site is built and deployed from `pr/website/` (gitignored) with `pr/deploy-site.sh`. Its `/docs` pages are generated from `docs/wiki/`, and a wiki GIF that has an MP4 cut of the same run on the site is shown there as that video (the README and the GitHub wiki keep the GIF, since GitHub cannot autoplay inline video). Its videos and GIFs sit in `pr/website/assets/` because that directory is what gets uploaded: they are web cuts (1280 to 1600 px wide, high CRF, posters next to them) derived from masters in the library. `pr/site-notes.md` records how each one was cut and from which master. A few superseded files stay deployed on purpose, so links that point at them keep resolving.
 
 ## Release notes and the media kit (`design-assets` branch)
 

docs/multi-user-plan.md

@@ -161,8 +161,8 @@ Codeman now ships a global **Startup Mode** picker (App Settings, Claude CLI tab
 | Screenshots `/api/screenshots` (deprecated)                                | Deprecated: removed in a later MAJOR, so no per-user subdir is planned; the replacement `POST /api/sessions/:id/paste-image` is already session-scoped. Former plan: per-user subdir `~/.codeman/screenshots/<username>/` in multi-user mode. Note: `GET /:name` deliberately rejects `/` in names as traversal, so derive the subdir server-side from `req.authUser` and keep client-visible names flat                                                  |
 | Attachments                                                                | Already session-scoped; inherits the session owner check. `attachmentConfineToWorkspace` is a global, default-OFF setting today: in multi-user mode it is FORCED ON for non-admins regardless of the setting (their attachments must resolve inside their own space); the setting keeps meaning what it means for admins                                                                                                                                  |
 | File routes (browse/preview)                                               | Path allowlist adds: non-admin paths must resolve (realpath) inside their own space or their own sessions' workingDirs                                                                                                                                                                                                                                                                                                                                    |
-| Settings (`settings.json`)                                                 | Global, admin-only writes in multi-user mode; reads allowed (per-device display keys stay in localStorage as today). Per-user server settings: out of scope v1                                                                                                                                                                                                                                                                                            |
-| System ops (self-update, tunnel toggle, span-displays, docker image build) | Admin-only                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Settings (`settings.json`)                                                 | Global, admin-only writes in multi-user mode; reads allowed (per-device display keys stay in localStorage as today). **Implemented (1.42.0):** `PUT /api/settings`, `PUT /api/execution/model-config`, `PUT /api/config` and `PUT /api/cases/order` answer 403 `FORBIDDEN` to a non-admin before parsing anything; quick-start and Ralph loop start skip a non-admin's `lastUsedCase`; the browser skips those writes for a non-admin (`_settingsReadOnly()`, settings-ui.js) and keeps their own run mode and respawn presets on the device; a non-admin's `GET /api/settings` omits `voiceSettings.apiKey`, `caseOrder` and `lastUsedCase` (`settingsForNonAdmin`). Per-user server settings: out of scope v1|
+| System ops (self-update, tunnel toggle, span-displays, docker image build) | Admin-only. **Implemented (1.42.0):** `POST /api/system/update`, `/api/system/span-displays`, `/api/tunnel/qr/regenerate` and `/api/cleanup-state` answer 403 `FORBIDDEN` to a non-admin; a non-admin's `POST /api/auth/revoke` revokes only their own login sessions and `GET /api/tunnel/info` lists only those |
 | `getLightState` init snapshot                                              | Filtered per connection. Actual contents to filter (verified): `sessions`, `scheduledRuns`, `respawnStatus`, `subagents`, `workflowRuns`, `planUsage` (host-plan telemetry: admin-only); `globalStats` stays coarse-global. Cron jobs are NOT in the snapshot (they have their own REST route; filter there). The snapshot is cached process-wide (`LIGHT_STATE_CACHE_TTL_MS`): either key the cache per role/user or filter AFTER the cache on each send |
 
 ## 7. SSE Event Filtering

docs/orchestrator-loop-architecture.md

@@ -244,7 +244,7 @@ RalphLoop.tick() → assignTasks()  // OR OrchestratorLoop does its own assignme
 session.sendInput(task.prompt)
   │
   ▼
-writeViaMux() → tmux send-keys -l "prompt..." + Enter
+writeViaMux() → tmux paste-buffer -p (prompt as one bracketed paste) + Enter
   │
   ▼
 Claude CLI receives prompt, executes, outputs results

docs/releasing.md

@@ -19,7 +19,7 @@ When user says "COM":
 
    Replace `patch` with `minor` or `major` as needed. Include `"xterm-zerolag-input": patch` on a separate line if that package changed too.
 
-3. **Consume the changeset**: `npm run version-packages` (auto-bumps `package.json` files, updates `CHANGELOG.md`, runs `npm install --package-lock-only`, and verifies lockfile sync via `scripts/check-lockfile-sync.mjs` — all in one command; never hand-edit `CHANGELOG.md` or `package-lock.json` versions)
+3. **Consume the changeset**: `npm run version-packages` (auto-bumps `package.json` files, updates `CHANGELOG.md`, runs `npm install --package-lock-only`, and verifies lockfile sync via `scripts/check-lockfile-sync.mjs` — all in one command; never hand-edit `CHANGELOG.md` or `package-lock.json` versions. It also writes `src/web/public/whats-new.json` (`scripts/generate-whats-new.mjs`): the bold lead-in of each change in the new `CHANGELOG.md` section, which the browser announces once per version in a toast. Commit it with the release; `test/whats-new.test.ts` fails when its version differs from `package.json`, so a hand bump needs `node scripts/generate-whats-new.mjs && npx prettier --write src/web/public/whats-new.json` too. A release whose notes have no bold lead-ins ships an empty list and shows no toast)
 4. **Sync CLAUDE.md version**: Update the `**Version**` line in the root `CLAUDE.md` (under COM Shorthand) to match the new version from `package.json`
 5. **Commit and deploy**: verify the branch first (`git branch --show-current`), then stage EXPLICIT paths — never `git add -A`, which has swept another session's WIP into a release. `git status --short` and account for every line before committing:
    `git add <paths> && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`

docs/wiki/Codeman-Skill.md

@@ -0,0 +1,166 @@
+# The Codeman Skill
+
+The codeman skill lets the agent inside a Codeman session drive Codeman itself. You ask in
+plain English, and the agent starts worker sessions in any installed CLI, hands each one its
+task, waits for them, reads their answers and cleans up after itself. No curl, no endpoint
+names, no session ids in your prompt.
+
+It is one skill for every agent CLI, in the `SKILL.md` format that Claude Code, Codex,
+Gemini CLI, OpenCode, Grok, OMP and most other agent CLIs read. It lives in the repo at
+[`skills/codeman`](https://github.com/Ark0N/Codeman/tree/master/skills/codeman).
+
+## See it work
+
+Three real runs on a live Codeman: real sessions, real agents, one typed prompt each.
+Nothing on screen is mocked up; the long waits are sped up and labelled as time-lapse.
+
+### Five workers in the tile grid
+
+The lead Claude Code session gets `use codeman to start 5 claude workers, one per TODO item`,
+and five Claude Code workers power on, one per item, with all six agents working at once.
+
+![A real codeman skill run in the tile grid: the lead Claude Code session powers on as the only tile, the prompt use codeman to start 5 claude workers, one per TODO item is typed, then five Claude Code worker sessions power on as new tiles one after another with the CRT animation, and all six agents work at once](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-skill-grid-20261015.gif)
+
+Sessions an agent starts do not join the grid by themselves. In this recording each worker
+was put on the grid as it started, the way `Ctrl`+click or dragging its tab does it: see
+[Tile Grid](Tile-Grid).
+
+### Eight workers, eight tabs
+
+The same prompt with eight workers, in the normal view. Every worker gets its own tab, and a
+lineage line runs from the lead to each one, so you can see who spawned whom. Clicking a
+worker's tab shows it at work.
+
+![A real codeman skill run in the normal view: the prompt use codeman to start 8 claude workers, one per TODO item is typed, eight worker tabs power on left to right while lineage lines draw from the lead to each one, then clicking a worker tab shows a live Claude Code worker receiving its task](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-skill-tabs-20261015.gif)
+
+### Two CLIs from one prompt
+
+Workers do not have to run the same CLI as the lead. Here the prompt is
+`use codeman to have a dsh worker on qwen build search and a claude one build checkout`: a
+DeepSeek Harness worker on a local qwen model and a Claude Code worker power on side by side.
+
+![A real codeman skill run: one short prompt typed into Claude Code, the tile grid powering on, then a DeepSeek Harness worker on a local qwen model and a Claude Code worker powering on as new tiles, with lineage lines from the lead to both](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-skill-crt-20261010.gif)
+
+## Install it
+
+Pick one route. The skill only acts inside a Codeman session, so a global install is safe.
+
+| How                | Command                                                                         | Scope |
+| ------------------ | ------------------------------------------------------------------------------- | ----- |
+| Skills CLI         | `npx skills add Ark0N/Codeman --skill codeman -g`                               | Global, any skills-aware agent. The way to give it to pi. |
+| Claude Code plugin | `/plugin marketplace add Ark0N/Codeman`, then `/plugin install codeman@codeman` | Global, through Claude Code's plugin manager. `/plugin update codeman` follows releases. |
+| Bundled CLI        | `codeman skill install`                                                         | Global, at `~/.claude/skills/codeman`. |
+| Bundled CLI        | `codeman skill install --case <name> [--mode <mode>]`                           | One case. `--mode codex` (or any other run mode) writes it where that CLI looks for skills. |
+| Web UI             | **App Settings → Agents & CLIs → All agent CLIs → Codeman Agent Skill**         | Injects it into each case when a session is created, where that session's CLI looks: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI, OpenCode, Antigravity, Grok, DeepSeek and OMP. Off by default. |
+
+Use the plugin **or** `codeman skill install`, not both: a Claude Code with both lists the
+skill twice (`codeman` and `codeman:codeman`).
+
+The web UI route skips pi, because a project skill makes pi ask to trust the folder at
+startup. A pi or plain shell session uses the [`codeman agent`
+commands](Driving-Codeman-From-An-Agent#the-codeman-agent-commands) instead, which are the
+same verbs as shell commands.
+
+### Remove it
+
+`codeman skill uninstall [--case <name>]` reverses the CLI installs (with `--case`, every
+Codeman-managed copy in that case, whichever CLI's directory it sits in). It never touches a
+`skills/codeman` you wrote yourself.
+
+Turning the web UI setting back off **does not remove copies it already injected**, because
+a sweep at session start would pull the skill out from under other live sessions sharing
+that directory. Remove them per case with `codeman skill uninstall --case <name>`.
+
+## Then just ask
+
+These prompts work as written:
+
+| You say                                                                                   | What happens |
+| ----------------------------------------------------------------------------------------- | ------------ |
+| "What sessions are running right now?"                                                     | Lists them with name, mode and status. Read-only. |
+| "Use codeman to start 5 claude workers, one per TODO item."                                | One worker per item, each handed its task, answers gathered as they finish. |
+| "Start a shell worker on the `myapp` case, run the test suite, tell me if it passes."      | Spawns, waits on a completion marker, reads the exit code, cleans up. |
+| "Spin up 3 workers for lint, typecheck and tests, run them in parallel, report failures."  | One session per task, all started first, then gathered as each finishes. |
+| "Have a claude worker summarize `src/session.ts`, then close it."                          | Spawns, waits until the worker is ready, sends and waits, reads the answer, deletes the session. |
+| "Have a DeepSeek Harness worker build search and a claude worker build checkout."          | A mixed fleet: one worker per CLI, started in one go. |
+| "Watch session w4 and tell me if it gets stuck on a permission prompt."                    | Blocks on the `blocked` signal and brings the question to **you**. |
+
+Sessions the agent creates are deleted when it is done, so you can watch the tabs appear and
+disappear in the dashboard while it works.
+
+### A run, start to finish
+
+> **You:** spin up 3 shell workers, run lint / typecheck / the frontend syntax check in
+> parallel, and tell me which failed.
+
+```text
+lint       -> 9f2d8e5f   dispatched
+typecheck  -> aff9c691   dispatched     3 tabs appear in the dashboard
+syntax     -> be9f1f15   dispatched
+
+lint         DONE_lint_17909      rc=0
+typecheck    DONE_typecheck_3409  rc=0   gathered as each one finishes
+syntax       DONE_syntax_18501    rc=0
+
+deleted 9f2d8e5f, aff9c691, be9f1f15    tabs disappear
+```
+
+The `DONE_<task>_<random>` strings are the
+[split-marker trick](Driving-Codeman-From-An-Agent#the-split-marker-trick): a shell session
+has no "turn finished" signal, so the skill waits for a marker in the output, typed in two
+halves so that only the command's real output ever contains the joined string.
+
+## Which workers it can drive
+
+Any run mode installed on the machine can be a worker. Claude Code and DeepSeek Harness are
+the two with real completion signals (Claude's from its hooks, DeepSeek's from the harness),
+so the skill can wait for "turn finished" and read the answer as clean text. Every other CLI
+and plain shell sessions are synchronized on an output marker instead, which works the same
+from your side. See [Agent CLIs](Agent-CLIs) for the run modes.
+
+With Claude Code workers, where the installed Claude Code supports it, the lead can also
+message a worker directly instead of typing into its terminal.
+
+## What it will and will not do
+
+- **It self-gates.** Outside a Codeman session (`CODEMAN_MUX` unset) it refuses to act and
+  never guesses an API URL, so a global install costs an unrelated agent session nothing.
+- **Unprompted, it may only** start sessions, prompt them, and delete the ones **it created
+  in that conversation, by exact id**, behind a guard that refuses to delete the agent's own
+  session.
+- **It will not** answer another session's permission prompt on your behalf. It brings the
+  question to you instead.
+- **Only when you ask, naming the target:** deleting a case (which erases a real directory
+  of your code), bulk kills, respawn, Ralph, cron, the orchestrator, and settings changes.
+
+## When the agent is Codex
+
+Two things to know:
+
+- Codex's default sandbox blocks network access, even to this machine, so the skill needs
+  **Bypass approvals and sandbox** (App Settings, Codex).
+- Codex 0.162 runs its commands in a shared background process, whose Codeman variables can
+  belong to the session that started it.
+
+The skill checks for both and says so instead of acting.
+
+## What is in the skill
+
+| File | Contents |
+| ---- | -------- |
+| [`SKILL.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/SKILL.md) | Safety rules, the fast path (start N workers, task them, collect the answers) and the verb index. Always loaded. |
+| [`reference/verbs.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/verbs.md) | Every verb in detail: readiness, send-and-wait, markers, interrupts, cleanup. Loaded on demand. |
+| [`reference/recipes.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/recipes.md) | Worked flows: claude, DeepSeek Harness and shell workers, fan-out, watching a blocked worker, messaging. Loaded on demand. |
+| [`reference/endpoints.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/endpoints.md) | Endpoint tables, error codes, the signals each mode emits, capacity limits. Loaded on demand. |
+| [`reference/messaging.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/messaging.md) | Talking to claude workers directly through Claude Code's cross-session messaging. Loaded on demand. |
+
+Only `SKILL.md` sits in the agent's context; the references load when a job needs them, so a
+quick run stays quick.
+
+## Read next
+
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the `codeman agent`
+  commands, the MCP server, and the raw HTTP rules the skill is built on.
+- [Tile Grid](Tile-Grid) - watching several workers side by side.
+- [The Dashboard](The-Dashboard) - tabs, lineage lines and status dots.
+- [Watching Agents Work](Watching-Agents-Work) - the subagents inside each session.

docs/wiki/Core-Concepts.md

@@ -46,7 +46,8 @@ case. Each has a stable id, and that id is what the API, the wait primitives, an
 event use.
 
 Several sessions can share one case. That is the normal way to parallelize: three workers
-in the same repo, three tabs, one case.
+in the same repo, three tabs, one case. They then also share one folder; when the workers
+edit and commit in parallel, give each its own checkout with [Git Worktrees](Git-Worktrees).
 
 A session carries state the case does not:
 

docs/wiki/Driving-Codeman-From-An-Agent.md

@@ -12,58 +12,19 @@ everything else.
 
 A skill in the `SKILL.md` format that Claude Code, Codex, Gemini CLI, OpenCode, Grok, OMP
 and most other agent CLIs read. It teaches the agent the whole API, so you ask in plain
-English instead of pasting endpoint documentation into prompts.
+English instead of pasting endpoint documentation into prompts:
 
-### Install it
+```bash
+codeman skill install    # or: npx skills add Ark0N/Codeman --skill codeman -g
+```
 
-| How          | Command                                                     | Scope                                                       |
-| ------------ | ----------------------------------------------------------- | ----------------------------------------------------------- |
-| Skills CLI   | `npx skills add Ark0N/Codeman --skill codeman -g`            | Global, any skills-aware agent. The way to give it to pi.    |
-| Claude Code plugin | `/plugin marketplace add Ark0N/Codeman`, then `/plugin install codeman@codeman` | Global, through Claude Code's plugin manager. `/plugin update codeman` follows releases. Pick this or `codeman skill install`, not both, or the skill is listed twice (`codeman` and `codeman:codeman`). |
-| Bundled CLI  | `codeman skill install`                                      | Global, at `~/.claude/skills/codeman`.                       |
-| Bundled CLI  | `codeman skill install --case <name> [--mode <mode>]`        | One case. `--mode codex` (or any other run mode) writes it where that CLI looks for skills. |
-| Web UI       | **App Settings → Agents & CLIs → All agent CLIs → Codeman Agent Skill** | Injects into each case when a session is created, where that session's CLI looks: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI, OpenCode, Antigravity, Grok, DeepSeek and OMP. Not pi: a project skill makes pi ask to trust the folder at startup. Off by default. |
+Then ask the agent in a Codeman session something like *"use codeman to start 5 claude
+workers, one per TODO item"*. It starts the workers, hands each one its task, gathers the
+answers and deletes the sessions it created.
 
-`codeman skill uninstall [--case <name>]` reverses the CLI installs (with `--case`, every
-Codeman-managed copy in that case), and never touches a `skills/codeman` you wrote yourself.
-
-Two things to know when the agent is **Codex**: its default sandbox blocks network access
-even to this machine, so the skill needs **Bypass approvals and sandbox** (App Settings,
-Codex); and Codex 0.162 runs its commands in a shared background process, whose Codeman
-variables can belong to the session that started it. The skill checks for both and says so
-instead of acting.
-
-### Then just ask
-
-| You say                                                                                 | What happens                                                                             |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| "What sessions are running right now?"                                                   | Lists them with name, mode, and status. Read-only.                                          |
-| "Start a shell worker on the `myapp` case, run the test suite, tell me if it passes."     | Spawns, waits on a completion marker, reads the exit code, cleans up.                       |
-| "Spin up 3 workers for lint, typecheck and tests, run them in parallel, report failures." | One session per task, all started first, then gathered as each finishes.                    |
-| "Have a claude worker summarize `src/session.ts`, then close it."                         | Spawns, runs the readiness ladder, sends and waits, reads the answer, deletes the session.  |
-| "Watch session w4 and tell me if it gets stuck on a permission prompt."                   | Blocks on the `blocked` signal and surfaces the question to **you**.                        |
-
-Sessions the agent creates get deleted when it is done. You can watch the tabs appear and
-disappear in the dashboard while it works.
-
-### What it will and will not do
-
-- **It self-gates.** Outside a Codeman session it refuses to act and does not guess an API
-  URL, so a global install costs an unrelated Claude Code session nothing.
-- **Unprompted, it may only** spawn sessions, prompt them, and delete ones **it created in
-  that conversation, by exact id**, behind a guard that refuses to delete the agent's own
-  session.
-- **It will not** answer another session's permission prompt on your behalf. It surfaces the
-  question instead.
-- **Deleting a case** (which erases a real directory of your code), bulk kills, respawn,
-  Ralph, cron, orchestrator, and settings writes all require you to ask, naming the target.
-
-Turning the setting back off **does not remove already-injected copies**, because a
-create-time sweep would yank the skill out from under other live sessions sharing that
-directory. Remove them per case with `codeman skill uninstall --case <name>`.
-
-The skill ships with the verb index always loaded, plus on-demand references for the verbs,
-worked multi-worker recipes, endpoint tables, and cross-session messaging. It drives
+**[The Codeman Skill](Codeman-Skill)** has the rest: recordings of real runs, every install
+route (Claude Code plugin, skills CLI, per case, the web UI setting), prompts that work as
+written, what it will and will not do on its own, and the notes for Codex. It drives
 DeepSeek Harness workers the same way it drives Claude ones (`spawn_workers alpha
 beta:deepseek` is a mixed fleet in one call), since those are the two modes with real
 completion signals.
@@ -191,9 +152,9 @@ Read these before writing any code. Each one has cost somebody an afternoon.
    output marker instead.
 7. **Nothing reports "ready", so wait for it explicitly.** A new session answers
    `{"signal":"exit","immediate":true}` until its PID exists, and that means *not started*,
-   not *crashed*. A Claude worker in a fresh case then sits on the CLI's trust dialog; prompt
-   it there and the wait resolves on idle in about two seconds looking exactly like a finished
-   turn, while your text sits stuck in the dialog.
+   not *crashed*. A Claude worker in a fresh case then sits on the CLI's trust dialog, whose
+   highlighted option is `No, exit`: prompt it there and your Enter quits the CLI. Codeman
+   holds `idle` while the dialog is on screen, but that is not a readiness signal either.
 
 ### Recipes
 
@@ -284,6 +245,7 @@ failing the spawn, because a cosmetic field must never break a worker.
 
 ## Read next
 
+- [The Codeman Skill](Codeman-Skill) - the skill in action, its install routes and its limits.
 - [HTTP API](HTTP-API) - the endpoint map and the envelope.
 - [Hooks And Integrations](Hooks-And-Integrations) - events flowing the other way.
 - [Watching Agents Work](Watching-Agents-Work) - seeing the fan-out in the UI.

docs/wiki/FAQ.md

@@ -207,10 +207,13 @@ cover them properly.
 ### Can agents start and supervise other agents?
 
 Yes. Codeman ships an agent skill that lets an agent inside a session drive the HTTP API:
-list sessions, spawn workers, send prompts, and block until a worker's turn finishes. It is
-off by default and enabled per case.
+list sessions, spawn workers in any installed CLI, send prompts, and block until a worker's
+turn finishes. Install it once with `codeman skill install` or the Claude Code plugin, then
+ask in plain English, for example *"use codeman to start 5 claude workers, one per TODO
+item"*. The web UI setting that injects it into every new session's case is off by default.
 
-See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
+See [The Codeman Skill](Codeman-Skill), with recordings of real runs, and
+[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) for the other routes.
 
 ### Can I run a case in a container?
 

docs/wiki/Git-Worktrees.md

@@ -0,0 +1,73 @@
+# Git Worktrees
+
+Sessions in one case share its folder. That is fine for one agent, but three agents in the
+same checkout edit the same files, overwrite each other's builds, and commit each other's
+half-finished work. A **git worktree** gives each of them a checkout of its own: same
+repository, same history, a separate folder on a separate branch.
+
+Codeman creates worktrees for a case whose folder is a git repository, starts sessions in
+them, and removes them again when the work is done.
+
+## Where they live
+
+`<case>/.claude/worktrees/<name>`, on a new branch `worktree-<name>`. That is exactly where
+Claude Code's own `claude --worktree <name>` puts them, so a worktree made in Codeman is one
+Claude Code recognizes, and the other way round. Codeman's Recent Sessions and Session Manager
+lists mark a session that runs in one with a `⑂ <name>` pill.
+
+The main checkout does not show the worktrees as untracked: Codeman adds `/.claude/worktrees/`
+(and `/.claude/settings.local.json`, the hooks file it writes for every Claude session, plus the
+`codeman` folder it writes when **Codeman Agent Skill** is on) to the repository's local
+`.git/info/exclude` when git does not ignore them already. Without that, those files would make
+every worktree look modified and git would refuse to remove it. Your tracked `.gitignore` is
+never touched.
+
+## Creating one and starting a session in it
+
+1. Pick the case in the toolbar's case picker.
+2. Open the picker again and choose **Git worktrees…** (on a phone: the case sheet's
+   **Worktrees** button).
+3. Under **New worktree**, type a name (letters, digits, `.`, `_`, `-`, up to 64 characters).
+4. Pick the CLI under **Start sessions with** (Claude Code, Codex, a shell, any installed run
+   mode).
+5. **Create & start session**.
+
+The worktree is created from the case's current commit, and the session opens in it as a tab
+named `w1-<name>`. Under **Branch and start point** you can name the branch yourself or start
+from another branch, tag or commit. An existing branch is never reused or reset: pick another
+name.
+
+**Open** on a worktree's row starts another session in it, with the CLI chosen above.
+
+## Removing one
+
+Two ways, and both use `git worktree remove` **without** `--force`:
+
+- **Remove…** on the worktree's row in the dialog.
+- Closing a session that runs in a worktree: the Close Session dialog offers **Kill & remove
+  worktree**, which kills the session and then removes its worktree.
+
+git refuses to remove a worktree that still holds uncommitted or untracked files, and Codeman
+shows that refusal as git worded it and leaves everything in place. Commit, stash or delete the
+work first, then remove again. A worktree a live session still runs in is refused too.
+
+**Also delete its branch** deletes the branch with `git branch -d`, which keeps a branch whose
+commits are not merged yet. The worktree is still removed, and the message says the branch was
+kept.
+
+If a worktree's folder was deleted by hand, its row says **missing** and offers only
+**Remove…**: that clears the record git keeps of it, so the name can be used for a new worktree.
+
+## What is not supported
+
+- **Docker cases and remote (SSH) cases.** A container can write to its workspace, and creating
+  a worktree runs the repository's hooks and checkout filters on the Codeman machine, so git is
+  never run there. A remote case's repository is on another machine. For the same reason a
+  worktree that a Docker case uses as its workspace (or that holds one) is never removed from
+  here: remove the Docker case first.
+- A case folder that is not the top of a repository (a subfolder of one), a bare repository, or
+  an empty repository with no commit yet.
+- Worktrees outside `.claude/worktrees/` (made by hand with `git worktree add`) are listed, but
+  Codeman neither starts sessions in them from the dialog nor removes them.
+
+The HTTP endpoints are in the [HTTP API](HTTP-API) reference (`/api/cases/:name/worktrees`).

docs/wiki/HTTP-API.md

@@ -72,7 +72,7 @@ Roughly 235 handlers across 26 route modules. By domain:
 | ------------------- | -------- | --------------------------------------------------- |
 | System              | 56       | Status, settings, digest, updates, tunnel.           |
 | Sessions            | 34       | Create, input, terminal, wait, last response, kill.  |
-| Cases               | 34       | Create, link, clone, remote and docker cases.        |
+| Cases               | 37       | Create, link, clone, worktrees, remote and docker cases. |
 | Files               | 17       | Preview, edit, raw, attachments, path picker.        |
 | Orchestrator        | 10       | Plans and phases.                                     |
 | Ralph               | 9        | Loop control and configuration.                       |

docs/wiki/Home.md

@@ -41,7 +41,8 @@ codeman web    # then open http://localhost:3000
 
 **Driving it from code**
 
-- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the bundled skill, worker sessions, wait primitives.
+- [The Codeman Skill](Codeman-Skill) - one prompt, a whole crew: an agent starting and supervising worker sessions.
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the `codeman agent` commands, the MCP server, wait primitives.
 - [HTTP API](HTTP-API) - the envelope, auth, the endpoint map, SSE events.
 - [Hooks And Integrations](Hooks-And-Integrations) - events flowing back into Codeman.
 
@@ -66,6 +67,7 @@ codeman web    # then open http://localhost:3000
 | [Agent CLIs](Agent-CLIs)                   | Which agent should this session run, and how do I set it up? |
 | [Custom Model Endpoints](Custom-Model-Endpoints) | How do I point a session at my own OpenAI-compatible endpoint? |
 | [Working With Files](Working-With-Files)   | How do I read, edit, and attach files?                     |
+| [Git Worktrees](Git-Worktrees)             | How do several agents work on one repository without sharing a folder? |
 | [Input And Voice](Input-And-Voice)         | How do I talk to an agent, including by voice?             |
 | [Mobile Guide](Mobile-Guide)               | How well does this work on a phone?                        |
 | [Keyboard Shortcuts](Keyboard-Shortcuts)   | What can I drive from the keyboard?                        |
@@ -101,6 +103,7 @@ codeman web    # then open http://localhost:3000
 
 | Page                                                              | What it answers                              |
 | ----------------------------------------------------------------- | -------------------------------------------- |
+| [The Codeman Skill](Codeman-Skill)                                | How do I get an agent to start and run workers for me? |
 | [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent)    | How does an agent spawn and drive workers?   |
 | [HTTP API](HTTP-API)                                              | What can I call, and what comes back?        |
 | [Hooks And Integrations](Hooks-And-Integrations)                  | How do I wire Codeman into something else?   |

docs/wiki/Keyboard-Shortcuts.md

@@ -67,6 +67,13 @@ default. See [Tile Grid](Tile-Grid).
 
 **App Settings → Shortcuts.** Bindings live in a registry with per-user overrides, so a
 rebind is stored as an override on top of the default rather than replacing the table.
+Previous Session (`Alt+[`) and Next Session (alternate, `Alt+]`) are rows like any other,
+so they can be rebound too.
+
+A chord another action already uses is refused, and the message names that action. The same
+check runs when you re-enable a disabled shortcut and when you press Reset: if its chord was
+given to something else in the meantime, it stays as it was. `Alt+1` to `Alt+9`,
+`Shift+Enter`/`Ctrl+Enter` and `Ctrl+V`/`Cmd+V` are reserved.
 
 Two things are deliberately not rebindable:
 
@@ -79,8 +86,11 @@ Two things are deliberately not rebindable:
 
 The terminal sees keystrokes before the app does. Any chord the app claims has to also be
 swallowed at the terminal layer, or xterm writes the control byte into the session as well
-as triggering the action. If you rebind something to a chord the terminal cares about
-(`Ctrl+D`, say), expect the CLI to see it too.
+as triggering the action. A chord **you** rebind an action to is kept out of the terminal
+too, so rebinding Previous Session to `Alt+J` switches the session and sends nothing to the
+CLI. The built-in defaults are deliberately not held back this way: `Ctrl+L` clears the
+screen and also reaches the CLI, which redraws on it. Binding an action back onto its own
+default behaves like the default.
 
 `Alt+1` through `Alt+9` are matched on **physical key position** rather than the character
 produced, so macOS Option layouts that produce `¡™£` still switch tabs.

docs/wiki/Mobile-Guide.md

@@ -66,7 +66,8 @@ autocorrect: Enter adds a new line, and only Send delivers the text, as one past
 by Enter, so your line breaks reach the agent intact. Anything already typed on the terminal
 prompt moves into the editor when it opens. Drafts are kept per session and in memory only,
 so switching tabs keeps them and a page reload forgets them; a dot on the key shows a draft
-is parked. The editor's Image button attaches photos or videos and puts their paths into the draft.
+is parked. The editor's Attach button attaches photos, videos or documents and puts their paths
+into the draft.
 Destructive commands need a double press, so you cannot fire `/clear` with a stray thumb. On
 Codex sessions the bar also shows `⇧←` and `⇧→`, the Shift-modified arrows Codex binds to
 editing the last queued message and walking the prompt stack.
@@ -103,12 +104,16 @@ into the Run dropdown.
 ## The Attach button
 
 The toolbar's **Attach** button (the picture icon beside the mic) is the keyboard-down way to
-hand the agent a photo or a video. One tap opens the camera and photo library sheet, nothing
-else: no editor, no keyboard. The chosen files upload and their paths land on the prompt, so
-you then tap the terminal, write the rest of your message and press Enter. Videos (mp4, webm,
-mov, m4v, ogv) upload as recorded, up to 1 GB each by default
-(`CODEMAN_MAX_PASTE_VIDEO_BYTES` on the server changes it), so a long 4K clip takes a moment
-on the way up.
+hand the agent a photo, a video or a document. One tap opens the system's sheet (camera,
+photo library, or a file from Files or a cloud drive), nothing else: no editor, no keyboard.
+The chosen files upload and their paths land on the prompt, so you then tap the terminal,
+write the rest of your message and press Enter. Videos (mp4, webm, mov, m4v, ogv)
+upload as recorded, up to 1 GB each by default (`CODEMAN_MAX_PASTE_VIDEO_BYTES` on the
+server changes it), so a long 4K clip takes a moment on the way up. Documents are PDFs,
+Office files (docx, pptx, xlsx), zips and plain-text formats such as txt, md, csv and json;
+a document keeps the plain-letters part of its name in the saved file, so the agent and you
+can tell the uploads apart. See [Working With Files](Working-With-Files) for where they land and how long they
+stay.
 
 If the keyboard was up when you tapped Attach, iOS closes it to show the photo sheet and does
 not bring it back, so the tap on the terminal is how you get it again. That is the system's
@@ -120,7 +125,7 @@ anything you had already typed, so you can write in front of a path, fix a word,
 **Use terminal keyboard** hands a single-line message back the other way, onto the prompt,
 so neither surface holds a half of your message. A multi-line message cannot make that trip
 (the prompt is a single line), so it stays parked as a draft and the dot on the Compose key
-shows it is waiting. The Compose editor's own Image button remains for the times you are
+shows it is waiting. The Compose editor's own Attach button remains for the times you are
 already writing in the editor.
 
 ## Tapping, links and copying

docs/wiki/Multi-User-Mode.md

@@ -60,6 +60,36 @@ Admins see everything.
 Ownership threads through every list endpoint, the session lookup helper, the WebSocket
 layer, and file previews. A user cannot address another user's session even by id.
 
+## Server-wide settings are admin only
+
+There is one set of server settings (`~/.codeman/settings.json`) for everyone: the feature
+switches, the run mode, respawn presets, the case order, the Cloudflare tunnel, the default
+models. Every user can **read** them, but only an **admin** can change them. For a regular
+user the settings write routes answer `403 FORBIDDEN` (see the
+[HTTP API](HTTP-API) and [`docs/api-reference.md`](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md)).
+A regular user reads them without what is the admin's: the Deepgram key an admin saved for
+voice dictation, and the admin's case names (case order, last used case).
+
+In the browser this means:
+
+- **App Settings → Save** still keeps a regular user's per-device settings (skin, fonts,
+  header buttons, keyboard bar and the rest of the per-device keys) on that device. If they
+  also changed a server-wide setting, one notice says it can only be changed by an admin,
+  and the setting keeps the server's value.
+- A regular user's run-mode pick and respawn presets are their own: kept in that browser
+  under their name, not sent to the server, and still theirs on the next visit (over what
+  an admin set). Their last used case is not recorded server-wide.
+- Reordering cases and switching the tunnel on or off are admin actions.
+- If the page could not tell yet who is signed in (a slow or failed sign-in check), the
+  server's refusal is read the same way: the same notice, and nothing more is sent.
+
+The operations that act on the whole server are admin actions too: updating Codeman,
+opening the multi-display window, regenerating the tunnel QR code (it clears every user's
+pending QR login) and cleaning up stale session state. **Revoke All** signs a regular user
+out of their own logins only, and the tunnel panel lists only their own.
+
+Per-user server settings are not part of this version.
+
 ## Safer defaults for regular users
 
 Non-admins get tighter defaults, and lifting them is an explicit per-user grant:

docs/wiki/Settings-Reference.md

@@ -29,6 +29,10 @@ The practical rule: **appearance and input are per device, behaviour is shared.*
 did not follow you, it is in one of the first two rows, and you change it again on that
 device.
 
+In [Multi-User Mode](Multi-User-Mode) the server's settings are shared by every user, so
+only an **admin** can change them. A regular user's **Save** keeps their per-device settings
+as usual and tells them that server-wide settings can only be changed by an admin.
+
 ## App Settings
 
 ### Updates
@@ -146,7 +150,7 @@ instead of its native cloud backend. See [Custom Model Endpoints](Custom-Model-E
 | Allowed Tools                    | The list used by the explicit mode.                                                            |
 | Ralph / Todo Tracker             | Enables the Ralph loop surfaces.                                                               |
 | Agent Teams                      | Experimental teams. Also needs the CLI's own environment flag.                                 |
-| Codeman Agent Skill              | Under **All agent CLIs**. Injects the agent skill into each new session's case, where that session's CLI looks for skills (every CLI except Pi and a plain shell). Off by default. See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent). |
+| Codeman Agent Skill              | Under **All agent CLIs**. Injects the agent skill into each new session's case, where that session's CLI looks for skills (every CLI except Pi and a plain shell). Off by default. See [The Codeman Skill](Codeman-Skill). |
 | Remote auto-reconnect            | Reattaches dropped remote SSH sessions. On by default.                                         |
 | Nice priority / value            | Runs agent processes at a lower CPU priority.                                                  |
 | Default Codex model              | Model for new local Codex sessions; empty uses Codex's own config. Letters, digits, `.` `_` `-` `/` only. |
@@ -217,7 +221,7 @@ Some things are configured before the server starts, not in the UI:
 | `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK` | Acknowledges exposing the server with no password.                  |
 | `CODEMAN_BASE_URL`                  | Mounts Codeman under a sub-path behind a reverse proxy that forwards the prefix unchanged. See [Remote Access](Remote-Access). |
 | `CODEMAN_MAX_DOWNLOAD_BYTES`        | Cap on raw file bodies and downloads. 2 GB by default, `0` for none.    |
-| `CODEMAN_MAX_PASTE_IMAGE_BYTES`     | Cap on one pasted, dropped or attached image. 50 MB by default.         |
+| `CODEMAN_MAX_PASTE_IMAGE_BYTES`     | Cap on one pasted, dropped or attached image or document. 50 MB by default. |
 | `CODEMAN_MAX_PASTE_VIDEO_BYTES`     | Cap on one attached video (phone Attach, drop). 1 GB by default; videos stream to disk, so this bounds disk use, not memory. |
 | `CODEMAN_MAX_REMOTE_FILE_SSH`       | Concurrent ssh reads for files in remote cases. 4 by default.           |
 | `CODEMAN_PATH_PROBE_TIMEOUT_MS`     | How long a linked case's folder may take to answer before it is shown as unreachable. 1500 ms by default; raise it for a slow but healthy mount. |

docs/wiki/Working-With-Files.md

@@ -168,17 +168,39 @@ blocks sensitive trees. In multi-user mode a non-admin gets only their own user
 root, because per-user spaces live inside the home directory and a home-directory root would
 expose everyone.
 
-## Images into a session
+## Files into a session
 
-Paste from the clipboard or drag and drop straight onto the terminal. The image is written
+Paste from the clipboard or drag and drop straight onto the terminal. The file is written
 where the agent can read it and the reference is inserted into your prompt. On a phone, the
-toolbar's Attach button opens the camera or photo library, videos included, and puts the path
-on your prompt, where it behaves like text you typed; the Image button inside the Compose
-editor does the same into the editor. Dropping a video onto the terminal works the same way.
+toolbar's Attach button opens the camera, photo library or files, and puts the path on your
+prompt, where it behaves like text you typed; the Attach button inside the Compose editor
+does the same into the editor. Dropping a video or a document onto the terminal works the
+same way.
 
-HEIC images from an iPhone are converted to JPEG on the way in.
-Videos (mp4, webm, mov, m4v, ogv) are stored as recorded, up to 1 GB each by default
-(`CODEMAN_MAX_PASTE_VIDEO_BYTES`); they stream to disk rather than through server memory.
+Images (png, jpg, gif, webp, bmp, heic) are re-encoded on the device before they go up (a GIF
+goes as is, so it keeps its frames), and HEIC from an iPhone is converted to JPEG. Videos (mp4, webm, mov, m4v, ogv) are stored as recorded,
+up to 1 GB each by default (`CODEMAN_MAX_PASTE_VIDEO_BYTES`); they stream to disk rather than
+through server memory. Documents are the office formats (pdf, docx, pptx, xlsx, zip) and the
+text family (txt, md, csv, tsv, json, log, yaml, yml, xml). Each is checked on the way in,
+against its file signature for the binary formats and against its encoding for text (UTF-8,
+no NUL bytes), so a script renamed to `.pdf` is refused while a `.txt` can hold any text at
+all. Files with script or page extensions (sh, py, js, html) are not accepted, since a prompt
+upload is something for the agent to read, not something for Codeman to store and serve. A
+document keeps a trimmed copy of its original name, letters, digits, dot, dash and underscore
+with anything else turned into a dash, so `Q3 report.pdf` is findable as
+`paste-<time>-<id>-Q3-report.pdf`; a name made entirely of other characters saves without
+one. Uploads are refused for remote (SSH) sessions, whose working directory is on the other
+host.
+
+Uploads land in `.codeman-uploads/` inside the case, next to the code the agent is working
+on, because that is the one path a local agent and a Docker case (whose workspace is mounted
+at the same absolute path) both see the same way. The first upload writes a `.gitignore` of `*` into `.codeman-uploads/`, so the
+directory ignores itself and your repository never picks the files up, while your own ignore file is
+left alone; a `.gitignore` you already had there is never overwritten. Files older than seven
+days are swept hourly, and the directory goes when the last session of the case is closed (a
+session that is only detached keeps it). Earlier releases wrote to `.claude-images/`; that
+directory is still swept and cleaned up the same way for one release so a case in use before
+the move is not left with stray files.
 
 ## Generated artifacts
 

docs/wiki/_Sidebar.md

@@ -15,6 +15,7 @@
 - [Agent CLIs](Agent-CLIs)
 - [Custom Model Endpoints](Custom-Model-Endpoints)
 - [Working With Files](Working-With-Files)
+- [Git Worktrees](Git-Worktrees)
 - [Input And Voice](Input-And-Voice)
 - [Mobile Guide](Mobile-Guide)
 - [Keyboard Shortcuts](Keyboard-Shortcuts)
@@ -42,6 +43,7 @@
 
 **Automation**
 
+- [The Codeman Skill](Codeman-Skill)
 - [Driving It From An Agent](Driving-Codeman-From-An-Agent)
 - [HTTP API](HTTP-API)
 - [Hooks & Integrations](Hooks-And-Integrations)

package-lock.json

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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.41.1",
+  "version": "1.42.0",
   "description": "Self-hosted mission control for AI coding agents: run Claude Code, Codex, OpenCode, Gemini, DeepSeek, Grok and more 24/7 in tmux, from any device.",
   "mcpName": "io.github.Ark0N/codeman",
   "type": "module",
@@ -39,7 +39,7 @@
     "check:public-assets": "node scripts/check-public-assets.mjs",
     "capture:subagents": "node scripts/capture-subagent-screenshots.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && node scripts/sync-plugin.mjs && npm install --package-lock-only && node scripts/check-lockfile-sync.mjs",
+    "version-packages": "changeset version && node scripts/generate-whats-new.mjs && prettier --write src/web/public/whats-new.json && node scripts/sync-plugin.mjs && npm install --package-lock-only && node scripts/check-lockfile-sync.mjs",
     "check:lockfile": "node scripts/check-lockfile-sync.mjs",
     "check:plugin": "node scripts/sync-plugin.mjs --check && claude plugin validate --strict plugins/codeman && claude plugin validate --strict .claude-plugin/marketplace.json",
     "knip": "npx --yes knip@latest --config config/knip.json",

plugins/codeman/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codeman",
   "description": "Drive Codeman, the self-hosted session manager for AI coding agents, from inside a Claude Code session: spawn worker sessions, prompt them, wait for them, read their answers, clean up. Acts only inside a Codeman-managed session.",
-  "version": "1.41.1",
+  "version": "1.42.0",
   "author": {
     "name": "Ark0N",
     "url": "https://github.com/Ark0N"

plugins/codeman/skills/codeman/SKILL.md

@@ -70,7 +70,7 @@ 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.33.4 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.42.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 ```
 
 ⚠️ **Never spend a Bash call on this check alone.** §1's block opens with this same
@@ -98,8 +98,11 @@ 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.33.4$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
-# ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+grep -qs '^CODEMAN_PREAMBLE=1.42.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.42.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# Positional parameters are always written with braces, ${1} and never a bare dollar-digit: Claude Code
+# replaces a bare one in a skill body with the matching word of the skill's arguments, and §0 is pasted
+# from that body (test/agent-skill.test.ts pins it).
 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
@@ -108,7 +111,7 @@ SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # reads. The data dir is wherever the hook-secret file lives. Values may be
 # quoted or `export`-prefixed.
 ENV_FILE="${CODEMAN_HOOK_SECRET_FILE:+${CODEMAN_HOOK_SECRET_FILE%hook-secret}.env}"
-envval() { sed -n "s/^\(export \)\{0,1\}$1=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
+envval() { sed -n "s/^\(export \)\{0,1\}${1}=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
 if [ -z "${CODEMAN_PASSWORD:-}" ] && [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
   CODEMAN_USERNAME=$(envval CODEMAN_USERNAME)
   CODEMAN_PASSWORD=$(envval CODEMAN_PASSWORD)
@@ -143,15 +146,15 @@ delete_session() {
 
 # ---- fast path: the four verbs, already written. §1 composes them. ----
 _composer_up() {   # <sid> <timeoutMs> -> "true"/"false". `shift+tab` is the one token
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 _dsh_up() {        # <sid> <timeoutMs> -> "true"/"false". The DeepSeek Harness TUI's
   # composer glyph. Override with DSH_READY_MARK for a profile that draws another one.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 # ---- the workspace-trust dialog: READ the screen, never press Enter blind ----
 # Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights
@@ -167,7 +170,7 @@ _trust_key() {     # <sid> -> "confirm" | "move" | "" (nothing safe to press)
   # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that
   # is the current frame rather than every repaint since launch. tail -1 anyway,
   # because the freshest marked row is the only one still true.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
@@ -185,7 +188,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   # the LAST `❯` line: Claude Code echoes a submitted prompt with the same glyph higher
   # up in the transcript, so only the last one says whether the text was taken.
   local t
-  t=$("${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  t=$("${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d '\r' | grep -a '^[[:space:]]*❯' | tail -1)
@@ -195,7 +198,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   printf '%s' "$t" | sed 's/^[[:space:]]*❯//' | tr -d '[:space:]' | sed "s/$(printf '\302\240')//g"
 }
 _accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could not
-  local sid="$1" k i=1
+  local sid="${1}" k i=1
   while [ "$i" -le 6 ]; do
     k=$(_trust_key "$sid")
     [ -n "$k" ] || return 1   # no dialog on screen, or a layout this cannot read
@@ -396,7 +399,7 @@ sendwait() {
 last_text() {
   local t="" prev="${2:-}"
   for _ in $(seq 1 15); do
-    t=$("${CURL[@]}" "$API/api/v1/sessions/$1/last-response" | jq -r '.data.text // empty')
+    t=$("${CURL[@]}" "$API/api/v1/sessions/${1}/last-response" | jq -r '.data.text // empty')
     [ -n "$t" ] && [ "$t" != "$prev" ] && { printf '%s\n' "$t"; return 0; }
     sleep 1
   done
@@ -407,10 +410,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.33.4
+CODEMAN_PREAMBLE=1.42.0
 PREAMBLE
 )
-. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
+. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.42.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
@@ -461,7 +464,7 @@ 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.33.4 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.42.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
                                   # (a name may carry a mode: `beta:deepseek`, see below)
 T=('reply with one line: the absolute path of your working directory'

plugins/codeman/skills/codeman/preamble.sh

@@ -1,4 +1,7 @@
-# ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# ---- Codeman agent preamble 1.42.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# Positional parameters are always written with braces, ${1} and never a bare dollar-digit: Claude Code
+# replaces a bare one in a skill body with the matching word of the skill's arguments, and §0 is pasted
+# from that body (test/agent-skill.test.ts pins it).
 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
@@ -7,7 +10,7 @@ SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # reads. The data dir is wherever the hook-secret file lives. Values may be
 # quoted or `export`-prefixed.
 ENV_FILE="${CODEMAN_HOOK_SECRET_FILE:+${CODEMAN_HOOK_SECRET_FILE%hook-secret}.env}"
-envval() { sed -n "s/^\(export \)\{0,1\}$1=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
+envval() { sed -n "s/^\(export \)\{0,1\}${1}=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
 if [ -z "${CODEMAN_PASSWORD:-}" ] && [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
   CODEMAN_USERNAME=$(envval CODEMAN_USERNAME)
   CODEMAN_PASSWORD=$(envval CODEMAN_PASSWORD)
@@ -42,15 +45,15 @@ delete_session() {
 
 # ---- fast path: the four verbs, already written. §1 composes them. ----
 _composer_up() {   # <sid> <timeoutMs> -> "true"/"false". `shift+tab` is the one token
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 _dsh_up() {        # <sid> <timeoutMs> -> "true"/"false". The DeepSeek Harness TUI's
   # composer glyph. Override with DSH_READY_MARK for a profile that draws another one.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 # ---- the workspace-trust dialog: READ the screen, never press Enter blind ----
 # Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights
@@ -66,7 +69,7 @@ _trust_key() {     # <sid> -> "confirm" | "move" | "" (nothing safe to press)
   # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that
   # is the current frame rather than every repaint since launch. tail -1 anyway,
   # because the freshest marked row is the only one still true.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
@@ -84,7 +87,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   # the LAST `❯` line: Claude Code echoes a submitted prompt with the same glyph higher
   # up in the transcript, so only the last one says whether the text was taken.
   local t
-  t=$("${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  t=$("${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d '\r' | grep -a '^[[:space:]]*❯' | tail -1)
@@ -94,7 +97,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   printf '%s' "$t" | sed 's/^[[:space:]]*❯//' | tr -d '[:space:]' | sed "s/$(printf '\302\240')//g"
 }
 _accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could not
-  local sid="$1" k i=1
+  local sid="${1}" k i=1
   while [ "$i" -le 6 ]; do
     k=$(_trust_key "$sid")
     [ -n "$k" ] || return 1   # no dialog on screen, or a layout this cannot read
@@ -295,7 +298,7 @@ sendwait() {
 last_text() {
   local t="" prev="${2:-}"
   for _ in $(seq 1 15); do
-    t=$("${CURL[@]}" "$API/api/v1/sessions/$1/last-response" | jq -r '.data.text // empty')
+    t=$("${CURL[@]}" "$API/api/v1/sessions/${1}/last-response" | jq -r '.data.text // empty')
     [ -n "$t" ] && [ "$t" != "$prev" ] && { printf '%s\n' "$t"; return 0; }
     sleep 1
   done
@@ -306,4 +309,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.33.4
+CODEMAN_PREAMBLE=1.42.0

plugins/codeman/skills/codeman/reference/recipes.md

@@ -21,7 +21,7 @@ by sourcing the preamble file the §0 bootstrap wrote, and checking its version
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null
-[ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.42.0 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
 ```
 
 Do **not** re-paste the preamble body into each call. Sourcing it is what retires the

scripts/generate-whats-new.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Writes src/web/public/whats-new.json for the version in package.json from CHANGELOG.md.
+// Runs as part of `npm run version-packages`, so every release carries its own notes and the
+// UI can announce them once per version without anyone remembering to.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildWhatsNew } from './lib/whats-new.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const { version } = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+const changelog = readFileSync(resolve(root, 'CHANGELOG.md'), 'utf8');
+const notes = buildWhatsNew(changelog, version);
+if (notes.highlights.length === 0) {
+  console.warn(`whats-new: no bold highlights found for ${version}; the in-app announcement will be skipped`);
+}
+writeFileSync(resolve(root, 'src/web/public/whats-new.json'), JSON.stringify(notes, null, 2) + '\n');
+console.log(`whats-new: ${version} -> ${notes.highlights.length} highlight(s)`);

scripts/lib/whats-new.mjs

@@ -0,0 +1,42 @@
+/**
+ * Pulls the headline of each change out of one version's section of CHANGELOG.md.
+ *
+ * Release notes here lead each change with a bold phrase ("**Tab layouts (#538, optional).** ..."),
+ * so a highlight is that phrase. The Thanks block is credit, not a feature.
+ */
+
+const MAX_HIGHLIGHTS = 8;
+
+/** The text between `## <version>` and the next `## ` heading, or '' when absent. */
+export function versionSection(changelog, version) {
+  const lines = changelog.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === `## ${version}`);
+  if (start === -1) return '';
+  let end = lines.findIndex((l, i) => i > start && /^## /.test(l));
+  if (end === -1) end = lines.length;
+  return lines.slice(start + 1, end).join('\n');
+}
+
+// Bold phrases the release notes use as group labels rather than as the headline of a change:
+// "**Fixes.**" heads the list of fixes, "**Fixes applied while landing.**" the review fixes.
+const SECTION_LABELS =
+  /^(?:thanks\b.*|fixes|fixes applied while landing|docs|docs and tests|new features|also in this release)$/i;
+
+/** Bold lead-ins at the start of a paragraph or bullet, cleaned for display. */
+export function extractHighlights(section) {
+  const out = [];
+  for (const line of section.split('\n')) {
+    // `changeset version` prefixes the first line of a committed changeset with its commit
+    // ("- d18deed: **Lead.** text"), which is the shape every changesets-bot release has.
+    const m = /^\s*(?:[-*]\s+)?(?:[0-9a-f]{7,40}:\s+)?\*\*([^*]{3,120})\*\*/.exec(line);
+    if (!m) continue;
+    const text = m[1].replace(/[\s.:]+$/, '').trim();
+    if (!text || SECTION_LABELS.test(text)) continue;
+    if (!out.includes(text)) out.push(text);
+  }
+  return out.slice(0, MAX_HIGHLIGHTS);
+}
+
+export function buildWhatsNew(changelog, version) {
+  return { version, highlights: extractHighlights(versionSection(changelog, version)) };
+}

skills/codeman/SKILL.md

@@ -70,7 +70,7 @@ 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.33.4 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.42.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 ```
 
 ⚠️ **Never spend a Bash call on this check alone.** §1's block opens with this same
@@ -98,8 +98,11 @@ 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.33.4$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
-# ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+grep -qs '^CODEMAN_PREAMBLE=1.42.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.42.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# Positional parameters are always written with braces, ${1} and never a bare dollar-digit: Claude Code
+# replaces a bare one in a skill body with the matching word of the skill's arguments, and §0 is pasted
+# from that body (test/agent-skill.test.ts pins it).
 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
@@ -108,7 +111,7 @@ SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # reads. The data dir is wherever the hook-secret file lives. Values may be
 # quoted or `export`-prefixed.
 ENV_FILE="${CODEMAN_HOOK_SECRET_FILE:+${CODEMAN_HOOK_SECRET_FILE%hook-secret}.env}"
-envval() { sed -n "s/^\(export \)\{0,1\}$1=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
+envval() { sed -n "s/^\(export \)\{0,1\}${1}=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
 if [ -z "${CODEMAN_PASSWORD:-}" ] && [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
   CODEMAN_USERNAME=$(envval CODEMAN_USERNAME)
   CODEMAN_PASSWORD=$(envval CODEMAN_PASSWORD)
@@ -143,15 +146,15 @@ delete_session() {
 
 # ---- fast path: the four verbs, already written. §1 composes them. ----
 _composer_up() {   # <sid> <timeoutMs> -> "true"/"false". `shift+tab` is the one token
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 _dsh_up() {        # <sid> <timeoutMs> -> "true"/"false". The DeepSeek Harness TUI's
   # composer glyph. Override with DSH_READY_MARK for a profile that draws another one.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 # ---- the workspace-trust dialog: READ the screen, never press Enter blind ----
 # Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights
@@ -167,7 +170,7 @@ _trust_key() {     # <sid> -> "confirm" | "move" | "" (nothing safe to press)
   # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that
   # is the current frame rather than every repaint since launch. tail -1 anyway,
   # because the freshest marked row is the only one still true.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
@@ -185,7 +188,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   # the LAST `❯` line: Claude Code echoes a submitted prompt with the same glyph higher
   # up in the transcript, so only the last one says whether the text was taken.
   local t
-  t=$("${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  t=$("${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d '\r' | grep -a '^[[:space:]]*❯' | tail -1)
@@ -195,7 +198,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   printf '%s' "$t" | sed 's/^[[:space:]]*❯//' | tr -d '[:space:]' | sed "s/$(printf '\302\240')//g"
 }
 _accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could not
-  local sid="$1" k i=1
+  local sid="${1}" k i=1
   while [ "$i" -le 6 ]; do
     k=$(_trust_key "$sid")
     [ -n "$k" ] || return 1   # no dialog on screen, or a layout this cannot read
@@ -396,7 +399,7 @@ sendwait() {
 last_text() {
   local t="" prev="${2:-}"
   for _ in $(seq 1 15); do
-    t=$("${CURL[@]}" "$API/api/v1/sessions/$1/last-response" | jq -r '.data.text // empty')
+    t=$("${CURL[@]}" "$API/api/v1/sessions/${1}/last-response" | jq -r '.data.text // empty')
     [ -n "$t" ] && [ "$t" != "$prev" ] && { printf '%s\n' "$t"; return 0; }
     sleep 1
   done
@@ -407,10 +410,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.33.4
+CODEMAN_PREAMBLE=1.42.0
 PREAMBLE
 )
-. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
+. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.42.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
@@ -461,7 +464,7 @@ 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.33.4 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.42.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
                                   # (a name may carry a mode: `beta:deepseek`, see below)
 T=('reply with one line: the absolute path of your working directory'

skills/codeman/preamble.sh

@@ -1,4 +1,7 @@
-# ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# ---- Codeman agent preamble 1.42.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# Positional parameters are always written with braces, ${1} and never a bare dollar-digit: Claude Code
+# replaces a bare one in a skill body with the matching word of the skill's arguments, and §0 is pasted
+# from that body (test/agent-skill.test.ts pins it).
 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
@@ -7,7 +10,7 @@ SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # reads. The data dir is wherever the hook-secret file lives. Values may be
 # quoted or `export`-prefixed.
 ENV_FILE="${CODEMAN_HOOK_SECRET_FILE:+${CODEMAN_HOOK_SECRET_FILE%hook-secret}.env}"
-envval() { sed -n "s/^\(export \)\{0,1\}$1=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
+envval() { sed -n "s/^\(export \)\{0,1\}${1}=//p" "$ENV_FILE" | tail -1 | sed 's/^"\(.*\)"$/\1/; s/^'\''\(.*\)'\''$/\1/'; }
 if [ -z "${CODEMAN_PASSWORD:-}" ] && [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then
   CODEMAN_USERNAME=$(envval CODEMAN_USERNAME)
   CODEMAN_PASSWORD=$(envval CODEMAN_PASSWORD)
@@ -42,15 +45,15 @@ delete_session() {
 
 # ---- fast path: the four verbs, already written. §1 composes them. ----
 _composer_up() {   # <sid> <timeoutMs> -> "true"/"false". `shift+tab` is the one token
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 _dsh_up() {        # <sid> <timeoutMs> -> "true"/"false". The DeepSeek Harness TUI's
   # composer glyph. Override with DSH_READY_MARK for a profile that draws another one.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/wait-output" \
     --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \
-    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+    --data-urlencode "timeout=${2}" | jq -r '.data.wait.matched // false'
 }
 # ---- the workspace-trust dialog: READ the screen, never press Enter blind ----
 # Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights
@@ -66,7 +69,7 @@ _trust_key() {     # <sid> -> "confirm" | "move" | "" (nothing safe to press)
   # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that
   # is the current frame rather than every repaint since launch. tail -1 anyway,
   # because the freshest marked row is the only one still true.
-  "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  "${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
@@ -84,7 +87,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   # the LAST `❯` line: Claude Code echoes a submitted prompt with the same glyph higher
   # up in the transcript, so only the last one says whether the text was taken.
   local t
-  t=$("${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+  t=$("${CURL[@]}" -G "$API/api/v1/sessions/${1}/terminal" --data-urlencode 'full=1' \
     | jq -r '.data.terminalBuffer // empty' \
     | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
     | tr -d '\r' | grep -a '^[[:space:]]*❯' | tail -1)
@@ -94,7 +97,7 @@ _composer_text() { # <sid> -> the composer's text with ALL whitespace removed: "
   printf '%s' "$t" | sed 's/^[[:space:]]*❯//' | tr -d '[:space:]' | sed "s/$(printf '\302\240')//g"
 }
 _accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could not
-  local sid="$1" k i=1
+  local sid="${1}" k i=1
   while [ "$i" -le 6 ]; do
     k=$(_trust_key "$sid")
     [ -n "$k" ] || return 1   # no dialog on screen, or a layout this cannot read
@@ -295,7 +298,7 @@ sendwait() {
 last_text() {
   local t="" prev="${2:-}"
   for _ in $(seq 1 15); do
-    t=$("${CURL[@]}" "$API/api/v1/sessions/$1/last-response" | jq -r '.data.text // empty')
+    t=$("${CURL[@]}" "$API/api/v1/sessions/${1}/last-response" | jq -r '.data.text // empty')
     [ -n "$t" ] && [ "$t" != "$prev" ] && { printf '%s\n' "$t"; return 0; }
     sleep 1
   done
@@ -306,4 +309,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.33.4
+CODEMAN_PREAMBLE=1.42.0

skills/codeman/reference/recipes.md

@@ -21,7 +21,7 @@ by sourcing the preamble file the §0 bootstrap wrote, and checking its version
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null
-[ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.42.0 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
 ```
 
 Do **not** re-paste the preamble body into each call. Sourcing it is what retires the

src/config/cli-registry/stock.ts

@@ -703,6 +703,8 @@ const CODEX: CliEntry = {
     //   (its notes field open)              `  tab or esc to clear notes | enter to submit answer`
     //   workspace trust, at startup         `› 1. Trust and continue`
     //                                       `  enter continue · esc quit`
+    //   (the same prompt reached after the  `  2. Back to Agent Command Center`
+    //   update prompt, 0.162.0, 2026-10-16) `  enter continue · esc back`
     // The pattern needs both: a `› N.` option row, then the key-hint row, which must END
     // the window. Below about 60 columns that hint wraps onto rows of its own
     // (`  Press enter to confirm or esc to` / `  cancel`, or `tab to add notes` /
@@ -725,7 +727,7 @@ const CODEX: CliEntry = {
       workingLine: '[Ee]sc to interrupt',
       watchingLine: String.raw`^\s{0,4}(\d+ background terminals?) running · /ps to view · /stop to close$`,
       watchingLines: 4,
-      blockedLine: String.raw`(?:^|\n) {0,4}› \d\. [\s\S]*\n {2}(?:Press enter to confirm|tab (?:to add|or esc to clear) notes|enter continue)(?:[^\n]|\n {2}(?=[a-z←])){0,120}(?:cancel|interrupt|quit|answer|all)$`,
+      blockedLine: String.raw`(?:^|\n) {0,4}› \d\. [\s\S]*\n {2}(?:Press enter to confirm|tab (?:to add|or esc to clear) notes|enter continue)(?:[^\n]|\n {2}(?=[a-z←])){0,120}(?:cancel|interrupt|quit|back|answer|all)$`,
       blockedLines: 20,
     },
     // The footer under the composer, measured on a live 0.147.0 pane:
@@ -1333,8 +1335,14 @@ const DEEPSEEK: CliEntry = {
     launcherTargetParam: 'profile',
     install: {
       command: {
-        linux: 'npm install -g @deepseek-ai/dsh',
-        darwin: 'npm install -g @deepseek-ai/dsh',
+        // pnpm rides along: `dsh plugin` spawns a literal `pnpm` with no npm fallback, so the
+        // terminal profile this CLI needs before it can run cannot be installed without it (#352).
+        // ⚠️ Only when none is on PATH. `corepack enable` puts a `pnpm` shim in node's own bin
+        // directory, which is npm's global bin for nvm and Homebrew, and `npm install -g pnpm`
+        // refuses to overwrite it (EEXIST). Asked for in the same command as dsh, that failure
+        // took dsh down with it, on exactly the machines that already had a working pnpm.
+        linux: 'npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)',
+        darwin: 'npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)',
       },
       npmPackage: '@deepseek-ai/dsh',
       docsUrl: 'https://github.com/deepseek-ai/deepseek-harness',

src/git-worktrees.ts

@@ -0,0 +1,953 @@
+/**
+ * @fileoverview Git worktrees for a LOCAL case: list, create and remove the worktrees a
+ * repository-backed case keeps under `<repo>/.claude/worktrees/<name>`, so several agents working
+ * on one repository each get their own working tree instead of sharing the case folder (sessions
+ * in one case share its folder, and two agents editing, building and committing in one checkout
+ * step on each other). Routes: `src/web/routes/worktree-routes.ts`; a session starts in one
+ * through the existing create paths (`POST /api/quick-start` with `worktree`, or
+ * `POST /api/sessions` with the worktree as `workingDir`).
+ *
+ * WHERE. `<repo>/.claude/worktrees/<name>` on a new branch `worktree-<name>` is Claude Code's own
+ * `--worktree` layout (measured in Claude Code 2.1.296: path `<repo>/.claude/worktrees/<name>`,
+ * branch `worktree-<name>`, names of letters, digits, `.`, `_`, `-`, at most 64 characters), and
+ * Codeman already recognizes it (the worktree pill, `CLAUDE_WORKTREE_PATH` in session-routes.ts).
+ * Names here are a strict subset of Claude's (one segment, starting with a letter or digit), so a
+ * worktree made here is one `claude --worktree <name>` would also find. The main checkout must not
+ * show the worktrees as untracked, so `/.claude/worktrees/` is appended to the repository's LOCAL
+ * `info/exclude` (in the real common git dir, never a tracked `.gitignore`) when git does not
+ * already ignore it. `/.claude/settings.local.json` gets the same treatment: Codeman installs its
+ * hooks there for every claude session, and an untracked copy in a worktree makes
+ * `git worktree remove` refuse forever (Claude Code itself ignores that file through the global
+ * excludes file, which is not guaranteed to be set up on a given machine). The copy of Codeman's
+ * agent skill (`<skills dir>/codeman/`, injected while `agentSkillEnabled` is on) is excluded for
+ * the same reason, for every skills folder the registry names (`WorktreeOptions.agentSkillDirs`).
+ *
+ * Split like the other git modules: a PURE half (name and branch validation, `worktree list`
+ * parsing, exclude text, the managed-path rule) unit-tested without git, and an IO half that
+ * spawns git through an injectable runner.
+ *
+ * Rules the code keeps and the tests pin:
+ *   - git is spawned with an argv array, never a shell, with `--` before every path operand, the
+ *     non-interactive environment of `gitNonInteractiveEnv()`, a timeout that kills the whole
+ *     process group, and capped output. Read-only calls add `--no-optional-locks`.
+ *   - Names and branches are validated BEFORE they reach git (charset, length, then
+ *     `git check-ref-format --branch`, whose answer must equal the input: `@{-1}` style shorthands
+ *     are refused up front, since `--branch` would expand them).
+ *   - Only `<repo>/.claude/worktrees/<valid-name>` is ever created or removed. Every component of
+ *     that path is `lstat`ed (a symlinked `.claude` or `worktrees` directory, or a symlink at the
+ *     worktree itself, is refused) and its real path must be exactly the expected one, so a
+ *     repository cannot redirect a create or a remove outside itself. What is left is a same-user
+ *     race (an agent swapping a directory between the check and git), which is accepted: that
+ *     agent already runs code as this user.
+ *   - Removal is `git worktree remove` WITHOUT `--force` (git refuses a tree with modified or
+ *     untracked files, and that refusal is the answer), refused while a live session runs inside
+ *     the worktree, and the optional branch delete is `git branch -d` (never `-D`, so an unmerged
+ *     branch survives).
+ *   - git never runs for a case at or inside a Docker case workspace (or whose common git dir is
+ *     there): a container could plant a checkout filter or a hook, and `git worktree add` runs the
+ *     repository's post-checkout hook and filters on the HOST. On a local case that is acceptable,
+ *     since the user's agent runs code there anyway. A managed worktree that is, sits inside, or
+ *     holds a Docker case workspace is never removed either: `git worktree remove` runs a status
+ *     inside the tree, then deletes it under the container.
+ *   - A repository that merely encloses the case and is the home folder or above (a dotfiles repo
+ *     in `$HOME`) is not the case's repository, and a case folder below a repository's top level
+ *     is refused: the worktrees would not be where the case is.
+ *
+ * @module git-worktrees
+ */
+
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { gitNonInteractiveEnv, isSafeGitRef, sanitizeGitOutput } from './git-clone.js';
+import { isInsideAny, isUnrelatedAncestor } from './git-workspace-status.js';
+
+// ─── Limits ──────────────────────────────────────────────────────────────────
+
+/** Claude Code's own limit for a `--worktree` name (2.1.296). */
+export const MAX_WORKTREE_NAME_LENGTH = 64;
+/** Longest accepted branch name. git allows more; 200 covers every real one. */
+export const MAX_WORKTREE_BRANCH_LENGTH = 200;
+/** A read-only git call (rev-parse, worktree list, check-ignore, check-ref-format). */
+export const WORKTREE_READ_TIMEOUT_MS = 15_000;
+/**
+ * `git worktree add` checks out a whole tree and runs the repository's post-checkout hook and
+ * smudge filters (Git LFS downloads objects there), so it gets the longest budget.
+ */
+export const WORKTREE_ADD_TIMEOUT_MS = 180_000;
+/** `git worktree remove` runs a status of the tree first, then deletes it. */
+export const WORKTREE_REMOVE_TIMEOUT_MS = 60_000;
+/** Captured stdout. `worktree list` is one short block per worktree. */
+const MAX_STDOUT_BYTES = 1_000_000;
+/** Captured stderr tail. */
+const MAX_STDERR_BYTES = 8_192;
+/** Worktrees listed. A repository with more is unusual; the count says when it was cut. */
+export const MAX_WORKTREES_LISTED = 200;
+
+/** Path segments of the managed worktrees folder, relative to the repository root. */
+export const WORKTREES_DIR_SEGMENTS = ['.claude', 'worktrees'] as const;
+/** The `info/exclude` line that hides the managed worktrees from the main checkout. */
+export const WORKTREES_EXCLUDE_LINE = '/.claude/worktrees/';
+/** The `info/exclude` line for the hooks file Codeman writes into every claude workspace. */
+export const SETTINGS_LOCAL_EXCLUDE_LINE = '/.claude/settings.local.json';
+
+/** A workspace-relative skills folder (`.claude/skills`, `.agents/skills`): plain segments only. */
+const SKILLS_DIR_RE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+
+/**
+ * The `info/exclude` line for the copy of Codeman's agent skill in `skillsDir` of a workspace
+ * (`<skillsDir>/codeman/`, written into the folder a session runs in while `agentSkillEnabled`
+ * is on), or null for a folder that is not a plain relative path.
+ */
+export function agentSkillExcludeLine(skillsDir: string): string | null {
+  if (!SKILLS_DIR_RE.test(skillsDir) || skillsDir.split('/').some((s) => s === '.' || s === '..')) return null;
+  return `/${skillsDir}/codeman/`;
+}
+
+// ─── Pure: names ─────────────────────────────────────────────────────────────
+
+const WORKTREE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const BRANCH_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+
+/**
+ * Why `name` cannot be a worktree name, or null when it can. One path segment of letters, digits,
+ * `.`, `_` and `-`, starting with a letter or digit, at most 64 characters, never `..` (the
+ * session path schema refuses any path containing it), and not ending in `.` or `.lock` (git's
+ * own ref rules, since the default branch is derived from the name).
+ */
+export function worktreeNameError(name: unknown): string | null {
+  if (typeof name !== 'string' || name.length === 0) return 'A worktree name is required.';
+  if (name.length > MAX_WORKTREE_NAME_LENGTH)
+    return `A worktree name is at most ${MAX_WORKTREE_NAME_LENGTH} characters.`;
+  if (!WORKTREE_NAME_RE.test(name))
+    return 'A worktree name may contain only letters, digits, ".", "_" and "-", and must start with a letter or digit.';
+  if (name.includes('..')) return 'A worktree name may not contain "..".';
+  if (name.endsWith('.') || name.toLowerCase().endsWith('.lock'))
+    return 'A worktree name may not end with "." or ".lock".';
+  return null;
+}
+
+/** The branch a new worktree gets when the caller names none: Claude Code's `worktree-<name>`. */
+export function defaultWorktreeBranch(name: string): string {
+  return `worktree-${name}`;
+}
+
+/**
+ * Why `branch` cannot be a new branch name, or null when it passes the charset gate. The final
+ * word is `git check-ref-format --branch` (see `createCaseWorktree`); this gate exists so nothing
+ * option-shaped, `@{...}`-shaped or otherwise surprising ever reaches git at all.
+ */
+export function worktreeBranchError(branch: unknown): string | null {
+  if (typeof branch !== 'string' || branch.length === 0) return 'A branch name is required.';
+  if (branch.length > MAX_WORKTREE_BRANCH_LENGTH)
+    return `A branch name is at most ${MAX_WORKTREE_BRANCH_LENGTH} characters.`;
+  if (!BRANCH_NAME_RE.test(branch))
+    return 'A branch name may contain only letters, digits, ".", "_", "-" and "/", and must start with a letter or digit.';
+  if (branch.includes('..') || branch.includes('//')) return 'A branch name may not contain ".." or "//".';
+  if (branch.endsWith('/') || branch.endsWith('.') || branch.toLowerCase().endsWith('.lock'))
+    return 'A branch name may not end with "/", "." or ".lock".';
+  if (branch.split('/').some((part) => part.startsWith('.'))) return 'No part of a branch name may start with ".".';
+  return null;
+}
+
+/** Why `base` cannot be a start point, or null. The same gate Clone Repo uses for a ref. */
+export function worktreeBaseError(base: unknown): string | null {
+  if (typeof base !== 'string' || !isSafeGitRef(base))
+    return 'The base must be a branch, tag or commit (letters, digits, ".", "_", "-", "/" and "+").';
+  return null;
+}
+
+// ─── Pure: paths ─────────────────────────────────────────────────────────────
+
+/** `<repo>/.claude/worktrees`. */
+export function managedWorktreesDir(repoRoot: string): string {
+  return join(repoRoot, ...WORKTREES_DIR_SEGMENTS);
+}
+
+/** `<repo>/.claude/worktrees/<name>`. The caller validates `name` first. */
+export function managedWorktreePath(repoRoot: string, name: string): string {
+  return join(managedWorktreesDir(repoRoot), name);
+}
+
+/**
+ * The managed worktree name of `path`, or null when it is not exactly
+ * `<repoRoot>/.claude/worktrees/<valid-name>`. Lexical: both sides must already be real paths.
+ */
+export function managedWorktreeName(repoRoot: string, path: string): string | null {
+  const dir = managedWorktreesDir(repoRoot) + sep;
+  const clean = path.endsWith(sep) && path.length > 1 ? path.slice(0, -1) : path;
+  if (!clean.startsWith(dir)) return null;
+  const name = clean.slice(dir.length);
+  if (!name || name.includes(sep)) return null;
+  return worktreeNameError(name) === null ? name : null;
+}
+
+/** True when `child` is `root` or inside it (lexical, on resolved paths). */
+export function isPathWithin(child: string, root: string): boolean {
+  const c = resolve(child);
+  const r = resolve(root);
+  return c === r || c.startsWith(r === sep ? r : r + sep);
+}
+
+/**
+ * `path` as the repository spells it: a path under `alias` (the case folder as its case resolves
+ * it, which can run through a symlink) moved under `root` (the repository's real top level), else
+ * `path` unchanged. Lexical, so it costs no filesystem call per session. Sessions keep the
+ * `workingDir` they were created with, while the worktree paths git lists are real, so without
+ * this a session spelled through the case's link counted for no worktree and did not block its
+ * removal.
+ */
+export function respellUnder(path: string, alias: string, root: string): string {
+  const p = resolve(path);
+  const a = resolve(alias);
+  if (a === resolve(root) || !isPathWithin(p, a)) return p;
+  return join(root, p.slice(a.length));
+}
+
+// ─── Pure: `git worktree list --porcelain` ───────────────────────────────────
+
+export interface ParsedWorktree {
+  path: string;
+  /** Commit checked out (absent for a bare entry). */
+  head: string | null;
+  /** Short branch name (`refs/heads/` stripped), null when detached or bare. */
+  branch: string | null;
+  detached: boolean;
+  bare: boolean;
+  locked: boolean;
+  lockReason?: string;
+  prunable: boolean;
+  prunableReason?: string;
+}
+
+/**
+ * Undo git's C-style path quoting (`"a\\"b\\303\\251"` → `a"bé`). Paths are printed quoted when
+ * they hold a `"`, a `\` or a control character even with `core.quotePath=false`; octal escapes are
+ * raw bytes, decoded as UTF-8. Text that is not quoted comes back unchanged.
+ */
+export function unquoteGitPath(text: string): string {
+  if (text.length < 2 || !text.startsWith('"') || !text.endsWith('"')) return text;
+  const body = text.slice(1, -1);
+  const bytes: number[] = [];
+  const simple: Record<string, number> = { a: 7, b: 8, f: 12, n: 10, r: 13, t: 9, v: 11, '"': 34, '\\': 92 };
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch !== '\\') {
+      for (const b of Buffer.from(ch, 'utf-8')) bytes.push(b);
+      continue;
+    }
+    const next = body[i + 1];
+    if (next !== undefined && /[0-7]/.test(next)) {
+      const oct = /^[0-7]{1,3}/.exec(body.slice(i + 1))![0];
+      bytes.push(parseInt(oct, 8) & 0xff);
+      i += oct.length;
+    } else if (next !== undefined && next in simple) {
+      bytes.push(simple[next]);
+      i += 1;
+    } else {
+      bytes.push(92);
+    }
+  }
+  return Buffer.from(bytes).toString('utf-8');
+}
+
+/**
+ * Parse `git worktree list --porcelain` (newline-terminated form: `-z` needs git 2.36, and Ubuntu
+ * 22.04 ships 2.34). Records are separated by blank lines; the first is the main worktree. Paths
+ * are read through `unquoteGitPath`, which together with `-c core.quotePath=false` keeps non-ASCII
+ * repository paths readable.
+ */
+export function parseWorktreeList(text: string): ParsedWorktree[] {
+  const out: ParsedWorktree[] = [];
+  let cur: ParsedWorktree | null = null;
+  const flush = () => {
+    if (cur) out.push(cur);
+    cur = null;
+  };
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (!line) {
+      flush();
+      continue;
+    }
+    const space = line.indexOf(' ');
+    const key = space === -1 ? line : line.slice(0, space);
+    const value = space === -1 ? '' : line.slice(space + 1);
+    if (key === 'worktree') {
+      flush();
+      cur = {
+        path: unquoteGitPath(value),
+        head: null,
+        branch: null,
+        detached: false,
+        bare: false,
+        locked: false,
+        prunable: false,
+      };
+      continue;
+    }
+    if (!cur) continue;
+    const entry: ParsedWorktree = cur;
+    if (key === 'HEAD') entry.head = value || null;
+    else if (key === 'branch') entry.branch = value.startsWith('refs/heads/') ? value.slice(11) : value || null;
+    else if (key === 'detached') entry.detached = true;
+    else if (key === 'bare') entry.bare = true;
+    else if (key === 'locked') {
+      entry.locked = true;
+      if (value) entry.lockReason = value;
+    } else if (key === 'prunable') {
+      entry.prunable = true;
+      if (value) entry.prunableReason = value;
+    }
+  }
+  flush();
+  return out;
+}
+
+// ─── Pure: exclude file ──────────────────────────────────────────────────────
+
+/**
+ * What to append to an `info/exclude` holding `existing` so that every line of `lines` is in it:
+ * the text ('' when nothing is missing) and the lines it adds. A file that does not end in a
+ * newline gets one first, so an appended pattern never fuses with the user's last line.
+ */
+export function excludeAppendText(existing: string, lines: readonly string[]): { text: string; added: string[] } {
+  const present = new Set(existing.split(/\r?\n/).map((l) => l.trim()));
+  const added = lines.filter((l) => !present.has(l));
+  if (added.length === 0) return { text: '', added };
+  const lead = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  return {
+    text: `${lead}# Added by Codeman: git worktrees and the files Codeman writes into each workspace stay local\n${added.join('\n')}\n`,
+    added,
+  };
+}
+
+// ─── Pure: git's answers ─────────────────────────────────────────────────────
+
+/**
+ * The part of git's stderr a user should see: its `fatal:`/`error:` lines (with any `hint:` lines
+ * dropped, they repeat what the UI says), sanitized and capped. Shown through `textContent` only.
+ */
+export function gitRefusalText(stderr: string): string {
+  const clean = sanitizeGitOutput(stderr, 2000);
+  const lines = clean
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !/^hint:/i.test(l));
+  const diagnostic = lines.filter((l) => /^(fatal|error|warning):/i.test(l));
+  const text = (diagnostic.length ? diagnostic : lines).join('\n');
+  return text.length > 1000 ? `${text.slice(0, 1000)}…` : text;
+}
+
+// ─── IO: git runner ──────────────────────────────────────────────────────────
+
+export interface WorktreeGitResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  spawnError?: string;
+}
+
+/** Runs `git <args>` in `cwd`; never throws. Injected so tests can refuse to run git at all. */
+export type WorktreeGitRunner = (
+  cwd: string,
+  args: string[],
+  opts?: { timeoutMs?: number }
+) => Promise<WorktreeGitResult>;
+
+/**
+ * Global options for a call that only reads: no optional index refresh, no filesystem monitor,
+ * no path quoting of non-ASCII names. Must precede the subcommand.
+ */
+const READ_ONLY_GIT_OPTIONS = ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.quotePath=false'];
+
+/**
+ * The production runner: argv only (no shell), the non-interactive environment, captured output
+ * caps, and a timeout that signals the whole process group (`detached: true`), because
+ * `git worktree add` fans out into checkout children, hooks and filters that a signal to the
+ * parent alone would leave running.
+ */
+export const runWorktreeGit: WorktreeGitRunner = (cwd, args, opts) =>
+  new Promise<WorktreeGitResult>((resolveRun) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn('git', args, {
+        cwd,
+        env: { ...gitNonInteractiveEnv(), GIT_OPTIONAL_LOCKS: '0' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true,
+      });
+    } catch (err) {
+      resolveRun({ code: null, stdout: '', stderr: '', timedOut: false, spawnError: String(err) });
+      return;
+    }
+    let stdout = '';
+    let stdoutBytes = 0;
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+    const killTree = (signal: NodeJS.Signals) => {
+      try {
+        if (child.pid) process.kill(-child.pid, signal);
+      } catch {
+        try {
+          child.kill(signal);
+        } catch {
+          /* already gone */
+        }
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree('SIGTERM');
+      killTimer = setTimeout(() => killTree('SIGKILL'), 3_000);
+    }, opts?.timeoutMs ?? WORKTREE_READ_TIMEOUT_MS);
+    child.stdout?.on('data', (chunk: Buffer) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes <= MAX_STDOUT_BYTES) stdout += chunk.toString('utf-8');
+    });
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString('utf-8');
+      if (stderr.length > MAX_STDERR_BYTES * 2) stderr = stderr.slice(-MAX_STDERR_BYTES);
+    });
+    const finish = (result: WorktreeGitResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolveRun(result);
+    };
+    child.on('error', (err) => finish({ code: null, stdout, stderr, timedOut, spawnError: String(err) }));
+    child.on('close', (code) => finish({ code, stdout, stderr, timedOut }));
+  });
+
+// ─── IO: results ─────────────────────────────────────────────────────────────
+
+/** Failure codes, named after the API error codes the routes map them to. */
+export type WorktreeFailureCode = 'INVALID_INPUT' | 'NOT_FOUND' | 'ALREADY_EXISTS' | 'CONFLICT' | 'OPERATION_FAILED';
+
+export interface WorktreeFailure {
+  ok: false;
+  code: WorktreeFailureCode;
+  message: string;
+  /** git's own words, when git refused (sanitized; render as text). */
+  gitMessage?: string;
+}
+
+const fail = (code: WorktreeFailureCode, message: string, gitMessage?: string): WorktreeFailure => ({
+  ok: false,
+  code,
+  message,
+  ...(gitMessage ? { gitMessage } : {}),
+});
+
+function gitFailure(run: WorktreeGitResult, what: string): WorktreeFailure {
+  if (run.spawnError && /enoent/i.test(run.spawnError))
+    return fail('OPERATION_FAILED', 'git is not installed on this machine (or not on the server’s PATH).');
+  if (run.timedOut) return fail('OPERATION_FAILED', `git timed out while ${what}.`);
+  const text = gitRefusalText(run.stderr);
+  return fail('OPERATION_FAILED', text ? `git failed while ${what}: ${text}` : `git failed while ${what}.`, text);
+}
+
+// ─── IO: the case's repository ───────────────────────────────────────────────
+
+export interface CaseRepository {
+  /** The repository's top level, which is the case folder (real path). */
+  repoRoot: string;
+  /** The real common git dir (`.git` of the main checkout), where `info/exclude` lives. */
+  commonDir: string;
+}
+
+export interface WorktreeOptions {
+  git?: WorktreeGitRunner;
+  /** Host paths of every Docker case workspace: git never runs at or inside one. */
+  dockerWorkspaces?: string[];
+  /** Overrides `os.homedir()` for the unrelated-ancestor rule (tests). */
+  home?: string;
+  /**
+   * Every workspace skills folder a session can get Codeman's agent skill in (the registry's
+   * `capabilities.agentSkillDir` values, passed in as data by the caller). A create excludes
+   * `<dir>/codeman/` for each, like the hooks file: a session in a worktree gets an untracked
+   * copy there, and `git worktree remove` would refuse that worktree forever.
+   */
+  agentSkillDirs?: readonly string[];
+}
+
+const realOr = async (p: string): Promise<string> => {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return resolve(p);
+  }
+};
+
+const DOCKER_REFUSAL =
+  'Worktrees are not available for a folder inside a Docker case workspace: a container can write there, and git would run its hooks and filters on this machine.';
+
+const DOCKER_WORKTREE_REFUSAL =
+  'This worktree is, or holds, a Docker case workspace: git would run inside a folder a container can write, and removing it would delete that workspace. Remove the Docker case first.';
+
+/**
+ * The repository a case folder IS, or why it is not one Codeman makes worktrees for. Never runs
+ * git when the folder (or the repository's common git dir) is at or inside a Docker case workspace.
+ */
+export async function resolveCaseRepository(
+  casePath: string,
+  opts: WorktreeOptions = {}
+): Promise<{ ok: true; repo: CaseRepository } | WorktreeFailure> {
+  const git = opts.git ?? runWorktreeGit;
+  const dockerRoots = await Promise.all((opts.dockerWorkspaces ?? []).filter(Boolean).map(realOr));
+  if (await isInsideAny(casePath, dockerRoots)) return fail('INVALID_INPUT', DOCKER_REFUSAL);
+
+  const run = await git(casePath, [...READ_ONLY_GIT_OPTIONS, 'rev-parse', '--show-toplevel', '--git-common-dir'], {
+    timeoutMs: WORKTREE_READ_TIMEOUT_MS,
+  });
+  if (run.code !== 0 || run.spawnError || run.timedOut) {
+    if (/must be run in a work tree/i.test(run.stderr)) {
+      return fail('INVALID_INPUT', 'This case folder is a bare git repository, which has no work tree to branch from.');
+    }
+    if (/not a git repository/i.test(run.stderr)) {
+      return fail('INVALID_INPUT', 'This case folder is not a git repository.');
+    }
+    return gitFailure(run, 'reading the repository');
+  }
+  const [top, common] = run.stdout.split('\n').map((l) => l.trim());
+  if (!top || !common) return fail('OPERATION_FAILED', 'git did not report the repository root.');
+  const [repoRoot, caseReal] = await Promise.all([realOr(top), realOr(casePath)]);
+  const commonDir = await realOr(resolve(casePath, common));
+  if (await isInsideAny(commonDir, dockerRoots)) return fail('INVALID_INPUT', DOCKER_REFUSAL);
+  if (repoRoot !== caseReal) {
+    if (await isUnrelatedAncestor(repoRoot, caseReal, opts.home ?? homedir())) {
+      return fail('INVALID_INPUT', 'This case folder is not a git repository.');
+    }
+    return fail(
+      'INVALID_INPUT',
+      `Worktrees need the case folder to be the top of a git repository; this folder is inside ${repoRoot}.`
+    );
+  }
+  return { ok: true, repo: { repoRoot, commonDir } };
+}
+
+// ─── IO: listing ─────────────────────────────────────────────────────────────
+
+export interface CaseWorktree extends ParsedWorktree {
+  /** The repository's main checkout (git lists it first). */
+  main: boolean;
+  /** The case folder itself (the main checkout, or a linked worktree linked as the case). */
+  isCase: boolean;
+  /** Under `<repo>/.claude/worktrees/<valid-name>`: Codeman may start sessions in it and remove it. */
+  managed: boolean;
+  /** The managed name, when `managed`. */
+  name?: string;
+}
+
+export async function listCaseWorktrees(
+  repo: CaseRepository,
+  opts: WorktreeOptions = {}
+): Promise<{ ok: true; worktrees: CaseWorktree[]; truncated: boolean } | WorktreeFailure> {
+  const git = opts.git ?? runWorktreeGit;
+  const run = await git(repo.repoRoot, [...READ_ONLY_GIT_OPTIONS, 'worktree', 'list', '--porcelain'], {
+    timeoutMs: WORKTREE_READ_TIMEOUT_MS,
+  });
+  if (run.code !== 0 || run.spawnError || run.timedOut) return gitFailure(run, 'listing worktrees');
+  const parsed = parseWorktreeList(run.stdout);
+  const truncated = parsed.length > MAX_WORKTREES_LISTED;
+  const worktrees = parsed.slice(0, MAX_WORKTREES_LISTED).map((wt, index): CaseWorktree => {
+    const name = index === 0 ? null : managedWorktreeName(repo.repoRoot, wt.path);
+    return {
+      ...wt,
+      main: index === 0,
+      isCase: wt.path === repo.repoRoot,
+      managed: name !== null,
+      ...(name ? { name } : {}),
+    };
+  });
+  return { ok: true, worktrees, truncated };
+}
+
+// ─── IO: path guards ─────────────────────────────────────────────────────────
+
+type DirState = 'dir' | 'absent' | 'symlink' | 'other';
+
+async function lstatState(path: string): Promise<DirState> {
+  try {
+    const st = await fs.lstat(path);
+    if (st.isSymbolicLink()) return 'symlink';
+    return st.isDirectory() ? 'dir' : 'other';
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return 'absent';
+    throw err;
+  }
+}
+
+/**
+ * Make sure `<repo>/.claude` and `<repo>/.claude/worktrees` are real directories (created when
+ * absent, refused when a symlink or a file) whose real path is exactly the lexical one.
+ */
+async function prepareWorktreesDir(repoRoot: string): Promise<{ ok: true; dir: string } | WorktreeFailure> {
+  let cur = repoRoot;
+  for (const segment of WORKTREES_DIR_SEGMENTS) {
+    cur = join(cur, segment);
+    const state = await lstatState(cur);
+    if (state === 'symlink') {
+      return fail(
+        'INVALID_INPUT',
+        `${cur} is a symlink. Codeman will not create worktrees through a link that could point outside the repository.`
+      );
+    }
+    if (state === 'other') return fail('INVALID_INPUT', `${cur} exists and is not a directory.`);
+    if (state === 'absent') {
+      try {
+        await fs.mkdir(cur);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
+          return fail('OPERATION_FAILED', `Could not create ${cur}: ${(err as Error).message}`);
+        }
+        if ((await lstatState(cur)) !== 'dir') return fail('INVALID_INPUT', `${cur} is not a plain directory.`);
+      }
+    }
+  }
+  if ((await realOr(cur)) !== cur) {
+    return fail('INVALID_INPUT', `${cur} does not resolve to itself; refusing to create a worktree there.`);
+  }
+  return { ok: true, dir: cur };
+}
+
+/**
+ * The managed worktree `name` of `repo` as it is on disk now: every component a real directory
+ * (no symlinks), the real path the expected one, and git listing it as a worktree of this
+ * repository. Used by removal and by starting a session in it.
+ *
+ * `allowMissing` (removal only, never a session start) also accepts a worktree whose folder is
+ * GONE (deleted by hand, or by an agent) while git still lists it, as prunable, at exactly the
+ * managed path: no component on the way may be a symlink or a file, and `missing` says so.
+ * Without it such a worktree was a dead end: it could not be removed, and its name could not be
+ * used again (the branch exists, then git refuses "a missing but already registered worktree").
+ */
+export async function resolveManagedWorktree(
+  repo: CaseRepository,
+  name: string,
+  opts: WorktreeOptions & { allowMissing?: boolean } = {}
+): Promise<{ ok: true; path: string; worktree: CaseWorktree; missing: boolean } | WorktreeFailure> {
+  const nameError = worktreeNameError(name);
+  if (nameError) return fail('INVALID_INPUT', nameError);
+  const target = managedWorktreePath(repo.repoRoot, name);
+  let cur = repo.repoRoot;
+  let missing = false;
+  for (const segment of [...WORKTREES_DIR_SEGMENTS, name]) {
+    cur = join(cur, segment);
+    const state = await lstatState(cur);
+    if (state === 'absent') {
+      if (!opts.allowMissing) return fail('NOT_FOUND', `No worktree named "${name}" in this case.`);
+      // Nothing below an absent folder exists, so nothing below it can redirect anything.
+      missing = true;
+      break;
+    }
+    if (state === 'symlink') {
+      return fail('INVALID_INPUT', `${cur} is a symlink. Codeman only manages worktrees that are real directories.`);
+    }
+    if (state === 'other') return fail('INVALID_INPUT', `${cur} is not a directory.`);
+  }
+  if (!missing && (await realOr(target)) !== target) {
+    return fail('INVALID_INPUT', `${target} does not resolve to itself; refusing to use it.`);
+  }
+  const listed = await listCaseWorktrees(repo, opts);
+  if (!listed.ok) return listed;
+  for (const wt of listed.worktrees) {
+    if (wt.main) continue;
+    if (missing) {
+      // Lexical only: the folder is gone, so there is no real path to compare. git never calls a
+      // LOCKED worktree prunable (prune skips it), so a locked one is taken too, and the caller's
+      // lock check then refuses it with git's lock reason.
+      if (wt.path === target && (wt.prunable || wt.locked)) {
+        return { ok: true, path: target, worktree: { ...wt, managed: true, name }, missing: true };
+      }
+      continue;
+    }
+    if (wt.path === target || (await realOr(wt.path)) === target) {
+      return { ok: true, path: target, worktree: { ...wt, managed: true, name }, missing: false };
+    }
+  }
+  if (missing) return fail('NOT_FOUND', `No worktree named "${name}" in this case.`);
+  return fail(
+    'NOT_FOUND',
+    `${target} is not a registered git worktree of this repository (a leftover folder, or one git no longer knows about).`
+  );
+}
+
+// ─── IO: excludes ────────────────────────────────────────────────────────────
+
+/**
+ * Append each of `lines` that git does not already ignore to `<commonDir>/info/exclude`. Returns
+ * the lines written. A symlinked `info` dir or `exclude` file is left alone (reported, never
+ * written through).
+ */
+async function ensureExcluded(
+  repo: CaseRepository,
+  probes: Array<{ line: string; probe: string }>,
+  git: WorktreeGitRunner
+): Promise<{ added: string[]; warning?: string }> {
+  const needed: string[] = [];
+  for (const { line, probe } of probes) {
+    const run = await git(repo.repoRoot, [...READ_ONLY_GIT_OPTIONS, 'check-ignore', '-q', '--', probe], {
+      timeoutMs: WORKTREE_READ_TIMEOUT_MS,
+    });
+    // 0: ignored. 1: not ignored. Anything else (128) is a git error: assume not ignored, since an
+    // extra exclude line is harmless and a missing one leaves the worktrees untracked.
+    if (run.code !== 0) needed.push(line);
+  }
+  if (needed.length === 0) return { added: [] };
+  const infoDir = join(repo.commonDir, 'info');
+  const excludePath = join(infoDir, 'exclude');
+  try {
+    const infoState = await lstatState(infoDir);
+    if (infoState === 'absent') await fs.mkdir(infoDir);
+    else if (infoState !== 'dir')
+      return { added: [], warning: `${infoDir} is not a plain directory; nothing was excluded.` };
+    const fileState = await lstatState(excludePath);
+    if (fileState === 'symlink' || fileState === 'dir') {
+      return { added: [], warning: `${excludePath} is not a plain file; nothing was excluded.` };
+    }
+    const existing = fileState === 'absent' ? '' : await fs.readFile(excludePath, 'utf-8');
+    const { text, added } = excludeAppendText(existing, needed);
+    if (text) await fs.appendFile(excludePath, text, { mode: 0o644 });
+    return { added };
+  } catch (err) {
+    return { added: [], warning: `Could not update ${excludePath}: ${(err as Error).message}` };
+  }
+}
+
+// ─── IO: one operation per repository at a time ──────────────────────────────
+
+const repoLocks = new Map<string, Promise<unknown>>();
+
+/** Serialize create/remove per repository: two creates must not both pass the "absent" check. */
+async function withRepoLock<T>(repoRoot: string, fn: () => Promise<T>): Promise<T> {
+  const prev = repoLocks.get(repoRoot) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  const tail = next.catch(() => undefined);
+  repoLocks.set(repoRoot, tail);
+  try {
+    return await next;
+  } finally {
+    if (repoLocks.get(repoRoot) === tail) repoLocks.delete(repoRoot);
+  }
+}
+
+// ─── IO: create ──────────────────────────────────────────────────────────────
+
+export interface CreateWorktreeRequest {
+  name: string;
+  /** New branch; default `worktree-<name>`. */
+  branch?: string;
+  /** Start point; default `HEAD` (the case's current commit). */
+  base?: string;
+}
+
+export interface CreatedWorktree {
+  name: string;
+  path: string;
+  branch: string;
+  base: string;
+  /** The commit the new branch starts at. */
+  head: string;
+  /** Lines appended to the repository's `info/exclude` (empty when git already ignored them). */
+  excludeAdded: string[];
+  warnings: string[];
+}
+
+export async function createCaseWorktree(
+  repo: CaseRepository,
+  req: CreateWorktreeRequest,
+  opts: WorktreeOptions = {}
+): Promise<{ ok: true; worktree: CreatedWorktree } | WorktreeFailure> {
+  const git = opts.git ?? runWorktreeGit;
+  const nameError = worktreeNameError(req.name);
+  if (nameError) return fail('INVALID_INPUT', nameError);
+  const branch = req.branch || defaultWorktreeBranch(req.name);
+  const branchError = worktreeBranchError(branch);
+  if (branchError) return fail('INVALID_INPUT', branchError);
+  const base = req.base || 'HEAD';
+  const baseError = worktreeBaseError(base);
+  if (baseError) return fail('INVALID_INPUT', baseError);
+
+  return withRepoLock(repo.repoRoot, async () => {
+    // A name already taken says so in those words, before the branch check would report the
+    // derived branch instead. Rechecked after the folders are prepared, below.
+    try {
+      if ((await lstatState(managedWorktreePath(repo.repoRoot, req.name))) !== 'absent') {
+        return fail('ALREADY_EXISTS', `A worktree named "${req.name}" already exists in this case.`);
+      }
+    } catch {
+      /* unreadable: the check after the folders are prepared reports it */
+    }
+    // git's own word on the branch name. The output must be the input: `--branch` expands
+    // shorthands, and anything it rewrote is not the name the user typed.
+    const refFormat = await git(repo.repoRoot, [...READ_ONLY_GIT_OPTIONS, 'check-ref-format', '--branch', branch], {
+      timeoutMs: WORKTREE_READ_TIMEOUT_MS,
+    });
+    if (refFormat.code !== 0 || refFormat.stdout.trim() !== branch) {
+      return fail('INVALID_INPUT', `"${branch}" is not a valid branch name.`, gitRefusalText(refFormat.stderr));
+    }
+    const existingBranch = await git(
+      repo.repoRoot,
+      [...READ_ONLY_GIT_OPTIONS, 'show-ref', '--verify', '--quiet', `refs/heads/${branch}`],
+      { timeoutMs: WORKTREE_READ_TIMEOUT_MS }
+    );
+    if (existingBranch.code === 0) {
+      return fail('ALREADY_EXISTS', `A branch named "${branch}" already exists. Pick another worktree name or branch.`);
+    }
+    const resolved = await git(
+      repo.repoRoot,
+      // No `--end-of-options` (git 2.30+): the base already passed the ref gate, which refuses a
+      // leading `-`, so it cannot be read as an option.
+      [...READ_ONLY_GIT_OPTIONS, 'rev-parse', '--verify', '--quiet', `${base}^{commit}`],
+      { timeoutMs: WORKTREE_READ_TIMEOUT_MS }
+    );
+    const head = resolved.stdout.trim();
+    if (resolved.code !== 0 || !/^[0-9a-f]{40,64}$/.test(head)) {
+      return fail('INVALID_INPUT', `"${base}" is not a commit in this repository (an empty repository has none yet).`);
+    }
+
+    const prepared = await prepareWorktreesDir(repo.repoRoot);
+    if (!prepared.ok) return prepared;
+    const target = join(prepared.dir, req.name);
+    try {
+      if ((await lstatState(target)) !== 'absent') {
+        return fail('ALREADY_EXISTS', `${target} already exists. Pick another worktree name.`);
+      }
+    } catch (err) {
+      return fail('OPERATION_FAILED', `Could not inspect ${target}: ${(err as Error).message}`);
+    }
+
+    const skillProbes: Array<{ line: string; probe: string }> = [];
+    for (const dir of new Set(opts.agentSkillDirs ?? [])) {
+      const line = agentSkillExcludeLine(dir);
+      if (line) skillProbes.push({ line, probe: `${dir}/codeman` });
+    }
+    const excluded = await ensureExcluded(
+      repo,
+      [
+        { line: WORKTREES_EXCLUDE_LINE, probe: `${WORKTREES_DIR_SEGMENTS.join('/')}/${req.name}` },
+        { line: SETTINGS_LOCAL_EXCLUDE_LINE, probe: '.claude/settings.local.json' },
+        ...skillProbes,
+      ],
+      git
+    );
+
+    // The resolved commit, not the ref text, after `--`: nothing here can be read as an option,
+    // and `--no-track` keeps a worktree started from `origin/main` from tracking (and pulling) main.
+    const add = await git(repo.repoRoot, ['worktree', 'add', '--no-track', '-b', branch, '--', target, head], {
+      timeoutMs: WORKTREE_ADD_TIMEOUT_MS,
+    });
+    if (add.code !== 0 || add.spawnError || add.timedOut) {
+      const text = gitRefusalText(add.stderr);
+      if (/already exists/i.test(text)) return fail('ALREADY_EXISTS', `git refused: ${text}`, text);
+      return gitFailure(add, 'creating the worktree');
+    }
+    return {
+      ok: true,
+      worktree: {
+        name: req.name,
+        path: target,
+        branch,
+        base,
+        head,
+        excludeAdded: excluded.added,
+        warnings: excluded.warning ? [excluded.warning] : [],
+      },
+    };
+  });
+}
+
+// ─── IO: remove ──────────────────────────────────────────────────────────────
+
+export interface RemoveWorktreeRequest {
+  name: string;
+  /** Also `git branch -d` the worktree's branch (never `-D`). */
+  deleteBranch?: boolean;
+  /** True when a live session runs at or inside `path`: the removal is refused. */
+  isInUse: (path: string) => boolean | Promise<boolean>;
+}
+
+export interface RemovedWorktree {
+  name: string;
+  path: string;
+  branch: string | null;
+  branchDeleted: boolean;
+  /** git's refusal to delete the branch (typically "not fully merged"); the worktree is gone regardless. */
+  branchError?: string;
+}
+
+export async function removeCaseWorktree(
+  repo: CaseRepository,
+  req: RemoveWorktreeRequest,
+  opts: WorktreeOptions = {}
+): Promise<{ ok: true; removed: RemovedWorktree } | WorktreeFailure> {
+  const git = opts.git ?? runWorktreeGit;
+  return withRepoLock(repo.repoRoot, async () => {
+    // A worktree whose folder is gone is removable too: `git worktree remove` then only drops
+    // git's record of it (measured on git 2.43: exit 0, nothing on disk touched).
+    const found = await resolveManagedWorktree(repo, req.name, { ...opts, allowMissing: true });
+    if (!found.ok) return found;
+    // The case passed the Docker rule, but the worktree folder itself can be a Docker case's
+    // workspace (a Docker case linked to it), or hold one. `git worktree remove` runs a status
+    // INSIDE the tree first (container-written files, checkout filters on this machine), then
+    // deletes the whole tree, ignored files included, under a container that still mounts it.
+    // A folder that is gone has neither problem: git only drops its record.
+    if (!found.missing) {
+      const dockerRoots = await Promise.all((opts.dockerWorkspaces ?? []).filter(Boolean).map(realOr));
+      if (dockerRoots.some((root) => isPathWithin(found.path, root) || isPathWithin(root, found.path))) {
+        return fail('INVALID_INPUT', DOCKER_WORKTREE_REFUSAL);
+      }
+    }
+    if (await req.isInUse(found.path)) {
+      return fail(
+        'CONFLICT',
+        `A live session is still running in worktree "${req.name}". Close it first, then remove the worktree.`
+      );
+    }
+    if (found.worktree.locked) {
+      return fail(
+        'CONFLICT',
+        `Worktree "${req.name}" is locked${found.worktree.lockReason ? ` (${found.worktree.lockReason})` : ''}. Unlock it with git first.`
+      );
+    }
+    const removed = await git(repo.repoRoot, ['worktree', 'remove', '--', found.path], {
+      timeoutMs: WORKTREE_REMOVE_TIMEOUT_MS,
+    });
+    if (removed.code !== 0 || removed.spawnError || removed.timedOut) {
+      if (removed.timedOut || removed.spawnError) return gitFailure(removed, 'removing the worktree');
+      const text = gitRefusalText(removed.stderr);
+      // git's own refusal (modified or untracked files, a lock): Codeman never forces, so this is
+      // the answer, in git's words.
+      return fail(
+        'CONFLICT',
+        text ? `git refused to remove the worktree: ${text}` : 'git refused to remove the worktree.',
+        text
+      );
+    }
+    const branch = found.worktree.branch;
+    let branchDeleted = false;
+    let branchError: string | undefined;
+    if (req.deleteBranch && branch) {
+      const del = await git(repo.repoRoot, ['branch', '-d', '--', branch], { timeoutMs: WORKTREE_READ_TIMEOUT_MS });
+      if (del.code === 0) branchDeleted = true;
+      else branchError = gitRefusalText(del.stderr) || 'git refused to delete the branch.';
+    }
+    return {
+      ok: true,
+      removed: {
+        name: req.name,
+        path: found.path,
+        branch,
+        branchDeleted,
+        ...(branchError ? { branchError } : {}),
+      },
+    };
+  });
+}

src/services/unified-session-service.ts

@@ -167,6 +167,18 @@ function overwrite<K extends keyof UnifiedSessionItem>(
   if (value !== undefined) item[key] = value;
 }
 
+/** `<repo>/.claude/worktrees/<name>`: Claude Code's `--worktree` layout, which Codeman's own worktrees use too. */
+const WORKTREE_PATH = /^(.+)\/\.claude\/worktrees\/([^/]+)\/?$/;
+
+/**
+ * The worktree a working directory is, by its layout alone: `{ repo, name }` for
+ * `<repo>/.claude/worktrees/<name>` (the folder itself, not a subfolder of it), else null.
+ */
+export function worktreeFromPath(workingDir: string): { repo: string; name: string } | null {
+  const m = WORKTREE_PATH.exec(workingDir);
+  return m ? { repo: m[1], name: m[2] } : null;
+}
+
 /**
  * Merge all source views into one list, applying precedence
  * (history → lifecycle → persisted → live) and the meaningfulness floor.
@@ -326,6 +338,17 @@ export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionIte
         if (byDir) item.lastPrompt = byDir.prompt;
       }
     }
+    // A live or persisted session started in a worktree Codeman created (or Claude Code's own
+    // `--worktree`) has no transcript record naming it until claude writes one, and a codex or
+    // shell session never gets one, so its row read like any other session of the repo. The
+    // folder layout says which worktree it is; a transcript record, when there is one, still wins.
+    if (!item.worktreeName && item.workingDir) {
+      const wt = worktreeFromPath(item.workingDir);
+      if (wt) {
+        item.worktreeName = wt.name;
+        item.worktreeRepo ??= wt.repo;
+      }
+    }
   }
 
   // Meaningfulness floor: keep real rows, drop bare lifecycle/mux-only noise.

src/session-submit-verifier.ts

@@ -4,7 +4,7 @@
  *
  * Claude Code 2.1.277 (auto-installed 2026-09-18) takes typed text the moment its
  * composer paints but ignores Enter for the first 30 to 50 seconds after it, so the
- * `send-keys -l <text>` + `send-keys Enter` pair `TmuxManager.sendInput()` sends 50 ms
+ * text + `send-keys Enter` pair `TmuxManager.sendInput()` sends 50 ms
  * apart leaves the prompt sitting on the composer with `0 tokens`, and every caller
  * that then waits for the turn (send-and-wait, the agent skill, the maintainer bot,
  * cron, Ralph) burns its whole timeout on a turn that never started. Measured through

src/session.ts

@@ -568,6 +568,7 @@ export class Session extends EventEmitter {
   private _activityStreak: ActivityStreak | null = null; // Unbroken run of PTY repaints (working detection)
   private _lastPaneProbeAt = 0; // Throttle for the tmux screen probe
   private _lastPaneProbeWorking: boolean | null = null; // Its last verdict (null = could not read)
+  private _lastPaneProbeTrustDialog = false; // Same capture showed the workspace-trust dialog (see _confirmIdle)
   /**
    * Background work the pane's own footer reports, e.g. `1 monitor`; null for none.
    *
@@ -2743,6 +2744,7 @@ export class Session extends EventEmitter {
     this._interactiveStartedAt = Date.now();
     this._trustDialogAttempts = 0;
     this._lastTrustDialogScanAt = 0;
+    this._lastPaneProbeTrustDialog = false; // the last pane's verdict, not this one's
     if (this._trustDialogTimer) {
       clearTimeout(this._trustDialogTimer);
       this._trustDialogTimer = null;
@@ -3179,13 +3181,24 @@ export class Session extends EventEmitter {
    * a two-marker match (isTrustDialogScreen), and an attempt cap.
    */
   private _maybeAcceptTrustDialog(): void {
-    if (this._trustDialogAccepted) return;
+    // Stopped: the kill itself produces PTY output, and the buffer tail still holds the
+    // dialog, so without this a deleted session kept "answering" it for several seconds.
+    if (this._trustDialogAccepted || this._isStopped) return;
     const now = Date.now();
     if (now - this._interactiveStartedAt > TRUST_DIALOG_WINDOW_MS) {
       this._trustDialogAccepted = true; // window closed; anything matching now is not the dialog
       return;
     }
-    if (now - this._lastTrustDialogScanAt < TRUST_DIALOG_RETRY_MS) return;
+    const sinceScan = now - this._lastTrustDialogScanAt;
+    if (sinceScan < TRUST_DIALOG_RETRY_MS) {
+      // ⚠️ Defer a throttled read, never drop it. The dialog's own paint is usually the
+      // last output a launching pane produces, and it tends to land inside the throttle
+      // of the read the blank screen before it triggered: dropped, nothing re-read the
+      // screen and the session sat on the dialog for good (2 of 12 fresh launches on
+      // Claude Code 2.1.294). A read already scheduled covers this one.
+      if (!this._trustDialogTimer) this._rescanTrustDialogIn(TRUST_DIALOG_RETRY_MS - sinceScan + 100);
+      return;
+    }
     this._lastTrustDialogScanAt = now;
 
     // Prefer the pane; fall back to the buffer tail on a direct-PTY session,
@@ -3220,14 +3233,17 @@ export class Session extends EventEmitter {
     // on a live 2.1.252 spawn: cursor moved at 6 s, then nothing). The timer is
     // one-shot and self-rearming through this same path, and every exit route
     // goes through _clearAllTimers().
-    // The +100ms puts the re-entry OUTSIDE the scan throttle above; firing at
-    // exactly the throttle boundary would let the scan return early and break
-    // the chain with the dialog still on screen.
+    // The +100ms puts the re-entry OUTSIDE the scan throttle above.
+    this._rescanTrustDialogIn(TRUST_DIALOG_RETRY_MS + 100);
+  }
+
+  /** Re-run the trust-dialog scan after `delayMs`, replacing any read already scheduled. */
+  private _rescanTrustDialogIn(delayMs: number): void {
     if (this._trustDialogTimer) clearTimeout(this._trustDialogTimer);
     this._trustDialogTimer = setTimeout(() => {
       this._trustDialogTimer = null;
       this._maybeAcceptTrustDialog();
-    }, TRUST_DIALOG_RETRY_MS + 100);
+    }, delayMs);
   }
 
   /**
@@ -3314,6 +3330,18 @@ export class Session extends EventEmitter {
       text === null
         ? null
         : !blockedOnScreen && (this._workingLinePattern().test(text) || this._paneAwaitsWorkers(text));
+    // A capture that failed proves nothing either way, so it keeps the last answer.
+    if (text !== null) {
+      const trustDialog = isTrustDialogScreen(text);
+      if (
+        trustDialog &&
+        !this._lastPaneProbeTrustDialog &&
+        now - this._interactiveStartedAt <= TRUST_DIALOG_WINDOW_MS
+      ) {
+        console.log(`[Session] Holding idle while the workspace trust dialog is on screen: ${this.id}`);
+      }
+      this._lastPaneProbeTrustDialog = trustDialog;
+    }
     this._readWatching(text);
     this._readScreenModel(text);
     return this._lastPaneProbeWorking;
@@ -3673,6 +3701,16 @@ export class Session extends EventEmitter {
       this.activityTimeout = setTimeout(() => this._confirmIdle(), PANE_PROBE_RECHECK_MS);
       return;
     }
+    // ⚠️ The workspace-trust dialog is not a composer, although its `❯` (on "No, exit")
+    // arms this check and the dialog sits quiet. Calling it idle let an agent that waited
+    // for idle send its prompt into the dialog, and the prompt's Enter answered *exit*.
+    // Not working either, so the status stays where it is until the dialog is gone.
+    // Bounded by the auto-accept's own startup window: later on, a screen that merely
+    // quotes the dialog (an agent reading session-trust-dialog.ts) must not hold idle off.
+    if (this._lastPaneProbeTrustDialog && Date.now() - this._interactiveStartedAt <= TRUST_DIALOG_WINDOW_MS) {
+      this.activityTimeout = setTimeout(() => this._confirmIdle(), PANE_PROBE_RECHECK_MS);
+      return;
+    }
     this._awaitingIdleConfirmation = false;
     this.activityTimeout = null;
     // Emit idle if either:
@@ -4685,7 +4723,7 @@ export class Session extends EventEmitter {
    *
    * More reliable than direct PTY write for programmatic input, especially
    * with Claude CLI which uses Ink (React for terminals).
-   * Uses tmux `send-keys -l` to inject text + Enter.
+   * Uses tmux to inject the text (one bracketed paste) + Enter.
    *
    * @param data - Input data with optional `\r` for Enter
    * @returns true if input was sent, false if no mux session or PTY

src/tmux-manager.ts

@@ -7,13 +7,13 @@
  * - **Persistence**: Sessions survive server restarts and disconnects
  * - **Ghost recovery**: Orphaned sessions are discovered and reattached on startup
  * - **Resource tracking**: Memory, CPU, and child process stats per session
- * - **Reliable input**: `send-keys -l` sends literal text in a single command
+ * - **Reliable input**: a submitted prompt goes in as one bracketed paste, then a separate Enter
  * - **Teammate support**: Immutable pane IDs enable targeting individual teammates
  *
  * tmux sessions are named `codeman-{sessionId}` and stored in ~/.codeman/mux-sessions.json.
  *
  * Key features:
- * - `send-keys 'text' Enter` sends literal text in a single command
+ * - `paste-buffer -p` + a separate `send-keys Enter` submits a prompt (see sendInput)
  * - `list-sessions -F` provides structured queries
  * - `display-message -p '#{pane_pid}'` for reliable PID discovery
  * - Single server architecture
@@ -436,6 +436,84 @@ export function resolveTmuxPaneTarget(muxName: string, paneTarget?: string): str
   return `${muxName}.${paneTarget}`;
 }
 
+let submitBufferSeq = 0;
+
+/** The tmux commands of one bracketed paste, see buildPasteTextCommands(). */
+export interface PasteTextCommands {
+  /** Fills a buffer of its own with the text. */
+  set: string;
+  /** Pastes that buffer into the target, bracketed, and deletes it (`-d`). */
+  paste: string;
+  /** Deletes the buffer when `paste` failed; `-d` only runs on a successful paste. */
+  discard: string;
+}
+
+/**
+ * Escape a final `;` for tmux. tmux splits commands on an argument that ENDS in
+ * `;` (`set-buffer -- 'a;'` stores `a`, `send-keys -l 'a;'` types `a`, a lone `;`
+ * is no argument at all); a final `\;` is its escape for a literal `;`. A `;`
+ * anywhere else in the argument is literal already. Exported for unit testing.
+ */
+export function escapeTmuxTrailingSemicolon(text: string): string {
+  return text.endsWith(';') ? `${text.slice(0, -1)}\\;` : text;
+}
+
+/**
+ * Whether a text+Enter submit types `text` as keys instead of pasting it: true for
+ * a single character. Claude Code's and Codex's selection dialogs ignore a bracketed
+ * paste, so a pasted `3` + Enter confirms the highlighted option instead of option 3;
+ * a typed `3` selects it. One character cannot form the burst Codex reads as a paste,
+ * so typing it is safe there. Exported for unit testing.
+ */
+export function submitsAsKeys(text: string): boolean {
+  return [...text].length === 1;
+}
+
+/**
+ * tmux commands that type `text` into `target` as ONE bracketed paste, ahead of a
+ * separately sent `Enter` that submits it. Exported for unit testing.
+ *
+ * Why a paste and not `send-keys -l`: Codex detects a paste that arrives WITHOUT
+ * bracketed-paste markers heuristically, from characters arriving in a fast burst,
+ * and folds an Enter that lands inside that burst window into the paste as a
+ * newline. `send-keys -l` types exactly such an unmarked burst, so a text+Enter
+ * pair sat in Codex's composer unsubmitted: always for long text (Codex shows it as
+ * `[Pasted Content N chars]`, which SubmitVerifier cannot match against the prompt,
+ * so nothing re-presses Enter), intermittently for short text at the 50 ms gap.
+ * `paste-buffer -p` wraps the text in the markers (only when the pane asked for
+ * them, so an app without bracketed paste sees the same bytes as before) and the
+ * Enter after it is unambiguous.
+ *
+ * Each call gets its own named buffer so concurrent sends cannot paste each other's
+ * text. tmux keeps a named buffer until something deletes it (`buffer-limit` trims
+ * only automatic ones), hence `discard` for a paste that fails.
+ *
+ * A single character is typed instead (submitsAsKeys), so a dialog answer selects.
+ * A final `;` is escaped (escapeTmuxTrailingSemicolon).
+ */
+export function buildPasteTextCommands(tmux: string, target: string, text: string): PasteTextCommands {
+  const buffer = `codeman-submit-${process.pid}-${++submitBufferSeq}`;
+  return {
+    set: `${tmux} set-buffer -b ${buffer} -- ${shellescape(escapeTmuxTrailingSemicolon(text))}`,
+    paste: `${tmux} paste-buffer -p -d -b ${buffer} -t ${shellescape(target)}`,
+    discard: `${tmux} delete-buffer -b ${buffer}`,
+  };
+}
+
+/**
+ * Run a bracketed paste. A failed paste (the pane or the server is gone) deletes
+ * the buffer before the paste's own error propagates; a failing delete is ignored.
+ */
+export async function pasteText(run: (cmd: string) => Promise<unknown>, cmds: PasteTextCommands): Promise<void> {
+  await run(cmds.set);
+  try {
+    await run(cmds.paste);
+  } catch (err) {
+    await run(cmds.discard).catch(() => undefined);
+    throw err;
+  }
+}
+
 /**
  * Pick the active pane id from `tmux list-panes -F '#{pane_id}:#{pane_active}'`
  * output (lines like `%0:1`). Returns the pane id whose active flag is 1.
@@ -3738,10 +3816,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   }
 
   /**
-   * Send input directly to a tmux session using `send-keys`.
+   * Send input directly to a tmux session.
    *
-   * Uses tmux send-keys for reliable input delivery:
-   * - `-l` flag sends literal text (no key interpretation)
+   * - Text followed by `\r` goes in as ONE bracketed paste (buildPasteTextCommands),
+   *   so Codex cannot fold the Enter into a paste burst; a single character is typed
+   *   with `send-keys -l` instead, so a dialog answer selects (submitsAsKeys)
+   * - Text without `\r` is typed literally with `send-keys -l` (no key interpretation)
    * - `Enter` key is sent as a SEPARATE tmux invocation after a small delay
    * - Ink (Claude CLI) needs text and Enter split to avoid treating Enter as a newline
    */
@@ -3776,19 +3856,32 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         // Send text first, then Enter as a SEPARATE tmux command after a short delay.
         // Ink (Claude CLI's terminal framework) needs them split — sending both in a
         // single tmux invocation (via \;) causes Ink to interpret Enter as a newline
-        // character in the input buffer rather than as form submission.
-        await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(textPart)}`, {
-          timeout: EXEC_TIMEOUT_MS,
-        });
+        // character in the input buffer rather than as form submission. The text goes
+        // in as a bracketed paste so Codex cannot fold the Enter into it either
+        // (see buildPasteTextCommands). A single character is typed, because a
+        // selection dialog ignores a pasted `3` and Enter then confirms the
+        // highlighted option (see submitsAsKeys).
+        if (submitsAsKeys(textPart)) {
+          await execAsync(
+            `${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`,
+            { timeout: EXEC_TIMEOUT_MS }
+          );
+        } else {
+          await pasteText(
+            (cmd) => execAsync(cmd, { timeout: EXEC_TIMEOUT_MS }),
+            buildPasteTextCommands(this.tmux(), session.muxName, textPart)
+          );
+        }
         await new Promise((resolve) => setTimeout(resolve, 50));
         await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" Enter`, {
           timeout: EXEC_TIMEOUT_MS,
         });
       } else if (textPart) {
         // Text only, no Enter
-        await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(textPart)}`, {
-          timeout: EXEC_TIMEOUT_MS,
-        });
+        await execAsync(
+          `${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`,
+          { timeout: EXEC_TIMEOUT_MS }
+        );
       } else if (hasCarriageReturn) {
         // Enter only
         await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" Enter`, {
@@ -3930,19 +4023,25 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       const textPart = input.replace(/\r/g, '').replace(/\n/g, '').trimEnd();
 
       if (textPart && hasCarriageReturn) {
-        execSync(`${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(textPart)}`, {
-          encoding: 'utf-8',
-          timeout: EXEC_TIMEOUT_MS,
-        });
+        execSync(
+          `${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`,
+          {
+            encoding: 'utf-8',
+            timeout: EXEC_TIMEOUT_MS,
+          }
+        );
         execSync(`${tmux} send-keys -t ${shellescape(target)} Enter`, {
           encoding: 'utf-8',
           timeout: EXEC_TIMEOUT_MS,
         });
       } else if (textPart) {
-        execSync(`${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(textPart)}`, {
-          encoding: 'utf-8',
-          timeout: EXEC_TIMEOUT_MS,
-        });
+        execSync(
+          `${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(escapeTmuxTrailingSemicolon(textPart))}`,
+          {
+            encoding: 'utf-8',
+            timeout: EXEC_TIMEOUT_MS,
+          }
+        );
       } else if (hasCarriageReturn) {
         execSync(`${tmux} send-keys -t ${shellescape(target)} Enter`, {
           encoding: 'utf-8',
@@ -4076,7 +4175,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         // Without geometry there is no cursor move, so fall back to the old trim.
         // Keeping the blank rows here would park the caret at the bottom of the
         // pane with nothing to correct it — worse than not trying at all.
-        if (!geometry) return normalizeScrollbackEol(rawCapture.replace(/\n+$/g, ''));
+        if (!geometry) {
+          const trimmed = rawCapture.replace(/\n+$/g, '');
+          return trimmed ? `${normalizeScrollbackEol(trimmed)}\x1b[0m` : '';
+        }
         // Take the line terminator off and nothing else. The trailing blank rows
         // that remain are the real bottom of the screen, and the cursor move
         // below counts up from it. tmux joins rows with a bare `\n`; normalize to
@@ -4090,7 +4192,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         // `_replayWouldShrinkBuffer` exists to refuse, arriving from the server
         // side where that guard cannot see it.
         if (!hasVisibleContent(trimmed)) return '';
-        return `${normalizeScrollbackEol(trimmed)}${formatCursorRestore(geometry)}`;
+        // capture-pane -e can leave the last row's SGR active (e.g. a nested
+        // tmux status bar). Hand live output the same default style as a visible
+        // snapshot, resetting before the cursor move so its position is kept.
+        return `${normalizeScrollbackEol(trimmed)}\x1b[0m${formatCursorRestore(geometry)}`;
       }
 
       const buffer = rawCapture.replace(/\n+$/g, '');
@@ -4099,7 +4204,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // positioned snapshot repaint and fall back to the raw capture. Normalize
       // its bare `\n` line endings to `\r\n` so the replay doesn't staircase
       // diagonally in a fresh xterm (COD-138, same reason as the fullHistory path).
-      return normalizeScrollbackEol(buffer);
+      return buffer ? `${normalizeScrollbackEol(buffer)}\x1b[0m` : '';
     } catch (err) {
       // ENOBUFS carries the truncated multi-MB stdout on the error object —
       // log a concise line instead of dumping it into the journal.

src/utils/deepseek-cli-resolver.ts

@@ -84,7 +84,8 @@ export const DEEPSEEK_VERSION_REGEX = /(?:^|\s)v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z][0
  */
 export const DEEPSEEK_IDENTITY_REGEX = /DeepSeek\s+Harness/i;
 
-const DEEPSEEK_NOT_FOUND = 'DeepSeek Harness CLI (dsh) not found. Install with: npm install -g @deepseek-ai/dsh';
+const DEEPSEEK_NOT_FOUND =
+  'DeepSeek Harness CLI (dsh) not found. Install with: npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)';
 
 /** Where profiles live: `$DSH_HOME/profiles`, defaulting to `~/.dsh/profiles`. */
 export function resolveDshHome(): string {

src/web/public/app.js

@@ -533,8 +533,8 @@ const DEFAULT_SHORTCUTS = [
     group: 'Session',
     label: 'Toggle Session Sidebar',
     // Alt+B, not Ctrl+B: Ctrl+B must reach the terminal (tmux prefix,
-    // readline backward-char). The Alt block below claims only Digit1-9 and
-    // the brackets, and the registry claims Alt for KeyK and Slash only.
+    // readline backward-char). The Alt block below claims only Digit1-9; the
+    // brackets are registry entries, and the registry claims Alt for KeyK and Slash only.
     bindings: [{ modifiers: ['alt'], key: 'b', code: 'KeyB' }],
     action: 'toggleSessionSidebar',
   },
@@ -638,11 +638,22 @@ const DEFAULT_SHORTCUTS = [
     bindings: [],
     action: 'removeTile',
   },
+  // Physical key codes, so macOS Option layouts that print "“" for Option+[ still match.
   {
-    id: 'previous-next-session',
+    id: 'previous-session',
     group: 'Session',
-    label: 'Previous / Next Session',
-    displayBindings: ['Alt/Option+[', 'Alt/Option+]'],
+    label: 'Previous Session',
+    displayBindings: ['Alt/Option+['],
+    bindings: [{ modifiers: ['alt'], code: 'BracketLeft' }],
+    action: 'previousSession',
+  },
+  {
+    id: 'next-session-alt',
+    group: 'Session',
+    label: 'Next Session (alternate)',
+    displayBindings: ['Alt/Option+]'],
+    bindings: [{ modifiers: ['alt'], code: 'BracketRight' }],
+    action: 'nextSession',
   },
   {
     id: 'switch-tab-n',
@@ -1388,19 +1399,7 @@ class CodemanApp {
     // getShortcutRegistry()). The command palette chord is deliberately NOT in
     // this map — shouldOpenCommandPaletteFromShortcut() dispatches it above with
     // focus-target awareness (it must fire from the terminal but not from inputs).
-    const SHORTCUT_ACTIONS = {
-      showShortcutOverlay: () => this.showShortcutOverlay(),
-      killActiveSession: () => this.killActiveSession(),
-      nextSession: () => this.nextSession(),
-      clearTerminal: () => this.clearTerminal(),
-      restoreTerminalSize: () => this.restoreTerminalSize(),
-      increaseFontSize: () => this.increaseFontSize(),
-      decreaseFontSize: () => this.decreaseFontSize(),
-      toggleVoiceInput: () => VoiceInput.toggle(),
-      moveActiveTabLeft: () => this.moveActiveTabLeft(),
-      moveActiveTabRight: () => this.moveActiveTabRight(),
-      toggleSessionSidebar: () => this.toggleSessionSidebar(),
-    };
+    const SHORTCUT_ACTIONS = this._shortcutActions();
 
     // Use capture to handle before terminal
     document.addEventListener('keydown', (e) => {
@@ -1447,6 +1446,7 @@ class CodemanApp {
         this.closeAllPanels();
         this.closeHelp();
         if (this.attachmentHistoryDrawerOpen) this.closeAttachmentHistory();
+        this.closeWorktreeModal?.();
         this.closeSessionManager();
         this.closeCommandPalette?.();
         this.closeShortcutOverlay?.();
@@ -1463,7 +1463,8 @@ class CodemanApp {
       // Option/Alt session navigation uses physical key CODES, not e.key, so macOS
       // keyboard layouts that emit special characters under Option (Option+1 -> ¡,
       // Option+[ -> "“") still switch sessions. e.code is the physical key regardless
-      // of layout. Option+1-9 = switch by index; Option+[ / Option+] = prev / next.
+      // of layout. Option+1-9 = switch by index. Option+[ / ] (prev / next) live in the
+      // shortcut registry, so they can be rebound.
       if (e.altKey && !e.ctrlKey && !e.shiftKey) {
         const code = e.code || '';
         const digitMatch = code.match(/^Digit([1-9])$/);
@@ -1489,16 +1490,6 @@ class CodemanApp {
           }
           return;
         }
-        if (e.code === 'BracketLeft') {
-          e.preventDefault();
-          this.prevSession();
-          return;
-        }
-        if (e.code === 'BracketRight') {
-          e.preventDefault();
-          this.nextSession();
-          return;
-        }
       }
 
       // Tile grid chords: only where they apply (tile-grid.js tileShortcutFor),
@@ -4843,6 +4834,8 @@ class CodemanApp {
       }
     }
 
+    if (data.version) this.checkWhatsNew?.(data.version);
+
     // Stop any active voice recording on reconnect
     VoiceInput.cleanup();
 
@@ -10336,9 +10329,10 @@ class CodemanApp {
     delete this.respawnActionLogs[sessionId];
   }
 
+  /** Resolves true once the session is gone from the server, false when it is still there. */
   async closeSession(sessionId, killMux = true) {
     // Already on its way out (a repeated click, the mux panel racing the tab).
-    if (this._closingSessions.has(sessionId)) return;
+    if (this._closingSessions.has(sessionId)) return false;
     // The tab goes FIRST and the server is asked after. The kill takes the server
     // a few hundred ms (SIGTERM grace, the process tree, tmux), and a tab that sat
     // there that long after "Kill" read as a click that did nothing. A refused
@@ -10416,7 +10410,7 @@ class CodemanApp {
       } else {
         this.showToast('Tab hidden, tmux still running', 'info');
       }
-      return;
+      return true;
     }
 
     // Still on the server (or the server is unreachable, in which case the resync
@@ -10431,6 +10425,7 @@ class CodemanApp {
       this.renderSessionTabs();
     }
     this.showToast('Failed to close session', 'error');
+    return false;
   }
 
   // Request confirmation before closing a session
@@ -10445,6 +10440,20 @@ class CodemanApp {
     const sessionNameEl = document.getElementById('closeConfirmSessionName');
     sessionNameEl.textContent = name;
 
+    // A session in a Codeman-managed git worktree also offers to remove the worktree
+    // (git worktree remove, never forced) once the session is gone. Read now, before the
+    // session leaves this.sessions.
+    const worktree = this._managedWorktreeOfSession?.(session) || null;
+    this.pendingCloseWorktree = worktree;
+    const wtOption = document.getElementById('closeConfirmWorktree');
+    if (wtOption) {
+      wtOption.hidden = !worktree;
+      const wtName = document.getElementById('closeConfirmWorktreeName');
+      if (wtName) wtName.textContent = worktree ? worktree.name : '';
+      const wtBranch = document.getElementById('closeConfirmWorktreeBranch');
+      if (wtBranch) wtBranch.checked = false;
+    }
+
     // Update kill button text based on session mode
     const killTitle = document.getElementById('closeConfirmKillTitle');
     if (killTitle) {
@@ -10472,15 +10481,24 @@ class CodemanApp {
 
   cancelCloseSession() {
     this.pendingCloseSessionId = null;
+    this.pendingCloseWorktree = null;
     document.getElementById('closeConfirmModal').classList.remove('active');
   }
 
-  async confirmCloseSession(killMux = true) {
+  /**
+   * `removeWorktree`: Close Session's "Kill & remove worktree". The worktree is removed only
+   * after the server confirms the session is gone (a live session inside is refused anyway),
+   * and only ever through `git worktree remove` without --force.
+   */
+  async confirmCloseSession(killMux = true, { removeWorktree = false } = {}) {
     const sessionId = this.pendingCloseSessionId;
+    const worktree = removeWorktree ? this.pendingCloseWorktree : null;
+    const deleteBranch = !!document.getElementById('closeConfirmWorktreeBranch')?.checked;
     this.cancelCloseSession();
 
     if (sessionId) {
-      await this.closeSession(sessionId, killMux);
+      const gone = await this.closeSession(sessionId, killMux);
+      if (gone && worktree) await this._removeWorktreeAfterClose?.(worktree, deleteBranch);
     }
   }
 
@@ -10698,6 +10716,54 @@ class CodemanApp {
   }
 
   // ─── Shortcut Registry ───────────────────────────────────────────────────────
+  /**
+   * Action name -> handler for the shortcut registry entries the document keydown
+   * handler dispatches generically (DEFAULT_SHORTCUTS + the user's rebinds). Entries
+   * absent here (copy selection, the palette, the tile chords) have their own dispatch.
+   */
+  _shortcutActions() {
+    return {
+      showShortcutOverlay: () => this.showShortcutOverlay(),
+      killActiveSession: () => this.killActiveSession(),
+      nextSession: () => this.nextSession(),
+      previousSession: () => this.prevSession(),
+      clearTerminal: () => this.clearTerminal(),
+      restoreTerminalSize: () => this.restoreTerminalSize(),
+      increaseFontSize: () => this.increaseFontSize(),
+      decreaseFontSize: () => this.decreaseFontSize(),
+      toggleVoiceInput: () => VoiceInput.toggle(),
+      moveActiveTabLeft: () => this.moveActiveTabLeft(),
+      moveActiveTabRight: () => this.moveActiveTabRight(),
+      toggleSessionSidebar: () => this.toggleSessionSidebar(),
+    };
+  }
+
+  /**
+   * True when `e` is a chord the USER rebound to a generically dispatched action.
+   * The document handler has already run the action, but its preventDefault() does not
+   * stop xterm, so without this gate a rebind to e.g. Alt+J would also type ESC j into the
+   * session. Defaults are not covered on purpose: several (Ctrl+L) rely on reaching the PTY,
+   * and neither is a chord that matches the entry's own default (a re-capture of it).
+   */
+  isUserBoundShortcutEvent(e) {
+    if (!e.ctrlKey && !e.metaKey && !e.altKey) return false;
+    const overrides = this.loadAppSettingsFromStorage().shortcutOverrides || {};
+    const actions = this._shortcutActions();
+    return this.getShortcutRegistry().some((shortcut) => {
+      if (shortcut.disabled || !Array.isArray(overrides[shortcut.id]?.bindings)) return false;
+      // toggleSessionSidebar has its own gate (shouldToggleSessionSidebarFromShortcut) that
+      // lets the chord through when the sidebar layout is off; swallowing it here would make a
+      // rebound sidebar key dead in the header layout.
+      if (shortcut.action === 'toggleSessionSidebar') return false;
+      if (typeof actions[shortcut.action] !== 'function') return false;
+      if (!this.matchesShortcutEvent(e, shortcut)) return false;
+      // Re-capturing the entry's own default (Ctrl+L for Clear Terminal) must keep reaching the
+      // CLI: clearTerminal() relies on ^L for the redraw.
+      const fallback = DEFAULT_SHORTCUTS.find((d) => d.id === shortcut.id);
+      return !this.matchesShortcutEvent(e, fallback);
+    });
+  }
+
   // Returns the merged shortcut list: DEFAULT_SHORTCUTS with any per-shortcut
   // overrides from settings.shortcutOverrides applied on top.
 

src/web/public/constants.js

@@ -2047,7 +2047,7 @@ function computeRewriteScrollLine(input) {
  * a `/g` regex, so {@link absoluteFilePathPattern} mints a fresh one per call.
  */
 const FILE_PATH_LINK_PATTERN =
-  /(\/(?:home|Users|tmp|var|private|opt|mnt|srv|media|data|workspace)\/[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|markdown|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html?|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
+  /(\/(?:home|Users|tmp|var|private|opt|mnt|srv|media|data|workspace)\/[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|markdown|md|ya?ml|csv|tsv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html?|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|zip|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
 
 /** A fresh, zero-state instance of {@link FILE_PATH_LINK_PATTERN}. */
 function absoluteFilePathPattern() {
@@ -2100,7 +2100,7 @@ function previewsInFileViewer(filePath) {
  * {@link findFilePathLinks}.
  */
 const RELATIVE_FILE_PATH_LINK_PATTERN =
-  /(^|[\s"'`(\[{<>=,])((?![^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*:\/\/)(?:~\/|[^\s"'`<>|;&()[\]{}=,\/~\n\x00-\x1f])[^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*\.(?:log|txt|json|markdown|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html?|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
+  /(^|[\s"'`(\[{<>=,])((?![^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*:\/\/)(?:~\/|[^\s"'`<>|;&()[\]{}=,\/~\n\x00-\x1f])[^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*\.(?:log|txt|json|markdown|md|ya?ml|csv|tsv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html?|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|zip|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
 
 /** The `(?:log|txt|…)` extension group, read off the rooted pattern so it cannot drift. */
 const FILE_LINK_EXTENSION_GROUP = /\\\.(\(\?:[^()]*\))\)\\b$/.exec(FILE_PATH_LINK_PATTERN.source)[1];

src/web/public/i18n.js

@@ -168,8 +168,8 @@
     'Restore the grid': '恢复平铺网格',
     'Remove tile (the session keeps running)': '移除窗格（会话继续运行）',
     'Drop a tab or a tile here': '将标签页或窗格拖放到此处',
-    // A file of an unsupported type dropped on a tile (tile-grid.js); the single
-    // view's drop (image-input.js) uses 'Only image or video files are supported'.
+    // A file of an unsupported type dropped on a tile (tile-grid.js) or the single
+    // view (image-input.js).
     'Unsupported file type': '不支持的文件类型',
     // Redraw (Ctrl+Shift+R, terminal-ui.js restoreTerminalSize) on the main pane, a tile or Pane B.
     'No active session': '没有活动会话',
@@ -265,6 +265,50 @@
     'New or link a case…': '新建或关联案例…',
     'Case settings…': '案例设置…',
     'No cases match': '没有匹配的案例',
+    // Git worktrees of a case (session-ui.js openWorktreeModal, the case picker row, the
+    // phone case sheet and Close Session's worktree option). Worktree and branch names,
+    // paths and git's own messages are user/git text and pass through untranslated.
+    'Git worktrees…': 'Git 工作树…',
+    'Git worktrees': 'Git 工作树',
+    'Close git worktrees': '关闭 Git 工作树',
+    Worktrees: '工作树',
+    'Worktrees…': '工作树…',
+    "Each worktree is its own checkout of the case's repository, on its own branch, in .claude/worktrees/ of the case. Agents working in parallel then never share one folder.":
+      '每个工作树都是案例仓库的独立检出，有自己的分支，位于案例的 .claude/worktrees/ 中。并行工作的智能体因此不会共用同一个文件夹。',
+    'Start sessions with': '启动会话所用',
+    'New worktree': '新建工作树',
+    Branch: '分支',
+    'Start from': '起点',
+    "New branch worktree-<name> from the case's current commit, unless you pick another below.":
+      '从案例当前提交新建分支 worktree-<name>，除非在下方另行选择。',
+    'Branch and start point': '分支和起点',
+    "A branch, tag or commit. Default: the case's current commit (HEAD).":
+      '分支、标签或提交。默认：案例当前提交（HEAD）。',
+    'Create & start session': '创建并启动会话',
+    'Loading worktrees…': '正在加载工作树…',
+    'No worktrees yet. Create one below.': '还没有工作树。请在下方创建。',
+    'detached HEAD': '游离 HEAD',
+    'main checkout': '主检出',
+    'not created by Codeman': '非 {name} 创建',
+    locked: '已锁定',
+    missing: '已丢失',
+    Open: '打开',
+    'Start a session in this worktree': '在此工作树中启动会话',
+    'Remove…': '移除…',
+    'git worktree remove refuses while the worktree has uncommitted or untracked files. Codeman never forces it.':
+      '工作树中有未提交或未跟踪的文件时，git worktree remove 会拒绝执行。{name} 从不强制移除。',
+    'Its folder is gone. Removing it clears the record git keeps of it, so the name can be used again.':
+      '它的文件夹已不存在。移除它会清除 git 保存的记录，这个名称便可再次使用。',
+    'Remove worktree': '移除工作树',
+    'Kill & remove worktree': '终止并移除工作树',
+    'git refuses while the worktree has uncommitted or untracked files; nothing is forced':
+      '工作树中有未提交或未跟踪的文件时 git 会拒绝；不会强制执行',
+    'Also delete its branch (git branch -d keeps a branch that is not merged)':
+      '同时删除其分支（git branch -d 会保留未合并的分支）',
+    'Name: letters, digits, ".", "_" and "-", starting with a letter or digit, at most 64 characters.':
+      '名称：字母、数字、"."、"_" 和 "-"，以字母或数字开头，最多 64 个字符。',
+    'A launch is already in progress': '已有启动正在进行',
+    'Codeman did not answer.': '{name} 没有响应。',
     'Add Case': '添加案例',
     'Open sessions': '打开会话',
     'Recent Sessions': '最近会话',
@@ -691,7 +735,7 @@
     // the DOM translator skips <textarea> subtrees.
     'Compose prompt': '撰写提示词',
     'Open a session to attach a file': '请先打开一个会话再添加附件',
-    'Only image or video files are supported': '仅支持图片或视频文件',
+    '📎 Attach': '📎 添加附件',
     'Compose prompt, draft saved': '撰写提示词，草稿已保存',
     'Resume saved prompt draft': '继续编辑已保存的提示词草稿',
     'Enter adds a new line': '按 Enter 换行',
@@ -798,9 +842,16 @@
 
     // Dynamic common status / toasts
     'Settings saved': '设置已保存',
+    // The once-per-release toast (settings-ui.js checkWhatsNew); its highlights stay English.
+    "See what's new": '查看更新内容',
     'Settings applied': '设置已应用',
     'Save and keep Settings open': '保存并保持设置打开',
     'Settings saved locally': '设置已保存到本机',
+    // Multi-user mode, a non-admin (settings-ui.js / session-ui.js): server-wide settings
+    // writes are admin-only there.
+    'Saved on this device. Server-wide settings can only be changed by an admin.':
+      '已保存到本设备。服务器全局设置只能由管理员更改。',
+    'Server-wide settings can only be changed by an admin': '服务器全局设置只能由管理员更改',
     'Tunnel active': '隧道已启用',
     'Tunnel starting — QR code will appear when ready...': '隧道正在启动，准备好后将显示二维码…',
     'Push notifications enabled': '推送通知已启用',
@@ -1179,6 +1230,8 @@
     'Close Panels': '关闭面板',
     'Previous / Next Session': '上一个 / 下一个会话',
     'Next Session': '下一个会话',
+    'Previous Session': '上一个会话',
+    'Next Session (alternate)': '下一个会话（备用）',
     'Switch to Tab N': '切换到第 N 个标签页',
     'Move Active Tab Left': '向左移动当前标签页',
     'Move Active Tab Right': '向右移动当前标签页',
@@ -1244,6 +1297,10 @@
       [/^Update to v(.+)$/, (_m, version) => `更新到 v${version}`],
       [/^You're up to date \(v(.+)\)\.$/, (_m, version) => `已是最新版本（v${version}）。`],
       [/^Update available: v(.+)$/, (_m, version) => `有可用更新：v${version}`],
+      [
+        /^Codeman updated to v([^:\s]+): (.+?)(?: \(\+(\d+) more\))?$/,
+        (_m, version, shown, more) => `Codeman 已更新到 v${version}：${shown}${more ? `（另有 ${more} 项）` : ''}`,
+      ],
       [/^Selected: (.+)$/, (_m, value) => `已选择：${value}`],
       [/^Failed to (.+)$/, (_m, action) => `操作失败：${action}`],
       [/^Will create: (.+)$/, (_m, path) => `将创建：${path}`],
@@ -1252,6 +1309,16 @@
       [/^Terminal restored to (\d+)x(\d+)$/, (_m, cols, rows) => `终端已恢复为 ${cols}x${rows}`],
       [/^View truncated to the first (\d+) cells$/, (_m, n) => `视图仅显示前 ${n} 个单元格`],
       [/^(\d+) unsupported number formats$/, (_m, n) => `${n} 种不支持的数字格式`],
+      // Git worktree toasts (session-ui.js): worktree and branch names and git's own
+      // words pass through untranslated.
+      [/^Worktree (\S+) created on branch (\S+)$/, (_m, wt, branch) => `已创建工作树 ${wt}，分支 ${branch}`],
+      [
+        /^Worktree (\S+) removed\. Branch (\S+) kept: ([\s\S]+)$/,
+        (_m, wt, branch, why) => `已移除工作树 ${wt}。保留了分支 ${branch}：${why}`,
+      ],
+      [/^Worktree (\S+) and branch (\S+) removed$/, (_m, wt, branch) => `已移除工作树 ${wt} 和分支 ${branch}`],
+      [/^Worktree (\S+) removed$/, (_m, wt) => `已移除工作树 ${wt}`],
+      [/^Worktree (\S+) was kept: ([\s\S]+)$/, (_m, wt, why) => `工作树 ${wt} 已保留：${why}`],
       // Group names are user text: they pass through untranslated.
       [/^Move to "(.+)"$/, (_m, group) => `移到“${group}”`],
       // Session names are user text too.

src/web/public/image-input.js

@@ -103,7 +103,7 @@ Object.assign(CodemanApp.prototype, {
 
       const mediaFiles = Array.from(e.dataTransfer.files).filter((f) => this._promptAttachKind(f));
       if (mediaFiles.length === 0) {
-        this.showToast('Only image or video files are supported', 'error');
+        this.showToast('Unsupported file type', 'error');
         return;
       }
       this._uploadAndInsertImages(mediaFiles);
@@ -124,7 +124,7 @@ Object.assign(CodemanApp.prototype, {
   async _attachFromToolbar(files, sessionId) {
     const media = files.filter((f) => this._promptAttachKind(f));
     if (media.length === 0) {
-      this.showToast('Only image or video files are supported', 'error');
+      this.showToast('Unsupported file type', 'error');
       return;
     }
     if (!sessionId) return; // no captured session: refuse rather than guess at one
@@ -230,7 +230,7 @@ Object.assign(CodemanApp.prototype, {
       if (pasteConsumed) return;
       pasteConsumed = true;
 
-      // Check for images or videos in clipboard items
+      // Check for images, videos or documents in clipboard items
       var imageFiles = [];
       var items = e.clipboardData && e.clipboardData.items;
       if (items) {
@@ -266,18 +266,27 @@ Object.assign(CodemanApp.prototype, {
     document.execCommand('paste');
   },
 
-  /** What a pick or a paste may upload: 'image', or 'video' for the camera
-   *  roll's clips (the server streams those to disk under their own cap), else
-   *  null. The one filter behind Attach, drop, the Compose and paste-dialog
-   *  pickers and the clipboard handlers. The MIME type decides; some Android
-   *  file managers hand over a File with none, so the name's extension is the
-   *  fallback, mirroring the server's own allowlists. */
+  /** What a pick or a paste may upload: 'image', 'video' for the camera roll's
+   *  clips (the server streams those to disk under their own cap), 'document'
+   *  for the office and text files the server admits, else null. The one filter
+   *  behind Attach, drop, the Compose and paste-dialog pickers and the clipboard
+   *  handlers. For media the MIME type decides, but a video MIME only for the
+   *  containers the server admits; some Android file managers hand over a File
+   *  with none, so the name's extension is the fallback. A document is known by
+   *  its extension alone, as on the server (the MIME a file manager gives a .md
+   *  or .csv is anyone's guess). Mirrors the server's allowlists. */
   _promptAttachKind(file) {
     if (file.type.startsWith('image/')) return 'image';
-    if (file.type.startsWith('video/')) return 'video';
+    // A video MIME counts only for the five containers the server accepts on
+    // ?kind=video (its own set in session-routes.ts); a 3gp or mkv falls to the
+    // extension check below and is refused up front, not after a 1GB upload and a 400.
+    if (/^video\/(mp4|quicktime|x-m4v|webm|ogg)$/i.test(file.type)) return 'video';
     const ext = (file.name || '').toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] || '';
     if (['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'heic', 'heif'].includes(ext)) return 'image';
     if (['mp4', 'webm', 'mov', 'm4v', 'ogv'].includes(ext)) return 'video';
+    if (['pdf', 'docx', 'pptx', 'xlsx', 'zip', 'txt', 'md', 'csv', 'tsv', 'json', 'log', 'yaml', 'yml', 'xml'].includes(ext)) {
+      return 'document';
+    }
     return null;
   },
 

src/web/public/index.html

@@ -790,7 +790,7 @@
                 <path d="m21 15-5-5L5 21"/>
               </svg>
             </button>
-            <input type="file" class="btn-attach-mobile-input" id="attachFileInput" accept="image/*,video/*" multiple tabindex="-1" aria-hidden="true">
+            <input type="file" class="btn-attach-mobile-input" id="attachFileInput" accept="image/*,video/*,.pdf,.docx,.pptx,.xlsx,.zip,.txt,.md,.csv,.tsv,.json,.log,.yaml,.yml,.xml" multiple tabindex="-1" aria-hidden="true">
           </span>
           <button class="btn-voice-mobile" id="voiceInputBtnMobile" onclick="VoiceInput.toggle()"
                   title="Voice input" aria-label="Start voice input" aria-pressed="false">
@@ -1693,6 +1693,18 @@
             <span class="close-option-title" id="closeConfirmKillTitle">Kill Tmux & Claude Code</span>
             <span class="close-option-desc">Terminate the session completely</span>
           </button>
+          <!-- Shown only for a session in a Codeman-managed git worktree (requestCloseSession,
+               app.js): kill it, then `git worktree remove` without --force. -->
+          <div class="close-option-worktree" id="closeConfirmWorktree" hidden>
+            <button class="close-option close-option-danger" onclick="app.confirmCloseSession(true, { removeWorktree: true })">
+              <span class="close-option-title">Kill &amp; remove worktree <span id="closeConfirmWorktreeName" data-i18n-skip></span></span>
+              <span class="close-option-desc">git refuses while the worktree has uncommitted or untracked files; nothing is forced</span>
+            </button>
+            <label class="close-option-worktree-branch">
+              <input type="checkbox" id="closeConfirmWorktreeBranch">
+              <span>Also delete its branch (git branch -d keeps a branch that is not merged)</span>
+            </label>
+          </div>
         </div>
         <div class="modal-footer-cancel">
           <button class="btn-toolbar btn-sm" onclick="app.cancelCloseSession()">Cancel</button>
@@ -1700,6 +1712,52 @@
       </div>
     </div>
 
+    <!-- Git worktrees of a case (session-ui.js openWorktreeModal; routes/worktree-routes.ts).
+         Opened from the case picker's "Git worktrees…" row and the phone case sheet. -->
+    <div class="modal" id="worktreeModal" role="dialog" aria-modal="true" aria-labelledby="worktreeModalTitle">
+      <div class="modal-backdrop" onclick="app.closeWorktreeModal()"></div>
+      <div class="modal-content worktree-modal">
+        <div class="modal-header">
+          <h3 id="worktreeModalTitle"><span>Git worktrees</span> <span class="worktree-modal-case" id="worktreeModalCase" data-i18n-skip></span></h3>
+          <button class="modal-close" onclick="app.closeWorktreeModal()" aria-label="Close git worktrees">&times;</button>
+        </div>
+        <div class="modal-body">
+          <p class="form-hint worktree-intro">Each worktree is its own checkout of the case's repository, on its own branch, in .claude/worktrees/ of the case. Agents working in parallel then never share one folder.</p>
+          <div class="worktree-status" id="worktreeStatus" role="status" aria-live="polite" hidden></div>
+          <div class="worktree-list" id="worktreeList"></div>
+          <div class="form-row worktree-mode-row">
+            <label for="worktreeMode">Start sessions with</label>
+            <select id="worktreeMode" class="form-select"></select>
+          </div>
+          <fieldset class="worktree-new">
+            <legend>New worktree</legend>
+            <div class="form-row">
+              <label for="worktreeName">Name</label>
+              <input type="text" id="worktreeName" maxlength="64" placeholder="fix-login" autocomplete="off" autocapitalize="off" spellcheck="false" onkeydown="if (event.key === 'Enter') app.createWorktreeFromModal()">
+              <span class="form-hint">New branch worktree-&lt;name&gt; from the case's current commit, unless you pick another below.</span>
+            </div>
+            <details class="worktree-advanced">
+              <summary>Branch and start point</summary>
+              <div class="form-row">
+                <label for="worktreeBranch">Branch</label>
+                <input type="text" id="worktreeBranch" maxlength="200" placeholder="worktree-<name>" autocomplete="off" autocapitalize="off" spellcheck="false">
+              </div>
+              <div class="form-row">
+                <label for="worktreeBase">Start from</label>
+                <input type="text" id="worktreeBase" maxlength="200" placeholder="HEAD" autocomplete="off" autocapitalize="off" spellcheck="false">
+                <span class="form-hint">A branch, tag or commit. Default: the case's current commit (HEAD).</span>
+              </div>
+            </details>
+            <div class="worktree-form-error" id="worktreeFormError" role="alert" hidden></div>
+          </fieldset>
+        </div>
+        <div class="form-actions">
+          <button type="button" class="wt-btn" onclick="app.closeWorktreeModal()">Close</button>
+          <button type="button" class="wt-btn wt-btn-primary" id="worktreeCreateBtn" onclick="app.createWorktreeFromModal()">Create &amp; start session</button>
+        </div>
+      </div>
+    </div>
+
     <!-- App Settings Modal -->
     <div class="modal" id="appSettingsModal">
       <div class="modal-backdrop" onclick="app.closeAppSettings()"></div>
@@ -3663,6 +3721,11 @@
             <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
             Create New Case
           </button>
+          <!-- The selected case's git worktrees (session-ui.js openWorktreeModal). -->
+          <button class="btn-toolbar btn-case-create-mobile btn-case-worktrees-mobile" onclick="app.showWorktreesFromMobile()">
+            <span aria-hidden="true">&#x2442;</span>
+            Worktrees
+          </button>
         </div>
       </div>
     </div>

src/web/public/keyboard-accessory.js

@@ -1282,11 +1282,11 @@ const KeyboardAccessoryBar = {
         <textarea class="paste-textarea prompt-composer-textarea" aria-label="Prompt" placeholder="Write your prompt…" autocorrect="on" autocapitalize="sentences" spellcheck="true"></textarea>
         <div class="paste-actions prompt-composer-actions">
           <button type="button" class="prompt-composer-terminal">Use terminal keyboard</button>
-          <button type="button" class="paste-image">🖼 Image</button>
+          <button type="button" class="paste-image">📎 Attach</button>
           <button type="button" class="paste-cancel">Cancel</button>
           <button type="button" class="paste-send">Send</button>
         </div>
-        <input type="file" class="paste-file-input" accept="image/*,video/*" multiple hidden>
+        <input type="file" class="paste-file-input" accept="image/*,video/*,.pdf,.docx,.pptx,.xlsx,.zip,.txt,.md,.csv,.tsv,.json,.log,.yaml,.yml,.xml" multiple hidden>
       </div>
     `;
 
@@ -1354,7 +1354,7 @@ const KeyboardAccessoryBar = {
         const currentSendButton = currentOverlay?.querySelector('.paste-send');
         if (currentImageButton) {
           currentImageButton.disabled = count > 0;
-          currentImageButton.textContent = count > 0 ? 'Uploading…' : '🖼 Image';
+          currentImageButton.textContent = count > 0 ? 'Uploading…' : '📎 Attach';
         }
         if (currentSendButton) currentSendButton.disabled = count > 0;
         const currentTerminalButton = currentOverlay?.querySelector('.prompt-composer-terminal');
@@ -1469,13 +1469,13 @@ const KeyboardAccessoryBar = {
   /** Show a paste overlay for iOS compatibility.
    *  Handles three input paths from one dialog:
    *   - Text: long-press the textarea → Paste → Send (unchanged).
-   *   - Image (picker): the "Image" button opens a native file picker
-   *     (accept=image/*,video/* → camera / photo library / files), the most reliable
-   *     way to attach a photo on mobile.
-   *   - Image (paste): if the browser exposes image blobs on the textarea's
+   *   - File (picker): the "Attach" button opens a native file picker
+   *     (accept=image/*,video/* plus the document extensions → camera / photo
+   *     library / files), the most reliable way to attach anything on mobile.
+   *   - File (paste): if the browser exposes file blobs on the textarea's
    *     paste event, we intercept them and upload directly. Support is spotty
    *     on mobile, so it is a best-effort enhancement layered on the picker.
-   *  All image paths reuse app._uploadAndInsertImages() (image-input.js), which
+   *  All upload paths reuse app._uploadAndInsertImages() (image-input.js), which
    *  uploads to /api/sessions/:id/paste-image and inserts the saved path. */
   pasteFromClipboard() {
     if (typeof app === 'undefined' || !app.activeSessionId) return;
@@ -1488,13 +1488,13 @@ const KeyboardAccessoryBar = {
     overlay.className = 'paste-overlay';
     overlay.innerHTML = `
       <div class="paste-dialog">
-        <textarea class="paste-textarea" placeholder="Long-press to paste text — or tap 🖼 to attach a photo or video"></textarea>
+        <textarea class="paste-textarea" placeholder="Long-press to paste text — or tap 📎 to attach a file"></textarea>
         <div class="paste-actions">
-          <button class="paste-image">🖼 Image</button>
+          <button class="paste-image">📎 Attach</button>
           <button class="paste-cancel">Cancel</button>
           <button class="paste-send">Send</button>
         </div>
-        <input type="file" class="paste-file-input" accept="image/*,video/*" multiple hidden>
+        <input type="file" class="paste-file-input" accept="image/*,video/*,.pdf,.docx,.pptx,.xlsx,.zip,.txt,.md,.csv,.tsv,.json,.log,.yaml,.yml,.xml" multiple hidden>
       </div>
     `;
 
@@ -1519,8 +1519,8 @@ const KeyboardAccessoryBar = {
       if (this._sendBracketedPaste(sessionId, text, 'Paste')) close();
     };
 
-    // Filter to images and videos, close the dialog, and hand off to the shared
-    // upload+insert pipeline. Returns true if any image was handled.
+    // Filter to what the server admits, close the dialog, and hand off to the
+    // shared upload+insert pipeline. Returns true if any file was handled.
     const handleImages = (files) => {
       const images = Array.from(files || []).filter((f) => app._promptAttachKind(f));
       if (images.length === 0) return false;
@@ -1530,7 +1530,7 @@ const KeyboardAccessoryBar = {
       return true;
     };
 
-    // Image picker (camera / photo library) — the reliable mobile path.
+    // File picker (camera / photo library / files) — the reliable mobile path.
     overlay.querySelector('.paste-image').addEventListener('click', () => fileInput.click());
     fileInput.addEventListener('change', () => handleImages(fileInput.files));
 

src/web/public/respawn-ui.js

@@ -597,8 +597,18 @@ Object.assign(CodemanApp.prototype, {
     // Update local cache + legacy localStorage
     this._serverRespawnPresets = custom;
     localStorage.setItem('codeman-respawn-presets', JSON.stringify(custom));
-    // Persist to server (cross-device sync)
-    this._apiPut('/api/settings', { respawnPresets: custom }).catch(() => {});
+    // Persist to server (cross-device sync). Not for a non-admin in multi-user mode: the
+    // presets are a key of the server-wide settings.json there, and its PUT is admin-only
+    // (403), so they are kept as their own on this device and win over the server's on the
+    // next load (_rememberOwnSetting, settings-ui.js). A PUT refused that way (sent before the
+    // role was known) marks the page read-only for the writes after it.
+    if (this._settingsReadOnly?.()) {
+      this._rememberOwnSetting?.('respawnPresets', custom);
+      return;
+    }
+    this._apiPut('/api/settings', { respawnPresets: custom })
+      .then((res) => this._noteSettingsWriteRefusal?.(res))
+      .catch(() => {});
   },
 
   renderPresetDropdown() {

src/web/public/session-ui.js

@@ -92,7 +92,7 @@ const RUN_MODE_LAUNCH = {
   },
   deepseek: {
     label: 'DeepSeek',
-    installHint: 'DeepSeek Harness CLI (dsh) not found. Install with: npm install -g @deepseek-ai/dsh',
+    installHint: 'DeepSeek Harness CLI (dsh) not found. Install with: npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)',
     // The two-part availability check is deliberate. `dsh` being installed is
     // not enough — DeepSeek ships no terminal front door, so a box can have a
     // perfect binary and nothing a pane can run.
@@ -128,14 +128,37 @@ const CASE_PICKER_REFRESH_MS = 5000;
 /**
  * Action rows at the bottom of the toolbar case picker. They replaced the "+"
  * and gear buttons that sat beside the picker (owner, 1.36.0 beta): the same two
- * actions, one click away, without two extra controls in the toolbar. The arrow
- * keys reach them after the last case; Enter or a click runs `run`.
+ * actions, one click away, without two extra controls in the toolbar, and the git
+ * worktrees of the selected case joined them. The arrow keys reach them after the
+ * last case; Enter or a click runs `run`.
  */
 const CASE_PICKER_ACTIONS = [
   { id: 'add', icon: '+', label: 'New or link a case…', run: (app) => app.showCreateCaseModal() },
   { id: 'settings', icon: '\u2699', label: 'Case settings…', run: (app) => app.toggleCaseSettings() },
+  // The selected case's git worktrees (openWorktreeModal below): a row here rather than a
+  // toolbar button, for the same reason the two above replaced theirs.
+  { id: 'worktrees', icon: '⑂', label: 'Git worktrees…', run: (app) => app.openWorktreeModal() },
 ];
 
+/** A worktree name the server accepts (src/git-worktrees.ts `worktreeNameError`), checked before the POST. */
+const WORKTREE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * The Codeman-managed worktree a working directory IS: `{ caseName, name, path }` when it is
+ * exactly `<case path>/.claude/worktrees/<name>` of a local case in `cases`, else null. Lexical
+ * on purpose (the browser cannot resolve links): the server re-checks every removal against the
+ * case's own repository, so a stale or wrong match can only be refused, never act elsewhere.
+ */
+function managedWorktreeOfDir(workingDir, cases) {
+  if (typeof workingDir !== 'string') return null;
+  const m = /^(.+)\/\.claude\/worktrees\/([^/]+)\/?$/.exec(workingDir);
+  if (!m || !WORKTREE_NAME_RE.test(m[2]) || m[2].includes('..')) return null;
+  const owner = (cases || []).find(
+    (c) => c && c.path === m[1] && c.location !== 'remote' && c.location !== 'docker'
+  );
+  return owner ? { caseName: owner.name, name: m[2], path: workingDir.replace(/\/$/, '') } : null;
+}
+
 const EXTERNAL_CLI_MODES = new Set(Object.keys(RUN_MODE_LAUNCH));
 const BUILT_IN_RUN_MODES = new Set(['claude', 'shell', ...Object.keys(RUN_MODE_LAUNCH)]);
 
@@ -604,6 +627,9 @@ Object.assign(CodemanApp.prototype, {
   },
 
   async saveLastUsedCase(caseName) {
+    // Multi-user non-admin: lastUsedCase is a key of the server-wide settings.json, whose
+    // PUT is admin-only (403), so it is not sent (_settingsReadOnly, settings-ui.js).
+    if (this._settingsReadOnly?.()) return;
     try {
       await fetch('/api/settings', {
         method: 'PUT',
@@ -692,8 +718,18 @@ Object.assign(CodemanApp.prototype, {
     this._runMode = mode;
     try { localStorage.setItem('codeman_runMode', mode); } catch {}
     this._applyRunMode();
-    // Sync to server for cross-device persistence
-    this._apiPut('/api/settings', { runMode: mode }).catch(() => {});
+    // Sync to server for cross-device persistence. Not for a non-admin in multi-user mode,
+    // where settings.json is server-wide and its PUT admin-only: the mode is kept as their own
+    // on this device and wins over the server's on the next load (_rememberOwnSetting,
+    // settings-ui.js). A PUT refused that way (sent before the role was known) marks the page
+    // read-only for the writes after it (_noteSettingsWriteRefusal).
+    if (this._settingsReadOnly?.()) {
+      this._rememberOwnSetting?.('runMode', mode);
+    } else {
+      this._apiPut('/api/settings', { runMode: mode })
+        .then((res) => this._noteSettingsWriteRefusal?.(res))
+        .catch(() => {});
+    }
     // Close menu
     document.getElementById('runModeMenu')?.classList.remove('active');
   },
@@ -1919,12 +1955,16 @@ Object.assign(CodemanApp.prototype, {
   },
 
   async runClaude(options = {}) {
-    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // `options.worktree` ({ caseName, name, path }, from the worktree modal): the session runs in
+    // that git worktree of the case and its tab is named after the worktree.
+    const wt = options.worktree || null;
+    const caseName = wt ? wt.caseName : document.getElementById('quickStartCase').value || 'testcase';
+    const nameBase = wt ? wt.name : caseName;
     const tabCount = this._readTabCount(options.count);
     const group = options.tabGroupId ? { tabGroupId: options.tabGroupId } : {};
 
     const ownsLaunchTerminal = this._beginSessionLaunchStatus(
-      `Starting ${tabCount} Claude session(s) in ${caseName}...`
+      `Starting ${tabCount} Claude session(s) in ${wt ? `worktree ${wt.name} of ` : ''}${caseName}...`
     );
     // Focus terminal NOW, in the synchronous user-gesture context (button click).
     // iOS Safari ignores programmatic focus() after any await, so this must happen
@@ -1933,25 +1973,32 @@ Object.assign(CodemanApp.prototype, {
     this.terminal.focus();
 
     try {
-      // Get case path first
-      const caseRes = await fetch(`/api/cases/${caseName}`);
-      const caseLookup = await caseRes.json();
-      let caseData = caseLookup?.data ?? {};
+      let caseData;
+      if (wt) {
+        // A worktree is local by construction (the server refuses one for a remote or Docker
+        // case) and its folder came from the worktree list: no case lookup, never a scaffold.
+        caseData = { path: wt.path, location: 'local' };
+      } else {
+        // Get case path first
+        const caseRes = await fetch(`/api/cases/${caseName}`);
+        const caseLookup = await caseRes.json();
+        caseData = caseLookup?.data ?? {};
 
-      // Create the case only when the server says it does not exist. Any other
-      // failure (a linked folder on a mount that is not answering) must not
-      // scaffold a same-name local case that would then shadow the real one.
-      if (!caseData.path) {
-        if (caseLookup?.errorCode !== 'NOT_FOUND') throw new Error(caseLookup?.error || 'Case lookup failed');
-        const createCaseRes = await fetch('/api/cases', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ name: caseName, description: '' })
-        });
-        const createCaseData = await createCaseRes.json();
-        if (!createCaseData.success) throw new Error(createCaseData.error || 'Failed to create case');
-        // API returns { success, data: { case: { name, path } } }
-        caseData = createCaseData.data.case;
+        // Create the case only when the server says it does not exist. Any other
+        // failure (a linked folder on a mount that is not answering) must not
+        // scaffold a same-name local case that would then shadow the real one.
+        if (!caseData.path) {
+          if (caseLookup?.errorCode !== 'NOT_FOUND') throw new Error(caseLookup?.error || 'Case lookup failed');
+          const createCaseRes = await fetch('/api/cases', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: caseName, description: '' })
+          });
+          const createCaseData = await createCaseRes.json();
+          if (!createCaseData.success) throw new Error(createCaseData.error || 'Failed to create case');
+          // API returns { success, data: { case: { name, path } } }
+          caseData = createCaseData.data.case;
+        }
       }
 
       const workingDir = caseData.path;
@@ -2024,8 +2071,8 @@ Object.assign(CodemanApp.prototype, {
 
       let firstSessionId = null;
 
-      // Find the highest existing w-number for THIS case to avoid duplicates
-      const startNumber = this._nextCaseSessionStartNumber(caseName);
+      // Find the highest existing w-number for THIS case (or worktree) to avoid duplicates
+      const startNumber = this._nextCaseSessionStartNumber(nameBase);
 
       // Get global Ralph tracker setting
       const ralphEnabled = this.isRalphTrackerEnabledByDefault();
@@ -2033,7 +2080,7 @@ Object.assign(CodemanApp.prototype, {
       // Create all sessions in parallel for speed
       const sessionNames = [];
       for (let i = 0; i < tabCount; i++) {
-        sessionNames.push(`w${startNumber + i}-${caseName}`);
+        sessionNames.push(`w${startNumber + i}-${nameBase}`);
       }
 
       // Build env overrides from global + case settings (case overrides global)
@@ -2140,40 +2187,49 @@ Object.assign(CodemanApp.prototype, {
   },
 
   async runShell(options = {}) {
-    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // `options.worktree`: see runClaude.
+    const wt = options.worktree || null;
+    const caseName = wt ? wt.caseName : document.getElementById('quickStartCase').value || 'testcase';
+    const nameBase = wt ? wt.name : caseName;
     // Run Shell reads the toolbar's one instance stepper, like every other run*();
     // its own second `− 1 +` group (#shellCount) was removed (#428).
     const shellCount = this._readTabCount(options.count);
     const group = options.tabGroupId ? { tabGroupId: options.tabGroupId } : {};
 
     const ownsLaunchTerminal = this._beginSessionLaunchStatus(
-      `Starting ${shellCount} Shell session(s) in ${caseName}...`,
+      `Starting ${shellCount} Shell session(s) in ${wt ? `worktree ${wt.name} of ` : ''}${caseName}...`,
       '1;33'
     );
 
     try {
-      // Get the case path
-      const caseRes = await fetch(`/api/cases/${caseName}`);
-      const caseLookup = await caseRes.json();
-      let caseData = caseLookup?.data ?? {};
+      let caseData;
+      if (wt) {
+        // Local by construction, folder from the worktree list (see runClaude).
+        caseData = { path: wt.path, location: 'local' };
+      } else {
+        // Get the case path
+        const caseRes = await fetch(`/api/cases/${caseName}`);
+        const caseLookup = await caseRes.json();
+        caseData = caseLookup?.data ?? {};
 
-      // Create the case only when the server says it does not exist. Any other
-      // failure (a linked folder on a mount that is not answering) must not
-      // scaffold a same-name local case that would then shadow the real one.
-      if (!caseData.path) {
-        if (caseLookup?.errorCode !== 'NOT_FOUND') throw new Error(caseLookup?.error || 'Case lookup failed');
-        const createCaseRes = await fetch('/api/cases', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ name: caseName, description: '' })
-        });
-        const createCaseData = await createCaseRes.json();
-        if (!createCaseData.success) throw new Error(createCaseData.error || 'Failed to create case');
-        // API returns { success, data: { case: { name, path } } }
-        caseData = createCaseData.data.case;
+        // Create the case only when the server says it does not exist. Any other
+        // failure (a linked folder on a mount that is not answering) must not
+        // scaffold a same-name local case that would then shadow the real one.
+        if (!caseData.path) {
+          if (caseLookup?.errorCode !== 'NOT_FOUND') throw new Error(caseLookup?.error || 'Case lookup failed');
+          const createCaseRes = await fetch('/api/cases', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: caseName, description: '' })
+          });
+          const createCaseData = await createCaseRes.json();
+          if (!createCaseData.success) throw new Error(createCaseData.error || 'Failed to create case');
+          // API returns { success, data: { case: { name, path } } }
+          caseData = createCaseData.data.case;
+        }
       }
 
-      const selectedCase = (this.cases || []).find(c => c.name === caseName);
+      const selectedCase = wt ? null : (this.cases || []).find(c => c.name === caseName);
       const isRemoteCase =
         caseData.location === 'remote' ||
         caseData.location === 'docker' ||
@@ -2206,13 +2262,13 @@ Object.assign(CodemanApp.prototype, {
         return;
       }
 
-      // Find the highest existing s-number for THIS case to avoid duplicates
-      const startNumber = this._nextCaseSessionStartNumber(caseName, 's');
+      // Find the highest existing s-number for THIS case (or worktree) to avoid duplicates
+      const startNumber = this._nextCaseSessionStartNumber(nameBase, 's');
 
       // Create all shell sessions in parallel
       const sessionNames = [];
       for (let i = 0; i < shellCount; i++) {
-        sessionNames.push(`s${startNumber + i}-${caseName}`);
+        sessionNames.push(`s${startNumber + i}-${nameBase}`);
       }
 
       // Step 1: Create all sessions in parallel
@@ -2331,16 +2387,19 @@ Object.assign(CodemanApp.prototype, {
         buildConfig: () => null,
       });
     if (!entry) throw new Error(`Unknown run mode: ${mode}`);
-    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // `options.worktree`: see runClaude. Quick-start resolves it server-side (`worktree`), so the
+    // session starts through the same path as any other, only in the worktree's folder.
+    const wt = options.worktree || null;
+    const caseName = wt ? wt.caseName : document.getElementById('quickStartCase').value || 'testcase';
     // Remote/docker cases run the CLI on the OTHER side — the local status
     // probe and the local-only config/env below don't apply (quick-start
     // rejects them for remote cases).
-    const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
+    const _runLoc = wt ? 'local' : (this.cases || []).find(c => c.name === caseName)?.location;
     const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
 
     const tabCount = this._readTabCount(options.count);
     const ownsLaunchTerminal = this._beginSessionLaunchStatus(
-      `Starting ${tabCount} ${entry.label} session(s) in ${caseName}...`
+      `Starting ${tabCount} ${entry.label} session(s) in ${wt ? `worktree ${wt.name} of ` : ''}${caseName}...`
     );
     // Focus in sync gesture context (see runClaude comment)
     this.terminal.focus();
@@ -2369,13 +2428,15 @@ Object.assign(CodemanApp.prototype, {
       // into `claude --settings`); none of these CLIs has an /effort. Each of
       // the eight bodies this launcher replaced carried that rule as a comment.
       const firstSessionId = await this._launchQuickStartInstances(
-        caseName,
+        // Only names the tabs (`w<n>-<name>`): a worktree session is named after the worktree.
+        wt ? wt.name : caseName,
         tabCount,
         entry.label,
         (sessionName) => ({
           caseName,
           mode,
           sessionName,
+          ...(wt ? { worktree: wt.name } : {}),
           ...(options.tabGroupId ? { tabGroupId: options.tabGroupId } : {}),
           ...(isRemote ? {} : {
             ...(entry.buildConfig(globalSettings) || {}),
@@ -4833,6 +4894,16 @@ Object.assign(CodemanApp.prototype, {
   },
 
   async saveCaseOrder(order) {
+    // Multi-user non-admin: the case order is ONE server-wide list (settings.json caseOrder)
+    // and PUT /api/cases/order is admin-only (403), so the move is not sent: say why, and put
+    // the list back the way the server orders it.
+    if (this._settingsReadOnly?.()) {
+      this.showToast('Server-wide settings can only be changed by an admin', 'warning');
+      const select = document.getElementById('quickStartCase');
+      await this.loadQuickStartCases(select?.value);
+      this.renderCaseManageList();
+      return;
+    }
     try {
       await fetch('/api/cases/order', {
         method: 'PUT',
@@ -5007,6 +5078,404 @@ Object.assign(CodemanApp.prototype, {
     // Remove animation class after it plays
     setTimeout(() => modal.classList.remove('from-mobile'), 300);
   },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Git worktrees of a case (src/git-worktrees.ts, routes/worktree-routes.ts)
+  // ═══════════════════════════════════════════════════════════════
+  //
+  // One dialog per case: its worktrees (Open, Remove), and a form for a new one that starts a
+  // session in it at once. Sessions start through run() with `options.worktree`, so every run
+  // mode keeps its own launch path (POST /api/sessions for claude and shell, quick-start with
+  // `worktree` for the rest). Everything git or the user named (worktree and branch names, paths,
+  // git's own refusals) renders through textContent and carries data-i18n-skip.
+
+  /** Open the worktree dialog for `caseName` (default: the case selected in the toolbar). */
+  openWorktreeModal(caseName) {
+    const modal = document.getElementById('worktreeModal');
+    const name = caseName || document.getElementById('quickStartCase')?.value || '';
+    if (!modal || !name) return;
+    this._worktreeCase = name;
+    this._worktreeData = null;
+    this._worktreeRemoveConfirm = null;
+    this._worktreeRemoveError = null;
+    const caseLabel = document.getElementById('worktreeModalCase');
+    if (caseLabel) caseLabel.textContent = name;
+    for (const id of ['worktreeName', 'worktreeBranch', 'worktreeBase']) {
+      const input = document.getElementById(id);
+      if (input) input.value = '';
+    }
+    this._setWorktreeFormError('');
+    this._fillWorktreeModeSelect();
+    this._renderWorktreeList();
+    modal.classList.add('active');
+    void this._loadWorktrees();
+    // Not on a touch device: focusing the field raises the on-screen keyboard over the list.
+    const touch = typeof MobileDetection !== 'undefined' && MobileDetection.isTouchDevice?.();
+    if (!touch) setTimeout(() => document.getElementById('worktreeName')?.focus?.(), 50);
+  },
+
+  /** The phone case sheet's Worktrees button: the selected case's worktrees. */
+  showWorktreesFromMobile() {
+    this.closeMobileCasePicker();
+    this.openWorktreeModal();
+  },
+
+  closeWorktreeModal() {
+    const modal = document.getElementById('worktreeModal');
+    // Called on every Escape (app.js): a no-op unless the dialog is open.
+    if (!modal || !modal.classList.contains('active')) return;
+    modal.classList.remove('active');
+    this._worktreeCase = null;
+    this._worktreeLoadSeq = (this._worktreeLoadSeq || 0) + 1;
+  },
+
+  _worktreesUrl(caseName, suffix = '') {
+    return `/api/cases/${encodeURIComponent(caseName)}/worktrees${suffix}`;
+  },
+
+  /** A JSON call that keeps the server's error text, which `_apiJson()` drops. */
+  async _worktreeRequest(path, opts = {}) {
+    const res = await this._api(path, opts);
+    if (!res) return { ok: false, error: 'Codeman did not answer.' };
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      /* an empty or non-JSON body: the status says enough */
+    }
+    if (res.ok && body?.success !== false) return { ok: true, data: body?.data ?? body };
+    return { ok: false, status: res.status, error: body?.error || `Request failed (${res.status})` };
+  },
+
+  async _loadWorktrees() {
+    const caseName = this._worktreeCase;
+    if (!caseName) return;
+    const seq = (this._worktreeLoadSeq = (this._worktreeLoadSeq || 0) + 1);
+    this._setWorktreeStatus('Loading worktrees…');
+    const r = await this._worktreeRequest(this._worktreesUrl(caseName));
+    if (seq !== this._worktreeLoadSeq || caseName !== this._worktreeCase) return;
+    this._worktreeData = r.ok ? r.data : null;
+    this._setWorktreeStatus(r.ok ? '' : r.error, !r.ok);
+    // A case that cannot list worktrees (not a repository, a Docker or remote case) cannot get one.
+    const createBtn = document.getElementById('worktreeCreateBtn');
+    if (createBtn) createBtn.disabled = !r.ok;
+    this._renderWorktreeList();
+  },
+
+  _setWorktreeStatus(text, isError = false) {
+    const el = document.getElementById('worktreeStatus');
+    if (!el) return;
+    el.textContent = text || '';
+    el.hidden = !text;
+    el.classList.toggle('worktree-status-error', !!isError);
+  },
+
+  _setWorktreeFormError(text) {
+    const el = document.getElementById('worktreeFormError');
+    if (!el) return;
+    el.textContent = text || '';
+    el.hidden = !text;
+  },
+
+  /** Every enabled, installed run mode, the shell last; the Run button's mode preselected. */
+  _fillWorktreeModeSelect() {
+    const select = document.getElementById('worktreeMode');
+    if (!select) return;
+    // Every launchable registry entry (agents and the shell), as data: no id is branched on here.
+    const modes = [];
+    for (const cli of registryCliCatalog()) {
+      if (cli.enabled && cli.available !== false) modes.push({ id: cli.id, label: cli.label });
+    }
+    if (modes.length === 0) {
+      // A cached page from before the registry catalogue: the built-in modes.
+      modes.push({ id: 'claude', label: 'Claude Code' });
+      for (const [id, entry] of Object.entries(RUN_MODE_LAUNCH)) modes.push({ id, label: entry.label });
+      modes.push({ id: 'shell', label: 'Terminal / Shell' });
+    }
+    select.replaceChildren(
+      ...modes.map((m) => {
+        const option = document.createElement('option');
+        option.value = m.id;
+        option.textContent = m.label;
+        return option;
+      })
+    );
+    const current = this._runMode || 'claude';
+    select.value = modes.some((m) => m.id === current) ? current : modes[0].id;
+  },
+
+  _selectedWorktreeMode() {
+    return document.getElementById('worktreeMode')?.value || this._runMode || 'claude';
+  },
+
+  _renderWorktreeList() {
+    const list = document.getElementById('worktreeList');
+    if (!list) return;
+    list.replaceChildren();
+    const data = this._worktreeData;
+    if (!data) return;
+    for (const wt of data.worktrees) list.appendChild(this._buildWorktreeRow(wt));
+    if (!data.worktrees.some((wt) => wt.managed)) {
+      const empty = document.createElement('div');
+      empty.className = 'worktree-empty';
+      empty.textContent = 'No worktrees yet. Create one below.';
+      list.appendChild(empty);
+    }
+  },
+
+  _buildWorktreeRow(wt) {
+    const row = document.createElement('div');
+    row.className = 'worktree-row' + (wt.managed ? ' worktree-row--managed' : '');
+    const head = document.createElement('div');
+    head.className = 'worktree-row-head';
+
+    const label = document.createElement('span');
+    label.className = 'worktree-row-name';
+    label.setAttribute('data-i18n-skip', '');
+    label.textContent = wt.managed ? `⑂ ${wt.name}` : wt.path.split('/').pop() || wt.path;
+    head.appendChild(label);
+
+    const badge = (text, extra = '', skip = false) => {
+      const b = document.createElement('span');
+      b.className = `worktree-badge${extra ? ` ${extra}` : ''}`;
+      if (skip) b.setAttribute('data-i18n-skip', '');
+      b.textContent = text;
+      head.appendChild(b);
+    };
+    if (wt.branch) badge(wt.branch, 'worktree-badge-branch', true);
+    else if (wt.detached) badge('detached HEAD', 'worktree-badge-branch');
+    if (wt.main) badge('main checkout');
+    else if (!wt.managed) badge('not created by Codeman', 'worktree-badge-dim');
+    if (wt.locked) badge('locked', 'worktree-badge-warn');
+    if (wt.prunable) badge('missing', 'worktree-badge-warn');
+    if (wt.sessionCount > 0) {
+      badge(`${wt.sessionCount} session${wt.sessionCount === 1 ? '' : 's'}`, 'worktree-badge-live');
+    }
+
+    if (wt.managed) {
+      const actions = document.createElement('span');
+      actions.className = 'worktree-row-actions';
+      // A worktree whose folder is gone (`prunable`) cannot host a session, but Remove still
+      // clears git's record of it, which is what frees its name for a new worktree.
+      if (!wt.prunable) {
+        const open = document.createElement('button');
+        open.type = 'button';
+        open.className = 'wt-btn wt-btn-sm';
+        open.textContent = 'Open';
+        open.title = 'Start a session in this worktree';
+        open.addEventListener('click', () => void this.openWorktreeSession(wt.name));
+        actions.appendChild(open);
+      }
+      const remove = document.createElement('button');
+      remove.type = 'button';
+      remove.className = 'wt-btn wt-btn-sm wt-btn-danger';
+      remove.textContent = 'Remove…';
+      remove.addEventListener('click', () => this.confirmWorktreeRemoval(wt.name));
+      actions.appendChild(remove);
+      head.appendChild(actions);
+    }
+    row.appendChild(head);
+
+    // A managed worktree's folder is always `.claude/worktrees/<name>` of the case: say just that,
+    // so the long repository prefix (already on the main row) is not repeated on every row.
+    const path = document.createElement('div');
+    path.className = 'worktree-row-path';
+    path.setAttribute('data-i18n-skip', '');
+    path.textContent = wt.managed ? `.claude/worktrees/${wt.name}` : this._shortenHomePath(wt.path);
+    path.title = wt.path;
+    row.appendChild(path);
+
+    if (wt.managed && this._worktreeRemoveConfirm === wt.name) row.appendChild(this._buildWorktreeRemoveConfirm(wt));
+    return row;
+  },
+
+  _buildWorktreeRemoveConfirm(wt) {
+    const box = document.createElement('div');
+    box.className = 'worktree-remove-confirm';
+    const note = document.createElement('p');
+    note.className = 'worktree-remove-note';
+    note.textContent = wt.prunable
+      ? 'Its folder is gone. Removing it clears the record git keeps of it, so the name can be used again.'
+      : 'git worktree remove refuses while the worktree has uncommitted or untracked files. Codeman never forces it.';
+    box.appendChild(note);
+
+    let checkbox = null;
+    if (wt.branch) {
+      const lbl = document.createElement('label');
+      lbl.className = 'worktree-remove-branch';
+      checkbox = document.createElement('input');
+      checkbox.type = 'checkbox';
+      const text = document.createElement('span');
+      text.textContent = 'Also delete its branch (git branch -d keeps a branch that is not merged)';
+      lbl.append(checkbox, text);
+      box.appendChild(lbl);
+    }
+
+    if (this._worktreeRemoveError?.name === wt.name) {
+      const err = document.createElement('pre');
+      err.className = 'worktree-remove-error';
+      err.setAttribute('data-i18n-skip', '');
+      err.textContent = this._worktreeRemoveError.text;
+      box.appendChild(err);
+    }
+
+    const buttons = document.createElement('div');
+    buttons.className = 'worktree-remove-buttons';
+    const cancel = document.createElement('button');
+    cancel.type = 'button';
+    cancel.className = 'wt-btn wt-btn-sm';
+    cancel.textContent = 'Cancel';
+    cancel.addEventListener('click', () => this.cancelWorktreeRemoval());
+    const confirm = document.createElement('button');
+    confirm.type = 'button';
+    confirm.className = 'wt-btn wt-btn-sm wt-btn-danger';
+    confirm.textContent = 'Remove worktree';
+    confirm.addEventListener('click', async () => {
+      confirm.disabled = true;
+      try {
+        await this.removeWorktreeFromModal(wt.name, !!checkbox?.checked);
+      } finally {
+        confirm.disabled = false;
+      }
+    });
+    buttons.append(cancel, confirm);
+    box.appendChild(buttons);
+    return box;
+  },
+
+  confirmWorktreeRemoval(name) {
+    this._worktreeRemoveConfirm = name;
+    this._worktreeRemoveError = null;
+    this._renderWorktreeList();
+  },
+
+  cancelWorktreeRemoval() {
+    this._worktreeRemoveConfirm = null;
+    this._worktreeRemoveError = null;
+    this._renderWorktreeList();
+  },
+
+  async removeWorktreeFromModal(name, deleteBranch) {
+    const caseName = this._worktreeCase;
+    if (!caseName) return;
+    const r = await this.removeCaseWorktree(caseName, name, deleteBranch);
+    if (caseName !== this._worktreeCase) return;
+    if (!r.ok) {
+      this._worktreeRemoveError = { name, text: r.error };
+      this._renderWorktreeList();
+      return;
+    }
+    this._worktreeRemoveConfirm = null;
+    this._worktreeRemoveError = null;
+    await this._loadWorktrees();
+  },
+
+  /** DELETE one worktree (never forced); shared by the dialog and Close Session. Toasts the outcome. */
+  async removeCaseWorktree(caseName, name, deleteBranch) {
+    const query = deleteBranch ? '?deleteBranch=true' : '';
+    const r = await this._worktreeRequest(this._worktreesUrl(caseName, `/${encodeURIComponent(name)}${query}`), {
+      method: 'DELETE',
+    });
+    if (r.ok) {
+      const removed = r.data?.removed || { name };
+      if (removed.branchError) {
+        this.showToast?.(
+          `Worktree ${removed.name} removed. Branch ${removed.branch} kept: ${removed.branchError}`,
+          'warning'
+        );
+      } else if (removed.branchDeleted) {
+        this.showToast?.(`Worktree ${removed.name} and branch ${removed.branch} removed`, 'success');
+      } else {
+        this.showToast?.(`Worktree ${removed.name} removed`, 'success');
+      }
+    }
+    return r;
+  },
+
+  async createWorktreeFromModal() {
+    const caseName = this._worktreeCase;
+    if (!caseName) return;
+    const name = (document.getElementById('worktreeName')?.value || '').trim();
+    const branch = (document.getElementById('worktreeBranch')?.value || '').trim();
+    const base = (document.getElementById('worktreeBase')?.value || '').trim();
+    if (!WORKTREE_NAME_RE.test(name) || name.includes('..') || /\.(lock)?$/i.test(name)) {
+      this._setWorktreeFormError(
+        'Name: letters, digits, ".", "_" and "-", starting with a letter or digit, at most 64 characters.'
+      );
+      return;
+    }
+    this._setWorktreeFormError('');
+    const mode = this._selectedWorktreeMode();
+    const btn = document.getElementById('worktreeCreateBtn');
+    if (btn) btn.disabled = true;
+    try {
+      const r = await this._worktreeRequest(this._worktreesUrl(caseName), {
+        method: 'POST',
+        body: { name, ...(branch ? { branch } : {}), ...(base ? { base } : {}) },
+      });
+      if (caseName !== this._worktreeCase) return;
+      if (!r.ok) {
+        this._setWorktreeFormError(r.error);
+        return;
+      }
+      const created = r.data.worktree;
+      this.showToast?.(`Worktree ${created.name} created on branch ${created.branch}`, 'success');
+      this.closeWorktreeModal();
+      await this._launchInWorktree({ caseName, name: created.name, path: created.path }, mode);
+    } finally {
+      if (btn) btn.disabled = false;
+    }
+  },
+
+  async openWorktreeSession(name) {
+    const caseName = this._worktreeCase;
+    const wt = this._worktreeData?.worktrees?.find((w) => w.managed && w.name === name);
+    if (!caseName || !wt) return;
+    const mode = this._selectedWorktreeMode();
+    this.closeWorktreeModal();
+    await this._launchInWorktree({ caseName, name, path: wt.path }, mode);
+  },
+
+  /**
+   * Start ONE session of `mode` in a worktree through run(), the Run button's own entry (its
+   * launch lock, its per-mode paths), with the same temporary `_runMode` swap the custom-model
+   * entries use, so the Run button's chosen mode is untouched afterwards.
+   */
+  async _launchInWorktree(worktree, mode) {
+    if (this._runInFlight) {
+      this.showToast?.('A launch is already in progress', 'info');
+      return;
+    }
+    const previous = this._runMode;
+    this._runMode = mode || previous;
+    try {
+      await this.run({ count: 1, worktree });
+    } finally {
+      this._runMode = previous;
+    }
+  },
+
+  /** The Codeman-managed worktree a session runs in, or null (see managedWorktreeOfDir). */
+  _managedWorktreeOfSession(session) {
+    if (!session || session.remote || session.docker) return null;
+    return managedWorktreeOfDir(session.workingDir, this.cases);
+  },
+
+  /**
+   * Close Session's "Kill & remove worktree", once the session is gone. git's refusal (a dirty
+   * tree) is the answer: the worktree stays, and the toast says why and opens the dialog.
+   */
+  async _removeWorktreeAfterClose(wt, deleteBranch) {
+    const r = await this.removeCaseWorktree(wt.caseName, wt.name, deleteBranch);
+    if (r.ok) {
+      if (this._worktreeCase === wt.caseName) void this._loadWorktrees();
+      return;
+    }
+    this.showToast?.(`Worktree ${wt.name} was kept: ${r.error}`, 'error', {
+      duration: 15000,
+      action: { label: 'Worktrees…', onClick: () => this.openWorktreeModal(wt.caseName) },
+    });
+  },
 });
 
 Object.defineProperty(CodemanApp.prototype, 'runMode', {

src/web/public/settings-ui.js

@@ -373,6 +373,39 @@ Object.assign(CodemanApp.prototype, {
     return select?.value.trim() || '';
   },
 
+  /**
+   * Announce a new release once per browser: one toast naming its headline changes.
+   * The notes come from /whats-new.json, which `npm run version-packages` regenerates from
+   * CHANGELOG.md for each release. A browser that has never seen any version just records the
+   * current one, so a fresh install is not greeted with "what's new".
+   */
+  async checkWhatsNew(runningVersion) {
+    if (this._whatsNewChecked) return;
+    this._whatsNewChecked = true;
+    const KEY = 'codeman-whats-new-seen';
+    let seen = null;
+    try { seen = localStorage.getItem(KEY); } catch { /* storage blocked: skip the announcement */ return; }
+    if (seen === runningVersion) return;
+    const remember = () => { try { localStorage.setItem(KEY, runningVersion); } catch { /* ignore */ } };
+    if (!seen) { remember(); return; }
+    try {
+      const res = await fetch('/whats-new.json', { cache: 'no-cache' });
+      if (!res.ok) return;
+      const notes = await res.json();
+      if (notes?.version !== runningVersion || !Array.isArray(notes.highlights) || !notes.highlights.length) return;
+      const shown = notes.highlights.slice(0, 3).join(' · ');
+      const more = notes.highlights.length > 3 ? ` (+${notes.highlights.length - 3} more)` : '';
+      remember();
+      this.showToast(`Codeman updated to v${runningVersion}: ${shown}${more}`, 'info', {
+        duration: 20000,
+        action: {
+          label: "See what's new",
+          onClick: () => window.open(`https://github.com/Ark0N/Codeman/releases/tag/codeman%40${runningVersion}`, '_blank', 'noopener'),
+        },
+      });
+    } catch { /* offline or malformed: try again next load */ }
+  },
+
   openAppSettings() {
     // Load current settings
     const settings = this.loadAppSettingsFromStorage();
@@ -678,6 +711,10 @@ Object.assign(CodemanApp.prototype, {
     // Activate focus trap
     this.activeFocusTrap = new FocusTrap(modal);
     this.activeFocusTrap.activate();
+
+    // Multi-user non-admin only: remember what the form shows now, so Save can tell a real
+    // change to a server-wide setting from an untouched one (see the method).
+    this._captureSettingsFormBaseline();
   },
 
   /**
@@ -1847,8 +1884,12 @@ Object.assign(CodemanApp.prototype, {
           regenBtn.textContent = 'Regenerate QR';
           regenBtn.style.cssText = 'margin-top:8px;padding:4px 12px;background:var(--bg-elevated);border:1px solid var(--border);border-radius:4px;color:var(--text-secondary);cursor:pointer;font-size:11px';
           regenBtn.onclick = () => {
+            // A refusal is not a success: in multi-user mode this is admin-only (403).
             fetch('/api/tunnel/qr/regenerate', { method: 'POST' })
-              .then(() => this.showToast('QR code regenerated', 'success'))
+              .then((res) => {
+                if (!res.ok) throw new Error(`HTTP ${res.status}`);
+                this.showToast('QR code regenerated', 'success');
+              })
               .catch(() => this.showToast('Failed to regenerate QR', 'error'));
           };
           const card = container.parentElement;
@@ -1943,6 +1984,11 @@ Object.assign(CodemanApp.prototype, {
   async toggleTunnelFromWelcome() {
     const btn = document.getElementById('welcomeTunnelBtn');
     if (!btn) return;
+    // The tunnel is a server-wide setting (PUT /api/settings), admin-only in multi-user mode.
+    if (this._settingsReadOnly()) {
+      this.showToast('Server-wide settings can only be changed by an admin', 'warning');
+      return;
+    }
     const isActive = btn.classList.contains('active');
     btn.disabled = true;
     try {
@@ -2269,12 +2315,22 @@ Object.assign(CodemanApp.prototype, {
   async _handleTunnelEnableRefusal(res) {
     if (!res || res.ok) return false;
     let message = 'Tunnel refused: set CODEMAN_PASSWORD before exposing Codeman publicly.';
+    let errorCode = '';
     try {
       const body = await res.json();
       if (body && body.error) message = body.error;
+      if (body && typeof body.errorCode === 'string') errorCode = body.errorCode;
     } catch {
       /* non-JSON body — use the default message */
     }
+    // A non-admin in multi-user mode: PUT /api/settings is admin-only there (403 FORBIDDEN).
+    // That is not the no-password refusal below, so no security prompt and no retry. The
+    // callers skip the PUT for a known non-admin; this covers a role that had not resolved yet.
+    if (res.status === 403 && errorCode === 'FORBIDDEN') {
+      this._dismissTunnelConnecting?.();
+      this.showToast('Server-wide settings can only be changed by an admin', 'warning');
+      return true;
+    }
     // 403 = the no-password safety refusal (COD-55). Warn loudly and let the
     // operator acknowledge the risk; on confirm, retry with explicit acknowledgment.
     if (res.status === 403) {
@@ -2323,6 +2379,12 @@ Object.assign(CodemanApp.prototype, {
   },
 
   async _tunnelPanelToggle(enable) {
+    // The tunnel is a server-wide setting (PUT /api/settings), admin-only in multi-user mode.
+    if (this._settingsReadOnly()) {
+      this.showToast('Server-wide settings can only be changed by an admin', 'warning');
+      this.closeTunnelPanel();
+      return;
+    }
     try {
       const res = await fetch('/api/settings', {
         method: 'PUT',
@@ -2659,6 +2721,13 @@ Object.assign(CodemanApp.prototype, {
       },
     };
 
+    // One-shot form read for _captureSettingsFormBaseline(): hand back what the form
+    // shows, before anything below is checked, stored, applied or sent.
+    if (this._readSettingsFormOnce === true) {
+      this._readSettingsFormOnce = false;
+      return settings;
+    }
+
     // SettingsUpdateSchema is .strict() and checks codexModel with this same
     // pattern, so one bad character 400s the WHOLE settings PUT while the toast
     // still says "Settings saved". Refuse it here, before anything is persisted.
@@ -2681,6 +2750,14 @@ Object.assign(CodemanApp.prototype, {
     // general-settings DOM), so the fresh rebuild would drop them on every save.
     if (_prev.shortcutOverrides !== undefined) settings.shortcutOverrides = _prev.shortcutOverrides;
 
+    // Multi-user mode, signed in as a non-admin: settings.json is one file for the whole
+    // server and PUT /api/settings answers 403 (system-routes.ts), so nothing is sent
+    // below. The per-device keys still save here exactly as before; every SYNCED key
+    // keeps the server's value, which the next page load would put back anyway, so this
+    // device never shows a server-wide change that did not happen.
+    const settingsReadOnly = this._settingsReadOnly();
+    const syncedChangeRefused = settingsReadOnly && this._keepServerSyncedSettings(settings, _prev);
+
     // Save to localStorage
     this.saveAppSettingsToStorage(settings);
     this._updateLocalEchoState();
@@ -2901,18 +2978,31 @@ Object.assign(CodemanApp.prototype, {
     let webhookError = '';
     let serverSaved = false;
     try {
-      const res = await this._apiPut('/api/settings', {
+      // A non-admin's save is not sent at all (see settingsReadOnly above): the server
+      // would refuse it with a 403, the plan-usage collection flip included.
+      const res = settingsReadOnly ? null : await this._apiPut('/api/settings', {
         ...serverSettings,
         ...(_chipFlip !== undefined ? { showPlanUsageLimits: _chipFlip } : {}),
         notificationPreferences: notifPrefsToSave,
         voiceSettings,
       });
 
+      // Multi-user mode, a non-admin whose role was not known when this save started
+      // (/api/me had not answered, or failed and admin-ui.js fell back to a single-user
+      // admin): the server refused the PUT as admin-only. End it the way a known non-admin's save
+      // ends: every synced key back to the server's value on this device, and the one admin
+      // toast below instead of "Settings saved". The page is read-only from here on.
+      const refusedAsNonAdmin = !settingsReadOnly && (await this._noteSettingsWriteRefusal(res));
+      if (refusedAsNonAdmin) {
+        this._keepServerSyncedSettings(settings, _prev);
+        this.saveAppSettingsToStorage(settings);
+      }
+
       // COD-55: the server refuses an unauthenticated public tunnel with a 403 — which
       // rejects the WHOLE settings PUT. Surface the message and revert the tunnel toggle
       // (in the UI + localStorage) so it doesn't look enabled. Other settings persisted
       // to localStorage above still apply locally.
-      if (settings.tunnelEnabled && (await this._handleTunnelEnableRefusal(res))) {
+      if (!refusedAsNonAdmin && settings.tunnelEnabled && (await this._handleTunnelEnableRefusal(res))) {
         settings.tunnelEnabled = false;
         this.saveAppSettingsToStorage(settings);
         const cb = document.getElementById('appSettingsTunnelEnabled');
@@ -2925,8 +3015,9 @@ Object.assign(CodemanApp.prototype, {
       // evidence the server kept the flags the Apply refresh below reads.
       serverSaved = !!res?.ok;
 
-      // Save model configuration separately
-      await this.saveModelConfigFromSettings();
+      // Save model configuration separately. For a non-admin it is not sent either, and the
+      // answer says whether this save would have changed it.
+      const modelConfigRefused = (await this.saveModelConfigFromSettings()) === true;
 
       // The webhook is server state in its own 0600 file (its URL is a secret, kept out of
       // settings.json), so like the model config above it is saved beside the settings PUT, not in
@@ -2935,12 +3026,18 @@ Object.assign(CodemanApp.prototype, {
       webhookError = this._webhookPending() ? await this.saveWebhook() : '';
       if (webhookError) {
         this.showToast(`Settings saved, but not the webhook: ${webhookError}`, 'warning');
+      } else if (syncedChangeRefused || modelConfigRefused || refusedAsNonAdmin) {
+        // ONE toast for the whole save, and only when the user really changed a server-wide
+        // setting: a non-admin saving a font size hears "Settings saved" as everyone does.
+        // A refused PUT always gets it: the server said this user is not an admin.
+        this.showToast('Saved on this device. Server-wide settings can only be changed by an admin.', 'warning');
       } else {
         this.showToast(keepOpen ? 'Settings applied' : 'Settings saved', 'success');
       }
 
-      // Show tunnel-specific feedback if toggled on
-      if (settings.tunnelEnabled) {
+      // Show tunnel-specific feedback if toggled on (never for a non-admin, whose save
+      // starts nothing: the box only shows what the server already has)
+      if (settings.tunnelEnabled && !settingsReadOnly && !refusedAsNonAdmin) {
         this.showToast('Tunnel starting — QR code will appear when ready...', 'info');
       }
     } catch (err) {
@@ -2966,7 +3063,9 @@ Object.assign(CodemanApp.prototype, {
     // gestureControlEnabled from settings.json), so a change only takes effect on
     // reload. Reload when it actually changed — the server PUT above already
     // persisted the new value.
-    if (settings.gestureControlEnabled !== _prevGestureEnabled) {
+    // `?? false`: a non-admin's save puts a synced key the server never stored back to
+    // absent (_keepServerSyncedSettings), and absent means off, as in _prevGestureEnabled.
+    if ((settings.gestureControlEnabled ?? false) !== _prevGestureEnabled) {
       this.showToast(
         settings.gestureControlEnabled ? 'Enabling gesture control — reloading…' : 'Disabling gesture control — reloading…',
         'info'
@@ -2975,6 +3074,147 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * True only for a signed-in NON-ADMIN in multi-user mode, where every server-wide settings
+   * write is refused with 403 FORBIDDEN (PUT /api/settings, PUT /api/execution/model-config and
+   * PUT /api/cases/order: settings.json is one file for the whole server). Single-user mode and
+   * admins answer false. Read at call time, because `window.__codemanUser` resolves after page
+   * load (admin-ui.js fetches /api/me). Also true once the server has refused one of these
+   * writes as admin-only on this page (_noteSettingsWriteRefusal): before /api/me answers, and
+   * after it failed (admin-ui.js then falls back to a single-user admin), the role alone reads
+   * as writable. Other modules call it as
+   * `this._settingsReadOnly?.()`, so a harness that loads one of them without this file reads
+   * it as writable, which is what an admin gets.
+   */
+  _settingsReadOnly() {
+    if (this._settingsWriteForbidden === true) return true;
+    // typeof guard: the load path calls this, and some vm harnesses define no `window`.
+    const me = (typeof window !== 'undefined' && window.__codemanUser) || {};
+    return !!(me.multiUser && me.role !== 'admin');
+  },
+
+  /**
+   * Whether `res` (a settings write's response) is the multi-user admin-only refusal: 403 with
+   * errorCode FORBIDDEN. The tunnel's no-password refusal is a 403 too, with another code, and
+   * is not this. When it is, the page reads as read-only from now on (_settingsReadOnly), so a
+   * write sent before the role was known is the last one. Reads a clone, so the caller can
+   * still read the body.
+   * @returns {Promise<boolean>}
+   */
+  async _noteSettingsWriteRefusal(res) {
+    if (!res || res.status !== 403) return false;
+    let body = null;
+    try {
+      body = await (typeof res.clone === 'function' ? res.clone() : res).json();
+    } catch {
+      return false;
+    }
+    if (body?.errorCode !== 'FORBIDDEN') return false;
+    this._settingsWriteForbidden = true;
+    return true;
+  },
+
+  /**
+   * Where a non-admin's OWN run mode and respawn presets live (multi-user mode). Both are keys of
+   * the server-wide settings.json, whose PUT is admin-only, so this user's picks are kept on this
+   * device under their name instead (_rememberOwnSetting) and put back over the server's on every
+   * page load (_applyOwnSettings): loadAppSettingsFromServer() writes the server's values into
+   * `codeman_runMode` and `codeman-respawn-presets` each time, which used to drop them on reload.
+   */
+  _ownSettingsKey() {
+    const me = (typeof window !== 'undefined' && window.__codemanUser) || {};
+    return `codeman:own-settings:${me.username || ''}`;
+  },
+
+  _readOwnSettings() {
+    try {
+      const own = JSON.parse(localStorage.getItem(this._ownSettingsKey()) || '{}');
+      return own && typeof own === 'object' && !Array.isArray(own) ? own : {};
+    } catch {
+      return {};
+    }
+  },
+
+  /** Keep a non-admin's own pick of a server-wide `key` on this device (see _ownSettingsKey). */
+  _rememberOwnSetting(key, value) {
+    try {
+      const own = this._readOwnSettings();
+      own[key] = value;
+      localStorage.setItem(this._ownSettingsKey(), JSON.stringify(own));
+    } catch {
+      /* storage unavailable: the pick lasts until the next page load */
+    }
+  },
+
+  /**
+   * A non-admin's own run mode and respawn presets win over the server's (see _ownSettingsKey).
+   * Called after the server's values are applied at load, and again on `codeman:me`, because the
+   * role can resolve either side of that load. A no-op for admins and single-user mode.
+   */
+  _applyOwnSettings() {
+    if (!this._settingsReadOnly()) return;
+    const own = this._readOwnSettings();
+    if (Array.isArray(own.respawnPresets)) {
+      this._serverRespawnPresets = own.respawnPresets;
+      try { localStorage.setItem('codeman-respawn-presets', JSON.stringify(own.respawnPresets)); } catch {}
+    }
+    if (typeof own.runMode === 'string' && own.runMode) {
+      this.runMode = own.runMode;
+      try { localStorage.setItem('codeman_runMode', own.runMode); } catch {}
+      this._applyRunMode?.();
+    }
+  },
+
+  /**
+   * What the App Settings form showed when it opened, read the way saveAppSettings() reads it
+   * (its one-shot `_readSettingsFormOnce` form read), so a non-admin's save can tell whether the
+   * user changed a SYNCED setting. The stored blob cannot answer that: a key no admin has ever
+   * saved is absent from it while the form shows the default, which would read as a change on
+   * every save. Taken only for a non-admin; nobody else's save asks for it.
+   */
+  _captureSettingsFormBaseline() {
+    this._settingsFormBaseline = null;
+    if (!this._settingsReadOnly()) return;
+    this._readSettingsFormOnce = true;
+    let pending;
+    try {
+      pending = this.saveAppSettings();
+    } finally {
+      // Consumed by the read itself; cleared here too in case it threw before reaching it.
+      this._readSettingsFormOnce = false;
+    }
+    Promise.resolve(pending)
+      .then((form) => {
+        this._settingsFormBaseline = form && typeof form === 'object' ? form : null;
+      })
+      .catch(() => {});
+  },
+
+  /**
+   * A non-admin's save in multi-user mode (saveAppSettings): put every SYNCED key of `settings`
+   * back to the value this device last had from the server (`prev`; deleted when it had none),
+   * and answer whether the form changed one since it opened. Synced means outside the per-device
+   * `displayKeys` merge policy of loadAppSettingsFromServer() (_displaySettingKeySet(), the one
+   * list both read): those are the keys the server's settings.json overwrites on every page load.
+   * A per-device key is left exactly as the user set it.
+   * @returns {boolean} true when the user changed at least one synced setting
+   */
+  _keepServerSyncedSettings(settings, prev) {
+    const displayKeys = this._displaySettingKeySet();
+    // Without a baseline (the form was read before the role was known) the stored blob stands
+    // in, and a key it lacks is not counted: no toast is better than one on every save.
+    const baseline = this._settingsFormBaseline || prev || {};
+    let changed = false;
+    for (const key of Object.keys(settings)) {
+      // shortcutOverrides is carried over from `prev` already and never comes from the form.
+      if (displayKeys.has(key) || key === 'shortcutOverrides') continue;
+      if (key in baseline && JSON.stringify(settings[key]) !== JSON.stringify(baseline[key])) changed = true;
+      if (prev && key in prev) settings[key] = prev[key];
+      else delete settings[key];
+    }
+    return changed;
+  },
+
   /**
    * After Apply: bring the groups whose contents depend on a SAVED value up to date without
    * reopening the modal. openAppSettings does the same on open; this is the part of it that
@@ -3025,10 +3265,12 @@ Object.assign(CodemanApp.prototype, {
     } catch (err) {
       console.warn('Failed to load model config:', err);
     }
+    // What the form shows now, so a non-admin's save can tell whether it was changed.
+    this._modelConfigBaseline = JSON.stringify(this._modelConfigFromSettingsForm());
   },
 
-  // Save model configuration from settings modal to server
-  async saveModelConfigFromSettings() {
+  /** The model configuration as the settings modal's form shows it (the PUT body). */
+  _modelConfigFromSettingsForm() {
     const defaultModelEl = document.getElementById('appSettingsDefaultModel');
     const showRecsEl = document.getElementById('appSettingsShowModelRecommendations');
     const exploreEl = document.getElementById('appSettingsModelExplore');
@@ -3042,11 +3284,26 @@ Object.assign(CodemanApp.prototype, {
     if (testEl?.value) agentTypeOverrides.test = testEl.value;
     if (reviewEl?.value) agentTypeOverrides.review = reviewEl.value;
 
-    const config = {
+    return {
       defaultModel: defaultModelEl?.value || '',
       showRecommendations: showRecsEl?.checked ?? true,
       agentTypeOverrides,
     };
+  },
+
+  /**
+   * Save model configuration from settings modal to server.
+   * @returns {Promise<boolean|undefined>} true only when a non-admin in multi-user mode changed it:
+   *   the config is a key of the server-wide settings.json and its PUT is admin-only (403), so it is
+   *   not sent, and saveAppSettings() folds this into its one admin-only toast
+   */
+  async saveModelConfigFromSettings() {
+    const config = this._modelConfigFromSettingsForm();
+
+    if (this._settingsReadOnly()) {
+      const baseline = this._modelConfigBaseline;
+      return typeof baseline === 'string' && JSON.stringify(config) !== baseline;
+    }
 
     try {
       await fetch('/api/execution/model-config', {
@@ -4331,6 +4588,37 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * The per-device DISPLAY keys. They are device-specific (mobile vs desktop) and must not be
+   * synced from the server, to avoid overriding mobile defaults: loadAppSettingsFromServer()
+   * seeds one from the server only when this device has no value for it. A non-admin's save in
+   * multi-user mode reads the same split (_keepServerSyncedSettings()), so the list lives here,
+   * once, and is there even when GET /api/settings failed at load.
+   * NOTE: Feature toggles (subagentTrackingEnabled, imageWatcherEnabled, ralphTrackerEnabled)
+   * are NOT display keys: they control server-side behavior and must sync from server.
+   */
+  _displaySettingKeySet() {
+    const displayKeys = new Set([
+      'showFontControls', 'showSystemStats', 'headerStatsStyle', 'showTokenCount', 'showCost',
+      'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
+      'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
+      'subagentActiveTabOnly', 'tabTwoRows', 'showTabCliLogos', 'tabOrientation', 'tabRailWidth', 'tabRailDetail', 'tabRailSort', 'tabArrangement', 'tabStateOrder', 'sessionListLayout', 'sessionSidebarFontSize', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
+      'skin', 'showPlanUsageLimits', 'showAttachmentsButton', 'showFileViewerButton', 'webglRendererEnabled',
+      'terminalFontFamily', 'terminalFontWeight', 'terminalFontWeightBold',
+      'language',
+      'terminalWheelLocalScrollback',
+      'autoCopySelection', 'copyStripMargin',
+      'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds',
+      'showTabDetachButton',
+      'mobileOverviewEnabled',
+      'sessionLineageLines',
+      'showSplitButton',
+      'showTileGridButton',
+      'tileDetachEnabled',
+    ]);
+    return displayKeys;
+  },
+
   async loadAppSettingsFromServer(settingsPromise = null) {
     // One-time migration: showPlanUsageLimits became a per-device display setting.
     // Before this, it synced from the server, so the (separate) mobile settings blob
@@ -4356,28 +4644,9 @@ Object.assign(CodemanApp.prototype, {
       if (settings) {
         // Extract notification prefs before merging app settings
         const { notificationPreferences, voiceSettings, respawnPresets, runMode, ...appSettings } = settings;
-        // Filter out display settings — these are device-specific (mobile vs desktop)
-        // and should not be synced from the server to avoid overriding mobile defaults.
-        // NOTE: Feature toggles (subagentTrackingEnabled, imageWatcherEnabled, ralphTrackerEnabled)
-        // are NOT display keys — they control server-side behavior and must sync from server.
-        const displayKeys = new Set([
-          'showFontControls', 'showSystemStats', 'headerStatsStyle', 'showTokenCount', 'showCost',
-          'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
-          'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
-          'subagentActiveTabOnly', 'tabTwoRows', 'showTabCliLogos', 'tabOrientation', 'tabRailWidth', 'tabRailDetail', 'tabRailSort', 'tabArrangement', 'tabStateOrder', 'sessionListLayout', 'sessionSidebarFontSize', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
-          'skin', 'showPlanUsageLimits', 'showAttachmentsButton', 'showFileViewerButton', 'webglRendererEnabled',
-          'terminalFontFamily', 'terminalFontWeight', 'terminalFontWeightBold',
-          'language',
-          'terminalWheelLocalScrollback',
-          'autoCopySelection', 'copyStripMargin',
-          'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds',
-          'showTabDetachButton',
-          'mobileOverviewEnabled',
-          'sessionLineageLines',
-          'showSplitButton',
-          'showTileGridButton',
-          'tileDetachEnabled',
-        ]);
+        // Display settings are device-specific (mobile vs desktop) and must not be synced
+        // from the server: see _displaySettingKeySet().
+        const displayKeys = this._displaySettingKeySet();
         // The plan-usage chip is a PER-DEVICE display setting (desktop default ON,
         // handheld default OFF): desktop can show it while mobile stays hidden. Drop
         // the server's stored value here so it is NEVER seeded into a device that
@@ -4428,14 +4697,17 @@ Object.assign(CodemanApp.prototype, {
           this._serverRespawnPresets = respawnPresets;
           // Also update localStorage for offline access
           localStorage.setItem('codeman-respawn-presets', JSON.stringify(respawnPresets));
-        } else {
-          // Migration: push existing localStorage presets to server
+        } else if (!this._settingsReadOnly()) {
+          // Migration: push existing localStorage presets to server. Not for a non-admin in
+          // multi-user mode: the presets are a server-wide setting there (admin-only PUT).
           const localPresets = localStorage.getItem('codeman-respawn-presets');
           if (localPresets) {
             const parsed = JSON.parse(localPresets);
             if (parsed.length > 0) {
               this._serverRespawnPresets = parsed;
-              this._apiPut('/api/settings', { respawnPresets: parsed }).catch(() => {});
+              this._apiPut('/api/settings', { respawnPresets: parsed })
+                .then((res) => this._noteSettingsWriteRefusal(res))
+                .catch(() => {});
             }
           }
         }
@@ -4447,6 +4719,10 @@ Object.assign(CodemanApp.prototype, {
           this._applyRunMode();
         }
 
+        // Multi-user non-admin: their own run mode and presets, kept on this device, win over
+        // the server's just applied (no-op otherwise; `codeman:me` below covers a late role).
+        this._applyOwnSettings();
+
         return merged;
       }
     } catch (err) {
@@ -4723,6 +4999,14 @@ Object.assign(CodemanApp.prototype, {
       this.showToast?.('Shortcut must include Ctrl, Cmd, or Alt', 'error');
       return;
     }
+    // Refuse a chord something else already owns: the registry dispatches the first match,
+    // so a duplicate would silently take over (or lose to) the other action.
+    const taken = this.findShortcutConflict(e, shortcutId);
+    if (taken) {
+      this.renderShortcutSettingsList();
+      this.showToast?.(`${this.describeShortcutEvent(e)} is already used by ${taken}`, 'error');
+      return;
+    }
     const modifiers = [];
     if (e.ctrlKey) modifiers.push('ctrl');
     if (e.metaKey) modifiers.push('meta');
@@ -4739,7 +5023,70 @@ Object.assign(CodemanApp.prototype, {
     this.renderShortcutSettingsList();
   },
 
+  /** Label of the action that already owns the chord in `e`, or '' when it is free. */
+  findShortcutConflict(e, shortcutId) {
+    // Chords the keydown handlers claim before (or outside) the registry: they are fixed, so a
+    // rebind onto one of them would be dead or would hijack it. Alt+1-9 switch tabs by index
+    // (the document handler does not exclude Cmd); Ctrl/Shift+Enter insert a newline and
+    // Ctrl/Cmd+V pastes, and the user-bound gate sits above those branches in the xterm handler.
+    if (e.altKey && !e.ctrlKey && !e.shiftKey && /^Digit[1-9]$/.test(e.code || '')) {
+      return 'Switch to Tab N';
+    }
+    // (Alt+Shift+Enter is the tile grid's Zoom chord, a registry entry, so Alt stays free.)
+    if (e.key === 'Enter' && !e.altKey && (e.ctrlKey || e.shiftKey)) return 'Insert Newline';
+    if ((e.ctrlKey || e.metaKey) && !e.altKey && !e.shiftKey && String(e.key).toLowerCase() === 'v') return 'Paste';
+    if (typeof this.getShortcutRegistry !== 'function' || typeof this.matchesShortcutEvent !== 'function') return '';
+    const other = this.getShortcutRegistry().find(
+      (shortcut) =>
+        shortcut.id !== shortcutId && !shortcut.disabled && Array.isArray(shortcut.bindings) && this.matchesShortcutEvent(e, shortcut)
+    );
+    return other ? other.label : '';
+  },
+
+  /**
+   * Label of the action that already owns a chord in `shortcut`'s bindings, or ''. Used when a
+   * binding comes back without a capture (re-enable, Reset), where the chord may have been
+   * given to another action in the meantime.
+   */
+  findShortcutBindingConflict(shortcut) {
+    for (const binding of shortcut?.bindings || []) {
+      const mods = binding.modifiers || [];
+      const taken = this.findShortcutConflict(
+        {
+          ctrlKey: mods.includes('ctrl'),
+          metaKey: mods.includes('meta'),
+          shiftKey: mods.includes('shift'),
+          altKey: mods.includes('alt'),
+          key: binding.key || '',
+          code: binding.code || '',
+        },
+        shortcut.id
+      );
+      if (taken) return taken;
+    }
+    return '';
+  },
+
+  describeShortcutEvent(e) {
+    const parts = [];
+    if (e.ctrlKey) parts.push('Ctrl');
+    if (e.metaKey) parts.push('Meta');
+    if (e.shiftKey) parts.push('Shift');
+    if (e.altKey) parts.push('Alt');
+    parts.push(e.key && e.key.length === 1 ? e.key.toUpperCase() : e.key || e.code);
+    return parts.join('+');
+  },
+
   resetShortcutOverride(shortcutId) {
+    // Reset puts the default chord back (and re-enables the row): refuse when another action
+    // has taken that chord since, instead of leaving two actions on one key.
+    const fallback = typeof DEFAULT_SHORTCUTS !== 'undefined' ? DEFAULT_SHORTCUTS.find((d) => d.id === shortcutId) : null;
+    const taken = fallback ? this.findShortcutBindingConflict(fallback) : '';
+    if (taken) {
+      this.renderShortcutSettingsList();
+      this.showToast?.(`The default chord is already used by ${taken}`, 'error');
+      return;
+    }
     const settings = this.loadAppSettingsFromStorage();
     const shortcutOverrides = { ...(settings.shortcutOverrides || {}) };
     delete shortcutOverrides[shortcutId];
@@ -4749,6 +5096,17 @@ Object.assign(CodemanApp.prototype, {
   },
 
   toggleShortcutEnabled(shortcutId, enabled) {
+    if (enabled) {
+      // Re-enabling brings the row's chord back into play: leave it disabled when another action
+      // has been bound to that chord while it was off.
+      const shortcut = this.getShortcutRegistry?.().find((s) => s.id === shortcutId);
+      const taken = this.findShortcutBindingConflict(shortcut);
+      if (taken) {
+        this.renderShortcutSettingsList();
+        this.showToast?.(`Its chord is already used by ${taken}`, 'error');
+        return;
+      }
+    }
     const settings = this.loadAppSettingsFromStorage();
     const shortcutOverrides = { ...(settings.shortcutOverrides || {}) };
     shortcutOverrides[shortcutId] = { ...(shortcutOverrides[shortcutId] || {}), disabled: !enabled };
@@ -4781,6 +5139,9 @@ Object.assign(CodemanApp.prototype, {
 // all, and a module-level statement that throws there fails the whole file's
 // evaluation, not just this feature.
 document.addEventListener?.('codeman:me', () => {
+  // A non-admin's own run mode and respawn presets (multi-user mode) win over the server's,
+  // which the settings load may already have applied before the role was known.
+  window.app?._applyOwnSettings?.();
   window.app?._applyCustomModelAdminGate?.();
   window.app?._applyCliManagementAdminGate?.();
   window.app?._applyMcpSyncAdminGate?.();

src/web/public/styles.css

@@ -7793,6 +7793,9 @@ html[data-skin="og"] .welcome-primary:hover {
 .mobile-case-picker-footer {
   padding: 12px 20px 16px;
   border-top: 1px solid rgba(255, 255, 255, 0.1);
+  /* Create New Case and Worktrees share the row, half each. */
+  display: flex;
+  gap: 8px;
 }
 
 .btn-case-create-mobile {
@@ -8148,6 +8151,249 @@ html[data-skin="og"] .welcome-primary:hover {
   border-top: 1px solid var(--border);
 }
 
+/* Close Session: "Kill & remove worktree" (a session in a Codeman-managed git
+   worktree only). The wrapper re-asserts [hidden]: it lays out as a column. */
+.close-option-worktree {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+.close-option-worktree[hidden] {
+  display: none;
+}
+.close-option-worktree-branch {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.4rem;
+  font-size: 0.75rem;
+  color: var(--text-dim);
+  padding: 0 0.25rem;
+  cursor: pointer;
+}
+.close-option-worktree-branch input {
+  margin-top: 0.1rem;
+}
+
+/* Git worktrees dialog (session-ui.js openWorktreeModal). Its own small button
+   set: the skin block greys `.btn-toolbar.btn-primary` on non-OG skins, and this
+   dialog needs a primary action that reads as one on every skin. */
+.modal-content.worktree-modal {
+  max-width: 640px;
+  max-height: 88vh;
+  display: flex;
+  flex-direction: column;
+}
+.worktree-modal > .modal-body {
+  overflow-y: auto;
+  min-height: 0;
+}
+.worktree-modal-case {
+  font-family: 'SF Mono', Monaco, monospace;
+  font-weight: 500;
+  color: var(--text-dim);
+}
+.worktree-intro {
+  margin: 0 0 0.6rem;
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+.worktree-status {
+  font-size: 0.78rem;
+  color: var(--text-dim);
+  margin-bottom: 0.6rem;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.worktree-status[hidden],
+.worktree-form-error[hidden] {
+  display: none;
+}
+.worktree-status-error,
+.worktree-form-error {
+  color: var(--red);
+}
+.worktree-form-error {
+  font-size: 0.75rem;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  margin-top: 0.25rem;
+}
+.worktree-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  margin-bottom: 0.9rem;
+}
+.worktree-row {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 0.5rem 0.65rem;
+  background: var(--control-bg);
+}
+.worktree-row--managed {
+  border-color: var(--border-light);
+}
+.worktree-row-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.35rem 0.45rem;
+}
+.worktree-row-name {
+  font-weight: 600;
+  font-size: 0.85rem;
+  color: var(--text);
+  overflow-wrap: anywhere;
+}
+.worktree-badge {
+  font-size: 0.66rem;
+  line-height: 1.5;
+  padding: 0 0.4rem;
+  border-radius: 999px;
+  border: 1px solid var(--border-light);
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+.worktree-badge-branch {
+  font-family: 'SF Mono', Monaco, monospace;
+  color: var(--accent);
+  border-color: rgba(var(--accent-rgb), 0.35);
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+.worktree-badge-dim {
+  color: var(--text-muted);
+}
+.worktree-badge-warn {
+  color: var(--yellow);
+  border-color: var(--yellow);
+}
+.worktree-badge-live {
+  color: var(--green);
+  border-color: var(--green);
+}
+.worktree-row-actions {
+  display: inline-flex;
+  gap: 0.35rem;
+  margin-left: auto;
+}
+.worktree-row-path {
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 0.68rem;
+  color: var(--text-muted);
+  margin-top: 0.25rem;
+  overflow-wrap: anywhere;
+}
+.worktree-empty {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+  padding: 0.25rem 0.1rem;
+}
+.worktree-remove-confirm {
+  margin-top: 0.5rem;
+  padding-top: 0.5rem;
+  border-top: 1px dashed var(--border-light);
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+}
+.worktree-remove-note {
+  margin: 0;
+  font-size: 0.72rem;
+  color: var(--text-dim);
+}
+.worktree-remove-branch {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.4rem;
+  font-size: 0.72rem;
+  color: var(--text-dim);
+  cursor: pointer;
+}
+.worktree-remove-error {
+  margin: 0;
+  font-size: 0.72rem;
+  color: var(--red);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  background: rgba(224, 99, 99, 0.08);
+  border-radius: 6px;
+  padding: 0.4rem 0.5rem;
+}
+.worktree-remove-buttons {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.4rem;
+}
+.worktree-mode-row {
+  max-width: 320px;
+}
+.worktree-new {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 0.6rem 0.75rem 0.4rem;
+  margin: 0;
+  min-width: 0;
+}
+.worktree-new > legend {
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--text-dim);
+  padding: 0 0.3rem;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+.worktree-advanced {
+  margin-bottom: 0.5rem;
+}
+.worktree-advanced > summary {
+  cursor: pointer;
+  font-size: 0.75rem;
+  color: var(--text-dim);
+  margin-bottom: 0.5rem;
+}
+.wt-btn {
+  font: inherit;
+  font-size: 0.8rem;
+  padding: 0.4rem 0.85rem;
+  border-radius: var(--btn-radius);
+  border: 1px solid var(--control-border);
+  background: var(--control-bg);
+  color: var(--text);
+  cursor: pointer;
+  transition: background var(--transition-smooth), border-color var(--transition-smooth);
+}
+.wt-btn:hover:not(:disabled) {
+  background: var(--control-bg-hover);
+  border-color: var(--control-border-hover);
+}
+.wt-btn:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+.wt-btn-sm {
+  font-size: 0.72rem;
+  padding: 0.2rem 0.6rem;
+}
+.wt-btn-primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--accent-ink);
+  font-weight: 600;
+}
+.wt-btn-primary:hover:not(:disabled) {
+  background: var(--accent-hover);
+  border-color: var(--accent-hover);
+}
+.wt-btn-danger {
+  color: var(--red);
+  border-color: rgba(224, 99, 99, 0.45);
+}
+.wt-btn-danger:hover:not(:disabled) {
+  background: rgba(224, 99, 99, 0.12);
+  border-color: var(--red);
+}
+
 .modal-session-name {
   font-family: 'SF Mono', Monaco, monospace;
   font-size: 0.8rem;

src/web/public/terminal-tile.js

@@ -327,6 +327,7 @@
         ) {
           return false;
         }
+        if (ev.type === 'keydown' && global.app?.isUserBoundShortcutEvent?.(ev)) return false;
         if (ev.type === 'keydown' && global.app?.shouldOpenCommandPaletteFromShortcut?.(ev)) {
           return false;
         }

src/web/public/terminal-ui.js

@@ -749,6 +749,9 @@ Object.assign(CodemanApp.prototype, {
         return false;
       }
 
+      // A chord the user rebound to an app action (Settings -> Shortcuts) must not also type into the PTY.
+      if (ev.type === 'keydown' && this.isUserBoundShortcutEvent?.(ev)) return false;
+
       // Command palette chord (COD-153): keep it out of the PTY. The document
       // CAPTURE handler has already opened the palette by the time xterm sees
       // this keydown, but its preventDefault() does NOT stop xterm — without

src/web/public/whats-new.json

@@ -0,0 +1,13 @@
+{
+  "version": "1.42.0",
+  "highlights": [
+    "Git worktrees for a case (#625)",
+    "Codex sessions turn red when Codex asks you something (#624)",
+    "Prompt uploads take documents (#621)",
+    "Previous and Next Session are rebindable (#617)",
+    "A note after each update (#618)",
+    "Multi-user mode: only admins change server-wide settings",
+    "Codex submits long prompts (#628)",
+    "New Claude sessions in an untrusted folder (#634, #635)"
+  ]
+}

src/web/routes/case-routes.ts

@@ -60,6 +60,7 @@ import {
   isAdmin,
   isWorkingDirAllowed,
   ownerFor,
+  requireAdmin,
   resolveCasesDir,
   SETTINGS_PATH,
   validatePathWithinBase,
@@ -1665,7 +1666,13 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
 
   // ========== Reorder Cases ==========
 
-  app.put('/api/cases/order', async (req): Promise<ApiResponse<{ order: string[] }>> => {
+  app.put('/api/cases/order', async (req, reply): Promise<ApiResponse<{ order: string[] }> | undefined> => {
+    // `caseOrder` is ONE list in the server-wide settings.json, read by every user's
+    // GET /api/cases, so a non-admin's reorder would replace everyone's order (and
+    // publish their case names to every user through GET /api/settings). Admin-only in
+    // multi-user mode, like PUT /api/settings; a per-user order would need per-user
+    // storage. No-op in single-user mode.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     const { order } = parseBody(CaseOrderSchema, req.body, 'Invalid order data');
 
     try {

src/web/routes/index.ts

@@ -17,6 +17,7 @@ export { registerReadMyMindRoutes } from './readmymind-routes.js';
 export { registerGitStatusRoutes } from './git-status-routes.js';
 export { registerStatusTelemetryRoutes } from './status-telemetry-routes.js';
 export { registerCaseRoutes } from './case-routes.js';
+export { registerWorktreeRoutes } from './worktree-routes.js';
 export { registerSessionRoutes } from './session-routes.js';
 export { registerRespawnRoutes } from './respawn-routes.js';
 export { registerRalphRoutes } from './ralph-routes.js';

src/web/routes/ralph-routes.ts

@@ -16,6 +16,7 @@ import { SseEvent } from '../sse-events.js';
 import {
   autoConfigureRalph,
   getAuthUser,
+  isAdmin,
   ownerFor,
   resolveCasesDir,
   sessionCapacityMessage,
@@ -463,20 +464,25 @@ export function registerRalphRoutes(
       });
     }
 
-    // Save lastUsedCase
-    try {
-      let settings: Record<string, unknown> = {};
+    // Save lastUsedCase. It is a key of the server-wide settings.json, readable by every
+    // user through GET /api/settings, so a non-admin's case name is not written there in
+    // multi-user mode (writes are admin-only: PUT /api/settings). isAdmin is always true
+    // in single-user mode.
+    if (isAdmin(req)) {
       try {
-        settings = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf-8'));
+        let settings: Record<string, unknown> = {};
+        try {
+          settings = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf-8'));
+        } catch {
+          /* ignore */
+        }
+        settings.lastUsedCase = caseName;
+        const dir = dirname(SETTINGS_PATH);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        fs.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2)).catch(() => {}); // Ignore - persisting lastUsedCase is non-critical
       } catch {
-        /* ignore */
+        /* non-critical */
       }
-      settings.lastUsedCase = caseName;
-      const dir = dirname(SETTINGS_PATH);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-      fs.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2)).catch(() => {}); // Ignore - persisting lastUsedCase is non-critical
-    } catch {
-      /* non-critical */
     }
 
     const sessionId = session.id;

src/web/routes/session-routes.ts

@@ -13,6 +13,7 @@ import { execFile } from 'node:child_process';
 import fs from 'node:fs/promises';
 import { finished } from 'node:stream/promises';
 import { randomBytes, randomUUID } from 'node:crypto';
+import { isUtf8 } from 'node:buffer';
 import { performance } from 'node:perf_hooks';
 import {
   ApiErrorCode,
@@ -181,6 +182,7 @@ import {
   readDockerHosts,
   toSessionDocker,
 } from '../../docker-hosts.js';
+import { resolveCaseRepository, resolveManagedWorktree } from '../../git-worktrees.js';
 import { LRUMap } from '../../utils/lru-map.js';
 import { describeUnknownPath, probePathKind } from '../../utils/index.js';
 import { findLatestOmpSessionId } from '../../utils/omp-session-resolver.js';
@@ -323,18 +325,36 @@ export function stripInkRedrawBloat(buffer: string): string {
 }
 
 /**
- * Validate image bytes against a declared extension. Sniffs the first ~12 bytes
- * for a known magic-number signature. Defends against polyglots (e.g. HTML or
- * SVG disguised under a `Content-Type: image/png` header) and against simple
- * extension-only spoofing — both the multipart filename and the Content-Type
- * are attacker-controlled, the raw bytes are not.
+ * The text half of the document allowlist: these are judged on their encoding
+ * (valid UTF-8, no NUL byte) rather than on a signature, since plain text has none.
+ */
+const TEXT_UPLOAD_EXTS = new Set(['.txt', '.md', '.csv', '.tsv', '.json', '.log', '.yaml', '.yml', '.xml']);
+
+/**
+ * Validate upload bytes against a declared extension. Sniffs the first ~12 bytes
+ * for a known magic-number signature (a text file is instead required to be
+ * UTF-8 without a NUL byte, the one check plain text allows). Defends against
+ * polyglots (e.g. HTML or SVG disguised under a `Content-Type: image/png`
+ * header) and against simple extension-only spoofing — both the multipart
+ * filename and the Content-Type are attacker-controlled, the raw bytes are not.
+ * Fail-closed: an extension this function does not know is never a match.
  *
  * Signatures: https://en.wikipedia.org/wiki/List_of_file_signatures
  */
 export function imageMagicMatchesExt(data: Buffer, ext: string): boolean {
+  if (TEXT_UPLOAD_EXTS.has(ext)) return data.length > 0 && !data.includes(0) && isUtf8(data);
   if (data.length < 12) return false;
   const u32be = (off: number): number => data.readUInt32BE(off);
   switch (ext) {
+    case '.pdf':
+      // "%PDF-"
+      return u32be(0) === 0x25504446 && data[4] === 0x2d;
+    case '.docx':
+    case '.pptx':
+    case '.xlsx':
+    case '.zip':
+      // PK\x03\x04, the local-file header every non-empty zip (OOXML included) opens with
+      return u32be(0) === 0x504b0304;
     case '.png':
       return u32be(0) === 0x89504e47 && u32be(4) === 0x0d0a1a0a;
     case '.jpg':
@@ -428,11 +448,27 @@ async function ensureUploadDir(workingDir: string): Promise<string | null> {
   return uploadDir;
 }
 
+/**
+ * The part of an uploaded document's name that survives into the saved name,
+ * so `Q3 report (final).pdf` is findable as `paste-<ts>-<hex>-Q3-report-final.pdf`.
+ * Only `[A-Za-z0-9._-]` survive, runs of anything else become one `-`, and the
+ * result is capped at 40 chars; nothing in it can be a path separator or a
+ * second extension that matters (the allowlisted extension is appended after).
+ */
+function sanitizeUploadStem(filename: string): string {
+  const stem = basename(filename).replace(/\.[^.]*$/, '');
+  return stem
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, 40);
+}
+
 /** Open a fresh, uniquely named paste file for writing. */
-async function openPasteFile(imageDir: string, ext: string) {
+async function openPasteFile(imageDir: string, ext: string, stem = '') {
   // Date.now() collides on same-ms uploads from two tabs (last-write wins
   // silently). Append 8 hex chars so concurrent pastes get distinct names.
-  const filename = `paste-${Date.now()}-${randomBytes(4).toString('hex')}${ext}`;
+  // The `paste-` prefix is what the GC (paste-image-gc.ts) matches on.
+  const filename = `paste-${Date.now()}-${randomBytes(4).toString('hex')}${stem ? `-${stem}` : ''}${ext}`;
   const filepath = join(imageDir, filename);
   // O_EXCL: refuse to overwrite (collision is impossible with random suffix,
   // but defends against TOCTOU). O_NOFOLLOW: refuse if filepath is a symlink.
@@ -2037,7 +2073,7 @@ export function registerSessionRoutes(
     const stopDeathWatch = wantsWait ? watchForDeadWorker(ctx.mux, session, id) : () => {};
 
     // Write input to PTY. Direct write is synchronous; writeViaMux
-    // (tmux send-keys) is fire-and-forget to avoid blocking the HTTP response.
+    // (tmux paste + Enter) is fire-and-forget to avoid blocking the HTTP response.
     // Every write here is `fromUser`: this route carries a person's prompt, or an
     // agent's on their behalf, so it may name the tab (Ralph, respawn, cron and
     // approvals write through the session directly and never say so).
@@ -2060,7 +2096,7 @@ export function registerSessionRoutes(
     // A plain prompt (`<text>\r`) goes through the mux even when the caller did not
     // ask for it: written straight into the pane it arrives as one burst, and Claude
     // Code takes a long burst as a paste whose `\r` becomes a newline, so the prompt
-    // sat unsent (see isPlainPromptInput). The mux path types the text, presses Enter
+    // sat unsent (see isPlainPromptInput). The mux path pastes the text, presses Enter
     // separately and arms the SubmitVerifier. An explicit `useMux: false` keeps the
     // raw write for a caller that really wants it.
     const autoMux = useMux === undefined && isPlainPromptInput(inputStr);
@@ -3698,6 +3734,7 @@ export function registerSessionRoutes(
       agentOrigin,
       customModel,
       tabGroupId,
+      worktree,
     } = parseBody(QuickStartSchema, req.body);
 
     // Resolved ONCE here: the same value labels a case directory this request creates
@@ -3731,6 +3768,16 @@ export function registerSessionRoutes(
       : (await readDockerCases(CODEMAN_CONFIG_DIR)).find(
           (item) => item.name === caseName && canAccessOwned(getAuthUser(req), item.owner)
         );
+    // Worktrees are local only (src/git-worktrees.ts): refused BEFORE a remote host is woken or a
+    // container is touched, since neither branch below could honour it.
+    if (worktree && (remoteCase || dockerCase)) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        remoteCase
+          ? 'worktree is not available for remote (SSH) cases: the repository is on another machine'
+          : 'worktree is not available for Docker cases: git would run on this machine over a workspace the container can write'
+      );
+    }
     if (remoteCase) {
       const host = (await readRemoteHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === remoteCase.hostId);
       if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Remote host not found');
@@ -3972,6 +4019,27 @@ export function registerSessionRoutes(
       );
     }
 
+    // Where the session runs: the case folder, or one of its git worktrees. A worktree is only
+    // ever USED here (created through POST /api/cases/:name/worktrees), so a case that does not
+    // exist yet is a 404 rather than a scaffold, and the worktree must be a registered, managed
+    // one, every path component a real directory (src/git-worktrees.ts).
+    let workspacePath = resolvedCasePath;
+    if (worktree) {
+      if (localCaseState === 'absent') {
+        return createErrorResponse(ApiErrorCode.NOT_FOUND, `Case "${caseName}" not found`);
+      }
+      if (localCaseState !== 'directory') {
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Case path is not a folder');
+      }
+      const caseRepo = await resolveCaseRepository(resolvedCasePath, {
+        dockerWorkspaces: (await readDockerCases(CODEMAN_CONFIG_DIR)).map((c) => c.hostWorkspacePath).filter(Boolean),
+      });
+      if (!caseRepo.ok) return createErrorResponse(ApiErrorCode[caseRepo.code], caseRepo.message);
+      const managed = await resolveManagedWorktree(caseRepo.repo, worktree);
+      if (!managed.ok) return createErrorResponse(ApiErrorCode[managed.code], managed.message);
+      workspacePath = managed.path;
+    }
+
     // Create case folder and CLAUDE.md if it doesn't exist (only for non-linked, non-remote,
     // non-docker cases — docker workspaces are scaffolded in their own block below)
     if (localCaseState === 'absent') {
@@ -4030,9 +4098,9 @@ export function registerSessionRoutes(
       // of its own. Skipped for remote cases — resolvedCasePath is a REMOTE path that
       // doesn't exist on the local filesystem.
       if (getCli(mode)?.capabilities.hooks === 'always') {
-        await applyWorkspaceHooks(resolvedCasePath, await ctx.getWorkspaceHooksEnabled());
+        await applyWorkspaceHooks(workspacePath, await ctx.getWorkspaceHooksEnabled());
       } else {
-        await refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
+        await refreshStaleCodemanHooks(workspacePath).catch(() => {});
       }
     }
 
@@ -4044,7 +4112,7 @@ export function registerSessionRoutes(
     // hostWorkspacePath is a real host dir and the skill crosses the bind mount.
     const quickStartSkillDir = agentSkillDir(getCli(mode)?.capabilities);
     if (!remote && quickStartSkillDir && (await ctx.getAgentSkillEnabled())) {
-      await injectAgentSkill(resolvedCasePath, quickStartSkillDir);
+      await injectAgentSkill(workspacePath, quickStartSkillDir);
     }
 
     // Docker cases: the workspace is a REAL host dir bind-mounted into the container.
@@ -4077,14 +4145,14 @@ export function registerSessionRoutes(
     // docker — the docker workspace is a real host dir, so the settings file crosses
     // the bind mount and the in-container claude reads it). Remote was rejected above.
     if (getCli(mode)?.capabilities.model.source === 'claude-settings-file' && modelOverride !== undefined) {
-      await updateCaseModel(resolvedCasePath, modelOverride || null);
+      await updateCaseModel(workspacePath, modelOverride || null);
     }
 
     // Strip stale disk entries for keys this request is actively setting (Claude only —
     // see POST /api/sessions for full rationale).
     // Same chain, same replacement as the create path above: byte-identical, drift-proof.
     if (!isExternalCliMode(mode) && !remote && envOverrides && Object.keys(envOverrides).length > 0) {
-      await stripCaseEnvKeys(resolvedCasePath, Object.keys(envOverrides));
+      await stripCaseEnvKeys(workspacePath, Object.keys(envOverrides));
     }
 
     // Create a new session with the case as working directory
@@ -4140,7 +4208,7 @@ export function registerSessionRoutes(
     );
     const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
     const qsGatedEnvOverrides = await clampEnvOverridesForOwner(owner, envOverrides);
-    const qsResolvedOmpConfig = resolveOmpConfigForCreate(mode, resolvedCasePath, qsLaunchOmpConfig);
+    const qsResolvedOmpConfig = resolveOmpConfigForCreate(mode, workspacePath, qsLaunchOmpConfig);
 
     // Custom Model Endpoint Profiles, applied AT CREATE TIME (docs/custom-model-endpoints-plan.md)
     // rather than via the dedicated restart-in-place route (POST /api/sessions/:id/custom-
@@ -4246,7 +4314,7 @@ export function registerSessionRoutes(
         customModel.modelId,
         qsCustomModelSessionId,
         cmContextLength,
-        resolvedCasePath
+        workspacePath
       );
       if (!cmApplied) {
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${mode} has no known custom-model mechanism`);
@@ -4287,7 +4355,7 @@ export function registerSessionRoutes(
 
     const qsSessionOptions: ConstructorParameters<typeof Session>[0] = {
       id: qsCustomModelSessionId,
-      workingDir: resolvedCasePath,
+      workingDir: workspacePath,
       name: sessionName ? sessionName.slice(0, MAX_SESSION_NAME_LENGTH) : '',
       mux: ctx.mux,
       useMux: true,
@@ -4345,7 +4413,7 @@ export function registerSessionRoutes(
     // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
     // so the initial state already has the phrase configured (only if globally enabled)
     if (getCli(mode)?.capabilities.ralph && !remote && !docker && ctx.store.getConfig().ralphEnabled) {
-      autoConfigureRalph(session, resolvedCasePath, ctx);
+      autoConfigureRalph(session, workspacePath, ctx);
       if (!session.ralphTracker.enabled) {
         session.ralphTracker.enable();
         session.ralphTracker.enableAutoEnable(); // Allow re-enabling on restart
@@ -4409,34 +4477,40 @@ export function registerSessionRoutes(
         ).catch(() => {});
       }
 
-      // Save lastUsedCase to settings for TUI/web sync
-      try {
-        const settingsFilePath = SETTINGS_PATH;
-        let settings: Record<string, unknown> = {};
+      // Save lastUsedCase to settings for TUI/web sync. It is a key of the server-wide
+      // settings.json, readable by every user through GET /api/settings, so a non-admin's
+      // case name is not written there in multi-user mode (writes are admin-only, like
+      // PUT /api/settings). isAdmin is always true in single-user mode.
+      if (isAdmin(req)) {
         try {
-          settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
+          const settingsFilePath = SETTINGS_PATH;
+          let settings: Record<string, unknown> = {};
+          try {
+            settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
+          } catch (err) {
+            if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+          }
+          settings.lastUsedCase = caseName;
+          const dir = dirname(settingsFilePath);
+          if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+          }
+          // Use async write to avoid blocking event loop
+          fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch((err) => {
+            // Non-critical but log for debugging
+            console.warn('[Server] Failed to save settings (lastUsedCase):', err);
+          });
         } catch (err) {
-          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
-        }
-        settings.lastUsedCase = caseName;
-        const dir = dirname(settingsFilePath);
-        if (!existsSync(dir)) {
-          mkdirSync(dir, { recursive: true });
-        }
-        // Use async write to avoid blocking event loop
-        fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch((err) => {
           // Non-critical but log for debugging
-          console.warn('[Server] Failed to save settings (lastUsedCase):', err);
-        });
-      } catch (err) {
-        // Non-critical but log for debugging
-        console.warn('[Server] Failed to prepare settings update:', err);
+          console.warn('[Server] Failed to prepare settings update:', err);
+        }
       }
 
       return {
         sessionId: session.id,
         casePath: resolvedCasePath,
         caseName,
+        ...(worktree ? { worktree, workingDir: workspacePath } : {}),
         ...(customModel ? { modelSwapInProgress: qsCustomModelSwapInProgress } : {}),
         ...(tabGroupId ? { tabLayout } : {}),
       };
@@ -5373,6 +5447,12 @@ export function registerSessionRoutes(
   // so an uploaded video is a type that previews. 3gp/mkv are deliberately out: they
   // would upload but not preview, and a phone's camera roll produces neither.
   const ALLOWED_VIDEO_EXTS = new Set([...VIDEO_ATTACHMENT_EXTENSIONS].map((e) => `.${e}`));
+  // Documents a user hands an agent to read: the office formats plus the text
+  // family. Curated on purpose, never SUPPORTED_ATTACHMENT_EXTENSIONS or
+  // EDITABLE_EXTENSIONS, which carry sh/py/js/html; a prompt upload is a thing
+  // to read, not a thing to run or serve. Each is judged on its bytes by
+  // imageMagicMatchesExt (signature, or UTF-8 without NUL for text).
+  const ALLOWED_DOCUMENT_EXTS = new Set(['.pdf', '.docx', '.pptx', '.xlsx', '.zip', ...TEXT_UPLOAD_EXTS]);
   const VIDEO_MIME_EXT: Record<string, string> = {
     mp4: '.mp4',
     quicktime: '.mov',
@@ -5382,6 +5462,19 @@ export function registerSessionRoutes(
   };
   // The per-file size cap (MAX_PASTE_IMAGE_BYTES) is enforced by @fastify/multipart (registered in server.ts).
 
+  /** Write buffered upload bytes into the session's upload dir. Null: the dir is not a real directory. */
+  async function writeBufferedUpload(workingDir: string, ext: string, bytes: Buffer, stem = '') {
+    const uploadDir = await ensureUploadDir(workingDir);
+    if (!uploadDir) return null;
+    const { filename, filepath, fh } = await openPasteFile(uploadDir, ext, stem);
+    try {
+      await fh.writeFile(bytes);
+    } finally {
+      await fh.close();
+    }
+    return { path: filepath, filename };
+  }
+
   app.post('/api/sessions/:id/paste-image', async (req, reply) => {
     // CSRF defense: state-changing routes must come from same origin.
     // Cookies are SameSite=lax, multipart/form-data is a "simple" CORS request
@@ -5515,13 +5608,13 @@ export function registerSessionRoutes(
           `Unsupported video type. Allowed: ${[...ALLOWED_VIDEO_EXTS].join(', ')}`
         );
       }
-      const imageDir = await ensureUploadDir(session.workingDir);
-      if (!imageDir) {
+      const uploadDir = await ensureUploadDir(session.workingDir);
+      if (!uploadDir) {
         await finished(part.file.resume()).catch(() => {});
         reply.code(403);
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${UPLOADS_DIR} is not a regular directory`);
       }
-      const { filename, filepath, fh } = await openPasteFile(imageDir, ext);
+      const { filename, filepath, fh } = await openPasteFile(uploadDir, ext);
       // Written as it arrives: a phone video is far too large to buffer the way an
       // image is. The container is judged on the first 12 bytes as soon as they are
       // in, so a mislabeled upload stops touching disk at its first chunk; the rest
@@ -5580,12 +5673,41 @@ export function registerSessionRoutes(
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Empty file');
     }
 
+    // Dispatch mirrors the client's _promptAttachKind: an image MIME type takes
+    // the image path whatever the name says, a document extension (the MIME a
+    // phone gives a .md is anyone's guess) takes the document branch, anything
+    // else the image path exactly as before, HEIC sniff included. See CLAUDE.md.
+    const origExt = part.filename ? extname(part.filename).toLowerCase() : '';
+    const imageMime = /^image\//i.test(part.mimetype || '');
+    if (!imageMime && ALLOWED_DOCUMENT_EXTS.has(origExt)) {
+      if (!imageMagicMatchesExt(imageBytes, origExt)) {
+        // The first bytes of a text file are user content, so for text the log
+        // names the failure and never the bytes; a signature is safe to print.
+        const detail = TEXT_UPLOAD_EXTS.has(origExt)
+          ? `reason=${imageBytes.includes(0) ? 'nul-byte' : 'not-utf8'}`
+          : `magic=${imageBytes.subarray(0, 12).toString('hex')}`;
+        console.warn(
+          `[paste-image] document mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${origExt} size=${imageBytes.length} ${detail}`
+        );
+        reply.code(415);
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, `File bytes do not match declared type ${origExt}`);
+      }
+      const saved = await writeBufferedUpload(
+        session.workingDir,
+        origExt,
+        imageBytes,
+        sanitizeUploadStem(part.filename)
+      );
+      if (!saved) {
+        reply.code(403);
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${UPLOADS_DIR} is not a regular directory`);
+      }
+      return saved;
+    }
+
     // Determine extension from filename or Content-Type.
     let ext = '.png';
-    if (part.filename) {
-      const origExt = extname(part.filename).toLowerCase();
-      if (ALLOWED_IMAGE_EXTS.has(origExt)) ext = origExt;
-    }
+    if (ALLOWED_IMAGE_EXTS.has(origExt)) ext = origExt;
     const mimeMatch = (part.mimetype || '').toLowerCase().match(/^image\/(png|jpeg|jpg|webp|gif|bmp|heic|heif)$/);
     if (mimeMatch) {
       const map: Record<string, string> = {
@@ -5626,6 +5748,15 @@ export function registerSessionRoutes(
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Could not convert HEIC image to JPEG');
       }
     } else if (!imageMagicMatchesExt(imageBytes, ext)) {
+      // A foreign extension with no image MIME (a script, an HTML page, a video
+      // without its flag) was never going to be an image: say so, rather than
+      // the ".png" the default extension would name. Decided only HERE, after
+      // the sniff, so anything the image path ever accepted by its bytes (a
+      // HEIC under a generic name) still is.
+      if (origExt && !ALLOWED_IMAGE_EXTS.has(origExt) && !imageMime) {
+        reply.code(400);
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Unsupported file type: ${origExt}`);
+      }
       // Sniff actual bytes — a polyglot HTML/PNG would otherwise pass and
       // serve back with image/png MIME. Log the real header so format
       // mismatches can be pinned down without a reproduce-and-guess loop. The
@@ -5637,20 +5768,12 @@ export function registerSessionRoutes(
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`);
     }
 
-    // {workingDir}/.codeman-uploads/, see ensureUploadDir.
-    const imageDir = await ensureUploadDir(session.workingDir);
-    if (!imageDir) {
+    const saved = await writeBufferedUpload(session.workingDir, ext, imageBytes);
+    if (!saved) {
       reply.code(403);
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${UPLOADS_DIR} is not a regular directory`);
     }
-    const { filename, filepath, fh } = await openPasteFile(imageDir, ext);
-    try {
-      await fh.writeFile(imageBytes);
-    } finally {
-      await fh.close();
-    }
-
-    return { path: filepath, filename };
+    return saved;
   });
 
   // Returned so the server can own the registry's LIFETIME (drop state when a session is

src/web/routes/status-telemetry-routes.ts

@@ -51,12 +51,17 @@ export function registerStatusTelemetryRoutes(app: FastifyInstance, ctx: Session
 
     const payload = data as RawStatuslinePayload | undefined;
 
+    // Only a CLI that has a statusline exporter at all speaks for its own model and
+    // prompt-cache state: both ride the SAME statusline payload the exporter POSTs, so
+    // both are gated on capabilities.statusLineTelemetry (the gate that also decides
+    // whether the exporter is injected at all, in tmux-manager._resolveStatusLine).
+    const session = ctx.sessions.get(sessionId);
+    const reportsStatusLine = !!session && !!getCli(session.mode)?.capabilities.statusLineTelemetry;
+
     // The model the CLI says it is running, for the session headers (displayModel). It
     // rides every render, so it follows an in-session `/model`; the session dedupes and
-    // broadcasts only a change. Only a CLI that has a statusline exporter at all may
-    // report one here.
-    const session = ctx.sessions.get(sessionId);
-    if (session && getCli(session.mode)?.capabilities.statusLineTelemetry) {
+    // broadcasts only a change.
+    if (session && reportsStatusLine) {
       session.noteReportedModel('statusline', payload?.model?.display_name);
     }
 
@@ -68,7 +73,7 @@ export function registerStatusTelemetryRoutes(app: FastifyInstance, ctx: Session
     // it backgrounds this POST (hooks-config.ts), so two sub-second loopback reports can
     // arrive out of order; a stale one then briefly overwrites newer state until the next
     // render corrects it. Accepted for a display-only readout rather than ordered here.
-    const promptCache = parsePromptCache(payload);
+    const promptCache = reportsStatusLine ? parsePromptCache(payload) : null;
     if (promptCache && session?.setPromptCache(promptCache)) {
       ctx.broadcast(SessionPromptCache, { sessionId, ...session.promptCache });
       // Persisted on change, like a model change, so a crash restores the latest report.

src/web/routes/system-routes.ts

@@ -17,7 +17,7 @@ import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } f
 import { isUnauthenticatedNetworkAcknowledged } from '../network-auth-policy.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { findUser, canUsernameRunPrivilegedCommands } from '../../user-store.js';
-import { getAuthUser, requireAdmin, canAccessOwned } from '../route-helpers.js';
+import { getAuthUser, isAdmin, requireAdmin, canAccessOwned, revokeUserSessions } from '../route-helpers.js';
 import {
   ConfigUpdateSchema,
   SettingsUpdateSchema,
@@ -144,6 +144,28 @@ export function resolveSpanUrl(hostHeader: string | undefined, fallbackPort = '3
   return `http://localhost:${port}`;
 }
 
+/**
+ * What GET /api/settings answers a NON-ADMIN in multi-user mode: settings.json minus what
+ * belongs to the server's admin rather than to the reader. `voiceSettings.apiKey` is the
+ * Deepgram key an admin saved, a credential (the reader's browser seeded it into its own
+ * voice config and dictated on the admin's account); `caseOrder` and `lastUsedCase` name the
+ * admin's cases. Everything else stays readable, because the page reads the synced feature
+ * switches from it. Writes are admin-only there (PUT /api/settings). Exported for unit testing.
+ */
+export function settingsForNonAdmin(settings: unknown): unknown {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) return settings;
+  const out: Record<string, unknown> = { ...(settings as Record<string, unknown>) };
+  delete out.caseOrder;
+  delete out.lastUsedCase;
+  const voice = out.voiceSettings;
+  if (voice && typeof voice === 'object' && !Array.isArray(voice) && 'apiKey' in voice) {
+    const voiceOut: Record<string, unknown> = { ...(voice as Record<string, unknown>) };
+    delete voiceOut.apiKey;
+    out.voiceSettings = voiceOut;
+  }
+  return out;
+}
+
 export function registerSystemRoutes(
   app: FastifyInstance,
   ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort & TabLayoutPort
@@ -163,12 +185,17 @@ export function registerSystemRoutes(
 
   app.get('/api/tunnel/status', async () => ctx.tunnelManager.getStatus());
 
-  app.get('/api/tunnel/info', async () => {
+  app.get('/api/tunnel/info', async (req) => {
     const status = ctx.tunnelManager.getStatus();
     const sseClients = ctx.getSseClientCount();
     const sessions: Array<{ ip: string; ua: string; createdAt: number; method: string }> = [];
+    // Multi-user mode: a non-admin is shown only their own logins (address and browser of
+    // every other user's sessions are not theirs to read), matching what their Revoke All
+    // can revoke (POST /api/auth/revoke). null = everyone's (admin, single-user mode).
+    const onlyUser = isMultiUserMode() && !isAdmin(req) ? getAuthUser(req).username : null;
     if (ctx.authSessions) {
       for (const [, record] of ctx.authSessions) {
+        if (onlyUser !== null && record.username !== onlyUser) continue;
         sessions.push({ ip: record.ip, ua: record.ua, createdAt: record.createdAt, method: record.method });
       }
     }
@@ -300,7 +327,10 @@ export function registerSystemRoutes(
 
   // ========== QR Regeneration ==========
 
-  app.post('/api/tunnel/qr/regenerate', async () => {
+  app.post('/api/tunnel/qr/regenerate', async (req, reply) => {
+    // Clears EVERY outstanding QR login code (each user's minted one too) and rotates the
+    // server's token: admin-only in multi-user mode, like the other tunnel controls.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     ctx.tunnelManager.regenerateQrToken();
     return {};
   });
@@ -309,6 +339,19 @@ export function registerSystemRoutes(
 
   app.post('/api/auth/revoke', async (req) => {
     const result = RevokeSessionSchema.safeParse(req.body);
+    // Multi-user mode: a NON-ADMIN revokes only their own login sessions. The bare form
+    // below clears every session on the server, so for them it used to sign out every
+    // user, admins included; a named token is revoked only when it is one of theirs.
+    if (isMultiUserMode() && !isAdmin(req)) {
+      const username = getAuthUser(req).username;
+      const token = result.success ? result.data.sessionToken : undefined;
+      if (token) {
+        if (ctx.authSessions?.peek(token)?.username === username) ctx.authSessions?.delete(token);
+      } else {
+        revokeUserSessions(ctx.authSessions, username);
+      }
+      return {};
+    }
     if (result.success && result.data.sessionToken) {
       ctx.authSessions?.delete(result.data.sessionToken);
     } else {
@@ -327,6 +370,8 @@ export function registerSystemRoutes(
   // panels can be dragged across the physical monitor seam. macOS only; needs
   // the one-time "Displays have separate Spaces" OFF prerequisite (see script).
   app.post('/api/system/span-displays', async (req, reply) => {
+    // Launches a browser window on the SERVER's desktop: admin-only in multi-user mode.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     // macOS only: the launcher uses osascript + Finder desktop bounds and Chrome
     // --app geometry flags. Fail clearly elsewhere instead of spawning a bash
     // that errors out invisibly (the toast would otherwise lie "Opening…").
@@ -379,7 +424,9 @@ export function registerSystemRoutes(
 
   // Kick off a detached update to the latest release. Returns immediately; the
   // browser then polls /api/system/update/status across the service restart.
-  app.post('/api/system/update', async (_req, reply) => {
+  app.post('/api/system/update', async (req, reply) => {
+    // Updates and restarts the server under every user: admin-only in multi-user mode.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     const result = await startUpdate();
     if (result.ok) {
       return { updateId: result.updateId, toTag: result.toTag, toVersion: result.toVersion };
@@ -617,13 +664,16 @@ export function registerSystemRoutes(
           // synchronous-spawn precedent this endpoint is modelled on.
           detached: true,
           // Inherit the environment: this needs a HOME to resolve $DSH_HOME
-          // against, and a PATH carrying `pnpm`. ⚠️ `dsh plugin` does NOT bundle a
+          // against, and a PATH carrying `pnpm` (see the PATH below). ⚠️ `dsh plugin` does NOT bundle a
           // package manager — it `spawnSync`s a literal `pnpm` with no npm
           // fallback, so on a host without one this exits 127 and dsh's own
           // stderr ("pnpm not found on PATH") is what reaches the caller through
           // the OPERATION_FAILED detail below. That is the same missing
           // dependency that broke the docker agent image in issue #352.
-          env: process.env,
+          // PATH leads with the directory `dsh` itself resolved to: CLI management installs
+          // `dsh` and `pnpm` into the user prefix (`~/.local/bin`), which a service's own PATH
+          // usually lacks, so `dsh plugin` could not find the `pnpm` sitting next to it.
+          env: { ...process.env, PATH: [dir, process.env.PATH].filter(Boolean).join(':') },
         });
       } catch (err) {
         resolve({ code: null, output: `spawn failed: ${getErrorMessage(err)}`, timedOut: false });
@@ -718,7 +768,10 @@ export function registerSystemRoutes(
 
   // ========== State & Lifecycle ==========
 
-  app.post('/api/cleanup-state', async () => {
+  app.post('/api/cleanup-state', async (req, reply) => {
+    // Drops every user's stale session records (and their tab-layout entries): admin-only
+    // in multi-user mode, like the other server-wide maintenance operations.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     const activeSessionIds = new Set(ctx.sessions.keys());
     const result = await ctx.tabLayouts.runStaleSessionCleanup(activeSessionIds, (ids) =>
       ctx.store.cleanupSessionsByIds(ids)
@@ -866,7 +919,10 @@ export function registerSystemRoutes(
     return { config: ctx.store.getConfig() };
   });
 
-  app.put('/api/config', async (req) => {
+  app.put('/api/config', async (req, reply) => {
+    // Process-wide app config in state.json (poll interval, timeouts, the session cap,
+    // respawn defaults): admin-only in multi-user mode, like PUT /api/settings.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     const configData = parseBody(ConfigUpdateSchema, req.body, 'Invalid config');
     ctx.store.setConfig(configData as Partial<ReturnType<typeof ctx.store.getConfig>>);
     return { config: ctx.store.getConfig() };
@@ -935,7 +991,7 @@ export function registerSystemRoutes(
 
   // ========== Settings ==========
 
-  app.get('/api/settings', async () => {
+  app.get('/api/settings', async (req) => {
     // A plain read. This route must NEVER write settings.json: readJsonConfig()
     // answers `{}` for ANY read failure (a parse error, EACCES, EMFILE, a read
     // that lands inside PUT's non-atomic write), not only for a missing file,
@@ -947,10 +1003,20 @@ export function registerSystemRoutes(
     // `workspaceHooksEnabled` means ON, and the client resolves its own display
     // default through planUsageChipEnabled(). Pinned by
     // test/routes/system-routes-settings-get-plan-usage-default.test.ts.
-    return readJsonConfig(SETTINGS_PATH, 'settings', {});
+    const settings = await readJsonConfig<unknown>(SETTINGS_PATH, 'settings', {});
+    // Readable by every signed-in user, but a non-admin in multi-user mode gets it without
+    // the admin's credential and case names (settingsForNonAdmin). isAdmin is always true in
+    // single-user mode, so that answer is the file as it is.
+    return isAdmin(req) ? settings : settingsForNonAdmin(settings);
   });
 
-  app.put('/api/settings', async (req) => {
+  app.put('/api/settings', async (req, reply) => {
+    // Multi-user mode: settings.json is ONE file for the whole server (feature switches,
+    // the plan-usage collection switch, run mode, respawn presets, the tunnel), so a write
+    // is admin-only, like every other server-wide setting (docs/multi-user-plan.md,
+    // Settings row). Refused FIRST: nothing is parsed, written, toggled or started for a
+    // non-admin. GET above stays readable by everyone. No-op in single-user mode.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     const settings = parseBody(SettingsUpdateSchema, req.body, 'Invalid settings') as Record<string, unknown>;
 
     // COD-55: enabling the Cloudflare tunnel publishes the whole app (full terminal
@@ -1089,7 +1155,10 @@ export function registerSystemRoutes(
     return { success: true, data: settings.modelConfig || {} };
   });
 
-  app.put('/api/execution/model-config', async (req) => {
+  app.put('/api/execution/model-config', async (req, reply) => {
+    // The `modelConfig` key of the server-wide settings.json (cron's and the plan
+    // orchestrator's default model): admin-only in multi-user mode, like PUT /api/settings.
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
     const modelConfig = parseBody(ModelConfigUpdateSchema, req.body, 'Invalid model config') as Record<string, unknown>;
 
     try {

src/web/routes/worktree-routes.ts

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Git worktrees of a local case (src/git-worktrees.ts holds the rules):
+ *
+ *   GET    /api/cases/:name/worktrees             the case repository's worktrees, which of them
+ *                                                 Codeman manages, and the live sessions in each
+ *   POST   /api/cases/:name/worktrees             create `<case>/.claude/worktrees/<name>` on a
+ *                                                 new branch (`{ name, branch?, base? }`)
+ *   DELETE /api/cases/:name/worktrees/:worktree   `git worktree remove` WITHOUT --force, refused
+ *                                                 while a live session runs inside; optional
+ *                                                 `?deleteBranch=true` is `git branch -d`
+ *
+ * A session starts in a worktree through the EXISTING create paths, never a new spawn path here:
+ * `POST /api/quick-start` with `worktree: <name>` (validated against this module's rules), or
+ * `POST /api/sessions` with the worktree path as `workingDir`.
+ *
+ * The case is resolved the way quick-start resolves it: an owned remote or Docker case is refused
+ * with a 400 (git must never run on the host over a Docker workspace, and a remote case's folder
+ * is on another machine); a linked case resolves for admins only in multi-user mode; anything else
+ * is the caller's own case space, confined with `isWorkingDirAllowed`. The case folder is probed
+ * BOUNDED (#516): a case on a network mount that stopped answering is a 422, never a 404.
+ *
+ * Statuses are set explicitly from the error code, so the route answers the same with or without
+ * the server's envelope hook.
+ */
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { ApiErrorCode, createErrorResponse, httpStatusForErrorCode, type ApiResponse } from '../../types.js';
+import { readDockerCases } from '../../docker-hosts.js';
+import { readRemoteCases } from '../../remote-hosts.js';
+import { dataPath, getDataDir } from '../../config/instance.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { listClis } from '../../config/cli-registry/registry.js';
+import { agentSkillDir } from '../../hooks-config.js';
+import { describeUnknownPath, probePathKind } from '../../utils/index.js';
+import {
+  createCaseWorktree,
+  isPathWithin,
+  listCaseWorktrees,
+  managedWorktreesDir,
+  removeCaseWorktree,
+  resolveCaseRepository,
+  respellUnder,
+  worktreeNameError,
+  type CaseRepository,
+  type CaseWorktree,
+  type CreatedWorktree,
+  type RemovedWorktree,
+  type WorktreeFailure,
+  type WorktreeGitRunner,
+} from '../../git-worktrees.js';
+import { CreateWorktreeSchema, RemoveWorktreeQuerySchema } from '../schemas.js';
+import {
+  canAccessOwned,
+  getAuthUser,
+  isAdmin,
+  isWorkingDirAllowed,
+  parseBody,
+  readJsonConfig,
+  resolveCasesDir,
+  validatePathWithinBase,
+} from '../route-helpers.js';
+import type { SessionPort } from '../ports/index.js';
+
+const SAFE_CASE_NAME = /^[a-zA-Z0-9_-]+$/;
+
+/** Host paths of every Docker case workspace: git never runs for a case at or inside one. */
+const defaultDockerWorkspaces = async (): Promise<string[]> =>
+  (await readDockerCases(getDataDir()).catch(() => [])).map((c) => c.hostWorkspacePath).filter(Boolean);
+
+/**
+ * Every workspace skills folder a session of some registry CLI gets Codeman's agent skill in
+ * (`capabilities.agentSkillDir`), read from the registry at call time as data, never by CLI id.
+ */
+const registryAgentSkillDirs = (): string[] => {
+  const dirs = new Set<string>();
+  for (const cli of listClis()) {
+    const dir = agentSkillDir(cli.capabilities);
+    if (dir) dirs.add(dir);
+  }
+  return [...dirs];
+};
+
+/** A live session in a worktree, as the list reports it to a caller who may see it. */
+export interface WorktreeSessionRef {
+  id: string;
+  name: string;
+}
+
+/** One row of `GET /api/cases/:name/worktrees`. */
+export interface CaseWorktreeInfo extends CaseWorktree {
+  /** Live sessions running in this worktree (deepest worktree wins), all owners. */
+  sessionCount: number;
+  /** The ones the caller may see (all of them outside multi-user mode). */
+  sessions: WorktreeSessionRef[];
+}
+
+export interface CaseWorktreeList {
+  caseName: string;
+  repoRoot: string;
+  /** `<repo>/.claude/worktrees`, where Codeman creates and removes worktrees. */
+  worktreesDir: string;
+  worktrees: CaseWorktreeInfo[];
+  truncated: boolean;
+}
+
+type Fail = ApiResponse<never>;
+
+function failWith(reply: FastifyReply, code: ApiErrorCode, message: string): Fail {
+  reply.code(httpStatusForErrorCode(code));
+  return createErrorResponse(code, message);
+}
+
+function failFrom(reply: FastifyReply, failure: WorktreeFailure): Fail {
+  return failWith(reply, ApiErrorCode[failure.code], failure.message);
+}
+
+/**
+ * The LOCAL folder of case `name` for this caller, or the refusal. Mirrors quick-start's
+ * resolution (remote, then Docker, then linked, then the caller's case space) so a name means
+ * the same case here as it does to the Run button.
+ */
+async function resolveLocalCaseFolder(
+  req: FastifyRequest,
+  name: string
+): Promise<{ ok: true; casePath: string } | { ok: false; code: ApiErrorCode; message: string }> {
+  if (!SAFE_CASE_NAME.test(name)) {
+    return { ok: false, code: ApiErrorCode.INVALID_INPUT, message: 'Invalid case name' };
+  }
+  const user = getAuthUser(req);
+  const configDir = getDataDir();
+  // Ownership folded into the match, as quick-start does: a foreign same-named remote/Docker
+  // case falls through to the caller's own local case instead of shadowing it.
+  if ((await readRemoteCases(configDir)).some((c) => c.name === name && canAccessOwned(user, c.owner))) {
+    return {
+      ok: false,
+      code: ApiErrorCode.INVALID_INPUT,
+      message: 'Worktrees are not available for remote (SSH) cases: the repository is on another machine.',
+    };
+  }
+  if ((await readDockerCases(configDir)).some((c) => c.name === name && canAccessOwned(user, c.owner))) {
+    return {
+      ok: false,
+      code: ApiErrorCode.INVALID_INPUT,
+      message:
+        'Worktrees are not available for Docker cases: a container can write to the workspace, and git would run its hooks and filters on this machine.',
+    };
+  }
+  const linkedCases = await readJsonConfig<Record<string, string>>(dataPath('linked-cases.json'), 'linked cases', {});
+  // Linked cases carry no owner: only admins resolve them in multi-user mode.
+  const linked = !isMultiUserMode() || isAdmin(req) ? linkedCases[name] : undefined;
+  const casePath = linked || validatePathWithinBase(name, resolveCasesDir(user));
+  if (!casePath) return { ok: false, code: ApiErrorCode.INVALID_INPUT, message: 'Invalid case path' };
+  if (!isWorkingDirAllowed(user, casePath)) {
+    return { ok: false, code: ApiErrorCode.FORBIDDEN, message: 'case path is outside your workspace' };
+  }
+  const kind = await probePathKind(casePath, { pastCap: true });
+  if (kind === 'unknown') {
+    return {
+      ok: false,
+      code: ApiErrorCode.OPERATION_FAILED,
+      message: describeUnknownPath('Case folder', casePath, { pastCap: true }),
+    };
+  }
+  if (kind === 'absent') return { ok: false, code: ApiErrorCode.NOT_FOUND, message: `Case "${name}" not found` };
+  if (kind !== 'directory')
+    return { ok: false, code: ApiErrorCode.INVALID_INPUT, message: 'Case path is not a folder' };
+  return { ok: true, casePath };
+}
+
+/**
+ * Live local sessions, with the folder each runs in as the case's repository spells it
+ * (`respellUnder`: a folder named through the case's own path, which can run through a symlink,
+ * is moved onto the repository's real top level, where git lists the worktrees). Remote sessions
+ * have no local folder.
+ */
+function liveLocalSessions(
+  ctx: SessionPort,
+  casePath: string,
+  repoRoot: string
+): Array<{ id: string; name: string; owner?: string; dir: string }> {
+  const out: Array<{ id: string; name: string; owner?: string; dir: string }> = [];
+  for (const session of ctx.sessions.values()) {
+    if (session.remote || !session.workingDir || !session.workingDir.startsWith('/')) continue;
+    const dir = respellUnder(session.workingDir, casePath, repoRoot);
+    out.push({ id: session.id, name: session.name, owner: session.owner, dir });
+  }
+  return out;
+}
+
+export function registerWorktreeRoutes(
+  app: FastifyInstance,
+  ctx: SessionPort,
+  deps: { git?: WorktreeGitRunner; dockerWorkspaces?: () => Promise<string[]> } = {}
+): void {
+  const dockerWorkspaces = deps.dockerWorkspaces ?? defaultDockerWorkspaces;
+
+  /**
+   * Case folder → its repository, or the refusal already rendered. `casePath` is the folder as
+   * the case resolves it (possibly through a symlink); `repo.repoRoot` is its real path.
+   */
+  async function caseRepository(
+    req: FastifyRequest,
+    reply: FastifyReply,
+    name: string
+  ): Promise<{ ok: true; repo: CaseRepository; casePath: string; dockerRoots: string[] } | { ok: false; fail: Fail }> {
+    const folder = await resolveLocalCaseFolder(req, name);
+    if (!folder.ok) return { ok: false, fail: failWith(reply, folder.code, folder.message) };
+    const dockerRoots = await dockerWorkspaces();
+    const repo = await resolveCaseRepository(folder.casePath, { git: deps.git, dockerWorkspaces: dockerRoots });
+    if (!repo.ok) return { ok: false, fail: failFrom(reply, repo) };
+    return { ok: true, repo: repo.repo, casePath: folder.casePath, dockerRoots };
+  }
+
+  app.get('/api/cases/:name/worktrees', async (req, reply): Promise<ApiResponse<CaseWorktreeList>> => {
+    const { name } = req.params as { name: string };
+    const resolved = await caseRepository(req, reply, name);
+    if (!resolved.ok) return resolved.fail;
+    const { repo, casePath } = resolved;
+    const listed = await listCaseWorktrees(repo, { git: deps.git });
+    if (!listed.ok) return failFrom(reply, listed);
+
+    // Each live session belongs to the DEEPEST worktree holding its folder, so a session in a
+    // managed worktree is not also counted against the main checkout that contains it.
+    const user = getAuthUser(req);
+    const rows: CaseWorktreeInfo[] = listed.worktrees.map((wt) => ({ ...wt, sessionCount: 0, sessions: [] }));
+    for (const session of liveLocalSessions(ctx, casePath, repo.repoRoot)) {
+      let best: CaseWorktreeInfo | undefined;
+      for (const row of rows) {
+        if (!isPathWithin(session.dir, row.path)) continue;
+        if (!best || row.path.length > best.path.length) best = row;
+      }
+      if (!best) continue;
+      best.sessionCount += 1;
+      if (canAccessOwned(user, session.owner)) best.sessions.push({ id: session.id, name: session.name });
+    }
+    return {
+      success: true,
+      data: {
+        caseName: name,
+        repoRoot: repo.repoRoot,
+        worktreesDir: managedWorktreesDir(repo.repoRoot),
+        worktrees: rows,
+        truncated: listed.truncated,
+      },
+    };
+  });
+
+  app.post('/api/cases/:name/worktrees', async (req, reply): Promise<ApiResponse<{ worktree: CreatedWorktree }>> => {
+    const { name } = req.params as { name: string };
+    const body = parseBody(CreateWorktreeSchema, req.body);
+    const nameError = worktreeNameError(body.name);
+    if (nameError) return failWith(reply, ApiErrorCode.INVALID_INPUT, nameError);
+    const resolved = await caseRepository(req, reply, name);
+    if (!resolved.ok) return resolved.fail;
+    const created = await createCaseWorktree(resolved.repo, body, {
+      git: deps.git,
+      agentSkillDirs: registryAgentSkillDirs(),
+    });
+    if (!created.ok) return failFrom(reply, created);
+    reply.code(201);
+    return { success: true, data: { worktree: created.worktree } };
+  });
+
+  app.delete(
+    '/api/cases/:name/worktrees/:worktree',
+    async (req, reply): Promise<ApiResponse<{ removed: RemovedWorktree }>> => {
+      const { name, worktree } = req.params as { name: string; worktree: string };
+      const query = parseBody(RemoveWorktreeQuerySchema, req.query ?? {});
+      const nameError = worktreeNameError(worktree);
+      if (nameError) return failWith(reply, ApiErrorCode.INVALID_INPUT, nameError);
+      const resolved = await caseRepository(req, reply, name);
+      if (!resolved.ok) return resolved.fail;
+      const removed = await removeCaseWorktree(
+        resolved.repo,
+        {
+          name: worktree,
+          deleteBranch: query.deleteBranch === 'true' || query.deleteBranch === '1',
+          // Any owner's session blocks: removing the folder under a running agent is the damage
+          // this refusal exists to prevent, whoever started it.
+          isInUse: (path) =>
+            liveLocalSessions(ctx, resolved.casePath, resolved.repo.repoRoot).some((s) => isPathWithin(s.dir, path)),
+        },
+        // The worktree folder itself must not be (or hold) a Docker case workspace either.
+        { git: deps.git, dockerWorkspaces: resolved.dockerRoots }
+      );
+      if (!removed.ok) return failFrom(reply, removed);
+      return { success: true, data: { removed: removed.removed } };
+    }
+  );
+}

src/web/schemas.ts

@@ -707,7 +707,16 @@ export const StatusTelemetrySchema = z.object({
           miss_recache_tokens: z.number().nullish(),
           last_miss_at: z.number().nullish(),
           recache_tokens_if_cold: z.number().nullish(),
-          last_miss_cause: z.object({ causes: z.array(z.unknown()).max(20).nullish() }).nullish(),
+          // Keep the first 20 causes instead of 400-ing the whole post (which also drops the
+          // footer, the plan chip and the model report it carries) when Claude Code reports more. The
+          // preprocess slices BEFORE the array validates, so an over-long array costs one bounded
+          // slice, never per-element validation across every entry (parsePromptCache then keeps
+          // the string ones among those 20).
+          last_miss_cause: z
+            .object({
+              causes: z.preprocess((v) => (Array.isArray(v) ? v.slice(0, 20) : v), z.array(z.unknown()).nullish()),
+            })
+            .nullish(),
         })
         .nullish(),
     })
@@ -759,6 +768,34 @@ export const ClonePreflightSchema = z.object({
   repository: z.string().min(1).max(2048),
 });
 
+// ========== Git worktrees of a case (src/git-worktrees.ts) ==========
+
+/**
+ * A worktree name: one segment of letters, digits, `.`, `_`, `-`, starting with a letter or
+ * digit, at most 64 characters (Claude Code's own `--worktree` limit). The finer rules (no `..`,
+ * no trailing `.lock`) are `worktreeNameError()`, which every route applies after this.
+ */
+const worktreeNameSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'Invalid worktree name. Use letters, digits, ".", "_" and "-".');
+
+/** Schema for POST /api/cases/:name/worktrees: a new worktree on a new branch. */
+export const CreateWorktreeSchema = z.object({
+  name: worktreeNameSchema,
+  /** New branch name; default `worktree-<name>`, Claude Code's convention. */
+  branch: z.string().min(1).max(200).optional(),
+  /** Start point (branch, tag or commit); default the case's current HEAD. */
+  base: z.string().min(1).max(200).optional(),
+});
+
+/** Query of DELETE /api/cases/:name/worktrees/:worktree. */
+export const RemoveWorktreeQuerySchema = z.object({
+  /** Also `git branch -d` the worktree's branch (never `-D`). */
+  deleteBranch: z.enum(['true', 'false', '1', '0']).optional(),
+});
+
 const RemoteCommandOverridesSchema = z
   .object({
     shell: z.string().min(1).max(300).optional(),
@@ -1139,6 +1176,13 @@ export const QuickStartSchema = z.object({
   parentSessionId: parentSessionIdSchema,
   /** Tab group to place the new session in: see tabGroupIdSchema. */
   tabGroupId: tabGroupIdSchema,
+  /**
+   * Start the session in this git worktree of the case (`<case>/.claude/worktrees/<worktree>`,
+   * created through POST /api/cases/:name/worktrees) instead of the case folder. Local cases
+   * only: refused (400) for remote and Docker cases. The worktree must be a registered worktree
+   * of the case's repository; it is never created here.
+   */
+  worktree: worktreeNameSchema.optional(),
   /** Model override written to <case>/.claude/settings.local.json (e.g. "opus[1m]").
    *  Empty string clears. Applied for local AND docker cases (the docker workspace is
    *  a real host dir, so the settings file crosses the bind mount); rejected for

src/web/server.ts

@@ -192,6 +192,7 @@ import {
   registerStatusTelemetryRoutes,
   registerSystemRoutes,
   registerCaseRoutes,
+  registerWorktreeRoutes,
   registerSessionRoutes,
   registerRespawnRoutes,
   registerRalphRoutes,
@@ -1154,6 +1155,7 @@ export class WebServer extends EventEmitter {
     registerStatusTelemetryRoutes(this.app, ctx);
     registerSystemRoutes(this.app, ctx);
     registerCaseRoutes(this.app, ctx);
+    registerWorktreeRoutes(this.app, ctx);
     // The registry's lifetime is the server's: it drops per-session wake state on every
     // cleanup path and resolves in-flight wakes on shutdown.
     this.remoteWake = registerSessionRoutes(this.app, ctx);

test/agent-skill.test.ts

@@ -163,6 +163,30 @@ describe('preamble single-source (seed + §0 heredoc parity)', () => {
     expect(preamble).toBe(heredoc);
   });
 
+  it("SKILL.md's shell survives Claude Code's skill-argument substitution unchanged", async () => {
+    // When Claude Code loads a skill WITH arguments (the Skill tool passes the user's request words),
+    // it rewrites the skill body before the model sees it. Measured on 2.1.300: every `$ARGUMENTS[N]`,
+    // `$ARGUMENTS` and bare `$N` (digits, then no word character) becomes the matching argument, 0-based,
+    // and a backslash before `$` is consumed as an escape. A bare `$1` in §0 arrived as
+    // `sessions/5/terminal` and `timeout=claude` for "start 5 claude workers", so an agent pasting §0
+    // wrote a broken preamble. `${1}` is the same bash and is never touched; keep it that way.
+    const skillMd = await readFile(join(packagedDir, 'SKILL.md'), 'utf-8');
+    const substitute = (body: string, args: string[]): string =>
+      body
+        .replace(/(?<!\\)\\\$(?=\d|ARGUMENTS)/g, '$')
+        .replace(/\$ARGUMENTS\[(\d+)\]/g, (m, i: string) => args[Number(i)] ?? m)
+        .replace(/\$(\d+)(?!\w)/g, (m, i: string) => args[Number(i)] ?? m)
+        .replaceAll('$ARGUMENTS', args.join(' '));
+    const args = 'start 5 claude workers, one per TODO item'.split(/\s+/);
+    expect(substitute(skillMd, args)).toBe(skillMd);
+
+    // And the heredoc an agent pastes from the substituted body is still the seeded preamble.
+    const rendered = substitute(skillMd, args);
+    const start = rendered.indexOf("<<'PREAMBLE'\n") + "<<'PREAMBLE'\n".length;
+    const preamble = await readFile(join(packagedDir, 'preamble.sh'), 'utf-8');
+    expect(rendered.slice(start, rendered.indexOf('\nPREAMBLE\n', start) + 1)).toBe(preamble);
+  });
+
   it('seedAgentSessionPreamble writes the stamped preamble to the XDG cache path, 0600', async () => {
     const prevXdg = process.env.XDG_CACHE_HOME;
     const cacheDir = join(casePath, 'xdg-cache');

test/codex-blocked-detection.test.ts

@@ -59,6 +59,10 @@ const DIALOGS = [
   'question-notes-typed.txt',
   'trust-dialog.txt', // drawn at the TOP of an otherwise blank screen at startup
   'trust-dialog-w40.txt',
+  // The same prompt, reached through the update prompt (`2. Skip`) on 0.162.0 with 0.163.0
+  // out: `2. Back to Agent Command Center` over `enter continue · esc back`. Captured
+  // 2026-10-16 from Codeman's own launch flags in a fresh git repo, at 120 columns.
+  'trust-dialog-back.txt',
 ];
 
 /** Screens with no dialog codex blocks on, several of them quoting the dialogs' words. */

test/deepseek-install-profile-path.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
+
+const root = resolve(import.meta.dirname, '..');
+const dirs: string[] = [];
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function deepseekInstallCommand(platform: 'linux' | 'darwin'): string {
+  const ds = STOCK_CLIS.find((c) => (c.id as string) === 'deepseek')!;
+  return ds.discovery.install.command![platform]!;
+}
+
+/**
+ * Run the stock install command through `/bin/sh -c` (what CLI management does, `shell: true`)
+ * with a fake `npm` that records each call, on a PATH that holds only the fake bins. So this
+ * exercises the real string, not a copy of it.
+ */
+function runInstall(opts: { pnpmOnPath: boolean; npmFails?: boolean }): { status: number | null; npmCalls: string[] } {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-install-'));
+  dirs.push(dir);
+  const npmBin = join(dir, 'npm-bin');
+  const pnpmBin = join(dir, 'pnpm-bin');
+  mkdirSync(npmBin);
+  mkdirSync(pnpmBin);
+  const log = join(dir, 'npm.log');
+  writeFileSync(log, '');
+  writeFileSync(join(npmBin, 'npm'), '#!/bin/sh\necho "$*" >> "$NPM_LOG"\nexit "${NPM_EXIT:-0}"\n');
+  chmodSync(join(npmBin, 'npm'), 0o755);
+  writeFileSync(join(pnpmBin, 'pnpm'), '#!/bin/sh\nexit 0\n');
+  chmodSync(join(pnpmBin, 'pnpm'), 0o755);
+  const result = spawnSync('/bin/sh', ['-c', deepseekInstallCommand('linux')], {
+    env: {
+      PATH: opts.pnpmOnPath ? `${npmBin}:${pnpmBin}` : npmBin,
+      NPM_LOG: log,
+      NPM_EXIT: opts.npmFails ? '1' : '0',
+    },
+    encoding: 'utf-8',
+  });
+  const npmCalls = readFileSync(log, 'utf-8').split('\n').filter(Boolean);
+  return { status: result.status, npmCalls };
+}
+
+describe('DeepSeek install', () => {
+  it('is the same command on linux and darwin', () => {
+    expect(deepseekInstallCommand('darwin')).toBe(deepseekInstallCommand('linux'));
+  });
+
+  it('installs pnpm with dsh when none is on PATH, since `dsh plugin` spawns a literal pnpm', () => {
+    const { status, npmCalls } = runInstall({ pnpmOnPath: false });
+    expect(status).toBe(0);
+    expect(npmCalls).toEqual(['install -g @deepseek-ai/dsh', 'install -g pnpm']);
+  });
+
+  it('leaves an existing pnpm alone (a corepack shim makes `npm install -g pnpm` fail with EEXIST)', () => {
+    const { status, npmCalls } = runInstall({ pnpmOnPath: true });
+    expect(status).toBe(0);
+    expect(npmCalls).toEqual(['install -g @deepseek-ai/dsh']);
+  });
+
+  it('reports a failed dsh install and does not go on to pnpm', () => {
+    const { status, npmCalls } = runInstall({ pnpmOnPath: false, npmFails: true });
+    expect(status).not.toBe(0);
+    expect(npmCalls).toEqual(['install -g @deepseek-ai/dsh']);
+  });
+
+  it("puts dsh's own directory first on the profile install's PATH", () => {
+    const src = readFileSync(resolve(root, 'src/web/routes/system-routes.ts'), 'utf8');
+    expect(src).toMatch(/env: \{ \.\.\.process\.env, PATH: \[dir, process\.env\.PATH\]/);
+  });
+});

test/fixtures/codex-dialogs/trust-dialog-back.txt

@@ -0,0 +1,12 @@
+
+  Folder access
+  /tmp/codex-scratch/repo
+
+  Trust this folder? Codex can read, edit, and run files here, subject to your permission settings. Folder settings
+  can run code automatically, even without a model request. Continue only if you trust these files. Your trust
+  decision will be saved.
+
+› 1. Trust and continue
+  2. Back to Agent Command Center
+
+  enter continue · esc back

test/fixtures/styled-pane-capture.ts

@@ -0,0 +1,36 @@
+import { vi } from 'vitest';
+
+export const styledCapture = 'normal\n\x1b[30m\x1b[42m[session] 0:claude*\n';
+
+// Exercise the real capture method without a constructor or any real tmux IO.
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+  execFileSync: vi.fn(),
+  exec: vi.fn(),
+  execFile: vi.fn(),
+  spawn: vi.fn(),
+}));
+
+export async function createStyledPaneCapture() {
+  vi.resetModules();
+  vi.stubEnv('VITEST', undefined);
+  try {
+    const { TmuxManager } = await import('../../src/tmux-manager.js');
+    const { execSync } = await import('node:child_process');
+    const manager = Object.create(TmuxManager.prototype) as InstanceType<typeof TmuxManager>;
+    Object.defineProperty(manager, 'tmux', { value: () => 'fake-tmux' });
+    return (fullHistory: boolean, geometry = true, capture = styledCapture) => {
+      vi.mocked(execSync).mockImplementation((command) => {
+        if (String(command).includes('capture-pane')) return capture;
+        if (String(command).includes('display-message')) {
+          if (!geometry) throw new Error('cursor query failed');
+          return '0 0 40 2 0 1';
+        }
+        throw new Error(`Unexpected tmux command: ${command}`);
+      });
+      return manager.capturePaneBuffer('codeman-629', undefined, { fullHistory });
+    };
+  } finally {
+    vi.unstubAllEnvs();
+  }
+}

test/git-worktrees.test.ts

@@ -0,0 +1,484 @@
+/**
+ * @fileoverview src/git-worktrees.ts: the pure rules (worktree and branch names, `worktree list`
+ * parsing, the managed-path rule, exclude text) without git, then the IO half against a REAL temp
+ * repository (create, list, exclude, symlink guards, remove without --force, `branch -d`), plus an
+ * injected runner proving the Docker refusal never spawns git at all. Port: N/A.
+ */
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  agentSkillExcludeLine,
+  createCaseWorktree,
+  defaultWorktreeBranch,
+  excludeAppendText,
+  gitRefusalText,
+  isPathWithin,
+  listCaseWorktrees,
+  managedWorktreeName,
+  parseWorktreeList,
+  removeCaseWorktree,
+  resolveCaseRepository,
+  resolveManagedWorktree,
+  respellUnder,
+  runWorktreeGit,
+  unquoteGitPath,
+  worktreeBaseError,
+  worktreeBranchError,
+  worktreeNameError,
+  type CaseRepository,
+  type WorktreeGitRunner,
+} from '../src/git-worktrees.js';
+
+const ENV = {
+  ...process.env,
+  LC_ALL: 'C',
+  GIT_AUTHOR_NAME: 'T',
+  GIT_AUTHOR_EMAIL: 't@example.com',
+  GIT_COMMITTER_NAME: 'T',
+  GIT_COMMITTER_EMAIL: 't@example.com',
+  GIT_CONFIG_GLOBAL: '/dev/null',
+  GIT_CONFIG_NOSYSTEM: '1',
+};
+const git = (cwd: string, ...args: string[]) =>
+  execFileSync('git', args, { cwd, env: ENV, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+describe('worktreeNameError', () => {
+  it.each(['fix-login', 'a', 'v1.2', 'under_score', 'A9', 'x'.repeat(64)])('accepts %s', (name) => {
+    expect(worktreeNameError(name)).toBeNull();
+  });
+  it.each([
+    ['', 'required'],
+    ['x'.repeat(65), 'at most 64'],
+    ['-flag', 'start with a letter'],
+    ['.hidden', 'start with a letter'],
+    ['a/b', 'only letters'],
+    ['a b', 'only letters'],
+    ['a..b', '".."'],
+    ['name.', 'end with'],
+    ['name.lock', 'end with'],
+    ['semi;colon', 'only letters'],
+    ['ünï', 'only letters'],
+  ])('refuses %j', (name, why) => {
+    expect(worktreeNameError(name)).toContain(why);
+  });
+  it('refuses a non-string', () => {
+    expect(worktreeNameError(undefined)).not.toBeNull();
+    expect(worktreeNameError(42)).not.toBeNull();
+  });
+});
+
+describe('branch and base gates', () => {
+  it('derives Claude Code’s default branch name', () => {
+    expect(defaultWorktreeBranch('fix-login')).toBe('worktree-fix-login');
+  });
+  it.each(['main', 'feat/login', 'worktree-a.b', 'user/x_y-z'])('accepts branch %s', (b) => {
+    expect(worktreeBranchError(b)).toBeNull();
+  });
+  it.each(['-D', '@{-1}', 'a..b', 'a//b', 'trail/', 'x.lock', 'feat/.hidden', 'sp ace', 'a~1', 'a^', 'a:b'])(
+    'refuses branch %j',
+    (b) => {
+      expect(worktreeBranchError(b)).not.toBeNull();
+    }
+  );
+  it('gates the base like Clone Repo’s ref', () => {
+    expect(worktreeBaseError('HEAD')).toBeNull();
+    expect(worktreeBaseError('origin/main')).toBeNull();
+    expect(worktreeBaseError('--upload-pack=x')).not.toBeNull();
+    expect(worktreeBaseError('HEAD@{1}')).not.toBeNull();
+  });
+});
+
+describe('paths', () => {
+  it('names only <repo>/.claude/worktrees/<valid-name>', () => {
+    expect(managedWorktreeName('/r', '/r/.claude/worktrees/a')).toBe('a');
+    expect(managedWorktreeName('/r', '/r/.claude/worktrees/a/')).toBe('a');
+    expect(managedWorktreeName('/r', '/r/.claude/worktrees/a/sub')).toBeNull();
+    expect(managedWorktreeName('/r', '/r/.claude/worktrees/')).toBeNull();
+    expect(managedWorktreeName('/r', '/r/../x/.claude/worktrees/a')).toBeNull();
+    expect(managedWorktreeName('/r', '/other/.claude/worktrees/a')).toBeNull();
+    expect(managedWorktreeName('/r', '/r/.claude/worktrees/-x')).toBeNull();
+  });
+  it('isPathWithin is a segment match, not a string prefix', () => {
+    expect(isPathWithin('/r/.claude/worktrees/a', '/r/.claude/worktrees/a')).toBe(true);
+    expect(isPathWithin('/r/.claude/worktrees/a/src', '/r/.claude/worktrees/a')).toBe(true);
+    expect(isPathWithin('/r/.claude/worktrees/ab', '/r/.claude/worktrees/a')).toBe(false);
+  });
+  it('respellUnder moves a path named through the case link onto the real repository root', () => {
+    expect(respellUnder('/link/.claude/worktrees/a', '/link', '/real')).toBe('/real/.claude/worktrees/a');
+    expect(respellUnder('/link/.claude/worktrees/a/src/', '/link', '/real')).toBe('/real/.claude/worktrees/a/src');
+    expect(respellUnder('/link', '/link', '/real')).toBe('/real');
+    // Not under the alias (a segment match, never a string prefix), or no alias at all: unchanged.
+    expect(respellUnder('/linked/x', '/link', '/real')).toBe('/linked/x');
+    expect(respellUnder('/real/.claude/worktrees/a', '/link', '/real')).toBe('/real/.claude/worktrees/a');
+    expect(respellUnder('/real/x', '/real', '/real')).toBe('/real/x');
+  });
+});
+
+describe('parseWorktreeList', () => {
+  it('parses main, branch, detached, locked and prunable records', () => {
+    const text = [
+      'worktree /repo',
+      'HEAD 1111111111111111111111111111111111111111',
+      'branch refs/heads/main',
+      '',
+      'worktree /repo/.claude/worktrees/a',
+      'HEAD 2222222222222222222222222222222222222222',
+      'branch refs/heads/worktree-a',
+      'locked busy agent',
+      '',
+      'worktree /elsewhere/b',
+      'HEAD 3333333333333333333333333333333333333333',
+      'detached',
+      'prunable gitdir file points to non-existent location',
+      '',
+    ].join('\n');
+    const list = parseWorktreeList(text);
+    expect(list).toHaveLength(3);
+    expect(list[0]).toMatchObject({ path: '/repo', branch: 'main', detached: false, locked: false });
+    expect(list[1]).toMatchObject({ branch: 'worktree-a', locked: true, lockReason: 'busy agent' });
+    expect(list[2]).toMatchObject({ branch: null, detached: true, prunable: true });
+  });
+  it('reads a bare record and a record with no trailing blank line', () => {
+    const list = parseWorktreeList('worktree /bare.git\nbare\n\nworktree /w\nHEAD abc\nbranch refs/heads/x');
+    expect(list[0]).toMatchObject({ bare: true, head: null });
+    expect(list[1]).toMatchObject({ path: '/w', branch: 'x' });
+  });
+  it('unquotes a C-quoted path', () => {
+    expect(parseWorktreeList('worktree "/r/a\\"b\\303\\251"\nHEAD x\n')[0].path).toBe('/r/a"bé');
+  });
+});
+
+describe('unquoteGitPath', () => {
+  it('leaves plain text alone and decodes escapes', () => {
+    expect(unquoteGitPath('/plain path')).toBe('/plain path');
+    expect(unquoteGitPath('"/a\\tb\\\\c"')).toBe('/a\tb\\c');
+    expect(unquoteGitPath('"/\\344\\275\\240"')).toBe('/你');
+  });
+});
+
+describe('excludeAppendText', () => {
+  it('adds only what is missing, after a newline the file lacked', () => {
+    const r = excludeAppendText('*.log', ['/.claude/worktrees/', '/.claude/settings.local.json']);
+    expect(r.added).toEqual(['/.claude/worktrees/', '/.claude/settings.local.json']);
+    expect(r.text.startsWith('\n# Added by Codeman')).toBe(true);
+    expect(r.text.endsWith('/.claude/settings.local.json\n')).toBe(true);
+  });
+  it('is a no-op when every line is present', () => {
+    expect(excludeAppendText('/.claude/worktrees/\n', ['/.claude/worktrees/'])).toEqual({ text: '', added: [] });
+  });
+  it('agentSkillExcludeLine names the skill copy of a plain relative skills folder only', () => {
+    expect(agentSkillExcludeLine('.claude/skills')).toBe('/.claude/skills/codeman/');
+    expect(agentSkillExcludeLine('.agents/skills')).toBe('/.agents/skills/codeman/');
+    for (const bad of ['', '/abs', 'a/../b', 'a//b', '.', 'x/', 'a b', '*', '!neg']) {
+      expect(agentSkillExcludeLine(bad), bad).toBeNull();
+    }
+  });
+});
+
+describe('gitRefusalText', () => {
+  it('keeps fatal/error lines, drops hints and control bytes', () => {
+    const t = gitRefusalText(
+      "fatal: '.claude/worktrees/a' contains modified or untracked files, use --force to delete it\nhint: x\n\u001b[31m"
+    );
+    expect(t).toBe("fatal: '.claude/worktrees/a' contains modified or untracked files, use --force to delete it");
+  });
+});
+
+// ─── IO against a real repository ────────────────────────────────────────────
+
+describe('git worktrees on a real repository', () => {
+  let dir: string;
+  let repoDir: string;
+  let repo: CaseRepository;
+
+  beforeEach(async () => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), 'git-worktrees-')));
+    repoDir = join(dir, 'repo');
+    mkdirSync(repoDir);
+    git(repoDir, 'init', '-q', '-b', 'main');
+    writeFileSync(join(repoDir, 'a.txt'), '1\n');
+    git(repoDir, 'add', 'a.txt');
+    git(repoDir, 'commit', '-q', '-m', 'base');
+    const resolved = await resolveCaseRepository(repoDir, { home: '/nonexistent-home' });
+    if (!resolved.ok) throw new Error(resolved.message);
+    repo = resolved.repo;
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('resolves the repository root and the real common git dir', () => {
+    expect(repo.repoRoot).toBe(repoDir);
+    expect(repo.commonDir).toBe(join(repoDir, '.git'));
+  });
+
+  it('refuses a folder that is not a repository, and one below the top level', async () => {
+    const plain = join(dir, 'plain');
+    mkdirSync(plain);
+    const notRepo = await resolveCaseRepository(plain, { home: '/nonexistent-home' });
+    expect(notRepo).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+    mkdirSync(join(repoDir, 'sub'));
+    const sub = await resolveCaseRepository(join(repoDir, 'sub'), { home: '/nonexistent-home' });
+    expect(sub.ok).toBe(false);
+    if (!sub.ok) expect(sub.message).toContain('top of a git repository');
+  });
+
+  it('treats a repository at the home folder above the case as no repository', async () => {
+    mkdirSync(join(repoDir, 'proj'));
+    const r = await resolveCaseRepository(join(repoDir, 'proj'), { home: repoDir });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.message).toBe('This case folder is not a git repository.');
+  });
+
+  it('never spawns git for a case inside a Docker case workspace', async () => {
+    let spawned = 0;
+    const spy: WorktreeGitRunner = async () => {
+      spawned++;
+      return { code: 0, stdout: '', stderr: '', timedOut: false };
+    };
+    const r = await resolveCaseRepository(repoDir, { git: spy, dockerWorkspaces: [dir] });
+    expect(r).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+    expect(spawned).toBe(0);
+  });
+
+  it('creates <repo>/.claude/worktrees/<name> on worktree-<name>, excluded from the main checkout', async () => {
+    const created = await createCaseWorktree(repo, { name: 'fix-login' });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const wtPath = join(repoDir, '.claude', 'worktrees', 'fix-login');
+    expect(created.worktree).toMatchObject({ path: wtPath, branch: 'worktree-fix-login', base: 'HEAD' });
+    expect(created.worktree.excludeAdded).toEqual(['/.claude/worktrees/', '/.claude/settings.local.json']);
+    expect(readFileSync(join(wtPath, 'a.txt'), 'utf-8')).toBe('1\n');
+    expect(git(wtPath, 'rev-parse', '--abbrev-ref', 'HEAD').trim()).toBe('worktree-fix-login');
+    // The main checkout stays clean: the worktree folder is excluded, not untracked.
+    expect(git(repoDir, 'status', '--porcelain')).toBe('');
+    expect(readFileSync(join(repoDir, '.git', 'info', 'exclude'), 'utf-8')).toContain('/.claude/worktrees/');
+    // A hooks file Codeman would write into the worktree does not make it dirty either.
+    mkdirSync(join(wtPath, '.claude'), { recursive: true });
+    writeFileSync(join(wtPath, '.claude', 'settings.local.json'), '{}');
+    expect(git(wtPath, 'status', '--porcelain')).toBe('');
+
+    // A second create with the same lines already present appends nothing.
+    const second = await createCaseWorktree(repo, { name: 'other', branch: 'feat/other' });
+    expect(second.ok && second.worktree.excludeAdded).toEqual([]);
+    const listed = await listCaseWorktrees(repo);
+    expect(listed.ok).toBe(true);
+    if (!listed.ok) return;
+    expect(listed.worktrees.map((w) => [w.main, w.isCase, w.managed, w.name ?? null, w.branch])).toEqual([
+      [true, true, false, null, 'main'],
+      [false, false, true, 'fix-login', 'worktree-fix-login'],
+      [false, false, true, 'other', 'feat/other'],
+    ]);
+  });
+
+  it('refuses an existing branch, a bad base, a bad branch and a taken folder before touching anything', async () => {
+    git(repoDir, 'branch', 'worktree-taken');
+    expect(await createCaseWorktree(repo, { name: 'taken' })).toMatchObject({ ok: false, code: 'ALREADY_EXISTS' });
+    expect(await createCaseWorktree(repo, { name: 'x', base: 'nosuchref' })).toMatchObject({
+      ok: false,
+      code: 'INVALID_INPUT',
+    });
+    expect(await createCaseWorktree(repo, { name: 'x', branch: '@{-1}' })).toMatchObject({
+      ok: false,
+      code: 'INVALID_INPUT',
+    });
+    expect(await createCaseWorktree(repo, { name: '../escape' })).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+    mkdirSync(join(repoDir, '.claude', 'worktrees', 'busy'), { recursive: true });
+    expect(await createCaseWorktree(repo, { name: 'busy' })).toMatchObject({ ok: false, code: 'ALREADY_EXISTS' });
+    expect(git(repoDir, 'branch', '--list', 'worktree-busy')).toBe('');
+  });
+
+  it('names a taken worktree name as such, not as its derived branch', async () => {
+    expect((await createCaseWorktree(repo, { name: 'dup' })).ok).toBe(true);
+    const again = await createCaseWorktree(repo, { name: 'dup' });
+    expect(again).toMatchObject({ ok: false, code: 'ALREADY_EXISTS' });
+    if (!again.ok) expect(again.message).toBe('A worktree named "dup" already exists in this case.');
+  });
+
+  it('says a bare repository is bare', async () => {
+    const bare = join(dir, 'bare.git');
+    git(dir, 'init', '-q', '--bare', bare);
+    const r = await resolveCaseRepository(bare, { home: '/nonexistent-home' });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.message).toContain('bare git repository');
+  });
+
+  it('starts from a named base', async () => {
+    git(repoDir, 'checkout', '-q', '-b', 'side');
+    writeFileSync(join(repoDir, 'b.txt'), '2\n');
+    git(repoDir, 'add', 'b.txt');
+    git(repoDir, 'commit', '-q', '-m', 'side');
+    git(repoDir, 'checkout', '-q', 'main');
+    const created = await createCaseWorktree(repo, { name: 'from-side', base: 'side' });
+    expect(created.ok).toBe(true);
+    expect(readFileSync(join(repoDir, '.claude', 'worktrees', 'from-side', 'b.txt'), 'utf-8')).toBe('2\n');
+  });
+
+  it('refuses to create through a symlinked .claude or worktrees directory', async () => {
+    const outside = join(dir, 'outside');
+    mkdirSync(join(outside, 'worktrees'), { recursive: true });
+    symlinkSync(outside, join(repoDir, '.claude'));
+    const viaClaude = await createCaseWorktree(repo, { name: 'evil' });
+    expect(viaClaude).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+    if (!viaClaude.ok) expect(viaClaude.message).toContain('symlink');
+    rmSync(join(repoDir, '.claude'));
+    mkdirSync(join(repoDir, '.claude'));
+    symlinkSync(join(outside, 'worktrees'), join(repoDir, '.claude', 'worktrees'));
+    expect(await createCaseWorktree(repo, { name: 'evil' })).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+    expect(git(repoDir, 'worktree', 'list', '--porcelain')).not.toContain('evil');
+  });
+
+  it('removes a clean worktree, refuses a dirty one and a live one, and never force-deletes', async () => {
+    const created = await createCaseWorktree(repo, { name: 'w1' });
+    expect(created.ok).toBe(true);
+    const wtPath = join(repoDir, '.claude', 'worktrees', 'w1');
+
+    const live = await removeCaseWorktree(repo, { name: 'w1', isInUse: (p) => p === wtPath });
+    expect(live).toMatchObject({ ok: false, code: 'CONFLICT' });
+
+    writeFileSync(join(wtPath, 'scratch.txt'), 'untracked work');
+    const dirty = await removeCaseWorktree(repo, { name: 'w1', isInUse: () => false });
+    expect(dirty).toMatchObject({ ok: false, code: 'CONFLICT' });
+    if (!dirty.ok) expect(dirty.gitMessage).toContain('contains modified or untracked files');
+    expect(readFileSync(join(wtPath, 'scratch.txt'), 'utf-8')).toBe('untracked work');
+
+    rmSync(join(wtPath, 'scratch.txt'));
+    const clean = await removeCaseWorktree(repo, { name: 'w1', deleteBranch: true, isInUse: () => false });
+    expect(clean).toMatchObject({ ok: true, removed: { name: 'w1', branch: 'worktree-w1', branchDeleted: true } });
+    expect(git(repoDir, 'branch', '--list', 'worktree-w1')).toBe('');
+    expect(git(repoDir, 'worktree', 'list', '--porcelain')).not.toContain('w1');
+  });
+
+  it('never removes a worktree that is, or holds, a Docker case workspace', async () => {
+    const made = await createCaseWorktree(repo, { name: 'boxed' });
+    if (!made.ok) throw new Error(made.message);
+    const wtPath = made.worktree.path;
+    mkdirSync(join(wtPath, 'sandbox'));
+    // The worktree IS a Docker case's workspace, or one sits inside it: refused before git runs,
+    // and nothing is deleted. git still lists it.
+    for (const dockerWorkspaces of [[wtPath], [join(wtPath, 'sandbox')]]) {
+      let spawned = 0;
+      const counting: WorktreeGitRunner = async (cwd, args, o) => {
+        if (args.includes('remove')) spawned++;
+        return runWorktreeGit(cwd, args, o);
+      };
+      const r = await removeCaseWorktree(
+        repo,
+        { name: 'boxed', isInUse: () => false },
+        { git: counting, dockerWorkspaces }
+      );
+      expect(r).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+      if (!r.ok) expect(r.message).toContain('Docker case workspace');
+      expect(spawned).toBe(0);
+      expect(existsSync(join(wtPath, 'a.txt'))).toBe(true);
+    }
+    expect(git(repoDir, 'worktree', 'list', '--porcelain')).toContain('boxed');
+    // An unrelated Docker workspace does not get in the way.
+    rmSync(join(wtPath, 'sandbox'), { recursive: true });
+    const elsewhere = join(dir, 'other-box');
+    mkdirSync(elsewhere);
+    const ok = await removeCaseWorktree(
+      repo,
+      { name: 'boxed', isInUse: () => false },
+      { dockerWorkspaces: [elsewhere] }
+    );
+    expect(ok.ok).toBe(true);
+    expect(existsSync(wtPath)).toBe(false);
+  });
+
+  it('keeps an unmerged branch: git branch -d refuses, never -D', async () => {
+    await createCaseWorktree(repo, { name: 'w2' });
+    const wtPath = join(repoDir, '.claude', 'worktrees', 'w2');
+    writeFileSync(join(wtPath, 'new.txt'), 'x');
+    git(wtPath, 'add', 'new.txt');
+    git(wtPath, 'commit', '-q', '-m', 'work');
+    const r = await removeCaseWorktree(repo, { name: 'w2', deleteBranch: true, isInUse: () => false });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.removed.branchDeleted).toBe(false);
+    expect(r.removed.branchError).toContain('not fully merged');
+    expect(git(repoDir, 'branch', '--list', 'worktree-w2')).toContain('worktree-w2');
+  });
+
+  it('only removes a registered worktree that is a real directory', async () => {
+    mkdirSync(join(repoDir, '.claude', 'worktrees', 'stray'), { recursive: true });
+    expect(await removeCaseWorktree(repo, { name: 'stray', isInUse: () => false })).toMatchObject({
+      ok: false,
+      code: 'NOT_FOUND',
+    });
+    expect(await removeCaseWorktree(repo, { name: 'missing', isInUse: () => false })).toMatchObject({
+      ok: false,
+      code: 'NOT_FOUND',
+    });
+    // A symlink at the worktree's own place is refused, never followed.
+    await createCaseWorktree(repo, { name: 'real' });
+    symlinkSync(join(repoDir, '.claude', 'worktrees', 'real'), join(repoDir, '.claude', 'worktrees', 'link'));
+    expect(await resolveManagedWorktree(repo, 'link')).toMatchObject({ ok: false, code: 'INVALID_INPUT' });
+  });
+
+  it('refuses a locked worktree', async () => {
+    await createCaseWorktree(repo, { name: 'locked' });
+    git(repoDir, 'worktree', 'lock', '--reason', 'agent busy', join(repoDir, '.claude', 'worktrees', 'locked'));
+    const r = await removeCaseWorktree(repo, { name: 'locked', isInUse: () => false });
+    expect(r).toMatchObject({ ok: false, code: 'CONFLICT' });
+    if (!r.ok) expect(r.message).toContain('agent busy');
+  });
+
+  it('removes a worktree whose folder was deleted by hand, so its name can be used again', async () => {
+    const made = await createCaseWorktree(repo, { name: 'gone' });
+    if (!made.ok) throw new Error(made.message);
+    rmSync(made.worktree.path, { recursive: true, force: true });
+    const listed = await listCaseWorktrees(repo);
+    expect(listed.ok && listed.worktrees.find((w) => w.name === 'gone')).toMatchObject({
+      managed: true,
+      prunable: true,
+    });
+    // A session never starts in it; only removal accepts a missing folder.
+    expect(await resolveManagedWorktree(repo, 'gone')).toMatchObject({ ok: false, code: 'NOT_FOUND' });
+    // Before the fix this was NOT_FOUND, and both ways of reusing the name failed.
+    const r = await removeCaseWorktree(repo, { name: 'gone', deleteBranch: true, isInUse: () => false });
+    expect(r).toMatchObject({ ok: true, removed: { name: 'gone', branch: 'worktree-gone', branchDeleted: true } });
+    expect(git(repoDir, 'worktree', 'list', '--porcelain')).not.toContain('gone');
+    expect((await createCaseWorktree(repo, { name: 'gone' })).ok).toBe(true);
+  });
+
+  it('refuses a missing worktree that a live session still names, or that is locked', async () => {
+    const made = await createCaseWorktree(repo, { name: 'held' });
+    if (!made.ok) throw new Error(made.message);
+    git(repoDir, 'worktree', 'lock', '--reason', 'on a removable disk', made.worktree.path);
+    rmSync(made.worktree.path, { recursive: true, force: true });
+    expect(await removeCaseWorktree(repo, { name: 'held', isInUse: () => true })).toMatchObject({
+      ok: false,
+      code: 'CONFLICT',
+    });
+    const locked = await removeCaseWorktree(repo, { name: 'held', isInUse: () => false });
+    expect(locked).toMatchObject({ ok: false, code: 'CONFLICT' });
+    if (!locked.ok) expect(locked.message).toContain('removable disk');
+  });
+
+  it('never follows a symlink on the way to a missing worktree', async () => {
+    const made = await createCaseWorktree(repo, { name: 'via' });
+    if (!made.ok) throw new Error(made.message);
+    // The whole worktrees folder replaced by a link to somewhere else.
+    const elsewhere = join(dir, 'elsewhere');
+    mkdirSync(elsewhere);
+    rmSync(join(repoDir, '.claude', 'worktrees'), { recursive: true, force: true });
+    symlinkSync(elsewhere, join(repoDir, '.claude', 'worktrees'));
+    expect(await removeCaseWorktree(repo, { name: 'via', isInUse: () => false })).toMatchObject({
+      ok: false,
+      code: 'INVALID_INPUT',
+    });
+  });
+});

test/i18n-exit-run-help.test.ts

@@ -42,11 +42,14 @@ afterAll(() => {
   en.dom.window.close();
 });
 
-/** Latin words left after removing what may stay: key names, the AI acronym, the N placeholder. */
+/**
+ * Latin words left after removing what may stay: key names, the AI acronym, the N placeholder,
+ * and Git, a product name every translation that names it keeps (the Git status rows too).
+ */
 const leftover = (text: string) =>
   text
     .replace(/\b(Ctrl|Cmd|Shift|Alt|Option)\+\w+/g, '')
-    .replace(/\b(Ctrl|Cmd|Shift|Alt|Option|Enter|Tab|Space|End|Home|Escape|G|AI|N)\b/g, '')
+    .replace(/\b(Ctrl|Cmd|Shift|Alt|Option|Enter|Tab|Space|End|Home|Escape|G|AI|N|Git)\b/g, '')
     .match(/[A-Za-z]+/g) ?? [];
 
 const helpers = new Function(
@@ -204,7 +207,7 @@ describe('the case picker rows and the host-window and dictation toasts in zh-CN
   );
 
   it('finds the strings it checks (the check is not vacuous)', () => {
-    expect(pickerLabels).toEqual(['New or link a case\u2026', 'Case settings\u2026']);
+    expect(pickerLabels).toEqual(['New or link a case\u2026', 'Case settings\u2026', 'Git worktrees\u2026']);
     expect(SESSION_UI).toContain('<div class="case-combobox-empty">No cases match</div>');
     expect(toasts.sort()).toEqual([
       'Could not open a new window for this dashboard',

test/keyboard-shortcuts.test.ts

@@ -14,10 +14,11 @@ describe('keyboard shortcuts', () => {
   });
 
   it('provides Option+bracket shortcuts for previous and next session', () => {
-    expect(appSource).toContain("e.code === 'BracketLeft'");
-    expect(appSource).toContain("e.code === 'BracketRight'");
-    expect(appSource).toContain('this.prevSession()');
-    expect(appSource).toContain('this.nextSession()');
+    // Registry entries (so they can be rebound), matched by physical key code.
+    expect(appSource).toMatch(/id: 'previous-session'[\s\S]*?code: 'BracketLeft'[\s\S]*?action: 'previousSession'/);
+    expect(appSource).toMatch(/id: 'next-session-alt'[\s\S]*?code: 'BracketRight'[\s\S]*?action: 'nextSession'/);
+    expect(appSource).toContain('previousSession: () => this.prevSession()');
+    expect(appSource).toContain('nextSession: () => this.nextSession()');
   });
 
   it('suppresses xterm PTY injection for the same physical Alt nav codes (no ESC leak)', () => {
@@ -53,7 +54,7 @@ describe('keyboard shortcuts', () => {
     // getShortcutRegistry() + matchesShortcutEvent() so overrides and per-shortcut
     // disables (App Settings → Shortcuts) actually take effect.
     expect(appSource).not.toContain('const SHORTCUTS = [');
-    expect(appSource).toContain('const SHORTCUT_ACTIONS = {');
+    expect(appSource).toContain('const SHORTCUT_ACTIONS = this._shortcutActions();');
     expect(appSource).toContain('for (const shortcut of this.getShortcutRegistry())');
     expect(appSource).toContain('if (this.matchesShortcutEvent(e, shortcut))');
     expect(appSource).toContain('if (shortcut.disabled || !shortcut.action) continue;');

test/link-provider-regex.test.ts

@@ -151,6 +151,9 @@ describe('terminal link-provider regexes (shipped source)', () => {
       // Camera-roll video uploads the agent echoes back (VIDEO_ATTACHMENT_EXTENSIONS).
       '/home/a/.codeman-uploads/paste-1-ab.m4v',
       '/home/a/.codeman-uploads/paste-2-cd.ogv',
+      // Document uploads the agent echoes back (zip and tsv join the already-matched office/text set).
+      '/home/a/.codeman-uploads/paste-3-ef-archive.zip',
+      '/home/a/.codeman-uploads/paste-4-gh-data.tsv',
       // Longer extension of a family must win over its prefix (tsx over ts).
       '/home/a/src/App.tsx',
     ];

test/mobile-prompt-composer.test.ts

@@ -45,8 +45,14 @@ function loadComposer(sessionId = 'session-1') {
     _predictiveEcho: { clearPredictions: vi.fn() },
     _sendInputAsync: vi.fn(),
     _uploadAndInsertImages: vi.fn(async () => ['/tmp/image-one.png']),
-    _promptAttachKind: (file: { type: string }) =>
-      file.type.startsWith('image/') ? 'image' : file.type.startsWith('video/') ? 'video' : null,
+    _promptAttachKind: (file: { type: string; name?: string }) =>
+      file.type.startsWith('image/')
+        ? 'image'
+        : file.type.startsWith('video/')
+          ? 'video'
+          : /\.(pdf|docx|txt|md)$/i.test(file.name || '')
+            ? 'document'
+            : null,
     showToast: vi.fn(),
   };
   const schedule = (callback: () => void, delay = 0) => {
@@ -576,20 +582,40 @@ describe('mobile prompt composer', () => {
     expect((document.querySelector('.paste-send') as HTMLButtonElement).disabled).toBe(false);
   });
 
-  it('offers videos in the Image key picker and filters the pick through the shared classifier', async () => {
+  it('offers videos and documents in the Attach key picker and filters the pick through the shared classifier', async () => {
     const { app, bar, document } = loadComposer();
     bar.composePrompt();
     const fileInput = document.querySelector('.paste-file-input') as HTMLInputElement;
-    expect(fileInput.getAttribute('accept')).toBe('image/*,video/*');
+    expect(fileInput.getAttribute('accept')).toBe(
+      'image/*,video/*,.pdf,.docx,.pptx,.xlsx,.zip,.txt,.md,.csv,.tsv,.json,.log,.yaml,.yml,.xml'
+    );
+    expect((document.querySelector('.paste-image') as HTMLButtonElement).textContent).toBe('📎 Attach');
     const video = new document.defaultView!.File(['clip'], 'clip.mov', { type: 'video/quicktime' });
     const pdf = new document.defaultView!.File(['%PDF'], 'notes.pdf', { type: 'application/pdf' });
-    Object.defineProperty(fileInput, 'files', { configurable: true, value: [video, pdf] });
+    const script = new document.defaultView!.File(['#!/bin/sh'], 'run.sh', { type: 'text/x-shellscript' });
+    Object.defineProperty(fileInput, 'files', { configurable: true, value: [video, pdf, script] });
 
     fileInput.dispatchEvent(new document.defaultView!.Event('change', { bubbles: true }));
-    expect(app._uploadAndInsertImages).toHaveBeenCalledWith([video], { insert: false });
+    expect(app._uploadAndInsertImages).toHaveBeenCalledWith([video, pdf], { insert: false });
     await vi.waitFor(() => expect(textarea(document).value).toContain('/tmp/image-one.png'));
   });
 
+  it('puts an uploaded document path into the draft like a photo', async () => {
+    const { app, bar, document } = loadComposer();
+    app._uploadAndInsertImages.mockResolvedValueOnce(['/case/.codeman-uploads/paste-1-ab-notes.pdf']);
+    bar.composePrompt();
+    const input = textarea(document);
+    input.value = 'summarize';
+    input.selectionStart = input.selectionEnd = input.value.length;
+    input.dispatchEvent(new document.defaultView!.Event('input', { bubbles: true }));
+    const fileInput = document.querySelector('.paste-file-input') as HTMLInputElement;
+    const pdf = new document.defaultView!.File(['%PDF'], 'notes.pdf', { type: '' }); // no MIME: the name decides
+    Object.defineProperty(fileInput, 'files', { configurable: true, value: [pdf] });
+    fileInput.dispatchEvent(new document.defaultView!.Event('change', { bubbles: true }));
+    await vi.waitFor(() => expect(input.value).toBe('summarize /case/.codeman-uploads/paste-1-ab-notes.pdf'));
+    expect(app.terminal.paste).not.toHaveBeenCalled();
+  });
+
   it('takes a video pasted into the editor through the shared classifier', () => {
     const { app, bar, document } = loadComposer();
     bar.composePrompt();

test/routes/session-routes.test.ts

@@ -352,7 +352,7 @@ describe('session-routes', () => {
     });
 
     const jpeg = Buffer.from('ffd8ffe000104a46494600010100', 'hex');
-    const upload = (name: string, mime: string, bytes: Buffer) =>
+    const uploadImage = (name: string, mime: string, bytes: Buffer) =>
       harness.app.inject({
         method: 'POST',
         url: `/api/sessions/${harness.ctx._sessionId}/paste-image`,
@@ -368,14 +368,14 @@ describe('session-routes', () => {
       const workDir = await mkdtemp(join(tmpdir(), 'codeman-uploads-'));
       harness.ctx._session.workingDir = workDir;
       try {
-        const first = await upload('shot.jpg', 'image/jpeg', jpeg);
+        const first = await uploadImage('shot.jpg', 'image/jpeg', jpeg);
         expect(first.statusCode).toBe(200);
         expect(JSON.parse(first.body).data.path).toMatch(/\/\.codeman-uploads\/paste-\d+-[a-f0-9]{8}\.jpg$/);
         expect(await readdir(workDir)).toEqual(['.codeman-uploads']);
         expect(await readFile(join(workDir, '.codeman-uploads', '.gitignore'), 'utf8')).toBe('*\n');
 
         await writeFile(join(workDir, '.codeman-uploads', '.gitignore'), 'theirs\n');
-        expect((await upload('shot.jpg', 'image/jpeg', jpeg)).statusCode).toBe(200);
+        expect((await uploadImage('shot.jpg', 'image/jpeg', jpeg)).statusCode).toBe(200);
         expect(await readFile(join(workDir, '.codeman-uploads', '.gitignore'), 'utf8')).toBe('theirs\n');
       } finally {
         await rm(workDir, { recursive: true });
@@ -392,9 +392,9 @@ describe('session-routes', () => {
         throw Object.assign(new Error('no space left on device'), { code: 'ENOSPC' });
       });
       try {
-        expect((await upload('shot.jpg', 'image/jpeg', jpeg)).statusCode).toBe(500);
+        expect((await uploadImage('shot.jpg', 'image/jpeg', jpeg)).statusCode).toBe(500);
         expect(existsSync(ignoreFile)).toBe(false);
-        expect((await upload('shot.jpg', 'image/jpeg', jpeg)).statusCode).toBe(200);
+        expect((await uploadImage('shot.jpg', 'image/jpeg', jpeg)).statusCode).toBe(200);
         expect(await readFile(ignoreFile, 'utf8')).toBe('*\n');
       } finally {
         spy.mockRestore();
@@ -408,7 +408,7 @@ describe('session-routes', () => {
       harness.ctx._session.workingDir = workDir;
       await symlink(elsewhere, join(workDir, '.codeman-uploads'));
       try {
-        const res = await upload('shot.jpg', 'image/jpeg', jpeg);
+        const res = await uploadImage('shot.jpg', 'image/jpeg', jpeg);
         expect(res.statusCode).toBe(403);
         expect(JSON.parse(res.body).error).toBe('.codeman-uploads is not a regular directory');
         expect(await readdir(elsewhere)).toEqual([]);
@@ -424,7 +424,7 @@ describe('session-routes', () => {
       // A remote session's workingDir is the REMOTE path: a file written here is unreadable there.
       (harness.ctx._session as unknown as { remote: unknown }).remote = { hostId: 'gpu-box' };
       try {
-        const res = await upload('shot.jpg', 'image/jpeg', jpeg);
+        const res = await uploadImage('shot.jpg', 'image/jpeg', jpeg);
         expect(res.statusCode).toBe(400);
         expect(JSON.parse(res.body).error).toMatch(/remote/);
         expect(await readdir(workDir)).toEqual([]);
@@ -591,9 +591,9 @@ describe('session-routes', () => {
         headers: movHeaders,
         payload: imageUploadBody(boundary, 'IMG_0001.MOV', 'video/quicktime', qtMov),
       });
-      // The image path falls back to .png for an unknown type and fails its magic check.
-      expect(res.statusCode).toBe(415);
-      expect(JSON.parse(res.body).error).toMatch(/do not match declared type/);
+      // Named as a type the image path does not take: once the sniff fails, refused by name.
+      expect(res.statusCode).toBe(400);
+      expect(JSON.parse(res.body).error).toMatch(/Unsupported file type: \.mov/);
     });
 
     it('refuses an image declared under ?kind=video, so nothing rides the video cap through memory', async () => {
@@ -757,6 +757,117 @@ describe('session-routes', () => {
         await rm(workDir, { recursive: true });
       }
     });
+
+    // Documents: admitted by the name's extension, judged on the bytes, buffered
+    // like an image, saved with a sanitized stem of the original name.
+    const pdf = Buffer.concat([Buffer.from('%PDF-1.4\n%'), Buffer.alloc(16)]);
+    const zip = Buffer.concat([Buffer.from('504b0304140000000800', 'hex'), Buffer.alloc(16)]);
+    const upload = (name: string, mime: string, bytes: Buffer) =>
+      harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/paste-image`,
+        headers: movHeaders,
+        payload: imageUploadBody(boundary, name, mime, bytes),
+      });
+
+    it('accepts a PDF, an OOXML document and a text file into .codeman-uploads with the name kept', async () => {
+      const workDir = await mkdtemp(join(tmpdir(), 'codeman-doc-'));
+      harness.ctx._session.workingDir = workDir;
+      for (const [name, mime, bytes, saved] of [
+        ['Q3 report.pdf', 'application/pdf', pdf, /\/\.codeman-uploads\/paste-\d+-[a-f0-9]{8}-Q3-report\.pdf$/],
+        ['notes.docx', 'application/octet-stream', zip, /-notes\.docx$/], // no usable MIME: the name decides
+        ['todo.md', 'text/markdown', Buffer.from('# héllo\n- [ ] one\n'), /-todo\.md$/],
+        ['data.csv', 'application/octet-stream', Buffer.from('a,b\n1,2\n'), /-data\.csv$/],
+        ['archive.zip', 'application/zip', zip, /-archive\.zip$/],
+      ] as const) {
+        const res = await upload(name, mime, bytes);
+        expect(res.statusCode, name).toBe(200);
+        const body = JSON.parse(res.body);
+        expect(body.data.path, name).toMatch(saved);
+        expect(await readFile(body.data.path), name).toEqual(bytes);
+      }
+      // The workspace-side convention: the dir ignores itself, the old dir is not created.
+      expect(await readFile(join(workDir, '.codeman-uploads', '.gitignore'), 'utf8')).toBe('*\n');
+      expect(await readdir(workDir)).toEqual(['.codeman-uploads']);
+      await rm(workDir, { recursive: true });
+    });
+
+    it('keeps only [A-Za-z0-9._-] of the original stem, capped at 40 chars', async () => {
+      const workDir = await mkdtemp(join(tmpdir(), 'codeman-doc-'));
+      harness.ctx._session.workingDir = workDir;
+      const res = await upload('../..\\ (final) ' + 'x'.repeat(60) + '.v2.PDF', 'application/pdf', pdf);
+      expect(res.statusCode).toBe(200);
+      const { filename } = JSON.parse(res.body).data;
+      expect(filename).toMatch(/^paste-\d+-[a-f0-9]{8}-final-x{34}\.pdf$/);
+      await rm(workDir, { recursive: true });
+    });
+
+    it('refuses a script or an HTML page by name, with a message that says so', async () => {
+      const workDir = await mkdtemp(join(tmpdir(), 'codeman-doc-'));
+      harness.ctx._session.workingDir = workDir;
+      for (const [name, mime] of [
+        ['run.sh', 'text/x-shellscript'],
+        ['page.html', 'text/html'],
+        ['app.py', 'text/x-python'],
+      ] as const) {
+        const res = await upload(name, mime, Buffer.from('#!/bin/sh\necho hi\n'));
+        expect(res.statusCode, name).toBe(400);
+        expect(JSON.parse(res.body).error, name).toMatch(/Unsupported file type/);
+      }
+      expect(await readdir(workDir)).toEqual([]);
+      await rm(workDir, { recursive: true });
+    });
+
+    it('keeps the image path for an image MIME under a document name and for HEIC under a generic name', async () => {
+      const workDir = await mkdtemp(join(tmpdir(), 'codeman-doc-'));
+      harness.ctx._session.workingDir = workDir;
+      heicConvert.mockClear();
+      const gif = Buffer.concat([Buffer.from('GIF89a'), Buffer.alloc(10)]);
+      const heic = Buffer.from('00000034667479706865696300000000', 'hex');
+      for (const [name, mime, bytes, ext] of [
+        ['animation.txt', 'image/gif', gif, '.gif'], // the MIME type wins over the name, as on the client
+        ['camera.pdf', 'image/heic', heic, '.jpg'],
+        ['camera.bin', 'application/octet-stream', heic, '.jpg'], // sniffed, as it was before documents
+      ] as const) {
+        const res = await upload(name, mime, bytes);
+        expect(res.statusCode, name).toBe(200);
+        expect(JSON.parse(res.body).data.filename.endsWith(ext), name).toBe(true);
+      }
+      expect(heicConvert).toHaveBeenCalledTimes(2);
+      await rm(workDir, { recursive: true });
+    });
+
+    it('logs why a text upload was refused without printing its bytes', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        const secret = Buffer.from('token=SECRET\u0000');
+        expect((await upload('notes.txt', 'text/plain', secret)).statusCode).toBe(415);
+        const line = warn.mock.calls.map((c) => String(c[0])).find((l) => l.includes('declaredExt=.txt'));
+        expect(line).toMatch(/reason=nul-byte/);
+        expect(line).not.toContain(secret.toString('hex'));
+        expect(line).not.toContain('SECRET');
+      } finally {
+        warn.mockRestore();
+      }
+    });
+
+    it('refuses document bytes that do not match the declared type', async () => {
+      const workDir = await mkdtemp(join(tmpdir(), 'codeman-doc-'));
+      harness.ctx._session.workingDir = workDir;
+      const png = Buffer.concat([Buffer.from('89504e470d0a1a0a', 'hex'), Buffer.alloc(24)]);
+      for (const [name, bytes] of [
+        ['fake.pdf', png], // PNG bytes under a PDF name
+        ['fake.docx', pdf], // a PDF under an OOXML name
+        ['binary.txt', Buffer.from('hello\u0000world')], // a NUL byte is never text
+        ['latin1.csv', Buffer.from([0x61, 0x2c, 0xe9, 0x0a])], // not UTF-8
+      ] as const) {
+        const res = await upload(name, 'application/octet-stream', bytes);
+        expect(res.statusCode, name).toBe(415);
+        expect(JSON.parse(res.body).error, name).toMatch(/do not match declared type/);
+      }
+      expect(await readdir(workDir)).toEqual([]);
+      await rm(workDir, { recursive: true });
+    });
   });
 
   // ========== GET /api/sessions ==========

test/routes/status-telemetry-routes.test.ts

@@ -154,6 +154,20 @@ describe('POST /api/status-telemetry', () => {
     expect(events.filter((e) => e === SessionPromptCache)).toHaveLength(1);
   });
 
+  it('keeps the first 20 miss causes instead of refusing a post that carries more', async () => {
+    const causes = Array.from({ length: 25 }, (_, i) => `cause_${i}`);
+    const res = await post({
+      sessionId: SID,
+      data: { ...REAL, prompt_cache: { warm: false, ttl: '1h', last_miss_cause: { causes } } },
+    });
+    // Accepted, not 400: an over-long causes array must not blank the whole statusline.
+    expect(res.statusCode).toBe(200);
+    const session = h.ctx.sessions.get(SID) as unknown as { promptCache: { lastMissCauses?: string[] } | null };
+    expect(session.promptCache?.lastMissCauses).toHaveLength(20);
+    expect(session.promptCache?.lastMissCauses?.[0]).toBe('cause_0');
+    expect(session.promptCache?.lastMissCauses?.[19]).toBe('cause_19');
+  });
+
   it('rejects a malformed body (missing sessionId) with 400', async () => {
     const res = await post({ data: REAL });
     expect(res.statusCode).toBe(400);
@@ -212,6 +226,20 @@ describe('POST /api/status-telemetry: the session model (displayModel)', () => {
     expect(session.toState().displayModel).toBeUndefined();
   });
 
+  it('stores no prompt-cache from a CLI with no statusline exporter, but still broadcasts plan usage', async () => {
+    const session = realSession('codex', 'codex-cache');
+    const res = await post({
+      sessionId: 'codex-cache',
+      data: { ...REAL, prompt_cache: { warm: true, ttl: '1h', expires_at: Math.floor(Date.now() / 1000) + 3600 } },
+    });
+    expect(res.statusCode).toBe(200);
+    // Prompt cache is gated like the model report; the rest of the post still lands.
+    expect(session.toState().promptCache).toBeUndefined();
+    const events = h.ctx.broadcast.mock.calls.map(([name]) => name);
+    expect(events).not.toContain(SessionPromptCache);
+    expect(events).toContain(SessionStatusTelemetry);
+  });
+
   it('broadcasts the STORED prompt-cache object, so a compaction stamp reaches the live readout', async () => {
     const session = realSession('claude', 'claude-compact');
     const expiresAtS = Math.floor(Date.now() / 1000) + 3600;

test/routes/system-routes-settings-admin-only.test.ts

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Multi-user mode: server-wide settings writes are admin-only.
+ *
+ * `~/.codeman/settings.json` is ONE file for the whole server (feature switches, the
+ * plan-usage collection switch, run mode, respawn presets, the tunnel). Before this,
+ * any signed-in NON-ADMIN could rewrite it through PUT /api/settings, although
+ * docs/multi-user-plan.md makes settings writes admin-only. Pinned here:
+ *  - a non-admin PUT /api/settings is 403 FORBIDDEN before anything is parsed (an
+ *    invalid body is still 403, not 400), written, toggled or started (watchers, the
+ *    tunnel, the tmux history limit);
+ *  - the same gate on the other server-wide writes: PUT /api/execution/model-config,
+ *    PUT /api/config and PUT /api/cases/order;
+ *  - an admin, and single-user mode, write as before; GET /api/settings stays readable,
+ *    but a non-admin reads it without the admin's Deepgram key and case names
+ *    (settingsForNonAdmin).
+ *
+ * Uses app.inject(), so no real HTTP port is needed. Port: N/A.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerSystemRoutes, settingsForNonAdmin } from '../../src/web/routes/system-routes.js';
+import { registerCaseRoutes } from '../../src/web/routes/case-routes.js';
+
+const { STORED, subagentWatcher, imageWatcher, workflowRunWatcher } = vi.hoisted(() => {
+  const makeWatcher = (running: boolean) => {
+    let isOn = running;
+    return {
+      isRunning: vi.fn(() => isOn),
+      start: vi.fn(() => {
+        isOn = true;
+      }),
+      stop: vi.fn(() => {
+        isOn = false;
+      }),
+      getStats: vi.fn(() => ({})),
+      watchSession: vi.fn(),
+      getRecentRunSummaries: vi.fn(() => []),
+      __reset: () => {
+        isOn = running;
+      },
+    };
+  };
+  return {
+    // The persisted settings.json these tests start from.
+    STORED: { subagentTrackingEnabled: false, imageWatcherEnabled: true, cliManagementEnabled: false },
+    subagentWatcher: makeWatcher(false),
+    imageWatcher: makeWatcher(true),
+    workflowRunWatcher: makeWatcher(false),
+  };
+});
+
+vi.mock('node:fs/promises', () => ({
+  default: {
+    readFile: vi.fn(async () => JSON.stringify(STORED)),
+    writeFile: vi.fn(async () => undefined),
+  },
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return { ...actual, existsSync: vi.fn(() => true), mkdirSync: vi.fn(), readdirSync: vi.fn(() => []) };
+});
+
+vi.mock('../../src/subagent-watcher.js', () => ({ subagentWatcher }));
+vi.mock('../../src/image-watcher.js', () => ({ imageWatcher }));
+vi.mock('../../src/workflow-run-watcher.js', () => ({ workflowRunWatcher }));
+
+import fs from 'node:fs/promises';
+const writeFile = vi.mocked(fs.writeFile);
+const readFile = vi.mocked(fs.readFile);
+
+const NON_ADMIN = { username: 'bob', role: 'user' } as const;
+const ADMIN = { username: 'root', role: 'admin' } as const;
+
+function makeTunnelManager() {
+  return {
+    start: vi.fn(),
+    stop: vi.fn(),
+    isRunning: vi.fn(() => false),
+    getUrl: vi.fn(() => null),
+    getStatus: vi.fn(() => ({ running: false })),
+  };
+}
+
+/** A body that would touch everything PUT /api/settings can act on. */
+const EVERYTHING = {
+  tunnelEnabled: true,
+  subagentTrackingEnabled: true,
+  imageWatcherEnabled: false,
+  showUltracodeAgents: true,
+  tmuxHistoryLimit: 50000,
+  cliManagementEnabled: true,
+  runMode: 'shell',
+};
+
+describe('server-wide settings writes are admin-only in multi-user mode', () => {
+  const savedMultiUser = process.env.CODEMAN_MULTIUSER;
+  let harness: RouteTestHarness | undefined;
+  let tunnel: ReturnType<typeof makeTunnelManager>;
+
+  async function as(user: typeof NON_ADMIN | typeof ADMIN | null, register = registerSystemRoutes) {
+    if (user) process.env.CODEMAN_MULTIUSER = '1';
+    else delete process.env.CODEMAN_MULTIUSER;
+    harness = await createRouteTestHarness(register, user ? { authUser: user } : undefined);
+    tunnel = makeTunnelManager();
+    (harness.ctx as unknown as { tunnelManager: unknown }).tunnelManager = tunnel;
+    return harness;
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    for (const w of [subagentWatcher, imageWatcher, workflowRunWatcher]) w.__reset();
+  });
+
+  afterEach(async () => {
+    await harness?.app.close();
+    harness = undefined;
+    if (savedMultiUser === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = savedMultiUser;
+  });
+
+  describe('PUT /api/settings', () => {
+    it('refuses a non-admin with 403 FORBIDDEN, and nothing is written, toggled or started', async () => {
+      const { app, ctx } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'PUT', url: '/api/settings', payload: EVERYTHING });
+
+      expect(res.statusCode).toBe(403);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+      expect(body.errorCode).toBe('FORBIDDEN');
+      expect(writeFile).not.toHaveBeenCalled();
+      for (const w of [subagentWatcher, imageWatcher, workflowRunWatcher]) {
+        expect(w.start).not.toHaveBeenCalled();
+        expect(w.stop).not.toHaveBeenCalled();
+      }
+      expect(tunnel.start).not.toHaveBeenCalled();
+      expect(ctx.mux.setHistoryLimit).not.toHaveBeenCalled();
+    });
+
+    it('refuses a non-admin before the body is even parsed (an invalid body is 403, not 400)', async () => {
+      const { app } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'PUT', url: '/api/settings', payload: { notASetting: 1 } });
+      expect(res.statusCode).toBe(403);
+      expect(JSON.parse(res.body).errorCode).toBe('FORBIDDEN');
+      expect(writeFile).not.toHaveBeenCalled();
+    });
+
+    it('still lets a non-admin READ the settings', async () => {
+      const { app } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'GET', url: '/api/settings' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual(STORED);
+    });
+
+    for (const [label, user] of [
+      ['an admin in multi-user mode', ADMIN],
+      ['single-user mode', null],
+    ] as const) {
+      it(`writes, reconciles watchers and starts the tunnel for ${label}`, async () => {
+        const { app, ctx } = await as(user);
+        // Single-user mode with no CODEMAN_PASSWORD needs the COD-55 tunnel acknowledgement
+        // (multi-user mode counts as authenticated); that guard is not what this file tests.
+        const payload = user ? EVERYTHING : { ...EVERYTHING, acknowledgeUnauthTunnel: true };
+        const res = await app.inject({ method: 'PUT', url: '/api/settings', payload });
+
+        expect(res.statusCode).toBe(200);
+        expect(writeFile).toHaveBeenCalledTimes(1);
+        const written = JSON.parse(String(writeFile.mock.calls[0][1]));
+        expect(written).toMatchObject({ ...STORED, ...EVERYTHING });
+        expect(subagentWatcher.start).toHaveBeenCalledTimes(1);
+        expect(imageWatcher.stop).toHaveBeenCalledTimes(1);
+        expect(workflowRunWatcher.start).toHaveBeenCalledTimes(1);
+        expect(tunnel.start).toHaveBeenCalledTimes(1);
+        expect(ctx.mux.setHistoryLimit).toHaveBeenCalledTimes(1);
+      });
+    }
+  });
+
+  describe("GET /api/settings: what is the admin's stays the admin's", () => {
+    // An admin's App Settings save stores the Deepgram key (voiceSettings.apiKey) here, and
+    // the admin's own cases are named in caseOrder / lastUsedCase.
+    const WITH_SECRETS = {
+      autoNameSessions: true,
+      runMode: 'shell',
+      caseOrder: ['rootcase', 'secret-project'],
+      lastUsedCase: 'secret-project',
+      voiceSettings: { provider: 'deepgram', apiKey: 'dg-SECRET-probe-123', language: 'en' },
+    };
+
+    it('gives a non-admin the settings without the Deepgram key and the case names', async () => {
+      const { app } = await as(NON_ADMIN);
+      readFile.mockResolvedValueOnce(JSON.stringify(WITH_SECRETS));
+      const res = await app.inject({ method: 'GET', url: '/api/settings' });
+      expect(res.statusCode).toBe(200);
+      expect(res.body).not.toContain('dg-SECRET-probe-123');
+      expect(res.body).not.toContain('secret-project');
+      expect(JSON.parse(res.body)).toEqual({
+        autoNameSessions: true,
+        runMode: 'shell',
+        voiceSettings: { provider: 'deepgram', language: 'en' },
+      });
+    });
+
+    for (const [label, user] of [
+      ['an admin in multi-user mode', ADMIN],
+      ['single-user mode', null],
+    ] as const) {
+      it(`gives ${label} the file as it is`, async () => {
+        const { app } = await as(user);
+        readFile.mockResolvedValueOnce(JSON.stringify(WITH_SECRETS));
+        const res = await app.inject({ method: 'GET', url: '/api/settings' });
+        expect(res.statusCode).toBe(200);
+        expect(JSON.parse(res.body)).toEqual(WITH_SECRETS);
+      });
+    }
+
+    it('settingsForNonAdmin leaves its input alone and passes a non-object through', () => {
+      const input = structuredClone(WITH_SECRETS);
+      settingsForNonAdmin(input);
+      expect(input).toEqual(WITH_SECRETS);
+      expect(settingsForNonAdmin([1, 2])).toEqual([1, 2]);
+      expect(settingsForNonAdmin(null)).toBe(null);
+      expect(settingsForNonAdmin({ voiceSettings: { language: 'de' } })).toEqual({ voiceSettings: { language: 'de' } });
+    });
+  });
+
+  describe('PUT /api/execution/model-config', () => {
+    const config = { defaultModel: 'opus', agentTypeOverrides: { explore: 'sonnet' } };
+
+    it('refuses a non-admin with 403 FORBIDDEN and writes nothing', async () => {
+      const { app } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'PUT', url: '/api/execution/model-config', payload: config });
+      expect(res.statusCode).toBe(403);
+      expect(JSON.parse(res.body).errorCode).toBe('FORBIDDEN');
+      expect(writeFile).not.toHaveBeenCalled();
+    });
+
+    it('writes it for an admin', async () => {
+      const { app } = await as(ADMIN);
+      const res = await app.inject({ method: 'PUT', url: '/api/execution/model-config', payload: config });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(String(writeFile.mock.calls[0][1])).modelConfig).toEqual(config);
+    });
+
+    it('stays readable by a non-admin', async () => {
+      const { app } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'GET', url: '/api/execution/model-config' });
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('PUT /api/config', () => {
+    it('refuses a non-admin with 403 FORBIDDEN and changes nothing', async () => {
+      const { app, ctx } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'PUT', url: '/api/config', payload: { maxConcurrentSessions: 50 } });
+      expect(res.statusCode).toBe(403);
+      expect(JSON.parse(res.body).errorCode).toBe('FORBIDDEN');
+      expect(ctx.store.setConfig).not.toHaveBeenCalled();
+    });
+
+    it('updates it for an admin', async () => {
+      const { app, ctx } = await as(ADMIN);
+      const res = await app.inject({ method: 'PUT', url: '/api/config', payload: { maxConcurrentSessions: 10 } });
+      expect(res.statusCode).toBe(200);
+      expect(ctx.store.setConfig).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('PUT /api/cases/order (the one global caseOrder in settings.json)', () => {
+    it('refuses a non-admin with 403 FORBIDDEN and writes nothing', async () => {
+      const { app, ctx } = await as(NON_ADMIN, registerCaseRoutes);
+      const res = await app.inject({ method: 'PUT', url: '/api/cases/order', payload: { order: ['b', 'a'] } });
+      expect(res.statusCode).toBe(403);
+      expect(JSON.parse(res.body).errorCode).toBe('FORBIDDEN');
+      expect(writeFile).not.toHaveBeenCalled();
+      expect(ctx.broadcast).not.toHaveBeenCalled();
+    });
+
+    for (const [label, user] of [
+      ['an admin in multi-user mode', ADMIN],
+      ['single-user mode', null],
+    ] as const) {
+      it(`writes it for ${label}`, async () => {
+        const { app } = await as(user, registerCaseRoutes);
+        const res = await app.inject({ method: 'PUT', url: '/api/cases/order', payload: { order: ['b', 'a'] } });
+        expect(res.statusCode).toBe(200);
+        expect(JSON.parse(String(writeFile.mock.calls[0][1])).caseOrder).toEqual(['b', 'a']);
+      });
+    }
+  });
+});

test/routes/system-routes-system-ops-admin-only.test.ts

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Multi-user mode: the server-wide system operations are admin-only.
+ *
+ * docs/multi-user-plan.md lists the system operations (self-update, the tunnel,
+ * span-displays) as admin-only, but these routes had no role check, so any signed-in
+ * NON-ADMIN could run them. Pinned here:
+ *  - POST /api/system/update, POST /api/system/span-displays, POST /api/tunnel/qr/regenerate
+ *    and POST /api/cleanup-state answer 403 FORBIDDEN to a non-admin, and nothing runs;
+ *  - POST /api/auth/revoke: a non-admin revokes only their OWN login sessions (the bare
+ *    form used to clear every session on the server, every admin's included), and a named
+ *    token only when it is one of theirs;
+ *  - GET /api/tunnel/info lists only the caller's own logins for a non-admin;
+ *  - an admin, and single-user mode, behave as before.
+ *
+ * Uses app.inject(), so no real HTTP port is needed. Port: N/A.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerSystemRoutes } from '../../src/web/routes/system-routes.js';
+import { StaleExpirationMap } from '../../src/utils/stale-expiration-map.js';
+import type { AuthSessionRecord } from '../../src/web/ports/auth-port.js';
+
+const { startUpdate } = vi.hoisted(() => ({
+  startUpdate: vi.fn(async () => ({ ok: true, updateId: 'u1', toTag: 'v9.9.9', toVersion: '9.9.9' })),
+}));
+
+vi.mock('../../src/web/self-update.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../src/web/self-update.js')>();
+  return { ...actual, startUpdate };
+});
+
+const NON_ADMIN = { username: 'bob', role: 'user' } as const;
+const ADMIN = { username: 'root', role: 'admin' } as const;
+
+function makeTunnelManager() {
+  return {
+    regenerateQrToken: vi.fn(),
+    isRunning: vi.fn(() => true),
+    getUrl: vi.fn(() => 'https://example.trycloudflare.com'),
+    getStatus: vi.fn(() => ({ running: true, url: 'https://example.trycloudflare.com' })),
+  };
+}
+
+function record(username: string | undefined, ip: string): AuthSessionRecord {
+  return {
+    ip,
+    ua: 'test-agent',
+    createdAt: 1,
+    method: 'basic',
+    username,
+    role: username === 'root' ? 'admin' : 'user',
+  };
+}
+
+describe('server-wide system operations are admin-only in multi-user mode', () => {
+  const savedMultiUser = process.env.CODEMAN_MULTIUSER;
+  let harness: RouteTestHarness | undefined;
+  let tunnel: ReturnType<typeof makeTunnelManager>;
+  let sessions: StaleExpirationMap<string, AuthSessionRecord>;
+
+  async function as(user: typeof NON_ADMIN | typeof ADMIN | null) {
+    if (user) process.env.CODEMAN_MULTIUSER = '1';
+    else delete process.env.CODEMAN_MULTIUSER;
+    harness = await createRouteTestHarness(registerSystemRoutes, user ? { authUser: user } : undefined);
+    tunnel = makeTunnelManager();
+    sessions = new StaleExpirationMap<string, AuthSessionRecord>({ ttlMs: 60_000 });
+    // Two logins of the non-admin, one of an admin, one single-user (no identity).
+    sessions.set('bob-laptop', record('bob', '10.0.0.2'));
+    sessions.set('bob-phone', record('bob', '10.0.0.3'));
+    sessions.set('root-desk', record('root', '10.0.0.1'));
+    Object.assign(harness.ctx as unknown as Record<string, unknown>, { tunnelManager: tunnel, authSessions: sessions });
+    return harness;
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    await harness?.app.close();
+    harness = undefined;
+    sessions?.dispose();
+    if (savedMultiUser === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = savedMultiUser;
+  });
+
+  const forbidden = (res: { statusCode: number; body: string }) => {
+    expect(res.statusCode).toBe(403);
+    const body = JSON.parse(res.body);
+    expect(body.success).toBe(false);
+    expect(body.errorCode).toBe('FORBIDDEN');
+  };
+
+  describe('POST /api/system/update', () => {
+    it('refuses a non-admin, and no update starts', async () => {
+      const { app } = await as(NON_ADMIN);
+      forbidden(await app.inject({ method: 'POST', url: '/api/system/update', payload: {} }));
+      expect(startUpdate).not.toHaveBeenCalled();
+    });
+
+    for (const [label, user] of [
+      ['an admin in multi-user mode', ADMIN],
+      ['single-user mode', null],
+    ] as const) {
+      it(`starts it for ${label}`, async () => {
+        const { app } = await as(user);
+        const res = await app.inject({ method: 'POST', url: '/api/system/update', payload: {} });
+        expect(res.statusCode).toBe(200);
+        expect(startUpdate).toHaveBeenCalledTimes(1);
+      });
+    }
+  });
+
+  describe('POST /api/system/span-displays', () => {
+    it('refuses a non-admin before anything else', async () => {
+      const { app } = await as(NON_ADMIN);
+      forbidden(await app.inject({ method: 'POST', url: '/api/system/span-displays' }));
+    });
+
+    it('lets an admin through the gate (off macOS the route then answers its own 400)', async () => {
+      const { app } = await as(ADMIN);
+      const res = await app.inject({ method: 'POST', url: '/api/system/span-displays' });
+      if (process.platform === 'darwin') expect(res.statusCode).not.toBe(403);
+      else expect(res.statusCode).toBe(400);
+    });
+  });
+
+  describe('POST /api/tunnel/qr/regenerate', () => {
+    it("refuses a non-admin, and nobody's QR codes are cleared", async () => {
+      const { app } = await as(NON_ADMIN);
+      forbidden(await app.inject({ method: 'POST', url: '/api/tunnel/qr/regenerate' }));
+      expect(tunnel.regenerateQrToken).not.toHaveBeenCalled();
+    });
+
+    for (const [label, user] of [
+      ['an admin in multi-user mode', ADMIN],
+      ['single-user mode', null],
+    ] as const) {
+      it(`regenerates for ${label}`, async () => {
+        const { app } = await as(user);
+        const res = await app.inject({ method: 'POST', url: '/api/tunnel/qr/regenerate' });
+        expect(res.statusCode).toBe(200);
+        expect(tunnel.regenerateQrToken).toHaveBeenCalledTimes(1);
+      });
+    }
+  });
+
+  describe('POST /api/cleanup-state', () => {
+    it("refuses a non-admin, and no user's session records are touched", async () => {
+      const { app, ctx } = await as(NON_ADMIN);
+      forbidden(await app.inject({ method: 'POST', url: '/api/cleanup-state' }));
+      expect(ctx.tabLayouts.runStaleSessionCleanup).not.toHaveBeenCalled();
+      expect(ctx.store.cleanupSessionsByIds).not.toHaveBeenCalled();
+    });
+
+    it('runs for an admin', async () => {
+      const { app, ctx } = await as(ADMIN);
+      const res = await app.inject({ method: 'POST', url: '/api/cleanup-state' });
+      expect(res.statusCode).toBe(200);
+      expect(ctx.tabLayouts.runStaleSessionCleanup).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('POST /api/auth/revoke', () => {
+    const tokens = () => [...sessions.keys()].sort();
+
+    it('the bare form signs a non-admin out of their own sessions only, never anyone else', async () => {
+      const { app } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'POST', url: '/api/auth/revoke', payload: {} });
+      expect(res.statusCode).toBe(200);
+      expect(tokens()).toEqual(['root-desk']);
+    });
+
+    it("a non-admin's named token is revoked only when it is theirs", async () => {
+      const { app } = await as(NON_ADMIN);
+      await app.inject({ method: 'POST', url: '/api/auth/revoke', payload: { sessionToken: 'root-desk' } });
+      expect(tokens()).toEqual(['bob-laptop', 'bob-phone', 'root-desk']);
+      await app.inject({ method: 'POST', url: '/api/auth/revoke', payload: { sessionToken: 'bob-phone' } });
+      expect(tokens()).toEqual(['bob-laptop', 'root-desk']);
+    });
+
+    for (const [label, user] of [
+      ['an admin in multi-user mode', ADMIN],
+      ['single-user mode', null],
+    ] as const) {
+      it(`the bare form still clears every session for ${label}, a named token any session`, async () => {
+        const { app } = await as(user);
+        await app.inject({ method: 'POST', url: '/api/auth/revoke', payload: { sessionToken: 'bob-phone' } });
+        expect(tokens()).toEqual(['bob-laptop', 'root-desk']);
+        const res = await app.inject({ method: 'POST', url: '/api/auth/revoke', payload: {} });
+        expect(res.statusCode).toBe(200);
+        expect(tokens()).toEqual([]);
+      });
+    }
+  });
+
+  describe('GET /api/tunnel/info', () => {
+    const ips = (res: { body: string }) =>
+      (JSON.parse(res.body).authSessions as { ip: string }[]).map((s) => s.ip).sort();
+
+    it("lists only the non-admin's own logins", async () => {
+      const { app } = await as(NON_ADMIN);
+      const res = await app.inject({ method: 'GET', url: '/api/tunnel/info' });
+      expect(res.statusCode).toBe(200);
+      expect(ips(res)).toEqual(['10.0.0.2', '10.0.0.3']);
+    });
+
+    it('lists every login for an admin', async () => {
+      const { app } = await as(ADMIN);
+      const res = await app.inject({ method: 'GET', url: '/api/tunnel/info' });
+      expect(ips(res)).toEqual(['10.0.0.1', '10.0.0.2', '10.0.0.3']);
+    });
+  });
+});

test/routes/worktree-routes.test.ts

@@ -0,0 +1,440 @@
+/**
+ * @fileoverview The worktree routes (`/api/cases/:name/worktrees`) and quick-start's `worktree`
+ * field, against a REAL temp git repository in the per-file temp HOME's case space
+ * (`test/setup.ts`). Covers the happy path end to end (create, list with live sessions, start a
+ * session in it, remove, branch delete) and every refusal: Docker and remote cases (git never
+ * spawned for Docker), a folder that is not a repository, bad names, a symlinked `.claude`, a
+ * dirty tree, a live session inside, and multi-user ownership. Port: N/A (app.inject()).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { createMockRouteContext, safeRmHomeTree, type MockRouteContext } from '../mocks/index.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { ApiErrorCode, httpStatusForErrorCode } from '../../src/types.js';
+import { registerWorktreeRoutes } from '../../src/web/routes/worktree-routes.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+import { CASES_DIR } from '../../src/web/route-helpers.js';
+import { getDataDir } from '../../src/config/instance.js';
+import { userCasesDir } from '../../src/config/multiuser.js';
+import { Session } from '../../src/session.js';
+import { applyAgentSkill } from '../../src/hooks-config.js';
+import type { WorktreeGitRunner } from '../../src/git-worktrees.js';
+
+const ENV = {
+  ...process.env,
+  LC_ALL: 'C',
+  GIT_AUTHOR_NAME: 'T',
+  GIT_AUTHOR_EMAIL: 't@example.com',
+  GIT_COMMITTER_NAME: 'T',
+  GIT_COMMITTER_EMAIL: 't@example.com',
+  GIT_CONFIG_GLOBAL: '/dev/null',
+  GIT_CONFIG_NOSYSTEM: '1',
+};
+const git = (cwd: string, ...args: string[]) =>
+  execFileSync('git', args, { cwd, env: ENV, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+/** A git repository with one commit at `dir`. */
+function makeRepo(dir: string): string {
+  mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main');
+  writeFileSync(join(dir, 'README.md'), '# repo\n');
+  git(dir, 'add', 'README.md');
+  git(dir, 'commit', '-q', '-m', 'init');
+  return realpathSync(dir);
+}
+
+interface Harness {
+  app: FastifyInstance;
+  ctx: MockRouteContext;
+}
+
+/**
+ * The worktree routes plus the session routes (quick-start, POST /api/sessions), with the
+ * production envelope hook mirrored from server.ts: quick-start returns a bare object and relies
+ * on it for both the `{ success, data }` wrapper and the error-code status, as in
+ * case-clone-routes.test.ts.
+ */
+async function harness(
+  opts: { authUser?: { username: string; role: 'admin' | 'user' }; git?: WorktreeGitRunner } = {}
+): Promise<Harness> {
+  const app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+  if (opts.authUser) {
+    const authUser = opts.authUser;
+    app.addHook('onRequest', async (req) => {
+      (req as unknown as { authUser: typeof authUser }).authUser = authUser;
+    });
+  }
+  app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
+    if (!req.url.startsWith('/api')) return done(null, payload);
+    if (payload === null || typeof payload !== 'object') return done(null, payload);
+    const p = payload as { success?: unknown; errorCode?: unknown };
+    if (p.success === false) {
+      if (reply.statusCode === 200 && typeof p.errorCode === 'string') {
+        reply.code(httpStatusForErrorCode(p.errorCode as ApiErrorCode));
+      }
+      return done(null, payload);
+    }
+    if (p.success === true) return done(null, payload);
+    return done(null, { success: true, data: payload });
+  });
+  const ctx = createMockRouteContext();
+  registerWorktreeRoutes(app, ctx as never, { git: opts.git });
+  registerSessionRoutes(app, ctx as never);
+  installRouteErrorHandler(app);
+  await app.ready();
+  return { app, ctx };
+}
+
+let h: Harness;
+let repo: string;
+
+beforeEach(async () => {
+  vi.spyOn(Session.prototype, 'startInteractive').mockResolvedValue(undefined);
+  vi.spyOn(Session.prototype, 'startShell').mockResolvedValue(undefined);
+  repo = makeRepo(join(CASES_DIR, 'wtcase'));
+  h = await harness();
+});
+
+afterEach(async () => {
+  await h.app.close();
+  vi.restoreAllMocks();
+  delete process.env.CODEMAN_MULTIUSER;
+  await rm(join(getDataDir(), 'docker-hosts.json'), { force: true });
+  await rm(join(getDataDir(), 'docker-cases.json'), { force: true });
+  await rm(join(getDataDir(), 'remote-hosts.json'), { force: true });
+  await rm(join(getDataDir(), 'remote-cases.json'), { force: true });
+  await rm(join(getDataDir(), 'linked-cases.json'), { force: true });
+  safeRmHomeTree(CASES_DIR);
+  safeRmHomeTree(join(process.env.HOME ?? '/nonexistent', 'codeman-users'));
+});
+
+const list = (name = 'wtcase') => h.app.inject({ method: 'GET', url: `/api/cases/${name}/worktrees` });
+const create = (payload: Record<string, unknown>, name = 'wtcase') =>
+  h.app.inject({ method: 'POST', url: `/api/cases/${name}/worktrees`, payload });
+const remove = (wt: string, query = '', name = 'wtcase') =>
+  h.app.inject({ method: 'DELETE', url: `/api/cases/${name}/worktrees/${wt}${query}` });
+
+describe('worktree routes: happy path', () => {
+  it('creates, lists, starts a session in, and removes a worktree', async () => {
+    const before = await list();
+    expect(before.statusCode).toBe(200);
+    expect(before.json().data).toMatchObject({ caseName: 'wtcase', repoRoot: repo, truncated: false });
+    expect(before.json().data.worktrees).toHaveLength(1);
+
+    const res = await create({ name: 'fix-login' });
+    expect(res.statusCode).toBe(201);
+    const wtPath = join(repo, '.claude', 'worktrees', 'fix-login');
+    expect(res.json().data.worktree).toMatchObject({ name: 'fix-login', path: wtPath, branch: 'worktree-fix-login' });
+    expect(git(repo, 'status', '--porcelain')).toBe('');
+
+    // Start a session in it through the EXISTING quick-start path.
+    const qs = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'wtcase', mode: 'claude', worktree: 'fix-login', sessionName: 'w1-fix-login' },
+    });
+    expect(qs.statusCode).toBe(200);
+    const qsData = qs.json().data;
+    expect(qsData).toMatchObject({ casePath: repo, worktree: 'fix-login', workingDir: wtPath });
+    const session = h.ctx.sessions.get(qsData.sessionId) as unknown as { workingDir: string };
+    expect(session.workingDir).toBe(wtPath);
+    // The session's hooks land in the worktree it runs in, not the case folder.
+    expect(readFileSync(join(wtPath, '.claude', 'settings.local.json'), 'utf-8')).toContain('/api/hook-event');
+    // ...and that file does not make the worktree dirty (it is excluded).
+    expect(git(wtPath, 'status', '--porcelain')).toBe('');
+
+    const listed = (await list()).json().data.worktrees;
+    const row = listed.find((w: { name?: string }) => w.name === 'fix-login');
+    expect(row).toMatchObject({ managed: true, branch: 'worktree-fix-login', sessionCount: 1 });
+    expect(row.sessions).toEqual([{ id: qsData.sessionId, name: 'w1-fix-login' }]);
+    // The main checkout does not count a session that runs in a worktree below it.
+    expect(listed[0]).toMatchObject({ main: true, isCase: true, managed: false });
+
+    // Refused while that session lives.
+    const busy = await remove('fix-login');
+    expect(busy.statusCode).toBe(409);
+    expect(busy.json().error).toContain('live session');
+
+    h.ctx.sessions.delete(qsData.sessionId);
+    const gone = await remove('fix-login', '?deleteBranch=true');
+    expect(gone.statusCode).toBe(200);
+    expect(gone.json().data.removed).toMatchObject({
+      name: 'fix-login',
+      branch: 'worktree-fix-login',
+      branchDeleted: true,
+    });
+    expect(existsSync(wtPath)).toBe(false);
+    expect(git(repo, 'branch', '--list', 'worktree-fix-login')).toBe('');
+  });
+
+  it('surfaces git’s refusal for a dirty tree and keeps the files', async () => {
+    await create({ name: 'dirty', branch: 'feat/dirty' });
+    const wtPath = join(repo, '.claude', 'worktrees', 'dirty');
+    writeFileSync(join(wtPath, 'wip.txt'), 'work');
+    const res = await remove('dirty');
+    expect(res.statusCode).toBe(409);
+    expect(res.json().error).toContain('contains modified or untracked files');
+    expect(readFileSync(join(wtPath, 'wip.txt'), 'utf-8')).toBe('work');
+  });
+
+  it('removes a worktree its sessions got the agent skill in (agentSkillEnabled on)', async () => {
+    // The agent skill is injected into the folder a session runs in, so a worktree session gets
+    // an untracked `<skills dir>/codeman/`, which used to make `git worktree remove` refuse forever.
+    (h.ctx.getAgentSkillEnabled as unknown as { mockResolvedValue(v: boolean): void }).mockResolvedValue(true);
+    expect((await create({ name: 'skilled' })).statusCode).toBe(201);
+    const wtPath = join(repo, '.claude', 'worktrees', 'skilled');
+    const qs = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'wtcase', mode: 'claude', worktree: 'skilled' },
+    });
+    expect(qs.statusCode).toBe(200);
+    h.ctx.sessions.delete(qs.json().data.sessionId);
+    expect(existsSync(join(wtPath, '.claude', 'skills', 'codeman', 'SKILL.md'))).toBe(true);
+    // The other skills directory (codex, gemini and the rest scan `.agents/skills`), written by
+    // the same function quick-start calls; those CLIs are not installed here.
+    await applyAgentSkill(wtPath, true, '.agents/skills');
+    expect(existsSync(join(wtPath, '.agents', 'skills', 'codeman', 'SKILL.md'))).toBe(true);
+    expect(git(wtPath, 'status', '--porcelain')).toBe('');
+    expect(git(repo, 'status', '--porcelain')).toBe('');
+    const res = await remove('skilled');
+    expect(res.statusCode).toBe(200);
+    expect(existsSync(wtPath)).toBe(false);
+  });
+
+  it('removes a worktree whose folder was deleted by hand and frees its name', async () => {
+    await create({ name: 'gone' });
+    const wtPath = join(repo, '.claude', 'worktrees', 'gone');
+    await rm(wtPath, { recursive: true, force: true });
+    const row = (await list()).json().data.worktrees.find((w: { name?: string }) => w.name === 'gone');
+    expect(row).toMatchObject({ managed: true, prunable: true });
+    // A session cannot start in it.
+    const qs = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'wtcase', mode: 'shell', worktree: 'gone' },
+    });
+    expect(qs.statusCode).toBe(404);
+    const res = await remove('gone', '?deleteBranch=true');
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.removed).toMatchObject({ name: 'gone', branchDeleted: true });
+    expect(git(repo, 'worktree', 'list')).not.toContain('gone');
+    expect((await create({ name: 'gone' })).statusCode).toBe(201);
+  });
+
+  it('lets a POST /api/sessions create path use the worktree as workingDir', async () => {
+    await create({ name: 'viasessions' });
+    const wtPath = join(repo, '.claude', 'worktrees', 'viasessions');
+    const res = await h.app.inject({
+      method: 'POST',
+      url: '/api/sessions',
+      payload: { workingDir: wtPath, mode: 'shell', name: 's1-viasessions' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.session.workingDir).toBe(wtPath);
+  });
+});
+
+describe('worktree routes: refusals', () => {
+  it('rejects bad names before git (schema and the finer rules)', async () => {
+    for (const name of ['-x', 'a/b', '.hidden', 'x'.repeat(65), 'a..b', 'n.lock']) {
+      const res = await create({ name });
+      expect(res.statusCode, name).toBe(400);
+    }
+    expect((await remove('a..b')).statusCode).toBe(400);
+    expect((await create({ name: 'ok', branch: '-D' })).statusCode).toBe(400);
+    expect((await create({ name: 'ok', base: '--upload-pack=sh' })).statusCode).toBe(400);
+    expect(git(repo, 'worktree', 'list')).not.toContain('ok');
+  });
+
+  it('answers 404 for a missing case and 400 for a folder that is not a repository', async () => {
+    expect((await list('nosuchcase')).statusCode).toBe(404);
+    mkdirSync(join(CASES_DIR, 'plain'), { recursive: true });
+    const res = await list('plain');
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toContain('not a git repository');
+  });
+
+  it('refuses a Docker case with a 400 and never spawns git', async () => {
+    let spawned = 0;
+    const spy: WorktreeGitRunner = async () => {
+      spawned++;
+      return { code: 0, stdout: '', stderr: '', timedOut: false };
+    };
+    await h.app.close();
+    h = await harness({ git: spy });
+    await mkdir(getDataDir(), { recursive: true });
+    await writeFile(
+      join(getDataDir(), 'docker-hosts.json'),
+      JSON.stringify([{ id: 'd1', label: 'box', image: 'codeman/agent:base' }])
+    );
+    await writeFile(
+      join(getDataDir(), 'docker-cases.json'),
+      JSON.stringify([{ name: 'dockcase', type: 'docker', hostId: 'd1', hostWorkspacePath: repo }])
+    );
+    for (const res of [
+      await list('dockcase'),
+      await create({ name: 'x' }, 'dockcase'),
+      await remove('x', '', 'dockcase'),
+    ]) {
+      expect(res.statusCode).toBe(400);
+      expect(res.json().error).toContain('Docker');
+    }
+    // The local case whose folder IS that Docker workspace is refused too (git would run there).
+    const viaLocal = await list('wtcase');
+    expect(viaLocal.statusCode).toBe(400);
+    expect(viaLocal.json().error).toContain('Docker');
+    expect(spawned).toBe(0);
+
+    const qs = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'dockcase', mode: 'shell', worktree: 'x' },
+    });
+    expect(qs.statusCode).toBe(400);
+    expect(qs.json().error).toContain('Docker');
+  });
+
+  it('refuses to remove a worktree a Docker case uses as its workspace', async () => {
+    expect((await create({ name: 'boxed' })).statusCode).toBe(201);
+    const wtPath = join(repo, '.claude', 'worktrees', 'boxed');
+    await mkdir(getDataDir(), { recursive: true });
+    await writeFile(
+      join(getDataDir(), 'docker-cases.json'),
+      JSON.stringify([{ name: 'boxcase', type: 'docker', hostId: 'd1', hostWorkspacePath: wtPath }])
+    );
+    // The local case itself is fine (listing and creating still work)...
+    expect((await list()).statusCode).toBe(200);
+    // ...but removing the folder the container mounts is refused, and nothing is deleted.
+    const res = await remove('boxed');
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toContain('Docker case workspace');
+    expect(existsSync(join(wtPath, 'README.md'))).toBe(true);
+    expect(git(repo, 'worktree', 'list')).toContain('boxed');
+  });
+
+  it('refuses a remote case with a 400', async () => {
+    await mkdir(getDataDir(), { recursive: true });
+    await writeFile(
+      join(getDataDir(), 'remote-hosts.json'),
+      JSON.stringify([{ id: 'r1', label: 'far', host: 'far.example', username: 'u' }])
+    );
+    await writeFile(
+      join(getDataDir(), 'remote-cases.json'),
+      JSON.stringify([{ name: 'farcase', type: 'remote', hostId: 'r1', remotePath: '/srv/repo' }])
+    );
+    const res = await list('farcase');
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toContain('remote');
+    const qs = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'farcase', mode: 'shell', worktree: 'x' },
+    });
+    expect(qs.statusCode).toBe(400);
+    expect(qs.json().error).toContain('remote');
+  });
+
+  it('refuses to create through a symlinked .claude directory', async () => {
+    const outside = join(CASES_DIR, 'outside');
+    mkdirSync(join(outside, 'worktrees'), { recursive: true });
+    symlinkSync(outside, join(repo, '.claude'));
+    const res = await create({ name: 'evil' });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toContain('symlink');
+    expect(existsSync(join(outside, 'worktrees', 'evil'))).toBe(false);
+  });
+
+  it('quick-start refuses an unregistered worktree and never scaffolds a missing case', async () => {
+    mkdirSync(join(repo, '.claude', 'worktrees', 'stray'), { recursive: true });
+    const stray = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'wtcase', mode: 'shell', worktree: 'stray' },
+    });
+    expect(stray.statusCode).toBe(404);
+    const missing = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'brandnew', mode: 'shell', worktree: 'x' },
+    });
+    expect(missing.statusCode).toBe(404);
+    expect(existsSync(join(CASES_DIR, 'brandnew'))).toBe(false);
+    const badName = await h.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      payload: { caseName: 'wtcase', mode: 'shell', worktree: '../x' },
+    });
+    expect(badName.statusCode).toBe(400);
+  });
+});
+
+describe('worktree routes: a case reached through a symlink', () => {
+  // A linked case's folder can be a symlink (a repository on another disk, macOS's /tmp), and
+  // POST /api/sessions stores `workingDir` as it was spelled. The worktree list and the removal
+  // guard compare paths lexically, so a session spelled through the link has to be mapped onto
+  // the repository's real path first, or it is invisible to both.
+  it('counts and protects a session whose folder names the worktree through the case link', async () => {
+    const link = join(CASES_DIR, 'repo-link');
+    symlinkSync(repo, link);
+    await mkdir(getDataDir(), { recursive: true });
+    await writeFile(join(getDataDir(), 'linked-cases.json'), JSON.stringify({ linkedviasym: link }));
+    const made = await create({ name: 'sym' }, 'linkedviasym');
+    expect(made.statusCode).toBe(201);
+    const real = join(repo, '.claude', 'worktrees', 'sym');
+    expect(made.json().data.worktree.path).toBe(real);
+
+    // The same worktree, spelled through the link.
+    const spelled = join(link, '.claude', 'worktrees', 'sym');
+    const res = await h.app.inject({
+      method: 'POST',
+      url: '/api/sessions',
+      payload: { workingDir: spelled, mode: 'shell', name: 's1-sym' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.session.workingDir).toBe(spelled);
+
+    const busy = await remove('sym', '', 'linkedviasym');
+    expect(busy.statusCode).toBe(409);
+    expect(busy.json().error).toContain('live session');
+    expect(existsSync(real)).toBe(true);
+
+    const row = (await list('linkedviasym')).json().data.worktrees.find((w: { name?: string }) => w.name === 'sym');
+    expect(row).toMatchObject({ managed: true, sessionCount: 1 });
+    expect(row.sessions).toEqual([{ id: res.json().data.session.id, name: 's1-sym' }]);
+  });
+});
+
+describe('worktree routes: multi-user ownership', () => {
+  it('resolves a non-admin’s own case space only, never a linked case or another user’s case', async () => {
+    process.env.CODEMAN_MULTIUSER = '1';
+    // A linked case is admin-only: a non-admin's lookup falls through to their own space.
+    await mkdir(getDataDir(), { recursive: true });
+    await writeFile(join(getDataDir(), 'linked-cases.json'), JSON.stringify({ linkedrepo: repo }));
+    makeRepo(join(userCasesDir('alice'), 'alicecase'));
+
+    await h.app.close();
+    h = await harness({ authUser: { username: 'bob', role: 'user' } });
+    expect((await list('linkedrepo')).statusCode).toBe(404);
+    expect((await list('alicecase')).statusCode).toBe(404);
+    expect((await create({ name: 'x' }, 'alicecase')).statusCode).toBe(404);
+    expect(existsSync(join(userCasesDir('alice'), 'alicecase', '.claude'))).toBe(false);
+
+    await h.app.close();
+    h = await harness({ authUser: { username: 'alice', role: 'user' } });
+    expect((await list('alicecase')).statusCode).toBe(200);
+    expect((await create({ name: 'mine' }, 'alicecase')).statusCode).toBe(201);
+
+    await h.app.close();
+    h = await harness({ authUser: { username: 'root', role: 'admin' } });
+    const linked = await list('linkedrepo');
+    expect(linked.statusCode).toBe(200);
+    expect(linked.json().data.repoRoot).toBe(repo);
+  });
+});

test/session-trust-dialog.test.ts

@@ -16,6 +16,17 @@
  */
 import { describe, expect, it, vi, afterEach } from 'vitest';
 import { Session } from '../src/session.js';
+
+// The restart case below starts a real direct-PTY session; the real `claude` must never
+// run from a test, so pty.spawn runs a harmless stand-in instead.
+vi.mock('node-pty', async (importOriginal) => {
+  const real = await importOriginal<typeof import('node-pty')>();
+  return {
+    ...real,
+    spawn: (_file: string, _args: string[] | string, options: import('node-pty').IPtyForkOptions) =>
+      real.spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], options),
+  };
+});
 import {
   isTrustDialogScreen,
   compactScreenText,
@@ -239,6 +250,48 @@ describe('Session trust-dialog auto-accept', () => {
     expect(writes).toEqual([]);
   });
 
+  it('reads the dialog that painted inside the throttle of the read before it', () => {
+    vi.useFakeTimers();
+    // Measured on 2.1.294: one read at +156 ms saw a blank pane, the dialog painted
+    // within the throttle, and a quiet dialog sends no further output to read on.
+    let screen = '';
+    const { writes, tick } = sessionShowing(() => screen);
+    tick();
+    vi.advanceTimersByTime(500);
+    screen = RENDERED_DIALOG_2_1_252;
+    tick(); // the dialog's own paint: throttled, and the last output the pane produces
+    vi.advanceTimersByTime(5000);
+    expect(writes[0]).toBe(TRUST_KEY_DOWN);
+  });
+
+  it('cancels a deferred read when the session is stopped', async () => {
+    vi.useFakeTimers();
+    // DELETE goes through stop(), and a read deferred just before it must not outlive it.
+    let screen = '';
+    const { session, tick } = sessionShowing(() => screen);
+    tick();
+    screen = RENDERED_DIALOG_2_1_252;
+    const before = vi.getTimerCount();
+    tick(); // throttled, so a read is deferred
+    expect(vi.getTimerCount()).toBe(before + 1);
+    await session.stop(false);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('neither scans nor arms a timer once the session is stopped', async () => {
+    vi.useFakeTimers();
+    // Killing the pane produces output of its own, and the buffer tail still shows the
+    // dialog, so a deleted session went on "answering" it on a timer for several seconds.
+    const { session, tick } = sessionShowing(() => RENDERED_DIALOG_2_1_252);
+    await session.stop(false);
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    tick();
+    tick(); // inside the throttle of the first
+    expect(vi.getTimerCount()).toBe(0);
+    expect(log.mock.calls.some(([line]) => String(line).includes('trust dialog'))).toBe(false);
+    log.mockRestore();
+  });
+
   it('does not press Enter on a normal screen', () => {
     vi.useFakeTimers();
     const { writes, tick } = sessionShowing(() => RENDERED_MAIN_UI);
@@ -249,3 +302,104 @@ describe('Session trust-dialog auto-accept', () => {
     expect(writes).toEqual([]);
   });
 });
+
+describe('Session idle detection while the trust dialog is up', () => {
+  afterEach(() => vi.useRealTimers());
+
+  /** A just-launched pane (busy, inside the startup window) rendering `screen` (null: capture failed). */
+  function launchingSession(screen: () => string | null) {
+    const mux = { isAvailable: () => true, capturePaneText: () => screen() };
+    const session = new Session({
+      workingDir: '/tmp',
+      mode: 'claude',
+      mux,
+      muxSession: { muxName: 'codeman-test', sessionId: 'test', createdAt: Date.now() },
+    } as unknown as ConstructorParameters<typeof Session>[0]);
+    const internals = session as unknown as {
+      _detectInteractiveActivity(data: string): void;
+      _markActivity(): void;
+      _interactiveStartedAt: number;
+      _status: string;
+    };
+    internals._interactiveStartedAt = Date.now();
+    internals._status = 'busy'; // what startInteractive() leaves a new pane at
+    let idles = 0;
+    session.on('idle', () => idles++);
+    /** One repaint carrying a `❯`, which is what arms the idle confirmation. */
+    const paint = (chunk: string) => {
+      internals._markActivity();
+      internals._detectInteractiveActivity(chunk);
+    };
+    return { session, paint, idles: () => idles };
+  }
+
+  it('does not call the dialog idle, although its own ❯ arms the check', () => {
+    vi.useFakeTimers();
+    const { session, paint, idles } = launchingSession(() => RENDERED_DIALOG_2_1_252);
+    paint(RENDERED_DIALOG_2_1_252);
+    vi.advanceTimersByTime(30_000);
+    expect(session.status).toBe('busy');
+    expect(idles()).toBe(0);
+  });
+
+  it('goes idle once the dialog has been answered and the composer is up', () => {
+    vi.useFakeTimers();
+    let screen = RENDERED_DIALOG_2_1_252;
+    const { session, paint, idles } = launchingSession(() => screen);
+    paint(RENDERED_DIALOG_2_1_252);
+    vi.advanceTimersByTime(10_000);
+    expect(session.status).toBe('busy');
+
+    // No new output needed: the check keeps re-reading the screen on its own.
+    screen = RENDERED_MAIN_UI.replace('✻ Actualizing… (13m 23s · ↓ 47.5k tokens)', '');
+    vi.advanceTimersByTime(10_000);
+    expect(session.status).toBe('idle');
+    expect(idles()).toBe(1);
+  });
+
+  it('keeps holding when a capture fails after the dialog was seen', () => {
+    vi.useFakeTimers();
+    // A failed capture says nothing about whether the dialog went away.
+    let screen: string | null = RENDERED_DIALOG_2_1_252;
+    const { session, paint, idles } = launchingSession(() => screen);
+    paint(RENDERED_DIALOG_2_1_252);
+    vi.advanceTimersByTime(5000);
+    screen = null;
+    vi.advanceTimersByTime(20_000);
+    expect(session.status).toBe('busy');
+    expect(idles()).toBe(0);
+  });
+
+  it("does not carry the last pane's dialog verdict into a restarted pane", async () => {
+    // The session saw the dialog on its last pane, then restarted where no capture can
+    // replace that verdict (here the direct-PTY fallback, which has no pane to read; a
+    // failed capture keeps it the same way). The new pane must still be able to go idle.
+    const session = new Session({ workingDir: '/tmp', mode: 'claude', useMux: false });
+    (session as unknown as { _lastPaneProbeTrustDialog: boolean })._lastPaneProbeTrustDialog = true;
+    try {
+      await session.startInteractive();
+      vi.useFakeTimers();
+      const internals = session as unknown as {
+        _detectInteractiveActivity(data: string): void;
+        _markActivity(): void;
+      };
+      internals._markActivity();
+      internals._detectInteractiveActivity('❯ ');
+      vi.advanceTimersByTime(30_000);
+      expect(session.status).toBe('idle');
+    } finally {
+      vi.useRealTimers();
+      await session.stop();
+    }
+  });
+
+  it('lets a dialog-looking screen go idle outside the startup window', () => {
+    vi.useFakeTimers();
+    // A live agent can print the dialog's words hours in, and must not be held busy.
+    const { session, paint } = launchingSession(() => RENDERED_DIALOG_2_1_252);
+    vi.advanceTimersByTime(10 * 60_000);
+    paint(RENDERED_DIALOG_2_1_252);
+    vi.advanceTimersByTime(30_000);
+    expect(session.status).toBe('idle');
+  });
+});

test/session-worktree-label.test.ts

@@ -45,6 +45,24 @@ describe('worktree fields through the unified merge (#266)', () => {
     expect(merged[0].gitBranch).toBeUndefined();
   });
 
+  it('names the worktree of a LIVE session from its folder layout (no transcript record yet)', () => {
+    const merged = mergeUnifiedSessions({
+      live: [{ id: 'live1', name: 'w1-fix-login', mode: 'codex', workingDir: '/repo/.claude/worktrees/fix-login' }],
+    });
+    expect(merged[0]).toMatchObject({ worktreeName: 'fix-login', worktreeRepo: '/repo' });
+  });
+
+  it('lets a transcript record win over the layout, and ignores a subfolder of a worktree', () => {
+    const fromTranscript = mergeUnifiedSessions({
+      history: [historyRow({ worktreeName: 'named-by-claude', worktreeRepo: '/elsewhere' })],
+    });
+    expect(fromTranscript[0]).toMatchObject({ worktreeName: 'named-by-claude', worktreeRepo: '/elsewhere' });
+    const sub = mergeUnifiedSessions({
+      live: [{ id: 'live2', name: 'x', workingDir: '/repo/.claude/worktrees/fix-login/src' }],
+    });
+    expect(sub[0].worktreeName).toBeUndefined();
+  });
+
   it('finds a session by worktree name and by branch', () => {
     const items = [
       { sessionId: 'a', worktreeName: 'autodev', sources: ['history'] },

test/settings-admin-only-multiuser.test.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Multi-user mode, end to end: a non-admin cannot change the server-wide
+ * settings.json (live server, ephemeral port, real multi-user auth, real file on disk).
+ *
+ * The route tests (test/routes/system-routes-settings-admin-only.test.ts) pin each
+ * gate with a mocked filesystem. This one runs the real auth middleware and reads the
+ * real file back, so "settings.json is unchanged" is asserted on bytes:
+ *  - PUT /api/settings, PUT /api/execution/model-config and PUT /api/cases/order are
+ *    403 FORBIDDEN for a non-admin, and the file is byte-identical afterwards;
+ *  - GET /api/settings stays readable by the non-admin, without the admin's Deepgram
+ *    key and case names (an admin still reads the file as it is);
+ *  - a non-admin's quick-start does not record its case as `lastUsedCase` (a key every
+ *    user can read through GET /api/settings), while an admin's still does;
+ *  - an admin's PUT /api/settings still writes;
+ *  - a non-admin's bare POST /api/auth/revoke signs out only their own logins: an admin's
+ *    cookie still works afterwards (it used to clear every login on the server).
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { WebServer } from '../src/web/server.js';
+import { TmuxManager } from '../src/tmux-manager.js';
+import { createUser, invalidateUsersCache } from '../src/user-store.js';
+import { SETTINGS_PATH } from '../src/web/route-helpers.js';
+
+vi.spyOn(TmuxManager, 'isTmuxAvailable').mockReturnValue(true);
+
+const basic = (u: string, p: string) => 'Basic ' + Buffer.from(`${u}:${p}`).toString('base64');
+const bob = { Authorization: basic('bob', 'bobpass1234') };
+const root = { Authorization: basic('root', 'rootpass123') };
+
+let server: WebServer;
+const saved: Record<string, string | undefined> = {};
+const url = (p: string) => `http://localhost:${server.boundPort}${p}`;
+
+const INITIAL = {
+  autoNameSessions: false,
+  cliManagementEnabled: false,
+  lastUsedCase: 'rootcase',
+  caseOrder: ['rootcase'],
+  modelConfig: { defaultModel: 'sonnet' },
+  voiceSettings: { provider: 'deepgram', apiKey: 'dg-SECRET-live-456', language: 'en' },
+};
+const readSettingsBytes = () => fs.readFile(SETTINGS_PATH, 'utf-8');
+
+async function send(method: string, path: string, headers: Record<string, string>, body?: unknown) {
+  const res = await fetch(url(path), {
+    method,
+    headers: { ...headers, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: res.status, body: (await res.json()) as Record<string, any> };
+}
+
+/** The quick-start write of lastUsedCase is fire-and-forget: poll for it briefly. */
+async function settleSettings(predicate: (s: Record<string, unknown>) => boolean): Promise<Record<string, unknown>> {
+  let last: Record<string, unknown> = {};
+  for (let i = 0; i < 40; i++) {
+    last = JSON.parse(await readSettingsBytes());
+    if (predicate(last)) return last;
+    await new Promise((r) => setTimeout(r, 25));
+  }
+  return last;
+}
+
+beforeAll(async () => {
+  for (const k of ['CODEMAN_MULTIUSER', 'CODEMAN_PASSWORD', 'CODEMAN_USERNAME']) saved[k] = process.env[k];
+  process.env.CODEMAN_MULTIUSER = '1';
+  delete process.env.CODEMAN_PASSWORD;
+  delete process.env.CODEMAN_USERNAME;
+  invalidateUsersCache();
+  await createUser({ username: 'root', role: 'admin', password: 'rootpass123' });
+  await createUser({ username: 'bob', role: 'user', password: 'bobpass1234' });
+
+  await fs.mkdir(dirname(SETTINGS_PATH), { recursive: true });
+  await fs.writeFile(SETTINGS_PATH, JSON.stringify(INITIAL, null, 2));
+
+  server = new WebServer(0, false, true);
+  await server.start();
+});
+
+afterAll(async () => {
+  await server?.stop();
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  invalidateUsersCache();
+});
+
+describe('a non-admin and the server-wide settings.json', () => {
+  it('cannot write it through any settings route, and the file stays byte-identical', async () => {
+    const before = await readSettingsBytes();
+    for (const [path, body] of [
+      ['/api/settings', { autoNameSessions: true, cliManagementEnabled: true, runMode: 'shell' }],
+      ['/api/execution/model-config', { defaultModel: 'opus' }],
+      ['/api/cases/order', { order: ['bobcase'] }],
+    ] as const) {
+      const res = await send('PUT', path, bob, body);
+      expect(res.status, path).toBe(403);
+      expect(res.body.success, path).toBe(false);
+      expect(res.body.errorCode, path).toBe('FORBIDDEN');
+    }
+    expect(await readSettingsBytes()).toBe(before);
+  });
+
+  it("can still read it, without the admin's Deepgram key and case names", async () => {
+    const res = await send('GET', '/api/settings', bob);
+    expect(res.status).toBe(200);
+    expect(res.body.data.autoNameSessions).toBe(false);
+    expect(JSON.stringify(res.body)).not.toContain('dg-SECRET-live-456');
+    expect(res.body.data.voiceSettings).toEqual({ provider: 'deepgram', language: 'en' });
+    expect('caseOrder' in res.body.data).toBe(false);
+    expect('lastUsedCase' in res.body.data).toBe(false);
+
+    const admin = await send('GET', '/api/settings', root);
+    expect(admin.body.data.voiceSettings.apiKey).toBe('dg-SECRET-live-456');
+    expect(admin.body.data.caseOrder).toEqual(['rootcase']);
+  });
+
+  it("does not get its quick-start case recorded as everyone's lastUsedCase; an admin's still is", async () => {
+    const mine = await send('POST', '/api/quick-start', bob, { caseName: 'bobproj' });
+    expect(mine.status).toBe(200);
+    expect(mine.body.success).toBe(true);
+    // Give a (wrong) fire-and-forget write every chance to land before checking.
+    await new Promise((r) => setTimeout(r, 200));
+    expect(JSON.parse(await readSettingsBytes()).lastUsedCase).toBe('rootcase');
+
+    const theirs = await send('POST', '/api/quick-start', root, { caseName: 'rootproj2' });
+    expect(theirs.status).toBe(200);
+    expect((await settleSettings((s) => s.lastUsedCase === 'rootproj2')).lastUsedCase).toBe('rootproj2');
+  });
+
+  it('does not get its Ralph loop case recorded as lastUsedCase either; an admin still does', async () => {
+    const mine = await send('POST', '/api/ralph-loop/start', bob, { caseName: 'bobralph', taskDescription: 'x' });
+    expect(mine.status).toBe(200);
+    expect(mine.body.success).toBe(true);
+    await new Promise((r) => setTimeout(r, 200));
+    expect(JSON.parse(await readSettingsBytes()).lastUsedCase).toBe('rootproj2');
+
+    const theirs = await send('POST', '/api/ralph-loop/start', root, { caseName: 'rootralph', taskDescription: 'x' });
+    expect(theirs.status).toBe(200);
+    expect((await settleSettings((s) => s.lastUsedCase === 'rootralph')).lastUsedCase).toBe('rootralph');
+  });
+});
+
+describe("a non-admin's Revoke All", () => {
+  /** Sign in with Basic auth and keep only the session cookie it mints. */
+  async function cookieFor(headers: Record<string, string>) {
+    const res = await fetch(url('/api/status'), { headers });
+    expect(res.status).toBe(200);
+    const cookie = (res.headers.get('set-cookie') || '').split(';')[0];
+    expect(cookie).toMatch(/^codeman_session=/);
+    return { Cookie: cookie };
+  }
+
+  it("signs out only the non-admin's own logins, never an admin's", async () => {
+    const rootCookie = await cookieFor(root);
+    const bobCookie = await cookieFor(bob);
+    expect((await fetch(url('/api/status'), { headers: rootCookie })).status).toBe(200);
+
+    const res = await send('POST', '/api/auth/revoke', bobCookie, {});
+    expect(res.status).toBe(200);
+
+    expect((await fetch(url('/api/status'), { headers: rootCookie })).status).toBe(200);
+    expect((await fetch(url('/api/status'), { headers: bobCookie })).status).toBe(401);
+  });
+});
+
+describe('an admin and the server-wide settings.json', () => {
+  it('still writes it', async () => {
+    const res = await send('PUT', '/api/settings', root, { autoNameSessions: true });
+    expect(res.status).toBe(200);
+    expect(res.body.success).toBe(true);
+    expect(JSON.parse(await readSettingsBytes()).autoNameSessions).toBe(true);
+  });
+});

test/settings-admin-only-ui.test.ts

@@ -0,0 +1,550 @@
+/**
+ * @fileoverview Multi-user mode: a NON-ADMIN's browser and the admin-only settings writes.
+ *
+ * In multi-user mode PUT /api/settings (and PUT /api/execution/model-config,
+ * PUT /api/cases/order) answer 403 FORBIDDEN for a non-admin (system-routes.ts,
+ * case-routes.ts), because settings.json is one file for the whole server. The page
+ * must not break on that:
+ *  - App Settings Save/Apply keeps saving the per-device keys to localStorage exactly
+ *    as before, sends no settings PUT and no model-config PUT, keeps every SYNCED key
+ *    at the server's value, and shows ONE "only an admin" toast, only when the user
+ *    really changed a synced setting (an untouched synced key that no admin ever
+ *    stored must not read as a change: that is what the form baseline is for).
+ *  - The background writes (run mode, respawn presets, last used case, case order,
+ *    the respawn-preset migration on load, the tunnel toggles) are not sent, and the
+ *    non-admin's own run mode and respawn presets stay theirs on this device across a
+ *    reload (the server's would otherwise overwrite them on every load).
+ *  - A save sent before the role was known (/api/me slow or failed) that the server
+ *    refuses with 403 FORBIDDEN ends like a known non-admin's: synced keys back to the
+ *    server's value, the one admin toast (never "Settings saved"), read-only from then.
+ *  - The display-key split does not depend on GET /api/settings having loaded.
+ *  - Admins and single-user mode send everything as before.
+ *  - Both toasts read in Chinese under zh-CN.
+ *
+ * The real modules run inside a JSDOM window (runScripts: 'outside-only') with the
+ * real index.html, so the form is the real App Settings form. Port: none.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import vm from 'node:vm';
+import { JSDOM } from 'jsdom';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { SettingsUpdateSchema } from '../src/web/schemas.js';
+
+const PUBLIC = join(process.cwd(), 'src/web/public');
+const read = (name: string) => readFileSync(join(PUBLIC, name), 'utf8');
+const INDEX = read('index.html');
+const I18N = read('i18n.js');
+const SETTINGS_UI = read('settings-ui.js');
+const SESSION_UI = read('session-ui.js');
+const RESPAWN_UI = read('respawn-ui.js');
+const SCRIPTS = [read('constants.js'), read('app.js'), SETTINGS_UI];
+
+const DESKTOP_KEY = 'codeman-app-settings';
+const SAVE_TOAST = 'Saved on this device. Server-wide settings can only be changed by an admin.';
+const ADMIN_TOAST = 'Server-wide settings can only be changed by an admin';
+
+type Settings = Record<string, unknown>;
+type Who = 'non-admin' | 'admin' | 'single-user' | 'unknown';
+/** `unknown`: GET /api/me has not answered yet, so admin-ui.js has set no identity. */
+const IDENTITY: Record<Who, Settings | undefined> = {
+  'non-admin': { username: 'bob', role: 'user', multiUser: true },
+  admin: { username: 'root', role: 'admin', multiUser: true },
+  'single-user': { username: 'admin', role: 'admin', multiUser: false },
+  unknown: undefined,
+};
+
+/** What PUT /api/settings answers a non-admin in multi-user mode (system-routes.ts). */
+const forbiddenResponse = () => {
+  const res = {
+    ok: false,
+    status: 403,
+    json: async () => ({ success: false, error: 'You do not have permission', errorCode: 'FORBIDDEN' }),
+    clone: () => res,
+  };
+  return res;
+};
+
+/**
+ * Methods that run for real. Every other method is a no-op: openAppSettings() and
+ * saveAppSettings() fan out into panels (voice, webhook, tunnel, push, header) this
+ * file is not about.
+ */
+const REAL = new Set([
+  'openAppSettings',
+  'saveAppSettings',
+  'applyAppSettings',
+  'loadAppSettingsFromServer',
+  'loadAppSettingsFromStorage',
+  'saveAppSettingsToStorage',
+  'getSettingsStorageKey',
+  'getDefaultSettings',
+  'tabCliLogosEnabled',
+  'resolveTabArrangement',
+  'resolveTabStateOrder',
+  'resolveHeaderStatsStyle',
+  'resolveSessionSidebarFontSize',
+  'planUsageChipEnabled',
+  'planUsageCollectionFlip',
+  'loadModelConfigForSettings',
+  'saveModelConfigFromSettings',
+  '_modelConfigFromSettingsForm',
+  '_settingsReadOnly',
+  '_captureSettingsFormBaseline',
+  '_keepServerSyncedSettings',
+  '_displaySettingKeySet',
+  '_noteSettingsWriteRefusal',
+  '_applyOwnSettings',
+  '_readOwnSettings',
+  '_ownSettingsKey',
+]);
+
+/** Methods the load/save paths call that other modules add to the prototype. */
+const ELSEWHERE = [
+  '_updateLocalEchoState',
+  'renderProjectInsightsPanel',
+  'updateSubagentWindowVisibility',
+  'showWelcome',
+  '_applyRunMode',
+];
+
+const windows: { close(): void }[] = [];
+afterEach(() => {
+  for (const win of windows.splice(0)) win.close();
+});
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+/**
+ * Boot index.html with constants.js, app.js and settings-ui.js, as `who`, with `stored` as
+ * this device's blob and `server` as GET /api/settings (merged in by the real loader, which
+ * is also what publishes the display-key list the non-admin save reads).
+ */
+async function boot(who: Who, stored: Settings, server: Settings | null) {
+  const dom = new JSDOM(INDEX, { url: 'http://localhost/', runScripts: 'outside-only' });
+  const win = dom.window as unknown as Window &
+    typeof globalThis & { eval(src: string): void; __App: any; __codemanUser: Settings; fetch: unknown };
+  windows.push(win);
+  if (win.document.readyState !== 'complete') await new Promise((resolve) => win.addEventListener('load', resolve));
+  win.setInterval = (() => 0) as unknown as typeof win.setInterval;
+  win.localStorage.setItem(DESKTOP_KEY, JSON.stringify(stored));
+  const fetchCalls: { url: string; method: string; body?: string }[] = [];
+  win.fetch = vi.fn(async (url: string, opts: { method?: string; body?: string } = {}) => {
+    fetchCalls.push({ url, method: opts.method || 'GET', body: opts.body });
+    const data = url === '/api/execution/model-config' ? { defaultModel: 'sonnet', showRecommendations: true } : {};
+    return { ok: true, status: 200, json: async () => ({ success: true, data }) };
+  });
+  win.eval(
+    [
+      `var MobileDetection = {
+         getDeviceType: () => 'desktop',
+         isHandheldDevice: () => false,
+         isMobile: () => false,
+         isTouchDevice: () => false,
+       };
+       var KeyboardHandler = {}, SwipeHandler = {}, DeepgramProvider = {}, NotificationManager = function () {};
+       var KeyboardAccessoryBar = { setMode() {} };
+       var VoiceInput = { _getDeepgramConfig: () => ({}), _saveDeepgramConfig() {}, refreshClaudeStatus: () => Promise.resolve() };
+       var FocusTrap = function () { this.activate = () => {}; this.deactivate = () => {}; };
+       var DEFAULT_VOICE_KEYTERMS = '';`,
+      ...SCRIPTS,
+      'window.__App = CodemanApp;',
+    ].join('\n')
+  );
+  win.__codemanUser = IDENTITY[who] as Settings;
+  const target = Object.create(win.__App.prototype);
+  target.sessions = new Map();
+  target.sessionOrder = [];
+  target._apiPut = vi.fn(async () => ({ ok: true }));
+  target.showToast = vi.fn();
+  target.closeAppSettings = vi.fn();
+  const noop = () => undefined;
+  for (const name of ELSEWHERE) target[name] = noop;
+  const app = new Proxy(target, {
+    get(t, key, receiver) {
+      const value = Reflect.get(t, key, receiver);
+      const stubbed =
+        typeof key === 'string' && typeof value === 'function' && !Object.hasOwn(t, key) && !REAL.has(key);
+      return stubbed ? noop : value;
+    },
+  }) as any;
+  await app.loadAppSettingsFromServer(Promise.resolve(server));
+  const doc = win.document;
+  const box = (id: string) => doc.getElementById(id) as HTMLInputElement;
+  const storedBlob = () => JSON.parse(win.localStorage.getItem(DESKTOP_KEY) || '{}') as Settings;
+  const toasts = () => (target.showToast.mock.calls as unknown[][]).map((c) => c[0]);
+  const puts = () => fetchCalls.filter((c) => c.method === 'PUT');
+  return { win, doc, app, target, box, storedBlob, toasts, puts };
+}
+
+// What the server already holds for this instance: an admin has saved App Settings before.
+const SERVER: Settings = { autoNameSessions: false, workspaceHooksEnabled: true, claudeMode: 'auto' };
+
+describe('a non-admin in multi-user mode saving App Settings', () => {
+  it('keeps the per-device keys, sends no PUT, keeps the synced key at the server value, and toasts once', async () => {
+    const { app, target, box, storedBlob, toasts, puts } = await boot('non-admin', { ...SERVER }, SERVER);
+    await open_(app);
+    box('appSettingsTabTwoRows').checked = true; // per-device (displayKeys)
+    box('appSettingsAutoNameSessions').checked = true; // synced, server-wide
+    await app.saveAppSettings();
+
+    expect(target._apiPut).not.toHaveBeenCalled();
+    expect(puts()).toEqual([]);
+    expect(storedBlob().tabTwoRows).toBe(true);
+    expect(storedBlob().autoNameSessions).toBe(false);
+    expect(toasts()).toEqual([SAVE_TOAST]);
+  });
+
+  it('says "Settings saved" (no admin toast) when only per-device keys changed', async () => {
+    const { app, target, box, storedBlob, toasts, puts } = await boot('non-admin', { ...SERVER }, SERVER);
+    await open_(app);
+    box('appSettingsTabTwoRows').checked = true;
+    await app.saveAppSettings();
+
+    expect(target._apiPut).not.toHaveBeenCalled();
+    expect(puts()).toEqual([]);
+    expect(storedBlob().tabTwoRows).toBe(true);
+    expect(toasts()).toEqual(['Settings saved']);
+  });
+
+  it('does not read untouched synced keys no admin ever stored as a change', async () => {
+    // A fresh instance: the server holds nothing, so the blob has no synced keys while the
+    // form shows their defaults. Comparing against the blob would toast on every save.
+    const { app, box, storedBlob, toasts, puts } = await boot('non-admin', {}, {});
+    await open_(app);
+    box('appSettingsTabTwoRows').checked = true;
+    await app.saveAppSettings();
+    expect(toasts()).toEqual(['Settings saved']);
+    expect(puts()).toEqual([]);
+    // The synced keys the form read stay absent (the server default), never the form's copy.
+    expect('autoNameSessions' in storedBlob()).toBe(false);
+    expect('claudeMode' in storedBlob()).toBe(false);
+    expect(storedBlob().tabTwoRows).toBe(true);
+
+    // And a real change there still gets the one admin toast.
+    await open_(app);
+    box('appSettingsAutoNameSessions').checked = true;
+    await app.saveAppSettings();
+    expect(toasts()).toEqual(['Settings saved', SAVE_TOAST]);
+    expect('autoNameSessions' in storedBlob()).toBe(false);
+  });
+
+  it('does not send the model config either, and folds a change to it into the same one toast', async () => {
+    const { app, doc, toasts, puts } = await boot('non-admin', { ...SERVER }, SERVER);
+    await open_(app);
+    (doc.getElementById('appSettingsDefaultModel') as HTMLSelectElement).value = 'opus';
+    await app.saveAppSettings();
+    expect(puts()).toEqual([]);
+    expect(toasts()).toEqual([SAVE_TOAST]);
+  });
+
+  it('Apply behaves the same: nothing sent, the modal stays open', async () => {
+    const { app, target, box, toasts, puts } = await boot('non-admin', { ...SERVER }, SERVER);
+    await open_(app);
+    box('appSettingsAutoNameSessions').checked = true;
+    await app.applyAppSettings();
+    expect(target._apiPut).not.toHaveBeenCalled();
+    expect(puts()).toEqual([]);
+    expect(target.closeAppSettings).not.toHaveBeenCalled();
+    expect(toasts()).toEqual([SAVE_TOAST]);
+  });
+});
+
+describe('a save sent before the role was known, refused as admin-only', () => {
+  it('ends like a known non-admin save: synced key kept at the server value, one admin toast', async () => {
+    const { app, target, box, storedBlob, toasts, puts } = await boot('unknown', { ...SERVER }, SERVER);
+    target._apiPut = vi.fn(async () => forbiddenResponse());
+    await open_(app);
+    box('appSettingsTabTwoRows').checked = true; // per-device
+    box('appSettingsAutoNameSessions').checked = true; // synced
+    await app.saveAppSettings();
+
+    // The one PUT that went out before anything knew better, and nothing after it: the model
+    // config is not sent, and "Settings saved" (the old answer to a 403) is never shown.
+    expect(target._apiPut).toHaveBeenCalledTimes(1);
+    expect(puts()).toEqual([]);
+    expect(toasts()).toEqual([SAVE_TOAST]);
+    expect(storedBlob().tabTwoRows).toBe(true);
+    expect(storedBlob().autoNameSessions).toBe(false);
+
+    // Read-only from here on: the next save sends nothing.
+    expect(app._settingsReadOnly()).toBe(true);
+    await open_(app);
+    box('appSettingsAutoNameSessions').checked = true;
+    await app.saveAppSettings();
+    expect(target._apiPut).toHaveBeenCalledTimes(1);
+    expect(toasts()).toEqual([SAVE_TOAST, SAVE_TOAST]);
+  });
+
+  it('the same for a page whose /api/me failed (admin-ui.js falls back to a single-user admin)', async () => {
+    const { app, target, box, storedBlob, toasts } = await boot('single-user', { ...SERVER }, SERVER);
+    target._apiPut = vi.fn(async () => forbiddenResponse());
+    await open_(app);
+    box('appSettingsAutoNameSessions').checked = true;
+    await app.saveAppSettings();
+    expect(toasts()).toEqual([SAVE_TOAST]);
+    expect(storedBlob().autoNameSessions).toBe(false);
+  });
+
+  it('is not confused with the tunnel no-password 403 (another errorCode): that still prompts', async () => {
+    const { app, target } = await boot('admin', { ...SERVER }, SERVER);
+    const res = {
+      ok: false,
+      status: 403,
+      json: async () => ({ success: false, error: 'no password', errorCode: 'OPERATION_FAILED' }),
+    };
+    expect(await app._noteSettingsWriteRefusal({ ...res, clone: () => res })).toBe(false);
+    expect(app._settingsReadOnly()).toBe(false);
+    expect(target._settingsWriteForbidden).toBeUndefined();
+  });
+});
+
+describe('a non-admin save when GET /api/settings failed at page load', () => {
+  it('still keeps the synced keys at the stored value and toasts once', async () => {
+    const { app, box, storedBlob, toasts, puts } = await boot('non-admin', { ...SERVER }, null);
+    await open_(app);
+    box('appSettingsTabTwoRows').checked = true;
+    box('appSettingsAutoNameSessions').checked = true;
+    await app.saveAppSettings();
+    expect(puts()).toEqual([]);
+    expect(storedBlob().tabTwoRows).toBe(true);
+    expect(storedBlob().autoNameSessions).toBe(false);
+    expect(toasts()).toEqual([SAVE_TOAST]);
+  });
+});
+
+describe('an admin, and single-user mode, saving App Settings', () => {
+  for (const who of ['admin', 'single-user'] as const) {
+    it(`${who}: sends the settings PUT and the model config as before`, async () => {
+      const { app, target, box, storedBlob, toasts, puts } = await boot(who, { ...SERVER }, SERVER);
+      await open_(app);
+      box('appSettingsAutoNameSessions').checked = true;
+      await app.saveAppSettings();
+
+      expect(target._apiPut).toHaveBeenCalledTimes(1);
+      const [path, body] = target._apiPut.mock.calls[0] as [string, Settings];
+      expect(path).toBe('/api/settings');
+      expect(body.autoNameSessions).toBe(true);
+      expect(SettingsUpdateSchema.safeParse(body).error?.issues ?? []).toEqual([]);
+      expect(puts().map((p) => p.url)).toEqual(['/api/execution/model-config']);
+      expect(storedBlob().autoNameSessions).toBe(true);
+      expect(toasts()).toEqual(['Settings saved']);
+    });
+  }
+});
+
+/** Open App Settings and let its async model-config read land, as a user would. */
+async function open_(app: { openAppSettings(): void }) {
+  app.openAppSettings();
+  await tick();
+  await tick();
+}
+
+// ─── Background writes (vm harness: settings-ui.js + session-ui.js + respawn-ui.js) ───
+
+function loadBackground(who: Who, storage = new Map<string, string>()) {
+  const elements: Record<string, any> = {
+    quickStartCase: { value: 'mine' },
+    welcomeTunnelBtn: { classList: { contains: () => false }, disabled: false },
+    runModeMenu: { classList: { remove: () => {} } },
+    runBtn: { className: '', nextElementSibling: { className: '' } },
+    runBtnLabel: { textContent: '' },
+  };
+  const CodemanApp = function CodemanApp(this: any) {};
+  const fetchMock = vi.fn(async () => ({ ok: true, status: 200, json: async () => ({ success: true, data: {} }) }));
+  const confirmMock = vi.fn(() => true);
+  const listeners: Record<string, (() => void)[]> = {};
+  const win: Record<string, unknown> = { __codemanUser: IDENTITY[who] };
+  const context = vm.createContext({
+    CodemanApp,
+    VoiceInput: {},
+    window: win,
+    localStorage: {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+    },
+    document: {
+      getElementById: (id: string) => elements[id] ?? null,
+      addEventListener: (type: string, fn: () => void) => (listeners[type] ||= []).push(fn),
+    },
+    fetch: fetchMock,
+    confirm: confirmMock,
+    console,
+  });
+  vm.runInContext(SETTINGS_UI, context, { filename: 'settings-ui.js' });
+  vm.runInContext(SESSION_UI, context, { filename: 'session-ui.js' });
+  vm.runInContext(RESPAWN_UI, context, { filename: 'respawn-ui.js' });
+  const app = new (CodemanApp as any)();
+  app.loadAppSettingsFromStorage = () => ({});
+  app.saveAppSettingsToStorage = () => {};
+  app._apiPut = vi.fn(() => Promise.resolve({ ok: true }));
+  app.showToast = vi.fn();
+  app.loadQuickStartCases = vi.fn(async () => {});
+  app.renderCaseManageList = vi.fn();
+  app.closeTunnelPanel = vi.fn();
+  app._showTunnelConnecting = vi.fn();
+  app._pollTunnelStatus = vi.fn();
+  app._dismissTunnelConnecting = vi.fn();
+  app._updateWelcomeTunnelBtn = vi.fn();
+  app._updateTunnelIndicator = vi.fn();
+  win.app = app;
+  /** What admin-ui.js does once GET /api/me answers. */
+  const resolveMe = (identity: Settings) => {
+    win.__codemanUser = identity;
+    for (const fn of listeners['codeman:me'] || []) fn();
+  };
+  return { app, fetchMock, confirmMock, storage, resolveMe };
+}
+
+const settingsPuts = (b: ReturnType<typeof loadBackground>) => [
+  ...b.app._apiPut.mock.calls.filter((c: unknown[]) => c[0] === '/api/settings'),
+  ...b.fetchMock.mock.calls.filter((c: unknown[]) => c[0] === '/api/settings' || c[0] === '/api/cases/order'),
+];
+
+describe('background writes', () => {
+  it('a non-admin sends none of them, and the device keeps its own copy', async () => {
+    const b = loadBackground('non-admin');
+    b.app.setRunMode('codex');
+    expect(b.storage.get('codeman_runMode')).toBe('codex');
+    b.app.saveRespawnPresets([{ id: 'p', name: 'mine' }]);
+    expect(JSON.parse(b.storage.get('codeman-respawn-presets')!)).toEqual([{ id: 'p', name: 'mine' }]);
+    await b.app.saveLastUsedCase('mine');
+    await b.app.toggleTunnelFromWelcome();
+    await b.app._tunnelPanelToggle(true);
+    expect(settingsPuts(b)).toEqual([]);
+    expect(b.app.showToast.mock.calls.map((c: unknown[]) => c[0])).toEqual([ADMIN_TOAST, ADMIN_TOAST]);
+  });
+
+  it('a non-admin case reorder is not sent: one toast, and the list goes back to the server order', async () => {
+    const b = loadBackground('non-admin');
+    await b.app.saveCaseOrder(['b', 'a']);
+    expect(settingsPuts(b)).toEqual([]);
+    expect(b.app.showToast.mock.calls.map((c: unknown[]) => c[0])).toEqual([ADMIN_TOAST]);
+    expect(b.app.loadQuickStartCases).toHaveBeenCalledWith('mine');
+    expect(b.app.renderCaseManageList).toHaveBeenCalled();
+  });
+
+  it('a non-admin never runs the respawn-preset migration PUT on page load', async () => {
+    const b = loadBackground('non-admin');
+    b.storage.set('codeman-respawn-presets', JSON.stringify([{ id: 'p' }]));
+    await b.app.loadAppSettingsFromServer(Promise.resolve({ autoNameSessions: false }));
+    expect(settingsPuts(b)).toEqual([]);
+  });
+
+  it('a 403 FORBIDDEN on a tunnel enable is the admin-only answer, not the no-password prompt', async () => {
+    const b = loadBackground('admin');
+    const refused = await b.app._handleTunnelEnableRefusal({
+      ok: false,
+      status: 403,
+      json: async () => ({ success: false, error: 'You do not have permission', errorCode: 'FORBIDDEN' }),
+    });
+    expect(refused).toBe(true);
+    expect(b.confirmMock).not.toHaveBeenCalled();
+    expect(b.fetchMock).not.toHaveBeenCalled();
+    expect(b.app.showToast.mock.calls.map((c: unknown[]) => c[0])).toEqual([ADMIN_TOAST]);
+  });
+
+  it("a non-admin's own run mode and respawn presets survive a reload over the server's", async () => {
+    const before = loadBackground('non-admin');
+    before.app.setRunMode('codex');
+    before.app.saveRespawnPresets([{ id: 'mine', name: 'mine' }]);
+    expect(settingsPuts(before)).toEqual([]);
+
+    // The next page load, on the same device: the server holds an admin's picks.
+    const after = loadBackground('non-admin', before.storage);
+    await after.app.loadAppSettingsFromServer(
+      Promise.resolve({ runMode: 'shell', respawnPresets: [{ id: 'admin', name: 'admin' }] })
+    );
+    expect(after.app.runMode).toBe('codex');
+    expect(after.storage.get('codeman_runMode')).toBe('codex');
+    // What loadRespawnPresets() reads before anything else (respawn-ui.js).
+    expect(after.app._serverRespawnPresets).toEqual([{ id: 'mine', name: 'mine' }]);
+    expect(JSON.parse(after.storage.get('codeman-respawn-presets')!)).toEqual([{ id: 'mine', name: 'mine' }]);
+    expect(settingsPuts(after)).toEqual([]);
+  });
+
+  it('they win too when the role resolves only after the settings load (codeman:me)', async () => {
+    const before = loadBackground('non-admin');
+    before.app.setRunMode('codex');
+    const after = loadBackground('unknown', before.storage);
+    await after.app.loadAppSettingsFromServer(Promise.resolve({ runMode: 'shell' }));
+    expect(after.app.runMode).toBe('shell');
+    after.resolveMe(IDENTITY['non-admin'] as Settings);
+    expect(after.app.runMode).toBe('codex');
+    expect(after.storage.get('codeman_runMode')).toBe('codex');
+  });
+
+  it("they are the user's own: another user, or an admin, on the same device gets the server's", async () => {
+    const before = loadBackground('non-admin');
+    before.app.setRunMode('codex');
+    const other = loadBackground('unknown', before.storage);
+    await other.app.loadAppSettingsFromServer(Promise.resolve({ runMode: 'shell' }));
+    other.resolveMe({ username: 'carol', role: 'user', multiUser: true });
+    expect(other.app.runMode).toBe('shell');
+    const admin = loadBackground('admin', before.storage);
+    await admin.app.loadAppSettingsFromServer(Promise.resolve({ runMode: 'shell' }));
+    expect(admin.app.runMode).toBe('shell');
+  });
+
+  it('a background PUT refused as admin-only (role not known yet) makes the page read-only', async () => {
+    const b = loadBackground('unknown');
+    b.app._apiPut = vi.fn(() => Promise.resolve(forbiddenResponse()));
+    b.app.setRunMode('codex');
+    await tick();
+    await tick();
+    expect(b.app._settingsReadOnly()).toBe(true);
+    b.app.saveRespawnPresets([{ id: 'p' }]);
+    expect(b.app._apiPut).toHaveBeenCalledTimes(1);
+  });
+
+  for (const who of ['admin', 'single-user'] as const) {
+    it(`${who}: every background write is still sent`, async () => {
+      const b = loadBackground(who);
+      b.app.setRunMode('codex');
+      b.app.saveRespawnPresets([{ id: 'p' }]);
+      await b.app.saveLastUsedCase('mine');
+      await b.app.saveCaseOrder(['b', 'a']);
+      expect(b.app._apiPut.mock.calls.map((c: unknown[]) => c[0])).toEqual(['/api/settings', '/api/settings']);
+      expect(b.fetchMock.mock.calls.map((c: unknown[]) => c[0])).toEqual(['/api/settings', '/api/cases/order']);
+      b.storage.set('codeman-respawn-presets', JSON.stringify([{ id: 'p' }]));
+      b.app._apiPut.mockClear();
+      await b.app.loadAppSettingsFromServer(Promise.resolve({}));
+      expect(b.app._apiPut).toHaveBeenCalledWith('/api/settings', { respawnPresets: [{ id: 'p' }] });
+    });
+  }
+});
+
+// ─── zh-CN ───
+
+describe('the admin-only toasts in zh-CN', () => {
+  type Api = { t(s: string): string; configure(o: Record<string, string>): void };
+  function translator(language: string) {
+    const dom = new JSDOM('<!doctype html><html><body></body></html>', {
+      runScripts: 'outside-only',
+      url: 'http://localhost/',
+    });
+    windows.push(dom.window);
+    vm.runInContext(I18N, dom.getInternalVMContext(), { filename: 'i18n.js' });
+    const api = (dom.window as unknown as { CodemanI18n: Api }).CodemanI18n;
+    api.configure({ language });
+    return api;
+  }
+
+  it('finds both toasts in the code that shows them', () => {
+    expect(SETTINGS_UI).toContain(`this.showToast('${SAVE_TOAST}', 'warning')`);
+    expect(SETTINGS_UI).toContain(`this.showToast('${ADMIN_TOAST}', 'warning')`);
+    expect(SESSION_UI).toContain(`this.showToast('${ADMIN_TOAST}', 'warning')`);
+  });
+
+  it('translates both, and leaves English as it is', () => {
+    const zh = translator('zh-CN');
+    const en = translator('en');
+    for (const text of [SAVE_TOAST, ADMIN_TOAST]) {
+      const t = zh.t(text);
+      expect(t, text).not.toBe(text);
+      expect(/[A-Za-z]/.test(t), t).toBe(false);
+      expect(en.t(text)).toBe(text);
+    }
+  });
+});

test/shortcut-rebinding.test.ts

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview Behaviour of shortcut rebinding: Alt+[ / Alt+] as registry entries, the
+ * user-bound gate that keeps a rebound chord out of the PTY, and refusal of duplicate chords.
+ *
+ * Real code under test: constants.js + app.js + settings-ui.js in one `vm` context (the
+ * makeApp() harness of ctrl-w-never-closes.test.ts, with settings-ui.js loaded after app.js).
+ */
+import { readFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+
+const read = (f: string) => readFileSync(resolve(import.meta.dirname, `../src/web/public/${f}`), 'utf8');
+
+type Shortcut = { id: string; label: string; action?: string; bindings?: unknown[]; disabled?: boolean };
+type App = {
+  getShortcutRegistry(): Shortcut[];
+  matchesShortcutEvent(e: Record<string, unknown>, s: Shortcut): boolean;
+  isUserBoundShortcutEvent(e: Record<string, unknown>): boolean;
+  findShortcutConflict(e: Record<string, unknown>, id: string): string;
+  onShortcutCaptureKeydown(e: Record<string, unknown>, id: string): void;
+  toggleShortcutEnabled(id: string, enabled: boolean): void;
+  resetShortcutOverride(id: string): void;
+  loadAppSettingsFromStorage: () => Record<string, any>;
+  saveAppSettingsToStorage: (s: Record<string, any>) => void;
+  renderShortcutSettingsList: () => void;
+  showToast: (msg: string, type?: string) => void;
+};
+
+function makeApp(initial: Record<string, any> = {}) {
+  const settings: Record<string, any> = structuredClone(initial);
+  const context = vm.createContext({
+    console,
+    performance,
+    setInterval: vi.fn(),
+    clearInterval: vi.fn(),
+    setTimeout,
+    clearTimeout,
+    requestAnimationFrame: vi.fn(),
+    HTMLCanvasElement: class HTMLCanvasElement {},
+    WebSocket: { OPEN: 1 },
+    fetch: vi.fn(),
+    document: { addEventListener: vi.fn(), getElementById: () => null, querySelector: () => null },
+    localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() },
+    window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+    MobileDetection: { getDeviceType: () => 'desktop', isMobile: () => false, isTouchDevice: () => false },
+  });
+  vm.runInContext(`${read('constants.js')}\n${read('app.js')}\nglobalThis.__CodemanApp = CodemanApp;`, context);
+  vm.runInContext(read('settings-ui.js'), context, { filename: 'settings-ui.js' });
+  const CodemanApp = (context as unknown as { __CodemanApp: { prototype: object } }).__CodemanApp;
+  const app = Object.create(CodemanApp.prototype) as App;
+  app.loadAppSettingsFromStorage = () => settings;
+  app.saveAppSettingsToStorage = (s) => {
+    const next = { ...s };
+    Object.keys(settings).forEach((k) => delete settings[k]);
+    Object.assign(settings, next);
+  };
+  app.renderShortcutSettingsList = vi.fn();
+  app.showToast = vi.fn();
+  return { app, settings };
+}
+
+const key = (o: Record<string, unknown>) => ({
+  type: 'keydown',
+  key: '',
+  code: '',
+  ctrlKey: false,
+  metaKey: false,
+  shiftKey: false,
+  altKey: false,
+  preventDefault: vi.fn(),
+  stopPropagation: vi.fn(),
+  ...o,
+});
+
+const ownerOf = (app: App, e: Record<string, unknown>) =>
+  app.getShortcutRegistry().find((s) => !s.disabled && s.action && app.matchesShortcutEvent(e, s))?.action;
+
+describe('Alt+[ and Alt+] are registry entries', () => {
+  it('resolve to previousSession and nextSession by physical key', () => {
+    const { app } = makeApp();
+    expect(ownerOf(app, key({ altKey: true, key: '[', code: 'BracketLeft' }))).toBe('previousSession');
+    expect(ownerOf(app, key({ altKey: true, key: ']', code: 'BracketRight' }))).toBe('nextSession');
+  });
+
+  it('match the macOS Option layout that prints a curly quote for Option+[', () => {
+    const { app } = makeApp();
+    expect(ownerOf(app, key({ altKey: true, key: '“', code: 'BracketLeft' }))).toBe('previousSession');
+  });
+
+  it('keep their Alt/Option+[ labels until rebound', () => {
+    const { app } = makeApp({
+      shortcutOverrides: { 'next-session-alt': { bindings: [{ modifiers: ['alt'], key: 'j' }] } },
+    });
+    const byId = (id: string) =>
+      app.getShortcutRegistry().find((s) => s.id === id) as Shortcut & { displayBindings?: string[] };
+    expect(byId('previous-session').displayBindings).toEqual(['Alt/Option+[']);
+    expect(byId('next-session-alt').displayBindings).toBeUndefined();
+  });
+});
+
+describe('isUserBoundShortcutEvent', () => {
+  const altJ = key({ altKey: true, key: 'j', code: 'KeyJ' });
+
+  it('is false with no overrides, even for a default chord', () => {
+    const { app } = makeApp();
+    expect(app.isUserBoundShortcutEvent(key({ altKey: true, key: '[', code: 'BracketLeft' }))).toBe(false);
+    expect(app.isUserBoundShortcutEvent(key({ ctrlKey: true, key: 'l', code: 'KeyL' }))).toBe(false);
+  });
+
+  it('is true for a chord the user rebound an action to', () => {
+    const { app } = makeApp({
+      shortcutOverrides: { 'previous-session': { bindings: [{ modifiers: ['alt'], key: 'j', code: 'KeyJ' }] } },
+    });
+    expect(app.isUserBoundShortcutEvent(altJ)).toBe(true);
+  });
+
+  it('is false for the copy-selection rebind, which has its own dispatch', () => {
+    const { app } = makeApp({
+      shortcutOverrides: { 'copy-selection': { bindings: [{ modifiers: ['alt'], key: 'j', code: 'KeyJ' }] } },
+    });
+    expect(app.isUserBoundShortcutEvent(altJ)).toBe(false);
+  });
+
+  it('is false for a rebound sidebar toggle, whose own gate lets the chord through', () => {
+    const { app } = makeApp({
+      shortcutOverrides: { 'toggle-session-sidebar': { bindings: [{ modifiers: ['alt'], key: 's', code: 'KeyS' }] } },
+    });
+    expect(app.isUserBoundShortcutEvent(key({ altKey: true, key: 's', code: 'KeyS' }))).toBe(false);
+  });
+
+  it('is false when the entry was re-captured onto its own default (Ctrl+L still reaches the CLI)', () => {
+    const { app } = makeApp({
+      shortcutOverrides: { 'clear-terminal': { bindings: [{ modifiers: ['ctrl'], key: 'l', code: 'KeyL' }] } },
+    });
+    expect(app.isUserBoundShortcutEvent(key({ ctrlKey: true, key: 'l', code: 'KeyL' }))).toBe(false);
+  });
+
+  it('is false for a disabled rebound entry', () => {
+    const { app } = makeApp({
+      shortcutOverrides: {
+        'previous-session': { bindings: [{ modifiers: ['alt'], key: 'j', code: 'KeyJ' }], disabled: true },
+      },
+    });
+    expect(app.isUserBoundShortcutEvent(altJ)).toBe(false);
+  });
+});
+
+describe('duplicate chords are refused', () => {
+  const ctrlL = key({ ctrlKey: true, key: 'l', code: 'KeyL' });
+
+  it("a capture onto another action's chord names the owner and stores nothing", () => {
+    const { app, settings } = makeApp();
+    app.onShortcutCaptureKeydown(ctrlL, 'next-session-alt');
+    expect(app.showToast).toHaveBeenCalledWith(expect.stringContaining('already used by Clear Terminal'), 'error');
+    expect(settings.shortcutOverrides).toBeUndefined();
+  });
+
+  it("a shortcut's own id and a disabled owner are free", () => {
+    const { app } = makeApp({ shortcutOverrides: { 'previous-session': { disabled: true } } });
+    expect(app.findShortcutConflict(ctrlL, 'clear-terminal')).toBe('');
+    expect(app.findShortcutConflict(key({ altKey: true, key: '[', code: 'BracketLeft' }), 'next-session-alt')).toBe('');
+  });
+
+  it.each([
+    ['Alt+1', { altKey: true, key: '¡', code: 'Digit1' }],
+    ['Cmd+Alt+1', { altKey: true, metaKey: true, key: '¡', code: 'Digit1' }],
+    ['Ctrl+Enter', { ctrlKey: true, key: 'Enter', code: 'Enter' }],
+    ['Shift+Enter', { shiftKey: true, key: 'Enter', code: 'Enter' }],
+    ['Ctrl+V', { ctrlKey: true, key: 'v', code: 'KeyV' }],
+    ['Cmd+V', { metaKey: true, key: 'v', code: 'KeyV' }],
+  ])('%s is reserved', (_n, ev) => {
+    const { app } = makeApp();
+    expect(app.findShortcutConflict(key(ev), 'previous-session')).not.toBe('');
+  });
+
+  it('no two default shortcuts share a chord', () => {
+    const { app } = makeApp();
+    for (const s of app.getShortcutRegistry()) {
+      for (const b of (s.bindings || []) as { modifiers?: string[]; key?: string; code?: string }[]) {
+        const m = b.modifiers || [];
+        const ev = key({
+          ctrlKey: m.includes('ctrl'),
+          metaKey: m.includes('meta'),
+          shiftKey: m.includes('shift'),
+          altKey: m.includes('alt'),
+          key: b.key || '',
+          code: b.code || '',
+        });
+        expect({ id: s.id, owner: app.findShortcutConflict(ev, s.id) }).toEqual({ id: s.id, owner: '' });
+      }
+    }
+  });
+
+  it('re-enabling a disabled action whose chord was taken is refused and leaves it disabled', () => {
+    const { app, settings } = makeApp({
+      shortcutOverrides: {
+        'clear-terminal': { disabled: true },
+        'next-session-alt': { bindings: [{ modifiers: ['ctrl'], key: 'l', code: 'KeyL' }] },
+      },
+    });
+    app.toggleShortcutEnabled('clear-terminal', true);
+    expect(app.showToast).toHaveBeenCalledWith(
+      expect.stringContaining('already used by Next Session (alternate)'),
+      'error'
+    );
+    expect(settings.shortcutOverrides['clear-terminal'].disabled).toBe(true);
+  });
+
+  it('re-enabling with no clash enables it', () => {
+    const { app, settings } = makeApp({ shortcutOverrides: { 'clear-terminal': { disabled: true } } });
+    app.toggleShortcutEnabled('clear-terminal', true);
+    expect(settings.shortcutOverrides['clear-terminal'].disabled).toBe(false);
+  });
+
+  it('Reset is refused while another action owns the default chord, and works once it is free', () => {
+    const { app, settings } = makeApp({
+      shortcutOverrides: {
+        'clear-terminal': { bindings: [{ modifiers: ['ctrl'], key: 'j', code: 'KeyJ' }] },
+        'next-session-alt': { bindings: [{ modifiers: ['ctrl'], key: 'l', code: 'KeyL' }] },
+      },
+    });
+    app.resetShortcutOverride('clear-terminal');
+    expect(app.showToast).toHaveBeenCalledWith(
+      expect.stringContaining('already used by Next Session (alternate)'),
+      'error'
+    );
+    expect(settings.shortcutOverrides['clear-terminal']).toBeDefined();
+
+    app.resetShortcutOverride('next-session-alt');
+    app.resetShortcutOverride('clear-terminal');
+    expect(settings.shortcutOverrides['clear-terminal']).toBeUndefined();
+  });
+});

test/tab-cli-logos-setting.test.ts

@@ -82,6 +82,8 @@ const REAL = new Set([
   // Real so the save builds the body a browser would send (the schema check).
   'resolveHeaderStatsStyle',
   'resolveSessionSidebarFontSize',
+  // The display-key list the load merge reads (settings-ui.js keeps it in one method).
+  '_displaySettingKeySet',
 ]);
 
 /**

test/terminal-copy-selection.test.ts

@@ -138,8 +138,8 @@ describe('smart-copy wiring invariants', () => {
     // the copy action were reachable from there, Ctrl+C would be swallowed with
     // no selection and the user would lose the interrupt key.
     const actionsBlock = APP_SOURCE.slice(
-      APP_SOURCE.indexOf('const SHORTCUT_ACTIONS = {'),
-      APP_SOURCE.indexOf('// Use capture to handle before terminal')
+      APP_SOURCE.indexOf('_shortcutActions() {'),
+      APP_SOURCE.indexOf('isUserBoundShortcutEvent(e) {')
     );
     expect(actionsBlock.length).toBeGreaterThan(0);
     expect(actionsBlock).not.toContain('copyTerminalSelection');

test/tmux-capture-full-history.test.ts

@@ -80,7 +80,7 @@ describe('tmux full-history pane capture (COD-47)', () => {
     // up from them, so the two decisions travel together: no geometry, no move,
     // and the old trim applies instead.
     expect(methodBody).toContain("rawCapture.replace(/\\n$/, '')");
-    expect(methodBody).toContain("if (!geometry) return normalizeScrollbackEol(rawCapture.replace(/\\n+$/g, ''))");
+    expect(methodBody).toContain("const trimmed = rawCapture.replace(/\\n+$/g, '')");
   });
 
   it('defers to the byte history when the pane holds nothing visible', () => {
@@ -144,7 +144,7 @@ describe('the geometry a capture reports back', () => {
     const write = methodBody.indexOf('opts.capturedGeometry = { cols: geometry.cols, rows: geometry.rows }');
     // Anchor on the REPLAY branch, not the earlier `if (fullHistory)` that only
     // sizes the exec buffer.
-    const replayBranch = methodBody.indexOf('if (!geometry) return normalizeScrollbackEol(');
+    const replayBranch = methodBody.indexOf('if (!geometry) {');
     const visibleReturn = methodBody.indexOf('if (geometry) return formatPaneSnapshot(');
     expect(write).toBeGreaterThan(-1);
     expect(replayBranch).toBeGreaterThan(-1);

test/tmux-capture-sgr.browser.test.ts

@@ -0,0 +1,58 @@
+import { createRequire } from 'node:module';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { chromium, type Browser } from 'playwright';
+import { createStyledPaneCapture } from './fixtures/styled-pane-capture.js';
+
+let browser: Browser;
+let capture: Awaited<ReturnType<typeof createStyledPaneCapture>>;
+beforeAll(async () => {
+  capture = await createStyledPaneCapture();
+  browser = await chromium.launch({ headless: true });
+});
+afterAll(async () => {
+  await browser?.close();
+});
+
+describe('captured status-bar colors stay out of live writes (#629)', () => {
+  it.each([
+    [true, true],
+    [true, false],
+    [false, false],
+  ])('fullHistory=%s, geometry=%s', async (fullHistory, geometry) => {
+    const snapshot = capture(fullHistory, geometry);
+    expect(snapshot).not.toBeNull();
+    const page = await browser.newPage();
+    try {
+      await page.setContent('<div id="terminal"></div>');
+      await page.addScriptTag({ path: createRequire(import.meta.url).resolve('@xterm/xterm') });
+      const result = await page.evaluate(async (snapshot) => {
+        const terminal = new (window as any).Terminal({ cols: 40, rows: 2 });
+        terminal.open(document.getElementById('terminal'));
+        const write = (data: string) => new Promise<void>((resolve) => terminal.write(data, resolve));
+        await write(snapshot!);
+        const status = terminal.buffer.active.getLine(1).getCell(0);
+        const statusBackground = status.getBgColor();
+        await write('\x1b[1;1Htyped\x1b[K');
+        const line = terminal.buffer.active.getLine(0);
+        const result = {
+          statusBackground,
+          text: line.translateToString(true),
+          typedDefault: line.getCell(0).isBgDefault(),
+          erasedDefault: line.getCell(10).isBgDefault(),
+          statusAfter: terminal.buffer.active.getLine(1).getCell(0).getBgColor(),
+        };
+        terminal.dispose();
+        return result;
+      }, snapshot);
+      expect(result).toEqual({
+        statusBackground: 2,
+        text: 'typed',
+        typedDefault: true,
+        erasedDefault: true,
+        statusAfter: 2,
+      });
+    } finally {
+      await page.close();
+    }
+  });
+});

test/tmux-capture-sgr.test.ts

@@ -0,0 +1,26 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { createStyledPaneCapture, styledCapture } from './fixtures/styled-pane-capture.js';
+
+let capture: Awaited<ReturnType<typeof createStyledPaneCapture>>;
+beforeAll(async () => {
+  capture = await createStyledPaneCapture();
+});
+
+describe('capturePaneBuffer style handoff (#629)', () => {
+  it('resets the captured style before restoring the cursor', () => {
+    expect(capture(true)).toBe(`${styledCapture.trimEnd().replace(/\n/g, '\r\n')}\x1b[0m\x1b[1A\r`);
+  });
+
+  it.each([true, false])('resets the raw fallback (fullHistory=%s)', (fullHistory) => {
+    expect(capture(fullHistory, false)).toBe(`${styledCapture.trimEnd().replace(/\n/g, '\r\n')}\x1b[0m`);
+  });
+
+  it.each([true, false])('keeps an empty raw fallback empty (fullHistory=%s)', (fullHistory) => {
+    expect(capture(fullHistory, false, '\n\n')).toBe('');
+    expect(capture(fullHistory, false, '')).toBe('');
+  });
+
+  it('keeps an all-blank full-history capture empty', () => {
+    expect(capture(true, true, '\n\n')).toBe('');
+  });
+});

test/tmux-submit-paste.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Covers `buildPasteTextCommands()` and `pasteText()`: the text half of a text+Enter
+ * submit (`sendInput`) goes in as ONE bracketed paste. Also `submitsAsKeys()`: a
+ * single character is typed instead, since a selection dialog ignores a pasted `3`
+ * and the Enter then confirms the highlighted option. And
+ * `escapeTmuxTrailingSemicolon()`, which every literal text path runs through.
+ *
+ * Why: `send-keys -l` typed the text as an unmarked burst, and Codex's paste-burst
+ * heuristic folded the Enter that followed 50 ms later into the paste as a newline,
+ * so the prompt sat in the composer unsubmitted (always at 1500 chars, sometimes for
+ * a one-line prompt). With `paste-buffer -p` the paste is marked and the separate
+ * Enter submits.
+ *
+ * Strategy: pure command shape, plus a round trip through a real shell with a fake
+ * `tmux` that prints its argv, so quoting and tmux's trailing-`;` rule are checked
+ * on the bytes a shell actually hands over. `pasteText` runs against a recording
+ * runner. No real tmux.
+ *
+ * Port: N/A (no server / no real tmux)
+ */
+import { execSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+import { buildPasteTextCommands, escapeTmuxTrailingSemicolon, pasteText, submitsAsKeys } from '../src/tmux-manager.js';
+
+const FAKE_TMUX = `${JSON.stringify(process.execPath)} -e 'console.log(JSON.stringify(process.argv.slice(1)))' --`;
+
+function argvOf(cmd: string): string[] {
+  return JSON.parse(execSync(cmd, { encoding: 'utf-8' })) as string[];
+}
+
+describe('buildPasteTextCommands', () => {
+  it('fills a buffer, pastes it bracketed into the target and deletes it', () => {
+    const { set, paste, discard } = buildPasteTextCommands('tmux -L codeman', 'codeman-abc12345', 'hello');
+    const buffer = /set-buffer -b (\S+) -- /.exec(set)?.[1];
+    expect(buffer).toMatch(/^codeman-submit-\d+-\d+$/);
+    expect(set).toBe(`tmux -L codeman set-buffer -b ${buffer} -- 'hello'`);
+    expect(paste).toBe(`tmux -L codeman paste-buffer -p -d -b ${buffer} -t 'codeman-abc12345'`);
+    expect(discard).toBe(`tmux -L codeman delete-buffer -b ${buffer}`);
+  });
+
+  it('never types the text with send-keys (the unmarked burst Codex misreads)', () => {
+    for (const cmd of Object.values(buildPasteTextCommands('tmux', 'codeman-abc12345', 'read your inbox'))) {
+      expect(cmd).not.toContain('send-keys');
+    }
+  });
+
+  it('uses a fresh buffer per call, so concurrent sends cannot paste each other', () => {
+    const a = buildPasteTextCommands('tmux', 't', 'a').set;
+    const b = buildPasteTextCommands('tmux', 't', 'b').set;
+    expect(/-b (\S+)/.exec(a)?.[1]).not.toBe(/-b (\S+)/.exec(b)?.[1]);
+  });
+
+  it.each([
+    ['quotes and shell syntax', `it's "quoted" $HOME \`id\` $(id) & | > <`],
+    ['tmux format syntax', '#{session_name} #S'],
+    ['leading dash', '-t other --help'],
+    ['non-ASCII', 'Mailbox lesen — äöü “x”'],
+    ['a long prompt', 'x'.repeat(1500)],
+  ])('hands the text to tmux unchanged through the shell: %s', (_label, text) => {
+    const { set } = buildPasteTextCommands(FAKE_TMUX, 't', text);
+    expect(argvOf(set).at(-1)).toBe(text);
+  });
+
+  it.each([
+    ['x;', 'x\\;'],
+    [';', '\\;'],
+    ['x;;', 'x;\\;'],
+    ['x\\;', 'x\\\\;'],
+  ])('escapes a trailing ";" (tmux command separator): %s', (text, expected) => {
+    const { set } = buildPasteTextCommands(FAKE_TMUX, 't', text);
+    expect(argvOf(set).at(-1)).toBe(expected);
+  });
+
+  it('leaves a ";" inside the text alone', () => {
+    const { set } = buildPasteTextCommands(FAKE_TMUX, 't', 'a; b');
+    expect(argvOf(set).at(-1)).toBe('a; b');
+  });
+});
+
+describe('submitsAsKeys', () => {
+  it.each(['3', '9', 'y', 'n', ';', 'ä', '👍'])('types a single character: %s', (text) => {
+    expect(submitsAsKeys(text)).toBe(true);
+  });
+
+  it.each(['10', 'yes', '/cost', 'read your inbox', 'x'.repeat(1500)])('pastes anything longer: %s', (text) => {
+    expect(submitsAsKeys(text)).toBe(false);
+  });
+});
+
+describe('escapeTmuxTrailingSemicolon', () => {
+  it.each([
+    ['x;', 'x\\;'],
+    [';', '\\;'],
+    ['a; b', 'a; b'],
+    ['plain', 'plain'],
+  ])('%s -> %s', (text, expected) => {
+    expect(escapeTmuxTrailingSemicolon(text)).toBe(expected);
+  });
+});
+
+describe('pasteText', () => {
+  const cmds = { set: 'SET', paste: 'PASTE', discard: 'DISCARD' };
+
+  function recorder(failOn: string[] = []) {
+    const ran: string[] = [];
+    const run = async (cmd: string) => {
+      ran.push(cmd);
+      if (failOn.includes(cmd)) throw new Error(`${cmd} failed`);
+    };
+    return { ran, run };
+  }
+
+  it('fills the buffer, then pastes it; the paste deletes it, so nothing else runs', async () => {
+    const { ran, run } = recorder();
+    await pasteText(run, cmds);
+    expect(ran).toEqual(['SET', 'PASTE']);
+  });
+
+  it('deletes the buffer when the paste fails, and reports the paste error', async () => {
+    const { ran, run } = recorder(['PASTE']);
+    await expect(pasteText(run, cmds)).rejects.toThrow('PASTE failed');
+    expect(ran).toEqual(['SET', 'PASTE', 'DISCARD']);
+  });
+
+  it('still reports the paste error when the delete fails too', async () => {
+    const { ran, run } = recorder(['PASTE', 'DISCARD']);
+    await expect(pasteText(run, cmds)).rejects.toThrow('PASTE failed');
+    expect(ran).toEqual(['SET', 'PASTE', 'DISCARD']);
+  });
+
+  it('does not paste when filling the buffer failed', async () => {
+    const { ran, run } = recorder(['SET']);
+    await expect(pasteText(run, cmds)).rejects.toThrow('SET failed');
+    expect(ran).toEqual(['SET']);
+  });
+});
+
+describe('sendInput wiring', () => {
+  // sendInput() returns before touching tmux under vitest (IS_TEST_MODE), so the
+  // branch that submits text is pinned on the source instead.
+  async function source(): Promise<string> {
+    const { readFileSync } = await import('node:fs');
+    return readFileSync(new URL('../src/tmux-manager.ts', import.meta.url), 'utf-8');
+  }
+
+  async function sendInputBody(): Promise<string> {
+    const src = await source();
+    return src.slice(src.indexOf('async sendInput('), src.indexOf('// ========== Pane Methods'));
+  }
+
+  it('submits text through pasteText, not send-keys -l', async () => {
+    const body = await sendInputBody();
+    const submitBranch = body.slice(
+      body.indexOf('if (textPart && hasCarriageReturn)'),
+      body.indexOf('} else if (textPart)')
+    );
+    const pasteBranch = submitBranch.slice(submitBranch.indexOf('} else {'));
+    expect(pasteBranch).toContain('pasteText(');
+    expect(pasteBranch).toContain('buildPasteTextCommands(');
+    expect(pasteBranch).not.toMatch(/send-keys[^`]*-l/);
+  });
+
+  it('types a single-character submit with send-keys -l, so a dialog answer selects', async () => {
+    const body = await sendInputBody();
+    const keysBranch = body.slice(body.indexOf('if (submitsAsKeys(textPart))'), body.indexOf('} else {'));
+    expect(keysBranch).toMatch(/send-keys[^`]*-l \$\{shellescape\(escapeTmuxTrailingSemicolon\(textPart\)\)\}/);
+    expect(keysBranch).not.toContain('pasteText(');
+  });
+
+  it('escapes a trailing ";" on every send-keys -l in sendInput and sendInputToPane', async () => {
+    const src = await source();
+    const typed = src.match(/send-keys[^`\n]*-l \$\{[^`\n]*\}/g) ?? [];
+    const inSend = [await sendInputBody(), src.slice(src.indexOf('sendInputToPane(muxName'))]
+      .map((b) => b.slice(0, b.indexOf('\n  }\n')))
+      .join('\n');
+    const typedHere = typed.filter((cmd) => inSend.includes(cmd));
+    expect(typedHere.length).toBe(4);
+    for (const cmd of typedHere) expect(cmd).toContain('escapeTmuxTrailingSemicolon(textPart)');
+  });
+});

test/toolbar-attach.test.ts

@@ -19,7 +19,7 @@ function loadToolbar(sessionId: string | null = 'session-1', localEcho = true, k
   const dom = new JSDOM(
     '<!DOCTYPE html><html><body><span class="btn-attach-mobile-wrap">' +
       '<button type="button" id="attachBtnMobile"></button>' +
-      '<input type="file" id="attachFileInput" accept="image/*,video/*" multiple>' +
+      '<input type="file" id="attachFileInput" accept="image/*,video/*,.pdf,.docx,.pptx,.xlsx,.zip,.txt,.md,.csv,.tsv,.json,.log,.yaml,.yml,.xml" multiple>' +
       '</span></body></html>'
   );
   const { window } = dom;
@@ -333,13 +333,13 @@ describe('phone toolbar Attach button', () => {
     expect(composerBar._insertComposerText).not.toHaveBeenCalled();
   });
 
-  it('rejects a selection with neither image nor video with a toast and no upload', async () => {
+  it('rejects a selection the server would refuse with a toast and no upload', async () => {
     const { app, window, select } = loadToolbar();
-    select([new window.File(['%PDF-'], 'doc.pdf', { type: 'application/pdf' })]);
+    select([new window.File(['#!/bin/sh'], 'run.sh', { type: 'text/x-shellscript' })]);
     await Promise.resolve();
     expect(app._uploadAndInsertImages).not.toHaveBeenCalled();
     expect(app._sendInputAsync).not.toHaveBeenCalled();
-    expect(app.showToast).toHaveBeenCalledWith('Only image or video files are supported', 'error');
+    expect(app.showToast).toHaveBeenCalledWith('Unsupported file type', 'error');
   });
 
   it('classifies a pick by its name when the file manager supplied no MIME type', () => {
@@ -348,8 +348,38 @@ describe('phone toolbar Attach button', () => {
     expect(kind('clip.ogv', '')).toBe('video');
     expect(kind('IMG_0001.MOV', '')).toBe('video');
     expect(kind('shot.heic', '')).toBe('image');
-    expect(kind('notes.pdf', '')).toBeNull();
     expect(kind('clip.ogv', 'image/jpeg')).toBe('image'); // the MIME type wins when present
+    // Documents are known by the name alone: the MIME a file manager gives them varies.
+    expect(kind('notes.pdf', 'application/pdf')).toBe('document');
+    expect(kind('Q3 report.XLSX', '')).toBe('document');
+    expect(kind('todo.md', 'text/plain')).toBe('document');
+    expect(kind('data.csv', 'application/octet-stream')).toBe('document');
+    expect(kind('run.sh', 'text/x-shellscript')).toBeNull();
+    expect(kind('page.html', 'text/html')).toBeNull();
+    expect(kind('noext', '')).toBeNull();
+  });
+
+  it('uploads a document as picked, through the image path (no re-encode, no video flag)', async () => {
+    const { app, window, fetchMock } = loadToolbar();
+    const pdf = new window.File(['%PDF-'], 'notes.pdf', { type: 'application/pdf' });
+    expect(await app._normalizeImageForUpload(pdf)).toBe(pdf);
+    await app._uploadPasteImage('session-1', pdf);
+    expect(fetchMock.mock.calls[0][0]).toBe('/api/sessions/session-1/paste-image');
+  });
+
+  it('counts a video MIME only for the containers the server admits on ?kind=video', () => {
+    const { app, window } = loadToolbar();
+    const kind = (type: string, name = 'clip') => app._promptAttachKind(new window.File(['x'], name, { type }));
+    // The five the server's ?kind=video branch accepts (session-routes.ts).
+    for (const type of ['video/mp4', 'video/quicktime', 'video/x-m4v', 'video/webm', 'video/ogg']) {
+      expect(kind(type)).toBe('video');
+    }
+    // A video MIME outside that set is refused client-side (no full upload then a
+    // 400) when the name's extension is not one the server admits either.
+    expect(kind('video/3gpp', 'clip.3gp')).toBeNull();
+    expect(kind('video/x-matroska', 'clip.mkv')).toBeNull();
+    // An admitted extension still rescues an odd MIME, as the server's path does.
+    expect(kind('video/3gpp', 'clip.mp4')).toBe('video');
   });
 
   it('flags the upload as a video by name as well as by MIME type', async () => {

test/whats-new.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { JSDOM } from 'jsdom';
+// @ts-expect-error plain .mjs helper shared with scripts/generate-whats-new.mjs
+import { extractHighlights, versionSection, buildWhatsNew } from '../scripts/lib/whats-new.mjs';
+
+const root = resolve(import.meta.dirname, '..');
+
+const CHANGELOG = `# aicodeman
+
+## 1.2.0
+
+### Minor Changes
+
+- ### Thanks
+  - @someone for a fix
+
+  **The tile grid: six sessions side by side.** Body text with **inline bold** later.
+
+- **Split view (#560).** More text.
+- A bullet with no bold lead.
+
+  **Behaviour change: \`Ctrl+W\` no longer closes a session.** Details.
+
+## 1.1.0
+
+- **Old feature.** Not for 1.2.0.
+`;
+
+describe('whats-new extraction', () => {
+  it('limits itself to the requested version section', () => {
+    const section = versionSection(CHANGELOG, '1.2.0');
+    expect(section).toContain('tile grid');
+    expect(section).not.toContain('Old feature');
+    expect(versionSection(CHANGELOG, '9.9.9')).toBe('');
+  });
+
+  it('takes bold lead-ins only, cleaned, and skips the Thanks block', () => {
+    expect(extractHighlights(versionSection(CHANGELOG, '1.2.0'))).toEqual([
+      'The tile grid: six sessions side by side',
+      'Split view (#560)',
+      'Behaviour change: `Ctrl+W` no longer closes a session',
+    ]);
+  });
+
+  it('reads a lead-in behind the commit prefix changesets writes for a committed changeset', () => {
+    const section = '- d18deed: **Each release announces itself (#618).** Text.\n- 13e652e: A fix with no lead-in.';
+    expect(extractHighlights(section)).toEqual(['Each release announces itself (#618)']);
+  });
+
+  it('skips group labels the release notes put in bold (Fixes, Fixes applied while landing)', () => {
+    const section = [
+      '  **Tab layouts (#538).** Text.',
+      '  **Fixes.**',
+      '  - **Shells reload cleanly (#601).** Text.',
+      '  **Fixes applied while landing.** Remote tabs keep their scrollback.',
+    ].join('\n');
+    expect(extractHighlights(section)).toEqual(['Tab layouts (#538)', 'Shells reload cleanly (#601)']);
+  });
+
+  it('yields no highlights for a release written without bold lead-ins', () => {
+    const changelog =
+      '## 1.32.1\n\n### Patch Changes\n\n- 13e652e: Terminal copy: no gutter on the clipboard (#469).\n';
+    expect(buildWhatsNew(changelog, '1.32.1')).toEqual({ version: '1.32.1', highlights: [] });
+  });
+
+  it('caps the list', () => {
+    const many = Array.from({ length: 20 }, (_, i) => `**Feature number ${i}.** text`).join('\n\n');
+    expect(extractHighlights(many)).toHaveLength(8);
+  });
+
+  it('builds the payload the client reads', () => {
+    expect(buildWhatsNew(CHANGELOG, '1.2.0').version).toBe('1.2.0');
+  });
+});
+
+describe('shipped whats-new.json', () => {
+  it("matches the package version, so a release cannot ship the previous release's notes", () => {
+    const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+    const notes = JSON.parse(readFileSync(resolve(root, 'src/web/public/whats-new.json'), 'utf8'));
+    expect(notes.version).toBe(pkg.version);
+    // A release written without bold lead-ins legitimately has none (the client then stays
+    // quiet), so an empty list must not turn the release commit's CI red.
+    expect(Array.isArray(notes.highlights)).toBe(true);
+  });
+
+  it('is regenerated by the release script and consumed once per version by the client', () => {
+    const pkg = readFileSync(resolve(root, 'package.json'), 'utf8');
+    expect(pkg).toMatch(/"version-packages": "changeset version && node scripts\/generate-whats-new\.mjs/);
+    const ui = readFileSync(resolve(root, 'src/web/public/settings-ui.js'), 'utf8');
+    expect(ui).toContain("'codeman-whats-new-seen'");
+    expect(ui).toContain("fetch('/whats-new.json'");
+    expect(readFileSync(resolve(root, 'src/web/public/app.js'), 'utf8')).toContain(
+      'this.checkWhatsNew?.(data.version)'
+    );
+  });
+});
+
+describe('the announcement in zh-CN', () => {
+  const dom = new JSDOM('<!doctype html><html><body></body></html>', {
+    runScripts: 'outside-only',
+    url: 'http://localhost/',
+  });
+  vm.runInContext(readFileSync(resolve(root, 'src/web/public/i18n.js'), 'utf8'), dom.getInternalVMContext());
+  const api = (
+    dom.window as unknown as { CodemanI18n: { t(s: string): string; configure(o: Record<string, string>): void } }
+  ).CodemanI18n;
+  api.configure({ language: 'zh-CN' });
+
+  it('translates the button and the toast frame, keeping the version and the English highlights', () => {
+    expect(api.t("See what's new")).toBe('查看更新内容');
+    expect(api.t('Codeman updated to v1.41.2: Tab layouts (#538) · Split view')).toBe(
+      'Codeman 已更新到 v1.41.2：Tab layouts (#538) · Split view'
+    );
+    expect(api.t('Codeman updated to v1.41.2: A · B · C (+5 more)')).toBe(
+      'Codeman 已更新到 v1.41.2：A · B · C（另有 5 项）'
+    );
+  });
+
+  it('builds the strings the pattern expects', () => {
+    const ui = readFileSync(resolve(root, 'src/web/public/settings-ui.js'), 'utf8');
+    expect(ui).toContain('`Codeman updated to v${runningVersion}: ${shown}${more}`');
+    expect(ui).toContain('` (+${notes.highlights.length - 3} more)`');
+    expect(ui).toContain(`label: "See what's new"`);
+  });
+});