heyspex 0.2.4 → 0.2.6

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "heyspex",
       "source": "./plugins/heyspex",
       "displayName": "HeySpex",
-      "description": "HeySpex plugin for Claude Code and GitHub Copilot CLI: vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+      "description": "SpexCode plugin (for Claude Code), also installable in GitHub Copilot CLI: HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
     }
   ]
 }

package/bin/hs.mjs

@@ -12,6 +12,7 @@
  * node_modules) executes the .ts entrypoints.
  */
 import { BINDING_VERBS, runVaultBindingCommand } from "./hs-vault-binding.mjs";
+import { findProjectRoot } from "../scripts/lib/customer-kit.mjs";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
@@ -36,6 +37,73 @@ import {
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, "..");
 
+/**
+ * True when this `hs` runs from an installed `heyspex` npm package rather than
+ * a HeySpex source checkout. Same signal `hs doctor` already dispatches on:
+ * scripts/heyspex-doctor.mjs only exists in a source clone (never in `files`).
+ */
+const IS_INSTALLED_PACKAGE = !existsSync(path.join(PKG_ROOT, "scripts", "heyspex-doctor.mjs"));
+
+/**
+ * Help lines for verbs that only work inside a HeySpex source checkout (dev
+ * server, Dev-Factory, seat registry, Companion build, the SpexCrawl dev path).
+ * `hs --help` from an installed package drops them and says so once.
+ */
+const DEV_ONLY_HELP_PREFIXES = [
+  "  hs server ",
+  "  hs factory ",
+  "  hs seat ",
+  // Platform-operator verbs whose implementations are not in the npm package:
+  // test-customer minting (admin), the Neon fleet queue, SpexCode Doctrine
+  // synthesis over this checkout's spexharness/ tree.
+  "  hs admin ",
+  "  hs queue ",
+  "  hs doctrine ",
+  // Verbs listed in the source-checkout help whose implementation the npm
+  // package does not carry (see NOT_IN_PACKAGE_VERBS below for each reason).
+  // Invoking one from an installed package prints a clear "not available in
+  // the npm package" line instead of "install is incomplete".
+  "  hs agent ",
+  "  hs chat ",
+  "  hs code-watcher ",
+  "  hs harness ",
+  "  hs hooks ",
+  "  hs import ",
+  "  hs milestone ",
+  "  hs model ",
+  "  hs registry ",
+  "  hs skills ",
+  "  hs voice ",
+  "  hs check judge ",
+  "  hs bench ",
+  "  node dev-factory/",
+  "                                              search/scrape/crawl CLI",
+  "                                              not an `hs` verb",
+  "                                              Companion)",
+];
+
+function helpForThisInstall(lines) {
+  if (!IS_INSTALLED_PACKAGE) return lines;
+  const out = [];
+  for (const line of lines) {
+    if (DEV_ONLY_HELP_PREFIXES.some((p) => line.startsWith(p))) continue;
+    if (line.startsWith("  hs companion start|stop|status|build")) {
+      out.push("  hs companion start|stop|status            Desktop companion tray app (not in the npm package yet)");
+      continue;
+    }
+    out.push(line);
+  }
+  out.push(
+    "HeySpex developer-only verbs (hs server, hs factory, hs seat, hs admin, hs queue,",
+    "hs doctrine, hs companion build) need a HeySpex source checkout and are not",
+    "listed here. Neither are verbs whose implementation the npm package does not",
+    "carry (hs agent, hs chat, hs code-watcher, hs harness, hs hooks, hs import,",
+    "hs milestone, hs model, hs registry, hs skills, hs voice, hs check judge).",
+    "",
+  );
+  return out;
+}
+
 /**
  * Every script path `hs` spawns directly by filesystem path (as opposed to
  * `dispatchSpexConsoleEntry`'s own three-case tsx/bundle/missing resolution,
@@ -545,8 +613,23 @@ function extractGlobalVaultFlag(argv) {
 }
 
 function usage() {
-  process.stdout.write(
-    [
+  process.stdout.write(usageLines().join("\n"));
+}
+
+/**
+ * `hs <namespace> --help` for a namespace whose own handler has no help text
+ * (its first token must be a sub-verb): print this install's `hs --help`
+ * lines for that namespace and exit 0, instead of "unknown verb --help".
+ */
+const HELP_FROM_USAGE_NAMESPACES = new Set(["index", "mcp", "wip", "worktree", "skills"]);
+
+/** @param {string} namespace */
+export function namespaceHelpLines(namespace, lines = usageLines()) {
+  return lines.filter((l) => l.startsWith(`  hs ${namespace} `));
+}
+
+function usageLines() {
+  return helpForThisInstall([
       "hs — HeySpex vault CLI",
       "",
       "Usage:",
@@ -573,7 +656,7 @@ function usage() {
       "  hs gateway validate [slug] [--json]        Validate user-authored gateway skills (.heyspex/skills/user/)",
       "  hs mode on|off|status|toggle               Master switch: HeySpex layer on or off (restart Claude Code)",
       "  hs dev [mode:local|mode:cloud|mode:prod]   Dev/prod mode + local/cloud reliance (status when bare)",
-      "  hs setup claude|cursor|copilot [--check|--uninstall]  Install agent lifecycle hooks (copilot also: --print, --hooks)",
+      "  hs setup claude|cursor|copilot [--check|--uninstall]  Install agent lifecycle hooks (claude, copilot also: --print; copilot: --hooks)",
       "  hs skills sync|check                       Propagate skills to Cursor/Codex/Claude (cwd-safe)",
       "  hs skills add <module-path> --name <n> --trigger </slash> [--export <n>] [--description <t>]  Register a skill (extension seam)",
       "  hs skills remove <name>                    Remove a customer-registered skill",
@@ -674,8 +757,7 @@ function usage() {
       "`hs install --register-vault` without --dry-run in that case refuses instead of",
       "registering, asking for --target. --attach-vault (satellite mode) is exempt.",
       "",
-    ].join("\n"),
-  );
+    ]);
 }
 
 /**
@@ -689,8 +771,11 @@ function usage() {
  *   2. Published install of a BUNDLED verb — currently `hs-init.ts`,
  *      `hs-install.ts`, `hs-claim.ts`, `hs-check.ts`, `hs-env.ts`,
  *      `hs-connect.ts`, `hs-join.ts`, `hs-vault.ts`, `hs-workspace.ts`,
- *      `hs-defer.ts`, `hs-vault-pull.ts`, `hs-dev.ts`, `hs-index-rebuild.ts`,
- *      `hs-index-reconcile.ts` — see `scripts/build-cli-bundle.mjs`'s
+ *      `hs-defer.ts`, `hs-vault-pull.ts`, `hs-vault-push.ts`, `hs-dev.ts`,
+ *      `hs-index-rebuild.ts`, `hs-index-reconcile.ts`, `hs-handoff.ts`,
+ *      `hs-pin.ts`, `hs-events.ts`, `hs-export-events.ts`, `hs-prereq.ts`,
+ *      `hs-trash.ts`, `hs-trust.ts`, `hs-next-launch.ts`, `hs-revalidate.ts`,
+ *      `hs-test.ts`, `hs-spawn.ts` — see `scripts/build-cli-bundle.mjs`'s
  *      `ENTRIES` array and doc comment for the authoritative list and why
  *      each qualifies: neither the source nor tsx exists, but
  *      `dist/cli/<name>.mjs` does — run the plain-JS bundle directly with
@@ -778,6 +863,10 @@ function dispatchSpexConsoleEntry(entryFile, args, vaultRoot, extraEnv = {}) {
  * version.
  */
 function runStandaloneDoctor(args, vaultRoot) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(`Usage:\n${namespaceHelpLines("doctor").join("\n")}\n`);
