@davesheffer/hunch 1.45.2 → 1.47.0

package/dist/core/agenthook.js

@@ -209,16 +209,32 @@ function explicitToolOutcome(response) {
         return "success";
     return "unknown";
 }
-function normalizeToolOutcome(input, event) {
+/** Cursor's postToolUse carries `tool_output` as a JSON-stringified result
+ * payload, e.g. `{"exitCode":0,"stdout":"..."}` (cursor.com/docs/agent/hooks, #496).
+ * Parsed, its exit code reaches the probe gate; text that is not a JSON object
+ * stays a bare string, which carries no status. */
+function cursorToolOutput(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        return obj(parsed) ?? value;
+    }
+    catch {
+        return value;
+    }
+}
+function normalizeToolOutcome(input, event, provider) {
     if (event !== "PostToolUse" && event !== "PostToolUseFailure")
         return undefined;
-    const response = input.tool_response ?? input.toolResponse ?? input.tool_result ?? input.toolResult;
+    const response = input.tool_response ?? input.toolResponse ?? input.tool_result ?? input.toolResult
+        ?? (provider === "cursor" ? cursorToolOutput(input.tool_output) ?? input.output : undefined);
     return {
         // Claude Code splits successful and failed calls into separate lifecycle
         // events. Providers without that split may expose an explicit result flag.
         status: event === "PostToolUseFailure" ? "failure" : explicitToolOutcome(response),
         output: event === "PostToolUseFailure"
-            ? toolOutput(input.error ?? response)
+            ? toolOutput(input.error ?? (provider === "cursor" ? input.error_message : undefined) ?? response)
             : toolOutput(response),
     };
 }
