@holmes-lab/holmes-kit 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.1.13] - 2026-08-23
+
+The HITL approval overhaul — a human decides in the CLI, and never types a line of scope
+syntax. Driven by dogfooding feedback from governing a real 46-spec Python repo.
+
+### Added
+- **Approval request queue (REQ-244)**: every refusal whose only fix is an owner approval now
+  files a structured request into `.ax/approvals/queue.jsonl`, and the refusal text carries the
+  request id. Six gate sites — hard-hitl shell, config-write, role-policy, spec_approve, sealed
+  spec_retire, review-resolve. Repeats fold by content-hash id (six blocks, one row). The queue
+  is information, never authority: a forged `granted` event opens no gate.
+- **Grant file channel (REQ-245)**: approvals delivered by dropping a file into
+  `.ax/approvals/grants/`, read at judgement time — no `.mcp.json` editing, no MCP reconnect. A
+  grant is an ordinary Approval, judged by the existing `approvalCovers`; hard-hitl replay is
+  refused atomically by the existing ledger nonce consumption. Grants must be narrow (scope +
+  expires + nonce), so the committed-token failure the dogfooding found cannot recur. The session
+  cannot mint its own — `.ax/approvals` joined the protected directories on both the Write and
+  shell surfaces.
+- **`holmes-kit approve` (REQ-246)**: the decision surface. Interactive on a TTY — 승인/거부/질문/
+  건너뛰기 per request — or `--grant`/`--deny`/`--ask` for a CI/remote operator. The grant is
+  derived mechanically from the queue entry (kind→scope.kind, target→pattern, id→nonce); the human
+  types a decision, an optional rationale, and a TTL, and never scope grammar. Denials and holds
+  reach the agent in its next refusal, so a retry loop stops.
+- **Stop-gate pending-awareness + startup token health (REQ-247)**: the stop hook no longer
+  re-blocks a debt already queued for the owner — it says so once and lets the turn finish — while
+  a single non-waiting or code-resolvable violation still blocks. The MCP server logs the approval
+  token's health at startup (valid, invalid with reason, or absent), to stderr only.
+
+### Changed
+- **codex hook coverage is measured, not inferred (REQ-248, backlog)**: codex-cli 0.149.0 hook
+  protocol is identical to ours and our shipped hook is IO-compatible, but codex loads hooks
+  through its plugin system, not `config.toml` — so `init --agent codex` wires MCP only, and codex
+  stays governed by the server-side approval gates until plugin packaging lands.
+  `HARNESS_ENFORCES.codex` stays false: enforcement not observed is not written as present.
+
+<!-- @implements A-SPEC-209 -->
+## [0.1.12] - 2026-08-23
+
+### Added
+- **Install Guide (`docs/install-guide.md`, shipped in the package)**: install paths organised by
+  account type and privileges — a decision table first, commands second — because the same wrong
+  command (`npm install -g` against a protected prefix) was run three times by a real adopter
+  before the right one. Troubleshooting is keyed to the exact error text npm prints (`EPERM mkdir`,
+  `notarget`, `better-sqlite3` build failures, `spawn sh ENOENT`), and each entry says why
+  elevation is the wrong fix.
+
+### Changed
+- **README Quickstart leads with the situation table**, and steps 2–3 use `npx holmes-kit …` —
+  the bare `holmes-kit` they previously showed only exists on PATH after a global install, which
+  is not the primary path.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.1.11] - 2026-08-23
 

package/README.md

@@ -51,58 +51,35 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 
 ## ⚡ Quickstart (3-Minute Setup)
 
