heyspex 0.2.6 → 0.2.7

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

@@ -28,6 +28,7 @@ import { listConfigLeaves } from './config-settings.mjs';
 // the MCP server's package closure. See dev-factory-bridge.mjs for the full
 // rationale ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]]).
 import { loadDreamResearch } from './dev-factory-bridge.mjs';
+import { resolveSeatModelForCaller } from './seat-identity.mjs';
 
 const RESEARCH_PREFIX = 'agent_behaviors.research.';
 
@@ -39,12 +40,30 @@ const RESEARCH_PREFIX = 'agent_behaviors.research.';
  * source — NOT the resource-profile/fallback-chain/capability-gating resolution the research
  * doc's separate feature will add later.
  */
-export async function executeResolveResearchPlan(vaultRoot) {
+/**
+ * The research agent when `default_agent` is not configured: the harness default for the
+ * research-synthesis seat ([[HS-J3NY-C86Z-TASK-replace-hard-coded-owner-defaults-on]]) —
+ * opus under Claude Code, auto under Copilot, null with no harness (the caller asks). Never an
+ * owner default: the owner's DeepSeek routing only answers through the gated owner overlay.
+ * @returns {{ agent: string|null, source: string }}
+ */
+export function defaultResearchAgent({ env = process.env, resolve = resolveSeatModelForCaller } = {}) {
+  try {
+    const r = resolve({ seatId: 'research-synthesis', env });
+    return { agent: r?.model ?? null, source: r?.source ?? 'no-harness' };
+  } catch {
+    return { agent: null, source: 'no-harness' };
+  }
+}
+
+export async function executeResolveResearchPlan(vaultRoot, { env = process.env } = {}) {
   const leaves = listConfigLeaves(vaultRoot).filter((s) => s.key.startsWith(RESEARCH_PREFIX));
   const cfg = Object.fromEntries(leaves.map((s) => [s.key.slice(RESEARCH_PREFIX.length), s.value]));
 
   const method = cfg.default_method ?? 'ladder';
-  const defaultAgent = cfg.default_agent ?? 'deepseek';
+  const fallbackAgent = cfg.default_agent ? null : defaultResearchAgent({ env });
+  const defaultAgent = cfg.default_agent ?? fallbackAgent.agent;
+  const defaultAgentSource = cfg.default_agent ? 'config' : fallbackAgent.source;
   const defaultSource = cfg.default_source ?? 'web-native';
 
   let endpoint = null;
@@ -76,6 +95,7 @@ export async function executeResolveResearchPlan(vaultRoot) {
     ok: true,
     method,
     default_agent: defaultAgent,
+    default_agent_source: defaultAgentSource,
     default_source: defaultSource,
     resource: { source: defaultSource, endpoint },
     note,

package/vendor/heyspex-mcp/seat-assign-cli.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// vendor/heyspex-mcp/seat-assign-cli.mjs — `hs seat list|set|reset|defaults` for customers
+// ([[HS-EUNP-C86Z-TASK-hs-seat-list-set-reset-for-customers-in]], epic
+// [[HS-K9L7-C86Z-EPIC-per-user-per-vault-seat-assignments]]).
+//
+//   hs seat list   [--harness claude-code|copilot] [--json] [--refresh]
+//   hs seat set    <seat> <model> [--harness claude-code|copilot]
+//   hs seat reset  <seat> [--harness claude-code|copilot]
+//   hs seat defaults [--harness …] [--json]     (read-only harness defaults; seat-defaults-cli)
+//
+// Every choice is the signed-in user's OWN, for the vault this repo is bound to, under one harness
+// (`/api/me/seats`). Strictly per user (owner ruling 2026-10-17). Never reads or writes the
+// owner's dev-factory/seats.json — the source-checkout `hs seat add|update|disable` registry
+// verbs are a different tool.
+//
+// Exit: 0 ok · 1 the console refused or could not be reached · 2 bad arguments / invalid model.
+import { readdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+
+import { detectHarness, listInstalledHarnessPlugins, normalizeHarness } from '../../spexharness/src/adapters/harness-detect.mjs';
+import { listCopilotModels, validateCopilotModel } from '../../spexharness/src/adapters/copilot-models.mjs';
+import { validateSeatAssignment } from './seat-assignment-rules.mjs';
+import {
+  fetchSeatAssignments, invalidateSeatCache, assignmentFor, normalizeAssignments, reportCopilotFallback, SEATS_ENDPOINT,
+} from './seat-assignments-client.mjs';
+import { PRODUCT_SEATS, canonicalSeatId, resolveSeatModel } from './seat-defaults.mjs';
+import { runSeatDefaultsCli } from './seat-defaults-cli.mjs';
+
+const SOURCE_LABELS = {
+  'user-assignment': 'you · this vault',
+  'harness-default': 'harness default',
+  human: 'a person',
+  'no-harness': 'no harness',
+};
+
+export const SEAT_CLI_USAGE = [
+  'Usage:',
+  '  hs seat list   [--harness claude-code|copilot] [--json] [--refresh]   Every seat, its model and where it comes from',
+  '  hs seat set    <seat> <model> [--harness claude-code|copilot]        Use <model> for <seat> (you only, this vault)',
+  '  hs seat reset  <seat> [--harness claude-code|copilot]                Back to the harness default',
+  '  hs seat defaults [--harness …] [--json]                              The harness defaults alone',
+  '  hs seat report-fallback <seat> --log <file>                          Record that Copilot refused a seat model (launchers)',
+  '',
+  'Claude Code seats take opus, sonnet, haiku, fable, inherit or a full claude-* id.',
+  'Copilot seats take auto (the default) or a Copilot model id.',
+  '',
+].join('\n');
+
+function parseArgs(argv) {
+  const out = { positional: [], json: false, refresh: false, harness: undefined, error: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--refresh') out.refresh = true;
+    else if (a === '--log') { out.log = argv[++i] ?? null; if (!out.log) { out.error = '--log needs a file'; return out; } }
+    else if (a === '--harness' || a.startsWith('--harness=')) {
+      const v = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i];
+      const h = normalizeHarness(v);
+      if (h === undefined || h === null) { out.error = `--harness must be claude-code or copilot (got "${v ?? ''}")`; return out; }
+      out.harness = h;
+    } else if (a.startsWith('--')) { out.error = `unknown option "${a}"`; return out; }
+    else out.positional.push(a);
+  }
+  return out;
+}
+
+function detect(env, forced) {
+  if (forced) return { harness: forced, status: 'resolved', source: 'flag:--harness' };
+  const home = env.HEYSPEX_SEAT_HOME || env.HEYSPEX_HOME || os.homedir();
+  const deps = {
+    readFile: (p) => { try { return readFileSync(p, 'utf8'); } catch { return null; } },
+    listDir: (p) => { try { return readdirSync(p); } catch { return []; } },
+  };
+  const installed = listInstalledHarnessPlugins({ home, copilotHome: env.COPILOT_HOME || undefined, deps });
+  return detectHarness(env, null, installed);
+}
+
+function noHarnessMessage(detected) {
+  return detected?.status === 'needs-choice'
+    ? `No harness detected and several are installed (${(detected.choices ?? []).join(', ')}): pass --harness claude-code or --harness copilot.`
+    : 'No harness detected: pass --harness claude-code or --harness copilot (or set HEYSPEX_HARNESS).';
+}
+
+function consoleProblem(res) {
+  const b = res?.body && typeof res.body === 'object' ? res.body : {};
+  return b.message || b.hint || b.error || res?.error || `HTTP ${res?.status ?? 0}`;
+}
+
+/** The rows `hs seat list` prints: every product seat, effective model + source, for one harness. */
+export function buildSeatRows(harness, assignments) {
+  const rows = normalizeAssignments(assignments);
+  return PRODUCT_SEATS.map((s) => {
+    const r = resolveSeatModel({ seat: s.id, harness, assignment: assignmentFor(rows, harness, s.id), overlay: () => null });
+    const own = r.source === 'user-assignment' ? rows.find((a) => a.harness === harness && a.seat === s.id) : null;
+    const rejectedAt = own?.override_rejected_at ?? null;
+    const label = rejectedAt
+      ? `you · this vault — REFUSED by ${harness === 'copilot' ? 'Copilot' : harness}, ran on auto`
+      : SOURCE_LABELS[r.source] ?? r.source;
+    return {
+      seat: s.id, title: s.title, tier: s.tier, harness, model: r.model, source: r.source,
+      override_rejected: Boolean(rejectedAt), override_rejected_at: rejectedAt, label,
+    };
+  });
+}
+
+/**
+ * Validate a model for `hs seat set` under the detected harness. Copilot uses sibling HS-F4UM's
+ * validateCopilotModel over listCopilotModels() (`auto` + the installed CLI's `copilot help config`
+ * ids, cached per CLI version): any well-formed id is accepted, an unlisted one with a warning.
+ */
+function validateForSet({ seat, harness, model, copilotModelList }) {
+  if (harness !== 'copilot') return validateSeatAssignment({ seat, harness, model });
+  const seatCheck = validateSeatAssignment({ seat, harness, model: 'auto' });
+  if (!seatCheck.ok) return seatCheck;
+  const c = validateCopilotModel(model, copilotModelList());
+  if (!c.ok) return { ok: false, error: 'invalid_model', message: c.error };
+  return { ok: true, seat: seatCheck.seat, harness, model: c.model, warnings: c.warning ? [c.warning] : [] };
+}
+
+/**
+ * @param {string[]} argv   arguments after `hs seat`
+ * @param {object} [deps]
+ * @param {object} [deps.env]
+ * @param {{write: Function}} [deps.stdout]
+ * @param {{write: Function}} [deps.stderr]
+ * @param {Function} [deps.consoleFetch]  injectable transport (tests); default is the shared MCP transport
+ * @param {string|null} [deps.vaultId]    cache key override (tests)
+ * @param {string[]|null} [deps.copilotModels]  Copilot CLI model list (sibling HS-F4UM); null = unknown
+ * @returns {Promise<number>} exit code
+ */
+export async function runSeatAssignCli(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const consoleFetch = deps.consoleFetch ?? (async (p, o) => (await import('./console-transport.mjs')).consoleFetch(p, o));
+  const fetchOpts = { consoleFetch, env, ...(deps.vaultId !== undefined ? { vaultId: deps.vaultId } : {}) };
+
+  const [sub = 'list', ...rest] = argv;
+  if (sub === '--help' || sub === '-h' || sub === 'help') { stdout.write(SEAT_CLI_USAGE); return 0; }
+  if (sub === 'defaults') return runSeatDefaultsCli(rest, { env, stdout, stderr });
+
+  const args = parseArgs(rest);
+  if (args.error) { stderr.write(`hs seat ${sub}: ${args.error}\n`); return 2; }
+  const detected = detect(env, args.harness);
+  const harness = detected.harness ?? null;
+
+  if (sub === 'list' || sub === 'assignments') {
+    if (args.positional.length) { stderr.write(`hs seat ${sub}: unexpected argument "${args.positional[0]}"\n`); return 2; }
+    const fetched = harness ? await fetchSeatAssignments({ ...fetchOpts, refresh: args.refresh }) : { source: 'none', assignments: [] };
+    const rows = buildSeatRows(harness, fetched.assignments);
+    if (args.json) {
+      stdout.write(`${JSON.stringify({ harness: detected, vault_id: fetched.vaultId ?? null, assignments_source: fetched.source, error: fetched.error ?? null, seats: rows }, null, 2)}\n`);
+      return 0;
+    }
+    if (!harness) stdout.write(`${noHarnessMessage(detected)}\n`);
+    else stdout.write(`Seats for harness: ${harness}\n`);
+    if (fetched.error) {
+      stdout.write(fetched.source === 'stale-cache'
+        ? `(could not reach the console: ${fetched.error} — showing your last saved choices)\n`
+        : `(could not read your seat choices: ${fetched.error} — showing harness defaults)\n`);
+    }
+    const w = Math.max(...rows.map((r) => r.seat.length));
+    const mw = Math.max(8, ...rows.map((r) => String(r.model ?? '-').length));
+    for (const r of rows) stdout.write(`  ${r.seat.padEnd(w)}  ${String(r.model ?? '-').padEnd(mw)}  ${r.label}\n`);
+    const refused = rows.filter((r) => r.override_rejected);
+    if (refused.length) {
+      stdout.write(
+        `\n${refused.length === 1 ? 'One seat\'s' : `${refused.length} seats'`} model was refused by ${harness === 'copilot' ? 'Copilot' : harness} on the last run, `
+        + 'so that run used auto instead: ' + refused.map((r) => `${r.seat} (${r.model})`).join(', ') + '.\n'
+        + (harness === 'copilot'
+          ? 'Your Copilot plan or org policy may not allow named models (Free and Student plans get auto only). '
+          : '')
+        + 'Pick another model with `hs seat set <seat> <model>`, or go back to the default with `hs seat reset <seat>`.\n',
+      );
+    }
+    return 0;
+  }
+
+  if (sub === 'report-fallback') {
+    // `hs seat report-fallback <seat> --log <file>`: a launcher hands over a Copilot seat run's
+    // stdout; a heyspex.copilot_model_fallback event marks the user's row override_rejected.
+    const logFile = args.log ?? null;
+    const seatArg = args.positional[0];
+    if (!seatArg || !logFile || args.positional.length !== 1) { stderr.write('hs seat report-fallback: expected <seat> --log <file>\n'); return 2; }
+    let logText;
+    try { logText = (deps.readFile ?? ((p) => readFileSync(p, 'utf8')))(logFile); } catch (err) {
+      stderr.write(`hs seat report-fallback: cannot read ${logFile}: ${err?.message ?? err}\n`); return 2;
+    }
+    const r = await reportCopilotFallback({ seat: seatArg, logText, consoleFetch, env, vaultId: deps.vaultId });
+    if (!r.reported && r.error) { stderr.write(`hs seat report-fallback: the console did not record it — ${r.error}\n`); return 1; }
+    stdout.write(r.reported
+      ? `Copilot refused ${r.model} for ${canonicalSeatId(seatArg)}; that run used auto. Recorded on your seat.\n`
+      : 'No Copilot model fallback in that run.\n');
+    return 0;
+  }
+
+  if (sub === 'set' || sub === 'reset') {
+    const need = sub === 'set' ? 2 : 1;
+    if (args.positional.length !== need) {
+      stderr.write(`hs seat ${sub}: expected ${sub === 'set' ? '<seat> <model>' : '<seat>'}\n${SEAT_CLI_USAGE}`);
+      return 2;
+    }
+    if (!harness) { stderr.write(`hs seat ${sub}: ${noHarnessMessage(detected)}\n`); return 2; }
+    const [seatArg, modelArg] = args.positional;
+    const copilotModelList = () => deps.copilotModelList
+      ?? (Array.isArray(deps.copilotModels) ? { models: ['auto', ...deps.copilotModels] } : listCopilotModels({ env }));
+    const verdict = sub === 'set'
+      ? validateForSet({ seat: seatArg, harness, model: modelArg, copilotModelList })
+      : validateSeatAssignment({ seat: seatArg, harness, model: harness === 'copilot' ? 'auto' : 'inherit' });
+    if (!verdict.ok) { stderr.write(`hs seat ${sub}: ${verdict.message}\n`); return 2; }
+    let res;
+    try {
+      res = sub === 'set'
+        ? await consoleFetch(SEATS_ENDPOINT, { method: 'PUT', body: { harness, seat: verdict.seat, model: verdict.model } })
+        : await consoleFetch(`${SEATS_ENDPOINT}?harness=${encodeURIComponent(harness)}&seat=${encodeURIComponent(verdict.seat)}`, { method: 'DELETE' });
+    } catch (err) {
+      res = { ok: false, status: 0, error: err?.message ?? String(err) };
+    }
+    if (!res?.ok) { stderr.write(`hs seat ${sub}: the console did not save it — ${consoleProblem(res)}\n`); return 1; }
+    const vaultId = res.body?.vault_id ?? deps.vaultId ?? null;
+    if (vaultId) invalidateSeatCache(vaultId, { env });
+    if (sub === 'set') {
+      for (const w of [...verdict.warnings, ...(Array.isArray(res.body?.warnings) ? res.body.warnings : [])].filter((x, i, a) => a.indexOf(x) === i)) {
+        stderr.write(`warning: ${w}\n`);
+      }
+      stdout.write(`${verdict.seat} → ${verdict.model} (you · this vault, ${harness})\n`);
+    } else {
+      const fallback = resolveSeatModel({ seat: canonicalSeatId(verdict.seat), harness, overlay: () => null });
+      stdout.write(`${verdict.seat} → ${fallback.model ?? '-'} (harness default, ${harness})${res.body?.removed === 0 ? ' — it was not set' : ''}\n`);
+    }
+    return 0;
+  }
+
+  stderr.write(`hs seat: unknown subcommand "${sub}"\n${SEAT_CLI_USAGE}`);
+  return 2;
+}
+
+/** Subcommands this customer CLI answers (bin/hs.mjs routes them here). */
+export const SEAT_ASSIGN_SUBCOMMANDS = Object.freeze(['list', 'assignments', 'set', 'reset', 'defaults', 'report-fallback', 'help']);
+
+const isMain = process.argv[1]?.replaceAll('\\', '/').endsWith('/seat-assign-cli.mjs');
+if (isMain) runSeatAssignCli(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/vendor/heyspex-mcp/seat-assignment-rules.mjs

@@ -0,0 +1,96 @@
+// vendor/heyspex-mcp/seat-assignment-rules.mjs
+//
+// The ONE validation rule set for a user's own seat → model assignment
+// ([[HS-K9L7-C86Z-EPIC-per-user-per-vault-seat-assignments]]). Shared by the console route
+// (`/api/me/seats`, spex-console imports this file) and the customer CLI (`hs seat set`), so the
+// two surfaces can never disagree about what a valid assignment is.
+//
+//   claude-code → a Claude alias (opus | sonnet | haiku | fable | inherit) or a full `claude-*` id.
+//   copilot     → `auto`, or a Copilot model id. HeySpex cannot check a user's Copilot
+//                 entitlement in advance (research HS-RXJO §Copilot defaults), so any id that is
+//                 not in the supplied Copilot list is ACCEPTED WITH A WARNING; until sibling epic
+//                 HS-F4UM supplies that list every non-auto id carries the warning.
+//
+// Seats must be PRODUCT roster seats (seat-defaults.mjs PRODUCT_SEATS) and never the human
+// `owner` seat. Pure: no fs, no env, no network.
+import { canonicalSeatId, COPILOT_DEFAULT_MODEL, PRODUCT_SEATS } from './seat-defaults.mjs';
+
+/** Harnesses a seat assignment can be keyed by. */
+export const ASSIGNABLE_HARNESSES = Object.freeze(['claude-code', 'copilot']);
+
+/** Claude Code model aliases (agent `model:` accepts these, plus a full id). */
+export const CLAUDE_MODEL_ALIASES = Object.freeze(['opus', 'sonnet', 'haiku', 'fable', 'inherit']);
+
+/** Longest model id we store. */
+export const MAX_MODEL_ID_LENGTH = 128;
+
+const MODEL_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:/\-[\]]*$/;
+const CLAUDE_FULL_ID = /^claude-[a-z0-9][a-z0-9.-]*(\[1m\])?$/i;
+
+const ASSIGNABLE_SEATS = new Set(PRODUCT_SEATS.filter((s) => s.tier !== 'human').map((s) => s.id));
+
+/** Product seats a user may assign (every non-human seat), in roster order. */
+export function listAssignableSeats() {
+  return PRODUCT_SEATS.filter((s) => ASSIGNABLE_SEATS.has(s.id));
+}
+
+/** True when `harness` is one of {@link ASSIGNABLE_HARNESSES}. */
+export function isAssignableHarness(harness) {
+  return ASSIGNABLE_HARNESSES.includes(harness);
+}
+
+/**
+ * Validate one assignment.
+ * @param {{ seat: string, harness: string, model: string, copilotModels?: string[]|null }} input
+ * @returns {{ ok: true, seat: string, harness: 'claude-code'|'copilot', model: string, warnings: string[] }
+ *          | { ok: false, error: 'invalid_seat'|'invalid_harness'|'invalid_model', message: string }}
+ */
+export function validateSeatAssignment({ seat, harness, model, copilotModels = null } = {}) {
+  const seatId = canonicalSeatId(seat);
+  if (!seatId || !ASSIGNABLE_SEATS.has(seatId)) {
+    const human = seatId === 'owner';
+    return {
+      ok: false,
+      error: 'invalid_seat',
+      message: human
+        ? 'The owner seat is a person, not a model — it cannot be assigned.'
+        : `Unknown seat "${seat ?? ''}". Run \`hs seat list\` for the seat ids.`,
+    };
+  }
+  if (!isAssignableHarness(harness)) {
+    return {
+      ok: false,
+      error: 'invalid_harness',
+      message: `harness must be one of ${ASSIGNABLE_HARNESSES.join(', ')} (got "${harness ?? ''}").`,
+    };
+  }
+  const m = typeof model === 'string' ? model.trim() : '';
+  if (!m) return { ok: false, error: 'invalid_model', message: 'model must be a non-empty model id.' };
+  if (m.length > MAX_MODEL_ID_LENGTH || !MODEL_ID_SHAPE.test(m)) {
+    return { ok: false, error: 'invalid_model', message: `"${m}" is not a valid model id.` };
+  }
+  const warnings = [];
+  if (harness === 'claude-code') {
+    const alias = m.toLowerCase();
+    if (CLAUDE_MODEL_ALIASES.includes(alias)) return { ok: true, seat: seatId, harness, model: alias, warnings };
+    if (!CLAUDE_FULL_ID.test(m)) {
+      return {
+        ok: false,
+        error: 'invalid_model',
+        message: `Claude Code seats take a Claude model: ${CLAUDE_MODEL_ALIASES.join(', ')} or a full claude-* id (got "${m}").`,
+      };
+    }
+    return { ok: true, seat: seatId, harness, model: m, warnings };
+  }
+  // copilot
+  if (m.toLowerCase() === COPILOT_DEFAULT_MODEL) {
+    return { ok: true, seat: seatId, harness, model: COPILOT_DEFAULT_MODEL, warnings };
+  }
+  const known = Array.isArray(copilotModels) ? copilotModels.filter((x) => typeof x === 'string') : null;
+  if (!known || known.length === 0) {
+    warnings.push(`HeySpex cannot check "${m}" against your Copilot plan yet; if Copilot refuses it the seat runs on auto.`);
+  } else if (!known.includes(m)) {
+    warnings.push(`"${m}" is not in your Copilot CLI's model list; if Copilot refuses it the seat runs on auto.`);
+  }
+  return { ok: true, seat: seatId, harness, model: m, warnings };
+}

package/vendor/heyspex-mcp/seat-assignments-client.mjs

@@ -0,0 +1,265 @@
+// vendor/heyspex-mcp/seat-assignments-client.mjs
+//
+// The client half of a user's own seat → model assignments
+// ([[HS-146G-C86Z-TASK-mcp-and-cli-seat-resolve-path-fetches]], epic
+// [[HS-K9L7-C86Z-EPIC-per-user-per-vault-seat-assignments]]). The MCP server and the `hs` CLI
+// fetch the caller's rows from `GET /api/me/seats` (authenticated, vault-scoped by the shared
+// console transport), keep a read-through copy at `~/.heyspex/seats/<vault_id>.json` (never under
+// the vault, never committed), and hand the row for (harness, seat) to resolveSeatModel's USER
+// ASSIGNMENT rung. Offline or refused → the cached copy; no cache → no assignment, so the seat
+// falls back to the harness default. Never reads or writes dev-factory/seats.json.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
+import { detectHarness } from '../../spexharness/src/adapters/harness-detect.mjs';
+import { canonicalSeatId } from './seat-defaults.mjs';
+import { readCurrentAccountId } from './credentials.mjs';
+import { resolveSeatModelForCaller } from './seat-identity.mjs';
+
+/** The console route this client talks to. */
+export const SEATS_ENDPOINT = '/api/me/seats';
+
+/** A cached copy younger than this is used without a network call. */
+export const SEAT_CACHE_MAX_AGE_MS = 5 * 60 * 1000;
+
+const SAFE_VAULT_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+
+/**
+ * The signed-in account the cache is keyed by: HS_ACCOUNT_ID, else the credentials store's current
+ * account under this HEYSPEX_HOME. Null when signed out (the cache then falls back to the vault key).
+ */
+export function seatCacheAccountId(env = process.env) {
+  const e = typeof env?.HS_ACCOUNT_ID === 'string' ? env.HS_ACCOUNT_ID.trim() : '';
+  if (e) return e;
+  try {
+    return readCurrentAccountId({ homeDir: heyspexHome(env) }) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `~/.heyspex/seats/<account_id>/<vault_id>.json` (signed in) or `~/.heyspex/seats/<vault_id>.json`
+ * (signed out) for a vault id, or null for an id unsafe as a file name. Keyed by ACCOUNT as well as
+ * vault ([[HS-92PF-C86Z-TASK-fresh-install-seat-acceptance-checks-in]]): two accounts signed in on one
+ * machine never read each other's cached choices. `accountId` undefined = resolve it; null = none.
+ */
+export function seatCacheFile(vaultId, { env = process.env, accountId } = {}) {
+  if (typeof vaultId !== 'string' || !SAFE_VAULT_ID.test(vaultId) || vaultId === '.' || vaultId === '..') return null;
+  const acct = accountId === undefined ? seatCacheAccountId(env) : accountId;
+  const scoped = typeof acct === 'string' && SAFE_VAULT_ID.test(acct) && acct !== '.' && acct !== '..';
+  return scoped
+    ? join(heyspexHome(env), '.heyspex', 'seats', acct, `${vaultId}.json`)
+    : join(heyspexHome(env), '.heyspex', 'seats', `${vaultId}.json`);
+}
+
+/** Keep only well-formed { harness, seat, model } rows. */
+export function normalizeAssignments(rows) {
+  if (!Array.isArray(rows)) return [];
+  const out = [];
+  for (const r of rows) {
+    if (!r || typeof r !== 'object') continue;
+    const harness = r.harness === 'claude-code' || r.harness === 'copilot' ? r.harness : null;
+    const seat = canonicalSeatId(r.seat ?? r.seatId);
+    const model = typeof r.model === 'string' ? r.model.trim() : '';
+    if (harness && seat && model) {
+      out.push({
+        harness, seat, model,
+        override_rejected_at: r.override_rejected_at ?? r.overrideRejectedAt ?? null,
+        updated_at: r.updated_at ?? r.updatedAt ?? null,
+      });
+    }
+  }
+  return out;
+}
+
+/** The user's model for one (harness, seat), or null. */
+export function assignmentFor(assignments, harness, seat) {
+  const id = canonicalSeatId(seat);
+  if (!harness || !id) return null;
+  const hit = normalizeAssignments(assignments).find((a) => a.harness === harness && a.seat === id);
+  return hit ? hit.model : null;
+}
+
+function readCache(file, readFile) {
+  if (!file) return null;
+  try {
+    const parsed = JSON.parse(readFile(file));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return { fetchedAt: Number(parsed.fetched_at) || 0, assignments: normalizeAssignments(parsed.assignments) };
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(file, payload, { mkdir, writeFile, rename }) {
+  if (!file) return;
+  try {
+    mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`);
+    rename(tmp, file);
+  } catch {
+    // Best effort: a cache that cannot be written only costs a network call next time.
+  }
+}
+
+/** The vault id the shared transport would send, or null. */
+function defaultVaultId() {
+  return import('./console-fetch.mjs')
+    .then((m) => {
+      try {
+        const h = m.getVaultIdHeader();
+        return h?.[m.VAULT_ID_HEADER] ?? null;
+      } catch {
+        return null;
+      }
+    })
+    .catch(() => null);
+}
+
+async function defaultConsoleFetch(path, options) {
+  const { consoleFetch } = await import('./console-transport.mjs');
+  return consoleFetch(path, options);
+}
+
+/**
+ * Fetch the caller's assignments for the current vault (cached, offline-tolerant).
+ * @param {object} [o]
+ * @param {(path: string, options?: object) => Promise<{ok: boolean, status: number, body?: any}>} [o.consoleFetch]
+ * @param {string|null} [o.vaultId]   cache key; defaults to the transport's resolved vault id
+ * @param {boolean} [o.refresh]       skip a fresh cache and ask the console
+ * @param {number} [o.maxAgeMs]
+ * @param {() => number} [o.now]
+ * @param {object} [o.env]            HEYSPEX_HOME override lives here (tests use fake homes)
+ * @param {object} [o.fs]             { readFile, writeFile, mkdir, rename } seams
+ * @returns {Promise<{ source: 'cache'|'console'|'stale-cache'|'none', vaultId: string|null, assignments: Array<{harness:string, seat:string, model:string}>, error?: string, status?: number, body?: any }>}
+ */
+export async function fetchSeatAssignments({
+  consoleFetch = defaultConsoleFetch,
+  vaultId,
+  refresh = false,
+  maxAgeMs = SEAT_CACHE_MAX_AGE_MS,
+  now = Date.now,
+  env = process.env,
+  fs = {},
+} = {}) {
+  const io = {
+    readFile: fs.readFile ?? ((p) => readFileSync(p, 'utf8')),
+    writeFile: fs.writeFile ?? ((p, d) => writeFileSync(p, d)),
+    mkdir: fs.mkdir ?? ((p, o) => mkdirSync(p, o)),
+    rename: fs.rename ?? ((a, b) => renameSync(a, b)),
+  };
+  const vid = vaultId === undefined ? await defaultVaultId() : vaultId;
+  const file = seatCacheFile(vid, { env });
+  const cached = readCache(file, io.readFile);
+  if (!refresh && cached && now() - cached.fetchedAt < maxAgeMs) {
+    return { source: 'cache', vaultId: vid, assignments: cached.assignments };
+  }
+  let res;
+  try {
+    res = await consoleFetch(SEATS_ENDPOINT);
+  } catch (err) {
+    res = { ok: false, status: 0, error: err?.message ?? String(err) };
+  }
+  if (res?.ok && res.body && typeof res.body === 'object') {
+    const assignments = normalizeAssignments(res.body.assignments);
+    const servedVault = typeof res.body.vault_id === 'string' ? res.body.vault_id : vid;
+    writeCache(seatCacheFile(servedVault, { env }), { vault_id: servedVault, fetched_at: now(), assignments }, io);
+    return { source: 'console', vaultId: servedVault, assignments, body: res.body };
+  }
+  const error = res?.error || res?.body?.error || `HTTP ${res?.status ?? 0}`;
+  if (cached) return { source: 'stale-cache', vaultId: vid, assignments: cached.assignments, error, status: res?.status };
+  return { source: 'none', vaultId: vid, assignments: [], error, status: res?.status };
+}
+
+/** Drop the cached copy so the next read asks the console (after a set/reset). */
+export function invalidateSeatCache(vaultId, { env = process.env, writeFile } = {}) {
+  const file = seatCacheFile(vaultId, { env });
+  if (!file) return;
+  try {
+    (writeFile ?? ((p, d) => writeFileSync(p, d)))(file, `${JSON.stringify({ vault_id: vaultId, fetched_at: 0, assignments: [] })}\n`);
+  } catch {
+    // nothing cached
+  }
+}
+
+// ── Copilot refused an override (HS-F4UM hand-off) ───────────────────────────
+// spexharness/src/seats/copilot-run.mjs retries a refused `--model <id>` once with `auto` and writes
+// a `heyspex.copilot_model_fallback` JSONL event ({ data: { from, to: 'auto', reason } }) on the
+// run's stdout. The launcher that knows WHICH seat it ran hands that log here, and the caller's own
+// assignment row is marked override_rejected (PATCH /api/me/seats) so `hs seat list` can say so.
+
+/** Matches copilot-run.mjs COPILOT_FALLBACK_EVENT (kept literal: no import of the launcher). */
+export const COPILOT_FALLBACK_EVENT_TYPE = 'heyspex.copilot_model_fallback';
+
+/** Every fallback event in a run's JSONL stdout: [{ from, to, reason, timestamp }]. */
+export function parseCopilotFallbackEvents(text) {
+  const out = [];
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t.startsWith('{') || !t.includes(COPILOT_FALLBACK_EVENT_TYPE)) continue;
+    try {
+      const e = JSON.parse(t);
+      if (e?.type !== COPILOT_FALLBACK_EVENT_TYPE || typeof e.data?.from !== 'string') continue;
+      out.push({ from: e.data.from, to: e.data.to ?? 'auto', reason: e.data.reason ?? null, timestamp: e.timestamp ?? null });
+    } catch {
+      // not JSON — Copilot's own text
+    }
+  }
+  return out;
+}
+
+/**
+ * Report a Copilot seat run's fallback to the console: marks the caller's (copilot, seat) row as
+ * override_rejected for the refused model. No fallback event in the log → no call. Never throws.
+ * @param {{ seat: string, logText?: string, events?: Array<{from: string}>, consoleFetch?: Function, vaultId?: string|null, env?: object }} p
+ * @returns {Promise<{ reported: boolean, model?: string, marked?: number, error?: string }>}
+ */
+export async function reportCopilotFallback({ seat, logText = '', events, consoleFetch = defaultConsoleFetch, vaultId, env = process.env } = {}) {
+  const evs = events ?? parseCopilotFallbackEvents(logText);
+  const last = evs.at(-1);
+  const seatId = canonicalSeatId(seat);
+  if (!last || !seatId) return { reported: false };
+  let res;
+  try {
+    res = await consoleFetch(SEATS_ENDPOINT, {
+      method: 'PATCH',
+      body: { harness: 'copilot', seat: seatId, model: last.from, override_rejected: true },
+    });
+  } catch (err) {
+    res = { ok: false, status: 0, error: err?.message ?? String(err) };
+  }
+  if (!res?.ok) return { reported: false, model: last.from, error: res?.body?.error || res?.error || `HTTP ${res?.status ?? 0}` };
+  const vid = res.body?.vault_id ?? vaultId ?? null;
+  if (vid) invalidateSeatCache(vid, { env });
+  return { reported: true, model: last.from, marked: Number(res.body?.marked) || 0 };
+}
+
+/**
+ * resolveSeatModelForCaller with the caller's own assignment filled in: detect the harness the
+ * same way the resolver does, pick the user's row for (harness, seat), and pass it as `assignment`.
+ * Synchronous; pass the rows from {@link fetchSeatAssignments}.
+ */
+export function resolveSeatModelWithAssignments({ assignments = [], ...opts } = {}) {
+  if (opts.assignment) return resolveSeatModelForCaller(opts);
+  const detected = detectHarness(opts.env ?? {}, opts.payload ?? null, opts.installedPlugins ?? []);
+  const assignment = assignmentFor(assignments, detected.harness, opts.seatId);
+  return resolveSeatModelForCaller({ ...opts, assignment });
+}
+
+/**
+ * The async one-call path for the MCP server / CLI: fetch (or read the cache), then resolve.
+ * Never throws for a console problem — it resolves to the harness default instead.
+ */
+export async function resolveSeatModelForCallerAsync({ fetchOptions = {}, ...opts } = {}) {
+  let fetched;
+  try {
+    fetched = await fetchSeatAssignments({ env: opts.env ?? process.env, ...fetchOptions });
+  } catch {
+    fetched = { source: 'none', assignments: [] };
+  }
+  const resolved = resolveSeatModelWithAssignments({ ...opts, assignments: fetched.assignments });
+  return { ...resolved, assignmentsSource: fetched.source };
+}