@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/{computer/host/workspace.js → workspace/object.js}

@@ -4,20 +4,20 @@ import { DurableObject, tracing } from "cloudflare:workers";
 // object owes on waking, which is the callbacks registered on it below.
 import { installScheduler, namedDeadline } from "@dynamicagents/core/alarm";
 import { Workspace } from "@cloudflare/computer";
-import { CloudflareContainerBackend, withWorkspaceContainer } from "@cloudflare/computer/backends/container";
+import { ContainerBackend, withWorkspaceContainer } from "@cloudflare/computer/backends/container";
 import { createGitClient } from "@cloudflare/computer/git";
 import { createCloudflareObserver } from "@cloudflare/computer/observe/cloudflare";
-import { MAX_TOOL_CALL_MS } from "@dynamicagents/core";
 import { ContainerTrust } from "./ca-trust.js";
 import { ContainerDeps } from "./container-deps.js";
+import { DepsSnapshot } from "./deps-snapshot.js";
 import { ContainerGitIdentity } from "./git-identity.js";
 import { InstallJob } from "./install-job.js";
 import { WorkspaceGitHost } from "./git-host.js";
 import { SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, WorkspaceSync, syncRetryDelayMs } from "./sync.js";
-// Leaf modules rather than `../index.js` — see the same import in
+// Leaf modules rather than `./index.ts` — see the same import in
 // {@link file://./install-job.ts} for why the barrel is not reachable from here.
