toolroll 0.9.103 → 0.9.105

package/dist/release-card.js

@@ -1,20 +1,3 @@
-/**
- * The release card (docs/plans/chat-management.md §0a.5): how a deploy gate is approved from chat until the
- * authenticator ships. Alex's decision (2026-10-25): chat keeps approving releases by tap, so the tap is made to mean
- * exactly what was shown.
- *
- * - `approvalTermsOf`: every signed term of the scope (its agent profile and phase route setting by setting) and every
- *   field of its release terms, one line each, "none" for an empty one and "any file in the project" for unnamed paths
- *   (a contract test changes each input of the approval digest in turn and holds the text to change with it).
- * - `releaseChangeList`: what changed since the last verified release, from the plane's own record of it (the merge
- *   commit of the newest merged release whose merge operation succeeded), read as verified Git objects from the
- *   project's recorded Git directory: never a tag or a ref, so moving one changes nothing, and history rewritten around
- *   the objects (a shallow boundary, grafts, replacement refs) refuses the list rather than shortening it.
- *   With no earlier release on record, the pull request's own commits from GitHub, for the recorded owner/name.
- * - `releaseCardOf`: the short card, the full terms (sent as a file where the chat app limits a message), and
- *   `cardDigest`, which binds the scope digest, the plan form's digest, the baseline and the change list: Continue and
- *   Approve carry it, and anything different at the tap refuses.
- */
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { lstatSync, realpathSync } from "node:fs";
@@ -33,25 +16,15 @@ import { RELEASE_PATH, releaseConfigProblem, releaseGitEnv, releaseRemote, relea
 import { taskCheckStamp } from "./store.js";
 import { nightlyReleaseLines } from "./nightly-github.js";
 const NONE = "none";
-/** A budget in dollars from integer micro-dollars, in integer arithmetic: cents when it is whole cents, else every digit. */
 const money = (micro) => {
     const exact = BigInt(micro), whole = exact / 1000000n, rest = (exact < 0n ? -exact : exact) % 1000000n;
     const fraction = rest.toString().padStart(6, "0");
     return `${exact < 0n && whole === 0n ? "-" : ""}$${whole}.${rest % 10000n === 0n ? fraction.slice(0, 2) : fraction}`;
 };
-/** Words the card itself says in place of a value: a signed string spelled the same is quoted, never mistaken for one. */
 const RESERVED = new Set([NONE, "yes", "no", "null", "empty", "not set", "any file in the project", "the whole project", "unreadable"]);
-/** Text that reads the same plain as quoted: ASCII letters, digits and ordinary punctuation only (no lookalike letters
- * from other scripts, no direction marks), never a comma, semicolon, parenthesis, quote, backslash, line break or
- * control character, nor a trailing space. */
 const PLAIN = /^[A-Za-z0-9~/.#$@][A-Za-z0-9 ._/@~+#=!?&%$*:<>|^-]*$/;
-/** JSON-quoted with everything outside printable ASCII \u-escaped (JSON.stringify leaves non-ASCII as it is). */
 const quoted = (value) => JSON.stringify(value).replace(/[^\x20-\x7e]/g, one => `\\u${one.charCodeAt(0).toString(16).padStart(4, "0")}`);
-/** One signed string, unambiguous: as it is when plain, else quoted; an empty, number-like or colon-bearing string, or
- * one of the card's own words, is quoted too. */
 const text = (value) => PLAIN.test(value) && !value.endsWith(" ") && !RESERVED.has(value.toLowerCase()) && !/^-?\d+(\.\d+)?$/.test(value) ? value : quoted(value);
-/** One signed value as the card says it, every shape distinct: "none" for null, "not set" for absent, "empty" for an
- * empty list, `""` for an empty string; a list's entries each said the same way, so a comma never joins two into one. */
 const said = (value) => {
     if (value === undefined)
         return "not set";
@@ -65,15 +38,11 @@ const said = (value) => {
         return value.length === 0 ? "empty" : value.map(one => typeof one === "string" ? text(one) : one === null ? "null" : said(one)).join(", ");
     return text(String(value));
 };
-/** The scope's own terms the card names, in order. A contract test holds `goal`, `outOfScope`, `touches` and
- * `acceptance` (contracts/scope.ts) and the scope's other signed fields to this list; the agent profile and the phase
- * route follow as one line per signed setting (`profile.…`, `route.…`). */
 export const SCOPE_TERM_LABELS = {
     title: "Title", project: "Project", filedBy: "Filed by", goal: "Goal", outOfScope: "Not in scope", touches: "Paths it may touch",
     acceptance: "Done when", qualityMode: "Evidence standard", agents: "Agents and model", permission: "Agents may", checks: "Checks", checkAccess: "Check access",
     budgetMicrousd: "Budget per attempt", candidate: "Candidate commit",
 };
-/** Every leaf of a signed value, at its path (`a.b`, `legs.0.model`), as the card says it. */
 function leavesOf(value, path) {
     if (Array.isArray(value))
         return value.every(one => one === null || typeof one !== "object") ? [{ path, value: said(value) }]
@@ -84,8 +53,6 @@ function leavesOf(value, path) {
     }
     return [{ path, value: said(value) }];
 }
-/** Every field of the release terms, by its path in the terms (contracts/release-terms.ts), against the schema's
- * own leaves: the contract test checks every one has a label. */
 export const RELEASE_TERM_LABELS = {
     version: "Release terms version", repo: "Repository", packageVersion: "Package version", branch: "Branch", pr: "Pull request", base: "Base",
     approvedSha: "Approved commit", approvedTree: "Approved tree",
@@ -95,8 +62,6 @@ export const RELEASE_TERM_LABELS = {
     "policy.unsandboxedCarry": "Carry when checks aren't sandboxed",
     "grant.id": "Release check grant", "grant.digest": "Release check grant digest", access: "Release check access", expiresAt: "Expires",
 };
-/** Every field of a release check's purpose (contracts/release-terms.ts releaseCheckPurposeSchema): the sealed form
- * Toolroll's own releases take while their checks run outside the sandbox. A contract test checks every leaf has one. */
 export const RELEASE_CHECK_LABELS = {
     version: "Release check version", purpose: "Approved as", repo: "Repository", packageVersion: "Package version", branch: "Branch", pr: "Pull request",
     base: "Base", approvedSha: "Approved commit", approvedTree: "Approved tree", "grant.id": "Release check grant", "grant.digest": "Release check grant digest",
@@ -111,7 +76,6 @@ export function releaseSealOf(scope) {
         return { kind: "check", purpose: scope.releaseCheck, identity: scope.releaseCheck };
     return null;
 }
-/** What an unsandboxed (or sign-ins) release check means, said before anyone approves it. Null in the sandbox. */
 export function releaseAccessWords(access) {
     if (access === "unsandboxed")
         return "The release check runs this commit's code with full access to this computer.";
@@ -119,7 +83,6 @@ export function releaseAccessWords(access) {
         return "The release check runs this commit's code with your sign-ins on this computer.";
     return null;
 }
-/** The leaf paths of a zod object schema (nested objects joined with dots). */
 export function schemaLeaves(schema, prefix = "") {
     const shape = schema.shape;
     if (shape === undefined || shape === null)
@@ -127,7 +90,6 @@ export function schemaLeaves(schema, prefix = "") {
     return Object.entries(shape).flatMap(([key, child]) => schemaLeaves(child, prefix === "" ? key : `${prefix}.${key}`));
 }
 const valueAt = (terms, path) => path.split(".").reduce((at, key) => at !== null && typeof at === "object" ? at[key] : undefined, terms);
-/** Every signed term of `scope`, its release terms included, one line each. Reads only. */
 export function approvalTermsOf(store, scope, words) {
     const ref = store.lookupRef(scope.taskId);
     const repo = ref?.repo ?? null;
@@ -138,11 +100,8 @@ export function approvalTermsOf(store, scope, words) {
         project: repo === null ? NONE : `${text(projectName(repo))} (${text(repo)})`,
         filedBy: filer === null ? NONE : filer.name === null ? filer.kind : `${text(filer.name)}${filer.kind === "person" ? "" : ` (${filer.kind})`}`,
         goal: said(scope.goal),
-        // null (nothing excluded) and an empty exclusion are signed apart, and read apart.
         outOfScope: said(scope.outOfScope),
-        // No paths named is no limit: the work may touch any file in the project.
         touches: scope.touches.length === 0 ? "any file in the project" : said(scope.touches),
-        // Each criterion's fields quoted, always: a colon or a parenthesis in one never moves the boundary to the next.
         acceptance: scope.acceptance.length === 0 ? NONE : scope.acceptance.map(one => `${quoted(one.id)}: ${quoted(one.statement)} (evidence: ${said(one.evidence)})`).join("; "),
         qualityMode: scope.qualityMode === "strict" ? "strict" : "standard",
         agents: profile === null ? NONE : `${profile.provider} · ${text(profile.model)}`,
@@ -153,14 +112,11 @@ export function approvalTermsOf(store, scope, words) {
         candidate: said(scope.candidate),
     };
     const lines = Object.keys(SCOPE_TERM_LABELS).map(key => ({ key, label: SCOPE_TERM_LABELS[key], value: scopeValues[key] }));
-    // Every signed setting of the agent profile (what it may read, reach and write, its limits) and the phase route the
-    // digest binds, one line each: the summary lines above never stand in for them.
     if (profile !== null)
         for (const leaf of leavesOf(profile, "profile"))
             lines.push({ key: leaf.path, label: `Agent setting ${leaf.path.slice("profile.".length)}`, value: leaf.value });
     if (scope.proposedRouteJson != null) {
         const route = routeFromJson(scope.proposedRouteJson);
-        // Unreadable (it then never seals): its stored text, exactly, so two different ones never read alike.
         if (route === null)
             lines.push({ key: "route", label: "Phase route (unreadable)", value: quoted(scope.proposedRouteJson) });
         else
@@ -168,7 +124,6 @@ export function approvalTermsOf(store, scope, words) {
                 lines.push({ key: leaf.path, label: `Phase route ${leaf.path.slice("route.".length)}`, value: leaf.value });
     }
     const terms = scope.releaseTerms ?? null;
-    // A release check's purpose (the form Toolroll's own releases seal): every one of its fields, never "none".
     if (terms === null && scope.releaseCheck != null) {
         const purpose = scope.releaseCheck;
         for (const path of schemaLeaves(releaseCheckPurposeSchema)) {
@@ -180,9 +135,7 @@ export function approvalTermsOf(store, scope, words) {
     for (const path of schemaLeaves(releaseTermsSchema)) {
         const label = RELEASE_TERM_LABELS[path] ?? path;
         const value = terms === null ? NONE : path === "pr" ? `#${terms.pr}`
-            // The whole project is protected, and the signed list is said too (it is part of what was signed).
             : path === "policy.protectedPaths" && terms.policy.protectProject ? `the whole project (listed: ${said(terms.policy.protectedPaths)})`
-                // Absent (sealed before the setting existed) is off, said apart from a signed "no".
                 : path === "policy.unsandboxedCarry" && terms.policy.unsandboxedCarry === undefined ? "no (not set when sealed)" : said(valueAt(terms, path));
         lines.push({ key: `release.${path}`, label, value });
     }
@@ -191,13 +144,6 @@ export function approvalTermsOf(store, scope, words) {
 export const termsText = (lines) => lines.map(line => `${line.label}: ${line.value}`).join("\n");
 const SHA = /^[0-9a-f]{40}$/;
 const sha256 = (text) => createHash("sha256").update(text).digest("hex");
-/**
- * The plane's own record of the last verified release of `repo`: the merge commit GitHub answered with, recorded once
- * the release verified the merged tree (the newest merged authority whose merge operation succeeded). Never a tag.
- * Whether the plane recorded one, and its merge commit (eval-harness review 2, finding 4):
- * `recorded: false` only when no merged release is on the record at all; a recorded one whose commit isn't a full id is
- * `recorded: true` with `sha: null` — something to refuse on, never "no previous release".
- */
 export function releaseBaselineRecord(store, repo) {
     const row = store.handle.prepare(`SELECT o.external_ref FROM release_authority a LEFT JOIN release_operation o
     ON o.authority = a.id AND o.kind = 'merge' AND o.state = 'succeeded'
@@ -207,47 +153,47 @@ export function releaseBaselineRecord(store, repo) {
     const ref = row["external_ref"];
     return { recorded: true, sha: typeof ref === "string" && SHA.test(ref) ? ref : null };
 }
-/** The commits after `from` up to `to`, as verified Git objects only, from the project's recorded Git directory: the
- * release coordinator's checkout config allowlist first, then commit-extract's verified range (every commit hashed here,
- * a shallow boundary, grafts or replacement refs refused, and the range proved to stop only in the last release's own
- * history). Null when they can't be read, so a card never shows a shortened list. */
-export function commitsBetween(repo, from, to) {
+export const CONFIG_LIST_MS = 60_000;
+export function readCommitsBetween(repo, from, to) {
     if (!SHA.test(from) || !SHA.test(to))
-        return null;
+        return { ok: false, why: "a commit id isn't a full id" };
     let gitDir;
     try {
         const named = join(realpathSync(repo), ".git");
         if (!lstatSync(named).isDirectory())
-            return null;
+            return { ok: false, why: "the project has no Git folder of its own" };
         gitDir = realpathSync(named);
     }
     catch {
-        return null;
+        return { ok: false, why: "the project's Git folder can't be read" };
     }
     const tools = releaseTools();
     const env = { ...releaseGitEnv(), PATH: RELEASE_PATH };
-    const listing = spawnSync(tools.git, [`--git-dir=${gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env, encoding: "utf8", timeout: 15_000 });
-    if (listing.status !== 0 || releaseConfigProblem(listing.stdout) !== null)
-        return null;
+    const listing = spawnSync(tools.git, [`--git-dir=${gitDir}`, "--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], { cwd: "/", env, encoding: "utf8", timeout: CONFIG_LIST_MS });
+    if (listing.status !== 0) {
+        const how = listing.error?.code === "ETIMEDOUT" ? `timed out after ${CONFIG_LIST_MS / 1000} s`
+            : listing.signal !== null ? `stopped by ${listing.signal}` : listing.error !== undefined ? "couldn't start" : `exited ${listing.status}`;
+        return { ok: false, why: `Git couldn't list the project's settings (${how})` };
+    }
+    if (releaseConfigProblem(listing.stdout) !== null)
+        return { ok: false, why: "the project's Git settings hold an entry a release read refuses" };
     const range = verifiedRange(gitDir, from, to, { git: tools.git, env });
-    if (!range.ok)
-        return null;
-    return range.value.map(one => ({ sha: one.id, subject: subjectText(one.message) }));
+    if (!range.ok) {
+        const said = subjectText(range.message).replace(/\.$/, "");
+        return { ok: false, why: /^[A-Z][a-z]/.test(said) ? said[0].toLowerCase() + said.slice(1) : said };
+    }
+    return { ok: true, commits: range.value.map(one => ({ sha: one.id, subject: subjectText(one.message) })) };
+}
+export function commitsBetween(repo, from, to) {
+    const read = readCommitsBetween(repo, from, to);
+    return read.ok ? read.commits : null;
 }
-/** GitHub lists at most this many of a pull request's commits; a longer one is never shown as complete. */
 export const PULL_REQUEST_COMMITS_MAX = 250;
-/** A commit subject is someone else's text: one line, control-free (src/terminal-text.ts), bounded. The card digest
- * binds this cleaned text, so every surface shows exactly what was bound (Codex round 2, finding 7). */
 export const subjectText = (subject) => cleanTerminalLine(subject.split("\n")[0] ?? "").trim().slice(0, 200);
 const ghRead = args => {
     const read = spawnSync(releaseTools().gh, args, { cwd: "/", env: releaseGitEnv(), encoding: "utf8", timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
     return { status: read.status, stdout: String(read.stdout ?? "") };
 };
-/**
- * A pull request's own commits from GitHub, for the recorded owner/name, complete and bound to the candidate (Codex
- * round 2, finding 6): every page (`--paginate`), accepted only when the pull request's head is `head`, the newest
- * listed commit is `head` and the count is the pull request's own count. Otherwise why, never a shortened list.
- */
 export function pullRequestCommits(slug, pr, head, read = ghRead) {
     const about = read(["api", `repos/${slug}/pulls/${pr}`, "--jq", '[.head.sha, (.commits|tostring)] | join("\\t")']);
     if (about.status !== 0)
@@ -288,9 +234,7 @@ export function pullRequestCommits(slug, pr, head, read = ghRead) {
         return { ok: false, why: "GitHub listed a commit twice" };
     return { ok: true, commits: commits.reverse() };
 }
-/** The ledger act that records a verified release (the merged tree proved equal to the approved one). */
 export const RELEASE_VERIFIED_ACTION = "release verified";
-/** The project's own Git directory: `<realpath(repo)>/.git`, a real directory. */
 function gitDirOf(repo) {
     try {
         const named = join(realpathSync(repo), ".git");
@@ -300,12 +244,6 @@ function gitDirOf(repo) {
         return null;
     }
 }
-/**
- * Record a verified release (Codex round 2, finding 1: verified release history apart from carrying). The coordinator
- * calls it once main's merge commit was proved to hold the approved tree; the plane proves it again here, from its own
- * records only: the task is a release scope of a project, and `merge` read as a verified Git object from the project's
- * recorded Git directory has exactly the sealed approved tree. False when anything doesn't hold (nothing written).
- */
 export function recordVerifiedRelease(store, input) {
     if (!SHA.test(input.merge))
         return false;
@@ -325,10 +263,6 @@ export function recordVerifiedRelease(store, input) {
         source: "work", detail: input.merge });
     return true;
 }
-/**
- * The last verified release of `repo`, from either record: a merged release authority's succeeded merge, or a verified
- * release row (recordVerifiedRelease). The newer stands. Shaped as releaseBaselineRecord.
- */
 export function verifiedReleaseBaseline(store, repo) {
     const authority = store.handle.prepare(`SELECT o.external_ref, COALESCE(o.finished_at, '') AS at FROM release_authority a LEFT JOIN release_operation o
     ON o.authority = a.id AND o.kind = 'merge' AND o.state = 'succeeded'
@@ -342,12 +276,8 @@ export function verifiedReleaseBaseline(store, repo) {
     const ref = authority["external_ref"];
     return { recorded: true, sha: typeof ref === "string" && SHA.test(ref) ? ref : null };
 }
-/** What changed since the last verified release, for a release's sealed identity (terms or a release check's purpose),
- * from Toolroll's records only. */
 export function releaseChangeList(store, terms, read) {
     const record = verifiedReleaseBaseline(store, terms.repo);
-    // A release recorded with a merge commit that can't be read: the list couldn't be read (eval-harness review 2,
-    // finding 4) — never the pull request's commits, as if there were no previous release.
     if (record.recorded && record.sha === null)
         return { baseline: null, commits: null, source: "unread", baselineUnreadable: true, digest: sha256(`release-changes:${JSON.stringify({ baseline: null, source: "unread", commits: null, recorded: true })}`) };
     const baseline = record.recorded ? record.sha : null;
@@ -355,7 +285,10 @@ export function releaseChangeList(store, terms, read) {
     let source;
     let why;
     if (baseline !== null) {
-        commits = commitsBetween(terms.repo, baseline, terms.approvedSha);
+        const read = readCommitsBetween(terms.repo, baseline, terms.approvedSha);
+        commits = read.ok ? read.commits : null;
+        if (!read.ok)
+            why = read.why;
         source = commits === null ? "unread" : "recorded";
     }
     else {
@@ -370,7 +303,6 @@ export function releaseChangeList(store, terms, read) {
     return { baseline, commits, source, ...(why === undefined ? {} : { why }),
         digest: sha256(`release-changes:${JSON.stringify(why === undefined ? { baseline, source, commits } : { baseline, source, commits, why })}`) };
 }
-/** The card digest: everything the person is shown that can change under them. */
 export function cardDigestOf(scopeDigest, formDigest, changes) {
     return sha256(`release-card:v1:${JSON.stringify([scopeDigest, formDigest, changes.baseline, changes.digest])}`);
 }
@@ -383,9 +315,6 @@ function changeWords(changes, terms, cap) {
         return [head, "No commits."];
     return [head, ...changes.commits.slice(0, cap).map(one => `• ${one.sha.slice(0, 7)} ${one.subject.slice(0, 100)}`), ...(changes.commits.length > cap ? [`• and ${changes.commits.length - cap} more`] : [])];
 }
-/** The release card for a deploy gate, against the live records now. */
-/** How this task's last check ran, when one did and it wasn't plainly sandboxed: the sealed level above is what will run;
- * this is what did. Nothing for a release no check has run for. */
 function lastCheckWords(store, repo, taskId) {
     const ran = repo === null ? null : taskCheckStamp(store, repo, taskId);
     const words = ran === null ? null : ranWords(ran.reading);
@@ -393,7 +322,6 @@ function lastCheckWords(store, repo, taskId) {
 }
 export function releaseCardOf(store, scope, formDigest, words, read) {
     const terms = scope.releaseTerms ?? null;
-    // Either sealed form (Codex round 2, finding 1): the identity both share, for the head lines and the change list.
     const identity = releaseSealOf(scope)?.identity ?? null;
     const lines = approvalTermsOf(store, scope, words);
     const value = (key) => lines.find(line => line.key === key)?.value ?? NONE;
@@ -407,15 +335,10 @@ export function releaseCardOf(store, scope, formDigest, words, read) {
         identity === null ? `Candidate ${said(scope.candidate).slice(0, 12)} · ${value("project")}` : `${projectName(identity.repo)} · ${identity.branch} · pull request #${identity.pr} · commit ${identity.approvedSha.slice(0, 7)}`,
         terms === null ? identity === null ? `Checks: ${value("checks")} · check access: ${value("checkAccess")}` : `Carry later commits: no, every later commit asks again · checks: ${value("checks")}`
             : `Carry later commits: ${terms.policy.carry ? "yes" : "no"} · checks: ${value("checks")} · expires ${terms.expiresAt}`,
-        // What an unsandboxed check means, before consent (Codex round 2, finding 1).
         ...(identity === null || releaseAccessWords(identity.access) === null ? [] : [releaseAccessWords(identity.access)]),
-        // A check that already ran for this task, from its stamp (H2): never read as sandboxed when it can't be shown.
         ...lastCheckWords(store, identity?.repo ?? null, scope.taskId),
-        // Option A's disclosure, on the card as on the approval sheet: never approved from chat without it.
         ...(terms !== null && terms.policy.carry && terms.access !== "sandboxed" ? ["This project's checks don't run in the sandbox: later test-only commits will run outside the sandbox without being shown to you first."] : []),
-        // Filed while CI runs (Alex, 2026-10-29): a person may approve now, and is told plainly what still waits.
         ...(releaseCiRunningOf(store, scope.taskId) === null ? [] : [RELEASE_CI_RUNNING_WORDS]),
-        // GitHub's nightly (nightly-github.ts): what holds this release, or why it can't be read. Not a signed term.
         ...(terms === null ? [] : nightlyReleaseLines(store, { repo: terms.repo, taskId: scope.taskId, candidate: scope.candidate ?? null, now: new Date() })),
         "",
         ...changeWords(changes, identity, 5),