@dynamicagents/plugins 0.12.0 → 0.13.0

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

@@ -4,20 +4,19 @@ 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 { 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 +29,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 +42,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.
  *
@@ -66,7 +65,7 @@ import { pathExists } from "../read.js";
  * - `./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 +76,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 +89,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 +122,38 @@ 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";
 /**
  * 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 +180,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 +205,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 +234,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 +244,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.
  */
@@ -353,7 +373,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         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 +412,38 @@ 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.
      */
     #backendMemo;
     get backend() {
-        return (this.#backendMemo ??= new CloudflareContainerBackend({
+        return (this.#backendMemo ??= this.#newBackend());
+    }
+    #newBackend() {
+        const image = this.ctx.container?.images?.[IMAGE_NAME];
+        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 }
+        });
     }
     #workspaceMemo;
     get #workspace() {
@@ -486,7 +525,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
@@ -581,7 +620,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 +696,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 +708,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 +718,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 +736,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 +755,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 +772,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
@@ -793,7 +840,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      *
      * 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 +863,117 @@ 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 tree go with the container. This is
+     * for a workspace that will be worked in again — the next task on the same
+     * repository has to skip the clone and the install, which is the cost the whole
+     * design is arranged around.
+     *
+     * **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 +1041,10 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             reason,
             running: this.ctx.container?.running ?? false
         });
+        // 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 +1175,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 +1187,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
@@ -1161,7 +1323,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 +1353,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

package/dist/workspace/open.d.ts

@@ -0,0 +1,95 @@
+import type { WorkspaceClient, WorkspaceStub } from "@cloudflare/computer";
+import type { WorkspaceAdvisory } from "./advisory.js";
+/**
+ * Reaching a workspace: which one a call names, and the two ways to open it.
+ *
+ * A leaf, so the object, `/computer`'s tools and its proxy in
+ * `../computer/proxy.ts` can import it without
+ * going through the barrel that re-exports them.
+ */
+/**
+ * Where a parent puts the workspace name so its sub-agents reach the same one.
+ *
+ * A sub-agent cannot compute this itself. The name is derived from the caller
+ * and the repository, and the checkout it should work in is one its parent
+ * chose — so a sub-agent that named its own would land beside the parent's
+ * checkout, in a workspace with nothing in it.
+ *
+ * A spec's `prepare` runs on the parent, where the name resolves, and its
+ * return value reaches the sub-agent's plugins as `runtime()`. That is the
+ * channel core built for exactly this, and it is emphatically *not* the
+ * sub-agent's input, which the parent's model writes — a workspace name there
+ * would be model-authored, and a model naming another caller's workspace would
+ * get that caller's files.
+ */
+export declare const WORKSPACE_RUNTIME_KEY = "workspaceName";
+/**
+ * Read a parent-resolved workspace name off a sub-agent's `runtime()`.
+ *
+ * Returns `undefined` rather than throwing on anything unexpected: a parent has
+ * no runtime at all, and falling back to the configured thunk is right there.
+ */
+export declare function workspaceNameFromRuntime(runtime: unknown): string | undefined;
+/**
+ * The Durable Object the workspace lives in, as this plugin needs to see it.
+ *
+ * Structural rather than imported: the class is the host's — it owns the
+ * container binding, the alarm and the install job — and a plugin that imported
+ * it would stop a second host from bringing its own. `__getWorkspaceStub` is the
+ * one method `getWorkspace()` calls across the boundary, and it is what
+ * `withWorkspace` installs (or what a host that constructs `Workspace` itself
+ * reimplements, which is the same three lines).
+ */
+export interface WorkspaceHost extends Rpc.DurableObjectBranded {
+    __getWorkspaceStub(): Promise<WorkspaceStub>;
+    /**
+     * The same workspace for filesystem-only work, which the host must serve
+     * **without starting a container**.
+     *
+     * The filesystem is the Durable Object's own SQLite, while the first command
+     * in a fresh container waits for the whole tree to be pushed into it — so a
+     * file tool served the other way waits minutes for a local `readdir`. See
+     * `WorkspaceObjectBase.__getWorkspaceFsStub` in `./object.ts`.
+     *
+     * Required rather than optional, for the reason {@link advisories} gives. A
+     * host with nothing to distinguish returns its own `__getWorkspaceStub()`.
+     */
+    __getWorkspaceFsStub(): Promise<WorkspaceStub>;
+    /**
+     * Everything currently true about the workspace that a caller must not assume
+     * away — see {@link file://./advisory.ts}. An empty array is the good case.
+     *
+     * Required rather than optional, and not only because Workers RPC types an
+     * optional method as a union nothing can call. A host with nothing to report
+     * returns `[]` in one line; a host that forgot to expose it gets a compile
+     * error instead of a `bash` that silently runs against a half-built
+     * `node_modules`, or against a workspace whose writes are being dropped.
+     *
+     * `deriveAdvisories` builds the array from what the host already knows, so
+     * implementing this is gathering what the host has rather than writing policy.
+     */
+    advisories(): Promise<readonly WorkspaceAdvisory[]>;
+}
+/**
+ * Open the workspace behind a Durable Object stub.
+ *
+ * The cast is unavoidable, and narrow enough to be worth isolating here rather
+ * than repeating. `getWorkspace` wants a handle whose `__getWorkspaceStub()`
+ * resolves to a `WorkspaceStub` — the concrete class, private fields and all.
+ * Across a Durable Object boundary Workers RPC hands back a structural
+ * `Stub<WorkspaceStub>`, which forwards every method faithfully but carries none
+ * of the class's private brand: runtime-compatible, type-incompatible. This is
+ * the only place in the plugin that gap is crossed.
+ */
+export declare function openWorkspace(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;
+/**
+ * The same workspace, opened for filesystem work alone.
+ *
+ * `getWorkspace` calls exactly one method on what it is handed, so the host is
+ * wrapped in an object answering it from the other side of the seam — see
+ * {@link WorkspaceHost.__getWorkspaceFsStub}. Everything past that is identical.
+ *
+ * **Only the file tools take this.** `bash` and `workspaceExec` need the
+ * container started and its CA installed, so they open it the other way.
+ */
+export declare function openWorkspaceFs(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;

package/dist/workspace/open.js

@@ -0,0 +1,63 @@
+import { getWorkspace } from "@cloudflare/computer";
+/**
+ * Reaching a workspace: which one a call names, and the two ways to open it.
+ *
+ * A leaf, so the object, `/computer`'s tools and its proxy in
+ * `../computer/proxy.ts` can import it without
+ * going through the barrel that re-exports them.
+ */
+/**
+ * Where a parent puts the workspace name so its sub-agents reach the same one.
+ *
+ * A sub-agent cannot compute this itself. The name is derived from the caller
+ * and the repository, and the checkout it should work in is one its parent
+ * chose — so a sub-agent that named its own would land beside the parent's
+ * checkout, in a workspace with nothing in it.
+ *
+ * A spec's `prepare` runs on the parent, where the name resolves, and its
+ * return value reaches the sub-agent's plugins as `runtime()`. That is the
+ * channel core built for exactly this, and it is emphatically *not* the
+ * sub-agent's input, which the parent's model writes — a workspace name there
+ * would be model-authored, and a model naming another caller's workspace would
+ * get that caller's files.
+ */
+export const WORKSPACE_RUNTIME_KEY = "workspaceName";
+/**
+ * Read a parent-resolved workspace name off a sub-agent's `runtime()`.
+ *
+ * Returns `undefined` rather than throwing on anything unexpected: a parent has
+ * no runtime at all, and falling back to the configured thunk is right there.
+ */
+export function workspaceNameFromRuntime(runtime) {
+    const value = runtime?.[WORKSPACE_RUNTIME_KEY];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Open the workspace behind a Durable Object stub.
+ *
+ * The cast is unavoidable, and narrow enough to be worth isolating here rather
+ * than repeating. `getWorkspace` wants a handle whose `__getWorkspaceStub()`
+ * resolves to a `WorkspaceStub` — the concrete class, private fields and all.
+ * Across a Durable Object boundary Workers RPC hands back a structural
+ * `Stub<WorkspaceStub>`, which forwards every method faithfully but carries none
+ * of the class's private brand: runtime-compatible, type-incompatible. This is
+ * the only place in the plugin that gap is crossed.
+ */
+export function openWorkspace(host) {
+    return getWorkspace(host);
+}
+/**
+ * The same workspace, opened for filesystem work alone.
+ *
+ * `getWorkspace` calls exactly one method on what it is handed, so the host is
+ * wrapped in an object answering it from the other side of the seam — see
+ * {@link WorkspaceHost.__getWorkspaceFsStub}. Everything past that is identical.
+ *
+ * **Only the file tools take this.** `bash` and `workspaceExec` need the
+ * container started and its CA installed, so they open it the other way.
+ */
+export function openWorkspaceFs(host) {
+    return getWorkspace({
+        __getWorkspaceStub: () => host.__getWorkspaceFsStub()
+    });
+}