@davesheffer/hunch 1.46.0 → 1.47.0

package/dist/core/commitrepair.js

@@ -1,9 +1,10 @@
 /**
- * Deterministic repair for a decision's commit provenance after a squash-merge.
+ * Deterministic repair of a decision's commit provenance after a squash-merge.
  *
- * A squash-merge produces one new commit whose parent is the pre-merge target
- * tip — the original per-commit SHAs it squashed are never ancestors of it.
- * This module matches an orphaned decision to the ONE newly-merged commit
+ * A squash-merge lands ONE new commit on the target branch; the original
+ * per-commit SHAs are never its ancestors, so a decision citing one of them
+ * becomes orphaned. This module matches each orphaned decision to exactly one
+ * newly merged commit: the candidate
  * with the same patch-id, or failing that the ONE whose changed files are a
  * superset of the decision's related_files. Zero or multiple qualifying
  * candidates means "don't guess" — same discipline as repair.ts's
@@ -17,22 +18,13 @@ export function commitRepairReviewHash(queued, withheld = new Set()) {
     const snapshot = queued.map((r) => ({ id: r.id, from: r.from, to: r.to, withheld: withheld.has(r) }));
     return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
 }
-/** A scope entry is exact (usable as a match key) only when it contains no glob syntax. */
-function isExactPath(entry) {
-    return !!entry && !/[*?[\]{}]/.test(entry);
+/** True when a scope entry can serve as an exact match key (non-empty, no glob metacharacters). */
+function isExactScope(entry) {
+    return entry.length > 0 && !/[*?[\]{}]/.test(entry);
 }
-/** 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 function orphanedCommitDecisions(decisions, status) {
-    return decisions.filter((d) => {
-        if (d.status === "superseded" || d.status === "rejected")
-            return false;
-        if (!d.commit)
-            return false;
-        return status(d.commit) === "orphaned";
-    });
+    return decisions.filter((d) => d.status !== "superseded" && d.status !== "rejected" && !!d.commit && status(d.commit) === "orphaned");
 }
 /** Match each orphaned decision to exactly one candidate. A candidate with the
  *  same `git patch-id --stable` as the orphaned commit (a rebase- or
@@ -55,29 +47,16 @@ export function planCommitRepair(orphaned, candidates, patchIdOf = () => null) {
             if (same.length > 1)
                 continue; // ambiguous: never guess
         }
-        const files = (d.related_files ?? []).filter(isExactPath);
-        if (!files.length)
+        const scope = (d.related_files ?? []).filter(isExactScope);
+        if (scope.length === 0)
             continue;
-        const matches = candidates.filter((c) => files.every((f) => c.files.includes(f)));
-        if (matches.length !== 1)
-            continue; // zero or ambiguous: never guess
-        rewrites.push({ id: d.id, from: d.commit, to: matches[0].sha });
+        const supersets = candidates.filter((c) => scope.every((f) => c.files.includes(f)));
+        if (supersets.length === 1)
+            rewrites.push({ id: d.id, from: d.commit, to: supersets[0].sha });
     }
     return { rewrites, records: [...new Set(rewrites.map((r) => r.id))] };
 }
-/** 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 function liveRewrites(queued, decisions) {
     const byId = new Map(decisions.map((d) => [d.id, d]));
     return queued.filter((r) => {
@@ -85,128 +64,67 @@ export function liveRewrites(queued, decisions) {
         return !!d && d.commit === r.from && d.status !== "superseded" && d.status !== "rejected";
     });
 }
-/** 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 function deadRewrites(queued, decisions) {
     const byId = new Map(decisions.map((d) => [d.id, d]));
     return queued.filter((r) => {
         const d = byId.get(r.id);
-        return !!d && (d.commit !== r.from || d.status === "superseded" || d.status === "rejected");
+        if (!d)
+            return false;
+        return d.commit !== r.from || d.status === "superseded" || d.status === "rejected";
     });
 }
-/** 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 function resolvedRewriteIds(toApply, decisions) {
-    const seen = new Set(decisions.map((d) => d.id));
-    return new Set(toApply.filter((r) => seen.has(r.id)).map((r) => r.id));
+    const visible = new Set(decisions.map((d) => d.id));
+    return new Set(toApply.filter((r) => visible.has(r.id)).map((r) => r.id));
 }
-/** 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. */
+const tripleKey = (r) => JSON.stringify([r.id, r.from, r.to]);
+/** Drop rewrites whose exact {id, from, to} triple is tombstoned. A plain filter: survivors keep identity. */
 export function withoutDropped(rewrites, dropped) {
-    if (!dropped.length)
+    if (dropped.length === 0)
         return [...rewrites];
-    const tombstoned = new Set(dropped.map((t) => `${t.id}\0${t.from}\0${t.to}`));
-    return rewrites.filter((r) => !tombstoned.has(`${r.id}\0${r.from}\0${r.to}`));
+    const keys = new Set(dropped.map(tripleKey));
+    return rewrites.filter((r) => !keys.has(tripleKey(r)));
 }
-/** Append newly-dropped {id, from, to} triples to the tombstone list,
- *  deduped — same append-only, dedupe-by-key shape as mergeRewrites. */
+/** `existing` followed by the entries of `newly` whose exact triple is not already tombstoned. */
 export function addDropped(newly, existing) {
-    const seen = new Set(existing.map((t) => `${t.id}\0${t.from}\0${t.to}`));
-    const additions = newly.filter((t) => !seen.has(`${t.id}\0${t.from}\0${t.to}`));
-    return [...existing, ...additions];
+    const keys = new Set(existing.map(tripleKey));
+    const out = [...existing];
+    for (const n of newly) {
+        const k = tripleKey(n);
+        if (keys.has(k))
+            continue;
+        keys.add(k);
+        out.push(n);
+    }
+    return out;
 }
-/** 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 function mergeRewrites(fresh, queued) {
     const overridden = new Set();
-    for (const r of fresh) {
-        const first = firstFor(queued, r.id);
-        if (first)
-            overridden.add(first);
+    for (const f of fresh) {
+        const hit = firstFor(queued, f.id);
+        if (hit)
+            overridden.add(hit);
     }
-    return [...fresh, ...queued.filter((r) => !overridden.has(r))];
+    return [...fresh, ...queued.filter((q) => !overridden.has(q))];
 }
-/** 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. */
+/**
+ * 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 function withheldForUnresolvableTo(toApply, existing) {
     if (existing === null)
         return { applicable: [...toApply], withheld: [] };
@@ -216,40 +134,31 @@ export function withheldForUnresolvableTo(toApply, existing) {
         (existing.has(r.to) ? applicable : withheld).push(r);
     return { applicable, withheld };
 }
-/** 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). */
+/** The single first-match rule for duplicate decision ids. */
 export function firstFor(entries, id) {
-    return entries.find((r) => r.id === id);
+    return entries.find((e) => e.id === id);
 }
-/** 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 plan's rewrite for `id` (first match). */
 export function pickRewrite(plan, id) {
     return firstFor(plan.rewrites, id);
 }
-/** 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 function repairDecisionCommit(d, plan) {
-    const mine = pickRewrite(plan, d.id);
-    if (!mine || d.commit !== mine.from)
+    const entry = pickRewrite(plan, d.id);
+    if (!entry || d.commit !== entry.from)
         return d;
-    const evidence = replaceExact(d.provenance.evidence, `commit:${mine.from}`, `commit:${mine.to}`);
     return {
         ...d,
-        commit: mine.to,
-        provenance: { ...d.provenance, evidence: evidence.values },
+        commit: entry.to,
+        provenance: {
+            ...d.provenance,
+            evidence: replaceExact(d.provenance.evidence, `commit:${entry.from}`, `commit:${entry.to}`).values,
+        },
     };
 }
 //# sourceMappingURL=commitrepair.js.map

package/dist/core/correction.js

@@ -57,13 +57,12 @@ export const TESTIMONY_CORRECTION_RATIONALE = "Recorded by the agent as a correc
  *  Returns "" when the hint cannot be made repo-relative (no root, or a path outside the
  *  repo). The caller then falls back to "**", where the existing severity guard
  *  down-ranks a non-explicit blocking rule to a warning — fail-safe and honest, rather
- *  than a blocking rule enforced nowhere.
+ *  than a blocking rule that is enforced nowhere.
  *
- *  Thin adapter over the shared `repoRelativeTarget` (core/paths.ts): that function
- *  passes an unresolvable absolute hint through UNCHANGED (still absolute) rather
- *  than signaling failure directly, since other callers (checkConstraints, why())
- *  want the original target back to fail their own match safely. This adapter
- *  converts that "still absolute" signal to "" — the fail-safe this caller needs. */
+ *  This is a thin adapter over the shared `repoRelativeTarget`, which hands an
+ *  unresolvable absolute hint back unchanged instead of signalling failure (other
+ *  callers want the original target back). Here a result that is still absolute is
+ *  turned into the empty string. */
 function repoRelativeHint(rawHint, root) {
     if (!rawHint)
         return "";
@@ -72,9 +71,10 @@ function repoRelativeHint(rawHint, root) {
         return rawHint;
     if (!root)
         return "";
-    const rewritten = repoRelativeTarget(rawHint, root);
-    const stillAbsolute = isAbsolute(rewritten) || /^[a-zA-Z]:/.test(rewritten);
-    return stillAbsolute ? "" : rewritten;
+    const rel = repoRelativeTarget(rawHint, root);
+    if (isAbsolute(rel) || /^[a-zA-Z]:/.test(rel))
+        return "";
+    return rel;
 }
 /**
  * Build the Constraint a correction mints. Pure (caller passes `now`), so the

package/dist/core/docanchors.js

@@ -360,11 +360,11 @@ function htmlBlockEnd(s) {
 /** Character ranges covered by inline code spans (`…`), same rationale as
  *  codeRanges: prose quoting a marker in backticks is showing an example.
  *  CommonMark-lite: an opener run pairs with the next run of the SAME length
- *  on the same line; unpaired runs never open a span.
- *  Expects LF-normalized text — see parseDocAnchors's normalization.
- *  `split("\n")` does not split a bare CR, so on CR-only input the whole
- *  document reads as one line and stray backticks on different lines
- *  falsely pair. */
+ *  on the same line; an unpaired backtick run never opens a span, and pairing
+ *  is per line. Expects LF-normalized input (see scanDocAnchors): the text is
+ *  split on LF only, so a CR-only document would read as one long line and
+ *  stray backticks on different lines would falsely pair.
+ */
 function inlineSpanRanges(text) {
     const ranges = [];
     let offset = 0;
@@ -394,10 +394,10 @@ export function parseDocAnchors(text) {
  *  never closes hides every marker below it, almost always by mistake (#381). */
 export function scanDocAnchors(text) {
     // codeRanges is CRLF-sensitive (its fence-line regex's `.` excludes \r, so
-    // "```\r" never matched at all on a CRLF checkout); inlineSpanRanges is
-    // lone-CR-sensitive (split("\n") doesn't split a bare CR — see its
-    // docblock). Either way an example marker inside a fence/span registered as
-    // a live, pinned anchor. Normalizing both CRLF and lone CR once here keeps
+    // trailing CR means a CRLF fence line was never recognized as a fence), and the
+    // inline-span scan is sensitive to a bare CR (it splits on LF only, see its
+    // docblock). Either way an example marker inside a fence or span got registered
+    // as a live pinned anchor. Normalizing CRLF and lone CR once, here, keeps
     // codeRanges/inlineSpanRanges/MARKER offsets consistent with each other
     // and with the line numbers reported below. A leading BOM is dropped too, so
     // line 1 starts at column 0 (#381); it is one char on line 1, so line numbers hold.

package/dist/core/drift.js

@@ -48,25 +48,17 @@ export function computeDrift(store, root, deps = {}) {
         return liveFiles.has(p) || liveDirs.some((dir) => p.startsWith(dir));
     };
     const premiseEnv = { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) };
-    // A plain existence check is meaningless outside a git repo — computed once,
-    // not per decision, and never a false positive for a directory that merely
-    // happens to hold .hunch/ without being a git checkout. Injectable so tests
-    // (and callers with a cheaper oracle) never have to shell out per decision.
-    const gitRepo = isGitRepo(root);
-    // One batched `git cat-file --batch-check` for every commit-bearing decision,
-    // not one `rev-parse` per decision — skipped entirely when a predicate is
-    // injected (tests/callers with a cheaper oracle never pay for this at all).
-    const resolvableCommits = gitRepo && !deps.commitResolvable
-        ? commitsExist([...new Set(decisions.filter((d) => d.commit).map((d) => d.commit))], root)
-        : null;
-    const defaultCommitResolvable = (sha) => {
-        if (!gitRepo)
-            return true; // never flag outside a git repo
-        if (resolvableCommits === null)
-            return true; // the batch check itself failed, or was skipped — fail open
-        return resolvableCommits.has(sha);
-    };
-    const commitResolvable = deps.commitResolvable ?? defaultCommitResolvable;
+    // Commit-provenance resolver. Injectable so tests/callers avoid spawning git. The
+    // default runs ONE batched existence check over every decision's commit (not a
+    // process per decision), and outside a git repo the check is meaningless, so it
+    // never flags anything there.
+    let commitResolvable = deps.commitResolvable;
+    if (!commitResolvable) {
+        const inRepo = isGitRepo(root);
+        const shas = inRepo ? [...new Set(decisions.map((d) => d.commit).filter((c) => !!c))] : [];
+        const resolvable = inRepo ? commitsExist(shas, root) : null;
+        commitResolvable = (sha) => !inRepo || resolvable === null || resolvable.has(sha);
+    }
     for (const d of decisions) {
         // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
         //    a since-deleted file is legitimate history, not drift.
@@ -79,15 +71,18 @@ export function computeDrift(store, root, deps = {}) {
                     findings.push({ kind: "dead-ref", id: d.id, detail: `references missing file "${f}"` });
                 }
             }
-            // 8. COMMIT-UNRESOLVABLE — an in-force decision's commit provenance no longer
-            //    resolves at all (source branch gone + gc'd past recovery). The
-            //    opportunistic post-merge repair (commitrepair.ts) is the fix path; this
-            //    is purely the "nothing caught it" signal — deterministic, never auto-fixed.
-            //    Mirrors repair.ts:59's live-records-only rule: `inForce` alone doesn't
-            //    exclude a never-adopted "rejected" decision (superseded_by is null for
-            //    those too), so exclude it explicitly here.
+            // 8. COMMIT-UNRESOLVABLE — the commit provenance no longer resolves here (its
+            //    source branch was deleted and garbage-collected). The post-merge repair
+            //    flow is the fix path; this is only the deterministic "nothing caught it"
+            //    signal and is never auto-fixed. Same live-records-only rule as the repair
+            //    module, hence the explicit rejected exclusion (a never-adopted decision
+            //    also has superseded_by null).
             if (d.commit && d.status !== "rejected" && !commitResolvable(d.commit)) {
-                findings.push({ kind: "commit-unresolvable", id: d.id, detail: `commit ${d.commit} no longer resolves in this repository — provenance may need manual repair` });
+                findings.push({
+                    kind: "commit-unresolvable",
+                    id: d.id,
+                    detail: `commit ${d.commit} no longer resolves in this repository — provenance may need manual repair`,
+                });
             }
         }
         // 2. SUPERSEDE-INTEGRITY — a contradiction class: A.supersedes = B, but B is

package/dist/core/escalations.d.ts

@@ -33,76 +33,34 @@ export interface Escalation {
     detail: string;
     /** the concrete resolution the human's answer maps to. */
     resolution: string;
-    /** false ONLY for an entry whose own resolution requires acting on a
-     *  DIFFERENT entry first (a duplicate-id queue's non-drop, non-apply
-     *  follower) — it still surfaces, for transparency, but gating surfaces
-     *  (CI exit code, "needs your call" tallies) must not count it: resolving
-     *  the actionable entry ahead of it is what clears it, not anything a
-     *  human can do to this row directly (#61). Omitted (undefined) means
-     *  true — every other escalation kind is always directly actionable. */
+    /** `false` marks an entry whose resolution depends on first acting on a DIFFERENT
+     *  entry: the non-drop, non-apply follower in a duplicate-id commit-repair queue.
+     *  It still surfaces for transparency, but gating surfaces (the CI exit code and
+     *  "needs your call" tallies) must not count it. Omitted/undefined = actionable. */
     actionable?: boolean;
 }
-/** Escalations gating surfaces (CI exit codes, "needs your call" counts/lists)
- *  should act on: everything except an entry explicitly marked
- *  actionable:false (#61). The full list — including non-actionable
- *  entries — still belongs in any transparency-facing output (e.g. --json). */
+/** The entries a human can act on right now (order preserved). */
 export declare function actionableEscalations(items: readonly Escalation[]): Escalation[];
 export interface EscalationSummary {
-    /** the subset a gating surface should count/exit/ask on. */
+    /** the gating subset. */
     actionable: Escalation[];
-    /** how many entries were filtered out — informational-only, shown for
-     *  transparency but not itself a decision to raise. */
+    /** how many entries were filtered out as context-only. */
     context: number;
 }
-/** One computation for every "N need your call (+M shown for context)"
- *  consumer (CLI `escalations`, SessionStart, the `hunch_now`/`hunch_escalations`
- *  MCP tools) — introduced alongside `actionable` (#61) specifically so a
- *  future consumer of Escalation[] can't repeat the mistake of hand-rolling
- *  the filter and forgetting it (the VS Code panel did, before this existed). */
 export declare function summarizeEscalations(items: readonly Escalation[]): EscalationSummary;
-/** "you" (the CLI, talking directly to the operator) vs "mcp" (an assistant
- *  relaying a question to the human, third person). */
+/** "cli" speaks to the operator (second person); "mcp" is an assistant relaying to the human (third person). */
 export type EscalationAudience = "cli" | "mcp";
-/** The ONE "N need your call (+M shown for context)" headline, shared by the
- *  CLI `escalations` command and the `hunch_escalations` MCP tool (#61) —
- *  including its own "nothing actionable, but N item(s) queued for context"
- *  fallback, so that unreachable-today prose exists in exactly one place
- *  instead of being hand-copied per consumer (the copy-paste is how the VS
- *  Code panel missed the filter entirely before `actionable` existed).
- *  Callers are expected to have already special-cased `items.length === 0`
- *  (a plainer "nothing needs your decision" message, no tally at all). */
+/** One-line heading for a non-empty escalation list. Callers handle the empty list themselves. */
 export declare function escalationHeadline(items: readonly Escalation[], audience: EscalationAudience): string;
 /** The decisions a human must make NOW, to be asked INLINE. Empty in a healthy graph. */
 export declare function pendingEscalations(decisions: readonly Decision[]): Escalation[];
-/** A commit-provenance repair the post-merge hook detected and queued
- *  (src/core/repairqueue.ts) but never applied — the match signal (related_files
- *  overlap) isn't strong enough to write unattended, so it's a question for the
- *  human, exactly like every other entry here, never a silent write.
- *
- *  `decisions` is the caller's VISIBLE scope (supplies the title only) —
- *  MCP/SessionStart pass store.advisoryRecs(), which is public-only in
- *  private mode. `live` is the scope liveRewrites checks the repair against;
- *  it defaults to `decisions` but callers on an advisory scope must pass the
- *  FULL store (store.recs()) here, since repair-provenance itself reads the
- *  full store — an overlay decision's repair is fully answerable even where
- *  its title isn't visible, and must not go silent just because the title is
- *  private.
- *
- *  `withheld` (from repairqueue.ts's withheldRewrites — a git-facing check
- *  this module deliberately stays free of, so the caller runs it and passes
- *  the result in) names entries whose proposed `to` doesn't resolve to a
- *  real commit here. `--apply --only <id>` can never resolve one of these —
- *  advertising it as the answer would be advice guaranteed to no-op
- *  forever, which is worse than not asking at all. Such an entry still
- *  needs a human (only `--drop` can retire it), so it still escalates, just
- *  with wording that doesn't promise `--apply` will help.
- *
- *  Keyed by OBJECT, not by id, matching withheldForUnresolvableTo's own
- *  contract: a corrupted queue file can carry two entries sharing an id
- *  (one resolvable, one not) — an id-keyed set couldn't tell them apart and
- *  would wrongly tag the resolvable sibling as unresolvable too. Every
- *  caller of this function already passes the SAME `queued` array to both
- *  this function and withheldRewrites, so identity holds. */
+/** A commit-provenance repair the post-merge hook queued but never applied is a human
+ *  question, never a silent write. `decisions` is the caller's VISIBLE scope and supplies
+ *  titles only. `live` is the scope liveness is checked against: callers on an advisory
+ *  scope pass the full store so an overlay decision's repair isn't silenced just because
+ *  its title is private. `withheld` holds entries whose proposed `to` doesn't resolve to a
+ *  real commit; membership is by object identity, not id, so two corrupted entries
+ *  sharing an id stay distinguishable. */
 export declare function commitRepairEscalations(queued: readonly CommitRewrite[], decisions: readonly Decision[], live?: readonly Decision[], withheld?: ReadonlySet<CommitRewrite>): Escalation[];
 /** The minimal policy shape the escalation scan needs — a structural subset of
  *  constitution PolicySpec, so this module stays dependency-free of the