toolroll 0.9.62 → 0.9.65

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 0.9.65 — 2026-10-22
+
+0.9.64 was tagged but never published: a macOS check failed on Node 24.
+0.9.65 is the first published release with everything listed under 0.9.64
+below, plus:
+
+- **The release check's upgrade test** skips a tagged release that never
+  reached npm, instead of failing to install it.
+- **A Linux build's network bridge always fits a socket path.** When the
+  plane's own folder is too deep for one, the bridge goes in the system temp
+  folder, which a confined Linux build never sees (its `/tmp` is its own).
+
+## 0.9.64 — 2026-10-22
+
+**Upgrading:** builds now reach only the network their approval allows
+(below). On a Mac, a project whose tests start a local server needs
+**Settings → Project → Network → local services** turned on. A machine with
+no OS sandbox (Windows, Linux without bubblewrap) no longer runs builds
+unless an instance operator allows it (`toolroll config unconfined-agents`).
+
+- **Builds reach only their approved network.** Each approved task seals
+  what its build may reach: the agent's provider, the package registries
+  the project uses, and hosts you add in **Settings → Project → Network**
+  (or `toolroll project network`). The OS sandbox refuses everything else,
+  name lookups included; a result's **Network** row shows what the build
+  connected to and what was refused.
+- **Agents you can watch.** A light cockpit with each task's agent lanes,
+  the live conversation in time order, and real terminals for running
+  builds.
+- **ACP agents.** OpenCode, Cursor, Cline, Qwen and Goose can build, each
+  checked on this machine before it takes work.
+- **Passwordless mode.** Signing in is the only password; credential
+  changes still ask for it.
+- **One page per task and agent**, with Activity, Result and Plan tabs and
+  one ⋯ menu.
+- **Lead sweeps.** One card and one yes start many isolated tasks, tracked
+  in one table.
+- **The lead queue.** Messages sent while the lead answers wait their turn.
+- **Lead tools on demand**, with prompt caching: smaller, cheaper turns.
+- **How it ran.** Every result shows time, turns, tokens and cache use.
+- **Signed webhooks become tasks.**
+- **Phone keyboard.** Chat and text boxes stay above it; Return writes a
+  new line on a phone.
+- **A calmer UI**: one button style, theme tokens, status glyphs and a Crew
+  rail.
+- **`toolroll release` finishes**: a release build is recorded as a commit of
+  its own holding exactly the candidate's files; the release now accepts it
+  by its files and deploys to it, instead of stopping at the check.
+- **Release check** sizes itself to the machine; deploys keep hidden table
+  ids and find dependencies behind macOS's temp-folder link.
+
+## 0.9.63 — 2026-10-13
+
+- **Scheduled flows run on their own.** Sign a flow once with limits
+  (runs a day, budget, end date); its on-time firings build without a
+  person, and the script it runs is checked again when it fires.
+- **Secrets in the OS keychain.** Tool keys, the Linear key, Google mail and
+  flow secrets move into the macOS Keychain or Linux Secret Service, never
+  argv or the database. OAuth tools give each run a short-lived token, never
+  the refresh token. Settings shows how each tool's runs get credentials.
+- **Builds stay in their own checkout.** A build can't read or write another
+  project's or another task's checkout, and a checkout swapped for a link
+  is refused at the next launch.
+- **Safer cleanup.** Removing finished checkouts runs git with hooks,
+  filters and nested-repo config switched off.
+- **Attack suite.** Every bypass found in review is a permanent test, run by
+  the Quick check whenever sandbox or secrets code changes.
+- **Tool secrets stay outside the build.** A broker outside the sandbox
+  holds them. Codex refuses tools that carry secrets. Shared dependencies and
+  `git gc` work inside the fence.
+- **Tighter sandbox.** Builds can no longer rename folders above protected
+  paths or inspect other processes' memory; tool servers get only the
+  environment they need.
+- **Tools with secrets need the macOS sandbox.** A build without it, and
+  every build on Linux, leaves those tools out and says why.
+- **`toolroll doctor`.** Checks that Toolroll's service holds no key a build
+  could read, and lists the steps to fix it. It reads only.
+- **Research tools answer every refusal**, even when the service accepts the
+  rest with an empty reply.
+
 ## 0.9.62 — 2026-10-12
 
 - **Release checks in minutes.** The upgrade path runs on a sample, CI's

