@dynamicagents/plugins 0.13.0 → 0.15.0

package/dist/workspace/git-host.js

@@ -1,226 +0,0 @@
-/**
- * What the container's own `git init` would write, over isomorphic-git's.
- *
- * isomorphic-git's `init` writes `core.*` for a filesystem without symlinks or
- * an executable bit that ignores case, and the container's git obeys it. With
- * `symlinks = false`, a command there that rewrites the tree — starter puts a
- * worktree on its branch with `checkout -f` — writes each link as a file holding
- * its target, and `status` calls that clean. With `filemode = false`, a script
- * made executable is committed as 100644. The store models all three.
- */
-const CONTAINER_CORE_CONFIG = {
-    "core.symlinks": true,
-    "core.filemode": true,
-    "core.ignorecase": false
-};
-export class WorkspaceGitHost {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    /**
-     * Each operation takes `url` explicitly rather than a remote name: resolving
-     * `origin` would read `.git/config`, a workspace file a co-installed shell
-     * tool can write.
-     */
-    async clone(req) {
-        return this.#run(req.allowedHosts, async (git, onAuth) => {
-            // Spelled out rather than `git.clone`, and the reason is the credential.
-            //
-            // `clone` is the one network operation the client does not give an
-            // `onAuth` callback — it authenticates only through a `headers` option,
-            // which means attaching the token to the very first request to a URL the
-            // *model* chose. Composing the same work out of `fetch` puts every
-            // credentialed request on this side of `onAuth` instead, where the host is
-            // checked at the moment the token would be handed over. The cost is four
-            // calls instead of one; `clone` is these four.
-            await git.init({ dir: req.dir });
-            // Straight after `init`, so a clone that fails part-way leaves nothing
-            // behind that the container's git would misread.
-            for (const [path, value] of Object.entries(CONTAINER_CORE_CONFIG))
-                await git.configSet({ dir: req.dir, path, value });
-            await git.remoteAdd({
-                dir: req.dir,
-                name: "origin",
-                url: req.url,
-                force: true
-            });
-            const fetched = await git.fetch({
-                url: req.url,
-                dir: req.dir,
-                onAuth,
-                // Omission is passed through as omission, because the tool the model
-                // reads says so: `repo_clone` describes `depth` as "omit for full
-                // history; needed if you must rebase", and `/repo` deliberately leaves
-                // the key off when it is unset. Defaulting to 1 here made every such
-                // clone shallow, so the one thing the model was told to omit it for —
-                // rebasing — failed on a repository it had asked for in full.
-                ...(req.depth === undefined ? {} : { depth: req.depth }),
-                singleBranch: true,
-                tags: false,
-                ...(req.branch ? { ref: req.branch } : {})
-            });
-            const landed = req.branch ?? fetched.defaultBranch?.replace(/^refs\/heads\//, "");
-            if (!landed)
-                throw new Error(`cloned ${req.url} but the remote named no default branch to check out`);
-            await git.checkout({ dir: req.dir, ref: landed });
-            // What a real `git clone` writes and the container's git will look for:
-            // without it the branch tracks nothing, and an agent reaching for a bare
-            // `git status` in the shell sees a branch with no upstream.
-            await git.configSet({
-                dir: req.dir,
-                path: `branch.${landed}.remote`,
-                value: "origin"
-            });
-            await git.configSet({
-                dir: req.dir,
-                path: `branch.${landed}.merge`,
-                value: `refs/heads/${landed}`
-            });
-            return landed;
-        });
-    }
-    async fetch(req) {
-        return this.#run(req.allowedHosts, async (git, onAuth) => {
-            const result = await git.fetch({
-                url: req.url,
-                dir: req.dir,
-                onAuth,
-                prune: true,
-                tags: false,
-                singleBranch: false,
-                // Every branch is fetched, but isomorphic-git still resolves one ref
-                // against the remote's list, and left to itself it picks the current
-                // branch's upstream. A checkout left on a branch whose pull request
-                // merged — and whose remote branch went with it — then fails every
-                // fetch with `Could not find refs/heads/<branch>`. The remote's HEAD
-                // is always listed.
-                remoteRef: "HEAD",
-                ...(req.depth ? { depth: req.depth } : {})
-            });
-            return `fetched ${req.url} (default branch ${result.defaultBranch ?? "unknown"})`;
-        });
-    }
-    /**
-     * `remote.origin.url` from the local store, or `undefined` where there is no
-     * checkout or no origin. Reads only, and needs no credential.
-     */
-    async origin(dir) {
-        try {
-            const url = await this.deps
-                .git()
-                .configGet({ dir, path: "remote.origin.url" });
-            return typeof url === "string" && url ? url : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    async push(req) {
-        return this.#run(req.allowedHosts, async (git, onAuth) => {
-            const result = await git.push({
-                url: req.url,
-                dir: req.dir,
-                ref: req.branch,
-                remoteRef: req.branch,
-                onAuth
-                // No `force`, ever, and not a knob: `/repo` refuses anything but a plain
-                // branch name precisely so that a push cannot be turned into a force
-                // push, and this is the other end of that promise.
-            });
-            // isomorphic-git reports a rejected push in the *result* rather than by
-            // throwing — a non-fast-forward comes back `ok: false` with the reason on
-            // the ref. Reading only the absence of an exception would report every
-            // rejected push as a success, in the one plugin whose entire theme is that
-            // a failed command is not a completed operation.
-            if (!result.ok) {
-                const perRef = Object.entries(result.refs)
-                    .filter(([, status]) => !status.ok)
-                    .map(([ref, status]) => `${ref}: ${status.error ?? "rejected"}`)
-                    .join("; ");
-                // `||`, not `??`, on the second rung: `perRef` is a joined string, so
-                // "no failing ref carried a reason" is `""` rather than nullish — and
-                // `??` would hand that through as the error message. A rejected push
-                // reporting a blank reason is the one outcome worse than a generic one.
-                throw new Error(result.error ?? (perRef || "the remote rejected the push"));
-            }
-            return `pushed ${req.branch} to ${req.url}`;
-        });
-    }
-    /**
-     * The shared body: entry-point bookkeeping, the credential, and the translation
-     * back into something that survives RPC.
-     *
-     * A thrown `GitError` loses its prototype crossing a Durable Object boundary,
-     * so `instanceof` on the far side is not available and the caller would be left
-     * pattern-matching a string. The `code` is lifted here, while the error is
-     * still itself, and travels as data.
-     */
-    async #run(allowedHosts, body) {
-        // Bound to the credential rather than checked before the call, which is
-        // strictly stronger: this is the moment the token would be handed over, and
-        // it sees the URL git actually authenticated against — including one it
-        // reached by redirect. A host nobody allowed gets no credential and the
-        // request fails unauthenticated, rather than the token being offered to it
-        // and *then* the mistake being noticed.
-        const onAuth = (url) => {
-            let host;
-            try {
-                const parsed = new URL(url);
-                if (parsed.protocol !== "https:")
-                    return {};
-                host = parsed.hostname;
-            }
-            catch {
-                return {};
-            }
-            if (!allowedHosts.includes(host)) {
-                console.warn(`[${this.deps.tag()}] refused to authenticate to a host`, {
-                    host
-                });
-                return {};
-            }
-            return { username: "x-access-token", password: this.deps.token() };
-        };
-        try {
-            return { ok: true, detail: await body(this.deps.git(), onAuth) };
-        }
-        catch (err) {
-            const code = err?.code;
-            const message = describeGitError(err);
-            console.error(`[${this.deps.tag()}] git failed`, { code, message });
-            return {
-                ok: false,
-                ...(typeof code === "string" ? { code } : {}),
-                message
-            };
-        }
-    }
-}
-/**
- * A git error's message with the chain of causes behind it.
- *
- * `@cloudflare/computer/git` wraps isomorphic-git's errors, and classifies some
- * by a heuristic: any failure whose message mentions `.git` beside a missing
- * path or a ref it could not find is reported as "not a git repository" — a
- * sentence that is wrong about a checkout that plainly is one, and names
- * neither the file nor the ref. What actually failed is only on `cause`, which
- * a Durable Object boundary does not carry, so it is folded into the message
- * here while the error is still itself.
- */
-export function describeGitError(err) {
-    const parts = [];
-    const seen = new Set();
-    let at = err;
-    for (let depth = 0; at !== undefined && at !== null && depth < 4; depth++) {
-        const e = at;
-        const text = typeof e.message === "string" ? e.message : String(at);
-        if (!seen.has(text)) {
-            seen.add(text);
-            const name = typeof e.name === "string" ? e.name : "";
-            parts.push(name && depth > 0 ? `${name}: ${text}` : text);
-        }
-        at = e.cause;
-    }
-    return parts.join(" ← ");
-}

