kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/Ansuz/tools/ansuz-handoff-snapshot.js

@@ -0,0 +1,626 @@
+#!/usr/bin/env node
+/**
+ * ansuz-handoff-snapshot.js — Live Handoff Write CLI (TASK_1400)
+ *
+ * Snapshot tool that auto-builds ISBAR JSON from available context and atomically
+ * writes to the per-session handoff slot at .kenaz/specialist/handoffs/<sessionId>.json
+ * (M3 migration, TASK_1760). The legacy single slot
+ * .kenaz/specialist/ansuz_session_handoff.json is read-only back-compat for readers.
+ *
+ * CLI:
+ *   node ansuz-handoff-snapshot.js --trigger=<trigger> [--last-milestone=<text>] [--project-path=<path>]
+ *     [--session-id=<id>] [--transcript-path=<conversation.jsonl>]  (transcript scopes task lists to this conversation)
+ *
+ * Triggers: live_dispatch_milestone | live_phase_exit | live_decision_point | manual
+ *
+ * Sources (in order, best-effort):
+ *   (a) Last 10 git commits + working tree diff stat
+ *   (b) Recent task transitions from .kenaz/tasks/{status}/
+ *   (c) Current session_id from .kenaz/specialist/ansuz_session.json
+ *
+ * Output: prints handoff_path + session_id + rune_ids summary on success.
+ * Exit non-zero on schema validation failure (prior valid handoff untouched).
+ *
+ * Also require()-able as a module (TASK_1837): exports HANDOFF_STALE_AFTER_MS /
+ * FRESHNESS_WINDOW_MS as the single timing authority consumed by
+ * .claude/hooks/handoff-staleness.js. main() runs only under require.main.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+// Shared project identity resolver (TASK_1701): consults session-keyed pin file so
+// handoffs land in the correct project without requiring --project-path on every call.
+const projectResolver = require('../../tools/lib/project-resolver');
+
+// ─────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────
+
+const VALID_TRIGGERS = [
+  'live_dispatch_milestone',
+  'live_phase_exit',
+  'live_decision_point',
+  'manual',
+];
+
+// Handoff timing authority (TASK_1837; repair pattern from TASK_1838's
+// dispatchLockStaleness). HANDOFF_STALE_AFTER_MS is THE single threshold: a slot
+// older than this is stale, and the staleness hook
+// (.claude/hooks/handoff-staleness.js) require()s it from this module to decide
+// when to nudge. FRESHNESS_WINDOW_MS — how recent an existing slot must be for
+// this writer to refuse an auto-rewrite — is DERIVED from it, never held as an
+// independent constant: anything the hook calls stale, this writer must be
+// willing to rewrite. Two independent constants previously drifted (hook 5min vs
+// writer 30min), creating a 25-minute dead zone in which the hook demanded a
+// refresh that this writer answered with a skip.
+const HANDOFF_STALE_AFTER_MS = 5 * 60 * 1000;
+const FRESHNESS_WINDOW_MS = HANDOFF_STALE_AFTER_MS;
+const FRESHNESS_WINDOW_MIN = Math.round(FRESHNESS_WINDOW_MS / 60000);
+
+// ─────────────────────────────────────────
+// CLI argument parsing
+// ─────────────────────────────────────────
+
+// Value flags accept both `--flag=value` and `--flag value` via the shared
+// resolver helper (a local `=`-only parser turned `--trigger x` into
+// trigger=true -> 'invalid trigger "true"'). `--force` is the only boolean.
+const VALUE_FLAGS = ['trigger', 'last-milestone', 'project-path', 'session-id', 'transcript-path'];
+
+function parseArgs(argv) {
+  const args = {};
+  for (const name of VALUE_FLAGS) {
+    const value = projectResolver.extractCliFlag(argv, name);
+    if (value !== null) args[name] = value;
+  }
+  if (argv.includes('--force')) args.force = true;
+  return args;
+}
+
+// ─────────────────────────────────────────
+// Project path resolution (TASK_1701: uses shared resolver + pin file)
+// Priority: CLI --project-path > pin (session_id) > CLAUDE_PROJECT_DIR > cwd .kenaz/ > BASE_DIR
+// Pin outranks CLAUDE_PROJECT_DIR: hook-spawned children inherit the env var from
+// the session's launch cwd (core), which is exactly the leak the pin exists to fix —
+// a session pinned to a sub-project must not have its handoff routed back to core
+// by ambient env (observed 2026-07-06: commit-hook handoffs landing in core).
+// (TASK_2345: the .active-file fallback was removed with the Muninn watcher that wrote it.)
+// ─────────────────────────────────────────
+
+function resolveProjectPath(cliProjectPath, argv) {
+  if (cliProjectPath) return path.resolve(cliProjectPath);
+  const args = argv || process.argv.slice(2);
+  const sid = projectResolver.extractCliSessionId(args);
+  if (sid) {
+    const pinned = projectResolver.lookupPin(sid);
+    if (pinned) return pinned;
+  }
+  if (process.env.CLAUDE_PROJECT_DIR) return path.resolve(process.env.CLAUDE_PROJECT_DIR);
+  return projectResolver.resolve(null, { argv: args });
+}
+
+// ─────────────────────────────────────────
+// Data gathering helpers
+// ─────────────────────────────────────────
+
+function readSessionId(projectPath) {
+  try {
+    const sessionFile = path.join(projectPath, '.kenaz', 'specialist', 'ansuz_session.json');
+    if (!fs.existsSync(sessionFile)) return null;
+    const data = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+    // Dead-pid guard (TASK_1615): a session file left by a dead process is stale —
+    // stamping its session_id poisons every subsequent auto-snapshot.
+    if (data.pid) {
+      try {
+        process.kill(data.pid, 0);
+      } catch {
+        return null; // recorded process is gone — ignore the stale file
+      }
+    }
+    return data.session_id || null;
+  } catch {
+    return null;
+  }
+}
+
+// TASK_1982: resolve the CURRENT Claude Code conversation id (the same id the
+// staleness hook receives as hook-stdin payload.session_id) from the
+// stream-lease identity anchor, so a caller with no --session-id (the MCP
+// tool path — ansuz_handoff_snapshot has no hook stdin to read from) lands on
+// the SAME slot name the hook looks for, instead of minting a fresh
+// ansuz-prompt-<ts> file on every call. current_stream.json.conversation_id is
+// written by stream-lease.js register --conversation-id=<claude-session-uuid>
+// at boot; guarded by the stream's own lease heartbeat (mirrors the dead-pid
+// guard above) so a stale pointer left by a closed session cannot poison
+// every subsequent MCP-path snapshot.
+function readCurrentConversationId() {
+  try {
+    const streamLease = require(path.join(__dirname, '..', '..', 'tools', 'stream-lease.js'));
+    if (!fs.existsSync(streamLease.STREAM_ID_FILE)) return null;
+    const stream = JSON.parse(fs.readFileSync(streamLease.STREAM_ID_FILE, 'utf8'));
+    if (!stream || !stream.conversation_id) return null;
+    const lease = stream.session_id ? streamLease.readLease(stream.session_id) : null;
+    if (!lease || !streamLease.isSessionLive(lease)) return null;
+    return String(stream.conversation_id);
+  } catch {
+    return null;
+  }
+}
+
+function getRecentCommits(projectPath, n = 10) {
+  try {
+    const result = spawnSync('git', ['log', '--oneline', `-${n}`], {
+      cwd: projectPath,
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    if (result.status !== 0 || result.error) return [];
+    const output = (result.stdout || '').trim();
+    return output ? output.split('\n').filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+function getDiffStat(projectPath) {
+  try {
+    const result = spawnSync('git', ['diff', '--stat', 'HEAD'], {
+      cwd: projectPath,
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    if (result.status !== 0 || result.error) return '';
+    const lines = (result.stdout || '').trim().split('\n').filter(Boolean);
+    return lines[lines.length - 1] || '';
+  } catch {
+    return '';
+  }
+}
+
+function getRecentTasks(projectPath, limit = 5) {
+  const tasks = [];
+  const statusDirs = ['active', 'done', 'blocked'];
+  for (const status of statusDirs) {
+    const dir = path.join(projectPath, '.kenaz', 'tasks', status);
+    if (!fs.existsSync(dir)) continue;
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      try {
+        const filePath = path.join(dir, f);
+        const stat = fs.statSync(filePath);
+        const raw = fs.readFileSync(filePath, 'utf8');
+        // Extract title line (fast, no YAML parser needed)
+        const titleMatch = raw.match(/^title:\s*(.+)$/m);
+        const idMatch = raw.match(/^id:\s*(.+)$/m) || f.match(/(TASK_\d+)/);
+        tasks.push({
+          id: (idMatch && (idMatch[1] || idMatch[0])) || f.replace('.yaml', ''),
+          title: titleMatch ? titleMatch[1].trim().replace(/^["']|["']$/g, '') : f,
+          status,
+          mtimeMs: stat.mtimeMs,
+        });
+      } catch { /* skip */ }
+    }
+  }
+  // Sort by mtime descending, take limit
+  tasks.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return tasks.slice(0, limit);
+}
+
+// ─────────────────────────────────────────
+// Hand-rolled schema validator (~30 LOC)
+// Validates required fields against ansuz_session_handoff.schema.json structure.
+// ─────────────────────────────────────────
+
+function validateHandoff(obj) {
+  const errors = [];
+
+  function req(o, fields, prefix) {
+    for (const f of fields) {
+      if (o[f] === undefined || o[f] === null || o[f] === '') {
+        errors.push(`${prefix}.${f} is required`);
+      }
+    }
+  }
+
+  req(obj, ['schema_version', 'session_id', 'triggered_by', 'generated_at', 'isbar'], 'root');
+
+  if (obj.schema_version !== 1) {
+    errors.push('root.schema_version must be 1');
+  }
+  if (!VALID_TRIGGERS.includes(obj.triggered_by)) {
+    errors.push(`root.triggered_by must be one of: ${VALID_TRIGGERS.join(', ')}`);
+  }
+
+  const isbar = obj.isbar || {};
+  req(isbar, ['identification', 'situation', 'background', 'assessment', 'recommendation'], 'isbar');
+
+  const ident = isbar.identification || {};
+  req(ident, ['session_id', 'fatigue_potential', 'context_size_kb'], 'isbar.identification');
+
+  const sit = isbar.situation || {};
+  req(sit, ['current_topic', 'pending_decisions'], 'isbar.situation');
+  if (sit.pending_decisions !== undefined && !Array.isArray(sit.pending_decisions)) {
+    errors.push('isbar.situation.pending_decisions must be an array');
+  }
+
+  const bg = isbar.background || {};
+  req(bg, ['key_decisions', 'user_intent'], 'isbar.background');
+  if (bg.key_decisions !== undefined && !Array.isArray(bg.key_decisions)) {
+    errors.push('isbar.background.key_decisions must be an array');
+  }
+
+  const assess = isbar.assessment || {};
+  req(assess, ['why_handing_off', 'unfinished'], 'isbar.assessment');
+  if (assess.unfinished !== undefined && !Array.isArray(assess.unfinished)) {
+    errors.push('isbar.assessment.unfinished must be an array');
+  }
+
+  const rec = isbar.recommendation || {};
+  req(rec, ['first_action', 'context_to_restore'], 'isbar.recommendation');
+
+  return errors;
+}
+
+// ─────────────────────────────────────────
+// Atomic write (temp+rename, per-pid suffix)
+// ─────────────────────────────────────────
+
+function atomicWriteJson(filePath, obj) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2), 'utf8');
+    fs.renameSync(tmp, filePath);
+  } catch (e) {
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
+// ─────────────────────────────────────────
+// Dashboard HTTP helpers (best-effort — skip gracefully if server not running)
+// ─────────────────────────────────────────
+
+async function callMcpTool(toolName, toolArgs) {
+  const http = require('http');
+  const body = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: { name: toolName, arguments: toolArgs },
+  });
+
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        hostname: '127.0.0.1',
+        port: 18080,
+        path: '/api/mcp',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+        },
+        timeout: 4000,
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.error) { reject(new Error(parsed.error.message)); return; }
+            const text = parsed.result?.content?.[0]?.text;
+            resolve(text ? JSON.parse(text) : parsed.result);
+          } catch (e) { reject(e); }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('mcp timeout')); });
+    req.write(body);
+    req.end();
+  });
+}
+
+async function getKeyDecisionsFromSynapse(projectPath, n = 5) {
+  try {
+    // Use synapse_recall (project-scoped, honours projectPath) — NOT cortex_recall,
+    // which is cross-project global and would bleed core/other-project decisions
+    // into a sub-project's handoff (e.g. KenazAI HOOK_MARKER/TASK_574 into jiayao).
+    const result = await callMcpTool('synapse_recall', {
+      query: 'decision risk ash',
+      type: 'decision',
+      projectPath,
+      limit: n,
+    });
+    const runes = result?.runes || [];
+    if (!Array.isArray(runes) || runes.length === 0) return null;
+    return runes.slice(0, n).map((r) => {
+      const type = r.type || r.rune_type || 'rune';
+      const text = r.content || r.body || r.summary || '';
+      return `[${type}] ${String(text).substring(0, 100)}`;
+    }).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+async function archiveHandoffToHippocampus(handoff, projectPath) {
+  try {
+    const startResult = await callMcpTool('hippocampus_episode_start', {
+      scope: `handoff:${handoff.session_id}`,
+      projectPath,
+    });
+    const episodeId = startResult?.episode_id;
+    if (!episodeId) return false;
+
+    await callMcpTool('hippocampus_episode_append', {
+      episode_id: episodeId,
+      phase: 'archive',
+      content: JSON.stringify(handoff, null, 2),
+      projectPath,
+    });
+
+    await callMcpTool('hippocampus_episode_close', {
+      episode_id: episodeId,
+      summary: `Archived handoff snapshot session=${handoff.session_id} trigger=${handoff.triggered_by}`,
+      outcome: 'archived',
+      projectPath,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─────────────────────────────────────────
+// ISBAR builder
+// ─────────────────────────────────────────
+
+/**
+ * Task ids named in THIS conversation's own tool calls (assistant tool_use
+ * inputs), from its transcript. null when no transcript is available —
+ * callers then fall back to the project-wide task list. Hook-injected
+ * notices ("Task completed: TASK_X") are user-role text and do not count.
+ */
+function conversationTaskIds(transcriptPath) {
+  if (!transcriptPath) return null;
+  let text;
+  try {
+    text = fs.readFileSync(String(transcriptPath), 'utf8');
+  } catch {
+    return null;
+  }
+  const ids = new Set();
+  for (const line of text.split('\n')) {
+    if (!line.includes('TASK_') || !line.includes('"tool_use"')) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (!entry || entry.type !== 'assistant' || !Array.isArray(entry.message && entry.message.content)) continue;
+    for (const part of entry.message.content) {
+      if (!part || part.type !== 'tool_use') continue;
+      for (const m of JSON.stringify(part.input || {}).matchAll(/TASK_\d+/g)) ids.add(m[0]);
+    }
+  }
+  return ids;
+}
+
+function buildIsbar(sessionId, trigger, lastMilestone, commits, tasks, diffStat, keyDecisions, scopeTaskIds = null) {
+  // With a transcript, "pending/unfinished" means tasks THIS conversation
+  // touched; the project-wide active list put other sessions' cards there
+  // (a plain session's slot listed TASK_2005/2006 it never saw).
+  const inScope = t => !scopeTaskIds || scopeTaskIds.has(t.id);
+  const recentTaskTitles = tasks.filter(inScope).map(t => `${t.id}: ${t.title} [${t.status}]`);
+  const activeTasks = tasks.filter(t => t.status === 'active' && inScope(t)).map(t => `${t.id}: ${t.title}`);
+  const latestCommit = commits[0] || 'no commits';
+  const topicFromCommit = latestCommit.replace(/^[a-f0-9]{7,} /, '').substring(0, 80);
+  const topicFromMilestone = lastMilestone || topicFromCommit;
+
+  const reasonMap = {
+    live_dispatch_milestone: 'Task dispatched — capturing state before context diverges',
+    live_phase_exit: `Phase exit (${lastMilestone || 'unknown'}) — milestone checkpoint`,
+    live_decision_point: 'Major decision or risk recorded — preserving decision context',
+    manual: 'Manual handoff snapshot requested',
+  };
+
+  const contextFacts = [
+    `Last commit: ${latestCommit}`,
+    diffStat ? `Diff stat: ${diffStat}` : null,
+    recentTaskTitles.length > 0 ? `Recent tasks: ${recentTaskTitles.slice(0, 3).join('; ')}` : null,
+  ].filter(Boolean).join(' | ');
+
+  return {
+    identification: {
+      session_id: sessionId,
+      fatigue_potential: 0,
+      context_size_kb: 0,
+    },
+    situation: {
+      current_topic: topicFromMilestone,
+      pending_decisions: activeTasks.length > 0
+        ? activeTasks
+        : [scopeTaskIds ? '(no active tasks touched in this conversation)' : '(no active tasks)'],
+    },
+    background: {
+      key_decisions: (keyDecisions && keyDecisions.length > 0)
+        ? keyDecisions
+        : commits.slice(0, 5).map(c => c.replace(/^[a-f0-9]{7,} /, '')),
+      user_intent: recentTaskTitles.length > 0 ? recentTaskTitles[0] : 'Continue active work',
+    },
+    assessment: {
+      why_handing_off: reasonMap[trigger] || 'Snapshot triggered',
+      unfinished: activeTasks,
+    },
+    recommendation: {
+      first_action: lastMilestone
+        ? `Continue from: ${lastMilestone}`
+        : `Continue from: ${topicFromCommit}`,
+      context_to_restore: contextFacts || 'No recent context available',
+    },
+  };
+}
+
+// ─────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────
+
+async function main() {
+  const cliArgs = parseArgs(process.argv.slice(2));
+
+  const trigger = cliArgs['trigger'];
+  const lastMilestone = cliArgs['last-milestone'] || null;
+  // Pass argv so resolver can find --session-id for pin lookup (R4/TASK_1701)
+  const projectPath = resolveProjectPath(cliArgs['project-path'], process.argv.slice(2));
+
+  // Validate trigger
+  if (!trigger) {
+    console.error('Error: --trigger is required');
+    console.error(`Valid values: ${VALID_TRIGGERS.join(', ')}`);
+    process.exit(1);
+  }
+  if (!VALID_TRIGGERS.includes(trigger)) {
+    console.error(`Error: invalid trigger "${trigger}"`);
+    console.error(`Valid values: ${VALID_TRIGGERS.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Gather context (all best-effort)
+  // Slot-naming note (TASK_1828, refined TASK_1982): <conversation-uuid>.json is
+  // the preferred family — it is what the staleness hook looks for first
+  // (hook-stdin payload.session_id). Resolution order: explicit --session-id >
+  // the CURRENT Claude conversation id via the stream-lease identity anchor
+  // (readCurrentConversationId — matches the hook's payload.session_id for the
+  // MCP tool path, which has no hook stdin of its own) > the boot-registered
+  // ansuz_session.json id > ansuz-prompt-<timestamp>.json as the last-resort
+  // anonymous fallback when no identity source is available at all. Readers
+  // MUST still select slots by generated_at, never by filename ordering (see
+  // kenaz.rs tool_ansuz_handoff_snapshot and post-complete.js readLatestHandoff).
+  const sessionId = cliArgs['session-id']
+    || readCurrentConversationId()
+    || readSessionId(projectPath)
+    || `ansuz-prompt-${Date.now()}`;
+
+  // Freshness arbitration (TASK_1615): a freshly written handoff means a live
+  // author (main thread or recent snapshot) is at work — this auto-snapshot must
+  // not clobber richer content. Dead sessions emit no further events, so the
+  // silent-death fallback semantics are preserved: stale slots get written.
+  // FRESHNESS_WINDOW_MS is derived from HANDOFF_STALE_AFTER_MS at the top of
+  // this file (TASK_1837) — do not reintroduce a local constant here.
+  // M3 (TASK_1760): handoff writer migration — per-session slot under handoffs/
+  // Legacy single slot kept for read-only back-compat (readers fall back to it).
+  const handoffsDir = path.join(projectPath, '.kenaz', 'specialist', 'handoffs');
+  fs.mkdirSync(handoffsDir, { recursive: true });
+  const handoffPath = path.join(handoffsDir, sessionId + '.json');
+  // Legacy back-compat slot: .kenaz/specialist/ansuz_session_handoff.json is
+  // read-only after this migration (readers fall back to it; nothing writes it).
+  // TASK_1828: the unused legacyHandoffPath variable was removed — read-back
+  // ends (kenaz.rs, post-complete.js) resolve the legacy path themselves.
+  if (!cliArgs['force'] && fs.existsSync(handoffPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+      const age = Date.now() - new Date(existing.generated_at || 0).getTime();
+      // The guard protects caller-authored content from auto-snapshots. A caller that
+      // brings its own NEW milestone text is that author (TASK_2325: a restored
+      // negative control stayed recorded as "source disabled" for 5 minutes).
+      const newMilestone = lastMilestone && lastMilestone !== existing.last_milestone;
+      if (!newMilestone && Number.isFinite(age) && age >= 0 && age < FRESHNESS_WINDOW_MS) {
+        console.log(`⏭️  handoff skip: existing slot is fresh (${Math.round(age / 60000)}min < ${FRESHNESS_WINDOW_MIN}min, session=${existing.session_id}). Use --force to override.`);
+        process.exit(0);
+      }
+    } catch { /* corrupt existing — proceed to overwrite */ }
+  }
+
+  const commits = getRecentCommits(projectPath, 10);
+  // --transcript-path (passed by the commit/question/decision hooks) scopes the
+  // task lists to this conversation. Scoped: look wider, then filter, so other
+  // sessions' recent cards cannot push ours out of the top 5.
+  const scopeTaskIds = conversationTaskIds(cliArgs['transcript-path']);
+  const tasks = scopeTaskIds
+    ? getRecentTasks(projectPath, 200).filter(t => scopeTaskIds.has(t.id)).slice(0, 5)
+    : getRecentTasks(projectPath, 5);
+  const diffStat = getDiffStat(projectPath);
+  // R2 (TASK_1982): a repeated snapshot for the SAME session updates the same
+  // slot file (already true — the slot is keyed by sessionId) but previously
+  // silently dropped the prior generated_at. Carry it into a small bounded
+  // history array instead, so repeat snapshots stay visible in the file.
+  let priorHistory = [];
+  if (fs.existsSync(handoffPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+      if (existing.session_id && existing.session_id !== sessionId) {
+        await archiveHandoffToHippocampus(existing, projectPath);
+      } else if (existing.session_id === sessionId) {
+        priorHistory = Array.isArray(existing.history) ? existing.history.slice(-9) : [];
+        if (existing.generated_at) priorHistory.push(existing.generated_at);
+      }
+    } catch { /* ignore corrupt/missing */ }
+  }
+
+  // Pull recent decision/risk runes from this project's Synapse (best-effort; skip if dashboard not running)
+  const keyDecisions = await getKeyDecisionsFromSynapse(projectPath, 5);
+
+  // Build handoff object
+  const generatedAt = new Date().toISOString();
+  const isbar = buildIsbar(sessionId, trigger, lastMilestone, commits, tasks, diffStat, keyDecisions, scopeTaskIds);
+
+  const handoff = {
+    schema_version: 1,
+    session_id: sessionId,
+    triggered_by: trigger,
+    generated_at: generatedAt,
+    fatigue_potential: 0,
+    context_size_kb: 0,
+    last_milestone: lastMilestone || undefined,
+    isbar,
+  };
+  if (priorHistory.length > 0) handoff.history = priorHistory;
+
+  // Schema validation — fail fast, don't overwrite prior valid handoff
+  const errors = validateHandoff(handoff);
+  if (errors.length > 0) {
+    console.error('Schema validation failed:');
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+
+  // Atomic write to active slot (handoffPath already declared above)
+  atomicWriteJson(handoffPath, handoff);
+
+  // Print summary
+  const topicShort = (isbar.situation.current_topic || '').substring(0, 60);
+  console.log(`✅ handoff written: ${handoffPath}`);
+  console.log(`   session_id=${sessionId}`);
+  console.log(`   trigger=${trigger}`);
+  console.log(`   generated_at=${generatedAt}`);
+  console.log(`   topic="${topicShort}"`);
+}
+
+// Single-source export (TASK_1837): the staleness hook consumes
+// HANDOFF_STALE_AFTER_MS from here so hook and writer can never drift apart.
+module.exports = { HANDOFF_STALE_AFTER_MS, FRESHNESS_WINDOW_MS, conversationTaskIds, parseArgs };
+
+// CLI entry. Every caller spawns `node ansuz-handoff-snapshot.js ...` directly
+// (.claude/hooks/*, phase-gate.js, kenaz.rs), so require.main === module holds
+// there. The guard exists so the staleness hook can require() this module for
+// the threshold WITHOUT executing a snapshot. (The "no require.main guard" rule
+// from TASK_1827/1829 applies to .claude/hooks/* entry points invoked via
+// node -e — not to this CLI, which is never invoked that way.)
+if (require.main === module) {
+  main().catch(e => {
+    console.error('Fatal error:', e.message);
+    process.exit(1);
+  });
+}