@occasiolabs/occasio 0.8.5 → 0.8.6

package/README.md

@@ -9,12 +9,13 @@ Occasio sits between the agent and the cloud on your own machine, decides every
 ```bash
 npm install -g @occasiolabs/occasio
 
-occasio demo attest      # End-to-end attestation pipeline (30s, no API key)
-occasio demo anomalies   # Live EDR detection on a synthetic adversarial chain (5s)
+occasio demo audit       # Auditor scenario: signed attestation + cross-verifier proof (10s, no API key)
+occasio demo attest      # End-to-end attestation pipeline against a synthetic chain
+occasio demo anomalies   # Live EDR detection on a synthetic adversarial chain
 occasio harness          # Real Claude Code attacking a denied path — defense holds
 ```
 
-The first two demos run against synthetic data so you can see the full pipeline in under a minute with no external dependencies. The third spawns a real Claude Code subordinate under your Anthropic login (bundled auth — no API key required) and proves the defense end-to-end.
+The first three demos run against synthetic data so you can see the full pipeline in seconds with no external dependencies. The fourth spawns a real Claude Code subordinate under your Anthropic login (bundled auth — no API key required) and proves the defense end-to-end. Start with `demo audit` — it answers the only question that actually matters: *"prove what your AI agent did in CI."*
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occasiolabs/occasio",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "mcpName": "io.github.occasiolabs/occasio",
   "description": "Occasio — cryptographically verifiable behavioral attestation for AI coding agents. Tool-call interception + policy enforcement + tamper-evident audit chain + Sigstore-signed in-toto attestations + windowed EDR detection. Same engine for Claude Code and MCP; Computer-Use scaffold included.",
   "main": "src/index.js",
