@matt82198/aesop 0.1.0-rc.1 → 0.2.0

package/mcp/CLAUDE.md

@@ -1,213 +0,0 @@
-# mcp/ — Read-Only Fleet State MCP Server
-
-**Purpose**: Expose Aesop fleet operational status as a Model Context Protocol (MCP) server for Claude Code and other MCP clients.
-
-## Server
-
-**File**: `server.mjs` — Stdio-transport MCP server implementing the JSON-RPC 2.0 protocol.
-
-**Configuration**:
-- `AESOP_ROOT` environment variable or `--root <path>` command-line flag (no hardcoded paths)
-- `AESOP_STATE_ROOT` environment variable for state directory override (default: `AESOP_ROOT/state`)
-- `AESOP_TRANSCRIPTS_ROOT` environment variable for transcript directory override (default: `~/.claude/projects`)
-- Reads `aesop.config.json` from AESOP_ROOT for optional config file overrides
-
-**Launch**:
-```bash
-node mcp/server.mjs [--root /path/to/aesop]
-```
-
-The server reads from stdin, writes JSON-RPC responses to stdout. Suitable for direct MCP integration or debugging via manual JSON-RPC frames.
-
-## Tools
-
-All tools are **strictly read-only**: no state mutations, no file writes, no shell-outs except the minimal dash-extra.mjs passthrough for fleet_agents.
-
-### fleet_status
-
-**Description**: Get fleet operational status — daemon heartbeats, monitor heartbeat, orchestrator activity, alert count.
-
-**Input**: No arguments.
-
-**Output** (JSON):
-```json
-{
-  "watchdog": {
-    "alive": "ALIVE" | "STALE",
-    "age_seconds": <bucketed>,
-    "threshold_seconds": 300
-  },
-  "monitor": {
-    "alive": "ALIVE" | "STALE",
-    "age_seconds": <bucketed>,
-    "threshold_seconds": 3600
-  },
-  "orchestrator": <parsed orchestrator-status.json> or null,
-  "alerts": {
-    "count": <int>,
-    "sample_lines": [<last 3 unreviewed lines>]
-  }
-}
-```
-
-**Missing files**: If a file doesn't exist, the corresponding field is `null`. The response never crashes; missing state files are reported gracefully with `absent` markers where applicable.
-
-### fleet_agents
-
-**Description**: List active Claude agents from transcript directory. Invokes `dash-extra.mjs --json` with environment variables for path portability.
-
-**Input**: No arguments.
-
-**Output** (JSON):
-```json
-{
-  "absent": <bool>,
-  "agents": [
-    {
-      "project": <string>,
-      "taskLabel": <string>,
-      "promptFull": <string>,
-      "runtimeSeconds": <int>,
-      "tokensUsed": <int>,
-      "startedAt": <ISO string>,
-      "lastActivity": <ISO string>
-    },
-    ...
-  ]
-}
-```
-
-**Design notes**:
-- Passes through `dash-extra.mjs --json` output (no reimplementation).
-- Timeout: 5 seconds. On timeout or error, returns empty agents list.
-- Environment variables (`AESOP_ROOT`, `AESOP_STATE_ROOT`, `AESOP_TRANSCRIPTS_ROOT`) are set before invoking dash-extra to ensure portable transcript discovery.
-
-### fleet_tracker
-
-**Description**: Get fleet work items from `tracker.json`, grouped by lane.
-
-**Input**: No arguments.
-
-**Output** (JSON):
-```json
-{
-  "absent": <bool>,
-  "by_lane": {
-    "ranked": [
-      {
-        "id": <string>,
-        "title": <string>,
-        "priority": "P0" | "P1" | "P2",
-        "status": "todo" | "in-progress" | "done",
-        "tags": [<string>, ...]
-      },
-      ...
-    ],
-    "in-progress": [ ... ],
-    "done": [ ... ],
-    ...
-  }
-}
-```
-
-**Lanes**: Each lane is optional and present only if items exist in it. Common lanes: `ranked`, `proposed`, `in-progress`, `done`.
-
-### fleet_cost
-
-**Description**: Get per-model token usage totals from the fleet outcomes ledger (`state/ledger/OUTCOMES-LEDGER.md`).
-
-**Input**: No arguments.
-
-**Output** (JSON):
-```json
-{
-  "absent": <bool>,
-  "by_model": {
-    "claude-haiku-4": {
-      "tokens_in": <int>,
-      "tokens_out": <int>,
-      "total_tokens": <int>,
-      "count": <int>
-    },
-    "claude-opus": { ... },
-    ...
-  },
-  "total_tokens_in": <int>,
-  "total_tokens_out": <int>
-}
-```
-
-**Design notes**:
-- Parses markdown table rows from the ledger file.
-- Reports **token counts only** — no invented dollar figures.
-- Gracefully handles missing or malformed lines (skips with no error).
-
-## MCP Integration
-
-### Claude Code (claude.json)
-
-To register the server in Claude Code:
-
-```json
-{
-  "mcp": {
-    "aesop-fleet": {
-      "command": "node",
-      "args": [
-        "/path/to/aesop/mcp/server.mjs",
-        "--root",
-        "/path/to/aesop"
-      ],
-      "env": {
-        "AESOP_ROOT": "/path/to/aesop"
-      }
-    }
-  }
-}
-```
-
-### Portable Setup
-
-For portable configuration (no hardcoded user paths), use environment variables:
-
-```bash
-export AESOP_ROOT=/path/to/aesop
-export AESOP_STATE_ROOT=/path/to/state  # optional override
-export AESOP_TRANSCRIPTS_ROOT=/path/to/transcripts  # optional override
-node /path/to/aesop/mcp/server.mjs
-```
-
-Or use the `--root` flag:
-
-```bash
-node /path/to/aesop/mcp/server.mjs --root /path/to/aesop
-```
-
-## Invariants & Guarantees
-
-1. **Strictly read-only**: All tools are read-only. Zero state mutations, zero file writes.
-2. **No shell execution** (except dash-extra.mjs invocation with timeout): Minimizes surface area for injection or performance issues.
-3. **Graceful degradation**: Missing state files → empty results with `absent: true` markers, never a crash.
-4. **No external dependencies**: Plain Node.js (no npm packages). Server.mjs uses only stdlib modules: `fs`, `path`, `os`, `child_process`, `readline`.
-5. **JSON-RPC 2.0 compliant**: Standard request/response format with proper error codes.
-6. **Portable paths**: All paths resolved from AESOP_ROOT, AESOP_STATE_ROOT, AESOP_TRANSCRIPTS_ROOT env vars or config file. No hardcoded paths like `/home/user/aesop`.
-
-## Testing
-
-See `tests/mcp-fleet.test.mjs` for end-to-end tests:
-- Spawn server over stdio
-- Drive JSON-RPC initialize + tools/list + tools/call round-trips
-- Validate read-only behavior (no state mutations after calls)
-- Verify fixture isolation (temp state root)
-
-Run:
-```bash
-npm test  # or
-node tests/mcp-fleet.test.mjs
-```
-
-## Files
-
-- **server.mjs** — Main MCP server implementation (stdio, JSON-RPC 2.0)
-- **package.json** — Minimal metadata; no external dependencies
-- **CLAUDE.md** — This file