package/dist/workspace/git-identity.d.ts

@@ -1,57 +0,0 @@
-import type { Workspace } from "@cloudflare/computer";
-/**
- * The identity a commit made in this container carries when nothing nearer
- * answers for it.
- *
- * `/repo` configures the checkouts it clones and names the identity on every
- * commit it makes — see {@link file://../repo/checkout.ts writeGitIdentity}.
- * Neither reaches a repository the container made for itself: a submodule
- * checked out by a bootstrap, a `git init`, a second clone from the shell. Those
- * have no identity at all, and git refuses to commit without one — so whatever
- * is driving the shell has to invent a name to get past the refusal, and that
- * invention is what ends up in the history.
- *
- * This is the layer underneath, so there is nothing to invent: every repository
- * in the container starts out attributed to the deployment.
- *
- * **System scope, not global.** `--global` writes `$HOME/.gitconfig`, and a
- * command run through the runtime cannot count on `HOME` being set to anything
- * in particular — nor is the identity a property of one user of the container.
- * `--system` is also the *lowest* precedence git has, which is the right place
- * for it: a checkout's own config still wins, and so does the environment
- * `/repo` and the session's launch put on a commit.
- */
-/** Written to `/etc/gitconfig`; the values arrive as variables, never inline. */
-export declare const GIT_IDENTITY_COMMAND: string;
-export interface ContainerGitIdentityDeps {
-    workspace: () => Workspace;
-    author: () => {
-        name: string;
-        email: string;
-    };
-    /** Log prefix and object id, for the one line an operator can see. */
-    tag: () => string;
-    id: () => string;
-}
-/**
- * The write above, once per container.
- *
- * In memory, with {@link file://./ca-trust.ts}'s lifetime and for its reason: it
- * describes one container, and an isolate that lost it re-runs an idempotent
- * command.
- */
-export declare class ContainerGitIdentity {
-    #private;
-    private readonly deps;
-    constructor(deps: ContainerGitIdentityDeps);
-    forget(): void;
-    /**
-     * Configure this container if it has not been configured yet.
-     *
-     * **Never throws**, like the CA install and unlike the dependency setup. What
-     * a failure costs is an attribution, and every later commit says plainly that
-     * it has no identity to use — where a throw here would fail a workspace that
-     * is otherwise entirely usable.
-     */
-    ensure(): Promise<void>;
-}

