toolroll 0.9.92 → 0.9.94

package/dist/check-only.js

@@ -0,0 +1,99 @@
+/**
+ * Automatic recheck under a check-only authorization (docs/plans/plain-toolroll.md P2.2).
+ *
+ * When a build finishes, the approval that built its commit writes one authorization: this task, this exact commit, the
+ * approved check command's digest, the access the build's own check had, one automatic run, and an expiry. It never
+ * seals anything and starts no build and no agent: it asks the follow-up check road (result-follow-ups.ts), which checks
+ * the commit out in a fresh folder and runs the approved command, nothing else.
+ *
+ * The sweep uses it only when the result's verdict is missing or unreadable. A failed, passed or running check needs
+ * nothing, and closes it. The claim (used_at, compare-and-swap in the transaction that asks) is the cap: a second worker
+ * or a crash after the claim finds it spent, and the need stays with the person. A changed command is a different
+ * digest, so the old authorization covers nothing: Run checks on the new command is the person's act.
+ */
+import { assignmentChecksForRun } from "./assignment.js";
+import { runCheckLevel, repoOfRun, checkCommandFor } from "./check-levels.js";
+import { approvedScopeStands, authorizationProblem, readAuthorization } from "./check-only-standing.js";
+import { requestFollowUpChecks } from "./result-follow-ups.js";
+import { releaseCheckScope } from "./scope.js";
+import { refArchived } from "./task-archive.js";
+import { approvedCheckStateOf } from "./task-status.js";
+/** How long a recheck may still start after its build finished. */
+export const CHECK_ONLY_WINDOW_MS = 24 * 60 * 60_000;
+export const RECHECK_ACTOR = "Toolroll";
+/**
+ * Written only from the existing approval of this exact commit: the seal this run was admitted under, still standing,
+ * on the bytes this run built. Null when anything is missing, and the person's Run checks stays the only road.
+ */
+export function authorizeCheckOnly(store, runId, now) {
+    return store.transact(() => {
+        const run = store.getRun(runId);
+        if (run === null || run.role !== "builder" || run.outcome !== "built" || run.headRevision === null || !/^[a-f0-9]{40}$/.test(run.headRevision))
+            return null;
+        const ref = store.refById(run.taskRef);
+        if (ref === null || ref.repo === null || refArchived(store, ref.id))
+            return null;
+        const scope = store.getScope(ref.externalId);
+        if (scope === null || scope.approvedDigest !== scope.digest || run.scopeDigest !== scope.digest)
+            return null;
+        // A release's check has its own road (check-failure.ts), and the nightly's its own.
+        if (releaseCheckScope(scope) || scope.releaseTerms != null)
+            return null;
+        if (!approvedScopeStands(store, ref.id, scope.digest, now))
+            return null;
+        const level = runCheckLevel(store, runId);
+        if (level === "off")
+            return null;
+        const chosen = checkCommandFor(store, ref.repo, level ?? "full");
+        if (chosen.command === null || chosen.level === "off")
+            return null;
+        const written = store.handle.prepare(`INSERT INTO check_authorization (task_ref, run, candidate, command_digest, level, check_access, scope_digest, written_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (task_ref, candidate, command_digest) DO NOTHING`)
+            .run(ref.id, runId, run.headRevision, chosen.command.digest, chosen.level, store.runCheckAccess(runId), scope.digest, now.toISOString(), new Date(now.getTime() + CHECK_ONLY_WINDOW_MS).toISOString());
+        return Number(written.changes) > 0 ? Number(written.lastInsertRowid) : null;
+    });
+}
+/** Claim one authorization and ask for its check, in one transaction. Null: nothing was asked. */
+export function claimRecheck(store, authorization, now) {
+    return store.transact(() => {
+        const row = store.handle.prepare("SELECT * FROM check_authorization WHERE id = ? AND used_at IS NULL AND closed_at IS NULL AND expires_at > ?").get(authorization, now.toISOString());
+        if (row === undefined)
+            return null;
+        const auth = readAuthorization(row);
+        const run = store.getRun(auth.run);
+        const repo = repoOfRun(store, auth.run);
+        if (run === null || repo === null || store.lastBuilderRun(auth.taskRef)?.id !== auth.run || store.hasLiveClaim(auth.taskRef, now))
+            return null;
+        const live = checkCommandFor(store, repo, auth.level).command;
+        if (live === null || authorizationProblem(store, auth, { head: run.headRevision ?? "", digest: live.digest }, now) !== null)
+            return null;
+        const asked = requestFollowUpChecks(store, { runId: auth.run, level: auth.level, actor: RECHECK_ACTOR, why: "recheck" }, now);
+        // An existing request is the person's own: it stands, and this authorization isn't spent on it.
+        if (!asked.ok || asked.existing)
+            return null;
+        const spent = store.handle.prepare("UPDATE check_authorization SET used_at = ?, used_request = ? WHERE id = ? AND used_at IS NULL").run(now.toISOString(), asked.request, auth.id);
+        if (Number(spent.changes) !== 1)
+            throw new Error("the recheck's authorization moved inside its own transaction");
+        return { request: asked.request };
+    });
+}
+/** Each sweep: a standing authorization whose result has no readable verdict asks for its one check. */
+export function requestMissingRechecks(store, root, now) {
+    const open = store.handle.prepare("SELECT * FROM check_authorization WHERE used_at IS NULL AND closed_at IS NULL AND expires_at > ? ORDER BY id").all(now.toISOString());
+    let asked = 0;
+    for (const row of open) {
+        const auth = readAuthorization(row);
+        const run = store.getRun(auth.run);
+        if (run === null || run.finishedAt === null)
+            continue;
+        const state = approvedCheckStateOf(assignmentChecksForRun(store, root, auth.run, now));
+        if (state === "not-run" || state === "unreadable") {
+            if (claimRecheck(store, auth.id, now) !== null)
+                asked++;
+            continue;
+        }
+        if (state !== "running")
+            store.handle.prepare("UPDATE check_authorization SET closed_at = ? WHERE id = ? AND used_at IS NULL").run(now.toISOString(), auth.id);
+    }
+    return asked;
+}

