feat(docker): attach a case to an already-running container

Docker cases could only run in a container Codeman created itself. Attaching to
one the user already built and runs means Codeman must leave that container's
lifecycle completely alone, which the launch chain could not do: it was
`image inspect` -> `inspect || create` -> `start` -> `exec`.

Adds `DockerCase.owned`, mirroring the `owned:false` contract remote-SSH already
uses for attached sessions. Absent (every existing case) means owned, so current
behaviour is byte-identical. `false` means the container belongs to the user and
Codeman may only exec into it.

The launch chain for an attached container only looks, then execs: no image gate
(the image is theirs), no create, and no `start` — starting a container we do not
own is the very mutation attaching promises not to perform. A missing or stopped
container fails closed with an actionable message instead. Credential seeding is
skipped too: those copies read from create-time read-only mounts that do not
exist here, and writing host credentials into someone's container is not ours to
do, so its CLIs must already be authenticated inside it.

Four fail-closed guards. buildDockerStopCommand and buildDockerRemoveCommand
throw during pure string construction, so no caller bug can turn into a
`docker stop`/`rm` on a container we do not own; removeDockerContainer refuses
again at the lowest layer; drift reports "none" for an attached container, which
carries no `codeman.confighash` label and would otherwise always look drifted and
409 the launch gate forever; and the orphan reaper skips attached containers
through a check deliberately independent of the two conditions already covering
them.

`owned` is applied AFTER the config hash is computed. dockerConfigHash takes an
explicit field list, so ownership can never shift an existing case's hash — if it
did, every pre-existing case would trip the drift gate at once, and the remedy
the UI offers is "recreate the container".

Adds POST /api/cases/docker-adopt and a read-only
POST /api/docker-cases/adopt-preflight. The preflight refuses at LINK time rather
than at session launch, where the only ways out would be a dead pane or starting
a container we do not own.

Tests assert the negative guarantee directly — that create, start, stop, rm,
restart and kill are absent from the generated commands while `docker exec -it`
and `new-session -A` remain — since it cannot be observed by using the feature.

src/web/routes/case-routes.ts

