heyspex 0.2.5 → 0.2.7

package/dev-factory/lib/dispatch-guard.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * dispatch-guard.mjs — pre-dispatch checks the controller runs BEFORE its first builder
+ * call, so a dispatch that can never pass its own gate is refused up front with the fix
+ * named (exit 3, gate_environment_fault) instead of burning iterations on it.
+ *
+ * Born 2026-08-26 (HS-VHQG): the frozen check ran a test file that did not exist, the
+ * single-target builder only writes its target, and the controller spent 3 iterations x
+ * (best-of-3 + self-repair) + 3 DeepSeek diagnoses before escalating "no progress:
+ * identical failure signature x3" — a harness fault reported as a model fault.
+ *
+ *   node dev-factory/lib/dispatch-guard.mjs --self-test
+ */
+
+/** Normalize a repo path for loose comparison (posix separators, no leading ./). */
+function normRel(p) {
+  return String(p ?? "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+/** True when the builder's --target set (comma-separated) can WRITE the scoped test file —
+ *  i.e. the test is itself a target. The builder only ever writes its targets. */
+export function buildCanCreateTest(targetArg, testArg) {
+  const test = normRel(testArg);
+  if (!test) return true; // no scoped test → nothing to guard
+  const targets = String(targetArg ?? "").split(",").map((s) => normRel(s.trim())).filter(Boolean);
+  return targets.some((t) => t === test || t.endsWith(`/${test}`) || test.endsWith(`/${t}`));
+}
+
+/** Plain-language abort reason for the pre-dispatch guard (rides the exit-3 path). */
+export function impossibleTestReason(targetArg, testArg) {
+  return `the scoped test does not exist yet and this build cannot create it — the frozen check runs ${testArg}, `
+    + `but this controller builds ONE target (--target ${targetArg}) and the builder only writes its target. `
+    + `No candidate can ever turn this gate green, so no builder was called and no iteration was spent. `
+    + `This task needs two files (the implementation + a new test), which is the routing table's "multi-file implementation" shape: `
+    + `route it to the multi-file seat (a harness sub-agent with an explicit cheap model — never the single-target fleet build), `
+    + `or split the spec so the test file lands as its own greenfield task first (--target ${testArg}) and this task's gate can then find it.`;
+}
+
+/** vitest's "No test files found" banner (it prints its include/exclude globs after it) —
+ *  a gate that found nothing to run, never a red test. */
+export function isNoTestFilesOutput(output) {
+  const s = String(output ?? "");
+  if (/No test files found/i.test(s)) return true;
+  // Older vitest prints only the include/exclude listing; treat it as no-test-files ONLY when
+  // nothing in the output looks like a test result.
+  // No \b here: vitest wraps the labels in dim ANSI codes ("[2minclude:") that glue to the word.
+  return /include:\s/.test(s) && /exclude:\s/.test(s)
+    && !/\b(passed|failed)\b.*\btests?\b/i.test(s) && !/✓|✗|×|FAIL\s+src/.test(s);
+}
+
+// ── self-test ────────────────────────────────────────────────────────────────────────
+function runSelfTest() {
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  console.log("== dispatch-guard.mjs self-test ==\n");
+  check("impl target + new test (HS-VHQG shape) → cannot create", !buildCanCreateTest("spex-console/src/lib/cli/init.ts", "spex-console/src/lib/cli/init.customer-vault.test.ts"));
+  check("test IS the target (greenfield test task) → can create", buildCanCreateTest("spex-console/src/w.test.ts", "spex-console/src/w.test.ts"));
+  check("comma target set containing the test → can create", buildCanCreateTest("a/x.ts,a/x.test.ts", "a/x.test.ts"));
+  check("runner-relative test vs repo-relative target still matches", buildCanCreateTest("spex-console/src/w.test.ts", "src/w.test.ts"));
+  check("backslash paths normalize", buildCanCreateTest("spex-console\\src\\w.test.ts", "spex-console/src/w.test.ts"));
+  check("no scoped test → nothing to guard", buildCanCreateTest("a.ts", ""));
+  const reason = impossibleTestReason("a.ts", "a.test.ts");
+  check("reason names both files, the multi-file seat, and the greenfield split", /a\.test\.ts/.test(reason) && /--target a\.ts/.test(reason) && /multi-file seat/.test(reason) && /greenfield/.test(reason));
+  check("vitest no-test-files banner → environmental", isNoTestFilesOutput("No test files found, exiting with code 1\ninclude: src/**/*.test.ts\nexclude: **/node_modules/**"));
+  check("include/exclude listing with no results → environmental", isNoTestFilesOutput("include: src/**/*.test.ts\nexclude:  **/node_modules/**"));
+  check("a real failing test run is NOT environmental", !isNoTestFilesOutput("FAIL  src/lib/x.test.ts > does thing\nTests  1 failed | 2 passed (3)\ninclude: src/**/*.test.ts exclude: **/node_modules/**"));
+  check("a passing run is NOT environmental", !isNoTestFilesOutput("✓ src/x.test.ts (3 tests)\nTests 3 passed (3)"));
+  check("empty output is NOT environmental", !isNoTestFilesOutput(""));
+  console.log(ok ? "\n✓ dispatch-guard self-test passed" : "\n✗ dispatch-guard self-test FAILED");
+  return ok ? 0 : 1;
+}
+
+if (process.argv.includes("--self-test") && process.argv[1] && /dispatch-guard\.mjs$/.test(process.argv[1].replace(/\\/g, "/"))) {
+  process.exit(runSelfTest());
+}

package/dev-factory/lib/local-firecrawl.mjs

@@ -0,0 +1,294 @@
+/**
+ * local-firecrawl.mjs — zero-config discovery of a self-hosted Firecrawl running in THIS machine's
+ * Docker, plus a minimal search/scrape client for it.
+ *
+ * Owner ruling 2026-10-17: research in a customer repo (the `heyspex` npm package) finds URLs
+ * through a self-hosted Firecrawl in the user's LOCAL Docker. "No ENV variable required. It will
+ * just see the Docker>Firecrawl on the local and it will utilize it." So this module never needs
+ * configuration:
+ *
+ *   1. optional override — HEYSPEX_FIRECRAWL_URL, then FIRECRAWL_BASE_URL (ignored when it points
+ *      at the hosted api.firecrawl.dev: hosted credits are ask-before-spend, never automatic);
+ *   2. `docker ps` — the Firecrawl API container and the host port it publishes;
+ *   3. the self-hosted default, http://localhost:3002 (SELF_HOST.md in github.com/firecrawl/firecrawl).
+ *
+ * Every candidate is probed with a GET on its origin before use. Hosted Firecrawl is filtered out
+ * of every list, no API key is ever sent (a local stack runs with USE_DB_AUTHENTICATION=false),
+ * and nothing here throws: failures come back as `{ ok: false, reason }`.
+ *
+ * Node built-ins only — this file ships in the npm package and must not import SpexFleet code.
+ */
+import { spawnSync } from 'node:child_process';
+
+export const DEFAULT_LOCAL_FIRECRAWL_PORT = 3002;
+export const DEFAULT_LOCAL_FIRECRAWL_BASE_URLS = Object.freeze([
+  `http://127.0.0.1:${DEFAULT_LOCAL_FIRECRAWL_PORT}/v2`,
+  `http://localhost:${DEFAULT_LOCAL_FIRECRAWL_PORT}/v2`,
+]);
+
+/** One-line setup instructions printed after every FIRECRAWL_UNAVAILABLE reason. */
+export const LOCAL_FIRECRAWL_SETUP_HINT =
+  'Research needs a self-hosted Firecrawl running in your local Docker. Start Docker Desktop, then ' +
+  'start the Firecrawl stack: `git clone https://github.com/firecrawl/firecrawl.git && cd firecrawl`, ' +
+  'create `.env` in that folder with `PORT=3002` and `USE_DB_AUTHENTICATION=false`, then ' +
+  '`docker compose build && docker compose up -d` (official steps: SELF_HOST.md in ' +
+  'github.com/firecrawl/firecrawl). No API key or environment variable is needed: it is found ' +
+  'automatically on localhost:3002 or from `docker ps`.';
+
+/** True for the hosted Firecrawl API (the thing that spends real credits). */
+export function isHostedFirecrawlUrl(url) {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return host === 'firecrawl.dev' || host.endsWith('.firecrawl.dev');
+  } catch {
+    return false;
+  }
+}
+
+/** Trim, drop trailing slashes, and add the `/v2` API path when the URL has no version path. */
+export function normalizeFirecrawlBaseUrl(url) {
+  const raw = String(url ?? '').trim().replace(/\/+$/, '');
+  if (!raw) return '';
+  try {
+    const u = new URL(raw);
+    if (!/^https?:$/.test(u.protocol)) return '';
+    if (!/\/v\d+$/.test(u.pathname.replace(/\/+$/, ''))) u.pathname = `${u.pathname.replace(/\/+$/, '')}/v2`;
+    return u.toString().replace(/\/+$/, '');
+  } catch {
+    return '';
+  }
+}
+
+function originOf(baseUrl) {
+  try {
+    return new URL(baseUrl).origin;
+  } catch {
+    return '';
+  }
+}
+
+// ── docker ps ───────────────────────────────────────────────────────────────────────────────────
+
+const NON_API_SERVICE_RE = /playwright|postgres|redis|rabbit|searxng|worker/i;
+
+/** Is this `docker ps` row the Firecrawl API container (not its playwright/db/queue siblings)? */
+export function isFirecrawlApiContainer({ name = '', image = '' } = {}) {
+  const imageRepo = String(image).split('@')[0];
+  const lastSeg = imageRepo.split('/').pop().split(':')[0].toLowerCase();
+  const n = String(name).toLowerCase();
+  if (NON_API_SERVICE_RE.test(lastSeg)) return false;
+  if (lastSeg === 'firecrawl' || lastSeg === 'firecrawl-api' || lastSeg === 'firecrawl_api') return true;
+  // `docker compose build` from a checkout tags the image after the project; the container name
+  // (firecrawl-api-1 / firecrawl_api_1) still says what it is.
+  return /firecrawl/.test(n) && /(^|[-_])api([-_]\d+)?$/.test(n) && !NON_API_SERVICE_RE.test(n);
+}
+
+/**
+ * Parse a `docker ps` Ports column, e.g. `0.0.0.0:3002->3002/tcp, [::]:3002->3002/tcp`, into
+ * published TCP mappings `{ hostIp, hostPort, containerPort }`. Unpublished ports (`6379/tcp`) are
+ * dropped. Ranges map their first port.
+ */
+export function parseDockerPorts(portsText) {
+  const out = [];
+  for (const part of String(portsText ?? '').split(',')) {
+    const m = part.trim().match(/^(?:(\[[^\]]*\]|[^:\s]+):)?(\d+)(?:-\d+)?->(\d+)(?:-\d+)?\/tcp$/);
+    if (!m) continue;
+    out.push({ hostIp: m[1] ?? '', hostPort: Number(m[2]), containerPort: Number(m[3]) });
+  }
+  return out;
+}
+
+function hostForBinding(hostIp) {
+  const ip = String(hostIp).replace(/^\[|\]$/g, '');
+  if (!ip || ip === '0.0.0.0' || ip === '127.0.0.1') return '127.0.0.1';
+  if (ip === '::' || ip === '::1') return '[::1]';
+  return ip.includes(':') ? `[${ip}]` : ip;
+}
+
+/**
+ * Parse `docker ps --format '{{.Names}}\t{{.Image}}\t{{.Ports}}'` output into the Firecrawl API
+ * containers it lists, each with the base URLs its published ports reach.
+ */
+export function parseDockerPsFirecrawl(text) {
+  const rows = [];
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const [name = '', image = '', ports = ''] = line.split('\t');
+    if (!isFirecrawlApiContainer({ name, image })) continue;
+    const maps = parseDockerPorts(ports);
+    // The API listens on PORT (3002 by default) inside the container; prefer that mapping.
+    const preferred = maps.filter((p) => p.containerPort === DEFAULT_LOCAL_FIRECRAWL_PORT);
+    const ordered = [...preferred, ...maps.filter((p) => p.containerPort !== DEFAULT_LOCAL_FIRECRAWL_PORT)];
+    const seen = new Set();
+    const baseUrls = [];
+    for (const p of ordered) {
+      const u = `http://${hostForBinding(p.hostIp)}:${p.hostPort}/v2`;
+      if (seen.has(u)) continue;
+      seen.add(u);
+      baseUrls.push(u);
+    }
+    rows.push({ name: name.trim(), image: image.trim(), baseUrls });
+  }
+  return rows;
+}
+
+/** Default docker runner. Returns `{ status, stdout, stderr, error }` like spawnSync; never throws. */
+export function runDockerPs() {
+  try {
+    const r = spawnSync('docker', ['ps', '--format', '{{.Names}}\t{{.Image}}\t{{.Ports}}'], {
+      encoding: 'utf8',
+      timeout: 8000,
+      windowsHide: true,
+    });
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '', error: r.error ?? null };
+  } catch (e) {
+    return { status: null, stdout: '', stderr: '', error: e };
+  }
+}
+
+/**
+ * Ask Docker which Firecrawl API containers are running.
+ * @returns {{ state: 'missing'|'down'|'running', containers: Array<{name,image,baseUrls}>, detail?: string }}
+ */
+export function dockerFirecrawlContainers({ runDocker = runDockerPs } = {}) {
+  let r;
+  try {
+    r = runDocker();
+  } catch (e) {
+    return { state: 'missing', containers: [], detail: e?.message || String(e) };
+  }
+  if (r?.error) {
+    const code = r.error.code;
+    return { state: code === 'ENOENT' ? 'missing' : 'down', containers: [], detail: r.error.message || String(code) };
+  }
+  if (r?.status !== 0) {
+    return { state: 'down', containers: [], detail: String(r?.stderr || '').trim().split(/\r?\n/)[0] || `docker ps exited ${r?.status}` };
+  }
+  return { state: 'running', containers: parseDockerPsFirecrawl(r.stdout) };
+}
+
+// ── probing ─────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * GET the origin of a candidate. `requireSignature` (used for the unconfirmed localhost:3002 guess)
+ * also requires the body to look like Firecrawl, so an unrelated service on that port is not used.
+ */
+export async function probeFirecrawlBase(baseUrl, { httpFetch = globalThis.fetch, timeoutMs = 3000, requireSignature = false } = {}) {
+  const origin = originOf(baseUrl);
+  if (!origin) return { up: false, reason: `invalid URL ${baseUrl}` };
+  try {
+    const res = await httpFetch(`${origin}/`, { method: 'GET', signal: AbortSignal.timeout(timeoutMs) });
+    if (!requireSignature) return { up: true, status: res?.status ?? 0 };
+    let body = '';
+    try {
+      body = typeof res?.text === 'function' ? await res.text() : JSON.stringify(await res.json());
+    } catch {
+      body = '';
+    }
+    if (/firecrawl|SCRAPERS-JS/i.test(body)) return { up: true, status: res?.status ?? 0 };
+    return { up: false, reason: `${origin} answered but is not a Firecrawl API` };
+  } catch (e) {
+    return { up: false, reason: `${origin} not reachable (${e?.cause?.code || e?.name || e?.message || e})` };
+  }
+}
+
+/**
+ * Find a local self-hosted Firecrawl. Never throws, never returns a hosted URL.
+ * @returns {Promise<{ok:true, baseUrl:string, source:'override'|'docker'|'default', container?:string}
+ *   | {ok:false, reason:string, docker:string}>}
+ */
+export async function detectLocalFirecrawl({ env = process.env, runDocker = runDockerPs, httpFetch = globalThis.fetch, timeoutMs = 3000 } = {}) {
+  const candidates = [];
+  const seen = new Set();
+  const notes = [];
+  const push = (url, source, extra = {}) => {
+    const u = normalizeFirecrawlBaseUrl(url);
+    if (!u || isHostedFirecrawlUrl(u) || seen.has(u)) return;
+    seen.add(u);
+    candidates.push({ baseUrl: u, source, ...extra });
+  };
+
+  for (const key of ['HEYSPEX_FIRECRAWL_URL', 'FIRECRAWL_BASE_URL']) {
+    const v = String(env?.[key] ?? '').trim();
+    if (!v) continue;
+    if (isHostedFirecrawlUrl(v)) notes.push(`${key} points at hosted Firecrawl and was ignored`);
+    else push(v, 'override');
+  }
+
+  const docker = dockerFirecrawlContainers({ runDocker });
+  for (const c of docker.containers) {
+    for (const u of c.baseUrls) push(u, 'docker', { container: c.name });
+  }
+  for (const u of DEFAULT_LOCAL_FIRECRAWL_BASE_URLS) push(u, 'default');
+
+  const reasons = [];
+  for (const c of candidates) {
+    const probe = await probeFirecrawlBase(c.baseUrl, { httpFetch, timeoutMs, requireSignature: c.source === 'default' });
+    if (probe.up) return { ok: true, baseUrl: c.baseUrl, source: c.source, ...(c.container ? { container: c.container } : {}) };
+    reasons.push(probe.reason);
+  }
+
+  let headline;
+  if (docker.state === 'missing') headline = 'Docker is not installed or not on PATH';
+  else if (docker.state === 'down') headline = 'Docker is installed but not running';
+  else if (!docker.containers.length) headline = 'Docker is running but no Firecrawl API container is up';
+  else if (!docker.containers.some((c) => c.baseUrls.length)) headline = `Firecrawl container ${docker.containers[0].name} publishes no host port`;
+  else headline = `Firecrawl container ${docker.containers[0].name} is up but not answering yet (still starting? retry in a minute)`;
+  const detail = [...notes, ...reasons].join('; ');
+  return { ok: false, docker: docker.state, reason: `${headline}${detail ? ` (${detail})` : ''}` };
+}
+
+// ── search / scrape against a local instance (no API key, no credits) ─────────────────────────────
+
+async function postJson(baseUrl, path, body, { httpFetch, timeoutMs }) {
+  const res = await httpFetch(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  let json = null;
+  try {
+    json = await res.json();
+  } catch {
+    json = null;
+  }
+  return { res, json };
+}
+
+/** @returns {Promise<{ok:true, results:Array<{title,url,snippet}>} | {ok:false, error:string}>} */
+export async function localFirecrawlSearch(baseUrl, query, { limit = 6, httpFetch = globalThis.fetch, timeoutMs = 45000 } = {}) {
+  if (isHostedFirecrawlUrl(baseUrl)) return { ok: false, error: 'refused: hosted Firecrawl endpoint' };
+  try {
+    const { res, json } = await postJson(baseUrl, '/search', { query, limit, sources: [{ type: 'web' }] }, { httpFetch, timeoutMs });
+    if (!res?.ok || json?.success === false) return { ok: false, error: json?.error || `HTTP ${res?.status ?? 0}` };
+    const rows = json?.data?.web ?? (Array.isArray(json?.data) ? json.data : []);
+    return {
+      ok: true,
+      results: rows.map((r) => ({
+        title: r.title ?? '',
+        url: r.url ?? '',
+        snippet: r.description ?? (typeof r.markdown === 'string' ? r.markdown.slice(0, 300) : ''),
+      })),
+    };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+
+/** @returns {Promise<{ok:true, title:string, markdown:string, status:number} | {ok:false, error:string}>} */
+export async function localFirecrawlScrape(baseUrl, url, { httpFetch = globalThis.fetch, timeoutMs = 90000 } = {}) {
+  if (isHostedFirecrawlUrl(baseUrl)) return { ok: false, error: 'refused: hosted Firecrawl endpoint' };
+  try {
+    const { res, json } = await postJson(baseUrl, '/scrape', { url, formats: ['markdown'], onlyMainContent: true }, { httpFetch, timeoutMs });
+    if (!res?.ok || json?.success === false) return { ok: false, error: json?.error || `HTTP ${res?.status ?? 0}` };
+    return {
+      ok: true,
+      title: json?.data?.metadata?.title ?? '',
+      markdown: json?.data?.markdown ?? '',
+      status: json?.data?.metadata?.statusCode ?? res?.status ?? 0,
+    };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}

package/dev-factory/lib/runner-path.mjs

@@ -0,0 +1,51 @@
+/**
+ * runner-path.mjs — make a scoped test/target path relative to the cwd its runner
+ * actually executes in.
+ *
+ * Born 2026-10-15 (HS-7BYJ baseline): the controller's red-baseline pre-check ran scoped
+ * vitest from `<worktree>/spex-console` (where the vitest config lives) but handed it the
+ * REPO-relative test path `spex-console/src/lib/x.test.ts`. vitest's file filter then
+ * matched nothing ("No test files found, exiting with code 1") and the run was classified
+ * as gate_environment_fault before any builder ran. One helper, used at every call site
+ * that runs a tool from a package subdirectory, instead of patching one site.
+ */
+import { isAbsolute, relative } from "node:path";
+
+const toPosix = (p) => String(p ?? "").replace(/\\/g, "/");
+const stripDot = (p) => p.replace(/^(\.\/)+/, "");
+const caseFold = (p) => (process.platform === "win32" ? p.toLowerCase() : p);
+
+/** `child` is `base` or under it (posix strings, case-insensitive on Windows). */
+function isUnder(child, base) {
+  const c = caseFold(child), b = caseFold(base).replace(/\/+$/, "");
+  return c === b || c.startsWith(`${b}/`);
+}
+
+/**
+ * Convert `path` to a path relative to the runner's cwd.
+ *
+ * @param {string} path      repo-relative ("spex-console/src/x.test.ts"), already
+ *                           cwd-relative ("src/x.test.ts"), absolute, or backslashed.
+ * @param {object} [opts]
+ * @param {string} [opts.cwdRel=""]  the runner's cwd, relative to the repo/worktree root
+ *                           ("spex-console", "companion", "vendor/heyspex-mcp"; "" = root).
+ * @param {string[]} [opts.roots=[]] absolute roots an absolute `path` may live under (the
+ *                           gate worktree, the main repo) — it is re-rooted against the first
+ *                           match. An absolute path under none of them is returned posix-ified.
+ * @returns {string} posix path relative to `cwdRel`. A repo-relative path OUTSIDE `cwdRel`
+ *                   (e.g. vendor/… while the runner sits in spex-console) is returned
+ *                   unchanged — it is either already cwd-relative or not this runner's file.
+ */
+export function toRunnerRelativePath(path, { cwdRel = "", roots = [] } = {}) {
+  let p = stripDot(toPosix(path).trim());
+  if (!p) return p;
+  const cwd = stripDot(toPosix(cwdRel)).replace(/^\/+|\/+$/g, "");
+  if (isAbsolute(p) || /^[A-Za-z]:\//.test(p)) {
+    const root = roots.map((r) => toPosix(r).replace(/\/+$/, "")).find((r) => r && isUnder(p, r));
+    if (!root) return p;
+    p = p.slice(root.length).replace(/^\/+/, "");
+  }
+  if (!cwd) return p;
+  if (isUnder(p, cwd)) return toPosix(relative(cwd, p)) || ".";
+  return p;
+}

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

@@ -45,6 +45,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveCooModeEnabled } from './fleet-readiness.mjs';
+import { isDevFactoryOverlayOpen } from '../../vendor/heyspex-mcp/dev-factory-overlay.mjs';
 
 /** Repo root: honor CLAUDE_PROJECT_DIR, else two dirs up from dev-factory/lib. */
 export function repoRoot() {
@@ -52,6 +53,19 @@ export function repoRoot() {
   return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 }
 
+/**
+ * The AMBIENT repo root — the one a caller gets when it passes no root — or null when the
+ * owner dev-factory overlay is closed there ([[HS-R475-C86Z-TASK-load-the-owner-dev-factory-overlay-only]]).
+ * repoRoot() honours CLAUDE_PROJECT_DIR, so in another developer's repo (or an installed
+ * package) this is null and seats.json is never read: the owner's seats never inject into a
+ * customer session. An EXPLICIT root is the caller's own choice (fixtures, sync-seat-context)
+ * and is not re-gated.
+ */
+export function ambientOverlayRoot(env = process.env) {
+  const root = repoRoot();
+  return isDevFactoryOverlayOpen(root, { env }) ? root : null;
+}
+
 /** The single registry file every front reads. Relative to the repo root. */
 export const SEATS_REGISTRY_RELATIVE_PATH = path.join('dev-factory', 'seats.json');
 
@@ -80,9 +94,11 @@ export function seatsRegistryPath(root = repoRoot()) {
  * @param {string} [root]
  * @returns {object|null}
  */
-export function loadSeatRegistry(root = repoRoot()) {
+export function loadSeatRegistry(root = undefined) {
+  const r = root ?? ambientOverlayRoot();
+  if (!r) return null;
   try {
-    return JSON.parse(readFileSync(seatsRegistryPath(root), 'utf8'));
+    return JSON.parse(readFileSync(seatsRegistryPath(r), 'utf8'));
   } catch {
     return null;
   }
@@ -144,7 +160,7 @@ export function seatReferenceLine(seats) {
  *   text: string|null,
  * }}
  */
-export function buildSeatContextModel({ root = repoRoot(), registry } = {}) {
+export function buildSeatContextModel({ root, registry } = {}) {
   const reg = registry === undefined ? loadSeatRegistry(root) : registry;
   if (!reg) {
     return { registry: null, enabled: false, reason: 'registry missing or corrupt', inject: [], reference: [], text: null };
@@ -194,6 +210,6 @@ export function buildSeatContextModel({ root = repoRoot(), registry } = {}) {
  * @param {string} [root] repo root (defaults to repoRoot())
  * @returns {string|null}
  */
-export function buildSeatContext(root = repoRoot()) {
+export function buildSeatContext(root = undefined) {
   return buildSeatContextModel({ root }).text;
 }