heyspex 0.2.1 → 0.2.3

package/spexharness/src/rule-table.mjs

@@ -172,7 +172,7 @@ export const BUILT_IN_RULES = Object.freeze(
       "configKey": "agent_behaviors.coo_delegation_guard.enabled",
       "ignoreInjectedContent": false,
       "patterns": [],
-      "inject": "DEV-FACTORY DELEGATION GUARD (dev-factory-delegation-routing) — as COO you do not do a\nphase's reasoning in your own context. Before the breakdown phase for the on-deck epic,\nthe guard checks the seat-audit record: if that phase has NOT been delegated to the seat\nthe routing table names for it, the exact delegation command is injected and you run it\nfirst. Delegation is table-driven — consult dev-factory/routing-table.json and route to\nthe calibrated seat model (build → free local fleet; breakdown/critic/synthesis →\nDeepSeek; cloud/Opus is escalation-only). \"Delegate-first\" NEVER means spawning a\nsubagent on the session's own tier. If you have already delegated this breakdown,\nproceed. The guard fails open: a missing or unreadable seat registry / audit record\nnever blocks session start or a claim.\n",
+      "inject": "DEV-FACTORY DELEGATION GUARD (dev-factory-delegation-routing) — as COO you do not do a\nphase's reasoning in your own context. Before the breakdown phase for the on-deck epic,\nthe guard checks the seat-audit record: if that phase has NOT been delegated to the seat\nthe routing table names for it, the exact delegation command is injected and you run it\nfirst. Delegation is table-driven — consult dev-factory/routing-table.json and route to\nthe calibrated seat model (build → cloud DeepSeek builder via controller.mjs, local\nfleet paused by owner ruling 2026-10-15; breakdown/critic/synthesis → DeepSeek;\ncloud/Opus is escalation-only). \"Delegate-first\" NEVER means spawning a\nsubagent on the session's own tier. If you have already delegated this breakdown,\nproceed. The guard fails open: a missing or unreadable seat registry / audit record\nnever blocks session start or a claim.\n",
       "naming": null
     },
     {

package/vendor/heyspex-mcp/cli-verbs.mjs

@@ -17,10 +17,14 @@ import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { DEFAULT_LOGIN_TIMEOUT_MS, buildConnectUrl, describeCallbackFailure, describeRedeemFailure, generateLoginState, openBrowser as openBrowserDefault, startCallbackListener as startCallbackListenerDefault } from './login-handoff.mjs';
 import { getConfig, getConsoleUrl } from './mcp-config.mjs';
 import { homedir, hostname } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { handleToolsCall, handleToolsList } from './tool-dispatch.mjs';
 import { writeBuildRecord } from '../../scripts/check-mcp-freshness.mjs';
+
+/** This server's own code directory (vendor/heyspex-mcp of the checkout it runs from). */
+const SERVER_CODE_DIR = dirname(fileURLToPath(import.meta.url));
 import { registerSpec } from './register-spec.mjs';
 import { validateLinkage } from './validate-linkage.mjs';
 import { execFileSync } from 'node:child_process';
@@ -1615,9 +1619,19 @@ stdio parent so tool schemas stay current without reconnecting Cursor).
  */
 export function stampMcpBuildRecord() {
   try {
-    const { vaultRoot: fingerprintVaultRoot } = getConfig();
+    const { vaultRoot: fingerprintVaultRoot, vaultSource } = getConfig();
+    // Unbound ([[HS-TYJA]]): vaultRoot is only the launch folder, not a
+    // vault - never create .heyspex/ there.
+    if (vaultSource === 'unbound') return;
+    // HS-C0NW: never mkdir a .heyspex/ into a folder that is not there (a host that passed an
+    // unexpanded `${CLAUDE_PROJECT_DIR}` used to leave a junk directory by that name).
+    if (!existsSync(fingerprintVaultRoot)) return;
     writeBuildRecord({
       vaultRoot: fingerprintVaultRoot,
+      // Fingerprint the code this process actually runs. Since the repo split
+      // the vault holds no vendor/ tree, so `<vaultRoot>/vendor/heyspex-mcp`
+      // fingerprinted nothing (null) for every bound repo.
+      vendorDir: SERVER_CODE_DIR,
       pid: process.pid,
       startedAt: new Date().toISOString(),
     });

package/vendor/heyspex-mcp/cli.mjs

@@ -52,6 +52,12 @@ import { filterToolSurface, handleLoadTools } from './tool-catalog.mjs';
 import { handlePromptsGet, handlePromptsList } from './prompts.mjs';
 import { SERVER_VERSION, handleInitialize, handleToolsCall, handleToolsList, resolveInjectableSeat, vaultRootGateVerdict } from './tool-dispatch.mjs';
 import { runCallCli, runExportCli, runLoginCli, runLogoutCli, runMcpInstallCli, runPairCli, runRegisterCli, runValidateCli, runWhoamiCli, stampMcpBuildRecord } from './cli-verbs.mjs';
+import { scrubUnusableDirEnv } from './usable-dir-env.mjs';
+
+// HS-C0NW: a host that does not expand `${CLAUDE_PROJECT_DIR}` in the MCP manifest hands us the
+// literal text. Treat such values as unset so every reader (resolver, console-fetch, subprocess
+// children that inherit this env) falls through to the cwd walk instead of mkdir-ing a junk path.
+scrubUnusableDirEnv(process.env, { requireExisting: { HEYSPEX_VAULT_ROOT: false } });
 
 // Dev-factory seat identity (epic HS-CXO0): surface each caller's seat on connect.
 // resolveCooModeEnabled is the SHARED readiness predicate — the SessionStart hook
@@ -191,7 +197,7 @@ function handleRequest(request) {
         const vaultRoot = config.vaultRoot;
         // Same mode-aware gate as tools/call: an absent clone only refuses on
         // the disk tier (see vaultRootGateVerdict in tool-dispatch.mjs).
-        const promptGate = vaultRootGateVerdict(vaultRoot);
+        const promptGate = vaultRootGateVerdict(vaultRoot, { vaultSource: config.vaultSource, vaultError: config.vaultError });
         if (promptGate) {
           sendError(id, -32003, promptGate.message);
           break;
@@ -302,8 +308,10 @@ const INFO_ONLY = SHOW_HELP || SHOW_VERSION;
 // SV2K: migrate legacy .heyspex/idea-focus.yaml → capture-focus.yaml on startup.
 if (!INFO_ONLY) {
   try {
-    const { vaultRoot: bootVaultRoot } = getConfig();
-    if (existsSync(bootVaultRoot)) {
+    const { vaultRoot: bootVaultRoot, vaultSource: bootSource } = getConfig();
+    // Unbound ([[HS-TYJA]]): vaultRoot is only the launch folder, not a vault -
+    // never migrate files there.
+    if (bootSource !== 'unbound' && existsSync(bootVaultRoot)) {
       migrateLegacyIdeaFocus(bootVaultRoot);
     }
   } catch (err) {
@@ -389,7 +397,15 @@ if (!RUNNING_AS_CLI && !INFO_ONLY && process.env.HEYSPEX_DISABLE_STDIO_BOOTSTRAP
     // unless HEYSPEX_ALLOW_POINTER_VAULT=1 — in which case say which vault
     // this process will act on, once, right here at start.
     announcePointerVaultOnce({ vaultId: bootVaultId, repoRootAbs: bootVaultRoot, source: bootVaultSource });
-    if (existsSync(bootVaultRoot)) {
+    if (bootVaultSource === 'unbound') {
+      // No vault for this launch folder ([[HS-TYJA]]). The server still boots
+      // (tools/list works); every vault-scoped call is refused per call with
+      // the typed code (console-fetch.mjs). Say why once, at start.
+      const bootErr = getConfig().vaultError;
+      process.stderr.write?.(
+        `[heyspex-mcp] ${bootErr?.code ?? 'VAULT_UNBOUND'}: no vault for ${bootVaultRoot}; vault tools will refuse until fixed. Fix: ${bootErr?.fix ?? 'hs vault bind --vault <name|id>'}\n`,
+      );
+    } else if (existsSync(bootVaultRoot)) {
       captureChannelWatcher = createCaptureChannelWatcher({
         vaultRoot: bootVaultRoot,
         getConsoleUrl,

package/vendor/heyspex-mcp/console-fetch.mjs

@@ -99,7 +99,7 @@ export { isVaultLessEndpoint, VAULT_LESS_ENDPOINTS };
 // ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
 import { hsCommand } from '../../scripts/lib/hs-command.mjs';
 import { maybeDrainOnFirstSuccess } from './write-outbox.mjs';
-import { getActiveConfig, registryAccountIdForRoot, UNREGISTERED_VAULT_ID } from './vault-resolve.mjs';
+import { getActiveConfig, isVaultResolutionError, registryAccountIdForRoot, UNREGISTERED_VAULT_ID } from './vault-resolve.mjs';
 
 export const DEFAULT_CONSOLE_TIMEOUT_MS = 30000;
 
@@ -524,12 +524,13 @@ export class AccountNotConfiguredError extends Error {
   }
 }
 
-/** True for the three local scope refusals this module throws. */
+/** True for the local scope refusals: this module's three, plus the resolver's VaultResolutionError (VAULT_UNBOUND / VAULT_BINDING_BROKEN). */
 export function isLocalScopeRefusal(err) {
   return (
     err instanceof VaultNotRegisteredError
     || err instanceof AccountNotConfiguredError
     || err instanceof VaultNotPinnedError
+    || isVaultResolutionError(err)
   );
 }
 
@@ -552,6 +553,12 @@ export function isLocalScopeRefusal(err) {
 export function vaultIdHeaderFor(resolved, opts = {}) {
   const vaultId = typeof resolved?.vaultId === 'string' ? resolved.vaultId.trim() : '';
   if (!vaultId) return {};
+  // Nothing names a vault for this repo ([[HS-TYJA]]: no default "active"
+  // vault exists): refuse with the resolver's typed VAULT_UNBOUND /
+  // VAULT_BINDING_BROKEN, whose message carries the `hs vault bind` fix.
+  if (resolved?.source === 'unbound' && isVaultResolutionError(resolved.error)) {
+    throw resolved.error;
+  }
   if (vaultId === UNREGISTERED_VAULT_ID) {
     throw new VaultNotRegisteredError(resolved?.repoRootAbs, resolved?.source);
   }
@@ -624,7 +631,7 @@ export function getAccountIdHeader({ repoAccountId, ...opts } = {}) {
  * `consoleFetch` already handles (`ok: false`, `status: 0`), with the code on
  * `refusal` AND on `authProblem` so `consoleErrorCode` / the never-buffer
  * contract pick it up with no per-caller change. Pure.
- * @param {VaultNotRegisteredError | AccountNotConfiguredError | VaultNotPinnedError | AccountTokenMissingError} err
+ * @param {VaultNotRegisteredError | AccountNotConfiguredError | VaultNotPinnedError | AccountTokenMissingError | import("./vault-binding.mjs").VaultResolutionError} err
  * @param {string} url the request that was NOT sent
  */
 export function scopeRefusalResult(err, url) {
@@ -638,6 +645,11 @@ export function scopeRefusalResult(err, url) {
     refusal: err.code,
     authProblem: err.code,
     authMessage: err.message,
+    // VaultResolutionError ([[HS-TYJA]]): the exact repair command and the
+    // folder resolution walked from, so the tool refusal names the same fix
+    // `hs vault resolve` prints.
+    ...(typeof err.fix === 'string' && err.fix ? { fix: err.fix } : {}),
+    ...(typeof err.from === 'string' && err.from ? { from: err.from } : {}),
   };
 }
 

package/vendor/heyspex-mcp/dev-tools.mjs

@@ -18,6 +18,10 @@ import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
 // elsewhere; same precedence plan-review.mjs's `resolveCodeAuditRoots` uses.
 const CHECKOUT_ROOT = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
 
+// Where the cloud admin dev-mode setting lives. Used when an older
+// scripts/lib/dev-mode.mjs does not export CLOUD_CONSOLE_URL itself.
+export const CLOUD_DEV_MODE_URL = 'https://app.heyspex.com';
+
 export async function handleDevServerStatus(vaultRoot) {
   try {
     const local = join(CHECKOUT_ROOT, 'scripts', 'dev-server-status.mjs');
@@ -93,10 +97,13 @@ export async function handleDevMode(vaultRoot, args = {}) {
       }
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
-    // get (default): two-pass — resolve without the cloud rung to learn which
-    // console to ask, then fold the fetched cloud setting into the resolution.
-    const pre = mod.resolveDevMode();
-    const cloud = await mod.fetchCloudDevMode({ consoleUrl: pre.consoleUrl });
+    // get (default): read the cloud admin setting from the CLOUD console —
+    // never the resolved console URL, which under a local override is
+    // localhost and can never answer for the cloud (staleAgainstCloud then
+    // silently read false) — and fold it into the resolution.
+    const cloud = await mod.fetchCloudDevMode({
+      consoleUrl: mod.CLOUD_CONSOLE_URL ?? CLOUD_DEV_MODE_URL,
+    });
     const resolved = mod.resolveDevMode({
       cloudSetting: cloud.ok ? cloud.setting : undefined,
     });

package/vendor/heyspex-mcp/events-tools.mjs

@@ -182,7 +182,7 @@ export async function handleExportEvents(args = {}) {
   let vault = null;
   try {
     vault = resolveActiveVault();
-    if (vault?.specsDirAbs) body.expected_vault_root = vault.specsDirAbs;
+    if (vault?.specsDirAbs && vault.source !== 'unbound') body.expected_vault_root = vault.specsDirAbs;
   } catch { /* best-effort — the export still runs unguarded when unresolvable */ }
   const result = await consoleFetch('/api/control/export-events', { method: 'POST', body });
   if (!result.ok) return controlError(result, 'EXPORT_EVENTS_FAILED');

package/vendor/heyspex-mcp/factory-run-status.mjs

@@ -0,0 +1,42 @@
+// heyspex_factory_run_status - the MCP face of the SpexCode run-state model (epic HS-P5NU, task HS-8AOE).
+//
+// The SAME snapshot `spexcode status --json` and GET /api/factory/run/status return: run id, lease,
+// heartbeat, current seat, queue positions, stopped reason and the recent audit trail from
+// dev-factory/state/seat-events.jsonl. The reader (dev-factory/lib/run-state-model.mjs) is a code-repo
+// artifact, so it is imported lazily from the checkout (dev-factory-bridge pattern) - a missing
+// dev-factory degrades to a typed error, never a crash of the MCP server.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+const CHECKOUT_ROOT = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+
+/**
+ * @param {object} [args]  { trail?: number } how many recent audit events (default 8, max 200)
+ * @param {{ codeRoot?: string, isPidAlive?: (pid:number)=>boolean, now?: ()=>number }} [deps]
+ */
+export async function handleFactoryRunStatus(args = {}, deps = {}) {
+  try {
+    const root = deps.codeRoot ?? CHECKOUT_ROOT;
+    const modPath = join(root, 'dev-factory', 'lib', 'run-state-model.mjs');
+    if (!existsSync(modPath)) {
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'FACTORY_RUN_STATUS_UNAVAILABLE', message: `dev-factory run-state model not found at ${modPath}` }, null, 2) }] };
+    }
+    const mod = await import(pathToFileURL(modPath).href);
+    const requested = Number(args?.trail);
+    const trail = Number.isFinite(requested) ? Math.min(Math.max(Math.trunc(requested), 0), 200) : 8;
+    const model = mod.readRunStateModel({
+      stateDir: join(root, 'dev-factory', 'state'),
+      queuePath: join(root, 'dev-factory', 'coo-queue.json'),
+      trail,
+      ...(deps.isPidAlive ? { isPidAlive: deps.isPidAlive } : {}),
+      ...(deps.now ? { now: deps.now } : {}),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(model, null, 2) }] };
+  } catch (err) {
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'FACTORY_RUN_STATUS_FAILED', message: String(err?.message ?? err) }, null, 2) }] };
+  }
+}

package/vendor/heyspex-mcp/mcp-config.mjs

@@ -19,7 +19,9 @@ export function getConfig() {
   // vaultId + vaultSource ([[HS-M95C]]): the locally resolved identity, so a
   // cloud console request can be scoped to THIS repo's vault instead of the
   // account's active-vault pointer (see console-fetch.mjs `getVaultIdHeader`).
-  const { repoRootAbs, vaultId, source: vaultSource } = getActiveConfig();
+  // vaultError: the typed VaultResolutionError when source is 'unbound'
+  // ([[HS-TYJA]]); vaultRoot is then only the launch folder, never a vault.
+  const { repoRootAbs, vaultId, source: vaultSource, error: vaultError = null } = getActiveConfig();
   const vaultRoot = repoRootAbs;
 
   // Per-vault default roadmap (env > the vault's own `type: roadmap` spec >
@@ -34,7 +36,7 @@ export function getConfig() {
   }
   const defaultRoadmapId = roadmap.id;
 
-  return { vaultRoot, vaultId, vaultSource, defaultRoadmapId };
+  return { vaultRoot, vaultId, vaultSource, vaultError, defaultRoadmapId };
 }
 
 // Resolved on every call (no caching): the MCP process is spawned once at

package/vendor/heyspex-mcp/spec-edit-tools.mjs

@@ -10,6 +10,31 @@ import { detectAgentIdentity, getConsoleUrl } from './mcp-config.mjs';
 import { resolveVaultWriteMode } from './read-path.mjs';
 import { deferredPayloadFromError, splitRawSpec, updateSpecViaConsole } from './cloud-vault-writes.mjs';
 import { writeFileSync } from 'node:fs';
+
+/**
+ * Split a whole spec for the cloud PUT with a FULL YAML parser. splitRawSpec's
+ * dependency-free parseSimpleYaml only knows flat keys, string lists, block
+ * scalars and two special nested keys, so a protocol's `enforcement:` list of
+ * objects reached the console as `['rule: <id>']` and the pull wrote that
+ * flattened block back (seen 2026-10-15 on dev-factory-delegation-routing,
+ * HS-PGHA; it broke scripts/build-guardrails.mjs). js-yaml loads lazily so the
+ * MCP startup stays lean (see yaml-scalar.mjs); CORE_SCHEMA keeps unquoted
+ * dates as strings, matching parseSimpleYaml. A YAML error falls back to the
+ * simple parser, so no edit that worked before is refused now.
+ */
+async function splitRawSpecFullYaml(raw) {
+  const text = String(raw ?? '');
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return splitRawSpec(text);
+  try {
+    const { default: yaml } = await import('js-yaml');
+    const parsed = yaml.load(match[1], { schema: yaml.CORE_SCHEMA });
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return splitRawSpec(text);
+    return { frontmatter: parsed, body: text.slice(match[0].length).trim() };
+  } catch {
+    return splitRawSpec(text);
+  }
+}
 import { executeShipEpicCloudAware } from './plan-push.mjs';
 import { executeRegenTask, executeRegenTasksForEpic } from './regen-tasks.mjs';
 import { loadTask } from './vault-io.mjs';
@@ -137,7 +162,7 @@ export async function handleEditFile(args = {}, deps = {}) {
   let cloudWrite = null;
   if (writeMode === 'cloud') {
     const consoleUrl = deps.consoleUrl ?? getConsoleUrl();
-    const { frontmatter, body } = splitRawSpec(args.content);
+    const { frontmatter, body } = await splitRawSpecFullYaml(args.content);
     const specId = typeof frontmatter?.id === 'string' ? frontmatter.id.trim() : '';
     if (!specId) {
       await releaseClaim();

package/vendor/heyspex-mcp/test-helpers.mjs

@@ -146,9 +146,12 @@ export function installScopedConsoleEnv({
 export function mirrorValidatorDeps(repoRoot, root) {
   cpSync(join(repoRoot, 'scripts'), join(root, 'scripts'), { recursive: true });
 
-  const vaultResolveRel = join('vendor', 'heyspex-mcp', 'vault-resolve.mjs');
   mkdirSync(join(root, 'vendor', 'heyspex-mcp'), { recursive: true });
-  cpSync(join(repoRoot, vaultResolveRel), join(root, vaultResolveRel));
+  // vault-resolve.mjs imports vault-binding.mjs (the repo binding, HS-TYJA).
+  for (const file of ['vault-resolve.mjs', 'vault-binding.mjs']) {
+    const rel = join('vendor', 'heyspex-mcp', file);
+    cpSync(join(repoRoot, rel), join(root, rel));
+  }
 
   const indexerRel = join('spex-console', 'src', 'lib', 'indexer');
   mkdirSync(join(root, indexerRel), { recursive: true });

package/vendor/heyspex-mcp/tool-catalog.mjs

@@ -2210,6 +2210,18 @@ export const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'heyspex_factory_run_status',
+    description:
+      'Status of the SpexCode orchestrator run (`spexcode run` / `hs factory run`), read from dev-factory/state: the SAME snapshot `spexcode status --json` and GET /api/factory/run/status return. Returns { schema: "spex.run-state/1", runId, live, front, lease { held, pid, acquiredAt, runId }, heartbeat { pid, beatAt, fresh, runId }, current (the COO seat: epic, milestone, pid, alive), queue [{ position, milestone, branch }], failures, stoppedReason, trail { file, total, events[] } } where trail.events are the last N typed seat events (the audit file seat-events.jsonl). Local disk state, read-only; deferred (load via heyspex_load_tools). Use `trail` to choose how many recent events (default 8, max 200).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        trail: { type: 'number', description: 'How many recent seat events to include (default 8, max 200; 0 = none).' },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: 'heyspex_dev_mode',
     description:

package/vendor/heyspex-mcp/tool-dispatch.mjs

@@ -28,6 +28,7 @@ import { handleGetProcedureViaTier, handleListProceduresViaTier, handleRunPrefli
 import { handleListRecipes, handleStartRecipe } from './recipe-handlers.mjs';
 import { handleFleetQueueClaim, handleFleetQueueComplete, handleFleetQueueList, handleFleetQueueSubmit } from './fleet-handlers.mjs';
 import { handleDevMode, handleDevServerStatus } from './dev-tools.mjs';
+import { handleFactoryRunStatus } from './factory-run-status.mjs';
 import { wrapDesignResult } from './tool-helpers.mjs';
 import { executeSettingsGet, executeSettingsList, executeSettingsSet } from './settings-tools.mjs';
 import { executeFirecrawlResearch, executeResolveResearchPlan } from './research-tools.mjs';
@@ -339,6 +340,8 @@ function dispatchHeySpexToolUnbudgeted(name, args, vaultRoot, config) {
       return handleDevServerStatus(vaultRoot);
     case 'heyspex_dev_mode':
       return handleDevMode(vaultRoot, args);
+    case 'heyspex_factory_run_status':
+      return handleFactoryRunStatus(args);
     case 'heyspex_settings_list':
       return wrapDesignResult(executeSettingsList(vaultRoot, args));
     case 'heyspex_settings_get':
@@ -390,8 +393,14 @@ function dispatchHeySpexToolUnbudgeted(name, args, vaultRoot, config) {
  * BYPASSES this gate on purpose — it calls the `*ViaTier` helpers directly —
  * so it proves the handlers, not the gate; keep both.
  */
-export function vaultRootGateVerdict(vaultRoot, { env = process.env } = {}) {
-  if (typeof vaultRoot === 'string' && vaultRoot && existsSync(vaultRoot)) return null;
+export function vaultRootGateVerdict(vaultRoot, { env = process.env, vaultSource = null, vaultError = null } = {}) {
+  // Unbound ([[HS-TYJA]]): `vaultRoot` is only the launch folder, never a
+  // vault, so its existing on disk proves nothing. Treat it as absent: the
+  // disk tier refuses with the resolver's typed code + fix; the neon tier
+  // proceeds and every vault-scoped console call is refused per call
+  // (console-fetch.mjs) while vault-less calls still work.
+  const unbound = vaultSource === 'unbound';
+  if (!unbound && typeof vaultRoot === 'string' && vaultRoot && existsSync(vaultRoot)) return null;
   let readTier = 'disk';
   try {
     readTier = resolveDevMode({ env }).readTier;
@@ -399,6 +408,14 @@ export function vaultRootGateVerdict(vaultRoot, { env = process.env } = {}) {
     readTier = 'disk';
   }
   if (readTier === 'neon') return null;
+  if (unbound && vaultError && typeof vaultError.code === 'string') {
+    return {
+      error: vaultError.code,
+      message: vaultError.message,
+      ...(vaultError.fix ? { fix: vaultError.fix } : {}),
+      ...(vaultError.from ? { from: vaultError.from } : {}),
+    };
+  }
   return { error: 'VAULT_NOT_FOUND', message: `Vault root not found: ${vaultRoot}` };
 }
 
@@ -407,7 +424,7 @@ export function handleToolsCall(params) {
   const config = getConfig();
   const vaultRoot = config.vaultRoot;
 
-  const gate = vaultRootGateVerdict(vaultRoot);
+  const gate = vaultRootGateVerdict(vaultRoot, { vaultSource: config.vaultSource, vaultError: config.vaultError });
   if (gate) {
     return {
       isError: true,
@@ -444,26 +461,8 @@ export function handleToolsCall(params) {
   // PreToolUse hook: hooks fail open and `.heyspex/mode.json` can disarm them,
   // whereas this runs on every call in every session. `refuse` returns instead
   // of dispatching; `warn` lets the call through and rides along on the result.
-  const preflightVerdict = evaluatePreflightGate(
-    vaultRoot,
-    name,
-    args,
-    detectAgentIdentity(args.agent, args.session_id).sessionId,
-  );
-  if (preflightVerdict && preflightVerdict.level === 'refuse') {
-    return {
-      isError: true,
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          error: preflightVerdict.error,
-          message: preflightVerdict.message,
-          required_intents: preflightVerdict.intents,
-          tool: preflightVerdict.tool,
-        }, null, 2),
-      }],
-    };
-  }
+  const preflightVerdict = preflightVerdictFor(vaultRoot, name, args);
+  if (preflightVerdict && preflightVerdict.level === 'refuse') return preflightRefusal(preflightVerdict);
 
   // Capture-obligation backstop ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]): holds on surfaces where
   // no hook loads. Fail open; break-glass HEYSPEX_OBLIGATION_BACKSTOP_OFF=1.
@@ -485,6 +484,43 @@ export function handleToolsCall(params) {
     : finalized;
 }
 
+/** The preflight proof-of-use verdict for one call — the SAME session id the marker write uses. */
+export function preflightVerdictFor(vaultRoot, name, args = {}) {
+  return evaluatePreflightGate(vaultRoot, name, args, detectAgentIdentity(args.agent, args.session_id).sessionId);
+}
+
+/** The refusal result a `refuse`-level verdict returns instead of dispatching. */
+export function preflightRefusal(verdict) {
+  return {
+    isError: true,
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        error: verdict.error,
+        message: verdict.message,
+        required_intents: verdict.intents,
+        tool: verdict.tool,
+      }, null, 2),
+    }],
+  };
+}
+
+/**
+ * The in-process seat path (spexharness tool-catalog createMcpInvoker) calls this, not the bare
+ * dispatchHeySpexTool, so heyspex_claim_spec / heyspex_submit_for_review refuse with
+ * PREFLIGHT_NOT_RUN there exactly as over stdio (B4, 2026-10-14). The bare function stays
+ * ungated for the console's POST /api/mcp, whose serverless instances cannot share markers.
+ */
+export function dispatchHeySpexToolGated(name, args = {}, vaultRoot, config, { dispatch = dispatchHeySpexTool } = {}) {
+  const verdict = preflightVerdictFor(vaultRoot, name, args);
+  if (verdict && verdict.level === 'refuse') return preflightRefusal(verdict);
+  const result = dispatch(name, args, vaultRoot, config);
+  if (!verdict || verdict.level !== 'warn') return result;
+  return result && typeof result.then === 'function'
+    ? result.then((r) => attachPreflightWarning(r, verdict))
+    : attachPreflightWarning(result, verdict);
+}
+
 /**
  * Ride a warn-level preflight verdict along on an otherwise successful result.
  * Best-effort by construction — a result whose text is not JSON is left exactly

package/vendor/heyspex-mcp/usable-dir-env.mjs

@@ -0,0 +1,82 @@
+/**
+ * usable-dir-env.mjs - is an env var that is supposed to name a directory
+ * actually usable as one? (HS-C0NW)
+ *
+ * Some hosts never expand `${CLAUDE_PROJECT_DIR}`-style placeholders in an MCP
+ * manifest's `env` block (GitHub Copilot CLI expands `${CLAUDE_PLUGIN_ROOT}` /
+ * `${PLUGIN_ROOT}` but not the project dir), so the server receives the
+ * literal text. Resolved relative to the plugin dir it became a path like
+ * `<pkg>/plugins/heyspex/${CLAUDE_PROJECT_DIR}`, which then got a `.heyspex/`
+ * build record mkdir'd into it. A value like that is "unset", not a path.
+ *
+ * Pure and dependency-free (node:fs / node:path only) so the plugin launcher
+ * (plugins/heyspex/bin/launch-mcp.mjs) and the vault resolver share one rule.
+ */
+import { statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+
+/** Env vars a host may set to name the project / vault folder. */
+export const DIR_ENV_KEYS = ['HEYSPEX_VAULT_ROOT', 'CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR'];
+
+/** `${VAR}`, `${VAR:-x}`, `$VAR`, `%VAR%` anywhere in the value. */
+const PLACEHOLDER = /\$\{[^}]*\}|\$[A-Za-z_][A-Za-z0-9_]*|%[A-Za-z_][A-Za-z0-9_]*%/;
+
+/** True when `value` still contains an unexpanded variable reference. */
+export function hasUnexpandedPlaceholder(value) {
+  return typeof value === 'string' && PLACEHOLDER.test(value);
+}
+
+function isExistingDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why `value` is not a usable directory, or null when it is.
+ * Reasons: 'empty' | 'placeholder' | 'relative' | 'missing'.
+ * `requireExisting: false` skips the on-disk check (a registered vault root may
+ * legitimately have no local checkout).
+ */
+export function unusableDirReason(value, { requireExisting = true, isDir = isExistingDir } = {}) {
+  if (typeof value !== 'string' || !value.trim()) return 'empty';
+  const v = value.trim();
+  if (hasUnexpandedPlaceholder(v)) return 'placeholder';
+  if (!isAbsolute(v)) return 'relative';
+  if (requireExisting && !isDir(v)) return 'missing';
+  return null;
+}
+
+/** Is `value` an existing absolute directory with no leftover placeholder? */
+export function isUsableDirValue(value, opts) {
+  return unusableDirReason(value, opts) === null;
+}
+
+/**
+ * Return a COPY of `env` with every unusable DIR_ENV_KEYS entry removed, so
+ * resolution falls through to the normal cwd walk. `onDrop(key, value, reason)`
+ * is called per removal. `requireExisting` may be a boolean or a per-key map.
+ */
+export function withoutUnusableDirEnv(env, { keys = DIR_ENV_KEYS, requireExisting = true, isDir, onDrop } = {}) {
+  const out = { ...env };
+  for (const key of keys) {
+    if (out[key] === undefined) continue;
+    const need = typeof requireExisting === 'object' ? requireExisting[key] !== false : requireExisting;
+    const reason = unusableDirReason(out[key], { requireExisting: need, ...(isDir ? { isDir } : {}) });
+    if (reason) {
+      onDrop?.(key, out[key], reason);
+      delete out[key];
+    }
+  }
+  return out;
+}
+
+/** In-place variant for `process.env` (the launcher hands its env to the server). */
+export function scrubUnusableDirEnv(env = process.env, opts = {}) {
+  const dropped = [];
+  withoutUnusableDirEnv(env, { ...opts, onDrop: (k, v, r) => dropped.push({ key: k, value: v, reason: r }) });
+  for (const { key } of dropped) delete env[key];
+  return dropped;
+}