heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/cli-verbs.mjs

@@ -0,0 +1,2076 @@
+// The argv verbs: node cli.mjs validate | register | call | export | pair | login.
+// Each returns an exit code. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// Freshness handshake (HS-G263-DIAG-2F0X): this process is long-running, so a
+// vendor/heyspex-mcp/*.mjs edit made after startup does NOT reach it — the
+// in-memory tool schemas silently drift from code on disk. Stamping a build
+// fingerprint at startup lets scripts/check-mcp-freshness.mjs (and its
+// SessionStart hook) prove staleness instead of guessing. See
+// [[mcp-server-restart-after-vendor-updates]].
+//
+// Browser hand-off primitives for `hs login` (RFC 8252 loopback), epic
+// [[HS-IFQM-IZQ7-EPIC-hs-login-browser-hand-off-for-cli-and]].
+
+import { DEFAULT_LOGIN_TIMEOUT_MS, buildConnectUrl, describeCallbackFailure, describeRedeemFailure, generateLoginState, openBrowser as openBrowserDefault, startCallbackListener as startCallbackListenerDefault } from './login-handoff.mjs';
+import { getConfig, getConsoleUrl } from './mcp-config.mjs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { handleToolsCall, handleToolsList } from './tool-dispatch.mjs';
+import { writeBuildRecord } from '../../scripts/check-mcp-freshness.mjs';
+import { registerSpec } from './register-spec.mjs';
+import { validateLinkage } from './validate-linkage.mjs';
+import { execFileSync } from 'node:child_process';
+import {
+  LEGACY_ACCOUNT_ID,
+  assertNotRealHomeUnderTest,
+  describeBearerSource,
+  findStoredAccount,
+  migrateLegacyCredentials,
+  readBearer,
+  readCredentialsStore,
+  writeAccountCredentials,
+} from './credentials.mjs';
+import { followCurrentAccountInRegistry, signOutAccount, switchCurrentAccount } from './account-switch.mjs';
+import { resolveSessionOwnerUncached } from './session-owner.mjs';
+import { isLoopbackConsoleUrl } from '../../scripts/lib/console-url-resolver.mjs';
+import { formatIdentity, probeCredentialIdentity, readStoredBearer } from './whoami.mjs';
+import {
+  EXIT_ACCOUNT_MISMATCH,
+  EXIT_RECEIPT_DISAGREE,
+  buildSidesReceipt,
+  formatSidesReceipt,
+  unreadSide,
+} from './receipt-shape.mjs';
+
+// Basenames of `.md` files staged under specs/ — the scope for --staged-only.
+export function stagedSpecBasenames(vaultRoot) {
+  let out = '';
+  try {
+    out = execFileSync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACM'], {
+      cwd: vaultRoot,
+      encoding: 'utf-8',
+    });
+  } catch {
+    return [];
+  }
+  return out
+    .split(/\r?\n/)
+    .map((p) => p.trim())
+    .filter((p) => p.startsWith('specs/') && p.endsWith('.md'))
+    .map((p) => p.replace(/.*\//, '').replace(/\.md$/, ''));
+}
+
+// Frozen-by-protocol mismatches are informational, never defects — a closed /
+// superseded spec's roster is historical record and editing it is forbidden
+// ([[closed-trackable-specs-are-historical-record-not-living-docs]]). Printed on
+// BOTH the OK and the failing path so they are always visible, never swallowed.
+function renderFrozenMismatches(result) {
+  const frozen = result.frozen_parent_child_mismatches ?? [];
+  if (!frozen.length) return;
+  process.stdout.write(
+    `  ${frozen.length} frozen parent/child mismatch(es) — excluded: a closed/superseded spec's ` +
+      `roster is historical record and must not be edited. No action required.\n`,
+  );
+  for (const m of frozen) {
+    process.stdout.write(`  [FROZEN — not a defect] ${m.parent} ⇄ ${m.child} (${m.frozen_side} frozen): ${m.issue}\n`);
+  }
+}
+
+export function renderLinkageText(result, { stagedOnly } = {}) {
+  const s = result.summary;
+  if (result.valid) {
+    process.stdout.write(
+      `validate-linkage: OK (${s.total_specs_checked} subject spec(s) checked${stagedOnly ? ', staged-only' : ''})\n`,
+    );
+    if (result.warnings.length) {
+      process.stdout.write(`  (${result.warnings.length} warning(s) — run with --json for details)\n`);
+    }
+    renderFrozenMismatches(result);
+    return;
+  }
+  process.stdout.write(
+    `validate-linkage: ${s.orphans} orphan(s), ${s.broken_links} broken link(s), ` +
+      `${s.missing_refs} missing manifest ref(s), ${s.mismatches} parent/child mismatch(es)\n\n`,
+  );
+  for (const o of result.orphan_specs) {
+    process.stdout.write(`[ORPHAN ${o.type}] ${o.spec_id}\n  → ${o.file_path}\n  ${o.reason}\n  fix: ${o.suggestion}\n`);
+  }
+  for (const b of result.broken_wikilinks) {
+    process.stdout.write(`[BROKEN LINK] ${b.link} at ${b.file}:${b.line}\n`);
+  }
+  for (const m of result.missing_manifest_refs) {
+    process.stdout.write(`[MISSING REF] ${m.manifest} → ${m.ref} (${m.error})\n`);
+  }
+  for (const m of result.parent_child_mismatches) {
+    process.stdout.write(`[MISMATCH] ${m.parent} ⇄ ${m.child}: ${m.issue}\n`);
+  }
+  renderFrozenMismatches(result);
+}
+
+export async function runValidateCli(argv) {
+  const flags = { json: false, preCommit: false, stagedOnly: false, noWarnings: false, spec: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') flags.json = true;
+    else if (a === '--pre-commit') flags.preCommit = true;
+    else if (a === '--staged-only') flags.stagedOnly = true;
+    else if (a === '--no-warnings') flags.noWarnings = true;
+    else if (a === '--spec') flags.spec = argv[++i];
+    else if (a.startsWith('--spec=')) flags.spec = a.slice('--spec='.length);
+    else {
+      process.stderr.write(`[heyspex-mcp validate] unknown argument: ${a}\n`);
+      return 2;
+    }
+  }
+  const { vaultRoot } = getConfig();
+  if (!existsSync(vaultRoot)) {
+    process.stderr.write(`[heyspex-mcp validate] vault root not found: ${vaultRoot}\n`);
+    return 2;
+  }
+  let specIds = flags.spec ? [flags.spec] : null;
+  if (flags.stagedOnly) {
+    specIds = stagedSpecBasenames(vaultRoot);
+    if (specIds.length === 0) return 0; // nothing staged under specs/ → nothing to validate
+  }
+  const result = validateLinkage(vaultRoot, { spec_ids: specIds, includeWarnings: !flags.noWarnings });
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    renderLinkageText(result, flags);
+  }
+  return result.valid ? 0 : 1;
+}
+
+// `register` CLI verb — the terminal / disaster-recovery face of
+// heyspex_register_spec ([[HS-TASK-5K13]], [[capability-three-faces-no-per-capability-slash]]).
+//   node vendor/heyspex-mcp/cli.mjs register HS-TASK-5K13 --parent HS-EPIC-0037 [--json] [--dry-run]
+export async function runRegisterCli(argv) {
+  const flags = { json: false, dryRun: false, specId: null, parent: null, roadmap: null, position: null };
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') flags.json = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--parent') flags.parent = argv[++i];
+    else if (a.startsWith('--parent=')) flags.parent = a.slice('--parent='.length);
+    else if (a === '--roadmap') flags.roadmap = argv[++i];
+    else if (a.startsWith('--roadmap=')) flags.roadmap = a.slice('--roadmap='.length);
+    else if (a === '--position') flags.position = argv[++i];
+    else if (a.startsWith('--position=')) flags.position = a.slice('--position='.length);
+    else if (a.startsWith('--')) {
+      process.stderr.write(`[heyspex-mcp register] unknown argument: ${a}\n`);
+      return 2;
+    } else positionals.push(a);
+  }
+  flags.specId = positionals[0] || null;
+  if (!flags.specId) {
+    process.stderr.write('[heyspex-mcp register] usage: register <spec-id> [--parent <id>] [--roadmap <id>] [--position <p>] [--json] [--dry-run]\n');
+    return 2;
+  }
+  const { vaultRoot } = getConfig();
+  if (!existsSync(vaultRoot)) {
+    process.stderr.write(`[heyspex-mcp register] vault root not found: ${vaultRoot}\n`);
+    return 2;
+  }
+  const result = registerSpec(vaultRoot, {
+    spec_id: flags.specId,
+    parent_id: flags.parent,
+    roadmap_id: flags.roadmap || undefined,
+    position: flags.position || undefined,
+    dryRun: flags.dryRun,
+  });
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (!result.success) {
+    process.stdout.write(`register-spec: ${result.error} — ${result.message}\n`);
+    if (result.suggestions?.length) process.stdout.write(`  did you mean: ${result.suggestions.join(', ')}\n`);
+  } else if (result.already_registered) {
+    process.stdout.write(`register-spec: ${result.spec_id} already linked — no change.\n`);
+  } else {
+    process.stdout.write(`register-spec: ${result.dry_run ? '[dry-run] would apply' : 'linked'} ${result.spec_id}\n`);
+    for (const c of result.changes) process.stdout.write(`  • ${c.action} (${c.file})\n`);
+    if (result.validation) {
+      process.stdout.write(`  validation: ${result.validation.valid ? 'OK' : `${result.validation.orphan_specs.length} orphan(s), ${result.validation.parent_child_mismatches.length} mismatch(es) remaining`}\n`);
+    }
+  }
+  return result.success ? 0 : 1;
+}
+
+/**
+ * Coerce an `--arg key=value` value: JSON literals when parseable, else raw string.
+ * @param {string} raw
+ */
+export function coerceCallCliArgValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * @param {string} flag e.g. `--arg spec_id=HS-TASK-NCH5`
+ * @returns {{ key: string, value: unknown } | { error: { code: number, message: string } }}
+ */
+export function parseCallCliArgFlag(flag) {
+  const body = flag.startsWith('--arg=') ? flag.slice('--arg='.length) : null;
+  const eq = body !== null ? body.indexOf('=') : -1;
+  if (body !== null && eq > 0) {
+    const key = body.slice(0, eq);
+    return { key, value: coerceCallCliArgValue(body.slice(eq + 1)) };
+  }
+  const bare = flag.startsWith('--arg') ? flag : null;
+  if (bare === null) {
+    return { error: { code: 2, message: `invalid --arg flag: ${flag}` } };
+  }
+  return { error: { code: 2, message: '--arg requires key=value (e.g. --arg spec_id=HS-TASK-NCH5)' } };
+}
+
+/**
+ * Parse argv for the `call` CLI verb — one-shot MCP tool invocation without
+ * starting the stdio JSON-RPC loop ([[HS-TASK-ISK7]] parity for all tools).
+ *
+ * Prefer repeated `--arg key=value` over `--args '<json>'` on Windows/PowerShell —
+ * shell JSON quoting is unreliable there.
+ *
+ * @param {string[]} argv tokens after `call`
+ * @returns {{ help?: true, error?: { code: number, message: string }, tool?: string, args?: object, json?: boolean }}
+ */
+export function parseCallCliArgs(argv) {
+  let tool = null;
+  let json = false;
+  let argsJson = null;
+  let argsFromFile = false;
+  /** @type {Record<string, unknown>} */
+  const argPairs = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') return { help: true };
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a === '--args') {
+      const v = argv[++i];
+      if (v === undefined) {
+        return { error: { code: 2, message: '--args requires a JSON object string' } };
+      }
+      argsJson = v;
+      continue;
+    }
+    if (a.startsWith('--args=')) {
+      argsJson = a.slice('--args='.length);
+      continue;
+    }
+    if (a === '--args-file') {
+      const v = argv[++i];
+      if (v === undefined) {
+        return { error: { code: 2, message: '--args-file requires a path' } };
+      }
+      argsJson = v;
+      argsFromFile = true;
+      continue;
+    }
+    if (a.startsWith('--args-file=')) {
+      argsJson = a.slice('--args-file='.length);
+      argsFromFile = true;
+      continue;
+    }
+    if (a === '--arg') {
+      const v = argv[++i];
+      if (v === undefined || !v.includes('=')) {
+        return { error: { code: 2, message: '--arg requires key=value (e.g. --arg spec_id=HS-TASK-NCH5)' } };
+      }
+      const eq = v.indexOf('=');
+      const key = v.slice(0, eq);
+      if (!key) {
+        return { error: { code: 2, message: '--arg requires key=value (e.g. --arg spec_id=HS-TASK-NCH5)' } };
+      }
+      argPairs[key] = coerceCallCliArgValue(v.slice(eq + 1));
+      continue;
+    }
+    if (a.startsWith('--arg=')) {
+      const parsed = parseCallCliArgFlag(a);
+      if (parsed.error) return parsed;
+      argPairs[parsed.key] = parsed.value;
+      continue;
+    }
+    if (a.startsWith('-')) {
+      return { error: { code: 2, message: `unknown argument: ${a}` } };
+    }
+    if (!tool) {
+      tool = a;
+      continue;
+    }
+    return { error: { code: 2, message: `unexpected argument: ${a}` } };
+  }
+  if (!tool) {
+    return { error: { code: 2, message: 'tool name required (e.g. heyspex_claim_spec)' } };
+  }
+  /** @type {Record<string, unknown>} */
+  let args = {};
+  if (argsJson !== null) {
+    let rawJson = argsJson;
+    if (argsFromFile) {
+      if (!existsSync(rawJson)) {
+        return { error: { code: 2, message: `--args-file not found: ${rawJson}` } };
+      }
+      try {
+        rawJson = readFileSync(rawJson, 'utf8');
+      } catch (err) {
+        return {
+          error: {
+            code: 2,
+            message: `--args-file could not read ${argsJson}: ${err?.message ?? err}`,
+          },
+        };
+      }
+    }
+    try {
+      const parsed = JSON.parse(rawJson);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { error: { code: 2, message: '--args/--args-file must be a JSON object' } };
+      }
+      args = parsed;
+    } catch {
+      return { error: { code: 2, message: '--args/--args-file must be valid JSON' } };
+    }
+  }
+  Object.assign(args, argPairs);
+  return { tool, args, json };
+}
+
+export const PAIR_CLI_HELP = `heyspex-mcp pair — exchange a console pairing code for a persistent MCP bearer
+
+Usage:
+  node vendor/heyspex-mcp/cli.mjs pair <code> [--console-url <url>] [--label <text>] [--json]
+  hs mcp pair <code> [--console-url <url>]
+
+Mint a pairing code from the signed-in console (POST /api/mcp/pairing-codes,
+Clerk-gated), then redeem it here. The console is then asked who the new
+\`hsmcp_\` bearer belongs to (GET /api/mcp/session); only then is the bearer
+AND the console URL stored in ~/.heyspex/credentials.yaml, under THAT account
+(created with restrictive permissions if absent) — NEVER in the repo — and that
+account becomes current. Other accounts already stored stay signed in. If the
+console cannot confirm the account, nothing is stored and the verb exits 1.
+Every subsequent MCP call to a cloud console picks the current account's token
+up automatically (env HEYSPEX_MCP_TOKEN still wins if set).
+
+[[HS-GD45-MCPC-TASK-mcp-cloud-auth-shared-console-resolver]].
+`;
+
+/**
+ * Upsert top-level \`key: value\` lines in a file under \`~/.heyspex/\`,
+ * preserving every other line untouched (no full YAML parse/dump — these
+ * files carry hand-maintained blocks and comments that a naive round-trip
+ * could reformat). Creates the directory + file (with the given file mode)
+ * if absent. Never writes into the repo — always the caller's HOME.
+ *
+ * Shared by {@link upsertCredentialsYamlKeys} (`credentials.yaml`, secret
+ * bearer material, 0o600) and {@link upsertConfigYamlKeys} (`config.yaml`,
+ * non-secret per-machine settings like \`account_id:\`/\`owner:\`).
+ */
+function upsertHeyspexHomeYamlKeys(homeDir, fileName, updates, { fileMode = 0o600 } = {}) {
+  const dir = join(homeDir, '.heyspex');
+  const filePath = join(dir, fileName);
+  // Never the real ~/.heyspex under a test runner (HS-UA9S, same guard as registry-file.ts).
+  assertNotRealHomeUnderTest(filePath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  let content = '';
+  try {
+    content = readFileSync(filePath, 'utf8');
+  } catch {
+    content = '';
+  }
+  const lines = content.length > 0 ? content.split(/\r?\n/) : [];
+  for (const [key, value] of Object.entries(updates)) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`^${escapedKey}:.*$`);
+    const serialized = `${key}: ${value}`;
+    const idx = lines.findIndex((line) => pattern.test(line));
+    if (idx >= 0) lines[idx] = serialized;
+    else lines.push(serialized);
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  writeFileSync(filePath, `${lines.join('\n')}\n`, { mode: fileMode });
+  return filePath;
+}
+
+/**
+ * Upsert top-level \`key: value\` lines in \`~/.heyspex/credentials.yaml\`,
+ * preserving every other line untouched (no full YAML parse/dump — this file
+ * carries hand-maintained blocks like \`clerk:\` that a naive round-trip
+ * could reformat). Creates the directory + file with restrictive
+ * permissions if absent. Never writes into the repo — always the caller's
+ * HOME.
+ */
+export function upsertCredentialsYamlKeys(homeDir, updates) {
+  return upsertHeyspexHomeYamlKeys(homeDir, 'credentials.yaml', updates, { fileMode: 0o600 });
+}
+
+/**
+ * Upsert top-level \`key: value\` lines in \`~/.heyspex/config.yaml\` (the
+ * user's HOME config, NOT the vault-tracked \`<repo>/.heyspex/config.yaml\`
+ * that \`config-settings.mjs\`/\`vault.ts\`'s \`configYamlPath()\` read/write).
+ * This is where the ONE account reader (\`session-owner.mjs\`, which
+ * \`resolveConfiguredAccountId\` in
+ * \`spex-console/src/lib/cli/vault-workspace-shared.ts\` delegates to) reads
+ * \`account_id:\` from — nothing wrote that key before this, so the old
+ * non-strict resolver always fell through to the \`pwher\` sentinel
+ * ([[HS-4GFR-GO2H-DIAG-cli-cloud-writes-land-on-the-pwher]]); that fallback is
+ * gone ([[HS-630L-WW9R-TASK-one-strict-cli-account-reader-hs-login]]).
+ *
+ * Same comment/unknown-key-preserving upsert as
+ * {@link upsertCredentialsYamlKeys}, but non-secret content, so a normal
+ * (non-0600) file mode — this file also carries a hand-maintained \`owner:\`
+ * key and may carry user comments, all preserved untouched.
+ */
+export function upsertConfigYamlKeys(homeDir, updates) {
+  return upsertHeyspexHomeYamlKeys(homeDir, 'config.yaml', updates, { fileMode: 0o644 });
+}
+
+export function parsePairCliArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { help: true };
+  const positional = [];
+  let consoleUrlOverride;
+  let label;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--console-url') { consoleUrlOverride = argv[i + 1]; i += 1; continue; }
+    if (arg === '--label') { label = argv[i + 1]; i += 1; continue; }
+    if (arg === '--json') { json = true; continue; }
+    positional.push(arg);
+  }
+  const code = positional[0];
+  if (!code) {
+    return {
+      error: { message: 'Usage: hs mcp pair <code> [--console-url <url>] [--label <text>]', code: 2 },
+    };
+  }
+  return { code, consoleUrlOverride, label, json };
+}
+
+/**
+ * THE redeem + credential-write path, shared by `hs mcp pair <code>` (code
+ * typed by hand) and `hs login` (code delivered by the browser hand-off).
+ * There is exactly one of these on purpose: both verbs must store the bearer
+ * the same way, through the per-account store (`credentials.mjs`
+ * `writeAccountCredentials`), which preserves the hand-maintained blocks in
+ * ~/.heyspex/credentials.yaml.
+ *
+ * Prints NOTHING (callers own their own voice) and never returns, logs, or
+ * echoes token material — the summary carries ids only, exactly like the
+ * pair verb has always printed.
+ *
+ * In order ([[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]], after
+ * [[HS-630L-WW9R-TASK-one-strict-cli-account-reader-hs-login]]):
+ *   1. redeem the code (the bearer is held in memory only);
+ *   2. ask the console who that bearer belongs to (`probe` =
+ *      `probeCredentialIdentity`, GET /api/mcp/session — the same probe
+ *      `hs whoami` and the install/connect identity gate use). The pair body's
+ *      `userId` is never trusted: it is what the console minted the code for,
+ *      not a verdict on the token. A failed probe stores NOTHING (no token
+ *      under a guessed id) and returns `{ ok: false, half: 'account', message }`;
+ *   3. store the bearer + console URL under the CONFIRMED account id, make it
+ *      current, and move registry.json's `current_account_id` with it
+ *      (`account-switch.mjs`). Other stored accounts are untouched. An
+ *      existing v1 (single-token) file is re-keyed in the same write: its
+ *      token goes under the account the console confirms for IT, or stays
+ *      under `legacy` when the console cannot say. Nothing is written to
+ *      ~/.heyspex/config.yaml any more (one account-id store, invariant 3).
+ *
+ * Returns { ok: true, summary } | { ok: false, half: 'bearer' | 'account', message }.
+ */
+export async function redeemAndStorePairingCode({
+  consoleUrl,
+  code,
+  label,
+  probe = probeCredentialIdentity,
+  homeDir = homedir(),
+  requireAccount = null,
+}) {
+  let response;
+  try {
+    response = await fetch(`${consoleUrl}/api/mcp/pair`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        code,
+        label: label ?? hostname(),
+      }),
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      half: 'bearer',
+      message: `could not reach ${consoleUrl}: ${err?.message ?? err}`,
+    };
+  }
+
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+
+  if (!response.ok || !body?.token) {
+    return {
+      ok: false,
+      half: 'bearer',
+      message: `pairing failed: ${describeRedeemFailure(response.status, body?.error)}`,
+    };
+  }
+
+  const resolvedConsoleUrl =
+    typeof body.consoleUrl === 'string' && body.consoleUrl.trim() ? body.consoleUrl.trim() : consoleUrl;
+
+  // The account: ask the console who the redeemed bearer belongs to BEFORE
+  // anything is stored. Never `body.userId` ([[HS-630L-WW9R-TASK-one-strict-cli-account-reader-hs-login]] AC3).
+  const identity = await probe({ consoleUrl: resolvedConsoleUrl, token: body.token });
+  if (identity?.kind !== 'identified') {
+    return {
+      ok: false,
+      half: 'account',
+      message:
+        `the console did not confirm which account the new sign-in belongs to ` +
+        `(${describeProbeFailure(identity)}). Nothing was stored — the credentials on this ` +
+        'machine are unchanged. Check the console with `hs whoami`, then run `hs login` again.',
+    };
+  }
+
+  // `hs login --account <id>`: the sign-in must be THAT account. Anyone else
+  // is refused before anything is stored, so the current account never moves.
+  if (requireAccount && !identityMatches(identity, requireAccount)) {
+    return {
+      ok: false,
+      half: 'account',
+      mismatch: { requested: requireAccount, accountId: identity.accountId, email: identity.email ?? null },
+      message:
+        `you asked to sign in as ${requireAccount}, but the console confirmed ${formatIdentity(identity)}. ` +
+        `Nothing was stored -- this machine's current account is unchanged. Sign in as ${requireAccount} ` +
+        `in the browser, then run \`hs login --account ${requireAccount}\` again.`,
+    };
+  }
+
+  // A v1 (single-token) file: learn whose its token is before re-keying it.
+  const existing = readCredentialsStore({ homeDir });
+  let rekeyLegacyAs = null;
+  const legacy = existing.schemaVersion === 1 ? existing.accounts[LEGACY_ACCOUNT_ID] : null;
+  if (legacy?.mcp_token) {
+    if (legacy.mcp_token === body.token) {
+      rekeyLegacyAs = identity.accountId;
+    } else {
+      const legacyIdentity = await probe({
+        consoleUrl: legacy.console_url ?? resolvedConsoleUrl,
+        token: legacy.mcp_token,
+      });
+      if (legacyIdentity?.kind === 'identified') rekeyLegacyAs = legacyIdentity.accountId;
+    }
+  }
+
+  let credentialsPath;
+  try {
+    credentialsPath = writeAccountCredentials({
+      homeDir,
+      accountId: identity.accountId,
+      mcpToken: body.token,
+      consoleUrl: resolvedConsoleUrl,
+      email: identity.email,
+      makeCurrent: true,
+      rekeyLegacyAs,
+    });
+  } catch (err) {
+    return { ok: false, half: 'bearer', message: `could not store the credentials: ${err?.message ?? err}` };
+  }
+  const registry = followCurrentAccountInRegistry({ homeDir, accountId: identity.accountId });
+  const stored = readCredentialsStore({ homeDir });
+
+  return {
+    ok: true,
+    summary: {
+      paired: true,
+      sessionId: body.sessionId,
+      // The account the CONSOLE confirmed for the stored bearer — not the pair
+      // body's claim. Both normally agree; when they do not, the probe wins and
+      // `pairBodyUserId` lets `--json` consumers see the disagreement.
+      userId: identity.accountId,
+      email: identity.email,
+      pairBodyUserId: typeof body.userId === 'string' ? body.userId : null,
+      consoleUrl: resolvedConsoleUrl,
+      credentialsPath,
+      currentAccountId: stored.currentAccountId,
+      storedAccounts: Object.keys(stored.accounts),
+      registryCurrentAccount: registry.status,
+      accountSource: 'session-probe',
+    },
+  };
+}
+
+/** The human lines every successful pairing prints (pair + login share them). */
+function renderPairedLines(summary) {
+  const others = summary.storedAccounts.filter((id) => id !== summary.userId);
+  return (
+    `  console:     ${summary.consoleUrl}\n` +
+    `  session:     ${summary.sessionId}\n` +
+    `  user:        ${summary.email ? `${summary.email} (${summary.userId})` : summary.userId}\n` +
+    `  bearer stored under account ${summary.userId} in ${summary.credentialsPath} (never the repo); it is now current.\n` +
+    (others.length > 0 ? `  also signed in on this machine: ${others.join(', ')} (hs login --switch-account <id>)\n` : '')
+  );
+}
+
+/** One line for the human about why GET /api/mcp/session did not identify the stored bearer. */
+function describeProbeFailure(identity) {
+  switch (identity?.kind) {
+    case 'rejected':
+      return `the console rejected the stored token with HTTP ${identity.status}`;
+    case 'unsupported':
+      return `the console has no /api/mcp/session route yet (HTTP ${identity.status}) — it needs the deploy`;
+    case 'unreachable':
+      return `the session probe failed: ${identity.message}`;
+    case 'no_credential':
+      return 'no bearer was available to probe with';
+    default:
+      return 'the session probe returned no identity';
+  }
+}
+
+/** True when `wanted` names this identity: its account id, or its email (any case). */
+function identityMatches(identity, wanted) {
+  const w = String(wanted ?? '').trim();
+  if (!w) return true;
+  return w === identity.accountId || Boolean(identity.email && identity.email.toLowerCase() === w.toLowerCase());
+}
+
+// ---------------------------------------------------------------------------
+// The `hs login` receipt ([[HS-CRNE-WW9R-TASK-give-hs-install-and-hs-login-the]]):
+// what this machine stored (credentials.yaml) next to what the console says
+// that stored token belongs to (GET /api/mcp/session), in the shared receipt
+// envelope (./receipt-shape.mjs). The account must agree.
+// ---------------------------------------------------------------------------
+
+/** The retry a login receipt names when the two sides name different accounts. */
+export const LOGIN_RECEIPT_RETRY = 'hs login --switch-account';
+
+/** The rows of the login receipt: the account must agree; the rest is shown. */
+export const LOGIN_RECEIPT_ROWS = Object.freeze([
+  { label: 'account', local: 'account_id', cloud: 'userId', compare: true },
+  { label: 'email', local: 'email', cloud: 'email' },
+  { label: 'console', local: 'console_url' },
+  { label: 'token from', local: 'source' },
+  { label: 'mode', cloud: 'mode' },
+]);
+
+/** The current account as stored on this machine, or null (none, or only a v1 `legacy` token). */
+function currentStoredAccount(homeDir) {
+  const store = readCredentialsStore({ homeDir });
+  const id = store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID ? store.currentAccountId : null;
+  return { store, id, entry: id ? (store.accounts[id] ?? null) : null };
+}
+
+/** Local side: the current account in credentials.yaml, its console, and where the bearer resolves from. */
+export function readLoginLocalSide({ homeDir = homedir(), env = process.env } = {}) {
+  try {
+    const { id, entry } = currentStoredAccount(homeDir);
+    return {
+      read: true,
+      account_id: id,
+      email: entry?.email ?? null,
+      console_url: entry?.console_url ?? null,
+      source: readBearer({ env, homeDir }).source ?? null,
+    };
+  } catch (err) {
+    return unreadSide(`credentials.yaml could not be read: ${err?.message ?? err}`);
+  }
+}
+
+/**
+ * Cloud side: GET /api/mcp/session with the token stored for the current
+ * account, at that account's console (else `fallbackConsoleUrl`). Never
+ * includes token material.
+ */
+export async function readLoginCloudSide({ homeDir = homedir(), probe = probeCredentialIdentity, fallbackConsoleUrl } = {}) {
+  const { entry } = currentStoredAccount(homeDir);
+  if (!entry?.mcp_token) return unreadSide('no stored sign-in to ask the console about');
+  const identity = await probe({ consoleUrl: entry.console_url ?? fallbackConsoleUrl, token: entry.mcp_token });
+  if (identity?.kind !== 'identified') {
+    return unreadSide(`GET /api/mcp/session: ${describeProbeFailure(identity)}`);
+  }
+  return {
+    read: true,
+    userId: identity.accountId,
+    email: identity.email ?? null,
+    mode: typeof identity.mode === 'string' ? identity.mode : null,
+  };
+}
+
+/** Build the login receipt; a disagreement names {@link LOGIN_RECEIPT_RETRY}. */
+export function buildLoginReceipt({ local, cloud, before }) {
+  const receipt = buildSidesReceipt({ local, cloud, rows: LOGIN_RECEIPT_ROWS, before: before ?? {} });
+  if (receipt.verified && !receipt.agree) receipt.retry = LOGIN_RECEIPT_RETRY;
+  return receipt;
+}
+
+/** Exit for a finished login: 21 when both sides were read and disagree, else `ok`. */
+function loginReceiptExit(receipt, ok = 0) {
+  return receipt.verified && !receipt.agree ? EXIT_RECEIPT_DISAGREE : ok;
+}
+
+/** Print a finished login: JSON with `receipt`, or the text lines then the receipt table. */
+function emitLogin({ json, stdout, summary, text, receipt }) {
+  if (json) stdout.write(`${JSON.stringify({ ...summary, receipt }, null, 2)}\n`);
+  else stdout.write(`${text}${formatSidesReceipt(receipt, LOGIN_RECEIPT_ROWS)}\n`);
+}
+
+/** Same console, ignoring case and trailing slashes. */
+function sameConsoleUrl(a, b) {
+  const norm = (u) => String(u ?? '').trim().replace(/\/+$/, '').toLowerCase();
+  return Boolean(a) && norm(a) === norm(b);
+}
+
+export async function runPairCli(argv) {
+  const parsed = parsePairCliArgs(argv);
+  if (parsed.help) {
+    process.stdout.write(`${PAIR_CLI_HELP}\n`);
+    return 0;
+  }
+  if (parsed.error) {
+    process.stderr.write(`[heyspex-mcp pair] ${parsed.error.message}\n`);
+    return parsed.error.code;
+  }
+
+  const consoleUrl = parsed.consoleUrlOverride
+    ? parsed.consoleUrlOverride.trim().replace(/\/+$/, '')
+    : getConsoleUrl();
+
+  const redeemed = await redeemAndStorePairingCode({
+    consoleUrl,
+    code: parsed.code,
+    label: parsed.label,
+  });
+  if (!redeemed.ok) {
+    const half = redeemed.half === 'account' ? 'account half failed: ' : '';
+    process.stderr.write(`[heyspex-mcp pair] ${half}${redeemed.message}\n`);
+    return 1;
+  }
+
+  const summary = redeemed.summary;
+  if (parsed.json) {
+    process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+  } else {
+    process.stdout.write(`Paired.\n${renderPairedLines(summary)}`);
+  }
+  return 0;
+}
+
+export const LOGIN_CLI_HELP = `heyspex-mcp login — pair this machine through your browser (nothing to type)
+
+Usage:
+  node vendor/heyspex-mcp/cli.mjs login [--console-url <url>] [--label <text>] [--timeout <seconds>] [--no-browser] [--json]
+  hs login [--switch-account [<id|email>] | --create-account] [--console-url <url>] [--label <text>]
+  hs login --account <id|email> [--json]
+  hs login --migrate [--dry-run] [--json]
+
+Opens your default browser at <console>/companion/connect. If you are already
+signed in there, the console mints the single-use pairing code itself and hands
+it straight back to a one-shot listener on 127.0.0.1 — no code to read, copy or
+paste. The console is then asked who the new \`hsmcp_\` bearer belongs to
+(GET /api/mcp/session, the same probe \`hs whoami\` uses), and the bearer AND the
+console URL are stored in ~/.heyspex/credentials.yaml (never in the repo) under
+THAT account, which becomes current — exactly like \`hs mcp pair\`. Accounts
+already stored on this machine stay signed in, each with its own token and
+console. If the console cannot confirm the account, nothing is stored and the
+command exits non-zero naming \`hs whoami\`.
+
+Already signed in? When the current account's stored token is confirmed by the
+same console, \`hs login\` changes nothing, opens no browser and says so (use
+--switch-account to sign in as someone else). Every run ends with a receipt:
+the account stored here next to the account GET /api/mcp/session names for that
+token. If they differ the command exits ${EXIT_RECEIPT_DISAGREE} and names
+\`${LOGIN_RECEIPT_RETRY}\`.
+
+The listener binds 127.0.0.1 only, serves exactly one exchange, verifies the
+state nonce, and closes. It gives up after ${Math.round(DEFAULT_LOGIN_TIMEOUT_MS / 1000)} seconds.
+
+Flags:
+  --console-url <url>   Override the resolved console (default: shared resolver)
+  --label <text>        Name this machine in the console session list (default: hostname)
+  --timeout <seconds>   How long to wait for the browser (default: ${Math.round(DEFAULT_LOGIN_TIMEOUT_MS / 1000)})
+  --no-browser          Print the URL and wait; don't launch anything (headless/SSH)
+  --json                Emit the same summary shape as \`hs mcp pair --json\`
+  --switch-account [<id|email>]
+                        With an account that already holds a token here: make it
+                        current (no browser, no pairing); the registry's current
+                        account moves with it. Otherwise (or with no value): the
+                        console shows "Signed in as X — continue / use a different
+                        account / create a new account" first, then pairs
+  --create-account      Same chooser, opened on "create a new account"
+  --account <id|email>  Be signed in as exactly this account. Already holding a
+                        token for it: make it current (no browser). Otherwise
+                        sign in through the account chooser; if the console
+                        confirms a DIFFERENT account, nothing is stored, the
+                        current account is unchanged and the command exits ${EXIT_ACCOUNT_MISMATCH}
+  --migrate           Re-key an existing single-account credentials file under
+                        the account the console confirms for its token (no pairing)
+  --dry-run             With --migrate: print the plan, write nothing
+
+Check which account this machine is signed in as: \`hs whoami\`. Sign out: \`hs logout\`.
+
+Pairing a machine from a browser on a DIFFERENT computer? That case cannot use
+a loopback redirect — use the typed-code fallback: \`hs mcp pair <code>\`.
+
+[[HS-IFQM-IZQ7-EPIC-hs-login-browser-hand-off-for-cli-and]] ·
+[[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]].
+`;
+
+export function parseLoginCliArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { help: true };
+  let consoleUrlOverride;
+  let label;
+  let json = false;
+  let openBrowser = true;
+  let timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS;
+  let prompt;
+  let switchTarget;
+  let migrate = false;
+  let dryRun = false;
+  let account;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--console-url') { consoleUrlOverride = argv[i + 1]; i += 1; continue; }
+    // `hs login --account <id|email>` (the repair HS-VWUD's account_token_missing
+    // refusal names): a required value, never a following flag.
+    if (arg === '--account') {
+      const value = argv[i + 1];
+      if (typeof value !== 'string' || !value.trim() || value.startsWith('-')) {
+        return { error: { message: '--account expects an account id or email', code: 2 } };
+      }
+      account = value.trim();
+      i += 1;
+      continue;
+    }
+    if (arg === '--label') { label = argv[i + 1]; i += 1; continue; }
+    if (arg === '--json') { json = true; continue; }
+    if (arg === '--no-browser') { openBrowser = false; continue; }
+    if (arg === '--migrate') { migrate = true; continue; }
+    if (arg === '--dry-run') { dryRun = true; continue; }
+    if (arg === '--switch-account' || arg === '--create-account') {
+      const next = arg === '--switch-account' ? 'select_account' : 'create';
+      if (prompt && prompt !== next) {
+        return { error: { message: '--switch-account and --create-account are mutually exclusive', code: 2 } };
+      }
+      prompt = next;
+      // `--switch-account <id|email>`: an optional value (anything not a flag).
+      const value = argv[i + 1];
+      if (arg === '--switch-account' && typeof value === 'string' && value && !value.startsWith('-')) {
+        switchTarget = value.trim();
+        i += 1;
+      }
+      continue;
+    }
+    if (arg === '--timeout') {
+      const seconds = Number(argv[i + 1]);
+      i += 1;
+      if (!Number.isFinite(seconds) || seconds <= 0) {
+        return { error: { message: '--timeout expects a positive number of seconds', code: 2 } };
+      }
+      timeoutMs = Math.round(seconds * 1000);
+      continue;
+    }
+    return {
+      error: {
+        message:
+          `unknown argument \`${arg}\`\n` +
+          '  Usage: hs login [--switch-account [<id|email>] | --create-account] [--console-url <url>] [--label <text>] [--timeout <seconds>] [--no-browser] [--json]\n' +
+          '         hs login --account <id|email> [--json]\n' +
+          '         hs login --migrate [--dry-run] [--json]\n' +
+          '  (a pairing code you typed by hand goes to `hs mcp pair <code>`)',
+        code: 2,
+      },
+    };
+  }
+  if (dryRun && !migrate) {
+    return { error: { message: '--dry-run only applies to --migrate', code: 2 } };
+  }
+  if (migrate && prompt) {
+    return { error: { message: '--migrate does not pair; drop --switch-account / --create-account', code: 2 } };
+  }
+  if (account && (prompt || migrate)) {
+    return {
+      error: { message: '--account names the one account to be signed in as; drop --switch-account / --create-account / --migrate', code: 2 },
+    };
+  }
+  return { consoleUrlOverride, label, json, openBrowser, timeoutMs, prompt, switchTarget, migrate, dryRun, account };
+}
+
+/**
+ * `hs login --switch-account <id|email>` when that account already holds a
+ * token here: make it current in the credentials store AND registry.json
+ * (`account-switch.mjs`), with no browser and no pairing. Returns `null` when
+ * the account is not stored (the caller then pairs).
+ */
+function switchToStoredAccount({ target, homeDir, env, json, stdout }) {
+  const store = readCredentialsStore({ homeDir });
+  const match = findStoredAccount(store, target);
+  if (!match?.mcp_token || match.accountId === LEGACY_ACCOUNT_ID) return null;
+  const before = readLoginLocalSide({ homeDir, env });
+  const result = switchCurrentAccount({ homeDir, accountId: match.accountId });
+  // A stored-account switch makes no network call, so the receipt's cloud
+  // side is honestly "not read" (`hs whoami` asks the console).
+  const receipt = buildLoginReceipt({
+    local: readLoginLocalSide({ homeDir, env }),
+    cloud: unreadSide('a stored-account switch makes no network call -- confirm with `hs whoami`'),
+    before: { local: before },
+  });
+  const already = before.read && before.account_id === match.accountId;
+  const summary = {
+    switched: !already,
+    method: 'switch',
+    accountId: match.accountId,
+    email: match.email,
+    consoleUrl: match.console_url,
+    credentialsPath: result.credentialsPath,
+    registryCurrentAccount: result.registry.status,
+  };
+  const who = match.email ? `${match.email} (${match.accountId})` : match.accountId;
+  emitLogin({
+    json,
+    stdout,
+    summary,
+    receipt,
+    text:
+      (already
+        ? `Already signed in as ${who} — nothing to change.\n`
+        : `Switched to ${who} — no new sign-in needed.\n`) +
+      `  console:     ${match.console_url ?? '(resolved by the shared console resolver)'}\n` +
+      `  current account set in ${result.credentialsPath}` +
+      (result.registry.status === 'updated' ? ' and ~/.heyspex/registry.json' : '') +
+      '.\n  Confirm with: hs whoami\n',
+  });
+  return 0;
+}
+
+/**
+ * `hs login --migrate [--dry-run]`: the explicit v1 → v2 re-key of an existing
+ * single-account credentials file. The flat token is probed (GET
+ * /api/mcp/session) and moved under the account the console confirms for it;
+ * a failed probe writes nothing.
+ */
+async function migrateStoredCredentials({ parsed, homeDir, probe, stdout, stderr, resolveConsoleUrl }) {
+  const store = readCredentialsStore({ homeDir });
+  const emit = (payload, line) => {
+    stdout.write(parsed.json ? `${JSON.stringify(payload, null, 2)}\n` : `${line}\n`);
+    return 0;
+  };
+  if (store.schemaVersion === 2) {
+    return emit(
+      { action: 'already-v2', currentAccountId: store.currentAccountId },
+      'Credentials are already stored per account; nothing to migrate.',
+    );
+  }
+  const legacy = store.accounts[LEGACY_ACCOUNT_ID];
+  if (!legacy?.mcp_token) {
+    return emit({ action: 'nothing-to-migrate' }, 'No stored sign-in to migrate. Run: hs login');
+  }
+  const consoleUrl = (parsed.consoleUrlOverride ?? legacy.console_url ?? resolveConsoleUrl())
+    .trim()
+    .replace(/\/+$/, '');
+  const identity = await probe({ consoleUrl, token: legacy.mcp_token });
+  if (identity?.kind !== 'identified') {
+    stderr.write(
+      `[heyspex-mcp login] --migrate: the console did not confirm which account the stored token belongs to ` +
+        `(${describeProbeFailure(identity)}). Nothing was changed. Run \`hs whoami\`, or \`hs login\` to sign in again.\n`,
+    );
+    return 1;
+  }
+  const plan = migrateLegacyCredentials({
+    homeDir,
+    confirmedAccountId: identity.accountId,
+    email: identity.email,
+    apply: !parsed.dryRun,
+  });
+  const registry = parsed.dryRun
+    ? { status: 'dry-run' }
+    : followCurrentAccountInRegistry({ homeDir, accountId: identity.accountId });
+  const configNote =
+    store.legacyAccountId && store.legacyAccountId !== identity.accountId
+      ? ` (~/.heyspex/config.yaml said ${store.legacyAccountId}; the console's answer wins)`
+      : '';
+  return emit(
+    {
+      action: plan.action,
+      dryRun: parsed.dryRun,
+      accountId: identity.accountId,
+      email: identity.email,
+      path: plan.path,
+      registryCurrentAccount: registry.status,
+    },
+    `${parsed.dryRun ? 'Would re-key' : 'Re-keyed'} the stored sign-in under ${formatIdentity(identity)}${configNote}.\n` +
+      `  file: ${plan.path}${parsed.dryRun ? '\n  Nothing was written (--dry-run).' : ''}`,
+  );
+}
+
+/**
+ * `hs login` — the browser hand-off (RFC 8252 loopback), replacing the
+ * mint-a-code-and-paste-it ceremony with one click. Shares its redemption and
+ * its credential write with `hs mcp pair`; only the code's carrier differs.
+ *
+ * `deps` exists for tests: it stubs the browser launch, the listener and the
+ * output streams so the flow can be exercised without opening a real browser,
+ * reaching a console, or monkeypatching process.stdout (which would swallow
+ * the test runner's own reporter output).
+ */
+export async function runLoginCli(argv, deps = {}) {
+  const {
+    openBrowser: openBrowserFn = openBrowserDefault,
+    startListener = startCallbackListenerDefault,
+    redeem = redeemAndStorePairingCode,
+    generateState = generateLoginState,
+    probe = probeCredentialIdentity,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    homeDir = homedir(),
+    resolveConsoleUrl = getConsoleUrl,
+    env = process.env,
+  } = deps;
+
+  const parsed = parseLoginCliArgs(argv);
+  if (parsed.help) {
+    stdout.write(`${LOGIN_CLI_HELP}\n`);
+    return 0;
+  }
+  if (parsed.error) {
+    stderr.write(`[heyspex-mcp login] ${parsed.error.message}\n`);
+    return parsed.error.code;
+  }
+
+  if (parsed.migrate) {
+    return migrateStoredCredentials({ parsed, homeDir, probe, stdout, stderr, resolveConsoleUrl });
+  }
+
+  // `--switch-account <id|email>` / `--account <id|email>` naming an account
+  // that already holds a token here: switch without pairing. Otherwise fall
+  // through to the browser.
+  const storedTarget = parsed.account ?? parsed.switchTarget;
+  if (storedTarget) {
+    const switched = switchToStoredAccount({ target: storedTarget, homeDir, env, json: parsed.json, stdout });
+    if (switched !== null) return switched;
+  }
+
+  const consoleUrl = parsed.consoleUrlOverride
+    ? parsed.consoleUrlOverride.trim().replace(/\/+$/, '')
+    : resolveConsoleUrl();
+
+  // The receipt's "before" read of this machine (HS-CRNE): its `changed` is
+  // what this run moved.
+  const before = readLoginLocalSide({ homeDir, env });
+
+  // A plain re-run while signed in is a no-op (invariant 6): the current
+  // account's stored token, on this same console, is asked who it belongs to.
+  // Confirmed -> nothing to do, no browser, no pairing write. A disagreement
+  // is the receipt's (exit 21, retry `hs login --switch-account`). A token
+  // the console no longer accepts (or cannot answer for) signs in again.
+  if (!parsed.prompt && !parsed.switchTarget && !parsed.account) {
+    const { store, id, entry } = currentStoredAccount(homeDir);
+    if (store.schemaVersion === 2 && entry?.mcp_token && sameConsoleUrl(entry.console_url, consoleUrl)) {
+      const cloud = await readLoginCloudSide({ homeDir, probe, fallbackConsoleUrl: consoleUrl });
+      if (cloud.read) {
+        const local = readLoginLocalSide({ homeDir, env });
+        const receipt = buildLoginReceipt({ local, cloud, before: { local: before } });
+        const who = formatIdentity({ accountId: id, email: entry.email ?? null });
+        emitLogin({
+          json: parsed.json,
+          stdout,
+          receipt,
+          summary: {
+            paired: false,
+            method: 'already-signed-in',
+            userId: id,
+            email: entry.email ?? null,
+            consoleUrl: entry.console_url,
+            currentAccountId: id,
+            storedAccounts: Object.keys(store.accounts),
+          },
+          text: receipt.agree
+            ? `Already signed in as ${who} on ${entry.console_url} — nothing to change.\n` +
+              '  Sign in as someone else: hs login --switch-account\n'
+            : `Signed in here as ${who}, but the console says that token belongs to another account.\n`,
+        });
+        return loginReceiptExit(receipt);
+      }
+    }
+  }
+
+  const state = generateState();
+
+  let listener;
+  try {
+    listener = await startListener({ expectedState: state, timeoutMs: parsed.timeoutMs });
+  } catch (err) {
+    stderr.write(
+      `[heyspex-mcp login] could not open a local listener on 127.0.0.1: ${err?.message ?? err}\n` +
+        '  Fall back to the typed code: hs mcp pair <code>\n',
+    );
+    return 1;
+  }
+
+  const connectUrl = buildConnectUrl({
+    consoleUrl,
+    port: listener.port,
+    state,
+    client: 'cli',
+    label: parsed.label ?? hostname(),
+    // `--account <id>` that is not stored here opens the account chooser, so
+    // the browser's current session is not silently reused for it.
+    ...(parsed.prompt || parsed.account ? { prompt: parsed.prompt ?? 'select_account' } : {}),
+  });
+
+  // In --json mode stdout stays pure JSON, so progress goes to stderr — a
+  // headless box still sees the URL it needs to paste.
+  const progress = parsed.json ? stderr : stdout;
+  if (parsed.openBrowser) {
+    const launched = openBrowserFn(connectUrl);
+    progress.write(
+      launched
+        ? 'Opening your browser to finish sign-in...\n'
+        : 'Could not launch a browser on this machine.\n',
+    );
+  }
+  progress.write(
+    `  If it doesn't open, paste this into a signed-in browser:\n    ${connectUrl}\n` +
+      `  Waiting up to ${Math.round(parsed.timeoutMs / 1000)}s (listening on 127.0.0.1:${listener.port})...\n`,
+  );
+
+  const outcome = await listener.waitForCallback();
+
+  if (!outcome.ok) {
+    const detail = describeCallbackFailure(outcome.reason);
+    stderr.write(
+      `[heyspex-mcp login] sign-in did not complete: ${detail}\n` +
+        '  Nothing was stored. Retry with `hs login`, or use the typed-code fallback: `hs mcp pair <code>`\n',
+    );
+    return 1;
+  }
+
+  // From here the code is treated exactly like a hand-typed one — same redeem,
+  // same credential write, same session probe for the account half. The code
+  // is NEVER printed.
+  const redeemed = await redeem({
+    consoleUrl,
+    code: outcome.code,
+    label: parsed.label,
+    probe,
+    homeDir,
+    ...(parsed.account ? { requireAccount: parsed.account } : {}),
+  });
+  if (!redeemed.ok && redeemed.mismatch) {
+    // `--account <id>` and the console confirmed someone else: nothing stored,
+    // the account-mismatch exit (20), both accounts named.
+    const { requested, accountId, email } = redeemed.mismatch;
+    if (parsed.json) {
+      stdout.write(
+        `${JSON.stringify(
+          {
+            ok: false,
+            error: 'ACCOUNT_MISMATCH',
+            message: redeemed.message,
+            requested_account: requested,
+            signed_in_account: accountId,
+            signed_in_email: email,
+            stored: false,
+            retry: `hs login --account ${requested}`,
+          },
+          null,
+          2,
+        )}\n`,
+      );
+    } else {
+      stderr.write(`[heyspex-mcp login] ${redeemed.message}\n`);
+    }
+    return EXIT_ACCOUNT_MISMATCH;
+  }
+  if (!redeemed.ok) {
+    const half = redeemed.half === 'account' ? 'account half failed: ' : '';
+    stderr.write(`[heyspex-mcp login] ${half}${redeemed.message}\n`);
+    return 1;
+  }
+
+  const summary = { ...redeemed.summary, method: 'browser' };
+  // The receipt (HS-CRNE): read back what was stored, then ask the console
+  // again -- with the token read back from disk -- who it belongs to.
+  const receipt = buildLoginReceipt({
+    local: readLoginLocalSide({ homeDir, env }),
+    cloud: await readLoginCloudSide({ homeDir, probe, fallbackConsoleUrl: consoleUrl }),
+    before: { local: before },
+  });
+  // `--switch-account <x>` that had to pair: say so when the browser signed in
+  // as someone else (the new account is stored and current either way).
+  const target = parsed.switchTarget;
+  const switchMissed =
+    target &&
+    target !== summary.userId &&
+    !(summary.email && summary.email.toLowerCase() === target.toLowerCase());
+  emitLogin({
+    json: parsed.json,
+    stdout,
+    receipt,
+    summary: { ...summary, ...(target ? { requestedAccount: target } : {}) },
+    text: `Signed in.\n${renderPairedLines(summary)}`,
+  });
+  if (switchMissed) {
+    stderr.write(
+      `[heyspex-mcp login] you asked to switch to ${target}, but the browser signed in as ` +
+        `${summary.email ? `${summary.email} (${summary.userId})` : summary.userId}. That account is stored and current; ` +
+        `run \`hs login --switch-account ${target}\` again and pick ${target} in the browser.\n`,
+    );
+    return 1;
+  }
+  return loginReceiptExit(receipt);
+}
+
+export const WHOAMI_CLI_HELP = `heyspex-mcp whoami — which account is this machine signed in as?
+
+Usage:
+  hs whoami [--account <id|email>] [--console-url <url>] [--json]
+
+Asks the console who a stored credential (~/.heyspex/credentials.yaml, written
+by \`hs login\` / \`hs mcp pair\`) belongs to, and prints the account id, email,
+token source (env | credentials-file), console URL and whether that account is
+the machine's current one. Without --account it is the CURRENT account — the
+one \`hs connect\` / \`hs install\` would attach a repo to; with --account it is
+that stored account (its own token and console). Prints no token material.
+
+Not the right account? \`hs login --switch-account <id|email>\` (or \`--create-account\`).
+
+Exit codes: 0 signed in · 16 not signed in / credential rejected / no such stored
+account · 17 the console names a different account than the one the token is
+stored under · 12 console unreachable
+
+[[HS-HAQI-KODY-DIAG-hs-install-and-hs-connect-bind-a-new]] ·
+[[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]].
+`;
+
+export function parseWhoamiCliArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { help: true };
+  let consoleUrlOverride;
+  let accountId;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--console-url') {
+      consoleUrlOverride = argv[i + 1];
+      i += 1;
+      if (!consoleUrlOverride || consoleUrlOverride.startsWith('-')) {
+        return { error: { message: '--console-url requires a URL', code: 2 } };
+      }
+      continue;
+    }
+    if (arg === '--account') {
+      accountId = argv[i + 1];
+      i += 1;
+      if (!accountId || accountId.startsWith('-')) {
+        return { error: { message: '--account requires an account id or email', code: 2 } };
+      }
+      continue;
+    }
+    if (arg === '--json') { json = true; continue; }
+    return {
+      error: {
+        message: `unknown argument \`${arg}\`\n  Usage: hs whoami [--account <id|email>] [--console-url <url>] [--json]`,
+        code: 2,
+      },
+    };
+  }
+  return accountId === undefined ? { consoleUrlOverride, json } : { consoleUrlOverride, json, accountId };
+}
+
+/**
+ * Which stored account a `hs whoami` / `hs logout` invocation is about, from
+ * the credentials store: the named one (`--account <id|email>`), else the
+ * current one. On a v1 file the single flat token is the account the
+ * `config.yaml` `account_id` names (read-compatible, no migration needed).
+ * Pure over the store read. `found: false` only when an account was NAMED and
+ * is not stored.
+ */
+function selectStoredAccount(store, named) {
+  const v1Id = store.schemaVersion === 1 && store.accounts[LEGACY_ACCOUNT_ID] ? store.legacyAccountId : null;
+  const currentId = store.schemaVersion === 2 ? store.currentAccountId : v1Id ?? (store.accounts[LEGACY_ACCOUNT_ID] ? LEGACY_ACCOUNT_ID : null);
+  if (!named) {
+    const entry = currentId ? store.accounts[currentId] ?? store.accounts[LEGACY_ACCOUNT_ID] : null;
+    return { found: true, accountId: currentId, entry: entry ?? null, currentId };
+  }
+  const match = findStoredAccount(store, named) ?? (v1Id && named === v1Id ? { accountId: v1Id, ...store.accounts[LEGACY_ACCOUNT_ID] } : null);
+  if (!match) return { found: false, accountId: null, entry: null, currentId };
+  const { accountId, ...entry } = match;
+  return { found: true, accountId, entry, currentId };
+}
+
+/**
+ * `hs whoami` — print the account a stored credential belongs to. Shares its
+ * probe with the install/connect identity gate (`whoami.mjs`), so the answer
+ * here is the account those verbs would bind.
+ */
+export async function runWhoamiCli(argv, deps = {}) {
+  const {
+    probe = probeCredentialIdentity,
+    readBearer: readBearerDep,
+    env = process.env,
+    homeDir = homedir(),
+    stdout = process.stdout,
+    stderr = process.stderr,
+    resolveConsoleUrl = getConsoleUrl,
+  } = deps;
+  const parsed = parseWhoamiCliArgs(argv);
+  if (parsed.help) {
+    stdout.write(`${WHOAMI_CLI_HELP}\n`);
+    return 0;
+  }
+  if (parsed.error) {
+    stderr.write(`[heyspex-mcp whoami] ${parsed.error.message}\n`);
+    return parsed.error.code;
+  }
+  const emit = (payload, line, code) => {
+    if (parsed.json) stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    else (code === 0 ? stdout : stderr).write(`${line}\n`);
+    return code;
+  };
+
+  const store = readCredentialsStore({ homeDir });
+  const selected = selectStoredAccount(store, parsed.accountId);
+  if (!selected.found) {
+    const stored = Object.keys(store.accounts).filter((id) => id !== LEGACY_ACCOUNT_ID);
+    return emit(
+      { signedIn: false, reason: 'no_such_account', account: parsed.accountId, storedAccounts: stored },
+      `No stored sign-in for ${parsed.accountId} on this machine` +
+        (stored.length > 0 ? ` (stored: ${stored.join(', ')})` : '') +
+        `.\n  Run: hs login --switch-account ${parsed.accountId}`,
+      16,
+    );
+  }
+
+  const consoleUrl = (
+    parsed.consoleUrlOverride ??
+    (parsed.accountId ? selected.entry?.console_url : null) ??
+    resolveConsoleUrl()
+  )
+    .trim()
+    .replace(/\/+$/, '');
+  // The ONE reader's verdict (env HEYSPEX_MCP_TOKEN first, then the store's
+  // named-or-current account) — token AND source, so the receipt says which
+  // bearer was confirmed ([[HS-6V9X-WW9R-TASK-make-hs-install-remote-confirm-the]]
+  // AC1/AC3). A `readBearer` dep that returns a bare token (older tests) has no source.
+  const bearer = readBearerDep
+    ? normalizeBearerVerdict(readBearerDep())
+    : readBearer({ env, homeDir, ...(parsed.accountId ? { accountId: selected.accountId } : {}) });
+  const result = await probe({ consoleUrl, token: bearer.token });
+  // What the store says this token is filed under (null for an env token, or a
+  // v1 file whose config.yaml names no account).
+  const storedAccountId =
+    bearer.source === 'credentials-file' && selected.accountId !== LEGACY_ACCOUNT_ID ? selected.accountId : null;
+  switch (result.kind) {
+    case 'identified': {
+      const current =
+        bearer.source === 'env'
+          ? result.accountId === selected.currentId
+          : !parsed.accountId || selected.accountId === selected.currentId;
+      const mismatch = storedAccountId !== null && storedAccountId !== result.accountId;
+      return emit(
+        {
+          signedIn: true,
+          accountId: result.accountId,
+          email: result.email,
+          displayName: result.displayName,
+          consoleUrl,
+          tokenSource: bearer.source,
+          storedAccountId,
+          current,
+          ...(mismatch ? { mismatch: true } : {}),
+        },
+        mismatch
+          ? `The token stored under ${storedAccountId} belongs to ${formatIdentity(result)} on ${consoleUrl}.\n` +
+              `  Sign that account in again: hs login --switch-account ${storedAccountId}`
+          : `Signed in as ${formatIdentity(result)}\n  console:  ${consoleUrl}\n` +
+              `  token:    ${describeBearerSource(bearer.source)}\n` +
+              `  current:  ${current}\n` +
+              '  Not you? hs login --switch-account <id|email>   (or --create-account)',
+        mismatch ? 17 : 0,
+      );
+    }
+    case 'no_credential':
+      return emit(
+        { signedIn: false, reason: 'no_credential', consoleUrl },
+        'Not signed in on this machine (no credential in ~/.heyspex/credentials.yaml).\n  Run: hs login',
+        16,
+      );
+    case 'rejected':
+      return emit(
+        { signedIn: false, reason: 'rejected', status: result.status, consoleUrl },
+        `The stored credential was rejected by ${consoleUrl} (HTTP ${result.status}) — revoked or from another console.\n  Run: hs login`,
+        16,
+      );
+    case 'unsupported':
+      return emit(
+        { signedIn: null, reason: 'unsupported', status: result.status, consoleUrl },
+        `${consoleUrl} does not answer whoami yet (HTTP ${result.status}); it needs the console deploy that adds GET /api/mcp/session.`,
+        12,
+      );
+    default:
+      return emit(
+        { signedIn: null, reason: 'unreachable', message: result.message, consoleUrl },
+        `Could not reach ${consoleUrl}: ${result.message}`,
+        12,
+      );
+  }
+}
+
+export const LOGOUT_CLI_HELP = `heyspex-mcp logout — sign an account out of this machine
+
+Usage:
+  hs logout [--account <id|email>] [--json]
+
+Removes ONE account's stored token and console URL from
+~/.heyspex/credentials.yaml: the named account, or (with no flag) the current
+account. Every other stored account stays signed in. Signing the current
+account out clears the machine's current account in credentials.yaml AND
+~/.heyspex/registry.json; pick the next one with \`hs login --switch-account <id>\`.
+Nothing is sent to the console (the token is not revoked there). Prints no
+token material. A HEYSPEX_MCP_TOKEN env var still outranks the file.
+
+Exit codes: 0 signed out (or nothing to sign out) · 16 no such stored account
+
+[[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]].
+`;
+
+export function parseLogoutCliArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { help: true };
+  let accountId;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--account') {
+      accountId = argv[i + 1];
+      i += 1;
+      if (!accountId || accountId.startsWith('-')) {
+        return { error: { message: '--account requires an account id or email', code: 2 } };
+      }
+      continue;
+    }
+    if (arg === '--json') { json = true; continue; }
+    return {
+      error: { message: `unknown argument \`${arg}\`\n  Usage: hs logout [--account <id|email>] [--json]`, code: 2 },
+    };
+  }
+  return { accountId, json };
+}
+
+/** `hs logout [--account <id|email>]` — remove one stored account (default: the current one). */
+export async function runLogoutCli(argv, deps = {}) {
+  const { homeDir = homedir(), env = process.env, stdout = process.stdout, stderr = process.stderr } = deps;
+  const parsed = parseLogoutCliArgs(argv);
+  if (parsed.help) {
+    stdout.write(`${LOGOUT_CLI_HELP}\n`);
+    return 0;
+  }
+  if (parsed.error) {
+    stderr.write(`[heyspex-mcp logout] ${parsed.error.message}\n`);
+    return parsed.error.code;
+  }
+  const emit = (payload, line, code) => {
+    if (parsed.json) stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    else (code === 0 ? stdout : stderr).write(`${line}\n`);
+    return code;
+  };
+  const store = readCredentialsStore({ homeDir });
+  let target = null;
+  if (parsed.accountId) {
+    const match =
+      findStoredAccount(store, parsed.accountId) ??
+      (store.schemaVersion === 1 && store.legacyAccountId === parsed.accountId && store.accounts[LEGACY_ACCOUNT_ID]
+        ? { accountId: LEGACY_ACCOUNT_ID }
+        : null);
+    if (!match) {
+      return emit(
+        { signedOut: false, reason: 'no_such_account', account: parsed.accountId },
+        `No stored sign-in for ${parsed.accountId} on this machine; nothing was removed.`,
+        16,
+      );
+    }
+    target = match.accountId;
+  }
+  const result = signOutAccount({ homeDir, accountId: target });
+  const envNote =
+    typeof env?.HEYSPEX_MCP_TOKEN === 'string' && env.HEYSPEX_MCP_TOKEN.trim()
+      ? '\n  Note: HEYSPEX_MCP_TOKEN is set in this shell and still signs requests in; unset it too.'
+      : '';
+  if (!result.removed) {
+    return emit(
+      { signedOut: false, reason: 'not_signed_in', currentAccountId: result.currentAccountId },
+      `Not signed in on this machine; nothing was removed.${envNote}`,
+      0,
+    );
+  }
+  const removedLabel = result.removed === LEGACY_ACCOUNT_ID ? store.legacyAccountId ?? 'the stored sign-in' : result.removed;
+  const remaining = Object.keys(readCredentialsStore({ homeDir }).accounts);
+  return emit(
+    {
+      signedOut: true,
+      accountId: result.removed === LEGACY_ACCOUNT_ID ? store.legacyAccountId : result.removed,
+      wasCurrent: result.wasCurrent,
+      currentAccountId: result.currentAccountId,
+      remainingAccounts: remaining,
+      registryCurrentAccount: result.registry.status,
+    },
+    `Signed out ${removedLabel}.` +
+      (result.wasCurrent
+        ? remaining.length > 0
+          ? `\n  No account is current now. Still signed in: ${remaining.join(', ')} — pick one with hs login --switch-account <id>.`
+          : '\n  No account is signed in on this machine now. Run: hs login'
+        : `\n  The current account (${result.currentAccountId}) is unchanged.`) +
+      envNote,
+    0,
+  );
+}
+
+export const CALL_CLI_HELP = `heyspex-mcp call — invoke one MCP tool and exit (no stdio loop)
+
+Usage:
+  node vendor/heyspex-mcp/cli.mjs call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]
+  hs mcp call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]
+
+Runs a single tools/call handler and exits. Use this when the MCP host does not
+expose heyspex_* tools — never pipe JSON-RPC into the long-lived stdio server.
+
+Prefer repeated --arg key=value over --args JSON (especially on Windows/PowerShell,
+where inline JSON quoting is unreliable).
+
+Examples:
+  hs mcp call heyspex_claim_spec --arg spec_id=HS-TASK-NCH5 --json
+  hs mcp call heyspex_next_on_deck --arg summary=true --arg spec_id=HS-EPIC-YQ5A --json
+  hs mcp call heyspex_validate_linkage --args '{"spec_id":"HS-EPIC-YQ5A"}' --json
+  hs mcp call heyspex_defer_spec --args-file .cursor/defer-args.json --json
+`;
+
+export async function runCallCli(argv) {
+  const parsed = parseCallCliArgs(argv);
+  if (parsed.help) {
+    process.stdout.write(`${CALL_CLI_HELP}\n`);
+    return 0;
+  }
+  if (parsed.error) {
+    process.stderr.write(`[heyspex-mcp call] ${parsed.error.message}\n`);
+    return parsed.error.code;
+  }
+  const result = await handleToolsCall({ name: parsed.tool, arguments: parsed.args });
+  const text = result?.content?.[0]?.text;
+  if (parsed.json) {
+    try {
+      process.stdout.write(`${JSON.stringify(JSON.parse(text), null, 2)}\n`);
+    } catch {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+  } else if (text) {
+    process.stdout.write(`${text}\n`);
+  } else {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+  return result?.isError ? 1 : 0;
+}
+
+export const EXPORT_CLI_HELP = `heyspex-mcp export — introspection for the stdio subprocess proxy
+
+Usage:
+  node vendor/heyspex-mcp/cli.mjs export tools-list [--json]
+
+Emits JSON for tools/list from a fresh Node process (used by the long-lived MCP
+stdio parent so tool schemas stay current without reconnecting Cursor).
+`;
+
+/**
+ * Freshness handshake (HS-G263-DIAG-2F0X): stamp what build this process IS,
+ * right now — so later drift is provable instead of silent. Never fatal: a
+ * write failure here must not block whatever caller invoked us.
+ *
+ * IMPORTANT: this must be called from every code path that determines what
+ * the MCP client believes "the running server" is currently serving — NOT
+ * just the literal stdio-bootstrap block. Under MCP_SUBPROCESS_TOOLS (the
+ * default; see mcp-subprocess.mjs), the long-lived stdio parent is spawned
+ * once per agent session and then kept alive; it never re-runs its own
+ * bootstrap block again. Every `tools/list` (and `tools/call`) the client
+ * makes after that is actually served by a FRESH short-lived
+ * `node cli.mjs export tools-list` / `call` child spawned per-request — that
+ * child sets `RUNNING_AS_CLI = true`, which always skipped the old
+ * bootstrap-only call site below. That is why a schema change (e.g.
+ * force_promote / heyspex_claim_file becoming reachable) was visible to the
+ * client with NO corresponding build-record write: the code path the client
+ * actually observed (`export tools-list`) never touched
+ * .heyspex/mcp-server-build.json. Calling it here, at the moment the fresh
+ * subprocess reports the tool catalog, is what "every server start"
+ * concretely means in this architecture — it fires on the actual signal the
+ * owner used as proof of freshness (new tools reachable).
+ */
+export function stampMcpBuildRecord() {
+  try {
+    const { vaultRoot: fingerprintVaultRoot } = getConfig();
+    writeBuildRecord({
+      vaultRoot: fingerprintVaultRoot,
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    process.stderr.write?.(`[heyspex-mcp] build fingerprint skipped: ${err?.message ?? err}\n`);
+  }
+}
+
+export async function runExportCli(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(`${EXPORT_CLI_HELP}\n`);
+    return 0;
+  }
+  const sub = argv.find((a) => !a.startsWith('-'));
+  const json = argv.includes('--json');
+  if (sub === 'tools-list') {
+    // Stamp BEFORE emitting: the payload we're about to hand back IS "the
+    // running server's schema" from the client's perspective, so the build
+    // record must reflect this exact fingerprint, not a stale parent-startup
+    // snapshot. See stampMcpBuildRecord() doc above.
+    stampMcpBuildRecord();
+    const payload = handleToolsList();
+    process.stdout.write(`${JSON.stringify(payload, null, json ? 2 : 0)}\n`);
+    return 0;
+  }
+  process.stderr.write('[heyspex-mcp export] usage: export tools-list [--json]\n');
+  return 2;
+}
+
+// ─── `hs mcp install --remote` ────────────────────────────────────────────────
+// Writes (or prints) the Claude Code project `.mcp.json` that points at the
+// REMOTE MCP endpoint — `POST <console>/api/mcp`, the Streamable-HTTP form —
+// instead of spawning this stdio server. The bearer minted by `hs login` /
+// `hs mcp pair` is referenced BY ENV NAME, never inlined: the file is
+// routinely committed, and a literal `hsmcp_` token in it would be a leaked
+// credential. Same two artifacts `hs install --remote` produces
+// (spex-console/src/lib/cli/install.ts `renderRemoteClaudeMcpJson` /
+// `buildClaudeMcpAddRemoteCommandPowerShell`) — keep the shapes in step; that
+// module is the one under unit test and this verb is its no-TypeScript face
+// for a machine that only has the packed MCP server.
+
+/** Env var the generated config references for the `hsmcp_` bearer. */
+export const REMOTE_MCP_TOKEN_ENV = 'HEYSPEX_MCP_TOKEN';
+
+export const MCP_INSTALL_CLI_HELP = `heyspex-mcp install — wire a client to the HeySpex MCP server
+
+Usage:
+  node vendor/heyspex-mcp/cli.mjs install --remote [--console-url <url>] [--write] [--json]
+  hs mcp install --remote [--console-url <url>] [--write] [--json]
+
+--remote is currently required: this verb exists for the CLOUD endpoint
+(\`POST <console>/api/mcp\`). The local stdio wiring is \`hs install\`, which
+also writes specs/, heyspex.yaml and the agent contract.
+
+Prints the \`.mcp.json\` block and the equivalent \`claude mcp add --transport
+http …\` command. Nothing is written unless --write is passed.
+
+--write reads the existing .mcp.json first. When a stdio \`heyspex\` entry
+carrying env.HEYSPEX_VAULT_ROOT (the local vault pin — same key \`hs install\`
+and the satellite attachment write) is present, that entry is preserved
+byte-for-byte under its existing key and the cloud form is written under a
+second key (\`heyspex-cloud\`) instead of overwriting it — the local pin and
+the cloud endpoint live side by side. With no pin present, the write still
+lands under the single \`heyspex\` key, matching today's output.
+
+  --console-url <url>  Console origin (default: the resolved console URL).
+  --write              Write .mcp.json into the resolved vault root,
+                        preserving any stdio vault pin under a second key.
+                        Confirms FIRST (GET /api/mcp/session) that the bearer
+                        the manifest will use belongs to the account this repo
+                        is recorded under (heyspex.yaml account:, else this
+                        machine's configured account); a mismatch refuses
+                        (exit 17) naming both accounts and
+                        \`hs login --switch-account\`, and writes nothing.
+  --json               Emit { url, mcp_json, claude_command, wrote, bearer,
+                        account, token_source } instead (never the token).
+
+Auth: pair the machine first (\`hs login\`, or \`hs mcp pair <code>\`). Once
+paired, an already-paired machine resolves the bearer automatically from
+~/.heyspex/credentials.yaml's \`mcp_token\` (same precedence as every other
+cloud call: ${REMOTE_MCP_TOKEN_ENV} env first, credentials-store fallback) —
+no unconditional export is required. The generated \`.mcp.json\` still stores
+\${${REMOTE_MCP_TOKEN_ENV}} as an env REFERENCE (never the literal token, and
+never into a committed file); export ${REMOTE_MCP_TOKEN_ENV} in the shell
+that launches the client only if that client does not itself read
+~/.heyspex/credentials.yaml.`;
+
+/** Endpoint URL for a console origin (idempotent if it already ends in /api/mcp). */
+export function remoteMcpEndpoint(consoleUrl) {
+  const base = String(consoleUrl ?? '').trim().replace(/\/+$/, '');
+  if (!base) return '';
+  return /\/api\/mcp$/.test(base) ? base : `${base}/api/mcp`;
+}
+
+/** The `.mcp.json` object for the remote endpoint (env-reference auth). */
+export function renderRemoteMcpJson(url) {
+  return {
+    mcpServers: {
+      heyspex: {
+        type: 'http',
+        url,
+        headers: { Authorization: `Bearer \${${REMOTE_MCP_TOKEN_ENV}}` },
+      },
+    },
+  };
+}
+
+/**
+ * The equivalent one-liner. The header is SINGLE-quoted so PowerShell does
+ * not expand the reference — the literal `${HEYSPEX_MCP_TOKEN}` is what gets
+ * stored, exactly as in the JSON form.
+ */
+export function buildRemoteClaudeMcpAddCommand(url) {
+  return (
+    `claude mcp add --transport http --scope project heyspex '${String(url).replace(/'/g, "''")}' `
+    + `--header 'Authorization: Bearer \${${REMOTE_MCP_TOKEN_ENV}}'`
+  );
+}
+
+/**
+ * Detect a stdio `heyspex` entry carrying `env.HEYSPEX_VAULT_ROOT` — the
+ * local vault pin (an ordinary `hs install` or an `--attach-vault` satellite
+ * write both put it there, see `spex-console/src/lib/cli/install.ts`
+ * `renderClaudeMcpJson`) — in a parsed `.mcp.json` object. Returns the entry
+ * object, or `null` when no such pin is present (missing file, missing key,
+ * a non-stdio transport, or no vault-root env). Pure and never throws.
+ */
+export function findStdioVaultPin(mcpJson) {
+  const entry = mcpJson?.mcpServers?.heyspex;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null;
+  if (entry.type !== 'stdio') return null;
+  const env = entry.env;
+  if (!env || typeof env !== 'object' || Array.isArray(env)) return null;
+  const pin = env.HEYSPEX_VAULT_ROOT;
+  return typeof pin === 'string' && pin.trim() ? entry : null;
+}
+
+/** Read + JSON.parse an existing `.mcp.json`, or `null` if absent/unparseable. Never throws. */
+function readExistingMcpJson(target) {
+  try {
+    return JSON.parse(readFileSync(target, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge the remote cloud entry into an existing `.mcp.json`. When a stdio
+ * vault pin ({@link findStdioVaultPin}) is present under `heyspex`, that
+ * entry is left untouched (same object, so its serialization is
+ * byte-for-byte identical) and the cloud form is written under a second key,
+ * `heyspex-cloud` — `--remote --write` must not detach a project from its
+ * pinned vault ([[HS-D1QU-B0IT-EPIC-cloud-mcp-alongside-the-satellite-pin]]).
+ * With no pin, keeps today's single-key `heyspex` shape. Any other top-level
+ * keys in the existing file (and any other existing `mcpServers` entries)
+ * are preserved untouched. Pure.
+ */
+export function mergeRemoteMcpJson(existingJson, cloudEntry) {
+  const base =
+    existingJson && typeof existingJson === 'object' && !Array.isArray(existingJson) ? existingJson : {};
+  const existingServers =
+    base.mcpServers && typeof base.mcpServers === 'object' && !Array.isArray(base.mcpServers)
+      ? base.mcpServers
+      : {};
+  const pin = findStdioVaultPin(base);
+  const mergedServers = { ...existingServers };
+  if (pin) {
+    mergedServers['heyspex-cloud'] = cloudEntry;
+  } else {
+    mergedServers.heyspex = cloudEntry;
+  }
+  return { ...base, mcpServers: mergedServers };
+}
+
+/**
+ * Resolve whether an `Authorization` bearer is available for this machine,
+ * and where it would come from — same precedence as console-fetch.mjs's
+ * {@link getAuthHeader} (env `HEYSPEX_MCP_TOKEN` first, then
+ * `~/.heyspex/credentials.yaml`'s `mcp_token`, written by `hs login` / `hs
+ * mcp pair`). NEVER returns the literal token — only a resolved/source
+ * verdict — so callers can steer printed guidance and JSON output without
+ * ever risking the value landing in a committed file
+ * ([[HS-D1QU-B0IT-EPIC-cloud-mcp-alongside-the-satellite-pin]] AC4).
+ */
+export function resolveInstallBearer({ env = process.env, homeDir = homedir() } = {}) {
+  // The ONE shared reader (./credentials.mjs, HS-HL0D) — the same precedence
+  // the MCP runtime, `hs whoami` and the CLI gate use; only its SOURCE leaves
+  // this function. `credentials` keeps this verb's pinned --json vocabulary.
+  const { source } = readBearer({ env, homeDir });
+  if (source === 'env') return { resolved: true, source: 'env' };
+  if (source === 'credentials-file') return { resolved: true, source: 'credentials' };
+  return { resolved: false, source: null };
+}
+
+/**
+ * Accept either a bare token (string | null — what an older `readBearer` dep
+ * or `readStoredBearer` returns) or the shared reader's `{ token, source }`.
+ * @returns {{ token: string | null, source: 'env' | 'credentials-file' | null }}
+ */
+export function normalizeBearerVerdict(value) {
+  if (value && typeof value === 'object') {
+    const token = typeof value.token === 'string' && value.token.trim() ? value.token.trim() : null;
+    const source = token && (value.source === 'env' || value.source === 'credentials-file') ? value.source : null;
+    return { token, source };
+  }
+  const token = typeof value === 'string' && value.trim() ? value.trim() : null;
+  return { token, source: null };
+}
+
+// Anchored to a TOP-LEVEL `account:` line of heyspex.yaml — the same shape
+// spex-console/src/lib/cli/install-identity.ts `parseMarkerAccount` reads.
+const MARKER_ACCOUNT_LINE_RE = /^account:[ \t]*["']?([^"'\r\n#]+)/m;
+
+/**
+ * The account a repo is recorded under: `heyspex.yaml` `account:` in
+ * `vaultRoot` when the marker names one (written once
+ * [[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]] lands), else this
+ * machine's configured account (`HS_ACCOUNT_ID`, then config.yaml — the ONE
+ * account reader, ./session-owner.mjs), else `null` ("unrecorded"). Never
+ * throws.
+ * @param {{ vaultRoot: string, env?: object, homeDir?: string }} opts
+ * @returns {{ accountId: string, source: 'heyspex.yaml' | 'config.yaml' } | null}
+ */
+export function readRecordedRepoAccount({ vaultRoot, env = process.env, homeDir = homedir() }) {
+  let marker = null;
+  try {
+    marker = readFileSync(join(vaultRoot, 'heyspex.yaml'), 'utf8');
+  } catch {
+    marker = null;
+  }
+  const fromMarker = typeof marker === 'string' ? marker.match(MARKER_ACCOUNT_LINE_RE)?.[1]?.trim() : '';
+  if (fromMarker) return { accountId: fromMarker, source: 'heyspex.yaml' };
+  const configured = resolveSessionOwnerUncached({ env, homeDir });
+  return configured ? { accountId: configured, source: 'config.yaml' } : null;
+}
+
+/**
+ * The pure decision behind `hs mcp install --remote --write`'s confirmation
+ * ([[HS-6V9X-WW9R-TASK-make-hs-install-remote-confirm-the]] AC2/AC3): given
+ * the GET /api/mcp/session verdict for the bearer this manifest will use, the
+ * repo's recorded account and the bearer's source, either proceed with an
+ * `hs whoami`-style receipt or refuse (exit 20 `ACCOUNT_MISMATCH` when the
+ * repo's heyspex.yaml records another account, 17 `IDENTITY_UNCONFIRMED` when
+ * only this machine's configured account differs -- both naming both accounts
+ * and the repair command; 16 when not
+ * signed in / rejected; 12 when the console cannot answer). Never includes
+ * token material.
+ * @param {{ probe: object, recorded: { accountId: string, source: string } | null, consoleUrl: string, tokenSource: string | null }} input
+ */
+export function decideRemoteInstallAccount({ probe, recorded, consoleUrl, tokenSource }) {
+  const refuse = (code, error, message, extra = {}) => ({
+    ok: false,
+    code,
+    message: `[heyspex-mcp install] refusing -- ${message} Nothing was written.`,
+    payload: { ok: false, error, message, ...extra },
+  });
+  if (probe.kind === 'no_credential') {
+    return refuse(16, 'sign_in_required', 'this machine is not signed in to HeySpex. Run `hs login` first.');
+  }
+  if (probe.kind === 'rejected') {
+    return refuse(
+      16,
+      'sign_in_required',
+      `the stored sign-in was rejected by ${consoleUrl} (HTTP ${probe.status}) -- revoked, or from another console. Run \`hs login\` first.`,
+    );
+  }
+  if (probe.kind === 'unsupported') {
+    return refuse(
+      12,
+      'console_unsupported',
+      `${consoleUrl} cannot confirm whose sign-in this is yet (HTTP ${probe.status}); it needs the console deploy that adds GET /api/mcp/session.`,
+    );
+  }
+  if (probe.kind !== 'identified') {
+    return refuse(
+      12,
+      'console_unreachable',
+      `could not reach ${consoleUrl} to confirm which account this token belongs to (${probe.message}).`,
+    );
+  }
+  const identity = { accountId: probe.accountId, email: probe.email };
+  const shown = `${formatIdentity(identity)} [token: ${describeBearerSource(tokenSource)}]`;
+  if (recorded && recorded.accountId !== identity.accountId) {
+    // The repo's COMMITTED marker names the account: an account mismatch,
+    // the same exit (20 `ACCOUNT_MISMATCH`) and repair `hs connect` / `hs
+    // install --remote` give ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]],
+    // install-identity.ts). Compared only with this machine's configured
+    // account (no `account:` in the marker) it stays unconfirmed (17).
+    const fromMarker = recorded.source === 'heyspex.yaml';
+    const repair = fromMarker ? `hs login --account ${recorded.accountId}` : 'hs login --switch-account';
+    return refuse(
+      fromMarker ? EXIT_ACCOUNT_MISMATCH : 17,
+      fromMarker ? 'ACCOUNT_MISMATCH' : 'identity_unconfirmed',
+      `this repo is recorded under account ${recorded.accountId} (${recorded.source}), but the token this install would wire belongs to ${shown}. ` +
+        `Sign in as the repo's account with \`${repair}\`, then re-run (or pass --account ${recorded.accountId} to \`hs install --remote\`).`,
+      {
+        repo_account: recorded.accountId,
+        repo_account_source: recorded.source,
+        signed_in_account: identity.accountId,
+        signed_in_email: identity.email,
+        token_source: tokenSource,
+        repair,
+      },
+    );
+  }
+  const repoLine = !recorded
+    ? '  repo:     unrecorded (heyspex.yaml has no account:, no account_id in ~/.heyspex/config.yaml) -- using the signed-in account'
+    : recorded.source === 'heyspex.yaml'
+      ? `  repo:     ${recorded.accountId} (heyspex.yaml) -- matches the signed-in account`
+      : `  repo:     unrecorded in heyspex.yaml -- compared with this machine's configured account ${recorded.accountId} (~/.heyspex/config.yaml), which matches`;
+  return {
+    ok: true,
+    receipt: [`Signed in as ${formatIdentity(identity)}`, `  token:    ${describeBearerSource(tokenSource)}`, repoLine],
+    account: {
+      account_id: identity.accountId,
+      email: identity.email,
+      repo_account: recorded?.accountId ?? null,
+      repo_account_source: recorded?.source ?? 'unrecorded',
+    },
+  };
+}
+
+/**
+ * `deps` exists for tests (mirrors {@link runLoginCli}): it injects the
+ * resolved vault root, the env/homeDir bearer resolution reads, and the
+ * output streams, so the read-before-write merge and the bearer-resolution
+ * guidance can be exercised without touching this machine's real
+ * `~/.heyspex/` or the checkout's own `.mcp.json`.
+ */
+export async function runMcpInstallCli(argv, deps = {}) {
+  const {
+    env = process.env,
+    homeDir = homedir(),
+    stdout = process.stdout,
+    stderr = process.stderr,
+    vaultRoot: vaultRootOverride,
+    probe = probeCredentialIdentity,
+  } = deps;
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    stdout.write(`${MCP_INSTALL_CLI_HELP}\n`);
+    return 0;
+  }
+  if (!argv.includes('--remote')) {
+    stderr.write('[heyspex-mcp install] --remote is required (local stdio wiring is `hs install`)\n');
+    return 2;
+  }
+  const json = argv.includes('--json');
+  const write = argv.includes('--write');
+  const overrideIdx = argv.indexOf('--console-url');
+  const override = overrideIdx >= 0 ? argv[overrideIdx + 1] : undefined;
+  const consoleOrigin = String(override ?? getConsoleUrl()).trim().replace(/\/+$/, '').replace(/\/api\/mcp$/, '');
+  const url = remoteMcpEndpoint(override ?? getConsoleUrl());
+  if (!url) {
+    stderr.write('[heyspex-mcp install] could not resolve a console URL\n');
+    return 1;
+  }
+
+  const mcpJson = renderRemoteMcpJson(url);
+  const cloudEntry = mcpJson.mcpServers.heyspex;
+  const command = buildRemoteClaudeMcpAddCommand(url);
+  const bearer = resolveInstallBearer({ env, homeDir });
+  // The ONE reader's full verdict — the token is used ONLY to ask the console
+  // whose it is; it never reaches stdout, stderr or a written file.
+  const bearerVerdict = readBearer({ env, homeDir });
+
+  let vaultRoot = null;
+  if (write) {
+    try {
+      vaultRoot = vaultRootOverride ?? getConfig().vaultRoot;
+    } catch (err) {
+      stderr.write(`[heyspex-mcp install] could not resolve the vault root: ${err?.message ?? err}\n`);
+      return 1;
+    }
+  }
+
+  // --write confirms, BEFORE writing, that the bearer this manifest will use
+  // belongs to the account this repo is recorded under: GET /api/mcp/session
+  // names the token's account; heyspex.yaml `account:` (else this machine's
+  // configured account) names the repo's. A loopback console binds no cloud
+  // account and is not gated — the same rule as the `hs install` gate
+  // ([[HS-6V9X-WW9R-TASK-make-hs-install-remote-confirm-the]] AC2).
+  let confirmation = null;
+  if (write && !isLoopbackConsoleUrl(consoleOrigin)) {
+    const probed = await probe({ consoleUrl: consoleOrigin, token: bearerVerdict.token });
+    const verdict = decideRemoteInstallAccount({
+      probe: probed,
+      recorded: readRecordedRepoAccount({ vaultRoot, env, homeDir }),
+      consoleUrl: consoleOrigin,
+      tokenSource: bearerVerdict.source,
+    });
+    if (!verdict.ok) {
+      if (json) stdout.write(`${JSON.stringify({ ...verdict.payload, wrote: null, token_source: bearerVerdict.source }, null, 2)}\n`);
+      else stderr.write(`${verdict.message}\n`);
+      return verdict.code;
+    }
+    confirmation = verdict;
+  }
+
+  let wrote = null;
+  let outputJson = mcpJson;
+  if (write) {
+    try {
+      const target = join(vaultRoot, '.mcp.json');
+      const existing = readExistingMcpJson(target);
+      const merged = mergeRemoteMcpJson(existing, cloudEntry);
+      writeFileSync(target, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+      wrote = target;
+      outputJson = merged;
+    } catch (err) {
+      stderr.write(`[heyspex-mcp install] could not write .mcp.json: ${err?.message ?? err}\n`);
+      return 1;
+    }
+  }
+
+  const body = `${JSON.stringify(outputJson, null, 2)}\n`;
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          url,
+          mcp_json: outputJson,
+          claude_command: command,
+          wrote,
+          bearer,
+          // The receipt: which account the bearer was confirmed as (null when
+          // this run did not confirm one -- print-only, or a loopback console)
+          // and where the bearer came from. Never the token itself.
+          account: confirmation?.account ?? null,
+          token_source: bearerVerdict.source,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return 0;
+  }
+
+  const confirmationBlock = confirmation ? `${confirmation.receipt.join('\n')}\n\n` : '';
+
+  const bearerGuidance = bearer.resolved
+    ? bearer.source === 'env'
+      ? `Then launch the client — ${REMOTE_MCP_TOKEN_ENV} is already set in this shell.\n`
+      : `Then launch the client — this machine is already paired, so the bearer resolves from ` +
+        `~/.heyspex/credentials.yaml (mcp_token). Export ${REMOTE_MCP_TOKEN_ENV} in the shell that ` +
+        `launches the client if it does not read that file itself.\n`
+    : `Then pair the machine (\`hs login\`) and export ${REMOTE_MCP_TOKEN_ENV} before launching the client.\n`;
+
+  stdout.write(
+    `HeySpex remote MCP → ${url}\n\n`
+    + confirmationBlock
+    + `.mcp.json${wrote ? ` (written to ${wrote})` : ' (not written — pass --write)'}:\n${body}\n`
+    + `Equivalent command:\n  ${command}\n\n`
+    + bearerGuidance,
+  );
+  return 0;
+}