@@ -15,6 +15,7 @@
     "NOTICE"
   ],
   "scripts": {
+    "prepack": "node -e \"const fs=require('fs'),p=require('path');function rm(d){if(!fs.existsSync(d))return;for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory())rm(f);else fs.unlinkSync(f);}fs.rmdirSync(d);}rm('docs/__pycache__');console.log('prepack: cleared docs/__pycache__');\"",
     "pretest": "npm run lint:all",
     "test": "node test-interceptor.js && node test-native-handlers.js && node test-audit-chain.js && node test-attest.js && node test-policy-paths.js && node test-anomaly.js",
     "lint": "eslint src/audit src/attest src/core src/executor",

package/src/cli/conversation.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * conversation.js — read the last conversation snippet from Claude Code's
+ * own per-project session files at ~/.claude/projects/<cwd-encoded>/<id>.jsonl
+ *
+ * Why: pipeline-events.jsonl captures tool calls, but the actual prompts and
+ * model replies live in Claude Code's session files. Those already exist on
+ * disk — we don't need to add a new capture path in the proxy.
+ *
+ * Read-only, no I/O outside ~/.claude. Returns null on any miss (no claude
+ * dir, no project dir, no session file, malformed JSONL, etc.) — caller
+ * degrades gracefully.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// Claude Code encodes the cwd by replacing every path separator (':', '\', '/')
+// with a single '-'. So `C:\Users\leona\foo` → `C--Users-leona-foo` because
+// `C` + `:` (-) + `\` (-) + `Users`… yields two dashes between C and Users.
+function encodeCwd(cwd) {
+  return cwd.replace(/[:\\/]/g, '-');
+}
+
+function findProjectDir(cwd) {
+  const root = path.join(os.homedir(), '.claude', 'projects');
+  if (!fs.existsSync(root)) return null;
+  const encoded = encodeCwd(cwd);
+  const candidate = path.join(root, encoded);
+  if (fs.existsSync(candidate)) return candidate;
+  // Case-insensitive fallback (Windows drive letters): scan once.
+  try {
+    const entries = fs.readdirSync(root);
+    const hit = entries.find(n => n.toLowerCase() === encoded.toLowerCase());
+    return hit ? path.join(root, hit) : null;
+  } catch { return null; }
+}
+
+function listSessionFiles(projectDir) {
+  if (!projectDir) return [];
+  try {
+    return fs.readdirSync(projectDir)
+      .filter(n => n.endsWith('.jsonl') && /^[0-9a-f-]{36}\.jsonl$/i.test(n))
+      .map(n => {
+        const full = path.join(projectDir, n);
+        let mtime = 0;
+        try { mtime = fs.statSync(full).mtimeMs; } catch { /* */ }
+        return { name: n, full, mtime };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+  } catch { return []; }
+}
+
+// Pull a string preview out of message.content, which Claude Code stores as
+// either a raw string or an array of typed blocks.
+function previewText(content, max = 240) {
+  if (!content) return '';
+  if (typeof content === 'string') return content.slice(0, max).trim();
+  if (!Array.isArray(content)) return '';
+  for (const block of content) {
+    if (!block) continue;
+    if (typeof block === 'string') return block.slice(0, max).trim();
+    if (block.type === 'text' && typeof block.text === 'string') {
+      return block.text.slice(0, max).trim();
+    }
+  }
+  return '';
+}
+
+function loadConversation(sessionFile) {
+  let text;
+  try { text = fs.readFileSync(sessionFile, 'utf8'); }
+  catch { return null; }
+
+  let firstUser = null, lastUser = null, lastAssistant = null;
+  let firstTs = null, lastTs = null;
+
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (row.type !== 'user' && row.type !== 'assistant') continue;
+    const msg = row.message;
+    if (!msg) continue;
+    const preview = previewText(msg.content);
+    if (!preview) continue;
+    const ts = row.timestamp || null;
+    if (ts && !firstTs) firstTs = ts;
+    if (ts) lastTs = ts;
+    if (row.type === 'user') {
+      if (!firstUser) firstUser = preview;
+      lastUser = preview;
+    } else if (row.type === 'assistant') {
+      lastAssistant = preview;
+    }
+  }
+
+  if (!firstUser && !lastUser && !lastAssistant) return null;
+  return { firstUser, lastUser, lastAssistant, firstTs, lastTs };
+}
+
+/**
+ * Best-effort: find and read the most recent Claude Code conversation for
+ * the given cwd. Returns null if none found.
+ */
+function readLastConversation(cwd) {
+  const dir = findProjectDir(cwd);
+  if (!dir) return null;
+  const sessions = listSessionFiles(dir);
+  if (!sessions.length) return null;
+  // Try the newest first; fall through to older if newest is empty.
+  for (const s of sessions.slice(0, 3)) {
+    const conv = loadConversation(s.full);
+    if (conv) return { ...conv, sessionFile: s.full };
+  }
+  return null;
+}
+
+module.exports = { readLastConversation, encodeCwd, findProjectDir, listSessionFiles, loadConversation };

package/src/cli/help.js

@@ -46,6 +46,7 @@ ${col.b('Run')} ${col.d('— start a session, observe live state')}
 
 ${col.b('Inspect')} ${col.d('— forensics over what the agent did')}
   replay                     ${col.d('(stable)')} Replay run audit (--last N, --detail, --run <id>)
+  recap                      ${col.d('(stable)')} Markdown session summary for agent context (--last N, --run, --format)
   boundary                   ${col.d('(stable)')} Per-request: produced / re-entered / prevented
   inspect                    ${col.d('(stable)')} Cloud-boundary manifest (--last N, --entry N)
   distill                    ${col.d('(stable)')} Inspect distilled outputs (--last N, --entry <N>)
@@ -73,9 +74,10 @@ ${col.b('Policy & extras')}
   policy doctor              ${col.d('(beta)')}   Cross-reference logs with policy; suggest tightening
   computer-use               ${col.d('(alpha)')}  Apply policy to a JSONL of tool_use blocks (--dry-run --example)
   mcp-experiment             ${col.d('(beta)')}   MCP vs. built-in tool adoption stats
-  demo                       ${col.d('(stable)')} 10-second proof: see Occasio block real secrets
+  demo audit                 ${col.d('(stable)')} Auditor scenario: signed attestation + cross-verifier proof
   demo attest                ${col.d('(stable)')} End-to-end attestation pipeline against a synthetic chain
   demo anomalies             ${col.d('(stable)')} End-to-end EDR test: synthetic adversarial chain
+  demo                       ${col.d('(stable)')} 10-second proof: see Occasio block real secrets
 
 ${col.b('Presets:')}
   --preset balanced  (default)  Intercept safe reads locally, log all requests
@@ -88,7 +90,8 @@ ${col.b('Flags:')}
   --block-secrets               Alias for --preset strict
   --log-only                    Alias for --preset off
   --dashboard                   Open live dashboard at http://localhost:3001
-  --port <N>                    Proxy port (default: 8081)
+  --port <N>                    Proxy port (default: auto-assigned by OS)
+  --recap                       Print a previous-session banner at startup
   --verbose                     Print live per-request chatter (off by default)
 
 ${col.b('Multi-agent routing:')}

package/src/cli/recap.js

@@ -0,0 +1,367 @@
+'use strict';
+
+/**
+ * occasio recap — markdown summary of a past session, sized to paste into
+ * a new Claude prompt so the next agent picks up where the last one left off.
+ *
+ * Reads from ~/.occasio/pipeline-events.jsonl (read-only). Groups by run_id,
+ * picks the most recent session by default. No network, no signing, no policy
+ * decisions made — pure read view.
+ *
+ * Usage:
+ *   occasio recap                       # last session, markdown
+ *   occasio recap --last 3              # last 3 sessions
+ *   occasio recap --run <id>            # specific session
+ *   occasio recap --format text|json    # alt outputs
+ *
+ * The output is shaped to be useful as agent context — short, factual,
+ * decisions-first. Not an audit view (use `occasio replay --detail` for that).
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const { readLastConversation } = require('./conversation');
+
+const CHAIN_FILE = path.join(os.homedir(), '.occasio', 'pipeline-events.jsonl');
+
+const col = {
+  r:  s => `\x1b[31m${s}\x1b[0m`,
+  g:  s => `\x1b[32m${s}\x1b[0m`,
+  y:  s => `\x1b[33m${s}\x1b[0m`,
+  c:  s => `\x1b[36m${s}\x1b[0m`,
+  d:  s => `\x1b[2m${s}\x1b[0m`,
+  b:  s => `\x1b[1m${s}\x1b[0m`,
+};
+
+// Normalise tool names: chain has both PascalCase (Claude-Code-style) and
+// snake_case (shell-tool aliases via interceptor). Render as the canonical
+// display name so the recap doesn't double-count Read/read_file.
+const TOOL_DISPLAY = {
+  read_file:    'Read',
+  read:         'Read',
+  Read:         'Read',
+  grep:         'Grep',
+  Grep:         'Grep',
+  glob:         'Glob',
+  Glob:         'Glob',
+  find_files:   'Glob',
+  edit_file:    'Edit',
+  Edit:         'Edit',
+  MultiEdit:    'Edit',
+  write_file:   'Write',
+  Write:        'Write',
+  bash:         'Bash',
+  Bash:         'Bash',
+  shell_bash:   'Bash',
+  shell_powershell: 'PowerShell',
+  TodoWrite:    'TodoWrite',
+  TodoRead:     'TodoRead',
+  WebFetch:     'WebFetch',
+  WebSearch:    'WebSearch',
+};
+const TOOLS_THAT_READ     = new Set(['Read', 'Grep', 'Glob']);
+const TOOLS_THAT_MODIFY   = new Set(['Edit', 'Write']);
+
+function normTool(name) { return TOOL_DISPLAY[name] || name || 'unknown'; }
+
+function readChain(file) {
+  if (!fs.existsSync(file)) return [];
+  const text = fs.readFileSync(file, 'utf8');
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function groupByRun(rows) {
+  const map = new Map();
+  for (const r of rows) {
+    const id = r.run_id || 'legacy';
+    if (!map.has(id)) map.set(id, []);
+    map.get(id).push(r);
+  }
+  for (const arr of map.values()) {
+    arr.sort((a, b) => (a.ts || '') < (b.ts || '') ? -1 : 1);
+  }
+  return map;
+}
+
+function pickRecentRuns(rowsByRun, n) {
+  const entries = [...rowsByRun.entries()].map(([id, rows]) => ({
+    id,
+    rows,
+    end: rows.length ? rows[rows.length - 1].ts || '' : '',
+  }));
+  entries.sort((a, b) => a.end < b.end ? 1 : -1);
+  return entries.slice(0, n);
+}
+
+function pathOf(row) {
+  const t = row.tool_inputs || {};
+  return t.path || t.file_path || t.pattern || t.command || null;
+}
+
+function aggregate(rows) {
+  const tools = {};
+  const readPaths = new Set();
+  const modifyPaths = new Set();
+  const blocked = [];
+  const transformed = [];
+  const toolCalls = [];
+
+  for (const r of rows) {
+    if (r.kind !== 'tool_call') continue;
+    const tool = normTool(r.tool_name);
+    tools[tool] = (tools[tool] || 0) + 1;
+    toolCalls.push(r);
+
+    const p = pathOf(r);
+    if (p && r.action !== 'BLOCK') {
+      if (TOOLS_THAT_READ.has(tool))   readPaths.add(p);
+      if (TOOLS_THAT_MODIFY.has(tool)) modifyPaths.add(p);
+    }
+    if (r.action === 'BLOCK') {
+      blocked.push({ tool, target: p, reason: r.reason || 'policy' });
+    }
+    if (r.action === 'TRANSFORM') {
+      transformed.push({ tool, target: p, redacted: r.secrets_redacted || 0 });
+    }
+  }
+
+  return {
+    tools, readPaths: [...readPaths], modifyPaths: [...modifyPaths],
+    blocked, transformed, toolCalls,
+    start: rows[0]?.ts || null,
+    end:   rows[rows.length - 1]?.ts || null,
+  };
+}
+
+function shortPath(p, root) {
+  if (!p) return '(no path)';
+  if (root && p.startsWith(root)) {
+    const rel = p.slice(root.length).replace(/^[\\/]+/, '');
+    return rel || p;
+  }
+  return p;
+}
+
+function durationStr(start, end) {
+  if (!start || !end) return 'unknown';
+  const ms = new Date(end) - new Date(start);
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  const min = Math.round(ms / 60000);
+  if (min < 1) return '<1 min';
+  if (min < 60) return min + ' min';
+  return Math.floor(min/60) + 'h ' + (min%60) + 'm';
+}
+
+function lastActionsLines(toolCalls, root, n = 5) {
+  const last = toolCalls.slice(-n);
+  return last.map((r, i) => {
+    const tool = normTool(r.tool_name);
+    const p = shortPath(pathOf(r), root);
+    const action = r.action || '';
+    const tag = action === 'BLOCK' ? '✗' : action === 'TRANSFORM' ? '⚙' : '·';
+    return `${i+1}. ${tag} ${tool}  ${p}${action && action !== 'PASS' && action !== 'LOCAL' ? '  → ' + action : ''}`;
+  });
+}
+
+function renderMarkdown(run, root, conv) {
+  const a = aggregate(run.rows);
+  const dur = durationStr(a.start, a.end);
+  const date = a.start ? new Date(a.start).toISOString().replace('T', ' ').slice(0, 16) : 'unknown';
+
+  const lines = [];
+  lines.push(`# Previous session — ${date}, ${dur}`);
+  lines.push('');
+
+  if (conv && (conv.lastUser || conv.lastAssistant)) {
+    lines.push('## Last conversation');
+    if (conv.lastUser) {
+      lines.push(`- **You said:** ${conv.lastUser}`);
+    }
+    if (conv.lastAssistant) {
+      lines.push(`- **Agent replied:** ${conv.lastAssistant}`);
+    }
+    lines.push('');
+  }
+
+  if (a.readPaths.length || a.modifyPaths.length) {
+    lines.push('## Files touched');
+    if (a.modifyPaths.length) {
+      const shown = a.modifyPaths.slice(0, 10).map(p => shortPath(p, root));
+      const more = a.modifyPaths.length > 10 ? ` (+${a.modifyPaths.length - 10} more)` : '';
+      lines.push(`- modified: ${shown.join(', ')}${more}`);
+    }
+    if (a.readPaths.length) {
+      const shown = a.readPaths.slice(0, 10).map(p => shortPath(p, root));
+      const more = a.readPaths.length > 10 ? ` (+${a.readPaths.length - 10} more)` : '';
+      lines.push(`- read: ${shown.join(', ')}${more}`);
+    }
+    lines.push('');
+  }
+
+  const toolEntries = Object.entries(a.tools).sort((x, y) => y[1] - x[1]);
+  if (toolEntries.length) {
+    lines.push('## Tools used');
+    lines.push('- ' + toolEntries.map(([k, v]) => `${v} ${k}`).join(' · '));
+    lines.push('');
+  }
+
+  if (a.blocked.length || a.transformed.length) {
+    lines.push('## Decisions');
+    if (a.blocked.length) {
+      const byTarget = {};
+      for (const b of a.blocked) {
+        const key = `${b.tool}  ${shortPath(b.target, root)}`;
+        byTarget[key] = (byTarget[key] || 0) + 1;
+      }
+      for (const [k, count] of Object.entries(byTarget)) {
+        lines.push(`- ${count}× BLOCK  ${k}`);
+      }
+    }
+    if (a.transformed.length) {
+      const total = a.transformed.reduce((s, t) => s + (t.redacted || 0), 0);
+      lines.push(`- ${a.transformed.length}× TRANSFORM (${total} secret${total === 1 ? '' : 's'} redacted)`);
+    }
+    lines.push('');
+  }
+
+  if (a.toolCalls.length) {
+    lines.push('## Last actions');
+    for (const line of lastActionsLines(a.toolCalls, root)) lines.push(line);
+    lines.push('');
+  }
+
+  // Open-thread heuristic: surface last Bash/Edit/Write so the next agent
+  // knows the most recent state-changing action.
+  const lastBash  = [...a.toolCalls].reverse().find(r => normTool(r.tool_name) === 'Bash' || normTool(r.tool_name) === 'PowerShell');
+  const lastWrite = [...a.toolCalls].reverse().find(r => TOOLS_THAT_MODIFY.has(normTool(r.tool_name)));
+  if (lastBash || lastWrite) {
+    lines.push('## Open thread (best-guess from last actions)');
+    if (lastWrite) {
+      lines.push(`- last write: ${normTool(lastWrite.tool_name)}  ${shortPath(pathOf(lastWrite), root)}`);
+    }
+    if (lastBash) {
+      const cmd = (lastBash.tool_inputs && (lastBash.tool_inputs.command || lastBash.tool_inputs.cmd)) || '(no cmd)';
+      const exit = (typeof lastBash.exit_code === 'number') ? ` (exit ${lastBash.exit_code})` : '';
+      lines.push(`- last shell: ${cmd.slice(0, 80)}${cmd.length > 80 ? '…' : ''}${exit}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function renderText(run, root, conv) {
+  // Plain text variant, no markdown noise — convenient for CLI piping.
+  return renderMarkdown(run, root, conv).replace(/^#+\s*/gm, '').replace(/\n{3,}/g, '\n\n');
+}
+
+function renderJson(run, root, conv) {
+  const a = aggregate(run.rows);
+  return JSON.stringify({
+    run_id: run.id,
+    started_at: a.start,
+    ended_at:   a.end,
+    duration:   durationStr(a.start, a.end),
+    conversation: conv ? {
+      last_user:      conv.lastUser || null,
+      last_assistant: conv.lastAssistant || null,
+    } : null,
+    files: {
+      read:     a.readPaths.map(p => shortPath(p, root)),
+      modified: a.modifyPaths.map(p => shortPath(p, root)),
+    },
+    tools: a.tools,
+    decisions: { blocked: a.blocked, transformed: a.transformed },
+    last_actions: a.toolCalls.slice(-5).map(r => ({
+      tool: normTool(r.tool_name), action: r.action,
+      path: shortPath(pathOf(r), root), ts: r.ts,
+    })),
+  }, null, 2);
+}
+
+function parseArgs(argv) {
+  const out = { last: 1, run: null, format: 'md' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--last') out.last = Math.max(1, parseInt(argv[++i], 10) || 1);
+    else if (a === '--run') out.run = argv[++i];
+    else if (a === '--format') out.format = argv[++i];
+    else if (a === '--help' || a === '-h') out.help = true;
+  }
+  return out;
+}
+
+function printHelp() {
+  process.stdout.write(`
+${col.b('occasio recap')}  ${col.d('— session summary for agent context')}
+
+  Markdown summary of a past Occasio session: files touched, tools used,
+  decisions made, last actions. Designed to paste into a new Claude prompt
+  so the next session picks up where the last one left off.
+
+${col.b('Usage')}
+  occasio recap                       last session (markdown)
+  occasio recap --last 3              last 3 sessions
+  occasio recap --run <id>            specific session
+  occasio recap --format text|json    alternative output
+
+${col.b('Tip')}
+  occasio recap | clip               ${col.d('(Windows)')}
+  occasio recap | pbcopy             ${col.d('(macOS)')}
+  occasio recap | xclip -sel clip    ${col.d('(Linux)')}
+
+`);
+}
+
+function run(argv) {
+  const opts = parseArgs(argv || []);
+  if (opts.help) { printHelp(); return 0; }
+
+  const rows = readChain(CHAIN_FILE);
+  if (!rows.length) {
+    process.stderr.write(col.d(`No chain at ${CHAIN_FILE} — run \`occasio claude\` first.\n`));
+    return 1;
+  }
+
+  const byRun = groupByRun(rows);
+  let runs;
+  if (opts.run) {
+    if (!byRun.has(opts.run)) {
+      process.stderr.write(col.r(`No session with run_id ${opts.run}\n`));
+      return 1;
+    }
+    runs = [{ id: opts.run, rows: byRun.get(opts.run) }];
+  } else {
+    runs = pickRecentRuns(byRun, opts.last);
+  }
+
+  const root = process.cwd();
+  // Conversation snippet from Claude Code's own session files for the cwd.
+  // Only attach to the most-recent run; older runs in --last N get none
+  // (we have no way to map run_id to a specific Claude session reliably).
+  const conv = readLastConversation(root);
+  const parts = [];
+  for (let i = 0; i < runs.length; i++) {
+    const r = runs[i];
+    const useConv = i === 0 ? conv : null;
+    if (opts.format === 'json') {
+      parts.push(renderJson(r, root, useConv));
+    } else if (opts.format === 'text') {
+      parts.push(renderText(r, root, useConv));
+    } else {
+      parts.push(renderMarkdown(r, root, useConv));
+    }
+  }
+
+  process.stdout.write(parts.join('\n\n---\n\n') + '\n');
+  return 0;
+}
+
+module.exports = { run, aggregate, renderMarkdown, normTool };