@@ -13,7 +13,7 @@ import fs from 'node:fs/promises';
 import { join, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import type { ApiResponse, CaseInfo, DockerHost, RemoteSessionInfo, SessionDocker } from '../../types.js';
+import type { ApiResponse, CaseInfo, DockerHost, RemoteSessionInfo, SessionDocker, SessionMode } from '../../types.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import {
   CreateCaseSchema,
@@ -24,6 +24,8 @@ import {
   RemoteCaseLinkSchema,
   RemoteHostSchema,
   DockerCaseLinkSchema,
+  DockerCaseAdoptSchema,
+  DockerAdoptPreflightSchema,
   DockerHostSchema,
   DockerExportSchema,
   DockerImportSchema,
@@ -66,6 +68,8 @@ import {
   DEFAULT_AGENT_IMAGE,
   dockerContainerName,
   dockerDisplayPath,
+  probeAdoptableContainer,
+  DOCKER_ADOPT_PROBE_MODES,
   readDockerCases,
   readDockerHosts,
   removeDockerContainer,
@@ -73,6 +77,7 @@ import {
   writeDockerCases,
   writeDockerHosts,
 } from '../../docker-hosts.js';
+import type { AdoptedContainerProbe } from '../../docker-hosts.js';
 import { buildDockerRemoveCommand } from '../../tmux-manager.js';
 import {
   checkRemoteTmuxAvailable,
@@ -771,6 +776,106 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     }
   );
 
+  /**
+   * ADOPT an already-running container (`owned: false`). The mirror of the
+   * remote-SSH attach path: Codeman execs into a container the user built and
+   * runs, and never creates, starts, stops, restarts or removes it.
+   *
+   * Everything here is read-only toward the container. The preflight refuses at
+   * LINK time — missing, stopped, or no tmux inside — because the alternative is
+   * failing at session launch, where the only ways out would be a dead pane or
+   * starting a container we do not own. There is no image gate and no
+   * `ensureCaseImage`: adoption never runs `docker create`, so the container's
+   * image is the user's business.
+   */
+  app.post(
+    '/api/cases/docker-adopt',
+    async (req): Promise<ApiResponse<{ case: unknown; image?: string; availableModes?: SessionMode[] }>> => {
+      const dockerCase = {
+        ...parseBody(DockerCaseAdoptSchema, req.body),
+        type: 'docker' as const,
+        owner: ownerFor(req),
+        owned: false as const,
+      };
+      const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId);
+      if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
+
+      const linkedCases = await readLinkedCases();
+      const dockerCases = await readDockerCases(CODEMAN_CONFIG_DIR);
+      if (
+        dockerCases.some((item) => item.name === dockerCase.name) ||
+        linkedCases[dockerCase.name] ||
+        existsSync(join(resolveCasesDir(getAuthUser(req)), dockerCase.name))
+      ) {
+        return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Case already exists');
+      }
+      // Two cases must never share one adopted container: session close kills the
+      // in-container tmux by session id, but a shared adoption would let one case's
+      // teardown and another's launch race over the same tmux server.
+      const container = dockerCase.container;
+      if (dockerCases.some((item) => (item.container ?? dockerContainerName(item.name)) === container)) {
+        return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, `Container "${container}" is already linked to a case`);
+      }
+
+      if (!isWorkingDirAllowed(getAuthUser(req), dockerCase.hostWorkspacePath)) {
+        return createErrorResponse(ApiErrorCode.FORBIDDEN, 'hostWorkspacePath is outside your workspace');
+      }
+      // The workspace must ALREADY exist: it mirrors a path inside a container we
+      // did not create, so silently mkdir-ing it would invent a host directory that
+      // does not correspond to whatever is actually mounted there.
+      if (!existsSync(dockerCase.hostWorkspacePath)) {
+        return createErrorResponse(
+          ApiErrorCode.INVALID_INPUT,
+          'hostWorkspacePath does not exist. Adoption mirrors an existing container, so point this at the real host directory already mounted into it.'
+        );
+      }
+
+      const availability = await checkDockerAvailable(host.engine);
+      if (!availability.ok) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          availability.error || 'docker daemon is not available'
+        );
+      }
+      const probe = await probeAdoptableContainer(toSessionDocker(host, dockerCase), [...DOCKER_ADOPT_PROBE_MODES]);
+      if (!probe.ok) {
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not adoptable');
+      }
+
+      await writeDockerCases(CODEMAN_CONFIG_DIR, [...dockerCases, dockerCase]);
+      ctx.broadcast(SseEvent.CaseLinked, {
+        name: dockerCase.name,
+        path: dockerCase.hostWorkspacePath,
+        type: 'docker',
+      });
+      return {
+        success: true,
+        data: { case: dockerCase, image: probe.image, availableModes: probe.availableModes },
+      };
+    }
+  );
+
+  /**
+   * Preflight an existing container WITHOUT linking anything, so the UI can tell
+   * the user "not running" / "no tmux" / "codex present, claude missing" before
+   * they commit to a case name. Read-only; never touches container lifecycle.
+   */
+  app.post('/api/docker-cases/adopt-preflight', async (req): Promise<ApiResponse<AdoptedContainerProbe>> => {
+    const body = parseBody(DockerAdoptPreflightSchema, req.body);
+    const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === body.hostId);
+    if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
+    const probe = await probeAdoptableContainer(
+      {
+        engine: host.engine ?? 'docker',
+        context: host.context,
+        daemonHost: host.daemonHost,
+        containerName: body.container,
+      },
+      [...DOCKER_ADOPT_PROBE_MODES]
+    );
+    return { success: true, data: probe };
+  });
+
   // One-click "Run in Docker": create a NORMAL case (folder in CASES_DIR, scaffolded)
   // AND link it to a hardened container with default settings, auto-provisioning a
   // shared `default` docker host so the user never touches host/image/network fields.
