toolroll 0.9.72 → 0.9.74

package/dist/release-cli.js

@@ -16,13 +16,16 @@ import { RELEASE_LIMITS, runRelease } from "./release.js";
 import { processes, releaseAdapters } from "./release-adapters.js";
 import { releaseGate } from "./release-gate.js";
 import { databasePath, openStore, revokeRelease } from "./store.js";
-import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit } from "./release-carry.js";
+import { carryRefusalWords, proveCarry, setAskEveryReleaseCommit, setUnsandboxedCarry } from "./release-carry.js";
 import { authenticateApprover, machineActing, personProof } from "./scope.js";
 import { createNightlyCheckFlow } from "./nightly-check.js";
 import { parseSchedule } from "./flow-schedule.js";
 export const RELEASE_HELP = `toolroll release <branch> — release Toolroll itself, from a pushed branch with an open pull request
 
-  Requires an active approver's scope approval (the only human step) and a passing Full check on the exact commit.
+  First looks at the pull request's checks: a required check that failed stops before anything is filed or sent for
+  approval, and checks not started or still running are named and waited for (stopping if they don't finish within
+  the gate's limit). Then requires an active approver's scope approval (the only human step) and a passing Full check
+  on the exact commit.
   Completes that result, drains, backs up, deploys and relinks both CLI names to that commit. After PR checks pass,
   squash-merges, deletes the matching remote branch, verifies the merged tree and tags. Both macOS legs gate npm
   publication; Homebrew waits for its checks to register and all pass before merging.
@@ -49,6 +52,11 @@ toolroll release nightly --repo <path> --as <you> --token <password> [--schedule
 toolroll release ask-every-commit on|off --repo <path> [--as <you> --token <password>] — this project's releases ask
   for every later commit (on), or carry test-only commits again (off: your password, never the lead's token)
 
+toolroll release unsandboxed-carry on|off --repo <path> [--as <you> --token <password>] — carry release approvals
+  when this project's checks aren't sandboxed (on: your password, never the lead's token). With it on, later
+  test-only commits of a release run outside the sandbox without being shown to you first. Off by default; it counts
+  only for releases approved while it is on.
+
 Options
   --no-carry             every later commit of this release asks for approval again
   --to <commit>          with carry: the later commit
@@ -126,7 +134,7 @@ export async function runReleaseCommand(args, write, deps = {}) {
         return refuse("usage", "--yes goes with --release-gate <id>; a release needs no confirmation beyond the owner's approval.", 2);
     if (positional[0] === "nightly" && positional.length === 1)
         return runNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, schedule: scheduleFlag, start: args.includes("--start") }, write, json, deps);
-    if (["carry", "revoke", "ask-every-commit"].includes(positional[0] ?? "") && positional.length === 2) {
+    if (["carry", "revoke", "ask-every-commit", "unsandboxed-carry"].includes(positional[0] ?? "") && positional.length === 2) {
         return runAuthorityCommand(positional[0], positional[1], { to, request, as, token, repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo) }, write, json, deps);
     }
     if (positional.length !== 1)
@@ -255,6 +263,31 @@ async function runAuthorityCommand(command, target, flags, write, json, deps) {
             const words = target === "on" ? "Every later release commit in this project asks for approval." : "Later test-only release commits ship under the release approval.";
             return answer(true, { repo: flags.repo, ask: target === "on" }, words, 0);
         }
+        if (command === "unsandboxed-carry") {
+            if (target !== "on" && target !== "off")
+                return answer(false, { reason: "usage", message: "unsandboxed-carry takes on or off." }, "unsandboxed-carry takes on or off.", 2);
+            if (flags.repo === undefined)
+                return answer(false, { reason: "usage", message: "Name the project with --repo <path>." }, "Name the project with --repo <path>.", 2);
+            // Turning it on relaxes a release's rules: a person's own ceremony, as an approval needs, never a lead or remote
+            // token. Turning it off is only stricter.
+            let actor = "cli";
+            if (target === "on") {
+                const refused = (message) => answer(false, { reason: "person-only", message }, message, 1);
+                if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined || process.env["TOOLROLL_REMOTE_TOKEN"] !== undefined)
+                    return refused("Only a person turns this on, never the lead or a remote token.");
+                if (flags.as === undefined || flags.token === undefined)
+                    return refused("Turning this on needs your password: add --as <you> --token <password>.");
+                const proved = authenticateApprover(store, flags.as, flags.token, flags.repo);
+                if (!proved.ok || !personProof(proved.method))
+                    return refused("Only an approver of this project, proved as a person, turns this on.");
+                actor = flags.as;
+            }
+            setUnsandboxedCarry(store, flags.repo, target === "on", actor, now);
+            const words = target === "on"
+                ? "Release approvals approved from now on carry when this project's checks aren't sandboxed: later test-only commits will run outside the sandbox without being shown to you first."
+                : "Release approvals carry only when this project's checks are sandboxed.";
+            return answer(true, { repo: flags.repo, unsandboxedCarry: target === "on" }, words, 0);
+        }
         const id = Number(target);
         if (!Number.isSafeInteger(id) || id < 1)
             return answer(false, { reason: "usage", message: `${target} isn't a release id.` }, `${target} isn't a release id.`, 2);

package/dist/release-git.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The release's repository as Toolroll records it (docs/plans/chat-management.md §0a.2), never as the gate checkout
+ * says: the checkout is one of the plane's recorded projects (by real path), its Git directory is that project's own
+ * plain `.git` folder, and its GitHub `owner/name` and the URL fetched from come from the recorded remote
+ * (`project.remote_url`), not the checkout's `origin`. The checkout is where the release check ran the build's own code,
+ * so its `.git/config` is treated as build-written.
+ */
+export type ReleaseRepo = {
+    checkout: string;
+    gitDir: string;
+    remote: string;
+    slug: string;
+    ssh: boolean;
+};
+/** The programs the coordinator runs, by absolute path, found once when it starts. */
+export type ReleaseTools = {
+    git: string;
+    gh: string;
+    ssh: string;
+};
+/** owner/name and transport of a recorded GitHub remote, read strictly (https or ssh to github.com, nothing else). */
+export declare function releaseRemote(url: string): {
+    slug: string;
+    ssh: boolean;
+} | null;
+/** Fixed system folders: the only PATH the coordinator's Git and gh run with. */
+export declare const RELEASE_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
+/** Git, gh and ssh by absolute path: the system's Git (or the first in the fixed system folders), the installed gh as
+ * this process's PATH finds it now, and the system ssh. Resolved once; never looked up again. */
+export declare function releaseTools(path?: string): ReleaseTools;
+/** The coordinator's Git and gh environment: an allowlist, a fixed PATH, no system or global Git config, no prompts. */
+export declare function releaseGitEnv(base?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv;
+/** Every coordinator Git command's fixed settings, ahead of its own arguments: the recorded Git directory and checkout,
+ * no hooks, fsmonitor, replacement objects, pager or submodule recursion, only https (and ssh for an ssh remote), the
+ * system ssh, and gh as the only credential helper. */
+export declare function releaseGitArgs(repo: ReleaseRepo, tools: ReleaseTools): string[];
+/** The named remote the coordinator fetches, looks and pushes through: defined only on its own command line (`-c`), so
+ * no checkout setting names or rewrites it. */
+export declare const RELEASE_REMOTE = "toolroll-release";
+/** The first local or worktree setting a gate checkout's config holds that a release won't run with, or null: one
+ * outside the allowlist (an include, a command, a proxy, TLS or header setting, a credential helper, a URL rewrite, a
+ * hooks folder), a remote named like a URL or after the coordinator's own, or a remote over a transport helper. */
+export declare function releaseConfigProblem(listing: string): string | null;

package/dist/release-git.js

@@ -0,0 +1,106 @@
+/**
+ * The release coordinator's Git, as one hardened runner's pieces (docs/plans/chat-management.md §0a.2): the recorded
+ * repository's shape, the programs by absolute path, the allowlisted environment, the fixed settings and the checkout
+ * config allowlist. Kept apart from release-adapters.ts so the release card (release-card.ts) reads Git the same way
+ * without loading the coordinator.
+ */
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { HARDENED_GIT_ARGS } from "./agent-fence.js";
+import { TEARDOWN_FLAGS } from "./teardown-git.js";
+/** owner/name and transport of a recorded GitHub remote, read strictly (https or ssh to github.com, nothing else). */
+export function releaseRemote(url) {
+    const part = "([A-Za-z0-9_.-]+)";
+    const https = new RegExp(`^https://github\\.com/${part}/${part}?(?:\\.git)?/?$`).exec(url);
+    const ssh = new RegExp(`^(?:ssh://)?git@github\\.com[:/]${part}/${part}?(?:\\.git)?/?$`).exec(url);
+    const match = https ?? ssh;
+    if (match === null || match[2] === undefined || match[1].startsWith(".") || match[2].startsWith("."))
+        return null;
+    return { slug: `${match[1]}/${match[2].replace(/\.git$/, "")}`, ssh: https === null };
+}
+const executable = (path) => { try {
+    accessSync(path, fsConstants.X_OK);
+    return statSync(path).isFile();
+}
+catch {
+    return false;
+} };
+/** Fixed system folders: the only PATH the coordinator's Git and gh run with. */
+export const RELEASE_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
+/** Git, gh and ssh by absolute path: the system's Git (or the first in the fixed system folders), the installed gh as
+ * this process's PATH finds it now, and the system ssh. Resolved once; never looked up again. */
+export function releaseTools(path = process.env["PATH"] ?? "") {
+    const find = (name, dirs) => {
+        for (const dir of dirs) {
+            if (!isAbsolute(dir))
+                continue;
+            const candidate = join(dir, name);
+            if (executable(candidate))
+                return candidate;
+        }
+        return null;
+    };
+    const system = ["/usr/bin", "/bin", "/usr/local/bin", "/opt/homebrew/bin"];
+    return {
+        git: find("git", system) ?? "/usr/bin/git",
+        gh: find("gh", [...path.split(delimiter), ...system]) ?? "/usr/bin/gh",
+        ssh: find("ssh", ["/usr/bin", "/bin"]) ?? "/usr/bin/ssh",
+    };
+}
+/** The coordinator's Git and gh environment: an allowlist, a fixed PATH, no system or global Git config, no prompts. */
+export function releaseGitEnv(base = process.env) {
+    const kept = ["HOME", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "USER", "LOGNAME", "SSH_AUTH_SOCK", "GH_CONFIG_DIR", "XDG_CONFIG_HOME", "GH_TOKEN", "GITHUB_TOKEN", "GH_HOST"];
+    return {
+        ...Object.fromEntries(kept.flatMap(name => base[name] === undefined ? [] : [[name, base[name]]])),
+        PATH: RELEASE_PATH, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1", GIT_ASKPASS: "", SSH_ASKPASS: "",
+    };
+}
+/** Every coordinator Git command's fixed settings, ahead of its own arguments: the recorded Git directory and checkout,
+ * no hooks, fsmonitor, replacement objects, pager or submodule recursion, only https (and ssh for an ssh remote), the
+ * system ssh, and gh as the only credential helper. */
+export function releaseGitArgs(repo, tools) {
+    return [`--git-dir=${repo.gitDir}`, `--work-tree=${repo.checkout}`, "--no-replace-objects", "--no-pager", ...HARDENED_GIT_ARGS, ...TEARDOWN_FLAGS,
+        "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", ...(repo.ssh ? ["-c", "protocol.ssh.allow=always"] : []),
+        "-c", `core.sshCommand=${tools.ssh}`, "-c", "core.askPass=", "-c", "fetch.recurseSubmodules=false", "-c", "core.pager=cat",
+        // Where it connects and what it sends: verified TLS, no proxy, no extra header or cookie file. (An empty CA file
+        // or path can't be given here, Git then trusts nothing; a checkout setting either stops the release instead.)
+        "-c", "http.sslVerify=true", "-c", "http.proxy=", "-c", "http.extraHeader=", "-c", "http.cookieFile=",
+        // The recorded URL, as a remote that exists only here.
+        "-c", `remote.${RELEASE_REMOTE}.url=${repo.remote}`, "-c", `remote.${RELEASE_REMOTE}.pushurl=${repo.remote}`, "-c", `remote.${RELEASE_REMOTE}.proxy=`,
+        ...(repo.ssh ? [] : ["-c", `credential.helper=!'${tools.gh.replace(/'/g, "'\\''")}' auth git-credential`])];
+}
+/** The named remote the coordinator fetches, looks and pushes through: defined only on its own command line (`-c`), so
+ * no checkout setting names or rewrites it. */
+export const RELEASE_REMOTE = "toolroll-release";
+/** The local and worktree settings a gate checkout may hold for a release (an allowlist): plain values Git writes
+ * itself and that never decide where it connects, what it sends or what it runs. Anything else stops the release. */
+const RELEASE_KEYS = [
+    /^core\.(repositoryformatversion|filemode|bare|logallrefupdates|ignorecase|precomposeunicode|symlinks|autocrlf|eol|safecrlf|quotepath|longpaths|checkstat|trustctime)$/,
+    /^extensions\.(worktreeconfig|objectformat|refstorage)$/,
+    /^remote\.[^/:\\]+\.(url|fetch|pushurl|tagopt|prune)$/,
+    /^branch\..+\.(remote|merge|rebase|pushremote|description|vscode-merge-base)$/,
+    /^(user\.(name|email)|pull\.(rebase|ff)|init\.defaultbranch|lfs\.repositoryformatversion)$/,
+];
+/** The first local or worktree setting a gate checkout's config holds that a release won't run with, or null: one
+ * outside the allowlist (an include, a command, a proxy, TLS or header setting, a credential helper, a URL rewrite, a
+ * hooks folder), a remote named like a URL or after the coordinator's own, or a remote over a transport helper. */
+export function releaseConfigProblem(listing) {
+    const fields = listing.split("\0");
+    for (let at = 0; at + 1 < fields.length; at += 2) {
+        if (fields[at] !== "local" && fields[at] !== "worktree")
+            continue;
+        const entry = fields[at + 1];
+        const newline = entry.indexOf("\n");
+        const key = (newline < 0 ? entry : entry.slice(0, newline)).toLowerCase();
+        const value = (newline < 0 ? "" : entry.slice(newline + 1)).trim();
+        if (key.includes(RELEASE_REMOTE))
+            return key;
+        if (key === "core.fsmonitor" && /^(false|no|off|0)$/i.test(value))
+            continue;
+        if (!RELEASE_KEYS.some(pattern => pattern.test(key)))
+            return key;
+        if (/^remote\./.test(key) && /^[A-Za-z][A-Za-z0-9+.-]*::/.test(value))
+            return key;
+    }
+    return null;
+}