package/src/demo/audit-demo.js

@@ -0,0 +1,330 @@
+'use strict';
+
+/**
+ * demo/audit-demo.js — `occasio demo audit`
+ *
+ * Hero demo: the auditor scenario. Shows the actual moat — a signed,
+ * offline-verifiable attestation of agent behavior that any third
+ * party can re-check with two independent verifiers (Node + Python).
+ *
+ * Flow:
+ *   1. Auditor question framed
+ *   2. Build richer synthetic chain (~12 rows: PASS + BLOCKs on the
+ *      asked-about path + TRANSFORM + LOCAL)
+ *   3. Verify chain integrity (Node SHA-256 walker)
+ *   4. Build unsigned attestation
+ *   5. Answer the auditor's question from the chain
+ *   6. Re-verify with the independent Python verifier (docs/attest_verify.py)
+ *      on the same artifact → byte-identical result
+ *   7. Show what --sign would add in real CI
+ *   8. CTA + spec link
+ *
+ * No API key, no network, no touching the user's real ~/.occasio chain.
+ */
+
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const { buildAttestation } = require('../attest');
+const { verifyFile }       = require('../audit/verifier');
+const { canonicalize }     = require('../attest/canonicalize');
+
+const C = {
+  r:  s => `\x1b[31m${s}\x1b[0m`,
+  g:  s => `\x1b[32m${s}\x1b[0m`,
+  y:  s => `\x1b[33m${s}\x1b[0m`,
+  c:  s => `\x1b[36m${s}\x1b[0m`,
+  d:  s => `\x1b[2m${s}\x1b[0m`,
+  b:  s => `\x1b[1m${s}\x1b[0m`,
+  rb: s => `\x1b[31;1m${s}\x1b[0m`,
+  gb: s => `\x1b[32;1m${s}\x1b[0m`,
+};
+
+const GENESIS = '0'.repeat(64);
+const DENIED_PATH = '/etc/secrets/db.yml';
+
+// Strip the OS temp prefix so demo output is screen-recording-safe
+// (Windows TEMP contains the username; macOS/Linux less so but still
+// machine-specific). Internal use still uses the real path.
+function displayPath(p) {
+  const tmp = os.tmpdir();
+  if (p && p.startsWith(tmp)) {
+    const suffix = p.slice(tmp.length).replace(/^[\\/]+/, '');
+    return process.platform === 'win32' ? `%TEMP%\\${suffix}` : `$TMPDIR/${suffix}`;
+  }
+  return p;
+}
+
+function appendRow(file, prevHash, row) {
+  const withPrev = { ...row, prev_hash: prevHash };
+  const hash = crypto.createHash('sha256').update(JSON.stringify(withPrev), 'utf8').digest('hex');
+  const full = { ...withPrev, hash };
+  fs.appendFileSync(file, JSON.stringify(full) + '\n');
+  return { hash, full };
+}
+
+function buildAuditScenarioChain(chainFile, policyFile) {
+  fs.writeFileSync(chainFile, '');
+  fs.writeFileSync(policyFile, [
+    'version: 1',
+    'deny_paths:',
+    '  - "/etc/secrets/**"',
+    '  - "**/.env"',
+    '  - "**/.ssh/**"',
+    'deny_patterns:',
+    '  api_key: "(?i)api[_-]?key\\\\s*[:=]\\\\s*\\\\S+"',
+    'block_secrets_in_tool_results: true',
+    '',
+  ].join('\n'));
+
+  const RUN = crypto.randomBytes(16).toString('hex');
+  const RUN_ID = `${RUN.slice(0,8)}-${RUN.slice(8,12)}-${RUN.slice(12,16)}-${RUN.slice(16,20)}-${RUN.slice(20,32)}`;
+  const policyHash = crypto.createHash('sha256').update(fs.readFileSync(policyFile)).digest('hex');
+
+  let prev = GENESIS;
+  const ts = (sec) => new Date(Date.UTC(2026, 4, 16, 9, 30, sec)).toISOString();
+
+  const blockedHashes = [];
+
+  // 1. policy_loaded
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(0), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'occasio',
+    kind: 'policy_loaded', tool_name: 'policy_loaded', action: 'INFO',
+    tool_inputs: { policy_hash: policyHash, policy_path: policyFile, version: 1 },
+    policy_source: 'user', reason: 'policy-loaded',
+  }));
+
+  // 2-4. Three normal PASS reads of source files
+  for (const [i, p] of [[5, 'src/server.js'], [8, 'src/db.js'], [12, 'package.json']]) {
+    ({ hash: prev } = appendRow(chainFile, prev, {
+      ts: ts(i), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'claude-code',
+      kind: 'tool_call', tool_name: 'Read', action: 'PASS',
+      tool_inputs: { path: p },
+    }));
+  }
+
+  // 5. LOCAL Glob discovery
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(15), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Glob', action: 'LOCAL',
+    tool_inputs: { pattern: 'src/**/*.js' },
+  }));
+
+  // 6-8. THREE attempts to read the denied path — all BLOCKED
+  //      (this is what the auditor will ask about)
+  for (const [i, attempt] of [
+    [18, DENIED_PATH],
+    [22, '/etc/secrets/../secrets/db.yml'],     // traversal attempt
+    [27, DENIED_PATH],                          // retry
+  ].entries()) {
+    const r = appendRow(chainFile, prev, {
+      ts: ts(attempt[0]), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'claude-code',
+      kind: 'tool_call', tool_name: 'Read', action: 'BLOCK',
+      tool_inputs: { path: attempt[1] },
+      reason: 'path-denied',
+    });
+    prev = r.hash;
+    blockedHashes.push({ ts: ts(attempt[0]), hash: r.hash, path: attempt[1] });
+  }
+
+  // 9. TRANSFORM — Grep result had an API key, redacted before forward
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(32), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Grep', action: 'TRANSFORM',
+    tool_inputs: { pattern: 'config', path: 'src/' },
+    secrets_redacted: 1,
+    transform: 'redact-secrets',
+  }));
+
+  // 10-11. Two more PASS reads
+  for (const [i, p] of [[36, 'src/auth.js'], [40, 'src/routes.js']]) {
+    ({ hash: prev } = appendRow(chainFile, prev, {
+      ts: ts(i), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'claude-code',
+      kind: 'tool_call', tool_name: 'Read', action: 'PASS',
+      tool_inputs: { path: p },
+    }));
+  }
+
+  // 12. LOCAL grep
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(45), event_id: crypto.randomUUID(), run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Grep', action: 'LOCAL',
+    tool_inputs: { pattern: 'TODO', path: 'src/' },
+  }));
+
+  return { runId: RUN_ID, blockedHashes };
+}
+
+function tryPython(att, chainFile, attFile) {
+  const candidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
+  for (const cmd of candidates) {
+    const probe = spawnSync(cmd, ['--version'], { stdio: 'pipe', shell: false });
+    if (probe.status === 0) {
+      const verifierPath = path.join(__dirname, '..', '..', 'docs', 'attest_verify.py');
+      if (!fs.existsSync(verifierPath)) {
+        return { ran: false, reason: `verifier script not found at ${verifierPath}` };
+      }
+      const result = spawnSync(cmd, [verifierPath, attFile, '--chain', chainFile], {
+        stdio: 'pipe', shell: false, encoding: 'utf8',
+      });
+      const out = (result.stdout || '') + (result.stderr || '');
+      // Parse the verifier's "[STATUS] check name" lines. For an unsigned
+      // attestation, sigstore steps SKIP and the chain step OKs — that is
+      // the success shape for the demo. Real failure = any FAIL line.
+      const lines = out.split('\n');
+      const checks = [];
+      for (const line of lines) {
+        const m = line.match(/\[\s*(OK|FAIL|SKIP)\s*\]\s+(.+?)\s*$/);
+        if (m) checks.push({ status: m[1], name: m[2] });
+      }
+      const anyFail = checks.some(c => c.status === 'FAIL');
+      const chainOk = checks.some(c => c.status === 'OK' && /chain/i.test(c.name));
+      return {
+        ran: true,
+        cmd,
+        exitCode: result.status,
+        checks,
+        anyFail,
+        chainOk,
+        stdout: result.stdout || '',
+      };
+    }
+  }
+  return { ran: false, reason: 'no python3/python on PATH' };
+}
+
+async function runAuditDemoCli(_args = []) {
+  const tmpDir   = fs.mkdtempSync(path.join(os.tmpdir(), 'lf-demo-audit-'));
+  const chainFile  = path.join(tmpDir, 'pipeline-events.jsonl');
+  const policyFile = path.join(tmpDir, 'policy.yml');
+  const attFile    = path.join(tmpDir, 'occasio-attestation.json');
+
+  console.log(C.b('\n⚡ Occasio — auditor demo  ') + C.d('(no API key, no network, ~10s)\n'));
+
+  // ── Scene ──────────────────────────────────────────────────────────────
+  console.log(C.b('━━━ The question ━━━\n'));
+  console.log('  ' + C.y('Auditor:') + ' "Your CI merged 47 AI-authored PRs last month. Prove the');
+  console.log('           agent in build #2849 never read ' + C.c(DENIED_PATH) + '."');
+  console.log('');
+  console.log('  ' + C.d('Without Occasio: you grep through stderr logs, hope nothing was'));
+  console.log('  ' + C.d('rotated, and email Anthropic for server-side traces.'));
+  console.log('  ' + C.d('With Occasio: you hand the auditor one JSON file. They verify it offline.'));
+  console.log('');
+
+  // ── Step 1: chain ──────────────────────────────────────────────────────
+  console.log(C.b('1.') + ' Synthesizing the CI-run audit chain  ' + C.d('(12 rows, hash-linked)'));
+  const { runId, blockedHashes } = buildAuditScenarioChain(chainFile, policyFile);
+  console.log('   ' + C.g('✓') + ' run_id: ' + C.c(runId));
+  console.log('   ' + C.d('chain: ' + displayPath(chainFile)));
+  console.log('');
+
+  // ── Step 2: verify ─────────────────────────────────────────────────────
+  console.log(C.b('2.') + ' Verifying chain integrity  ' + C.d('(SHA-256 walk: prev_hash → hash, GENESIS → HEAD)'));
+  const ver = verifyFile(chainFile);
+  if (!ver.ok) {
+    console.error('   ' + C.r('✗') + ' chain broken — demo bug');
+    return 1;
+  }
+  console.log('   ' + C.g('✓') + ' all ' + ver.chained + ' rows chained, no tamper gap');
+  console.log('');
+
+  // ── Step 3: build attestation ──────────────────────────────────────────
+  console.log(C.b('3.') + ' Building behavioral attestation  ' + C.d('(unsigned; --sign needs OIDC)'));
+  const att = buildAttestation({ runId, logFile: chainFile, policyFile });
+  if (!att) {
+    console.error('   ' + C.r('✗') + ' buildAttestation returned null');
+    return 1;
+  }
+  fs.writeFileSync(attFile, JSON.stringify(att, null, 2));
+  console.log('   ' + C.g('✓') + ' ' + C.d(displayPath(attFile)));
+  console.log('   ' + C.d('tool_calls: ' + att.execution_summary.tool_calls
+    + '  blocked: ' + att.execution_summary.blocked
+    + '  transformed: ' + att.execution_summary.transformed
+    + '  secrets_redacted: ' + att.execution_summary.secrets_redacted));
+  console.log('');
+
+  // ── Step 4: ANSWER THE AUDITOR ─────────────────────────────────────────
+  console.log(C.b('━━━ Answer to the auditor ━━━\n'));
+  console.log('  ' + C.y('Q:') + ' "Did the agent read ' + C.c(DENIED_PATH) + '?"');
+  console.log('  ' + C.gb('A: NO.') + ' ' + blockedHashes.length + ' attempts, all denied by policy. Evidence:');
+  console.log('');
+  for (const b of blockedHashes) {
+    console.log('     ' + C.d(b.ts) + '  ' + C.rb('BLOCK') + '  '
+      + b.path.padEnd(38) + '  ' + C.d('hash=' + b.hash.slice(0, 16) + '…'));
+  }
+  console.log('');
+  console.log('  ' + C.d('These row hashes are linked into the chain. Tampering with any'));
+  console.log('  ' + C.d('one of them breaks the SHA-256 walk and the attestation fails verify.'));
+  console.log('');
+
+  // ── Step 5: Node verifier (canonical round-trip) ───────────────────────
+  console.log(C.b('4.') + ' Re-verifying with the Node verifier  ' + C.d('(canonical JSON round-trip)'));
+  const reparsed = JSON.parse(fs.readFileSync(attFile, 'utf8'));
+  const { signature: _o1, ...expected } = att;
+  const { signature: _o2, ...observed } = reparsed;
+  if (canonicalize(expected) !== canonicalize(observed)) {
+    console.error('   ' + C.r('✗') + ' canonical bytes diverged');
+    return 1;
+  }
+  console.log('   ' + C.g('✓') + ' predicate canonical-stable across reparse');
+  console.log('');
+
+  // ── Step 6: Python cross-verifier ──────────────────────────────────────
+  console.log(C.b('5.') + ' Re-verifying with the independent Python verifier  ' + C.d('(docs/attest_verify.py)'));
+  const py = tryPython(att, chainFile, attFile);
+  if (!py.ran) {
+    console.log('   ' + C.y('○') + ' Python verifier skipped — ' + py.reason);
+    console.log('   ' + C.d('  install python3 to run the cross-verifier; the Node check above already passed'));
+  } else if (py.anyFail) {
+    console.log('   ' + C.r('✗') + ' Python verifier reported FAIL  ' + C.d('(' + py.cmd + ' exit ' + py.exitCode + ')'));
+    for (const c of py.checks) {
+      const tag = c.status === 'OK' ? C.g('OK  ') : c.status === 'FAIL' ? C.r('FAIL') : C.y('SKIP');
+      console.log('     [' + tag + '] ' + c.name);
+    }
+  } else if (py.chainOk) {
+    console.log('   ' + C.g('✓') + ' independent Python verifier agrees on the audit chain');
+    for (const c of py.checks) {
+      const tag = c.status === 'OK' ? C.g('OK  ') : C.y('SKIP');
+      console.log('     [' + tag + '] ' + c.name);
+    }
+    console.log('   ' + C.d('  (sigstore steps SKIP because the demo attestation is unsigned;'));
+    console.log('   ' + C.d('   in real CI with --sign, all three rows would show OK)'));
+  } else {
+    console.log('   ' + C.y('○') + ' Python verifier ran but did not produce the expected check lines');
+    console.log('   ' + C.d('  exit ' + py.exitCode + ' — see ' + displayPath(attFile) + ' for the artifact'));
+  }
+  console.log('');
+
+  // ── Step 7: what --sign adds in CI ─────────────────────────────────────
+  console.log(C.b('━━━ In real CI: --sign adds the third check ━━━\n'));
+  console.log('  ' + C.c('occasio attest --run-id ' + runId.slice(0, 8) + '… --sign'));
+  console.log('  ' + C.d('  → signs via Sigstore keyless using GitHub Actions OIDC (no key mgmt)'));
+  console.log('  ' + C.d('  → emits .json attestation + .bundle.json Sigstore bundle'));
+  console.log('  ' + C.d('  → workflow posts a Check Run on the PR with the verify summary'));
+  console.log('');
+  console.log('  ' + C.b('Auditor verifies offline with three independent paths:'));
+  console.log('  ' + C.d('  • ') + C.c('occasio attest verify <file>') + C.d('       (Node)'));
+  console.log('  ' + C.d('  • ') + C.c('python3 docs/attest_verify.py <file>') + C.d(' (stdlib + sigstore-python)'));
+  console.log('  ' + C.d('  • ') + C.c('cosign verify-blob …') + C.d('                (any sigstore-conformant tool)'));
+  console.log('');
+  console.log('  ' + C.d('All three must agree. None of them trust Occasio\'s own verifier.'));
+  console.log('');
+
+  // ── CTA ────────────────────────────────────────────────────────────────
+  console.log(C.b('━━━ Try it on your own CI ━━━\n'));
+  console.log('  ' + C.c('npm install -g @occasiolabs/occasio'));
+  console.log('  ' + C.c('occasio policy init                     ') + C.d('# write ~/.occasio/policy.yml'));
+  console.log('  ' + C.c('occasio register                        ') + C.d('# alias `claude` through the proxy'));
+  console.log('  ' + C.d('Add .github/workflows/attest-on-pr.yml from docs/reference-pipeline.md'));
+  console.log('');
+  console.log('  ' + C.b('Spec:') + ' https://github.com/occasiolabs/occasio/tree/main/spec/agent-attestation/v1');
+  console.log('  ' + C.b('Scratch artifacts kept at:') + ' ' + C.d(displayPath(tmpDir)));
+  console.log('');
+
+  return 0;
+}
+
+module.exports = { runAuditDemoCli, buildAuditScenarioChain };

