tickmarkr 2.6.7 → 2.6.9

package/dist/gates/run-gates.js

@@ -9,7 +9,8 @@ import { GATE_NAMES } from "../graph/schema.js";
 import { acceptanceGate } from "./acceptance.js";
 import { classifiedFileDurations, compareToBaseline, effectiveCeilingMs, waitForCalmWindow, calmWindowReady } from "./baseline.js";
 import { evidenceGate } from "./evidence.js";
-import { captureLlmOutput } from "./llm.js";
+import { captureLlmOutput, SeatLaunchError } from "./llm.js";
+import { withLaunchGuard } from "../drivers/orca.js";
 import { disallowedBy, observedSeat } from "../route/preference.js";
 import { marginalCostRank } from "../route/router.js";
 import { carriedAuthorVendors, gateReviewerFloor, pickReviewer, reviewGate } from "./review.js";
@@ -1243,27 +1244,66 @@ export async function runGates(task, ctx) {
         // seat spends two invocations, and one blended span cannot tell a slow reviewer from two.
         // A pick that found NO eligible seat dispatched nothing, so it contributes no invocation.
         const invocations = [];
+        const retiredNow = () => [...(ctx.reviewNoVerdicts ?? [])].filter(([, causes]) => causes.length >= 2).map(([seat]) => seat);
+        // v2.6.8 T1: retirement is live through the LAUNCH, not only the pick. reviewGate awaits its diff read
+        // after it picks, and a pane seat awaits its slot, so another task can retire the picked seat inside
+        // either await. The seat is named when its command is built and checked against the live tally there and
+        // again as its pane is bound (onSlot runs inside llm.ts's launch guard, which closes that pane unrun), and
+        // a driver that still awaits lookups before it submits the terminal (Orca's runtime probe and worktree
+        // lookup) re-reads it at that submission (withLaunchGuard): a retired seat is never launched, and dispatch
+        // picks again under the live exclusions (atPick) — the next eligible seat, or none. Bounded: each
+        // withdrawal is a seat newly retired, and the pool is finite.
+        let launching = {};
+        const refuseRetired = () => {
+            if (launching.seat === undefined || !retiredNow().includes(launching.seat))
+                return;
+            launching.withdrawn = true;
+            throw new SeatLaunchError(launching.seat, new Error("retired for the run before it launched"));
+        };
+        const reviewVia = via && { ...via, onSlot: (slot) => { via.onSlot?.(slot); refuseRetired(); } };
+        const guarded = (adapter) => new Proxy(adapter, {
+            get(target, property) {
+                if (property === "headlessCommand") {
+                    return (promptFile, model, effort) => {
+                        launching.seat = channelKey({ adapter: target.id, model });
+                        refuseRetired();
+                        return target.headlessCommand(promptFile, model, effort);
+                    };
+                }
+                const value = Reflect.get(target, property, target);
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        });
         // Dispatch is PROVEN, never inferred: captureLlmOutput records one output per runLlm return, so an
         // empty capture means reviewGate returned before asking anyone — a policy skip, a pre-dispatch diff
         // cap, or no eligible seat. Reading `noEligibleReviewer` alone missed the first two and invented
         // an "unknown" span for each.
         const dispatch = async (run) => {
-            const captured = await captureLlmDispatches(ctx.adapters, run);
-            invocations.push(...captured.invocations);
-            const rv = captured.value;
+            const withdrawn = [];
+            let picked;
+            for (;;) {
+                launching = {};
+                const captured = await withLaunchGuard(refuseRetired, () => captureLlmDispatches(ctx.adapters.map(guarded), run));
+                invocations.push(...captured.invocations);
+                picked = captured.value;
+                if (cancelled || !launching.withdrawn)
+                    break;
+                withdrawn.push(launching.seat);
+            }
+            const rv = withdrawn.length === 0 ? picked : { ...picked, details: `${withdrawn.map((seat) => `review dispatch withdrawn: ${seat} was retired for the run (two real no-verdicts) after it was picked, before it launched; picked again`).join("\n")}\n${picked.details}` };
             if (cancelled)
                 return rv; // a cancelled seat's non-answer says nothing about the seat
             if (rv.meta?.noVerdict === true || rv.meta?.unparseable === true) {
                 await ctx.onGate?.({ phase: "note", gate: "review", name: "review-no-verdict", payload: { ...rv.meta }, result: rv });
-                if (typeof rv.meta.reviewer === "string") {
+                // v2.6.8 T1: a seat that never LAUNCHED (any launchCause, checkout-proof-timeout or none) said
+                // nothing about the work or about itself: no run-scoped strike and no soft demotion. It gets one
+                // bounded same-seat launch retry below and is excluded for the rest of THIS round only.
+                if (typeof rv.meta.reviewer === "string" && rv.meta.cause !== "seat-launch-failed") {
                     const reviewer = rv.meta.reviewer;
                     const cause = String(rv.meta.cause);
-                    // E1: a checkout-proof timeout is the host being slow to print the seat's proof, not the seat
-                    // failing. It is still a no-verdict re-routed away from for THIS round, but it never strikes the
-                    // run-scoped tally; every other launch failure (foreign or malformed proof included) does.
-                    const proofTimeout = cause === "seat-launch-failed" && rv.meta.launchCause === "checkout-proof-timeout";
-                    // OBS-1025 add.2: the run-scoped tally; two no-verdicts retire the seat for the rest of the run.
-                    const causes = rv.meta.noVerdict === true && ctx.reviewNoVerdicts && !proofTimeout
+                    // OBS-1025 add.2: the run-scoped tally of REAL no-verdicts (silent, truncated, closure-mismatch,
+                    // no nonce …); two of them retire the seat for the run — a hard exclusion, never a soft ranking.
+                    const causes = rv.meta.noVerdict === true && ctx.reviewNoVerdicts
                         ? [...(ctx.reviewNoVerdicts.get(reviewer) ?? []), cause] : undefined;
                     if (causes)
                         ctx.reviewNoVerdicts.set(reviewer, causes);
@@ -1279,15 +1319,34 @@ export async function runGates(task, ctx) {
             }
             return rv;
         };
-        // OBS-1025 add.2: seats with two no-verdicts this run are out of the rotation for every pick below.
-        const retired = [...(ctx.reviewNoVerdicts ?? [])].filter(([, causes]) => causes.length >= 2).map(([seat]) => seat);
+        // OBS-1025 add.2: seats with two REAL no-verdicts this run (launch failures never strike) are RETIRED:
+        // out of every pick below for the rest of the run, and a resumed daemon re-seeds the tally from the
+        // journal. demotedReviewers is only a soft preference, live or replayed on resume — it ranks a seat
+        // last and never excludes or retires it; history or prefer can never resurrect a retired seat.
+        // The tally is shared across the run's tasks, so it is read LIVE at every pick — after every awaited
+        // notification and inside reviewGate after its promotion reads (atPick), since another task can retire a
+        // seat inside any await: a seat retired while this round's dispatch, note or read is pending is out of
+        // the initial pick, the launch retry, the re-emission and the re-route alike — and one retired after its
+        // pick is refused at launch (dispatch, above).
+        const retired = retiredNow();
+        // reviewGate awaits its promotion path reads BEFORE it picks, and another task can retire a seat inside
+        // that await too. So the exclusions every reviewGate call is handed are a live view: each read — the pick's
+        // included — answers from `fixed` plus the tally as it stands at that read, never a copy taken before.
+        // ponytail: a read-through Proxy because review.ts takes a plain list; a live-exclusion parameter there retires it.
+        const atPick = (fixed) => new Proxy([], {
+            get: (_target, prop) => {
+                const now = [...new Set([...fixed, ...retiredNow()])];
+                const value = Reflect.get(now, prop);
+                return typeof value === "function" ? value.bind(now) : value;
+            },
+        });
         // RF-1: THIS task's prior reviewers — earlier rounds' seats plus the seats that produced garbage for
         // it (excludeReviewers names only dispatched seats). Kept apart from the eligibility exclusions the
         // retry below adds for a flaked seat's whole adapter: those sibling channels never reviewed.
         const priorReviewers = [...(ctx.priorReviewers ?? []), ...(ctx.excludeReviewers ?? [])];
         const carriedAuthors = ctx.carriedAuthors ?? [];
         let exclusions = [...(ctx.excludeReviewers ?? []), ...retired];
-        let rv = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, via, exclusions, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, priorReviewers, carriedAuthors, ctx.operatorContext));
+        let rv = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, reviewVia, atPick(exclusions), ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, priorReviewers, carriedAuthors, ctx.operatorContext));
         // OBS-193/574: an unparseable review verdict retries the REVIEW, preferring a different adapter. Only
         // a single-adapter eligible pool may fall back to another channel on the flaked adapter. The flaked
         // verdict never enters results; an exhausted pool preserves its cause.
@@ -1299,19 +1358,50 @@ export async function runGates(task, ctx) {
         let hop = 0;
         // OBS-1196: seats already re-asked after a malformed verdict — once per seat, so never unbounded.
         const reemitted = new Set();
+        // v2.6.8 T1: seats already relaunched after a launch failure — once per seat per candidate (the
+        // daemon replays the spent ones), so a launch retry is bounded and never a second malformed allowance.
+        const launchRetried = new Set(ctx.launchRetried ?? []);
         while (!cancelled && (rv.meta?.unparseable === true || rv.meta?.noVerdict === true) && typeof rv.meta.reviewer === "string") {
             hop++;
             const flaked = rv.meta.reviewer;
-            const retryVia = via
-                ? { ...via, nameFor: (role, adapter) => via.nameFor(role, adapter) + `-r${hop}` }
+            const retryVia = reviewVia
+                ? { ...reviewVia, nameFor: (role, adapter) => reviewVia.nameFor(role, adapter) + `-r${hop}` }
                 : undefined;
+            // v2.6.8 T1: bounded same-seat launch retry. A seat that could not launch is launched ONCE more
+            // (fresh launch identity, fresh nonce, same subject) before any other seat is picked, journaled as
+            // the review-infra-retry naming that seat; its verdict decides. A second refusal re-routes below. A
+            // seat two real no-verdicts retired — before the note, while it was awaited, or during the relaunch's
+            // own promotion read (atPick) — is never relaunched: the withdrawn retry is said in the round's
+            // details, and the re-route below excludes the seat.
+            if (rv.meta.cause === "seat-launch-failed" && !launchRetried.has(flaked) && !retiredNow().includes(flaked)) {
+                launchRetried.add(flaked);
+                await ctx.onGate?.({ phase: "note", gate: "review", name: "review-infra-retry", payload: { reviewer: flaked, cause: "seat-launch-failed",
+                        sameSeat: true, ...(rv.meta.launchCause ? { launchCause: rv.meta.launchCause } : {}) }, result: rv });
+                const others = ctx.channels.map(channelKey).filter((key) => key !== flaked);
+                const again = retiredNow().includes(flaked) ? undefined : await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, atPick(others), ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, retryPrior, carriedAuthors, ctx.operatorContext));
+                if (again && again.meta?.noEligibleReviewer !== true) {
+                    // The relaunch that completes a malformed verdict's re-emission (the re-emission was what failed to
+                    // launch) publishes that delivery, so the seat is a delivery flake again, not a bad reviewer.
+                    const reemission = rv.meta.reviewReemission?.reviewer === flaked;
+                    if (reemission && again.meta?.unparseable !== true && again.meta?.noVerdict !== true) {
+                        await ctx.onGate?.({ phase: "note", gate: "review", name: "review-reemission", payload: { reviewer: flaked, cause: "malformed-verdict",
+                                delivered: true, launchRetry: true }, result: again });
+                    }
+                    routes.push(`review launch retry (same seat, fresh launch): ${flaked} failed to launch; launched once more`);
+                    rv = { ...again, details: `${routes.join("\n")}\n${again.details}`, meta: { ...again.meta, reviewLaunchRetry: { reviewer: flaked } } };
+                    continue;
+                }
+                if (retiredNow().includes(flaked)) {
+                    routes.push(`review launch retry withdrawn: ${flaked} was retired for the run (two real no-verdicts) while its relaunch was pending`);
+                }
+            }
             // OBS-1196: a malformed (unparseable) verdict is a delivery defect of THIS seat, not a reason to drop it. Ask the
             // same seat once more on the same subject; reviewGate mints a fresh nonce, so only a new, whole,
             // nonce-bound verdict can answer — the malformed bytes are never salvaged into one.
-            if (rv.meta.cause === "malformed-verdict" && rv.meta.closureInvalid !== true && !reemitted.has(flaked)) {
+            if (rv.meta.cause === "malformed-verdict" && rv.meta.closureInvalid !== true && !reemitted.has(flaked) && !retiredNow().includes(flaked)) {
                 reemitted.add(flaked);
                 const others = ctx.channels.map(channelKey).filter((key) => key !== flaked);
-                const again = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, others, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, retryPrior, carriedAuthors, ctx.operatorContext));
+                const again = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, atPick(others), ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, retryPrior, carriedAuthors, ctx.operatorContext));
                 if (again.meta?.noEligibleReviewer !== true) {
                     await ctx.onGate?.({ phase: "note", gate: "review", name: "review-reemission", payload: { reviewer: flaked, cause: "malformed-verdict",
                             delivered: again.meta?.unparseable !== true && again.meta?.noVerdict !== true }, result: again });
@@ -1319,6 +1409,9 @@ export async function runGates(task, ctx) {
                     rv = { ...again, details: `${routes.join("\n")}\n${again.details}`, meta: { ...again.meta, reviewReemission: { reviewer: flaked } } };
                     continue;
                 }
+                if (retiredNow().includes(flaked)) {
+                    routes.push(`review re-emission withdrawn: ${flaked} was retired for the run (two real no-verdicts) while its re-emission was pending`);
+                }
             }
             const emptyOutput = rv.meta.cause === "empty-output";
             if (emptyOutput) {
@@ -1334,16 +1427,18 @@ export async function runGates(task, ctx) {
             // and the prior reviewers' tiers, the flaked seat's own included, so a retry never drops a tier.
             retryPrior = [...retryPrior, flaked];
             const retryFloor = gateReviewerFloor(task, ctx.cfg, ctx.author, ctx.channels, retryPrior).floor;
+            exclusions = [...new Set([...exclusions, ...retiredNow()])];
             const crossAdapter = pickReviewer(ctx.author, ctx.channels, [...exclusions, ...adapterExclusions], ctx.cfg.review.prefer ?? [], retryFloor, undefined, undefined, undefined, carriedAuthorVendors(ctx.channels, carriedAuthors));
             const exclusion = crossAdapter ? "adapter" : "channel";
             exclusions = [...exclusions, ...(crossAdapter ? adapterExclusions : [flaked])];
-            const second = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, exclusions, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, retryPrior, carriedAuthors, ctx.operatorContext));
+            const second = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, atPick(exclusions), ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, retryPrior, carriedAuthors, ctx.operatorContext));
             if (second.meta?.noEligibleReviewer !== true) {
                 const retried = typeof second.meta?.reviewer === "string" ? second.meta.reviewer : "none";
                 const route = exclusion === "adapter"
                     ? `different-adapter retry; excluded flaked adapter ${flakedAdapter}`
                     : `same-adapter fallback; excluded flaked channel ${flaked}`;
-                const produced = emptyOutput ? "EMPTY output" : rv.meta.cause === "closure-mismatch" ? "a verdict closing no carried fingerprint" : "no parseable verdict";
+                const produced = emptyOutput ? "EMPTY output" : rv.meta.cause === "closure-mismatch" ? "a verdict closing no carried fingerprint"
+                    : rv.meta.cause === "seat-launch-failed" ? "no verdict (it failed to launch)" : "no parseable verdict";
                 // `details` is lifted onto the journal's gate-result row; meta.reviewRetry is not. Keep every
                 // re-route visible in the result text a reader actually opens, including on a red retry.
                 routes.push(`review re-route (${route}): ${flaked} produced ${produced}; replaced by ${retried}`);

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

@@ -88,13 +88,16 @@ export declare function verifyManifestReport(opts: {
 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.
+ * No measured-green 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 × its own killed a slower file that would have passed.
  */
 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;
+/** v2.6.8 P4 (prospectively superseding v2.5.5's "untimed = 3 × longest"): only the file's OWN usable green duration K
+ * buys measured slack, max(3 × K, L) with L the longest usable entry (red included) or legacy longestFile. An untimed,
+ * baseline-red or legacy longest-only file has no measure of its runtime and gets the finite battery ceiling. */
 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
@@ -130,6 +133,37 @@ export declare function classifyPollGap(prev: {
     wall: number;
     mono: number;
 }, pollMs: number): HostInterruption | undefined;
+/**
+ * v2.6.8 P4: an overdue poll on Darwin asks the kernel when it last slept and woke (`sysctl -n kern.sleeptime
+ * kern.waketime`), synchronously and bounded, before that poll's hang decision; the segment's overlap with the gap is
+ * credited as `host-suspend`. Unreadable evidence is unknown and credits 0. NAMED RESIDUAL: the kernel keeps only the
+ * MOST RECENT segment, so a gap holding several sleeps or maintenance DarkWakes credits only the last one — that
+ * under-credit fails closed: the file can still be killed as a hang, as on 2.6.7.
+ */
+export interface SleepSegment {
+    sleep: number;
+    wake: number;
+}
+export interface SleepEvidence {
+    platform: () => NodeJS.Platform;
+    /** The synchronous OS-command boundary (spawnSync's shape). */
+    command: (file: string, args: string[], opts: {
+        encoding: "utf8";
+        timeout: number;
+        maxBuffer: number;
+        killSignal: "SIGKILL";
+    }) => {
+        status: number | null;
+        signal: NodeJS.Signals | null;
+        stdout?: string;
+        stderr?: string;
+        error?: Error;
+    };
+    /** Replaces the default sysctl reader; production supplies none. */
+    reader?: () => SleepSegment | undefined;
+}
+export declare const setSleepEvidenceForTests: (evidence: Partial<SleepEvidence>) => void;
+export declare const resetSleepEvidenceForTests: () => void;
 export declare const runWithInterruptionSink: <T>(sink: (interruption: HostInterruption) => void, run: () => Promise<T>) => Promise<T>;
 export interface ManifestRunResult {
     evidenceReceipt: GateEvidenceReceipt;

package/dist/gates/test-manifest.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -331,8 +332,8 @@ export function verifyManifestReport(opts) {
 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.
+ * No measured-green 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 × its own killed a slower file that would have passed.
  */
 export const MIN_FILE_HANG_BUDGET_MS = 10_000;
 let hangBudgetFloorMs = MIN_FILE_HANG_BUDGET_MS;
@@ -340,17 +341,20 @@ let hangBudgetFloorMs = MIN_FILE_HANG_BUDGET_MS;
 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;
+/** v2.6.8 P4 (prospectively superseding v2.5.5's "untimed = 3 × longest"): only the file's OWN usable green duration K
+ * buys measured slack, max(3 × K, L) with L the longest usable entry (red included) or legacy longestFile. An untimed,
+ * baseline-red or legacy longest-only file has no measure of its runtime and gets the finite battery ceiling. */
 export function fileHangBudgetMs(file, baselineDurations, ceilingMs = DEFAULT_FILE_HANG_BUDGET_MS, longestFile) {
     const ceiling = usable(ceilingMs) ? ceilingMs : DEFAULT_FILE_HANG_BUDGET_MS;
     const timings = baselineDurations?.filter((d) => usable(d.durationMs)) ?? [];
-    const longest = Math.max(0, ...timings.map((d) => d.durationMs), usable(longestFile?.durationMs) ? longestFile.durationMs : 0);
-    if (!longest)
-        return ceiling;
     // 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));
+    if (known === undefined)
+        return ceiling;
+    const longest = Math.max(...timings.map((d) => d.durationMs), usable(longestFile?.durationMs) ? longestFile.durationMs : 0);
+    return Math.min(ceiling, Math.max(FILE_HANG_SLACK * known, longest));
 }
 /**
  * OBS-953 (+add): a per-file hang budget counted in raw wall time charged a lid-close to the file that
@@ -377,8 +381,29 @@ export function classifyPollGap(prev, now, pollMs) {
         return { kind: "unknown", ...gap, subtractedMs: 0 };
     return undefined;
 }
-/** The detected suspend a file started at `startedAt` sat through. */
-const suspendedSince = (interruptions, startedAt) => interruptions.reduce((sum, i) => sum + Math.min(i.subtractedMs, Math.max(0, i.to - Math.max(i.from, startedAt))), 0);
+const systemSleepEvidence = { platform: () => process.platform, command: (file, args, opts) => spawnSync(file, args, opts) };
+let sleepEvidence = systemSleepEvidence;
+export const setSleepEvidenceForTests = (evidence) => { sleepEvidence = { ...systemSleepEvidence, ...evidence }; };
+export const resetSleepEvidenceForTests = () => { sleepEvidence = systemSleepEvidence; };
+const SYSCTL_TIMEOUT_MS = 1_000, SYSCTL_MAX_BYTES = 4_096;
+const SYSCTL_STAMP = /^\{ sec = (\d{1,15}), usec = (\d{1,6}) \} [A-Z][a-z]{2} [A-Z][a-z]{2} +\d{1,2} \d{2}:\d{2}:\d{2} \d{4}$/;
+/** Lazy: runs only from an overdue poll, never at import. A timeout or overrun of 1000 ms, a signal, nonzero exit, more
+ * than 4096 combined output bytes, or a truncated, unparseable or reversed pair is unknown. spawnSync SIGKILLs the child
+ * at either bound and joins it: a child ignoring SIGTERM cannot hold the poll, so hang enforcement still runs. */
+function readDarwinSleepSegment() {
+    const startedMs = hangClocks.mono();
+    const r = sleepEvidence.command("sysctl", ["-n", "kern.sleeptime", "kern.waketime"], { encoding: "utf8", timeout: SYSCTL_TIMEOUT_MS, maxBuffer: SYSCTL_MAX_BYTES, killSignal: "SIGKILL" });
+    const out = r.stdout ?? "", err = r.stderr ?? "";
+    if (hangClocks.mono() - startedMs >= SYSCTL_TIMEOUT_MS || r.error || r.signal || r.status !== 0
+        || Buffer.byteLength(out) + Buffer.byteLength(err) > SYSCTL_MAX_BYTES)
+        return undefined;
+    const [sleep, wake, ...rest] = out.replace(/\n$/, "").split("\n").map((line) => SYSCTL_STAMP.exec(line))
+        .map((m) => m ? Number(m[1]) * 1000 + Number(m[2]) / 1000 : NaN);
+    return !rest.length && sleep < wake ? { sleep: sleep, wake: wake } : undefined;
+}
+/** Per gap, a file started at `startedAt` is credited the larger of the offset it sat through and its own overlap with
+ * the kernel segment: the same suspend is never counted twice, and nothing before the file started is credited. */
+const suspendedSince = (credits, startedAt) => credits.reduce((sum, c) => sum + Math.max(Math.min(c.offsetMs, Math.max(0, c.to - Math.max(c.from, startedAt))), Math.max(0, c.wake - Math.max(c.sleep, startedAt))), 0);
 // The daemon journals each interruption where it ran (task gate, tip verify); no sink, no journal row.
 const interruptionSink = new AsyncLocalStorage();
 export const runWithInterruptionSink = (sink, run) => interruptionSink.run(sink, run);
@@ -397,13 +422,33 @@ export function runManifestedTest(cmd, cwd, opts) {
     let hangWallMs;
     let poll;
     const interruptions = [];
+    const credits = [];
+    let creditedUntil = -Infinity;
     const sink = interruptionSink.getStore();
     let last = { wall: hangClocks.wall(), mono: hangClocks.mono() };
     const checkHang = (atCeiling = false) => {
         const at = { wall: hangClocks.wall(), mono: hangClocks.mono() };
-        const gap = classifyPollGap(last, at, pollMs);
+        let gap = classifyPollGap(last, at, pollMs);
         last = at;
         if (gap) {
+            let os;
+            if (sleepEvidence.platform() === "darwin") {
+                try {
+                    os = (sleepEvidence.reader ?? readDarwinSleepSegment)();
+                }
+                catch {
+                    os = undefined;
+                }
+                last = { wall: hangClocks.wall(), mono: hangClocks.mono() }; // the bounded read itself is no poll gap
+            }
+            // Clipped to this gap and past any segment already credited, so a repeated pair never credits twice.
+            const sleep = Math.max(os?.sleep ?? Infinity, gap.from, creditedUntil), wake = Math.min(os?.wake ?? -Infinity, gap.to);
+            const osMs = wake > sleep ? wake - sleep : 0;
+            if (osMs)
+                creditedUntil = wake;
+            credits.push({ from: gap.from, to: gap.to, offsetMs: gap.subtractedMs, ...(osMs ? { sleep, wake } : { sleep: 0, wake: 0 }) });
+            if (osMs > gap.subtractedMs)
+                gap = { ...gap, kind: "host-suspend", subtractedMs: osMs };
             interruptions.push(gap);
             sink?.(gap);
         }
@@ -416,7 +461,7 @@ export function runManifestedTest(cmd, cwd, opts) {
                 continue;
             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);
+            const activeMs = wallMs - suspendedSince(credits, startedAt);
             if (activeMs >= budget || (atCeiling && budget === overallCeilingMs)) {
                 killedFile = file;
                 hangBudgetMs = budget;

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

@@ -10,7 +10,13 @@ export interface ProcessIdentity {
     cwd: string;
     pgid: number;
 }
-export type IdentityRead = ProcessIdentity | "DEAD" | "UNKNOWN";
+/** `UNKNOWN — <why>` is UNKNOWN that names its cause (Darwin's lsof missing or unusable): never life, never death. */
+export type IdentityRead = ProcessIdentity | "DEAD" | "UNKNOWN" | `UNKNOWN — ${string}`;
+/** The host the production reader inspects through; Darwin (and every non-Linux host) reads cwd only via lsof. */
+export interface IdentityHost {
+    platform?: NodeJS.Platform;
+    lsof?: string;
+}
 /** 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). */
@@ -23,15 +29,19 @@ export interface BeatLifecycleDeps {
     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 function defaultBeatDeps(host?: IdentityHost): BeatLifecycleDeps;
+/** A named, nonzero refusal: dispatch renders the message and exits 1. `notice` is a reclaim it must not lose. */
 export declare class BeatRefusal extends Error {
+    readonly notice?: string | undefined;
+    constructor(message: string, notice?: string | undefined);
 }
 /**
  * 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.
+ * DEAD only when the kernel says so (ESRCH or a zombie) — also when it exits between ps and the cwd read;
+ * anything unreadable is UNKNOWN, never DEAD. Linux reads cwd from /proc and never needs lsof; every other
+ * host reads it through lsof, so a missing or unusable lsof beside a LIVE pid is UNKNOWN that names lsof.
  */
-export declare function readProcessIdentity(pid: number): IdentityRead;
+export declare function readProcessIdentity(pid: number, host?: IdentityHost): 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;
@@ -58,12 +68,61 @@ export interface BeatOwner {
 }
 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;
+/** Runs `mutate` as ONE claimed act (claimedAct); `check` is the act's own barrier (owner generation, records). */
+export type ClaimGuard = <T>(mutate: () => T, check?: () => void) => T;
+/** Outside any claim (a direct call): the barrier, then the mutation. */
+export declare const unclaimed: ClaimGuard;
 /**
- * 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.
+ * Atomic first-writer-wins claim. A held claim is BUSY unless `reclaim` (every claimant passes its boundaries) confirms
+ * DEAD every pid parsed from the claim's own bytes — its holder and any launched writer publishing under it
+ * (reclaimDeadClaim): then exactly those bytes are removed (takeClaim) and the claim is taken; the returned notice says
+ * so (on a refusal, `BeatRefusal.notice` does). A live, reused or unreadable holder or publisher is never taken over.
+ * A linked claim is SETTLED (returned) only when no claim removal is under way and it is still the canonical claim: a
+ * removal's put-back may replace a claim linked into its gap, so until that removal ends the claim holds nothing — the
+ * claimant withdraws exactly its own linked bytes (takeClaim) and refuses BUSY, so no caller, a long-lived bridge
+ * included, is left holding a live claim nobody acts under; its next attempt links afresh. When another live taker
+ * holds or has moved aside those very bytes (a mistaken death proof included), the withdrawal cannot land then; once
+ * this attempt refuses, its token is no longer in use, so the bytes are this process's STRAND wherever they are
+ * (strandOf), proven from the bytes alone: every later attempt in this process withdraws them from the claim path
+ * first (withdrawStrand) and discards them from a killed taker's lock instead of restoring them (recoverLock) — so
+ * recovery never waits for the caller to exit.
+ */
+export declare function acquireBeatClaim(repoRoot: string, tier: SupervisionTier, token: string, reclaim?: BeatLifecycleDeps): string | undefined;
+/** The ONE finite contention policy shared by every waiting claimant: loop ticks, legacy one-shots and stop. */
+export declare const BEAT_CLAIM_WAIT: {
+    readonly tries: 20;
+    readonly intervalMs: 250;
+};
+export interface ClaimWait {
+    tries?: number;
+    intervalMs?: number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Release removes exactly the bytes that name this token (takeClaim), after any claimed act under them — a launched
+ * writer's included — has finished: a replacement found at any instant is left in place. However it ends, the token is
+ * then no longer in use: bytes under it that a live taker kept or moved aside are this process's strand (strandOf),
+ * withdrawn or discarded by its next attempt. `told` gets the notice of a dead taker's lock recovered on the way.
+ */
+export declare function releaseBeatClaim(repoRoot: string, tier: SupervisionTier, token: string, told?: (notice: string) => void): void;
+/**
+ * Run ONE supervision.ts writer (stand-down, arm or beat) under a claim without letting it touch the tier: it writes
+ * into a STAGED copy of the tier's records (arm, clear-duty latch, beat, stand-down marker), then every record it
+ * changed is committed by one rename — a discharged latch by one removal — as ONE claimed act each (`guard`), in the
+ * writers' own order (arm, raised latch, beat, marker, discharged latch). Compare-and-commit: inside each act, after
+ * the caller's own barrier (its owner generation) and before the final claim check, every record must still be
+ * exactly what this write was staged from (or what it committed itself) — a record replaced meanwhile, the owner by
+ * the caller's barrier, refuses with nothing further committed. A claim lost, or a record or owner replaced, before
+ * the first commit therefore lands nothing; one lost between two commits lands nothing further; either refuses. What a
+ * failing writer published before its failure is committed the same way, then the failure is rethrown.
+ * ponytail: staging stands in for a commit guard supervision.ts's atomic writers do not take; a writer killed mid-write
+ * leaves an inert `<tier>.stage.<pid>.<uuid>` directory (no reader lists it), which the next start, stop or legacy
+ * write removes once that pid is confirmed dead (acquireBeatClaim).
+ */
+export declare function supervised<T>(repoRoot: string, tier: SupervisionTier, guard: ClaimGuard, write: (root: string) => T): T;
+/**
+ * A legacy writer: the launch generation it carries (if any), its seat, the arm a running loop holds, the
+ * boundaries its checks read through, and where the notice of a dead claim it reclaimed goes.
  */
 export interface LegacyWriter {
     generation?: string;
@@ -71,6 +130,7 @@ export interface LegacyWriter {
     settled?: boolean;
     arm?: SupervisionArm;
     deps: BeatLifecycleDeps;
+    noticed?: (notice: string) => void;
 }
 /**
  * The recheck a legacy write calls immediately before it mutates; `arm` is the arm the writer itself holds, and
@@ -79,17 +139,23 @@ export interface LegacyWriter {
 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.
+ * child acts under its launcher's claim (underLaunchClaim) while that claim is still held for its generation, names
+ * this child as its publisher and its launcher is not confirmed dead; afterwards it takes the tier claim itself like
+ * every other writer. `act` receives the recheck it must call before it writes (the tier's ownership still admits
+ * this writer, then the claim still names this holder) and the guard every supervision write it makes commits under
+ * (supervised): each commit is one claimed act whose barrier re-runs that same ownership check. A claim held by
+ * anyone else is waited out under BEAT_CLAIM_WAIT (20 attempts 250 ms apart, absent `waits` fields default to it)
+ * and then refuses BUSY with nothing written; invalid tries/interval refuse before any claim or write. Like start
+ * and stop, the writer reclaims a claim whose recorded pids are all confirmed dead (`noticed` receives the notice): a
+ * legacy --loop writer killed inside its claimed tick never strands the --stand-down migration step, and a live
+ * writer's claim is never taken. Under its own claim, the release that follows `act` is the claim's last check: a claim
+ * lost by then refuses, never reports success. Under the launcher's claim no release follows and nothing is checked
+ * after the last act — each act verified the claim last — so the launcher's release after its read-back never ends
+ * the loop it launched. A dead or abandoned generation recorded for this writer's seat is retired first (retireDead).
  */
-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>;
+export declare function withLegacyClaim<T>(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter, act: (recheck: LegacyRecheck, held: ClaimGuard) => T | Promise<T>, waits?: ClaimWait): 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;
+export declare function assertLegacyOwnership(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter, arm?: SupervisionArm, created?: boolean, held?: BeatOwner, claimed?: ClaimGuard): 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
@@ -107,7 +173,7 @@ export declare function assertLegacyOwnership(repoRoot: string, tier: Supervisio
  */
 export declare function assertOwnedGeneration(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter & {
     generation: string;
-}, arm?: SupervisionArm | undefined, created?: boolean, held?: BeatOwner, pid?: number): BeatOwner;
+}, arm?: SupervisionArm | undefined, created?: boolean, held?: BeatOwner, claimed?: ClaimGuard, pid?: number): BeatOwner;
 export type CheckedBeat = {
     kind: "EMPTY";
 } | {
@@ -124,9 +190,14 @@ export type CheckedBeat = {
     owner: BeatOwner & {
         pid: number;
     };
+} | {
+    kind: "ABANDONED";
+    owner: BeatOwner;
+    reason: string;
 } | {
     kind: "FOREIGN";
     reason: string;
+    migrate?: string;
 } | {
     kind: "PID-REUSED";
     owner: BeatOwner & {
@@ -140,15 +211,29 @@ export type CheckedBeat = {
  * 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.
+ * An UNBOUND owner (no pid, or no arm epoch) is a launch in progress only while a claim is held: a launch publishes and
+ * binds only under its own claim. So when the caller holds the tier claim (`held`), or no claim exists before and after
+ * the owner is read (status), an unbound owner with no live recorded process is ABANDONED — its launcher died — and
+ * the next start, stop or legacy write retires it (retireDead); a live recorded process keeps it UNKNOWN.
+ */
+export declare function inspectBeat(repoRoot: string, tier: SupervisionTier, seat: string | undefined, deps: BeatLifecycleDeps, held?: boolean): CheckedBeat;
+/**
+ * Status: the recorded liveness, rendered without writing; healthy states exit 0, the rest nonzero. It is observation
+ * only: a claim whose recorded pids are all dead, what a killed taker or writer left, or — read in the process that
+ * stranded it (a bridge) — that process's own strand (strandOf), is REPORTED (nonzero) with the pids and the exact
+ * command that recovers it — never recovered here, and no file is touched.
  */
-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. */
+/** start: one claim (a single attempt), 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. */
+/**
+ * stop: retire only the recorded generation, signalling its exact pid, then read back DISARMED. A loop tick
+ * holding the claim is waited out under BEAT_CLAIM_WAIT; a claim whose recorded pids are all confirmed dead is
+ * reclaimed. Every stand-down commit (supervised), signal and removal is one claimed act under stop's claim (`held`)
+ * with the owner generation it acts on re-verified inside it.
+ */
 export declare function stopBeat(repoRoot: string, tier: SupervisionTier, seat: string, deps: BeatLifecycleDeps): Promise<string>;
 export {};