@holmes-lab/holmes-kit 0.1.17 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.2.0] - 2026-08-27
+
+The approval decision surface, world-tier: the operator stays at one screen, and a grant is exactly what they saw.
+
+### Added
+- **`approve --watch` — a resident decision surface (REQ-262)**: `holmes-kit approve --watch` stays open and polls the approval queue, so a blocked request appears the moment it arrives, one key decides it, and an empty queue idles instead of exiting (Ctrl-C quits). The operator no longer re-runs `approve` per request or transcribes a long id into another window. Harness-independent — the queue is a file, so a request from Claude Code, Codex CLI or Antigravity is decided on the same screen with the same keys. `--poll-ms <ms>` tunes the idle cadence; a non-TTY invocation is refused with guidance to use `--list`. The reaction deadline (a request surfaces within one poll cycle) is a tested judgment, not prose.
+- **In-session approval via MCP elicitation (REQ-263)**: when a client advertises the `elicitation` capability, an `spec_approve` / `review-resolve` that would be refused for want of an approval becomes a question inside the session — one human answer completes it, no out-of-band `--grant`. The policy (which kinds are elicitable) and protocol (question form, response interpretation) are pure and fail-closed: an unsupported client, a declined/cancelled dialog, a malformed response, or a timeout all degrade to the exact same refusal-and-queue text as before. A single-use approval leaves nothing reusable behind.
+- **`ledger rechain` — provenance that survives rebase and merge (REQ-256)**: a new subcommand re-links the provenance hash-chain against an explicit mainline after history is rewritten, ships `merge=union` attributes so a merge does not fork the chain, and buffers appends made mid-rebase into a sidecar that flushes, under the same lock, on the first append after the rebase ends. A `git rebase`/`merge` of a governed branch no longer strands the ledger.
+- **`doctor` detects distributed spec-id preemption (REQ-254)**: two new read-only checks — a WARN when the same spec id carries mismatched content digests (with the conflicting file paths), and a WARN when a bare id and its dotted-suffix family coexist (with the file lists). A legitimate duplicate (same id, same digest) and a clean store stay silent.
+
+### Fixed
+- **The decision screen cannot be forged, and it shows every byte it is deciding on (REQ-262)**: a decision row now carries only characters whose terminal width is known — every control, combining, zero-width, bidi, variation-selector, tab or ambiguous-width character an agent might place in a command or a spec is rendered as its own `\uXXXX` escape. Nothing on the screen can repaint it, hide behind an ANSI conceal, misalign a row, or pose as a line the template wrote; a removed character is shown, not silently dropped. The `[v]` detail view stays readable (folded under a template-owned margin) so a Korean command or spec body reads as itself.
+- **A derived grant matches the command literally — `rm -rf *` no longer authorizes `rm -rf /anything` (REQ-262)**: a grant minted from an approved queue target is compared to the action by string equality, so a `*` or a trailing `/` in the target is that character, not a wildcard or a directory prefix. The screen deliberately shows no scope grammar, so the operator could not have known the `*` they saw was a glob; now it isn't one. A present-but-malformed narrowing flag fails closed.
+- **A closed output pipe is the end of a pipeline, not a crash (REQ-262)**: `approve`, `approve --watch` and `approve --list` piped to a reader that stops early (`| head`) now exit quietly with the conventional status instead of printing a Node stack trace. The stdout guard now installs on every shipped invocation — it previously lived in an entry block the `holmes-kit` binary never runs, so it was dead on the shipped package.
+
+### Unverified (named)
+- Windows execution and CI remain program-level gaps this release does not close.
+
+## [0.1.18] - 2026-08-23
+
+### Fixed
+- **The npx MCP wiring actually starts the server (REQ-259)**: `init` on an npm-installed package wrote `npx -y @holmes-lab/holmes-kit@<ver> holmes-mcp`, which npx resolves to the package-name-matching *default* binary (`holmes-kit`) with `holmes-mcp` as its argument — exit 1, so **every npm-installed wiring since the 0.1.15 npx pin launched a dead MCP server** (`CONNECTION_CLOSED` in the harness). The wiring now rides `-p` (`npx -y -p <pkg>@<ver> holmes-mcp`), the launcher test spawns the generated form against a locally packed tarball (with the pre-fix form kept as a failing control), and `doctor` gains **`mcp wiring spawn`** — it runs the target's `.mcp.json` command verbatim inside a 30s bound and names a dead wiring FAIL with the re-init remediation. Existing projects: re-run `holmes-kit init` (doctor will point at the dead wiring).
+- **`serverInfo.version` reports the real package version** — it was hardcoded to `0.1.0`, blinding client-side drift diagnosis.
+
+### Changed
+- **`approve` without a TTY names the next command (REQ-260)**: the implicit non-TTY fallback (e.g. Claude Code's `!` shell) used to print the pending list and exit 0 silently; it now appends runnable `--grant` / `--deny` / `--ask` examples carrying the first real pending id. Explicit `--list` output is unchanged for scripts.
+
 ## [0.1.17] - 2026-08-23
 
 The two `main` lines — the Windows-compatibility line (12 commits, verified on Windows 11 and

package/dist/.build-id

@@ -1 +1 @@
-e6199ca-mt5qbc5d
+f7a048d-mtbm5atb

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

@@ -0,0 +1,2 @@
+import { PendingRequest } from '../governance/approval-queue';
+export declare function renderDecisionContext(root: string, entry: PendingRequest): string;

package/dist/holmes/cli/approve-context.js

@@ -0,0 +1,180 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDecisionContext = renderDecisionContext;
+// @implements A-SPEC-262.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const screen_safe_1 = require("./screen-safe");
+/**
+ * What is actually being approved.
+ *
+ * REQ-262 measured the harm: the queue carries kind/target/why, and a human approved three A-SPECs
+ * without ever seeing their contents — a rubber stamp, not a decision. This renderer fetches the
+ * SUBJECT for the screen: a spec's body, a finding's record, or (for shell/config-write shapes) the
+ * target verbatim, which IS the subject the queue holds.
+ *
+ * READ-ONLY, and no failure may kill the surface: a context that cannot be read reports WHY in one
+ * line and the decision stays possible. If missing context blocked deciding, this screen would
+ * become a second gate — and the gate is not what REQ-246 built here.
+ */
+const MAX_BODY = 2400;
+// Clipping is code-point safe and painting bytes never reach the screen (round-1): a UTF-16 slice
+// cut a surrogate pair in half, and an ANSI sequence inside a spec body could repaint the terminal
+// the human is deciding on.
+// Round-5: every context row is folded to a terminal row — a body is shown, not flooded.
+// Round-6: and folded UNDER A MARGIN, so no body byte can start a line and pose as a template row.
+const BODY_INDENT = '  \u2502 ';
+// Round-10: the clip ran AFTER escaping, so it counted escape-expanded units — 500 non-breaking
+// spaces (503 source characters) reported "603자 잘림", a statement false on its face on the screen
+// whose job is saying how much is not shown, and it cut MAX_BODY's real budget by six. It also let
+// the cut land INSIDE an escape, leaving a bare `00` that was the tail of `\u3000` (round-1's
+// severed-surrogate lesson, one representation later). The source is clipped first; the notice then
+// counts what it always should have.
+const clip = (s) => (0, screen_safe_1.wrapColumns)((0, screen_safe_1.stripControl)((0, screen_safe_1.clipCodePoints)(s, MAX_BODY)), 76, BODY_INDENT);
+function specContext(root, id) {
+    const specsDir = path.join(root, '.ax', 'specs');
+    // Found BY ID, never by guessing a filename — which folder holds which type is the store's
+    // business, not this screen's. The store's own `list()` is async and this screen is synchronous
+    // (a screen must not force its caller to become async), so the walk mirrors the store's tolerance:
+    // skip what cannot be read, never throw.
+    //
+    // @implements A-SPEC-262.1 — EVERY match is collected, not the first. Round-1: `.ax/specs` is not
+    // a protected directory and draft authoring is deliberately free, so an agent could drop a second
+    // file carrying the same id; the walk returned whichever readdir reached first and the human read
+    // a benign DECOY body while spec_approve sealed the real spec. Two files claiming one id is an
+    // ambiguity this screen refuses to resolve — the same doctrine spec_approve applies to duplicates
+    // — and the source path is always named so the human knows which file they read.
+    const found = [];
+    const { parseSpec } = require('../spec/spec-parser');
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+                continue;
+            }
+            if (!e.name.endsWith('.md'))
+                continue;
+            try {
+                if (!fs.statSync(p).isFile())
+                    continue; // never open a FIFO (the 2026-08-24 hang lesson)
+                const spec = parseSpec(fs.readFileSync(p, 'utf8'));
+                if (spec.id === id)
+                    found.push({ spec, file: path.relative(specsDir, p).split(path.sep).join('/') });
+            }
+            catch { /* unreadable file: the store's own reports own that */ }
+        }
+    };
+    walk(specsDir);
+    // The absolute specs path alone can exceed a row on a real machine, so it gets one of its own.
+    if (found.length === 0) {
+        return `맥락을 읽을 수 없습니다: 스펙 ${(0, screen_safe_1.rowField)(id, 24)} 를 찾지 못했습니다\n   ${(0, screen_safe_1.rowField)(specsDir, 76)}`;
+    }
+    if (found.length > 1) {
+        return [
+            `맥락이 모호합니다: ${(0, screen_safe_1.rowField)(id, 40)} 를 주장하는 파일이 ${found.length}건입니다:`,
+            ...found.map((f) => `   ${(0, screen_safe_1.rowField)(f.file, 72)}`).sort(),
+            '어느 것이 승인 대상인지 확정되기 전에는 본문을 보여 주지 않습니다',
+        ].join('\n')
+            + `\n   (holmes-kit doctor 의 'spec id 선점 충돌'을 확인하십시오)`;
+    }
+    const { spec, file } = found[0];
+    const body = [spec.preamble ?? '', ...Object.entries(spec.sections).map(([h, t]) => `## ${h}\n${t}`)]
+        .filter((s2) => s2.trim() !== '').join('\n\n');
+    return clip(`■ ${(0, screen_safe_1.flattenField)(spec.id, 40)} — ${(0, screen_safe_1.flattenField)(spec.title, 120)}\n   [현재 상태: ${(0, screen_safe_1.flattenField)(spec.status, 20)}]  (${(0, screen_safe_1.flattenField)(file, 60)})\n\n${body}`);
+}
+function findingContext(root, id) {
+    const file = path.join(root, '.ax', 'ledger', 'findings.jsonl');
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    // Round-6: the one producer here with neither a sanitiser nor a fold, while its sibling three
+    // lines up (`specContext` not-found) had both. Measured at 555 columns — seven rows — for an
+    // ordinary missing ledger on an ordinary path. The errno message is not agent-controlled today,
+    // but the path is composed from `root`, and "not agent-controlled today" is how round-2's misses
+    // were justified as well.
+    catch (e) {
+        return [
+            '맥락을 읽을 수 없습니다: 발견 원장을 읽지 못했습니다',
+            `   ${(0, screen_safe_1.rowField)(file, 76)}`,
+            `   ${(0, screen_safe_1.rowField)(String(e instanceof Error ? e.message : e).split('\n')[0], 76)}`,
+        ].join('\n');
+    }
+    let latest;
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const f = JSON.parse(line);
+            if (f.id === id)
+                latest = f; // last wins: the ledger is append-only history
+        }
+        catch { /* a torn line is the ledger's own report, not this screen's */ }
+    }
+    // Round-3: this was the one sibling site that skipped flattenField, and it is outside clip() —
+    // a review-resolve target that is not in the ledger repainted the whole interactive screen.
+    if (!latest)
+        return `맥락을 읽을 수 없습니다: 발견 ${(0, screen_safe_1.rowField)(id, 24)} 의 기록이 원장에 없습니다`;
+    return clip(`■ 발견 ${(0, screen_safe_1.flattenField)(id, 60)}\n   [${(0, screen_safe_1.flattenField)(String(latest.severity ?? '?'), 20)} · ${(0, screen_safe_1.flattenField)(String(latest.status ?? '?'), 20)}${latest.category ? ' · ' + (0, screen_safe_1.flattenField)(String(latest.category), 40) : ''}]\n\n${(0, screen_safe_1.flattenField)(String(latest.summary ?? '(요약 없음)'), 2000)}`);
+}
+function renderDecisionContext(root, entry) {
+    try {
+        if (entry.kind === 'spec-approve')
+            return specContext(root, entry.target);
+        if (entry.kind === 'review-resolve')
+            return findingContext(root, entry.target);
+        // shell / config-write / anything else: the queue's target IS the subject.
+        // A shell/config-write target is ONE command: flattened, so it cannot forge lines on the screen.
+        // [v] is the escape hatch for a target the list row had to clip, so its cap is generous — a
+        // decision surface that cannot show the subject anywhere has failed at its one job (round-2).
+        // Round-9: this branch went through `flattenField`, which does not escape the space characters
+        // that are not spaces — so `[v]`, the view a clipped row SENDS the operator to, printed
+        // `rm -rf\u00a0/` as `rm -rf /`. It uses the same body pipeline as every other subject now.
+        return `■ ${(0, screen_safe_1.rowField)(entry.kind, 40)}\n\n${clip(entry.target)}`;
+    }
+    catch (e) {
+        // Belt and braces: no context failure may kill the decision surface.
+        return `맥락을 읽을 수 없습니다:\n   ${(0, screen_safe_1.rowField)(String(e instanceof Error ? e.message : e).split('\n')[0], 76)}`;
+    }
+}

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

