heyspex 0.2.4 → 0.2.6

package/scripts/claude-statusline/statusline-command.mjs

@@ -32,11 +32,14 @@
 //     write the current pin to `.heyspex/statusline-focus-cache.json` on every
 //     change, so the file reflects the live pin within ms of a change.
 //   - PULL: within FOCUS_CACHE_TTL_MS we read that file with no HTTP at all
-//     (including a negative-cached null when the console is down); only past the
-//     TTL do we fall back to one GET to reconcile (console restarted, cache
-//     deleted, first run before any pin change), then rewrite the file.
+//     (including a negative-cached null when the console is down); past the TTL
+//     we still render the cached value immediately and spawn ONE detached,
+//     authenticated background refresh per window (maybeRefreshStatuslineCaches,
+//     HS-17A1 / HS-5EPV) that rewrites the file for the next repaint. The line
+//     itself never makes a network call.
 // Because push keeps the value fresh, the TTL is just a reconciliation interval —
-// default 60s, overridable via HEYSPEX_STATUSLINE_FOCUS_TTL_MS (0 = always fetch).
+// default 60s, overridable via HEYSPEX_STATUSLINE_FOCUS_TTL_MS (0 = refresh every
+// window, min 5 s).
 //   .heyspex/active-claims.json  — claims[*].sessionId / specId / status (still
 //                                  file-backed pending its own Neon migration, [[HS-TASK-ACLM]]).
 //   .git (via `git branch --show-current`) — current branch
