heyspex 0.2.5 → 0.2.6

package/dist/cli/hs-vault-push.mjs

@@ -1073,10 +1073,10 @@ var require_stringify = __commonJS({
       data = Object.assign({}, file.data, data);
       const open = opts.delimiters[0];
       const close = opts.delimiters[1];
-      const matter4 = engine.stringify(data, options2).trim();
+      const matter5 = engine.stringify(data, options2).trim();
       let buf = "";
-      if (matter4 !== "{}") {
-        buf = newline(open) + newline(matter4) + newline(close);
+      if (matter5 !== "{}") {
+        buf = newline(open) + newline(matter5) + newline(close);
       }
       if (typeof file.excerpt === "string" && file.excerpt !== "") {
         if (str2.indexOf(file.excerpt.trim()) === -1) {
@@ -1182,19 +1182,19 @@ var require_gray_matter = __commonJS({
     var toFile = require_to_file();
     var parse2 = require_parse();
     var utils = require_utils();
-    function matter4(input, options2) {
+    function matter5(input, options2) {
       if (input === "") {
         return { data: {}, content: input, excerpt: "", orig: input };
       }
       let file = toFile(input);
-      const cached = matter4.cache[file.content];
+      const cached = matter5.cache[file.content];
       if (!options2) {
         if (cached) {
           file = Object.assign({}, cached);
           file.orig = cached.orig;
           return file;
         }
-        matter4.cache[file.content] = file;
+        matter5.cache[file.content] = file;
       }
       return parseMatter(file, options2);
     }
@@ -1216,7 +1216,7 @@ var require_gray_matter = __commonJS({
       }
       str2 = str2.slice(openLen);
       const len = str2.length;
-      const language = matter4.language(str2, opts);
+      const language = matter5.language(str2, opts);
       if (language.name) {
         file.language = language.name;
         str2 = str2.slice(language.raw.length);
@@ -1251,24 +1251,24 @@ var require_gray_matter = __commonJS({
       }
       return file;
     }
-    matter4.engines = engines2;
-    matter4.stringify = function(file, data, options2) {
-      if (typeof file === "string") file = matter4(file, options2);
+    matter5.engines = engines2;
+    matter5.stringify = function(file, data, options2) {
+      if (typeof file === "string") file = matter5(file, options2);
       return stringify(file, data, options2);
     };
-    matter4.read = function(filepath, options2) {
+    matter5.read = function(filepath, options2) {
       const str2 = fs12.readFileSync(filepath, "utf8");
-      const file = matter4(str2, options2);
+      const file = matter5(str2, options2);
       file.path = filepath;
       return file;
     };
-    matter4.test = function(str2, options2) {
+    matter5.test = function(str2, options2) {
       return utils.startsWith(str2, defaults(options2).delimiters[0]);
     };
-    matter4.language = function(str2, options2) {
+    matter5.language = function(str2, options2) {
       const opts = defaults(options2);
       const open = opts.delimiters[0];
-      if (matter4.test(str2)) {
+      if (matter5.test(str2)) {
         str2 = str2.slice(open.length);
       }
       const language = str2.slice(0, str2.search(/\r?\n/));
@@ -1277,11 +1277,11 @@ var require_gray_matter = __commonJS({
         name: language ? language.trim() : ""
       };
     };
-    matter4.cache = {};
-    matter4.clearCache = function() {
-      matter4.cache = {};
+    matter5.cache = {};
+    matter5.clearCache = function() {
+      matter5.cache = {};
     };
-    module2.exports = matter4;
+    module2.exports = matter5;
   }
 });
 
@@ -3068,11 +3068,12 @@ function getPostgresAdminDb() {
 function inertClient() {
   return false;
 }
-var isNeonPool;
+var isNeonPool, registerVaultScopedDbAccessor;
 var init_postgres_client_cli_shim = __esm({
   "dist/cli/._postgres-client.cli-shim.mjs"() {
     "use strict";
     isNeonPool = inertClient;
+    registerVaultScopedDbAccessor = inertClient;
   }
 });
 
@@ -3323,6 +3324,141 @@ var init_clients = __esm({
   }
 });
 
+// spex-console/src/lib/rate-limits.ts
+var RATE_LIMIT_BUDGETS;
+var init_rate_limits = __esm({
+  "spex-console/src/lib/rate-limits.ts"() {
+    "use strict";
+    RATE_LIMIT_BUDGETS = {
+      mcp_tool_calls: { daily: 500, hourly: 125 },
+      spec_writes: { daily: 100, hourly: 25 },
+      capture_sessions: { daily: 20, hourly: 5 },
+      // Paul's Advocate free-text chat ([[HS-4YYB-XEBI-TASK-paul-s-advocate-answers-real-questions]]):
+      // a public YC reviewer can otherwise run up LLM spend on an unauthenticated-feeling
+      // widget. 30/hour matches the builder brief's "e.g. 30 messages/hour" starting point;
+      // daily is 4x hourly (looser than the 25%-of-daily pattern above — a reviewer chatting
+      // steadily through a demo session should not get cut off mid-conversation).
+      advocate_chat: { daily: 120, hourly: 30 }
+    };
+  }
+});
+
+// spex-console/src/lib/plan-tier.ts
+function scaledBudgets(multiplier) {
+  const out = {};
+  for (const [bucket, budget] of Object.entries(RATE_LIMIT_BUDGETS)) {
+    out[bucket] = {
+      daily: Math.round(budget.daily * multiplier),
+      hourly: Math.round(budget.hourly * multiplier)
+    };
+  }
+  return Object.freeze(out);
+}
+var PLAN_TIER_RATE_LIMIT_MULTIPLIER, PLAN_TIER_LIMITS;
+var init_plan_tier = __esm({
+  "spex-console/src/lib/plan-tier.ts"() {
+    "use strict";
+    init_sql_orm_inert_cli_shim();
+    init_postgres_client_cli_shim();
+    init_postgres();
+    init_rate_limits();
+    PLAN_TIER_RATE_LIMIT_MULTIPLIER = {
+      free: 1,
+      pro: 4,
+      enterprise: 20
+    };
+    PLAN_TIER_LIMITS = {
+      free: {
+        statement_timeout_ms: 5e3,
+        read_work_mem: "4MB",
+        rate_limit_budgets: scaledBudgets(PLAN_TIER_RATE_LIMIT_MULTIPLIER.free)
+      },
+      pro: {
+        statement_timeout_ms: 15e3,
+        read_work_mem: "16MB",
+        rate_limit_budgets: scaledBudgets(PLAN_TIER_RATE_LIMIT_MULTIPLIER.pro)
+      },
+      enterprise: {
+        statement_timeout_ms: 3e4,
+        read_work_mem: "64MB",
+        rate_limit_budgets: scaledBudgets(PLAN_TIER_RATE_LIMIT_MULTIPLIER.enterprise)
+      }
+    };
+  }
+});
+
+// spex-console/src/lib/db/clients/vault-router.ts
+import { existsSync as existsSync8, readFileSync as readFileSync13 } from "node:fs";
+import { homedir as homedir10 } from "node:os";
+import { join as join11 } from "node:path";
+var CREDENTIALS_PATH, ROUTER_KEY, globalRouter, router;
+var init_vault_router = __esm({
+  "spex-console/src/lib/db/clients/vault-router.ts"() {
+    "use strict";
+    init_sql_orm_inert_cli_shim();
+    init_sql_orm_inert_cli_shim();
+    init_postgres();
+    init_postgres_client_cli_shim();
+    CREDENTIALS_PATH = join11(homedir10(), ".heyspex", "credentials.yaml");
+    ROUTER_KEY = Symbol.for("heyspex.vaultRouter");
+    globalRouter = globalThis;
+    if (!globalRouter[ROUTER_KEY]) {
+      globalRouter[ROUTER_KEY] = {
+        dedicated: /* @__PURE__ */ new Map(),
+        refCache: /* @__PURE__ */ new Map(),
+        warnedSchemaMissing: false
+      };
+    }
+    router = globalRouter[ROUTER_KEY];
+  }
+});
+
+// spex-console/src/lib/db/clients/vault-scope.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+function warnScopeClosedOnce(ctx) {
+  if (ctx.warnedClosed) return;
+  ctx.warnedClosed = true;
+  console.warn(
+    `[vault-scope] db use after vault scope closed; falling back to the pool connection (unscoped) (vaultId: ${ctx.vaultId})`
+  );
+}
+function handleScopeClosedAccess(ctx) {
+  if (ctx.onStaleUse === "throw") {
+    throw new VaultScopeClosedError(ctx.vaultId);
+  }
+  warnScopeClosedOnce(ctx);
+}
+var VaultScopeClosedError, vaultScopeStorage;
+var init_vault_scope = __esm({
+  "spex-console/src/lib/db/clients/vault-scope.ts"() {
+    "use strict";
+    init_sql_orm_inert_cli_shim();
+    init_plan_tier();
+    init_postgres_client_cli_shim();
+    init_vault_router();
+    VaultScopeClosedError = class extends Error {
+      vaultId;
+      constructor(vaultId) {
+        super(
+          `Vault scope for "${vaultId}" is closed; this path opted into onStaleUseAfterClose: "throw", so a db handle used after the scope's transaction settled fails loudly instead of silently falling back to the unscoped pool connection.`
+        );
+        this.name = "VaultScopeClosedError";
+        this.vaultId = vaultId;
+      }
+    };
+    vaultScopeStorage = new AsyncLocalStorage();
+    registerVaultScopedDbAccessor(() => {
+      const ctx = vaultScopeStorage.getStore();
+      if (!ctx) return null;
+      if (ctx.closed) {
+        handleScopeClosedAccess(ctx);
+        return null;
+      }
+      return ctx.proxy;
+    });
+  }
+});
+
 // spex-console/src/lib/scheduler/types.ts
 var init_types2 = __esm({
   "spex-console/src/lib/scheduler/types.ts"() {
@@ -3857,10 +3993,45 @@ var init_config = __esm({
   }
 });
 
-// spex-console/src/lib/vault-frontmatter.ts
+// spex-console/src/lib/safe-yaml.ts
 import yaml2 from "js-yaml";
+function dropUndefinedDeep(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => item !== void 0).map((item) => dropUndefinedDeep(item));
+  }
+  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (v === void 0) continue;
+      out[k] = dropUndefinedDeep(v);
+    }
+    return out;
+  }
+  return value;
+}
+function safeYamlDump(value, options2 = {}) {
+  const { schema: _ignoredSchema, ...rest } = options2;
+  const data = dropUndefinedDeep(value);
+  if (grayMatterYamlStringify) return grayMatterYamlStringify(data, rest);
+  return yaml2.dump(data, { ...rest, schema: SAFE_YAML_SCHEMA });
+}
+var import_gray_matter, SAFE_YAML_SCHEMA, grayMatterYamlStringify, YAML_FAILSAFE_SCHEMA;
+var init_safe_yaml = __esm({
+  "spex-console/src/lib/safe-yaml.ts"() {
+    "use strict";
+    import_gray_matter = __toESM(require_gray_matter(), 1);
+    SAFE_YAML_SCHEMA = yaml2.DEFAULT_SAFE_SCHEMA ?? yaml2.DEFAULT_SCHEMA;
+    grayMatterYamlStringify = (() => {
+      const engine = import_gray_matter.default.engines?.yaml;
+      return typeof engine?.stringify === "function" ? engine.stringify : void 0;
+    })();
+    YAML_FAILSAFE_SCHEMA = yaml2.FAILSAFE_SCHEMA;
+  }
+});
+
+// spex-console/src/lib/vault-frontmatter.ts
 function normalizeFrontmatterForYaml(frontmatter) {
-  const processed = { ...frontmatter };
+  const processed = dropUndefinedDeep(frontmatter);
   for (const [key, value] of Object.entries(processed)) {
     if (value instanceof Date) {
       processed[key] = value.toISOString();
@@ -3869,20 +4040,21 @@ function normalizeFrontmatterForYaml(frontmatter) {
   return processed;
 }
 function stringifySpecMarkdown(body, frontmatter) {
-  const fm = yaml2.dump(normalizeFrontmatterForYaml(frontmatter), YAML_STRINGIFY_OPTIONS).trim();
+  const fm = safeYamlDump(normalizeFrontmatterForYaml(frontmatter), YAML_STRINGIFY_OPTIONS).trim();
   return `---
 ${fm}
 ---
 ${body}`;
 }
 function parseSpecMarkdown(raw) {
-  return (0, import_gray_matter.default)(raw);
+  return (0, import_gray_matter2.default)(raw);
 }
-var import_gray_matter, YAML_STRINGIFY_OPTIONS;
+var import_gray_matter2, YAML_STRINGIFY_OPTIONS;
 var init_vault_frontmatter = __esm({
   "spex-console/src/lib/vault-frontmatter.ts"() {
     "use strict";
-    import_gray_matter = __toESM(require_gray_matter(), 1);
+    import_gray_matter2 = __toESM(require_gray_matter(), 1);
+    init_safe_yaml();
     YAML_STRINGIFY_OPTIONS = {
       quotingType: '"',
       skipInvalid: true,
@@ -4777,11 +4949,11 @@ var init_guardrail_naming = __esm({
 import { createHash as createHash3 } from "node:crypto";
 import { promises as fs6 } from "node:fs";
 import path9 from "node:path";
-var import_gray_matter2;
+var import_gray_matter3;
 var init_parser = __esm({
   "spex-console/src/lib/indexer/parser.ts"() {
     "use strict";
-    import_gray_matter2 = __toESM(require_gray_matter(), 1);
+    import_gray_matter3 = __toESM(require_gray_matter(), 1);
     init_vault_id();
     init_vault_shared();
   }
@@ -4920,12 +5092,12 @@ var init_linkage_validation = __esm({
 });
 
 // spex-console/src/lib/perf-timing.ts
-import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 var storage;
 var init_perf_timing = __esm({
   "spex-console/src/lib/perf-timing.ts"() {
     "use strict";
-    storage = new AsyncLocalStorage();
+    storage = new AsyncLocalStorage2();
   }
 });
 
@@ -4947,12 +5119,12 @@ var init_planning_flow_model = __esm({
 });
 
 // spex-console/src/lib/request-memo.ts
-import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage3 } from "node:async_hooks";
 var storage2;
 var init_request_memo = __esm({
   "spex-console/src/lib/request-memo.ts"() {
     "use strict";
-    storage2 = new AsyncLocalStorage2();
+    storage2 = new AsyncLocalStorage3();
   }
 });
 
@@ -5200,18 +5372,17 @@ var init_search_body_hit = __esm({
 
 // spex-console/src/lib/vault.ts
 import { spawn } from "node:child_process";
-import { readdirSync as readdirSync2, readFileSync as readFileSync13, statSync as statSync5 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync14, statSync as statSync5 } from "node:fs";
 import { promises as fs9 } from "node:fs";
 import path14 from "node:path";
-import yaml3 from "js-yaml";
 function vaultRoot() {
   return getActiveSpecsDir();
 }
-var import_gray_matter3, VAULT_CACHE_TTL_WATCHED_MS, VAULT_CACHE_KEY, vaultCacheStore, VAULT_CACHE_DELTA_LISTENERS_KEY, vaultCacheDeltaListeners, SEARCH_TEXT_KEY, searchTextStore, VAULT_SNAPSHOT_KEY, vaultSnapshotStore;
+var import_gray_matter4, VAULT_CACHE_TTL_WATCHED_MS, VAULT_CACHE_KEY, vaultCacheStore, VAULT_CACHE_DELTA_LISTENERS_KEY, vaultCacheDeltaListeners, SEARCH_TEXT_KEY, searchTextStore, VAULT_SNAPSHOT_KEY, vaultSnapshotStore;
 var init_vault = __esm({
   "spex-console/src/lib/vault.ts"() {
     "use strict";
-    import_gray_matter3 = __toESM(require_gray_matter(), 1);
+    import_gray_matter4 = __toESM(require_gray_matter(), 1);
     init_diagnose_skeleton();
     init_auth();
     init_capture_vault();
@@ -5222,6 +5393,7 @@ var init_vault = __esm({
     init_skips();
     init_clients();
     init_postgres_client_cli_shim();
+    init_vault_scope();
     init_helpers();
     init_index_write_service();
     init_spec_read_service();
@@ -5238,6 +5410,7 @@ var init_vault = __esm({
     init_planning_flow_model();
     init_request_memo();
     init_review_mode();
+    init_safe_yaml();
     init_active_milestone();
     init_area();
     init_claim_eligibility();
@@ -5322,7 +5495,7 @@ var init_vault = __esm({
 });
 
 // spex-console/bin/hs-vault-push.ts
-import { readFileSync as readFileSync15 } from "node:fs";
+import { readFileSync as readFileSync16 } from "node:fs";
 import path15 from "node:path";
 import process4 from "node:process";
 
@@ -5706,7 +5879,7 @@ async function writeDirtyMarker(vaultRoot2, id, now = () => /* @__PURE__ */ new
 }
 
 // spex-console/src/lib/vault-sync/pull-io.ts
-import { promises as fs10, readFileSync as readFileSync14 } from "node:fs";
+import { promises as fs10, readFileSync as readFileSync15 } from "node:fs";
 import { EOL } from "node:os";
 import nodePath3 from "node:path";
 
@@ -6352,7 +6525,7 @@ function runEntry(name, main2, options2 = {}) {
 // spex-console/bin/hs-vault-push.ts
 function readMarkerVaultId(vaultRoot2) {
   try {
-    return parseVaultId(readFileSync15(path15.join(vaultRoot2, "heyspex.yaml"), "utf8"));
+    return parseVaultId(readFileSync16(path15.join(vaultRoot2, "heyspex.yaml"), "utf8"));
   } catch {
     return null;
   }

package/dist/cli-templates/harness-commands/claude/hs-res.md

@@ -1,63 +1,71 @@
----
-description: Confidence-ladder research method's entrypoint — SpexCrawl via the Companion (search/gather) is PRIMARY + DeepSeek (synthesis); self-hosted Firecrawl is an AUTOMATIC fallback (no permission needed, owner ruling 2026-08-22), zero Claude/Anthropic involvement.
-argument-hint: "[research question/topic]"
----
-
-# Research (`/hs-res`)
-
-> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
-
-## What to do
-
-1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
-   console doc-toolbar Promote pin via `heyspex_active_research`
-   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
-   capture body as the question. Either way, restate the scope and confirm with the user.
-
-2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
-   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
-   for research"). Decompose into a few independent search angles, then per angle:
-   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
-   searches AND returns the cleaned pages of the top results. Specific extra URLs:
-   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
-   Prerequisites: the Companion running and paired to the console. LAN mode
-   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
-   machine than the console — since HS-V9WH the Companion polls loopback consoles too
-   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
-   misdocumented as a requirement). When missing, the CLI exits 3 with
-   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
-   running or not polling this console.
-
-   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
-   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
-   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
-   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
-   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
-   prefer other reachable machines over the one the orchestrating session runs on; check
-   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
-   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
-   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
-   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
-
-3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
-   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
-   instructions to a temp prompt file.
-
-4. **Synthesize via DeepSeek** —
-   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
-   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
-   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
-   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
-   with `SYNTHESIZE_UNAVAILABLE`).
-
-5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
-   pipeline), with `sources` populated from the gathered URLs.
-
-**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
-`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
-`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
-permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
-user's explicit per-run permission, every time. If a CLI reports unavailable
-(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
-**stop** and tell the user — never silently substitute another backend. Full method,
-escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.
+---
+description: Confidence-ladder research method's entrypoint — SpexCrawl via the Companion (search/gather) is PRIMARY + DeepSeek (synthesis); self-hosted Firecrawl is an AUTOMATIC fallback (no permission needed, owner ruling 2026-08-22), zero Claude/Anthropic involvement.
+argument-hint: "[research question/topic]"
+---
+
+# Research (`/hs-res`)
+
+> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
+
+## What to do
+
+1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
+   console doc-toolbar Promote pin via `heyspex_active_research`
+   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
+   capture body as the question. Either way, restate the scope and confirm with the user.
+
+2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
+   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
+   for research"). Decompose into a few independent search angles, then per angle:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
+   searches AND returns the cleaned pages of the top results. Specific extra URLs:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
+   Prerequisites: the Companion running and paired to the console. LAN mode
+   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
+   machine than the console — since HS-V9WH the Companion polls loopback consoles too
+   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
+   misdocumented as a requirement). When missing, the CLI exits 3 with
+   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
+   running or not polling this console.
+
+   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
+   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
+   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
+   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
+   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
+   prefer other reachable machines over the one the orchestrating session runs on; check
+   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
+   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
+   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
+   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
+
+   **In a repo that uses the `heyspex` npm package** (not a HeySpex platform checkout): the
+   package ships only the SpexCrawl client (`dev-factory/spexcrawl/spexcrawl-cli.mjs` under
+   `node_modules/heyspex/`). It needs the HeySpex Companion, which the npm package does not
+   distribute yet, so it usually exits 3 `SPEXCRAWL_UNAVAILABLE`. The Firecrawl fallback and
+   the DeepSeek synthesis CLI (`firecrawl-cli.mjs`, `synthesize-cli.mjs`) are HeySpex-platform
+   only and are not in the package. When a CLI named in steps 2 or 4 is missing or reports
+   unavailable, stop and tell the user this research method is not available in their install.
+
+3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
+   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
+   instructions to a temp prompt file.
+
+4. **Synthesize via DeepSeek** —
+   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
+   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
+   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
+   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
+   with `SYNTHESIZE_UNAVAILABLE`).
+
+5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
+   pipeline), with `sources` populated from the gathered URLs.
+
+**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
+`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
+`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
+permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
+user's explicit per-run permission, every time. If a CLI reports unavailable
+(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
+**stop** and tell the user — never silently substitute another backend. Full method,
+escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.