toolroll 0.9.60 → 0.9.62

package/dist/provider.js

@@ -21,7 +21,7 @@
 import { claudeFenceSettings, codexFenceArgv } from "./agent-fence.js";
 import { claudeSteerHooks } from "./steer-mailbox.js";
 import {} from "./exec.js";
-import { runStreamJsonl, runClaudeStreamJsonl, runGeminiStreamJsonl } from "./exec.js";
+import { runStreamJsonl, runClaudeStreamJsonl, runGeminiStreamJsonl, CLAUDE_COST_UNKNOWN } from "./exec.js";
 import { scanForSecrets } from "./evidence.js";
 import { FINDINGS_MODEL_SCHEMA } from "./contracts/review-findings.js";
 import { REVIEW_OUTPUT_LIMITS } from "./structured-output.js";
@@ -167,11 +167,26 @@ const CLAUDE_REVIEW_JSON_SCHEMA = {
     required: ["version"],
     additionalProperties: false,
 };
+/**
+ * A build's own setup (plan, build and repair; never a review, which keeps
+ * the isolation above). No settings file loads — not the user's, the
+ * repository's or the local one — so none of their hooks, plugins or
+ * permissions reach the run; Toolroll's one `--settings` (the fence and the
+ * steering hook) is all there is. MCP servers come only from `--mcp-config`:
+ * the project's named tools, or an explicit empty list. The repository's
+ * CLAUDE.md still loads, through `--add-dir` on the workspace. Sign-in is
+ * the CLI's own (keychain or ~/.claude), which no setting source governs.
+ * `-p` never shows the workspace trust prompt (Claude Code 2.1.290), so a
+ * fresh worktree can't wedge a headless run. Checked against 2.1.290 with
+ * planted user, project and local hooks and MCP servers: none loaded.
+ */
+export const CLAUDE_BUILD_ISOLATION_ARGV = ["--setting-sources", "", "--strict-mcp-config"];
+const EMPTY_MCP_CONFIG = '{"mcpServers":{}}';
 /** Claude's own tools that only make sense with a person to wake them. */
 export const HEADLESS_DISALLOWED_TOOLS = ["ScheduleWakeup", "CronCreate", "Monitor"];
 const claudeArgv = (invocation) => [
     "-p",
-    invocation.brief,
+    ...(invocation.streamInput === true ? ["--input-format", "stream-json"] : [invocation.brief]),
     ...(invocation.resumeSession === null ? [] : ["--resume", invocation.resumeSession]),
     // stream-json (arc 1): the terminal result event IS the old buffered
     // envelope, now arriving as one line of many — the streaming transport
@@ -197,22 +212,47 @@ const claudeArgv = (invocation) => [
             // turn that a -p process never gets. Denied at the harness too.
             "--disallowedTools", HEADLESS_DISALLOWED_TOOLS.join(","),
             ...(invocation.allowedTools === undefined || invocation.allowedTools.length === 0 ? [] : ["--allowedTools", invocation.allowedTools.join(",")]),
+            ...CLAUDE_BUILD_ISOLATION_ARGV,
+            ...(invocation.workspace === undefined ? [] : ["--add-dir", invocation.workspace]),
             ...(invocation.toolArgv ?? []),
             ...(invocation.extraMcpServers === undefined ? [] : ["--mcp-config", JSON.stringify({ mcpServers: invocation.extraMcpServers })]),
+            // Strict with nothing named still names its empty list.
+            ...((invocation.toolArgv ?? []).includes("--mcp-config") || invocation.extraMcpServers !== undefined ? [] : ["--mcp-config", EMPTY_MCP_CONFIG]),
             ...claudeSettingsArgv(invocation),
             ...(invocation.jsonSchema === undefined ? [] : ["--json-schema", JSON.stringify(invocation.jsonSchema)])
         ]),
 ];
-/** One --settings for a build: the fence's deny rules and the steering doorbell, whichever the run has. */
+/** The build's one --settings: no personal memory, plus the fence and steering doorbell. */
 function claudeSettingsArgv(invocation) {
-    const fenced = invocation.fence !== undefined && invocation.fence.length > 0;
-    if (!fenced && invocation.steerFolder === undefined)
-        return [];
+    const denied = [...(invocation.fence ?? []), ...(invocation.fileToolFence ?? [])];
     return ["--settings", JSON.stringify({
-            ...(fenced ? JSON.parse(claudeFenceSettings(invocation.fence)) : {}),
+            autoMemoryEnabled: false,
+            ...(denied.length > 0 ? JSON.parse(claudeFenceSettings(denied)) : {}),
             ...(invocation.steerFolder === undefined ? {} : { hooks: claudeSteerHooks(invocation.steerFolder.dir, invocation.steerFolder.name) }),
         })];
 }