package/dist/workspace/git-identity.js

@@ -1,147 +0,0 @@
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-/**
- * The identity a commit made in this container carries when nothing nearer
- * answers for it.
- *
- * `/repo` configures the checkouts it clones and names the identity on every
- * commit it makes — see {@link file://../repo/checkout.ts writeGitIdentity}.
- * Neither reaches a repository the container made for itself: a submodule
- * checked out by a bootstrap, a `git init`, a second clone from the shell. Those
- * have no identity at all, and git refuses to commit without one — so whatever
- * is driving the shell has to invent a name to get past the refusal, and that
- * invention is what ends up in the history.
- *
- * This is the layer underneath, so there is nothing to invent: every repository
- * in the container starts out attributed to the deployment.
- *
- * **System scope, not global.** `--global` writes `$HOME/.gitconfig`, and a
- * command run through the runtime cannot count on `HOME` being set to anything
- * in particular — nor is the identity a property of one user of the container.
- * `--system` is also the *lowest* precedence git has, which is the right place
- * for it: a checkout's own config still wins, and so does the environment
- * `/repo` and the session's launch put on a commit.
- */
-/** Written to `/etc/gitconfig`; the values arrive as variables, never inline. */
-export const GIT_IDENTITY_COMMAND = [
-    'git config --system user.name "$GIT_NAME"',
-    'git config --system user.email "$GIT_EMAIL"',
-    "echo IDENTITY OK"
-].join(" && ");
-/** How long the write may take before it is not going to happen. */
-const IDENTITY_TIMEOUT_MS = 30_000;
-/**
- * The write above, once per container.
- *
- * In memory, with {@link file://./ca-trust.ts}'s lifetime and for its reason: it
- * describes one container, and an isolate that lost it re-runs an idempotent
- * command.
- */
-export class ContainerGitIdentity {
-    deps;
-    #done = false;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    forget() {
-        this.#done = false;
-    }
-    /**
-     * Configure this container if it has not been configured yet.
-     *
-     * **Never throws**, like the CA install and unlike the dependency setup. What
-     * a failure costs is an attribution, and every later commit says plainly that
-     * it has no identity to use — where a throw here would fail a workspace that
-     * is otherwise entirely usable.
-     */
-    async ensure() {
-        if (this.#done)
-            return;
-        const author = this.deps.author();
-        try {
-            const env_1 = { stack: [], error: void 0, hasError: false };
-            try {
-                const handle = __addDisposableResource(env_1, await this.deps
-                    .workspace()
-                    .runtime.exec(GIT_IDENTITY_COMMAND, {
-                    cwd: "/",
-                    encoding: "utf8",
-                    timeoutMs: IDENTITY_TIMEOUT_MS,
-                    env: { GIT_NAME: author.name, GIT_EMAIL: author.email }
-                }), false);
-                const result = await handle.result();
-                const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-                this.#done = result.exitCode === 0 && output.includes("IDENTITY OK");
-                if (this.#done)
-                    return;
-                console.warn(`[${this.deps.tag()}] could not set the container's git identity`, {
-                    id: this.deps.id(),
-                    output: output.trim()
-                });
-            }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
-            }
-            finally {
-                __disposeResources(env_1);
-            }
-        }
-        catch (err) {
-            console.warn(`[${this.deps.tag()}] could not set the container's git identity`, {
-                id: this.deps.id(),
-                err: String(err)
-            });
-        }
-    }
-}

