@holmes-lab/holmes-kit 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,7 +5,44 @@ 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.0] - 2026-09-04
+## [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
+
+- **Antigravity hooks: 0.10.0's `command`+`args` form regressed on the real launcher — reverted to an
+  unquoted single command string** (REQ-541). Field measurement on Windows/agy showed the hook
+  launcher **ignores `args`** and runs only the `command` string: 0.10.0's `command:"node"` +
+  `args:[path]` launched bare `node`, which evaluated the stdin JSON payload as code
+  (`SyntaxError: Unexpected token ':'`, exit 1) — every tool blocked. A second measurement had already
+  shown it keeps quotes **literal** (the pre-0.10.0 `node "<path>"` form died with MODULE_NOT_FOUND).
+  The only form the launcher runs is an unquoted single string, whitespace-split. `.agents/hooks.json`
+  now emits `command: "node <forward-slash path>"` (no quotes, no `args`); on win32 a path containing
+  a space is converted to its 8.3 short name, best-effort (lookup failure keeps the original path).
+  `doctor` continues to judge old (args) and new (string) wirings alike. **Re-run
+  `holmes-kit init --target <dir> --agent antigravity --force` after upgrading** — the fix changes
+  what init writes, not files already on disk. *Windows/agy real runtime and the 8.3 branch remain
+  unverified in this environment; validated by emitted shape + a naive-split execution simulation.*
 
 Governance UX tools for multi-agent round-trips and observability, a cross-harness approval fix, and
 an Antigravity portability fix. All additive and backward-compatible; existing behaviour is unchanged

package/README.md

