tickmarkr 2.5.5 → 2.5.7

package/dist/run/journal.js

@@ -1,9 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { channelKey, shq, TokenUsageSchema } from "../adapters/types.js";
-import { graphDefinitionHash, stateDirName, taskContentDigest, tickmarkrDir } from "../graph/graph.js";
+import { graphDefinitionHash, stateDirName, taskContentDigest, taskDefinitionFingerprint, tickmarkrDir } from "../graph/graph.js";
 import { GATE_NAMES, TIERS } from "../graph/schema.js";
 import { channelRouteIdentity } from "../route/preference.js";
 import { buildProfile, classify } from "../route/profile.js";
@@ -60,8 +61,8 @@ export function formatJournalNarration({ event, taskId, data }) {
 // replayResumeState(), consumed by the daemon on resume to re-seed demotedChannels.
 export const CHANNEL_EXCLUSION_KINDS = ["dead-channel"];
 // v1.24 OBS-18: explicit data on task-approved when the operator releases an attempt-cap park.
-// Approve stamps this; replayResumeState zeros the attempt counter (fresh budget) while keeping
-// tried (consult bans / burned channels). Absent on pre-v1.24 events ⇒ inert (corpus outcome-identical).
+// Approve stamps this; replayResumeState resets both the attempt counter and tried seats for a fresh
+// budget. Absent on pre-v1.24 events ⇒ inert (corpus outcome-identical).
 export const ATTEMPT_CAP_RELEASE = "attempt-cap";
 // OBS-130: task-approved carries the exact failed gate the operator satisfied. The release tag keeps
 // ordinary humanGate and attempt-cap approvals byte-compatible while making this authority explicit.
@@ -74,8 +75,8 @@ export const REVIEW_UPHELD_RELEASE = "review-upheld";
 // gate before it — daemon.ts remainingGates), which is wrong when the gate failed against a stale task
 // DECLARATION rather than a bad diff: amend the spec's files[], recompile, and the gate now passes
 // honestly. This release runs the whole gate suite over the parked commit before any worker and
-// marks no gate satisfied: green merges directly, red returns to the ladder. Budget semantics match attempt-cap
-// (fresh attempts, tried survives) because the park cost the task its remaining budget.
+// marks no gate satisfied: green merges directly, red returns to the existing ladder with attempts
+// and tried seats intact.
 export const RECHECK_RELEASE = "recheck";
 // OBS-738: one authority for every recovery surface. The ref is accepted only from the row that
 // preservation itself writes; task-human prose, branch heads and commit history are deliberately
@@ -217,9 +218,20 @@ function identifierIn(note) {
 // code identity still has one stable identity of its own: its own words, with the volatile tokens
 // swept out so line/path churn cannot mint a new symbol for the same finding. It is the reviewer's
 // own bytes, never a guess, and it can never fuse two different findings into one.
+// OBS-1013 add.3: the words are BOUNDED — the first sentence, or a short hash when even that is long.
+// A whole-note symbol made a 600-byte fingerprint no reviewer could echo, so a real closure read as
+// malformed and bought a worker. A sentence a reviewer can copy is the identity; the hash is the fallback.
+const SYMBOL_SENTENCE_CAP = 160;
+export function boundedSymbol(note) {
+    const words = normalizeGateFailure(note);
+    if (!words)
+        return "";
+    const sentence = words.split(/(?<=[.!?])\s+|\n/)[0].trim();
+    return sentence.length <= SYMBOL_SENTENCE_CAP ? sentence : createHash("sha256").update(words).digest("hex").slice(0, 12);
+}
 function toFinding(cls, note, path, symbol, rationale) {
     const p = path || UNIDENTIFIED;
-    const s = symbol || normalizeGateFailure(note) || UNIDENTIFIED;
+    const s = symbol || boundedSymbol(note) || UNIDENTIFIED;
     return {
         class: cls, path: p, symbol: s, note,
         ...(rationale !== undefined ? { rationale } : {}),
@@ -644,16 +656,25 @@ function decisionForNextDispatch(events, taskId, event) {
  * `task-dispatch`: everything between the two — worktree recreation, setup, prompt write, slot
  * allocation, the launch itself — can still die with no worker having read a word, and clearing at
  * task-dispatch meant `--retry-failed` after exactly that death rebuilt the prompt without the gate
- * failures OR the delivery failure that preceded it. `task-approved` also clears (an operator approval
- * retires the findings it settled — the uphold case re-derives its own brief separately).
+ * failures OR the delivery failure that preceded it. Of the approvals, only a WAIVE clears (the operator
+ * retired the findings by fiat — the uphold case re-derives its own brief separately). OBS-1074: a
+ * plain approve, a scope grant or a recheck re-funds an attempt that must still see why the last one
+ * parked, plus the operator's stated reason — v2.5.7's T11 looped four times on one hygiene oracle
+ * because every approval erased exactly the finding the fresh attempt was funded to fix.
  */
 export function journaledFailureBrief(events, taskId) {
     let rows = [];
     for (const e of events) {
         if (e.taskId !== taskId)
             continue;
-        if (e.event === "worker-launch" || e.event === "task-approved")
+        if (e.event === "worker-launch")
             rows = [];
+        else if (e.event === "task-approved") {
+            if (e.data.release === GATE_SATISFIED_RELEASE)
+                rows = [];
+            else if (typeof e.data.reason === "string" && e.data.reason.trim())
+                rows.push(`approval: ${e.data.reason.trim()}`);
+        }
         else if (e.event === "gate-result" && e.data.pass === false && e.data.skipped !== true
             && typeof e.data.details === "string")
             rows.push(`${e.data.gate}: ${e.data.details}`);
@@ -773,7 +794,7 @@ const DispatchAssignmentSchema = z.object({
 // routing profile's QUALITY_FAIL_PARKS (route/profile.ts): the channel did nothing wrong.
 export const PARK_KINDS = ["human-gate", "ladder-exhausted", "attempt-cap", "gate-fail", "quota",
     "reroute-exhausted", "setup", "stall", "merge-conflict", "tip-moved", "infra", "dispatch",
-    "authoring", "scope-request"];
+    "authoring", "scope-request", "diff-cap"];
 // v1.85 T3: "repair" is a third dispatch mode beside the v1.29 session pair — a fix-only attempt that
 // carries the failing findings and the diff CONTENT of the work already landed, instead of re-buying
 // ~20m of onboarding to rediscover them (62 of 68 measured re-dispatches were fresh).
@@ -971,12 +992,37 @@ export function recordedGraphDefinitionHash(events) {
     }
     return recorded ?? undefined;
 }
+/**
+ * OBS-1073 residual: the `--graph-changed` release belongs to the ENGAGEMENT, not to the launch call. The
+ * daemon writes it on the run-resume row; every replay that runs inside that engagement from another
+ * process (the approve CLI) reads it back here. Without it the first in-run approval after a released
+ * launch re-ran the whole-graph asserts the launch had waived and killed the daemon (v2.5.7 run …152220).
+ */
+export function engagementReleased(events) {
+    const engagement = events.filter((e) => e.event === "run-start" || e.event === "run-resume").at(-1);
+    return engagement?.data.graphChanged === true;
+}
+/** The run's own graph.json (copied by the daemon at every start/resume) — the definitions the last engagement ran on. */
+function snapshotDefinitions(journal) {
+    const path = join(journal.dir, "graph.json");
+    if (!existsSync(path))
+        return new Map();
+    const snapshot = JSON.parse(readFileSync(path, "utf8"));
+    return new Map((snapshot.tasks ?? []).map((t) => [t.id, taskDefinitionFingerprint(t)]));
+}
 /** An approval is the durable authority; graph.json is only its materialized projection. */
 export const ScopeAmendmentSchema = z.object({
     from: z.string(), to: z.string(), beforeFiles: z.array(z.string()), files: z.array(z.string()),
     parkLine: z.number().int().positive(),
+    /** OBS-1073: the amended task's definition minus files[] at approval; absent on rows older than v2.5.7. */
+    definition: z.string().optional(),
 });
-export function replayScopeAmendments(graph, events) {
+/**
+ * `release` is the operator's audited `--graph-changed`. `approvedDefinitions` supplies, per amended task,
+ * the definition fingerprint the amendment was granted against when the row itself carries none (rows
+ * older than v2.5.7): the caller reads it from the run's materialized graph snapshot.
+ */
+export function replayScopeAmendments(graph, events, release = false, approvedDefinitions = new Map()) {
     const amendments = events.filter((e) => e.event === "task-approved" && e.data.release === "scope-request")
         .map((event) => ({ event, amendment: ScopeAmendmentSchema.parse(event.data.amendment) }));
     if (!amendments.length)
@@ -995,20 +1041,37 @@ export function replayScopeAmendments(graph, events) {
         }
         result = { ...result, tasks: result.tasks.map((t) => t.id === id ? { ...t, files: original } : t) };
     }
+    // OBS-1073: `from`/`to` bind the WHOLE graph, so a later spec repair of ANOTHER task (a pin-sweep miss
+    // found mid-run, D-57) makes them unmatchable forever and `--graph-changed` — applied only after this
+    // replay — never reaches its own release. Under that audited release the amended task's files[]
+    // recognition above still holds and the caller journals the rehash; only the whole-graph identity
+    // asserts are waived. Without the release nothing changes: fail closed.
     for (const { event, amendment } of amendments) {
-        if (graphDefinitionHash(result) !== amendment.from) {
+        if (release) {
+            // The release waives the WHOLE-GRAPH identity (another task may lawfully have moved), never the
+            // amended task's own definition: goal, acceptance, deps, floor must still be what was approved.
+            const approved = amendment.definition ?? approvedDefinitions.get(event.taskId ?? "");
+            const current = result.tasks.find((t) => t.id === event.taskId);
+            if (approved === undefined || current === undefined) {
+                throw new Error(`refusing scope amendment replay under --graph-changed: no approved definition fingerprint for ${event.taskId}`);
+            }
+            if (taskDefinitionFingerprint(current) !== approved) {
+                throw new Error(`refusing scope amendment replay: ${event.taskId} definition changed beyond the approved amendment (goal, acceptance, deps or routing)`);
+            }
+        }
+        if (!release && graphDefinitionHash(result) !== amendment.from) {
             throw new Error(`refusing scope amendment replay: graph task definition changed beyond approval for ${event.taskId}`);
         }
         result = { ...result, tasks: result.tasks.map((t) => t.id === event.taskId ? { ...t, files: amendment.files } : t) };
-        if (graphDefinitionHash(result) !== amendment.to)
+        if (!release && graphDefinitionHash(result) !== amendment.to)
             throw new Error("refusing invalid scope amendment hash");
     }
     return result;
 }
 /** Publish/recover the audit before dispatch, even after a crash between approval and rehash. */
-export function applyScopeAmendments(graph, journal, auditReplay = false) {
+export function applyScopeAmendments(graph, journal, auditReplay = false, release = false) {
     const events = journal.read();
-    const result = replayScopeAmendments(graph, events); // validate all before moving any identity
+    const result = replayScopeAmendments(graph, events, release, release ? snapshotDefinitions(journal) : new Map()); // validate all before moving any identity
     const approvals = events.filter((e) => e.event === "task-approved" && e.data.release === "scope-request");
     for (const approval of approvals) {
         const amendment = ScopeAmendmentSchema.parse(approval.data.amendment);
@@ -1483,24 +1546,32 @@ export class Journal {
                 // A reroute bans the in-force channel; retry/decompose/human verdicts ban nothing (D-03).
                 pendingReroute.add(e.taskId);
             }
-            else if (e.event === "task-approved"
-                && (e.data.release === ATTEMPT_CAP_RELEASE || e.data.release === RECHECK_RELEASE)) {
+            else if (e.event === "task-approved" && e.data.release === ATTEMPT_CAP_RELEASE) {
                 // v1.24 OBS-18: operator released an attempt-cap park. Pre-v1.24 task-approved events have no
                 // `release` key ⇒ this branch never fires (corpus criterion: identical statuses + resume state).
-                // attempts reset to 0 so the daemon's attempt-cap check does not re-park in the same tick;
-                // tried survives (consult bans and burned channels are not forgotten); lastAssignment is
-                // cleared so the daemon's nextChannel-over-tried path skips burned channels on first dispatch
-                // (restoring the last burned assignment would re-try it first — the failure the tried-list exists to prevent).
+                // attempts and tried reset so the daemon's attempt-cap check does not re-park in the same tick
+                // and the newly funded engagement starts with a cleared seat list; lastAssignment clears too.
+                // OBS-1028: a RECHECK release is deliberately NOT here — it marks no gate satisfied and funds no
+                // attempt, so the ladder (attempts AND tried) survives it untouched. Only THIS fresh-budget
+                // release resets the ladder, and it resets both halves: a fresh budget on a cleared seat list.
                 const st = m.get(e.taskId);
                 if (st) {
                     st.attempts = 0;
+                    st.tried = [];
                     st.lastAssignment = undefined;
                 }
             }
+            else if (e.event === "task-approved" && e.data.release === RECHECK_RELEASE) {
+                // OBS-1028: the ladder survives a recheck (attempts AND tried); only the seat memory is cleared
+                // so a red battery's next dispatch is picked over the exclusions instead of restoring the parked seat.
+                const st = m.get(e.taskId);
+                if (st)
+                    st.lastAssignment = undefined;
+            }
             else if (e.event === "task-approved" && e.data.release === REVIEW_UPHELD_RELEASE) {
-                // OBS-189: the operator upheld the reviewer. Same budget semantics as the attempt-cap release
-                // (fresh attempts, tried survives, no burned-channel restore) PLUS the findings carry: the
-                // newest failed review's details ride into the funded attempt as its retry brief.
+                // OBS-189: the operator upheld the reviewer. It funds fresh attempts without forgetting tried
+                // seats (unlike an attempt-cap fresh-budget release), and carries the newest failed review's
+                // details into the funded attempt as its retry brief.
                 const st = m.get(e.taskId);
                 if (st) {
                     st.attempts = 0;
@@ -1608,7 +1679,9 @@ export class Journal {
     replayExcludedChannels() {
         const excluded = new Set();
         for (const e of this.read()) {
-            if (e.event === "channel-exclusion" && typeof e.data.channel === "string") {
+            // OBS-1010: an in-run no-trailer demotion is a WORKER exclusion too; review-pool-demotion is
+            // the reviewer seat's own fold (daemon demotedReviewers) and never benches the worker channel.
+            if ((e.event === "channel-exclusion" || e.event === "channel-demotion") && typeof e.data.channel === "string") {
                 excluded.add(e.data.channel);
             }
             else if (e.event === "dead-channel-failover" && typeof e.data.from === "string") {

package/dist/run/lease.d.ts

@@ -12,3 +12,47 @@ export declare class CommandLeases {
     private readonly owners;
     run<T>(run: () => Promise<T>, waiting: (count: number) => void, pollMs: number, signal?: AbortSignal): Promise<T>;
 }
+/**
+ * OBS-1042: the standalone battery's cross-process lease. Two `tickmarkr verify` runs in two linked
+ * worktrees of one clone share NO daemon and NO state directory, so the in-process `CommandLeases`
+ * above never saw each other and both full suites ran on one host. This reservation is keyed on the
+ * repository's COMMON git dir (`git rev-parse --git-common-dir`), which every linked worktree of a
+ * clone shares and an unrelated repository never does. One file, created exclusively; the holder
+ * writes its pid and cwd so a waiter can journal who it waits on and reclaim a reservation whose
+ * holder is dead. Each reservation releases only itself: a waiter that never acquired removes nothing,
+ * so cancelling it never frees the holder. The daemon's adoption is deferred to 2.5.7.
+ */
+export interface RepositoryLeaseHolder {
+    pid: number;
+    cwd: string;
+    at: number;
+    token: string;
+}
+export interface RepositoryLeaseOptions {
+    pollMs?: number;
+    signal?: AbortSignal;
+    /** Called once per distinct holder the waiter is queued behind. */
+    onWait?: (holder: RepositoryLeaseHolder) => void;
+}
+export declare function repositoryLeasePath(cwd: string): Promise<string>;
+/** OBS-1057: dev+ino alone is not an identity across unlink/recreate — Linux hands the freed inode
+ * number straight to the next file, so a stale observation of a dead or corrupt reservation matched
+ * the fresh reservation that replaced it and reclaimDead removed the live winner (public CI, ubuntu).
+ * The bytes are the generation: a fragment never hashes like a complete record, and two complete
+ * records differ by token. Size and mtime are not enough (a same-length reservation written within
+ * the filesystem's timestamp resolution — Leg-2 review of the first cut). */
+export declare const inodeIdentity: (st: {
+    dev: number | bigint;
+    ino: number | bigint;
+}, bytes: string | Buffer) => string;
+/** The identity a reclaimer would observe at a path right now, or undefined when nothing is there. */
+export declare const observeIdentity: (path: string) => string | undefined;
+export declare const readHolder: (path: string) => RepositoryLeaseHolder | undefined;
+/** Publish `mine` at `path` atomically: the record is written whole to a private file and linked
+ * into place — `link` is exclusive (EEXIST when the path is taken) and a reader never sees a partial
+ * record, so a process killed at any point of its acquisition leaves either nothing or a complete
+ * record naming a pid a waiter can check. Returns false when the path is taken. */
+export declare function tryReserve(path: string, mine: RepositoryLeaseHolder): boolean;
+/** Exposed for recovery regressions; the standalone verify uses the combined critical section. */
+export declare const reclaimDead: (path: string, identity: string, pollMs?: number) => Promise<boolean>;
+export declare function withRepositoryLease<T>(cwd: string, run: () => Promise<T>, opts?: RepositoryLeaseOptions): Promise<T>;

package/dist/run/lease.js

@@ -1,5 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, rmdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
 // The process census and command admission deliberately use the same command-head classifier.
 export function isRunnerCommand(command) {
     // Inspect executable positions only: inference prompts and shell script bodies may name runners.
@@ -17,9 +21,11 @@ export function isRunnerCommand(command) {
     const flags = "(?:\\s+(?:--?[\\w-]+(?:=[^\\s]+)?|--))*";
     const manager = `${binary}(?:npm|pnpm|yarn|bun)${flags}`;
     const jsRunner = `${binary}(?:vitest(?:\\.mjs)?|jest|mocha)(?:\\s|$)`;
-    // Test scripts may be scoped (test:unit); runner binaries may be launched through a manager.
-    // Keep each match anchored to that executable position so prompt/argument mentions stay out.
-    return new RegExp(`^${manager}\\s+(?:run${flags}\\s+)?test[\\w:.-]*(?:\\s|$)`, "i").test(head)
+    // Test scripts may be scoped (test:unit, test.integration); runner binaries may be launched
+    // through a manager. Keep each match anchored to that executable position so prompt/argument
+    // mentions stay out. OBS-1045: the scope is `test` followed by a `:` or `.` separator — the npm
+    // scoping convention — so a differently named script such as `test-lint` is never leased.
+    return new RegExp(`^${manager}\\s+(?:run${flags}\\s+)?test(?:[:.][\\w.-]+)?(?:\\s|$)`, "i").test(head)
         || new RegExp(`^${manager}\\s+(?:(?:exec|x|dlx)${flags}\\s+)?${jsRunner}`, "i").test(head)
         || new RegExp(`^${binary}npx${flags}\\s+${jsRunner}`, "i").test(head)
         || /^(?:\S*\/)?(?:go|make|cargo)\s+test(?:\s|$)/i.test(head)
@@ -85,3 +91,220 @@ export class CommandLeases {
         }
     }
 }
+const LEASE_FILE = "tickmarkr-runner.lease";
+export async function repositoryLeasePath(cwd) {
+    const commonDir = await new Promise((ok, fail) => execFile("git", ["rev-parse", "--git-common-dir"], { cwd, encoding: "utf8" }, (error, stdout) => error ? fail(error) : ok(stdout.trim())));
+    return join(resolve(cwd, commonDir), LEASE_FILE);
+}
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+};
+const isCode = (error, code) => error.code === code;
+/** OBS-1057: dev+ino alone is not an identity across unlink/recreate — Linux hands the freed inode
+ * number straight to the next file, so a stale observation of a dead or corrupt reservation matched
+ * the fresh reservation that replaced it and reclaimDead removed the live winner (public CI, ubuntu).
+ * The bytes are the generation: a fragment never hashes like a complete record, and two complete
+ * records differ by token. Size and mtime are not enough (a same-length reservation written within
+ * the filesystem's timestamp resolution — Leg-2 review of the first cut). */
+export const inodeIdentity = (st, bytes) => `${st.dev}-${st.ino}-${createHash("sha256").update(bytes).digest("hex").slice(0, 16)}`;
+/** The identity a reclaimer would observe at a path right now, or undefined when nothing is there. */
+export const observeIdentity = (path) => readOccupant(path)?.identity;
+const readOccupant = (path) => {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const st = fstatSync(fd);
+        const bytes = readFileSync(fd, "utf8");
+        const identity = inodeIdentity(st, bytes);
+        try {
+            const holder = JSON.parse(bytes);
+            if (typeof holder.pid === "number" && typeof holder.cwd === "string" && typeof holder.token === "string")
+                return { holder, identity };
+        }
+        catch { /* incomplete/foreign bytes are reclaimable under the mutation lock */ }
+        return { holder: undefined, identity };
+    }
+    catch (error) {
+        if (isCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+};
+export const readHolder = (path) => readOccupant(path)?.holder;
+/** Crash-recoverable serialization for lease-path mutations. The highest atomic owner-generation
+ * symlink is authoritative. A process killed in the critical section leaves its pid behind, so one
+ * contender can exclusively publish the next generation and finish the interrupted operation. */
+const mutationLock = (path) => `${path}.lock`;
+const lockGeneration = (entry) => {
+    const match = /^owner\.(\d+)$/.exec(entry);
+    return match ? Number(match[1]) : undefined;
+};
+const mutationHolder = (lock) => {
+    let names;
+    try {
+        names = readdirSync(lock);
+    }
+    catch (error) {
+        if (isCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    const current = names.flatMap((entry) => {
+        const gen = lockGeneration(entry);
+        return gen === undefined ? [] : [{ entry, gen }];
+    }).sort((a, b) => b.gen - a.gen)[0];
+    if (!current)
+        return undefined;
+    try {
+        const target = readlinkSync(join(lock, current.entry));
+        const pid = Number(/^([1-9]\d*):/.exec(target)?.[1]);
+        return Number.isInteger(pid) && pid > 0 ? { ...current, target, pid } : { ...current, target };
+    }
+    catch {
+        return current;
+    }
+};
+const releaseMutationLock = (lock, entry, target, inherited) => {
+    const holder = mutationHolder(lock);
+    if (holder?.entry !== entry || holder.target !== target)
+        return;
+    // Remove our marker last. A successor published after that point is never in this snapshot.
+    for (const name of [...inherited, entry]) {
+        try {
+            unlinkSync(join(lock, name));
+        }
+        catch (error) {
+            if (!isCode(error, "ENOENT"))
+                return;
+        }
+    }
+    try {
+        rmdirSync(lock);
+    }
+    catch { /* ENOTEMPTY: a successor owns the directory */ }
+};
+const withMutationLock = async (path, pollMs, signal, run) => {
+    const lock = mutationLock(path);
+    const target = `${process.pid}:${randomUUID()}`;
+    let entry = "";
+    let inherited = [];
+    for (;;) {
+        signal?.throwIfAborted();
+        try {
+            mkdirSync(lock);
+        }
+        catch (error) {
+            if (!isCode(error, "EEXIST"))
+                throw error;
+        }
+        const holder = mutationHolder(lock);
+        if (holder?.pid !== undefined && alive(holder.pid)) {
+            await new Promise((wake) => setTimeout(wake, pollMs));
+            continue;
+        }
+        entry = `owner.${(holder?.gen ?? -1) + 1}`;
+        try {
+            symlinkSync(target, join(lock, entry));
+            inherited = readdirSync(lock).filter((name) => name !== entry && lockGeneration(name) !== undefined);
+            break;
+        }
+        catch (error) {
+            if (!isCode(error, "EEXIST") && !isCode(error, "ENOENT"))
+                throw error;
+        }
+    }
+    try {
+        return await run();
+    }
+    finally {
+        releaseMutationLock(lock, entry, target, inherited);
+    }
+};
+/** Publish `mine` at `path` atomically: the record is written whole to a private file and linked
+ * into place — `link` is exclusive (EEXIST when the path is taken) and a reader never sees a partial
+ * record, so a process killed at any point of its acquisition leaves either nothing or a complete
+ * record naming a pid a waiter can check. Returns false when the path is taken. */
+export function tryReserve(path, mine) {
+    const draft = `${path}.${mine.token}.draft`;
+    writeFileSync(draft, JSON.stringify(mine) + "\n");
+    try {
+        linkSync(draft, path);
+        return true;
+    }
+    catch (error) {
+        if (isCode(error, "EEXIST"))
+            return false;
+        throw error;
+    }
+    finally {
+        rmSync(draft, { force: true });
+    }
+}
+/** Link the inspected dead inode to its stable tombstone, then remove the canonical name. This runs
+ * only under the mutation lock. EEXIST means an earlier reclaimer died after link: recovery finishes
+ * only if both names still bind that exact inode, never a replacement holder. */
+const reclaimDeadLocked = (path, identity) => {
+    const tombstone = `${path}.dead-${identity}`;
+    try {
+        linkSync(path, tombstone);
+    }
+    catch (error) {
+        if (!isCode(error, "EEXIST") && !isCode(error, "ENOENT"))
+            throw error;
+    }
+    const dead = readOccupant(tombstone);
+    const current = readOccupant(path);
+    if (dead?.identity !== identity || current?.identity !== identity)
+        return false;
+    unlinkSync(path);
+    return true;
+};
+/** Exposed for recovery regressions; the standalone verify uses the combined critical section. */
+export const reclaimDead = async (path, identity, pollMs = 10) => withMutationLock(path, pollMs, undefined, () => reclaimDeadLocked(path, identity));
+const inspectAndReserve = (path, mine) => {
+    let occupant = readOccupant(path);
+    if (occupant && (!occupant.holder || !alive(occupant.holder.pid))) {
+        reclaimDeadLocked(path, occupant.identity);
+        occupant = readOccupant(path);
+    }
+    if (!occupant && tryReserve(path, mine))
+        return { acquired: true };
+    return { acquired: false, holder: occupant?.holder };
+};
+export async function withRepositoryLease(cwd, run, opts = {}) {
+    const path = await repositoryLeasePath(cwd);
+    const pollMs = opts.pollMs ?? 1_000;
+    const mine = { pid: process.pid, cwd, at: Date.now(), token: randomUUID() };
+    let waitingOn;
+    for (;;) {
+        opts.signal?.throwIfAborted();
+        const attempt = await withMutationLock(path, pollMs, opts.signal, () => inspectAndReserve(path, mine));
+        if (attempt.acquired)
+            break;
+        if (attempt.holder && attempt.holder.pid !== waitingOn) {
+            waitingOn = attempt.holder.pid;
+            opts.onWait?.(attempt.holder);
+        }
+        await new Promise((wake) => setTimeout(wake, pollMs));
+    }
+    try {
+        return await run();
+    }
+    finally {
+        // Release is serialized with reclamation/acquisition and removes only this generation.
+        await withMutationLock(path, pollMs, undefined, () => {
+            if (readHolder(path)?.token === mine.token)
+                unlinkSync(path);
+        });
+    }
+}

package/dist/run/operator-page-summary.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure operator-page grouping over the `operator-page` rows the daemon journals (one row per
+ * delivered page, carrying the producer's `suppressed` count). This module consumes that count and
+ * never throttles a second time: it only coalesces EQUIVALENT rows for display while keeping every
+ * source line, both evidence timestamps, and the producer's suppressed count separate from what was
+ * actually observed. Folding is incremental and pure; `fold(fold(empty, a), b)` equals
+ * `fold(empty, [...a, ...b])` and no journal byte is touched.
+ */
+import type { JournalEvent } from "./journal.js";
+export interface OperatorPageRow {
+    /** Source reference (journal line number or any stable locator). */
+    readonly line: number;
+    readonly ts: string;
+    readonly runId: string;
+    readonly taskId: string;
+    /** Current park identity (e.g. park kind + attempt); part of the group key. */
+    readonly park: string;
+    /** Decision state (e.g. blocked / idle / failed / resolved); part of the group key. */
+    readonly status: string;
+    /** Producer-suppressed page count; absent on rows written before suppression metadata existed. */
+    readonly suppressed?: number;
+    readonly blocker?: string;
+    readonly owner?: string;
+    readonly requiredAction?: string;
+    readonly permittedActions?: readonly string[];
+}
+export interface OperatorPageGroup {
+    readonly key: string;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly park: string;
+    readonly status: string;
+    readonly blocker?: string;
+    readonly owner?: string;
+    readonly requiredAction?: string;
+    readonly permittedActions: readonly string[];
+    readonly firstEvidenceAt: string;
+    readonly lastEvidenceAt: string;
+    /** Rows actually present in the journal. */
+    readonly observedCount: number;
+    /** Sum of the producer's `suppressed` counts; never added to observedCount. */
+    readonly suppressedCount: number;
+    /** True when at least one row lacked suppression metadata (pre-metadata journal). */
+    readonly rawOnly: boolean;
+    readonly lines: readonly number[];
+}
+export interface OperatorPageSummary {
+    readonly groups: readonly OperatorPageGroup[];
+}
+export declare const EMPTY_OPERATOR_PAGE_SUMMARY: OperatorPageSummary;
+/** Projects a journal event onto a row; returns undefined for anything that is not an operator page. */
+export declare function operatorPageRow(event: JournalEvent, line: number, runId: string): OperatorPageRow | undefined;
+/** Folds rows into a summary. Pure: returns a new summary, never mutates inputs. */
+export declare function foldOperatorPages(prior: OperatorPageSummary, rows: readonly OperatorPageRow[]): OperatorPageSummary;
+/** Full replay from journal events. */
+export declare function summarizeOperatorPages(events: readonly JournalEvent[], runId: string): OperatorPageSummary;

package/dist/run/operator-page-summary.js

@@ -0,0 +1,68 @@
+export const EMPTY_OPERATOR_PAGE_SUMMARY = { groups: [] };
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Projects a journal event onto a row; returns undefined for anything that is not an operator page. */
+export function operatorPageRow(event, line, runId) {
+    if (event.event !== "operator-page" || event.taskId === undefined)
+        return undefined;
+    const d = event.data;
+    const permitted = Array.isArray(d.permittedActions) ? d.permittedActions.filter((a) => typeof a === "string") : undefined;
+    return {
+        line, ts: event.ts, runId, taskId: event.taskId,
+        park: str(d.park) ?? `${str(d.slot) ?? ""}#${typeof d.attempt === "number" ? d.attempt : ""}`,
+        status: str(d.status) ?? "unknown",
+        ...(typeof d.suppressed === "number" ? { suppressed: d.suppressed } : {}),
+        ...(str(d.blocker) !== undefined ? { blocker: str(d.blocker) } : {}),
+        ...(str(d.owner) !== undefined ? { owner: str(d.owner) } : {}),
+        ...(str(d.requiredAction) !== undefined ? { requiredAction: str(d.requiredAction) } : {}),
+        ...(permitted !== undefined ? { permittedActions: permitted } : {}),
+    };
+}
+const groupKey = (r) => [r.runId, r.taskId, r.park, r.status].join("\u0000");
+const openKey = (r) => `${r.runId}\u0000${r.taskId}`;
+/** Permitted actions compare as a SET: order and duplicates never open a new group. */
+const actionSet = (a) => [...new Set(a ?? [])].sort().join("\u0000");
+const sameDecision = (g, r) => g.key === groupKey(r)
+    && g.blocker === r.blocker && g.owner === r.owner && g.requiredAction === r.requiredAction
+    && actionSet(g.permittedActions) === actionSet(r.permittedActions);
+/** Folds rows into a summary. Pure: returns a new summary, never mutates inputs. */
+export function foldOperatorPages(prior, rows) {
+    const groups = [...prior.groups];
+    // One open group per run/task: ANY change in park, status or decision closes it, so a later
+    // transition can never merge backward into an earlier group across an intervening change.
+    const open = new Map();
+    groups.forEach((g, i) => open.set(openKey(g), i));
+    for (const row of rows) {
+        const key = groupKey(row);
+        const idx = open.get(openKey(row));
+        const g = idx === undefined ? undefined : groups[idx];
+        if (g !== undefined && sameDecision(g, row)) {
+            groups[idx] = {
+                ...g,
+                firstEvidenceAt: row.ts < g.firstEvidenceAt ? row.ts : g.firstEvidenceAt,
+                lastEvidenceAt: row.ts > g.lastEvidenceAt ? row.ts : g.lastEvidenceAt,
+                observedCount: g.observedCount + 1,
+                suppressedCount: g.suppressedCount + (row.suppressed ?? 0),
+                rawOnly: g.rawOnly || row.suppressed === undefined,
+                lines: [...g.lines, row.line],
+            };
+            continue;
+        }
+        groups.push({
+            key, runId: row.runId, taskId: row.taskId, park: row.park, status: row.status,
+            ...(row.blocker !== undefined ? { blocker: row.blocker } : {}),
+            ...(row.owner !== undefined ? { owner: row.owner } : {}),
+            ...(row.requiredAction !== undefined ? { requiredAction: row.requiredAction } : {}),
+            permittedActions: [...(row.permittedActions ?? [])],
+            firstEvidenceAt: row.ts, lastEvidenceAt: row.ts,
+            observedCount: 1, suppressedCount: row.suppressed ?? 0,
+            rawOnly: row.suppressed === undefined, lines: [row.line],
+        });
+        open.set(openKey(row), groups.length - 1);
+    }
+    return { groups };
+}
+/** Full replay from journal events. */
+export function summarizeOperatorPages(events, runId) {
+    const rows = events.flatMap((e, i) => { const r = operatorPageRow(e, i + 1, runId); return r ? [r] : []; });
+    return foldOperatorPages(EMPTY_OPERATOR_PAGE_SUMMARY, rows);
+}