heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/session-end.mjs

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+// Claude Code SessionEnd hook (HS-EPIC-NWUE / HS-EPIC-2BKX; engine wiring per
+// task HS-U618, epic HS-Y646 "session bootstrap and stop for every seat").
+//
+// Fires when a Claude Code session ends and does TWO independent things:
+//
+//   1. Console claim relay (original behavior, unchanged): posts the session
+//      id + termination `source` to `/api/agent/session-end`, which
+//      (server-side, tier-correctly) finds the matching active claim and
+//      releases it so the What's Next hero flips the Launch CTA back to
+//      "Re-spawn session". This is the FAST path for "the agent closed" — the
+//      10-min stale timeout is the backstop for hard window kills / SIGKILL,
+//      which do NOT fire SessionEnd. Source gating lives SERVER-side (the
+//      route decides which `source` values count as "closed") so it's
+//      unit-testable and so this half stays a dumb relay. Notably the route
+//      must NOT release on source `resume` (session suspended for
+//      `--resume`/`--continue`) or `clear` (`/clear`) — those mean the
+//      session lives on.
+//
+//   2. Engine session-end (new, HS-U618): records the WIP hand-off, releases
+//      the session's active claims, and exports its events — via
+//      `runSessionEnd()` below — by calling straight into
+//      spexharness/src/session-record.mjs's durable session store
+//      (`createSessionStore`'s `updateWip`/`releaseClaim`/`finishSession`)
+//      rather than re-deriving that logic here (epic scope: "the plugin's
+//      SessionEnd and Stop hooks as engine calls"). This only does anything
+//      for a session the harness itself bootstrapped (spexharness's
+//      `createSession`) — a plain Claude Code plugin session has no durable
+//      record, so `runSessionEnd` reads `null` and no-ops. Idempotent: a
+//      session already sealed (`endedAt` set) is read back as closed and
+//      skipped rather than re-recorded, so this hook firing twice for one
+//      session (a duplicate SessionEnd, a retried close) never double-writes.
+//
+// Both halves are independently fail-open — MUST exit 0 on every failure
+// path, a hook that breaks Claude Code is worse than a hook that silently
+// does nothing (mirrors emit-claim-status.mjs) — and neither half's failure
+// affects the other.
+//
+// Console URL resolution delegates to the ONE shared resolver
+// (scripts/lib/console-url-resolver.mjs, [[HS-GD45-MCPC-TASK]]) — MODE-AWARE
+// precedence ([[HS-VOJ7-YL1C-DIAG-console-url-resolver-ignores-dev-mode]]):
+// HEYSPEX_CONSOLE_URL env → ~/.heyspex/credentials.yaml `console_url` →
+// .heyspex/console-url discovery file (local reliance ONLY) → the console URL
+// derived from the resolved dev mode (cloud → https://app.heyspex.com).
+//
+// P9 (HS-U95M, plugin parity, epic [[HS-HEBV-8CMW-EPIC-spexcode-profile-v0-learn-the-developer]]):
+// a THIRD, independent half — after the console relay and the engine session-end above,
+// this hook also surfaces any P6 profile proposals still `pending` (never accepted or
+// declined) via spexharness/src/profile/proposals.mjs's own `listPending()` (thin shell,
+// never a second read of the ledger). The plugin's Stop/SessionEnd hook cannot run an
+// arrow-key select (`presentPendingProposal`, T15) the way an interactive SpexCode seat
+// can — this is a plain summary naming each pending item and how to act on it (`/profile
+// add|remove`, or the next SpexCode launch's own prompt). Absence of the ledger, or an
+// empty pending queue, produces no section and never throws — own failure boundary,
+// independent of the console-relay and engine halves, per this file's own header
+// contract ("Both halves are independently fail-open").
+
+import path from 'node:path';
+import http from 'node:http';
+import https from 'node:https';
+import { fileURLToPath } from 'node:url';
+
+import {
+  resolveConsoleUrl as resolveConsoleUrlShared,
+  DEFAULT_CONSOLE_URL,
+} from '../lib/console-url-resolver.mjs';
+// Bearer for /api/agent/session-end — same reader every other consumer uses, never
+// re-implemented and never printed.
+import { readCredentialsMcpToken } from '../lib/dev-mode.mjs';
+import {
+  appendSessionRecord,
+  createSessionStore,
+} from '../../spexharness/src/session-record.mjs';
+import {
+  defaultProposalsLedgerPath,
+  listPending,
+} from '../../spexharness/src/profile/proposals.mjs';
+
+const REQUEST_TIMEOUT_MS = 800;
+const ENGINE_TIMEOUT_MS = 1500;
+const PROPOSALS_TIMEOUT_MS = 500;
+
+function repoRoot() {
+  // session-end.mjs lives in scripts/claude-hooks/, so up two levels.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+// Stays fail-open (must exit 0 on every failure path, per the file-header
+// contract) but no longer fails SILENTLY: resolve in `strict` mode first so
+// an unresolved console URL logs loudly instead of quietly posting the release
+// to a guessed localhost:3000
+// ([[HS-OQ34-G59F-DIAG-console-url-silently-defaults-to]]). Since the resolver
+// became mode-aware this can only throw in LOCAL reliance (no
+// env/credentials/discovery-file match); cloud reliance always has a resolved
+// answer — the derived cloud console.
+function resolveConsoleUrl() {
+  try {
+    return resolveConsoleUrlShared({ repoRoot: repoRoot(), strict: true });
+  } catch {
+    console.error(
+      `[session-end] console URL unresolved in local reliance (no env/credentials/discovery-file ` +
+        `match) — guessing ${DEFAULT_CONSOLE_URL}. The release-claim POST may silently miss the real console.`,
+    );
+    return DEFAULT_CONSOLE_URL;
+  }
+}
+
+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);
+    });
+  });
+}
+
+function postSessionEnd(consoleUrl, body, token) {
+  return new Promise((resolve) => {
+    let url;
+    try {
+      url = new URL('/api/agent/session-end', consoleUrl);
+    } catch {
+      resolve();
+      return;
+    }
+    const transport = url.protocol === 'https:' ? https : http;
+    const payload = JSON.stringify(body);
+    const req = transport.request(
+      {
+        method: 'POST',
+        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),
+          ...(token ? { authorization: `Bearer ${token}` } : {}),
+        },
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+      (res) => {
+        res.on('data', () => {});
+        res.on('end', resolve);
+        res.on('error', resolve);
+      },
+    );
+    req.on('error', resolve);
+    req.on('timeout', () => {
+      req.destroy();
+      resolve();
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+/* ============================================================================================
+ * Engine session-end (HS-U618) — record WIP, release claims, export events, idempotently.
+ * ============================================================================================ */
+
+/** Where the local (network-free) events export lands — one JSONL line per session close. */
+export function sessionEventsExportPath(root = repoRoot()) {
+  return path.join(root, '.heyspex', 'session-end-events.jsonl');
+}
+
+/**
+ * Default `exporter`: appends the session's events + tool-call log to a local JSONL file via
+ * session-record.mjs's own `appendSessionRecord` (same line-atomic append the harness uses for
+ * its own per-machine records) — no network, no Neon, so this half never depends on the console
+ * being reachable.
+ *
+ * @param {{ root?: string }} [opts]
+ * @returns {{ export: (sessionId: string, data: { events?: Array, toolCalls?: Array }) => Promise<object> }}
+ */
+export function createLocalEventsExporter({ root = repoRoot() } = {}) {
+  const filePath = sessionEventsExportPath(root);
+  return {
+    async export(sessionId, { events = [], toolCalls = [] } = {}) {
+      const record = { sessionId, exportedAt: new Date().toISOString(), events, toolCalls };
+      appendSessionRecord(filePath, record);
+      return { filePath, eventCount: events.length, toolCallCount: toolCalls.length };
+    },
+  };
+}
+
+/**
+ * Default `ledger`: wraps a spexharness durable session store's `getSession` /
+ * `updateWip` / `finishSession` — reused, not re-derived. `getSession` fails soft to `null`
+ * (no durable record for this session — most Claude Code plugin sessions today, since nothing
+ * yet calls the store's `createSession` for them — or storage genuinely unreachable) so the
+ * caller can no-op rather than throw.
+ *
+ * @param {ReturnType<typeof createSessionStore>} store
+ */
+export function createStoreLedger(store) {
+  return {
+    async getSession(sessionId) {
+      try {
+        return await store.getSession(sessionId);
+      } catch {
+        return null;
+      }
+    },
+    async recordWip(sessionId, wip) {
+      await store.updateWip(sessionId, wip);
+      return store.finishSession(sessionId, null);
+    },
+  };
+}
+
+/**
+ * Default `claims`: releases every claim the store has on record for this session, by reading
+ * the session's own `claims` array and calling the store's `releaseClaim` for each — the store's
+ * existing claim bookkeeping, not a second copy of it.
+ *
+ * @param {ReturnType<typeof createSessionStore>} store
+ */
+export function createStoreClaims(store) {
+  return {
+    async release(sessionId) {
+      let existing;
+      try {
+        existing = await store.getSession(sessionId);
+      } catch {
+        return [];
+      }
+      const specIds = (existing?.claims ?? []).map((c) => c?.specId).filter(Boolean);
+      for (const specId of specIds) {
+        await store.releaseClaim(sessionId, specId);
+      }
+      return specIds;
+    },
+  };
+}
+
+/**
+ * Build the production `{ ledger, claims, exporter }` deps {@link runSessionEnd} takes. One
+ * store backs both `ledger` and `claims` so a real close does one connection's worth of work,
+ * not two. `backend`/`root` are injection points for tests (an in-memory session backend, a
+ * scratch events-export dir) — omitted, `ledger`/`claims` default to the real Neon-backed store
+ * (lazy: no connection opens until a method is actually called) and `exporter` writes under the
+ * real repo's `.heyspex/`.
+ *
+ * @param {{ backend?: object, root?: string }} [opts]
+ */
+export function buildDefaultDeps({ backend = undefined, root = undefined } = {}) {
+  const store = createSessionStore(backend ? { backend } : {});
+  return {
+    ledger: createStoreLedger(store),
+    claims: createStoreClaims(store),
+    exporter: createLocalEventsExporter(root ? { root } : {}),
+  };
+}
+
+/**
+ * The engine session-end core (HS-U618 AC1-4): records the WIP hand-off, releases the session's
+ * active claims, and exports its events — exactly once per session id.
+ *
+ * Idempotent by design: a session the ledger already reports `endedAt` on is read back as
+ * already-closed and none of the three actions run again, so a duplicate SessionEnd (or a
+ * retried close) never double-records. A session id the ledger has no record for at all (the
+ * common case for a plain Claude Code plugin session, which nothing yet bootstraps through the
+ * harness's durable store) is likewise a no-op — there is nothing this routine can close.
+ *
+ * @param {{ sessionId: string, source?: string|null, wip?: unknown }} input
+ * @param {{
+ *   ledger: { getSession: (id: string) => Promise<object|null>, recordWip: (id: string, wip: unknown) => Promise<object> },
+ *   claims: { release: (id: string) => Promise<string[]> },
+ *   exporter: { export: (id: string, data: { events?: Array, toolCalls?: Array }) => Promise<object> },
+ * }} deps injectable — tests pass fakes (or the real pieces above over an in-memory backend), so
+ *   this never needs a reachable console or a live Neon connection to prove its contract.
+ * @returns {Promise<object>} a receipt describing what happened.
+ */
+export async function runSessionEnd({ sessionId, source = null, wip = null } = {}, deps) {
+  if (!sessionId) return { closed: false, reason: 'missing_session_id' };
+  const { ledger, claims, exporter } = deps;
+
+  const existing = await ledger.getSession(sessionId);
+  if (!existing) return { closed: false, reason: 'no_session_record', sessionId };
+  if (existing.endedAt) return { closed: false, reason: 'already_closed', sessionId };
+
+  const wipReceipt = await ledger.recordWip(sessionId, wip ?? existing.wip ?? null);
+  const releasedClaims = await claims.release(sessionId, { source });
+  const exportReceipt = await exporter.export(sessionId, {
+    events: existing.events ?? [],
+    toolCalls: existing.toolCalls ?? [],
+  });
+
+  return {
+    closed: true,
+    sessionId,
+    wip: { endedAt: wipReceipt?.endedAt ?? null, value: wipReceipt?.wip ?? null },
+    releasedClaims,
+    exported: exportReceipt,
+  };
+}
+
+/* ============================================================================================
+ * Pending profile proposals (HS-U95M, P9) — a third, independent half.
+ * ============================================================================================ */
+
+/**
+ * Render the P6 pending-proposals queue into the plain-text summary this hook prints for
+ * the developer. Thin shell over spexharness/src/profile/proposals.mjs's own `listPending`
+ * — never a second read or fold of the ledger. Returns `null` (no proposal section, AC2)
+ * when there is nothing pending, or when the ledger cannot be read at all (missing file,
+ * corrupt content) — a broken read must never surface as an error, only as silence.
+ *
+ * @param {{ ledgerPath: string, listPendingFn?: typeof listPending }} opts
+ * @returns {string|null}
+ */
+export function renderPendingProposalsSummary({ ledgerPath, listPendingFn = listPending }) {
+  let pending;
+  try {
+    pending = listPendingFn({ ledgerPath });
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(pending) || pending.length === 0) return null;
+
+  const count = pending.length;
+  const lines = [
+    `SpexCode Profile — ${count} pending observation${count === 1 ? '' : 's'} waiting for a decision:`,
+  ];
+  pending.forEach((proposal, i) => {
+    const obs = proposal?.observation ?? {};
+    const text = typeof obs.text === 'string' && obs.text.trim() ? obs.text.trim() : '(no text)';
+    lines.push(
+      `  ${i + 1}. ${text} _(source: ${obs.source ?? 'unknown'}, project: ${obs.project ?? 'unknown'}, session: ${obs.session ?? 'unknown'})_`,
+    );
+  });
+  lines.push(
+    'Act on these with `/profile add` / `/profile remove`, or you will be asked again the next time SpexCode launches.',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * The proposals half's own dependency bundle — `root` defaults to this repo's real root
+ * (production), but a test passes a scratch `root` so the ledger never touches
+ * `~/.heyspex` or this repo's own `.heyspex/` store.
+ *
+ * @param {{ root?: string }} [opts]
+ */
+export function defaultProposalsDeps({ root = repoRoot() } = {}) {
+  return { ledgerPath: defaultProposalsLedgerPath(root) };
+}
+
+/**
+ * Print the pending-proposals summary to `stdout`, if there is one. Own failure boundary —
+ * this must never throw, and never affects the console relay or the engine half above.
+ *
+ * @param {{ ledgerPath: string }} deps
+ * @param {{ write: (chunk: string) => unknown }} [stdout]
+ * @returns {Promise<string|null>} the summary printed, or null when there was none.
+ */
+export async function reportPendingProposals(deps, stdout = process.stdout) {
+  try {
+    const summary = renderPendingProposalsSummary(deps);
+    if (summary) stdout.write(`${summary}\n`);
+    return summary;
+  } catch {
+    return null;
+  }
+}
+
+/** Race a promise against a timeout so the engine half can never stall the hook's own exit. */
+function withTimeout(promise, ms, fallback) {
+  return Promise.race([
+    promise,
+    new Promise((resolve) => setTimeout(() => resolve(fallback), ms)),
+  ]);
+}
+
+async function main() {
+  const stdinRaw = await readStdin();
+  let payload = null;
+  if (stdinRaw) {
+    try {
+      payload = JSON.parse(stdinRaw);
+    } catch {
+      // Non-JSON stdin — nothing actionable.
+    }
+  }
+
+  const sessionId =
+    payload?.session_id ??
+    payload?.conversation_id ??
+    process.env.CLAUDE_CODE_SESSION_ID ??
+    process.env.CURSOR_TRACE_ID ??
+    process.env.CURSOR_SESSION_ID ??
+    process.env.COMPOSER_SESSION_ID;
+  if (!sessionId) return;
+
+  // `source` may be absent on some payloads; forward what we have and let the
+  // server gate. (When absent, the server treats it as a non-closing event.)
+  const source = typeof payload?.source === 'string' ? payload.source : undefined;
+
+  await postSessionEnd(
+    resolveConsoleUrl(),
+    { session_id: sessionId, source },
+    readCredentialsMcpToken(),
+  );
+
+  // Engine half (HS-U618) — independent of the relay above, own failure boundary, own
+  // timeout, never allowed to affect this hook's exit code.
+  await withTimeout(
+    runSessionEnd({ sessionId, source }, buildDefaultDeps()).catch(() => null),
+    ENGINE_TIMEOUT_MS,
+    null,
+  );
+
+  // Pending profile proposals half (HS-U95M, P9) — independent of both halves above, own
+  // failure boundary, own timeout. No-op (prints nothing) when nothing is pending.
+  await withTimeout(
+    reportPendingProposals(defaultProposalsDeps()).catch(() => null),
+    PROPOSALS_TIMEOUT_MS,
+    null,
+  );
+}
+
+// Entry-guard: run main() only when executed as the hook, NOT when imported — the test file
+// imports runSessionEnd/buildDefaultDeps/createLocalEventsExporter/createStoreLedger/
+// createStoreClaims to unit-test the engine half with injected fakes, and importing this module
+// must never itself read stdin or make a network/DB call. Mirrors preflight-reminder.mjs.
+const INVOKED_DIRECTLY =
+  !!process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (INVOKED_DIRECTLY) {
+  main().catch(() => {
+    // Swallow — never break Claude Code on a hook failure.
+  });
+}

package/scripts/claude-hooks/settings-write-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/settings-write-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/settings-write-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/settlement-check-gate.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// settlement-check-gate.mjs — thin CLI shell around the pure
+// evaluateSessionSettlement() decision ([[HS-N33D-CWPX-TASK-settlement-check-before-stop-companion]]).
+//
+// NOT WIRED into .claude/settings.json's live `Stop` hook array by this task
+// (deliberately — that array governs THIS session's own Stop event, and
+// wiring an unvalidated new gate into it live is a self-referential risk).
+// This script is the thin shell a follow-up task can point a Stop hook at
+// once validated outside an active session: it resolves the real signals
+// (a settlement/drain status file, whether SpexCompanion's heartbeat is
+// recent, whether git shows uncommitted changes) and prints the pure
+// evaluator's verdict as JSON. Untested by design — the pure-core/thin-shell
+// split ([[unit-test-authoring-protocol]] §1) puts all the tested logic in
+// session-settlement-check.mjs; this file only wires real inputs to it.
+//
+// Usage (once wired as a Stop hook):
+//   node scripts/claude-hooks/settlement-check-gate.mjs
+//
+// Signals are read from environment variables so a hook runner (or a human,
+// for now) can supply them without this script reaching into git/Companion
+// state itself — that wiring is the follow-up task's job, not this one's.
+
+import { evaluateSessionSettlement } from "../lib/session-settlement-check.mjs";
+
+function boolEnv(name) {
+  return process.env[name] === "1" || process.env[name] === "true";
+}
+
+const result = evaluateSessionSettlement({
+  hasUnsettledWrites: boolEnv("HEYSPEX_HAS_UNSETTLED_WRITES"),
+  drainTriggeredImmediately: boolEnv("HEYSPEX_DRAIN_TRIGGERED_IMMEDIATELY"),
+  diskEditsThisSession: boolEnv("HEYSPEX_DISK_EDITS_THIS_SESSION"),
+  companionRunning: boolEnv("HEYSPEX_COMPANION_RUNNING"),
+});
+
+process.stdout.write(`${JSON.stringify(result)}\n`);
+// Exit 0 always — this script is report-only until a follow-up task decides
+// how a fired tripwire should affect the Stop hook's own exit code.
+process.exit(0);

package/scripts/claude-hooks/status-flip-detect.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Back-compat re-exports — prefer terminal-close-shared.mjs for new code.
+
+export {
+  STATUS_REVIEW_RE,
+  armPendingTerminalClose,
+  clearPendingTerminalClose,
+  detectShipFromEditLike as detectFlip,
+  isPendingTerminalCloseArmed,
+  isRecordWipSuccess,
+  isSessionEndEvent,
+  isShipEvent as isPostToolUseShipEvent,
+  pendingTerminalClosePath,
+  readStdin,
+  repoRoot,
+  resolveCloseTerminalOnTaskCompleteFromSettings,
+} from './terminal-close-shared.mjs';