@holmes-lab/holmes-kit 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -5,7 +5,64 @@ 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.10.1] - 2026-09-04
+## [0.12.0] - 2026-09-05
+
+World-top-tier RTM dashboard, in flight. The `holmes-kit serve` dashboard stops being a table of
+accordions and becomes a real coverage matrix, gains a one-call launcher, and learns to serve CFG/PDG
+for a function. Additive and backward-compatible — every existing `/api/*` payload keeps its shape and
+values; these are new fields, a new endpoint, a new tool, and a rebuilt heatmap view.
+
+### Added
+
+- **2D coverage matrix** (REQ-545): the heatmap tab is now a single **requirement × pipeline-stage
+  grid** — rows are requirements ordered by completeness (seriation), each cell a sequential-ramp
+  colour with the coverage percent printed in it (so magnitude never rides on colour alone). Replaces
+  the per-REQ accordion-of-tables. `/api/rtm/heatmap` gains an additive `matrix` field
+  (`{reqs, stages, values, order, buckets}`) built by pure, unit-tested `buildStageMatrix` +
+  `seriateRows` + `coverageBucket`.
+- **`rtm_dashboard` MCP tool** (REQ-545): ask to *see* the RTM heatmap / coverage matrix and the
+  server launches (idempotently — a second call reuses the live one) and returns `{ url, running,
+  census }`, where `census` is an honesty summary (`reqCount, pipelineCount, coveredCount,
+  coveragePct, retiredCount, findingsScanned`). No more starting `serve` by hand.
+- **`/api/cfg` — control-flow + program-dependence for one function** (REQ-545): `?file=&symbol=`
+  returns that function's CFG (blocks with source line/label, control-flow edges) and PDG (block-level
+  control deps + reaching-def data deps), consumed from the same `cfgOf`/`pdgOf` the taint lane uses.
+  A non-CFG language is named as `unsupported`, never faked as an empty graph. (Graph-view rendering
+  of this lands next.)
+
+### Changed
+
+- **Dashboard design tokens** (REQ-545): the palette moved off the Tailwind-default + emoji-marker
+  look to a tokenised system — a single-hue sequential coverage ramp, reserved status colours, a
+  UI/mono type pairing (data in tabular-nums), surfaces and ink, with a light and a dark palette via
+  `prefers-color-scheme`. Applied to the new matrix view and the tab bar; structure emoji removed
+  (meaning markers only). The rest of the dashboard tokenises incrementally in the follow-on slice.
+- **Upgrade nudges point at one command** (REQ-544): the session banner's drift line and doctor's
+  version-drift fix hint now name `holmes-kit upgrade` (the right binary per platform — `npx.cmd` on
+  win32) instead of spelling out a manual `npm i` + `init --force`.
+
+## [0.11.0] - 2026-09-05
+
+Zero-config upgrades — preparation is automatic, execution is your explicit choice. Additive and
+backward-compatible; nothing changes at the default settings until you run `holmes-kit upgrade`.
+
+### Added
+
+- **`holmes-kit upgrade`** (REQ-543): one command to move every wired workspace to the latest — it
+  shows a plan (current → latest, and which workspaces it will re-pin), asks for confirmation, then
+  installs per install-mode, clears the stale npx cache, re-pins each recorded workspace, and prints
+  a per-workspace result table. `--dry-run` prints the plan and changes nothing; `--yes` skips the
+  prompt (required in a non-interactive shell — the execution is a deliberate choice, never a silent
+  auto-install of a gate-enforcing engine). A source checkout is told to upgrade via git.
+- **Workspace registry** (REQ-543): every successful `init` now records where holmes-kit is wired
+  (`~/.holmes/workspaces.json` — target, agents, version), so `upgrade` knows every workspace to
+  re-pin. Best-effort and side-channel: a registry problem never affects `init`.
+- **Session drift nudge** (REQ-543): when a session starts in a workspace whose `.mcp.json` pin is
+  OLDER than the installed package, the banner adds one line pointing at `holmes-kit upgrade`.
+  Detection is automatic; the re-pin **write** stays behind your `upgrade`/`init --force` choice —
+  a session-start force-write would bypass the governance-wiring approval, so it is not done silently.
+  Opt out with `HOLMES_NO_AUTO_REPIN`; no drift, opt-out, or unreadable pin leaves the banner
+  byte-identical.
 
 ### Fixed
 

package/README.md