package/dist/workspace/index.d.ts

@@ -1,49 +0,0 @@
-/**
- * `@dynamicagents/plugins/workspace` — the Durable Object a container workspace
- * lives in, and the client side every other plugin reaches it through.
- *
- * The filesystem **is** a Durable Object's SQLite, mounted into the container
- * over FUSE by `computerd`. Commands see a normal `/workspace`; the Worker reads
- * the same tree over RPC; and when the container is replaced the tree is pushed
- * back into the new one — so a checkout outlives the container that held it.
- *
- * `WorkspaceObjectBase` is the object: container backend, egress, CA trust,
- * credentialed git, the dependency install, the sync drain and idle reclaim. A
- * host subclasses it and answers a short config. Everything else here is what
- * reaches it from outside: `openWorkspace`, `workspaceExec`, and the advisory
- * vocabulary it reports its state in.
- *
- * `@dynamicagents/plugins/computer` is the agent's tools over it; `/repo` and
- * `/scratch` take `workspaceExec` injected.
- *
- * Requires the Workers **Paid** plan (containers) and a Durable Object binding
- * whose class extends `WorkspaceObjectBase` — see the README for the wrangler
- * block.
- */
-/** How a repository installs its dependencies — the mechanical half. */
-export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand, type InstallPlan, type InstallProbe, type InstallResolution, type InstallRule, type InstallState } from "./install.js";
-/**
- * The workspace-advisory vocabulary, which a host needs all of: the type to
- * return over RPC, `deriveAdvisories` to build it from what it already knows,
- * and `sessionAdvisory` for a host driving a whole session rather than one
- * command. `shapeOf` and `renderAdvisory` are exported for the specs that hold
- * their exhaustiveness — a host has no reason to call either, since calling them
- * would mean writing policy or wording that has one home already.
- */
-export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf, type AdvisoryAudience, type AdvisoryInput, type AdvisoryShape, type WorkspaceAdvisory } from "./advisory.js";
-export { pathExists } from "./read.js";
-export { cancelledNote, truncateOutput } from "./format.js";
-export { openWorkspace, openWorkspaceFs, workspaceNameFromRuntime, WORKSPACE_RUNTIME_KEY, type WorkspaceHost } from "./open.js";
-export { withShell, withShellTranscript } from "./shell.js";
-export { workspaceExec, DEFAULT_CWD, DEFAULT_TIMEOUT_MS, type WorkspaceClientConfig } from "./exec.js";
-/**
- * The object itself. The modules below import the client-side leaves beside
- * them, never this barrel: a cycle through a module that builds a class at
- * import time is a base that evaluates `undefined`.
- */
-export { WorkspaceObjectBase, IDLE_RECLAIM_MS, WORKSPACE_DIR, workspaceName, type WorkspaceObjectConfig, type WorkspaceGitConfig } from "./object.js";
-export { InstallJob, type InstallJobDeps } from "./install-job.js";
-export { WorkspaceSync, SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, SYNC_DRAIN_MAX_BACKOFF_MS, syncRetryDelayMs, type DrainOutcome, type SyncDrainIntent, type WorkspaceSyncDeps } from "./sync.js";
-export { ContainerTrust, TRUST_CA_COMMAND, type ContainerTrustDeps } from "./ca-trust.js";
-export { WorkspaceGitHost, type GitHostDeps } from "./git-host.js";
-export type { WorkspaceWakeHandlers } from "./wake.js";

