heyspex 0.1.0 → 0.2.0

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

@@ -25,11 +25,60 @@
  * it to every outbound request — `consoleFetch` AND `postClaimEndpoint` share
  * one transport, so both get it for free. No token resolvable → no header,
  * exactly today's (unauthenticated) behavior against a local dev console.
+ *
+ * SIGN-IN vs OUTAGE ([[HS-9R6S-N8VP-DIAG-capture-writes-report-the-console-as]]):
+ * a refused connection is NOT proof the console is down — it is equally the
+ * symptom of talking to the wrong console. After recovery has failed, a
+ * status-0 result is re-classified against the resolved reliance
+ * (scripts/lib/dev-mode.mjs) + the resolved bearer token:
+ *
+ *   - cloud reliance + loopback URL  → `CONSOLE_LOCAL_URL_IN_CLOUD_MODE`
+ *   - cloud reliance + no token      → `CONSOLE_NOT_SIGNED_IN`
+ *   - anything else                  → `CONSOLE_UNREACHABLE` (unchanged)
+ *   - an answered HTTP 401           → `CONSOLE_NOT_SIGNED_IN`
+ *
+ * Both new classes carry `authProblem` on the result. Callers MUST NOT treat
+ * an `authProblem` result as bufferable: nothing becomes reachable until the
+ * user runs `hs login`, so stashing to the offline buffer would hide the real
+ * cause behind a false "your words will sync" promise. The 4xx →
+ * CAPTURE_CONFLICT / 5xx → PATCH_FAILED contract is untouched — both still
+ * mean "the server ANSWERED", and neither buffers; 401 only gets a more
+ * specific code and an actionable message inside that same never-buffer family.
+ *
+ * EXPLICIT SCOPE ([[HS-MVG4-WW9R-TASK-mcp-and-hs-name-account-vault-on-every]],
+ * invariant 2 of [[HS-BIWR-WW9R-EPIC-explicit-vault-scope-on-every-console]]):
+ * every vault-scoped request names `{ account, vault }` on the wire —
+ * `x-heyspex-vault-id` from the resolver (ANY source, the registry pointer
+ * included) and `x-heyspex-account-id` from the one account reader
+ * (session-owner.mjs). A cwd that resolves to an UNREGISTERED root, or a
+ * machine with no configured account, is refused LOCALLY before any fetch:
+ * `consoleFetch` / `postClaimEndpoint` return a status-0 result carrying
+ * `refusal: VAULT_NOT_REGISTERED | ACCOUNT_NOT_CONFIGURED` (also stamped as
+ * `authProblem`, so every existing never-buffer path treats it the same way a
+ * sign-in problem is treated) and a message naming `hs connect` / `hs login`.
+ * 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.
  */
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { readBearer } from './credentials.mjs';
+import { resolveSessionOwnerUncached } from './session-owner.mjs';
+import { isVaultLessEndpoint, VAULT_LESS_ENDPOINTS } from './vault-less-endpoints.mjs';
+
+export { isVaultLessEndpoint, VAULT_LESS_ENDPOINTS };
+
+// The runnable form of a HeySpex command on THIS machine — `hs login` when the
+// bin is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" login`.
+// Never hard-code the bare `hs …` spelling in text a human reads, and never an
+// `npx` form: npx resolves from the READER's working directory, and outside a
+// 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';
+
 export const DEFAULT_CONSOLE_TIMEOUT_MS = 30000;
 
 /** Backoff when Next dev restarts (next.config change, etc.) — ECONNREFUSED is transient. */
