@holmes-lab/holmes-kit 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,102 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.16.0] - 2026-09-07
+
+The graph learns to speak intent, and the call graph learns to speak up at sealing time. An A-SPEC
+approval now returns what your Files-to-Touch declaration *missed* — and every spec the graph
+names arrives with its one-sentence intent beside the id, extracted (never generated) from the
+spec store. Two more mechanisms were benchmarked under pre-registration and honestly discarded.
+
+### Added
+- **Impact advisory on approval (REQ-566)** — a successful A-SPEC `spec_approve` may now carry
+  `impactAdvisory`: files whose symbols **call into** the declared Files-to-Touch but sit outside
+  the declaration (1-hop, capped at 10, repo-relative allow-list). Advisory, never verdict: it
+  rides the response *after* the seal is committed, degrades to absence on any failure, and every
+  emission lands in an observation ledger (`.ax/ledger/impact-advisories.<replica>.jsonl` — paths,
+  ids and integers only) so its false-positive rate is measured *before* anyone proposes a hard
+  gate. The RTM graph persists at `.ax/rtm.sqlite` and keeps itself fresh: `rtm_impact` rebuilds
+  on basis drift, and the Stop hook spawns a TTL-gated detached reindex (staleness was measured as
+  the advisory's quality factor: 7 findings on an 8-day-old graph, 17 after a fresh one).
+- **SPEC intent summaries in the graph (REQ-568)** — graph nodes gain a `summary` column (schema
+  `rtm-graph/2` → `/3`; old stores rebuild automatically on first use, no migration step). Every
+  SPEC node stores `"<title> — <first sentence of its intent section>"`, extracted
+  deterministically (REQ=Problem / Need, H-SPEC=Intent, A-SPEC=Objective; 200-char cap; title-less
+  legacy specs — 20 measured in this very store — fall back to sentence, then id). Same store,
+  byte-identical graph; measured cost +6.4% build time / +4.2% file size. `RtmGraph.summaryOf(id)`
+  reads it back, and `rtm_impact` responses add `impactedSummaries: [{id, summary}]` beside the
+  unchanged `impacted` list.
+- **Session-context observability (REQ-564)** — the ledger records which agent/model drove a
+  session and what the governance overhead cost, per replica
+  (`.ax/ledger/session-context.<replica>.jsonl`), grounding field reports in machine attribution.
+
+### Changed
+- **`impactAdvisory.files[].anchors` shape (REQ-568, code-interface)** — anchors are now
+  `[{id, summary}]` instead of `string[]`, so the reader sees *which intent* is at risk without a
+  spec-store round trip. Consumers parsing anchors must read `.id`. The summary is information
+  only: value tests pin that the advisory's file list, ordering and `more` count are independent
+  of the prose, and the observation ledger stays prose-free.
+
+### Notes
+- Two pre-registered negatives, kept as records rather than shipped: the judgement-axis
+  FACT/EVIDENCE bundle tied its bench (0.480 vs 0.478) and was discarded with its re-attempt
+  conditions sealed (REQ-567, 15th rejection); a spec-intent **vector assist** for uncited
+  requests was built, measured byte-identical to the lexical path over 441 held-out traceability
+  cases (long queries already match ~371 specs lexically; the lexical-zero segment is protected by
+  the reorder-not-admit rule), reverted, and its A/T-SPECs retired (REQ-568 S3, 16th rejection).
+  The S-491 embedding win belongs to direct query→file ranking and does not transport through the
+  spec-matching layer.
+
+## [0.15.0] - 2026-09-06
+
+The first field report on Holmes-Kit's own operational data (1,412 unique approval requests vs. 8
+decisions — a 99.4% write-only backlog) drove this release: the approval queue becomes a real
+decision inbox, the field data itself gains machine attribution, and "did you consider all three
+harnesses and all three OSes" stops being a habit and becomes a sealing gate.
+
+### Added
+- **Compatibility declaration gate (REQ-565)** — sealing an A-SPEC now requires two frontmatter
+  declarations, `harness_impact:` and `os_impact:` — either `'none: <real reason>'` or a full
+  3-cell mapping (`{claude, codex, agy}` / `{windows, mac, linux}`, verdicts
+  `supported|unavailable|n-a: <grounds>`). The duty lives on the **act of approval** (the
+  `breaking_change` shape), so already-approved specs are untouched; any spec that changes
+  re-approves and acquires the fields. A `none` claim is **cross-checked by machine**: Files to
+  Touch entries on the harness surface (`hooks/`, adapters, `cli/init|agents`, `mcp/server`)
+  contradict a harness `none`, and file contents carrying OS signals (`process.platform`,
+  `'win32'`, `spawn(`, `.ps1`) contradict an os `none` — a 3-cell mapping is exempt, because it
+  already faced the axis. `spec_slice_init` scaffolds both fields as TODO so authors meet them;
+  the gate refuses the untouched scaffold. The author-facing blocker list (`approvalBlockers`)
+  pre-announces everything the act would refuse — gate/act parity held by test.
+- **`holmes-kit approve --refusals [N]` (REQ-563)** — a read-only view of what this machine's gate
+  refused lately (newest last), so the operator can find the id a deny message named and decide it.
+- **Per-machine field data (REQ-562)** — test outcomes now record to
+  `test-outcomes.<replica>.jsonl` (the provenance replica convention) and merge with the legacy
+  file in timestamp order, so RED→GREEN sequences survive multi-machine histories; approval-queue
+  events carry a `replica` field (`unknown` for pre-existing events). A repo-local aggregator
+  (`src/tools/field-report`, **not shipped in the package**) turns the ledgers into gate-friction,
+  queue-health and RED-first metrics.
+
+### Fixed
+- **The approval queue is a decision inbox again (REQ-563)** — measured: 1,412 unique requests,
+  8 decisions, and the two real inbox items buried under 1,404 single-shot gate refusals nobody
+  ever meant to decide. Gate refusals (shell and unknown kinds) now land in a **local, per-replica
+  refusal log** (`.ax/approvals/refusals.<replica>.jsonl`, added to the managed gitignore — raw
+  commands never leave the machine, closing the public-repo exposure where 45% of tracked targets
+  carried absolute paths). Decision-seeking kinds (`spec-approve`, `config-write`,
+  `autonomy-grant`, `spec-reappraisal`) stay in the tracked queue. `approve <id>` falls back to
+  the refusal log, so the out-of-band shell approval path survives end to end (deny → approve →
+  allow, verified); re-opening after a decision is count-based (clock-free — a millisecond tie
+  was measured losing legitimate retries), and a hold's question now reaches the retry even for
+  refusal-log ids.
+- **Fixture pollution of real field data (REQ-563)** — the adapter parity suite ran deny scenarios
+  against the repository root: 774 `rm -rf /` requested-events over ten days, the single largest
+  item in the first field report. The suite now uses governed tmp roots; measured after: a full
+  suite run adds **zero** events to the real ledgers.
+
+### Notes
+- Version bump is **minor** with two `gate-behavior` changes aboard; the release classifier
+  routes this to HITL by design. The compat gate applies to **newly sealed** A-SPECs only.
+
 ## [0.14.0] - 2026-09-06
 
 Closes the gate's oldest blind spot: it judged *where* a change landed, never *what kind* of change it