package/src/index.js

@@ -56,10 +56,11 @@ const VERSION = (() => {
   catch { return '0.0.0-unknown'; }
 })();
 const LOG_SCHEMA_VERSION = 2;
-// Port override via env var (used by `occasio harness` and redteam to
-// run isolated proxies against scratch audit chains on free ports). Default
-// is 8081 to preserve existing user-facing behaviour.
-let PORT = parseInt(process.env.OCCASIO_PORT, 10) || 8081;
+// Port: defaults to 0 (auto-assigned by the OS) so multiple `occasio claude`
+// sessions can run in parallel. Explicit overrides via OCCASIO_PORT env or
+// --port flag still pin a fixed port (and surface EADDRINUSE if taken).
+let PORT = parseInt(process.env.OCCASIO_PORT, 10) || 0;
+let PORT_EXPLICIT = PORT !== 0;
 const ANTHROPIC_REAL = 'api.anthropic.com';
 const LOG_DIR      = path.join(os.homedir(), '.occasio');
 const SESSION_FILE = path.join(LOG_DIR, 'session.json');
@@ -131,6 +132,60 @@ const col = {
   d: s => `\x1b[2m${s}\x1b[0m`,  b: s => `\x1b[1m${s}\x1b[0m`,
 };
 
+// Print a compact recap banner just before claude starts — gives the user
+// (and the agent, via on-screen context) a memory anchor for the previous
+// session in this cwd. Silent if no prior data exists.
+function printSessionRecapBanner() {
+  let conv = null;
+  try { conv = require('./cli/conversation').readLastConversation(process.cwd()); }
+  catch { /* module load issue → skip */ }
+
+  // Last run summary from the audit chain.
+  let runLine = null;
+  try {
+    const chainFile = path.join(LOG_DIR, 'pipeline-events.jsonl');
+    if (fs.existsSync(chainFile)) {
+      const text = fs.readFileSync(chainFile, 'utf8');
+      const rows = [];
+      for (const line of text.split('\n')) {
+        if (!line) continue;
+        try { rows.push(JSON.parse(line)); } catch { /* skip */ }
+      }
+      const byRun = new Map();
+      for (const r of rows) {
+        const id = r.run_id || 'legacy';
+        if (!byRun.has(id)) byRun.set(id, []);
+        byRun.get(id).push(r);
+      }
+      const newest = [...byRun.entries()].map(([id, rs]) => ({
+        id, rs, end: rs[rs.length - 1]?.ts || '',
+      })).sort((a, b) => a.end < b.end ? 1 : -1)[0];
+      if (newest) {
+        const tc = newest.rs.filter(r => r.kind === 'tool_call').length;
+        const blocked = newest.rs.filter(r => r.action === 'BLOCK').length;
+        const date = newest.end ? new Date(newest.end).toISOString().slice(0, 16).replace('T', ' ') : 'unknown';
+        runLine = `${tc} tool calls, ${blocked} blocked  ·  ${date}`;
+      }
+    }
+  } catch { /* skip */ }
+
+  if (!conv && !runLine) return;
+
+  const oneLine = (s, max = 160) => {
+    const flat = String(s).replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
+  };
+  process.stderr.write('\n' + col.b('── previous session in this directory ──') + '\n');
+  if (runLine) process.stderr.write('  ' + col.d(runLine) + '\n');
+  if (conv && conv.lastUser) {
+    process.stderr.write('  ' + col.y('You: ') + oneLine(conv.lastUser) + '\n');
+  }
+  if (conv && conv.lastAssistant) {
+    process.stderr.write('  ' + col.g('Agent: ') + oneLine(conv.lastAssistant) + '\n');
+  }
+  process.stderr.write(col.d('  (enabled via --recap; suppress next time by omitting it)') + '\n\n');
+}
+
 // ── Pre-send manifest ─────────────────────────────────────────────────────────
 
 function fmtTok(n) {
@@ -284,6 +339,10 @@ if (cmd === 'replay') {
   process.exit(0);
 }
 
+if (cmd === 'recap') {
+  process.exit(require('./cli/recap').run(args.slice(1)));
+}
+
 if (cmd === 'distill') {
   runDistillCli(args.slice(1));
   process.exit(0);
@@ -404,6 +463,13 @@ if (cmd === 'demo' && (args[1] === 'anomalies' || args[1] === 'anomaly')) {
   process.exit(runAnomaliesDemoCli(args.slice(2)));
 }
 
+if (cmd === 'demo' && (args[1] === 'audit' || args[1] === 'auditor')) {
+  const { runAuditDemoCli } = require('./demo/audit-demo');
+  runAuditDemoCli(args.slice(2)).then(code => process.exit(code))
+    .catch(e => { process.stderr.write(`[demo audit] ${e.message}\n`); process.exit(1); });
+  return;
+}
+
 if (cmd === 'demo') {
   const { scanSecrets } = require('../src/analyzer');
   // Realistic-looking but synthetic credentials. Each hits exactly one pattern.
@@ -537,16 +603,22 @@ if (cmd === 'doctor' || cmd === 'check') {
       ok('log dir', LOG_DIR);
     } catch (e) { bad('log dir', e.message); }
 
-    // 4. Port availability (async)
-    await new Promise(resolve => {
-      const srv = net.createServer();
-      srv.once('error', () => {
-        bad(`port ${PORT}`, `already in use — kill it: netstat -ano | findstr :${PORT}`);
-        resolve();
+    // 4. Port availability (async) — only probe when an explicit port is pinned.
+    // With auto-assignment (default), the OS picks a free port at listen-time
+    // so there's nothing meaningful to probe in advance.
+    if (PORT_EXPLICIT) {
+      await new Promise(resolve => {
+        const srv = net.createServer();
+        srv.once('error', () => {
+          bad(`port ${PORT}`, `already in use — kill it: netstat -ano | findstr :${PORT}`);
+          resolve();
+        });
+        srv.once('listening', () => { srv.close(); ok(`port ${PORT}`, 'available'); resolve(); });
+        srv.listen(PORT, '127.0.0.1');
       });
-      srv.once('listening', () => { srv.close(); ok(`port ${PORT}`, 'available'); resolve(); });
-      srv.listen(PORT, '127.0.0.1');
-    });
+    } else {
+      ok('port', 'auto-assigned at runtime');
+    }
 
     // 5. Python + LAO scorer script
     const laoPyPath = path.join(__dirname, 'lao_prep.py');
@@ -632,8 +704,15 @@ if (prIdx >= 0) {
 const di = claudeArgs.indexOf('--dashboard');
 const useDashboard = di >= 0;
 if (di >= 0) claudeArgs.splice(di, 1);
+const recapIdx = claudeArgs.indexOf('--recap');
+const showRecap = recapIdx >= 0;
+if (recapIdx >= 0) claudeArgs.splice(recapIdx, 1);
 const pi = claudeArgs.indexOf('--port');
-if (pi >= 0) { PORT = parseInt(claudeArgs[pi+1], 10) || PORT; claudeArgs.splice(pi, 2); }
+if (pi >= 0) {
+  const parsed = parseInt(claudeArgs[pi+1], 10);
+  if (parsed > 0) { PORT = parsed; PORT_EXPLICIT = true; }
+  claudeArgs.splice(pi, 2);
+}
 
 // Budget flag: --budget <N> sets a session dollar limit.
 const bgtIdx = claudeArgs.indexOf('--budget');
@@ -1353,7 +1432,7 @@ const server = http.createServer((req, res) => {
 
 server.on('error', e => {
   if (e.code === 'EADDRINUSE') {
-    process.stderr.write(col.r(`\n❌ Port ${PORT} already in use. Kill the old process first:\n`));
+    process.stderr.write(col.r(`\n❌ Port ${PORT} already in use. Kill the old process first or omit --port / OCCASIO_PORT to let the OS auto-assign:\n`));
     process.stderr.write(col.d(`   netstat -ano | findstr :${PORT}  → then: taskkill /PID <pid> /F\n\n`));
   } else {
     process.stderr.write(col.r(`\n❌ ${e.message}\n`));
@@ -1362,6 +1441,17 @@ server.on('error', e => {
 });
 
 server.listen(PORT, '127.0.0.1', () => {
+  PORT = server.address().port;
+  process.stderr.write(col.d(`occasio proxy listening on 127.0.0.1:${PORT}\n`));
+
+  // Best-effort: print a 3-line recap of the previous session so the user
+  // (and via screen-context, the agent itself) has a memory anchor before
+  // typing the next prompt. Silent if no prior session in this cwd.
+  // Disable with --no-recap.
+  if (showRecap) {
+    try { printSessionRecapBanner(); } catch { /* never block startup */ }
+  }
+
   const env = { ...process.env, ANTHROPIC_BASE_URL: `http://localhost:${PORT}` };
   // On Windows, npm installs binaries as .cmd wrappers (claude.cmd).
   // spawn() without shell:true calls CreateProcess directly, which won't