package/dist/workspace/index.js

@@ -1,58 +0,0 @@
-/**
- * `@dynamicagents/plugins/workspace` — the Durable Object a container workspace
- * lives in, and the client side every other plugin reaches it through.
- *
- * The filesystem **is** a Durable Object's SQLite, mounted into the container
- * over FUSE by `computerd`. Commands see a normal `/workspace`; the Worker reads
- * the same tree over RPC; and when the container is replaced the tree is pushed
- * back into the new one — so a checkout outlives the container that held it.
- *
- * `WorkspaceObjectBase` is the object: container backend, egress, CA trust,
- * credentialed git, the dependency install, the sync drain and idle reclaim. A
- * host subclasses it and answers a short config. Everything else here is what
- * reaches it from outside: `openWorkspace`, `workspaceExec`, and the advisory
- * vocabulary it reports its state in.
- *
- * `@dynamicagents/plugins/computer` is the agent's tools over it; `/repo` and
- * `/scratch` take `workspaceExec` injected.
- *
- * Requires the Workers **Paid** plan (containers) and a Durable Object binding
- * whose class extends `WorkspaceObjectBase` — see the README for the wrangler
- * block.
- */
-/** How a repository installs its dependencies — the mechanical half. */
-export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand } from "./install.js";
-/**
- * The workspace-advisory vocabulary, which a host needs all of: the type to
- * return over RPC, `deriveAdvisories` to build it from what it already knows,
- * and `sessionAdvisory` for a host driving a whole session rather than one
- * command. `shapeOf` and `renderAdvisory` are exported for the specs that hold
- * their exhaustiveness — a host has no reason to call either, since calling them
- * would mean writing policy or wording that has one home already.
- */
-export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf } from "./advisory.js";
-// A host implementing `InstallProbe` needs exactly this, and hand-rolling it
-// loses the fast path: across a Durable Object boundary `fs` is a stub carrying
-// `exists`, which a `stat`-only probe never asks for.
-export { pathExists } from "./read.js";
-export { cancelledNote, truncateOutput } from "./format.js";
-export { openWorkspace, openWorkspaceFs, workspaceNameFromRuntime, WORKSPACE_RUNTIME_KEY } from "./open.js";
-export { withShell, withShellTranscript } from "./shell.js";
-export { workspaceExec, DEFAULT_CWD, DEFAULT_TIMEOUT_MS } from "./exec.js";
-/**
- * The object itself. The modules below import the client-side leaves beside
- * them, never this barrel: a cycle through a module that builds a class at
- * import time is a base that evaluates `undefined`.
- */
-export { WorkspaceObjectBase, IDLE_RECLAIM_MS, WORKSPACE_DIR, workspaceName } from "./object.js";
-// The dependency install, exported because a host that wants to report on one —
-// or a spec that drives it — needs the type, not because anything but
-// `./object.ts` constructs it.
-export { InstallJob } from "./install-job.js";
-// The pull the library owns no alarm for. Its constants are exported because a
-// host deferring to a drain has to back off at the same rate this does.
-export { WorkspaceSync, SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, SYNC_DRAIN_MAX_BACKOFF_MS, syncRetryDelayMs } from "./sync.js";
-// `TRUST_CA_COMMAND` is exported so a host can assert what its image will be
-// asked to run — see the file for why this cannot live in an entrypoint.
-export { ContainerTrust, TRUST_CA_COMMAND } from "./ca-trust.js";
-export { WorkspaceGitHost } from "./git-host.js";

package/dist/workspace/install-job.d.ts

