heyspex 0.1.0 → 0.2.1

package/scripts/dev-server-status.mjs

@@ -39,6 +39,13 @@ import http from 'node:http';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+// The runnable form of a HeySpex command on THIS machine — `hs …` when the bin
+// is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" …`. Never an
+// `npx` form: npx resolves from the READER's working directory, and outside a
+// checkout `npx hs` installs the unrelated public package hs@2.0.1
+// ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+import { hsCommand } from './lib/hs-command.mjs';
+
 // `/api/version` is the spex-console liveness endpoint (cheap JSON, no page
 // render). Probing `/` false-negatives during Next dev JIT compiles — the full
 // app shell can exceed 2s while API routes the UI already uses keep returning
@@ -109,14 +116,30 @@ function readLockfile(vaultRoot) {
   return { present: false, pid: null, url: null, startedAt: null, host: null, lan: null };
 }
 
+/**
+ * Count of rows in `.heyspex/index-write-failures.jsonl` — the durable, operator-visible
+ * record `spex-console/src/lib/vault.ts`'s `recordIndexWriteFailure` appends to whenever a
+ * Neon index upsert fails and the write falls through to disk-only (QC finding, harness
+ * security epic HS-KRK5). A `console.error` line alone scrolls out of view; surfacing the
+ * count here means `heyspex_dev_server_status` (and `hs dev-status`) actually show it.
+ * Missing/unreadable file => 0, never a throw — this status check must never itself fail.
+ */
+function countIndexWriteFailures(vaultRoot) {
+  const file = path.join(vaultRoot, '.heyspex', 'index-write-failures.jsonl');
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    return raw.split(/\r?\n/).filter((line) => line.trim().length > 0).length;
+  } catch {
+    return 0;
+  }
+}
+
 function readConsoleUrlFile(vaultRoot) {
-  for (const name of ['console-url', 'cockpit-url']) { // legacy-cockpit fallback
-    try {
-      const raw = fs.readFileSync(path.join(vaultRoot, '.heyspex', name), 'utf8').trim();
-      if (raw.length > 0) return raw.replace(/\/+$/, '');
-    } catch {
-      // try next candidate
-    }
+  try {
+    const raw = fs.readFileSync(path.join(vaultRoot, '.heyspex', 'console-url'), 'utf8').trim();
+    if (raw.length > 0) return raw.replace(/\/+$/, '');
+  } catch {
+    // missing or unreadable discovery file
   }
   return null;
 }
@@ -135,11 +158,6 @@ export function writeConsoleUrlFile(vaultRoot, url) {
   const normalized = String(url).trim().replace(/\/+$/, '');
   fs.writeFileSync(tmp, `${normalized}\n`, 'utf8');
   fs.renameSync(tmp, file);
-  try {
-    fs.writeFileSync(path.join(dir, 'cockpit-url'), `${normalized}\n`, 'utf8'); // legacy-cockpit shadow
-  } catch {
-    // Best-effort — canonical console-url above is authoritative.
-  }
   return normalized;
 }
 
@@ -463,7 +481,7 @@ const DISCREPANCY_GUIDANCE_TEXT = {
   port_mismatch:
     'The lockfile points at one port but the live console server is answering on a different one. A server IS running (see `servers`) — do not start a new one; use the port shown in `servers`, not the lockfile\'s port.',
   multiple_servers:
-    'More than one console server is answering at once — this is the corrupted-.next state two concurrent `next dev` processes cause. Do NOT start another. Stop the extras first (`hs server stop` / `npm run console:stop`).',
+    `More than one console server is answering at once — this is the corrupted-.next state two concurrent \`next dev\` processes cause. Do NOT start another. Stop the extras first (\`${hsCommand('server stop')}\` / \`npm run console:stop\`).`,
   page_probe_failed:
     'The API probe answered but a real page route failed to render (HS-D4O9-DIAG: e.g. a missing dependency leaves every page throwing while API handlers keep answering 200). The server is up but likely broken — check server logs / reinstall deps. Restarting the dev server will usually NOT fix this on its own, so do not treat this flag as "not running".',
 };
@@ -647,6 +665,9 @@ export async function getDevServerStatus({ vaultRoot, ports, pagePath } = {}) {
     // entry is restart-BLOCKING (evidence a server exists), never a restart
     // trigger. See DISCREPANCY_GUIDANCE_TEXT above for the per-code rationale.
     discrepancyGuidance: buildDiscrepancyGuidance([...new Set(discrepancies)]),
+    // Additive (QC finding, harness security epic HS-KRK5): a count, not the raw rows —
+    // an operator glancing at status output needs "is this happening", not a full replay.
+    indexWriteFailures: countIndexWriteFailures(root),
     platform: process.platform,
     checkedAt: new Date().toISOString(),
   };

package/scripts/dev-server-stop.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * dev-server-stop — stop the spex-console Next.js dev server from any terminal.
+ *
+ * Pairs with scripts/dev-server-status.mjs (ground-truth probe). Kills ONLY
+ * processes attributable to the console — the lockfile-recorded launcher pid
+ * (+ its child tree), HTTP-identified console listeners, and node processes on
+ * the lockfile's own port — then clears the discovery files the launcher
+ * leaves behind when force-killed (exit handlers do not run under
+ * `taskkill /F`).
+ *
+ * HS-W7E3: this script used to kill EVERY listener on the candidate port range
+ * and took down Docker Desktop's backend (listening on 3002) as collateral.
+ * Unattributable listeners are now left alone and reported; the old sweep is
+ * opt-in behind `--force-ports`, never the default.
+ *
+ * Faces:
+ *   - npm run console:stop
+ *   - hs server stop
+ *
+ * Run:  node scripts/dev-server-stop.mjs [--json] [--dry-run] [--force-ports]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { getDevServerStatus, summarizeStatus } from './dev-server-status.mjs';
+
+function defaultVaultRoot() {
+  if (process.env.HS_VAULT_ROOT) return process.env.HS_VAULT_ROOT;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+function discoveryPaths(vaultRoot) {
+  const dir = path.join(vaultRoot, '.heyspex');
+  return {
+    lock: path.join(dir, 'dev-server.lock.json'),
+    consoleUrl: path.join(dir, 'console-url'),
+  };
+}
+
+function clearDiscovery(vaultRoot) {
+  const paths = discoveryPaths(vaultRoot);
+  const removed = [];
+  for (const [key, file] of Object.entries(paths)) {
+    try {
+      if (fs.existsSync(file)) {
+        fs.rmSync(file, { force: true });
+        removed.push(key);
+      }
+    } catch {
+      // Best-effort — status re-check is the source of truth.
+    }
+  }
+  return removed;
+}
+
+function pidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Kill a process and its descendants. Mirrors ensure-next-dev.mjs killChildTree:
+ * on Windows `shell: true` means the listening pid is often a grandchild, so
+ * `taskkill /T /F` is required.
+ */
+function killProcessTree(pid) {
+  if (!pidAlive(pid)) {
+    return { pid, killed: false, reason: 'not_alive' };
+  }
+  if (process.platform === 'win32') {
+    const result = spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    return {
+      pid,
+      killed: result.status === 0,
+      reason: result.status === 0 ? 'taskkill' : `taskkill_exit_${result.status ?? 'err'}`,
+    };
+  }
+  try {
+    process.kill(-pid, 'SIGTERM'); // process group when possible
+  } catch {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // Already gone.
+    }
+  }
+  // Sync grace (~1s) then SIGKILL — Atomics.wait is the portable sleep.
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
+  } catch {
+    // SharedArrayBuffer unavailable — fall through to immediate SIGKILL.
+  }
+  if (pidAlive(pid)) {
+    try {
+      process.kill(-pid, 'SIGKILL');
+    } catch {
+      try {
+        process.kill(pid, 'SIGKILL');
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return { pid, killed: !pidAlive(pid), reason: 'signal' };
+}
+
+// Local twin of dev-server-status.mjs's portFromUrl (not exported there).
+function portFromUrl(url) {
+  if (typeof url !== 'string') return null;
+  try {
+    const u = new URL(url);
+    if (u.port) return Number(u.port);
+    return u.protocol === 'https:' ? 443 : 80;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide what to kill — pure and unit-testable (HS-W7E3). A pid is targeted
+ * ONLY when it is attributable to the console:
+ *   - the lockfile's recorded launcher pid (killProcessTree covers its
+ *     children, so the `next dev` grandchild goes with it), or
+ *   - a listener the HTTP probe identified as spex-console, or
+ *   - a node-named listener on the exact port the lockfile points at (a hung
+ *     console child that stopped answering HTTP).
+ * Every other listener on the candidate range (Docker's backend, a Firecrawl
+ * container, any unrelated dev tool) is SKIPPED and reported, unless the
+ * caller explicitly opted into the old sweep with `--force-ports`.
+ */
+export function planKills(status, { forcePorts = false } = {}) {
+  const targets = new Map();
+  const skipped = [];
+  const addTarget = (pid, reason, port = null) => {
+    if (!pid || typeof pid !== 'number') return;
+    const entry = targets.get(pid) || { pid, ports: [], reasons: [] };
+    if (port != null && !entry.ports.includes(port)) entry.ports.push(port);
+    if (!entry.reasons.includes(reason)) entry.reasons.push(reason);
+    targets.set(pid, entry);
+  };
+
+  const lock = status.lockfile || {};
+  const lockPort = portFromUrl(lock.url);
+  if (lock.present && lock.pidAlive && lock.pid) {
+    addTarget(lock.pid, 'lockfile pid (console launcher; tree kill covers its children)');
+  }
+
+  for (const server of status.servers || []) {
+    if (server.probe === 'console') {
+      addTarget(server.pid, `HTTP-identified spex-console on :${server.port}`, server.port);
+    } else if (
+      lock.present &&
+      lockPort != null &&
+      server.port === lockPort &&
+      /^node(\.exe)?$/i.test(server.name || '')
+    ) {
+      addTarget(server.pid, `node process on the lockfile's port :${server.port}`, server.port);
+    } else if (forcePorts) {
+      addTarget(server.pid, `--force-ports sweep on :${server.port}`, server.port);
+    } else if (server.pid) {
+      skipped.push({
+        pid: server.pid,
+        port: server.port,
+        name: server.name || '',
+        reason: 'not attributable to the console (use --force-ports to sweep)',
+      });
+    }
+  }
+
+  return { targets: [...targets.values()], skipped };
+}
+
+function describeTarget(t) {
+  const ports = t.ports.length ? ` (:${t.ports.join(', :')})` : '';
+  return `pid ${t.pid}${ports} — ${t.reasons.join('; ')}`;
+}
+
+function describeSkipped(s) {
+  return `pid ${s.pid}${s.name ? ` (${s.name})` : ''} on :${s.port} — ${s.reason}`;
+}
+
+export async function stopDevServer({ vaultRoot, forcePorts = false, dryRun = false } = {}) {
+  const root = vaultRoot || defaultVaultRoot();
+  const before = await getDevServerStatus({ vaultRoot: root });
+  const plan = planKills(before, { forcePorts });
+  const hadLock = before.lockfile?.present === true;
+  // HS-W7E3: "running" means console-attributed work to do — an unrelated
+  // listener on a candidate port (Docker on 3002…) is NOT the console running.
+  const wasRunning = before.running || plan.targets.length > 0;
+  const skippedNote = plan.skipped.length
+    ? `\nLeft alone (not the console):\n  ${plan.skipped.map(describeSkipped).join('\n  ')}`
+    : '';
+
+  if (dryRun) {
+    const wouldKill = plan.targets.length
+      ? `Would kill:\n  ${plan.targets.map(describeTarget).join('\n  ')}`
+      : 'Would kill: nothing (no process attributable to the console).';
+    return {
+      stopped: false,
+      alreadyStopped: !wasRunning && !hadLock,
+      dryRun: true,
+      killed: [],
+      wouldKill: plan.targets,
+      skipped: plan.skipped,
+      cleared: [],
+      before,
+      after: before,
+      message: `Dev server stop — DRY RUN (nothing killed, discovery files untouched).\n${wouldKill}${skippedNote}`,
+    };
+  }
+
+  if (!wasRunning && !hadLock) {
+    return {
+      stopped: false,
+      alreadyStopped: true,
+      killed: [],
+      skipped: plan.skipped,
+      cleared: [],
+      before,
+      after: before,
+      message: `Dev server: already stopped.${skippedNote}`,
+    };
+  }
+
+  const killed = plan.targets.map((t) => ({ ...killProcessTree(t.pid), attribution: t.reasons }));
+
+  // Force-kill skips launcher exit handlers — clear discovery ourselves.
+  const cleared = clearDiscovery(root);
+
+  // Give OS sockets a beat to release before re-probe.
+  await new Promise((r) => setTimeout(r, 400));
+  const after = await getDevServerStatus({ vaultRoot: root });
+
+  // Success = no CONSOLE-identified server remains. Unrelated listeners on
+  // candidate ports are deliberately left standing (HS-W7E3), so the old
+  // `servers.length === 0` condition would false-fail every stop.
+  if (!after.running) {
+    if (after.lockfile?.present) clearDiscovery(root);
+    return {
+      stopped: true,
+      alreadyStopped: false,
+      killed,
+      skipped: plan.skipped,
+      cleared,
+      before,
+      after: await getDevServerStatus({ vaultRoot: root }),
+      message: wasRunning
+        ? `Dev server: stopped${killed.length ? ` (killed pid ${killed.map((k) => k.pid).join(', ')})` : ''}.${skippedNote}`
+        : `Dev server: cleared stale lock (nothing console-attributable was listening).${skippedNote}`,
+    };
+  }
+
+  return {
+    stopped: false,
+    alreadyStopped: false,
+    killed,
+    skipped: plan.skipped,
+    cleared,
+    before,
+    after,
+    message:
+      `Dev server: STOP FAILED — console still listening.\n` +
+      summarizeStatus(after) +
+      `\nTry: npm run console:status  then  node scripts/dev-server-stop.mjs --force-ports (sweeps ALL candidate-port listeners — check --dry-run first)`,
+  };
+}
+
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  const asJson = process.argv.includes('--json');
+  const dryRun = process.argv.includes('--dry-run');
+  const forcePorts = process.argv.includes('--force-ports');
+  stopDevServer({ dryRun, forcePorts })
+    .then((result) => {
+      if (asJson) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              stopped: result.stopped,
+              alreadyStopped: result.alreadyStopped,
+              ...(result.dryRun ? { dryRun: true, wouldKill: result.wouldKill } : {}),
+              killed: result.killed,
+              skipped: result.skipped,
+              cleared: result.cleared,
+              before: result.before,
+              after: result.after,
+              message: result.message,
+            },
+            null,
+            2,
+          ) + '\n',
+        );
+      } else {
+        process.stdout.write(result.message + '\n');
+      }
+      process.exit(result.stopped || result.alreadyStopped || result.dryRun ? 0 : 1);
+    })
+    .catch((err) => {
+      process.stderr.write(`Dev server stop failed: ${err?.message ?? err}\n`);
+      process.exit(1);
+    });
+}

