heyspex 0.2.6 → 0.2.7

package/spexharness/doctrine/baseline/SPEXCODE-DOCTRINE.baseline.json

@@ -1,29 +1,29 @@
-{
-  "schemaVersion": 1,
-  "edition": "baseline",
-  "learnedAt": "2026-09-11T10:05:22.053Z",
-  "curatedAt": "2026-10-03",
-  "_comment": "Baseline edition of SpexCode Doctrine: the foundational layer that ships in the heyspex npm package and is injected into customer sessions (owner ruling 2026-10-03, task HS-A2PO). Every principle is copied verbatim from the learned set (spexharness/doctrine/SPEXCODE-DOCTRINE.json, learnedAt above), with its confidence kept and its evidence ids dropped (they name the owner's own sessions). Selection rule: generic engineering practice only. Never add a rule about the spex-console dev server, Neon, the COO seat, dev-factory, the owner's own machine or preferences, or any heyspex-app path; spexharness/src/doctrine/inject.test.mjs fails if one appears. A customer's own learned layer is built on top of this file, never written into it.",
-  "sources": {
-    "curatedFrom": "spexharness/doctrine/SPEXCODE-DOCTRINE.json",
-    "principleCountInSource": 1481
-  },
-  "principles": [
-    { "text": "Treat a spec as done only after its own gate has run and exact pass/fail counts are reported.", "category": "verification", "confidence": 0.92, "stance": "do", "evidence": [] },
-    { "text": "Before reporting done, re-check every item in the stated range, not just the one flagged as missed, and explain the cause of any gap.", "category": "verification", "confidence": 0.9, "stance": "do", "evidence": [] },
-    { "text": "Back every claimed acceptance criterion with something actually run — tests, typecheck, lint, or measured timings — instead of asserting completion.", "category": "verification", "confidence": 0.9, "stance": "do", "evidence": [] },
-    { "text": "Never claim a build complete or flip status on faith; only after typecheck and the real tests are green.", "category": "verification", "confidence": 0.88, "stance": "avoid", "evidence": [] },
-    { "text": "When an exit test is unmet or a regression is found, say so explicitly in the artefact instead of papering over it or closing on a number you set out to beat and did not.", "category": "verification", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "Report exactly what was not done, could not be done, or failed, and name the blocker, rather than glossing over an untested branch or a red acceptance criterion.", "category": "verification", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "Touch only the files in scope; when an out-of-scope edit is unavoidable, keep it minimal and flag it explicitly.", "category": "session-hygiene", "confidence": 0.88, "stance": "do", "evidence": [] },
-    { "text": "When a design question is open, research it with the designated tools instead of guessing an answer or a number.", "category": "research-grounding", "confidence": 0.88, "stance": "do", "evidence": [] },
-    { "text": "Confirming an outline or stub is not doing the work; fill every section with real sourced content before reporting research done.", "category": "research-grounding", "confidence": 0.85, "stance": "avoid", "evidence": [] },
-    { "text": "Irreversible or transactional writes are two-phase: present a proposal and take a real human confirmation turn before executing, never in the same turn the proposal is authored.", "category": "safety-permissions", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "Run at the most restrictive permission mode until the folder is trusted, and never auto-approve a block-severity gate.", "category": "safety-permissions", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "Disclose known out-of-scope failures, deliberate deviations, and residual risk in the final report rather than burying them.", "category": "communication", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "End every close-out or status report with an explicit per-item outcome word (fixed, partly fixed, not fixed, not started), stated before the detail, so a found bug is never left ambiguous.", "category": "communication", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "Session titles stay short and descriptive in plain words, never raw spec/task ids, and remain sticky through follow-ups and sub-steps rather than changing at each turn.", "category": "naming", "confidence": 0.85, "stance": "do", "evidence": [] },
-    { "text": "Parallelise independent workstreams by spawning sub-agents instead of serialising everything in the main thread.", "category": "delegation", "confidence": 0.84, "stance": "do", "evidence": [] }
-  ],
-  "conflicts": []
-}
+{
+  "schemaVersion": 1,
+  "edition": "baseline",
+  "learnedAt": "2026-09-11T10:05:22.053Z",
+  "curatedAt": "2026-10-03",
+  "_comment": "Baseline edition of SpexCode Doctrine: the foundational layer that ships in the heyspex npm package and is injected into customer sessions (owner ruling 2026-10-03, task HS-A2PO). Every principle is copied verbatim from the learned set (spexharness/doctrine/SPEXCODE-DOCTRINE.json, learnedAt above), with its confidence kept and its evidence ids dropped (they name the owner's own sessions). Selection rule: generic engineering practice only. Never add a rule about the spex-console dev server, Neon, the COO seat, dev-factory, the owner's own machine or preferences, or any heyspex-app path; spexharness/src/doctrine/inject.test.mjs fails if one appears. A customer's own learned layer is built on top of this file, never written into it.",
+  "sources": {
+    "curatedFrom": "spexharness/doctrine/SPEXCODE-DOCTRINE.json",
+    "principleCountInSource": 1481
+  },
+  "principles": [
+    { "text": "Treat a spec as done only after its own gate has run and exact pass/fail counts are reported.", "category": "verification", "confidence": 0.92, "stance": "do", "evidence": [] },
+    { "text": "Before reporting done, re-check every item in the stated range, not just the one flagged as missed, and explain the cause of any gap.", "category": "verification", "confidence": 0.9, "stance": "do", "evidence": [] },
+    { "text": "Back every claimed acceptance criterion with something actually run — tests, typecheck, lint, or measured timings — instead of asserting completion.", "category": "verification", "confidence": 0.9, "stance": "do", "evidence": [] },
+    { "text": "Never claim a build complete or flip status on faith; only after typecheck and the real tests are green.", "category": "verification", "confidence": 0.88, "stance": "avoid", "evidence": [] },
+    { "text": "When an exit test is unmet or a regression is found, say so explicitly in the artefact instead of papering over it or closing on a number you set out to beat and did not.", "category": "verification", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Report exactly what was not done, could not be done, or failed, and name the blocker, rather than glossing over an untested branch or a red acceptance criterion.", "category": "verification", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Touch only the files in scope; when an out-of-scope edit is unavoidable, keep it minimal and flag it explicitly.", "category": "session-hygiene", "confidence": 0.88, "stance": "do", "evidence": [] },
+    { "text": "When a design question is open, research it with the designated tools instead of guessing an answer or a number.", "category": "research-grounding", "confidence": 0.88, "stance": "do", "evidence": [] },
+    { "text": "Confirming an outline or stub is not doing the work; fill every section with real sourced content before reporting research done.", "category": "research-grounding", "confidence": 0.85, "stance": "avoid", "evidence": [] },
+    { "text": "Irreversible or transactional writes are two-phase: present a proposal and take a real human confirmation turn before executing, never in the same turn the proposal is authored.", "category": "safety-permissions", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Run at the most restrictive permission mode until the folder is trusted, and never auto-approve a block-severity gate.", "category": "safety-permissions", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Disclose known out-of-scope failures, deliberate deviations, and residual risk in the final report rather than burying them.", "category": "communication", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "End every close-out or status report with an explicit per-item outcome word (fixed, partly fixed, not fixed, not started), stated before the detail, so a found bug is never left ambiguous.", "category": "communication", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Session titles stay short and descriptive in plain words, never raw spec/task ids, and remain sticky through follow-ups and sub-steps rather than changing at each turn.", "category": "naming", "confidence": 0.85, "stance": "do", "evidence": [] },
+    { "text": "Parallelise independent workstreams by spawning sub-agents instead of serialising everything in the main thread.", "category": "delegation", "confidence": 0.84, "stance": "do", "evidence": [] }
+  ],
+  "conflicts": []
+}

package/spexharness/src/adapters/copilot-models.mjs

@@ -0,0 +1,179 @@
+// spexharness/src/adapters/copilot-models.mjs
+//
+// Which models can a Copilot seat be pointed at? ([[HS-OUIT-C86Z-TASK-copilot-model-list-from-the-copilot-cli]]
+// of epic [[HS-F4UM-C86Z-EPIC-copilot-model-list-and-auto-pass-through]]; design: research
+// [[HS-RXJO-C86Z-RES-spexfleet-per-user-seat-assignment-with]] §Copilot defaults.)
+//
+// Owner ruling: under Copilot every seat defaults to `auto`; a seat may be overridden to any model the
+// Copilot harness offers. There is NO supported per-user entitlement listing (github/copilot-cli#700),
+// so the list here is the installed CLI's SUPPORTED-model enum, printed by `copilot help config`
+// under the `model` key - suggestions, not a promise. Any well-formed typed id is accepted too: the
+// Copilot CLI itself is the final check at launch, and a rejected override falls back to `auto` for
+// that run (spexharness/src/seats/copilot-run.mjs).
+//
+// The parsed list is cached per CLI version under <HEYSPEX_HOME>/.heyspex/cache/copilot-models.json
+// (never under the vault, never in ~/.copilot). Everything impure is injectable so tests never run a
+// real Copilot.
+//
+//   node spexharness/src/adapters/copilot-models.mjs [--refresh] [--json]
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveCopilotCli } from '../../../scripts/lib/copilot-cli.mjs';
+import { heyspexHome } from '../../../scripts/lib/heyspex-home.mjs';
+
+/** Copilot's automatic model selection: always offered, always first, the default for every seat. */
+export const COPILOT_AUTO = 'auto';
+
+/** The cache file name under <home>/.heyspex/cache/. */
+export const COPILOT_MODELS_CACHE_FILE = 'copilot-models.json';
+
+/** Where the per-version cache lives. */
+export function copilotModelsCachePath(env = process.env) {
+  return path.join(heyspexHome(env), '.heyspex', 'cache', COPILOT_MODELS_CACHE_FILE);
+}
+
+/**
+ * Pull the `model` enum out of `copilot help config` text. The block looks like
+ *     `model`: AI model to use for Copilot CLI; ...
+ *       - "claude-sonnet-5.5"
+ *       - "gpt-5.4"
+ * and ends at the first line that is not a `- "id"` row (a blank line or the next `key`). The format
+ * is not a stable contract (a user in copilot-cli#700 saw an earlier list vanish), so anything
+ * unexpected yields [] rather than a guess.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parseCopilotModelEnum(text) {
+  const lines = String(text ?? '').split(/\r?\n/);
+  const start = lines.findIndex((l) => /^\s*`model`\s*:/.test(l));
+  if (start < 0) return [];
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = /^\s*-\s*"([^"]+)"\s*$/.exec(lines[i]);
+    if (!m) break;
+    const id = m[1].trim();
+    if (id && id !== COPILOT_AUTO && !out.includes(id)) out.push(id);
+  }
+  return out;
+}
+
+/** `GitHub Copilot CLI 1.0.100-1.` → `1.0.100-1`; null when no version is found. */
+export function parseCopilotVersion(text) {
+  const m = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)/.exec(String(text ?? ''));
+  return m ? m[1].replace(/\.$/, '') : null;
+}
+
+/** Run the CLI once (Windows npm shims need a shell). Returns { status, stdout } or null on spawn failure. */
+function defaultRun(cliPath, args) {
+  const shim = /\.(cmd|bat)$/i.test(cliPath);
+  const q = (a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a);
+  try {
+    const opts = { encoding: 'utf8', timeout: 30000, windowsHide: true };
+    // A shim goes through the shell as ONE pre-quoted command line (args + shell:true is deprecated, DEP0190).
+    const r = shim ? spawnSync([cliPath, ...args].map(q).join(' '), { ...opts, shell: true }) : spawnSync(cliPath, args, opts);
+    if (r.error) return null;
+    return { status: r.status, stdout: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+  } catch { return null; }
+}
+
+function readCache(file, readFile) {
+  try { const j = JSON.parse(readFile(file)); return j && typeof j === 'object' && j.versions && typeof j.versions === 'object' ? j : { versions: {} }; } catch { return { versions: {} }; }
+}
+
+/**
+ * @typedef {object} CopilotModelList
+ * @property {string[]} models        `auto` first, then the CLI's supported ids (in the CLI's order)
+ * @property {'copilot help config'|'cache'|'none'} source
+ * @property {string|null} cliVersion
+ * @property {string|null} cliPath
+ * @property {string|null} cachedAt   ISO time the list was read from the CLI
+ * @property {string} note            the entitlement caveat, for display
+ */
+
+/** Shown wherever the list is shown: the list is what the CLI supports, not what this user may use. */
+export const COPILOT_MODELS_NOTE =
+  'Models the installed Copilot CLI supports (`copilot help config`), not a per-user entitlement list - plan and org policy decide what actually runs. Any typed id is accepted; Copilot is the final check and a rejected override falls back to auto for that run.';
+
+/**
+ * List the models a Copilot seat can be set to. Never throws: no CLI → `['auto']`, source `none`.
+ * @param {{ refresh?: boolean, env?: Record<string,string|undefined>, cli?: {path: string, version?: string}|null,
+ *           run?: (cliPath: string, args: string[]) => ({status: number|null, stdout: string}|null),
+ *           cachePath?: string, readFile?: (p: string) => string, writeFile?: (p: string, s: string) => void,
+ *           now?: () => Date }} [opts]
+ * @returns {CopilotModelList}
+ */
+export function listCopilotModels(opts = {}) {
+  const env = opts.env ?? process.env;
+  const run = opts.run ?? defaultRun;
+  const now = opts.now ?? (() => new Date());
+  const cachePath = opts.cachePath ?? copilotModelsCachePath(env);
+  const readFile = opts.readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
+  const writeFile = opts.writeFile ?? ((p, s) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, s); });
+  const cli = opts.cli !== undefined ? opts.cli : resolveCopilotCli({ env });
+  const result = (models, source, cliVersion, cachedAt) => Object.freeze({
+    models: Object.freeze([COPILOT_AUTO, ...models]), source, cliVersion, cliPath: cli?.path ?? null, cachedAt, note: COPILOT_MODELS_NOTE,
+  });
+  if (!cli?.path) return result([], 'none', null, null);
+
+  // The version keys the cache: the child-process marker when we are inside Copilot, else `copilot --version`.
+  let version = (typeof env.COPILOT_CLI_BINARY_VERSION === 'string' && env.COPILOT_CLI_BINARY_VERSION.trim()) || cli.version || null;
+  if (!version) { const v = run(cli.path, ['--version']); version = v ? parseCopilotVersion(v.stdout) : null; }
+  const key = version ?? 'unknown';
+
+  const cache = readCache(cachePath, readFile);
+  const hit = cache.versions[key];
+  if (!opts.refresh && version && hit && Array.isArray(hit.models) && hit.models.length) {
+    return result(hit.models, 'cache', version, hit.cachedAt ?? null);
+  }
+
+  const r = run(cli.path, ['help', 'config']);
+  const models = r ? parseCopilotModelEnum(r.stdout) : [];
+  if (!models.length) {
+    // The CLI answered with no parsable enum: an older cached list for this version beats nothing.
+    if (hit?.models?.length) return result(hit.models, 'cache', version, hit.cachedAt ?? null);
+    return result([], 'none', version, null);
+  }
+  const cachedAt = now().toISOString();
+  if (version) {
+    cache.versions[key] = { models, cachedAt, cliPath: cli.path };
+    try { writeFile(cachePath, `${JSON.stringify(cache, null, 2)}\n`); } catch { /* the cache is an optimisation only */ }
+  }
+  return result(models, 'copilot help config', version, cachedAt);
+}
+
+/** A model id Copilot could plausibly take: non-empty, no whitespace or quotes, bounded length. */
+const WELL_FORMED = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/;
+
+/**
+ * Validate a typed Copilot model id for a seat (`hs seat set <seat> <model> --harness copilot`).
+ * Unknown-but-well-formed ids are ACCEPTED with a warning: the list is not an entitlement list, and
+ * Copilot's own refusal (with the auto fallback) is the final check.
+ * @param {string} id
+ * @param {{ models?: readonly string[] }|CopilotModelList} [list]  default: listCopilotModels()
+ * @returns {{ ok: boolean, model: string|null, known: boolean, warning?: string, error?: string }}
+ */
+export function validateCopilotModel(id, list) {
+  const model = String(id ?? '').trim();
+  if (!model) return { ok: false, model: null, known: false, error: 'a Copilot model id is required (use "auto" to let Copilot pick)' };
+  if (!WELL_FORMED.test(model)) return { ok: false, model: null, known: false, error: `"${model}" is not a valid Copilot model id (letters, digits and . _ : / @ + - only, no spaces)` };
+  if (model === COPILOT_AUTO) return { ok: true, model, known: true };
+  const models = (list ?? listCopilotModels()).models ?? [];
+  if (models.includes(model)) return { ok: true, model, known: true };
+  return {
+    ok: true, model, known: false,
+    warning: `"${model}" is not in the installed Copilot CLI's model list${models.length > 1 ? '' : ' (no list could be read)'}; it is kept as typed - Copilot decides at launch, and a rejected model falls back to auto for that run`,
+  };
+}
+
+const isMain = process.argv[1]?.replaceAll('\\', '/').endsWith('/copilot-models.mjs');
+if (isMain) {
+  const list = listCopilotModels({ refresh: process.argv.includes('--refresh') });
+  if (process.argv.includes('--json')) console.log(JSON.stringify(list, null, 2));
+  else {
+    console.log(`Copilot models (${list.source}${list.cliVersion ? `, CLI ${list.cliVersion}` : ''}):`);
+    for (const m of list.models) console.log(`  ${m}${m === COPILOT_AUTO ? '  (default for every seat)' : ''}`);
+    console.log(`\n${list.note}`);
+  }
+}

