fix(docker): close the three adoption gaps the negative guarantee missed

Review follow-ups to #357. Each is a path that still touched, or still hid, a
container Codeman does not own.

**Export still mutated it.** The four fail-closed layers cover create/start/
stop/remove, but `POST /api/docker-cases/:name/export` reaches the container
twice through neither: a full export `docker commit`s it, and even a
workspace-only export `docker pause`s it first for snapshot consistency. Pause
freezes the owner's processes for as long as the tar takes, on a container we
promised not to touch. Full export is refused for an adopted case (it packages
someone else's container, with their logins, into a bundle Codeman hands out);
workspace-only keeps working and no longer pauses, accepting a live filesystem
the way `tar` does on any running host directory.

**A freshly linked OWNED case became unusable.** The run menu now probes the
container for its CLIs, and a failed probe hides every agent mode behind the
reason. For an adopted case that is right. For an owned one the container does
not exist until the first session launches it, so every newly linked Docker case
answered `container "codeman-case-x" not found (adoption never creates a
container — start it yourself first)` and offered nothing but Shell, for a
container the launch chain was about to create itself. A failed probe is
recorded only when the case is adopted; `CaseInfo.docker.owned` is on the wire
so the frontend can tell them apart. Verified in a browser: owned-with-no-
container offers all ten modes and no notice, adopted-but-stopped offers Shell
and says why.

**Multi-user gating.** Adoption is admin-only, unlike `docker-link` beside it.
Linking creates OUR container, whose sole bind mount `isWorkingDirAllowed` has
already confined to the caller's space; an adopted container's mounts are
whatever its owner gave it, so one mounting `/` hands the adopter a shell over
the whole host — exactly the workspace scoping multi-user mode exists to
enforce. Listing the engine's containers and browsing directories inside an
arbitrary one are machine-level reads and follow the docker-HOST policy for the
same reason. The preflight is deliberately not admin-only: the run menu fires it
for every docker case, so it admits a non-admin for a container already linked
to a case they can access, and nothing else.

Verified end to end against a real pre-existing root container (alpine + tmux,
no bind mounts): adopt, claude session inside it, workspace export, session
close and case unlink all left `StartedAt`, `RestartCount`, `Pid` and `Paused`
untouched; the pane ran the CONTAINER's claude, without
`--dangerously-skip-permissions`; a stopped container was refused at both
preflight and launch and was never started.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TecFD9hvPYJ1mkkMtBQbT1

src/docker-export.ts

@@ -30,6 +30,7 @@ import { spawn } from 'node:child_process';
 import { pipeline } from 'node:stream/promises';
 import type { DockerEngine, SessionDocker } from './types.js';
 import { runWithConversionLimit } from './document-conversion-limiter.js';
+import { isAdoptedContainer } from './docker-hosts.js';
 
 const IS_TEST_MODE = !!process.env.VITEST;
 
@@ -287,7 +288,13 @@ export async function exportDockerCase(params: {
     const bundlePath = join(exportsDir, exportBundleName(caseName, timestamp, mode));
     const stageDir = join(exportsDir, `.stage-${caseName}-${timestamp}`);
     mkdirSync(stageDir, { recursive: true });
-    const wasRunning = await isContainerRunning(argv, docker.containerName);
+    // ⚠️ NEVER pause an ADOPTED container. The freeze exists only to make the committed
+    // image and the workspace tar mutually consistent, and it is a lifecycle mutation on a
+    // container that belongs to the user — it stops their processes for however long the
+    // tar takes. A workspace-only export of an adopted case therefore accepts a live
+    // filesystem, the same guarantee `tar` gives on any running host directory. Full-image
+    // export is refused for an adopted case at the route, before reaching here.
+    const wasRunning = !isAdoptedContainer(docker) && (await isContainerRunning(argv, docker.containerName));
     let commitTag: string | undefined;
 
     try {

src/types/api.ts

@@ -174,6 +174,17 @@ export interface CaseInfo {
      * every CLI), which the UI reads as "do not gate".
      */
     availableModes?: string[];
+    /**
+     * `false` for an ADOPTED container (mirror of `DockerCase.owned`); absent = owned.
+     *
+     * ⚠️ The UI needs this to read a FAILED container probe correctly. For an adopted
+     * case a missing container is a real fault worth reporting, because the user is the
+     * only one who can start it. For an owned case it is the NORMAL state before the
+     * first session: the container is created on demand by the launch chain, so treating
+     * "not found" as a fault there hid every agent mode behind an error telling the user
+     * to start a container Codeman was about to create itself.
+     */
+    owned?: boolean;
   };
 }
 

src/web/public/session-ui.js

@@ -503,6 +503,11 @@ Object.assign(CodemanApp.prototype, {
     if (isDocker && !this._dockerCaseModes?.[caseName]) void this._probeDockerCaseModes(activeCase, menu);
     // An unreachable container hides every agent mode and explains why, instead
     // of silently offering modes that cannot start.
+    //
+    // ⚠️ ADOPTED cases only. For an OWNED case a missing container is the normal
+    // state before the first session — the launch chain creates and starts it — so
+    // reporting it as a fault hid every agent mode on a freshly linked Docker case
+    // behind "start it yourself first", for a container Codeman was about to create.
     const probeError = isDocker ? this._dockerCaseProbeError?.[caseName] : null;
     for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek', 'omp']) {
       const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`);
@@ -707,12 +712,19 @@ Object.assign(CodemanApp.prototype, {
         this._dockerCaseModes[name] = probe.availableModes;
         delete this._dockerCaseProbeError?.[name];
       } else {
-        // A container that cannot be probed — recreated, stopped, engine down —
-        // must NOT fall through to "show everything". Offering claude on a
+        // An ADOPTED container that cannot be probed — recreated, stopped, engine
+        // down — must NOT fall through to "show everything". Offering claude on a
         // container that is not running is a click that can only fail, with the
         // reason visible nowhere. Record the reason and say it in the menu.
-        this._dockerCaseProbeError = this._dockerCaseProbeError || {};
-        this._dockerCaseProbeError[name] = probe?.error || `Could not read container "${container}".`;
+        //
+        // ⚠️ An OWNED container gets no error: it does not exist until the first
+        // session launches it, so "not found" is the expected answer for every
+        // newly linked Docker case, and gating on it made those cases unusable.
+        // Leaving the cache empty reads as "unknown", which does not gate.
+        if (activeCase?.docker?.owned === false) {
+          this._dockerCaseProbeError = this._dockerCaseProbeError || {};
+          this._dockerCaseProbeError[name] = probe?.error || `Could not read container "${container}".`;
+        }
         delete this._dockerCaseModes[name];
       }
       // Only repaint while the menu the user opened is still on screen.

src/web/routes/case-routes.ts

@@ -300,6 +300,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
           path: dockerCase.hostWorkspacePath,
           network: host.network ?? 'bridge',
           ...(dockerCase.availableModes ? { availableModes: dockerCase.availableModes } : {}),
+          ...(dockerCase.owned === false ? { owned: false } : {}),
         },
       };
       const existingIndex = cases.findIndex((item) => item.name === dockerCase.name);
@@ -794,7 +795,15 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    */
   app.post(
     '/api/cases/docker-adopt',
-    async (req): Promise<ApiResponse<{ case: unknown; image?: string; availableModes?: SessionMode[] }>> => {
+    async (req, reply): Promise<ApiResponse<{ case: unknown; image?: string; availableModes?: SessionMode[] }>> => {
+      // ⚠️ Admin-only in multi-user mode, unlike `docker-link` right above. Linking
+      // creates OUR container, whose only bind mount is a workspace `isWorkingDirAllowed`
+      // has already confined. Adoption names a container someone else built, and its
+      // mounts are whatever its owner gave it — a container mounting `/` hands the
+      // adopter a shell over the whole host, which is exactly the workspace scoping this
+      // mode exists to enforce. Same machine-level reasoning as the docker HOST routes.
+      const denied = adminOnly(req, reply);
+      if (denied) return denied;
       const dockerCase = {
         ...parseBody(DockerCaseAdoptSchema, req.body),
         type: 'docker' as const,
@@ -880,7 +889,11 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    */
   app.get(
     '/api/docker-hosts/:hostId/containers',
-    async (req): Promise<ApiResponse<{ containers: DockerContainerInfo[] }>> => {
+    async (req, reply): Promise<ApiResponse<{ containers: DockerContainerInfo[] }>> => {
+      // Enumerating every container on the engine is machine-level information (names,
+      // images, uptime), so it follows the docker-host policy rather than the case one.
+      const denied = adminOnly(req, reply);
+      if (denied) return denied;
       const { hostId } = req.params as { hostId: string };
       const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === hostId);
       if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
@@ -899,7 +912,11 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    * container nothing is mounted at a matching host path, so the field would
    * otherwise be typed blind. Read-only — one `ls` through `docker exec`.
    */
-  app.post('/api/docker-cases/browse', async (req): Promise<ApiResponse<DockerBrowseResult>> => {
+  app.post('/api/docker-cases/browse', async (req, reply): Promise<ApiResponse<DockerBrowseResult>> => {
+    // Reads a directory listing inside an ARBITRARY named container, so it is gated with
+    // the adopt flow it serves rather than with the (owner-scoped) case file routes.
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
     const body = parseBody(DockerBrowseSchema, req.body);
     const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId);
     if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
@@ -915,8 +932,25 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     return { success: true, data: result };
   });
 
-  app.post('/api/docker-cases/adopt-preflight', async (req): Promise<ApiResponse<AdoptedContainerProbe>> => {
+  app.post('/api/docker-cases/adopt-preflight', async (req, reply): Promise<ApiResponse<AdoptedContainerProbe>> => {
     const body = parseBody(DockerAdoptPreflightSchema, req.body);
+    const dockerCases = await readDockerCases(CODEMAN_CONFIG_DIR);
+    // ⚠️ NOT plain `adminOnly`, unlike the two routes above: the run menu probes this for
+    // every docker case to learn which CLIs the CONTAINER has, so an admin-only gate would
+    // hide every agent mode from a non-admin's own docker case. A non-admin may therefore
+    // probe a container ALREADY linked to a case they can access — never an arbitrary one,
+    // which is the adopt-time question and stays admin-only with the rest of that flow.
+    if (!isAdmin(req)) {
+      const owns = dockerCases.some(
+        (item) =>
+          (item.container ?? dockerContainerName(item.name)) === body.container &&
+          canAccessOwned(getAuthUser(req), item.owner)
+      );
+      if (!owns) {
+        reply.code(403);
+        return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Admin only in multi-user mode');
+      }
+    }
     const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId);
     if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
     const probe = await probeAdoptableContainer(
@@ -1060,6 +1094,17 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
 
     const sessionDocker = toSessionDocker(host, dockerCase);
+    // A full export `docker commit`s the container into an image. For an ADOPTED
+    // container that means packaging someone else's container — with whatever
+    // credentials its owner logged in with — into a bundle Codeman then hands out,
+    // and it is the one export step that touches the container at all. The
+    // workspace-only export is a plain host-directory tar and stays available.
+    if (mode === 'full' && dockerCase.owned === false) {
+      return createErrorResponse(
+        ApiErrorCode.FORBIDDEN,
+        `Case "${name}" adopted an existing container. Codeman does not own it and will not commit it to an image — use a workspace-only export, or build the image yourself.`
+      );
+    }
     if (mode === 'full' && !sessionDocker.mountCredentials) {
       return createErrorResponse(
         ApiErrorCode.INVALID_INPUT,