tickmarkr 2.6.6 → 2.6.7

package/dist/gates/test-manifest.d.ts

@@ -87,6 +87,14 @@ export declare function verifyManifestReport(opts: {
 /** How much longer than its baseline measurement one file may legitimately run before it is a hang. */
 export declare const FILE_HANG_SLACK = 3;
 export declare const DEFAULT_FILE_HANG_BUDGET_MS = 60000;
+/**
+ * No file is a hang before this much active time, whatever its baseline says (the battery ceiling still wins below it). A fast
+ * suite's per-file timings are a few ms, so 3 × longest killed a new or slower file that would have passed, or a scheduling gap, as an infra hang.
+ */
+export declare const MIN_FILE_HANG_BUDGET_MS = 10000;
+/** Tests of the baseline-derived budget's kill mechanics opt out of the floor; production never does. */
+export declare const setHangBudgetFloorForTests: (ms: number) => void;
+export declare const resetHangBudgetFloorForTests: () => void;
 export declare function fileHangBudgetMs(file: string, baselineDurations?: readonly BaselineFileDuration[] | null, ceilingMs?: number, longestFile?: BaselineFileDuration | null): number;
 /**
  * OBS-953 (+add): a per-file hang budget counted in raw wall time charged a lid-close to the file that

package/dist/gates/test-manifest.js

@@ -4,6 +4,7 @@ import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileS
 import { tmpdir } from "node:os";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { performance } from "node:perf_hooks";
+import { verificationPhase, withVerificationJob } from "../run/verification-job.js";
 import { TEST_REPORTER_SOURCE } from "./test-reporter.js";
 import { shq } from "../adapters/types.js";
 import { beginGateEvidence, redactGateOutput } from "./baseline.js";
@@ -329,6 +330,15 @@ export function verifyManifestReport(opts) {
 /** How much longer than its baseline measurement one file may legitimately run before it is a hang. */
 export const FILE_HANG_SLACK = 3;
 export const DEFAULT_FILE_HANG_BUDGET_MS = 60_000;
+/**
+ * No file is a hang before this much active time, whatever its baseline says (the battery ceiling still wins below it). A fast
+ * suite's per-file timings are a few ms, so 3 × longest killed a new or slower file that would have passed, or a scheduling gap, as an infra hang.
+ */
+export const MIN_FILE_HANG_BUDGET_MS = 10_000;
+let hangBudgetFloorMs = MIN_FILE_HANG_BUDGET_MS;
+/** Tests of the baseline-derived budget's kill mechanics opt out of the floor; production never does. */
+export const setHangBudgetFloorForTests = (ms) => { hangBudgetFloorMs = ms; };
+export const resetHangBudgetFloorForTests = () => { hangBudgetFloorMs = MIN_FILE_HANG_BUDGET_MS; };
 const usable = (n) => n !== undefined && Number.isFinite(n) && n > 0;
 export function fileHangBudgetMs(file, baselineDurations, ceilingMs = DEFAULT_FILE_HANG_BUDGET_MS, longestFile) {
     const ceiling = usable(ceilingMs) ? ceilingMs : DEFAULT_FILE_HANG_BUDGET_MS;
@@ -336,7 +346,10 @@ export function fileHangBudgetMs(file, baselineDurations, ceilingMs = DEFAULT_FI
     const longest = Math.max(0, ...timings.map((d) => d.durationMs), usable(longestFile?.durationMs) ? longestFile.durationMs : 0);
     if (!longest)
         return ceiling;
-    const known = timings.find((d) => d.file === file)?.durationMs;
+    // A file that was RED in the baseline ended early there: its duration is no measure of its green runtime. The
+    // failure is read from EVERY entry, before the usable-duration filter can drop a 0 ms or non-finite red one.
+    const red = baselineDurations?.some((d) => d.file === file && d.failed) ?? false;
+    const known = red ? undefined : timings.find((d) => d.file === file)?.durationMs;
     return Math.min(ceiling, known === undefined ? FILE_HANG_SLACK * longest : Math.max(FILE_HANG_SLACK * known, longest));
 }
 /**
@@ -401,7 +414,7 @@ export function runManifestedTest(cmd, cwd, opts) {
             const startedAt = report.started[file];
             if (startedAt === undefined || file in report.completed)
                 continue;
-            const budget = fileHangBudgetMs(file, opts.baselineDurations, overallCeilingMs, opts.longestFile);
+            const budget = Math.min(overallCeilingMs, Math.max(hangBudgetFloorMs, fileHangBudgetMs(file, opts.baselineDurations, overallCeilingMs, opts.longestFile)));
             const wallMs = at.wall - startedAt;
             const activeMs = wallMs - suspendedSince(interruptions, startedAt);
             if (activeMs >= budget || (atCeiling && budget === overallCeilingMs)) {
@@ -532,9 +545,14 @@ function strandedSingleForkFiles(files, nonce, run) {
     const parallel = files.filter(f => !scheduling[f].singleFork);
     if (!single.length || !parallel.length || single.some(f => Object.hasOwn(r.started, f) || Object.hasOwn(r.completed, f)))
         return;
-    if (parallel.some(f => !Object.hasOwn(r.started, f)
-        || !["passed", "skipped"].includes(r.completed[f]?.status ?? "")
-        || (r.completed[f]?.tests?.failed ?? 0) !== 0))
+    if (parallel.some(f => {
+        const completion = r.completed[f];
+        if (!Object.hasOwn(r.started, f) || !completion)
+            return true;
+        if (completion.status === "failed")
+            return !completion.failures?.length || !(completion.tests && completion.tests.failed > 0);
+        return !["passed", "skipped"].includes(completion.status) || (completion.tests?.failed ?? 0) !== 0;
+    }))
         return;
     return single;
 }
@@ -561,115 +579,137 @@ export async function evaluateManifestedTest(cmd, cwd, opts) {
     const dir = opts.artifactDir ?? mkdtempSync(join(tmpdir(), "tickmarkr-test-report-"));
     let nonce = randomBytes(16).toString("hex");
     let reportPath = join(dir, `test-manifest-report-${nonce}.json`);
-    const reporterPath = join(dir, `test-reporter-${nonce}.mjs`);
-    const evidenceReceipts = [];
-    let spawnedCommand = cmd;
-    let manifestPath;
-    let recovery;
-    const { env, verification } = manifestEnvironment(cwd);
     try {
-        const invocation = await discoverTestManifest(cmd, cwd, { dir, nonce, env, overallCeilingMs: opts.overallCeilingMs, evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir } });
-        evidenceReceipts.push(...invocation.evidenceReceipts);
-        const files = invocation.files;
-        // R41: the EXPECTED manifest is evidence in its own right — persisted beside the report with the
-        // exact discovery invocation, so a later reader can tell what this invocation was asked to prove
-        // without reconstructing it from the runner's own claims.
-        manifestPath = join(dir, `test-manifest-expected-${nonce}.json`);
-        writeFileSync(manifestPath, JSON.stringify({
-            nonce, verification, listingCommand: invocation.listing, listingExit: invocation.listingExit,
-            listingStdoutSha256: createHash("sha256").update(invocation.listingStdout).digest("hex"),
-            discoveredAt: Date.now(), files,
-        }, null, 2) + "\n");
-        writeFileSync(reporterPath, TEST_REPORTER_SOURCE);
-        spawnedCommand = `${cmd}${invocation.separator} --reporter=${shq(reporterPath)} --outputFile=${shq(reportPath)}`;
-        let invoked = await runManifestedTest(spawnedCommand, cwd, {
-            evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir }, manifest: files, nonce, reportPath, env,
-            baselineDurations: opts.baselineDurations?.map((d) => ({ ...d, file: toManifestPath(d.file, cwd) })),
-            longestFile: opts.longestFile,
-            overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS,
-            pollMs: 20,
-        });
-        let verdict = verifyManifestReport({ manifest: files, nonce, exitCode: invoked.exitCode,
-            report: invoked.report, killedFile: invoked.killedFile, hangBudgetMs: invoked.hangBudgetMs,
-            hangActiveMs: invoked.hangActiveMs, hangWallMs: invoked.hangWallMs });
-        evidenceReceipts.push(...invoked.evidenceReceipts);
-        const interruptions = [...invoked.interruptions];
-        const stranded = opts.allowStrandedRecovery === false ? undefined : strandedSingleForkFiles(files, nonce, invoked);
-        if (stranded) {
-            const first = invoked.report;
-            const retryNonce = randomBytes(16).toString("hex");
-            recovery = { firstNonce: nonce, firstReportPath: reportPath, retryNonce, files: stranded };
-            nonce = retryNonce;
-            reportPath = join(dir, `test-manifest-report-${nonce}.json`);
-            const retryCommand = singleForkRetryCommand(opts.retryBaseCommand ?? cmd, cwd, stranded, files.filter(f => !stranded.includes(f)));
-            const listed = await discoverTestManifest(retryCommand, cwd, { dir, nonce, env,
-                overallCeilingMs: opts.overallCeilingMs, evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir } });
-            evidenceReceipts.push(...listed.evidenceReceipts);
-            if (listed.files.length !== stranded.length || listed.files.some(f => !stranded.includes(f)))
-                throw new Error("single fork retry discovery does not match the stranded set");
-            writeFileSync(join(dir, `test-manifest-expected-${nonce}.json`), JSON.stringify({ nonce, files: stranded,
-                firstNonce: recovery.firstNonce, listingCommand: listed.listing, verification }, null, 2) + "\n");
-            spawnedCommand = `${retryCommand}${listed.separator} --reporter=${shq(reporterPath)} --outputFile=${shq(reportPath)}`;
-            invoked = await runManifestedTest(spawnedCommand, cwd, {
-                evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir }, manifest: stranded, nonce, reportPath, env,
-                baselineDurations: opts.baselineDurations?.map(d => ({ ...d, file: toManifestPath(d.file, cwd) })),
-                longestFile: opts.longestFile, overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS, pollMs: 20,
-            });
-            evidenceReceipts.push(...invoked.evidenceReceipts);
-            interruptions.push(...invoked.interruptions);
-            verdict = verifyManifestReport({ manifest: stranded, nonce, exitCode: invoked.exitCode,
-                report: invoked.report, killedFile: invoked.killedFile, hangBudgetMs: invoked.hangBudgetMs,
-                hangActiveMs: invoked.hangActiveMs, hangWallMs: invoked.hangWallMs });
-            // An all-skipped retry may contribute lifecycle accounting, but only the combined manifest
-            // can establish executed success. Never rewrite either invocation's persisted certificate.
-            if (verdict.pass || verdict.meta.noExecutedModules) {
-                const retry = invoked.report;
-                if (retry.certificate?.errors !== 0 || !Array.isArray(retry.certificate.diagnostics) || retry.certificate.diagnostics.length)
-                    verdict = { kind: "fail-closed", pass: false, details: "single fork retry has unknown or nonempty runner diagnostics", meta: { classification: "infra", infra: true } };
-                else
-                    verdict = verifyManifestReport({ manifest: files, nonce, exitCode: invoked.exitCode, report: {
-                            ...retry, requested: files, started: { ...first.started, ...retry.started }, completed: { ...first.completed, ...retry.completed },
-                        } });
+        return await withVerificationJob(cmd, cwd, reportPath, opts.evidence, async () => {
+            const reporterPath = join(dir, `test-reporter-${nonce}.mjs`);
+            const evidenceReceipts = [];
+            let spawnedCommand = cmd;
+            let manifestPath;
+            let retainedFirstVerdict;
+            let recovery;
+            const { env, verification } = manifestEnvironment(cwd);
+            try {
+                const invocation = await verificationPhase("discovery", `${nonce}-listing`, join(dir, `listing-${nonce}.json`), () => discoverTestManifest(cmd, cwd, { dir, nonce, env, overallCeilingMs: opts.overallCeilingMs, evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir } }));
+                evidenceReceipts.push(...invocation.evidenceReceipts);
+                const files = invocation.files;
+                // R41: the EXPECTED manifest is evidence in its own right — persisted beside the report with the
+                // exact discovery invocation, so a later reader can tell what this invocation was asked to prove
+                // without reconstructing it from the runner's own claims.
+                manifestPath = join(dir, `test-manifest-expected-${nonce}.json`);
+                writeFileSync(manifestPath, JSON.stringify({
+                    nonce, verification, listingCommand: invocation.listing, listingExit: invocation.listingExit,
+                    listingStdoutSha256: createHash("sha256").update(invocation.listingStdout).digest("hex"),
+                    discoveredAt: Date.now(), files,
+                }, null, 2) + "\n");
+                writeFileSync(reporterPath, TEST_REPORTER_SOURCE);
+                spawnedCommand = `${cmd}${invocation.separator} --reporter=${shq(reporterPath)} --outputFile=${shq(reportPath)}`;
+                let invoked = await verificationPhase("first-pass", nonce, reportPath, () => runManifestedTest(spawnedCommand, cwd, {
+                    evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir }, manifest: files, nonce, reportPath, env,
+                    baselineDurations: opts.baselineDurations?.map((d) => ({ ...d, file: toManifestPath(d.file, cwd) })),
+                    longestFile: opts.longestFile,
+                    overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS,
+                    pollMs: 20,
+                }));
+                let verdict = verifyManifestReport({ manifest: files, nonce, exitCode: invoked.exitCode,
+                    report: invoked.report, killedFile: invoked.killedFile, hangBudgetMs: invoked.hangBudgetMs,
+                    hangActiveMs: invoked.hangActiveMs, hangWallMs: invoked.hangWallMs });
+                evidenceReceipts.push(...invoked.evidenceReceipts);
+                const interruptions = [...invoked.interruptions];
+                const stranded = opts.allowStrandedRecovery === false ? undefined : strandedSingleForkFiles(files, nonce, invoked);
+                if (stranded) {
+                    const first = invoked.report;
+                    if (verdict.kind === "work")
+                        retainedFirstVerdict = verdict;
+                    const retryNonce = randomBytes(16).toString("hex");
+                    recovery = { firstNonce: nonce, firstReportPath: reportPath, retryNonce, files: stranded };
+                    nonce = retryNonce;
+                    reportPath = join(dir, `test-manifest-report-${nonce}.json`);
+                    const retryCommand = singleForkRetryCommand(opts.retryBaseCommand ?? cmd, cwd, stranded, files.filter(f => !stranded.includes(f)));
+                    const listed = await verificationPhase("continuation-discovery", `${nonce}-listing`, join(dir, `listing-${nonce}.json`), () => discoverTestManifest(retryCommand, cwd, { dir, nonce, env,
+                        overallCeilingMs: opts.overallCeilingMs, evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir } }), recovery.firstNonce);
+                    evidenceReceipts.push(...listed.evidenceReceipts);
+                    if (listed.files.length !== stranded.length || listed.files.some(f => !stranded.includes(f)))
+                        throw new Error("single fork retry discovery does not match the stranded set");
+                    writeFileSync(join(dir, `test-manifest-expected-${nonce}.json`), JSON.stringify({ nonce, files: stranded,
+                        firstNonce: recovery.firstNonce, listingCommand: listed.listing, verification }, null, 2) + "\n");
+                    spawnedCommand = `${retryCommand}${listed.separator} --reporter=${shq(reporterPath)} --outputFile=${shq(reportPath)}`;
+                    invoked = await verificationPhase("continuation", nonce, reportPath, () => runManifestedTest(spawnedCommand, cwd, {
+                        evidence: { ...opts.evidence, artifactDir: opts.evidence?.artifactDir ?? dir }, manifest: stranded, nonce, reportPath, env,
+                        baselineDurations: opts.baselineDurations?.map(d => ({ ...d, file: toManifestPath(d.file, cwd) })),
+                        longestFile: opts.longestFile, overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS, pollMs: 20,
+                    }), recovery.firstNonce);
+                    evidenceReceipts.push(...invoked.evidenceReceipts);
+                    interruptions.push(...invoked.interruptions);
+                    verdict = verifyManifestReport({ manifest: stranded, nonce, exitCode: invoked.exitCode,
+                        report: invoked.report, killedFile: invoked.killedFile, hangBudgetMs: invoked.hangBudgetMs,
+                        hangActiveMs: invoked.hangActiveMs, hangWallMs: invoked.hangWallMs });
+                    // An all-skipped retry may contribute lifecycle accounting, but only the combined manifest
+                    // can establish executed success. Never rewrite either invocation's persisted certificate.
+                    if (verdict.pass || verdict.meta.noExecutedModules) {
+                        const retry = invoked.report;
+                        if (retry.certificate?.errors !== 0 || !Array.isArray(retry.certificate.diagnostics) || retry.certificate.diagnostics.length)
+                            verdict = { kind: "fail-closed", pass: false, details: "single fork retry has unknown or nonempty runner diagnostics", meta: { classification: "infra", infra: true } };
+                        else
+                            verdict = verifyManifestReport({ manifest: files, nonce, exitCode: invoked.exitCode, report: {
+                                    ...retry, requested: files, started: { ...first.started, ...retry.started }, completed: { ...first.completed, ...retry.completed },
+                                } });
+                    }
+                    const firstFailures = verifyManifestReport({ manifest: files, nonce: recovery.firstNonce, exitCode: 1, report: first });
+                    if (firstFailures.kind === "work")
+                        verdict = { ...firstFailures,
+                            details: `${firstFailures.details}\ncontinuation: ${verdict.details}`,
+                            meta: { ...firstFailures.meta, continuation: verdict.meta,
+                                failingTests: [...new Set([...firstFailures.meta.failingTests, ...(verdict.meta.failingTests ?? [])])],
+                                failingFiles: [...new Set([...firstFailures.meta.failingFiles, ...(verdict.meta.failingFiles ?? [])])],
+                                failureEvidence: [...firstFailures.meta.failureEvidence, ...(verdict.meta.failureEvidence ?? [])] } };
+                    verdict.details = `single fork retry ${nonce} after worker RPC timeout in ${recovery.firstNonce}: ${verdict.details}`;
+                }
+                // Preserve the validator's verdict and classification; runner evidence only explains it.
+                const evidenceReceipt = invoked.evidenceReceipt;
+                const evidenceRoot = opts.evidence?.artifactDir ?? dir;
+                const stdoutPath = join(evidenceRoot, evidenceReceipt.stdout.path);
+                const stderrPath = join(evidenceRoot, evidenceReceipt.stderr.path);
+                const stdoutTail = Buffer.from(redactGateOutput(invoked.stdout, env)).subarray(-16 * 1024);
+                const stderrTail = Buffer.from(redactGateOutput(invoked.stderr, env)).subarray(-16 * 1024);
+                const report = invoked.report?.nonce === nonce ? invoked.report : undefined;
+                const neverStarted = report ? files.filter(file => !(file in report.started)).length : "unknown";
+                const errors = report?.certificate?.errors;
+                const reporterErrors = typeof errors === "number" && Number.isInteger(errors) && errors >= 0 ? errors : "unknown";
+                const reportedDiagnostics = report?.certificate?.diagnostics;
+                const runnerErrors = Array.isArray(reportedDiagnostics) ? reportedDiagnostics.filter(error => typeof error === "string") : [];
+                const diagnostics = !verdict.pass
+                    ? `\nclassification: ${verdict.meta.classification ?? "unknown"}; runner-level diagnostic: never-started ${neverStarted}; reporter errors ${reporterErrors}; runner vitest`
+                        + [...runnerErrors,
+                            stdoutTail.toString(), stderrTail.toString()].filter(Boolean).map(text => `\n${text}`).join("")
+                    : "";
+                // The interruption is reported beside the verdict, never folded into it or into raw wall service.
+                const interrupted = interruptions.length
+                    ? `\nhost interruptions: ${interruptions.map(i => `${i.kind} ${Math.round(i.wallMs)}ms wall / ${Math.round(i.monoMs)}ms monotonic, ${Math.round(i.subtractedMs)}ms subtracted`).join("; ")}`
+                    : "";
+                return { evidenceReceipt, evidenceReceipts, pass: verdict.pass, kind: verdict.kind,
+                    details: verdict.details + interrupted + diagnostics,
+                    classification: verdict.meta.classification,
+                    meta: { ...verdict.meta, nonce, manifest: files, manifestPath, listingCommand: invocation.listing, verification,
+                        ...(recovery ? { recovery, retryable: false } : {}), ...(interruptions.length ? { interruptions } : {}),
+                        spawnedCommand, processExit: invoked.exitCode, pid: invoked.pid, stdoutPath, stderrPath },
+                    exitCode: invoked.exitCode ?? -1, reportPath };
             }
-            verdict.details = `single fork retry ${nonce} after worker RPC timeout in ${recovery.firstNonce}: ${verdict.details}`;
-        }
-        // Preserve the validator's verdict and classification; runner evidence only explains it.
-        const evidenceReceipt = invoked.evidenceReceipt;
-        const evidenceRoot = opts.evidence?.artifactDir ?? dir;
-        const stdoutPath = join(evidenceRoot, evidenceReceipt.stdout.path);
-        const stderrPath = join(evidenceRoot, evidenceReceipt.stderr.path);
-        const stdoutTail = Buffer.from(redactGateOutput(invoked.stdout, env)).subarray(-16 * 1024);
-        const stderrTail = Buffer.from(redactGateOutput(invoked.stderr, env)).subarray(-16 * 1024);
-        const report = invoked.report?.nonce === nonce ? invoked.report : undefined;
-        const neverStarted = report ? files.filter(file => !(file in report.started)).length : "unknown";
-        const errors = report?.certificate?.errors;
-        const reporterErrors = typeof errors === "number" && Number.isInteger(errors) && errors >= 0 ? errors : "unknown";
-        const reportedDiagnostics = report?.certificate?.diagnostics;
-        const runnerErrors = Array.isArray(reportedDiagnostics) ? reportedDiagnostics.filter(error => typeof error === "string") : [];
-        const diagnostics = !verdict.pass
-            ? `\nclassification: ${verdict.meta.classification ?? "unknown"}; runner-level diagnostic: never-started ${neverStarted}; reporter errors ${reporterErrors}; runner vitest`
-                + [...runnerErrors,
-                    stdoutTail.toString(), stderrTail.toString()].filter(Boolean).map(text => `\n${text}`).join("")
-            : "";
-        // The interruption is reported beside the verdict, never folded into it or into raw wall service.
-        const interrupted = interruptions.length
-            ? `\nhost interruptions: ${interruptions.map(i => `${i.kind} ${Math.round(i.wallMs)}ms wall / ${Math.round(i.monoMs)}ms monotonic, ${Math.round(i.subtractedMs)}ms subtracted`).join("; ")}`
-            : "";
-        return { evidenceReceipt, evidenceReceipts, pass: verdict.pass, kind: verdict.kind,
-            details: verdict.details + interrupted + diagnostics,
-            classification: verdict.meta.classification,
-            meta: { ...verdict.meta, nonce, manifest: files, manifestPath, listingCommand: invocation.listing, verification,
-                ...(recovery ? { recovery, retryable: false } : {}), ...(interruptions.length ? { interruptions } : {}),
-                spawnedCommand, processExit: invoked.exitCode, pid: invoked.pid, stdoutPath, stderrPath },
-            exitCode: invoked.exitCode ?? -1, reportPath };
+            catch (error) {
+                const evidenceReceipt = error?.evidenceReceipt;
+                if (evidenceReceipt)
+                    evidenceReceipts.push(...(error.evidenceReceipts ?? [evidenceReceipt]));
+                return { evidenceReceipt, evidenceReceipts, pass: false, kind: retainedFirstVerdict ? "work" : "infra", classification: retainedFirstVerdict ? "regression" : "infra", exitCode: -1, reportPath,
+                    details: (retainedFirstVerdict ? `${retainedFirstVerdict.details}\n` : "") + (recovery ? `single fork retry ${recovery.retryNonce} after ${recovery.firstNonce}: ` : "") + (error instanceof Error ? error.message : String(error)),
+                    meta: { ...(retainedFirstVerdict?.meta ?? { classification: "infra", infra: true }), ...(retainedFirstVerdict ? { firstPass: retainedFirstVerdict.meta } : {}), manifestDiscoveryFailed: true, spawnedCommand, verification,
+                        ...(recovery ? { recovery, retryable: false } : {}), ...(manifestPath ? { manifestPath } : {}) } };
+            }
+        });
     }
     catch (error) {
-        const evidenceReceipt = error?.evidenceReceipt;
-        if (evidenceReceipt)
-            evidenceReceipts.push(...(error.evidenceReceipts ?? [evidenceReceipt]));
-        return { evidenceReceipt, evidenceReceipts, pass: false, kind: "infra", classification: "infra", exitCode: -1, reportPath,
-            details: (recovery ? `single fork retry ${recovery.retryNonce} after ${recovery.firstNonce}: ` : "") + (error instanceof Error ? error.message : String(error)),
-            meta: { classification: "infra", infra: true, manifestDiscoveryFailed: true, spawnedCommand, verification,
-                ...(recovery ? { recovery, retryable: false } : {}), ...(manifestPath ? { manifestPath } : {}) } };
+        const job = error;
+        return { pass: false, kind: "infra", classification: "infra", exitCode: -1, reportPath,
+            details: error instanceof Error ? error.message : String(error),
+            meta: { infra: true, classification: "infra", retryable: false,
+                verificationJobPath: job.verificationJobPath, verificationJob: job.verificationJob } };
     }
 }

package/dist/run/beat-lifecycle.d.ts

@@ -0,0 +1,154 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { type SupervisionArm, type SupervisionTier } from "./supervision.js";
+/** start's whole budget — launch, read-back and any overrun — before it must refuse and roll back. */
+export declare const BEAT_STARTUP_CEILING_MS = 60000;
+/** The generation a started child carries; it lets the child act under its launcher's claim only. */
+export declare const BEAT_GENERATION_ENV = "TICKMARKR_BEAT_GENERATION";
+export interface ProcessIdentity {
+    birth: string;
+    command: string;
+    cwd: string;
+    pgid: number;
+}
+export type IdentityRead = ProcessIdentity | "DEAD" | "UNKNOWN";
+/** Every boundary the lifecycle crosses, injectable so failures are exercised where they really occur. */
+export interface BeatLifecycleDeps {
+    /** Command prefix that re-executes this same CLI (node, its flags, the entry the launcher ran). */
+    cli: readonly string[];
+    spawn: (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+    kill: (pid: number, signal: NodeJS.Signals) => void;
+    identity: (pid: number) => IdentityRead;
+    openLog: (path: string) => number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    env: NodeJS.ProcessEnv;
+}
+export declare function defaultBeatDeps(): BeatLifecycleDeps;
+/** A named, nonzero refusal: dispatch renders the message and exits 1. */
+export declare class BeatRefusal extends Error {
+}
+/**
+ * The live process behind a pid: birth (lstart), full argv, cwd and process group. A missing process is
+ * DEAD only when the kernel says so (ESRCH or a zombie); anything unreadable is UNKNOWN, never DEAD.
+ */
+export declare function readProcessIdentity(pid: number): IdentityRead;
+export declare const beatClaimPath: (repoRoot: string, tier: SupervisionTier) => string;
+export declare const beatOwnerPath: (repoRoot: string, tier: SupervisionTier) => string;
+export declare const beatLogPath: (repoRoot: string, tier: SupervisionTier) => string;
+/**
+ * The exact generation start launched. pid/birth/command/pgid are absent only while it is launching;
+ * priorArmId/priorArmEpoch name the (already fenced) arm on disk at launch, which the child's own arm then
+ * replaces; armEpoch is bound from the exact child's checked beat, and ownership is the COMPLETE durable arm
+ * generation (armId AND armEpoch) — a same-id arm with another epoch is a replacement.
+ */
+export interface BeatOwner {
+    tier: SupervisionTier;
+    seat: string;
+    generation: string;
+    armId: string;
+    cwd: string;
+    startedAt: string;
+    armEpoch?: string;
+    priorArmId?: string;
+    priorArmEpoch?: string;
+    pid?: number;
+    birth?: string;
+    command?: string;
+    pgid?: number;
+}
+type Read<T> = T | "NONE" | "UNREADABLE";
+export declare function readBeatOwner(repoRoot: string, tier: SupervisionTier): Read<BeatOwner>;
+/** Atomic first-writer-wins claim; a held claim is BUSY and is never taken over. */
+export declare function acquireBeatClaim(repoRoot: string, tier: SupervisionTier, token: string): void;
+export declare function releaseBeatClaim(repoRoot: string, tier: SupervisionTier, token: string): void;
+/**
+ * A legacy writer: the launch generation it carries (if any), its seat, the arm a running loop holds, and the
+ * boundaries its checks read through.
+ */
+export interface LegacyWriter {
+    generation?: string;
+    seat: string;
+    settled?: boolean;
+    arm?: SupervisionArm;
+    deps: BeatLifecycleDeps;
+}
+/**
+ * The recheck a legacy write calls immediately before it mutates; `arm` is the arm the writer itself holds, and
+ * `created` says this writer published that arm under this claim a moment ago (an owned re-arm).
+ */
+export type LegacyRecheck = (arm?: SupervisionArm, created?: boolean) => void;
+/**
+ * Run one legacy write (one-shot tick, new arm, EVERY loop tick, stand-down) under the tier claim. A launched
+ * child acts under its launcher's claim while that claim is still held for its generation; afterwards it takes
+ * the tier claim itself like every other writer. `act` receives the recheck it must call immediately before it
+ * writes: the claim still names this holder and the tier's ownership still admits this writer. A claim held by
+ * anyone else refuses with nothing written — `waits` only lets a running loop's tick outlast a brief holder.
+ */
+export declare function withLegacyClaim<T>(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter, act: (recheck: LegacyRecheck) => T | Promise<T>, waits?: {
+    tries: number;
+    sleep: (ms: number) => Promise<void>;
+}): Promise<T>;
+/** The ownership a legacy writer needs before each mutation: its own COMPLETE launched generation, or no owner at all. */
+export declare function assertLegacyOwnership(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter, arm?: SupervisionArm, created?: boolean, held?: BeatOwner): BeatOwner | undefined;
+/**
+ * ONE RULE: every legacy write is preceded by the shared complete owned-generation check of the CURRENT owner
+ * record and durable arm against the EXACT generation this writer holds — token, seat, pid (once settled), armId
+ * and armEpoch. `held` is the owner this claim's previous check validated and `arm` the arm the writer holds (a
+ * loop's own arm; before the launcher binds the epoch that arm is the evidence). The first check of a claim by a
+ * writer holding neither takes the generation on record; from then on the held generation changes in exactly
+ * two verified ways, and any other change — also one between this check's own reads — refuses with no write:
+ *  (i) the writer's OWN re-arm (`created`: it published `arm` under this claim after the complete check): the
+ *      arm on disk must be exactly that arm and the owner exactly the owner checked before the arm write; only
+ *      then is the owner rebound to the arm (same token, seat, process), and the complete check runs AGAIN as
+ *      the new generation before the beat. After any mismatch the owner is never rewritten.
+ * (ii) the launcher completing an UNBOUND owner for this writer (launcherBound) — never adopted from disk.
+ * Once `settled` (past its first beat) the record must name its pid: a launch that refused without proving it
+ * could signal its child leaves no pid behind, and that child retires itself.
+ */
+export declare function assertOwnedGeneration(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter & {
+    generation: string;
+}, arm?: SupervisionArm | undefined, created?: boolean, held?: BeatOwner, pid?: number): BeatOwner;
+export type CheckedBeat = {
+    kind: "EMPTY";
+} | {
+    kind: "DISARMED";
+    seat?: string;
+} | {
+    kind: "OWN-LIVE";
+    owner: BeatOwner & {
+        pid: number;
+    };
+    advancing: boolean;
+} | {
+    kind: "OWN-DEAD";
+    owner: BeatOwner & {
+        pid: number;
+    };
+} | {
+    kind: "FOREIGN";
+    reason: string;
+} | {
+    kind: "PID-REUSED";
+    owner: BeatOwner & {
+        pid: number;
+    };
+} | {
+    kind: "UNKNOWN";
+    reason: string;
+};
+/**
+ * The checked state of one tier, read-only: no claim, no write, no signal. Every authoritative record —
+ * owner, marker, beat and durable arm — is validated before any outcome is selected, and ownership binds to
+ * this repository's canonical root, the recorded seat and the recorded arm before the process is consulted.
+ */
+export declare function inspectBeat(repoRoot: string, tier: SupervisionTier, seat: string | undefined, deps: BeatLifecycleDeps): CheckedBeat;
+/** Status: the recorded liveness, rendered without writing; healthy states exit 0, the rest nonzero. */
+export declare function beatStatus(repoRoot: string, tier: SupervisionTier, seat: string | undefined, deps: BeatLifecycleDeps): {
+    out: string;
+    code: number;
+};
+/** start: one claim, one child; exit zero only after this exact child's own advancing beat reads back. */
+export declare function startBeat(repoRoot: string, tier: SupervisionTier, seat: string, deps: BeatLifecycleDeps): Promise<string>;
+/** stop: retire only the recorded generation, signalling its exact pid, then read back DISARMED. */
+export declare function stopBeat(repoRoot: string, tier: SupervisionTier, seat: string, deps: BeatLifecycleDeps): Promise<string>;
+export {};