heyspex 0.1.0 → 0.2.0

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

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+// HeySpex Intent Classifier — SEMANTIC layer.
+//
+// The Intent Classifier has two layers ([[HS-UJVA-EPIC-KKMO-autonomous-skill-routing-context]]):
+//   1. LEXICAL (fast path) — the per-rule regex patterns in the guardrail registry.
+//      A regex hit fires instantly and never waits on this module.
+//   2. SEMANTIC — on a regex MISS, resolve intent WITHOUT a second, separate model.
+//      DEFAULT (mode: self_check, [[HS-M4PN-TASK]]): the router deterministically
+//      injects a SELF-CHECK instruction and lets the agent already running the session
+//      judge intent as part of its own turn — no network, no fleet machine, works for
+//      every user. The self-check block is built in _intent-classifier-router.mjs;
+//      this module is the OPT-IN model fallback for anyone who still wants it.
+//      Why the semantic layer exists at all (regex alone is not enough):
+//      [[intent-classifier-injected-content]] — 9/10 paraphrased improvement-idea
+//      phrasings missed before the patterns were broadened, and paraphrase drift
+//      never ends.
+//
+// OPT-IN MODEL FALLBACK (mode: model): classifyIntent() below classifies the prompt
+// with a fast LOCAL model (Ollama) and returns { behavior, confidence } so the caller
+// can fire above a threshold. This is the ORIGINAL mechanism, now DEMOTED to an
+// explicit opt-in — it is NEVER on the default path, so no reachable endpoint is
+// required for the semantic layer to function ([[HS-M4PN-TASK]] AC2).
+//
+// HARD FAIL-SAFE CONTRACT (hook house rules): this module NEVER throws, NEVER
+// hangs past its timeout, and on ANY problem (endpoint down, timeout, bad JSON,
+// unexpected shape) returns { behavior: null, confidence: 0 } so the calling hook
+// proceeds exactly as if the semantic layer did not exist. Dependency-free:
+// Node stdlib + global fetch only (hooks run on a fresh clone with no npm install).
+//
+// Config (.heyspex/config.yaml → agent_behaviors.intent_classifier.*), all optional.
+// The file is read from the VAULT root (the loader's `defaultConfigRoot()`), not this
+// checkout — [[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]:
+//   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)
+//   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)
+// Env overrides (kill switch first):
+//   HEYSPEX_INTENT_SEMANTIC_OFF=1      hard off (disables Layer 2 entirely)
+//   HEYSPEX_INTENT_SEMANTIC_MODE=self_check|model
+//   HEYSPEX_INTENT_ENDPOINT / HEYSPEX_INTENT_MODEL /
+//   HEYSPEX_INTENT_TIMEOUT_MS / HEYSPEX_INTENT_MIN_CONFIDENCE
+//
+// Self-test without a session (exercises the opt-in model fallback):
+//   node scripts/claude-hooks/_intent-classifier-semantic.mjs --ping
+//   node scripts/claude-hooks/_intent-classifier-semantic.mjs --classify "some prompt"
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { readConfigLeafRaw } from './_guardrail-loader.mjs';
+import { defaultConfigRoot } from '../../spexharness/src/config-root.mjs';
+
+// The CODE checkout — where `.heyspex/intent-classifier-history.jsonl` (an event
+// log, a code-repo artifact) is appended. NOT where config.yaml is read from: the
+// config reads below default to the vault root via `defaultConfigRoot()`
+// ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+export const DEFAULT_REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+// Semantic-layer modes ([[HS-M4PN-TASK]]):
+//   'self_check' — DEFAULT. On a regex miss the router injects a deterministic
+//                  self-check instruction; the session's own agent judges intent.
+//                  No network, no fleet machine.
+//   'model'      — OPT-IN fallback. classifyIntent() calls the local Ollama endpoint.
+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',
+  model: 'qwen3:8b',
+  timeoutMs: 2500,
+  minConfidence: 0.7,
+});
+
+// The behavior catalog the classifier chooses from. Descriptions are the actual
+// classification instructions, so keep them about the USER'S INTENT, not the
+// system's response. Any hook can pass its own list; this shared catalog keeps
+// capture-trigger and research-trigger consistent if both adopt the semantic layer.
+export const KNOWN_BEHAVIORS = Object.freeze([
+  {
+    key: 'capture_on_idea',
+    description:
+      'The user is sharing a raw idea, suggestion, observation, or improvement thought — a brain-dump about something that could exist or be better — rather than giving a direct work order, asking a question about existing work, or continuing work already in progress.',
+  },
+  {
+    key: 'research_before_decision',
+    description:
+      'The user is declining to make a design or architecture decision themselves and is asking for research, best practices, or an expert recommendation instead (e.g. "not a decision I should have to make", "don\'t reinvent the wheel").',
+  },
+  {
+    key: 'settings_intent',
+    description:
+      'The user wants to READ or CHANGE a HeySpex workflow setting / agent behavior — enable or disable a behavior (auto-capture, the research trigger, the intent classifier), turn something on or off, set/lower/raise a threshold or value (confidence, timeout), or ask what a setting is currently. About the configuration itself, NOT a request to do the underlying work. (e.g. "turn off auto-capture", "lower the classifier confidence to 0.6", "is auto-capture on", "make it stop capturing everything").',
+  },
+  {
+    key: 'defer_intent',
+    description:
+      'The user wants to DEFER, POSTPONE, or SCHEDULE a follow-up to a later time — "come back to this later", "remind me in a week", "park/table this until X is done", "schedule this for next week", "not now — later, after the migration". About WHEN to revisit something, not a request to do it now.',
+  },
+]);
+
+function num(raw, fallback) {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function clamp01(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(1, v));
+}
+
+/**
+ * Resolve the semantic-layer config: env override → .heyspex/config.yaml →
+ * shipped defaults. FAIL-SAFE: any unreadable value falls back to its default.
+ * `repoRoot` is the directory holding `.heyspex/config.yaml` — defaults to the
+ * vault root; an explicit argument (tests, fixtures) always wins.
+ */
+export function readIntentClassifierConfig(repoRoot = defaultConfigRoot()) {
+  const cfg = { ...DEFAULTS };
+  try {
+    if (process.env.HEYSPEX_INTENT_SEMANTIC_OFF === '1') cfg.semanticEnabled = false;
+    else {
+      const enabled = readConfigLeafRaw('agent_behaviors.intent_classifier.semantic_enabled', repoRoot);
+      if (enabled !== undefined) cfg.semanticEnabled = enabled.trim().toLowerCase() !== 'false';
+    }
+    // Mode: env override → config → default 'self_check'. Any unrecognized value
+    // falls back to the deterministic default rather than silently enabling the model.
+    const modeRaw =
+      process.env.HEYSPEX_INTENT_SEMANTIC_MODE ||
+      unquote(readConfigLeafRaw('agent_behaviors.intent_classifier.mode', repoRoot));
+    if (typeof modeRaw === 'string') {
+      const m = modeRaw.trim().toLowerCase();
+      if (SEMANTIC_MODES.includes(m)) cfg.semanticMode = m;
+    }
+    const endpoint =
+      process.env.HEYSPEX_INTENT_ENDPOINT ||
+      unquote(readConfigLeafRaw('agent_behaviors.intent_classifier.endpoint', repoRoot));
+    if (endpoint && /^https?:\/\//.test(endpoint)) cfg.endpoint = endpoint.replace(/\/+$/, '');
+    const model =
+      process.env.HEYSPEX_INTENT_MODEL ||
+      unquote(readConfigLeafRaw('agent_behaviors.intent_classifier.model', repoRoot));
+    if (model) cfg.model = model;
+    cfg.timeoutMs = num(
+      process.env.HEYSPEX_INTENT_TIMEOUT_MS ??
+        readConfigLeafRaw('agent_behaviors.intent_classifier.timeout_ms', repoRoot),
+      DEFAULTS.timeoutMs,
+    );
+    const minConf = Number(
+      process.env.HEYSPEX_INTENT_MIN_CONFIDENCE ??
+        readConfigLeafRaw('agent_behaviors.intent_classifier.min_confidence', repoRoot),
+    );
+    if (Number.isFinite(minConf) && minConf > 0 && minConf <= 1) cfg.minConfidence = minConf;
+  } catch {
+    return { ...DEFAULTS };
+  }
+  return cfg;
+}
+
+function unquote(raw) {
+  if (typeof raw !== 'string') return undefined;
+  const v = raw.trim();
+  const m = v.match(/^"(.*)"$/) || v.match(/^'(.*)'$/);
+  return m ? m[1] : v || undefined;
+}
+
+function buildSystemPrompt(behaviors) {
+  const rows = behaviors
+    .map((b) => `- ${b.key}: ${b.description}`)
+    .join('\n');
+  return (
+    'You classify ONE user message from a coding-agent session into exactly one behavior key, or "none" ' +
+    'when no behavior applies. Behaviors:\n' +
+    rows +
+    '\n- none: a direct work order, a question about existing work, a bug report to fix now, small talk, or anything else.\n' +
+    'Reply with STRICT JSON only, no prose: {"behavior":"<one key above or none>","confidence":<number 0..1>}'
+  );
+}
+
+/**
+ * Classify a prompt into one of the given behaviors via the local Ollama endpoint.
+ *
+ * @param {string} prompt              the user's message
+ * @param {{key:string, description:string}[]} behaviors  candidate behaviors (defaults to KNOWN_BEHAVIORS)
+ * @param {object} [opts]              { endpoint, model, timeoutMs, repoRoot } — omitted values come from config
+ * @returns {Promise<{behavior: string|null, confidence: number, latencyMs?: number, error?: string}>}
+ *   behavior is null when nothing matched OR anything failed (fail-safe).
+ */
+export async function classifyIntent(prompt, behaviors = KNOWN_BEHAVIORS, opts = {}) {
+  const none = { behavior: null, confidence: 0 };
+  try {
+    if (typeof prompt !== 'string' || !prompt.trim()) return none;
+    const list = Array.isArray(behaviors) && behaviors.length ? behaviors : KNOWN_BEHAVIORS;
+    const cfg = readIntentClassifierConfig(opts.repoRoot ?? defaultConfigRoot());
+    const endpoint = opts.endpoint ?? cfg.endpoint;
+    const model = opts.model ?? cfg.model;
+    const timeoutMs = num(opts.timeoutMs, cfg.timeoutMs);
+
+    // Very short prompts carry no classifiable intent; very long ones are truncated
+    // to keep the local model inside the latency budget.
+    const text = prompt.trim().slice(0, 2000);
+    if (text.length < 12) return none;
+
+    // Optional call counter (proof/observability): when HEYSPEX_INTENT_CALL_LOG names
+    // a file, append one byte per model call so a test can assert exactly ≤1 call per
+    // prompt. Fail-safe: never let instrumentation break the classifier.
+    if (process.env.HEYSPEX_INTENT_CALL_LOG) {
+      try {
+        fs.appendFileSync(process.env.HEYSPEX_INTENT_CALL_LOG, `${new Date().toISOString()} ${model}\n`);
+      } catch {
+        /* ignore */
+      }
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const t0 = Date.now();
+    let res;
+    try {
+      res = await fetch(`${endpoint}/api/chat`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        signal: controller.signal,
+        body: JSON.stringify({
+          model,
+          stream: false,
+          format: 'json',
+          think: false, // qwen3: skip the reasoning preamble; harmless no-op elsewhere
+          keep_alive: '30m', // keep the classifier warm between prompts
+          options: { temperature: 0, num_predict: 120 },
+          messages: [
+            { role: 'system', content: buildSystemPrompt(list) },
+            { role: 'user', content: text },
+          ],
+        }),
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const latencyMs = Date.now() - t0;
+    if (!res || !res.ok) return { ...none, latencyMs, error: `http_${res?.status ?? 'no_response'}` };
+
+    const payload = await res.json().catch(() => null);
+    const content = payload?.message?.content;
+    if (typeof content !== 'string' || !content.trim()) return { ...none, latencyMs, error: 'empty_response' };
+
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      // Defensive: some models wrap JSON in text — try the first {...} span.
+      const m = content.match(/\{[\s\S]*\}/);
+      if (!m) return { ...none, latencyMs, error: 'unparseable_response' };
+      try {
+        parsed = JSON.parse(m[0]);
+      } catch {
+        return { ...none, latencyMs, error: 'unparseable_response' };
+      }
+    }
+
+    const rawBehavior = typeof parsed?.behavior === 'string' ? parsed.behavior.trim() : '';
+    const confidence = clamp01(parsed?.confidence);
+    const valid = list.some((b) => b.key === rawBehavior);
+    if (!valid || rawBehavior === 'none') return { behavior: null, confidence, latencyMs };
+    return { behavior: rawBehavior, confidence, latencyMs };
+  } catch (err) {
+    const error = err?.name === 'AbortError' ? 'timeout' : 'unreachable';
+    return { ...none, error };
+  }
+}
+
+/**
+ * Append one classifier-decision row to .heyspex/intent-classifier-history.jsonl.
+ * Called by the hooks for FIRES (either layer), semantic NEAR-MISSES (matched
+ * behavior below threshold), and semantic ERRORS — never for the ordinary
+ * regex-miss/no-match case, so the log stays small. FAIL-SAFE: never throws.
+ */
+export function appendClassifierEvent(row, repoRoot = DEFAULT_REPO_ROOT) {
+  try {
+    const full = {
+      timestamp: new Date().toISOString(),
+      event_kind: 'intent_classifier.decision',
+      ...row,
+    };
+    fs.appendFileSync(
+      path.join(repoRoot, '.heyspex', 'intent-classifier-history.jsonl'),
+      JSON.stringify(full) + '\n',
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── self-test CLI (no session required) ─────────────────────────────────────
+
+async function ping() {
+  const cfg = readIntentClassifierConfig();
+  const out = { config: cfg, reachable: false, version: null, classify: null };
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), cfg.timeoutMs);
+    const res = await fetch(`${cfg.endpoint}/api/version`, { signal: controller.signal });
+    clearTimeout(timer);
+    if (res.ok) {
+      out.reachable = true;
+      out.version = (await res.json().catch(() => null))?.version ?? null;
+    }
+  } catch {
+    /* stays unreachable */
+  }
+  if (out.reachable) {
+    out.classify = await classifyIntent(
+      "it'd be smart to let the app notice ideas on its own",
+      KNOWN_BEHAVIORS,
+    );
+  }
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  process.exit(out.reachable && out.classify?.behavior === 'capture_on_idea' ? 0 : 1);
+}
+
+async function classifyCli(text) {
+  const result = await classifyIntent(text, KNOWN_BEHAVIORS);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  process.exit(0);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  if (process.argv.includes('--ping')) {
+    ping();
+  } else {
+    const idx = process.argv.indexOf('--classify');
+    if (idx !== -1 && process.argv[idx + 1]) {
+      classifyCli(process.argv[idx + 1]);
+    } else if (process.argv.length > 2) {
+      process.stdout.write(
+        'Usage: node _intent-classifier-semantic.mjs --ping | --classify "<text>"\n',
+      );
+      process.exit(2);
+    }
+  }
+}

package/scripts/claude-hooks/_run.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// _run.mjs — the single chokepoint every HeySpex Claude Code hook runs through.
+//
+// `.claude/settings.json` never names a hook script directly. It names this
+// shim plus the hook to run:
+//
+//   node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs" wip-checkpoint
+//   node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs" emit-claim-status --event=Stop
+//
+// The shim asks one question — is HeySpex on? — and either exits 0 immediately
+// or hands off to the real hook. One place to reason about, and a hook added
+// tomorrow inherits the off-switch for free.
+//
+// Delegation is a dynamic `import()` in THIS process, not a subprocess, so the
+// hook still owns stdin (Claude Code pipes the event payload there) and still
+// sets this process's exit code. `process.argv` is rewritten first so a hook
+// reading `--event=Stop` sees exactly what it saw before the shim existed.
+//
+// Everything here is fail-open. A shim that throws must never take down a
+// Claude Code session, and it must never be the reason a guardrail silently
+// stops firing — so an unresolvable mode reads as ON, and a genuinely broken
+// hook path reports on stderr and exits 0.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const HOOK_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HOOK_DIR, '..', '..');
+
+const [target, ...rest] = process.argv.slice(2);
+
+if (!target) {
+  process.stderr.write('[heyspex] _run.mjs: no hook name given\n');
+  process.exit(0);
+}
+
+/**
+ * Resolve the hook to run.
+ *   `wip-checkpoint`               → scripts/claude-hooks/wip-checkpoint.mjs
+ *   `scripts/stamp-provenance.mjs` → <repo>/scripts/stamp-provenance.mjs
+ *
+ * A bare name is constrained to a safe charset and must land inside the hook
+ * directory; a path form is resolved from the repo root and must stay inside
+ * it. Both guards exist so a mangled settings.json can't turn the shim into an
+ * arbitrary-script runner.
+ */
+function resolveHook(name) {
+  const abs = name.includes('/') || name.includes('\\')
+    ? path.resolve(REPO_ROOT, name)
+    : /^[A-Za-z0-9._-]+$/.test(name)
+      ? path.join(HOOK_DIR, name.endsWith('.mjs') ? name : `${name}.mjs`)
+      : null;
+  if (!abs) return null;
+  const inRepo = path.relative(REPO_ROOT, abs);
+  if (inRepo.startsWith('..') || path.isAbsolute(inRepo)) return null;
+  return abs;
+}
+
+// --- the off-switch -------------------------------------------------------
+// Inlined rather than imported from scripts/heyspex-mode.mjs: this runs on
+// every tool call in every session, and a resolve+parse of another module is
+// real latency for a question answered by one small file read. The two must
+// agree — see the resolution order documented in heyspex-mode.mjs.
+function heyspexIsOff() {
+  try {
+    const raw = String(process.env.HEYSPEX_MODE ?? '').trim().toLowerCase();
+    if (raw) return ['off', '0', 'false', 'disabled', 'disable', 'no'].includes(raw);
+    const state = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, '.heyspex', 'mode.json'), 'utf8'));
+    return state?.mode === 'off';
+  } catch {
+    return false; // fail-open: HeySpex is on unless something says otherwise
+  }
+}
+
+// --- hooks the off-switch may NOT silence ---------------------------------
+// The productivity hooks (reminders, injections, checkpoints) exist to help,
+// so a global "HeySpex is off" is the right answer for them. A SECURITY
+// control is different: the mode is decided by a repo file (.heyspex/mode.json)
+// that any agent can write, and nothing guards that file — so sharing the
+// off-switch would mean "write one JSON file, disarm the guard forever"
+// (the disarm chain, C8). Anything named here runs regardless of mode.
+// Each always-on hook keeps its OWN documented escape hatch, and it must be
+// an ENV VAR (HEYSPEX_ENV_VAULT_GUARD_OFF=1 for env-vault-guard;
+// HEYSPEX_RESEARCH_GUARD_OFF=1 for research-method-guard) — a human setting a
+// variable for their session, not a file an agent can create.
+// research-protocol-gate ([[HS-K0ZP]]) joins the set for the same reason as
+// research-method-guard: its whole point is that the agent cannot switch it
+// off. Escape hatch: HEYSPEX_RESEARCH_PROTOCOL_GATE_OFF=1, owner-set, env only.
+// git-identity-guard (owner ruling 2026-09-19, vault lesson
+// when-git-says-author-identity-unknown) has NO escape hatch at all — not
+// even an env var: the owner's own path is `hs source identity set`, typed by
+// a human, so there is nothing a hatch would enable that the sanctioned form
+// does not already do. Agents read git identity; they never write it.
+const ALWAYS_ON = new Set(['env-vault-guard', 'research-method-guard', 'research-protocol-gate', 'git-identity-guard']);
+
+function isAlwaysOn(name) {
+  const base = String(name)
+    .replace(/^.*[\\/]/, '')
+    .replace(/\.mjs$/i, '');
+  return ALWAYS_ON.has(base);
+}
+
+if (!isAlwaysOn(target) && heyspexIsOff()) process.exit(0);
+
+const hookPath = resolveHook(target);
+if (!hookPath || !fs.existsSync(hookPath)) {
+  process.stderr.write(`[heyspex] _run.mjs: hook not found: ${target}\n`);
+  process.exit(0);
+}
+
+// Make the hook believe it was invoked directly.
+process.argv = [process.argv[0], hookPath, ...rest];
+
+try {
+  await import(pathToFileURL(hookPath).href);
+} catch (err) {
+  process.stderr.write(`[heyspex] hook ${target} failed: ${err?.message ?? err}\n`);
+  process.exit(0);
+}

