@occasiolabs/occasio 0.8.1

package/src/demo/README.md

@@ -0,0 +1,31 @@
+# `src/demo/` — production CLI demos
+
+The files in this folder back the `occasio demo <name>` CLI subcommands. They are **production features**, not throwaway scaffolding: they ship in the npm package, are linked from the project README, and are the first-impression artifact for design partners, investors, and auditors evaluating the project.
+
+## What "demo" means here
+
+Each file in this folder implements one runnable CLI demo that exercises a full Occasio pipeline end-to-end against synthetic data, in seconds, with no external dependencies (no API key, no GitHub Actions, no network). The synthetic-data choice is deliberate:
+
+- Demos never touch the user's real `~/.occasio/pipeline-events.jsonl` audit chain
+- Demos do not require credentials or sign-in
+- Demos exercise the same code paths the real CLIs use (`buildAttestation`, `runDetectors`, etc.) — they wrap the production primitives rather than re-implementing them
+- A passing `occasio demo X` is also a smoke test for the underlying schiene
+
+## Files
+
+| File | CLI command | What it demonstrates |
+|---|---|---|
+| `attest-demo.js` | `occasio demo attest` | Build → verify → check-run-preview for the attestation pipeline |
+| `anomalies-demo.js` | `occasio demo anomalies` | Synthetic adversarial chain → all 4 EDR detectors fire |
+
+## Naming convention
+
+`demo/<feature>-demo.js` exports `run<Feature>DemoCli(args)` and is wired into the top-level CLI dispatcher (`src/index.js`) under `cmd === 'demo' && args[1] === '<feature>'`. The two-token CLI form (`occasio demo <feature>`) keeps these visible as a coherent demo surface in `occasio --help` without polluting the top-level command namespace.
+
+If you need a CLI that operates against real user data (not synthetic), it does not belong here — put it directly in `src/<feature>/cli.js` next to the production primitives.
+
+## Why not put these in `examples/`
+
+`examples/` (sibling of `src/`) is for static example files users copy into their own setup — `policy.yml` templates, GitHub Action YAML snippets, JSONL fixtures. The contents of `examples/` are read by the user, not executed by Occasio.
+
+`src/demo/` is for executable demos that ship as installable CLI commands. Different distribution path, different audience.