@@ -0,0 +1,27 @@
+import { PendingRequest } from '../governance/approval-queue';
+/**
+ * Transcription-zero references for the decision surface.
+ *
+ * REQ-262 measured the harm: a human retyping `--grant req-f5bae240c` into another window truncated
+ * the id and the decision died. Git's short hashes are the lesson — people type the least the screen
+ * already shows. Three grammars, non-overlapping by construction:
+ *
+ *   - a bare number is the 1-BASED INDEX of the printed list (`[1] …`),
+ *   - an exact id is itself,
+ *   - anything else is a PREFIX, and it must be unique.
+ *
+ * The number and the prefix cannot collide: queue ids are `req-<12hex>` (approvalRequestId), so no
+ * id can start with a digit. A numeric miss is therefore NOT retried as a prefix — that fallback
+ * would manufacture the very ambiguity this grammar exists to avoid.
+ *
+ * An ambiguous prefix is REFUSED BY NAME (every candidate listed): on a decision surface "probably
+ * this one" is not a decision (REQ-262 Constraints). PURE — no I/O, no clock.
+ */
+export type RefResolution = {
+    ok: true;
+    entry: PendingRequest;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveRequestRef(pending: PendingRequest[], ref: string): RefResolution;

package/dist/holmes/cli/approve-ref.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRequestRef = resolveRequestRef;
+const screen_safe_1 = require("./screen-safe");
+function resolveRequestRef(pending, ref) {
+    const r = ref.trim();
+    if (r === '')
+        return { ok: false, reason: '참조가 비어 있습니다 — 목록의 번호나 id 접두를 주십시오' };
+    if (pending.length === 0)
+        return { ok: false, reason: '승인 대기 중인 요청이 없습니다' };
+    if (/^\d+$/.test(r)) {
+        const n = Number(r);
+        if (n < 1 || n > pending.length) {
+            return { ok: false, reason: `번호 ${(0, screen_safe_1.rowField)(r, 20)} 는 목록 밖입니다 — 유효 범위는 1..${pending.length} 입니다` };
+        }
+        return { ok: true, entry: pending[n - 1] };
+    }
+    // Exact BEFORE prefix: when one id is a prefix of another, the exact spelling is not ambiguous —
+    // it is the most precise thing the human could have typed.
+    const exact = pending.find((p) => p.id === r);
+    if (exact)
+        return { ok: true, entry: exact };
+    const matches = pending.filter((p) => p.id.startsWith(r));
+    if (matches.length === 1)
+        return { ok: true, entry: matches[0] };
+    if (matches.length === 0) {
+        return { ok: false, reason: `참조 '${(0, screen_safe_1.rowField)(r, 60)}' 에 맞는 대기 요청이 없습니다 — 목록의 번호나 id 접두를 확인하십시오` };
+    }
+    return {
+        ok: false,
+        // The ids are AGENT-CHOSEN text (round-2): this refusal is printed on the operator's terminal.
+        // Round-5: the candidates rode on the refusal's own line, so enough of them (or one forged wide
+        // id) wrapped it past a row and pushed the question off the top of the screen. The refusal keeps
+        // one row; each candidate gets its own, which is also how the operator copies one.
+        reason: [
+            `참조 '${(0, screen_safe_1.rowField)(r, 30)}' 가 ${matches.length}건에 맞습니다 — 더 길게 주십시오:`,
+            ...matches.map((m) => `   ${(0, screen_safe_1.rowField)(m.id, 60)}`),
+        ].join('\n'),
+    };
+}

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

@@ -0,0 +1,29 @@
+import { ApproveIO } from './approve';
+/** The idle line, printed once on entering idle (not on every poll — flood is the template's enemy). */
+export declare const WATCH_IDLE = "\u25C6 \uC2B9\uC778 \uB300\uAE30 \uC911\u2026 (Ctrl-C \uB85C \uC885\uB8CC)";
+/** Default idle poll cadence. The reaction DEADLINE is a tested judgment (T-SPEC), not this number. */
+export declare const DEFAULT_POLL_MS = 500;
+export interface WatchOpts {
+    /** Idle poll cadence in ms. */
+    pollMs?: number;
+    /** Ends the resident loop and any in-flight idle wait / keypress wait. */
+    signal?: AbortSignal;
+    /**
+     * Wait one idle poll cycle. Injected so tests drive the loop deterministically without wall time.
+     * Must resolve early if `signal` aborts, so an idle watch shuts down at once.
+     */
+    waitIdle?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Exported for test: the shipped idle wait must resolve at once on abort, not after the timer. */
+export declare function defaultWaitIdle(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Run the resident decision surface until `signal` aborts.
+ *
+ * Each pass reads the queue once. A non-empty queue is handed to runInteractive (S-262.1 verbatim —
+ * same one-key flow, same escaping); when it returns, the snapshot is spent and the loop re-reads,
+ * so a request that arrived during a decision is presented on the next pass (one cycle late, never
+ * lost). An empty queue announces idle once and waits a poll cycle. Abort — in the idle wait or in
+ * runInteractive's keypress wait (which rejects AbortError, wired by the caller) — ends the loop and
+ * resolves; pending items stay in the queue.
+ */
+export declare function runWatch(root: string, io: ApproveIO, actor: string, opts?: WatchOpts): Promise<void>;

package/dist/holmes/cli/approve-watch.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_POLL_MS = exports.WATCH_IDLE = void 0;
+exports.defaultWaitIdle = defaultWaitIdle;
+exports.runWatch = runWatch;
+// @implements A-SPEC-262.2
+//
+// The RESIDENCE of the decision surface. S-262.1 made the surface's CONTENT (transcript-zero
+// references, context, one-key/batch); this is a thin polling loop over that content, so a request
+// appears the moment it arrives, decisions continue, and an empty queue idles instead of exiting.
+//
+// It adds NO rendering and NO terminal-control sequences — the sixteen rounds of escaping work in
+// screen-safe.ts stay untouched. runWatch only reads the queue, delegates a non-empty queue to the
+// existing runInteractive, and waits between polls when the queue is empty.
+const approval_queue_1 = require("../governance/approval-queue");
+const approve_1 = require("./approve");
+/** The idle line, printed once on entering idle (not on every poll — flood is the template's enemy). */
+exports.WATCH_IDLE = '◆ 승인 대기 중… (Ctrl-C 로 종료)';
+/** Default idle poll cadence. The reaction DEADLINE is a tested judgment (T-SPEC), not this number. */
+exports.DEFAULT_POLL_MS = 500;
+/** Exported for test: the shipped idle wait must resolve at once on abort, not after the timer. */
+function defaultWaitIdle(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+        const onAbort = () => { clearTimeout(timer); resolve(); };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Run the resident decision surface until `signal` aborts.
+ *
+ * Each pass reads the queue once. A non-empty queue is handed to runInteractive (S-262.1 verbatim —
+ * same one-key flow, same escaping); when it returns, the snapshot is spent and the loop re-reads,
+ * so a request that arrived during a decision is presented on the next pass (one cycle late, never
+ * lost). An empty queue announces idle once and waits a poll cycle. Abort — in the idle wait or in
+ * runInteractive's keypress wait (which rejects AbortError, wired by the caller) — ends the loop and
+ * resolves; pending items stay in the queue.
+ */
+async function runWatch(root, io, actor, opts = {}) {
+    const pollMs = opts.pollMs ?? exports.DEFAULT_POLL_MS;
+    const signal = opts.signal;
+    const waitIdle = opts.waitIdle ?? defaultWaitIdle;
+    let idleAnnounced = false;
+    // The pending ids the operator was last SHOWN. An item they skipped stays in the queue, so without
+    // this the loop would re-present it every poll — a flood, and (with no wait between) a busy spin
+    // that starves the event loop. We re-present only when the pending set has something NEW in it;
+    // skipped items wait, silently, until they change or a new request joins them.
+    let lastPresented = new Set();
+    while (!signal?.aborted) {
+        const state = (0, approval_queue_1.readQueue)(root);
+        // Prune ids that are no longer pending BEFORE deciding what is new (round-1 F1). Without this,
+        // `lastPresented` kept the id of an item that was decided and removed, so when that id came
+        // BACK — the agent retrying a denied action, which is the very thing a resident operator watches
+        // for — it read as already-seen and was never re-presented, as long as some skipped sibling kept
+        // the queue non-empty (the empty-queue reset never fired). A departed id is new again on return.
+        const pendingIds = new Set(state.pending.map((p) => p.id));
+        lastPresented = new Set([...lastPresented].filter((id) => pendingIds.has(id)));
+        const hasNew = state.pending.some((p) => !lastPresented.has(p.id));
+        if (state.pending.length > 0 && hasNew) {
+            idleAnnounced = false;
+            const shown = new Set(state.pending.map((p) => p.id)); // what this pass presents
+            try {
+                await (0, approve_1.runInteractive)(root, io, actor);
+            }
+            catch (e) {
+                // The operator leaving mid-decision (Ctrl-C / EOF) surfaces as AbortError through the
+                // caller's `ask`. That ends the watch quietly — it is not an error to report.
+                if (e?.name === 'AbortError')
+                    return;
+                throw e;
+            }
+            // Remember only the shown ids that are STILL pending after the pass — the ones the operator
+            // SKIPPED. A decided item (granted/denied) has left the queue, so it is NOT remembered, and if
+            // its id returns (a retry after denial) it reads as new and is re-presented (round-1 F1). A
+            // request that arrived DURING the pass is not in `shown`, so it too is new next pass — one
+            // cycle late, not lost. Skipped items are in both sets, so they are not re-flooded.
+            const afterIds = new Set((0, approval_queue_1.readQueue)(root).pending.map((p) => p.id));
+            lastPresented = new Set([...shown].filter((id) => afterIds.has(id)));
+        }
+        else if (state.pending.length === 0) {
+            if (!idleAnnounced) {
+                io.print(exports.WATCH_IDLE);
+                idleAnnounced = true;
+            }
+            // No reset of `lastPresented` here (round-3): the top-of-pass prune above already intersects
+            // it with the current pending set every pass, so on an empty queue it becomes empty before it
+            // is ever read — a reset here was dead code (proven behavior-neutral: a poison value survived
+            // the whole suite). A later re-arrival is still genuinely new, guaranteed by that prune.
+        }
+        await waitIdle(pollMs, signal); // ALWAYS yield a poll cycle — no tight re-presentation
+    }
+}

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

@@ -1,4 +1,4 @@
-import { QueueState } from '../governance/approval-queue';
+import { QueueState, PendingRequest } from '../governance/approval-queue';
 export type DecisionResult = {
     ok: true;
     expires?: string;
@@ -6,19 +6,11 @@ export type DecisionResult = {
     ok: false;
     reason: string;
 };
-/**
- * Approve: mint the narrow grant this request was filed for.
- *
- * @implements A-SPEC-246
- * A TTL that is not a positive integer is refused — a grant with no meaningful expiry violates the
- * narrowness rule the whole file channel rests on (REQ-245).
- */
 export declare function grantRequest(root: string, id: string, opts: {
     actor: string;
     ttlMinutes?: number;
     rationale?: string;
 }): DecisionResult;
-/** Deny, with a reason the agent will see in its next refusal. */
 export declare function denyRequest(root: string, id: string, reason: string, actor: string): DecisionResult;
 /** Hold with a question — 추후 승인/거부. The agent carries the question to the user. */
 export declare function holdRequest(root: string, id: string, question: string, actor: string): DecisionResult;
@@ -30,17 +22,73 @@ export declare function holdRequest(root: string, id: string, question: string,
  * teaches syntax, humans start typing it.
  */
 export declare function renderPending(state: QueueState): string;
+/**
+ * @implements A-SPEC-262.1
+ * What a decision line must say. Round-1: `✓ 승인 — <expires> 까지 유효` named NOTHING, so an index
+ * that resolved against a shifted queue granted a different request than the operator read, with no
+ * way to see it from the screen. Every decision now echoes the request it acted on.
+ */
+/**
+ * @implements A-SPEC-262.1
+ * The kind cell and the subject, fitted to what is LEFT OF THE ROW after the caller's own prefix.
+ *
+ * Round-8: the budgets were global constants derived once, from `✓ 승인 — ` — and `✓ 거부 기록됨 — `
+ * is seven columns wider, so every denial echo ran to 88 columns and wrapped. Round-7 had widened
+ * the kind cell without re-measuring any line that carries it. A constant cannot know which prefix
+ * it will be printed behind, so the line computes its own room and the prefix is passed in. The
+ * floor keeps a forged kind from eating the subject entirely.
+ */
+export declare function subjectCells(prefix: string, p: PendingRequest): string;
+/**
+ * @implements A-SPEC-262.1
+ * How many columns the SUBJECT gets behind `prefix` — the one place that knows, so a caller asking
+ * "will this fit?" and the caller that renders it cannot disagree.
+ *
+ * Round-9: `[A]`'s filter asked `isClipped(target, ROW_COLS)` with the constant 50 while the batch
+ * row it gates has 69 columns for `kind: 'shell'`. Every target between 51 and 69 columns was
+ * therefore refused as "not fitting a row" and told so on screen, while the list had already printed
+ * it whole — round-8's defect in the other direction, because round-8 fixed the renderer and left
+ * the predicate on the constant.
+ */
+export declare function subjectRoom(prefix: string, p: PendingRequest): number;
+export declare function decisionSubject(p: PendingRequest, prefix?: string): string;
+/**
+ * @implements A-SPEC-262.1
+ * The traceability cell, on a row of its own. Round-5: an 80-column row cannot hold the subject AND
+ * the id AND the expiry — the one-line form measured 81 columns and wrapped, and a wrapped decision
+ * line is how a queue scrolls its own evidence away. Splitting costs a row and keeps both facts
+ * whole; neither may be dropped, since the subject is what the human read and the id is what the
+ * grant is keyed by.
+ */
+export declare function decisionDetail(p: PendingRequest, tail?: string): string;
+/**
+ * The non-TTY fallback's next-command hint. Pure.
+ *
+ * @implements A-SPEC-260
+ * Without a TTY the interactive loop cannot run, and the silent list-then-exit-0 left the operator
+ * with no idea what to type (measured 2026-08-23 — Claude Code's `!` runs with a non-TTY stdin).
+ * The examples carry the FIRST pending id read from the queue, never a placeholder the operator
+ * 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.
+ */
+export declare function renderNonTtyHint(state: QueueState): string;
 export interface ApproveIO {
     print: (s: string) => void;
     /** Ask one question, resolve with the raw answer. Injected so tests script the conversation. */
     ask: (prompt: string) => Promise<string>;
 }
 /**
- * The interactive loop — one entry at a time, one letter per decision.
+ * The interactive loop — one entry at a time, ONE KEY per decision.
  *
  * @implements A-SPEC-246
- * [a] mints the mechanical grant (optional rationale + TTL, enter accepts defaults), [d] requires a
- * reason because an unreasoned denial is invisible to the agent in any useful way, [q] holds with a
- * question the agent will carry to the user, [s] leaves the entry for later.
+ * @implements A-SPEC-262.1
+ * REQ-262 measured what the first cut cost: `[a]` then asked for a rationale and a TTL, so three
+ * approvals were nine inputs and the human left the surface to type elsewhere. Approving is now a
+ * single key with the defaults; the narrowing prompts moved to `[e]`, which is where someone who
+ * actually wants to narrow will look. `[v]` renders the SUBJECT (the spec body, the finding, the
+ * command) and re-asks the same item — looking is not deciding. `[A]` takes every remaining item,
+ * and it is only offered after `renderPending` has already put each item's summary on the screen
+ * (REQ-262 Constraints: nothing is approved unseen). `[d]` still demands a reason, because an
+ * unreasoned denial is invisible to the agent; `[q]` holds with a question; `[s]` leaves it.
  */
 export declare function runInteractive(root: string, io: ApproveIO, actor: string): Promise<void>;