heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/wip-checkpoint.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// Claude Code hook → WIP before/after safety net for implementation sessions.
+//
+// Hardens the two ends of the WIP handoff contract that were, until now, pure
+// agent discipline (session-close-protocol says record WIP *after*; the claim
+// contract says read WIP *before*) and — critically — covers the gap NEITHER
+// side covered: context-window rollover *mid*-implementation. The session-close
+// protocol is too heavy for a rollover (it flips status, writes HS-REV, treats
+// work as done) but work is still continuing. This hook injects the right
+// reminder at the right moment instead of relying on the agent remembering.
+//
+// Two events, one script (mirrors emit-claim-status.mjs's multi-event shape):
+//
+//   SessionStart (source: startup | resume)
+//     → the *before* side. Remind the agent to run heyspex_handoff_load + read
+//       the WIP ledger before claiming/continuing, and preview the most recent
+//       ledger entry so the resume context is non-empty.
+//
+//   SessionStart (source: compact)
+//     → the reliable *mid-flight* net. Claude Code re-runs SessionStart right
+//       AFTER an auto/manual compaction, so additionalContext here lands in the
+//       fresh post-compaction context — the one place a reminder is guaranteed
+//       to be seen. Framed as "rollover, not fresh start — work continues."
+//
+//   PreCompact
+//     → the *before-compaction* warning. Best-effort: fires just before context
+//       is compacted. Nudges a heyspex_record_wip + heyspex_handoff_record flush
+//       to the self-purging Neon lane while the full context is still present.
+//
+// IMPORTANT — what this hook does NOT do: a shell hook cannot call MCP tools, so
+// it cannot perform the flush/load itself. It injects the reminder (same model
+// as preflight-reminder.mjs). The agent still makes the tool calls.
+//
+// No CLAUDE_AGENT gate ([[HS-DT9L-NLR7-DIAG-nine-hooks-are-switched-off-in]]).
+// This used to exit early in interactive sessions, so the mid-session rollover net
+// never fired where a human is actually doing implementation work. Safe to run
+// everywhere: this hook only ever injects additionalContext, it can never deny
+// anything, so there is no approval-fatigue risk in removing the gate.
+//
+// Env gate:
+//   HEYSPEX_WIP_CHECKPOINT_OFF=1    hard kill switch — silent even when opted in.
+//
+// MUST exit 0 on every failure path — a hook that breaks Claude Code is worse
+// than a hook that silently does nothing.
+//
+// Output shape: { hookSpecificOutput: { hookEventName, additionalContext } }.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getActiveConfig } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+import { resolveConsoleUrl as resolveConsoleUrlShared } from '../lib/console-url-resolver.mjs';
+import { readCredentialsMcpToken, resolveDevMode } from '../lib/dev-mode.mjs';
+
+const NOTES_EXCERPT_MAX = 320;
+const REMAINING_ITEM_MAX = 200;
+const REMAINING_ITEMS_MAX = 3;
+const LEDGER_REL = ['.heyspex', 'wip-state.json'];
+const WIP_FETCH_TIMEOUT_MS = 1500;
+
+function repoRoot() {
+  // scripts/claude-hooks/ → up two levels.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+// Since the repo split (2026-08-31) the WIP ledger lives in the VAULT, not the
+// code checkout. Reading repoRoot() here previewed a frozen pre-split snapshot to
+// every new session — the HS-OR8H repo-split "quiet window OPEN" notice kept
+// re-appearing for days after the window closed, because the live ledger had moved
+// and this copy never advanced. Resolve the vault first; fall back to the code repo
+// so a pre-split or standalone checkout still previews its own ledger.
+function vaultRoot() {
+  try {
+    return getActiveConfig()?.repoRootAbs ?? null;
+  } catch {
+    return null; // registry unreadable — the code-repo base still applies
+  }
+}
+
+// Ledger roots in precedence order: vault first, code repo second.
+function ledgerRoots() {
+  const roots = [];
+  const vault = vaultRoot();
+  if (vault) roots.push(vault);
+  const repo = repoRoot();
+  if (!roots.includes(repo)) roots.push(repo);
+  return roots;
+}
+
+async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || ''), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+  });
+}
+
+function emit(eventName, additionalContext) {
+  if (!additionalContext) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: eventName, additionalContext },
+    }),
+  );
+}
+
+function truncate(value, limit) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  return trimmed.length > limit ? `${trimmed.slice(0, limit)}…` : trimmed;
+}
+
+// Read the file ledger and return the single most-recently-updated entry, or
+// null when the ledger is missing/empty/malformed. The file ledger runs
+// alongside the Neon handoff_context lane until the file→Neon cutover
+// (HS-EPIC-PFMN); reading the file keeps SessionStart robust when console/Neon
+// is offline.
+function mostRecentLedgerEntry() {
+  let parsed = null;
+  for (const root of ledgerRoots()) {
+    try {
+      const candidate = JSON.parse(fs.readFileSync(path.join(root, ...LEDGER_REL), 'utf8'));
+      if (candidate && typeof candidate === 'object') {
+        parsed = candidate;
+        break;
+      }
+    } catch {
+      // missing or unreadable at this root — try the next one
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  let best = null;
+  for (const [epicId, entry] of Object.entries(parsed)) {
+    if (!entry || typeof entry !== 'object') continue;
+    const updatedAt = typeof entry.updatedAt === 'string' ? entry.updatedAt : '';
+    if (!best || updatedAt > best.updatedAt) {
+      best = { epicId, updatedAt, entry };
+    }
+  }
+  return best;
+}
+
+function ledgerPreview(best, source = 'disk') {
+  if (!best) return '';
+  const { epicId, entry } = best;
+  const lines = [`Most recent WIP ledger entry — ${epicId} (updated ${best.updatedAt || 'unknown'}):`];
+  const notes = truncate(entry.notes, NOTES_EXCERPT_MAX);
+  if (notes) lines.push(`  notes: ${notes}`);
+  if (Array.isArray(entry.remaining) && entry.remaining.length) {
+    lines.push('  remaining:');
+    for (const item of entry.remaining.slice(0, REMAINING_ITEMS_MAX)) {
+      const text = truncate(item, REMAINING_ITEM_MAX);
+      if (text) lines.push(`    • ${text}`);
+    }
+  }
+  lines.push(
+    source === 'cloud'
+      ? '  (This is a cloud WIP preview from /api/wip — trust it over reconstructing state from scratch.)'
+      : '  (This is a disk preview — the vault file on disk is the source of truth; ' +
+          'do not reconstruct state by re-reading every child spec + git diff.)',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Cloud-reliance SessionStart preview: `GET {console}/api/wip` (bearer-gated)
+ * returns `{ wip_state: { "<SPEC-ID>": { sessionId, agent, updatedAt, notes,
+ * remaining, filesTouched, ... } } }` — the same shape `heyspex_record_wip`
+ * writes. Only consulted when `resolveDevMode()` reports cloud reliance; falls
+ * back to disk on ANY failure (unreachable console, bad token, malformed
+ * body) and never throws — this hook must stay fail-open and silent.
+ */
+async function fetchCloudLedgerEntry(root) {
+  let mode;
+  try {
+    mode = resolveDevMode({});
+  } catch {
+    return null;
+  }
+  if (mode.reliance !== 'cloud') return null;
+
+  let consoleUrl;
+  try {
+    consoleUrl = resolveConsoleUrlShared({
+      repoRoot: root,
+      devMode: { reliance: mode.reliance, consoleUrl: mode.consoleUrl },
+    });
+  } catch {
+    return null;
+  }
+
+  const token = readCredentialsMcpToken();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), WIP_FETCH_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    const res = await fetch(`${consoleUrl}/api/wip`, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const wipState = body?.wip_state;
+    if (!wipState || typeof wipState !== 'object') return null;
+    let best = null;
+    for (const [specId, entry] of Object.entries(wipState)) {
+      if (!entry || typeof entry !== 'object') continue;
+      const updatedAt = typeof entry.updatedAt === 'string' ? entry.updatedAt : '';
+      if (!best || updatedAt > best.updatedAt) {
+        best = { epicId: specId, updatedAt, entry };
+      }
+    }
+    return best;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const BEFORE_REMINDER =
+  'Session start. Before you claim or continue work, load the prior handoff: ' +
+  'call `heyspex_handoff_load({})` for your Neon lane context, and read the ' +
+  '`/hs-next` WIP block (file ledger at `.heyspex/wip-state.json`). Trust the ' +
+  'structured handoff over reconstructing state from scratch.';
+
+const COMPACT_REMINDER =
+  'Context was just compacted mid-session. This is a ROLLOVER, not a fresh ' +
+  'start — work is continuing. Re-orient before your next action: run ' +
+  '`heyspex_handoff_load({})` and re-read the WIP ledger below. Do NOT treat ' +
+  'this as session close — do not flip status or write an HS-REV; the work is ' +
+  'not done.';
+
+const PRECOMPACT_REMINDER =
+  '⚠️ Context is about to be compacted. CHECKPOINT NOW while the full context ' +
+  'is still present, if you are mid-implementation: (1) `heyspex_record_wip` ' +
+  'for the worked epic (filesTouched / untrackedArtifacts / specsFiled / ' +
+  'verified / remaining / notes), and (2) `heyspex_handoff_record` to the ' +
+  'self-purging Neon lane. This is a context-rollover CHECKPOINT, not session ' +
+  'close — do NOT flip status or write an HS-REV; work is continuing.';
+
+async function main() {
+  if (process.env.HEYSPEX_WIP_CHECKPOINT_OFF === '1') return;
+
+  const raw = await readStdinJson();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  const event = payload?.hook_event_name;
+  if (!event) return;
+
+  if (event === 'SessionStart') {
+    const source = payload?.source;
+    let best = await fetchCloudLedgerEntry(repoRoot());
+    let ledgerSource = 'cloud';
+    if (!best) {
+      best = mostRecentLedgerEntry();
+      ledgerSource = 'disk';
+    }
+    const preview = ledgerPreview(best, ledgerSource);
+    const head = source === 'compact' ? COMPACT_REMINDER : BEFORE_REMINDER;
+    emit(event, preview ? `${head}\n\n${preview}` : head);
+    return;
+  }
+
+  if (event === 'PreCompact') {
+    emit(event, PRECOMPACT_REMINDER);
+    return;
+  }
+}
+
+main().catch(() => {
+  // Never break Claude Code on a hook failure.
+});

package/scripts/cursor-hooks/manifest.mjs

@@ -0,0 +1,235 @@
+// manifest.mjs — the Cursor registration for every HeySpex lifecycle hook.
+//
+// SSOT for three consumers: install-cursor-hooks.mjs (writes `.cursor/hooks.json`),
+// heyspex-doctor.mjs (the `cursor-hooks` check), and _run.smoke.mjs (asserts the
+// manifest stays in parity with `.claude/settings.json`).
+//
+// HOW THE MAPPING WAS DERIVED
+//
+// Claude Code splits the tool lifecycle by PHASE (PreToolUse / PostToolUse) and
+// selects with a regex over tool names. Cursor splits by CHANNEL — shell, MCP,
+// file read, file edit, subagent each get their own event — and its `matcher`
+// only understands tool KINDS (`Write`, `Shell`, `Read`, `Grep`, `Delete`,
+// `Task`, `MCP:<name>`). So one Claude row can become a row on a different
+// event here, and a Claude matcher like `mcp__heyspex__heyspex_claim_spec` moves
+// into the shim's own `tool` filter.
+//
+// Two rules keep this honest:
+//   1. NO DOUBLE-FIRE. A hook is registered on exactly one channel per phase.
+//      Shell-facing gates go on `beforeShellExecution` (the only event that
+//      reliably carries the command text) and are therefore NOT also on
+//      `preToolUse`, whose registrations are scoped to `Write|Delete`.
+//   2. NO SILENT DOWNGRADE. A Claude hard gate maps to an event where Cursor
+//      honors a `permission` verdict, or it is listed in UNPORTABLE with the
+//      rule that covers it instead. A gate that can only "advise" in Cursor is
+//      not parity, and pretending otherwise is worse than a documented gap.
+//
+// `matcher` is Cursor-side (cheap, evaluated before the process spawns);
+// `tool` becomes `--hs-tool=<regex>` and is evaluated by the shim after it
+// parses the payload. Prefer `matcher`; use `tool` only for what it can't say.
+
+export const SHIM = 'scripts/cursor-hooks/_run.mjs';
+export const DEFAULT_TIMEOUT_SECONDS = 5;
+
+/**
+ * @typedef {object} HookEntry
+ * @property {string} event    Cursor hook event name (camelCase).
+ * @property {string} hook     Hook name resolved under scripts/claude-hooks/,
+ *                             or a repo-relative path for a hook that lives
+ *                             elsewhere.
+ * @property {string[]} [args] Extra args forwarded to the hook verbatim.
+ * @property {string} [matcher] Cursor-side matcher.
+ * @property {string} [tool]   Shim-side tool-name regex (`--hs-tool=`).
+ * @property {number} [timeout] Seconds; defaults to DEFAULT_TIMEOUT_SECONDS.
+ * @property {string} [claudeEvent] Override the Claude event name the hook is
+ *                             told it is running under, when the Cursor event
+ *                             maps ambiguously.
+ * @property {string} why      One line: what this registration buys.
+ */
+
+/** @type {HookEntry[]} */
+export const HOOKS = [
+  // ── Session start ───────────────────────────────────────────────────────
+  // Cursor's sessionStart honors `additional_context`, so these injections
+  // land in context exactly as they do in Claude Code.
+  { event: 'sessionStart', hook: 'wip-checkpoint', why: 'Surface the previous session WIP handoff before work resumes.' },
+  { event: 'sessionStart', hook: 'inject-dev-server-awareness', why: 'Once-per-session reminder that dev-server status is a tool call, not a guess.' },
+  { event: 'sessionStart', hook: 'inject-coo-seat', why: 'Inject the dev-factory COO seat mandate when the COO window is open.' },
+  { event: 'sessionStart', hook: 'coo-guard-check', why: 'Warn at session start when a breakdown has not been delegated.' },
+  { event: 'sessionStart', hook: 'check-auto-memory-budget', why: 'Self-heal and budget-check the auto-memory index.' },
+  { event: 'sessionStart', hook: 'check-claude-md-budget', why: 'Advisory budget check on the always-loaded agent contract.' },
+  { event: 'sessionStart', hook: 'check-mcp-freshness-hook', why: 'Warn when the running MCP server is stale versus vendor.' },
+
+  // ── Compaction ──────────────────────────────────────────────────────────
+  // Claude re-runs SessionStart(source: compact) after compaction; Cursor fires
+  // preCompact BEFORE it, so the shim relays this one as SessionStart(compact)
+  // to keep wip-checkpoint's "rollover, not fresh start" framing.
+  { event: 'preCompact', hook: 'wip-checkpoint', claudeEvent: 'SessionStart', why: 'Carry the WIP handoff across a context compaction.' },
+
+  // ── Every user turn ─────────────────────────────────────────────────────
+  // beforeSubmitPrompt is Cursor's UserPromptSubmit. It honors `user_message`
+  // but not `additional_context`, so these three surface in the transcript
+  // rather than as invisible context — the routing still reaches the agent,
+  // and the user can see why it fired.
+  { event: 'beforeSubmitPrompt', hook: 'preflight-reminder', why: 'Name the required procedure before a filing/destructive/protocol turn.' },
+  { event: 'beforeSubmitPrompt', hook: 'intent-classifier-trigger', why: 'Route capture / research / settings / defer intents to the right skill.' },
+  { event: 'beforeSubmitPrompt', hook: 'inject-communication-style', why: 'Re-assert the plain-language communication rules each turn.' },
+
+  // ── Before every tool call (any tool) ───────────────────────────────────
+  { event: 'preToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PreToolUse'], why: 'Claim liveness heartbeat to the console.' },
+  { event: 'preToolUse', matcher: '.*', hook: 'coo-denylist-gate', why: 'Hard deny the COO-window deny list.' },
+  { event: 'preToolUse', matcher: '.*', hook: 'log-session-activity', args: ['--event=PreToolUse'], why: 'Append agent.tool_called rows to the session log.' },
+
+  // ── Before a file write / delete ─────────────────────────────────────────
+  // Cursor's `Write` covers create AND patch (Claude's Write|Edit|MultiEdit);
+  // the shim re-derives which one from the input shape. `Delete` is included on
+  // the vault guard because removing a profile file is the loss it exists to
+  // prevent, and Claude had no separate delete tool to list.
+  { event: 'preToolUse', matcher: 'Write|Delete', hook: 'env-vault-guard', why: 'Block destructive writes to the encrypted env vault (ALWAYS ON).' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'settings-write-gate', why: 'Require approval before .heyspex/config.yaml changes.' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'enforce-vault-naming', why: 'Block vault filenames that violate the naming registry.' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'guard-auto-memory-writes', why: 'Block new topic files in the auto-memory directory.' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'preflight-reminder', why: 'Preflight reminder on the edit path itself.' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'claim-before-code-gate', why: 'Deny the first code edit after plan exit with no claim.' },
+
+  // ── Before a shell command ──────────────────────────────────────────────
+  // beforeShellExecution, not preToolUse/Shell: it is the only event guaranteed
+  // to carry the command string, and Cursor honors allow/deny/ask on it.
+  { event: 'beforeShellExecution', hook: 'env-vault-guard', why: 'Block shell writes/exfiltration targeting the env vault (ALWAYS ON).' },
+  { event: 'beforeShellExecution', hook: 'settings-write-gate', why: 'Catch shell writes to .heyspex/config.yaml.' },
+  { event: 'beforeShellExecution', hook: 'enforce-vault-naming', why: 'Catch vault files created via the shell.' },
+  { event: 'beforeShellExecution', hook: 'guard-auto-memory-writes', why: 'Catch auto-memory topic files created via the shell.' },
+  { event: 'beforeShellExecution', hook: 'preflight-reminder', why: 'Preflight reminder on rm -rf / force-push shaped commands.' },
+  { event: 'beforeShellExecution', hook: 'dev-server-task-reminder', timeout: 10, why: 'Dev-server start/stop hard gate plus DB-safety reminder.' },
+  { event: 'beforeShellExecution', hook: 'git-stash-gate', timeout: 10, why: 'Always ask before a mutating git stash.' },
+
+  // ── Before specific MCP tools ───────────────────────────────────────────
+  // Cursor fires preToolUse for MCP tools too (matcher `MCP:<name>`), so these
+  // stay on preToolUse rather than beforeMCPExecution — registering both would
+  // fire each gate twice. Scoping is the shim's `tool` regex because a Cursor
+  // matcher cannot name one MCP tool per entry portably.
+  { event: 'preToolUse', matcher: '.*', tool: 'heyspex_claim_spec$', hook: 'coo-guard-check', why: 'Block a claim whose breakdown was never delegated.' },
+  { event: 'preToolUse', matcher: '.*', tool: 'heyspex_file_spec$', hook: 'capture-workflow-gate', timeout: 8, why: 'Deny filing an implementation spec straight out of an open capture.' },
+  { event: 'preToolUse', matcher: '.*', tool: 'heyspex_settings_set$', hook: 'settings-write-gate', why: 'Require approval for settings changes made through MCP.' },
+  { event: 'preToolUse', matcher: '.*', tool: '[Nn]eon__(prepare_database_migration|complete_database_migration|reset_from_parent|delete_branch)$', hook: 'dev-server-task-reminder', timeout: 10, why: 'DB-safety gate on Neon migration/reset/delete tools.' },
+  { event: 'preToolUse', matcher: '.*', tool: '^(Workflow|Skill)$', hook: 'deep-research-cost-gate', why: 'Cost confirmation before a paid deep-research harness launch.' },
+  { event: 'preToolUse', matcher: '.*', tool: '^(WebSearch|WebFetch|web_search|web_fetch)$|heyspex_save_research$', hook: 'research-protocol-gate', why: 'WebSearch/WebFetch/save_research refused until the research preflight ran (HS-K0ZP, HS-EN4F).' },
+
+  // ── Before a subagent spawn ─────────────────────────────────────────────
+  // subagentStart over preToolUse/Task: it carries subagent_type and the model,
+  // which is exactly what the routing gate decides on, and it can deny.
+  { event: 'subagentStart', hook: 'agent-spawn-delegation-gate', why: 'Block a build/breakdown/critic subagent on an off-routing model.' },
+
+  // ── After every tool call ───────────────────────────────────────────────
+  { event: 'postToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PostToolUse'], why: 'Claim liveness heartbeat after the call resolves.' },
+  { event: 'postToolUse', matcher: '.*', hook: 'log-session-activity', args: ['--event=PostToolUse'], why: 'Append the tool result row to the session log.' },
+  { event: 'postToolUse', matcher: '.*', hook: 'close-terminal-on-ship', why: 'Close the Launch terminal once the spec ships.' },
+  { event: 'postToolUse', matcher: 'Write', hook: 'notify-status-flip', why: 'Sound on an in_review status flip.' },
+  { event: 'postToolUse', matcher: 'Write', hook: 'scripts/stamp-provenance-on-edit.mjs', why: 'Stamp assisted_by provenance on direct spec edits.' },
+
+  // afterFileEdit is a distinct signal, not a duplicate: it reports the edit
+  // that actually landed (with old/new strings) even when the write came from a
+  // path postToolUse did not describe as an edit.
+  { event: 'afterFileEdit', matcher: '.*', hook: 'close-terminal-on-ship', why: 'Ship detection from the concrete file edit.' },
+
+  // ── End of the agent turn ───────────────────────────────────────────────
+  // Cursor's `stop` honors `followup_message`, which is how a blocking Stop
+  // hook re-drives the agent — the same effect as Claude's exit-2 block.
+  { event: 'stop', hook: 'emit-claim-status', args: ['--event=Stop'], why: 'Mark the claim pending-on-response.' },
+  { event: 'stop', hook: 'naughty-list-gate', why: 'Re-drive the turn when the final message uses banned jargon.' },
+  { event: 'stop', hook: 'enforce-session-sequence', why: 'Re-drive the turn when work shipped without record_wip.' },
+
+  // ── Session end ─────────────────────────────────────────────────────────
+  { event: 'sessionEnd', hook: 'session-end', why: 'Release the claim and notify the console.' },
+  { event: 'sessionEnd', hook: 'close-terminal-on-ship', why: 'Final terminal cleanup.' },
+];
+
+/**
+ * Claude registrations with no Cursor trigger. Kept in code, not in a comment,
+ * so the doctor can report the gap and the smoke test can assert the list has
+ * not quietly grown.
+ */
+export const UNPORTABLE = [
+  {
+    hook: 'plan-review-gate',
+    claudeEvent: 'PreToolUse/ExitPlanMode',
+    reason: 'Cursor exposes no ExitPlanMode tool call to hooks.',
+    coveredBy: '.cursor/rules/plan-review-required.mdc (always-on rule)',
+  },
+  {
+    hook: 'plan-exit-ingest-gate',
+    claudeEvent: 'PreToolUse/ExitPlanMode',
+    reason: 'Same missing trigger; it is also what arms claim-before-code-gate.',
+    coveredBy: '.cursor/rules/plan-review-required.mdc + spec-creation-linkage.mdc',
+  },
+];
+
+/**
+ * The command string Cursor runs for one entry.
+ *
+ * The tool filter is a REGEX, and its metacharacters are also shell
+ * metacharacters — `[Nn]eon__(a|b)$` unquoted is a syntax error in bash, not a
+ * pattern. It is therefore always double-quoted. A trailing `$` inside double
+ * quotes is literal in both bash and PowerShell, and the patterns contain no
+ * whitespace, so quoting is sufficient without any escaping.
+ */
+export function commandFor(entry) {
+  const parts = ['node', SHIM, entry.hook];
+  if (entry.tool) parts.push(`--hs-tool="${entry.tool}"`);
+  if (entry.claudeEvent) parts.push(`--hs-claude-event=${entry.claudeEvent}`);
+  for (const arg of entry.args ?? []) parts.push(arg);
+  return parts.join(' ');
+}
+
+/**
+ * Same command, addressed from a PLUGIN install.
+ *
+ * A project hook runs with the repo as its working directory, so a relative
+ * path resolves. A plugin hook runs from the plugin's own cache directory,
+ * where `scripts/cursor-hooks/_run.mjs` does not exist — the shim and the hook
+ * bodies live in the host vault checkout. `$CURSOR_PROJECT_DIR` is how the
+ * plugin reaches back into it (the same reason the plugin's MCP entry goes
+ * through bin/launch-mcp.mjs instead of naming cli.mjs directly).
+ */
+export function commandForPlugin(entry) {
+  return commandFor(entry).replace(`node ${SHIM}`, `node "$CURSOR_PROJECT_DIR/${SHIM}"`);
+}
+
+/**
+ * The committed launcher a CUSTOMER repo carries for Cursor, repo-relative.
+ * Written by `hs install` / `scripts/install-cursor-hooks.mjs` from
+ * `renderCustomerLauncher('cursor')` in scripts/lib/customer-kit.mjs; it finds
+ * the `heyspex` package (node_modules/heyspex) and hands off to this shim.
+ */
+export const CUSTOMER_LAUNCHER = '.cursor/heyspex/run-hook.mjs';
+
+/**
+ * Same command, addressed from a CUSTOMER repo: the committed launcher by
+ * `$CURSOR_PROJECT_DIR` — never this machine's path. A customer repo has no
+ * `scripts/cursor-hooks/` of its own, so the relative form failed there with
+ * MODULE_NOT_FOUND ([[HS-EN4F-F4V2-DIAG-a-repo-set-up-with-hs-install-gets-no]]);
+ * the 2026-10-02 fix wrote the platform checkout's ABSOLUTE path, which the
+ * customer committed and which existed on no other machine
+ * ([[HS-0AF8-WW9R-TASK-portable-hook-and-command-paths-in]]).
+ */
+export function commandForCustomer(entry) {
+  return commandFor(entry).replace(`node ${SHIM}`, `node "$CURSOR_PROJECT_DIR/${CUSTOMER_LAUNCHER}"`);
+}
+
+/** Identity of an entry inside `.cursor/hooks.json` — what "already installed"
+ *  means, and what a repair replaces. Two entries for the same hook on the same
+ *  event are distinguished by their scoping, so the tool filter is part of it. */
+export function identityFor(entry) {
+  return `${entry.hook}::${entry.tool ?? ''}::${(entry.args ?? []).join(' ')}`;
+}
+
+export function timeoutFor(entry) {
+  return entry.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+}
+
+/** Every Cursor event this manifest registers, in a stable order. */
+export function events() {
+  const seen = [];
+  for (const entry of HOOKS) if (!seen.includes(entry.event)) seen.push(entry.event);
+  return seen;
+}

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(),
   };