heyspex 0.2.1 → 0.2.3

package/scripts/lib/standalone-doctor.mjs

@@ -24,7 +24,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 import { TEMPLATE_CORE_DESTS, TEMPLATE_VERSION } from "./template-pin.mjs";
 
@@ -180,15 +180,49 @@ function readTemplatePin(yamlText) {
   return v.length > 0 ? v : null;
 }
 
+/** Same-path test, case-insensitive on Windows, separator-agnostic. */
+function samePathLoose(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const norm = (p) => {
+    const s = resolve(p).replace(/\\/g, "/").replace(/\/+$/, "");
+    return process.platform === "win32" ? s.toLowerCase() : s;
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * The `hs init --customer-vault <dir>` form that repairs `vaultRoot` from
+ * where the doctor was invoked: `.` only when the caller already stands in
+ * the vault; otherwise the vault's absolute path, double-quoted when it
+ * carries a backslash or whitespace (Git Bash eats bare backslashes). A
+ * satellite repo's doctor audits `../<vault>`, so `.` there would scaffold
+ * the wrong directory ([[HS-NXNP-36X3-DIAG-the-hs-launcher-loses-the-caller-s]]).
+ * Pure; exported for the full doctor to render through `hsCommand`.
+ */
+export function templateRepairCommand(vaultRoot, invokedCwd) {
+  if (typeof vaultRoot !== "string" || vaultRoot.length === 0) {
+    return "hs init --customer-vault .";
+  }
+  if (invokedCwd === undefined || samePathLoose(vaultRoot, invokedCwd)) {
+    return "hs init --customer-vault .";
+  }
+  const target = /[\\\s]/.test(vaultRoot) ? `"${vaultRoot}"` : vaultRoot;
+  return `hs init --customer-vault ${target}`;
+}
+
 /**
  * The `vault-template` doctor row: does a customer vault carry the current
  * HeySpex template (HS-KH0Q)? Pure over injectable `exists` / `readFile`
  * (default node:fs; `readFile` returns the text or null), same row shape as
- * {@link vaultConfigCheckRow}.
+ * {@link vaultConfigCheckRow}. `opts.invokedCwd` (the caller's directory)
+ * decides whether the repair names `.` or the vault's absolute path — see
+ * {@link templateRepairCommand}; the row carries that command as `repair`.
  *   - platform vault (marker protocol present) -> ok: it is the template source;
- *   - any core dest missing -> fail, naming the files, repair `hs init --customer-vault .`;
+ *   - any core dest missing -> fail, naming the files, with the repair;
  *   - `heyspex.yaml` pins {@link TEMPLATE_VERSION} -> ok;
- *   - pin older/newer/absent while the files exist -> warn.
+ *   - pin older/newer/absent while the files exist -> warn, same repair.
+ * The repair is `hs init --customer-vault` on an EXISTING vault, which is a
+ * REFRESH (adds only missing shipped files, writes the pin, never overwrites).
  */
 export function templateCheckRow(vaultRoot, opts = {}) {
   const exists = opts.exists ?? existsSync;
@@ -202,12 +236,16 @@ export function templateCheckRow(vaultRoot, opts = {}) {
       }
     });
   const id = "vault-template";
-  const repair = "hs init --customer-vault .";
+  // The published-install doctor (`bin/hs.mjs` runStandaloneDoctor) never
+  // chdirs, so its own cwd IS the caller's directory; the full doctor is
+  // spawned at the platform root and passes HS_INVOKED_CWD explicitly.
+  const repair = templateRepairCommand(vaultRoot, opts.invokedCwd ?? process.cwd());
   if (typeof vaultRoot !== "string" || vaultRoot.length === 0) {
     return {
       id,
       status: "fail",
       detail: "template not checked — no vault root resolved",
+      repair,
       human: `No vault was found. Run \`${repair}\` in the directory that should become the vault.`,
     };
   }
@@ -225,9 +263,10 @@ export function templateCheckRow(vaultRoot, opts = {}) {
       id,
       status: "fail",
       detail: `missing template file(s): ${missing.join(", ")}`,
+      repair,
       human:
         `The vault is missing ${missing.length} shipped template file(s): ${missing.join(", ")}. ` +
-        `Run \`${repair}\` in the vault directory — it adds only what is missing and never overwrites an existing file.`,
+        `Run \`${repair}\` — on an existing vault it adds only what is missing, writes the template_version pin, and never overwrites an existing file.`,
     };
   }
   const pin = readTemplatePin(readFile(at("heyspex.yaml")));