package/README.md

@@ -25,6 +25,7 @@
 - 🤖 **Autonomous Approval — three layers, always bounded** *(reworked in 0.13.0; foundation 0.8.0)*: for teams that want the agent to self-drive the SDLC, autonomy is a posture the agent holds at two scopes — a **project default** you opt into at `holmes-kit init --autonomy` (persisted as the `HOLMES_AUTONOMOUS_APPROVAL` env in `.mcp.json`), and a **per-session envelope** you grant on the spot with `holmes-kit autonomy on --for 2h` (an expiring marker under the agent-write-protected `.ax/state/`). Under either, the agent seals **low-risk** specs itself (ledgered under an `autonomous:<client>` actor); every **governance-critical, high-risk, or irreversible** decision — `gate-behavior`/breaking A-SPECs, architecture/gate/taint files, and every upstream `REQ`/`H-SPEC`/`C-SPEC` — is instead **refused and routed to the out-of-band `holmes-kit approve` queue** for a human, never silently self-approved. The active posture is **surfaced at every session start** so it can't be forgotten *(0.14.0: the hook side now reads the project default out of `.mcp.json` directly, so an `init --autonomy` project sees its banner and escalations without an env round-trip)*, and an agent can never grant it to itself: the env is env-only (blocked like `HOLMES_ROLE`), the session command needs a real TTY or an out-of-band `HOLMES_APPROVAL`, and the marker lives where agents can't write. Off = byte-identical to a fully human-gated project. *(new in 0.10.0)* `HOLMES_ELICIT=off` routes every decision straight to the same queue.
 - 🧭 **Spec-Evolution Trigger** *(new in 0.14.0)*: the gate used to judge only *where* a change lands (file ∈ Files-to-Touch, anchored, approved) — never *what kind* of change it is, so a real architecture swap inside an approved scope passed unreviewed. Now, when a changed in-scope source **newly introduces an external dependency** (a swapped engine, a new runtime), Holmes-Kit raises a **spec-reappraisal**: manual mode warns at the turn boundary, and under autonomy it also files the drift in the out-of-band `holmes-kit approve` queue so the owner sees it — a decided reappraisal is never re-raised for the same drift. Observe-first by design: it never blocks a turn. Detection is TS/JS + Python, string- and comment-safe (prettier multiline imports, CRLF files, docstrings and template literals all judged correctly).
 - 🚢 **Release Autonomy + Docs-Currency Gate** *(new in 0.13.0)*: publishing is irreversible and outward, so `npm publish` stays **human-approved by default** — but a deterministic classifier (`releaseAutonomy`, reusing the same per-spec risk grade) lets a **low-risk** release (patch/minor, every spec auto-grade, autonomy on) self-publish under the ledger, while a **major** bump, any `gate-behavior`/security/architecture spec, or an upstream `REQ`/`H-SPEC` forces HITL. The `holmes-publish` playbook also gains a **docs-currency gate**: before any release it diffs the specs since the last tag and blocks if a user-facing change never reached `README`/`CHANGELOG` — a stale doc is a false claim.
