From 15eebde83213b1b5def51c453b7b027bb684fe80 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 01/26] feat(docker): attach a case to an already-running container MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docker cases could only run in a container Codeman created itself. Attaching to one the user already built and runs means Codeman must leave that container's lifecycle completely alone, which the launch chain could not do: it was `image inspect` -> `inspect || create` -> `start` -> `exec`. Adds `DockerCase.owned`, mirroring the `owned:false` contract remote-SSH already uses for attached sessions. Absent (every existing case) means owned, so current behaviour is byte-identical. `false` means the container belongs to the user and Codeman may only exec into it. The launch chain for an attached container only looks, then execs: no image gate (the image is theirs), no create, and no `start` — starting a container we do not own is the very mutation attaching promises not to perform. A missing or stopped container fails closed with an actionable message instead. Credential seeding is skipped too: those copies read from create-time read-only mounts that do not exist here, and writing host credentials into someone's container is not ours to do, so its CLIs must already be authenticated inside it. Four fail-closed guards. buildDockerStopCommand and buildDockerRemoveCommand throw during pure string construction, so no caller bug can turn into a `docker stop`/`rm` on a container we do not own; removeDockerContainer refuses again at the lowest layer; drift reports "none" for an attached container, which carries no `codeman.confighash` label and would otherwise always look drifted and 409 the launch gate forever; and the orphan reaper skips attached containers through a check deliberately independent of the two conditions already covering them. `owned` is applied AFTER the config hash is computed. dockerConfigHash takes an explicit field list, so ownership can never shift an existing case's hash — if it did, every pre-existing case would trip the drift gate at once, and the remedy the UI offers is "recreate the container". Adds POST /api/cases/docker-adopt and a read-only POST /api/docker-cases/adopt-preflight. The preflight refuses at LINK time rather than at session launch, where the only ways out would be a dead pane or starting a container we do not own. Tests assert the negative guarantee directly — that create, start, stop, rm, restart and kill are absent from the generated commands while `docker exec -it` and `new-session -A` remain — since it cannot be observed by using the feature. --- src/docker-hosts.ts | 157 +++++++++++++++++++++++- src/tmux-manager.ts | 53 +++++++- src/types/session.ts | 24 ++++ src/web/routes/case-routes.ts | 135 ++++++++++++++++++++- src/web/routes/session-routes.ts | 57 ++++++--- src/web/schemas.ts | 44 +++++++ test/docker-adopted-container.test.ts | 168 ++++++++++++++++++++++++++ 7 files changed, 604 insertions(+), 34 deletions(-) create mode 100644 test/docker-adopted-container.test.ts diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts index e2a92486..b49502a5 100644 --- a/src/docker-hosts.ts +++ b/src/docker-hosts.ts @@ -55,6 +55,21 @@ export const DEFAULT_AGENT_IMAGE = 'codeman/agent:base'; /** HOME inside the base image (the `agent` user). Cred mounts + hook-secret land under it. */ export const CONTAINER_HOME = '/home/agent'; +/** + * Modes the adoption preflight probes for inside an existing container. `shell` + * is omitted deliberately: it needs no CLI binary and is always available, so it + * is reported as available without a `command -v` lookup. + */ +export const DOCKER_ADOPT_PROBE_MODES = [ + 'claude', + 'codex', + 'opencode', + 'gemini', + 'antigravity', + 'pi', + 'shell', +] as const satisfies readonly SessionMode[]; + /** Per-case container name prefix. The `case` letters deliberately do NOT matter to * tmux; this is a DOCKER name (`^[a-zA-Z0-9][a-zA-Z0-9_.-]+$`), and case names are * already validated `^[a-zA-Z0-9_-]+$`, so `codeman-case-` is always valid. */ @@ -251,7 +266,22 @@ export function toSessionDocker(host: DockerHost, dockerCase: DockerCase): Sessi extraCreateArgs: host.extraCreateArgs, extraExecArgs: host.extraExecArgs, }; - return { ...base, configHash: dockerConfigHash(base) }; + // `owned` is deliberately applied AFTER the hash: dockerConfigHash() picks an + // explicit field list, so ownership can never shift an existing case's hash and + // mass-trip the drift gate. + const session: SessionDocker = { ...base, configHash: dockerConfigHash(base) }; + if (dockerCase.owned === false) session.owned = false; + return session; +} + +/** + * An ADOPTED container is one the user built and runs themselves. Codeman may + * only exec into it; it must never create, start, stop, restart or remove it. + * Every lifecycle branch routes through this one predicate so a new call site + * cannot silently opt out. + */ +export function isAdoptedContainer(docker: Pick): boolean { + return docker.owned === false; } // ========== Shell escaping ========== @@ -713,9 +743,15 @@ export interface DockerDriftStatus { * daemon down) means there is nothing to drift. No-op under VITEST. */ export async function checkDockerConfigDrift( - docker: Pick + docker: Pick ): Promise { if (IS_TEST_MODE) return { exists: false, running: false, drifted: false }; + // An ADOPTED container carries no `codeman.confighash` label — it was never + // created from our config — so every comparison would report drift and the + // launch gate would demand a recreate we are not allowed to perform. Ownership + // of its configuration belongs to the user; report "no drift" and never offer + // to rebuild it. + if (isAdoptedContainer(docker)) return { exists: true, running: false, drifted: false }; const argv = dockerEngineArgv(docker); try { const { stdout } = await execFileAsync( @@ -743,8 +779,15 @@ export async function checkDockerConfigDrift( * case's lastClaudeSessionId. No-op under VITEST. */ export async function removeDockerContainer( - docker: Pick + docker: Pick ): Promise { + // Fail CLOSED at the lowest layer: an adopted container is the user's, and no + // caller — recreate-on-drift, case delete, a future teardown — may remove it. + if (isAdoptedContainer(docker)) { + throw new Error( + `Refusing to remove adopted container "${docker.containerName}": Codeman does not own its lifecycle.` + ); + } if (IS_TEST_MODE) return; const argv = dockerEngineArgv(docker); await execFileAsync(argv[0], [...argv.slice(1), 'rm', '-f', docker.containerName], { timeout: 30_000 }); @@ -990,6 +1033,105 @@ export async function checkDockerTmuxAvailable( } } +/** Preflight facts about an ALREADY-RUNNING container the user wants to adopt. */ +export interface AdoptedContainerProbe { + ok: boolean; + exists: boolean; + running: boolean; + /** The container's own image ref (informational — we never enforce ours on it). */ + image?: string; + /** `command -v tmux` inside the container; required for durable sessions. */ + tmuxPath?: string; + /** Modes whose CLI resolved inside the container (`command -v `). */ + availableModes?: SessionMode[]; + error?: string; +} + +/** + * Preflight an EXISTING container for adoption. Read-only by construction: it + * runs `inspect` plus one `exec` of `command -v`, and never creates, starts or + * modifies anything. Refusing here is what keeps the failure at link time — a + * clear message — instead of at session launch, where the only alternatives + * would be a dead pane or starting a container we do not own. + * + * `--pull=never` is irrelevant here: adoption never touches images. The image + * ref is reported only so the UI can show what the user is attaching to. + */ +export async function probeAdoptableContainer( + docker: Pick, + modes: SessionMode[] = [] +): Promise { + if (IS_TEST_MODE) { + return { ok: true, exists: true, running: true, tmuxPath: '/usr/bin/tmux', availableModes: modes }; + } + const argv = dockerEngineArgv(docker); + let running = false; + let image: string | undefined; + try { + const { stdout } = await execFileAsync( + argv[0], + [...argv.slice(1), 'inspect', '-f', '{{.State.Running}}\t{{.Config.Image}}', docker.containerName], + { timeout: DOCKER_PROBE_TIMEOUT_MS } + ); + const [state = '', img = ''] = stdout.trim().split('\t'); + running = state === 'true'; + image = img || undefined; + } catch { + return { + ok: false, + exists: false, + running: false, + error: `container "${docker.containerName}" not found (adoption never creates a container — start it yourself first)`, + }; + } + if (!running) { + return { + ok: false, + exists: true, + running: false, + image, + error: `container "${docker.containerName}" exists but is not running (Codeman never starts a container it does not own — start it yourself, then retry)`, + }; + } + // One exec resolves tmux plus every requested CLI, so adoption costs a single + // round trip. Binaries are fixed mode names, never user input. + const probes = ['tmux', ...modes.filter((m) => m !== 'shell')]; + const script = probes.map((bin) => `command -v ${bin} >/dev/null 2>&1 && echo ${bin}`).join('; '); + try { + const { stdout } = await execFileAsync( + argv[0], + [...argv.slice(1), 'exec', docker.containerName, 'sh', '-lc', script], + { timeout: DOCKER_PROBE_TIMEOUT_MS } + ); + const found = new Set( + stdout + .split('\n') + .map((line) => line.trim()) + .filter(Boolean) + ); + if (!found.has('tmux')) { + return { + ok: false, + exists: true, + running: true, + image, + error: `container "${docker.containerName}" has no tmux (required for durable sessions; install it inside the container)`, + }; + } + return { + ok: true, + exists: true, + running: true, + image, + tmuxPath: 'tmux', + availableModes: modes.filter((m) => m === 'shell' || found.has(m)), + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + return { ok: false, exists: true, running: true, image, error: `could not exec into the container: ${msg}` }; + } +} + /** * Resolve the host's IP on the default docker bridge (the address a container * reaches as `host.docker.internal`), so the server can bind a hooks-only listener @@ -1052,9 +1194,18 @@ export async function reapOrphanedDockerContainers( } const cases = await readDockerCases(configDir); const expected = new Set(cases.map((c) => c.container ?? dockerContainerName(c.name))); + // ADOPTED containers are never reapable, and this guard is deliberately + // independent of the two conditions that already cover them (we never applied + // the `codeman.managed=1` label filtered on above, and they are referenced by a + // live case so they are in `expected`). An adopted container is the user's + // property; it must survive even if a future edit narrows either condition. + const adopted = new Set( + cases.filter((item) => item.owned === false).map((item) => item.container ?? dockerContainerName(item.name)) + ); const reaped: string[] = []; for (const { name, inst } of rows) { if (inst !== instance) continue; // only THIS instance's containers + if (adopted.has(name)) continue; // never reap a container we do not own if (expected.has(name)) continue; // still referenced by a live case try { await execFileAsync(bin, ['rm', '-f', name], { timeout: DOCKER_PROBE_TIMEOUT_MS }); diff --git a/src/tmux-manager.ts b/src/tmux-manager.ts index 5088793d..3e0c96cb 100644 --- a/src/tmux-manager.ts +++ b/src/tmux-manager.ts @@ -1275,7 +1275,15 @@ export interface DockerLaunchOptions { export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string { const { mode, docker, sessionId, resumeSessionId, createContext, execEnv, execEnvNames, seedCopies } = opts; const base = buildDockerBaseArgs(docker).join(' '); - const createArgs = buildDockerCreateArgs(createContext).join(' '); + // ADOPTED container (docker.owned === false): the user built it and runs it, so + // this chain may only LOOK and then exec. No image check (the image is theirs), + // no create, and above all no `start` — starting a container we do not own is + // exactly the lifecycle mutation adoption promises never to perform. A missing + // or stopped container fails closed with an actionable message instead. + const adopted = docker.owned === false; + // Built lazily: an adopted case has no meaningful create-config, so computing + // create args for it would demand a context the adopt path never assembles. + const createArgs = adopted ? '' : buildDockerCreateArgs(createContext).join(' '); const name = shellescape(docker.containerName); const workdir = shellescape(docker.containerWorkdir); const image = shellescape(docker.image); @@ -1318,16 +1326,33 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string { ); const startFailMsg = shellescape(`Codeman: container ${docker.containerName} failed to start (docker daemon down?)`); - const imageCheck = `${base} image inspect ${image} >/dev/null 2>&1 || { echo ${imageMissingMsg}; exit 1; }`; + const notFoundMsg = shellescape( + `Codeman: container ${docker.containerName} not found. Adopted containers are never created by Codeman — start it yourself, then reopen this session.` + ); + const notRunningMsg = shellescape( + `Codeman: container ${docker.containerName} is not running. Codeman never starts a container it does not own — start it yourself, then reopen this session.` + ); + + const imageCheck = adopted + ? '' + : `${base} image inspect ${image} >/dev/null 2>&1 || { echo ${imageMissingMsg}; exit 1; }`; // create-if-missing (idempotent): reconnect / boot recovery re-runs this exact chain. - const ensure = `${base} inspect ${name} >/dev/null 2>&1 || ${base} ${createArgs}`; - const start = `${base} start ${name} >/dev/null 2>&1 || { echo ${startFailMsg}; exit 1; }`; + const ensure = adopted + ? `${base} inspect ${name} >/dev/null 2>&1 || { echo ${notFoundMsg}; exit 1; }` + : `${base} inspect ${name} >/dev/null 2>&1 || ${base} ${createArgs}`; + const start = adopted + ? `[ "$(${base} inspect -f '{{.State.Running}}' ${name} 2>/dev/null)" = true ] || { echo ${notRunningMsg}; exit 1; }` + : `${base} start ${name} >/dev/null 2>&1 || { echo ${startFailMsg}; exit 1; }`; // Seed writable credential config from read-only host mounts ONCE per container // (guarded by [ -e ] so reconnects never clobber in-container config; `cp -a` for // whole-dir credential seeds). mkdir -p the parent so a file seed works even when // no sibling share-mount pre-created the dir. Paths are fixed CONTAINER_HOME // constants (no shell metachars), so the whole inner command is shell-quoted once. - const seedSteps = (seedCopies ?? []).map((s) => { + // An ADOPTED container gets NO seed copies: those read from create-time + // read-only mounts that do not exist here, and writing host credentials into a + // container the user owns is a mutation adoption does not permit. Its CLIs must + // already be authenticated inside it. + const seedSteps = (adopted ? [] : (seedCopies ?? [])).map((s) => { const cp = s.recursive ? 'cp -a' : 'cp'; const parent = s.to.slice(0, s.to.lastIndexOf('/')); return `mkdir -p ${parent} 2>/dev/null; [ -e ${s.to} ] || ${cp} ${s.from} ${s.to} 2>/dev/null || true`; @@ -1335,7 +1360,7 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string { const innerCmd = seedSteps.length ? `${seedSteps.join(' ; ')} ; ${tmuxInvocation}` : tmuxInvocation; const execCmd = `exec ${base} exec -it --workdir ${workdir} ${execEnvFlags.join(' ')} ${name} sh -lc ${shellescape(innerCmd)}`; - return [imageCheck, ensure, start, execCmd].join(' ; '); + return [imageCheck, ensure, start, execCmd].filter(Boolean).join(' ; '); } /** @@ -1351,13 +1376,29 @@ export function buildDockerKillCommand(options: { docker: SessionDocker; session return `${base} exec ${shellescape(docker.containerName)} tmux -L ${DOCKER_TMUX_SOCKET} kill-session -t ${shellescape(dkrName)}`; } +/** + * Guard for the two builders that mutate CONTAINER lifecycle. They are pure + * string builders, so refusing here means an adopted container cannot even have + * a stop/remove command constructed for it — there is no shape of caller bug + * that turns into a `docker stop`/`rm` on something we do not own. + */ +function assertOwnedContainer(docker: SessionDocker, action: string): void { + if (docker.owned === false) { + throw new Error( + `Refusing to ${action} adopted container "${docker.containerName}": Codeman does not own its lifecycle.` + ); + } +} + /** Explicit container stop (frees RAM/CPU; conversation resumes on next launch via --resume). */ export function buildDockerStopCommand(docker: SessionDocker): string { + assertOwnedContainer(docker, 'stop'); return `${buildDockerBaseArgs(docker).join(' ')} stop -t 10 ${shellescape(docker.containerName)}`; } /** Explicit container removal (case-delete). Destroys in-image state; bind mounts survive. */ export function buildDockerRemoveCommand(docker: SessionDocker): string { + assertOwnedContainer(docker, 'remove'); return `${buildDockerBaseArgs(docker).join(' ')} rm -f ${shellescape(docker.containerName)}`; } diff --git a/src/types/session.ts b/src/types/session.ts index 8e429459..7187dae4 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -243,6 +243,24 @@ export interface DockerCase { containerWorkdir?: string; /** Container name (default codeman-case-). */ container?: string; + /** + * Whether THIS Codeman created the container (mirror of `SessionRemote.owned`). + * + * - `true` (default for cases Codeman linked/quick-created): we own the + * container; drift may recreate it, case-delete may `docker rm -f` it, and + * the launch chain may create + start it. + * - `false` (ADOPTED: an already-running container the user built and runs + * themselves): Codeman must never create, start, stop, restart or remove it. + * The launch chain fails closed when the container is missing or not running + * instead of touching its lifecycle, drift is not evaluated (there is no + * `codeman.confighash` label to compare), and no credential seed is copied + * into its HOME. Only the in-container tmux session is ever created or + * killed — exactly the `owned:false` remote-SSH contract. + * + * Absent is treated as owned (cases persisted before this field existed were + * all created by us). + */ + owned?: boolean; /** Last captured Claude conversation id, replayed via --resume on a fresh launch. */ lastClaudeSessionId?: string; } @@ -275,6 +293,12 @@ export interface SessionDocker { extraExecArgs?: string[]; /** Stable hash of the drift-relevant create args (recreate-on-drift detection). */ configHash?: string; + /** + * Mirror of `DockerCase.owned`, flattened onto the live session so every + * lifecycle decision (launch chain, drift, stop, remove) can see it without + * re-reading docker-cases.json. Absent = owned. See `DockerCase.owned`. + */ + owned?: boolean; } /** diff --git a/src/web/routes/case-routes.ts b/src/web/routes/case-routes.ts index 978ac941..49c94e2e 100644 --- a/src/web/routes/case-routes.ts +++ b/src/web/routes/case-routes.ts @@ -13,7 +13,7 @@ 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 } from '../../types.js'; +import type { ApiResponse, CaseInfo, DockerHost, RemoteSessionInfo, SessionDocker, SessionMode } from '../../types.js'; import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js'; import { CreateCaseSchema, @@ -24,6 +24,8 @@ import { RemoteCaseLinkSchema, RemoteHostSchema, DockerCaseLinkSchema, + DockerCaseAdoptSchema, + DockerAdoptPreflightSchema, DockerHostSchema, DockerExportSchema, DockerImportSchema, @@ -66,6 +68,8 @@ import { DEFAULT_AGENT_IMAGE, dockerContainerName, dockerDisplayPath, + probeAdoptableContainer, + DOCKER_ADOPT_PROBE_MODES, readDockerCases, readDockerHosts, removeDockerContainer, @@ -73,6 +77,7 @@ import { writeDockerCases, writeDockerHosts, } from '../../docker-hosts.js'; +import type { AdoptedContainerProbe } from '../../docker-hosts.js'; import { buildDockerRemoveCommand } from '../../tmux-manager.js'; import { checkRemoteTmuxAvailable, @@ -771,6 +776,106 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config } ); + /** + * ADOPT an already-running container (`owned: false`). The mirror of the + * remote-SSH attach path: Codeman execs into a container the user built and + * runs, and never creates, starts, stops, restarts or removes it. + * + * Everything here is read-only toward the container. The preflight refuses at + * LINK time — missing, stopped, or no tmux inside — because the alternative is + * failing at session launch, where the only ways out would be a dead pane or + * starting a container we do not own. There is no image gate and no + * `ensureCaseImage`: adoption never runs `docker create`, so the container's + * image is the user's business. + */ + app.post( + '/api/cases/docker-adopt', + async (req): Promise> => { + const dockerCase = { + ...parseBody(DockerCaseAdoptSchema, req.body), + type: 'docker' as const, + owner: ownerFor(req), + owned: false as const, + }; + const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId); + if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found'); + + const linkedCases = await readLinkedCases(); + const dockerCases = await readDockerCases(CODEMAN_CONFIG_DIR); + if ( + dockerCases.some((item) => item.name === dockerCase.name) || + linkedCases[dockerCase.name] || + existsSync(join(resolveCasesDir(getAuthUser(req)), dockerCase.name)) + ) { + return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Case already exists'); + } + // Two cases must never share one adopted container: session close kills the + // in-container tmux by session id, but a shared adoption would let one case's + // teardown and another's launch race over the same tmux server. + const container = dockerCase.container; + if (dockerCases.some((item) => (item.container ?? dockerContainerName(item.name)) === container)) { + return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, `Container "${container}" is already linked to a case`); + } + + if (!isWorkingDirAllowed(getAuthUser(req), dockerCase.hostWorkspacePath)) { + return createErrorResponse(ApiErrorCode.FORBIDDEN, 'hostWorkspacePath is outside your workspace'); + } + // The workspace must ALREADY exist: it mirrors a path inside a container we + // did not create, so silently mkdir-ing it would invent a host directory that + // does not correspond to whatever is actually mounted there. + if (!existsSync(dockerCase.hostWorkspacePath)) { + return createErrorResponse( + ApiErrorCode.INVALID_INPUT, + 'hostWorkspacePath does not exist. Adoption mirrors an existing container, so point this at the real host directory already mounted into it.' + ); + } + + const availability = await checkDockerAvailable(host.engine); + if (!availability.ok) { + return createErrorResponse( + ApiErrorCode.OPERATION_FAILED, + availability.error || 'docker daemon is not available' + ); + } + const probe = await probeAdoptableContainer(toSessionDocker(host, dockerCase), [...DOCKER_ADOPT_PROBE_MODES]); + if (!probe.ok) { + return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not adoptable'); + } + + await writeDockerCases(CODEMAN_CONFIG_DIR, [...dockerCases, dockerCase]); + ctx.broadcast(SseEvent.CaseLinked, { + name: dockerCase.name, + path: dockerCase.hostWorkspacePath, + type: 'docker', + }); + return { + success: true, + data: { case: dockerCase, image: probe.image, availableModes: probe.availableModes }, + }; + } + ); + + /** + * Preflight an existing container WITHOUT linking anything, so the UI can tell + * the user "not running" / "no tmux" / "codex present, claude missing" before + * they commit to a case name. Read-only; never touches container lifecycle. + */ + app.post('/api/docker-cases/adopt-preflight', async (req): Promise> => { + const body = parseBody(DockerAdoptPreflightSchema, req.body); + const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId); + if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found'); + const probe = await probeAdoptableContainer( + { + engine: host.engine ?? 'docker', + context: host.context, + daemonHost: host.daemonHost, + containerName: body.container, + }, + [...DOCKER_ADOPT_PROBE_MODES] + ); + return { success: true, data: probe }; + }); + // One-click "Run in Docker": create a NORMAL case (folder in CASES_DIR, scaffolded) // AND link it to a hardened container with default settings, auto-provisioning a // shared `default` docker host so the user never touches host/image/network fields. @@ -1010,9 +1115,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config engine: result.manifest.engine, image: result.importedImage ?? result.manifest.image, network: (['bridge', 'none', 'custom'].includes(result.manifest.network) ? result.manifest.network : 'bridge') as - | 'bridge' - | 'none' - | 'custom', + 'bridge' | 'none' | 'custom', }; await writeDockerHosts( CODEMAN_CONFIG_DIR, @@ -1042,8 +1145,22 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config '/api/docker-cases/:name/recreate', async (req): Promise> => { const { name } = req.params as { name: string }; - const dockerCase = (await readDockerCases(CODEMAN_CONFIG_DIR)).find((item) => item.name === name); + // Ownership gate: recreate DESTROYS a container, so it must be scoped like + // delete is (`canAccessOwned`). Without it any user could rebuild another + // user's container by name. + const dockerCase = (await readDockerCases(CODEMAN_CONFIG_DIR)).find( + (item) => item.name === name && canAccessOwned(getAuthUser(req), item.owner) + ); if (!dockerCase) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker case not found'); + // An ADOPTED container is the user's own: there is nothing to recreate it + // from (no create-config, no image gate) and destroying it is exactly what + // adoption promises never to do. + if (dockerCase.owned === false) { + return createErrorResponse( + ApiErrorCode.FORBIDDEN, + `Case "${name}" adopted an existing container. Codeman does not own its lifecycle and will not recreate it — rebuild it yourself, or unlink the case.` + ); + } const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId); if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found'); const sessionDocker = toSessionDocker(host, dockerCase); @@ -1154,7 +1271,13 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config ); // Best-effort `docker rm -f` the per-case container (case-delete is the // explicit teardown that removes it; the bind-mounted workspace survives). - const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId); + // An ADOPTED container is skipped entirely: unlinking the case must leave + // the user's own container running and untouched. The seed file is skipped + // with it — adoption never wrote one. + const host = + dockerCase.owned === false + ? undefined + : (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId); if (host) { const sessionDocker = toSessionDocker(host, dockerCase); try { diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index 3e7c258f..36ccea31 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -127,6 +127,7 @@ import { import { checkDockerAvailable, checkDockerConfigDrift, + probeAdoptableContainer, checkDockerTmuxAvailable, ensureAgentBaseImage, DEFAULT_AGENT_IMAGE, @@ -2957,25 +2958,43 @@ export function registerSessionRoutes( ); } const sessionDocker = toSessionDocker(host, dockerCase); - // Ensure the base image exists, auto-building the default image on first use so - // it is never a blocker. Dedup'd with any build kicked off at case-create, so - // this awaits the SAME in-flight build rather than starting a second one. - const ensured = await ensureAgentBaseImage(sessionDocker, sessionDocker.image, { - onProgress: (line) => ctx.broadcast(SseEvent.DockerImageBuildProgress, { name: dockerCase.name, line }), - }); - if (!ensured.ok) { - return createErrorResponse(ApiErrorCode.OPERATION_FAILED, ensured.error || 'base image not available'); - } - if (ensured.built) { - ctx.broadcast(SseEvent.DockerImageBuildComplete, { name: dockerCase.name, image: sessionDocker.image }); - } - // tmux is a hard prerequisite (the in-container tmux makes reconnect durable). - // Skip the extra container-run probe for our OWN default image (the baked - // Dockerfile always contains tmux); still verify a custom image. - if (sessionDocker.image !== DEFAULT_AGENT_IMAGE) { - const tmuxCheck = await checkDockerTmuxAvailable(sessionDocker); - if (!tmuxCheck.ok) { - return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'base image is missing tmux'); + // An ADOPTED container skips every image-side gate: we never run `docker + // create`, so the image is the user's business, and `ensureAgentBaseImage` + // would build/require an image that has nothing to do with their container. + // The prerequisite that DOES still hold is tmux inside it, so probe the live + // container (not the image) and refuse before launch rather than dead-paning. + if (sessionDocker.owned === false) { + const probe = await probeAdoptableContainer(sessionDocker, [mode]); + if (!probe.ok) { + return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not usable'); + } + if (mode !== 'shell' && !probe.availableModes?.includes(mode)) { + return createErrorResponse( + ApiErrorCode.OPERATION_FAILED, + `"${mode}" is not installed in container "${sessionDocker.containerName}". Adoption never modifies the container — install it inside, or pick another mode.` + ); + } + } else { + // Ensure the base image exists, auto-building the default image on first use so + // it is never a blocker. Dedup'd with any build kicked off at case-create, so + // this awaits the SAME in-flight build rather than starting a second one. + const ensured = await ensureAgentBaseImage(sessionDocker, sessionDocker.image, { + onProgress: (line) => ctx.broadcast(SseEvent.DockerImageBuildProgress, { name: dockerCase.name, line }), + }); + if (!ensured.ok) { + return createErrorResponse(ApiErrorCode.OPERATION_FAILED, ensured.error || 'base image not available'); + } + if (ensured.built) { + ctx.broadcast(SseEvent.DockerImageBuildComplete, { name: dockerCase.name, image: sessionDocker.image }); + } + // tmux is a hard prerequisite (the in-container tmux makes reconnect durable). + // Skip the extra container-run probe for our OWN default image (the baked + // Dockerfile always contains tmux); still verify a custom image. + if (sessionDocker.image !== DEFAULT_AGENT_IMAGE) { + const tmuxCheck = await checkDockerTmuxAvailable(sessionDocker); + if (!tmuxCheck.ok) { + return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'base image is missing tmux'); + } } } diff --git a/src/web/schemas.ts b/src/web/schemas.ts index 1641e61f..c5860388 100644 --- a/src/web/schemas.ts +++ b/src/web/schemas.ts @@ -792,6 +792,50 @@ export const DockerCaseLinkSchema = z.object({ .optional(), }); +/** + * ADOPT an already-running container the user built and runs themselves. The + * container name is REQUIRED (there is nothing to derive it from — we are not + * creating it), and `hostWorkspacePath` still points at real host bytes so the + * file routes, watchers and transcript correlation keep working exactly as they + * do for an owned case. Everything that only makes sense at container-create + * time (image, network, resources, gpus, credential mounts) is deliberately + * absent: adoption never runs `docker create`. + */ +export const DockerCaseAdoptSchema = z.object({ + name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'), + hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'), + container: z + .string() + .min(2) + .max(128) + .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'), + hostWorkspacePath: z + .string() + .min(1) + .max(2000) + .regex(/^\//, 'Workspace path must be absolute') + .regex(/^[^,]*$/, 'Workspace path must not contain commas (docker --mount is comma-delimited)') + .regex(NO_SHELL_META, 'Invalid characters in workspace path'), + containerWorkdir: z + .string() + .min(1) + .max(2000) + .regex(/^\//, 'Container workdir must be absolute') + .regex(/^[^,]*$/, 'Container workdir must not contain commas (docker --mount is comma-delimited)') + .regex(NO_SHELL_META, 'Invalid characters in container workdir') + .optional(), +}); + +/** Read-only adoption preflight: report on an existing container, link nothing. */ +export const DockerAdoptPreflightSchema = z.object({ + hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'), + container: z + .string() + .min(2) + .max(128) + .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'), +}); + export const DockerExportSchema = z.object({ mode: z.enum(['full', 'workspace']).optional(), }); diff --git a/test/docker-adopted-container.test.ts b/test/docker-adopted-container.test.ts new file mode 100644 index 00000000..9561bf49 --- /dev/null +++ b/test/docker-adopted-container.test.ts @@ -0,0 +1,168 @@ +/** + * @fileoverview Adopting an ALREADY-RUNNING container (`DockerCase.owned === false`). + * + * The whole point of adoption is a negative guarantee: Codeman execs into a + * container the user built and runs, and never creates, starts, stops, restarts + * or removes it. A negative guarantee cannot be observed by using the feature — + * only by asserting that the mutating verbs are absent — so these tests read the + * generated command strings and assert on what is NOT in them. + * + * Mirror of the `owned:false` remote-SSH contract (COD-105). + */ +import { describe, it, expect } from 'vitest'; +import { + toSessionDocker, + isAdoptedContainer, + removeDockerContainer, + checkDockerConfigDrift, + dockerConfigHash, +} from '../src/docker-hosts.js'; +import { + buildDockerLaunchCommand, + buildDockerStopCommand, + buildDockerRemoveCommand, + buildDockerKillCommand, +} from '../src/tmux-manager.js'; +import type { DockerCase, DockerHost, SessionDocker } from '../src/types.js'; + +const HOST: DockerHost = { id: 'h1', label: 'local', engine: 'docker', image: 'codeman/agent:base' }; + +function caseFor(owned: boolean | undefined): DockerCase { + return { + name: 'adopted', + type: 'docker', + hostId: 'h1', + hostWorkspacePath: '/srv/work', + container: 'my-own-container', + ...(owned === undefined ? {} : { owned }), + }; +} + +function launchFor(docker: SessionDocker): string { + return buildDockerLaunchCommand({ + mode: 'codex', + docker, + sessionId: '11111111-2222-3333-4444-555555555555', + createContext: { + docker, + sessionId: '11111111-2222-3333-4444-555555555555', + instance: 'default', + userArgs: ['--user', '1000:0'], + credentialMounts: [], + extraMounts: [], + envCreate: { HOME: '/home/agent' }, + addHostGateway: true, + gatewayAlias: 'host.docker.internal', + }, + execEnv: { TERM: 'xterm-256color' }, + execEnvNames: [], + seedCopies: [{ from: '/seed/creds.json', to: '/home/agent/.claude/.credentials.json' }], + }); +} + +describe('adopted container: ownership plumbing', () => { + it('carries owned:false from the case onto the live session metadata', () => { + expect(toSessionDocker(HOST, caseFor(false)).owned).toBe(false); + expect(isAdoptedContainer(toSessionDocker(HOST, caseFor(false)))).toBe(true); + }); + + it('treats an absent flag as owned, so existing cases are unchanged', () => { + const docker = toSessionDocker(HOST, caseFor(undefined)); + expect(docker.owned).toBeUndefined(); + expect(isAdoptedContainer(docker)).toBe(false); + }); + + it('keeps ownership OUT of the config hash so adoption cannot mass-trip drift', () => { + // A drift-hash that moved with `owned` would flag every pre-existing case the + // moment this field shipped, and the remedy the UI offers is "recreate". + const owned = toSessionDocker(HOST, caseFor(undefined)); + const adopted = toSessionDocker(HOST, caseFor(false)); + expect(adopted.configHash).toBe(owned.configHash); + expect(dockerConfigHash({ ...owned, owned: false } as never)).toBe(owned.configHash); + }); +}); + +describe('adopted container: the launch chain never mutates lifecycle', () => { + const adopted = launchFor(toSessionDocker(HOST, caseFor(false))); + const owned = launchFor(toSessionDocker(HOST, caseFor(undefined))); + + it('never creates the container', () => { + expect(owned).toContain('docker create'); + expect(adopted).not.toContain('docker create'); + }); + + it('never starts the container', () => { + expect(owned).toContain('docker start'); + expect(adopted).not.toContain('docker start'); + }); + + it('never stops or removes the container', () => { + for (const verb of ['docker stop', 'docker rm', 'docker restart', 'docker kill']) { + expect(adopted).not.toContain(verb); + } + }); + + it('fails closed when the container is missing instead of creating it', () => { + expect(adopted).toContain('docker inspect'); + expect(adopted).toMatch(/not found.*start it yourself/i); + }); + + it('fails closed when the container is stopped instead of starting it', () => { + expect(adopted).toMatch(/\{\{\.State\.Running\}\}/); + expect(adopted).toMatch(/not running.*never starts a container it does not own/i); + }); + + it('skips the base-image gate, which describes an image adoption never uses', () => { + expect(owned).toContain('image inspect'); + expect(adopted).not.toContain('image inspect'); + }); + + it('never seeds host credentials into a container it does not own', () => { + expect(owned).toContain('.credentials.json'); + expect(adopted).not.toContain('.credentials.json'); + }); + + it('still execs into the in-container tmux, which is the whole point', () => { + expect(adopted).toContain('docker exec -it'); + expect(adopted).toContain('new-session -A'); + }); +}); + +describe('adopted container: mutating verbs fail closed at the builder', () => { + const docker = toSessionDocker(HOST, caseFor(false)); + + it('refuses to build a stop command', () => { + expect(() => buildDockerStopCommand(docker)).toThrow(/does not own its lifecycle/); + }); + + it('refuses to build a remove command', () => { + expect(() => buildDockerRemoveCommand(docker)).toThrow(/does not own its lifecycle/); + }); + + it('refuses to remove the container', async () => { + await expect(removeDockerContainer(docker)).rejects.toThrow(/does not own its lifecycle/); + }); + + it('still allows killing THIS session in-container tmux, never the container', () => { + const kill = buildDockerKillCommand({ docker, sessionId: 'abcdef12-0000-0000-0000-000000000000' }); + expect(kill).toContain('tmux'); + expect(kill).toContain('kill-session'); + expect(kill).not.toContain('docker stop'); + expect(kill).not.toContain('docker rm'); + }); + + it('still permits every verb for an owned container', () => { + const ownedDocker = toSessionDocker(HOST, caseFor(undefined)); + expect(buildDockerStopCommand(ownedDocker)).toContain('stop -t 10'); + expect(buildDockerRemoveCommand(ownedDocker)).toContain('rm -f'); + }); +}); + +describe('adopted container: drift is not evaluated', () => { + it('reports no drift rather than demanding a recreate we may not perform', async () => { + // An adopted container carries no codeman.confighash label, so a real + // comparison would always report drift and the launch gate would 409 forever. + const status = await checkDockerConfigDrift(toSessionDocker(HOST, caseFor(false))); + expect(status.drifted).toBe(false); + }); +}); From bc55b6b0daa352929b08e626f1aee91d68459616 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 02/26] feat(docker): add the attach-an-existing-container panel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Docker tab gains an "Attach to an existing container" toggle. Ticking it swaps the create-time fields (image, network, advanced) — which describe a `docker create` attaching never runs — for the container name, and routes the submit to the adopt endpoint. Reuses the existing linkDockerCase flow end to end: only the final call differs. The docker-host upsert still applies, since it is what resolves the engine/context/daemon for `docker exec`; its create-time fields are simply never read for an attached case. --- src/web/public/index.html | 15 ++++- src/web/public/session-ui.js | 83 +++++++++++++++++++++++++-- src/web/public/styles.css | 26 +++++++++ test/docker-adopted-container.test.ts | 36 ++++++++++++ 4 files changed, 153 insertions(+), 7 deletions(-) diff --git a/src/web/public/index.html b/src/web/public/index.html index d9491d45..bb5757b0 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2831,6 +2831,15 @@

Docker

Run the case inside a container: one per case, shared by all its sessions.

+
+ + On: Codeman only docker execs into a container you already built and run — it never creates, starts, stops or removes it. The CLIs must already be installed and logged in inside it. +
+
+ + + Must be running already. +
@@ -2846,12 +2855,12 @@ A reusable docker host profile. Reuse the same ID across cases to share settings.
-
+
Build it once with node scripts/build-agent-image.mjs. Contains node + claude/codex/gemini/opencode/agy/pi/grok/dsh + tmux.
-
+
-
+
Advanced container settings
diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index 6de0507c..24c1f49b 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -2334,6 +2334,14 @@ Object.assign(CodemanApp.prototype, { modal.querySelectorAll('.set-rail-item').forEach(btn => { btn.onclick = () => this.switchCaseModalTab(btn.dataset.tab); }); + // Adopt-an-existing-container toggle + its read-only preflight. Assigned (not + // addEventListener) so reopening the modal cannot stack duplicate handlers, + // matching the rail wiring right above. + const adoptToggle = document.getElementById('dockerAdoptExisting'); + if (adoptToggle) adoptToggle.onchange = () => this._syncDockerAdoptMode(); + const adoptCheck = document.getElementById('dockerAdoptCheckBtn'); + if (adoptCheck) adoptCheck.onclick = () => this._dockerAdoptPreflight(); + this._syncDockerAdoptMode(); // Scroll-into-view on focus for mobile keyboard visibility modal.querySelectorAll('input[type="text"]').forEach(input => { if (!input._mobileScrollWired) { @@ -2890,10 +2898,64 @@ Object.assign(CodemanApp.prototype, { } }, + /** + * Reflect the "attach to an existing container" checkbox onto the modal so CSS + * can swap which half of the Docker panel applies. An attribute rather than + * per-row inline styles: the panel is rebuilt by nothing, but the create-time + * rows are a SET (image, network, advanced block) and one attribute keeps them + * in lockstep with the container-name row. + */ + _syncDockerAdoptMode() { + const modal = document.getElementById('createCaseModal'); + if (!modal) return; + const adopting = document.getElementById('dockerAdoptExisting')?.checked; + if (adopting) modal.setAttribute('data-docker-adopt', '1'); + else modal.removeAttribute('data-docker-adopt'); + }, + + /** + * Read-only preflight against an existing container. It links nothing, so the + * user can find out "not running" / "no tmux" / "codex present, claude missing" + * before committing to a case name — the same reason the server refuses at link + * time rather than at session launch. + */ + async _dockerAdoptPreflight() { + const statusEl = document.getElementById('dockerLinkStatus'); + const container = document.getElementById('dockerContainerName')?.value.trim(); + const hostId = document.getElementById('dockerHostId').value.trim() || 'local'; + if (!container) { + if (statusEl) statusEl.textContent = 'Enter a container name first.'; + return; + } + if (statusEl) statusEl.textContent = 'Inspecting container...'; + // _apiJson folds every failure to null, and a preflight's whole value is the + // reason it failed, so the envelope is unwrapped by hand here. + const probe = await this._apiJson('/api/docker-cases/adopt-preflight', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ hostId, container }), + }); + if (!statusEl) return; + if (!probe) { + statusEl.textContent = 'Could not reach the docker host profile. Save a Host ID first.'; + return; + } + if (!probe.ok) { + statusEl.textContent = probe.error || 'Container is not adoptable.'; + return; + } + const modes = (probe.availableModes || []).filter((m) => m !== 'shell'); + statusEl.textContent = modes.length + ? `Running (${probe.image || 'unknown image'}). Available: ${modes.join(', ')}.` + : `Running (${probe.image || 'unknown image'}), but no agent CLI found inside — only Shell will work.`; + }, + async linkDockerCase() { const name = document.getElementById('dockerCaseName').value.trim(); const hostWorkspacePath = document.getElementById('dockerWorkspacePath').value.trim(); const hostId = document.getElementById('dockerHostId').value.trim() || 'local'; + const adopting = !!document.getElementById('dockerAdoptExisting')?.checked; + const container = document.getElementById('dockerContainerName')?.value.trim() || ''; const image = document.getElementById('dockerImage').value.trim() || 'codeman/agent:base'; const network = document.getElementById('dockerNetwork').value; const memory = document.getElementById('dockerMemory').value.trim(); @@ -2914,9 +2976,15 @@ Object.assign(CodemanApp.prototype, { this.showToast('Workspace path must be absolute', 'error'); return; } + if (adopting && !container) { + this.showToast('Enter the name of the running container to attach to', 'error'); + return; + } try { - if (statusEl) statusEl.textContent = 'Checking docker daemon + base image...'; + if (statusEl) { + statusEl.textContent = adopting ? 'Inspecting the existing container...' : 'Checking docker daemon + base image...'; + } // omitted optionals sent as UNDEFINED (never null — Zod .optional() rejects null) const resources = {}; if (memory) resources.memory = memory; @@ -2947,16 +3015,23 @@ Object.assign(CodemanApp.prototype, { } if (!hostData.success) throw new Error(hostData.error || 'Failed to save docker host'); - const caseRes = await fetch('/api/cases/docker-link', { + // Adoption reuses this whole flow and differs only in the final call: a + // different endpoint (which never creates a container) plus the container + // name. The host upsert above still applies — it is what resolves the + // engine/context/daemon for the `docker exec`; its create-time fields are + // simply never read for an adopted case. + const caseRes = await fetch(adopting ? '/api/cases/docker-adopt' : '/api/cases/docker-link', { method: 'POST', headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ name, hostId, hostWorkspacePath }), + body: JSON.stringify(adopting ? { name, hostId, hostWorkspacePath, container } : { name, hostId, hostWorkspacePath }), }); const caseData = await caseRes.json(); if (caseData.success) { this.closeCreateCaseModal(); const caps = caseData.data?.capsEnforced === false ? ' (resource caps are advisory on this engine)' : ''; - this.showToast(`Docker case "${name}" linked${caps}`, 'success'); + const modes = (caseData.data?.availableModes || []).filter((m) => m !== 'shell'); + const found = adopting && modes.length ? ` — found ${modes.join(', ')}` : ''; + this.showToast(`Docker case "${name}" ${adopting ? 'attached' : 'linked'}${caps}${found}`, 'success'); await this.loadQuickStartCases(name); await this.saveLastUsedCase(name); } else { diff --git a/src/web/public/styles.css b/src/web/public/styles.css index 8efb776e..7ca4edc3 100644 --- a/src/web/public/styles.css +++ b/src/web/public/styles.css @@ -16601,6 +16601,32 @@ html[data-tab-orientation='vertical'] .home-sessions { label as a row label, its `.form-hint` as a row description. Scoped to the document, so `.form-row` everywhere else is untouched. ─────────────────────────────────────────────────────────────────────────── */ +/* Adopt-an-existing-container mode swaps which half of the Docker panel applies: + the create-time fields (image, network, resources, credential mounts) describe + a `docker create` that adoption never runs, and the container name is the one + field only adoption needs. `.docker-adopt-only` is hidden by default so the + panel stays exactly as it was until the checkbox is ticked. Rules carry + `!important` because the adapter block above paints `.form-row` as a row card + and `details.advanced-options` has its own display. */ +#createCaseModal .docker-adopt-only { + display: none !important; +} +#createCaseModal[data-docker-adopt='1'] .docker-adopt-only { + display: block !important; +} +#createCaseModal[data-docker-adopt='1'] .docker-create-only { + display: none !important; +} +#createCaseModal .btn-inline-check { + background: none; + border: none; + padding: 0; + font: inherit; + color: var(--accent, #4a9eff); + cursor: pointer; + text-decoration: underline; +} + #createCaseModal .set-doc .form-row { margin: 0 0 3px; padding: 7px 10px; diff --git a/test/docker-adopted-container.test.ts b/test/docker-adopted-container.test.ts index 9561bf49..cd15a443 100644 --- a/test/docker-adopted-container.test.ts +++ b/test/docker-adopted-container.test.ts @@ -10,6 +10,7 @@ * Mirror of the `owned:false` remote-SSH contract (COD-105). */ import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; import { toSessionDocker, isAdoptedContainer, @@ -158,6 +159,41 @@ describe('adopted container: mutating verbs fail closed at the builder', () => { }); }); +describe('adopted container: the Add Case panel id contract', () => { + // The modal's load/save contract is getElementById by fixed id, so a renamed or + // dropped id stops the control working with no error anywhere. Static guard in + // the style of app-settings-structure / session-options-structure. + const html = readFileSync(new URL('../src/web/public/index.html', import.meta.url), 'utf8'); + const ui = readFileSync(new URL('../src/web/public/session-ui.js', import.meta.url), 'utf8'); + const css = readFileSync(new URL('../src/web/public/styles.css', import.meta.url), 'utf8'); + + it('ships every id session-ui.js reads back', () => { + for (const id of ['dockerAdoptExisting', 'dockerContainerName', 'dockerAdoptCheckBtn']) { + expect(html).toContain(`id="${id}"`); + expect(ui).toContain(`'${id}'`); + } + }); + + it('routes adoption to the endpoint that never creates a container', () => { + expect(ui).toContain('/api/cases/docker-adopt'); + expect(ui).toContain('/api/docker-cases/adopt-preflight'); + // The create path must survive untouched beside it. + expect(ui).toContain('/api/cases/docker-link'); + }); + + it('hides the adopt-only row until the toggle is on, so the panel is unchanged by default', () => { + expect(css).toContain('#createCaseModal .docker-adopt-only'); + expect(css).toMatch(/#createCaseModal \.docker-adopt-only \{\s*display: none/); + expect(css).toContain("#createCaseModal[data-docker-adopt='1'] .docker-adopt-only"); + }); + + it('marks the create-time rows so adoption hides the fields it never uses', () => { + // image / network / advanced describe a `docker create` adoption never runs. + expect(html.match(/docker-create-only/g)?.length).toBeGreaterThanOrEqual(3); + expect(css).toContain("#createCaseModal[data-docker-adopt='1'] .docker-create-only"); + }); +}); + describe('adopted container: drift is not evaluated', () => { it('reports no drift rather than demanding a recreate we may not perform', async () => { // An adopted container carries no codeman.confighash label, so a real From c98a59d7090b5ee526fe1f71cf7fb4554d79764e Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 03/26] fix(docker): verify the container workdir and end the probe with exit 0 Two defects that only a real container exposes. The probe chained `command -v X && echo X` with semicolons, and a script's exit status is its last command's. A container without the last probed CLI made the whole `sh -lc` exit 1, so a perfectly healthy container with tmux and claude was reported as "could not exec into the container". A missing CLI is data here, not failure, so the script now ends with `exit 0`. containerWorkdir defaulted to hostWorkspacePath. That default holds for an owned container only because the create-time bind mount puts the host directory at that exact path; attaching mounts nothing, so the two are independent facts. A host path absent inside the container makes `docker exec --workdir` fail with an OCI chdir error that surfaces in the pane as a bare "execvp failed". The preflight now proves the directory exists inside the container and refuses at link time. --- src/docker-hosts.ts | 40 ++++++++++++++++++++++++++++++++--- src/web/public/index.html | 5 +++++ src/web/public/session-ui.js | 10 +++++++-- src/web/routes/case-routes.ts | 13 ++++++++++-- src/web/schemas.ts | 8 +++++++ 5 files changed, 69 insertions(+), 7 deletions(-) diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts index b49502a5..c039815d 100644 --- a/src/docker-hosts.ts +++ b/src/docker-hosts.ts @@ -1044,6 +1044,8 @@ export interface AdoptedContainerProbe { tmuxPath?: string; /** Modes whose CLI resolved inside the container (`command -v `). */ availableModes?: SessionMode[]; + /** Whether the requested working directory exists INSIDE the container. */ + workdirExists?: boolean; error?: string; } @@ -1059,10 +1061,18 @@ export interface AdoptedContainerProbe { */ export async function probeAdoptableContainer( docker: Pick, - modes: SessionMode[] = [] + modes: SessionMode[] = [], + containerWorkdir?: string ): Promise { if (IS_TEST_MODE) { - return { ok: true, exists: true, running: true, tmuxPath: '/usr/bin/tmux', availableModes: modes }; + return { + ok: true, + exists: true, + running: true, + tmuxPath: '/usr/bin/tmux', + availableModes: modes, + workdirExists: true, + }; } const argv = dockerEngineArgv(docker); let running = false; @@ -1096,7 +1106,19 @@ export async function probeAdoptableContainer( // One exec resolves tmux plus every requested CLI, so adoption costs a single // round trip. Binaries are fixed mode names, never user input. const probes = ['tmux', ...modes.filter((m) => m !== 'shell')]; - const script = probes.map((bin) => `command -v ${bin} >/dev/null 2>&1 && echo ${bin}`).join('; '); + // `; exit 0` is load-bearing: the script's status is its LAST command's, so a + // missing final CLI made the whole `sh -lc` exit 1 and the probe reported + // "could not exec into the container" for a container that was perfectly fine. + // Absence of a CLI is data here, not failure — only a real exec error is. + const steps = probes.map((bin) => `command -v ${bin} >/dev/null 2>&1 && echo ${bin}`); + // The workdir is checked INSIDE the container, and that is a fact independent + // of hostWorkspacePath: an owned container gets the host dir bind-mounted at the + // same absolute path at create time, but adoption mounts nothing, so the two + // paths only coincide if the user mounted it there themselves. `docker exec + // --workdir ` fails with an OCI chdir error the pane surfaces as a bare + // "execvp failed", so it is resolved here into an actionable message. + if (containerWorkdir) steps.push(`[ -d ${shellescape(containerWorkdir)} ] && echo __workdir__`); + const script = `${steps.join('; ')}; exit 0`; try { const { stdout } = await execFileAsync( argv[0], @@ -1118,6 +1140,17 @@ export async function probeAdoptableContainer( error: `container "${docker.containerName}" has no tmux (required for durable sessions; install it inside the container)`, }; } + const workdirExists = containerWorkdir ? found.has('__workdir__') : undefined; + if (containerWorkdir && !workdirExists) { + return { + ok: false, + exists: true, + running: true, + image, + workdirExists: false, + error: `"${containerWorkdir}" does not exist inside container "${docker.containerName}". Adoption mounts nothing, so the container workdir must already exist there — set it to a path inside the container (it need not match the host workspace path).`, + }; + } return { ok: true, exists: true, @@ -1125,6 +1158,7 @@ export async function probeAdoptableContainer( image, tmuxPath: 'tmux', availableModes: modes.filter((m) => m === 'shell' || found.has(m)), + workdirExists, }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); diff --git a/src/web/public/index.html b/src/web/public/index.html index bb5757b0..4d54096a 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2840,6 +2840,11 @@ Must be running already.
+
+ + + A path that already exists inside the container. Adoption mounts nothing, so this need not match the host workspace path — leave blank to reuse it only if you mounted it there yourself. +
diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index 24c1f49b..9da4990d 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -2922,6 +2922,7 @@ Object.assign(CodemanApp.prototype, { async _dockerAdoptPreflight() { const statusEl = document.getElementById('dockerLinkStatus'); const container = document.getElementById('dockerContainerName')?.value.trim(); + const containerWorkdir = document.getElementById('dockerAdoptWorkdir')?.value.trim(); const hostId = document.getElementById('dockerHostId').value.trim() || 'local'; if (!container) { if (statusEl) statusEl.textContent = 'Enter a container name first.'; @@ -2933,7 +2934,7 @@ Object.assign(CodemanApp.prototype, { const probe = await this._apiJson('/api/docker-cases/adopt-preflight', { method: 'POST', headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ hostId, container }), + body: JSON.stringify({ hostId, container, ...(containerWorkdir ? { containerWorkdir } : {}) }), }); if (!statusEl) return; if (!probe) { @@ -2956,6 +2957,7 @@ Object.assign(CodemanApp.prototype, { const hostId = document.getElementById('dockerHostId').value.trim() || 'local'; const adopting = !!document.getElementById('dockerAdoptExisting')?.checked; const container = document.getElementById('dockerContainerName')?.value.trim() || ''; + const adoptWorkdir = document.getElementById('dockerAdoptWorkdir')?.value.trim() || ''; const image = document.getElementById('dockerImage').value.trim() || 'codeman/agent:base'; const network = document.getElementById('dockerNetwork').value; const memory = document.getElementById('dockerMemory').value.trim(); @@ -3023,7 +3025,11 @@ Object.assign(CodemanApp.prototype, { const caseRes = await fetch(adopting ? '/api/cases/docker-adopt' : '/api/cases/docker-link', { method: 'POST', headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(adopting ? { name, hostId, hostWorkspacePath, container } : { name, hostId, hostWorkspacePath }), + body: JSON.stringify( + adopting + ? { name, hostId, hostWorkspacePath, container, ...(adoptWorkdir ? { containerWorkdir: adoptWorkdir } : {}) } + : { name, hostId, hostWorkspacePath } + ), }); const caseData = await caseRes.json(); if (caseData.success) { diff --git a/src/web/routes/case-routes.ts b/src/web/routes/case-routes.ts index 49c94e2e..6e526995 100644 --- a/src/web/routes/case-routes.ts +++ b/src/web/routes/case-routes.ts @@ -837,7 +837,15 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config availability.error || 'docker daemon is not available' ); } - const probe = await probeAdoptableContainer(toSessionDocker(host, dockerCase), [...DOCKER_ADOPT_PROBE_MODES]); + // The container workdir is validated INSIDE the container. It defaults to + // hostWorkspacePath only because that is what an owned container's bind + // mount guarantees; adoption mounts nothing, so the probe has to prove it. + const adoptDocker = toSessionDocker(host, dockerCase); + const probe = await probeAdoptableContainer( + adoptDocker, + [...DOCKER_ADOPT_PROBE_MODES], + adoptDocker.containerWorkdir + ); if (!probe.ok) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not adoptable'); } @@ -871,7 +879,8 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config daemonHost: host.daemonHost, containerName: body.container, }, - [...DOCKER_ADOPT_PROBE_MODES] + [...DOCKER_ADOPT_PROBE_MODES], + body.containerWorkdir ); return { success: true, data: probe }; }); diff --git a/src/web/schemas.ts b/src/web/schemas.ts index c5860388..65ef1395 100644 --- a/src/web/schemas.ts +++ b/src/web/schemas.ts @@ -834,6 +834,14 @@ export const DockerAdoptPreflightSchema = z.object({ .min(2) .max(128) .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'), + /** Optional: also verify this path exists INSIDE the container. */ + containerWorkdir: z + .string() + .min(1) + .max(2000) + .regex(/^\//, 'Container workdir must be absolute') + .regex(NO_SHELL_META, 'Invalid characters in container workdir') + .optional(), }); export const DockerExportSchema = z.object({ From bb45909169a2df78c77db18ece60f6f35d36e229 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 04/26] feat(docker): link to container attach from the Create New tab Attaching lived only on the Docker tab, but the place users look for anything container-shaped is the "Run in an isolated Docker container" checkbox on Create New. A feature nobody can find is a feature nobody has. Adds a one-click link there that switches to the Docker tab, turns the toggle on and focuses the container field. Reuses switchCaseModalTab and the existing sync helper; no new CSS. --- src/web/public/index.html | 1 + src/web/public/session-ui.js | 16 ++++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/src/web/public/index.html b/src/web/public/index.html index 4d54096a..9734ec06 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2629,6 +2629,7 @@
Runs this case in a hardened, isolated container. The base image is built automatically on first use. Docker/Podman must be installed. + Already have a container running? — Codeman only docker execs in and never touches its lifecycle.
Container settings (optional, sensible defaults) diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index 9da4990d..8cedd647 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -2341,6 +2341,8 @@ Object.assign(CodemanApp.prototype, { if (adoptToggle) adoptToggle.onchange = () => this._syncDockerAdoptMode(); const adoptCheck = document.getElementById('dockerAdoptCheckBtn'); if (adoptCheck) adoptCheck.onclick = () => this._dockerAdoptPreflight(); + const adoptJump = document.getElementById('dockerAdoptJumpBtn'); + if (adoptJump) adoptJump.onclick = () => this.jumpToDockerAdopt(); this._syncDockerAdoptMode(); // Scroll-into-view on focus for mobile keyboard visibility modal.querySelectorAll('input[type="text"]').forEach(input => { @@ -2913,6 +2915,20 @@ Object.assign(CodemanApp.prototype, { else modal.removeAttribute('data-docker-adopt'); }, + /** + * Cross-link from the Create New tab's "Run in an isolated Docker container" + * row. Adoption lives on the Docker tab, but the place users actually look for + * anything container-shaped is that checkbox, so this jumps them there with the + * toggle already on rather than leaving the feature undiscoverable. + */ + jumpToDockerAdopt() { + this.switchCaseModalTab('case-docker'); + const toggle = document.getElementById('dockerAdoptExisting'); + if (toggle) toggle.checked = true; + this._syncDockerAdoptMode(); + document.getElementById('dockerContainerName')?.focus(); + }, + /** * Read-only preflight against an existing container. It links nothing, so the * user can find out "not running" / "no tmux" / "codex present, claude missing" From e2f750cb304f79e7a30b5acc9e4c2540bcf5aada Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 05/26] i18n(docker): translate the attach panel, and unblock translation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new strings were English only. Adding entries surfaced a deeper problem: the translator matches whole text nodes and skips `code`/`pre`, so an inline `` mid-sentence splits a hint into fragments that can never match an entry — which is why the panel's existing "Build it once with ..." hint was never translated either. Drops the inline markup from the new hints so each is a single text node, then adds the zh-CN entries. The brand name goes through the existing {name} placeholder. Server-side error bodies are deliberately not added: the client receives them already interpolated with a concrete container name, so a template key could never match. --- src/web/public/i18n.js | 13 +++++++++++++ src/web/public/index.html | 6 +++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/src/web/public/i18n.js b/src/web/public/i18n.js index fbdcc296..f9d83ab8 100644 --- a/src/web/public/i18n.js +++ b/src/web/public/i18n.js @@ -713,6 +713,19 @@ 'Runs this case in a hardened, isolated container. The base image is built automatically on first use. Docker/Podman must be installed.': '在加固的隔离容器中运行此案例。首次使用时会自动构建基础镜像；必须安装 Docker/Podman。', 'Run in an isolated Docker container': '在隔离的 Docker 容器中运行', + 'Attach to an existing container': '接入已在运行的容器', + 'On: Codeman only runs docker exec into a container you already built and run — it never creates, starts, stops or removes it. The CLIs must already be installed and logged in inside it.': + '开启后，{name}只会 docker exec 进入你自己构建并运行的容器，绝不创建、启动、停止或删除它；容器内必须已安装并登录好相应 CLI。', + 'Container Name': '容器名称', + 'Must be running already.': '该容器必须已在运行。', + 'Check container': '检查容器', + 'Container Workdir': '容器内工作目录', + 'A path that already exists inside the container. Adoption mounts nothing, so this need not match the host workspace path.': + '容器内已存在的路径。接入不挂载任何目录，因此它不必与主机工作区路径相同。', + 'Already have a container running?': '已经有正在运行的容器？', + 'Attach to it instead': '改为接入该容器', + 'Codeman only runs docker exec into it and never touches its lifecycle.': + '{name}只会 docker exec 进入它，绝不触碰其生命周期。', 'Absolute HOST directory, bind-mounted into the container. Codeman scaffolds CLAUDE.md + hooks into it.': '绑定挂载到容器中的主机绝对目录；{name}会在其中生成 CLAUDE.md 和 hooks。', 'A reusable docker host profile. Reuse the same ID across cases to share settings.': diff --git a/src/web/public/index.html b/src/web/public/index.html index 9734ec06..7e1024e4 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2629,7 +2629,7 @@
Runs this case in a hardened, isolated container. The base image is built automatically on first use. Docker/Podman must be installed. - Already have a container running? — Codeman only docker execs in and never touches its lifecycle. + Already have a container running? Codeman only runs docker exec into it and never touches its lifecycle.
Container settings (optional, sensible defaults) @@ -2834,7 +2834,7 @@

Run the case inside a container: one per case, shared by all its sessions.

- On: Codeman only docker execs into a container you already built and run — it never creates, starts, stops or removes it. The CLIs must already be installed and logged in inside it. + On: Codeman only runs docker exec into a container you already built and run — it never creates, starts, stops or removes it. The CLIs must already be installed and logged in inside it.
@@ -2844,7 +2844,7 @@
- A path that already exists inside the container. Adoption mounts nothing, so this need not match the host workspace path — leave blank to reuse it only if you mounted it there yourself. + A path that already exists inside the container. Adoption mounts nothing, so this need not match the host workspace path.
From 34c12ca18bc2b0827a7510517fb2c2fd33c9ec74 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 06/26] feat(docker): make the container field a picker you can also type into Typing a container name from memory is error-prone. The field becomes a native datalist: pick from the engine's containers, type to filter, or type a name that is not listed (the engine may be remote, or the container may not exist yet). A datalist gives all three natively, so no dropdown state machine is introduced. Adds listDockerContainers and GET /api/docker-hosts/:hostId/containers, following the listRemoteCodemanSessions discovery precedent: read-only and never throwing, so an unreachable daemon returns an empty list and the field degrades to plain text instead of erroring. Stopped containers stay in the list, sorted after running ones and labelled. Attaching does require a running container, but hiding stopped ones turns "my container is not in the list" into a dead end, while showing `Exited (137) 8 days ago` says exactly what to fix. --- src/docker-hosts.ts | 49 +++++++++++++++++++++++++++++++++++ src/web/public/i18n.js | 2 +- src/web/public/index.html | 5 ++-- src/web/public/session-ui.js | 40 ++++++++++++++++++++++++++++ src/web/routes/case-routes.ts | 24 ++++++++++++++++- 5 files changed, 116 insertions(+), 4 deletions(-) diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts index c039815d..7ad11346 100644 --- a/src/docker-hosts.ts +++ b/src/docker-hosts.ts @@ -1049,6 +1049,55 @@ export interface AdoptedContainerProbe { error?: string; } +/** One container on the engine, as offered to the adoption picker. */ +export interface DockerContainerInfo { + name: string; + image: string; + running: boolean; + /** Engine's own status string, e.g. "Up 3 hours" / "Exited (0) 2 days ago". */ + status: string; +} + +/** + * List the engine's containers for the adoption picker (mirror of + * `listRemoteCodemanSessions`). Read-only and NEVER throws: an unreachable + * daemon, a missing engine or zero containers all return `[]`, because this + * feeds a convenience picker whose input the user can always type by hand. + * + * Stopped containers ARE included, sorted after running ones and carrying their + * status: adoption requires a running container, but hiding a stopped one turns + * "my container is not in the list" into a dead end with no explanation, while + * showing `my-box (Exited (0) 2 days ago)` says exactly what to fix. + */ +export async function listDockerContainers( + docker: Pick +): Promise { + if (IS_TEST_MODE) return []; + const argv = dockerEngineArgv(docker); + try { + const { stdout } = await execFileAsync( + argv[0], + [...argv.slice(1), 'ps', '-a', '--format', '{{.Names}}\t{{.Image}}\t{{.State}}\t{{.Status}}'], + { timeout: DOCKER_PROBE_TIMEOUT_MS } + ); + const rows = stdout + .split('\n') + .map((line) => line.split('\t')) + .filter((parts) => parts.length >= 4 && parts[0]) + .map(([name, image, state, status]) => ({ + name, + image: image || '', + running: state === 'running', + status: status || '', + })); + // Running first, then by name, so the containers a user can actually adopt + // are the ones at the top of the list. + return rows.sort((a, b) => Number(b.running) - Number(a.running) || a.name.localeCompare(b.name)); + } catch { + return []; + } +} + /** * Preflight an EXISTING container for adoption. Read-only by construction: it * runs `inspect` plus one `exec` of `command -v`, and never creates, starts or diff --git a/src/web/public/i18n.js b/src/web/public/i18n.js index f9d83ab8..30ee874d 100644 --- a/src/web/public/i18n.js +++ b/src/web/public/i18n.js @@ -717,7 +717,7 @@ 'On: Codeman only runs docker exec into a container you already built and run — it never creates, starts, stops or removes it. The CLIs must already be installed and logged in inside it.': '开启后，{name}只会 docker exec 进入你自己构建并运行的容器，绝不创建、启动、停止或删除它；容器内必须已安装并登录好相应 CLI。', 'Container Name': '容器名称', - 'Must be running already.': '该容器必须已在运行。', + 'Pick from the running containers or type a name.': '从正在运行的容器中选择，或直接输入名称。', 'Check container': '检查容器', 'Container Workdir': '容器内工作目录', 'A path that already exists inside the container. Adoption mounts nothing, so this need not match the host workspace path.': diff --git a/src/web/public/index.html b/src/web/public/index.html index 7e1024e4..f83a17d9 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2838,8 +2838,9 @@
- - Must be running already. + + + Pick from the running containers or type a name.
diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index 8cedd647..2377c37d 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -2343,6 +2343,18 @@ Object.assign(CodemanApp.prototype, { if (adoptCheck) adoptCheck.onclick = () => this._dockerAdoptPreflight(); const adoptJump = document.getElementById('dockerAdoptJumpBtn'); if (adoptJump) adoptJump.onclick = () => this.jumpToDockerAdopt(); + // Containers come from the host profile, so switching Host ID invalidates the + // suggestions. Dropping the marker (rather than refetching here) keeps the + // fetch lazy — it happens when adopt mode is actually on. + const hostIdInput = document.getElementById('dockerHostId'); + if (hostIdInput) { + hostIdInput.onchange = () => { + delete document.getElementById('dockerContainerList')?.dataset.loadedFor; + if (document.getElementById('dockerAdoptExisting')?.checked) void this._loadDockerContainerOptions(); + }; + } + // A fresh open re-reads the engine: containers start and stop between visits. + delete document.getElementById('dockerContainerList')?.dataset.loadedFor; this._syncDockerAdoptMode(); // Scroll-into-view on focus for mobile keyboard visibility modal.querySelectorAll('input[type="text"]').forEach(input => { @@ -2913,6 +2925,34 @@ Object.assign(CodemanApp.prototype, { const adopting = document.getElementById('dockerAdoptExisting')?.checked; if (adopting) modal.setAttribute('data-docker-adopt', '1'); else modal.removeAttribute('data-docker-adopt'); + if (adopting) void this._loadDockerContainerOptions(); + }, + + /** + * Fill the container-name ``. A native datalist is deliberate: the + * field must accept a free-typed name (the engine may be remote, or the + * container may not exist yet when the form is filled), and datalist gives + * type-to-filter over the suggestions without a custom dropdown. + * + * Best-effort by design — the endpoint returns [] for an unreachable daemon, + * and an empty list simply leaves the field as plain text input. + */ + async _loadDockerContainerOptions() { + const list = document.getElementById('dockerContainerList'); + if (!list) return; + const hostId = document.getElementById('dockerHostId')?.value.trim() || 'local'; + if (list.dataset.loadedFor === hostId) return; // one fetch per host per open + const data = await this._apiJson(`/api/docker-hosts/${encodeURIComponent(hostId)}/containers`); + const containers = data?.containers || []; + list.textContent = ''; + for (const c of containers) { + const option = document.createElement('option'); + option.value = c.name; + // Engine-supplied strings: set as text, never as markup. + option.textContent = c.running ? `${c.image} · ${c.status}` : `${c.image} · ${c.status} (not running)`; + list.appendChild(option); + } + list.dataset.loadedFor = hostId; }, /** diff --git a/src/web/routes/case-routes.ts b/src/web/routes/case-routes.ts index 6e526995..fc2079d3 100644 --- a/src/web/routes/case-routes.ts +++ b/src/web/routes/case-routes.ts @@ -69,6 +69,7 @@ import { dockerContainerName, dockerDisplayPath, probeAdoptableContainer, + listDockerContainers, DOCKER_ADOPT_PROBE_MODES, readDockerCases, readDockerHosts, @@ -77,7 +78,7 @@ import { writeDockerCases, writeDockerHosts, } from '../../docker-hosts.js'; -import type { AdoptedContainerProbe } from '../../docker-hosts.js'; +import type { AdoptedContainerProbe, DockerContainerInfo } from '../../docker-hosts.js'; import { buildDockerRemoveCommand } from '../../tmux-manager.js'; import { checkRemoteTmuxAvailable, @@ -868,6 +869,27 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config * the user "not running" / "no tmux" / "codex present, claude missing" before * they commit to a case name. Read-only; never touches container lifecycle. */ + /** + * Containers on the host's engine, for the adoption picker. Read-only and + * best-effort (mirror of the remote `:hostId/sessions` discovery route): an + * unreachable daemon yields an empty list rather than an error, because the + * container name is a free-text field the user can always type by hand. + */ + app.get( + '/api/docker-hosts/:hostId/containers', + async (req): Promise> => { + const { hostId } = req.params as { hostId: string }; + const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === hostId); + if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found'); + const containers = await listDockerContainers({ + engine: host.engine ?? 'docker', + context: host.context, + daemonHost: host.daemonHost, + }); + return { success: true, data: { containers } }; + } + ); + app.post('/api/docker-cases/adopt-preflight', async (req): Promise> => { const body = parseBody(DockerAdoptPreflightSchema, req.body); const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId); From 2f83a37c6d69b7e25ffc3b81d914116f6df412fd Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:02:19 -0700 Subject: [PATCH 07/26] feat(docker): take run-mode availability from the container The run-mode dropdown hides CLIs that are not installed on the HOST (#201). That is right for local sessions and wrong for a container case, whose agents run inside the container: a host with no claude installed hides the mode while the container ships one, which is exactly what happened on a real deployment. The adoption preflight already probes what the container has, so that result is persisted on the case and surfaced through CaseInfo. Docker cases gate on it; every other case keeps the host probe unchanged. An absent list reads as "do not gate" rather than "nothing available": an owned container runs our base image, which ships every CLI, and treating unknown as empty would leave the menu with Shell alone. --- src/types/api.ts | 7 +++++++ src/types/session.ts | 9 +++++++++ src/web/public/session-ui.js | 16 ++++++++++++++- src/web/routes/case-routes.ts | 13 +++++++++---- test/docker-adopted-container.test.ts | 28 +++++++++++++++++++++++++++ 5 files changed, 68 insertions(+), 5 deletions(-) diff --git a/src/types/api.ts b/src/types/api.ts index b63268af..a57b2795 100644 --- a/src/types/api.ts +++ b/src/types/api.ts @@ -167,6 +167,13 @@ export interface CaseInfo { image?: string; path: string; network?: string; + /** + * CLIs available INSIDE the container. A container case runs its agents in + * the container, so HOST CLI availability says nothing about what it can + * run. Absent = unknown (an owned container runs our base image, which ships + * every CLI), which the UI reads as "do not gate". + */ + availableModes?: string[]; }; } diff --git a/src/types/session.ts b/src/types/session.ts index 7187dae4..21e117b9 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -261,6 +261,15 @@ export interface DockerCase { * all created by us). */ owned?: boolean; + /** + * CLIs found INSIDE the container by the adoption preflight. A container case + * runs its agents in the container, so host CLI availability says nothing about + * what this case can run — the base image ships every CLI, and an adopted + * container ships whatever its owner installed. Absent = unknown (owned cases, + * or a case linked before this field existed), which callers read as "do not + * gate". + */ + availableModes?: SessionMode[]; /** Last captured Claude conversation id, replayed via --resume on a fresh launch. */ lastClaudeSessionId?: string; } diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index 2377c37d..b43e4288 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -474,9 +474,23 @@ Object.assign(CodemanApp.prototype, { * run modes like the rest, and neither `agy` nor `pi` is likely to be installed. */ _refreshRunModeAvailability(menu) { + // A DOCKER case runs its agents INSIDE the container, so host CLI + // availability answers the wrong question: the host may have no claude at + // all while the container ships one, and gating on the host hides a mode + // that would have worked. Adoption records what the container really has + // (`availableModes`); an owned container runs our base image, which ships + // every CLI, so an absent list means "do not gate" rather than "nothing". + // Same source every run* path reads the selected case from. + const caseName = document.getElementById('quickStartCase')?.value; + const activeCase = caseName ? (this.cases || []).find((c) => c.name === caseName) : null; + const containerModes = activeCase?.location === 'docker' ? activeCase.docker?.availableModes : null; for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']) { const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`); - if (btn) btn.style.display = this.isCliAvailable(mode) ? 'flex' : 'none'; + if (!btn) continue; + let available; + if (activeCase?.location === 'docker') available = containerModes ? containerModes.includes(mode) : true; + else available = this.isCliAvailable(mode); + btn.style.display = available ? 'flex' : 'none'; } // DeepSeek is the one mode whose availability has two halves: `dsh` can be // perfectly installed while no pane-capable profile exists, because DeepSeek diff --git a/src/web/routes/case-routes.ts b/src/web/routes/case-routes.ts index fc2079d3..11ac46e7 100644 --- a/src/web/routes/case-routes.ts +++ b/src/web/routes/case-routes.ts @@ -297,6 +297,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config image: host.image, path: dockerCase.hostWorkspacePath, network: host.network ?? 'bridge', + ...(dockerCase.availableModes ? { availableModes: dockerCase.availableModes } : {}), }, }; const existingIndex = cases.findIndex((item) => item.name === dockerCase.name); @@ -851,15 +852,19 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not adoptable'); } - await writeDockerCases(CODEMAN_CONFIG_DIR, [...dockerCases, dockerCase]); + // Persist what the container actually has: the run-mode picker gates on + // HOST CLIs, which is the wrong question for a case whose agents run inside + // a container the host knows nothing about. + const adoptedCase = { ...dockerCase, availableModes: probe.availableModes }; + await writeDockerCases(CODEMAN_CONFIG_DIR, [...dockerCases, adoptedCase]); ctx.broadcast(SseEvent.CaseLinked, { - name: dockerCase.name, - path: dockerCase.hostWorkspacePath, + name: adoptedCase.name, + path: adoptedCase.hostWorkspacePath, type: 'docker', }); return { success: true, - data: { case: dockerCase, image: probe.image, availableModes: probe.availableModes }, + data: { case: adoptedCase, image: probe.image, availableModes: probe.availableModes }, }; } ); diff --git a/test/docker-adopted-container.test.ts b/test/docker-adopted-container.test.ts index cd15a443..1c14463c 100644 --- a/test/docker-adopted-container.test.ts +++ b/test/docker-adopted-container.test.ts @@ -194,6 +194,34 @@ describe('adopted container: the Add Case panel id contract', () => { }); }); +describe('adopted container: run modes come from the CONTAINER, not the host', () => { + const ui = readFileSync(new URL('../src/web/public/session-ui.js', import.meta.url), 'utf8'); + /** Slice the method BODY. Anchored on the definition, not a call site: the + * menu opener calls _loadRunModeHistory() ABOVE this definition, so slicing + * between call sites silently yields an empty string and passes nothing. */ + const refreshFn = (src) => { + const start = src.indexOf('_refreshRunModeAvailability(menu) {'); + expect(start).toBeGreaterThan(-1); + return src.slice(start, start + 1600); + }; + + it('gates a docker case on availableModes instead of host CLI probes', () => { + // The sandbox host had codex but no claude while the adopted container had + // claude and no codex; gating on the host hid the only mode that worked. + const fn = refreshFn(ui); + expect(fn).toContain("location === 'docker'"); + expect(fn).toContain('availableModes'); + // Non-docker cases must keep the original host probe (#201). + expect(fn).toContain('this.isCliAvailable(mode)'); + }); + + it('leaves an owned container ungated when nothing was probed', () => { + // Our base image ships every CLI, so an absent list means "unknown", and + // treating unknown as "nothing available" would empty the menu. + expect(refreshFn(ui)).toMatch(/containerModes \?[^:]*:\s*true/); + }); +}); + describe('adopted container: drift is not evaluated', () => { it('reports no drift rather than demanding a recreate we may not perform', async () => { // An adopted container carries no codeman.confighash label, so a real From 8b20f5b1f8aa004bfd484a5df89dd4a32c8b811b Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:01:28 -0700 Subject: [PATCH 08/26] fix(docker): probe container CLIs by their real binary name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The adoption preflight used the mode name as the binary name. claude, codex, opencode, gemini and pi happen to match, so it never showed — but antigravity ships as `agy` and deepseek as `dsh`, so a container that has either was reported as not having it, and the mode was silently dropped from the case. Adds a MODE_BINARIES map, single-sourced with defaultDockerCommandForMode, which launches those same binaries. Probing and result filtering share one `binaryFor` so the two cannot drift apart. --- src/docker-hosts.ts | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts index 7ad11346..d9d2de1b 100644 --- a/src/docker-hosts.ts +++ b/src/docker-hosts.ts @@ -67,9 +67,19 @@ export const DOCKER_ADOPT_PROBE_MODES = [ 'gemini', 'antigravity', 'pi', + 'grok', + 'deepseek', 'shell', ] as const satisfies readonly SessionMode[]; +/** + * The BINARY a mode looks for inside a container. Not always the mode name: + * `antigravity` ships as `agy` and `deepseek` as `dsh`, so probing by mode name + * would report those two as missing on a container that has them. Single source + * with `defaultDockerCommandForMode`, which launches the same binaries. + */ +const MODE_BINARIES: Partial> = { antigravity: 'agy', deepseek: 'dsh' }; + /** Per-case container name prefix. The `case` letters deliberately do NOT matter to * tmux; this is a DOCKER name (`^[a-zA-Z0-9][a-zA-Z0-9_.-]+$`), and case names are * already validated `^[a-zA-Z0-9_-]+$`, so `codeman-case-` is always valid. */ @@ -1154,7 +1164,9 @@ export async function probeAdoptableContainer( } // One exec resolves tmux plus every requested CLI, so adoption costs a single // round trip. Binaries are fixed mode names, never user input. - const probes = ['tmux', ...modes.filter((m) => m !== 'shell')]; + const wanted = modes.filter((m) => m !== 'shell'); + const binaryFor = (mode: SessionMode) => MODE_BINARIES[mode] ?? mode; + const probes = ['tmux', ...wanted.map(binaryFor)]; // `; exit 0` is load-bearing: the script's status is its LAST command's, so a // missing final CLI made the whole `sh -lc` exit 1 and the probe reported // "could not exec into the container" for a container that was perfectly fine. @@ -1206,7 +1218,7 @@ export async function probeAdoptableContainer( running: true, image, tmuxPath: 'tmux', - availableModes: modes.filter((m) => m === 'shell' || found.has(m)), + availableModes: modes.filter((m) => m === 'shell' || found.has(binaryFor(m))), workdirExists, }; } catch (err) { From 06e7cbe2860baa30c01eafde6610796e456226d4 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 21:19:17 -0700 Subject: [PATCH 09/26] fix(docker): probe the container's CLIs live instead of trusting attach time MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Storing the container's CLIs on the case at attach time left two gaps: a case linked before that field existed has none at all, and a container's CLIs can be installed or removed long after it was linked. A real deployment hit the first one — the host had only codex, the container only claude, and with no stored list the menu still gated on the host and hid the mode that actually worked. The probe now runs when a container case is selected, reusing the existing adopt-preflight endpoint, so there is no new backend surface. Results are cached per case for the page's lifetime, since the menu opens often and the probe is a `docker exec` round trip; a concurrent probe for the same case is deduplicated with an in-flight marker. A failed probe leaves the cache empty, which the caller reads as "unknown" and therefore does not gate. Hiding every mode because one probe failed is worse than offering one that turns out to be missing, which the launch path already refuses with a specific message. The repaint only happens while the menu is still open, so a late answer cannot make the list jump under a user who already closed it. --- src/web/public/session-ui.js | 45 +++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index b43e4288..ebb9eec1 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -483,7 +483,14 @@ Object.assign(CodemanApp.prototype, { // Same source every run* path reads the selected case from. const caseName = document.getElementById('quickStartCase')?.value; const activeCase = caseName ? (this.cases || []).find((c) => c.name === caseName) : null; - const containerModes = activeCase?.location === 'docker' ? activeCase.docker?.availableModes : null; + const isDocker = activeCase?.location === 'docker'; + // Prefer a LIVE probe over the value stored at attach time: a container's + // CLIs can be installed or removed long after the case was linked, and a + // case linked before that field existed has none at all. + const containerModes = isDocker + ? this._dockerCaseModes?.[caseName] || activeCase.docker?.availableModes || null + : null; + if (isDocker && !this._dockerCaseModes?.[caseName]) void this._probeDockerCaseModes(activeCase, menu); for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']) { const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`); if (!btn) continue; @@ -633,6 +640,42 @@ Object.assign(CodemanApp.prototype, { } }, + /** + * Ask the container which CLIs it actually has, and re-gate the menu once the + * answer lands. Cached per case for the page's lifetime: the menu re-opens + * often and the probe is a `docker exec` round trip. + * + * Best-effort by design — an unreachable daemon or a stopped container leaves + * the cache empty, which the caller reads as "unknown" and therefore does not + * gate. Hiding every mode because a probe failed would be worse than showing + * one that turns out to be missing, which the launch path already refuses with + * a specific message. + */ + async _probeDockerCaseModes(activeCase, menu) { + const name = activeCase?.name; + const container = activeCase?.docker?.container; + const hostId = activeCase?.docker?.hostId; + if (!name || !container || !hostId) return; + this._dockerCaseModes = this._dockerCaseModes || {}; + if (this._dockerModeProbeInFlight?.[name]) return; + this._dockerModeProbeInFlight = this._dockerModeProbeInFlight || {}; + this._dockerModeProbeInFlight[name] = true; + try { + const probe = await this._apiJson('/api/docker-cases/adopt-preflight', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ hostId, container }), + }); + if (probe?.ok && Array.isArray(probe.availableModes)) { + this._dockerCaseModes[name] = probe.availableModes; + // Only repaint while the menu the user opened is still on screen. + if (menu?.classList.contains('active')) this._refreshRunModeAvailability(menu); + } + } finally { + delete this._dockerModeProbeInFlight[name]; + } + }, + async _loadRunModeHistory() { const container = document.getElementById('runModeHistory'); if (!container) return; From 3685ad85bc7a8dd97c8b7bfe53b9eacca7875847 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 23:31:28 -0700 Subject: [PATCH 10/26] fix(docker): stop requiring the CLI on the host for a container session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Attaching a container, picking claude and hitting Run gave one line — `execvp(3) failed.: No such file or directory` — and the run-mode menu offered every mode. Three separate defects, found on a real deployment. TmuxManager.createSession resolved the CLI directory without distinguishing a docker session, so a host with no claude threw, the catch fell back to a direct PTY, and that PTY exec'd the CLI on the HOST. The failure surfaced as a bare execvp error naming nothing. A docker session runs its CLI inside the container; the host does not need it. All eight modes now sit behind a cliRunsInContainer guard, and whether the container has the CLI is settled by the adoption preflight or the image gate before launch. The running check used a bare double quote and command substitution. The whole chain is embedded in an outer `bash -c "…"`, so the unescaped quote closed that string early and the remainder was re-tokenized. It is now a `grep -qx` pipeline using only the single-quote form every other line in the builder already uses. Claude Code refuses --dangerously-skip-permissions as root. Our base image runs a non-root user, so an owned container never hit this; an adopted container's user belongs to its owner and is frequently root, and keeping the flag killed the pane with a message visible only inside the container. The preflight now reports runsAsRoot and the launch chain drops the flag for it. The menu also showed every mode because the container CLI probe only started when the menu opened. It is warmed when the case is selected instead. --- src/docker-hosts.ts | 18 ++++++++-- src/tmux-manager.ts | 38 +++++++++++++------- src/types/session.ts | 17 +++++---- src/web/public/session-ui.js | 7 ++++ src/web/routes/session-routes.ts | 3 ++ test/docker-adopted-container.test.ts | 52 ++++++++++++++++++++++++++- 6 files changed, 110 insertions(+), 25 deletions(-) diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts index d9d2de1b..a6ce66ad 100644 --- a/src/docker-hosts.ts +++ b/src/docker-hosts.ts @@ -160,11 +160,16 @@ export function dockerContainerName(caseName: string): string { } /** Default pane command per CLI mode (mirror of defaultRemoteCommandForMode). */ -export function defaultDockerCommandForMode(mode: SessionMode): string { +export function defaultDockerCommandForMode(mode: SessionMode, runsAsRoot = false): string { const commands: Record = { shell: 'exec bash -l', - // Mirror the LOCAL claude default so the in-container agent runs non-interactively. - claude: 'exec claude --dangerously-skip-permissions', + // Mirror the LOCAL claude default so the in-container agent runs + // non-interactively — EXCEPT as root, where Claude Code refuses the flag + // outright ("cannot be used with root/sudo privileges"). Our base image runs + // a non-root user so an owned container never hits this; an adopted + // container's user belongs to its owner and is frequently root, and keeping + // the flag there kills the pane with a message only visible inside it. + claude: runsAsRoot ? 'exec claude' : 'exec claude --dangerously-skip-permissions', opencode: 'exec opencode', codex: 'exec codex', gemini: 'exec gemini', @@ -1056,6 +1061,8 @@ export interface AdoptedContainerProbe { availableModes?: SessionMode[]; /** Whether the requested working directory exists INSIDE the container. */ workdirExists?: boolean; + /** Whether the container's exec user is root (uid 0). */ + runsAsRoot?: boolean; error?: string; } @@ -1179,6 +1186,10 @@ export async function probeAdoptableContainer( // --workdir ` fails with an OCI chdir error the pane surfaces as a bare // "execvp failed", so it is resolved here into an actionable message. if (containerWorkdir) steps.push(`[ -d ${shellescape(containerWorkdir)} ] && echo __workdir__`); + // Claude Code REFUSES --dangerously-skip-permissions as root. Our own base + // image runs a non-root user so an owned container never hits it; an adopted + // container's user belongs to its owner and is frequently root. + steps.push(`[ "$(id -u)" = 0 ] && echo __root__`); const script = `${steps.join('; ')}; exit 0`; try { const { stdout } = await execFileAsync( @@ -1220,6 +1231,7 @@ export async function probeAdoptableContainer( tmuxPath: 'tmux', availableModes: modes.filter((m) => m === 'shell' || found.has(binaryFor(m))), workdirExists, + runsAsRoot: found.has('__root__'), }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); diff --git a/src/tmux-manager.ts b/src/tmux-manager.ts index 3e0c96cb..f177d35a 100644 --- a/src/tmux-manager.ts +++ b/src/tmux-manager.ts @@ -1290,7 +1290,8 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string { const dkrName = dockerTmuxSessionName(sessionId); const sid = sessionId.slice(0, 8); - let modeCommand = docker.commands?.[mode as DockerCommandMode] || defaultDockerCommandForMode(mode); + let modeCommand = + docker.commands?.[mode as DockerCommandMode] || defaultDockerCommandForMode(mode, !!docker.runsAsRoot); if (mode === 'claude') { modeCommand = claudeDockerPaneCommand(modeCommand, sessionId, resumeSessionId); } else if (resumeSessionId) { @@ -1327,10 +1328,10 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string { const startFailMsg = shellescape(`Codeman: container ${docker.containerName} failed to start (docker daemon down?)`); const notFoundMsg = shellescape( - `Codeman: container ${docker.containerName} not found. Adopted containers are never created by Codeman — start it yourself, then reopen this session.` + `Codeman: container ${docker.containerName} not found. Adopted containers are never created by Codeman - start it yourself, then reopen this session.` ); const notRunningMsg = shellescape( - `Codeman: container ${docker.containerName} is not running. Codeman never starts a container it does not own — start it yourself, then reopen this session.` + `Codeman: container ${docker.containerName} is not running. Codeman never starts a container it does not own - start it yourself, then reopen this session.` ); const imageCheck = adopted @@ -1340,8 +1341,13 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string { const ensure = adopted ? `${base} inspect ${name} >/dev/null 2>&1 || { echo ${notFoundMsg}; exit 1; }` : `${base} inspect ${name} >/dev/null 2>&1 || ${base} ${createArgs}`; + // ⚠️ No double quotes and no `$(…)` here. This whole chain is embedded in an + // outer `bash -c "…"`, so an unescaped `"` closes that string early, the rest + // is re-tokenized, and tmux fails to exec with a bare `execvp(3) failed`. A + // `grep -qx` pipeline reads the same answer using only the single-quoted form + // every other line in this builder already uses. const start = adopted - ? `[ "$(${base} inspect -f '{{.State.Running}}' ${name} 2>/dev/null)" = true ] || { echo ${notRunningMsg}; exit 1; }` + ? `${base} inspect -f ${shellescape('{{.State.Running}}')} ${name} 2>/dev/null | grep -qx true || { echo ${notRunningMsg}; exit 1; }` : `${base} start ${name} >/dev/null 2>&1 || { echo ${startFailMsg}; exit 1; }`; // Seed writable credential config from read-only host mounts ONCE per container // (guarded by [ -e ] so reconnects never clobber in-container config; `cp -a` for @@ -2115,29 +2121,37 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer { // from the resolvers (formatCliNotFoundMessage) so the error names WHERE it // looked — server PATH, login shell, checked directories — instead of just // asserting the CLI is missing (the classic systemd/launchd PATH trap). + // + // ⚠️ A DOCKER session runs its CLI INSIDE the container, so the host does not + // need it at all. Demanding it here threw for a host without the binary, the + // catch fell back to a direct PTY, and that PTY tried to exec the CLI on the + // HOST — surfacing as a bare `execvp(3) failed: No such file or directory` + // with nothing pointing at the real cause. The container's own CLIs are + // verified by the adoption preflight / image gate before launch instead. const { pathExport, dir: cliDir } = this.buildPathExport(mode); - if (mode === 'claude' && !cliDir) { + const cliRunsInContainer = !!docker; + if (!cliRunsInContainer && mode === 'claude' && !cliDir) { throw new Error(getClaudeNotFoundMessage()); } - if (mode === 'opencode' && !cliDir) { + if (!cliRunsInContainer && mode === 'opencode' && !cliDir) { throw new Error(getOpenCodeNotFoundMessage()); } - if (mode === 'codex' && !cliDir) { + if (!cliRunsInContainer && mode === 'codex' && !cliDir) { throw new Error(getCodexNotFoundMessage()); } - if (mode === 'gemini' && !cliDir) { + if (!cliRunsInContainer && mode === 'gemini' && !cliDir) { throw new Error(getGeminiNotFoundMessage()); } - if (mode === 'antigravity' && !cliDir) { + if (!cliRunsInContainer && mode === 'antigravity' && !cliDir) { throw new Error(getAntigravityNotFoundMessage()); } - if (mode === 'pi' && !cliDir) { + if (!cliRunsInContainer && mode === 'pi' && !cliDir) { throw new Error(getPiNotFoundMessage()); } - if (mode === 'deepseek' && !cliDir) { + if (!cliRunsInContainer && mode === 'deepseek' && !cliDir) { throw new Error(getDeepSeekNotFoundMessage()); } - if (mode === 'grok' && !cliDir) { + if (!cliRunsInContainer && mode === 'grok' && !cliDir) { throw new Error(getGrokNotFoundMessage()); } diff --git a/src/types/session.ts b/src/types/session.ts index 21e117b9..d3fe4565 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -47,15 +47,7 @@ export type ClaudeMode = 'dangerously-skip-permissions' | 'auto' | 'normal' | 'a /** Session mode: which CLI backend a session runs */ export type SessionMode = - | 'claude' - | 'shell' - | 'opencode' - | 'codex' - | 'gemini' - | 'antigravity' - | 'pi' - | 'grok' - | 'deepseek'; + 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek'; export type RemoteCommandMode = Extract< SessionMode, @@ -302,6 +294,13 @@ export interface SessionDocker { extraExecArgs?: string[]; /** Stable hash of the drift-relevant create args (recreate-on-drift detection). */ configHash?: string; + /** + * Whether the container's exec user is root. Claude Code REFUSES + * `--dangerously-skip-permissions` as root, and an adopted container's user + * belongs to its owner, so the flag is omitted rather than letting the pane + * die with a message only visible inside the container. + */ + runsAsRoot?: boolean; /** * Mirror of `DockerCase.owned`, flattened onto the live session so every * lifecycle decision (launch chain, drift, stop, remove) can see it without diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index ebb9eec1..dc4503bd 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -187,6 +187,13 @@ Object.assign(CodemanApp.prototype, { this.closeCasePicker(); this.updateDirDisplayForCase(select.value); this.updateMobileCaseLabel(select.value); + // Warm the container's CLI list HERE rather than when the run menu opens. + // The probe is a `docker exec` round trip, so gating it on the menu meant the + // menu painted every mode first and only narrowed a moment later — which + // reads as "it shows all of them" and lets a mode be picked that the + // container does not have. + const picked = (this.cases || []).find((c) => c.name === select.value); + if (picked?.location === 'docker') void this._probeDockerCaseModes(picked, null); if (save) { this.saveLastUsedCase(select.value); } diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index 36ccea31..3fc80c94 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -2968,6 +2968,9 @@ export function registerSessionRoutes( if (!probe.ok) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not usable'); } + // The probe already exec'd into the container; carry its facts onto the + // live session so the launch chain does not have to re-ask. + sessionDocker.runsAsRoot = probe.runsAsRoot; if (mode !== 'shell' && !probe.availableModes?.includes(mode)) { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, diff --git a/test/docker-adopted-container.test.ts b/test/docker-adopted-container.test.ts index 1c14463c..2d9c6c1b 100644 --- a/test/docker-adopted-container.test.ts +++ b/test/docker-adopted-container.test.ts @@ -12,6 +12,7 @@ import { describe, it, expect } from 'vitest'; import { readFileSync } from 'node:fs'; import { + defaultDockerCommandForMode, toSessionDocker, isAdoptedContainer, removeDockerContainer, @@ -113,6 +114,18 @@ describe('adopted container: the launch chain never mutates lifecycle', () => { expect(adopted).toMatch(/not running.*never starts a container it does not own/i); }); + it('uses no double quote and no command substitution in the launch chain', () => { + // The whole chain is embedded in an outer `bash -c "…"`. An unescaped `"` + // closes that string early, the remainder is re-tokenized, and tmux fails to + // exec with a bare `execvp(3) failed: No such file or directory` — no hint + // that the command was ever malformed. `$(…)` is banned with it because it + // is then evaluated by the wrong shell at the wrong time. + expect(adopted).not.toContain('"'); + expect(adopted).not.toContain('$('); + // Every other line already quotes with the single-quote helper. + expect(adopted).toContain("grep -qx true"); + }); + it('skips the base-image gate, which describes an image adoption never uses', () => { expect(owned).toContain('image inspect'); expect(adopted).not.toContain('image inspect'); @@ -129,6 +142,43 @@ describe('adopted container: the launch chain never mutates lifecycle', () => { }); }); +describe('adopted container: claude as root', () => { + it('drops --dangerously-skip-permissions when the container runs as root', () => { + // Claude Code refuses the flag as root ("cannot be used with root/sudo + // privileges"), so keeping it kills the pane with a message only visible + // inside the container. Our base image runs a non-root user, which is why an + // owned container never hit this. + expect(defaultDockerCommandForMode('claude', true)).toBe('exec claude'); + expect(defaultDockerCommandForMode('claude', false)).toContain('--dangerously-skip-permissions'); + expect(defaultDockerCommandForMode('claude')).toContain('--dangerously-skip-permissions'); + }); + + it('leaves every other mode unchanged as root', () => { + for (const mode of ['codex', 'shell', 'pi'] as const) { + expect(defaultDockerCommandForMode(mode, true)).toBe(defaultDockerCommandForMode(mode, false)); + } + }); +}); + +describe('adopted container: the host is not required to have the CLI', () => { + const src = readFileSync(new URL('../src/tmux-manager.ts', import.meta.url), 'utf8'); + + it('skips every host CLI requirement for a docker session', () => { + // A docker session runs its CLI inside the container. Demanding it on the + // host threw, the catch fell back to a direct PTY, and that PTY tried to + // exec the CLI on the HOST — surfacing as a bare `execvp(3) failed` with + // nothing naming the real cause. + const guarded = src.match(/!cliRunsInContainer && mode === '/g) || []; + const unguarded = src.match(/\n if \(mode === '[a-z]+' && !cliDir\)/g) || []; + expect(guarded.length).toBeGreaterThanOrEqual(7); + expect(unguarded).toHaveLength(0); + }); + + it('derives the flag from the docker metadata the session already carries', () => { + expect(src).toContain('const cliRunsInContainer = !!docker;'); + }); +}); + describe('adopted container: mutating verbs fail closed at the builder', () => { const docker = toSessionDocker(HOST, caseFor(false)); @@ -202,7 +252,7 @@ describe('adopted container: run modes come from the CONTAINER, not the host', ( const refreshFn = (src) => { const start = src.indexOf('_refreshRunModeAvailability(menu) {'); expect(start).toBeGreaterThan(-1); - return src.slice(start, start + 1600); + return src.slice(start, start + 2000); }; it('gates a docker case on availableModes instead of host CLI probes', () => { From 23ab2e77fd01394a47b9c2370042cf2d46d9a3c8 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 23:31:28 -0700 Subject: [PATCH 11/26] fix(files): give the picker a root when the server runs as root MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Link Existing's Browse did nothing: GET /api/filesystem/browse answered 403 "No filesystem browse roots are available". Two rules were fighting. /root is a default blocked tree in the attachment guard, and Codeman running as root — containers, plenty of servers — makes homedir() exactly /root, so the picker's own allowlisted Home root was blocked; the other candidates live under it or do not exist. The root list came out empty and there was nothing the user could open. The blocked trees exist to keep ~/.ssh and friends out of reach, not to seal off the user's own home. Only trees that would swallow a configured root whole are dropped now: /root goes when Home is it (or sits inside it), /etc holds no configured root and is untouched. Secrets stay protected — isSensitivePath independently matches .ssh/, .env and credentials* at any depth, and it is what the directory probe asks about. ⚠️ Navigation must reuse the same narrowed list the roots were chosen with. Handing the raw trees downstream admits a root and then refuses every path inside it, which reads as a picker that opens and does nothing. --- src/web/routes/file-routes.ts | 53 ++++++++++++++++++++++++++++-- test/file-picker-root-home.test.ts | 53 ++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 test/file-picker-root-home.test.ts diff --git a/src/web/routes/file-routes.ts b/src/web/routes/file-routes.ts index 20a567f3..adffc9dd 100644 --- a/src/web/routes/file-routes.ts +++ b/src/web/routes/file-routes.ts @@ -38,7 +38,7 @@ import { import { generateFirstPageThumbnail } from '../../document-thumbnailer.js'; import { getOfficePreviewPdfPath, getPreviewPdfDownloadName } from '../../document-preview-cache.js'; import { sanitizeAttachmentHistoryItem } from '../../session-attachment-history.js'; -import { isBlockedAttachmentPath, loadAttachmentGuardConfig } from '../../config/attachment-guard.js'; +import { isBlockedAttachmentPath, isUnderTree, loadAttachmentGuardConfig } from '../../config/attachment-guard.js'; import { isMultiUserMode, userSpacePath } from '../../config/multiuser.js'; import { CASES_DIR, @@ -425,6 +425,40 @@ function getFilesystemPreviewKind(fileName: string): FilesystemPreviewKind | und return undefined; } +/** + * Blocked trees, minus any tree that would swallow a configured picker root + * whole. + * + * `/root` is a default blocked tree, and Codeman running as root (containers, + * plenty of servers) makes `homedir()` exactly `/root` — so the picker's own + * allowlisted Home root was blocked by the attachment guard, every other + * candidate lives under it or does not exist, and the endpoint answered 403 + * "No filesystem browse roots are available" with no root the user could reach. + * + * Dropping the tree does NOT expose secrets: `isSensitivePath` independently + * matches `.ssh/`, `.env`, `credentials*` and friends at any depth, and it is + * what the directory probe below asks about. Trees with no configured root + * beneath them (`/etc`) are untouched. + */ +function pickerBlockedTrees(blockedTrees: readonly string[], roots: readonly string[]): readonly string[] { + if (roots.length === 0) return blockedTrees; + return blockedTrees.filter((tree) => !roots.some((root) => isUnderTree(root, tree))); +} + +/** Resolve candidate roots to realpaths, dropping the ones that do not exist. */ +function resolveCandidateRootPaths(candidates: ReadonlyArray<{ path: string }>): string[] { + const out: string[] = []; + for (const candidate of candidates) { + if (!isAbsolute(candidate.path)) continue; + try { + out.push(realpathSync(candidate.path)); + } catch { + // Optional roots (for example /mnt/d on non-WSL hosts) are omitted. + } + } + return out; +} + function isBlockedPickerPath(path: string, blockedTrees: readonly string[], directory = false): boolean { if (isBlockedAttachmentPath(path, blockedTrees)) return true; // The shared sensitive-path matcher describes file locations such as @@ -491,13 +525,14 @@ async function resolveFilesystemPickerRoots( } const guard = await loadAttachmentGuardConfig(); + const trees = pickerBlockedTrees(guard.blockedTrees, resolveCandidateRootPaths(candidates)); const roots: FilesystemBrowseRoot[] = []; const seen = new Set(); for (const candidate of candidates) { if (!isAbsolute(candidate.path)) continue; try { const resolved = realpathSync(candidate.path); - if (seen.has(resolved) || isBlockedPickerPath(resolved, guard.blockedTrees, true)) continue; + if (seen.has(resolved) || isBlockedPickerPath(resolved, trees, true)) continue; const stat = await fs.stat(resolved); if (!stat.isDirectory()) continue; seen.add(resolved); @@ -556,7 +591,19 @@ async function resolveFilesystemPickerPath( } const guard = await loadAttachmentGuardConfig(); - return { candidatePath, resolvedPath, roots, matchingRoot, blockedTrees: guard.blockedTrees }; + // Navigation must use the SAME narrowed list the roots were selected with. + // Handing the raw trees down here would admit a root and then refuse every + // path inside it, which reads as a picker that opens and then does nothing. + return { + candidatePath, + resolvedPath, + roots, + matchingRoot, + blockedTrees: pickerBlockedTrees( + guard.blockedTrees, + roots.map((root) => root.path) + ), + }; } function appendDownloadFlag(url: string): string { diff --git a/test/file-picker-root-home.test.ts b/test/file-picker-root-home.test.ts new file mode 100644 index 00000000..c726237f --- /dev/null +++ b/test/file-picker-root-home.test.ts @@ -0,0 +1,53 @@ +/** + * @fileoverview The picker must offer a root when Codeman runs as root. + * + * `/root` is a DEFAULT blocked tree in the attachment guard, and Codeman running + * as root — containers, plenty of servers — makes `homedir()` exactly `/root`. + * The picker's own allowlisted Home root was therefore blocked by the guard, + * every other candidate lives under it or does not exist, and the endpoint + * answered 403 "No filesystem browse roots are available" with nothing the user + * could open. The fix drops only the trees that would swallow a configured root + * whole; `isSensitivePath` still guards what is inside. + */ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { isBlockedAttachmentPath, isUnderTree } from '../src/config/attachment-guard.js'; + +const TREES = ['/root', '/etc']; + +/** Mirror of pickerBlockedTrees in file-routes.ts. */ +const narrow = (trees: readonly string[], roots: readonly string[]) => + roots.length === 0 ? trees : trees.filter((t) => !roots.some((r) => isUnderTree(r, t))); + +describe('file picker roots when the server runs as root', () => { + it('drops the tree that would swallow the configured Home root', () => { + expect(narrow(TREES, ['/root'])).toEqual(['/etc']); + }); + + it('keeps trees that hold no configured root', () => { + expect(narrow(TREES, ['/home/alice'])).toEqual(['/root', '/etc']); + expect(narrow(TREES, [])).toEqual(['/root', '/etc']); + }); + + it('also frees a root nested under the blocked tree', () => { + // ~/codeman-cases is /root/codeman-cases when running as root. + expect(narrow(TREES, ['/root/codeman-cases'])).toEqual(['/etc']); + }); + + it('still refuses secrets inside the freed tree', () => { + const trees = narrow(TREES, ['/root']); + for (const p of ['/root/.ssh/id_rsa', '/root/.aws/credentials', '/root/app/.env']) { + expect(isBlockedAttachmentPath(p, trees)).toBe(true); + } + // …while ordinary files under it become reachable, which is the point. + expect(isBlockedAttachmentPath('/root/projects/readme.md', trees)).toBe(false); + }); + + it('navigation reuses the same narrowed list the roots were chosen with', () => { + // Handing the raw trees to navigation would admit a root and then refuse + // every path inside it — a picker that opens and then does nothing. + const src = readFileSync(new URL('../src/web/routes/file-routes.ts', import.meta.url), 'utf8'); + expect(src.match(/pickerBlockedTrees\(/g)?.length).toBeGreaterThanOrEqual(3); + expect(src).not.toMatch(/blockedTrees:\s*guard\.blockedTrees/); + }); +}); From 5452ad5c5ae314bec730a21688f3b74a443cdef4 Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 23:31:28 -0700 Subject: [PATCH 12/26] feat(docker): add a folder picker to both path fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both paths in the adoption form had to be typed. Each gets a Browse button using the same path-input-group markup Link Existing uses, so the two look and behave alike. What they can browse differs, and that is the point. The host workspace path reuses the existing host picker. The container workdir cannot: an adopted container has nothing mounted at a matching host path, so a host listing would be a different filesystem — and getting this field wrong is the source of the opaque OCI chdir error at launch, which makes it the field that most needs to be clickable. Adds a read-only POST /api/docker-cases/browse: one `ls` through docker exec, no writes, no lifecycle, path shell-escaped like every other value. `ls -Ap` marks directories with a trailing slash and keeps names with spaces intact. PathPicker takes an optional fetchListing source rather than being forked: the container variant only swaps where the rows come from, and reuses the rendering, navigation, Up and Choose/Select unchanged. --- src/docker-hosts.ts | 54 ++++++++++++++++++++++++++ src/web/public/index.html | 10 ++++- src/web/public/keyboard-accessory.js | 10 +++-- src/web/public/session-ui.js | 56 +++++++++++++++++++++++++++ src/web/routes/case-routes.ts | 26 ++++++++++++- src/web/schemas.ts | 16 ++++++++ test/docker-adopted-container.test.ts | 34 ++++++++++++++++ 7 files changed, 200 insertions(+), 6 deletions(-) diff --git a/src/docker-hosts.ts b/src/docker-hosts.ts index a6ce66ad..e2801b55 100644 --- a/src/docker-hosts.ts +++ b/src/docker-hosts.ts @@ -1239,6 +1239,60 @@ export async function probeAdoptableContainer( } } +/** One directory listing from INSIDE a container, shaped like the host picker's. */ +export interface DockerBrowseResult { + path: string; + parent: string | null; + entries: Array<{ name: string; path: string; type: 'directory' | 'file' }>; + error?: string; +} + +/** + * List a directory INSIDE a container, for the adoption form's container-workdir + * picker. The host filesystem picker cannot serve this: the path lives in the + * container, and for an adopted container nothing is mounted at a matching host + * location, so the user would otherwise be typing a path blind. + * + * Read-only: one `ls` through `docker exec`, no writes, no lifecycle. The path + * is shell-escaped like every other value this module interpolates, and output + * is parsed as NUL-free lines with a leading type marker so a filename with + * spaces survives. + */ +export async function browseInContainer( + docker: Pick, + path: string +): Promise { + const target = path && path.startsWith('/') ? path : '/'; + const parent = target === '/' ? null : target.replace(/\/+$/, '').split('/').slice(0, -1).join('/') || '/'; + if (IS_TEST_MODE) return { path: target, parent, entries: [] }; + const argv = dockerEngineArgv(docker); + // `-p` marks directories with a trailing slash; `-A` shows dotfiles but not + // the . and .. entries the picker navigates with its own Up control. + const script = `cd ${shellescape(target)} 2>/dev/null && ls -Ap 2>/dev/null || echo __ERR__`; + try { + const { stdout } = await execFileAsync( + argv[0], + [...argv.slice(1), 'exec', docker.containerName, 'sh', '-lc', script], + { timeout: DOCKER_PROBE_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 } + ); + if (stdout.includes('__ERR__')) return { path: target, parent, entries: [], error: 'Not a readable directory' }; + const base = target.endsWith('/') ? target : `${target}/`; + const entries = stdout + .split('\n') + .map((line) => line.trim()) + .filter(Boolean) + .map((name) => { + const isDir = name.endsWith('/'); + const clean = isDir ? name.slice(0, -1) : name; + return { name: clean, path: `${base}${clean}`, type: (isDir ? 'directory' : 'file') as 'directory' | 'file' }; + }) + .sort((a, b) => Number(b.type === 'directory') - Number(a.type === 'directory') || a.name.localeCompare(b.name)); + return { path: target, parent, entries }; + } catch (err) { + return { path: target, parent, entries: [], error: err instanceof Error ? err.message : String(err) }; + } +} + /** * Resolve the host's IP on the default docker bridge (the address a container * reaches as `host.docker.internal`), so the server can bind a hooks-only listener diff --git a/src/web/public/index.html b/src/web/public/index.html index f83a17d9..6df870b3 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2844,7 +2844,10 @@
- +
+ + +
A path that already exists inside the container. Adoption mounts nothing, so this need not match the host workspace path.
@@ -2854,7 +2857,10 @@
- +
+ + +
Absolute HOST directory, bind-mounted into the container. Codeman scaffolds CLAUDE.md + hooks into it.
diff --git a/src/web/public/keyboard-accessory.js b/src/web/public/keyboard-accessory.js index 35b67c3e..7ec9a890 100644 --- a/src/web/public/keyboard-accessory.js +++ b/src/web/public/keyboard-accessory.js @@ -185,9 +185,13 @@ const PathPicker = { if (this._options.sessionId) params.set('sessionId', this._options.sessionId); if (this._showHidden) params.set('showHidden', 'true'); try { - const response = await fetch(`/api/filesystem/browse?${params.toString()}`); - const result = await response.json(); - if (!response.ok || !result.success) throw new Error(result.error || 'Failed to browse this folder'); + // A caller may supply its own source (the container-workdir picker browses + // INSIDE a container, which the host filesystem endpoint cannot answer). + // It returns the same shape, so everything below is unchanged. + const result = this._options.fetchListing + ? await this._options.fetchListing(path) + : await (await fetch(`/api/filesystem/browse?${params.toString()}`)).json(); + if (!result?.success) throw new Error(result?.error || 'Failed to browse this folder'); if (!this.overlay || loadSequence !== this._loadSequence) return; this.render(result.data); } catch (error) { diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index dc4503bd..15109b16 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -2895,6 +2895,62 @@ Object.assign(CodemanApp.prototype, { }); }, + /** HOST workspace directory — the same picker Link Existing uses. */ + openDockerWorkspacePathPicker() { + const pathInput = document.getElementById('dockerWorkspacePath'); + PathPicker.open({ + title: 'Select Host Workspace Folder', + initialPath: pathInput.value.trim(), + directoriesOnly: true, + onSelect: (path) => { + pathInput.value = path; + const nameInput = document.getElementById('dockerCaseName'); + if (nameInput && !nameInput.value.trim()) { + const folder = path.split('/').filter(Boolean).pop() || ''; + if (/^[a-zA-Z0-9_-]+$/.test(folder)) nameInput.value = folder; + } + }, + }); + }, + + /** + * Container workdir. Browses INSIDE the container, because for an adopted + * container nothing is mounted at a matching host path — the host picker would + * be listing a different filesystem, and typing this field blind is exactly + * what makes the launch fail with an OCI chdir error. + */ + openDockerWorkdirPicker() { + const pathInput = document.getElementById('dockerAdoptWorkdir'); + const container = document.getElementById('dockerContainerName')?.value.trim(); + const hostId = document.getElementById('dockerHostId')?.value.trim() || 'local'; + if (!container) { + this.showToast('Enter the container name first', 'error'); + return; + } + PathPicker.open({ + title: `Select Folder Inside ${container}`, + initialPath: pathInput.value.trim() || '/', + directoriesOnly: true, + fetchListing: async (path) => { + const data = await this._apiJson('/api/docker-cases/browse', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ hostId, container, path: path || '/' }), + }); + if (!data) return { success: false, error: `Could not read ${container}. Is it running?` }; + if (data.error) return { success: false, error: data.error }; + // Shape it like the host endpoint: one root, so Up/Location behave. + return { + success: true, + data: { ...data, root: '/', roots: [{ label: container, path: '/' }], truncated: false }, + }; + }, + onSelect: (path) => { + pathInput.value = path; + }, + }); + }, + async linkRemoteCase() { const name = document.getElementById('remoteCaseName').value.trim(); const remotePath = document.getElementById('remoteCasePath').value.trim(); diff --git a/src/web/routes/case-routes.ts b/src/web/routes/case-routes.ts index 11ac46e7..5aa4a2f0 100644 --- a/src/web/routes/case-routes.ts +++ b/src/web/routes/case-routes.ts @@ -26,6 +26,7 @@ import { DockerCaseLinkSchema, DockerCaseAdoptSchema, DockerAdoptPreflightSchema, + DockerBrowseSchema, DockerHostSchema, DockerExportSchema, DockerImportSchema, @@ -70,6 +71,7 @@ import { dockerDisplayPath, probeAdoptableContainer, listDockerContainers, + browseInContainer, DOCKER_ADOPT_PROBE_MODES, readDockerCases, readDockerHosts, @@ -78,7 +80,7 @@ import { writeDockerCases, writeDockerHosts, } from '../../docker-hosts.js'; -import type { AdoptedContainerProbe, DockerContainerInfo } from '../../docker-hosts.js'; +import type { AdoptedContainerProbe, DockerBrowseResult, DockerContainerInfo } from '../../docker-hosts.js'; import { buildDockerRemoveCommand } from '../../tmux-manager.js'; import { checkRemoteTmuxAvailable, @@ -895,6 +897,28 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config } ); + /** + * Browse a directory INSIDE a container, for the adoption form's + * container-workdir picker. The host picker cannot answer this: for an adopted + * container nothing is mounted at a matching host path, so the field would + * otherwise be typed blind. Read-only — one `ls` through `docker exec`. + */ + app.post('/api/docker-cases/browse', async (req): Promise> => { + const body = parseBody(DockerBrowseSchema, req.body); + const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId); + if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found'); + const result = await browseInContainer( + { + engine: host.engine ?? 'docker', + context: host.context, + daemonHost: host.daemonHost, + containerName: body.container, + }, + body.path || '/' + ); + return { success: true, data: result }; + }); + app.post('/api/docker-cases/adopt-preflight', async (req): Promise> => { const body = parseBody(DockerAdoptPreflightSchema, req.body); const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId); diff --git a/src/web/schemas.ts b/src/web/schemas.ts index 65ef1395..ffffd388 100644 --- a/src/web/schemas.ts +++ b/src/web/schemas.ts @@ -844,6 +844,22 @@ export const DockerAdoptPreflightSchema = z.object({ .optional(), }); +/** Read-only directory listing inside a container (adoption workdir picker). */ +export const DockerBrowseSchema = z.object({ + hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'), + container: z + .string() + .min(2) + .max(128) + .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'), + path: z + .string() + .max(2000) + .regex(/^\//, 'Path must be absolute') + .regex(NO_SHELL_META, 'Invalid characters in path') + .optional(), +}); + export const DockerExportSchema = z.object({ mode: z.enum(['full', 'workspace']).optional(), }); diff --git a/test/docker-adopted-container.test.ts b/test/docker-adopted-container.test.ts index 2d9c6c1b..36f86780 100644 --- a/test/docker-adopted-container.test.ts +++ b/test/docker-adopted-container.test.ts @@ -272,6 +272,40 @@ describe('adopted container: run modes come from the CONTAINER, not the host', ( }); }); +describe('adopted container: both path fields get a folder picker', () => { + const html = readFileSync(new URL('../src/web/public/index.html', import.meta.url), 'utf8'); + const ui = readFileSync(new URL('../src/web/public/session-ui.js', import.meta.url), 'utf8'); + const picker = readFileSync(new URL('../src/web/public/keyboard-accessory.js', import.meta.url), 'utf8'); + + it('wires a Browse button to each of the two paths', () => { + expect(html).toContain('app.openDockerWorkspacePathPicker()'); + expect(html).toContain('app.openDockerWorkdirPicker()'); + // Same markup Link Existing uses, so the two look and behave alike. + expect(html.match(/path-input-browse/g)?.length).toBeGreaterThanOrEqual(3); + }); + + it('browses the CONTAINER for the container workdir, not the host', () => { + // For an adopted container nothing is mounted at a matching host path, so a + // host listing would be a different filesystem — and typing this field blind + // is what makes the launch fail with an OCI chdir error. + const fn = ui.slice(ui.indexOf('openDockerWorkdirPicker()'), ui.indexOf('async linkRemoteCase()')); + expect(fn).toContain('/api/docker-cases/browse'); + expect(fn).not.toContain('/api/filesystem/browse'); + expect(fn).toContain('fetchListing'); + }); + + it('keeps the host picker for the host workspace path', () => { + const fn = ui.slice(ui.indexOf('openDockerWorkspacePathPicker()'), ui.indexOf('openDockerWorkdirPicker()')); + expect(fn).toContain('PathPicker.open'); + expect(fn).not.toContain('fetchListing'); + }); + + it('reuses one PathPicker via an optional source rather than forking it', () => { + expect(picker).toContain('this._options.fetchListing'); + expect(picker).toContain('/api/filesystem/browse'); + }); +}); + describe('adopted container: drift is not evaluated', () => { it('reports no drift rather than demanding a recreate we may not perform', async () => { // An adopted container carries no codeman.confighash label, so a real From 8e5e207386f18c820679659466b58664a61c2a5f Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 23:31:28 -0700 Subject: [PATCH 13/26] fix(docker): send the probe body as an object, and explain an unreachable container MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The run menu still offered every mode for an attached container. The browser's actual request showed why: POST /api/docker-cases/adopt-preflight -> 400 {"error":"Invalid input: expected object, received string"} _api serializes `body` and sets Content-Type itself, and three call sites each passed an already-stringified body, so it was encoded twice and the server saw a JSON string where it expects an object. curl was fine throughout, so nothing in the server logs pointed at it. Also fixes the design defect underneath: a failed probe fell through to "do not gate", which silently offered every mode. When the container has been recreated, is stopped, or the engine is unreachable, the user sees claude, clicks it, and it can only fail — with the reason visible nowhere. A failed probe now hides every agent mode (Shell needs no CLI and stays) and shows the server's own reason at the top of the menu. Two static guards switched from a character window to brace matching. They sliced between two call sites, and _loadRunModeHistory's call appears above its definition, so the slice came out empty and the assertion verified nothing — the same trap twice in one file. --- src/types/session.ts | 10 ++++- src/web/public/session-ui.js | 52 +++++++++++++++++++++----- src/web/public/styles.css | 12 ++++++ src/web/routes/case-routes.ts | 4 +- src/web/routes/session-routes.ts | 15 +++++--- src/web/routes/system-routes.ts | 5 ++- test/docker-adopted-container.test.ts | 54 ++++++++++++++++++++++++++- 7 files changed, 131 insertions(+), 21 deletions(-) diff --git a/src/types/session.ts b/src/types/session.ts index d3fe4565..39910bfc 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -47,7 +47,15 @@ export type ClaudeMode = 'dangerously-skip-permissions' | 'auto' | 'normal' | 'a /** Session mode: which CLI backend a session runs */ export type SessionMode = - 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek'; + | 'claude' + | 'shell' + | 'opencode' + | 'codex' + | 'gemini' + | 'antigravity' + | 'pi' + | 'grok' + | 'deepseek'; export type RemoteCommandMode = Extract< SessionMode, diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index 15109b16..11fd15a0 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -498,14 +498,18 @@ Object.assign(CodemanApp.prototype, { ? this._dockerCaseModes?.[caseName] || activeCase.docker?.availableModes || null : null; if (isDocker && !this._dockerCaseModes?.[caseName]) void this._probeDockerCaseModes(activeCase, menu); + // An unreachable container hides every agent mode and explains why, instead + // of silently offering modes that cannot start. + const probeError = isDocker ? this._dockerCaseProbeError?.[caseName] : null; for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']) { const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`); if (!btn) continue; let available; - if (activeCase?.location === 'docker') available = containerModes ? containerModes.includes(mode) : true; + if (isDocker) available = probeError ? false : containerModes ? containerModes.includes(mode) : true; else available = this.isCliAvailable(mode); btn.style.display = available ? 'flex' : 'none'; } + this._renderRunModeNotice(menu, probeError); // DeepSeek is the one mode whose availability has two halves: `dsh` can be // perfectly installed while no pane-capable profile exists, because DeepSeek // ships no terminal front door. In that state the honest offer is "add one", @@ -647,6 +651,27 @@ Object.assign(CodemanApp.prototype, { } }, + /** + * One-line explanation at the top of the run menu. Only a container that could + * not be read produces one; everything else removes it, so a stale reason can + * never outlive the condition that caused it. + */ + _renderRunModeNotice(menu, message) { + if (!menu) return; + let el = menu.querySelector('.run-mode-notice'); + if (!message) { + el?.remove(); + return; + } + if (!el) { + el = document.createElement('div'); + el.className = 'run-mode-notice'; + menu.prepend(el); + } + // Server-supplied text: set it, never parse it as markup. + el.textContent = message; + }, + /** * Ask the container which CLIs it actually has, and re-gate the menu once the * answer lands. Cached per case for the page's lifetime: the menu re-opens @@ -668,16 +693,27 @@ Object.assign(CodemanApp.prototype, { this._dockerModeProbeInFlight = this._dockerModeProbeInFlight || {}; this._dockerModeProbeInFlight[name] = true; try { + // ⚠️ _api serializes `body` and sets Content-Type itself. Passing an + // already-stringified body double-encodes it and the server rejects a + // JSON string where it expects an object (400 INVALID_INPUT). const probe = await this._apiJson('/api/docker-cases/adopt-preflight', { method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ hostId, container }), + body: { hostId, container }, }); if (probe?.ok && Array.isArray(probe.availableModes)) { this._dockerCaseModes[name] = probe.availableModes; - // Only repaint while the menu the user opened is still on screen. - if (menu?.classList.contains('active')) this._refreshRunModeAvailability(menu); + delete this._dockerCaseProbeError?.[name]; + } else { + // A container that cannot be probed — recreated, stopped, engine down — + // must NOT fall through to "show everything". Offering claude on a + // container that is not running is a click that can only fail, with the + // reason visible nowhere. Record the reason and say it in the menu. + this._dockerCaseProbeError = this._dockerCaseProbeError || {}; + this._dockerCaseProbeError[name] = probe?.error || `Could not read container "${container}".`; + delete this._dockerCaseModes[name]; } + // Only repaint while the menu the user opened is still on screen. + if (menu?.classList.contains('active')) this._refreshRunModeAvailability(menu); } finally { delete this._dockerModeProbeInFlight[name]; } @@ -2934,8 +2970,7 @@ Object.assign(CodemanApp.prototype, { fetchListing: async (path) => { const data = await this._apiJson('/api/docker-cases/browse', { method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ hostId, container, path: path || '/' }), + body: { hostId, container, path: path || '/' }, }); if (!data) return { success: false, error: `Could not read ${container}. Is it running?` }; if (data.error) return { success: false, error: data.error }; @@ -3109,8 +3144,7 @@ Object.assign(CodemanApp.prototype, { // reason it failed, so the envelope is unwrapped by hand here. const probe = await this._apiJson('/api/docker-cases/adopt-preflight', { method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ hostId, container, ...(containerWorkdir ? { containerWorkdir } : {}) }), + body: { hostId, container, ...(containerWorkdir ? { containerWorkdir } : {}) }, }); if (!statusEl) return; if (!probe) { diff --git a/src/web/public/styles.css b/src/web/public/styles.css index 7ca4edc3..50912082 100644 --- a/src/web/public/styles.css +++ b/src/web/public/styles.css @@ -16608,6 +16608,18 @@ html[data-tab-orientation='vertical'] .home-sessions { panel stays exactly as it was until the checkbox is ticked. Rules carry `!important` because the adapter block above paints `.form-row` as a row card and `details.advanced-options` has its own display. */ +/* Run-menu notice: why a container case is offering no agent modes. Lives at the + top of the menu so the reason is where the missing entries would have been. */ +.run-mode-notice { + padding: 8px 12px; + margin: 0 0 4px; + font-size: 12px; + line-height: 1.45; + color: var(--text-muted, #9aa0a6); + border-bottom: 1px solid var(--border, #333); + white-space: normal; +} + #createCaseModal .docker-adopt-only { display: none !important; } diff --git a/src/web/routes/case-routes.ts b/src/web/routes/case-routes.ts index 5aa4a2f0..2024d994 100644 --- a/src/web/routes/case-routes.ts +++ b/src/web/routes/case-routes.ts @@ -1175,7 +1175,9 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config engine: result.manifest.engine, image: result.importedImage ?? result.manifest.image, network: (['bridge', 'none', 'custom'].includes(result.manifest.network) ? result.manifest.network : 'bridge') as - 'bridge' | 'none' | 'custom', + | 'bridge' + | 'none' + | 'custom', }; await writeDockerHosts( CODEMAN_CONFIG_DIR, diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index 3fc80c94..c50ddcb3 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -944,8 +944,9 @@ export function registerSessionRoutes( } } if (body.mode === 'antigravity') { - const { isAntigravityAvailable, getAntigravityNotFoundMessage } = - await import('../../utils/antigravity-cli-resolver.js'); + const { isAntigravityAvailable, getAntigravityNotFoundMessage } = await import( + '../../utils/antigravity-cli-resolver.js' + ); if (!isAntigravityAvailable()) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getAntigravityNotFoundMessage()); } @@ -3025,8 +3026,9 @@ export function registerSessionRoutes( // Check OpenCode availability if requested. Error text comes from the // resolver so it carries the resolution diagnostics; same for the modes below. if (mode === 'opencode') { - const { isOpenCodeAvailable, getOpenCodeNotFoundMessage } = - await import('../../utils/opencode-cli-resolver.js'); + const { isOpenCodeAvailable, getOpenCodeNotFoundMessage } = await import( + '../../utils/opencode-cli-resolver.js' + ); if (!isOpenCodeAvailable()) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getOpenCodeNotFoundMessage()); } @@ -3050,8 +3052,9 @@ export function registerSessionRoutes( // Check Antigravity availability if requested if (mode === 'antigravity') { - const { isAntigravityAvailable, getAntigravityNotFoundMessage } = - await import('../../utils/antigravity-cli-resolver.js'); + const { isAntigravityAvailable, getAntigravityNotFoundMessage } = await import( + '../../utils/antigravity-cli-resolver.js' + ); if (!isAntigravityAvailable()) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getAntigravityNotFoundMessage()); } diff --git a/src/web/routes/system-routes.ts b/src/web/routes/system-routes.ts index 4929e977..a23fb286 100644 --- a/src/web/routes/system-routes.ts +++ b/src/web/routes/system-routes.ts @@ -683,8 +683,9 @@ export function registerSystemRoutes( `Installing ${pkg} into profile "${profile}" failed: ${detail}` ); } - const { listDeepSeekProfiles, resolveDefaultDeepSeekProfile, isDeepSeekRunnable } = - await import('../../utils/deepseek-cli-resolver.js'); + const { listDeepSeekProfiles, resolveDefaultDeepSeekProfile, isDeepSeekRunnable } = await import( + '../../utils/deepseek-cli-resolver.js' + ); return { profile, package: pkg, diff --git a/test/docker-adopted-container.test.ts b/test/docker-adopted-container.test.ts index 36f86780..62d26cfd 100644 --- a/test/docker-adopted-container.test.ts +++ b/test/docker-adopted-container.test.ts @@ -123,7 +123,7 @@ describe('adopted container: the launch chain never mutates lifecycle', () => { expect(adopted).not.toContain('"'); expect(adopted).not.toContain('$('); // Every other line already quotes with the single-quote helper. - expect(adopted).toContain("grep -qx true"); + expect(adopted).toContain('grep -qx true'); }); it('skips the base-image gate, which describes an image adoption never uses', () => { @@ -142,6 +142,44 @@ describe('adopted container: the launch chain never mutates lifecycle', () => { }); }); +describe('adopted container: the probe request must reach the server', () => { + const ui = readFileSync(new URL('../src/web/public/session-ui.js', import.meta.url), 'utf8'); + const api = readFileSync(new URL('../src/web/public/api-client.js', import.meta.url), 'utf8'); + + it('never hands _apiJson an already-stringified body', () => { + // _api serializes `body` and sets Content-Type itself. Passing a string + // double-encodes it, the server sees a JSON string where it expects an + // object, and answers 400 INVALID_INPUT — which the caller reads as "the + // container could not be probed", so the menu silently showed every mode. + expect(api).toContain('fetchOpts.body = JSON.stringify(body)'); + const calls = [...ui.matchAll(/_apiJson\([^)]*\{[\s\S]{0,400}?\}\s*\)/g)].map((m) => m[0]); + expect(calls.length).toBeGreaterThan(0); + for (const call of calls) expect(call).not.toContain('body: JSON.stringify'); + }); + + it('hides every agent mode and says why when the container cannot be read', () => { + // Offering claude on a container that is not running is a click that can + // only fail, with the reason visible nowhere. + // Brace-matched, not a character window: slicing between two call sites + // silently yields '' when the second one appears ABOVE the first, and the + // assertion then passes over nothing. That has bitten this file twice. + const start = ui.indexOf('async _probeDockerCaseModes(activeCase, menu) {'); + expect(start).toBeGreaterThan(-1); + const open = ui.indexOf('{', start); + let depth = 0; + let fn = ''; + for (let i = open; i < ui.length; i++) { + if (ui[i] === '{') depth++; + else if (ui[i] === '}' && --depth === 0) { + fn = ui.slice(start, i + 1); + break; + } + } + expect(fn).toContain('_dockerCaseProbeError'); + expect(ui).toContain('_renderRunModeNotice'); + }); +}); + describe('adopted container: claude as root', () => { it('drops --dangerously-skip-permissions when the container runs as root', () => { // Claude Code refuses the flag as root ("cannot be used with root/sudo @@ -249,10 +287,22 @@ describe('adopted container: run modes come from the CONTAINER, not the host', ( /** Slice the method BODY. Anchored on the definition, not a call site: the * menu opener calls _loadRunModeHistory() ABOVE this definition, so slicing * between call sites silently yields an empty string and passes nothing. */ + /** + * The method BODY, delimited by brace depth rather than a character budget. + * A fixed window silently truncates the moment the method grows — which is + * exactly what happened twice: a comment added above the assertion pushed the + * asserted line past the cutoff and CI failed on a test that was still true. + */ const refreshFn = (src) => { const start = src.indexOf('_refreshRunModeAvailability(menu) {'); expect(start).toBeGreaterThan(-1); - return src.slice(start, start + 2000); + const open = src.indexOf('{', start); + let depth = 0; + for (let i = open; i < src.length; i++) { + if (src[i] === '{') depth++; + else if (src[i] === '}' && --depth === 0) return src.slice(start, i + 1); + } + throw new Error('unbalanced braces in _refreshRunModeAvailability'); }; it('gates a docker case on availableModes instead of host CLI probes', () => { From 47ee49128c1a2320b5c6ba3020cf893acbc76fff Mon Sep 17 00:00:00 2001 From: d fei Date: Sat, 29 Aug 2026 23:49:04 -0700 Subject: [PATCH 14/26] style: match the prettier version the lockfile pins MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Format check failed twice, on different files each time, because three prettier versions were in play: package.json says ^3.4.0, package-lock pins 3.8.3 (CI runs npm ci, so that is the one CI uses), and the local node_modules had 3.9.6. Files formatted with 3.9.6 were then "fixed" with 3.4.2, pushing session-routes and system-routes onto a third style — every version change moved the failure to a different set of files. Line-break placement in `await import` and a union type only; no logic changes. --- src/web/routes/session-routes.ts | 15 ++++++--------- src/web/routes/system-routes.ts | 5 ++--- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index c50ddcb3..3fc80c94 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -944,9 +944,8 @@ export function registerSessionRoutes( } } if (body.mode === 'antigravity') { - const { isAntigravityAvailable, getAntigravityNotFoundMessage } = await import( - '../../utils/antigravity-cli-resolver.js' - ); + const { isAntigravityAvailable, getAntigravityNotFoundMessage } = + await import('../../utils/antigravity-cli-resolver.js'); if (!isAntigravityAvailable()) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getAntigravityNotFoundMessage()); } @@ -3026,9 +3025,8 @@ export function registerSessionRoutes( // Check OpenCode availability if requested. Error text comes from the // resolver so it carries the resolution diagnostics; same for the modes below. if (mode === 'opencode') { - const { isOpenCodeAvailable, getOpenCodeNotFoundMessage } = await import( - '../../utils/opencode-cli-resolver.js' - ); + const { isOpenCodeAvailable, getOpenCodeNotFoundMessage } = + await import('../../utils/opencode-cli-resolver.js'); if (!isOpenCodeAvailable()) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getOpenCodeNotFoundMessage()); } @@ -3052,9 +3050,8 @@ export function registerSessionRoutes( // Check Antigravity availability if requested if (mode === 'antigravity') { - const { isAntigravityAvailable, getAntigravityNotFoundMessage } = await import( - '../../utils/antigravity-cli-resolver.js' - ); + const { isAntigravityAvailable, getAntigravityNotFoundMessage } = + await import('../../utils/antigravity-cli-resolver.js'); if (!isAntigravityAvailable()) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getAntigravityNotFoundMessage()); } diff --git a/src/web/routes/system-routes.ts b/src/web/routes/system-routes.ts index a23fb286..4929e977 100644 --- a/src/web/routes/system-routes.ts +++ b/src/web/routes/system-routes.ts @@ -683,9 +683,8 @@ export function registerSystemRoutes( `Installing ${pkg} into profile "${profile}" failed: ${detail}` ); } - const { listDeepSeekProfiles, resolveDefaultDeepSeekProfile, isDeepSeekRunnable } = await import( - '../../utils/deepseek-cli-resolver.js' - ); + const { listDeepSeekProfiles, resolveDefaultDeepSeekProfile, isDeepSeekRunnable } = + await import('../../utils/deepseek-cli-resolver.js'); return { profile, package: pkg, From 5969a1df96a0c6b1f7c9a60029729ece807287de Mon Sep 17 00:00:00 2001 From: shenlvkang-collab Date: Tue, 1 Sep 2026 12:29:02 +0800 Subject: [PATCH 15/26] fix(mobile): give the Add Case modal a reachable submit button MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mobile.css hides #createCaseModal's .set-foot below 860px, and that modal's header — unlike Settings' — carries no set-head-save. So on a phone the Create/Link button existed nowhere and the modal could not be submitted at all. Adds the header button and drives both together through switchCaseModalTab() and submitCaseModal(), so whichever one is pressed the other shows the same pending state and is equally unclickable. Following the Settings pattern also means Add Case picks up the existing .set-head-actions:has(.set-head-save) tray and .set-head-save sizing with no new CSS; the mobile.css comment that still listed Add Case as a lone-× sheet is corrected to match. --- .changeset/fix-mobile-add-case-submit.md | 16 +++++++++ src/web/public/index.html | 7 ++++ src/web/public/mobile.css | 6 ++-- src/web/public/session-ui.js | 41 ++++++++++++++++-------- 4 files changed, 55 insertions(+), 15 deletions(-) create mode 100644 .changeset/fix-mobile-add-case-submit.md diff --git a/.changeset/fix-mobile-add-case-submit.md b/.changeset/fix-mobile-add-case-submit.md new file mode 100644 index 00000000..e15097e6 --- /dev/null +++ b/.changeset/fix-mobile-add-case-submit.md @@ -0,0 +1,16 @@ +--- +"aicodeman": patch +--- + +fix(mobile): give the Add Case modal a reachable submit button + +`mobile.css` hides `#createCaseModal`'s `.set-foot` on phones, and unlike the Settings +modal that header carries no `set-head-save` — so the Create/Link button existed nowhere +on a phone and the modal could not be submitted at all. Adds the header button and drives +both together, so whichever one is pressed the other shows the same pending state and is +equally unclickable. + +Add Case follows the Settings modal's header-save pattern, so it picks up the existing +`.set-head-actions:has(.set-head-save)` tray and `.set-head-save` sizing below 860px with no +new CSS; the `mobile.css` comment that still listed Add Case as a lone-× sheet is updated to +match. diff --git a/src/web/public/index.html b/src/web/public/index.html index 78eff9d3..9391b9c2 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -2582,8 +2582,15 @@

Add Case

+
+
diff --git a/src/web/public/mobile.css b/src/web/public/mobile.css index c9b0838d..7dc2655c 100644 --- a/src/web/public/mobile.css +++ b/src/web/public/mobile.css @@ -3333,8 +3333,10 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat recessed tray and matching pill geometry instead of reading as a fat accent pill parked beside a stray × glyph. Tray colors come from skin tokens, never a hardcoded black alpha, or the light skins get a grey slab. - `:has()` keeps the tray off the two sheets that carry a lone × (Session - Options and Add Case save from inside their own forms). */ + `:has()` keeps the tray off Session Options, the one sheet left carrying a + lone × because it saves from inside its own per-section forms. Add Case + now has a header save of its own (its footer is hidden below 860px, so + that button is the only way to submit it there), and picks up the tray. */ :is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-head-actions:has(.set-head-save) { padding: 3px; border: 1px solid var(--border); diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index b4d18479..0ace6eef 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -2416,15 +2416,19 @@ Object.assign(CodemanApp.prototype, { // A switched-to panel starts at its own top. const doc = document.getElementById('createCaseDoc'); if (doc) doc.scrollTop = 0; - // Update submit button (hide for manage tab) - const submitBtn = document.getElementById('caseModalSubmit'); + // Update submit buttons (hide for manage tab). Two of them: mobile.css hides + // this modal's .set-foot, so phones submit through the header button instead. + const submitBtns = ['caseModalSubmit', 'caseModalSubmitMobile'] + .map((id) => document.getElementById(id)) + .filter(Boolean); if (tabName === 'case-manage') { - submitBtn.style.display = 'none'; + submitBtns.forEach((btn) => { + btn.style.display = 'none'; + }); this.renderCaseManageList(); this.refreshDockerExports(); } else { - submitBtn.style.display = ''; - submitBtn.textContent = + const label = tabName === 'case-create' ? 'Create' : tabName === 'case-clone' @@ -2434,6 +2438,10 @@ Object.assign(CodemanApp.prototype, { : tabName === 'case-docker' ? 'Link Docker' : 'Link'; + submitBtns.forEach((btn) => { + btn.style.display = ''; + btn.textContent = label; + }); } // Focus appropriate input if (tabName === 'case-create') { @@ -2454,14 +2462,19 @@ Object.assign(CodemanApp.prototype, { }, async submitCaseModal() { - const btn = document.getElementById('caseModalSubmit'); - const originalText = btn.textContent; - btn.classList.add('loading'); - btn.textContent = + // Both submit buttons move together: whichever one the user pressed, the + // other must show the same pending state and be equally unclickable. + const btns = ['caseModalSubmit', 'caseModalSubmitMobile'].map((id) => document.getElementById(id)).filter(Boolean); + const originalText = btns.map((btn) => btn.textContent); + const pendingText = this.caseModalTab === 'case-create' ? 'Creating...' : this.caseModalTab === 'case-clone' ? 'Cloning...' : 'Linking...'; // A clone holds this request open for minutes; without disabling the button a // second click fires a second clone (the loser then fails on ALREADY_EXISTS). - btn.disabled = true; + btns.forEach((btn) => { + btn.classList.add('loading'); + btn.textContent = pendingText; + btn.disabled = true; + }); try { if (this.caseModalTab === 'case-create') { await this.createCase(); @@ -2475,9 +2488,11 @@ Object.assign(CodemanApp.prototype, { await this.linkCase(); } } finally { - btn.classList.remove('loading'); - btn.disabled = false; - btn.textContent = originalText; + btns.forEach((btn, index) => { + btn.classList.remove('loading'); + btn.disabled = false; + btn.textContent = originalText[index]; + }); } }, From 3eff1feb5d94bb22c014320e42be74cf6f0e4d94 Mon Sep 17 00:00:00 2001 From: shenlvkang-collab Date: Tue, 1 Sep 2026 12:30:48 +0800 Subject: [PATCH 16/26] fix(web): render one Claude response-viewer message per model message MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Claude reader concatenated every assistant row between two human prompts into one card, fusing up to 74 distinct model messages into a single card, and it never read the attachment rows that hold a prompt typed while the agent was working. Measured over 57 real transcripts on 2026-09-01, the viewer shows 1,806 messages instead of 356 and 353 user cards instead of 178, with the assistant text sequence unchanged row for row and the response without ?context=full byte-identical on all 57 files. One assistant row IS one whole model message: in that corpus no assistant row carries more than one content block and no message id carries more than one text block, so there was nothing to reassemble. Each row becomes its own message carrying an additive {kind, label, turn}, and the frontend renders a same-role run inside one turn as badge-less continuation segments — which is what keeps a p90 of 11 messages per turn from reading as card spam. A numeric turn gates that rendering, so Codex, the external-CLI pane parser and an older server keep one badge per card. A prompt typed while Claude is working is recorded ONLY as an attachment/queued_command row. Taking it when origin.kind is 'human' and commandMode is 'prompt' recovers 162 user cards from 163 such rows — one is a verbatim repeat inside an unanswered user run and is collapsed by the existing dedup guard — and restores the turn boundary whose absence let the assistant runs fuse. The CLI's own queue entries are cleanly separable: of 322 queued_command rows, 159 are commandMode 'task-notification' and not one of them carries an origin key. This narrows #169 rather than reverting it: sidechain exclusion, the restored- rebind, replayed-snapshot dedup and synthetic-row filtering are all unchanged and still asserted. --- .../fix-claude-response-viewer-per-message.md | 15 ++ docs/architecture-invariants.md | 2 +- skills/codeman/reference/endpoints.md | 1 + skills/codeman/reference/verbs.md | 12 +- src/web/public/app.js | 57 ++++- src/web/public/i18n.js | 1 + src/web/public/styles.css | 37 ++++ src/web/routes/session-routes.ts | 107 ++++++--- test/frontend-public-tooling.test.ts | 10 +- test/response-viewer-turn-segments.test.ts | 149 +++++++++++++ ...ession-routes-claude-last-response.test.ts | 204 +++++++++++++++++- 11 files changed, 547 insertions(+), 48 deletions(-) create mode 100644 .changeset/fix-claude-response-viewer-per-message.md create mode 100644 test/response-viewer-turn-segments.test.ts diff --git a/.changeset/fix-claude-response-viewer-per-message.md b/.changeset/fix-claude-response-viewer-per-message.md new file mode 100644 index 00000000..50b2ef5b --- /dev/null +++ b/.changeset/fix-claude-response-viewer-per-message.md @@ -0,0 +1,15 @@ +--- +"aicodeman": patch +--- + +fix(web): render one Claude response-viewer message per model message + +The Claude reader concatenated every assistant row between two human prompts into one +card, fusing up to 74 distinct model messages into a single card, and it never read the +attachment rows that hold a prompt typed while the agent was working. Measured over 57 +real transcripts on 2026-09-01, the viewer now shows 1,806 messages instead of 356 and +353 user cards instead of 178, recovering the user's own words from 162 absorbed +prompts, with the assistant text sequence unchanged row for row and the response without +`?context=full` byte-identical on all 57 files. A same-speaker run inside one turn +renders as continuation segments under one badge, and the header reports turns as well +as messages instead of claiming a 1,566-row session was "6 messages". diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md index e34e7cd5..c7bd485e 100644 --- a/docs/architecture-invariants.md +++ b/docs/architecture-invariants.md @@ -340,7 +340,7 @@ Anatomy: `.set-shell` → `.set-shell-head` (title + `.set-head-actions`) + `.se ⚠️ **`Session.lastSubmitAt` is persisted state, not a runtime counter.** `start()` reassigns `_claudeSessionId = resumeSessionId || id` on every launch — including the re-attach path for a mux session that survived the restart — so a recovered pane always points the viewer at its *launch* conversation, even when the CLI moved on via `/clear` hours earlier. The submit anchor is the only thing that can correct that without user input, so it round-trips through `SessionState.lastSubmitAt` and is restored in `restoreMuxSessions()`. Drop it from `toState()` and recovered panes silently show the pre-`/clear` transcript until the user types again. Restoring a *stale* anchor is safe: the resolver's staleness guard rejects any candidate transcript older than the one the pane is currently on, which is exactly the shape of a respawn into a fresh conversation. -⚠️ **Claude transcripts are grouped at real human-turn boundaries, not per JSONL row.** A Claude transcript is an append-only event log, so one logical exchange spans many rows: tool-result rows, meta/image/skill rows, compact summaries, task/team notifications, sidechains, replayed assistant snapshots, and multi-block assistant output. Rendering a card per row was the bug: it produced duplicate and truncated cards that looked like the viewer had lost the response. The grouping walks to the next genuine user turn and dedups replayed assistant snapshots while preserving the tool/task/skill/compact/team metadata filtering. Related: a recovered `restored-` tmux placeholder carries a **stale cwd**, so transcript lookup by working directory finds nothing; it rebinds to the matching top-level Claude transcript UUID instead when that match is unambiguous. Tests: `test/routes/session-routes-claude-last-response.test.ts`. Purely client-side (no `renderIndexHtml` step): the template ships with `btn-response-viewer-header--hidden` and `applyHeaderVisibilitySettings()` (settings-ui.js) toggles it after settings load. Hiding must go through that marker class — the base rule is `display:inline-flex !important`, so an inline style can't override it. `showResponseViewer` is in the `displayKeys` per-device set (settings-ui.js), so it does NOT sync across devices. +⚠️ **The Claude viewer emits one message per model message and groups them with `turn`; it never concatenates them.** A Claude transcript is an append-only event log, so one logical exchange spans many rows: tool-result rows, meta/image/skill rows, compact summaries, task/team notifications, sidechains, replayed assistant snapshots. Rendering a card per *row* was the original bug (#169) — but the fix overshot to one card per *human turn*, which fused up to 74 distinct model messages into a single card and reported it as one message. One assistant row IS one whole model message: measured across a real `~/.claude/projects` (CLI 2.1.220-2.1.251) no assistant row carries more than one content block and no `message.id` carries more than one text block, so there was never anything to reassemble, and no adjacent pair of assistant rows continues a table, a list, or an open code fence. Each row is therefore its own message carrying `{kind, label, role, text, timestamp, turn}`; the frontend renders a same-role run inside one `turn` as badge-less continuation segments (`.rv-msg-cont`), which is what keeps a p90 of 11 messages per turn from reading as card spam. ⚠️ **A prompt typed while Claude is working is recorded ONLY as an `attachment/queued_command` row** — the CLI never re-emits it as a `user` row — so reading only `user` rows lost 162 of 353 user cards on that corpus AND lost the turn boundary each one carries, which is what let an assistant run fuse in the first place. Take it only when `attachment.origin.kind === 'human'` and `commandMode === 'prompt'`; the CLI's own queue entries (`commandMode: 'task-notification'`) carry no `origin` key at all. The shape is not a documented CLI contract, so every field check must fail closed. ⚠️ **`data.text` (no `?context=full`) is frozen on the last assistant row and must never be derived from `messages.at(-1)`** — agent pollers hash it (`skills/codeman/preamble.sh`), and the last message can be the user's own queued prompt. Replayed assistant snapshots are still deduped, and the tool/task/skill/compact/team metadata filtering is unchanged. Related: a recovered `restored-` tmux placeholder carries a **stale cwd**, so transcript lookup by working directory finds nothing; it rebinds to the matching top-level Claude transcript UUID instead when that match is unambiguous. Tests: `test/routes/session-routes-claude-last-response.test.ts`, `test/response-viewer-turn-segments.test.ts`. Purely client-side (no `renderIndexHtml` step): the template ships with `btn-response-viewer-header--hidden` and `applyHeaderVisibilitySettings()` (settings-ui.js) toggles it after settings load. Hiding must go through that marker class — the base rule is `display:inline-flex !important`, so an inline style can't override it. `showResponseViewer` is in the `displayKeys` per-device set (settings-ui.js), so it does NOT sync across devices. **File Viewer button** (header, 1.4.1) is **shown by default on desktop** since `211f3c0` (post-1.8.0): toggle under App Settings → Header & Panels → Header buttons → File Viewer (`showFileViewerButton`, in the per-device `displayKeys` set, fallback default `true`). Purely client-side like the response viewer: the template now ships the button VISIBLE (no `--hidden` class) and `applyHeaderVisibilitySettings()` toggles the `btn-file-viewer--hidden` marker class after settings load; phones still hide it via mobile.css. The button toggles the file-browser panel open/closed without opening the settings modal (`panels-ui.js`). The same commit set the **default desktop header** to WS/CPU/MEM + File Viewer + gear: the token-count chip (`showTokenCount`, no settings-UI toggle) and the lifecycle-log button (`showLifecycleLog`) both default **OFF** now (templates ship them hidden; stored prefs still honored). The plan-usage chip default is unchanged (opt-in, see Plan-usage chip). The **Cron toolbar button** joined the same opt-in pattern in 1.6.0: template ships `btn-cron--hidden`, `applyHeaderVisibilitySettings()` toggles it via the per-device `showCronButton` setting (default OFF, App Settings → Header & Panels → Scheduling); cron jobs themselves are unaffected. ### Session list layout (header strip vs. left sidebar) diff --git a/skills/codeman/reference/endpoints.md b/skills/codeman/reference/endpoints.md index c9ab7d43..8a52be31 100644 --- a/skills/codeman/reference/endpoints.md +++ b/skills/codeman/reference/endpoints.md @@ -283,6 +283,7 @@ than into an existing checkout. | create a session in an arbitrary directory (no case, **no PTY**, id at `.data.session.id`) | `POST /api/v1/sessions`, then `POST /api/v1/sessions/:id/interactive` or `.../shell` to start it, see [Starting a worker](#starting-a-worker) | | send input | `POST /api/v1/sessions/:id/input` | | **read a worker's answer** (claude/codex/deepseek) | `GET /api/v1/sessions/:id/last-response` → `.data.{text,timestamp}`, clean transcript text, no TUI noise. ⚠️ **Poll it**, see [symptom 7](#7-last-response-returns-an-empty-string-right-after-stop) | +| read the whole conversation | `GET /api/v1/sessions/:id/last-response?context=full` → `.data.messages[]`. ⚠️ **Only `{role,text}` is present for every mode.** `kind`/`label` come from claude (`prompt`/`response`), deepseek and the pane parser (which also emit `status`/`tool`) but NOT from codex; `timestamp` from claude and codex but not deepseek/pane; `turn` and `queued:true` (a prompt typed while the agent was working) from claude only. `.data.text` is unchanged by `context=full` — it stays the last assistant message, never `messages[-1]` | | read terminal (tail is in **BYTES**, raw ANSI) | `GET /api/v1/sessions/:id/terminal?tail=3000` → `.data.terminalBuffer`, for *diagnosis* (unsubmitted prompt?), not for reading answers | | full tmux scrollback (context bomb; post-mortems only) | `GET /api/v1/sessions/:id/terminal?full=1` | | background agents, one session | `GET /api/v1/sessions/:id/subagents` | diff --git a/skills/codeman/reference/verbs.md b/skills/codeman/reference/verbs.md index fa09d565..4b93d069 100644 --- a/skills/codeman/reference/verbs.md +++ b/skills/codeman/reference/verbs.md @@ -391,7 +391,17 @@ done printf '%s\n' "$TXT" ``` -`.data` is `{text, timestamp}`. ⚠️ **On a hook-less workspace this reads the PREVIOUS +`.data` is `{text, timestamp}`. Add `?context=full` for the whole conversation in +`.data.messages[]`. ⚠️ **The four readers do not emit the same fields — only `{role, text}` +is guaranteed.** `kind`/`label` come from claude (`prompt`/`response`), deepseek and the pane +parser (the last two also emit `status`/`tool`), but **not** from codex; `timestamp` comes +from claude and codex but not from deepseek or the pane parser. A claude worker additionally +carries `turn` (a run of same-speaker messages inside one `turn` is one utterance split into +segments, not separate exchanges) and `queued: true` on a prompt the user typed while the +agent was still working. Filter on `role`, not on `kind`, unless you know the mode. +`.data.text` does not change under `context=full`: it stays the +last **assistant** message, so never read it as `messages[-1]`, which can be a prompt. +⚠️ **On a hook-less workspace this reads the PREVIOUS turn.** `last-response` returns whatever the transcript last flushed, so it is only as correct as your end-of-turn signal: pair it with a `stop` signal or a marker, never with a bare `idle` ([§5.1](#51-where-to-spawn)). ⚠️ **Poll it, do not read it once.** `text` is written diff --git a/src/web/public/app.js b/src/web/public/app.js index d256f436..421643b2 100644 --- a/src/web/public/app.js +++ b/src/web/public/app.js @@ -2183,15 +2183,26 @@ class CodemanApp { } /** Build one response-viewer message so the brief and full views share markup and CSS. */ - _buildResponseViewerMessage(text, role, agentLabel) { + _buildResponseViewerMessage(text, role, agentLabel, meta) { const div = document.createElement('div'); const isUser = role === 'user'; div.className = 'rv-message ' + (isUser ? 'rv-msg-user' : 'rv-msg-assistant'); + // Consecutive messages from one speaker inside one turn are segments of a + // single utterance: one badge, a hairline seam. Claude emits a median of 3 + // messages per turn (p90 11, max 51), so a badge per message would be the + // card spam the old concatenation was introduced to avoid. `meta` is + // optional so the brief view's 3-argument call keeps its exact shape. + const continuation = !!(meta && meta.continuation); + if (continuation) div.classList.add('rv-msg-cont'); + if (meta && meta.kind) div.dataset.kind = meta.kind; + if (meta && meta.queued) div.dataset.queued = '1'; - const roleBadge = document.createElement('div'); - roleBadge.className = 'rv-role ' + (isUser ? 'rv-role-user' : 'rv-role-assistant'); - roleBadge.textContent = isUser ? 'You' : agentLabel; - div.appendChild(roleBadge); + if (!continuation) { + const roleBadge = document.createElement('div'); + roleBadge.className = 'rv-role ' + (isUser ? 'rv-role-user' : 'rv-role-assistant'); + roleBadge.textContent = isUser ? 'You' : agentLabel; + div.appendChild(roleBadge); + } const renderedText = document.createElement('div'); renderedText.className = 'rv-text'; @@ -2351,19 +2362,49 @@ class CodemanApp { if (!body) return; if (messages.length === 0) { - body.textContent = 'No conversation history available'; + // Never destroy what the eye button already rendered: the brief view has + // a terminal-buffer fallback (see toggleResponseViewer) that this + // endpoint does not, so an empty full-context result must not wipe a + // real answer the user is reading. + // ⚠️ Idempotent, because More deliberately stays live here: the branch + // returns before the button is hidden so a transcript that appears a + // moment later can still be loaded, and appending would then stack a + // second identical notice on every retry. + // `:scope >` keeps the lookup off model-rendered markdown inside .rv-text. + let notice = body.querySelector(':scope > .rv-notice'); + if (!notice) { + notice = document.createElement('div'); + notice.className = 'rv-notice'; + body.appendChild(notice); + } + const emptyText = 'No full conversation history available for this session'; + notice.textContent = window.codemanT?.(emptyText) || emptyText; return; } // Render conversation thread const agentLabel = this._getResponseViewerAgentLabel(); body.innerHTML = ''; + let previous = null; for (const msg of messages) { - body.appendChild(this._buildResponseViewerMessage(msg.text, msg.role, agentLabel)); + // ⚠️ A numeric `turn` is REQUIRED, never same-role adjacency alone. + // Only the Claude reader emits turns; Codex and the external-CLI pane + // parser emit adjacent assistant/response blocks with no turn at all, and + // an older server emits none either — all three must keep rendering one + // badged card per message exactly as they do today. + const continuation = + !!previous && previous.role === msg.role && typeof msg.turn === 'number' && previous.turn === msg.turn; + body.appendChild(this._buildResponseViewerMessage(msg.text, msg.role, agentLabel, { ...msg, continuation })); + previous = msg; } this._bindResponseViewerInteractions(body); - if (title) title.textContent = `Conversation (${messages.length} messages)`; + const turns = new Set(messages.filter((msg) => typeof msg.turn === 'number').map((msg) => msg.turn)).size; + if (title) { + title.textContent = turns + ? `Conversation (${messages.length} messages, ${turns} turns)` + : `Conversation (${messages.length} messages)`; + } if (moreBtn) moreBtn.style.display = 'none'; // Scroll to bottom (latest message) body.scrollTop = body.scrollHeight; diff --git a/src/web/public/i18n.js b/src/web/public/i18n.js index fbdcc296..207b6423 100644 --- a/src/web/public/i18n.js +++ b/src/web/public/i18n.js @@ -86,6 +86,7 @@ 'Instance count': '实例数量', 'No response yet': '暂无回复', 'No response yet — send a message in this session first.': '暂无回复，请先在此会话中发送一条消息。', + 'No full conversation history available for this session': '此会话没有可显示的完整对话历史', 'Last Response': '最近一次回复', More: '更多', 'Codeman version': '{name}版本', diff --git a/src/web/public/styles.css b/src/web/public/styles.css index a517b3c0..d7563e39 100644 --- a/src/web/public/styles.css +++ b/src/web/public/styles.css @@ -12600,6 +12600,43 @@ kbd { background: color-mix(in srgb, var(--green) 12%, transparent); } +/* Consecutive messages from one speaker inside one turn are segments of a + single utterance, not separate cards: no repeated badge, a hairline seam. + The role accent survives because the colour rules above match on BOTH + :has(.rv-role-*) and .rv-msg-* — a badge-less continuation still hits the + class arm. Do not drop either arm. */ +.rv-message.rv-msg-cont { + margin-top: -18px; + border-top: 0; + border-top-left-radius: 0; + border-top-right-radius: 0; + padding-top: 0; +} + +.rv-message.rv-msg-cont > .rv-text { + border-top: 1px solid var(--border); + padding-top: 12px; +} + +.rv-message:has(+ .rv-msg-cont) { + border-bottom-left-radius: 0; + border-bottom-right-radius: 0; + padding-bottom: 0; +} + +/* A prompt the user typed while the agent was working (absorbed mid-turn). + A pseudo-element, not a text node, so the i18n MutationObserver cannot + rewrite it. */ +.rv-message[data-queued='1'] .rv-role::after { + content: ' ⏱'; +} + +.rv-notice { + opacity: 0.7; + font-style: italic; + margin-top: 12px; +} + /* Markdown rendered content inside response viewer. Prose uses a proportional font for readability; code keeps monospace. */ .rv-text, diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index 9c9e7b40..8ab5e2a9 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -1926,9 +1926,13 @@ export function registerSessionRoutes( } interface ClaudeResponseMessage { + kind: 'prompt' | 'response'; + label: 'Prompt' | 'Response'; role: 'user' | 'assistant'; text: string; timestamp?: string; + turn: number; + queued?: boolean; } interface ClaudeTranscriptEntry { @@ -1938,6 +1942,19 @@ export function registerSessionRoutes( isSidechain?: boolean; isCompactSummary?: boolean; message?: { content?: unknown }; + // A prompt typed while Claude is working is absorbed mid-turn and recorded + // ONLY here — the CLI never re-emits it as a `user` row. Every field stays + // optional and unvalidated: `queued_command` is not a documented CLI + // contract, so a missing/renamed field must mean "skip", which is also what + // the CLI's own non-human queue entries (commandMode 'task-notification', + // no `origin` key) require. Shape observed on Claude Code 2.1.220-2.1.251. + attachment?: { + type?: string; + prompt?: string; + commandMode?: string; + timestamp?: string; + origin?: { kind?: string }; + }; } function extractClaudeText(content: unknown, separator: string): string { @@ -1963,10 +1980,17 @@ export function registerSessionRoutes( } /** - * Claude writes one logical turn as many JSONL rows: text, thinking and tool - * blocks share message ids, while tool results are represented as user rows. - * Build viewer cards from real user boundaries instead of treating every row - * as a separate chat message. + * Claude writes an append-only event log: tool results arrive as user rows, + * thinking/tool_use rows carry no text, and a prompt typed while the agent is + * working is only ever recorded as an `attachment/queued_command` row. But one + * assistant row IS one whole model message: measured across ~/.claude/projects + * (CLI 2.1.220-2.1.251) no assistant row carries more than one content block + * and no message id carries more than one text block, so there is nothing to + * reassemble. Emit one card per row and group them with `turn` instead of + * concatenating a human turn's replies into a single card (#169), which fused + * up to 74 distinct model messages into one card. Splitting is safe for + * markdown: no adjacent pair of assistant text rows in the corpus continues a + * table, a list, or an open code fence. */ function parseClaudeResponseTranscript( content: string, @@ -1975,8 +1999,23 @@ export function registerSessionRoutes( let lastText = ''; let lastTimestamp = ''; const messages: ClaudeResponseMessage[] = []; - let currentUserFragments = new Set(); - let currentAssistantFragments = new Set(); + // #169's replay guards, kept: they now SKIP a duplicated row instead of + // concatenating it into the previous card. + const currentUserFragments = new Set(); + const currentAssistantFragments = new Set(); + // Turn 0 is reserved for anything emitted before the first human prompt. + let turn = 0; + + const pushUserMessage = (text: string, timestamp: string | undefined, queued: boolean): void => { + // A run of consecutive human inputs (a mid-turn queued burst) is ONE turn, + // so the viewer renders it under one badge instead of one badge per line. + if (messages.at(-1)?.role !== 'user') turn += 1; + const message: ClaudeResponseMessage = { kind: 'prompt', label: 'Prompt', role: 'user', text, timestamp, turn }; + if (queued) message.queued = true; + messages.push(message); + currentUserFragments.add(text); + currentAssistantFragments.clear(); + }; for (const line of content.split('\n')) { if (!line) continue; @@ -1990,25 +2029,37 @@ export function registerSessionRoutes( // rows include repeated image dimensions and other UI-generated context. if (entry.isSidechain) continue; + // A prompt typed while Claude is working is absorbed mid-turn and lives + // ONLY in an attachment row, so it was lost outright. `origin.kind` and + // `commandMode` separate the human's queue entries from the CLI's own: + // measured over 57 real transcripts on 2026-09-01, 322 queued_command rows + // split 163 `prompt`/`human` and 159 `task-notification`, and not one of + // those 159 carries an `origin` key. The 163 human rows become 162 user + // cards here — one is a verbatim repeat inside a still-unanswered user run + // and is collapsed by the dedup guard below — out of 353 user cards total. + if (entry.type === 'attachment') { + if (!full) continue; + const queued = entry.attachment; + if (!queued || queued.type !== 'queued_command') continue; + if (queued.origin?.kind !== 'human' || queued.commandMode !== 'prompt') continue; + const text = typeof queued.prompt === 'string' ? queued.prompt.trim() : ''; + if (!text || isClaudeSyntheticUserMessage(entry, text)) continue; + if (currentUserFragments.has(text)) continue; + pushUserMessage(text, queued.timestamp || entry.timestamp, true); + continue; + } + if (entry.type === 'user') { const text = extractClaudeText(entry.message?.content, '\n').trim(); // A tool_result block has no text block and naturally drops out here. if (!text || isClaudeSyntheticUserMessage(entry, text)) continue; if (!full) continue; - - const previous = messages.at(-1); - if (previous?.role === 'user') { - // Claude can replay the initial user row while restoring a transcript. - // Only collapse duplicates within the same unanswered user turn; the - // same prompt after an assistant response remains a legitimate turn. - if (currentUserFragments.has(text)) continue; - previous.text += `\n\n${text}`; - currentUserFragments.add(text); - } else { - messages.push({ role: 'user', text, timestamp: entry.timestamp }); - currentUserFragments = new Set([text]); - } - currentAssistantFragments.clear(); + // Claude replays the initial user row while restoring a transcript, and + // a CLI that also wrote an absorbed prompt as a user row would double it. + // Both collapse here. The same prompt sent again AFTER a reply is a + // legitimate second turn, because that reply cleared the set. + if (currentUserFragments.has(text)) continue; + pushUserMessage(text, entry.timestamp, false); continue; } @@ -2019,18 +2070,10 @@ export function registerSessionRoutes( lastTimestamp = entry.timestamp || ''; if (!full) continue; - const previous = messages.at(-1); - if (previous?.role === 'assistant') { - // Replayed snapshots sometimes repeat an identical text block. Distinct - // progress/final blocks are kept, but remain inside one Claude card. - if (currentAssistantFragments.has(text)) continue; - previous.text += `\n\n${text}`; - previous.timestamp = entry.timestamp || previous.timestamp; - currentAssistantFragments.add(text); - } else { - messages.push({ role: 'assistant', text, timestamp: entry.timestamp }); - currentAssistantFragments = new Set([text]); - } + // Replayed snapshots repeat an identical text block inside one turn. + if (currentAssistantFragments.has(text)) continue; + messages.push({ kind: 'response', label: 'Response', role: 'assistant', text, timestamp: entry.timestamp, turn }); + currentAssistantFragments.add(text); currentUserFragments.clear(); } diff --git a/test/frontend-public-tooling.test.ts b/test/frontend-public-tooling.test.ts index 945754ac..6785409d 100644 --- a/test/frontend-public-tooling.test.ts +++ b/test/frontend-public-tooling.test.ts @@ -24,7 +24,15 @@ describe('frontend public asset tooling', () => { const appJs = readFileSync(resolve(repoRoot, 'src/web/public/app.js'), 'utf8'); expect(appJs).toContain("body.appendChild(this._buildResponseViewerMessage(lastResponse, 'assistant'"); - expect(appJs).toContain('body.appendChild(this._buildResponseViewerMessage(msg.text, msg.role, agentLabel));'); + expect(appJs).toContain( + 'body.appendChild(this._buildResponseViewerMessage(msg.text, msg.role, agentLabel, { ...msg, continuation }));' + ); + // ⚠️ A numeric `turn` gates continuation rendering. Only the Claude reader + // emits turns; Codex, the external-CLI pane parser and an older server emit + // adjacent same-role messages with none, and must keep one badge per card. + expect(appJs).toContain( + "!!previous && previous.role === msg.role && typeof msg.turn === 'number' && previous.turn === msg.turn" + ); expect(appJs).toContain("div.className = 'rv-message ' + (isUser ? 'rv-msg-user' : 'rv-msg-assistant');"); expect(appJs).toContain("renderedText.className = 'rv-text';"); }); diff --git a/test/response-viewer-turn-segments.test.ts b/test/response-viewer-turn-segments.test.ts new file mode 100644 index 00000000..ed852618 --- /dev/null +++ b/test/response-viewer-turn-segments.test.ts @@ -0,0 +1,149 @@ +/** + * @fileoverview Response-viewer turn segmentation (`CodemanApp._buildResponseViewerMessage`). + * + * The server now emits one message per model message instead of concatenating a + * human turn's replies into one card, so a long autonomous run arrives as tens + * of messages rather than one 12,000-character block. Rendered naively that is + * card spam — the measured distribution is p50 3 messages per turn, p90 11, + * max 51, with 58% of messages under 80 characters. So consecutive messages + * from one speaker inside one `turn` render as SEGMENTS of one card: no + * repeated role badge, a hairline seam. + * + * Pinned here because the badge suppression is the only thing standing between + * the server change and a wall of 51 "Claude" badges: + * + * 1. A continuation carries `rv-msg-cont` and has NO `.rv-role` child, while + * keeping its role class so the CSS accent survives (the colour rules match + * on both `:has(.rv-role-*)` and `.rv-msg-*` — only the class arm hits here). + * 2. A queued prompt is marked in the DOM, not in text, so the i18n + * MutationObserver cannot rewrite the marker. + * 3. The 4th argument is genuinely optional: the brief view's 3-argument call + * still renders a badge. + * + * Loaded via `vm` with a jsdom document injected (same technique as + * response-viewer-file-links.test.ts). + * Port: N/A + */ +import { readFileSync } from 'node:fs'; +import { performance } from 'node:perf_hooks'; +import { resolve } from 'node:path'; +import vm from 'node:vm'; +import { JSDOM } from 'jsdom'; +import { describe, expect, it, vi } from 'vitest'; + +const dom = new JSDOM(''); +const { document, NodeFilter } = dom.window; + +interface MessageBuilder { + _buildResponseViewerMessage(text: string, role: string, agentLabel: string, meta?: unknown): HTMLElement; + loadFullContext(): Promise; + activeSessionId?: string; +} + +function loadCodemanAppClass() { + const constants = readFileSync(resolve(import.meta.dirname, '../src/web/public/constants.js'), 'utf8'); + const source = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8'); + const context = vm.createContext({ + console, + performance, + setInterval: vi.fn(), + clearInterval: vi.fn(), + setTimeout, + clearTimeout, + requestAnimationFrame: vi.fn(), + HTMLCanvasElement: class HTMLCanvasElement {}, + fetch: vi.fn(), + document, + NodeFilter, + localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() }, + window: { addEventListener: vi.fn(), removeEventListener: vi.fn() }, + MobileDetection: {}, + }); + vm.runInContext(`${constants}\n${source}\nglobalThis.__CodemanApp = CodemanApp;`, context); + // The context is returned too: app.js closes over the context's own `fetch`, so a + // test that drives loadFullContext has to replace THAT binding, not globalThis'. + return { CodemanApp: (context as { __CodemanApp: { prototype: MessageBuilder } }).__CodemanApp, context }; +} + +const { CodemanApp, context: appContext } = loadCodemanAppClass(); + +function build(text: string, role: string, meta?: unknown): HTMLElement { + const app = Object.create(CodemanApp.prototype) as MessageBuilder; + return app._buildResponseViewerMessage(text, role, 'Claude', meta); +} + +describe('response viewer turn segmentation', () => { + it('renders a continuation without a repeated role badge but keeps its role class', () => { + const div = build('second half of the same turn', 'assistant', { continuation: true, kind: 'response', turn: 3 }); + + expect(div.classList.contains('rv-msg-cont')).toBe(true); + expect(div.classList.contains('rv-msg-assistant')).toBe(true); + expect(div.querySelector('.rv-role')).toBeNull(); + expect(div.querySelector('.rv-text')).not.toBeNull(); + expect(div.dataset.kind).toBe('response'); + }); + + it('marks a prompt the user queued mid-turn in the DOM, not in the text', () => { + const div = build('actually use PowerShell', 'user', { + continuation: false, + kind: 'prompt', + queued: true, + turn: 2, + }); + + expect(div.dataset.queued).toBe('1'); + expect(div.dataset.kind).toBe('prompt'); + const badge = div.querySelector('.rv-role'); + expect(badge).not.toBeNull(); + expect(badge!.classList.contains('rv-role-user')).toBe(true); + // The marker is a CSS pseudo-element, so the badge text stays translatable. + expect(badge!.textContent).toBe('You'); + }); + + it('still renders a badge for the brief view, which passes no meta', () => { + const div = build('the last response', 'assistant'); + + expect(div.classList.contains('rv-msg-cont')).toBe(false); + expect(div.querySelector('.rv-role')!.textContent).toBe('Claude'); + expect(div.dataset.kind).toBeUndefined(); + expect(div.dataset.queued).toBeUndefined(); + }); +}); + +/** + * The empty-state branch deliberately does NOT wipe the body — the brief view has + * a terminal-buffer fallback this endpoint does not — and deliberately leaves the + * More button live so a transcript that appears a moment later can still be + * loaded. Both together mean the notice must be idempotent: without that, every + * retry stacks another identical line. Upstream got this for free because it + * assigned `body.textContent`. + */ +describe('response viewer empty full-context state', () => { + it('reuses one notice across repeated More clicks and keeps the brief card', async () => { + const body = document.createElement('div'); + body.id = 'responseViewerBody'; + const title = document.createElement('div'); + title.id = 'responseViewerTitle'; + const more = document.createElement('button'); + more.id = 'responseViewerMore'; + document.body.append(body, title, more); + body.textContent = 'No response yet — send a message in this session first.'; + + const app = Object.create(CodemanApp.prototype) as MessageBuilder; + app.activeSessionId = 's1'; + (appContext as { fetch: unknown }).fetch = vi.fn(async () => ({ + json: async () => ({ data: { messages: [] } }), + })); + + await app.loadFullContext(); + await app.loadFullContext(); + await app.loadFullContext(); + + expect(body.querySelectorAll('.rv-notice')).toHaveLength(1); + expect(body.textContent).toContain('No response yet'); + // More stays clickable: it is the only retry path once a transcript lands. + expect(more.style.display).toBe(''); + + document.body.innerHTML = ''; + }); +}); diff --git a/test/routes/session-routes-claude-last-response.test.ts b/test/routes/session-routes-claude-last-response.test.ts index f9cd8bc2..3980d136 100644 --- a/test/routes/session-routes-claude-last-response.test.ts +++ b/test/routes/session-routes-claude-last-response.test.ts @@ -60,6 +60,24 @@ const assistantEntry = (text: string, timestamp: string) => ({ message: { content: [{ type: 'text', text }] }, }); +/** + * A prompt typed while Claude is working. Shape copied from a real CLI 2.1.251 + * row: the CLI's own queue entries carry commandMode 'task-notification' and no + * `origin` key at all, which is what separates them from the human's. + */ +const queuedEntry = (prompt: string, timestamp: string, kind: 'human' | 'task-notification' = 'human') => ({ + type: 'attachment', + timestamp, + attachment: { + type: 'queued_command', + prompt, + source_uuid: `src-${timestamp}`, + commandMode: kind === 'human' ? 'prompt' : 'task-notification', + ...(kind === 'human' ? { origin: { kind: 'human' } } : {}), + timestamp, + }, +}); + describe('GET /api/sessions/:id/last-response (claude)', () => { let harness: LocalHarness; let testHome: string; @@ -93,7 +111,7 @@ describe('GET /api/sessions/:id/last-response (claude)', () => { return { response, body: JSON.parse(response.body) }; } - it('recovers a placeholder tmux session by UUID prefix and groups JSONL fragments into turns', async () => { + it('recovers a placeholder tmux session by UUID prefix and renders one message per model message', async () => { const restoredId = 'restored-40568a29'; const conversationId = '40568a29-d4eb-4eb6-b671-8401428e4f39'; const session = harness.ctx._session as typeof harness.ctx._session & { @@ -135,15 +153,60 @@ describe('GET /api/sessions/:id/last-response (claude)', () => { expect(full.body.data).toEqual({ text: 'Second half.', timestamp: '2026-07-21T00:00:06Z', + // #169's guarantees all still hold and this array proves them: the replayed + // 'first prompt' row, the replayed 'Checking the files.' snapshot, the + // sidechain row and all five synthetic rows are absent. Only the GROUPING + // UNIT narrows, from one card per human turn to one card per model + // message, carried by `turn` instead of by a '\n\n' joiner. messages: [ - { role: 'user', text: 'first prompt', timestamp: '2026-07-21T00:00:00Z' }, { + kind: 'prompt', + label: 'Prompt', + role: 'user', + text: 'first prompt', + timestamp: '2026-07-21T00:00:00Z', + turn: 1, + }, + { + kind: 'response', + label: 'Response', role: 'assistant', - text: 'Checking the files.\n\nThe first result is ready.', + text: 'Checking the files.', + timestamp: '2026-07-21T00:00:01Z', + turn: 1, + }, + { + kind: 'response', + label: 'Response', + role: 'assistant', + text: 'The first result is ready.', timestamp: '2026-07-21T00:00:03Z', + turn: 1, + }, + { + kind: 'prompt', + label: 'Prompt', + role: 'user', + text: 'second prompt', + timestamp: '2026-07-21T00:00:00Z', + turn: 2, + }, + { + kind: 'response', + label: 'Response', + role: 'assistant', + text: 'First half.', + timestamp: '2026-07-21T00:00:04Z', + turn: 2, + }, + { + kind: 'response', + label: 'Response', + role: 'assistant', + text: 'Second half.', + timestamp: '2026-07-21T00:00:06Z', + turn: 2, }, - { role: 'user', text: 'second prompt', timestamp: '2026-07-21T00:00:00Z' }, - { role: 'assistant', text: 'First half.\n\nSecond half.', timestamp: '2026-07-21T00:00:06Z' }, ], }); expect(session.adoptClaudeSessionId).toHaveBeenCalledWith(conversationId); @@ -175,6 +238,137 @@ describe('GET /api/sessions/:id/last-response (claude)', () => { ['assistant', 'Second answer.'], ]); }); + + /** + * A prompt typed while Claude is working is absorbed mid-turn and recorded + * ONLY as an attachment row — 160 of the 347 user cards across a real + * ~/.claude/projects. Reading only `user` rows lost them outright AND lost the + * turn boundary they carry, which is what let an assistant run fuse. + */ + it('surfaces a prompt the user queued while Claude was working', async () => { + const sessionId = harness.ctx._session.id; + const session = harness.ctx._session as typeof harness.ctx._session & { + claudeSessionId: string; + adoptClaudeSessionId: ReturnType; + }; + session.claudeSessionId = sessionId; + session.adoptClaudeSessionId = vi.fn(); + writeTranscript(sessionId, [ + userEntry('start the job'), + assistantEntry('Working on it.', '2026-07-21T00:00:01Z'), + queuedEntry('actually use PowerShell', '2026-07-21T00:00:02Z'), + queuedEntry('background agent finished', '2026-07-21T00:00:03Z', 'task-notification'), + // The most common attachment subtype; it carries no prompt/origin at all. + { type: 'attachment', attachment: { type: 'total_tokens_reminder', tokens: 1 } }, + assistantEntry('Switched to PowerShell.', '2026-07-21T00:00:04Z'), + ]); + + const { body } = await getLastResponse(sessionId, true); + const messages = body.data.messages as Array<{ role: string; text: string; turn: number; queued?: boolean }>; + expect(messages.map((message) => [message.role, message.text, message.turn])).toEqual([ + ['user', 'start the job', 1], + ['assistant', 'Working on it.', 1], + ['user', 'actually use PowerShell', 2], + ['assistant', 'Switched to PowerShell.', 2], + ]); + expect(messages[2].queued).toBe(true); + expect(messages[0].queued).toBeUndefined(); + }); + + /** + * Mostly forward insurance. A queued prompt re-emitted as a `user` row AFTER + * its attachment row — the shape that would double-render — is not observed on + * CLI 2.1.220-2.1.251 (0 of 163 measured 2026-09-01). The only exact-text + * collisions are three occurrences of the same one-character nudge in a single + * transcript, and the guard fires on one of them, which is why 163 human + * queued rows yield 162 cards. The guard exists so a CLI that starts writing + * both rows does not double every absorbed prompt. + */ + it('renders an absorbed prompt once when the CLI also writes it as a user row', async () => { + const sessionId = harness.ctx._session.id; + const session = harness.ctx._session as typeof harness.ctx._session & { + claudeSessionId: string; + adoptClaudeSessionId: ReturnType; + }; + session.claudeSessionId = sessionId; + session.adoptClaudeSessionId = vi.fn(); + writeTranscript(sessionId, [ + userEntry('go'), + assistantEntry('OK.', '2026-07-21T00:00:01Z'), + queuedEntry('switch to PowerShell', '2026-07-21T00:00:02Z'), + userEntry('switch to PowerShell'), + assistantEntry('Done.', '2026-07-21T00:00:03Z'), + ]); + + const { body } = await getLastResponse(sessionId, true); + const messages = body.data.messages as Array<{ role: string; text: string; queued?: boolean }>; + const absorbed = messages.filter((message) => message.role === 'user' && message.text === 'switch to PowerShell'); + expect(absorbed).toHaveLength(1); + expect(absorbed[0].queued).toBe(true); + }); + + /** + * The brief response is what agent pollers hash (skills/codeman/preamble.sh + * last_text()). It must stay the last assistant row and must NEVER be derived + * from messages.at(-1), which can be the user's own queued prompt. + */ + it('keeps the brief response on the last assistant row while a turn is in flight', async () => { + const sessionId = harness.ctx._session.id; + const session = harness.ctx._session as typeof harness.ctx._session & { + claudeSessionId: string; + adoptClaudeSessionId: ReturnType; + }; + session.claudeSessionId = sessionId; + session.adoptClaudeSessionId = vi.fn(); + writeTranscript(sessionId, [ + userEntry('go'), + assistantEntry('Let me look.', '2026-07-21T00:00:01Z'), + { type: 'assistant', message: { content: [{ type: 'tool_use', id: 'x' }] } }, + { type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 'x' }] } }, + ]); + + const brief = await getLastResponse(sessionId); + expect(brief.body.data).toEqual({ text: 'Let me look.', timestamp: '2026-07-21T00:00:01Z' }); + + const { body } = await getLastResponse(sessionId, true); + const messages = body.data.messages as Array<{ role: string; text: string }>; + expect(messages.at(-1)).toMatchObject({ role: 'assistant', text: 'Let me look.' }); + expect(body.data.text).toBe('Let me look.'); + }); + + /** + * A multi-line paste absorbed mid-turn arrives as N queued rows within a few + * hundred milliseconds (observed: 5 rows inside ~360ms). They are one turn, so + * the viewer renders them under one badge instead of N. + */ + it('groups a burst of queued prompts into one turn', async () => { + const sessionId = harness.ctx._session.id; + const session = harness.ctx._session as typeof harness.ctx._session & { + claudeSessionId: string; + adoptClaudeSessionId: ReturnType; + }; + session.claudeSessionId = sessionId; + session.adoptClaudeSessionId = vi.fn(); + writeTranscript(sessionId, [ + userEntry('go'), + assistantEntry('OK.', '2026-07-21T00:00:01Z'), + queuedEntry('one more thing', '2026-07-21T00:00:02.100Z'), + queuedEntry('and the requirements are', '2026-07-21T00:00:02.360Z'), + queuedEntry('finally, keep it fast', '2026-07-21T00:00:02.480Z'), + assistantEntry('Understood.', '2026-07-21T00:00:05Z'), + ]); + + const { body } = await getLastResponse(sessionId, true); + const messages = body.data.messages as Array<{ role: string; turn: number }>; + expect(messages.map((message) => [message.role, message.turn])).toEqual([ + ['user', 1], + ['assistant', 1], + ['user', 2], + ['user', 2], + ['user', 2], + ['assistant', 2], + ]); + }); }); /** From ccfda623fea3165f8ad5242b27df5c385fd8a86b Mon Sep 17 00:00:00 2001 From: shenlvkang-collab Date: Tue, 1 Sep 2026 12:33:24 +0800 Subject: [PATCH 17/26] fix(session): learn the live Claude conversation from the CLI's own hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Which conversation a pane is on was re-derived by correlating ~/.claude/history.jsonl against Session.lastSubmitAt — and lastSubmitAt is bumped only by input that flows through Codeman's own write path (Session.write / writeViaMux). A user who attaches to the pane's tmux session directly never set it, so resolveActiveClaudeSessionIdFromHistory() returned at its first line for that pane's whole life and the response viewer stayed pinned to the launch conversation, showing a pre-/clear transcript indefinitely. A UserPromptSubmit hook reports the live conversation id from inside the CLI process, delivered under the pane's own $CODEMAN_SESSION_ID. That binding is a fact rather than a correlation: it never consults workingDir, so it cannot be claimed by a sibling pane on the same folder, a closed tab, or a bare `claude` in the user's terminal. A pane holding such an id skips the correlation entirely, so the number of prompts eligible for cwd-based guessing goes DOWN, never up — the naive alternative (relax the guard, or synthesize an anchor from PTY activity) is the reverted bug the resolver's own comment describes. The hook also stamps lastSubmitAt, so it finally means "a prompt was submitted" rather than "typed into Codeman's web terminal". Conversations vouched for first-hand — and only those — extend a persisted claudeSessionChain, whose tail re-pins the conversation when a surviving tmux session is re-attached after a restart. ⚠️ start() resets the id at THREE points and the last one runs unconditionally after the mux branch, so the tail is applied there too; patching only the mux branch looks right and silently does nothing. ⚠️ The hook's stdout is discarded with curl's own -o /dev/null. Claude Code injects a UserPromptSubmit hook's stdout into the model's context ("Exit code 0 - stdout shown to Claude"), and a trailing >/dev/null does NOT work: curlCmd already ends `... 2>/dev/null || true`, and in `pipeline || true >/dev/null` the shell binds the redirection to `true`, which never runs on the success path. The discard is opt-in so the five SSE-fed events keep byte-identical command text and no workspace's settings file is rewritten for them. The staleness marker is quote-free for the matching reason: hooksJson is JSON.stringify'd, so a quoted needle never matches and the gate would rewrite every workspace on every spawn. Existing workspaces heal on their next Claude spawn through the staleness sweep. --- .../fix-claude-conversation-first-hand.md | 23 ++++ docs/architecture-invariants.md | 2 + src/hooks-config.ts | 43 ++++++- src/session.ts | 110 +++++++++++++++- src/types/api.ts | 4 + src/types/session.ts | 9 ++ src/web/route-helpers.ts | 5 + src/web/routes/hook-event-routes.ts | 24 +++- src/web/routes/session-routes.ts | 11 +- src/web/schemas.ts | 3 + src/web/server.ts | 4 + test/hooks-config.test.ts | 61 +++++++++ test/mocks/mock-session.ts | 26 ++++ test/routes/hook-event-routes.test.ts | 69 ++++++++++ ...ession-routes-claude-last-response.test.ts | 39 +++++- .../session-claude-conversation-chain.test.ts | 118 ++++++++++++++++++ 16 files changed, 540 insertions(+), 11 deletions(-) create mode 100644 .changeset/fix-claude-conversation-first-hand.md create mode 100644 test/session-claude-conversation-chain.test.ts diff --git a/.changeset/fix-claude-conversation-first-hand.md b/.changeset/fix-claude-conversation-first-hand.md new file mode 100644 index 00000000..41755447 --- /dev/null +++ b/.changeset/fix-claude-conversation-first-hand.md @@ -0,0 +1,23 @@ +--- +"aicodeman": patch +--- + +fix(session): learn the live Claude conversation from the CLI's own hook + +Which conversation a pane is on was re-derived by correlating `~/.claude/history.jsonl` +against `Session.lastSubmitAt` — and `lastSubmitAt` is bumped only by input that flows +through Codeman's own write path. A user who attaches to the pane's tmux session directly +never set it, so the resolver returned at its first line for that pane's whole life and the +response viewer stayed pinned to the launch conversation, showing a pre-`/clear` transcript +indefinitely. A new `UserPromptSubmit` hook reports the live conversation id from inside the +CLI process, addressed by the pane's own `$CODEMAN_SESSION_ID`, so the id is a fact rather +than a correlation: it never consults the working directory and cannot be claimed by a +sibling pane on the same folder. A pane with such an id now skips the correlation entirely, +which strictly reduces the number of prompts eligible for cwd-based guessing. The hook also +stamps `lastSubmitAt`, so it finally means "a prompt was submitted" rather than "typed into +Codeman's web terminal". Conversations vouched for this way are persisted as a chain, whose +tail re-pins the conversation when a surviving tmux session is re-attached after a restart — +`start()` otherwise resets the id back to the launch conversation. Existing workspaces heal +on their next Claude spawn via the hooks staleness sweep. The hook's stdout is discarded with curl's own `-o /dev/null`: +Claude Code injects `UserPromptSubmit` output into the model's context, so an undiscarded +curl would paste the API envelope into the user's own prompt on every turn. diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md index e34e7cd5..72aa3c0a 100644 --- a/docs/architecture-invariants.md +++ b/docs/architecture-invariants.md @@ -338,6 +338,8 @@ Anatomy: `.set-shell` → `.set-shell-head` (title + `.set-head-actions`) + `.se ⚠️ **A Claude pane's conversation is identified by the pane's own Enter, never by "newest entry for this cwd".** `~/.claude/history.jsonl` records every submitted prompt as `{project, sessionId, timestamp}`, and `/clear` moves the pane to a fresh `.jsonl` that nothing on the PTY announces — so the viewer has to re-derive the live conversation. Keying that off `project` alone was the bug: a cwd is shared with every other Codeman tab on it, with tabs long since closed, and with any plain `claude` the user runs in their own terminal, so the eye followed whichever of those conversations was typed into last and showed a stranger's transcript. `resolveActiveClaudeSessionIdFromHistory()` instead credits an entry to a pane only when it lands within `CLAUDE_SUBMIT_MATCH_MS` of that pane's `Session.lastSubmitAt` **and** no other pane on the same cwd submitted closer — the same last-submit correlation the Codex locator uses. With no correlated entry the pane keeps the id it has: a viewer one turn behind beats a viewer showing someone else's conversation. +⚠️ **A first-hand conversation id outranks every correlation, and the correlation must never run when one exists.** `UserPromptSubmit` and `Stop` hook payloads carry `session_id` — the pane's LIVE conversation, reported from inside the CLI process — and reach Codeman addressed by that pane's own `$CODEMAN_SESSION_ID`. That binding is a fact: it never consults `workingDir`, so it cannot be claimed by a sibling pane on the same folder, by a closed tab, or by a bare `claude` in the user's terminal. `Session.claudeSessionIdIsFirstHand` gates `resolveActiveClaudeSessionIdFromHistory()` at its first line, so the number of prompts eligible for cwd-based guessing goes DOWN, never up. There is no TTL: if hooks stop arriving the last hook-supplied id is kept forever rather than falling back to guessing, which is the same rule as the paragraph below. ⚠️ **This is also the only fix for a pane driven by attaching to its tmux session directly.** `lastSubmitAt` was bumped only by `Session.write()`/`writeViaMux()`, i.e. input that flows through Codeman, so such a pane's anchor stayed 0 and the resolver returned at `if (!submitAt)` for the pane's entire life. The hook stamps it too (`markPromptSubmitted()`), so it finally means "a prompt was submitted". ⚠️ **Only a first-hand adoption may extend `Session.claudeSessionChain`** — a correlated guess writing into the pane's permanent record is precisely the bug the paragraph above describes, made durable. The chain is persisted because `/clear` is otherwise unrecoverable: once the pane moves on, the predecessor id exists nowhere else. Its tail re-pins the conversation on a RESTORED mux attach, where the launch id is a lie (the CLI never stopped and may have `/clear`ed before the restart); a NEW pane has an empty chain and keeps the launch id unchanged. ⚠️ **The hook's stdout must stay discarded, using curl's own `-o /dev/null`** (`curlCmdSilent`): Claude Code injects a `UserPromptSubmit` hook's stdout into the model's context — the CLI's own hook reference says "Exit code 0 - stdout shown to Claude" — so an undiscarded curl pastes Codeman's `{"success":true,…}` envelope into the user's own prompt on every turn. ⚠️ **A trailing `>/dev/null` does NOT work and looks like it does**: `curlCmd` already ends `… 2>/dev/null || true`, and in `pipeline || true >/dev/null` the shell binds the redirection to `true`, which never runs on the success path. An `endsWith('>/dev/null')` assertion passes on exactly that broken form, so the test asserts the `-o` flag instead. The other events feed SSE, where their stdout is harmless — hence a separate builder rather than a change to `curlCmd`. Tests: `test/hooks-config.test.ts`, `test/routes/hook-event-routes.test.ts`, `test/routes/session-routes-claude-last-response.test.ts`. + ⚠️ **`Session.lastSubmitAt` is persisted state, not a runtime counter.** `start()` reassigns `_claudeSessionId = resumeSessionId || id` on every launch — including the re-attach path for a mux session that survived the restart — so a recovered pane always points the viewer at its *launch* conversation, even when the CLI moved on via `/clear` hours earlier. The submit anchor is the only thing that can correct that without user input, so it round-trips through `SessionState.lastSubmitAt` and is restored in `restoreMuxSessions()`. Drop it from `toState()` and recovered panes silently show the pre-`/clear` transcript until the user types again. Restoring a *stale* anchor is safe: the resolver's staleness guard rejects any candidate transcript older than the one the pane is currently on, which is exactly the shape of a respawn into a fresh conversation. ⚠️ **Claude transcripts are grouped at real human-turn boundaries, not per JSONL row.** A Claude transcript is an append-only event log, so one logical exchange spans many rows: tool-result rows, meta/image/skill rows, compact summaries, task/team notifications, sidechains, replayed assistant snapshots, and multi-block assistant output. Rendering a card per row was the bug: it produced duplicate and truncated cards that looked like the viewer had lost the response. The grouping walks to the next genuine user turn and dedups replayed assistant snapshots while preserving the tool/task/skill/compact/team metadata filtering. Related: a recovered `restored-` tmux placeholder carries a **stale cwd**, so transcript lookup by working directory finds nothing; it rebinds to the matching top-level Claude transcript UUID instead when that match is unambiguous. Tests: `test/routes/session-routes-claude-last-response.test.ts`. Purely client-side (no `renderIndexHtml` step): the template ships with `btn-response-viewer-header--hidden` and `applyHeaderVisibilitySettings()` (settings-ui.js) toggles it after settings load. Hiding must go through that marker class — the base rule is `display:inline-flex !important`, so an inline style can't override it. `showResponseViewer` is in the `displayKeys` per-device set (settings-ui.js), so it does NOT sync across devices. diff --git a/src/hooks-config.ts b/src/hooks-config.ts index 534993f0..687ee36d 100644 --- a/src/hooks-config.ts +++ b/src/hooks-config.ts @@ -366,19 +366,33 @@ export function generateHooksConfig(): { hooks: Record } { // never lands in this config and rotation needs no respawn. If the var/file is // missing the header is empty — the middleware then allows the request only on // the plain loopback bypass (tunnel down), same as pre-secret behavior. - const curlCmd = (event: HookEventType) => + const curlCmd = (event: HookEventType, options: { discardStdout?: boolean } = {}) => `HOOK_DATA=$(cat 2>/dev/null || echo '{}'); ` + `printf '{"event":"${event}","sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ` + // `-k`, same as the statusline exporter: CODEMAN_API_URL is loopback HTTPS with // a self-signed cert on --https/tailscale installs. Without it curl exits 60, // the `|| true` swallows it, and ALL SIX hook events die silently: respawn loses // its definitive idle signals and the wait endpoints lose stop/blocked. - `curl -sk -X POST "$CODEMAN_API_URL/api/hook-event" ` + + `curl -sk ${options.discardStdout ? '-o /dev/null ' : ''}-X POST "$CODEMAN_API_URL/api/hook-event" ` + `-H 'Content-Type: application/json' ` + `-H "X-Codeman-Hook-Secret: $(cat "$CODEMAN_HOOK_SECRET_FILE" 2>/dev/null)" ` + `--data @- ` + `2>/dev/null || true`; + // The same POST with stdout DISCARDED, via curl's own `-o`. UserPromptSubmit is + // one of the hook events whose stdout Claude Code injects into the model's + // context (the CLI's own hook reference: "Exit code 0 - stdout shown to + // Claude"), so an undiscarded curl pastes Codeman's `{"success":true,…}` + // envelope into the user's prompt on every single turn. + // ⚠️ It MUST be curl's flag, not a trailing redirect. `curlCmd` already ends + // `… 2>/dev/null || true`, and in `pipeline || true >/dev/null` the shell binds + // the redirection to `true` — which never runs on the success path — so the + // envelope still reaches stdout. Verified in dash and bash. + // ⚠️ The flag is opt-in so the other events' command text stays byte-identical: + // their stdout feeds the SSE stream harmlessly, and changing it would rewrite + // every workspace's settings file for no gain. + const curlCmdSilent = (event: HookEventType) => curlCmd(event, { discardStdout: true }); + return { hooks: { Notification: [ @@ -410,6 +424,16 @@ export function generateHooksConfig(): { hooks: Record } { hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_SECONDS }], }, ], + // The pane's LIVE conversation id, reported by the CLI process itself. + // Without it the response viewer has to guess which `.jsonl` a pane + // is on after a `/clear`, and the only anchor it can guess from is an + // Enter that went THROUGH Codeman — so a user who attaches to tmux + // directly never gets one and stays pinned to the launch conversation. + UserPromptSubmit: [ + { + hooks: [{ type: 'command', command: curlCmdSilent('prompt_submitted'), timeout: HOOK_TIMEOUT_SECONDS }], + }, + ], SubagentStop: [ { hooks: [ @@ -735,9 +759,22 @@ export async function refreshStaleCodemanHooks(casePath: string): Promise // Approvals Inbox needs the elicitation_complete/elicitation_response // matchers; their absence marks a pre-inbox hooks block. const hasElicitationComplete = hooksJson.includes('elicitation_complete'); + // The UserPromptSubmit event is what gives a tmux-driven pane a first-hand + // conversation id; its absence marks a pre-prompt_submitted hooks block. + // ⚠️ No surrounding quotes: `hooksJson` is JSON.stringify'd, so the marker + // inside the command reads \"prompt_submitted\" and a quoted needle never + // matches — which would make this gate permanently false and rewrite every + // workspace's settings file on every Claude spawn. The sibling markers are + // quote-free for the same reason. + const hasPromptSubmit = hooksJson.includes('prompt_submitted'); if ( !isOurs || - (hasSecret && hasBackgroundWake && hasSubagentStopGuard && hasElicitationComplete && !hasTlsFlaglessCurl) + (hasSecret && + hasBackgroundWake && + hasSubagentStopGuard && + hasElicitationComplete && + hasPromptSubmit && + !hasTlsFlaglessCurl) ) return; const generated = generateHooksConfig(); diff --git a/src/session.ts b/src/session.ts index 8a0608aa..f7c3085b 100644 --- a/src/session.ts +++ b/src/session.ts @@ -152,6 +152,11 @@ const WIRE_ACTIVITY_SETTLE_MS = 15_000; /** Graceful shutdown delay when stopping session (100ms) */ const GRACEFUL_SHUTDOWN_DELAY_MS = 100; +// Conversations kept in a pane's chain. A pane that /clears repeatedly would +// otherwise grow state.json without bound; 32 covers any real session's history +// and the oldest entries are the ones whose transcripts Claude Code has pruned. +const MAX_CLAUDE_SESSION_CHAIN = 32; + // Filter out terminal focus escape sequences (focus in/out reports) // ^[[I (focus in), ^[[O (focus out), and the enable/disable sequences // eslint-disable-next-line no-control-regex @@ -427,6 +432,17 @@ export class Session extends EventEmitter { private _wireActivityAt: number; private _wireActivitySettleUntil: number; private _claudeSessionId: string | null = null; + // Set only when the id came from the CLI's own UserPromptSubmit/Stop hook + // payload, keyed on this pane's $CODEMAN_SESSION_ID. That binding is a fact, + // not a correlation: it never consults cwd, so a sibling pane on the same + // folder cannot steal it. Runtime-only — a restart must re-earn it from the + // next hook rather than trust a persisted claim. + private _claudeSessionIdIsFirstHand = false; + // Conversations this pane has been on, oldest first, current last. Grows only + // through a first-hand adoption, so it can never splice in a foreign + // conversation. Persisted, because `/clear` is otherwise unrecoverable: the + // predecessor id exists nowhere else once the pane moves on. + private _claudeSessionChain: string[] = []; private _totalCost: number = 0; private _messages: ClaudeMessage[] = []; private _lineBuffer: string = ''; @@ -648,6 +664,8 @@ export class Session extends EventEmitter { attachmentHistory?: SessionAttachmentHistoryItem[]; /** Restored wall-clock ms of the pane's last Enter (see `lastSubmitAt`). */ lastSubmitAt?: number; + /** Restored conversation chain, oldest first (see `claudeSessionChain`). */ + claudeSessionChain?: string[]; /** Restored wall-clock ms of the pane's last output (recovery only; see `_wireActivityAt`). */ lastActivityAt?: number; /** Remote execution metadata for sessions launched through SSH inside local tmux. */ @@ -704,6 +722,13 @@ export class Session extends EventEmitter { // response viewer re-derive the live conversation without waiting for the // user to type again. this._lastSubmitAt = config.lastSubmitAt ?? 0; + // Restored chain: its tail is the conversation the CLI was actually on when + // the server stopped, which outranks the launch id seeded just above. The + // FIRST-HAND flag is deliberately NOT restored — a persisted claim is not a + // fact, so the pane re-earns the guess-free path from its next hook. + this._claudeSessionChain = Array.isArray(config.claudeSessionChain) ? [...config.claudeSessionChain] : []; + const restoredConversation = this._claudeSessionChain[this._claudeSessionChain.length - 1]; + if (restoredConversation) this._claudeSessionId = restoredConversation; this._mux = config.mux || null; this._useMux = config.useMux ?? (this._mux !== null && this._mux.isAvailable()); this._muxSession = config.muxSession || null; @@ -902,6 +927,20 @@ export class Session extends EventEmitter { return this._claudeSessionId; } + /** + * True when `claudeSessionId` came from the CLI's own hook payload rather than + * from the launch config or a history correlation. The response viewer uses it + * to skip guessing entirely — see resolveActiveClaudeSessionIdFromHistory(). + */ + get claudeSessionIdIsFirstHand(): boolean { + return this._claudeSessionIdIsFirstHand; + } + + /** Conversations this pane has been on, oldest first, current last. */ + get claudeSessionChain(): readonly string[] { + return this._claudeSessionChain; + } + /** Docker execution metadata when this session runs inside a container, else undefined. */ get docker(): SessionDocker | undefined { return this._docker; @@ -959,11 +998,38 @@ export class Session extends EventEmitter { // payload). In interactive PTY mode Claude CLI emits no JSON to stdout, so // `_handleJsonMessage` never sees `session_id`; hooks are the only signal // that conveys a post-/clear conversation switch. - adoptClaudeSessionId(newId: string): void { - if (!newId || newId === this._claudeSessionId) return; + // + // `firstHand` marks an id that came from the CLI process itself — a hook + // payload whose delivery was keyed on this pane's $CODEMAN_SESSION_ID. Only + // those extend the chain: a history-correlated guess must never be able to + // write a foreign conversation into this pane's permanent record. + adoptClaudeSessionId(newId: string, options: { firstHand?: boolean } = {}): void { + if (!newId) return; + if (options.firstHand) { + this._claudeSessionIdIsFirstHand = true; + this._recordClaudeSessionInChain(newId); + } + if (newId === this._claudeSessionId) return; this._claudeSessionId = newId; } + /** + * Append to the conversation chain, oldest first. A repeat of the current tail + * is a no-op (every prompt in a conversation reports the same id), and an id + * already in the chain moves to the tail rather than duplicating, which is + * what a `/resume` back to an earlier conversation does. + */ + private _recordClaudeSessionInChain(id: string): void { + if (this._claudeSessionChain[this._claudeSessionChain.length - 1] === id) return; + const existing = this._claudeSessionChain.indexOf(id); + if (existing !== -1) this._claudeSessionChain.splice(existing, 1); + this._claudeSessionChain.push(id); + // A pane that /clears in a loop must not grow this without bound. + if (this._claudeSessionChain.length > MAX_CLAUDE_SESSION_CHAIN) { + this._claudeSessionChain.splice(0, this._claudeSessionChain.length - MAX_CLAUDE_SESSION_CHAIN); + } + } + /** The tmux session name, if the session is running inside a mux */ get muxName(): string | null { return this._muxSession?.muxName ?? null; @@ -1397,6 +1463,12 @@ export class Session extends EventEmitter { respawnBlocked: this._respawnBlocked || undefined, attachmentHistory: this.attachmentHistory.length > 0 ? this.attachmentHistory : undefined, lastSubmitAt: this._lastSubmitAt || undefined, + // Only a chain the CLI's own hooks vouched for is persisted, and only when + // the pane actually moved conversation. Its LAST entry is the live one, so + // it is also what restores `claudeSessionId` across a restart — `start()` + // resets that field to the launch id at three separate points, which is + // why a recovered pane otherwise shows its pre-/clear transcript forever. + claudeSessionChain: this._claudeSessionChain.length > 0 ? [...this._claudeSessionChain] : undefined, // envOverrides intentionally NOT on the public SessionState type — they must not // leak into SSE / GET /api/sessions broadcasts (schema allows OPENCODE_*, which // can carry secrets). For disk persistence, session-manager calls @@ -1931,6 +2003,11 @@ export class Session extends EventEmitter { }, REMOTE_CLI_VERSION_PROBE_DELAY_MS); } + // ⚠️ Hoisted, because the "third reset point" below runs unconditionally + // AFTER the mux branch and would otherwise stomp the restored conversation + // straight back to the launch id. + let restoredConversation: string | undefined; + // If mux wrapping is enabled, create or attach to a mux session if (this._useMux && this._mux) { try { @@ -1972,7 +2049,15 @@ export class Session extends EventEmitter { // over the generic `this.id` fallback, or this line clobbers it back // to the Codeman id // on every single respawn. - this._claudeSessionId = this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id; + // ⚠️ 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. + restoredConversation = isRestored ? this._claudeSessionChain[this._claudeSessionChain.length - 1] : undefined; + this._claudeSessionId = + restoredConversation || this._resumeSessionId || this._ompConfig?.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 @@ -2094,8 +2179,13 @@ export class Session extends EventEmitter { // 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). - this._claudeSessionId = this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id; + // (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. + this._claudeSessionId = + restoredConversation || this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id; this._pid = this.ptyProcess.pid; console.log('[Session] Interactive PTY spawned with PID:', this._pid); @@ -3185,6 +3275,16 @@ export class Session extends EventEmitter { } } + /** + * A prompt was submitted, reported by the CLI's own UserPromptSubmit hook. + * `_trackSubmit` only sees input that flows through Codeman's write path, so + * a pane the user drives by attaching to tmux directly never stamped this and + * `lastSubmitAt` stayed 0 for its whole life. + */ + markPromptSubmitted(): void { + this._lastSubmitAt = Date.now(); + } + /** * Per-client highest-applied input sequence, for exactly-once input delivery. * Keyed by the web client's stable `clientId`. Bounded so many devices over a diff --git a/src/types/api.ts b/src/types/api.ts index b63268af..e90cb265 100644 --- a/src/types/api.ts +++ b/src/types/api.ts @@ -110,6 +110,10 @@ export type HookEventType = | 'stop' | 'teammate_idle' | 'task_completed' + // Claude Code's UserPromptSubmit. The payload's `session_id` is the pane's + // LIVE conversation id, reported by the CLI process itself, so it survives a + // `/clear` without any cwd/timestamp correlation. + | 'prompt_submitted' // No Claude Code hook behind this one: it is the DeepSeek status bridge's // "a turn STARTED" report (see deepseek-status-shim.ts). Keep in step with // HookEventSchema in web/schemas.ts. diff --git a/src/types/session.ts b/src/types/session.ts index 3c34b49d..d415ff9f 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -648,6 +648,15 @@ export interface SessionState { * again until the pane's own Enter is known. */ lastSubmitAt?: number; + /** + * Claude conversations this pane has been on, oldest first, current last. + * Written ONLY from a first-hand `UserPromptSubmit`/`Stop` hook payload — + * never from the history correlation — so it cannot record a sibling pane's + * conversation. Persisted because `/clear` is otherwise unrecoverable: once + * the pane moves on, the predecessor id exists nowhere else, and the last + * entry is what re-pins `claudeSessionId` past `start()`'s three resets. + */ + claudeSessionChain?: string[]; /** * PTY-exit circuit breaker tripped — respawn blocked until an explicit restart * (COD-118). Runtime-only: never restored on boot (fresh server = fresh breaker). diff --git a/src/web/route-helpers.ts b/src/web/route-helpers.ts index fb02fd61..0c676bff 100644 --- a/src/web/route-helpers.ts +++ b/src/web/route-helpers.ts @@ -422,6 +422,11 @@ export function sanitizeHookData(data: Record | null | undefine 'stop_hook_active', 'transcript_path', 'message', + // UserPromptSubmit identity fields. `prompt` is deliberately NOT here: the + // prompt text would land in the SSE broadcast, and Read My Mind already + // captures intent through transcript-watcher. + 'prompt_id', + 'source', ]; for (const key of allowedKeys) { diff --git a/src/web/routes/hook-event-routes.ts b/src/web/routes/hook-event-routes.ts index aa4f30e6..b69e4129 100644 --- a/src/web/routes/hook-event-routes.ts +++ b/src/web/routes/hook-event-routes.ts @@ -129,7 +129,29 @@ export function registerHookEventRoutes( if (data && typeof data.session_id === 'string' && data.session_id) { const session = ctx.sessions.get(sessionId); const prevClaudeSessionId = session?.claudeSessionId; - session?.adoptClaudeSessionId(data.session_id); + const prevChainLength = session?.claudeSessionChain.length ?? 0; + // FIRST-HAND: this payload came from the CLI process itself and reached us + // because the pane's own $CODEMAN_SESSION_ID addressed it. No cwd, no + // timestamp, nothing a sibling pane on the same folder could win — so the + // response viewer can stop guessing entirely (see + // resolveActiveClaudeSessionIdFromHistory). + session?.adoptClaudeSessionId(data.session_id, { firstHand: true }); + if (event === 'prompt_submitted') { + // Repairs `lastSubmitAt` for a pane driven straight from tmux: it was + // bumped only by input that flowed through Codeman's own write path, so + // it read 0 forever for those panes and every consumer of "when did this + // pane last submit" silently degraded. + session?.markPromptSubmitted(); + } + // Persist when the conversation actually moved: `/clear` emits no + // completion event, so without this the successor id is lost on restart + // and recovery falls back to the launch conversation. + if ( + session && + (session.claudeSessionId !== prevClaudeSessionId || session.claudeSessionChain.length !== prevChainLength) + ) { + ctx.persistSessionState(session); + } // Docker sessions: keep the case's resume seed following the LIVE // conversation (post-/clear id switches), so a container stop/reboot // relaunch resumes the right transcript. diff --git a/src/web/routes/session-routes.ts b/src/web/routes/session-routes.ts index 9c9e7b40..8af3a8a4 100644 --- a/src/web/routes/session-routes.ts +++ b/src/web/routes/session-routes.ts @@ -1860,8 +1860,17 @@ export function registerSessionRoutes( session: Session, projectsDir: string ): Promise { + // A pane whose conversation id came from its OWN hook needs no correlation: + // $CODEMAN_SESSION_ID (the pane's env) -> data.session_id (the CLI's own + // stdin JSON) is a first-hand binding that never looks at cwd, so it cannot + // be stolen by a sibling pane, a closed tab, or a bare `claude` in a + // terminal. Guessing can only be worse than the fact. This is also what + // closes the hole below for a pane driven straight from tmux: it never + // reaches `if (!submitAt)`. + if (session.claudeSessionIdIsFirstHand) return null; + const submitAt = session.lastSubmitAt; - if (!submitAt) return null; // never typed through Codeman — nothing to credit + if (!submitAt) return null; // no anchor at all — nothing to credit const cached = claudeHistoryPinCache.get(session.id); if (cached && cached.submitAt === submitAt) return cached.claudeSessionId; diff --git a/src/web/schemas.ts b/src/web/schemas.ts index a78b9def..003dd506 100644 --- a/src/web/schemas.ts +++ b/src/web/schemas.ts @@ -924,6 +924,9 @@ export const HookEventSchema = z.object({ 'stop', 'teammate_idle', 'task_completed', + // Claude Code's UserPromptSubmit: a first-hand report of the pane's live + // conversation id. Keep in step with HookEventType in types/api.ts. + 'prompt_submitted', // A turn STARTED. Unlike the others this one has no Claude Code hook behind // it: it is reported by the DeepSeek Harness status shim, and exists so a // dialog answered in the terminal resolves its Approvals Inbox item at once diff --git a/src/web/server.ts b/src/web/server.ts index 0cf318d6..2272aef5 100644 --- a/src/web/server.ts +++ b/src/web/server.ts @@ -2794,6 +2794,10 @@ export class WebServer extends EventEmitter { // the launch conversation until the user types again, even though // the re-attached CLI is on a post-`/clear` one. lastSubmitAt: savedState?.lastSubmitAt, + // Conversations this pane provably owned, oldest first. Its tail is + // the conversation the CLI was on when the server stopped, which is + // what a re-attach must point the viewer at instead of the launch id. + claudeSessionChain: savedState?.claudeSessionChain, // The pane's last output, previous run's value. Without it every // restart restamped all sessions "now" (constructor + the attach // repaint within the same second), flattening the home screens' diff --git a/test/hooks-config.test.ts b/test/hooks-config.test.ts index 9239bcbd..774774b3 100644 --- a/test/hooks-config.test.ts +++ b/test/hooks-config.test.ts @@ -42,6 +42,34 @@ describe('generateHooksConfig', () => { expect(config.hooks.Stop).toHaveLength(1); }); + it('reports the live conversation id on every prompt, with stdout discarded', () => { + const config = generateHooksConfig(); + expect(config.hooks.UserPromptSubmit).toBeInstanceOf(Array); + expect(config.hooks.UserPromptSubmit).toHaveLength(1); + const command = (config.hooks.UserPromptSubmit as Array<{ hooks: Array<{ command: string }> }>)[0].hooks[0].command; + expect(command).toContain('"event":"prompt_submitted"'); + expect(command).toContain('$CODEMAN_SESSION_ID'); + // ⚠️ Claude Code injects a UserPromptSubmit hook's stdout into the model's + // context ("Exit code 0 - stdout shown to Claude"), so without this the API + // envelope is pasted into the user's own prompt on every turn. Every other + // event's stdout is harmless (it feeds SSE). + // ⚠️ Assert curl's OWN flag, not a trailing redirect: the command already + // ends `… 2>/dev/null || true`, and in `pipeline || true >/dev/null` the + // shell binds the redirect to `true`, which never runs on the success path. + // A `endsWith('>/dev/null')` assertion passes on exactly that broken form. + expect(command).toContain('curl -sk -o /dev/null -X POST'); + expect(command.trimEnd().endsWith('>/dev/null')).toBe(false); + }); + + it("leaves every other hook event's command text byte-identical", () => { + // The opt-in discard exists so the five SSE-fed events do not change shape: + // rewriting their command churns every workspace's settings.local.json. + const config = generateHooksConfig(); + const stop = (config.hooks.Stop as Array<{ hooks: Array<{ command: string }> }>)[0].hooks[0].command; + expect(stop).toContain('curl -sk -X POST'); + expect(stop).not.toContain('-o /dev/null'); + }); + it('should guard subagent stops while their background work is active', () => { const config = generateHooksConfig(); const subagentHooks = config.hooks.SubagentStop as Array<{ @@ -324,6 +352,39 @@ describe('writeHooksConfig', () => { expect(serialized).not.toContain('CODEMAN_BACKGROUND_REWAKE_V1'); }); + it('heals a hooks block written before UserPromptSubmit existed', async () => { + const claudeDir = join(testDir, '.claude'); + const settingsPath = join(claudeDir, 'settings.local.json'); + mkdirSync(claudeDir, { recursive: true }); + // An otherwise-current block from the previous release: the pane would keep + // guessing its conversation from ~/.claude/history.jsonl forever. + const hooks = generateHooksConfig().hooks; + delete hooks.UserPromptSubmit; + writeFileSync(settingsPath, JSON.stringify({ hooks }, null, 2)); + + await refreshStaleCodemanHooks(testDir); + + const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8')); + expect(JSON.stringify(parsed.hooks.UserPromptSubmit)).toContain('prompt_submitted'); + }); + + it('leaves an already-current hooks block untouched', async () => { + // ⚠️ The staleness gate reads a JSON.stringify'd blob, so a marker written + // with surrounding quotes never matches and the gate is permanently false — + // which rewrites every workspace's settings.local.json on every Claude + // spawn instead of never. This asserts the no-op, which is the property a + // quoted needle silently breaks. + const claudeDir = join(testDir, '.claude'); + const settingsPath = join(claudeDir, 'settings.local.json'); + mkdirSync(claudeDir, { recursive: true }); + writeFileSync(settingsPath, JSON.stringify({ hooks: generateHooksConfig().hooks }, null, 2)); + const before = readFileSync(settingsPath, 'utf-8'); + + await refreshStaleCodemanHooks(testDir); + + expect(readFileSync(settingsPath, 'utf-8')).toBe(before); + }); + it('replaces the V2 background hook without duplicating it', async () => { const claudeDir = join(testDir, '.claude'); const settingsPath = join(claudeDir, 'settings.local.json'); diff --git a/test/mocks/mock-session.ts b/test/mocks/mock-session.ts index 18990a2e..b43b2fcd 100644 --- a/test/mocks/mock-session.ts +++ b/test/mocks/mock-session.ts @@ -29,6 +29,32 @@ export class MockSession extends EventEmitter { terminalBuffer: string = ''; /** Mirrors Session.lastSubmitAt — the response viewer credits history entries by it. */ lastSubmitAt: number = 0; + /** Mirrors Session.claudeSessionId — the conversation the viewer reads. */ + claudeSessionId: string | null = null; + /** Mirrors Session.claudeSessionIdIsFirstHand — set only by a hook adoption. */ + claudeSessionIdIsFirstHand: boolean = false; + /** Mirrors Session.claudeSessionChain — oldest first, current last. */ + claudeSessionChain: string[] = []; + + /** Mirrors Session.adoptClaudeSessionId, including the first-hand chain rule. */ + adoptClaudeSessionId(newId: string, options: { firstHand?: boolean } = {}): void { + if (!newId) return; + if (options.firstHand) { + this.claudeSessionIdIsFirstHand = true; + if (this.claudeSessionChain[this.claudeSessionChain.length - 1] !== newId) { + const existing = this.claudeSessionChain.indexOf(newId); + if (existing !== -1) this.claudeSessionChain.splice(existing, 1); + this.claudeSessionChain.push(newId); + } + } + if (newId === this.claudeSessionId) return; + this.claudeSessionId = newId; + } + + /** Mirrors Session.markPromptSubmitted. */ + markPromptSubmitted(): void { + this.lastSubmitAt = Date.now(); + } private _muxName: string | null = null; diff --git a/test/routes/hook-event-routes.test.ts b/test/routes/hook-event-routes.test.ts index 279d2c3a..a553ea0c 100644 --- a/test/routes/hook-event-routes.test.ts +++ b/test/routes/hook-event-routes.test.ts @@ -115,6 +115,75 @@ describe('hook-event-routes', () => { ); }); + /** + * The pane's live conversation id, reported by the CLI process itself. This + * is what lets the response viewer stop guessing from ~/.claude/history.jsonl + * — a guess that could never run at all for a pane the user drives by + * attaching to tmux, because `lastSubmitAt` only ever saw Codeman's own + * write path. + */ + it('adopts the conversation id first-hand from a prompt_submitted hook', async () => { + const session = harness.ctx._session; + const before = session.lastSubmitAt; + + const res = await harness.app.inject({ + method: 'POST', + url: '/api/hook-event', + payload: { + event: 'prompt_submitted', + sessionId: harness.ctx._sessionId, + data: { hook_event_name: 'UserPromptSubmit', session_id: 'conv-1', source: 'user' }, + }, + }); + + expect(res.statusCode).toBe(200); + expect(session.claudeSessionId).toBe('conv-1'); + expect(session.claudeSessionIdIsFirstHand).toBe(true); + expect(session.claudeSessionChain).toEqual(['conv-1']); + expect(session.lastSubmitAt).toBeGreaterThan(before); + expect(harness.ctx.persistSessionState).toHaveBeenCalledWith(session); + }); + + it('records a /clear successor in the chain and persists it, without duplicating a repeat', async () => { + const session = harness.ctx._session; + const submit = async (conversationId: string) => + harness.app.inject({ + method: 'POST', + url: '/api/hook-event', + payload: { + event: 'prompt_submitted', + sessionId: harness.ctx._sessionId, + data: { hook_event_name: 'UserPromptSubmit', session_id: conversationId }, + }, + }); + + await submit('conv-1'); + await submit('conv-1'); // every prompt in a conversation reports the same id + await submit('conv-2'); // the user ran /clear + + expect(session.claudeSessionChain).toEqual(['conv-1', 'conv-2']); + expect(session.claudeSessionId).toBe('conv-2'); + // `/clear` emits no completion event, so the successor is lost on restart + // unless the hook itself persists it. + expect(harness.ctx.persistSessionState).toHaveBeenCalledTimes(2); + }); + + it('does not leak the prompt text into the broadcast', async () => { + await harness.app.inject({ + method: 'POST', + url: '/api/hook-event', + payload: { + event: 'prompt_submitted', + sessionId: harness.ctx._sessionId, + data: { hook_event_name: 'UserPromptSubmit', session_id: 'conv-1', prompt: 'my secret prompt' }, + }, + }); + + const broadcast = JSON.stringify(harness.ctx.broadcast.mock.calls); + expect(broadcast).not.toContain('my secret prompt'); + expect(broadcast).toContain('conv-1'); + }); + it('returns 404 for unknown session', async () => { const res = await harness.app.inject({ method: 'POST', diff --git a/test/routes/session-routes-claude-last-response.test.ts b/test/routes/session-routes-claude-last-response.test.ts index f9cd8bc2..7ac29f7c 100644 --- a/test/routes/session-routes-claude-last-response.test.ts +++ b/test/routes/session-routes-claude-last-response.test.ts @@ -232,16 +232,18 @@ describe('GET /api/sessions/:id/last-response (claude conversation pinning)', () } /** Replaces the pre-seeded mock session with a Claude pane in WORKDIR. */ - function addPane(id: string, conversationId: string, lastSubmitAt: number) { + function addPane(id: string, conversationId: string, lastSubmitAt: number, firstHand = false) { const base = harness.ctx._session; const pane = Object.create(Object.getPrototypeOf(base)) as typeof base & { claudeSessionId: string; lastSubmitAt: number; + claudeSessionIdIsFirstHand: boolean; adoptClaudeSessionId: ReturnType; }; Object.assign(pane, base, { id, mode: 'claude', workingDir: WORKDIR, docker: undefined }); pane.claudeSessionId = conversationId; pane.lastSubmitAt = lastSubmitAt; + pane.claudeSessionIdIsFirstHand = firstHand; pane.adoptClaudeSessionId = vi.fn((newId: string) => { pane.claudeSessionId = newId; }); @@ -286,6 +288,41 @@ describe('GET /api/sessions/:id/last-response (claude conversation pinning)', () expect(pane.adoptClaudeSessionId).not.toHaveBeenCalled(); }); + /** + * The whole point of the UserPromptSubmit hook: a pane driven by attaching to + * tmux directly never bumps `lastSubmitAt` (only Codeman's own write path + * does), so before this the correlation could not run at all for it and the + * viewer stayed pinned to the launch conversation for the pane's whole life. + */ + it("trusts the pane's own hook over any history correlation", async () => { + const pane = addPane('pane-1', 'hook-conversation', 0, true); + writeTranscript('hook-conversation', 'the answer this pane gave', NOW - 60_000); + // A newer, closer entry that the correlation would otherwise have claimed. + writeTranscript('decoy-conversation', 'a stranger answer', NOW); + writeHistory([{ sessionId: 'decoy-conversation', timestamp: NOW }]); + + expect(await getLastResponse('pane-1')).toEqual({ + text: 'the answer this pane gave', + timestamp: expect.any(String), + }); + expect(pane.adoptClaudeSessionId).not.toHaveBeenCalled(); + }); + + it('never lets a correlation override a first-hand id, even a well-anchored one', async () => { + // Same shape as the /clear-following test above, which DOES adopt — the only + // difference is that this pane's id came from its own hook. + const pane = addPane('pane-1', 'before-clear', NOW, true); + writeTranscript('before-clear', 'answer before clear', NOW - 60_000); + writeTranscript('after-clear', 'answer after clear', NOW + 500); + writeHistory([{ sessionId: 'after-clear', timestamp: NOW + 120 }]); + + expect(await getLastResponse('pane-1')).toEqual({ + text: 'answer before clear', + timestamp: expect.any(String), + }); + expect(pane.adoptClaudeSessionId).not.toHaveBeenCalled(); + }); + it('credits a shared-cwd entry to the pane whose Enter is closest to it', async () => { const near = addPane('pane-near', 'near-conversation', NOW); const far = addPane('pane-far', 'far-conversation', NOW - 4_000); diff --git a/test/session-claude-conversation-chain.test.ts b/test/session-claude-conversation-chain.test.ts new file mode 100644 index 00000000..49d00060 --- /dev/null +++ b/test/session-claude-conversation-chain.test.ts @@ -0,0 +1,118 @@ +/** + * @fileoverview Session.claudeSessionChain — the record of which Claude + * conversations a pane has actually been on. + * + * Which conversation the response viewer reads is `Session.claudeSessionId`, + * and `start()` reassigns it to the launch id at THREE separate points. That is + * correct for a fresh pane and a lie for a re-attached one: a mux session that + * survived a Codeman restart never stopped, so the CLI may have `/clear`ed hours + * ago and moved to a conversation the launch id knows nothing about. The chain + * is what carries that across the restart, and its tail must therefore outrank + * the launch id on the restored path only. + * + * Two properties are pinned here because both were broken in ways nothing else + * caught: + * + * 1. **Only a first-hand adoption extends the chain.** The id has to come from + * the CLI's own hook payload, delivered under the pane's `$CODEMAN_SESSION_ID`. + * A history-correlated guess writing into this record would make the + * "showed a stranger's conversation" bug permanent instead of transient. + * 2. **A restored conversation survives every reset point.** The mux branch and + * the unconditional "third reset point" after it both reassign the field, so + * patching only the first leaves the restore silently undone. + * + * Port: N/A + */ +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { describe, expect, it } from 'vitest'; +import { Session } from '../src/session.js'; + +describe('Session claude conversation chain', () => { + it('extends the chain only for a first-hand adoption', () => { + const session = new Session({ workingDir: '/tmp', mode: 'claude' }); + + // A correlated guess: adopted for display, but never recorded. + session.adoptClaudeSessionId('guessed-conversation'); + expect(session.claudeSessionId).toBe('guessed-conversation'); + expect(session.claudeSessionChain).toEqual([]); + expect(session.claudeSessionIdIsFirstHand).toBe(false); + + // The CLI's own hook: recorded. + session.adoptClaudeSessionId('hook-conversation', { firstHand: true }); + expect(session.claudeSessionChain).toEqual(['hook-conversation']); + expect(session.claudeSessionIdIsFirstHand).toBe(true); + }); + + it('records a /clear successor once, however many prompts report it', () => { + const session = new Session({ workingDir: '/tmp', mode: 'claude' }); + + session.adoptClaudeSessionId('conv-1', { firstHand: true }); + session.adoptClaudeSessionId('conv-1', { firstHand: true }); // every prompt reports the same id + session.adoptClaudeSessionId('conv-2', { firstHand: true }); // the user ran /clear + + expect(session.claudeSessionChain).toEqual(['conv-1', 'conv-2']); + expect(session.claudeSessionId).toBe('conv-2'); + }); + + it('moves a resumed conversation to the tail instead of duplicating it', () => { + const session = new Session({ workingDir: '/tmp', mode: 'claude' }); + + session.adoptClaudeSessionId('conv-1', { firstHand: true }); + session.adoptClaudeSessionId('conv-2', { firstHand: true }); + session.adoptClaudeSessionId('conv-1', { firstHand: true }); // /resume back + + expect(session.claudeSessionChain).toEqual(['conv-2', 'conv-1']); + }); + + it('round-trips the chain through toState and re-pins the conversation on restore', () => { + const original = new Session({ workingDir: '/tmp', mode: 'claude' }); + original.adoptClaudeSessionId('conv-1', { firstHand: true }); + original.adoptClaudeSessionId('conv-2', { firstHand: true }); + + const state = original.toState() as { claudeSessionChain?: string[] }; + expect(state.claudeSessionChain).toEqual(['conv-1', 'conv-2']); + + // Boot recovery rebuilds the pane from that state. The launch id would point + // the viewer at the pre-/clear conversation; the chain's tail corrects it. + const restored = new Session({ + workingDir: '/tmp', + mode: 'claude', + id: original.id, + claudeSessionChain: state.claudeSessionChain, + }); + expect(restored.claudeSessionId).toBe('conv-2'); + // ⚠️ NOT restored: a persisted claim is not a fact. The pane re-earns the + // guess-free path from its next hook. + expect(restored.claudeSessionIdIsFirstHand).toBe(false); + }); + + it('omits the chain from toState when the pane never moved conversation', () => { + const session = new Session({ workingDir: '/tmp', mode: 'claude' }); + expect((session.toState() as { claudeSessionChain?: string[] }).claudeSessionChain).toBeUndefined(); + }); + + it('applies the restored conversation at EVERY reset point in start()', () => { + // ⚠️ Structural pin, not a behavioural one: exercising start() needs a real + // PTY and mux. start() reassigns _claudeSessionId at three points, and the + // last one runs unconditionally AFTER the mux branch — so patching only the + // mux branch leaves the restore silently undone, which is what shipped + // 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 + ); + expect(fallbackAssignments).not.toBeNull(); + expect(fallbackAssignments!.length).toBeGreaterThanOrEqual(2); + for (const assignment of fallbackAssignments!) { + expect(assignment).toContain('restoredConversation ||'); + } + }); + + it('leaves a fresh pane on its launch id', () => { + const session = new Session({ workingDir: '/tmp', mode: 'claude' }); + expect(session.claudeSessionId).toBe(session.id); + expect(session.claudeSessionChain).toEqual([]); + }); +}); From 7e4914d991ea864d7dfbefe03f042380d02981c4 Mon Sep 17 00:00:00 2001 From: Michael Tiller Date: Fri, 4 Sep 2026 12:10:20 -0400 Subject: [PATCH 18/26] feat(web): support a reverse-proxy base URL (--base-url / CODEMAN_BASE_URL) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codeman can now be mounted under a sub-path behind a reverse proxy that forwards the prefix unchanged (e.g. https://host/codeman/). Default is `/` (root), which is byte-identical to the historical behavior. Design — few choke points, mirrored ingress/egress: - src/config/base-path.ts: pure single-source normalize/validate/join/strip. - Server ingress: stripBasePath() inside Fastify rewriteUrl, so routes stay declared prefix-agnostic; un-prefixed requests (hooks, health, docker bridge hitting the raw port) pass through unchanged. - Server egress: one onSend hook prepends the base to root-absolute Location headers (covers all redirects). - HTML: renderIndexHtml points at the mount and injects window.__CODEMAN_BASE__ — ONLY when a base is set (inert at root). - Frontend runtime URLs: CodemanBase.url() route builder in constants.js, applied transparently by a fetch wrapper and explicitly at the EventSource/WebSocket/window.open/-src sites. - sw.js derives its base from self.location; manifest uses relative start_url/scope. - Web-tab proxy: proxyPrefixFor(cap, basePath) is the single base-aware root that cascades to the injected , HTML/attr rewrites, runtimeUrlShim, Set-Cookie Path and Location; capabilityFromReferer strips the base off the browser Referer, while the ingress parsers stay base-agnostic (rewriteUrl already stripped it). --base-url rides the daemon relaunch (buildWebArgs) and the service unit (resolveServicePlan). constants.js is guarded against a missing `window` for isolated unit-test contexts. Tests: test/base-path.test.ts (pure helpers), base-path coverage in webview-proxy/render-index-html/daemon-control; CodemanBase stubbed in the vm-isolated panels-ui test contexts. Docs: Remote-Access.md (sub-path section + nginx example), security-architecture.md env table, CLAUDE.md pattern. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01XUkPBxbumnct6qSrx4JDju --- CLAUDE.md | 3 + docs/security-architecture.md | 1 + docs/wiki/Remote-Access.md | 42 +++++++++ src/cli.ts | 26 +++++- src/config/base-path.ts | 101 +++++++++++++++++++++ src/daemon-control.ts | 3 + src/web/middleware/auth.ts | 28 +++--- src/web/public/app.js | 12 ++- src/web/public/constants.js | 57 ++++++++++++ src/web/public/keyboard-accessory.js | 2 +- src/web/public/manifest.json | 3 +- src/web/public/notification-manager.js | 2 +- src/web/public/panels-ui.js | 71 ++++++++------- src/web/public/session-ui.js | 2 +- src/web/public/settings-ui.js | 5 +- src/web/public/sw.js | 19 ++-- src/web/public/voice-input.js | 2 +- src/web/public/webview-tabs.js | 4 +- src/web/routes/webview-routes.ts | 58 +++++++----- src/web/server.ts | 79 +++++++++++++--- src/web/webview-proxy.ts | 44 +++++---- test/base-path.test.ts | 119 +++++++++++++++++++++++++ test/daemon-control.test.ts | 10 +++ test/file-browser-search.test.ts | 4 + test/file-preview-detach.test.ts | 2 + test/file-preview-media.test.ts | 2 + test/render-index-html.test.ts | 39 ++++++++ test/webview-proxy.test.ts | 36 ++++++++ 28 files changed, 664 insertions(+), 112 deletions(-) create mode 100644 src/config/base-path.ts create mode 100644 test/base-path.test.ts diff --git a/CLAUDE.md b/CLAUDE.md index a2fdb8de..24b31634 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -99,6 +99,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph | Dev with TLS | `npx tsx src/index.ts web --https` | | Override window title hostname | `npx tsx src/index.ts web --title-hostname ` (default: `os.hostname()` — `codeman:` is used for tab title, title-flash, and OS desktop notification prefix) | | Bind a non-loopback host | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` | +| Mount under a reverse-proxy sub-path | `npx tsx src/index.ts web --base-url /codeman` (env `CODEMAN_BASE_URL`; default `/`). Normalized in `src/config/base-path.ts` (`''` = root). See Reverse-proxy base path below + `docs/wiki/Remote-Access.md` | | Continuous typecheck | `tsc --noEmit --watch` | | Watch-mode test | `npm run test:watch -- test/.test.ts` (runs the CI gate's config; pass a file to narrow it) | | Test coverage | `npm run test:coverage` | @@ -250,6 +251,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **Self-update** (App Settings → System → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. ⚠️ **The Compose deployment is the one supervisor that does NOT outlive the restart**: there the restart IS the container exiting (`restart: unless-stopped` relaunches it), which kills the script too — safe only because the terminal `restarting` marker is written BEFORE the kill, so nothing may be appended after it. Two config facts make it work at all and both are load-bearing: the repo is a HOST BIND MOUNT over `/opt/codeman` (a pull into the baked image copy would land in the writable layer and be silently discarded by the next `up`), and the runtime image keeps devDependencies + a build toolchain (`npm run build` is tsc+esbuild, and node-pty has no Linux prebuild), which is why `npm prune --omit=dev` is gone and the updater passes `--include=dev` against `NODE_ENV=production`. ⚠️ An in-place container update applies CODE ONLY — a restart reuses the existing image and config — so `evaluateEnvironmentGate()` REFUSES a release that changes `server.Dockerfile`/`docker-compose.yaml` (sha256 vs the baseline `Start-Codeman.sh` writes to `docker-env-applied.json` on every start) or adds `.env.example` keys the user's `.env` lacks, and refuses when the restart policy would not bring the container back. That third check exists because **Compose resolves an unset `${VAR}` to the EMPTY STRING and starts anyway**, so a new required setting otherwise arrives as a silently blank env var. Every unknown fails OPEN in the gate (no baseline, unreadable `.env`, no socket): failing closed would permanently block containers created before the fingerprint file existed. ⚠️ The KILL does not: the server exits only when `--restart-by-exit 1` was passed, i.e. the Compose file declared `CODEMAN_RESTART_BY_EXIT=1` (set ONLY there, since that file is what sets `restart: unless-stopped`; the image ENV deliberately does not) or the daemon reported an auto-restart policy; otherwise the build lands as `completed-needs-manual-restart`, because exiting blind takes a `docker run` container with no restart policy down with no UI left to recover it. The gate is re-evaluated on `POST /api/system/update`, so hiding the button is UX, not the control. ⚠️ The four global agent CLIs in `server.Dockerfile` are PINNED on purpose — unpinned, a user's CLI versions are a function of when their image was built rather than of any commit, which is the one environment change no diff-derived gate can see; pinning turns it into a Dockerfile change the gate already catches. `test/docker-compose-env-parity.test.ts` is the merge-side guard (every compose `${VAR}` ↔ an `.env.example` entry). → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update) +**Reverse-proxy base path** (`--base-url` / `CODEMAN_BASE_URL`, default `/`; `src/config/base-path.ts` is the pure single-source, normalized to `''` for root or `/foo`): lets Codeman be mounted under a sub-path behind a proxy that **forwards the prefix unchanged** (does NOT strip it). Deliberately few choke points, mirrored ingress/egress: **(server ingress)** `stripBasePath()` runs inside Fastify's `rewriteUrl` so ALL routes stay declared prefix-agnostic (`/api/...`, `/ws/...`) — and a request arriving WITHOUT the prefix (hooks, health checks, docker bridge, all hitting the raw port) is left untouched, so the server answers at both; **(server egress)** one `onSend` hook prepends the base to every root-absolute `Location` header, covering all redirects; **(HTML)** `renderIndexHtml` rewrites the shipped `` to the mount and injects `window.__CODEMAN_BASE__` — the template's asset refs are all RELATIVE so `` handles them for free; **(frontend runtime URLs)** root-absolute URLs ignore ``, so `CodemanBase.url()` (constants.js) is the route builder, applied transparently by a `fetch` wrapper and explicitly at the few EventSource/WebSocket/`window.open`/``-src sites; **(sw.js/manifest)** the worker derives its base from `self.location`, the manifest uses relative `start_url`/`scope`; **(web-tab proxy)** `proxyPrefixFor(cap, basePath)` is the single base-aware root that cascades to the injected ``, root-absolute HTML rewrites, the `runtimeUrlShim`, `Set-Cookie` Path and `Location` rebasing — while the INGRESS parsers (`capabilityFromProxyPath`, `resolveUpstreamUrl`) stay base-agnostic because `rewriteUrl` strips the prefix before routing, and `capabilityFromReferer(referer, basePath)` strips it from the browser-supplied Referer. ⚠️ `--base-url` rides the daemon relaunch via `buildWebArgs` and the service unit via `resolveServicePlan`. Pure helpers unit-tested in `test/base-path.test.ts` + `test/webview-proxy.test.ts`; HTML injection in `test/render-index-html.test.ts`. + **Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments) **File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND the response viewer's `_linkifyFilePaths()`; a fresh instance per call, since `lastIndex` is per-object state. The chat linkifier walks TEXT NODES with DOM APIs (the source is model output; never rebuild sanitized markup as a string) and skips subtrees already inside an ``. ⚠️ **An out-of-workspace path is served through the ATTACHMENT routes, not the file routes** — `file-content`/`file-raw` are workspace-confined and 404 exactly the paths agents print most (a `/tmp` capture, Claude's scratchpad), so `openFilePreview()` registers such a path via `POST /api/sessions/:id/attachments` with **`notify: false`** (suppresses only the `attachment:detected` broadcast — same guard, same routes; without it every click also popped a card announcing the file already on screen) and renders by id. The click is an explicit action on the explicit, Origin-guarded route, which is what distinguishes it from the force-confined magic-link scanner. ⚠️ **Media extensions are single-sourced** (`VIDEO_ATTACHMENT_EXTENSIONS`/`AUDIO_ATTACHMENT_EXTENSIONS` in `attachment-registry.ts`, imported by `file-content`'s classification) so a clip plays the same in or out of the workspace; a player needs all THREE of allowlist + a real `MIME_TYPES` entry (octet-stream renders a dead player) + the range-aware body. ⚠️ **`TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS`** (never a second list): if the viewer would edit it inside the workspace, it can be read outside. Widening READ must never widen RUN, so `html`/`htm` joined `svg` in `serveRawFile`'s download-only branch, other text goes out as inert `text/plain`+`nosniff`, and `~/.codeman*/state.json` joined `isSensitivePath` (it persists `envOverrides`, which can hold `GEMINI_API_KEY`). ⚠️ The terminal sends an **out-of-workspace** path to the preview instead of the log viewer (that one spawns `tail -f` and reaches only workspace + `/var/log` + `~/logs`); in-workspace text keeps the tail viewer and `file-stream-manager`'s allowlist is untouched. The image-watcher keeps its own narrow detection list, so none of this cards every file an agent writes. → [architecture-invariants#file-path-links-terminal--response-viewer](docs/architecture-invariants.md#file-path-links-terminal--response-viewer) diff --git a/docs/security-architecture.md b/docs/security-architecture.md index 5f2116ce..719caac3 100644 --- a/docs/security-architecture.md +++ b/docs/security-architecture.md @@ -529,6 +529,7 @@ A saved dashboard URL renders as a tab, served through Codeman's own origin at ` | `CODEMAN_PASSWORD` (+ `CODEMAN_USERNAME`) | Enable HTTP Basic auth | | `--host` / `CODEMAN_HOST` | Bind host (default `127.0.0.1`) | | `CODEMAN_ALLOWED_HOSTS` | Extra `Host`/`Origin` allowlist entries for reverse proxies (comma‑separated; exact host, or leading‑dot `.suffix` for subdomains) — see §3 | +| `--base-url` / `CODEMAN_BASE_URL` | Sub‑path prefix Codeman is mounted under behind a reverse proxy, e.g. `/codeman` (default `/`); the proxy must forward the prefix unchanged. Independent of `CODEMAN_ALLOWED_HOSTS` | | `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK` | Acknowledge an unauthenticated non‑loopback bind (downgrades the warning) | | `--https` | Enable TLS (adds HSTS) | | `CODEMAN_INSTANCE` | Scope tmux socket + data dir for isolation | diff --git a/docs/wiki/Remote-Access.md b/docs/wiki/Remote-Access.md index e7e810c1..1a6a9e10 100644 --- a/docs/wiki/Remote-Access.md +++ b/docs/wiki/Remote-Access.md @@ -167,6 +167,47 @@ and is not one. Also make sure the proxy forwards WebSocket upgrades. The terminal is a WebSocket, and the upgrade runs the same Host and Origin checks, closing with code `4003` on failure. +### Mounting under a sub-path + +By default Codeman assumes it is served at the origin root (`/`). To mount it under a +sub-path — e.g. `https://example.com/codeman/` — start it with `--base-url` (or the +`CODEMAN_BASE_URL` env var): + +```bash +codeman web --base-url /codeman +# or +CODEMAN_BASE_URL=/codeman codeman web +``` + +The value is a plain path prefix; `/` (the default) means "mounted at the root". With a +prefix set, Codeman emits every URL — the HTML shell and its assets, API/SSE/WebSocket +calls, redirects, the PWA manifest and the service worker — under that prefix, so a browser +loading `https://example.com/codeman/` stays inside the mount. + +**Forward the prefix unchanged — do NOT strip it.** Codeman expects the proxy to pass the +full path (including `/codeman/`) straight through. A minimal nginx block: + +```nginx +location /codeman/ { + proxy_pass http://127.0.0.1:3000; # note: no trailing slash — keep the /codeman/ prefix + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; # WebSocket + proxy_set_header Connection "upgrade"; +} +``` + +Notes and current limits: + +- The prefix must still be paired with `CODEMAN_ALLOWED_HOSTS` for your domain, exactly as + above — the two are independent. +- Health checks, Claude Code hooks and the docker bridge connect to the raw port directly + (bypassing the proxy), so Codeman also keeps answering at the un-prefixed paths on the port + itself. Nothing about those flows changes. +- **Web-tab (dashboard) proxying** is base-path aware: proxied dashboards have their injected + `` tag, root-absolute asset rewrites, runtime `fetch`/XHR shim, `Set-Cookie` paths, and + redirects all rebased onto the mount, so they load the same under `--base-url` as at the root. + ## Session cookies and rate limits The first request prompts for HTTP Basic credentials. On success the server issues an opaque @@ -198,6 +239,7 @@ for the full guide. | Symptom | Cause and fix | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `403 host not allowed` | Your domain is not in the allowlist. Set `CODEMAN_ALLOWED_HOSTS`. | +| Assets 404 / blank page under a sub-path | Start Codeman with `--base-url /` and have the proxy forward the prefix unchanged (don't strip it). | | Phone shows the login page but the terminal never connects | The proxy is not forwarding WebSocket upgrades. | | Browser warns about the certificate | Expected with `--https` and its self-signed certificate. Tailscale gives you a real one instead. | | LAN IP does not respond, but a tunnel to the same box works | The server is bound to loopback. That is the default. A tunnel reaches it; a LAN browser cannot. | diff --git a/src/cli.ts b/src/cli.ts index 874d0d22..2da7fac7 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -16,6 +16,7 @@ import { isAbsolute, join } from 'node:path'; import { homedir } from 'node:os'; import { dataPath } from './config/instance.js'; import { casePath } from './config/cases-dir.js'; +import { assertValidBasePath } from './config/base-path.js'; import { installAgentSkillInto, removeAgentSkillFrom, type AgentSkillApplyResult } from './hooks-config.js'; import { getSessionManager } from './session-manager.js'; import { getTaskQueue } from './task-queue.js'; @@ -843,6 +844,11 @@ function addWebLaunchOptions(cmd: Command): Command { .option('-H, --host ', 'Host to bind to', process.env.CODEMAN_HOST || '127.0.0.1') .option('-p, --port ', 'Port to listen on (env: CODEMAN_PORT)', process.env.CODEMAN_PORT || '3000') .option('--https', 'Enable HTTPS with self-signed certificate (only needed for remote access, not localhost)') + .option( + '--base-url ', + 'Sub-path Codeman is mounted under behind a reverse proxy, e.g. /codeman (env: CODEMAN_BASE_URL)', + process.env.CODEMAN_BASE_URL || '/' + ) .option('--title-hostname ', 'Override the hostname shown in the browser title') .option( '--allow-unauthenticated-network', @@ -859,6 +865,7 @@ function toWebLaunchOptions(options: { host: string; port: string; https?: boolean; + baseUrl?: string; titleHostname?: string; allowUnauthenticatedNetwork?: boolean; multiuser?: boolean; @@ -868,10 +875,18 @@ function toWebLaunchOptions(options: { console.error(palette.err(`✗ Invalid port: ${options.port}`)); process.exit(1); } + let basePath: string; + try { + basePath = assertValidBasePath(options.baseUrl); + } catch (err) { + console.error(palette.err(`✗ ${err instanceof Error ? err.message : String(err)}`)); + process.exit(1); + } return { host: options.host, port, https: !!options.https, + basePath, titleHostname: options.titleHostname, allowUnauthenticatedNetwork: !!options.allowUnauthenticatedNetwork, multiuser: !!options.multiuser, @@ -961,14 +976,21 @@ webCmd.action(async (options) => { const https = launch.https; const titleHostname = options.titleHostname; const allowUnauthenticatedNetwork = launch.allowUnauthenticatedNetwork ?? false; + const basePath = launch.basePath ?? ''; + // Single source of truth for subsystems that read it directly (e.g. renderers). + if (basePath) process.env.CODEMAN_BASE_URL = basePath; const displayHost = host === '0.0.0.0' ? 'localhost' : host; - console.log(palette.info(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`)); + console.log( + palette.info( + `Starting Codeman web interface on ${displayHost}:${port}${basePath ? basePath + '/' : ''}${https ? ' (HTTPS)' : ''}...` + ) + ); try { // The server prints its own "running at" line (it also covers the daemon and // service launch paths), so this one used to be a duplicate of it. - const server = await startWebServer(port, https, false, host, titleHostname, allowUnauthenticatedNetwork); + const server = await startWebServer(port, https, false, host, titleHostname, allowUnauthenticatedNetwork, basePath); if (https) { console.log(palette.warn(' Note: Accept the self-signed certificate in your browser on first visit')); } diff --git a/src/config/base-path.ts b/src/config/base-path.ts new file mode 100644 index 00000000..0ac9d1ed --- /dev/null +++ b/src/config/base-path.ts @@ -0,0 +1,101 @@ +/** + * @fileoverview Reverse-proxy base-path support — the single source of truth for + * the URL prefix Codeman is mounted under. + * + * When Codeman runs behind a reverse proxy at a sub-path (e.g. `/codeman/`), the + * proxy forwards the FULL request path INCLUDING that prefix (it does not strip + * it). Every URL the server emits to the browser (the HTML shell, redirects, + * the manifest/service-worker) and every URL the browser builds (fetch/SSE/WS) + * must therefore carry the prefix too. + * + * This module normalizes the operator-supplied value (`--base-url` / the + * `CODEMAN_BASE_URL` env var) into ONE canonical form used everywhere: + * - `''` — mounted at the origin root (the default, `/`) + * - `/foo` — mounted at a sub-path (leading slash, NO trailing slash) + * + * Keeping the normalized form free of a trailing slash means `basePath + '/api/x'` + * and `basePath + '/'` both compose cleanly, and `''` degrades to the historical + * root behavior with no special-casing at the call sites. + * + * @module config/base-path + */ + +/** + * A normalized base path is either empty (root) or one-or-more `/segment` + * groups, where a segment is a conservative, proxy-safe subset of path + * characters. This deliberately excludes anything that could change routing + * meaning (`?`, `#`, `:`, whitespace, `%`) so the prefix is a plain path. + */ +const VALID_BASE_PATH = /^(?:\/[A-Za-z0-9._~-]+)+$/; + +/** + * Normalize an operator-supplied base path into the canonical form. + * + * Accepts loose input (`codeman`, `/codeman`, `/codeman/`, `//codeman//`) and + * returns `''` for root or `/codeman` otherwise. Does NOT validate the character + * set — call {@link assertValidBasePath} (or {@link isValidBasePath}) for that. + */ +export function normalizeBasePath(input: string | undefined | null): string { + if (input === undefined || input === null) return ''; + let p = String(input).trim(); + if (p === '' || p === '/') return ''; + if (!p.startsWith('/')) p = '/' + p; + p = p.replace(/\/{2,}/g, '/'); // collapse duplicate slashes + p = p.replace(/\/+$/, ''); // drop trailing slash(es) + return p; +} + +/** True if `normalized` is a legal canonical base path (`''` or `/seg[/seg...]`). */ +export function isValidBasePath(normalized: string): boolean { + return normalized === '' || VALID_BASE_PATH.test(normalized); +} + +/** + * Normalize AND validate, throwing a human-readable error on bad input. Used by + * the CLI so a typo (`--base-url /a b`, `--base-url ?x`) fails loudly at startup + * instead of silently producing broken URLs. + */ +export function assertValidBasePath(input: string | undefined | null): string { + const normalized = normalizeBasePath(input); + if (!isValidBasePath(normalized)) { + throw new Error( + `Invalid --base-url ${JSON.stringify(input)}: use a plain path like "/codeman" ` + + `(letters, digits, and ._~- in each segment).` + ); + } + return normalized; +} + +/** + * Join the base path onto a root-absolute application path (`/api/x` → `/base/api/x`). + * + * Leaves alone anything that is not a root-absolute app path: empty strings, + * protocol-relative (`//host`) and absolute URLs (`http://`, `ws://`, `data:`), + * fragments/queries, and paths already carrying the prefix. This is the one + * function the whole codebase routes URL construction through. + */ +export function joinBasePath(basePath: string, path: string): string { + if (!basePath) return path; + if (typeof path !== 'string' || path.length === 0) return path; + if (!path.startsWith('/')) return path; // relative / fragment / query — resolved against + if (path.startsWith('//')) return path; // protocol-relative + if (path === basePath || path.startsWith(basePath + '/') || path.startsWith(basePath + '?')) { + return path; // already prefixed + } + return basePath + path; +} + +/** + * Strip the base path off an INCOMING request URL so internal routing stays + * prefix-agnostic. Requests that arrive WITHOUT the prefix (health checks, + * hooks, the docker bridge — all of which hit the raw port, bypassing the proxy) + * are returned unchanged, so the server answers at both `/api/x` and + * `/base/api/x`. + */ +export function stripBasePath(basePath: string, url: string): string { + if (!basePath) return url; + if (url === basePath) return '/'; + if (url.startsWith(basePath + '/')) return url.slice(basePath.length); + if (url.startsWith(basePath + '?')) return '/' + url.slice(basePath.length); + return url; +} diff --git a/src/daemon-control.ts b/src/daemon-control.ts index 52a6ac00..cb09f3d7 100644 --- a/src/daemon-control.ts +++ b/src/daemon-control.ts @@ -45,6 +45,8 @@ export interface WebLaunchOptions { host: string; port: number; https: boolean; + /** Reverse-proxy sub-path prefix (normalized: '' for root, or '/foo'). */ + basePath?: string; titleHostname?: string; allowUnauthenticatedNetwork?: boolean; multiuser?: boolean; @@ -87,6 +89,7 @@ export interface DaemonStatus { export function buildWebArgs(options: WebLaunchOptions): string[] { const args = ['web', '--host', options.host, '--port', String(options.port)]; if (options.https) args.push('--https'); + if (options.basePath) args.push('--base-url', options.basePath); if (options.titleHostname) args.push('--title-hostname', options.titleHostname); if (options.allowUnauthenticatedNetwork) args.push('--allow-unauthenticated-network'); if (options.multiuser) args.push('--multiuser'); diff --git a/src/web/middleware/auth.ts b/src/web/middleware/auth.ts index af0d0cfe..adbd9461 100644 --- a/src/web/middleware/auth.ts +++ b/src/web/middleware/auth.ts @@ -142,7 +142,9 @@ function isPasswordChangeExempt(req: FastifyRequest): boolean { * match the prefix at all. The Host allowlist is NOT bypassed, so DNS-rebinding * protection still applies to these requests. */ -function hasValidWebviewCapability(req: FastifyRequest): boolean { +function hasValidWebviewCapability(req: FastifyRequest, basePath = ''): boolean { + // req.url is already base-stripped by the server's rewriteUrl, so the path form + // needs no base; the Referer form below is browser-supplied and does. const url = (req.url ?? '').split('?')[0]; const fromPath = capabilityFromProxyPath(url); @@ -167,7 +169,10 @@ function hasValidWebviewCapability(req: FastifyRequest): boolean { // class the 404 relay could never rescue. See matchesRegisteredRoute. if (matchesRegisteredRoute(req, url)) return false; - const fromReferer = capabilityFromReferer(typeof req.headers.referer === 'string' ? req.headers.referer : undefined); + const fromReferer = capabilityFromReferer( + typeof req.headers.referer === 'string' ? req.headers.referer : undefined, + basePath + ); return !!fromReferer && webviewCapabilities.resolve(fromReferer) !== undefined; } @@ -210,7 +215,7 @@ function matchesRegisteredRoute(req: FastifyRequest, url: string): boolean { * * @returns AuthState for lifecycle management (dispose on server stop) */ -export function registerAuthMiddleware(app: FastifyInstance, https: boolean): AuthState { +export function registerAuthMiddleware(app: FastifyInstance, https: boolean, basePath = ''): AuthState { const state: AuthState = { authSessions: null, authFailures: null, @@ -270,7 +275,7 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au ttlMs: AUTH_FAILURE_WINDOW_MS, refreshOnGet: false, }); - registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, state.userFailures); + registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, state.userFailures, basePath); return state; } @@ -293,7 +298,7 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au } // Web-tab proxy, authenticated by the capability in the path, not the cookie. - if (hasValidWebviewCapability(req)) { + if (hasValidWebviewCapability(req, basePath)) { done(); return; } @@ -381,7 +386,8 @@ function registerMultiUserAuthHook( authSessions: StaleExpirationMap, authFailures: StaleExpirationMap, hookSecretFailures: StaleExpirationMap, - userFailures: StaleExpirationMap + userFailures: StaleExpirationMap, + basePath = '' ): void { const setSessionCookie = (reply: FastifyReply, token: string) => reply.setCookie(AUTH_COOKIE_NAME, token, { @@ -432,7 +438,7 @@ function registerMultiUserAuthHook( // `req.authUser` stays undefined here on purpose: the proxy handler enforces // ownership against the identity BOUND TO THE CAPABILITY, which is stricter // than re-deriving it from a request that carries no credentials. - if (hasValidWebviewCapability(req)) return; + if (hasValidWebviewCapability(req, basePath)) return; const clientIp = req.ip; @@ -552,7 +558,7 @@ const SAFE_HTTP_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']); * * WebSocket upgrades are validated separately in the ws route handler. */ -export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPolicy): void { +export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPolicy, basePath = ''): void { app.addHook('onRequest', (req, reply, done) => { const policy = getPolicy(); if (!isAllowedRequestHost(req.headers.host, policy)) { @@ -568,7 +574,7 @@ export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPol if ( !SAFE_HTTP_METHODS.has(req.method) && !isAllowedRequestOrigin(req.headers.origin, policy) && - !hasValidWebviewCapability(req) + !hasValidWebviewCapability(req, basePath) ) { reply.code(403).send('Forbidden: cross-site request blocked'); return; @@ -580,7 +586,7 @@ export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPol /** * Register security headers and CORS middleware on every response. */ -export function registerSecurityHeaders(app: FastifyInstance, https: boolean): void { +export function registerSecurityHeaders(app: FastifyInstance, https: boolean, basePath = ''): void { // Gesture-control overlay (opt-in via CODEMAN_GESTURE=1) runs MediaPipe, which // needs WebAssembly eval (script-src) and blob workers (worker-src). Its wasm // runtime + model are self-hosted under /gesture/ (same-origin, covered by @@ -634,7 +640,7 @@ export function registerSecurityHeaders(app: FastifyInstance, https: boolean): v // net::ERR_FAILED while the page itself renders fine (script/css/img loads // are not CORS-checked). Falling through lets the proxy route reply with the // right headers. - if (req.method === 'OPTIONS' && !hasValidWebviewCapability(req)) { + if (req.method === 'OPTIONS' && !hasValidWebviewCapability(req, basePath)) { reply.code(204).send(); done(); return; diff --git a/src/web/public/app.js b/src/web/public/app.js index c80d526c..30542094 100644 --- a/src/web/public/app.js +++ b/src/web/public/app.js @@ -1268,7 +1268,11 @@ class CodemanApp { if (typeof window !== 'undefined' && typeof window.__CODEMAN_SOLO__ === 'string' && window.__CODEMAN_SOLO__) { return window.__CODEMAN_SOLO__; } - const m = location.pathname.match(/^\/session\/([^/]+)\/?$/); + // Strip the reverse-proxy base so the match works under a sub-path mount. + const base = window.CodemanBase?.base || ''; + let path = location.pathname; + if (base && path.startsWith(base)) path = path.slice(base.length) || '/'; + const m = path.match(/^\/session\/([^/]+)\/?$/); return m ? decodeURIComponent(m[1]) : null; } catch { return null; } } @@ -1293,7 +1297,7 @@ class CodemanApp { if (this.detachedSessions.has(id) && this._raiseDetached(id)) return; const features = 'width=960,height=680,menubar=no,toolbar=no,location=no,status=no'; let win = null; - try { win = window.open('/session/' + encodeURIComponent(id), 'codeman-session-' + id, features); } catch {} + try { win = window.open(CodemanBase.url('/session/' + encodeURIComponent(id)), 'codeman-session-' + id, features); } catch {} if (!win) { this.showToast?.('Pop-out blocked — allow popups for this site to detach a session', 'error'); return; @@ -1545,7 +1549,7 @@ class CodemanApp { // regardless of filter (server side). const _sseParams = new URLSearchParams({ clientId: this._clientId }); if (this.activeSessionId) _sseParams.set('sessions', this.activeSessionId); - this.eventSource = new EventSource(`/api/events?${_sseParams.toString()}`); + this.eventSource = new EventSource(CodemanBase.url(`/api/events?${_sseParams.toString()}`)); // Store all event listeners for cleanup on reconnect. // @@ -2753,7 +2757,7 @@ class CodemanApp { // up to the limit). const cid = this._clientId ? `${this._clientId}:${this._wsTabNonce}` : ''; const cidQuery = cid ? `?cid=${encodeURIComponent(cid)}` : ''; - const url = `${proto}//${location.host}/ws/sessions/${sessionId}/terminal${cidQuery}`; + const url = `${proto}//${location.host}${CodemanBase.base}/ws/sessions/${sessionId}/terminal${cidQuery}`; const ws = new WebSocket(url); this._ws = ws; this._wsSessionId = sessionId; diff --git a/src/web/public/constants.js b/src/web/public/constants.js index 80308150..dee5cc27 100644 --- a/src/web/public/constants.js +++ b/src/web/public/constants.js @@ -22,6 +22,63 @@ // Codeman — Shared constants and utility functions for frontend modules +// ═══════════════════════════════════════════════════════════════ +// Reverse-proxy base path +// ═══════════════════════════════════════════════════════════════ +// When Codeman is served behind a reverse proxy under a sub-path (e.g. /codeman/), +// the server injects `window.__CODEMAN_BASE__` (normalized: '' for root, or '/foo'). +// The `` tag in index.html already rewrites the RELATIVE asset refs, but +// every URL the frontend builds at RUNTIME is root-absolute (`/api/...`, `/ws/...`) +// and root-absolute URLs ignore `` — so those must be prefixed here instead. +// Rather than touch ~190 call sites, all runtime URL construction routes through this +// ONE choke point: `CodemanBase.url()` is the route builder, and a thin wrapper over +// `fetch` applies it transparently. The handful of EventSource/WebSocket sites call +// `CodemanBase.url()` / `CodemanBase.base` explicitly. No-op when mounted at root. +const CodemanBase = (function () { + // `window` is absent in some unit-test vm contexts that load this module in + // isolation; guard so the module still evaluates (base degrades to root). + const _win = typeof window !== 'undefined' ? window : undefined; + const base = String((_win && _win.__CODEMAN_BASE__) || '').replace(/\/+$/, ''); + /** + * Prefix a root-absolute application path with the mount base. Leaves untouched: + * relative paths and fragments/queries (resolved against ``), protocol-relative + * (`//host`) and absolute URLs, and paths already carrying the prefix. + */ + function url(path) { + if (!base) return path; + if (typeof path !== 'string' || path.length === 0) return path; + if (path[0] !== '/') return path; // relative / fragment / query + if (path[1] === '/') return path; // protocol-relative + if (path === base || path.startsWith(base + '/') || path.startsWith(base + '?')) return path; + return base + path; + } + return { base, url }; +})(); +if (typeof window !== 'undefined') window.CodemanBase = CodemanBase; + +// Transparently prefix root-absolute app paths on every fetch, so the many +// `/api/...` string literals across the frontend need no per-call edit. +if (typeof window !== 'undefined' && CodemanBase.base && typeof window.fetch === 'function') { + const _origFetch = window.fetch.bind(window); + window.fetch = function (input, init) { + if (typeof input === 'string') return _origFetch(CodemanBase.url(input), init); + if (typeof Request !== 'undefined' && input instanceof Request) { + try { + const u = new URL(input.url); + if (u.origin === location.origin) { + const prefixed = CodemanBase.url(u.pathname); + if (prefixed !== u.pathname) { + return _origFetch(new Request(u.origin + prefixed + u.search + u.hash, input), init); + } + } + } catch (_e) { + /* not a parseable URL — fall through */ + } + } + return _origFetch(input, init); + }; +} + // ═══════════════════════════════════════════════════════════════ // Web Push Utilities // ═══════════════════════════════════════════════════════════════ diff --git a/src/web/public/keyboard-accessory.js b/src/web/public/keyboard-accessory.js index 35b67c3e..43c6ebe7 100644 --- a/src/web/public/keyboard-accessory.js +++ b/src/web/public/keyboard-accessory.js @@ -304,7 +304,7 @@ const PathPicker = { // A hidden file is only reachable while the toggle is on, and the preview // endpoint re-resolves the path independently, so it needs the flag too. if (this._showHidden) params.set('showHidden', 'true'); - const previewUrl = `/api/filesystem/preview?${params.toString()}`; + const previewUrl = (window.CodemanBase?.url || ((p) => p))(`/api/filesystem/preview?${params.toString()}`); const overlay = document.createElement('div'); overlay.className = 'path-preview-overlay'; diff --git a/src/web/public/manifest.json b/src/web/public/manifest.json index 79b6ea64..8ce935b0 100644 --- a/src/web/public/manifest.json +++ b/src/web/public/manifest.json @@ -2,7 +2,8 @@ "name": "Codeman", "short_name": "Codeman", "description": "Claude Code session manager", - "start_url": "/", + "start_url": "./", + "scope": "./", "display": "standalone", "orientation": "any", "background_color": "#0a0a0a", diff --git a/src/web/public/notification-manager.js b/src/web/public/notification-manager.js index 2d7f4d9f..c1f7f665 100644 --- a/src/web/public/notification-manager.js +++ b/src/web/public/notification-manager.js @@ -390,7 +390,7 @@ class NotificationManager { const notif = new Notification(`${this.originalTitle}: ${localizedTitle}`, { body: localizedBody, tag, // Groups same-tag notifications - icon: '/favicon.ico', + icon: (window.CodemanBase?.url || ((p) => p))('/favicon.ico'), silent: true, // We handle audio ourselves }); diff --git a/src/web/public/panels-ui.js b/src/web/public/panels-ui.js index 66197c27..482e7639 100644 --- a/src/web/public/panels-ui.js +++ b/src/web/public/panels-ui.js @@ -3424,7 +3424,7 @@ Object.assign(CodemanApp.prototype, { const nameClass = isDir ? 'file-tree-name directory' : 'file-tree-name'; const downloadBtn = !isDir - ? `⬇` + ? `⬇` : ''; html.push(` @@ -3599,7 +3599,7 @@ Object.assign(CodemanApp.prototype, { : ''; const nameClass = isDir ? 'file-tree-name directory' : 'file-tree-name'; const downloadBtn = !isDir - ? `⬇` + ? `⬇` : ''; return `
@@ -3998,18 +3998,20 @@ Object.assign(CodemanApp.prototype, { // (html/htm arrive as a download there by design — file-raw serves them // attachment-only so widening READ never widens RUN.) const officeDoc = ext === 'docx' || ext === 'pptx'; - this.filePreviewDetachUrl = attachmentId - ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/${officeDoc ? 'preview' : 'raw'}` - : officeDoc - ? `/api/sessions/${sessionId}/file-preview?path=${encodeURIComponent(filePath)}` - : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`; + this.filePreviewDetachUrl = CodemanBase.url( + attachmentId + ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/${officeDoc ? 'preview' : 'raw'}` + : officeDoc + ? `/api/sessions/${sessionId}/file-preview?path=${encodeURIComponent(filePath)}` + : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}` + ); if (detachBtn) detachBtn.hidden = false; // Registered attachment: render straight from its by-id routes — images and // PDFs inline, Office docs via the server-converted PDF preview, text fetched // raw. (Workspace-path previews fall through to the file-content endpoint.) if (attachmentId) { - const base = `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}`; + const base = CodemanBase.url(`/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}`); const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg']); // VIDEO/AUDIO mirror VIDEO_ATTACHMENT_EXTENSIONS/AUDIO_ATTACHMENT_EXTENSIONS // (src/attachment-registry.ts, the single source); the frontend cannot import @@ -4067,13 +4069,13 @@ Object.assign(CodemanApp.prototype, { // to file-content below, which would dump the binary bytes as mojibake. if (ext === 'docx' || ext === 'pptx') { footerEl.textContent = ext.toUpperCase(); - const previewSrc = `/api/sessions/${sessionId}/file-preview?path=${encodeURIComponent(filePath)}`; + const previewSrc = CodemanBase.url(`/api/sessions/${sessionId}/file-preview?path=${encodeURIComponent(filePath)}`); bodyEl.innerHTML = ``; return; } if (ext === 'pdf') { footerEl.textContent = 'PDF'; - const rawSrc = `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`; + const rawSrc = CodemanBase.url(`/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`); bodyEl.innerHTML = ``; return; } @@ -4107,19 +4109,19 @@ Object.assign(CodemanApp.prototype, { const data = result.data; if (data.type === 'image') { - bodyEl.innerHTML = `${escapeHtml(filePath)}`; + bodyEl.innerHTML = `${escapeHtml(filePath)}`; footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`; } else if (data.type === 'video') { // playsinline: iOS otherwise hijacks playback into its fullscreen // player, which leaves the overlay behind it and its own close button // as the only way back. - bodyEl.innerHTML = ``; + bodyEl.innerHTML = ``; footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`; } else if (data.type === 'audio') { - bodyEl.innerHTML = ``; + bodyEl.innerHTML = ``; footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`; } else if (data.type === 'binary') { - const downloadHref = `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}&download=true`; + const downloadHref = CodemanBase.url(`/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}&download=true`); bodyEl.innerHTML = `
Binary file (${this.formatFileSize(data.size)})
Cannot preview
Download
`; footerEl.textContent = data.extension || 'binary'; } else { @@ -4416,9 +4418,11 @@ Object.assign(CodemanApp.prototype, { }, openAttachmentInNewTab(sessionId, filePath, attachmentId = null) { - const url = attachmentId - ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/raw` - : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`; + const url = CodemanBase.url( + attachmentId + ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/raw` + : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}` + ); window.open(url, '_blank'); }, @@ -4454,19 +4458,22 @@ Object.assign(CodemanApp.prototype, { const stack = this.ensureAttachmentCardStack(); const session = this.sessions.get(sessionId); const sessionName = session?.name || sessionId.substring(0, 8); - const attachmentRawUrl = + const attachmentRawUrl = CodemanBase.url( rawUrl || - (attachmentId - ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/raw` - : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`); - const attachmentPreviewUrl = + (attachmentId + ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/raw` + : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`) + ); + const attachmentPreviewUrl = CodemanBase.url( previewUrl || - (attachmentId ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/preview` : null); - const attachmentThumbnailUrl = + (attachmentId ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/preview` : null) + ); + const attachmentThumbnailUrl = CodemanBase.url( thumbnailUrl || - (attachmentId - ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/thumbnail` - : `/api/sessions/${sessionId}/file-thumbnail?path=${encodeURIComponent(filePath)}`); + (attachmentId + ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/thumbnail` + : `/api/sessions/${sessionId}/file-thumbnail?path=${encodeURIComponent(filePath)}`) + ); const downloadUrl = attachmentId ? `${attachmentRawUrl}?download=true` : `${attachmentRawUrl}&download=true`; const typeLabel = (extension || attachmentType || 'file').toUpperCase(); @@ -4730,7 +4737,7 @@ Object.assign(CodemanApp.prototype, { .join(' • '); const thumb = item.thumbnailUrl && !item.missing - ? `` + ? `` : ''; const disabled = item.missing ? 'disabled aria-disabled="true"' : ''; return ` @@ -4770,7 +4777,7 @@ Object.assign(CodemanApp.prototype, { const item = this.getAttachmentHistoryItem(itemId); if (!item || item.missing) return; if (item.rawUrl || item.url) { - window.open(item.rawUrl || item.url, '_blank'); + window.open(CodemanBase.url(item.rawUrl || item.url), '_blank'); return; } this.openAttachmentInNewTab(item.sessionId, item.relativePath || item.fileName, item.attachmentId || null); @@ -4779,7 +4786,7 @@ Object.assign(CodemanApp.prototype, { downloadAttachmentHistoryItem(itemId) { const item = this.getAttachmentHistoryItem(itemId); if (!item || item.missing || !item.downloadUrl) return; - window.open(item.downloadUrl, '_blank'); + window.open(CodemanBase.url(item.downloadUrl), '_blank'); }, reshowAttachmentCard(itemId) { @@ -4925,7 +4932,7 @@ Object.assign(CodemanApp.prototype, { // Connect to SSE stream const eventSource = new EventSource( - `/api/sessions/${sessionId}/tail-file?path=${encodeURIComponent(filePath)}&lines=50` + CodemanBase.url(`/api/sessions/${sessionId}/tail-file?path=${encodeURIComponent(filePath)}&lines=50`) ); eventSource.onmessage = (e) => { @@ -5067,7 +5074,7 @@ Object.assign(CodemanApp.prototype, { // Build image URL using the existing file-raw endpoint // Use relativePath (path from working dir) instead of fileName (basename) for subdirectory images - const imageUrl = `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(relativePath || fileName)}`; + const imageUrl = CodemanBase.url(`/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(relativePath || fileName)}`); // Create window element const win = document.createElement('div'); diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js index b4d18479..2254be0a 100644 --- a/src/web/public/session-ui.js +++ b/src/web/public/session-ui.js @@ -3046,7 +3046,7 @@ Object.assign(CodemanApp.prototype, { return `
${nm} (${mb} MB) - Download + Download diff --git a/src/web/public/settings-ui.js b/src/web/public/settings-ui.js index a346b479..75e088a6 100644 --- a/src/web/public/settings-ui.js +++ b/src/web/public/settings-ui.js @@ -187,7 +187,10 @@ Object.assign(CodemanApp.prototype, { registerServiceWorker() { if (!('serviceWorker' in navigator)) return; - navigator.serviceWorker.register('/sw.js').then((reg) => { + // Behind a sub-path mount the worker is served at /sw.js and controls + // / (Service-Worker-Allowed is '/', so this narrower scope is permitted). + const _swBase = window.CodemanBase?.base || ''; + navigator.serviceWorker.register(_swBase + '/sw.js', { scope: _swBase + '/' }).then((reg) => { this._swRegistration = reg; // Listen for messages from service worker (notification clicks) navigator.serviceWorker.addEventListener('message', (event) => { diff --git a/src/web/public/sw.js b/src/web/public/sw.js index de45a218..efe17981 100644 --- a/src/web/public/sw.js +++ b/src/web/public/sw.js @@ -20,6 +20,13 @@ const CACHE_NAME = 'codeman-v1'; +// Reverse-proxy base path: the worker is served at `/sw.js`, so its own +// location tells us the mount prefix ('' at root, or '/codeman'). Every URL below +// is prefixed through B() so the cached shell, icons and API calls resolve under +// the mount instead of escaping to the origin root. +const SW_BASE = self.location.pathname.replace(/\/sw\.js$/, ''); +const B = (p) => (p && p[0] === '/' ? SW_BASE + p : p); + // Core app shell -- cached on install for instant startup const APP_SHELL = [ '/', @@ -45,7 +52,7 @@ const APP_SHELL = [ '/icon-192.png', '/icon-512.png', '/manifest.json', -]; +].map(B); // --- Install: precache app shell --- @@ -116,9 +123,9 @@ self.addEventListener('push', (event) => { const options = { body: body || '', tag: tag || 'codeman-default', - icon: '/icon-192.png', - badge: '/icon-192.png', - data: { sessionId, approvalId, url: sessionId ? `/?session=${sessionId}` : '/' }, + icon: B('/icon-192.png'), + badge: B('/icon-192.png'), + data: { sessionId, approvalId, url: sessionId ? B(`/?session=${sessionId}`) : B('/') }, renotify: true, requireInteraction: urgency === 'critical', }; @@ -143,7 +150,7 @@ self.addEventListener('notificationclick', (event) => { event.notification.close(); const { sessionId, approvalId, url } = event.notification.data || {}; - const targetUrl = url || '/'; + const targetUrl = url || B('/'); const action = event.action || null; // Approve/Deny action buttons answer the Approvals Inbox item directly from @@ -152,7 +159,7 @@ self.addEventListener('notificationclick', (event) => { // because a service worker fetch carries the worker's own (same) origin. if ((action === 'approve' || action === 'deny') && approvalId) { event.waitUntil( - fetch(`/api/approvals/${encodeURIComponent(approvalId)}/answer`, { + fetch(B(`/api/approvals/${encodeURIComponent(approvalId)}/answer`), { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, diff --git a/src/web/public/voice-input.js b/src/web/public/voice-input.js index 28c22985..1c6355e9 100644 --- a/src/web/public/voice-input.js +++ b/src/web/public/voice-input.js @@ -322,7 +322,7 @@ const ClaudeVoiceProvider = { if (opts.keyterms?.length) params.set('keyterms', opts.keyterms.join(',')); const proto = location.protocol === 'https:' ? 'wss:' : 'ws:'; try { - this._ws = new WebSocket(`${proto}//${location.host}/ws/voice/stream?${params}`); + this._ws = new WebSocket(`${proto}//${location.host}${window.CodemanBase?.base || ''}/ws/voice/stream?${params}`); } catch (err) { this._onError?.('Failed to open voice stream: ' + err.message); this._cleanup(); diff --git a/src/web/public/webview-tabs.js b/src/web/public/webview-tabs.js index 97c87a44..0e56365b 100644 --- a/src/web/public/webview-tabs.js +++ b/src/web/public/webview-tabs.js @@ -182,7 +182,9 @@ Object.assign(CodemanApp.prototype, { if (webview.trusted) sandbox.push('allow-same-origin'); frame.setAttribute('sandbox', sandbox.join(' ')); frame.setAttribute('referrerpolicy', 'no-referrer-when-downgrade'); - frame.src = src; + // Proxied dashboards carry a root-absolute `/webview//` embedUrl that must + // ride the mount prefix; external (trusted) URLs are absolute and pass through. + frame.src = CodemanBase.url(src); const failure = document.createElement('div'); failure.className = 'webview-failure'; diff --git a/src/web/routes/webview-routes.ts b/src/web/routes/webview-routes.ts index b39d247c..16204ba1 100644 --- a/src/web/routes/webview-routes.ts +++ b/src/web/routes/webview-routes.ts @@ -102,14 +102,14 @@ function withWebviews(fn: (list: Webview[]) => Promise | T): Promise { return next; } -export function registerWebviewRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort): void { - registerCrudRoutes(app, ctx); - registerProxyRoutes(app); +export function registerWebviewRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort, basePath = ''): void { + registerCrudRoutes(app, ctx, basePath); + registerProxyRoutes(app, basePath); } // ───────────────────────────── CRUD ───────────────────────────── -function registerCrudRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort): void { +function registerCrudRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort, basePath: string): void { app.get('/api/webviews', async (req) => { const user = getAuthUser(req); const all = await readWebviews(configDir()); @@ -279,7 +279,7 @@ function registerCrudRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort } const capability = webviewCapabilities.mint(webview.id, webview.owner); - const data: WebviewOpenData = { webview, embedUrl: proxyPrefixFor(capability) }; + const data: WebviewOpenData = { webview, embedUrl: proxyPrefixFor(capability, basePath) }; return { success: true, data }; }); } @@ -347,7 +347,7 @@ async function probeUrl(url: string): Promise { // ───────────────────────────── Proxy ───────────────────────────── -function registerProxyRoutes(app: FastifyInstance): void { +function registerProxyRoutes(app: FastifyInstance, basePath: string): void { app.register(async (scope) => { // Encapsulated to this plugin only. The proxy must relay request bodies // BYTE-FOR-BYTE, so every parser is replaced with a pass-through that hands @@ -358,11 +358,11 @@ function registerProxyRoutes(app: FastifyInstance): void { // A single GET route serving both roles: `handler` for normal requests, // `wsHandler` for upgrades. Registering them as two routes on one URL would - // collide. + // collide. (The WS leg produces no browser-facing URLs, so it needs no base.) scope.route<{ Params: ProxyParams }>({ method: 'GET', url: `${WEBVIEW_PROXY_PREFIX}/:cap/*`, - handler: proxyHttp, + handler: (req, reply) => proxyHttp(req, reply, basePath), wsHandler: proxyWebSocket, }); @@ -371,14 +371,14 @@ function registerProxyRoutes(app: FastifyInstance): void { scope.route<{ Params: ProxyParams }>({ method: ['POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], url: `${WEBVIEW_PROXY_PREFIX}/:cap/*`, - handler: proxyHttp, + handler: (req, reply) => proxyHttp(req, reply, basePath), }); // `/webview/` with no trailing slash: redirect rather than serve, so the // browser's notion of the base path ends in `/` and relative URLs in the // dashboard's HTML resolve inside the prefix instead of one level above it. scope.get<{ Params: { cap: string } }>(`${WEBVIEW_PROXY_PREFIX}/:cap`, (req, reply) => { - return reply.redirect(proxyPrefixFor(req.params.cap), 302); + return reply.redirect(proxyPrefixFor(req.params.cap, basePath), 302); }); }); } @@ -406,8 +406,12 @@ async function lookupCapability(capability: string): Promise { * streamed asset comes back zero-length. Returning the reply is what tells Fastify * the response is already owned by this handler. */ -function proxyHttp(req: FastifyRequest<{ Params: ProxyParams }>, reply: FastifyReply): Promise { - return proxyRequest(req, reply, req.params.cap, req.params['*'] ?? ''); +function proxyHttp( + req: FastifyRequest<{ Params: ProxyParams }>, + reply: FastifyReply, + basePath: string +): Promise { + return proxyRequest(req, reply, req.params.cap, req.params['*'] ?? '', basePath); } /** @@ -419,7 +423,8 @@ async function proxyRequest( req: FastifyRequest, reply: FastifyReply, cap: string, - wildcard: string + wildcard: string, + basePath = '' ): Promise { const webview = await lookupCapability(cap); if (!webview) { @@ -454,7 +459,8 @@ async function proxyRequest( const headers = buildUpstreamRequestHeaders(req.headers, upstream, { forwardCookies: webview.trusted, sessionCookieName: AUTH_COOKIE_NAME, - refererPath: typeof req.headers.referer === 'string' ? stripProxyPrefix(req.headers.referer, cap) : undefined, + refererPath: + typeof req.headers.referer === 'string' ? stripProxyPrefix(req.headers.referer, cap, basePath) : undefined, }); // #237: the timeout bounds TIME-TO-HEADERS only. A plain AbortSignal.timeout on @@ -546,7 +552,8 @@ async function proxyRequest( response.headers.getSetCookie(), cap, upstream, - secureContext + secureContext, + basePath ); reply.code(response.status); @@ -575,7 +582,7 @@ async function proxyRequest( // Buffer only HTML, only under the cap: `` injection needs the whole // document, and buffering an unbounded upstream body is a memory hazard. const html = await response.text(); - return reply.send(html.length <= MAX_WEBVIEW_HTML_REWRITE_BYTES ? rewriteHtml(html, cap) : html); + return reply.send(html.length <= MAX_WEBVIEW_HTML_REWRITE_BYTES ? rewriteHtml(html, cap, basePath) : html); } return reply.send(Readable.fromWeb(response.body as Parameters[0])); @@ -596,25 +603,34 @@ async function proxyRequest( * * @returns true when the request was handled (caller must not also reply). */ -export async function tryWebviewRefererFallback(req: FastifyRequest, reply: FastifyReply): Promise { +export async function tryWebviewRefererFallback( + req: FastifyRequest, + reply: FastifyReply, + basePath = '' +): Promise { // Safe methods only. A write arriving here has already lost its raw body to the // root instance's JSON parser, so it could not be relayed faithfully anyway. if (req.method !== 'GET' && req.method !== 'HEAD') return false; - const capability = capabilityFromReferer(typeof req.headers.referer === 'string' ? req.headers.referer : undefined); + const capability = capabilityFromReferer( + typeof req.headers.referer === 'string' ? req.headers.referer : undefined, + basePath + ); if (!capability) return false; if (!webviewCapabilities.resolve(capability)) return false; + // req.url is already base-stripped by the server's rewriteUrl, so this is the + // internal path the upstream resolver expects. const path = req.url.split('?')[0].replace(/^\//, ''); - await proxyRequest(req, reply, capability, path); + await proxyRequest(req, reply, capability, path, basePath); return true; } /** Turn a proxy-side Referer back into the upstream path it corresponds to. */ -function stripProxyPrefix(referer: string, capability: string): string | undefined { +function stripProxyPrefix(referer: string, capability: string, basePath = ''): string | undefined { try { const url = new URL(referer); - const prefix = proxyPrefixFor(capability); + const prefix = proxyPrefixFor(capability, basePath); if (!url.pathname.startsWith(prefix)) return undefined; return `/${url.pathname.slice(prefix.length)}${url.search}`; } catch { diff --git a/src/web/server.ts b/src/web/server.ts index 0cf318d6..49a724d9 100644 --- a/src/web/server.ts +++ b/src/web/server.ts @@ -41,6 +41,7 @@ import fs from 'node:fs/promises'; import { execSync } from 'node:child_process'; import { hostname as getHostname } from 'node:os'; import { dataPath, getDataDir, CODEMAN_INSTANCE } from '../config/instance.js'; +import { normalizeBasePath, stripBasePath, joinBasePath } from '../config/base-path.js'; import { GLYPH, palette } from '../cli-style.js'; import { getHookSecret } from '../config/hook-secret.js'; import { EventEmitter } from 'node:events'; @@ -260,6 +261,8 @@ export class WebServer extends EventEmitter { private port: number; private host: string; private https: boolean; + /** Reverse-proxy sub-path prefix (normalized: '' for root, or '/foo'). */ + private basePath: string; private testMode: boolean; private mux: TerminalMultiplexer; // Centralized cleanup for standalone timers (intervals + resettable timeouts) @@ -330,13 +333,16 @@ export class WebServer extends EventEmitter { testMode: boolean = false, host: string = '127.0.0.1', titleHostname?: string, - allowUnauthenticatedNetwork: boolean = false + allowUnauthenticatedNetwork: boolean = false, + basePath: string = '' ) { super(); this.setMaxListeners(0); this.host = host; this.port = port; this.https = https; + // Normalize so callers may pass raw operator input; '' == mounted at root. + this.basePath = normalizeBasePath(basePath || process.env.CODEMAN_BASE_URL); this.testMode = testMode; this.allowUnauthenticatedNetwork = allowUnauthenticatedNetwork || isExplicitlyEnabled(process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK); @@ -344,7 +350,12 @@ export class WebServer extends EventEmitter { this.windowTitle = `codeman:${this.titleHostname}`; this.indexHtmlTemplate = readFileSync(join(__dirname, 'public', 'index.html'), 'utf-8'); - const rewriteUrl = (req: { url?: string }): string => rewriteApiV1Url(req.url || ''); + // Ingress: strip the reverse-proxy prefix so all internal routing stays + // prefix-agnostic (routes are still declared at `/api/...`, `/`, `/ws/...`). + // Requests that arrive WITHOUT the prefix (hooks, health checks, the docker + // bridge — all hitting the raw port) pass through unchanged. Then apply the + // existing /api/v1 alias rewrite. + const rewriteUrl = (req: { url?: string }): string => rewriteApiV1Url(stripBasePath(this.basePath, req.url || '')); if (https) { const { key, cert } = getOrCreateSelfSignedCert(); this.app = Fastify({ logger: false, https: { key, cert }, rewriteUrl }); @@ -725,6 +736,21 @@ export class WebServer extends EventEmitter { // Cookie plugin (needed for auth session tokens) await this.app.register(fastifyCookie); + // Egress: when mounted under a reverse-proxy sub-path, any root-absolute + // `Location` we emit (redirects in system/webview/file routes, `/`, `/api/...`) + // must carry the prefix or the browser resolves it against the origin root and + // escapes the mount. One hook covers every current and future redirect, mirroring + // the ingress strip in `rewriteUrl`. No-op when mounted at root (basePath === ''). + if (this.basePath) { + this.app.addHook('onSend', (_req, reply, payload, done) => { + const loc = reply.getHeader('location'); + if (typeof loc === 'string') { + reply.header('location', joinBasePath(this.basePath, loc)); + } + done(null, payload); + }); + } + // Uniform response envelope (stable HTTP contract — docs/api-reference.md): // wrap bare JSON payloads as { success:true, data } and map { success:false } // error envelopes to a conventional HTTP status (instead of 200). Skips @@ -749,10 +775,10 @@ export class WebServer extends EventEmitter { // Anti-DNS-rebinding Host allowlist + cross-site (CSRF) Origin guard. Registered // before auth so forged cross-site / rebound requests are rejected up front, even // on the default no-password install. See docs/reports/security-review-2026-06-09.md. - registerHostGuard(this.app, () => this.getHostPolicy()); + registerHostGuard(this.app, () => this.getHostPolicy(), this.basePath); // Auth middleware (Basic Auth + session cookies + rate limiting) - const authState = registerAuthMiddleware(this.app, this.https); + const authState = registerAuthMiddleware(this.app, this.https, this.basePath); if (authState) { this.authSessions = authState.authSessions; this.authFailures = authState.authFailures; @@ -777,7 +803,7 @@ export class WebServer extends EventEmitter { }); // Security headers + CORS - registerSecurityHeaders(this.app, this.https); + registerSecurityHeaders(this.app, this.https, this.basePath); this.app.get('/', async (_req, reply) => { return reply .header('Cache-Control', 'no-cache') @@ -949,7 +975,7 @@ export class WebServer extends EventEmitter { // rescue. Reaching this handler at all already proves no Codeman route matched, // and the relay declines unless the Referer carries a live capability, so // genuinely unknown `/api` paths still get the envelope below. - if (await tryWebviewRefererFallback(req, reply)) return reply; + if (await tryWebviewRefererFallback(req, reply, this.basePath)) return reply; if (req.url.startsWith('/api')) { return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, notFound)); } @@ -1023,7 +1049,7 @@ export class WebServer extends EventEmitter { registerMeRoutes(this.app, ctx); registerAdminRoutes(this.app, ctx); registerOrchestratorRoutes(this.app, ctx); - registerWebviewRoutes(this.app, ctx); + registerWebviewRoutes(this.app, ctx, this.basePath); registerTabLayoutRoutes(this.app, ctx); // Cron: build the service from the same context, recompute @@ -1383,6 +1409,20 @@ export class WebServer extends EventEmitter { 'Codeman', `${escapeHtmlText(this.windowTitle)}` ); + // Reverse-proxy sub-path support. The template ships `` and all + // static asset refs are RELATIVE, so pointing the base at the mount prefix + // rewrites every asset URL for free. `window.__CODEMAN_BASE__` gives the + // frontend the same prefix for the root-absolute URLs it builds at runtime + // (fetch/SSE/WS), which `` cannot touch. Injected right after `` + // so it is set before any (deferred) script runs. ONLY when a base is set — + // at root ('') the template is left byte-identical to the historical output + // (the frontend reads a missing `__CODEMAN_BASE__` as root anyway). + if (this.basePath) { + html = html.replace( + '', + `\n ` + ); + } // Cache-bust same-origin module scripts + stylesheets so a normal reload // always serves the latest (static assets carry a 1-year immutable cache). html = this.cacheBustAssets(html); @@ -1492,10 +1532,9 @@ export class WebServer extends EventEmitter { html = html.replace('', `\n`); if (settings.gestureControlEnabled === true) { const v = this.gestureBundleVersion(); - html = html.replace( - '', - `\n` - ); + // Relative src so the injected `` resolves it under the mount + // prefix (a root-absolute `/gesture/...` would escape a sub-path mount). + html = html.replace('', `\n`); } } return html; @@ -2490,7 +2529,18 @@ export class WebServer extends EventEmitter { const displayHost = this.host === '0.0.0.0' ? 'localhost' : this.host; // The only startup banner: `codeman web` used to print its own copy of this // line, but the daemon and service launch paths never go through the CLI. - console.log(palette.ok(`${GLYPH.ok} Codeman web interface running at ${protocol}://${displayHost}:${this.port}`)); + console.log( + palette.ok( + `${GLYPH.ok} Codeman web interface running at ${protocol}://${displayHost}:${this.port}${this.basePath}${this.basePath ? '/' : ''}` + ) + ); + if (this.basePath) { + console.log( + palette.muted( + ` Mounted under base path ${this.basePath} (front it with a reverse proxy that forwards ${this.basePath}/ unchanged).` + ) + ); + } // Opt-in: also serve the HOOK endpoints on the docker bridge gateway so // in-container hooks (permission/idle/stop callbacks) can reach a loopback-bound @@ -3335,9 +3385,10 @@ export async function startWebServer( testMode: boolean = false, host: string = '127.0.0.1', titleHostname?: string, - allowUnauthenticatedNetwork: boolean = false + allowUnauthenticatedNetwork: boolean = false, + basePath: string = '' ): Promise { - const server = new WebServer(port, https, testMode, host, titleHostname, allowUnauthenticatedNetwork); + const server = new WebServer(port, https, testMode, host, titleHostname, allowUnauthenticatedNetwork, basePath); await server.start(); return server; } diff --git a/src/web/webview-proxy.ts b/src/web/webview-proxy.ts index 4856b34b..d94626f7 100644 --- a/src/web/webview-proxy.ts +++ b/src/web/webview-proxy.ts @@ -39,6 +39,7 @@ */ import { WEBVIEW_PROXY_PREFIX } from '../config/webview-limits.js'; +import { stripBasePath } from '../config/base-path.js'; /** Headers that are per-connection and must never be relayed in either direction. */ const HOP_BY_HOP = new Set([ @@ -99,9 +100,18 @@ const DROP_RESPONSE_HEADERS = new Set([ 'referrer-policy', ]); -/** The same-origin path prefix an iframe loads for a given capability. */ -export function proxyPrefixFor(capability: string): string { - return `${WEBVIEW_PROXY_PREFIX}/${capability}/`; +/** + * The same-origin path prefix an iframe loads for a given capability. + * + * `basePath` is the reverse-proxy mount prefix (`''` at root, or `/foo`). It is + * INCLUDED here because this value is browser-facing — the iframe src, the + * ``, the runtime shim's rewrite target, Location/Set-Cookie rebasing — + * and all of those must ride the mount or they escape it. Requests coming the other + * way are base-stripped before routing, so the parsers (`capabilityFromProxyPath`, + * `resolveUpstreamUrl`) deliberately do NOT take a base. + */ +export function proxyPrefixFor(capability: string, basePath = ''): string { + return `${basePath}${WEBVIEW_PROXY_PREFIX}/${capability}/`; } /** @@ -178,10 +188,13 @@ export function capabilityFromProxyPath(pathname: string): string | null { * Extract the capability a `Referer` belongs to. Backs the 404 fallback that * catches root-absolute asset requests (`/static/app.js`) which `` cannot fix. */ -export function capabilityFromReferer(referer: string | undefined): string | null { +export function capabilityFromReferer(referer: string | undefined, basePath = ''): string | null { if (!referer) return null; try { - return capabilityFromProxyPath(new URL(referer).pathname); + // The Referer is browser-supplied, so under a sub-path mount it carries the + // prefix (`/foo/webview//...`); strip it back to the internal path the + // capability parser expects. + return capabilityFromProxyPath(stripBasePath(basePath, new URL(referer).pathname)); } catch { return null; } @@ -232,7 +245,7 @@ export function isFramableCrossOrigin(xFrameOptions: string | undefined, csp: st * proxied: relaying them would turn this into an open proxy for any host the * upstream chooses to name. */ -export function rewriteLocation(location: string, requestUrl: URL, capability: string): string { +export function rewriteLocation(location: string, requestUrl: URL, capability: string, basePath = ''): string { let resolved: URL; try { resolved = new URL(location, requestUrl); @@ -241,7 +254,7 @@ export function rewriteLocation(location: string, requestUrl: URL, capability: s } if (resolved.origin !== requestUrl.origin) return location; const suffix = resolved.pathname.replace(/^\//, ''); - return `${proxyPrefixFor(capability)}${suffix}${resolved.search}${resolved.hash}`; + return `${proxyPrefixFor(capability, basePath)}${suffix}${resolved.search}${resolved.hash}`; } /** @@ -252,7 +265,7 @@ export function rewriteLocation(location: string, requestUrl: URL, capability: s * cookie name, and `Secure` is dropped when Codeman itself is serving plain HTTP * in dev, where a Secure cookie would simply be discarded. */ -export function rewriteSetCookie(cookie: string, capability: string, secureContext: boolean): string { +export function rewriteSetCookie(cookie: string, capability: string, secureContext: boolean, basePath = ''): string { const parts = cookie.split(';'); const out: string[] = [parts[0]]; let sawPath = false; @@ -266,13 +279,13 @@ export function rewriteSetCookie(cookie: string, capability: string, secureConte sawPath = true; const value = attr.slice('path='.length); const suffix = value.replace(/^\//, ''); - out.push(`Path=${proxyPrefixFor(capability)}${suffix}`); + out.push(`Path=${proxyPrefixFor(capability, basePath)}${suffix}`); continue; } out.push(attr); } - if (!sawPath) out.push(`Path=${proxyPrefixFor(capability)}`); + if (!sawPath) out.push(`Path=${proxyPrefixFor(capability, basePath)}`); return out.join('; '); } @@ -336,7 +349,8 @@ export function buildDownstreamResponseHeaders( setCookies: string[], capability: string, requestUrl: URL, - secureContext: boolean + secureContext: boolean, + basePath = '' ): { headers: Record; setCookie: string[]; csp: string | null } { const headers: Record = {}; let csp: string | null = null; @@ -349,7 +363,7 @@ export function buildDownstreamResponseHeaders( continue; } if (lower === 'location') { - headers['location'] = rewriteLocation(value, requestUrl, capability); + headers['location'] = rewriteLocation(value, requestUrl, capability, basePath); continue; } if (DROP_RESPONSE_HEADERS.has(lower)) continue; @@ -365,7 +379,7 @@ export function buildDownstreamResponseHeaders( // override this; that is the dashboard author's own decision about their page. headers['referrer-policy'] = 'same-origin'; - const setCookie = setCookies.map((cookie) => rewriteSetCookie(cookie, capability, secureContext)); + const setCookie = setCookies.map((cookie) => rewriteSetCookie(cookie, capability, secureContext, basePath)); return { headers, setCookie, csp }; } @@ -593,8 +607,8 @@ try{ * relative URLs, attribute rewriting for root-absolute markup, and the shim for * URLs built at runtime. */ -export function rewriteHtml(html: string, capability: string): string { - const prefix = proxyPrefixFor(capability); +export function rewriteHtml(html: string, capability: string, basePath = ''): string { + const prefix = proxyPrefixFor(capability, basePath); // Fresh regexes per call: module-level /g patterns carry `lastIndex` between calls. const rebased = html diff --git a/test/base-path.test.ts b/test/base-path.test.ts new file mode 100644 index 00000000..22abb5ac --- /dev/null +++ b/test/base-path.test.ts @@ -0,0 +1,119 @@ +/** + * @fileoverview Unit tests for the pure reverse-proxy base-path helpers + * (src/config/base-path.ts). These back the server ingress strip (rewriteUrl), + * the egress Location rewrite (onSend), and the frontend route builder, so their + * correctness is what makes a sub-path mount work end to end. + */ +import { describe, it, expect } from 'vitest'; +import { + normalizeBasePath, + isValidBasePath, + assertValidBasePath, + joinBasePath, + stripBasePath, +} from '../src/config/base-path.js'; + +describe('normalizeBasePath', () => { + it('treats root / and empty as no prefix', () => { + expect(normalizeBasePath('/')).toBe(''); + expect(normalizeBasePath('')).toBe(''); + expect(normalizeBasePath(undefined)).toBe(''); + expect(normalizeBasePath(null)).toBe(''); + expect(normalizeBasePath(' ')).toBe(''); + }); + + it('adds a leading slash and drops trailing slashes', () => { + expect(normalizeBasePath('codeman')).toBe('/codeman'); + expect(normalizeBasePath('/codeman')).toBe('/codeman'); + expect(normalizeBasePath('/codeman/')).toBe('/codeman'); + expect(normalizeBasePath('codeman///')).toBe('/codeman'); + }); + + it('collapses duplicate slashes and keeps nested segments', () => { + expect(normalizeBasePath('//a//b//')).toBe('/a/b'); + expect(normalizeBasePath('/tools/codeman')).toBe('/tools/codeman'); + }); +}); + +describe('isValidBasePath / assertValidBasePath', () => { + it('accepts root and well-formed segments', () => { + expect(isValidBasePath('')).toBe(true); + expect(isValidBasePath('/codeman')).toBe(true); + expect(isValidBasePath('/tools/codeman-2')).toBe(true); + expect(isValidBasePath('/a_b.c~d')).toBe(true); + }); + + it('rejects segments with unsafe characters', () => { + expect(isValidBasePath('/a b')).toBe(false); + expect(isValidBasePath('/a?b')).toBe(false); + expect(isValidBasePath('/a#b')).toBe(false); + expect(isValidBasePath('/a%2f')).toBe(false); + }); + + it('assertValidBasePath normalizes valid input and throws on bad', () => { + expect(assertValidBasePath('/codeman/')).toBe('/codeman'); + expect(assertValidBasePath('/')).toBe(''); + expect(() => assertValidBasePath('/a b')).toThrow(/Invalid --base-url/); + expect(() => assertValidBasePath('?x')).toThrow(/Invalid --base-url/); + }); +}); + +describe('joinBasePath (frontend/egress route builder)', () => { + it('is a no-op at root', () => { + expect(joinBasePath('', '/api/x')).toBe('/api/x'); + expect(joinBasePath('', '/')).toBe('/'); + }); + + it('prefixes root-absolute app paths', () => { + expect(joinBasePath('/codeman', '/api/x')).toBe('/codeman/api/x'); + expect(joinBasePath('/codeman', '/')).toBe('/codeman/'); + expect(joinBasePath('/codeman', '/ws/sessions/1/terminal')).toBe('/codeman/ws/sessions/1/terminal'); + }); + + it('leaves absolute, protocol-relative, and relative URLs alone', () => { + expect(joinBasePath('/codeman', 'https://x/y')).toBe('https://x/y'); + expect(joinBasePath('/codeman', 'ws://x/y')).toBe('ws://x/y'); + expect(joinBasePath('/codeman', '//host/y')).toBe('//host/y'); + expect(joinBasePath('/codeman', 'app.js')).toBe('app.js'); + expect(joinBasePath('/codeman', '#frag')).toBe('#frag'); + expect(joinBasePath('/codeman', 'data:image/png;base64,AAAA')).toBe('data:image/png;base64,AAAA'); + }); + + it('is idempotent — never double-prefixes', () => { + expect(joinBasePath('/codeman', '/codeman/api/x')).toBe('/codeman/api/x'); + expect(joinBasePath('/codeman', '/codeman')).toBe('/codeman'); + expect(joinBasePath('/codeman', '/codeman?y=1')).toBe('/codeman?y=1'); + }); + + it('does not treat a same-named sibling path as already-prefixed', () => { + // /codeman-docs must NOT be mistaken for the /codeman mount. + expect(joinBasePath('/codeman', '/codeman-docs/x')).toBe('/codeman/codeman-docs/x'); + }); +}); + +describe('stripBasePath (server ingress)', () => { + it('is a no-op at root', () => { + expect(stripBasePath('', '/api/x')).toBe('/api/x'); + }); + + it('strips the prefix from proxied requests', () => { + expect(stripBasePath('/codeman', '/codeman/api/x')).toBe('/api/x'); + expect(stripBasePath('/codeman', '/codeman')).toBe('/'); + expect(stripBasePath('/codeman', '/codeman/')).toBe('/'); + expect(stripBasePath('/codeman', '/codeman?y=1')).toBe('/?y=1'); + }); + + it('leaves un-prefixed requests unchanged (direct-to-port: hooks, health, docker bridge)', () => { + expect(stripBasePath('/codeman', '/api/x')).toBe('/api/x'); + expect(stripBasePath('/codeman', '/api/hook-event')).toBe('/api/hook-event'); + // A same-named sibling is not the mount. + expect(stripBasePath('/codeman', '/codeman-docs/x')).toBe('/codeman-docs/x'); + }); + + it('round-trips with joinBasePath', () => { + const base = '/tools/codeman'; + for (const p of ['/', '/api/x', '/ws/y', '/session/abc']) { + expect(stripBasePath(base, joinBasePath(base, p))).toBe(p); + } + }); +}); diff --git a/test/daemon-control.test.ts b/test/daemon-control.test.ts index 10651337..a5bb642f 100644 --- a/test/daemon-control.test.ts +++ b/test/daemon-control.test.ts @@ -52,6 +52,16 @@ describe('buildWebArgs', () => { ]); }); + it('forwards --base-url so a detached/service relaunch keeps the mount prefix', () => { + const args = buildWebArgs({ host: '127.0.0.1', port: 3000, https: false, basePath: '/codeman' }); + expect(args).toContain('--base-url'); + expect(args[args.indexOf('--base-url') + 1]).toBe('/codeman'); + }); + + it('omits --base-url at root (empty basePath)', () => { + expect(buildWebArgs({ host: '127.0.0.1', port: 3000, https: false, basePath: '' })).not.toContain('--base-url'); + }); + it('never re-emits the daemon flags themselves (the child must not re-fork)', () => { const args = buildWebArgs({ host: '127.0.0.1', port: 3000, https: false }); expect(args).not.toContain('--daemon'); diff --git a/test/file-browser-search.test.ts b/test/file-browser-search.test.ts index 13e804b8..d6e95a58 100644 --- a/test/file-browser-search.test.ts +++ b/test/file-browser-search.test.ts @@ -161,6 +161,8 @@ function loadPanel(options: { sessionId?: string | null; showHidden?: boolean } CodemanApp, console, escapeHtml, + // Reverse-proxy route builder from constants.js (not loaded here); identity at root. + CodemanBase: { base: '', url: (p: string) => p }, localStorage: { getItem: () => null, setItem: vi.fn() }, document: { getElementById: (id: string) => elements[id] ?? null, @@ -222,6 +224,8 @@ function loadRealSelectSessionHarness(options: { terminalFailure?: boolean } = { }, HTMLCanvasElement: class HTMLCanvasElement {}, WebSocket: { OPEN: 1 }, + // Reverse-proxy route builder from constants.js (not loaded here); identity at root. + CodemanBase: { base: '', url: (p: string) => p }, MobileDetection: { isTouchDevice: () => false }, localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() }, document: { diff --git a/test/file-preview-detach.test.ts b/test/file-preview-detach.test.ts index 9e31df9c..6773386c 100644 --- a/test/file-preview-detach.test.ts +++ b/test/file-preview-detach.test.ts @@ -38,6 +38,8 @@ function loadApp() { console: { ...console, warn: vi.fn(), error: vi.fn() }, localStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} }, escapeHtml: (s: string) => String(s), + // Reverse-proxy route builder from constants.js (not loaded here); identity at root. + CodemanBase: { base: '', url: (p: string) => p }, document: { getElementById: () => null, addEventListener: vi.fn() }, window: windowStub, setTimeout, diff --git a/test/file-preview-media.test.ts b/test/file-preview-media.test.ts index 1152ddf5..33af4591 100644 --- a/test/file-preview-media.test.ts +++ b/test/file-preview-media.test.ts @@ -64,6 +64,8 @@ function loadApp(media: FakeMedia[]) { console: { ...console, warn: vi.fn() }, localStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} }, escapeHtml: (s: string) => String(s), + // Reverse-proxy route builder from constants.js (not loaded here); identity at root. + CodemanBase: { base: '', url: (p: string) => p }, document: { getElementById: () => null, addEventListener: vi.fn() }, window: { addEventListener: vi.fn() }, setTimeout, diff --git a/test/render-index-html.test.ts b/test/render-index-html.test.ts index 1d103508..0cb6b334 100644 --- a/test/render-index-html.test.ts +++ b/test/render-index-html.test.ts @@ -228,3 +228,42 @@ describe('WebServer.renderIndexHtml', () => { expect(html).not.toContain('gesture-codeman.js'); }); }); + +describe('WebServer.renderIndexHtml reverse-proxy base path', () => { + const BASE_TEMPLATE = ['', '', 'Codeman', '', ''].join('\n'); + + function makeBaseServer(basePath: string) { + // constructor: (port, https, testMode, host, titleHostname, allowUnauth, basePath) + const server = new WebServer(0, false, true, '127.0.0.1', undefined, false, basePath); + // eslint-disable-next-line @typescript-eslint/no-explicit-any + (server as any).indexHtmlTemplate = BASE_TEMPLATE; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + (server as any).readSettings = vi.fn(async () => ({})); + return server; + } + + it('is inert at root — base tag unchanged and no base global injected', async () => { + const server = makeBaseServer(''); + const html = await render(server); + expect(html).toContain(''); + // At root the frontend reads a MISSING __CODEMAN_BASE__ as root, so nothing is + // injected and the historical output is byte-identical. + expect(html).not.toContain('__CODEMAN_BASE__'); + }); + + it('points the base tag and the base global at a sub-path mount', async () => { + const server = makeBaseServer('/codeman'); + const html = await render(server); + expect(html).toContain(''); + expect(html).toContain('window.__CODEMAN_BASE__="/codeman"'); + // The global rides right after , before any (deferred) script. + expect(html.indexOf('window.__CODEMAN_BASE__')).toBeLessThan(html.indexOf('')); + }); + + it('normalizes a raw operator prefix passed to the constructor', async () => { + const server = makeBaseServer('codeman/'); + const html = await render(server); + expect(html).toContain(''); + expect(html).toContain('window.__CODEMAN_BASE__="/codeman"'); + }); +}); diff --git a/test/webview-proxy.test.ts b/test/webview-proxy.test.ts index bd020f34..e4b4c52f 100644 --- a/test/webview-proxy.test.ts +++ b/test/webview-proxy.test.ts @@ -684,3 +684,39 @@ describe('referrer policy on proxied responses', () => { expect(headers['referrer-policy']).toBe('same-origin'); }); }); + +describe('reverse-proxy base path', () => { + const BASE = '/codeman'; + const BASED_PREFIX = `${BASE}/webview/${CAP}/`; + + it('rides the mount into the iframe prefix', () => { + expect(proxyPrefixFor(CAP, BASE)).toBe(BASED_PREFIX); + expect(proxyPrefixFor(CAP, '')).toBe(PREFIX); // root unchanged + }); + + it('rewrites HTML (base tag, root-absolute attrs, shim) under the mount', () => { + const out = rewriteHtml('', CAP, BASE); + expect(out).toContain(``); + expect(out).toContain(`src="${BASED_PREFIX}logo.png"`); + // The runtime shim's rewrite target is the base-prefixed path. + expect(out).toContain(JSON.stringify(BASED_PREFIX)); + }); + + it('rebases Set-Cookie Path onto the mounted prefix so the browser sends it back', () => { + expect(rewriteSetCookie('sid=abc; Path=/', CAP, true, BASE)).toContain(`Path=${BASED_PREFIX}`); + expect(rewriteSetCookie('sid=abc; HttpOnly', CAP, true, BASE)).toContain(`Path=${BASED_PREFIX}`); + }); + + it('rewrites a same-origin Location into the mounted prefix', () => { + const requestUrl = new URL('http://127.0.0.1:4000/app'); + expect(rewriteLocation('/dashboard?x=1', requestUrl, CAP, BASE)).toBe(`${BASED_PREFIX}dashboard?x=1`); + }); + + it('extracts the capability from a browser Referer that carries the mount prefix', () => { + expect(capabilityFromReferer(`https://box.ts.net${BASED_PREFIX}page`, BASE)).toBe(CAP); + // A same-named sibling path must not be mistaken for the mount. + expect(capabilityFromReferer(`https://box.ts.net/codeman-docs/webview/${CAP}/page`, BASE)).toBeNull(); + // Without the base arg the prefixed Referer no longer matches (documents why the arg exists). + expect(capabilityFromReferer(`https://box.ts.net${BASED_PREFIX}page`)).toBeNull(); + }); +}); From 06febfa03258d01df541f161753bff94513d1fef Mon Sep 17 00:00:00 2001 From: Devvyn <22340871+opticon454@users.noreply.github.com> Date: Sat, 5 Sep 2026 17:14:05 +0800 Subject: [PATCH 19/26] fix(file-picker): default the case picker to Codeman Cases, not Home MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Link Existing" case picker opens with an empty path and no sessionId, so the browse endpoint's fallback root picked whichever root happened to be first in the list — which was always `Home`. On the native default that's harmless (~/codeman-cases nests inside Home anyway), but a Docker deployment binds CODEMAN_APPDATA_PATH (Home) and CODEMAN_CASES_PATH at unrelated host paths, so the picker opened somewhere with no cases in sight. Worse: if CODEMAN_CASES_PATH is ever changed after cases already exist, the old cases directory lingers, still reachable, under Home — indistinguishable at a glance from the real one under the new Codeman Cases root. Prefer the Codeman Cases root in the fallback chain, ahead of the generic roots[0]. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01R9ZSTEenc8soSu9bTi8Xru --- src/web/routes/file-routes.ts | 15 ++++++++++++++- test/routes/file-routes.test.ts | 15 +++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/src/web/routes/file-routes.ts b/src/web/routes/file-routes.ts index 20a567f3..9640cd28 100644 --- a/src/web/routes/file-routes.ts +++ b/src/web/routes/file-routes.ts @@ -536,8 +536,21 @@ async function resolveFilesystemPickerPath( throwFilesystemPickerError(403, ApiErrorCode.INVALID_INPUT, 'No filesystem browse roots are available'); } + // With no explicit path (the "Link Existing" case picker, which passes no + // sessionId and an empty initialPath until the user has typed something), + // land on the shared cases root rather than falling through to whichever + // root happens to be first. `Home` is only nested under `Codeman Cases` on + // the native default (~/codeman-cases); a Docker deployment binds them at + // unrelated host paths (CODEMAN_APPDATA_PATH vs CODEMAN_CASES_PATH), so a + // Home-first fallback opened the picker somewhere with no cases in sight — + // and, worse, made an OLD case folder left behind by a since-changed + // CODEMAN_CASES_PATH look like a normal thing to stumble across while + // browsing for one to link. const fallbackRoot = - roots.find((root) => root.label === 'Current Folder') ?? roots.find((root) => root.path === '/mnt/d') ?? roots[0]; + roots.find((root) => root.label === 'Current Folder') ?? + roots.find((root) => root.label === 'Codeman Cases') ?? + roots.find((root) => root.path === '/mnt/d') ?? + roots[0]; const candidatePath = resolve(requestedPath ?? fallbackRoot.path); let resolvedPath: string; diff --git a/test/routes/file-routes.test.ts b/test/routes/file-routes.test.ts index 9552c32a..e8c532d3 100644 --- a/test/routes/file-routes.test.ts +++ b/test/routes/file-routes.test.ts @@ -10,6 +10,7 @@ import { Readable } from 'node:stream'; import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js'; import { registerFileRoutes } from '../../src/web/routes/file-routes.js'; import { ApiErrorCode } from '../../src/types.js'; +import { CASES_DIR } from '../../src/web/route-helpers.js'; // Mock fs/promises for file operations vi.mock('node:fs/promises', () => ({ @@ -114,6 +115,20 @@ describe('file-routes', () => { ]); }); + it('defaults to the Codeman Cases root, not Home, when linking a case with no path chosen yet', async () => { + // The "Link Existing" case picker opens with an empty path and no + // sessionId. `Home` and `Codeman Cases` are unrelated bind mounts under + // Docker, so falling back to whichever root happened to be listed first + // could open the picker somewhere with no cases in it at all — and, worse, + // make a stale directory from a since-changed CODEMAN_CASES_PATH look like + // a normal thing to stumble across while browsing for one to link. + const res = await harness.app.inject({ method: 'GET', url: '/api/filesystem/browse' }); + + expect(res.statusCode).toBe(200); + const body = JSON.parse(res.body); + expect(body.data.path).toBe(CASES_DIR); + }); + it('rejects paths outside the configured roots', async () => { const res = await harness.app.inject({ method: 'GET', From 8ad2215118fc62206076780842089726d68b2b01 Mon Sep 17 00:00:00 2001 From: Codeman maintainer Date: Sat, 5 Sep 2026 16:22:54 +0200 Subject: [PATCH 20/26] fix(docker): close the three adoption gaps the negative guarantee missed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-ups to #357. Each is a path that still touched, or still hid, a container Codeman does not own. **Export still mutated it.** The four fail-closed layers cover create/start/ stop/remove, but `POST /api/docker-cases/:name/export` reaches the container twice through neither: a full export `docker commit`s it, and even a workspace-only export `docker pause`s it first for snapshot consistency. Pause freezes the owner's processes for as long as the tar takes, on a container we promised not to touch. Full export is refused for an adopted case (it packages someone else's container, with their logins, into a bundle Codeman hands out); workspace-only keeps working and no longer pauses, accepting a live filesystem the way `tar` does on any running host directory. **A freshly linked OWNED case became unusable.** The run menu now probes the container for its CLIs, and a failed probe hides every agent mode behind the reason. For an adopted case that is right. For an owned one the container does not exist until the first session launches it, so every newly linked Docker case answered `container "codeman-case-x" not found (adoption never creates a container — start it yourself first)` and offered nothing but Shell, for a container the launch chain was about to create itself. A failed probe is recorded only when the case is adopted; `CaseInfo.docker.owned` is on the wire so the frontend can tell them apart. Verified in a browser: owned-with-no- container offers all ten modes and no notice, adopted-but-stopped offers Shell and says why. **Multi-user gating.** Adoption is admin-only, unlike `docker-link` beside it. Linking creates OUR container, whose sole bind mount `isWorkingDirAllowed` has already confined to the caller's space; an adopted container's mounts are whatever its owner gave it, so one mounting `/` hands the adopter a shell over the whole host — exactly the workspace scoping multi-user mode exists to enforce. Listing the engine's containers and browsing directories inside an arbitrary one are machine-level reads and follow the docker-HOST policy for the same reason. The preflight is deliberately not admin-only: the run menu fires it for every docker case, so it admits a non-admin for a container already linked to a case they can access, and nothing else. Verified end to end against a real pre-existing root container (alpine + tmux, no bind mounts): adopt, claude session inside it, workspace export, session close and case unlink all left `StartedAt`, `RestartCount`, `Pid` and `Paused` untouched; the pane ran the CONTAINER's claude, without `--dangerously-skip-permissions`; a stopped container was refused at both preflight and launch and was never started. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01TecFD9hvPYJ1mkkMtBQbT1 --- CLAUDE.md | 57 +++++++++++++++--------- docs/architecture-invariants.md | 16 +++++-- docs/docker-cases.md | 61 ++++++++++++++++++++++++-- src/docker-export.ts | 9 +++- src/types/api.ts | 11 +++++ src/web/public/session-ui.js | 20 +++++++-- src/web/routes/case-routes.ts | 53 ++++++++++++++++++++-- test/docker-adopted-container.test.ts | 63 +++++++++++++++++++++++++++ 8 files changed, 253 insertions(+), 37 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cee65117..5c742fd1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co > > **This file is in `.prettierignore` on purpose.** Prettier's markdown printer escapes underscores inside the glob-heavy paths used throughout (`agent-*.jsonl` became `agent-\_.jsonl`, collapsing backtick spans and corrupting a whole paragraph). Do not remove the ignore entry, and do not run `prettier --write` on it. > -> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those. +> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection), `.dockerignore` (the build context is the repo root, so Docker resolves it there and nowhere else) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those. ## Quick Reference @@ -75,13 +75,13 @@ 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.23.2 (must match `package.json`) +**Version**: 1.24.7 (must match `package.json`) ## Project Overview Codeman is a Claude Code session manager with web interface and autonomous Ralph Loop. Spawns Claude CLI via PTY, streams via SSE, supports respawn cycling for 24+ hour autonomous runs. -**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), Antigravity (`agy`, Google), Pi (pi.dev), Grok Build (`grok`, xAI) and DeepSeek Harness (`dsh`) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek'`). +**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), Antigravity (`agy`, Google), Pi (pi.dev), Grok Build (`grok`, xAI), DeepSeek Harness (`dsh`) and OMP (`omp`) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp'`). **TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`. @@ -113,6 +113,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph | Production logs | `journalctl --user -u codeman-web -f` | | Detached server | `codeman web -d` (`--status`, `--stop`; pidfile+log at `dataPath('web.pid'/'web.log')`). ⚠ Refuses to start a 2nd server on one data dir — see Instance isolation | | Install/remove the service | `codeman service install` / `status` / `uninstall` (systemd user unit on Linux, LaunchAgent on macOS; names from `config/service-names.ts`) | +| Dependency doctor | `codeman doctor` (alias `check-deps`; `--json`, `--category core\|office\|other`). Probes Node/Claude CLI/tmux/LibreOffice/MS Office against `config/dependency-registry.ts`; engine is pure given an injectable `ProbeHost` | +| Multi-user accounts | `codeman users add ` / `passwd ` / `list` / `rm ` (writes `~/.codeman/users.json`, mode 0600; see Multi-user mode) | **CI**: `.github/workflows/ci.yml` (push to master/main + PRs, Node 22) runs two jobs: **(1)** `check:lockfile`, `typecheck`, `lint`, `check:frontend-syntax`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s); **(2)** the **unit/integration test suite** via `npm run test:ci` (`config/vitest.ci.config.ts` — excludes the browser-driven `test/mobile/**` suite, `perf-*` benchmarks, and 5 Playwright tests; globs live in `config/test-suites.ts`). `npm test` runs this same config, so local green == CI green. Tests are tmux-safe in CI: `TmuxManager` no-ops all shell commands under `VITEST` (see Testing). @@ -148,9 +150,9 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph | ---------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **Entry** | `src/index.ts`, `src/cli.ts`, `daemon-control`, `service-installer`, `config/service-names`, `cli-style` | The last three back `web -d` / `service install`; `cli-style` is the shared palette/table/spinner/confirm kit | | **TUI** | `src/tui/`: `tui-app` ★ + `tui-client` (the only IO) over a pure core (`-model`, `-layout`, `-render`, `-keys`, `-ansi`, `-composer`, `-approvals`, `-digest`, `-sse`, `-types`) | `codeman tui`, a CLIENT of the server, never a second brain. Design doc: `docs/tui-plan.md`; user guide `docs/tui.md` | -| **DeepSeek** | `src/utils/deepseek-cli-resolver.ts`, `src/deepseek-status-shim.ts` | `dsh` is a PROFILE LAUNCHER, not an agent; read `docs/deepseek-integration.md` first | -| **Session** | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose | -| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★ | | +| **DeepSeek** | `src/utils/deepseek-cli-resolver.ts`, `src/deepseek-status-shim.ts`, `src/deepseek-web-server.ts` (background `dsh web`, not a session) | `dsh` is a PROFILE LAUNCHER, not an agent; read `docs/deepseek-integration.md` first | +| **Session** | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `session-trust-dialog` (pure), `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose | +| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★, `src/proc-tree.ts` (pure, bounded descendant walk) | | | **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first | | **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first | | **Orchestrator** | `src/orchestrator-loop.ts`, `-planner`, `-verifier` | Read `docs/orchestrator-loop-architecture.md` first | @@ -158,14 +160,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph | **Agents** | `src/subagent-watcher.ts` ★, `team-watcher`, `bash-tool-parser`, `transcript-watcher`, `workflow-run-watcher` | `workflow-run-watcher` is STANDALONE and never touches `subagent-watcher` | | **AI** | `src/ai-checker-base.ts`, `ai-idle-checker.ts`, `ai-plan-checker.ts` | | | **Tasks** | `src/task.ts`, `task-queue.ts`, `task-tracker.ts` | | -| **State** | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`, `intent-store.ts` | | +| **State** | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`, `intent-store.ts`, `tab-layout.ts` (pure model) + `-service` (sole mutation boundary) + `-persistence` + `-legacy-order` | | | **Infra** | `src/hooks-config.ts`, `push-store`, `tunnel-manager`, `image-watcher`, `file-stream-manager`, `remote-hosts` + `remote-reconnect` (pure), `docker-hosts` + `docker-export` | Remote/docker case overlays; see Key Patterns | | **Web tabs** | `src/webview-store.ts`, `webview-capabilities.ts`, `src/web/webview-proxy.ts` (pure), `src/web/routes/webview-routes.ts` | Dashboard URLs as tabs; NOT a SessionMode | | **Search** | `src/search-service.ts` | Pure in-memory core for `GET /api/search` | | **Attachments** | `src/attachment-registry.ts`, `attachment-magic`, `generated-artifact-attachments`, `session-attachment-history`, `document-preview-cache`, `document-thumbnailer`, `document-conversion-limiter`, `config/attachment-guard` | See Key Patterns | | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`) | `templates/` holds the CLAUDE.md scaffold generated into new cases | -| **Web** | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (24 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` | | -| **Frontend** | `src/web/public/app.js` (~5K lines, core) + 30 modules + `sw.js` | See Frontend section for the load order, which is authoritative | +| **Web** | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (25 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` | | +| **Frontend** | `src/web/public/app.js` (~6.7K lines, core) + 31 modules + `sw.js` | See Frontend section for the load order, which is authoritative | | **Types** | `src/types/index.ts` (barrel) → 22 domain files; also `src/types.ts` root re-export | See `@fileoverview` in index.ts | ★ = Large, central file (>50KB) — read its `@fileoverview` first. All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`. @@ -174,7 +176,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **Config**: `src/config/` — 21 files, no barrel (`index.ts`) exists; import from the specific file. -**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver`/`antigravity-cli-resolver`/`pi-cli-resolver`/`grok-cli-resolver` (CLI path resolution; ⚠ `pi-cli-resolver` and `grok-cli-resolver` additionally version-probe the binary, since `pi` is a generic name and `grok` has npm squatters), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority). +**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver`/`antigravity-cli-resolver`/`pi-cli-resolver`/`grok-cli-resolver`/`deepseek-cli-resolver`/`omp-cli-resolver` (CLI path resolution, one per `SessionMode`, all nine sharing the lookup chain in `cli-executable-resolver`: server PATH, then that CLI's install dirs, then an interactive login shell LAST, since it is the only step that spawns anything and it is what finds nvm/Homebrew installs under a service manager's minimal PATH; ⚠ `pi-`, `grok-` and `deepseek-cli-resolver` additionally probe the binary's identity, since `pi` is a generic name, `grok` has npm squatters, and Debian ships an unrelated `dsh`), `file-query` (⚠ Files-panel search matcher, glob-by-two-pointer, never RegExp), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority), `shell-resolver` (⚠ resolves a real login shell for `mode: 'shell'`; the literal string `$SHELL` used to be expanded by the SERVER's shell, which is empty in a container), `event-loop-monitor` (a sync `execSync` freezes the port while the process stays alive, leaving no trace), `dependency-checker` + `dependency-report` (the `codeman doctor` probe engine, registry in `config/dependency-registry.ts`). ### Data Flow @@ -193,6 +195,10 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph ⚠️ **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. +**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). + +**Process-tree walks are bounded** (`proc-tree.ts`, pure + unit tested): `collectDescendants(pid, byParent)` is the ONE descendant traversal, fed by a single cached `ps -eo pid=,ppid=` snapshot (`refreshProcSnapshot()` in tmux-manager.ts: in-flight-shared, async because `execSync`'s timeout cannot return at all while spawnSync waits on an unkillable child, and ANY error discards the result rather than caching a truncated `ps`, which would make whole subtrees invisible to the kill path). ⚠️ **The unbounded version took a machine down** (2026-07-30): it ran `pgrep -P ` once per node and recursed with no visited set, no depth limit and no node cap, so across ~28 adopted tmux trees the fan-out exploded while each `pgrep` blocked in the WSL kernel reading `/proc//cgroup`, ending at ~13,000 `pgrep` processes in D-state, a load average above 13,000, and a machine recoverable only by restarting WSL, which cost every running session. Three properties make that impossible and each has a test: a cycle terminates (a real tree has none, a stale snapshot can still produce one), depth is capped (`PROC_WALK_MAX_DEPTH`), node count is capped (`PROC_WALK_MAX_NODES`). The fourth is structural: the function takes a snapshot and cannot spawn anything at all. ⚠️ It lives in its own module because as a private method of `tmux-manager.ts` the regression test had to keep its own COPY of the algorithm, which is a test that passes while the shipped code rots. ⚠️ Truncation is reported through `onTruncated` rather than silently, with BOTH caps named: a silent depth cap hides a deep tree exactly as effectively as a silent node cap hides a wide one. + **Auto-resume on usage limit** (opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit, `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time and `SessionAutoOps` arms a timer for reset+2min, then sends Esc + `continue`. ⚠️ Respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected`), which is what prevents `/clear` from wiping the paused conversation. Claude-mode only. → [architecture-invariants#auto-resume-on-usage-limit](docs/architecture-invariants.md#auto-resume-on-usage-limit) **Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the Claude `statusLineTelemetry` flag on session create). It renders compact Claude and Codex provider rows. Claude data comes from Codeman's marked `statusLine.command` exporter, which POSTs `rate_limits` to `POST /api/status-telemetry`, never overwrites a user's hand-authored statusLine, and prints the footer through. Main Codex usage comes from a read-only host `account/rateLimits/read` app-server poll at startup and every 5 minutes; exclude model-specific buckets such as Spark, and omit the Codex row when no signed-in limit is available. Distinct from auto-resume, which reacts to Claude's limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md` @@ -201,11 +207,17 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **Cron (`CronJob`s)**: saved, named jobs on a recurring schedule (`once`/`interval`/`daily`/`weekly`) with per-job run history. ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded loop); the two never interact and keep separate `Scheduled*` / `Cron*` names. `CronService` **reuses the existing session layer** rather than rebuilding tmux logic. Next-run math is pure and unit-tested in `cron-time.ts` (server-local timezone). The schedule is advanced BEFORE launch so a slow launch cannot re-trigger. → [architecture-invariants#cron-jobs](docs/architecture-invariants.md#cron-jobs), `docs/cron-discovery.md` -**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs inside a durable remote `tmux -L codeman-remote` (session name `codeman-ssh-`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so an instance on the target host never adopts it), fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill** on tab close; owned ones propagate `kill-session`. A bounded-backoff watcher auto-reconnects dropped sessions (`remoteAutoReconnect`, default ON). ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**, which `shellescape`s every user field. Never hand-build an ssh line elsewhere. ⚠️ Run flows must route remote cases through `POST /api/quick-start`, not `POST /api/sessions` (which stat-validates `workingDir` locally and has no `caseName`). → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md` +**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs inside a durable remote `tmux -L codeman-remote` (session name `codeman-ssh-`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so an instance on the target host never adopts it), fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill** on tab close; owned ones propagate `kill-session`. A bounded-backoff watcher auto-reconnects dropped sessions (`remoteAutoReconnect`, default ON). ⚠️ **It revives ONLY when the durable remote tmux session is verifiably still alive** (`remoteTmuxSessionAlive()`, a `has-session` probe over ssh, #355): a clean agent exit (Ctrl-C, Ctrl-D, `exit`) tears that session down, and `isPaneDead()` cannot tell it from a transport drop, so the watcher used to relaunch a FRESH agent after every clean exit (claude only looked fine because its `|| --resume` fallback masked it). An unreachable host answers `undefined`, which also means do not revive. ⚠️ `has-session` prints NOTHING on success, so the probe is classified by EXIT STATUS (`classifyRemoteAliveExit`: 0 alive, ssh's 255 or a timeout unknown, anything else gone); reading stdout classified every live session as gone and silently disabled transport-drop reconnects. The answer is cached per session and forgotten whenever the pane is seen alive again, or a stale `true` from one transport drop would revive the next clean exit. ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**, which `shellescape`s every user field. Never hand-build an ssh line elsewhere. ⚠️ Run flows must route remote cases through `POST /api/quick-start`, not `POST /api/sessions` (which stat-validates `workingDir` locally and has no `caseName`). → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md` -**Docker cases**: a case can point at a **container**, with any of the CLI run modes running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a `SessionMode` of its own**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design) +**Docker cases**: a case can point at a **container**, with any of the CLI run modes running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a `SessionMode` of its own**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ A case may instead **ADOPT** a container the user already runs (`DockerCase.owned === false`, mirror of remote-SSH's `owned:false`): Codeman only `exec`s into it and never creates, starts, stops, restarts or removes it, so a missing or stopped container FAILS CLOSED with an actionable message instead of being fixed. Absent = owned, so existing cases are byte-identical. The guarantee is enforced at four independent layers because it cannot be observed by using the feature: `buildDockerStopCommand`/`buildDockerRemoveCommand` throw during pure STRING CONSTRUCTION, `removeDockerContainer` refuses again, drift reports "none" (an adopted container carries no `codeman.confighash` label, so a real comparison would 409 the launch forever), and the boot reaper skips it. ⚠️ Two lifecycle touches the original design missed and that are easy to re-introduce: the full-image export `docker commit`s the container (refused for an adopted case) and the workspace export `docker pause`s it first (skipped — it freezes the owner's processes for the length of the tar). ⚠️ `owned` is applied AFTER `dockerConfigHash`, which takes an explicit field list, or every pre-existing case would trip the drift gate at once. ⚠️ Run modes for a container case come from the CONTAINER (`availableModes`, live-probed): gating the run menu on HOST CLIs (#201) is right for local sessions and wrong here, since a host with no `claude` may run a container that ships one. ⚠️ **A failed probe means opposite things per ownership** — for an ADOPTED case it is a fault worth reporting, for an OWNED one it is the NORMAL state before the first session (the launch chain creates the container), so treating it as a fault hid every agent mode on every freshly linked Docker case behind "start it yourself first". That is why `CaseInfo.docker.owned` is on the wire. ⚠️ Claude is launched WITHOUT `--dangerously-skip-permissions` when the container's exec user is root (Claude Code refuses the flag as root and the refusal is visible only inside the container); which flag to drop is a per-CLI fact, so it is the registry's `overlays.docker.rootCommand`, never a branch. ⚠️ Adoption is **admin-only in multi-user mode**, unlike `docker-link`: linking creates OUR container, whose one bind mount `isWorkingDirAllowed` has already confined, while an adopted container's mounts belong to its owner and one mounting `/` hands the adopter the host. The same reasoning admin-gates the container listing and the in-container directory browser; the preflight instead admits a non-admin for a container already linked to a case they own, because the run menu probes it for every docker case. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design) -**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek)**: `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 seven **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/` 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 `_configureDeepSeek()` 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 config clamp removed. `clampEnvOverridesForOwner()` (session-routes.ts) DROPS `DSH_PERMISSION_MODE`, `DSH_HOME` and `DEEPSEEK_BASE_URL` for a non-granted owner (the last because `_configureDeepSeek()` forwards the SERVER's own `DEEPSEEK_API_KEY` into the pane, so a redirected base URL would send it to a foreign host) (dropping falls through to what `_configureDeepSeek()` exports, which is the clamped value); `DSH_HOME` is there because it points the launcher at a profile tree whose plugin code runs at BOOT, before any approval row applies. Every OTHER CLI's bypass is a command-line flag reachable only through its config, which is why the config clamp alone is the whole gate for them. (3) It is the **only non-claude mode that passes `hooksAvailableForMode()`**, and for it alone that predicate is a per-SESSION question rather than a per-mode one (`deepSeekConfig.statusReporting: false` disarms the bridge, so every call site passes `sessionHookOptions(session)`; answering from the mode there re-creates the infinite-wait-dressed-as-a-timeout the guard exists to prevent). It passes because the terminal front door reports idle/working/blocked to a supervisor over a generic env-gated contract and `deepseek-status-shim.ts` makes Codeman that supervisor — real `stop`/`blocked` signals, real Approvals Inbox items, plus the `agent_working` event that clears an alert answered in the terminal. ⚠️ The resolver needs the strictest identity probe of the family (`dsh --help` must say `DeepSeek Harness`) because Debian ships an unrelated `dsh` (dancer's shell) that would pass a version probe. Model is NOT a session field (it is a profile composition entry). ⚠️ `hooksAvailableForMode()` is about hook SIGNALS and is not a stand-in for "is this a claude session": Read My Mind and intent capture read Claude's own transcript and compare `mode === 'claude'` directly, because when `deepseek` earned a yes the shared predicate silently widened both to a mode with no transcript to read (pinned by a static check in `test/deepseek-mode.test.ts`). ⚠️ **It is also the only external CLI whose answers are READ FROM DISK rather than scraped off the pane**: `deepseek-transcript.ts` reads `$DSH_HOME/sessions///session.jsonl.zstd` and backs the `last-response` route for dsh, because the pane segmenter served dsh-TUI's ASCII-art SPLASH as the worker's answer (measured), which anything polling for a first answer reads as an answer. Three traps live in that file: dsh appends **one zstd FRAME per write** and Node's `zlib` zstd decoder stops at the first (a real 56-line transcript decoded as 1 line, so the module walks frame headers itself; a Node older than 22.15 has no zstd and falls back to the pane); every turn also records a **plugin-sourced `user/message`** (the runtime-context snapshot) that must not render as the user's words; and a failed `turn/end` is surfaced as `Turn error: …` rather than as an empty string that reads as "still thinking". ⚠️ Session→transcript pairing is by the header's own `cwd` plus a ±60 s boot window, never by reproducing dsh's directory mangling (which has already changed form once) — and NEVER by newest-mtime alone, which handed a fresh worker its predecessor's answer in the same case dir. DeepSeek's own tests: `test/deepseek-mode.test.ts`, `test/deepseek-cli-resolver.test.ts`, `test/deepseek-transcript.test.ts`; user guide `docs/deepseek-integration.md`. → [architecture-invariants#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek) +**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 ` 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 '':` 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 `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/` 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 config clamp removed. `clampEnvOverridesForOwner()` (session-routes.ts) DROPS `DSH_PERMISSION_MODE`, `DSH_HOME` and `DEEPSEEK_BASE_URL` for a non-granted owner (the last because `_configureCliEnv()` forwards the SERVER's own `DEEPSEEK_API_KEY` into the pane, so a redirected base URL would send it to a foreign host) (dropping falls through to what `_configureCliEnv()` exports, which is the clamped value); `DSH_HOME` is there because it points the launcher at a profile tree whose plugin code runs at BOOT, before any approval row applies. Every OTHER CLI's bypass is a command-line flag reachable only through its config, which is why the config clamp alone is the whole gate for them. (3) It is the **only non-claude mode that passes `hooksAvailableForMode()`**, and for it alone that predicate is a per-SESSION question rather than a per-mode one (`deepSeekConfig.statusReporting: false` disarms the bridge, so every call site passes `sessionHookOptions(session)`; answering from the mode there re-creates the infinite-wait-dressed-as-a-timeout the guard exists to prevent). It passes because the terminal front door reports idle/working/blocked to a supervisor over a generic env-gated contract and `deepseek-status-shim.ts` makes Codeman that supervisor — real `stop`/`blocked` signals, real Approvals Inbox items, plus the `agent_working` event that clears an alert answered in the terminal. ⚠️ The resolver needs the strictest identity probe of the family (`dsh --help` must say `DeepSeek Harness`) because Debian ships an unrelated `dsh` (dancer's shell) that would pass a version probe. Model is NOT a session field (it is a profile composition entry). ⚠️ `hooksAvailableForMode()` is about hook SIGNALS and is not a stand-in for "is this a claude session": Read My Mind and intent capture read Claude's own transcript and compare `mode === 'claude'` directly, because when `deepseek` earned a yes the shared predicate silently widened both to a mode with no transcript to read (pinned by a static check in `test/deepseek-mode.test.ts`). ⚠️ **It is also the only external CLI whose answers are READ FROM DISK rather than scraped off the pane**: `deepseek-transcript.ts` reads `$DSH_HOME/sessions///session.jsonl.zstd` and backs the `last-response` route for dsh, because the pane segmenter served dsh-TUI's ASCII-art SPLASH as the worker's answer (measured), which anything polling for a first answer reads as an answer. Three traps live in that file: dsh appends **one zstd FRAME per write** and Node's `zlib` zstd decoder stops at the first (a real 56-line transcript decoded as 1 line, so the module walks frame headers itself; a Node older than 22.15 has no zstd and falls back to the pane); every turn also records a **plugin-sourced `user/message`** (the runtime-context snapshot) that must not render as the user's words; and a failed `turn/end` is surfaced as `Turn error: …` rather than as an empty string that reads as "still thinking". ⚠️ Session→transcript pairing is by the header's own `cwd` plus a ±60 s boot window, never by reproducing dsh's directory mangling (which has already changed form once) — and NEVER by newest-mtime alone, which handed a fresh worker its predecessor's answer in the same case dir. DeepSeek's own tests: `test/deepseek-mode.test.ts`, `test/deepseek-cli-resolver.test.ts`, `test/deepseek-transcript.test.ts`; user guide `docs/deepseek-integration.md`. OMP (`omp`) needs no bypass flag (the CLI's own `~/.omp` config governs trust/model routing, defaulting to `tools.approvalMode: yolo`), so its registry entry declares `privilegedParams: []` and a launch spec that only ever passes `--model`/`--resume`/`--continue` — but the multi-user clamp is NOT a no-op for it: `OMP_*` is an allowlisted `envOverrides` prefix, and the two credential-resolution keys it admits, `OMP_AUTH_BROKER_URL`/`OMP_AUTH_BROKER_TOKEN`, are clamped in `clampEnvOverridesForOwner()` for a non-granted owner, the same shape as `DEEPSEEK_BASE_URL`. Separately, `PI_*` is already allowlisted (pi needs it) and omp reads several of its knobs too (`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, `PI_SUBPROCESS_CMD`, `PI_SHELL_PREFIX`) — a redirected `PI_CONFIG_DIR` moves the `~/.omp` tree `omp-session-resolver.ts`/`omp-transcript.ts` hardcode, silently breaking pinning/history; this is a known gap shared with pi, not fixed here. → [architecture-invariants#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek-omp](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek-omp) + +**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. **Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w-` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. ⚠️ **Closing has the mirror-image race and one owner**: `closeSession()` reads `wasActive` BEFORE its `await` and announces the delete via `_closingSessions`, while `_onSessionDeleted` skips the active-session handoff for an id in that set. Both used to read `activeSessionId` after the fact, so the `session_deleted` broadcast for your own delete could null it first and closing the tab you were on landed on the welcome screen instead of the next session, on the same build, depending on timing. The fallback also picks the first order entry that is still in `sessions` (a dead id can linger in `sessionOrder`, same reason Alt+N indexes a live-filtered list). A delete from ANOTHER client still shows the welcome screen, which is the honest answer when what you were looking at was taken away. Tests: `test/session-close-fallback.test.ts`. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization) @@ -213,6 +225,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **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) +**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`. + **Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`. ⚠️ **Every claude session INSTALLS the hooks block into its workspace** (`applyWorkspaceHooks` in hooks-config.ts → `ensureCodemanHooks`, an add-only merge that keeps a user's own handlers), from EVERY claude create path — both interactive routes, cron fires, legacy scheduled runs, the plan-orchestrator one-shots — and from `restoreMuxSessions()` for sessions recovered on server start (that boot sweep skips a workspace that no longer exists, so a deleted repo with a surviving tmux session is never resurrected as an empty dir). Before 2026-08-15 hooks were written ONLY when Codeman created the case DIRECTORY, so a linked case / cloned repo — where most sessions actually run — had no hooks at all and every hook-driven surface was silently dead there: an AskUserQuestion dialog blocked the pane while the tab and the phone overview both read a calm `idle`, with no Approvals Inbox item, no push, no definitive `stop`/`idle_prompt` for respawn and no `stop`/`blocked` for the wait endpoints. The escape hatch is the synced `workspaceHooksEnabled` setting (App Settings → Agents & CLIs → Claude, **default ON**); OFF restores the old behavior, where a Codeman block that is already there is still refreshed when stale (COD-91) but one is never added. ⚠️ Route the decision through `applyWorkspaceHooks` rather than calling `ensureCodemanHooks` at a new site, or the setting silently stops applying to that path. ⚠️ Claude Code RE-READS `settings.local.json`, so an already-running session starts firing hooks without a restart (measured 2026-08-15) — and the notification for a blocking dialog is delayed by Claude Code (~30s), so the alert trails the dialog. ⚠️ An AskUserQuestion / plan-selection dialog arrives as **`permission_prompt`**, not `elicitation_dialog` (that one is MCP elicitation), so it renders as the RED "needs you" alert, not the yellow idle one. **Approvals Inbox** (cross-session queue of prompts waiting on a human; `approvalsInboxEnabled`, SYNCED, default OFF: every surface is opt-in; only the store and answer endpoints run regardless, so flipping it ON shows anything already pending): `web/approval-inbox.ts` is a `sessionWaits`-style singleton fed by `/api/hook-event`, holding at most ONE item per session (a new prompt supersedes), claude-mode only, in-memory. Cards are answered via `POST /api/approvals/:id/answer`, which sends a digit / Esc / idle-prompt text through `writeViaMux` (menu answers never carry `\r`). ⚠️ `option` digits are accepted ONLY when they match options parsed from the captured pane frame, and the answer path RE-CAPTURES the pane first (a dialog that no longer parses on screen means the keystroke would land in the composer, so refuse with 409). ⚠️ Resolution on the heuristic `working` signal ALONE is restricted to `idle` items; a permission/question item gets the pane-VERIFIED variant on that same signal (`resolveIfDialogGone()` → `verifyStillAnswerable()`), so the heuristic only decides when to LOOK and the screen decides the outcome. That is what clears a dialog answered in the terminal mid-turn; the other definitive signals are `stop`, `elicitation_complete`/`elicitation_response`, exit/delete, answer, supersede and the 12h TTL. ⚠️ **Viewing a session ACKNOWLEDGES its idle item, it does not resolve it** (`POST /api/approvals/session/:sessionId/viewed` → `acknowledgedAt` → `approval:updated`): the item stays pending (still answerable, still Read My Mind context) and only stops arming the yellow tab alert. That flag is what makes the clear durable, since the view-clears-idle rule used to live in one browser's memory and `seedApprovals()` re-armed the alert on the next reload while other devices never heard about it at all; the local half is `markIdleAlertSeen()` (app.js), called from BOTH `selectSession` paths, including the already-active early return, where a click could otherwise never clear the alert. ⚠️ **Only a HUMAN opening a session acknowledges**: `selectSession(id, { auto: true })` marks the three selections the APP makes (boot restore, a solo window opening its target, the fallback after the active session is closed) and skips the acknowledgement, so a page load cannot silently spend an alert the user never saw. The flag defaults to user-initiated, so an untagged call site fails toward acknowledging rather than toward an alert nothing can clear; `test/session-select-ack-gate.test.ts` pins both the gate and the tagged call sites. Idle-only by construction (`acknowledge()` defaults to `['idle']`): looking at a permission/question dialog does not answer it. ⚠️ Same rule on the input path: `_ackDelivery` (app.js) spends the IDLE alert only, via that same `markIdleAlertSeen()`. It used to `clearPendingHooks(sessionId)` with no kind, so one keystroke wiped a RED alert on that device while the dialog was still up, the other devices stayed red, and a reload re-seeded it. ⚠️ Claude Code fires no "permission answered" hook (only `elicitation_complete`/`elicitation_response`, i.e. the question flavor), so an answered-in-the-terminal dialog would otherwise sit pending until `stop`: `GET /api/approvals` therefore runs a **staleness sweep** over the caller's own items via `verifyStillAnswerable()`, which is deliberately the conservative check the answer path uses (only an item whose ORIGINAL frame parsed options can be dropped, so an unreadable capture keeps the alert rather than losing a live one). ⚠️ **`applyCapture()` is therefore ADD-ONLY for `options`**: a re-capture that parses nothing must never erase a parse an earlier one found. Claude Code delays the Notification hook behind the dialog (measured 6s, documented ~30s), so the 600ms re-capture routinely lands on a frame the user has ALREADY answered; clearing the field there made the item permanently unsweepable, because `verifyStillAnswerable()` reads a MISSING `options` as "we never could read this dialog" and keeps such items answerable by design. The red "needs you" then survived every sweep AND every page reload, went away only on `stop` (2026-08-20: a confirmed question left a tab flowing red for ~8 minutes while the turn ran on), and the stale card still accepted an answer, typing a bare `1` into a composer with no dialog under it. Pinned by `test/approval-inbox.test.ts`. ⚠️ A frame that parses no options is CONCLUSIVE in exactly two cases, and the second one closes the late-hook hole: the item once parsed options (they cannot vanish while the dialog is up), or the frame shows Claude actively running a turn. A modal dialog BLOCKS the turn, so the two cannot coexist — measured on v2.1.237, a live-dialog frame carries neither the `… (13s` timer NOR the `esc to interrupt` footer, which the dialog replaces with `Enter to select · ↑/↓ to navigate · Esc to cancel`. Anything else stays answerable, so an unreadable capture still keeps the alert. That second signal is reached by a delayed staleness pass (`STALE_CHECK_DELAY_MS`, 3s) scheduled alongside the re-capture, because a prompt answered BEFORE the hook lands creates an item whose FIRST capture already has no dialog in it: nothing ever parsed, `stop` may have fired already, and the alert then outlived reloads until the 12h TTL. ⚠️ That pass must stay comfortably LATER than `RECAPTURE_DELAY_MS`, whose whole reason for existing is that the hook can beat Ink to the screen — resolving inside the paint window would clear the alert for a dialog that was about to appear. The frontend seeds from `GET /api/approvals` in `handleInit` **regardless of the setting**: the seed re-arms the tab-alert state machine (`setPendingHook`) unconditionally, and only populating `this.approvals` (the inbox surfaces) is gated — seeding used to be gated wholesale, which left a reloaded page with NO red tab while a permission dialog sat blocking a session (2026-08-15); `_onApprovalResolved` clears the pending-hook alert unconditionally for the same reason. ⚠️ The red/yellow tab alert itself is a STEADY border/background/dot with a pulse on top: the original keyframes swung to transparent at 0%/100%, so half of every cycle looked like a normal tab. Push Approve/Deny buttons stay gated on the setting (`sendPushNotifications` strips `actions`/`approvalId` when OFF) and are answered from `sw.js` directly so they work with no tab open. Surfaces (all gated on the setting): header bell (marker-hidden until count > 0, phones never show it) + drawer (`approvals-ui.js`), phone overview NEEDS YOU answer strips (`mobile-overview.js`). Design: `docs/approvals-inbox-plan.md`. @@ -231,11 +245,10 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **Auto Copy (copy-on-select)** (`autoCopySelection`, per-device, default OFF): a finished terminal selection lands on the clipboard with no keystroke. ⚠️ It fires at the END of a gesture, never in `onSelectionChange` (that callback runs per cell crossed, so copying there is one clipboard write per mouse move); it only ARMS `_autoCopyPending`, and a document-level `mouseup` listener flushes. ⚠️ The flush is SYNCHRONOUS inside the handler because both clipboard paths need user activation (Firefox gates `navigator.clipboard.writeText` on it, and the plain-HTTP `execCommand` fallback must run in the gesture's own task); a timer or a wait for `onSelectionChange` loses it, invisibly in Chrome. ⚠️ Touch needs its OWN calls from `_endTouchSelectionGesture()`/`_selectTouchSelectionLine()`: that path `preventDefault()`s its touchend, so no mouseup ever arrives and the toggle would be dead on phones. ⚠️ Unlike `copyTerminalSelection()` it must NOT clear the selection (the text would vanish under the cursor that highlighted it) and must NOT focus the terminal (that opens the on-screen keyboard over it); focus is RESTORED to whatever held it, which only matters for the `execCommand` fallback. Guards are pure in `decideAutoCopy()` (constants.js): off, blank/whitespace-only, and a 1M-char cap (an autoscrolling drag can sweep the whole 50k-line scrollback), refused rather than truncated with a toast pointing at Ctrl+C. Silent on success except once per page load; failures toast, throttled 10s. Tests: `test/terminal-auto-copy.test.ts`. -**Terminal scrollback strip + wheel/touch forwarding** (#205): codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed shell/opencode/antigravity get a NARROW strip (alt-screen toggles only — it removes tmux's own attach-time `smcup`, which otherwise parks xterm in the scrollback-less alt buffer and turns the wheel into arrow keys). ⚠️ Gated on `useMux`: direct-PTY fallback sessions must keep the alt screen for vim/less/htop. Wheel AND touch forward to the CLI transcript for **claude ≥ 2.1.187 ONLY** at ANY scroll position (snap-to-bottom first); Shift+wheel and the `terminalWheelLocalScrollback` setting stay local. ⚠️ Codex was in that list and must never go back without a fresh measurement: codex-cli 0.147.0 ignores SGR wheel reports entirely (`mouse_any_flag=0`, inline viewport, transcript pushed into terminal scrollback), so forwarding produced a dead wheel (#227 follow-up). `_wheelScrollLines()` reads `ev.deltaMode` (Firefox = LINE units). ⚠️ When that gate is FALSE on a claude session whose local buffer is hollow (`baseY === 0`), the gesture becomes coalesced PageUp/PageDown key sends (`_maybePageCliTranscript`) instead of a no-op; ⚠️ and `getClaudeCliVersion()` must never cache a FAILED probe (one timeout used to disable forwarding process-wide until restart). ⚠️ **A click is hand-reported to the CLI only while the CLI actually has mouse tracking on.** The full strip removes the mouse DECSETs, so xterm's `mouseTrackingMode` is permanently `none` there and the browser hand-encodes SGR reports (`_sendSyntheticSgrTap`); without state it did that on EVERY click, so a stripped-mode pane running a plain shell (CLI exited, or a shell started inside a claude-mode session) received reports it never asked for and printed them as literal text (`[<0;88;20M`), garbling the next typed line. `_recordStrippedMouseMode()` (session.ts) records what the strip removes, `toState()` publishes `cliMouseTracking`, and `_shouldReportMouseToCli()` gates all three report sites on it. Only 1000/1001/1002/1003 count (1005/1006 are encodings, 1007 is alt-scroll), and the change broadcasts UNdebounced since a dialog can be clicked inside the 500ms window. `_logScrollRouting()` prints the routing decision and its inputs once per session — read it before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding) - +**Terminal scrollback strip + wheel/touch forwarding** (#205): codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed shell/opencode/antigravity/omp get a NARROW strip (alt-screen toggles only — it removes tmux's own attach-time `smcup`, which otherwise parks xterm in the scrollback-less alt buffer and turns the wheel into arrow keys). ⚠️ Gated on `useMux`: direct-PTY fallback sessions must keep the alt screen for vim/less/htop. Wheel AND touch forward to the CLI transcript for **claude ≥ 2.1.187 ONLY** at ANY scroll position (snap-to-bottom first); Shift+wheel and the `terminalWheelLocalScrollback` setting stay local. ⚠️ Codex was in that list and must never go back without a fresh measurement: codex-cli 0.147.0 ignores SGR wheel reports entirely (`mouse_any_flag=0`, inline viewport, transcript pushed into terminal scrollback), so forwarding produced a dead wheel (#227 follow-up). `_wheelScrollLines()` reads `ev.deltaMode` (Firefox = LINE units). ⚠️ When that gate is FALSE on a claude session whose local buffer is hollow (`baseY === 0`), the gesture becomes coalesced PageUp/PageDown key sends (`_maybePageCliTranscript`) instead of a no-op; ⚠️ and `getClaudeCliVersion()` must never cache a FAILED probe (one timeout used to disable forwarding process-wide until restart). ⚠️ **A click is hand-reported to the CLI only while the CLI actually has mouse tracking on.** The full strip removes the mouse DECSETs, so xterm's `mouseTrackingMode` is permanently `none` there and the browser hand-encodes SGR reports (`_sendSyntheticSgrTap`); without state it did that on EVERY click, so a stripped-mode pane running a plain shell (CLI exited, or a shell started inside a claude-mode session) received reports it never asked for and printed them as literal text (`[<0;88;20M`), garbling the next typed line. `_recordStrippedMouseMode()` (session.ts) records what the strip removes, `toState()` publishes `cliMouseTracking`, and `_shouldReportMouseToCli()` gates all three report sites on it. Only 1000/1001/1002/1003 count (1005/1006 are encodings, 1007 is alt-scroll), and the change broadcasts UNdebounced since a dialog can be clicked inside the 500ms window. `_logScrollRouting()` prints the routing decision and its inputs once per session — read it before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding) **Detached start + service install** (issue #231): `codeman web -d` relaunches the SAME entry script with `detached:true` (setsid), so there is no controlling terminal and no shell job entry. ⚠️ `nohup` is NOT what makes this work: Node re-arms SIGHUP to its default disposition even when it inherits "ignore", and `cli.ts` handles SIGHUP with a graceful shutdown, so a delivered HUP still stops the server. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile check + `/api/status` probe): a second instance on the shared tmux socket attaches PTYs to the first one's live sessions. ⚠️ Neither may report success it has not observed — the parent polls `/api/status` until the child answers or dies, since `launchctl load` and a clean spawn are both silent about a server that starts and immediately exits. `--stop` verifies the pid still LOOKS like a Codeman server (`ps -o command=`) before signalling, because pids get recycled. Unit/label names live in `config/service-names.ts` so install.sh, `detectSupervisor()` and `service install` cannot drift into supervising two copies; they are instance-scoped, and identical to the historical names for the default instance. `service install` bakes the installing shell's PATH into the unit (launchd gives a job `/usr/bin:/bin:/usr/sbin:/sbin`, which finds neither a Homebrew/nvm `node` nor `tmux`/`claude`) and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install) -**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update) +**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. ⚠️ **The Compose deployment is the one supervisor that does NOT outlive the restart**: there the restart IS the container exiting (`restart: unless-stopped` relaunches it), which kills the script too — safe only because the terminal `restarting` marker is written BEFORE the kill, so nothing may be appended after it. Two config facts make it work at all and both are load-bearing: the repo is a HOST BIND MOUNT over `/opt/codeman` (a pull into the baked image copy would land in the writable layer and be silently discarded by the next `up`), and the runtime image keeps devDependencies + a build toolchain (`npm run build` is tsc+esbuild, and node-pty has no Linux prebuild), which is why `npm prune --omit=dev` is gone and the updater passes `--include=dev` against `NODE_ENV=production`. ⚠️ An in-place container update applies CODE ONLY — a restart reuses the existing image and config — so `evaluateEnvironmentGate()` REFUSES a release that changes `server.Dockerfile`/`docker-compose.yaml` (sha256 vs the baseline `Start-Codeman.sh` writes to `docker-env-applied.json` on every start) or adds `.env.example` keys the user's `.env` lacks, and refuses when the restart policy would not bring the container back. That third check exists because **Compose resolves an unset `${VAR}` to the EMPTY STRING and starts anyway**, so a new required setting otherwise arrives as a silently blank env var. Every unknown fails OPEN in the gate (no baseline, unreadable `.env`, no socket): failing closed would permanently block containers created before the fingerprint file existed. ⚠️ The KILL does not: the server exits only when `--restart-by-exit 1` was passed, i.e. the Compose file declared `CODEMAN_RESTART_BY_EXIT=1` (set ONLY there, since that file is what sets `restart: unless-stopped`; the image ENV deliberately does not) or the daemon reported an auto-restart policy; otherwise the build lands as `completed-needs-manual-restart`, because exiting blind takes a `docker run` container with no restart policy down with no UI left to recover it. The gate is re-evaluated on `POST /api/system/update`, so hiding the button is UX, not the control. ⚠️ The four global agent CLIs in `server.Dockerfile` are PINNED on purpose — unpinned, a user's CLI versions are a function of when their image was built rather than of any commit, which is the one environment change no diff-derived gate can see; pinning turns it into a Dockerfile change the gate already catches. `test/docker-compose-env-parity.test.ts` is the merge-side guard (every compose `${VAR}` ↔ an `.env.example` entry). → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update) **Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments) @@ -245,6 +258,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **File Viewer edit mode** (issue #212): the file-preview overlay edits workspace text files in place — `GET .../file-content?edit=1` + `PUT /api/sessions/:id/file-content`, policy in `src/config/file-editing.ts`. This is a **third file surface and the only one that WRITES**: read-path confinement (realpath + workspace + ownership) plus sensitive/blocked/`.git` denies and an extension **allowlist**; writes are `wx`-temp + rename (no `O_CREAT` anywhere = edit-in-place is structural); optimistic concurrency via sha256 `baseHash` → 409. ⚠️ `edit=1` never truncates and the client must never save a plain-preview buffer (the 500-line truncation would silently delete the rest). ⚠️ CRLF/UTF-8 guards: EOL re-applied server-side, non-UTF-8 refused via round-trip compare. → [architecture-invariants#file-viewer-edit-mode](docs/architecture-invariants.md#file-viewer-edit-mode), `docs/file-viewer-edit-plan.md` +**Files panel search** (COD-236, the `q` param on `GET /api/sessions/:id/files`): `compileFileQuery()` (`utils/file-query.ts`, pure, no IO, so it unit-tests directly) compiles the query into a reusable predicate, which is what lets the server-side walk prune instead of streaming the whole tree. ⚠️ **A query turns that endpoint into a FLAT match list rather than a nested tree**, and the walk deliberately recurses past non-matching directories, since the whole point of searching is to reach a file whose ancestors do not match. An empty or whitespace-only query compiles to `null`, which is what keeps the default tree response byte-identical when no search is requested. ⚠️ **Globs are never compiled into a RegExp**: `*a*a*a…` translated to `^.*a.*a.*a…$` is a classic backtracking blowup evaluated synchronously against every walked path, so one pathological query would freeze the event loop for the whole server (the same reason `search-service.ts` is regex-free). `globMatch()` is a two-pointer wildcard walk instead, O(text · pattern) with both operands short by construction, and an overlong query (`MAX_QUERY_LENGTH`, 256) also compiles to `null` rather than running. A query containing `/` matches the relative path, otherwise the bare entry name; globs match anchored and case-insensitively (`*` spans any run, slashes included, `?` exactly one character), everything else is a plain case-insensitive substring. + **Raw file bodies are streamed and range-aware**: `file-raw` and the attachments `/raw` route always advertise `Accept-Ranges: bytes` and answer a `Range` header with `206` + `Content-Range` (single-range only; parser is pure + unit-tested in `src/web/http-range.ts`, a malformed spec is ignored → 200 while an out-of-bounds one is a 416). ⚠️ A 200-only response is what made the File Viewer's `