heyspex 0.1.0 → 0.2.0

package/scripts/lib/hs-source-identity.mjs

@@ -0,0 +1,526 @@
+#!/usr/bin/env node
+/**
+ * hs-source-identity.mjs — `hs source identity [show|set|clear]`: the ONE
+ * sanctioned way a git author identity is written on this machine.
+ *
+ * THE INCIDENT (2026-09-19)
+ * ------------------------
+ * Agents that hit git's "Author identity unknown — Please tell me who you
+ * are" worked around it by running `git config user.email <the email on the
+ * owner's Claude account>` in the repo-local `.git/config` of four repos. A
+ * repo-local value beats the global identity the owner set later, so every
+ * commit from this machine was authored as a non-team address for ten days
+ * and Vercel silently refused two production deploys. Vault lesson:
+ * `when-git-says-author-identity-unknown`.
+ *
+ * THE RULING
+ * ----------
+ * A repo-local (or global) git identity override is a HUMAN-AUTHORIZED
+ * action only, run through this command by the human themselves — in their
+ * own terminal, or in Claude Code with the `!` prefix (which runs outside the
+ * agent's tool calls). Agents may READ identity (`show`), never write it.
+ *
+ * THREE LAYERS enforce it (docs/admin/workflow/git-identity.md):
+ *   1. this command — `set`/`clear` refuse when an agent env marker is
+ *      present, unless `--human` / HS_HUMAN_IDENTITY=1 says a human typed it
+ *      through Claude Code's `!` prefix (which inherits the agent's env);
+ *   2. the PreToolUse gate spexharness/src/gates/git-identity-guard.mjs —
+ *      an agent cannot even ask a tool to run `git config user.email …`;
+ *   3. the pre-commit guard scripts/guard-git-identity.mjs — a repo-local
+ *      override that this command did not record cannot commit.
+ *
+ * WHAT `set` RECORDS: `.heyspex/git-identity.json` at the repo root —
+ * `{ scope, email, name, authorizedAt, authorizedBy: "human", via }`. Layer 3
+ * and `show` compare the live `.git/config` against it; a mismatch is an
+ * override written behind the command's back. The email is ALWAYS the
+ * human's explicit `--email` argument — never read from any HeySpex, Clerk
+ * or Claude identity source (that is precisely the mistake the incident made).
+ *
+ * Exit codes: 0 ok · 2 usage · 3 refused (agent shell without --human).
+ *
+ * Every git call goes through an injectable runner (`run`) so the test
+ * (hs-source-identity.test.mjs) drives temp repos only and never touches this
+ * machine's real identity.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { detectAgentMarkers } from './agent-env-markers.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+/** Where `set` records the human authorization, relative to the repo root. Git-ignored. */
+export const AUTH_FILE_REL = path.join('.heyspex', 'git-identity.json');
+
+/** The flag / env var that says "a human typed this through Claude Code's `!` prefix". */
+export const HUMAN_FLAG = '--human';
+export const HUMAN_ENV = 'HS_HUMAN_IDENTITY';
+
+/** The env vars git consults before any config file. Any of these set = an override. */
+export const GIT_IDENTITY_ENV_VARS = [
+  'GIT_AUTHOR_EMAIL',
+  'GIT_AUTHOR_NAME',
+  'GIT_COMMITTER_EMAIL',
+  'GIT_COMMITTER_NAME',
+];
+
+export const EXIT = Object.freeze({ OK: 0, USAGE: 2, REFUSED: 3 });
+
+/** The two sanctioned human forms — quoted verbatim in every refusal, doc and gate reason. */
+export const HUMAN_FORMS = Object.freeze({
+  terminal: 'hs source identity set --email you@example.com',
+  claudeCode: '!hs source identity set --email you@example.com --human',
+});
+
+export const VAULT_LESSON = 'when-git-says-author-identity-unknown';
+
+export const USAGE =
+  'hs source identity — read or (human-only) write the git author identity\n\n' +
+  '  hs source identity [show] [--json]                       Effective user.name / user.email, where each\n' +
+  '                                                            comes from, and whether a repo-local override is\n' +
+  '                                                            authorized (read-only; agents may run this)\n' +
+  '  hs source identity set --email <email> [--name <name>]   Write the identity (repo-local by default,\n' +
+  '                       [--global] [--human]                 --global for the global one) and record the\n' +
+  '                                                            authorization in .heyspex/git-identity.json\n' +
+  '  hs source identity clear [--human]                        Remove the repo-local [user] override and the\n' +
+  '                                                            authorization; the global identity applies again\n\n' +
+  '  set / clear are HUMAN-ONLY. Type them yourself:\n' +
+  `    in your own terminal:   ${HUMAN_FORMS.terminal}\n` +
+  `    inside Claude Code:     ${HUMAN_FORMS.claudeCode}\n` +
+  '  (the `!` prefix runs outside the agent\'s tool calls but inherits its env — that is the only\n' +
+  '   reason --human exists). Exit codes: 0 ok · 2 usage · 3 refused.\n';
+
+// ---- git runner ------------------------------------------------------------
+
+/**
+ * Default subprocess runner — injectable so tests can spy / redirect to a
+ * temp repo. Never throws on a non-zero exit; callers check `.status`.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, env?: Record<string, string|undefined> }} [opts]
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+export function defaultRun(cmd, args, opts = {}) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...opts,
+    });
+    return { status: 0, stdout, stderr: '' };
+  } catch (err) {
+    return {
+      status: typeof err.status === 'number' ? err.status : 1,
+      stdout: err.stdout ? String(err.stdout) : '',
+      stderr: err.stderr ? String(err.stderr) : String(err.message ?? ''),
+    };
+  }
+}
+
+function git(run, args, { cwd, env }) {
+  return run('git', args, { cwd, env });
+}
+
+// ---- reading ---------------------------------------------------------------
+
+/** Infer git's config scope from a `--show-origin` origin string when `--show-scope` is unavailable. */
+function scopeFromOrigin(origin) {
+  const o = String(origin ?? '').replace(/\\/g, '/');
+  if (/\/\.git\/config$/.test(o) || /\/\.git\/worktrees\/[^/]+\/config\.worktree$/.test(o)) return 'local';
+  if (/\/config\.worktree$/.test(o)) return 'worktree';
+  if (/\/etc\/gitconfig$/.test(o)) return 'system';
+  if (/\.gitconfig$/.test(o) || /\/\.config\/git\/config$/.test(o)) return 'global';
+  if (/^command line/.test(o) || /^blob:/.test(o)) return 'command';
+  return 'file';
+}
+
+/**
+ * Every value git holds for `key`, most-specific LAST (git's own precedence:
+ * the last line wins), with the scope and file each comes from.
+ *
+ * @param {string} key
+ * @param {{ run?: Function, cwd: string, env?: Record<string, string|undefined> }} deps
+ * @returns {{ scope: string, origin: string, value: string }[]}
+ */
+export function readConfigOrigins(key, { run = defaultRun, cwd, env = process.env }) {
+  const r = git(run, ['config', '--show-scope', '--show-origin', '--get-all', key], { cwd, env });
+  if (r.status !== 0 || !r.stdout.trim()) return [];
+  return r.stdout
+    .split(/\r?\n/)
+    .filter((l) => l.trim())
+    .map((line) => {
+      const parts = line.split('\t');
+      if (parts.length >= 3) {
+        return { scope: parts[0], origin: parts[1], value: parts.slice(2).join('\t') };
+      }
+      // Older git without --show-scope: `<origin>\t<value>`.
+      return { scope: scopeFromOrigin(parts[0]), origin: parts[0], value: parts.slice(1).join('\t') };
+    });
+}
+
+/** Repo-local (`.git/config`) values only — what an unauthorized override looks like. */
+export function readLocalIdentity({ run = defaultRun, cwd, env = process.env }) {
+  const get = (key) => {
+    const r = git(run, ['config', '--local', '--get-all', key], { cwd, env });
+    if (r.status !== 0) return null;
+    const lines = r.stdout.split(/\r?\n/).filter((l) => l.trim());
+    return lines.length ? lines[lines.length - 1] : null;
+  };
+  return { email: get('user.email'), name: get('user.name') };
+}
+
+/** Repo top-level for `cwd`, or null when not inside a git work tree. */
+export function resolveRepoRoot({ run = defaultRun, cwd, env = process.env }) {
+  const r = git(run, ['rev-parse', '--show-toplevel'], { cwd, env });
+  if (r.status !== 0) return null;
+  const top = r.stdout.trim();
+  return top ? path.resolve(top) : null;
+}
+
+/** The recorded human authorization, or null when absent / unreadable. */
+export function readAuthorization(repoRoot) {
+  if (!repoRoot) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(repoRoot, AUTH_FILE_REL), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The GIT_AUTHOR_* / GIT_COMMITTER_* values present in `env` (set to anything non-blank). */
+export function envOverrides(env = process.env) {
+  const out = {};
+  for (const k of GIT_IDENTITY_ENV_VARS) {
+    if (env[k] != null && String(env[k]).trim() !== '') out[k] = String(env[k]);
+  }
+  return out;
+}
+
+/**
+ * The env values that actually OVERRIDE the config-resolved identity.
+ *
+ * git itself exports GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL into a hook's
+ * environment (pre-commit included), mirroring the identity it resolved from
+ * config — so "the var is set" is not evidence of an override inside a hook.
+ * An env value is an override only when it DIFFERS from config: a forged
+ * author for one commit, or `git commit --author=…` (git exports that too,
+ * which is how the pre-commit guard catches --author as a side effect).
+ *
+ * @param {Record<string,string|undefined>} env
+ * @param {{ email: string|null, name: string|null }} configIdentity - config-only values (no env).
+ * @returns {Record<string, string>} var → value, for the vars that differ.
+ */
+export function effectiveEnvOverrides(env, configIdentity) {
+  const present = envOverrides(env);
+  const out = {};
+  for (const [k, v] of Object.entries(present)) {
+    const expected = /EMAIL$/.test(k) ? configIdentity.email : configIdentity.name;
+    if ((expected ?? null) === null || v.trim() !== String(expected).trim()) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Does the live repo-local override match the recorded authorization?
+ * Both email AND name must match (the authorization records the post-`set`
+ * local values, so a name someone added afterwards is a mismatch too).
+ */
+export function authorizationMatches(local, auth) {
+  if (!auth || auth.scope !== 'local' || auth.authorizedBy !== 'human') return false;
+  return (local.email ?? null) === (auth.email ?? null) && (local.name ?? null) === (auth.name ?? null);
+}
+
+/**
+ * The full read-only picture: effective identity + provenance, the local
+ * override, the authorization record, env overrides, and a one-line verdict.
+ *
+ * @param {{ run?: Function, cwd?: string, env?: Record<string, string|undefined> }} [deps]
+ */
+export function inspectIdentity({ run = defaultRun, cwd = process.cwd(), env = process.env } = {}) {
+  const repoRoot = resolveRepoRoot({ run, cwd, env });
+  const emailOrigins = readConfigOrigins('user.email', { run, cwd, env });
+  const nameOrigins = readConfigOrigins('user.name', { run, cwd, env });
+  const configIdentity = {
+    email: emailOrigins[emailOrigins.length - 1]?.value ?? null,
+    name: nameOrigins[nameOrigins.length - 1]?.value ?? null,
+  };
+  const overrides = effectiveEnvOverrides(env, configIdentity);
+  const local = repoRoot ? readLocalIdentity({ run, cwd, env }) : { email: null, name: null };
+  const localOverride = local.email != null || local.name != null;
+  const auth = readAuthorization(repoRoot);
+  const authorized = localOverride ? authorizationMatches(local, auth) : null;
+
+  const effective = (origins, envKeys) => {
+    for (const k of envKeys) {
+      if (overrides[k]) return { value: overrides[k], source: `env ${k}`, scope: 'env' };
+    }
+    const last = origins[origins.length - 1];
+    if (!last) return { value: null, source: 'not set', scope: null };
+    return { value: last.value, source: `${last.scope}: ${last.origin}`, scope: last.scope };
+  };
+  const email = effective(emailOrigins, ['GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL']);
+  const name = effective(nameOrigins, ['GIT_AUTHOR_NAME', 'GIT_COMMITTER_NAME']);
+
+  let verdict;
+  let ok;
+  if (Object.keys(overrides).length) {
+    ok = false;
+    verdict =
+      `unauthorized environment override (${Object.keys(overrides).join(', ')}) — unset it; ` +
+      `identity is written only by hs source identity set (human)`;
+  } else if (localOverride && !authorized) {
+    ok = false;
+    verdict =
+      'unauthorized repo-local override — run hs source identity clear (human) or ' +
+      `hs source identity set --email <email> (human) to record it`;
+  } else if (!email.value || !name.value) {
+    ok = false;
+    verdict = `no ${!email.value ? 'user.email' : 'user.name'} configured — a human runs: ${HUMAN_FORMS.terminal}`;
+  } else if (localOverride) {
+    ok = true;
+    verdict = `ok (repo-local override authorized by human ${auth.authorizedAt ?? ''})`.replace(/\s+\)/, ')');
+  } else {
+    ok = true;
+    verdict = 'ok';
+  }
+
+  return {
+    repoRoot,
+    email,
+    name,
+    origins: { email: emailOrigins, name: nameOrigins },
+    localOverride: localOverride ? local : null,
+    authorization: auth,
+    authorized,
+    envOverrides: overrides,
+    ok,
+    verdict,
+  };
+}
+
+/** Human-readable `show` output. */
+export function formatIdentityReport(info) {
+  const lines = [];
+  lines.push(`git identity${info.repoRoot ? ` — ${info.repoRoot}` : ' — (not inside a git work tree)'}`);
+  lines.push(`  user.email   ${info.email.value ?? '(not set)'}   [${info.email.source}]`);
+  lines.push(`  user.name    ${info.name.value ?? '(not set)'}   [${info.name.source}]`);
+  if (info.localOverride) {
+    const l = info.localOverride;
+    lines.push(`  repo-local [user] override: present (email=${l.email ?? '-'}, name=${l.name ?? '-'})`);
+    if (!info.authorization) lines.push(`  authorization (${AUTH_FILE_REL}): none recorded`);
+    else if (info.authorized) {
+      lines.push(
+        `  authorization (${AUTH_FILE_REL}): matches — ${info.authorization.authorizedBy} via "${info.authorization.via}" at ${info.authorization.authorizedAt}`,
+      );
+    } else {
+      lines.push(
+        `  authorization (${AUTH_FILE_REL}): MISMATCH — recorded scope=${info.authorization.scope ?? '-'} email=${info.authorization.email ?? '-'} name=${info.authorization.name ?? '-'}`,
+      );
+    }
+  } else {
+    lines.push('  repo-local [user] override: none');
+  }
+  const envKeys = Object.keys(info.envOverrides);
+  lines.push(`  env overrides: ${envKeys.length ? envKeys.map((k) => `${k}=${info.envOverrides[k]}`).join(', ') : 'none'}`);
+  lines.push(`  verdict: ${info.verdict}`);
+  return lines.join('\n') + '\n';
+}
+
+// ---- writing (human-only) --------------------------------------------------
+
+export const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Parse `hs source identity …` argv (after the `identity` token). */
+export function parseIdentityArgs(argv) {
+  const out = { verb: 'show', json: false, human: false, global: false, email: null, name: null, errors: [] };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith('-')) out.verb = args.shift();
+  while (args.length) {
+    const a = args.shift();
+    if (a === '--json') out.json = true;
+    else if (a === HUMAN_FLAG) out.human = true;
+    else if (a === '--global') out.global = true;
+    else if (a === '--email' || a.startsWith('--email=')) {
+      out.email = a.includes('=') ? a.slice('--email='.length) : args.shift() ?? null;
+    } else if (a === '--name' || a.startsWith('--name=')) {
+      out.name = a.includes('=') ? a.slice('--name='.length) : args.shift() ?? null;
+    } else if (a === '--help' || a === '-h') out.verb = 'help';
+    else out.errors.push(`unknown argument: ${a}`);
+  }
+  if (!['show', 'set', 'clear', 'help'].includes(out.verb)) {
+    out.errors.push(`unknown verb: ${out.verb} (expected show | set | clear)`);
+  }
+  if (out.verb === 'set') {
+    if (!out.email) out.errors.push('set requires --email <email>');
+    else if (!EMAIL_RE.test(out.email)) out.errors.push(`--email does not look like an email address: ${out.email}`);
+    if (out.name != null && !out.name.trim()) out.errors.push('--name must not be empty');
+  }
+  return out;
+}
+
+/** True when a human vouched for this invocation (`--human` or HS_HUMAN_IDENTITY). */
+export function humanVouched({ human, env = process.env }) {
+  if (human) return true;
+  const v = String(env[HUMAN_ENV] ?? '').trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+
+/** The refusal text printed when an agent shell runs `set`/`clear` without `--human`. */
+export function refusalMessage(verb, markers) {
+  return (
+    `hs source identity ${verb}: REFUSED — an AI agent shell is running this (${markers.join(', ')}).\n` +
+    'Git identity is a human-authorized action only (owner ruling 2026-09-19, vault lesson\n' +
+    `${VAULT_LESSON}). Agents read identity (hs source identity show); they never write it.\n` +
+    '\n' +
+    'If you are the human, type the command yourself:\n' +
+    `  in your own terminal:   ${HUMAN_FORMS.terminal}\n` +
+    `  inside Claude Code:     ${HUMAN_FORMS.claudeCode}\n` +
+    '\n' +
+    "(The `!` prefix runs outside the agent's tool calls but inherits its environment, which is\n" +
+    ` the only reason ${HUMAN_FLAG} / ${HUMAN_ENV}=1 exist. An agent must never pass them.)\n`
+  );
+}
+
+function writeAuthorization(repoRoot, record) {
+  const file = path.join(repoRoot, AUTH_FILE_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n', 'utf8');
+  return file;
+}
+
+function removeAuthorization(repoRoot) {
+  const file = path.join(repoRoot, AUTH_FILE_REL);
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    /* absent */
+  }
+  return file;
+}
+
+/**
+ * The command. Returns the exit code; prints through `stdout`/`stderr`.
+ *
+ * @param {string[]} argv - tokens AFTER `identity` (e.g. `['set','--email','a@b.c']`).
+ * @param {{ cwd?: string, env?: Record<string,string|undefined>, run?: Function,
+ *           stdout?: (s: string) => void, stderr?: (s: string) => void, now?: () => Date }} [deps]
+ * @returns {number}
+ */
+export function runIdentityCommand(argv, deps = {}) {
+  const {
+    cwd = process.env.HS_INVOKED_CWD || process.cwd(),
+    env = process.env,
+    run = defaultRun,
+    stdout = (s) => process.stdout.write(s),
+    stderr = (s) => process.stderr.write(s),
+    now = () => new Date(),
+  } = deps;
+
+  const args = parseIdentityArgs(argv);
+  if (args.verb === 'help') {
+    stdout(USAGE);
+    return EXIT.OK;
+  }
+  if (args.errors.length) {
+    stderr(`hs source identity: ${args.errors.join('; ')}\n\n${USAGE}`);
+    return EXIT.USAGE;
+  }
+
+  if (args.verb === 'show') {
+    const info = inspectIdentity({ run, cwd, env });
+    stdout(args.json ? JSON.stringify(info, null, 2) + '\n' : formatIdentityReport(info));
+    return EXIT.OK;
+  }
+
+  // ---- set / clear: human-only from here -----------------------------------
+  const markers = detectAgentMarkers(env);
+  if (markers.length && !humanVouched({ human: args.human, env })) {
+    stderr(refusalMessage(args.verb, markers));
+    return EXIT.REFUSED;
+  }
+
+  const repoRoot = resolveRepoRoot({ run, cwd, env });
+  if (!repoRoot && !(args.verb === 'set' && args.global)) {
+    stderr(`hs source identity ${args.verb}: not inside a git work tree (${cwd})\n`);
+    return EXIT.USAGE;
+  }
+
+  if (args.verb === 'set') {
+    const scope = args.global ? 'global' : 'local';
+    const scopeFlag = `--${scope}`;
+    const w = git(run, ['config', scopeFlag, 'user.email', args.email], { cwd, env });
+    if (w.status !== 0) {
+      stderr(`hs source identity set: git config ${scopeFlag} user.email failed: ${w.stderr.trim()}\n`);
+      return EXIT.USAGE;
+    }
+    if (args.name != null) {
+      const n = git(run, ['config', scopeFlag, 'user.name', args.name], { cwd, env });
+      if (n.status !== 0) {
+        stderr(`hs source identity set: git config ${scopeFlag} user.name failed: ${n.stderr.trim()}\n`);
+        return EXIT.USAGE;
+      }
+    }
+    // Record what is actually there after the write (the name may pre-exist).
+    let recordedName = args.name;
+    if (scope === 'local') recordedName = readLocalIdentity({ run, cwd, env }).name;
+    const record = {
+      scope,
+      email: args.email,
+      name: recordedName ?? null,
+      authorizedAt: now().toISOString(),
+      authorizedBy: 'human',
+      via: 'hs source identity set',
+    };
+    let file = null;
+    if (repoRoot) file = writeAuthorization(repoRoot, record);
+    stdout(
+      `hs source identity set: wrote ${scope} user.email=${args.email}` +
+        (args.name != null ? ` user.name=${args.name}` : '') +
+        (file ? `\n  recorded authorization → ${file}` : '') +
+        '\n\n',
+    );
+    stdout(formatIdentityReport(inspectIdentity({ run, cwd, env })));
+    return EXIT.OK;
+  }
+
+  // clear
+  const before = readLocalIdentity({ run, cwd, env });
+  const had = before.email != null || before.name != null;
+  if (had) {
+    const r = git(run, ['config', '--local', '--remove-section', 'user'], { cwd, env });
+    if (r.status !== 0) {
+      stderr(`hs source identity clear: git config --local --remove-section user failed: ${r.stderr.trim()}\n`);
+      return EXIT.USAGE;
+    }
+  }
+  const file = removeAuthorization(repoRoot);
+  stdout(
+    (had
+      ? `hs source identity clear: removed repo-local [user] override (email=${before.email ?? '-'}, name=${before.name ?? '-'})`
+      : 'hs source identity clear: no repo-local [user] override was present') +
+      `\n  removed authorization file (if any) → ${file}\n\n`,
+  );
+  stdout(formatIdentityReport(inspectIdentity({ run, cwd, env })));
+  return EXIT.OK;
+}
+
+// ---- direct-invocation entry -----------------------------------------------
+
+function invokedDirectly() {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  // bin/hs.mjs spawns `[script, 'identity', ...rest]`; a direct call may omit the verb token.
+  const tokens = process.argv.slice(2);
+  if (tokens[0] === 'identity') tokens.shift();
+  process.exitCode = runIdentityCommand(tokens);
+}

package/scripts/lib/hs-source-log.mjs

@@ -26,41 +26,31 @@
  * {@link formatSettlementResult}.
  */
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { readBearerToken } from '../../vendor/heyspex-mcp/credentials.mjs';
 import { resolveConsoleUrl } from './console-url-resolver.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
 // ---- Bearer-header idiom -------------------------------------------------
-// Mirrors `readPairedToken`/`bearerHeaderFor` in
-// `spex-console/src/lib/cli/control-shared.ts` byte-for-byte in behavior:
-// same paired `hsmcp_`/`hscmp_` token read from `~/.heyspex/credentials.yaml`,
-// same loopback-skip rule (a local dev console never needed auth; a genuinely
-// remote/paired console does — [[HS-PH7O-ILNC-DIAG-hs-check-report-cannot-authenticate]]).
-// Duplicated here in plain Node ESM rather than imported from that TS module
-// because `scripts/lib/*.mjs` runs standalone (bare `node`, no Next.js build
-// step) — the same reasoning `console-url-resolver.mjs`'s own module doc
-// gives for staying dependency-free.
+// Same contract as `readPairedToken`/`bearerHeaderFor` in
+// `spex-console/src/lib/cli/control-shared.ts`: the bearer comes from the ONE
+// shared reader (`vendor/heyspex-mcp/credentials.mjs`,
+// [[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]] — env
+// `HEYSPEX_MCP_TOKEN`, then `mcp_token:` in `~/.heyspex/credentials.yaml`),
+// and the loopback-skip rule stays (a local dev console never needed auth; a
+// genuinely remote/paired console does —
+// [[HS-PH7O-ILNC-DIAG-hs-check-report-cannot-authenticate]]).
 
 /**
- * Raw paired Bearer token from `~/.heyspex/credentials.yaml`, or `undefined`
- * if absent/unreadable.
+ * Paired Bearer token for this machine, or `undefined` if none resolves.
  * @returns {string | undefined}
  */
 export function readPairedToken() {
-  try {
-    const raw = readFileSync(join(homedir(), '.heyspex', 'credentials.yaml'), 'utf-8');
-    const match = raw.match(/\b(hsmcp_[A-Za-z0-9_-]+|hscmp_[A-Za-z0-9_-]+)\b/);
-    return match?.[1];
-  } catch {
-    return undefined;
-  }
+  return readBearerToken() ?? undefined;
 }
 
 /**