@@ -39,6 +88,26 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * Cold cloud lambda ([[HS-2FQY]] read side): the console answers 503
+ * `vault_scope_unresolved` (+ `Retry-After`) while it has not resolved its
+ * active vault yet, instead of a 200 empty bucket that reads as "the vault is
+ * empty". Transient by contract — the console kicks its own self-heal — so
+ * the client waits the advertised window (capped) and tries once more.
+ */
+export const VAULT_SCOPE_RETRY_CAP_MS = 5000;
+export const VAULT_SCOPE_RETRY_DEFAULT_MS = 3000;
+
+export function isVaultScopeUnresolved(result) {
+  return result?.status === 503 && result?.body?.error === 'vault_scope_unresolved';
+}
+
+export function retryAfterMs(result) {
+  const raw = Number(result?.retryAfterSeconds);
+  if (!Number.isFinite(raw) || raw <= 0) return VAULT_SCOPE_RETRY_DEFAULT_MS;
+  return Math.min(raw * 1000, VAULT_SCOPE_RETRY_CAP_MS);
+}
+
 /**
  * Detect AbortError from a thrown fetch error. Covers the standard
  * `AbortError` name and the substring fallback some runtimes use
@@ -98,26 +167,415 @@ export function rewriteUrlOrigin(urlString, originUrl) {
   return target.href;
 }
 
+/** Local refusal: the repo records an account this machine holds no token for. */
+export const ACCOUNT_TOKEN_MISSING = 'account_token_missing';
+
+/**
+ * Thrown by {@link getAuthHeader} when the repo's heyspex.yaml records
+ * `account: <A>` and this machine stores no token for A
+ * ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]], invariant 4). The
+ * transport refuses every console call with it rather than sending the
+ * CURRENT account's token — that fallback is exactly how a repo connected as
+ * A wrote as B after `hs login --switch-account B`. Names `hs login --account A`.
+ */
+export class AccountTokenMissingError extends Error {
+  /** @param {string} accountId the account the repo records */
+  constructor(accountId) {
+    super(
+      `This repo is connected under HeySpex account ${accountId} (its heyspex.yaml \`account:\`), `
+        + 'but this machine holds no sign-in for that account, so the console call was refused before it was sent. '
+        + `Run \`${hsCommand(`login --account ${accountId}`)}\` to sign in as it, then try again. `
+        + 'Nothing was sent, and the current account was NOT used in its place.',
+    );
+    this.name = 'AccountTokenMissingError';
+    this.code = ACCOUNT_TOKEN_MISSING;
+    this.accountId = accountId;
+  }
+}
+
+// `account:` line of a repo's heyspex.yaml — the account `hs connect` recorded
+// the repo under. Same line-anchored shape as {@link MARKER_VAULT_ID_RE} and
+// as init.ts `parseAccountId` / install-identity.ts `parseMarkerAccount`.
+const MARKER_ACCOUNT_RE = /^account:[ \t]*["']?([^"'\r\n#]+)/m;
+
+/**
+ * The `account` a repo's `heyspex.yaml` records, or `null` (no marker, no
+ * key, unreadable). Never throws. `readFile` is a test seam.
+ * @param {string | null | undefined} repoRootAbs
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ */
+export function readMarkerAccount(repoRootAbs, { readFile } = {}) {
+  if (typeof repoRootAbs !== 'string' || !repoRootAbs.trim()) return null;
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  try {
+    const raw = read(join(repoRootAbs, 'heyspex.yaml'));
+    const value = String(raw ?? '').match(MARKER_ACCOUNT_RE)?.[1]?.trim() ?? '';
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The account THIS process's repo records: the resolver's root (memoized
+ * `getActiveConfig`) → its heyspex.yaml `account:`. Read per call, so an `hs
+ * connect` backfill is seen without a restart. `null` when the resolver
+ * fails or the marker records none (a legacy marker: the current account
+ * applies, unchanged).
+ * @returns {string | null}
+ */
+export function getRepoAccountId() {
+  let resolved;
+  try {
+    resolved = getActiveConfig();
+  } catch {
+    return null;
+  }
+  return readMarkerAccount(resolved?.repoRootAbs);
+}
+
 /**
  * Resolve the outbound `Authorization` header, or `{}` when no token
  * resolves (no header at all — matches today's unauthenticated behavior
  * against a local dev console). Precedence: `HEYSPEX_MCP_TOKEN` env →
- * `~/.heyspex/credentials.yaml` `mcp_token`. Injectable `env`/`homeDir` for
- * tests; never throws (an unreadable credentials file is just "no token").
+ * `~/.heyspex/credentials.yaml` — read by the ONE shared bearer reader
+ * (`./credentials.mjs`, [[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]]),
+ * never re-implemented here.
+ *
+ * Which stored token: the REPO's account when its heyspex.yaml records one
+ * (`repoAccountId`, default {@link getRepoAccountId}), else the current
+ * account ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]]). A recorded
+ * account with no stored token throws {@link AccountTokenMissingError} — never
+ * a silent fall back to the current account. Injectable `env`/`homeDir`/
+ * `repoAccountId` for tests (`null` = "the repo records none"); an unreadable
+ * 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;
+  const { token } = readBearer({ env, homeDir, accountId });
+  if (!token && accountId) throw new AccountTokenMissingError(accountId);
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/**
+ * VAULT SCOPING ([[HS-M95C]]): a cloud console scopes every request to the
+ * account's active-vault POINTER unless the request names a vault. The MCP
+ * server resolves its vault locally (vault-resolve.mjs, five tiers) but never
+ * put that id on the wire, so a session started in repo A read/wrote vault B.
+ *
+ * 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.
  */
-export function getAuthHeader({ env = process.env, homeDir = homedir() } = {}) {
-  const envToken = env.HEYSPEX_MCP_TOKEN?.trim();
-  if (envToken) return { Authorization: `Bearer ${envToken}` };
+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`. */
+export const ACCOUNT_ID_HEADER = 'x-heyspex-account-id';
 
+/** Local refusal: the cwd resolves to a root no registry row names. */
+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';
+
+/**
+ * Thrown by {@link vaultIdHeaderFor} / {@link getVaultIdHeader} when the
+ * resolver landed on the `unregistered` sentinel (`reason: 'unregistered'`),
+ * or on a registered row whose id is a LEGACY slug with no cloud UUID to
+ * stand in for it (`reason: 'legacy-id'`, see {@link cloudVaultIdFor}).
+ * `code` is stable for machine matching; the message names the resolved root
+ * and the runnable `hs connect` form for this machine.
+ */
+export class VaultNotRegisteredError extends Error {
+  /**
+   * @param {string | null | undefined} repoRootAbs the root the resolver settled on
+   * @param {string | null | undefined} source the resolver tier that produced it
+   * @param {{ reason?: 'unregistered' | 'legacy-id', legacyId?: string | null }} [detail]
+   */
+  constructor(repoRootAbs, source, { reason = 'unregistered', legacyId = null } = {}) {
+    const root = typeof repoRootAbs === 'string' && repoRootAbs.trim() ? repoRootAbs.trim() : null;
+    const where = root ? ` (${root})` : '';
+    // Names the verb (`hs connect`) AND the form that runs on this machine
+    // (`hsCommand`, [[HS-I6HT]]) — identical when the bin is on PATH.
+    const why =
+      reason === 'legacy-id'
+        ? `This repo${where} is registered on this machine under a legacy id (\`${legacyId}\`), not the vault id the console knows, and its heyspex.yaml carries no \`vault_id\` to stand in for it, `
+        : `This repo${where} is not connected to a HeySpex vault on this machine (\`hs connect\` has not registered it), `;
+    super(
+      why
+        + 'so the console call was refused before it was sent. '
+        + `Run \`${hsCommand('connect')}\`${root ? ` in ${root}` : ''} to ${reason === 'legacy-id' ? 're-register' : 'connect'} it, then try again. Nothing was sent.`,
+    );
+    this.name = 'VaultNotRegisteredError';
+    this.code = VAULT_NOT_REGISTERED;
+    this.reason = reason;
+    this.repoRootAbs = root;
+    this.source = typeof source === 'string' ? source : null;
+    this.legacyId = legacyId;
+  }
+}
+
+/** The shape of every vault id the console mints (`randomUUID()`); a registry row that is not one is a legacy slug. */
+const CLOUD_VAULT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isCloudVaultId(value) {
+  return typeof value === 'string' && CLOUD_VAULT_ID_RE.test(value.trim());
+}
+
+// `vault_id:` line of a repo's heyspex.yaml — the id the console minted and
+// `hs init` / `hs connect` wrote back ([[HS-6CFU-TASK-write-minted-vault-id-back-into-heyspex]]).
+// Same minimal line-anchored shape as session-owner.mjs's `account_id:` reader.
+const MARKER_VAULT_ID_RE = /^vault_id:[ \t]*["']?([^"'\r\n#]+)/m;
+
+/**
+ * The `vault_id` a repo's `heyspex.yaml` carries, or `null` (no marker, no
+ * key, unreadable). Never throws. `readFile` is a test seam.
+ * @param {string | null | undefined} repoRootAbs
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ */
+export function readMarkerVaultId(repoRootAbs, { readFile } = {}) {
+  if (typeof repoRootAbs !== 'string' || !repoRootAbs.trim()) return null;
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  try {
+    const raw = read(join(repoRootAbs, 'heyspex.yaml'));
+    const value = String(raw ?? '').match(MARKER_VAULT_ID_RE)?.[1]?.trim() ?? '';
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The id to put on the wire for a REGISTERED resolver result: the registry
+ * row's id when it is a cloud UUID; otherwise (a legacy slug row such as the
+ * pre-UUID `heyspex-specs` registration) the UUID the repo's `heyspex.yaml`
+ * `vault_id` names. The committed marker is a first-class routing fact now:
+ * the resolver's cwd tier already returns a marker's `vault_id` itself
+ * (`cwd-marker`, and `marker-registry-mismatch` when a registry row
+ * disagrees — the marker wins, [[HS-VVNQ]]), and its `account:` picks the
+ * token ({@link getAuthHeader}, [[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]]);
+ * this fallback covers the remaining tiers that land on a slug row. Neither a UUID →
+ * throws {@link VaultNotRegisteredError} (`reason: 'legacy-id'`): the console
+ * can only scope by the id it minted, and a slug on the wire is a guaranteed
+ * 409, so refusing locally is the honest answer.
+ * @param {{ vaultId: string, repoRootAbs?: string, source?: string }} resolved
+ * @param {{ readMarkerVaultId?: (repoRootAbs: string) => string | null }} [opts]
+ */
+export function cloudVaultIdFor(resolved, { readMarkerVaultId: readMarker = readMarkerVaultId } = {}) {
+  const rowId = resolved.vaultId.trim();
+  if (isCloudVaultId(rowId)) return rowId;
+  const marker = readMarker(resolved.repoRootAbs);
+  if (isCloudVaultId(marker)) return marker.trim();
+  throw new VaultNotRegisteredError(resolved.repoRootAbs, resolved.source, { reason: 'legacy-id', legacyId: rowId });
+}
+
+/**
+ * Thrown by {@link accountIdHeaderFor} / {@link getAccountIdHeader} when no
+ * account resolves (no `HS_ACCOUNT_ID`, no `account_id:` in
+ * `~/.heyspex/config.yaml`). Names `hs login`, the only thing that fixes it.
+ */
+export class AccountNotConfiguredError extends Error {
+  constructor() {
+    super(
+      'This machine has no HeySpex account configured (`hs login` has not been run), '
+        + 'so the console call was refused before it was sent. '
+        + `Run \`${hsCommand('login')}\` on this machine, then try again. Nothing was sent.`,
+    );
+    this.name = 'AccountNotConfiguredError';
+    this.code = ACCOUNT_NOT_CONFIGURED;
+  }
+}
+
+/** True for the two local scope refusals this module throws. */
+export function isLocalScopeRefusal(err) {
+  return err instanceof VaultNotRegisteredError || err instanceof AccountNotConfiguredError;
+}
+
+/**
+ * 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`.
+ * @param {{ vaultId?: string, source?: string, repoRootAbs?: string } | null | undefined} resolved
+ * @param {{ readMarkerVaultId?: (repoRootAbs: string) => string | null }} [opts]
+ */
+export function vaultIdHeaderFor(resolved, opts = {}) {
+  const vaultId = typeof resolved?.vaultId === 'string' ? resolved.vaultId.trim() : '';
+  if (!vaultId) return {};
+  if (vaultId === UNREGISTERED_VAULT_ID) {
+    throw new VaultNotRegisteredError(resolved?.repoRootAbs, resolved?.source);
+  }
+  return { [VAULT_ID_HEADER]: cloudVaultIdFor({ ...resolved, vaultId }, opts) };
+}
+
+/**
+ * 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.
+ */
+export function getVaultIdHeader() {
+  let resolved;
   try {
-    const raw = readFileSync(join(homeDir, '.heyspex', 'credentials.yaml'), 'utf8');
-    const match = raw.match(/^mcp_token:\s*["']?([^"'\r\n#]+)/m);
-    const token = match?.[1]?.trim();
-    if (token) return { Authorization: `Bearer ${token}` };
+    resolved = getActiveConfig();
   } catch {
-    // Missing file, missing key, or unreadable — no credentials-file token.
+    return {};
   }
-  return {};
+  return vaultIdHeaderFor(resolved);
+}
+
+/**
+ * Pure gate: the account header for a configured account id, or throws
+ * {@link AccountNotConfiguredError} when none is configured.
+ * @param {string | null | undefined} accountId
+ */
+export function accountIdHeaderFor(accountId) {
+  const id = typeof accountId === 'string' ? accountId.trim() : '';
+  if (!id) throw new AccountNotConfiguredError();
+  return { [ACCOUNT_ID_HEADER]: id };
+}
+
+/**
+ * The account-id header for THIS process: the repo's recorded `account:`
+ * when its heyspex.yaml names one — the account whose token
+ * {@link getAuthHeader} sends, so the two headers can never name different
+ * accounts ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]]) — else
+ * the one account reader (session-owner.mjs: `HS_ACCOUNT_ID` env, then the
+ * credentials store's current account). Read per call, like the bearer —
+ * `hs login` can re-pair the machine while a server is up. Injectable
+ * `env`/`homeDir`/`repoAccountId` for tests (`null` = "the repo records none").
+ * @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;
+  return accountIdHeaderFor(recorded || resolveSessionOwnerUncached(opts));
+}
+
+/**
+ * The transport result for a local scope refusal — the shape every caller of
+ * `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 {string} url the request that was NOT sent
+ */
+export function scopeRefusalResult(err, url) {
+  return {
+    ok: false,
+    status: 0,
+    body: null,
+    url,
+    error: err.message,
+    errorKind: 'refused',
+    refusal: err.code,
+    authProblem: err.code,
+    authMessage: err.message,
+  };
+}
+
+/** Cloud mode, but the resolved console URL points at this machine. */
+export const CONSOLE_LOCAL_URL_IN_CLOUD_MODE = 'CONSOLE_LOCAL_URL_IN_CLOUD_MODE';
+/** Cloud mode, but no bearer token is stored on this machine (or a 401 came back). */
+export const CONSOLE_NOT_SIGNED_IN = 'CONSOLE_NOT_SIGNED_IN';
+
+/**
+ * Plain-language, action-naming text for the two sign-in classes. Written for
+ * the repo owner to read directly: short sentences, no jargon, the exact
+ * command to run, and an explicit "do not start a local server" so an agent
+ * does not fall back to `npm run dev` — a customer has no local server.
+ *
+ * The command is rendered by `hsCommand`, never typed out, so the message
+ * names a form that actually runs on the machine reading it
+ * ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+ */
+export function consoleAuthErrorMessage(code, url) {
+  const where = url ? ` (${url})` : '';
+  const login = hsCommand('login');
+  if (code === CONSOLE_LOCAL_URL_IN_CLOUD_MODE) {
+    return (
+      `HeySpex is set to cloud mode, but this machine is pointed at a local console${where}. `
+      + `Nothing was saved. Run \`${login}\` to point this machine at the HeySpex cloud, then try again. `
+      + 'Do not start a local dev server — cloud is the normal mode.'
+    );
+  }
+  if (code === CONSOLE_NOT_SIGNED_IN) {
+    return (
+      `This machine is not signed in to HeySpex, so the call${url ? ` to ${url}` : ''} could not go through. `
+      + `Nothing was saved. Run \`${login}\` on this machine, then try again. `
+      + 'The server is not down — do not start a local dev server.'
+    );
+  }
+  return null;
+}
+
+/** Message for an answered HTTP 401 (the console replied; it rejected the token). */
+export function consoleUnauthorizedMessage(url) {
+  const where = url ? ` at ${url}` : '';
+  return (
+    `HeySpex${where} rejected this request because this machine is not signed in (HTTP 401). `
+    + `Nothing was saved. Run \`${hsCommand('login')}\` on this machine, then try again.`
+  );
+}
+
+/**
+ * Lazy, cached, never-throwing load of the shared dev/prod mode core. Kept
+ * dynamic (and optional) so a vendored copy of this directory without the
+ * repo's `scripts/` tree simply falls back to today's behavior instead of
+ * failing to import. Mirrors cli.mjs's handleDevMode self-containment note.
+ */
+let devModeCorePromise;
+async function loadDevModeCore() {
+  if (!devModeCorePromise) {
+    devModeCorePromise = import('../../scripts/lib/dev-mode.mjs').catch(() => null);
+  }
+  return devModeCorePromise;
+}
+
+/**
+ * Resolve the effective reliance ("cloud" | "local"), or `null` when it cannot
+ * be determined (no dev-mode core available). Never reimplements the contract:
+ * `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() } = {}) {
+  const core = await loadDevModeCore();
+  if (!core) return null;
+  try {
+    if (typeof core.resolveDevMode === 'function') {
+      return core.resolveDevMode({ env, homeDir }).reliance ?? null;
+    }
+    const { record } = core.readLocalDevModeRecord({ homeDir });
+    const mode = record?.mode ?? 'prod';
+    return core.deriveSemantics(mode, record?.reliance ?? null).reliance ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide whether a transport failure is really a sign-in problem. Pure.
+ *
+ * @param {{ url: string, reliance: string|null, hasToken: boolean }} state
+ * @returns {string|null} one of the two auth codes, or null (= genuine outage)
+ */
+export function classifyConsoleAuthProblem({ url, reliance, hasToken }) {
+  if (reliance !== 'cloud') return null; // local dev / unknown → today's behavior
+  if (isLoopbackUrl(url)) return CONSOLE_LOCAL_URL_IN_CLOUD_MODE;
+  if (!hasToken) return CONSOLE_NOT_SIGNED_IN;
+  return null;
+}
+
+function headerHasToken(header) {
+  const value = header?.Authorization;
+  return typeof value === 'string' && value.trim().length > 0;
 }
 
 /**
@@ -129,6 +587,9 @@ export function getAuthHeader({ env = process.env, homeDir = homedir() } = {}) {
  * @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.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}).
  */
 export function makeConsoleFetch({
   getConsoleUrl,
@@ -136,7 +597,72 @@ export function makeConsoleFetch({
   defaultTimeoutMs = DEFAULT_CONSOLE_TIMEOUT_MS,
   recoverFromTransportFailure,
   getAuthHeader: getAuthHeaderDep = getAuthHeader,
+  getVaultIdHeader: getVaultIdHeaderDep = getVaultIdHeader,
+  getAccountIdHeader: getAccountIdHeaderDep = getAccountIdHeader,
+  getConsoleAuthState,
 }) {
+  function safeAuthHeader() {
+    try {
+      return getAuthHeaderDep() || {};
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * One header resolver, two policies. A resolver that throws a local scope
+   * refusal ({@link isLocalScopeRefusal}) is surfaced as `{ refusal }` for a
+   * vault-scoped endpoint and swallowed to `{}` for a vault-less one; any
+   * OTHER throw is "no header" either way (a broken resolver must not become
+   * a new failure mode — unchanged from before).
+   */
+  function headerOrRefusal(resolveHeader, vaultLess) {
+    try {
+      return { headers: resolveHeader() || {} };
+    } catch (err) {
+      if (!vaultLess && isLocalScopeRefusal(err)) return { refusal: err };
+      return { headers: {} };
+    }
+  }
+
+  /**
+   * The `{ account, vault }` scope headers for one request, or the local
+   * refusal that stops it before any fetch. Vault-less endpoints never refuse.
+   * @returns {{ headers: object } | { refusal: Error }}
+   */
+  function scopeHeadersFor(method, path) {
+    const vaultLess = isVaultLessEndpoint(method, path);
+    const vault = headerOrRefusal(getVaultIdHeaderDep, vaultLess);
+    if (vault.refusal) return vault;
+    const account = headerOrRefusal(getAccountIdHeaderDep, vaultLess);
+    if (account.refusal) return account;
+    return { headers: { ...vault.headers, ...account.headers } };
+  }
+
+  /**
+   * The Authorization header for one request, or the local refusal that stops
+   * it: a repo that records an account this machine holds no token for
+   * ({@link AccountTokenMissingError}) refuses EVERY console call, vault-less
+   * ones included — sending no token, or the current account's, would both be
+   * wrong. Any other throw is "no header" (unchanged).
+   * @returns {{ headers: object } | { refusal: Error }}
+   */
+  function authOrRefusal() {
+    try {
+      return { headers: getAuthHeaderDep() || {} };
+    } catch (err) {
+      if (err instanceof AccountTokenMissingError) return { refusal: err };
+      return { headers: {} };
+    }
+  }
+
+  const resolveAuthState =
+    getConsoleAuthState
+    || (async () => ({
+      reliance: await resolveConsoleReliance(),
+      hasToken: headerHasToken(safeAuthHeader()),
+    }));
+
   async function attempt(url, init, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -149,7 +675,14 @@ export function makeConsoleFetch({
       } catch {
         parsed = { raw: text };
       }
-      return { ok: response.ok, status: response.status, body: parsed, url };
+      const retryAfterRaw = response.headers?.get?.('retry-after');
+      return {
+        ok: response.ok,
+        status: response.status,
+        body: parsed,
+        url,
+        ...(retryAfterRaw != null && retryAfterRaw !== '' ? { retryAfterSeconds: retryAfterRaw } : {}),
+      };
     } catch (err) {
       const errorKind = isAbortError(err) ? 'timeout' : 'network';
       return {
@@ -244,15 +777,52 @@ export function makeConsoleFetch({
     return result;
   }
 
+  /**
+   * Last word on a status-0 failure: was the console really down, or were we
+   * talking to the wrong console / with no sign-in? Runs only AFTER every
+   * recovery path has failed, so a genuinely recoverable local dev server
+   * still heals exactly as before ([[HS-9R6S-N8VP-DIAG]]).
+   */
+  async function stampAuthProblem(result, url) {
+    let state;
+    try {
+      state = await resolveAuthState({ url });
+    } catch {
+      return result; // never let classification turn into a new failure mode
+    }
+    const authProblem = classifyConsoleAuthProblem({
+      url: result.url || url,
+      reliance: state?.reliance ?? null,
+      hasToken: state?.hasToken === true,
+    });
+    if (!authProblem) return result;
+    return {
+      ...result,
+      authProblem,
+      reliance: state?.reliance ?? null,
+      authMessage: consoleAuthErrorMessage(authProblem, result.url || url),
+    };
+  }
+
   async function withRetry(url, init, timeoutMs, { retryOnTimeout = true } = {}) {
     let result = await attempt(url, init, timeoutMs);
     if (!result.ok && result.errorKind === 'timeout' && retryOnTimeout) {
       result = await attempt(url, init, timeoutMs);
     }
+    // Cold cloud lambda: wait the advertised window, then the same URL once more.
+    if (!result.ok && isVaultScopeUnresolved(result)) {
+      await sleep(retryAfterMs(result));
+      const retry = await attempt(url, init, timeoutMs);
+      if (retry.ok) return { ...retry, recoveredVia: 'vault_scope_unresolved', attemptedUrl: url };
+      result = retry;
+    }
     if (result.ok) return result;
     if (result.errorKind === 'network') {
       result = await recoverNetworkFailure(result, { url, init, timeoutMs });
     }
+    if (!result.ok && result.status === 0) {
+      result = await stampAuthProblem(result, url);
+    }
     return result;
   }
 
@@ -261,10 +831,15 @@ export function makeConsoleFetch({
    */
   async function postClaimEndpoint(method, specId, bodyJson) {
     const consoleUrl = getConsoleUrl();
-    const url = `${consoleUrl}/api/specs/${encodeURIComponent(specId)}/claim`;
+    const path = `/api/specs/${encodeURIComponent(specId)}/claim`;
+    const url = `${consoleUrl}${path}`;
+    const auth = authOrRefusal();
+    if (auth.refusal) return scopeRefusalResult(auth.refusal, url);
+    const scope = scopeHeadersFor(method, path);
+    if (scope.refusal) return scopeRefusalResult(scope.refusal, url);
     const init = {
       method,
-      headers: { 'content-type': 'application/json', ...getAuthHeaderDep() },
+      headers: { 'content-type': 'application/json', ...auth.headers, ...scope.headers },
     };
     if (bodyJson !== undefined) {
       init.body = JSON.stringify(bodyJson);
@@ -287,9 +862,19 @@ export function makeConsoleFetch({
   async function consoleFetch(path, options = {}) {
     const consoleUrl = getConsoleUrl();
     const url = `${consoleUrl}${path}`;
+    const method = options.method || 'GET';
+    const auth = authOrRefusal();
+    if (auth.refusal) return scopeRefusalResult(auth.refusal, url);
+    const scope = scopeHeadersFor(method, path);
+    if (scope.refusal) return scopeRefusalResult(scope.refusal, url);
     const init = {
-      method: options.method || 'GET',
-      headers: { 'content-type': 'application/json', ...getAuthHeaderDep(), ...options.headers },
+      method,
+      headers: {
+        'content-type': 'application/json',
+        ...auth.headers,
+        ...scope.headers,
+        ...options.headers,
+      },
     };
     if (options.body !== undefined) {
       init.body = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
@@ -308,7 +893,51 @@ export function makeConsoleFetch({
  * actually down). Caller supplies the HTTP-error fallback used when the
  * transport succeeded but the console returned a 4xx/5xx.
  */
+/**
+ * The console's three TYPED vault-scope refusals
+ * ([[HS-T5J5-WW9R-TASK-typed-vault-refusals-vault-not]]), one envelope
+ * `{ error, reason, requested, hint }`. They name WHICH vault was refused and
+ * why; the `hint` names the account's active vault when it is known. The
+ * transport renders them by name so an agent reads two vault ids, not a bare
+ * status ([[HS-N0VS-WW9R-TASK-hs-doctor-and-the-mcp-transport-name]] for
+ * [[HS-W3JF-PEGM-DIAG-one-account-wide-active-vault-pointer]] fix 3).
+ */
+export const SCOPE_REFUSAL_CODES = Object.freeze(['VAULT_SCOPE_MISMATCH', 'ACCOUNT_MISMATCH', 'VAULT_NOT_REGISTERED']);
+
+/** The typed refusal envelope on a failed transport result, or `null`. Pure. */
+export function scopeRefusalEnvelope(result) {
+  const body = result?.body;
+  if (!body || typeof body !== 'object' || !SCOPE_REFUSAL_CODES.includes(body.error)) return null;
+  return body;
+}
+
+/**
+ * Agent-facing text for a typed refusal: code, reason, the vault the request
+ * named, and the console's hint (which carries the account's active vault when
+ * known) — the "both vaults side by side" the incident lacked. Pure.
+ */
+export function scopeRefusalMessage(envelope, url) {
+  const where = url ? ` from ${url}` : '';
+  const reason = typeof envelope.reason === 'string' && envelope.reason ? envelope.reason : 'no reason given';
+  const requested =
+    typeof envelope.requested === 'string' && envelope.requested
+      ? `vault ${envelope.requested}`
+      : `no vault (no \`${VAULT_ID_HEADER}\` header)`;
+  const hint = typeof envelope.hint === 'string' && envelope.hint ? ` ${envelope.hint}` : '';
+  return `${envelope.error} (${reason})${where}: this request named ${requested}.${hint}`.trim();
+}
+
 export function consoleErrorCode(result, httpFailureCode) {
+  // A local scope refusal never reached the wire: the code IS the answer.
+  if (result.refusal) return result.refusal;
+  // A sign-in problem outranks every transport story: no amount of retrying,
+  // port discovery or waiting fixes it, and "the server is down" sends the
+  // agent off to start a local dev server the customer does not have.
+  if (result.authProblem) return result.authProblem;
+  // A typed vault-scope refusal IS the code — never the caller's generic one.
+  const scoped = scopeRefusalEnvelope(result);
+  if (scoped) return scoped.error;
+  if (result.status === 401) return CONSOLE_NOT_SIGNED_IN;
   if (result.urlMismatch) return 'CONSOLE_URL_MISMATCH';
   if (result.errorKind === 'timeout') return 'CONSOLE_TIMEOUT';
   if (result.status === 0) return 'CONSOLE_UNREACHABLE';
@@ -321,6 +950,18 @@ export function consoleErrorCode(result, httpFailureCode) {
  * server on network error.
  */
 export function consoleErrorMessage(result, httpFailureMessage) {
+  if (result.refusal) return result.error || result.authMessage || httpFailureMessage;
+  if (result.authProblem) {
+    return (
+      result.authMessage
+      || consoleAuthErrorMessage(result.authProblem, result.url)
+      || httpFailureMessage
+    );
+  }
+  // A typed vault-scope refusal names both vaults; the generic text names none.
+  const scoped = scopeRefusalEnvelope(result);
+  if (scoped) return scopeRefusalMessage(scoped, result.url);
+  if (result.status === 401) return consoleUnauthorizedMessage(result.url);
   if (result.urlMismatch) {
     const live =
       result.suggestedUrl