+- 🧭 **Compatibility declaration gate** *(new in 0.15.0)*: Holmes-Kit runs on three agent harnesses (Claude Code, Codex, Antigravity) and three OSes (Windows/macOS/Linux) — and now the **sealing act itself asks whether you considered them**. A new A-SPEC approves only with `harness_impact:` and `os_impact:` declared (`'none: <reason>'` or a full 3-cell mapping with `supported|unavailable|n-a` verdicts); a `none` claim is machine-cross-checked against Files-to-Touch (harness-surface paths, OS-signal file contents), the slice scaffold plants both fields as TODO the gate refuses untouched, and already-sealed specs are untouched — the duty arrives with the next re-approval, exactly like `breaking_change`.
 - 🌐 **English CLI & hook surface** *(new in 0.13.0)*: the operator-facing CLI and hook messages — `doctor` output, the CLI usage/errors, the hook `deny` reasons and ART citations, and the interactive `approve`/`init`/`upgrade`/`semantic-key` prompts — are now English, guarded by a hangul-absence test over the **rendered runtime output** (not just a source scan, which misses `\u`-escaped strings). The MCP tool responses (`spec_create`/`spec_approve`/ledger/review) are still being migrated and are next.
 - 🪧 **Session Banner + Update Notice** *(new in 0.8.0; refresh implemented + made uniform in 0.12.2)*: every session start emits an English intro (version + governance rule + npm URL) to both the human transcript and the agent context (SessionStart hook + MCP `instructions`); when a newer published version is on npm, an install-mode-aware `holmes-kit upgrade` command is appended. The registry refresh (dist-tags query → cached in `~/.holmes/update-check.json`) is detached, TTL-gated, and fail-silent, and now fires from **every harness's MCP-server startup** — not just Claude's SessionStart hook — so Claude / Antigravity / Codex are notified alike. Opts out via `HOLMES_NO_UPDATE_CHECK`/`CI`. Upgrade execution stays your explicit choice (`holmes-kit upgrade`), never a silent auto-install.
 - 🧱 **Deterministic Gate, Hardened** *(new in 0.8.0; further hardened in 0.13.0)*: shell writes are judged at the segment's **effective working directory** (`cd sub && cat > ../src/x.ts` is sealed, legitimate out-of-tree scratch writes are freed); the governing anchor is the **whole set**, not the first match. *(0.13.0)* Two more bypasses are closed: the gate treats a project as **governed when any spec exists** (a fresh project holding only unapproved drafts is no longer an ungoverned free-for-all), and it classifies `cp`/`mv` by their **destination** (a copy/move landing on a source path is sealed even when the source file isn't code). Every gate change ships with two consecutive clean adversarial rounds.