@@ -19,6 +19,7 @@
 - 📋 **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`.
 - 🤖 **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 @@
-0d70dec-mtn1jk14
+2fb1cad-mtnmh3yo

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

@@ -49,6 +49,19 @@ export interface AgentFile {
     path: string;
     content: string;
 }
+/**
+ * Antigravity 훅 배선.
+ *
+ * 매처는 `*` 다. 좁히면 그 밖의 도구가 게이트를 지나가고, Antigravity 의 도구 목록은 우리가
+ * 통제하지 않는다 — 이름을 열거하는 순간 다음에 추가되는 도구가 무료 통행권을 얻는다.
+ * (Claude 배선이 `guardrail` 모드에서 좁은 매처를 쓰는 것과 다른 선택인데, 그쪽은 그 좁힘이
+ * 무엇을 뜻하는지 문서화된 모드 선택이고 여기는 기본 배선이기 때문이다.)
+ */
+/** `node <forward-slash path>` — unquoted, single string; the only form agy's launcher runs. */
+export declare function antigravityHookCommand(scriptPath: string): string;
+/** win32-only, best-effort: a spaced path becomes its 8.3 short name (no spaces); anything else — or
+ *  any lookup failure — returns the input unchanged. */
+export declare function shortPathIfSpaced(p: string): string;
 /**
  * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
  *

package/dist/holmes/cli/agents.js

@@ -34,11 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
+exports.antigravityHookCommand = antigravityHookCommand;
+exports.shortPathIfSpaced = shortPathIfSpaced;
 exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
 // @implements A-SPEC-442
 // @implements A-SPEC-193
 const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 const mcp_launcher_1 = require("./mcp-launcher");
 /**
  * 하네스별 배선물.
@@ -107,19 +110,37 @@ const mcpConfig = (packageRoot, specsDir, launcher) => {
  * (Claude 배선이 `guardrail` 모드에서 좁은 매처를 쓰는 것과 다른 선택인데, 그쪽은 그 좁힘이
  * 무엇을 뜻하는지 문서화된 모드 선택이고 여기는 기본 배선이기 때문이다.)
  */
-// @implements A-SPEC-539.1
-// agy's hook launcher tokenizes the `command` string on whitespace and does NOT honor quotes, so an
-// earlier quoted `node "<path>"` (A-SPEC-193 §2b-2) still broke on a path with spaces: measured on a
-// Windows machine whose Node lives at `C:\Program Files\nodejs`, reported from agy 2026-09-04 — the
-// launcher split `node "C:\Program Files\...` at the space, node took `"C:\Program` for a module
-// (MODULE_NOT_FOUND), and the gate loaded not at all (silently off). Passing the script path as an
-// `args` ELEMENT — the same array form mcp_config already uses — sidesteps tokenization entirely, on
-// every platform. This supersedes the quoted-string form for the antigravity wiring; quoting only
-// ever helped launchers that honor quotes, which agy's does not.
+// @implements A-SPEC-541.1
+// Two field measurements (both 2026-09-04, Windows/agy) pinned the launcher's real contract, each by
+// killing one prior form:
+//   · `node "C:\...js"` (quoted, A-SPEC-193 §2b-2) → the quotes stayed LITERAL and node got
+//     `"C:\...` as a module path → MODULE_NOT_FOUND. The launcher does not honor quotes.
+//   · `command:'node', args:[path]` (A-SPEC-539.1 / 0.10.0) → the launcher IGNORED `args` and ran
+//     bare `node`, which took the stdin JSON payload as code → `SyntaxError: Unexpected token ':'`
+//     (exit 1), every tool blocked. The launcher executes only the single `command` string.
+// So the only form it can run is an UNQUOTED single command string, whitespace-split — which means
+// the path itself must carry no space. Forward slashes (node accepts them on Windows) avoid JSON
+// backslash escaping; a spaced path is converted to its 8.3 short name on win32, best-effort.
+/** `node <forward-slash path>` — unquoted, single string; the only form agy's launcher runs. */
+function antigravityHookCommand(scriptPath) {
+    return `node ${scriptPath.replace(/\\/g, '/')}`;
+}
+/** win32-only, best-effort: a spaced path becomes its 8.3 short name (no spaces); anything else — or
+ *  any lookup failure — returns the input unchanged. */
+function shortPathIfSpaced(p) {
+    if (process.platform !== 'win32' || !p.includes(' '))
+        return p;
+    try {
+        const out = (0, node_child_process_1.execFileSync)('cmd', ['/d', '/c', `for %I in ("${p}") do @echo %~sI`], { encoding: 'utf8' }).trim();
+        return out !== '' && !out.includes(' ') ? out : p;
+    }
+    catch {
+        return p;
+    }
+}
 const antigravityHookEntry = (packageRoot, script) => ({
     type: 'command',
-    command: 'node',
-    args: [path.join(packageRoot, 'bin', script)],
+    command: antigravityHookCommand(shortPathIfSpaced(path.join(packageRoot, 'bin', script))),
     timeout: 30,
 });
 /**

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,7 @@ 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} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, `${(0, npx_bin_1.npxBin)()} @holmes-lab/holmes-kit@latest init 을 다시 실행해 .mcp.json 을 최신 버전으로 재배선하십시오 (전역 -g 업그레이드 불필요).`);
                 }
                 else if (verdict === 'match') {
                     add('mcp server version', 'PASS', `MCP 서버 버전 ${launch} 가 이 CLI 와 일치합니다`);
@@ -810,7 +811,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 +1281,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

@@ -458,7 +458,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/project/npx-bin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @implements A-SPEC-542.1
+ * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
+ * platform of the machine whose terminal reads the emitted hint. Field-measured 2026-09-05 (codex on
+ * Windows): a locked-down PowerShell execution policy blocks the `npx` call because the `.ps1` shim
+ * is resolved first (PSSecurityException); `npx.cmd` runs. Everywhere else `npx` is correct, so every
+ * non-win32 emission stays byte-identical. Only the exact 'win32' token switches — a typo or unknown
+ * platform must never flip a POSIX hint to a Windows-only form.
+ */
+export declare function npxBin(platform?: string): string;

package/dist/holmes/project/npx-bin.js

@@ -0,0 +1,16 @@
+"use strict";
+// @implements A-SPEC-542.1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.npxBin = npxBin;
+/**
+ * @implements A-SPEC-542.1
+ * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
+ * platform of the machine whose terminal reads the emitted hint. Field-measured 2026-09-05 (codex on
+ * Windows): a locked-down PowerShell execution policy blocks the `npx` call because the `.ps1` shim
+ * is resolved first (PSSecurityException); `npx.cmd` runs. Everywhere else `npx` is correct, so every
+ * non-win32 emission stays byte-identical. Only the exact 'win32' token switches — a typo or unknown
+ * platform must never flip a POSIX hint to a Windows-only form.
+ */
+function npxBin(platform = process.platform) {
+    return platform === 'win32' ? 'npx.cmd' : 'npx';
+}

