@geminixiang/mikan 1.0.0-beta.7 → 1.0.0-beta.70

package/dist/sandbox/provisioner.d.ts

@@ -0,0 +1,139 @@
+export type { ContainerBindTranslator, ContainerMount, DockerContainerManagerOptions, ProvisionOptions, ResourceLimits, SandboxLimitStatus, } from "../types.js";
+import type { ContainerBindTranslator, DockerContainerManagerOptions, ProvisionOptions, ResourceLimits, SandboxLimitStatus } from "../types.js";
+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;
+    private static readonly IMAGE_MODE_LABEL;
+    private static readonly VAULT_ID_LABEL_KEY;
+    private static readonly CONVERSATION_ID_LABEL_KEY;
+    private static readonly MOUNT_SIGNATURE_LABEL_KEY;
+    private static readonly MIGRATE_IMAGE_PREFIX;
+    private static readonly MIGRATE_BINDS_LABEL_KEY;
+    private readonly limits?;
+    private readonly boostLimits?;
+    private readonly boostedKeys;
+    private readonly overrideLimits;
+    private readonly execFileImpl;
+    constructor(image: string, options?: DockerContainerManagerOptions);
+    static sanitizeSegment(value: string): string;
+    static containerName(containerKey: string): string;
+    static networkName(containerKey: string): string;
+    provision(containerKey: string, options?: ProvisionOptions): Promise<string>;
+    private provisionInner;
+    boost(containerKey: string): Promise<SandboxLimitStatus>;
+    setLimits(containerKey: string, limits: ResourceLimits): Promise<SandboxLimitStatus>;
+    getLimitStatus(containerKey: string): SandboxLimitStatus;
+    getDefaultLimits(): ResourceLimits | undefined;
+    getBoostLimits(): ResourceLimits | undefined;
+    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;
+    private getContainerName;
+    private mountArgs;
+    private toBindSpec;
+    private runContainer;
+    private effectiveLimits;
+    private resourceLimitArgs;
+    private applyResourceLimits;
+    private hasRuntimeDrift;
+    private hasBindMountDrift;
+    private expectedBinds;
+    private sameBinds;
+    private hasMountSignatureDrift;
+    private mountSignature;
+    private mountSourceFingerprint;
+    private inspectBindMounts;
+    private hasNetworkModeDrift;
+    private ensureNetwork;
+    private inspectStatus;
+    private listContainerNamesByLabel;
+    private listContainerNamesByPrefix;
+    private parseNameLines;
+    private inspectContainerDetails;
+    private normalizeDockerValue;
+    private parseDockerTimestamp;
+    private containerKeyFromContainerName;
+    /** @returns true when the container is gone (removed or already missing). */
+    private forceRemoveContainer;
+    private removeLegacyContainer;
+}
+//# sourceMappingURL=provisioner.d.ts.map

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

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

package/dist/{provisioner.js → sandbox/provisioner.js}

