toolroll 0.9.76 → 0.9.78

package/dist/console-chrome.d.ts

@@ -0,0 +1,41 @@
+import { type BrowserProjectState } from "./browser-workspace.js";
+import type { Store } from "./store.js";
+import { type WorkIndexOptions } from "./work-index.js";
+import type { WorkSummaryAccess } from "./work-summary.js";
+import type { WorkspaceRevision } from "./workspace-revision.js";
+export type SidebarProject = {
+    path: string;
+    name: string;
+};
+/** The sidebar's projects with their states (agent-state.ts) for one reader: the page's first read and the summary
+ * room's snapshots are this one function, so the two never disagree. Never marks anything seen. Work with no project
+ * yet is its own entry when this reader may see it and something counts there. */
+export declare function projectSummaryOf(store: Store, now: Date, access: WorkSummaryAccess, actor: string, projects: readonly SidebarProject[], evidenceRoot: string | undefined): BrowserProjectState[];
+/** One access, canonically and in full (every field it has, so a field added later keys too): the same reader and
+ * scope always spell the same key, whatever order its projects came in. */
+export declare function accessKey(access: WorkSummaryAccess): string;
+/**
+ * Values read from the database, each kept while the workspace revision (workspace-revision.ts: every meaningful
+ * commit, from any process, moves it) is the one it was read at, and never past the revision's own clock boundary
+ * (a lease or liveness window ending) or `maxAgeMs`, whichever is first — time alone (an agent going quiet) shows
+ * within that bound. A value is stored under the revision read before it was computed, so a commit that lands while it
+ * is computed only makes it miss sooner. Callers must not change a value they were handed.
+ */
+export declare class RevisionCache {
+    #private;
+    constructor(revision: WorkspaceRevision, clock: () => Date, options?: {
+        maxEntries?: number;
+        maxAgeMs?: number;
+    });
+    /** The value for `key` at the current revision, or undefined. */
+    peek<T>(key: string): T | undefined;
+    /** The cached value, or `compute()` now (stored for the next reader). Errors are never cached. */
+    read<T>(key: string, compute: () => T): T;
+    /** The cached value, or one read asynchronously (a read worker) and stored. A failure answers undefined and leaves
+     * the key empty, so the request thread computes it as before. */
+    fill<T>(key: string, compute: () => Promise<T>): Promise<T | undefined>;
+}
+/** The keys the console's chrome reads are kept under (serve.ts and its read-worker prefetch spell them the same). */
+export declare const countsKey: (access: WorkSummaryAccess) => string;
+export declare const summaryKey: (actor: string, access: WorkSummaryAccess, projects: readonly SidebarProject[]) => string;
+export declare const indexKey: (access: WorkSummaryAccess, options: WorkIndexOptions) => string;

package/dist/console-chrome.js