@@ -19,6 +19,8 @@
 - 📋 **Requirements & Specification Governance**: Strict **"No Spec, No Code"** enforcement with 4-tier spec chain traceability (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) and `// @implements A-SPEC-XXX` code anchors (comma-lists and every anchor in a file participate in the gate).
 - 🔴 **Inbuilt TDD — RED-first, enforced not asked** *(new in 0.9.0)*: the test-first discipline is a holmes-installed `holmes-tdd-slice` skill **and** a new constitution article **ART-8**. A changed A-SPEC must show a recorded `red-assertion → green` sequence in the ledger; a `red-error` (a test that could not run) is not a valid RED, so "the covering test failed *correctly*" is judged mechanically, not on trust. `test_run` classifies each covered file (`red-assertion`/`red-error`/`green`) and records per-A-SPEC outcomes the Stop hook reads. Ships at `redFirstEvidence: track` (observe-first, non-blocking; `strict`/`off` per repo), evidence-gated and jest-only for now. A T-SPEC may also declare `kills:` mutations and `test_run --mutate` reports which SURVIVED (a coverage gap). Where superpowers *asks* for RED-first and discriminating power, holmes-kit *proves* them.
 - 🧰 **Governance UX tools** *(new in 0.10.0)*: `spec_unseal` (the inverse of `spec_approve` — return a sealed spec to editable `draft` in one act, out-of-band approval required, refuses approved dependents), `approval_status` and `ledger_timeline` (read-only observability into a spec's seal state and the governance history), and a structured `conflict` on `spec_approve`'s optimistic-concurrency refusal (read vs. current version + retry). See CHANGELOG for details.
+- ⬆️ **Zero-config upgrades** *(new in 0.11.0)*: `holmes-kit upgrade` moves **every** wired workspace to the latest in one command — plan → confirm → install → re-pin all recorded workspaces (`--dry-run`/`--yes` supported). Preparation is automatic (each `init` records the workspace; a session whose pin is behind nudges you to upgrade); the re-pin **write** stays your explicit choice, never a silent auto-install. Opt out of the nudge with `HOLMES_NO_AUTO_REPIN`.
+- 📊 **World-top-tier RTM dashboard** *(new in 0.12.0, in flight)*: `holmes-kit serve` — ask to *see* the RTM heatmap and the `rtm_dashboard` MCP tool launches the server idempotently and hands back the URL plus an honesty **census** (requirement/pipeline counts, coverage %, what's excluded). The heatmap is now a real **2D coverage matrix** (requirements × pipeline stages, rows seriated by completeness, sequential-ramp cells with the percent printed in each), and `/api/cfg?file=&symbol=` serves a function's **CFG + PDG** (control-flow blocks + data/control dependence) from the same engine the taint lane uses — a non-CFG language is named, never faked. Tokenised palette + light/dark; graph-view rendering of CFG/PDG lands next.
 - 🤖 **Autonomous Approval** *(new in 0.8.0)*: with the out-of-band `HOLMES_AUTONOMOUS_APPROVAL` switch on, an agent seals **low/mid-risk** specs itself (ledgered under an `autonomous:<client>` actor) — while `gate-behavior` changes, architecture/gate/taint files, and every upstream `REQ`/`H-SPEC`/`C-SPEC` still ask a human through the in-session TUI. The switch is env-only; a session cannot set it (blocked like `HOLMES_ROLE`). Off = byte-identical to before. *(new in 0.10.0)* Set **`HOLMES_ELICIT=off`** to skip the in-session prompt entirely and route every decision to the out-of-band `holmes-kit approve` queue instead — one decision surface that behaves identically across Claude Code / Antigravity / Codex.
 - 🪧 **Session Banner + Update Notice** *(new in 0.8.0)*: every session start emits an English intro (version + governance rule + npm URL) to both the human transcript and the agent context (SessionStart hook + MCP `instructions`); when a newer published version is cached, an install-mode-aware update command is appended. Registry check is detached, fail-silent, and opts out via `HOLMES_NO_UPDATE_CHECK`/`CI`.
 - 🧱 **Deterministic Gate, Hardened** *(new in 0.8.0)*: shell writes are judged at the segment's **effective working directory** (`cd sub && cat > ../src/x.ts` is sealed, legitimate out-of-tree scratch writes are freed); the governing anchor is the **whole set**, not the first match. Every gate change ships with two consecutive clean adversarial rounds.

package/dist/.build-id

@@ -1 +1 @@
-b8567d9-mtn379s6
+85d7b53-mtnr6dpp

package/dist/holmes/cli/approve.js

@@ -46,6 +46,7 @@ exports.renderNonTtyHint = renderNonTtyHint;
 exports.runInteractive = runInteractive;
 // @implements A-SPEC-246
 const fs = __importStar(require("node:fs"));
+const npx_bin_1 = require("../project/npx-bin");
 const path = __importStar(require("node:path"));
 const approval_queue_1 = require("../governance/approval-queue");
 const screen_safe_1 = require("./screen-safe");
@@ -143,7 +144,7 @@ function grantRequest(root, id, opts) {
     }
     const { entry } = findPending(root, id);
     if (!entry)
-        return { ok: false, reason: `대기 중인 요청 ${(0, screen_safe_1.rowField)(id, 40)} 가 없습니다 — npx holmes-kit approve --list 로 확인하십시오` };
+        return { ok: false, reason: `대기 중인 요청 ${(0, screen_safe_1.rowField)(id, 40)} 가 없습니다 — ${(0, npx_bin_1.npxBin)()} 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

package/dist/holmes/cli/doctor.js

@@ -49,6 +49,7 @@ exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
 // @implements A-SPEC-207
 // @implements A-SPEC-100.2
 const fs = __importStar(require("node:fs"));
+const npx_bin_1 = require("../project/npx-bin");
 const tier_1 = require("../semantic/tier");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
@@ -756,7 +757,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const launch = (0, mcp_version_1.mcpLaunchVersion)({ command: server.command, args: server.args }, readPkgVersionAt);
                 const verdict = (0, mcp_version_1.versionDriftVerdict)(launch, cli);
                 if (verdict === 'drift') {
-                    add('mcp server version', 'WARN', `이 프로젝트의 MCP 서버는 holmes-kit ${launch} 를 띄우지만 이 CLI 는 ${cli} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, 'npx @holmes-lab/holmes-kit@latest init 을 다시 실행해 .mcp.json 을 최신 버전으로 재배선하십시오 (전역 -g 업그레이드 불필요).');
+                    add('mcp server version', 'WARN', `이 프로젝트의 MCP 서버는 holmes-kit ${launch} 를 띄우지만 이 CLI 는 ${cli} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, 
+                    // @implements A-SPEC-544.1 — one command installs + re-pins every workspace; init --force is the per-workspace path.
+                    `${(0, npx_bin_1.npxBin)()} holmes-kit upgrade 로 최신 설치 + 전 워크스페이스 재핀 (이 워크스페이스만 고치려면 ${(0, npx_bin_1.npxBin)()} holmes-kit init --force).`);
                 }
                 else if (verdict === 'match') {
                     add('mcp server version', 'PASS', `MCP 서버 버전 ${launch} 가 이 CLI 와 일치합니다`);
@@ -810,7 +813,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const h = JSON.parse(fs.readFileSync(agyHooks, 'utf8'));
                 const entry = h['holmes-kit'];
                 const pre = entry?.PreToolUse?.[0];
-                // @implements A-SPEC-539.1 — the hook script path now lives in args[0] (command is bare
+                // @implements A-SPEC-541.1 — the hook script path now lives in args[0] (command is bare
                 // 'node'); older wirings joined it into the command string. Read args first, fall back to
                 // parsing the string so a pre-539 hooks.json is still judged correctly.
                 const scriptOf = (e) => (Array.isArray(e?.args) && typeof e?.args[0] === 'string') ? e.args[0] : (0, settings_merge_1.hookScriptPath)(e?.command ?? '');
@@ -1280,7 +1283,7 @@ function pushGateCheck(target) {
             : {
                 name: 'push gate', level: 'WARN',
                 detail: 'pre-push 증빙 게이트가 설치되어 있지 않습니다 — 미검증 HEAD 가 다른 에이전트의 기준선이 될 수 있습니다',
-                fix: 'npx holmes-kit install-push-gate 를 실행하십시오 (기존 훅은 덮지 않습니다)',
+                fix: `${(0, npx_bin_1.npxBin)()} holmes-kit install-push-gate 를 실행하십시오 (기존 훅은 덮지 않습니다)`,
             };
     }
     catch {

package/dist/holmes/cli/index.js

@@ -82,6 +82,8 @@ const KNOWN_FLAGS = {
     'semantic-key': ['help'],
     // @implements A-SPEC-509.1 — the explicit installation act for the pre-push evidence gate.
     'install-push-gate': ['help', 'target'],
+    // @implements A-SPEC-543.2 — one-command upgrade: install + re-pin every registered workspace.
+    upgrade: ['help', 'dry-run', 'yes'],
 };
 // @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
@@ -212,6 +214,10 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
     --target <dir>             also verify that target's wiring points at this install
     --json                     machine-readable output
 
+  holmes-kit upgrade [flags]   install the latest and re-pin every recorded workspace (one command)
+    --dry-run                  show the plan (current→latest, workspaces to re-pin), change nothing
+    --yes                      skip the confirmation prompt (required in a non-interactive shell)
+
   holmes-kit skills refresh [flags]   refresh the recovery skills holmes-kit owns
     --target <dir>             target project (default: cwd; must exist). Touches ONLY marker-owned
                                skill files (installs absent ones, REWRITES all marker-owned ones,
@@ -1038,9 +1044,52 @@ async function main(argv) {
                     process.stdout.write(c.after.split('\n').map((l) => `    | ${l}`).join('\n') + '\n');
                 }
             }
+            // @implements A-SPEC-543.1 — zero-config upgrade PREPARATION: a successful real wiring records
+            // WHERE holmes-kit is wired, so `upgrade` later knows every workspace to re-pin. Best-effort by
+            // contract: a registry problem must never change init's output or exit code.
+            if (!opts.dryRun && !opts.remove) {
+                try {
+                    const { recordWorkspace } = require('../update/workspaces');
+                    const os2 = require('node:os');
+                    const pkgVersion = (() => {
+                        try {
+                            return String(JSON.parse(fs.readFileSync(path.join(opts.packageRoot, 'package.json'), 'utf8')).version ?? '');
+                        }
+                        catch {
+                            return '';
+                        }
+                    })();
+                    recordWorkspace(os2.homedir(), { target: opts.target, agents: [...agents], version: pkgVersion, ts: new Date().toISOString() });
+                }
+                catch { /* registry failure never fails init */ }
+            }
         }
         return res.exitCode;
     }
+    // @implements A-SPEC-543.2 — one-command upgrade. Preparation is zero-config (init records the
+    // registry); the EXECUTION is the user's explicit choice — a plan is shown and confirmed (or a
+    // non-TTY passes --yes), never a silent auto-install of a gate-enforcing engine.
+    if (cmd === 'upgrade') {
+        const { runUpgrade } = require('./upgrade');
+        return await runUpgrade({
+            dryRun: flags['dry-run'] === true,
+            yes: flags.yes === true,
+            stdout: (s) => process.stdout.write(s),
+            stderr: (s) => process.stderr.write(s),
+            confirm: async (prompt) => {
+                if (!process.stdin.isTTY || !process.stdout.isTTY)
+                    return false;
+                const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    const ans = (await rl.question(prompt)).trim().toLowerCase();
+                    return ans === 'y' || ans === 'yes';
+                }
+                finally {
+                    rl.close();
+                }
+            },
+        });
+    }
     // round-8: `holmes-kit --target x` 나 `holmes-kit --` 처럼 명령 자리에 플래그가 오면 exit 1,
     // 같은 토큰이 하위 명령 뒤에 오면 exit 2 였다 — 같은 실수에 두 가지 진단.
     process.stderr.write(cmd.startsWith('-')

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

@@ -0,0 +1,14 @@
+export interface UpgradeIO {
+    dryRun: boolean;
+    yes: boolean;
+    stdout: (s: string) => void;
+    stderr: (s: string) => void;
+    confirm: (prompt: string) => Promise<boolean>;
+}
+/**
+ * @implements A-SPEC-543.2
+ * Thin orchestration around the pure `planUpgrade`. Resolves latest from the update cache, plans,
+ * shows/confirms (the user's choice), then installs + re-pins every registered workspace. Install
+ * failure aborts BEFORE any re-pin (never re-pin to a version that did not install).
+ */
+export declare function runUpgrade(io: UpgradeIO): Promise<number>;

package/dist/holmes/cli/upgrade.js

@@ -0,0 +1,177 @@
+"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.runUpgrade = runUpgrade;
+// @implements A-SPEC-543.2
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const update_notice_1 = require("../update/update-notice");
+const workspaces_1 = require("../update/workspaces");
+const upgrade_plan_1 = require("../update/upgrade-plan");
+const session_start_1 = require("../hooks/session-start");
+const npx_bin_1 = require("../project/npx-bin");
+const PKG = '@holmes-lab/holmes-kit';
+// Local copy of index.ts's packageRoot (dist/holmes/cli/upgrade.js → 3 up) — avoids a require cycle,
+// since index.ts lazily requires THIS module.
+function packageRoot() {
+    return path.resolve(__dirname, '..', '..', '..');
+}
+function currentVersion(root) {
+    try {
+        return String(JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version ?? '0.0.0');
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** `npm` on POSIX, `npm.cmd` on win32 — the shim a spawn resolves (same binary-name reasoning as npxBin). */
+function npmBin() { return process.platform === 'win32' ? 'npm.cmd' : 'npm'; }
+/** Render the plan for the human, one line per fact. */
+function renderPlan(plan) {
+    const lines = [
+        `Holmes-Kit upgrade: ${plan.current} → ${plan.latest} (install mode: ${plan.installMode})`,
+        plan.repins.length
+            ? `Will re-pin ${plan.repins.length} workspace(s):`
+            : 'No wired workspaces recorded yet — install only.',
+        ...plan.repins.map((w) => `  • ${w.target}  [${w.agents.join(', ')}]`),
+    ];
+    return lines.join('\n') + '\n';
+}
+/**
+ * @implements A-SPEC-543.2
+ * Thin orchestration around the pure `planUpgrade`. Resolves latest from the update cache, plans,
+ * shows/confirms (the user's choice), then installs + re-pins every registered workspace. Install
+ * failure aborts BEFORE any re-pin (never re-pin to a version that did not install).
+ */
+async function runUpgrade(io) {
+    const root = packageRoot();
+    const current = currentVersion(root);
+    const mode = (0, session_start_1.detectInstallMode)(root);
+    const cached = (0, update_notice_1.readCache)(os.homedir(), (p) => fs.readFileSync(p, 'utf8'));
+    const registry = (() => {
+        try {
+            return (0, workspaces_1.readRegistry)(fs.readFileSync(path.join(os.homedir(), '.holmes', 'workspaces.json'), 'utf8'));
+        }
+        catch {
+            return (0, workspaces_1.readRegistry)(null);
+        }
+    })();
+    const plan = (0, upgrade_plan_1.planUpgrade)({ current, latest: cached?.latest ?? null, registry, installMode: mode });
+    if (plan.kind === 'noop') {
+        io.stdout(`${plan.reason}\n`);
+        return 0;
+    }
+    io.stdout(renderPlan(plan));
+    if (io.dryRun) {
+        io.stdout('(dry-run — nothing installed or re-pinned)\n');
+        return 0;
+    }
+    if (plan.installMode === 'source') {
+        io.stderr('source checkout: upgrade via git (git pull && npm run build), not npm install.\n');
+        return 1;
+    }
+    const go = io.yes || await io.confirm('계속합니까? [y/N] ');
+    if (!go) {
+        io.stdout(io.yes ? '' : 'aborted — nothing installed or re-pinned.\n');
+        if (!io.yes && (!process.stdin.isTTY))
+            io.stderr('non-interactive: pass --yes to upgrade without a prompt.\n');
+        return io.yes ? 0 : (process.stdin.isTTY ? 0 : 1);
+    }
+    // (1) install — failure aborts before any re-pin.
+    try {
+        const args = plan.installMode === 'global-npx'
+            ? ['i', '-g', `${PKG}@${plan.latest}`]
+            : ['i', '-D', `${PKG}@${plan.latest}`];
+        (0, node_child_process_1.execFileSync)(npmBin(), args, { stdio: 'inherit', cwd: process.cwd() });
+    }
+    catch {
+        io.stderr(`install failed — nothing re-pinned. Try manually: ${npmBin()} i ${plan.installMode === 'global-npx' ? '-g' : '-D'} ${PKG}@${plan.latest}\n`);
+        return 1;
+    }
+    // (2) best-effort: clear our stale npx cache so a subsequent npx picks up the new version.
+    try {
+        const npxDir = path.join(os.homedir(), '.npm', '_npx');
+        for (const d of fs.readdirSync(npxDir)) {
+            const pkgJson = path.join(npxDir, d, 'node_modules', PKG, 'package.json');
+            if (fs.existsSync(pkgJson))
+                fs.rmSync(path.join(npxDir, d), { recursive: true, force: true });
+        }
+    }
+    catch { /* cache clear is best-effort */ }
+    // (3) re-pin every registered workspace that still exists.
+    const { runInit } = require('./init');
+    const newRoot = packageRoot(); // may differ after a global install; re-resolve
+    let repinned = 0, skipped = 0, failed = 0;
+    io.stdout('\nRe-pinning workspaces:\n');
+    for (const w of registry.workspaces) {
+        if (!fs.existsSync(w.target)) {
+            io.stdout(`  건너뜀 (경로 없음): ${w.target}\n`);
+            skipped++;
+            continue;
+        }
+        try {
+            const res = runInit({
+                target: w.target,
+                packageRoot: newRoot,
+                mode: 'guardrail',
+                specsDir: '.ax/specs',
+                settingsFile: 'local',
+                mcp: true,
+                dryRun: false,
+                force: true,
+                remove: false,
+                agents: w.agents,
+                allowAdditive: true,
+            });
+            if (res.ok) {
+                io.stdout(`  재핀: ${w.target}\n`);
+                repinned++;
+            }
+            else {
+                io.stdout(`  실패: ${w.target}\n`);
+                failed++;
+            }
+        }
+        catch {
+            io.stdout(`  실패: ${w.target}\n`);
+            failed++;
+        }
+    }
+    io.stdout(`\nUpgraded to ${plan.latest}. 재핀 ${repinned} · 건너뜀 ${skipped} · 실패 ${failed}. 새 세션에서 훅/MCP 가 새 배선을 읽습니다.\n`);
+    io.stdout(`(개별 워크스페이스는 언제든 ${(0, npx_bin_1.npxBin)()} holmes-kit init --agent <…> --force 로 재배선할 수 있습니다.)\n`);
+    return 0;
+}

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

@@ -41,6 +41,7 @@ exports.readQueue = readQueue;
 exports.queueHint = queueHint;
 // @implements A-SPEC-244
 const node_crypto_1 = require("node:crypto");
+const npx_bin_1 = require("../project/npx-bin");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const screen_safe_1 = require("../cli/screen-safe");
@@ -281,13 +282,13 @@ function queueHint(root, req) {
         // template-owned margin; this producer, read by the operator AND relayed by the agent, never got
         // one. The first row keeps the template's own opening; the rest sit under the margin.
         return (0, screen_safe_1.wrapColumns)(`\n[보류 — 운영자 질문: ${(0, screen_safe_1.flattenField)(held.question ?? '(질문 없음)', 300)}] 게이트는 닫혀 있습니다.`
-            + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 npx holmes-kit approve 에서 내립니다.', 76, '  \u2502 ');
+            + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 내립니다.`, 76, '  \u2502 ');
     }
     const decided = state.decisions[id];
     const denialLine = decided?.event === 'denied'
         ? (0, screen_safe_1.wrapColumns)(`\n[거부됨${decided.reason ? `: ${(0, screen_safe_1.flattenField)(decided.reason, 300)}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`, 76, '  \u2502 ')
         : '';
     return enqueueApprovalRequest(root, req)
-        ? `${denialLine}\n[승인 대기 ${id}] 운영자: npx holmes-kit approve`
+        ? `${denialLine}\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`
         : denialLine;
 }

package/dist/holmes/hooks/session-start.js

@@ -76,6 +76,41 @@ function pkgVersion() {
         return '0.0.0';
     }
 }
+/**
+ * @implements A-SPEC-543.3
+ * If this workspace's holmes pin is behind the installed package, return a one-line NUDGE to run
+ * `holmes-kit upgrade`; otherwise return ''. Detection is zero-config (automatic every session), but
+ * the re-pin WRITE is NOT done here: `runInit({force:true})` is gated by a governance-wiring approval,
+ * so a silent session-start write would bypass it. The write stays the user's explicit choice via
+ * `upgrade`/`init --force`. Forward-drift + opt-out judgment is the pure `repinDecision`; every
+ * failure returns '' (fail-open — a banner is never a gate).
+ */
+function driftNudge(cwd, installed, env) {
+    try {
+        const { mcpLaunchVersion } = require('../cli/mcp-version');
+        const { repinDecision } = require('../update/upgrade-plan');
+        const { npxBin } = require('../project/npx-bin');
+        const mcpPath = path.join(cwd, '.mcp.json');
+        if (!fs.existsSync(mcpPath))
+            return '';
+        const mcp = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+        const entry = mcp.mcpServers?.['holmes-kit'];
+        if (!entry || typeof entry.command !== 'string' || !Array.isArray(entry.args))
+            return '';
+        const pinned = mcpLaunchVersion({ command: entry.command, args: entry.args }, (dir) => { try {
+            return String(JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version);
+        }
+        catch {
+            return undefined;
+        } });
+        if (!repinDecision({ pinned, installed, env }).repin)
+            return '';
+        return `\n[Holmes-Kit] this workspace is pinned to ${pinned}, but ${installed} is installed — run \`${npxBin()} holmes-kit upgrade\` to re-pin.`;
+    }
+    catch {
+        return '';
+    }
+}
 // CLI entry: read the hook JSON on stdin (unused beyond triggering), emit the banner, and — when
 // allowed — fire the detached refresh. Wrapped so any failure is an empty output + exit 0.
 if (require.main === module) {
@@ -91,6 +126,16 @@ if (require.main === module) {
                 readFile: (p) => fs.readFileSync(p, 'utf8'),
                 mode: detectInstallMode(pkgRootFromEntry()),
             });
