heyspex 0.1.0 → 0.2.0

package/dev-factory/lib/model-catalog.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+/**
+ * model-catalog.mjs — typed accessors over dev-factory/model-catalog.json, the ONE place model
+ * ids, aliases, retirements, context windows, capabilities, endpoints and list prices are
+ * declared for every cloud provider (DeepSeek, Anthropic, OpenAI, Gemini, OpenRouter, GitHub
+ * Models) and every local runtime (Ollama, vLLM).
+ *
+ * Why: vendors ship and retire models every few weeks (DeepSeek retired `deepseek-v4-flash`
+ * on 2026-09-10 and the rename touched 110 files). With this module an upgrade is a JSON edit
+ * plus three self-tests; code imports the role constants below instead of spelling ids.
+ *
+ *   import { DEEPSEEK, OLLAMA, ANTHROPIC, resolveModelId, contextWindowFor } from "./lib/model-catalog.mjs";
+ *   runToolLoop with DEEPSEEK.CHEAP ("deepseek-flash" today)
+ *   resolveModelId("deepseek-v4-flash")            // "deepseek-flash" (alias → current)
+ *   isRetiredModelId("deepseek-v4-flash")          // true
+ *   contextWindowFor("qwen3-coder:30b")            // 262144
+ *   providerEntries()                              // the whole cloud-clients PROVIDERS table
+ *
+ *   node dev-factory/lib/model-catalog.mjs --self-test
+ *   node dev-factory/lib/model-catalog.mjs --print            # resolved constants as JSON
+ *
+ * ROUTING is not here: which seat runs which model lives in routing-table.json; this file says
+ * what a model IS and how it is reached. Pure module — reads the JSON once at import, no
+ * network, no other I/O. When dev-factory merges into SpexFleet this file and the JSON move
+ * together; every importer uses a relative path (the console goes through ONE shim,
+ * spex-console/src/lib/model-catalog.ts) so the move is a path edit, not a sweep.
+ */
+// A STATIC JSON import, not `readFileSync`: this module is reached from the console's CLIENT
+// bundles (through spex-console/src/lib/model-catalog.ts — `store/agent-store.ts` and the
+// dev-factory pipeline tab are "use client" files), and a `node:fs` / `node:path` / `node:url`
+// import there makes Turbopack fail every page with "the chunking context does not support
+// external modules (request: node:fs)" (2026-09-18: every route on the local console 500'd).
+// Bundlers inline the JSON; Node reads it once at import — the same "read once at import, no
+// other I/O" contract as before.
+import catalogJson from "../model-catalog.json" with { type: "json" };
+
+/** Where the catalog lives, as a `file:` URL string (informational — nothing reads it back). */
+export const MODEL_CATALOG_PATH = new URL("../model-catalog.json", import.meta.url).href;
+
+/**
+ * Return a catalog document (default: the bundled JSON). Exported so tests can feed a fixture.
+ * Typed `any` on purpose: `JSON.parse` used to hand TS an `any` here, and every consumer's
+ * inferred type (role blocks, provider entries, the console's typed shim) was built on that.
+ * A static JSON import would otherwise leak the literal JSON shape into those inferences.
+ * @param {any} [doc]
+ * @returns {any}
+ */
+export function loadModelCatalog(doc = /** @type {any} */ (catalogJson)) {
+  return doc;
+}
+
+export const MODEL_CATALOG = Object.freeze(loadModelCatalog());
+
+// ── flattened index: id → descriptor ─────────────────────────────────────────────────────────
+function buildIndex(catalog) {
+  const byId = new Map();
+  const aliases = new Map();
+  const retired = new Map();
+  const providers = new Map();
+  for (const [locality, block] of Object.entries({ cloud: catalog.cloud ?? {}, local: catalog.local ?? {} })) {
+    for (const [provider, p] of Object.entries(block)) {
+      if (provider.startsWith("_")) continue;
+      // `p.kind` (from the JSON) is the wire PROTOCOL — "openai" (chat-completions-compatible),
+      // "anthropic" (Messages API) or "ollama" — and cloud-clients.mjs branches on it
+      // (`p.kind === "anthropic"`). `locality` is the cloud/local classification the outer loop
+      // walks. Keep them distinct: overwriting the provider's protocol kind with "cloud"/"local"
+      // broke the Anthropic call branch silently (providerEntries() emitted kind: "cloud" for
+      // every provider, so `callModel` always took the OpenAI-compat path).
+      providers.set(provider, { ...p, provider, locality, kind: p.kind ?? locality });
+      for (const [id, m] of Object.entries(p.models ?? {})) {
+        byId.set(id, Object.freeze({ id, kind: locality, provider, tier: m.tier ?? (locality === "local" ? "local" : null), ...m }));
+      }
+      for (const [alias, target] of Object.entries(p.aliases ?? {})) aliases.set(alias, { target, provider, kind: locality });
+      for (const r of p.retired ?? []) retired.set(r.id, { ...r, provider, kind: locality });
+    }
+  }
+  return { byId, aliases, retired, providers };
+}
+const INDEX = buildIndex(MODEL_CATALOG);
+
+/** Every current (non-alias, non-retired) model id in the catalog. */
+export const ALL_MODEL_IDS = Object.freeze([...INDEX.byId.keys()]);
+/** alias → current id, across every provider. */
+export const MODEL_ALIASES = Object.freeze(Object.fromEntries([...INDEX.aliases].map(([a, v]) => [a, v.target])));
+/** Retired ids (still routed by the vendor or not) — live code must not spell these. */
+export const RETIRED_MODEL_IDS = Object.freeze([...INDEX.retired.keys()]);
+/** Provider names, cloud and local. */
+export const PROVIDER_NAMES = Object.freeze([...INDEX.providers.keys()]);
+
+/** Alias → current id; unknown ids pass through unchanged (a local Ollama tag we don't list). */
+export function resolveModelId(id) {
+  if (typeof id !== "string" || !id) return id;
+  const hit = INDEX.aliases.get(id);
+  return hit ? hit.target : id;
+}
+export function isRetiredModelId(id) { return INDEX.retired.has(id); }
+export function isKnownModelId(id) { return INDEX.byId.has(id) || INDEX.aliases.has(id); }
+/** Descriptor for a current id or an alias (resolved); null when the catalog has never heard of it. */
+export function modelInfo(id) { return INDEX.byId.get(resolveModelId(id)) ?? null; }
+/** The provider block (endpoint, key env, roles…) a model id belongs to, or null. */
+export function providerOf(id) { const m = modelInfo(id); return m ? INDEX.providers.get(m.provider) ?? null : null; }
+export function providerInfo(name) { return INDEX.providers.get(name) ?? null; }
+export function isLocalModel(id) { return modelInfo(id)?.kind === "local"; }
+export function isDeepSeekModel(id) { return modelInfo(id)?.provider === "deepseek"; }
+export function isAnthropicModel(id) { return modelInfo(id)?.provider === "anthropic"; }
+export function hasCapability(id, cap) { return (modelInfo(id)?.capabilities ?? []).includes(cap); }
+/** Context window in tokens for a known id/alias, else `fallback`. */
+export function contextWindowFor(id, fallback = null) { return modelInfo(id)?.contextWindow ?? fallback; }
+/** Max output tokens for a known id/alias, else `fallback`. */
+export function maxOutputTokensFor(id, fallback = null) { return modelInfo(id)?.maxOutputTokens ?? fallback; }
+
+// ── per-provider role constants ──────────────────────────────────────────────────────────────
+/**
+ * Per-provider role-constant block (DEEPSEEK, ANTHROPIC, OLLAMA, …). The fixed props below are
+ * typed explicitly; role names vary per provider (roles.chatDefault → CHAT_DEFAULT, roles.cheap →
+ * CHEAP, …) so TS consumers (spex-console) need an index signature to reach them —
+ * `DEEPSEEK.CHAT_DEFAULT`, `DEEPSEEK.JUDGE`, `OLLAMA.JUDGE_FALLBACK`, etc.
+ * @returns {{ provider: string, kind: string|null, company: string, baseUrl: string|null,
+ *   keyEnv: string|null, keyEnvFallback: string|null, verifiedOn: string,
+ *   roles: Record<string, string>, ids: readonly string[], aliases: Record<string, string>,
+ *   retired: readonly string[], [roleConstant: string]: any }}
+ */
+function roleBlock(name, extra = {}) {
+  const p = INDEX.providers.get(name) ?? {};
+  const roles = p.roles ?? {};
+  const upper = Object.fromEntries(Object.entries(roles).map(([k, v]) => [k.replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase(), v]));
+  return Object.freeze({
+    provider: name,
+    kind: p.kind ?? null,
+    company: p.company ?? name,
+    baseUrl: p.baseUrl ?? null,
+    keyEnv: p.keyEnv ?? null,
+    keyEnvFallback: p.keyEnvFallback ?? null,
+    verifiedOn: p.verifiedOn ?? MODEL_CATALOG.verified,
+    roles: Object.freeze({ ...roles }),
+    ids: Object.freeze(Object.keys(p.models ?? {})),
+    aliases: Object.freeze({ ...(p.aliases ?? {}) }),
+    retired: Object.freeze((p.retired ?? []).map((r) => r.id)),
+    ...upper,   // e.g. roles.chatDefault → CHAT_DEFAULT, roles.cheap → CHEAP
+    ...extra,
+  });
+}
+
+const DS = MODEL_CATALOG.cloud?.deepseek ?? {};
+/** DeepSeek: FLASH/PRO are the cheap/strong roles; CHAT_DEFAULT, JUDGE, LEGACY_JUDGE from roles. */
+export const DEEPSEEK = roleBlock("deepseek", {
+  FLASH: DS.roles?.cheap,
+  PRO: DS.roles?.strong,
+  anthropicBaseUrl: DS.anthropicBaseUrl ?? null,
+  peakHoursUtc: DS.peakHoursUtc ?? null,
+});
+/** Anthropic: DEFAULT/STRONG/MID/CHEAP/MAX/PREVIOUS_STRONG/PREVIOUS_MID + Claude Code CLI alias words. */
+export const ANTHROPIC = roleBlock("anthropic", { cliAliases: Object.freeze({ ...(MODEL_CATALOG.cloud?.anthropic?.cliAliases ?? {}) }) });
+export const OPENAI = roleBlock("openai");
+export const GEMINI = roleBlock("gemini");
+export const OPENROUTER = roleBlock("openrouter");
+export const GITHUB_MODELS = roleBlock("github-models");
+/** Ollama: BUILDER/CODER/JUDGE_FALLBACK/VISION/SMALL. */
+export const OLLAMA = roleBlock("ollama");
+export const VLLM = roleBlock("vllm");
+
+// ── DeepSeek pricing corners ─────────────────────────────────────────────────────────────────
+/** True when `date` falls inside DeepSeek's published peak window (UTC, weekdays). */
+export function isDeepSeekPeak(date = new Date()) {
+  const p = DEEPSEEK.peakHoursUtc;
+  if (!p) return true;
+  const day = date.getUTCDay();
+  if (Array.isArray(p.days) && !p.days.includes(day)) return false;
+  const mins = date.getUTCHours() * 60 + date.getUTCMinutes();
+  const toMin = (hhmm) => { const [h, m] = String(hhmm).split(":").map(Number); return h * 60 + (m || 0); };
+  return (p.ranges ?? []).some(([a, b]) => mins >= toMin(a) && mins < toMin(b));
+}
+
+/**
+ * $/1M for a DeepSeek id at a given (cacheHit, peak) corner. `peak` defaults to the clock via
+ * {@link isDeepSeekPeak}; pass `{ peak: true }` for the conservative upper bound.
+ * Returns { input, output } or null for a non-DeepSeek id.
+ */
+export function deepseekPricePer1M(id, { cacheHit = false, peak = null, at = new Date() } = {}) {
+  const m = modelInfo(id);
+  if (!m || m.provider !== "deepseek" || !m.pricePer1M?.peak) return null;
+  const corner = (peak ?? isDeepSeekPeak(at)) ? m.pricePer1M.peak : m.pricePer1M.offPeak;
+  return { input: cacheHit ? corner.cacheHit : corner.cacheMiss, output: corner.output };
+}
+
+/**
+ * Flat list price { input, output } $/1M for any catalog id: DeepSeek → PEAK CACHE-MISS (the
+ * conservative upper bound until cache-hit/off-peak accounting lands in cost()); other cloud →
+ * the provider's flat sheet; local → { 0, 0 }. null for an unknown id.
+ */
+export function listPricePer1M(id) {
+  const m = modelInfo(id);
+  if (!m) return null;
+  if (m.kind === "local") return { input: 0, output: 0 };
+  if (m.provider === "deepseek") return deepseekPricePer1M(id, { peak: true });
+  if (m.pricePer1M && Number.isFinite(m.pricePer1M.input)) return { input: m.pricePer1M.input, output: m.pricePer1M.output };
+  return null;
+}
+
+// ── cloud-clients PROVIDERS derivation ───────────────────────────────────────────────────────
+/**
+ * The full PROVIDERS table for cloud-clients.mjs, derived from every provider's `providerKeys`
+ * (plus, where `emitAliasesAsProviderKeys` is set, one entry per alias with `legacyAliasOf` so
+ * an old `/model deepseek-v4-flash` or stale COO_MODEL still resolves). Entry shape is what
+ * callModel/buildOpenAIBody/cost() already read: { kind, baseUrl, keyEnv, keyEnvFallback?,
+ * company?, model, priceIn, priceOut, tier, local?, noTemp?, legacyAliasOf? }.
+ */
+export function providerEntries() {
+  const out = {};
+  for (const [name, p] of INDEX.providers) {
+    if (!p.providerKeys || !p.baseUrl) continue;
+    const base = { kind: p.kind ?? "openai", baseUrl: p.baseUrl, keyEnv: p.keyEnv ?? null };
+    if (p.keyEnvFallback) base.keyEnvFallback = p.keyEnvFallback;
+    if (p.company && p.company !== name) base.company = p.company;
+    // Optional wire details cloud-clients.mjs honours when present: the strict-tools beta host
+    // and the per-seat isolation field name (DeepSeek declares both; other providers neither).
+    if (p.betaBaseUrl) base.betaBaseUrl = p.betaBaseUrl;
+    if (p.userIdField) base.userIdField = p.userIdField;
+    const entryFor = (modelId, overrides = {}) => {
+      const target = resolveModelId(modelId);
+      const m = modelInfo(target);
+      const price = listPricePer1M(target) ?? { input: 0, output: 0 };
+      const e = { ...base, model: modelId, priceIn: price.input, priceOut: price.output, tier: m?.tier ?? (p.locality === "local" ? "local" : "strong") };
+      if (m?.kind === "local" || overrides.local) e.local = true;
+      if (m?.noTemp || overrides.noTemp) e.noTemp = true;
+      if (overrides.legacyAliasOf) e.legacyAliasOf = overrides.legacyAliasOf;
+      return e;
+    };
+    for (const [key, spec] of Object.entries(p.providerKeys)) out[key] = entryFor(spec.model, spec);
+    if (p.emitAliasesAsProviderKeys) {
+      for (const [alias, target] of Object.entries(p.aliases ?? {})) {
+        if (out[alias] || Object.values(p.providerKeys).some((s) => s.model === alias)) continue;
+        out[alias] = entryFor(target, { legacyAliasOf: target });
+      }
+    }
+  }
+  return out;
+}
+/** Back-compat name: the DeepSeek slice of {@link providerEntries}. */
+export function deepseekProviderEntries() {
+  return Object.fromEntries(Object.entries(providerEntries()).filter(([, e]) => e.baseUrl === DEEPSEEK.baseUrl));
+}
+
+// ── fleet-manifest derivation ────────────────────────────────────────────────────────────────
+/**
+ * The rows fleet-manifest.mjs used to hand-maintain: `{ contextWindows, costEstimates }` keyed
+ * by id, for EVERY catalog model (cloud rows carry vramRequiredMb: null and "api"/"metered").
+ */
+export function fleetManifestModelRows() {
+  const contextWindows = {};
+  const costEstimates = {};
+  for (const id of ALL_MODEL_IDS) {
+    const m = modelInfo(id);
+    contextWindows[id] = {
+      contextWindow: m.contextWindow,
+      vramRequiredMb: m.vramRequiredMb ?? null,
+      architecture: m.architecture ?? m.provider,
+      capabilities: m.capabilities ?? [],
+    };
+    const price = listPricePer1M(id);
+    if (m.kind === "local") {
+      costEstimates[id] = { kind: "free", note: `local model, zero API cost.${m.note ? " " + m.note : ""}` };
+    } else if (m.provider === "deepseek") {
+      costEstimates[id] = { kind: "metered", usdPerMInput: price.input, usdPerMOutput: price.output,
+        note: `${m.displayName ?? id}: peak cache-miss list rates (model-catalog.json, verified ${providerInfo("deepseek")?.verifiedOn}); off-peak halves, cache hits ~50x cheaper` };
+    } else if (price) {
+      costEstimates[id] = { kind: "metered", usdPerMInput: price.input, usdPerMOutput: price.output,
+        note: `${m.displayName ?? id}: list rates (model-catalog.json, verified ${providerOf(id)?.verifiedOn ?? MODEL_CATALOG.verified})` };
+    } else {
+      costEstimates[id] = { kind: "metered", note: m.note ?? "pricing not recorded in model-catalog.json" };
+    }
+  }
+  return { contextWindows, costEstimates };
+}
+
+/** The subset of `ids` that are retired — for router/seat self-tests and the lint. */
+export function findRetiredIds(ids) {
+  return [...new Set(ids)].filter((id) => isRetiredModelId(id));
+}
+
+// ── self-test ────────────────────────────────────────────────────────────────────────────────
+export function runSelfTest({ log = console.log } = {}) {
+  let ok = true;
+  const check = (name, cond) => { log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  log("== model-catalog self-test ==\n");
+  check("catalog has a verified date", /^\d{4}-\d{2}-\d{2}$/.test(String(MODEL_CATALOG.verified)));
+  check("every provider role points at a current id of that provider",
+    [...INDEX.providers.values()].every((p) => Object.values(p.roles ?? {}).every((id) => id in (p.models ?? {}) || (p.aliases ?? {})[id])));
+  check("every providerKeys.model is a current id or a declared alias of that provider",
+    [...INDEX.providers.values()].every((p) => Object.values(p.providerKeys ?? {}).every((s) => s.model in (p.models ?? {}) || (p.aliases ?? {})[s.model])));
+  check("no alias target is itself an alias or retired",
+    Object.values(MODEL_ALIASES).every((t) => INDEX.byId.has(t) && !INDEX.retired.has(t)));
+  check("every retired id has an alias to its successor",
+    RETIRED_MODEL_IDS.every((id) => MODEL_ALIASES[id]));
+  check("no current id is also listed as retired",
+    ALL_MODEL_IDS.every((id) => !INDEX.retired.has(id)));
+  check("every model has a positive context window",
+    ALL_MODEL_IDS.every((id) => modelInfo(id).contextWindow > 0));
+  check("every cloud model has a list price",
+    ALL_MODEL_IDS.filter((id) => !isLocalModel(id)).every((id) => listPricePer1M(id)?.input > 0 && listPricePer1M(id)?.output > 0));
+  check("DeepSeek prices are four-corner, positive, and off-peak is half of peak",
+    DEEPSEEK.ids.every((id) => { const p = modelInfo(id).pricePer1M; return ["cacheHit", "cacheMiss", "output"].every((k) => p?.peak?.[k] > 0 && Math.abs(p.peak[k] - 2 * p.offPeak[k]) < 1e-9); }));
+  check("every local model has a VRAM figure",
+    ALL_MODEL_IDS.filter(isLocalModel).every((id) => Number.isFinite(modelInfo(id).vramRequiredMb)));
+  check("resolveModelId maps a retired id to its successor",
+    RETIRED_MODEL_IDS.every((id) => ALL_MODEL_IDS.includes(resolveModelId(id))));
+  check("providerEntries covers every providerKey and every DeepSeek alias, with prices", (() => {
+    const e = providerEntries();
+    const keys = [...INDEX.providers.values()].flatMap((p) => Object.keys(p.providerKeys ?? {}));
+    return keys.every((k) => e[k]?.model && e[k].baseUrl && Number.isFinite(e[k].priceIn))
+      && Object.keys(DEEPSEEK.aliases).every((a) => e[a]?.legacyAliasOf || e.deepseek?.model === a);
+  })());
+  check("isDeepSeekPeak: Tue 02:30 UTC is peak, Sat 02:30 UTC is not, Tue 12:00 UTC is not",
+    isDeepSeekPeak(new Date("2026-09-15T02:30:00Z")) && !isDeepSeekPeak(new Date("2026-09-19T02:30:00Z")) && !isDeepSeekPeak(new Date("2026-09-15T12:00:00Z")));
+  check("fleetManifestModelRows covers every catalog id",
+    Object.keys(fleetManifestModelRows().contextWindows).length === ALL_MODEL_IDS.length);
+  check("Claude CLI alias words resolve to current Anthropic ids",
+    Object.values(ANTHROPIC.cliAliases).every((id) => ANTHROPIC.ids.includes(id)));
+  log(`\n${ok ? "✓ self-test PASS — catalog invariants verified." : "✗ self-test FAIL"}`);
+  return ok ? 0 : 1;
+}
+
+// `process.argv` is undefined in a browser bundle (Next only shims `process.env`), so guard the
+// whole CLI branch instead of indexing into it.
+const isMain =
+  typeof process !== "undefined" &&
+  Array.isArray(process.argv) &&
+  Boolean(process.argv[1]) &&
+  /model-catalog\.mjs$/.test(String(process.argv[1]).replace(/\\/g, "/"));
+if (isMain) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--self-test")) process.exit(runSelfTest());
+  if (argv.includes("--print")) {
+    console.log(JSON.stringify({ DEEPSEEK, ANTHROPIC, OPENAI, GEMINI, OPENROUTER, GITHUB_MODELS, OLLAMA, VLLM, ALL_MODEL_IDS, MODEL_ALIASES, RETIRED_MODEL_IDS, providerEntries: providerEntries() }, null, 2));
+    process.exit(0);
+  }
+  if (argv.length) { console.error("usage: node dev-factory/lib/model-catalog.mjs --self-test | --print"); process.exit(64); }
+}