package/dist/holmes/update/upgrade-plan.d.ts

@@ -0,0 +1,43 @@
+import { InstallMode } from './update-notice';
+import { Registry, WorkspaceEntry } from './workspaces';
+/** What `holmes-kit upgrade` would do — pure facts; wording and refusals belong to the CLI. */
+export type UpgradePlan = {
+    kind: 'noop';
+    reason: string;
+} | {
+    kind: 'run';
+    current: string;
+    latest: string;
+    installMode: InstallMode;
+    repins: WorkspaceEntry[];
+};
+/**
+ * @implements A-SPEC-543.2
+ * Pure: decide whether an upgrade runs and what it touches. Unknown latest is a noop (silence is not
+ * an install), and so is an equal or OLDER latest — upgrade never plans a downgrade. A 'run' plan
+ * carries the registry's workspaces verbatim as the re-pin list; an empty list is still a valid run
+ * (install-only, first machine).
+ */
+export declare function planUpgrade(a: {
+    current: string;
+    latest: string | null;
+    registry: Registry;
+    installMode: InstallMode;
+}): UpgradePlan;
+/** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
+export declare const NO_AUTO_REPIN_ENV = "HOLMES_NO_AUTO_REPIN";
+/**
+ * @implements A-SPEC-543.3
+ * Pure: should a session auto re-pin this workspace's derived artifacts? Only when the pin is a real
+ * version, the installed package is strictly NEWER (forward-only — never a downgrade or a match), and
+ * the operator has not opted out. The install was the user's explicit choice; this completes it at
+ * the workspace level. A decision always says why.
+ */
+export declare function repinDecision(a: {
+    pinned: string | null;
+    installed: string;
+    env: NodeJS.ProcessEnv;
+}): {
+    repin: boolean;
+    reason: string;
+};