package/dist/release.d.ts

@@ -5,7 +5,11 @@
  *
  *   gate → approval → check → complete → quiet → deploy → link → ci → merge → tree → tag → publish → homebrew → done
  *
- * gate files a prepared-candidate task pinned to the branch's exact commit, with the full release check. approval
+ * gate, before filing a task for that commit, looks at the pull request's required checks on it: one that failed stops
+ * the release before anything is filed or sent for approval; it waits, naming them, for checks not started or still
+ * running, and stops if they don't finish within its limit (a task already filed is not looked at again; ci checks
+ * once more before merging). It then files a prepared-candidate task pinned to the branch's exact commit, with the full
+ * release check. approval
  * waits for an active approver's yes to that exact scope (never a mode's, an AI's or the lead's). check requires a Full
  * result of that commit: a failed check stops the release and stays visible, nothing reruns it. complete marks that
  * exact result Complete through the task's own authorization. quiet waits until nothing builds. deploy runs the
@@ -35,7 +39,7 @@ export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "
 export declare const RELEASE_TAG_CHECKS: readonly ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
 export declare const RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 export type ReleaseStep = typeof RELEASE_STEPS[number];
-type WaitingStep = "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
+type WaitingStep = "gate" | "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
 /** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
 export declare const RELEASE_LIMITS: Readonly<Record<WaitingStep, number>>;
 /** One check attempt; `app` is the GitHub App that made it (github-actions for a workflow), when known. */