@@ -1010,9 +1115,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       engine: result.manifest.engine,
       image: result.importedImage ?? result.manifest.image,
       network: (['bridge', 'none', 'custom'].includes(result.manifest.network) ? result.manifest.network : 'bridge') as
-        | 'bridge'
-        | 'none'
-        | 'custom',
+        'bridge' | 'none' | 'custom',
     };
     await writeDockerHosts(
       CODEMAN_CONFIG_DIR,
@@ -1042,8 +1145,22 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     '/api/docker-cases/:name/recreate',
     async (req): Promise<ApiResponse<{ name: string; container: string }>> => {
       const { name } = req.params as { name: string };
-      const dockerCase = (await readDockerCases(CODEMAN_CONFIG_DIR)).find((item) => item.name === name);
+      // Ownership gate: recreate DESTROYS a container, so it must be scoped like
+      // delete is (`canAccessOwned`). Without it any user could rebuild another
+      // user's container by name.
+      const dockerCase = (await readDockerCases(CODEMAN_CONFIG_DIR)).find(
+        (item) => item.name === name && canAccessOwned(getAuthUser(req), item.owner)
+      );
       if (!dockerCase) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker case not found');
+      // An ADOPTED container is the user's own: there is nothing to recreate it
+      // from (no create-config, no image gate) and destroying it is exactly what
+      // adoption promises never to do.
+      if (dockerCase.owned === false) {
+        return createErrorResponse(
+          ApiErrorCode.FORBIDDEN,
+          `Case "${name}" adopted an existing container. Codeman does not own its lifecycle and will not recreate it — rebuild it yourself, or unlink the case.`
+        );
+      }
       const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId);
       if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found');
       const sessionDocker = toSessionDocker(host, dockerCase);
@@ -1154,7 +1271,13 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       );
       // Best-effort `docker rm -f` the per-case container (case-delete is the
       // explicit teardown that removes it; the bind-mounted workspace survives).