+    process.exit(0);
+  }
   const jsonOut = args.includes("--json");
   let version = "0.0.0";
   try {
@@ -891,6 +980,45 @@ function runStandaloneDoctor(args, vaultRoot) {
   printStandaloneDoctorReport(report, jsonOut);
 }
 
+/** Usage for `hs setup`; printed by --help/-h (exit 0) and on a bad target (exit 2). */
+const SETUP_USAGE =
+  "Usage:\n" +
+  "  hs setup claude [--check|--uninstall|--print]   Claude Code lifecycle hooks (--print: setup steps; alias claude-code)\n" +
+  "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
+  "  hs setup copilot [--check|--uninstall|--print|--hooks|--statusline [--force]]   GitHub Copilot (plugin; --hooks for the cloud agent; --statusline opt-in status line)\n" +
+  "  hs setup <target> --help   This help (never installs anything)\n";
+
+/**
+ * `hs setup claude --print` (alias `claude-code`): the Claude Code steps for a
+ * repo that uses the heyspex npm package — the sibling of `hs setup copilot
+ * --print`. Text only; writes nothing. The one-source-of-hooks note is backed
+ * by the `yields-to-plugin` marker in the committed launcher
+ * (scripts/lib/customer-kit.mjs LAUNCHER_YIELD_MARKER).
+ */
+function claudeCodeSetupSteps() {
+  return [
+    "# Using HeySpex in Claude Code",
+    "",
+    "1. Open this repo in Claude Code (run `claude` from the repo root).",
+    "2. On first open Claude Code asks whether to use the project MCP server `heyspex`",
+    "   (declared in this repo's .mcp.json). Approve it. No .mcp.json yet? Run `npx hs install`.",
+    "   Not signed in on this machine? Run `npx hs login` first.",
+    "3. Check: ask Claude to run `heyspex_preflight`, or run `npx hs doctor`.",
+    "",
+    "Optional: the SpexCode plugin (for Claude Code), from the copy inside node_modules:",
+    "  claude plugin marketplace add ./node_modules/heyspex",
+    "  claude plugin install heyspex@heyspex-marketplace",
+    "  (or in a session: /plugin marketplace add ./node_modules/heyspex, then",
+    "   /plugin install heyspex@heyspex-marketplace)",
+    "",
+    "One source of hooks: the plugin and this repo's .claude/heyspex/run-hook.mjs yield to",
+    "each other. When the plugin is enabled on this machine the committed launcher exits",
+    "silently and the plugin runs every hook, so each hook fires once. Set",
+    "HEYSPEX_REPO_HOOKS=1 to keep the repo hooks as the source instead.",
+    "",
+  ].join("\n");
+}
+
 function printStandaloneDoctorReport(report, jsonOut) {
   if (jsonOut) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -913,14 +1041,86 @@ function printStandaloneDoctorReport(report, jsonOut) {
     if (check.human) process.stdout.write(`         ${check.human}\n`);
   }
   process.stdout.write(
-    "\nNote: the full `hs doctor` (git hooks, Cursor wiring, console secrets, and\n" +
-      "dozens of other source-checkout-only checks) only ships inside a clone of\n" +
-      "https://github.com/pwhermanson/workflow-protocol — this is the subset that\n" +
-      "applies to a published install.\n",
+    "\nNote: this is the setup check for a published install. The full platform\n" +
+      "doctor (git hooks, console secrets and other source-checkout checks) is for\n" +
+      "HeySpex developers only and is not part of the npm package.\n",
   );
   process.exit(report.ok ? 0 : 1);
 }
 
+/** The tray-host subcommands of `hs companion` (bare `hs companion` means start). */
+const COMPANION_HOST_COMMANDS = new Set(["start", "stop", "status", "build"]);
+
+/**
+ * The `hs companion` host subcommand to answer with "not distributed through
+ * the npm package yet", or null. Non-null only for start|stop|status|build (or
+ * a bare `hs companion`) when `pkgRoot` has no companion/ source -- an
+ * installed `heyspex` package. Pure apart from the injectable `exists`.
+ * @param {string | undefined} namespace
+ * @param {string | undefined} command
+ * @param {{ pkgRoot?: string, exists?: (p: string) => boolean }} [opts]
+ * @returns {string | null}
+ */
+export function companionHostWithoutSource(namespace, command, { pkgRoot = PKG_ROOT, exists = existsSync } = {}) {
+  if (namespace !== "companion") return null;
+  const sub = command === undefined ? "start" : command;
+  if (!COMPANION_HOST_COMMANDS.has(sub)) return null;
+  return exists(path.join(pkgRoot, "companion")) ? null : sub;
+}
+
+/**
+ * Verbs (`"<namespace>"` or `"<namespace> <sub>"`) a source checkout runs but
+ * the npm package deliberately does not carry, each with the reason a
+ * customer sees. `hs --help` from an installed package hides their lines
+ * (DEV_ONLY_HELP_PREFIXES); invoking one exits 1 with
+ * {@link notInPackageMessage} instead of dispatchSpexConsoleEntry's
+ * "install is incomplete". A verb that IS bundled (scripts/build-cli-bundle.mjs
+ * ENTRIES) never belongs here.
+ */
+export const NOT_IN_PACKAGE_VERBS = Object.freeze({
+  admin: "platform-operator test-customer minting.",
+  queue: "the SpexFleet build queue runs only on the HeySpex platform.",
+  seat: "SpexFleet seat registry, platform build system only.",
+  agent: "the vendored agent collections it imports from are not shipped.",
+  chat: "the SpexCode chat front needs the SpexCode engine, which is not in the npm package.",
+  "code-watcher": "it needs the HeySpex source tree and its TypeScript toolchain.",
+  harness: "SpexCode gate fixtures live in the SpexCode engine, which is not in the npm package.",
+  hooks: "the SpexCode extension seam is read by the SpexCode engine, which is not in the npm package.",
+  import: "it uses the SpexFleet model router, which is not in the npm package.",
+  milestone: "use the console or the heyspex_* MCP tools to read a milestone.",
+  model: "the SpexFleet seat routing table is not in the npm package.",
+  registry: "the launch registry is managed from the console.",
+  skills: "skill sync and the SpexCode skill registry need a HeySpex source checkout.",
+  voice: "voice profiles feed the SpexVoice Companion, which is not in the npm package yet.",
+  "check judge": "the decorrelated judge seat runs on the HeySpex platform.",
+  factory: "SpexFleet/dev-factory internals are platform-only.",
+  doctrine: "SpexCode Doctrine synthesis internals are platform-only.",
+  bench: "SpexCode bench internals are platform-only.",
+});
+
+/**
+ * The NOT_IN_PACKAGE_VERBS key this invocation hits from an installed
+ * package, or null. Pure apart from `installed`.
+ * @param {string | undefined} namespace
+ * @param {string | undefined} command
+ * @param {{ installed?: boolean }} [opts]
+ * @returns {string | null}
+ */
+export function notInPackageVerb(namespace, command, { installed = IS_INSTALLED_PACKAGE } = {}) {
+  if (!installed || !namespace) return null;
+  const two = command ? `${namespace} ${command}` : null;
+  if (two && Object.hasOwn(NOT_IN_PACKAGE_VERBS, two)) return two;
+  return Object.hasOwn(NOT_IN_PACKAGE_VERBS, namespace) ? namespace : null;
+}
+
+/** @param {string} key a NOT_IN_PACKAGE_VERBS key */
+export function notInPackageMessage(key) {
+  return (
+    `hs ${key}: not available in the npm package — ${NOT_IN_PACKAGE_VERBS[key]}\n` +
+    `    It runs only inside a HeySpex source checkout. \`hs --help\` lists every verb this install can run.\n`
+  );
+}
+
 function main(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     usage();
@@ -952,6 +1152,43 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
+  // A source-checkout-only verb from an installed package: say so before vault
+  // resolution can refuse with an unrelated binding error.
+  const missingVerb = notInPackageVerb(namespace, command);
+  if (missingVerb) {
+    process.stderr.write(notInPackageMessage(missingVerb));
+    process.exit(1);
+  }
+  if (
+    HELP_FROM_USAGE_NAMESPACES.has(namespace) &&
+    (command === "--help" || command === "-h")
+  ) {
+    const lines = namespaceHelpLines(namespace);
+    if (lines.length) {
+      process.stdout.write(`Usage:\n${lines.join("\n")}\n`);
+      process.exit(0);
+    }
+  }
+
+  // `hs companion start|stop|status|build` from an installed package: the tray
+  // app's source (companion/) is not in the tarball, so say THAT first -- before
+  // vault resolution can refuse with "not bound to a vault", which sends a
+  // customer to fix a binding that would not help.
+  const companionSub = companionHostWithoutSource(namespace, command);
+  if (companionSub) {
+    import("../scripts/lib/hs-companion-settings.mjs").then(
+      (m) => {
+        process.stderr.write(`${m.renderCompanionNotDistributed(companionSub)}\n`);
+        process.exit(1);
+      },
+      (err) => {
+        process.stderr.write(`hs companion: ${err.message}\n`);
+        process.exit(1);
+      },
+    );
+    return;
+  }
+
   const {
     vaultRoot,
     usedRegistryFallback,
@@ -1066,7 +1303,18 @@ function main(argv) {
 
   // `hs setup claude|cursor` — install agent lifecycle hooks into the vault root.
   if (namespace === "setup") {
-    const agent = command?.toLowerCase();
+    const agent = command?.toLowerCase() === "claude-code" ? "claude" : command?.toLowerCase();
+    // --help/-h anywhere (`hs setup --help`, `hs setup copilot --help`) prints usage and
+    // exits 0 BEFORE any installer is spawned: the installers ignore unknown flags, so a
+    // forwarded --help used to run the real install (Copilot: into ~/.copilot).
+    if ([command, ...rest].some((a) => a === "--help" || a === "-h")) {
+      process.stdout.write(SETUP_USAGE);
+      process.exit(0);
+    }
+    if (agent === "claude" && rest.includes("--print")) {
+      process.stdout.write(claudeCodeSetupSteps());
+      process.exit(0);
+    }
     const SPAWN_KEYS = {
       claude: "setup:claude",
       cursor: "setup:cursor",
@@ -1074,10 +1322,7 @@ function main(argv) {
     };
     if (!agent || !Object.hasOwn(SPAWN_KEYS, agent)) {
       process.stderr.write(
-        `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` +
-          "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
-          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
-          "  hs setup copilot [--check|--uninstall|--print|--hooks|--statusline [--force]]   GitHub Copilot (plugin; --hooks for the cloud agent; --statusline opt-in status line)\n",
+        `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` + SETUP_USAGE,
       );
       process.exit(2);
     }
@@ -1095,8 +1340,10 @@ function main(argv) {
       }
     }
     const script = spawnTargetPath(SPAWN_KEYS[agent]);
-    // Copilot sets up the repo you are standing in, never the (possibly sibling) vault root.
-    const target = agent === "copilot" ? process.cwd() : vaultRoot || process.cwd();
+    // Every agent sets up the PROJECT you are standing in (nearest .git /
+    // heyspex.yaml at or above cwd) -- never the (possibly sibling) vault
+    // root, and never this package's own folder under node_modules/.
+    const target = findProjectRoot(INVOKED_CWD);
     const child = spawn(process.execPath, [script, ...setupFlags], {
       cwd: target,
       stdio: "inherit",
@@ -1315,6 +1562,22 @@ function main(argv) {
     return;
   }
 
+  // `hs trust list` / `hs trust revoke [path]` — standalone management of the machine-local
+  // folder-trust store `hs chat`'s first-run prompt writes to
+  // ([[HS-25AJ-8CMW-TASK-folder-trust-revoke-through-the]], deferred from
+  // [[HS-ZBEB-8CMW-TASK-folder-trust-for-spexcode-first-run]], which shipped only `hs chat
+  // --revoke-trust`). Thin CLI verb — same shell shape as `chat`/`hooks`/`bench` below; the real
+  // logic lives in `spex-console/src/lib/cli/trust-cli.ts` over `folder-trust.ts`'s pure
+  // functions. Forwards the full argv; the entrypoint drops the leading `trust` token.
+  // Machine-local, never acts on a vault, so it runs ABOVE the hard vault gate
+  // (it is in POINTER_FALLBACK_NAMESPACES): since HS-TYJA (a2bbb0698) dropped the
+  // registry-pointer fallback, `hs trust revoke` from an unbound dir hit
+  // VAULT_UNBOUND here.
+  if (namespace === "trust") {
+    dispatchSpexConsoleEntry("hs-trust.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
   if (!vaultRoot) {
     process.stderr.write(noVaultMessage(vaultError));
     process.exit(1);
@@ -1936,18 +2199,6 @@ function main(argv) {
     return;
   }
 
-  // `hs trust list` / `hs trust revoke [path]` — standalone management of the machine-local
-  // folder-trust store `hs chat`'s first-run prompt writes to
-  // ([[HS-25AJ-8CMW-TASK-folder-trust-revoke-through-the]], deferred from
-  // [[HS-ZBEB-8CMW-TASK-folder-trust-for-spexcode-first-run]], which shipped only `hs chat
-  // --revoke-trust`). Thin CLI verb — same shell shape as `chat`/`hooks`/`bench` above; the real
-  // logic lives in `spex-console/src/lib/cli/trust-cli.ts` over `folder-trust.ts`'s pure
-  // functions. Forwards the full argv; the entrypoint drops the leading `trust` token.
-  if (namespace === "trust") {
-    dispatchSpexConsoleEntry("hs-trust.ts", argv, vaultRoot || process.cwd());
-    return;
-  }
-
   // `hs doctrine extract|learn|show` — SpexCode Doctrine corpus reader + synthesis
   // ([[HS-TWTC-8CMW-TASK-dr1-doctrine-corpus-reader-stream-every]],
   // [[HS-YMPY-8CMW-TASK-dr2-doctrine-synthesis-a-routed]] of epic

package/dev-factory/lib/dispatch-guard.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * dispatch-guard.mjs — pre-dispatch checks the controller runs BEFORE its first builder
+ * call, so a dispatch that can never pass its own gate is refused up front with the fix
+ * named (exit 3, gate_environment_fault) instead of burning iterations on it.
+ *
+ * Born 2026-08-26 (HS-VHQG): the frozen check ran a test file that did not exist, the
+ * single-target builder only writes its target, and the controller spent 3 iterations x
+ * (best-of-3 + self-repair) + 3 DeepSeek diagnoses before escalating "no progress:
+ * identical failure signature x3" — a harness fault reported as a model fault.
+ *
+ *   node dev-factory/lib/dispatch-guard.mjs --self-test
+ */
+
+/** Normalize a repo path for loose comparison (posix separators, no leading ./). */
+function normRel(p) {
+  return String(p ?? "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+/** True when the builder's --target set (comma-separated) can WRITE the scoped test file —
+ *  i.e. the test is itself a target. The builder only ever writes its targets. */
+export function buildCanCreateTest(targetArg, testArg) {
+  const test = normRel(testArg);
+  if (!test) return true; // no scoped test → nothing to guard
+  const targets = String(targetArg ?? "").split(",").map((s) => normRel(s.trim())).filter(Boolean);
+  return targets.some((t) => t === test || t.endsWith(`/${test}`) || test.endsWith(`/${t}`));
+}
+
+/** Plain-language abort reason for the pre-dispatch guard (rides the exit-3 path). */
+export function impossibleTestReason(targetArg, testArg) {
+  return `the scoped test does not exist yet and this build cannot create it — the frozen check runs ${testArg}, `
+    + `but this controller builds ONE target (--target ${targetArg}) and the builder only writes its target. `
+    + `No candidate can ever turn this gate green, so no builder was called and no iteration was spent. `
+    + `This task needs two files (the implementation + a new test), which is the routing table's "multi-file implementation" shape: `
+    + `route it to the multi-file seat (a harness sub-agent with an explicit cheap model — never the single-target fleet build), `
+    + `or split the spec so the test file lands as its own greenfield task first (--target ${testArg}) and this task's gate can then find it.`;
+}
+
+/** vitest's "No test files found" banner (it prints its include/exclude globs after it) —
+ *  a gate that found nothing to run, never a red test. */
+export function isNoTestFilesOutput(output) {
+  const s = String(output ?? "");
+  if (/No test files found/i.test(s)) return true;
+  // Older vitest prints only the include/exclude listing; treat it as no-test-files ONLY when
+  // nothing in the output looks like a test result.
+  // No \b here: vitest wraps the labels in dim ANSI codes ("[2minclude:") that glue to the word.
+  return /include:\s/.test(s) && /exclude:\s/.test(s)
+    && !/\b(passed|failed)\b.*\btests?\b/i.test(s) && !/✓|✗|×|FAIL\s+src/.test(s);
+}
+
+// ── self-test ────────────────────────────────────────────────────────────────────────
+function runSelfTest() {
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  console.log("== dispatch-guard.mjs self-test ==\n");
+  check("impl target + new test (HS-VHQG shape) → cannot create", !buildCanCreateTest("spex-console/src/lib/cli/init.ts", "spex-console/src/lib/cli/init.customer-vault.test.ts"));
+  check("test IS the target (greenfield test task) → can create", buildCanCreateTest("spex-console/src/w.test.ts", "spex-console/src/w.test.ts"));
+  check("comma target set containing the test → can create", buildCanCreateTest("a/x.ts,a/x.test.ts", "a/x.test.ts"));
+  check("runner-relative test vs repo-relative target still matches", buildCanCreateTest("spex-console/src/w.test.ts", "src/w.test.ts"));
+  check("backslash paths normalize", buildCanCreateTest("spex-console\\src\\w.test.ts", "spex-console/src/w.test.ts"));
+  check("no scoped test → nothing to guard", buildCanCreateTest("a.ts", ""));
+  const reason = impossibleTestReason("a.ts", "a.test.ts");
+  check("reason names both files, the multi-file seat, and the greenfield split", /a\.test\.ts/.test(reason) && /--target a\.ts/.test(reason) && /multi-file seat/.test(reason) && /greenfield/.test(reason));
+  check("vitest no-test-files banner → environmental", isNoTestFilesOutput("No test files found, exiting with code 1\ninclude: src/**/*.test.ts\nexclude: **/node_modules/**"));
+  check("include/exclude listing with no results → environmental", isNoTestFilesOutput("include: src/**/*.test.ts\nexclude:  **/node_modules/**"));
+  check("a real failing test run is NOT environmental", !isNoTestFilesOutput("FAIL  src/lib/x.test.ts > does thing\nTests  1 failed | 2 passed (3)\ninclude: src/**/*.test.ts exclude: **/node_modules/**"));
+  check("a passing run is NOT environmental", !isNoTestFilesOutput("✓ src/x.test.ts (3 tests)\nTests 3 passed (3)"));
+  check("empty output is NOT environmental", !isNoTestFilesOutput(""));
+  console.log(ok ? "\n✓ dispatch-guard self-test passed" : "\n✗ dispatch-guard self-test FAILED");
+  return ok ? 0 : 1;
+}
+
+if (process.argv.includes("--self-test") && process.argv[1] && /dispatch-guard\.mjs$/.test(process.argv[1].replace(/\\/g, "/"))) {
+  process.exit(runSelfTest());
+}

package/dev-factory/lib/runner-path.mjs

@@ -0,0 +1,51 @@
+/**
+ * runner-path.mjs — make a scoped test/target path relative to the cwd its runner
+ * actually executes in.
+ *
+ * Born 2026-10-15 (HS-7BYJ baseline): the controller's red-baseline pre-check ran scoped
+ * vitest from `<worktree>/spex-console` (where the vitest config lives) but handed it the
+ * REPO-relative test path `spex-console/src/lib/x.test.ts`. vitest's file filter then
+ * matched nothing ("No test files found, exiting with code 1") and the run was classified
+ * as gate_environment_fault before any builder ran. One helper, used at every call site
+ * that runs a tool from a package subdirectory, instead of patching one site.
+ */
+import { isAbsolute, relative } from "node:path";
+
+const toPosix = (p) => String(p ?? "").replace(/\\/g, "/");
+const stripDot = (p) => p.replace(/^(\.\/)+/, "");
+const caseFold = (p) => (process.platform === "win32" ? p.toLowerCase() : p);
+
+/** `child` is `base` or under it (posix strings, case-insensitive on Windows). */
+function isUnder(child, base) {
+  const c = caseFold(child), b = caseFold(base).replace(/\/+$/, "");
+  return c === b || c.startsWith(`${b}/`);
+}
+
+/**
+ * Convert `path` to a path relative to the runner's cwd.
+ *
+ * @param {string} path      repo-relative ("spex-console/src/x.test.ts"), already
+ *                           cwd-relative ("src/x.test.ts"), absolute, or backslashed.
+ * @param {object} [opts]
+ * @param {string} [opts.cwdRel=""]  the runner's cwd, relative to the repo/worktree root
+ *                           ("spex-console", "companion", "vendor/heyspex-mcp"; "" = root).
+ * @param {string[]} [opts.roots=[]] absolute roots an absolute `path` may live under (the
+ *                           gate worktree, the main repo) — it is re-rooted against the first
+ *                           match. An absolute path under none of them is returned posix-ified.
+ * @returns {string} posix path relative to `cwdRel`. A repo-relative path OUTSIDE `cwdRel`
+ *                   (e.g. vendor/… while the runner sits in spex-console) is returned
+ *                   unchanged — it is either already cwd-relative or not this runner's file.
+ */
+export function toRunnerRelativePath(path, { cwdRel = "", roots = [] } = {}) {
+  let p = stripDot(toPosix(path).trim());
+  if (!p) return p;
+  const cwd = stripDot(toPosix(cwdRel)).replace(/^\/+|\/+$/g, "");
+  if (isAbsolute(p) || /^[A-Za-z]:\//.test(p)) {
+    const root = roots.map((r) => toPosix(r).replace(/\/+$/, "")).find((r) => r && isUnder(p, r));
+    if (!root) return p;
+    p = p.slice(root.length).replace(/^\/+/, "");
+  }
+  if (!cwd) return p;
+  if (isUnder(p, cwd)) return toPosix(relative(cwd, p)) || ".";
+  return p;
+}