package/spexharness/src/adapters/harness-detect.mjs

@@ -0,0 +1,148 @@
+// spexharness/src/adapters/harness-detect.mjs
+//
+// Which coding harness is this HeySpex process running under, for SEAT DEFAULTS?
+// ([[HS-KQ5E-C86Z-TASK-pure-harness-detection-and-seat-default]] of epic
+// [[HS-C65J-C86Z-EPIC-harness-aware-seat-default-resolver]]; design: research
+// [[HS-RXJO-C86Z-RES-spexfleet-per-user-seat-assignment-with]] §Harness detection; owner rulings 2026-10-17.)
+//
+// The sibling ./detect-harness.mjs answers a narrower question (which output dialect a HOOK must
+// speak) and always returns a string. This module answers "whose models are the seat defaults",
+// so it must also say WHERE the answer came from and refuse to guess when it cannot tell:
+//
+//   1. env.HEYSPEX_HARNESS (claude-code | copilot | none)        — every plugin/kit install stamps it
+//   2. hook payload shape (the existing detectHarness)           — when a payload is present
+//   3. positive env markers                                      — Copilot: COPILOT_AGENT_SESSION_ID,
+//        COPILOT_CLI, COPILOT_PLUGIN_ROOT; Claude Code: CLAUDECODE, CLAUDE_CODE_SESSION_ID.
+//        Both present → copilot (a Claude Code shell launching Copilot is the documented nesting;
+//        the reverse is not). CLAUDE_PLUGIN_ROOT is NEVER a marker: Copilot expands it too.
+//   4. installed plugins                                         — exactly one → that harness;
+//        several → status 'needs-choice' (the caller asks); none → status 'none'.
+//
+// Pure: env, payload and the installed-plugin list come in; nothing is read here. The one impure
+// helper, listInstalledHarnessPlugins(), takes injected fs deps and an explicit home so tests use
+// fake homes and never touch a real ~/.claude or ~/.copilot.
+
+import path from 'node:path';
+import { detectHarness as detectHookHarness } from './detect-harness.mjs';
+
+/** The harnesses that carry their own seat defaults. */
+export const SEAT_HARNESSES = Object.freeze(['claude-code', 'copilot']);
+
+/** Env markers that positively identify Copilot CLI (observed in its child processes, 2026-10-17 probe). */
+export const COPILOT_ENV_MARKERS = Object.freeze(['COPILOT_AGENT_SESSION_ID', 'COPILOT_CLI', 'COPILOT_PLUGIN_ROOT']);
+
+/** Env markers that positively identify Claude Code. CLAUDE_PLUGIN_ROOT is deliberately absent. */
+export const CLAUDE_ENV_MARKERS = Object.freeze(['CLAUDECODE', 'CLAUDE_CODE_SESSION_ID']);
+
+/** Accepted spellings of an explicit HEYSPEX_HARNESS value. */
+const EXPLICIT = Object.freeze({
+  'claude-code': 'claude-code',
+  claude: 'claude-code',
+  claudecode: 'claude-code',
+  copilot: 'copilot',
+  'github-copilot': 'copilot',
+  none: null,
+});
+
+/** Normalize a harness name to 'claude-code' | 'copilot', or undefined when it is not one. */
+export function normalizeHarness(value) {
+  const key = String(value ?? '').trim().toLowerCase();
+  if (!key || !Object.prototype.hasOwnProperty.call(EXPLICIT, key)) return undefined;
+  return EXPLICIT[key];
+}
+
+const present = (env, k) => typeof env?.[k] === 'string' && env[k].trim() !== '';
+
+/**
+ * @typedef {object} HarnessResult
+ * @property {'claude-code'|'copilot'|null} harness
+ * @property {'resolved'|'needs-choice'|'none'} status
+ * @property {'env:HEYSPEX_HARNESS'|'hook-payload'|'env-marker'|'installed-plugin'|'none'} source
+ * @property {string|null} detail   which marker / plugin decided it (null when nothing did)
+ * @property {string[]} [choices]   set only for status 'needs-choice'
+ */
+
+/**
+ * @param {Record<string, string|undefined>} [env]
+ * @param {unknown} [payload] parsed hook stdin, when this runs inside a hook
+ * @param {string[]} [installedPlugins] harnesses the heyspex plugin is installed for
+ * @returns {HarnessResult}
+ */
+export function detectHarness(env = {}, payload = null, installedPlugins = []) {
+  const safeEnv = env && typeof env === 'object' ? env : {};
+
+  // 1. Explicit stamp. `none` is an explicit "no harness" (plain terminal), not a fall-through.
+  if (present(safeEnv, 'HEYSPEX_HARNESS')) {
+    const h = normalizeHarness(safeEnv.HEYSPEX_HARNESS);
+    if (h !== undefined) {
+      return Object.freeze({ harness: h, status: h ? 'resolved' : 'none', source: 'env:HEYSPEX_HARNESS', detail: String(safeEnv.HEYSPEX_HARNESS).trim() });
+    }
+  }
+
+  // 2. Hook payload shape. The hook detector reads HEYSPEX_HARNESS itself; pass a stripped env so a
+  //    junk value (rejected above) cannot leak back in through it.
+  if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+    const fromPayload = detectHookHarness(payload, {});
+    if (fromPayload === 'claude-code' || fromPayload === 'copilot') {
+      return Object.freeze({ harness: fromPayload, status: 'resolved', source: 'hook-payload', detail: fromPayload });
+    }
+  }
+
+  // 3. Positive env markers, Copilot first (nesting rule).
+  const copilotMarker = COPILOT_ENV_MARKERS.find((k) => present(safeEnv, k));
+  if (copilotMarker) return Object.freeze({ harness: 'copilot', status: 'resolved', source: 'env-marker', detail: copilotMarker });
+  const claudeMarker = CLAUDE_ENV_MARKERS.find((k) => present(safeEnv, k));
+  if (claudeMarker) return Object.freeze({ harness: 'claude-code', status: 'resolved', source: 'env-marker', detail: claudeMarker });
+
+  // 4. Installed plugins.
+  const installed = [...new Set((Array.isArray(installedPlugins) ? installedPlugins : []).map(normalizeHarness).filter(Boolean))].sort();
+  if (installed.length === 1) {
+    return Object.freeze({ harness: installed[0], status: 'resolved', source: 'installed-plugin', detail: installed[0] });
+  }
+  if (installed.length > 1) {
+    return Object.freeze({ harness: null, status: 'needs-choice', source: 'installed-plugin', detail: null, choices: Object.freeze(installed) });
+  }
+  return Object.freeze({ harness: null, status: 'none', source: 'none', detail: null });
+}
+
+/**
+ * The value a launcher should stamp into HEYSPEX_HARNESS for its child, or null when it cannot tell
+ * from env alone (then it stamps nothing and the child falls back to its own detection).
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {'claude-code'|'copilot'|null}
+ */
+export function harnessStampFor(env = {}) {
+  const r = detectHarness(env, null, []);
+  return r.status === 'resolved' ? r.harness : null;
+}
+
+/**
+ * Which harnesses the heyspex plugin is installed for. Best effort, never throws.
+ * Evidence: ~/.claude/plugins/installed_plugins.json with a "heyspex@…" key → claude-code;
+ * a heyspex entry under <copilotHome>/installed-plugins or <copilotHome>/plugins (one level of
+ * <marketplace>/<plugin> nesting) → copilot.
+ * @param {{ home: string, copilotHome?: string, deps: { readFile: (p: string) => string|null, listDir: (p: string) => string[] } }} opts
+ * @returns {string[]}
+ */
+export function listInstalledHarnessPlugins({ home, copilotHome, deps }) {
+  const out = [];
+  if (!home || !deps) return out;
+  const read = (p) => { try { return deps.readFile(p); } catch { return null; } };
+  const list = (p) => { try { const r = deps.listDir(p); return Array.isArray(r) ? r : []; } catch { return []; } };
+  try {
+    const raw = read(path.join(home, '.claude', 'plugins', 'installed_plugins.json'));
+    if (raw) {
+      const j = JSON.parse(raw);
+      const keys = Object.keys(j?.plugins ?? j ?? {});
+      if (keys.some((k) => /^heyspex(@|$)/i.test(k))) out.push('claude-code');
+    }
+  } catch { /* unreadable registry is no evidence */ }
+  const cHome = copilotHome || path.join(home, '.copilot');
+  const isOurs = (n) => /^heyspex(@|$|-)/i.test(String(n));
+  for (const sub of ['installed-plugins', 'plugins']) {
+    const dir = path.join(cHome, sub);
+    const names = list(dir);
+    if (names.some(isOurs) || names.some((n) => list(path.join(dir, n)).some(isOurs))) { out.push('copilot'); break; }
+  }
+  return out;
+}