-      const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId);
+      // An ADOPTED container is skipped entirely: unlinking the case must leave
+      // the user's own container running and untouched. The seed file is skipped
+      // with it — adoption never wrote one.
+      const host =
+        dockerCase.owned === false
+          ? undefined
+          : (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId);
       if (host) {
         const sessionDocker = toSessionDocker(host, dockerCase);
         try {

src/web/routes/session-routes.ts

@@ -127,6 +127,7 @@ import {
 import {
   checkDockerAvailable,
   checkDockerConfigDrift,
+  probeAdoptableContainer,
   checkDockerTmuxAvailable,
   ensureAgentBaseImage,
   DEFAULT_AGENT_IMAGE,
@@ -2957,25 +2958,43 @@ export function registerSessionRoutes(
         );
       }
       const sessionDocker = toSessionDocker(host, dockerCase);
-      // Ensure the base image exists, auto-building the default image on first use so
-      // it is never a blocker. Dedup'd with any build kicked off at case-create, so
-      // this awaits the SAME in-flight build rather than starting a second one.
-      const ensured = await ensureAgentBaseImage(sessionDocker, sessionDocker.image, {
-        onProgress: (line) => ctx.broadcast(SseEvent.DockerImageBuildProgress, { name: dockerCase.name, line }),
-      });
-      if (!ensured.ok) {
-        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, ensured.error || 'base image not available');
-      }
-      if (ensured.built) {
-        ctx.broadcast(SseEvent.DockerImageBuildComplete, { name: dockerCase.name, image: sessionDocker.image });
-      }
-      // tmux is a hard prerequisite (the in-container tmux makes reconnect durable).
-      // Skip the extra container-run probe for our OWN default image (the baked
-      // Dockerfile always contains tmux); still verify a custom image.
-      if (sessionDocker.image !== DEFAULT_AGENT_IMAGE) {
-        const tmuxCheck = await checkDockerTmuxAvailable(sessionDocker);
-        if (!tmuxCheck.ok) {
-          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'base image is missing tmux');
+      // An ADOPTED container skips every image-side gate: we never run `docker
+      // create`, so the image is the user's business, and `ensureAgentBaseImage`
+      // would build/require an image that has nothing to do with their container.
+      // The prerequisite that DOES still hold is tmux inside it, so probe the live
+      // container (not the image) and refuse before launch rather than dead-paning.
+      if (sessionDocker.owned === false) {
+        const probe = await probeAdoptableContainer(sessionDocker, [mode]);
+        if (!probe.ok) {
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not usable');
+        }
+        if (mode !== 'shell' && !probe.availableModes?.includes(mode)) {
+          return createErrorResponse(
+            ApiErrorCode.OPERATION_FAILED,
+            `"${mode}" is not installed in container "${sessionDocker.containerName}". Adoption never modifies the container — install it inside, or pick another mode.`
+          );
+        }
+      } else {
+        // Ensure the base image exists, auto-building the default image on first use so
+        // it is never a blocker. Dedup'd with any build kicked off at case-create, so
+        // this awaits the SAME in-flight build rather than starting a second one.
+        const ensured = await ensureAgentBaseImage(sessionDocker, sessionDocker.image, {
+          onProgress: (line) => ctx.broadcast(SseEvent.DockerImageBuildProgress, { name: dockerCase.name, line }),
+        });
+        if (!ensured.ok) {
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, ensured.error || 'base image not available');
+        }
+        if (ensured.built) {
+          ctx.broadcast(SseEvent.DockerImageBuildComplete, { name: dockerCase.name, image: sessionDocker.image });
+        }
+        // tmux is a hard prerequisite (the in-container tmux makes reconnect durable).
+        // Skip the extra container-run probe for our OWN default image (the baked
+        // Dockerfile always contains tmux); still verify a custom image.
+        if (sessionDocker.image !== DEFAULT_AGENT_IMAGE) {
+          const tmuxCheck = await checkDockerTmuxAvailable(sessionDocker);
+          if (!tmuxCheck.ok) {
+            return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'base image is missing tmux');
+          }
         }
       }
 

src/web/schemas.ts

@@ -792,6 +792,50 @@ export const DockerCaseLinkSchema = z.object({
     .optional(),
 });
 
+/**
+ * ADOPT an already-running container the user built and runs themselves. The
+ * container name is REQUIRED (there is nothing to derive it from — we are not
+ * creating it), and `hostWorkspacePath` still points at real host bytes so the
+ * file routes, watchers and transcript correlation keep working exactly as they
+ * do for an owned case. Everything that only makes sense at container-create
+ * time (image, network, resources, gpus, credential mounts) is deliberately
+ * absent: adoption never runs `docker create`.
+ */
+export const DockerCaseAdoptSchema = z.object({
+  name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
+  hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
+  container: z
+    .string()
+    .min(2)
+    .max(128)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'),
+  hostWorkspacePath: z
+    .string()
+    .min(1)
+    .max(2000)
+    .regex(/^\//, 'Workspace path must be absolute')
+    .regex(/^[^,]*$/, 'Workspace path must not contain commas (docker --mount is comma-delimited)')
+    .regex(NO_SHELL_META, 'Invalid characters in workspace path'),
+  containerWorkdir: z
+    .string()
+    .min(1)
+    .max(2000)
+    .regex(/^\//, 'Container workdir must be absolute')
+    .regex(/^[^,]*$/, 'Container workdir must not contain commas (docker --mount is comma-delimited)')
+    .regex(NO_SHELL_META, 'Invalid characters in container workdir')
+    .optional(),
+});
+
+/** Read-only adoption preflight: report on an existing container, link nothing. */
+export const DockerAdoptPreflightSchema = z.object({
+  hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
+  container: z
+    .string()
+    .min(2)
+    .max(128)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'),
+});
+
 export const DockerExportSchema = z.object({
   mode: z.enum(['full', 'workspace']).optional(),
 });