package/dist/check-report.d.ts

@@ -88,6 +88,8 @@ export type PreparedAttempt = {
     snapshot: ObligationSnapshot | null;
     /** The identities the check was asked to report one by one (required ones). */
     watch: string[];
+    /** The exact cases the check was asked about for learning only (docs/plans/learning-loops.md): never gate evidence. */
+    learn: string[];
 };
 /** A Full check's preparation refused (eval-harness review 2, finding 4): the plane recorded a release whose commit it
  * can't verify now, so the check's obligations can't be decided. The check isn't run (builder.ts: `baseline-unverifiable`). */
@@ -112,6 +114,11 @@ export declare function prepareCheckAttempt(store: Store, root: string, input: {
     /** A release's check (signed release terms or a release authority): CI never stands in for its unit suite. Sealed in
      * the inventory (whose digest the attempt row holds); only an explicit false lets CI stand in. */
     release?: boolean;
+    /** Exact cases asked about for learning only (docs/plans/learning-loops.md): a separate handshake field, at most 200,
+     * that never joins `watch`, the inventory or anything the check owes. */
+    learn?: readonly string[];
+    /** The limit the check runs under when the plane gave it more than the approved one (check-load.ts checkLimitFor). */
+    limitMs?: number | undefined;
 }, now: Date): PreparedAttempt | null;
 /** Seal one JSON payload as a structured-output artifact under its capture label. */
 export declare function sealJson(store: Store, root: string, runId: number, name: string, value: unknown, capture: string, now: Date): number;

package/dist/check-report.js