package/scripts/heyspex-mode.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// heyspex-mode.mjs — the master on/off switch for the HeySpex agent layer.
+//
+// HeySpex layers a lot onto a plain Claude Code session: ~25 lifecycle hooks,
+// an MCP server, a statusline, and an always-loaded agent contract (CLAUDE.md).
+// That is the point when you are working the HeySpex protocol — and pure noise
+// when you just want to edit a file in this repo. This module is the single
+// place that answers "is HeySpex on right now?", and the code that flips it.
+//
+// Resolution order (first match wins):
+//   1. HEYSPEX_MODE env var — `off`/`0`/`disabled` or `on`/`1`/`enabled`.
+//      A per-shell escape hatch that never touches disk.
+//   2. .heyspex/mode.json  — the persisted machine-local choice (gitignored).
+//   3. Default: ON. Absent/unreadable/corrupt state means HeySpex works out of
+//      the box, and a broken state file can never silently disable the
+//      guardrails. Fail-open is deliberate.
+//
+// `isHeySpexOff()` runs on EVERY hook invocation, so it stays dependency-free
+// and does at most one small synchronous read.
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * The root the mode switch reads and writes. In the platform checkout that is REPO_ROOT (unchanged). When this file
+ * runs from an INSTALLED package (node_modules/heyspex/...) REPO_ROOT is the package, not the project the dev is
+ * working in: the switch used to write inside node_modules and the hook runner never saw it. So: the project
+ * (CLAUDE_PROJECT_DIR, else the nearest ancestor of cwd holding a state dir or .git, else cwd).
+ */
+export function resolveModeRoot(repoRoot = REPO_ROOT, env = process.env, cwd = process.cwd()) {
+  if (!repoRoot.split(path.sep).includes('node_modules')) return repoRoot;
+  const fromEnv = String(env.CLAUDE_PROJECT_DIR ?? '').trim();
+  if (fromEnv) return fromEnv;
+  let d = cwd;
+  for (;;) {
+    if (fs.existsSync(path.join(d, '.hey' + 'spex')) || fs.existsSync(path.join(d, '.git'))) return d;
+    const up = path.dirname(d);
+    if (up === d) return cwd;
+    d = up;
+  }
+}
+export const MODE_ROOT = resolveModeRoot();
+
+const STATE_REL = '.heyspex/mode.json';
+const BACKUP_DIR_REL = '.heyspex/mode-backup';
+const CLAUDE_MD_REL = 'CLAUDE.md';
+const CLAUDE_MD_OFF_REL = 'CLAUDE.heyspex-off.md';
+const LOCAL_SETTINGS_REL = '.claude/settings.local.json';
+
+const OFF_WORDS = new Set(['off', '0', 'false', 'disabled', 'disable', 'no']);
+const ON_WORDS = new Set(['on', '1', 'true', 'enabled', 'enable', 'yes']);
+
+/** Resolve a repo-relative path against the repo root. */
+function at(repoRoot, rel) {
+  return path.join(repoRoot, ...rel.split('/'));
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * The env override, if the user set one. Returns 'on' | 'off' | null.
+ * Exported so `hs mode status` can tell the user their env var is overriding
+ * the persisted state — otherwise "I turned it off but it's still on" is
+ * an unexplainable mystery.
+ */
+export function envOverride() {
+  const raw = String(process.env.HEYSPEX_MODE ?? '').trim().toLowerCase();
+  if (!raw) return null;
+  if (OFF_WORDS.has(raw)) return 'off';
+  if (ON_WORDS.has(raw)) return 'on';
+  return null;
+}
+
+/** The persisted state file, or null when absent/corrupt. */
+export function readState(repoRoot = REPO_ROOT) {
+  return readJson(at(repoRoot, STATE_REL));
+}
+
+/**
+ * THE hot-path question, called by every hook through `_run.mjs`.
+ * Fail-open: any surprise resolves to "HeySpex is on".
+ */
+export function isHeySpexOff(repoRoot = REPO_ROOT) {
+  try {
+    const override = envOverride();
+    if (override) return override === 'off';
+    return readState(repoRoot)?.mode === 'off';
+  } catch {
+    return false;
+  }
+}
+
+/** Current effective mode plus where it came from. */
+export function resolveMode(repoRoot = REPO_ROOT) {
+  const override = envOverride();
+  const state = readState(repoRoot);
+  const persisted = state?.mode === 'off' ? 'off' : 'on';
+  return {
+    mode: override ?? persisted,
+    source: override ? 'env:HEYSPEX_MODE' : state ? STATE_REL : 'default',
+    overriddenByEnv: Boolean(override) && override !== persisted,
+    persisted,
+    state,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Surface 1 — the MCP server
+//
+// `.claude/settings.local.json` is gitignored and machine-local, which makes it
+// exactly the right lever: turning HeySpex off must not dirty a tracked file
+// that a teammate would then see in `git status`. Claude Code reads this at
+// startup, so a restart is required either way.
+// ---------------------------------------------------------------------------
+
+function applyMcp(repoRoot, enabled) {
+  const file = at(repoRoot, LOCAL_SETTINGS_REL);
+  const settings = readJson(file) ?? {};
+  if (enabled) {
+    settings.enableAllProjectMcpServers = true;
+    const list = new Set(settings.enabledMcpjsonServers ?? []);
+    list.add('heyspex');
+    settings.enabledMcpjsonServers = [...list];
+    delete settings.disabledMcpjsonServers;
+  } else {
+    settings.enableAllProjectMcpServers = false;
+    settings.enabledMcpjsonServers = (settings.enabledMcpjsonServers ?? []).filter((s) => s !== 'heyspex');
+    const disabled = new Set(settings.disabledMcpjsonServers ?? []);
+    disabled.add('heyspex');
+    settings.disabledMcpjsonServers = [...disabled];
+  }
+  writeJson(file, settings);
+  return path.relative(repoRoot, file).replace(/\\/g, '/');
+}
+
+export function mcpEnabled(repoRoot = REPO_ROOT) {
+  const settings = readJson(at(repoRoot, LOCAL_SETTINGS_REL)) ?? {};
+  if ((settings.disabledMcpjsonServers ?? []).includes('heyspex')) return false;
+  if (settings.enableAllProjectMcpServers === true) return true;
+  return (settings.enabledMcpjsonServers ?? []).includes('heyspex');
+}
+
+// ---------------------------------------------------------------------------
+// Surface 2 — CLAUDE.md, the always-loaded agent contract
+//
+// This is the one tracked file the switch has to touch: as long as CLAUDE.md
+// carries the HeySpex contract, the agent keeps following HeySpex protocol even
+// with every hook silenced. So `off` swaps in a short stub and stashes the real
+// file under .heyspex/mode-backup/ with its sha256. `on` restores it and
+// verifies the hash, so a round-trip is provably byte-identical.
+//
+// If you edit CLAUDE.md while HeySpex is off, `on` refuses to clobber your work
+// and tells you where the backup is.
+// ---------------------------------------------------------------------------
+
+const CLAUDE_MD_STUB = `# Project Instructions for AI Agents
+
+**HeySpex is currently OFF for this checkout.**
+
+This repository normally runs the HeySpex agent protocol — a spec vault under
+\`specs/\`, an MCP server, lifecycle hooks, and a full agent contract in this
+file. All of that is disabled right now, so treat this as an ordinary codebase:
+read the code, make the change that was asked for, run the tests.
+
+Do **not** file specs, claim work, recall vault memories, or run HeySpex
+procedures while this notice is here — the tools backing them are turned off.
+
+To turn HeySpex back on:
+
+\`\`\`bash
+npm run heyspex:on      # or: node bin/hs.mjs mode on
+\`\`\`
+
+Then restart Claude Code. The real agent contract is restored from
+\`.heyspex/mode-backup/CLAUDE.md\`.
+`;
+
+function applyClaudeMd(repoRoot, enabled, state, force = false) {
+  const live = at(repoRoot, CLAUDE_MD_REL);
+  const backup = at(repoRoot, `${BACKUP_DIR_REL}/CLAUDE.md`);
+
+  if (!enabled) {
+    if (state?.claudeMd?.stubbed) return { action: 'already-stubbed' };
+    if (!fs.existsSync(live)) return { action: 'skipped', reason: 'no CLAUDE.md' };
+    const original = fs.readFileSync(live);
+    fs.mkdirSync(path.dirname(backup), { recursive: true });
+    fs.writeFileSync(backup, original);
+    // Ship the stub alongside the backup too, so `mode status` can tell a
+    // pristine stub from one the user has since edited.
+    fs.writeFileSync(live, CLAUDE_MD_STUB, 'utf8');
+    return {
+      action: 'stubbed',
+      originalSha256: sha256(original),
+      stubSha256: sha256(Buffer.from(CLAUDE_MD_STUB, 'utf8')),
+      backup: path.relative(repoRoot, backup).replace(/\\/g, '/'),
+    };
+  }
+
+  if (!state?.claudeMd?.stubbed) return { action: 'nothing-to-restore' };
+  if (!fs.existsSync(backup)) {
+    return { action: 'failed', reason: `backup missing at ${BACKUP_DIR_REL}/CLAUDE.md` };
+  }
+  // Refuse to silently discard edits made to the stub while HeySpex was off.
+  // `--force` is the way out: it says "I've read my edits, restore anyway".
+  if (fs.existsSync(live) && !force) {
+    const current = sha256(fs.readFileSync(live));
+    if (state.claudeMd.stubSha256 && current !== state.claudeMd.stubSha256) {
+      return {
+        action: 'failed',
+        reason:
+          `CLAUDE.md changed while HeySpex was off — refusing to overwrite it.\n` +
+          `      Your edits: CLAUDE.md · the real contract: ${BACKUP_DIR_REL}/CLAUDE.md\n` +
+          `      Salvage anything you want to keep, then rerun with --force to restore.`,
+      };
+    }
+  }
+  const restored = fs.readFileSync(backup);
+  fs.writeFileSync(live, restored);
+  const ok = !state.claudeMd.originalSha256 || sha256(restored) === state.claudeMd.originalSha256;
+  return { action: 'restored', verified: ok };
+}
+
+export function claudeMdStubbed(repoRoot = REPO_ROOT) {
+  return Boolean(readState(repoRoot)?.claudeMd?.stubbed);
+}
+
+// ---------------------------------------------------------------------------
+// The flip
+// ---------------------------------------------------------------------------
+
+/**
+ * Turn the whole HeySpex layer on or off.
+ *
+ * Hooks and the statusline need no file surgery — they read `isHeySpexOff()`
+ * themselves at fire time, via `scripts/claude-hooks/_run.mjs`. Only the MCP
+ * server and CLAUDE.md have to be physically changed, because Claude Code
+ * consumes both before any HeySpex code gets to run.
+ */
+export function setMode(target, { repoRoot = REPO_ROOT, force = false } = {}) {
+  if (target !== 'on' && target !== 'off') {
+    throw new Error(`setMode: expected 'on' or 'off', got '${target}'`);
+  }
+  const enabled = target === 'on';
+  const prior = readState(repoRoot);
+  const steps = [];
+
+  const claudeMd = applyClaudeMd(repoRoot, enabled, prior, force);
+  if (claudeMd.action === 'failed') {
+    return { ok: false, mode: prior?.mode ?? 'on', error: claudeMd.reason, steps };
+  }
+  steps.push({ surface: 'CLAUDE.md', ...claudeMd });
+
+  steps.push({ surface: 'MCP server', action: enabled ? 'enabled' : 'disabled', file: applyMcp(repoRoot, enabled) });
+  steps.push({ surface: 'hooks', action: enabled ? 'live' : 'silenced (all exit 0)' });
+  steps.push({ surface: 'statusline', action: enabled ? 'live' : 'blank' });
+
+  const next = {
+    mode: target,
+    changedAt: new Date().toISOString(),
+    claudeMd: enabled
+      ? { stubbed: false }
+      : claudeMd.action === 'stubbed'
+        ? { stubbed: true, originalSha256: claudeMd.originalSha256, stubSha256: claudeMd.stubSha256 }
+        : (prior?.claudeMd ?? { stubbed: false }),
+  };
+  writeJson(at(repoRoot, STATE_REL), next);
+
+  return { ok: true, mode: target, steps, restartRequired: true };
+}