heyspex 0.2.5 → 0.2.7

package/vendor/heyspex-mcp/seat-defaults-cli.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// vendor/heyspex-mcp/seat-defaults-cli.mjs — read-only listing of every SpexFleet seat's default
+// model for the harness this shell runs under ([[HS-2K22-C86Z-TASK-plugin-installs-stamp-heyspex-harness]],
+// epic HS-C65J). Thin shell over seat-defaults.mjs + harness-detect.mjs; editing seats is epic HS-K9L7's.
+//
+//   node vendor/heyspex-mcp/seat-defaults-cli.mjs [--json] [--harness claude-code|copilot]
+//
+// Exit 0 always for a listing; 2 on a bad argument. Reads the installed-plugin registries under the
+// user's home (or HEYSPEX_SEAT_HOME / COPILOT_HOME when set — tests point these at fake homes).
+import { readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import { detectHarness, listInstalledHarnessPlugins, normalizeHarness } from '../../spexharness/src/adapters/harness-detect.mjs';
+import { formatSeatDefaults, listSeatDefaults } from './seat-defaults.mjs';
+
+export function runSeatDefaultsCli(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  let json = false;
+  let forced;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') json = true;
+    else if (a === '--harness' || a.startsWith('--harness=')) {
+      const v = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i];
+      forced = normalizeHarness(v);
+      if (forced === undefined) { stderr.write(`seat defaults: --harness must be claude-code, copilot or none (got "${v ?? ''}")\n`); return 2; }
+    } else { stderr.write(`seat defaults: unknown argument "${a}"\n`); return 2; }
+  }
+  const home = env.HEYSPEX_SEAT_HOME || os.homedir();
+  const deps = {
+    readFile: (p) => { try { return readFileSync(p, 'utf8'); } catch { return null; } },
+    listDir: (p) => { try { return readdirSync(p); } catch { return []; } },
+  };
+  const installed = listInstalledHarnessPlugins({ home, copilotHome: env.COPILOT_HOME || undefined, deps });
+  const detected = forced !== undefined
+    ? { harness: forced, status: forced ? 'resolved' : 'none', source: 'flag:--harness', detail: forced }
+    : detectHarness(env, null, installed);
+  if (json) {
+    stdout.write(`${JSON.stringify({ harness: detected, installedPlugins: installed, seats: listSeatDefaults(detected.harness) }, null, 2)}\n`);
+  } else {
+    stdout.write(formatSeatDefaults(detected));
+  }
+  return 0;
+}
+
+const isMain = process.argv[1]?.replaceAll('\\', '/').endsWith('/seat-defaults-cli.mjs');
+if (isMain) process.exitCode = runSeatDefaultsCli(process.argv.slice(2));

package/vendor/heyspex-mcp/seat-defaults.mjs