package/monitor/CLAUDE.md

@@ -1,40 +0,0 @@
-# monitor/ — Orchestration monitor
-
-**Purpose**: Continuous background signal collector and refinement proposer — watches fleet machinery health deterministically (Node.js, no LLM), emits cycle snapshots, and proposes rule changes via append-only PROPOSALS.md; GOAL IS FIXED (improve machinery, never mission).
-
-## Files
-
-- **CHARTER.md** — Governance document; defines 11 signal checks (4 of them extended/opt-in), action tiers (AUTO/PROPOSE), outputs, single-instance guard, single-writer discipline. Read-only; behavior changes only via PROPOSALS/behavioral-PR flow.
-- **collect-signals.mjs** — Deterministic signal collector (Node.js built-ins only); emits BRIEF.md + SIGNALS.json each cycle; reads config from env or aesop.config.json.
-- **BRIEF.md** — Human-readable cycle snapshot (heartbeats, git state, memory freshness, log rotation, junk sprawl, stray scripts, security alerts, respawn watch, cost cadence, unreviewed prompts); overwritten each cycle; runtime.
-- **SIGNALS.json** — Machine-readable metrics (same signal keys as BRIEF); JSON; overwritten each cycle; runtime.
-- **PROPOSALS.md** — Structured inbox for user approval (idempotent per signal key, append-only); never edited by monitor after emission; tracks isolation-violation-detected, respawn-watch-breach, stray-repo-scripts, security-alerts-high-med, stale-memory-files; gitignored.
-- **ACTIONS.log** — Append-only log of AUTO tier actions taken (heartbeat updates, log rotation invokes, junk quarantine); runtime; gitignored.
-- **.monitor-heartbeat** — Epoch timestamp (line 1) for single-instance liveness check (<300s = skip cycle); runtime; gitignored.
-- **.signal-state.json** — Sidecar state (cycleCount, etc.); runtime; gitignored.
-
-## Contracts
-
-**Signal keys collected**: heartbeats, git, memory, logs, junk, strayRepo, alerts, respawnWatch, costTick, unreviewedPrompts, isolationViolations. Outputs: BRIEF.md (human), SIGNALS.json (machine); both runtime/gitignored. PROPOSALS.md (tracked, append-only); ACTIONS.log (runtime/gitignored).
-
-**Extended signals (opt-in, default OFF)**: checks 5 (junk), 6 (strayRepo), 8 (respawnWatch), and 10 (unreviewedPrompts) are extended — disabled by default.
-- Config key: `monitor.extended_signals` (boolean, default `false`) in aesop.config.json.
-- Env override: `AESOP_EXTENDED_SIGNALS` (`'true'` or `'1'` to enable).
-- Precedence: env var > config file > default (false).
-- When disabled, extended checks emit `{"skipped": true}` in SIGNALS.json and BRIEF.md notes them as "extended (off)"; their dirs are not walked. PROPOSE-tier signals for extended checks (respawn-watch-breach, stray-repo-scripts) are only emitted when extended_signals is ON.
-
-**AUTO tier actions** (apply immediately, log to ACTIONS.log): heartbeat checks (read-only); log rotation (invoke rotate_logs.py if available, fail-open); heartbeat write (.monitor-heartbeat update); junk script quarantine (move old temp .py/.mjs to monitor/quarantine/ + manifest — only when extended_signals is ON).
-
-**PROPOSE tier actions** (write to PROPOSALS.md, await user approval): rule changes, agent config changes, deletions outside monitor/quarantine/, orchestration policy changes.
-
-**Idempotency rule**: Proposal emission keyed on signal key (e.g., 'respawn-watch-breach'); only emitted if not already present in PROPOSALS.md (check: `**Signal:** <key>` exists). Idempotent + append-only; safe to run repeatedly.
-
-## Invariants & Gotchas
-
-- CHARTER.md is authority; monitor logic is faithful to it; never edit CHARTER.md or collect-signals.mjs directly — propose via PROPOSALS.md.
-- Goal is FIXED (improve machinery, never mission); if monitor thinks goal should change, it writes note to PROPOSALS.md and stops.
-- Single-instance guard via .monitor-heartbeat; if <300s old, skip cycle.
-- Single-writer discipline: only monitor writes BRIEF.md, SIGNALS.json, ACTIONS.log, .monitor-heartbeat, .signal-state.json.
-- Config from env (AESOP_ROOT, BRAIN_ROOT, SCRIPTS_ROOT, TEMP_ROOT, AESOP_EXTENDED_SIGNALS) or aesop.config.json; falls back to safe defaults.
-- Robust to missing files; treats missing dirs/logs as empty, never crashes.
-- Node.js only (no Python, no LLM, no cloud); deterministic + cheap.