@@ -0,0 +1,166 @@
+/**
+ * The console's shared chrome (the sidebar's project states, the Tasks count, the crew list): computed at most once
+ * per workspace revision for one reader's exact access, and readable on a read worker (read-executor.ts) as well as on
+ * the request thread. Cache metadata only: nothing here grants access. Every entry's key carries every authorization
+ * input its computation reads (the reader, their admitted projects, whether they see unplaced work, the projects their
+ * sidebar may list), so a value read for one scope is never served to another.
+ */
+import { createHash } from "node:crypto";
+import { NO_COUNTS, projectStates, STATE_WORDS } from "./agent-state.js";
+import { boundProjectSummary } from "./browser-workspace.js";
+import { WORK_INDEX_MAX_LIMIT, workIndexPage } from "./work-index.js";
+/** Tasks the rail lists under a project; the rest are a count that links to the project's tasks. */
+const RAIL_TASKS = 6;
+/** Asks a project names for the chime (its count is complete beyond them). */
+const ASKS_PER_PROJECT = 100;
+/** The sidebar's projects with their states (agent-state.ts) for one reader: the page's first read and the summary
+ * room's snapshots are this one function, so the two never disagree. Never marks anything seen. Work with no project
+ * yet is its own entry when this reader may see it and something counts there. */
+export function projectSummaryOf(store, now, access, actor, projects, evidenceRoot) {
+    const states = new Map(projectStates(store, access, actor, now, evidenceRoot, projects.map(one => one.path)).map(one => [one.repo, one]));
+    // A row that needs a person or failed says what the Tasks list says it needs (its own next step); a row at work says
+    // what its agent did last; a finished one says Done.
+    const asking = [...states.values()].flatMap(one => one.families.slice(0, RAIL_TASKS)).filter(one => one.state === "needs-you" || one.state === "failed").map(one => one.rootId);
+    const needWords = new Map();
+    if (asking.length > 0) {
+        try {
+            // Every row the rail may list, in pages the index allows.
+            for (let at = 0; at < asking.length; at += WORK_INDEX_MAX_LIMIT)
+                for (const item of workIndexPage(store, now, access, { roots: asking.slice(at, at + WORK_INDEX_MAX_LIMIT), limit: WORK_INDEX_MAX_LIMIT, ...(evidenceRoot === undefined ? {} : { root: evidenceRoot }) }).items)
+                    needWords.set(item.rootId, item.status.detail !== "" ? item.status.detail : item.status.label);
+        }
+        catch { /* the rows keep their state's words */ }
+    }
+    // The chime's subjects: an opaque key per obligation and version, scoped to this reader (no words, no ids in it).
+    const keyOf = (...parts) => createHash("sha256").update([actor, ...parts].join("\u0000")).digest("base64url").slice(0, 22);
+    // Newest first, so a new ask always has a key however many older ones wait (those were heard when they were new).
+    const asksOf = (state) => [
+        ...(state?.families ?? []).flatMap(one => one.ask === undefined ? [] : [{ at: one.ask.at, ask: { key: keyOf("task", one.rootId, one.ask.version), task: one.rootId, run: one.ask.run, at: one.ask.at } }]),
+        ...(state?.flowAsks ?? []).map(one => ({ at: one.at, ask: { key: keyOf("flow", one.card, one.stage, one.entry), task: null, run: null, at: one.at } })),
+    ].sort((a, b) => b.at.localeCompare(a.at)).slice(0, ASKS_PER_PROJECT).map(one => one.ask);
+    const railOf = (state) => {
+        const families = state?.families ?? [];
+        const tasks = families.slice(0, RAIL_TASKS).flatMap((one) => {
+            const task = store.getTask(one.rootId);
+            const line = one.state === "needs-you" || one.state === "failed" ? needWords.get(one.rootId) ?? null : one.line;
+            return task === null ? [] : [{ id: one.rootId, title: task.title, href: `/t/${encodeURIComponent(one.rootId)}`, state: one.state, line: line ?? STATE_WORDS[one.state] }];
+        });
+        return { tasks, more: Math.max(0, families.length - RAIL_TASKS), asks: asksOf(state) };
+    };
+    const rows = projects.map(one => {
+        const state = states.get(one.path);
+        return { path: one.path, name: one.name, href: `/work?project=${encodeURIComponent(one.path)}`, state: state?.state ?? "idle", counts: state?.counts ?? { ...NO_COUNTS }, ...railOf(state) };
+    });
+    const unplaced = states.get(null);
+    if (unplaced !== undefined && unplaced.state !== "idle")
+        rows.push({ path: null, name: "No project", href: "/work", state: unplaced.state, counts: unplaced.counts, ...railOf(unplaced) });
+    return boundProjectSummary(rows);
+}
+/** One access, canonically and in full (every field it has, so a field added later keys too): the same reader and
+ * scope always spell the same key, whatever order its projects came in. */
+export function accessKey(access) {
+    const record = access;
+    return JSON.stringify(Object.keys(record).sort().map(name => {
+        const value = record[name];
+        return [name, Array.isArray(value) ? [...new Set(value.map(String))].sort() : value === undefined ? null : value];
+    }));
+}
+/**
+ * Values read from the database, each kept while the workspace revision (workspace-revision.ts: every meaningful
+ * commit, from any process, moves it) is the one it was read at, and never past the revision's own clock boundary
+ * (a lease or liveness window ending) or `maxAgeMs`, whichever is first — time alone (an agent going quiet) shows
+ * within that bound. A value is stored under the revision read before it was computed, so a commit that lands while it
+ * is computed only makes it miss sooner. Callers must not change a value they were handed.
+ */
+export class RevisionCache {
+    #entries = new Map();
+    #revision;
+    #clock;
+    #maxEntries;
+    #maxAgeMs;
+    constructor(revision, clock, options = {}) {
+        this.#revision = revision;
+        this.#clock = clock;
+        this.#maxEntries = options.maxEntries ?? 128;
+        this.#maxAgeMs = options.maxAgeMs ?? 30_000;
+    }
+    /** The value for `key` at the current revision, or undefined. */
+    peek(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        let revision;
+        try {
+            revision = this.#revision.current();
+        }
+        catch {
+            return undefined;
+        }
+        if (entry.revision !== revision || this.#clock().getTime() >= entry.expiresAt) {
+            this.#entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /** The cached value, or `compute()` now (stored for the next reader). Errors are never cached. */
+    read(key, compute) {
+        const hit = this.peek(key);
+        if (hit !== undefined)
+            return hit;
+        const started = this.#started();
+        const value = compute();
+        if (started !== null)
+            this.#store(key, started, value);
+        return value;
+    }
+    /** The cached value, or one read asynchronously (a read worker) and stored. A failure answers undefined and leaves
+     * the key empty, so the request thread computes it as before. */
+    async fill(key, compute) {
+        const hit = this.peek(key);
+        if (hit !== undefined)
+            return hit;
+        const started = this.#started();
+        if (started === null)
+            return undefined;
+        let value;
+        try {
+            value = await compute();
+        }
+        catch {
+            return undefined;
+        }
+        // A worker can finish after an approval changed or a lease expired. Its caller must not pin that old answer
+        // into a request even though the shared cache would reject it on the next lookup.
+        try {
+            if (this.#revision.current() !== started.revision || this.#clock().getTime() >= started.expiresAt)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+        this.#store(key, started, value);
+        return value;
+    }
+    #started() {
+        try {
+            const now = this.#clock();
+            return { revision: this.#revision.current(), expiresAt: Math.min(this.#revision.expiresAt(now), now.getTime() + this.#maxAgeMs) };
+        }
+        catch {
+            return null;
+        }
+    }
+    #store(key, started, value) {
+        this.#entries.delete(key);
+        if (this.#entries.size >= this.#maxEntries)
+            this.#entries.delete(this.#entries.keys().next().value);
+        this.#entries.set(key, { ...started, value });
+    }
+}
+/** The keys the console's chrome reads are kept under (serve.ts and its read-worker prefetch spell them the same). */
+export const countsKey = (access) => `counts\u0000${accessKey(access)}`;
+export const summaryKey = (actor, access, projects) => `summary\u0000${actor}\u0000${accessKey(access)}\u0000${JSON.stringify(projects.map(one => [one.path, one.name]))}`;
+export const indexKey = (access, options) => {
+    const record = options;
+    return `index\u0000${accessKey(access)}\u0000${JSON.stringify(Object.keys(record).sort().map(name => [name, record[name] ?? null]))}`;
+};

package/dist/contracts/console-api.d.ts

@@ -98,7 +98,7 @@ export declare const CONSOLE_FORMS: {
     readonly storage: FormContract<"cleanup" | "password" | "path" | "preview">;
     readonly pullRequests: FormContract<"act" | "base" | "github" | "method" | "password" | "repo" | "when-green">;
     readonly checks: FormContract<"act" | "command" | "level" | "on" | "password" | "repo" | "timeout">;
-    readonly backups: FormContract<"every" | "folder" | "keep" | "password">;
+    readonly backups: FormContract<"every" | "folder" | "keep" | "live_every" | "live_folder" | "password">;
     readonly data: FormContract<"password">;
     readonly flowsOn: FormContract<"repo" | "starter">;
     readonly integrationsTest: FormContract<"key">;

package/dist/contracts/console-api.js

@@ -107,7 +107,7 @@ export const CONSOLE_FORMS = {
     storage: formContract("POST /settings/storage, /settings/storage/clean, /settings/storage/discard", ["password", "cleanup", "preview", "path"]),
     pullRequests: formContract("POST /settings/pull-requests", ["repo", "act", "password", "github", "base", "method", "when-green"]),
     checks: formContract("POST /settings/checks", ["repo", "password", "act", "on", "level", "command", "timeout"]),
-    backups: formContract("POST /settings/backups", ["password", "every", "keep", "folder"]),
+    backups: formContract("POST /settings/backups", ["password", "every", "keep", "folder", "live_every", "live_folder"]),
     data: formContract("POST /settings/data", ["password"]),
     flowsOn: formContract("POST /settings/flows/on", ["repo", "starter"]),
     integrationsTest: formContract("POST /settings/integrations/test", ["key"]),

package/dist/contracts/release-check.d.ts

@@ -43,6 +43,10 @@ export declare const checkReportSchema: z.ZodObject<{
         ran: z.ZodBoolean;
         code: z.ZodNullable<z.ZodInt>;
         timedOut: z.ZodBoolean;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        stopped: z.ZodOptional<z.ZodBoolean>;
+        spawnFailed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     units: z.ZodNullable<z.ZodObject<{
         reusedFromCI: z.ZodBoolean;
@@ -81,6 +85,7 @@ export declare const checkReportSchema: z.ZodObject<{
             scripted: "scripted";
         }>;
         finished: z.ZodBoolean;
+        inventoried: z.ZodOptional<z.ZodBoolean>;
         groups: z.ZodArray<z.ZodObject<{
             group: z.ZodString;
             state: z.ZodEnum<{
@@ -102,6 +107,7 @@ export declare const checkReportSchema: z.ZodObject<{
     }, z.core.$strict>>;
     upgrades: z.ZodNullable<z.ZodObject<{
         finished: z.ZodBoolean;
+        inventoried: z.ZodOptional<z.ZodBoolean>;
         versions: z.ZodArray<z.ZodObject<{
             version: z.ZodString;
             state: z.ZodEnum<{
@@ -130,6 +136,8 @@ export declare const checkInventorySchema: z.ZodObject<{
         unit: "unit";
         upgrade: "upgrade";
     }>>;
+    ciSubstitute: z.ZodOptional<z.ZodBoolean>;
+    release: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type CheckInventory = z.infer<typeof checkInventorySchema>;
 /** The sealed inventory artifact: what was sealed before the run, and what the run declared. */
@@ -148,6 +156,8 @@ export declare const sealedInventorySchema: z.ZodObject<{
             unit: "unit";
             upgrade: "upgrade";
         }>>;
+        ciSubstitute: z.ZodOptional<z.ZodBoolean>;
+        release: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
     declared: z.ZodObject<{
         groups: z.ZodArray<z.ZodObject<{
@@ -229,6 +239,8 @@ export type CheckHandshake = {
     mode: "full" | "targeted";
     plan: TargetedPlan | null;
     watch: string[];
+    owed?: CheckPart[];
+    ciSubstitute?: boolean;
 };
 /** A unit test: its file and full name. */
 export declare const unitIdentity: (file: string, testName: string) => string;

package/dist/contracts/release-check.js

@@ -38,6 +38,12 @@ export const checkReportSchema = versioned(1, {
         ran: z.boolean(),
         code: z.int().min(0).max(255).nullable(),
         timedOut: z.boolean(),
+        /** When it started, the signal that ended it, whether the check stopped it (another part's failure or the check's
+         * own limit) and whether it could start at all — each apart from its code. Absent from an older orchestrator. */
+        startedAt: z.string().max(40).nullable().optional(),
+        signal: z.string().max(20).nullable().optional(),
+        stopped: z.boolean().optional(),
+        spawnFailed: z.boolean().optional(),
     })).max(CHECK_PARTS.length),
     /** The unit suite, from the Vitest main process's fd-3 lines: every file's outcome, and the identities that failed,
      * were skipped, passed on a retry or were asked about. Null when the unit part didn't run. */
@@ -65,6 +71,9 @@ export const checkReportSchema = versioned(1, {
         script: z.enum(JOURNEY_SCRIPTS),
         kind: z.enum(["scripted", "real"]),
         finished: z.boolean(),
+        /** The runner listed its groups before any started (an empty list is an explicit "none of this kind"); absent or
+         * false, the run has no inventory and nothing it lacks can be told from nothing it owed. */
+        inventoried: z.boolean().optional(),
         groups: z.array(z.strictObject({
             group: groupName,
             state: z.enum(["passed", "failed", "not-run"]),
@@ -77,6 +86,8 @@ export const checkReportSchema = versioned(1, {
     })).max(4),
     upgrades: z.strictObject({
         finished: z.boolean(),
+        /** The upgrade path listed its versions before any ran. */
+        inventoried: z.boolean().optional(),
         versions: z.array(z.strictObject({ version: versionName, state: z.enum(["passed", "failed", "not-run"]) })).max(500),
     }).nullable(),
 });
@@ -88,7 +99,13 @@ export function readCheckReport(input) {
  * sealed beside these after it ran. */
 export const checkInventorySchema = versioned(1, {
     units: z.array(repoPath).max(20_000),
+    /** The parts the check owes. For a full check the plane decides them before it runs (check-report.ts
+     * fullObligationsOf) and they ride on the handshake; every one needs an outcome. */
     parts: z.array(z.enum(CHECK_PARTS)).max(CHECK_PARTS.length),
+    /** Whether CI's run of the exact commit may stand in for the local unit suite. Absent is no. */
+    ciSubstitute: z.boolean().optional(),
+    /** Whether the plane prepared it as a release's check (sealed with the attempt; absent on older inventories). */
+    release: z.boolean().optional(),
 });
 /** The sealed inventory artifact: what was sealed before the run, and what the run declared. */
 export const sealedInventorySchema = versioned(1, {

package/dist/contracts/release-terms.d.ts

@@ -64,3 +64,44 @@ export declare function storedReleaseTerms(raw: unknown): {
     ok: false;
     problem: string;
 };
+/**
+ * A release check's purpose (docs/plans/pipeline-speed.md, P0): what a person agrees to when they approve a release
+ * whose later commits can't carry (its checks run outside the sandbox, or carrying is off) — this exact candidate is a
+ * release's check. It never carries a later commit, never lets CI stand in for the check's units and never approves
+ * itself; it lets the plane hold the check to the release's strict report rules and rerun it, on this identical
+ * candidate under this same approval, after a failure the plane itself confirmed as infrastructure. Part of the scope
+ * digest when present; read strictly. A scope carries terms or this purpose, never both.
+ */
+export declare const releaseCheckPurposeSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    purpose: z.ZodLiteral<"release-check">;
+    repo: z.ZodString;
+    packageVersion: z.ZodString;
+    branch: z.ZodString;
+    pr: z.ZodInt;
+    base: z.ZodLiteral<"main">;
+    approvedSha: z.ZodString;
+    approvedTree: z.ZodString;
+    grant: z.ZodObject<{
+        id: z.ZodInt;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    access: z.ZodEnum<{
+        sandboxed: "sandboxed";
+        "sign-ins": "sign-ins";
+        unsandboxed: "unsandboxed";
+    }>;
+}, z.core.$strict>;
+export type ReleaseCheckPurpose = z.infer<typeof releaseCheckPurposeSchema>;
+export declare function readReleaseCheckPurpose(input: unknown): ContractResult<ReleaseCheckPurpose>;
+/** The digest a scope binds for its release check purpose, domain-separated from the terms' and every other input. */
+export declare function releaseCheckPurposeDigest(purpose: ReleaseCheckPurpose): string;
+/** Strict stored purpose: null column → null; anything that isn't exactly a purpose, as written → a problem. */
+export declare function storedReleaseCheckPurpose(raw: unknown): {
+    ok: true;
+    purpose: ReleaseCheckPurpose | null;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function serializeReleaseCheckPurpose(purpose: ReleaseCheckPurpose): string;

package/dist/contracts/release-terms.js

@@ -72,3 +72,56 @@ export function storedReleaseTerms(raw) {
         return { ok: false, problem: "the release terms are not stored exactly as written" };
     return { ok: true, terms: read.value };
 }
+/**
+ * A release check's purpose (docs/plans/pipeline-speed.md, P0): what a person agrees to when they approve a release
+ * whose later commits can't carry (its checks run outside the sandbox, or carrying is off) — this exact candidate is a
+ * release's check. It never carries a later commit, never lets CI stand in for the check's units and never approves
+ * itself; it lets the plane hold the check to the release's strict report rules and rerun it, on this identical
+ * candidate under this same approval, after a failure the plane itself confirmed as infrastructure. Part of the scope
+ * digest when present; read strictly. A scope carries terms or this purpose, never both.
+ */
+export const releaseCheckPurposeSchema = versioned(1, {
+    purpose: z.literal("release-check"),
+    repo: z.string().min(1).max(4096),
+    packageVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
+    branch: z.string().min(1).max(255).regex(/^[A-Za-z0-9._/-]+$/),
+    pr: z.int().min(1),
+    base: z.literal("main"),
+    approvedSha: sha,
+    approvedTree: sha,
+    grant: z.strictObject({ id: z.int(), digest: z.string().min(1).max(128) }),
+    access: z.enum(["sandboxed", "sign-ins", "unsandboxed"]),
+});
+export function readReleaseCheckPurpose(input) {
+    return readVersioned(releaseCheckPurposeSchema, input);
+}
+/** The digest a scope binds for its release check purpose, domain-separated from the terms' and every other input. */
+export function releaseCheckPurposeDigest(purpose) {
+    return createHash("sha256").update(`release-check-purpose:${JSON.stringify(purpose)}`).digest("hex");
+}
+/** Strict stored purpose: null column → null; anything that isn't exactly a purpose, as written → a problem. */
+export function storedReleaseCheckPurpose(raw) {
+    if (raw === null || raw === undefined)
+        return { ok: true, purpose: null };
+    if (typeof raw !== "string")
+        return { ok: false, problem: "the release check purpose is not stored as text" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, problem: "the release check purpose can't be read" };
+    }
+    const read = readReleaseCheckPurpose(parsed);
+    if (!read.ok)
+        return { ok: false, problem: `the release check purpose doesn't match its contract (${read.issues[0]?.line ?? "invalid"})` };
+    if (JSON.stringify(read.value) !== raw)
+        return { ok: false, problem: "the release check purpose is not stored exactly as written" };
+    return { ok: true, purpose: read.value };
+}
+export function serializeReleaseCheckPurpose(purpose) {
+    const read = readReleaseCheckPurpose(purpose);
+    if (!read.ok)
+        throw new Error(`The release check purpose doesn't match its contract: ${read.issues[0]?.line ?? "invalid"}`);
+    return JSON.stringify(read.value);
+}

package/dist/contracts/verification-receipt.d.ts

@@ -13,7 +13,7 @@
  */
 import { z } from "zod";
 import { type ContractResult } from "./contract.js";
-export declare const VERIFICATION_FAILURES: readonly ["spawn-failed", "timed-out", "dependency-missing", "setup-stale", "setup-failed", "own-install-failed", "tracked-files-changed", "setup-changed-files", "checkout-moved", "cleanliness-unavailable", "dependency-still-missing", "retry-spawn-failed", "retry-timed-out", "custody-lost", "coverage-incomplete"];
+export declare const VERIFICATION_FAILURES: readonly ["spawn-failed", "timed-out", "dependency-missing", "setup-stale", "setup-failed", "own-install-failed", "tracked-files-changed", "setup-changed-files", "checkout-moved", "cleanliness-unavailable", "dependency-still-missing", "retry-spawn-failed", "retry-timed-out", "custody-lost", "coverage-incomplete", "no-result", "stopped-by-toolroll", "baseline-unverifiable"];
 /**
  * What the repository's approved verification command did: not configured; configured but the run could not attempt
  * it (`attemptFailed`, which downgrades to `short` rather than `refuted`: "we could not check" is not "the claim is
@@ -26,12 +26,14 @@ export declare const verifyCommandFactsSchema: z.ZodUnion<readonly [z.ZodObject<
     ran: z.ZodLiteral<false>;
     attemptFailed: z.ZodLiteral<true>;
     failure: z.ZodOptional<z.ZodEnum<{
+        "baseline-unverifiable": "baseline-unverifiable";
         "checkout-moved": "checkout-moved";
         "cleanliness-unavailable": "cleanliness-unavailable";
         "coverage-incomplete": "coverage-incomplete";
         "custody-lost": "custody-lost";
         "dependency-missing": "dependency-missing";
         "dependency-still-missing": "dependency-still-missing";
+        "no-result": "no-result";
         "own-install-failed": "own-install-failed";
         "retry-spawn-failed": "retry-spawn-failed";
         "retry-timed-out": "retry-timed-out";
@@ -39,6 +41,7 @@ export declare const verifyCommandFactsSchema: z.ZodUnion<readonly [z.ZodObject<
         "setup-failed": "setup-failed";
         "setup-stale": "setup-stale";
         "spawn-failed": "spawn-failed";
+        "stopped-by-toolroll": "stopped-by-toolroll";
         "timed-out": "timed-out";
         "tracked-files-changed": "tracked-files-changed";
     }>>;
@@ -47,6 +50,11 @@ export declare const verifyCommandFactsSchema: z.ZodUnion<readonly [z.ZodObject<
     ran: z.ZodLiteral<true>;
     exitCode: z.ZodInt;
     setupReplayed: z.ZodOptional<z.ZodLiteral<true>>;
+    firstAttempt: z.ZodOptional<z.ZodObject<{
+        class: z.ZodLiteral<"launch">;
+        program: z.ZodString;
+        exitCode: z.ZodInt;
+    }, z.core.$strict>>;
 }, z.core.$strict>]>;
 export type VerifyCommandFacts = z.infer<typeof verifyCommandFactsSchema>;
 /** The approved verification grant the gate ran, exactly as the store held it. */
@@ -76,7 +84,7 @@ export declare const receiptLogSchema: z.ZodObject<{
     }>>;
 }, z.core.$strict>;
 export declare const RECEIPT_VERSION = 3;
-export declare const RECEIPT_COVERAGES: readonly ["full", "composed", "partial", "identity-removed"];
+export declare const RECEIPT_COVERAGES: readonly ["full", "composed", "partial", "identity-removed", "no-result"];
 export type ReceiptCoverage = typeof RECEIPT_COVERAGES[number];
 /** The receipt as read: a reused gate names its source run and digest; a direct one names neither. */
 export declare const verificationReceiptSchema: z.ZodObject<{
@@ -109,12 +117,14 @@ export declare const verificationReceiptSchema: z.ZodObject<{
         ran: z.ZodLiteral<false>;
         attemptFailed: z.ZodLiteral<true>;
         failure: z.ZodOptional<z.ZodEnum<{
+            "baseline-unverifiable": "baseline-unverifiable";
             "checkout-moved": "checkout-moved";
             "cleanliness-unavailable": "cleanliness-unavailable";
             "coverage-incomplete": "coverage-incomplete";
             "custody-lost": "custody-lost";
             "dependency-missing": "dependency-missing";
             "dependency-still-missing": "dependency-still-missing";
+            "no-result": "no-result";
             "own-install-failed": "own-install-failed";
             "retry-spawn-failed": "retry-spawn-failed";
             "retry-timed-out": "retry-timed-out";
@@ -122,6 +132,7 @@ export declare const verificationReceiptSchema: z.ZodObject<{
             "setup-failed": "setup-failed";
             "setup-stale": "setup-stale";
             "spawn-failed": "spawn-failed";
+            "stopped-by-toolroll": "stopped-by-toolroll";
             "timed-out": "timed-out";
             "tracked-files-changed": "tracked-files-changed";
         }>>;
@@ -130,6 +141,11 @@ export declare const verificationReceiptSchema: z.ZodObject<{
         ran: z.ZodLiteral<true>;
         exitCode: z.ZodInt;
         setupReplayed: z.ZodOptional<z.ZodLiteral<true>>;
+        firstAttempt: z.ZodOptional<z.ZodObject<{
+            class: z.ZodLiteral<"launch">;
+            program: z.ZodString;
+            exitCode: z.ZodInt;
+        }, z.core.$strict>>;
     }, z.core.$strict>]>;
     log: z.ZodObject<{
         artifactId: z.ZodInt;
@@ -147,6 +163,7 @@ export declare const verificationReceiptSchema: z.ZodObject<{
         composed: "composed";
         full: "full";
         "identity-removed": "identity-removed";
+        "no-result": "no-result";
         partial: "partial";
     }>>;
     check: z.ZodOptional<z.ZodObject<{
@@ -157,6 +174,7 @@ export declare const verificationReceiptSchema: z.ZodObject<{
         report: z.ZodNullable<z.ZodString>;
         inventory: z.ZodNullable<z.ZodString>;
         exitCode: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
+        retried: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strict>>;
     composed: z.ZodOptional<z.ZodObject<{
         base: z.ZodInt;

package/dist/contracts/verification-receipt.js

@@ -30,6 +30,12 @@ export const VERIFICATION_FAILURES = [
     "custody-lost",
     // A release check that didn't cover what it owed, or lost a required test (release-once.md): never a pass.
     "coverage-incomplete",
+    // A Full release check with no complete, valid result (check-report.ts fullCheckProblem): an error, never a pass.
+    "no-result",
+    // Toolroll's own shutdown stopped the check (its hard stop): it never finished.
+    "stopped-by-toolroll",
+    // A Full check whose recorded last release couldn't be verified: what it owed is unknown, so it never ran.
+    "baseline-unverifiable",
 ];
 /**
  * What the repository's approved verification command did: not configured; configured but the run could not attempt
@@ -39,7 +45,10 @@ export const VERIFICATION_FAILURES = [
 export const verifyCommandFactsSchema = z.union([
     z.strictObject({ configured: z.literal(false) }),
     z.strictObject({ configured: z.literal(true), ran: z.literal(false), attemptFailed: z.literal(true), failure: z.enum(VERIFICATION_FAILURES).optional() }),
-    z.strictObject({ configured: z.literal(true), ran: z.literal(true), exitCode: z.int().min(0).max(255), setupReplayed: z.literal(true).optional() }),
+    z.strictObject({ configured: z.literal(true), ran: z.literal(true), exitCode: z.int().min(0).max(255), setupReplayed: z.literal(true).optional(),
+        // The first attempt of a check rerun after the approved setup, classified on its own (eval-harness review 2,
+        // finding 5): only a launch failure — its program missing — is ever replayed.
+        firstAttempt: z.strictObject({ class: z.literal("launch"), program: z.string().min(1).max(200), exitCode: z.int().min(0).max(255) }).optional() }),
 ]);
 /** The approved verification grant the gate ran, exactly as the store held it. */
 export const receiptCommandSchema = z.strictObject({
@@ -65,7 +74,7 @@ export const receiptLogSchema = z.strictObject({
     captureStatus: z.enum(["ok", "failed"]).nullable(),
 });
 export const RECEIPT_VERSION = 3;
-export const RECEIPT_COVERAGES = ["full", "composed", "partial", "identity-removed"];
+export const RECEIPT_COVERAGES = ["full", "composed", "partial", "identity-removed", "no-result"];
 const receiptFields = {
     run: z.int(),
     head: z.string(),
@@ -85,7 +94,10 @@ export const verificationReceiptSchema = versioned(RECEIPT_VERSION, {
     /** Version 3: the attempt sealed before the check ran, and its sealed report (null: it gave none). */
     check: z.strictObject({ attempt: z.enum(["full", "targeted"]), report: z.string().nullable(), inventory: z.string().nullable(),
         /** The command's own exit, kept here when `result` reads a failed attempt because the coverage fell short. */
-        exitCode: z.int().min(0).max(255).nullable().optional() }).optional(),
+        exitCode: z.int().min(0).max(255).nullable().optional(),
+        /** What passed only on a retry inside the check (check-failure.ts retriedInside), sealed here from its report: null
+         * when it gave no valid report, so nobody can tell (unknown, never "no retries"). Absent on older receipts. */
+        retried: z.array(z.string().min(1).max(800)).max(6000).nullable().optional() }).optional(),
     /** Version 3, composed: the full check A and every link the reader proves again. */
     composed: z.strictObject({
         base: z.int().min(1), baseReceipt: z.string(), baseReport: z.string(), authority: z.int().min(1), carries: z.array(z.int()),

package/dist/contracts/verification-view.d.ts

@@ -37,12 +37,14 @@ export declare const legacyGateViewSchema: z.ZodObject<{
         ran: z.ZodLiteral<false>;
         attemptFailed: z.ZodLiteral<true>;
         failure: z.ZodOptional<z.ZodEnum<{
+            "baseline-unverifiable": "baseline-unverifiable";
             "checkout-moved": "checkout-moved";
             "cleanliness-unavailable": "cleanliness-unavailable";
             "coverage-incomplete": "coverage-incomplete";
             "custody-lost": "custody-lost";
             "dependency-missing": "dependency-missing";
             "dependency-still-missing": "dependency-still-missing";
+            "no-result": "no-result";
             "own-install-failed": "own-install-failed";
             "retry-spawn-failed": "retry-spawn-failed";
             "retry-timed-out": "retry-timed-out";
@@ -50,6 +52,7 @@ export declare const legacyGateViewSchema: z.ZodObject<{
             "setup-failed": "setup-failed";
             "setup-stale": "setup-stale";
             "spawn-failed": "spawn-failed";
+            "stopped-by-toolroll": "stopped-by-toolroll";
             "timed-out": "timed-out";
             "tracked-files-changed": "tracked-files-changed";
         }>>;
@@ -58,6 +61,11 @@ export declare const legacyGateViewSchema: z.ZodObject<{
         ran: z.ZodLiteral<true>;
         exitCode: z.ZodInt;
         setupReplayed: z.ZodOptional<z.ZodLiteral<true>>;
+        firstAttempt: z.ZodOptional<z.ZodObject<{
+            class: z.ZodLiteral<"launch">;
+            program: z.ZodString;
+            exitCode: z.ZodInt;
+        }, z.core.$strict>>;
     }, z.core.$strict>]>;
     log: z.ZodObject<{
         artifactId: z.ZodInt;

package/dist/controller-service.js

@@ -8,7 +8,10 @@ const stop = () => stopping.abort();
 process.on("SIGTERM", stop);
 process.on("SIGINT", stop);
 try {
-    await superviseController({ file, argv, signal: stopping.signal, onState: state => {
+    // A stop is forwarded to the controller (SIGTERM) and waited for. Past 55 s its whole tree is stopped outright: before
+    // launchd's own ExitTimeOut (60 s) kills this process and could leave the controller running without it. `up` signs
+    // off within 50 s at its default grace and stops itself if this process dies first (operate.ts upCommand).
+    await superviseController({ file, argv, signal: stopping.signal, shutdownMs: 55_000, onState: state => {
             if (state.phase === "backoff")
                 process.stderr.write(`Controller exited (${state.exit?.signal ?? state.exit?.code ?? "unknown"}); restart in ${state.retryMs} ms.\n`);
         } });

package/dist/controller-supervisor.d.ts

@@ -1,3 +1,4 @@
+import { type ChildProcess } from "node:child_process";
 export type ControllerState = {
     phase: "starting" | "running" | "backoff" | "stopped";
     generation: number;
@@ -27,4 +28,11 @@ export declare function superviseController(args: {
     maxRetryMs?: number;
     stableMs?: number;
     shutdownMs?: number;
+    /** An IPC channel to each controller (fd 3), for a parent that speaks to it (`toolroll up`'s console and worker). */
+    ipc?: boolean;
+    /** Prefix every line the controller writes, sent to this process's stderr: two controllers' logs stay apart. An
+     * empty label sends its lines there unprefixed (a JSON log keeps one object a line). */
+    label?: string;
+    /** Each spawned controller's handle, before it runs: the caller listens to its messages and may signal it. */
+    onSpawn?: (child: ChildProcess, generation: number) => void;
 }): Promise<void>;