@@ -0,0 +1,232 @@
+// vendor/heyspex-mcp/seat-defaults.mjs
+//
+// The CUSTOMER default model for every SpexFleet seat, decided by the harness the installed
+// plugin runs in ([[HS-KQ5E-C86Z-TASK-pure-harness-detection-and-seat-default]] of epic
+// [[HS-C65J-C86Z-EPIC-harness-aware-seat-default-resolver]]; research
+// [[HS-RXJO-C86Z-RES-spexfleet-per-user-seat-assignment-with]]).
+//
+// Owner rulings 2026-10-17 (capture [[HS-5TM7-C86Z-CAP-spexfleet-roles-are-assignable-by-each-u]]):
+//   Claude Code → Claude models on every seat, tiered by the seat's job:
+//       judgement / planning → opus   (COO, director, breakdown, critic, inquisitor, council,
+//                                      research synthesis, architect/engineer/verifier/reviewer/supervisor)
+//       execution            → sonnet (builder, capture expand)
+//       mechanical           → haiku  (ground rerank, research gather, fit analysis)
+//       in-session sub-agent → inherit (follows the user's own main Claude Code session)
+//   Copilot → "auto" on every seat.
+//   No harness → no default (the caller asks); NEVER an owner default (DeepSeek, routing table).
+//
+// Precedence (resolveSeatModel): explicit per-run override > the user's own assignment (epic
+// HS-K9L7 fills it) > ownerOverlay() (the owner's dev-factory fleet; sibling epic HS-9JMD owns
+// the gate that decides when it may load) > harness default.
+//
+// Pure: no fs, no env reads, no clock. The seat roster below is the PRODUCT roster (the built-in
+// seat ids of the seat registry, epic HS-RJVM), never anyone's seats.json assignments.
+
+/** Seat tiers. */
+export const SEAT_TIERS = Object.freeze(['judgement', 'execution', 'mechanical', 'in-session', 'human']);
+
+/** The model aliases the Claude Code harness accepts for each tier (aliases track Anthropic's current release). */
+export const CLAUDE_TIER_MODELS = Object.freeze({
+  judgement: 'opus',
+  execution: 'sonnet',
+  mechanical: 'haiku',
+  'in-session': 'inherit',
+  human: null,
+});
+
+/** Copilot's own automatic model selection — the default for every Copilot seat. */
+export const COPILOT_DEFAULT_MODEL = 'auto';
+
+/**
+ * The product seat roster: every built-in SpexFleet seat id and its tier. Display titles are for
+ * read-only listings only; the id is the contract.
+ */
+export const PRODUCT_SEATS = Object.freeze([
+  { id: 'owner', tier: 'human', title: 'Owner' },
+  { id: 'coo-phase-1', tier: 'judgement', title: 'COO (phase 1)' },
+  { id: 'coo-phase-2', tier: 'judgement', title: 'COO (phase 2)' },
+  { id: 'director-of-operations', tier: 'judgement', title: 'Director of Operations' },
+  { id: 'breakdown', tier: 'judgement', title: 'Breakdown' },
+  { id: 'build', tier: 'execution', title: 'Builder' },
+  { id: 'critic', tier: 'judgement', title: 'Critic' },
+  { id: 'expand', tier: 'execution', title: 'Capture expand' },
+  { id: 'research-initiation', tier: 'mechanical', title: 'Research gather' },
+  { id: 'research-synthesis', tier: 'judgement', title: 'Research synthesis' },
+  { id: 'inquisitor', tier: 'judgement', title: 'Inquisitor' },
+  { id: 'fit-analysis', tier: 'mechanical', title: 'Fit analysis' },
+  { id: 'ground-rerank', tier: 'mechanical', title: 'Ground rerank' },
+  { id: 'software-architect', tier: 'judgement', title: 'Software Architect' },
+  { id: 'principal-engineer', tier: 'judgement', title: 'Principal Engineer' },
+  { id: 'council-code-reviewer', tier: 'judgement', title: 'Council: code reviewer' },
+  { id: 'council-spec-auditor', tier: 'judgement', title: 'Council: spec auditor' },
+  { id: 'council-integrator', tier: 'judgement', title: 'Council: integrator' },
+  { id: 'subagent-capture-triager', tier: 'in-session', title: 'Sub-agent: capture triager' },
+  { id: 'subagent-plan-grounder', tier: 'in-session', title: 'Sub-agent: plan grounder' },
+  { id: 'subagent-resolution-triager', tier: 'in-session', title: 'Sub-agent: resolution triager' },
+  { id: 'subagent-deployment-engineer', tier: 'in-session', title: 'Sub-agent: deployment engineer' },
+  { id: 'subagent-code-reviewer', tier: 'in-session', title: 'Sub-agent: code reviewer' },
+  { id: 'subagent-research-synthesizer', tier: 'in-session', title: 'Sub-agent: research synthesizer' },
+  { id: 'verifier', tier: 'judgement', title: 'Verifier' },
+  { id: 'reviewer', tier: 'judgement', title: 'Reviewer' },
+  { id: 'supervisor', tier: 'judgement', title: 'Supervisor' },
+].map((s) => Object.freeze(s)));
+
+const SEAT_BY_ID = new Map(PRODUCT_SEATS.map((s) => [s.id, s]));
+
+/** Role names callers use for a seat (HEYSPEX_FLEET_ROLE vocabulary, purposes) → product seat id. */
+export const SEAT_ALIASES = Object.freeze({
+  builder: 'build',
+  coo: 'coo-phase-1',
+  director: 'director-of-operations',
+  research: 'research-synthesis',
+  'research-gather': 'research-initiation',
+  synthesis: 'research-synthesis',
+  rerank: 'ground-rerank',
+  'capture-expand': 'expand',
+  fit: 'fit-analysis',
+});
+
+/** Normalize a seat id or role name to a product seat id (lower-case, aliases folded). Unknown ids pass through. */
+export function canonicalSeatId(seat) {
+  const raw = typeof seat === 'string' ? seat : seat && typeof seat === 'object' ? seat.id : '';
+  const id = String(raw ?? '').trim().toLowerCase();
+  if (!id) return '';
+  return SEAT_ALIASES[id] ?? id;
+}
+
+/**
+ * The tier of a seat. Product seats use the roster; an unlisted id is classified by shape
+ * (council-* → judgement, subagent-* → in-session); any other developer-added seat is execution.
+ * @returns {'judgement'|'execution'|'mechanical'|'in-session'|'human'|null} null only for an empty id
+ */
+export function seatTier(seat) {
+  const id = canonicalSeatId(seat);
+  if (!id) return null;
+  const known = SEAT_BY_ID.get(id);
+  if (known) return known.tier;
+  if (id.startsWith('council-')) return 'judgement';
+  if (id.startsWith('subagent-')) return 'in-session';
+  return 'execution';
+}
+
+const HARNESS_NAMES = new Set(['claude-code', 'copilot']);
+
+/**
+ * @typedef {object} SeatDefault
+ * @property {string} seat               canonical seat id
+ * @property {string|null} tier
+ * @property {'claude-code'|'copilot'|null} harness
+ * @property {string|null} model         null = no default (human seat, or no harness)
+ * @property {'harness-default'|'human'|'no-harness'} source
+ */
+
+/**
+ * The harness default model for one seat.
+ * @param {string|{id: string}} seat
+ * @param {'claude-code'|'copilot'|string|null|undefined} harness
+ * @returns {SeatDefault}
+ */
+export function defaultModelForSeat(seat, harness) {
+  const id = canonicalSeatId(seat);
+  const tier = seatTier(id);
+  const h = HARNESS_NAMES.has(harness) ? harness : null;
+  if (tier === 'human') return Object.freeze({ seat: id, tier, harness: h, model: null, source: 'human' });
+  if (!h || !tier) return Object.freeze({ seat: id, tier, harness: h, model: null, source: 'no-harness' });
+  const model = h === 'copilot' ? COPILOT_DEFAULT_MODEL : CLAUDE_TIER_MODELS[tier];
+  return Object.freeze({ seat: id, tier, harness: h, model, source: 'harness-default' });
+}
+
+/** Every product seat's harness default, in roster order. */
+export function listSeatDefaults(harness) {
+  return PRODUCT_SEATS.map((s) => ({ ...defaultModelForSeat(s.id, harness), title: s.title }));
+}
+
+// ── Owner overlay seam ───────────────────────────────────────────────────────
+// The owner's personal dev-factory fleet (seats.json fill.model, routing table) is an OVERLAY that
+// must only ever load for the owner on a heyspex-app source checkout. Deciding that is sibling epic
+// HS-9JMD's job; this module only provides the slot. The default overlay is "no overlay".
+// A registered overlay receives { seat, harness, ...ctx } and returns a model id string or null.
+
+const NO_OVERLAY = () => null;
+let registeredOverlay = NO_OVERLAY;
+
+/** Install the owner-overlay resolver (HS-9JMD). Pass null to clear. Returns the previous one. */
+export function registerOwnerOverlay(fn) {
+  const prev = registeredOverlay;
+  registeredOverlay = typeof fn === 'function' ? fn : NO_OVERLAY;
+  return prev;
+}
+
+/**
+ * Ask the owner overlay for a seat's model. Never throws; anything but a non-empty string is null.
+ * @param {{ seat: string, harness?: string|null, [k: string]: unknown }} ctx
+ * @param {Function} [overlay] injectable (tests / a caller that carries its own gate)
+ * @returns {string|null}
+ */
+export function ownerOverlay(ctx = {}, overlay = registeredOverlay) {
+  try {
+    const m = overlay(ctx);
+    return typeof m === 'string' && m.trim() ? m.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {object} SeatModelResolution
+ * @property {string} seat
+ * @property {string|null} model
+ * @property {'explicit'|'user-assignment'|'owner-overlay'|'harness-default'|'human'|'no-harness'} source
+ * @property {'claude-code'|'copilot'|null} harness
+ * @property {string|null} tier
+ */
+
+const nonEmpty = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+/**
+ * The full seat → model chain.
+ * @param {object} p
+ * @param {string} p.seat
+ * @param {'claude-code'|'copilot'|null} [p.harness]
+ * @param {string|null} [p.explicit]     per-run override (--model, HEYSPEX_SEAT_MODEL_<SEAT>)
+ * @param {string|null} [p.assignment]   the user's own assignment for this seat (HS-K9L7)
+ * @param {Function} [p.overlay]         owner-overlay resolver; defaults to the registered one
+ * @param {object} [p.overlayContext]    extra context handed to the overlay
+ * @returns {SeatModelResolution}
+ */
+export function resolveSeatModel({ seat, harness = null, explicit = null, assignment = null, overlay, overlayContext = {} } = {}) {
+  const base = defaultModelForSeat(seat, harness);
+  const out = (model, source) => Object.freeze({ seat: base.seat, model, source, harness: base.harness, tier: base.tier });
+  const e = nonEmpty(explicit);
+  if (e) return out(e, 'explicit');
+  const a = nonEmpty(assignment);
+  if (a) return out(a, 'user-assignment');
+  const o = ownerOverlay({ ...overlayContext, seat: base.seat, harness: base.harness }, overlay ?? registeredOverlay);
+  if (o) return out(o, 'owner-overlay');
+  return out(base.model, base.source);
+}
+
+/** The env key for a per-run seat override: HEYSPEX_SEAT_MODEL_<SEAT> (seat id upper-cased, '-' → '_'). */
+export function seatModelEnvKey(seat) {
+  return `HEYSPEX_SEAT_MODEL_${canonicalSeatId(seat).toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+}
+
+/**
+ * A plain-text table of seat defaults (read-only listing for `hs seat` / smoke proofs).
+ * @param {{ harness: string|null, status?: string, choices?: string[] }} detected
+ */
+export function formatSeatDefaults(detected) {
+  const harness = detected?.harness ?? null;
+  const lines = [];
+  if (!harness) {
+    lines.push(detected?.status === 'needs-choice'
+      ? `No harness detected and several are installed (${(detected.choices ?? []).join(', ')}): set HEYSPEX_HARNESS to choose.`
+      : 'No harness detected: set HEYSPEX_HARNESS=claude-code or HEYSPEX_HARNESS=copilot.');
+  } else {
+    lines.push(`Seat defaults for harness: ${harness}`);
+  }
+  const rows = listSeatDefaults(harness);
+  const w = Math.max(...rows.map((r) => r.seat.length));
+  for (const r of rows) lines.push(`  ${r.seat.padEnd(w)}  ${String(r.model ?? '-').padEnd(8)}  ${r.source}`);
+  return lines.join('\n') + '\n';
+}

package/vendor/heyspex-mcp/seat-identity.mjs

@@ -20,6 +20,9 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { PACKAGE_ROOT } from "./package-root.mjs";
+import { canonicalSeatId, ownerOverlay, registerOwnerOverlay, resolveSeatModel, seatModelEnvKey } from "./seat-defaults.mjs";
+import { devFactoryOverlayVerdict } from "./dev-factory-overlay.mjs";
+import { detectHarness } from "../../spexharness/src/adapters/harness-detect.mjs";
 
 /**
  * Read and parse <vaultRoot>/dev-factory/seats.json.
@@ -126,6 +129,174 @@ export function resolveSeatForCaller({
   return resolveSeat({ agent, sessionId }, { registry, env });
 }
 
+/**
+ * True when `packageRoot` is a heyspex-app SOURCE checkout rather than an installed npm package
+ * (`…/node_modules/heyspex`). Pure on the path string. The owner's dev-factory overlay only ever
+ * applies on a source checkout ([[HS-C65J-C86Z-EPIC-harness-aware-seat-default-resolver]]); the
+ * stricter owner-account gate is sibling epic HS-9JMD's, registered through
+ * seat-defaults.mjs `registerOwnerOverlay`.
+ */
+export function isSourceCheckoutRoot(packageRoot) {
+  const p = String(packageRoot ?? "").replaceAll("\\", "/").replace(/\/+$/, "");
+  if (!p) return false;
+  return !/\/node_modules\/heyspex$/i.test(p);
+}
+
+/** The `fill.model` the owner's seats.json assigns `seatId` (aliases folded), or null. Pure. */
+export function seatFillModel(registry, seatId) {
+  if (!registry || !Array.isArray(registry.seats)) return null;
+  const id = canonicalSeatId(seatId);
+  if (!id) return null;
+  const seat = registry.seats.find((s) => s && typeof s.id === "string" && canonicalSeatId(s.id) === id);
+  const m = seat?.fill?.model;
+  return typeof m === "string" && m.trim() ? m.trim() : null;
+}
+
+/**
+ * Build the owner's dev-factory overlay: seat → `fill.model`, else the first route of the seat's
+ * routing purpose (`fill.routingPurpose` / `routing_purpose` / `filledBy.purpose`) through the
+ * owner's router `pickRoute`. Pure given its inputs — the caller supplies the registry and the
+ * router (never imported here: dev-factory/router.mjs is not in the npm package). Sibling epic
+ * HS-9JMD registers the result via seat-defaults.mjs `registerOwnerOverlay` behind its gate.
+ * @param {{ registry: object|null, pickRoute?: (purpose: string) => {model?: string}|undefined }} p
+ * @returns {(ctx: {seat: string}) => string|null}
+ */
+export function createDevFactoryOverlay({ registry, pickRoute } = {}) {
+  return ({ seat } = {}) => {
+    const direct = seatFillModel(registry, seat);
+    if (direct) return direct;
+    if (typeof pickRoute !== "function" || !registry || !Array.isArray(registry.seats)) return null;
+    const id = canonicalSeatId(seat);
+    const row = registry.seats.find((s) => s && typeof s.id === "string" && canonicalSeatId(s.id) === id);
+    const purpose = row?.fill?.routingPurpose ?? row?.routing_purpose ?? row?.filledBy?.purpose ?? null;
+    if (typeof purpose !== "string" || !purpose) return null;
+    try {
+      const m = pickRoute(purpose)?.model;
+      return typeof m === "string" && m ? m : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Which model a seat runs on for this caller — the CUSTOMER default comes from the harness the
+ * installed plugin runs in ([[HS-MDZB-C86Z-TASK-wire-harness-seat-defaults-into-seat]]).
+ *
+ * Chain (seat-defaults.mjs `resolveSeatModel`):
+ *   1. explicit: `model`, else env HEYSPEX_SEAT_MODEL_<SEAT>
+ *   2. the user's own assignment (`assignment`; epic HS-K9L7 supplies it)
+ *   3. owner overlay: a registered overlay (registerDevFactoryOwnerOverlay) wins; otherwise, ONLY
+ *      when the HS-9JMD gate is open, the vault's dev-factory/seats.json `fill.model`
+ *   4. harness default (Claude tiers / Copilot `auto`); no harness → model null, never an owner default
+ *
+ * @param {object} p
+ * @param {string} p.seatId
+ * @param {string} [p.vaultRoot]         where seats.json is read (only on a source checkout)
+ * @param {object} [p.env]
+ * @param {unknown} [p.payload]          hook payload, when called from a hook
+ * @param {string[]} [p.installedPlugins]
+ * @param {string|null} [p.model]
+ * @param {string|null} [p.assignment]
+ * @param {object|null} [p.registry]     injected seats.json (tests); read off vaultRoot otherwise
+ * @param {string} [p.packageRoot]       injected install root (tests); this package's root otherwise
+ * @param {Function} [p.pickRouteFn]     the owner router pickRoute (owner checkout only; never imported here)
+ * @param {boolean} [p.overlayOpen]      injected HS-9JMD gate verdict (tests); computed from the root otherwise
+ * @returns {{seat: string, model: string|null, source: string, harness: string|null, tier: string|null, harnessDetection: object}}
+ */
+export function resolveSeatModelForCaller({
+  seatId,
+  vaultRoot,
+  env = {},
+  payload = null,
+  installedPlugins = [],
+  model = null,
+  assignment = null,
+  registry,
+  packageRoot = PACKAGE_ROOT,
+  pickRouteFn,
+  overlayOpen,
+} = {}) {
+  const detected = detectHarness(env, payload, installedPlugins);
+  const explicit = model ?? env?.[seatModelEnvKey(seatId)] ?? null;
+  // HS-9JMD gate ([[HS-RA2Q-C86Z-TASK-wire-the-owner-overlay-to-the-dev]]): the inline seats.json
+  // fallback opens only where the dev-factory overlay verdict is open — a source checkout AND the
+  // owner account AND the switch on. Evaluated lazily, once, and only when no registered overlay
+  // answered, so a customer install never even stats the owner files.
+  let gate = typeof overlayOpen === "boolean" ? overlayOpen : undefined;
+  const isOpen = () => {
+    if (gate === undefined) gate = isSourceCheckoutRoot(packageRoot) && ownerOverlayGateOpen({ root: overlayRootFor(vaultRoot, packageRoot), env });
+    return gate;
+  };
+  const overlay = (ctx) => {
+    const registered = ownerOverlay(ctx);
+    if (registered) return registered;
+    if (!isOpen()) return null;
+    const reg = registry !== undefined ? registry : vaultRoot ? readSeatsRegistry(vaultRoot) : null;
+    return createDevFactoryOverlay({ registry: reg, pickRoute: pickRouteFn })(ctx);
+  };
+  const r = resolveSeatModel({ seat: seatId, harness: detected.harness, explicit, assignment, overlay });
+  return { ...r, harnessDetection: detected };
+}
+
+/** The repo root whose dev-factory/ the inline fallback would read (the vault root when it has one). */
+function overlayRootFor(vaultRoot, packageRoot) {
+  return vaultRoot || packageRoot || null;
+}
+
+/**
+ * The HS-9JMD dev-factory overlay verdict for `root` (see dev-factory-overlay.mjs): open only on a
+ * heyspex-app source checkout, for the declared owner account, with HEYSPEX_DEV_FACTORY not "0".
+ * Never throws.
+ */
+export function ownerOverlayGateOpen({ root, env = process.env, accountId } = {}) {
+  try {
+    return devFactoryOverlayVerdict({ root, env, ...(accountId !== undefined ? { accountId } : {}) }).open === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register the owner's dev-factory fleet as the seat-defaults owner overlay — ONLY when the HS-9JMD
+ * gate is open for `root` ([[HS-RA2Q-C86Z-TASK-wire-the-owner-overlay-to-the-dev]]). The router is
+ * the owner's `dev-factory/router.mjs` `pickRoute`, loaded from `root` only after the gate opened
+ * (it is not in the npm package). A closed gate registers nothing and reads nothing: the seat chain
+ * falls through to the harness default.
+ *
+ * @param {object} [p]
+ * @param {string} [p.root]           repo root that holds dev-factory/ (default: this package's root)
+ * @param {object} [p.env]
+ * @param {string|null} [p.accountId] injected signed-in account (tests)
+ * @param {Function} [p.pickRoute]    injected router (tests); else imported from <root>/dev-factory/router.mjs
+ * @param {object|null} [p.registry]  injected seats.json (tests); else read from <root>
+ * @param {Function} [p.register]     injected registerOwnerOverlay (tests)
+ * @returns {Promise<{ registered: boolean, reason: string }>}
+ */
+export async function registerDevFactoryOwnerOverlay({ root = PACKAGE_ROOT, env = process.env, accountId, pickRoute, registry, register = registerOwnerOverlay } = {}) {
+  let verdict;
+  try {
+    verdict = devFactoryOverlayVerdict({ root, env, ...(accountId !== undefined ? { accountId } : {}) });
+  } catch {
+    verdict = { open: false, reason: "error" };
+  }
+  if (!verdict.open) return { registered: false, reason: verdict.reason };
+  const reg = registry !== undefined ? registry : readSeatsRegistry(root);
+  if (!reg) return { registered: false, reason: "no-seats-registry" };
+  let route = pickRoute;
+  if (typeof route !== "function") {
+    try {
+      const { pathToFileURL } = await import("node:url");
+      const mod = await import(pathToFileURL(path.join(root, "dev-factory", "router.mjs")).href);
+      route = typeof mod.pickRoute === "function" ? (purpose) => mod.pickRoute(purpose) : undefined;
+    } catch {
+      route = undefined; // no router: fill.model pins still apply
+    }
+  }
+  register(createDevFactoryOverlay({ registry: reg, pickRoute: route }));
+  return { registered: true, reason: verdict.reason };
+}
+
 /**
  * Render a resolved seat as a single-line identity banner for delivery to the
  * caller — the same seat's OWN mandate, so a Builder worker sees "Builder" and a

package/vendor/heyspex-mcp/test-helpers.mjs

@@ -3,9 +3,9 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
 import { resetActiveConfigCache } from './vault-resolve.mjs';
 
@@ -134,35 +134,49 @@ export function installScopedConsoleEnv({
  * part of `scripts/`) also imports `vendor/heyspex-mcp/vault-resolve.mjs` by a
  * relative path OUTSIDE `scripts/` — that file must be mirrored too, or the
  * copied validator dangles with MODULE_NOT_FOUND the moment it computes its
- * own default root. `vault-resolve.mjs` itself has no further local-file
- * imports (node builtins only), so this is a single extra copy, not a chain.
+ * own default root, and that file in turn imports `vault-binding.mjs` →
+ * `usable-dir-env.mjs` (a chain, not a single copy).
  *
- * Single source of truth: the next dependency the validator grows is a one-line
- * add here, not a silent breakage in every round-trip test.
+ * The mirror is DERIVED, not hand-listed: a hardcoded list rotted three times
+ * as modules grew imports (last miss: `usable-dir-env.mjs`, HS-PNBC). We walk
+ * relative import specifiers transitively from the validator and copy every
+ * reached file that lives outside `scripts/` (which is copied wholesale).
  *
  * @param {string} repoRoot Absolute path to the real repo root.
  * @param {string} root Absolute path to the temp vault being assembled.
  */
 export function mirrorValidatorDeps(repoRoot, root) {
   cpSync(join(repoRoot, 'scripts'), join(root, 'scripts'), { recursive: true });
-
-  mkdirSync(join(root, 'vendor', 'heyspex-mcp'), { recursive: true });
-  // vault-resolve.mjs imports vault-binding.mjs (the repo binding, HS-TYJA).
-  for (const file of ['vault-resolve.mjs', 'vault-binding.mjs']) {
-    const rel = join('vendor', 'heyspex-mcp', file);
-    cpSync(join(repoRoot, rel), join(root, rel));
+  for (const abs of localImportClosure(join(repoRoot, 'scripts', 'validate-vault-ids.mjs'))) {
+    const rel = relative(repoRoot, abs);
+    if (rel.startsWith('..') || isAbsolute(rel)) continue;
+    if (rel.split(sep)[0] === 'scripts') continue; // already copied wholesale
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    cpSync(abs, join(root, rel));
   }
+}
+
+// Relative specifiers in `from '…'`, side-effect `import '…'`, and literal `import('…')`.
+const LOCAL_IMPORT_RE = /(?:\bfrom\s*|\bimport\s*\(?\s*)(['"])(\.{1,2}\/[^'"]+)\1/g;
 
-  const indexerRel = join('spex-console', 'src', 'lib', 'indexer');
-  mkdirSync(join(root, indexerRel), { recursive: true });
-  for (const file of [
-    'vault-rules.mjs',
-    'vault-naming-rules.generated.mjs',
-    // validate-vault-ids.mjs imports handoff-envelope.mjs (split/defer lineage rule).
-    'handoff-envelope.mjs',
-  ]) {
-    const rel = join(indexerRel, file);
-    const src = join(repoRoot, rel);
-    if (existsSync(src)) cpSync(src, join(root, rel));
+/**
+ * Every local file transitively reachable from `entry` via relative import
+ * specifiers (bare/builtin specifiers ignored). A missing target is skipped so
+ * the copied script fails loudly with MODULE_NOT_FOUND instead of here.
+ *
+ * @param {string} entry Absolute path to the entry module.
+ * @returns {Set<string>} Absolute paths, entry included.
+ */
+export function localImportClosure(entry) {
+  const seen = new Set();
+  const stack = [entry];
+  while (stack.length) {
+    const file = stack.pop();
+    if (seen.has(file) || !existsSync(file)) continue;
+    seen.add(file);
+    for (const m of readFileSync(file, 'utf8').matchAll(LOCAL_IMPORT_RE)) {
+      stack.push(resolve(dirname(file), m[2]));
+    }
   }
+  return seen;
 }