-### 1. Install
-
-Install it into the project you want to govern. This is the path verified end to end — the
-wiring `init` writes uses absolute paths, so a local install works from any directory:
-
-```bash
-npm install --save-dev @holmes-lab/holmes-kit
-```
-
-<details>
-<summary>Prefer one install for many projects? (<code>npm install -g</code>)</summary>
-
-A global install works too, but **do not elevate to get it**. Where npm puts global packages is
-your npm configuration, not ours — and on Windows it often points inside the Node.js installation
-directory:
-
-```text
-npm error code EPERM
-npm error path C:\Program Files\nodejs\node_modules\@holmes-lab
-```
-
-Running the install as Administrator would "fix" that by executing this package's native
-dependency install scripts with system privileges. Point npm at a user-writable prefix instead:
-
-```powershell
-npm config set prefix "$env:APPDATA\npm"          # Windows
-# then ensure %APPDATA%\npm is on PATH
-```
-```bash
-npm config set prefix "$HOME/.npm-global"          # macOS / Linux
-export PATH="$HOME/.npm-global/bin:$PATH"
-```
-
-A Node version manager (`nvm`, `fnm`, `volta`) does the same thing by keeping the whole
-toolchain under your home directory.
-</details>
-
-**Prerequisites** — Node.js `>= 20.0.0`, plus a native binary for two kinds of dependency:
-
-| Dependency | How the binary arrives |
-|---|---|
-| 8 tree-sitter grammars | Prebuilt binaries ship inside the packages (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) — nothing is compiled |
-| `better-sqlite3` | Downloaded at install time by `prebuild-install`, **falling back to compiling** if no prebuild matches your platform and Node ABI |
-
-Only the second can require a toolchain. If it has to compile, you need a C++ build environment:
-Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows, or
-`apk add --no-cache python3 make g++` on Alpine.
+### 1. Install — find your row first
+
+The same wrong command was run three times by a real adopter before the right one; a table beats
+prose read top-to-bottom.
+
+| Which situation are you in? | Privileges | Command |
+|---|---|---|
+| **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` |
+| Company-managed PC / restricted account | none | same — no system directory is touched |
+| CI / container | none | same, plus `--prefer-online` right after a release |
+| CLI across many projects (`-g`) | depends | run `npm config get prefix` first — see below |
+
+**Before `npm install -g`**: if `npm config get prefix` names a protected directory
+(`C:\Program Files\nodejs`, `/usr/local`), `-g` dies with `EPERM` **before any package file
+arrives** — no package version can fix that, and elevation is the wrong fix (it runs native
+install scripts with system privileges, and it did not even work in the reported case). Move the
+prefix to user space instead — one-time setup, exact commands in the
+**[Install Guide](docs/install-guide.md)**, along with troubleshooting keyed to the exact error
+text (`EPERM mkdir`, `notarget`, `better-sqlite3` build failures).
+
+**Prerequisites** — Node.js `>= 20.0.0`. The 8 tree-sitter grammars ship prebuilt binaries for
+macOS/Linux/Windows and compile nothing; `better-sqlite3` downloads a prebuild at install time,
+falling back to compiling — only that fallback needs a C++ toolchain (VS Build Tools / Xcode CLT /
+`apk add python3 make g++`).
 
 ### 2. Initialize in Your Project
 ```bash
 cd /path/to/your/project
-holmes-kit init
+npx holmes-kit init      # drop the npx prefix if you installed with -g
 ```
 *An interactive prompt will ask which AI agent harnesses to wire into your project:*
 ```text
@@ -114,7 +91,7 @@ holmes-kit init
 
 ### 3. Verify Health
 ```bash
-holmes-kit doctor
+npx holmes-kit doctor
 ```
 *If everything is green, your project is governed and ready for AI pair-programming!*
 

package/dist/.build-id

@@ -1 +1 @@
-c3422e5-mt570gca
+0c506c6-mt5buls8

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

@@ -14,8 +14,15 @@ export type Agent = (typeof AGENTS)[number];
  * - `claude` — PreToolUse/Stop 훅. 이 저장소가 처음부터 배선해 온 하네스.
  * - `antigravity` — PreToolUse/Stop 훅이 있고 `deny`/`continue` 로 막을 수 있다(설치본의
  *   `agy-customizations` 규약 문서와 실제 대화 기록에서 실측).