-import { deriveAdvisories } from "../advisory.js";
-import { pathExists } from "../read.js";
+import { deriveAdvisories } from "./advisory.js";
+import { pathExists } from "./read.js";
 /**
  * A workspace: one Durable Object, one container, one repository.
  *
@@ -30,7 +30,7 @@ import { pathExists } from "../read.js";
  * A directory inside the plugin rather than a subpath beside it, so that one
  * capability stays one import path and a consumer cannot take the tools without
  * the object they address. The bundle cost of that is nothing: `sideEffects` is
- * false, so an agent that only calls `sb_exec` carries no container backend and
+ * false, so an agent that only calls `bash` carries no container backend and
  * no isomorphic-git.
  *
  * What this file must not do is import the plugin barrel. The barrel re-exports
@@ -43,7 +43,7 @@ import { pathExists } from "../read.js";
  * FUSE at `/workspace`. Commands run against the same tree the Worker reads over
  * RPC, and the tree outlives the container.
  *
- * **One repository per object**, because `computer` is strictly 1 DO ↔ 1
+ * **One repository per object**, because `@cloudflare/computer` is strictly 1 DO ↔ 1
  * container: the id derives from caller *and* repository (see `workspaceName`),
  * so two repositories for one caller are two objects and two containers.
  *
@@ -63,10 +63,11 @@ import { pathExists } from "../read.js";
  * and each carries the reasoning for its own decisions:
  *
  * - `./install-job.ts` — when a dependency install runs, and every guard on it.
+ * - `./deps-snapshot.ts` — starting a container from one that already installed.
  * - `./sync.ts` — the host's half of syncing, which nothing else will do.
  * - `./ca-trust.ts` — making a container able to speak TLS.
  * - `./git-identity.ts` — who a container's commits belong to.
- * - `./git-host.ts` — the operations that hold the forge credential.
+ * - `./git-host.ts` — the operations that hold the GitHub credential.
  *
  * Each takes a small explicit seam, and that is the test: a module that needed
  * the whole object back would be a module that did not want extracting.
@@ -77,7 +78,7 @@ export const WORKSPACE_DIR = "/workspace";
  * The Durable Object name for one caller's checkout of one repository.
  *
  * Exported because several places must agree on it and none can see the others:
- * the plugin that resolves the stub, the agent that hands it down to subagents,
+ * the plugin that resolves the stub, the agent that hands it down to sub-agents,
  * and the cancellation path. A pipe rather than a slash, so the caller half
  * cannot forge a repository boundary by containing one.
  *
@@ -90,7 +91,7 @@ export const WORKSPACE_DIR = "/workspace";
  *
  * `repo` is not always a repository. A host may pass a sentinel through here as
  * one — a scratchpad is modelled that way, which is what keys it to its own
- * object and its own container. Anything that is not a forge name works, as long
+ * object and its own container. Anything that is not a GitHub name works, as long
  * as no caller could clone something that collides with it.
  */
 export function workspaceName(callerKey, repo) {
@@ -123,31 +124,40 @@ const IDLE_RECLAIM_ID = "idle-reclaim-id";
  * Source-only workspaces are small (6.3 MB for slack-gatekeeper), which makes
  * this hygiene rather than cost control — but unbounded hygiene is still
  * unbounded.
+ *
+ * Exported because a host keeping work in a workspace has to say how long that
+ * work survives untouched.
  */
-const IDLE_RECLAIM_MS = 7 * 24 * 60 * 60 * 1000;
+export const IDLE_RECLAIM_MS = 7 * 24 * 60 * 60 * 1000;
 /** Where the container-idle deadline keeps its current schedule id. */
 const CONTAINER_IDLE_ID = "container-idle-id";
+/** The holds on the container — see `hold` — as key → the time each lapses. */
+const HOLDS_KEY = "container-holds";
+/** When a release was asked for while a hold stood, for the last `unhold`. */
+const RELEASE_ASKED_KEY = "container-release-asked";
 /** Where the container-warm wake keeps its current schedule id. */
 const CONTAINER_WARM_ID = "container-warm-id";
+/** Where the dependency-snapshot wake keeps its current schedule id. */
+const DEPS_SNAPSHOT_ID = "deps-snapshot-id";
 /**
  * How long a container stays up after the last command **started**.
  *
- * Ours to schedule: `withWorkspaceContainer` wraps the runtime's raw
- * `ctx.container`, not `@cloudflare/containers`' `Container`, so there is no
- * `sleepAfter` to lean on.
+ * Ours to schedule. The backend replaces a container but never stops one, and
+ * there is no `@cloudflare/containers` `Container` here with a `sleepAfter` to
+ * lean on: a container nobody is using runs until this deadline stops it.
  *
  * **This must exceed the longest command the agent allows**, and breaking that
  * kills work in flight. Measured from when a command *starts*: `#touch()` arms
  * the clock on the way into this object, and a running command touches nothing
  * again until it finishes — `handle.result()` is one long await and the FUSE
- * traffic under it never surfaces as an RPC. Set equal to the computer plugin's
- * `DEFAULT_TIMEOUT_MS`, the two timers race and whichever fires first destroys
+ * traffic under it never surfaces as an RPC. Set equal to `DEFAULT_TIMEOUT_MS`
+ * in `./exec.ts`, the two timers race and whichever fires first destroys
  * the container the other depends on. Twenty minutes is double that ceiling;
- * raise it, never lower it, if `sb_exec` is given a longer timeout.
+ * raise it, never lower it, if `bash` is given a longer timeout.
  *
  * **The default, not the policy.** "Longest command" is a fact about the agent,
  * so one whose commands run longer must say so via
- * {@link WorkspaceObjectConfig.containerIdleMs} — `claude-coder` holds a
+ * {@link WorkspaceObjectConfig.containerIdleMs} — `claude-coordinator` holds a
  * `claude -p` session open for its whole 40-minute timeout.
  */
 const CONTAINER_IDLE_MS = 20 * 60_000;
@@ -174,13 +184,13 @@ const SYNC_DRAIN_GRACE_MS = 30 * 60_000;
 /**
  * How long a container start may take before the calls waiting on it are refused.
  *
- * A minute under core's per-call limit, and tied to it: past that limit core
- * abandons the call anyway, the model reads no reason, and the next call joins
- * the same stuck start. As late as that allows, because refusing a start that
- * was only slow clears `#readying` while it runs, and the next caller starts a
- * second one beside it — and a start pushing a large tree has taken nine minutes.
+ * Late, because refusing a start that was only slow clears `#readying` while it
+ * runs, and the next caller starts a second one beside it — and a start pushing
+ * a large tree has taken nine minutes. Not later, because a turn is cut at
+ * fifteen: past that the model reads no reason, and its next turn joins the
+ * same stuck start.
  */
-const READY_DEADLINE_MS = MAX_TOOL_CALL_MS - 60_000;
+const READY_DEADLINE_MS = 9 * 60_000;
 /**
  * `work`, refused once `ms` pass without it settling. The work itself goes on;
  * only the wait for it ends — see {@link READY_DEADLINE_MS}.
@@ -199,6 +209,22 @@ export function readyWithin(work, ms) {
  * see {@link WorkspaceObjectBase.#purgeSyncedTrees}.
  */
 const SYNCED_TREES_PURGED_KEY = "deps:purged";
+/**
+ * The `images` key a container starts from: `containers[].images.app` in the
+ * consumer's wrangler config. Named to the backend rather than left as its
+ * default, because {@link IMAGE_ENV} has to be read under the same key.
+ */
+const IMAGE_NAME = "app";
+/**
+ * The env name the prepared image's reference rides under — see `backend` for
+ * why it rides at all.
+ *
+ * Nothing reads it, and the spelling keeps it that way. `computerd` hands a
+ * command its allowlist plus every `COMPUTER_VAR_` name, and reads its own
+ * configuration from `COMPUTERD_`, where a later release could claim this
+ * name. Outside both, it stays in the daemon's environment, unread.
+ */
+const IMAGE_ENV = "DYNAMICAGENTS_IMAGE";
 // --- the object -------------------------------------------------------------
 /**
  * Named rather than the anonymous class expression an app would write here.
@@ -212,10 +238,9 @@ class WorkspaceContainerHost extends DurableObject {
 }
 /**
  * `withWorkspaceContainer` adds one method, `getWorkspaceContainer()`, over
- * `this.ctx.container` — the runtime's own container handle. There is no
- * `@cloudflare/containers` `Container` subclass here and so no `sleepAfter`:
- * idle shutdown is this object's job, and it lands on the wake map with
- * everything else.
+ * `this.ctx.container` — the runtime's own container handle, started with the
+ * image and instance size this object asks for. Stopping it is this object's
+ * job — see {@link CONTAINER_IDLE_MS}.
  */
 const WorkspaceContainerBase = withWorkspaceContainer(WorkspaceContainerHost);
 /**
@@ -223,14 +248,13 @@ const WorkspaceContainerBase = withWorkspaceContainer(WorkspaceContainerHost);
  *
  * Abstract because a Durable Object class takes no constructor arguments, so
  * per-agent configuration cannot arrive that way. {@link workspaceConfig} is the
- * seam, and it is the shape core's own `RecipeSubagentBase.subagentRuntime`
- * uses for exactly the same reason.
+ * seam, for the same reason Think's own hooks are methods rather than options.
  *
  * ## Why `backend` and `#workspace` are lazy
  *
  * **Base class fields run before subclass fields**, so as plain fields they
  * would read `undefined` from any `workspaceConfig()` that touches a subclass
- * field — which `ClaudeCoderWorkspaceDO`'s does, for its credential store.
+ * field — which `ClaudeCoordinatorWorkspace`'s does, for its credential store.
  * Memoised getters remove the hazard rather than documenting it, which is what
  * lets a subclass implement the seam however it likes.
  */
@@ -281,6 +305,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             idleReclaim: () => this.#onIdleReclaim(),
             containerIdle: (payload) => this.#onContainerIdle(payload),
             containerWarm: () => this.#onContainerWarm(),
+            depsSnapshot: () => this.#onDepsSnapshot(),
             syncRetry: (payload) => this.#onSyncDrain(payload)
         },
         onError: (err) => {
@@ -317,6 +342,18 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         key: CONTAINER_WARM_ID,
         callback: "containerWarm"
     });
