@holmes-lab/holmes-kit 0.1.18 → 0.2.1

package/dist/holmes/cli/index.js

@@ -33,8 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBrokenPipe = void 0;
 exports.packageRoot = packageRoot;
 exports.main = main;
+exports.installPipeGuard = installPipeGuard;
 // @implements A-SPEC-100.2
 // @implements A-SPEC-213
 // @implements A-SPEC-215
@@ -74,7 +76,8 @@ 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'],
+    approve: ['help', 'target', 'list', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
+    ledger: ['help', 'target', 'ref', 'dry-run'],
 };
 // @implements A-SPEC-171 — subcommands that render their OWN usage on `--help`. A-SPEC-171 governs
 // "help before any side effect"; a command whose usage lives past this handler (approve, whose
@@ -84,9 +87,11 @@ const KNOWN_FLAGS = {
 const SELF_HELP_COMMANDS = new Set(['approve']);
 const APPROVE_USAGE = `holmes-kit approve — 승인 대기 요청의 결재 (HITL)
 
-  대화형(TTY):        항목마다 [a]승인 [d]거부 [q]질문 [s]건너뛰기
+  대화형(TTY):        항목마다 [a]승인 [e]사유·기간 지정 승인 [v]상세 [d]거부 [q]질문 [s]건너뛰기 [A]남은 전체 승인
+  --watch             상주 모드 — 요청이 도착하는 즉시 결정, 큐가 비면 대기 (Ctrl-C 로 종료, --poll-ms <밀리초>)
   --list              대기 목록만 출력
-  --grant <id>        해당 요청의 좁은 그랜트 발급 (--ttl <분>, --rationale <문구>)
+  --grant <참조>      해당 요청의 좁은 그랜트 발급 (--ttl <분>, --rationale <문구>)
+                      참조 = 목록 번호(1,2,…) | id | id 접두 — 긴 id를 옮겨 적을 필요가 없습니다
   --deny <id> --reason <문구>     거부 — 사유가 에이전트의 다음 거부 문면에 실립니다
   --ask <id> --question <문구>    질문 남기고 보류 — 에이전트가 사용자에게 전달합니다
   --target <dir>      프로젝트 루트 (기본: 현재 디렉터리)
@@ -99,7 +104,7 @@ class UnknownFlagError extends Error {
  * what you'd do" spelling performed a REAL write (round-3 HIGH; same class inverted --remove and
  * --force). A boolean flag must never consume a token.
  */
-const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list']);
+const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'watch']);
 function parseFlags(argv, known) {
     const flags = {};
     const positionals = [];
@@ -180,12 +185,19 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
     --remove                   remove holmes-kit wiring (holmes-owned entries only)
     --force                    re-wire an already-wired target (requires HOLMES_APPROVAL)
 
+  holmes-kit ledger rechain    re-chain forked ledger files against the committed mainline
+    --target <dir>             project to repair (default: cwd)
+    --ref <git-ref>            mainline ref (default: HEAD; walks first-parent to the first
+                               verifying committed version)
+    --dry-run                  report what would be re-chained, write nothing
+
   holmes-kit approve           review pending approval requests (HITL)
-    (no flags, TTY)            interactive: [a]승인 [d]거부 [q]질문 [s]건너뛰기 per request
+    (no flags, TTY)            interactive: [a]승인 [e]지정승인 [v]상세 [d]거부 [q]질문 [s]건너뛰기 [A]전체승인
     --list                     print the pending queue and exit
-    --grant <id> [--ttl <min>] [--rationale <text>]   mint the narrow grant for one request
-    --deny <id> --reason <text>                       record a denial the agent will see
-    --ask <id> --question <text>                      hold with a question the agent relays
+    --grant <ref> [--ttl <min>] [--rationale <text>]  mint the narrow grant for one request
+    --deny <ref> --reason <text>                      record a denial the agent will see
+    --ask <ref> --question <text>                     hold with a question the agent relays
+    <ref>                      list index (1,2,…), full id, or a unique id prefix
     --target <dir>             project root (default: cwd)
 
   holmes-kit doctor [flags]    diagnose the install
@@ -201,6 +213,7 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
   holmes-kit --version | --help
 `;
 async function main(argv) {
+    installPipeGuard(); // @implements A-SPEC-262.1 — cover the shipped bin, not just direct entry (round-11)
     const cmd = argv[0];
     // @implements A-SPEC-190 (round 7) — `holmes-kit constructor` resolved through the prototype
     // chain to a truthy non-array and crashed with an unhandled TypeError instead of saying
@@ -233,7 +246,7 @@ async function main(argv) {
         }
         // Positionals these commands do not take are refused, not dropped: `skills refresh <dir>`
         // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
-        const expected = cmd === 'skills' ? ['refresh'] : [];
+        const expected = cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain'] : [];
         const unexpected = positionals.filter((p) => !expected.includes(p));
         if (unexpected.length > 0) {
             const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
@@ -354,13 +367,358 @@ async function main(argv) {
         }
         return res.ok ? 0 : 1;
     }
+    // @implements A-SPEC-256.1 — re-chain forked ledgers against an EXPLICIT mainline (a named git
+    // ref, default HEAD). Greedy mainline selection is the measured trap this command refuses to be.
+    if (cmd === 'ledger') {
+        if (positionals[0] !== 'rechain') {
+            process.stderr.write(`unknown ledger subcommand\n\n${USAGE}`);
+            return 2;
+        }
+        const { rechainLedger, acceptsAsMainline } = require('../governance/ledger-rechain');
+        const { verifyChain, ProvenanceChain, hasKeyedLookingEvents, keylessSelfConsistent, keyedSelfConsistent, parseLedgerLines, chainNext } = require('../governance/provenance-chain');
+        const { withLedgerLock, LedgerLockError } = require('../governance/ledger-lock');
+        const { isLedgerFilename } = require('../governance/provenance-ledger');
+        const { assertSafeRev } = require('../rtm/git-changes');
+        const { cleanSubprocessEnv } = require('../project/root');
+        const { execFileSync } = require('node:child_process');
+        const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
+        // A valueless `--ref` (parsed as boolean true) is already refused by the generic value-flag
+        // guard earlier in main() with '--ref requires a value' (round-8: the branch here was dead).
+        const ref = typeof flags.ref === 'string' ? flags.ref : 'HEAD';
+        const dry = flags['dry-run'] === true;
+        const key = process.env.HOLMES_LEDGER_KEY || undefined;
+        // Every git subprocess here runs with the scrubbed env (round-1 adversarial finding): this
+        // block reads HOLMES_LEDGER_KEY, and a git that inherits it hands the live signing key to
+        // hooks/credential helpers — the exact channel cleanSubprocessEnv exists to close.
+        const gitEnv = cleanSubprocessEnv();
+        // Name a wrong --target as a wrong PATH, not as 'not a git repo' (round-12: the git error was
+        // misdiagnosed) — the same class doctor's --target guard fixes.
+        if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+            process.stderr.write(`--target ${root} 는 존재하는 디렉터리가 아닙니다.\n`);
+            return 2;
+        }
+        try {
+            execFileSync('git', ['-C', root, 'rev-parse', '--git-dir'], { stdio: 'pipe', env: gitEnv });
+        }
+        catch {
+            process.stderr.write('git 저장소가 아닙니다 — 정본(ref) 없이는 재연쇄하지 않습니다: 재연쇄는 전량 재서명이며, 무엇이 정본인지는 커밋된 이력만이 말할 수 있습니다.\n');
+            return 1;
+        }
+        // The ref is validated BEFORE the walk (round-2 finding: a typo'd --ref silently degraded the
+        // explicit repair request into a "no change" success). Same guard every user-supplied-rev git
+        // call site uses.
+        try {
+            assertSafeRev(ref);
+            execFileSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { stdio: 'pipe', env: gitEnv });
+        }
+        catch {
+            process.stderr.write(`--ref ${ref} 를 커밋으로 해석할 수 없습니다 — 정본을 지정하지 못한 채로는 재연쇄하지 않습니다.\n`);
+            return 1;
+        }
+        const ledgerDir = path.join(root, '.ax', 'ledger');
+        const files = fs.existsSync(ledgerDir)
+            // The CANONICAL live-ledger set is defined ONCE, in provenance-ledger.ts (round-16): the legacy
+            // `provenance.jsonl` or a `provenance.<id>.jsonl` replica with no dots in <id>. An inline copy
+            // drifted in round-15 (a loose `.*` swept in backups like `provenance.bak.jsonl`); the store's
+            // own matcher makes that drift impossible.
+            ? fs.readdirSync(ledgerDir).filter(isLedgerFilename)
+            : [];
+        if (files.length === 0) {
+            process.stdout.write('원장 파일이 없습니다 — 재연쇄할 것이 없습니다.\n');
+            return 0;
+        }
+        // STRICT parse (round-9): a torn TAIL is tolerated, but mid-file corruption or a non-object line
+        // throws — the repair tool must not drop a line and then 'fix' the seq gap, making the loss
+        // permanent and invisible to verify().
+        const parse = (raw, file) => parseLedgerLines(raw, file, { throwOnCorruption: true });
+        // The first-parent commit list is the SAME for every file (one ref), so resolve it ONCE outside
+        // the loop (round-9: it was re-run per file).
+        const WALK_LIMIT = 64;
+        let walkCommits = [];
+        try {
+            walkCommits = execFileSync('git', ['-C', root, 'rev-list', '--first-parent', '-n', String(WALK_LIMIT), ref], { encoding: 'utf8', env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] })
+                .split('\n').map((l) => l.trim()).filter(Boolean);
+        }
+        catch (e) {
+            // A rev-list failure (the ref was already rev-parse-verified) is a real git error, not an
+            // empty history — surface it rather than degrading every file to a false 'no mainline'
+            // (round-12).
+            process.stderr.write(`git rev-list 실패 — 이력을 열거할 수 없습니다: ${e.message.split('\n')[0]}\n`);
+            return 1;
+        }
+        // Resolve the SYMBOLIC ref once (round-13): 'HEAD' is ephemeral, so the audit event records the
+        // branch name too, making the trail self-describing later. Falls back to the raw ref.
+        let refLabel = ref;
+        try {
+            refLabel = execFileSync('git', ['-C', root, 'rev-parse', '--abbrev-ref', ref], { encoding: 'utf8', env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] }).trim() || ref;
+        }
+        catch { /* keep raw ref */ }
+        const planRechain = (mainline, input, mainlineAt) => {
+            const r = rechainLedger(mainline, input, key);
+            if ('refused' in r)
+                return { refused: r.refused };
+            if (r.alreadyVerified)
+                return { audited: r.events, orphanCount: 0, alreadyVerified: true, mainlineLen: mainline.length, mainlineAt };
+            const audited = [...r.events];
+            audited.push(chainNext(audited, {
+                ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'ledger-rechained',
+                summary: `rechained against ${refLabel}@${mainlineAt.slice(0, 8)} — 본선 ${mainline.length} + 고아 ${r.orphanCount}`,
+                inputs: [refLabel, mainlineAt, String(r.orphanCount)], rationale: 'ledger rechain repair', authorization: '',
+            }, key));
+            // Verify the AUDITED chain (round-8: never claim "검증 통과" without verifying; round-16: verify
+            // the chain we will actually write, WITH its keyed audit tail, not the pre-audit prefix).
+            const v = verifyChain(audited, key);
+            if (!v.ok)
+                return { refused: `재연쇄 산출이 검증되지 않습니다(brokenAt=${v.brokenAt ?? '?'}: ${v.detail ?? ''}) — 정본(--ref)이나 키 설정을 확인하십시오.` };
+            return { audited, orphanCount: r.orphanCount, alreadyVerified: false, mainlineLen: mainline.length, mainlineAt };
+        };
+        // "Is this committed version VALIDLY KEYED under the current key?" — the load-bearing distinction
+        // of the two-phase walk: a keyed mainline is terminal, and a keyed ancestor is the only rollback
+        // evidence (round-18). Named once so the `key !== undefined` narrowing is not copy-pasted.
+        const isValidlyKeyed = (c) => c.some((e) => key !== undefined && keyedSelfConsistent(e, key));
+        let failed = 0;
+        for (const name of files) {
+            const abs = path.join(ledgerDir, name);
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            let working;
+            try {
+                working = parse(fs.readFileSync(abs, 'utf8'), name);
+            }
+            catch (e) {
+                process.stdout.write(`✗ ${name}: ${e.message} — 손상 줄을 조사·복구한 뒤 다시 실행하십시오.\n`);
+                failed++;
+                continue;
+            }
+            // Refuse to re-sign what this entry point cannot verify (a keyless run rewriting an intact
+            // keyed ledger as keyless is the exact attack signature the HMAC detector exists for,
+            // manufactured by the repair tool).
+            if (!key && hasKeyedLookingEvents(working)) {
+                process.stdout.write(`✗ ${name}: 자기일관 아닌 줄이 있습니다 — keyed(HMAC) 이거나 content-tampered 이며 키 없이는 구별할 수 없습니다. keyed 라면 HOLMES_LEDGER_KEY 를 설정하고, 변조라면 조사하십시오. rechain 은 포크만 복구하며 이 줄을 재서명하지 않습니다.\n`);
+                failed++;
+                continue;
+            }
+            // Mainline = the FIRST VERIFYING committed version, walking first-parent from the ref. A
+            // union-merge commit's own HEAD carries the seam, so "the ref, verbatim" strands the operator
+            // right after the scenario this command exists for. The walk selects the last healthy
+            // COMMITTED state; every line outside it is preserved as an orphan.
+            let mainline = null;
+            let mainlineAt = '';
+            let presentAnywhere = false;
+            let presentButCorrupt = false; // a committed version existed but strict-parse rejected it
+            let keyedBlocked = false; // a keyed-looking committed version the current mode can't verify
+            let sawKeyedCommitted = false; // any committed version in the walk carried keyed-looking events
+            for (const at of walkCommits) {
+                let cand;
+                // `:./` pins the pathspec to -C's cwd: a bare `<ref>:<rel>` is repo-TOPLEVEL-relative, so a
+                // governed subdirectory of a monorepo would adopt the PARENT repo's same-named ledger. A
+                // show failure means "absent at THIS commit" and the walk CONTINUES; stderr is piped. A
+                // committed candidate that is CORRUPT (strict-parse throws) is skipped like an absent one.
+                let raw;
+                try {
+                    raw = execFileSync('git', ['-C', root, 'show', `${at}:./${rel}`], { encoding: 'utf8', maxBuffer: 1 << 28, env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] });
+                }
+                catch {
+                    continue;
+                } // absent at THIS commit — walk continues
+                presentAnywhere = true;
+                // Present but CORRUPT is distinct from absent (round-14): remember it so the final message
+                // names corruption, not 'absent from history'.
+                try {
+                    cand = parse(raw, `${at}:${rel}`);
+                }
+                catch {
+                    presentButCorrupt = true;
+                    continue;
+                }
+                // Two DISTINCT phases (round-18): MAINLINE SELECTION while `mainline === null`, then, only
+                // for a keyless mainline chosen under a set key, a ROLLBACK SCAN of older commits. Keeping
+                // them separate stops an older corrupt ancestor — reachable only because the scan walks past
+                // the chosen mainline — from hijacking selection-phase logic (keyedBlocked) or being counted
+                // as a keyed ancestor.
+                if (mainline === null) {
+                    // Stop only at an UNACCOUNTABLE candidate — one carrying a line this mode can explain
+                    // neither as keyless-self-consistent NOR (key present) as validly keyed under the current
+                    // key. That is wrong-key / tamper (round-12), and for a keyless run any keyed-looking line
+                    // (round-5 V2). A union-merge SEAM of a keyed ledger is NOT unaccountable: its lines ARE
+                    // keyed-self-consistent (signed correctly, only linkage broken), so the walk continues past
+                    // it to the healthy keyed ancestor and rechain repairs the seam (round-14 regression).
+                    const unaccountable = cand.some((e) => !keylessSelfConsistent(e) && !(key !== undefined && keyedSelfConsistent(e, key)));
+                    if (unaccountable) {
+                        keyedBlocked = true;
+                        break;
+                    }
+                    // An empty committed ledger is trivially "valid" but adopting it re-chains the whole working
+                    // file from genesis, discarding its relation to real history — walk past it (round-14).
+                    if (cand.length === 0)
+                        continue;
+                    if (!acceptsAsMainline(cand, key))
+                        continue;
+                    mainline = cand;
+                    mainlineAt = at;
+                    // A KEYED mainline (or a keyless run) is terminal — the walk goes newest→oldest, so nothing
+                    // older can override the newest verifying state. Only a KEYLESS mainline under a SET key
+                    // enters the rollback scan: KEY ADOPTION IS MONOTONIC (round-17), so it must confirm no
+                    // OLDER committed version was validly keyed under this key (which would make this keyless
+                    // mainline a rollback). Legit first-adoption has no such ancestor and the mainline stands.
+                    if (!key || isValidlyKeyed(cand))
+                        break;
+                }
+                else {
+                    // ROLLBACK SCAN: only a version VALIDLY KEYED UNDER THE CURRENT KEY is rollback evidence
+                    // (round-18). A merely keyed-LOOKING older commit — content-tampered, garbage-hash, or
+                    // signed under a foreign key — is NOT: counting it would misdiagnose corruption as a
+                    // key-rollback and block a healthy first-key adoption over an unrelated older corrupt commit.
+                    if (isValidlyKeyed(cand)) {
+                        sawKeyedCommitted = true;
+                        break;
+                    }
+                }
+            }
+            // A keyless mainline was selected under a set key atop a genuinely-keyed ancestor: a keyless-
+            // rollback of a formerly-keyed ledger (round-17). Refuse — do not launder. (Legit first-adoption
+            // never reaches here: sawKeyedCommitted stays false. A keyed union-merge seam repair selects a
+            // KEYED mainline, so it never enters the rollback scan.) Note: a full first-parent history
+            // rewrite that erases every keyed commit within WALK_LIMIT (rebase/squash) defeats this
+            // git-anchored check — the fundamental limitation named in provenance-chain.ts and spec §22.
+            if (mainline !== null && key && sawKeyedCommitted) {
+                process.stdout.write(`✗ ${name}: 커밋 이력이 keyed(HMAC)였는데 현재 본선 후보가 keyless입니다 — 키 채택은 되돌릴 수 없습니다(keyless-rollback). 이 재기록은 keyed 이력을 폐기하고 keyless 내용을 키로 재서명해 위조를 세탁합니다. verify 가 이미 이를 변조로 표시합니다. 건강한 keyed 정본을 --ref 로 지정하거나 변조를 조사하십시오.\n`);
+                failed++;
+                continue;
+            }
+            if (keyedBlocked) {
+                process.stdout.write(key
+                    ? `✗ ${name}: 커밋 이력의 본선이 현재 HOLMES_LEDGER_KEY 로 검증되지 않습니다 — 키가 틀렸거나 이력이 변조됐습니다. 지나쳐 재연쇄하면 keyed 이력이 틀린 키로 재서명됩니다. 올바른 키를 확인하십시오.\n`
+                    : `✗ ${name}: 커밋 이력의 본선에 자기일관 아닌 줄이 있습니다 — keyed(HMAC) 이거나 content-tampered 입니다. keyed 라면 HOLMES_LEDGER_KEY 를 설정하고, 변조라면 조사하십시오. 지나쳐 재연쇄하지 않습니다.\n`);
+                failed++;
+                continue;
+            }
+            if (mainline === null) {
+                // With no verifying committed mainline nothing can arbitrate. A verifying working file
+                // needs no arbitration; a broken one is refused, not guessed at.
+                if (verifyChain(working, key).ok) {
+                    process.stdout.write(`· ${name}: 커밋 이력에 검증본 없음, 작업본 검증됨 — 무변경\n`);
+                    continue;
+                }
+                process.stdout.write(presentButCorrupt
+                    ? `✗ ${name}: 커밋 이력의 원장본이 손상되어 있고 작업본도 검증 실패 — 손상 커밋본을 복구하거나 건강한 정본을 --ref 로 지정하십시오\n`
+                    : presentAnywhere
+                        ? `✗ ${name}: first-parent ${WALK_LIMIT}커밋 안에 검증되는 커밋본이 없고 작업본도 검증 실패 — 정본을 --ref 로 지정하십시오\n`
+                        : `✗ ${name}: ${ref} 이력에 없고 작업본도 검증 실패 — 정본을 --ref 로 지정하십시오\n`);
+                failed++;
+                continue;
+            }
+            // Read-rechain-write runs under the ledger lock: an unlocked wholesale rewrite would erase any
+            // append landing between the snapshot and the write. The working file is RE-READ inside the
+            // hold; the git walk stayed outside (it never touches the file).
+            const fixedMainline = mainline;
+            // --dry-run is READ-ONLY (round-10): it takes NO write lock (the lock's stale-break recorder
+            // would append a lock-broken event, and lock contention would fail the CI gate on drift it
+            // never checked) and opens nothing for write — it judges the snapshot `working` and returns an
+            // exit code only. The write path (lock, audit event, atomic rewrite) is for the real run only.
+            if (dry) {
+                const rd = planRechain(fixedMainline, working, mainlineAt);
+                if ('refused' in rd) {
+                    process.stdout.write(`✗ ${name}: ${rd.refused}\n`);
+                    failed++;
+                    continue;
+                }
+                if (rd.alreadyVerified) {
+                    process.stdout.write(`· ${name}: 이미 검증됨 — 무변경\n`);
+                    continue;
+                }
+                process.stdout.write(`○ ${name}: 재연쇄 대상 — 고아 ${rd.orphanCount}건 (dry-run, 미기록)\n`);
+                failed++;
+                continue; // drift detected → CI gate fails
+            }
+            let verdict;
+            try {
+                verdict = withLedgerLock(abs, () => {
+                    // Corruption appearing between the outer read and the lock throws here; catch it as a
+                    // per-file ✗ (round-14: an uncaught strict-parse throw crashed the whole multi-file run).
+                    let fresh;
+                    try {
+                        fresh = parse(fs.readFileSync(abs, 'utf8'), name);
+                    } // read inside the lock (round-8)
+                    catch (e) {
+                        return { line: `✗ ${name}: ${e.message} — 손상 줄을 조사·복구한 뒤 다시 실행하십시오.`, fail: true };
+                    }
+                    // Re-checked INSIDE the hold (TOCTOU): a non-self-consistent line appearing between the
+                    // snapshot and the lock is either keyed or content-tampered — honest either way (round-8).
+                    if (!key && hasKeyedLookingEvents(fresh)) {
+                        return { line: `✗ ${name}: 락 획득 사이에 자기일관 아닌 줄이 추가되었습니다 — keyed(HOLMES_LEDGER_KEY 설정) 이거나 변조입니다. 재서명하지 않습니다.`, fail: true };
+                    }
+                    // ONE judgment (round-16): rechain, chain the KEYED audit event onto the tail (the ledger's
+                    // own doctrine — the audit trail must not silently change; the `ledger-rechained` event
+                    // attributes the regeneration to this tool, the mainline ref/sha, and the orphan count, is
+                    // keyed iff a key is present, and is idempotent), then verify the WHOLE audited chain. The
+                    // SAME function the dry-run advisory used, so the two can never disagree.
+                    const plan = planRechain(fixedMainline, fresh, mainlineAt);
+                    if ('refused' in plan)
+                        return { line: `✗ ${name}: ${plan.refused}`, fail: true };
+                    if (plan.alreadyVerified)
+                        return { line: `· ${name}: 이미 검증됨 — 무변경` };
+                    const audited = plan.audited;
+                    // ATOMIC rewrite: a crash mid-write must leave the old file, never a verifying prefix that
+                    // the rerun's no-change guard silently accepts.
+                    const serialized = audited.map((e) => JSON.stringify(e)).join('\n') + '\n';
+                    const tmp = abs + '.rechain-tmp';
+                    fs.writeFileSync(tmp, serialized);
+                    fs.renameSync(tmp, abs);
+                    // Confirm the ON-DISK result matches what we verified (round-15): the success line must
+                    // reflect the file, not just the in-memory array — a torn/short write is reported, not
+                    // silently blessed as '검증 통과'.
+                    if (fs.readFileSync(abs, 'utf8') !== serialized) {
+                        return { line: `✗ ${name}: 재기록된 파일이 검증한 내용과 다릅니다(디스크 이상?) — 다시 실행하십시오.`, fail: true };
+                    }
+                    return { line: `✓ ${name}: 재연쇄 완료 — 본선 ${fixedMainline.length}(${mainlineAt.slice(0, 8)}) + 고아 ${plan.orphanCount}, 감사 기록 남김, 체인 검증 통과` };
+                }, { onStaleBreak: new ProvenanceChain(abs).staleBreakRecorder() });
+            }
+            catch (e) {
+                // Lock contention is a per-file refusal, not a crash.
+                if (e instanceof LedgerLockError) {
+                    process.stdout.write(`✗ ${name}: 원장 락을 얻지 못했습니다(다른 기록자 사용 중) — 잠시 후 다시 실행하십시오.\n`);
+                    failed++;
+                    continue;
+                }
+                // Any OTHER fault — a raw I/O error on the atomic write (ENOSPC/EACCES/EIO), etc. — is a
+                // per-file ✗, NOT an abort of the whole run: one replica's disk failure must not abandon its
+                // siblings, consistent with every other per-file fault (corruption, lock, refusal). The
+                // message is printed (never swallowed) so the failure stays visible and the exit is nonzero.
+                // The atomic tmp is left only on a mid-write crash and is ignored by isLedgerFilename; still,
+                // best-effort remove it so a retry starts clean.
+                try {
+                    fs.rmSync(abs + '.rechain-tmp', { force: true });
+                }
+                catch { /* best-effort */ }
+                process.stdout.write(`✗ ${name}: 재기록 중 오류 — ${e.message.split('\n')[0]}. 이 파일은 건너뜁니다(다른 파일은 계속). 원인을 조사한 뒤 다시 실행하십시오.\n`);
+                failed++;
+                continue;
+            }
+            process.stdout.write(verdict.line + '\n');
+            if (verdict.fail)
+                failed++;
+        }
+        return failed === 0 ? 0 : 1;
+    }
     // @implements A-SPEC-215
     if (cmd === 'approve') {
         // @implements A-SPEC-246 — the surface where a human decides. Interactive on a TTY with no
         // decision flags; every interactive decision has a flag equivalent so a CI or remote operator
         // is never locked out.
-        const { grantRequest, denyRequest, holdRequest, renderPending, renderNonTtyHint, runInteractive } = require('./approve');
+        const { grantRequest, denyRequest, holdRequest, renderPending, renderNonTtyHint, runInteractive, decisionSubject, decisionDetail } = require('./approve');
         const { readQueue } = require('../governance/approval-queue');
+        // @implements A-SPEC-262.1 — the flag path speaks the SAME grammar as the screen: an index, an
+        // exact id, or a unique prefix. A remote operator decides here, so an ambiguous reference must
+        // refuse by name here too — never resolve to "probably this one".
+        const { resolveRequestRef } = require('./approve-ref');
+        // The SUBJECT travels with the id: every decision line names what it acted on, so an index that
+        // resolved against a queue that shifted since `--list` is visible on the screen (round-1).
+        // The detail row travels with it: round-5 measured the one-line form at 81 columns, so the flag
+        // path prints the same two rows the screen does — subject read, id acted on.
+        const resolveRef = (ref) => {
+            const r = resolveRequestRef(readQueue(root).pending, ref);
+            return r.ok ? { id: r.entry.id, subject: (prefix) => decisionSubject(r.entry, prefix), detail: (tail) => decisionDetail(r.entry, tail) } : { refusal: r.reason };
+        };
         const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
         const actor = (() => { try {
             return os.userInfo().username || 'operator';
@@ -378,8 +736,13 @@ async function main(argv) {
                 opts.ttlMinutes = Number(flags.ttl);
             if (typeof flags.rationale === 'string')
                 opts.rationale = flags.rationale;
-            const r = grantRequest(root, flags.grant, opts);
-            process.stdout.write(r.ok ? `✓ 승인 — ${r.expires} 까지 유효\n` : `✗ ${r.reason}\n`);
+            const ref = resolveRef(flags.grant);
+            if ('refusal' in ref) {
+                process.stdout.write(`\u2717 ${ref.refusal}\n`);
+                return 1;
+            }
+            const r = grantRequest(root, ref.id, opts);
+            process.stdout.write(r.ok ? `✓ 승인 — ${ref.subject('✓ 승인 — ')}\n${ref.detail(`${r.expires} 까지 유효`)}\n` : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
         if (typeof flags.deny === 'string') {
@@ -388,8 +751,13 @@ async function main(argv) {
                 process.stderr.write('✗ --deny 는 --reason 이 필요합니다 — 사유 없는 거부는 에이전트가 볼 수 없습니다\n');
                 return 1;
             }
-            const r = denyRequest(root, flags.deny, reason, actor);
-            process.stdout.write(r.ok ? '✓ 거부 기록됨\n' : `✗ ${r.reason}\n`);
+            const ref = resolveRef(flags.deny);
+            if ('refusal' in ref) {
+                process.stdout.write(`\u2717 ${ref.refusal}\n`);
+                return 1;
+            }
+            const r = denyRequest(root, ref.id, reason, actor);
+            process.stdout.write(r.ok ? `✓ 거부 — ${ref.subject('✓ 거부 — ')}\n${ref.detail('거부가 기록됐습니다')}\n` : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
         if (typeof flags.ask === 'string') {
@@ -398,14 +766,58 @@ async function main(argv) {
                 process.stderr.write('✗ --ask 는 --question 이 필요합니다\n');
                 return 1;
             }
-            const r = holdRequest(root, flags.ask, question, actor);
-            process.stdout.write(r.ok ? '✓ 보류 — 질문이 다음 거부 문면에 실립니다\n' : `✗ ${r.reason}\n`);
+            const ref = resolveRef(flags.ask);
+            if ('refusal' in ref) {
+                process.stdout.write(`\u2717 ${ref.refusal}\n`);
+                return 1;
+            }
+            const r = holdRequest(root, ref.id, question, actor);
+            process.stdout.write(r.ok ? `✓ 보류 — ${ref.subject('✓ 보류 — ')}\n${ref.detail('질문은 다음 거부 문면에')}\n` : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
         if (flags.list) {
             process.stdout.write(renderPending(readQueue(root)) + '\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,
+        // ends the watch at once and exit 0; pending items stay in the queue.
+        if (flags.watch === true) {
+            let pollMs;
+            if (typeof flags['poll-ms'] === 'string') {
+                pollMs = Number(flags['poll-ms']);
+                if (!Number.isInteger(pollMs) || pollMs <= 0) {
+                    process.stderr.write(`✗ --poll-ms 는 양의 정수(밀리초)여야 합니다 — 받은 값: ${flags['poll-ms']}\n`);
+                    return 1;
+                }
+            }
+            if (!process.stdin.isTTY) {
+                process.stderr.write('✗ 대화형 상주 모드(--watch)는 TTY 가 필요합니다 — 스크립트에서는 --list 를 쓰십시오\n');
+                return 1;
+            }
+            const { runWatch } = require('./approve-watch');
+            const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
+            const ac = new AbortController();
+            rl.once('close', () => ac.abort());
+            const onSig = () => ac.abort();
+            process.once('SIGINT', onSig);
+            try {
+                await runWatch(root, {
+                    print: (t) => process.stdout.write(t + '\n'),
+                    ask: (q) => rl.question(q, { signal: ac.signal }),
+                }, actor, { signal: ac.signal, ...(pollMs !== undefined ? { pollMs } : {}) });
+            }
+            catch (e) {
+                if (e?.name !== 'AbortError')
+                    throw e;
+            }
+            finally {
+                process.removeListener('SIGINT', onSig);
+                rl.close();
+            }
+            return 0;
+        }
         // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
         // with the real pending id filled in; the explicit --list above stays script-clean.
         if (!process.stdin.isTTY) {
@@ -414,11 +826,32 @@ async function main(argv) {
             process.stdout.write(renderPending(state) + (hint ? '\n\n' + hint : '') + '\n');
             return 0;
         }
+        // @implements A-SPEC-262.1
+        // AWAITED, not fire-and-forget. Measured 2026-08-25 against the shipped bin with a real pty: the
+        // prompt printed and the session ended with zero grants, because `void runInteractive(...)`
+        // returned 0 immediately and bin/holmes-kit.js turns that into `process.exit(0)` — killing the
+        // loop before the first keypress. The decision surface REQ-246 shipped had never run for a real
+        // operator; every test called `runInteractive` directly and so never crossed this seam.
         const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
-        void runInteractive(root, {
-            print: (t) => process.stdout.write(t + '\n'),
-            ask: (q) => rl.question(q),
-        }, actor).finally(() => rl.close());
+        // EOF is the operator LEAVING (Ctrl-D, a closed pipe). Node leaves a pending `question`
+        // unsettled when the interface closes, so without this the awaited loop would hang the command
+        // forever — measured 2026-08-25, a pty probe hung for five minutes. The abort ends the session
+        // the way the operator asked: quietly, exit 0, nothing decided that was not decided.
+        const ac = new AbortController();
+        rl.once('close', () => ac.abort());
+        try {
+            await runInteractive(root, {
+                print: (t) => process.stdout.write(t + '\n'),
+                ask: (q) => rl.question(q, { signal: ac.signal }),
+            }, actor);
+        }
+        catch (e) {
+            if (e?.name !== 'AbortError')
+                throw e;
+        }
+        finally {
+            rl.close();
+        }
         return 0;
     }
     if (cmd === 'serve') {
@@ -500,7 +933,9 @@ async function main(argv) {
             isAdditive = true;
         }
         else if (process.stdin.isTTY && process.stdout.isTTY && flags['dry-run'] !== true && flags.remove !== true) {
-            agents = await promptAgentSelection(AGENTS, ['claude', 'antigravity']);
+            // Default to all harnesses checked — matches the menu's "Select All (Recommended)" and
+            // spares users a toggle per harness. Deselecting is one keystroke; a missed wiring is not.
+            agents = await promptAgentSelection(AGENTS, [...AGENTS]);
             isAdditive = true;
         }
         else {
@@ -548,6 +983,40 @@ async function main(argv) {
         : `unknown command: ${cmd}\n\n${USAGE}`);
     return cmd.startsWith('-') ? 2 : 1;
 }
+/**
+ * @implements A-SPEC-262.1
+ * Is this the normal end of a pipeline rather than a fault? Round-10: `approve --list | head` printed
+ * a Node stack dump and exited 1 — on a command whose own help says it is for scripts, where a
+ * consumer that stops reading is how pipelines end. Exported so the decision is testable without
+ * spawning a process and racing a pipe.
+ */
+const isBrokenPipe = (err) => err?.code === 'EPIPE';
+exports.isBrokenPipe = isBrokenPipe;
+let pipeGuardInstalled = false;
+/**
+ * @implements A-SPEC-262.1
+ * A broken stdout pipe is the normal end of `| head`, not a fault worth a thousand bytes of Node
+ * internals on the operator's screen; exit quietly with the conventional status.
+ *
+ * Round-10 installed this ONLY inside `if (require.main === module)`. Round-11 measured that the
+ * shipped `holmes-kit` never runs that block — `bin/holmes-kit.js` loads this file as a MODULE and
+ * calls `main()`, so `require.main` is the bin, not this module. The guard was therefore DEAD on the
+ * shipped binary: an interactive or `--watch` surface piped to a reader that closes (`| head`)
+ * crashed with an unhandled `'error'` EPIPE stack and exit 1 (measured byte-identical for one-shot
+ * and watch — a shared adapter property, not a watch defect). Installing from `main()` — the one
+ * path every shipped invocation takes — makes the round-10 fix actually run. Idempotent: the module
+ * flag keeps repeated `main()` calls (the test suite) from stacking listeners.
+ */
+function installPipeGuard() {
+    if (pipeGuardInstalled)
+        return;
+    pipeGuardInstalled = true;
+    process.stdout.on('error', (err) => {
+        if ((0, exports.isBrokenPipe)(err))
+            process.exit(0);
+        throw err;
+    });
+}
 if (require.main === module) {
     main(process.argv.slice(2))
         .then((code) => process.exit(code))