package/README.md

@@ -409,13 +409,13 @@ do not loosen when you leave the room:
 | touch a default branch | builds land on `toolroll/<task>` in a leased worktree; push + PR happen only under a publication grant naming the exact repo, branch prefix, and base |
 | approve its own work | approval nonces are minted only on screens that restate the digest-bound terms, and require your approver token typed again — **no LLM sits in any approval path** — and the [agent fence](#what-an-agent-can-reach) keeps your remembered login, runner tokens and the database out of the agent's reach |
 | act on an irreversible option | `reversible` is a schema field; irreversible choices never auto-apply, and answering one from a phone takes a second minted confirmation tap |
-| see Toolroll's secrets | the [agent fence](#what-an-agent-can-reach) blocks your login, runner and bot tokens, stored provider keys and project tool secrets at the operating system; other providers' keys are stripped from each agent's environment; secrets live in 0600 files, never in the database, URLs, or logs |
+| see Toolroll's secrets | the [agent fence](#what-an-agent-can-reach) blocks your login, runner and bot tokens, stored provider keys and project tool secrets at the operating system; other providers' keys are stripped from each agent's environment; tool secrets rest sealed in the OS keychain ([how](#how-build-sessions-are-protected)) and other secrets in 0600 files, never in the database, URLs, or logs |
 | spend while idle | **an LLM never polls** — the daemon does every no-judgement chore at zero token cost and wakes an agent only on a real event |
 | spend without being counted | every provider spawn is stamped *before* it spends, so cost is measured, never asserted |
 | guess at a judgement call | it parks a typed decision — recap, options with reversibility, recommendation, evidence — and the other eleven tasks keep going |
 
 The whole claim is executable: one test,
-[`src/unattended.test.ts`](src/unattended.test.ts), queues twelve tasks,
+[`src/unattended.slow.test.ts`](src/unattended.slow.test.ts), queues twelve tasks,
 walks away, and comes back to pull requests.
 
 The name comes from a captain's night orders — the written standing instructions left for the officer of the watch: *proceed on this course without me, and wake me under exactly these conditions.* That is the product, and it is not about the hour: it is for **long-running work that outlasts your attention** — an afternoon of errands, a weekend, or yes, a night.
@@ -572,17 +572,75 @@ runner and coordinator tokens, chat bot tokens, the database and its backups,
 other runs' evidence) — everything there except the build's own worktree —
 and `~/.toolroll` (stored provider keys and project tool secrets).
 
+Seatbelt and bubblewrap deny the whole checkout pool and allow the build’s own
+checkout back, covering other projects created after launch too. Codex keeps
+the own checkout’s ancestors traversable and denies each other project folder
+found in trusted checkout pools at launch. A project added after a Codex build
+starts is covered on the next launch. Own Git data, linked shared dependencies
+and launch tools remain available.
+
 | | Auto | Full access |
 |---|---|---|
-| **Codex / OpenRouter** (any OS) | Codex's workspace sandbox (workspace writes, no network) with the fence | Codex's sandbox widened to write anywhere with network, with the fence |
-| **Claude** | macOS: the agent runs inside a sandbox that denies the fence. Linux/Windows: Claude's own file tools refuse the fence, but its shell is not fenced yet | same |
-| **Gemini** | macOS: fenced like Claude. Linux/Windows: not fenced yet | same |
+| **Codex / OpenRouter** (any OS) | Codex's workspace sandbox (workspace writes, no network) with the fence | Codex's sandbox widened to write anywhere, with the fence; its commands reach the network only when the project's network is open |
+| **Claude, Gemini, ACP agents** | macOS: the agent runs inside a Seatbelt sandbox that denies the fence. Linux: inside bubblewrap. Neither (Windows, or Linux without bubblewrap): the build doesn't start, unless an instance operator allows unconfined agents | same |
+
+**The network.** Each approved scope says what its build may reach: the
+agent's provider, the package registries the project uses (npm, PyPI,
+crates.io, the Go proxy, RubyGems, Maven), and any hosts an approver added
+with `toolroll project network --repo <p> --allow api.example.com`. Every
+connection goes through the run's own proxy, which admits only those hosts;
+the sandbox refuses everything else, name lookups included. On a Mac a build
+reaches no local service but its own proxy and tools: a project whose tests
+start a local server sets `--local any` (every local service on that Mac then
+becomes reachable). A result's **Network** row says what the build connected
+to and what was refused.
 
 Each attempt records how it was fenced. Two limits to know: in **API-key
 mode** an agent's own provider key is in its environment, so its shell can
 read it (subscription mode, the default, puts no key there); and a project's
