chore: version packages

#386 made Codex conversations resumable from Past Sessions, and
resumeMobileOverviewSession() correctly passes row.resumeId on to
resumeHistorySession(). The phone's own row projection never copied the
field off the unified-list item though, so row.resumeId was always
undefined there and a tapped Codex row started a FRESH session on a thread
that was already on disk. The desktop path worked; only the phone was blind.

The test fails without the projection line, and pins the other half too: a
claude row must not grow a resumeId, since the field is what distinguishes
"resume this conversation" from "start a new one".

Docs: CLAUDE.md and architecture-invariants both still described the unified
list as merging Claude transcript files. It has been three stores since this
PR (Claude's ~/.claude/projects, omp's ~/.omp/agent/sessions, codex's
~/.codex/sessions), the alias field keeps its Claude-era name without being
Claude-only, and the scanner-only rule behind resumeId was written down
nowhere.

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

CHANGELOG.md

@@ -1,5 +1,47 @@
 # aicodeman
 
+## 1.26.1
+
+### Patch Changes
+
+- Codex sessions no longer report idle for their entire life, and Codex conversations now appear in Past Sessions and can be resumed.
+
+  **Per-CLI work detection (#385, irisitymichaelgrundberg).** The composer glyph and the working status line are now registry data (`capabilities.workDetect`) rather than Claude constants. Claude keeps its exact current pair, Codex declares `›` plus its `esc to interrupt` footer, and any CLI that declares neither falls back to Claude's, which is what every session used before. Work detection had been gated Claude-mode-only on the reasoning that an external CLI has no `❯`, which was true and still left every Codex session reporting `idle` from the moment it started. `workingLine` is config-supplied and its compiled pattern runs on the PTY hot path, so it goes through `compileVersionRegex()` in both the schema refine and the runtime compile: a nested quantifier there would backtrack on the event loop for the whole server. The Codex footer is matched case-insensitively on the E, so a future version capitalising it cannot make the fix silently inert.
+
+  **Codex conversations in Past Sessions (#386, irisitymichaelgrundberg).** A bounded scanner reads codex's `~/.codex/sessions` rollout store, so the unified session list now merges three transcript stores rather than one (Claude's `~/.claude/projects`, omp's `~/.omp/agent/sessions`, codex's `~/.codex/sessions`). A scanned row carries a `resumeId`, the rollout's own thread id, which lets it resume through `codexConfig.resumeSessionId`; a live session never carries one, so a row without it stays a genuinely fresh session. Live and resumed Codex sessions fold into their rollout row through the existing alias map, including a `session_meta.originator` match for fresh panes, so a conversation never shows up twice. The phone overview carries `resumeId` through its own row projection, without which a tapped Codex past row started a fresh session on a thread already on disk.
+
+  ### Thanks
+  - @irisitymichaelgrundberg for both PRs (#385, #386), and for turning a full review round on #386 in a day.
+
+## 1.26.0
+
+### Minor Changes
+
+- Tag the case directories agent workers create, and clean up what they leave behind.
+
+  A long agent orchestration creates one case directory per worker, and deleting the
+  sessions never removed them, so `~/codeman-cases` filled with scratch folders that
+  looked exactly like real projects.
+  - A case directory `POST /api/quick-start` **creates** for an agent-driven spawn now
+    carries a `.codeman-agent-case.json` marker recording when it was made, by whom,
+    from which session, and in which mode. Only the branch that creates the directory
+    writes it, so a linked case, a cloned repo or any pre-existing path is never
+    labelled, and deleting the marker file adopts a scratch case as a real one.
+  - The label comes from the new `X-Codeman-Agent-Origin` header that the packaged agent
+    skill sets on its shared curl invocation (preamble 1.22.0), or an `agentOrigin` body
+    field, falling back to a resolved `parentSessionId` so workers spawned by an older
+    skill copy are still labelled.
+  - `GET /api/cases` publishes it as `agentCreated`, and the new read-only
+    `GET /api/cases/agent-created` lists the scratch cases with `inUse` (a live session
+    is still working in it) and `modifiedAt`.
+  - Add Case -> Manage badges every agent-created case and adds a sticky **Clean up**
+    entry point that names each directory in its confirmation and skips any case a
+    running session is using. Removal still goes through `DELETE /api/cases/:name`.
+  - The agent skill's per-session preamble cache (`~/.cache/codeman-agent-<id>.sh`) is
+    now removed with the session and swept at boot. One was written per Claude session
+    and nothing ever deleted them (236 orphans on a working machine); the sweep keeps
+    every live session's file and only takes orphans older than seven days.
+
 ## 1.25.0
 
 ### Minor Changes

CLAUDE.md

@@ -75,7 +75,7 @@ When user says "COM":
 
 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.
 
-**Version**: 1.25.0 (must match `package.json`)
+**Version**: 1.26.1 (must match `package.json`)
 
 ## Project Overview
 
@@ -193,9 +193,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Agent wait primitives**: bounded long-polls so an agent driving Codeman from a shell can block instead of poll: `GET /api/sessions/:id/wait` (lifecycle signal), `GET /api/sessions/:id/wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST /api/sessions/:id/input`. Registry in `session-wait-registry.ts` (pure, no `Session` reference), bounds in `config/agent-wait.ts`. ⚠️ **A timeout is a 200** (`wait.timedOut`), never an error, so callers loop over short waits. ⚠️ `stop`/`blocked` are hook-driven and fire for **`claude` and `deepseek` ONLY** (`shell` installs none either); asking for one explicitly on any other mode is a 400, the default set silently drops them. `deepseek` qualifies because the DeepSeek Harness TUI REPORTS idle/working/blocked to its supervisor and Codeman is that supervisor (`deepseek-status-shim.ts`), so its signals are definitive rather than inferred — `hooksAvailableForMode()` in `session-wait-registry.ts` is the one place that rule lives. ⚠️ Send-and-wait registers the waiter BEFORE the write (a separate POST-then-wait races and reports the PREVIOUS turn), and both teardown paths must `notifySignal('exit')` BEFORE `cancelAll()`. ⚠️ Client-hangup abort listens on **`reply.raw`** guarded by `writableFinished`: on `req.raw`, `close` fires when the request BODY ends, which on a POST killed every send-and-wait instantly and no `app.inject()` test could see it. ⚠️ Worker liveness cannot come from `session.pid` — for a tmux session that is the local attach client, which outlives a worker dying inside its pane — so it is probed at the mux layer (`isPaneDead`, ~750 ms cache) on blocking waits only, never on the input hot path. ⚠️ Signals are edge-triggered with no history: one that fires with no waiter registered is unobservable afterwards, so gather fan-outs with send-and-wait or latched `wait-output` markers, never fire-and-forget-then-sequential-signal-waits. ⚠️ **`deepseek` is therefore the one non-claude mode the skill drives like claude** — `spawn_workers alpha beta:deepseek` is a mixed fleet in one call, and `sendwait`/`last_text` need no variant. Two traps are baked into the preamble rather than left to the agent: the harness's boot `idle` report lands ~300 ms BEFORE its composer paints (2.26 s vs 2.56 s, measured), so readiness must come from the composer and never from the signal, or a send-and-wait resolves on the boot edge and reports a turn that never ran; and `sendwait` asks for `wait:"stop,exit"` rather than the default set, because that set also carries `idle`, which for an external CLI is inferred from output stabilization — on a dsh worker whose TUI repaints rarely, a re-wait resolved in 0 ms with `signal:"idle"` on a turn with minutes left to run. The primitives are packaged as the **`skills/codeman` agent skill**: installable via `codeman skill install [--case <name>]` / `skill uninstall`, or auto-injected into a case's `.claude/skills/` on Claude session create behind `agentSkillEnabled` (SYNCED, default OFF). Injection is ADD-ONLY at create, marker-owned (`applyAgentSkill` in `hooks-config.ts` never touches an unmarked user copy) and refuses symlinks (this repo's own `.claude/skills/codeman` is a symlink to the source, which the injector must never write through). ⚠️ Claude Code loads a same-named USER-LEVEL skill (`~/.claude/skills/codeman`, written once by `codeman skill install` with no `--case`) over the per-case copy, and nothing used to refresh it: a stale Aug-9 user copy shadowed every fresh injection (2026-08-14: agents ran the old recipes, spawned workers serially and lost their lineage arcs), so session create now also refreshes a marker-owned user copy (`refreshUserAgentSkill`; refresh-only, never installs, foreign/symlink refused). Session create additionally pre-seeds the skill's §0 preamble cache (`seedAgentSessionPreamble` → `${XDG_CACHE_HOME:-~/.cache}/codeman-agent-<id>.sh`, local claude sessions only), single-sourced from `skills/codeman/preamble.sh` and pinned byte-identical to SKILL.md's §0 heredoc by `test/agent-skill.test.ts`, so the skill's bootstrap is a two-line loader instead of a ~150-line paste the model types out (~47 s of generation, measured live). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
 
+**Agent-created case marker** (`src/agent-case-marker.ts`): a case directory `POST /api/quick-start` **creates** for an agent-driven spawn gets a `.codeman-agent-case.json` marker, so the scratch workspaces a long orchestration leaves behind (one per worker, and deleting the session does not remove them) can still be told apart from the user's real projects months later. `GET /api/cases` publishes it as `agentCreated`; `GET /api/cases/agent-created` is the read-only cleanup listing, adding `inUse` (a live session's `workingDir` is that case) and `modifiedAt`; Add Case → Manage badges each one and offers a review-then-delete sweep. The signal is the skill preamble's `X-Codeman-Agent-Origin` header (or an `agentOrigin` body field), falling back to a RESOLVED `parentSessionId` — nothing in the browser UI sets lineage, so a create request naming its spawning session came from an agent by construction, and that fallback is what still labels workers spawned by a stale skill copy. ⚠️ **Only the branch that CREATES the directory may write it.** A linked case, a cloned repo or any pre-existing path must never be labelled: the label drives a recursive-delete affordance, and mislabelling someone's repo there is the one failure mode that costs real work. `POST /api/sessions` takes an existing `workingDir`, so it writes no marker at all, by construction. ⚠️ Reading is TOTAL: anything that is not a well-formed version-1 marker (truncated write, hand-edited junk) reads as *not* agent-created rather than as a half-trusted entry, and deleting the file is the supported way to adopt a scratch case as a real one — which is what the `note` written into it tells whoever finds it. ⚠️ Removal stays on the existing `DELETE /api/cases/:name`, one name at a time, so there is exactly ONE recursive-delete path; the UI's sweep names every directory in its confirm and EXCLUDES an `inUse` case outright rather than confirming it away. ⚠️ Marker in the case dir rather than a registry under `~/.codeman`: it survives a wiped data dir or a different instance, is removed by the same `rm -rf` that removes the case (so no stale-entry pruning), and a user who runs `ls -a` can see what labelled their directory. Adding the header changed the preamble, so `CODEMAN_PREAMBLE` was bumped (1.22.0) — a cached copy is version-checked, and forgetting the bump leaves every already-seeded agent sending the old headers. Tests: `test/agent-case-marker.test.ts`, `test/routes/agent-case-marker-routes.test.ts`.
+
+**Agent preamble cache GC**: the §0 preamble seeded per claude session (`$XDG_CACHE_HOME/codeman-agent-<id>.sh`) is now REMOVED with the session (`removeAgentSessionPreamble` from `_doCleanupSession`, `killMux` only — a detach leaves the session recoverable and its agent would come back to a loader whose file we deleted) and swept at boot (`pruneAgentSessionPreambles(this.sessions.keys())`, once, after restore, so every session this instance owns is in the keep set). Nothing removed them before: 236 leftovers measured on a working machine, the oldest three weeks old. ⚠️ The sweep needs BOTH guards — never a live session's file at any age (the two-line loader reads it mid-run), and `AGENT_PREAMBLE_MAX_AGE_MS` (7d) of age on top, which is what keeps ANOTHER instance's sessions (whose ids this process cannot see) out of the blast radius. Losing one is degradation, not breakage: the §0 fallback block rewrites it. Tests live with the seed's in `test/agent-skill.test.ts`.
+
 **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 (`❯`) about once a second all through a turn, so the old "saw a ❯, wait 2s → idle" rule flipped every working session to idle two seconds in (measured: a session mid-tool-call at 17 minutes reporting `status:"idle"`). Its working indicator is `✻ Actualizing… (13m 23s · ↓ 47.5k tokens)`: the glyph animates through `· ✢ ✳ ∗ ✻ ✽`, the gerund is randomized, and the finished line (`✻ Cooked for 2m 49s`) carries the same glyph, so neither `SPINNER_PATTERN` (braille, not what current versions draw) nor a keyword list can see it. Matching the new line in the STREAM does not work either: tmux ships partial repaints, so the whole line reaches the PTY only every few tens of seconds. 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. Claude-mode only, since an external CLI has no `❯`, so nothing would ever arm the confirmation and the session would latch busy.
+⚠️ **A `❯` sighting is NOT the end of a turn, and neither is silence.** Claude redraws the composer (`❯`) about once a second all through a turn, so the old "saw a ❯, wait 2s → idle" rule flipped every working session to idle two seconds in (measured: a session mid-tool-call at 17 minutes reporting `status:"idle"`). Its working indicator is `✻ Actualizing… (13m 23s · ↓ 47.5k tokens)`: the glyph animates through `· ✢ ✳ ∗ ✻ ✽`, the gerund is randomized, and the finished line (`✻ Cooked for 2m 49s`) carries the same glyph, so neither `SPINNER_PATTERN` (braille, not what current versions draw) nor a keyword list can see it. Matching the new line in the STREAM does not work either: tmux ships partial repaints, so the whole line reaches the PTY only every few tens of seconds. 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 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`, 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.
 
 **Workspace-trust dialog auto-accept** (`session-trust-dialog.ts`, pure + unit tested): Claude Code asks once per directory ("Is this a project you created or one you trust?") before it will read or edit anything, and since Codeman sessions run permission-skipping or classifier-guarded modes the answer is always yes, so a session parked on that dialog is simply stuck. ⚠️ **Match the compacted SCREEN, never the stream.** tmux repaints a row by writing each word and then a cursor-forward (`\x1b[C`) instead of a space, and Ink colours each word separately, so the wire carries `I\x1b[Ctrust\x1b[Cthis\x1b[Cfolder`; stripping the escapes leaves `Itrustthisfolder`, because the spaces are not there to strip, they were never sent. A plain `includes('trust this folder')` therefore never matched a single chunk and the auto-accept was silently DEAD for every session that hit the dialog. `compactScreenText()` removes ALL whitespace instead (plus the `ESC ( B` charset selects that `stripAnsi` does not cover, which would otherwise land inside a phrase as a literal `(B`), which survives both that repaint style and the spaced full-screen redraw. ⚠️ **Never answer it with a blind `\r`.** The layout has changed under us at least twice, and Claude Code 2.1.252 dropped the option numbers, put "No, exit" FIRST and highlights IT by default, so the Enter that answered the old dialog now picks *exit* and the pane dies (`Pane is dead (status 1)`) seconds after the session starts. `trustDialogNextKey()` reads the `❯` marker and returns ONE step at a time (an arrow while the cursor is on the wrong option, Enter only once the screen shows it on the trust option), with the pane re-read between steps, so a dropped arrow costs a repaint instead of the session; a frame that does not say which option is highlighted returns null and waits for the next repaint. ⚠️ The LAST marked option in the text wins, because the direct-PTY fallback reads an append-only buffer where every repaint since launch is still present and an older frame must not out-vote the freshest one. ⚠️ Answering types into a live session, so THREE guards must all hold and none is redundant: a **startup-only window** (`TRUST_DIALOG_WINDOW_MS`, 90s, since the dialog renders before the main UI and leaving it open forever would let an agent transcript that merely QUOTES the dialog trigger an Enter, this file being an example), a **two-marker match** requiring a trust phrase AND one of the dialog's own confirm affordances (`isTrustDialogScreen`), and an **attempt cap** (`TRUST_DIALOG_MAX_ATTEMPTS`, 6: a keystroke can land while Ink is still mounting the widget and be dropped, which is the other half of why sessions got stuck here, but retrying forever would hammer keys into whatever came next; it was 3 while one Enter answered the dialog, and answering now costs at least two keystrokes). ⚠️ 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).
 
@@ -215,9 +219,9 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Docker Compose deployment** (`docker/`, contributed): Codeman itself runs in a container and spawns Docker cases as **SIBLING** containers through the mounted host socket (Docker-outside-of-Docker), never nested. That inverts one assumption the bare-host path takes for granted: the daemon no longer shares Codeman's filesystem, so a bind source valid *inside* Codeman means nothing to it. `resolveDockerDaemonMountSource()` translates sources under HOME into the daemon's namespace via `CODEMAN_DOCKER_HOST_HOME`, and `CODEMAN_CASES_PATH` points the cases dir at a host-absolute bind mount so a workspace resolves to the SAME absolute path on both sides (which is what keeps the transcript projHash matching, per Docker cases above). ⚠️ **`CODEMAN_CASES_PATH` must move every consumer or none**: it is resolved once in `config/cases-dir.ts` because `src/cli.ts` resolves case paths too, and when only the server's `CASES_DIR` learned the override, `codeman skill install --case <name>` reported "Case not found" on exactly the deployment the override exists for. ⚠️ **`.dockerignore` patterns match the WHOLE context-relative path**, so a bare `.env` line excludes only the ROOT file: `docker/.env` (which holds `CODEMAN_PASSWORD` and any provider keys) rode `COPY . .` into the image until `**/.env` was added — verified in both directions with a real build context. ⚠️ A Compose LONG-form bind (`type: bind`) **creates a missing host source directory ROOT-OWNED** rather than refusing, so any bind source the runtime user must write to has to be pre-created and chowned. `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1` drops `--memory-swap` (and filters only that one kernel warning) for hosts without swap accounting; `--memory` still applies. ⚠️ The deployment ALSO self-updates in place (the repo bind mount at `/opt/codeman` + a restart-by-exiting supervisor) — see Self-update below and `docs/docker-self-update.md` before touching `server.Dockerfile`, the compose file or `.env.example`, since each is an input to the updater's environment gate. `docs/docker-compose.md` + `docker/README.md` (user guides)
 
-**CLI registry** (`src/config/cli-registry/`): every run mode is a `CliEntry` — discovery (search dirs, version + identity probes), the launch argv template, env handling, the `capabilities` flags that replace per-CLI branching, and the `overlays` that back the remote/docker pane commands. **No code outside `stock.ts` may branch on a CLI id**; behaviour that genuinely differs is either a capability field or a NAMED PROFILE selected by one (`profiles.ts`), and `test/cli-registry-no-id-branching.test.ts` fails the build if an id check reappears — it matches `===`, `!==`, `case '<id>':` and `[...].includes(mode)`, because an earlier `===`-only version let 36 negated branches survive the conversion (including a seven-mode Ralph chain whose own comment asked the next person to keep it in step with `isExternalCliMode()` by hand). ⚠️ Config contains no shell text: an entry declares typed argv tokens, literals are validated against a safe-word pattern at LOAD time (a bad literal rejects the whole entry — a silently dropped `--no-approve` is not cosmetic), and values resolve through patterns NAMED in code, so a user `clis.json` cannot widen its own validation. ⚠️ `external`, `hooks` and `altScreen` are three INDEPENDENT capabilities on purpose; deriving one from another shipped the `until=stop`-hangs-on-shell bug. ⚠️ **`param` is TWO namespaces.** `launch.params` keys, `env.configSetenv[].fromParam` and `capabilities.privilegedParams[].param` all name a LAUNCH PARAM; the legacy `<Mode>Config` wire field is a separate namespace, bridged only by `launch.legacyConfigAliases`. Getting `privilegedParams[].param` wrong is SILENT — it is the multi-user bypass clamp's only handle on a CLI's privilege switch, and a wrong name clamps nothing with no load error and no failing test — so `schema.ts` rejects an entry naming a param it never declared. Codex is the entry where the two names differ (`bypassApprovals` vs `dangerouslyBypassApprovals`) and therefore the one that catches a regression. ⚠️ Six fields are DECLARED-FOR-LATER and read by nothing (`shortBadge`, `accent`, `capabilities.echo`/`wheelForward`/`keyboardAccessory`/`maxFrameBytes`): all frontend behaviour, transcribed rather than measured, so re-measure before wiring one up; the list is pinned so it cannot quietly grow. Spawn commands are pinned as literal strings in `test/cli-registry-spawn-golden.test.ts`, remote/docker pane commands in `test/location-overlay-commands.test.ts`. ⚠️ Anything reading the registry resolves it AT CALL TIME (`sessionModeSchema()`, `allowedEnvPrefixes()`, `dependencyRegistry()`, the resolvers' `searchDirs` thunks) — a module-level const freezes at first import, so a CLI enabled while the server ran moved the run menu but not that surface. `~/.codeman/clis.json` overrides any entry (read-only in this release; nothing writes it, so importing the registry has no filesystem side effects). → `docs/cli-registry.md`
+**CLI registry** (`src/config/cli-registry/`): every run mode is a `CliEntry` — discovery (search dirs, version + identity probes), the launch argv template, env handling, the `capabilities` flags that replace per-CLI branching, and the `overlays` that back the remote/docker pane commands. **No code outside `stock.ts` may branch on a CLI id**; behaviour that genuinely differs is either a capability field or a NAMED PROFILE selected by one (`profiles.ts`), and `test/cli-registry-no-id-branching.test.ts` fails the build if an id check reappears — it matches `===`, `!==`, `case '<id>':` and `[...].includes(mode)`, because an earlier `===`-only version let 36 negated branches survive the conversion (including a seven-mode Ralph chain whose own comment asked the next person to keep it in step with `isExternalCliMode()` by hand). ⚠️ Config contains no shell text: an entry declares typed argv tokens, literals are validated against a safe-word pattern at LOAD time (a bad literal rejects the whole entry — a silently dropped `--no-approve` is not cosmetic), and values resolve through patterns NAMED in code, so a user `clis.json` cannot widen its own validation. ⚠️ `external`, `hooks` and `altScreen` are three INDEPENDENT capabilities on purpose; deriving one from another shipped the `until=stop`-hangs-on-shell bug. ⚠️ Two capability fields carry a REGEX from config (`discovery.version.regex` and `capabilities.workDetect.workingLine`) and both must compile through `compileVersionRegex()`, which caps length and refuses nested quantifiers; `workingLine` is the one that runs on the PTY hot path. ⚠️ **`param` is TWO namespaces.** `launch.params` keys, `env.configSetenv[].fromParam` and `capabilities.privilegedParams[].param` all name a LAUNCH PARAM; the legacy `<Mode>Config` wire field is a separate namespace, bridged only by `launch.legacyConfigAliases`. Getting `privilegedParams[].param` wrong is SILENT — it is the multi-user bypass clamp's only handle on a CLI's privilege switch, and a wrong name clamps nothing with no load error and no failing test — so `schema.ts` rejects an entry naming a param it never declared. Codex is the entry where the two names differ (`bypassApprovals` vs `dangerouslyBypassApprovals`) and therefore the one that catches a regression. ⚠️ Six fields are DECLARED-FOR-LATER and read by nothing (`shortBadge`, `accent`, `capabilities.echo`/`wheelForward`/`keyboardAccessory`/`maxFrameBytes`): all frontend behaviour, transcribed rather than measured, so re-measure before wiring one up; the list is pinned so it cannot quietly grow. Spawn commands are pinned as literal strings in `test/cli-registry-spawn-golden.test.ts`, remote/docker pane commands in `test/location-overlay-commands.test.ts`. ⚠️ Anything reading the registry resolves it AT CALL TIME (`sessionModeSchema()`, `allowedEnvPrefixes()`, `dependencyRegistry()`, the resolvers' `searchDirs` thunks) — a module-level const freezes at first import, so a CLI enabled while the server ran moved the run menu but not that surface. `~/.codeman/clis.json` overrides any entry (read-only in this release; nothing writes it, so importing the registry has no filesystem side effects). → `docs/cli-registry.md`
 
-**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All eight **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. ⚠️ **Codex sessions use PREDICTIVE WRITE-THROUGH echo, never the buffer overlay** (`_localEchoPolicy` in `_updateLocalEchoState`, terminal-ui.js): codex's composer reacts per keystroke ("/" pops a live-filtering picker, arrows edit server-side state, the composer grows as it wraps), so buffer-until-Enter starved it into issues #218/#219/#220/#222 and stays disabled (`_localEchoEnabled` remains false for codex). Instead, `PredictiveEchoAddon` (separate `vendor/xterm-predictive-echo.js` bundle) paints each keystroke at the predicted cell while the wire path stays BYTE-IDENTICAL: the onData hook (`_predictHookOnData`) is a plain statement with no `return`, so control always falls through into the untouched send path — pinned by vm and E2E byte-identity tests. Predictions reconcile against the parsed buffer and only while the cursor sits on the measured composer row (`isCodexComposerRow`, `/^› /`). Codex also **drops keystrokes that share a PTY read with a bracketed paste**, so flushed text and the paste sequence must go out as separate delayed writes (mirroring the Enter branch's delayed `\r`). Tests: `test/local-echo-codex-gating.test.ts`, `test/codex-predictive-echo.test.ts` (E2E vs real codex), `packages/xterm-zerolag-input/test/codex-replay.test.ts`. ⚠️ **Pi is the opposite kind of CLI and needs the opposite instincts**: it has NO permission prompts and no sandbox, so there is no bypass flag to send and Codeman must not invent one; its privileged knob is the tri-state `approveProjectTrust` (`--approve`/`--no-approve`), which makes pi EXECUTE repo-local `.pi/extensions` TypeScript, so the multi-user clamp puts pi in the **materialize** branch (an absent config still yields `--no-approve` for a non-granted owner) and `--api-key` is never wired. Pi stays OUT of `isAltScreenStripMode()` (main-screen TUI, and its 0.84.0 fullscreen mode is runtime-switchable via `/settings`, where the alt screen is load-bearing), and lands on the `'buffer'` echo policy via the `_updateLocalEchoState` fallthrough. Pi's own tests: `test/pi-mode.test.ts`, `test/routes/external-cli-bypass-clamp.test.ts`; user guide `docs/pi-integration.md`. ⚠️ **Grok is codex-shaped on permissions but opencode-shaped on rendering**: its bypass switch is `alwaysApprove` (`--always-approve`, grok's `bypassPermissions` mode — the Run button sends it `true` like antigravity's, and the clamp's only-if-sent branch strips it for non-granted owners), while its fullscreen alt-screen TUI keeps it OUT of `isAltScreenStripMode()`; the resolver version-probes `grok --version` like pi's (npm squatters exist for the name — `GET /api/grok/status` surfaces path + version), and grok lands on the `'buffer'` echo policy via the fallthrough (UNMEASURED against a live authenticated session; if its composer turns out per-keystroke-reactive like codex, flip it to the `'off'` branch). Grok's own tests: `test/grok-mode.test.ts`, `test/grok-cli-resolver.test.ts`; user guide `docs/grok-integration.md`. ⚠️ **DeepSeek breaks three of this family's assumptions, so do not pattern-match it onto its siblings.** (1) The agent is a **PROFILE, not the binary**: `dsh` is a launcher over `$DSH_HOME/profiles/<name>` and DeepSeek ships only `web`/`headless`/`base`, so the terminal front door is ALWAYS third-party and "installed" ≠ "runnable" — the Run button gates on `isDeepSeekRunnable()` (binary AND a pane-capable profile) while `isDeepSeekAvailable()` gates the "add a profile" affordance; a `web`/`headless` profile is refused at spawn because it cannot drive a pane. (2) The permission switch is the **`DSH_PERMISSION_MODE` env export, not a flag** (`read-only`/`workspace-write`/`danger-full-access`) — the harness has none, and this is the one legitimate exception to the effort-style env-var ban because it is read with `??` as a boot-time default, so it stays soft; absent = `workspace-write`, which asks, hence the only-if-sent clamp branch, clamping to `workspace-write` (never `read-only`, which would break the workspace). ⚠️ **That clamp needs a second half no other CLI needs**, because the switch is an env var and `DSH_*` is an allowlisted `envOverrides` prefix: `applyEnvOverrides()` runs AFTER `_configureCliEnv()` in tmux-manager, so a non-granted owner sending `DSH_PERMISSION_MODE` on the SAME request would land last and hand back exactly the privilege the configLine truncated
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. ⚠️ **Work detection is no longer part of that gate**: it is per-CLI `capabilities.workDetect` data (see the ❯ note above), so a CLI that declares its own glyph and working line gets the same screen-probed idle confirmation claude gets, and one that declares neither keeps the output-stabilization behaviour. All eight **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. ⚠️ **Codex sessions use PREDICTIVE WRITE-THROUGH echo, never the buffer overlay** (`_localEchoPolicy` in `_updateLocalEchoState`, terminal-ui.js): codex's composer reacts per keystroke ("/" pops a live-filtering picker, arrows edit server-side state, the composer grows as it wraps), so buffer-until-Enter starved it into issues #218/#219/#220/#222 and stays disabled (`_localEchoEnabled` remains false for codex). Instead, `PredictiveEchoAddon` (separate `vendor/xterm-predictive-echo.js` bundle) paints each keystroke at the predicted cell while the wire path stays BYTE-IDENTICAL: the onData hook (`_predictHookOnData`) is a plain statement with no `return`, so control always falls through into the untouched send path — pinned by vm and E2E byte-identity tests. Predictions reconcile against the parsed buffer and only while the cursor sits on the measured composer row (`isCodexComposerRow`, `/^› /`). Codex also **drops keystrokes that share a PTY read with a bracketed paste**, so flushed text and the paste sequence must go out as separate delayed writes (mirroring the Enter branch's delayed `\r`). Tests: `test/local-echo-codex-gating.test.ts`, `test/codex-predictive-echo.test.ts` (E2E vs real codex), `packages/xterm-zerolag-input/test/codex-replay.test.ts`. ⚠️ **Pi is the opposite kind of CLI and needs the opposite instincts**: it has NO permission prompts and no sandbox, so there is no bypass flag to send and Codeman must not invent one; its privileged knob is the tri-state `approveProjectTrust` (`--approve`/`--no-approve`), which makes pi EXECUTE repo-local `.pi/extensions` TypeScript, so the multi-user clamp puts pi in the **materialize** branch (an absent config still yields `--no-approve` for a non-granted owner) and `--api-key` is never wired. Pi stays OUT of `isAltScreenStripMode()` (main-screen TUI, and its 0.84.0 fullscreen mode is runtime-switchable via `/settings`, where the alt screen is load-bearing), and lands on the `'buffer'` echo policy via the `_updateLocalEchoState` fallthrough. Pi's own tests: `test/pi-mode.test.ts`, `test/routes/external-cli-bypass-clamp.test.ts`; user guide `docs/pi-integration.md`. ⚠️ **Grok is codex-shaped on permissions but opencode-shaped on rendering**: its bypass switch is `alwaysApprove` (`--always-approve`, grok's `bypassPermissions` mode — the Run button sends it `true` like antigravity's, and the clamp's only-if-sent branch strips it for non-granted owners), while its fullscreen alt-screen TUI keeps it OUT of `isAltScreenStripMode()`; the resolver version-probes `grok --version` like pi's (npm squatters exist for the name — `GET /api/grok/status` surfaces path + version), and grok lands on the `'buffer'` echo policy via the fallthrough (UNMEASURED against a live authenticated session; if its composer turns out per-keystroke-reactive like codex, flip it to the `'off'` branch). Grok's own tests: `test/grok-mode.test.ts`, `test/grok-cli-resolver.test.ts`; user guide `docs/grok-integration.md`. ⚠️ **DeepSeek breaks three of this family's assumptions, so do not pattern-match it onto its siblings.** (1) The agent is a **PROFILE, not the binary**: `dsh` is a launcher over `$DSH_HOME/profiles/<name>` and DeepSeek ships only `web`/`headless`/`base`, so the terminal front door is ALWAYS third-party and "installed" ≠ "runnable" — the Run button gates on `isDeepSeekRunnable()` (binary AND a pane-capable profile) while `isDeepSeekAvailable()` gates the "add a profile" affordance; a `web`/`headless` profile is refused at spawn because it cannot drive a pane. (2) The permission switch is the **`DSH_PERMISSION_MODE` env export, not a flag** (`read-only`/`workspace-write`/`danger-full-access`) — the harness has none, and this is the one legitimate exception to the effort-style env-var ban because it is read with `??` as a boot-time default, so it stays soft; absent = `workspace-write`, which asks, hence the only-if-sent clamp branch, clamping to `workspace-write` (never `read-only`, which would break the workspace). ⚠️ **That clamp needs a second half Line truncated
 
 **DeepSeek web UI** (`POST`/`GET`/`DELETE /api/deepseek/web`, `deepseek-web-server.ts`): the Run menu's "DeepSeek web UI..." entry supervises ONE background `dsh web` child process, deliberately **NOT a shell session**. The session version worked and was still wrong in use: it put a terminal tab on screen next to the web tab the user actually asked for, every single time, and nothing about a long-lived HTTP server needs to be a tab. ⚠️ What a session gave for free now has to be paid for explicitly, and every piece is load-bearing: **exactly one** server (a second click REUSES it rather than racing it for a port, which two sessions structurally could not do), **restarted when the browser authority changes** (`--trusted-host` fences dsh's `/api` against the browser authority, and a Codeman reachable at both loopback and a tailnet name has two, so whoever asks last wins: the asker is by definition the origin about to load the page), **killed on shutdown** (`stopDeepSeekWeb()` in the server teardown, because the child is detached so its whole plugin tree can be signalled at once, which also means it would OUTLIVE Codeman and hold its port against the next start), and **failures returned to the caller**, since with no tab there is nowhere for a stack trace to land. ⚠️ The port search starts at dsh's own default 3080 and walks 40, never fixed: that default is precisely the port most likely to be taken already by the user's own `dsh web`, and hardcoding it killed this feature with EADDRINUSE once. Free-port detection BINDS rather than connects (a connect probe cannot tell "free" from "listening but not answering yet"), so it is racy by nature and the caller still waits for the server to really answer before reporting success. ⚠️ Both `POST` and `DELETE` sit at the **same privilege bar as the profile installer** (`canUsernameRunPrivilegedCommands`) even though the action reads as "open a page": booting a dsh profile executes the plugin code in it, and the server is a single shared instance, so stopping it in multi-user mode takes it out from under other users' tabs.
 
@@ -227,7 +231,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **PR bot** (`scripts/pr-bot/`, maintainer tooling, NOT part of the server; `docs/pr-bot.md`): a daemon (`codeman-pr-bot` user unit) that lists open PRs with `gh`, reviews each head commit once in a Codeman claude session named `prbot-<n>` running in a private `git clone --shared` under `~/.codeman/pr-bot/worktrees/` (a clone, NOT a linked worktree: Claude Code reads a linked worktree's project settings from the MAIN checkout, so its `opus[1m]` pin silently overrode the bot's `modelOverride`, measured), and reports verdict + ranked findings + recommendation to Telegram with buttons. ⚠️ It reviews on its own but **never writes to GitHub on its own**: merge / close / post-comment / approve-CI happen only from a Telegram command or button from the configured chat, and merge/close/post take a second confirmation tap (`runConfirmed` in `bot.ts` is the one write site). ⚠️ The shared checkout is never checked out or reset by it (it only fetches into `refs/pr-bot/<n>`, which also anchors the clone's objects against gc), a clone's `node_modules` is a SYMLINK into the main checkout unless the PR changes the lockfile (then the link is unlinked before `npm ci`), and `src/web/public/vendor` is copied per file, never linked, because postinstall regenerates it in place. Readiness/end-of-turn follow the codeman skill's rules (composer first, trust dialog read off the screen, `stop,blocked,exit` never `idle`). The Telegram token + chat id come from the existing notifier bot's `~/codeman-cases/telegram/.env`. Type-checked via `config/tsconfig.pr-bot.json` (part of `npm run typecheck`), linted/formatted with `src/`; tests `test/pr-bot-report.test.ts`, `test/pr-bot-state.test.ts`, `test/pr-bot-commands.test.ts` (the confirm-before-write flows against stubbed `gh`/Telegram).
 
-**Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows fold into their owning session via a `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
+**Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). ⚠️ **Transcript history is THREE stores, not one**, because each CLI keeps its conversations in its own: Claude's `~/.claude/projects`, omp's `~/.omp/agent/sessions` and codex's `~/.codex/sessions` (#386). Rows fold into their owning session via the `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice; that field is named for Claude and carries whatever id the CLI names its conversation with, which for every non-Claude row diverges from the Codeman id by construction. ⚠️ **`resumeId` is set by a SCANNER row only, never by a live session**, and that is what makes it safe to resume on: a row carrying one is a conversation already on disk, so `resumeHistorySession()` sends `codexConfig.resumeSessionId` and a row without one is a genuinely fresh session. Every surface that re-projects these rows has to carry the field through, the phone overview included, or a tap on that surface silently starts a second conversation. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
 
 **Owner tab layouts** (COD-359, `tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat tab strip, scoped per owner (`SINGLE_USER_LAYOUT_OWNER` = `@single` when multi-user is off), persisted under the `tabLayouts` key in state.json. A layout is `{version, groups[], ungrouped[], updatedAt}` whose refs point at either a session or a saved webview (`TabRefKind`), capped at 32 groups / 512 refs. ⚠️ **BACKEND ONLY as of 1.24.1**: nothing in `src/web/public/` calls these routes yet, so a UI built on top is new frontend work, not a rewiring job. ⚠️ **`TabLayoutService` is the single mutation boundary** and every lifecycle caller (session created/removed, webview created/deleted, a legacy order PUT) describes ONE completed server action and gets AT MOST ONE versioned write; writing layout state from a route or a manager directly is what the service exists to prevent. ⚠️ The layout does not replace `PUT /api/session-order`, it PROJECTS onto it: `tab-layout-legacy-order.ts` is the pure translation both ways (`putLegacyOrder()` recomposes a global order from the owner's groups), so changing one side without the other silently desyncs the tab strip from the stored layout. ⚠️ **Reconciliation is gated on a SUCCESSFUL restore** (`markRestorationComplete` / `markRestorationFailed` / `markRestorationSkipped`, plus `assertDeletionReady()`): pruning refs against a session list that failed to load would delete live tabs, so a failed restore must leave the layout untouched. `PUT` takes exactly `{baseVersion, layout}` (any other key shape is a validation error), answers a stale `baseVersion` with the current layout rather than clobbering, and is capped at 128 KiB. Broadcasts `tab:layoutChanged`, owner-routed via `deriveTabLayoutSseHint`.
 
@@ -364,7 +368,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### API Routes
 
-~227 handlers across 25 route files in `src/web/routes/`: system (56), sessions (34), cases (29), files (17), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), webviews (6 + the `/webview/:cap/*` proxy), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), approvals (4), readmymind (4), me (2), teams (2), tab-layout (2), search (1), hooks (1), clipboard (1), status-telemetry (1), voice (1 + the `/ws/voice/stream` relay), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~228 handlers across 25 route files in `src/web/routes/`: system (56), sessions (34), cases (30), files (17), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), webviews (6 + the `/webview/:cap/*` proxy), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), approvals (4), readmymind (4), me (2), teams (2), tab-layout (2), search (1), hooks (1), clipboard (1), status-telemetry (1), voice (1 + the `/ws/voice/stream` relay), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 **HTTP contract** (stable since 0.9.x, see `docs/versioning-policy.md`; full envelope/status/error-code/SSE spec in `docs/api-reference.md`): responses use the `ApiResponse<T>` envelope — `{ success: true, data? }` or `{ success: false, error, errorCode }` (`src/types/api.ts`). `/api/v1/*` is a versioned alias of `/api/*` (URL rewrite in `server.ts`).
 

docs/architecture-invariants.md

@@ -20,7 +20,7 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)
 
-**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini' || 'antigravity' || 'pi' || 'grok' || 'deepseek'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). All seven modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Antigravity specifics: command built by `buildAntigravityCommand()` (`--model`, `--conversation <id>` resume, `--dangerously-skip-permissions` from the `antigravityConfig` payload); availability via `GET /api/antigravity/status` — routes fail with `OPERATION_FAILED` + install hint (`curl -fsSL https://antigravity.google/cli/install.sh | bash`) when missing. Unlike the other three it is NOT an npm package (standalone binary, `~/.local/bin/agy`), which is why `docker/agent.Dockerfile` installs it with its own `--dir /usr/local/bin` step rather than in the `npm install -g` line, and why it does NOT join `isAltScreenStripMode()`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Agents & CLIs → Codex; Respawn/Ralph options are Claude-only, so session options open on the Session tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM). Grok specifics: command built by `buildGrokCommand()` (`--always-approve` from `grokConfig.alwaysApprove` — grok's `bypassPermissions` permission mode, deny rules still apply; `--model`; `--resume <id>` / `--continue`, id-regexed so grok's resume-by-TITLE feature can never put an arbitrary string on the spawn line); availability via `GET /api/grok/status`, which carries `version` because the resolver version-probes candidates (`grok` has npm squatters, e.g. @vibe-kit/grok-cli — `GROK_VERSION_REGEX` is shared with the dependency registry so doctor and run mode agree). Like antigravity it is a standalone binary (xAI installer → `~/.grok/bin`, symlinked into `~/.local/bin`), so `docker/agent.Dockerfile` installs it in its own step (copy to `/usr/local/bin`, drop root's `~/.grok` in the same layer) and it stays OUT of `isAltScreenStripMode()` (fullscreen alt-screen TUI with mouse support — the opencode case, not the Ink case). Env allowlist: `GROK_*` plus the vendor namespace `XAI_*` (`XAI_API_KEY` is grok's documented headless auth var — the same narrow-vendor-namespace reasoning as `GOOGLE_*` for gemini). Docker cred seeding is per-file (`auth.json`, `config.toml`, `pager.toml` from `~/.grok` — the dir also holds `sessions/`, `memory/`, and the ~160MB binary under `downloads/`). Grok tests: `test/grok-mode.test.ts`, `test/grok-cli-resolver.test.ts`.
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini' || 'antigravity' || 'pi' || 'grok' || 'deepseek'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). ⚠️ **Work detection left this gate in #385** and is now per-CLI `capabilities.workDetect` data (`promptGlyph` + `workingLine`), because gating it on the mode left every Codex session reporting `idle` for its entire life; a CLI declaring neither falls back to Claude's pair, which is logic-identical to the pre-registry behaviour. All seven modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Antigravity specifics: command built by `buildAntigravityCommand()` (`--model`, `--conversation <id>` resume, `--dangerously-skip-permissions` from the `antigravityConfig` payload); availability via `GET /api/antigravity/status` — routes fail with `OPERATION_FAILED` + install hint (`curl -fsSL https://antigravity.google/cli/install.sh | bash`) when missing. Unlike the other three it is NOT an npm package (standalone binary, `~/.local/bin/agy`), which is why `docker/agent.Dockerfile` installs it with its own `--dir /usr/local/bin` step rather than in the `npm install -g` line, and why it does NOT join `isAltScreenStripMode()`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Agents & CLIs → Codex; Respawn/Ralph options are Claude-only, so session options open on the Session tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM). Grok specifics: command built by `buildGrokCommand()` (`--always-approve` from `grokConfig.alwaysApprove` — grok's `bypassPermissions` permission mode, deny rules still apply; `--model`; `--resume <id>` / `--continue`, id-regexed so grok's resume-by-TITLE feature can never put an arbitrary string on the spawn line); availability via `GET /api/grok/status`, which carries `version` because the resolver version-probes candidates (`grok` has npm squatters, e.g. @vibe-kit/grok-cli — `GROK_VERSION_REGEX` is shared with the dependency registry so doctor and run mode agree). Like antigravity it is a standalone binary (xAI installer → `~/.grok/bin`, symlinked into `~/.local/bin`), so `docker/agent.Dockerfile` installs it in its own step (copy to `/usr/local/bin`, drop root's `~/.grok` in the same layer) and it stays OUT of `isAltScreenStripMode()` (fullscreen alt-screen TUI with mouse support — the opencode case, not the Ink case). Env allowlist: `GROK_*` plus the vendor namespace `XAI_*` (`XAI_API_KEY` is grok's documented headless auth var — the same narrow-vendor-namespace reasoning as `GOOGLE_*` for gemini). Docker cred seeding is per-file (`auth.json`, `config.toml`, `pager.toml` from `~/.grok` — the dir also holds `sessions/`, `memory/`, and the ~160MB binary under `downloads/`). Grok tests: `test/grok-mode.test.ts`, `test/grok-cli-resolver.test.ts`.
 
 **DeepSeek Harness (`dsh`) specifics** — the mode that breaks three of the assumptions the six above share, so read this before changing anything about it.
 
@@ -98,7 +98,7 @@ Tests: `test/docker-hosts.test.ts`, `test/docker-exec-options.test.ts`, `test/do
 
 ### Unified session list and Session Manager
 
-**Unified session list** (COD-160/#139): `GET /api/sessions/unified?limit=&q=` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows are keyed by conversation UUID and folded into their owning session via a `claudeSessionId → Codeman id` alias map (resumed//clear-respawned sessions must not appear twice); lifecycle name/mode resolution is first-seen-wins (the log returns entries NEWEST-first). No terminal buffers in the response (unlike `/api/sessions`). Consumed by the Cmd+K Session Manager (#146). Session Manager polish (COD-162/#157, 1.6.0): **pinning** via `POST /api/sessions/:id/pin` (`session:pinned` SSE; killing a pinned session demotes it to a lightweight stopped record that stays visible/resumable, and cleanup skips pinned records); **cross-device tab order** via `PUT /api/session-order` (`session:orderChanged` SSE, persisted in `state.json`; pure `normalizeSessionOrder`/`mergeSessionOrder` in `src/session-order.ts`: pushing device wins, server-only ids fall to the end, never dropped); resume from the manager keeps the original session name (COD-143); `firstPrompt` is backfilled for sessions whose id != transcript UUID and the most recent prompt (`lastPrompt`) is shown + searched (COD-140/145).
+**Unified session list** (COD-160/#139): `GET /api/sessions/unified?limit=&q=` merges live sessions, persisted state, lifecycle-log history, and transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). ⚠️ **Transcript history is three stores** (#386): Claude's `~/.claude/projects`, omp's `~/.omp/agent/sessions` and codex's `~/.codex/sessions`. Rows are keyed by whatever id that CLI names the conversation with and folded into their owning session via the `claudeSessionId → Codeman id` alias map (resumed//clear-respawned sessions must not appear twice; the field keeps its Claude-era name and is not Claude-only). A codex row additionally carries `resumeId`, the rollout's own thread id, set by the scanner and never by a live session, which is what lets a row be resumed through `codexConfig.resumeSessionId` while a row without one stays a fresh session; the alias chain therefore includes `config.codexConfig?.resumeSessionId`, and a fresh codex pane is matched by `session_meta.originator` (`codeman_<sessionId>` for every pane Codeman spawns); lifecycle name/mode resolution is first-seen-wins (the log returns entries NEWEST-first). No terminal buffers in the response (unlike `/api/sessions`). Consumed by the Cmd+K Session Manager (#146). Session Manager polish (COD-162/#157, 1.6.0): **pinning** via `POST /api/sessions/:id/pin` (`session:pinned` SSE; killing a pinned session demotes it to a lightweight stopped record that stays visible/resumable, and cleanup skips pinned records); **cross-device tab order** via `PUT /api/session-order` (`session:orderChanged` SSE, persisted in `state.json`; pure `normalizeSessionOrder`/`mergeSessionOrder` in `src/session-order.ts`: pushing device wins, server-only ids fall to the end, never dropped); resume from the manager keeps the original session name (COD-143); `firstPrompt` is backfilled for sessions whose id != transcript UUID and the most recent prompt (`lastPrompt`) is shown + searched (COD-140/145).
 
 ### Session lineage lines (tab → tab it spawned)
 

docs/cli-registry.md

@@ -36,12 +36,19 @@ interface CliEntry {
   launch: CliLaunch; // the structured argv template
   env: CliEnv; // exports, tmux setenv keys, the env-override allowlist
   capabilities: CliCapabilities; // what every call site reads instead of the id
+  //   .workDetect?: { promptGlyph, workingLine } — how this CLI's pane shows work
   overlays: CliOverlays; // remote-SSH / Docker pane commands, credential store
 }
 ```
 
 `capabilities` is the important part. It is what `isExternalCliMode()`, `isAltScreenStripMode()`, `hooksAvailableForMode()` and every other former per-mode branch actually read.
 
+### Regexes that come from config
+
+Two capability fields carry a regular expression an override file can set: `discovery.version.regex` and `capabilities.workDetect.workingLine`. Both go through `compileVersionRegex()`, which caps the source at 200 characters, refuses the nested-quantifier shapes that cause catastrophic backtracking, and returns `null` rather than throwing so every caller degrades instead of crashing.
+
+`workingLine` is the one that matters most, because it is compiled once per session and then run against every accumulated PTY chunk and every pane capture. A nested quantifier there is a ReDoS against the event loop for the whole server, not just that session. The guard therefore runs in two places, and neither is redundant: `schema.ts` rejects the entry at LOAD time so a bad pattern never reaches a session, and `_workingLinePattern()` in `session.ts` compiles through the same helper so the runtime cannot end up with a pattern the schema would have refused.
+
 ### Three capabilities that must stay independent
 
 `external`, `hooks` and `altScreen` describe three different, deliberately unequal sets, and deriving any one from another has already shipped a bug. `shell` has no hooks but is **not** an external CLI, so a hooks predicate written as `!isExternalCliMode()` accepted `until=stop` on a shell session and then blocked the caller for their entire timeout. `deepseek` is the mirror image: it IS external and it DOES have hooks.

package-lock.json

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

package.json

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

skills/codeman/SKILL.md

@@ -47,7 +47,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.21.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.22.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
@@ -75,8 +75,8 @@ PRE="${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh"
 mkdir -p "$(dirname "$PRE")"
 # Rewrite unless the file already ends with THIS version's stamp, so a stale or a
 # half-written file self-heals here instead of costing you a round trip to rm it.
-grep -qs '^CODEMAN_PREAMBLE=1.21.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
-# ---- Codeman agent preamble 1.21.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+grep -qs '^CODEMAN_PREAMBLE=1.22.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.22.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -96,7 +96,10 @@ AUTH=(); [ -n "${CODEMAN_PASSWORD:-}" ] && AUTH=(-u "${CODEMAN_USERNAME:-admin}:
 # draw the lineage. Set once here and every present and future create call carries it;
 # it is ignored on every other endpoint. Purely cosmetic (see §5.1) and it can never
 # fail a spawn, so there is no case where you would want to leave it off.
-CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF")
+# X-Codeman-Agent-Origin: marks a case directory a spawn CREATES as agent scratch, so the
+# user can find and delete it long after your workers are gone (§5.14). Same deal: set
+# once, cosmetic, never fails a spawn, and it labels only directories Codeman creates.
+CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF" -H "X-Codeman-Agent-Origin: codeman-skill")
 CID=codeman-agent-1            # FIXED literal, never "agent-$$": see below
 
 # Fail-CLOSED session delete. The DELETE lives INSIDE the guard on purpose: the older
@@ -322,10 +325,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.21.0
+CODEMAN_PREAMBLE=1.22.0
 PREAMBLE
 )
-. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.21.0 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
+. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.22.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
@@ -376,7 +379,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.21.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.22.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'
@@ -441,7 +444,8 @@ Four things this block leans on, each one link away, no detour needed to run it:
   strands the prompt on the composer until a bare `\r` follows: all three are reasons
   to let `sendwait` build the call rather than hand-rolling it.
 - Each `sendwait` costs that worker one billed turn, as does every prompt you send it.
-- Deleting the sessions does **not** remove the case directories: §5.14.
+- Deleting the sessions does **not** remove the case directories. They are marked as
+  agent-created, so `GET /api/v1/cases/agent-created` lists them for cleanup: §5.14.
 
 ### DeepSeek Harness workers
 
@@ -494,7 +498,7 @@ One row per job. Acting on this table alone is correct; the §5 links are the de
 | find yourself, list what exists | `GET /api/v1/sessions`, match your `$SELF` by **prefix** | [§5.11](reference/verbs.md#511-list-and-find-yourself) |
 | read or record what the user wants | `GET/PUT .../intent`, and `POST .../readmymind` to predict | [§5.12](reference/verbs.md#512-read-my-mind) |
 | talk to a claude worker directly | `ListAgents` / `SendMessage`, when the feature is on at both ends | [§5.13](reference/verbs.md#513-messaging-claude-workers) |
-| clean up | `delete_session "$SID"` per id you created. Case directories and git worktrees are **not** removed with it | [§5.14](reference/verbs.md#514-clean-up) |
+| clean up | `delete_session "$SID"` per id you created. Case directories and git worktrees are **not** removed with it; `GET /api/v1/cases/agent-created` lists the scratch case dirs your spawns left behind, for you to report | [§5.14](reference/verbs.md#514-clean-up) |
 
 ## 3. Rules digest
 
@@ -595,7 +599,7 @@ these**; open the one row you actually hit.
 | [5.11 List and find yourself](reference/verbs.md#511-list-and-find-yourself) | enumerate sessions, or match `$SELF` by prefix |
 | [5.12 Read My Mind](reference/verbs.md#512-read-my-mind) | read or record what the user wants for a case |
 | [5.13 Messaging claude workers](reference/verbs.md#513-messaging-claude-workers) | `ListAgents` / `SendMessage` instead of the HTTP path |
-| [5.14 Clean up](reference/verbs.md#514-clean-up) | what deleting a session does **not** remove |
+| [5.14 Clean up](reference/verbs.md#514-clean-up) | what deleting a session does **not** remove, and how to list the case dirs you left |
 
 ## 6. Setup and auth
 

skills/codeman/preamble.sh

@@ -1,4 +1,4 @@
-# ---- Codeman agent preamble 1.21.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# ---- Codeman agent preamble 1.22.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -18,7 +18,10 @@ AUTH=(); [ -n "${CODEMAN_PASSWORD:-}" ] && AUTH=(-u "${CODEMAN_USERNAME:-admin}:
 # draw the lineage. Set once here and every present and future create call carries it;
 # it is ignored on every other endpoint. Purely cosmetic (see §5.1) and it can never
 # fail a spawn, so there is no case where you would want to leave it off.
-CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF")
+# X-Codeman-Agent-Origin: marks a case directory a spawn CREATES as agent scratch, so the
+# user can find and delete it long after your workers are gone (§5.14). Same deal: set
+# once, cosmetic, never fails a spawn, and it labels only directories Codeman creates.
+CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF" -H "X-Codeman-Agent-Origin: codeman-skill")
 CID=codeman-agent-1            # FIXED literal, never "agent-$$": see below
 
 # Fail-CLOSED session delete. The DELETE lives INSIDE the guard on purpose: the older
@@ -244,4 +247,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.21.0
+CODEMAN_PREAMBLE=1.22.0

skills/codeman/reference/endpoints.md

@@ -364,6 +364,15 @@ the global 50, or the per-user 25 in multi-user mode, never the waiter cap),
 `CONFLICT`, `OPERATION_FAILED` and `INVALID_INPUT`. None of them are retryable in a
 loop.
 
+⚠️ A case directory quick-start **creates** for you is labelled agent-created (a
+`.codeman-agent-case.json` marker, written because the §0 preamble sends
+`X-Codeman-Agent-Origin`), which is what lets the user find it afterwards:
+`GET /api/v1/cases/agent-created` returns `.data.cases[]` of
+`{name, path, createdAt, createdBy, parentSessionId, inUse, modifiedAt}`, newest first,
+read-only, scoped to the caller's own case space. Report it when you finish; deleting is
+`DELETE /api/v1/cases/:name` and is the user's call by name ([§5.14](verbs.md#514-clean-up)).
+A directory that already existed is never labelled.
+
 ⚠️ `caseName` resolves through the linked-cases registry first, so a name that happens
 to match a case the user linked in lands in that **real repo**, not a fresh scratch
 directory. Pick distinctive scratch names, and use a linked name deliberately when you

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.18.3 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.22.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

skills/codeman/reference/verbs.md

@@ -731,6 +731,21 @@ Deleting a session ends the agent and its pane. It does **not** remove:
   it, and ask before running `git worktree remove`, which discards uncommitted work
   inside it.
 
+Those case directories are **labelled** rather than left anonymous. A directory
+`quick-start` creates for a spawn carrying the preamble's `X-Codeman-Agent-Origin`
+header gets a `.codeman-agent-case.json` marker, which is what puts it in the web UI's
+agent-case cleanup list (Add Case → Manage) and in:
+
+```bash
+"${CURL[@]}" "$API/api/v1/cases/agent-created" | jq -r '.data.cases[] | "\(.name)\t\(.createdAt)\tinUse=\(.inUse)"'
+```
+
+Read-only, scoped to the user's own case space, and `inUse` is true while a live
+session is still working in that directory. Report that list when you finish a run
+with workers, so the user knows exactly what to sweep; the deletion is still theirs to
+ask for by name. Only a directory Codeman **created** is ever labelled, so a linked
+case, a cloned repo or a worktree never appears there.
+
 Confirm cleanup with `GET /api/v1/sessions`, never with `/api/v1/sessions/unified`
 (that one folds in transcript history from the whole machine and will keep showing
 your worker forever).

src/agent-case-marker.ts

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview The marker file that records a case directory as one Codeman scaffolded
+ * FOR an agent-spawned session, so scratch worker workspaces can be told apart from the
+ * user's real projects long after the sessions that created them are gone.
+ *
+ * Why a file in the case directory rather than a central registry in `~/.codeman`:
+ * the thing being labelled is a directory on the user's disk, and the label has to
+ * survive everything that can happen to Codeman's own state (a wiped data dir, a
+ * different instance, a hand-moved case). A registry would also need stale-entry
+ * pruning and owner scoping of its own, while a marker is deleted by the same `rm -rf`
+ * that deletes the case, and is discoverable by a user who just runs `ls -a`.
+ *
+ * ⚠️ Written ONLY on the path that CREATES the directory (`POST /api/quick-start`'s
+ * `!existsSync` branch). A linked case, a cloned repo, a git worktree or any other
+ * pre-existing directory must never be labelled agent-created: the label drives a
+ * cleanup affordance, and mislabelling someone's repo there is the one failure mode
+ * that costs real work. `POST /api/sessions` takes an existing `workingDir` and so
+ * writes no marker at all, by construction.
+ *
+ * ⚠️ Reading is strict and total: anything that does not parse as a version-1 marker
+ * (truncated write, hand-edited junk, a user's unrelated file of the same name) reads
+ * as "not agent-created" rather than as a partially-trusted entry. A marker is
+ * metadata; deleting the file is the supported way to adopt a scratch case as a real
+ * one, which is what the `note` field written into it tells the user.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Marker filename inside the case directory. Dot-prefixed so it stays out of the way. */
+export const AGENT_CASE_MARKER_FILE = '.codeman-agent-case.json';
+
+/** Current marker schema version. A marker of any other version reads as absent. */
+export const AGENT_CASE_MARKER_VERSION = 1;
+
+/**
+ * Origin recorded when a create request carried a resolvable spawning session but no
+ * explicit origin of its own (an agent driving the API by hand, or an older copy of
+ * the skill). Nothing in the browser UI sets lineage, so this really does mean "another
+ * session spawned this", not "a human clicked Run".
+ */
+export const AGENT_ORIGIN_SPAWNED_BY_SESSION = 'agent-session';
+
+/** Origin the packaged agent skill sends on its shared curl invocation. */
+export const AGENT_ORIGIN_CODEMAN_SKILL = 'codeman-skill';
+
+/** Longest accepted origin token (the value is echoed into the UI and the marker). */
+const MAX_ORIGIN_LENGTH = 32;
+
+/** Longest accepted free-text field read back out of a marker. */
+const MAX_MARKER_FIELD_LENGTH = 200;
+
+/** Lowercase token: what an origin may look like on the wire and on disk. */
+const AGENT_ORIGIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** Explains the file to whoever finds it in their case directory. */
+const MARKER_NOTE =
+  'Created by a Codeman agent worker (see the Manage tab in Add Case). ' +
+  'Delete this file to keep the case out of the agent-case cleanup list; ' +
+  'deleting the whole directory removes the case.';
+
+/**
+ * What a case directory records about the agent spawn that created it.
+ * Every field beyond `version`/`createdAt`/`createdBy` is decoration for the cleanup UI.
+ */
+export interface AgentCaseMarker {
+  version: typeof AGENT_CASE_MARKER_VERSION;
+  /** ISO timestamp of the spawn that created the directory. */
+  createdAt: string;
+  /** Who asked: `codeman-skill`, `agent-session`, or another caller's own token. */
+  createdBy: string;
+  /** Full id of the session that spawned the worker, when one resolved. */
+  parentSessionId?: string;
+  /** That session's display name at spawn time, so the user recognises it later. */
+  parentSessionName?: string;
+  /** Run mode the worker was started in (`claude`, `deepseek`, …). */
+  mode?: string;
+  /** Owner the case was created for, in multi-user mode. */
+  owner?: string;
+}
+
+/**
+ * Validate an origin token coming off the wire (`agentOrigin` body field or the
+ * `X-Codeman-Agent-Origin` header). Returns `undefined` for anything that is not a
+ * short lowercase token — the value reaches the UI and a JSON file, so it is
+ * allowlisted rather than escaped at each use.
+ */
+export function normalizeAgentOrigin(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const value = raw.trim().toLowerCase();
+  if (!value || value.length > MAX_ORIGIN_LENGTH) return undefined;
+  return AGENT_ORIGIN_PATTERN.test(value) ? value : undefined;
+}
+
+/** Trim an optional free-text marker field to something safe to store and render. */
+function normalizeField(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const value = raw.trim();
+  return value ? value.slice(0, MAX_MARKER_FIELD_LENGTH) : undefined;
+}
+
+/**
+ * Build a marker from a spawn's details. Pure, so the route can hand it straight to
+ * the writer and the tests can assert on the shape without touching a disk.
+ */
+export function buildAgentCaseMarker(input: {
+  createdBy: string;
+  createdAt?: Date;
+  parentSessionId?: string;
+  parentSessionName?: string;
+  mode?: string;
+  owner?: string;
+}): AgentCaseMarker {
+  const marker: AgentCaseMarker = {
+    version: AGENT_CASE_MARKER_VERSION,
+    createdAt: (input.createdAt ?? new Date()).toISOString(),
+    createdBy: normalizeAgentOrigin(input.createdBy) ?? AGENT_ORIGIN_SPAWNED_BY_SESSION,
+  };
+  const parentSessionId = normalizeField(input.parentSessionId);
+  const parentSessionName = normalizeField(input.parentSessionName);
+  const mode = normalizeField(input.mode);
+  const owner = normalizeField(input.owner);
+  if (parentSessionId) marker.parentSessionId = parentSessionId;
+  if (parentSessionName) marker.parentSessionName = parentSessionName;
+  if (mode) marker.mode = mode;
+  if (owner) marker.owner = owner;
+  return marker;
+}
+
+/**
+ * Parse marker JSON. Returns `null` for anything that is not a well-formed version-1
+ * marker, including a valid-JSON object of the wrong shape — see the strictness note
+ * in the file header.
+ */
+export function parseAgentCaseMarker(raw: string): AgentCaseMarker | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+
+  const record = value as Record<string, unknown>;
+  if (record.version !== AGENT_CASE_MARKER_VERSION) return null;
+
+  const createdAt = normalizeField(record.createdAt);
+  const createdBy = normalizeAgentOrigin(record.createdBy);
+  if (!createdAt || !createdBy || Number.isNaN(Date.parse(createdAt))) return null;
+
+  return buildAgentCaseMarker({
+    createdBy,
+    createdAt: new Date(createdAt),
+    parentSessionId: normalizeField(record.parentSessionId),
+    parentSessionName: normalizeField(record.parentSessionName),
+    mode: normalizeField(record.mode),
+    owner: normalizeField(record.owner),
+  });
+}
+
+/**
+ * Write the marker into `casePath`. Best-effort by design: the marker is metadata for
+ * a later cleanup, and a failed write must never fail the worker spawn that is the
+ * point of the request. Returns whether it landed.
+ */
+export async function writeAgentCaseMarker(casePath: string, marker: AgentCaseMarker): Promise<boolean> {
+  try {
+    const body = JSON.stringify({ ...marker, note: MARKER_NOTE }, null, 2);
+    await writeFile(join(casePath, AGENT_CASE_MARKER_FILE), `${body}\n`, 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read the marker out of `casePath`, or `null` if there isn't a valid one. */
+export async function readAgentCaseMarker(casePath: string): Promise<AgentCaseMarker | null> {
+  try {
+    return parseAgentCaseMarker(await readFile(join(casePath, AGENT_CASE_MARKER_FILE), 'utf-8'));
+  } catch {
+    return null;
+  }
+}

src/codex-transcript.ts

@@ -0,0 +1,393 @@
+/**
+ * @fileoverview Scan `~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl` for Past
+ * Sessions rows, the codex analog of what `scanOmpSessionsHistory()`
+ * (omp-transcript.ts) does for omp and `scanProjectDir()` (session-routes.ts)
+ * does for Claude's own `~/.claude/projects` transcripts.
+ *
+ * Without this a codex conversation is invisible to Codeman the moment its
+ * session record goes away, even though codex itself never forgot it: the
+ * unified list is built from `~/.claude/projects` plus omp's own store, and
+ * codex writes to neither. A user who wanted to pick a codex thread back up had
+ * to find its id by hand and pass `codexConfig.resumeSessionId` to the API.
+ *
+ * ## Why this reads windows rather than whole files
+ *
+ * An omp session file is the conversation only, so its scanner reads each file
+ * whole. A codex rollout is not comparable: it carries every reasoning block and
+ * every tool call, and its `session_meta` line alone embeds the full base
+ * instructions. Measured on a real store of 519 rollouts, the median file is
+ * 407 KiB, the 90th percentile 1.3 MiB and the largest 25 MiB, for 381 MiB in
+ * total. So this reads a head window for the identity and the opening prompt,
+ * and a tail window for the most recent one.
+ *
+ * The head budget is 128 KiB because `session_meta` runs to roughly 19 KiB and
+ * the first real user message lands near 69 KiB behind it, both measured on
+ * codex 0.152.1.
+ *
+ * ## Where the prompt text comes from
+ *
+ * Codex has emitted user input under three shapes, and this reads all of them,
+ * preferring the ones that carry real input only:
+ *
+ *  - `event_msg` / `item_completed` with an `item.type` of `UserMessage`, which
+ *    is what codex 0.152.1 writes.
+ *  - `event_msg` / `user_message`, which older versions wrote.
+ *  - `response_item` rows with `role: 'user'`, the last resort. These mix real
+ *    input with injected context (AGENTS.md, environment context, compaction
+ *    summaries), so they are read only when neither shape above appears, and
+ *    the obvious injections are dropped.
+ *
+ * @module codex-transcript
+ */
+
+import { open, readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { LRUMap } from './utils/lru-map.js';
+
+/** Covers `session_meta` (~19 KiB) plus the first user message (~69 KiB behind it). */
+const HEAD_BYTES = 131072;
+
+/** Enough to hold the last few turns' worth of lines without re-reading the file. */
+const TAIL_BYTES = 65536;
+
+/**
+ * Newest rollouts to REPORT. Counted in emitted rows, not files scanned: the
+ * store is mostly sub-agent threads this never returns, so capping files first
+ * would spend the budget on rows nobody sees.
+ */
+const MAX_ROLLOUTS = 400;
+
+/**
+ * How many emitted rows also get a tail read for `lastPrompt`. The head read is
+ * cached (see below) but the tail cannot be, because appending to a rollout is
+ * exactly what changes it, so this is the one genuinely per-request cost and it
+ * stays bounded. Counted in emitted rows for the same reason as above — against
+ * file index a store of sub-agent threads spends the whole budget before the
+ * first row that needed it.
+ */
+const MAX_TAIL_READS = 100;
+
+/** Directory nesting under `sessions/` is year/month/day; stop well past that. */
+const MAX_WALK_DEPTH = 5;
+
+/** A rollout shorter than this cannot hold a complete `session_meta` line. */
+const MIN_ROLLOUT_BYTES = 100;
+
+export interface CodexHistorySession {
+  /** The rollout's own thread id — the token `codex resume <id>` expects. */
+  sessionId: string;
+  /**
+   * `session_meta.originator`, which codex stamps from
+   * CODEX_INTERNAL_ORIGINATOR_OVERRIDE — `codeman_<sessionId>` for every pane
+   * Codeman spawns. The only link between a FRESH codex pane and the rollout it
+   * is writing, since such a pane knows no thread id of its own.
+   */
+  originator?: string;
+  workingDir: string;
+  sizeBytes: number;
+  /** ISO timestamp, from the file's own mtime. */
+  lastModified: string;
+  firstPrompt?: string;
+  lastPrompt?: string;
+}
+
+/** The half of a rollout that never changes once codex has written it. */
+interface RolloutIdentity {
+  threadId?: string;
+  cwd?: string;
+  /** `'subagent'` marks a thread codex spawned for itself. */
+  threadSource?: string;
+  /** `codeman_<sessionId>` for a pane Codeman spawned; codex's own default otherwise. */
+  originator?: string;
+  firstPrompt?: string;
+}
+
+/**
+ * `session_meta` is written once and never rewritten — the same fact
+ * `readCodexRolloutMetaCached()` in session-routes.ts relies on — so a path's
+ * identity is cached, and a rescan costs a `stat` per file plus head reads for
+ * rollouts this process has not seen before.
+ *
+ * ⚠️ The first user message is NOT written up front: codex writes it when the
+ * user submits. Caching before then pins `firstPrompt: undefined` for the life
+ * of the process, and every scan of the home screen, the command palette and the
+ * search-index refresh can land in that window — so the row reads as having no
+ * prompt until a restart. `shouldCacheIdentity()` is the guard.
+ *
+ * Bounded, unlike a plain Map: this process runs for days and every sub-agent
+ * rollout adds an entry. Same reason and same size as `codexRolloutMetaCache`.
+ */
+const identityCache = new LRUMap<string, RolloutIdentity>({ maxSize: 4096 });
+
+/**
+ * Is this identity settled enough to keep?
+ *
+ * A known `firstPrompt` settles it. So does a head read that FILLED its window,
+ * which means the prompt is genuinely not in the first `HEAD_BYTES` rather than
+ * not written yet. A short file with no prompt is the ambiguous case — codex is
+ * still to write one — so that one is re-read next scan.
+ */
+function shouldCacheIdentity(identity: RolloutIdentity, fileSize: number): boolean {
+  if (!identity.threadId) return false;
+  return identity.firstPrompt !== undefined || fileSize >= HEAD_BYTES;
+}
+
+function codexSessionsRoot(): string {
+  const home = process.env.CODEX_HOME || join(homedir(), '.codex');
+  return join(home, 'sessions');
+}
+
+/** Read at most `bytes` from the front of a file. Returns '' when unreadable. */
+async function readHead(path: string, bytes: number): Promise<string> {
+  const fh = await open(path, 'r').catch(() => null);
+  if (!fh) return '';
+  try {
+    const buf = Buffer.alloc(bytes);
+    const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+    return buf.subarray(0, bytesRead).toString('utf-8');
+  } catch {
+    return '';
+  } finally {
+    await fh.close().catch(() => {});
+  }
+}
+
+/**
+ * Read at most `bytes` from the end of a file, dropping the leading partial
+ * line so every line handed back parses.
+ */
+async function readTail(path: string, size: number, bytes: number): Promise<string> {
+  const fh = await open(path, 'r').catch(() => null);
+  if (!fh) return '';
+  try {
+    const want = Math.min(bytes, size);
+    const buf = Buffer.alloc(want);
+    const { bytesRead } = await fh.read(buf, 0, want, size - want);
+    const text = buf.subarray(0, bytesRead).toString('utf-8');
+    if (want >= size) return text; // whole file, nothing was cut
+    const nl = text.indexOf('\n');
+    return nl === -1 ? '' : text.slice(nl + 1);
+  } catch {
+    return '';
+  } finally {
+    await fh.close().catch(() => {});
+  }
+}
+
+/** Flatten codex's message content, which is a string or an array of text blocks. */
+function contentText(content: unknown): string {
+  if (typeof content === 'string') return content.trim();
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter(
+      (b): b is { text: string } => !!b && typeof b === 'object' && typeof (b as { text?: unknown }).text === 'string'
+    )
+    .map((b) => b.text)
+    .join('\n')
+    .trim();
+}
+
+/** One line's user-prompt text, whichever of the three shapes it is. */
+function userPromptFromLine(entry: {
+  type?: string;
+  payload?: {
+    type?: string;
+    role?: string;
+    content?: unknown;
+    message?: unknown;
+    item?: { type?: string; content?: unknown };
+  };
+}): { text: string; injectionProne: boolean } | null {
+  const p = entry.payload;
+  if (!p) return null;
+
+  if (entry.type === 'event_msg' && p.type === 'item_completed' && p.item?.type === 'UserMessage') {
+    const text = contentText(p.item.content);
+    return text ? { text, injectionProne: false } : null;
+  }
+  if (entry.type === 'event_msg' && p.type === 'user_message') {
+    const text = typeof p.message === 'string' ? p.message.trim() : contentText(p.message);
+    return text ? { text, injectionProne: false } : null;
+  }
+  if (entry.type === 'response_item' && p.role === 'user') {
+    const text = contentText(p.content);
+    return text ? { text, injectionProne: true } : null;
+  }
+  return null;
+}
+
+/**
+ * Injected context rather than something the user typed. Codex prepends the
+ * repository's AGENTS.md and wraps environment context in a tag, and both arrive
+ * as `response_item` user rows.
+ */
+function isInjectedContext(text: string): boolean {
+  return text.startsWith('#') || text.startsWith('<');
+}
+
+/** Collapse to one line and cap, so a row carries a title rather than an essay. */
+function asPreview(text: string): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > 200 ? `${flat.slice(0, 200)}…` : flat;
+}
+
+/** Parse a head window into the facts about a rollout that never change. */
+function parseIdentity(head: string): RolloutIdentity {
+  const out: RolloutIdentity = {};
+  let fallback: string | undefined;
+  for (const line of head.split('\n')) {
+    if (!line) continue;
+    let entry: {
+      type?: string;
+      payload?: {
+        id?: string;
+        session_id?: string;
+        cwd?: string;
+        thread_source?: string;
+        originator?: string;
+        type?: string;
+        role?: string;
+        content?: unknown;
+        message?: unknown;
+        item?: { type?: string; content?: unknown };
+      };
+    };
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // truncated tail of the window, or a malformed line
+    }
+    const p = entry.payload;
+    if (entry.type === 'session_meta' && p) {
+      out.threadId ??= p.id || p.session_id;
+      out.cwd ??= p.cwd;
+      out.threadSource ??= p.thread_source;
+      out.originator ??= p.originator;
+    } else if (entry.type === 'turn_context' && p) {
+      out.cwd ??= p.cwd;
+    }
+    if (out.firstPrompt) continue;
+    const prompt = userPromptFromLine(entry);
+    if (!prompt) continue;
+    if (!prompt.injectionProne) {
+      out.firstPrompt = asPreview(prompt.text);
+    } else if (!fallback && !isInjectedContext(prompt.text)) {
+      fallback = asPreview(prompt.text);
+    }
+  }
+  out.firstPrompt ??= fallback;
+  return out;
+}
+
+/** The most recent user prompt in a tail window, or undefined. */
+function parseLastPrompt(tail: string): string | undefined {
+  let best: string | undefined;
+  let fallback: string | undefined;
+  for (const line of tail.split('\n')) {
+    if (!line) continue;
+    try {
+      const prompt = userPromptFromLine(JSON.parse(line));
+      if (!prompt) continue;
+      if (!prompt.injectionProne) best = asPreview(prompt.text);
+      else if (!isInjectedContext(prompt.text)) fallback = asPreview(prompt.text);
+    } catch {
+      // Malformed line — keep scanning.
+    }
+  }
+  return best ?? fallback;
+}
+
+/** Every rollout file under `sessions/`, newest first. */
+async function listRollouts(root: string): Promise<Array<{ path: string; mtimeMs: number; size: number }>> {
+  const files: Array<{ path: string; mtimeMs: number; size: number }> = [];
+  const walk = async (dir: string, depth: number): Promise<void> => {
+    if (depth > MAX_WALK_DEPTH) return;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries) return;
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+      const st = await stat(full).catch(() => null);
+      if (!st || st.size < MIN_ROLLOUT_BYTES) continue;
+      files.push({ path: full, mtimeMs: st.mtimeMs, size: st.size });
+    }
+  };
+  await walk(root, 0);
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return files;
+}
+
+/**
+ * Codex conversations on this host, newest first, for the unified session list.
+ *
+ * Sub-agent threads are left out: codex spawns them for itself, they are not
+ * something a person picks back up, and on a real store they outnumber the
+ * threads that are.
+ */
+export async function scanCodexSessionsHistory(): Promise<CodexHistorySession[]> {
+  const files = await listRollouts(codexSessionsRoot());
+  const out: CodexHistorySession[] = [];
+
+  for (const file of files) {
+    if (out.length >= MAX_ROLLOUTS) break;
+
+    let identity = identityCache.get(file.path);
+    if (!identity) {
+      identity = parseIdentity(await readHead(file.path, HEAD_BYTES));
+      if (shouldCacheIdentity(identity, file.size)) identityCache.set(file.path, identity);
+    }
+    if (!identity.threadId || identity.threadSource === 'subagent') continue;
+    // A row with no directory has nowhere to resume INTO, and emitting an empty
+    // one makes a click post `workingDir: ''`. omp drops such a row; so does this.
+    if (!identity.cwd) continue;
+
+    const lastPrompt =
+      out.length < MAX_TAIL_READS ? parseLastPrompt(await readTail(file.path, file.size, TAIL_BYTES)) : undefined;
+
+    out.push({
+      sessionId: identity.threadId,
+      originator: identity.originator,
+      workingDir: identity.cwd,
+      sizeBytes: file.size,
+      lastModified: new Date(file.mtimeMs).toISOString(),
+      firstPrompt: identity.firstPrompt,
+      lastPrompt: lastPrompt ?? identity.firstPrompt,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Which codex thread each Codeman-spawned pane is writing, keyed by Codeman
+ * session id.
+ *
+ * Codeman spawns every codex pane with
+ * CODEX_INTERNAL_ORIGINATOR_OVERRIDE=codeman_<sessionId>, and codex stamps that
+ * into `session_meta.originator`. That is the ONLY link between a fresh codex
+ * pane and the rollout it is writing: such a pane knows no thread id of its own,
+ * so it cannot be folded into its own Past-Sessions row from its own side.
+ *
+ * Newest wins. `/new` typed inside the codex TUI leaves several rollouts sharing
+ * one originator, and the pane is on the most recent — so this expects `rows`
+ * newest-first, as `scanCodexSessionsHistory()` returns them.
+ */
+export function codexThreadBySessionId(rows: CodexHistorySession[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const row of rows) {
+    const owner = /^codeman_(.+)$/.exec(row.originator ?? '')?.[1];
+    if (owner && !out.has(owner)) out.set(owner, row.sessionId);
+  }
+  return out;
+}
+
+/** Test seam: drop the per-path identity cache. */
+export function __clearCodexIdentityCache(): void {
+  identityCache.clear();
+}

src/config/cli-registry/schema.ts

@@ -13,7 +13,7 @@
  */
 
 import { z } from 'zod';
-import { TOKEN_PATTERNS } from './patterns.js';
+import { compileVersionRegex, TOKEN_PATTERNS } from './patterns.js';
 import { isKnownLauncherProfile, isKnownSetenvProfile } from './profiles.js';
 
 /** A bare CLI id: lowercase, starts with a letter, at most 24 chars. Also used as a CSS/URL token. */
@@ -274,6 +274,23 @@ const capabilitiesSchema = z
     effort: z.boolean(),
     agentSkillInjection: z.boolean(),
     statusLineTelemetry: z.boolean(),
+    workDetect: z
+      .object({
+        promptGlyph: z.string().min(1).max(8),
+        // Config-supplied regex, so it goes through the same guard as `version.regex`:
+        // ~/.codeman/clis.json can set this, and the compiled pattern runs on the PTY
+        // hot path, where a nested quantifier would be a ReDoS against the event loop.
+        // A broken pattern must also fail at LOAD time rather than inside a data handler.
+        workingLine: z
+          .string()
+          .min(1)
+          .refine(
+            (src) => compileVersionRegex(src) !== null,
+            'workingLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
+          ),
+      })
+      .strict()
+      .optional(),
     model: z
       .object({ source: z.enum(['flag', 'claude-settings-file', 'none']), param: z.string().optional() })
       .strict(),

src/config/cli-registry/stock.ts

@@ -183,6 +183,13 @@ const CLAUDE: CliEntry = {
   },
   capabilities: {
     external: false,
+    // The historical hard-coded pair, now stated as data. `workingLine` matches both the
+    // `✻ Actualizing… (39s · ↓ 2.0k tokens)` status line and the bare `esc to interrupt`
+    // footer, because tmux repaints partially and only one of the two may land in a chunk.
+    workDetect: {
+      promptGlyph: '❯',
+      workingLine: String.raw`…\s*\((?:\d+h\s+)?(?:\d+m\s+)?\d+s\b|esc to interrupt`,
+    },
     requiresMux: false,
     // Claude installs Codeman's own hooks block into every workspace it runs in, so its
     // stop/idle signals are unconditional — no per-session veto, unlike deepseek's bridge.
@@ -418,6 +425,11 @@ const CODEX: CliEntry = {
   },
   capabilities: {
     ...agentDefaults(),
+    // Codex draws `› Ask Codex to do anything` on its composer row and
+    // `Working (2m 49s • esc to interrupt)` above it while a turn runs. It animates no
+    // braille spinner, and it never prints `esc to interrupt` at rest, so that phrase
+    // alone separates a running turn from an idle one.
+    workDetect: { promptGlyph: '›', workingLine: '[Ee]sc to interrupt' },
     transcript: 'codex-rollout',
     altScreen: 'strip-full',
     echo: { policy: 'predict', anchor: { kind: 'cursor' }, predictProfile: 'codex' },

src/config/cli-registry/types.ts

@@ -306,6 +306,29 @@ export interface CliCapabilities {
    * independent — see this interface's own doc comment.
    */
   external: boolean;
+  /**
+   * How to read this CLI's own TUI for whether it is mid-turn.
+   *
+   * Codeman infers a working agent from the pane, so the two strings it needs are the
+   * ones that differ per CLI: the glyph on the composer row, and the status line the CLI
+   * draws while a turn runs. Holding them here is what lets a non-Claude CLI report work
+   * at all — `external` used to gate the whole detector, so every external CLI reported
+   * itself permanently idle even mid-turn.
+   *
+   * `promptGlyph` only ARMS the idle confirmation and is never on its own evidence that a
+   * turn ended, because a CLI redraws its composer throughout a turn. `workingLine` is
+   * the evidence, and `_confirmIdle` consults it before believing the pane went quiet.
+   *
+   * An entry that omits this field keeps Codeman's historical behaviour: the Claude glyph
+   * arms the confirmation and the Claude working line answers it. Leave it out for a CLI
+   * whose TUI nobody has characterised, and its sessions report work exactly as before.
+   */
+  workDetect?: {
+    /** The glyph this CLI draws on its composer row, e.g. Claude's `❯`, Codex's `›`. */
+    promptGlyph: string;
+    /** Source of a regex matching the status line this CLI draws while a turn runs. */
+    workingLine: string;
+  };
   /** No direct-PTY fallback: the CLI must run inside tmux (secrets ride tmux setenv). */
   requiresMux: boolean;
   /**

src/hooks-config.ts

@@ -1066,9 +1066,80 @@ export async function installAgentSkillInto(skillDir: string): Promise<AgentSkil
  */
 export async function seedAgentSessionPreamble(sessionId: string): Promise<void> {
   const content = await readFile(join(agentSkillSourceDir(), 'preamble.sh'), 'utf-8');
-  const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
-  await mkdir(cacheDir, { recursive: true });
-  await writeFile(join(cacheDir, `codeman-agent-${sessionId}.sh`), content, { mode: 0o600 });
+  await mkdir(agentPreambleCacheDir(), { recursive: true });
+  await writeFile(agentPreamblePath(sessionId), content, { mode: 0o600 });
+}
+
+/** Where the preamble caches live. One formula, shared by seed / remove / prune. */
+function agentPreambleCacheDir(): string {
+  return process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+}
+
+/** `codeman-agent-<sessionId>.sh` in that directory. */
+function agentPreamblePath(sessionId: string): string {
+  return join(agentPreambleCacheDir(), `codeman-agent-${sessionId}.sh`);
+}
+
+/** Matches exactly what seedAgentSessionPreamble writes, and nothing else in ~/.cache. */
+const AGENT_PREAMBLE_FILE_PATTERN = /^codeman-agent-(.+)\.sh$/;
+
+/** How long a preamble cache with no live session behind it is kept before the sweep takes it. */
+export const AGENT_PREAMBLE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Drop one session's preamble cache. Called when a session is deleted, which is the
+ * precise counterpart to seeding it at create: one file per claude session was being
+ * written and nothing ever removed them (236 leftovers measured on a working machine,
+ * the oldest three weeks old). Best-effort — a file that will not delete is litter,
+ * never a reason to fail a teardown.
+ */
+export async function removeAgentSessionPreamble(sessionId: string): Promise<void> {
+  await unlink(agentPreamblePath(sessionId)).catch(() => {});
+}
+
+/**
+ * Sweep preamble caches left by sessions that are gone: the delete path above covers
+ * an orderly teardown, and this covers everything else (a crash, a killed server, a
+ * session deleted by an older build, another instance's leftovers).
+ *
+ * ⚠️ Two guards, and both matter: a file whose session is in `keepSessionIds` is never
+ * touched however old it is, and everything else needs `maxAgeMs` of age on top. A live
+ * session's cache is load-bearing — remove it and the skill's two-line loader fails its
+ * version check mid-run — and the age floor is what keeps a session belonging to
+ * ANOTHER instance (whose ids this process cannot see) out of the blast radius. Losing
+ * one is degradation rather than breakage: the §0 fallback block rewrites it.
+ *
+ * Returns how many it removed. Best-effort throughout; a missing cache dir is 0.
+ */
+export async function pruneAgentSessionPreambles(
+  keepSessionIds: Iterable<string>,
+  maxAgeMs: number = AGENT_PREAMBLE_MAX_AGE_MS
+): Promise<number> {
+  const cacheDir = agentPreambleCacheDir();
+  const keep = new Set(keepSessionIds);
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+
+  let entries: string[];
+  try {
+    entries = await readdir(cacheDir);
+  } catch {
+    return 0;
+  }
+
+  for (const entry of entries) {
+    const sessionId = AGENT_PREAMBLE_FILE_PATTERN.exec(entry)?.[1];
+    if (!sessionId || keep.has(sessionId)) continue;
+    const path = join(cacheDir, entry);
+    try {
+      if ((await lstat(path)).mtimeMs > cutoff) continue;
+      await unlink(path);
+      removed++;
+    } catch {
+      /* best-effort — a vanished or unreadable file is not our problem */
+    }
+  }
+  return removed;
 }
 
 /**

src/services/unified-session-service.ts

@@ -2,12 +2,16 @@
  * @fileoverview Pure merge/filter logic for the unified session list (COD-121).
  *
  * Combines four read-only views of a session — live (in-memory `Session`),
- * persisted (`state.json`), transcript history (`~/.claude/projects`), and the
- * lifecycle audit log — plus mux process stats, into one de-duplicated list
- * keyed by sessionId. Transcript-history rows are keyed by the Claude
- * conversation UUID (the `.jsonl` filename stem), which diverges from the
- * Codeman id for resumed sessions — an alias map (claudeSessionId → Codeman id,
- * built from the live/persisted views) folds them into the owning session item.
+ * persisted (`state.json`), transcript history, and the lifecycle audit log —
+ * plus mux process stats, into one de-duplicated list keyed by sessionId.
+ *
+ * Transcript history is not one source but three, because the CLIs keep their
+ * conversations in their own stores: Claude's `~/.claude/projects`, omp's
+ * `~/.omp/agent/sessions` and codex's `~/.codex/sessions`. Each row is keyed by
+ * whatever id that CLI names the conversation with, which diverges from the
+ * Codeman id for a resumed session and for every non-Claude one — an alias map
+ * (claudeSessionId → Codeman id, built from the live/persisted views) folds them
+ * into the owning session item.
  * Higher-precedence sources overwrite scalar fields when present
  * (history < lifecycle < persisted < live), while the `sources` array
  * always accumulates every contributing view. A "meaningfulness floor" drops
@@ -39,6 +43,11 @@ export type UnifiedSessionItem = {
   /** Main repo root a worktree belongs to (#266). */
   worktreeRepo?: string;
   remote?: boolean;
+  /**
+   * Token this row's CLI resumes by, when that is not `sessionId`. Set only from
+   * a transcript scanner — see the field of the same name on `HistoryInput`.
+   */
+  resumeId?: string;
   /** Pinned to the top of the session manager list (COD-139). */
   pinned?: boolean;
   /** When the session was pinned (epoch ms) — orders the pinned group desc. */
@@ -100,12 +109,21 @@ export type HistoryInput = {
   worktreeName?: string;
   worktreeRepo?: string;
   /**
-   * Set only by a non-claude transcript source (currently omp); the Claude
-   * scanner never stamps this; the meaningfulness floor below still counts a
-   * row with a `mode` as real, since that also signals "not claude" — see
-   * where it's read below for the isReal check this touches.
+   * Set only by a non-claude transcript source (currently omp and codex); the
+   * Claude scanner never stamps this; the meaningfulness floor below still
+   * counts a row with a `mode` as real, since that also signals "not claude" —
+   * see where it's read below for the isReal check this touches.
    */
   mode?: string;
+  /**
+   * The token this CLI's own resume command expects, when it is NOT the row's
+   * `sessionId`. Codex names a thread by an id of its own that lives in the
+   * rollout, and a live codex session's `sessionId` is Codeman's uuid instead —
+   * so a resume that reused `sessionId` would ask codex for a thread that does
+   * not exist. Only a transcript scanner sets this, which is what keeps the two
+   * kinds of row apart.
+   */
+  resumeId?: string;
 };
 
 /** Mux process-stat view. */
@@ -186,6 +204,7 @@ export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionIte
     // transcript source (currently only omp) does, so a history-only row
     // still gets a mode badge instead of reading as claude by default.
     overwrite(item, 'mode', h.mode);
+    overwrite(item, 'resumeId', h.resumeId);
     const ms = Date.parse(h.lastModified);
     if (!Number.isNaN(ms) && item.lastActivityAt === undefined) item.lastActivityAt = ms;
   }

src/session.ts

@@ -106,6 +106,7 @@ import {
 import { DEFAULT_TMUX_HISTORY_LIMIT } from './config/terminal-history.js';
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
 import { getCli } from './config/cli-registry/registry.js';
+import { compileVersionRegex } from './config/cli-registry/patterns.js';
 import { resolveSessionCliVersion } from './utils/cli-resolver.js';
 import {
   buildInteractiveArgs,
@@ -481,6 +482,8 @@ 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)
+  /** Lazily compiled `capabilities.workDetect.workingLine`. See _workingLinePattern(). */
+  private _workingLineRe: RegExp | undefined = undefined;
   private _trustDialogAccepted: boolean = false; // Stops the trust-dialog scan (answered, or given up)
   private _trustDialogAttempts = 0; // Keystrokes sent at the trust dialog
   private _lastTrustDialogScanAt = 0; // Throttle for the trust-dialog screen read
@@ -721,13 +724,20 @@ export class Session extends EventEmitter {
     this._wireActivityAt = config.lastActivityAt || Date.now();
     this._wireActivitySettleUntil = config.lastActivityAt ? Date.now() + WIRE_ACTIVITY_SETTLE_MS : 0;
     // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
-    // For omp, `claudeSessionId` doubles as the generic "external transcript id"
-    // alias key mergeUnifiedSessions() folds a history row into its owning
-    // session by: omp mints its OWN uuid, unrelated to this Codeman id, so
-    // without this an omp conversation's Past-Sessions row (keyed by omp's
-    // id) would never merge with its own live/persisted row (keyed by this
-    // id) — it would just show up a second time.
-    this._claudeSessionId = config.resumeSessionId || config.ompConfig?.resumeSessionId || this.id;
+    // For omp and codex, `claudeSessionId` doubles as the generic "external
+    // transcript id" alias key mergeUnifiedSessions() folds a history row into
+    // its owning session by: each mints its OWN thread id, unrelated to this
+    // Codeman id, so without this the conversation's Past-Sessions row (keyed by
+    // that thread id) would never merge with its own live/persisted row (keyed
+    // by this id) — it would just show up a second time. For codex a duplicate
+    // is worse than cosmetic: the stale row still resumes, so clicking it starts
+    // a SECOND `codex resume` on a thread already open in another pane.
+    //
+    // This covers a RESUMED codex session, which knows its thread id up front. A
+    // fresh one learns its id only once codex writes the rollout, so it is folded
+    // from the other side — see the originator stamping in `gatherUnifiedInputs()`.
+    this._claudeSessionId =
+      config.resumeSessionId || config.ompConfig?.resumeSessionId || config.codexConfig?.resumeSessionId || this.id;
     // Restored from state.json on boot recovery. start() resets _claudeSessionId
     // to the launch id even when re-attaching to a mux session whose CLI has
     // moved on (a `/clear` before the restart), so this anchor is what lets the
@@ -2065,16 +2075,23 @@ export class Session extends EventEmitter {
         // this to omp's own session uuid — that already-resolved id must win
         // over the generic `this.id` fallback, or this line clobbers it back
         // to the Codeman id
-        // on every single respawn.
+        // on every single respawn. codex needs the same fallback for the same
+        // reason: its thread id lives in `_codexConfig`, so without it every
+        // respawn drops a resumed codex session's alias and its Past-Sessions
+        // row springs back as a duplicate that still resumes.
         // ⚠️ A RESTORED mux session is the one case where the launch id is a
         // lie: the CLI never stopped, so a `/clear` before the Codeman restart
         // already moved it to a conversation `this.id` knows nothing about. The
         // persisted chain's tail is that conversation, reported first-hand by
-        // the CLI's own hook, so it outranks the fallback here. A NEW pane has
-        // an empty chain and falls through to exactly today's expression.
+        // the CLI's own hook, so it outranks every fallback here. A NEW pane has
+        // an empty chain and falls through to the resume/alias fallbacks.
         restoredConversation = isRestored ? this._claudeSessionChain[this._claudeSessionChain.length - 1] : undefined;
         this._claudeSessionId =
-          restoredConversation || this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id;
+          restoredConversation ||
+          this._resumeSessionId ||
+          this._ompConfig?.resumeSessionId ||
+          this._codexConfig?.resumeSessionId ||
+          this.id;
 
         // For NEW mux sessions: wait for readiness then clean buffer
         // For RESTORED mux sessions: don't do anything - client will fetch buffer on tab switch
@@ -2175,15 +2192,19 @@ export class Session extends EventEmitter {
     // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
     // Mirrors the mux branch above and must not clobber it: this line runs
     // unconditionally after both the mux and direct-PTY paths, so it also needs
-    // the ompConfig fallback or it stomps the mux branch's correctly-resolved
-    // OMP alias back to this.id on every mux/plain-reattach boot recovery
-    // (the "third reset point" — see DECISIONS.md). For the same reason it needs
-    // `restoredConversation`: on a RESTORED mux attach the CLI never stopped and
-    // may have `/clear`ed before the restart, so the launch id is a lie and the
-    // chain's tail is the live conversation. Empty on every other path, which
-    // leaves this expression exactly as it was.
+    // the ompConfig and codexConfig fallbacks or it stomps the mux branch's
+    // correctly-resolved OMP/codex alias back to this.id on every mux/plain-
+    // reattach boot recovery (the "third reset point" — see DECISIONS.md).
+    // For the same reason it needs `restoredConversation`: on a RESTORED mux
+    // attach the CLI never stopped and may have `/clear`ed before the restart,
+    // so the launch id is a lie and the chain's tail is the live conversation.
+    // It is empty on every other path, so those paths keep the alias chain.
     this._claudeSessionId =
-      restoredConversation || this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id;
+      restoredConversation ||
+      this._resumeSessionId ||
+      this._ompConfig?.resumeSessionId ||
+      this._codexConfig?.resumeSessionId ||
+      this.id;
 
     this._pid = this.ptyProcess.pid;
     console.log('[Session] Interactive PTY spawned with PID:', this._pid);
@@ -2388,12 +2409,14 @@ export class Session extends EventEmitter {
    * @param data raw PTY chunk, ANSI included
    */
   private _detectInteractiveActivity(data: string): void {
-    // The prompt line contains "❯" when Claude is waiting for input. It only ARMS
-    // the check and is NOT evidence the turn ended: Claude redraws the composer
-    // about once a second all the way through a turn, which is exactly how a
-    // working session used to flip to idle two seconds in. _confirmIdle() waits
-    // for the pane to actually go quiet before believing it.
-    if (data.includes('❯')) {
+    const workDetect = getCli(this.mode)?.capabilities.workDetect;
+    // The composer row carries this glyph when the CLI is waiting for input. It only
+    // ARMS the check and is NOT evidence the turn ended: a CLI redraws its composer
+    // about once a second all the way through a turn, which is exactly how a working
+    // session used to flip to idle two seconds in. _confirmIdle() waits for the pane to
+    // actually go quiet before believing it. A CLI that declares no glyph keeps Claude's,
+    // which is the glyph every such session has been armed by until now.
+    if (data.includes(workDetect?.promptGlyph ?? '❯')) {
       // Only start a new timeout if we're not already awaiting idle confirmation.
       // This prevents status bar redraws (which include the prompt) from resetting it.
       if (!this._awaitingIdleConfirmation) {
@@ -2412,9 +2435,10 @@ export class Session extends EventEmitter {
     // new status line does not rescue it either (tmux repaints partially, so the
     // complete line reaches the PTY only every few tens of seconds). An unbroken run
     // of repaints is the signal that survives. See session-activity.ts for the
-    // measurement. Claude only: an external CLI's TUI has no ❯, so nothing would
-    // ever arm the idle confirmation and such a session would latch busy forever.
-    if (!isExternalCliMode(this.mode)) {
+    // measurement. This needs a pane Codeman can read: without a glyph to arm the idle
+    // confirmation, a session latches busy forever. A CLI that declares work detection
+    // supplies its own glyph, and the non-external modes keep the run they always had.
+    if (workDetect || !isExternalCliMode(this.mode)) {
       this._activityStreak = trackActivityStreak(this._activityStreak, Date.now());
       // A streak is the TRIGGER to look, not the verdict: typing into the composer
       // also produces a steady stream of repaints. The screen settles it, and only
@@ -2449,10 +2473,30 @@ export class Session extends EventEmitter {
     if (now - this._lastPaneProbeAt < PANE_PROBE_MIN_INTERVAL_MS) return this._lastPaneProbeWorking;
     this._lastPaneProbeAt = now;
     const text = this._mux.capturePaneText?.(this._muxSession.muxName) ?? null;
-    this._lastPaneProbeWorking = text === null ? null : CLAUDE_WORKING_LINE_PATTERN.test(text);
+    this._lastPaneProbeWorking = text === null ? null : this._workingLinePattern().test(text);
     return this._lastPaneProbeWorking;
   }
 
+  /**
+   * The regex matching this CLI's "a turn is running" status line.
+   *
+   * Compiled once per session and cached: `_probePaneWorking` runs it against a whole
+   * pane capture on a timer, and the throttled text detector runs it against every
+   * accumulated chunk. A CLI that declares no pattern falls back to Claude's, which is
+   * the pattern every session used before the registry carried one.
+   */
+  private _workingLinePattern(): RegExp {
+    if (this._workingLineRe === undefined) {
+      const src = getCli(this.mode)?.capabilities.workDetect?.workingLine;
+      // Same guard the schema applies, not a second opinion: `compileVersionRegex()` is
+      // what keeps a nested quantifier out of this pattern, and this one runs on the PTY
+      // hot path. It returns null rather than throwing, and Claude's pattern is the
+      // fallback every session used before the registry carried one.
+      this._workingLineRe = (src ? compileVersionRegex(src) : null) ?? CLAUDE_WORKING_LINE_PATTERN;
+    }
+    return this._workingLineRe;
+  }
+
   /**
    * Mark the pane as working. Idempotent: `working` is emitted on the transition
    * only, so the per-chunk detectors can all call it freely.
@@ -2541,10 +2585,6 @@ export class Session extends EventEmitter {
    * PTY data chunk. Receives accumulated raw data to process in one batch.
    */
   private _processExpensiveParsers(rawData: string): void {
-    // Skip Claude-specific parsers for external CLI sessions (Ralph tracker,
-    // BashToolParser, token + CLI-info parsing all depend on Claude's output format).
-    if (isExternalCliMode(this.mode)) return;
-
     // Lazy ANSI strip: only compute cleanData when a consumer actually needs it.
     let _cleanData: string | null = null;
     const getCleanData = (): string => {
@@ -2554,6 +2594,19 @@ export class Session extends EventEmitter {
       return _cleanData;
     };
 
+    // Work detection by status line, ahead of the external-CLI gate below. The pattern
+    // comes from the CLI's own registry entry, so this is the one parser here that is not
+    // Claude-specific — and it sat under that gate, which is why an external CLI reported
+    // itself idle through an entire turn. Guarded on the descriptor so a CLI without one
+    // still skips the ANSI strip the gate used to save it.
+    if (!this._isWorking && getCli(this.mode)?.capabilities.workDetect) {
+      if (this._workingLinePattern().test(getCleanData())) this._markWorking();
+    }
+
+    // Skip Claude-specific parsers for external CLI sessions (Ralph tracker,
+    // BashToolParser, token + CLI-info parsing all depend on Claude's output format).
+    if (isExternalCliMode(this.mode)) return;
+
     // Forward to Ralph tracker to detect Ralph loops and todos
     // (opencode sessions already returned early at line 1209)
     if (this._ralphTracker.enabled || !this._ralphTracker.autoEnableDisabled) {
@@ -2585,16 +2638,13 @@ export class Session extends EventEmitter {
       this.parseTaskDescriptionsFromTerminalData(getCleanData());
     }
 
-    // Work detection (text-based, needs clean data: the status line is coloured,
-    // so raw data has escape sequences between the `…` and the elapsed timer).
-    // Only check if a faster path didn't already trigger working state.
+    // Legacy gerunds, Claude-only. The status-line pattern above already ran for every
+    // CLI that declares one, so this adds only the older wording. Current Claude
+    // randomizes the word ("Actualizing…", "Finagling…"), so these catch a fraction of
+    // turns; the pattern above and the activity streak carry the rest.
     if (!this._isWorking) {
       const cleanData = getCleanData();
       if (
-        CLAUDE_WORKING_LINE_PATTERN.test(cleanData) ||
-        // Legacy gerunds. Current Claude randomizes the word ("Actualizing…",
-        // "Finagling…"), so these catch only a fraction of turns; the pattern
-        // above and the activity streak carry the rest.
         cleanData.includes('Thinking') ||
         cleanData.includes('Writing') ||
         cleanData.includes('Reading') ||

src/types/api.ts

@@ -157,6 +157,20 @@ export interface CaseInfo {
   location?: 'local' | 'linked-local' | 'remote' | 'docker';
   /** Whether this is a linked local folder */
   linked?: boolean;
+  /**
+   * Present when Codeman scaffolded this case directory for an AGENT-spawned session
+   * (the packaged skill's workers, or any spawn naming a parent session), read back
+   * from the case's own marker file — see `src/agent-case-marker.ts`. Absent for every
+   * case a human created, linked or cloned, which is what makes it usable as the
+   * "safe to clean up" signal in the Manage tab.
+   */
+  agentCreated?: {
+    createdAt: string;
+    createdBy: string;
+    parentSessionId?: string;
+    parentSessionName?: string;
+    mode?: string;
+  };
   /** Remote case metadata for display and session creation */
   remote?: {
     hostId: string;
@@ -192,6 +206,25 @@ export interface CaseInfo {
   };
 }
 
+/**
+ * One agent-created case as `GET /api/cases/agent-created` reports it: the cleanup
+ * view over `CaseInfo.agentCreated`, with the two facts a human needs before deleting
+ * a directory — whether an agent is still working in it, and when it was last touched.
+ */
+export interface AgentCaseSummary {
+  name: string;
+  path: string;
+  createdAt: string;
+  createdBy: string;
+  parentSessionId?: string;
+  parentSessionName?: string;
+  mode?: string;
+  /** A live session's working directory is this case — deleting it would pull the rug. */
+  inUse: boolean;
+  /** Directory mtime, so "nothing has touched this in a week" is answerable. */
+  modifiedAt?: string;
+}
+
 // ========== Error Handling Utilities ==========
 
 /**

src/web/public/mobile-overview.js

@@ -228,6 +228,11 @@ Object.assign(CodemanApp.prototype, {
           name: item.name || '',
           title: title || item.name || dir.split('/').pop() || item.sessionId.slice(0, 8),
           mode: item.mode || 'claude',
+          // Only the scanner sets this, and only for a codex rollout. Dropping it here
+          // is not cosmetic: resumeMobileOverviewSession() passes row.resumeId on to
+          // resumeHistorySession(), so without it a tapped Codex row starts a FRESH
+          // session on a thread that is already on disk.
+          resumeId: item.resumeId || undefined,
           caseName: matched ? matched.name : '',
           dir: this._shortenHomePath ? this._shortenHomePath(dir) : dir,
           at: item.lastActivityAt || item.createdAt || 0,
@@ -389,7 +394,13 @@ Object.assign(CodemanApp.prototype, {
   async resumeMobileOverviewSession(sessionId) {
     const row = (this._mobileOverviewPastRows || []).find((r) => r.id === sessionId);
     if (!row || !row.workingDir) return;
-    await this.resumeHistorySession(row.claudeSessionId || row.id, row.workingDir, row.name || undefined, row.mode);
+    await this.resumeHistorySession(
+      row.claudeSessionId || row.id,
+      row.workingDir,
+      row.name || undefined,
+      row.mode,
+      row.resumeId
+    );
   },
 
   // ═══════════════════════════════════════════════════════════════

src/web/public/panels-ui.js

@@ -670,7 +670,13 @@ Object.assign(CodemanApp.prototype, {
             } else if (record.workingDir) {
               // History rows are keyed by the Claude conversation UUID; resumed
               // sessions carry theirs separately as claudeSessionId.
-              void this.resumeHistorySession(s.claudeSessionId || s.sessionId, record.workingDir, undefined, s.mode);
+              void this.resumeHistorySession(
+                s.claudeSessionId || s.sessionId,
+                record.workingDir,
+                undefined,
+                s.mode,
+                s.resumeId
+              );
             }
           },
         });

src/web/public/session-ui.js

@@ -804,7 +804,7 @@ Object.assign(CodemanApp.prototype, {
         btn.append(...parts);
         btn.addEventListener('click', (e) => {
           e.stopPropagation();
-          this.resumeHistorySession(s.sessionId, s.workingDir, s.name, s.mode);
+          this.resumeHistorySession(s.sessionId, s.workingDir, s.name, s.mode, s.resumeId);
         });
         container.appendChild(btn);
       }
@@ -3595,17 +3595,33 @@ Object.assign(CodemanApp.prototype, {
       return;
     }
 
-    let html = '';
+    // Cases an agent worker created (server-side marker file, see agent-case-marker.ts).
+    // A long orchestration leaves one scratch directory per worker behind, so they get
+    // a badge and a bulk cleanup entry point rather than having to be recognised by name.
+    const agentCases = cases.filter(c => c.agentCreated);
+    let html = agentCases.length > 0
+      ? `<div class="case-manage-agent-bar">
+          <span class="case-manage-agent-count">${agentCases.length} case${agentCases.length === 1 ? '' : 's'} created by agent workers</span>
+          <button class="case-manage-btn case-manage-btn-cleanup" onclick="app.cleanupAgentCases()"
+                  title="Review and delete the scratch cases agent workers left behind">Clean up</button>
+         </div>`
+      : '';
     cases.forEach((c, idx) => {
       const isFirst = idx === 0;
       const isLast = idx === cases.length - 1;
       // Was `/Users/<user>` only, the mirror image of the Run menu's bug: every
       // case path on a Linux host rendered in full, unabbreviated.
       const pathDisplay = c.path ? this._shortenHomePath(c.path) : '';
+      const agentTitle = c.agentCreated
+        ? `Created by an agent worker${c.agentCreated.parentSessionName ? ` from ${c.agentCreated.parentSessionName}` : ''}` +
+          ` (${c.agentCreated.createdBy})${c.agentCreated.createdAt ? ` on ${new Date(c.agentCreated.createdAt).toLocaleString()}` : ''}`
+        : '';
       html += `
         <div class="case-manage-item" data-case="${escapeHtml(c.name)}">
           <div class="case-manage-info">
-            <span class="case-manage-name">${escapeHtml(c.name)}</span>
+            <span class="case-manage-name">${escapeHtml(c.name)}${
+              c.agentCreated ? `<span class="case-manage-tag-agent" title="${escapeHtml(agentTitle)}" data-i18n-skip>agent</span>` : ''
+            }</span>
             <span class="case-manage-path">${escapeHtml(pathDisplay)}</span>
           </div>
           <div class="case-manage-actions">
@@ -3683,6 +3699,80 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * Review-then-delete the scratch cases agent workers left behind.
+   *
+   * ⚠️ Never silently bulk-deletes: the confirm names every directory, and a case a
+   * LIVE session is still working in is excluded outright rather than confirmed away
+   * (`inUse` from the server, which knows every session's working directory). Removal
+   * reuses `DELETE /api/cases/:name` one name at a time, so there is no second
+   * recursive-delete path to keep in step with the first.
+   */
+  async cleanupAgentCases() {
+    let agentCases;
+    try {
+      const res = await fetch('/api/cases/agent-created');
+      const body = await res.json();
+      if (!body.success) {
+        this.showToast(body.error || 'Failed to list agent cases', 'error');
+        return;
+      }
+      agentCases = body.data.cases || [];
+    } catch (err) {
+      this.showToast('Failed to list agent cases: ' + err.message, 'error');
+      return;
+    }
+
+    const busy = agentCases.filter(c => c.inUse);
+    const removable = agentCases.filter(c => !c.inUse);
+    if (removable.length === 0) {
+      this.showToast(
+        busy.length > 0
+          ? `All ${busy.length} agent case(s) are still in use by a running session`
+          : 'No agent-created cases to clean up',
+        'info'
+      );
+      return;
+    }
+
+    const names = removable.map(c => `  ${c.name}`).join('\n');
+    const busyNote = busy.length > 0 ? `\n\nSkipping ${busy.length} case(s) still in use by a running session.` : '';
+    if (!confirm(`Permanently delete ${removable.length} agent-created case folder(s) and everything in them?\n\n${names}${busyNote}`)) {
+      return;
+    }
+
+    let deleted = 0;
+    const failed = [];
+    for (const item of removable) {
+      try {
+        const res = await fetch(`/api/cases/${encodeURIComponent(item.name)}`, { method: 'DELETE' });
+        const body = await res.json();
+        if (body.success) deleted++;
+        else failed.push(item.name);
+      } catch {
+        failed.push(item.name);
+      }
+    }
+
+    this.showToast(
+      failed.length === 0
+        ? `Deleted ${deleted} agent case(s)`
+        : `Deleted ${deleted}, failed: ${failed.join(', ')}`,
+      failed.length === 0 ? 'success' : 'error'
+    );
+
+    // Refresh the picker (its selected case may be one we just deleted) and the list.
+    const select = document.getElementById('quickStartCase');
+    const currentCase = select?.value;
+    const currentDeleted = removable.some(c => c.name === currentCase);
+    if (currentDeleted) select?.blur?.();
+    await this.loadQuickStartCases(currentDeleted ? null : currentCase);
+    if (currentDeleted) {
+      await this.saveLastUsedCase(document.getElementById('quickStartCase')?.value || 'testcase');
+    }
+    this.renderCaseManageList();
+  },
+
   async saveCaseOrder(order) {
     try {
       await fetch('/api/cases/order', {

src/web/public/styles.css

@@ -5941,6 +5941,57 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   color: #ef4444;
 }
 
+/* Agent-created cases: the badge on a scratch case, and the bulk cleanup bar above
+   the list. Tokens only (no hardcoded ink), so the light skins repaint with the rest. */
+.case-manage-tag-agent {
+  display: inline-block;
+  margin-left: 6px;
+  padding: 0 5px;
+  border: 1px solid var(--control-border);
+  border-radius: 3px;
+  background: var(--control-bg);
+  color: var(--text-muted);
+  font-size: 0.58rem;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  vertical-align: 1px;
+}
+
+.case-manage-agent-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 4px;
+  padding: 8px 10px;
+  border: 1px solid var(--control-border);
+  border-radius: 6px;
+  /* Sticky, and therefore OPAQUE: it is the first child of the scrolling list
+     (.case-manage-list is a 320px-tall flex scroller), so a translucent bar would
+     have case rows sliding visibly under it, and a static one would put the cleanup
+     button out of reach the moment a long case list is scrolled. */
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background: var(--bg-card);
+}
+
+.case-manage-agent-count {
+  font-size: 0.7rem;
+  color: var(--text-dim);
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* The shared .case-manage-btn is a 26px icon square; this one carries a word. */
+.case-manage-btn-cleanup {
+  width: auto;
+  padding: 0 10px;
+  white-space: nowrap;
+}
+
 .toolbar-input {
   padding: 0.4rem 0.5rem;
   background: var(--bg-input);

src/web/public/terminal-ui.js

@@ -2193,7 +2193,7 @@ Object.assign(CodemanApp.prototype, {
           if (isLive && this.sessions.has(s.sessionId)) {
             this.selectSession(s.sessionId);
           } else {
-            this.resumeHistorySession(s.claudeSessionId || s.sessionId, s.workingDir || '', s.name, s.mode);
+            this.resumeHistorySession(s.claudeSessionId || s.sessionId, s.workingDir || '', s.name, s.mode, s.resumeId);
           }
         })
     );
@@ -2436,7 +2436,7 @@ Object.assign(CodemanApp.prototype, {
         } else {
           // Resume by the Claude conversation UUID when present (resumed sessions
           // carry theirs separately from their Codeman id).
-          this.resumeHistorySession(s.claudeSessionId || s.sessionId, s.workingDir || '', s.name, s.mode);
+          this.resumeHistorySession(s.claudeSessionId || s.sessionId, s.workingDir || '', s.name, s.mode, s.resumeId);
         }
         this.closeSessionManager?.();
         closeMenu();
@@ -2904,7 +2904,7 @@ Object.assign(CodemanApp.prototype, {
     return `w${startNumber}-${dirName}`;
   },
 
-  async resumeHistorySession(sessionId, workingDir, existingName, mode) {
+  async resumeHistorySession(sessionId, workingDir, existingName, mode, resumeId) {
     // Close the run mode menu if open
     document.getElementById('runModeMenu')?.classList.remove('active');
     // Close folder history modal if open
@@ -2942,19 +2942,27 @@ Object.assign(CodemanApp.prototype, {
         grok: 'grokConfig',
         omp: 'ompConfig',
       }[effectiveMode];
-      // codex/gemini/antigravity have no wired continuation here yet (their
-      // configs use an exact conversation id, not a "continue most recent"
-      // flag, and the row's own `sessionId` is not verified to carry that
-      // id for these three modes) — `continuesSomething` below is what keeps
-      // their row from being retired for a resume that didn't actually
-      // continue anything.
+      // codex names a thread by an id of its own, not by Codeman's session id,
+      // so it continues only when the row carried that id: `resumeId` is set by
+      // the rollout scanner (codex-transcript.ts) and by nothing else, which is
+      // what stops a LIVE codex row — whose sessionId is Codeman's uuid — from
+      // asking codex for a thread that does not exist.
+      //
+      // gemini/antigravity still have no wired continuation here (same reason
+      // codex used to have none: an exact conversation id nothing supplies) —
+      // `continuesSomething` below is what keeps their row from being retired
+      // for a resume that didn't actually continue anything.
+      const codexResumeId = effectiveMode === 'codex' ? resumeId : undefined;
       const modeConfig =
         modeConfigKey
           ? { [modeConfigKey]: { continueSession: true } }
           : effectiveMode === 'deepseek'
             ? { deepSeekConfig: { resumeSession: true } }
-            : {};
-      const continuesSomething = Boolean(modeConfigKey) || effectiveMode === 'deepseek';
+            : codexResumeId
+              ? { codexConfig: { resumeSessionId: codexResumeId } }
+              : {};
+      const continuesSomething =
+        Boolean(modeConfigKey) || effectiveMode === 'deepseek' || Boolean(codexResumeId);
       const createRes = await fetch('/api/sessions', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -2982,11 +2990,16 @@ Object.assign(CodemanApp.prototype, {
       // as a duplicate — click it 3 times, see the same name 3 times. Claude
       // rows are left alone: `sessionId` there is a claudeSessionId, which
       // usually has no live/persisted Codeman session of its own to delete.
-      // Gated on `continuesSomething`: for codex/gemini/antigravity (no
-      // continuation wired above), this is really a FRESH session with no
+      // Gated on `continuesSomething`: for gemini/antigravity, and for a codex
+      // row carrying no `resumeId`, this is really a FRESH session with no
       // relation to the old row's conversation, so retiring it would discard
       // the old conversation with no recovery — worse than the duplicate row
       // this guard exists to prevent for the modes that DO continue.
+      //
+      // A codex row that DOES continue passes this gate, but the DELETE is a
+      // no-op for it: `sessionId` there is codex's thread id and no Codeman
+      // session carries that id. Its duplicate is cleared from the other side
+      // instead, by the alias fold in gatherUnifiedInputs()/Session.
       if (effectiveMode !== 'claude' && continuesSomething && sessionId !== newSessionId) {
         fetch(`/api/sessions/${sessionId}?killMux=true`, { method: 'DELETE' }).catch(() => {});
       }

src/web/route-helpers.ts

@@ -23,6 +23,7 @@ import { dataPath } from '../config/instance.js';
 import { getCasesDir } from '../config/cases-dir.js';
 import { isMultiUserMode, maxSessionsPerUser, userCasesDir } from '../config/multiuser.js';
 import { SYNTHETIC_ADMIN, findUser } from '../user-store.js';
+import { AGENT_ORIGIN_SPAWNED_BY_SESSION, normalizeAgentOrigin } from '../agent-case-marker.js';
 
 // Shared path constants used across route modules. CASES_DIR (project folders)
 // stays shared across instances; SETTINGS_PATH is per-instance runtime state.
@@ -361,6 +362,33 @@ export function resolveParentSessionId(
   return parent.id;
 }
 
+/**
+ * Resolve "an agent asked for this", the signal that labels a case directory
+ * Codeman is about to CREATE as an agent scratch workspace (see agent-case-marker.ts).
+ *
+ * Two signals, in order:
+ * 1. an explicit `agentOrigin` body field, or the `X-Codeman-Agent-Origin` header the
+ *    packaged skill sets once on its shared curl invocation, so every spawn recipe
+ *    carries it without a per-recipe edit. The body wins, mirroring parentSessionId;
+ * 2. failing that, an already-RESOLVED parent session id. A create request that names
+ *    the session that spawned it came from an agent by construction: nothing in the
+ *    browser UI sets lineage. This is what still labels workers spawned by a stale
+ *    skill copy or by hand-rolled curl that only carries the lineage header.
+ *
+ * ⚠️ Decoration, like parentSessionId: never an ownership or permission signal, and
+ * never a reason to fail a spawn. An unrecognised origin token is dropped by
+ * `normalizeAgentOrigin` rather than rejected.
+ */
+export function resolveAgentCaseOrigin(
+  req: FastifyRequest,
+  bodyValue: string | undefined,
+  resolvedParentSessionId: string | undefined
+): string | undefined {
+  const header = req.headers['x-codeman-agent-origin'];
+  const raw = bodyValue ?? (Array.isArray(header) ? header[0] : header);
+  return normalizeAgentOrigin(raw) ?? (resolvedParentSessionId ? AGENT_ORIGIN_SPAWNED_BY_SESSION : undefined);
+}
+
 /**
  * Parse and validate a request body against a Zod schema, or throw a structured 400 error.
  * Replaces the repeated pattern: `const r = Schema.safeParse(body); if (!r.success) return createErrorResponse(...)`.

src/web/routes/case-routes.ts

@@ -13,7 +13,15 @@ import fs from 'node:fs/promises';
 import { join, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import type { ApiResponse, CaseInfo, DockerHost, RemoteSessionInfo, SessionDocker, SessionMode } from '../../types.js';
+import type {
+  AgentCaseSummary,
+  ApiResponse,
+  CaseInfo,
+  DockerHost,
+  RemoteSessionInfo,
+  SessionDocker,
+  SessionMode,
+} from '../../types.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import {
   CreateCaseSchema,
@@ -42,6 +50,7 @@ import {
 } from '../../git-clone.js';
 import type { GitRemoteProbe, GitUrlParse } from '../../git-clone.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
+import { readAgentCaseMarker, type AgentCaseMarker } from '../../agent-case-marker.js';
 import { settingsWriteBlocker, writeHooksConfig } from '../../hooks-config.js';
 import {
   canAccessOwned,
@@ -144,6 +153,21 @@ function repoShipsClaudeSettings(casePath: string): boolean {
   return ['settings.json', 'settings.local.json'].some((file) => existsSync(join(casePath, '.claude', file)));
 }
 
+/**
+ * Project a case's marker onto the wire shape `CaseInfo.agentCreated` carries.
+ * `owner` stays server-side: the listings are already owner-scoped, and it is not
+ * something the case list needs to publish.
+ */
+function agentCreatedInfo(marker: AgentCaseMarker): NonNullable<CaseInfo['agentCreated']> {
+  return {
+    createdAt: marker.createdAt,
+    createdBy: marker.createdBy,
+    ...(marker.parentSessionId ? { parentSessionId: marker.parentSessionId } : {}),
+    ...(marker.parentSessionName ? { parentSessionName: marker.parentSessionName } : {}),
+    ...(marker.mode ? { mode: marker.mode } : {}),
+  };
+}
+
 /** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
 async function readLinkedCases(): Promise<Record<string, string>> {
   return readJsonConfig<Record<string, string>>(LINKED_CASES_FILE, 'linked cases', {});
@@ -222,11 +246,16 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       const entries = await fs.readdir(listBase, { withFileTypes: true });
       for (const e of entries) {
         if (e.isDirectory() && SAFE_CASE_NAME.test(e.name)) {
+          const casePath = join(listBase, e.name);
+          // Only a directory Codeman scaffolded for an agent spawn carries a marker,
+          // so this stays absent for every human-created, linked or cloned case.
+          const marker = await readAgentCaseMarker(casePath);
           cases.push({
             name: e.name,
-            path: join(listBase, e.name),
-            hasClaudeMd: existsSync(join(listBase, e.name, 'CLAUDE.md')),
+            path: casePath,
+            hasClaudeMd: existsSync(join(casePath, 'CLAUDE.md')),
             location: 'local',
+            ...(marker ? { agentCreated: agentCreatedInfo(marker) } : {}),
           });
         }
       }
@@ -326,6 +355,61 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     return cases;
   });
 
+  // ========== Agent-created cases (cleanup listing) ==========
+
+  /**
+   * The scratch workspaces agent workers left behind, newest first.
+   *
+   * A long orchestration creates one case directory per worker, and deleting the
+   * sessions does not remove them, so without this the only way to tell an agent's
+   * `alpha`/`beta` from a real project was to remember which was which. Reads the same
+   * marker `GET /api/cases` exposes and adds the two facts a human needs before
+   * deleting a directory: whether a live session is still working in it, and when it
+   * was last touched.
+   *
+   * ⚠️ Read-only on purpose: removal goes through the existing `DELETE /api/cases/:name`,
+   * one name at a time, so this file keeps exactly one recursive-delete path. Scoped by
+   * construction — it only ever walks the caller's own case space.
+   */
+  app.get('/api/cases/agent-created', async (req): Promise<ApiResponse<{ cases: AgentCaseSummary[] }>> => {
+    const user = getAuthUser(req);
+    const listBase = resolveCasesDir(user);
+    const inUsePaths = new Set(
+      Array.from(ctx.sessions.values())
+        .filter((session) => canAccessOwned(user, session.owner))
+        .map((session) => session.workingDir)
+    );
+
+    let entries;
+    try {
+      entries = await fs.readdir(listBase, { withFileTypes: true });
+    } catch {
+      return { success: true, data: { cases: [] } }; // case space not created yet
+    }
+
+    const summaries: AgentCaseSummary[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !SAFE_CASE_NAME.test(entry.name)) continue;
+      const casePath = join(listBase, entry.name);
+      const marker = await readAgentCaseMarker(casePath);
+      if (!marker) continue;
+      const modifiedAt = await fs
+        .stat(casePath)
+        .then((stat) => stat.mtime.toISOString())
+        .catch(() => undefined);
+      summaries.push({
+        name: entry.name,
+        path: casePath,
+        ...agentCreatedInfo(marker),
+        inUse: inUsePaths.has(casePath),
+        ...(modifiedAt ? { modifiedAt } : {}),
+      });
+    }
+
+    summaries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return { success: true, data: { cases: summaries } };
+  });
+
   app.post('/api/cases', async (req): Promise<ApiResponse<{ case: { name: string; path: string } }>> => {
     const { name, description } = parseBody(CreateCaseSchema, req.body);
 

src/web/routes/session-routes.ts

@@ -76,12 +76,14 @@ import {
   ownerFor,
   parseBody,
   persistAndBroadcastSession,
+  resolveAgentCaseOrigin,
   resolveCasesDir,
   resolveParentSessionId,
   sessionCapacityMessage,
   SETTINGS_PATH,
   validatePathWithinBase,
 } from '../route-helpers.js';
+import { buildAgentCaseMarker, writeAgentCaseMarker } from '../../agent-case-marker.js';
 import { canUsernameRunPrivilegedCommands, resolveClaudeModeForUsername } from '../../user-store.js';
 import { enabledClis, getCli } from '../../config/cli-registry/registry.js';
 import { resolveCliLaunchError } from '../../utils/cli-launcher.js';
@@ -146,6 +148,7 @@ import {
 import { LRUMap } from '../../utils/lru-map.js';
 import { findLatestOmpSessionId } from '../../utils/omp-session-resolver.js';
 import { scanOmpSessionsHistory } from '../../omp-transcript.js';
+import { scanCodexSessionsHistory, codexThreadBySessionId } from '../../codex-transcript.js';
 import {
   getLastTranscriptResponse,
   isExternalCliTranscriptMode,
@@ -2973,8 +2976,13 @@ export function registerSessionRoutes(
       envOverrides,
       effort,
       parentSessionId,
+      agentOrigin,
     } = parseBody(QuickStartSchema, req.body);
 
+    // Resolved ONCE here: the same value labels a case directory this request creates
+    // (agent-case-marker.ts) and draws the tab lineage line on the session below.
+    const qsParentSessionId = resolveParentSessionId(ctx, req, parentSessionId, owner);
+
     // Multi-user: shell mode is arbitrary host-account execution, gated by the grant.
     // Resolve the owner's grant from the store so a GRANTED regular user is not wrongly denied.
     if (getCli(mode)?.capabilities.privilegedCommandGate && !(await canUsernameRunPrivilegedCommands(owner))) {
@@ -3220,6 +3228,26 @@ export function registerSessionRoutes(
           await writeHooksConfig(resolvedCasePath);
         }
 
+        // Label a directory an AGENT asked us to create, so the scratch workspaces a
+        // long orchestration leaves behind can be told apart from the user's real
+        // projects later (see agent-case-marker.ts). This is the only branch that may
+        // write it: it is the only one that creates the directory, and a pre-existing
+        // case must never be labelled. Best-effort — a failed marker must not fail the
+        // spawn it decorates.
+        const qsAgentOrigin = resolveAgentCaseOrigin(req, agentOrigin, qsParentSessionId);
+        if (qsAgentOrigin) {
+          await writeAgentCaseMarker(
+            resolvedCasePath,
+            buildAgentCaseMarker({
+              createdBy: qsAgentOrigin,
+              parentSessionId: qsParentSessionId,
+              parentSessionName: qsParentSessionId ? ctx.sessions.get(qsParentSessionId)?.name : undefined,
+              mode,
+              owner,
+            })
+          );
+        }
+
         ctx.broadcast(SseEvent.CaseCreated, { name: caseName, path: resolvedCasePath });
       } catch (err) {
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
@@ -3353,7 +3381,7 @@ export function registerSessionRoutes(
       docker,
       resumeSessionId: dockerResumeId,
       tmuxHistoryLimit: qsTerminalHistoryConfig.tmuxHistoryLimit,
-      parentSessionId: resolveParentSessionId(ctx, req, parentSessionId, owner),
+      parentSessionId: qsParentSessionId,
     });
 
     // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
@@ -4137,6 +4165,13 @@ export function registerSessionRoutes(
     // Persisted sessions (state.json). resumeSessionId is the Claude
     // conversation UUID a resumed session continues — feed it to the merge's
     // alias map so its transcript row folds into this session.
+    //
+    // codex keeps its thread id in `codexConfig` instead, and state.json stores
+    // that, so read it here as well. Without it a resumed codex session that has
+    // been demoted to a persisted-only record loses its alias and duplicates: the
+    // originator fallback below cannot rescue that one, because a RESUMED rollout
+    // keeps the original session_meta (see findActiveCodexFile) and so still
+    // names whichever pane first created the thread.
     const persisted: PersistedSessionInput[] = Object.values(ctx.store.getState().sessions).map((p) => ({
       id: p.id,
       name: p.name,
@@ -4145,7 +4180,7 @@ export function registerSessionRoutes(
       workingDir: p.workingDir,
       createdAt: p.createdAt,
       lastActivityAt: p.lastActivityAt,
-      claudeSessionId: p.resumeSessionId,
+      claudeSessionId: p.resumeSessionId || p.codexConfig?.resumeSessionId,
       pinned: p.pinned,
       pinnedAt: p.pinnedAt,
     }));
@@ -4213,6 +4248,49 @@ export function registerSessionRoutes(
       // Best-effort, same as the claude scan above.
     }
 
+    // Codex's own rollout store (~/.codex/sessions) — the same treatment omp
+    // gets above, and for the same reason: codex writes no Claude transcript, so
+    // without this a codex conversation disappears from the list as soon as its
+    // session record does. `resumeId` is the rollout's own thread id, which is
+    // what `codex resume` takes; see codex-transcript.ts.
+    try {
+      const codexRows = await scanCodexSessionsHistory();
+      for (const h of codexRows) {
+        history.push({
+          sessionId: h.sessionId,
+          workingDir: h.workingDir,
+          sizeBytes: h.sizeBytes,
+          lastModified: h.lastModified,
+          firstPrompt: h.firstPrompt,
+          lastPrompt: h.lastPrompt,
+          mode: 'codex',
+          resumeId: h.sessionId,
+        });
+      }
+
+      // Fold a FRESH codex pane into its own rollout row. A resumed one already
+      // folds, because Session sets `claudeSessionId` from the resume id it was
+      // given; a fresh one has no thread id until codex writes the rollout, so
+      // the link has to come from the other side. Codeman spawns every codex pane
+      // with CODEX_INTERNAL_ORIGINATOR_OVERRIDE=codeman_<sessionId>, and codex
+      // stamps that into session_meta.originator, so the rollout names the pane.
+      //
+      // Newest rollout wins: `/new` typed inside the TUI leaves several rollouts
+      // carrying the same originator, and the pane is on the most recent one.
+      // Rows arrive newest-first, so the first match is it.
+      //
+      // Never overwrites an id a session already knows — that one came from the
+      // resume path and is authoritative.
+      const codexThreads = codexThreadBySessionId(codexRows);
+      for (const row of [...live, ...persisted]) {
+        if (row.claudeSessionId && row.claudeSessionId !== row.id) continue;
+        const threadId = codexThreads.get(row.id);
+        if (threadId) row.claudeSessionId = threadId;
+      }
+    } catch {
+      // Best-effort, same as the two scans above.
+    }
+
     // Mux process stats (best-effort; guard against mocks lacking the method).
     let mux: MuxStatInput[] = [];
     try {

src/web/schemas.ts

@@ -1025,6 +1025,16 @@ export const QuickStartSchema = z.object({
   envOverrides: safeEnvOverridesSchema,
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
   effort: effortLevelSchema,
+  /**
+   * Who is spawning this worker (`codeman-skill` from the packaged agent skill), or,
+   * equivalently, the `X-Codeman-Agent-Origin` header; the body wins when both are
+   * present. Used ONLY to label a case directory this request CREATES as an agent
+   * scratch workspace, so it can be found and cleaned up later — see
+   * `src/agent-case-marker.ts`. Never a permission signal, and an unrecognised token
+   * is dropped rather than rejected. `POST /api/sessions` has no equivalent field
+   * because it takes an existing `workingDir` and so never creates a directory to label.
+   */
+  agentOrigin: z.string().max(64).optional(),
 });
 
 // ========== Hook Events ==========

src/web/server.ts

@@ -81,7 +81,7 @@ import { RunSummaryTracker } from '../run-summary.js';
 import { PlanOrchestrator } from '../plan-orchestrator.js';
 import { OrchestratorLoop } from '../orchestrator-loop.js';
 import { getLifecycleLog } from '../session-lifecycle-log.js';
-import { applyWorkspaceHooks } from '../hooks-config.js';
+import { applyWorkspaceHooks, pruneAgentSessionPreambles, removeAgentSessionPreamble } from '../hooks-config.js';
 import { PushSubscriptionStore } from '../push-store.js';
 import webpush from 'web-push';
 import { SseStreamManager } from './sse-stream-manager.js';
@@ -1370,6 +1370,12 @@ export class WebServer extends EventEmitter {
           // Best-effort cleanup
         }
       }
+      // Drop the agent skill's preamble cache for this session (seeded at create).
+      // killMux only: a detach leaves the session recoverable, and its agent would
+      // come back to a loader whose file we deleted.
+      if (killMux) {
+        void removeAgentSessionPreamble(sessionId);
+      }
       await session.stop(killMux);
       this.sessions.delete(sessionId);
       // Only remove from state.json if we're also killing the mux session.
@@ -2514,6 +2520,19 @@ export class WebServer extends EventEmitter {
       }
     }
 
+    // Sweep agent preamble caches whose sessions are gone (see
+    // pruneAgentSessionPreambles). Once per boot, after restore, so every session this
+    // instance owns is in the keep set. Best-effort and off the startup critical path.
+    if (!this.testMode) {
+      void pruneAgentSessionPreambles(this.sessions.keys())
+        .then((removed) => {
+          if (removed > 0) console.log(`[agent-skill] pruned ${removed} stale preamble cache file(s)`);
+        })
+        .catch(() => {
+          /* best-effort */
+        });
+    }
+
     // Bound disk use under heavy paste-image traffic: delete `paste-*` files
     // older than 7 days from each live session's .claude-images/ hourly.
     if (!this.testMode) {

test/agent-case-marker.test.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview The agent-case marker: the label that tells a scratch worker workspace
+ * apart from the user's real projects.
+ *
+ * The rules under test are the ones that keep a cleanup affordance safe: reading is
+ * total (anything that is not a well-formed version-1 marker reads as "not
+ * agent-created", never as a half-trusted entry), the origin token is allowlisted
+ * rather than escaped at each use, and writing never throws — a failed marker must not
+ * fail the worker spawn it decorates.
+ *
+ * Port: N/A (pure + a temp dir).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  AGENT_CASE_MARKER_FILE,
+  AGENT_ORIGIN_CODEMAN_SKILL,
+  AGENT_ORIGIN_SPAWNED_BY_SESSION,
+  buildAgentCaseMarker,
+  normalizeAgentOrigin,
+  parseAgentCaseMarker,
+  readAgentCaseMarker,
+  writeAgentCaseMarker,
+} from '../src/agent-case-marker.js';
+
+describe('normalizeAgentOrigin', () => {
+  it('accepts a short lowercase token', () => {
+    expect(normalizeAgentOrigin('codeman-skill')).toBe('codeman-skill');
+    expect(normalizeAgentOrigin('  Codeman-Skill  ')).toBe('codeman-skill');
+    expect(normalizeAgentOrigin('agent.v2_1')).toBe('agent.v2_1');
+  });
+
+  it('drops anything that is not one', () => {
+    // The value reaches a JSON file and the case-manage UI, so it is allowlisted at
+    // the boundary instead of escaped at every use site.
+    expect(normalizeAgentOrigin('<script>')).toBeUndefined();
+    expect(normalizeAgentOrigin('has space')).toBeUndefined();
+    expect(normalizeAgentOrigin('-leading-dash')).toBeUndefined();
+    expect(normalizeAgentOrigin('x'.repeat(33))).toBeUndefined();
+    expect(normalizeAgentOrigin('')).toBeUndefined();
+    expect(normalizeAgentOrigin(undefined)).toBeUndefined();
+    expect(normalizeAgentOrigin(42)).toBeUndefined();
+  });
+});
+
+describe('buildAgentCaseMarker', () => {
+  it('keeps only the fields that were supplied', () => {
+    const marker = buildAgentCaseMarker({ createdBy: AGENT_ORIGIN_CODEMAN_SKILL });
+    expect(marker.version).toBe(1);
+    expect(marker.createdBy).toBe(AGENT_ORIGIN_CODEMAN_SKILL);
+    expect(Date.parse(marker.createdAt)).not.toBeNaN();
+    expect('parentSessionId' in marker).toBe(false);
+    expect('mode' in marker).toBe(false);
+  });
+
+  it('falls back to the spawned-by-session origin rather than storing junk', () => {
+    expect(buildAgentCaseMarker({ createdBy: 'not a token' }).createdBy).toBe(AGENT_ORIGIN_SPAWNED_BY_SESSION);
+  });
+});
+
+describe('parseAgentCaseMarker', () => {
+  const valid = JSON.stringify({
+    version: 1,
+    createdAt: '2026-09-07T10:00:00.000Z',
+    createdBy: 'codeman-skill',
+    parentSessionId: 'sess-1',
+    parentSessionName: 'w1-claudeman',
+    mode: 'claude',
+    note: 'ignored',
+  });
+
+  it('round-trips a well-formed marker and drops unknown fields', () => {
+    const marker = parseAgentCaseMarker(valid);
+    expect(marker).toEqual({
+      version: 1,
+      createdAt: '2026-09-07T10:00:00.000Z',
+      createdBy: 'codeman-skill',
+      parentSessionId: 'sess-1',
+      parentSessionName: 'w1-claudeman',
+      mode: 'claude',
+    });
+  });
+
+  it('reads anything malformed as absent', () => {
+    // Each of these must mean "not an agent case", because the answer drives a
+    // recursive-delete affordance in the UI.
+    expect(parseAgentCaseMarker('not json')).toBeNull();
+    expect(parseAgentCaseMarker('[]')).toBeNull();
+    expect(parseAgentCaseMarker('null')).toBeNull();
+    expect(parseAgentCaseMarker(JSON.stringify({ version: 2, createdAt: '2026-09-07', createdBy: 'x' }))).toBeNull();
+    expect(parseAgentCaseMarker(JSON.stringify({ version: 1, createdBy: 'x' }))).toBeNull();
+    expect(parseAgentCaseMarker(JSON.stringify({ version: 1, createdAt: 'whenever', createdBy: 'x' }))).toBeNull();
+    expect(
+      parseAgentCaseMarker(JSON.stringify({ version: 1, createdAt: '2026-09-07T10:00:00Z', createdBy: 'bad token' }))
+    ).toBeNull();
+  });
+});
+
+describe('writeAgentCaseMarker / readAgentCaseMarker', () => {
+  let caseDir: string;
+
+  beforeEach(async () => {
+    caseDir = await mkdtemp(join(tmpdir(), 'codeman-agent-case-'));
+  });
+
+  afterEach(async () => {
+    await rm(caseDir, { recursive: true, force: true });
+  });
+
+  it('round-trips through the case directory', async () => {
+    const marker = buildAgentCaseMarker({
+      createdBy: AGENT_ORIGIN_CODEMAN_SKILL,
+      parentSessionId: 'sess-1',
+      mode: 'claude',
+    });
+    expect(await writeAgentCaseMarker(caseDir, marker)).toBe(true);
+    expect(await readAgentCaseMarker(caseDir)).toEqual(marker);
+  });
+
+  it('writes a note explaining the file to whoever finds it', async () => {
+    await writeAgentCaseMarker(caseDir, buildAgentCaseMarker({ createdBy: AGENT_ORIGIN_CODEMAN_SKILL }));
+    const raw = JSON.parse(await readFile(join(caseDir, AGENT_CASE_MARKER_FILE), 'utf-8'));
+    expect(raw.note).toContain('Delete this file');
+  });
+
+  it('reports failure instead of throwing when the directory is missing', async () => {
+    // Best-effort by design: a marker that cannot be written must not fail the spawn.
+    const written = await writeAgentCaseMarker(join(caseDir, 'nope'), buildAgentCaseMarker({ createdBy: 'x-agent' }));
+    expect(written).toBe(false);
+  });
+
+  it('reads an absent or corrupt marker as not-agent-created', async () => {
+    expect(await readAgentCaseMarker(caseDir)).toBeNull();
+    await writeFile(join(caseDir, AGENT_CASE_MARKER_FILE), '{ truncated', 'utf-8');
+    expect(await readAgentCaseMarker(caseDir)).toBeNull();
+  });
+});

test/agent-skill.test.ts

@@ -11,7 +11,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtemp, rm, mkdir, writeFile, readFile, symlink, readdir, stat } from 'node:fs/promises';
+import { mkdtemp, rm, mkdir, writeFile, readFile, symlink, readdir, stat, utimes } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir, homedir } from 'node:os';
@@ -21,10 +21,25 @@ import {
   removeAgentSkillFrom,
   refreshUserAgentSkill,
   seedAgentSessionPreamble,
+  removeAgentSessionPreamble,
+  pruneAgentSessionPreambles,
 } from '../src/hooks-config.js';
 
 const MARKER_PREFIX = '<!-- codeman-managed-agent-skill';
 
+/** Run `fn` against a throwaway XDG cache dir, restoring the env afterwards. */
+async function withCacheDir(fn: (cacheDir: string) => Promise<void>): Promise<void> {
+  const prevXdg = process.env.XDG_CACHE_HOME;
+  const cacheDir = join(casePath, 'xdg-cache');
+  process.env.XDG_CACHE_HOME = cacheDir;
+  try {
+    await fn(cacheDir);
+  } finally {
+    if (prevXdg === undefined) delete process.env.XDG_CACHE_HOME;
+    else process.env.XDG_CACHE_HOME = prevXdg;
+  }
+}
+
 let casePath: string;
 const skillDir = () => join(casePath, '.claude', 'skills', 'codeman');
 
@@ -165,6 +180,57 @@ describe('preamble single-source (seed + §0 heredoc parity)', () => {
     }
   });
 
+  it('removeAgentSessionPreamble drops one session cache and shrugs at a missing one', async () => {
+    // Seeding writes one file per claude session and nothing used to remove them
+    // (236 leftovers measured on a working machine); session teardown calls this.
+    await withCacheDir(async (cacheDir) => {
+      await seedAgentSessionPreamble('gone-session');
+      expect(existsSync(join(cacheDir, 'codeman-agent-gone-session.sh'))).toBe(true);
+
+      await removeAgentSessionPreamble('gone-session');
+      expect(existsSync(join(cacheDir, 'codeman-agent-gone-session.sh'))).toBe(false);
+
+      await expect(removeAgentSessionPreamble('never-existed')).resolves.toBeUndefined();
+    });
+  });
+
+  it('pruneAgentSessionPreambles takes only aged caches with no live session behind them', async () => {
+    await withCacheDir(async (cacheDir) => {
+      const aged = (name: string) => join(cacheDir, name);
+      for (const id of ['live-old', 'dead-old', 'dead-fresh']) {
+        await seedAgentSessionPreamble(id);
+      }
+      // Age two of them past the cutoff; `dead-fresh` stays new.
+      const old = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+      await utimes(aged('codeman-agent-live-old.sh'), old, old);
+      await utimes(aged('codeman-agent-dead-old.sh'), old, old);
+      // An unrelated file in the same cache dir must be invisible to the sweep.
+      await writeFile(aged('someone-elses-file.sh'), 'not ours\n');
+
+      const removed = await pruneAgentSessionPreambles(['live-old']);
+
+      expect(removed).toBe(1);
+      expect(existsSync(aged('codeman-agent-dead-old.sh'))).toBe(false);
+      // A live session's cache is load-bearing: the skill's two-line loader reads it
+      // mid-run, so age alone must never take it.
+      expect(existsSync(aged('codeman-agent-live-old.sh'))).toBe(true);
+      // And a recently-seeded one belongs to a session this process may not know about.
+      expect(existsSync(aged('codeman-agent-dead-fresh.sh'))).toBe(true);
+      expect(existsSync(aged('someone-elses-file.sh'))).toBe(true);
+    });
+  });
+
+  it('pruneAgentSessionPreambles reports 0 rather than throwing when there is no cache dir', async () => {
+    const prevXdg = process.env.XDG_CACHE_HOME;
+    process.env.XDG_CACHE_HOME = join(casePath, 'no-such-cache');
+    try {
+      expect(await pruneAgentSessionPreambles([])).toBe(0);
+    } finally {
+      if (prevXdg === undefined) delete process.env.XDG_CACHE_HOME;
+      else process.env.XDG_CACHE_HOME = prevXdg;
+    }
+  });
+
   it('seedAgentSessionPreamble falls back to ~/.cache when XDG_CACHE_HOME is unset', async () => {
     const prevXdg = process.env.XDG_CACHE_HOME;
     delete process.env.XDG_CACHE_HOME;

test/cli-registry-schema.test.ts

@@ -17,6 +17,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { CliEntrySchema } from '../src/config/cli-registry/schema.js';
+import { compileVersionRegex } from '../src/config/cli-registry/patterns.js';
 import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
 import type { CliEntry } from '../src/config/cli-registry/types.js';
 
@@ -75,6 +76,34 @@ describe('strictness', () => {
   });
 });
 
+describe('workDetect.workingLine is guarded like every other config regex', () => {
+  it('rejects a nested quantifier', () => {
+    expectRejected((e) => {
+      (e.capabilities as Record<string, unknown>).workDetect = { promptGlyph: '>', workingLine: '(a+)+b' };
+    }, 'this pattern is compiled once and then run against every accumulated PTY chunk, so catastrophic backtracking here freezes the event loop for the whole server');
+  });
+
+  it('rejects a source longer than compileVersionRegex() will compile', () => {
+    expectRejected((e) => {
+      (e.capabilities as Record<string, unknown>).workDetect = { promptGlyph: '>', workingLine: 'a'.repeat(201) };
+    }, 'the schema must not accept a pattern the runtime will then refuse to compile, or the CLI silently falls back to the Claude pattern');
+  });
+
+  it('rejects a pattern that is not a regex at all', () => {
+    expectRejected((e) => {
+      (e.capabilities as Record<string, unknown>).workDetect = { promptGlyph: '>', workingLine: '([unclosed' };
+    }, 'a broken pattern must fail at LOAD time, not inside the PTY data handler');
+  });
+
+  it('accepts both shipped patterns unchanged', () => {
+    for (const entry of STOCK_CLIS) {
+      const src = entry.capabilities.workDetect?.workingLine;
+      if (!src) continue;
+      expect(compileVersionRegex(src), `${entry.id} declares a workingLine the guard refuses`).not.toBeNull();
+    }
+  });
+});
+
 describe('no shell text can reach the command line', () => {
   it('rejects a literal carrying shell metacharacters', () => {
     for (const evil of ['pi; rm -rf /', 'pi && curl evil.sh', 'pi`whoami`', 'pi $(id)', 'pi | tee', 'pi > /etc/x']) {

test/codex-resume-alias-survives-start.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview A resumed codex session must keep its thread-id alias across
+ * `start()`, not just at construction.
+ *
+ * `claudeSessionId` doubles as the generic "external transcript id" the unified
+ * list folds a Past-Sessions row into its owning session by. For codex that id
+ * is the rollout's thread id, and losing it is not cosmetic: the stale row stays
+ * in PAST and still resumes, so clicking it starts a SECOND `codex resume` on a
+ * thread already open in the live pane.
+ *
+ * The bug this pins: the alias was wired into the constructor only. `start()`
+ * recomputes `claudeSessionId` at two further points — the mux branch and the
+ * unconditional "third reset point" that runs after both the mux and direct-PTY
+ * paths — and both listed only Claude's `resumeSessionId` and omp's. For codex
+ * both are undefined, so every mux reattach and every boot recovery reset the
+ * alias back to the Codeman id and the duplicate came back. The existing comment
+ * at the third reset point already warned that omitting omp's fallback there
+ * "stomps the mux branch's correctly-resolved OMP alias"; codex needed the same.
+ *
+ * Mirrors `test/omp-fresh-run-no-resume.test.ts`, which drives a real `Session`
+ * against the in-memory tmux layer that vitest substitutes.
+ */
+import { mkdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Session } from '../src/session.js';
+import { TmuxManager } from '../src/tmux-manager.js';
+
+describe('codex: a resumed thread id survives start()', () => {
+  const workingDir = join(homedir(), 'codeman-cases', 'codex-resume-alias');
+  const THREAD_ID = '01a060f0-0361-7f91-abde-b283020db0d7';
+  const sessions: Session[] = [];
+
+  afterEach(() => {
+    for (const s of sessions.splice(0)) s.stop();
+    rmSync(workingDir, { recursive: true, force: true });
+  });
+
+  function makeSession(useMux: boolean): Session {
+    mkdirSync(workingDir, { recursive: true });
+    const session = new Session({
+      workingDir,
+      mode: 'codex',
+      codexConfig: { resumeSessionId: THREAD_ID },
+      mux: new TmuxManager(),
+      useMux,
+    });
+    sessions.push(session);
+    return session;
+  }
+
+  it('carries the thread id from construction', () => {
+    expect(makeSession(true).claudeSessionId).toBe(THREAD_ID);
+  });
+
+  it('still carries it after starting under mux', async () => {
+    const session = makeSession(true);
+    await session.startInteractive();
+    expect(session.claudeSessionId).toBe(THREAD_ID);
+  });
+
+  it('refuses to start without mux at all, so the mux path is the only one to cover', async () => {
+    // codex declares `requiresMux`, so there is no direct-PTY codex session for
+    // the third reset point to run against on its own — the assertion above is
+    // the whole surface.
+    await expect(makeSession(false).startInteractive()).rejects.toThrow(/require tmux/i);
+  });
+
+  it('a fresh codex session keeps the Codeman id, having no thread of its own', async () => {
+    mkdirSync(workingDir, { recursive: true });
+    const session = new Session({ workingDir, mode: 'codex', mux: new TmuxManager(), useMux: true });
+    sessions.push(session);
+
+    await session.startInteractive();
+
+    // Nothing to alias to yet — codex has not written the rollout. Such a
+    // session is folded from the other side, by originator (codexThreadBySessionId).
+    expect(session.claudeSessionId).toBe(session.id);
+  });
+});

test/codex-transcript.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Reading codex's own rollout store for Past Sessions rows.
+ *
+ * Three of these assertions exist because the obvious implementation was
+ * measured to be wrong against real files (codex CLI 0.152.1):
+ *
+ * - codex 0.152.1 emits NO `event_msg`/`user_message` rows at all. It writes
+ *   `event_msg`/`item_completed` carrying an `item.type` of `UserMessage`
+ *   instead, so a scanner that knew only the older shape found a prompt for
+ *   July rollouts and nothing for September ones.
+ * - the `response_item` fallback sees codex's injected context, and on a real
+ *   store the FIRST such row is the repository's AGENTS.md every time. Taking
+ *   it literally titled every row with the same instructions block.
+ * - codex spawns sub-agent threads into the same store, stamped
+ *   `thread_source: 'subagent'`. On the store this was built against they
+ *   outnumbered the threads a person can actually resume.
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { appendFile, mkdtemp, mkdir, writeFile, rm, utimes } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import {
+  scanCodexSessionsHistory,
+  codexThreadBySessionId,
+  __clearCodexIdentityCache,
+} from '../src/codex-transcript.js';
+
+let home: string;
+let prevCodexHome: string | undefined;
+
+/** A rollout's opening line, as codex writes it. */
+const sessionMeta = (opts: { id: string; cwd?: string; threadSource?: string; originator?: string }) =>
+  JSON.stringify({
+    timestamp: '2026-09-02T07:05:37.421Z',
+    type: 'session_meta',
+    payload: {
+      id: opts.id,
+      session_id: opts.id,
+      ...(opts.cwd ? { cwd: opts.cwd } : {}),
+      originator: opts.originator ?? 'codex-tui',
+      ...(opts.threadSource ? { thread_source: opts.threadSource } : {}),
+      // The real thing embeds full base instructions here; padded so the file
+      // clears the size floor and exercises the head window.
+      base_instructions: { text: 'x'.repeat(500) },
+    },
+  });
+
+/** codex 0.152.1's user-input row. */
+const itemCompletedUser = (text: string) =>
+  JSON.stringify({
+    type: 'event_msg',
+    payload: { type: 'item_completed', item: { type: 'UserMessage', id: 'i1', content: [{ type: 'text', text }] } },
+  });
+
+/** The shape older codex versions wrote. */
+const legacyUserMessage = (text: string) =>
+  JSON.stringify({ type: 'event_msg', payload: { type: 'user_message', message: text } });
+
+/** The last-resort shape, which also carries codex's injected context. */
+const responseItemUser = (text: string) =>
+  JSON.stringify({ type: 'response_item', payload: { role: 'user', content: [{ type: 'text', text }] } });
+
+async function writeRollout(id: string, lines: string[], mtime?: Date): Promise<string> {
+  const dir = join(home, 'sessions', '2026', '09', '02');
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `rollout-2026-09-02T09-05-37-${id}.jsonl`);
+  await writeFile(path, lines.join('\n') + '\n', 'utf-8');
+  if (mtime) await utimes(path, mtime, mtime);
+  return path;
+}
+
+beforeEach(async () => {
+  home = await mkdtemp(join(tmpdir(), 'codex-transcript-'));
+  prevCodexHome = process.env.CODEX_HOME;
+  process.env.CODEX_HOME = home;
+  __clearCodexIdentityCache();
+});
+
+afterEach(async () => {
+  if (prevCodexHome === undefined) delete process.env.CODEX_HOME;
+  else process.env.CODEX_HOME = prevCodexHome;
+  await rm(home, { recursive: true, force: true });
+});
+
+describe('scanCodexSessionsHistory', () => {
+  it('returns nothing when the store does not exist', async () => {
+    process.env.CODEX_HOME = join(home, 'nope');
+    expect(await scanCodexSessionsHistory()).toEqual([]);
+  });
+
+  it('reads the thread id, working directory and opening prompt', async () => {
+    await writeRollout('01a060f0-0361-7f91-abde-b283020db0d7', [
+      sessionMeta({ id: '01a060f0-0361-7f91-abde-b283020db0d7', cwd: '/repo/one' }),
+      itemCompletedUser('Continue the audit log architecture'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].sessionId).toBe('01a060f0-0361-7f91-abde-b283020db0d7');
+    expect(rows[0].workingDir).toBe('/repo/one');
+    expect(rows[0].firstPrompt).toBe('Continue the audit log architecture');
+    expect(rows[0].sizeBytes).toBeGreaterThan(0);
+  });
+
+  it('still reads the prompt shape older codex versions wrote', async () => {
+    await writeRollout('11111111-1111-7111-8111-111111111111', [
+      sessionMeta({ id: '11111111-1111-7111-8111-111111111111', cwd: '/repo/two' }),
+      legacyUserMessage('$pr-review-comment-fixer 349'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].firstPrompt).toBe('$pr-review-comment-fixer 349');
+  });
+
+  it('skips injected context when only the fallback shape is present', async () => {
+    await writeRollout('22222222-2222-7222-8222-222222222222', [
+      sessionMeta({ id: '22222222-2222-7222-8222-222222222222', cwd: '/repo/three' }),
+      responseItemUser('# AGENTS.md instructions for /repo/three\n<INSTRUCTIONS> ...'),
+      responseItemUser('<environment_context>cwd=/repo/three</environment_context>'),
+      responseItemUser('Replace PanicOnError with Require().NoError'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].firstPrompt).toBe('Replace PanicOnError with Require().NoError');
+  });
+
+  it('prefers a real user row over the injection-prone fallback', async () => {
+    await writeRollout('33333333-3333-7333-8333-333333333333', [
+      sessionMeta({ id: '33333333-3333-7333-8333-333333333333', cwd: '/repo/four' }),
+      responseItemUser('Some earlier response_item row'),
+      itemCompletedUser('The prompt the user actually typed'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].firstPrompt).toBe('The prompt the user actually typed');
+  });
+
+  it('leaves out sub-agent threads, which nobody resumes', async () => {
+    await writeRollout('44444444-4444-7444-8444-444444444444', [
+      sessionMeta({ id: '44444444-4444-7444-8444-444444444444', cwd: '/repo/five' }),
+      itemCompletedUser('a real conversation'),
+    ]);
+    await writeRollout('55555555-5555-7555-8555-555555555555', [
+      sessionMeta({ id: '55555555-5555-7555-8555-555555555555', cwd: '/repo/five', threadSource: 'subagent' }),
+      itemCompletedUser('work codex gave itself'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows.map((r) => r.sessionId)).toEqual(['44444444-4444-7444-8444-444444444444']);
+  });
+
+  it('reports the most recent prompt as well as the first', async () => {
+    await writeRollout('66666666-6666-7666-8666-666666666666', [
+      sessionMeta({ id: '66666666-6666-7666-8666-666666666666', cwd: '/repo/six' }),
+      itemCompletedUser('the opening question'),
+      itemCompletedUser('a follow-up'),
+      itemCompletedUser('the latest thing asked'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].firstPrompt).toBe('the opening question');
+    expect(rows[0].lastPrompt).toBe('the latest thing asked');
+  });
+
+  it('orders rows newest first', async () => {
+    await writeRollout(
+      '77777777-7777-7777-8777-777777777777',
+      [sessionMeta({ id: '77777777-7777-7777-8777-777777777777', cwd: '/repo/old' }), itemCompletedUser('older')],
+      new Date('2026-08-01T00:00:00Z')
+    );
+    await writeRollout(
+      '88888888-8888-7888-8888-888888888888',
+      [sessionMeta({ id: '88888888-8888-7888-8888-888888888888', cwd: '/repo/new' }), itemCompletedUser('newer')],
+      new Date('2026-09-05T00:00:00Z')
+    );
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows.map((r) => r.workingDir)).toEqual(['/repo/new', '/repo/old']);
+  });
+
+  it('ignores a file too short to hold a session_meta line', async () => {
+    const dir = join(home, 'sessions', '2026', '09', '02');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'rollout-2026-09-02T09-05-37-short.jsonl'), '{}\n', 'utf-8');
+
+    expect(await scanCodexSessionsHistory()).toEqual([]);
+  });
+
+  it('survives a rollout whose lines are malformed', async () => {
+    await writeRollout('99999999-9999-7999-8999-999999999999', [
+      sessionMeta({ id: '99999999-9999-7999-8999-999999999999', cwd: '/repo/seven' }),
+      '{not json at all',
+      itemCompletedUser('still found me'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].firstPrompt).toBe('still found me');
+  });
+
+  it('reports the originator, which is how a fresh pane finds its own rollout', async () => {
+    await writeRollout('bbbbbbbb-bbbb-7bbb-8bbb-bbbbbbbbbbbb', [
+      sessionMeta({
+        id: 'bbbbbbbb-bbbb-7bbb-8bbb-bbbbbbbbbbbb',
+        cwd: '/repo/nine',
+        originator: 'codeman_2f1c9a44-1111-2222-3333-444455556666',
+      }),
+      itemCompletedUser('hello'),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].originator).toBe('codeman_2f1c9a44-1111-2222-3333-444455556666');
+  });
+
+  it('drops a rollout that records no working directory', async () => {
+    // Emitting workingDir: '' would make a click post an empty directory.
+    await writeRollout('cccccccc-cccc-7ccc-8ccc-cccccccccccc', [
+      sessionMeta({ id: 'cccccccc-cccc-7ccc-8ccc-cccccccccccc' }),
+      itemCompletedUser('nowhere to resume into'),
+    ]);
+
+    expect(await scanCodexSessionsHistory()).toEqual([]);
+  });
+
+  it('picks up a prompt written after an earlier scan saw none', async () => {
+    // The bug this pins: the identity cache was written as soon as the thread id
+    // was known, but codex writes the first UserMessage only when the user
+    // submits. Any scan in that window — the home screen, the command palette,
+    // the search-index refresh — pinned `firstPrompt: undefined` until restart.
+    const id = 'dddddddd-dddd-7ddd-8ddd-dddddddddddd';
+    const path = await writeRollout(id, [sessionMeta({ id, cwd: '/repo/ten' })]);
+
+    const before = await scanCodexSessionsHistory();
+    expect(before).toHaveLength(1);
+    expect(before[0].firstPrompt).toBeUndefined();
+
+    await appendFile(path, itemCompletedUser('the prompt, typed a moment later') + '\n', 'utf-8');
+
+    const after = await scanCodexSessionsHistory();
+    expect(after[0].firstPrompt).toBe('the prompt, typed a moment later');
+  });
+
+  it('does not spend the lastPrompt budget on rollouts it never returns', async () => {
+    // The budget used to count file index, so a store whose newest files are all
+    // sub-agent threads exhausted it before the first row that needed it.
+    for (let i = 0; i < 3; i++) {
+      await writeRollout(
+        `eeeeeeee-eeee-7eee-8eee-00000000000${i}`,
+        [
+          sessionMeta({ id: `eeeeeeee-eeee-7eee-8eee-00000000000${i}`, cwd: '/repo/sub', threadSource: 'subagent' }),
+          itemCompletedUser('subagent work'),
+        ],
+        new Date('2026-09-05T00:00:00Z')
+      );
+    }
+    await writeRollout(
+      'ffffffff-ffff-7fff-8fff-ffffffffffff',
+      [
+        sessionMeta({ id: 'ffffffff-ffff-7fff-8fff-ffffffffffff', cwd: '/repo/real' }),
+        itemCompletedUser('opening'),
+        itemCompletedUser('the latest thing asked'),
+      ],
+      new Date('2026-09-04T00:00:00Z')
+    );
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].lastPrompt).toBe('the latest thing asked');
+  });
+
+  it('collapses a long prompt to a single capped line', async () => {
+    await writeRollout('aaaaaaaa-aaaa-7aaa-8aaa-aaaaaaaaaaaa', [
+      sessionMeta({ id: 'aaaaaaaa-aaaa-7aaa-8aaa-aaaaaaaaaaaa', cwd: '/repo/eight' }),
+      itemCompletedUser('line one\nline two\n' + 'y'.repeat(500)),
+    ]);
+
+    const rows = await scanCodexSessionsHistory();
+    expect(rows[0].firstPrompt).not.toContain('\n');
+    expect(rows[0].firstPrompt!.length).toBeLessThanOrEqual(201);
+    expect(rows[0].firstPrompt!.endsWith('…')).toBe(true);
+  });
+});
+
+describe('codexThreadBySessionId', () => {
+  const row = (sessionId: string, originator?: string) =>
+    ({ sessionId, originator, workingDir: '/w', sizeBytes: 1, lastModified: '2026-09-02T00:00:00.000Z' }) as never;
+
+  it('maps a Codeman-spawned pane to the thread it is writing', () => {
+    const map = codexThreadBySessionId([row('thread-a', 'codeman_sess-1')]);
+    expect(map.get('sess-1')).toBe('thread-a');
+  });
+
+  it('ignores a rollout codex started on its own', () => {
+    expect(codexThreadBySessionId([row('thread-a', 'codex-tui')]).size).toBe(0);
+    expect(codexThreadBySessionId([row('thread-a', undefined)]).size).toBe(0);
+  });
+
+  it('keeps the newest rollout when a pane has several', () => {
+    // `/new` inside the codex TUI leaves the pane's originator on more than one
+    // rollout; the pane is on the most recent, and rows arrive newest-first.
+    const map = codexThreadBySessionId([row('thread-new', 'codeman_sess-1'), row('thread-old', 'codeman_sess-1')]);
+    expect(map.get('sess-1')).toBe('thread-new');
+  });
+});

test/command-palette-ui.test.ts

@@ -397,11 +397,13 @@ describe('Session Manager unified list', () => {
     expect(app.selectSession).toHaveBeenCalledWith('sess-alpha');
     expect(app.resumeHistorySession).not.toHaveBeenCalled();
 
-    // History row → resume by conversation UUID.
+    // History row → resume by conversation UUID. The trailing `resumeId` is the
+    // CLI's own thread token, which only a non-claude transcript scanner sets;
+    // a Claude row carries none, so it arrives undefined here.
     const [historyRecord, , historyOptions] = app._buildHistoryItem.mock.calls[1];
     expect(historyRecord).toMatchObject({ sessionId: 'conv-uuid-1', sizeBytes: 2048, firstPrompt: 'old prompt' });
     historyOptions.onActivate();
-    expect(app.resumeHistorySession).toHaveBeenCalledWith('conv-uuid-1', '/repo/old', undefined, undefined);
+    expect(app.resumeHistorySession).toHaveBeenCalledWith('conv-uuid-1', '/repo/old', undefined, undefined, undefined);
   });
 
   it('surfaces an error message instead of an empty list when the endpoint fails', async () => {

test/mobile-overview.test.ts

@@ -224,6 +224,37 @@ describe('mobile overview model', () => {
     expect(model.past[0].title).toBe('w4-claudeman');
   });
 
+  it('carries resumeId through to the past row so a Codex tap resumes its thread', () => {
+    const app = loadOverviewApp();
+    const model = app.buildMobileOverviewModel({
+      sessions: [],
+      cases: CASES,
+      history: [
+        {
+          sessionId: 'rollout-1',
+          workingDir: '/home/arkon/codeman-cases/beta',
+          firstPrompt: 'port the parser',
+          mode: 'codex',
+          resumeId: 'codex-thread-id',
+          lastActivityAt: 300,
+        },
+        // A claude row carries none, and must not grow one.
+        {
+          sessionId: 'claude-1',
+          workingDir: '/home/arkon/default/claudeman',
+          claudeSessionId: 'claude-uuid-a',
+          lastActivityAt: 200,
+        },
+      ],
+    });
+
+    // resumeMobileOverviewSession() reads row.resumeId off exactly this projection and
+    // hands it to resumeHistorySession(); an undefined here is a fresh codex session on
+    // a thread that already exists, which is the phone-only half of the resume feature.
+    expect(model.past[0]).toMatchObject({ mode: 'codex', resumeId: 'codex-thread-id' });
+    expect(model.past[1].resumeId).toBeUndefined();
+  });
+
   it('does not title a past row with the transcript reader placeholder', () => {
     const app = loadOverviewApp();
     const model = app.buildMobileOverviewModel({

test/resume-history-mode-fidelity.test.ts

@@ -90,7 +90,7 @@ describe('resumeHistorySession: row retirement is gated on actual continuation',
     fetchMock = stubFetch('new-session-id');
   });
 
-  it.each(['codex', 'gemini', 'antigravity'])(
+  it.each(['gemini', 'antigravity'])(
     'does NOT retire the old row for %s (no continuation is wired for it)',
     async (mode) => {
       const app = makeApp();
@@ -104,6 +104,44 @@ describe('resumeHistorySession: row retirement is gated on actual continuation',
     }
   );
 
+  // codex continues only when the row carried its thread id. A row without one
+  // is a live session's row, whose sessionId is Codeman's own uuid — sending
+  // THAT to `codex resume` asks for a thread that does not exist, so it must
+  // stay a fresh session and must not retire the row it came from.
+  it('does NOT continue or retire a codex row that carries no resumeId', async () => {
+    const app = makeApp();
+    await app.resumeHistorySession.call(app, 'codeman-uuid', '/repo', 'w1-repo', 'codex');
+
+    expect(createBody(fetchMock)).toMatchObject({ mode: 'codex' });
+    expect(createBody(fetchMock).codexConfig).toBeUndefined();
+    expect(deleteCalls(fetchMock)).toEqual([]);
+  });
+
+  it('resumes a codex row by the thread id the row carried', async () => {
+    const app = makeApp();
+    await app.resumeHistorySession.call(
+      app,
+      '01a060f0-0361-7f91-abde-b283020db0d7',
+      '/repo',
+      'w1-repo',
+      'codex',
+      '01a060f0-0361-7f91-abde-b283020db0d7'
+    );
+
+    expect(createBody(fetchMock)).toMatchObject({
+      mode: 'codex',
+      codexConfig: { resumeSessionId: '01a060f0-0361-7f91-abde-b283020db0d7' },
+    });
+  });
+
+  it('ignores a resumeId on a row that is not codex', async () => {
+    const app = makeApp();
+    await app.resumeHistorySession.call(app, 'old-id', '/repo', 'w1-repo', 'gemini', 'some-thread-id');
+
+    expect(createBody(fetchMock).codexConfig).toBeUndefined();
+    expect(deleteCalls(fetchMock)).toEqual([]);
+  });
+
   it.each([
     ['opencode', 'openCodeConfig'],
     ['pi', 'piConfig'],

test/routes/agent-case-marker-routes.test.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview End-to-end wiring of the agent-case label: quick-start writes the
+ * marker, the case list publishes it, and `GET /api/cases/agent-created` reports it
+ * for cleanup.
+ *
+ * The rules under test are the ones that decide whether the cleanup list can be
+ * trusted: only a directory quick-start CREATES is ever labelled (a pre-existing
+ * case — a linked repo, a real project — never is), a spawn with no agent signal at
+ * all leaves no marker, the lineage header alone is enough to label one (that is how
+ * a stale skill copy still gets swept up), and a case a live session is working in is
+ * reported as `inUse` rather than silently offered up for deletion.
+ *
+ * Real filesystem against the per-file temp HOME from test/setup.ts, so the marker is
+ * asserted as bytes on disk rather than through a mock.
+ *
+ * Port: N/A (app.inject()).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { mkdir, rm, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createMockRouteContext, createMockSession, type MockRouteContext } from '../mocks/index.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+import { registerCaseRoutes } from '../../src/web/routes/case-routes.js';
+import { getCasesDir } from '../../src/config/cases-dir.js';
+import { AGENT_CASE_MARKER_FILE } from '../../src/agent-case-marker.js';
+import type { AgentCaseSummary, CaseInfo } from '../../src/types.js';
+
+const PARENT_ID = 'test-session-1'; // the id the mock context pre-populates
+
+interface Harness {
+  app: FastifyInstance;
+  ctx: MockRouteContext;
+}
+
+async function createHarness(): Promise<Harness> {
+  const app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+  const ctx = createMockRouteContext();
+  registerSessionRoutes(app, ctx);
+  registerCaseRoutes(app, ctx);
+  installRouteErrorHandler(app);
+  await app.ready();
+  return { app, ctx };
+}
+
+describe('agent-created case marker', () => {
+  let harness: Harness;
+  const created: string[] = [];
+
+  /** Spawn a worker through quick-start, the skill's usual route. */
+  async function quickStart(caseName: string, opts: { headers?: Record<string, string>; payload?: object } = {}) {
+    created.push(caseName);
+    return harness.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      headers: opts.headers,
+      payload: { caseName, mode: 'claude', ...(opts.payload ?? {}) },
+    });
+  }
+
+  const markerPath = (caseName: string) => join(getCasesDir(), caseName, AGENT_CASE_MARKER_FILE);
+
+  async function readMarker(caseName: string): Promise<Record<string, unknown> | null> {
+    try {
+      return JSON.parse(await readFile(markerPath(caseName), 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
+
+  async function listCases(): Promise<CaseInfo[]> {
+    const res = await harness.app.inject({ method: 'GET', url: '/api/cases' });
+    const body = JSON.parse(res.body);
+    return (body.data ?? body) as CaseInfo[];
+  }
+
+  async function listAgentCases(): Promise<AgentCaseSummary[]> {
+    const res = await harness.app.inject({ method: 'GET', url: '/api/cases/agent-created' });
+    expect(res.statusCode).toBe(200);
+    return JSON.parse(res.body).data.cases as AgentCaseSummary[];
+  }
+
+  beforeEach(async () => {
+    harness = await createHarness();
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+    for (const name of created.splice(0)) {
+      await rm(join(getCasesDir(), name), { recursive: true, force: true });
+    }
+  });
+
+  it('labels a case directory created for a spawn carrying the skill origin header', async () => {
+    const res = await quickStart('agentcase1', {
+      headers: { 'x-codeman-agent-origin': 'codeman-skill', 'x-codeman-parent-session': PARENT_ID },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const marker = await readMarker('agentcase1');
+    expect(marker).toMatchObject({
+      version: 1,
+      createdBy: 'codeman-skill',
+      parentSessionId: PARENT_ID,
+      mode: 'claude',
+    });
+    expect(Date.parse(String(marker?.createdAt))).not.toBeNaN();
+  });
+
+  it('accepts the origin as a body field too, with the body winning', async () => {
+    await quickStart('agentcase2', {
+      headers: { 'x-codeman-agent-origin': 'codeman-skill' },
+      payload: { agentOrigin: 'my-orchestrator' },
+    });
+
+    expect(await readMarker('agentcase2')).toMatchObject({ createdBy: 'my-orchestrator' });
+  });
+
+  it('labels a spawn that carries only the lineage header, which is how an older skill copy still gets swept up', async () => {
+    await quickStart('agentcase3', { headers: { 'x-codeman-parent-session': PARENT_ID } });
+
+    expect(await readMarker('agentcase3')).toMatchObject({
+      createdBy: 'agent-session',
+      parentSessionId: PARENT_ID,
+    });
+  });
+
+  it('writes NO marker for a spawn with no agent signal at all', async () => {
+    // A human clicking Run in the browser sets neither header, and their case must
+    // not turn up in a cleanup list.
+    await quickStart('humancase1');
+
+    expect(await readMarker('humancase1')).toBeNull();
+  });
+
+  it('never labels a directory that already existed', async () => {
+    // The linchpin: a linked case or a real repo is not ours to offer for deletion,
+    // and the create branch is the only place the marker may be written.
+    const name = 'preexisting1';
+    created.push(name);
+    await mkdir(join(getCasesDir(), name), { recursive: true });
+
+    const res = await harness.app.inject({
+      method: 'POST',
+      url: '/api/quick-start',
+      headers: { 'x-codeman-agent-origin': 'codeman-skill' },
+      payload: { caseName: name, mode: 'claude' },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(await readMarker(name)).toBeNull();
+  });
+
+  it('drops an unrecognised origin token rather than storing it', async () => {
+    await quickStart('agentcase4', { payload: { agentOrigin: '<script>alert(1)</script>' } });
+
+    // No parent either, so nothing labels this one at all.
+    expect(await readMarker('agentcase4')).toBeNull();
+  });
+
+  it('still spawns the worker when the origin is bogus', async () => {
+    const res = await quickStart('agentcase5', { payload: { agentOrigin: 'not a token' } });
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).sessionId ?? JSON.parse(res.body).data?.sessionId).toBeTruthy();
+  });
+
+  it('publishes the label on GET /api/cases and hides it from cases without one', async () => {
+    await quickStart('agentcase6', { headers: { 'x-codeman-agent-origin': 'codeman-skill' } });
+    await quickStart('humancase2');
+
+    const cases = await listCases();
+    expect(cases.find((c) => c.name === 'agentcase6')?.agentCreated).toMatchObject({ createdBy: 'codeman-skill' });
+    expect(cases.find((c) => c.name === 'humancase2')?.agentCreated).toBeUndefined();
+  });
+
+  it('lists only agent cases in the cleanup listing, newest first', async () => {
+    await quickStart('agentcase7', { headers: { 'x-codeman-agent-origin': 'codeman-skill' } });
+    await quickStart('humancase3');
+
+    const listed = await listAgentCases();
+    expect(listed.map((c) => c.name)).toContain('agentcase7');
+    expect(listed.map((c) => c.name)).not.toContain('humancase3');
+    const sorted = [...listed].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    expect(listed.map((c) => c.name)).toEqual(sorted.map((c) => c.name));
+  });
+
+  it('flags a case a live session is still working in as inUse', async () => {
+    // Deleting one of these would pull the rug out from under a running worker, so
+    // the UI excludes it rather than confirming it away.
+    await quickStart('agentcase8', { headers: { 'x-codeman-agent-origin': 'codeman-skill' } });
+    const busyPath = join(getCasesDir(), 'agentcase8');
+    const busy = createMockSession('busy-session') as unknown as { workingDir: string };
+    busy.workingDir = busyPath;
+    harness.ctx.sessions.set('busy-session', busy as never);
+
+    const entry = (await listAgentCases()).find((c) => c.name === 'agentcase8');
+    expect(entry?.inUse).toBe(true);
+    expect(entry?.path).toBe(busyPath);
+  });
+
+  it('reports a marker-less case space as an empty list rather than failing', async () => {
+    expect(await listAgentCases()).toEqual([]);
+  });
+});

test/services/unified-session-service.test.ts

@@ -14,6 +14,94 @@ import {
 } from '../../src/services/unified-session-service.js';
 
 describe('mergeUnifiedSessions', () => {
+  // A codex conversation showing twice is worse than cosmetic: the stale PAST row
+  // still resumes, so clicking it starts a SECOND `codex resume` on a thread
+  // already open in another pane. Both folds below are what prevent that.
+  it('folds a RESUMED codex session into its own rollout row', () => {
+    // Session sets claudeSessionId from codexConfig.resumeSessionId, so the live
+    // row already names the thread the rollout is keyed by.
+    const merged = mergeUnifiedSessions({
+      live: [{ id: 'codeman-uuid', status: 'idle', mode: 'codex', claudeSessionId: 'codex-thread-id' }],
+      history: [
+        {
+          sessionId: 'codex-thread-id',
+          workingDir: '/w',
+          sizeBytes: 4000,
+          lastModified: '2026-09-02T00:00:00.000Z',
+          mode: 'codex',
+          resumeId: 'codex-thread-id',
+        },
+      ],
+    });
+    expect(merged).toHaveLength(1);
+    expect(merged[0].sessionId).toBe('codeman-uuid');
+    expect([...merged[0].sources].sort()).toEqual(['history', 'live']);
+  });
+
+  it('folds a FRESH codex session once its rollout has been matched by originator', () => {
+    // A fresh pane knows no thread id, so gatherUnifiedInputs() stamps one onto
+    // the live row from session_meta.originator (see codexThreadBySessionId).
+    // This is that stamped row.
+    const merged = mergeUnifiedSessions({
+      live: [{ id: 'codeman-uuid', status: 'busy', mode: 'codex', claudeSessionId: 'fresh-thread-id' }],
+      persisted: [{ id: 'codeman-uuid', status: 'idle', mode: 'codex', claudeSessionId: 'fresh-thread-id' }],
+      history: [
+        {
+          sessionId: 'fresh-thread-id',
+          workingDir: '/w',
+          sizeBytes: 900,
+          lastModified: '2026-09-02T00:00:00.000Z',
+          mode: 'codex',
+          resumeId: 'fresh-thread-id',
+        },
+      ],
+    });
+    expect(merged).toHaveLength(1);
+    expect(merged[0].sessionId).toBe('codeman-uuid');
+    expect(merged[0].status).toBe('busy');
+  });
+
+  it('leaves an unrelated codex rollout as its own row', () => {
+    const merged = mergeUnifiedSessions({
+      live: [{ id: 'codeman-uuid', status: 'idle', mode: 'codex', claudeSessionId: 'thread-one' }],
+      history: [
+        {
+          sessionId: 'thread-two',
+          workingDir: '/w',
+          sizeBytes: 4000,
+          lastModified: '2026-09-02T00:00:00.000Z',
+          mode: 'codex',
+          resumeId: 'thread-two',
+        },
+      ],
+    });
+    expect(merged.map((m) => m.sessionId).sort()).toEqual(['codeman-uuid', 'thread-two']);
+  });
+
+  it("carries a transcript row's own resume token, and stamps none on a live row", () => {
+    // codex names a thread by an id in its rollout, not by Codeman's session id.
+    // The scanner sets `resumeId`; a live session never does, which is what stops
+    // a resume from asking codex for a thread whose id is really Codeman's uuid.
+    const merged = mergeUnifiedSessions({
+      live: [{ id: 'codeman-uuid', status: 'idle', mode: 'codex' }],
+      history: [
+        {
+          sessionId: 'codex-thread-id',
+          workingDir: '/w',
+          sizeBytes: 4000,
+          lastModified: '2026-09-02T00:00:00.000Z',
+          mode: 'codex',
+          resumeId: 'codex-thread-id',
+        },
+      ],
+    });
+    const fromTranscript = merged.find((m) => m.sessionId === 'codex-thread-id');
+    const fromLive = merged.find((m) => m.sessionId === 'codeman-uuid');
+    expect(fromTranscript?.resumeId).toBe('codex-thread-id');
+    expect(fromTranscript?.mode).toBe('codex');
+    expect(fromLive?.resumeId).toBeUndefined();
+  });
+
   it('dedupes the same sessionId across live + persisted into one item', () => {
     const merged = mergeUnifiedSessions({
       live: [{ id: 's1', status: 'working', isWorking: true }],

test/session-activity.test.ts

@@ -1,5 +1,5 @@
 /**
- * Working/idle detection for an interactive Claude pane.
+ * Working/idle detection for an interactive agent pane, Claude's and Codex's.
  *
  * The bug this pins: Claude redraws the composer (`❯`) about once a second all
  * the way through a turn, so the old "saw a ❯, wait 2s, call it idle" rule
@@ -7,11 +7,17 @@
  * worker: `GET /api/sessions` reported `idle` for a session that had been
  * running for 17 minutes and was mid-tool-call.
  *
+ * A second bug this pins: work detection read Claude's glyph and Claude's status line
+ * for every CLI, so a Codex session reported itself idle through an entire turn. Each CLI
+ * now names its own pair in `capabilities.workDetect`, and a CLI that names none reports
+ * work exactly as before.
+ *
  * The status-line fixtures below are verbatim captures from live panes
- * (`tmux -L codeman capture-pane -p`) on Claude Code 2.1.220.
+ * (`tmux -L codeman capture-pane -p`) on Claude Code 2.1.220 and Codex CLI 0.152.1.
  */
 import { describe, expect, it, vi, afterEach } from 'vitest';
 import { Session } from '../src/session.js';
+import { getCli } from '../src/config/cli-registry/index.js';
 import { CLAUDE_WORKING_LINE_PATTERN } from '../src/utils/regex-patterns.js';
 import {
   trackActivityStreak,
@@ -38,7 +44,7 @@ function feed(session: Session, data: string): void {
  * A session whose mux reports a fixed (or scripted) screen, so the pane probe has
  * something to read. Only `capturePaneText` is exercised by these paths.
  */
-function withFakePane(screen: string | (() => string)): Session {
+function withFakePane(screen: string | (() => string), mode: 'claude' | 'codex' = 'claude'): Session {
   const read = typeof screen === 'function' ? screen : () => screen;
   const mux = {
     isAvailable: () => true,
@@ -46,12 +52,26 @@ function withFakePane(screen: string | (() => string)): Session {
   } as unknown as NonNullable<Parameters<typeof Session.prototype.constructor>[0]>['mux'];
   return new Session({
     workingDir: '/tmp',
-    mode: 'claude',
+    mode,
     mux,
     muxSession: { muxName: 'codeman-test', sessionId: 'test', createdAt: Date.now() },
   } as ConstructorParameters<typeof Session>[0]);
 }
 
+/**
+ * Codex's pane, verbatim, while a turn runs and once it has finished. Codex draws `›` on
+ * its composer row through the whole turn, exactly as Claude draws `❯`, and prints
+ * `esc to interrupt` only while the turn is live.
+ */
+const CODEX_WORKING =
+  'Working (2m 49s • esc to interrupt)\n› Ask Codex to do anything\n' +
+  '  gpt-5.6-sol high · Context 59% left · ~/innovi/irisplus-ent-2 · main\n';
+const CODEX_FINISHED =
+  '─ Worked for 3m 47s ────────────────────\n› Ask Codex to do anything\n' +
+  '  gpt-5.6-sol high · Context 57% left · ~/innovi/irisplus-ent-2 · main\n';
+/** Codex's own composer repaint, the frame that arms the idle confirmation. */
+const CODEX_COMPOSER_REPAINT = '\x1b[31;1H\x1b[38;5;246m›\xa0\x1b[39m\x1b[0m';
+
 /** A composer repaint: the frame Claude ships roughly once a second while working. */
 const COMPOSER_REPAINT =
   '\x1b[31;1H\x1b[38;5;246m❯\xa0\x1b[39m\x1b[0m\x1b[33;1H  \x1b[38;5;246mOpus 5  in:143,699 out:669  ctx:14%\x1b[39m';
@@ -230,11 +250,13 @@ describe('Session interactive idle detection', () => {
     expect(session.status).toBe('idle');
   });
 
-  it('does not mark an external CLI pane working off raw activity', () => {
+  it('does not mark an uncharacterised CLI working off raw activity', () => {
     vi.useFakeTimers();
-    // Codex/Gemini/OpenCode render their own TUIs and have no ❯, so nothing would
-    // arm the idle confirmation, so a session marked working here would never recover.
-    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    // Gemini and OpenCode render their own TUIs, and Codeman knows neither one's glyph,
+    // so nothing would arm the idle confirmation and a session marked working here would
+    // never recover. A CLI that names no glyph therefore reports no work at all.
+    expect(getCli('gemini')?.capabilities.workDetect).toBeUndefined();
+    const session = new Session({ workingDir: '/tmp', mode: 'gemini' });
     const events: string[] = [];
     session.on('working', () => events.push('working'));
 
@@ -245,6 +267,59 @@ describe('Session interactive idle detection', () => {
 
     expect(events).toEqual([]);
   });
+
+  it('marks a Codex pane working, and lets the turn end', () => {
+    vi.useFakeTimers();
+    let screen = CODEX_WORKING;
+    const session = withFakePane(() => screen, 'codex');
+    const events: string[] = [];
+    session.on('working', () => events.push('working'));
+    session.on('idle', () => events.push('idle'));
+
+    for (let i = 0; i < 3; i++) {
+      feed(session, CODEX_COMPOSER_REPAINT);
+      vi.advanceTimersByTime(1000);
+    }
+    vi.advanceTimersByTime(20_000);
+
+    // The old code reported this session idle for the whole turn.
+    expect(events).toEqual(['working']);
+    expect(session.status).toBe('busy');
+
+    // Turn over: the working footer gives way to the finished line, which must NOT
+    // read as work — it sits on screen for the whole idle period afterwards.
+    screen = CODEX_FINISHED;
+    vi.advanceTimersByTime(20_000);
+
+    expect(events).toEqual(['working', 'idle']);
+    expect(session.status).toBe('idle');
+  });
+});
+
+describe("codex's work-detection descriptor", () => {
+  const codex = getCli('codex')?.capabilities.workDetect;
+
+  it('matches the footer Codex prints while a turn runs', () => {
+    expect(new RegExp(codex!.workingLine).test(CODEX_WORKING)).toBe(true);
+  });
+
+  it('does not match the finished line, nor the idle footer', () => {
+    expect(new RegExp(codex!.workingLine).test(CODEX_FINISHED)).toBe(false);
+  });
+
+  it('matches the footer case-insensitively on the E', () => {
+    // Characterised on codex-cli 0.152.1, which prints a lowercase `esc`. A future
+    // version capitalising it would otherwise make the whole fix silently inert:
+    // the pane would simply never look like it was working.
+    expect(new RegExp(codex!.workingLine).test(CODEX_WORKING.replace('esc to interrupt', 'Esc to interrupt'))).toBe(
+      true
+    );
+  });
+
+  it('names the glyph Codex actually draws on its composer row', () => {
+    expect(CODEX_COMPOSER_REPAINT).toContain(codex!.promptGlyph);
+    expect(CODEX_WORKING).toContain(codex!.promptGlyph);
+  });
 });
 
 describe('wire activity stamp across recovery', () => {

test/session-claude-conversation-chain.test.ts

@@ -100,9 +100,11 @@ describe('Session claude conversation chain', () => {
     // before this existed. Every assignment built from the launch-id fallback
     // must therefore carry `restoredConversation` first.
     const source = readFileSync(resolve(import.meta.dirname, '../src/session.ts'), 'utf8');
-    const fallbackAssignments = source.match(
-      /_claudeSessionId =\s*\n?\s*[^;]*?_resumeSessionId \|\| this\._ompConfig\?\.resumeSessionId \|\| this\.id;/g
-    );
+    // The tail of the chain grows as each CLI gains a resume alias of its own
+    // (omp, then codex), so the pattern pins the two ends and lets the middle
+    // widen. A `[^;]` run cannot cross a statement boundary, so each match is
+    // still one assignment.
+    const fallbackAssignments = source.match(/_claudeSessionId =[^;]*?_resumeSessionId[^;]*?this\.id;/g);
     expect(fallbackAssignments).not.toBeNull();
     expect(fallbackAssignments!.length).toBeGreaterThanOrEqual(2);
     for (const assignment of fallbackAssignments!) {