package/dist/holmes/update/upgrade-plan.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_AUTO_REPIN_ENV = void 0;
+exports.planUpgrade = planUpgrade;
+exports.repinDecision = repinDecision;
+// @implements A-SPEC-543.2
+const update_notice_1 = require("./update-notice");
+/**
+ * @implements A-SPEC-543.2
+ * Pure: decide whether an upgrade runs and what it touches. Unknown latest is a noop (silence is not
+ * an install), and so is an equal or OLDER latest — upgrade never plans a downgrade. A 'run' plan
+ * carries the registry's workspaces verbatim as the re-pin list; an empty list is still a valid run
+ * (install-only, first machine).
+ */
+function planUpgrade(a) {
+    if (a.latest === null) {
+        return { kind: 'noop', reason: 'latest version unknown (registry unreachable and no cache) — nothing to plan' };
+    }
+    if ((0, update_notice_1.compareSemver)(a.latest, a.current) <= 0) {
+        return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})` };
+    }
+    return { kind: 'run', current: a.current, latest: a.latest, installMode: a.installMode, repins: a.registry.workspaces };
+}
+/** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
+exports.NO_AUTO_REPIN_ENV = 'HOLMES_NO_AUTO_REPIN';
+/**
+ * @implements A-SPEC-543.3
+ * Pure: should a session auto re-pin this workspace's derived artifacts? Only when the pin is a real
+ * version, the installed package is strictly NEWER (forward-only — never a downgrade or a match), and
+ * the operator has not opted out. The install was the user's explicit choice; this completes it at
+ * the workspace level. A decision always says why.
+ */
+function repinDecision(a) {
+    const optOut = a.env[exports.NO_AUTO_REPIN_ENV];
+    if (typeof optOut === 'string' && optOut !== '') {
+        return { repin: false, reason: `${exports.NO_AUTO_REPIN_ENV} set — auto re-pin disabled` };
+    }
+    if (a.pinned === null) {
+        return { repin: false, reason: 'workspace pin unreadable — no re-pin on an unknown pin' };
+    }
+    if ((0, update_notice_1.compareSemver)(a.installed, a.pinned) > 0) {
+        return { repin: true, reason: `installed ${a.installed} is newer than pin ${a.pinned} — re-pin forward` };
+    }
+    return { repin: false, reason: `pin ${a.pinned} is up to date with installed ${a.installed} — no re-pin` };
+}

package/dist/holmes/update/workspaces.d.ts

@@ -0,0 +1,35 @@
+/** One wired workspace, as the registry answers "what is wired NOW" (not a history). */
+export interface WorkspaceEntry {
+    target: string;
+    agents: string[];
+    version: string;
+    ts: string;
+}
+export interface Registry {
+    version: 1;
+    workspaces: WorkspaceEntry[];
+}
+export declare const EMPTY_REGISTRY: Registry;
+/**
+ * @implements A-SPEC-543.1
+ * Parse the registry file's content. `null` (absent), broken JSON, or a wrong shape all yield the
+ * empty registry — best-effort by design: a broken registry restarts empty rather than ever breaking
+ * wiring (the recorder that feeds it is swallowed too).
+ */
+export declare function readRegistry(raw: string | null): Registry;
+/**
+ * @implements A-SPEC-543.1
+ * Pure: replace the entry whose `target` matches (path-identity dedup — the registry answers what is
+ * wired NOW), append otherwise, preserve order, never mutate the inputs.
+ */
+export declare function mergeWorkspaceEntry(reg: Registry, entry: WorkspaceEntry): Registry;
+/**
+ * @implements A-SPEC-543.1
+ * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
+ * swallowed (returns false) — a registry problem must never fail the init that feeds it.
+ */
+export declare function recordWorkspace(home: string, entry: WorkspaceEntry, io?: {
+    read: (p: string) => string;
+    write: (p: string, c: string) => void;
+    mkdir: (p: string) => void;
+}): boolean;

package/dist/holmes/update/workspaces.js

@@ -0,0 +1,109 @@
+"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.EMPTY_REGISTRY = void 0;
+exports.readRegistry = readRegistry;
+exports.mergeWorkspaceEntry = mergeWorkspaceEntry;
+exports.recordWorkspace = recordWorkspace;
+// @implements A-SPEC-543.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.EMPTY_REGISTRY = { version: 1, workspaces: [] };
+/**
+ * @implements A-SPEC-543.1
+ * Parse the registry file's content. `null` (absent), broken JSON, or a wrong shape all yield the
+ * empty registry — best-effort by design: a broken registry restarts empty rather than ever breaking
+ * wiring (the recorder that feeds it is swallowed too).
+ */
+function readRegistry(raw) {
+    if (raw === null)
+        return { version: 1, workspaces: [] };
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed?.workspaces))
+            return { version: 1, workspaces: [] };
+        const workspaces = parsed.workspaces.filter((w) => !!w && typeof w.target === 'string'
+            && Array.isArray(w.agents)
+            && typeof w.version === 'string'
+            && typeof w.ts === 'string');
+        return { version: 1, workspaces };
+    }
+    catch {
+        return { version: 1, workspaces: [] };
+    }
+}
+/**
+ * @implements A-SPEC-543.1
+ * Pure: replace the entry whose `target` matches (path-identity dedup — the registry answers what is
+ * wired NOW), append otherwise, preserve order, never mutate the inputs.
+ */
+function mergeWorkspaceEntry(reg, entry) {
+    const replaced = reg.workspaces.some((w) => w.target === entry.target);
+    return {
+        version: 1,
+        workspaces: replaced
+            ? reg.workspaces.map((w) => (w.target === entry.target ? entry : w))
+            : [...reg.workspaces, entry],
+    };
+}
+/**
+ * @implements A-SPEC-543.1
+ * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
+ * swallowed (returns false) — a registry problem must never fail the init that feeds it.
+ */
+function recordWorkspace(home, entry, io = {
+    read: (p) => fs.readFileSync(p, 'utf8'),
+    write: (p, c) => fs.writeFileSync(p, c),
+    mkdir: (p) => { fs.mkdirSync(p, { recursive: true }); },
+}) {
+    try {
+        const dir = path.join(home, '.holmes');
+        const file = path.join(dir, 'workspaces.json');
+        let raw = null;
+        try {
+            raw = io.read(file);
+        }
+        catch {
+            raw = null;
+        }
+        const merged = mergeWorkspaceEntry(readRegistry(raw), entry);
+        io.mkdir(dir);
+        io.write(file, `${JSON.stringify(merged, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",