-own tool secrets reach that project's tools. Reviews and the lead chat run
-with no tools and are confined to their own files. See [SECURITY.md](SECURITY.md).
+own tool secrets reach that project's tools. They stay in a per-run broker
+outside the fence: the agent gets only its address and a token that stops
+working when the run ends, and on macOS it can't read another process's
+arguments or environment. Reviews and the lead chat run with no tools and are
+confined to their own files. See [SECURITY.md](SECURITY.md).
+
+### How build sessions are protected
+
+A build runs as your own user, so Toolroll keeps the secrets it holds (tool
+keys and sign-ins, the Linear key, a Google mail connection, flow webhook
+secrets) away from it in layers:
+
+- **The fence.** The operating system denies the build Toolroll's own
+  folders, your home configuration and other projects (the table above).
+- **The broker.** A run's tools are served by a broker in Toolroll's own
+  process, outside the fence. The agent gets only the broker's local address
+  and a key for that run, which stops working when the run ends. Another
+  run's key opens nothing.
+- **The keychain.** At rest, secrets are in the macOS Keychain (through
+  `security`, with the value on its input) or the Linux Secret Service (the
+  system's `secret-tool`, value on its input). A fenced build can still ask
+  the keychain for an item, so each is sealed with a key in `tool-secrets`
+  beside Toolroll's database. Toolroll makes that folder when it starts,
+  before any build, and records which key it made; a folder, key or link put
+  there by anything else is refused. What a build reads is ciphertext.
+  Secrets are read only when a run starts. Files from before move into the
+  keychain the first time they are used, and the plaintext copy is removed.
+  Where there is no keychain, or the keyring doesn't answer, secrets stay in
+  owner-only files, and Settings and `toolroll integrations` say so.
+- **Short-lived tokens.** A service connected by signing in gives each run
+  a fresh access token of its own, made outside the fence when the run starts
+  and limited to read access for research steps where the service allows.
+  The refresh token never leaves Toolroll, and one renewal runs at a time
+  across Toolroll's processes. If a renewed sign-in can't be saved, the run
+  doesn't start and every token made for it is revoked. The run's token is
+  revoked when the run ends, or runs out on its own where the service has no
+  way to revoke it. Keys you paste in stay in the broker. Settings → Tools
+  shows which each tool uses.
+
+What remains: any program of yours running outside the fence (not started by
+a build) can read what you can, including Toolroll's folder and the keychain.
+Toolroll protects your secrets from its builds, not from other software you
+run.
 
 Every new-task and task-scope form has the same two-choice control. A task's
 choice is durable through planning rewrites and is sealed into the approved
@@ -1081,7 +1139,7 @@ doubling backoff, three-strike stalls a person exits with `task requeue` —
 and every provider spawn is stamped before it spends, so cost is measured,
 never asserted. CI on published PRs is watched as episodes that never call
 silence green. The whole unattended stretch is one test,
-[`src/unattended.test.ts`](src/unattended.test.ts): queue twelve, walk
+[`src/unattended.slow.test.ts`](src/unattended.slow.test.ts): queue twelve, walk
 away, come back to PRs. Architecture: [`docs/DESIGN.md`](docs/DESIGN.md);
 the item-by-item ledger: [`docs/PROGRESS.md`](docs/PROGRESS.md).
 

package/dist/acp-agents.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The coding agents Toolroll runs over the Agent Client Protocol
+ * (docs/plans/acp-adapter.md). Each is its own provider id — readiness,
+ * sign-in pauses, routing and spend stay per agent — but they share one
+ * transport (acp-client.ts), and a row here is the only place an agent is
+ * described.
+ *
+ * Nothing in a row is trusted to be true of the binary on this machine: an
+ * agent runs only after its conformance check passed against that exact
+ * binary (attestation), and the check is what proves the argv, the name it
+ * gives in `initialize`, and the models it offers. Until then it is listed
+ * and refused.
+ */
+import type { ProviderId } from "./contracts/provider.js";
+export declare const ACP_PROVIDER_IDS: readonly ["opencode", "cursor", "cline", "qwen", "goose"];
+export type AcpProviderId = (typeof ACP_PROVIDER_IDS)[number];
+/** The providers with their own adapter and key: everything that is not an ACP agent. */
+export type KeyedProviderId = Exclude<ProviderId, AcpProviderId>;
+export type AcpAgent = {
+    /** How people know it. */
+    name: string;
+    /** The command looked up on PATH. */
+    binary: string;
+    /** What starts its ACP server on stdio. */
+    argv: readonly string[];
+    /** What the operator runs to sign in. */
+    signIn: string;
+    /** Folders under the home directory that hold its own configuration and sign-in (fenced like other agents' homes). */
+    home: readonly string[];
+    /** What still reaches a run beside the brief: its own configuration surfaces, in words. */
+    configSurface: readonly string[];
+};
+export declare const ACP_AGENTS: Readonly<Record<AcpProviderId, AcpAgent>>;
+export declare function isAcpProvider(provider: string): provider is AcpProviderId;
+/** Whether a profile (or anything carrying a provider) is an ACP agent's: narrows the union. */
+export declare function isAcpProfile<P extends {
+    provider: string;
+}>(profile: P): profile is Extract<P, {
+    provider: AcpProviderId;
+}>;
+export declare function isKeyedProvider(provider: ProviderId): provider is KeyedProviderId;
+/** Build a per-provider record whose ACP entries all come from one function of the agent's row. */
+export declare function withAcp<K extends KeyedProviderId, V>(keyed: Record<K, V>, acp: (agent: AcpAgent, provider: AcpProviderId) => V): Record<K | AcpProviderId, V>;

package/dist/acp-agents.js

@@ -0,0 +1,62 @@
+export const ACP_PROVIDER_IDS = ["opencode", "cursor", "cline", "qwen", "goose"];
+export const ACP_AGENTS = {
+    opencode: {
+        name: "OpenCode",
+        binary: "opencode",
+        // --pure: "run without external plugins" (opencode 1.18 `acp --help`).
+        argv: ["acp", "--pure"],
+        signIn: "opencode auth login",
+        home: [".config/opencode", ".local/share/opencode"],
+        configSurface: ["~/.config/opencode (models, providers, permissions)", "repository AGENTS.md and opencode.json", "its own sign-ins (opencode auth login)"],
+    },
+    cursor: {
+        name: "Cursor",
+        binary: "cursor-agent",
+        argv: ["acp"],
+        signIn: "cursor-agent login",
+        home: [".cursor"],
+        configSurface: ["~/.cursor (rules, MCP servers)", "repository .cursor/rules and AGENTS.md", "its own sign-in"],
+    },
+    cline: {
+        name: "Cline",
+        binary: "cline",
+        argv: ["--acp"],
+        signIn: "cline auth",
+        home: [".cline"],
+        configSurface: ["~/.cline (settings, MCP servers)", "repository .clinerules", "its own sign-in"],
+    },
+    qwen: {
+        name: "Qwen Code",
+        binary: "qwen",
+        argv: ["--acp"],
+        signIn: "qwen (then /auth)",
+        home: [".qwen"],
+        configSurface: ["~/.qwen/settings.json (MCP servers, model settings)", "QWEN.md (global and repository)", "its own sign-in"],
+    },
+    goose: {
+        name: "Goose",
+        binary: "goose",
+        argv: ["acp"],
+        signIn: "goose configure",
+        home: [".config/goose"],
+        configSurface: ["~/.config/goose (providers, extensions)", "repository .goosehints", "its own sign-in"],
+    },
+};
+const ACP = new Set(ACP_PROVIDER_IDS);
+export function isAcpProvider(provider) {
+    return ACP.has(provider);
+}
+/** Whether a profile (or anything carrying a provider) is an ACP agent's: narrows the union. */
+export function isAcpProfile(profile) {
+    return ACP.has(profile.provider);
+}
+export function isKeyedProvider(provider) {
+    return !ACP.has(provider);
+}
+/** Build a per-provider record whose ACP entries all come from one function of the agent's row. */
+export function withAcp(keyed, acp) {
+    const out = { ...keyed };
+    for (const provider of ACP_PROVIDER_IDS)
+        out[provider] = acp(ACP_AGENTS[provider], provider);
+    return out;
+}

package/dist/acp-attest.d.ts

@@ -0,0 +1,44 @@
+/** What makes an interpreter load code beside the script it was given: never passed to an ACP launch. */
+export declare const INTERPRETER_INJECTION_ENV: readonly string[];
+/** Bumped whenever the conformance probe changes what it proves: every attestation made under another version is void. */
+export declare const ACP_CONFORMANCE_VERSION = 2;
+export type FileBinding = {
+    role: "launcher" | "interpreter" | "package" | "entry";
+    path: string;
+    sha256: string;
+    dev: number;
+    ino: number;
+    ctimeMs: number;
+    size: number;
+};
+/** How the attested binary is started, and every file that start depends on. */
+export type AcpLaunch = {
+    /** What is executed: the launcher itself, or the pinned interpreter. */
+    file: string;
+    /** Arguments before the agent's own ACP argv: a script's shebang arguments and the script itself. */
+    prefix: string[];
+    bindings: FileBinding[];
+};
+/** sha256 of a regular file, read without following a final symlink. */
+export declare function hashFile(path: string): string | null;
+/** The interpreter and its arguments a shebang line names — `#!/abs/interp [arg]` or `#!/usr/bin/env [-S] name [args]` — or null. */
+export declare function parseShebang(line: string, path: string): {
+    interpreter: string;
+    args: string[];
+} | null;
+/**
+ * How to launch a binary found at `launcher` (a realpath), with every file bound — or why it can't be. `path` is the
+ * PATH a `#!/usr/bin/env name` shebang is resolved on, once, here.
+ */
+export declare function launchOf(launcher: string, path: string): AcpLaunch | {
+    problem: string;
+};
+/** Whether every bound file is still the one that passed: same stat, or on any change the same sha256. */
+export declare function verifyLaunch(launch: AcpLaunch): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/** A stored launch, read strictly: anything this code never writes reads as null. */
+export declare function launchFromJson(json: string): AcpLaunch | null;

package/dist/acp-attest.js

@@ -0,0 +1,269 @@
+/**
+ * An ACP agent's admission (docs/plans/acp-adapter.md § Admission): it runs only on a passed conformance check of the
+ * exact binary on this runner, recorded as an attestation. Absence is denial.
+ *
+ * The record says how to launch that binary — a native launcher directly, a script through the interpreter its
+ * shebang named, resolved once at the check and pinned (the child's PATH never chooses it) — and binds every file
+ * that launch depends on: the launcher, the interpreter, and for a package its package.json and entry. Each binding
+ * keeps the file's stat tuple and sha256. At spawn, after all asynchronous setup, every binding is checked again: a
+ * changed stat is re-hashed, and the spawn refuses unless every hash still matches.
+ *
+ * What it proves, exactly: the bytes of those files are the bytes that passed the check, as of the re-check
+ * immediately before spawn. Not an exclusive lock on the paths: a writer racing the narrow window between that re-check
+ * and exec is not excluded (Node has no exec-by-descriptor), the same residual the version attestation states. Nor the
+ * agent's other files (a bundle's chunks, its plugins): those are its configuration surface. The environment
+ * variables that make an interpreter load other code are shed at every ACP launch (INTERPRETER_INJECTION_ENV).
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+/** What makes an interpreter load code beside the script it was given: never passed to an ACP launch. */
+export const INTERPRETER_INJECTION_ENV = [
+    "NODE_OPTIONS", "NODE_PATH", "NODE_REPL_EXTERNAL_MODULE", "PYTHONPATH", "PYTHONSTARTUP", "PYTHONHOME", "PYTHONINSPECT",
+    "RUBYOPT", "RUBYLIB", "PERL5OPT", "PERL5LIB", "PERLLIB", "BUN_OPTIONS", "DENO_DIR", "LD_PRELOAD", "LD_LIBRARY_PATH",
+    "DYLD_INSERT_LIBRARIES", "DYLD_LIBRARY_PATH", "DYLD_FRAMEWORK_PATH",
+];
+/** Bumped whenever the conformance probe changes what it proves: every attestation made under another version is void. */
+export const ACP_CONFORMANCE_VERSION = 2;
+const READ_CAP = 64 * 1024;
+const HASH_CHUNK = 1024 * 1024;
+/** sha256 of a regular file, read without following a final symlink. */
+export function hashFile(path) {
+    let fd = null;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | (constants.O_NONBLOCK ?? 0));
+        if (!fstatSync(fd).isFile())
+            return null;
+        const hash = createHash("sha256");
+        const buffer = Buffer.alloc(HASH_CHUNK);
+        for (;;) {
+            const read = readSync(fd, buffer, 0, HASH_CHUNK, null);
+            if (read === 0)
+                break;
+            hash.update(buffer.subarray(0, read));
+        }
+        return hash.digest("hex");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function head(path, cap) {
+    let fd = null;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | (constants.O_NONBLOCK ?? 0));
+        if (!fstatSync(fd).isFile())
+            return null;
+        const buffer = Buffer.alloc(cap);
+        return buffer.subarray(0, readSync(fd, buffer, 0, cap, 0));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function bind(role, path) {
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile())
+            return null;
+        const sha256 = hashFile(path);
+        if (sha256 === null)
+            return null;
+        return { role, path, sha256, dev: stat.dev, ino: stat.ino, ctimeMs: stat.ctimeMs, size: stat.size };
+    }
+    catch {
+        return null;
+    }
+}
+function isNative(bytes) {
+    if (bytes.length < 4)
+        return false;
+    const magic = bytes.readUInt32BE(0);
+    return magic === 0x7f454c46 || [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe, 0xbebafeca].includes(magic);
+}
+/** A name found on a PATH, by realpath; only absolute PATH entries count. */
+function onPath(name, path) {
+    for (const folder of path.split(delimiter)) {
+        if (folder === "" || !isAbsolute(folder))
+            continue;
+        try {
+            const real = realpathSync(join(folder, name));
+            const stat = statSync(real);
+            if (stat.isFile() && (stat.mode & 0o111) !== 0)
+                return real;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** The interpreter and its arguments a shebang line names — `#!/abs/interp [arg]` or `#!/usr/bin/env [-S] name [args]` — or null. */
+export function parseShebang(line, path) {
+    if (!line.startsWith("#!"))
+        return null;
+    const words = line.slice(2).trim().split(/\s+/).filter(one => one !== "");
+    const [first, ...rest] = words;
+    if (first === undefined || !isAbsolute(first))
+        return null;
+    if (first === "/usr/bin/env" || first === "/bin/env") {
+        const named = rest[0] === "-S" ? rest.slice(1) : rest;
+        const [name, ...args] = named;
+        if (name === undefined || name.includes("/") || name.startsWith("-") || name.includes("="))
+            return null;
+        const interpreter = onPath(name, path);
+        return interpreter === null ? null : { interpreter, args };
+    }
+    if (rest.length > 1)
+        return null;
+    try {
+        return { interpreter: realpathSync(first), args: rest };
+    }
+    catch {
+        return null;
+    }
+}
+/** The nearest package.json above a script and the file its `bin`/`main` names, when that is not the launcher. */
+function packageBindings(launcher) {
+    let folder = dirname(launcher);
+    for (let depth = 0; depth < 6; depth += 1) {
+        const file = join(folder, "package.json");
+        const bytes = head(file, READ_CAP);
+        if (bytes !== null) {
+            let parsed;
+            try {
+                parsed = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                return null;
+            }
+            const pkg = bind("package", file);
+            if (pkg === null)
+                return null;
+            const bins = typeof parsed["bin"] === "string" ? [parsed["bin"]] : parsed["bin"] !== null && typeof parsed["bin"] === "object" ? Object.values(parsed["bin"]) : [];
+            const entries = [...bins, parsed["main"]].filter((one) => typeof one === "string");
+            const out = [pkg];
+            for (const entry of new Set(entries)) {
+                let real;
+                try {
+                    real = realpathSync(join(folder, entry));
+                }
+                catch {
+                    continue;
+                }
+                if (real === launcher)
+                    continue;
+                const bound = bind("entry", real);
+                if (bound !== null)
+                    out.push(bound);
+            }
+            return out;
+        }
+        const up = dirname(folder);
+        if (up === folder)
+            break;
+        folder = up;
+    }
+    return [];
+}
+/**
+ * How to launch a binary found at `launcher` (a realpath), with every file bound — or why it can't be. `path` is the
+ * PATH a `#!/usr/bin/env name` shebang is resolved on, once, here.
+ */
+export function launchOf(launcher, path) {
+    const bytes = head(launcher, 4096);
+    if (bytes === null)
+        return { problem: `${launcher} can't be read` };
+    const self = bind("launcher", launcher);
+    if (self === null)
+        return { problem: `${launcher} can't be read` };
+    if (isNative(bytes))
+        return { file: launcher, prefix: [], bindings: [self] };
+    const first = bytes.toString("utf8").split("\n")[0] ?? "";
+    const shebang = parseShebang(first, path);
+    if (shebang === null)
+        return { problem: `${launcher} is neither a native program nor a script whose interpreter can be pinned (unsupported-launcher)` };
+    const interpreterBytes = head(shebang.interpreter, 4096);
+    if (interpreterBytes === null || !isNative(interpreterBytes))
+        return { problem: `${shebang.interpreter}, which runs ${launcher}, is not a native program (unsupported-launcher)` };
+    const interpreter = bind("interpreter", shebang.interpreter);
+    const pkg = packageBindings(launcher);
+    if (interpreter === null || pkg === null)
+        return { problem: `the files ${launcher} runs from can't all be read` };
+    return { file: shebang.interpreter, prefix: [...shebang.args, launcher], bindings: [self, interpreter, ...pkg] };
+}
+/** Whether every bound file is still the one that passed: same stat, or on any change the same sha256. */
+export function verifyLaunch(launch) {
+    for (const binding of launch.bindings) {
+        let stat;
+        try {
+            if (lstatSync(binding.path).isSymbolicLink())
+                return { ok: false, problem: `${binding.path} became a link since the check` };
+            stat = statSync(binding.path);
+        }
+        catch {
+            return { ok: false, problem: `${binding.path} is gone since the check` };
+        }
+        if (stat.dev === binding.dev && stat.ino === binding.ino && stat.ctimeMs === binding.ctimeMs && stat.size === binding.size)
+            continue;
+        if (hashFile(binding.path) !== binding.sha256)
+            return { ok: false, problem: `${binding.path} changed since the check — check the agent again` };
+    }
+    return { ok: true };
+}
+/** A stored launch, read strictly: anything this code never writes reads as null. */
+export function launchFromJson(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const value = parsed;
+    if (typeof value["file"] !== "string" || !isAbsolute(value["file"]))
+        return null;
+    if (!Array.isArray(value["prefix"]) || !value["prefix"].every(one => typeof one === "string"))
+        return null;
+    if (!Array.isArray(value["bindings"]) || value["bindings"].length === 0)
+        return null;
+    const bindings = [];
+    for (const one of value["bindings"]) {
+        if (one === null || typeof one !== "object")
+            return null;
+        const b = one;
+        if (!["launcher", "interpreter", "package", "entry"].includes(String(b["role"])))
+            return null;
+        if (typeof b["path"] !== "string" || !isAbsolute(b["path"]) || typeof b["sha256"] !== "string" || !/^[0-9a-f]{64}$/.test(b["sha256"]))
+            return null;
+        if (![b["dev"], b["ino"], b["ctimeMs"], b["size"]].every(n => typeof n === "number" && Number.isFinite(n)))
+            return null;
+        bindings.push({ role: b["role"], path: b["path"], sha256: b["sha256"], dev: b["dev"], ino: b["ino"], ctimeMs: b["ctimeMs"], size: b["size"] });
+    }
+    if (bindings[0]?.role !== "launcher")
+        return null;
+    // What is executed is a bound file — the launcher itself, or the bound interpreter with the launcher as its script
+    // — and nothing a stored row could point elsewhere.
+    const launcher = bindings[0].path;
+    const prefix = value["prefix"];
+    if (value["file"] === launcher) {
+        if (prefix.length !== 0)
+            return null;
+    }
+    else {
+        const interpreter = bindings.find(one => one.role === "interpreter");
+        if (interpreter === undefined || interpreter.path !== value["file"] || prefix[prefix.length - 1] !== launcher)
+            return null;
+    }
+    return { file: value["file"], prefix, bindings };
+}

package/dist/acp-check.d.ts

@@ -0,0 +1,28 @@
+import type { ProviderRunner } from "./provider.js";
+import { type Store } from "./store.js";
+import type { WorktreePool } from "./worktree.js";
+export declare const CHECK_PROMPTS: {
+    readonly ok: "Create a file named done.txt in the current folder containing exactly the word ok. Then stop. Do nothing else.";
+    readonly stop: "Run the shell command `sleep 120` and wait for it to finish.";
+};
+export type AcpCheckJob = {
+    store: Store;
+    runner: string;
+    token: string;
+    /** The watch running it: its project and its lease's owner. */
+    watch: {
+        repo: string;
+        owner: string;
+    };
+    pool: WorktreePool;
+    clock?: () => Date;
+    keyHome?: string;
+    /** Tests only: a stand-in agent runner. */
+    agent?: ProviderRunner;
+    /** Tests only: a PATH to find the agent on. */
+    env?: Readonly<Record<string, string | undefined>>;
+    progress?: (line: string) => void;
+};
+/** Close what no live watch holds any more, let go of what finished checks still hold, then run this runner's next
+ * check, if one is waiting. */
+export declare function runAcpChecks(job: AcpCheckJob): Promise<void>;