heyspex 0.1.0

package/bin/postinstall.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Root postinstall guard. The dev-machine setup steps (PM control-center deps,
+// Claude Code hooks, CommandCode update) live under scripts/, which
+// .vercelignore excludes from the Vercel upload — so on Vercel (or any CI, or
+// any environment where scripts/ is absent) this must exit 0 instead of
+// crashing `npm install` with MODULE_NOT_FOUND. Lives in bin/ (uploaded to
+// Vercel) precisely so the guard itself always resolves.
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+// Installed as somebody else's dependency (HS-ZJSP): the published `heyspex`
+// package ships this file because npm runs the `postinstall` script for every
+// consumer, but NONE of the dev-machine setup below belongs in a customer's
+// install — and printing a "skipping" line at them is noise, not information.
+// A package installed from the registry always lands under a node_modules/
+// directory; a clone of this repo never does. Exit silently in the former case.
+if (repoRoot.replace(/\\/g, "/").includes("/node_modules/")) {
+  process.exit(0);
+}
+
+const steps = [
+  ["scripts/ensure-pm-cc-deps.mjs"],
+  ["scripts/install-claude-code-hooks.mjs"],
+  // Cursor's two install surfaces. `.cursor/mcp.json` is gitignored (it is
+  // machine-local), so without this step a fresh clone opens in Cursor with no
+  // heyspex MCP server at all; `.cursor/hooks.json` is tracked but merges
+  // idempotently, and the installer also retires superseded registrations.
+  ["scripts/install-cursor-mcp.mjs"],
+  ["scripts/install-cursor-hooks.mjs"],
+  ["scripts/install-commandcode.mjs", "--update"],
+  ["scripts/sync-skills.mjs"],
+  // Git hooks (.git/hooks/ is never cloned) — installs pre-commit + pre-push so a
+  // single `npm install` on a fresh clone is enough, with no second `npm run setup`.
+  // No --force: an idempotent re-run no-ops on the HeySpex hook and refuses to
+  // clobber a foreign pre-commit (exit 1 surfaces that rather than silently replacing).
+  ["scripts/install-git-hooks.mjs"],
+];
+
+if (process.env.VERCEL || process.env.CI) {
+  console.log("[postinstall] VERCEL/CI detected — skipping dev-machine setup.");
+  process.exit(0);
+}
+
+for (const [script, ...args] of steps) {
+  const abs = join(repoRoot, script);
+  if (!existsSync(abs)) {
+    console.log(`[postinstall] ${script} not present — skipping dev-machine setup.`);
+    process.exit(0);
+  }
+  const { status } = spawnSync(process.execPath, [abs, ...args], {
+    cwd: repoRoot,
+    stdio: "inherit",
+  });
+  if (status !== 0) process.exit(status ?? 1);
+}
+
+// Advisory only, never fatal, and deliberately NOT `npm link` itself: a
+// postinstall that mutates the machine's global npm prefix would repoint `hs`
+// away from whatever clone owned it, silently, on every install. `npm install`
+// completing clean while `hs` resolves nowhere is exactly the fresh-machine
+// failure in [[HS-BFXF-WBJU-DIAG-hs-never-resolves-on-a-fresh-machine]] — so
+// say so here, where a new operator is already looking, and let `npm run
+// doctor` carry the full check. Imported dynamically so the published package
+// (which ships this file but not scripts/) can never fail to resolve it.
+const hsLinkLib = join(repoRoot, "scripts/lib/hs-link.mjs");
+if (existsSync(hsLinkLib)) {
+  try {
+    const { describeHsLink } = await import(pathToFileURL(hsLinkLib).href);
+    const link = describeHsLink(repoRoot);
+    if (link.status !== "linked") {
+      const what = {
+        missing: "does not resolve on PATH",
+        foreign: `resolves to an unrelated tool (${link.target})`,
+        "other-checkout": `resolves to a DIFFERENT checkout (${link.target})`,
+        unreadable: `resolves to ${link.shim}, whose target could not be read`,
+      }[link.status];
+      console.log(`[postinstall] heads up: \`hs\` ${what}.`);
+      console.log("[postinstall] Run `npm link` once from this repo root to put hs/heyspex/heyspex-mcp on PATH.");
+      console.log("[postinstall] Until then use `node bin/hs.mjs …` — never `npx hs` (unrelated package). Details: `npm run doctor`.");
+    }
+  } catch {
+    // An advisory that crashes the install would be worse than no advisory.
+  }
+}

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

@@ -0,0 +1,274 @@
+// dev-factory/lib/fleet-readiness.mjs — shared fleet-readiness predicate (E1 / HS-CXO0).
+// Single source of truth for "should dev-factory seat identity be injected?", reused by
+// the MCP server AND scripts/claude-hooks/inject-coo-seat.mjs so the two never drift
+// (epic AC: "the MCP server and the SessionStart hook use the same predicate — no drift").
+// Build brief: dev-factory/state/briefs/fleet-readiness.brief.md
+//
+// The embedded `--self-test` below IS the deterministic gate (run via
+// `node dev-factory/controller.mjs --self-test-gate --target dev-factory/lib/fleet-readiness.mjs`).
+// Its assertions ARE the acceptance criteria made executable — the Builder seat implements
+// the two function bodies until every case passes. Do NOT weaken the assertions.
+//
+// Pure logic + injectable inputs (no network). Fail-closed: any missing/corrupt input
+// resolves to not-ready, never throws.
+import { loadFleetState } from "./fleet-state.mjs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const DEFAULT_FLEET_FRESHNESS_MS = 15 * 60 * 1000; // 15 minutes
+
+/** Repo root — honour CLAUDE_PROJECT_DIR, else walk up from this file (dev-factory/lib → root). */
+function repoRoot() {
+  if (process.env.CLAUDE_PROJECT_DIR) return process.env.CLAUDE_PROJECT_DIR;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+
+/**
+ * Is the local build fleet "set up and enabled"?
+ * @param {{fleetState?: object, routingTable?: object, nowMs?: number, freshnessMs?: number, repoRoot?: string}} opts
+ *   All injectable for tests. fleetState → loadFleetState({ repoRoot }) if omitted;
+ *   routingTable → JSON.parse(readFileSync(<repoRoot>/dev-factory/routing-table.json)) if omitted;
+ *   nowMs → Date.now(); freshnessMs → DEFAULT_FLEET_FRESHNESS_MS.
+ * @returns {{ready: boolean, reason: string, freshMachines: string[]}}
+ *
+ * ready === true only when BOTH hold:
+ *   1. ≥1 machine in fleetState.machines has lastProbe.ok === true AND
+ *      nowMs - Date.parse(lastSeen) <= freshnessMs (collected into freshMachines).
+ *   2. routingTable.purposes.build has ≥1 entry with kind === 'local' whose `machine`
+ *      key exists in routingTable.machines (a local build seat actually resolves).
+ * Fail-closed: any missing/corrupt input → { ready:false, reason:"fleet state unavailable: <msg>", freshMachines:[] }.
+ */
+export function isFleetReady(opts = {}) {
+  const {
+    fleetState: fsInput,
+    routingTable: rtInput,
+    nowMs: nowMsInput,
+    freshnessMs: freshnessMsInput,
+    repoRoot: repoRootInput,
+  } = opts;
+  const repoRootVal = repoRootInput ?? repoRoot();
+  try {
+    const fleetState = fsInput ?? loadFleetState({ repoRoot: repoRootVal });
+    if (!fleetState || typeof fleetState !== "object" || !fleetState.machines)
+      throw new Error("invalid fleetState");
+    const routingTable =
+      rtInput ??
+      JSON.parse(
+        readFileSync(
+          path.join(repoRootVal, "dev-factory", "routing-table.json"),
+          "utf8",
+        ),
+      );
+    if (!routingTable || typeof routingTable !== "object")
+      throw new Error("invalid routingTable");
+    const nowMs = nowMsInput ?? Date.now();
+    const freshnessMs = freshnessMsInput ?? DEFAULT_FLEET_FRESHNESS_MS;
+    // compute freshMachines
+    const freshMachines = [];
+    for (const [machine, info] of Object.entries(fleetState.machines || {})) {
+      try {
+        if (!info.lastProbe?.ok) continue;
+        // lastSeen is the primary freshness stamp, but historically it was never
+        // written on some paths (sidecar rows with lastSeen: null). A healthy
+        // probe timestamp is an equivalent liveness signal — fall back to
+        // lastProbe.at so a null/unparseable lastSeen doesn't permanently
+        // report the fleet as not-ready.
+        let seenMs = Date.parse(info.lastSeen);
+        if (isNaN(seenMs)) seenMs = Date.parse(info.lastProbe?.at);
+        if (isNaN(seenMs)) continue;
+        if (nowMs - seenMs <= freshnessMs) freshMachines.push(machine);
+      } catch {}
+    }
+    if (freshMachines.length === 0) {
+      return {
+        ready: false,
+        reason: "no recent healthy probe",
+        freshMachines: [],
+      };
+    }
+    // check routing table
+    const localBuild = (routingTable.purposes?.build ?? []).find(
+      (entry) => entry.kind === "local" && routingTable.machines[entry.machine],
+    );
+    if (!localBuild) {
+      return {
+        ready: false,
+        reason: "no resolvable local build seat",
+        freshMachines: [],
+      };
+    }
+    return { ready: true, reason: "fleet ready", freshMachines };
+  } catch (e) {
+    return {
+      ready: false,
+      reason: "fleet state unavailable: " + String(e),
+      freshMachines: [],
+    };
+  }
+}
+
+/**
+ * Resolve the effective on/off state given seats.json settings.cooMode (true | false | "auto").
+ * @param {boolean|"auto"|null|undefined} cooMode
+ * @param {object} opts forwarded to isFleetReady when cooMode === "auto".
+ * @returns {{enabled: boolean, reason: string}}
+ *   true  → { enabled:true,  reason:"cooMode=on (explicit)" }
+ *   false/null/undefined → { enabled:false, reason:"cooMode=off (explicit)" }
+ *   "auto" → { enabled: isFleetReady(opts).ready, reason:"cooMode=auto → " + <that reason> }
+ *   else   → { enabled:false, reason:"cooMode unrecognized: " + String(cooMode) }
+ */
+export function resolveCooModeEnabled(cooMode, opts = {}) {
+  if (cooMode === true || cooMode === "on") {
+    return { enabled: true, reason: "cooMode=on (explicit)" };
+  }
+  if (cooMode === false || cooMode == null) {
+    return { enabled: false, reason: "cooMode=off (explicit)" };
+  }
+  if (cooMode === "auto") {
+    const r = isFleetReady(opts);
+    return { enabled: r.ready, reason: "cooMode=auto → " + r.reason };
+  }
+  return { enabled: false, reason: "cooMode unrecognized: " + String(cooMode) };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deterministic gate — `node dev-factory/lib/fleet-readiness.mjs --self-test`
+// These assertions ARE the acceptance criteria. Do NOT weaken them.
+// All inputs INJECTED (no disk, no network).
+// ─────────────────────────────────────────────────────────────────────────────
+function runSelfTest() {
+  let ok = true;
+  const check = (name, cond) => {
+    console.log(`  ${cond ? "✓" : "✗"} ${name}`);
+    if (!cond) ok = false;
+  };
+  console.log("== dev-factory/lib/fleet-readiness.mjs self-test ==\n");
+
+  const nowMs = Date.parse("2026-07-05T08:00:00.000Z");
+  const iso = (deltaMs) => new Date(nowMs + deltaMs).toISOString();
+
+  // A routing table with a resolvable local build seat (machine 'basement' exists).
+  const routingTable = {
+    machines: { "night-action": {}, "basement-geek": {} },
+    purposes: { build: [{ kind: "local", machine: "basement-geek" }] },
+  };
+  // A routing table with NO resolvable local build seat.
+  const noBuildTable = { machines: {}, purposes: { build: [] } };
+
+  const fresh = {
+    version: 1,
+    machines: {
+      basement: {
+        lastProbe: { at: iso(-60_000), ok: true },
+        lastSeen: iso(-60_000),
+      },
+    },
+  }; // 1 min ago
+  const stale = {
+    version: 1,
+    machines: {
+      basement: {
+        lastProbe: { at: iso(-60 * 60_000), ok: true },
+        lastSeen: iso(-60 * 60_000),
+      },
+    },
+  }; // 60 min ago
+
+  check(
+    "fresh fleet + resolvable local build seat → ready",
+    isFleetReady({ fleetState: fresh, routingTable, nowMs }).ready === true,
+  );
+  check(
+    "stale fleet (probe > freshnessMs old) → not ready",
+    isFleetReady({ fleetState: stale, routingTable, nowMs }).ready === false,
+  );
+  check(
+    "fresh fleet but no resolvable local build seat → not ready",
+    isFleetReady({ fleetState: fresh, routingTable: noBuildTable, nowMs })
+      .ready === false,
+  );
+
+  // lastSeen was never stamped on some sidecar paths — a fresh healthy probe
+  // (lastProbe.ok + fresh lastProbe.at) must still count the machine as fresh.
+  const nullSeenFreshProbe = {
+    version: 1,
+    machines: {
+      basement: {
+        lastProbe: { at: iso(-60_000), ok: true },
+        lastSeen: null,
+      },
+    },
+  };
+  const nullSeenStaleProbe = {
+    version: 1,
+    machines: {
+      basement: {
+        lastProbe: { at: iso(-60 * 60_000), ok: true },
+        lastSeen: null,
+      },
+    },
+  };
+  check(
+    "lastSeen null but fresh healthy probe → ready (lastProbe.at fallback)",
+    isFleetReady({ fleetState: nullSeenFreshProbe, routingTable, nowMs })
+      .ready === true,
+  );
+  check(
+    "lastSeen null and stale probe → not ready",
+    isFleetReady({ fleetState: nullSeenStaleProbe, routingTable, nowMs })
+      .ready === false,
+  );
+
+  check(
+    "resolveCooModeEnabled(true) → enabled",
+    resolveCooModeEnabled(true).enabled === true,
+  );
+  check(
+    "resolveCooModeEnabled(false) → disabled",
+    resolveCooModeEnabled(false).enabled === false,
+  );
+  check(
+    "resolveCooModeEnabled('auto', fresh) → enabled",
+    resolveCooModeEnabled("auto", { fleetState: fresh, routingTable, nowMs })
+      .enabled === true,
+  );
+  check(
+    "resolveCooModeEnabled('auto', stale) → disabled",
+    resolveCooModeEnabled("auto", { fleetState: stale, routingTable, nowMs })
+      .enabled === false,
+  );
+
+  // Fail-closed: a corrupt fleetState (machines is null) must NOT throw and must be not-ready.
+  check(
+    "corrupt input → ready:false and does NOT throw",
+    (() => {
+      try {
+        const r = isFleetReady({
+          fleetState: { machines: null },
+          routingTable,
+          nowMs,
+        });
+        return r.ready === false;
+      } catch {
+        return false;
+      }
+    })(),
+  );
+
+  console.log(
+    `\n${
+      ok
+        ? "✓ self-test PASS — fresh/stale gating, local-build-seat resolution, cooMode true/false/auto, fail-closed corrupt input verified."
+        : "✗ self-test FAIL"
+    }`,
+  );
+  return ok ? 0 : 1;
+}
+
+if (
+  process.argv[1] &&
+  pathToFileURL(process.argv[1]).href === import.meta.url
+) {
+  if (process.argv.includes("--self-test")) process.exit(runSelfTest());
+}

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

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * lib/fleet-state.mjs — per-machine runtime state sidecar (engine-side half of a twin pair).
+ *
+ * Operates on the SAME store file as spex-console/src/lib/fleet/fleet-state-store.ts, with a
+ * BYTE-IDENTICAL schema (the join-codes.mjs ↔ join-code-store.ts twin pattern):
+ *   store: <repo>/.heyspex/fleet-state.json
+ *
+ * This is RUNTIME state (lastSeen / probe results / model inventory drift / roles / fleet
+ * version) — deliberately NOT routing-table.json (identity + routing, sole writer
+ * lib/routing-updater.mjs). The routing table says what a machine IS; this file says what it
+ * was DOING last time anyone looked.
+ *
+ * Schema (version field for migration):
+ *   { "version": 1, "machines": { "<machineKey>": {
+ *       "roles": ["build"], "firstSeen": "<iso>", "lastSeen": "<iso|null>",
+ *       "lastProbe": { "at": "<iso>", "ok": true },
+ *       "knownModels": ["llama3:8b"], "newModels": ["qwen3:32b"],
+ *       "fleetVersion": null, "notes": null } } }
+ *
+ * Model drift contract: recordProbe diffs the probed model list against knownModels — anything
+ * unseen lands in newModels (the "new model appeared on this box" signal for the console) and
+ * STAYS there until acknowledgeModels() moves it into knownModels.
+ *
+ * SCHEMA NOTE: this file is the store's FIRST reader/writer; the TypeScript module is the
+ * second. Keep field names in lock-step.
+ *
+ *   node dev-factory/lib/fleet-state.mjs --self-test
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
+
+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);
+}
+
+function heyspexDir(opts = {}) {
+  const root = opts.rootDir ?? findRepoRoot();
+  const dir = join(root, ".heyspex");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+const storePath = (opts = {}) => join(heyspexDir(opts), "fleet-state.json");
+
+const emptyState = () => ({ version: SCHEMA_VERSION, machines: {} });
+
+/** Load the fleet-state document. Fail closed: missing/corrupt file → an empty v1 state. */
+export function loadFleetState(opts = {}) {
+  const p = storePath(opts);
+  if (!existsSync(p)) return emptyState();
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf8"));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.machines !== "object" || parsed.machines === null) {
+      return emptyState();
+    }
+    return { version: parsed.version ?? SCHEMA_VERSION, machines: parsed.machines };
+  } catch {
+    return emptyState();
+  }
+}
+
+function writeFleetState(state, opts = {}) {
+  const p = storePath(opts);
+  const tmp = `${p}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
+  renameSync(tmp, p);
+}
+
+const defaultMachine = (nowIso) => ({
+  roles: [],
+  firstSeen: nowIso,
+  lastSeen: null,
+  lastProbe: null,
+  knownModels: [],
+  newModels: [],
+  fleetVersion: null,
+  notes: null,
+});
+
+function ensureMachine(state, machineKey, nowIso) {
+  if (!state.machines[machineKey]) state.machines[machineKey] = defaultMachine(nowIso);
+  return state.machines[machineKey];
+}
+
+/**
+ * Record one probe result for a machine (creates the entry on first sight).
+ *   - lastProbe = { at, ok } always
+ *   - lastSeen stamped ONLY on ok
+ *   - models (when given): diffed against knownModels — anything unseen joins newModels
+ *     until acknowledgeModels() moves it to knownModels.
+ * Returns the updated machine record.
+ */
+export function recordProbe(machineKey, { ok, models } = {}, opts = {}) {
+  if (!machineKey) throw new Error("fleet-state: recordProbe needs a machineKey");
+  const nowIso = new Date().toISOString();
+  const state = loadFleetState(opts);
+  const m = ensureMachine(state, machineKey, nowIso);
+  m.lastProbe = { at: nowIso, ok: Boolean(ok) };
+  if (ok) m.lastSeen = nowIso;
+  if (Array.isArray(models)) {
+    for (const model of models) {
+      if (typeof model !== "string" || !model) continue;
+      if (!m.knownModels.includes(model) && !m.newModels.includes(model)) m.newModels.push(model);
+    }
+  }
+  writeFleetState(state, opts);
+  return m;
+}
+
+/**
+ * Acknowledge models: move each listed model out of newModels and into knownModels
+ * (added to knownModels even if it was never in newModels — an explicit ack wins).
+ * Returns the updated machine record, or null if the machine is unknown.
+ */
+export function acknowledgeModels(machineKey, models = [], opts = {}) {
+  const state = loadFleetState(opts);
+  const m = state.machines[machineKey];
+  if (!m) return null;
+  for (const model of models) {
+    if (typeof model !== "string" || !model) continue;
+    m.newModels = m.newModels.filter((x) => x !== model);
+    if (!m.knownModels.includes(model)) m.knownModels.push(model);
+  }
+  writeFleetState(state, opts);
+  return m;
+}
+
+/** Replace a machine's roles list (creates the entry if unseen). Returns the record. */
+export function setRoles(machineKey, roles = [], opts = {}) {
+  if (!machineKey) throw new Error("fleet-state: setRoles needs a machineKey");
+  const nowIso = new Date().toISOString();
+  const state = loadFleetState(opts);
+  const m = ensureMachine(state, machineKey, nowIso);
+  m.roles = roles.filter((r) => typeof r === "string" && r);
+  writeFleetState(state, opts);
+  return m;
+}
+
+/** Set a machine's fleet software version (creates the entry if unseen). Returns the record. */
+export function setFleetVersion(machineKey, v, opts = {}) {
+  if (!machineKey) throw new Error("fleet-state: setFleetVersion needs a machineKey");
+  const nowIso = new Date().toISOString();
+  const state = loadFleetState(opts);
+  const m = ensureMachine(state, machineKey, nowIso);
+  m.fleetVersion = v ?? null;
+  writeFleetState(state, opts);
+  return m;
+}
+
+/** Remove a machine's runtime state entirely. Returns true if an entry was removed. */
+export function forgetMachine(machineKey, opts = {}) {
+  const state = loadFleetState(opts);
+  if (!state.machines[machineKey]) return false;
+  delete state.machines[machineKey];
+  writeFleetState(state, opts);
+  return true;
+}
+
+// ── Self-test (temp-dir store — never touches the real .heyspex) ───────────────────
+function runSelfTest() {
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  console.log("== lib/fleet-state.mjs self-test ==\n");
+
+  const root = join(tmpdir(), `hs-fleetstate-selftest-${process.pid}`);
+  mkdirSync(join(root, ".heyspex"), { recursive: true });
+  const opts = { rootDir: root };
+
+  check("empty store loads as version-1 empty state", (() => {
+    const s = loadFleetState(opts);
+    return s.version === 1 && Object.keys(s.machines).length === 0;
+  })());
+
+  const first = recordProbe("night-action", { ok: true, models: ["gpt-oss:20b"] }, 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);
+
+  acknowledgeModels("night-action", ["gpt-oss:20b"], 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"));
+
+  const drift = recordProbe("night-action", { ok: true, models: ["gpt-oss:20b", "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"));
+
+  const seenBefore = drift.lastSeen;
+  const failed = recordProbe("night-action", { ok: false }, opts);
+  check("failed probe records lastProbe.ok=false but does NOT advance lastSeen",
+    failed.lastProbe.ok === false && failed.lastSeen === seenBefore);
+
+  const withRoles = setRoles("basement-geek", ["build", "critic"], opts);
+  check("setRoles creates an unseen machine and stores the roles",
+    withRoles.roles.join(",") === "build,critic" && withRoles.lastSeen === null);
+
+  const withVersion = setFleetVersion("basement-geek", "0.3.1", opts);
+  check("setFleetVersion stamps fleetVersion", withVersion.fleetVersion === "0.3.1");
+
+  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")
+      && s.machines["basement-geek"]?.fleetVersion === "0.3.1"
+      && s.version === 1;
+  })());
+
+  check("forgetMachine removes the entry (true) and is a no-op the second time (false)",
+    forgetMachine("basement-geek", opts) === true && forgetMachine("basement-geek", opts) === false
+    && loadFleetState(opts).machines["basement-geek"] === undefined);
+
+  check("corrupt store fails closed to an empty state (never throws)", (() => {
+    writeFileSync(join(root, ".heyspex", "fleet-state.json"), "{not json");
+    const s = loadFleetState(opts);
+    return s.version === 1 && Object.keys(s.machines).length === 0;
+  })());
+
+  check("acknowledgeModels on an unknown machine returns null (no phantom entry)",
+    acknowledgeModels("ghost", ["m"], opts) === null);
+
+  console.log(`\n${ok ? "✓ self-test PASS — create-on-probe, lastSeen gating, model drift → newModels, acknowledge, roles/version, forget, atomic persistence, fail-closed load verified." : "✗ self-test FAIL"}`);
+  return ok ? 0 : 1;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────────
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  if (process.argv.includes("--self-test")) process.exit(runSelfTest());
+  console.log([
+    "lib/fleet-state.mjs — per-machine runtime state sidecar (.heyspex/fleet-state.json).",
+    "",
+    "  import { loadFleetState, recordProbe, acknowledgeModels, setRoles, setFleetVersion, forgetMachine } from \"./lib/fleet-state.mjs\";",
+    "  node dev-factory/lib/fleet-state.mjs --self-test",
+  ].join("\n"));
+  process.exit(0);
+}
+
+export const FLEET_STATE_VERSION = SCHEMA_VERSION;