tickmarkr 2.5.4 → 2.5.6

package/dist/run/execution-budget.d.ts

@@ -0,0 +1,25 @@
+export declare class ExecutionBudgetExceeded extends Error {
+    readonly taskId: string;
+    constructor(taskId: string, reason?: string);
+}
+export interface ExecutionBudgetEvent {
+    event: string;
+    taskId?: string;
+    data: Record<string, unknown>;
+}
+export interface ExecutionBudgetOptions {
+    limitMs: number;
+    taskId: string;
+    readEvents: () => readonly ExecutionBudgetEvent[];
+    append: (event: string, taskId: string, data: Record<string, unknown>) => void;
+}
+export declare const executionSignal: () => AbortSignal | undefined;
+/** Cleanup only: the caller must bound cleanup and must not authorize task work here. */
+export declare const withoutExecutionBudget: <T>(run: () => T) => T;
+export declare const remainingExecutionMs: () => number | undefined;
+/** One wall-clock interval around task execution, shared by parallel children. Cancellation is
+ * cooperative: callers must stop on executionSignal(), and this wrapper waits for their cleanup.
+ * Durable slices are bought before work: at least one minute or 1% of the task ceiling, capped
+ * by what remains. This avoids a per-second journal stream. An interrupted slice stays fully
+ * charged, conservatively consuming its unused portion; daemon-offline time is never charged. */
+export declare function withExecutionBudget<T>(opts: ExecutionBudgetOptions, run: () => Promise<T>): Promise<T>;

