@holmes-lab/holmes-kit 0.1.18 → 0.2.1

package/dist/holmes/cli/approve.js

@@ -37,12 +37,17 @@ exports.grantRequest = grantRequest;
 exports.denyRequest = denyRequest;
 exports.holdRequest = holdRequest;
 exports.renderPending = renderPending;
+exports.subjectCells = subjectCells;
+exports.subjectRoom = subjectRoom;
+exports.decisionSubject = decisionSubject;
+exports.decisionDetail = decisionDetail;
 exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const approval_queue_1 = require("../governance/approval-queue");
+const screen_safe_1 = require("./screen-safe");
 const approval_grants_1 = require("../governance/approval-grants");
 /**
  * `holmes-kit approve` — the surface where a human decides.
@@ -62,18 +67,43 @@ const approval_grants_1 = require("../governance/approval-grants");
  * The moment the human must know scope syntax, this UI has no reason to exist.
  */
 const DEFAULT_TTL_MINUTES = 30;
+// @implements A-SPEC-262.1 — round-5: the guard bounded TTL below only. `--ttl 1e12` threw an
+// uncaught RangeError out of the interactive loop (killing every remaining decision on the surface
+// whose purpose is making decisions cheap), and `--ttl 1e10` minted a grant expiring in the year
+// 21039 — permanent authority from a slipped digit, in the channel REQ-245 built on "a grant is
+// only a grant when it is narrow". A week is already generous for a narrow grant.
+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 };
 };
 /** CLI-side event writer. The CLI runs in the operator's terminal, outside the session gates. */
