heyspex 0.2.0 → 0.2.1

package/scripts/lib/customer-kit.mjs

@@ -50,8 +50,11 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { dispositionFor } from './hook-dispositions.mjs';
+
 /** @typedef {'customer' | 'platform'} KitScope */
 
 /**
@@ -75,6 +78,7 @@ export const HOOK_SCOPES = Object.freeze({
   'inject-communication-style': { scope: 'customer', why: 'Plain-language communication rules each turn.' },
   'inject-vault-context': { scope: 'customer', why: 'Lexical vault retrieval for the prompt.' },
   'git-identity-guard': { scope: 'customer', why: 'Agents never write git identity (owner ruling 2026-09-19).' },
+  'vault-write-tier-guard': { scope: 'customer', why: 'Cloud write mode: disk edits to vault specs are a mirror the console never reads back (HS-FCNH).' },
   'settings-write-gate': { scope: 'customer', why: 'Approval before the vault\'s .heyspex/config.yaml changes.' },
   'emit-claim-status': { scope: 'customer', why: 'Claim liveness heartbeat to the console.' },
   'enforce-vault-naming': { scope: 'customer', why: 'Naming V3 filename guard (HS-RY2N).' },
@@ -82,7 +86,10 @@ export const HOOK_SCOPES = Object.freeze({
   'plan-review-gate': { scope: 'customer', why: 'Plan review + QC markers before ExitPlanMode.' },
   'plan-exit-ingest-gate': { scope: 'customer', why: 'Plan ingest on ExitPlanMode; arms claim-before-code.' },
   'claim-before-code-gate': { scope: 'customer', why: 'First code edit after plan exit needs a claim.' },
+  'directive-obligation-gate': { scope: 'customer', why: 'A capture_on_idea directive leaves a durable obligation; an unmet one denies sub-agent spawns, product-code writes and builds, and re-drives Stop once. Also claim-before-build (HS-20SW).' },
   'capture-workflow-gate': { scope: 'customer', why: 'No implementation spec straight out of an open capture.' },
+  'vault-mirror-catchup': { scope: 'customer', why: 'Cloud write mode: a SessionStart detached `hs pull --apply` closes a stale disk mirror before the first tool call (HS-XJFQ).' },
+  'diagnose-capture-reminder': { scope: 'customer', why: 'Warn when a diagnose is filed with no capture holding the owner\'s words (HS-IK2D).' },
   'git-stash-gate': { scope: 'customer', why: 'Always ask before a mutating git stash.' },
   'research-method-guard': { scope: 'customer', why: 'Research method guard (HS-EN4F).' },
   'deep-research-cost-gate': { scope: 'customer', why: 'Cost confirmation before a paid deep-research launch.' },
@@ -102,6 +109,7 @@ export const HOOK_SCOPES = Object.freeze({
   'coo-guard-check': { scope: 'platform', why: 'dev-factory breakdown-delegation guard.' },
   'coo-denylist-gate': { scope: 'platform', why: 'dev-factory COO window deny list.' },
   'agent-spawn-delegation-gate': { scope: 'platform', why: 'dev-factory seat routing for subagents.' },
+  'capture-execution-gate': { scope: 'platform', why: 'Blocks dev-factory research/paid-model/routing surfaces past an ungrounded capture (HS-KNJ8).' },
   'check-mcp-freshness-hook': { scope: 'platform', why: 'Freshness of the vendored MCP build — a platform-dev concern.' },
   'dev-server-task-reminder': { scope: 'platform', why: 'spex-console dev server + Neon DB safety.' },
   'env-vault-guard': { scope: 'platform', why: 'Guards heyspex-app\'s encrypted env vault paths.' },
@@ -138,6 +146,7 @@ export const CLAUDE_HOOK_ROWS = Object.freeze([
   { event: 'SessionStart', hook: 'check-claude-md-budget', timeout: 5 },
   { event: 'SessionStart', hook: 'check-mcp-freshness-hook', timeout: 5 },
   { event: 'SessionStart', hook: 'git-reflog-audit', timeout: 5 },
+  { event: 'SessionStart', hook: 'vault-mirror-catchup', timeout: 5 },
   { event: 'PreCompact', hook: 'wip-checkpoint', timeout: 5 },
   { event: 'UserPromptSubmit', hook: 'preflight-reminder', timeout: 5 },
   { event: 'UserPromptSubmit', hook: 'intent-classifier-trigger', timeout: 5 },
@@ -145,10 +154,13 @@ export const CLAUDE_HOOK_ROWS = Object.freeze([
   { event: 'UserPromptSubmit', hook: 'inject-vault-context', timeout: 10 },
   { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell', hook: 'env-vault-guard', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Bash|PowerShell', hook: 'git-identity-guard', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell', hook: 'vault-write-tier-guard', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit|Bash|PowerShell|mcp__heyspex__heyspex_settings_set', hook: 'settings-write-gate', timeout: 5 },
   { event: 'PreToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PreToolUse'], timeout: 5 },
   { event: 'PreToolUse', matcher: '.*', hook: 'coo-denylist-gate', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Agent|Task', hook: 'agent-spawn-delegation-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Bash|PowerShell|Agent|Task', hook: 'capture-execution-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Agent|Task|Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell', hook: 'directive-obligation-gate', timeout: 5 },
   { event: 'PreToolUse', matcher: 'mcp__heyspex__heyspex_claim_spec', hook: 'coo-guard-check', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Write|NotebookEdit|Bash|PowerShell', hook: 'enforce-vault-naming', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Write|NotebookEdit|Bash|PowerShell', hook: 'guard-auto-memory-writes', timeout: 5 },
@@ -157,6 +169,7 @@ export const CLAUDE_HOOK_ROWS = Object.freeze([
   { event: 'PreToolUse', matcher: 'ExitPlanMode', hook: 'plan-exit-ingest-gate', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Edit|MultiEdit|Write', hook: 'claim-before-code-gate', timeout: 5 },
   { event: 'PreToolUse', matcher: 'mcp__heyspex__heyspex_file_spec', hook: 'capture-workflow-gate', timeout: 8 },
+  { event: 'PreToolUse', matcher: 'mcp__heyspex__heyspex_file_spec', hook: 'diagnose-capture-reminder', timeout: 5 },
   { event: 'PreToolUse', matcher: 'Bash|PowerShell|mcp__neon__prepare_database_migration|mcp__neon__complete_database_migration|mcp__neon__reset_from_parent|mcp__neon__delete_branch|mcp__Neon__prepare_database_migration|mcp__Neon__complete_database_migration|mcp__Neon__reset_from_parent|mcp__Neon__delete_branch', hook: 'dev-server-task-reminder', timeout: 10 },
   { event: 'PreToolUse', matcher: 'Bash|PowerShell', hook: 'git-stash-gate', timeout: 10 },
   { event: 'PreToolUse', matcher: 'Skill|Workflow', hook: 'research-method-guard', timeout: 5 },
@@ -169,7 +182,9 @@ export const CLAUDE_HOOK_ROWS = Object.freeze([
   { event: 'Stop', hook: 'epic-milestone-phrasing-gate', timeout: 5 },
   { event: 'Stop', hook: 'git-reflog-audit', timeout: 5 },
   { event: 'Stop', hook: 'enforce-session-sequence', timeout: 5 },
+  { event: 'Stop', hook: 'directive-obligation-gate', timeout: 5 },
   { event: 'PostToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PostToolUse'], timeout: 5 },
+  { event: 'PostToolUse', matcher: 'Skill|mcp__heyspex__heyspex_update_capture|mcp__heyspex__heyspex_promote_capture.*|mcp__heyspex__heyspex_file_spec|mcp__heyspex__heyspex_claim_spec|mcp__heyspex__heyspex_release_spec|mcp__heyspex__heyspex_defer_spec', hook: 'directive-obligation-gate', timeout: 5 },
   { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', hook: 'notify-status-flip', timeout: 5 },
   { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', hook: 'close-terminal-on-ship', timeout: 5 },
   { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', hook: 'scripts/stamp-provenance-on-edit.mjs', timeout: 5 },
@@ -305,11 +320,73 @@ export const CUSTOMER_LAUNCHERS = Object.freeze({
  */
 export function customerRunnerPrefix(_platformRoot, surface = 'claude') {
   const l = CUSTOMER_LAUNCHERS[surface];
+  // Claude rows are self-locating (Copilot CLI loads .claude/settings.json and does not document CLAUDE_PROJECT_DIR).
+  if (surface === 'claude') return CUSTOMER_RUNNER_PREFIX;
   return `node "$${l.projectDirEnv}/${l.rel.join('/')}"`;
 }
 
 /** Runner prefix inside the plugin: its own launcher, which finds the platform. */
