heyspex 0.2.0 → 0.2.1

package/vendor/heyspex-mcp/promote-capture.mjs

@@ -333,6 +333,7 @@ function findResearchByIdLocal(vaultRoot, researchId) {
  */
 async function findCaptureByIdViaTier(vaultRoot, captureId, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findCaptureByIdLocal(vaultRoot, captureId),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, captureId),
@@ -347,6 +348,7 @@ async function findCaptureByIdViaTier(vaultRoot, captureId, { tier, consoleUrl,
  */
 async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, researchId),

package/vendor/heyspex-mcp/promote-research.mjs

@@ -217,6 +217,7 @@ function findResearchByIdLocal(vaultRoot, researchId) {
  */
 async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
     neonRead: async () => {
@@ -274,6 +275,7 @@ function findMilestoneById(vaultRoot, milestoneId) {
  */
 async function findMilestoneByBasenameViaTier(vaultRoot, basename, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findMilestoneByBasename(vaultRoot, basename),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, basename),
@@ -288,6 +290,7 @@ async function findMilestoneByBasenameViaTier(vaultRoot, basename, { tier, conso
  */
 async function findMilestoneByIdViaTier(vaultRoot, milestoneId, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findMilestoneById(vaultRoot, milestoneId),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, milestoneId),
@@ -334,6 +337,7 @@ function findEpicByIdOrBasename(vaultRoot, idOrBasename) {
  */
 async function findEpicByIdOrBasenameViaTier(vaultRoot, idOrBasename, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findEpicByIdOrBasename(vaultRoot, idOrBasename),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, idOrBasename),
@@ -437,6 +441,7 @@ async function resolvePillarViaTier(vaultRoot, raw, { tier, consoleUrl, consoleF
   const basename = normalizePillarRef(raw);
   if (!basename) return { ok: false };
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => resolvePillar(vaultRoot, raw),
     neonRead: async () => {
@@ -1004,6 +1009,7 @@ async function resolveOwnerIntentViaTier(vaultRoot, researchRaw, { tier, console
       let raw;
       try {
         raw = await readViaSelector({
+    allowDiskFallback: false,
           tier,
           diskRead: () => {
             const capturesDir = join(vaultRoot, 'specs', 'captures');

package/vendor/heyspex-mcp/read-path.mjs

@@ -46,6 +46,9 @@
  * import) so tests can stub scripts/lib/dev-mode.mjs and prove the verdict
  * comes from `resolveDevMode` itself, not from string-matching this file.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { importDevModeCore } from './dev-mode-core.mjs';
 // THIS PACKAGE's own root (vendor/heyspex-mcp/read-path.mjs -> two levels
@@ -97,6 +100,27 @@ export class ConsoleUnreachableCloudModeError extends Error {
   }
 }
 
+/**
+ * `{ degraded:true, source:'cloud', warning }` when the resolved vault is a
+ * satellite binding whose vault clone is absent on this machine (marker with
+ * vault_path, no clone), else null. Same record shape as the outage fallback.
+ */
+export function vaultNotClonedInfo() {
+  try {
+    const cfg = getActiveConfig();
+    if (cfg && cfg.vaultCloned === false) {
+      return {
+        degraded: true,
+        source: 'cloud',
+        warning: `vault ${cfg.vaultId} is bound by this repo's heyspex.yaml but is not cloned at ${cfg.vaultPath ?? 'its vault_path'} on this machine; answered from the cloud (cloud-only mode). Clone the vault repo there for local reads.`,
+      };
+    }
+  } catch {
+    /* resolver failure: not a clone problem */
+  }
+  return null;
+}
+
 /**
  * resolveReadTier({ env, homeDir, loadDevMode? }) -> "disk" | "neon"
  *
@@ -132,23 +156,155 @@ export async function resolveVaultWriteMode({ env, homeDir, loadDevMode = loadRe
 }
 
 /**
- * readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl })
+ * A console read that failed, carrying the transport verdict so
+ * {@link readViaSelector} can tell an OUTAGE (status 0, 5xx, timeout/network)
+ * from an ANSWER (401/403/404/409). Thrown by the `neonRead` closures; build
+ * one from a consoleFetch result with {@link consoleReadErrorFrom}.
+ */
+export class ConsoleReadError extends Error {
+  constructor(message, { status, errorKind, route } = {}) {
+    super(message);
+    this.name = 'ConsoleReadError';
+    this.status = status;
+    this.errorKind = errorKind;
+    this.route = route;
+  }
+}
+
+/** Build a {@link ConsoleReadError} from a consoleFetch result `{status, errorKind}`. */
+export function consoleReadErrorFrom(res, message, route) {
+  const e = new ConsoleReadError(message, { status: res?.status, errorKind: res?.errorKind, route });
+  if (res?.authProblem || res?.refusal) e.authProblem = true;
+  return e;
+}
+
+/**
+ * True when `err` says the console was unreachable or broken (status 0, any
+ * 5xx, errorKind timeout/abort/network). False for answered 4xx verdicts
+ * (401/403/404/409) and for anything unclassified.
+ */
+export function isOutageClass(err) {
+  if (!err || typeof err !== 'object') return false;
+  if (err.authProblem) return false; // sign-in / scope refusals are not outages
+  const { status, errorKind } = err;
+  if (errorKind === 'timeout' || errorKind === 'abort' || errorKind === 'network') return true;
+  if (typeof status === 'number' && (status === 0 || status >= 500)) return true;
+  return false;
+}
+
+// Per-call collector so callers whose reader returns a non-object (Set, array,
+// null) can still learn that the answer came from the local clone.
+const degradationScope = new AsyncLocalStorage();
+
+/**
+ * Run `fn`, collecting a {@link readViaSelector} degradation record for every
+ * disk-fallback read made inside it. Resolves `{ value, degraded }` where
+ * `degraded` is null or `{ degraded:true, source:'disk', cloud_error, warning }`.
+ */
+export async function withDegradationScope(fn) {
+  const records = [];
+  const value = await degradationScope.run(records, fn);
+  return { value, degraded: records[0] ?? null };
+}
+
+function lastCommitIso(root) {
+  try {
+    const out = execFileSync('git', ['-C', root, 'log', '-1', '--format=%cI'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000,
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stamp a degradation record onto a reader's result. Plain objects get the
+ * fields spread in; an MCP tool result (`{content:[{type:'text',text:<json>}]}`)
+ * gets them merged into the JSON payload inside `text` (and spread on the
+ * envelope too); any other shape (Set/array/null/primitive) is returned
+ * unchanged — it rides the {@link withDegradationScope} collector instead.
+ */
+export function mergeDegradation(result, info) {
+  if (!isPlainObject(result) || !info) return result;
+  const first = Array.isArray(result.content) ? result.content[0] : null;
+  if (first && first.type === 'text' && typeof first.text === 'string') {
+    try {
+      const parsed = JSON.parse(first.text);
+      if (isPlainObject(parsed)) {
+        return { ...result, ...info, content: [{ ...first, text: JSON.stringify({ ...parsed, ...info }, null, 2) }, ...result.content.slice(1)] };
+      }
+    } catch {
+      /* not JSON — fall through to the envelope spread */
+    }
+  }
+  return { ...result, ...info };
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+
+/**
+ * readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl, vaultRoot?, allowDiskFallback? })
  *
  * Runs the read matching `tier`:
  *   - "disk": calls `diskRead()` (`neonRead` is never invoked).
- *   - "neon": calls `neonRead()`. On failure, wraps the error into a plain
- *     {@link ConsoleUnreachableCloudModeError} naming `consoleUrl` and
- *     `routeLabel`; `diskRead` is never called (no silent local fallback
- *     out of cloud reliance).
+ *   - "neon": calls `neonRead()`. On failure:
+ *       * DEGRADE ("degrade, don't die"): when `diskRead` exists, the failure
+ *         is outage-class ({@link isOutageClass}), a local clone exists
+ *         (`<vaultRoot>/specs`), and HEYSPEX_NO_DISK_FALLBACK !== '1', answer
+ *         from `diskRead()`. A plain-object result is returned spread with
+ *         `degraded: true, source: 'disk', cloud_error, warning`; any other
+ *         shape (Set/array/null) is returned unchanged and the same record is
+ *         pushed to the active {@link withDegradationScope} collector.
+ *       * otherwise wraps the error into {@link ConsoleUnreachableCloudModeError}
+ *         naming `consoleUrl` and `routeLabel` (4xx, no clone, no diskRead,
+ *         opt-out env, or `allowDiskFallback: false` for write preconditions).
  */
-export async function readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl }) {
+export async function readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl, vaultRoot, allowDiskFallback = true }) {
+  // A satellite whose marker names a vault that is not cloned here is
+  // CLOUD-ONLY: a disk read would silently answer empty. Serve the cloud read
+  // (when this read has one) and declare it - never a silent empty answer.
+  const uncloned = vaultNotClonedInfo();
+  if (uncloned && typeof neonRead === 'function') {
+    const result = await neonRead();
+    const store = degradationScope.getStore();
+    if (store) store.push(uncloned);
+    return mergeDegradation(result, uncloned);
+  }
   if (tier === 'disk') {
+    if (uncloned) {
+      throw new ConsoleUnreachableCloudModeError(
+        `VAULT_NOT_CLONED_LOCALLY: route "${routeLabel}" has no cloud read and ${uncloned.warning}`,
+      );
+    }
     return diskRead();
   }
   if (tier === 'neon') {
     try {
       return await neonRead();
     } catch (err) {
+      const root = vaultRoot ?? resolveVaultRoot();
+      if (
+        allowDiskFallback &&
+        typeof diskRead === 'function' &&
+        isOutageClass(err) &&
+        process.env.HEYSPEX_NO_DISK_FALLBACK !== '1' &&
+        root && existsSync(join(root, 'specs'))
+      ) {
+        const result = await diskRead();
+        const kind = err.status ? `HTTP ${err.status}` : (err.errorKind ?? 'unreachable');
+        const info = {
+          degraded: true,
+          source: 'disk',
+          cloud_error: String(err?.message ?? err),
+          warning: `Console ${consoleUrl} failed (${kind}); answered from the local clone at ${root} (last commit ${lastCommitIso(root)}). Writes still require the console.`,
+        };
+        const store = degradationScope.getStore();
+        if (store) store.push(info);
+        return mergeDegradation(result, info);
+      }
       throw new ConsoleUnreachableCloudModeError(
         `CONSOLE_UNREACHABLE_CLOUD_MODE: route "${routeLabel}" failed against console ${consoleUrl} — ${String(err?.message ?? err)}`,
       );

package/vendor/heyspex-mcp/request-context.mjs

@@ -18,7 +18,7 @@
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-/** @typedef {{ consoleUrl?: string, authHeader?: Record<string, string> }} RequestContext */
+/** @typedef {{ consoleUrl?: string, authHeader?: Record<string, string>, vaultId?: string }} RequestContext */
 
 const storage = new AsyncLocalStorage();
 
@@ -57,3 +57,27 @@ export function contextAuthHeader() {
   const header = storage.getStore()?.authHeader;
   return header && typeof header === 'object' ? header : undefined;
 }
+
+/**
+ * Outbound `x-heyspex-vault-id` for the active request, or `undefined` outside
+ * any request context (the stdio server then resolves the repo-bound vault
+ * from its cwd). INSIDE a context the answer is ALWAYS an object: the caller's
+ * own vault header, or `{}` when it sent none. It is never the server
+ * process's own vault (a shared serverless runtime has none), and never the
+ * account-wide active pointer: a bearer call that names no vault is refused by
+ * the console (`vault-scope-required`). Owner principles P1/P2/P3, 2026-10-16.
+ */
+export function contextVaultIdHeader() {
+  const store = storage.getStore();
+  if (!store) return undefined;
+  const id = typeof store.vaultId === 'string' ? store.vaultId.trim() : '';
+  return id ? { 'x-heyspex-vault-id': id } : {};
+}
+
+/**
+ * Outbound `x-heyspex-account-id` for the active request: always `{}` inside a
+ * context (the forwarded credential IS the account), `undefined` outside.
+ */
+export function contextAccountIdHeader() {
+  return storage.getStore() ? {} : undefined;
+}

package/vendor/heyspex-mcp/research-handlers.mjs

@@ -14,7 +14,7 @@ import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
 import { randomUUID } from 'node:crypto';
 import { basename, join, relative, isAbsolute, resolve, sep } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { readViaSelector, resolveReadTier, resolveVaultWriteMode } from './read-path.mjs';
+import { consoleReadErrorFrom, readViaSelector, resolveReadTier, resolveVaultWriteMode, withDegradationScope } from './read-path.mjs';
 import { detectAgentIdentity, getConsoleUrl } from './mcp-config.mjs';
 import { collectOccupiedKeysEitherKind, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
@@ -318,8 +318,9 @@ export async function handleSaveResearch(vaultRoot, args) {
   const tier = await resolveReadTier();
   const consoleUrl = getConsoleUrl();
   let occupiedResearch;
+  let occupiedDegraded = null;
   try {
-    occupiedResearch = await readViaSelector({
+    ({ value: occupiedResearch, degraded: occupiedDegraded } = await withDegradationScope(() => readViaSelector({
       tier,
       diskRead: () => {
         const existingFiles = readdirSync(researchDir).filter(f => f.endsWith('.md') && !f.endsWith('.review.md'));
@@ -343,13 +344,13 @@ export async function handleSaveResearch(vaultRoot, args) {
       neonRead: async () => {
         const res = await consoleFetch('/api/vault/occupied-ids?bucket=research');
         if (!res.ok) {
-          throw new Error(`GET /api/vault/occupied-ids?bucket=research returned ${res.status}: ${res.error || ''}`);
+          throw consoleReadErrorFrom(res, `GET /api/vault/occupied-ids?bucket=research returned ${res.status}: ${res.error || ''}`, null);
         }
         return new Set(Array.isArray(res.body?.ids) ? res.body.ids : []);
       },
       routeLabel: 'GET /api/vault/occupied-ids?bucket=research',
       consoleUrl,
-    });
+    })));
   } catch (err) {
     return {
       isError: true,
@@ -445,6 +446,7 @@ ${bodyMarkdown}`;
   // the caller that research_type was not supplied so it defaulted, rather
   // than silently going unnoticed.
   if (researchTypeWasOmitted) attachResearchTypeWarning(result);
+  if (occupiedDegraded) result.degraded_warning = occupiedDegraded.warning;
 
   return {
     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],

package/vendor/heyspex-mcp/roadmap-default.mjs

@@ -0,0 +1,70 @@
+// Per-vault default roadmap resolution. The MCP used to hardcode the HeySpex
+// platform vault's roadmap id ('HS-ROADMAP-PRODUCT'), so every customer vault
+// (whose roadmap has a different id, e.g. the `hs init` starter
+// 'HS-START-ROADMAP') failed `heyspex_next_on_deck` with ROADMAP_NOT_FOUND.
+//
+// Precedence (explicit `roadmap_id` arg is applied by callers, above this):
+//   HEYSPEX_ROADMAP_ID env > the vault's own `type: roadmap` spec >
+//   'HS-ROADMAP-PRODUCT' (last resort).
+// Resolved per call from the vault root of THAT call: one MCP process can
+// serve several vaults, so nothing here is cached.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+
+export const PLATFORM_ROADMAP_ID = 'HS-ROADMAP-PRODUCT';
+
+const SCAN_DIRS = ['specs/roadmaps', 'specs/roadmap', 'specs'];
+
+function headFields(file) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return null;
+  const grab = (k) => {
+    const r = new RegExp('^' + k + ':[ \t]*(.+?)[ \t\r]*$', 'm').exec(m[1]);
+    return r ? r[1].replace(/^["']|["']$/g, '') : null;
+  };
+  return { type: grab('type'), id: grab('id') };
+}
+
+/** All `type: roadmap` spec ids found on disk under the vault's specs/. */
+export function listVaultRoadmapIds(vaultRoot) {
+  const ids = new Set();
+  if (!vaultRoot) return [];
+  for (const dir of SCAN_DIRS) {
+    const abs = join(vaultRoot, dir);
+    if (!existsSync(abs)) continue;
+    let names;
+    try {
+      names = readdirSync(abs);
+    } catch {
+      continue;
+    }
+    for (const n of names) {
+      if (!n.endsWith('.md')) continue;
+      const f = headFields(join(abs, n));
+      if (f && f.type === 'roadmap' && f.id) ids.add(f.id);
+    }
+  }
+  return [...ids].sort();
+}
+
+/**
+ * @returns {{ id: string, source: 'env'|'vault'|'vault-multiple'|'fallback', candidates?: string[] }}
+ */
+export function resolveDefaultRoadmap(vaultRoot, env = process.env) {
+  const fromEnv = env.HEYSPEX_ROADMAP_ID?.trim();
+  if (fromEnv) return { id: fromEnv, source: 'env' };
+  const ids = listVaultRoadmapIds(vaultRoot);
+  if (ids.length === 1) return { id: ids[0], source: 'vault' };
+  if (ids.length > 1) {
+    const id = ids.includes(PLATFORM_ROADMAP_ID) ? PLATFORM_ROADMAP_ID : ids[0];
+    return { id, source: 'vault-multiple', candidates: ids };
+  }
+  return { id: PLATFORM_ROADMAP_ID, source: 'fallback' };
+}

package/vendor/heyspex-mcp/session-owner.mjs

@@ -33,6 +33,7 @@
 // is spawned once per session; pairing changes restart it). Callers inject
 // `env` / `homeDir` / `readFile` for tests, which bypasses the cache.
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -45,7 +46,7 @@ const ACCOUNT_ID_LINE_RE = /^account_id:\s*["']?([^"'\r\n#]+)/m;
  * Read the paired account id from `~/.heyspex/config.yaml`, or null.
  * @param {{ homeDir?: string, readFile?: (p: string) => string }} [opts]
  */
-export function readConfigAccountId({ homeDir = homedir(), readFile } = {}) {
+export function readConfigAccountId({ homeDir = heyspexHome(), readFile } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
   try {
     const raw = read(join(homeDir, '.heyspex', 'config.yaml'));
@@ -62,7 +63,7 @@ export function readConfigAccountId({ homeDir = homedir(), readFile } = {}) {
  * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
  * @returns {string | null}
  */
-export function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir(), readFile } = {}) {
+export function resolveSessionOwnerUncached({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
   const fromEnv = typeof env?.HS_ACCOUNT_ID === 'string' ? env.HS_ACCOUNT_ID.trim() : '';
   if (fromEnv) return fromEnv;
   return readCurrentAccountId({ homeDir, readFile });

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

@@ -5,6 +5,8 @@
 import { consoleFetch } from './console-transport.mjs';
 import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
 import { detectAgentIdentity } from './mcp-config.mjs';
+import { resolveReadTier } from './read-path.mjs';
+import { deferControlWrite } from './write-outbox.mjs';
 
 /**
  * Import a community agent role via console `POST /api/agents/import` — the MCP
@@ -85,6 +87,14 @@ export async function handleHandoffRecord(args = {}) {
     body,
   });
   if (!result.ok) {
+    const deferred = await deferControlWrite(result, {
+      route: '/api/control/handoff-context',
+      method: 'PUT',
+      request_body: body,
+      acting_agent: identity.agent,
+      session_id: identity.sessionId,
+    }, { isCloud: async () => (await resolveReadTier()) === 'neon' });
+    if (deferred) return deferred;
     const payload = {
       error: consoleErrorCode(result, 'HANDOFF_RECORD_FAILED'),
       message: consoleErrorMessage(result, `Handoff-context endpoint returned ${result.status}`),

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

@@ -8,7 +8,7 @@ import { detectTagDrift } from './plan-ground.mjs';
 import { consoleErrorMessage } from './console-fetch.mjs';
 import { detectAgentIdentity, getConsoleUrl } from './mcp-config.mjs';
 import { resolveVaultWriteMode } from './read-path.mjs';
-import { splitRawSpec, updateSpecViaConsole } from './cloud-vault-writes.mjs';
+import { deferredPayloadFromError, splitRawSpec, updateSpecViaConsole } from './cloud-vault-writes.mjs';
 import { writeFileSync } from 'node:fs';
 import { executeShipEpicCloudAware } from './plan-push.mjs';
 import { executeRegenTask, executeRegenTasksForEpic } from './regen-tasks.mjs';
@@ -168,6 +168,13 @@ export async function handleEditFile(args = {}, deps = {}) {
       });
     } catch (err) {
       await releaseClaim();
+      // Outage: the edit was queued to the write outbox (truthful receipt, not an error).
+      const deferred = deferredPayloadFromError(err);
+      if (deferred) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ ...deferred, file_path: args.file_path, spec_id: specId, write_mode: 'cloud', on_disk: false }, null, 2) }],
+        };
+      }
       return {
         isError: true,
         content: [{ type: 'text', text: JSON.stringify({

package/vendor/heyspex-mcp/split-research.mjs

@@ -438,6 +438,7 @@ function findCaptureByIdOrBasename(vaultRoot, ref) {
 
 async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, researchId),
@@ -448,6 +449,7 @@ async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl
 
 async function findMilestoneViaTier(vaultRoot, ref, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findMilestoneByIdOrBasename(vaultRoot, ref),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, ref),
@@ -458,6 +460,7 @@ async function findMilestoneViaTier(vaultRoot, ref, { tier, consoleUrl, consoleF
 
 async function findCaptureViaTier(vaultRoot, ref, { tier, consoleUrl, consoleFetch }) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => findCaptureByIdOrBasename(vaultRoot, ref),
     neonRead: () => fetchSpecRecordViaConsole(consoleFetch, ref),

package/vendor/heyspex-mcp/submit-for-review.mjs

@@ -6,6 +6,7 @@
  */
 
 import { extractSection, hasHeading, parseAcceptanceSubsections } from './alignment-gate.mjs';
+import { gatherCloseBranchReport } from './close-branch-report.mjs';
 import { readMvpModeState } from './mvp-mode.mjs';
 import { isBelowReviewLevel, reviewLevelForGrain } from './review-rollup.mjs';
 
@@ -142,7 +143,13 @@ function findClaimAcProgress(claimsBody, specId) {
 /**
  * @param {{ vaultRoot: string, consoleFetch: Function, postClaimEndpoint?: Function, args?: Record<string, unknown> }} ctx
  */
-export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClaimEndpoint, args = {} }) {
+export async function executeSubmitForReview({
+  vaultRoot,
+  consoleFetch,
+  postClaimEndpoint,
+  args = {},
+  gatherBranchReport = gatherCloseBranchReport,
+}) {
   const specId = typeof args.spec_id === 'string' ? args.spec_id.trim() : '';
   if (!specId) {
     return { error: 'INVALID_ARGS', message: 'spec_id is required' };
@@ -295,6 +302,16 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
     isReviewUnit: effectiveIsReviewUnit,
   });
 
+  // Name the branch each half of the session landed on, and whether they
+  // match ([[HS-PPX7-CWPX-TASK-session-close-names-the-branch-each]]).
+  // Best-effort: a failure here never blocks the close-out.
+  try {
+    const report = await gatherBranchReport({ consoleFetch });
+    guidance.branch_report = report;
+  } catch {
+    guidance.branch_report = { status: 'unknown', matches: false, lines: ['Branch report unavailable.'] };
+  }
+
   return {
     spec_id: specId,
     requested_status: 'in_review',

package/vendor/heyspex-mcp/summary-write-tools.mjs

@@ -27,7 +27,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { updateSpecViaConsole } from './cloud-vault-writes.mjs';
+import { deferredPayloadFromError, updateSpecViaConsole } from './cloud-vault-writes.mjs';
 import { consoleFetch, controlOk } from './console-transport.mjs';
 import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
 import { getConsoleUrl } from './mcp-config.mjs';
@@ -157,6 +157,10 @@ export async function handleAuthorSummary(vaultRoot, args = {}, deps = {}) {
     try {
       written = await updateSpecViaConsole({ consoleFetch: fetchDep, consoleUrl, specId: rowId, frontmatter, body });
     } catch (err) {
+      const deferred = deferredPayloadFromError(err);
+      if (deferred) {
+        return controlOk({ ...deferred, written: false, spec_id: rowId, summary, write_mode: 'cloud', on_disk: false });
+      }
       return errorResult({
         error: err?.notFound ? 'SPEC_NOT_FOUND' : 'CONSOLE_UNREACHABLE_CLOUD_MODE',
         message: String(err?.message ?? err),

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

@@ -22,7 +22,15 @@ import { resetActiveConfigCache } from './vault-resolve.mjs';
  *   - a temp HOME (`HOME` + `USERPROFILE`, what `os.homedir()` reads) holding
  *     `~/.heyspex/registry.json` with the roots the test names,
  *   - `HS_ACCOUNT_ID` (tier 1 of session-owner.mjs) as the configured account,
- *   - optionally `HEYSPEX_VAULT_ROOT` pointed at a registered root.
+ *   - optionally `HEYSPEX_VAULT_ROOT` pointed at a registered root,
+ *   - `CLAUDE_PROJECT_DIR` (the resolver's cwd base) pointed at that root —
+ *     or at the temp home when none is given — so the resolver's walk starts
+ *     inside the fixture and never climbs through the ambient checkout. The
+ *     walk (tier 2) outranks `HEYSPEX_VAULT_ROOT` (tier 3, [[HS-VVNQ]]), so a
+ *     satellite pin in the repo the suite is run FROM (heyspex-app's own
+ *     `.mcp.json` since 2026-10-10) would otherwise silently replace the
+ *     root a test pinned, and the machine's registry pointer (tier 4) would
+ *     otherwise answer for a test that pinned nothing.
  *
  * `registerRoot(root)` adds a row for a root a test mints later (its own temp
  * vault) and resets the memoized resolver so the next request sees it. Call
@@ -42,10 +50,12 @@ export function installScopedConsoleEnv({
   repoRootAbs,
   activeVaultId,
 } = {}) {
-  const ENV_KEYS = ['HOME', 'USERPROFILE', 'HS_ACCOUNT_ID', 'HEYSPEX_VAULT_ROOT'];
+  const ENV_KEYS = ['HOME', 'USERPROFILE', 'HS_ACCOUNT_ID', 'HEYSPEX_VAULT_ROOT', 'CLAUDE_PROJECT_DIR', 'HEYSPEX_MCP_TOKEN'];
   const saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
   const home = mkdtempSync(join(tmpdir(), 'hs-scoped-home-'));
-  const registryDir = join(home, '.heyspex');
+  // The registry lives under the HeySpex home: HEYSPEX_HOME when a test set one, else the scoped HOME.
+  const registryHome = process.env.HEYSPEX_HOME?.trim() || home;
+  const registryDir = join(registryHome, '.heyspex');
   mkdirSync(registryDir, { recursive: true });
   const registryPath = join(registryDir, 'registry.json');
   // Registry schema v2 (HS-RXLG): the pointer is the signed-in account's row.
@@ -77,6 +87,11 @@ export function installScopedConsoleEnv({
   process.env.HOME = home;
   process.env.USERPROFILE = home;
   process.env.HS_ACCOUNT_ID = accountId;
+  // The scoped registry row is bound to this account (machine-local binding), so the
+  // machine must hold a sign-in for it; an env bearer stands in for the credentials file.
+  process.env.HEYSPEX_MCP_TOKEN ||= 'hsmcp_scoped_test_token';
+  // Fence the resolver's walk inside the fixture (see the doc comment above).
+  process.env.CLAUDE_PROJECT_DIR = repoRootAbs ?? home;
   if (repoRootAbs) {
     registerRoot(repoRootAbs, vaultId);
     process.env.HEYSPEX_VAULT_ROOT = repoRootAbs;

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

@@ -605,7 +605,7 @@ export const TOOLS = [
         },
         user_quote: {
           type: 'string',
-          description: 'Verbatim excerpt from the human in this turn (appended to Notes)',
+          description: 'Verbatim excerpt from the human in this turn (appended to Notes). Stored exactly as given: newlines, spacing and wording are preserved (no trimming or flattening).',
         },
         agent_note: {
           type: 'string',
@@ -637,6 +637,12 @@ export const TOOLS = [
           description:
             'Author the `## Done When` checklist — markdown checklist lines (e.g. "- [ ] criterion") stating how the idea will be verified done. Written between User Stories and Expanded Concept. This is the fix for the promote sufficiency gate\'s "done-criteria" missing-element ([[HS-NR43-DIAG-CAIO]]): pass this instead of force_promote when the gate reports done-criteria as missing — elicit the criteria from the user rather than inventing them.',
         },
+        sources: {
+          type: 'array',
+          description:
+            'Sources saved WITH the capture, verbatim (owner: files and original docs are saved as source). Each entry is ONE of: { url, title? } a link; { path, name?, mime? } a local file the MCP reads itself (preferred for documents, so the content never has to pass through the model); { name, text, mime?, origin? } an original text document; { name, content_base64, mime?, origin? } a binary file. Stored inline in the capture and listed under Source Material, with the original content under Source Files. Limits: 256 KiB per file, 1 MiB and 20 entries per capture; larger entries are refused by name (nothing is truncated). Appends to earlier sources.',
+          items: { type: 'object' },
+        },
         jtbd: {
           type: 'string',
           description: