heyspex 0.2.2 → 0.2.4

package/.claude-plugin/marketplace.json

@@ -8,7 +8,8 @@
     {
       "name": "heyspex",
       "source": "./plugins/heyspex",
-      "description": "SpexCode plugin (for Claude Code and GitHub Copilot CLI): HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+      "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."
     }
   ]
 }

package/README.md

@@ -4,6 +4,17 @@
 
 HeySpex sits between "I have an idea" and "an AI agent writes code" - it distills ideas into context-window-sized plans that agents build correctly the first time. This page is the team-member onboarding walk-through: it takes you from an empty computer to your first claimed spec, and links the authoritative doc for every step instead of duplicating it.
 
+## Using the published package with GitHub Copilot
+
+```bash
+npm install heyspex
+npx heyspex setup copilot          # registers the plugin with the Copilot CLI
+npx heyspex setup copilot --check  # confirm; exit 0 = installed
+npx heyspex setup copilot --statusline  # optional: HeySpex status line in Copilot's settings.json (--uninstall to remove)
+```
+
+Prerequisite: the GitHub Copilot CLI. Either install the GitHub Copilot app (its bundled CLI at `%LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe` is auto-detected, newest version wins), or `npm install -g @github/copilot`, or `winget install GitHub.Copilot`. If none is found, `setup copilot` installs nothing and exits non-zero. `COPILOT_HOME` is honoured. Full guide: [docs/copilot-plugin-install.md](docs/copilot-plugin-install.md).
+
 ## Machine setup
 
 Prerequisites: Node.js `>=20 <25` (tested on 22.x), npm 10.x, git. No local database - HeySpex uses a cloud Postgres (Neon). Only if you will work on the Windows Companion tray app: the [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) and [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows) (`pwsh`).

package/bin/hs-vault-binding.mjs

@@ -0,0 +1,157 @@
+/**
+ * `hs vault bind | bindings | resolve` — the repo-binding verbs ([[HS-TYJA]]).
+ *
+ *   hs vault bind [--vault <name|id|path>] [--repo <dir>] [--force] [--dry-run] [--json]
+ *       Bind a code repo (default: the git checkout containing cwd) to a
+ *       registered vault: writes the repo's heyspex.yaml `vault:` block and the
+ *       registry `linked_repos[]` row. Idempotent; refuses to re-point a bound
+ *       repo without --force (prints the current binding); refuses a vault
+ *       checkout (it already resolves to itself). Without --vault it re-asserts
+ *       the repo's existing binding (refreshes path, remote and registry row).
+ *   hs vault bindings [--json]
+ *       Every binding on this machine, health-checked, sorted by repo path,
+ *       plus how the CURRENT folder resolves. Read-only.
+ *   hs vault resolve [--json]
+ *       Which vault an agent launched here writes to, and why. Read-only;
+ *       exits 1 with the typed error when unbound.
+ *
+ * Exit codes: 0 ok · 1 typed resolution/binding error · 2 usage error.
+ * `--json` prints exactly one JSON object on stdout (errors included:
+ * `{ ok: false, error: <CODE>, code: <CODE>, message, from, fix, details }`).
+ *
+ * One implementation: the logic lives in vendor/heyspex-mcp/vault-binding.mjs
+ * (shared with the MCP server and spexcode); this file is argv + printing.
+ */
+import {
+  bindRepo,
+  defaultRegistryDir,
+  isVaultResolutionError,
+  listBindings,
+} from '../vendor/heyspex-mcp/vault-binding.mjs';
+import { resolveActiveVault } from '../vendor/heyspex-mcp/vault-resolve.mjs';
+
+export const BINDING_VERBS = new Set(['bind', 'bindings', 'resolve']);
+
+function parseFlags(args) {
+  const out = { force: false, dryRun: false, json: false, repo: null, unknown: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--force') out.force = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--repo') out.repo = args[++i] ?? null;
+    else if (a.startsWith('--repo=')) out.repo = a.slice('--repo='.length);
+    else out.unknown.push(a);
+  }
+  return out;
+}
+
+/**
+ * How the folder `cwd` resolves, as a plain JSON-safe object. STABLE shape
+ * (`hs vault resolve --json`; scripts match on it):
+ *   ok:     { ok: true,  cwd, source, vault_id, vault_root, bound_repo?, worktree_of? }
+ *   failed: { ok: false, cwd, source: 'unbound', error, code, message, from, fix, details }
+ * (`error` and `code` are the same typed code; `error` is kept for older readers.)
+ */
+export function describeResolution(cwd, { env = process.env, registryDir } = {}) {
+  const r = resolveActiveVault({ cwd, env, ...(registryDir ? { registryDir } : {}) });
+  const slash = (p) => String(p).replace(/\\/g, '/');
+  if (r.source === 'unbound') {
+    const e = r.error && typeof r.error.toJSON === 'function'
+      ? r.error.toJSON()
+      : { ok: false, error: 'VAULT_UNBOUND', code: 'VAULT_UNBOUND', message: null, from: slash(cwd), fix: null, details: {} };
+    return { ok: false, cwd: slash(cwd), source: 'unbound', error: e.error, code: e.code, message: e.message, from: e.from ?? slash(cwd), fix: e.fix, details: e.details ?? {} };
+  }
+  return {
+    ok: true,
+    cwd: slash(cwd),
+    source: r.source,
+    vault_id: r.vaultId,
+    vault_root: slash(r.repoRootAbs),
+    ...(r.boundRepoAbs ? { bound_repo: slash(r.boundRepoAbs) } : {}),
+    ...(r.worktreeOf ? { worktree_of: slash(r.worktreeOf) } : {}),
+  };
+}
+
+const SOURCE_TEXT = {
+  'repo-binding': 'bound to this repo (heyspex.yaml kind: repo-binding)',
+  'satellite-pin': 'bound to this repo (satellite pin in .mcp.json)',
+  'cwd-marker': 'this folder is inside the vault checkout',
+  'marker-registry-mismatch': 'this folder is inside the vault checkout (marker id differs from the registry row - run `hs connect --check`)',
+  'cwd-heuristic': 'this folder is inside a vault checkout (specs/)',
+  'env-vault-root': 'HEYSPEX_VAULT_ROOT override',
+  'env-vault-dir': 'HEYSPEX_VAULT_DIR override',
+  explicit: 'explicit --vault',
+};
+
+/**
+ * @param {string} verb  bind | bindings | resolve
+ * @param {string[]} args argv after the verb (global --vault already extracted)
+ * @param {{ vaultSelector?: string|null, cwd?: string, env?: object, registryDir?: string, stdout?: { write(s: string): unknown }, stderr?: { write(s: string): unknown } }} [ctx]
+ * @returns {number} exit code
+ */
+export function runVaultBindingCommand(verb, args, {
+  vaultSelector = null,
+  cwd = process.cwd(),
+  env = process.env,
+  registryDir = defaultRegistryDir(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const flags = parseFlags(args);
+  const emitJson = (obj) => stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+  if (flags.unknown.length) {
+    const msg = `hs vault ${verb}: unknown argument(s): ${flags.unknown.join(' ')}`;
+    if (flags.json) emitJson({ ok: false, error: 'USAGE', message: msg });
+    else stderr.write(`${msg}\n`);
+    return 2;
+  }
+  try {
+    if (verb === 'bind') {
+      const res = bindRepo({ repo: flags.repo ?? undefined, cwd, vault: vaultSelector, force: flags.force, dryRun: flags.dryRun, registryDir });
+      if (flags.json) emitJson(res);
+      else {
+        const what = { bound: 'Bound', rebound: 'Re-bound', refreshed: 'Refreshed binding of', unchanged: 'Already bound:' }[res.status] ?? res.status;
+        stdout.write(`${res.dryRun ? '(dry run) ' : ''}${what} ${res.repo} -> vault ${res.vault.name} (${res.vault.id}) at ${res.vault.path}\n`);
+        if (res.previous) stdout.write(`  previously bound to ${res.previous.name ?? res.previous.id} (${res.previous.id})\n`);
+        if (res.movedFrom) stdout.write(`  replaced the stale registry row for ${res.movedFrom} (same git remote; the repo moved)\n`);
+        for (const f of res.wrote) stdout.write(`  wrote ${f}\n`);
+        if (res.status === 'bound' || res.status === 'rebound') stdout.write('  Restart agent sessions launched in this repo so their MCP server re-resolves.\n');
+      }
+      return 0;
+    }
+    if (verb === 'bindings') {
+      const list = listBindings({ registryDir });
+      const here = describeResolution(cwd, { env, registryDir });
+      if (flags.json) {
+        emitJson({ ok: true, here, ...list });
+        return 0;
+      }
+      stdout.write(here.ok
+        ? `This folder (${here.cwd}) -> vault ${here.vault_id} at ${here.vault_root} [${SOURCE_TEXT[here.source] ?? here.source}]\n`
+        : `This folder (${here.cwd}) -> UNBOUND (${here.error}). Fix: ${here.fix}\n`);
+      stdout.write(`\nRepo bindings (${list.bindings.length}):\n`);
+      if (!list.bindings.length) stdout.write('  (none - run `hs vault bind --vault <name|id>` inside a code repo)\n');
+      for (const b of list.bindings) {
+        stdout.write(`  ${b.status === 'ok' ? 'ok ' : '!! '} ${b.repo} -> ${b.vault_name ?? '?'} (${b.vault_id})${b.status === 'ok' ? '' : `  [${b.status}]`}\n`);
+      }
+      stdout.write(`\nRegistered vaults (${list.vaults.length}) - each resolves for agents launched inside its own checkout:\n`);
+      for (const v of list.vaults) stdout.write(`  ${v.name}  ${v.id}  ${v.path}\n`);
+      return 0;
+    }
+    if (verb === 'resolve') {
+      const here = describeResolution(cwd, { env, registryDir });
+      if (flags.json) emitJson(here);
+      else if (here.ok) stdout.write(`${here.vault_root}  (${here.vault_id}; ${SOURCE_TEXT[here.source] ?? here.source})\n`);
+      else stderr.write(`${here.code}: ${here.message}\n  fix: ${here.fix ?? '(see above)'}\n`);
+      return here.ok ? 0 : 1;
+    }
+  } catch (err) {
+    if (!isVaultResolutionError(err)) throw err;
+    if (flags.json) emitJson(err.toJSON());
+    else stderr.write(`hs vault ${verb}: ${err.code}: ${err.message}\n${err.fix ? `  fix: ${err.fix}\n` : ''}`);
+    return 1;
+  }
+  stderr.write(`hs vault: unknown verb ${verb}\n`);
+  return 2;
+}

package/bin/hs.mjs

@@ -11,6 +11,7 @@
  * service directly. tsx (a workspace devDep, hoisted to the repo-root
  * node_modules) executes the .ts entrypoints.
  */
+import { BINDING_VERBS, runVaultBindingCommand } from "./hs-vault-binding.mjs";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
@@ -316,21 +317,11 @@ export function findVaultRoot(start, stopAt) {
 }
 
 /**
- * Registry fallback for when the specs/ walk-up finds nothing — since the
- * repo split (2026-08-31) the vault lives outside the code repo, so `hs`
- * run from the code repo would otherwise exit "no vault detected".
- * Delegates to the shared resolver (same one the MCP server trusts) but
- * only accepts a result that names a real vault: the resolver's last-resort
- * cwd fallback is rejected so the "no vault detected" error below still
- * fires when there is genuinely no vault anywhere.
- *
- * The test is deliberately "anything but `cwd-heuristic`", so every real
- * tier passes it: `explicit`, `account-pointer`, `env-vault-root`,
- * `env-vault-dir`, and `satellite-pin` (an on-disk manifest attachment found
- * by the resolver's tier-3 walk -- that tier reported the untrue
- * `env-vault-root` until 2026-09-18; both labels are accepted here, so the
- * rename changed nothing). `cwd-marker` and `marker-registry-mismatch` (a
- * heyspex.yaml `vault_id` named the vault, [[HS-VVNQ]]) pass too.
+ * The shared resolver's answer (vendor/heyspex-mcp/vault-resolve.mjs) as a
+ * vault root, or null when it names none. Despite the historical name it
+ * never reads a registry pointer any more ([[HS-TYJA]]): it returns explicit,
+ * env, satellite-pin, repo-binding and marker results; `unbound` and the
+ * bare `cwd-heuristic` label return null. Kept for existing importers.
  */
 export function findRegistryVaultRoot(options = {}) {
   let resolved;
@@ -339,7 +330,7 @@ export function findRegistryVaultRoot(options = {}) {
   } catch {
     return null;
   }
-  if (!resolved || resolved.source === "cwd-heuristic") return null;
+  if (!resolved || resolved.source === "cwd-heuristic" || resolved.source === "unbound") return null;
   if (!existsSync(resolved.specsDirAbs)) return null;
   return resolved.repoRootAbs;
 }
@@ -412,56 +403,69 @@ export function pointerOnlyRefusalLine(cwd, vaultRoot) {
 
 /**
  * The vault-resolution ladder `main()` runs at the top of every invocation,
- * factored out so it is unit-testable without spawning a child process
- * ([[HS-0I1G-B0IT-TASK-track-and-announce-the-registry-active]]).
+ * factored out so it is unit-testable without spawning a child process.
  *
- * Reports `usedRegistryFallback: true` only when NONE of `HS_VAULT_ROOT`, an
- * explicit `--target`-equivalent, or a marker/satellite pin found walking up
- * from `cwd` answered, and `findRegistryVaultRoot()` (the machine's
- * last-active vault, `~/.heyspex/registry.json`) is what resolved the root.
- * `hs install` uses that flag to warn (always) and — when `--register-vault`
- * is given without `--dry-run` — refuse, so a customer onboarding an empty
- * directory doesn't silently write into whatever vault this machine last had
- * active in some other terminal/console tab.
+ * Owner ruling 2026-10-14 ([[HS-TYJA]]): one shared order, the same as the MCP
+ * server and spexcode -- `HS_VAULT_ROOT` (this CLI's explicit tier) ->
+ * `HEYSPEX_VAULT_ROOT` / `HEYSPEX_VAULT_DIR` (a true override) -> the walk up
+ * from `cwd` (satellite pin, heyspex.yaml `vault:` repo binding, vault
+ * checkout) -> nothing (`vaultRoot: null`). The registry's active pointer is
+ * never consulted, so `usedRegistryFallback` is always `false` now: the
+ * HS-0I1G "silently bootstrapping into the last-active vault" failure it
+ * guarded against can no longer happen. The field stays for callers.
  *
- * `stopAt` is a TEST-ONLY walk-boundary fence, threaded through to both
- * `findVaultRoot`'s own walk and `resolveActiveVault`'s inner cwd walk (via
- * its `cwdWalkRoot` option) — production callers (`main()`) omit it.
+ * `stopAt` is a TEST-ONLY walk-boundary fence (the resolver's `cwdWalkRoot`).
  *
  * @param {string} cwd
  * @param {NodeJS.ProcessEnv} env
  * @param {string} [stopAt]
- * @returns {{ vaultRoot: string|null, usedRegistryFallback: boolean }}
+ * @param {{ registryDir?: string }} [opts] test-only registry dir override
+ * @returns {{ vaultRoot: string|null, usedRegistryFallback: boolean, source: string|null, error: Error|null }}
+ *   `error`: the resolver's typed VaultResolutionError (VAULT_UNBOUND /
+ *   VAULT_BINDING_BROKEN / VAULT_NOT_FOUND) when `vaultRoot` is null.
  */
-export function resolveVaultRootForMain(cwd, env, stopAt) {
+export function resolveVaultRootForMain(cwd, env, stopAt, opts = {}) {
   if (env.HS_VAULT_ROOT) {
-    return { vaultRoot: env.HS_VAULT_ROOT, usedRegistryFallback: false };
+    return { vaultRoot: env.HS_VAULT_ROOT, usedRegistryFallback: false, source: "HS_VAULT_ROOT", error: null };
   }
-  // A pin that cannot be honoured is a REFUSAL, never a reason to fall
-  // through to the account-wide pointer (owner principle P1, 2026-10-16).
+  // A pin that cannot be honoured is a REFUSAL, never a reason to walk on
+  // past it to some other vault (owner principle P1, 2026-10-16).
   const brokenPin = findBrokenSatellitePin(cwd, stopAt);
   if (brokenPin) {
-    return { vaultRoot: null, usedRegistryFallback: false, brokenPin };
-  }
-  const walkedRoot = findVaultRoot(cwd, stopAt);
-  if (walkedRoot) {
-    return { vaultRoot: walkedRoot, usedRegistryFallback: false };
-  }
-  // Same ONE order as both resolvers ([[HS-VVNQ]], shared fixture
-  // spex-console/src/lib/vault-resolve/precedence-fixtures.json):
-  // `HS_VAULT_ROOT` (this CLI's explicit tier) → the walk above (satellite
-  // pin, then marker) → `HEYSPEX_VAULT_ROOT`/`HEYSPEX_VAULT_DIR` env → the
-  // registry pointer, the last two via the shared resolver. `cwd` is passed
-  // explicitly so the resolver's own walk starts where ours did — left to
-  // its default it would start from `CLAUDE_PROJECT_DIR`, and a marker found
-  // THERE (a different folder) would be mislabelled a registry fallback.
-  const registryRoot = findRegistryVaultRoot(
-    stopAt ? { cwd, cwdWalkRoot: stopAt } : { cwd },
+    return { vaultRoot: null, usedRegistryFallback: false, source: null, error: null, brokenPin };
+  }
+  let resolved;
+  try {
+    resolved = resolveActiveVault({
+      cwd,
+      env,
+      ...(stopAt ? { cwdWalkRoot: stopAt } : {}),
+      ...(opts.registryDir ? { registryDir: opts.registryDir } : {}),
+    });
+  } catch {
+    resolved = null;
+  }
+  if (!resolved || resolved.source === "unbound") {
+    return { vaultRoot: null, usedRegistryFallback: false, source: resolved?.source ?? null, error: resolved?.error ?? null };
+  }
+  return { vaultRoot: resolved.repoRootAbs, usedRegistryFallback: false, source: resolved.source, error: null };
+}
+
+/**
+ * The stderr text `hs` prints when a command needs a vault and none resolves:
+ * the resolver's typed code, message and exact fix ([[HS-TYJA]]), or the
+ * generic line when there is no typed error.
+ * @param {{ code?: string, message?: string, fix?: string|null } | null | undefined} error
+ */
+export function noVaultMessage(error) {
+  if (error && typeof error.code === "string" && error.message) {
+    return `hs: ${error.code}: ${error.message}\n${error.fix ? `  fix: ${error.fix}\n` : ""}`;
+  }
+  return (
+    "hs: no vault detected — could not find a heyspex.yaml marker or a " +
+    "specs/ folder walking up from the current directory. " +
+    "Set HS_VAULT_ROOT or run from inside a vault.\n"
   );
-  return {
-    vaultRoot: registryRoot,
-    usedRegistryFallback: Boolean(registryRoot),
-  };
 }
 
 /** True when `argv` carries `--attach-vault` (bare or `=value` form). */
@@ -559,6 +563,9 @@ function usage() {
       "  hs join <code>                         Join with a pairing code (LAN auto-find; no IP to type)",
       "  hs join [<repo>] [--dir d] [--code c] [--at url] [--profile p] [--skip steps] [--json] [--yes]  Fresh-machine onboarding (clone → toolchain → deps → doctor → agent layer → secrets → verify)",
       "  hs vault list|register|switch|active         Manage registered vaults + active pointer",
+      "  hs vault bind [--vault <name|id>] [--repo <dir>] [--force] [--dry-run] [--json]  Bind this repo to a vault (agents launched here write to it)",
+      "  hs vault bindings [--json]                   List repo bindings + how this folder resolves",
+      "  hs vault resolve [--json]                    Which vault an agent launched here writes to",
       "  hs workspace list|create|switch              Manage registered workspaces (company containers)",
       "  hs connect [--dry-run] [--json] | --check [--json]  Detect+scaffold+register this repo (or read-only check)",
       "  hs --vault <id> <subcommand>                 One-shot vault override for this invocation",
@@ -945,19 +952,15 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
-  const resolvedMain = resolveVaultRootForMain(process.cwd(), process.env);
-  const { usedRegistryFallback, brokenPin } = resolvedMain;
-  // P1: the pointer is not a binding. A verb that acts on a vault runs with
-  // NO vault (and is refused at the gate) rather than on whatever vault the
-  // console last selected; onboarding/registry verbs keep the old fallback.
-  const pointerOnly =
-    usedRegistryFallback &&
-    !pointerVaultAllowed(process.env) &&
-    !pointerFallbackAllowedFor(namespace, command);
-  const vaultRoot = pointerOnly ? null : resolvedMain.vaultRoot;
-  if (pointerOnly) {
-    process.stderr.write(pointerOnlyRefusalLine(process.cwd(), resolvedMain.vaultRoot));
-  }
+  const {
+    vaultRoot,
+    usedRegistryFallback,
+    error: vaultError,
+    brokenPin,
+  } = resolveVaultRootForMain(process.cwd(), process.env);
+  // The registry pointer is never consulted ([[HS-TYJA]]), so the only P1
+  // refusal left is a satellite pin that cannot be honoured; onboarding /
+  // registry verbs and `hs doctor` still run so the pin can be repaired.
   if (
     brokenPin &&
     namespace !== "doctor" &&
@@ -1050,11 +1053,7 @@ function main(argv) {
   // (optional name defaults to "peer"). Needs a vault (this machine owns it).
   if (namespace === "invite") {
     if (!vaultRoot) {
-      process.stderr.write(
-        "hs: no vault detected — could not find a heyspex.yaml marker or a " +
-          "specs/ folder walking up from the current directory. " +
-          "Set HS_VAULT_ROOT or run from inside a vault.\n",
-      );
+      process.stderr.write(noVaultMessage(vaultError));
       process.exit(1);
     }
     dispatchSpexConsoleEntry(
@@ -1078,7 +1077,7 @@ function main(argv) {
         `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]   GitHub Copilot (plugin; --hooks for the cloud agent)\n",
+          "  hs setup copilot [--check|--uninstall|--print|--hooks|--statusline [--force]]   GitHub Copilot (plugin; --hooks for the cloud agent; --statusline opt-in status line)\n",
       );
       process.exit(2);
     }
@@ -1090,7 +1089,7 @@ function main(argv) {
       setupFlags.length = 0;
       for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
-        if (["--check", "--uninstall", "--print", "--hooks", "--json"].includes(a)) setupFlags.push(a);
+        if (["--check", "--uninstall", "--print", "--hooks", "--json", "--statusline", "--force"].includes(a)) setupFlags.push(a);
         else if (a === "--target" && rest[i + 1]) setupFlags.push(a, rest[++i]);
         else if (a.startsWith("--target=")) setupFlags.push(a);
       }
@@ -1173,6 +1172,15 @@ function main(argv) {
   // May run outside any vault (registering a fresh directory, or listing/
   // switching from anywhere), so it bypasses the hard vault gate below like
   // init/install/setup.
+  if (namespace === "vault" && BINDING_VERBS.has(command)) {
+    // `hs vault bind|bindings|resolve` - repo bindings ([[HS-TYJA]]). Plain
+    // .mjs over the shared resolver (no tsx), cwd = where the user typed it.
+    process.exitCode = runVaultBindingCommand(command, rest, {
+      vaultSelector: vaultIdOverride ?? null,
+      cwd: INVOKED_CWD,
+    });
+    return;
+  }
   if (namespace === "vault") {
     dispatchSpexConsoleEntry("hs-vault.ts", argv, vaultRoot || process.cwd(), {
       ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
@@ -1308,11 +1316,7 @@ function main(argv) {
   }
 
   if (!vaultRoot) {
-    process.stderr.write(
-      "hs: no vault detected — could not find a heyspex.yaml marker or a " +
-        "specs/ folder walking up from the current directory. " +
-        "Set HS_VAULT_ROOT or run from inside a vault.\n",
-    );
+    process.stderr.write(noVaultMessage(vaultError));
     process.exit(1);
   }
 

package/bin/spexcode.mjs

@@ -57,6 +57,81 @@ const SEATS_JSON_PATH = path.resolve(__dirname, "..", "dev-factory", "seats.json
  */
 export const SPEXCODE_BACKEND_KIND = "spexcode";
 
+/**
+ * Verbs SpexCode handles ITSELF, in-process, instead of forwarding to `hs chat` (HS-WF12,
+ * owner ruling 2026-10-14 "it all operates inside a single harness application"):
+ *   seat    run one harness-hosted seat process (spexharness/src/seats/run-seat.mjs) — what the
+ *           orchestrator launches for every api seat (`spexcode seat --role coo --brief …`)
+ *   go      the guided run wizard (spexharness/src/orchestrator/go.mjs): checks, presets, one confirm, then `run`
+ *   watch   the run as plain sentences: new seat events as they land through the narrative renderer
+ *           (spexharness/src/orchestrator/render/seat-narrative.mjs) + a one-line footer, until Ctrl+C
+ *   run | status | stop | plan   the deterministic orchestrator (spexharness/src/orchestrator/cli.mjs;
+ *           `node dev-factory/coo-dispatcher.mjs …` is its thin alias)
+ *   status and watch take --verbose (every tool step), --trace (the raw event lines, the pre-narrative
+ *   format) and --seat <id> (one seat; a seat id or a spec id like HS-MP6H). Harness verbs are routed
+ *   before the chat --seat guard below, so `status --seat` is a trail filter, never a seat launch check.
+ * Anything else is a chat session, forwarded unchanged to `hs chat` as before.
+ */
+export const HARNESS_VERBS = Object.freeze({
+  seat: "../spexharness/src/seats/run-seat.mjs",
+  run: "../spexharness/src/orchestrator/cli.mjs",
+  status: "../spexharness/src/orchestrator/cli.mjs",
+  stop: "../spexharness/src/orchestrator/cli.mjs",
+  plan: "../spexharness/src/orchestrator/cli.mjs",
+  rearm: "../spexharness/src/orchestrator/cli.mjs", // clear strike rows before a long run (spexcode rearm halted)
+  go: "../spexharness/src/orchestrator/go.mjs", // the guided wizard: checks, presets, confirm, then the same `run` path
+  watch: "../spexharness/src/orchestrator/go.mjs", // narrative tail of the audit file + footer, until Ctrl+C
+});
+
+/** The harness verb argv names, or null when argv is a chat session. */
+export function harnessVerb(argv) {
+  const first = argv[0];
+  return typeof first === "string" && Object.prototype.hasOwnProperty.call(HARNESS_VERBS, first) ? first : null;
+}
+
+/**
+ * Run a harness verb in-process. `importFn` is injectable so tests never load the real modules.
+ * @returns {Promise<number>} exit code
+ */
+export async function runHarnessVerb(argv, { importFn, stderr = process.stderr } = {}) {
+  const verb = harnessVerb(argv);
+  const injected = typeof importFn === "function";
+  if (!injected) importFn = (spec) => import(spec);
+  const rel = HARNESS_VERBS[verb];
+  // Pin the vault root BEFORE the orchestrator loads: the dispatcher resolves its vault at import time, and
+  // the owner should never have to set it by hand. Discovery (dev-factory/lib/vault-root.mjs resolveRunVaultRoot):
+  // HEYSPEX_VAULT_ROOT, else the vault bound to the repo spexcode was launched in (heyspex.yaml `vault:`,
+  // a satellite pin, or a vault checkout — the same shared resolver as `hs` and the MCP server). There is no
+  // "active" vault (owner ruling 2026-10-14, HS-TYJA): unbound is a typed VAULT_UNBOUND ERROR for a verb that
+  // spawns or plans (run/plan/rearm). status/stop/watch only warn (they read run state, not the vault).
+  if (!injected && verb !== "seat" && verb !== "go") { // go pins it itself and reports where it came from
+    let pinned;
+    try {
+      const { ensureVaultRootEnv } = await import("../spexharness/src/orchestrator/go.mjs");
+      pinned = await ensureVaultRootEnv(process.env);
+    } catch (err) {
+      pinned = { path: null, error: String(err && err.message ? err.message : err) };
+    }
+    if (!pinned.path) {
+      const docsOnly = argv.some((a) => a === "--help" || a === "-h" || a === "--self-test");
+      stderr.write(`spexcode ${verb}: ${pinned.error}\n`);
+      if (["run", "plan", "rearm"].includes(verb) && !docsOnly) return 1;
+    }
+  }
+  let mod;
+  try {
+    mod = await importFn(rel);
+  } catch (err) {
+    stderr.write(`spexcode ${verb}: could not load ${rel}: ${err && err.message ? err.message : err}
+`);
+    return 1;
+  }
+  if (verb === "seat") return mod.runSeatCli(argv.slice(1));
+  if (verb === "go") return mod.runGoCli(argv.slice(1));
+  if (verb === "watch") return mod.runWatchCli(argv.slice(1));
+  return mod.runOrchestratorCli(argv);
+}
+
 /** Every argument `spexcode` receives is forwarded unchanged to `hs chat`. */
 export function buildForwardArgs(argv) {
   return ["chat", ...argv];
@@ -189,6 +264,9 @@ export async function runSpexcode(argv, deps = {}) {
     stderr = process.stderr,
   } = deps;
 
+  // Harness verbs (seat / run / status / stop / plan) never go to chat — one application.
+  if (harnessVerb(argv)) return runHarnessVerb(argv, { importFn: deps.importFn, stderr });
+
   const seatId = parseSeatArg(argv);
   if (seatId !== null) {
     let registry;
@@ -212,8 +290,21 @@ export async function runSpexcode(argv, deps = {}) {
   return runForward(argv, { hsPath, spawnFn });
 }
 
+/** Help text only (HS-JH41): the orchestrator verbs and run flags, shown above the chat help for a bare `spexcode --help`. */
+const RUN_HELP_ADDENDUM = [
+  "SpexCode run (the overnight orchestrator): spexcode go | run | plan | status | watch | stop | rearm   (spexcode run --help for all flags)",
+  "  --windows            default: one visible viewer window per COO, owned and closed by the launcher",
+  "  --windows-minimized  the same window, minimized (Overnight)",
+  "  --headless           windows off (CI / scripted); the seat still runs as an attached, piped process",
+  "  --milestone-seats    default: one COO per milestone      --epic-seats  a seat for each epic (older shape)",
+  "  --verbose / --trace  more run output (every tool step / raw seat-event lines)",
+  "",
+  "",
+].join("\n");
+
 async function main() {
   const argv = process.argv.slice(2);
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) process.stdout.write(RUN_HELP_ADDENDUM);
   process.exitCode = await runSpexcode(argv);
 }
 

package/dev-factory/engine/worktree.mjs

@@ -34,6 +34,8 @@ import { spawnSync } from "node:child_process";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
+import { toRunnerRelativePath } from "../lib/runner-path.mjs";
+import { isNoTestFilesOutput } from "../lib/dispatch-guard.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -97,13 +99,24 @@ export function runTsc(ctx, worktree) {
   return { count: (out.match(/error TS\d+/g) || []).length, status: r.status, output: out.trim().slice(0, 1200), timedOut: r.error?.code === "ETIMEDOUT" };
 }
 
-/** Run a scoped vitest file in <worktree>/<spex>. Returns { pass, output, timedOut }. */
+/** The vitest filter for `testRel` as seen from vitest's cwd (<worktree>/<spex>). Callers pass
+ *  the test REPO-relative ("spex-console/src/x.test.ts", same convention as task.target) or
+ *  already spex-relative ("src/x.test.ts"); vitest only matches the latter from its cwd —
+ *  the repo-relative form printed "No test files found" and was misread as a red baseline
+ *  (HS-7BYJ, 2026-10-15). */
+export function vitestFilter(ctx, worktree, testRel) {
+  return toRunnerRelativePath(testRel, { cwdRel: ctx.spex, roots: [worktree, ctx.repo] });
+}
+
+/** Run a scoped vitest file in <worktree>/<spex>. Returns { pass, output, timedOut, cwd, filter }. */
 export function runVitest(ctx, worktree, testRel) {
-  const r = spawnSync(`npx --no-install vitest run ${testRel}`, {
-    cwd: join(worktree, ctx.spex), shell: true, encoding: "utf8", timeout: ctx.testTimeout,
+  const cwd = join(worktree, ctx.spex);
+  const filter = vitestFilter(ctx, worktree, testRel);
+  const r = spawnSync(`npx --no-install vitest run ${filter}`, {
+    cwd, shell: true, encoding: "utf8", timeout: ctx.testTimeout,
   });
   const out = ((r.stdout || "") + (r.stderr || ""));
-  return { pass: r.status === 0 && !r.error, output: out.trim().slice(-1200), timedOut: r.error?.code === "ETIMEDOUT" };
+  return { pass: r.status === 0 && !r.error, output: out.trim().slice(-1200), timedOut: r.error?.code === "ETIMEDOUT", cwd, filter };
 }
 
 // HS-AY5K: the deterministic gate used to run EVERY test file through scoped
@@ -191,7 +204,10 @@ export function runPlainSelfTestScript(ctx, worktree, testRel) {
  *  runGate and baselineTest both call through, so the routing rule lives in exactly
  *  one place. Order matters: node:test and the plain-self-test conventions are both
  *  narrow, cheap-to-check positives; vitest is the default fallback for everything else. */
-function runScopedTest(ctx, worktree, testRel) {
+function runScopedTest(ctx, worktree, testPath) {
+  // Root-relative for the node runners (cwd = worktree root); an absolute or backslashed
+  // path is re-rooted here, and runVitest re-relativizes it to its own spex cwd.
+  const testRel = toRunnerRelativePath(testPath, { cwdRel: "", roots: [worktree, ctx.repo] });
   const abs = join(worktree, testRel);
   if (isNodeTestFile(abs)) return runNodeTest(ctx, worktree, testRel);
   if (isPlainSelfTestScript(abs)) return runPlainSelfTestScript(ctx, worktree, testRel);
@@ -290,7 +306,8 @@ export function runLanguageGate(ctx, worktree, task, code, { buildCmd, testCmd,
 // relative against `worktree`; vitest resolves it spex-relative against
 // `worktree/ctx.spex`) — a NEW-FILE test could land under either once the builder
 // creates it.
-function testExistsAtBaseline(ctx, worktree, testRel) {
+function testExistsAtBaseline(ctx, worktree, testPath) {
+  const testRel = toRunnerRelativePath(testPath, { cwdRel: "", roots: [worktree, ctx.repo] });
   return existsSync(join(worktree, testRel)) || existsSync(join(worktree, ctx.spex, testRel));
 }
 
@@ -302,7 +319,19 @@ export function baselineTest(ctx, worktree, testRel) {
       output: `test file does not exist at baseline (${testRel}) — expected NEW-FILE condition, not a gate/environment fault`,
     };
   }
-  return runScopedTest(ctx, worktree, testRel);
+  const r = runScopedTest(ctx, worktree, testRel);
+  // The file EXISTS (checked above), so a runner that still reports "No test files found"
+  // is a path/filter mismatch between the caller and the runner's cwd — never a silent
+  // environment fault. Name the cwd and the filter so the fix is obvious (HS-7BYJ).
+  if (!r.pass && isNoTestFilesOutput(r.output)) {
+    return {
+      ...r,
+      runnerPathMismatch: true,
+      output: `runner found no test files although ${testRel} exists — runner cwd: ${r.cwd ?? worktree}, filter: ${r.filter ?? testRel}. `
+        + `The test path is not relative to the runner's cwd (or the runner's include globs exclude it); fix the path convention, not the code.\n${r.output}`,
+    };
+  }
+  return r;
 }
 
 // HS-L9BX: `setupWorktree` builds the gate's worktree from `git worktree add --detach

package/dev-factory/lib/epic-detect.mjs

@@ -26,7 +26,7 @@
  * exact -EPIC-suffix regression that motivated the module.
  */
 
-import { pathToFileURL } from "node:url";
+import { isMainModule } from "../../scripts/lib/shared-path-helpers.mjs";
 
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 
@@ -185,6 +185,6 @@ function runSelfTest() {
   return ok ? 0 : 1;
 }
 
-if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+if (isMainModule(import.meta.url)) {
   if (process.argv.includes("--self-test")) process.exit(runSelfTest());
 }