heyspex 0.2.5 → 0.2.7

package/scripts/claude-hooks/_intent-classifier-semantic.mjs

@@ -33,7 +33,7 @@
 //   semantic_enabled: true|false   (default true — turns Layer 2 on/off entirely)
 //   mode: self_check|model         (default self_check — deterministic injection;
 //                                    `model` opts into the Ollama fallback below)
-//   endpoint:  Ollama base URL     (default http://192.168.1.252:11434 — mode:model only)
+//   endpoint:  Ollama base URL     (default http://localhost:11434 — mode:model only; HS-J3NY: never the owner's LAN box)
 //   model:     model name          (default qwen3:8b — mode:model only)
 //   timeout_ms: request budget     (default 2500 — the hook's overall budget is 5s)
 //   min_confidence: fire threshold (default 0.7 — consumed by the calling hook)
@@ -74,7 +74,7 @@ export const SEMANTIC_MODES = Object.freeze(['self_check', 'model']);
 export const DEFAULTS = Object.freeze({
   semanticEnabled: true,
   semanticMode: 'self_check',
-  endpoint: 'http://192.168.1.252:11434',
+  endpoint: 'http://localhost:11434',
   model: 'qwen3:8b',
   timeoutMs: 2500,
   minConfidence: 0.7,

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

@@ -49,6 +49,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getActiveConfig, isResolvedVault } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+import { parseSpecId } from '../../vendor/heyspex-mcp/spec-id-lib.mjs';
 import { hookVaultHeaders } from '../lib/hook-vault-header.mjs';
 import { resolveConsoleUrl as resolveConsoleUrlShared } from '../lib/console-url-resolver.mjs';
 import { readCredentialsMcpToken, resolveDevMode } from '../lib/dev-mode.mjs';
@@ -105,9 +106,23 @@ function ledgerRoots() {
 // HS-EPIC-BUD-PROTECT under vault id `vault-test`). Real ids are server-minted
 // file keys; a SessionStart preview must never present one of these as the
 // prior session's hand-off.
-const FIXTURE_ID_RE = /^HS-EPIC-(?:FILLER-\d+|OLD\d+|BUD-[A-Z0-9-]+|CLAIMED-BUD|TRIGGER(?:-[A-Z0-9-]+)?)$/;
+// Parsed through the sanctioned id parser (spec-id-lib parseSpecId), never a
+// hand-rolled type-first regex ([[HS-MIL-KY1F]]): only legacy type-first EPIC
+// ids whose family token is one of the known fixture families qualify.
+const FIXTURE_EPIC_FAMILIES = {
+  FILLER: (slug) => /^\d+$/.test(slug), // HS-EPIC-FILLER-07
+  BUD: (slug) => slug !== '', // HS-EPIC-BUD-PROTECT
+  CLAIMED: (slug) => slug === 'BUD', // HS-EPIC-CLAIMED-BUD
+  TRIGGER: () => true, // HS-EPIC-TRIGGER, HS-EPIC-TRIGGER-X
+};
 function isFixtureLedgerEntry(epicId) {
-  return typeof epicId === 'string' && FIXTURE_ID_RE.test(epicId);
+  if (typeof epicId !== 'string') return false;
+  const parsed = parseSpecId(epicId);
+  if (!parsed || parsed.ordering !== 'type-first' || parsed.typeLabel !== 'EPIC') return false;
+  const { familyKey, titleSlug } = parsed;
+  if (/^OLD\d+$/.test(familyKey)) return titleSlug === ''; // HS-EPIC-OLD34
+  const rule = FIXTURE_EPIC_FAMILIES[familyKey];
+  return rule ? rule(titleSlug) : false;
 }
 
 async function readStdinJson() {

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

@@ -5,6 +5,11 @@
  *   start|stop|status|build   tray-host lifecycle → companion/start.ps1 (PowerShell 7),
  *                             which launches companion/src/HeySpex.Companion.Host directly
  *                             (the versioned-folder indirection was retired 2026-08-12).
+ *                             From an installed npm package (no companion/ source) they
+ *                             drive the SpexCompanion the Windows setup installed, or offer
+ *                             the install ([[HS-056P-EH9T-EPIC-npx-heyspex-companion-install-front-door]]).
+ *   install [--quiet|--dry-run] download + SHA-256 + Authenticode check + run the signed
+ *                             SpexCompanionSetup.exe (scripts/lib/companion-install.mjs).
  *   settings list|get|set     every Companion setting, via the console's
  *                             GET/PUT /api/companion/settings ([[HS-UDH1]]); plus the
  *                             short aliases (mute, volume, orb, wake, ...).
@@ -25,6 +30,7 @@ import {
   renderHelp,
   runCompanionSettings,
 } from "./lib/hs-companion-settings.mjs";
+import { runCompanionInstall, runInstalledCompanionHost } from "./lib/companion-install.mjs";
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const START_PS1 = path.join(PKG_ROOT, "companion", "start.ps1");
@@ -35,6 +41,12 @@ 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/). Drive the Companion
+    // the Windows setup installed, or offer `npx heyspex companion install`.
+    if (!existsSync(path.join(PKG_ROOT, "companion"))) {
+      process.exit(runInstalledCompanionHost(sub));
+    }
     process.stderr.write(`hs companion: start script not found at ${START_PS1}\n`);
     process.exit(1);
   }
@@ -55,7 +67,32 @@ function runHost(sub, rest) {
   });
 }
 
+/** A one-line download progress meter, on an interactive stderr only. */
+function progressMeter() {
+  if (!process.stderr.isTTY) return null;
+  let last = -2;
+  return ({ received, total }) => {
+    const pct = total ? Math.floor((received / total) * 100) : -1;
+    if (pct === last && pct !== -1) return;
+    last = pct;
+    const mb = (received / 1048576).toFixed(1);
+    process.stderr.write(`\r  ${pct < 0 ? `${mb} MB` : `${pct}% (${mb} MB)`}${pct === 100 ? "\n" : ""}`);
+  };
+}
+
+// The async paths below (install, settings) make TLS requests, so they set
+// process.exitCode and return instead of calling process.exit(): on Windows with
+// Node 24, process.exit() while undici's pooled socket is still closing aborts
+// with `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)` (exit
+// 0xC0000409/127) after the right output was printed
+// ([[HS-5HM6-EH9T-DIAG-companion-install-dry-run-native]], same root cause as
+// [[HS-94QX-ZZKK-DIAG-cli-entrypoints-exit-with-process-exit]]).
 async function main(argv) {
+  if (argv[0] === "install") {
+    process.exitCode = await runCompanionInstall(argv.slice(1), { progress: progressMeter() });
+    return;
+  }
+
   const parsed = parseCompanionArgs(argv);
 
   if (parsed.error) {
@@ -76,13 +113,14 @@ async function main(argv) {
   const result = await runCompanionSettings(parsed, { consoleFetch });
   if (result.ok) {
     process.stdout.write(`${result.stdout}\n`);
-    process.exit(0);
+    process.exitCode = 0;
+    return;
   }
   process.stderr.write(`hs companion: ${result.stderr}\n`);
-  process.exit(result.exitCode);
+  process.exitCode = result.exitCode;
 }
 
 main(process.argv.slice(2)).catch((err) => {
   process.stderr.write(`hs companion: ${err.message}\n`);
-  process.exit(1);
+  process.exitCode = 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();