@@ -244,7 +283,8 @@ export function templateCheckRow(vaultRoot, opts = {}) {
     detail: pin
       ? `heyspex.yaml pins template v${pin}, current is v${TEMPLATE_VERSION}`
       : `heyspex.yaml has no template_version pin (current is v${TEMPLATE_VERSION})`,
-    human: `Core template files are present but the pin is not current. Run \`${repair}\` to refresh the pin and add any newer shipped files.`,
+    repair,
+    human: `Core template files are present but the pin is not current. Run \`${repair}\` — it refreshes the pin in heyspex.yaml, adds any newer shipped files, and never overwrites an existing file.`,
   };
 }
 
@@ -289,25 +329,56 @@ export function classifyRegistryFile(rawText) {
   ];
   const accounts =
     json.accounts && typeof json.accounts === "object" ? json.accounts : {};
+  const legacyRows = rows.filter(
+    (r) => r && typeof r === "object" && (r.account_id ?? LEGACY) === LEGACY,
+  );
   const legacy =
     Object.prototype.hasOwnProperty.call(accounts, LEGACY) ||
     json.current_account_id === LEGACY ||
-    rows.some(
-      (r) => r && typeof r === "object" && (r.account_id ?? LEGACY) === LEGACY,
-    );
-  return { kind: legacy ? "legacy" : "v2" };
+    legacyRows.length > 0;
+  return { kind: legacy ? "legacy" : "v2", legacyRows };
+}
+
+/** First `account:` / `account_id:` scalar of a heyspex.yaml text, or null. Pure. */
+function markerAccountOf(text) {
+  if (typeof text !== "string") return null;
+  const m = text.match(/^account(?:_id)?:\s*["']?([^"'\s#]+)/m);
+  return m ? m[1] : null;
+}
+
+/**
+ * Which `legacy` rows `hs vault migrate-registry` could actually re-key —
+ * the same two proofs the migration itself accepts (`registry-file.ts`
+ * `planRegistryMigration`): the row's repo `heyspex.yaml` records an
+ * `account:`, or (vault rows) the signed-in account's cloud roster lists the
+ * id. Pure over the injected readers; with none injected nothing is provable.
+ * @param {Array<object>} legacyRows
+ * @param {{ readMarker?: (root: string) => string | null, cloudVaultIds?: string[] | null }} opts
+ */
+export function provableLegacyRows(legacyRows, { readMarker, cloudVaultIds } = {}) {
+  const cloud = new Set(Array.isArray(cloudVaultIds) ? cloudVaultIds : []);
+  return legacyRows.filter((r) => {
+    if (typeof r?.id === "string" && cloud.has(r.id)) return true;
+    if (!readMarker || typeof r?.repo_root_abs !== "string") return false;
+    const account = markerAccountOf(readMarker(r.repo_root_abs));
+    return Boolean(account) && account !== "legacy";
+  });
 }
 
 /**
  * Render {@link classifyRegistryFile} as one `hs doctor` row (`registry-schema`).
- * A v1 file (or v2 with `legacy` state) is a `warn` that carries
- * {@link REGISTRY_SCHEMA_FIX}, so `hs doctor --fix` runs `hs vault
- * migrate-registry`. It is a warn, not a fail: the loader still reads a v1
- * file. An unreadable file is a warn with no fix — the migration refuses to
- * overwrite it, so a human looks first.
+ * A v1 file is a `warn` that carries {@link REGISTRY_SCHEMA_FIX}, so `hs
+ * doctor --fix` runs `hs vault migrate-registry`. A v2 file with rows still
+ * keyed `legacy` warns ONLY when that migration would actually re-key one of
+ * them ({@link provableLegacyRows}, via `opts.readMarker` / `opts.cloudVaultIds`):
+ * the migration leaves UNPROVEN rows on `legacy` by design, so warning about
+ * them named a repair that is a no-op and the warn never cleared. Unprovable
+ * legacy rows are `ok`, with the count in the detail. It is a warn, not a
+ * fail: the loader still reads a v1 file. An unreadable file is a warn with
+ * no fix — the migration refuses to overwrite it, so a human looks first.
  */
-export function registrySchemaCheckRow(rawText) {
-  const { kind } = classifyRegistryFile(rawText);
+export function registrySchemaCheckRow(rawText, opts = {}) {
+  const { kind, legacyRows = [] } = classifyRegistryFile(rawText);
   const id = "registry-schema";
   if (kind === "missing") {
     return {
@@ -334,20 +405,41 @@ export function registrySchemaCheckRow(rawText) {
         "(`hs vault migrate-registry` will not overwrite it).",
     };
   }
-  const detail =
-    kind === "v1"
-      ? "schema v1 — one machine-global active vault for every account"
-      : "schema v2, but some rows are still keyed to `legacy` (no account)";
+  const human =
+    "Run `hs vault migrate-registry --dry-run` to see the plan, then `hs vault migrate-registry` " +
+    "(or `hs doctor --fix`) while signed in: it rewrites ~/.heyspex/registry.json as schema v2 " +
+    "and keys each row to the account PROVEN for it (its heyspex.yaml `account:`, or your cloud " +
+    "vault roster). Unproven rows stay `legacy` and keep resolving. A second run changes nothing.";
+  if (kind === "v1") {
+    return {
+      id,
+      status: "warn",
+      detail:
+        "schema v1 — one machine-global active vault for every account; fix: `hs vault migrate-registry`",
+      fix: [...REGISTRY_SCHEMA_FIX],
+      human,
+    };
+  }
+  const provable = provableLegacyRows(legacyRows, opts);
+  if (provable.length > 0) {
+    const ids = provable.map((r) => r.id ?? "?").join(", ");
+    return {
+      id,
+      status: "warn",
+      detail:
+        `schema v2; ${provable.length} of ${legacyRows.length} legacy row(s) can be re-keyed to an account ` +
+        `(${ids}); fix: \`hs vault migrate-registry\``,
+      fix: [...REGISTRY_SCHEMA_FIX],
+      human,
+    };
+  }
   return {
     id,
-    status: "warn",
-    detail: `${detail}; fix: \`hs vault migrate-registry\``,
-    fix: [...REGISTRY_SCHEMA_FIX],
-    human:
-      "Run `hs vault migrate-registry --dry-run` to see the plan, then `hs vault migrate-registry` " +
-      "(or `hs doctor --fix`) while signed in: it rewrites ~/.heyspex/registry.json as schema v2 " +
-      "and keys each row to the account PROVEN for it (its heyspex.yaml `account:`, or your cloud " +
-      "vault roster). Unproven rows stay `legacy` and keep resolving. A second run changes nothing.",
+    status: "ok",
+    detail:
+      legacyRows.length > 0
+        ? `schema v2; ${legacyRows.length} row(s) on legacy (unprovable, kept by design — they still resolve)`
+        : "schema v2; a legacy pointer remains (nothing to re-key)",
   };
 }
 
@@ -543,11 +635,18 @@ export function foldConnectionReport(
 
   let summary;
   if (failed.length > 0) {
+    // Each failing per-row entry already prints its own repair as `human`
+    // (a doctor's "Needs you" list shows every row with one), so the summary
+    // repeats the list only when some failing row has no repair of its own —
+    // otherwise the same command showed up twice.
+    const uncovered = failed.filter((r) => !r.human);
     const repairs = [...new Set(failed.map((r) => r.repair).filter(Boolean))];
     summary = {
       status: "fail",
-      detail: `${failed.length} local-vs-cloud row(s) disagree: ${failed.map((r) => r.id.slice(idPrefix.length + 1)).join(", ")}`,
-      human: `Run the repair named on each failing row: ${repairs.join("; ")}`,
+      detail: `${failed.length} local-vs-cloud row(s) disagree: ${failed.map((r) => r.id.slice(idPrefix.length + 1)).join(", ")} — see each row's repair`,
+      ...(uncovered.length > 0
+        ? { human: `Run the repair named on each failing row: ${repairs.join("; ")}` }
+        : {}),
     };
   } else if (!localConnected) {
     summary = {

package/scripts/wip-ledger-health.mjs

@@ -29,7 +29,8 @@
  */
 import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./lib/shared-path-helpers.mjs";
 
 import { getAuthHeader, makeConsoleFetch } from "../vendor/heyspex-mcp/console-fetch.mjs";
 import { resolveConsoleUrl } from "./lib/console-url-resolver.mjs";
@@ -647,7 +648,7 @@ export function main(argv = process.argv.slice(2)) {
 }
 
 const invokedDirectly =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+  isMainModule(import.meta.url);
 if (invokedDirectly) {
   main();
 }

package/spexharness/src/gates/vault-mirror-catchup.mjs

@@ -5,18 +5,30 @@
 // first tool call"). In cloud write mode the console is the system of record and the disk clone is a
 // mirror; this gate starts `hs pull --apply` in the BACKGROUND so the hook returns immediately.
 //
-// Fail-open and silent on every skip: local reliance, no vault root / no heyspex.yaml, kill switch
+// Fail-open on every skip: local reliance, no resolvable vault, kill switch
 // HEYSPEX_VAULT_MIRROR_CATCHUP_OFF=1, or a catch-up that already ran in the last 10 minutes (stamp file).
-// Never denies. Emits one line of additionalContext when it spawns.
+// Never denies. Emits one line of additionalContext when it spawns (or when a satellite's vault is skipped).
 //
-// ctx (all optional, for tests): env, vaultRoot, writeMode, now, exists(p), statMtimeMs(p), mkdirp(p),
-// writeFile(p, s), openLog(p) -> fd, spawnDetached(cmd, args, opts), hsCommand() -> { command, args, shell }.
+// TARGET (mlc-app incident, 2026-10-16): the pull target is the VAULT bound to the launch folder, resolved
+// by the shared resolver (vendor/heyspex-mcp/vault-resolve.mjs) - never the hook's cwd / project dir. In a
+// satellite (heyspex.yaml `vault_path`) or a repo-binding code repo that is the bound vault's checkout; a
+// satellite whose vault is not cloned here is SKIPPED with a log line, and a target that is not a vault
+// checkout is refused (`hs pull` refuses too - the hard guard lives in its write path).
+//
+// LOG: the gate writes `<iso> vault-mirror-catchup: target=<root> start: <cmd>` before spawning; the
+// detached runner (./vault-mirror-catchup.runner.mjs) sends the pull's stdout/stderr into the same log and
+// appends `<iso> vault-mirror-catchup: done exit=<code>`. Skips that name a target are logged too.
+//
+// ctx (all optional, for tests): env, vaultRoot, resolveVault() -> resolver result, isVault(p), writeMode,
+// now, exists(p), statMtimeMs(p), mkdirp(p), writeFile(p, s), appendFile(p, s), spawnDetached(cmd, args,
+// opts), hsCommand() -> { command, args, shell }, runnerPath.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
-import { defaultConfigRoot } from '../config-root.mjs';
+import { isVaultRoot, resolveActiveVault } from '../../../vendor/heyspex-mcp/vault-resolve.mjs';
 import { resolveDevMode } from '../../../scripts/lib/dev-mode.mjs';
 import { describeHsCommand } from '../../../scripts/lib/hs-command.mjs';
 
@@ -28,6 +40,7 @@ export const KILL_ENV = 'HEYSPEX_VAULT_MIRROR_CATCHUP_OFF';
 export const FRESH_WINDOW_MS = 10 * 60 * 1000;
 export const LOG_REL = '.heyspex/vault-mirror-catchup.log';
 export const STAMP_REL = '.heyspex/vault-mirror-catchup.stamp';
+export const RUNNER_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), 'vault-mirror-catchup.runner.mjs');
 
 /** Resolve how to launch `hs pull --apply`: the PATH shim (shell on Windows) or `node <dispatcher>`. */
 export function defaultHsLaunch() {
@@ -37,9 +50,43 @@ export function defaultHsLaunch() {
   return { command: 'hs', args: ['pull', '--apply'], shell: process.platform === 'win32' };
 }
 
+/** One log line: `<iso> vault-mirror-catchup: <text>`. */
+export function logLine(nowMs, text) {
+  return `${new Date(nowMs).toISOString()} vault-mirror-catchup: ${text}\n`;
+}
+
+/**
+ * Which vault does the catch-up pull into? The shared resolver's answer for the launch folder, never the
+ * folder itself. Returns { vaultRoot, boundRepoAbs } or { vaultRoot: null, reason, logDir?, detail? }.
+ */
+export function resolveCatchupTarget(deps = {}) {
+  if (deps.vaultRoot !== undefined) {
+    return deps.vaultRoot ? { vaultRoot: deps.vaultRoot, boundRepoAbs: null } : { vaultRoot: null, reason: 'no-vault-root' };
+  }
+  let r;
+  try {
+    r = (deps.resolveVault ?? (() => resolveActiveVault({ env: deps.env ?? process.env })))();
+  } catch {
+    return { vaultRoot: null, reason: 'no-vault-root' };
+  }
+  if (!r || r.source === 'unbound') return { vaultRoot: null, reason: 'no-vault-root' };
+  if (r.vaultCloned === false) {
+    // A satellite whose vault is not cloned at its vault_path: nothing local to mirror into, and the
+    // satellite itself must never grow a specs/ tree.
+    const where = r.boundRepoAbs ?? r.repoRootAbs;
+    return {
+      vaultRoot: null,
+      reason: 'vault-not-cloned',
+      logDir: where,
+      detail: `skipped: vault ${r.vaultId} is not cloned at ${r.vaultPath ?? 'its vault_path'} (relative to ${where}); nothing pulled`,
+    };
+  }
+  return { vaultRoot: r.repoRootAbs, boundRepoAbs: r.boundRepoAbs ?? null };
+}
+
 /**
- * Pure-ish decision: returns { spawn: false } or { spawn: true, vaultRoot, command, args, ... }.
- * All I/O goes through injected deps.
+ * Pure-ish decision: returns { spawn: false, reason, ... } or { spawn: true, vaultRoot, command, args, ... }.
+ * All I/O goes through injected deps. A skip that knows where to report carries `logPath` + `logText`.
  */
 export function decideCatchup(deps = {}) {
   const env = deps.env ?? process.env;
@@ -53,17 +100,25 @@ export function decideCatchup(deps = {}) {
     }
   }
   if (writeMode !== 'cloud') return { spawn: false, reason: 'local-reliance' };
-  let vaultRoot = deps.vaultRoot;
-  if (vaultRoot === undefined) {
-    try {
-      vaultRoot = defaultConfigRoot();
-    } catch {
-      vaultRoot = null;
-    }
+  const target = resolveCatchupTarget({ ...deps, env });
+  const vaultRoot = target.vaultRoot;
+  if (!vaultRoot) {
+    const out = { spawn: false, reason: target.reason };
+    if (target.logDir) Object.assign(out, { logPath: path.join(target.logDir, LOG_REL), logText: target.detail });
+    return out;
   }
-  if (!vaultRoot) return { spawn: false, reason: 'no-vault-root' };
   const exists = deps.exists ?? fs.existsSync;
   if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { spawn: false, reason: 'no-heyspex-yaml' };
+  // Belt and braces: whatever named it, the target must be a vault checkout - never a satellite or a
+  // repo-binding code repo (either would grow an untracked specs/ tree).
+  if (!(deps.isVault ?? isVaultRoot)(vaultRoot)) {
+    return {
+      spawn: false,
+      reason: 'target-not-vault',
+      logPath: path.join(vaultRoot, LOG_REL),
+      logText: `skipped: target=${vaultRoot} is not a vault checkout (satellite or repo-binding marker); nothing pulled`,
+    };
+  }
 
   const now = (deps.now ?? Date.now)();
   const stampPath = path.join(vaultRoot, STAMP_REL);
@@ -78,26 +133,50 @@ export function decideCatchup(deps = {}) {
     return { spawn: false, reason: 'stamp-fresh' };
   }
   const launch = (deps.hsCommand ?? defaultHsLaunch)();
-  return { spawn: true, vaultRoot, stampPath, logPath: path.join(vaultRoot, LOG_REL), ...launch };
+  return {
+    spawn: true,
+    vaultRoot,
+    boundRepoAbs: target.boundRepoAbs ?? null,
+    stampPath,
+    logPath: path.join(vaultRoot, LOG_REL),
+    ...launch,
+  };
 }
 
-/** Perform the detached spawn for a { spawn: true } decision. Throws on failure (caller fails open). */
+/** Append a skip line to the log a skip decision names - only when that `.heyspex/` already exists. */
+export function logSkip(d, deps = {}) {
+  if (!d?.logPath || !d.logText) return false;
+  const exists = deps.exists ?? fs.existsSync;
+  if (!exists(path.dirname(d.logPath))) return false; // never create .heyspex/ in someone's code repo
+  const appendFile = deps.appendFile ?? ((p, s) => fs.appendFileSync(p, s));
+  appendFile(d.logPath, logLine((deps.now ?? Date.now)(), d.logText));
+  return true;
+}
+
+/**
+ * Perform the detached spawn for a { spawn: true } decision. Throws on failure (caller fails open).
+ * Writes the start line (timestamp + target + command) BEFORE spawning; the runner appends the pull's
+ * output and the exit line.
+ */
 export function startCatchup(d, deps = {}) {
   const mkdirp = deps.mkdirp ?? ((p) => fs.mkdirSync(p, { recursive: true }));
   const writeFile = deps.writeFile ?? ((p, s) => fs.writeFileSync(p, s));
-  const openLog = deps.openLog ?? ((p) => fs.openSync(p, 'a'));
+  const appendFile = deps.appendFile ?? ((p, s) => fs.appendFileSync(p, s));
   const spawnDetached = deps.spawnDetached ?? ((cmd, args, opts) => spawn(cmd, args, opts));
   const env = deps.env ?? process.env;
+  const now = (deps.now ?? Date.now)();
   mkdirp(path.dirname(d.logPath));
-  writeFile(d.stampPath, new Date((deps.now ?? Date.now)()).toISOString() + '\n');
-  const fd = openLog(d.logPath);
-  const child = spawnDetached(d.command, d.args, {
+  writeFile(d.stampPath, new Date(now).toISOString() + '\n');
+  const bound = d.boundRepoAbs ? ` (bound from ${d.boundRepoAbs})` : '';
+  appendFile(d.logPath, logLine(now, `target=${d.vaultRoot}${bound} start: ${[d.command, ...d.args].join(' ')}`));
+  const spec = JSON.stringify({ logPath: d.logPath, command: d.command, args: d.args, shell: d.shell === true, cwd: d.vaultRoot });
+  const child = spawnDetached(process.execPath, [deps.runnerPath ?? RUNNER_PATH, spec], {
     cwd: d.vaultRoot,
     env: { ...env, HS_VAULT_ROOT: d.vaultRoot },
     detached: true,
-    stdio: ['ignore', fd, fd],
+    stdio: 'ignore',
     windowsHide: true,
-    shell: d.shell === true,
+    shell: false,
   });
   child?.on?.('error', () => {});
   child?.unref?.();
@@ -107,7 +186,17 @@ export function startCatchup(d, deps = {}) {
 export function run(evt, ctx = {}) {
   try {
     const d = decideCatchup(ctx);
-    if (!d.spawn) return { decision: 'allow' };
+    if (!d.spawn) {
+      try {
+        logSkip(d, ctx);
+      } catch {
+        /* a log failure never becomes a hook failure */
+      }
+      if (d.reason === 'vault-not-cloned') {
+        return { decision: 'inject', inject: { additionalContext: `vault mirror catch-up ${d.logText}`, severity: 'info' } };
+      }
+      return { decision: 'allow' };
+    }
     startCatchup(d, ctx);
     return {
       decision: 'inject',

package/spexharness/src/gates/vault-mirror-catchup.runner.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// spexharness/src/gates/vault-mirror-catchup.runner.mjs
+//
+// The detached middleman the vault-mirror-catchup gate spawns: it runs `hs pull --apply` with its
+// stdout/stderr going straight into the catch-up log, then appends ONE closing line with the exit code.
+// The gate has already written the start line (timestamp + resolved target), so the log always shows
+// where the pull went and how it ended - even when the pull itself prints nothing (the mlc-app incident
+// left an empty log and no way to tell what had run).
+//
+// argv[2]: JSON { logPath, command, args, shell, cwd }. The environment is inherited from the gate.
+
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+
+function append(logPath, line) {
+  try {
+    fs.appendFileSync(logPath, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    /* nowhere left to report to */
+  }
+}
+
+let spec;
+try {
+  spec = JSON.parse(process.argv[2] ?? '');
+} catch {
+  process.exit(2);
+}
+const { logPath, command, args = [], shell = false, cwd } = spec ?? {};
+if (!logPath || !command) process.exit(2);
+
+let fd;
+try {
+  fd = fs.openSync(logPath, 'a');
+} catch {
+  fd = 'ignore';
+}
+let child;
+try {
+  child = spawn(command, args, { cwd, env: process.env, stdio: ['ignore', fd, fd], windowsHide: true, shell: shell === true });
+} catch (err) {
+  append(logPath, `vault-mirror-catchup: spawn failed: ${err?.message ?? err}`);
+  process.exit(1);
+}
+child.on('error', (err) => {
+  append(logPath, `vault-mirror-catchup: spawn failed: ${err?.message ?? err}`);
+  process.exitCode = 1;
+});
+child.on('close', (code, signal) => {
+  append(logPath, `vault-mirror-catchup: done exit=${code ?? 'null'}${signal ? ` signal=${signal}` : ''}`);
+  process.exitCode = typeof code === 'number' ? code : 1;
+});