-export const PLUGIN_RUNNER_PREFIX = 'node "${CLAUDE_PLUGIN_ROOT}/bin/run-hook.mjs"';
+const BOOTSTRAP_WALK =
+  "var d=process.cwd(),r=e.CLAUDE_PROJECT_DIR;if(!r||!f.existsSync(p.join(r,...n))){r='';for(;;){if(f.existsSync(p.join(d,...n))){r=d;break}var q=p.dirname(d);if(q===d)break;d=q}}";
+
+/**
+ * SELF-LOCATING BOOTSTRAP ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]], Copilot compatibility).
+ *
+ * GitHub Copilot CLI runs the hooks in .claude/settings.json too, but it is not documented to set
+ * CLAUDE_PROJECT_DIR / CLAUDE_PLUGIN_ROOT, and a PowerShell-run command expands an unset $VAR to
+ * nothing - so \`node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs"\` became \`node /scripts/...\`,
+ * MODULE_NOT_FOUND, exit 1, and Copilot turns ANY non-zero exit into a DENY (on a \`.*\` matcher: every tool
+ * call). A registered command must therefore (a) work with no env var at all, under bash AND PowerShell, and
+ * (b) FAIL OPEN when it cannot find the runtime. It is an inline \`node -e\` script, single-quoted JS only
+ * (no double quote, backslash, dollar or backtick), so it survives JSON and every shell unchanged:
+ *   root = CLAUDE_PROJECT_DIR if it holds the shim, else walk up from cwd looking for scripts/claude-hooks/_run.mjs;
+ *   not found -> exit 0; found -> import the shim in-process with the same argv and stdin (the shim owns both).
+ * The plugin variant first tries <CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT>/bin/run-hook.mjs. The trailing //comment is
+ * deliberate: it keeps the recognisable ...scripts/claude-hooks/_run.mjs" <hook> tail every drift check,
+ * ourHookTail and the doctor already parse.
+ * @param {{ plugin?: boolean }} [opts]
+ */
+export function buildBootstrap({ plugin = false } = {}) {
+  const walk = BOOTSTRAP_WALK;
+  const body = plugin
+    ? "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=['scripts','claude-hooks','_run.mjs'],s='',m=e.CLAUDE_PLUGIN_ROOT||e.COPILOT_PLUGIN_ROOT||e.PLUGIN_ROOT;" +
+      "if(m&&f.existsSync(p.join(m,'bin','run-hook.mjs')))s=p.join(m,'bin','run-hook.mjs');" +
+      "if(!s){" + walk + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}}"
+    : "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=['scripts','claude-hooks','_run.mjs'],s='';" +
+      walk + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}";
+  return (
+    body +
+    "if(!s)process.exit(0);process.argv=[process.argv[0],s].concat(process.argv.slice(1));" +
+    "import(u.pathToFileURL(s).href).catch(function(){process.exit(0)});" +
+    (plugin ? '//bin/run-hook.mjs' : '//scripts/claude-hooks/_run.mjs')
+  );
+}
+
+/** Platform checkout runner (.claude/settings.json): self-locating, env-independent, fail-open. */
+export const PLATFORM_RUNNER_PREFIX = 'node -e "' + buildBootstrap() + '"';
+
+/** Runner prefix inside the plugin: self-locating too (plugin root env, then cwd walk-up), fail-open. */
+export const PLUGIN_RUNNER_PREFIX = 'node -e "' + buildBootstrap({ plugin: true }) + '"';
+
+/**
+ * Customer-repo bootstrap (same defect, same fix as {@link buildBootstrap}): the committed launcher
+ * `.claude/heyspex/run-hook.mjs` is resolved from CLAUDE_PROJECT_DIR if it holds the launcher, else by walking up
+ * from cwd, else exit 0 (fail open). Sets CLAUDE_PROJECT_DIR to the found root so the shim reads
+ * <project>/.heyspex/mode.json (`hs mode off`). Single-quoted JS only; survives JSON, bash and PowerShell.
+ */
+export function buildCustomerBootstrap() {
+  const rel = CUSTOMER_LAUNCHERS.claude.rel.map((s) => "'" + s + "'").join(',');
+  return (
+    "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=[" + rel + "],s='';" +
+    BOOTSTRAP_WALK + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}" +
+    "if(!s)process.exit(0);process.argv=[process.argv[0],s].concat(process.argv.slice(1));" +
+    "import(u.pathToFileURL(s).href).catch(function(){process.exit(0)});" +
+    '//' + CUSTOMER_LAUNCHERS.claude.rel.join('/')
+  );
+}
+
+/** Customer repo runner (.claude/settings.json): self-locating, env-independent, fail-open. */
+export const CUSTOMER_RUNNER_PREFIX = 'node -e "' + buildCustomerBootstrap() + '"';
 
 // The launcher is kept as ONE template string (not a sibling file) so the
 // bundled CLI (`dist/cli/*.mjs`, built from install.ts) carries it by