+            // @implements A-SPEC-543.3 — self-healing re-pin: when this workspace's holmes pin is OLDER
+            // than the installed package, the user already chose to install; complete that choice by
+            // re-pinning the derived artifacts and telling the operator to restart. Forward-only, opt-out
+            // via HOLMES_NO_AUTO_REPIN, and FAIL-OPEN — any failure leaves the banner exactly as it was.
+            try {
+                const notice = driftNudge(process.cwd(), pkgVersion(), process.env);
+                if (notice)
+                    out.hookSpecificOutput.additionalContext += notice;
+            }
+            catch { /* the banner is never a gate */ }
             process.stdout.write(JSON.stringify({ hookSpecificOutput: out.hookSpecificOutput }));
             if (out.shouldRefresh) {
                 // Detached, unref'd child so the session start does not wait on the network. The refresh

package/dist/holmes/hooks/stop.js

@@ -49,6 +49,7 @@ exports.guardCountOrZero = guardCountOrZero;
 exports.readGuardCount = readGuardCount;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
+const npx_bin_1 = require("../project/npx-bin");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const json_state_1 = require("../project/json-state");
 const node_child_process_1 = require("node:child_process");
@@ -813,7 +814,7 @@ if (require.main === module) {
             else if (ackWaiting.length > 0) {
                 // @implements A-SPEC-247 — acknowledged, not clean: name what is waiting so the user sees
                 // the standing approval debt exactly once, and the agent knows the ball is not in its court.
-                process.stderr.write(`[Holmes-Kit] 승인 대기 중 — 오너 결정을 기다리는 항목: ${ackWaiting.join(', ')}. npx holmes-kit approve 에서 결재하십시오. (이 부채로는 재차단하지 않습니다)\n`);
+                process.stderr.write(`[Holmes-Kit] 승인 대기 중 — 오너 결정을 기다리는 항목: ${ackWaiting.join(', ')}. ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 결재하십시오. (이 부채로는 재차단하지 않습니다)\n`);
             }
             else if (guard.capped) {
                 process.stderr.write(`[Holmes-Kit] governance gate YIELDING after ${exports.MAX_CONSECUTIVE_BLOCKS} consecutive blocks — issues remain UNRESOLVED:\n${out.reason ?? ''}\n`);

package/dist/holmes/mcp/elicit-approval.js

@@ -1,5 +1,4 @@
 "use strict";
-// @implements A-SPEC-263.1
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_PRESENTATIONS = exports.ELICIT_TIMEOUT_MS = exports.ELICITABLE_KINDS = void 0;
 exports.elicitationDisabled = elicitationDisabled;
@@ -10,6 +9,8 @@ exports.buildDecisionForm = buildDecisionForm;
 exports.buildReasonForm = buildReasonForm;
 exports.runElicitFlow = runElicitFlow;
 exports.interpretElicitResult = interpretElicitResult;
+// @implements A-SPEC-263.1
+const npx_bin_1 = require("../project/npx-bin");
 /**
  * The decision comes INTO the session (REQ-263): an approval-shaped refusal (spec_approve without a
  * covering HOLMES_APPROVAL) becomes an in-session question when the client advertises the MCP
@@ -89,7 +90,7 @@ function classifyElicitError(e, timeoutMs = exports.ELICIT_TIMEOUT_MS) {
  * Template-owned text with no interpolated attacker data.
  */
 function expiredNotice(waitedMs) {
-    return `[세션 승인 다이얼로그 만료 — ${Math.round(waitedMs / 1000)}초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: npx holmes-kit approve. `;
+    return `[세션 승인 다이얼로그 만료 — ${Math.round(waitedMs / 1000)}초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: ${(0, npx_bin_1.npxBin)()} holmes-kit approve. `;
 }
 // FLATTEN attacker-influenced text (round-1): the model chooses spec titles and finding ids, and
 // interpolating them raw let a crafted title inject fake lines ("[시스템] … approve.") into the
@@ -111,7 +112,7 @@ function buildDecisionForm(req, attempt, timeoutMs) {
         // @implements A-SPEC-497.1 — the forewarning is the LAST line and template-owned: it survives a
         // cap-filling summary (appended after the caps) and tells the human, before the clock runs out,
         // where an undecided request goes and where the decision still lives.
-        message: `${redisplay}[Holmes-Kit 승인 요청] ${flat(req.kind, 40)} — ${flat(req.target, 80)}\n${flat(req.summary, 200)}\n승인(approve) / 거부(deny) / 질문(question) 을 선택하세요. 사유는 거부·질문을 고르면 이어서 묻습니다.\n⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: npx holmes-kit approve).`,
+        message: `${redisplay}[Holmes-Kit 승인 요청] ${flat(req.kind, 40)} — ${flat(req.target, 80)}\n${flat(req.summary, 200)}\n승인(approve) / 거부(deny) / 질문(question) 을 선택하세요. 사유는 거부·질문을 고르면 이어서 묻습니다.\n⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve).`,
         requestedSchema: {
             type: 'object',
             properties: {

package/dist/holmes/mcp/handlers.d.ts

@@ -237,6 +237,22 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         events: import("../governance/ledger-timeline").TimelineEntry[];
         reason?: undefined;
     }>;
+    rtm_dashboard(a: {
+        root?: string;
+        port?: number;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        url?: undefined;
+        running?: undefined;
+        census?: undefined;
+    } | {
+        ok: boolean;
+        url: string;
+        running: boolean;
+        census: import("../server/dashboard-launcher").DashboardCensus;
+        reason?: undefined;
+    }>;
     spec_approve(a: {
         root?: string;
         id: string;
@@ -458,7 +474,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         baselineRecorded?: string | undefined;
         scopeFallback?: "full" | undefined;
         tier: import("../rtm/test-scope").RegressionTier;
-        mode: "full" | "scoped" | "noop";
+        mode: "full" | "noop" | "scoped";
         passed: boolean;
         skipped: boolean;
         ranFiles: string[];

package/dist/holmes/mcp/handlers.js

@@ -45,6 +45,7 @@ exports.makeHandlers = makeHandlers;
 // @implements A-SPEC-269
 // @implements A-SPEC-267
 const fs = __importStar(require("node:fs"));
+const http = __importStar(require("node:http"));
 const assoc_arm_1 = require("../assoc/assoc-arm");
 // @implements A-SPEC-478 — the semantic tier runtime, resolved HERE (the async edge) and injected
 // into the sync analysis; the replay harness injects nothing, keeping every pin untouched.
@@ -213,6 +214,21 @@ class HandlerRefusal extends Error {
     constructor(message) { super(message); this.name = 'HandlerRefusal'; }
 }
 exports.HandlerRefusal = HandlerRefusal;
+/** GET a localhost JSON endpoint (used by rtm_dashboard to read the census off the server it launched). */
+function fetchJson(url) {
+    return new Promise((resolve, reject) => {
+        http.get(url, (res) => {
+            let data = '';
+            res.on('data', (c) => (data += c));
+            res.on('end', () => { try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            } });
+        }).on('error', reject);
+    });
+}
 /** Marker test that survives realm boundaries (jest's instanceof does not). */
 function isHandlerRefusal(e) {
     return !!e && typeof e === 'object' && e.holmesRefusal === true;
@@ -1322,6 +1338,24 @@ function makeRawHandlers(store, opts) {
             const events = fs.existsSync(dir) ? new ledger_store_1.FileLedgerStore(dir).loadAll() : [];
             return { ok: true, events: (0, ledger_timeline_1.timelineFrom)(events, a.id) };
         },
+        // @implements A-SPEC-545.3 — "show me the RTM dashboard" launches (idempotently) the server the
+        // agent would otherwise start by hand, and returns its URL plus an honesty census of what it shows.
+        async rtm_dashboard(a) {
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            try {
+                const { startDashboardServer } = await Promise.resolve().then(() => __importStar(require('../server/dashboard')));
+                const { ensureDashboard, dashboardCensus } = await Promise.resolve().then(() => __importStar(require('../server/dashboard-launcher')));
+                const launch = await ensureDashboard(dest.root, a.port, (opts) => startDashboardServer(opts));
+                const rtm = await fetchJson(`${launch.url}/api/rtm`);
+                const heatmap = await fetchJson(`${launch.url}/api/rtm/heatmap`);
+                return { ok: true, url: launch.url, running: launch.running, census: dashboardCensus(rtm, heatmap) };
+            }
+            catch (err) {
+                return { ok: false, reason: `대시보드 기동 실패: ${err?.message ?? String(err)}` };
+            }
+        },
         async spec_approve(a) {
             const approvalRaw = process.env.HOLMES_APPROVAL;
             let approval;