@geminixiang/mikan 1.0.0-beta.76 → 1.0.0-beta.77

package/dist/sandbox/index.js

@@ -54,14 +54,6 @@ export function getSandboxWorkspaceCapabilities(type) {
     return requireSandboxAdapter(type).workspace;
 }
 const warnedUnenforcedPrivacy = new Set();
-/**
- * Only backends with a managed Workspace projection enforce office
- * visibility (read-only global knowledge, no access to other private
- * offices). Host, shared-container, and remote backends run every office in
- * one filesystem and are documented as trusted deployments (ADR 0003), so a
- * private office there is served with a one-time warning rather than
- * refused: refusing would take every DM offline on those backends.
- */
 export function assertSandboxSupportsWorkspacePolicy(sandboxConfig, visibility, officeKey) {
     const capabilities = getSandboxWorkspaceCapabilities(sandboxConfig.type);
     if (capabilities.managedProjection || visibility === "public")
@@ -86,10 +78,6 @@ export function parseSandboxArg(value) {
 export async function validateSandbox(config) {
     await requireSandboxAdapter(config.type).validate?.(config);
 }
-/**
- * Create an executor that runs commands on host, in Docker, or through a
- * Cloudflare sandbox bridge.
- */
 export function createExecutor(config, env, ensureReady) {
     const adapter = requireSandboxAdapter(config.type);
     if (!adapter.createExecutor) {
@@ -97,12 +85,6 @@ export function createExecutor(config, env, ensureReady) {
     }
     return adapter.createExecutor(config, env, ensureReady);
 }
-/**
- * The runtime path context for a sandbox config before an actor-specific
- * executor is resolved. `image` configs are unresolved by nature (the actor
- * decides the concrete container), but their mount layout is fixed, so path
- * mapping is known without resolving.
- */
 export function getUnresolvedSandboxPathContext(sandboxConfig, hostWorkspaceRoot) {
     if (sandboxConfig.type === "image") {
         return createMountedRuntimePathContext(hostWorkspaceRoot, "/workspace");

package/dist/sandbox/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContainerExecutor, containerSandboxAdapter } from \"./container.js\";\nimport { CloudflareSandboxExecutor, cloudflareSandboxAdapter } from \"./cloudflare.js\";\nimport { HostExecutor, hostSandboxAdapter } from \"./host.js\";\nimport { createMountedRuntimePathContext, execSimple, SandboxError } from \"./utils.js\";\nimport * as log from \"../log.js\";\nimport type {\n  Executor,\n  ImageSandboxConfig,\n  RuntimePathContext,\n  SandboxAdapter,\n  SandboxConfig,\n} from \"./types.js\";\n\nexport type {\n  CloudflareSandboxConfig,\n  ExecOptions,\n  ExecResult,\n  Executor,\n  RuntimePathContext,\n  SandboxAdapter,\n  SandboxConfig,\n} from \"./types.js\";\nexport { CloudflareSandboxExecutor, ContainerExecutor, HostExecutor };\nexport { SandboxError } from \"./utils.js\";\n\nfunction parseImageSandboxArg(value: string): ImageSandboxConfig | undefined {\n  if (!value.startsWith(\"image:\")) {\n    return undefined;\n  }\n\n  const image = value.slice(\"image:\".length);\n  if (!image) {\n    throw new SandboxError(\"Error: image sandbox requires image name (e.g., image:ubuntu:24.04)\");\n  }\n  return { type: \"image\", image };\n}\n\nasync function validateImageSandbox(config: ImageSandboxConfig): Promise<void> {\n  try {\n    await execSimple(\"docker\", [\"--version\"]);\n  } catch {\n    throw new SandboxError(\"Error: Docker is not installed or not in PATH\");\n  }\n  console.log(`  Image auto-provisioning enabled. Image: ${config.image}`);\n}\n\nconst imageSandboxAdapter: SandboxAdapter<ImageSandboxConfig> = {\n  type: \"image\",\n  credentials: { env: true, fileMounts: true },\n  workspace: { managedProjection: true },\n  parse: parseImageSandboxArg,\n  validate: validateImageSandbox,\n};\n\nconst sandboxAdapters = [\n  hostSandboxAdapter,\n  containerSandboxAdapter,\n  imageSandboxAdapter,\n  cloudflareSandboxAdapter,\n] as const;\nconst sandboxAdapterByType = new Map(\n  sandboxAdapters.map((adapter) => [adapter.type, adapter]),\n) as Map<SandboxConfig[\"type\"], SandboxAdapter>;\n\nexport function getSandboxAdapters(): readonly [...typeof sandboxAdapters] {\n  return sandboxAdapters;\n}\n\nfunction requireSandboxAdapter(type: SandboxConfig[\"type\"]): SandboxAdapter {\n  const adapter = sandboxAdapterByType.get(type);\n  if (!adapter) throw new SandboxError(`Error: Unsupported sandbox type '${type}'`);\n  return adapter;\n}\n\nexport function getSandboxCredentialCapabilities(\n  type: SandboxConfig[\"type\"],\n): SandboxAdapter[\"credentials\"] {\n  return requireSandboxAdapter(type).credentials;\n}\n\nexport function getSandboxWorkspaceCapabilities(\n  type: SandboxConfig[\"type\"],\n): SandboxAdapter[\"workspace\"] {\n  return requireSandboxAdapter(type).workspace;\n}\n\nconst warnedUnenforcedPrivacy = new Set<string>();\n\n/**\n * Only backends with a managed Workspace projection enforce office\n * visibility (read-only global knowledge, no access to other private\n * offices). Host, shared-container, and remote backends run every office in\n * one filesystem and are documented as trusted deployments (ADR 0003), so a\n * private office there is served with a one-time warning rather than\n * refused: refusing would take every DM offline on those backends.\n */\nexport function assertSandboxSupportsWorkspacePolicy(\n  sandboxConfig: SandboxConfig,\n  visibility: \"public\" | \"private\",\n  officeKey: string,\n): void {\n  const capabilities = getSandboxWorkspaceCapabilities(sandboxConfig.type);\n  if (capabilities.managedProjection || visibility === \"public\") return;\n  if (warnedUnenforcedPrivacy.has(officeKey)) return;\n  warnedUnenforcedPrivacy.add(officeKey);\n  log.logWarning(\n    `Sandbox '${sandboxConfig.type}' cannot enforce private office visibility for ${officeKey}`,\n    \"host, container, and cloudflare backends share one filesystem; use image:* to isolate private channels and DMs\",\n  );\n}\n\nexport function parseSandboxArg(value: string): SandboxConfig {\n  for (const adapter of sandboxAdapters) {\n    const config = adapter.parse(value);\n    if (config) {\n      return config;\n    }\n  }\n\n  if (value.startsWith(\"docker:\")) {\n    throw new SandboxError(\n      `Error: '${value}' is not supported. Use 'container:<container-name>' for the shared-container mode or 'image:<image-name>' for mikan-managed per-user containers.`,\n    );\n  }\n\n  throw new SandboxError(\n    `Error: Invalid sandbox type '${value}'. Use 'host', 'container:<container-name>', 'image:<image-name>', or 'cloudflare:<sandbox-id>'`,\n  );\n}\n\nexport async function validateSandbox(config: SandboxConfig): Promise<void> {\n  await requireSandboxAdapter(config.type).validate?.(config);\n}\n\n/**\n * Create an executor that runs commands on host, in Docker, or through a\n * Cloudflare sandbox bridge.\n */\nexport function createExecutor(\n  config: SandboxConfig,\n  env?: Record<string, string>,\n  ensureReady?: () => Promise<void>,\n): Executor {\n  const adapter = requireSandboxAdapter(config.type);\n  if (!adapter.createExecutor) {\n    throw new SandboxError(\"Error: image sandbox must resolve to a concrete container executor\");\n  }\n  return adapter.createExecutor(config, env, ensureReady);\n}\n\n/**\n * The runtime path context for a sandbox config before an actor-specific\n * executor is resolved. `image` configs are unresolved by nature (the actor\n * decides the concrete container), but their mount layout is fixed, so path\n * mapping is known without resolving.\n */\nexport function getUnresolvedSandboxPathContext(\n  sandboxConfig: SandboxConfig,\n  hostWorkspaceRoot: string,\n): RuntimePathContext {\n  if (sandboxConfig.type === \"image\") {\n    return createMountedRuntimePathContext(hostWorkspaceRoot, \"/workspace\");\n  }\n\n  return createExecutor(sandboxConfig).getPathContext(hostWorkspaceRoot);\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContainerExecutor, containerSandboxAdapter } from \"./container.js\";\nimport { CloudflareSandboxExecutor, cloudflareSandboxAdapter } from \"./cloudflare.js\";\nimport { HostExecutor, hostSandboxAdapter } from \"./host.js\";\nimport { createMountedRuntimePathContext, execSimple, SandboxError } from \"./utils.js\";\nimport * as log from \"../log.js\";\nimport type {\n  Executor,\n  ImageSandboxConfig,\n  RuntimePathContext,\n  SandboxAdapter,\n  SandboxConfig,\n} from \"./types.js\";\n\nexport type {\n  CloudflareSandboxConfig,\n  ExecOptions,\n  ExecResult,\n  Executor,\n  RuntimePathContext,\n  SandboxAdapter,\n  SandboxConfig,\n} from \"./types.js\";\nexport { CloudflareSandboxExecutor, ContainerExecutor, HostExecutor };\nexport { SandboxError } from \"./utils.js\";\n\nfunction parseImageSandboxArg(value: string): ImageSandboxConfig | undefined {\n  if (!value.startsWith(\"image:\")) {\n    return undefined;\n  }\n\n  const image = value.slice(\"image:\".length);\n  if (!image) {\n    throw new SandboxError(\"Error: image sandbox requires image name (e.g., image:ubuntu:24.04)\");\n  }\n  return { type: \"image\", image };\n}\n\nasync function validateImageSandbox(config: ImageSandboxConfig): Promise<void> {\n  try {\n    await execSimple(\"docker\", [\"--version\"]);\n  } catch {\n    throw new SandboxError(\"Error: Docker is not installed or not in PATH\");\n  }\n  console.log(`  Image auto-provisioning enabled. Image: ${config.image}`);\n}\n\nconst imageSandboxAdapter: SandboxAdapter<ImageSandboxConfig> = {\n  type: \"image\",\n  credentials: { env: true, fileMounts: true },\n  workspace: { managedProjection: true },\n  parse: parseImageSandboxArg,\n  validate: validateImageSandbox,\n};\n\nconst sandboxAdapters = [\n  hostSandboxAdapter,\n  containerSandboxAdapter,\n  imageSandboxAdapter,\n  cloudflareSandboxAdapter,\n] as const;\nconst sandboxAdapterByType = new Map(\n  sandboxAdapters.map((adapter) => [adapter.type, adapter]),\n) as Map<SandboxConfig[\"type\"], SandboxAdapter>;\n\nexport function getSandboxAdapters(): readonly [...typeof sandboxAdapters] {\n  return sandboxAdapters;\n}\n\nfunction requireSandboxAdapter(type: SandboxConfig[\"type\"]): SandboxAdapter {\n  const adapter = sandboxAdapterByType.get(type);\n  if (!adapter) throw new SandboxError(`Error: Unsupported sandbox type '${type}'`);\n  return adapter;\n}\n\nexport function getSandboxCredentialCapabilities(\n  type: SandboxConfig[\"type\"],\n): SandboxAdapter[\"credentials\"] {\n  return requireSandboxAdapter(type).credentials;\n}\n\nexport function getSandboxWorkspaceCapabilities(\n  type: SandboxConfig[\"type\"],\n): SandboxAdapter[\"workspace\"] {\n  return requireSandboxAdapter(type).workspace;\n}\n\nconst warnedUnenforcedPrivacy = new Set<string>();\n\nexport function assertSandboxSupportsWorkspacePolicy(\n  sandboxConfig: SandboxConfig,\n  visibility: \"public\" | \"private\",\n  officeKey: string,\n): void {\n  const capabilities = getSandboxWorkspaceCapabilities(sandboxConfig.type);\n  if (capabilities.managedProjection || visibility === \"public\") return;\n  if (warnedUnenforcedPrivacy.has(officeKey)) return;\n  warnedUnenforcedPrivacy.add(officeKey);\n  log.logWarning(\n    `Sandbox '${sandboxConfig.type}' cannot enforce private office visibility for ${officeKey}`,\n    \"host, container, and cloudflare backends share one filesystem; use image:* to isolate private channels and DMs\",\n  );\n}\n\nexport function parseSandboxArg(value: string): SandboxConfig {\n  for (const adapter of sandboxAdapters) {\n    const config = adapter.parse(value);\n    if (config) {\n      return config;\n    }\n  }\n\n  if (value.startsWith(\"docker:\")) {\n    throw new SandboxError(\n      `Error: '${value}' is not supported. Use 'container:<container-name>' for the shared-container mode or 'image:<image-name>' for mikan-managed per-user containers.`,\n    );\n  }\n\n  throw new SandboxError(\n    `Error: Invalid sandbox type '${value}'. Use 'host', 'container:<container-name>', 'image:<image-name>', or 'cloudflare:<sandbox-id>'`,\n  );\n}\n\nexport async function validateSandbox(config: SandboxConfig): Promise<void> {\n  await requireSandboxAdapter(config.type).validate?.(config);\n}\n\nexport function createExecutor(\n  config: SandboxConfig,\n  env?: Record<string, string>,\n  ensureReady?: () => Promise<void>,\n): Executor {\n  const adapter = requireSandboxAdapter(config.type);\n  if (!adapter.createExecutor) {\n    throw new SandboxError(\"Error: image sandbox must resolve to a concrete container executor\");\n  }\n  return adapter.createExecutor(config, env, ensureReady);\n}\n\nexport function getUnresolvedSandboxPathContext(\n  sandboxConfig: SandboxConfig,\n  hostWorkspaceRoot: string,\n): RuntimePathContext {\n  if (sandboxConfig.type === \"image\") {\n    return createMountedRuntimePathContext(hostWorkspaceRoot, \"/workspace\");\n  }\n\n  return createExecutor(sandboxConfig).getPathContext(hostWorkspaceRoot);\n}\n"]}

package/dist/sandbox/provisioner.d.ts

@@ -4,7 +4,6 @@ export declare class DockerContainerManager {
     private readonly image;
     private state;
     private inflight;
-    /** Active layout migration; unset means no translation ever applies. */
     private bindTranslator?;
     private layoutMigrations;
     private static readonly MANAGED_LABEL;
@@ -33,77 +32,18 @@ export declare class DockerContainerManager {
     stop(containerKey: string): Promise<void>;
     remove(containerKey: string): Promise<void>;
     stopIdle(maxIdleMs: number): Promise<void>;
-    /**
-     * Force-remove every managed container belonging to the given conversation
-     * ids. The office layout migration renames the host directories a
-     * container's workspace mount points at, so a surviving container would keep
-     * writing through stale mounts while the runtime works in the new location.
-     */
     removeContainersForConversations(conversationIds: ReadonlySet<string>): Promise<void>;
-    /**
-     * Arm the office-layout container migration. Containers whose binds still
-     * reference legacy raw-id paths are moved to the office-key layout without
-     * losing their writable layer: commit → remove → create with translated
-     * binds, preserving everything installed inside. Idempotent per container
-     * and resumable — the pre-removal binds ride on the snapshot image label,
-     * so a crash between commit and create resumes from the snapshot.
-     */
     armContainerLayoutMigration(translator: ContainerBindTranslator): void;
-    /**
-     * Sweep every managed container through the layout migration, serially and
-     * with a small gap, so the one-time cost never lands on the boot path or on
-     * a message. Safe to fire-and-forget; each unit is idempotent.
-     */
     sweepContainerLayoutMigration(delayMs?: number): Promise<void>;
-    /** Move one container to the office-key layout; no-op when already there. */
     private migrateContainerLayout;
     private migrateContainerLayoutInner;
-    /**
-     * Create `containerName` from its layout snapshot with `bindSpecs`,
-     * restoring the managed labels and recomputing the mount signature.
-     * `create`, not `run`: idle containers stay stopped exactly as they were;
-     * callers that need the container running start it themselves.
-     */
     private createContainerFromSnapshot;
-    /**
-     * `docker commit` captures the empty directories Docker created as bind
-     * targets, so a public office that stopped being mounted would linger in
-     * the snapshot as an empty `/workspace/public/<key>`. Remove any entry
-     * there that no current bind targets; only empty directories are removed,
-     * so a real file could never be deleted by this pass.
-     */
     private removeStaleMountpoints;
-    /**
-     * Recreate a drifted container with the desired mounts while keeping its
-     * writable layer: commit — the new binds ride the snapshot label, so a
-     * crash at any point resumes through the layout-migration path — then
-     * remove, create from the snapshot, and start. The snapshot is untagged
-     * once the new container is confirmed up: its only job was bridging
-     * commit → create, and the container now owns that content in its own
-     * writable layer, so nothing still needs the tag.
-     */
     private recreateContainerPreservingContents;
-    /** Binds recorded on a snapshot image, or undefined when no snapshot exists. */
     private readMigrateImageBinds;
     private readImageLabel;
-    /**
-     * Delete a container's layout snapshot after an intentional removal, so a
-     * missing container plus a surviving snapshot can only mean a crash in the
-     * middle of the layout migration (the resume discriminator).
-     */
     private removeMigrateSnapshot;
     private listMigrateSnapshotContainerNames;
-    /**
-     * Catch-up pass for snapshots the success path in
-     * `migrateContainerLayoutInner` did not get to remove itself — e.g. a
-     * crash between `createContainerFromSnapshot` and its own cleanup. A
-     * snapshot is only still needed while its container remains "missing"
-     * (the resume path in `migrateContainerLayoutInner` reads pre-removal
-     * binds off it); once the container exists again in any state, the
-     * snapshot has done its job regardless of whether that container's
-     * `Config.Image` still points at it — removing a tag never deletes
-     * layers a live container still uses.
-     */
     private removeDanglingMigrateImages;
     reconcile(): Promise<void>;
     private setState;
@@ -132,7 +72,6 @@ export declare class DockerContainerManager {
     private normalizeDockerValue;
     private parseDockerTimestamp;
     private containerKeyFromContainerName;
-    /** @returns true when the container is gone (removed or already missing). */
     private forceRemoveContainer;
     private removeLegacyContainer;
 }

package/dist/sandbox/provisioner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../../src/sandbox/provisioner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../../src/sandbox/provisioner.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/provisioner.js

@@ -19,7 +19,6 @@ function isDockerNotFoundError(err) {
         /network [^\n]+ not found/.test(haystack) ||
         /error: no such [^\n]+/.test(haystack));
 }
-/** Parse `src:dst[:ro]` back into a ContainerMount for signature computation. */
 function bindSpecToMount(bindSpec) {
     const readOnly = bindSpec.endsWith(":ro");
     const spec = readOnly ? bindSpec.slice(0, -3) : bindSpec;
@@ -71,9 +70,6 @@ export class DockerContainerManager {
     async provisionInner(containerKey, options) {
         const containerName = options.containerName ?? DockerContainerManager.containerName(containerKey);
         const mounts = options.mounts ?? [];
-        // A container still on the pre-office layout must move its writable layer
-        // to the new mounts before the drift check below would recreate it from
-        // the base image and discard everything installed inside.
         await this.migrateContainerLayout(containerName);
         const status = await this.inspectStatus(containerName);
         try {
@@ -149,9 +145,6 @@ export class DockerContainerManager {
         const networkName = DockerContainerManager.networkName(containerKey);
         const removed = await this.forceRemoveContainer(containerName, `Container ${containerName} removed`, `Failed to remove container ${containerName}`);
         if (!removed) {
-            // The container may still be running with its old mounts. Keeping the
-            // ownership state (and throwing) is the honest outcome: callers such
-            // as credential refresh must not report a teardown that did not happen.
             throw new Error(`Failed to remove container ${containerName}`);
         }
         try {
@@ -176,12 +169,6 @@ export class DockerContainerManager {
         }
         await Promise.all(toStop.map((containerKey) => this.stop(containerKey)));
     }
-    /**
-     * Force-remove every managed container belonging to the given conversation
-     * ids. The office layout migration renames the host directories a
-     * container's workspace mount points at, so a surviving container would keep
-     * writing through stale mounts while the runtime works in the new location.
-     */
     async removeContainersForConversations(conversationIds) {
         if (conversationIds.size === 0)
             return;
@@ -193,30 +180,14 @@ export class DockerContainerManager {
             await this.forceRemoveContainer(containerName, `Removed container ${containerName} after office migration`, `Failed to remove container ${containerName} after office migration`);
         }));
     }
-    /**
-     * Arm the office-layout container migration. Containers whose binds still
-     * reference legacy raw-id paths are moved to the office-key layout without
-     * losing their writable layer: commit → remove → create with translated
-     * binds, preserving everything installed inside. Idempotent per container
-     * and resumable — the pre-removal binds ride on the snapshot image label,
-     * so a crash between commit and create resumes from the snapshot.
-     */
     armContainerLayoutMigration(translator) {
         this.bindTranslator = translator;
     }
-    /**
-     * Sweep every managed container through the layout migration, serially and
-     * with a small gap, so the one-time cost never lands on the boot path or on
-     * a message. Safe to fire-and-forget; each unit is idempotent.
-     */
     async sweepContainerLayoutMigration(delayMs = 2000) {
         if (!this.bindTranslator)
             return;
         let names;
         try {
-            // Include snapshot names: a crash between commit and create leaves a
-            // snapshot with no container, which must resume before the GC below
-            // could mistake it for an orphan.
             const containers = await this.listContainerNamesByLabel();
             const snapshots = await this.listMigrateSnapshotContainerNames();
             names = Array.from(new Set([...containers, ...snapshots]));
@@ -234,11 +205,8 @@ export class DockerContainerManager {
             }
             await new Promise((resolve) => setTimeout(resolve, delayMs));
         }
-        // Snapshot images whose container has since been recreated from the base
-        // image are no longer referenced; reclaim them.
         await this.removeDanglingMigrateImages();
     }
-    /** Move one container to the office-key layout; no-op when already there. */
     migrateContainerLayout(containerName) {
         const translator = this.bindTranslator;
         if (!translator)
@@ -257,9 +225,6 @@ export class DockerContainerManager {
         let originalBinds;
         const status = await this.inspectStatus(containerName);
         if (status === "missing") {
-            // Resume path: a previous run committed and removed the container but
-            // died before creating the replacement. The snapshot carries the
-            // pre-removal binds on its label.
             const labeled = await this.readMigrateImageBinds(snapshotImage);
             if (labeled === undefined)
                 return;
@@ -269,7 +234,7 @@ export class DockerContainerManager {
             originalBinds = await this.inspectBindMounts(containerName);
             const translated = originalBinds.map(translator);
             if (this.sameBinds(translated.toSorted(), originalBinds.slice().toSorted())) {
-                return; // already on the office layout
+                return;
             }
             log.logInfo(`Migrating container ${containerName} to the office layout`);
             await this.execFileImpl("docker", [
@@ -282,25 +247,11 @@ export class DockerContainerManager {
             await this.execFileImpl("docker", ["rm", "-f", containerName]);
         }
         await this.createContainerFromSnapshot(containerName, originalBinds.map(translator));
-        // The snapshot's only job was bridging commit → create; the new container
-        // already owns that content in its own writable layer; untagging it now
-        // (rather than waiting for a "natural recreation from the base image"
-        // that never happens — every recreation path here targets this same
-        // snapshot family) is what makes migration actually one-time instead of
-        // repeating on every future sweep that still finds the tag.
         await this.removeMigrateSnapshot(containerName);
         log.logInfo(`Container ${containerName} migrated to the office layout`);
     }
-    /**
-     * Create `containerName` from its layout snapshot with `bindSpecs`,
-     * restoring the managed labels and recomputing the mount signature.
-     * `create`, not `run`: idle containers stay stopped exactly as they were;
-     * callers that need the container running start it themselves.
-     */
     async createContainerFromSnapshot(containerName, bindSpecs, knownContainerKey) {
         const snapshotImage = `${DockerContainerManager.MIGRATE_IMAGE_PREFIX}:${containerName}`;
-        // The sweep has only the container name and derives the key; the drift
-        // path knows the real key (container names can be caller-supplied).
         const containerKey = knownContainerKey ?? this.containerKeyFromContainerName(containerName) ?? containerName;
         const networkName = await this.ensureNetwork(containerKey);
         const conversationId = await this.readImageLabel(snapshotImage, DockerContainerManager.CONVERSATION_ID_LABEL_KEY);
@@ -336,13 +287,6 @@ export class DockerContainerManager {
             "infinity",
         ]);
     }
-    /**
-     * `docker commit` captures the empty directories Docker created as bind
-     * targets, so a public office that stopped being mounted would linger in
-     * the snapshot as an empty `/workspace/public/<key>`. Remove any entry
-     * there that no current bind targets; only empty directories are removed,
-     * so a real file could never be deleted by this pass.
-     */
     async removeStaleMountpoints(containerName, bindSpecs) {
         const keep = new Set(bindSpecs
             .map((bind) => bindSpecToMount(bind).target)
@@ -371,15 +315,6 @@ export class DockerContainerManager {
             log.logWarning(`Could not clean stale mountpoints in ${containerName}`, String(err));
         }
     }
-    /**
-     * Recreate a drifted container with the desired mounts while keeping its
-     * writable layer: commit — the new binds ride the snapshot label, so a
-     * crash at any point resumes through the layout-migration path — then
-     * remove, create from the snapshot, and start. The snapshot is untagged
-     * once the new container is confirmed up: its only job was bridging
-     * commit → create, and the container now owns that content in its own
-     * writable layer, so nothing still needs the tag.
-     */
     async recreateContainerPreservingContents(containerKey, containerName, mounts) {
         const snapshotImage = `${DockerContainerManager.MIGRATE_IMAGE_PREFIX}:${containerName}`;
         const bindSpecs = mounts.map((mount) => this.toBindSpec(mount));
@@ -396,7 +331,6 @@ export class DockerContainerManager {
         await this.removeStaleMountpoints(containerName, bindSpecs);
         await this.removeMigrateSnapshot(containerName);
     }
-    /** Binds recorded on a snapshot image, or undefined when no snapshot exists. */
     async readMigrateImageBinds(snapshotImage) {
         const raw = await this.readImageLabel(snapshotImage, DockerContainerManager.MIGRATE_BINDS_LABEL_KEY);
         if (raw === undefined)
@@ -421,11 +355,6 @@ export class DockerContainerManager {
             return undefined;
         }
     }
-    /**
-     * Delete a container's layout snapshot after an intentional removal, so a
-     * missing container plus a surviving snapshot can only mean a crash in the
-     * middle of the layout migration (the resume discriminator).
-     */
     async removeMigrateSnapshot(containerName) {
         try {
             await this.execFileImpl("docker", [
@@ -433,9 +362,7 @@ export class DockerContainerManager {
                 `${DockerContainerManager.MIGRATE_IMAGE_PREFIX}:${containerName}`,
             ]);
         }
-        catch {
-            // No snapshot for this container — the common case.
-        }
+        catch { }
     }
     async listMigrateSnapshotContainerNames() {
         try {
@@ -451,17 +378,6 @@ export class DockerContainerManager {
             return [];
         }
     }
-    /**
-     * Catch-up pass for snapshots the success path in
-     * `migrateContainerLayoutInner` did not get to remove itself — e.g. a
-     * crash between `createContainerFromSnapshot` and its own cleanup. A
-     * snapshot is only still needed while its container remains "missing"
-     * (the resume path in `migrateContainerLayoutInner` reads pre-removal
-     * binds off it); once the container exists again in any state, the
-     * snapshot has done its job regardless of whether that container's
-     * `Config.Image` still points at it — removing a tag never deletes
-     * layers a live container still uses.
-     */
     async removeDanglingMigrateImages() {
         let stdout;
         try {
@@ -479,7 +395,7 @@ export class DockerContainerManager {
             const containerName = image.slice(DockerContainerManager.MIGRATE_IMAGE_PREFIX.length + 1);
             const status = await this.inspectStatus(containerName);
             if (status === "missing")
-                continue; // still needed for a future resume
+                continue;
             try {
                 await this.execFileImpl("docker", ["rmi", image]);
                 log.logInfo(`Removed layout-migration snapshot image ${image}`);
@@ -515,9 +431,6 @@ export class DockerContainerManager {
                 log.logWarning(`Skipping unmanaged-style container without container key`, containerName);
                 continue;
             }
-            // Containers keyed under the pre-office raw-conversation resource key
-            // are unreachable now that resource identity is the office key: no
-            // provision will ever address them again, so reap rather than adopt.
             if (containerKey === legacyConversationResourceKey(details.conversationId)) {
                 legacyRemovals.push(this.forceRemoveContainer(containerName, `Removed container ${containerName} keyed by pre-office resource identity`, `Failed to remove legacy-keyed container ${containerName}`).then(() => undefined));
                 continue;
@@ -542,9 +455,6 @@ export class DockerContainerManager {
         return mounts.flatMap((mount) => ["-v", this.toBindSpec(mount)]);
     }
     toBindSpec(mount) {
-        // The `:ro` suffix is part of the bind spec, so it also flows into
-        // expectedBinds/mountSignature — flipping a mount's writability is drift
-        // and recreates the container rather than leaving a stale writable bind.
         return `${mount.source}:${mount.target}${mount.readOnly ? ":ro" : ""}`;
     }
     async runContainer(containerKey, containerName, mounts, options) {
@@ -599,9 +509,6 @@ export class DockerContainerManager {
             args.push("--cpus", limits.cpus);
         if (limits?.memory) {
             args.push("--memory", limits.memory);
-            // Keep Docker's no-extra-swap semantics explicit. Docker requires
-            // memory-swap to be updated together when raising an existing memory
-            // limit above the current swap limit.
             args.push("--memory-swap", limits.memory);
         }
         return args;
@@ -684,16 +591,8 @@ export class DockerContainerManager {
         try {
             const stat = statSync(source);
             if (stat.isFile()) {
-                // Files are atomically replaced (rename), which leaves the container
-                // holding a stale inode — content changes must recreate the mount.
                 return createHash("sha256").update(readFileSync(source)).digest("hex");
             }
-            // Directories: a bind mount follows changes inside the directory live,
-            // so only replacing the directory itself makes the mount stale.
-            // Size/mtime churn from ordinary activity — event files coming and
-            // going, children being created — must not read as drift. Identity is
-            // dev:ino plus birth time, because ext4 recycles inode numbers
-            // immediately and a same-path replacement can reuse the old one.
             return `${stat.isDirectory() ? "dir" : "other"}:${stat.dev}:${stat.ino}:${stat.birthtimeMs}`;
         }
         catch {
@@ -849,7 +748,6 @@ export class DockerContainerManager {
         const containerKey = containerName.slice(prefix.length);
         return containerKey.length > 0 ? containerKey : undefined;
     }
-    /** @returns true when the container is gone (removed or already missing). */
     async forceRemoveContainer(containerName, successLog, failureLog) {
         try {
             await this.execFileImpl("docker", ["rm", "-f", containerName]);