@davesheffer/hunch 1.45.1 → 1.46.0

package/dist/core/boundedSpawn.js

@@ -0,0 +1,321 @@
+/** Run a child process under our own timer and kill its WHOLE tree on timeout
+ * (issues #44, #489, #498).
+ *
+ * Node's `timeout` option on spawn/execFile/execFileSync/spawnSync kills only
+ * the root process. On Windows that root is often a wrapper (cmd.exe for a
+ * `.cmd` shim, or Git for Windows' `cmd\git.exe`), so the real worker (the
+ * agent CLI, or `git.exe` / `git-remote-https.exe`) keeps running as an
+ * orphan. Running `taskkill /T` afterwards is too late: the root is gone, so
+ * the tree can no longer be reached by parent pid.
+ *
+ * Both forms here run the command under a small Node supervisor that owns the
+ * deadline and kills the tree while the root still exists:
+ * - Windows: `taskkill /pid <root> /T /F` runs to completion BEFORE the root
+ *   is killed.
+ * - POSIX: the descendants are found by walking a `ps -A -o pid=,ppid=`
+ *   snapshot (on Linux without ps, `/proc/<pid>/stat`) from the root, taken
+ *   while the root is still alive. The tree gets
+ *   SIGTERM first (git removes its ref/pack lock files on SIGTERM, not on
+ *   SIGKILL), then SIGKILL for whatever is still alive after a short grace.
+ *
+ * The child is NOT detached: it stays in Hunch's process group, so a terminal
+ * Ctrl-C still reaches it directly. The supervisor's timer is always cleared,
+ * and a timeout is reported as a result (`timedOut`), never a hang.
+ *
+ * Cost: one extra Node startup (~30 ms) per call, so this is for network or
+ * long-running commands, not hot local git calls. */
+import { spawn, spawnSync } from "node:child_process";
+const RESULT_SENTINEL = "\n__HUNCH_BOUNDED_SPAWN_RESULT__";
+const DEFAULT_KILL_GRACE_MS = 1_500;
+/** Plain-JS supervisor run as `node -e`. Reads a JSON spec on stdin, runs the
+ *  command, forwards its stdout/stderr, and appends one sentinel line with the
+ *  outcome to stderr. */
+const SUPERVISOR = `
+const { spawn, execFile } = require("node:child_process");
+const SENTINEL = ${JSON.stringify(RESULT_SENTINEL)};
+const win = process.platform === "win32";
+let raw = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  const spec = JSON.parse(raw);
+  const result = { status: null, signal: null, timedOut: false, overflowed: false, killSignal: null, error: null };
+  let child = null, timer = null, finished = false, killing = false, bytes = 0, errBytes = 0;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    if (timer) { clearTimeout(timer); timer = null; }
+    if (child) {
+      if (child.stdout) child.stdout.destroy();
+      if (child.stderr) child.stderr.destroy();
+      child.unref();
+    }
+    process.stderr.write(SENTINEL + JSON.stringify(result) + "\\n");
+  };
+  const rootGone = () => child.exitCode !== null || child.signalCode !== null;
+  const alive = (pid) => {
+    if (pid === child.pid) return !rootGone();
+    try { process.kill(pid, 0); return true; } catch (e) { return false; }
+  };
+  // pid -> ppid for every process: ps, else (Linux without procps, e.g.
+  // busybox) /proc/*/stat, else an empty map (only the root gets signalled).
+  const snapshot = (cb) => {
+    execFile(spec.psFile || "ps", ["-A", "-o", "pid=,ppid="], { timeout: 2000, windowsHide: true }, (err, out) => {
+      const ppids = new Map();
+      if (!err) {
+        for (const line of String(out).split("\\n")) {
+          const f = line.trim().split(/\\s+/);
+          if (f.length >= 2) ppids.set(Number(f[0]), Number(f[1]));
+        }
+        return cb(ppids);
+      }
+      if (process.platform !== "linux") return cb(ppids);
+      try {
+        const fs = require("node:fs");
+        for (const d of fs.readdirSync("/proc")) {
+          if (!/^\\d+$/.test(d)) continue;
+          try {
+            // "pid (comm) state ppid ...": comm may hold spaces and ')', so
+            // parse past the LAST ')'.
+            const stat = fs.readFileSync("/proc/" + d + "/stat", "utf8");
+            const f = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+            ppids.set(Number(d), Number(f[1]));
+          } catch (e) { /* exited mid-scan */ }
+        }
+      } catch (e) {}
+      cb(ppids);
+    });
+  };
+  // Every pid reachable from roots in a pid -> ppid snapshot (roots included).
+  const reach = (roots, ppids) => {
+    const kids = new Map();
+    for (const [pid, ppid] of ppids) {
+      if (!kids.has(ppid)) kids.set(ppid, []);
+      kids.get(ppid).push(pid);
+    }
+    const seen = new Set(roots), stack = roots.slice();
+    while (stack.length) {
+      for (const c of kids.get(stack.pop()) || []) {
+        if (c !== process.pid && !seen.has(c)) { seen.add(c); stack.push(c); }
+      }
+    }
+    return Array.from(seen);
+  };
+  const signalAll = (pids, sig) => {
+    // Descendants first, the root last: the root stays alive (and the tree
+    // reachable) for as long as possible.
+    for (const pid of pids) {
+      if (pid === child.pid) continue;
+      try { process.kill(pid, sig); } catch (e) {}
+    }
+    try { child.kill(sig); } catch (e) {}
+  };
+  const killTree = () => {
+    if (killing) return;
+    killing = true;
+    if (!child || !child.pid) return finish();
+    if (win) {
+      execFile("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true, timeout: 10000 }, () => {
+        try { child.kill("SIGKILL"); } catch (e) {}
+        result.killSignal = "SIGKILL";
+        finish();
+      });
+      return;
+    }
+    snapshot((ppids) => {
+      const pids = reach([child.pid], ppids);
+      signalAll(pids, "SIGTERM");
+      result.killSignal = "SIGTERM";
+      const deadline = Date.now() + spec.killGraceMs;
+      const poll = () => {
+        const left = pids.filter(alive);
+        if (left.length === 0) return finish();
+        if (Date.now() < deadline) { setTimeout(poll, 50); return; }
+        // Re-walk from the survivors: anything they spawned during the grace.
+        snapshot((now) => {
+          const rest = reach(left, now);
+          for (const pid of rest) { try { process.kill(pid, "SIGKILL"); } catch (e) {} }
+          try { child.kill("SIGKILL"); } catch (e) {}
+          result.killSignal = "SIGKILL";
+          finish();
+        });
+      };
+      poll();
+    });
+  };
+  const hasInput = typeof spec.input === "string";
+  try {
+    child = spawn(spec.file, spec.args, {
+      cwd: spec.cwd || undefined,
+      env: spec.env || process.env,
+      stdio: [hasInput ? "pipe" : "ignore", spec.stdout, "pipe"],
+      shell: spec.shell === true,
+      windowsHide: true,
+    });
+  } catch (e) {
+    result.error = { code: e && e.code, message: String(e && e.message) };
+    return finish();
+  }
+  if (spec.timeoutMs > 0) {
+    timer = setTimeout(() => { timer = null; if (finished) return; result.timedOut = true; killTree(); }, spec.timeoutMs);
+  }
+  if (child.stdout) child.stdout.on("data", (c) => {
+    if (killing) return;
+    bytes += c.length;
+    if (bytes > spec.maxBuffer) {
+      result.overflowed = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+      return killTree();
+    }
+    process.stdout.write(c);
+  });
+  child.stderr.on("data", (c) => {
+    if (killing || errBytes > spec.maxBuffer) return;
+    errBytes += c.length;
+    process.stderr.write(c);
+  });
+  child.on("error", (e) => { if (killing) return; result.error = { code: e && e.code, message: String(e && e.message) }; finish(); });
+  child.on("close", (code, signal) => {
+    if (killing) return;
+    result.status = code;
+    result.signal = signal;
+    finish();
+  });
+  if (hasInput) {
+    child.stdin.on("error", () => {});
+    child.stdin.end(spec.input);
+  }
+});
+`;
+let psFileOverride = null;
+/** Test seam: replace the ps binary used for the POSIX tree snapshot
+ *  (null restores "ps"). Not for production callers. */
+export function __setPsFileForTests(file) {
+    psFileOverride = file;
+}
+function supervisorRequest(file, args, opts) {
+    const maxBuffer = opts.maxBuffer ?? 16 * 1024 * 1024;
+    const spec = JSON.stringify({
+        file, args,
+        cwd: opts.cwd ?? null,
+        env: opts.env ?? process.env,
+        input: opts.input ?? null,
+        timeoutMs: opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : 0,
+        killGraceMs: opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS,
+        maxBuffer,
+        shell: opts.shell === true,
+        stdout: opts.stdout ?? "pipe",
+        psFile: psFileOverride,
+    });
+    // The supervisor itself must not inherit user NODE_OPTIONS (loaders, --inspect).
+    const env = { ...process.env, ELECTRON_RUN_AS_NODE: "1" };
+    delete env.NODE_OPTIONS;
+    // Backstop only, if the supervisor itself wedges: its own timer is the real bound.
+    const backstopMs = opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs + (opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS) + 15_000 : undefined;
+    return { spec, env, maxBuffer, backstopMs };
+}
+function toResult(stdout, rawErr, failure) {
+    const at = rawErr.lastIndexOf(RESULT_SENTINEL);
+    const stderr = at >= 0 ? rawErr.slice(0, at) : rawErr;
+    let outcome = null;
+    if (at >= 0) {
+        try {
+            outcome = JSON.parse(rawErr.slice(at + RESULT_SENTINEL.length).trim());
+        }
+        catch {
+            outcome = null;
+        }
+    }
+    const result = { stdout, stderr, status: null, signal: null, timedOut: false, overflowed: false };
+    if (!outcome) {
+        const error = new Error(`bounded spawn supervisor ${failure.error ? `failed: ${failure.error.message}` : `exited ${failure.status ?? failure.signal} without a result`}`);
+        error.code = failure.error?.code ?? "ESUPERVISOR";
+        result.error = error;
+        result.signal = failure.signal;
+        return result;
+    }
+    if (outcome.error) {
+        const error = new Error(outcome.error.message);
+        if (outcome.error.code)
+            error.code = outcome.error.code;
+        result.error = error;
+    }
+    result.timedOut = outcome.timedOut;
+    result.overflowed = outcome.overflowed;
+    result.status = outcome.status;
+    result.signal = outcome.killSignal ?? outcome.signal;
+    return result;
+}
+/** Async bounded run. Always resolves; inspect `timedOut` / `error` / `status`. */
+export function boundedSpawn(file, args, opts = {}) {
+    const { spec, env, maxBuffer, backstopMs } = supervisorRequest(file, args, opts);
+    return new Promise((resolve) => {
+        const out = [];
+        const err = [];
+        let outLen = 0;
+        let backstop = null;
+        let settled = false;
+        const supervisor = spawn(process.execPath, ["-e", SUPERVISOR], { env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+        const settle = (failure) => {
+            if (settled)
+                return;
+            settled = true;
+            if (backstop) {
+                clearTimeout(backstop);
+                backstop = null;
+            }
+            resolve(toResult(Buffer.concat(out).toString("utf8"), Buffer.concat(err).toString("utf8"), failure));
+        };
+        if (backstopMs)
+            backstop = setTimeout(() => { backstop = null; supervisor.kill("SIGKILL"); }, backstopMs);
+        supervisor.stdout.on("data", (d) => { if (outLen <= maxBuffer) {
+            out.push(d);
+            outLen += d.length;
+        } });
+        supervisor.stderr.on("data", (d) => { err.push(d); });
+        supervisor.on("error", (error) => settle({ error, status: null, signal: null }));
+        supervisor.on("close", (status, signal) => settle({ status, signal }));
+        supervisor.stdin.on("error", () => { });
+        supervisor.stdin.end(spec);
+    });
+}
+/** Synchronous bounded run, spawnSync-shaped: never throws. */
+export function boundedSpawnSync(file, args, opts) {
+    const stdoutMode = opts.stdout ?? "pipe";
+    const { spec, env, maxBuffer, backstopMs } = supervisorRequest(file, args, {
+        ...opts,
+        timeoutMs: opts.timeout,
+        maxBuffer: opts.maxBuffer ?? 64 * 1024 * 1024,
+        stdout: typeof stdoutMode === "number" ? "inherit" : stdoutMode,
+    });
+    const run = spawnSync(process.execPath, ["-e", SUPERVISOR], {
+        input: spec,
+        stdio: ["pipe", typeof stdoutMode === "number" ? stdoutMode : "pipe", "pipe"],
+        env,
+        windowsHide: true,
+        maxBuffer: maxBuffer * 2 + 1024 * 1024,
+        timeout: backstopMs,
+    });
+    return toResult(run.stdout ? run.stdout.toString("utf8") : "", run.stderr ? run.stderr.toString("utf8") : "", run);
+}
+/** Synchronous bounded exec: returns stdout (utf8) on exit 0, throws a
+ *  BoundedExecError otherwise. On timeout the error carries
+ *  `code: "ETIMEDOUT"` and the signal actually delivered to the tree. */
+export function boundedExecFileSync(file, args, opts) {
+    const r = boundedSpawnSync(file, args, opts);
+    const fail = (message, fields) => {
+        const error = new Error(message);
+        Object.assign(error, { stdout: r.stdout, stderr: r.stderr, status: r.status, signal: r.signal }, fields);
+        throw error;
+    };
+    if (r.timedOut)
+        return fail(`${file} timed out after ${opts.timeout}ms`, { code: "ETIMEDOUT" });
+    if (r.overflowed)
+        return fail(`${file}: stdout exceeded maxBuffer`, { code: "ENOBUFS" });
+    if (r.error)
+        return fail(`${file}: ${r.error.message}`, { code: r.error.code ?? "ESPAWN" });
+    if (r.status !== 0)
+        return fail(`${file} exited ${r.status ?? r.signal}`, {});
+    return r.stdout;
+}
+//# sourceMappingURL=boundedSpawn.js.map

package/dist/core/config.d.ts

@@ -28,6 +28,12 @@ export interface HunchConfig {
      *  (see src/mcp/toolset.ts). Undefined = decide from the root's contents. */
     mcp_tools?: string;
     workspaces?: Partial<WorkspacesConfig>;
+    /** `hunch verify` knobs: `tests` discovery glob, `command` runner template
+     *  (`{files}` is replaced by the selected test paths). */
+    verify?: {
+        tests?: string;
+        command?: string;
+    };
 }
 /** The effective workspace config: every field present, unknown values ignored. */
 export declare function workspacesConfig(config: HunchConfig): WorkspacesConfig;

package/dist/core/config.js

@@ -35,6 +35,7 @@ export function readConfig(paths) {
             firmness: isFirmness(raw.firmness) ? raw.firmness : DEFAULT_FIRMNESS,
             ...(typeof raw.mcp_tools === "string" && raw.mcp_tools.trim() ? { mcp_tools: raw.mcp_tools.trim() } : {}),
             ...(raw.workspaces && typeof raw.workspaces === "object" && !Array.isArray(raw.workspaces) ? { workspaces: raw.workspaces } : {}),
+            ...(raw.verify && typeof raw.verify === "object" && !Array.isArray(raw.verify) ? { verify: raw.verify } : {}),
         };
     }
     catch {

package/dist/core/delivery.d.ts

@@ -124,6 +124,16 @@ export declare const SEVERITY: {
 export declare const PROFILE_BASE_SCORE: Record<DeliveryProfile, Record<DeliveryKind, number>>;
 export declare const TASK_STOP_WORDS: Set<string>;
 export declare function lexicalTokens(value: string): Set<string>;
+/** Test hook: forget memoized commit verdicts. */
+export declare function resetCommitReachabilityMemo(): void;
+/** Test hook: number of git spawns issued by delivery provenance probes so far. */
+export declare function commitReachabilityProbeCount(): number;
+/** A per-build reachability probe. `prime` registers the commits the build may
+ *  ask about; the first lookup then judges all of them in two batched spawns. */
+export type LocalCommitReachability = ((commit: string) => CommitReachability) & {
+    prime: (commits: readonly string[]) => void;
+};
+export declare function localCommitReachability(root: string): LocalCommitReachability;
 /** Validate the public receipt without trusting a caller-supplied identity. */
 export declare function assertDeliveryEnvelope(envelope: DeliveryEnvelope): void;
 /** The string a hash-based injection dedup (`injectionMode`'s `hashInput`) must

package/dist/core/delivery.js

@@ -311,11 +311,15 @@ function componentResolves(id, target, options) {
     const component = (options.components ?? []).find((candidate) => candidate.id === id && candidate.status === "active");
     return !!component && component.paths.some((path) => anchorResolves(path, target, options));
 }
-function gitProbe(root, args) {
+let gitProbeCount = 0;
+function gitProbe(root, args, input) {
+    gitProbeCount++;
     const result = spawnSync("git", ["-C", root, ...args], {
         encoding: "utf8",
         env: { ...process.env, GIT_NO_REPLACE_OBJECTS: "1" },
-        stdio: ["ignore", "pipe", "ignore"],
+        input,
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: [input === undefined ? "ignore" : "pipe", "pipe", "ignore"],
         timeout: 2_000,
         windowsHide: true,
     });
@@ -336,32 +340,134 @@ function defaultBranchRef(root) {
     }
     return null;
 }
-function localCommitReachability(root) {
+// Process-wide memo (#473): every delivery build used to re-probe git for the
+// same capture commits. Verdicts are keyed by the default branch's TIP sha, so a
+// long-lived process stays correct after new commits land. Only ancestry
+// answers (merge-base exit 0/1) are cached; a missing object or a transient
+// spawn failure is re-probed on the next call.
+const REACHABILITY_MEMO_CAP = 10_000;
+const reachabilityMemo = new Map();
+/** Test hook: forget memoized commit verdicts. */
+export function resetCommitReachabilityMemo() {
+    reachabilityMemo.clear();
+}
+/** Test hook: number of git spawns issued by delivery provenance probes so far. */
+export function commitReachabilityProbeCount() {
+    return gitProbeCount;
+}
+function memoizeReachability(key, verdict) {
+    if (reachabilityMemo.size >= REACHABILITY_MEMO_CAP)
+        reachabilityMemo.clear();
+    reachabilityMemo.set(key, verdict);
+    return verdict;
+}
+export function localCommitReachability(root) {
     let initialized = false;
     let branch = null;
-    return (commit) => {
+    let tip = null;
+    // #485: each hook call is a fresh process, so the memo alone still cost two
+    // spawns per capture commit. Primed commits are judged together on the first
+    // lookup — one `cat-file --batch-check` resolves them, one `rev-list` tests
+    // ancestry — and kept for this build only. A spawn failure (timeout, ENOBUFS)
+    // primes every pending commit "unknown", the verdict a failed per-commit probe
+    // gives, so a slow git costs one timeout rather than 2N more spawns. Unexpected
+    // output leaves a commit unprimed and the per-commit path below decides it, so
+    // within a build the verdicts match that path.
+    let expected = [];
+    const primed = new Map();
+    const batch = (commits) => {
+        const pending = [...new Set(commits)].filter((commit) => /^[0-9a-f]{7,64}$/i.test(commit) && !primed.has(commit) && !(tip && reachabilityMemo.has(`${root}\0${tip}\0${commit}`)));
+        if (!pending.length || !branch)
+            return;
+        const resolved = gitProbe(root, ["cat-file", "--batch-check=%(objectname)"], pending.map((commit) => `${commit}^{commit}\n`).join(""));
+        if (!resolved.available) {
+            for (const commit of pending)
+                primed.set(commit, "unknown");
+            return;
+        }
+        const lines = resolved.stdout.split(/\r?\n/);
+        if (resolved.status !== 0 || lines.length !== pending.length)
+            return;
+        const shas = new Map();
+        for (const [i, commit] of pending.entries()) {
+            const line = lines[i];
+            if (/^[0-9a-f]{40,64}$/i.test(line))
+                shas.set(commit, line);
+            // A missing object is not memoized, as on the per-commit path.
+            else if (line === `${commit}^{commit} missing` || line === `${commit}^{commit} ambiguous`)
+                primed.set(commit, "unreachable");
+            else
+                return;
+        }
+        if (!shas.size)
+            return;
+        // `rev-list <shas> ^<tip>` lists exactly the commits NOT reachable from the tip.
+        // It prints the whole history behind an unreachable capture commit (e.g.
+        // orphaned by a rewrite), so this probe costs O(|unreachable history|); a
+        // history big enough to time out primes "unknown" below.
+        const listed = gitProbe(root, ["rev-list", "--stdin"], `${[...new Set(shas.values())].join("\n")}\n^${tip ?? branch}\n`);
+        // A failed spawn or a nonzero exit is a merge-base answer outside 0/1: "unknown", never memoized.
+        if (!listed.available || listed.status !== 0) {
+            for (const commit of shas.keys())
+                primed.set(commit, "unknown");
+            return;
+        }
+        const unreachable = new Set(listed.stdout.split(/\r?\n/).filter(Boolean));
+        for (const [commit, sha] of shas) {
+            const verdict = unreachable.has(sha) ? "unreachable" : "reachable";
+            primed.set(commit, tip ? memoizeReachability(`${root}\0${tip}\0${commit}`, verdict) : verdict);
+        }
+    };
+    const lookup = (commit) => {
         if (!initialized) {
+            // The default ref is looked up every build (origin/HEAD can be retargeted
+            // while the old ref still exists); only verdicts are shared across builds.
             branch = defaultBranchRef(root);
+            if (branch) {
+                // One spawn: the tip sha plus whether the repo is shallow. A shallow
+                // boundary can make a present commit look unreachable until a deepen,
+                // so a shallow build never memoizes. Unexpected output disables the memo.
+                const resolved = gitProbe(root, ["rev-parse", "--is-shallow-repository", "--verify", "--quiet", `${branch}^{commit}`]);
+                const [shallow, sha, ...rest] = resolved.stdout.split(/\r?\n/);
+                if (resolved.available && resolved.status === 0 && !rest.length && shallow === "false" && sha && /^[0-9a-f]{40,64}$/i.test(sha)) {
+                    tip = sha;
+                }
+            }
             initialized = true;
         }
         if (!branch)
             return "unknown";
         if (!/^[0-9a-f]{7,64}$/i.test(commit))
             return "unreachable";
+        const key = tip ? `${root}\0${tip}\0${commit}` : null;
+        const memo = key ? reachabilityMemo.get(key) : undefined;
+        if (memo)
+            return memo;
+        if (expected.length && !primed.has(commit)) {
+            const commits = [...expected, commit];
+            expected = [];
+            batch(commits);
+        }
+        const batched = primed.get(commit);
+        if (batched)
+            return batched;
+        const remember = (verdict) => key ? memoizeReachability(key, verdict) : verdict;
         const exact = gitProbe(root, ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`]);
         if (!exact.available)
             return "unknown";
+        // A missing object is not memoized: a later fetch/deepen can bring it in under the same tip.
         if (exact.status !== 0)
             return "unreachable";
-        const ancestry = gitProbe(root, ["merge-base", "--is-ancestor", exact.stdout, branch]);
+        const ancestry = gitProbe(root, ["merge-base", "--is-ancestor", exact.stdout, tip ?? branch]);
         if (!ancestry.available)
             return "unknown";
         if (ancestry.status === 0)
-            return "reachable";
+            return remember("reachable");
         if (ancestry.status === 1)
-            return "unreachable";
+            return remember("unreachable");
         return "unknown";
     };
+    return Object.assign(lookup, { prime: (commits) => { expected.push(...commits); } });
 }
 function validationState(anchors, anchorsResolve, commit, reachability, requireCommit = false, canValidateAnchors = true) {
     if (anchors.length && canValidateAnchors && !anchors.some(anchorsResolve)) {
@@ -521,8 +627,10 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
     const profile = options.profile ?? "builder";
     const budget = Number.isFinite(ctx.budget_tokens) ? Math.max(0, Math.floor(ctx.budget_tokens)) : 1500;
     const cap = budget * 4;
-    const reachability = options.commitReachability
-        ?? (options.root ? localCommitReachability(options.root) : (() => "unknown"));
+    const local = !options.commitReachability && options.root ? localCommitReachability(options.root) : null;
+    // Only decisions carry a capture commit; register them so the first lookup batches them all (#485).
+    local?.prime(ctx.decisions.flatMap((decision) => decision.commit ? [decision.commit] : []));
+    const reachability = options.commitReachability ?? local ?? (() => "unknown");
     const canValidateAnchors = options.root !== undefined || options.symbols !== undefined || options.components !== undefined;
     const candidates = [];
     const query = queryProfile(ctx.target, options);

package/dist/core/migrate.d.ts

@@ -10,6 +10,9 @@ export interface Migration {
     /** The version this migration PRODUCES (i.e. it upgrades version-1 → `version`). */
     version: number;
     description: string;
+    /** The kinds `up` changes. Omitted = it may touch any kind (conservative: a
+     *  failed record of any kind then holds the manifest version). */
+    kinds?: EntityKind[];
     /** Transform one raw record (untrusted JSON) of `kind` to the next shape. */
     up(kind: EntityKind, raw: Record<string, unknown>): Record<string, unknown>;
 }
@@ -24,5 +27,11 @@ export declare function readManifest(paths: HunchPaths): Manifest;
 /** Write `.hunch/manifest.json` at `version` (default: the current SCHEMA_VERSION). */
 export declare function writeManifest(paths: HunchPaths, version?: number): void;
 /** Apply every migration in (fromVersion, toVersion] to a single raw record. Skips
- *  non-object input untouched (the loader's Zod pass will reject it). */
+ *  non-object input untouched (the loader's Zod pass will reject it). All-or-nothing:
+ *  the steps run on a deep copy, so `raw` is never mutated and a caller that rejects
+ *  the result (or a step that throws) keeps the original record intact — never a
+ *  half-migrated one. */
 export declare function migrateRaw(kind: EntityKind, raw: unknown, fromVersion: number, migrations?: Migration[], toVersion?: number): unknown;
+/** Whether some migration in (fromVersion, toVersion] may change a record of
+ *  `kind` — i.e. whether re-running migrations could ever fix a failed one. */
+export declare function hasPendingMigration(kind: EntityKind, fromVersion: number, migrations?: Migration[], toVersion?: number): boolean;

package/dist/core/migrate.js

@@ -31,6 +31,7 @@ export const MIGRATIONS = [
         // losslessly — no record is dropped, and `valid_from` is populated BEFORE the
         // Zod pass. Defensive: input is untrusted JSON.
         version: 2,
+        kinds: ["decisions", "constraints"],
         description: "Add valid_from/valid_to/superseded_by/retired (decisions) and status/valid_from/valid_to (constraints)",
         up(kind, raw) {
             if (kind === "decisions") {
@@ -64,6 +65,7 @@ export const MIGRATIONS = [
         // relationship schema is validated; newly written resource relationships use
         // hunch.resource-relationship/1 and keep their currentness/metadata.
         version: 3,
+        kinds: ["edges"],
         description: "Version existing graph edges before adding Engineering Landscape resources and relationships",
         up(kind, raw) {
             if (kind === "edges") {
@@ -98,15 +100,24 @@ export function writeManifest(paths, version = SCHEMA_VERSION) {
     writeFileAtomic(paths.manifest, JSON.stringify({ schema_version: version }, null, 2) + "\n");
 }
 /** Apply every migration in (fromVersion, toVersion] to a single raw record. Skips
- *  non-object input untouched (the loader's Zod pass will reject it). */
+ *  non-object input untouched (the loader's Zod pass will reject it). All-or-nothing:
+ *  the steps run on a deep copy, so `raw` is never mutated and a caller that rejects
+ *  the result (or a step that throws) keeps the original record intact — never a
+ *  half-migrated one. */
 export function migrateRaw(kind, raw, fromVersion, migrations = MIGRATIONS, toVersion = SCHEMA_VERSION) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw))
         return raw;
-    let rec = raw;
-    for (const m of [...migrations].sort((a, b) => a.version - b.version)) {
-        if (m.version > fromVersion && m.version <= toVersion)
-            rec = m.up(kind, rec);
-    }
+    const steps = migrations.filter((m) => m.version > fromVersion && m.version <= toVersion);
+    if (steps.length === 0)
+        return raw; // nothing to apply: no copy needed
+    let rec = structuredClone(raw);
+    for (const m of steps.sort((a, b) => a.version - b.version))
+        rec = m.up(kind, rec);
     return rec;
 }
+/** Whether some migration in (fromVersion, toVersion] may change a record of
+ *  `kind` — i.e. whether re-running migrations could ever fix a failed one. */
+export function hasPendingMigration(kind, fromVersion, migrations = MIGRATIONS, toVersion = SCHEMA_VERSION) {
+    return migrations.some((m) => m.version > fromVersion && m.version <= toVersion && (!m.kinds || m.kinds.includes(kind)));
+}
 //# sourceMappingURL=migrate.js.map

package/dist/core/pipeline.d.ts

@@ -231,11 +231,18 @@ export interface BeforeEditProbeVerdict {
     block: boolean;
     state: PipelineState;
     reason?: string;
+    /** The host cannot report command results, so the evidence is unverifiable:
+     * the gate is advisory and `reason` says why instead of denying. */
+    unverifiable?: boolean;
 }
 /** Before-edit evidence is useful only before implementation. At firm/strict,
  * deny at most two product edits per prompt until all such receipts exist;
- * then fail open so a broken probe or discriminator cannot deadlock the agent. */
-export declare function beforeEditProbeVerdict(state: PipelineState): BeforeEditProbeVerdict;
+ * then fail open so a broken probe or discriminator cannot deadlock the agent.
+ * A host whose hooks carry no command outcome (`commandOutcomes: false`) can
+ * never produce a receipt, so its gate is advisory: it never denies. */
+export declare function beforeEditProbeVerdict(state: PipelineState, opts?: {
+    commandOutcomes?: boolean;
+}): BeforeEditProbeVerdict;
 export declare function executionObligationBrief(state: PipelineState): string;
 /** Harness/orchestrator injection. Malformed input returns no obligations. */
 export declare function environmentExecutionObligations(value?: string | undefined): ExecutionObligation[];

package/dist/core/pipeline.js

@@ -704,10 +704,20 @@ export function pendingExecutionObligations(state) {
 }
 /** Before-edit evidence is useful only before implementation. At firm/strict,
  * deny at most two product edits per prompt until all such receipts exist;
- * then fail open so a broken probe or discriminator cannot deadlock the agent. */
-export function beforeEditProbeVerdict(state) {
+ * then fail open so a broken probe or discriminator cannot deadlock the agent.
+ * A host whose hooks carry no command outcome (`commandOutcomes: false`) can
+ * never produce a receipt, so its gate is advisory: it never denies. */
+export function beforeEditProbeVerdict(state, opts = {}) {
     const pending = state.obligations.filter((item) => item.phase === "before-edit" && item.status !== "satisfied");
-    if (!pending.length || state.probeBlocks >= 2)
+    if (!pending.length)
+        return { block: false, state };
+    if (opts.commandOutcomes === false) {
+        return {
+            block: false, state, unverifiable: true,
+            reason: `Hunch evidence gate is advisory here: this host's hooks do not report command results, so ${pending.length} pre-edit evidence obligation(s) cannot be verified and do not block edits. Run them anyway and check their output yourself.`,
+        };
+    }
+    if (state.probeBlocks >= 2)
         return { block: false, state };
     const instructions = pending.slice(0, 3).map((item) => {
         const command = item.probe?.command ?? firstCommand(item);