heyspex 0.1.0 → 0.2.1

package/scripts/claude-hooks/claim-liveness-shared.mjs

@@ -0,0 +1,577 @@
+// Shared claim-liveness helpers for Claude Code + Cursor CLI hooks.
+// Resolves session id from host env / hook payload and PATCHes the tier-dispatched
+// heartbeat API — never reads `.heyspex/active-claims.json` ([[HS-TASK-A3FE]]).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import https from 'node:https';
+import { fileURLToPath } from 'node:url';
+
+import { resolveConsoleUrl as resolveConsoleUrlShared } from '../lib/console-url-resolver.mjs';
+// Bearer for the cloud-gated heartbeat PATCH — same reader every other consumer uses, never
+// re-implemented and never printed.
+import { readCredentialsMcpToken } from '../lib/dev-mode.mjs';
+import { hookVaultHeaders } from '../lib/hook-vault-header.mjs';
+// Read-only reuse of the resource governor's OWN liveness rule + config resolver — never a
+// second, hand-invented rule at this layer. See the "Lease liveness" section below.
+import { describeLivenessRule, resolveGovernorConfig } from '../../dev-factory/lib/fleet-queue-file.mjs';
+
+// The console's heartbeat PATCH is a WAN round-trip to Neon (measured 420–1400ms
+// on a home connection). The old 800ms budget sat *inside* that spread, so a
+// large fraction of heartbeats were killed mid-flight by `req.destroy()`, which
+// RSTs the socket and surfaces on the dev server as
+// `⨯ uncaughtException: [Error: aborted] { code: 'ECONNRESET' }`. Because the
+// gating below cuts request volume by ~10x, we can now afford a budget that sits
+// *above* the real latency spread, so a heartbeat completes instead of resetting.
+// Still well under the 5s hook timeout in `.claude/settings.json`.
+export const REQUEST_TIMEOUT_MS = 2500;
+export const PENDING_EXCERPT_MAX = 140;
+export const ERROR_MESSAGE_MAX = 280;
+
+// PreToolUse is registered with matcher `.*`, so without gating every single tool
+// call fires a blocking PATCH. Claims go stale after 10 minutes
+// (`staleTimeoutMs()`), so re-sending an *unchanged* status more than once per
+// 20s buys nothing. Status *transitions* (working→pending→blocked) always send
+// immediately — this only collapses repeats.
+export const HEARTBEAT_THROTTLE_MS = 20_000;
+// A session that holds no claim 404s on every tool call, and each 404 still costs
+// a full Neon round-trip server-side. Remember the negative answer and stop
+// asking. Safe to make this long because acquiring a claim invalidates it
+// immediately (see `CLAIM_ACQUIRE_TOOL_RE`) and acquire already stamps
+// `heartbeat_at` server-side — so a suppressed heartbeat cannot make a live
+// claim look stale (staleness is a 10-minute window).
+export const NO_CLAIM_TTL_MS = 180_000;
+// Console unreachable / timed out: back off briefly so we don't burn the full
+// request budget on every tool call while the dev server is down or restarting.
+export const UNREACHABLE_BACKOFF_MS = 15_000;
+const CACHE_MAX_SESSIONS = 32;
+
+// ── Lease liveness (HS-JM67, [[HS-AU7I-2U3R-EPIC-resource-governor-leases-and-wait]]) ───────────
+//
+// This hook is the client for the governor's `spec:HS-XXXX` resource kind (see the epic's
+// resource-key table): each session's cached entry below IS a holder record, so it must obey
+// the SAME liveness rule the governor states for every other resource kind — never a second,
+// hand-invented one. THE RULE is owned by dev-factory/lib/fleet-queue-file.mjs's
+// createResourceGovernor (isDead()) and imported here via describeLivenessRule(), not restated
+// by hand, so the two layers cannot drift apart:
+//
+//   a holder is DEAD (its lease reclaimable) iff it is NOT paused AND
+//   now - lastLivenessAt > leaseTtlMs. A PAUSED holder is NEVER reclaimed by liveness — only a
+//   resume (a tool call settling) or an administrator's forceBreak ends a pause.
+//
+// THE GAP THIS CLOSES (named in the task's Scope): PreToolUse fires once, then this hook goes
+// silent for the tool call's ENTIRE duration — a long Bash/build/model call can easily outlast
+// leaseTtlMs, and until now nothing distinguished that silence from a crashed session. Fix:
+// PreToolUse marks the session PAUSED (with a fresh liveness stamp — starting a call is itself
+// proof of life); PostToolUse/Stop/SubagentStop resume it (also a fresh liveness stamp, per the
+// governor's gov-resumed semantics). A session that pauses and then truly crashes (no further
+// hook calls at all) stays paused=true forever and is correctly exempt from reclaim under the
+// SAME rule the governor applies elsewhere — this module never invents a "paused too long"
+// second rule.
+//
+// CONFIGURATION, NOT A BARE CONSTANT ([[dev-factory-rules-are-configuration-not]]): leaseTtlMs
+// below is resolveGovernorConfig()'s own resolution — explicit override >
+// HEYSPEX_GOVERNOR_LEASE_TTL_MS env > the governor's GOVERNOR_DEFAULTS — the exact same
+// resolution the governor itself uses, so an owner can retune both layers with one env var.
+
+/** Same config source as the governor: explicit override > HEYSPEX_GOVERNOR_* env > defaults. */
+export function resolveLivenessConfig(overrides = {}) {
+  return resolveGovernorConfig(overrides);
+}
+
+/** The governor's own rule text, unchanged — never hand-restated at this layer. */
+export function describeHookLivenessRule(config = resolveLivenessConfig()) {
+  return describeLivenessRule(config);
+}
+
+/**
+ * THE liveness predicate, applied to one cached session entry. Mirrors
+ * createResourceGovernor()'s internal `isDead()` exactly: a paused holder is NEVER dead; an
+ * unpaused holder is dead once its last liveness stamp is older than `leaseTtlMs`. An entry
+ * with no liveness stamp at all reads as "unknown", not dead — same fail-open posture as every
+ * other read in this module (a session this hook has never heard a liveness signal from yet is
+ * not evidence of death).
+ */
+export function isHolderDead(entry, nowMs = Date.now(), config = resolveLivenessConfig()) {
+  if (!entry) return false;
+  if (entry.paused) return false;
+  const lastLivenessAt = entry.lastLivenessAt ?? entry.sentAt ?? entry.touchedAt;
+  if (typeof lastLivenessAt !== 'number' || !Number.isFinite(lastLivenessAt)) return false;
+  return nowMs - lastLivenessAt > config.leaseTtlMs;
+}
+
+/**
+ * PreToolUse: a tool call is starting whose duration is unknown and may outlast leaseTtlMs —
+ * mark the session PAUSED so it is never reclaimed mid-call, per the governor's rule. Starting
+ * the call is itself a fresh liveness signal, so lastLivenessAt is stamped too.
+ */
+export function markToolInFlight(cache, sessionId, nowMs) {
+  const entry = { ...(cache[sessionId] ?? {}), paused: true, lastLivenessAt: nowMs, touchedAt: nowMs };
+  cache[sessionId] = entry;
+  return entry;
+}
+
+/**
+ * PostToolUse / Stop / SubagentStop: no tool is in flight any more — resume, which (per the
+ * governor's gov-resumed handling) is itself a fresh liveness signal.
+ */
+export function markToolSettled(cache, sessionId, nowMs) {
+  const entry = { ...(cache[sessionId] ?? {}), paused: false, lastLivenessAt: nowMs, touchedAt: nowMs };
+  cache[sessionId] = entry;
+  return entry;
+}
+
+/**
+ * Enforce the rule across every cached session — the cache file
+ * (`.heyspex/claim-liveness-cache.json`) is shared by every session/process on this machine, so
+ * this mirrors the governor's reclaimAndPromote() running at the top of every mutating call: ANY
+ * hook invocation from ANY still-live session sweeps every OTHER session's dead entries too. A
+ * live-but-paused holder's entry is left completely untouched. Returns the list of reclaimed
+ * session ids (empty when nothing was dead).
+ */
+export function reclaimDeadSessions(cache, nowMs = Date.now(), config = resolveLivenessConfig()) {
+  const reclaimed = [];
+  for (const sessionId of Object.keys(cache)) {
+    if (isHolderDead(cache[sessionId], nowMs, config)) {
+      delete cache[sessionId];
+      reclaimed.push(sessionId);
+    }
+  }
+  return reclaimed;
+}
+
+export function repoRoot(fromUrl = import.meta.url) {
+  // claim-liveness-shared.mjs lives in scripts/claude-hooks/, so up two levels.
+  return path.resolve(path.dirname(fileURLToPath(fromUrl)), '..', '..');
+}
+
+// Delegates to the ONE shared resolver (scripts/lib/console-url-resolver.mjs,
+// [[HS-GD45-MCPC-TASK]]) — both MCP claims and this hook's PATCHes must hit
+// the same console, so they share one precedence implementation instead of
+// two hand-duplicated copies.
+export function resolveConsoleUrl(root = repoRoot()) {
+  return resolveConsoleUrlShared({ repoRoot: root });
+}
+
+export async function readStdin() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let resolved = false;
+    const finish = (value) => {
+      if (resolved) return;
+      resolved = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || null), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      finish(buf || null);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      finish(buf || null);
+    });
+  });
+}
+
+export function parseArgs(argv) {
+  const out = {};
+  for (const arg of argv.slice(2)) {
+    const m = /^--([^=]+)=(.*)$/.exec(arg);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+/** Normalize Claude (`PreToolUse`) and Cursor (`preToolUse`) event names. */
+export function normalizeHookEvent(event) {
+  if (!event || typeof event !== 'string') return null;
+  const key = event.trim();
+  const map = {
+    PreToolUse: 'PreToolUse',
+    preToolUse: 'PreToolUse',
+    PostToolUse: 'PostToolUse',
+    postToolUse: 'PostToolUse',
+    Stop: 'Stop',
+    stop: 'Stop',
+    SubagentStop: 'SubagentStop',
+    subagentStop: 'SubagentStop',
+  };
+  return map[key] ?? key;
+}
+
+/**
+ * Resolve the agent session id from hook stdin payload + host env.
+ * Claude: `session_id` / CLAUDE_CODE_SESSION_ID. Cursor: `conversation_id` /
+ * CURSOR_TRACE_ID (same id MCP `heyspex_claim_spec` writes on acquire).
+ */
+export function resolveSessionId(payload) {
+  const fromPayload =
+    (typeof payload?.session_id === 'string' && payload.session_id.trim()) ||
+    (typeof payload?.conversation_id === 'string' && payload.conversation_id.trim()) ||
+    '';
+  if (fromPayload) return fromPayload;
+
+  return (
+    process.env.CLAUDE_CODE_SESSION_ID?.trim() ||
+    process.env.CLAUDE_SESSION_ID?.trim() ||
+    process.env.CURSOR_TRACE_ID?.trim() ||
+    process.env.CURSOR_SESSION_ID?.trim() ||
+    process.env.COMPOSER_SESSION_ID?.trim() ||
+    process.env.HEYSPEX_SESSION_ID?.trim() ||
+    ''
+  );
+}
+
+// Claim lifecycle tools observed through the hook payload's `tool_name`. Seeing
+// one is authoritative news about whether this session holds a claim, so it
+// resets the negative cache rather than waiting out NO_CLAIM_TTL_MS.
+const CLAIM_ACQUIRE_TOOL_RE = /heyspex_(claim_spec|claim_acquire|claim_file)$/;
+const CLAIM_RELEASE_TOOL_RE = /heyspex_(release_spec|claim_release|defer_spec)$/;
+
+/**
+ * Classify a hook payload's tool name as a claim lifecycle event.
+ * Returns `"acquire"`, `"release"`, or `null`.
+ */
+export function claimLifecycleEvent(toolName) {
+  if (typeof toolName !== 'string' || !toolName) return null;
+  if (CLAIM_ACQUIRE_TOOL_RE.test(toolName)) return 'acquire';
+  if (CLAIM_RELEASE_TOOL_RE.test(toolName)) return 'release';
+  return null;
+}
+
+function truncate(value, limit) {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  return trimmed.length > limit ? trimmed.slice(0, limit) : trimmed;
+}
+
+// Build the PATCH body from the event + payload. Returns null when no update
+// should be emitted (e.g. a successful PostToolUse — we don't downgrade from
+// pending to working on every tool result; PreToolUse already covers that).
+export function buildPatch(event, payload) {
+  if (event === 'PreToolUse') {
+    const toolName = payload?.tool_name;
+    if (toolName === 'AskUserQuestion') {
+      const questions = payload?.tool_input?.questions;
+      const first = Array.isArray(questions) && questions.length > 0 ? questions[0] : null;
+      const excerpt = truncate(first?.question, PENDING_EXCERPT_MAX);
+      return {
+        status: 'pending',
+        pendingReason: 'question',
+        ...(excerpt ? { pendingExcerpt: excerpt } : {}),
+      };
+    }
+    return { status: 'working' };
+  }
+
+  if (event === 'Stop' || event === 'SubagentStop') {
+    return { status: 'pending', pendingReason: 'response' };
+  }
+
+  if (event === 'PostToolUse') {
+    const response = payload?.tool_response;
+    let errorText;
+    if (response && typeof response === 'object') {
+      if (response.is_error === true) {
+        errorText =
+          truncate(response.error, ERROR_MESSAGE_MAX) ??
+          truncate(response.message, ERROR_MESSAGE_MAX) ??
+          truncate(response.content, ERROR_MESSAGE_MAX) ??
+          'Tool returned is_error=true';
+      } else if (typeof response.error === 'string' && response.error.trim()) {
+        errorText = truncate(response.error, ERROR_MESSAGE_MAX);
+      }
+    }
+    if (errorText) {
+      return { status: 'blocked', errorMessage: errorText };
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * PATCH the heartbeat endpoint. Resolves to `{ status }` where `status` is the
+ * HTTP status code, or `null` when the request never got an answer (bad URL,
+ * connection refused, timeout).
+ *
+ * `Connection: close` is deliberate: the hook is a one-shot process, so keeping
+ * the socket alive only means the socket dies with the process — which the
+ * server sees as a reset. Asking for a clean close lets the server tear the
+ * connection down on its own terms.
+ *
+ * `token` (from `readCredentialsMcpToken()`) is sent as `Authorization: Bearer
+ * <token>` when present — the endpoint is bearer-gated server-side, so a hook
+ * running against the cloud console with no resolvable token 401s every time.
+ */
+export function patchHeartbeat(consoleUrl, sessionId, body, token) {
+  return new Promise((resolve) => {
+    let url;
+    try {
+      url = new URL('/api/control/active-claims/heartbeat', consoleUrl);
+    } catch {
+      resolve(null);
+      return;
+    }
+    const transport = url.protocol === 'https:' ? https : http;
+    const payload = JSON.stringify({ session_id: sessionId, ...body });
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const req = transport.request(
+      {
+        method: 'PATCH',
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(payload),
+          connection: 'close',
+          ...(token ? { authorization: `Bearer ${token}` } : {}),
+          ...hookVaultHeaders(),
+        },
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        // Drain the body before settling: bailing early would leave unread bytes
+        // on the socket, and destroying a socket with unread data is exactly what
+        // produces a server-side ECONNRESET.
+        res.on('data', () => {});
+        res.on('end', () => finish({ status }));
+        res.on('error', () => finish({ status }));
+      },
+    );
+    req.on('error', () => finish(null));
+    req.on('timeout', () => {
+      req.destroy();
+      finish(null);
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+/** Where the per-session send-gate state lives. Best-effort; never load-bearing. */
+export function livenessCachePath(root = repoRoot()) {
+  return path.join(root, '.heyspex', 'claim-liveness-cache.json');
+}
+
+function readLivenessCache(cachePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read-only check: does the negative-cache CURRENTLY say this session holds no
+ * claim (a heartbeat 404'd and `NO_CLAIM_TTL_MS` hasn't elapsed)? Local-file-only
+ * — no network round-trip — so callers with a tight PreToolUse budget (e.g. the
+ * claim-before-code hard gate, HS-38J5) can use it without adding request latency.
+ *
+ * Deliberately conservative in both directions:
+ *   - `true`  only on a FRESH negative signal (this session's own heartbeat
+ *     recently 404'd) — never inferred from "no entry at all", since an absent
+ *     entry just means no heartbeat has round-tripped yet (console cold-start,
+ *     offline dev, or this is the session's very first tool call).
+ *   - Never throws; a missing/corrupt cache file reads as "unknown" (false),
+ *     same fail-open posture as every other read in this module.
+ *
+ * @param {string} sessionId
+ * @param {string} [root]
+ * @returns {boolean}
+ */
+export function hasFreshNoClaimSignal(sessionId, root = repoRoot()) {
+  const trimmed = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!trimmed) return false;
+  const cache = readLivenessCache(livenessCachePath(root));
+  const entry = cache[trimmed];
+  return typeof entry?.noClaimUntil === 'number' && entry.noClaimUntil > Date.now();
+}
+
+function writeLivenessCache(cachePath, cache) {
+  // Drop the oldest sessions past the cap so the file cannot grow without bound.
+  const entries = Object.entries(cache).sort(
+    (a, b) => (b[1]?.touchedAt ?? 0) - (a[1]?.touchedAt ?? 0),
+  );
+  const trimmed = Object.fromEntries(entries.slice(0, CACHE_MAX_SESSIONS));
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    // Write-then-rename: concurrent hook processes must never observe a
+    // half-written file. A lost race just costs one extra heartbeat.
+    const tmp = `${cachePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(trimmed, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, cachePath);
+  } catch {
+    // Read-only checkout / racing rename — gating degrades to "always send".
+  }
+}
+
+/**
+ * Decide whether this heartbeat is worth a network round-trip.
+ * Returns `{ send: boolean, reason: string }`.
+ *
+ * Skips when the session is negative-cached (no claim), when the console was
+ * just unreachable, or when an identical status was sent within the throttle
+ * window. A status *change* always sends.
+ */
+export function shouldSendHeartbeat(entry, signature, now = Date.now()) {
+  if (!entry) return { send: true, reason: 'first-send' };
+  if (typeof entry.noClaimUntil === 'number' && entry.noClaimUntil > now) {
+    return { send: false, reason: 'no-claim-cached' };
+  }
+  if (typeof entry.retryAfter === 'number' && entry.retryAfter > now) {
+    return { send: false, reason: 'console-unreachable-backoff' };
+  }
+  if (entry.signature !== signature) return { send: true, reason: 'status-changed' };
+  if (typeof entry.sentAt !== 'number' || now - entry.sentAt >= HEARTBEAT_THROTTLE_MS) {
+    return { send: true, reason: 'throttle-window-elapsed' };
+  }
+  return { send: false, reason: 'throttled' };
+}
+
+/**
+ * Forget the "this session holds no claim" answer for `sessionId`. Call after a
+ * claim is acquired so the very next hook heartbeats instead of waiting out the
+ * negative-cache TTL.
+ */
+export function clearNoClaimCache(sessionId, root = repoRoot()) {
+  const trimmed = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!trimmed) return;
+  const cachePath = livenessCachePath(root);
+  const cache = readLivenessCache(cachePath);
+  if (!cache[trimmed]) return;
+  delete cache[trimmed].noClaimUntil;
+  delete cache[trimmed].retryAfter;
+  writeLivenessCache(cachePath, cache);
+}
+
+export async function emitClaimLivenessFromHook({
+  argv = process.argv,
+  eventArg,
+  payload,
+  // Injectable so the smoke test can exercise the real gate against a temp repo
+  // instead of the developer's live .heyspex/ state.
+  root = repoRoot(),
+}) {
+  const event = normalizeHookEvent(eventArg ?? payload?.hook_event_name);
+  if (!event) return;
+
+  const sessionId = resolveSessionId(payload);
+  if (!sessionId) return;
+
+  const cachePath = livenessCachePath(root);
+  const cache = readLivenessCache(cachePath);
+  const now = Date.now();
+
+  // Enforce the liveness rule FIRST (governor order: reclaimAndPromote() runs at the top of
+  // every mutating call) — this session's own hook invocation is itself proof of life for
+  // itself, and doubles as the poller that sweeps every OTHER cached session's dead entries too
+  // (the cache file is shared across every session/process on this machine). A live-but-paused
+  // holder is left untouched by this sweep.
+  reclaimDeadSessions(cache, now);
+
+  // Close the long-tool-call gap: PreToolUse marks this session PAUSED (exempt from reclaim)
+  // for the call's unknown duration; PostToolUse/Stop/SubagentStop resume it. Both edges are a
+  // fresh liveness stamp, matching the governor's gov-resumed semantics.
+  if (event === 'PreToolUse') {
+    markToolInFlight(cache, sessionId, now);
+  } else if (event === 'PostToolUse' || event === 'Stop' || event === 'SubagentStop') {
+    markToolSettled(cache, sessionId, now);
+  }
+  // Persist the reclaim sweep + pause/resume state now — several paths below return early
+  // (no lifecycle patch, no patch at all, throttled) without reaching the write at the bottom
+  // of this function, and the liveness state must never depend on a heartbeat actually sending.
+  writeLivenessCache(cachePath, cache);
+
+  // Claim lifecycle news arrives on the PostToolUse edge (the tool has actually
+  // run by then). Record it and stop — a lifecycle call carries no status patch
+  // of its own; the next PreToolUse sends against the corrected cache.
+  const toolErrored = payload?.tool_response?.is_error === true;
+  const lifecycle =
+    event === 'PostToolUse' && !toolErrored ? claimLifecycleEvent(payload?.tool_name) : null;
+  if (lifecycle) {
+    const entry = { ...(cache[sessionId] ?? {}), touchedAt: now };
+    if (lifecycle === 'acquire') {
+      delete entry.noClaimUntil;
+      delete entry.retryAfter;
+      // Force the next heartbeat through: acquire may have set a status the
+      // throttle would otherwise suppress as "unchanged".
+      delete entry.signature;
+      delete entry.sentAt;
+    } else {
+      entry.noClaimUntil = now + NO_CLAIM_TTL_MS;
+    }
+    cache[sessionId] = entry;
+    writeLivenessCache(cachePath, cache);
+    return;
+  }
+
+  const patch = buildPatch(event, payload);
+  if (!patch) return;
+
+  const signature = JSON.stringify(patch);
+  const entry = cache[sessionId];
+
+  const { send } = shouldSendHeartbeat(entry, signature, now);
+  if (!send) return;
+
+  const token = readCredentialsMcpToken();
+  const result = await patchHeartbeat(resolveConsoleUrl(root), sessionId, patch, token);
+
+  const next = { ...(entry ?? {}), touchedAt: now };
+  if (result === null) {
+    // No answer at all — console down or mid-restart. Back off; leave the last
+    // successful signature in place so the next send still counts as a change.
+    next.retryAfter = now + UNREACHABLE_BACKOFF_MS;
+  } else if (result.status === 404) {
+    // The endpoint answered "no active claim for this session". Stop asking.
+    next.noClaimUntil = now + NO_CLAIM_TTL_MS;
+    delete next.retryAfter;
+  } else if (result.status === 401 || result.status === 403) {
+    // The console rejected this machine's token — never cache that as success
+    // (a fixed/re-paired token must retry, not wait out the throttle window),
+    // and warn the operator exactly once per session. Still fails open: no
+    // throw, the tool call is never blocked — just back off so a persistently
+    // bad token can't turn into a per-tool-call flood.
+    if (!entry?.authWarned) {
+      console.error(
+        `HeySpex: console rejected this machine's token (${result.status}) — run \`hs login\`.`,
+      );
+    }
+    next.authWarned = true;
+    next.retryAfter = now + UNREACHABLE_BACKOFF_MS;
+    delete next.signature;
+    delete next.sentAt;
+  } else if (result.status >= 200 && result.status < 300) {
+    next.signature = signature;
+    next.sentAt = now;
+    delete next.noClaimUntil;
+    delete next.retryAfter;
+  } else {
+    // 4xx/5xx other than 404/401/403 — a malformed patch or a server fault.
+    // Throttle it like a success so a persistent error can't turn into a
+    // per-tool-call flood.
+    next.signature = signature;
+    next.sentAt = now;
+    delete next.retryAfter;
+  }
+  cache[sessionId] = next;
+  writeLivenessCache(cachePath, cache);
+}

package/scripts/claude-hooks/close-terminal-on-ship.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Hook entrypoint for auto-close terminal (Claude Code + Cursor).
+// See terminal-close-shared.mjs for detection/kill logic.
+//
+// Arms on ship; closes after heyspex_record_wip updates wip-state.json
+// (or on SessionEnd backstop). Opt-in debug trace (off by default):
+//   HEYSPEX_TERMINAL_CLOSE_DEBUG=1 → .heyspex/terminal-close-debug.jsonl
+// Mute: HEYSPEX_CLOSE_TERMINAL_ON_SHIP_OFF=1
+
+import {
+  armPendingTerminalClose,
+  isRecordWipSuccess,
+  isSessionEndEvent,
+  isShipEvent,
+  readStdin,
+  resolveCloseTerminalOnTaskCompleteFromSettings,
+  tryCloseIfReady,
+} from './terminal-close-shared.mjs';
+
+const KILL_SWITCH = 'HEYSPEX_CLOSE_TERMINAL_ON_SHIP_OFF';
+
+function resolveSessionId(payload) {
+  return (
+    payload?.session_id ??
+    payload?.conversation_id ??
+    process.env.CLAUDE_CODE_SESSION_ID ??
+    process.env.CURSOR_TRACE_ID ??
+    null
+  );
+}
+
+async function main() {
+  if (process.env[KILL_SWITCH] === '1') return;
+
+  const stdinRaw = await readStdin();
+  if (!stdinRaw) return;
+
+  let payload;
+  try {
+    payload = JSON.parse(stdinRaw);
+  } catch {
+    return;
+  }
+
+  if (!resolveCloseTerminalOnTaskCompleteFromSettings()) return;
+
+  if (isSessionEndEvent(payload)) {
+    tryCloseIfReady('session_end');
+    return;
+  }
+
+  if (isShipEvent(payload)) {
+    armPendingTerminalClose(resolveSessionId(payload), 'ship');
+    return;
+  }
+
+  if (isRecordWipSuccess(payload)) {
+    tryCloseIfReady('record_wip');
+  }
+}
+
+main().catch(() => {
+  // Swallow — never break the host agent.
+});

package/scripts/claude-hooks/coo-denylist-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/coo-denylist-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/coo-denylist-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/coo-guard-check.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/coo-guard-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import { hookGate as gate } from '../../spexharness/src/gates/coo-guard-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/deep-research-cost-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/deep-research-cost-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/deep-research-cost-gate.mjs';
+
+await runGateAsHook(gate);