heyspex 0.1.0

package/vendor/heyspex-mcp/login-handoff.mjs

@@ -0,0 +1,438 @@
+/**
+ * Browser hand-off primitives for `hs login`
+ * ([[HS-IFQM-IZQ7-EPIC-hs-login-browser-hand-off-for-cli-and]] on
+ * milestone [[HS-O6UA-IZQ7-MIL-seamless-companion-onboarding]], research
+ * [[HS-Z38G-IZQ7-RES-seamless-companion-onboarding-one-click-]]).
+ *
+ * This is the OAuth-for-native-apps loopback pattern (RFC 8252) that gcloud,
+ * `gh auth login --web` and Claude Code login already use: the CLI opens the
+ * system browser against the signed-in console, the console mints the
+ * single-use pairing code server-side and redirects it to a one-shot
+ * 127.0.0.1 listener, and the CLI redeems it silently. The typed-code page
+ * (`hs mcp pair <code>`, RFC 8628 device flow) stays as the cross-machine
+ * fallback for the one case loopback cannot cover.
+ *
+ * Everything here is deliberately transport-only and dependency-free so the
+ * CLI verb (vendor/heyspex-mcp/cli.mjs `runLoginCli`) can stay thin and the
+ * unit tests can drive it without a browser or a console.
+ *
+ * SECURITY invariants (not suggestions):
+ *  - the listener binds 127.0.0.1 ONLY, never 0.0.0.0;
+ *  - it serves exactly ONE exchange and then closes (or closes on timeout);
+ *  - the `state` nonce must match EXACTLY what this process generated;
+ *  - the pairing code is never printed, logged, or echoed back into the page.
+ */
+import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+/** Loopback host. Never make this configurable to a non-loopback address. */
+export const LOOPBACK_HOST = '127.0.0.1';
+
+/** Path the console redirects the browser to. */
+export const LOGIN_CALLBACK_PATH = '/callback';
+
+/** Console page that performs the mint + redirect (built in parallel). */
+export const LOGIN_CONNECT_PATH = '/companion/connect';
+
+/** ~3 minutes, per the shared hand-off contract. */
+export const DEFAULT_LOGIN_TIMEOUT_MS = 180_000;
+
+/**
+ * The console rejects a callback port below 1024 (privileged range), so an
+ * ephemeral port the OS hands us must clear that bar. Every platform's
+ * ephemeral range already sits far above it; this is a fail-closed guard, not
+ * an expected branch.
+ */
+export const MIN_CALLBACK_PORT = 1024;
+
+/** The console rejects a state longer than this. Ours is 43 chars. */
+export const MAX_STATE_LENGTH = 512;
+
+/**
+ * This epic's client identifier. The console validates it exactly — it is not
+ * a CLI flag on purpose.
+ */
+export const LOGIN_CLIENT = 'cli';
+
+/**
+ * Opaque, single-use nonce binding the browser round trip to THIS process.
+ * 32 bytes of CSPRNG output (the contract floor is 16).
+ *
+ * base64URL — never plain base64 — is load-bearing, not cosmetic: the console
+ * percent-encodes the value on the way back, but `URLSearchParams` decodes a
+ * literal `+` as a SPACE. A nonce containing `+` or `/` could therefore come
+ * back byte-different and fail its own exact-match check. base64url's alphabet
+ * ([A-Za-z0-9_-]) is query-safe in both directions.
+ */
+export function generateLoginState(byteLength = 32) {
+  if (!Number.isInteger(byteLength) || byteLength < 16) {
+    throw new Error('generateLoginState: byteLength must be an integer >= 16');
+  }
+  const state = randomBytes(byteLength).toString('base64url');
+  if (state.length > MAX_STATE_LENGTH) {
+    throw new Error('generateLoginState: nonce exceeds the console state limit');
+  }
+  return state;
+}
+
+/**
+ * Constant-time nonce comparison. Length mismatch short-circuits (that is not
+ * a secret — the length of our own nonce is fixed and public).
+ */
+export function statesMatch(received, expected) {
+  if (typeof received !== 'string' || typeof expected !== 'string') return false;
+  if (received.length === 0 || received.length !== expected.length) return false;
+  const a = Buffer.from(received, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Build the console URL the browser is sent to. `consoleUrl` MUST come from
+ * the shared resolver (scripts/lib/console-url-resolver.mjs) — never a
+ * hardcoded origin.
+ *
+ *   <consoleUrl>/companion/connect?port=<port>&state=<nonce>&client=cli[&label=<text>]
+ */
+export function buildConnectUrl({ consoleUrl, port, state, client = LOGIN_CLIENT, label } = {}) {
+  if (typeof consoleUrl !== 'string' || !consoleUrl.trim()) {
+    throw new Error('buildConnectUrl: consoleUrl is required');
+  }
+  // The console validates 1024–65535 and rejects anything outside it.
+  if (!Number.isInteger(port) || port < MIN_CALLBACK_PORT || port > 65535) {
+    throw new Error(`buildConnectUrl: port must be ${MIN_CALLBACK_PORT}-65535`);
+  }
+  if (typeof state !== 'string' || !state) {
+    throw new Error('buildConnectUrl: state is required');
+  }
+  if (state.length > MAX_STATE_LENGTH) {
+    throw new Error(`buildConnectUrl: state must be <= ${MAX_STATE_LENGTH} chars`);
+  }
+  const base = consoleUrl.trim().replace(/\/+$/, '');
+  const url = new URL(`${base}${LOGIN_CONNECT_PATH}`);
+  url.searchParams.set('port', String(port));
+  url.searchParams.set('state', state);
+  url.searchParams.set('client', client || LOGIN_CLIENT);
+  if (typeof label === 'string' && label.trim()) url.searchParams.set('label', label.trim());
+  return url.toString();
+}
+
+/**
+ * Reasons arrive from a browser redirect, i.e. from outside this process.
+ * Clamp them to a short opaque token before they reach a terminal, a log, or
+ * an HTML page.
+ */
+export function sanitizeReason(raw) {
+  if (typeof raw !== 'string') return 'unknown';
+  const cleaned = raw.trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '_').slice(0, 64);
+  return cleaned || 'unknown';
+}
+
+/**
+ * Plain-language wording for a failed hand-off. Never leaks the raw payload.
+ *
+ * The console's `error` vocabulary (missing_state, invalid_state,
+ * missing_client, invalid_client, not_authenticated, mint_failed) is an OPEN
+ * set — an unrecognized reason must degrade to a generic message, never throw.
+ */
+export function describeCallbackFailure(reason) {
+  switch (reason) {
+    // locally detected
+    case 'timeout':
+      return 'timed out waiting for the browser to come back';
+    case 'state_mismatch':
+      return 'the browser response did not match this sign-in attempt (rejected)';
+    case 'missing_code':
+      return 'the console came back without a pairing code';
+    case 'aborted':
+      return 'the sign-in was cancelled';
+    // console vocabulary
+    case 'not_authenticated':
+      return 'that browser is not signed in to the console — sign in there, then run hs login again';
+    case 'mint_failed':
+      return 'the console could not mint a pairing code — try again shortly';
+    case 'missing_state':
+    case 'invalid_state':
+      return 'the console rejected this sign-in attempt as malformed (bad state) — run hs login again';
+    case 'missing_client':
+    case 'invalid_client':
+      return 'the console rejected this client — your `hs` CLI may be out of date';
+    // legacy / open set
+    case 'signed_out':
+      return 'the console session was signed out';
+    case 'access_denied':
+      return 'the console denied the pairing request';
+    default:
+      return `the console refused the hand-off (${reason})`;
+  }
+}
+
+/**
+ * Plain-language wording for a redeem (POST /api/mcp/pair) rejection. The
+ * status codes are meaningful and each one has a different user fix.
+ */
+export function describeRedeemFailure(status, errorCode) {
+  switch (status) {
+    case 404:
+      return 'that pairing code is not recognized (it may never have been minted)';
+    case 409:
+      return 'that pairing code was already used — start a fresh sign-in';
+    case 410:
+      return 'that pairing code expired — start a fresh sign-in';
+    case 403:
+      return 'pairing is not permitted for this account (revoked)';
+    case 503:
+      return 'the console database is unavailable right now — try again shortly';
+    default:
+      return typeof errorCode === 'string' && errorCode.trim()
+        ? errorCode.trim()
+        : `HTTP ${status}`;
+  }
+}
+
+const PAGE_STYLE =
+  'font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif;' +
+  'margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;' +
+  'background:#0b0d10;color:#e8eaed;text-align:center';
+
+function htmlPage(title, body) {
+  const safeTitle = String(title).replace(/[<>&]/g, '');
+  const safeBody = String(body).replace(/[<>&]/g, '');
+  return (
+    '<!doctype html><html lang="en"><head><meta charset="utf-8">' +
+    '<meta name="viewport" content="width=device-width,initial-scale=1">' +
+    `<title>${safeTitle}</title></head>` +
+    `<body style="${PAGE_STYLE}"><main style="max-width:32rem;padding:2rem">` +
+    `<h1 style="font-size:1.4rem;margin:0 0 .5rem">${safeTitle}</h1>` +
+    `<p style="margin:0;opacity:.75">${safeBody}</p>` +
+    '</main></body></html>'
+  );
+}
+
+function respond(res, status, html) {
+  try {
+    res.writeHead(status, {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'no-store',
+      connection: 'close',
+    });
+    res.end(html);
+  } catch {
+    /* the browser hung up; the outcome is already settled */
+  }
+}
+
+/**
+ * Start the one-shot loopback listener.
+ *
+ * Resolves once the socket is bound, with:
+ *   { port, callbackUrl, waitForCallback(), close() }
+ *
+ * `waitForCallback()` resolves EXACTLY once with
+ *   { ok: true, code } | { ok: false, reason }
+ * and the server is closed either way. Nothing is retried, nothing is
+ * accepted after the first exchange.
+ */
+export function startCallbackListener({
+  expectedState,
+  timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS,
+} = {}) {
+  if (typeof expectedState !== 'string' || !expectedState) {
+    throw new Error('startCallbackListener: expectedState is required');
+  }
+
+  let settled = false;
+  let resolveResult;
+  const resultPromise = new Promise((resolve) => {
+    resolveResult = resolve;
+  });
+  let timer = null;
+
+  const closeServer = () => {
+    try {
+      server.closeAllConnections?.();
+    } catch {
+      /* older node */
+    }
+    try {
+      server.close();
+    } catch {
+      /* already closing */
+    }
+  };
+
+  const finish = (outcome, res) => {
+    if (settled) return;
+    settled = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    resolveResult(outcome);
+    if (res) {
+      // Let the response flush before we tear the socket down, otherwise the
+      // browser shows a connection reset instead of the "you can close this
+      // tab" page.
+      res.on('finish', closeServer);
+      res.on('close', closeServer);
+      setTimeout(closeServer, 250).unref?.();
+    } else {
+      closeServer();
+    }
+  };
+
+  const server = createServer((req, res) => {
+    let parsed = null;
+    try {
+      parsed = new URL(req.url ?? '/', `http://${LOOPBACK_HOST}`);
+    } catch {
+      parsed = null;
+    }
+
+    if (!parsed || parsed.pathname !== LOGIN_CALLBACK_PATH) {
+      // Keep listening — a favicon probe must not burn the single exchange.
+      respond(res, 404, htmlPage('Not found', 'This is the HeySpex CLI sign-in listener.'));
+      return;
+    }
+
+    if (settled) {
+      respond(
+        res,
+        410,
+        htmlPage('Already handled', 'This sign-in was already completed. You can close this tab.'),
+      );
+      return;
+    }
+
+    const stateParam = parsed.searchParams.get('state');
+    const error = parsed.searchParams.get('error');
+
+    // The console omits `state` entirely when the STATE ITSELF was what it
+    // rejected (missing/absurd length) — there is nothing to echo back. That
+    // shape is a failed attempt reported honestly, NOT a nonce mismatch, and
+    // it must not crash the listener. Nothing is redeemed either way; the only
+    // thing at stake is which message the user reads.
+    if (error && stateParam === null) {
+      const reason = sanitizeReason(error);
+      respond(
+        res,
+        400,
+        htmlPage("Sign-in didn't complete", 'You can close this tab and check the terminal.'),
+      );
+      finish({ ok: false, reason }, res);
+      return;
+    }
+
+    const state = stateParam ?? '';
+    if (!statesMatch(state, expectedState)) {
+      // Never echo either nonce back into the page.
+      respond(
+        res,
+        400,
+        htmlPage(
+          "Sign-in didn't complete",
+          'That response did not match this sign-in attempt, so it was rejected. Nothing was stored. Run hs login again.',
+        ),
+      );
+      finish({ ok: false, reason: 'state_mismatch' }, res);
+      return;
+    }
+
+    if (error) {
+      const reason = sanitizeReason(error);
+      respond(
+        res,
+        400,
+        htmlPage("Sign-in didn't complete", 'You can close this tab and check the terminal.'),
+      );
+      finish({ ok: false, reason }, res);
+      return;
+    }
+
+    const code = parsed.searchParams.get('code');
+    if (!code) {
+      respond(
+        res,
+        400,
+        htmlPage("Sign-in didn't complete", 'You can close this tab and check the terminal.'),
+      );
+      finish({ ok: false, reason: 'missing_code' }, res);
+      return;
+    }
+
+    respond(
+      res,
+      200,
+      htmlPage("You're signed in", 'You can close this tab and return to your terminal.'),
+    );
+    finish({ ok: true, code }, res);
+  });
+
+  server.on('error', (err) => {
+    finish({ ok: false, reason: sanitizeReason(err?.code ?? 'listen_failed') });
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    // Port 0 = let the OS pick an ephemeral port. 127.0.0.1 ONLY.
+    server.listen(0, LOOPBACK_HOST, () => {
+      server.removeListener('error', reject);
+      const address = server.address();
+      const port = typeof address === 'object' && address ? address.port : 0;
+      // The console refuses to redirect to a privileged port, so a listener
+      // there is useless — fail closed rather than open a browser that will
+      // bounce. Every platform's ephemeral range is far above 1024, so this
+      // is a guard, not an expected branch.
+      if (port < MIN_CALLBACK_PORT) {
+        closeServer();
+        reject(
+          new Error(
+            `loopback listener got port ${port}, below the console's ${MIN_CALLBACK_PORT} minimum`,
+          ),
+        );
+        return;
+      }
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => finish({ ok: false, reason: 'timeout' }), timeoutMs);
+      }
+      resolve({
+        port,
+        callbackUrl: `http://${LOOPBACK_HOST}:${port}${LOGIN_CALLBACK_PATH}`,
+        waitForCallback: () => resultPromise,
+        close: () => finish({ ok: false, reason: 'aborted' }),
+      });
+    });
+  });
+}
+
+/**
+ * Open `url` in the user's default browser, detached. Returns false if the
+ * launcher could not even be spawned — the caller always prints the URL too,
+ * so a headless box can paste it by hand.
+ *
+ * Windows uses rundll32's FileProtocolHandler rather than `cmd /c start`
+ * because the connect URL contains `&` query separators, which cmd.exe treats
+ * as command separators; rundll32 involves no shell parsing at all.
+ */
+export function openBrowser(url, { platform = process.platform, spawnFn = spawn } = {}) {
+  const opts = { detached: true, stdio: 'ignore', windowsHide: true };
+  try {
+    let child;
+    if (platform === 'win32') {
+      child = spawnFn('rundll32.exe', ['url.dll,FileProtocolHandler', url], opts);
+    } else if (platform === 'darwin') {
+      child = spawnFn('open', [url], opts);
+    } else {
+      child = spawnFn('xdg-open', [url], opts);
+    }
+    child?.on?.('error', () => {
+      /* no browser on this box — the printed URL is the fallback */
+    });
+    child?.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,136 @@
+/**
+ * Fresh-process delegation for the long-lived MCP stdio server.
+ *
+ * Cursor/Claude spawn `cli.mjs` once per agent session and keep it alive.
+ * Node caches ESM modules in that parent, so in-process `handleToolsCall` can
+ * run stale code after disk edits. Each tools/call (and tools/list) spawns a
+ * short-lived `node cli.mjs call|export …` child instead — same pattern as
+ * `hs mcp call`, without requiring an MCP reconnect.
+ *
+ * Opt out (debug only): HEYSPEX_MCP_INLINE_CALLS=1
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** @type {boolean} */
+export const MCP_SUBPROCESS_TOOLS = process.env.HEYSPEX_MCP_INLINE_CALLS !== '1';
+
+/**
+ * @param {string} stdout
+ * @param {string} stderr
+ * @param {number} code
+ * @returns {{ content: Array<{ type: string, text: string }>, isError?: boolean }}
+ */
+export function parseCallCliStdoutToMcpResult(stdout, stderr, code) {
+  const trimmed = stdout.trim();
+  if (!trimmed) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'SUBPROCESS_EMPTY',
+          message: stderr.trim() || `child exit ${code}`,
+        }),
+      }],
+    };
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && Array.isArray(parsed.content)) {
+      return parsed;
+    }
+    const isError = code !== 0 || parsed?.error != null || parsed?.isError === true;
+    return {
+      ...(isError ? { isError: true } : {}),
+      content: [{ type: 'text', text: JSON.stringify(parsed) }],
+    };
+  } catch {
+    return {
+      isError: code !== 0,
+      content: [{ type: 'text', text: trimmed }],
+    };
+  }
+}
+
+/**
+ * @param {string} cliPath absolute path to cli.mjs
+ * @param {string[]} args argv after `node cli.mjs`
+ * @returns {Promise<{ stdout: string, stderr: string, code: number }>}
+ */
+export function spawnMcpChild(cliPath, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [cliPath, ...args], {
+      env: {
+        ...process.env,
+        HEYSPEX_DISABLE_STDIO_BOOTSTRAP: '1',
+        // Prevent infinite subprocess recursion if the child ever hit stdio bootstrap.
+        HEYSPEX_MCP_INLINE_CALLS: '1',
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', reject);
+    child.on('close', (exitCode) => {
+      resolve({ stdout, stderr, code: exitCode ?? 1 });
+    });
+  });
+}
+
+/**
+ * @param {string} cliPath
+ * @param {{ name: string, arguments?: Record<string, unknown> }} params
+ */
+export async function invokeFreshToolsCall(cliPath, params) {
+  const { name, arguments: toolArgs = {} } = params;
+  const tmpDir = mkdtempSync(join(tmpdir(), 'heyspex-mcp-call-'));
+  const argsFile = join(tmpDir, 'args.json');
+  try {
+    writeFileSync(argsFile, JSON.stringify(toolArgs), 'utf8');
+    const { stdout, stderr, code } = await spawnMcpChild(cliPath, [
+      'call',
+      name,
+      '--args-file',
+      argsFile,
+      '--json',
+    ]);
+    return parseCallCliStdoutToMcpResult(stdout, stderr, code);
+  } finally {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * @param {string} cliPath
+ * @returns {Promise<{ tools: unknown[] }>}
+ */
+export async function invokeFreshToolsList(cliPath) {
+  const { stdout, stderr, code } = await spawnMcpChild(cliPath, [
+    'export',
+    'tools-list',
+    '--json',
+  ]);
+  if (code !== 0) {
+    throw new Error(stderr.trim() || `export tools-list exit ${code}`);
+  }
+  const parsed = JSON.parse(stdout.trim());
+  if (!parsed || !Array.isArray(parsed.tools)) {
+    throw new Error('export tools-list returned invalid payload');
+  }
+  return parsed;
+}

package/vendor/heyspex-mcp/mvp-mode.mjs

@@ -0,0 +1,101 @@
+/**
+ * MVP Mode reader for MCP callers — [[HS-EPIC-MRDR]] §AC #7 / [[HS-MIL-MVMD]].
+ *
+ * A thin, filesystem-only mirror of the console's `readMvpModeState`
+ * (`spex-console/src/lib/vault.ts`). No cache: an MCP invocation is short-lived, so
+ * each call reads the file once. Kept dependency-free (no js-yaml) — the
+ * `mvp_mode:` block is shallow and predictable, so a targeted block parse is
+ * enough and avoids pulling console code into the vendor tree.
+ *
+ * `cli.mjs` / `next-review.mjs` use this so an agent can branch on whether the
+ * relax-review-to-milestone regime is active (e.g. skip the per-task HS-REV
+ * close-out gate while ON).
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function configYamlPath(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'config.yaml');
+}
+
+function stripInlineComment(value) {
+  // Drop a trailing ` # comment` that isn't inside quotes. The config uses
+  // unquoted scalars, so a simple split on ` #` is sufficient and safe.
+  const idx = value.indexOf(' #');
+  const v = idx === -1 ? value : value.slice(0, idx);
+  return v.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Parse the `mvp_mode:` block out of a raw config.yaml string. Returns the
+ * recognized fields, or `null` when the block is absent. `enabled` is true only
+ * when the literal value is `true` (mirrors the console's failsafe parse).
+ */
+export function parseMvpModeBlock(raw) {
+  const lines = String(raw).split(/\r?\n/);
+  const blockIdx = lines.findIndex((l) => /^mvp_mode\s*:/.test(l));
+  if (blockIdx === -1) return null;
+
+  // `review_backlog_never_blocks` defaults ON — see the case below.
+  const state = { enabled: false, review_backlog_never_blocks: true };
+  for (let i = blockIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    // A non-indented, non-blank, non-comment line ends the block.
+    if (/^\S/.test(line) && line.trim() !== '' && !line.trimStart().startsWith('#')) {
+      break;
+    }
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) continue;
+    const key = trimmed.slice(0, colon).trim();
+    const val = stripInlineComment(trimmed.slice(colon + 1));
+    switch (key) {
+      case 'enabled':
+        state.enabled = val.toLowerCase() === 'true';
+        break;
+      case 'activated':
+        if (val) state.activated = val;
+        break;
+      case 'reason':
+        if (val) state.reason = val;
+        break;
+      case 'review_grain':
+        // task | epic | milestone — epic is steady-state Standard grain ([[HS-EPIC-7CWZ]]).
+        if (val === 'task' || val === 'epic' || val === 'milestone')
+          state.review_grain = val;
+        break;
+      case 'review_backlog_never_blocks':
+        // Opt-OUT only: absent ⇒ true. A batched review grain implies a standing
+        // review backlog, so "specs awaiting review" can never gate the next
+        // claim (owner ruling 2026-08-14). Set it to `false` explicitly to
+        // restore drain-the-queue-first behavior.
+        state.review_backlog_never_blocks = val.toLowerCase() !== 'false';
+        break;
+      case 'flip_off_when':
+        if (val) state.flip_off_when = val;
+        break;
+      default:
+        break;
+    }
+  }
+  return state;
+}
+
+/**
+ * One-shot read of the effective MVP Mode state. Returns the state object when
+ * the regime is ON, else `null` (file missing, block absent, or `enabled`
+ * falsy) — same contract as the console's `readMvpModeState`.
+ */
+export function readMvpModeState(vaultRoot) {
+  let raw;
+  try {
+    raw = readFileSync(configYamlPath(vaultRoot), 'utf-8');
+  } catch {
+    return null;
+  }
+  const block = parseMvpModeBlock(raw);
+  if (!block || !block.enabled) return null;
+  return block;
+}