tickmarkr 2.5.5 → 2.5.7

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

@@ -1,3 +1,4 @@
+import type { CommandReceiptAttribution, ShellReceipt } from "./protocol.js";
 import { spawn } from "node:child_process";
 import { ROUTING_ENV_SEAMS } from "../route/router.js";
 export { ROUTING_ENV_SEAMS };
@@ -76,6 +77,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`
@@ -110,10 +151,14 @@ export interface ShellOptions {
     signal?: AbortSignal;
     onSpawn?: (pid: number | undefined) => void;
     onTimeout?: () => void;
+    /** Independent of the legacy pid callback; started means the child emitted spawn. */
+    onReceipt?: (receipt: ShellReceipt) => void;
+    /** Called once per invocation (1-based), including each pre-spawn retry. */
+    receiptAttribution?: (invocation: number) => CommandReceiptAttribution;
 }
 /** 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 sh(cmd: string, cwd: string, timeoutMs?: number, options?: ShellOptions): Promise<ShResult>;
 export declare function shGit(cmd: string, cwd: string, timeoutMs?: number): Promise<ShResult>;
 export declare function shOk(cmd: string, cwd: string): Promise<string>;
 export declare function shGitOk(cmd: string, cwd: string): Promise<string>;

package/dist/run/git.js

@@ -1,8 +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";
@@ -82,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"
@@ -131,10 +212,45 @@ export const SPAWN_RETRY_BACKOFF_MS = 50;
 const SHELL_REAP_GRACE_MS = 2000;
 /** 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));
+    const inherited = executionSignal();
+    const signal = inherited && options.signal ? AbortSignal.any([inherited, options.signal]) : inherited ?? options.signal;
+    let attribution;
+    let confirmedStart = false;
+    let terminal = false;
+    const begin = (invocation) => {
+        attribution = options.receiptAttribution?.(invocation);
+        confirmedStart = false;
+        terminal = false;
+    };
+    const emit = (receipt) => {
+        if (terminal)
+            return;
+        if (receipt.outcome === "started")
+            confirmedStart = true;
+        else
+            terminal = true;
+        // Observational callbacks must not change process cleanup, retries or cancellation.
+        try {
+            options.onReceipt?.({ ...receipt, confirmedStart, ...(attribution ? { attribution: { ...attribution } } : {}) });
+        }
+        catch { /* receipt sinks are observational */ }
+    };
+    const checkAbort = () => {
+        if (signal?.aborted)
+            emit({ outcome: "cancelled", exitCode: null, signal: null });
+        signal?.throwIfAborted();
+    };
+    begin(1);
+    checkAbort();
+    return withCommandLease(cmd, () => executeShell(cmd, cwd, timeoutMs, login, { ...options, signal }, { begin, emit, checkAbort }))
+        .catch((error) => {
+        if (signal?.aborted)
+            emit({ outcome: "cancelled", exitCode: null, signal: null });
+        throw error;
+    });
 }
-function executeShell(cmd, cwd, timeoutMs, login, options) {
-    options.signal?.throwIfAborted();
+function executeShell(cmd, cwd, timeoutMs, login, options, observation) {
+    observation.checkAbort();
     // 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
@@ -161,13 +277,22 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
         // detached: bash gets its own process group so a timeout can kill the whole tree —
         // SIGKILLing bash alone orphans grandchildren (codex/pi) that hold the stdio pipes
         // open, so "close" never fires and the promise wedges forever (v1.33.1 init hang).
-        const p = (spawnChild ?? spawn)("bash", [login ? "-lc" : "-c", cmd], { cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+        let p;
+        try {
+            p = (spawnChild ?? spawn)("bash", [login ? "-lc" : "-c", cmd], { cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+        }
+        catch (error) {
+            observation.emit({ outcome: "spawn-failed", exitCode: null, signal: null, error: String(error) });
+            throw error;
+        }
         let stdout = "", stderr = "";
         const stdoutDecoder = new StringDecoder("utf8");
         const stderrDecoder = new StringDecoder("utf8");
         let timedOut = false, reapedGroup = false, done = false, started = false, outputSeen = false;
         let reapError, exitedCode;
         let signalExit = false;
+        let exitSignal = null;
+        let spawnError;
         let reapTimer;
         let drainTimer;
         const finish = (code, err) => {
@@ -180,6 +305,12 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
             options.signal?.removeEventListener("abort", abort);
             stdout += stdoutDecoder.end();
             stderr += stderrDecoder.end();
+            observation.emit({
+                outcome: options.signal?.aborted ? "cancelled" : timedOut ? "timed-out" : spawnError ? "spawn-failed" : "completed",
+                pid: p.pid, exitCode: signalExit || spawnError ? null : code,
+                signal: exitSignal, ...(spawnError ? { error: spawnError } : {}),
+                durationMs: Date.now() - startedAt,
+            });
             resolve({
                 code,
                 ...(signalExit ? { signalExit: true } : {}),
@@ -232,7 +363,7 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
         options.onSpawn?.(p.pid);
         if (options.signal?.aborted)
             abort();
-        p.on("spawn", () => { started = true; }); // the command exists from here on — never retryable past it
+        p.on("spawn", () => { started = true; observation.emit({ outcome: "started", pid: p.pid }); }); // 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
         // kernel-chosen boundaries. A deterministic fixture proves this decoder correct rather than
@@ -249,21 +380,24 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
             stderr += stderrDecoder.write(d);
         });
         p.on("error", (e) => {
+            spawnError = String(e);
             if (!done && !started && !outputSeen && e.code === RETRYABLE_SPAWN_CODE) {
                 done = true;
                 clearTimeout(timer);
                 options.signal?.removeEventListener("abort", abort);
+                observation.emit({ outcome: "spawn-failed", exitCode: null, signal: null, error: String(e), durationMs: Date.now() - startedAt });
                 resolve({ refused: e });
                 return;
             }
             finish(127, String(e));
         });
-        p.on("close", (code) => { signalExit = code === null; finish(code ?? 1); });
+        p.on("close", (code, signal) => { signalExit = code === null; exitSignal = signal; 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) => {
+        p.on("exit", (code, signal) => {
+            exitSignal = signal;
             signalExit = code === null;
             exitedCode = code ?? 1;
             // Allow a short pipe drain after killing, bounded even for an escaped descendant.
@@ -289,6 +423,9 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
     return (async () => {
         const startedAt = Date.now();
         for (let n = 1;; n++) {
+            if (n > 1)
+                observation.begin(n);
+            observation.checkAbort();
             const r = await attempt();
             if (!("refused" in r))
                 return r;
@@ -301,8 +438,8 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
         }
     })();
 }
-export function sh(cmd, cwd, timeoutMs = DEFAULT_SHELL_TIMEOUT_MS) {
-    return shell(cmd, cwd, timeoutMs, true);
+export function sh(cmd, cwd, timeoutMs = DEFAULT_SHELL_TIMEOUT_MS, options = {}) {
+    return shell(cmd, cwd, timeoutMs, true, options);
 }
 // Git plumbing never needs an operator profile; skip login-shell startup and its side effects.
 export function shGit(cmd, cwd, timeoutMs = DEFAULT_SHELL_TIMEOUT_MS) {

package/dist/run/journal.d.ts

@@ -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
@@ -143,8 +144,11 @@ export declare function pendingRechecks(events: JournalEvent[]): Set<string>;
  * `task-dispatch`: everything between the two — worktree recreation, setup, prompt write, slot
  * allocation, the launch itself — can still die with no worker having read a word, and clearing at
  * task-dispatch meant `--retry-failed` after exactly that death rebuilt the prompt without the gate
- * failures OR the delivery failure that preceded it. `task-approved` also clears (an operator approval
- * retires the findings it settled — the uphold case re-derives its own brief separately).
+ * failures OR the delivery failure that preceded it. Of the approvals, only a WAIVE clears (the operator
+ * retired the findings by fiat — the uphold case re-derives its own brief separately). OBS-1074: a
+ * plain approve, a scope grant or a recheck re-funds an attempt that must still see why the last one
+ * parked, plus the operator's stated reason — v2.5.7's T11 looped four times on one hygiene oracle
+ * because every approval erased exactly the finding the fresh attempt was funded to fix.
  */
 export declare function journaledFailureBrief(events: JournalEvent[], taskId: string): string[];
 /**
@@ -192,7 +196,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", "scope-request"];
+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];
@@ -244,6 +248,7 @@ export declare const TelemetryRowSchema: z.ZodObject<{
         "tip-moved": "tip-moved";
         authoring: "authoring";
         "scope-request": "scope-request";
+        "diff-cap": "diff-cap";
     }>>;
     tokens: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         input: z.ZodNumber;
@@ -298,6 +303,13 @@ export declare function gateResultJournalData(gate: string, pass: boolean, detai
     signalQuality: number;
 } & Record<string, unknown>;
 export declare function recordedGraphDefinitionHash(events: JournalEvent[]): string | undefined;
+/**
+ * OBS-1073 residual: the `--graph-changed` release belongs to the ENGAGEMENT, not to the launch call. The
+ * daemon writes it on the run-resume row; every replay that runs inside that engagement from another
+ * process (the approve CLI) reads it back here. Without it the first in-run approval after a released
+ * launch re-ran the whole-graph asserts the launch had waived and killed the daemon (v2.5.7 run …152220).
+ */
+export declare function engagementReleased(events: JournalEvent[]): boolean;
 /** An approval is the durable authority; graph.json is only its materialized projection. */
 export declare const ScopeAmendmentSchema: z.ZodObject<{
     from: z.ZodString;
@@ -305,10 +317,16 @@ export declare const ScopeAmendmentSchema: z.ZodObject<{
     beforeFiles: z.ZodArray<z.ZodString>;
     files: z.ZodArray<z.ZodString>;
     parkLine: z.ZodNumber;
+    definition: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare function replayScopeAmendments(graph: RunGraph, events: JournalEvent[]): RunGraph;
+/**
+ * `release` is the operator's audited `--graph-changed`. `approvedDefinitions` supplies, per amended task,
+ * the definition fingerprint the amendment was granted against when the row itself carries none (rows
+ * older than v2.5.7): the caller reads it from the run's materialized graph snapshot.
+ */
+export declare function replayScopeAmendments(graph: RunGraph, events: JournalEvent[], release?: boolean, approvedDefinitions?: ReadonlyMap<string, string>): 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 declare function applyScopeAmendments(graph: RunGraph, journal: Journal, auditReplay?: boolean, release?: boolean): RunGraph;
 export type EngagementCompare = {
     comparable: true;
     recorded: string;