+/**
+ * A path this process may write: it exists and is a regular file, or it does not exist yet.
+ *
+ * Round-8: round-7 gave the queue's reader and its enqueue this guard and stopped there, so the two
+ * writes a DECISION makes — the audit append and the grant file — could still be aimed at a FIFO.
+ * Measured: a named pipe at the grant temp path left the shipped `approve --grant 1` blocked inside
+ * open(2) with no output at all, and that request could never be decided again. `lstat`, so a
+ * symlink is refused rather than followed somewhere this project does not own.
+ */
+const isWritablePath = (file) => {
+    try {
+        return fs.lstatSync(file).isFile();
+    }
+    catch {
+        return true;
+    } // absent is fine; it gets created
+};
 const appendEvent = (root, event) => {
     try {
         const file = path.join(root, approval_queue_1.QUEUE_RELPATH);
         if (!fs.existsSync(path.join(root, '.ax')))
             return false;
         fs.mkdirSync(path.dirname(file), { recursive: true });
+        if (!isWritablePath(file))
+            return false;
         fs.appendFileSync(file, JSON.stringify({ ...event, ts: new Date().toISOString() }) + '\n');
         return true;
     }
@@ -88,48 +118,115 @@ const appendEvent = (root, event) => {
  * 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).
  */
+/**
+ * @implements A-SPEC-262.1
+ * The id must DERIVE from the record it labels. Round-3: `foldQueue` takes `{id, kind, target}`
+ * verbatim, and nothing checked that `id === approvalRequestId(kind, target)` — so a record could
+ * pair a benign-looking id with a hostile target and the grant took its scope pattern from the
+ * fresh read. No escape byte is needed for that attack; the round-1 echo line even confirms the
+ * substituted subject, because the echo is rendered from the snapshot the human saw. Every
+ * legitimate entry satisfies this (enqueueApprovalRequest computes the id the same way), so a
+ * mismatch is a tampered or corrupt record and is refused rather than acted on.
+ */
+// Folded to rows at the source (round-5): a refusal that wraps is a refusal whose first clause can
+// scroll away, and this one names the reason a decision was withheld.
+const TAMPERED = ['큐 기록이 자기일관되지 않습니다 — id 가 kind·target 에서 나온 값이 아닙니다.',
+    '   위조되었거나 손상된 줄이므로 이 요청은 결정하지 않습니다'].join('\n');
+function recordIsSelfConsistent(entry) {
+    return entry.id === (0, approval_queue_1.approvalRequestId)(entry.kind, entry.target);
+}
 function grantRequest(root, id, opts) {
     const ttl = opts.ttlMinutes ?? DEFAULT_TTL_MINUTES;
-    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl <= 0) {
-        return { ok: false, reason: `TTL 은 1 이상의 정수(분)여야 합니다 — 받은 값: ${String(ttl)}` };
+    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl <= 0 || ttl > MAX_TTL_MINUTES) {
+        return { ok: false, reason: `TTL 은 1..${MAX_TTL_MINUTES} 사이의 정수(분)여야 합니다 — 받은 값: ${(0, screen_safe_1.rowField)(String(ttl), 40)}` };
     }
     const { entry } = findPending(root, id);
     if (!entry)
-        return { ok: false, reason: `대기 중인 요청 ${id} 가 없습니다 — npx holmes-kit approve --list 로 확인하십시오` };
+        return { ok: false, reason: `대기 중인 요청 ${(0, screen_safe_1.rowField)(id, 40)} 가 없습니다 — npx holmes-kit approve --list 로 확인하십시오` };
+    if (!recordIsSelfConsistent(entry))
+        return { ok: false, reason: TAMPERED };
+    // A "does this match what the operator saw" parameter was written here too and then removed: the
+    // derivation check above already covers every substitution. A different (kind,target) yields a
+    // different id, so the lookup misses; the SAME id can only carry the same subject. An unexercised
+    // second guard is not defence in depth, it is a line nobody can prove still works (round-3
+    // mutation test: neutering it left the suite green).
     const expires = new Date(Date.now() + ttl * 60_000).toISOString();
     const grant = {
         actor: opts.actor,
         token: 'grant',
         rationale: opts.rationale?.trim() ? opts.rationale : DEFAULT_RATIONALE,
-        scope: [{ kind: entry.kind, pattern: entry.target }],
+        // exact (round-14): the queue target is a LITERAL command the operator read on the decision
+        // row, not a glob. Without this a `*` in the target became a wildcard, so approving `rm -rf *`
+        // authorized `rm -rf /any/path` — the grant covering commands the operator never saw, breaking
+        // "the grant is for what the human saw" (round-3) in the scope layer.
+        scope: [{ kind: entry.kind, pattern: entry.target, exact: true }],
         expires,
         nonce: id,
     };
+    // @implements A-SPEC-262.1 — AUDIT AND AUTHORITY STAND OR FALL TOGETHER.
+    // Round-3 wrote the grant first and discarded the append's failure: a live nonce with no record.
+    // Round-4 put the audit first and created the mirror: an orphan `granted` event with no grant,
+    // which foldQueue treats as decided — the request vanished from `--list` and the log claimed an
+    // approval that never happened. The temp file makes the ordering honest: everything that can fail
+    // happens BEFORE either half is committed, and the rename is intra-directory.
+    const dir = path.join(root, approval_grants_1.GRANTS_RELDIR);
+    const tmp = path.join(dir, `.${id}.json.tmp`);
     try {
-        const dir = path.join(root, approval_grants_1.GRANTS_RELDIR);
         fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(path.join(dir, `${id}.json`), JSON.stringify(grant, null, 2) + '\n');
+        if (!isWritablePath(tmp) || !isWritablePath(path.join(dir, `${id}.json`))) {
+            return { ok: false, reason: '그랜트 파일 자리가 일반 파일이 아닙니다 — 큐 디렉터리를 확인하십시오' };
+        }
+        fs.writeFileSync(tmp, JSON.stringify(grant, null, 2));
     }
     catch (e) {
-        return { ok: false, reason: `그랜트 파일을 쓸 수 없습니다: ${e instanceof Error ? e.message : String(e)}` };
+        // Round-7: budgeted at 200 columns on a one-row screen — measured 232 columns, three terminal
+        // rows, and three of them in a row scrolled the [A] confirmation off a 24-row terminal. The same
+        // class round-6 closed in findingContext, three files over.
+        return { ok: false, reason: `그랜트 파일을 쓸 수 없습니다:\n   ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
+    }
+    if (!appendEvent(root, { event: 'granted', id, actor: opts.actor, expires })) {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch { /* best effort: the temp name is not a grant */ }
+        return { ok: false, reason: '승인 기록(큐 이벤트)을 쓸 수 없어 그랜트를 발급하지 않았습니다 — .ax/approvals 쓰기 권한을 확인하십시오' };
+    }
+    try {
+        fs.renameSync(tmp, path.join(dir, `${id}.json`));
+    }
+    catch (e) {
+        return { ok: false, reason: `그랜트 파일을 제자리에 놓지 못했습니다 — 큐에는 승인 기록이 남았으니 다시 실행하십시오\n   ${(0, screen_safe_1.rowField)(e instanceof Error ? e.message : String(e), 76)}` };
     }
-    appendEvent(root, { event: 'granted', id, actor: opts.actor });
     return { ok: true, expires };
 }
-/** Deny, with a reason the agent will see in its next refusal. */
 function denyRequest(root, id, reason, actor) {
     const { entry } = findPending(root, id);
     if (!entry)
-        return { ok: false, reason: `대기 중인 요청 ${id} 가 없습니다` };
-    appendEvent(root, { event: 'denied', id, reason, actor });
+        return { ok: false, reason: `대기 중인 요청 ${(0, screen_safe_1.rowField)(id, 40)} 가 없습니다` };
+    // @implements A-SPEC-262.1 — round-4: the derivation gate guarded grant only, so a tampered record
+    // let the operator "deny" one subject while the denial was keyed to another id entirely.
+    if (!recordIsSelfConsistent(entry))
+        return { ok: false, reason: TAMPERED };
+    // 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 })) {
+        return { ok: false, reason: '거부 기록(큐 이벤트)을 쓸 수 없었습니다 — .ax/approvals 쓰기 권한을 확인하십시오. 아무것도 기록되지 않았습니다' };
+    }
     return { ok: true };
 }
 /** Hold with a question — 추후 승인/거부. The agent carries the question to the user. */
 function holdRequest(root, id, question, actor) {
     const { entry } = findPending(root, id);
     if (!entry)
-        return { ok: false, reason: `대기 중인 요청 ${id} 가 없습니다` };
-    appendEvent(root, { event: 'held', id, question, actor });
+        return { ok: false, reason: `대기 중인 요청 ${(0, screen_safe_1.rowField)(id, 40)} 가 없습니다` };
+    // @implements A-SPEC-262.1 — round-4: the derivation gate guarded grant only, so a tampered record
+    // let the operator "deny" one subject while the denial was keyed to another id entirely.
+    if (!recordIsSelfConsistent(entry))
+        return { ok: false, reason: TAMPERED };
+    if (!appendEvent(root, { event: 'held', id, question, actor })) {
+        return { ok: false, reason: '보류 기록(큐 이벤트)을 쓸 수 없었습니다 — .ax/approvals 쓰기 권한을 확인하십시오. 아무것도 기록되지 않았습니다' };
+    }
     return { ok: true };
 }
 /**
@@ -140,21 +237,91 @@ function holdRequest(root, id, question, actor) {
  * teaches syntax, humans start typing it.
  */
 function renderPending(state) {
-    if (state.pending.length === 0)
+    if (state.pending.length === 0) {
+        // Round-7: this early return made the malformed-line row below UNREACHABLE in exactly the case
+        // it exists for — a wholly corrupted queue printed "no requests waiting" and exited 0, which is
+        // what an agent would see after destroying it. approval-queue.ts promises the opposite:
+        // "an empty-looking queue must be distinguishable from a corrupted one".
+        if (state.malformedLines > 0) {
+            return ['승인 대기 중인 요청이 없습니다.',
+                `(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`].join('\n');
+        }
         return '승인 대기 중인 요청이 없습니다.';
+    }
     const lines = [`◆ 승인 대기 ${state.pending.length}건`, ''];
     state.pending.forEach((p, i) => {
-        lines.push(`[${i + 1}] ${p.kind}  ${p.target}`);
-        lines.push(`    이유: ${p.why}`);
-        const since = p.firstTs ? ` · ${p.firstTs} 부터` : '';
-        lines.push(`    차단 ${p.count}회${since}${p.hold ? `   (보류 중 — 질문: ${p.question ?? ''})` : ''}`);
-        lines.push(`    id: ${p.id}`);
+        // @implements A-SPEC-262.1 — every field here is AGENT-CONTROLLED (the target is the command it
+        // was blocked on). Round-1 forged two extra rows and hid the real ones behind an ANSI conceal,
+        // and the operator granted a `curl … | sh` they never saw. The template owns the line structure.
+        lines.push(`[${i + 1}] ${subjectCells(`[${i + 1}]  `, p)}`);
+        lines.push(`    이유: ${(0, screen_safe_1.rowField)(p.why, screen_safe_1.ROW_COLS)}`);
+        // Round-6: this row composed THREE separately-budgeted fields plus twenty columns of template,
+        // and round-5's whole-line accounting only covered the line PREFIXES. Measured at 117 columns
+        // for an ordinary hold — no forgery, no wide characters, just a question of average length. A
+        // hold's question is the actionable part, so it gets a row instead of being squeezed onto one.
+        const since = p.firstTs ? ` · ${(0, screen_safe_1.rowField)(p.firstTs, 28)} 부터` : '';
+        lines.push(`    차단 ${p.count}회${since}${p.hold ? '   (보류 중)' : ''}`);
+        if (p.hold)
+            lines.push(`    질문: ${(0, screen_safe_1.rowField)(p.question ?? '(질문 없음)', screen_safe_1.ROW_COLS)}`);
+        lines.push(`    id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
         lines.push('');
     });
     if (state.malformedLines > 0)
         lines.push(`(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`);
     return lines.join('\n');
 }
+/**
+ * @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.
+ */
+function subjectCells(prefix, p) {
+    return `${(0, screen_safe_1.rowField)(p.kind, screen_safe_1.KIND_COLS)} ${(0, screen_safe_1.rowField)(p.target, subjectRoom(prefix, p))}`;
+}
+/**
+ * @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.
+ */
+function subjectRoom(prefix, p) {
+    // No floor: round-10 measured the unfloored value at a minimum of 49 across 40,000 hostile kinds
+    // and every prefix this screen uses (the widest is ten columns, and the kind cell is capped at
+    // twenty), so `Math.max(16, …)` could never fire. An unexercised guard is not defence in depth —
+    // it is a second thing to keep true (round-5).
+    const kind = (0, screen_safe_1.rowField)(p.kind, screen_safe_1.KIND_COLS);
+    return screen_safe_1.ROW_MAX - (0, screen_safe_1.displayWidth)(prefix) - (0, screen_safe_1.displayWidth)(kind) - 1;
+}
+function decisionSubject(p, prefix = '\u2713 \uc2b9\uc778 \u2014 ') {
+    return subjectCells(prefix, p);
+}
+/**
+ * @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.
+ */
+function decisionDetail(p, tail = '') {
+    return `   ${(0, screen_safe_1.rowField)(p.id, 20)}${tail === '' ? '' : ` \u00b7 ${(0, screen_safe_1.rowField)(tail, 40)}`}`;
+}
 /**
  * The non-TTY fallback's next-command hint. Pure.
  *
@@ -168,55 +335,204 @@ function renderPending(state) {
 function renderNonTtyHint(state) {
     if (state.pending.length === 0)
         return '';
-    const id = state.pending[0].id;
+    // @implements A-SPEC-262.1 — round-2: the id is AGENT-CONTROLLED (foldQueue takes it verbatim and
+    // .ax/approvals has no write gate), and these three lines exist to be COPIED INTO A SHELL. A
+    // crafted id carrying a concealed `curl … | sh` rode into the operator's clipboard invisibly.
+    // Flattened, so what is pasted is what is read. The index is offered first: it needs no id at all.
+    const p = state.pending[0];
+    // Flattened so it cannot forge a line, then SHELL-QUOTED so pasting it cannot run anything: this
+    // block exists to be copied into a shell, and the id is agent-controlled (round-2).
+    // Round-5 weighed the row rule against A-SPEC-260's contract here and the contract wins: these
+    // three lines are PASTED INTO A SHELL, so they must stay one line AND carry the id in full. A
+    // clipped id is not a shorter command, it is a command naming a request that does not exist — or,
+    // worse, a different one.
+    //
+    // Round-9: §13 routed this through `rowField`, which DOUBLES BACKSLASHES — so the pasted command
+    // named an id that does not exist, and the refusal then rendered the doubling twice over. A real
+    // queue id is `req-` plus twelve hex digits (`recordIsSelfConsistent` refuses to decide anything
+    // else), so a well-formed id is printed verbatim and quoted, and anything else is shown in row
+    // form with a note: an id that cannot be decided is not a command worth pasting.
+    // One expression, not two arms: `rowField` is the identity on a well-formed id (twelve hex digits
+    // and a `req-` prefix are all printable ASCII), so a branch that printed it verbatim could not be
+    // distinguished from this by any input — an arm no test can reach is not a guarantee, it is a
+    // second thing to keep true.
+    const wellFormed = /^req-[0-9a-f]{12}$/.test(p.id);
+    const id = `${(0, screen_safe_1.safeRef)((0, screen_safe_1.rowField)(p.id, 40))}${wellFormed ? '' : '   # 위조된 id — 결정 불가'}`;
     return [
-        '대화형 결정은 TTY에서만 동작합니다 — 이 셸에서는 아래 비대화형 명령을 사용하십시오:',
+        '대화형 결정은 TTY에서만 동작합니다.',
+        '이 셸에서는 아래 비대화형 명령을 사용하십시오:',
+        '  holmes-kit approve --grant 1        # 위 목록의 첫 항목 (번호로 참조 가능)',
         `  holmes-kit approve --grant ${id}`,
         `  holmes-kit approve --deny ${id} --reason "<사유>"`,
         `  holmes-kit approve --ask ${id} --question "<질문>"`,
     ].join('\n');
 }
 /**
- * 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.
  */
 async function runInteractive(root, io, actor) {
     const state = (0, approval_queue_1.readQueue)(root);
     io.print(renderPending(state));
     if (state.pending.length === 0)
         return;
-    for (const p of state.pending) {
-        io.print(`\n─ ${p.kind}  ${p.target}`);
-        const answer = (await io.ask('[a]승인  [d]거부  [q]질문 남기고 보류  [s]건너뛰기 > ')).trim().toLowerCase();
+    const grantDefault = (p) => {
+        const r = grantRequest(root, p.id, { actor });
+        if (!r.ok) {
+            io.print(`\u2717 ${r.reason}`);
+            return false;
+        }
+        io.print(`\u2713 \uc2b9\uc778 \u2014 ${decisionSubject(p, '\u2713 \uc2b9\uc778 \u2014 ')}`);
+        io.print(decisionDetail(p, `${r.expires} \uae4c\uc9c0 \uc720\ud6a8`));
+        return true;
+    };
+    const queue = [...state.pending];
+    for (let i = 0; i < queue.length; i++) {
+        const p = queue[i];
+        // @implements A-SPEC-262.1 — round-2: THIS line was the seam round-1 missed. renderPending was
+        // sanitised; the header printed immediately above the prompt was not, so an erase-and-repaint
+        // target wiped the safe list, forged a benign header, and the operator pressed [a] on it.
+        io.print(`\n\u2500 ${subjectCells('\u2500  ', p)}`);
+        // The raw answer is kept: [A] and [a] are different keys, so lowercasing before the branch
+        // would erase the batch decision.
+        const raw = (await io.ask('[a]\uc2b9\uc778  [e]\uc0ac\uc720\u00b7\uae30\uac04  [v]\uc0c1\uc138  [d]\uac70\ubd80  [q]\ubcf4\ub958  [s]\uac74\ub108\ub700  [A]\uc804\uccb4 > ')).trim();
+        if (raw === 'A') {
+            // @implements A-SPEC-262.1 — CONFIRMED, with the count and the list. Round-1: this was the one
+            // decision in the loop with no second prompt, and it differs from [a] only by Shift — a
+            // Caps-Lock slip granted every item the operator had not looked at. The "summaries are already
+            // on screen" justification also fails on a queue longer than a screen, and right after a [v]
+            // scrolled them away, so the confirmation RE-PRINTS them.
+            // ROW BUDGET (round-5). The bound round-4 added was a code-point budget, and a code point is
+            // not a row: `⟪`, `⟫` and every Hangul character in the removal marker are TWO columns, so a
+            // 200-code-point line measured 302 columns — four wrapped rows for ONE item, and a full queue
+            // of them scrolls the earlier summaries away before the y/N prompt, which is exactly the flood
+            // this re-print exists to prevent. Two bounds now, both in the unit the screen uses:
+            //   · each item must fit WHOLE on one row — an item that would be clipped is not batched at
+            //     all, because a clipped subject is a subject the operator did not see; it stays pending
+            //     for an individual decision, where [v] shows it in full.
+            //   · at most BATCH_MAX items per confirmation, so the list itself always fits a screen. The
+            //     rest are not lost: [A] again takes the next batch.
+            const BATCH_MAX = 20;
+            const rest = queue.slice(i);
+            const fits = (q) => !(0, screen_safe_1.isClipped)(q.target, subjectRoom('   - ', q));
+            const showable = rest.filter(fits);
+            const oversize = rest.length - showable.length;
+            const batch = showable.slice(0, BATCH_MAX);
+            const deferred = showable.length - batch.length;
+            if (batch.length === 0) {
+                io.print('\u2717 \ub0a8\uc740 \ud56d\ubaa9\uc740 \ud55c \ud589\uc5d0 \uc548 \ub2f4\uaca8 \uc77c\uad04 \ub300\uc0c1\uc774 \uc544\ub2d9\ub2c8\ub2e4 \u2014 [v]\ub85c \uac1c\ubcc4 \uacb0\uc815');
+                i--;
+                continue;
+            }
+            io.print(`\u25c6 \ub2e4\uc74c ${batch.length}\uac74\uc744 \uc2b9\uc778\ud569\ub2c8\ub2e4:`);
+            for (const q of batch) {
+                io.print(`   - ${subjectCells('   - ', q)}`);
+            }
+            if (oversize > 0) {
+                io.print(`   (\ud55c \ud589\uc5d0 \uc548 \ub2f4\uae30\ub294 ${oversize}\uac74 \uc81c\uc678 \u2014 [v]\ub85c \uac1c\ubcc4 \uacb0\uc815)`);
+            }
+            if (deferred > 0) {
+                io.print(`   (\ub098\uba38\uc9c0 ${deferred}\uac74\uc740 \ub2e4\uc74c [A] \uc5d0\uc11c \uc774\uc5b4\uc11c \ubb3b\uc2b5\ub2c8\ub2e4)`);
+            }
+            const ok = (await io.ask(`\uc774 ${batch.length}\uac74\uc744 \uc2b9\uc778\ud569\ub2c8\uae4c? [y/N] > `)).trim().toLowerCase();
+            if (ok !== 'y' && ok !== 'yes') {
+                io.print('\u2717 \uc77c\uad04 \uc2b9\uc778\uc744 \ucde8\uc18c\ud588\uc2b5\ub2c8\ub2e4 \u2014 \ud56d\ubaa9\ubcc4\ub85c \uacc4\uc18d\ud558\uc2ed\uc2dc\uc624');
+                i--;
+                continue;
+            }
+            // @implements A-SPEC-262.1 — round-7: `granted` was built from `batch` BEFORE any grant ran,
+            // so an item whose grant FAILED (a read-only grants dir, or the round-4 tamper refusal) was
+            // spliced out of the queue and never asked again — the session ended, exit 0, nothing granted
+            // and nothing pending re-shown. That is the doctrine round-6 wrote three lines below, broken
+            // in the branch round-6 rewrote. Only what actually succeeded leaves the queue.
+            const granted = new Set();
+            for (const q of batch) {
+                io.print(`\n\u2500 ${subjectCells('\u2500  ', q)}`);
+                if (grantDefault(q))
+                    granted.add(q.id);
+            }
+            // Not `return`: the excluded and deferred items are still undecided, and dropping the operator
+            // out of the loop would silently leave them for a future session.
+            const remaining = rest.filter((q) => !granted.has(q.id));
+            queue.splice(i, rest.length, ...remaining);
+            i--;
+            continue;
+        }
+        const answer = raw.toLowerCase();
         if (answer === 'a') {
-            const rationale = (await io.ask(`사유 (enter = "${DEFAULT_RATIONALE}") > `)).trim();
-            const ttlRaw = (await io.ask(`유효 시간(분, enter = ${DEFAULT_TTL_MINUTES}) > `)).trim();
+            grantDefault(p);
+        }
+        else if (answer === 'e') {
+            const rationale = (await io.ask(`\uc0ac\uc720 (enter = "${DEFAULT_RATIONALE}") > `)).trim();
+            const ttlRaw = (await io.ask(`\uc720\ud6a8 \uc2dc\uac04(\ubd84, enter = ${DEFAULT_TTL_MINUTES}) > `)).trim();
             const ttl = ttlRaw === '' ? DEFAULT_TTL_MINUTES : Number(ttlRaw);
             const r = grantRequest(root, p.id, { actor, rationale, ttlMinutes: ttl });
-            io.print(r.ok ? `✓ 승인 — ${r.expires} 까지 유효` : `✗ ${r.reason}`);
+            // @implements A-SPEC-262.1 — round-6: this branch alone RETURNED on failure, so a mistyped TTL
+            // ("30분") ended the whole session with exit 0 and every remaining item undecided — measured on
+            // a real pty, and the operator cannot tell it from a normal end of queue. The same `return`
+            // fired on the round-4 tamper refusal, which means a single forged queue line placed first
+            // could abandon the session when the operator pressed the MOST careful key. A refused decision
+            // is one item's problem; it re-asks, exactly like an unknown key.
+            if (!r.ok) {
+                io.print(`\u2717 ${r.reason}`);
+                i--;
+                continue;
+            }
+            io.print(`\u2713 \uc2b9\uc778 \u2014 ${decisionSubject(p, '\u2713 \uc2b9\uc778 \u2014 ')}`);
+            io.print(decisionDetail(p, `${r.expires} \uae4c\uc9c0 \uc720\ud6a8`));
+        }
+        else if (answer === 'v') {
+            const { renderDecisionContext } = require('./approve-context');
+            io.print(renderDecisionContext(root, p));
+            i--; // same item, asked again: seeing is not deciding
+            continue;
         }
         else if (answer === 'd') {
-            const reason = (await io.ask('거부 사유(에이전트에게 전달됩니다) > ')).trim();
+            const reason = (await io.ask('\uac70\ubd80 \uc0ac\uc720(\uc5d0\uc774\uc804\ud2b8\uc5d0\uac8c \uc804\ub2ec\ub429\ub2c8\ub2e4) > ')).trim();
             if (reason === '') {
-                io.print('✗ 사유 없는 거부는 에이전트가 볼 수 없습니다 — 건너뜁니다');
+                io.print('\u2717 \uc0ac\uc720 \uc5c6\ub294 \uac70\ubd80\ub294 \uc5d0\uc774\uc804\ud2b8\uac00 \ubcfc \uc218 \uc5c6\uc2b5\ub2c8\ub2e4 \u2014 \uac74\ub108\ub701\ub2c8\ub2e4');
                 continue;
             }
             const r = denyRequest(root, p.id, reason, actor);
-            io.print(r.ok ? '✓ 거부 기록됨' : `✗ ${r.reason}`);
+            if (r.ok) {
+                io.print(`\u2713 \uac70\ubd80 \u2014 ${decisionSubject(p, '\u2713 \uac70\ubd80 \u2014 ')}`);
+                io.print(decisionDetail(p, '\uac70\ubd80\uac00 \uae30\ub85d\ub410\uc2b5\ub2c8\ub2e4'));
+            }
+            else
+                io.print(`\u2717 ${r.reason}`);
         }
         else if (answer === 'q') {
-            const question = (await io.ask('질문(에이전트가 사용자에게 전달합니다) > ')).trim();
+            const question = (await io.ask('\uc9c8\ubb38(\uc5d0\uc774\uc804\ud2b8\uac00 \uc0ac\uc6a9\uc790\uc5d0\uac8c \uc804\ub2ec\ud569\ub2c8\ub2e4) > ')).trim();
             if (question === '') {
-                io.print('✗ 빈 질문 — 건너뜁니다');
+                io.print('\u2717 \ube48 \uc9c8\ubb38 \u2014 \uac74\ub108\ub701\ub2c8\ub2e4');
                 continue;
             }
             const r = holdRequest(root, p.id, question, actor);
-            io.print(r.ok ? '✓ 보류 — 질문이 다음 거부 문면에 실립니다' : `✗ ${r.reason}`);
+            if (r.ok) {
+                io.print(`\u2713 \ubcf4\ub958 \u2014 ${decisionSubject(p, '\u2713 \ubcf4\ub958 \u2014 ')}`);
+                io.print(decisionDetail(p, '\uc9c8\ubb38\uc740 \ub2e4\uc74c \uac70\ubd80 \ubb38\uba74\uc5d0'));
+            }
+            else
+                io.print(`\u2717 ${r.reason}`);
+        }
+        else if (answer !== 's') {
+            // @implements A-SPEC-262.1 — a typo is NOT a decision. Round-1: any unrecognized input (the
+            // double-tap `aa` of the new one-key flow, a bare Enter) silently advanced, so the operator
+            // saw the next item's prompt and read it as "approved, next please" while the item stayed
+            // pending and the agent stayed blocked. Only [s] skips; everything else asks again.
+            io.print(`\u2717 \uc54c \uc218 \uc5c6\ub294 \ud0a4\uc785\ub2c8\ub2e4${raw === '' ? '' : `: '${(0, screen_safe_1.rowField)(raw, 20)}'`} \u2014 \ub2e4\uc2dc \uc785\ub825\ud558\uc2ed\uc2dc\uc624`);
+            i--;
+            continue;
         }
-        // 's' and anything else: leave it for later.
     }
 }

package/dist/holmes/cli/codex-toml.d.ts

@@ -0,0 +1,26 @@
+import { McpServerEntry } from './mcp-launcher';
+/** The one table holmes-kit owns in a Codex config.toml. */
+export declare const CODEX_TABLE = "mcp_servers.holmes-kit";
+/**
+ * Serialize the `[mcp_servers.holmes-kit]` table. `env` is an inline table so the whole entry is ONE
+ * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
+ * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
+ */
+export declare function codexMcpBlock(entry: McpServerEntry, specsDir: string): string;
+/**
+ * Merge `block` (a full `codexMcpBlock` output) into `existing`. When `existing` is null/empty the
+ * block stands alone. When our table is already present its region is REPLACED (no duplicate); when
+ * absent the block is appended after a blank-line separator. Every other line is preserved verbatim.
+ */
+export declare function mergeCodexToml(existing: string | null, block: string): string;
+/** Strip our region from `existing`, preserving everything else. Absent → returned unchanged. */
+export declare function removeCodexToml(existing: string): string;
+/**
+ * Read `{command,args}` from our table in a config.toml — for doctor's drift check. Parses only the
+ * shape `codexMcpBlock` writes; anything it cannot read returns null (doctor then WARNs rather than
+ * translating an unreadable wiring into a pass).
+ */
+export declare function readCodexHolmesEntry(raw: string): {
+    command: string;
+    args: string[];
+} | null;