package/src/demo/anomalies-demo.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * demo/anomalies-demo.js — `occasio demo anomalies`
+ *
+ * Production CLI command, first-class user-facing feature. See
+ * src/demo/README.md for the folder convention. Builds a synthetic
+ * adversarial audit chain in a temp dir and runs all four anomaly
+ * detectors against it. Each detector is designed to fire on exactly
+ * one of the four written patterns:
+ *
+ *   deny-rate           pattern: 12 BLOCK rows in the recent window
+ *                                (vs. a quiet historical baseline)
+ *   file-read-volume    pattern: 60 distinct file paths read in window
+ *                                (vs. historical p95 ≈ 5)
+ *   unknown-tool-input  pattern: Bash invoked with novel `env` key
+ *                                (after 60 historical "Bash {command, cwd}" rows)
+ *   secret-redact-rate  pattern: 3 redacted-secret rows in window
+ *                                (vs. zero in 250 historical rows)
+ *
+ * Never touches ~/.occasio — uses os.tmpdir() throughout.
+ *
+ * Used by:
+ *   - Smoke-testing the EDR layer end-to-end
+ *   - First-time demo / "show me what would have fired in our last shift"
+ *   - Reference for what a real adversarial-activity chain shape looks like
+ */
+
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+const crypto = require('crypto');
+
+const { runDetectors, DEFAULT_WINDOW_MS } = require('../anomaly');
+
+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`,
+};
+
+const SEV_COLOR = { high: C.r, medium: C.y, low: C.c };
+
+const GENESIS  = '0'.repeat(64);
+const RUN_ID   = '12345678-1234-1234-1234-123456789abc';
+
+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;
+}
+
+/**
+ * Build the adversarial chain. Returns the file path + the "now" anchor we
+ * should evaluate against (cleaner than relying on wall clock).
+ *
+ * Timeline:
+ *   t = NOW - 3h ...... NOW - 20m  → historical baseline (quiet)
+ *   t = NOW - 10m ..... NOW         → window (the anomalies live here)
+ */
+function buildAdversarialChain(chainFile) {
+  fs.writeFileSync(chainFile, '');
+  const NOW = Date.parse('2026-05-14T16:00:00.000Z');
+  const tIso = (msAgo) => new Date(NOW - msAgo).toISOString();
+  let prev = GENESIS;
+
+  // ── Historical baseline ────────────────────────────────────────────────
+  // 300 quiet rows over 3h: tool reads against a small file pool, no BLOCKs,
+  // no redactions, all Bash calls use only { command, cwd } keys.
+  const baselinePaths = ['a.js', 'b.js', 'c.js', 'd.js', 'e.js'];
+  for (let i = 0; i < 300; i++) {
+    const msAgo = 3 * 60 * 60 * 1000 - i * Math.floor((3 * 60 * 60 * 1000 - 20 * 60 * 1000) / 300);
+    if (i % 3 === 0) {
+      prev = appendRow(chainFile, prev, {
+        ts: tIso(msAgo),
+        kind: 'tool_call', tool_name: 'Read', action: 'PASS',
+        tool_inputs: { path: 'src/' + baselinePaths[i % baselinePaths.length] },
+        run_id: RUN_ID,
+      });
+    } else if (i % 3 === 1) {
+      prev = appendRow(chainFile, prev, {
+        ts: tIso(msAgo),
+        kind: 'tool_call', tool_name: 'Grep', action: 'PASS',
+        tool_inputs: { pattern: 'TODO', path: 'src/' },
+        run_id: RUN_ID,
+      });
+    } else {
+      prev = appendRow(chainFile, prev, {
+        ts: tIso(msAgo),
+        kind: 'tool_call', tool_name: 'Bash', action: 'PASS',
+        tool_inputs: { command: 'ls', cwd: '/workspace' },
+        run_id: RUN_ID,
+      });
+    }
+  }
+
+  // ── Window: adversarial activity (last ~10 minutes) ────────────────────
+  // Each block below intentionally triggers one of the four detectors.
+
+  // (1) Deny-rate spike — 12 rapid BLOCKs on sensitive paths
+  for (let i = 0; i < 12; i++) {
+    prev = appendRow(chainFile, prev, {
+      ts: tIso(10 * 60_000 - i * 30_000),
+      kind: 'tool_call', tool_name: 'Read', action: 'BLOCK',
+      tool_inputs: { path: '/home/user/.ssh/id_rsa' },
+      reason: 'path-denied',
+      run_id: RUN_ID,
+    });
+  }
+
+  // (2) File-read-volume burst — 60 distinct paths, all new
+  for (let i = 0; i < 60; i++) {
+    prev = appendRow(chainFile, prev, {
+      ts: tIso(8 * 60_000 - i * 5_000),
+      kind: 'tool_call', tool_name: 'Read', action: 'PASS',
+      tool_inputs: { path: `recon/discovered-${i}.cfg` },
+      run_id: RUN_ID,
+    });
+  }
+
+  // (3) Unknown-tool-input — Bash invoked with previously-unseen `env` key
+  prev = appendRow(chainFile, prev, {
+    ts: tIso(5 * 60_000),
+    kind: 'tool_call', tool_name: 'Bash', action: 'PASS',
+    tool_inputs: { command: 'curl https://example.com', cwd: '/workspace',
+                   env: { LD_PRELOAD: '/tmp/x.so' } },
+    run_id: RUN_ID,
+  });
+
+  // (4) Secret-redact-rate — 3 redaction events
+  for (let i = 0; i < 3; i++) {
+    prev = appendRow(chainFile, prev, {
+      ts: tIso(3 * 60_000 - i * 30_000),
+      kind: 'tool_call', tool_name: 'Grep', action: 'TRANSFORM',
+      tool_inputs: { pattern: 'sk-ant-', path: 'src/' },
+      secrets_redacted: 1,
+      run_id: RUN_ID,
+    });
+  }
+
+  return { chainFile, nowMs: NOW };
+}
+
+function runAnomaliesDemoCli(_args = []) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lf-demo-anomalies-'));
+  const chainFile = path.join(tmpDir, 'pipeline-events.jsonl');
+
+  process.stdout.write(`${C.b('occasio demo anomalies')}\n`);
+  process.stdout.write(`${C.d('  scratch dir: ' + tmpDir)}\n\n`);
+
+  // ── Step 1 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('1.')} Building synthetic adversarial chain  ${C.d('(300 quiet baseline rows + 4 distinct anomaly patterns in last 10 min)')}\n`);
+  const { nowMs } = buildAdversarialChain(chainFile);
+  const stat = fs.statSync(chainFile);
+  process.stdout.write(`   ${C.g('✓')} ${C.d(chainFile + ' (' + stat.size + ' bytes)')}\n\n`);
+
+  // ── Step 2 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('2.')} Running detectors over the last ${C.c('15 minutes')}  ${C.d('(window vs. historical baseline)')}\n\n`);
+  const result = runDetectors({
+    chainFile,
+    windowMs: DEFAULT_WINDOW_MS,
+    now: nowMs,
+  });
+
+  process.stdout.write(`   ${C.d('window: ' + result.window_start + ' → ' + result.window_end)}\n`);
+  process.stdout.write(`   ${C.d(result.window_rows + ' rows in window, ' + result.history_rows + ' historical)')}\n\n`);
+
+  if (result.alerts.length === 0) {
+    process.stderr.write(`   ${C.r('✗ no alerts fired — detectors are silent on activity that should trigger them')}\n`);
+    return 1;
+  }
+
+  for (const a of result.alerts) {
+    const color = SEV_COLOR[a.severity] || C.d;
+    process.stdout.write(`   ${color('[' + a.severity.toUpperCase() + ']')} ${C.b(a.detector_id)}\n`);
+    process.stdout.write(`       ${a.message}\n`);
+    if (a.rows_implicated && a.rows_implicated.length) {
+      process.stdout.write(`       ${C.d('implicated: ' + a.rows_implicated[0].slice(0, 16) +
+        '…  (+' + (a.rows_implicated.length - 1) + ' more)')}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // ── Step 3 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('3.')} Verifying all four built-in detectors fired\n`);
+  const fired = new Set(result.alerts.map(a => a.detector_id));
+  const expected = ['deny-rate', 'file-read-volume', 'unknown-tool-input', 'secret-redact-rate'];
+  let allFired = true;
+  for (const id of expected) {
+    if (fired.has(id)) {
+      process.stdout.write(`   ${C.g('✓')} ${id}\n`);
+    } else {
+      process.stdout.write(`   ${C.r('✗')} ${id} ${C.d('— did NOT fire on its trigger pattern (regression!)')}\n`);
+      allFired = false;
+    }
+  }
+  process.stdout.write('\n');
+
+  if (!allFired) return 1;
+  process.stdout.write(`${C.g('✓')} EDR layer end-to-end OK  ${C.d('(scratch chain preserved at ' + tmpDir + ')')}\n`);
+  process.stdout.write(`\n${C.d('Re-run against the same chain interactively:')}\n`);
+  process.stdout.write(`   ${C.c('occasio anomalies --chain ' + chainFile + ' --since "' + new Date(nowMs).toISOString() + '"')}\n\n`);
+  return 0;
+}
+
+module.exports = { runAnomaliesDemoCli, buildAdversarialChain };

package/src/demo/attest-demo.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * demo/attest-demo.js — `occasio demo attest`
+ *
+ * Production CLI command, first-class user-facing feature. The `demo/`
+ * folder houses CLIs that exercise a full pipeline against synthetic
+ * data so users can see the system end-to-end in seconds without
+ * touching their real ~/.occasio chain. These are demos in the
+ * sense of "demonstrations" — they are not throwaway scaffolding,
+ * they ship in the npm package and are documented in the README.
+ *
+ * End-to-end demo of the attestation pipeline, locally, without GitHub
+ * Actions or external services. Runs against a synthetic audit chain so
+ * it never touches the user's real ~/.occasio/pipeline-events.jsonl.
+ *
+ * Flow demonstrated:
+ *   1. Build a hash-chained scratch audit chain (3 PASS + 1 BLOCK + 1
+ *      TRANSFORM with redacted secret + 1 policy_loaded row)
+ *   2. Verify the chain integrity (mirrors `occasio audit verify`)
+ *   3. Build an unsigned attestation for the synthetic run_id
+ *   4. Verify the predicate ↔ attestation byte-equivalence (canonical
+ *      JSON round-trip) without invoking Sigstore — the test harness
+ *      validates the cryptographic path elsewhere
+ *   5. Print what the GitHub Check Run summary WOULD look like
+ *   6. Render the same data as the View-Evidence page would render it
+ *
+ * Used by:
+ *   - First-time demo / "show me what this does end-to-end"
+ *   - Smoke test in CI for the full predicate happy path
+ *   - Reference Pipeline doc (docs/reference-pipeline.md)
+ */
+
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+const crypto = require('crypto');
+
+const { buildAttestation }      = require('../attest');
+const { verifyFile }            = require('../audit/verifier');
+const { canonicalize }          = require('../attest/canonicalize');
+const { buildSummary }          = require('../../integrations/attest-action/scripts/post-check');
+
+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`,
+};
+
+const GENESIS = '0'.repeat(64);
+
+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 buildSyntheticChain(chainFile, policyFile) {
+  // Reset the chain file fresh.
+  fs.writeFileSync(chainFile, '');
+  fs.writeFileSync(policyFile, [
+    'version: 1',
+    'deny_paths:',
+    '  - "**/.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 = (s) => new Date(Date.UTC(2026, 0, 1, 12, 0, s)).toISOString();
+
+  // 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',
+  }));
+  // PASS read
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(5), event_id: crypto.randomUUID(),
+    run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Read', action: 'PASS',
+    tool_inputs: { path: 'src/index.js' },
+  }));
+  // BLOCK on denied path
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(10), event_id: crypto.randomUUID(),
+    run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Read', action: 'BLOCK',
+    tool_inputs: { path: '/home/user/.ssh/id_rsa' },
+    reason: 'path-denied',
+  }));
+  // TRANSFORM with redacted secret in result
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(15), event_id: crypto.randomUUID(),
+    run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Grep', action: 'TRANSFORM',
+    tool_inputs: { pattern: 'TODO', path: 'src/' },
+    secrets_redacted: 1,
+  }));
+  // LOCAL Glob
+  ({ hash: prev } = appendRow(chainFile, prev, {
+    ts: ts(20), event_id: crypto.randomUUID(),
+    run_id: RUN_ID, agent: 'claude-code',
+    kind: 'tool_call', tool_name: 'Glob', action: 'LOCAL',
+    tool_inputs: { pattern: '**/*.js' },
+  }));
+
+  return RUN_ID;
+}
+
+async function runAttestDemoCli(_args = []) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lf-demo-attest-'));
+  const chainFile  = path.join(tmpDir, 'pipeline-events.jsonl');
+  const policyFile = path.join(tmpDir, 'policy.yml');
+  const outFile    = path.join(tmpDir, 'occasio-attestation.json');
+
+  process.stdout.write(`${C.b('occasio demo attest')}\n`);
+  process.stdout.write(`${C.d('  scratch dir: ' + tmpDir)}\n\n`);
+
+  // ── Step 1 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('1.')} Building synthetic audit chain  ${C.d('(5 rows: policy_loaded + Read PASS + Read BLOCK + Grep TRANSFORM/redacted + Glob LOCAL)')}\n`);
+  const runId = buildSyntheticChain(chainFile, policyFile);
+  process.stdout.write(`   ${C.g('✓')} run_id: ${C.c(runId)}\n\n`);
+
+  // ── Step 2 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('2.')} Verifying audit-chain integrity  ${C.d('(SHA-256-walk every prev_hash → hash link)')}\n`);
+  const ver = verifyFile(chainFile);
+  if (!ver.ok) {
+    process.stderr.write(`   ${C.r('✗')} chain broken — this should not happen on a synthetic chain\n`);
+    return 1;
+  }
+  process.stdout.write(`   ${C.g('✓')} chain integrity OK  ${C.d('(' + ver.chained + ' rows)')}\n\n`);
+
+  // ── Step 3 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('3.')} Building behavioral attestation  ${C.d('(unsigned — signing requires Sigstore + GitHub OIDC)')}\n`);
+  const att = buildAttestation({ runId, logFile: chainFile, policyFile });
+  if (!att) {
+    process.stderr.write(`   ${C.r('✗')} buildAttestation returned null\n`);
+    return 1;
+  }
+  fs.writeFileSync(outFile, JSON.stringify(att, null, 2));
+  process.stdout.write(`   ${C.g('✓')} ${C.d(outFile)}\n`);
+  process.stdout.write(`     ${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)}\n`);
+  process.stdout.write(`     ${C.d('chain: ' + att.audit_chain.first_hash.slice(0,12) + '…' +
+    att.audit_chain.last_hash.slice(0,12) + '  (' + att.audit_chain.event_count + ' events)')}\n`);
+  process.stdout.write(`     ${C.d('policy: ' + att.policy.source + '  hash=' +
+    att.policy.file_hash.slice(0,16) + '…')}\n\n`);
+
+  // ── Step 4 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('4.')} Canonical-JSON byte-equivalence  ${C.d('(predicate parsed back from disk vs in-memory attestation)')}\n`);
+  const reparsed = JSON.parse(fs.readFileSync(outFile, 'utf8'));
+  const { signature: _omit1, ...expected } = att;
+  const { signature: _omit2, ...observed } = reparsed;
+  if (canonicalize(expected) !== canonicalize(observed)) {
+    process.stderr.write(`   ${C.r('✗')} canonical bytes diverged — this is a bug\n`);
+    return 1;
+  }
+  process.stdout.write(`   ${C.g('✓')} canonical round-trip stable\n\n`);
+
+  // ── Step 5 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('5.')} GitHub Check Run preview  ${C.d('(this is what reviewers see on the PR)')}\n`);
+  const { title, summary } = buildSummary(att, '');
+  process.stdout.write(`\n   ${C.b('Title:')} ${title}\n\n`);
+  for (const line of summary.split('\n').slice(0, 12)) {
+    process.stdout.write(`   ${line}\n`);
+  }
+  process.stdout.write(`   ${C.d('… (table truncated; full body in the live Check Run)')}\n\n`);
+
+  // ── Step 6 ─────────────────────────────────────────────────────────────
+  process.stdout.write(`${C.b('6.')} Next steps for a live deployment\n`);
+  process.stdout.write(`   - Add ${C.c('.github/workflows/attest-on-pr.yml')} from ${C.d('docs/reference-pipeline.md')}\n`);
+  process.stdout.write(`   - Grant the workflow ${C.c('id-token: write')} + ${C.c('checks: write')} permissions\n`);
+  process.stdout.write(`   - Push a PR; the Action will sign via Sigstore keyless and post a Check Run\n`);
+  process.stdout.write(`   - Auditors verify offline: ${C.c('occasio attest verify <file>')}\n\n`);
+  process.stdout.write(`${C.d('Scratch artifacts kept at ' + tmpDir + ' for inspection.')}\n`);
+
+  return 0;
+}
+
+module.exports = { runAttestDemoCli, buildSyntheticChain };

