@occasiolabs/occasio 0.8.4 → 0.8.6

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

@@ -1,6 +1,11 @@
 // `occasio help` — top-level usage. Pure text; no side effects other
 // than console.log. Each CLI command lives in its own file under
 // src/cli/ as part of the index.js decomposition (see CHANGELOG).
+//
+// Maturity tags follow the bewertung pillars:
+//   (stable) — load-bearing, has test coverage and field validation
+//   (beta)   — works end-to-end but missing breadth (one detector, one preset)
+//   (alpha)  — scaffold; needs operator calibration before relying on it
 
 'use strict';
 
@@ -19,42 +24,60 @@ function run() {
   console.log(`
 ${col.b(`⚡ Occasio v${VERSION}`)}
 
-${col.b('Usage:')}
-  occasio claude [args...]   Start Claude with local proxy (intercept + log)
-  occasio demo               10-second proof: see Occasio block real secrets
-  occasio demo attest        End-to-end attestation pipeline against a synthetic audit chain
-  occasio demo anomalies     End-to-end EDR test: synthetic adversarial chain → all 4 detectors
-  occasio dashboard          Open live dashboard for the running session
-  occasio register           Register shell alias (type 'claude' directly)
-  occasio status             Show session stats and savings breakdown
-  occasio doctor             Check setup: Node, claude CLI, port, Python, profile
-  occasio clear              Reset today's log and session data
-  occasio clear --history    Wipe all historical logs
-  occasio ledger             Inspect token ledger (--last N, --summary, --scope session|today)
-  occasio replay             Replay run audit (--last N, --detail, --run <id>, --attribute)
-  occasio distill            Inspect distilled outputs (--last N, --entry <N> for raw)
-  occasio inspect            Cloud-boundary manifest (--last N, --entry N, --run <id>)
-  occasio boundary           Per-request three-column view: produced / re-entered / prevented
-  occasio baseline           Behavior baseline: [learn|show|compare|reset] (per project cwd)
-  occasio harness            Run a real Claude Code session against scratch fixtures and verify governance claims (needs ANTHROPIC_API_KEY)
-  occasio redteam            Autonomous adversarial test — tester LLM probes a subject Claude Code session under Occasio (needs ANTHROPIC_API_KEY + @anthropic-ai/sdk)
-  occasio policy [show]      Show active policy: flags, tool routing, overrides
-  occasio policy show --diff Only values that differ from defaults
-  occasio policy validate    Validate policy.yml and report errors/warnings
-  occasio policy init        Create a starter policy.yml (safe, non-destructive)
-                                Use --template strict|finance for a non-default starter
-  occasio policy doctor      Cross-reference session logs with policy; surface suggestions
-  occasio audit [verify]     Verify tamper-evident hash chain in pipeline-events.jsonl
-  occasio audit repair       Truncate a crash-partial trailing line (--file <path> [--dry-run])
-  occasio report             Governance export: file access log, blocked paths, secret events
-  occasio anomalies          Live anomaly detection over the audit chain (--window 15m, --json)
-  occasio computer-use       Apply a Computer-Use policy to a JSONL of tool_use blocks (--dry-run --example)
-  occasio attest --run-id <uuid>  AI-Agent Behavioral Attestation v1: hash-chain commitment + execution summary for one run
-                              Add --sign in GitHub Actions (with permissions: id-token: write) for Sigstore keyless signing
-  occasio attest verify <file>   Re-verify a signed attestation: Sigstore bundle + DSSE payload match + audit chain integrity
-  occasio selftest           Run governance self-checks on a scratch chain (does not touch your audit log)
-  occasio report --format csv  CSV export for auditors / SIEM import
-  occasio mcp-experiment     MCP vs. built-in tool adoption stats (experiment)
+${col.b('60-Second Start:')}
+  ${col.c('occasio init')}        Create policy.yml from a template
+  ${col.c('occasio register')}    Install shell alias so 'claude' uses the proxy
+  ${col.c('claude --version')}    Confirm the wrapper resolves Claude Code
+
+${col.b('Usage:')}  occasio <command> [args...]   (or  oc <command>)
+
+${col.b('Setup')} ${col.d('— one-time, per project')}
+  init                       ${col.d('(stable)')} Create starter policy.yml (--template strict|finance)
+  register                   ${col.d('(stable)')} Register shell alias (type 'claude' directly)
+  doctor                     ${col.d('(stable)')} Check setup: Node, claude CLI, port, Python, profile
+
+${col.b('Run')} ${col.d('— start a session, observe live state')}
+  claude [args...]           ${col.d('(stable)')} Start Claude with local proxy (intercept + log)
+  status                     ${col.d('(stable)')} Session stats, savings breakdown, coverage
+  clear                      ${col.d('(stable)')} Reset today's log and session data
+  clear --history            ${col.d('(stable)')} Wipe all historical logs
+  ledger                     ${col.d('(stable)')} Inspect token ledger (--last N, --summary, --scope)
+  dashboard                  ${col.d('(beta)')}   Open live dashboard at http://localhost:3001
+
+${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>)
+  report                     ${col.d('(stable)')} Governance export (--format csv for SIEM)
+  preflight                  ${col.d('(beta)')}   Read-only miner over past logs
+  baseline                   ${col.d('(beta)')}   Behavior baseline: [learn|show|compare|reset]
+
+${col.b('Audit')} ${col.d('— tamper-evidence and attestation')}
+  audit verify               ${col.d('(stable)')} Verify hash chain in pipeline-events.jsonl
+  audit repair               ${col.d('(stable)')} Truncate crash-partial trailing line (--file --dry-run)
+  attest --run-id <uuid>     ${col.d('(stable)')} Behavioral attestation: hash-chain + execution summary
+                             ${col.d('Add --sign in GitHub Actions for Sigstore keyless signing')}
+  attest verify <file>       ${col.d('(stable)')} Re-verify signed attestation (bundle + DSSE + chain)
+  selftest                   ${col.d('(stable)')} Run governance self-checks on scratch chain
+
+${col.b('Detect')} ${col.d('— anomalies, adversarial probes')}
+  anomalies                  ${col.d('(beta)')}   Windowed EDR over the audit chain (--window 15m --json)
+  harness                    ${col.d('(alpha)')}  Real Claude Code run vs. governance claims (API key required)
+  redteam                    ${col.d('(alpha)')}  Autonomous adversarial probe (API key + SDK required)
+
+${col.b('Policy & extras')}
+  policy [show]              ${col.d('(stable)')} Show active policy: flags, routing, overrides
+  policy show --diff         ${col.d('(stable)')} Only values that differ from defaults
+  policy validate            ${col.d('(stable)')} Validate policy.yml and report errors/warnings
+  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 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
@@ -67,8 +90,9 @@ ${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)
-  --verbose                     Print live per-request chatter (off by default — quiet for Claude Code's TUI)
+  --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:')}
   Default               → Claude Code adapter

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/cli/status.js

@@ -26,7 +26,7 @@ function todayStr() {
 function getLogFile() { return path.join(LOG_DIR, 'logs', `${todayStr()}.jsonl`); }
 
 function run() {
-  let s = null; try { s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8')); } catch {}
+  let s = null; try { s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8')); } catch { /* ignore */ }
   console.log(col.b('\n⚡ Occasio\n'));
   if (!s) { console.log(col.d('  No session data yet. Run: occasio claude\n')); return; }
 

package/src/dashboard.js

@@ -16,7 +16,6 @@ const path = require('path');
 const os   = require('os');
 
 const DASHBOARD_PORT = 3001;
-const PROXY_PORT     = 8081;
 const LOG_DIR      = path.join(os.homedir(), '.occasio');
 const SESSION_FILE = path.join(LOG_DIR, 'session.json');
 
@@ -97,8 +96,8 @@ const server = http.createServer((req, res) => {
   }
 
   if (req.url === '/api/clear' && req.method === 'POST') {
-    try { fs.writeFileSync(todayLogFile(), ''); } catch {}
-    try { fs.writeFileSync(SESSION_FILE, '{}'); } catch {}
+    try { fs.writeFileSync(todayLogFile(), ''); } catch { /* ignore */ }
+    try { fs.writeFileSync(SESSION_FILE, '{}'); } catch { /* ignore */ }
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end('{"ok":true}');
     broadcast({ type: 'update', session: {}, entries: [] });