@mindrian_os/cli 2.0.0-beta.35 → 2.0.0-beta.37

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mos",
   "description": "MindrianOS -- Your AI innovation co-founder. Larry thinks with you through PWS methodology, builds your Data Room as you explore, and chains frameworks intelligently. Install and go.",
-  "version": "2.0.0-beta.35",
+  "version": "2.0.0-beta.37",
   "author": {
     "name": "Jonathan Sagir",
     "url": "https://mindrian-os.com"

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [2.0.0-beta.37] - 2026-09-11
+
+### Fixed - hooks.json no longer prints an unknown-keys warning at every session start (quick task 260911-juq)
+
+- Claude Code 2.1.268 printed, on every session start on every surface that loads the
+  plugin manifest: `hooks.json: unknown keys "_mcpFirst198Migrated",
+  "_firstInstallRouterOrdering" ignored`. Both keys were our own build metadata, never
+  hook configuration, so the loader was correct to ignore them and correct to complain.
+  They now live in `data/hooks-markers.json`, and `hooks/hooks.json`'s top level is
+  exactly one key, `hooks`. No matcher, command, or timeout inside the hooks block
+  changed; the block is byte-identical to the pre-fix file.
+- New guard test `tests/test-quick-260911-juq-hooks-json-top-level.cjs`, registered as
+  a leg of `bash tests/run-all-198.sh`, keeps both halves of this fix honest going
+  forward: the top level cannot silently grow a stray key again, and the sidecar path
+  cannot silently go dead and make the D-06 adapter budget vacuous.
+
+### Added - a per-install opaque header lets Theo bucket without learning who you are (quick task 260911-iko)
+
+- Every Brain call now carries `x-theo-install-id`: a 32-character lowercase hex value
+  minted once from `crypto.randomBytes(16)`, stored at `~/.mindrian/theo-install-id.json`
+  (mode 0600) beside the pre-warm marker. It rides both of `callTool`'s wire requests
+  (the session initialize and the tools/call), and is simply omitted, never an error,
+  when it cannot be minted or read. This lets Theo tell one install calling twice from
+  two installs calling once, with nothing else about the install attached to it.
+- `node scripts/doctor.cjs --reset-install-id` rotates the id on demand, prints exactly
+  `install id rotated`, and never prints the value. The doctor's Brain-smoke layer 0
+  also grows an `install_id_present` boolean, reported the same way: presence only,
+  never the value.
+- Canon Part 8 position, stated once and reproduced in full at
+  `docs/THEO-INSTALL-ID.md`: the id is an opaque CSPRNG handle, never derived from
+  identity, never logged, never printed in full.
+
 ## [2.0.0-beta.35] - 2026-09-11
 
 ### Added - doctor sees the Tier 0 shadow, Theo's node floor stops rubber-stamping (quick task 260911-axz)

package/commands/doctor.md

@@ -2,7 +2,7 @@
 name: doctor
 description: "Diagnose and optionally repair MindrianOS install: install-cache drift, sentinel gaps, active-room guard, surface-verification, ROOM.md drift, UI compliance, statusline visibility, Brain smoke, and a paste-ready command-registration bug report for Anthropic"
 help_jtbd: "Diagnose and optionally repair an off-feeling install."
-argument-hint: "[--fix] [--all] [--cascade-rooms] [--graph-derive-health] [--heal-room] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--card-fire-health] [--install-state] [--stale-first-touch] [--deprecated-usage] [--brain-smoke] [--eureka-smoke] [--drift] [--report-registration-bug] [--acceptance] [--pre-tag] [--pre-flight] [--dogfood-acceptance] [--claims] [--check-rs-engine] [--post-update] [--bind-check] [--simulate-write] [--scan-commands] [--scan-scripts] [--light-npx] [--dry-run] [--json]"
+argument-hint: "[--fix] [--all] [--cascade-rooms] [--graph-derive-health] [--heal-room] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--card-fire-health] [--install-state] [--stale-first-touch] [--deprecated-usage] [--brain-smoke] [--eureka-smoke] [--drift] [--report-registration-bug] [--reset-install-id] [--acceptance] [--pre-tag] [--pre-flight] [--dogfood-acceptance] [--claims] [--check-rs-engine] [--post-update] [--bind-check] [--simulate-write] [--scan-commands] [--scan-scripts] [--light-npx] [--dry-run] [--json]"
 body_shape: E (Action Report)
 hitl_shape: "F.0"
 hitl_why: "It surfaces one diagnosed repair for a single approve-or-defer decision."
@@ -125,6 +125,7 @@ These siblings own their own exit contracts and are not part of the class-flag d
 - `--dogfood-acceptance` -> the Canon Part 6 dog-fooding acceptance pass.
 - `--claims` -> the claims-verification leg.
 - `--check-rs-engine` -> the reason-select engine probe (NOT part of `--all`).
+- `--reset-install-id` -> rotates the opaque per-install bucket key the plugin sends to Theo, prints `install id rotated`, never prints the value, and always exits 0. Full contract: `docs/THEO-INSTALL-ID.md`.
 - `--post-update` -> the post-`claude plugin update` confirmation pass.
 - `--bind-check <roomDir>` -> a lightweight LOCAL room-health check run at BIND-TIME (never per-turn, never a Brain call). NEVER-BLOCK: an unhealthy room degrades to an advisory and STILL exits 0.
 - `--light-npx` -> the lighter npx-roundtrip variant for `--acceptance`.

package/data/hooks-markers.json

@@ -0,0 +1,25 @@
+{
+  "_mcpFirst198Migrated": {
+    "_note": "Phase 198-08 (SPEC-5, D-05/D-06) migration markers, extended by Phase 198-09 (D-05 final wave). Each entry names a hook script that now dispatches to lib/mcp/adapter-client.cjs behind MINDRIAN_MCP_FIRST ('cli' or 'all') instead of running its business logic locally; flag OFF (unset/empty, the default) keeps the pre-migration legacy behavior byte-identical (SPEC-7). This is metadata for tests/test-198-adapter-budget.test.cjs's import-audit + line-count budget (D-06) to enumerate -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key in hooks/hooks.json. Migration order is D-05: statusline + SessionStart FIRST (198-08); Stop-gate enforcement LAST (198-09, this entry), only after server-side gate dedup + relevance existed (lib/mcp/gate-dedup.cjs, Task 1 of 198-09). scripts/check-card-fire.cjs is NOT listed here -- it stays a separate Stop hook entry that no-ops under the flag (deferring to on-stop's daemon-backed decision), never itself migrated to a thin adapter shape.",
+    "surfaces": [
+      {
+        "script": "scripts/statusline-mos-dispatch",
+        "tool": "status_read",
+        "note": "Statusline segment (spend/cap from day one). Flag ON wakes the daemon and queries status_read; flag OFF execs the legacy scripts/statusline-mos exactly as shipped."
+      },
+      {
+        "script": "scripts/sessionstart-coordinator.cjs",
+        "tool": "room_state_bound,status_read",
+        "note": "SessionStart binding + status segments. Flag ON wakes the daemon and queries room_state_bound + status_read (runThinAdapter); flag OFF runs the full 11-contributor runAll() exactly as shipped."
+      },
+      {
+        "script": "scripts/on-stop",
+        "tool": "stop_gate_check",
+        "note": "Stop-gate enforcement + business close-out (D-05 final wave). Flag ON wakes the daemon and queries stop_gate_check (lib/mcp/tools/stop-gate.cjs -> lib/mcp/stop-gate-handler.cjs -- gate-dedup + relevance gate the fire decision, the shipped check-card-fire.cjs predicate is the final authority, the daemon owns STATE.md/memory-lifecycle/minto-debouncer/folder-memory close-out); flag OFF runs the full legacy body exactly as shipped."
+      }
+    ]
+  },
+  "_firstInstallRouterOrdering": {
+    "_note": "Phase 267.2-06 (HOOK-08). scripts/first-install-router.cjs is registered in the UserPromptSubmit chain immediately AFTER scripts/mva-detect.cjs and before scripts/brain-derivation-drain.cjs. This is metadata for a human reader (and any future drift test) -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key in hooks/hooks.json. ORDERING IS LOAD BEARING: the router consumes the pending MVA state that mva-detect.cjs writes on the same turn, so running before it would read a stale or absent state. Do not reorder these two entries without re-checking this dependency."
+  }
+}

package/hooks/hooks.json

@@ -1,27 +1,4 @@
 {
-  "_mcpFirst198Migrated": {
-    "_note": "Phase 198-08 (SPEC-5, D-05/D-06) migration markers, extended by Phase 198-09 (D-05 final wave). Each entry names a hook script that now dispatches to lib/mcp/adapter-client.cjs behind MINDRIAN_MCP_FIRST ('cli' or 'all') instead of running its business logic locally; flag OFF (unset/empty, the default) keeps the pre-migration legacy behavior byte-identical (SPEC-7). This is metadata for tests/test-198-adapter-budget.test.cjs's import-audit + line-count budget (D-06) to enumerate -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key below. Migration order is D-05: statusline + SessionStart FIRST (198-08); Stop-gate enforcement LAST (198-09, this entry), only after server-side gate dedup + relevance existed (lib/mcp/gate-dedup.cjs, Task 1 of 198-09). scripts/check-card-fire.cjs is NOT listed here -- it stays a separate Stop hook entry that no-ops under the flag (deferring to on-stop's daemon-backed decision), never itself migrated to a thin adapter shape.",
-    "surfaces": [
-      {
-        "script": "scripts/statusline-mos-dispatch",
-        "tool": "status_read",
-        "note": "Statusline segment (spend/cap from day one). Flag ON wakes the daemon and queries status_read; flag OFF execs the legacy scripts/statusline-mos exactly as shipped."
-      },
-      {
-        "script": "scripts/sessionstart-coordinator.cjs",
-        "tool": "room_state_bound,status_read",
-        "note": "SessionStart binding + status segments. Flag ON wakes the daemon and queries room_state_bound + status_read (runThinAdapter); flag OFF runs the full 11-contributor runAll() exactly as shipped."
-      },
-      {
-        "script": "scripts/on-stop",
-        "tool": "stop_gate_check",
-        "note": "Stop-gate enforcement + business close-out (D-05 final wave). Flag ON wakes the daemon and queries stop_gate_check (lib/mcp/tools/stop-gate.cjs -> lib/mcp/stop-gate-handler.cjs -- gate-dedup + relevance gate the fire decision, the shipped check-card-fire.cjs predicate is the final authority, the daemon owns STATE.md/memory-lifecycle/minto-debouncer/folder-memory close-out); flag OFF runs the full legacy body exactly as shipped."
-      }
-    ]
-  },
-  "_firstInstallRouterOrdering": {
-    "_note": "Phase 267.2-06 (HOOK-08). scripts/first-install-router.cjs is registered in the UserPromptSubmit chain immediately AFTER scripts/mva-detect.cjs and before scripts/brain-derivation-drain.cjs. This is metadata for a human reader (and any future drift test) -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key below. ORDERING IS LOAD BEARING: the router consumes the pending MVA state that mva-detect.cjs writes on the same turn, so running before it would read a stale or absent state. Do not reorder these two entries without re-checking this dependency."
-  },
   "hooks": {
     "SessionStart": [
       {

package/lib/core/brain-client.cjs

@@ -305,6 +305,34 @@ function isAvailable() {
   return !!getApiKey();
 }
 
+// Quick 260911-iko (D-04): the opaque per-install header, spread into both
+// of callTool's wire requests. A per-process memo is correct here (mirrors
+// the getApiKey() memo idiom above) and must be commented as such: the id
+// only changes on reinstall or on a `doctor --reset-install-id` run, and
+// both of those happen in a DIFFERENT process, so re-reading it on every
+// call would buy nothing. Wrapped in its own try/catch so a missing or
+// broken install-id module can never take a Brain call down -- the header
+// is a bucket key, never a requirement (D-04: omitted, never an error).
+//
+// This helper never touches the Part 8 egress belt (classify() at
+// callTool's egress-guard call below): that belt classifies `args`, and
+// headers are not payload. The install id never enters `args` and must
+// never be added to them.
+let _memoizedInstallIdHeaders = null;
+function _installIdHeaders() {
+  if (_memoizedInstallIdHeaders) return _memoizedInstallIdHeaders;
+  try {
+    const installIdMod = require('./install-id.cjs');
+    const id = installIdMod.getInstallId();
+    _memoizedInstallIdHeaders = (typeof id === 'string')
+      ? { [installIdMod.installIdHeaderName]: id }
+      : {};
+  } catch (_e) {
+    _memoizedInstallIdHeaders = {};
+  }
+  return _memoizedInstallIdHeaders;
+}
+
 // ---------------------------------------------------------------------------
 // Phase 250-04 (HONEST-03, SEED-011 Option A) -- per-install silent
 // registration. Design doc: docs/BRAIN-IDENTITY-DESIGN.md.
@@ -350,6 +378,12 @@ async function _tryAutoRegister() {
 
   try {
     const installId = crypto.randomUUID();
+    // Quick 260911-iko: the x-theo-install-id header does NOT ride here.
+    // D-04 names callTool's two header blocks only; registration is a
+    // different endpoint with its own contract, and it runs before there is
+    // an established Brain session to bucket. Adding it here would be a
+    // change to Theo's registration surface, which D-06 says must be
+    // announced to Theo first -- a deliberate exclusion, not a miss.
     const res = await fetch(`${BRAIN_URL}/register`, {
       method: 'POST',
       signal: AbortSignal.timeout(BRAIN_REQUEST_TIMEOUT_MS),
@@ -456,6 +490,7 @@ async function _ensureSession(apiKey) {
         'Content-Type': 'application/json',
         'Accept': 'application/json, text/event-stream',
         'Authorization': `Bearer ${apiKey}`,
+        ..._installIdHeaders(),
       },
       body: JSON.stringify({
         jsonrpc: '2.0',
@@ -675,6 +710,7 @@ async function callTool(toolName, args) {
             'Content-Type': 'application/json',
             'Accept': 'application/json, text/event-stream',
             'Authorization': `Bearer ${key}`,
+            ..._installIdHeaders(),
           },
           body: JSON.stringify({
             jsonrpc: '2.0',

package/lib/core/doctor/class-m-brain-smoke.cjs

@@ -202,6 +202,14 @@ async function _runLayer(_name, fn) {
 //     `instanceUri`, `quarantineCode`, and `serverAgent` are never copied
 //     (T-axz-02).
 //
+// (d) install_id_present (Quick 260911-iko, T-iko-02): whether the opaque
+//     per-install id (lib/core/install-id.cjs) can be read from the state
+//     dir. This row carries the BOOLEAN ONLY and NEVER the id value -- it
+//     reads through peekInstallId, which never mints, so running doctor
+//     can never create the id it is reporting on. A missing id is
+//     information, never a failure: it never changes the verdict below,
+//     exactly as the origin and health halves already do not.
+//
 // Verdict: ok is false if and only if at least one mindrian-brain shadow
 // entry was found. The origin and health halves are information, never the
 // verdict, exactly as L6 treats canon/override as information separate from
@@ -221,6 +229,19 @@ async function _layer0(opts) {
 
   const payload = { resolved_origin: resolved_origin, is_theo: is_theo, override: override, shadows: shadows };
 
+  // Quick 260911-iko (D-03, T-iko-02): install_id_present, a BOOLEAN ONLY,
+  // never the value. Uses peekInstallId, NOT getInstallId, so a diagnostic
+  // run never mints the thing it is reporting on. A missing install id is
+  // information, never a failure -- this never changes the verdict below,
+  // exactly as the origin and health halves already are.
+  try {
+    const installIdFn = opts.mockInstallId
+      || (() => require('../install-id.cjs').peekInstallId());
+    payload.install_id_present = typeof installIdFn() === 'string';
+  } catch (_e) {
+    payload.install_id_present = false;
+  }
+
   const theoHealthFn = opts.mockTheoHealth
     || (async () => require('../brain-client.cjs').callTool('theo_health', {}));
   try {
@@ -533,6 +554,7 @@ async function _layer6(opts) {
  *   mockQuery?:           function,
  *   mockScopedServers?:   function,
  *   mockTheoHealth?:      function,
+ *   mockInstallId?:       function,
  *   claudeConfigPath?:    string,
  *   projectDir?:          string,
  * }} [opts]

package/lib/core/install-id.cjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Quick 260911-iko (D-01 through D-08) -- the opaque per-install id Theo
+ * uses to bucket "one install calling twice" apart from "two installs
+ * calling once", without ever learning who the install belongs to.
+ *
+ * WHAT IT IS FOR: Theo needs a bucket key. Today it has none, and every
+ * substitute it could reach for instead (a key, a hostname, an account id)
+ * would be user data crossing the Brain boundary, which Canon Part 8
+ * forbids. A 128-bit coin flip minted locally and sent as a header is the
+ * one answer that gives Theo the bucketing and gives the user nothing to
+ * leak.
+ *
+ * WHY A CSPRNG VALUE IS A GENERIC HANDLE, NOT USER DATA (D-07): the value
+ * is `crypto.randomBytes(16)`, 16 bytes straight out of the platform CSPRNG
+ * with NO INPUT at all. There is no function from the user, the machine,
+ * the account, the room, the path, the hostname, or the Brain key to this
+ * value, so there is nothing to invert. A hash of an identifier would still
+ * BE that identifier wearing a hat: the same user on two installs would
+ * hash to the same bucket, and anyone holding the identifier could confirm
+ * a match. A random 128-bit value cannot do either. It carries exactly one
+ * bit of meaning: "the caller that sent this header before is the caller
+ * sending it now."
+ *
+ * THE EXPLICIT FORBIDDEN LIST -- this module must NEVER derive the id from:
+ *   - os.hostname()
+ *   - os.userInfo() / os.userInfo().username
+ *   - process.env.USER / process.env.USERNAME / process.env.LOGNAME
+ *   - process.cwd()
+ *   - a home directory path
+ *   - a MAC address or machine id
+ *   - an account id or room name
+ *   - the Brain key (process.env.MINDRIAN_BRAIN_KEY, resolve-brain-key.cjs)
+ *   - a hash of any of the above (crypto's createHash)
+ * tests/test-339-install-id-header.cjs arm 9 scans THIS FILE with comments
+ * stripped and fails the suite if any of those tokens appears outside this
+ * prose -- so this comment is safe and LOAD-BEARING, and must stay.
+ *
+ * NEVER LOGGED, NEVER PRINTED IN FULL (D-03): doctor reports presence only,
+ * and on rotation the word "rotated" -- never the value. The id itself is
+ * the user's own to read from their own file.
+ *
+ * Posture copied deliberately from lib/core/brain-prewarm.cjs: this module
+ * NEVER throws to its caller and NEVER writes to stdout, because it can run
+ * inside an MCP stdio process where a stray stdout byte corrupts the
+ * JSON-RPC transport. A single stderr line, guarded by MINDRIAN_DEBUG, is
+ * permitted, and it prints the FILE PATH or an error message only, never
+ * the id value.
+ *
+ * CJS only, no new dependencies: require only fs, path, os, crypto.
+ * No em-dashes (hyphens only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const INSTALL_ID_HEADER_NAME = 'x-theo-install-id';
+const ID_SHAPE_RE = /^[a-f0-9]{32}$/;
+const FILE_NAME = 'theo-install-id.json';
+
+const debugLog = (msg) => {
+  if (!process.env.MINDRIAN_DEBUG) return;
+  try {
+    process.stderr.write('[install-id] ' + msg + '\n');
+  } catch (_e) {
+    // swallow -- this function must never throw
+  }
+};
+
+/**
+ * installIdPath(homeDir) -- the on-disk location of the id file.
+ *
+ * Deliberately duplicates the SAME resolution expression as
+ * lib/core/brain-prewarm.cjs::markerPath rather than extracting a shared
+ * helper -- two call sites is below the threshold where coupling two
+ * never-throws modules beats a duplicated two-line expression. Safety net:
+ * tests/test-339-install-id-header.cjs arm 10 asserts both modules resolve
+ * to the same directory (the drift guard). Extraction trigger: a THIRD
+ * call site.
+ *
+ * @param {string} [homeDir] defaults to MINDRIAN_HOME or ~/.mindrian
+ * @returns {string}
+ */
+function installIdPath(homeDir) {
+  const home = homeDir || process.env.MINDRIAN_HOME || path.join(os.homedir(), '.mindrian');
+  return path.join(home, FILE_NAME);
+}
+
+/**
+ * Read the id file and return the id string, or null on any failure, any
+ * shape mismatch, or a fresh homeDir with no file yet. Never mints, never
+ * writes, never throws.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function _readValidId(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.id === 'string' && ID_SHAPE_RE.test(parsed.id)) {
+      return parsed.id;
+    }
+    return null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * peekInstallId({ homeDir }) -- read-only. Returns the id when the file
+ * holds a valid one, otherwise null. NEVER mints, NEVER writes, NEVER
+ * throws. This exists so the doctor can report presence without a
+ * diagnostic run silently creating the thing it is diagnosing.
+ * @param {{homeDir?: string}} [opts]
+ * @returns {string|null}
+ */
+function peekInstallId(opts) {
+  const o = opts || {};
+  try {
+    return _readValidId(installIdPath(o.homeDir));
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Atomically write { id, minted_at } to installIdPath(homeDir), mode 0600.
+ * Every fs operation is wrapped; any failure returns false and leaves no
+ * temp file behind.
+ * @param {string} homeDir
+ * @param {string} id
+ * @returns {boolean}
+ */
+function _atomicWrite(homeDir, id) {
+  const finalPath = installIdPath(homeDir);
+  const dir = path.dirname(finalPath);
+  const tmpPath = path.join(
+    dir,
+    FILE_NAME + '.tmp-' + process.pid + '-' + crypto.randomBytes(3).toString('hex')
+  );
+  const body = { id: id, minted_at: new Date().toISOString() };
+  const json = JSON.stringify(body);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(tmpPath, json, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmpPath, finalPath);
+    if (process.platform !== 'win32') {
+      try {
+        fs.chmodSync(finalPath, 0o600);
+      } catch (_e) {
+        // belt only -- the write-time mode already applied it.
+      }
+    }
+    debugLog('id written: ' + finalPath);
+    return true;
+  } catch (e) {
+    debugLog('id write failed: ' + (e && e.message ? e.message : String(e)));
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (_e) {
+      // no temp file to clean up, or already gone.
+    }
+    return false;
+  }
+}
+
+/**
+ * getInstallId({ homeDir }) -- mint-once. peekInstallId first; on a hit
+ * return it. On a miss, mint a fresh 32-hex id from crypto.randomBytes(16),
+ * write it atomically, then RE-CHECK for a concurrent winner: two processes
+ * making their first Brain call at the same instant must converge on ONE
+ * bucket, not split it. Every failure returns null rather than throwing.
+ *
+ * Returning null rather than an unpersisted in-memory id on a write
+ * failure is deliberate: a volatile id would send a different value on
+ * every process and quietly break the one-install-one-id property the
+ * whole header exists to provide.
+ *
+ * @param {{homeDir?: string}} [opts]
+ * @returns {string|null}
+ */
+function getInstallId(opts) {
+  const o = opts || {};
+  const existing = peekInstallId(o);
+  if (existing) return existing;
+
+  const minted = crypto.randomBytes(16).toString('hex');
+  const wrote = _atomicWrite(o.homeDir, minted);
+  if (!wrote) {
+    // Concurrent-winner re-check even on our own write failure: another
+    // process may have won the race while we were failing.
+    return peekInstallId(o);
+  }
+
+  // Concurrent-winner re-check: if another process's mint landed between
+  // our write and this read, defer to it so both processes converge on one
+  // bucket rather than splitting into two.
+  const afterWrite = peekInstallId(o);
+  if (afterWrite && afterWrite !== minted) {
+    return afterWrite;
+  }
+  return afterWrite || minted;
+}
+
+/**
+ * resetInstallId({ homeDir }) -- mints unconditionally and REPLACES,
+ * skipping the concurrent-winner re-check (rotation must win over an
+ * existing file by definition). Same atomic write, same mode, same
+ * never-throws contract.
+ * @param {{homeDir?: string}} [opts]
+ * @returns {string|null}
+ */
+function resetInstallId(opts) {
+  const o = opts || {};
+  const minted = crypto.randomBytes(16).toString('hex');
+  const wrote = _atomicWrite(o.homeDir, minted);
+  return wrote ? minted : null;
+}
+
+module.exports = {
+  installIdHeaderName: INSTALL_ID_HEADER_NAME,
+  installIdPath: installIdPath,
+  peekInstallId: peekInstallId,
+  getInstallId: getInstallId,
+  resetInstallId: resetInstallId,
+};

package/lib/mcp/hook-adapter-audit.cjs

@@ -1,7 +1,9 @@
 'use strict';
 // Phase 198-08 (SPEC-5, D-06) -- hook-adapter-audit: the measured
 // "adapter-only" budget for MIGRATED hook scripts (enumerated from
-// hooks/hooks.json's _mcpFirst198Migrated marker, Task 1). Two checks:
+// data/hooks-markers.json's _mcpFirst198Migrated marker, moved there by
+// quick task 260911-juq because the Claude Code hook loader warns on
+// unknown top-level keys in hooks/hooks.json). Two checks:
 //   1. IMPORT AUDIT -- a migrated hook script's own require() calls (after
 //      comment-stripping, so a header/doc comment naming lib/core does not
 //      self-invalidate the gate) never reach into lib/core, lib/workflow, or
@@ -14,10 +16,10 @@
 //      cannot silently re-fatten a thin adapter back into a business-logic
 //      script without this test failing.
 //
-// Scope: ONLY the surfaces hooks.json's own migration marker names (D-05:
-// statusline + SessionStart THIS plan; Stop-gate scripts are Plan 09's
-// concern and are never enumerated here -- enumeration comes from the
-// marker, not a hand-maintained list, so Plan 09 adding its own marker
+// Scope: ONLY the surfaces data/hooks-markers.json's own migration marker
+// names (D-05: statusline + SessionStart THIS plan; Stop-gate scripts are
+// Plan 09's concern and are never enumerated here -- enumeration comes from
+// the marker, not a hand-maintained list, so Plan 09 adding its own marker
 // entries later does not require touching this file).
 //
 // No em-dashes. CJS only.
@@ -26,7 +28,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const HOOKS_JSON_PATH = path.join(REPO_ROOT, 'hooks', 'hooks.json');
+const HOOKS_MARKERS_PATH = path.join(REPO_ROOT, 'data', 'hooks-markers.json');
 
 // Measured baseline + a small margin (D-06: "set the budget from the thin
 // post-migration line counts with a small margin; record the exact numbers
@@ -68,15 +70,17 @@ const LINE_BUDGETS = {
 const FORBIDDEN_IMPORT_PATTERN = /require\(.*lib\/core|require\(.*lib\/workflow|require\(.*lib\/memory/;
 
 /**
- * migratedSurfaces() -- read hooks.json's _mcpFirst198Migrated.surfaces
- * marker (Task 1) and return the list of migrated script paths (repo-root
+ * migratedSurfaces() -- read data/hooks-markers.json's
+ * _mcpFirst198Migrated.surfaces marker (Task 1; moved out of hooks/hooks.json
+ * by quick task 260911-juq so the hook loader stops warning on unknown
+ * top-level keys) and return the list of migrated script paths (repo-root
  * relative). Never throws; a missing/malformed marker returns [].
  *
  * @returns {string[]}
  */
 function migratedSurfaces() {
   try {
-    const raw = fs.readFileSync(HOOKS_JSON_PATH, 'utf8');
+    const raw = fs.readFileSync(HOOKS_MARKERS_PATH, 'utf8');
     const parsed = JSON.parse(raw);
     const marker = parsed && parsed._mcpFirst198Migrated;
     const surfaces = marker && Array.isArray(marker.surfaces) ? marker.surfaces : [];

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@mindrian_os/cli",
-  "version": "2.0.0-beta.35",
+  "version": "2.0.0-beta.37",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@mindrian_os/cli",
-      "version": "2.0.0-beta.35",
+      "version": "2.0.0-beta.37",
       "license": "BSL-1.1",
       "dependencies": {
         "@ig3/markdown-it-wikilinks": "^1.0.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindrian_os/cli",
-  "version": "2.0.0-beta.35",
+  "version": "2.0.0-beta.37",
   "description": "Install MindrianOS into Claude Code with one command -- `npx @mindrian_os/cli`. Ships the MindrianOS plugin (Larry + PWS methodology + Data Room) plus a setup/diagnostics CLI (install/doctor/update).",
   "scripts": {
     "mcp": "node bin/mindrian-mcp-server.cjs",

package/scripts/doctor.cjs

@@ -255,6 +255,12 @@ function parseArgs(argv) {
     // reads through the read-only navigation door + a LOCAL queue write; zero
     // network surface (Canon Part 8).
     graphDeriveHealth: false,
+    // Quick 260911-iko (D-05): --reset-install-id is a SIBLING flag, like
+    // --report-registration-bug, NOT a class flag: it is deliberately NOT
+    // added to the --all activation block below, and it carries its own
+    // always-exit-0 contract (rotation either succeeds or the state dir is
+    // not writable; neither case is a doctor-drift finding).
+    resetInstallId: false,
   };
   for (const arg of argv) {
     if (arg === '--fix') flags.fix = true;
@@ -286,6 +292,10 @@ function parseArgs(argv) {
     // the --all activation block below (same exclusion rationale as
     // --check-rs-engine: --all is class A-M drift detection, not escalation).
     else if (arg === '--report-registration-bug') flags.reportRegistrationBug = true;
+    // Quick 260911-iko (D-05): --reset-install-id rotates the opaque
+    // per-install bucket key. SIBLING flag, own exit-0 contract, see the
+    // parseArgs default comment above.
+    else if (arg === '--reset-install-id') flags.resetInstallId = true;
     else if (arg === '--post-update') flags.postUpdate = true;
     else if (arg === '--dogfood-acceptance') flags.dogfoodAcceptance = true;
     else if (arg === '--claims') flags.claims = true;
@@ -461,6 +471,11 @@ Environment readiness probes (Phase 127.2 Plan 03 -- separate from class flags):
                            host-side core bug. stdout only; --json for the machine shape.
                            Exit 0 whenever the report assembles (even offline); non-zero
                            only if the assembler itself throws. NOT in --all.
+  --reset-install-id       (Quick task 260911-iko) rotates the opaque per-install bucket
+                           key the plugin sends to Theo as the x-theo-install-id header.
+                           Mints a fresh id, replaces the state-dir file, prints exactly
+                           "install id rotated", never prints the value, and always exits
+                           0 (even when the state dir is not writable). NOT in --all.
   --post-update            (Phase 127.2 Plan 04 Instance #7) atomically activate
                            freshly-landed cache-staging bytes via scripts/post-update-
                            activation.cjs (delegates to --fix pipeline + writes the
@@ -3143,6 +3158,26 @@ function main() {
     return;
   }
 
+  // Quick 260911-iko (D-05): --reset-install-id dispatch. Dispatched BEFORE
+  // the class-flag block and BEFORE --acceptance, same position/shape as
+  // --bind-check above: own dispatch, own always-exit-0 contract. Never
+  // prints the id value, not even on the failure path (D-03).
+  if (flags.resetInstallId) {
+    let rotated = null;
+    try {
+      rotated = require(path.join(__dirname, '..', 'lib', 'core', 'install-id.cjs')).resetInstallId();
+    } catch (_e) {
+      rotated = null;
+    }
+    if (typeof rotated === 'string') {
+      console.log('install id rotated');
+    } else {
+      console.log('install id rotation failed (state dir not writable)');
+    }
+    process.exit(0);
+    return;
+  }
+
   // Phase 123 Plan-04: release-gate runner. --acceptance has its own exit-
   // code contract (0 = all points passed; 1 = any point failed); HARD ABORT
   // -- no --allow override (per CONTEXT D-16: release infra is the one gate

package/skills/doctor/SKILL.md

@@ -3,7 +3,7 @@ name: doctor
 description: "Diagnose and optionally repair MindrianOS install: install-cache drift, sentinel gaps, active-room guard, surface-verification, ROOM.md drift, UI compliance, statusline visibility, Brain smoke, and a paste-ready command-registration bug report for Anthropic"
 license: BSL-1.1. See LICENSE for complete terms (Business Source License 1.1, Change Date 2030-04-16 to Apache License 2.0).
 help_jtbd: "Diagnose and optionally repair an off-feeling install."
-argument-hint: "[--fix] [--all] [--cascade-rooms] [--graph-derive-health] [--heal-room] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--card-fire-health] [--install-state] [--stale-first-touch] [--deprecated-usage] [--brain-smoke] [--eureka-smoke] [--drift] [--report-registration-bug] [--acceptance] [--pre-tag] [--pre-flight] [--dogfood-acceptance] [--claims] [--check-rs-engine] [--post-update] [--bind-check] [--simulate-write] [--scan-commands] [--scan-scripts] [--light-npx] [--dry-run] [--json]"
+argument-hint: "[--fix] [--all] [--cascade-rooms] [--graph-derive-health] [--heal-room] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--card-fire-health] [--install-state] [--stale-first-touch] [--deprecated-usage] [--brain-smoke] [--eureka-smoke] [--drift] [--report-registration-bug] [--reset-install-id] [--acceptance] [--pre-tag] [--pre-flight] [--dogfood-acceptance] [--claims] [--check-rs-engine] [--post-update] [--bind-check] [--simulate-write] [--scan-commands] [--scan-scripts] [--light-npx] [--dry-run] [--json]"
 body_shape: E (Action Report)
 hitl_shape: "F.0"
 hitl_why: "It surfaces one diagnosed repair for a single approve-or-defer decision."
@@ -123,6 +123,7 @@ These siblings own their own exit contracts and are not part of the class-flag d
 - `--dogfood-acceptance` -> the Canon Part 6 dog-fooding acceptance pass.
 - `--claims` -> the claims-verification leg.
 - `--check-rs-engine` -> the reason-select engine probe (NOT part of `--all`).
+- `--reset-install-id` -> rotates the opaque per-install bucket key the plugin sends to Theo, prints `install id rotated`, never prints the value, and always exits 0. Full contract: `docs/THEO-INSTALL-ID.md`.
 - `--post-update` -> the post-`claude plugin update` confirmation pass.
 - `--bind-check <roomDir>` -> a lightweight LOCAL room-health check run at BIND-TIME (never per-turn, never a Brain call). NEVER-BLOCK: an unhealthy room degrades to an advisory and STILL exits 0.
 - `--light-npx` -> the lighter npx-roundtrip variant for `--acceptance`.