+    /**
+     * Snapshot a container that just installed — see `./deps-snapshot.ts`.
+     *
+     * From the alarm rather than the install's drain, which a model turn's
+     * `waitUntil` may own.
+     */
+    #snapshotDue = namedDeadline({
+        storage: this.ctx.storage,
+        scheduler: this.#wake.scheduler,
+        key: DEPS_SNAPSHOT_ID,
+        callback: "depsSnapshot"
+    });
     /**
      * Come back and move the next block of an outstanding pull.
      *
@@ -349,11 +386,24 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         ready: () => this.#ready(),
         waitUntil: (promise) => this.ctx.waitUntil(promise),
         containerGone: () => this.#containerGone(),
+        installedRecords: (tree) => this.#snapshot.dueEntries(tree),
+        installed: async () => void (await this.#snapshotDue.set(new Date())),
+        tag: () => this.#tag,
+        id: () => this.ctx.id.toString()
+    });
+    /** The next container's dependency trees — see `./deps-snapshot.ts`. */
+    #snapshot = new DepsSnapshot({
+        storage: this.ctx.storage,
+        container: () => this.ctx.container,
+        image: () => this.#image,
+        workspace: () => this.#workspace,
+        rootFingerprint: (dir) => this.#install.rootFingerprint(dir),
+        tree: () => this.#install.tree(),
         tag: () => this.#tag,
         id: () => this.ctx.id.toString()
     });
     /**
-     * The forge credential, read at the moment it would be handed over.
+     * The GitHub credential, read at the moment it would be handed over.
      *
      * `#`-private, which is the only spelling actually unreachable over RPC — see
      * {@link WorkspaceGitConfig.tokenBinding} for why that matters here and not
@@ -392,19 +442,47 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      * Nothing sets `egressHost`; the default `computer.internal` is the host the
      * container's outbound HTTP is intercepted on, internal to that loopback.
      *
-     * The binding name and the egress policy are the subclass's — see
-     * {@link WorkspaceObjectConfig}, which carries the warnings on both.
+     * **The image rides in the env so that a deploy replaces the container.** The
+     * backend reuses a running container whose launch — env, network, size, image
+     * key — matches the one it asks for, and the image a key resolves to is not
+     * part of that: a container started before a deploy would go on running the
+     * old image under the new Worker. The library here and the `computerd` in the
+     * image are one release, and a daemon from across a version line fails to
+     * authenticate (`[stage=auth]`). With the prepared image's reference in the
+     * env as {@link IMAGE_ENV}, a new image is a new launch, and the next connect
+     * replaces the container. With no image prepared under {@link IMAGE_NAME}
+     * there is nothing to add, and the backend's start says so.
+     *
+     * The binding name, the egress policy and the instance size are the
+     * subclass's — see {@link WorkspaceObjectConfig}, which carries the warnings
+     * on each.
+     *
+     * `launch` is how a start restores a dependency snapshot instead of booting
+     * the image — see `./deps-snapshot.ts`. Never in the env: the env is part of
+     * what a running container is matched against.
      */
     #backendMemo;
     get backend() {
-        return (this.#backendMemo ??= new CloudflareContainerBackend({
+        return (this.#backendMemo ??= this.#newBackend());
+    }
+    /** The image a start boots, as the deploy prepared it. */
+    get #image() {
+        return this.ctx.container?.images?.[IMAGE_NAME];
+    }
+    #newBackend() {
+        const image = this.#image;
+        return new ContainerBackend({
             container: () => this,
             workspace: {
                 binding: this.#cfg.binding,
                 id: this.ctx.id.toString()
             },
-            egress: this.#cfg.egress
-        }));
+            egress: this.#cfg.egress,
+            name: IMAGE_NAME,
+            instance: this.#cfg.instance,
+            containerEnv: image === undefined ? {} : { [IMAGE_ENV]: image },
+            launch: this.#snapshot.launch
+        });
     }
     #workspaceMemo;
     get #workspace() {
