tickmarkr 2.5.4 → 2.5.6

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 { stateDirName, taskContentDigest, tickmarkrDir } from "../graph/graph.js";
+import { graphDefinitionHash, stateDirName, taskContentDigest, 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 } : {}),
@@ -773,7 +785,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"];
+    "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,6 +983,63 @@ export function recordedGraphDefinitionHash(events) {
     }
     return recorded ?? undefined;
 }
+/** 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(),
+});
+export function replayScopeAmendments(graph, events) {
+    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)
+        return graph;
+    let result = graph;
+    // Accept any materialized revision, including a fresh compilation of the original definition.
+    // Undo only recognized files[] values. Everything else must still hash to the approved definition.
+    const taskIds = new Set(amendments.map(({ event }) => event.taskId));
+    for (const id of taskIds) {
+        const history = amendments.filter(({ event }) => event.taskId === id);
+        const task = result.tasks.find((t) => t.id === id);
+        const original = history[0].amendment.beforeFiles;
+        if (!task || ![original, ...history.map(({ amendment }) => amendment.files)]
+            .some((files) => JSON.stringify(files) === JSON.stringify(task.files))) {
+            throw new Error(`refusing scope amendment replay: ${id} files[] changed beyond the approved amendment`);
+        }
+        result = { ...result, tasks: result.tasks.map((t) => t.id === id ? { ...t, files: original } : t) };
+    }
+    for (const { event, amendment } of amendments) {
+        if (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)
+            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) {
+    const events = journal.read();
+    const result = replayScopeAmendments(graph, events); // 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);
+        if (!events.some((e) => e.event === "graph-rehash" && e.data.approval === approval.ts && e.taskId === approval.taskId
+            && e.data.from === amendment.from && e.data.to === amendment.to)) {
+            journal.append("graph-rehash", approval.taskId, {
+                from: amendment.from, to: amendment.to, approval: approval.ts, by: approval.data.by, source: "approval",
+            });
+        }
+    }
+    if (auditReplay && graphDefinitionHash(graph) !== graphDefinitionHash(result) && approvals.length) {
+        const recorded = recordedGraphDefinitionHash(journal.read());
+        journal.append("graph-rehash", approvals.at(-1).taskId, {
+            from: recorded, to: graphDefinitionHash(result), approval: approvals.at(-1).ts, source: "approval", replay: true,
+            loaded: graphDefinitionHash(graph),
+        });
+    }
+    return result;
+}
 // THE shared comparator (criterion: status and resume decide through one comparator). status reads
 // .comparable; resume reads .comparable plus .reason/.recorded for its refusal message and the release.
 export function engagementComparable(events, loadedHash) {
@@ -1243,13 +1312,24 @@ export class Journal {
             : { ts: new Date().toISOString(), event, ...(taskId ? { taskId } : {}), data: persistedData };
         // T3 secret redaction: only the persisted bytes are masked — the caller's data stays untouched in
         // memory. The narrator receives the persisted (masked) row so a pane sink never shows a credential.
-        const line = redactSecrets(JSON.stringify(row));
-        appendFileSync(this.journalPath, line + "\n");
-        try {
-            this.narrate?.(JSON.parse(line));
+        const rows = [row];
+        if (event === "task-approved" && row.data.release === "scope-request") {
+            const amendment = ScopeAmendmentSchema.parse(row.data.amendment);
+            // Publish permission and its graph audit in one append. Otherwise a live sweep can read
+            // permission between the two writes, race the CLI's rehash, and audit the revision twice.
+            rows.push({ ts: row.ts, event: "graph-rehash", taskId: row.taskId, data: {
+                    from: amendment.from, to: amendment.to, approval: row.ts, by: row.data.by, source: "approval",
+                } });
         }
-        catch {
-            // narration is observational; a broken sink must not affect the journal or run
+        const lines = rows.map((entry) => redactSecrets(JSON.stringify(entry)));
+        appendFileSync(this.journalPath, lines.join("\n") + "\n");
+        for (const line of lines) {
+            try {
+                this.narrate?.(JSON.parse(line));
+            }
+            catch {
+                // narration is observational; a broken sink must not affect the journal or run
+            }
         }
         if (evidence && !evidence.written && (event === "judge-retry" || event === "gate-result")) {
             evidence.written = true;
@@ -1337,7 +1417,7 @@ export class Journal {
                 outstanding = parsed.success ? { assignment: parsed.data } : {}; // malformed: closable, unattributable
                 classified = null;
             }
-            else if (e.event === "scope-authoring" && outstanding) {
+            else if ((e.event === "scope-authoring" || e.event === "scope-request") && outstanding) {
                 classified = outstanding; // a duplicate classification closes nothing more (same rule as the replay)
                 outstanding = null;
             }
@@ -1391,7 +1471,7 @@ export class Journal {
                     st.lastAssignment = undefined;
                 }
             }
-            else if (e.event === "scope-authoring") {
+            else if (e.event === "scope-authoring" || e.event === "scope-request") {
                 // OBS-547: the dispatch this event closes was an authoring defect — the spec is missing a
                 // files[] line and the worker was never at fault. Rewind its accounting so a resume neither
                 // charges the attempt nor treats its channel as burned.
@@ -1415,24 +1495,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;
@@ -1540,7 +1628,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

@@ -0,0 +1,58 @@
+export declare function isRunnerCommand(command: string): boolean;
+export declare const COMMAND_LEASE_TOKEN_ENV = "TICKMARKR_LEASE_TOKEN";
+export type CommandLease = <T>(command: string, run: (token?: string) => Promise<T>) => Promise<T>;
+/** Async descendants share the reservation; a shell's descendants inherit the same token. */
+export declare function currentCommandLeaseToken(): string | undefined;
+/** Never export a command's token through process.env: concurrent sibling commands must queue. */
+export declare function commandLeaseEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const runWithCommandLease: <T>(lease: CommandLease, run: () => Promise<T>) => Promise<T>;
+export declare const withCommandLease: <T>(command: string, run: () => Promise<T>) => Promise<T>;
+/** Each reservation releases only itself, including an aborted waiter. */
+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