@@ -86,6 +90,9 @@ export type GateState = {
     } | null;
     /** A finished build that left no result to complete (it failed before the check), in words. */
     failed: string | null;
+    /** A newer attempt is queued or running (`task regate` after a failed check): the result shown is the one before it.
+     * Absent from a plane too old to say. */
+    pending?: boolean;
     completion: {
         actor: string;
         at: string;
@@ -467,4 +474,6 @@ export declare function checksVerdict(runs: readonly CheckRun[], required: reado
 };
 /** Run the release from wherever its journal stopped. */
 export declare function runRelease(options: ReleaseOptions, adapters: ReleaseAdapters): Promise<ReleaseOutcome>;
+/** A probe's failure that is only the network to GitHub being slow, never a decision (a Stop) or another error. */
+export declare function transientNetworkError(error: unknown): boolean;
 export {};

package/dist/release.js

@@ -5,7 +5,11 @@
  *
  *   gate → approval → check → complete → quiet → deploy → link → ci → merge → tree → tag → publish → homebrew → done
  *
- * gate files a prepared-candidate task pinned to the branch's exact commit, with the full release check. approval
+ * gate, before filing a task for that commit, looks at the pull request's required checks on it: one that failed stops
+ * the release before anything is filed or sent for approval; it waits, naming them, for checks not started or still
+ * running, and stops if they don't finish within its limit (a task already filed is not looked at again; ci checks
+ * once more before merging). It then files a prepared-candidate task pinned to the branch's exact commit, with the full
+ * release check. approval
  * waits for an active approver's yes to that exact scope (never a mode's, an AI's or the lead's). check requires a Full
  * result of that commit: a failed check stops the release and stays visible, nothing reruns it. complete marks that
  * exact result Complete through the task's own authorization. quiet waits until nothing builds. deploy runs the
