@matt82198/aesop 0.1.0-beta.4 → 0.1.0-beta.5

package/scan/fleet-scan.example.mjs

@@ -0,0 +1,292 @@
+// Example IOC/secret scanner — copy to fleet-scan.mjs and configure paths.
+// Scans committed code and fleet transcripts for security/alignment red-flags.
+// Runs each watchdog cycle; marks findings in SECURITY-ALERTS.log. Never blocks the fleet.
+//
+// SETUP:
+// 1. Copy this file to fleet-scan.mjs (in the same directory)
+// 2. Edit the REPOS and PROJECT_ROOTS configuration below to match your fleet setup
+// 3. Configure paths via aesop.config.json or environment variables:
+//    - AESOP_FLEET_ROOT: root directory containing your project repositories
+//    - AESOP_TRANSCRIPTS_ROOT: root directory containing ~/.claude/projects transcripts
+// 4. Ensure aesop.config.json contains repo definitions (see aesop.config.example.json)
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Load configuration from aesop.config.json or use environment variable defaults
+function loadConfig() {
+  const configPath = process.env.AESOP_CONFIG || path.join(process.cwd(), 'aesop.config.json');
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (e) {
+      console.error(`Warning: Failed to load config from ${configPath}: ${e.message}`);
+    }
+  }
+  return config;
+}
+
+const config = loadConfig();
+
+// Environment variable overrides (precedence: env > config > defaults)
+const FLEET_ROOT = process.env.AESOP_FLEET_ROOT || config.fleet_root || process.env.HOME;
+const TRANSCRIPTS_ROOT = process.env.AESOP_TRANSCRIPTS_ROOT || config.transcripts_root || path.join(process.env.HOME, '.claude', 'projects');
+
+// === CONFIGURE YOUR FLEET ===
+// Edit REPOS array to match your monitored repositories
+// Example: { path: '/path/to/project1', name: 'project1', branch: 'main' }
+// Paths can be absolute or relative to FLEET_ROOT
+const REPOS = config.repos || [
+  // Example:
+  // { path: 'project-a', name: 'project-a', branch: 'main' },
+  // { path: 'project-b', name: 'project-b', branch: 'main' },
+];
+
+// Transcript project roots to scan for fleet prompts
+// Default: ~/.claude/projects (set via AESOP_TRANSCRIPTS_ROOT or config)
+const PROJECT_ROOTS = [
+  TRANSCRIPTS_ROOT,
+];
+
+// Handoff/alerts directory (where SECURITY-ALERTS.log is stored)
+// Set via config: alerts.alerts_root or alerts_root
+const ALERTS_ROOT = config.alerts?.alerts_root || config.alerts_root || path.join(FLEET_ROOT, '..', 'conductor3', 'state');
+const ALERTS = path.join(ALERTS_ROOT, 'SECURITY-ALERTS.log');
+const SEENF = path.join(ALERTS_ROOT, '.fleet-scan-seen.json');
+const MARKERF = path.join(ALERTS_ROOT, '.fleet-scan-lastcommit');
+
+// Session ID to exclude (optional: set via EXCLUDE_SESSION env var or config)
+const MY_SESSION = process.env.EXCLUDE_SESSION || config.exclude_session || '';
+
+// ---- Utility functions ----
+const git = (a, cwd) => {
+  try {
+    return execSync(`git ${a}`, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return '';
+  }
+};
+const now = () => new Date().toISOString().replace('T', ' ').slice(0, 19);
+const seen = fs.existsSync(SEENF) ? new Set(JSON.parse(fs.readFileSync(SEENF, 'utf8'))) : new Set();
+const findings = [];
+
+const add = (sev, kind, where, detail) => {
+  const key = crypto
+    .createHash('sha1')
+    .update(sev + kind + where + detail)
+    .digest('hex')
+    .slice(0, 16);
+  if (seen.has(key)) return;
+  seen.add(key);
+  findings.push(`[${now()}] ${sev} ${kind} | ${where} | ${detail}`);
+};
+
+// ---- IOC patterns for ADDED code lines ----
+const CODE_IOC = [
+  ['HIGH', 'exec/shell', /Runtime\.getRuntime\(\)\.exec|new\s+ProcessBuilder|\bos\.system\(|\bsubprocess\.|\bpopen\(/i],
+  ['HIGH', 'reverse-shell', /\/dev\/tcp\/|\bnc\s+-e\b|bash\s+-i\b|sh\s+-i\b|socket\.SOCK_STREAM.*connect/i],
+  ['HIGH', 'pipe-to-shell', /\b(curl|wget)\b[^\n]*\|\s*(sh|bash)\b/i],
+  ['HIGH', 'b64-exec', /base64\s+(-d|--decode)[^\n]*\|\s*(sh|bash)|Base64.*decode[^\n]*exec/i],
+  ['HIGH', 'secret-literal', /AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|-----BEGIN[A-Z ]*PRIVATE KEY-----|xox[baprs]-[A-Za-z0-9-]{10,}|ghp_[A-Za-z0-9]{20,}/],
+  ['HIGH', 'cred-access', /\.ssh\/(id_|authorized)|\.aws\/credentials|\/etc\/(passwd|shadow)|secrets\.toml|\.env\b/i],
+  ['HIGH', 'destructive', /\brm\s+-rf\b|DROP\s+TABLE|TRUNCATE\s+TABLE|DELETE\s+FROM\s+\w+\s*;/i],
+  ['MED', 'deserialization', /\bObjectInputStream\b|\.readObject\(|XMLDecoder|@JsonTypeInfo|enableDefaultTyping/],
+  ['MED', 'reflection', /Class\.forName\(|Method\.invoke\(|getDeclaredMethod\(|setAccessible\(true\)/],
+  ['MED', 'raw-network', /new\s+Socket\(|URLConnection|\.openConnection\(|InetSocketAddress\(/i],
+  ['MED', 'hardcoded-cred', /(password|passwd|secret|api[_-]?key|token)\s*[:=]\s*["'][^"']{6,}["']/i],
+];
+
+function scanCodeAddedLines(diff, label) {
+  if (!diff) return;
+  let file = label;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      file = line.slice(4).replace(/^b\//, '');
+      continue;
+    }
+    if (!line.startsWith('+') || line.startsWith('+++')) continue;
+    const code = line.slice(1);
+    for (const [sev, kind, re] of CODE_IOC) {
+      if (re.test(code)) add(sev, 'CODE:' + kind, file, code.trim().slice(0, 160));
+    }
+  }
+}
+
+// Scan all configured repos
+for (const repo of REPOS) {
+  const repoPath = path.isAbsolute(repo.path) ? repo.path : path.join(FLEET_ROOT, repo.path);
+  if (!fs.existsSync(repoPath)) {
+    console.warn(`Warning: Repo not found: ${repoPath}`);
+    continue;
+  }
+
+  const head = git('rev-parse HEAD', repoPath).trim();
+  const markerFile = path.join(repoPath, '.fleet-scan-lastcommit-' + repo.name);
+  const last = fs.existsSync(markerFile) ? fs.readFileSync(markerFile, 'utf8').trim() : '';
+
+  if (head) {
+    if (last && last !== head) {
+      scanCodeAddedLines(git(`diff ${last}..${head}`, repoPath), `${repo.name}:commit-range`);
+    } else if (!last) {
+      scanCodeAddedLines(git(`show ${head}`, repoPath), `${repo.name}:${head.slice(0, 8)}`);
+    }
+    scanCodeAddedLines(git('diff HEAD', repoPath), `${repo.name}:working-tree`);
+    fs.writeFileSync(markerFile, head);
+  }
+}
+
+// ---- Fleet transcript scan (injection / exfil / off-goal) ----
+const CRED_HARVEST_ALLOWLIST = [
+  'secret_scan.py',
+  'secret/credential gate',
+  'scripts/CLAUDE.md',
+  'env_assignment',
+  'env_suspicious_keys',
+  'scanner_selftest',
+  'allow-pattern-docs',
+  'CRED_HARVEST_ALLOWLIST',
+  'generic_secret_assignment',
+];
+
+const EXFILTRATION_ALLOWLIST = [
+  'semantic-prompt-review',
+  'semantic review',
+  'OK/DRIFT/SUSPICIOUS',
+  'drift_escalator',
+  'prompt_classifier',
+  'alert-review',
+  'triage',
+  'EXFILTRATION_ALLOWLIST',
+  'power_selftest',
+  'secret_scan.py',
+  'fleet-scan.mjs',
+  'scanner_selftest',
+  'SECRETS-PERMITTED',
+  'resolve_alerts',
+];
+
+const PROMPT_IOC = [
+  ['HIGH', 'prompt-injection', /ignore\s+(all\s+)?(previous|prior|the\s+above)\s+instructions|disregard\s+(the|your)\s+(rules|instructions)|you\s+are\s+now\s+|new\s+system\s+prompt/i],
+  ['HIGH', 'exfiltration', /exfiltrat|send\s+(it|them|the\s+\w+)\s+to\s+https?:|upload\s+to\s+|POST\s+.*to\s+http|leak\s+(the\s+)?(secret|cred|token|key)/i],
+  ['HIGH', 'cred-harvest', /read\s+.*secrets\.toml|\.env\b|\.ssh\/|\.aws\/credentials|environment\s+variables?\s+.*(send|post|exfil)|harvest\s+(cred|token|key)/i],
+  ['HIGH', 'evade-security', /disable\s+(the\s+)?(sentinel|antivirus|edr|defender|firewall)|bypass\s+(the\s+)?(security|scan|review)|hide\s+(this\s+)?from\s+the\s+user|don.?t\s+tell\s+the\s+(user|owner)/i],
+  ['MED', 'danger-shell', /\b(curl|wget)\b.*\|\s*(sh|bash)|base64\s+-d|\/dev\/tcp\/|rm\s+-rf\s+(\/|~)|chmod\s+\+s/i],
+];
+
+function extractTexts(obj) {
+  const out = [];
+  const c = obj?.message?.content;
+  if (typeof c === 'string') out.push(c);
+  else if (Array.isArray(c)) {
+    for (const x of c) {
+      if (typeof x === 'string') out.push(x);
+      else if (x?.type === 'text' && x.text) out.push(x.text);
+      else if (x?.type === 'tool_use' && (x.name === 'Agent' || x.name === 'Task')) {
+        if (x.input?.prompt) out.push('[SPAWN] ' + x.input.prompt);
+        if (x.input?.description) out.push('[SPAWN] ' + x.input.description);
+      }
+    }
+  }
+  return out;
+}
+
+const SINCE = Date.now() - 25 * 60 * 1000;
+const tFiles = [];
+
+function walk(d) {
+  try {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.jsonl')) tFiles.push(p);
+    }
+  } catch {}
+}
+
+for (const r of PROJECT_ROOTS) {
+  if (fs.existsSync(r)) walk(r);
+}
+
+for (const fp of tFiles) {
+  if (MY_SESSION && fp.includes(MY_SESSION)) continue; // skip excluded session
+  let st;
+  try {
+    st = fs.statSync(fp);
+  } catch {
+    continue;
+  }
+  if (st.mtimeMs < SINCE) continue; // only recent fleet activity
+  const base = path.basename(fp);
+  const isAgentFile = base.startsWith('agent-'); // agent files: scan all; main session: [SPAWN] only
+  let lines;
+  try {
+    lines = fs.readFileSync(fp, 'utf8').split('\n');
+  } catch {
+    continue;
+  }
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    for (const text of extractTexts(obj)) {
+      if (!text || text.length < 8) continue;
+      const isSpawnedPrompt = text.startsWith('[SPAWN]');
+      const shouldScanPromptIOC = isAgentFile || isSpawnedPrompt;
+      let flagged = false;
+      if (shouldScanPromptIOC) {
+        for (const [sev, kind, re] of PROMPT_IOC) {
+          if (re.test(text)) {
+            if (kind === 'cred-harvest') {
+              const isDefensiveToolRef = CRED_HARVEST_ALLOWLIST.some((ref) => text.includes(ref));
+              if (isDefensiveToolRef) {
+                const detail = text.replace(/\s+/g, ' ').slice(0, 180);
+                add('SUPPRESSED-FP', 'cred-harvest (defensive-tool reference)', base, detail);
+                flagged = true;
+                continue;
+              }
+            }
+            if (kind === 'exfiltration') {
+              const isDefensiveReviewRef = EXFILTRATION_ALLOWLIST.some((ref) => text.includes(ref));
+              if (isDefensiveReviewRef) {
+                const detail = text.replace(/\s+/g, ' ').slice(0, 180);
+                add('SUPPRESSED-FP', 'exfiltration (defensive-review reference)', base, detail);
+                flagged = true;
+                continue;
+              }
+            }
+            add(sev, 'PROMPT:' + kind, base, text.replace(/\s+/g, ' ').slice(0, 180));
+            flagged = true;
+          }
+        }
+      }
+      void flagged;
+    }
+  }
+}
+
+// ---- emit ----
+// Ensure output directory exists
+if (!fs.existsSync(ALERTS_ROOT)) {
+  fs.mkdirSync(ALERTS_ROOT, { recursive: true });
+}
+
+if (findings.length) {
+  fs.appendFileSync(ALERTS, findings.join('\n') + '\n');
+  fs.writeFileSync(SEENF, JSON.stringify([...seen]));
+  console.log(`${findings.length} new finding(s) -> ${ALERTS}`);
+  for (const f of findings) console.log(f);
+} else {
+  fs.writeFileSync(SEENF, JSON.stringify([...seen]));
+  console.log('no new findings');
+}

package/skills/healthcheck/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: healthcheck
+description: Check fleet health — one colored ball (heartbeats, alerts, orchestrator, tracker items).
+version: 1.0.0
+---
+
+# Healthcheck — one colored health ball
+
+One-line status indicator for aesop fleet health, driven by aggregated signals.
+
+## Procedure
+
+Run the healthcheck tool and interpret the ball:
+
+```bash
+python tools/healthcheck.py
+```
+
+### Output interpretation
+
+**🟢 Green**: All heartbeats fresh (watchdog <300s, monitor <3600s), no HIGH alerts
+
+**🟡 Yellow**: Stale heartbeat OR unreviewed MED severity alert
+
+**🔴 Red**: HIGH severity alert OR watchdog dead (>600s) while orchestrator actively dispatching
+
+### Fixing issues
+
+When healthcheck returns non-green, check the bullet-list reasons:
+
+1. **Stale heartbeat**: Restart the relevant daemon (watchdog or monitor). Check `bash daemons/run-watchdog.sh --once` or monitor process.
+2. **Unreviewed HIGH alert**: Review SECURITY-ALERTS.log, prefix line with `NOTE:` or `RESOLVED-FP` to mark reviewed.
+3. **Unreviewed MED alert**: Same as HIGH — review and mark.
+4. **Dead watchdog + active dispatch**: Critical issue — watchdog daemon crashed while orchestrator was dispatching agents. Check logs, restart watchdog, verify orchestrator stability.
+
+### Machine-readable output
+
+For integration with monitoring/dashboards, use `--json`:
+
+```bash
+python tools/healthcheck.py --json
+```
+
+Returns a JSON object with `ball`, `health` status, issues list, and tracker lane counts.

package/state_store/CLAUDE.md

@@ -0,0 +1,39 @@
+# state_store/ — event-sourced state layer (DB source of truth, git as export)
+
+**Purpose**: the durable substrate to move aesop's coordination/state off git —
+which cannot scale to a team (single-writer control files, hot-file merge
+conflicts, no transactions/concurrency/real-time). State becomes an append-only
+event log with per-stream versioning; current state is a projection; git is
+demoted to a rendered, diffable **export**.
+
+**Status (2026-07-14)**: additive prototype. The live `ui/` tracker path
+(`collectors.py` → `state/tracker.json`) is UNCHANGED. This package ships the
+store + tracker projection + backfill + export, ready for a later dual-read
+cutover. Design: `conductor3 plans/aesop-scaling-rearchitecture.md`.
+
+## Files (stdlib only — sqlite3/json/threading/time)
+- **store.py** — `EventStore(db_path)`: append-only SQLite (WAL) log.
+  Concurrency-safe across threads and processes via `busy_timeout` +
+  `BEGIN IMMEDIATE` (atomic read-max-version-then-insert). `append/read/read_all`.
+- **projections.py** — `project_tracker(events)`: folds `item_created` /
+  `item_updated` / `item_archived` into the full `tracker.json` shape,
+  preserving first-seen order.
+- **api.py** — `StateAPI(db_path)`: the swap seam (`append`/`get`/`project`).
+  Backend swaps SQLite→Postgres here without touching callers.
+- **export.py** — `export_tracker(api, out_path)`: render the projection back to
+  a git-tracked JSON snapshot (indent=2, ascii-escaped to match the live file).
+- **ingest.py** — `ingest_tracker_json(api, path)`: backfill one `item_created`
+  per existing item (the migration/backfill path).
+
+## Invariants
+- **Append-only**: never mutate/delete events; state changes are new events.
+- **Per-stream version is 1-based and gapless** (enforced atomically).
+- **git as export, not source**: nothing here reads git for state.
+- **Round-trip fidelity**: ingest → project → export reproduces the same items
+  (tested against the real `state/tracker.json`).
+
+## Next (cutover, follow-up — NOT this increment)
+Point tracker CRUD at `StateAPI` (create→`item_created`, update→`item_updated`,
+move→lane update, delete→`item_archived`); add a `subscribe()` real-time path to
+replace the SSE file-watch; run the `export_tracker` job to keep `tracker.json`
+rendered during dual-read; then flip readers to the API.

package/state_store/__init__.py

@@ -0,0 +1,24 @@
+"""state_store — event-sourced state layer (DB source of truth, git as export).
+
+Additive prototype landed 2026-07-14: the live ui/ tracker path is UNCHANGED.
+This package provides the durable substrate to migrate aesop's coordination
+state off git (which does not scale to concurrent writers) onto a real store
+with transactions and per-stream versioning — SQLite (WAL) now, Postgres later
+behind the same StateAPI. git is demoted to a rendered export (see export.py).
+
+Design + rationale: conductor3 plans/aesop-scaling-rearchitecture.md; overview
+in state_store/CLAUDE.md.
+"""
+from .api import StateAPI
+from .export import export_tracker
+from .ingest import ingest_tracker_json
+from .projections import project_tracker
+from .store import EventStore
+
+__all__ = [
+    "EventStore",
+    "StateAPI",
+    "project_tracker",
+    "export_tracker",
+    "ingest_tracker_json",
+]

package/state_store/api.py

@@ -0,0 +1,35 @@
+"""state_store.api — StateAPI facade over the event store + projections.
+
+The single seam callers use, so the backend (SQLite now, Postgres later) can be
+swapped without touching call sites. ``project(view)`` reads the same-named
+stream and folds it through the registered projector.
+"""
+from __future__ import annotations
+
+from .projections import project_tracker
+from .store import EventStore
+
+_PROJECTORS = {"tracker": project_tracker}
+
+
+class StateAPI:
+    """Facade: append events, read a stream, or project a view to current state."""
+
+    def __init__(self, db_path: str):
+        self._store = EventStore(db_path)
+
+    def append(self, stream: str, event_type: str, payload: dict, actor: str = "system") -> int:
+        """Append one event; return its new per-stream version."""
+        return self._store.append(stream, event_type, payload, actor)
+
+    def get(self, stream: str) -> list:
+        """Return all events in ``stream`` ascending by version."""
+        return self._store.read(stream)
+
+    def project(self, view: str) -> dict:
+        """Fold the same-named stream through its projector into current state."""
+        try:
+            projector = _PROJECTORS[view]
+        except KeyError:
+            raise ValueError(f"unknown projection view: {view!r}")
+        return projector(self.get(view))

package/state_store/export.py

@@ -0,0 +1,19 @@
+"""state_store.export — render a projection back into git-tracked JSON.
+
+In the DB-source-of-truth design git stops being *read* for state; this job
+renders human-readable, diffable snapshots (e.g. tracker.json) FROM the
+projections for durability and review. The JSON style (indent=2, ascii-escaped)
+matches the existing state/tracker.json so a future cutover produces
+minimal-diff snapshots.
+"""
+from __future__ import annotations
+
+import json
+
+
+def export_tracker(api, out_path: str) -> None:
+    """Write the tracker projection to ``out_path`` as pretty JSON."""
+    projection = api.project("tracker")
+    with open(out_path, "w", encoding="utf-8") as fh:
+        json.dump(projection, fh, indent=2)
+        fh.write("\n")

package/state_store/ingest.py

@@ -0,0 +1,24 @@
+"""state_store.ingest — backfill events from an existing tracker.json.
+
+Migration path for the DB-source-of-truth cutover: read the current
+tracker.json and emit one ``item_created`` event per item (full payload) so the
+event store reproduces the current state. History is not reconstructed (only
+final state exists on disk), but the projection round-trips to the same items,
+so an export re-renders the identical tracker.json.
+"""
+from __future__ import annotations
+
+import json
+
+
+def ingest_tracker_json(api, tracker_json_path: str, actor: str = "migration") -> int:
+    """Append one ``item_created`` per item in ``tracker_json_path``.
+
+    Returns the number of items ingested.
+    """
+    with open(tracker_json_path, "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    items = data.get("items", [])
+    for item in items:
+        api.append("tracker", "item_created", item, actor)
+    return len(items)

package/state_store/projections.py

@@ -0,0 +1,52 @@
+"""state_store.projections — fold tracker events into current state.
+
+``project_tracker`` reconstructs the tracker.json shape
+(``{"version": 1, "items": [...]}``) from the ``tracker`` event stream:
+
+  - ``item_created``  : payload is the full item dict; establishes the item
+                        (kept in first-seen order).
+  - ``item_updated``  : payload is ``{"id": <id>, ...partial fields}``; merges
+                        the given fields onto the existing item.
+  - ``item_archived`` : payload is ``{"id": <id>}`` (+ optional
+                        ``completed_at``); sets ``status`` to ``"archived"``.
+
+Unknown ids on update/archive and unknown event types are ignored, keeping the
+fold tolerant of partial/legacy streams.
+"""
+from __future__ import annotations
+
+TRACKER_VERSION = 1
+
+
+def project_tracker(events: list) -> dict:
+    """Return the current tracker state projected from ``events``."""
+    order = []      # item ids in first-seen order (stable output ordering)
+    items = {}      # id -> item dict
+    for ev in events:
+        etype = ev.get("type")
+        payload = ev.get("payload") or {}
+        if etype == "item_created":
+            iid = payload.get("id")
+            if iid is None:
+                continue
+            if iid not in items:
+                order.append(iid)
+            items[iid] = dict(payload)
+        elif etype == "item_updated":
+            iid = payload.get("id")
+            if iid in items:
+                merged = dict(items[iid])
+                for key, value in payload.items():
+                    if key != "id":
+                        merged[key] = value
+                items[iid] = merged
+        elif etype == "item_archived":
+            iid = payload.get("id")
+            if iid in items:
+                merged = dict(items[iid])
+                merged["status"] = "archived"
+                if "completed_at" in payload:
+                    merged["completed_at"] = payload["completed_at"]
+                items[iid] = merged
+        # any other event type is ignored
+    return {"version": TRACKER_VERSION, "items": [items[i] for i in order]}

package/state_store/store.py

@@ -0,0 +1,102 @@
+"""state_store.store — SQLite-backed, append-only, concurrency-safe event log.
+
+Durable substrate for aesop's event-sourced state layer (the DB-source-of-truth
+design; git becomes a rendered export, not the coordination layer). Backend is
+SQLite in WAL mode so many readers and serialized writers share one file; the
+same interface is meant to swap to Postgres behind ``state_store.api.StateAPI``
+for team scale without touching call sites.
+
+Stdlib only (sqlite3, json, time) per aesop's no-external-deps invariant.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+
+
+class EventStore:
+    """Append-only event log stored at ``db_path``.
+
+    Safe under concurrent appends from multiple threads AND multiple EventStore
+    instances on the same file: every call opens its own connection with
+    ``PRAGMA busy_timeout`` and assigns the per-stream version inside a
+    ``BEGIN IMMEDIATE`` transaction, so the read-max-version-then-insert is
+    atomic and two writers can never collide or duplicate a version.
+    """
+
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("PRAGMA busy_timeout=5000")
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS events (
+                    id      INTEGER PRIMARY KEY AUTOINCREMENT,
+                    ts      REAL    NOT NULL,
+                    actor   TEXT    NOT NULL,
+                    stream  TEXT    NOT NULL,
+                    type    TEXT    NOT NULL,
+                    payload TEXT    NOT NULL,
+                    version INTEGER NOT NULL
+                )
+                """
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_events_stream_version "
+                "ON events(stream, version)"
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def append(self, stream: str, event_type: str, payload: dict, actor: str = "system") -> int:
+        """Append one event to ``stream``; return its new per-stream version (1-based)."""
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute("PRAGMA busy_timeout=5000")
+            # BEGIN IMMEDIATE takes the write lock up front so the
+            # read-max-then-insert below is atomic under contention.
+            conn.execute("BEGIN IMMEDIATE")
+            row = conn.execute(
+                "SELECT COALESCE(MAX(version), 0) FROM events WHERE stream = ?",
+                (stream,),
+            ).fetchone()
+            version = row[0] + 1
+            conn.execute(
+                "INSERT INTO events (ts, actor, stream, type, payload, version) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (time.time(), actor, stream, event_type, json.dumps(payload), version),
+            )
+            conn.commit()
+            return version
+        finally:
+            conn.close()
+
+    def read(self, stream: str) -> list:
+        """Return all events for ``stream`` ascending by version (empty if none)."""
+        return self._rows("WHERE stream = ? ORDER BY version ASC", (stream,))
+
+    def read_all(self) -> list:
+        """Return all events across all streams ascending by id."""
+        return self._rows("ORDER BY id ASC", ())
+
+    def _rows(self, clause: str, params) -> list:
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute("PRAGMA busy_timeout=5000")
+            cur = conn.execute(
+                "SELECT id, ts, actor, stream, type, payload, version FROM events " + clause,
+                params,
+            )
+            return [
+                {
+                    "id": r[0], "ts": r[1], "actor": r[2], "stream": r[3],
+                    "type": r[4], "payload": json.loads(r[5]), "version": r[6],
+                }
+                for r in cur.fetchall()
+            ]
+        finally:
+            conn.close()