toolroll 0.9.71 → 0.9.73

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,9 +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 and a check with sign-ins:
-     * every other launch is denied them (SEATBELT_NO_KEYCHAIN). */
+    /** 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";
     } | {
@@ -56,13 +58,22 @@ export declare const SEATBELT_PTY: string;
  * _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 and a check with sign-ins: the keychain's services. The runtime's
+ * 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;
-/** Toolroll's rules for a launch's terms, in order: its own terminal (unless its read denies cover the devices), then
- * the denies that must come last. */
+/**
+ * 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 '"'"'. */

package/dist/sandbox-runtime.js

@@ -4,8 +4,8 @@
  * 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),
  * 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, the keychain's services only for builds); the rest
- * of the rules, their baseline and their limits are the runtime's.
+ * 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)
@@ -116,7 +116,7 @@ export const SEATBELT_NO_OTHER_TERMINAL = [
     "(deny file-ioctl (ioctl-command 2147578994))",
 ].join("\n");
 /**
- * Last in every launch's profile but a build agent's and a check with sign-ins: the keychain's services. The runtime's
+ * 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).
  */
@@ -124,6 +124,18 @@ 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(/[*?[]/);
@@ -133,11 +145,12 @@ function deniesTerminals(deny) {
         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), then
- * the denies that must come last. */
+/** 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], SEATBELT_NO_OTHER_TERMINAL, ...terms.keychain === true ? [] : [SEATBELT_NO_KEYCHAIN]].join("\n");
+    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

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,96 @@ 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;
+/**
+ * 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;