package/dev-factory/lib/seat-context.mjs

@@ -0,0 +1,199 @@
+// Shared dev-factory seat-context builder — the single source of truth for the
+// "DEV-FACTORY SEAT: <title> — <mandate>" lines that give a session its COO
+// identity and delegation protocol.
+//
+// THE ONE REGISTRY (epic HS-RJVM AC 2, task HS-DZOR): every front's seat text is
+// produced HERE, from dev-factory/seats.json and nowhere else. No front carries a
+// second copy of any seat's mandate; the two always-loaded instruction files
+// (COMMANDCODE.md, .cursor/rules/dev-factory-seats.mdc) hold an AUTO-GENERATED
+// managed block regenerated from this builder by `npm run seats:sync`, which is
+// derived output, not an authored copy.
+//
+// Consumed by:
+//   - scripts/claude-hooks/inject-coo-seat.mjs  → SessionStart context injection (Claude Code plugin)
+//   - scripts/sync-seat-context.mjs             → writes the managed blocks into COMMANDCODE.md
+//                                                  and .cursor/rules/dev-factory-seats.mdc
+//                                                  (Command Code + Cursor, which have no
+//                                                   session-start context-injection hook)
+//   - spexharness/src/seat-context.mjs          → the harness's front-agnostic loader: the
+//                                                  chat front, the dispatcher and the headless
+//                                                  seats all go through it, so they inherit this
+//                                                  builder's text rather than reimplementing it
+//
+// Keeping every surface on this one function is what guarantees DeepSeek
+// (Command Code), Composer (Cursor), a headless seat and Claude Code all receive
+// byte-identical seat context — no drift from seats.json.
+//
+// SESSION-CONTEXT BUDGET (registry v3). The registry declares, per row, how much of
+// the seat belongs in a session's opening context:
+//
+//   contract.sessionContext = "inject"     → the seat's full mandate is injected
+//   contract.sessionContext = "reference"  → the seat is only NAMED; its mandate stays
+//                                            in dev-factory/seats.json, to be read on demand
+//
+// Honouring that field is what keeps session-start injection from growing linearly
+// with the roster: when the registry went live with 27 rows, injecting every active
+// row unconditionally pushed the block from 12 lines to 22 (5,237 → ~9,190 bytes).
+// Rows whose contract says "reference" (the sub-agent seats, whose mandates the
+// sub-agent definitions already carry at dispatch time) are now named on one line
+// instead of injected in full.
+//
+// A row with no contract.sessionContext defaults to "inject" — v1/v2 registries and
+// hand-written fixtures keep their existing behaviour.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveCooModeEnabled } from './fleet-readiness.mjs';
+
+/** Repo root: honor CLAUDE_PROJECT_DIR, else two dirs up from dev-factory/lib. */
+export function repoRoot() {
+  if (process.env.CLAUDE_PROJECT_DIR) return process.env.CLAUDE_PROJECT_DIR;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+/** The single registry file every front reads. Relative to the repo root. */
+export const SEATS_REGISTRY_RELATIVE_PATH = path.join('dev-factory', 'seats.json');
+
+/** The two session-context modes a seat contract may declare. */
+export const SESSION_CONTEXT_MODES = Object.freeze(['inject', 'reference']);
+
+/** A row with no declared mode behaves exactly as it did before v3. */
+export const DEFAULT_SESSION_CONTEXT_MODE = 'inject';
+
+/**
+ * The marker that identifies an AUTO-GENERATED seat block (written by
+ * scripts/sync-seat-context.mjs from this builder). Seat text found in a file
+ * carrying this marker is derived output of the one registry, not a second copy.
+ */
+export const GENERATED_SEAT_BLOCK_MARKER = 'BEGIN DEV-FACTORY SEATS';
+
+/** Absolute path of the single registry file for `root`. */
+export function seatsRegistryPath(root = repoRoot()) {
+  return path.join(root, SEATS_REGISTRY_RELATIVE_PATH);
+}
+
+/**
+ * Read + parse the single registry. NEVER throws — a missing or corrupt
+ * seats.json is `null`, the same fail-soft posture every consumer relies on.
+ *
+ * @param {string} [root]
+ * @returns {object|null}
+ */
+export function loadSeatRegistry(root = repoRoot()) {
+  try {
+    return JSON.parse(readFileSync(seatsRegistryPath(root), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Every seat row in a registry, or [] for a missing/odd-shaped one. */
+export function registrySeats(registry) {
+  return Array.isArray(registry?.seats) ? registry.seats.filter((s) => s && typeof s === 'object') : [];
+}
+
+/** One seat row by id, or null. The single-registry lookup every front shares. */
+export function findSeat(registry, seatId) {
+  if (!seatId) return null;
+  return registrySeats(registry).find((s) => s.id === seatId) ?? null;
+}
+
+/**
+ * The session-context mode a seat's CONTRACT declares: 'inject' (full mandate in
+ * the opening context) or 'reference' (named only). Unknown/missing → the default.
+ *
+ * @param {object} seat
+ * @returns {'inject'|'reference'}
+ */
+export function seatSessionContextMode(seat) {
+  const declared = seat?.contract?.sessionContext;
+  return SESSION_CONTEXT_MODES.includes(declared) ? declared : DEFAULT_SESSION_CONTEXT_MODE;
+}
+
+/** A seat is injected/named at session start only while it is FILLED AND ENFORCED. */
+function isActive(seat) {
+  return seat?.active === true;
+}
+
+/** The one line a seat in "inject" mode contributes. */
+export function seatInjectLine(seat) {
+  return `DEV-FACTORY SEAT: ${seat.title} — ${seat.mandate}`;
+}
+
+/** The single line that NAMES every "reference" seat without carrying its mandate. */
+export function seatReferenceLine(seats) {
+  const named = seats.map((seat) => `${seat.title} (${seat.id})`).join(', ');
+  return `DEV-FACTORY SEATS (reference only — full mandate in ${SEATS_REGISTRY_RELATIVE_PATH.replace(/\\/g, '/')}): ${named}`;
+}
+
+/**
+ * The structured seat context — the shape every front formats from, so a chat
+ * front, the dispatcher, a headless seat and the Claude Code hook all agree on
+ * WHICH seats are in play before anyone turns them into text.
+ *
+ * @param {{ root?: string, registry?: object|null }} [opts]
+ *   `registry` (when supplied) is used as-is — no disk read — so callers and tests
+ *   can drive the builder from an in-memory roster.
+ * @returns {{
+ *   registry: object|null,
+ *   enabled: boolean,
+ *   reason: string,
+ *   inject: object[],
+ *   reference: object[],
+ *   text: string|null,
+ * }}
+ */
+export function buildSeatContextModel({ root = repoRoot(), registry } = {}) {
+  const reg = registry === undefined ? loadSeatRegistry(root) : registry;
+  if (!reg) {
+    return { registry: null, enabled: false, reason: 'registry missing or corrupt', inject: [], reference: [], text: null };
+  }
+
+  const coo = resolveCooModeEnabled(reg?.settings?.cooMode);
+  if (!coo.enabled) {
+    return { registry: reg, enabled: false, reason: coo.reason, inject: [], reference: [], text: null };
+  }
+
+  const active = registrySeats(reg).filter(isActive);
+  const inject = active.filter(
+    (seat) =>
+      seatSessionContextMode(seat) === 'inject' &&
+      typeof seat.title === 'string' &&
+      typeof seat.mandate === 'string',
+  );
+  const reference = active.filter(
+    (seat) => seatSessionContextMode(seat) === 'reference' && typeof seat.title === 'string',
+  );
+
+  const lines = inject.map(seatInjectLine);
+  if (reference.length > 0) lines.push(seatReferenceLine(reference));
+
+  return {
+    registry: reg,
+    enabled: true,
+    reason: coo.reason,
+    inject,
+    reference,
+    text: lines.length > 0 ? lines.join('\n') : null,
+  };
+}
+
+/**
+ * Build the seat-injection text, or null when nothing should be injected.
+ *
+ * Rules (MUST match the MCP server + the Claude SessionStart hook so every
+ * surface stays byte-identical — epic HS-CXO0 AC, epic HS-RJVM AC 2):
+ *   - missing/corrupt seats.json           → null
+ *   - resolveCooModeEnabled(...) === false → null   (cooMode false, or "auto" and fleet not ready)
+ *   - no active seat that yields a line    → null
+ *   - otherwise → one "DEV-FACTORY SEAT: <title> — <mandate>" line per ACTIVE seat whose
+ *     contract.sessionContext is "inject" (the default), followed — when the roster has
+ *     any — by a single line NAMING the active "reference" seats.
+ *
+ * @param {string} [root] repo root (defaults to repoRoot())
+ * @returns {string|null}
+ */
+export function buildSeatContext(root = repoRoot()) {
+  return buildSeatContextModel({ root }).text;
+}

package/dev-factory/lib/spec-io.mjs

@@ -0,0 +1,93 @@
+/**
+ * Spec lookup + frontmatter split for the standalone reviewer.
+ *
+ * Deliberately tiny: it finds a spec file under specs/ by id and splits the
+ * YAML frontmatter from the markdown body. It does NOT do a full YAML parse —
+ * the acceptance-criteria parser only needs the body in the common case (task
+ * specs carry criteria as a `## Acceptance criteria` checklist). The rare
+ * `acceptance:` frontmatter array is detected with a minimal scan.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/** Recursively collect every .md file under a directory.
+ *  Dot-directories (specs/.trash, .obsidian, …) are SKIPPED: regen-replaced tasks keep a
+ *  same-named retired body under specs/.trash/, and because ".trash" sorts first the
+ *  retired copy SHADOWED the live spec — the 2026-07-09 HS-ATW1 re-dispatch built the
+ *  retired task (wrong target, 4 stale ACs) instead of the amended live one. */
+function walkMarkdown(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith(".")) continue; // never resolve into .trash / dot-dirs
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) walkMarkdown(full, out);
+    else if (entry.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Find the spec file for an id. Matches the id anywhere in the basename
+ * (case-insensitive), so it tolerates both legacy `HS-TASK-XXXX-slug` and
+ * pipeline-first `HS-XXXX-TASK-slug` filenames during the MB2M migration.
+ *
+ * @param {string} specsDir absolute path to the vault's specs/ directory
+ * @param {string} specId e.g. "HS-TASK-9SHA" or a bare "9SHA"
+ * @returns {string|null} absolute file path, or null if not found
+ */
+export function findSpecFile(specsDir, specId) {
+  const needle = specId.toLowerCase();
+  const files = walkMarkdown(specsDir);
+  const basenames = files.map((f) => f.split(/[\\/]/).pop().toLowerCase());
+  const exact = files.find((f) => f.split(/[\\/]/).pop().toLowerCase() === `${needle}.md`);
+  if (exact) return exact;
+  const prefixMatches = files.filter((f) =>
+    f.split(/[\\/]/).pop().toLowerCase().startsWith(`${needle}-`),
+  );
+  if (prefixMatches.length === 1) return prefixMatches[0];
+  if (prefixMatches.length > 1) return null;
+  const loose = files.find((f) => basenames.includes(needle) || f.split(/[\\/]/).pop().toLowerCase().includes(needle));
+  return loose ?? null;
+}
+
+/**
+ * Read + split a spec file.
+ * @param {string} filePath
+ * @returns {{ id: string|null, repo: string|null, frontmatter: { acceptance?: string[] }|null, body: string, raw: string }}
+ */
+export function parseSpec(filePath) {
+  const raw = readFileSync(filePath, "utf8");
+  const m = raw.match(FRONTMATTER);
+  const fmText = m?.[1] ?? "";
+  const body = m ? raw.slice(m[0].length) : raw;
+
+  const id = fmText.match(/^id:\s*["']?([^"'\r\n]+)/m)?.[1]?.trim() ?? null;
+
+  // HS-OM28 multi-repo builds: a task may declare WHICH repo its build runs in via a
+  // `repo:` frontmatter key (a named-repo table key, resolved through
+  // dev-factory/routing-table.json `repos` by lib/build-root.mjs — never a path).
+  // Absent → null → the vault itself, byte-identical single-repo behavior.
+  const repo = fmText.match(/^repo:\s*["']?([^"'\r\n]+)/m)?.[1]?.trim() ?? null;
+
+  // Minimal detection of an `acceptance:` frontmatter list (block form).
+  let acceptance;
+  const accBlock = fmText.match(/^acceptance:\s*\r?\n((?:\s*-\s+.+\r?\n?)+)/m);
+  if (accBlock) {
+    acceptance = accBlock[1]
+      .split(/\r?\n/)
+      .map((l) => l.match(/^\s*-\s+(.+?)\s*$/)?.[1])
+      .filter(Boolean)
+      .map((s) => s.replace(/^["']|["']$/g, ""));
+  }
+
+  return {
+    id,
+    repo,
+    frontmatter: acceptance ? { acceptance } : null,
+    body,
+    raw,
+  };
+}

package/dev-factory/lib/sufficiency-score.mjs

@@ -125,8 +125,14 @@ const USER_STORIES_RE =
 const DONE_CRITERIA_RE =
   /##[ \t]*(?:Done[ \t]+When|Acceptance[ \t]+Criteria(?:\s*\([^)\n]*\))?|Definition[ \t]+of[ \t]+Done)[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i;
 
-/** "As a <role>, I want …" — a user story with a real, named role. */
-const USER_STORY_WITH_ROLE_RE = /\bas\s+an?\s+\S+/i;
+/**
+ * "As a <role>, I want …" — a user story with a real, named role.
+ * Also accepts "As the <role>, …" (e.g. "As the owner, I want …") — the
+ * dominant phrasing across this vault's single-owner captures, which "as a/an"
+ * alone silently failed to recognize as a role
+ * ([[HS-K4JN-NG84-DIAG-the-capture-sufficiency-gate-reports]]).
+ */
+const USER_STORY_WITH_ROLE_RE = /\bas\s+(?:an?|the)\s+\S+/i;
 /**
  * A real (not AI-illustrative) Example is labeled by provenance
  * (capture-guardrails §Example). Tolerates markdown emphasis around the label