package/src/distiller.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * distiller.js — Output distillation for intercepted tool results.
+ *
+ * Applies conservative line-count limits to high-volume, low-risk, read-only
+ * command output before it re-enters the model as a tool_result.
+ *
+ * Rules:
+ *   grep / rg       → clip at GREP_MAX_LINES
+ *   find            → clip at FIND_MAX_LINES
+ *   ls / dir / gci  → clip at LS_MAX_LINES
+ *   git log         → clip at GIT_LOG_MAX_LINES
+ *   test runners    → smart extraction: failures + summary, clip at TEST_MAX_LINES
+ *
+ * All other commands pass through unchanged.
+ * Short output (below threshold) passes through unchanged.
+ *
+ * result.rawContent is set to the original string when output was distilled,
+ * so callers can persist it for replay/debugging.
+ */
+
+const GREP_MAX_LINES    = 50;
+const FIND_MAX_LINES    = 100;
+const LS_MAX_LINES      = 100;
+const GIT_LOG_MAX_LINES = 100;
+const TEST_MAX_LINES    = 100;
+
+/**
+ * Map a command string to its distillation category.
+ * Returns null when no rule applies.
+ */
+function classifyCmd(cmd) {
+  if (!cmd) return null;
+  const parts = cmd.trim().split(/\s+/);
+  const head  = parts[0].toLowerCase();
+
+  if (head === 'grep' || head === 'rg')                          return 'grep';
+  if (head === 'find')                                           return 'find';
+  if (['ls','eza','exa','lsd','dir'].includes(head))             return 'ls';
+  if (/^get-childitem$/i.test(parts[0]))                         return 'ls';
+  if (head === 'git' && parts[1] === 'log')                      return 'git-log';
+
+  // Test runners
+  if (['jest','vitest','pytest','py.test'].includes(head))       return 'test';
+  if (head === 'cargo' && parts[1] === 'test')                   return 'test';
+  if (head === 'go'    && parts[1] === 'test')                   return 'test';
+  if (['npm','npx','yarn','pnpm'].includes(head)) {
+    const sub = (parts[1] || '').toLowerCase();
+    if (sub === 'test' || sub === 'jest' || sub === 'vitest' || sub === 'run') {
+      // npm run test / yarn run test etc. — only classify as test when sub-cmd is test-like
+      if (sub === 'run') {
+        const subsub = (parts[2] || '').toLowerCase();
+        if (subsub === 'test' || subsub === 'jest' || subsub === 'vitest') return 'test';
+      } else {
+        return 'test';
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Distill a single tool-result output string.
+ *
+ * @param {string} cmd    The command that produced the output
+ * @param {string} output The raw output string
+ * @returns {{
+ *   content:     string,        // what to send to Anthropic
+ *   distilled:   boolean,
+ *   savedTokens: number,        // estimated tokens saved (bytes/4)
+ *   label:       string,        // human-readable label for logs
+ *   rawBytes:    number,        // original byte count (for ledger)
+ *   rawContent:  string | null, // original output when distilled; null when not distilled
+ * }}
+ */
+function distill(cmd, output) {
+  const rawBytes = Buffer.byteLength(output || '', 'utf8');
+  const none = { content: output, distilled: false, savedTokens: 0, label: '', rawBytes, rawContent: null };
+
+  if (!output || !cmd) return none;
+
+  const category = classifyCmd(cmd);
+  if (!category) return none;
+
+  // Test output uses smart failure-preserving extraction
+  if (category === 'test') return distillTestOutput(output, rawBytes, cmd);
+
+  const lines = output.split('\n');
+
+  let maxLines;
+  let unitLabel;
+  switch (category) {
+    case 'grep':     maxLines = GREP_MAX_LINES;     unitLabel = 'match lines'; break;
+    case 'find':     maxLines = FIND_MAX_LINES;     unitLabel = 'paths';       break;
+    case 'ls':       maxLines = LS_MAX_LINES;       unitLabel = 'entries';     break;
+    case 'git-log':  maxLines = GIT_LOG_MAX_LINES;  unitLabel = 'log lines';   break;
+    default: return none;
+  }
+
+  if (lines.length <= maxLines) return none;
+
+  const nonEmpty = lines.filter(l => l.trim()).length;
+  const content  = lines.slice(0, maxLines).join('\n')
+    + `\n[Occasio: ${nonEmpty} ${unitLabel} total — showing first ${maxLines}. Full output not re-sent to model.]`;
+
+  const savedBytes  = Math.max(0, rawBytes - Buffer.byteLength(content, 'utf8'));
+  const savedTokens = Math.ceil(savedBytes / 4);
+  const label       = `${category} clipped ${nonEmpty}→${maxLines} ${unitLabel}`;
+
+  return { content, distilled: true, savedTokens, label, rawBytes, rawContent: output };
+}
+
+// Regex matching lines that likely contain test failures or errors.
+const FAIL_RE = /\b(FAIL|FAILED|ERROR|error:|✗|×|AssertionError|not ok|ERRORED)\b/;
+
+/**
+ * Smart distillation for test-runner output.
+ * Keeps all failure-related lines (plus 1 line of context each side) and the
+ * last 15 lines (usually the summary).  Clips total to TEST_MAX_LINES.
+ */
+function distillTestOutput(output, rawBytes, cmd) {
+  const lines = output.split('\n');
+  const none  = { content: output, distilled: false, savedTokens: 0, label: '', rawBytes, rawContent: null };
+  if (lines.length <= TEST_MAX_LINES) return none;
+
+  // Collect indices worth preserving
+  const keepIdx = new Set();
+
+  // Failure context lines
+  lines.forEach((l, i) => {
+    if (FAIL_RE.test(l)) {
+      if (i > 0) keepIdx.add(i - 1);
+      keepIdx.add(i);
+      if (i < lines.length - 1) keepIdx.add(i + 1);
+    }
+  });
+
+  // Always keep the last 15 lines (pass/fail summary)
+  for (let i = Math.max(0, lines.length - 15); i < lines.length; i++) keepIdx.add(i);
+
+  const chosen = [...keepIdx].sort((a, b) => a - b).map(i => lines[i]);
+  const totalNonEmpty = lines.filter(l => l.trim()).length;
+  const note = `[Occasio: test output ${totalNonEmpty} lines — showing ${chosen.length} failure/summary lines. Full output saved for inspection: occasio distill]`;
+  const content = chosen.join('\n') + '\n' + note;
+
+  const savedBytes  = Math.max(0, rawBytes - Buffer.byteLength(content, 'utf8'));
+  const savedTokens = Math.ceil(savedBytes / 4);
+  const label       = `test clipped ${totalNonEmpty}→${chosen.length} lines (failures+summary)`;
+
+  return { content, distilled: true, savedTokens, label, rawBytes, rawContent: output };
+}
+
+module.exports = { distill, classifyCmd, GREP_MAX_LINES, FIND_MAX_LINES, LS_MAX_LINES, GIT_LOG_MAX_LINES, TEST_MAX_LINES, FAIL_RE };

package/src/embeddings.json

@@ -0,0 +1,72 @@
+{
+  "version": "1.0",
+  "description": "Class centroids for local routing decisions. Edit to extend without touching code.",
+
+  "always_local": [
+    "grep", "rg", "fd", "fzf",
+    "find", "locate",
+    "ls", "eza", "exa", "lsd", "tree",
+    "cat", "bat", "less", "more", "head", "tail",
+    "wc", "nl", "sort", "uniq", "cut", "tr",
+    "echo", "pwd", "which", "whereis", "where", "type",
+    "stat", "file", "du", "df", "dir",
+    "diff", "delta",
+    "date", "uptime", "uname",
+    "ps", "top", "htop"
+  ],
+  "_removed_from_always_local": {
+    "env": "may expose API keys/tokens — output bypasses outbound secret scanner when intercepted",
+    "printenv": "same reason as env"
+  },
+
+  "never_local": [
+    "rm", "rmdir", "del",
+    "npm", "npx", "pip", "pip3", "yarn", "pnpm", "cargo", "gem", "go", "mvn", "gradle",
+    "curl", "wget", "fetch",
+    "ssh", "scp", "sftp", "rsync",
+    "docker", "kubectl", "helm", "terraform", "ansible",
+    "python", "python3", "node", "ruby", "java", "perl", "php", "lua",
+    "make", "cmake", "gcc", "g++", "clang", "rustc", "javac",
+    "touch", "mkdir", "cp", "mv",
+    "chmod", "chown", "chgrp",
+    "kill", "pkill", "killall",
+    "tee", "dd",
+    "apt", "apt-get", "brew", "pacman", "yum", "dnf"
+  ],
+
+  "git_safe_subcommands": [
+    "log", "status", "diff", "show", "blame",
+    "branch", "tag",
+    "remote",
+    "stash",
+    "describe", "shortlog", "rev-parse",
+    "ls-files", "ls-remote", "ls-tree",
+    "cat-file", "count-objects",
+    "help", "version",
+    "bisect"
+  ],
+  "_removed_from_git_safe": {
+    "config": "git config without --get/--list is a write command (user.email, core.hooksPath, etc.)"
+  },
+
+  "git_unsafe_subcommands": [
+    "push", "pull", "fetch",
+    "commit", "merge", "rebase", "cherry-pick", "am",
+    "reset", "restore", "checkout", "switch",
+    "add", "rm", "mv",
+    "clean", "gc",
+    "init", "clone",
+    "submodule", "worktree"
+  ],
+
+  "dangerous_flags": [
+    "--force", "-f",
+    "--delete", "-D",
+    "--hard",
+    "--no-verify",
+    "--allow-unrelated-histories",
+    "--squash"
+  ],
+
+  "confidence_threshold": 0.5
+}