toolroll 0.9.70 → 0.9.72

package/dist/remote-main.d.ts

@@ -25,6 +25,8 @@ export declare function remoteUrlProblem(url: string): string | null;
 export type RemoteGit = (args: readonly string[]) => Promise<ExecResult>;
 export type RemoteMain = {
     url: string;
+    /** The private Git directory the read fetched into (plane-owned; gone at `close`). */
+    gitDir: string;
     /** The commit the recorded remote's main is at, as fetched just now. */
     main: string;
     /** Git in the private directory, hardened as above. */

package/dist/remote-main.js

@@ -165,7 +165,7 @@ export class RemoteMains {
             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 } };
+        return { ok: true, remote: { url, gitDir: dir, main, git, bring } };
     }
     close() {
         for (const dir of this.dirs.values()) {

package/dist/result-completion.d.ts

@@ -27,3 +27,9 @@ export declare function familyChangedFiles(store: Store, taskId: string, runId:
  * revises) changed protected files on a one-person approval, and nobody but its approver and requesters
  * has marked it complete. */
 export declare function protectedPublicationHold(store: Store, runId: number, root: string): string | null;
+/** A completion's mark (v134, approval policy §1.7a): whether a person or a machine credential made it. */
+export declare const COMPLETION_BY_PERSON = "proof person";
+export declare const COMPLETION_BY_MACHINE = "proof machine";
+/** Whether this person completing an already-complete result would release a protected publication hold: protected
+ * work needs someone other than its approver, no person's completion on record provides it, and this person can. */
+export declare function personCompletionOwed(store: Store, taskId: string, runId: number, receiptDigest: string, person: string, root: string): boolean;

package/dist/result-completion.js

@@ -78,9 +78,23 @@ export function protectedPublicationHold(store, runId, root) {
     const changed = familyChangedFiles(store, taskId, runId, root);
     if (store.protectedResultProblem(taskId, changed, null) === null)
         return null;
-    const completers = store.handle.prepare("SELECT DISTINCT actor FROM action_ledger WHERE run_id = ? AND action = ?").all(runId, COMPLETION_ACTION)
+    // Only a person's completion counts here (approval policy §1.7a): one a machine credential made, or one from before
+    // completions said who made them, never stands as the second person.
+    const completers = store.handle.prepare("SELECT DISTINCT actor FROM action_ledger WHERE run_id = ? AND action = ? AND detail = ?").all(runId, COMPLETION_ACTION, COMPLETION_BY_PERSON)
         .map(row => String(row["actor"])).filter(actor => actor.startsWith("operator:")).map(actor => actor.slice("operator:".length));
     if (completers.some(name => store.protectedResultProblem(taskId, changed, name) === null))
         return null;
     return "held: it changed protected files on a one-person approval, so it publishes once someone other than its approver marks it complete";
 }
+/** A completion's mark (v134, approval policy §1.7a): whether a person or a machine credential made it. */
+export const COMPLETION_BY_PERSON = "proof person";
+export const COMPLETION_BY_MACHINE = "proof machine";
+/** Whether this person completing an already-complete result would release a protected publication hold: protected
+ * work needs someone other than its approver, no person's completion on record provides it, and this person can. */
+export function personCompletionOwed(store, taskId, runId, receiptDigest, person, root) {
+    const changed = familyChangedFiles(store, taskId, runId, root);
+    if (store.protectedResultProblem(taskId, changed, null) === null || store.protectedResultProblem(taskId, changed, person) !== null)
+        return false;
+    return store.handle.prepare("SELECT 1 FROM action_ledger WHERE run_id = ? AND action = ? AND outcome = ? AND actor = ? AND detail = ?")
+        .get(runId, COMPLETION_ACTION, receiptDigest, `operator:${person}`, COMPLETION_BY_PERSON) === undefined;
+}

package/dist/result-follow-ups.js

@@ -2,6 +2,7 @@ import { checkoutRunner, ranAtLine, widestRan } from "./invoke.js";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { belongsToRelease } from "./release-authority.js";
 import { run as execRun } from "./exec.js";
 import { approvedCommandShell, SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
 import { runWithIsolatedDatabase } from "./child-database.js";
@@ -288,7 +289,34 @@ export function fullCheckGate(store, runId, now) {
     const fulls = followUpChecksOf(store, runId, now).filter(one => one.level === "full" && one.head === run.headRevision);
     // A Full build that waited for a batch check has had no check of its own: Merge waits for the batch, like Quick does.
     const batched = level === "full" && fulls.some(one => one.why === "batch");
-    if ((level === "full" && !batched) || (!batched && store.liveVerifyCommand(repo) === null))
+    // A recorded Full level is not a pass (review round 1): the build's own check must have passed, and a release
+    // check that re-ran only what failed is proved by its release alone, never cleared here.
+    if (level === "full" && !batched) {
+        const targeted = store.handle.prepare("SELECT 1 AS hit FROM release_check_attempt WHERE run = ? AND mode = 'targeted'").get(runId) !== undefined;
+        if (targeted)
+            return { state: "failed", message: "This result's check re-ran only what failed; it merges only through its release." };
+        const own = store.handle.prepare("SELECT status FROM run_check WHERE run = ?").get(runId);
+        if (own !== undefined && own["status"] === "passed")
+            return { state: "clear" };
+        // An ordinary task's own check didn't pass (or has no row): a Full check run again on this same commit decides
+        // (review round 2). A release's task never: it merges only through its release.
+        const taskId = store.refById(run.taskRef)?.externalId ?? null;
+        const last = fulls.at(-1);
+        if (last !== undefined && (taskId === null || !belongsToRelease(store, taskId))) {
+            if (last.state === "passed")
+                return { state: "clear" };
+            if (last.state === "failed")
+                return { state: "failed", message: `The full check failed on this commit${last.exitCode === null ? "" : ` (exit ${last.exitCode})`}. Fix it, or merge anyway.` };
+            if (last.state === "not-run")
+                return { state: "not-run", message: `The full check didn't finish on this commit${last.note === null ? "" : `: ${last.note}`} Run it again, or merge anyway.` };
+            return { state: "waiting", message: "The full check is still running on this commit. Merge once it passes, or merge anyway." };
+        }
+        // No row is a check pending or never requested, never a pass (security review).
+        if (own === undefined)
+            return { state: "not-requested", message: "The full check hasn't run on this commit yet. Merge once it passes, or merge anyway." };
+        return { state: "failed", message: "The full check didn't pass on this commit. Fix it, or merge anyway." };
+    }
+    if (!batched && store.liveVerifyCommand(repo) === null)
         return { state: "clear" };
     const last = fulls.at(-1);
     if (last === undefined)

package/dist/sandbox-runtime.d.ts

@@ -15,6 +15,11 @@ export type SrtTerms = {
     readConfig: FsReadRestrictionConfig;
     writeConfig: FsWriteRestrictionConfig;
     allowMachLookup: string[];
+    /** macOS: the launch may reach the keychain's services (securityd). Only a build's agent: every other launch is
+     * denied them (SEATBELT_NO_KEYCHAIN). */
+    keychain?: boolean;
+    /** macOS: a project check's launch, whose Chromium may register and reach its own service (SEATBELT_CHROMIUM). */
+    browser?: boolean;
     network: {
         kind: "open";
     } | {
@@ -38,8 +43,60 @@ export declare function shellQuote(words: readonly string[]): string;
  * the launch's own temp folder when it has one, so it keeps it; otherwise /tmp/claude, made if missing.
  */
 export declare function withRuntimeTemp<T>(temp: string | undefined, make: () => T): T;
+/**
+ * Toolroll's own Seatbelt rules, appended to the end of the runtime's profile (Seatbelt takes the last rule that
+ * matches). Static: constants here, never made from a launch's data.
+ *
+ * Terminals: a pseudo-terminal of the launch's own (node-pty, `script`, a test that drives a shell), and no other. The
+ * runtime's `allowPty` opens reads and writes on every /dev/ttys device, the operator's own open terminals among them,
+ * and its baseline already reads them (a read steals what is typed there). macOS marks a terminal the sandboxed process
+ * made with the `com.apple.sandbox.pty` extension (for that terminal only: a device number used again later outside is
+ * not covered), so only those are opened by name. A terminal handed down open (a live terminal's own) stays usable.
+ */
+export declare const SEATBELT_PTY: string;
+/** Last in every profile: no other terminal opened by name, and no keystrokes pushed into any terminal (TIOCSTI,
+ * _IOW('t', 114, char)), its own controlling terminal included. */
+export declare const SEATBELT_NO_OTHER_TERMINAL: string;
+/**
+ * Last in every launch's profile but a build agent's: the keychain's services. The runtime's
+ * baseline lets every sandboxed process ask securityd, so it reads the login keychain's items whose access list lets
+ * any program read them (anthropics/sandbox-runtime#755). Build agents keep it (Claude Code signs in from the keychain).
+ */
+export declare const SEATBELT_NO_KEYCHAIN: string;
+/**
+ * Chromium, a project check's launch only: Playwright's default browser (its Chromium headless shell) registers its
+ * port rendezvous service as org.chromium.Chromium.MachPortRendezvousServer.<its pid> at start, and its helpers look
+ * it up. Exactly that name. Chromium takes the prefix from its bundle id with no switch or variable to change it, and
+ * Seatbelt can't tie the pid to the caller, so the residual (another pid's name registered or looked up) is written
+ * up in SECURITY.md. Chrome for Testing (`channel: "chromium"`, headed runs) gets nothing: such a check runs Not
+ * sandboxed.
+ */
+export declare const SEATBELT_CHROMIUM: string;
+/** Toolroll's rules for a launch's terms, in order: its own terminal (unless its read denies cover the devices), a
+ * check's Chromium service, then the denies that must come last. */
+export declare function seatbeltRulesFor(terms: SrtTerms): string;
+/** The runtime's own quoting (its utils/shell-quote.js): a word bare when nothing in it is special, otherwise in single
+ * quotes with a quote inside as '"'"'. */
+export declare function srtQuote(words: readonly string[]): string;
+/** The words of a line srtQuote made, or null for any other line (an operator, a second command, other quoting). */
+export declare function srtWords(line: string): string[] | null;
+/**
+ * `command` (the runtime's macOS invocation) with `rules` appended to its profile, made again from its words. The
+ * runtime's invocation is exactly `env [-u NAME]… [NAME=value]… /usr/bin/sandbox-exec -p <profile> <shell> -c
+ * <command>`, each word quoted its way, and `<command>` is `expected` when given. Any other line (an operator, a word
+ * before `env` or after the command, another program) is refused, so the launch doesn't run.
+ */
+export declare function withSeatbeltRules(command: string, rules: string, expected?: string): string;
 /** The runtime's macOS invocation for `file args` run from `cwd`: a command line for /bin/sh. */
 export declare function srtMacosCommand(file: string, args: readonly string[], terms: SrtTerms, cwd?: string, temp?: string): string;
+/**
+ * macOS: what every sandboxed launch runs first, outside the sandbox, before it execs the runtime's command: a session of
+ * its own (setsid, syscall 147), so no terminal of whoever started Toolroll is its controlling terminal to reach. A
+ * launch that is a session leader already (a live terminal's program, its own terminal made for it) keeps that one; any
+ * other that still has a controlling terminal (getsid, syscall 310) is refused. Perl with -t reads neither PERL5OPT nor
+ * PERL5LIB, and -X keeps its taint warnings off the launch's output.
+ */
+export declare const DETACH: readonly string[];
 /** The Linux helper (sandbox-launch.ts) and the environment variable its launch is handed in. */
 export declare const SANDBOX_LAUNCH_SPEC = "TOOLROLL_SANDBOX_LAUNCH";
 export declare const sandboxLaunchHelper: () => string;
@@ -52,7 +109,8 @@ export type SandboxLaunchSpec = {
     temp?: string;
 };
 /**
- * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>`; on Linux the helper,
+ * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>` in a session of its own
+ * (DETACH); on Linux the helper,
  * handed the launch in its environment (never its arguments, which other users can list).
  */
 export declare function srtSpawn(file: string, args: readonly string[], terms: SrtTerms, cwd?: string, temp?: string, platform?: NodeJS.Platform): {

package/dist/sandbox-runtime.js

@@ -2,8 +2,10 @@
  * The sandbox engine: Anthropic's sandbox-runtime (`@anthropic-ai/sandbox-runtime`, pinned in package.json). Every
  * macOS Seatbelt profile and every Linux bubblewrap + seccomp invocation a fenced launch runs under is generated by
  * its own code, per launch, from a small static config (read denies with exact re-allows, write roots with denies
- * inside them, mach services, the run's proxy). Toolroll adds only what that config says (agent-fence.ts srtTermsOf);
- * the rules themselves, their baseline and their limits are the sandbox runtime's.
+ * inside them, mach services, the run's proxy). Toolroll adds only what that config says (agent-fence.ts srtTermsOf),
+ * plus, on macOS, a few static rules of its own appended to the end of the profile (seatbeltRulesFor: a terminal of the
+ * launch's own and no other, no keystrokes pushed into a terminal, a check's Chromium service, the keychain's services
+ * only for builds); the rest of the rules, their baseline and their limits are the runtime's.
  *
  * macOS: its profile builder runs in this process (it is synchronous), with this process's working folder set to the
  * launch's for the call, because the runtime anchors its mandatory write denies (.git/hooks, .vscode, shell profiles)
@@ -90,6 +92,146 @@ export function withRuntimeTemp(temp, make) {
             process.env["CLAUDE_TMPDIR"] = before.old;
     }
 }
+/**
+ * Toolroll's own Seatbelt rules, appended to the end of the runtime's profile (Seatbelt takes the last rule that
+ * matches). Static: constants here, never made from a launch's data.
+ *
+ * Terminals: a pseudo-terminal of the launch's own (node-pty, `script`, a test that drives a shell), and no other. The
+ * runtime's `allowPty` opens reads and writes on every /dev/ttys device, the operator's own open terminals among them,
+ * and its baseline already reads them (a read steals what is typed there). macOS marks a terminal the sandboxed process
+ * made with the `com.apple.sandbox.pty` extension (for that terminal only: a device number used again later outside is
+ * not covered), so only those are opened by name. A terminal handed down open (a live terminal's own) stays usable.
+ */
+export const SEATBELT_PTY = [
+    "; Toolroll: a pseudo-terminal the launch made itself",
+    "(allow pseudo-tty)",
+    "(allow file-read* file-write* file-ioctl (literal \"/dev/ptmx\"))",
+    "(allow file-read* file-write* file-ioctl (require-all (regex #\"^/dev/ttys[0-9]+$\") (extension \"com.apple.sandbox.pty\")))",
+].join("\n");
+/** Last in every profile: no other terminal opened by name, and no keystrokes pushed into any terminal (TIOCSTI,
+ * _IOW('t', 114, char)), its own controlling terminal included. */
+export const SEATBELT_NO_OTHER_TERMINAL = [
+    "; Toolroll: no other terminal, and nothing typed into one",
+    "(deny file-read-data file-write* (require-all (regex #\"^/dev/ttys[0-9]+$\") (require-not (extension \"com.apple.sandbox.pty\"))))",
+    "(deny file-ioctl (ioctl-command 2147578994))",
+].join("\n");
+/**
+ * Last in every launch's profile but a build agent's: the keychain's services. The runtime's
+ * baseline lets every sandboxed process ask securityd, so it reads the login keychain's items whose access list lets
+ * any program read them (anthropics/sandbox-runtime#755). Build agents keep it (Claude Code signs in from the keychain).
+ */
+export const SEATBELT_NO_KEYCHAIN = [
+    "; Toolroll: no keychain",
+    "(deny mach-lookup (global-name \"com.apple.SecurityServer\") (global-name \"com.apple.securityd.xpc\"))",
+].join("\n");
+/**
+ * Chromium, a project check's launch only: Playwright's default browser (its Chromium headless shell) registers its
+ * port rendezvous service as org.chromium.Chromium.MachPortRendezvousServer.<its pid> at start, and its helpers look
+ * it up. Exactly that name. Chromium takes the prefix from its bundle id with no switch or variable to change it, and
+ * Seatbelt can't tie the pid to the caller, so the residual (another pid's name registered or looked up) is written
+ * up in SECURITY.md. Chrome for Testing (`channel: "chromium"`, headed runs) gets nothing: such a check runs Not
+ * sandboxed.
+ */
+export const SEATBELT_CHROMIUM = [
+    "; Toolroll: the Chromium headless shell port rendezvous service",
+    "(allow mach-register mach-lookup (global-name-regex #\"^org\\.chromium\\.Chromium\\.MachPortRendezvousServer\\.[0-9]+$\"))",
+].join("\n");
+/** Whether a read deny covers the launch's own terminal devices (/dev/ptmx, /dev/ttys*): then it gets none. */
+function deniesTerminals(deny) {
+    const glob = deny.search(/[*?[]/);
+    const path = (glob < 0 ? deny : deny.slice(0, glob)).replace(/\/+$/, "");
+    const devices = ["/dev/ptmx", "/dev/ttys0"];
+    if (glob >= 0)
+        return devices.some(device => device.startsWith(path));
+    return path === "" || path === "/dev" || devices.includes(path) || /^\/dev\/ttys[0-9]*$/.test(path);
+}
+/** Toolroll's rules for a launch's terms, in order: its own terminal (unless its read denies cover the devices), a
+ * check's Chromium service, then the denies that must come last. */
+export function seatbeltRulesFor(terms) {
+    const denied = [...terms.readConfig.denyOnly, ...terms.readConfig.literalDenyOnly ?? []].some(one => deniesTerminals(typeof one === "string" ? one : String(one)));
+    return [...denied ? [] : [SEATBELT_PTY], ...terms.browser === true ? [SEATBELT_CHROMIUM] : [], SEATBELT_NO_OTHER_TERMINAL,
+        ...terms.keychain === true ? [] : [SEATBELT_NO_KEYCHAIN]].join("\n");
+}
+const BARE_WORD = /^[A-Za-z0-9_./:@+,-][A-Za-z0-9_./:=@+,-]*$/;
+/** The runtime's own quoting (its utils/shell-quote.js): a word bare when nothing in it is special, otherwise in single
+ * quotes with a quote inside as '"'"'. */
+export function srtQuote(words) {
+    return words.map(word => word === "" ? "''" : BARE_WORD.test(word) ? word : `'${word.replace(/'/g, `'"'"'`)}'`).join(" ");
+}
+/** The words of a line srtQuote made, or null for any other line (an operator, a second command, other quoting). */
+export function srtWords(line) {
+    const words = [];
+    let at = 0;
+    while (at < line.length) {
+        let word = "";
+        if (line[at] === "'") {
+            for (;;) {
+                const close = line.indexOf("'", at + 1);
+                if (close < 0)
+                    return null;
+                word += line.slice(at + 1, close);
+                at = close + 1;
+                if (line.startsWith(`"'"'`, at)) {
+                    word += "'";
+                    at += 3;
+                    continue;
+                }
+                break;
+            }
+        }
+        else {
+            const end = line.indexOf(" ", at);
+            word = line.slice(at, end < 0 ? line.length : end);
+            if (!BARE_WORD.test(word))
+                return null;
+            at += word.length;
+        }
+        words.push(word);
+        if (at === line.length)
+            break;
+        if (line[at] !== " " || at + 1 === line.length)
+            return null;
+        at += 1;
+    }
+    return words.length > 0 && srtQuote(words) === line ? words : null;
+}
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * `command` (the runtime's macOS invocation) with `rules` appended to its profile, made again from its words. The
+ * runtime's invocation is exactly `env [-u NAME]… [NAME=value]… /usr/bin/sandbox-exec -p <profile> <shell> -c
+ * <command>`, each word quoted its way, and `<command>` is `expected` when given. Any other line (an operator, a word
+ * before `env` or after the command, another program) is refused, so the launch doesn't run.
+ */
+export function withSeatbeltRules(command, rules, expected) {
+    if (rules.includes("'"))
+        throw new Error("a Seatbelt rule Toolroll adds can't hold a quote");
+    const shape = () => new Error("the sandbox runtime's command isn't the shape Toolroll knows");
+    const words = srtWords(command);
+    if (words === null || words[0] !== "env")
+        throw shape();
+    const exec = words.indexOf(SANDBOX_EXEC);
+    if (exec < 1 || words.length !== exec + 6 || words[exec + 1] !== "-p" || words[exec + 4] !== "-c")
+        throw shape();
+    for (let index = 1; index < exec; index += 1) {
+        if (words[index] === "-u") {
+            if (!ENV_NAME.test(words[index + 1] ?? ""))
+                throw shape();
+            index += 1;
+            continue;
+        }
+        const name = words[index].split("=", 1)[0];
+        if (!words[index].includes("=") || !ENV_NAME.test(name))
+            throw shape();
+    }
+    const profile = words[exec + 2];
+    if (!profile.startsWith("(version 1)\n(deny default"))
+        throw shape();
+    if (!/^\/[A-Za-z0-9_./-]+$/.test(words[exec + 3]))
+        throw shape();
+    if (expected !== undefined && words[exec + 5] !== expected)
+        throw shape();
+    return srtQuote([...words.slice(0, exec + 2), `${profile}\n${rules}\n`, ...words.slice(exec + 3)]);
+}
 /** The runtime's macOS invocation for `file args` run from `cwd`: a command line for /bin/sh. */
 export function srtMacosCommand(file, args, terms, cwd = process.cwd(), temp) {
     const network = terms.network;
@@ -110,13 +252,24 @@ export function srtMacosCommand(file, args, terms, cwd = process.cwd(), temp) {
     // The runtime anchors its mandatory write denies at this process's working folder: the launch's, for this call.
     const before = process.cwd();
     process.chdir(cwd);
+    let command;
     try {
-        return withRuntimeTemp(temp, () => wrapCommandWithSandboxMacOS(params));
+        command = withRuntimeTemp(temp, () => wrapCommandWithSandboxMacOS(params));
     }
     finally {
         process.chdir(before);
     }
+    return withSeatbeltRules(command, seatbeltRulesFor(terms), params.command);
 }
+/**
+ * macOS: what every sandboxed launch runs first, outside the sandbox, before it execs the runtime's command: a session of
+ * its own (setsid, syscall 147), so no terminal of whoever started Toolroll is its controlling terminal to reach. A
+ * launch that is a session leader already (a live terminal's program, its own terminal made for it) keeps that one; any
+ * other that still has a controlling terminal (getsid, syscall 310) is refused. Perl with -t reads neither PERL5OPT nor
+ * PERL5LIB, and -X keeps its taint warnings off the launch's output.
+ */
+export const DETACH = ["-t", "-X", "-e",
+    'syscall(147) != -1 or syscall(310, 0) == $$ or !open(my $t, "<", "/dev/tty") or die "toolroll: the sandboxed launch kept a terminal\\n"; exec { $ARGV[0] } @ARGV; die "toolroll: the sandbox could not start: $!\\n";'];
 /** The Linux helper (sandbox-launch.ts) and the environment variable its launch is handed in. */
 export const SANDBOX_LAUNCH_SPEC = "TOOLROLL_SANDBOX_LAUNCH";
 export const sandboxLaunchHelper = () => {
@@ -125,7 +278,8 @@ export const sandboxLaunchHelper = () => {
     return existsSync(beside) ? beside : fileURLToPath(new URL("../dist/sandbox-launch.js", import.meta.url));
 };
 /**
- * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>`; on Linux the helper,
+ * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>` in a session of its own
+ * (DETACH); on Linux the helper,
  * handed the launch in its environment (never its arguments, which other users can list).
  */
 export function srtSpawn(file, args, terms, cwd = process.cwd(), temp, platform = process.platform) {
@@ -133,7 +287,7 @@ export function srtSpawn(file, args, terms, cwd = process.cwd(), temp, platform
         const command = srtMacosCommand(file, args, terms, cwd, temp);
         if (!command.includes(SANDBOX_EXEC))
             throw new Error("the sandbox runtime returned the command unsandboxed");
-        return { file: "/bin/sh", args: ["-c", command], env: {} };
+        return { file: "/usr/bin/perl", args: [...DETACH, "/bin/sh", "-c", command], env: {} };
     }
     const spec = { file, args: [...args], cwd, terms, ...(temp === undefined ? {} : { temp }) };
     return { file: process.execPath, args: [sandboxLaunchHelper()], env: { [SANDBOX_LAUNCH_SPEC]: JSON.stringify(spec) } };

package/dist/scope.d.ts

@@ -353,8 +353,10 @@ export type Scope = SavedScopeTerms & {
     /** How the approval happened (v29): 'password' = the ceremony;
      * 'mode' = sealed by the signer's live mode (modeDigest names it);
      * 'chat' = the owner's own two taps in their paired chat, under their chat-approval setting or a signed term
-     * (modeDigest names that authority; the yes is the person's and doesn't lapse with it). */
-    approvalBasis?: "password" | "mode" | "chat" | "grant" | null;
+     * (modeDigest names that authority; the yes is the person's and doesn't lapse with it).
+     * 'schedule' = a standing order's firing (modeDigest names the order); 'lead' = the owner's lead (never a person);
+     * 'unknown' = a stored word this code doesn't write, which no reader treats as authority (approval-policy plan). */
+    approvalBasis?: ApprovalBasis | "unknown" | null;
     modeDigest?: string | null;
     /** v24 (optional so hand-built scopes in tests stay valid): the working
      * execution profile, its resolution state, and the immutable snapshot
@@ -403,9 +405,21 @@ export type Scope = SavedScopeTerms & {
     /** Who wrote the text (mate arc, ruling 2): a confirmed lead proposal,
      * the coordinator, a scout, or a person (null). Read raw and proved by
      * `termsProblem` — a word outside these is a stated problem, never a
-     * value that slips past the lead quarantine at a mode seal. */
-    proposedVia?: "mate" | "coordinator" | "scout" | null;
+     * value that slips past the lead quarantine at a mode seal. `lead`: the lead wrote it through its token (CLI); it is
+     * the lead's own text, not another machine's, so it isn't quarantined (`quarantinedAuthor`). */
+    proposedVia?: ScopeAuthor | null;
+    /** v135 (docs/plans/release-once.md): a release scope's terms — repository, version, pull request, approved commit,
+     * carry policy, grant, check access, expiry. Part of the digest when present; a person's seal of them opens the
+     * release's authority record. */
+    releaseTerms?: ReleaseTerms | null;
 };
+/** Who wrote a scope's text, when not a person (approval-policy plan §1.4). */
+export type ScopeAuthor = "mate" | "coordinator" | "scout" | "lead";
+/** The authorities a seal can stand on (approval-policy plan §1.5). Anything else stands on nothing. */
+/** `carried`: a later commit of a release carried under a person's release approval (release-once.md); only the carry
+ * transaction ever writes it. */
+export type ApprovalBasis = "password" | "mode" | "chat" | "grant" | "schedule" | "lead" | "carried";
+export declare const APPROVAL_BASES: readonly ApprovalBasis[];
 export type Approval = {
     approved: true;
     at: string;
@@ -439,11 +453,14 @@ export type ScopeInput = {
     posture?: "escalated";
     /** Who wrote this text (mate arc, ruling 2): `mate` for a confirmed mate
      * proposal — mode coverage then never seals it; a human rewrite clears it. */
-    proposedVia?: "mate" | "coordinator" | null;
+    proposedVia?: ScopeAuthor | null;
     /** v39: the signed acceptance rubric. Absent digests exactly like `[]` —
      * see `Scope.acceptance`. `propose` itself never requires this to be
      * non-empty; the roads that call it do. */
     acceptance?: readonly AcceptanceCriterion[];
+    /** v135: release terms (release-carry.ts releaseTermsFor), from the plane's own records. Undefined keeps any terms
+     * the scope already carries; null removes them. */
+    releaseTerms?: ReleaseTerms | null;
     now: Date;
     mutation?: Mutation;
 };
@@ -466,6 +483,8 @@ export declare function digestOf(scope: Pick<Scope, "goal" | "outOfScope" | "tou
     /** v69: a prepared commit, folded in only when present so every earlier
      * digest is untouched. */
     candidate?: string | null;
+    /** v135: release terms, folded in only when present. */
+    releaseTerms?: ReleaseTerms | null;
 }, target?: ExecutionProfile | null | {
     chain: readonly ChainEntry[];
 }, route?: PhaseRoute | null): string;
@@ -562,6 +581,11 @@ export type ApproveResult = {
  | {
     ok: false;
     reason: "password-now";
+}
+/** Approval policy, phase 1: a machine credential (the lead's token, a remote API token) is not a person. */
+ | {
+    ok: false;
+    reason: "machine-proof";
 };
 /**
  * Whether this name-and-token pair is a person the store knows. Shared by
@@ -835,3 +859,89 @@ export declare function acceptanceWords(criteria: readonly AcceptanceCriterion[]
 export declare function scopeRouteWords(scope: Pick<Scope, "proposedRouteJson">, readiness?: ReadinessLookup): string[];
 /** The scope, in the words an operator has to be able to agree or disagree with. */
 export declare function describeScope(scope: Scope, readiness?: ReadinessLookup): string[];
+/** The approval sheet's release lines (release-once.md): the release in one sentence, then what asks again. */
+export declare function releaseTermsSentence(terms: ReleaseTerms): string;
+/** What asks again, in full: the terms behind the sentence. */
+export declare function releaseAsksAgainWords(terms: ReleaseTerms): string[];
+export { personProof } from "./person-proof.js";
+import { type ReleaseTerms } from "./contracts/release-terms.js";
+import { type ReleaseAuthority, type ReleaseCarry } 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 declare const machineActing: () => boolean;
+/** A proof row's detail, either form: the legacy text (`<at> · generation <n> · digest <d>`) or the versioned record
+ * (`{"v":1,"at":…,"digest":…}`, more fields allowed). Any other shape is no proof. */
+export declare function proofDetailOf(detail: unknown): {
+    at: string;
+    digest: string;
+} | null;
+/**
+ * A person's approval of this task as it stands: approved, on the current digest, by the ceremony (`password`) or a
+ * paired-chat tap (`chat`), with a person's proof recorded for that approver and those exact bytes. Release, deploy
+ * and the protected-work counters ask this; a lead, a mode, a grant, a schedule or an approval with no proof is not
+ * a person's.
+ */
+export declare function personApprovalOf(store: Store, taskId: string): {
+    ok: true;
+    by: string;
+    at: string;
+    method: string;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * Who made a seal that says it came through a person's road (`password`, `chat`), from the acts recorded AT THAT SEAL
+ * (approval policy §1.5): the proof rows its approver left at the seal's own instant, and the lead's task act then.
+ * - `machine`: any proof there that isn't a person's (a lead or remote token, or a word this code doesn't know), or the
+ *   lead's act — fail closed, whatever its digest says;
+ * - `person`: a person's proof there for these exact bytes (parsed, either form);
+ * - `automation`: a standing order's firing that no person's proof stands behind;
+ * - `unproven`: none of these (a seal from before proof rows): it dispatches as before, and is never a person's yes.
+ * An older proof for the same bytes never vouches for a later seal. The dispatch belts ask the same in SQL
+ * (approval-authority.ts).
+ */
+export declare function sealOriginOf(store: Store, taskId: string, by: string, digest: string, at: string): {
+    origin: "machine";
+    lead: boolean;
+} | {
+    origin: "person";
+    method: string;
+} | {
+    origin: "automation";
+} | {
+    origin: "unproven";
+};
+/** Text another machine wrote (a confirmed chat proposal, a coordinator, a scout): no mode, grant, remembered password
+ * or chat tap seals it. The lead's own CLI text (`lead`) is not quarantined. */
+export declare const quarantinedAuthor: (via: string | null | undefined) => boolean;
+/** What a release task is about to do. */
+export type ReleaseAction = "dispatch" | "deploy" | "merge" | "complete";
+export type LiveRelease = {
+    applies: false;
+} | {
+    applies: true;
+    ok: true;
+    authority: ReleaseAuthority;
+    carry: ReleaseCarry | null;
+} | {
+    applies: true;
+    ok: false;
+    why: string;
+    authority: ReleaseAuthority | null;
+};
+/**
+ * Whether a task that belongs to a release authority may do `action` now. It applies to EVERY such task, whether its
+ * seal is the person's own or `carried`, and requires all of: the authority's current generation (never superseded,
+ * revoked or expired before it started); a state that fits the action; the task is the authority's current tip; the
+ * anchor's seal is a person's (personApprovalOf, unchanged) on the exact sealed anchor digest; the anchor's approver is
+ * still an active approver with access to the project; for a carried task, a carry row for exactly this task, scope
+ * digest, candidate and generation; the release check grant and check access as sealed (access only ever the fence);
+ * a sealed policy this runtime knows; and, for deploy and merge, no open main-check failure blocking a composed check.
+ * A task that belongs to no release reads `applies: false` — the ordinary rules decide it.
+ */
+export declare function liveReleaseOf(store: Store, taskId: string, action: ReleaseAction, now?: Date): LiveRelease;
+/**
+ * Open main-check failures (the nightly full check, part 3) block the deploy and the merge of a release whose gate
+ * 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;