@@ -447,6 +525,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         this.#gitIdentity.forget();
         this.#deps.forget();
         await this.#install.containerGone();
+        await this.#snapshot.forgetDue();
     }
     /**
      * Set once {@link reclaimIfIdle} has emptied storage, until the alarm it armed
@@ -486,7 +565,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      * method is reachable over RPC — see {@link WorkspaceGitConfig.tokenBinding}.
      *
      * **One start at a time**, because {@link #warmIfCold} makes overlap ordinary:
-     * a warm and the first `sb_exec` want the container at the same moment, as do
+     * a warm and the first `bash` want the container at the same moment, as do
      * a warm and the install alarm. Two starts means two trust commands through a
      * half-established connection, the second pushing the tree again behind the
      * first. Cleared on settle, so the next caller asks about the container that
@@ -499,19 +578,53 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         });
         return this.#readying;
     }
-    /** One start, run for whoever got there first — see {@link #ready}. */
+    /**
+     * One start, run for whoever got there first — see {@link #ready}.
+     *
+     * A cold start restores the dependency snapshot when one fits, and the marker
+     * the setup reads decides whether what came up is adopted as installed — see
+     * `./deps-snapshot.ts`.
+     */
     async #readyNow() {
         // Read **before** `ready()`, which starts a stopped container.
