@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/{computer → workspace}/install.d.ts

@@ -10,7 +10,7 @@
  *
  * ## Why this exists at all
  *
- * The alternative is a sentence in the subagent's soul — "install dependencies
+ * The alternative is a sentence in the sub-agent's soul — "install dependencies
  * before you do anything else" — and a standard with no command attached is one a
  * model satisfies with whichever check is cheapest: edit a README, run
  * `prettier --check` on that one file, report the change verified, and never run
@@ -36,25 +36,24 @@ export interface InstallProbe {
  * Where the install has got to, as the host reports it and the tools read it.
  *
  * Declared here rather than in the host because both sides depend on it and
- * neither owns the other: the Durable Object runs the job, and `sb_exec` refuses
+ * neither owns the other: the Durable Object runs the job, and `bash` refuses
  * to run against a tree that is still being built. A shape they agreed on
  * informally would drift, and the drift would show up as a shell command running
  * halfway through an `npm ci`.
  *
- * ## Why it is core's `JobState` with one field intersected in
+ * ## Why it is the host's `JobState` with one field intersected in
  *
- * Core owns the *choreography* around a job a Durable Object drives through its
- * alarm — arming, the single-flight guard, the staleness bound, the generation
- * marker a drain checks before it writes. This package owns what an install
+ * Core's `/job` owns the *choreography* around a job a Durable Object drives
+ * through its alarm — arming, the single-flight guard, the staleness bound, the
+ * generation a drain writes under. This package owns what an install
  * specifically **is**: which package manager, which lockfile, what counts as
  * skippable. Splitting them along that line is what lets a second job on the
  * same object — a coding-agent run, say — reuse every rule without inheriting
  * `npm ci`.
  *
  * `JobState` intersects `TExtra` into its `running`/`done`/`failed` variants
- * instead of nesting it under `meta`, so this alias is byte-identical to the
- * hand-written union it replaced. Every reader still spells `status.command` at
- * the top level and no call site moved.
+ * rather than nesting it under `meta`, so a reader spells `status.command` at
+ * the top level.
  */
 export type InstallState = JobState<{
     command: string;
@@ -137,8 +136,7 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  *
  * Content, not mtime: a `git fetch && reset --hard` onto a new commit rewrites
  * these files whether or not their dependencies changed, and re-installing on
- * every commit would throw away the thing that makes a warm container worth
- * having.
+ * every commit would throw away a tree that is already correct.
  *
  * ## Both files, not just the lockfile
  *
@@ -148,7 +146,7 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * from `pnpm@9` to `pnpm@10`, or add a dependency without regenerating the lock,
  * and every one of those changes what an install produces while leaving the
  * lockfile byte-identical. Hashing the lockfile alone calls that a match, skips
- * the install, and hands the subagent a `node_modules` that is quietly wrong —
+ * the install, and hands the agent a `node_modules` that is quietly wrong —
  * which surfaces as a missing module in a build, three tool calls later, with
  * nothing pointing back at the install that never ran.
  *
@@ -171,8 +169,8 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * {@link INSTALL_CONFIG_FILES} is hashed too, for the same reason `package.json`
  * is: a lockfile says which versions, and `.npmrc` says how they are laid out.
  * Flipping pnpm's `node-linker` to `hoisted` produces a different
- * `node_modules` from a byte-identical lockfile, and a warm container would
- * otherwise skip the reinstall that change requires.
+ * `node_modules` from a byte-identical lockfile, and a matching fingerprint
+ * would otherwise skip the reinstall that change requires.
  *
  * The residual is worth stating because it cannot be closed here: an override
  * that *builds* — `npm ci && npm run build`, the documented example — is not
@@ -184,10 +182,8 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * ## This is only half of the skip condition
  *
  * A matching fingerprint means "the same install would produce the same tree".
- * It does **not** mean the tree is there. `node_modules` lives in the container
- * and dies with it, while this fingerprint is stored in the Durable Object and
- * does not — so on a cold container the two disagree, and a caller that skips on
- * the fingerprint alone skips the install that the empty tree needs most. The
- * caller must also confirm `node_modules` is actually present.
+ * It does **not** mean the tree is there: it is on the container's disk, and
+ * goes with the container. The caller also needs a record that this container
+ * finished it — see `./install-job.ts`.
  */
 export declare function installFingerprint(fs: InstallProbe, dir: string, resolution: InstallResolution): Promise<string | null>;

package/dist/{computer → workspace}/install.js

@@ -10,7 +10,7 @@
  *
  * ## Why this exists at all
  *
- * The alternative is a sentence in the subagent's soul — "install dependencies
+ * The alternative is a sentence in the sub-agent's soul — "install dependencies
  * before you do anything else" — and a standard with no command attached is one a
  * model satisfies with whichever check is cheapest: edit a README, run
  * `prettier --check` on that one file, report the change verified, and never run
@@ -211,8 +211,7 @@ async function firstPresent(fs, dir, names) {
  *
  * Content, not mtime: a `git fetch && reset --hard` onto a new commit rewrites
  * these files whether or not their dependencies changed, and re-installing on
- * every commit would throw away the thing that makes a warm container worth
- * having.
+ * every commit would throw away a tree that is already correct.
  *
  * ## Both files, not just the lockfile
  *
@@ -222,7 +221,7 @@ async function firstPresent(fs, dir, names) {
  * from `pnpm@9` to `pnpm@10`, or add a dependency without regenerating the lock,
  * and every one of those changes what an install produces while leaving the
  * lockfile byte-identical. Hashing the lockfile alone calls that a match, skips
- * the install, and hands the subagent a `node_modules` that is quietly wrong —
+ * the install, and hands the agent a `node_modules` that is quietly wrong —
  * which surfaces as a missing module in a build, three tool calls later, with
  * nothing pointing back at the install that never ran.
  *
@@ -245,8 +244,8 @@ async function firstPresent(fs, dir, names) {
  * {@link INSTALL_CONFIG_FILES} is hashed too, for the same reason `package.json`
  * is: a lockfile says which versions, and `.npmrc` says how they are laid out.
  * Flipping pnpm's `node-linker` to `hoisted` produces a different
- * `node_modules` from a byte-identical lockfile, and a warm container would
- * otherwise skip the reinstall that change requires.
+ * `node_modules` from a byte-identical lockfile, and a matching fingerprint
+ * would otherwise skip the reinstall that change requires.
  *
  * The residual is worth stating because it cannot be closed here: an override
  * that *builds* — `npm ci && npm run build`, the documented example — is not
@@ -258,11 +257,9 @@ async function firstPresent(fs, dir, names) {
  * ## This is only half of the skip condition
  *
  * A matching fingerprint means "the same install would produce the same tree".
- * It does **not** mean the tree is there. `node_modules` lives in the container
- * and dies with it, while this fingerprint is stored in the Durable Object and
- * does not — so on a cold container the two disagree, and a caller that skips on
- * the fingerprint alone skips the install that the empty tree needs most. The
- * caller must also confirm `node_modules` is actually present.
+ * It does **not** mean the tree is there: it is on the container's disk, and
+ * goes with the container. The caller also needs a record that this container
+ * finished it — see `./install-job.ts`.
  */
 export async function installFingerprint(fs, dir, resolution) {
     if (resolution.kind !== "run")

package/dist/workspace/object.d.ts

@@ -0,0 +1,502 @@
+import { DurableObject } from "cloudflare:workers";
+import { type WorkspaceEgressPolicy, type WorkspaceStub } from "@cloudflare/computer";
+import { ContainerBackend, type ContainerInstanceSize } from "@cloudflare/computer/backends/container";
+import { type WorkspaceAdvisory } from "./advisory.js";
+import type { InstallPlan, InstallState } from "./install.js";
+import type { RepoGitResult } from "../repo/index.js";
+/**
+ * A workspace: one Durable Object, one container, one repository.
+ *
+ * **Shared by every agent in a Worker that has a container.** Each subclasses
+ * {@link WorkspaceObjectBase}, supplies a {@link WorkspaceObjectConfig}, and
+ * inherits everything else. Keep that seam narrow: it is the complete answer to
+ * "what is different about this agent's container", and anything that does not
+ * fit through it becomes a second copy of this file.
+ *
+ * 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 `bash` carries no container backend and
+ * no isomorphic-git.
+ *
+ * What this file must not do is import the plugin barrel. The barrel re-exports
+ * this module, and the class below is built at import time — a cycle would
+ * evaluate its base as `undefined`. The imports above reach the leaf modules
+ * beside it instead.
+ *
+ * `@cloudflare/computer` pairs a SQLite-backed virtual filesystem in *this*
+ * object's storage with a container running `computerd`, which mounts it over
+ * 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 `@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.
+ *
+ * **It constructs `Workspace` rather than using `withWorkspace`.** The mixin
+ * stores the `Workspace` under a module-private symbol the package does not
+ * export, so a method on the object cannot reach it — and what the host is
+ * required to do needs exactly that: driving an outstanding pull (the library
+ * owns no alarm and schedules nothing of its own), and the direct `runtime`
+ * access the detached install needs. So this object owns the `Workspace` and
+ * implements the one method the mixin otherwise provides,
+ * `__getWorkspaceStub`. Callers outside see no difference.
+ *
+ * ## What is here, and what is a module next door
+ *
+ * This file is the Durable Object: the wake map, the deadlines, the RPC surface
+ * and the wiring between them. The work each of those drives has its own home,
+ * and each carries the reasoning for its own decisions:
+ *
+ * - `./install-job.ts` — when a dependency install runs, and every guard on it.
+ * - `./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 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.
+ */
+/** Where every checkout lives, inside the container and in the VFS. */
+export declare 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 sub-agents,
+ * and the cancellation path. A pipe rather than a slash, so the caller half
+ * cannot forge a repository boundary by containing one.
+ *
+ * `repo` is undefined only before the first `repo_clone` or `scratch_open` of a
+ * session — what a task works in is model-chosen, so there is genuinely nothing
+ * to key on until it has chosen. That window resolves to a caller-level
+ * workspace, which is never worked in: `beforeCheckout` sets the repository
+ * before any git runs, and `scratch_open` sets its sentinel before anything
+ * resolves a name.
+ *
+ * `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 GitHub name works, as long
+ * as no caller could clone something that collides with it.
+ */
+export declare function workspaceName(callerKey: string, repo?: string): string;
+/**
+ * How long a workspace survives without being used.
+ *
+ * A Durable Object is **never** reclaimed by the platform, and a namespace
+ * cannot be enumerated from a Worker, so nothing else is coming to clean up.
+ * 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.
+ */
+export declare const IDLE_RECLAIM_MS: number;
+/**
+ * `work`, refused once `ms` pass without it settling. The work itself goes on;
+ * only the wait for it ends — see {@link READY_DEADLINE_MS}.
+ */
+export declare function readyWithin(work: Promise<void>, ms: number): Promise<void>;
+/**
+ * Named rather than the anonymous class expression an app would write here.
+ *
+ * This package emits declarations, and `DurableObject` brings `ctx` and `env` in
+ * protected — which makes the mixin's return type unnameable in a `.d.ts` and
+ * fails the build with TS4094. A named base gives the emitted type something to
+ * refer to. It costs one identifier and is invisible to a consumer.
+ */
+declare class WorkspaceContainerHost extends DurableObject<Cloudflare.Env> {
+}
+/**
+ * `withWorkspaceContainer` adds one method, `getWorkspaceContainer()`, over
+ * `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}.
+ */
+declare const WorkspaceContainerBase: typeof WorkspaceContainerHost & (new (...args: any[]) => WorkspaceContainerHost & {
+    getWorkspaceContainer(): import("@cloudflare/computer/backends/container").WorkspaceContainerAPI;
+});
+/**
+ * The GitHub credential, and who a commit made on this side is attributed to.
+ *
+ * Config rather than an env read, because this class cannot name a consumer's
+ * ambient `Env` — it is an interface `wrangler types` generates into *their*
+ * app, and a plugin that named it would compile only against the one Worker that
+ * happened to spell its bindings that way.
+ *
+ * It is also the honest direction. These are the repo plugin's secrets, declared
+ * by that plugin's `requires.secrets`, and a workspace holds them only because
+ * git runs on this side of the container boundary — see
+ * {@link file://./git-host.ts} for why it has to.
+ */
+export interface WorkspaceGitConfig {
+    /**
+     * The **name** of the binding holding the GitHub credential — never the
+     * credential itself.
+     *
+     * `workspaceConfig()` is an ordinary method on the prototype, and on a Durable
+     * Object `protected` is a typechecker's opinion rather than a runtime
+     * boundary: anything holding the namespace can call it. A config carrying the
+     * token would therefore hand it to any caller that asked — exactly what
+     * {@link file://./git-host.ts} exists to prevent, since the credential is
+     * supposed to be unreachable from anywhere but the moment git authenticates.
+     *
+     * So the config names the binding and the object reads it. Naming a secret by
+     * string is what the plugin contract's `requires.secrets` already does, and it
+     * is the only form available here: this package cannot name a consumer's
+     * ambient `Env`.
+     *
+     * An unset binding reads `undefined`, which means an unauthenticated request
+     * rather than a throw — that is what lets a workspace with no token still
+     * clone a public repository.
+     */
+    tokenBinding: string;
+    /**
+     * Who a commit is attributed to — on this side, and in the container.
+     *
+     * Two things read it: this object's git client, and `./git-identity.ts`,
+     * which writes it into the container's system config so a repository the
+     * container made for itself is attributed rather than nameless.
+     *
+     * **The repo plugin is not one of them.** It resolves `RepoConfig.author`
+     * independently, with a generic fallback of its own, and nothing in either
+     * package checks the two agree — so a commit *can* be attributed differently
+     * depending on which side made it, and the only thing preventing that is a
+     * consumer answering both from one place. A deployment's fallback for an
+     * unset binding belongs where that binding is read; this takes the resolved
+     * answer.
+     */
+    author: {
+        name: string;
+        email: string;
+    };
+}
+/**
+ * What one workspace object does not share with the next.
+ *
+ * Everything else about a workspace is identical between agents, which is why
+ * this interface is short and why it is worth having at all: a seam this narrow
+ * makes "what is different about this agent's container" a question with a
+ * complete answer in one place.
+ */
+export interface WorkspaceObjectConfig {
+    /**
+     * The wrangler Durable Object binding this class is bound as.
+     *
+     * Not cosmetic and not derivable: `computerd` dials **back** through it. The
+     * backend builds the container's loopback from this name plus the object id,
+     * so a wrong one produces a container that starts, mounts nothing and fails
+     * at the first command with no mention of a binding.
+     */
+    binding: string;
+    /**
+     * Where this workspace's container may send traffic, and through what.
+     *
+     * `direct` is the plain behaviour: the container's own network position.
+     * `http-gateway` routes **everything** through a `Fetcher` this Worker
+     * supplies, which is what puts the Worker on the model path — see
+     * `@dynamicagents/plugins/claude-code`.
+     *
+     * **Required in practice, and its absence is silent.** It is a policy that
+     * defaults to `{ mode: "none" }`, and the backend derives the container's
+     * network flag from it. Omit it and the container
+     * comes up with no network at all: the workspace mounts, commands run, and
+     * the install dies on a registry it cannot reach with nothing naming egress
+     * as the cause.
+     */
+    egress: WorkspaceEgressPolicy;
+    /** How this deployment installs dependencies for this agent's checkouts. */
+    installPlan: InstallPlan;
+    /** Log prefix — `coding-workspace`, `claude-coordinator-workspace`. */
+    label: string;
+    /**
+     * How long this agent's container stays up after the last command **started**.
+     *
+     * A per-agent value because the invariant on {@link CONTAINER_IDLE_MS} — it
+     * must exceed the longest command the shell allows — is an invariant about the
+     * *agent*, and the two differ by a factor of four. The coder's longest command
+     * is a tool call; `claude-coordinator`'s is a whole `claude -p` session that runs
+     * detached for its entire timeout.
+     *
+     * Omit it for the default. Raise it, never lower it, and raise it whenever the
+     * agent's longest command grows.
+     */
+    containerIdleMs?: number;
+    /**
+     * The size this agent's container starts at — a tier such as `standard-2`, or
+     * `{ vcpu, memoryMib, diskMb }`.
+     *
+     * Requested on every start, and part of what a running container is matched
+     * against: change it and the next connect replaces a container started at the
+     * old size. Which size, and why there is no default: {@link file://./README.md}.
+     */
+    instance: ContainerInstanceSize;
+    /** The GitHub credential and commit identity — see {@link WorkspaceGitConfig}. */
+    git: WorkspaceGitConfig;
+}
+/**
+ * One caller's checkout of one repository, and the container that mounts it.
+ *
+ * Abstract because a Durable Object class takes no constructor arguments, so
+ * per-agent configuration cannot arrive that way. {@link workspaceConfig} is the
+ * 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 `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.
+ */
+export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env = Cloudflare.Env> extends WorkspaceContainerBase {
+    #private;
+    /**
+     * This Worker's bindings, as the host's own generated `Env` spells them.
+     *
+     * Re-declared rather than inherited so a subclass reading a binding of its own
+     * — `claude-coordinator`'s reaches for its credential pool — gets its real type
+     * instead of the base's. `declare` because the field is the runtime's; this
+     * only narrows what TypeScript believes about it.
+     */
+    readonly env: TEnv;
+    /**
+     * Everything this agent's workspace does differently. Called once, lazily.
+     *
+     * Read through {@link #cfg}, never directly: an implementation may build
+     * something real — `claude-coordinator`'s constructs its egress gateway — and this
+     * is consulted on the busiest path in the object.
+     */
+    protected abstract workspaceConfig(): WorkspaceObjectConfig;
+    get backend(): ContainerBackend;
+    /**
+     * What `getWorkspace(stub)` calls from outside this object.
+     *
+     * The one piece of `withWorkspace` reimplemented here — see the file comment
+     * for why the mixin is not used. `ready()` first, because the stub is only
+     * meaningful once the workspace has opened its store.
+     */
+    __getWorkspaceStub(): Promise<WorkspaceStub>;
+    /**
+     * The same workspace, for a caller that will only touch the filesystem.
+     *
+     * **The container is not started, and that is the whole difference.** The
+     * filesystem is this object's own SQLite, so a read or write of it needs no
+     * container and an absent one cannot block it. {@link __getWorkspaceStub} adds
+     * `#ready()`, and the first command in a fresh container re-pushes the whole
+     * tree before it runs, with `timeoutMs` reaching the spawned process and
+     * nothing earlier.
+     *
+     * 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 `./open.ts`.
+     */
+    __getWorkspaceFsStub(): Promise<WorkspaceStub>;
+    /**
+     * 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
+     * entry-point bookkeeping, and making the workspace current before git reads
+     * it.
+     */
+    gitClone(req: {
+        url: string;
+        dir: string;
+        allowedHosts: string[];
+        branch?: string;
+        depth?: number;
+    }): Promise<RepoGitResult>;
+    gitFetch(req: {
+        url: string;
+        dir: string;
+        allowedHosts: string[];
+        depth?: number;
+    }): Promise<RepoGitResult>;
+    gitPush(req: {
+        url: string;
+        dir: string;
+        branch: string;
+        allowedHosts: string[];
+    }): Promise<RepoGitResult>;
+    /**
+     * 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.
+     */
+    gitOrigin(dir: string): Promise<string | undefined>;
+    /**
+     * Start this checkout's dependency install, and return without waiting.
+     *
+     * Called from `repo_clone` through the repo plugin's `afterCheckout` hook, so
+     * it runs inside a model turn — see `./install-job.ts` for why the drain's owner
+     * is the thing that matters here.
+     */
+    startInstall(req: {
+        dir: string;
+        repo?: string;
+    }): Promise<InstallState>;
+    /**
+     * 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`.
+     */
+    releaseContainer(): Promise<{
+        released: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    hold(key: string, untilMs: number): Promise<void>;
+    /**
+     * 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.
+     */
+    unhold(key: string): Promise<{
+        released: boolean;
+    }>;
+    /**
+     * Throw this workspace away if nothing has touched it for `maxIdleMs`.
+     *
+     * Re-checks the clock rather than trusting the caller: the alarm may have been
+     * armed a week ago, and a use since then must win. Safe to call from anywhere
+     * for the same reason, which is what lets the agent's cron poke it as a
+     * backstop without needing to know anything.
+     */
+    reclaimIfIdle(maxIdleMs?: number): Promise<{
+        reclaimed: boolean;
+        idleMs: number;
+        bytes: number;
+    }>;
+    /**
+     * Record what was checked out here, and say whether it is actually visible.
+     *
+     * **The single writer of {@link CHECKOUT_KEY}**, called by the two paths that
+     * know a checkout landed: the repo plugin's `afterCheckout` hook, which fires
+     * only once a tree is established, and `scratch_open`, which fires once
+     * `git init` has exited 0.
+     *
+     * **Why the checkout is recorded apart from the install**, which call sites
+     * point here for rather than restating: an install is conditional and a
+     * checkout is not. `resolveInstallCommand` skips a checkout it finds nothing
+     * to install in — any without a `package.json` — so a path written only as
+     * part of an install is missing exactly there. What that costs is not an
+     * optimisation: {@link checkoutDir} is how a delegated session is told where
+     * to work, so a repository can clone perfectly, report itself correctly
+     * through the repo tools, and never be worked in. The install keeps its own
+     * context for the mirror-image reason — what to re-run on a cold container has
+     * a different lifetime from what is on disk.
+     *
+     * Returns the probe as well as the path, so a caller learns in one round trip
+     * whether the tree is visible rather than discovering it a delegation later.
+     */
+    noteCheckout(req: {
+        dir: string;
+        repo?: string;
+        kind: "repo" | "scratch";
+    }): Promise<{
+        dir: string;
+        present: boolean;
+    }>;
+    /**
+     * Where the work is — a directory holding a git repository, or nothing.
+     *
+     * Two callers depend on that being the meaning rather than "a path somebody
+     * wrote down once": a Claude Code session takes it as its cwd, and
+     * `discardWorkingTree` runs `git reset --hard` in it. Both want the same
+     * question answered, and neither can recover from a confident wrong answer.
+     *
+     * So it is **probed, not remembered**. A record is where to look; `.git` being
+     * there is what makes the answer true. That costs one local read of this
+     * object's own SQLite — everything under the checkout is durable, `.git`
+     * included — and it is what turns a stale record into `undefined` instead of
+     * into a session started in a directory that is no longer a checkout.
+     *
+     * The record is the only source. A workspace that has never recorded one
+     * answers `undefined` until its next checkout does, which `repo_clone` does on
+     * any tree it can fetch and reset.
+     */
+    checkoutDir(): Promise<string | undefined>;
+    /**
+     * Everything currently true about this workspace that a caller must not assume
+     * 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
+     * hands it over. That split is why a host cannot get the severity of its own
+     * workspace wrong.
+     *
+     * **Nothing that starts a long job belongs on this path**, and the rule is
+     * sharper here than anywhere else in the object because every tool call reads
+     * it. `startInstall` in particular must never be reached from here: it hands
+     * its drain to `ctx.waitUntil`, whose lifetime is the invocation's, and an
+     * invocation on this path is a tool call that returns in milliseconds. The
+     * drain outlives its owner, dies mid-`npm ci` with "WritableStream RPC stub
+     * was disposed without calling close()", and leaves a half-written tree.
+     *
+     * A missing dependency tree arms an install here, which runs in the alarm,
+     * which owns no request and outlives every RPC. Here because a command reads
+     * this before its `#ready()` starts a container, so the gate holds it for the
+     * install rather than letting it outrun one.
+     */
+    advisories(): Promise<readonly WorkspaceAdvisory[]>;
+    /**
+     * `computerd`'s outbound WebSocket upgrade, on its way back in.
+     *
+     * The container dials the loopback rather than the other way round, so this
+     * object is the server for its own container's capnweb session. Everything
+     * else on this object is RPC; this is the only HTTP it speaks.
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Every durable wake-up this object has, dispatched from the one alarm.
+     *
+     * **This must not throw.** The runtime retries a failing alarm handler a
+     * bounded number of times and then stops for good — so a throw here would
+     * eventually take every *future* wake-up down with it, permanently, and the
+     * only symptom is that nothing ever happens again.
+     *
+     * Nothing else belongs here. Each reason to wake is a registered callback the
+     * scheduler dispatches by name, so this method neither matches on keys nor
+     * catches per-callback failures — the scheduler retries a failing callback and
+     * reports one that fails for good through `onError`. Nor does it sweep for a
+     * schedule that neither rescheduled nor cleared itself: a one-shot row is
+     * dropped when it runs, so it cannot stay due forever.
+     */
+    alarm(): Promise<void>;
+}
+export {};