@occasiolabs/occasio 0.8.3 → 0.8.4

package/README.md

@@ -83,6 +83,7 @@ occasio attest --run-id <uuid>  # Build a behavioral attestation for one session
 | `occasio distill` | Inspect distilled tool outputs |
 | `occasio dashboard` | Live browser dashboard at http://localhost:3001 |
 | `occasio audit verify` | Re-walk the SHA-256 audit chain end-to-end |
+| `occasio audit repair --file <path>` | Truncate a crash-partial trailing line (writes `.bak`) |
 | `occasio report` | Governance summary export (`--days N`, `--format csv`) |
 | `occasio anomalies` | EDR detection over the audit chain (`--window 15m`, `--json`) |
 | `occasio attest --run-id <uuid>` | Build a behavioral attestation predicate v1 |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,171 @@
+# Occasio Architecture
+
+A high-level map of the request pipeline and where each module lives.
+Use this as the orientation document before reading individual files.
+
+## Pipeline
+
+Every tool call from a coding agent travels the same five-stage pipeline,
+regardless of the upstream protocol (Anthropic SSE, MCP, computer-use).
+Each stage produces input for the next; nothing skips the auditor.
+
+```
+            agent (Claude Code, MCP client, computer-use loop)
+                                  |
+                                  v
+   +--------------+    raw events      +-----------------+
+   |   Adapter    | -----------------> |  Boundary event |
+   | src/adapters |                    |   src/core/     |
+   +--------------+                    +-----------------+
+                                              |
+                                              v
+                                      +-----------------+
+                                      |     Policy      |
+                                      |   src/policy/   |
+                                      +-----------------+
+                                              |
+                                       Decision { action,
+                                       reason, transform,
+                                       executor }
+                                              |
+                                              v
+                                      +-----------------+
+                                      |   Dispatcher    |
+                                      |  src/dispatch/  |
+                                      +-----------------+
+                                              |
+                                       Result { passThrough,
+                                       blocked, transformed,
+                                       exitCode, ... }
+                                              |
+                                              v
+                                      +-----------------+
+                                      |    Auditor      |
+                                      | src/audit/      |
+                                      +-----------------+
+                                              |
+                                              v
+                                      +-----------------+
+                                      |     Attest      |
+                                      |  src/attest/    |
+                                      +-----------------+
+                                              |
+                                              v
+                                in-toto + Sigstore bundle
+```
+
+## Stages
+
+### 1. Adapter — `src/adapters/`
+
+Each upstream protocol has its own adapter (`claude-code.js`,
+`mcp-server.js`, `computer-use.js`). Adapters turn raw transport frames
+(SSE deltas, JSON-RPC, screenshots) into a canonical `BoundaryEvent`
+defined in `src/core/boundary-event.js`. Downstream stages know nothing
+about the protocol of origin — that is the whole point of the boundary.
+
+### 2. Policy — `src/policy/`
+
+`engine.js` is a pure function over `(event, policy)` returning a
+`Decision`. `loader.js` parses the YAML-subset policy file with hot
+reload via watcher. `pattern-store.js` and `pathset.js` provide path
+matching and deny-list semantics. The engine itself does no I/O — every
+side effect happens in the dispatcher.
+
+### 3. Dispatcher — `src/dispatch/`
+
+Routes a Decision to one of three executors:
+
+- `executors/cloud.js` — forward to the upstream LLM provider.
+- `executors/local.js` — execute interceptable tools locally
+  (Read, Glob, Grep, TodoWrite, bounded shell reads).
+- `executors/block.js` — return a deny response without making the call.
+
+Transforms (redaction, distillation) run before execution and are
+recorded as part of the Result.
+
+### 4. Auditor — `src/audit/`
+
+`jsonl-auditor.js` appends one tamper-evident row per
+`(event, decision, result)` tuple to `~/.occasio/pipeline-events.jsonl`.
+
+Key properties:
+
+- Each row carries `prev_hash` (SHA-256 of the previous row's `hash`)
+  and `hash` (SHA-256 of the row minus the hash field).
+- The first row's `prev_hash` is `GENESIS` (64 zero hex digits).
+- Field order in the row literal is canonical and load-bearing. The
+  Python walker in `docs/audit_walker.py` mirrors that order so chain
+  verification does not depend on trusting Occasio's own code.
+- `audit_schema: 1` versions every new row. Verifier accepts legacy
+  schema-less rows; unknown future versions log a warning but do not
+  flip ok=false.
+- `loadPrevHash()` reads only the trailing 64KB of the log so bootstrap
+  on a million-row chain stays O(window) instead of O(file).
+- On a partial trailing line (crash mid-append), `loadPrevHash` fails
+  hard with `AUDIT_CORRUPT`. Use `occasio audit repair --file <path>`
+  to truncate the partial line; a `.bak` is written first.
+
+Subcommands:
+
+```
+occasio audit verify [--file <path>]
+occasio audit repair --file <path> [--dry-run]
+```
+
+### 5. Attest — `src/attest/`
+
+At the end of a session (or on demand), the attest module builds an
+in-toto statement covering the chain segment between two hashes and
+signs it with Sigstore (keyless Fulcio + Rekor). The browser viewer in
+`integrations/attest-view/` can re-verify the bundle.
+
+## Cross-cutting concerns
+
+- **Tool-name registry** (`src/core/tool-names.js`) holds canonical
+  tool identifiers. Adapters emit only canonical names. New tools must
+  be registered there first.
+- **Boundary events** (`src/core/boundary-event.js`) are the only
+  cross-stage data type. If a stage needs a new field, add it to the
+  boundary event rather than passing it through a side channel.
+- **Cost & ledger** (`src/cost/`) tracks tokens, model prices, and
+  per-session spend. The pipeline emits cost events into the same
+  audit log, chained with the rest.
+- **Policy hot-reload** records a `policy_loaded` audit row whose hash
+  links into the same chain — a policy swap is a first-class event.
+
+## What lives where
+
+| Concern               | Path                          |
+|-----------------------|-------------------------------|
+| HTTP proxy            | `src/index.js`, `bin/`        |
+| Anthropic SSE         | `src/adapters/claude-code.js` |
+| MCP server            | `src/adapters/mcp-server.js`  |
+| Policy DSL            | `src/policy/loader.js`        |
+| Policy engine         | `src/policy/engine.js`        |
+| Dispatcher            | `src/dispatch/`               |
+| Local tool execution  | `src/dispatch/executors/local.js` |
+| Audit chain           | `src/audit/jsonl-auditor.js`  |
+| Audit repair          | `src/audit/repair.js`         |
+| Audit verifier        | `src/audit/verifier.js`       |
+| Attestation           | `src/attest/index.js`         |
+| Cost/ledger           | `src/cost/`                   |
+
+## What is intentionally NOT in this diagram
+
+- Telemetry: there is none, by design.
+- Background daemons: audit writes happen synchronously on the
+  request-handling path. A queue-based async writer is a roadmap item
+  (`src/audit/queue.js` is reserved) but has not landed.
+- Database: every persisted artifact is an append-only file. No SQL,
+  no migrations to manage at runtime.
+
+## Reading order for new contributors
+
+1. `src/core/boundary-event.js` — what flows through the pipeline.
+2. `src/policy/engine.js` — pure-function decisions.
+3. `src/audit/jsonl-auditor.js` — the hash-chain invariant.
+4. `src/dispatch/index.js` — how Decisions become Results.
+5. `test-audit-chain.js` — the scenarios the auditor must survive.
+
+After those five files the rest of the codebase reads quickly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occasiolabs/occasio",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "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",
   "files": [
@@ -14,7 +14,9 @@
     "NOTICE"
   ],
   "scripts": {
-    "test": "node test-interceptor.js",
+    "test": "node test-interceptor.js && node test-audit-chain.js && node test-attest.js && node test-policy-paths.js",
+    "lint": "eslint src/audit src/attest",
+    "lint:all": "eslint src bin",
     "smoke": "node test-smoke.js",
     "test:mcp": "node test-mcp-server.js",
     "restart-check": "node scripts/restart-check.js",
@@ -64,6 +66,10 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "proper-lockfile": "^4.1.2",
     "sigstore": "^3.1.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.4"
   }
 }

