heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/credentials.mjs

@@ -0,0 +1,585 @@
+// credentials.mjs — the ONE bearer reader for routing fact A ("which account is
+// this machine signed in as"), [[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]]
+// under [[HS-3PEQ-WW9R-EPIC-one-home-for-every-routing-fact-and-per]].
+//
+// Before this file, four readers parsed `~/.heyspex/credentials.yaml` with
+// different rules: the MCP transport (console-fetch.mjs) and doctor honoured
+// `HEYSPEX_MCP_TOKEN` then the `mcp_token:` key, while `hs whoami` and the CLI's
+// `readPairedToken` took the FIRST `hsmcp_`/`hscmp_` match anywhere in the file
+// and ignored the env var — so `hs whoami` could name one account while the MCP
+// server sent another. Invariant 3 (one fact, one home): every read site now
+// imports this module, and `scripts/check-shared-helpers.mjs` refuses a new
+// `credentials.yaml` token regex anywhere else.
+//
+// Precedence, everywhere:
+//   1. `HEYSPEX_MCP_TOKEN` env (trimmed; blank counts as unset)
+//   2. the top-level `mcp_token:` key of `~/.heyspex/credentials.yaml`
+//      (never a bare token-shaped regex over the whole file — a Companion
+//      `hscmp_` token under `clerk:` is NOT this machine's MCP bearer)
+//
+// Plain Node ESM, zero dependencies: spex-console imports it straight from
+// TypeScript (same as whoami.mjs), hook scripts and dev-factory import it bare.
+// Pure core ({@link resolveBearer}, {@link parseMcpToken}) + thin shell
+// ({@link readBearer}); the shell never throws — an unreadable file is "no
+// file token". Never logs token material.
+//
+// Per-account store, schema v2 ([[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]],
+// invariant 4: credentials, pointer and active vault are keyed by account and
+// switch together). The file keeps its line-oriented shape so the blocks other
+// writers own (the Companion's `clerk:`, comments, `neon:`) survive byte for byte:
+//
+//   schema_version: 2
+//   current_account_id: user_B
+//   mcp_token: hsmcp_B            # mirror of the CURRENT account (see below)
+//   console_url: https://…        # mirror of the CURRENT account's console
+//   accounts:
+//     user_A:
+//       mcp_token: "hsmcp_A"
+//       console_url: "https://…"
+//       email: "a@example.test"
+//       paired_at: "2026-10-03T…"
+//     user_B:
+//       …
+//   clerk:
+//     companion_token: …          # untouched
+//
+// The top-level `mcp_token` / `console_url` mirror the current account so every
+// reader that predates v2 (an older published MCP package, the shared console
+// resolver's `console_url:` rung, `hs dev`'s console write) keeps reading the
+// right answer with no change. This module is the only writer of the v2 keys
+// and rewrites the mirror on every write, so the two never disagree.
+//
+// A v1 file (flat `mcp_token:` / `console_url:`, no `schema_version: 2`) is read
+// as ONE account named `legacy` — nothing is rewritten on read. The account id
+// of that legacy token is the `account_id:` an earlier `hs login` left in
+// `~/.heyspex/config.yaml`; that key is now read ONLY for a v1 file, and only
+// `hs login` / `hs login --migrate` (an explicit verb, with `--dry-run`)
+// re-keys the legacy token under the account the console confirms for it.
+
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import os, { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+/** Env var that outranks the credentials file. */
+export const MCP_TOKEN_ENV = 'HEYSPEX_MCP_TOKEN';
+
+/**
+ * @typedef {'env' | 'credentials-file'} BearerSource
+ * @typedef {{ token: string | null, source: BearerSource | null }} Bearer
+ */
+
+/** `~/.heyspex/credentials.yaml` for `homeDir`. */
+export function credentialsFilePath(homeDir = heyspexHome()) {
+  return join(homeDir, '.heyspex', 'credentials.yaml');
+}
+
+// The ONE token regex. Anchored to a TOP-LEVEL `mcp_token:` line; an optional
+// quote; the value up to a quote, comment or line end. Deliberately not a
+// token-shape (`hsmcp_…`) match: the key is the fact, the prefix is not.
+// `[ \t]*` (not `\s*`): the inherited copies used `\s*`, which swallowed the
+// newline after an EMPTY `mcp_token:` line and captured the next line's text
+// as the token — the fixture case "empty mcp_token key is no token" pins it.
+const MCP_TOKEN_LINE_RE = /^mcp_token:[ \t]*["']?([^"'\r\n#]+)/m;
+
+/**
+ * The `mcp_token:` value of a credentials.yaml text, or `null` when the key is
+ * absent/empty. Pure.
+ * @param {string | null | undefined} raw
+ * @returns {string | null}
+ */
+export function parseMcpToken(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const token = raw.match(MCP_TOKEN_LINE_RE)?.[1]?.trim();
+  return token ? token : null;
+}
+
+// ---------------------------------------------------------------------------
+// The per-account store (schema v2)
+// ---------------------------------------------------------------------------
+
+/** On-disk schema this module writes. */
+export const CREDENTIALS_SCHEMA_VERSION = 2;
+
+/** The account a v1 (flat, single-token) file's token is read under. */
+export const LEGACY_ACCOUNT_ID = 'legacy';
+
+/** The per-account fields, in the order they are written. */
+const ACCOUNT_FIELDS = ['mcp_token', 'console_url', 'email', 'paired_at'];
+
+/** Top-level keys this module owns (every other top-level line is preserved). */
+const MANAGED_TOP_LEVEL_KEYS = ['schema_version', 'current_account_id', 'mcp_token', 'console_url'];
+
+// An account id is written as a bare YAML key, so it is restricted to a safe
+// alphabet (Clerk ids `user_…`, `legacy`, test ids). Anything else is refused.
+const ACCOUNT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.@+-]*$/;
+
+/**
+ * @typedef {{ mcp_token: string | null, console_url: string | null, email: string | null, paired_at: string | null }} AccountCredentials
+ * @typedef {{ schemaVersion: 1 | 2, currentAccountId: string | null, accounts: Record<string, AccountCredentials> }} CredentialsStore
+ */
+
+/** True when `id` can be stored as an account key. */
+export function isValidAccountId(id) {
+  return typeof id === 'string' && ACCOUNT_ID_RE.test(id);
+}
+
+function topLevelScalar(raw, key) {
+  const re = new RegExp(`^${key}:[ \\t]*["']?([^"'\\r\\n#]+)`, 'm');
+  const value = raw.match(re)?.[1]?.trim();
+  return value ? value : null;
+}
+
+function decodeScalar(text) {
+  const t = text.trim();
+  if (t === '' || t === 'null' || t === '~') return null;
+  if (t.startsWith('"')) {
+    try {
+      const v = JSON.parse(t);
+      return typeof v === 'string' && v ? v : null;
+    } catch {
+      return t.replace(/^"|"$/g, '') || null;
+    }
+  }
+  if (t.startsWith("'")) return t.replace(/^'|'$/g, '') || null;
+  const bare = t.replace(/\s+#.*$/, '').trim();
+  return bare || null;
+}
+
+function emptyAccount() {
+  return { mcp_token: null, console_url: null, email: null, paired_at: null };
+}
+
+/** Index of the top-level `accounts:` line and the end (exclusive) of its block. */
+function findAccountsBlock(lines) {
+  const start = lines.findIndex((l) => /^accounts:[ \t]*(#.*)?$/.test(l));
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length && (lines[end].trim() === '' || /^[ \t]/.test(lines[end]))) end += 1;
+  // Trailing blank lines belong to whatever follows, not to the block.
+  while (end > start + 1 && lines[end - 1].trim() === '') end -= 1;
+  return { start, end };
+}
+
+function parseAccountsBlock(lines) {
+  /** @type {Record<string, AccountCredentials>} */
+  const accounts = {};
+  const block = findAccountsBlock(lines);
+  if (!block) return accounts;
+  let current = null;
+  for (const line of lines.slice(block.start + 1, block.end)) {
+    const header = line.match(/^ {2}([^\s:#][^:]*):[ \t]*(#.*)?$/);
+    if (header) {
+      const id = decodeScalar(header[1]);
+      current = isValidAccountId(id) ? id : null;
+      if (current) accounts[current] = emptyAccount();
+      continue;
+    }
+    const field = line.match(/^ {4}([a-z_]+):(.*)$/);
+    if (field && current && ACCOUNT_FIELDS.includes(field[1])) {
+      accounts[current][field[1]] = decodeScalar(field[2]);
+    }
+  }
+  return accounts;
+}
+
+/**
+ * Parse a credentials.yaml text into the per-account store. Pure, never throws.
+ *
+ * A file without `schema_version: 2` (every file written before this task, an
+ * empty file, a missing file) is v1: its top-level `mcp_token` (if any) is the
+ * one account {@link LEGACY_ACCOUNT_ID}, which is then also current.
+ * @param {string | null | undefined} raw
+ * @returns {CredentialsStore}
+ */
+export function parseCredentialsStore(raw) {
+  const text = typeof raw === 'string' ? raw : '';
+  if (topLevelScalar(text, 'schema_version') !== String(CREDENTIALS_SCHEMA_VERSION)) {
+    const token = parseMcpToken(text);
+    if (!token) return { schemaVersion: 1, currentAccountId: null, accounts: {} };
+    return {
+      schemaVersion: 1,
+      currentAccountId: LEGACY_ACCOUNT_ID,
+      accounts: {
+        [LEGACY_ACCOUNT_ID]: { ...emptyAccount(), mcp_token: token, console_url: topLevelScalar(text, 'console_url') },
+      },
+    };
+  }
+  const accounts = parseAccountsBlock(text.split(/\r?\n/));
+  const current = topLevelScalar(text, 'current_account_id');
+  return {
+    schemaVersion: 2,
+    currentAccountId: current && accounts[current] ? current : null,
+    accounts,
+  };
+}
+
+/** Find an account by id, or by email (case-insensitive). Pure. */
+export function findStoredAccount(store, idOrEmail) {
+  if (typeof idOrEmail !== 'string' || !idOrEmail.trim()) return null;
+  const needle = idOrEmail.trim();
+  if (store.accounts[needle]) return { accountId: needle, ...store.accounts[needle] };
+  const lower = needle.toLowerCase();
+  for (const [accountId, entry] of Object.entries(store.accounts)) {
+    if (entry.email && entry.email.toLowerCase() === lower) return { accountId, ...entry };
+  }
+  return null;
+}
+
+/**
+ * Pure core: fold an env value and a credentials-file text into ONE bearer
+ * verdict. `credentialsText` is `null` when there is no readable file.
+ *
+ * `accountId` names an account: its stored token is returned (or none). Without
+ * it the CURRENT account's token is returned. On a v1 file the one flat token is
+ * the `legacy` account, which `legacyAccountId` (the v1 `config.yaml`
+ * `account_id`) may also name. The env var outranks the file either way — it is
+ * the explicit tier.
+ * @param {{ envToken?: string | null | undefined, credentialsText?: string | null | undefined, accountId?: string | null, legacyAccountId?: string | null }} input
+ * @returns {Bearer}
+ */
+export function resolveBearer({ envToken, credentialsText, accountId, legacyAccountId } = {}) {
+  const fromEnv = typeof envToken === 'string' ? envToken.trim() : '';
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const store = parseCredentialsStore(credentialsText);
+  let entry;
+  if (typeof accountId === 'string' && accountId.trim()) {
+    const wanted = accountId.trim();
+    entry = store.accounts[wanted];
+    if (!entry && store.schemaVersion === 1 && legacyAccountId && wanted === legacyAccountId) {
+      entry = store.accounts[LEGACY_ACCOUNT_ID];
+    }
+  } else {
+    entry = store.currentAccountId ? store.accounts[store.currentAccountId] : undefined;
+  }
+  if (entry?.mcp_token) return { token: entry.mcp_token, source: 'credentials-file' };
+  return { token: null, source: null };
+}
+
+function readTextOrNull(read, path) {
+  try {
+    const raw = read(path);
+    return typeof raw === 'string' ? raw : null;
+  } catch {
+    return null; // missing / unreadable file
+  }
+}
+
+// Same line-anchored shape as session-owner.mjs's historical reader.
+const CONFIG_ACCOUNT_ID_RE = /^account_id:\s*["']?([^"'\r\n#]+)/m;
+
+/**
+ * The v1 `account_id:` of `~/.heyspex/config.yaml` — read ONLY to name the
+ * account of a v1 file's legacy token (migration read). Never written.
+ */
+function readLegacyConfigAccountId(read, homeDir) {
+  const raw = readTextOrNull(read, join(homeDir, '.heyspex', 'config.yaml'));
+  const value = raw?.match(CONFIG_ACCOUNT_ID_RE)?.[1]?.trim() ?? '';
+  return value || null;
+}
+
+/**
+ * Thin shell: read the env and the file, then {@link resolveBearer}. Never
+ * throws. `readFile` is a test seam (defaults to `readFileSync` utf8).
+ * `accountId` selects a named account's token instead of the current one's.
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string | null, accountId?: string | null }} [opts]
+ * @returns {Bearer}
+ */
+export function readBearer({ env = process.env, homeDir = heyspexHome(), readFile, accountId } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  const credentialsText = readTextOrNull(read, credentialsFilePath(homeDir));
+  const named = typeof accountId === 'string' && accountId.trim() ? accountId.trim() : null;
+  const legacyAccountId =
+    named && parseCredentialsStore(credentialsText).schemaVersion === 1
+      ? readLegacyConfigAccountId(read, homeDir)
+      : null;
+  return resolveBearer({ envToken: env?.[MCP_TOKEN_ENV], credentialsText, accountId: named, legacyAccountId });
+}
+
+/**
+ * Read the whole store from disk (never throws; a missing file is an empty v1
+ * store). For v1, `legacyAccountId` carries the `config.yaml` `account_id` the
+ * legacy token was last confirmed as (null when none).
+ * @param {{ homeDir?: string, readFile?: (p: string) => string | null }} [opts]
+ * @returns {CredentialsStore & { legacyAccountId: string | null }}
+ */
+export function readCredentialsStore({ homeDir = heyspexHome(), readFile } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
+  const legacyAccountId = store.schemaVersion === 1 ? readLegacyConfigAccountId(read, homeDir) : null;
+  return { ...store, legacyAccountId };
+}
+
+/**
+ * The account id this machine is signed in as, from the credentials store —
+ * the ONE stored account-id fact (invariant 3, fact A). No env tier here: the
+ * `HS_ACCOUNT_ID` override is the caller's (session-owner.mjs).
+ *
+ *   - v2: `current_account_id` (a real account; `legacy` defers to the v1 rule);
+ *   - v1 (an existing single-account file, or no file): the `config.yaml`
+ *     `account_id` the last `hs login` confirmed — read-compatible, no manual step.
+ * @param {{ homeDir?: string, readFile?: (p: string) => string | null }} [opts]
+ * @returns {string | null}
+ */
+export function readCurrentAccountId({ homeDir = heyspexHome(), readFile } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
+  if (store.schemaVersion === 2 && store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID) {
+    return store.currentAccountId;
+  }
+  if (store.schemaVersion === 2 && store.currentAccountId === null) return null;
+  return readLegacyConfigAccountId(read, homeDir);
+}
+
+// ---------------------------------------------------------------------------
+// Real-home guard + writers
+// ---------------------------------------------------------------------------
+
+/** True under vitest (`VITEST`) or the node:test runner (`NODE_TEST_CONTEXT`). */
+function underTestRunner(env = process.env) {
+  return Boolean(env.VITEST) || Boolean(env.NODE_TEST_CONTEXT);
+}
+
+function samePathLoose(a, b) {
+  const norm = (p) => {
+    const r = resolve(p).replace(/[\\/]+$/, '');
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * The OS account's real home directory — `os.userInfo().homedir` (the passwd
+ * entry / the Windows profile), which a test's `HOME` / `USERPROFILE` swap
+ * does NOT move. `os.homedir()` is the wrong yardstick here: the node:test
+ * suites point it at a temp dir, so the real home would look "foreign".
+ */
+function realUserHome() {
+  try {
+    const h = os.userInfo().homedir;
+    if (typeof h === 'string' && h) return h;
+  } catch {
+    // no passwd entry (some containers) — fall through
+  }
+  return null;
+}
+
+/**
+ * Refuse, under a test runner, to write anything into the REAL
+ * `~/.heyspex/` (credentials.yaml, config.yaml, registry.json). A sibling
+ * test once fell through to the real home and rewrote the owner's
+ * registry.json; this is the same guard registry-file.ts carries, for the
+ * credentials/config writers. Checked on the resolved target directory, so no
+ * call shape slips past it.
+ * @param {string} filePath
+ */
+export function assertNotRealHomeUnderTest(filePath) {
+  if (!underTestRunner()) return;
+  const real = realUserHome();
+  if (real && samePathLoose(dirname(filePath), join(real, '.heyspex'))) {
+    throw new Error(
+      `credentials: refusing to write ${filePath} under a test runner — that is the real ` +
+        '~/.heyspex directory. Point the test at a temp home.',
+    );
+  }
+}
+
+function encodeScalar(value) {
+  return JSON.stringify(String(value));
+}
+
+/**
+ * Serialize `store` into `existingText`, rewriting only the keys this module
+ * owns (the managed top-level keys and the `accounts:` block) and keeping every
+ * other line byte-identical. Pure. Keeps an existing top-level `console_url`
+ * when no account is current (it is also the machine's console, `hs dev`).
+ * @param {string} existingText
+ * @param {CredentialsStore} store
+ * @returns {string}
+ */
+export function serializeCredentialsStore(existingText, store) {
+  const lines = existingText ? existingText.split(/\r?\n/) : [];
+  const block = findAccountsBlock(lines);
+  const kept = block ? [...lines.slice(0, block.start), ...lines.slice(block.end)] : [...lines];
+  const previousConsoleUrl = topLevelScalar(existingText ?? '', 'console_url');
+  // `accounts:` too: an empty store is written as the one-line `accounts: {}`.
+  const managed = new RegExp(`^(${[...MANAGED_TOP_LEVEL_KEYS, 'accounts'].join('|')}):`);
+  const rest = kept.filter((l) => !managed.test(l));
+  while (rest.length > 0 && rest[rest.length - 1].trim() === '') rest.pop();
+  while (rest.length > 0 && rest[0].trim() === '') rest.shift();
+
+  const current = store.currentAccountId ? store.accounts[store.currentAccountId] : null;
+  const head = [`schema_version: ${CREDENTIALS_SCHEMA_VERSION}`];
+  if (current) head.push(`current_account_id: ${store.currentAccountId}`);
+  if (current?.mcp_token) head.push(`mcp_token: ${current.mcp_token}`);
+  const mirrorConsole = current?.console_url ?? previousConsoleUrl;
+  if (mirrorConsole) head.push(`console_url: ${mirrorConsole}`);
+
+  const accountLines = ['accounts:'];
+  for (const [id, entry] of Object.entries(store.accounts)) {
+    if (!isValidAccountId(id)) continue;
+    accountLines.push(`  ${id}:`);
+    for (const field of ACCOUNT_FIELDS) {
+      if (entry[field]) accountLines.push(`    ${field}: ${encodeScalar(entry[field])}`);
+    }
+  }
+  if (accountLines.length === 1) accountLines[0] = 'accounts: {}';
+
+  return `${[...head, ...accountLines, ...rest].join('\n')}\n`;
+}
+
+function writeStore(homeDir, store) {
+  const filePath = credentialsFilePath(homeDir);
+  assertNotRealHomeUnderTest(filePath);
+  let existing = '';
+  try {
+    existing = readFileSync(filePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, serializeCredentialsStore(existing, store), { mode: 0o600 });
+  renameSync(tmp, filePath);
+  return filePath;
+}
+
+function loadForWrite(homeDir) {
+  const { legacyAccountId, ...store } = readCredentialsStore({ homeDir });
+  return { store: { ...store, accounts: { ...store.accounts } }, legacyAccountId };
+}
+
+function requireAccountId(fn, accountId) {
+  if (!isValidAccountId(accountId)) throw new Error(`${fn}: a valid account id is required`);
+  return accountId;
+}
+
+/**
+ * Store (or replace) one account's credentials, leaving every other account
+ * untouched, and (by default) make it current. Converts a v1 file to v2: the
+ * flat legacy token is kept under `rekeyLegacyAs` (the account the console
+ * confirmed for it) when given, else under `legacy` — never dropped, never
+ * guessed. Returns the file path. Never logs token material.
+ * @param {{ homeDir?: string, accountId: string, mcpToken: string, consoleUrl?: string | null, email?: string | null, pairedAt?: string | null, makeCurrent?: boolean, rekeyLegacyAs?: string | null }} input
+ */
+export function writeAccountCredentials({
+  homeDir = heyspexHome(),
+  accountId,
+  mcpToken,
+  consoleUrl = null,
+  email = null,
+  pairedAt = null,
+  makeCurrent = true,
+  rekeyLegacyAs = null,
+}) {
+  requireAccountId('writeAccountCredentials', accountId);
+  if (typeof mcpToken !== 'string' || !mcpToken.trim()) {
+    throw new Error('writeAccountCredentials: mcpToken is required');
+  }
+  const { store } = loadForWrite(homeDir);
+  if (store.schemaVersion === 1) rekeyLegacy(store, rekeyLegacyAs);
+  store.accounts[accountId] = {
+    mcp_token: mcpToken.trim(),
+    console_url: consoleUrl ? String(consoleUrl).trim().replace(/\/+$/, '') : null,
+    email: email ?? null,
+    paired_at: pairedAt ?? new Date().toISOString(),
+  };
+  if (makeCurrent || !store.currentAccountId) store.currentAccountId = accountId;
+  store.schemaVersion = 2;
+  return writeStore(homeDir, store);
+}
+
+function rekeyLegacy(store, rekeyAs) {
+  const legacy = store.accounts[LEGACY_ACCOUNT_ID];
+  if (!legacy || !isValidAccountId(rekeyAs) || rekeyAs === LEGACY_ACCOUNT_ID) return;
+  delete store.accounts[LEGACY_ACCOUNT_ID];
+  if (!store.accounts[rekeyAs]) store.accounts[rekeyAs] = legacy;
+  if (store.currentAccountId === LEGACY_ACCOUNT_ID) store.currentAccountId = rekeyAs;
+}
+
+/**
+ * Plan (and with `apply`, perform) the v1 → v2 re-key of an existing
+ * single-account file: the flat token moves under `confirmedAccountId` — the
+ * account GET /api/mcp/session confirmed for THAT token. `hs login --migrate`
+ * is the only caller; `--dry-run` prints the plan without writing.
+ * @param {{ homeDir?: string, confirmedAccountId: string, email?: string | null, apply?: boolean }} input
+ * @returns {{ action: 'rekey' | 'already-v2' | 'nothing-to-migrate', accountId: string | null, path: string }}
+ */
+export function migrateLegacyCredentials({ homeDir = heyspexHome(), confirmedAccountId, email = null, apply = false }) {
+  const path = credentialsFilePath(homeDir);
+  const { store } = loadForWrite(homeDir);
+  if (store.schemaVersion === 2) return { action: 'already-v2', accountId: store.currentAccountId, path };
+  const legacy = store.accounts[LEGACY_ACCOUNT_ID];
+  if (!legacy) return { action: 'nothing-to-migrate', accountId: null, path };
+  requireAccountId('migrateLegacyCredentials', confirmedAccountId);
+  if (apply) {
+    rekeyLegacy(store, confirmedAccountId);
+    const entry = store.accounts[confirmedAccountId];
+    if (entry && !entry.email && email) entry.email = email;
+    store.currentAccountId = confirmedAccountId;
+    store.schemaVersion = 2;
+    writeStore(homeDir, store);
+  }
+  return { action: 'rekey', accountId: confirmedAccountId, path };
+}
+
+/**
+ * Make `accountId` current. It must already hold a token (a switch never
+ * pairs). Returns the file path.
+ * @param {{ homeDir?: string, accountId: string }} input
+ */
+export function setCurrentAccount({ homeDir = heyspexHome(), accountId }) {
+  requireAccountId('setCurrentAccount', accountId);
+  const { store } = loadForWrite(homeDir);
+  if (!store.accounts[accountId]?.mcp_token) {
+    throw new Error(`setCurrentAccount: no stored credentials for account ${accountId}`);
+  }
+  store.currentAccountId = accountId;
+  store.schemaVersion = 2;
+  return writeStore(homeDir, store);
+}
+
+/**
+ * Remove one account (default: the current one). Removing the current account
+ * clears `current_account_id` (and the top-level token mirror); every other
+ * account is untouched. A no-op write is skipped when nothing matched.
+ * @param {{ homeDir?: string, accountId?: string | null }} [input]
+ * @returns {{ removed: string | null, wasCurrent: boolean, currentAccountId: string | null, path: string }}
+ */
+export function removeAccount({ homeDir = heyspexHome(), accountId = null } = {}) {
+  const path = credentialsFilePath(homeDir);
+  const { store } = loadForWrite(homeDir);
+  const target = accountId ?? store.currentAccountId;
+  if (!target || !store.accounts[target]) {
+    return { removed: null, wasCurrent: false, currentAccountId: store.currentAccountId, path };
+  }
+  delete store.accounts[target];
+  const wasCurrent = store.currentAccountId === target;
+  if (wasCurrent) store.currentAccountId = null;
+  store.schemaVersion = 2;
+  writeStore(homeDir, store);
+  return { removed: target, wasCurrent, currentAccountId: store.currentAccountId, path };
+}
+
+/**
+ * Convenience for the many "just the token or nothing" call sites.
+ * @param {Parameters<typeof readBearer>[0]} [opts]
+ * @returns {string | null}
+ */
+export function readBearerToken(opts) {
+  return readBearer(opts).token;
+}
+
+/**
+ * The receipt wording for a {@link BearerSource} — what `hs whoami`, the
+ * install identity gate and `hs mcp install` print so a human can see WHICH
+ * token was confirmed ([[HS-6V9X-WW9R-TASK-make-hs-install-remote-confirm-the]]).
+ * Never includes token material.
+ * @param {BearerSource | null | undefined} source
+ * @returns {string}
+ */
+export function describeBearerSource(source) {
+  if (source === 'env') return `${MCP_TOKEN_ENV} (env)`;
+  if (source === 'credentials-file') return '~/.heyspex/credentials.yaml (mcp_token)';
+  return 'none';
+}

package/vendor/heyspex-mcp/defer-spec.mjs

@@ -13,7 +13,11 @@ import { join } from 'node:path';
 
 import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
 import { familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { collectOccupiedKeysEitherKindViaTier } from './occupied-keys.mjs';
+import { resolveReadTier } from './read-path.mjs';
+import { effectiveConsoleUrl } from './mcp-config.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
+import { resolveSessionOwner } from './session-owner.mjs';
 import {
   isoNow,
   deriveSlug,
@@ -199,6 +203,7 @@ function buildChildTaskContent({
   effort,
   handoffId,
   now,
+  sessionOwner = null,
 }) {
   const slug = deriveSlug(childName);
   const parentBasename = parentTask.basename;
@@ -217,6 +222,13 @@ function buildChildTaskContent({
     envelope.reason,
   ].filter(Boolean);
 
+  // `owner:` is inherited from the parent task; a parent with none gets the
+  // paired session account; with neither the line is OMITTED — never a literal
+  // handle ([[HS-WE87-WW9R-TASK-thread-the-gated-caller-through-every]]).
+  const inheritedOwner = getScalarField(parentFm.block, 'owner')?.trim();
+  const owner = inheritedOwner || (typeof sessionOwner === 'string' && sessionOwner.trim()) || null;
+  const ownerLine = owner ? `\nowner: ${yamlScalar(owner)}` : '';
+
   const fm = `---
 id: ${childId}
 file_id: ${childFileKey}
@@ -225,8 +237,7 @@ name: ${yamlScalar(childName)}
 type: task
 status: open
 kind: ${yamlScalar(kind)}
-effort: ${effort}
-owner: ${yamlScalar(getScalarField(parentFm.block, 'owner') ?? 'pwher')}
+effort: ${effort}${ownerLine}
 parent: '${parentEpicLink}'
 milestone: '${parentMilestoneLink}'
 requires_user_testing: ${requiresUserTesting}
@@ -427,6 +438,12 @@ export async function executeDeferSpec(vaultRoot, args = {}, deps = {}) {
   // source; `id:` keys onto the file key alone.
   const parentIdValue = getScalarField(parentFm.block, 'id')?.replace(/^['"]|['"]$/g, '') ?? null;
   const parentFamilyValue = getScalarField(parentFm.block, 'family')?.replace(/^['"]|['"]$/g, '') ?? null;
+  // The FAMILY fallback draw (`collectOccupiedTaskIds` / `mintFamilyKey`) stays
+  // a DISK scan on purpose ([[HS-FJWL]]): family keys are not required to be
+  // globally unique — any number of specs may legally share one — so that scan
+  // is a "pick something fresh" default, not a uniqueness gate, and it is only
+  // reached at all when the parent has no inheritable family. Do not convert it
+  // into a console walk. The FILE key below is the opposite case.
   const childFamilyKey =
     familyOf({
       id: parentIdValue,
@@ -438,8 +455,30 @@ export async function executeDeferSpec(vaultRoot, args = {}, deps = {}) {
     )?.familyKey ??
     mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit });
   // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
-  // and (V3) the anchor for `id:` itself.
-  const childFileKey = mintFileKey(vaultRoot, { randomUnit: deps?.randomUnit });
+  // and (V3) the anchor for `id:` itself. TIER-AWARE ([[HS-FJWL]]): a file key
+  // is the unique per-file identity, so occupancy has to come from whichever
+  // vault is of record for this session. An unreachable console REFUSES the
+  // mint rather than falling back to the stale local clone — a duplicate id is
+  // worse than a refusal. `deps.tier` / `deps.consoleUrl` / `deps.consoleFetch`
+  // are test seams; production resolves them the same way every other
+  // `*ViaTier` caller does.
+  let occupiedKeys;
+  try {
+    occupiedKeys = await collectOccupiedKeysEitherKindViaTier(vaultRoot, {
+      tier: deps?.tier ?? (await resolveReadTier()),
+      consoleUrl: deps?.consoleUrl ?? effectiveConsoleUrl(),
+      ...(deps?.consoleFetch ? { consoleFetch: deps.consoleFetch } : {}),
+    });
+  } catch (err) {
+    return {
+      error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+      message:
+        `Refusing to mint a file key for the split child: ${String(err?.message ?? err)}. ` +
+        `In cloud reliance the occupied-key set lives in the console's vault, not on this ` +
+        `machine — minting from the local clone would hand out an id another spec may already hold.`,
+    };
+  }
+  const childFileKey = mintFileKey(occupiedKeys, { randomUnit: deps?.randomUnit });
   const childId = `HS-${childFileKey}`;
   const childSlug = deriveSlug(childName);
   const childBasename = `${childId}-${childFamilyKey}-TASK-${childSlug}`;
@@ -461,6 +500,7 @@ export async function executeDeferSpec(vaultRoot, args = {}, deps = {}) {
       effort,
       handoffId,
       now,
+      sessionOwner: (deps?.resolveSessionOwner ?? resolveSessionOwner)(),
     }),
   });