tickmarkr 2.5.3 → 2.5.5

package/dist/run/git.d.ts

@@ -4,7 +4,7 @@ export { ROUTING_ENV_SEAMS };
 export declare const FORK_CAP_ENV = "VITEST_MAX_FORKS";
 export declare const SUITE_PARENT_ENV = "TICKMARKR_SUITE_PARENT";
 export declare const DEFAULT_FORK_CAP = "6";
-/** Verification owns the serialized suite window; workers keep their concurrency budget. */
+/** Verification uses command leases; workers keep their concurrency budget. */
 export declare const runWithVerificationBudget: <T>(capacity: RunCapacity, fn: () => Promise<T>) => Promise<T>;
 /**
  * OBS-618: how many PROCESSES one vitest fork can hold at its peak — the fork, a daemon it spawns,
@@ -89,6 +89,7 @@ export declare const resolvedCapacity: () => RunCapacity;
 export declare const DEFAULT_SHELL_TIMEOUT_MS = 600000;
 export interface ShResult {
     code: number;
+    signalExit?: boolean;
     stdout: string;
     stderr: string;
     timedOut?: boolean;
@@ -104,6 +105,14 @@ export declare const setSpawnForTests: (fn: typeof spawn) => void;
 export declare const resetSpawnForTests: () => void;
 export declare const SPAWN_ATTEMPT_LIMIT = 4;
 export declare const SPAWN_RETRY_BACKOFF_MS = 50;
+export interface ShellOptions {
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    onSpawn?: (pid: number | undefined) => void;
+    onTimeout?: () => void;
+}
+/** Shared command seam, including invocation-bound manifested runners. */
+export declare function shell(cmd: string, cwd: string, timeoutMs: number, login?: boolean, options?: ShellOptions): Promise<ShResult>;
 export declare function sh(cmd: string, cwd: string, timeoutMs?: number): Promise<ShResult>;
 export declare function shGit(cmd: string, cwd: string, timeoutMs?: number): Promise<ShResult>;
 export declare function shOk(cmd: string, cwd: string): Promise<string>;