-        if (!this.ctx.container?.running)
+        let restoring;
+        if (!this.ctx.container?.running) {
             await this.#containerGone();
-        await this.#workspace.ready();
-        // Before the first exec, which pushes the whole tree into a new container.
-        await this.#purgeSyncedTrees();
-        await this.#trust.ensure();
-        await this.#gitIdentity.ensure();
-        const found = await this.#deps.ensure(await this.#install.dir());
-        if (found)
-            await this.#install.reconcile(found.marker);
+            restoring = await this.#snapshot.arm(() => this.#expectedTree());
+        }
+        try {
+            await this.#workspace.ready();
+            // Before the first exec, which pushes the whole tree into a new container.
+            await this.#purgeSyncedTrees();
+            await this.#trust.ensure();
+            await this.#gitIdentity.ensure();
+            const found = await this.#deps.ensure(restoring?.dir ?? (await this.#install.dir()));
+            if (found)
+                await this.#install.reconcile(found.marker);
+            if (restoring &&
+                (await this.#snapshot.restored(restoring, found?.marker)))
+                await this.#install.adopt(restoring);
+        }
+        finally {
+            this.#snapshot.disarm();
+        }
+    }
+    /**
+     * The install a cold start would owe: where the last one ran, or the checkout
+     * when none has — a worktree seeded before its first install.
+     */
+    async #expectedTree() {
+        const target = (await this.#install.target()) ?? (await this.#checkoutTarget());
+        if (!target)
+            return undefined;
+        const fingerprint = await this.#install.fingerprintFor(target);
+        return fingerprint ? { dir: target.dir, fingerprint } : undefined;
+    }
+    async #checkoutTarget() {
+        const record = await this.ctx.storage.get(CHECKOUT_KEY);
+        if (!record?.dir)
+            return undefined;
+        return { dir: record.dir, ...(record.repo ? { repo: record.repo } : {}) };
     }
     /**
      * Delete every `node_modules` that was synced into this object, once.
@@ -581,7 +694,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             observer: createCloudflareObserver({ tracing }),
             // Git, running **here** rather than in the container.
             //
-            // This is what lets the forge token stay on this side of the boundary.
+            // This is what lets the GitHub token stay on this side of the boundary.
             // `createGitClient` binds isomorphic-git to `provider()` — the local
             // SQLite store, not the wire — so a clone, fetch or push executes next to
             // the data it writes, and the container never holds a credential at all.
@@ -657,7 +770,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      *
      * A stub cannot enforce what the caller does with it: `runtime.exec` on this
      * one would run against a container with no CA. The exec paths take the other
-     * method — see `openWorkspaceFs` in `@dynamicagents/plugins/computer`.
+     * method — see `openWorkspaceFs` in `./open.ts`.
      */
     async __getWorkspaceFsStub() {
         await this.#touch();
@@ -669,7 +782,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         return this.#workspace.stub();
     }
     /**
-     * Ask the alarm to start the container, so the first `sb_exec` finds one that
+     * Ask the alarm to start the container, so the first `bash` finds one that
      * is up and already holding the tree.
      *
      * What this avoids is the push, not the boot — see {@link __getWorkspaceFsStub}.
@@ -679,7 +792,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      * nothing to push and nothing to run, and a container it never uses still
      * bills.
      *
-     * Only the arming is awaited. A warm that fails costs the next `sb_exec` the
+     * Only the arming is awaited. A warm that fails costs the next `bash` the
      * start it would have paid for anyway.
      */
     async #warmIfCold() {