+/** With no settings sources, only `--add-dir` folders' CLAUDE.md load, and only with this set. */
+const claudeEnv = (invocation) => invocation.phase === "review" || invocation.workspace === undefined ? {} : { CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1" };
+/** The flags a build's own setup depends on, by provider. */
+const ISOLATION_FLAGS = {
+    claude: ["--setting-sources", "--strict-mcp-config", "--settings", "--add-dir", "--mcp-config"],
+    codex: ["--ignore-user-config", "--ignore-rules"],
+    openrouter: ["--ignore-user-config", "--ignore-rules"],
+};
+/**
+ * Whether a failed launch was an installed CLI too old for a build's own
+ * setup: it names one of those flags as unknown. Then nothing ran, and the
+ * run says so plainly instead of reading as a failed sign-in or bad work.
+ */
+export function isolationUnsupported(provider, stderr) {
+    const flags = ISOLATION_FLAGS[provider] ?? [];
+    const said = stderr.slice(0, 8192);
+    const flag = flags.find(one => new RegExp(`(unknown|unexpected|unrecognized) (option|argument)[^\\n]{0,8}${one.replace(/-/g, "\\-")}\\b`, "i").test(said));
+    if (flag === undefined)
+        return null;
+    const name = provider === "claude" ? "Claude Code" : "Codex";
+    return `The installed ${name} doesn't support ${flag}, which builds need to run without your own hooks, plugins and MCP servers. Update ${name} and try again.`;
+}
 /**
  * The turn's own words, preferring the schema-validated structured field
  * (present only under `--json-schema`) over the plain result string — the
@@ -267,6 +307,7 @@ function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConf
         tokensIn: typeof input === "number" && input >= 0 ? input : null,
         tokensOut: typeof output === "number" && output >= 0 ? output : null,
         costUsd: typeof cost === "number" && cost >= 0 ? cost : null,
+        ...(result !== null && result[CLAUDE_COST_UNKNOWN] === true ? { costUnknown: true } : {}),
         usageRaw: result?.usage === undefined ? null : JSON.stringify(result.usage).slice(0, USAGE_JSON_CAP),
         initObserved,
         // Structural, never prose (finding 15): consumed means the primary
@@ -376,6 +417,21 @@ const codexSandboxArgv = (mode, resuming) => resuming ? ["-c", `sandbox_mode="${
  * servers, exactly the surface `--strict-mcp-config` closes for claude —
  * ignored outright.
  */
+/**
+ * A Codex build's own setup, the equivalent of Claude's: the operator's
+ * config.toml (its MCP servers, model choices, profiles) and execpolicy
+ * rules ignored, ChatGPT apps and plugins off (plugins carry their own MCP
+ * servers), and hooks off. Sign-in still comes from CODEX_HOME, which
+ * `--ignore-user-config` leaves alone. The project's named tools follow as
+ * `-c mcp_servers.*` (project-tools.ts).
+ */
+export const CODEX_BUILD_ISOLATION_ARGV = [
+    "--ignore-user-config",
+    "--ignore-rules",
+    "-c", "apps._default.enabled=false",
+    "-c", "features.plugins=false",
+    "-c", "features.hooks=false",
+];
 const CODEX_REVIEW_ISOLATION_ARGV = (resuming) => [
     "--ignore-user-config",
     ...codexSandboxArgv("read-only", resuming),
@@ -406,6 +462,7 @@ const codexArgv = (extra) => (invocation) => {
         ...(invocation.resumeSession === null ? [] : ["resume", invocation.resumeSession]),
         "--json",
         "--skip-git-repo-check",
+        ...(invocation.phase === "review" ? [] : CODEX_BUILD_ISOLATION_ARGV),
         ...(invocation.phase === "review"
             ? CODEX_REVIEW_ISOLATION_ARGV(resuming)
             // The agent fence: Codex's own sandbox with Toolroll's secrets
@@ -725,6 +782,7 @@ const ADAPTERS = {
     claude: {
         binary: "claude",
         argv: claudeArgv,
+        env: claudeEnv,
         parse: claudeParse,
         defaultRunner: runClaudeStreamJsonl,
         extraOmitEnv: foreignCredentialEnv("claude"),
@@ -788,13 +846,14 @@ const AUDITS = {
         initSignal: "system-init",
         sessionIdentity: "announced",
         terminalContract: "none",
-        // Restricted mode is resume-safe and is enforced for sealed reviewer
-        // turns. `enforced` remains false here because this provider-wide audit
-        // also covers ordinary build turns, where the flag is not applied.
-        isolation: { flag: "--restricted", resumeSafe: true, enforced: false },
+        // Builds: no settings sources and strict MCP, fresh and resumed alike
+        // (CLAUDE_BUILD_ISOLATION_ARGV). Reviews keep --restricted --safe-mode.
+        isolation: { flag: CLAUDE_BUILD_ISOLATION_ARGV.filter(one => one !== "").join(" "), resumeSafe: true, enforced: true },
         configSurface: [
-            "~/.claude/CLAUDE.md and settings (hooks, MCP servers, plugins)",
-            "repository CLAUDE.md / .claude directory",
+            "Toolroll's own --settings (the fence and steering hook)",
+            "the project's named tools (Settings → Tools)",
+            "repository CLAUDE.md",
+            "organisation-managed settings",
         ],
     },
     codex: {
@@ -803,10 +862,11 @@ const AUDITS = {
         initSignal: "thread.started",
         sessionIdentity: "announced",
         terminalContract: "none",
-        // --ephemeral exists and is deliberately not passed: repair resumes
-        // sessions, and ephemeral runs have none to resume.
-        isolation: { flag: "--ephemeral", resumeSafe: false, enforced: false },
-        configSurface: ["~/.codex/config.toml", "repository AGENTS.md"],
+        // Builds ignore config.toml and execpolicy rules, with apps, plugins and
+        // hooks off (CODEX_BUILD_ISOLATION_ARGV); sign-in stays in CODEX_HOME.
+        // Never --ephemeral: repair resumes sessions.
+        isolation: { flag: "--ignore-user-config --ignore-rules", resumeSafe: true, enforced: true },
+        configSurface: ["the project's named tools (Settings → Tools)", "~/.codex/AGENTS.md and repository AGENTS.md", "sign-in from CODEX_HOME"],
     },
     openrouter: {
         transport: "streaming-jsonl",
@@ -814,10 +874,9 @@ const AUDITS = {
         initSignal: "thread.started",
         sessionIdentity: "announced",
         terminalContract: "none",
-        isolation: { flag: "--ephemeral", resumeSafe: false, enforced: false },
-        // The constant -c overrides pin the model provider per invocation, so
-        // user config cannot reroute the spend — but the file still loads.
-        configSurface: ["~/.codex/config.toml (model_provider pinned per invocation)", "repository AGENTS.md"],
+        // Codex's build setup, with the model provider pinned by constant -c overrides.
+        isolation: { flag: "--ignore-user-config --ignore-rules", resumeSafe: true, enforced: true },
+        configSurface: ["the project's named tools (Settings → Tools)", "~/.codex/AGENTS.md and repository AGENTS.md", `${OPENROUTER_ENV_KEY}`],
     },
     gemini: {
         transport: "streaming-jsonl",

package/dist/remote-main.d.ts

@@ -0,0 +1,57 @@
+import { type ExecResult } from "./exec.js";
+import type { Store } from "./store.js";
+import type { Runner } from "./worktree.js";
+/** The only credential helper https may use: the system keychain on macOS; elsewhere none, so a private https remote
+ * fails closed instead of asking. */
+export declare const CREDENTIAL_HELPER: string;
+export type RemoteUrl = {
+    kind: "network";
+    url: string;
+};
+/**
+ * A URL Toolroll may fetch remote main from: https or ssh (either form). Local paths, file URLs and loopback hosts
+ * (this machine is where builds run) are always refused. Remote helpers (ext::, fd:: and the like), plain http and
+ * git:// (no authentication), relative paths, embedded passwords and anything odd are refused.
+ */
+export declare function parseRemoteUrl(url: string): RemoteUrl | {
+    why: string;
+};
+/** Why a recorded URL may not be used as the trusted remote; null when it may. */
+export declare function remoteUrlProblem(url: string): string | null;
+export type RemoteGit = (args: readonly string[]) => Promise<ExecResult>;
+export type RemoteMain = {
+    url: string;
+    /** The commit the recorded remote's main is at, as fetched just now. */
+    main: string;
+    /** Git in the private directory, hardened as above. */
+    git: RemoteGit;
+    /** Bring this exact commit (with its history) from the project by fetch, for a content comparison. */
+    bring: (repo: string, head: string) => Promise<boolean>;
+};
+export type RemoteMainRead = {
+    ok: true;
+    remote: RemoteMain;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * One pass's reads of recorded remotes. Every `read` fetches again (the pre-teardown re-check is never older than
+ * the teardown); a project's private directory lasts until `close`, so a fetch after the first only brings what
+ * changed. Close removes every directory.
+ */
+export declare class RemoteMains {
+    private readonly store;
+    private readonly runner;
+    private readonly scratch;
+    private readonly helper;
+    private readonly dirs;
+    constructor(store: Store, runner: Runner | undefined, scratch: string, helper?: string);
+    private exec;
+    /** Nothing but fetched objects decides: a private directory that grew alternates, grafts or shallow state is
+     * not trusted. */
+    private clean;
+    private dirFor;
+    read(repo: string): Promise<RemoteMainRead>;
+    close(): void;
+}

package/dist/remote-main.js

@@ -0,0 +1,179 @@
+/**
+ * The project's main as its recorded remote has it, read by Toolroll's own process. Automatic completion of landed
+ * work (landed-cleanup.ts) trusts only this: a build shares the project's .git, so it can move the local main or
+ * repoint origin in .git/config, and neither may complete its own task.
+ *
+ * The remote URL is the one captured on first admission or explicitly supplied by the owner (project-admission.ts), never the repository's
+ * config. Each read fetches that URL's main into a fresh, private Git directory under Toolroll's evidence folder (which
+ * the agent fence denies to builds), with no system or global config, no includes or URL rewriting, no replace
+ * objects, no hooks, no ext or file transport and only an explicit credential helper. The shared repository's objects, refs,
+ * replace refs, grafts and shallow state are never read: commits enter only by fetch. A content comparison brings the
+ * result's exact recorded commit in by fetch too; git checks every object against its hash.
+ *
+ * Every doubt fails closed: no recorded remote, a URL that isn't allowed, a failed fetch or a remote without main all
+ * read as "not proven", and the task stays for a person.
+ */
+import { mkdirSync, mkdtempSync, rmSync, existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { run } from "./exec.js";
+/** The ref a fetched remote main is kept under, inside the private directory only. */
+const REMOTE_MAIN = "refs/toolroll/remote-main";
+const SHA = /^[0-9a-f]{40}$/;
+const FETCH_TIMEOUT_MS = 120_000;
+/** What the private directory's git may see of this process's environment: nothing that names a repository, an
+ * object store or config. The fixed settings below go on top. */
+const ENV_ALLOWLIST = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "SSH_AUTH_SOCK", "HTTPS_PROXY", "https_proxy", "NO_PROXY", "no_proxy"];
+const ENV = {
+    GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_NO_REPLACE_OBJECTS: "1", GIT_TERMINAL_PROMPT: "0",
+    GIT_ASKPASS: "", SSH_ASKPASS: "", GIT_SSH_COMMAND: "ssh -o BatchMode=yes",
+};
+/** The only credential helper https may use: the system keychain on macOS; elsewhere none, so a private https remote
+ * fails closed instead of asking. */
+export const CREDENTIAL_HELPER = process.platform === "darwin" ? "osxkeychain" : "";
+/** Settings for every command in the private directory. The directory's own config is ours and empty. File transport
+ * is off for the recorded remote; only the result fetch from the registered project path turns it on. */
+function hardened(helper, file = "never") {
+    return ["-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "protocol.ssh.allow=always",
+        "-c", `protocol.file.allow=${file}`, "-c", "protocol.ext.allow=never", "-c", "credential.helper=", ...(helper === "" ? [] : ["-c", `credential.helper=${helper}`]),
+        "-c", "gc.auto=0", "-c", "maintenance.auto=false", "-c", "fetch.recurseSubmodules=false", "-c", "core.fsmonitor=false"];
+}
+/**
+ * A URL Toolroll may fetch remote main from: https or ssh (either form). Local paths, file URLs and loopback hosts
+ * (this machine is where builds run) are always refused. Remote helpers (ext::, fd:: and the like), plain http and
+ * git:// (no authentication), relative paths, embedded passwords and anything odd are refused.
+ */
+export function parseRemoteUrl(url) {
+    const refused = { why: "its remote URL isn't one Toolroll fetches from" };
+    if (url === "" || url.length > 2048 || /[\x00-\x20\x7f]/.test(url) || url.startsWith("-") || url.includes("\\"))
+        return refused;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*::/.test(url) || /^file:/i.test(url) || /^[A-Za-z]:[\\/]/.test(url))
+        return refused;
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url)?.[1]?.toLowerCase();
+    if (scheme !== undefined) {
+        if (scheme !== "https" && scheme !== "ssh")
+            return refused;
+        try {
+            const parsed = new URL(url);
+            if (parsed.password !== "" || (scheme === "https" && parsed.username !== "") || parsed.search !== "" || parsed.hash !== "" || parsed.hostname === "" || loopback(parsed.hostname))
+                return refused;
+        }
+        catch {
+            return refused;
+        }
+        return { kind: "network", url };
+    }
+    // scp-like ssh: [user@]host:path, with no slash before the first colon.
+    const colon = url.indexOf(":");
+    const host = /^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9.-]+)$/.exec(url.slice(0, colon))?.[1];
+    if (colon > 0 && colon < url.length - 1 && host !== undefined && !loopback(host))
+        return { kind: "network", url };
+    return refused;
+}
+/** localhost (and its subdomains), any IPv4 spelling of 127.0.0.0/8 or 0.0.0.0 (inet_aton accepts 127.1, 0x7f.1 and
+ * the like), and ::1, :: or an IPv4-mapped loopback. */
+function loopback(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1").replace(/\.+$/, "");
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    const parts = host.split(".");
+    if (parts.length <= 4 && parts.every(part => /^(0x[0-9a-f]*|[0-9]+)$/.test(part))) {
+        const values = parts.map(part => part.startsWith("0x") ? parseInt(part.slice(2) || "0", 16) : /^0[0-7]+$/.test(part) ? parseInt(part, 8) : Number(part));
+        const first = values.length === 1 ? Math.floor(values[0] / 2 ** 24) : values[0];
+        return first === 127 || values.every(value => value === 0);
+    }
+    if (!host.includes(":"))
+        return false;
+    try {
+        const v6 = new URL(`http://[${host}]/`).hostname;
+        return v6 === "[::1]" || v6 === "[::]" || /^\[::ffff:(7f[0-9a-f]{2}:|0:)/.test(v6);
+    }
+    catch {
+        return true;
+    }
+}
+/** Why a recorded URL may not be used as the trusted remote; null when it may. */
+export function remoteUrlProblem(url) {
+    const parsed = parseRemoteUrl(url);
+    return "why" in parsed ? parsed.why : null;
+}
+/**
+ * One pass's reads of recorded remotes. Every `read` fetches again (the pre-teardown re-check is never older than
+ * the teardown); a project's private directory lasts until `close`, so a fetch after the first only brings what
+ * changed. Close removes every directory.
+ */
+export class RemoteMains {
+    store;
+    runner;
+    scratch;
+    helper;
+    dirs = new Map();
+    constructor(store, runner = run, scratch, helper = CREDENTIAL_HELPER) {
+        this.store = store;
+        this.runner = runner;
+        this.scratch = scratch;
+        this.helper = helper;
+    }
+    exec(dir, args, file = "never") {
+        return this.runner("git", ["--git-dir", dir, ...hardened(this.helper, file), ...args], { cwd: dir, envAllowlist: ENV_ALLOWLIST, env: ENV, timeoutMs: FETCH_TIMEOUT_MS, maxBuffer: 512 * 1024 * 1024 });
+    }
+    /** Nothing but fetched objects decides: a private directory that grew alternates, grafts or shallow state is
+     * not trusted. */
+    clean(dir) {
+        return !["shallow", join("info", "grafts"), join("objects", "info", "alternates"), join("objects", "info", "http-alternates")].some(name => existsSync(join(dir, name)));
+    }
+    async dirFor(repo) {
+        const known = this.dirs.get(repo);
+        if (known !== undefined && existsSync(known))
+            return known;
+        try {
+            mkdirSync(this.scratch, { recursive: true });
+            const dir = mkdtempSync(join(this.scratch, ".remote-main-"));
+            this.dirs.set(repo, dir);
+            const made = await this.runner("git", ["init", "--quiet", "--bare", "--template=", dir], { cwd: dir, envAllowlist: ENV_ALLOWLIST, env: ENV, timeoutMs: 30_000 });
+            return made.code === 0 ? dir : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async read(repo) {
+        const url = this.store.projectRemote(repo);
+        if (url === null)
+            return { ok: false, why: "the project has no recorded remote" };
+        const problem = remoteUrlProblem(url);
+        if (problem !== null)
+            return { ok: false, why: problem };
+        const dir = await this.dirFor(repo);
+        if (dir === null)
+            return { ok: false, why: "Toolroll couldn't read the project's remote main" };
+        const fetched = await this.exec(dir, ["fetch", "--quiet", "--no-tags", "--no-write-fetch-head", "--", url, `+refs/heads/main:${REMOTE_MAIN}`]);
+        if (fetched.code !== 0 || !this.clean(dir))
+            return { ok: false, why: "Toolroll couldn't read the project's remote main" };
+        const resolved = await this.exec(dir, ["rev-parse", "--verify", "--quiet", `${REMOTE_MAIN}^{commit}`]);
+        const main = resolved.stdout.trim();
+        if (resolved.code !== 0 || !SHA.test(main))
+            return { ok: false, why: "Toolroll couldn't read the project's remote main" };
+        const git = args => this.exec(dir, args);
+        const bring = async (from, head) => {
+            if (!SHA.test(head))
+                return false;
+            if ((await git(["cat-file", "-e", `${head}^{commit}`])).code === 0)
+                return true;
+            // The one local fetch: from the project path Toolroll registered (never a URL), for this exact hash-checked commit.
+            if (!isAbsolute(from))
+                return false;
+            const got = await this.exec(dir, ["fetch", "--quiet", "--no-tags", "--no-write-fetch-head", "--", from, `+${head}:refs/toolroll/results/${head}`], "always");
+            return got.code === 0 && this.clean(dir) && (await git(["cat-file", "-e", `${head}^{commit}`])).code === 0;
+        };
+        return { ok: true, remote: { url, main, git, bring } };
+    }
+    close() {
+        for (const dir of this.dirs.values()) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* the next pass makes its own */ }
+        }
+        this.dirs.clear();
+    }
+}

package/dist/result-completion.d.ts

@@ -6,6 +6,13 @@
 import type { Store } from "./store.js";
 /** The ledger action a person's (or lead's) completion of a result writes. */
 export declare const COMPLETION_ACTION = "assignment handoff checked";
+/** The actor of an automatic completion: the result's work already landed (landed-cleanup.ts). Its ledger detail is
+ * the plain-English reason ("its pull request merged"), the one place every surface reads it from. */
+export declare const LANDED_ACTOR = "system:landed";
+/** Who may complete a result, as a completion's ledger actor: a person, a lead, or Toolroll when the work landed. */
+export declare const COMPLETER_ACTOR: RegExp;
+/** Why Toolroll marked a result complete, from its completion's actor and detail; null for a person's completion. */
+export declare function landedReasonOf(actor: string | null | undefined, detail: string | null | undefined): string | null;
 /** Whether a task's family is marked complete. Completion is recorded on the
  * family's root against its current version's latest result, so the root, a
  * superseded revision and the current version all read Complete together. */

package/dist/result-completion.js

@@ -1,6 +1,15 @@
 import { readVerifiedArtifact } from "./evidence.js";
 /** The ledger action a person's (or lead's) completion of a result writes. */
 export const COMPLETION_ACTION = "assignment handoff checked";
+/** The actor of an automatic completion: the result's work already landed (landed-cleanup.ts). Its ledger detail is
+ * the plain-English reason ("its pull request merged"), the one place every surface reads it from. */
+export const LANDED_ACTOR = "system:landed";
+/** Who may complete a result, as a completion's ledger actor: a person, a lead, or Toolroll when the work landed. */
+export const COMPLETER_ACTOR = /^(?:(?:operator|coordinator|lead):.+|system:landed)$/;
+/** Why Toolroll marked a result complete, from its completion's actor and detail; null for a person's completion. */
+export function landedReasonOf(actor, detail) {
+    return actor === LANDED_ACTOR ? detail?.trim() || "its work is already in main" : null;
+}
 /** Whether a task's family is marked complete. Completion is recorded on the
  * family's root against its current version's latest result, so the root, a
  * superseded revision and the current version all read Complete together. */

package/dist/runner.d.ts

@@ -121,8 +121,10 @@ export declare function removeRunnerRepoAuthed(store: Store, args: {
 export declare const RUNNER_NAME_MAX = 60;
 /** The most tasks one worker may be set to run at once (the console's register form says the same). */
 export declare const RUNNER_CAPACITY_MAX = 64;
-/** A capacity as typed: a whole number from 1 to RUNNER_CAPACITY_MAX, or null. */
-export declare function parseRunnerCapacity(value: string): number | null;
+/** A capacity as typed; changing an existing worker may use zero to drain it. */
+export declare function parseRunnerCapacity(value: string, { allowZero }?: {
+    allowZero?: boolean | undefined;
+}): number | null;
 export declare function validRunnerName(name: string): boolean;
 /** A generated base name: lowercase [a-z0-9-], collapsed, trimmed. The
  * suffix budget (finding 24) is the CALLER's arithmetic — truncate the

package/dist/runner.js

@@ -165,10 +165,10 @@ export function removeRunnerRepoAuthed(store, args, now) {
 export const RUNNER_NAME_MAX = 60;
 /** The most tasks one worker may be set to run at once (the console's register form says the same). */
 export const RUNNER_CAPACITY_MAX = 64;
-/** A capacity as typed: a whole number from 1 to RUNNER_CAPACITY_MAX, or null. */
-export function parseRunnerCapacity(value) {
+/** A capacity as typed; changing an existing worker may use zero to drain it. */
+export function parseRunnerCapacity(value, { allowZero = false } = {}) {
     const capacity = Number(value.trim());
-    return value.trim() !== "" && Number.isInteger(capacity) && capacity >= 1 && capacity <= RUNNER_CAPACITY_MAX ? capacity : null;
+    return value.trim() !== "" && Number.isInteger(capacity) && capacity >= (allowZero ? 0 : 1) && capacity <= RUNNER_CAPACITY_MAX ? capacity : null;
 }
 export function validRunnerName(name) {
     if (name === "" || name.length > RUNNER_NAME_MAX)

package/dist/serve.js

@@ -14,7 +14,8 @@ import { startMaintenance } from './maintenance.js';
 import { connectionsOf, localConnectOf, oneClickOf } from "./mcp-connect.js";
 import { MOBILE_VIEWPORT_SCRIPT } from "./mobile-viewport.js";
 import { projectAuthority } from "./project-access.js";
-import { discoverTools, projectToolsOf, secretsSetFor, TOOL_CATALOG } from "./project-tools.js";
+import { discoverTools, projectToolsOf, secretsSetFor, TOOL_CATALOG, toolStanding } from "./project-tools.js";
+import { toolRefusal } from "./policy.js";
 import { isEdgeAddress, refuseEdge } from "./server/edge-refusal.js";
 import { announcePasswordBearer, isPasswordBearer, PASSWORD_BEARER_REFUSED, passwordBearerAccepted } from "./password-bearer.js";
 import { createSharedGuards } from "./server/guards.js";
@@ -390,7 +391,24 @@ export function createDecisionServer(options) {
         repo, name: projectName(repo), holdings: projectHoldings(store, repo), running: projectRunning(store, repo, clock()),
         canDelete: who.via === "cookie" && store.isInstanceOperator(who.name),
         builds: projectBuildsOf(repo, who),
+        access: projectAccessOf(repo),
     });
+    /** Settings → Project → Build access: the project's named tools and whether each loads for its builds. */
+    const projectAccessOf = (repo) => {
+        try {
+            const policy = store.orgPolicy();
+            return { tools: projectToolsOf(store, repo).map(tool => {
+                    const refused = toolRefusal(policy, tool.name);
+                    const set = secretsSetFor(repo, tool.spec, toolHome);
+                    // As a launch decides (toolLaunchFor): a tool the organisation doesn't allow, or missing a secret, is left out.
+                    return refused !== null ? { name: tool.name, loads: false, words: refused }
+                        : { name: tool.name, loads: tool.spec.secrets.every(one => one.optional || set.includes(one.name)), words: toolStanding(tool, set).words };
+                }) };
+        }
+        catch {
+            return { problem: "Couldn't read this project's tools right now." };
+        }
+    };
     /** Settings → Project → Builds at once: the saved number, its workers' capacity, and what builds now. */
     const projectBuildsOf = (repo, who) => {
         const capacities = store.listRunners().filter(one => one.retiredAt === null && one.repos.includes(repo)).map(one => one.capacity);

package/dist/server/live.d.ts

@@ -20,6 +20,9 @@ export type LiveRoom = {
 } | {
     kind: "team";
     conversation: string | null;
+} | {
+    kind: "agent";
+    run: number;
 };
 /** A room's name, read strictly: anything else is not a room. */
 export declare function parseLiveRoom(name: string): LiveRoom | null;

package/dist/server/live.js

@@ -1,3 +1,6 @@
+import { randomBytes } from "node:crypto";
+import { boardRunOf, holdAgentView, releaseAgentView } from "../agent-board.js";
+import { agentRunFingerprint } from "../agents-board.js";
 import { createLiveRooms, LiveConnection } from "../live-bus.js";
 import { reproveRemote } from "../operate-remote.js";
 import { rowVisible } from "../project.js";
@@ -8,7 +11,7 @@ import { adapterPolicy } from "./route-policy.js";
 import { requestContext } from "./request-context.js";
 /** A page asks for a few rooms at once: its workspace, what it shows, its conversation. */
 export const LIVE_ROOMS_PER_PAGE = 5;
-const ROOM_NAME = /^(workspace|task|flow|chat|team)(?::([^?]{1,400}))?(?:\?([^#]{0,600}))?$/;
+const ROOM_NAME = /^(workspace|task|flow|chat|team|agent)(?::([^?]{1,400}))?(?:\?([^#]{0,600}))?$/;
 /** At most one workspace nudge a second: a burst of writes is one re-read, the first heard at once. */
 const WORKSPACE_SETTLE_MS = 1_000;
 /** A running reply's preview: at most one snapshot every 80 ms; the last one always goes out. */
@@ -45,6 +48,8 @@ export function parseLiveRoom(name) {
             if (key !== null || !only("conversation"))
                 return null;
             return { kind, conversation: params.get("conversation") || null };
+        case "agent":
+            return key !== null && /^[1-9][0-9]{0,9}$/.test(key) && query === undefined ? { kind, run: Number(key) } : null;
     }
     return null;
 }
@@ -61,6 +66,8 @@ export function createLiveHandlers(runtime, live) {
         return cursor === null ? null : String(cursor);
     }, null, { bus: live.bus });
     const chatViewers = new Set();
+    // One agent's open view (Agents board): what it shows, keyed by the exact run.
+    const agentRooms = createLiveRooms(run => agentRunFingerprint(store, run), null, { bus: live.bus });
     /** The same session, still signed in, from the cookie and the account (never this request's context). */
     const readBrowser = (request, who) => {
         const again = identify(request, false);
@@ -177,7 +184,7 @@ export function createLiveHandlers(runtime, live) {
         if ([...url.searchParams.keys()].some(key => key !== "room") || names.length === 0 || names.length > LIVE_ROOMS_PER_PAGE || new Set(names).size !== names.length)
             return json(response, 400, { error: "room" });
         const rooms = names.map(name => ({ name, room: parseLiveRoom(name) }));
-        if (rooms.some(one => one.room === null) || rooms.filter(one => one.room?.kind === "workspace").length > 1 || rooms.filter(one => one.room?.kind === "chat").length > 1 || rooms.filter(one => one.room?.kind === "team").length > 1)
+        if (rooms.some(one => one.room === null) || rooms.filter(one => one.room?.kind === "agent").length > 1 || rooms.filter(one => one.room?.kind === "workspace").length > 1 || rooms.filter(one => one.room?.kind === "chat").length > 1 || rooms.filter(one => one.room?.kind === "team").length > 1)
             return json(response, 400, { error: "room" });
         // Admit every room before the stream opens, with the answers each page's own stream gave.
         const joins = [];
@@ -198,6 +205,31 @@ export function createLiveHandlers(runtime, live) {
                     // A sign-out or a narrowed account stops it.
                     valid: () => signedIn() && rowVisible(liveCeiling(), repo) && store.accountCanAccess(who.name, repo) }));
             }
+            else if (room.kind === "agent") {
+                const browser = who;
+                const run = store.getRun(room.run);
+                const repo = run === null ? null : store.refForId(run.taskRef)?.repo ?? null;
+                if (run === null || repo === null || !visible(repo) || !store.accountCanAccess(who.name, repo))
+                    return json(response, 404, { error: "run" });
+                // A repair is its build's own activity: its room is the build's.
+                const signedIn = sameBrowser(request, browser), runId = boardRunOf(store, run.id), view = randomBytes(12).toString("hex");
+                // The watch is a short lease in the database, renewed on every keep-alive and released when the page goes:
+                // the process that sends chat pings reads it there (agent-board.ts watchingAgent).
+                const watch = () => { try {
+                    holdAgentView(store, view, who.name, runId, clock());
+                }
+                catch { /* a missed renewal only lets a ping through */ } };
+                joins.push(connection => {
+                    watch();
+                    connection.onKeepAlive(watch);
+                    connection.onClose(() => { try {
+                        releaseAgentView(store, view, clock());
+                    }
+                    catch { /* it lapses on its own */ } });
+                    agentRooms.join(runId, { name: who.name, room: name, connection,
+                        valid: () => signedIn() && rowVisible(liveCeiling(), repo) && store.accountCanAccess(who.name, repo) });
+                });
+            }
             else if (room.kind === "flow") {
                 const browser = who;
                 const flow = store.getFlow(room.flow);
@@ -302,6 +334,7 @@ export function createLiveHandlers(runtime, live) {
             detachChat();
             workspaceRooms.close();
             teamRooms.close();
+            agentRooms.close();
             for (const viewer of [...chatViewers])
                 viewer.connection.close();
         },