@@ -392,7 +469,12 @@ const LAUNCHER_TEMPLATE = [
   '// (the Cursor one) runs exactly as if Cursor had invoked it directly.',
   'const shim = resolve(root, ...SHIM);',
   'process.argv[1] = shim;',
-  'await import(pathToFileURL(shim).href);',
+  'try {',
+  '  await import(pathToFileURL(shim).href);',
+  '} catch (err) {',
+  "  process.stderr.write('[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  '  process.exit(0);',
+  '}',
   '',
 ].join('\n');
 
@@ -576,15 +658,10 @@ export function renderPluginHooksDocument() {
       hooks: [{ type: 'command', command: d.command, timeout: d.timeout }],
     });
   }
+  // No top-level `_comment`: GitHub Copilot loads this file too and a strict reader may reject unknown keys. The
+  // provenance note lives in plugins/heyspex/README.md (GENERATED from this file's customer-scoped rows; edit
+  // scripts/lib/customer-kit.mjs and run `node scripts/lib/customer-kit.mjs --write-plugin-hooks`).
   return {
-    _comment:
-      'GENERATED from scripts/lib/customer-kit.mjs (customer-scoped rows only) — do not edit by hand; ' +
-      'run `node scripts/lib/customer-kit.mjs --write-plugin-hooks`. Every command goes through ' +
-      'bin/run-hook.mjs, which finds the hook runtime (HEYSPEX_PLATFORM_ROOT / HEYSPEX_MCP_ENTRY when set ' +
-      'in the machine\'s own env, then the plugin\'s own location, node_modules/heyspex, ' +
-      '$CLAUDE_PROJECT_DIR) — never $CLAUDE_PROJECT_DIR/scripts, which only exists in heyspex-app. ' +
-      'WARNING: a repo whose .claude/settings.json already carries the hs install kit hooks runs every ' +
-      'hook twice if this plugin is also enabled — use one or the other.',
     hooks,
   };
 }