@@ -1,9 +1,10 @@
-import { execFile } from "child_process";
-import { createHash } from "crypto";
-import { readFileSync, statSync } from "fs";
-import { promisify } from "util";
-import * as log from "./log.js";
-import { reportUserFacingError } from "./observability/sentry.js";
+import { execFile } from "node:child_process";
+import { legacyConversationResourceKey, sanitizeIdentitySegment } from "./identity.js";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { promisify } from "node:util";
+import * as log from "../log.js";
+import { reportUserFacingError } from "../observability/index.js";
 const execFileAsync = promisify(execFile);
 function isDockerNotFoundError(err) {
     if (!err || typeof err !== "object")
@@ -18,16 +19,30 @@ 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;
+    const separator = spec.indexOf(":");
+    return {
+        source: spec.slice(0, separator),
+        target: spec.slice(separator + 1),
+        ...(readOnly ? { readOnly: true } : {}),
+    };
+}
 export class DockerContainerManager {
     static { this.MANAGED_LABEL = "mikan.managed=true"; }
     static { this.IMAGE_MODE_LABEL = "mikan.sandbox=image"; }
     static { this.VAULT_ID_LABEL_KEY = "mikan.vault-id"; }
     static { this.CONVERSATION_ID_LABEL_KEY = "mikan.conversation-id"; }
     static { this.MOUNT_SIGNATURE_LABEL_KEY = "mikan.mount-signature"; }
+    static { this.MIGRATE_IMAGE_PREFIX = "mikan-migrate"; }
+    static { this.MIGRATE_BINDS_LABEL_KEY = "mikan.migrate-binds"; }
     constructor(image, options = {}) {
         this.image = image;
         this.state = new Map();
         this.inflight = new Map();
+        this.layoutMigrations = new Map();
         this.boostedKeys = new Set();
         this.overrideLimits = new Map();
         this.limits = options.limits;
@@ -35,11 +50,7 @@ export class DockerContainerManager {
         this.execFileImpl = options.execFileImpl ?? execFileAsync;
     }
     static sanitizeSegment(value) {
-        const sanitized = value
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, "-")
-            .replace(/^-+|-+$/g, "");
-        return sanitized || "unknown";
+        return sanitizeIdentitySegment(value);
     }
     static containerName(containerKey) {
         return `mikan-sandbox-${containerKey}`;
@@ -60,13 +71,16 @@ 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 {
             if (status !== "missing" &&
                 (await this.hasRuntimeDrift(containerKey, containerName, mounts))) {
                 log.logInfo(`Container ${containerName} configuration changed; recreating container`);
-                await this.execFileImpl("docker", ["rm", "-f", containerName]);
-                await this.runContainer(containerKey, containerName, mounts, options);
+                await this.recreateContainerPreservingContents(containerKey, containerName, mounts);
                 log.logInfo(`Container ${containerName} recreated`);
             }
             else if (status === "running") {
@@ -136,7 +150,13 @@ export class DockerContainerManager {
     async remove(containerKey) {
         const containerName = this.getContainerName(containerKey);
         const networkName = DockerContainerManager.networkName(containerKey);
-        await this.forceRemoveContainer(containerName, `Container ${containerName} removed`, `Failed to remove container ${containerName}`);
+        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 {
             await this.execFileImpl("docker", ["network", "rm", networkName]);
             log.logInfo(`Network ${networkName} removed`);
@@ -144,6 +164,7 @@ export class DockerContainerManager {
         catch (err) {
             log.logWarning(`Failed to remove network ${networkName}`, err instanceof Error ? err.message : String(err));
         }
+        await this.removeMigrateSnapshot(containerName);
         this.state.delete(containerKey);
         this.boostedKeys.delete(containerKey);
         this.overrideLimits.delete(containerKey);
@@ -158,6 +179,319 @@ 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;
+        const names = await this.listContainerNamesByLabel();
+        await Promise.all(names.map(async (containerName) => {
+            const details = await this.inspectContainerDetails(containerName);
+            if (!details?.conversationId || !conversationIds.has(details.conversationId))
+                return;
+            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]));
+        }
+        catch (err) {
+            log.logWarning("Container layout sweep could not list containers", String(err));
+            return;
+        }
+        for (const containerName of names) {
+            try {
+                await this.migrateContainerLayout(containerName);
+            }
+            catch (err) {
+                log.logWarning(`Container layout migration failed for ${containerName}; leaving it in place`, err instanceof Error ? err.message : String(err));
+            }
+            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)
+            return Promise.resolve();
+        const existing = this.layoutMigrations.get(containerName);
+        if (existing)
+            return existing;
+        const pending = this.migrateContainerLayoutInner(containerName, translator).finally(() => {
+            this.layoutMigrations.delete(containerName);
+        });
+        this.layoutMigrations.set(containerName, pending);
+        return pending;
+    }
+    async migrateContainerLayoutInner(containerName, translator) {
+        const snapshotImage = `${DockerContainerManager.MIGRATE_IMAGE_PREFIX}:${containerName}`;
+        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;
+            originalBinds = labeled;
+        }
+        else {
+            originalBinds = await this.inspectBindMounts(containerName);
+            const translated = originalBinds.map(translator);
+            if (this.sameBinds(translated.toSorted(), originalBinds.slice().toSorted())) {
+                return; // already on the office layout
+            }
+            log.logInfo(`Migrating container ${containerName} to the office layout`);
+            await this.execFileImpl("docker", [
+                "commit",
+                "-c",
+                `LABEL ${DockerContainerManager.MIGRATE_BINDS_LABEL_KEY}=${JSON.stringify(JSON.stringify(originalBinds))}`,
+                containerName,
+                snapshotImage,
+            ]);
+            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);
+        const labels = [
+            "--label",
+            DockerContainerManager.MANAGED_LABEL,
+            "--label",
+            DockerContainerManager.IMAGE_MODE_LABEL,
+            "--label",
+            `${DockerContainerManager.VAULT_ID_LABEL_KEY}=${containerKey}`,
+        ];
+        if (conversationId) {
+            labels.push("--label", `${DockerContainerManager.CONVERSATION_ID_LABEL_KEY}=${conversationId}`);
+        }
+        labels.push("--label", `${DockerContainerManager.MOUNT_SIGNATURE_LABEL_KEY}=${this.mountSignature(bindSpecs.map(bindSpecToMount))}`);
+        await this.execFileImpl("docker", [
+            "create",
+            "--name",
+            containerName,
+            "--network",
+            networkName,
+            "--cap-drop",
+            "ALL",
+            "--security-opt",
+            "no-new-privileges",
+            "--pids-limit",
+            "1024",
+            ...labels,
+            ...this.resourceLimitArgs(this.effectiveLimits(containerKey)),
+            ...bindSpecs.flatMap((bind) => ["-v", bind]),
+            snapshotImage,
+            "sleep",
+            "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)
+            .filter((target) => target.startsWith("/workspace/public/"))
+            .map((target) => target.slice("/workspace/public/".length)));
+        const script = [
+            "[ -d /workspace/public ] || exit 0",
+            "for d in /workspace/public/*; do",
+            '  [ -e "$d" ] || continue',
+            '  case " $KEEP " in *" ${d##*/} "*) continue;; esac',
+            '  rmdir "$d" 2>/dev/null || true',
+            "done",
+        ].join("\n");
+        try {
+            await this.execFileImpl("docker", [
+                "exec",
+                "-e",
+                `KEEP=${[...keep].join(" ")}`,
+                containerName,
+                "sh",
+                "-c",
+                script,
+            ]);
+        }
+        catch (err) {
+            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));
+        await this.execFileImpl("docker", [
+            "commit",
+            "-c",
+            `LABEL ${DockerContainerManager.MIGRATE_BINDS_LABEL_KEY}=${JSON.stringify(JSON.stringify(bindSpecs))}`,
+            containerName,
+            snapshotImage,
+        ]);
+        await this.execFileImpl("docker", ["rm", "-f", containerName]);
+        await this.createContainerFromSnapshot(containerName, bindSpecs, containerKey);
+        await this.execFileImpl("docker", ["start", containerName]);
+        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)
+            return undefined;
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed) || parsed.some((bind) => typeof bind !== "string")) {
+            throw new Error(`Snapshot image ${snapshotImage} carries malformed migrate binds`);
+        }
+        return parsed;
+    }
+    async readImageLabel(image, key) {
+        try {
+            const { stdout } = await this.execFileImpl("docker", [
+                "inspect",
+                "-f",
+                `{{index .Config.Labels "${key}"}}`,
+                image,
+            ]);
+            return this.normalizeDockerValue(stdout.trim());
+        }
+        catch {
+            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", [
+                "rmi",
+                `${DockerContainerManager.MIGRATE_IMAGE_PREFIX}:${containerName}`,
+            ]);
+        }
+        catch {
+            // No snapshot for this container — the common case.
+        }
+    }
+    async listMigrateSnapshotContainerNames() {
+        try {
+            const { stdout } = await this.execFileImpl("docker", [
+                "images",
+                DockerContainerManager.MIGRATE_IMAGE_PREFIX,
+                "--format",
+                "{{.Tag}}",
+            ]);
+            return this.parseNameLines(stdout);
+        }
+        catch {
+            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 {
+            ({ stdout } = await this.execFileImpl("docker", [
+                "images",
+                `${DockerContainerManager.MIGRATE_IMAGE_PREFIX}`,
+                "--format",
+                "{{.Repository}}:{{.Tag}}",
+            ]));
+        }
+        catch {
+            return;
+        }
+        for (const image of this.parseNameLines(stdout)) {
+            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
+            try {
+                await this.execFileImpl("docker", ["rmi", image]);
+                log.logInfo(`Removed layout-migration snapshot image ${image}`);
+            }
+            catch (err) {
+                log.logWarning(`Could not remove snapshot image ${image}`, String(err));
+            }
+        }
+    }
     async reconcile() {
         const discovered = new Set();
         const labeledNames = await this.listContainerNamesByLabel();
@@ -184,6 +518,13 @@ 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;
+            }
             const status = details.running ? "running" : "stopped";
             const lastUsed = details.startedAtMs ?? Date.now();
             this.state.set(containerKey, { status, lastUsed, containerName });
@@ -204,7 +545,10 @@ export class DockerContainerManager {
         return mounts.flatMap((mount) => ["-v", this.toBindSpec(mount)]);
     }
     toBindSpec(mount) {
-        return `${mount.source}:${mount.target}`;
+        // 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) {
         const networkName = await this.ensureNetwork(containerKey);
@@ -343,9 +687,17 @@ 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");
             }
-            return `${stat.isDirectory() ? "dir" : "other"}:${stat.size}:${stat.mtimeMs}`;
+            // 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 {
             return "missing";
@@ -469,12 +821,11 @@ export class DockerContainerManager {
                 `{{.State.Running}}\t{{.State.StartedAt}}\t{{index .Config.Labels "${DockerContainerManager.VAULT_ID_LABEL_KEY}"}}\t{{index .Config.Labels "${DockerContainerManager.CONVERSATION_ID_LABEL_KEY}"}}`,
                 containerName,
             ]);
-            const [runningRaw, startedAtRaw, vaultIdRaw, conversationIdRaw] = stdout.trim().split("\t");
+            const [runningRaw, startedAtRaw, , conversationIdRaw] = stdout.trim().split("\t");
             const running = runningRaw === "true";
             const startedAtMs = this.parseDockerTimestamp(startedAtRaw);
-            const vaultId = this.normalizeDockerValue(vaultIdRaw);
             const conversationId = this.normalizeDockerValue(conversationIdRaw);
-            return { running, startedAtMs, vaultId, conversationId };
+            return { running, startedAtMs, conversationId };
         }
         catch (err) {
             log.logWarning(`Failed to inspect container ${containerName} during reconcile`, err instanceof Error ? err.message : String(err));
@@ -501,13 +852,19 @@ 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]);
             log.logInfo(successLog);
+            return true;
         }
         catch (err) {
-            log.logWarning(failureLog, err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (/no such container/i.test(message))
+                return true;
+            log.logWarning(failureLog, message);
+            return false;
         }
     }
     async removeLegacyContainer(containerName) {