@@ -179,3 +188,28 @@ export type BaseContainment = {
  */
 export declare function declaredBaseContainment(cwd: string, declaredRef: string, targetRef?: string): Promise<BaseContainment>;
 export declare function removeWorktree(repo: string, dir: string): Promise<void>;
+export declare const REFS_PREFLIGHT_PREFIX = "refs/tickmarkr/preflight";
+export declare const REFS_PROBE_REMEDY = "run from the main repository or a full clone; a sandbox that denies writes under that path cannot host a run";
+export interface RefsProbeOk {
+    ok: true;
+    path: string;
+    refsDir: string;
+}
+export interface RefsProbeRefusal {
+    ok: false;
+    path: string;
+    refsDir: string;
+    error: string;
+}
+export type RefsProbeResult = RefsProbeOk | RefsProbeRefusal;
+export declare function refsRefusalMessage(action: "run" | "resume", path: string, error: string): string;
+/**
+ * OBS-983/984: prove the repository's common git directory accepts a ref write before starting
+ * the daemon. In a linked worktree, git resolves refs to the main repository's git directory.
+ * Creates and deletes a real ref under refs/tickmarkr/preflight/ through git itself, leaving
+ * nothing behind on success.
+ */
+export declare function probeRefsWritable(cwd?: string): Promise<RefsProbeResult>;
+export declare const probeRefs: typeof probeRefsWritable;
+export declare const refsProbe: typeof probeRefsWritable;
+export declare function assertRefsWritable(cwd?: string, action?: "run" | "resume"): Promise<RefsProbeResult>;

package/dist/run/git.js

@@ -1,6 +1,7 @@
+import { commandLeaseEnvironment, withCommandLease } from "./lease.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { availableParallelism, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
@@ -18,7 +19,7 @@ export const DEFAULT_FORK_CAP = "6";
 /** Worker concurrency is resolved once per run and isolated from other async runs. */
 const forkBudget = new AsyncLocalStorage();
 const verificationBudget = new AsyncLocalStorage();
-/** Verification owns the serialized suite window; workers keep their concurrency budget. */
+/** Verification uses command leases; workers keep their concurrency budget. */
 export const runWithVerificationBudget = (capacity, fn) => verificationBudget.run(capacity, fn);
 /**
  * OBS-618: how many PROCESSES one vitest fork can hold at its peak — the fork, a daemon it spawns,
@@ -128,14 +129,17 @@ export const SPAWN_RETRY_BACKOFF_MS = 50;
 // RULING-P99-28: SHIP — every gate user can hit the inherited-pipe hang at this product seam.
 /** Give a normally-exited shell's descendants this long to close their inherited pipes themselves. */
 const SHELL_REAP_GRACE_MS = 2000;
-// stdin "ignore": same class as HARD-05 / SubprocessDriver — never leave an open pipe a child can block on
-// (pi -p / codex exec wait for stdin EOF). timedOut distinguishes SIGKILL-timeout from a real nonzero exit.
-function shell(cmd, cwd, timeoutMs, login) {
+/** Shared command seam, including invocation-bound manifested runners. */
+export function shell(cmd, cwd, timeoutMs, login = false, options = {}) {
+    return withCommandLease(cmd, () => executeShell(cmd, cwd, timeoutMs, login, options));
+}
+function executeShell(cmd, cwd, timeoutMs, login, options) {
+    options.signal?.throwIfAborted();
     // OBS-74: scrub tickmarkr's own routing env seams from every child — a daemon carrying
     // TICKMARKR_QUALITY leaked it into baseline/gate/tip-verify children, turning a dogfood
     // repo's route() tests red inside the gates. Scrub a copy at this one choke point so
     // children are hermetic by construction; the daemon's own process.env stays unchanged.
-    const env = { ...process.env };
+    const env = commandLeaseEnvironment(options.env ?? process.env);
     for (const k of ROUTING_ENV_SEAMS)
         delete env[k];
     // A run freezes the operator override and cores at startup; admission can lower the round cap.
@@ -163,17 +167,22 @@ function shell(cmd, cwd, timeoutMs, login) {
         const stderrDecoder = new StringDecoder("utf8");
         let timedOut = false, reapedGroup = false, done = false, started = false, outputSeen = false;
         let reapError, exitedCode;
+        let signalExit = false;
         let reapTimer;
+        let drainTimer;
         const finish = (code, err) => {
             if (done)
                 return;
             done = true;
             clearTimeout(timer);
             clearTimeout(reapTimer);
+            clearTimeout(drainTimer);
+            options.signal?.removeEventListener("abort", abort);
             stdout += stdoutDecoder.end();
             stderr += stderrDecoder.end();
             resolve({
                 code,
+                ...(signalExit ? { signalExit: true } : {}),
                 stdout,
                 stderr: err ?? stderr,
                 timedOut,
@@ -183,8 +192,18 @@ function shell(cmd, cwd, timeoutMs, login) {
                 ...(reapError ? { reapError } : {}),
             });
         };
+        // Escaped descendants can retain pipes even after the shell and its group are dead.
+        const boundDrain = () => {
+            if (!done && !drainTimer)
+                drainTimer = setTimeout(() => {
+                    p.stdout?.destroy();
+                    p.stderr?.destroy();
+                    finish(exitedCode ?? 1);
+                }, 100);
+        };
         const timer = setTimeout(() => {
             timedOut = true;
+            options.onTimeout?.();
             try {
                 process.kill(-p.pid, "SIGKILL");
             }
@@ -198,7 +217,21 @@ function shell(cmd, cwd, timeoutMs, login) {
                 if (code !== "ESRCH")
                     finish(exitedCode ?? 1);
             }
+            boundDrain();
         }, timeoutMs);
+        const abort = () => {
+            try {
+                process.kill(-p.pid, "SIGKILL");
+            }
+            catch {
+                p.kill("SIGKILL");
+            }
+            boundDrain();
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        options.onSpawn?.(p.pid);
+        if (options.signal?.aborted)
+            abort();
         p.on("spawn", () => { started = true; }); // the command exists from here on — never retryable past it
         // OBS-716: one stateful decoder per stream carries an incomplete UTF-8 sequence into that
         // stream's next pipe chunk; decoding each chunk through string concatenation corrupts bytes at
@@ -219,22 +252,23 @@ function shell(cmd, cwd, timeoutMs, login) {
             if (!done && !started && !outputSeen && e.code === RETRYABLE_SPAWN_CODE) {
                 done = true;
                 clearTimeout(timer);
+                options.signal?.removeEventListener("abort", abort);
                 resolve({ refused: e });
                 return;
             }
             finish(127, String(e));
         });
-        p.on("close", (code) => finish(code ?? 1));
+        p.on("close", (code) => { signalExit = code === null; finish(code ?? 1); });
         // "close" waits for stdio to drain. Once bash exits normally, give descendants a bounded grace
         // to exit with it; a survivor still in bash's detached group is then reaped so its inherited pipe
         // cannot hold this promise until the command ceiling. A real timeout wins first and is never
         // reclassified as a grace reap.
         p.on("exit", (code) => {
+            signalExit = code === null;
             exitedCode = code ?? 1;
-            if (timedOut) {
-                finish(exitedCode);
+            // Allow a short pipe drain after killing, bounded even for an escaped descendant.
+            if (timedOut)
                 return;
-            }
             reapTimer = setTimeout(() => {
                 if (done)
                     return;
@@ -565,3 +599,70 @@ export async function removeWorktree(repo, dir) {
     await shGit(`rm -rf ${shq(dir)}`, repo);
     await shGit("git worktree prune", repo);
 }
+export const REFS_PREFLIGHT_PREFIX = "refs/tickmarkr/preflight";
+export const REFS_PROBE_REMEDY = "run from the main repository or a full clone; a sandbox that denies writes under that path cannot host a run";
+export function refsRefusalMessage(action, path, error) {
+    return `refusing to ${action}: repository refs directory ${path} is not writable (${error}). `
+        + `Remedy: ${REFS_PROBE_REMEDY}.`;
+}
+/**
+ * OBS-983/984: prove the repository's common git directory accepts a ref write before starting
+ * the daemon. In a linked worktree, git resolves refs to the main repository's git directory.
+ * Creates and deletes a real ref under refs/tickmarkr/preflight/ through git itself, leaving
+ * nothing behind on success.
+ */
+export async function probeRefsWritable(cwd = process.cwd()) {
+    const refsPathRes = await shGit("git rev-parse --git-path refs", cwd);
+    if (refsPathRes.code !== 0) {
+        const error = (refsPathRes.stderr || refsPathRes.stdout).trim() || "git rev-parse --git-path refs failed";
+        return { ok: false, path: "", refsDir: "", error };
+    }
+    const raw = refsPathRes.stdout.trim();
+    let refsDir = resolve(cwd, raw);
+    try {
+        refsDir = realpathSync(refsDir);
+    }
+    catch {
+        // keep resolved path if realpath fails
+    }
+    const headRes = await shGit("git rev-parse HEAD", cwd);
+    const target = headRes.code === 0 && headRes.stdout.trim()
+        ? headRes.stdout.trim()
+        : "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+    const probeId = `probe-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const ref = `${REFS_PREFLIGHT_PREFIX}/${probeId}`;
+    const createRes = await shGit(`git update-ref ${shq(ref)} ${shq(target)}`, cwd);
+    if (createRes.code !== 0) {
+        const error = (createRes.stderr || createRes.stdout).trim() || `git update-ref failed (${createRes.code})`;
+        return { ok: false, path: refsDir, refsDir, error };
+    }
+    const delRes = await shGit(`git update-ref -d ${shq(ref)}`, cwd);
+    if (delRes.code !== 0) {
+        const error = (delRes.stderr || delRes.stdout).trim() || `git update-ref -d failed (${delRes.code})`;
+        return { ok: false, path: refsDir, refsDir, error };
+    }
+    // Clean up empty directories left behind by git
+    try {
+        const preflightDir = join(refsDir, "tickmarkr", "preflight");
+        if (existsSync(preflightDir) && readdirSync(preflightDir).length === 0) {
+            rmSync(preflightDir, { recursive: true, force: true });
+        }
+        const tmDir = join(refsDir, "tickmarkr");
+        if (existsSync(tmDir) && readdirSync(tmDir).length === 0) {
+            rmSync(tmDir, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // best-effort cleanup of empty dirs
+    }
+    return { ok: true, path: refsDir, refsDir };
+}
+export const probeRefs = probeRefsWritable;
+export const refsProbe = probeRefsWritable;
+export async function assertRefsWritable(cwd = process.cwd(), action = "run") {
+    const probe = await probeRefsWritable(cwd);
+    if (!probe.ok) {
+        throw new Error(refsRefusalMessage(action, probe.path, probe.error));
+    }
+    return probe;
+}

package/dist/run/journal.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { type Assignment } from "../adapters/types.js";
 import type { TickmarkrConfig } from "../config/config.js";
-import { type GateName, type Task, type TaskStatus } from "../graph/schema.js";
+import { type GateName, type RunGraph, type Task, type TaskStatus } from "../graph/schema.js";
 import { type ProfileDiscount, type RoutingProfile } from "../route/profile.js";
 import { type DecisionEventWrite, type TrackedJournalRow } from "./protocol.js";
 export interface JournalEvent {
@@ -192,7 +192,7 @@ export declare function pendingRepairFindings(events: JournalEvent[], taskId: st
  * a channel it is no longer using, and a later unrelated failure is not parked under a stale reason.
  */
 export declare function activeRetryBan(events: JournalEvent[], taskId: string, channel: string): string | undefined;
-export declare const PARK_KINDS: readonly ["human-gate", "ladder-exhausted", "attempt-cap", "gate-fail", "quota", "reroute-exhausted", "setup", "stall", "merge-conflict", "tip-moved", "infra", "dispatch", "authoring"];
+export declare const PARK_KINDS: readonly ["human-gate", "ladder-exhausted", "attempt-cap", "gate-fail", "quota", "reroute-exhausted", "setup", "stall", "merge-conflict", "tip-moved", "infra", "dispatch", "authoring", "scope-request"];
 export type ParkKind = (typeof PARK_KINDS)[number];
 export declare const RETRY_MODES: readonly ["resume", "fresh", "repair"];
 export type RetryMode = (typeof RETRY_MODES)[number];
@@ -243,6 +243,7 @@ export declare const TelemetryRowSchema: z.ZodObject<{
         "merge-conflict": "merge-conflict";
         "tip-moved": "tip-moved";
         authoring: "authoring";
+        "scope-request": "scope-request";
     }>>;
     tokens: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         input: z.ZodNumber;
@@ -297,6 +298,17 @@ export declare function gateResultJournalData(gate: string, pass: boolean, detai
     signalQuality: number;
 } & Record<string, unknown>;
 export declare function recordedGraphDefinitionHash(events: JournalEvent[]): string | undefined;
+/** An approval is the durable authority; graph.json is only its materialized projection. */
+export declare const ScopeAmendmentSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    beforeFiles: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodString>;
+    parkLine: z.ZodNumber;
+}, z.core.$strip>;
+export declare function replayScopeAmendments(graph: RunGraph, events: JournalEvent[]): RunGraph;
+/** Publish/recover the audit before dispatch, even after a crash between approval and rehash. */
+export declare function applyScopeAmendments(graph: RunGraph, journal: Journal, auditReplay?: boolean): RunGraph;
 export type EngagementCompare = {
     comparable: true;
     recorded: string;

package/dist/run/journal.js

@@ -3,7 +3,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from
 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";
@@ -773,7 +773,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"];
 // 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 +971,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 +1300,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 +1405,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 +1459,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.

package/dist/run/lease.d.ts

@@ -0,0 +1,14 @@
+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>;
+}

package/dist/run/lease.js

@@ -0,0 +1,87 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+// 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); 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)
+        || 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);
+        }
+    }
+}

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;
     /**