heyspex 0.2.2 → 0.2.4

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/http-transport.mjs

@@ -163,7 +163,12 @@ export function createRemoteMcpHandler(deps) {
       // No listChanged: the remote surface is fixed (no progressive loader),
       // and JSON-response mode has no channel to push a notification anyway.
       capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: serverInfo?.name ?? 'heyspex', version: serverInfo?.version ?? '0.0.0-unknown' },
+      serverInfo: {
+        name: serverInfo?.name ?? 'heyspex',
+        ...(serverInfo?.title ? { title: serverInfo.title } : {}),
+        version: serverInfo?.version ?? '0.0.0-unknown',
+        ...(serverInfo?.icons ? { icons: serverInfo.icons } : {}),
+      },
       ...(instructions ? { instructions } : {}),
     };
   }

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/server-identity.mjs

@@ -0,0 +1,13 @@
+/**
+ * MCP server display identity (Implementation.title / Implementation.icons,
+ * MCP spec 2025-06-18 / 2025-11-25). `name` stays the stable identifier
+ * ("heyspex": tool prefixes mcp__heyspex__* depend on it); only `title` and
+ * `icons` are for display. The icon is the 128px PNG of
+ * plugins/heyspex/assets/heyspex-glyph-128.png inlined as a data: URI (PNG is
+ * the format the spec requires clients to support); a test keeps the two in sync.
+ */
+export const SERVER_TITLE = "HeySpex";
+export const SERVER_ICON_DATA_URI = "data:image/png;base64,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";
+export const SERVER_ICONS = Object.freeze([
+  Object.freeze({ src: SERVER_ICON_DATA_URI, mimeType: "image/png", sizes: Object.freeze(["128x128"]) }),
+]);

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';
@@ -38,6 +39,7 @@ import { applyToolBudget } from './response-budget.mjs';
 import { resolveDevMode } from '../../scripts/lib/dev-mode.mjs';
 import { dirname, join } from 'node:path';
 import { MODULE_DIR } from './package-root.mjs';
+import { SERVER_TITLE, SERVER_ICONS } from './server-identity.mjs';
 
 export const SERVER_NAME = 'heyspex';
 
@@ -143,7 +145,10 @@ export async function handleInitialize(params) {
     instructions,
     serverInfo: {
       name: SERVER_NAME,
+      // Display identity (MCP Implementation.title / .icons); `name` is the stable id.
+      title: SERVER_TITLE,
       version: SERVER_VERSION,
+      icons: SERVER_ICONS,
     },
   };
 }
@@ -339,6 +344,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 +397,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 +412,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 +428,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 +465,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 +488,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;
+}