heyspex 0.2.5 → 0.2.6

package/scripts/lib/capture-execution-guard.mjs

@@ -0,0 +1,221 @@
+// scripts/lib/capture-execution-guard.mjs
+//
+// [[HS-KNJ8-BQZC-DIAG-an-agent-session-executed-past-capture]] — the deterministic
+// "do not execute past an ungrounded capture" guard. Pure decision + tiny fs helpers.
+// Consumed by:
+//   - scripts/claude-hooks/capture-execution-gate.mjs   (PreToolUse, refuses)
+//   - scripts/lib/capture-verbatim-append.mjs           (UserPromptSubmit, writes the state)
+//   - scripts/record-grounding.mjs                      (/hs-ground helper, writes the record)
+//
+// WHERE THE GATE LEARNS CAPTURE STATE (cheap + offline): ONE local file,
+// `.heyspex/capture-gate-state.json` under the project root:
+//   { capture_id, session_id, expanded, written_at }
+// It is written ONLY by the UserPromptSubmit stage after a LIVE resolve of the on-deck
+// capture (console/Neon is the system of record; the offline capture-focus.yaml rots —
+// HS-O4U6 — so the gate never trusts it) and by record-grounding.mjs. The PreToolUse gate
+// reads nothing but that file and `.heyspex/research-grounding.json`: no network, no
+// MCP, no capture-focus.mjs import (a Bash-time hook must stay fast).
+//
+// FAIL OPEN whenever state is unknowable: no hook session id, no state file, unreadable or
+// malformed JSON, a state written by ANOTHER session, a state older than STATE_MAX_AGE_MS,
+// a state with no capture_id (the prompt stage writes capture_id:null when it verified
+// nothing is on deck for this session). Only a fresh, this-session, named, not-yet-cleared
+// capture can ever refuse anything.
+//
+// Self-clearing: while a state exists the prompt stage re-verifies it on EVERY substantive
+// prompt, so a promoted/closed capture stops gating at the next message; STATE_MAX_AGE_MS
+// bounds the worst case when no prompt arrives.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  GROUNDING_ARTIFACT_REL,
+  GROUNDING_FIELDS,
+  defaultReadGroundingArtifact,
+} from '../../spexharness/src/gates/deep-research-cost-gate.mjs';
+
+export const STATE_REL = path.join('.heyspex', 'capture-gate-state.json');
+export const STATE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+/** Owner/env kill switch for the gate; the config twin is agent_behaviors.capture_execution_gate.enabled. */
+export const GATE_OFF_ENV = 'HEYSPEX_CAPTURE_EXECUTION_GATE_OFF';
+export const GATE_CONFIG_KEY = 'agent_behaviors.capture_execution_gate.enabled';
+
+// ── state file ─────────────────────────────────────────────────────────────
+
+export function readGateState(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, STATE_REL), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeGateState(root, state) {
+  try {
+    const full = path.join(root, STATE_REL);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(
+      full,
+      JSON.stringify({ ...state, written_at: new Date().toISOString() }, null, 2) + '\n',
+      'utf8',
+    );
+    return true;
+  } catch {
+    return false; // best effort — a failed write only means the gate fails open
+  }
+}
+
+/** Does this capture body carry an agent expansion? (same two shapes capture-focus.mjs reads) */
+export function bodyHasExpansion(body) {
+  const text = String(body ?? '').replace(/\r\n/g, '\n');
+  if (/##[ \t]*Expanded[ \t]+Concept[ \t]*\n\s*\S/i.test(text)) return true;
+  return /<details>\s*\n<summary>\s*(?:Details|Expanded idea \(agent\))[^<\n]*<\/summary>\s*\n+\s*\S/i.test(text);
+}
+
+// ── grounding record ───────────────────────────────────────────────────────
+
+/** Is `artifact` a complete grounding record for `captureId`? Same predicate as deep-research-cost-gate's groundingBlock. */
+export function isGroundedFor(artifact, captureId) {
+  return Boolean(
+    artifact &&
+      typeof artifact === 'object' &&
+      captureId &&
+      artifact.source_idea_id === captureId &&
+      GROUNDING_FIELDS.every((k) => typeof artifact[k] === 'string' && artifact[k].trim()),
+  );
+}
+
+/**
+ * The /hs-ground helper's write: `.heyspex/research-grounding.json` in the EXACT shape
+ * deep-research-cost-gate reads, keyed to the capture, plus marks the gate state expanded
+ * (recording the grounding IS the expansion step of the Ground=Expand flow).
+ */
+export function recordGrounding(root, { source_idea_id, already_built, already_decided, owner_reference, residual_delta }, { sessionId } = {}) {
+  const record = { source_idea_id, already_built, already_decided, owner_reference, residual_delta };
+  const missing = ['source_idea_id', ...GROUNDING_FIELDS].filter((k) => typeof record[k] !== 'string' || !record[k].trim());
+  if (missing.length) return { ok: false, error: `missing or empty: ${missing.join(', ')}` };
+  const full = path.join(root, GROUNDING_ARTIFACT_REL);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, JSON.stringify({ ...record, recorded_at: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+  const prior = readGateState(root);
+  if (prior?.capture_id === source_idea_id) {
+    writeGateState(root, { ...prior, session_id: sessionId ?? prior.session_id, expanded: true });
+  }
+  return { ok: true, path: full };
+}
+
+// ── surface classification ─────────────────────────────────────────────────
+
+const PAID_SCRIPTS = ['firecrawl-cli', 'spexcrawl-cli', 'synthesize-cli', 'audit-via-deepseek', 'deepseek-build'];
+const SCRIPT_RE = new RegExp(`(^|[\\s/\\\\"'=])(?:${PAID_SCRIPTS.join('|')})(?:\\.mjs|\\.js|\\.ts)?(?=$|[\\s"';|&)])`, 'i');
+// :3002 on loopback OR any dotted-quad host (the owner's Firecrawl runs on the LAN, e.g. 192.168.1.252:3002).
+const FIRECRAWL_URL_RE = /(?:127\.0\.0\.1|localhost|\d{1,3}(?:\.\d{1,3}){3}):3002|api\.firecrawl\.dev/i;
+// A segment whose FIRST word is one of these only reads/inspects; never refused.
+const READ_ONLY_HEAD = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'grep', 'rg', 'egrep', 'fgrep', 'ls', 'dir', 'find', 'wc', 'type', 'echo',
+  'git', 'sed', 'awk', 'stat', 'file', 'diff', 'tree', 'pwd', 'cd', 'which', 'where', 'get-content', 'select-string',
+  'get-childitem', 'test-path', 'printf', 'sort', 'cut', 'jq',
+]);
+// Offline verification of the tools themselves — tests, self-tests, help.
+const OFFLINE_FLAG_RE = /(?:^|\s)(?:--test|--self-test|--help|-h)(?=\s|$)|\.(?:test|smoke)\.m?js\b/i;
+
+function splitSegments(command) {
+  return String(command).split(/&&|\|\||;|\||\r?\n/).map((s) => s.trim()).filter(Boolean);
+}
+
+function headWord(segment) {
+  // skip leading env assignments (FOO=1 node ...) and a leading "cd x" is its own segment already
+  const words = segment.split(/\s+/);
+  let i = 0;
+  while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++;
+  return (words[i] ?? '').replace(/^["']|["']$/g, '').toLowerCase();
+}
+
+/** Which gated Bash surface (if any) does this command invoke? */
+export function classifyBash(command) {
+  if (typeof command !== 'string' || !command.trim()) return null;
+  for (const seg of splitSegments(command)) {
+    if (READ_ONLY_HEAD.has(headWord(seg))) continue;
+    if (OFFLINE_FLAG_RE.test(seg)) continue;
+    if (FIRECRAWL_URL_RE.test(seg)) return { surface: 'firecrawl-api', detail: seg.slice(0, 120) };
+    if (SCRIPT_RE.test(seg)) {
+      const name = PAID_SCRIPTS.find((s) => seg.toLowerCase().includes(s));
+      return { surface: name ?? 'paid-research-script', detail: seg.slice(0, 120) };
+    }
+  }
+  return null;
+}
+
+// An Agent/Task prompt that tells a sub-agent to CHANGE research routing / the model catalog / a protocol.
+const ROUTING_TARGET_RE =
+  /routing[\s_-]*table|model[\s_-]*catalog|dev-factory-delegation-routing|research[\s_-]*(?:routing|seat)|routing[\s_-]*(?:pins?|rules?|seats?|defaults?)|seats\.json|specs[\\/]protocols[\\/]|protocol (?:file|edit)|edit(?:ing)? (?:the )?protocol|(?:default|always)[^.\n]{0,60}\b(?:research|synthesis)\b/i;
+const EDIT_VERB_RE =
+  /\b(?:edit|modify|change|update|rewrite|patch|set|make sure|ensure|always use|add|fix|implement|wire|configure|pin|route)\b/i;
+
+export function classifyAgent(input) {
+  const text = `${typeof input?.prompt === 'string' ? input.prompt : ''}\n${typeof input?.description === 'string' ? input.description : ''}`;
+  if (!text.trim()) return null;
+  if (ROUTING_TARGET_RE.test(text) && EDIT_VERB_RE.test(text)) {
+    return { surface: 'routing-edit-agent', detail: text.trim().slice(0, 120) };
+  }
+  return null;
+}
+
+export function classifySurface(toolName, toolInput) {
+  const name = String(toolName ?? '').trim();
+  if (name === 'Bash' || name === 'PowerShell') return classifyBash(toolInput?.command);
+  if (name === 'Agent' || name === 'Task') return classifyAgent(toolInput);
+  return null;
+}
+
+// ── decision ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ toolName?: string, toolInput?: object, sessionId?: string }} evt
+ * @param {{ root: string, env?: object, now?: number, readState?: Function, readGrounding?: Function, configEnabled?: boolean }} ctx
+ * @returns {{ decision: 'allow'|'deny', reason?: string }}
+ */
+export function decideCaptureExecution(evt, ctx) {
+  const env = ctx.env ?? process.env;
+  if (String(env[GATE_OFF_ENV] ?? '') === '1' || ctx.configEnabled === false) return { decision: 'allow' };
+  const hit = classifySurface(evt?.toolName, evt?.toolInput);
+  if (!hit) return { decision: 'allow' };
+  const sessionId = typeof evt?.sessionId === 'string' ? evt.sessionId.trim() : '';
+  if (!sessionId) return { decision: 'allow' }; // cannot prove it is THIS session's capture
+
+  const state = (ctx.readState ?? readGateState)(ctx.root);
+  const now = ctx.now ?? Date.now();
+  const writtenAt = Date.parse(state?.written_at ?? '');
+  if (
+    !state ||
+    !state.capture_id ||
+    state.session_id !== sessionId ||
+    !Number.isFinite(writtenAt) ||
+    now - writtenAt > STATE_MAX_AGE_MS
+  ) {
+    return { decision: 'allow' };
+  }
+
+  const grounded = isGroundedFor((ctx.readGrounding ?? defaultReadGroundingArtifact)(ctx.root), state.capture_id);
+  const expanded = state.expanded === true;
+  if (expanded && grounded) return { decision: 'allow' };
+
+  const why = [!expanded && 'it is still unexpanded', !grounded && `no grounding record for ${state.capture_id} exists`]
+    .filter(Boolean)
+    .join(' and ');
+  return {
+    decision: 'deny',
+    reason:
+      `Execution blocked (${hit.surface}): capture ${state.capture_id} is on deck for this session but ${why}. ` +
+      `Capture, ground and expand FIRST, then execute: (1) the owner's words must be in the capture verbatim; ` +
+      `(2) run /hs-ground on it (route-1 plans, route-2 code, route-3 the owner's own working reference); ` +
+      `(3) record the result with  node scripts/record-grounding.mjs --capture ${state.capture_id} --built "..." --decided "..." --reference "..." --delta "..."  ` +
+      `(writes ${GROUNDING_ARTIFACT_REL} and marks the capture expanded); (4) retry this exact call. ` +
+      `If the owner said to discard the capture or to just do it, promote/close the capture first. ` +
+      `Read-only tools, capture writes, /hs-ground, git and test runs are never gated. ` +
+      `Only the owner can lift this gate wholesale: set ${GATE_OFF_ENV}=1 in their own environment ` +
+      `(or agent_behaviors.capture_execution_gate.enabled: false).`,
+  };
+}

package/scripts/lib/customer-kit.mjs

@@ -1326,6 +1326,54 @@ export function auditCustomerKit({ targetRoot, platformRoot, deps = fsDeps }) {
   return report;
 }
 
+// ---------------------------------------------------------------------------
+// Which repo `hs setup <agent>` writes into
+// ---------------------------------------------------------------------------
+
+/**
+ * The project root a setup verb acts on: the nearest directory at/above
+ * `start` holding `.git` or `heyspex.yaml`, else `start` itself. Same walk
+ * `hs setup copilot` uses.
+ * @param {string} start
+ */
+export function findProjectRoot(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'heyspex.yaml'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(start);
+    dir = up;
+  }
+}
+
+/**
+ * True when `platformRoot` is an installed `heyspex` package (under a
+ * node_modules/ folder, or missing the source-checkout-only
+ * scripts/heyspex-doctor.mjs) rather than a HeySpex source checkout.
+ * @param {string} platformRoot
+ * @param {(p: string) => boolean} [exists]
+ */
+export function isInstalledPackageRoot(platformRoot, exists = fs.existsSync) {
+  if (toPosixPath(path.resolve(platformRoot)).includes('/node_modules/')) return true;
+  return !exists(path.join(platformRoot, 'scripts', 'heyspex-doctor.mjs'));
+}
+
+/**
+ * The repo a hook installer (`install-claude-code-hooks.mjs`,
+ * `install-cursor-hooks.mjs`) writes into. An explicit HS_SETUP_TARGET (what
+ * `hs setup` / `hs doctor --fix` pass) wins; with none, a source checkout
+ * targets itself (the dev `npm install` / `npm run hooks:*` path) but an
+ * INSTALLED package targets the customer's project found from cwd -- never
+ * its own package folder under node_modules/.
+ * @param {{ platformRoot: string, env?: Record<string, string | undefined>, cwd?: string, exists?: (p: string) => boolean }} opts
+ */
+export function resolveSetupTarget({ platformRoot, env = process.env, cwd = process.cwd(), exists = fs.existsSync }) {
+  const explicit = env.HS_SETUP_TARGET?.trim();
+  if (explicit) return path.resolve(explicit);
+  if (isInstalledPackageRoot(platformRoot, exists)) return findProjectRoot(cwd);
+  return path.resolve(platformRoot);
+}
+
 // ---------------------------------------------------------------------------
 // CLI: regenerate plugins/heyspex/hooks/hooks.json
 // ---------------------------------------------------------------------------

package/scripts/lib/hs-companion-settings.mjs

@@ -105,6 +105,31 @@ export const COMPANION_ALIASES = {
 
 export const HOST_COMMANDS = ["start", "stop", "status", "build"];
 
+/**
+ * What `hs companion start|stop|status|build` prints when run from an
+ * installed `heyspex` npm package: the tray app's source (companion/) is not
+ * in the tarball, so there is no start.ps1 to run. Says plainly that the
+ * Companion is not distributed through npm yet (a Windows installer is
+ * planned, research HS-AUY9) and what degrades without it, with the
+ * workaround for each. The dev (repo checkout) path never reaches this.
+ * @param {string} sub the host subcommand the caller asked for
+ */
+export function renderCompanionNotDistributed(sub) {
+  return [
+    `hs companion ${sub}: the HeySpex Companion (desktop tray app) is not distributed through the`,
+    "heyspex npm package yet; a Windows installer is planned (research HS-AUY9).",
+    "",
+    "Everything else in this package works without it. What you lose until then:",
+    "  - Automatic vault mirror (cloud <-> disk sync): run `npx hs pull --apply` to bring",
+    "    cloud-written specs down (and `npx hs push --apply` to send local edits up).",
+    "  - SpexVoice (voice capture and spoken commands): not available.",
+    "  - SpexCrawl research gather (/hs-res): its gather jobs need the Companion, so they",
+    "    report SPEXCRAWL_UNAVAILABLE.",
+    "",
+    "`hs companion settings ...` (console-backed) still works.",
+  ].join("\n");
+}
+
 const TRUE_WORDS = new Set(["true", "on", "yes", "1", "enabled"]);
 const FALSE_WORDS = new Set(["false", "off", "no", "0", "disabled"]);
 const NULL_WORDS = new Set(["null", "none"]);

package/scripts/record-grounding.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// /hs-ground helper: record the grounding result so the execution gate and the deep-research
+// gate can see it. [[HS-KNJ8-BQZC-DIAG-an-agent-session-executed-past-capture]]
+//
+//   node scripts/record-grounding.mjs --capture HS-CAP-XXXX --built "..." --decided "..." \
+//        --reference "..." --delta "..." [--root <project root>] [--session <id>]
+//
+// Writes .heyspex/research-grounding.json as
+//   { source_idea_id, already_built, already_decided, owner_reference, residual_delta, recorded_at }
+// (the shape deep-research-cost-gate.mjs already reads) and marks the capture expanded in
+// .heyspex/capture-gate-state.json. Never calls a model or the network.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { recordGrounding } from './lib/capture-execution-guard.mjs';
+
+export function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) out[a.slice(2)] = argv[++i];
+  }
+  return out;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const a = parseArgs(process.argv.slice(2));
+  const root = a.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const res = recordGrounding(
+    root,
+    { source_idea_id: a.capture, already_built: a.built, already_decided: a.decided, owner_reference: a.reference, residual_delta: a.delta },
+    { sessionId: a.session || process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID },
+  );
+  if (!res.ok) {
+    process.stderr.write(`record-grounding: ${res.error}\nusage: --capture <id> --built --decided --reference --delta (all required)\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`grounding recorded: ${res.path}\n`);
+}

package/vendor/heyspex-mcp/http-transport.mjs

@@ -111,7 +111,7 @@ export function toolNotAvailableRemotelyError(id, name) {
  * @property {(name: string) => boolean} [isKnownTool]
  *   Whether a name exists in the FULL catalog — distinguishes "needs the local
  *   server" from "no such tool" (default: same as `isToolAllowed`).
- * @property {{ name: string, version: string }} serverInfo
+ * @property {{ name: string, version: string, title?: string, icons?: ReadonlyArray<{ src: string, mimeType?: string, sizes?: ReadonlyArray<string> }> }} serverInfo
  * @property {string} [instructions]
  * @property {string} vaultRoot
  *   Passed through to `dispatch`. For the remote endpoint this is a path that

package/vendor/heyspex-mcp/test-helpers.mjs

@@ -3,9 +3,9 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
 import { resetActiveConfigCache } from './vault-resolve.mjs';
 
@@ -134,35 +134,49 @@ export function installScopedConsoleEnv({
  * part of `scripts/`) also imports `vendor/heyspex-mcp/vault-resolve.mjs` by a
  * relative path OUTSIDE `scripts/` — that file must be mirrored too, or the
  * copied validator dangles with MODULE_NOT_FOUND the moment it computes its
- * own default root. `vault-resolve.mjs` itself has no further local-file
- * imports (node builtins only), so this is a single extra copy, not a chain.
+ * own default root, and that file in turn imports `vault-binding.mjs` →
+ * `usable-dir-env.mjs` (a chain, not a single copy).
  *
- * Single source of truth: the next dependency the validator grows is a one-line
- * add here, not a silent breakage in every round-trip test.
+ * The mirror is DERIVED, not hand-listed: a hardcoded list rotted three times
+ * as modules grew imports (last miss: `usable-dir-env.mjs`, HS-PNBC). We walk
+ * relative import specifiers transitively from the validator and copy every
+ * reached file that lives outside `scripts/` (which is copied wholesale).
  *
  * @param {string} repoRoot Absolute path to the real repo root.
  * @param {string} root Absolute path to the temp vault being assembled.
  */
 export function mirrorValidatorDeps(repoRoot, root) {
   cpSync(join(repoRoot, 'scripts'), join(root, 'scripts'), { recursive: true });
-
-  mkdirSync(join(root, 'vendor', 'heyspex-mcp'), { recursive: true });
-  // vault-resolve.mjs imports vault-binding.mjs (the repo binding, HS-TYJA).
-  for (const file of ['vault-resolve.mjs', 'vault-binding.mjs']) {
-    const rel = join('vendor', 'heyspex-mcp', file);
-    cpSync(join(repoRoot, rel), join(root, rel));
+  for (const abs of localImportClosure(join(repoRoot, 'scripts', 'validate-vault-ids.mjs'))) {
+    const rel = relative(repoRoot, abs);
+    if (rel.startsWith('..') || isAbsolute(rel)) continue;
+    if (rel.split(sep)[0] === 'scripts') continue; // already copied wholesale
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    cpSync(abs, join(root, rel));
   }
+}
+
+// Relative specifiers in `from '…'`, side-effect `import '…'`, and literal `import('…')`.
+const LOCAL_IMPORT_RE = /(?:\bfrom\s*|\bimport\s*\(?\s*)(['"])(\.{1,2}\/[^'"]+)\1/g;
 
-  const indexerRel = join('spex-console', 'src', 'lib', 'indexer');
-  mkdirSync(join(root, indexerRel), { recursive: true });
-  for (const file of [
-    'vault-rules.mjs',
-    'vault-naming-rules.generated.mjs',
-    // validate-vault-ids.mjs imports handoff-envelope.mjs (split/defer lineage rule).
-    'handoff-envelope.mjs',
-  ]) {
-    const rel = join(indexerRel, file);
-    const src = join(repoRoot, rel);
-    if (existsSync(src)) cpSync(src, join(root, rel));
+/**
+ * Every local file transitively reachable from `entry` via relative import
+ * specifiers (bare/builtin specifiers ignored). A missing target is skipped so
+ * the copied script fails loudly with MODULE_NOT_FOUND instead of here.
+ *
+ * @param {string} entry Absolute path to the entry module.
+ * @returns {Set<string>} Absolute paths, entry included.
+ */
+export function localImportClosure(entry) {
+  const seen = new Set();
+  const stack = [entry];
+  while (stack.length) {
+    const file = stack.pop();
+    if (seen.has(file) || !existsSync(file)) continue;
+    seen.add(file);
+    for (const m of readFileSync(file, 'utf8').matchAll(LOCAL_IMPORT_RE)) {
+      stack.push(resolve(dirname(file), m[2]));
+    }
   }
+  return seen;
 }

package/bin/postinstall.mjs

@@ -1,88 +0,0 @@
-#!/usr/bin/env node
-// Root postinstall guard. The dev-machine setup steps (PM control-center deps,
-// Claude Code hooks, CommandCode update) live under scripts/, which
-// .vercelignore excludes from the Vercel upload — so on Vercel (or any CI, or
-// any environment where scripts/ is absent) this must exit 0 instead of
-// crashing `npm install` with MODULE_NOT_FOUND. Lives in bin/ (uploaded to
-// Vercel) precisely so the guard itself always resolves.
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-
-// Installed as somebody else's dependency (HS-ZJSP): the published `heyspex`
-// package ships this file because npm runs the `postinstall` script for every
-// consumer, but NONE of the dev-machine setup below belongs in a customer's
-// install — and printing a "skipping" line at them is noise, not information.
-// A package installed from the registry always lands under a node_modules/
-// directory; a clone of this repo never does. Exit silently in the former case.
-if (repoRoot.replace(/\\/g, "/").includes("/node_modules/")) {
-  process.exit(0);
-}
-
-const steps = [
-  ["scripts/ensure-pm-cc-deps.mjs"],
-  ["scripts/install-claude-code-hooks.mjs"],
-  // Cursor's two install surfaces. `.cursor/mcp.json` is gitignored (it is
-  // machine-local), so without this step a fresh clone opens in Cursor with no
-  // heyspex MCP server at all; `.cursor/hooks.json` is tracked but merges
-  // idempotently, and the installer also retires superseded registrations.
-  ["scripts/install-cursor-mcp.mjs"],
-  ["scripts/install-cursor-hooks.mjs"],
-  ["scripts/install-commandcode.mjs", "--update"],
-  ["scripts/sync-skills.mjs"],
-  // Git hooks (.git/hooks/ is never cloned) — installs pre-commit + pre-push so a
-  // single `npm install` on a fresh clone is enough, with no second `npm run setup`.
-  // No --force: an idempotent re-run no-ops on the HeySpex hook and refuses to
-  // clobber a foreign pre-commit (exit 1 surfaces that rather than silently replacing).
-  ["scripts/install-git-hooks.mjs"],
-];
-
-if (process.env.VERCEL || process.env.CI) {
-  console.log("[postinstall] VERCEL/CI detected — skipping dev-machine setup.");
-  process.exit(0);
-}
-
-for (const [script, ...args] of steps) {
-  const abs = join(repoRoot, script);
-  if (!existsSync(abs)) {
-    console.log(`[postinstall] ${script} not present — skipping dev-machine setup.`);
-    process.exit(0);
-  }
-  const { status } = spawnSync(process.execPath, [abs, ...args], {
-    cwd: repoRoot,
-    stdio: "inherit",
-  });
-  if (status !== 0) process.exit(status ?? 1);
-}
-
-// Advisory only, never fatal, and deliberately NOT `npm link` itself: a
-// postinstall that mutates the machine's global npm prefix would repoint `hs`
-// away from whatever clone owned it, silently, on every install. `npm install`
-// completing clean while `hs` resolves nowhere is exactly the fresh-machine
-// failure in [[HS-BFXF-WBJU-DIAG-hs-never-resolves-on-a-fresh-machine]] — so
-// say so here, where a new operator is already looking, and let `npm run
-// doctor` carry the full check. Imported dynamically so the published package
-// (which ships this file but not scripts/) can never fail to resolve it.
-const hsLinkLib = join(repoRoot, "scripts/lib/hs-link.mjs");
-if (existsSync(hsLinkLib)) {
-  try {
-    const { describeHsLink } = await import(pathToFileURL(hsLinkLib).href);
-    const link = describeHsLink(repoRoot);
-    if (link.status !== "linked") {
-      const what = {
-        missing: "does not resolve on PATH",
-        foreign: `resolves to an unrelated tool (${link.target})`,
-        "other-checkout": `resolves to a DIFFERENT checkout (${link.target})`,
-        unreadable: `resolves to ${link.shim}, whose target could not be read`,
-      }[link.status];
-      console.log(`[postinstall] heads up: \`hs\` ${what}.`);
-      console.log("[postinstall] Run `npm link` once from this repo root to put hs/heyspex/heyspex-mcp on PATH.");
-      console.log("[postinstall] Until then use `node bin/hs.mjs …` — never `npx hs` (unrelated package). Details: `npm run doctor`.");
-    }
-  } catch {
-    // An advisory that crashes the install would be worse than no advisory.
-  }
-}