@@ -0,0 +1,310 @@
+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.
+    let head = command.trim().replace(/['"]/g, "");
+    for (;;) {
+        const unwrapped = head
+            .replace(/^(?:\S*\/)?(?:ba|z)?sh\s+-[a-z]*c\s+/i, "")
+            .replace(/^cd\s+[^;&|]+\s*&&\s*/, "")
+            .replace(/^(?:env\s+)?(?:[A-Za-z_]\w*=\S+\s+)+/, "");
+        if (unwrapped === head)
+            break;
+        head = unwrapped;
+    }
+    const binary = "(?:\\S*/)?";
+    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, 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)
+        || /^(?:(?:\S*\/)?(?:node|npx)\s+)?(?:\S*\/)?(?:vitest(?:\.mjs)?|jest|mocha|pytest(?:\d+(?:\.\d+)*)?)(?:\s|$)/i.test(head)
+        || /^(?:\S*\/)?python[\d.]*\s+-m\s+pytest(?:\s|$)/i.test(head);
+}
+export const COMMAND_LEASE_TOKEN_ENV = "TICKMARKR_LEASE_TOKEN";
+const context = new AsyncLocalStorage();
+const ownership = new AsyncLocalStorage();
+/** Async descendants share the reservation; a shell's descendants inherit the same token. */
+export function currentCommandLeaseToken() {
+    const owner = ownership.getStore();
+    return owner ? (owner.active ? owner.token : undefined) : process.env[COMMAND_LEASE_TOKEN_ENV] || undefined;
+}
+/** Never export a command's token through process.env: concurrent sibling commands must queue. */
+export function commandLeaseEnvironment(env) {
+    const child = { ...env };
+    const token = currentCommandLeaseToken();
+    if (token)
+        child[COMMAND_LEASE_TOKEN_ENV] = token;
+    else
+        delete child[COMMAND_LEASE_TOKEN_ENV];
+    return child;
+}
+export const runWithCommandLease = (lease, run) => context.run(lease, run);
+export const withCommandLease = (command, run) => {
+    const lease = context.getStore();
+    if (!lease || !isRunnerCommand(command) || currentCommandLeaseToken())
+        return run();
+    return lease(command, token => {
+        const owner = { token: token ?? randomUUID(), active: true };
+        return ownership.run(owner, async () => {
+            try {
+                return await run();
+            }
+            finally {
+                owner.active = false;
+            } // A continuation after release must acquire a new lease.
+        });
+    });
+};
+/** Each reservation releases only itself, including an aborted waiter. */
+export class CommandLeases {
+    owners = new Set();
+    async run(run, waiting, pollMs, signal) {
+        const owner = Symbol("command");
+        this.owners.add(owner);
+        try {
+            let reported = false;
+            while (this.owners.values().next().value !== owner) {
+                signal?.throwIfAborted();
+                if (!reported) {
+                    waiting(this.owners.size - 1);
+                    reported = true;
+                }
+                await new Promise((wake) => setTimeout(wake, pollMs));
+            }
+            signal?.throwIfAborted();
+            return await run();
+        }
+        finally {
+            this.owners.delete(owner);
+        }
+    }
+}
+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/merge.d.ts

@@ -8,6 +8,8 @@ export interface TipVerifyResult {
     fingerprints: string[];
     details: string;
     artifact?: string;
+    reportPath?: string;
+    spawnedCommand?: string;
     /** Q121s: nonzero exit whose failures are ALL baseline-recorded — forgiven exactly as the battery forgives. */
     forgiven?: boolean;
     /**