@@ -331,9 +347,13 @@ export function normalizeHookEvent(raw, provider) {
     const event = eventName(input.hook_event_name ?? input.hookEventName ?? input.event, provider);
     if (!event)
         return null;
-    const rawToolName = stringAt(input, "tool_name", "toolName");
-    const toolInput = normalizeToolInput(input.tool_input ?? input.toolInput, provider === "codex" && /^(?:apply_patch|patch)$/i.test(rawToolName ?? ""));
-    const toolOutcome = normalizeToolOutcome(input, event);
+    // Cursor's before/afterShellExecution carry the command at top level and no
+    // tool name. afterShellExecution has no exit status (only `output`), so its
+    // outcome stays unknown; the installed postToolUse hook delivers the status.
+    const cursorShell = provider === "cursor" && input.tool_name === undefined && input.tool_input === undefined && typeof input.command === "string";
+    const rawToolName = cursorShell ? "Shell" : stringAt(input, "tool_name", "toolName");
+    const toolInput = normalizeToolInput(cursorShell ? { command: input.command } : input.tool_input ?? input.toolInput, provider === "codex" && /^(?:apply_patch|patch)$/i.test(rawToolName ?? ""));
+    const toolOutcome = normalizeToolOutcome(input, event, provider);
     return {
         hook_event_name: event,
         session_id: stringAt(input, "session_id", "sessionId", "conversation_id", "conversationId"),

package/dist/core/boundedSpawn.d.ts

@@ -0,0 +1,57 @@
+export interface BoundedSpawnOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Written to the child's stdin, which is then closed. Omitted = no stdin. */
+    input?: string;
+    /** Supervisor deadline. Omitted or 0 = no deadline. */
+    timeoutMs?: number;
+    /** stdout bytes allowed before the tree is killed. Default 16 MB. */
+    maxBuffer?: number;
+    /** Launch through the platform shell (cmd.exe on Windows). `file` is then
+     *  the whole command line and `args` should be empty. */
+    shell?: boolean;
+    /** POSIX: how long the tree gets after SIGTERM before SIGKILL. Default 1500. */
+    killGraceMs?: number;
+}
+export interface BoundedSpawnResult {
+    stdout: string;
+    stderr: string;
+    /** Exit status, or null when the child was killed or never started. */
+    status: number | null;
+    /** Signal that ended the child: its own exit signal, or on timeout/overflow
+     *  the last signal the supervisor delivered to the tree. */
+    signal: NodeJS.Signals | null;
+    /** The supervisor's deadline fired and the process tree was killed. */
+    timedOut: boolean;
+    /** stdout exceeded maxBuffer and the process tree was killed. */
+    overflowed: boolean;
+    /** Spawn failure (e.g. ENOENT), or the supervisor itself failing. */
+    error?: NodeJS.ErrnoException;
+}
+/** Test seam: replace the ps binary used for the POSIX tree snapshot
+ *  (null restores "ps"). Not for production callers. */
+export declare function __setPsFileForTests(file: string | null): void;
+/** Async bounded run. Always resolves; inspect `timedOut` / `error` / `status`. */
+export declare function boundedSpawn(file: string, args: string[], opts?: BoundedSpawnOptions): Promise<BoundedSpawnResult>;
+export interface BoundedSpawnSyncOptions extends Omit<BoundedSpawnOptions, "timeoutMs"> {
+    /** Supervisor deadline (required: this helper exists to bound the call). */
+    timeout: number;
+    /** stdout: captured ("pipe", the default), discarded, or written straight to
+     *  an open file descriptor. */
+    stdout?: "pipe" | "ignore" | number;
+}
+/** Synchronous bounded run, spawnSync-shaped: never throws. */
+export declare function boundedSpawnSync(file: string, args: string[], opts: BoundedSpawnSyncOptions): BoundedSpawnResult;
+/** Error thrown by boundedExecFileSync, shaped like execFileSync's: `code`
+ *  ETIMEDOUT / ENOBUFS / ENOENT, or `status` + `signal` for a failed exit. */
+export interface BoundedExecError extends Error {
+    code?: string;
+    status?: number | null;
+    signal?: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}
+/** 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 declare function boundedExecFileSync(file: string, args: string[], opts: BoundedSpawnSyncOptions): string;

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/commitrepair.d.ts

@@ -1,5 +1,6 @@
 import type { Decision } from "./types.js";
 import type { CommitCandidate, CommitRepairStatus } from "../extractors/git.js";
+/** One proposed provenance fix: decision `id` cites `from`, which should cite `to`. */
 export interface CommitRewrite {
     id: string;
     from: string;
@@ -8,14 +9,12 @@ export interface CommitRewrite {
 /** Bind review to the ordered queue and which targets are currently resolvable.
  * Queue order matters: duplicate decision ids use first-match selection. */
 export declare function commitRepairReviewHash(queued: readonly CommitRewrite[], withheld?: ReadonlySet<CommitRewrite>): string;
-/** A tombstone: the exact {id, from, to} rewrite a human explicitly rejected
- *  via `--drop`. Keyed on the full triple, not just {id, from} — the human's
- *  "no" answers the specific question the commit-repair-pending escalation
- *  asked ("apply THIS proposed replacement, from -> to?"), not a blanket
- *  refusal of every future replacement for this decision's still-orphaned
- *  commit. A later merge proposing a genuinely different `to` for the same
- *  {id, from} is a NEW proposal — not a repeat of the one that was rejected —
- *  and surfaces normally. */
+/**
+ * Tombstone for a rewrite a human explicitly rejected with `--drop`. The key is
+ * the full `{id, from, to}` triple, not just `{id, from}`: a later merge that
+ * proposes a DIFFERENT `to` for the same `{id, from}` is a new proposal and
+ * must surface normally.
+ */
 export interface DroppedRewrite {
     id: string;
     from: string;
@@ -23,12 +22,10 @@ export interface DroppedRewrite {
 }
 export interface CommitRepairPlan {
     rewrites: CommitRewrite[];
+    /** Distinct decision ids the rewrites touch. */
     records: string[];
 }
-/** Live decisions whose cited commit still exists here but is no longer an
- *  ancestor of the current tip. Only "orphaned" qualifies: a commit that
- *  doesn't resolve at all ("unresolvable") is out of repair scope, and a git
- *  failure ("unknown") must never be mistaken for repair-eligible. */
+/** Live decisions whose cited commit is orphaned (unresolvable/unknown/current are excluded). */
 export declare function orphanedCommitDecisions(decisions: readonly Decision[], status: (sha: string) => CommitRepairStatus): Decision[];
 /** Match each orphaned decision to exactly one candidate. A candidate with the
  *  same `git patch-id --stable` as the orphaned commit (a rebase- or
@@ -39,139 +36,47 @@ export declare function orphanedCommitDecisions(decisions: readonly Decision[],
  *  patch-id never equals any one of them, but weak: shared files like
  *  CHANGELOG.md often have one wrong superset (#450). */
 export declare function planCommitRepair(orphaned: readonly Decision[], candidates: readonly CommitCandidate[], patchIdOf?: (sha: string) => string | null): CommitRepairPlan;
-/** Whether a queued rewrite is still worth ASKING about: the decision it
- *  names still exists, still cites the commit the entry expects to replace (a
- *  decision that already moved on would make repairDecisionCommit's own
- *  stale-plan bail refuse it), and hasn't since been superseded/rejected —
- *  same exclusion as orphanedCommitDecisions, since repairing dead history's
- *  provenance isn't worth asking about. Backs the read-only escalation
- *  surface only (commitRepairEscalations) — absence-means-not-askable is
- *  safe there because it self-heals the moment visibility returns.
- *  repair-provenance itself does NOT use this: it reads the full store and
- *  may legitimately list (dry-run) or leave queued (apply) an entry this
- *  predicate would call not-live, so the escalation surface and the CLI can
- *  disagree about the same entry — see deadRewrites and resolvedRewriteIds
- *  for the CLI's own, looser-on-purpose reasoning. */
+/** Queued entries that are still answerable: the decision exists, still cites `from`, and is live. */
 export declare function liveRewrites(queued: readonly CommitRewrite[], decisions: readonly Decision[]): CommitRewrite[];
-/** Entries a decision has demonstrably outgrown: the decision IS present in
- *  `decisions`, and it either moved on from `from` or has since been
- *  superseded/rejected. An id this list can't see is deliberately NOT
- *  included — absence is a property of the READER (a branch checkout that
- *  predates the decision, an unmounted private overlay), not proof the match
- *  is stale. This predicate backs a DESTRUCTIVE prune (repair-provenance
- *  deletes what it returns from the queue file); repairqueue.ts's own
- *  docstring is why that matters — the queue is the one durable record of a
- *  match once ORIG_HEAD moves on and the matched-away commit can be gc'd, so
- *  deleting an entry on a merely-absent id would destroy it unrecoverably.
- *  Contrast liveRewrites, whose absence-means-not-askable rule is safe on
- *  the read-only escalation surface, which self-heals once visibility
- *  returns.
- *
- *  Caveat: "demonstrably" is only as strong as this run's view of
- *  `decisions`, which comes from the same git-tracked, branch-dependent
- *  files that motivate treating ABSENCE as inconclusive. A decision whose
- *  `commit`/`status` genuinely differ between branches (e.g. a repair
- *  already applied and committed on one branch, checked out here from a
- *  branch that predates it) could still read as "moved on" when it hasn't,
- *  from this branch's perspective. Far narrower than the absence case this
- *  function exists to fix, and not addressed here. */
+/**
+ * Queued entries whose decision IS visible but moved on (different or null
+ * commit) or was superseded/rejected. An id absent from `decisions` is never
+ * dead: absence comes from the reader's view (a branch checkout, an unmounted
+ * private overlay) and the CLI deletes whatever this returns. Caveat: a decision
+ * that differs between branches could still read as "moved on".
+ */
 export declare function deadRewrites(queued: readonly CommitRewrite[], decisions: readonly Decision[]): CommitRewrite[];
-/** Among `toApply` (the queued/matched candidates this run is about to act
- *  on), the ids repair-provenance may treat as RESOLVED once it's done: the
- *  decision is present in `decisions` this run, whether or not
- *  repairDecisionCommit actually changed it (a present decision that already
- *  moved on is "resolved" too — repairDecisionCommit's own bail refused it,
- *  and there is nothing more this run can do about it). An id whose decision
- *  is NOT present is never resolved — same reasoning as deadRewrites:
- *  absence is the reader's transient view, not proof the match is settled,
- *  so it must stay queued for a run where the decision is visible again. */
+/** Ids of `toApply` whose decision is visible, whether or not the rewrite changed it. */
 export declare function resolvedRewriteIds(toApply: readonly CommitRewrite[], decisions: readonly Decision[]): Set<string>;
-/** Remove any match whose exact {id, from, to} triple was already tombstoned
- *  by an earlier `--drop` — otherwise a later merge that re-derives the
- *  identical candidate would re-queue exactly what the human rejected. A
- *  match sharing {id, from} but proposing a different `to` is unaffected: it
- *  is a different proposal, not the rejected one.
- *
- *  Preserves object identity for every surviving entry (a plain filter, never
- *  a clone or a rebuild) — repair-provenance's own action relies on this to
- *  diff its swept-vs-active queue by reference (`queue.filter(r =>
- *  !active.includes(r))`) rather than re-spelling the {id, from, to} key a
- *  third time. Do not change this to normalize or reconstruct entries
- *  without updating that call site too. */
-export declare function withoutDropped(rewrites: readonly CommitRewrite[], dropped: readonly DroppedRewrite[]): CommitRewrite[];
-/** Append newly-dropped {id, from, to} triples to the tombstone list,
- *  deduped — same append-only, dedupe-by-key shape as mergeRewrites. */
+/** Drop rewrites whose exact {id, from, to} triple is tombstoned. A plain filter: survivors keep identity. */
+export declare function withoutDropped<T extends CommitRewrite>(rewrites: readonly T[], dropped: readonly DroppedRewrite[]): T[];
+/** `existing` followed by the entries of `newly` whose exact triple is not already tombstoned. */
 export declare function addDropped(newly: readonly DroppedRewrite[], existing: readonly DroppedRewrite[]): DroppedRewrite[];
-/** Combine a freshly-computed plan's rewrites with anything already queued
- *  (src/core/repairqueue.ts) from an earlier detection. A fresh match —
- *  computed just now, against the current range — overrides a queued one for
- *  the same decision; queued entries no longer reachable are simply not
- *  repeated by the fresh scan.
- *
- *  Overrides by object identity, targeting exactly the one queued entry
- *  firstFor (id) would pick — the same first-match rule --drop applies, and
- *  the same identity-not-id targeting the dead-entry prune applies (#53; the
- *  prune itself removes every provably-dead entry, not just a first match).
- *  A corrupted queue file, a hand edit, or a bug upstream could otherwise
- *  carry a SECOND entry sharing that id; overriding by id alone would
- *  silently destroy that still-queued sibling too, with no tombstone and no
- *  way to recover it, even though it was never the entry that would have
- *  been applied. Any such sibling is left queued and untouched.
- *
- *  How a survivor resolves: the dead-entry prune (deadRewrites), once
- *  --apply has moved the decision past the sibling's `from`; or a --drop
- *  whose tombstone matches the sibling's exact {id, from, to} — the same
- *  --drop that dropped the fresh entry, when the sibling happens to share
- *  its triple (the drop's own re-sweep, withoutDropped, catches it too), a
- *  second explicit --drop otherwise. NOT a later fresh detection: by this
- *  same first-match rule it always overrides the fresh entry sitting ahead
- *  of it, never the sibling. */
+/**
+ * Fresh detections first, then the queued entries they did not override. A fresh
+ * entry overrides only the FIRST queued entry with its id (see `firstFor`);
+ * later duplicate-id siblings survive untouched.
+ */
 export declare function mergeRewrites(fresh: readonly CommitRewrite[], queued: readonly CommitRewrite[]): CommitRewrite[];
-/** Partition the entries --apply is about to act on by whether their proposed
- *  `to` commit actually exists in this repository. `existing` is
- *  `commitsExist`'s result over every `to` in `toApply`: `null` means the
- *  check itself failed to run (not a git repo, git missing, timeout) and is
- *  treated as fail-open, same discipline as drift.ts's own use of
- *  commitsExist — nothing is withheld just because the check couldn't run.
- *
- *  A corrupted queue file, a hand-edited entry, or a bug upstream could
- *  otherwise get a `to` that never resolves to a real commit written
- *  straight into a decision's `commit` field and provenance evidence, then
- *  auto-committed into shared team memory. `withheld` entries must stay
- *  queued (never deleted, never passed to repairDecisionCommit) — the queue
- *  file is the one durable record of the match, same reasoning as
- *  deadRewrites/resolvedRewriteIds.
- *
- *  Both returned arrays preserve object identity (never clones or rebuilds
- *  an entry) — the CLI's queue sweep and its "still queued" reporting both
- *  key a `Set` off the exact objects in `withheld`, by reference, precisely
- *  because a corrupted queue file can carry two entries sharing an id (one
- *  resolvable, one not): an id alone can't tell them apart. Do not change
- *  this to normalize or reconstruct entries without updating those call
- *  sites too — same caveat withoutDropped's own docstring carries. */
-export declare function withheldForUnresolvableTo(toApply: readonly CommitRewrite[], existing: Set<string> | null): {
+/**
+ * Split entries by whether their proposed `to` resolves here. `existing === null`
+ * means the check could not run, so it fails open (everything applicable).
+ * Order and object references are preserved.
+ */
+export declare function withheldForUnresolvableTo(toApply: readonly CommitRewrite[], existing: ReadonlySet<string> | null): {
     applicable: CommitRewrite[];
     withheld: CommitRewrite[];
 };
-/** The one rule for which entry wins when more than one shares a decision id
- *  (a corrupted queue file, a hand edit, or a bug upstream): first match, by
- *  construction. Every caller goes through here so no two can independently
- *  drift on which entry "won" — this file's own duplicate-id queue handling
- *  has drifted between call sites three times already (see withoutDropped's,
- *  withheldForUnresolvableTo's, and mergeRewrites' own docstrings). */
-export declare function firstFor(entries: readonly CommitRewrite[], id: string): CommitRewrite | undefined;
-/** pickRewrite is firstFor scoped to a plan's own rewrites (planCommitRepair
- *  itself never produces same-id duplicates, but a plan carrying them isn't
- *  ruled out here — see firstFor). repairDecisionCommit uses this to decide
- *  what to WRITE; a caller that needs to know which entry WOULD be picked
- *  without writing anything (the CLI's --apply summary and queue sweep)
- *  calls this same function, so the two can never independently drift on
- *  which entry "won". */
+/** The single first-match rule for duplicate decision ids. */
+export declare function firstFor<T extends {
+    id: string;
+}>(entries: readonly T[], id: string): T | undefined;
+/** The plan's rewrite for `id` (first match). */
 export declare function pickRewrite(plan: CommitRepairPlan, id: string): CommitRewrite | undefined;
-/** Pure: rewrite `commit` for one decision, and its matching `commit:<sha>`
- *  evidence entry too if one is present (replaceExact is a no-op when the
- *  evidence array never cited the old sha) — or return the same reference
- *  when the plan doesn't touch it. If the record moved on since the plan was
- *  built (its commit no longer equals the plan's `from`), bail entirely
- *  rather than applying a now-stale match. */
+/**
+ * Pure: apply the plan's rewrite to a decision. Returns the same reference when
+ * there is no entry or the record moved on (`commit` no longer equals `from`);
+ * otherwise a copy with `commit` and the `commit:<from>` evidence moved to `to`
+ * (deduped if `to` was already cited).
+ */
 export declare function repairDecisionCommit(d: Decision, plan: CommitRepairPlan): Decision;