- * - `codex` — 이 기계에 설치되어 있지 않아 훅 규약을 **재지 못했다**. 재지 못한 것을 있다고
- *   적지 않는다. 도구(MCP)와 지침만 준다.
+ * - `codex` — 실측했다(codex-cli 0.149.0, 2026-08-23). 훅 규약 자체는 우리 것과 **동일**하다:
+ *   바이너리 스키마가 `PreToolUse` / `permissionDecision: allow|deny|ask` / `stop_hook_active` /
+ *   `hookSpecificOutput` 를 그대로 쓰고, codex 입력 형식으로 우리 `pre-tool-use.js` 를 먹이면 정확히
+ *   `deny` 를 낸다. 그런데도 `false` 인 이유는 **배선 경로**다: codex 의 훅은 `config.toml` 의
+ *   `[[hooks]]` 로 로드되지 않는다(잘못된 타입을 넣어도 `--strict-config` 가 통과 — 스키마 밖이다).
+ *   `hook_runtime` 트레이스는 실제 셸 도구 실행에도 진입하지 않았고, 바이너리 문자열이 훅을
+ *   `Plugins`/`RemotePlugin` 시스템(`codex plugin`, `--with-hooks` scaffold)으로 로드한다고 말한다.
+ *   즉 codex 훅 집행은 **plugin 패키징**이 필요하며 MCP·config 배선으로는 닿지 않는다(REQ-248 로 남김).
+ *   그때까지 codex 는 MCP 서버로만 지배되며, 그 경로는 실증됐다(spec_approve 등 서버측 승인 게이트).
  */
 export declare const HARNESS_ENFORCES: Record<Agent, boolean>;
 export interface AgentWiringOptions {

package/dist/holmes/cli/agents.js

@@ -53,8 +53,15 @@ exports.AGENTS = ['claude', 'antigravity', 'codex'];
  * - `claude` — PreToolUse/Stop 훅. 이 저장소가 처음부터 배선해 온 하네스.
  * - `antigravity` — PreToolUse/Stop 훅이 있고 `deny`/`continue` 로 막을 수 있다(설치본의
  *   `agy-customizations` 규약 문서와 실제 대화 기록에서 실측).
- * - `codex` — 이 기계에 설치되어 있지 않아 훅 규약을 **재지 못했다**. 재지 못한 것을 있다고
- *   적지 않는다. 도구(MCP)와 지침만 준다.
+ * - `codex` — 실측했다(codex-cli 0.149.0, 2026-08-23). 훅 규약 자체는 우리 것과 **동일**하다:
+ *   바이너리 스키마가 `PreToolUse` / `permissionDecision: allow|deny|ask` / `stop_hook_active` /
+ *   `hookSpecificOutput` 를 그대로 쓰고, codex 입력 형식으로 우리 `pre-tool-use.js` 를 먹이면 정확히
+ *   `deny` 를 낸다. 그런데도 `false` 인 이유는 **배선 경로**다: codex 의 훅은 `config.toml` 의
+ *   `[[hooks]]` 로 로드되지 않는다(잘못된 타입을 넣어도 `--strict-config` 가 통과 — 스키마 밖이다).
+ *   `hook_runtime` 트레이스는 실제 셸 도구 실행에도 진입하지 않았고, 바이너리 문자열이 훅을
+ *   `Plugins`/`RemotePlugin` 시스템(`codex plugin`, `--with-hooks` scaffold)으로 로드한다고 말한다.
+ *   즉 codex 훅 집행은 **plugin 패키징**이 필요하며 MCP·config 배선으로는 닿지 않는다(REQ-248 로 남김).
+ *   그때까지 codex 는 MCP 서버로만 지배되며, 그 경로는 실증됐다(spec_approve 등 서버측 승인 게이트).
  */
 exports.HARNESS_ENFORCES = {
     claude: true,

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

@@ -0,0 +1,46 @@
+import { QueueState } from '../governance/approval-queue';
+export type DecisionResult = {
+    ok: true;
+    expires?: string;
+} | {
+    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;
+/**
+ * The review screen. Pure.
+ *
+ * What a decision needs and nothing else: what (kind·target), why, how often it was blocked, since
+ * when, and any standing question. Deliberately NO scope grammar anywhere — the moment the screen
+ * teaches syntax, humans start typing it.
+ */
+export declare function renderPending(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.
+ *
+ * @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.
+ */
+export declare function runInteractive(root: string, io: ApproveIO, actor: string): Promise<void>;

package/dist/holmes/cli/approve.js

@@ -0,0 +1,200 @@
+"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.grantRequest = grantRequest;
+exports.denyRequest = denyRequest;
+exports.holdRequest = holdRequest;
+exports.renderPending = renderPending;
+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 approval_grants_1 = require("../governance/approval-grants");
+/**
+ * `holmes-kit approve` — the surface where a human decides.
+ *
+ * @implements A-SPEC-246
+ * The queue makes the review list (REQ-244) and grant files deliver approvals with no editing and
+ * no reconnect (REQ-245); what was missing is the surface where the decision happens. Without it
+ * the operator hand-writes grant JSON — scope grammar, expiry format, nonce rules — the exact
+ * "human types values into files" this programme exists to zero out.
+ *
+ * THE DECISION API IS THE HEART; THE TUI IS A SHELL. `grantRequest`/`denyRequest`/`holdRequest`
+ * write the files and events; both the interactive loop and the flags call the same three, so a
+ * CI or remote operator without a TTY is never locked out.
+ *
+ * A GRANT IS DERIVED, NEVER TYPED. kind→scope.kind, target→pattern, id→nonce, now+TTL→expires —
+ * all from the queue entry. The human's inputs are the decision, an optional rationale, and a TTL.
+ * The moment the human must know scope syntax, this UI has no reason to exist.
+ */
+const DEFAULT_TTL_MINUTES = 30;
+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. */
+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 });
+        fs.appendFileSync(file, JSON.stringify({ ...event, ts: new Date().toISOString() }) + '\n');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * 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).
+ */
+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)}` };
+    }
+    const { entry } = findPending(root, id);
+    if (!entry)
+        return { ok: false, reason: `대기 중인 요청 ${id} 가 없습니다 — npx holmes-kit approve --list 로 확인하십시오` };
+    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 }],
+        expires,
+        nonce: id,
+    };
+    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');
+    }
+    catch (e) {
+        return { ok: false, reason: `그랜트 파일을 쓸 수 없습니다: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    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: 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: true };
+}
+/**
+ * The review screen. Pure.
+ *
+ * What a decision needs and nothing else: what (kind·target), why, how often it was blocked, since
+ * when, and any standing question. Deliberately NO scope grammar anywhere — the moment the screen
+ * teaches syntax, humans start typing it.
+ */
+function renderPending(state) {
+    if (state.pending.length === 0)
+        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}`);
+        lines.push('');
+    });
+    if (state.malformedLines > 0)
+        lines.push(`(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`);
+    return lines.join('\n');
+}
+/**
+ * The interactive loop — one entry at a time, one letter 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.
+ */
+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();
+        if (answer === 'a') {
+            const rationale = (await io.ask(`사유 (enter = "${DEFAULT_RATIONALE}") > `)).trim();
+            const ttlRaw = (await io.ask(`유효 시간(분, 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}`);
+        }
+        else if (answer === 'd') {
+            const reason = (await io.ask('거부 사유(에이전트에게 전달됩니다) > ')).trim();
+            if (reason === '') {
+                io.print('✗ 사유 없는 거부는 에이전트가 볼 수 없습니다 — 건너뜁니다');
+                continue;
+            }
+            const r = denyRequest(root, p.id, reason, actor);
+            io.print(r.ok ? '✓ 거부 기록됨' : `✗ ${r.reason}`);
+        }
+        else if (answer === 'q') {
+            const question = (await io.ask('질문(에이전트가 사용자에게 전달합니다) > ')).trim();
+            if (question === '') {
+                io.print('✗ 빈 질문 — 건너뜁니다');
+                continue;
+            }
+            const r = holdRequest(root, p.id, question, actor);
+            io.print(r.ok ? '✓ 보류 — 질문이 다음 거부 문면에 실립니다' : `✗ ${r.reason}`);
+        }
+        // 's' and anything else: leave it for later.
+    }
+}

package/dist/holmes/cli/index.js

@@ -39,6 +39,7 @@ exports.main = main;
 // @implements A-SPEC-213
 // @implements A-SPEC-215
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const init_1 = require("./init");
 const doctor_1 = require("./doctor");
@@ -73,7 +74,17 @@ 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'],
 };
+const APPROVE_USAGE = `holmes-kit approve — 승인 대기 요청의 결재 (HITL)
+
+  대화형(TTY):        항목마다 [a]승인 [d]거부 [q]질문 [s]건너뛰기
+  --list              대기 목록만 출력
+  --grant <id>        해당 요청의 좁은 그랜트 발급 (--ttl <분>, --rationale <문구>)
+  --deny <id> --reason <문구>     거부 — 사유가 에이전트의 다음 거부 문면에 실립니다
+  --ask <id> --question <문구>    질문 남기고 보류 — 에이전트가 사용자에게 전달합니다
+  --target <dir>      프로젝트 루트 (기본: 현재 디렉터리)
+`;
 class UnknownFlagError extends Error {
 }
 /**
@@ -82,7 +93,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']);
+const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list']);
 function parseFlags(argv, known) {
     const flags = {};
     const positionals = [];
@@ -163,6 +174,14 @@ 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 approve           review pending approval requests (HITL)
+    (no flags, TTY)            interactive: [a]승인 [d]거부 [q]질문 [s]건너뛰기 per request
+    --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
+    --target <dir>             project root (default: cwd)
+
   holmes-kit doctor [flags]    diagnose the install
     --target <dir>             also verify that target's wiring points at this install
     --json                     machine-readable output
@@ -328,6 +347,64 @@ async function main(argv) {
         return res.ok ? 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, runInteractive } = require('./approve');
+        const { readQueue } = require('../governance/approval-queue');
+        const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
+        const actor = (() => { try {
+            return os.userInfo().username || 'operator';
+        }
+        catch {
+            return 'operator';
+        } })();
+        if (flags.help) {
+            process.stdout.write(APPROVE_USAGE);
+            return 0;
+        }
+        if (typeof flags.grant === 'string') {
+            const opts = { actor };
+            if (typeof flags.ttl === 'string')
+                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`);
+            return r.ok ? 0 : 1;
+        }
+        if (typeof flags.deny === 'string') {
+            const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
+            if (reason === '') {
+                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`);
+            return r.ok ? 0 : 1;
+        }
+        if (typeof flags.ask === 'string') {
+            const question = typeof flags.question === 'string' ? flags.question.trim() : '';
+            if (question === '') {
+                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`);
+            return r.ok ? 0 : 1;
+        }
+        if (flags.list || !process.stdin.isTTY) {
+            process.stdout.write(renderPending(readQueue(root)) + '\n');
+            return 0;
+        }
+        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());
+        return 0;
+    }
     if (cmd === 'serve') {
         if (typeof flags.target === 'string') {
             const t = path.resolve(flags.target);

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

@@ -0,0 +1,63 @@
+import { Approval } from '../guardrail/risk-gate';
+/**
+ * The grant file channel — approval delivery with no file editing and no reconnect.
+ *
+ * @implements A-SPEC-245
+ * WHY THIS EXISTS. The only delivery channel was the MCP server's environment. Dogfooded cost of ONE
+ * human approval (Notion, 2026-08-23, UX-1): edit `.mcp.json` by hand (the hook blocks the agent
+ * doing it) → reconnect MCP → retry — three to four round trips. And the edit left the token behind:
+ * the same report found HOLMES_APPROVAL committed to the target repository since 8/18. The forgery
+ * defence's root of trust, sitting in plaintext in git.
+ *
+ * WHAT A GRANT IS. An ordinary `Approval` — no new format — read from
+ * `.ax/approvals/grants/<nonce>.json` at JUDGEMENT TIME, so nothing needs restarting. Judgement is
+ * the ONE existing `approvalCovers`; single-use for hard-hitl rides the ONE existing ledger nonce
+ * consumption. This module adds reading a directory, nothing else.
+ *
+ * WHY GRANTS MUST BE NARROW. A file is only a grant when it carries `scope` AND `expires` AND
+ * `nonce`. The unscoped session master key stays env-only: a masterless key rolling around as a
+ * file recreates the committed-token incident this channel exists to remove.
+ *
+ * TRUST MODEL. The session cannot write `.ax/approvals` — the same identity-based Write gate and
+ * shell-command gate that protect `.ax/ledger`. A hand that can create a grant file is by
+ * definition outside the session: the operator.
+ */
+export declare const GRANTS_RELDIR: string;
+/**
+ * Read the grant files. Filename order, so selection is deterministic.
+ *
+ * Ignored files are COUNTED, not silently skipped: "I dropped a grant in and nothing opened" must
+ * be diagnosable, and a silent skip makes an inert grant indistinguishable from no grant.
+ */
+export declare function readGrants(root: string): {
+    grants: Approval[];
+    ignored: number;
+};
+/** First grant that covers the action — judged by `approvalCovers` and nothing else. Pure. */
+export declare function pickCoveringGrant(grants: Approval[], action: {
+    kind: string;
+    target: string;
+}, now: string): Approval | undefined;
+/**
+ * Resolve the approval for an action: env first, then the grant files.
+ *
+ * @implements A-SPEC-245
+ * Env-first IS the backward compatibility: an adopter whose flows run on the env token sees not one
+ * changed verdict, message, or consumed file from this slice.
+ */
+export declare function resolveApproval(root: string, envApproval: Approval | undefined, action: {
+    kind: string;
+    target: string;
+}, now: string): {
+    approval: Approval;
+    source: 'env' | 'grant';
+} | undefined;
+/**
+ * Best-effort single-use: remove the grant file after the act it authorized succeeded.
+ *
+ * hard-hitl does not rely on this — its replay is refused atomically by the ledger nonce
+ * consumption the grant's mandatory nonce rides through. For the other sites, a failed removal
+ * leaves a reuse window whose ceiling is the grant's own `expires`; stated rather than hidden.
+ * The nonce is flattened to a basename so a traversal-shaped nonce cannot reach outside the dir.
+ */
+export declare function consumeGrantFile(root: string, nonce: string): void;