heyspex 0.2.6 → 0.2.7

package/bin/hs.mjs

@@ -13,6 +13,7 @@
  */
 import { BINDING_VERBS, runVaultBindingCommand } from "./hs-vault-binding.mjs";
 import { findProjectRoot } from "../scripts/lib/customer-kit.mjs";
+import { companionDoctorRow } from "../scripts/lib/companion-install.mjs";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
@@ -86,15 +87,19 @@ function helpForThisInstall(lines) {
   if (!IS_INSTALLED_PACKAGE) return lines;
   const out = [];
   for (const line of lines) {
+    if (line.startsWith("  hs seat set|reset|assignments")) {
+      out.push("  hs seat list|set|reset [--harness <h>]     Your own model per SpexFleet seat in this vault (Claude Code / Copilot)");
+      continue;
+    }
     if (DEV_ONLY_HELP_PREFIXES.some((p) => line.startsWith(p))) continue;
     if (line.startsWith("  hs companion start|stop|status|build")) {
-      out.push("  hs companion start|stop|status            Desktop companion tray app (not in the npm package yet)");
+      out.push("  hs companion start|stop|status            Desktop companion tray app (installed by `hs companion install`)");
       continue;
     }
     out.push(line);
   }
   out.push(
-    "HeySpex developer-only verbs (hs server, hs factory, hs seat, hs admin, hs queue,",
+    "HeySpex developer-only verbs (hs server, hs factory, hs seat add|update|disable, hs admin, hs queue,",
     "hs doctrine, hs companion build) need a HeySpex source checkout and are not",
     "listed here. Neither are verbs whose implementation the npm package does not",
     "carry (hs agent, hs chat, hs code-watcher, hs harness, hs hooks, hs import,",
@@ -678,13 +683,12 @@ function usageLines() {
       "  hs worktree list|alloc|release|reap [--json] [--dry-run]  Session/build worktree registry (HS-03DO)",
       "  hs view <surface> [spec-id] [--width N --height N --browser edge|chrome]  Open one surface in a chromeless app-mode window",
       "  hs server stop [--json]                    Stop the spex-console dev server (any terminal)",
-      "  hs source status|preflight|commit|push   SpexSource local git operations",
-      "  hs source identity [show|set|clear]      Git author identity (set/clear are human-only; see hs source --help)",
       "  hs defer <id> [--until <when>] [--json]    Time-shift a spec (defer_until)",
       "  hs undefer <id> [--json]                   Clear a spec's defer_until",
       "  hs spawn [<id>] [--dry-run] [--json]       Launch a fresh /hs-next agent in a new terminal",
       '  hs capture "<text>"|--clipboard|--file <p> [--add]  Capture → console drafts (--add chains a group)',
       "  hs companion start|stop|status|build     Desktop companion tray app",
+      "  hs companion install [--quiet] [--dry-run]  Download, verify and run the signed SpexCompanion setup (Windows x64)",
       "  hs companion settings [list|get <k>|set <k> <v>] [--json]  Every Companion setting (console-backed)",
       "  hs companion mute|unmute|volume|orb|wake|activation|hotkey [<v>]  Setting shortcuts (omit <v> to read)",
       "  hs registry list [--json]                  List launch registry entries",
@@ -702,6 +706,7 @@ function usageLines() {
       "  hs next assist|auto <milestone...> --launch  Arm a dispatcher run on one or more milestones",
       "  hs model [<seat>] [--launch|--fleet]       Every seat and the model set for it",
       "  hs seat list|add|update|disable [--json]   Read/add/update/disable a seat in the registry (dev-factory/seats.json)",
+      "  hs seat set|reset|assignments [--harness]  Your own model per SpexFleet seat, this vault (customers: hs seat list|set|reset)",
       "  hs voice add|build|show|set|test|refresh|export  Build and manage a coded voice profile",
       "  hs trash [list|restore|empty]              The bin spec deletes go into",
       "  hs auto [filename] [--json]                Resolve /hs-auto dispatch plan",
@@ -731,6 +736,9 @@ function usageLines() {
       "                                              search/scrape/crawl CLI (standalone script,",
       "                                              not an `hs` verb; also reachable from the",
       "                                              Companion)",
+      "  node dev-factory/spexcrawl/firecrawl-cli.mjs search|scrape  Firecrawl — finds the",
+      "                                              self-hosted Firecrawl in this machine's",
+      "                                              Docker (no env var, no API key)",
       "",
       "Control plane (Neon — requires a reachable console):",
       "  hs pin get|set <id>|clear                  Read/set/clear the on-deck pin",
@@ -916,6 +924,11 @@ function runStandaloneDoctor(args, vaultRoot) {
   if (templateRow.status === "fail") report.ok = false;
   report.checks.push(templateRow);
 
+  // `companion` (HS-056P): is SpexCompanion installed? Optional, so it is never
+  // a failure -- missing on Windows is a warn that offers
+  // `npx heyspex companion install`; other platforms get a skipped note.
+  report.checks.push(companionDoctorRow());
+
   // `connection` ([[HS-W73V-WW9R-TASK-make-both-doctor-shapes-fail-on-cloud]],
   // invariants 8 and 10): the BUNDLED `hs connect --check --json` from the
   // invoked cwd, folded by the SAME function the full doctor uses
@@ -1096,8 +1109,22 @@ export const NOT_IN_PACKAGE_VERBS = Object.freeze({
   factory: "SpexFleet/dev-factory internals are platform-only.",
   doctrine: "SpexCode Doctrine synthesis internals are platform-only.",
   bench: "SpexCode bench internals are platform-only.",
+  server: "the spex-console dev server is part of the HeySpex source checkout; the hosted console is app.heyspex.com.",
 });
 
+/**
+ * Is this `hs <verb> ... --help|-h` (a help flag after the verb, before any
+ * `--` end-of-options marker)? Bare `hs --help` is handled before dispatch.
+ * @param {string[]} argv the argv after the global --vault flag is removed
+ */
+export function isHelpInvocation(argv) {
+  for (const a of argv.slice(1)) {
+    if (a === "--") return false;
+    if (a === "--help" || a === "-h") return true;
+  }
+  return false;
+}
+
 /**
  * The NOT_IN_PACKAGE_VERBS key this invocation hits from an installed
  * package, or null. Pure apart from `installed`.
@@ -1121,6 +1148,21 @@ export function notInPackageMessage(key) {
   );
 }
 
+/**
+ * Does `hs seat <command>` go to the customer seat-assignment CLI
+ * (vendor/heyspex-mcp/seat-assign-cli.mjs, epic HS-K9L7)? Installed package:
+ * list|assignments|set|reset|defaults|report-fallback|help (and a bare `hs seat`).
+ * Source checkout: the same minus `list`/bare, which stay the dev-factory
+ * registry (`hs-seat.ts`).
+ */
+export function routesToSeatAssignCli(namespace, command, { installed = IS_INSTALLED_PACKAGE } = {}) {
+  if (namespace !== "seat") return false;
+  if (installed) {
+    return command === undefined || ["list", "assignments", "set", "reset", "defaults", "report-fallback", "help", "--help", "-h"].includes(command);
+  }
+  return ["assignments", "set", "reset", "defaults", "report-fallback"].includes(command);
+}
+
 function main(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     usage();
@@ -1152,6 +1194,16 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
+  // `hs seat list|set|reset|defaults|report-fallback` — the signed-in user's OWN
+  // seat models (HS-K9L7). Installed package: these subcommands. Source checkout:
+  // set|reset|defaults|assignments|report-fallback (list stays the registry).
+  if (routesToSeatAssignCli(namespace, command)) {
+    import(pathToFileURL(path.join(PKG_ROOT, "vendor", "heyspex-mcp", "seat-assign-cli.mjs")).href)
+      .then((m) => m.runSeatAssignCli(argv.slice(1)))
+      .then((code) => process.exit(code));
+    return;
+  }
+
   // A source-checkout-only verb from an installed package: say so before vault
   // resolution can refuse with an unrelated binding error.
   const missingVerb = notInPackageVerb(namespace, command);
@@ -1170,31 +1222,38 @@ function main(argv) {
     }
   }
 
-  // `hs companion start|stop|status|build` from an installed package: the tray
-  // app's source (companion/) is not in the tarball, so say THAT first -- before
-  // vault resolution can refuse with "not bound to a vault", which sends a
-  // customer to fix a binding that would not help.
+  // `hs companion start|stop|status|build` from an installed package (no
+  // companion/ source in the tarball) and `hs companion install` anywhere are
+  // machine-local and need no vault: run them BEFORE vault resolution can
+  // refuse with "not bound to a vault", which sends a customer to fix a binding
+  // that would not help. scripts/hs-companion.mjs drives an installed
+  // SpexCompanion, or offers `npx heyspex companion install` when there is none
+  // (HS-056P; this replaced the "not distributed through the npm package yet" answer).
   const companionSub = companionHostWithoutSource(namespace, command);
-  if (companionSub) {
-    import("../scripts/lib/hs-companion-settings.mjs").then(
-      (m) => {
-        process.stderr.write(`${m.renderCompanionNotDistributed(companionSub)}\n`);
-        process.exit(1);
-      },
-      (err) => {
-        process.stderr.write(`hs companion: ${err.message}\n`);
-        process.exit(1);
-      },
-    );
+  if (companionSub || (namespace === "companion" && command === "install")) {
+    const companionArgs = command ? [command, ...rest] : ["start", ...rest];
+    const child = spawn(process.execPath, [spawnTargetPath("companion"), ...companionArgs], {
+      cwd: INVOKED_CWD,
+      stdio: "inherit",
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs companion: ${err.message}\n`);
+      process.exit(1);
+    });
     return;
   }
 
-  const {
-    vaultRoot,
-    usedRegistryFallback,
-    error: vaultError,
-    brokenPin,
-  } = resolveVaultRootForMain(process.cwd(), process.env);
+  const resolved = resolveVaultRootForMain(process.cwd(), process.env);
+  const { usedRegistryFallback, error: vaultError } = resolved;
+  // `hs <verb> --help` must always print help and exit 0, bound vault or not
+  // (install QC: ~28 verbs refused with VAULT_UNBOUND from an unbound folder).
+  // Help never reads or writes a vault, so an unresolved vault falls back to the
+  // invocation folder and the vault refusals below (broken pin, no vault,
+  // uncloned satellite) are skipped; each verb's own handler prints its help.
+  const helpRequested = isHelpInvocation(argv);
+  const vaultRoot = resolved.vaultRoot || (helpRequested ? INVOKED_CWD : resolved.vaultRoot);
+  const brokenPin = helpRequested ? null : resolved.brokenPin;
   // The registry pointer is never consulted ([[HS-TYJA]]), so the only P1
   // refusal left is a satellite pin that cannot be honoured; onboarding /
   // registry verbs and `hs doctor` still run so the pin can be repaired.
@@ -1588,6 +1647,7 @@ function main(argv) {
   // vault's files to disk must never scaffold specs/ into a code repo.
   if (
     ["pull", "push", "index"].includes(namespace) &&
+    !helpRequested &&
     readMarkerSatellite(vaultRoot) &&
     !existsSync(path.join(vaultRoot, "specs"))
   ) {

package/bin/spexcode.mjs

@@ -33,6 +33,8 @@ import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { PRODUCT_SEATS, canonicalSeatId, defaultModelForSeat } from "../vendor/heyspex-mcp/seat-defaults.mjs";
+import { detectHarness } from "../spexharness/src/adapters/harness-detect.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -200,6 +202,29 @@ export function resolveSeatGuard(argv, seatsRegistry) {
   };
 }
 
+/**
+ * HS-MDZB (epic HS-C65J): a customer install ships no dev-factory/seats.json (that file is the
+ * owner's own fleet). When it is ABSENT, a product seat id is allowed and runs on the harness
+ * default (Claude tiers under Claude Code, `auto` under Copilot); an unknown id is still refused.
+ * Pure: env in, a guard verdict plus a one-line notice out.
+ * @returns {{allowed: boolean, message?: string, notice?: string}}
+ */
+export function resolveSeatGuardWithoutRegistry(seatId, env = {}) {
+  const id = canonicalSeatId(seatId);
+  const known = PRODUCT_SEATS.some((s) => s.id === id);
+  if (!known) {
+    return {
+      allowed: false,
+      message: `spexcode: refusing --seat "${seatId}" — not a HeySpex seat (known: ${PRODUCT_SEATS.map((s) => s.id).join(", ")}).`,
+    };
+  }
+  const d = defaultModelForSeat(id, detectHarness(env).harness);
+  const notice = d.model
+    ? `spexcode: seat "${id}" uses the ${d.harness} default model "${d.model}".`
+    : `spexcode: seat "${id}" has no default model (no harness detected; set HEYSPEX_HARNESS=claude-code or copilot).`;
+  return { allowed: true, notice };
+}
+
 /** Load + JSON.parse `dev-factory/seats.json`. Isolated so tests can stub it. */
 export function loadSeatsRegistry(seatsJsonPath = SEATS_JSON_PATH) {
   return JSON.parse(readFileSync(seatsJsonPath, "utf8"));
@@ -273,6 +298,12 @@ export async function runSpexcode(argv, deps = {}) {
     try {
       registry = loadRegistry();
     } catch (err) {
+      if (err && err.code === "ENOENT") {
+        const guard = resolveSeatGuardWithoutRegistry(seatId, deps.env ?? process.env);
+        stderr.write((guard.allowed ? guard.notice : guard.message) + "\n");
+        if (!guard.allowed) return 2;
+        return runForward(argv, { hsPath, spawnFn });
+      }
       stderr.write(
         `spexcode: could not read dev-factory/seats.json to check --seat "${seatId}": ` +
           `${err && err.message ? err.message : err}\n`,

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/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;
 }