@@ -593,6 +670,230 @@ export function renderPluginHooksText() {
   return `${JSON.stringify(renderPluginHooksDocument(), null, 2)}\n`;
 }
 
+// ---------------------------------------------------------------------------
+// GitHub Copilot cloud agent: .github/hooks/heyspex.json
+// ---------------------------------------------------------------------------
+// The cloud agent loads NO plugins and no user-level hook files; its only hook source is
+// `.github/hooks/*.json` on the default branch. This is the one place a generated Copilot
+// manifest is justified ([[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]], option 3).
+// Generated from the SAME customer rows as hooks.json, restricted to the hooks whose Copilot
+// disposition (scripts/lib/hook-dispositions.mjs) is 'mapped'. The cloud agent is Linux bash only,
+// so every entry is `type: "command"` with a `bash` command; no PowerShell, no node -e bootstrap.
+
+/** Claude hook event -> Copilot hooks event (camelCase, as documented for the CLI and the cloud agent). */
+export const COPILOT_EVENT_NAMES = Object.freeze({
+  SessionStart: 'sessionStart',
+  SessionEnd: 'sessionEnd',
+  UserPromptSubmit: 'userPromptSubmitted',
+  PreToolUse: 'preToolUse',
+  PostToolUse: 'postToolUse',
+  Stop: 'agentStop',
+  PreCompact: 'preCompact',
+});
+
+/**
+ * Hooks shipped to the cloud agent although their Copilot disposition is 'advisory-degraded': their
+ * prompt-time OUTPUT is dropped, but they still run and ARM state (the HS-20SW capture obligation), and
+ * the 'mapped' directive-obligation-gate is inert without that arming.
+ */
+export const GITHUB_HOOKS_STATE_ARMING = Object.freeze(['intent-classifier-trigger']);
+
+/** Claude tool name -> Copilot tool name (documented: ask_user bash create edit glob grep powershell task view web_fetch). */
+const COPILOT_TOOL_NAMES = Object.freeze({
+  Write: 'create',
+  Edit: 'edit',
+  MultiEdit: 'edit',
+  NotebookEdit: 'edit',
+  Bash: 'bash',
+  PowerShell: 'powershell',
+  Agent: 'task',
+  Task: 'task',
+  WebFetch: 'web_fetch',
+  WebSearch: 'web_search',
+});
+
+/**
+ * Translate a Claude matcher to Copilot tool names. MCP tools become a suffix regex because the MCP
+ * tool-name spelling inside hook payloads is not documented (unverified live); tools with no Copilot
+ * counterpart (Skill, Workflow, ExitPlanMode) are dropped.
+ * @param {string | undefined} matcher
+ * @returns {string | null | undefined} undefined = no matcher, null = nothing translatable
+ */
+export function toCopilotMatcher(matcher) {
+  if (!matcher) return undefined;
+  const out = [];
+  for (const part of matcher.split('|')) {
+    let t = null;
+    if (part === '.*') t = '.*';
+    else if (COPILOT_TOOL_NAMES[part]) t = COPILOT_TOOL_NAMES[part];
+    else if (part.startsWith(MCP_PROJECT_PREFIX)) t = '.*' + part.slice(MCP_PROJECT_PREFIX.length);
+    else if (part.startsWith(MCP_PLUGIN_PREFIX)) t = '.*' + part.slice(MCP_PLUGIN_PREFIX.length);
+    if (t && !out.includes(t)) out.push(t);
+  }
+  if (out.includes('.*')) return '.*';
+  return out.length ? out.join('|') : null;
+}
+
+/** Hooks the cloud-agent manifest carries (see the module comment above). */
+export function githubHookNames() {
+  const names = new Set();
+  for (const r of customerHookRows()) {
+    if (dispositionFor(r.hook, 'copilot')?.disposition === 'mapped' || GITHUB_HOOKS_STATE_ARMING.includes(r.hook)) names.add(r.hook);
+  }
+  return names;
+}
+
+/**
+ * The bash command for one hook: resolve the runtime from node_modules/heyspex first, then the checkout's own
+ * scripts/, else exit 0 (fail open; Copilot turns any non-zero exit into a deny).
+ * @param {{ hook: string, args?: string[] }} row
+ */
+export function githubHookCommand(row) {
+  const tail = hookTail(row);
+  return (
+    'R=node_modules/heyspex/scripts/claude-hooks/_run.mjs; ' +
+    '[ -f "$R" ] || R=./scripts/claude-hooks/_run.mjs; ' +
+    '[ -f "$R" ] || exit 0; ' +
+    `exec node "$R" ${tail}`
+  );
+}
+
+/** The cloud agent's .github/hooks/heyspex.json document, generated from the customer rows. */
+export function renderGithubHooksDocument() {
+  const allowed = githubHookNames();
+  const hooks = {};
+  for (const row of customerHookRows()) {
+    if (!allowed.has(row.hook)) continue;
+    const event = COPILOT_EVENT_NAMES[row.event];
+    if (!event) continue;
+    const matcher = toCopilotMatcher(row.matcher);
+    if (matcher === null) continue; // a tool-scoped row with no Copilot tool to match
+    (hooks[event] ??= []).push({
+      type: 'command',
+      ...(matcher ? { matcher } : {}),
+      bash: githubHookCommand(row),
+      timeoutSec: row.timeout,
+    });
+  }
+  return { version: 1, hooks };
+}
+
+export function renderGithubHooksText() {
+  return `${JSON.stringify(renderGithubHooksDocument(), null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Double-firing detector (plugin AND repo hooks)
+// ---------------------------------------------------------------------------
+// Copilot CLI reads hooks from the plugin AND from .claude/settings.json / .github/hooks in the repo, and
+// Claude Code does the same for plugin + .claude/settings.json: with both present every hook runs twice.
+// Rule: pick one of plugin OR repo hooks. This detector is pure (injected fs), so the doctor and a test share it.
+
+const readJsonFile = (deps, file) => {
+  try {
+    const text = deps.readFile(file);
+    return text == null ? undefined : JSON.parse(text);
+  } catch {
+    return null; // present but unparseable
+  }
+};
+
+/** @param {unknown} settings */
+function countOurRows(settings) {
+  let n = 0;
+  const hooks = settings && typeof settings === 'object' && settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+  for (const groups of Object.values(hooks)) {
+    for (const g of Array.isArray(groups) ? groups : []) {
+      // Claude shape: { matcher, hooks: [{ command }] }; Copilot .github/hooks shape: { bash } / { command }.
+      const cmds = Array.isArray(g?.hooks) ? g.hooks.map((h) => h?.command) : [g?.command, g?.bash];
+      for (const c of cmds) if (typeof c === 'string' && (ourHookTail(c) !== null || /claude-hooks\/_run\.mjs/.test(c))) n++;
+    }
+  }
+  return n;
+}
+
+/**
+ * Whether BOTH repo-level HeySpex hooks AND an installed heyspex plugin are present for a project.
+ *
+ * Repo hooks: HeySpex rows in <project>/.claude/settings.json, .claude/settings.local.json or
+ * <project>/.github/hooks/*.json. Plugin evidence (any of): ~/.claude/plugins/installed_plugins.json with a
+ * "heyspex@..." key; `enabledPlugins` naming heyspex in ~/.claude/settings.json or the project's Claude settings;
+ * a heyspex directory under ~/.copilot/installed-plugins or ~/.copilot/plugins (best effort: the Copilot plugin
+ * list file is not documented, `copilot plugin list` is the authority). If no plugin registry can be read at all
+ * and repo hooks exist, the answer is 'unknown' (never a failure).
+ * @param {{ targetRoot: string, home?: string, deps?: { readFile: (p: string) => string | null, listDir?: (p: string) => string[] } }} opts
+ * @returns {{ status: 'ok' | 'warn' | 'unknown', detail: string, repoHooks: number, plugin: boolean | null, evidence: string[] }}
+ */
+export function detectDoubleFire({ targetRoot, home = os.homedir(), deps = fsDeps }) {
+  const evidence = [];
+  const repoFiles = ['.claude/settings.json', '.claude/settings.local.json'].map((f) => path.join(targetRoot, f));
+  let repoHooks = 0;
+  for (const f of repoFiles) {
+    const n = countOurRows(readJsonFile(deps, f));
+    if (n) { repoHooks += n; evidence.push(`${n} HeySpex hook row(s) in ${f}`); }
+  }
+  const ghDir = path.join(targetRoot, '.github', 'hooks');
+  for (const name of (deps.listDir ? deps.listDir(ghDir) : []).filter((x) => x.endsWith('.json'))) {
+    const n = countOurRows(readJsonFile(deps, path.join(ghDir, name)));
+    if (n) { repoHooks += n; evidence.push(`${n} HeySpex hook row(s) in .github/hooks/${name}`); }
+  }
+
+  let readable = 0;
+  let plugin = false;
+  const installed = readJsonFile(deps, path.join(home, '.claude', 'plugins', 'installed_plugins.json'));
+  if (installed !== undefined) {
+    readable++;
+    const keys = Object.keys(installed?.plugins ?? installed ?? {});
+    if (keys.some((k) => /^heyspex(@|$)/i.test(k))) { plugin = true; evidence.push('heyspex in ~/.claude/plugins/installed_plugins.json'); }
+  }
+  const userSettings = path.join(home, '.claude', 'settings.json');
+  for (const f of [userSettings, ...repoFiles]) {
+    const st = readJsonFile(deps, f);
+    if (st === undefined) continue;
+    if (f === userSettings) readable++; // a project file proves nothing about what is installed elsewhere
+    const ep = st?.enabledPlugins;
+    if (ep && typeof ep === 'object' && Object.entries(ep).some(([k, v]) => /^heyspex(@|$)/i.test(k) && v !== false)) {
+      plugin = true;
+      evidence.push(`heyspex in enabledPlugins of ${f}`);
+    }
+  }
+  if (deps.listDir) {
+    for (const sub of ['installed-plugins', 'plugins']) {
+      const dir = path.join(home, '.copilot', sub);
+      const names = deps.listDir(dir);
+      if (names.length) readable++;
+      if (names.some((n) => /heyspex/i.test(n))) {
+        plugin = true;
+        evidence.push(`heyspex under ${dir}`);
+      } else {
+        // one level deeper: <marketplace>/<plugin> layouts
+        for (const n of names) {
+          if (deps.listDir(path.join(dir, n)).some((m) => /heyspex/i.test(m))) {
+            plugin = true;
+            evidence.push(`heyspex under ${path.join(dir, n)}`);
+          }
+        }
+      }
+    }
+  }
+
+  if (repoHooks === 0) return { status: 'ok', detail: 'no repo-level HeySpex hooks to double up with a plugin', repoHooks, plugin: plugin || null, evidence };
+  if (plugin) {
+    return {
+      status: 'warn',
+      detail: `HeySpex hooks are registered in the repo AND the heyspex plugin is installed, so every hook fires twice (${evidence.join('; ')})`,
+      repoHooks,
+      plugin: true,
+      evidence,
+    };
+  }
+  if (readable === 0) {
+    return { status: 'unknown', detail: 'repo-level HeySpex hooks present, but no plugin registry could be read to rule out a second copy', repoHooks, plugin: null, evidence };
+  }
+  return { status: 'ok', detail: 'repo-level hooks only; no heyspex plugin found', repoHooks, plugin: false, evidence };
+}
+
+
 // ---------------------------------------------------------------------------
 // Harness commands (.claude/commands, .cursor/commands)
 // ---------------------------------------------------------------------------
@@ -880,6 +1181,22 @@ if (invokedDirectly(import.meta.url, 'customer-kit.mjs')) {
       process.exit(1);
     }
     console.log('customer-kit: plugins/heyspex/hooks/hooks.json up to date');
+  } else if (process.argv.includes('--write-github-hooks') || process.argv.includes('--check-github-hooks')) {
+    const ghTarget = path.join(platformRoot, '.github', 'hooks', 'heyspex.json');
+    const ghWant = renderGithubHooksText();
+    const ghSame = (fsDeps.readFile(ghTarget) ?? '').replace(/\r\n/g, '\n') === ghWant;
+    if (process.argv.includes('--write-github-hooks')) {
+      if (!ghSame) {
+        fs.mkdirSync(path.dirname(ghTarget), { recursive: true });
+        fs.writeFileSync(ghTarget, ghWant, 'utf8');
+      }
+      console.log(`customer-kit: ${ghSame ? 'unchanged' : 'wrote'} ${path.relative(platformRoot, ghTarget).replace(/\\/g, '/')}`);
+    } else if (!ghSame) {
+      console.error('customer-kit: .github/hooks/heyspex.json is stale - run `node scripts/lib/customer-kit.mjs --write-github-hooks`');
+      process.exit(1);
+    } else {
+      console.log('customer-kit: .github/hooks/heyspex.json up to date');
+    }
   } else {
     console.log('usage: node scripts/lib/customer-kit.mjs --write-plugin-hooks | --check-plugin-hooks');
   }

package/scripts/lib/dev-mode.mjs

@@ -47,6 +47,7 @@
  *
  * Zero deps beyond node builtins (same rule as console-url-resolver.mjs).
  */
+import { heyspexHome } from './heyspex-home.mjs';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -58,7 +59,7 @@ export const LOCAL_CONSOLE_URL = 'http://localhost:3000';
 export const DEV_MODE_FILENAME = 'dev-mode.json';
 
 /** Absolute path of the machine-local record. */
-export function devModeFilePath(homeDir = homedir()) {
+export function devModeFilePath(homeDir = heyspexHome()) {
   return join(homeDir, '.heyspex', DEV_MODE_FILENAME);
 }
 
@@ -97,7 +98,7 @@ const defaultReadFile = (p) => readFileSync(p, 'utf8');
  * `readFile` is an injectable seam (same shape as the TS twin's) so the
  * parity test can feed both implementations the SAME in-memory fixture.
  */
-export function readLocalDevModeRecord({ homeDir = homedir(), readFile = defaultReadFile } = {}) {
+export function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   let raw;
   try {
     raw = readFile(devModeFilePath(homeDir));
@@ -135,7 +136,7 @@ export function readLocalDevModeRecord({ homeDir = homedir(), readFile = default
  */
 export function resolveDevMode({
   env = process.env,
-  homeDir = homedir(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   cloudSetting = undefined,
 } = {}) {
@@ -382,7 +383,7 @@ export function upsertCredentialsYamlKeys(homeDir, updates) {
  * its historical name for the hook scripts that import it; the precedence is
  * the shared module's, never re-implemented here.
  */
-export function readCredentialsMcpToken({ env = process.env, homeDir = homedir() } = {}) {
+export function readCredentialsMcpToken({ env = process.env, homeDir = heyspexHome() } = {}) {
   return readBearer({ env, homeDir }).token;
 }
 
@@ -432,7 +433,7 @@ async function discardResponseBody(res) {
 export async function fetchCloudDevMode({
   consoleUrl,
   fetchImpl = fetch,
-  homeDir = homedir(),
+  homeDir = heyspexHome(),
   timeoutMs = 4000,
 } = {}) {
   if (!consoleUrl) return { ok: false, setting: undefined, error: 'no console url' };
@@ -488,7 +489,7 @@ export class DevModeNotAdminError extends Error {
 export async function applyDevMode(
   target,
   {
-    homeDir = homedir(),
+    homeDir = heyspexHome(),
     fetchImpl = fetch,
     source = 'cli',
     now = () => new Date().toISOString(),