@@ -33,7 +34,7 @@
 - 🐞 **Causal Defect Localization & CPG** *(equalized in 0.5–0.7)*: AST Code Property Graph (CFG/DDG/CDG) & Dataflow Taint reachability across 7 languages (TS/JS, Python, Go, Rust, Java, C/C++, C#) — **42 language×layer cells graded on measured evidence** (11 corpora, 39,344 functions, zero invariant violations; C++ conditional on 67.9% parse coverage, disclosed in the matrix).
 - 📏 **Measured, Not Claimed** *(new in 0.3.x)*: performance is judged against a pre-registered modeled-human band (R 0.67–0.78 / P ≈0.9±). Current official grade: **band entry on recall; division-of-labor precision 0.727 = 81% of the modeled human — reproduced by an independent context-free judge on a fresh blind window.** No superhuman claims until both metrics exceed the band.
 - 🧪 **Self-Healing & Diagnostic Doctor**: Automated integrity checks and self-healing auto-fix remediation (`holmes-kit doctor --fix` & `spec_remediate`) — wiring-handshake checks run on Windows natively as of 0.3.2. As of 0.9.0, doctor also reports holmes-kit's own advertised **MCP schema token cost** (computed live) and warns when `HOLMES_MCP_PROFILE=full` needlessly re-advertises the hook-enforced gate-duplicate tools.
-- 🔔 **Approval UX** *(new in 0.3.1)*: in-session approval dialogs forewarn their 120s deadline and, on expiry, the refusal says exactly where the decision went (`npx holmes-kit approve` out-of-band queue) — no more silently dead dialogs.
+- 🔔 **Approval UX** *(new in 0.3.1; inbox split 0.15.0)*: in-session approval dialogs forewarn their 120s deadline and, on expiry, the refusal says exactly where the decision went (`npx holmes-kit approve` out-of-band queue) — no more silently dead dialogs. Since 0.15.0 the tracked queue holds **decision-seeking requests only**; plain gate refusals live in a local per-machine refusal log (raw commands never leave the machine), browsable with `approve --refusals` and still decidable by id — measured before the split, 1,404 single-shot refusals were burying a 2-item inbox.
 - 🚦 **Push & Server-Side Re-Validation** *(hardened in 0.8.0)*: a local `pre-push` evidence gate (test-run ledger head == push HEAD, green, executed > 0) plus a **server-side CI workflow** that re-runs `npm ci → build → full suite → tarball install probe`, so a `--no-verify` push or a hook-less clone is still caught.
 - 📊 **Automated RTM & Taint Heatmap**: Interactive standalone HTML/SVG report generation (`generateRtmHeatmap`) for spec coverage and security dataflow reachability.
 - 🤖 **CLI-First AI Harness Matrix**: Native process hook gating for Claude Code, Antigravity CLI (AGY), Codex CLI, and Google Antigravity SDK.

package/dist/.build-id

@@ -1 +1 @@
-b352d54-mtpi1283
+b540876-mtqeiitb

package/dist/holmes/cli/approve.d.ts

@@ -83,6 +83,20 @@ export declare function decisionDetail(p: PendingRequest, tail?: string): string
  * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
  * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
  */
+/**
+ * @implements A-SPEC-563.2
+ * The read-only refusal view: what THIS machine's gate refused lately, newest last. The raw target
+ * appears on the operator's SCREEN only — the refusal log never leaves the machine (A-SPEC-563.1),
+ * and this renderer is the reason an operator can find the id the deny message named. Row width
+ * follows the decision list's screen-safe discipline.
+ */
+export declare function renderRefusals(refusals: Array<{
+    id: string;
+    kind: string;
+    target: string;
+    why: string;
+    ts: string;
+}>, limit?: number): string;
 export declare function renderNonTtyHint(state: QueueState): string;
 export interface ApproveIO {
     print: (s: string) => void;

package/dist/holmes/cli/approve.js

@@ -42,6 +42,7 @@ exports.subjectCells = subjectCells;
 exports.subjectRoom = subjectRoom;
 exports.decisionSubject = decisionSubject;
 exports.decisionDetail = decisionDetail;
+exports.renderRefusals = renderRefusals;
 exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246
@@ -78,7 +79,44 @@ const MAX_TTL_MINUTES = 7 * 24 * 60;
 const DEFAULT_RATIONALE = 'approved via holmes-kit approve';
 const findPending = (root, id) => {
     const state = (0, approval_queue_1.readQueue)(root);
-    return { entry: state.pending.find((p) => p.id === id), state };
+    const pending = state.pending.find((p) => p.id === id);
+    if (pending)
+        return { entry: pending, state };
+    // @implements A-SPEC-563.2 — the refusal-log fallback. Shell refusals no longer sit in the tracked
+    // inbox (A-SPEC-563.1), but the out-of-band approval story must survive: the operator saw the deny
+    // in session, the deny named this id, and the RAW target lives in this machine's local refusal log
+    // — exactly the "grant is for what the human saw" contract. A decided id never promotes: the
+    // granted/denied event in the queue closes the request, same single-use convention as pending.
+    try {
+        const { readRefusals } = require('../governance/approval-queue');
+        let mine = readRefusals(root).filter((r) => r.id === id);
+        // A decided id closes the request — UNLESS the gate refused it again afterwards. The fold has
+        // the same rule for pending (a later `requested` re-inserts after granted/denied): a human may
+        // change their mind, and the retry is what re-opens the question.
+        const decided = state.decisions[id];
+        if (decided) {
+            // Clock-free reopening: the decision recorded HOW MANY occurrences it covered, so a retry is
+            // simply everything past that count — millisecond ties (measured flaky under the full suite)
+            // cannot lose it. Legacy decisions without the count fall back to the timestamp rule.
+            if (typeof decided.covered === 'number')
+                mine = mine.slice(decided.covered);
+            else
+                mine = mine.filter((r) => r.ts > decided.ts);
+        }
+        if (mine.length > 0) {
+            const latest = mine[mine.length - 1];
+            return {
+                entry: {
+                    id, kind: latest.kind, target: latest.target, why: latest.why,
+                    count: mine.length, firstTs: mine[0].ts, lastTs: latest.ts,
+                    ...(latest.replica ? { replica: latest.replica } : {}),
+                },
+                state,
+            };
+        }
+    }
+    catch { /* a broken refusal log must not break the decision surface */ }
+    return { entry: undefined, state };
 };
 /** CLI-side event writer. The CLI runs in the operator's terminal, outside the session gates. */
 /**
@@ -186,7 +224,7 @@ function grantRequest(root, id, opts) {
         // class round-6 closed in findingContext, three files over.
         return { ok: false, reason: `cannot write the grant file:\n   ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
     }
-    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires })) {
+    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires, covered: entry.count })) {
         try {
             fs.rmSync(tmp, { force: true });
         }
@@ -212,7 +250,7 @@ function denyRequest(root, id, reason, actor) {
     // The event IS the decision here (there is no second artefact), so a failed append is a failed
     // decision — round-5: ✓ and exit 0 were printed over a read-only queue while nothing was recorded,
     // and the agent, never seeing the denial, retried forever.
-    if (!appendEvent(root, { event: 'denied', id, reason, actor })) {
+    if (!appendEvent(root, { event: 'denied', id, reason, actor, covered: entry.count })) {
         return { ok: false, reason: 'could not write the denial record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
     }
     return { ok: true };
@@ -366,6 +404,25 @@ function decisionDetail(p, tail = '') {
  * must transcribe: [noguess]. An empty queue yields an empty hint — nothing to act on, nothing to
  * advise. `renderPending` itself stays hint-free: the explicit `--list` output is for scripts.
  */
+/**
+ * @implements A-SPEC-563.2
+ * The read-only refusal view: what THIS machine's gate refused lately, newest last. The raw target
+ * appears on the operator's SCREEN only — the refusal log never leaves the machine (A-SPEC-563.1),
+ * and this renderer is the reason an operator can find the id the deny message named. Row width
+ * follows the decision list's screen-safe discipline.
+ */
+function renderRefusals(refusals, limit = 20) {
+    if (refusals.length === 0)
+        return '◆ no refusals recorded on this machine';
+    const recent = refusals.slice(-Math.max(1, limit));
+    const lines = [`◆ ${refusals.length} refusal(s) on this machine — showing ${recent.length} (newest last)`, ''];
+    for (const r of recent) {
+        lines.push(`${(0, screen_safe_1.rowField)(r.id, 20)} ${(0, screen_safe_1.rowField)(r.kind, screen_safe_1.KIND_COLS)} ${(0, screen_safe_1.rowField)(r.target, 40)}`);
+        lines.push(`  \u2502 ${(0, screen_safe_1.rowField)(r.why, 66)}  ${(0, screen_safe_1.rowField)(r.ts, 24)}`);
+    }
+    lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve <id>`);
+    return lines.join('\n');
+}
 function renderNonTtyHint(state) {
     if (state.pending.length === 0)
         return '';

package/dist/holmes/cli/gitignore-merge.js

@@ -36,6 +36,11 @@ exports.IGNORE_LINES = [
     // project content — left untracked they show up in `git status` and read as install damage.
     '.ax/state/',
     '*.holmes-bak-*',
+    // @implements A-SPEC-563.1 — the per-replica refusal log carries RAW refused commands (absolute
+    // paths measured in 45% of them), and the grant contract needs them raw ("the grant is for what
+    // the human saw" — round-14, exact match). Raw-and-local is the only shape that serves both ADR-012
+    // and approvals: the file never leaves the machine, and `holmes-kit approve` reads it right there.
+    '.ax/approvals/refusals*.jsonl',
     // @implements A-SPEC-193 — 하네스 배선물은 이 **설치본의 절대 경로**를 담는다(훅은 hooks.json
     // 이 있는 디렉터리를 cwd 로 돌고, 패키지가 어디 설치됐는지는 기계마다 다르다). 그 경로가
     // VCS 에 들어가면 다른 기계에서 남의 설치를 부르거나 아무것도 부르지 못한다. 팀과 공유하고

package/dist/holmes/cli/index.js

@@ -78,7 +78,7 @@ const KNOWN_FLAGS = {
     skills: ['help', 'target'],
     ci: ['help', 'target', 'specs-dir', 'json'],
     serve: ['help', 'target', 'port'],
-    approve: ['help', 'target', 'list', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
+    approve: ['help', 'target', 'list', 'refusals', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
     ledger: ['help', 'target', 'ref', 'dry-run'],
     // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
     'semantic-key': ['help'],
@@ -839,6 +839,18 @@ async function main(argv) {
             process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
             return 0;
         }
+        // @implements A-SPEC-563.2 — the read-only refusal view (local log; raw targets stay on-screen).
+        if (flags.refusals !== undefined) {
+            const { renderRefusals } = require('./approve');
+            const { readRefusals } = require('../governance/approval-queue');
+            const limit = typeof flags.refusals === 'string' ? Number(flags.refusals) : 20;
+            if (!Number.isInteger(limit) || limit <= 0) {
+                process.stderr.write(`✗ --refusals expects a positive integer count — received: ${flags.refusals}\n`);
+                return 1;
+            }
+            process.stdout.write(renderRefusals(readRefusals(root), limit) + '\n');
+            return 0;
+        }
         // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
         // named even on a non-TTY), then refuse a non-TTY (a resident interactive loop needs a terminal),
         // then run the loop. SIGINT and readline close both abort it — the operator leaving, either way,

package/dist/holmes/governance/approval-queue.d.ts

@@ -18,6 +18,24 @@
  * provenance chain already use, so a reader learns no new model.
  */
 export declare const QUEUE_RELPATH: string;
+export declare const DECISION_KINDS: ReadonlySet<string>;
+export interface RefusalRecord {
+    event: 'requested';
+    id: string;
+    kind: string;
+    target: string;
+    why: string;
+    ts: string;
+    replica?: string;
+    /** @implements A-SPEC-564.2 — the byte size of the deny feedback this refusal put back into the
+     * conversation (base reason + queue hint). Observation only; absent on legacy records. */
+    reasonBytes?: number;
+}
+export declare function refusalsFilename(replica: string): string;
+/** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
+export declare function isRefusalsFilename(name: string): boolean;
+/** All replica refusal logs of this project, merged in ts order (stable). Missing dir → []. */
+export declare function readRefusals(root: string): RefusalRecord[];
 export interface PendingRequest {
     id: string;
     kind: string;
@@ -28,6 +46,13 @@ export interface PendingRequest {
     lastTs: string;
     hold?: boolean;
     question?: string;
+    /**
+     * @implements A-SPEC-562.2
+     * Which machine raised this request (`resolveReplicaId`), or `'unknown'` for the events written
+     * before attribution existed. Display and aggregation ONLY — no gate, grant or approval decision
+     * reads it, so an absent or wrong value can never change a verdict.
+     */
+    replica?: string;
 }
 export interface QueueState {
     pending: PendingRequest[];
@@ -53,6 +78,17 @@ export interface QueueState {
         event: 'granted' | 'denied';
         reason?: string;
         ts: string;
+        covered?: number;
+    }>;
+    /**
+     * @implements A-SPEC-563.2
+     * Live holds by id, INDEPENDENT of pending: a shell refusal is no longer a pending entry
+     * (A-SPEC-563.1), but the operator's hold question must still reach the agent's next retry.
+     * A later decision clears the hold — an answered question is not still being asked.
+     */
+    holds: Record<string, {
+        question?: string;
+        ts: string;
     }>;
 }
 /**
@@ -88,6 +124,7 @@ export declare function enqueueApprovalRequest(root: string, req: {
     kind: string;
     target: string;
     why: string;
+    reasonBytes?: number;
 }): boolean;
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 export declare function readQueue(root: string, opts?: {
@@ -104,4 +141,6 @@ export declare function queueHint(root: string, req: {
     kind: string;
     target: string;
     why: string;
+}, opts?: {
+    baseReasonBytes?: number;
 }): string;

package/dist/holmes/governance/approval-queue.js

@@ -33,7 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QUEUE_RELPATH = void 0;
+exports.DECISION_KINDS = exports.QUEUE_RELPATH = void 0;
+exports.refusalsFilename = refusalsFilename;
+exports.isRefusalsFilename = isRefusalsFilename;
+exports.readRefusals = readRefusals;
 exports.approvalRequestId = approvalRequestId;
 exports.foldQueue = foldQueue;
 exports.enqueueApprovalRequest = enqueueApprovalRequest;
@@ -45,6 +48,7 @@ const npx_bin_1 = require("../project/npx-bin");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const screen_safe_1 = require("../cli/screen-safe");
+const replica_id_1 = require("./replica-id");
 /**
  * The approval request queue — the review list a human batches decisions over.
  *
@@ -65,6 +69,58 @@ const screen_safe_1 = require("../cli/screen-safe");
  * provenance chain already use, so a reader learns no new model.
  */
 exports.QUEUE_RELPATH = path.join('.ax', 'approvals', 'queue.jsonl');
+// @implements A-SPEC-563.1 — the tracked queue is a DECISION INBOX, not a refusal log. Measured
+// (field report, 2026-09-06): 1,412 unique requests vs 8 decisions — 99.8% of the backlog was
+// single-shot gate refusals nobody ever meant to decide, burying the real inbox (spec-approve 9,
+// config-write 1) and accumulating raw shell commands in a tracked file. Only these kinds seek a
+// decision; everything else routes to the local per-replica refusal log below. Wired RED-first.
+exports.DECISION_KINDS = new Set([
+    'spec-approve', 'config-write', 'autonomy-grant', 'spec-reappraisal',
+]);
+const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
+function refusalsFilename(replica) {
+    return `refusals.${replica}.jsonl`;
+}
+/** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
+function isRefusalsFilename(name) {
+    return REFUSALS_FILE_RE.test(name);
+}
+/** All replica refusal logs of this project, merged in ts order (stable). Missing dir → []. */
+function readRefusals(root) {
+    const dir = path.join(root, '.ax', 'approvals');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter(isRefusalsFilename).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    let i = 0;
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && r.event === 'requested' && typeof r.id === 'string'
+                    && typeof r.kind === 'string' && typeof r.target === 'string' && typeof r.ts === 'string') {
+                    out.push({ r: r, i: i++ });
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out.sort((a, b) => (a.r.ts < b.r.ts ? -1 : a.r.ts > b.r.ts ? 1 : a.i - b.i)).map((e) => e.r);
+}
 /**
  * Deterministic request id from the action's identity.
  *
@@ -87,6 +143,7 @@ function approvalRequestId(kind, target) {
 function foldQueue(lines, opts) {
     const pending = new Map();
     const decisions = {};
+    const holds = {};
     let malformedLines = 0;
     for (const raw of Array.isArray(lines) ? lines : []) {
         const line = String(raw ?? '').trim();
@@ -127,6 +184,9 @@ function foldQueue(lines, opts) {
                         count: 1,
                         firstTs: ts,
                         lastTs: ts,
+                        // @implements A-SPEC-562.2 — events written before attribution existed have no field;
+                        // `unknown` names that honestly instead of pretending they came from this machine.
+                        replica: typeof e.replica === 'string' && e.replica !== '' ? e.replica : 'unknown',
                     });
                 }
                 break;
@@ -135,10 +195,12 @@ function foldQueue(lines, opts) {
             case 'denied':
                 if (id) {
                     pending.delete(id);
+                    delete holds[id]; // @implements A-SPEC-563.2 — a decision answers the question
                     decisions[id] = {
                         event: e.event,
                         ...(typeof e.reason === 'string' ? { reason: e.reason } : {}),
                         ts: typeof e.ts === 'string' ? e.ts : '',
+                        ...(typeof e.covered === 'number' ? { covered: e.covered } : {}),
                     };
                 }
                 break;
@@ -149,6 +211,10 @@ function foldQueue(lines, opts) {
                     if (typeof e.question === 'string')
                         entry.question = e.question;
                 }
+                // @implements A-SPEC-563.2 — record the hold by id too: a refusal-log request has no pending
+                // entry to hang the question on, and the question must still reach the retry.
+                if (id)
+                    holds[id] = { ...(typeof e.question === 'string' ? { question: e.question } : {}), ts: typeof e.ts === 'string' ? e.ts : '' };
                 break;
             }
             default:
@@ -158,7 +224,7 @@ function foldQueue(lines, opts) {
     }
     const all = [...pending.values()];
     if (!opts)
-        return { pending: all, expired: [], malformedLines, decisions };
+        return { pending: all, expired: [], malformedLines, decisions, holds };
     // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
     // clockless entry must never be silently hidden by a clock it does not carry.
     const expired = [];
@@ -167,7 +233,7 @@ function foldQueue(lines, opts) {
         const last = Date.parse(p.lastTs);
         (Number.isFinite(last) && last + opts.ttlMs < opts.now ? expired : active).push(p);
     }
-    return { pending: active, expired, malformedLines, decisions };
+    return { pending: active, expired, malformedLines, decisions, holds };
 }
 /**
  * Append a request event. Fire-and-forget.
@@ -186,8 +252,27 @@ function enqueueApprovalRequest(root, req) {
         // An ungoverned directory gets no queue and no hint; it is not part of the system.
         if (!fs.existsSync(path.join(root, '.ax')))
             return false;
-        const file = path.join(root, exports.QUEUE_RELPATH);
+        // @implements A-SPEC-563.1 — kind routing: only decision-seeking kinds enter the tracked inbox;
+        // a gate refusal (shell, or any future kind — fail-safe toward a clean inbox) goes to this
+        // machine's LOCAL refusal log, raw target and all, where the approve fallback can still find it.
+        let refusalReplica = 'local';
+        try {
+            refusalReplica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = exports.DECISION_KINDS.has(req.kind)
+            ? path.join(root, exports.QUEUE_RELPATH)
+            : path.join(root, '.ax', 'approvals', refusalsFilename(refusalReplica));
         fs.mkdirSync(path.dirname(file), { recursive: true });
+        // @implements A-SPEC-562.2 — stamp the machine. Best-effort: a resolver failure omits the field
+        // rather than losing the request, because the queue is the channel a refusal depends on.
+        let replica;
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root);
+        }
+        catch {
+            replica = undefined;
+        }
         const event = {
             event: 'requested',
             id: approvalRequestId(req.kind, req.target),
@@ -195,6 +280,11 @@ function enqueueApprovalRequest(root, req) {
             target: req.target,
             why: req.why,
             ts: new Date().toISOString(),
+            ...(replica !== undefined && replica !== '' ? { replica } : {}),
+            // @implements A-SPEC-564.2 — only the refusal log carries the feedback cost; inbox kinds have
+            // no deny text to measure.
+            ...(!exports.DECISION_KINDS.has(req.kind) && typeof req.reasonBytes === 'number' && Number.isFinite(req.reasonBytes)
+                ? { reasonBytes: Math.max(0, Math.round(req.reasonBytes)) } : {}),
         };
         // TYPE BEFORE WRITE, for the same reason as the read (round-7): `appendFileSync` on a FIFO with
         // no reader blocks in open(2) forever. Guarding only the reader left the GATE wedged — measured:
@@ -244,12 +334,12 @@ function readQueue(root, opts) {
         // hook, the stop hook and the MCP handlers, not just the CLI. `approve-context.ts` has guarded
         // this since the 2026-08-24 hang; the queue reader, which far more code depends on, did not.
         if (!fs.lstatSync(file).isFile())
-            return { pending: [], expired: [], malformedLines: 1, decisions: {} };
+            return { pending: [], expired: [], malformedLines: 1, decisions: {}, holds: {} };
         const raw = fs.readFileSync(file, 'utf8');
         return foldQueue(raw.split('\n'), opts);
     }
     catch {
-        return { pending: [], expired: [], malformedLines: 0, decisions: {} };
+        return { pending: [], expired: [], malformedLines: 0, decisions: {}, holds: {} };
     }
 }
 /**
@@ -258,7 +348,7 @@ function readQueue(root, opts) {
  * Appended ONLY when the enqueue succeeded: a hint naming an id that was never written would send
  * the operator to an empty list.
  */
-function queueHint(root, req) {
+function queueHint(root, req, opts) {
     const id = approvalRequestId(req.kind, req.target);
     // @implements A-SPEC-246
     // Decisions are read BEFORE filing, so a human's answer reaches the agent in the very refusal
@@ -271,7 +361,8 @@ function queueHint(root, req) {
     // text is read twice: printed in the operator's terminal AND carried in the agent's refusal. Raw,
     // a held request could erase the screen and paint a line claiming the operator had approved. The
     // decision surface's rule applies here too — line structure belongs to the template.
-    const held = state.pending.find((p) => p.id === id && p.hold);
+    const held = state.pending.find((p) => p.id === id && p.hold)
+        ?? (state.holds[id] ? { question: state.holds[id].question } : undefined); // @implements A-SPEC-563.2
     // Round-5: folded to terminal rows. This text is read in a terminal by the operator as well, and
     // an unfolded hint carrying 300 columns of agent-authored question wraps unpredictably around
     // whatever the gate printed before it.
@@ -288,7 +379,11 @@ function queueHint(root, req) {
     const denialLine = decided?.event === 'denied'
         ? (0, screen_safe_1.wrapColumns)(`\n[거부됨${decided.reason ? `: ${(0, screen_safe_1.flattenField)(decided.reason, 300)}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`, 76, '  \u2502 ')
         : '';
-    return enqueueApprovalRequest(root, req)
-        ? `${denialLine}\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`
+    // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
+    // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
+    // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
+    const hint = `${denialLine}\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
+    return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
+        ? hint
         : denialLine;
 }