@@ -697,7 +810,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         await this.#containerWarm.set(new Date());
     }
     /**
-     * Clone, fetch and push — the operations that need the forge token.
+     * Clone, fetch and push — the operations that need the GitHub token.
      *
      * The work is `./git-host.ts`, which owns why the credential stays on this
      * side of the boundary. What stays here is what only this object can do: the
@@ -716,6 +829,14 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         const behind = await this.#beforeGit();
         return behind ?? (await this.#gitHost.push(req));
     }
+    /**
+     * A checkout's `origin`, from this object's storage. Starts no container and
+     * moves no deadline, like {@link checkoutDir}: a pull request polled for its
+     * review is not the workspace in use.
+     */
+    async gitOrigin(dir) {
+        return await this.#gitHost.origin(dir);
+    }
     /**
      * Bring the workspace up to date, or say why git must not run.
      *
@@ -725,7 +846,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      * did not finish, the workspace still holds the tree as it was before the
      * commit — and isomorphic-git, running here, would push a branch that does not
      * include it. That is the one failure worth stopping for: the push reports
-     * success, the forge shows an older tree, and nothing in either account says
+     * success, GitHub shows an older tree, and nothing in either account says
      * why.
      *
      * Refused rather than attempted, because every alternative is worse. Pushing
@@ -787,13 +908,33 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
     async startInstall(req) {
         return await this.#install.start(req);
     }
+    /**
+     * This workspace's dependency snapshot, for another of the same class to start
+     * from — see {@link seedDepsSnapshot}. Starts no container and moves no
+     * deadline.
+     */
+    async depsSnapshot() {
+        return await this.#snapshot.get();
+    }
+    /**
+     * Start this workspace's next container from `record`, another workspace's
+     * dependency snapshot, when it fits the checkout here — a worktree at the same
+     * path as the checkout it was cut from. Call it after the checkout and before
+     * the first command.
+     *
+     * A snapshot is that workspace's whole disk, so offer one only between
+     * workspaces of the same caller.
+     */
+    async seedDepsSnapshot(record) {
+        return await this.#snapshot.seed(record, () => this.#expectedTree());
+    }
     // --- lifecycle ---------------------------------------------------------------
     /**
      * Mark this workspace as in use, and push its reclamation back.
      *
      * Every entry point calls this, which is what makes the idle clock measure
      * *use* rather than "when the agent last said this name". The agent hands a
-     * workspace name to a subagent once and then never sees the traffic; the
+     * workspace name to a sub-agent once and then never sees the traffic; the
      * workspace sees all of it.
      */
     async #touch() {
@@ -816,6 +957,116 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         await this.#idleReclaim.set(new Date(now + IDLE_RECLAIM_MS));
         await this.#containerIdle.set(new Date(now + this.#containerIdleMs));
     }