@@ -21,7 +21,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { lstatSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { readVerifiedCommit, verifiedBlobs, verifiedTreeEntries } from "./commit-extract.js";
-import { CHECK_PARTS, CHECK_REPORT_MAX_BYTES, CHECK_REPORT_PREFIX, readCheckReport, } from "./contracts/release-check.js";
+import { CHECK_PARTS, CHECK_REPORT_MAX_BYTES, CHECK_REPORT_PREFIX, learnRequest, readCheckReport, } from "./contracts/release-check.js";
 import { readVerifiedArtifact, storeEvidence } from "./evidence.js";
 import { releaseBaselineRecord } from "./release-card.js";
 import { checkAttemptOf, recordCheckAttempt } from "./store.js";
@@ -219,8 +219,9 @@ export function prepareCheckAttempt(store, root, input, now) {
     // The command's own limit rides along, so the check ends itself (logs and report printed) before the plane stops it.
     // `reportBytes`: the largest report this plane reads back once sealed. A plane that doesn't say (0.9.77 and older) reads
     // only 64 KiB, so the check gives it no larger report rather than one that poisons the receipt (scripts/release-check.mjs).
-    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])], limitMs: input.command.timeoutMs, reportBytes: CHECK_ARTIFACT_CAP, ...(plan === null ? { owed, ciSubstitute } : {}) });
-    return { runId: input.runId, nonce, stdin, mode, inventory, context, plan, snapshot, watch: [...(input.watch ?? [])] };
+    const learn = learnRequest(input.learn ?? []);
+    const stdin = JSON.stringify({ nonce, mode, plan, watch: [...(input.watch ?? [])], limitMs: Number.isSafeInteger(input.limitMs) && input.limitMs >= input.command.timeoutMs ? input.limitMs : input.command.timeoutMs, reportBytes: CHECK_ARTIFACT_CAP, ...(plan === null ? { owed, ciSubstitute } : {}), ...(learn.length > 0 ? { learn } : {}) });
+    return { runId: input.runId, nonce, stdin, mode, inventory, context, plan, snapshot, watch: [...(input.watch ?? [])], learn };
 }
 /** Seal one JSON payload as a structured-output artifact under its capture label. */
 export function sealJson(store, root, runId, name, value, capture, now) {

package/dist/check-stamp.d.ts

@@ -0,0 +1,46 @@
+import { type CheckAccess } from "./check-access.js";
+export declare const CHECK_STAMP_VERSION = 1;
+/** Every path: the launch had no write or read fence of that kind. */
+export declare const EVERYWHERE = "*";
+/** What the launch's network was: the machine's own, or the fence's, with exactly the hosts it allowed. */
+export type StampNetwork = {
+    mode: "machine";
+} | {
+    mode: "open" | "allowlist";
+    hosts: string[];
+};
+export type CheckStamp = {
+    version: typeof CHECK_STAMP_VERSION;
+    /** The level the commands ran at, whatever was sealed. */
+    level: CheckAccess;
+    /** The digest of the whole fence as given to the launch (invoke.ts fenceDigest); null with no fence. */
+    policyDigest: string | null;
+    /** Where it could write: exact grants, or [EVERYWHERE]. */
+    writable: string[];
+    /** What it was given to read beyond the fence's denies, or [EVERYWHERE]. */
+    readable: string[];
+    network: StampNetwork;
+};
+export type StampReading = {
+    state: "current";
+    stamp: CheckStamp;
+} | {
+    state: "unknown";
+    why: "missing" | "old" | "unreadable";
+};
+/** A launch with no fence at all. */
+export declare const unfencedStamp: () => CheckStamp;
+export declare const stampDigest: (stamp: CheckStamp) => string;
+/** One saved stamp, exactly its shape or unknown. */
+export declare function readStamp(text: unknown): StampReading;
+/**
+ * A run's whole account of its checks: every launch it stamped. Any it can't read makes the whole unknown (one launch of
+ * unknown reach is reach unknown); otherwise the widest stands, so a narrow command never hides a wider one. None: unknown.
+ */
+export declare function readStamps(texts: readonly unknown[]): StampReading;
+/** Why relying on `reading` for a check that had to stay within `sealed` isn't possible, or null when it can be. */
+export declare function stampRefusal(reading: StampReading, sealed: CheckAccess): string | null;
+/** How a check ran, as a person reads it after the fact; null for a current sandboxed one, which needs no line. */
+export declare function ranWords(reading: StampReading): string | null;
+/** v154: one row per distinct launch of a run's commands (a run's repeats of one launch are one row). */
+export declare const V154_SCHEMA = "\nCREATE TABLE IF NOT EXISTS check_stamp (\n  id      INTEGER PRIMARY KEY,\n  run_id  INTEGER NOT NULL,\n  digest  TEXT NOT NULL,\n  stamp   TEXT NOT NULL,\n  at      TEXT NOT NULL,\n  UNIQUE (run_id, digest)\n);\n";

package/dist/check-stamp.js

@@ -0,0 +1,93 @@
+/**
+ * A check's execution stamp (docs/plans/trusted-release-reports.md, H2): what actually ran, written at launch by the code
+ * that launched it. Before this, a run's `sandbox_access` was all there was, and a missing or unreadable value read as
+ * "sandboxed". That reading is right for one thing only, choosing how a later check may run (narrowest), and wrong for
+ * saying how a check DID run. Anything that relies on how a check ran reads a stamp here: a missing, old or damaged one
+ * is `unknown`, which refuses where it matters and is never said to be sandboxed.
+ *
+ * Reading a stamp is strict, and a new shape takes a new version: an older build's stamp is `unknown` to a newer one.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonical-json.js";
+import { isCheckAccess, widerThan } from "./check-access.js";
+export const CHECK_STAMP_VERSION = 1;
+/** Every path: the launch had no write or read fence of that kind. */
+export const EVERYWHERE = "*";
+/** A launch with no fence at all. */
+export const unfencedStamp = () => ({ version: CHECK_STAMP_VERSION, level: "unsandboxed", policyDigest: null, writable: [EVERYWHERE], readable: [EVERYWHERE], network: { mode: "machine" } });
+export const stampDigest = (stamp) => createHash("sha256").update(`toolroll:check-stamp:${canonicalJson(stamp)}`).digest("hex").slice(0, 32);
+const paths = (value) => Array.isArray(value) && value.every(one => typeof one === "string" && one !== "");
+const networkIs = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const one = value;
+    if (one["mode"] === "machine")
+        return Object.keys(one).length === 1;
+    return (one["mode"] === "open" || one["mode"] === "allowlist") && paths(one["hosts"]) && Object.keys(one).length === 2;
+};
+/** One saved stamp, exactly its shape or unknown. */
+export function readStamp(text) {
+    if (typeof text !== "string")
+        return { state: "unknown", why: "missing" };
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { state: "unknown", why: "unreadable" };
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return { state: "unknown", why: "unreadable" };
+    const one = value;
+    if (one["version"] !== CHECK_STAMP_VERSION)
+        return { state: "unknown", why: typeof one["version"] === "number" ? "old" : "unreadable" };
+    const digest = one["policyDigest"];
+    const whole = isCheckAccess(one["level"]) && (digest === null || (typeof digest === "string" && /^[0-9a-f]{32}$/.test(digest)))
+        && paths(one["writable"]) && paths(one["readable"]) && networkIs(one["network"]) && Object.keys(one).length === 6;
+    if (!whole)
+        return { state: "unknown", why: "unreadable" };
+    // No fence and a narrow level can't both be true: a stamp that says so is damaged.
+    if (digest === null && one["level"] !== "unsandboxed")
+        return { state: "unknown", why: "unreadable" };
+    return { state: "current", stamp: value };
+}
+/**
+ * A run's whole account of its checks: every launch it stamped. Any it can't read makes the whole unknown (one launch of
+ * unknown reach is reach unknown); otherwise the widest stands, so a narrow command never hides a wider one. None: unknown.
+ */
+export function readStamps(texts) {
+    if (texts.length === 0)
+        return { state: "unknown", why: "missing" };
+    let widest = null;
+    for (const text of texts) {
+        const one = readStamp(text);
+        if (one.state === "unknown")
+            return one;
+        if (widest === null || widerThan(one.stamp.level, widest.level))
+            widest = one.stamp;
+    }
+    return { state: "current", stamp: widest };
+}
+/** Why relying on `reading` for a check that had to stay within `sealed` isn't possible, or null when it can be. */
+export function stampRefusal(reading, sealed) {
+    if (reading.state === "unknown")
+        return reading.why === "old" ? "its check's record is from an older Toolroll, so how it ran can't be shown" : "how its check ran wasn't recorded";
+    return widerThan(reading.stamp.level, sealed) ? `its check ran ${reading.stamp.level}, wider than the ${sealed} it was approved for` : null;
+}
+/** How a check ran, as a person reads it after the fact; null for a current sandboxed one, which needs no line. */
+export function ranWords(reading) {
+    if (reading.state === "unknown")
+        return "How these checks ran wasn't recorded";
+    return reading.stamp.level === "sandboxed" ? null : reading.stamp.level === "unsandboxed" ? "Checks ran without a sandbox" : "Checks ran with model and GitHub sign-ins";
+}
+/** v154: one row per distinct launch of a run's commands (a run's repeats of one launch are one row). */
+export const V154_SCHEMA = `
+CREATE TABLE IF NOT EXISTS check_stamp (
+  id      INTEGER PRIMARY KEY,
+  run_id  INTEGER NOT NULL,
+  digest  TEXT NOT NULL,
+  stamp   TEXT NOT NULL,
+  at      TEXT NOT NULL,
+  UNIQUE (run_id, digest)
+);
+`;