package/dist/run/execution-budget.js

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+export class ExecutionBudgetExceeded extends Error {
+    taskId;
+    constructor(taskId, reason = "automated execution ceiling exhausted") {
+        super(`${taskId}: ${reason}`);
+        this.taskId = taskId;
+        this.name = "ExecutionBudgetExceeded";
+    }
+}
+const context = new AsyncLocalStorage();
+const MIN_SLICE_MS = 60_000;
+const finite = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+function consumed(opts) {
+    const reservations = new Map();
+    for (const e of opts.readEvents()) {
+        if (e.taskId !== opts.taskId || !["execution-budget-reserved", "execution-budget-settled"].includes(e.event))
+            continue;
+        const d = e.data;
+        if (!d || d.limitMs !== opts.limitMs || typeof d.id !== "string" || !d.id) {
+            throw new ExecutionBudgetExceeded(opts.taskId, "invalid execution budget accounting");
+        }
+        if (e.event === "execution-budget-reserved") {
+            if (!finite(d.reservedMs) || d.reservedMs === 0 || reservations.has(d.id)) {
+                throw new ExecutionBudgetExceeded(opts.taskId, "invalid execution reservation");
+            }
+            reservations.set(d.id, { reserved: d.reservedMs });
+        }
+        else {
+            const prior = reservations.get(d.id);
+            if (!prior || prior.used !== undefined || !finite(d.usedMs) || d.usedMs > prior.reserved) {
+                throw new ExecutionBudgetExceeded(opts.taskId, "invalid execution settlement");
+            }
+            prior.used = d.usedMs;
+        }
+    }
+    const total = [...reservations.values()].reduce((sum, r) => sum + (r.used ?? r.reserved), 0);
+    if (!finite(total) || total > opts.limitMs)
+        throw new ExecutionBudgetExceeded(opts.taskId, "invalid execution total");
+    return total;
+}
+export const executionSignal = () => {
+    const budget = context.getStore();
+    budget?.check();
+    return budget?.signal;
+};
+/** Cleanup only: the caller must bound cleanup and must not authorize task work here. */
+export const withoutExecutionBudget = (run) => context.exit(run);
+export const remainingExecutionMs = () => context.getStore()?.remaining();
+/** One wall-clock interval around task execution, shared by parallel children. Cancellation is
+ * cooperative: callers must stop on executionSignal(), and this wrapper waits for their cleanup.
+ * Durable slices are bought before work: at least one minute or 1% of the task ceiling, capped
+ * by what remains. This avoids a per-second journal stream. An interrupted slice stays fully
+ * charged, conservatively consuming its unused portion; daemon-offline time is never charged. */
+export async function withExecutionBudget(opts, run) {
+    if (!finite(opts.limitMs) || opts.limitMs === 0 || !opts.taskId)
+        throw new ExecutionBudgetExceeded(opts.taskId, "invalid execution ceiling");
+    const parent = context.getStore();
+    if (parent) {
+        if (parent.taskId !== opts.taskId || parent.limitMs !== opts.limitMs)
+            throw new ExecutionBudgetExceeded(opts.taskId, "nested execution budget mismatch");
+        parent.check();
+        parent.signal.throwIfAborted();
+        return run();
+    }
+    const prior = consumed(opts);
+    const available = opts.limitMs - prior;
+    const sliceMs = Math.max(MIN_SLICE_MS, opts.limitMs / 100);
+    if (available <= 0)
+        throw new ExecutionBudgetExceeded(opts.taskId);
+    const controller = new AbortController();
+    const start = performance.now();
+    let reserved = 0;
+    let current;
+    let timer;
+    const elapsed = () => Math.max(0, performance.now() - start);
+    const remaining = () => Math.max(0, available - elapsed());
+    const stop = (error) => controller.abort(error instanceof Error ? error : new ExecutionBudgetExceeded(opts.taskId));
+    const buy = (amount) => {
+        if (amount <= 0)
+            return;
+        const next = { id: randomUUID(), before: reserved, amount };
+        opts.append("execution-budget-reserved", opts.taskId, { id: next.id, limitMs: opts.limitMs, reservedMs: amount });
+        current = next;
+        reserved += amount;
+    };
+    // JS timers cannot preempt a blocked event loop. Charge elapsed overruns before another
+    // observable operation or completion; expiration consumes the whole allowance across resume.
+    const check = () => {
+        try {
+            const used = Math.min(available, elapsed());
+            if (used > reserved)
+                buy(used - reserved);
+            if (used >= available)
+                stop(new ExecutionBudgetExceeded(opts.taskId));
+        }
+        catch (error) {
+            stop(error);
+        }
+    };
+    const reserve = () => {
+        if (elapsed() >= available)
+            check();
+        if (controller.signal.aborted)
+            return;
+        buy(Math.min(available - reserved, Math.max(sliceMs, elapsed() - reserved + sliceMs)));
+        timer = setTimeout(() => {
+            try {
+                reserve();
+            }
+            catch (error) {
+                stop(error);
+            }
+        }, Math.max(0, reserved - elapsed()));
+    };
+    reserve();
+    controller.signal.throwIfAborted();
+    const budget = { taskId: opts.taskId, limitMs: opts.limitMs, signal: controller.signal, remaining, check };
+    try {
+        return await context.run(budget, async () => {
+            controller.signal.throwIfAborted();
+            const result = await run();
+            check();
+            controller.signal.throwIfAborted();
+            return result;
+        });
+    }
+    catch (error) {
+        check();
+        controller.signal.throwIfAborted();
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        check();
+        if (current) {
+            const usedMs = Math.min(current.amount, Math.max(0, elapsed() - current.before));
+            opts.append("execution-budget-settled", opts.taskId, { id: current.id, limitMs: opts.limitMs, usedMs });
+        }
+        controller.signal.throwIfAborted();
+    }
+}

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,
@@ -76,6 +76,46 @@ export declare function readCapacity(value: unknown): CapacityRead;
  * different capacity, or a current capacity the caller could not state → no.
  */
 export declare function sameCapacity(recorded: unknown, current: RunCapacity | undefined): boolean;
