toolroll 0.9.70 → 0.9.72

package/dist/nightly-check.js

@@ -0,0 +1,362 @@
+/**
+ * The nightly full check on main (docs/plans/release-once.md, part 3): a safety net for accidental omissions, not a
+ * deadline.
+ *
+ * - A scheduled flow (flow-schedule.ts) whose standing order names `check: main-full`. A person approves it once, with
+ *   their password: the approval binds the release check grant (id and digest), the fenced check access and the
+ *   check-only capability, for future main commits. Each firing files `nightly-<date>-<sha7>` at main's head — never a
+ *   release branch — sealed with basis `schedule`; that task can't deploy, merge or complete.
+ * - A failing nightly writes one `main_check_failure` row per failed item (each failed identity, each group or version,
+ *   or the whole part for a part-level outcome) and sends one attention notification.
+ * - A row clears only when a qualifying full pass covers that exact item: intended mode full and coverage full, on a
+ *   commit that contains the failed main commit (verified ancestry), the item or its whole part ran and passed there.
+ *   A composed result never clears anything; a pass that covers one item never clears another.
+ * - Open rows refuse targeted planning and block the deploy and merge of a composed release (scope.ts liveReleaseOf).
+ * - A missed, stalled or disabled nightly gives no signal but its flow's own health notice after 26 hours.
+ */
+import { createHash } from "node:crypto";
+import { projectGitDir } from "./check-report.js";
+import { readVerifiedCommit, verifiedFirstParentWalk } from "./commit-extract.js";
+import { fileIdentity, groupIdentity, journeyIdentity, partIdentity, unitIdentity, versionIdentity } from "./contracts/release-check.js";
+import { propose, authenticateApprover, liveReleaseOf, personProof } from "./scope.js";
+import { failedIdentities, sealedRun } from "./release-recheck.js";
+import { verificationEvidence } from "./verification-evidence.js";
+import { BUILT_IN, TRUSTED_MAIN_ACTION, forgetTrustedMain, recordTrustedMain, trustedRemoteIdentity } from "./store.js";
+import { teardownGit } from "./teardown-git.js";
+/** Where the project's Git store keeps the objects of the remote main the plane read (they matter, the ref doesn't). */
+const NIGHTLY_MAIN_REF = "refs/toolroll/remote-main";
+import { RemoteMains } from "./remote-main.js";
+import { run } from "./exec.js";
+/** How long a nightly may be missing before its flow says so. */
+export const NIGHTLY_MISSED_MS = 26 * 60 * 60_000;
+export const NIGHTLY_STEM = "nightly";
+/** What every nightly firing files: fixed here, never read from the trigger's settings. */
+export const NIGHTLY_GOAL = "Run the full release check on main's head.";
+export const NIGHTLY_NOT = "Changing anything: this is a check only.";
+export const NIGHTLY_ACCEPTANCE = Object.freeze([{ id: "c1", statement: "The full release check passes on main", how: null, evidence: ["check"] }]);
+/** The ledger act that records a person's approval of a nightly check, keyed by its trigger. */
+export const NIGHTLY_APPROVED = "nightly check approved";
+/** The digest a person's approval of the nightly signs: the trigger, the project, the schedule, the check-only terms
+ * and the fixed words each firing files. */
+export function nightlyDigestOf(trigger, repo, schedule, check) {
+    return createHash("sha256").update(`nightly-check:${JSON.stringify({ trigger, repo, schedule, check, goal: NIGHTLY_GOAL, not: NIGHTLY_NOT, acceptance: NIGHTLY_ACCEPTANCE })}`).digest("hex").slice(0, 32);
+}
+/**
+ * The approval of a nightly check as the plane recorded it when a person proved themselves (createNightlyCheckFlow):
+ * the newest ledger row for this trigger. The trigger's own settings never stand in for it — anyone who can edit them
+ * could write one.
+ */
+export function nightlyApprovalOf(store, trigger) {
+    for (const row of store.handle.prepare("SELECT outcome, detail FROM action_ledger WHERE action = ? ORDER BY id DESC LIMIT 20").all(NIGHTLY_APPROVED)) {
+        try {
+            const read = JSON.parse(String(row["detail"]));
+            if (read["v"] !== 1 || read["trigger"] !== trigger)
+                continue;
+            if (typeof read["digest"] !== "string" || typeof read["by"] !== "string" || typeof read["proof"] !== "string" || typeof read["at"] !== "string" || !personProof(read["proof"]))
+                return null;
+            return { digest: read["digest"], by: read["by"], proof: read["proof"], at: read["at"] };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** How often the watch loop reads each recorded remote's main again, and how old a read may be when a nightly fires
+ * or debt is cleared against it (review round 2: one window, two refreshes wide, for both decisions). */
+export const TRUSTED_MAIN_REFRESH_MS = 30 * 60_000;
+export const TRUSTED_MAIN_FIRE_MS = 60 * 60_000;
+export const TRUSTED_MAIN_CLEAR_MS = TRUSTED_MAIN_FIRE_MS;
+/**
+ * Main's head as Toolroll's own process last read it from the project's RECORDED remote (remote-main.ts: the recorded
+ * URL, a private plane-owned Git directory, objects that arrive only by fetch) — never a ref in the project's Git
+ * directory, which a build shares and can move (review round 1). Null when there is no read young enough, when the
+ * last read failed, or when the read was of another remote than the one recorded now (review round 2).
+ */
+export function trustedMainOf(store, repo, now, maxAgeMs) {
+    const row = store.handle.prepare("SELECT outcome, at, detail FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, TRUSTED_MAIN_ACTION);
+    if (row === undefined || now.getTime() - Date.parse(String(row["at"])) > maxAgeMs)
+        return null;
+    const sha = String(row["outcome"]);
+    if (!/^[0-9a-f]{40}$/.test(sha))
+        return null;
+    const identity = trustedRemoteIdentity(store, repo);
+    try {
+        const read = JSON.parse(String(row["detail"]));
+        if (read.v !== 2 || read.sha !== sha || identity === null || read.url !== identity.url || read.record !== identity.record)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return sha;
+}
+/** The watch loop's read of each project's recorded remote main that the nightly check or main's debt needs, at most
+ * every 30 minutes. Each read is a fresh fetch into a private directory. A failed read forgets the last one. A good
+ * one hands its verified objects to the project's Git store (hardened git, content-addressed: git checks every object
+ * against its hash, and filing verifies the commit again), so the nightly can check a merge the checkout never pulled. */
+export async function refreshTrustedMains(store, root, now, runner = run) {
+    const repos = new Set([
+        ...store.handle.prepare("SELECT DISTINCT repo FROM main_check_failure WHERE cleared_at IS NULL").all().map(row => String(row["repo"])),
+        ...store.handle.prepare("SELECT DISTINCT repo FROM action_ledger WHERE action = ?").all(NIGHTLY_APPROVED).map(row => String(row["repo"])),
+    ]);
+    let read = 0;
+    const remotes = new RemoteMains(store, runner, root);
+    try {
+        for (const repo of repos) {
+            if (trustedMainOf(store, repo, now, TRUSTED_MAIN_REFRESH_MS) !== null)
+                continue;
+            const got = await remotes.read(repo);
+            if (!got.ok) {
+                forgetTrustedMain(store, repo, got.why, now);
+                continue;
+            }
+            await teardownGit(runner)(repo, ["-c", "protocol.file.allow=always", "fetch", "--quiet", "--no-tags", "--no-write-fetch-head", "--", got.remote.gitDir, `+refs/toolroll/remote-main:${NIGHTLY_MAIN_REF}`]);
+            if (recordTrustedMain(store, repo, got.remote.main, got.remote.url, now))
+                read++;
+        }
+    }
+    finally {
+        remotes.close();
+    }
+    return read;
+}
+/**
+ * Set up the nightly full check for a project, approved by a person proved now (their password or a re-check; never a
+ * lead or remote token). Its schedule starts paused unless `start`; turning it on is the flow's own switch.
+ */
+export function createNightlyCheckFlow(store, input, now) {
+    const proved = authenticateApprover(store, input.as, input.token, input.repo);
+    if (!proved.ok || !personProof(proved.method))
+        return { ok: false, message: "Only an approver of this project, proved as a person, sets up the nightly check." };
+    const grant = store.liveVerifyCommand(input.repo);
+    if (grant === null)
+        return { ok: false, message: "The project has no approved release check to run." };
+    if (store.projectCheckAccess(input.repo) !== "sandboxed")
+        return { ok: false, message: "The project's checks run outside the sandbox; the nightly check runs only inside it." };
+    const check = { kind: "main-full", grant: { id: grant.id, digest: grant.digest }, access: "sandboxed" };
+    // The order carries no approval: the person's yes is the plane's own ledger row, written below.
+    const order = {
+        stem: NIGHTLY_STEM, goal: NIGHTLY_GOAL, outOfScope: NIGHTLY_NOT, touches: [], requirements: [], acceptance: [...NIGHTLY_ACCEPTANCE], budgetPerRunMicrousd: null, costCeilingUsd: null,
+        singleFlight: true, filedBy: input.as, routine: null, approval: null, check,
+    };
+    const definition = { version: 1, start: "build", stages: [
+            { id: "build", title: "Check main", kind: "task", zone: { x: 0, y: 0, w: 260, h: 300, color: "blue" }, instructions: order.goal, planning: "skip", approver: null, message: null, close: null, script: null, sort: null, next: "done", onFail: null },
+            { id: "done", title: "Done", kind: "done", zone: { x: 420, y: 0, w: 260, h: 300, color: "green" }, instructions: null, planning: null, approver: null, message: null, close: null, script: null, sort: null, next: null, onFail: null },
+        ] };
+    return store.transact(() => {
+        const flow = store.createFlow({ repo: input.repo, name: "Nightly check of main", definitionJson: JSON.stringify(definition), by: input.as }, now);
+        const trigger = store.addFlowTrigger({ flow, kind: "schedule", configJson: JSON.stringify({ kind: "schedule", schedule: input.schedule, title: "Nightly check of main", description: null, zone: "build", order }), hookHash: null, cursor: null, nextAt: null, by: input.as }, now);
+        if (!input.start)
+            store.updateFlowTrigger(trigger, { state: "paused" }, now);
+        store.recordAction({ at: now.toISOString(), actor: input.as, repo: input.repo, taskId: null, runId: null, action: NIGHTLY_APPROVED, outcome: input.start ? "on" : "paused", source: "request",
+            detail: JSON.stringify({ v: 1, trigger, flow, digest: nightlyDigestOf(trigger, input.repo, input.schedule, check), by: input.as, proof: proved.method, at: now.toISOString(), schedule: input.schedule, grant: grant.id }) });
+        return { ok: true, flow, trigger };
+    });
+}
+/** A nightly firing (fileStandingOrder routes here): the approval checked again, main's head read, one check-only task
+ * filed and sealed by its standing order. */
+export function fileNightlyCheck(store, input, now) {
+    const { order, repo } = input;
+    const check = order.check;
+    // The approval is the plane's own record of the person's yes for this trigger; anything in the settings is ignored.
+    const approval = nightlyApprovalOf(store, input.trigger);
+    if (approval === null || approval.digest !== nightlyDigestOf(input.trigger, repo, input.schedule, check))
+        return { made: "skipped", note: "Skipped: the nightly check isn't approved as it stands. Set it up again." };
+    const account = store.accountOf(approval.by);
+    if (account === null || account.revokedAt !== null || account.role !== "approver" || !store.accountCanAccess(approval.by, repo))
+        return { made: "skipped", note: `Skipped: ${approval.by} can no longer approve in this project.` };
+    const grant = store.liveVerifyCommand(repo);
+    if (grant === null || grant.id !== check.grant.id || grant.digest !== check.grant.digest)
+        return { made: "skipped", note: "Skipped: the release check changed since the nightly check was approved." };
+    if (store.projectCheckAccess(repo) !== "sandboxed")
+        return { made: "skipped", note: "Skipped: the project's checks run outside the sandbox." };
+    const blocker = store.standingOrderBlocker(input.trigger, order.routine, now);
+    if (blocker !== null)
+        return { made: "skipped", note: `Skipped: the last one (${blocker.taskId}, ${blocker.state}) hasn't finished.` };
+    // Main as the plane read it from the recorded remote, recently; never a ref in the shared Git directory.
+    const trusted = trustedMainOf(store, repo, now, TRUSTED_MAIN_FIRE_MS);
+    if (trusted === null)
+        return { made: "skipped", note: "Skipped: main hasn't been read from the project's recorded remote lately." };
+    const gitDir = projectGitDir(repo);
+    if (gitDir === null || !readVerifiedCommit(gitDir, trusted).ok)
+        return { made: "skipped", note: `Skipped: main's ${trusted.slice(0, 7)} isn't in the project's history yet.` };
+    const head = { sha: trusted };
+    const taskId = `${NIGHTLY_STEM}-${now.toISOString().slice(0, 10).replace(/-/g, "")}-${head.sha.slice(0, 7)}`;
+    if (store.getTask(taskId) !== null)
+        return { made: "skipped", note: `Skipped: ${head.sha.slice(0, 7)} was already checked today (${taskId}).` };
+    store.createTask({ id: taskId, title: `Nightly check of main at ${head.sha.slice(0, 7)}`, filedBy: { name: null, kind: "automation" } }, now);
+    const ref = store.refFor(BUILT_IN, taskId, "ours");
+    store.placeTask(ref.id, repo, {}, now);
+    store.recordAction({ at: now.toISOString(), actor: "toolroll", repo, taskId, runId: null, action: "task checks chosen", outcome: "full", source: "request", detail: "Checks for this task: Full" });
+    // Fixed words, never the trigger's: what the person approved is what files.
+    propose(store, { taskId, goal: NIGHTLY_GOAL, outOfScope: NIGHTLY_NOT, candidate: head.sha, acceptance: [...NIGHTLY_ACCEPTANCE], now });
+    const sealed = store.sealScopeApproval(taskId, approval.by, now, {}, { kind: "schedule", modeDigest: approval.digest }, "automation");
+    store.handle.prepare("INSERT INTO nightly_check (repo, sha, task, at) VALUES (?, ?, ?, ?)").run(repo, head.sha, taskId, now.toISOString());
+    return sealed ? { made: "filed", taskId, approved: true, note: `Checking main at ${head.sha.slice(0, 7)}.` }
+        : { made: "filed", taskId, approved: false, note: "Its approval can't stand on its own here, so this one waits for approval." };
+}
+/** Whether a task is a nightly check of main (check only: it never deploys, merges or completes). */
+export const isNightlyTask = (store, taskId) => store.handle.prepare("SELECT 1 AS hit FROM nightly_check WHERE task = ?").get(taskId) !== undefined;
+/** Every item a failed check failed: each failed identity, each failed group or version, and the whole part for a
+ * part that couldn't say which items (it stopped, never reported, or crashed). No report: every part. */
+export function failedItems(report) {
+    if (report === null)
+        return [partIdentity("all")];
+    const items = new Set(failedIdentities(report));
+    for (const part of report.parts) {
+        if (!part.selected)
+            continue;
+        const attributed = part.part === "unit" ? report.units !== null && report.units.finished && report.units.runErrors === 0
+            : part.part === "upgrade" ? report.upgrades !== null && report.upgrades.finished
+                : part.part === "typecheck" || part.part === "build" ? false
+                    : report.journeys.some(one => (one.kind === "real" ? `${one.script}-real` : one.script) === part.part && one.finished && one.groups.every(group => group.state !== "not-run"));
+        if ((!part.ran || part.code !== 0) && (!attributed || part.part === "typecheck" || part.part === "build"))
+            items.add(partIdentity(part.part));
+    }
+    return [...items].sort();
+}
+/** The words of one failure notice: "2 unit files, app/pages". */
+export function failureSummary(items) {
+    const files = new Set(items.flatMap(one => /^unit:(.+?)::/.exec(one)?.[1] ?? /^file:(.+)$/.exec(one)?.[1] ?? []));
+    const groups = new Set(items.flatMap(one => { const m = /^(?:group|journey):(app|flows):(?:scripted|real):([^:]+?)(?:::|$)/.exec(one); return m === null ? [] : [`${m[1]}/${m[2]}`]; }));
+    const versions = items.flatMap(one => /^upgrade:(.+)$/.exec(one)?.[1] ?? []);
+    const parts = items.flatMap(one => /^part:(.+)$/.exec(one)?.[1] ?? []);
+    return [
+        ...(files.size === 0 ? [] : [`${files.size} unit file${files.size === 1 ? "" : "s"}`]), ...groups,
+        ...(versions.length === 0 ? [] : [`upgrade ${versions.join(", ")}`]), ...parts.map(one => one === "all" ? "the whole check" : `the ${one} part`),
+    ].join(", ") || "the check";
+}
+/**
+ * Whether a full run's report shows `item` itself ran and PASSED there (security review): a failed identity has to be
+ * reported passed by name — missing, skipped, or a passing part around it never clears it. A part-level item clears
+ * when that whole part ran and passed.
+ */
+export function coversItem(report, item) {
+    const part = (name) => report.parts.find(one => one.part === name);
+    const passedPart = (name) => { const one = part(name); return one !== undefined && one.ran && one.code === 0; };
+    const unit = /^unit:(.+?)::(.+)$/s.exec(item);
+    if (unit !== null)
+        return report.units?.identities.some(one => one.file === unit[1] && one.name === unit[2] && one.state === "passed") === true;
+    const file = /^file:(.+)$/.exec(item)?.[1];
+    if (file !== undefined)
+        return report.units?.files.some(one => one.file === file && one.state === "passed" && one.failed === 0) === true;
+    const journey = /^journey:(app|flows):(scripted|real):([^:]+?)::(.+)$/s.exec(item);
+    if (journey !== null) {
+        const found = report.journeys.find(one => one.script === journey[1] && one.kind === journey[2])?.groups.find(one => one.group === journey[3]);
+        return found?.journeys.some(one => one.name === journey[4] && one.state === "passed") === true;
+    }
+    const group = /^group:(app|flows):(scripted|real):(.+)$/.exec(item);
+    if (group !== null) {
+        const found = report.journeys.find(one => one.script === group[1] && one.kind === group[2])?.groups.find(one => one.group === group[3]);
+        return found !== undefined && found.state === "passed" && !found.unattributed;
+    }
+    const version = /^upgrade:(.+)$/.exec(item)?.[1];
+    if (version !== undefined)
+        return report.upgrades?.versions.some(one => one.version === version && one.state === "passed") === true;
+    const whole = /^part:(.+)$/.exec(item)?.[1];
+    if (whole === "all")
+        return report.parts.filter(one => one.selected).every(one => one.ran && one.code === 0) && report.exitCode === 0;
+    return whole !== undefined && passedPart(whole);
+}
+/**
+ * The plane's sweep (watch's follow-up checks): settle each finished nightly (failure rows and one attention notice),
+ * then let each finished full release check clear the main failures it covers. Returns how many it settled.
+ */
+export function settleReleaseChecks(store, root, now) {
+    let settled = 0;
+    for (const row of store.handle.prepare("SELECT * FROM nightly_check WHERE outcome IS NULL AND task IS NOT NULL ORDER BY id").all()) {
+        const ref = store.lookupRef(String(row["task"]));
+        if (ref === null)
+            continue;
+        const runs = store.runsFor(ref.id).filter(one => one.role === "builder" && one.finishedAt !== null).sort((a, b) => b.id - a.id);
+        const run = runs[0];
+        if (run === undefined)
+            continue;
+        const check = store.handle.prepare("SELECT status FROM run_check WHERE run = ?").get(run.id);
+        const status = check === undefined ? (run.outcome === "built" ? null : "failed") : String(check["status"]);
+        if (status === null || status === "running" || status === "pending")
+            continue;
+        const repo = String(row["repo"]), sha = String(row["sha"]);
+        store.transact(() => {
+            store.handle.prepare("UPDATE nightly_check SET run = ?, outcome = ? WHERE id = ?").run(run.id, status, Number(row["id"]));
+            if (status !== "passed") {
+                const items = failedItems(sealedRun(store, root, run.id)?.report ?? null);
+                for (const item of items)
+                    store.handle.prepare("INSERT OR IGNORE INTO main_check_failure (repo, sha, run, item, opened_at) VALUES (?, ?, ?, ?, ?)").run(repo, sha, run.id, item, now.toISOString());
+                store.enqueueNotification({ dedupeKey: `nightly-failed:${Number(row["id"])}`, kind: "nightly-failed", subject: "Nightly check failed on main",
+                    body: `Nightly full check failed on main at ${sha.slice(0, 7)}: ${failureSummary(items)}.`, pushClass: "attention", source: { taskRef: ref.id } }, now);
+            }
+        });
+        settled++;
+    }
+    for (const row of store.handle.prepare("SELECT a.run, a.mode, r.task_ref, r.head_revision, r.finished_at FROM release_check_attempt a JOIN run r ON r.id = a.run WHERE a.settled_at IS NULL AND r.finished_at IS NOT NULL ORDER BY a.run").all()) {
+        const runId = Number(row["run"]);
+        const repo = store.refById(Number(row["task_ref"]))?.repo ?? null;
+        store.transact(() => {
+            store.handle.prepare("UPDATE release_check_attempt SET settled_at = ? WHERE run = ?").run(now.toISOString(), runId);
+            if (repo === null || row["mode"] !== "full" || row["head_revision"] == null)
+                return;
+            // Only a full pass with coverage full clears anything; a composed result never does.
+            const gate = verificationEvidence(store, root, runId);
+            if (!gate.ok || gate.bytes === null)
+                return;
+            // A SUCCESSFUL executed full check only (review round 1): its receipt says it ran and passed, its coverage is full,
+            // and its own report exited 0. A failed full check clears nothing, whatever items it reports passed.
+            let receipt;
+            try {
+                receipt = JSON.parse(gate.bytes);
+            }
+            catch {
+                return;
+            }
+            if (receipt.coverage !== "full" || receipt.result?.ran !== true || receipt.result.exitCode !== 0)
+                return;
+            const report = sealedRun(store, root, runId)?.report ?? null;
+            if (report === null || report.exitCode !== 0)
+                return;
+            const gitDir = projectGitDir(repo);
+            if (gitDir === null)
+                return;
+            const head = String(row["head_revision"]);
+            // The pass has to be on main (its head an ancestor of, or main's head itself) or the exact candidate of a release
+            // whose approval stands: a pass on a side branch clears nothing (security review).
+            const task = store.refById(Number(row["task_ref"]))?.externalId ?? null;
+            const main = trustedMainOf(store, repo, now, TRUSTED_MAIN_CLEAR_MS);
+            const onMain = main !== null && (head === main || verifiedFirstParentWalk(gitDir, main, head, 5000).ok);
+            const release = task === null ? null : liveReleaseOf(store, task, "dispatch", now);
+            const candidate = task === null ? null : store.getScope(task)?.candidate ?? null;
+            // The run must have checked that very candidate: its head is the candidate, or the commit a prepared build recorded
+            // for it, holding exactly the candidate's verified tree.
+            const sameTree = (a, b) => { const x = readVerifiedCommit(gitDir, a), y = readVerifiedCommit(gitDir, b); return x.ok && y.ok && x.value.tree === y.value.tree; };
+            const releaseTip = release !== null && release.applies && release.ok && candidate !== null && release.authority.tipSha === candidate
+                && (head === candidate || sameTree(head, candidate));
+            if (!onMain && !releaseTip)
+                return;
+            for (const failure of store.handle.prepare("SELECT id, sha, item FROM main_check_failure WHERE repo = ? AND cleared_at IS NULL").all(repo)) {
+                const sha = String(failure["sha"]);
+                const contains = sha === head || verifiedFirstParentWalk(gitDir, head, sha, 2000).ok;
+                if (!contains || !coversItem(report, String(failure["item"])))
+                    continue;
+                store.handle.prepare("UPDATE main_check_failure SET cleared_by_run = ?, cleared_at = ? WHERE id = ? AND cleared_at IS NULL").run(runId, now.toISOString(), Number(failure["id"]));
+                store.recordAction({ at: now.toISOString(), actor: "toolroll", repo, taskId: null, runId, action: "main failure cleared", outcome: "cleared", source: "work", detail: `${String(failure["item"])} at ${sha.slice(0, 7)} · by run ${runId}` });
+            }
+        });
+        settled++;
+    }
+    return settled;
+}
+/** The nightly's flow health: "the nightly check hasn't run since …" after 26 hours without a firing. Null when it ran
+ * recently, or the project has no nightly check. */
+export function nightlyHealthWords(store, repo, configuredAt, now) {
+    const last = store.handle.prepare("SELECT at FROM nightly_check WHERE repo = ? ORDER BY id DESC LIMIT 1").get(repo);
+    const since = last === undefined ? configuredAt : String(last["at"]);
+    if (now.getTime() - Date.parse(since) < NIGHTLY_MISSED_MS)
+        return null;
+    return last === undefined ? `the nightly check hasn't run since it was set up (${since.slice(0, 16).replace("T", " ")})` : `the nightly check hasn't run since ${since.slice(0, 16).replace("T", " ")}`;
+}
+export { fileIdentity, groupIdentity, journeyIdentity, unitIdentity, versionIdentity };
+/** The items the nightly check of main found failing that are still open: a full check reports each by name. */
+export function openMainFailureItems(store, repo) {
+    return store.handle.prepare("SELECT DISTINCT item FROM main_check_failure WHERE repo = ? AND cleared_at IS NULL ORDER BY item").all(repo).map(row => String(row["item"]));
+}

package/dist/operate.js

@@ -56,6 +56,8 @@ import { readHooksBase, scheduleFromWords } from "./flow-triggers.js";
 import { sendSubagentSummaries } from "./subagent-admin.js";
 import { runRequestedUndos, sendSubagentWeeklies } from "./subagent-week.js";
 import { refreshConnections } from "./mcp-connect.js";
+import { releaseTermsFor } from "./release-carry.js";
+import { refreshTrustedMains, settleReleaseChecks } from "./nightly-check.js";
 import { SECRETS_FIRST, startToolSecrets, toolSecretStorage } from "./project-tools.js";
 import { followDiscord } from "./discord.js";
 import { followTeams } from "./teams.js";
@@ -192,7 +194,7 @@ import { register, authenticate, heartbeat as heartbeatRunner, isAlive, recoverD
 import { mintCoordinator, revokeCoordinator, listCoordinators } from "./coordinator.js";
 import { serveMcp } from "./mcp.js";
 import { createInterface } from "node:readline";
-import { propose, approve, addApprover, authenticateAccount, authenticateApprover as passwordApprover, describeScope, approvalOf, hashToken as hashApproverToken, modeFilingCoverage, acceptanceLinesToInput, parseAcceptanceCriteria, splitAcceptanceRubric, rubricIsPlaceholder, isCommitSha, credentialProof, rememberedLogin } from "./scope.js";
+import { propose, approve, addApprover, authenticateAccount, authenticateApprover as passwordApprover, describeScope, approvalOf, hashToken as hashApproverToken, modeFilingCoverage, acceptanceLinesToInput, parseAcceptanceCriteria, splitAcceptanceRubric, rubricIsPlaceholder, isCommitSha, credentialProof, rememberedLogin, personApprovalOf } from "./scope.js";
 import { CHAT_APPROVE_ALL, presetTerms, modeTermsJson, modeDigestOf, modeTermsFromJson, modeWords, MODE_MAX_DAYS } from "./modes.js";
 import { WorktreePool } from "./worktree.js";
 import { baseStandingWords, freshBaseFor, taskBaseOf } from "./task-base.js";
@@ -694,8 +696,12 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "request",
     // project sandbox (sandbox parity C9): read denies and macOS services.
     "read-deny", "mach",
+    // task scope --release <version>:<pr>:<branch>: a release scope's terms (release-once.md).
+    "release",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
+    // task scope --release ... --no-carry: every later commit asks again.
+    "no-carry",
     "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
     "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
@@ -6225,6 +6231,11 @@ async function runWatchLoop(args) {
             const ran = await runWaitingChecks(store, context.evidenceRoot, { now: context.clock, shouldStop: stopping });
             if (ran > 0)
                 progress(`watch: ran ${ran} follow-up check(s)`);
+            // The nightly check of main and the release checks that clear its failures (release-once.md, part 3).
+            await refreshTrustedMains(store, context.evidenceRoot, context.clock(), context.gitRunner);
+            const settledChecks = settleReleaseChecks(store, context.evidenceRoot, context.clock());
+            if (settledChecks > 0)
+                progress(`watch: settled ${settledChecks} release check(s)`);
             // A finished check may send a build's card down its failure path: now, not on the next beat.
             if (ran + batched > 0)
                 moveCards(store, repo, context.clock(), context.evidenceRoot);
@@ -9031,6 +9042,8 @@ function showTask(positional, context) {
         claim: currentClaim(store, ref.id, now),
         scope,
         approval: approvalOf(scope),
+        // Whether a person gave that approval, with their proof (approval policy): what the release gate reads.
+        personApproval: personApprovalOf(store, id),
         route: taskRouteView(routed, readiness),
         // Fresh base: the commit this task's work starts from, and how far current main has moved past it.
         base,
@@ -9719,6 +9732,25 @@ async function scopeTask(positional, flags, context) {
     const candidateGiven = text(flags, "candidate");
     if (candidateGiven !== undefined && !isCommitSha(candidateGiven))
         return fail(write, json, "task scope", "usage", "--candidate is the full 40-character commit hash the machine will check out", EXIT.usage);
+    // A release scope's terms (release-once.md), filled in from the plane's own records: `--release
+    // <version>:<pull request>:<branch>` with the candidate. Terms that can't be made (the checks run outside the
+    // sandbox, say) file the scope without them: every later commit then asks again, as before.
+    const releaseGiven = text(flags, "release");
+    let releaseTerms;
+    let releaseNote = null;
+    if (releaseGiven !== undefined) {
+        const spec = /^(\d+\.\d+\.\d+):([1-9][0-9]*):([A-Za-z0-9._/-]+)$/.exec(releaseGiven);
+        if (spec === null || candidateGiven === undefined)
+            return fail(write, json, "task scope", "usage", "--release takes <version>:<pull request>:<branch>, with --candidate <commit>", EXIT.usage);
+        const repo = store.lookupRef(id)?.repo ?? null;
+        if (repo === null)
+            return fail(write, json, "task scope", "usage", "a release scope's task has to be placed in its project first", EXIT.usage);
+        const made = releaseTermsFor(store, { repo, version: spec[1], pr: Number(spec[2]), branch: spec[3], candidate: candidateGiven, now, noCarry: flags.get("no-carry") === true });
+        if (made.ok)
+            releaseTerms = made.terms;
+        else
+            releaseNote = `Later commits on this release will each ask for approval: ${made.why}.`;
+    }
     if (acceptanceParse.criteria.length === 0)
         return fail(write, json, "task scope", "acceptance-required", "--acceptance named no valid criteria", EXIT.usage);
     const touches = (text(flags, "touches") ?? "").split(",").map(one => one.trim()).filter(Boolean);
@@ -9785,6 +9817,7 @@ async function scopeTask(positional, flags, context) {
             : null;
         const proposed = propose(store, {
             ...(candidateGiven === undefined ? {} : { candidate: candidateGiven }),
+            ...(releaseTerms === undefined ? {} : { releaseTerms }),
             taskId: id,
             goal,
             outOfScope: text(flags, "not") ?? null,
@@ -9836,7 +9869,8 @@ async function scopeTask(positional, flags, context) {
     }
     // A changed scope on a planning task plans again (v119): say so once, instead of leaving the old plan implied.
     const replanned = (store.lookupRef(id)?.planningGeneration ?? 0) > generationBefore;
-    return succeed(write, json, "task scope", { scope, ...(replanned ? { planningRestarted: true } : {}) }, () => [
+    return succeed(write, json, "task scope", { scope, ...(replanned ? { planningRestarted: true } : {}), ...(releaseNote === null ? {} : { releaseNote }) }, () => [
+        ...(releaseNote === null ? [] : [releaseNote]),
         replanned
             ? `Scope written for ${id}. The scope changed, so planning starts again; nothing builds until somebody approves the new plan.`
             : `Scope written for ${id}. Nothing will build it until somebody approves it.`,
@@ -10059,6 +10093,9 @@ function describeApproveFailure(reason, id) {
         return `you filed ${id}, and this project needs someone else to approve it`;
     if (reason === "person-required")
         return `${id} is protected work: a person has to approve it, not an operating mode, a schedule or a subagent`;
+    // Approval policy, phase 1: the lead's token (or a remote API token) proves a credential, not a person.
+    if (reason === "machine-proof")
+        return "only a person can approve this — approve it on the task page or from your paired chat";
     if (reason === "second-approver")
         return `your approval of ${id} is recorded; it is protected work, so a second person needs to approve it (toolroll task approve ${id} as them)`;
     if (reason === "no-approvers") {

package/dist/person-proof.d.ts

@@ -0,0 +1,2 @@
+/** Whether a recorded proof is a person's. A runtime string: a missing, corrupt or future value is never a person. */
+export declare function personProof(proof: string | null | undefined): boolean;

package/dist/person-proof.js

@@ -0,0 +1,14 @@
+/** Every credential method, classified: a person proved now (or by their own remembered sign-in), or a machine
+ * credential standing in for them. A new method fails to compile here until someone decides which it is. */
+const METHOD_IS_PERSON = {
+    "password-now": true, "sso-now": true, "fresh-password": true, "fresh-sso": true, "session": true, "cli-login": true,
+    "remote-token": false, "lead-token": false,
+};
+/** Proofs that aren't credential methods: the paired-chat tap, and the phone plan's passkey ceremony. */
+const OTHER_PERSON_PROOFS = new Set(["chat", "passkey"]);
+/** Whether a recorded proof is a person's. A runtime string: a missing, corrupt or future value is never a person. */
+export function personProof(proof) {
+    if (typeof proof !== "string")
+        return false;
+    return Object.prototype.hasOwnProperty.call(METHOD_IS_PERSON, proof) ? METHOD_IS_PERSON[proof] : OTHER_PERSON_PROOFS.has(proof);
+}

package/dist/plan-auto.js

@@ -1,7 +1,7 @@
 import { releaseUnattendedRun, reserveUnattendedRun, unattendedGrantStands } from "./flow-unattended.js";
 import { modeTermsFromJson } from "./modes.js";
 import { plannerContractOf, plannerSourceDigest } from "./planner-source.js";
-import { modeFilingCoverage, propose } from "./scope.js";
+import { modeFilingCoverage, propose, quarantinedAuthor } from "./scope.js";
 export const PLAN_AUTO_SCHEMA = `CREATE TABLE IF NOT EXISTS plan_authorization (
   task_id TEXT PRIMARY KEY REFERENCES task(id),
   source_digest TEXT NOT NULL,
@@ -21,7 +21,7 @@ export function applyModeToNewFiling(store, taskId, actor, now) {
     const ref = store.lookupRef(taskId);
     const scope = store.getScope(taskId);
     const coverage = modeFilingCoverage(store, ref?.repo ?? null, actor, now);
-    if (ref === null || scope === null || scope.proposedVia != null || coverage === null)
+    if (ref === null || scope === null || quarantinedAuthor(scope.proposedVia) || coverage === null)
         return;
     const filed = propose(store, { taskId, goal: scope.goal, outOfScope: scope.outOfScope, touches: scope.touches, acceptance: scope.acceptance,
         budgetMicrousd: scope.budgetMicrousd ?? coverage.defaultBudgetMicrousd,
@@ -48,7 +48,7 @@ export function authorizePlanUnderMode(store, taskId, actor, now) {
         if (!source.ok || source.contract.scope === null || source.contract.revision !== null)
             return false;
         const scope = source.contract.scope;
-        if (scope.proposedVia !== null || scope.acceptance.length === 0 || scope.touches.length === 0 || scope.terms.profileState !== "resolved" || store.scopeSealed(taskId))
+        if (quarantinedAuthor(scope.proposedVia) || scope.acceptance.length === 0 || scope.touches.length === 0 || scope.terms.profileState !== "resolved" || store.scopeSealed(taskId))
             return false;
         store.raw().prepare(`INSERT INTO plan_authorization(task_id,source_digest,scope_digest,mode_digest,signed_by,created_at,basis) VALUES (?,?,?,?,?,?,'mode')
       ON CONFLICT(task_id) DO UPDATE SET source_digest=excluded.source_digest,scope_digest=excluded.scope_digest,mode_digest=excluded.mode_digest,signed_by=excluded.signed_by,created_at=excluded.created_at,basis='mode'`)
@@ -72,7 +72,7 @@ function escalatedPosture(store, taskId) {
 export function sealFlowFilingUnderGrant(store, taskId, grant, card, now) {
     const ref = store.lookupRef(taskId);
     const scope = store.getScope(taskId);
-    if (ref === null || scope === null || scope.proposedVia != null || scope.profileState !== "resolved" || escalatedPosture(store, taskId))
+    if (ref === null || scope === null || quarantinedAuthor(scope.proposedVia) || scope.profileState !== "resolved" || escalatedPosture(store, taskId))
         return false;
     if (!unattendedGrantStands(store, grant.digest, grant.signedBy, ref.repo, scope.touches, now))
         return false;

package/dist/planner-source.d.ts

@@ -81,7 +81,7 @@ export type PlannerContractScope = ContractTerms & {
         approvedDigest: string | null;
         approvedBy: string | null;
     };
-    proposedVia: "mate" | "coordinator" | "scout" | null;
+    proposedVia: import("./scope.js").ScopeAuthor | null;
 };
 export type PlannerContract = {
     /** null: no scope was filed — the title is the only filed intent, and

package/dist/proof.js

@@ -620,6 +620,8 @@ function verificationFailureWords(failure) {
                 return "the retried verification command timed out after automatic recovery";
             case "custody-lost":
                 return "automatic recovery stopped because this worker no longer owned the build";
+            case "coverage-incomplete":
+                return "the release check didn't cover everything it owed, or a required test went missing or was skipped";
             case "timed-out":
                 return "the approved verification command timed out before checks finished";
             case "spawn-failed":