package/scan/CLAUDE.md

@@ -1,30 +0,0 @@
-# scan/ — Example IOC/secret scanner template
-
-The `fleet-scan.example.mjs` is a config-driven template for scanning committed code and fleet transcripts for security and alignment red-flags during each watchdog cycle.
-
-## Setup
-
-1. Copy `fleet-scan.example.mjs` → `fleet-scan.mjs` (in the same directory)
-2. Edit the configuration section to match your fleet setup (REPOS array, PROJECT_ROOTS paths)
-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`)
-
-## How it works
-
-When enabled (by copying to `fleet-scan.mjs`), the scanner:
-- Runs every watchdog cycle (default: every 150s)
-- Scans git repositories and transcript directories for patterns matching your configured IOC/secret rules
-- Logs findings to `SECURITY-ALERTS.log` with severity (HIGH/MED/LOW)
-- Never blocks the fleet (non-fatal, append-only)
-- Marks reviewed findings with `NOTE:` or `RESOLVED-FP` prefix to skip future alerts
-
-## Customization
-
-Edit the `fleet-scan.mjs` rules section to add domain-specific checks:
-- Pattern-based secret/credential detection
-- Alignment violations (e.g., non-approved libraries, unclosed TODO markers)
-- Transcript red-flags (e.g., cost anomalies, stalled agents)
-
-Output findings via the `add(severity, kind, where, detail)` function; the scanner handles deduplication and logging.

package/state_store/CLAUDE.md

@@ -1,39 +0,0 @@
-# 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/tools/CLAUDE.md

@@ -1,79 +0,0 @@
-# tools/ — Build utilities
-
-Local-only Python (stdlib only, no external deps), bash (POSIX, CRLF-safe). Never print secrets — report by pattern name/location only.
-
-## FILES
-
-- `alert_bridge.py` — Slack/Discord webhook bridge for SECURITY-ALERTS
-- `bench_runner.py` — Held-out benchmark runner + scorer with accuracy + cost axis (offline mock runner; pluggable Haiku/Sonnet/Opus runners return text or (text, usage))
-- `buildlog.py` — Uniform BUILDLOG.md appender
-- `ci_merge_wait.py` — CI-gated merge helper (polls gh pr view until SUCCESS)
-- `common.py` — Shared utilities (state directory resolution, heartbeat staleness checks)
-- `cost_ceiling.py` — Cost-ceiling checker: trips the HALT kill-switch when configured token limits are exceeded
-- `ensure_state.py` — Scaffold STATE.md and BUILDLOG.md templates
-- `eod_sweep.py` — End-of-day safety check (dirty trees, unpushed commits)
-- `fleet_ledger.py` — Append-only cost ledger with harvest/rotate
-- `fleet_prompt_extractor.py` — Extract and deduplicate Agent/Task spawn prompts
-- `halt.py` — Kill-switch: writes/reads/clears the `.HALT` sentinel that daemons/dispatch check to stop the fleet
-- `healthcheck.py` — Fleet health aggregator (heartbeat/alert/orchestrator status)
-- `heartbeat.py` — Single-instance loop liveness registry
-- `inbox_drain.py` — Drain UI inbox submissions
-- `launch_tui.py` — Spawn bash TUI script in detached terminal
-- `lock.mjs` — Fail-closed atomic lock acquisition (exponential backoff + stale-lock detection)
-- `metrics_gate.py` — PR gate for hard numeric claims in markdown
-- `orchestrator_status.py` — Atomic orchestrator status updates
-- `power_selftest.py` — Health check harness for /power bootstrap
-- `prepublish_scan.py` — Pre-publish full history + staged-changes scan gate
-- `proposals.mjs` — Proposal lifecycle manager (list/accept/reject)
-- `reconcile.py` — Detect/resolve drift between git STATE.md (phase) and the state_store projection (git-authoritative; --resolve appends to SQLite only)
-- `reconstitute.sh` — Clone/fetch repos from config with security validation
-- `rotate_logs.py` — Log rotation utility with size/line thresholds
-- `scanner_selftest.py` — Regression harness for secret_scan.py
-- `secret_scan.py` — Pre-push secret/credential detection gate
-- `self_stats.py` — Git-derived metrics counter + README block generator
-- `session_usage_summary.py` — Aggregate token usage across session transcripts
-- `stall_check.py` — Automated agent transcript stall detector
-- `svg_to_png.mjs` — Rasterize SVG to PNG via @resvg/resvg-js (with lazy import error handling)
-- `transcript_replay.py` — Replay post-commit edits from transcripts to recover work
-- `transcript_timeline.py` — Extract Write/Edit/Read timeline from transcripts
-- `verify_dash.py` — Browser proof for realtime SSE dashboard
-- `verify_submit_encoding.py` — Browser proof for /submit UTF-8 inbox bootstrap
-- `verify_prboard.py` — Browser proof for the Wave PR Board (/api/wave/prs), gh stubbed via AESOP_GH_BIN
-- `verify_agent_inspector.py` — Browser proof for the Agent Inspector drawer (/api/agent?id=), agents + transcript stubbed via a temp AESOP_ROOT
-- `agent-forensics.sh` — Incident forensics / behavior reconstruction
-
-## secret_scan.py — Pre-push secret/credential detection gate
-
-Scans staged/history/paths for secrets by regex pattern and credential filenames; blocks pushes on findings.
-
-- `secret_scan.py --staged [--repo PATH]` — scan git staged files
-- `secret_scan.py --history [--repo PATH]` — scan all git history blobs
-- `secret_scan.py PATH [PATH...]` — scan files/dirs directly (recurse)
-
-Exit: 0=clean, 1=findings, 2=usage error. Output masks secrets as `xxxx...`.
-
-**Pragma escape** (pattern findings only; credential filenames always fatal):
-```
-# secretscan: allow-pattern-docs
-```
-Mark file's first 10 lines to report rule-based findings as ALLOWED-DOC (non-fatal). Use only for deliberate pattern documentation.
-
-## agent-forensics.sh — Incident forensics / behavior reconstruction
-
-Read-only git plumbing; reconstructs agent behavior snapshot or diffs behavior-controlling files.
-
-- `bash tools/agent-forensics.sh <commit>` — print commit header, rules snapshot, CLAUDE.md, STATE.md, last 30 lines of BUILDLOG.md
-- `bash tools/agent-forensics.sh --diff <commitA> <commitB>` — diff CLAUDE.md, STATE.md, docs/, monitor/CHARTER.md, hooks/ between commits
-
-Exit: 0=success, 1=error (never raw git traces). Requires: git, head, tail, wc, grep.
-
-
-## Invariants
-
-- **Dependency-light**: Python tools must work on base Python 3 (no pip installs).
-- **CRLF-safe shell**: no line continuations in .sh scripts; Git Bash + Linux compatible.
-- **Never print secrets**: mask as pattern name + masked value only.
-- **Config-driven paths**: heartbeat/ledger/logs use AESOP_STATE_ROOT env var (default ./state) or CLI args; no hardcoded personal paths.
-- **Fragment-assembled secrets in tests**: scanner_selftest.py concatenates dummy secrets at runtime so pattern text never appears contiguously (self-scan invariant).
-- **verify_*.py are mandatory CI gates**: verify_dash.py and verify_submit_encoding.py are required pre-push gates; use `--allow-skip` only in truly browserless environments (CI must run both).
-- **lock.mjs is the ONLY lock implementation**: never reimplement locking in proposals.mjs or elsewhere; all proposals/state updates must use fail-closed lock.mjs with exponential backoff + stale-lock breaking.

package/ui/CLAUDE.md

@@ -1,127 +0,0 @@
-# ui/ — Web dashboard
-
-**Purpose**: Stdlib-only local observability dashboard. Serves a dark-theme HTML dashboard on a configurable port (realtime via Server-Sent Events), enabling real-time fleet monitoring without external dependencies.
-
-## Files (wave-14 U9 cutover: new React+Vite app structure)
-
-**Backend (Python, unchanged from wave-9 split)**:
-- **serve.py** — Thin (~65-line) entry point + composition layer. Wires the sibling modules, calls `config.reload()` / `csrf.init()` / `sse.reset_state()`, and re-exports their symbols so `serve.X` keeps resolving for the test suite (which loads serve.py by path) and for `python ui/serve.py`.
-- **config.py** — Path / env / `aesop.config.json` resolution. `reload()` recomputes all path globals from the current environment. **Load-bearing rule: every other module reads `config.X` at call time (`import config`), never `from config import <path>` — a frozen import would go stale after reload() (breaks test-fixture isolation).** Added in wave-14: `WEB_DIST` path pointing to `ui/web/dist/`.
-- **csrf.py** — Session-token generation (atomic O_EXCL 0600) + `validate_csrf_request()`; `init()` sets `SESSION_TOKEN`.
-- **collectors.py** — Read-only data collectors (heartbeats, repos, events, alerts, messages, backlog parse), tracker CRUD, and SSE section snapshots (incl. `read`-style tracker/orchestrator-status snapshots + inbox drain).
-- **agents.py** — Agent transcript reading (`get_fleet_agents`, `extract_agent_dispatch_prompt`) and path-traversal-safe agent-id handling (`_AGENT_ID_FORBIDDEN`).
-- **sse.py** — SSE client registry, bounded broadcast, hash-gated `_maybe_emit`, and the background `collector_loop`. `reset_state()` restores per-import collector isolation (the `sse` module is cached across test re-imports). Extended in wave-14: emits "cost" as a 6th SSE section.
-- **render.py** — Renders `ui/web/dist/index.html` (wave-14 U9 cutover: no fallback), substituting the CSRF token via a unique sentinel (the sentinel persists through Vite's build). Requires `template_path` parameter; legacy fallback removed.
-- **handler.py** — `DashboardHandler` (HTTP routing + all GET/POST endpoints incl. /api/tracker) and `run_server()`. Wave-14 additions: static serving (`GET /assets/*` from `ui/web/dist/assets/`), `/api/state` consolidated snapshot, `/api/session` for Vite dev server, `/api/cost` scorecard. Reads `config.X` / `csrf.SESSION_TOKEN` at call time.
-- **cost.py** — Parser for `state/ledger/OUTCOMES-LEDGER.md` (markdown table); returns per-model and per-day aggregates, verdict scorecards, and optional dollar estimates (only if `aesop.config.json` supplies `pricing` map).
-- **wave_prs.py** — Wave PR board collector: `get_wave_prs()` gathers open PRs (`gh pr list`) + PR-less `feat/*` branches (`git for-each-ref`), rolls check runs into passing/failing/pending/none, derives the top blocker, caches ~5s. Read-only; subprocess reads use `encoding='utf-8', errors='replace'`; degrades to `{available:false, error}` when gh is missing/un-authed. `AESOP_GH_BIN` overrides the gh binary.
-
-## State Store Integration (Wave-15)
-
-The tracker uses a **dual-path mutation model** backed by an event-sourced SQLite WAL store:
-
-- **Write path**: Mutations append events to `tracker_events.db` (WAL mode) via the StateAPI layer (`state_store/api.py`). Each mutation (create/update/delete) produces an immutable event in the event log.
-- **Read path**: `tracker.json` is re-rendered as an export (projection) from the event log on every read. This export is committed to git for checkpoint durability.
-- **Location**: `state/tracker_events.db` (SQLite WAL, never committed). `tracker.json` (rendered export, committed).
-- **Render-failure recovery**: If projection rendering fails, the UI falls back to the last-known good `tracker.json`; no data loss. Stale renders are repaired on the next successful mutation (idempotent re-render).
-
-This design provides:
-- **Durable event audit trail** (append-only events in WAL)
-- **Git-friendly checkpoints** (rendered tracker.json snapshots)
-- **Atomic mutations** (events append, projection re-renders)
-- **Graceful degradation** (fallback to last-known-good on render failure)
-
-**Frontend (React 18 + Vite + TypeScript, wave-14 U1–U8)**:
-- **ui/web/** — Complete React application (TypeScript, Vite, TypeScript strict mode).
-  - **src/main.tsx** — Vite entry point; renders `<App />` to `#root`.
-  - **src/App.tsx** — App shell: header + hash-routed view slots (/#/, /#/work, /#/activity, /#/cost).
-  - **src/styles/tokens.css** + **src/styles/global.css** — Design tokens (light/dark color palettes, spacing, typography) + base resets.
-  - **src/views/** — Page-level components (Overview, Work, Activity, Cost) with SSE bindings.
-  - **src/components/** — Reusable UI components (HealthHeader, AgentsPanel, TrackerBoard, Timeline, CostChart, etc.).
-  - **src/lib/api.ts** — Typed fetch helpers + CSRF header injection + `/api/session` fallback for dev server.
-  - **src/lib/useSSE.ts** — EventSource hook with reconnect logic, per-section state, connection status.
-  - **src/lib/types.ts** — TypeScript types for all API payloads (contract with backend).
-  - **src/lib/sanitizeUrl.ts** — XSS-safe URL parsing (PR links inert on bad schemes).
-  - **vite.config.ts** — Vite config with API proxy for `/data`, `/api`, `/events`, `/agent`, `/submit` to :8770.
-  - **dist/** — Built static files (committed to git; served by Python handler). Filenames are content-hashed by Vite.
-- **README.md** — User guide and configuration reference (updated for wave-14).
-
-## Configuration & Path Precedence
-
-Configuration is resolved in this order (first match wins):
-
-1. **Environment variables** (highest priority):
-   - `PORT` — HTTP server port (default: 8770)
-   - `AESOP_ROOT` — aesop installation root (default: `$HOME/aesop`)
-   - `AESOP_STATE_ROOT` — state directory (overrides config state_root)
-   - `AESOP_TRANSCRIPTS_ROOT` — Claude transcript directory (overrides config transcripts_root)
-   - `AESOP_UI_COLLECT_INTERVAL` — collector thread poll cadence in seconds (default: 1.0)
-
-2. **Config file** (`aesop.config.json`):
-   - `state_root` — path to state/ directory
-   - `transcripts_root` — path to Claude transcript directory
-
-3. **Built-in defaults** (lowest priority):
-   - `AESOP_ROOT/state` for state directory
-   - `~/.claude/projects` for transcripts
-
-## CSRF & Session Protection
-
-**Token model**:
-- Per-session CSRF token generated at startup, persisted to `state/.ui-session-token` (mode 0600, readable only by owner)
-- Token is 43-character URL-safe base64 string (256 bits)
-- Persistent across server restarts (read from file if exists, generate fresh if not)
-- Used to validate mutations via /submit endpoint
-
-**Validation on /submit POST**:
-1. **Origin/Referer check**: if present, must be local (http://127.0.0.1:<port>, http://localhost:<port>, or http://[::1]:<port>)
-2. **X-Aesop-Token header check**: must match SESSION_TOKEN exactly
-- Both checks fail-closed (missing header = rejection)
-- GET /events (SSE, read-only) requires no token
-
-**Local CLI access**:
-- CLI tools read token from `state/.ui-session-token` (0600) to submit to /submit endpoint
-- Legitimate browser clients: token injected into HTML template, sent by JavaScript
-
-## API Endpoints (wave-14 wave additions)
-
-**Read-only (no CSRF required)**:
-- `GET /` — Renders `ui/web/dist/index.html` with CSRF token substituted (hard 500 if dist missing).
-- `GET /assets/*` — Static files from `ui/web/dist/assets/` (content-hashed, immutable cache headers, path-traversal-safe).
-- `GET /api/state` — Consolidated first-paint snapshot: `{data, backlog, agents, tracker, status, cost}` in one round trip (reuses latest snapshots).
-- `GET /api/session` — Returns `{token}` for Vite dev server; Origin-checked fail-closed (only local origins).
-- `GET /api/cost` — Cost/scorecard summary from `state/ledger/OUTCOMES-LEDGER.md` (per-model, per-day, verdicts, optional pricing estimates).
-- `GET /api/wave/prs` — Wave PR board: open PRs (`gh pr list`) + PR-less `feat/*` branches (`git for-each-ref`), each with CI rollup / mergeable / age / top blocker. Cached ~5s; degrades to `{available:false, error}` when gh is missing/un-authenticated (never a 500). `wave_prs.py` collector; polled by the frontend (not an SSE section — `gh` is too slow for the collector tick). Set `AESOP_GH_BIN` to override the gh binary path.
-- `GET /events` — Server-Sent Events stream (read-only, no CSRF).
-
-**Mutations (CSRF-gated)**:
-- `POST /submit` — Append to inbox.
-- `POST /api/tracker`, `POST /api/tracker/<id>` — Tracker CRUD.
-
-## Server-Sent Events (SSE) Model
-
-**Realtime streaming via GET /events**:
-- ThreadingHTTPServer required (SSE holds one connection per client)
-- Streams JSON frames: `event: <section>` / `data: <json>`
-- Keepalive comment-line (`: keepalive`) sent every ~15s to prevent timeout
-- Read-only stream; no mutations
-
-**Sections emitted** (only on content change, in order):
-1. **data** — heartbeat status, daemon state, log tail
-2. **backlog** — AUDIT-BACKLOG.md parsed into tier buckets (P0/P1/P2/Needs decision)
-3. **agents** — fleet agent activity (from Claude transcripts directory)
-4. **tracker** — tracker items (CRUD mutations reflected in realtime)
-5. **status** — orchestrator phase + activity
-6. **cost** — cost/scorecard summary (wave-14 addition)
-
-## Background Collector Thread
-
-Daemon thread polling heartbeats/logs via mtime/fingerprint gates; re-derives SSE sections only on input change, broadcasts only when content-hash differs (avoids expensive operations on every tick). Started idempotently on first HTTP request via `start_collector_thread()`, runs with single-instance guard `_collector_lock`, wakes every `COLLECTOR_INTERVAL` (default 1.0s, `AESOP_UI_COLLECT_INTERVAL`).
-
-## Invariants & Gotchas
-
-- **Stdlib only**: No external dependencies (requests, flask, etc.). Uses only `http.server`, `json`, `subprocess`, `threading`.
-- **ThreadingHTTPServer required**: SSE model requires one thread per client connection. Standard HTTPServer (processes) cannot hold SSE connections open.
-- **Collector fail-open**: If collector thread crashes, server continues serving; realtime updates stop but dashboard remains accessible.
-- **Token file permissions**: On Unix-like systems, token file is chmod 0600 (user-only). Windows ignores mode bits but respects file permissions via ACLs.
-- **Paths git-ignored**: `state/.ui-session-token` is ephemeral (regenerated if missing), never committed.