@@ -1,121 +0,0 @@
-import { type Workspace } from "@cloudflare/computer";
-import type { Scheduler } from "@dynamicagents/core/alarm";
-import { type InstallPlan, type InstallState } from "./install.js";
-import type { WorkspaceWakeHandlers } from "./wake.js";
-export interface InstallJobDeps {
-    storage: DurableObjectStorage;
-    scheduler: Scheduler<WorkspaceWakeHandlers>;
-    workspace: () => Workspace;
-    /** How this deployment installs dependencies for this agent's checkouts. */
-    plan: () => InstallPlan;
-    /** How long an install may run before it is killed. */
-    timeoutMs: () => number;
-    /** Set only when the workspace is over its ceiling. */
-    headroom: () => {
-        bytes: number;
-        capBytes: number;
-    } | undefined;
-    /** The object's own entry-point bookkeeping, which an install still owes. */
-    touch: () => Promise<void>;
-    ready: () => Promise<void>;
-    /** Hand a drain to the invocation, for the caller that can hold one. */
-    waitUntil: (promise: Promise<unknown>) => void;
-    /** A container was replaced, so nothing believed about it still holds. */
-    containerGone: () => Promise<void>;
-    tag: () => string;
-    id: () => string;
-}
-export declare class InstallJob {
-    #private;
-    private readonly deps;
-    constructor(deps: InstallJobDeps);
-    /**
-     * Start a dependency install the moment we can see one will be needed.
-     *
-     * The signal is {@link CONTAINER_TREE_KEY}: a local read, true only while the
-     * container that ran the install is the one running.
-     *
-     * Armed as soon as a container is up or a command is about to start one,
-     * because the model's first minute is README-reading and `git status` — an
-     * install armed there runs *through* that minute, where one armed on the first
-     * `npm` command charges its full time to that command.
-     *
-     * It writes `running` before anything is running: the alarm has not fired yet,
-     * and a `done` record would let an `npm` command through against a tree that
-     * is not there. That also makes this self-limiting — the next call sees
-     * `running` and stops.
-     */
-    armIfTreeMissing(): Promise<void>;
-    /** Where the last install ran, for the container setup's marker read. */
-    dir(): Promise<string | undefined>;
-    /** The container went away, and its tree with it. */
-    containerGone(): Promise<void>;
-    /**
-     * Check the record against the marker a new isolate's setup read.
-     *
-     * The record can outlive its container in an isolate that did not watch it
-     * exit; the marker cannot.
-     */
-    reconcile(marker: string | null): Promise<void>;
-    /**
-     * The record exactly as the job wrote it, with no staleness bound applied.
-     *
-     * {@link state} is what almost everything wants. This is for the one caller
-     * that must not repair anything on the way past: the container-idle handler,
-     * which only needs to know whether something is running before it destroys the
-     * container underneath it.
-     */
-    read(): Promise<InstallState>;
-    /**
-     * Start installing this checkout's dependencies, and return without waiting.
-     *
-     * Called from `repo_clone` through the repo plugin's `afterCheckout` hook, so
-     * it runs inside a model turn and must not block on the install — 225 seconds
-     * for slack-gatekeeper, against a turn that is cut at fifteen minutes.
-     *
-     * That caller is a model turn, which lives long enough to hold the drain handed
-     * to `ctx.waitUntil` below. **A short-lived caller cannot**, which is why an
-     * install the alarm drives is awaited inside that alarm rather than calling
-     * this.
-     */
-    start(req: {
-        dir: string;
-        repo?: string;
-    }): Promise<InstallState>;
-    /**
-     * Whether this container holds a finished tree, asked only when it qualifies a
-     * `deps-broken` advisory (see `deriveAdvisories`).
-     */
-    treePresentIfItMatters(install: InstallState): Promise<boolean>;
-    /**
-     * The install record itself, with its staleness bound and re-attach applied.
-     *
-     * Split from {@link advisories} so `startInstall` can consult the record
-     * without going through the `node_modules` probe, which needs a container and
-     * has nothing to say about whether an install may start.
-     *
-     * Re-attaches on the way past. An isolate reset leaves the record saying
-     * `running` with nothing draining it, and without this the state would say
-     * `running` forever while the command had long since finished.
-     */
-    state(): Promise<InstallState>;
-    /**
-     * When a reinstall was queued, if one is waiting to run.
-     *
-     * Read by {@link file://./advisory.ts deriveAdvisories}, which is the only
-     * caller that needs it: a `failed` record with a repair already queued is a
-     * transient condition wearing a permanent record's clothes.
-     */
-    reinstallArmedAt(): Promise<number | undefined>;
-    /**
-     * The armed reinstall came due.
-     *
-     * `clearArmed` first and unconditionally: this handler runs for minutes, and
-     * the stamp left in place is what a second arming would recognise as its own.
-     * The reservation in `#beginInstall` would catch a double, but the cheaper
-     * answer is not to schedule one.
-     */
-    onRun(): Promise<void>;
-    /** The watchdog: an install still running that nobody is draining. */
-    onWatch(): Promise<void>;
-}