package/dist/checkout-cleanup.d.ts

@@ -1,11 +1,13 @@
-import { type CheckoutCleanup } from "./storage.js";
-import type { Store, WorktreeRow } from "./store.js";
+import { type CheckoutCleanup, type CheckoutIdle } from "./storage.js";
+import { type Store, type WorktreeRow } from "./store.js";
 import { type WorktreePool } from "./worktree.js";
 /** A release candidate's checkout holds the build a deploy installs: the newest complete one waits at most a week for it. */
 export declare const CANDIDATE_KEEP_MS: number;
 /** The worker's pass removes at most this many; a clean-up by hand has no cap. */
 export declare const AUTO_MAX = 20;
-export type KeepWhy = "in use" | "task not finished" | "waiting for review" | "release candidate" | "has changes" | "has commits" | "unreadable" | "git refused" | "not due yet" | "cleanup is off" | "no task";
+export type KeepWhy = "in use" | "task not finished" | "waiting for review" | "release candidate" | "has changes" | "has commits" | "not on its branch" | "unreadable" | "git refused" | "not due yet" | "cleanup is off" | "no task"
+/** A clean-up by hand leaves it; the next sweep takes it. */
+ | "idle";
 export type CheckoutItem = {
     path: string;
     repo: string;
@@ -17,10 +19,13 @@ export type CheckoutItem = {
     why: KeepWhy | null;
     /** With "not due yet" or "release candidate": when it may go. */
     dueAt?: string;
+    /** Past the idle limit: when its task last saw any activity. */
+    idleSince?: string;
 };
 export type CheckoutPlan = {
     at: string;
     cleanup: CheckoutCleanup;
+    idle: CheckoutIdle;
     manual: boolean;
     go: CheckoutItem[];
     stay: CheckoutItem[];
@@ -30,6 +35,9 @@ export type CheckoutPlan = {
     freeBytes: number;
     waitingReview: number;
     withChanges: number;
+    /** What the next sweep's idle cleanup takes. */
+    idleCount: number;
+    idleBytes: number;
 };
 type Status = {
     keep: KeepWhy | null;
@@ -64,6 +72,21 @@ export declare function finishedCheckouts(store: Store, now: Date, repo?: string
     taskId: string | null;
     finishedAt: string;
 }[];
+/** The newest activity of a task's whole family, and whether something rules idle cleanup out for it. */
+type IdleFact = {
+    activeAt: string;
+    blocked: boolean;
+};
+export type IdleFacts = {
+    byRef: Map<number, IdleFact>;
+    byBranch: Map<string, IdleFact>;
+};
+/**
+ * When each task family last saw a run, a person's act or a lease, read in one pass. A revision builds on what it
+ * revises, so a family is idle together. `blocked`: an open run, an unreleased claim, a release gate, or a task only an
+ * external tracker knows, in the family.
+ */
+export declare function idleFacts(store: Store): IdleFacts;
 /** Why a checkout stays as a clean-up by hand reads it (in use, or its task not done with it), before its files; null: it may go. */
 export declare function checkoutKeepWhy(pool: WorktreePool, row: WorktreeRow, statuses: ReturnType<typeof taskStatuses>, now: Date): KeepWhy | null;
 /**
@@ -83,11 +106,15 @@ export type CleanResult = {
         why: KeepWhy;
     }[];
     freed: number;
+    /** The worker's pass stopped at AUTO_MAX: more may be due, and the sweep comes back an hour later. */
+    more?: boolean;
 };
 /**
  * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
  * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
- * the ledger.
+ * the ledger. Idle checkouts go only with `idle`, the storage sweep's child (never the service's own pass, whose git
+ * and du must not hold up its heartbeats): each is judged again from a fresh read of its task and its family's
+ * activity, `spare` (live work), the OS's list of what runs in the folder, and `proveRecreatable`, inside its reservation.
  */
 export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: () => Date, options: {
     manual: boolean;
@@ -95,6 +122,10 @@ export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: ()
     repo?: string;
     only?: ReadonlySet<string>;
     spare?: (path: string) => boolean;
+    /** The storage sweep's child only: idle checkouts go too. `occupied` asks the OS whether any process works in a folder. */
+    idle?: {
+        occupied: (path: string) => boolean;
+    };
 }): Promise<CleanResult>;
 export type SlimResult = {
     slimmed: {
@@ -122,5 +153,5 @@ export declare function discardCheckout(store: Store, pool: WorktreePool, path:
     message: string;
 }>;
 /** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
-export declare function whyWords(item: Pick<CheckoutItem, "why" | "dueAt">): string;
+export declare function whyWords(item: Pick<CheckoutItem, "why" | "dueAt" | "idleSince">): string;
 export {};