+/**
+ * R41: the verification PROTOCOL a verdict was produced under — which implementation of the manifest
+ * discovery/report contract judged it, and the npm lifecycle policy its runner children ran with.
+ * Two verdicts are comparable only when both match: a manifest built from module collection ("vl1.1",
+ * the pre-stamp implementation) and one built from file specifications ("vl1.2") certify different
+ * sets, and a suite whose `pretest` hook ran (ignore-scripts=false) is a different measurement from
+ * one where npm skipped it. Bump VERIFICATION_PROTOCOL whenever discovery or report semantics change.
+ */
+export declare const VERIFICATION_PROTOCOL = "vl1.2";
+export type RunnerLifecycle = "hooks" | "ignore-scripts" | "unknown";
+export interface VerificationProtocol {
+    protocol: string;
+    /** The EFFECTIVE npm lifecycle policy a runner child receives: `hooks` (pretest/prebuild run),
+     * `ignore-scripts` (npm skips them), or `unknown` (could not be measured — never comparable). */
+    lifecycle: RunnerLifecycle;
+    /** Provenance only, never part of compatibility: an explicit process-scoped env export, or npm's
+     * own resolved config for that checkout (user/project npmrc). */
+    source: "explicit" | "npm-config" | "unknown";
+}
+/**
+ * R41: the lifecycle policy a runner child spawned from `env` in `cwd` receives. An explicit
+ * process-scoped `npm_config_ignore_scripts` export decides (npm reads env over every npmrc) and is
+ * recorded as such; otherwise the policy is MEASURED from npm's own resolved config for that checkout
+ * (`npm config get ignore-scripts` — user npmrc, project npmrc, env), so the identity binds what
+ * npm will actually do rather than a guess. A policy that cannot be measured is `unknown`, and an
+ * unknown policy is never compatible with anything, itself included. No env or npmrc is written here.
+ */
+export declare function runnerLifecycle(env?: NodeJS.ProcessEnv, cwd?: string): Pick<VerificationProtocol, "lifecycle" | "source">;
+export declare function verificationProtocol(env?: NodeJS.ProcessEnv, cwd?: string): VerificationProtocol;
+/**
+ * May a verdict recorded under `recorded` be reused — cached, replayed — by a session running
+ * `current`? Unlike capacity, ABSENT is NOT compatible: a row with no protocol stamp was produced by
+ * the pre-stamp implementation (module-collection discovery, lifecycle unstated), which is exactly
+ * the evidence a changed protocol must not inherit — positive or negative. Malformed → no. An
+ * `unknown` lifecycle on either side → no: two unmeasured policies are not the same policy.
+ * `source` is provenance and never enters the comparison — an explicit `false` and an npmrc `false`
+ * are the same effective policy.
+ */
+export declare function sameVerification(recorded: unknown, current: VerificationProtocol): boolean;
+export declare const describeVerification: (value: unknown) => string;
 export declare const describeCapacity: (value: unknown) => string;
 /**
  * The capacity a child spawned on THIS async context would receive: the same precedence `shell`
@@ -89,6 +129,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 +145,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>;

package/dist/run/git.js

@@ -1,7 +1,9 @@
+import { executionSignal } from "./execution-budget.js";
+import { commandLeaseEnvironment, withCommandLease } from "./lease.js";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { spawn } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { availableParallelism, tmpdir } from "node:os";
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { availableParallelism, homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { shq } from "../adapters/types.js";
@@ -18,7 +20,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,
@@ -81,6 +83,86 @@ export function sameCapacity(recorded, current) {
         return false;
     return read.capacity.forkCap === current.forkCap && read.capacity.cores === current.cores;
 }
+/**
+ * R41: the verification PROTOCOL a verdict was produced under — which implementation of the manifest
+ * discovery/report contract judged it, and the npm lifecycle policy its runner children ran with.
+ * Two verdicts are comparable only when both match: a manifest built from module collection ("vl1.1",
+ * the pre-stamp implementation) and one built from file specifications ("vl1.2") certify different
+ * sets, and a suite whose `pretest` hook ran (ignore-scripts=false) is a different measurement from
+ * one where npm skipped it. Bump VERIFICATION_PROTOCOL whenever discovery or report semantics change.
+ */
+export const VERIFICATION_PROTOCOL = "vl1.2";
+const lifecycleOf = (raw) => {
+    const v = raw?.trim().toLowerCase();
+    return v === "false" ? "hooks" : v === "true" ? "ignore-scripts" : undefined;
+};
+// Measured effective policy, keyed on everything npm resolves it from that this process can see:
+// the checkout, its project npmrc and the user npmrc (path + mtime), and the explicit env. A
+// rewritten npmrc changes the key, so a later battery in the same process re-measures.
+const measuredLifecycle = new Map();
+const mtimeOf = (p) => { try {
+    return String(statSync(p).mtimeMs);
+}
+catch {
+    return "-";
+} };
+/**
+ * R41: the lifecycle policy a runner child spawned from `env` in `cwd` receives. An explicit
+ * process-scoped `npm_config_ignore_scripts` export decides (npm reads env over every npmrc) and is
+ * recorded as such; otherwise the policy is MEASURED from npm's own resolved config for that checkout
+ * (`npm config get ignore-scripts` — user npmrc, project npmrc, env), so the identity binds what
+ * npm will actually do rather than a guess. A policy that cannot be measured is `unknown`, and an
+ * unknown policy is never compatible with anything, itself included. No env or npmrc is written here.
+ */
+export function runnerLifecycle(env = process.env, cwd = process.cwd()) {
+    const explicit = lifecycleOf(env.npm_config_ignore_scripts ?? env.NPM_CONFIG_IGNORE_SCRIPTS);
+    if (explicit)
+        return { lifecycle: explicit, source: "explicit" };
+    const userconfig = env.NPM_CONFIG_USERCONFIG ?? env.npm_config_userconfig ?? join(homedir(), ".npmrc");
+    const key = [cwd, mtimeOf(join(cwd, ".npmrc")), userconfig, mtimeOf(userconfig),
+        env.npm_config_ignore_scripts ?? env.NPM_CONFIG_IGNORE_SCRIPTS ?? ""].join("\0");
+    let lifecycle = measuredLifecycle.get(key);
+    if (lifecycle === undefined) {
+        try {
+            const out = execFileSync("npm", ["config", "get", "ignore-scripts"], {
+                cwd: existsSync(cwd) ? cwd : process.cwd(), env, encoding: "utf8", timeout: 15_000, stdio: ["ignore", "pipe", "ignore"],
+            });
+            lifecycle = lifecycleOf(out) ?? "unknown";
+        }
+        catch {
+            lifecycle = "unknown";
+        }
+        measuredLifecycle.set(key, lifecycle);
+    }
+    return { lifecycle, source: lifecycle === "unknown" ? "unknown" : "npm-config" };
+}
+export function verificationProtocol(env = process.env, cwd = process.cwd()) {
+    return { protocol: VERIFICATION_PROTOCOL, ...runnerLifecycle(env, cwd) };
+}
+/**
+ * May a verdict recorded under `recorded` be reused — cached, replayed — by a session running
+ * `current`? Unlike capacity, ABSENT is NOT compatible: a row with no protocol stamp was produced by
+ * the pre-stamp implementation (module-collection discovery, lifecycle unstated), which is exactly
+ * the evidence a changed protocol must not inherit — positive or negative. Malformed → no. An
+ * `unknown` lifecycle on either side → no: two unmeasured policies are not the same policy.
+ * `source` is provenance and never enters the comparison — an explicit `false` and an npmrc `false`
+ * are the same effective policy.
+ */
+export function sameVerification(recorded, current) {
+    if (recorded === null || typeof recorded !== "object")
+        return false;
+    const { protocol, lifecycle } = recorded;
+    if (lifecycle === "unknown" || current.lifecycle === "unknown")
+        return false;
+    return protocol === current.protocol && lifecycle === current.lifecycle;
+}
+export const describeVerification = (value) => {
+    if (value === null || typeof value !== "object")
+        return "an unrecorded verification protocol";
+    const { protocol, lifecycle, source } = value;
+    return typeof protocol === "string" && typeof lifecycle === "string"
+        ? `protocol ${protocol}, lifecycle ${lifecycle}${typeof source === "string" ? ` (${source})` : ""}` : "a malformed verification protocol";
+};
 export const describeCapacity = (value) => {
     const read = readCapacity(value);
     return read.state === "present"
@@ -128,14 +210,20 @@ 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 = {}) {
+    const inherited = executionSignal();
+    const signal = inherited && options.signal ? AbortSignal.any([inherited, options.signal]) : inherited ?? options.signal;
+    signal?.throwIfAborted();
+    return withCommandLease(cmd, () => executeShell(cmd, cwd, timeoutMs, login, { ...options, signal }));
+}
+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 +251,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 +276,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 +301,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 +336,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;
@@ -255,6 +373,7 @@ function shell(cmd, cwd, timeoutMs, login) {
     return (async () => {
         const startedAt = Date.now();
         for (let n = 1;; n++) {
+            options.signal?.throwIfAborted();
             const r = await attempt();
             if (!("refused" in r))
                 return r;

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 {
@@ -60,6 +60,7 @@ export interface ConsultGuidanceCarry {
  */
 export declare function outstandingConsultGuidance(events: JournalEvent[], taskId: string): ConsultGuidanceCarry | undefined;
 export declare const UNIDENTIFIED = "<unidentified>";
+export declare function boundedSymbol(note: string): string;
 /**
  * Structured findings for a BLOCKING review/judge gate result, parsed from the details the gate
  * already writes (D-03: no gate-module change, so an older gate's prose degrades to one unclassified
@@ -192,7 +193,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", "diff-cap"];
 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 +244,8 @@ export declare const TelemetryRowSchema: z.ZodObject<{
         "merge-conflict": "merge-conflict";
         "tip-moved": "tip-moved";
         authoring: "authoring";
+        "scope-request": "scope-request";
+        "diff-cap": "diff-cap";
     }>>;
     tokens: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         input: z.ZodNumber;
@@ -297,6 +300,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;