package/src/attest/check-summary.js

@@ -42,7 +42,7 @@ function mdText(s) {
   if (s === null || s === undefined) return '';
   return String(s)
     .replace(/[\r\n]+/g, ' ')
-    .replace(/([\\`*_{}\[\]()#+\-.!|<>])/g, '\\$1')
+    .replace(/([\\`*_{}[\]()#+\-.!|<>])/g, '\\$1')
     .slice(0, 256);
 }
 

package/src/attest/index.js

@@ -65,7 +65,20 @@ function offsetSeconds(start, then) {
 function readPolicyRulesDigest(policyFile) {
   let text;
   try { text = fs.readFileSync(policyFile, 'utf8'); }
-  catch { return null; }
+  catch (e) {
+    // Loud-fail: a missing/unreadable policy file is operationally significant
+    // for an attestation (the rules_digest in the output will be defaults, not
+    // the file's real contents). Surface it on stderr; the caller still falls
+    // back to schema defaults so attestation generation does not abort.
+    // ENOENT is the common, expected case when no user policy exists; demote
+    // it to a single-line note. Anything else (EACCES, EIO, etc.) is louder.
+    if (e && e.code === 'ENOENT') {
+      process.stderr.write(`[Occasio] attest: no policy file at ${policyFile} — using schema defaults for rules_digest\n`);
+    } else {
+      process.stderr.write(`[Occasio] attest: cannot read policy ${policyFile}: ${e.message} — rules_digest will use schema defaults\n`);
+    }
+    return null;
+  }
 
   // Tiny line-level scan — full parsing is overkill for a digest. Counts only.
   let denyPaths = 0, denyPatterns = 0, blockSecrets = null;

package/src/audit/jsonl-auditor.js

@@ -37,19 +37,114 @@ function computeHash(rowWithoutHash) {
   return sha256hex(JSON.stringify(rowWithoutHash));
 }
 
-// Scan an existing file in reverse for the most recent hash value.
-// Returns GENESIS when the file is empty, missing, or contains only legacy rows.
-function loadPrevHash(filePath) {
-  let content;
-  try { content = fs.readFileSync(filePath, 'utf8'); } catch { return GENESIS; }
-  const lines = content.split('\n').filter(Boolean);
-  for (let i = lines.length - 1; i >= 0; i--) {
+// Default tail-read window size (bytes). Large enough to contain several full
+// audit rows on any plausible workload; small enough that bootstrap on a
+// 100k-event log stays sub-50ms.
+const TAIL_READ_BYTES = 64 * 1024;
+
+// Read the trailing window of a file. Returns the decoded string (utf8) along
+// with a flag indicating whether the read started mid-file (i.e. the first
+// line in the returned buffer may be truncated).
+function readTail(filePath, bytes = TAIL_READ_BYTES) {
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const { size } = fs.fstatSync(fd);
+    const start = Math.max(0, size - bytes);
+    const len   = size - start;
+    const buf   = Buffer.alloc(len);
+    if (len > 0) fs.readSync(fd, buf, 0, len, start);
+    return { content: buf.toString('utf8'), truncated: start > 0 };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Outcome codes for scanning the tail. A [code, value] tuple is used rather
+// than an object literal so that field-name tokens used by the audit row
+// schema (see test-interceptor.js §32) cannot appear earlier in this file
+// than the row builder in record() below.
+//   ['hash',    hexString]         found a valid hash-bearing row
+//   ['genesis']                    file empty / legacy-only / missing
+//   ['corrupt', detailString]      last line invalid JSON, no fallback row
+function scanTailForPrevHash(filePath, bytes = TAIL_READ_BYTES) {
+  let content, truncated;
+  try {
+    ({ content, truncated } = readTail(filePath, bytes));
+  } catch {
+    return ['genesis'];
+  }
+  if (!content) return ['genesis'];
+
+  // Split into raw lines (no filter) so we can detect a partial trailing line
+  // separately from intentionally-empty lines. A well-formed JSONL ends in
+  // '\n'; if the last element after split is non-empty, the file was cut
+  // mid-write.
+  const raw = content.split('\n');
+  const lastFragment = raw[raw.length - 1];
+  const lines = raw.filter(Boolean);
+  if (lines.length === 0) return ['genesis'];
+
+  // If we read from offset 0, the first line is authoritative. If we read
+  // from mid-file, the first line in the window may be a fragment of a row
+  // truncated by the window — drop it so we never treat a fragment as legacy.
+  const startIdx = truncated && raw[0] === lines[0] ? 1 : 0;
+  const lastNonEmptyIdx = lines.length - 1;
+
+  // Detect a partial trailing line: file does not end in '\n' AND the last
+  // line fails to JSON.parse. A complete row that *happens* to be the final
+  // entry is fine — its trailing newline guarantees lastFragment === ''.
+  const trailingPartial = lastFragment !== '' && (() => {
+    try { JSON.parse(lines[lastNonEmptyIdx]); return false; } catch { return true; }
+  })();
+
+  // Walk lines in reverse to find the most recent valid hash-bearing row.
+  // Skip the partial trailing line if present.
+  const scanFrom = trailingPartial ? lastNonEmptyIdx - 1 : lastNonEmptyIdx;
+  for (let i = scanFrom; i >= startIdx; i--) {
     try {
       const row = JSON.parse(lines[i]);
-      if (typeof row.hash === 'string' && row.hash.length === 64) return row.hash;
-    } catch {}
+      if (typeof row.hash === 'string' && row.hash.length === 64) {
+        return ['hash', row.hash];
+      }
+    } catch {
+      // Mid-window JSON.parse failure: a truly corrupt earlier row. We do not
+      // attempt to recover past it here — if no valid hash row exists in the
+      // remaining window, fall through to the corrupt/genesis decision below.
+    }
+  }
+
+  // No hash row found in the window. If we observed a partial trailing line
+  // AND the window contains no complete hash row, the chain is in an
+  // ambiguous state — caller must decide whether to fail hard or fall back
+  // to GENESIS (only safe if the file truly contains zero prior chain rows).
+  if (trailingPartial) {
+    return ['corrupt', 'partial trailing line, no recoverable prev_hash in tail window'];
+  }
+  return ['genesis'];
+}
+
+// Public: returns the most recent hash to chain from, or GENESIS.
+// Throws AuditCorruptError when the file's last line is JSON-broken and no
+// earlier hash-bearing row exists in the tail window — this prevents the
+// silent tamper gap where a partial write would otherwise restart the chain.
+function loadPrevHash(filePath, opts = {}) {
+  const { tailBytes = TAIL_READ_BYTES, failHard = true } = opts;
+  // Missing file → genesis (initial bootstrap).
+  if (!fs.existsSync(filePath)) return GENESIS;
+  const [code, detail] = scanTailForPrevHash(filePath, tailBytes);
+  if (code === 'hash')    return detail;
+  if (code === 'genesis') return GENESIS;
+  // code === 'corrupt'
+  if (!failHard) {
+    process.stderr.write(`[occasio audit] WARNING: ${filePath}: ${detail}\n`);
+    return GENESIS;
   }
-  return GENESIS;
+  const err = new Error(
+    `Audit log corrupt at ${filePath}: ${detail}. ` +
+    `Run \`occasio audit repair --file ${filePath}\` to truncate the partial trailing line.`
+  );
+  err.code = 'AUDIT_CORRUPT';
+  throw err;
 }
 
 /**
@@ -63,17 +158,75 @@ function loadPrevHash(filePath) {
  * call. prevHash is only advanced on a successful append, keeping the
  * in-memory chain consistent with what is on disk if the proxy is restarted.
  */
-function createAuditor(filePath = DEFAULT_LOG) {
-  try { fs.mkdirSync(path.dirname(filePath), { recursive: true }); } catch {}
+function createAuditor(filePath = DEFAULT_LOG, opts = {}) {
+  // lock=true wraps each append in a proper-lockfile lockSync/unlockSync pair
+  // and re-reads prev_hash from disk inside the lock. This is the only safe
+  // way to share an audit log between two concurrent writers (e.g. proxy +
+  // MCP server on the same machine). Default off because single-writer
+  // workloads do not pay the I/O cost.
+  const { lock = false } = opts;
+  let lockfile = null;
+  if (lock) {
+    // Lazy-require so a missing proper-lockfile install does not break
+    // single-writer setups that never opt in.
+    try { lockfile = require('proper-lockfile'); }
+    catch (e) {
+      throw new Error(`createAuditor({ lock: true }) requires proper-lockfile: ${e.message}`);
+    }
+    // The lockfile target must exist before lockSync can create its companion
+    // directory marker. Touch it.
+    if (!fs.existsSync(filePath)) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, '');
+    }
+  }
+
+  try { fs.mkdirSync(path.dirname(filePath), { recursive: true }); }
+  catch { /* directory already exists, or unwritable — surface on first append */ }
 
   let prevHash = loadPrevHash(filePath);
 
+  function withLock(fn) {
+    if (!lock) return fn();
+    // proper-lockfile uses mkdir(2) for atomicity; staleness keeps the lock
+    // self-healing across crashes. realpath:false avoids extra syscalls for
+    // a path we already control.
+    // proper-lockfile's sync API forbids `retries` — it must busy-loop on
+     // EEXIST itself. Keep stale-cleanup so a crashed writer cannot freeze
+     // siblings forever.
+    let release = null;
+    const start = Date.now();
+    while (release === null) {
+      try {
+        release = lockfile.lockSync(filePath, { stale: 10000, realpath: false });
+      } catch (e) {
+        if (e.code !== 'ELOCKED') throw e;
+        if (Date.now() - start > 10000) throw e;
+        // tight spin — node has no sleepSync; a microtask burst is fine for
+        // contention durations expected here (single-digit ms per writer)
+        const until = Date.now() + 2;
+        while (Date.now() < until) { /* spin */ }
+      }
+    }
+    // Inside the lock we MUST re-read prev_hash — another process may have
+    // appended since we last advanced it. Without this, two concurrent
+    // writers would produce two rows with the same prev_hash → chain break.
+    prevHash = loadPrevHash(filePath, { failHard: false });
+    try { return fn(); }
+    finally { try { release(); } catch { /* lock already released by stale-timeout reaper */ } }
+  }
+
   function record(event, decision, result) {
     if (!event || !decision) return { ok: true };
+    return withLock(() => recordInner(event, decision, result));
+  }
+
+  function recordInner(event, decision, result) {
     // Field order is explicit and must remain stable — computeHash depends on it.
     // The Python walker in docs/audit_walker.py mirrors this order; any change
     // here without updating that walker breaks independent verifiability.
     const row = {
+      audit_schema: 1,
       ts:            event.timestamp,
       event_id:      event.id,
       session_id:    event.sessionId,
@@ -131,8 +284,13 @@ function createAuditor(filePath = DEFAULT_LOG) {
    * append failure, mirroring record()'s contract so the caller can
    * propagate AuditWriteError uniformly.
    */
-  function recordPolicyLoaded({ hash, path: policyPath, version, source }) {
+  function recordPolicyLoaded(args) {
+    return withLock(() => recordPolicyLoadedInner(args));
+  }
+
+  function recordPolicyLoadedInner({ hash, path: policyPath, version, source }) {
     const row = {
+      audit_schema: 1,
       ts:            new Date().toISOString(),
       event_id:      crypto.randomUUID(),
       session_id:    undefined,
@@ -175,4 +333,12 @@ function createAuditor(filePath = DEFAULT_LOG) {
   return { record, recordPolicyLoaded, file: filePath };
 }
 
-module.exports = { createAuditor, DEFAULT_LOG, GENESIS, computeHash };
+module.exports = {
+  createAuditor,
+  DEFAULT_LOG,
+  GENESIS,
+  computeHash,
+  loadPrevHash,
+  scanTailForPrevHash,
+  TAIL_READ_BYTES,
+};

package/src/audit/repair.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * repair.js — `occasio audit repair`
+ *
+ * Truncates the trailing partial line of an audit log so a crash mid-append
+ * does not leave the file in a state where loadPrevHash() fails hard.
+ *
+ * Contract:
+ *   - Examines only the last line. Earlier corruption is out of scope and
+ *     should be investigated via `occasio audit verify`.
+ *   - "Partial" means: the file does not end in '\n' AND the last
+ *     non-empty line cannot be JSON.parsed. Any other shape is a no-op.
+ *   - Writes a .bak alongside the original before mutating, even on dry-run
+ *     the .bak is NOT created.
+ *   - Returns { truncated, wouldTruncate, backupPath, removedBytes, detail }.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+function inspect(filePath) {
+  const buf = fs.readFileSync(filePath);
+  if (buf.length === 0) return { partial: false, reason: 'empty file' };
+  const endsWithNewline = buf[buf.length - 1] === 0x0A;
+  const text = buf.toString('utf8');
+  const raw  = text.split('\n');
+  const lastFragment = raw[raw.length - 1];
+
+  if (endsWithNewline && lastFragment === '') {
+    return { partial: false, reason: 'file ends in newline; last line is complete' };
+  }
+
+  // Non-empty trailing fragment. Test whether it parses as JSON — a complete
+  // single-line record without a trailing newline is valid (rare but legal).
+  try {
+    JSON.parse(lastFragment);
+    return { partial: false, reason: 'trailing line parses as JSON; not partial' };
+  } catch {
+    // Truncate to the last preceding newline.
+    const lastNewline = buf.lastIndexOf(0x0A);
+    if (lastNewline === -1) {
+      // Entire file is a single partial line.
+      return { partial: true, truncateTo: 0, removedBytes: buf.length };
+    }
+    return {
+      partial: true,
+      truncateTo: lastNewline + 1,
+      removedBytes: buf.length - (lastNewline + 1),
+    };
+  }
+}
+
+function repairAuditFile(filePath, opts = {}) {
+  const { dryRun = false } = opts;
+  if (!fs.existsSync(filePath)) {
+    return { truncated: false, wouldTruncate: false, detail: `file not found: ${filePath}` };
+  }
+
+  const info = inspect(filePath);
+  if (!info.partial) {
+    return {
+      truncated: false, wouldTruncate: false,
+      detail: info.reason,
+      removedBytes: 0,
+    };
+  }
+
+  if (dryRun) {
+    return {
+      truncated: false, wouldTruncate: true,
+      removedBytes: info.removedBytes,
+      detail: `would truncate ${info.removedBytes} bytes from tail`,
+    };
+  }
+
+  const backupPath = `${filePath}.bak`;
+  fs.copyFileSync(filePath, backupPath);
+  // Truncate in place.
+  const fd = fs.openSync(filePath, 'r+');
+  try {
+    fs.ftruncateSync(fd, info.truncateTo);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return {
+    truncated: true,
+    wouldTruncate: true,
+    backupPath,
+    removedBytes: info.removedBytes,
+    detail: `truncated ${info.removedBytes} bytes from tail; backup at ${path.basename(backupPath)}`,
+  };
+}
+
+function runRepairCli(args) {
+  const fileIdx = args.indexOf('--file');
+  if (fileIdx === -1 || !args[fileIdx + 1]) {
+    console.error('Usage: occasio audit repair --file <path> [--dry-run]');
+    process.exit(2);
+  }
+  const filePath = args[fileIdx + 1];
+  const dryRun   = args.includes('--dry-run');
+
+  const r = repairAuditFile(filePath, { dryRun });
+  if (r.truncated) {
+    console.log(`occasio audit repair: ${r.detail}`);
+    return;
+  }
+  if (r.wouldTruncate) {
+    console.log(`occasio audit repair (dry-run): ${r.detail}`);
+    console.log('Re-run without --dry-run to apply.');
+    return;
+  }
+  console.log(`occasio audit repair: nothing to do — ${r.detail}`);
+}
+
+module.exports = { repairAuditFile, runRepairCli };

package/src/audit/verifier.js

@@ -55,6 +55,8 @@ function verifyFile(filePath = DEFAULT_LOG) {
   let legacy = 0, chained = 0;
   let expectedPrevHash = null;  // null = no chained row seen yet
   let firstHash = null, lastHash = null;
+  const seenSchemaVersions = new Set();
+  const SUPPORTED_SCHEMA_VERSIONS = new Set([1]);
 
   for (let i = 0; i < lines.length; i++) {
     let row;
@@ -72,6 +74,23 @@ function verifyFile(filePath = DEFAULT_LOG) {
 
     chained++;
 
+    // Schema-version policy:
+    //   - rows with audit_schema=undefined are legacy (pre-versioning) and
+    //     verify as before — they are valid.
+    //   - rows with audit_schema=1 verify normally.
+    //   - rows with audit_schema=N for unknown N record a non-fatal warning
+    //     in errors with a `warning: true` marker; ok-state is unaffected.
+    if (row.audit_schema !== undefined) {
+      seenSchemaVersions.add(row.audit_schema);
+      if (!SUPPORTED_SCHEMA_VERSIONS.has(row.audit_schema)) {
+        errors.push({
+          line: i + 1,
+          detail: `unknown audit_schema version ${row.audit_schema} (this build supports: ${[...SUPPORTED_SCHEMA_VERSIONS].join(',')})`,
+          warning: true,
+        });
+      }
+    }
+
     if (expectedPrevHash === null) {
       // First chained row: prev_hash must be GENESIS.
       firstHash = row.prev_hash;
@@ -99,15 +118,30 @@ function verifyFile(filePath = DEFAULT_LOG) {
     lastHash = storedHash;
   }
 
-  return { ok: errors.length === 0, total: lines.length, legacy, chained, errors, firstHash, lastHash };
+  // Warnings (unknown schema versions) do not flip ok=false — they are
+  // forward-compatibility hints, not chain breakage.
+  const fatal = errors.filter(e => !e.warning);
+  return {
+    ok: fatal.length === 0,
+    total: lines.length, legacy, chained,
+    errors,
+    firstHash, lastHash,
+    schemaVersions: [...seenSchemaVersions],
+  };
 }
 
 function runAuditCli(args) {
   const sub = args[0];
 
+  // Dispatch sub-commands. `repair` is forwarded to src/audit/repair.js.
+  if (sub === 'repair') {
+    const { runRepairCli } = require('./repair');
+    return runRepairCli(args.slice(1));
+  }
+
   // Accept: `occasio audit`, `occasio audit verify`, `occasio audit verify --file <path>`
   if (sub && sub !== 'verify' && !sub.startsWith('-')) {
-    console.error(`Unknown audit subcommand: ${sub}\nUsage: occasio audit [verify] [--file <path>]`);
+    console.error(`Unknown audit subcommand: ${sub}\nUsage: occasio audit [verify|repair] [--file <path>]`);
     process.exit(1);
   }