package/scripts/claude-hooks/_transcript-text.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Shared Stop-hook input helpers: read the hook's stdin JSON payload and pull the
+// agent's own last message out of the transcript JSONL. Split out of
+// naughty-list-gate.mjs (its original sole owner) so a second Stop-hook scanner
+// (id-display-format-gate.mjs) doesn't fork a copy of the same 40 lines.
+//
+// DEPENDENCY-FREE, same contract as _guardrail-loader.mjs: every function degrades
+// to null/'' on any read/parse failure rather than throwing, so a caller's own
+// fail-safe wrapper never has to guard against this module misbehaving.
+
+import fs from 'node:fs';
+
+/** Read and parse the hook's stdin JSON payload. Resolves to null on any failure. */
+export async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || ''), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { buf += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); finish(buf); });
+    process.stdin.on('error', () => { clearTimeout(timer); finish(buf); });
+  });
+}
+
+/** Read the last assistant message's text out of a transcript JSONL file. */
+export function lastAssistantText(transcriptPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = raw.split(/\r?\n/).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let evt;
+    try { evt = JSON.parse(lines[i]); } catch { continue; }
+    const msg = evt?.message;
+    const role = msg?.role ?? evt?.role;
+    if (role !== 'assistant') continue;
+    const content = msg?.content;
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+      const text = content
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('\n')
+        .trim();
+      return text || null;
+    }
+    return null;
+  }
+  return null;
+}