@@ -45,7 +49,7 @@ export const REQUIRED_PR_CHECKS = [
 export const RELEASE_TAG_CHECKS = ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
 export const RELEASE_STEPS = ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 /** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
-export const RELEASE_LIMITS = { approval: 24 * 60, check: 120, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
+export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 120, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
 const POLL_MS = 15_000;
 /** A stop the release reports: the step it stopped at and why, in words. */
 class Stop extends Error {
@@ -177,16 +181,29 @@ export async function runRelease(options, adapters) {
         delete j.intents.deploy;
         save();
     };
-    /** Ask `probe` until it answers, within this step's limit. */
+    /** Ask `probe` until it answers, within this step's limit. A short network failure on the way to GitHub (git or gh
+     * timing out) is no answer yet, never the release's end: the next poll asks again, until the step's own limit. */
     const waitFor = async (at, what, probe) => {
         const deadline = adapters.now().getTime() + limits[at] * 60_000;
-        let said = false;
+        let said = false, unreachable = null;
         for (;;) {
-            const answer = await probe();
+            let answer;
+            try {
+                answer = await probe();
+                unreachable = null;
+            }
+            catch (error) {
+                if (!transientNetworkError(error))
+                    throw error;
+                if (unreachable === null)
+                    say(`  GitHub didn't answer in time (${networkWords(error)}); asking again`);
+                unreachable = networkWords(error);
+                answer = null;
+            }
             if (answer !== null)
                 return answer;
             if (adapters.now().getTime() >= deadline)
-                throw new Stop("timeout", `Still waiting for ${what} after ${limits[at]} minutes.`);
+                throw new Stop("timeout", `Still waiting for ${what} after ${limits[at]} minutes${unreachable === null ? "" : ` (GitHub last didn't answer: ${unreachable})`}.`);
             if (!said) {
                 say(`  waiting for ${what} (up to ${limits[at]} min)`);
                 said = true;
@@ -464,11 +481,13 @@ export async function runRelease(options, adapters) {
                         if (existing.exists && j.freshTask === true && j.intents.gate === undefined)
                             throw new Stop("approval", `Task ${j.task.id} appeared before this release filed it; rerun with --new.`);
                         if (existing.exists) {
+                            // Filed already (a resume after a lost answer): the task stands, and the ci step judges its checks.
                             if (existing.candidate !== j.candidate.sha)
                                 throw new Stop("conflict", `Task ${j.task.id} exists for a different commit (${existing.candidate?.slice(0, 7) ?? "none"}).`);
                             j.task.scopeDigest = existing.scopeDigest;
                         }
                         else {
+                            await earlyChecks(adapters, j, (what, probe) => waitFor("gate", what, probe));
                             intend("gate");
                             await adapters.repo.sync(j.branch);
                             const filed = await adapters.toolroll.fileGate({
@@ -516,6 +535,9 @@ export async function runRelease(options, adapters) {
                             await watch("dispatch");
                             const gate = await adapters.toolroll.gate(j.task.id);
                             await approved(gate);
+                            // A rerun of the same approved commit is on its way: the failure before it is not this release's answer.
+                            if (gate.pending === true && gate.result?.check !== "passed")
+                                return null;
                             if (gate.failed !== null)
                                 throw new Stop("check-failed", `The release build of ${j.task.id} failed: ${gate.failed}. Fix it and release the new commit with --new.`);
                             if (gate.result === null || gate.result.check === "running" || gate.result.check === "pending")
@@ -886,3 +908,57 @@ async function deployed(adapters, candidate) {
     const [runtime] = runtimes;
     return runtime !== undefined && runtime !== "" && await adapters.toolroll.runtimeCommit(runtime) === candidate ? runtime : null;
 }
+/**
+ * The gate's look at the pull request's required checks on the exact commit, before anything is filed or anyone is
+ * asked to approve (#237): a required check that failed or was cancelled stops here; checks not started or still
+ * running are named, and the gate waits for them; ones that never finish within the gate's limit stop here too. GitHub
+ * not answering is waited out the same way, never taken for a pass. The ci step still checks again before merging.
+ */
+async function earlyChecks(adapters, j, wait) {
+    const sha = j.candidate.sha.slice(0, 7);
+    const required = REQUIRED_PR_CHECKS;
+    let named = "", unread = false;
+    try {
+        await wait(`the pull request checks on ${sha}`, async () => {
+            let runs;
+            try {
+                runs = await adapters.github.checks(j.github, j.candidate.sha);
+            }
+            catch (error) {
+                if (!unread)
+                    adapters.say(`  Couldn't read the pull request checks on ${sha} (${error?.message ?? error}); trying again.`);
+                unread = true;
+                return null;
+            }
+            const verdict = checksVerdict(runs.filter(run => required.includes(run.name)), required);
+            if (verdict.state === "failed") {
+                throw new Stop("ci-failed", `Pull request checks already failed on ${sha}: ${verdict.failed.join(", ")}. Nothing was filed or sent for approval. Fix the branch, then release the new commit with \`toolroll release ${j.branch} --repo ${j.checkout} --new\` (or rerun the failed job on GitHub and run this command again).`);
+            }
+            if (verdict.state === "passed")
+                return true;
+            const now = verdict.waiting.join(", ");
+            if (now !== named) {
+                adapters.say(`  Pull request checks on ${sha} not finished yet: ${now}.`);
+                named = now;
+            }
+            return null;
+        });
+    }
+    catch (error) {
+        if (!(error instanceof Stop) || error.reason !== "timeout")
+            throw error;
+        throw new Stop("ci-missing", `Pull request checks on ${sha} didn't all finish in time${named === "" ? (unread ? " (GitHub didn't answer)" : "") : `: ${named}`}. Nothing was filed or sent for approval. Start or rerun them on GitHub, then run this command again.`);
+    }
+}
+/** The network failures a release's waits ride out: git or gh timing out (or cut off) on the way to GitHub. */
+const TRANSIENT_NETWORK = /Recv failure: (?:Operation timed out|Connection reset by peer)|TLS handshake timeout|Operation timed out|Connection timed out|i\/o timeout|Connection reset by peer|Failed to connect to [^\s]*github\.com port \d+/i;
+/** A probe's failure that is only the network to GitHub being slow, never a decision (a Stop) or another error. */
+export function transientNetworkError(error) {
+    if (error instanceof Stop || error instanceof Restart)
+        return false;
+    return TRANSIENT_NETWORK.test(String(error?.message ?? error));
+}
+/** The part of a network failure worth saying: its matching phrase. */
+function networkWords(error) {
+    return TRANSIENT_NETWORK.exec(String(error?.message ?? error))?.[0] ?? "a network failure";
+}

package/dist/repository-context-ui.js

@@ -1,5 +1,6 @@
 import { html, postForm } from "./html.js";
+import { framedSection } from './knowledge-ui.js';
 export function repositoryContextHtml(repo, query, result, csrf) {
     const root = `/settings/knowledge?repo=${encodeURIComponent(repo)}`;
-    return html `<section class="knowledge repository-context"><h2>Relevant code</h2><form method="get" action="/settings/knowledge"><input type="hidden" name="repo" value="${repo}"><label>Find code<input name="q" value="${query}" maxlength="1000" placeholder="A feature, file or symbol"></label><button type="submit">Search</button></form>${result === null ? '' : html `<p class="meta">${result.index.engine === 'typescript-ast' ? 'Code relationships' : 'Source search'}${result.mode === 'impact' ? ' · possible change impact' : ''}</p>${result.excerpts.length ? result.excerpts.map(one => html `<details><summary>${one.file}:${one.line}${one.symbol ? ` · ${one.symbol}` : ''}</summary><p class="meta">${one.reason}</p><pre>${one.text}</pre><a href="${root}&mode=impact&q=${encodeURIComponent(one.file)}">What this may affect</a></details>`) : html `<p>No matching source was found in this bounded search.</p>`}${result.relationships.length ? html `<details><summary>Related files</summary><ul>${result.relationships.map(one => html `<li>${one.from} → ${one.to} · ${one.kind}</li>`)}</ul></details>` : ''}<details><summary>Context details</summary><p>${result.index.status}${result.checkout ? ` · checkout ${result.checkout.head.slice(0, 8)}` : ''}</p>${result.warnings.map(one => html `<p>${one}</p>`)}</details>`}${csrf ? html `<details><summary>Refresh code index</summary>${postForm("/settings/knowledge/refresh", html `<p>Builds a local map of TypeScript and JavaScript imports. Uses no model.</p><button type="submit">Refresh index</button>`, { hidden: { repo } })}</details>` : ''}</section>`;
+    return framedSection('Relevant code', html `<form class="field-row" method="get" action="/settings/knowledge"><input type="hidden" name="repo" value="${repo}"><label>Find code<input name="q" value="${query}" maxlength="1000" placeholder="A feature, file or symbol"></label><button type="submit">Search</button></form>${result === null ? '' : html `<p class="meta">${result.index.engine === 'typescript-ast' ? 'Code relationships' : 'Source search'}${result.mode === 'impact' ? ' · possible change impact' : ''}</p>${result.excerpts.length ? result.excerpts.map(one => html `<details><summary>${one.file}:${one.line}${one.symbol ? ` · ${one.symbol}` : ''}</summary><p class="meta">${one.reason}</p><pre>${one.text}</pre><a href="${root}&mode=impact&q=${encodeURIComponent(one.file)}">What this may affect</a></details>`) : html `<p>No matching source was found in this bounded search.</p>`}${result.relationships.length ? html `<details><summary>Related files</summary><ul>${result.relationships.map(one => html `<li>${one.from} → ${one.to} · ${one.kind}</li>`)}</ul></details>` : ''}<details><summary>Context details</summary><p>${result.index.status}${result.checkout ? ` · checkout ${result.checkout.head.slice(0, 8)}` : ''}</p>${result.warnings.map(one => html `<p>${one}</p>`)}</details>`}${csrf ? html `<details><summary>Refresh code index</summary>${postForm("/settings/knowledge/refresh", html `<p>Builds a local map of TypeScript and JavaScript imports. Uses no model.</p><button type="submit">Refresh index</button>`, { hidden: { repo } })}</details>` : ''}`, 'repository-context');
 }

package/dist/run-efficiency.d.ts

@@ -8,7 +8,7 @@
  * kept 24 hours) are read once, bounded, through the descriptor-safe live reader, for step counts and observed step
  * times. No command text is ever stored here: repeats are counted, never quoted.
  */
-import type { Run, Store } from "./store.js";
+import { type Run, type Store } from "./store.js";
 import type { LiveActivityKind, LiveRecord } from "./live-records.js";
 export declare const RUN_EFFICIENCY_VERSION = 3;
 /** Budgets for one derivation: never more than the live file's own cap, and a bounded record count. */
@@ -62,10 +62,10 @@ export declare function usageOf(run: Pick<Run, "provider" | "model" | "tokensIn"
  * others their times are partly made up (Codex reports a step when it completes, ACP agents may report late), so no
  * duration is claimed for them. */
 export declare function stepsOf(records: Iterable<LiveRecord>, truncated: string | null, measured?: boolean): RunEfficiency["steps"];
-/** Derive a finished run's How it ran from its records. */
+/** Derive a finished run's How it ran from its records, read under the run's own captured "Show commands" answer. */
 export declare function deriveRunEfficiency(run: Run & {
     usageJson?: string | null;
-}, evidenceRoot: string, now: Date): RunEfficiency;
+}, evidenceRoot: string, now: Date, commands?: boolean): RunEfficiency;
 /**
  * A finished run's How it ran: the saved one when it was derived by this version, else derived now and saved (once:
  * a row whose steps were complete or have expired is final). An unfinished run is derived but never saved.

package/dist/run-efficiency.js

@@ -1,3 +1,14 @@
+/**
+ * How a run went (docs/plans/run-efficiency.md): derived from the run's own records, display only. It never changes a
+ * completion, an approval, a charge or a check verdict, and it claims nothing its sources don't hold — an unreported
+ * number is unknown (null, shown as a dash), never zero.
+ *
+ * Sources, and what each can say: the run row (wall times, tokens, the provider's raw usage with its cache counts, the
+ * agent's turns where reported) is kept with the run; the live records (`<evidence>/live/<run>.jsonl`, display-only,
+ * kept 24 hours) are read once, bounded, through the descriptor-safe live reader, for step counts and observed step
+ * times. No command text is ever stored here: repeats are counted, never quoted.
+ */
+import { runLiveCommands } from "./store.js";
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
 import { LIVE_RETAIN_MS, legacyLiveLogPath, liveLogPath, liveWindowRecords } from "./live.js";
@@ -95,7 +106,7 @@ const noSteps = (state, reason) => ({ state, reason, total: null, failed: null,
  * directory), measured once, and never more than the budget read whatever the file does meanwhile; then parsed line by
  * line. A file over the budget, in the older text format, with lines that don't read, or cut or capped while the agent
  * ran, says its steps are incomplete. Null when there is no step file at all. */
-function readRecords(evidenceRoot, runId) {
+function readRecords(evidenceRoot, runId, commands) {
     try {
         const dir = lstatSync(join(evidenceRoot, "live"));
         if (!dir.isDirectory() || dir.isSymbolicLink())
@@ -154,10 +165,10 @@ function readRecords(evidenceRoot, runId) {
         whole.length = EFFICIENCY_RECORDS;
     const keys = { inKey: false };
     // One record per line: a whole line that doesn't read is a record lost.
-    const read = liveWindowRecords({ text: whole.length === 0 ? "" : `${whole.join("\n")}\n`, format: "records" }, keys);
+    const read = liveWindowRecords({ text: whole.length === 0 ? "" : `${whole.join("\n")}\n`, format: "records" }, commands, keys);
     const lost = whole.length - read.length;
     // A finished run's last line without its newline is read like any other; one that doesn't read is a record lost.
-    const tail = unfinished.trim() === "" ? [] : liveWindowRecords({ text: `${unfinished}\n`, format: "records" }, keys);
+    const tail = unfinished.trim() === "" ? [] : liveWindowRecords({ text: `${unfinished}\n`, format: "records" }, commands, keys);
     const records = [...read, ...tail];
     const lostAll = lost + (unfinished.trim() !== "" && tail.length === 0 ? 1 : 0);
     if (records.length === 0 && text.trim() !== "")
@@ -170,10 +181,10 @@ function readRecords(evidenceRoot, runId) {
                         : null;
     return { records, truncated };
 }
-/** Derive a finished run's How it ran from its records. */
-export function deriveRunEfficiency(run, evidenceRoot, now) {
+/** Derive a finished run's How it ran from its records, read under the run's own captured "Show commands" answer. */
+export function deriveRunEfficiency(run, evidenceRoot, now, commands = false) {
     const finished = run.finishedAt;
-    const read = readRecords(evidenceRoot, run.id);
+    const read = readRecords(evidenceRoot, run.id, commands);
     const steps = read !== null && "unreadable" in read ? noSteps("truncated", read.unreadable)
         : read !== null ? stepsOf(read.records, read.truncated, run.provider === "claude")
             : finished !== null && now.getTime() - Date.parse(finished) > LIVE_RETAIN_MS ? noSteps("expired", "Step details are kept for a day after a run; this one's have expired.")
@@ -196,8 +207,9 @@ export function runEfficiencyOf(store, evidenceRoot, runId, now) {
         return null;
     const usageJson = store.handle.prepare("SELECT usage_json FROM run WHERE id = ?").get(runId)?.["usage_json"];
     const full = { ...run, usageJson: typeof usageJson === "string" ? usageJson : null };
+    const commands = runLiveCommands(store, runId);
     if (run.finishedAt === null)
-        return deriveRunEfficiency(full, evidenceRoot, now);
+        return deriveRunEfficiency(full, evidenceRoot, now, commands);
     let saved;
     try {
         saved = store.handle.prepare("SELECT parser_version, payload_json FROM run_efficiency WHERE run = ?").get(runId);
@@ -211,7 +223,7 @@ export function runEfficiencyOf(store, evidenceRoot, runId, now) {
         }
         catch { /* derived again below */ }
     }
-    const derived = deriveRunEfficiency(full, evidenceRoot, now);
+    const derived = deriveRunEfficiency(full, evidenceRoot, now, commands);
     const payload = JSON.stringify(derived);
     // A row too large for its column (it can't be: the counts are bounded) is shown, never saved.
     // Saving is a convenience: a store that can't take the row (read-only, busy) still shows what was derived.

package/dist/scope.d.ts

@@ -945,3 +945,10 @@ export declare function liveReleaseOf(store: Store, taskId: string, action: Rele
  * check was composed from a targeted run: a full pass is needed first. Null when nothing blocks.
  */
 export declare function mainDebtProblem(store: Store, repo: string, taskId: string): string | null;
+/**
+ * A deploy gate (docs/plans/chat-management.md §0a.5): a scope whose signed terms name a prepared candidate or carry
+ * release terms. Both are in the scope digest and written at filing, before any release authority exists, so this is
+ * read from the scope alone: a first approval and a fallback gate filed without --release are deploy gates too. From
+ * chat it is approved only through the release card.
+ */
+export declare function deployGateScope(scope: Pick<Scope, "candidate" | "releaseTerms">): boolean;

package/dist/scope.js

@@ -1327,7 +1327,8 @@ export function describeScope(scope, readiness = NO_READINESS) {
 export function releaseTermsSentence(terms) {
     if (!terms.policy.carry)
         return `Release ${terms.packageVersion} from pull request #${terms.pr} at ${terms.approvedSha.slice(0, 7)}. Every later commit asks for your approval again.`;
-    return `Release ${terms.packageVersion} from pull request #${terms.pr} at ${terms.approvedSha.slice(0, 7)}. Later commits on this pull request that only change tests, docs or the changelog ship without asking you again, until it merges or for 3 days. You'll see each one in the release summary.`;
+    const outside = terms.access === "sandboxed" ? "" : " This project's checks don't run in the sandbox: those later test-only commits will run outside the sandbox without being shown to you first.";
+    return `Release ${terms.packageVersion} from pull request #${terms.pr} at ${terms.approvedSha.slice(0, 7)}. Later commits on this pull request that only change tests, docs or the changelog ship without asking you again, until it merges or for 3 days. You'll see each one in the release summary.${outside}`;
 }
 /** What asks again, in full: the terms behind the sentence. */
 export function releaseAsksAgainWords(terms) {
@@ -1338,7 +1339,7 @@ export function releaseAsksAgainWords(terms) {
         `when it deletes, renames or changes the mode of a file, adds a binary, a symlink or a submodule; when it changes the production build;`,
         `when more than ${p.limits.lines} lines or ${p.limits.files} files change after this approval, or ${p.limits.churn} lines of churn;`,
         ...(p.protectProject ? ["when it changes anything: this project is protected;"] : p.protectedPaths.length === 0 ? [] : [`when it changes a protected path: ${p.protectedPaths.join(", ")};`]),
-        `and always once the deploy starts. Repository ${terms.repo}, branch ${terms.branch} into ${terms.base}, check grant ${terms.grant.id}, checks in the sandbox, until ${terms.expiresAt}.`,
+        `and always once the deploy starts. Repository ${terms.repo}, branch ${terms.branch} into ${terms.base}, check grant ${terms.grant.id}, ${terms.access === "sandboxed" ? "checks in the sandbox" : `checks outside the sandbox (${terms.access}), carried because the project allows it`}, until ${terms.expiresAt}.`,
     ];
 }
 function releaseTermsWords(terms) {
@@ -1358,7 +1359,7 @@ function describeApproval(approval) {
 export { personProof } from "./person-proof.js";
 import { personProof } from "./person-proof.js";
 import { releaseTermsDigest } from "./contracts/release-terms.js";
-import { newestReleaseGeneration, releaseAuthorityOfTask, releaseSealProblem } from "./release-authority.js";
+import { CHECK_ACCESS_WIDTH, carriesUnsandboxed, newestReleaseGeneration, releaseAuthorityOfTask, releaseSealProblem } from "./release-authority.js";
 /** Whether the command running now is a machine's: the lead (its token) or a remote API run. Trusted context only. */
 export const machineActing = () => currentActor()?.lead === true || activeRemote() !== null;
 /** A proof row's detail, either form: the legacy text (`<at> · generation <n> · digest <d>`) or the versioned record
@@ -1494,8 +1495,15 @@ export function liveReleaseOf(store, taskId, action, now = new Date()) {
     const grant = store.liveVerifyCommand(a.repo);
     if (grant === null || grant.id !== a.verifyCommand || grant.digest !== a.verifyDigest)
         return refuse("the release check command changed since the approval");
-    if (a.accessDigest !== "sandboxed" || store.projectCheckAccess(a.repo) !== "sandboxed")
-        return refuse("the project's checks no longer run in the sandbox");
+    // The checks reach no further than at the approval. Wider than the sandbox, a carried commit stands only while both
+    // the sealed and the current "Carry release approvals when checks aren't sandboxed" allow it (the stricter of the two).
+    const access = store.projectCheckAccess(a.repo);
+    const sealedWidth = CHECK_ACCESS_WIDTH[a.accessDigest], nowWidth = CHECK_ACCESS_WIDTH[access];
+    if (sealedWidth === undefined || nowWidth === undefined || nowWidth > sealedWidth)
+        return refuse(a.accessDigest === "sandboxed" ? "the project's checks no longer run in the sandbox" : "the project's checks reach further than when the release was approved");
+    if (carry !== null && (a.accessDigest !== "sandboxed" || access !== "sandboxed") && (a.policy?.unsandboxedCarry !== true || !carriesUnsandboxed(store, a.repo))) {
+        return refuse("carrying release approvals when checks aren't sandboxed is off");
+    }
     if (a.policy === null)
         return refuse("this Toolroll doesn't know the release's carry rules; update Toolroll first");
     if (action === "deploy" || action === "merge") {
@@ -1522,3 +1530,12 @@ export function mainDebtProblem(store, repo, taskId) {
         return null;
     return `the nightly full check on main has ${open} open failure${open === 1 ? "" : "s"}, so a check made from a re-run of what failed can't deploy; a full check has to pass first`;
 }
+/**
+ * A deploy gate (docs/plans/chat-management.md §0a.5): a scope whose signed terms name a prepared candidate or carry
+ * release terms. Both are in the scope digest and written at filing, before any release authority exists, so this is
+ * read from the scope alone: a first approval and a fallback gate filed without --release are deploy gates too. From
+ * chat it is approved only through the release card.
+ */
+export function deployGateScope(scope) {
+    return (scope.candidate ?? null) !== null || (scope.releaseTerms ?? null) !== null;
+}

package/dist/scout.d.ts

@@ -131,6 +131,9 @@ export declare function readReportImage(folder: string, file: string): {
 };
 /** The shorten turn's ask: the fields over their limits, and the same report again within them. */
 export declare function shortenReportBrief(over: readonly ReportProblem[], reportFile: string, structured: boolean): string;
+/** Whether a stream event shows the session writing its plan-mode plan
+ * file (~/.claude/plans/…) or handing a plan to ExitPlanMode. */
+export declare function touchesPlanFile(event: Record<string, unknown>): boolean;
 /** A cited link without its secrets: credential-shaped query values and path parts become REDACTED, a fragment
  * that carries one is dropped, and a link still showing one keeps only its origin. Unchanged when it has none. */
 export declare function scrubUrl(text: string): {