+    /**
+     * Stop the container, and **keep everything on disk**.
+     *
+     * The counterpart to {@link reclaimIfIdle}, and the difference is the whole
+     * reason both exist. A reclaim is for a workspace nobody wants again: it empties
+     * storage, so the checkout and the dependency snapshot go with the container.
+     * This is for a workspace that will be worked in again — the next task on the
+     * same repository skips the clone, and the install by restoring the snapshot.
+     *
+     * **Why a caller needs this at all.** The idle deadline would eventually do it,
+     * but it cannot be tuned down to meet a cost target: `containerIdleMs` must
+     * exceed the longest command the agent allows, and a container that outlives its
+     * work by that much bills for the difference. So a host that knows the work is
+     * finished says so, and the deadline goes back to being a backstop for the case
+     * where nothing got to say anything.
+     *
+     * Deliberately does **not** touch: `#touch()` would push the very deadline this
+     * is standing in for.
+     *
+     * `released: false` means the container is still up and the standing deadline
+     * still owns it — an install is running, or a pull is still moving blocks. Both
+     * resolve themselves: the drain re-arms the deadline to come back and finish,
+     * which is the same path `#onContainerIdle` takes. Under a {@link hold} the
+     * release is deferred instead, to the last `unhold`.
+     */
+    async releaseContainer() {
+        // Work this object cannot see. Deferred rather than refused: the last
+        // `unhold` releases, unless the workspace is used again first.
+        const holds = await this.#liveHolds();
+        if (holds.length > 0) {
+            await this.ctx.storage.put(RELEASE_ASKED_KEY, Date.now());
+            console.info(`[${this.#tag}] release deferred while held`, {
+                id: this.ctx.id.toString(),
+                holds
+            });
+            return { released: false };
+        }
+        await this.ctx.storage.delete(RELEASE_ASKED_KEY);
+        // An install in flight is "in use" even though nothing has called in.
+        // Same rule, and same reason, as `#onContainerIdle`.
+        const install = await this.#install.read();
+        if (install.state === "running")
+            return { released: false };
+        // Never stop a container with a pull still moving: that is what turns an
+        // outstanding write from late into lost. `#drainBeforeStop` carries the
+        // reasoning and re-arms the deadline when it defers.
+        const lastUsedAt = (await this.ctx.storage.get("lastUsedAt")) ?? 0;
+        if (await this.#drainBeforeStop(lastUsedAt, 0))
+            return { released: false };
+        // Dropped rather than left standing: the container is about to be gone, and an
+        // alarm that fires afterwards logs a stop against a container that is not
+        // running. `#touch` re-arms it the next time this workspace is used.
+        await this.#containerIdle.clear();
+        await this.#stopContainer("idle");
+        return { released: true };
+    }
+    /**
+     * Keep the container up for work this object cannot see, until `untilMs` or
+     * {@link unhold}.
+     *
+     * A Claude Code session a host starts here runs detached: nothing calls in
+     * while it works, and the runtime cannot list
+     * what is running. So a host done with the workspace cannot tell that the
+     * container is not, and {@link releaseContainer} would stop the session with
+     * it. A hold is the host saying so. It defers a release; it is not use, so it
+     * does not touch, and the idle deadline already outlasts a session.
+     *
+     * `untilMs` bounds a hold whose `unhold` never comes — a run cut between its
+     * start and its end. Past it the hold is ignored.
+     */
+    async hold(key, untilMs) {
+        const holds = await this.#holdMap();
+        holds[key] = untilMs;
+        await this.ctx.storage.put(HOLDS_KEY, holds);
+    }
+    /**
+     * The work a {@link hold} stood for is over. When it was the last hold, a
+     * release asked for while it stood happens now — unless the workspace was
+     * used since, in which case the next release is asked for by whoever used it.
+     */
+    async unhold(key) {
+        // Read and written with no other I/O between, so the object's input gate
+        // keeps another call from interleaving: the map written is the one decided on.
+        const holds = await this.#holdMap();
+        delete holds[key];
+        await this.ctx.storage.put(HOLDS_KEY, holds);
+        if (Object.keys(holds).length > 0)
+            return { released: false };
+        const asked = await this.ctx.storage.get(RELEASE_ASKED_KEY);
+        if (asked === undefined)
+            return { released: false };
+        // A use in the same millisecond as the ask counts as after it: wrongly
+        // keeping a container costs its idle window, wrongly stopping one a session.
+        const lastUsedAt = (await this.ctx.storage.get("lastUsedAt")) ?? 0;
+        if (lastUsedAt >= asked) {
+            await this.ctx.storage.delete(RELEASE_ASKED_KEY);
+            return { released: false };
+        }
+        return await this.releaseContainer();
+    }
+    /** Every hold, lapsed ones pruned. */
+    async #holdMap() {
+        const now = Date.now();
+        const stored = (await this.ctx.storage.get(HOLDS_KEY)) ?? {};
+        return Object.fromEntries(Object.entries(stored).filter(([, until]) => until > now));
+    }
+    /** The keys of the holds still standing. */
+    async #liveHolds() {
+        return Object.keys(await this.#holdMap());
+    }
     /**
      * Throw this workspace away if nothing has touched it for `maxIdleMs`.
      *
@@ -883,6 +1134,16 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             reason,
             running: this.ctx.container?.running ?? false
         });
+        // An install's snapshot the wake has not taken yet would go with the disk
+        // it is of, so it is taken here first. Not for a reclaim, which keeps
+        // nothing. Either way, one in flight needs the container running.
+        if (reason === "idle")
+            await this.#snapshot.takeDue();
+        await this.#snapshot.settled();
+        // Hang up the session to computerd first: a destroy that cuts it live
+        // surfaces as an uncaught `Network connection lost`. The workspace
+        // reconnects on its next use, and `close()` swallows its own failures.
+        await this.#workspaceMemo?.close();
         try {
             await this.ctx.container?.destroy();
         }
@@ -1013,7 +1274,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         }
         catch (err) {
             // A read of local SQLite that threw says nothing about the tree. Treat it
-            // as absent: refusing a delegation costs a round, starting a session in a
+            // as absent: refusing a delegation costs a tool call, starting a session in a
             // directory that may not exist costs the run.
             console.warn(`[${this.#tag}] could not probe a checkout`, {
                 id: this.ctx.id.toString(),
@@ -1025,7 +1286,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
     }
     /**
      * Everything currently true about this workspace that a caller must not assume
-     * away — the array `sb_exec`, `sb_write` and `sb_edit` all consult.
+     * away — the array `bash`, `edit` and the workspace's writes all consult.
      *
      * The policy is not here. `deriveAdvisories` decides which facts matter and
      * how they are worded; this method gathers what only the object can see and
@@ -1143,6 +1404,21 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             await this.#sync.arm((payload?.attempt ?? 0) + 1);
         }
     }
+    /** An install finished in this container — see `./deps-snapshot.ts`. */
+    async #onDepsSnapshot() {
+        // The record is read from this object's storage — each root's inputs, and
+        // which roots there are — so the install's own pull has to have landed: it
+        // carries the submodules a bootstrap cloned. One still moving comes back;
+        // one that failed is left to the stop, which drains before it takes.
+        const synced = await this.#sync.drain(SYNC_DRAIN_BUDGET_MS);
+        if (synced === "incomplete") {
+            await this.#snapshotDue.set(new Date(Date.now() + SYNC_DRAIN_RESUME_MS));
+            return;
+        }
+        if (synced === "failed")
+            return;
+        await this.#snapshot.takeDue();
+    }
     /** The idle-reclaim deadline came due. */
     async #onIdleReclaim() {
         const { reclaimed, idleMs } = await this.reclaimIfIdle();
@@ -1161,7 +1437,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      *
      * **Swallows its own failure.** Every other wake here is work somebody waits
      * for; this one is early, so a container that will not start must cost the
-     * next `sb_exec` a start rather than put the scheduler's retry ladder behind a
+     * next `bash` a start rather than put the scheduler's retry ladder behind a
      * deployment fault that will refuse for as long as it stands.
      */
     async #onContainerWarm() {
@@ -1191,6 +1467,13 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             await this.#containerIdle.set(new Date(Date.now() + this.#containerIdleMs));
             return;
         }
+        // Work nothing calls in for, which the deadline cannot measure: come back
+        // when the first hold lapses, without counting the hold as use.
+        const lapses = Object.values(await this.#holdMap());
+        if (lapses.length > 0) {
+            await this.#containerIdle.set(new Date(Math.min(...lapses)));
+            return;
+        }
         // Re-read the clock rather than trusting the alarm, the same way
         // `reclaimIfIdle` does. `#touch` moves the deadline forward, but an alarm
         // already in flight cannot be recalled — so without this a workspace that