heyspex 0.1.0 → 0.2.0

package/dev-factory/lib/fleet-queue.mjs

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+/**
+ * fleet-queue.mjs — a generic, file-backed queue for any machine-gated fleet resource.
+ *
+ * Owner ask (2026-07-12): "If I have one agent already sending research request in progress
+ * to Night Action, and another agent has research that needs to be done, that agent can
+ * submit it successfully to the research queue - instead of getting a fail or rejection.
+ * This queue can also be used when Night Action has an existing ollama process. Research can
+ * be sent to the queue to be presented to Night Action as soon as it is done." And: "this
+ * queue concept can be used across the whole fleet for different use cases."
+ *
+ * FIRST LANE: "research-firecrawl" — research requests that lose the Ollama-XOR-Firecrawl
+ * mode-lease race in night-action-mode.mjs's requestOrEnqueueFirecrawlMode() land here
+ * instead of failing (see night-action-mode.mjs). Lanes are free-form strings; any future
+ * machine-gated resource (a build slot, a breakdown job, a GPU node) reuses this same module
+ * under its own lane name — see the design note at the bottom of this file.
+ *
+ * STORAGE — event-sourced, append-only JSONL: `.heyspex/fleet-queue.jsonl` (repo root,
+ * resolved by walking up to the heyspex.yaml vault marker — same convention as
+ * dev-factory/lib/fleet-state.mjs). Every mutation (enqueue / claim / complete / fail) is
+ * appended as ONE JSON line via a fresh open("a") + write + close (mirrors
+ * dev-factory/lib/run-events.mjs) — never a whole-file rewrite. Current item state is derived
+ * by FOLDING an item's events in file order, the same event-sourcing shape
+ * .heyspex/claim-history.jsonl and .heyspex/focus-history.jsonl already use elsewhere in this
+ * repo for durable ledgers (append pattern confirmed against both before writing this).
+ *
+ * WHY EVENT-SOURCED APPEND OVER REWRITE-WITH-STATUS (the crash-safety justification the task
+ * asked for): a whole-file rewrite (read all items, mutate one, write a temp file, rename over
+ * the original) is atomic PER WRITE but requires a read-modify-write on the FULL file for every
+ * single mutation, and a crash between "read" and "rename" either loses the mutation or (worse,
+ * on a partial rename) can corrupt every other item's state too. An append-only event log makes
+ * each mutation a single new line: a crash mid-write can only ever cost the LAST line (which
+ * readAllEvents() below already tolerates — a corrupt/partial trailing line is skipped, not
+ * thrown, mirroring run-events.mjs), and it can NEVER corrupt or lose any prior item's history.
+ * The trade is that readers must fold history instead of reading a snapshot — cheap here since
+ * the queue is small and local.
+ *
+ * CONCURRENCY — double-claim rejection: enqueue/complete/fail don't need cross-process
+ * exclusion (each only ever touches its own new line or an item only its own claimant should be
+ * mutating), but claim() has a genuine race — two processes could both read "pending" for the
+ * same id before either appends its claim event. claim() (and complete/fail, for symmetry) take
+ * a short-lived, per-id, TTL-bounded advisory file lock (`<queue>.lock.<id>`, exclusive-create
+ * `wx`) around their read-decide-append critical section — true mutual exclusion for same-id
+ * ops across processes, while different ids proceed fully in parallel. A lock file left behind
+ * by a crashed holder is auto-broken after `staleLockMs` (default 5s) so the queue can never
+ * wedge on a dead process.
+ *
+ * CRASH-RECOVERY (claim TTL): a claim() that never gets a matching complete()/fail() within
+ * `CLAIM_TTL_MS` (default 15 min, override via options or HEYSPEX_FLEET_QUEUE_CLAIM_TTL_MS) is
+ * treated as STALE — effectiveStatus() reports it back as "pending" so any caller (including
+ * the original claimant retrying after a crash) can reclaim it. The stale claim's history is
+ * never deleted, only superseded by a fresh claim event — so `list()` still shows the full
+ * claim history for audit.
+ *
+ * API:
+ *   enqueue({ lane, payload, requestedBy }) -> { id, position }   // position = 1-indexed rank among pending items in that lane
+ *   nextPending(lane)                        -> item | null       // oldest pending (or stale-reclaimable) item in the lane
+ *   claim(id, claimant)                      -> { ok, reason? }   // rejects double-claim / terminal states
+ *   complete(id, result?)                    -> { ok, reason? }   // must currently be claimed
+ *   fail(id, reason?)                        -> { ok, reason? }   // from pending or claimed
+ *   list(lane?, status?)                     -> item[]            // oldest-first
+ *
+ * CLI: node dev-factory/lib/fleet-queue.mjs --self-test
+ */
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { codeRepoRoot } from "./code-repo-root.mjs";
+
+// ── repo-root + store resolution: this queue holds CODE-repo state (fleet-queue.jsonl), not
+//    vault state, so it anchors on the code repo itself rather than walking for a vault marker.
+export function findRepoRoot() {
+  return codeRepoRoot();
+}
+
+function defaultQueuePath() {
+  const dir = join(findRepoRoot(), ".heyspex");
+  mkdirSync(dir, { recursive: true });
+  return process.env.HEYSPEX_FLEET_QUEUE_PATH || join(dir, "fleet-queue.jsonl");
+}
+
+export const CLAIM_TTL_MS = Number(process.env.HEYSPEX_FLEET_QUEUE_CLAIM_TTL_MS) || 15 * 60 * 1000; // 15 min
+
+/** First lane (owner ask 2026-07-12): research requests that lose the Ollama-XOR-Firecrawl
+ *  mode-lease race in night-action-mode.mjs land here instead of failing. */
+export const RESEARCH_FIRECRAWL_LANE = "research-firecrawl";
+
+// ── event log I/O (mirrors run-events.mjs: line-atomic append, corrupt-tail-tolerant read) ──────
+function appendEvent(queuePath, record) {
+  mkdirSync(dirname(queuePath), { recursive: true });
+  const line = `${JSON.stringify(record)}\n`;
+  const fd = openSync(queuePath, "a");
+  try {
+    writeSync(fd, line);
+  } finally {
+    closeSync(fd);
+  }
+  return record;
+}
+
+function readAllEvents(queuePath) {
+  if (!existsSync(queuePath)) return [];
+  const text = readFileSync(queuePath, "utf8");
+  const events = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      // corrupt/partial trailing line (e.g. a crash mid-write) — skip, never throw
+    }
+  }
+  return events;
+}
+
+// ── per-id advisory lock (exclusive-create; auto-breaks a stale/crashed holder) ─────────────────
+function lockPathFor(queuePath, id) {
+  return `${queuePath}.lock.${id}`;
+}
+
+function acquireLock(queuePath, id, { timeoutMs = 3000, staleLockMs = 5000, pollMs = 15 } = {}) {
+  const lp = lockPathFor(queuePath, id);
+  mkdirSync(dirname(queuePath), { recursive: true });
+  const start = Date.now();
+  for (;;) {
+    try {
+      const fd = openSync(lp, "wx");
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      return true;
+    } catch (e) {
+      if (e?.code !== "EEXIST") throw e;
+      try {
+        const st = statSync(lp);
+        if (Date.now() - st.mtimeMs > staleLockMs) {
+          rmSync(lp, { force: true }); // break a lock left by a crashed holder
+          continue;
+        }
+      } catch {
+        continue; // lock vanished between the failed create and the stat — retry immediately
+      }
+      if (Date.now() - start > timeoutMs) return false;
+      // best-effort short busy-wait; this is a local dev tool, not a high-throughput queue
+      const until = Date.now() + pollMs;
+      while (Date.now() < until) { /* spin */ }
+    }
+  }
+}
+
+function releaseLock(queuePath, id) {
+  try {
+    rmSync(lockPathFor(queuePath, id), { force: true });
+  } catch {
+    // already gone — fine
+  }
+}
+
+function withLock(queuePath, id, fn) {
+  if (!acquireLock(queuePath, id)) return { ok: false, reason: `fleet-queue: could not acquire lock for "${id}" (held too long)` };
+  try {
+    return fn();
+  } finally {
+    releaseLock(queuePath, id);
+  }
+}
+
+// ── state derivation (event fold) ─────────────────────────────────────────────────────────────
+function foldOne(events) {
+  let state = null;
+  for (const ev of events) {
+    if (ev.type === "enqueue") {
+      state = {
+        id: ev.id,
+        lane: ev.lane,
+        payload: ev.payload ?? null,
+        requestedBy: ev.requestedBy ?? null,
+        status: "pending",
+        enqueuedAt: ev.at,
+        claimant: null,
+        claimedAt: null,
+        result: null,
+        failReason: null,
+        completedAt: null,
+      };
+    } else if (!state) {
+      continue; // orphan event with no enqueue in this log slice — ignore
+    } else if (ev.type === "claim") {
+      state.status = "claimed";
+      state.claimant = ev.claimant ?? null;
+      state.claimedAt = ev.at;
+    } else if (ev.type === "complete") {
+      state.status = "completed";
+      state.result = ev.result ?? null;
+      state.completedAt = ev.at;
+    } else if (ev.type === "fail") {
+      state.status = "failed";
+      state.failReason = ev.reason ?? null;
+      state.completedAt = ev.at;
+    }
+  }
+  return state;
+}
+
+/** Raw folded state (claimed stays "claimed" even if stale) keyed by id, oldest enqueue first. */
+function deriveRaw(queuePath) {
+  const events = readAllEvents(queuePath);
+  const byId = new Map();
+  for (const ev of events) {
+    if (!ev?.id) continue;
+    if (!byId.has(ev.id)) byId.set(ev.id, []);
+    byId.get(ev.id).push(ev);
+  }
+  const out = new Map();
+  for (const [id, evs] of byId) {
+    const s = foldOne(evs);
+    if (s) out.set(id, s);
+  }
+  return out;
+}
+
+/** Folded state with the TTL rule applied: a claim older than ttlMs reports back as "pending"
+ *  (reclaimable) without erasing claimant/claimedAt history — callers can see it was stale. */
+function deriveEffective(queuePath, { now = Date.now(), ttlMs = CLAIM_TTL_MS } = {}) {
+  const raw = deriveRaw(queuePath);
+  const out = new Map();
+  for (const [id, s] of raw) {
+    const stale = s.status === "claimed" && now - Date.parse(s.claimedAt) > ttlMs;
+    out.set(id, stale ? { ...s, status: "pending", stale: true } : { ...s, stale: false });
+  }
+  return out;
+}
+
+function genId() {
+  return `fq_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ── public API ────────────────────────────────────────────────────────────────────────────────
+export function enqueue({ lane, payload = null, requestedBy = null, queuePath = defaultQueuePath(), now = Date.now() } = {}) {
+  if (!lane) throw new Error("fleet-queue.enqueue: lane is required");
+  const id = genId();
+  const at = new Date(now).toISOString();
+  appendEvent(queuePath, { type: "enqueue", id, lane, payload, requestedBy, at });
+  const items = [...deriveEffective(queuePath, { now }).values()]
+    .filter((s) => s.lane === lane && s.status === "pending")
+    .sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt));
+  const position = items.findIndex((s) => s.id === id) + 1;
+  return { id, position };
+}
+
+export function nextPending(lane, { queuePath = defaultQueuePath(), now = Date.now(), ttlMs = CLAIM_TTL_MS } = {}) {
+  const items = [...deriveEffective(queuePath, { now, ttlMs }).values()]
+    .filter((s) => s.lane === lane && s.status === "pending")
+    .sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt));
+  return items[0] ?? null;
+}
+
+export function claim(id, claimant, { queuePath = defaultQueuePath(), now = Date.now(), ttlMs = CLAIM_TTL_MS } = {}) {
+  if (!id) return { ok: false, reason: "fleet-queue.claim: id is required" };
+  if (!claimant) return { ok: false, reason: "fleet-queue.claim: claimant is required" };
+  return withLock(queuePath, id, () => {
+    const state = deriveEffective(queuePath, { now, ttlMs }).get(id);
+    if (!state) return { ok: false, reason: `unknown id "${id}"` };
+    if (state.status === "completed") return { ok: false, reason: "already completed" };
+    if (state.status === "failed") return { ok: false, reason: "already failed" };
+    if (state.status === "claimed") return { ok: false, reason: `already claimed by ${state.claimant}` };
+    appendEvent(queuePath, { type: "claim", id, claimant, at: new Date(now).toISOString() });
+    return { ok: true, id, claimant, reclaimed: Boolean(state.stale) };
+  });
+}
+
+export function complete(id, result = null, { queuePath = defaultQueuePath(), now = Date.now() } = {}) {
+  if (!id) return { ok: false, reason: "fleet-queue.complete: id is required" };
+  return withLock(queuePath, id, () => {
+    const state = deriveEffective(queuePath, { now }).get(id);
+    if (!state) return { ok: false, reason: `unknown id "${id}"` };
+    if (state.status !== "claimed") return { ok: false, reason: `cannot complete from status "${state.status}" (must be claimed)` };
+    appendEvent(queuePath, { type: "complete", id, result, at: new Date(now).toISOString() });
+    return { ok: true, id };
+  });
+}
+
+export function fail(id, reason = null, { queuePath = defaultQueuePath(), now = Date.now() } = {}) {
+  if (!id) return { ok: false, reason: "fleet-queue.fail: id is required" };
+  return withLock(queuePath, id, () => {
+    const state = deriveEffective(queuePath, { now }).get(id);
+    if (!state) return { ok: false, reason: `unknown id "${id}"` };
+    if (state.status === "completed" || state.status === "failed") {
+      return { ok: false, reason: `cannot fail from terminal status "${state.status}"` };
+    }
+    appendEvent(queuePath, { type: "fail", id, reason, at: new Date(now).toISOString() });
+    return { ok: true, id };
+  });
+}
+
+export function list(lane = null, status = null, { queuePath = defaultQueuePath(), now = Date.now(), ttlMs = CLAIM_TTL_MS } = {}) {
+  const items = [...deriveEffective(queuePath, { now, ttlMs }).values()];
+  return items
+    .filter((s) => (lane ? s.lane === lane : true))
+    .filter((s) => (status ? s.status === status : true))
+    .sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt));
+}
+
+/*
+ * ── DESIGN NOTE: how this generalizes fleet-wide, and the future upgrade path ──────────────────
+ *
+ * This module is deliberately domain-blind: `lane` is a free-form string, `payload` is opaque
+ * JSON, and nothing in enqueue/claim/complete/fail/list knows about research, Firecrawl, or
+ * Night Action. The first lane ("research-firecrawl") is a CONSUMER of this queue, not part of
+ * its design. Any other machine-gated resource in the fleet can stand up its own lane the same
+ * way, with zero changes to this file:
+ *   - build jobs waiting on a busy GPU box               -> lane "build-<machine>"
+ *   - breakdown/critic jobs waiting on the DeepSeek seat  -> lane "breakdown-deepseek"
+ *   - any single-tenant resource with a "one workload at a time" mode lease, mirroring
+ *     night-action-mode.mjs's Ollama-XOR-Firecrawl shape (mode lease refuses -> caller enqueues
+ *     instead of failing -> a drain step pops the lane once the resource frees up)
+ * The pattern each consumer follows is the same three-step shape night-action-mode.mjs
+ * demonstrates: (1) try the gated resource directly, (2) on refusal, enqueue() instead of
+ * returning a hard failure, (3) a --drain (or equivalent poll) on the resource-owning side pops
+ * nextPending()/list() once the resource is free and dispatches the work.
+ *
+ * MULTI-MACHINE UPGRADE PATH: this file-backed JSONL queue is correct for a SINGLE shared
+ * filesystem (one repo checkout, or machines that all see the same network share) — the
+ * per-id file lock only provides mutual exclusion within one filesystem. The moment lanes need
+ * to be claimed/drained from genuinely separate machines with no shared disk (the fleet's
+ * long-run shape), the natural port is a Neon control-plane table with the SAME event-sourced
+ * shape (an append-only `fleet_queue_events` table, `claim` as an `INSERT ... WHERE NOT EXISTS a
+ * live claim` guarded by a DB-level unique constraint instead of a file lock, `nextPending` as an
+ * indexed `ORDER BY enqueued_at LIMIT 1` query) — the API surface above (enqueue/nextPending/
+ * claim/complete/fail/list) stays identical, so callers do not change; only defaultQueuePath()'s
+ * resolution swaps for a connection string. Do not build that port speculatively — this local
+ * file-backed version is the right MVP for the current single-box (Night Action) + single-vault
+ * (this repo) topology, and the Neon swap is scoped exactly when a second always-on machine
+ * needs to claim from the same lane.
+ */
+
+// ── self-test (local temp queue file — never touches the real .heyspex/fleet-queue.jsonl) ──────
+if (import.meta.url.endsWith("/" + (process.argv[1]?.split(/[\\/]/).pop() ?? "")) && process.argv.includes("--self-test")) {
+  (async () => {
+    const { tmpdir } = await import("node:os");
+    const { mkdtempSync, rmSync: rm } = await import("node:fs");
+    let ok = true;
+    const check = (n, c) => {
+      console.log(`  ${c ? "✓" : "✗"} ${n}`);
+      if (!c) ok = false;
+    };
+    console.log("== fleet-queue.mjs self-test ==\n");
+
+    const dir = mkdtempSync(join(tmpdir(), "hs-fleet-queue-selftest-"));
+    const qp = join(dir, "fleet-queue.jsonl");
+
+    // 1. enqueue: id + 1-indexed position, oldest-first within a lane
+    const a = enqueue({ lane: "research-firecrawl", payload: { q: "a" }, requestedBy: "agent-1", queuePath: qp, now: 1000 });
+    check("1 first enqueue gets position 1", a.position === 1 && typeof a.id === "string");
+    const b = enqueue({ lane: "research-firecrawl", payload: { q: "b" }, requestedBy: "agent-2", queuePath: qp, now: 2000 });
+    check("2 second enqueue in same lane gets position 2", b.position === 2);
+    const otherLane = enqueue({ lane: "build-gpu0", payload: { job: "x" }, queuePath: qp, now: 2500 });
+    check("3 a different lane starts its own position count", otherLane.position === 1);
+
+    // 2. nextPending returns oldest first, scoped to the lane
+    check("4 nextPending returns the oldest pending item in the lane", nextPending("research-firecrawl", { queuePath: qp, now: 3000 })?.id === a.id);
+    check("5 nextPending is lane-scoped", nextPending("build-gpu0", { queuePath: qp, now: 3000 })?.id === otherLane.id);
+
+    // 3. claim -> complete happy path
+    const claimA = claim(a.id, "claimant-1", { queuePath: qp, now: 4000 });
+    check("6 claim succeeds on a pending item", claimA.ok === true && claimA.reclaimed === false);
+    check("7 nextPending skips the now-claimed item", nextPending("research-firecrawl", { queuePath: qp, now: 4500 })?.id === b.id);
+    const doneA = complete(a.id, { savedTo: "specs/research/x.md" }, { queuePath: qp, now: 5000 });
+    check("8 complete succeeds on a claimed item", doneA.ok === true);
+    check("9 list reflects completed status + result", list("research-firecrawl", null, { queuePath: qp, now: 5500 }).find((i) => i.id === a.id)?.status === "completed");
+
+    // 4. double-claim rejection
+    const claimB1 = claim(b.id, "claimant-1", { queuePath: qp, now: 6000 });
+    check("10 first claim on b succeeds", claimB1.ok === true);
+    const claimB2 = claim(b.id, "claimant-2", { queuePath: qp, now: 6100 });
+    check("11 a second claim on the SAME still-live item is rejected", claimB2.ok === false && /already claimed/.test(claimB2.reason));
+
+    // 5. fail path
+    const failB = fail(b.id, "endpoint unreachable", { queuePath: qp, now: 7000 });
+    check("12 fail succeeds on a claimed item", failB.ok === true);
+    check("13 list reflects failed status + reason", list(null, "failed", { queuePath: qp, now: 7500 }).find((i) => i.id === b.id)?.failReason === "endpoint unreachable");
+    check("14 cannot claim a failed (terminal) item", claim(b.id, "claimant-3", { queuePath: qp, now: 7600 }).ok === false);
+    check("15 cannot complete an already-completed item", complete(a.id, {}, { queuePath: qp, now: 7700 }).ok === false);
+
+    // 6. crash-recovery semantics: a claimed-but-stale entry is reclaimable after the TTL
+    const c = enqueue({ lane: "research-firecrawl", payload: { q: "c" }, queuePath: qp, now: 10_000 });
+    const claimC = claim(c.id, "claimant-crashed", { queuePath: qp, now: 10_100, ttlMs: 1000 });
+    check("16 c gets claimed", claimC.ok === true);
+    const tooSoon = claim(c.id, "claimant-4", { queuePath: qp, now: 10_500, ttlMs: 1000 }); // 400ms later, still under 1000ms TTL
+    check("17 reclaim attempt before TTL expiry is rejected", tooSoon.ok === false);
+    const afterTtl = claim(c.id, "claimant-4", { queuePath: qp, now: 11_200, ttlMs: 1000 }); // 1100ms later, TTL exceeded
+    check("18 reclaim attempt after TTL expiry succeeds (stale claim reclaimed)", afterTtl.ok === true && afterTtl.reclaimed === true);
+    check("19 the ORIGINAL claim event is not erased — still visible in list()'s claimant history via the latest fold", list("research-firecrawl", "claimed", { queuePath: qp, now: 11_300, ttlMs: 1000 }).find((i) => i.id === c.id)?.claimant === "claimant-4");
+
+    // 7. unknown id handling
+    check("20 claim on an unknown id fails cleanly", claim("fq_does_not_exist", "x", { queuePath: qp }).ok === false);
+    check("21 complete on an unknown id fails cleanly", complete("fq_does_not_exist", {}, { queuePath: qp }).ok === false);
+
+    // 8. concurrent double-claim: two "processes" race claim() on the same id — only one wins
+    const d = enqueue({ lane: "research-firecrawl", payload: { q: "d" }, queuePath: qp, now: 12_000 });
+    const [raceA, raceB] = await Promise.all([
+      Promise.resolve().then(() => claim(d.id, "racer-A", { queuePath: qp, now: 12_100 })),
+      Promise.resolve().then(() => claim(d.id, "racer-B", { queuePath: qp, now: 12_100 })),
+    ]);
+    const winners = [raceA, raceB].filter((r) => r.ok);
+    check("22 concurrent claim() calls on the same id: exactly one wins", winners.length === 1);
+
+    // 9. append-only: the file only grows, corrupt trailing line tolerated
+    const beforeLines = readFileSync(qp, "utf8").split("\n").filter(Boolean).length;
+    const { appendFileSync } = await import("node:fs");
+    appendFileSync(qp, '{"type":"claim","id":"broken", partial-json');
+    check("23 a corrupt trailing line does not throw when reading state", (() => {
+      try {
+        list(null, null, { queuePath: qp });
+        return true;
+      } catch {
+        return false;
+      }
+    })());
+    check("24 file only grew (never rewritten) across the whole run", readFileSync(qp, "utf8").split("\n").filter(Boolean).length >= beforeLines);
+
+    rm(dir, { recursive: true, force: true });
+    console.log(`\n${ok ? "✓ self-test PASS" : "✗ self-test FAIL"}`);
+    process.exit(ok ? 0 : 1);
+  })();
+}

package/dev-factory/lib/fleet-state.mjs

@@ -29,22 +29,18 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { tmpdir } from "node:os";
+import { codeRepoRoot } from "./code-repo-root.mjs";
+import { OLLAMA } from "./model-catalog.mjs";
 
 const SCHEMA_VERSION = 1;
 
-// ── Repo-root resolution (walk up to the heyspex.yaml vault marker — same as join-codes.mjs) ──
-export function findRepoRoot(startDir = process.cwd()) {
-  let dir = resolve(startDir);
-  for (;;) {
-    if (existsSync(join(dir, "heyspex.yaml"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return resolve(startDir);
+// ── Repo-root resolution: this store holds CODE-repo state (fleet-state.json), not vault
+//    state, so it anchors on the code repo itself rather than walking for a vault marker.
+export function findRepoRoot() {
+  return codeRepoRoot();
 }
 
 function heyspexDir(opts = {}) {
@@ -184,20 +180,20 @@ function runSelfTest() {
     return s.version === 1 && Object.keys(s.machines).length === 0;
   })());
 
-  const first = recordProbe("night-action", { ok: true, models: ["gpt-oss:20b"] }, opts);
+  const first = recordProbe("night-action", { ok: true, models: [OLLAMA.BUILDER] }, opts);
   check("first ok probe creates the machine with firstSeen/lastSeen/lastProbe stamped",
     first.firstSeen != null && first.lastSeen != null && first.lastProbe?.ok === true);
   check("first-ever models land in newModels (nothing is silently 'known')",
-    first.newModels.includes("gpt-oss:20b") && first.knownModels.length === 0);
+    first.newModels.includes(OLLAMA.BUILDER) && first.knownModels.length === 0);
 
-  acknowledgeModels("night-action", ["gpt-oss:20b"], opts);
+  acknowledgeModels("night-action", [OLLAMA.BUILDER], opts);
   const acked = loadFleetState(opts).machines["night-action"];
   check("acknowledgeModels moves the model newModels → knownModels",
-    acked.knownModels.includes("gpt-oss:20b") && !acked.newModels.includes("gpt-oss:20b"));
+    acked.knownModels.includes(OLLAMA.BUILDER) && !acked.newModels.includes(OLLAMA.BUILDER));
 
-  const drift = recordProbe("night-action", { ok: true, models: ["gpt-oss:20b", "qwen3:32b"] }, opts);
+  const drift = recordProbe("night-action", { ok: true, models: [OLLAMA.BUILDER, "qwen3:32b"] }, opts);
   check("re-probe diffs against knownModels — only the NEW model joins newModels",
-    drift.newModels.length === 1 && drift.newModels[0] === "qwen3:32b" && drift.knownModels.includes("gpt-oss:20b"));
+    drift.newModels.length === 1 && drift.newModels[0] === "qwen3:32b" && drift.knownModels.includes(OLLAMA.BUILDER));
 
   const seenBefore = drift.lastSeen;
   const failed = recordProbe("night-action", { ok: false }, opts);
@@ -213,7 +209,7 @@ function runSelfTest() {
 
   check("state persists across a fresh load (atomic tmp+rename write)", (() => {
     const s = loadFleetState(opts);
-    return s.machines["night-action"]?.knownModels.includes("gpt-oss:20b")
+    return s.machines["night-action"]?.knownModels.includes(OLLAMA.BUILDER)
       && s.machines["basement-geek"]?.fleetVersion === "0.3.1"
       && s.version === 1;
   })());