heyspex 0.2.0 → 0.2.2

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

@@ -59,7 +59,28 @@
  * The endpoints in {@link VAULT_LESS_ENDPOINTS} (pairing, session identity,
  * creating/listing vaults and workspaces, dev-mode) are exempt: headers are
  * attached when they resolve, and nothing refuses when they do not.
+ *
+ * NO PIN, NO POINTER (diagnose "unpinned repo silently follows the
+ * account-wide active-vault pointer"; client half of
+ * [[HS-W3JF-PEGM-DIAG-one-account-wide-active-vault-pointer]] fix 2, "fail
+ * closed on a missing binding"): a repo that names no vault — no heyspex.yaml,
+ * no specs/, no satellite pin in its MCP manifest, no HEYSPEX_VAULT_ROOT/DIR —
+ * resolves at tier 4 to the registry's `active_vault_id` (`source:
+ * 'account-pointer'`), which mirrors whatever the owner last clicked in the
+ * console's vault switcher. On 2026-10-10 a session in the code repo resolved
+ * that way to a throwaway test vault, and every claim/file/submit would have
+ * landed there silently. So a pointer-sourced result is a THIRD local
+ * refusal, `VAULT_NOT_PINNED` ({@link VaultNotPinnedError}): the message names
+ * the vault the pointer would have used and the runnable pin (`hs install
+ * --attach-vault <id> --target <repo>` for a code repo, `hs connect` for a
+ * vault). The resolver's tier ORDER is untouched (decision memory
+ * `vault-resolver-precedence`) — only what the transport does with the
+ * result changes. Deliberate pointer use is the env hatch
+ * `HEYSPEX_ALLOW_POINTER_VAULT=1` ({@link pointerVaultAllowed}), which
+ * restores the old behaviour and announces the vault once per process on
+ * stderr ({@link announcePointerVaultOnce}).
  */
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -77,7 +98,8 @@ export { isVaultLessEndpoint, VAULT_LESS_ENDPOINTS };
 // checkout `npx hs` installs the unrelated public package hs@2.0.1
 // ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
 import { hsCommand } from '../../scripts/lib/hs-command.mjs';
-import { getActiveConfig, UNREGISTERED_VAULT_ID } from './vault-resolve.mjs';
+import { maybeDrainOnFirstSuccess } from './write-outbox.mjs';
+import { getActiveConfig, registryAccountIdForRoot, UNREGISTERED_VAULT_ID } from './vault-resolve.mjs';
 
 export const DEFAULT_CONSOLE_TIMEOUT_MS = 30000;
 
@@ -224,14 +246,19 @@ export function readMarkerAccount(repoRootAbs, { readFile } = {}) {
  * applies, unchanged).
  * @returns {string | null}
  */
-export function getRepoAccountId() {
+export function getRepoAccountId({ homeDir } = {}) {
   let resolved;
   try {
     resolved = getActiveConfig();
   } catch {
     return null;
   }
-  return readMarkerAccount(resolved?.repoRootAbs);
+  // Machine-local registry row, NOT the committed marker: a legacy
+  // `account:` line in heyspex.yaml is ignored (owner ruling 2026-10-16).
+  return registryAccountIdForRoot(
+    resolved?.repoRootAbs,
+    homeDir ? { registryDir: join(homeDir, '.heyspex') } : {},
+  );
 }
 
 /**
@@ -251,8 +278,8 @@ export function getRepoAccountId() {
  * credentials file is just "no token".
  * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, repoAccountId?: string | null }} [opts]
  */
-export function getAuthHeader({ env = process.env, homeDir = homedir(), repoAccountId } = {}) {
-  const accountId = repoAccountId === undefined ? getRepoAccountId() : repoAccountId;
+export function getAuthHeader({ env = process.env, homeDir = heyspexHome(), repoAccountId } = {}) {
+  const accountId = repoAccountId === undefined ? getRepoAccountId({ homeDir }) : repoAccountId;
   const { token } = readBearer({ env, homeDir, accountId });
   if (!token && accountId) throw new AccountTokenMissingError(accountId);
   return token ? { Authorization: `Bearer ${token}` } : {};
@@ -266,14 +293,19 @@ export function getAuthHeader({ env = process.env, homeDir = homedir(), repoAcco
  *
  * Contract (agreed with the console side, revised by
  * [[HS-MVG4-WW9R-TASK-mcp-and-hs-name-account-vault-on-every]]): send
- * `x-heyspex-vault-id: <id>` for EVERY registered id the resolver produced,
- * whatever its source — a repo-derived tier (`explicit`, `env-vault-root`,
- * `env-vault-dir`, `satellite-pin`, `cwd-heuristic`) AND the registry's active
- * pointer (`account-pointer`). The pointer used to send nothing so the cloud
- * console could fall back to ITS pointer; the two pointers drift, and a silent
- * fallback is exactly what served repo A's session from vault B. An
- * UNREGISTERED root is not a "no header" case either: it throws
- * {@link VaultNotRegisteredError} so the transport refuses before any fetch.
+ * `x-heyspex-vault-id: <id>` for EVERY registered id a REPO-DERIVED tier
+ * produced (`explicit`, `env-vault-root`, `env-vault-dir`, `satellite-pin`,
+ * `cwd-marker`, `marker-registry-mismatch`, `cwd-heuristic`). The registry's
+ * active pointer (`account-pointer`) used to send nothing so the cloud console
+ * could fall back to ITS pointer; HS-MVG4 then put the pointer's id on the
+ * wire too, because the two pointers drift and a silent fallback is exactly
+ * what served repo A's session from vault B. Both shapes share the same
+ * defect — the repo never said which vault it meant — so a pointer-sourced
+ * result is now REFUSED locally ({@link VaultNotPinnedError}) unless the
+ * `HEYSPEX_ALLOW_POINTER_VAULT=1` hatch is set, in which case the HS-MVG4
+ * behaviour (pointer id on the wire) applies. An UNREGISTERED root is not a
+ * "no header" case either: it throws {@link VaultNotRegisteredError} so the
+ * transport refuses before any fetch.
  */
 export const VAULT_ID_HEADER = 'x-heyspex-vault-id';
 /** The account the client believes it acts as; the console refuses a mismatch with 409 `ACCOUNT_MISMATCH`. */
@@ -283,6 +315,106 @@ export const ACCOUNT_ID_HEADER = 'x-heyspex-account-id';
 export const VAULT_NOT_REGISTERED = 'VAULT_NOT_REGISTERED';
 /** Local refusal: this machine has no configured account (`hs login` never ran). */
 export const ACCOUNT_NOT_CONFIGURED = 'ACCOUNT_NOT_CONFIGURED';
+/** Local refusal: the repo names no vault, so only the account-wide pointer answered. */
+export const VAULT_NOT_PINNED = 'VAULT_NOT_PINNED';
+
+/** The resolver tier that reads the registry's account-wide `active_vault_id` (vault-resolve.mjs tier 4). */
+export const POINTER_VAULT_SOURCE = 'account-pointer';
+/** Env hatch: `1`/`true` lets a pointer-sourced vault go on the wire (old behaviour), announced once per process. */
+export const ALLOW_POINTER_VAULT_ENV = 'HEYSPEX_ALLOW_POINTER_VAULT';
+
+/**
+ * Is the deliberate-pointer hatch set? Pure over `env`.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ */
+export function pointerVaultAllowed(env = process.env) {
+  const raw = env?.[ALLOW_POINTER_VAULT_ENV];
+  if (typeof raw !== 'string') return false;
+  const v = raw.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+/**
+ * Thrown by {@link vaultIdHeaderFor} / {@link getVaultIdHeader} when the
+ * resolver answered from the account-wide pointer (`source:
+ * 'account-pointer'`) and the hatch is off: the repo the session runs in
+ * names no vault, so the only thing that chose one was whatever the owner
+ * last selected in the console. `code` is stable for machine matching; the
+ * message names the vault the pointer WOULD have used (id + root), the repo
+ * that needs a pin, and the runnable pin for each repo kind.
+ */
+export class VaultNotPinnedError extends Error {
+  /**
+   * @param {{ vaultId?: string | null, repoRootAbs?: string | null, source?: string | null } | null | undefined} resolved
+   *   the pointer-sourced resolver result (its `repoRootAbs` is the POINTER vault's root)
+   * @param {{ cwd?: string | null }} [detail] `cwd`: the unpinned repo the session runs in
+   */
+  constructor(resolved, { cwd = null } = {}) {
+    const clean = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+    const vaultId = clean(resolved?.vaultId);
+    const vaultRoot = clean(resolved?.repoRootAbs);
+    const repo = clean(cwd);
+    const here = repo ? ` (${repo})` : '';
+    const wouldUse = vaultId
+      ? `vault ${vaultId}${vaultRoot ? ` (${vaultRoot})` : ''}`
+      : 'an unknown vault';
+    // Both commands render through `hsCommand` so they run on the machine
+    // reading them ([[HS-I6HT]]); `<repo>` stands in when the cwd is unknown.
+    const attach = hsCommand(`install --attach-vault ${vaultId ?? '<vault-id>'} --target ${repo ?? '<repo>'}`);
+    const connect = hsCommand('connect');
+    super(
+      `This repo${here} names no HeySpex vault — no heyspex.yaml, no specs/ dir, and no HEYSPEX_VAULT_ROOT pin in its .mcp.json — `
+        + 'so the console call was refused before it was sent. Without a pin the session would silently follow the '
+        + 'account-wide active-vault pointer (whatever vault was last selected in the console or by `hs vault use`), '
+        + `which right now names ${wouldUse}. `
+        + 'Pin a vault, then restart the MCP server: '
+        + `for a code repo run \`${attach}\`; for a vault repo run \`${connect}\` inside it. `
+        + `To follow the pointer on purpose, start the server with ${ALLOW_POINTER_VAULT_ENV}=1. Nothing was sent.`,
+    );
+    this.name = 'VaultNotPinnedError';
+    this.code = VAULT_NOT_PINNED;
+    this.vaultId = vaultId;
+    this.vaultRootAbs = vaultRoot;
+    this.repoRootAbs = repo;
+    this.source = clean(resolved?.source);
+  }
+}
+
+/** One line for stderr naming the pointer vault the hatch admitted. Pure. */
+export function pointerVaultNotice(resolved) {
+  const id = typeof resolved?.vaultId === 'string' && resolved.vaultId.trim() ? resolved.vaultId.trim() : 'unknown';
+  const root = typeof resolved?.repoRootAbs === 'string' && resolved.repoRootAbs.trim() ? ` (${resolved.repoRootAbs.trim()})` : '';
+  return `[heyspex-mcp] ${ALLOW_POINTER_VAULT_ENV} is set: this repo names no vault, so console calls follow the account-wide active-vault pointer — vault ${id}${root}. Every claim/file/submit this session lands there.\n`;
+}
+
+let _pointerVaultAnnounced = false;
+
+/**
+ * Write {@link pointerVaultNotice} to stderr ONCE per process, and only when
+ * `resolved` is pointer-sourced AND the hatch is on. Called at stdio-server
+ * start (cli.mjs) and lazily by {@link vaultIdHeaderFor} when the hatch
+ * admits a pointer header (covers the `cli.mjs call …` subprocesses), so
+ * every process that acts on the pointer says so exactly once. Returns
+ * `true` iff it wrote. Never throws.
+ * @param {{ vaultId?: string, repoRootAbs?: string, source?: string } | null | undefined} resolved
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, write?: (line: string) => unknown }} [opts]
+ */
+export function announcePointerVaultOnce(resolved, { env = process.env, write } = {}) {
+  if (_pointerVaultAnnounced) return false;
+  if (resolved?.source !== POINTER_VAULT_SOURCE || !pointerVaultAllowed(env)) return false;
+  _pointerVaultAnnounced = true;
+  try {
+    (write ?? ((line) => process.stderr.write(line)))(pointerVaultNotice(resolved));
+  } catch {
+    /* a stderr failure never becomes a transport failure */
+  }
+  return true;
+}
+
+/** Test-only: forget that the pointer notice was written, so the next process-start path writes it again. */
+export function resetPointerVaultNoticeForTests() {
+  _pointerVaultAnnounced = false;
+}
 
 /**
  * Thrown by {@link vaultIdHeaderFor} / {@link getVaultIdHeader} when the
@@ -392,19 +524,30 @@ export class AccountNotConfiguredError extends Error {
   }
 }
 
-/** True for the two local scope refusals this module throws. */
+/** True for the three local scope refusals this module throws. */
 export function isLocalScopeRefusal(err) {
-  return err instanceof VaultNotRegisteredError || err instanceof AccountNotConfiguredError;
+  return (
+    err instanceof VaultNotRegisteredError
+    || err instanceof AccountNotConfiguredError
+    || err instanceof VaultNotPinnedError
+  );
 }
 
 /**
- * Gate: the vault header for a resolver result. A registered id → the header
- * naming the CLOUD id ({@link cloudVaultIdFor}), whatever `source` says; the
- * `unregistered` sentinel → throws {@link VaultNotRegisteredError}; no result
- * / blank id → `{}` (nothing to name — the resolver itself failed, which is
- * not the same as "unregistered"). Pure given `opts.readMarkerVaultId`.
+ * Gate: the vault header for a resolver result. A registered id from a
+ * REPO-DERIVED tier → the header naming the CLOUD id ({@link cloudVaultIdFor});
+ * the `unregistered` sentinel → throws {@link VaultNotRegisteredError}; a
+ * pointer-sourced result (`source: 'account-pointer'`) → throws
+ * {@link VaultNotPinnedError} unless the hatch is on ({@link pointerVaultAllowed}
+ * over `opts.env`), in which case the pointer's id goes on the wire and the
+ * process announces it once ({@link announcePointerVaultOnce}); no result /
+ * blank id → `{}` (nothing to name — the resolver itself failed, which is not
+ * the same as "unregistered"). Pure given `opts.readMarkerVaultId`, `opts.env`
+ * and `opts.write`.
  * @param {{ vaultId?: string, source?: string, repoRootAbs?: string } | null | undefined} resolved
- * @param {{ readMarkerVaultId?: (repoRootAbs: string) => string | null }} [opts]
+ * @param {{ readMarkerVaultId?: (repoRootAbs: string) => string | null, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, cwd?: string | null, write?: (line: string) => unknown }} [opts]
+ *   `cwd`: the unpinned repo named in the refusal (default: the resolver's own
+ *   cwd base, `CLAUDE_PROJECT_DIR` then `process.cwd()`).
  */
 export function vaultIdHeaderFor(resolved, opts = {}) {
   const vaultId = typeof resolved?.vaultId === 'string' ? resolved.vaultId.trim() : '';
@@ -412,15 +555,32 @@ export function vaultIdHeaderFor(resolved, opts = {}) {
   if (vaultId === UNREGISTERED_VAULT_ID) {
     throw new VaultNotRegisteredError(resolved?.repoRootAbs, resolved?.source);
   }
+  if (resolved?.source === POINTER_VAULT_SOURCE) {
+    const env = opts.env ?? process.env;
+    if (!pointerVaultAllowed(env)) {
+      throw new VaultNotPinnedError(resolved, { cwd: opts.cwd === undefined ? resolverCwdBase() : opts.cwd });
+    }
+    announcePointerVaultOnce(resolved, { env, write: opts.write });
+  }
   return { [VAULT_ID_HEADER]: cloudVaultIdFor({ ...resolved, vaultId }, opts) };
 }
 
+/**
+ * The folder the resolver's walk started from — the repo that needs a pin.
+ * Mirrors vault-resolve.mjs `cwdBase` (`CLAUDE_PROJECT_DIR`, then `process.cwd()`).
+ */
+function resolverCwdBase() {
+  const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+  return typeof fromEnv === 'string' && fromEnv.trim() ? fromEnv.trim() : process.cwd();
+}
+
 /**
  * The vault-id header for THIS process, from the memoized resolver
  * (`getActiveConfig`, resolved once per process; tests reset it via
  * `resetActiveConfigCache`). A resolver FAILURE is "no header" (`{}`); an
- * `unregistered` RESULT throws {@link VaultNotRegisteredError} so the caller
- * refuses before any fetch.
+ * `unregistered` RESULT throws {@link VaultNotRegisteredError} and a
+ * pointer-sourced one throws {@link VaultNotPinnedError} (hatch off) so the
+ * caller refuses before any fetch.
  */
 export function getVaultIdHeader() {
   let resolved;
@@ -455,7 +615,7 @@ export function accountIdHeaderFor(accountId) {
  * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, repoAccountId?: string | null }} [opts]
  */
 export function getAccountIdHeader({ repoAccountId, ...opts } = {}) {
-  const recorded = repoAccountId === undefined ? getRepoAccountId() : repoAccountId;
+  const recorded = repoAccountId === undefined ? getRepoAccountId({ homeDir: opts.homeDir }) : repoAccountId;
   return accountIdHeaderFor(recorded || resolveSessionOwnerUncached(opts));
 }
 
@@ -464,7 +624,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} err
+ * @param {VaultNotRegisteredError | AccountNotConfiguredError | VaultNotPinnedError | AccountTokenMissingError} err
  * @param {string} url the request that was NOT sent
  */
 export function scopeRefusalResult(err, url) {
@@ -545,7 +705,7 @@ async function loadDevModeCore() {
  * `resolveDevMode` (env → machine-local record → default prod/cloud) when the
  * core exports it, else `readLocalDevModeRecord` + `deriveSemantics`.
  */
-export async function resolveConsoleReliance({ env = process.env, homeDir = homedir() } = {}) {
+export async function resolveConsoleReliance({ env = process.env, homeDir = heyspexHome() } = {}) {
   const core = await loadDevModeCore();
   if (!core) return null;
   try {
@@ -587,7 +747,7 @@ function headerHasToken(header) {
  * @param {number} [deps.defaultTimeoutMs]
  * @param {(failedResult: object, ctx: { url: string, init: object, timeoutMs: number }) => Promise<{ retryUrl?: string, reason?: string, healedUrl?: string, discoveryHealed?: boolean, devServerStatus?: object } | null | undefined>} [deps.recoverFromTransportFailure]
  * @param {() => object} [deps.getAuthHeader] Resolves the outbound Authorization header (default: {@link getAuthHeader}).
- * @param {() => object} [deps.getVaultIdHeader] Resolves the outbound `x-heyspex-vault-id` header (default: {@link getVaultIdHeader}); throws {@link VaultNotRegisteredError} for an unregistered root.
+ * @param {() => object} [deps.getVaultIdHeader] Resolves the outbound `x-heyspex-vault-id` header (default: {@link getVaultIdHeader}); throws {@link VaultNotRegisteredError} for an unregistered root, {@link VaultNotPinnedError} for a pointer-sourced one.
  * @param {() => object} [deps.getAccountIdHeader] Resolves the outbound `x-heyspex-account-id` header (default: {@link getAccountIdHeader}); throws {@link AccountNotConfiguredError} when no account is configured.
  * @param {() => Promise<{ reliance: string|null, hasToken: boolean }>} [deps.getConsoleAuthState] Resolves the reliance + token state used to tell "not signed in" from "server down" (default: dev-mode core + {@link getAuthHeader}).
  */
@@ -881,7 +1041,11 @@ export function makeConsoleFetch({
     }
     const timeoutMs = options.timeout || defaultTimeoutMs;
     const retryOnTimeout = options.retryOnTimeout === false ? isLoopbackUrl(url) : true;
-    return withRetry(url, init, timeoutMs, { retryOnTimeout });
+    const outcome = await withRetry(url, init, timeoutMs, { retryOnTimeout });
+    // Degrade-don't-die: the first successful console call of the process kicks
+    // a background replay of any queued writes (non-blocking, failure-safe).
+    if (outcome?.ok) maybeDrainOnFirstSuccess(consoleFetch);
+    return outcome;
   }
 
   return { postClaimEndpoint, consoleFetch };

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

@@ -6,13 +6,15 @@
 import {
   consoleErrorCode,
   consoleErrorMessage,
+  getAccountIdHeader,
   getAuthHeader,
+  getVaultIdHeader,
   makeConsoleFetch,
   resolveConsoleReliance,
   rewriteUrlOrigin,
 } from './console-fetch.mjs';
 import { effectiveConsoleUrl, getConfig } from './mcp-config.mjs';
-import { contextAuthHeader } from './request-context.mjs';
+import { contextAccountIdHeader, contextAuthHeader, contextVaultIdHeader } from './request-context.mjs';
 import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
@@ -145,6 +147,10 @@ export async function enrichConsoleFailurePayloadAsync(result, base) {
 export const { postClaimEndpoint, consoleFetch } = makeConsoleFetch({
   getConsoleUrl: effectiveConsoleUrl,
   getAuthHeader: () => contextAuthHeader() ?? getAuthHeader(),
+  // Remote endpoint: the vault is the CALLER's `x-heyspex-vault-id`, never the
+  // server process's own resolution (P1/P3).
+  getVaultIdHeader: () => contextVaultIdHeader() ?? getVaultIdHeader(),
+  getAccountIdHeader: () => contextAccountIdHeader() ?? getAccountIdHeader(),
   recoverFromTransportFailure: recoverConsoleTransportFailure,
 });
 

package/vendor/heyspex-mcp/credentials.mjs

@@ -56,6 +56,7 @@
 // `hs login` / `hs login --migrate` (an explicit verb, with `--dry-run`)
 // re-keys the legacy token under the account the console confirms for it.
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import os, { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -69,7 +70,7 @@ export const MCP_TOKEN_ENV = 'HEYSPEX_MCP_TOKEN';
  */
 
 /** `~/.heyspex/credentials.yaml` for `homeDir`. */
-export function credentialsFilePath(homeDir = homedir()) {
+export function credentialsFilePath(homeDir = heyspexHome()) {
   return join(homeDir, '.heyspex', 'credentials.yaml');
 }
 
@@ -284,7 +285,7 @@ function readLegacyConfigAccountId(read, homeDir) {
  * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string | null, accountId?: string | null }} [opts]
  * @returns {Bearer}
  */
-export function readBearer({ env = process.env, homeDir = homedir(), readFile, accountId } = {}) {
+export function readBearer({ env = process.env, homeDir = heyspexHome(), readFile, accountId } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
   const credentialsText = readTextOrNull(read, credentialsFilePath(homeDir));
   const named = typeof accountId === 'string' && accountId.trim() ? accountId.trim() : null;
@@ -302,7 +303,7 @@ export function readBearer({ env = process.env, homeDir = homedir(), readFile, a
  * @param {{ homeDir?: string, readFile?: (p: string) => string | null }} [opts]
  * @returns {CredentialsStore & { legacyAccountId: string | null }}
  */
-export function readCredentialsStore({ homeDir = homedir(), readFile } = {}) {
+export function readCredentialsStore({ homeDir = heyspexHome(), readFile } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
   const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
   const legacyAccountId = store.schemaVersion === 1 ? readLegacyConfigAccountId(read, homeDir) : null;
@@ -320,7 +321,7 @@ export function readCredentialsStore({ homeDir = homedir(), readFile } = {}) {
  * @param {{ homeDir?: string, readFile?: (p: string) => string | null }} [opts]
  * @returns {string | null}
  */
-export function readCurrentAccountId({ homeDir = homedir(), readFile } = {}) {
+export function readCurrentAccountId({ homeDir = heyspexHome(), readFile } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
   const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
   if (store.schemaVersion === 2 && store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID) {
@@ -462,7 +463,7 @@ function requireAccountId(fn, accountId) {
  * @param {{ homeDir?: string, accountId: string, mcpToken: string, consoleUrl?: string | null, email?: string | null, pairedAt?: string | null, makeCurrent?: boolean, rekeyLegacyAs?: string | null }} input
  */
 export function writeAccountCredentials({
-  homeDir = homedir(),
+  homeDir = heyspexHome(),
   accountId,
   mcpToken,
   consoleUrl = null,
@@ -504,7 +505,7 @@ function rekeyLegacy(store, rekeyAs) {
  * @param {{ homeDir?: string, confirmedAccountId: string, email?: string | null, apply?: boolean }} input
  * @returns {{ action: 'rekey' | 'already-v2' | 'nothing-to-migrate', accountId: string | null, path: string }}
  */
-export function migrateLegacyCredentials({ homeDir = homedir(), confirmedAccountId, email = null, apply = false }) {
+export function migrateLegacyCredentials({ homeDir = heyspexHome(), confirmedAccountId, email = null, apply = false }) {
   const path = credentialsFilePath(homeDir);
   const { store } = loadForWrite(homeDir);
   if (store.schemaVersion === 2) return { action: 'already-v2', accountId: store.currentAccountId, path };
@@ -527,7 +528,7 @@ export function migrateLegacyCredentials({ homeDir = homedir(), confirmedAccount
  * pairs). Returns the file path.
  * @param {{ homeDir?: string, accountId: string }} input
  */
-export function setCurrentAccount({ homeDir = homedir(), accountId }) {
+export function setCurrentAccount({ homeDir = heyspexHome(), accountId }) {
   requireAccountId('setCurrentAccount', accountId);
   const { store } = loadForWrite(homeDir);
   if (!store.accounts[accountId]?.mcp_token) {
@@ -545,7 +546,7 @@ export function setCurrentAccount({ homeDir = homedir(), accountId }) {
  * @param {{ homeDir?: string, accountId?: string | null }} [input]
  * @returns {{ removed: string | null, wasCurrent: boolean, currentAccountId: string | null, path: string }}
  */
-export function removeAccount({ homeDir = homedir(), accountId = null } = {}) {
+export function removeAccount({ homeDir = heyspexHome(), accountId = null } = {}) {
   const path = credentialsFilePath(homeDir);
   const { store } = loadForWrite(homeDir);
   const target = accountId ?? store.currentAccountId;

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

@@ -5,6 +5,7 @@ import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { PACKAGE_ROOT } from './package-root.mjs';
+import { listQuarantinedOutbox, outboxCount } from './write-outbox.mjs';
 import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
 
 // scripts/dev-server-status.mjs and scripts/lib/dev-mode.mjs are CODE-repo
@@ -26,6 +27,12 @@ export async function handleDevServerStatus(vaultRoot) {
     const coreUrl = pathToFileURL(scriptPath).href;
     const mod = await import(coreUrl);
     const status = await mod.getDevServerStatus({ vaultRoot });
+    // Degrade-don't-die visibility: queued / quarantined cloud writes.
+    try {
+      status.write_outbox = { pending: outboxCount(vaultRoot), quarantined: listQuarantinedOutbox(vaultRoot).length };
+    } catch {
+      /* best effort */
+    }
     return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
   } catch (err) {
     return {

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

@@ -18,6 +18,13 @@ import { randomUUID } from 'node:crypto';
 import { consoleFetch, enrichConsoleFailurePayloadAsync } from './console-transport.mjs';
 import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
 import { resolveReadTier } from './read-path.mjs';
+import {
+  buildDeferredPayload,
+  deferredToolResponse,
+  drainAndSummarize,
+  isOutageClassResult,
+  stashIfOutage,
+} from './write-outbox.mjs';
 import { join } from 'node:path';
 import { statSync, existsSync } from 'node:fs';
 import { importDevModeCore } from './dev-mode-core.mjs';
@@ -456,6 +463,9 @@ export async function handleFileSpec(args = {}, vaultRoot = null) {
   // shared `init`), so a slow-console retry replays the first create server-side
   // instead of double-allocating a second byte-identical spec.
   const idempotencyKey = randomUUID();
+  // Degrade-don't-die: replay anything queued by an earlier outage first (the
+  // drain never stashes, and is failure-safe).
+  const outboxNote = vaultRoot ? await drainAndSummarize(vaultRoot, consoleFetch) : {};
   const result = await consoleFetch('/api/specs', {
     method: 'POST',
     body,
@@ -469,6 +479,30 @@ export async function handleFileSpec(args = {}, vaultRoot = null) {
     retryOnTimeout: false,
   });
   if (!result.ok) {
+    // Outage class (status 0 / timeout / 5xx) in CLOUD reliance: queue the create
+    // with its idempotency key and answer truthfully "deferred" — never isError,
+    // never a claim it landed. 4xx / 401 / sign-in problems keep their loud envelope.
+    if (vaultRoot && isOutageClassResult(result) && (await resolveReadTier()) === 'neon') {
+      const stashed = stashIfOutage(
+        result,
+        {
+          op: 'create',
+          route: '/api/specs',
+          method: 'POST',
+          request_body: body,
+          idempotency_key: idempotencyKey,
+          acting_agent: actingAgent,
+          session_id: args.session_id ?? null,
+        },
+        vaultRoot,
+      );
+      if (stashed) {
+        return deferredToolResponse({
+          ...buildDeferredPayload(stashed, vaultRoot, { attempted: { type: args.type, name: args.name } }),
+          ...(outboxNote.drained ? { drained: outboxNote.drained } : {}),
+        });
+      }
+    }
     const payload = await enrichConsoleFailurePayloadAsync(result, {
       error: consoleErrorCode(result, 'FILE_SPEC_FAILED'),
       message: consoleErrorMessage(result, `POST /api/specs returned ${result.status}`),
@@ -523,6 +557,7 @@ export async function handleFileSpec(args = {}, vaultRoot = null) {
     landed,
     spec,
     console_response: result.body,
+    ...outboxNote,
   };
   if (landingError) {
     return {

package/vendor/heyspex-mcp/fleet-queue-tools.mjs

@@ -24,6 +24,7 @@
  * call these tools with no extra setup.
  */
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
@@ -40,7 +41,7 @@ export function resolveFleetToken() {
   const env = process.env.HEYSPEX_FLEET_TOKEN;
   if (env && env.trim()) return env.trim();
   try {
-    const yaml = readFileSync(join(homedir(), '.heyspex', 'credentials.yaml'), 'utf8');
+    const yaml = readFileSync(join(heyspexHome(), '.heyspex', 'credentials.yaml'), 'utf8');
     const clerk = yaml.match(/^clerk:\s*$([\s\S]*?)(?=^\S|\s*$(?![\s\S]))/m)?.[1] ?? yaml;
     const m = clerk.match(/^\s*companion_token:\s*["']?([^"'\r\n#]+)/m);
     if (m?.[1]?.trim()) return m[1].trim();

package/vendor/heyspex-mcp/folder-trust-store.mjs

@@ -17,6 +17,7 @@
  * own header; this file only carries the read/write/list primitives, not the trust decision
  * logic itself.
  */
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -25,7 +26,7 @@ import path from 'node:path';
 export const TRUST_STORE_REL = path.join('.heyspex', 'trusted-folders.json');
 
 /** Resolve the real trust-store path for a given home directory (defaults to `os.homedir()`). */
-export function trustStorePath(home = os.homedir()) {
+export function trustStorePath(home = heyspexHome()) {
   return path.join(home, TRUST_STORE_REL);
 }
 

package/vendor/heyspex-mcp/http-transport.mjs

@@ -125,6 +125,7 @@ export function toolNotAvailableRemotelyError(id, name) {
  * @property {string|null} [sessionId] The client's `Mcp-Session-Id`, if any.
  * @property {string} [consoleUrl] Origin the in-process handlers should call back to (the deployment itself).
  * @property {Record<string, string>} [authHeader] The caller's own credential to forward on those calls.
+ * @property {string|null} [vaultId] The caller's own `x-heyspex-vault-id`, forwarded so the call is scoped to the vault the CALLER named.
  * @property {string} [agentName] Default `agent` for tools whose schema declares one.
  */
 
@@ -204,6 +205,7 @@ export function createRemoteMcpHandler(deps) {
     const requestContext = {
       ...(ctx?.consoleUrl ? { consoleUrl: ctx.consoleUrl } : {}),
       ...(ctx?.authHeader ? { authHeader: ctx.authHeader } : {}),
+      ...(ctx?.vaultId ? { vaultId: ctx.vaultId } : {}),
     };
     try {
       const result = await runWithRequestContext(requestContext, () => dispatch(name, args, vaultRoot, config));

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

@@ -245,7 +245,7 @@ export async function walkSpecListPages(consoleFetch, path, { limit = 500, maxPa
     const pagePath = `${url.pathname}${url.search}`;
     const res = await consoleFetch(pagePath);
     if (!res.ok) {
-      throw new Error(`GET ${pagePath} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`);
+      throw Object.assign(new Error(`GET ${pagePath} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`), { status: res.status, errorKind: res.errorKind, authProblem: res.authProblem || res.refusal ? true : undefined });
     }
     const specs = Array.isArray(res.body?.specs) ? res.body.specs : [];
     rows.push(...specs);

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

@@ -4,8 +4,11 @@
 
 import { contextConsoleUrl } from './request-context.mjs';
 import { getActiveConfig } from './vault-resolve.mjs';
+import { resolveDefaultRoadmap } from './roadmap-default.mjs';
 import { resolveConsoleUrl } from '../../scripts/lib/console-url-resolver.mjs';
 
+const warnedMultiRoadmap = new Set();
+
 export function getConfig() {
   // Vault resolution is delegated to the shared 5-tier resolver
   // (vault-resolve.mjs) so the MCP face agrees with the console face on which
@@ -19,7 +22,17 @@ export function getConfig() {
   const { repoRootAbs, vaultId, source: vaultSource } = getActiveConfig();
   const vaultRoot = repoRootAbs;
 
-  const defaultRoadmapId = process.env.HEYSPEX_ROADMAP_ID || 'HS-ROADMAP-PRODUCT';
+  // Per-vault default roadmap (env > the vault's own `type: roadmap` spec >
+  // platform constant) — never the platform id for a customer vault.
+  const roadmap = resolveDefaultRoadmap(vaultRoot);
+  if (roadmap.source === 'vault-multiple' && !warnedMultiRoadmap.has(vaultRoot)) {
+    warnedMultiRoadmap.add(vaultRoot);
+    process.stderr.write?.(
+      `[heyspex-mcp] vault ${vaultRoot} has ${roadmap.candidates.length} roadmaps (${roadmap.candidates.join(', ')}); defaulting to ${roadmap.id}. Pass roadmap_id to choose.
+`,
+    );
+  }
+  const defaultRoadmapId = roadmap.id;
 
   return { vaultRoot, vaultId, vaultSource, defaultRoadmapId };
 }