@@ -297,7 +300,8 @@ function formatTelemetry(telemetry, usedPct) {
 // #28); we already hold the value, so a failed write is harmless — clean up and
 // move on rather than retry or throw.
 function writeFocusCache(file, specId) {
-  if (FOCUS_CACHE_TTL_MS === 0) return;
+  // Written even when FOCUS_CACHE_TTL_MS is 0: the cache is the line's only pin
+  // source now (TTL 0 just means "always stale -> refresh every window").
   const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
   // Carry the console-pushed `telemetry` block forward. This writer owns only the
   // pin; without the read-back a pull-path refresh (every repaint on a cache miss)
@@ -332,11 +336,14 @@ function writeFocusCache(file, specId) {
 // Live focus-pin fetch from the console. Short timeout so a slow/absent console
 // never makes the statusline sluggish. Returns the spec id, or null when the
 // console is unreachable / has no pin.
-async function fetchPinnedSpecId(base) {
+async function fetchPinnedSpecId(base, { headers, timeoutMs = CONSOLE_TIMEOUT_MS } = {}) {
   const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), CONSOLE_TIMEOUT_MS);
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
-    const res = await fetch(`${base}/api/control/pin`, { signal: ctrl.signal });
+    const res = await fetch(`${base}/api/control/pin`, {
+      signal: ctrl.signal,
+      ...(headers ? { headers } : {}),
+    });
     if (!res.ok) return null;
     const body = await res.json();
     const id = body?.pin?.specId;
@@ -353,27 +360,264 @@ async function fetchPinnedSpecId(base) {
 // running this returns null and the segment is simply dropped. A short-TTL file
 // cache (see header) collapses the per-message / per-refresh burst of statusline
 // invocations into at most one backend call per TTL window.
-async function readPinnedSpecId(root, opts = {}) {
-  const base = consoleUrl(root);
-  if (!base) return null;
+async function readPinnedSpecId(root) {
+  // Every host (Claude Code and Copilot) never blocks on the network: serve the
+  // last cached pin at ANY age (stale-while-revalidate — build() kicks off the
+  // detached, authenticated refresh, maybeRefreshStatuslineCaches below), or drop
+  // the segment. Not gated on consoleUrl(): that only knows the env var / local
+  // discovery file (empty in prod mode), while the refresh child resolves the
+  // console the cloud-aware way. HS-5EPV: the Claude path used to do an inline,
+  // UNAUTHENTICATED GET here that prod refuses, so its pin went stale forever.
+  return readAnyAgePinnedSpecId(focusCacheFile(root));
+}
+
+function readAnyAgePinnedSpecId(cacheFile) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    return typeof parsed?.specId === 'string' && parsed.specId ? parsed.specId : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Background cache refresh, every host — HS-17A1 (Copilot), HS-5EPV (Claude Code).
+//
+// The status line must never wait on the network, and in prod mode only an
+// authenticated read reaches the console (the old Claude-path inline GET was
+// unauthenticated and refused, so its pin froze). Stale-while-revalidate:
+// build() serves whatever is cached now and, when the pin cache (or, for
+// Copilot, the claims snapshot) is missing/past its TTL, spawns ONE detached,
+// unref'd child (`--refresh-caches <root>`) that does the authenticated console
+// reads and rewrites both caches for the NEXT repaint.
+//
+// At most one refresh per window: the window is the focus TTL (min 5 s) and
+// the guard is an exclusive-create lock file named after the window's bucket
+// index (`.heyspex/statusline-refresh-<bucket>.lock`, `wx`), so concurrent
+// repaints race on an atomic create and exactly one wins per bucket. Older
+// bucket files are swept by the winner. HEYSPEX_STATUSLINE_NO_REFRESH=1
+// disables spawning (tests / offline).
+// ---------------------------------------------------------------------------
+const COPILOT_REFRESH_MIN_WINDOW_MS = 5000;
+const COPILOT_REFRESH_TIMEOUT_MS = 8000;
+const REFRESH_LOCK_RE = /^statusline-refresh-\d+\.lock$/;
+
+// A claim counts as live for the Copilot repo fallback only if its newest
+// liveness stamp (lastActivityAt / heartbeatAt / claimedAt) is within this
+// window — mirrors the console's DEFAULT_CLAIM_STALE_MS (claim-lease.ts, 15 min).
+const CLAIM_FRESH_MS = (() => {
+  const raw = Number(process.env.HEYSPEX_STATUSLINE_CLAIM_FRESH_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 15 * 60_000;
+})();
+
+function claimsCacheFile(root) {
+  return path.join(root, '.heyspex', 'statusline-claims-cache.json');
+}
+
+/** Console claims snapshot written by the refresh child: `{ at, claims[] }` or null. */
+function readClaimsCache(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(claimsCacheFile(root), 'utf8'));
+    if (!parsed || typeof parsed.at !== 'number' || !Array.isArray(parsed.claims)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function copilotRefreshWindowMs() {
+  return Math.max(FOCUS_CACHE_TTL_MS, COPILOT_REFRESH_MIN_WINDOW_MS);
+}
 
-  const cacheFile = focusCacheFile(root);
-  const cached = readFocusCache(cacheFile);
-  if (cached) return cached.specId;
-  // Non-Claude hosts (Copilot) never block on the network: serve the last pushed
-  // pin even when past its TTL, or drop the segment.
-  if (opts.cacheOnly) {
+/**
+ * Stale-while-revalidate trigger, every host. Never blocks, never throws.
+ * Returns 'disabled' | 'fresh' | 'locked' | 'spawned' | 'error' (for tests).
+ * `needClaims` (Copilot) also treats a missing/old claims snapshot as stale; the
+ * Claude host renders only session-keyed claims, so only the pin gates it. The
+ * child always refreshes both, and the per-window lock is shared across hosts.
+ * @param {string} root
+ * @param {{ spawnImpl?: typeof spawn, now?: number, env?: Record<string, string|undefined>, needClaims?: boolean }} [deps]
+ */
+export function maybeRefreshStatuslineCaches(
+  root,
+  { spawnImpl = spawn, now = Date.now(), env = process.env, needClaims = true } = {},
+) {
+  try {
+    if (env.HEYSPEX_STATUSLINE_NO_REFRESH === '1') return 'disabled';
+    const windowMs = copilotRefreshWindowMs();
+    const pinFresh = readFocusCache(focusCacheFile(root)) !== undefined;
+    const claims = needClaims ? readClaimsCache(root) : null;
+    const claimsFresh = !needClaims || (!!claims && now - claims.at < windowMs);
+    if (pinFresh && claimsFresh) return 'fresh';
+
+    const dir = path.join(root, '.heyspex');
+    fs.mkdirSync(dir, { recursive: true });
+    const lockName = `statusline-refresh-${Math.floor(now / windowMs)}.lock`;
+    let fd;
+    try {
+      fd = fs.openSync(path.join(dir, lockName), 'wx');
+    } catch (err) {
+      return err?.code === 'EEXIST' ? 'locked' : 'error';
+    }
+    try {
+      fs.writeSync(fd, String(now));
+    } finally {
+      fs.closeSync(fd);
+    }
     try {
-      const parsed = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
-      return typeof parsed?.specId === 'string' && parsed.specId ? parsed.specId : null;
+      for (const f of fs.readdirSync(dir)) {
+        if (f !== lockName && REFRESH_LOCK_RE.test(f)) fs.rmSync(path.join(dir, f), { force: true });
+      }
     } catch {
-      return null;
+      /* sweep is best-effort */
     }
+    const child = spawnImpl(process.execPath, [fileURLToPath(import.meta.url), '--refresh-caches', root], {
+      cwd: root,
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child?.unref?.();
+    return 'spawned';
+  } catch {
+    return 'error';
   }
+}
+
+/** Copilot-host name kept for existing callers/tests (HS-17A1). */
+export const maybeRefreshCopilotCaches = maybeRefreshStatuslineCaches;
 
-  const specId = await fetchPinnedSpecId(base);
-  writeFocusCache(cacheFile, specId);
-  return specId;
+/**
+ * The detached child: authenticated console reads (same console-URL resolver,
+ * bearer, vault and account headers the MCP uses; cwd is the repo, so the vault
+ * header is the repo-bound one), then rewrite the focus cache and the claims
+ * snapshot. Heavy imports are dynamic so the foreground line never pays for them.
+ * A failed read still stamps the cache so the next window, not the next repaint,
+ * retries.
+ */
+async function refreshStatuslineCaches(root) {
+  if (!root) return;
+  let base = null;
+  let headers = {};
+  try {
+    const { resolveConsoleUrl } = await import('../lib/console-url-resolver.mjs');
+    base = resolveConsoleUrl({ repoRoot: root, log: () => {} });
+  } catch {
+    base = consoleUrl(root);
+  }
+  if (!base) return;
+  try {
+    const cf = await import('../../vendor/heyspex-mcp/console-fetch.mjs');
+    for (const fn of [cf.getAuthHeader, cf.getVaultIdHeader, cf.getAccountIdHeader]) {
+      try {
+        Object.assign(headers, fn() || {});
+      } catch {
+        /* missing token / unbound vault / no account: send what we have */
+      }
+    }
+  } catch {
+    headers = {};
+  }
+  try {
+    fs.mkdirSync(path.join(root, '.heyspex'), { recursive: true });
+  } catch {
+    /* ignore */
+  }
+
+  const specId = await fetchPinnedSpecId(base, { headers, timeoutMs: COPILOT_REFRESH_TIMEOUT_MS });
+  writeFocusCache(focusCacheFile(root), specId);
+
+  let claims = [];
+  let error;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), COPILOT_REFRESH_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${base}/api/claims`, { headers, signal: ctrl.signal });
+    if (res.ok) {
+      const body = await res.json();
+      claims = (Array.isArray(body?.claims) ? body.claims : [])
+        .filter((c) => c && typeof c.specId === 'string')
+        .map((c) => ({
+          specId: c.specId,
+          sessionId: c.sessionId ?? null,
+          agent: c.agent ?? null,
+          status: c.status ?? null,
+          effectiveStatus: c.effectiveStatus ?? null,
+          claimedAt: c.claimedAt ?? null,
+          lastActivityAt: c.lastActivityAt ?? null,
+          heartbeatAt: c.heartbeatAt ?? null,
+          staleAt: c.staleAt ?? null,
+          expiresAt: c.expiresAt ?? null,
+        }));
+    } else {
+      error = `http ${res.status}`;
+    }
+  } catch {
+    error = 'unreachable';
+  } finally {
+    clearTimeout(timer);
+  }
+  const file = claimsCacheFile(root);
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify({ at: Date.now(), claims, ...(error ? { error } : {}) }));
+    fs.renameSync(tmp, file);
+  } catch {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// Copilot-only repo fallback for the worked-spec segment, used ONLY when the
+// session-id lookup misses (a Copilot session id never matches a HeySpex claim,
+// which is keyed by the MCP/agent session). Deliberately NOT used on the Claude
+// path — see readActiveClaim's comment for why a cross-session fallback was
+// removed there; Copilot has no transcript signal to replace it, so it gets this
+// narrower rule instead:
+//   Candidates: `.heyspex/active-claims.json` (free tier, file-backed) plus the
+//   console claims snapshot the refresh child wrote (paid tier; the console
+//   scopes it to THIS repo's bound vault). The snapshot is ignored when older
+//   than CLAIM_FRESH_MS.
+//   A candidate is live only if: not released, effectiveStatus is not 'stale',
+//   expiresAt/staleAt (when present) are in the future, and its newest
+//   liveness stamp (max of lastActivityAt, heartbeatAt, claimedAt) is within
+//   CLAIM_FRESH_MS of now.
+//   Winner: the live candidate with the newest liveness stamp.
+export function readMostRecentRepoClaim(root, now = Date.now()) {
+  const candidates = [];
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, '.heyspex', 'active-claims.json'), 'utf8'));
+    const claims = parsed && typeof parsed === 'object' && parsed.claims ? parsed.claims : {};
+    candidates.push(...Object.values(claims));
+  } catch {
+    /* no file-backed claims */
+  }
+  const snap = readClaimsCache(root);
+  if (snap && now - snap.at < CLAIM_FRESH_MS) candidates.push(...snap.claims);
+
+  const ts = (v) => {
+    const n = typeof v === 'string' ? Date.parse(v) : NaN;
+    return Number.isFinite(n) ? n : null;
+  };
+  let best = null;
+  let bestAt = -Infinity;
+  for (const c of candidates) {
+    if (!c || typeof c.specId !== 'string' || !c.specId) continue;
+    if (c.status === 'released' || c.effectiveStatus === 'stale') continue;
+    const expires = ts(c.expiresAt);
+    const stale = ts(c.staleAt);
+    if ((expires !== null && expires <= now) || (stale !== null && stale <= now)) continue;
+    const live = Math.max(...[c.lastActivityAt, c.heartbeatAt, c.claimedAt].map(ts).filter((n) => n !== null));
+    if (!Number.isFinite(live) || now - live > CLAIM_FRESH_MS) continue;
+    if (live > bestAt) {
+      best = c;
+      bestAt = live;
+    }
+  }
+  return best;
 }
 
 // Session-matched only — deliberately no "most-recently-active claim"
@@ -503,7 +747,11 @@ function relevantSpecFromTranscript(session) {
 // only (name kept for backward compat with the original "suppress fallback"
 // meaning — the fallback it originally guarded no longer exists).
 function pickRelevantSpec(root, session, opts = {}) {
-  const claim = readActiveClaim(root, session?.session_id);
+  // `repoClaimFallback` (Copilot only): on a session-id miss, fall back to the
+  // repo's most recent live claim (readMostRecentRepoClaim). Claude passes none.
+  const claim =
+    readActiveClaim(root, session?.session_id) ??
+    (opts.repoClaimFallback ? readMostRecentRepoClaim(root) : null);
   const claimAt = claim ? Date.parse(claim.lastActivityAt ?? claim.claimedAt ?? '') : NaN;
   const ref = process.env.HEYSPEX_STATUSLINE_NO_CLAIM === '1' || opts.noTranscript
     ? null
@@ -996,7 +1244,10 @@ function threadLabel(session) {
 // `opts` (all optional; the Claude Code path passes none and is unchanged):
 //   host: 'copilot'   - no Claude glyph, no Haiku thread label, no transcript scan
 //   (Copilot's transcript_path is a directory, and there is no `claude` CLI), and
-//   a cache-only focus-pin read so the line never waits on the console.
+//   and a repo-level claim fallback for the worked-spec segment (readMostRecentRepoClaim).
+//   Both hosts read the focus pin cache-only (never wait on the console); it is
+//   kept fresh by a detached background refresh, maybeRefreshStatuslineCaches.
+//   refreshCaches: test seam replacing maybeRefreshStatuslineCaches.
 export async function build(root, session, opts = {}) {
   const foreign = opts.host === 'copilot';
   const segments = [];
@@ -1029,7 +1280,11 @@ export async function build(root, session, opts = {}) {
   const githubCluster = [dir, branch].filter(Boolean).join(' > ');
   if (githubCluster) segments.push(`${mark === GLYPH ? GITHUB_GLYPH : foreign ? '' : '⎇'} ${githubCluster}`.trim());
 
-  const pinned = await readPinnedSpecId(root, { cacheOnly: foreign });
+  // Stale-while-revalidate (both hosts) — kick the detached refresh (no-op when
+  // the caches are fresh or a refresh already ran this window), then read the
+  // cache. Copilot also needs the claims snapshot fresh (repo claim fallback).
+  (opts.refreshCaches ?? maybeRefreshStatuslineCaches)(root, { needClaims: foreign });
+  const pinned = await readPinnedSpecId(root);
   if (pinned) segments.push(`${mark} ${pinned}`);
 
   // HeySpex cluster, far right: "<glyph> <pillar> > <fileID> > <summary>"
@@ -1040,7 +1295,7 @@ export async function build(root, session, opts = {}) {
   // recent (pickRelevantSpec, above) — so it updates as the conversation's
   // focus moves, and never shows another session's claim.
   // Summary: what this session is about, in 2-6 words (sticky, pivot-only).
-  const worked = workedDoc(root, pickRelevantSpec(root, session, { noTranscript: foreign }));
+  const worked = workedDoc(root, pickRelevantSpec(root, session, { noTranscript: foreign, repoClaimFallback: foreign }));
   const label = foreign ? null : threadLabel(session);
   const heyspexCluster = [worked?.pillar, worked?.display, label].filter(Boolean).join(' > ');
   if (heyspexCluster) segments.push(`${mark} ${heyspexCluster}`);
@@ -1067,6 +1322,11 @@ async function main() {
 if (isDirectRun) {
   if (process.argv[2] === '--refresh-label') {
     refreshLabel(process.argv[3], process.argv[4], process.argv[5]);
+  } else if (process.argv[2] === '--refresh-caches' || process.argv[2] === '--refresh-copilot') {
+    // '--refresh-copilot' is the HS-17A1 spelling, accepted for compatibility.
+    refreshStatuslineCaches(process.argv[3])
+      .catch(() => {})
+      .finally(() => process.exit(0));
   } else {
     main();
   }

package/scripts/hs-companion.mjs

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import {
   makeCompanionConsoleFetch,
   parseCompanionArgs,
+  renderCompanionNotDistributed,
   renderHelp,
   runCompanionSettings,
 } from "./lib/hs-companion-settings.mjs";
@@ -35,6 +36,13 @@ function resolvePwsh() {
 
 function runHost(sub, rest) {
   if (!existsSync(START_PS1)) {
+    // No companion/ source beside this script: an installed npm package, not a
+    // repo checkout (the tarball never ships companion/). Say so instead of
+    // naming a path the customer can do nothing about.
+    if (!existsSync(path.join(PKG_ROOT, "companion"))) {
+      process.stderr.write(`${renderCompanionNotDistributed(sub)}\n`);
+      process.exit(1);
+    }
     process.stderr.write(`hs companion: start script not found at ${START_PS1}\n`);
     process.exit(1);
   }

package/scripts/install-claude-code-hooks.mjs

@@ -25,8 +25,18 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+// HS_SETUP_TARGET (what `hs setup claude` passes), else this checkout -- or,
+// from an installed `heyspex` package, the customer project found from cwd.
+// Never the package's own folder under node_modules/.
+const REPO_ROOT = resolveSetupTarget({ platformRoot: PLATFORM_ROOT });
 const SETTINGS_PATH = path.join(REPO_ROOT, '.claude', 'settings.json');
+// CUSTOMER TARGET: a repo other than this checkout gets the customer hook kit
+// (scripts/lib/customer-kit.mjs) through the committed, self-locating launcher
+// `.claude/heyspex/run-hook.mjs` -- the same rows `hs install` / `hs connect`
+// write -- never the platform-only rows, whose shim path exists only here.
+const CUSTOMER = !samePlatformPath(REPO_ROOT, PLATFORM_ROOT);
+const LAUNCHER_PATH = path.join(REPO_ROOT, ...CUSTOMER_LAUNCHERS.claude.rel);
 const HOOK_TIMEOUT_SECONDS = 5;
 
 const CLAIM_STATUS_MARKER = 'scripts/claude-hooks/emit-claim-status.mjs';
@@ -43,7 +53,16 @@ const SESSION_ACTIVITY_MARKER = 'scripts/claude-hooks/log-session-activity.mjs';
 // scripts/claude-hooks/_run.mjs and docs/claude-code-setup.md.
 const SHIM = 'scripts/claude-hooks/_run.mjs';
 // Self-locating, env-independent, fail-open command (Copilot compatibility): scripts/lib/customer-kit.mjs buildBootstrap().
-import { PLATFORM_RUNNER_PREFIX } from './lib/customer-kit.mjs';
+import {
+  CUSTOMER_LAUNCHERS,
+  PLATFORM_RUNNER_PREFIX,
+  customerRunnerPrefix,
+  mergeCustomerKitHooks,
+  ourHookTail,
+  planCustomerLauncherWrite,
+  resolveSetupTarget,
+  samePlatformPath,
+} from './lib/customer-kit.mjs';
 
 /** Canonical command string for a hook: `node "$CLAUDE_PROJECT_DIR/_run.mjs" <name> [args]`. */
 function shimCommand(scriptMarker, args = '') {
@@ -262,11 +281,93 @@ function check() {
   process.exit(1);
 }
 
+// ---------------------------------------------------------------------------
+// Customer target (a repo other than this checkout)
+// ---------------------------------------------------------------------------
+
+function readLauncher() {
+  try {
+    return fs.readFileSync(LAUNCHER_PATH, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function customerInstall() {
+  const settings = readSettings();
+  const merge = mergeCustomerKitHooks(settings, customerRunnerPrefix());
+  const plan = planCustomerLauncherWrite(readLauncher(), 'claude');
+  if (plan.write) {
+    fs.mkdirSync(path.dirname(LAUNCHER_PATH), { recursive: true });
+    fs.writeFileSync(LAUNCHER_PATH, plan.text, 'utf8');
+  }
+  if (merge.changed) writeSettings(settings);
+  if (!merge.changed && !plan.write) {
+    console.log(`install-claude-code-hooks: already installed (${merge.total} hooks, no changes) → ${SETTINGS_PATH}`);
+    return;
+  }
+  const parts = [];
+  if (merge.added.length) parts.push(`added ${merge.added.length}`);
+  if (merge.repaired.length) parts.push(`repaired ${merge.repaired.length}`);
+  if (merge.removed.length) parts.push(`retired ${merge.removed.length}`);
+  if (parts.length) console.log(`install-claude-code-hooks: ${parts.join('; ')} → ${SETTINGS_PATH} (${merge.total} hooks)`);
+  if (plan.write) console.log(`install-claude-code-hooks: wrote ${LAUNCHER_PATH} (resolves node_modules/heyspex)`);
+}
+
+function customerCheck() {
+  const settings = readSettings();
+  const merge = mergeCustomerKitHooks(JSON.parse(JSON.stringify(settings)), customerRunnerPrefix());
+  const plan = planCustomerLauncherWrite(readLauncher(), 'claude');
+  const issues = [
+    ...merge.added.map((x) => `missing ${x}`),
+    ...merge.repaired.map((x) => `drift ${x}`),
+    ...merge.removed.map((x) => `stale ${x}`),
+    ...(plan.write ? [`launcher ${CUSTOMER_LAUNCHERS.claude.rel.join('/')} ${plan.reason}`] : []),
+  ];
+  if (issues.length === 0) {
+    console.log('install-claude-code-hooks --check: OK');
+    process.exit(0);
+  }
+  console.error('install-claude-code-hooks --check: drift detected');
+  for (const issue of issues) console.error(`  - ${issue}`);
+  console.error('  Run `npx hs setup claude` to repair.');
+  process.exit(1);
+}
+
+function customerUninstall() {
+  const settings = readSettings();
+  if (!settings.hooks || typeof settings.hooks !== 'object') {
+    console.log('install-claude-code-hooks: nothing to uninstall (no hooks block).');
+    return;
+  }
+  let removed = 0;
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = groups
+      .map((g) => {
+        if (!g || !Array.isArray(g.hooks)) return g;
+        const hooks = g.hooks.filter((h) => ourHookTail(h?.command) === null);
+        removed += g.hooks.length - hooks.length;
+        return { ...g, hooks };
+      })
+      .filter((g) => !Array.isArray(g?.hooks) || g.hooks.length > 0);
+    if (kept.length === 0) delete settings.hooks[event];
+    else settings.hooks[event] = kept;
+  }
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  writeSettings(settings);
+  console.log(`install-claude-code-hooks: uninstalled ${removed} hook entr${removed === 1 ? 'y' : 'ies'} from ${SETTINGS_PATH}.`);
+}
+
 const mode = process.argv.includes('--uninstall')
   ? 'uninstall'
   : process.argv.includes('--check')
     ? 'check'
     : 'install';
-if (mode === 'uninstall') uninstall();
+if (CUSTOMER) {
+  if (mode === 'uninstall') customerUninstall();
+  else if (mode === 'check') customerCheck();
+  else customerInstall();
+} else if (mode === 'uninstall') uninstall();
 else if (mode === 'check') check();
 else install();

package/scripts/install-copilot-hooks.mjs

@@ -86,6 +86,7 @@ function parseArgs(argv) {
     else if (x === '--check') a.check = true;
     else if (x === '--uninstall') a.uninstall = true;
     else if (x === '--print') a.print = true;
+    else if (x === '--help' || x === '-h') a.help = true;
     else if (x === '--json') a.json = true;
     else if (x === '--target') {
       a.target = argv[++i] ?? null;
@@ -238,10 +239,25 @@ function manualCommands(spec) {
   ];
 }
 
+/** This package's own version (package.json), or null when unreadable. */
+function packageVersion() {
+  try {
+    const v = JSON.parse(fsDeps.readFile(path.join(PACKAGE_ROOT, 'package.json')) ?? 'null')?.version;
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The install doc as printed: its `heyspex-<version>.tgz` placeholder names this package's real version. */
+export function renderInstallDoc(doc, version) {
+  return version ? doc.replace(/heyspex-<version>\.tgz/g, `heyspex-${version}.tgz`) : doc;
+}
+
 function doPrint(out) {
   out(`Next: run \`${nextCommand()}\` (plugin) or \`${nextCommand()} --hooks\` (cloud agent) in this repo, then /restart.`);
   const doc = fsDeps.readFile(path.join(PACKAGE_ROOT, 'docs', 'copilot-plugin-install.md'));
-  if (doc !== null) { out(''); out(doc.replace(/\s+$/, '')); return 0; }
+  if (doc !== null) { out(''); out(renderInstallDoc(doc, packageVersion()).replace(/\s+$/, '')); return 0; }
   const spec = resolvePluginSpec(PACKAGE_ROOT);
   out('');
   out('# Installing HeySpex in GitHub Copilot CLI (built-in fallback; docs/copilot-plugin-install.md not found)');
@@ -385,6 +401,10 @@ export function main(argv = process.argv.slice(2), io = {}) {
       err('usage: hs setup copilot [--hooks] [--statusline [--force]] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
       return 2;
     }
+    if (a.help) {
+      out('usage: hs setup copilot [--hooks] [--statusline [--force]] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
+      return 0;
+    }
     if (a.print) return doPrint(out);
     const target = a.target ? path.resolve(a.target) : findRepoRoot(process.env.HS_SETUP_TARGET?.trim() || process.cwd());
     if (a.check) return doCheck(a, target, out);

package/scripts/install-cursor-hooks.mjs

@@ -42,13 +42,14 @@ import {
   hookScope,
   invokedDirectly,
   planCustomerLauncherWrite,
+  resolveSetupTarget,
   samePlatformPath,
 } from './lib/customer-kit.mjs';
 
 const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const REPO_ROOT = process.env.HS_SETUP_TARGET?.trim()
-  ? path.resolve(process.env.HS_SETUP_TARGET.trim())
-  : PLATFORM_ROOT;
+// HS_SETUP_TARGET, else this checkout -- or, from an installed package, the
+// customer project found from cwd (never the package folder itself).
+const REPO_ROOT = resolveSetupTarget({ platformRoot: PLATFORM_ROOT });
 const SETTINGS_PATH = path.join(REPO_ROOT, '.cursor', 'hooks.json');
 
 // CUSTOMER TARGET (`hs setup cursor` / `hs doctor --fix` with HS_SETUP_TARGET