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

package/tools/verify_submit_encoding.py

@@ -0,0 +1,202 @@
+"""Browser-level proof that /submit's inbox-file bootstrap writes valid UTF-8
+(ui/serve.py, handle_submit / INBOX_FILE header write).
+
+Bug: when state/ui-inbox.md doesn't exist yet, the header used to be written
+with INBOX_FILE.write_text(...) with no encoding=. On Windows that falls back
+to the locale-preferred encoding (cp1252), so the em-dash U+2014 in the header
+is encoded as the single byte 0x97. Every subsequent append opens the file
+with encoding='utf-8'. The result is a file that is not valid UTF-8 as a
+whole: any reader that does ui-inbox.md.read_text(encoding="utf-8") (the
+normal, correct thing to do — matching the encoding the append path already
+declares) raises UnicodeDecodeError: 'utf-8' codec can't decode byte 0x97.
+That breaks the project's "orchestrator reads state/ui-inbox.md each turn /
+on /power" pipeline on Windows dev machines.
+
+This drives the REAL /submit flow end-to-end in a real headless Chromium:
+type into #inbox-input, click #inbox-button, with the real CSRF token the
+page injects — against a FRESH fixture (no pre-existing ui-inbox.md, so the
+header-bootstrap path is exercised) — then asserts:
+  (a) state/ui-inbox.md decodes cleanly via .read_text(encoding="utf-8")
+      with NO exception
+  (b) it contains the submitted marker text
+
+Run: python tools/verify_submit_encoding.py     (exit 0 = proven, 1 = failed)
+     python tools/verify_submit_encoding.py --allow-skip (exit 0 = proven or skipped, 1 = failed)
+
+Fails with exit 1 if playwright/chromium is unavailable (unless --allow-skip is passed).
+Use --allow-skip for environments that legitimately can't run a browser.
+"""
+import argparse
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SERVE = REPO / "ui" / "serve.py"
+
+MARKER = "SUBMIT-ENCODING-FIXTURE-MARKER: rebuild the flux capacitor"
+
+
+def free_port():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def build_fixture(root: Path):
+    """Fresh fixture root — deliberately does NOT create state/ui-inbox.md,
+    so /submit exercises the header-bootstrap (write_text) path, not just
+    the append path."""
+    (root / "state").mkdir(exist_ok=True)
+    (root / "transcripts").mkdir(exist_ok=True)
+    (root / "dash").mkdir(exist_ok=True)
+
+    # Copy ui/web/dist from the real repo so the server can serve the built React app
+    repo = Path(__file__).resolve().parent.parent
+    real_dist = repo / "ui" / "web" / "dist"
+    if real_dist.is_dir():
+        fixture_dist = root / "ui" / "web" / "dist"
+        shutil.copytree(real_dist, fixture_dist)
+
+    (root / "AUDIT-BACKLOG.md").write_text(
+        "# Audit backlog — verify_submit_encoding fixture\n\n## Landing log\n- fixture\n",
+        encoding="utf-8",
+    )
+    # Minimal fake detector so the collector thread has nothing real to shell out to.
+    (root / "dash" / "dash-extra.mjs").write_text(
+        "console.log(JSON.stringify([]));\n", encoding="utf-8"
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Browser-level proof for /submit UTF-8 encoding"
+    )
+    parser.add_argument(
+        "--allow-skip",
+        action="store_true",
+        help="Allow skipping if playwright/chromium is unavailable (exit 0 instead of 1)"
+    )
+    args = parser.parse_args()
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        msg = "playwright missing — run `python -m playwright install chromium`, or pass --allow-skip"
+        if args.allow_skip:
+            print(f"SKIP: {msg}")
+            return 0
+        else:
+            print(f"FAIL: {msg}")
+            return 1
+
+    root = Path(tempfile.mkdtemp(prefix="aesop-verify-submit-"))
+    state_root = root / "state"
+
+    # HARD GUARD: refuse to run if state_root looks like the real repo state dir
+    # (e.g., ~/aesop/state or an absolute path ending with /aesop/state)
+    real_state = Path.home() / "aesop" / "state"
+    if state_root.resolve() == real_state.resolve():
+        print("FAIL: state dir resolved to real repo state (~aesop/state), refusing to run")
+        return 1
+
+    inbox_file = state_root / "ui-inbox.md"
+    port = free_port()
+    env = dict(
+        os.environ,
+        AESOP_ROOT=str(root),
+        AESOP_STATE_ROOT=str(state_root),
+        AESOP_TRANSCRIPTS_ROOT=str(root / "transcripts"),
+        AESOP_UI_COLLECT_INTERVAL="0.3",
+        PORT=str(port),
+    )
+    build_fixture(root)
+    assert not inbox_file.exists(), "fixture must start WITHOUT ui-inbox.md"
+
+    server = subprocess.Popen(
+        [sys.executable, str(SERVE)], env=env,
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+    failures = []
+    try:
+        for _ in range(50):
+            try:
+                socket.create_connection(("127.0.0.1", port), timeout=0.2).close()
+                break
+            except OSError:
+                time.sleep(0.2)
+        else:
+            print("FAIL: server never came up")
+            return 1
+
+        with sync_playwright() as pw:
+            try:
+                browser = pw.chromium.launch(headless=True)
+            except Exception as e:
+                msg = f"chromium unavailable ({e}); run: python -m playwright install chromium"
+                if args.allow_skip:
+                    print(f"SKIP: {msg}")
+                    return 0
+                else:
+                    print(f"FAIL: {msg}")
+                    return 1
+            page = browser.new_page()
+            page.goto(f"http://127.0.0.1:{port}/", wait_until="domcontentloaded")
+
+            # Drive the real /submit flow: inbox-input -> inbox-submit, real
+            # CSRF token (window.__AESOP_CSRF_TOKEN__ injected server-side).
+            page.wait_for_selector("[data-testid='inbox-input']", timeout=8000)
+            page.fill("[data-testid='inbox-input']", MARKER)
+            page.click("[data-testid='inbox-submit']")
+
+            # Wait for the inbox file to land on disk (async POST).
+            for _ in range(50):
+                if inbox_file.exists():
+                    break
+                time.sleep(0.2)
+            else:
+                failures.append("state/ui-inbox.md was never created by /submit")
+
+            browser.close()
+    finally:
+        server.terminate()
+        try:
+            server.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            server.kill()
+
+    if not failures:
+        raw = inbox_file.read_bytes()
+        try:
+            text = inbox_file.read_text(encoding="utf-8")
+        except UnicodeDecodeError as e:
+            bad_byte = raw[e.start:e.end].hex()
+            failures.append(
+                f"(a) state/ui-inbox.md is not valid UTF-8: {e} "
+                f"(offending byte(s): 0x{bad_byte}) — raw bytes: {raw!r}"
+            )
+        else:
+            if MARKER not in text:
+                failures.append(f"(b) submitted marker text not found in inbox file: {text!r}")
+
+    shutil.rmtree(root, ignore_errors=True)
+
+    if failures:
+        print("FAIL:")
+        for f in failures:
+            print("  -", f)
+        return 1
+    print("PROVEN: (a) state/ui-inbox.md decodes cleanly as UTF-8 "
+          "(b) submitted marker text present")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/ui/CLAUDE.md

@@ -0,0 +1,125 @@
+# 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).
+
+## 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 /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.

package/ui/agents.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Aesop UI — agent transcript reading + path-traversal-safe id handling (wave-9 split)."""
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import config
+
+
+def get_fleet_agents():
+    """Detect running subagents by calling dash-extra.mjs --json.
+
+    dash-extra.mjs truncates agent ids to 13 characters for display. With enough
+    concurrently-active agents, two distinct agents can share the same 13-char
+    prefix and collide onto the same id. The dashboard keys DOM rows (and the
+    click-to-expand lookup) by this id, so a collision silently merges two
+    different agents into one row and can show mismatched detail on click. Since
+    dash-extra.mjs is out of scope here, disambiguate post-hoc: keep the original
+    (display-friendly) id as a prefix, but suffix it to guarantee uniqueness.
+    """
+    agents = []
+    try:
+        # Call the working detector (dash-extra.mjs) with --json flag
+        dash_extra_path = config.AESOP_ROOT / "dash" / "dash-extra.mjs"
+        if not dash_extra_path.exists():
+            return agents
+        result = subprocess.run(
+            ["node", str(dash_extra_path), "--json"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode == 0 and result.stdout:
+            agents = json.loads(result.stdout.strip())
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError):
+        pass
+    except Exception:
+        pass
+
+    seen = {}
+    for a in agents:
+        if not isinstance(a, dict):
+            continue
+        aid = a.get("id", "")
+        if aid in seen:
+            seen[aid] += 1
+            a["id"] = f"{aid}-{seen[aid]}"
+        else:
+            seen[aid] = 1
+    return agents
+
+_AGENT_ID_FORBIDDEN = re.compile(r'\.\.|[/\\*?\[\]]')
+
+def extract_agent_dispatch_prompt(agent_id):
+    """
+    Extract dispatch prompt and metadata from agent jsonl transcript.
+    Returns dict with prompt, dispatcher, model, activity times, and message count.
+    Robust: missing/invalid file -> {error: "..."}
+    Security: rejects agent_id containing path-traversal or glob-metacharacter
+    sequences before building any glob pattern, and refuses to return a match
+    that resolves outside config.TRANSCRIPTS_ROOT (defense in depth). Error results
+    carry "invalid": True when the input itself was rejected, so callers can
+    map that to an HTTP 400 rather than a plain 404.
+
+    CRITICAL: Use prefix-matching via glob, not exact match. The dashboard (dash-extra.mjs)
+    scans for agent-*.jsonl files and emits a 13-char truncated ID; files on disk carry
+    full IDs (e.g., agent-a77b995bcdb953e9c1234567.jsonl). This function must search for
+    the same file format that the dashboard actually finds.
+    """
+    try:
+        if not agent_id or _AGENT_ID_FORBIDDEN.search(agent_id):
+            return {"error": "invalid agent id", "invalid": True}
+
+        # Prefix-match: search in config.TRANSCRIPTS_ROOT for files matching agent-agent_id*.jsonl
+        # The dashboard (dash-extra.mjs) scans for agent-*.jsonl files and emits
+        # a 13-char truncated ID; we must match against the same .jsonl files.
+        if not config.TRANSCRIPTS_ROOT.exists():
+            return {"error": f"transcripts root not found at {config.TRANSCRIPTS_ROOT}"}
+
+        # Glob for matching files (prefix-match handles truncated IDs)
+        matches = sorted(
+            config.TRANSCRIPTS_ROOT.glob(f"**/agent-{agent_id}*.jsonl"),
+            key=lambda p: p.stat().st_mtime, reverse=True,
+        )
+        if not matches:
+            return {"error": f"transcript not found for {agent_id}"}
+        output_file = matches[0]
+
+        # Containment check: the resolved match must stay inside config.TRANSCRIPTS_ROOT.
+        # Belt-and-suspenders alongside the input rejection above.
+        try:
+            is_contained = output_file.resolve().is_relative_to(config.TRANSCRIPTS_ROOT.resolve())
+        except AttributeError:
+            # Path.is_relative_to requires Python 3.9+; fall back for older runtimes.
+            try:
+                output_file.resolve().relative_to(config.TRANSCRIPTS_ROOT.resolve())
+                is_contained = True
+            except ValueError:
+                is_contained = False
+        if not is_contained:
+            return {"error": "resolved path outside transcripts root", "invalid": True}
+
+        dispatch_prompt = None
+        message_count = 0
+        model = None
+        parent_uuid = None
+        first_seen = None
+        last_activity = None
+
+        # Parse NDJSON (one JSON per line)
+        with open(output_file, 'r', encoding='utf-8', errors='ignore') as f:
+            lines = f.readlines()
+            message_count = len(lines)
+
+            # Get file mtime for activity time
+            stat = output_file.stat()
+            first_seen = int(stat.st_mtime)
+            last_activity = int(stat.st_mtime)
+
+            # First line should be type="user" with the dispatch prompt
+            if lines:
+                try:
+                    first_line = json.loads(lines[0])
+                    if first_line.get('type') == 'user':
+                        msg = first_line.get('message', {})
+                        dispatch_prompt = msg.get('content', '')
+                        parent_uuid = first_line.get('parentUuid')
+                except (json.JSONDecodeError, KeyError):
+                    pass
+
+            # Scan for model info in assistant messages
+            for line in lines[1:20]:  # Check first ~20 lines
+                try:
+                    obj = json.loads(line)
+                    if obj.get('type') == 'assistant' and not model:
+                        if 'model' in obj:
+                            model = obj.get('model')
+                except (json.JSONDecodeError, KeyError):
+                    pass
+
+        if not dispatch_prompt:
+            return {"error": f"no dispatch prompt found"}
+
+        # Infer dispatcher: if parentUuid is null, it's main thread; otherwise parent agent
+        dispatcher = "main thread" if parent_uuid is None else "parent agent"
+
+        return {
+            "id": agent_id,
+            "dispatch_prompt": dispatch_prompt,
+            "dispatcher": dispatcher,
+            "model": model or "unknown",
+            "message_count": message_count,
+            "first_seen": first_seen,
+            "last_activity": last_activity,
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+def _transcripts_fingerprint():
+    """Cheap fs-stat-only fingerprint of the transcripts tree.
+
+    Used to decide whether it's worth re-invoking `node dash-extra.mjs` (which is
+    comparatively expensive: process spawn + re-parsing every agent transcript).
+    Only file count + max mtime — no file content is read.
+    """
+    try:
+        if not config.TRANSCRIPTS_ROOT.exists():
+            return (0, 0.0)
+        count = 0
+        latest = 0.0
+        for p in config.TRANSCRIPTS_ROOT.glob("**/agent-*.jsonl"):
+            try:
+                mtime = p.stat().st_mtime
+            except OSError:
+                continue
+            count += 1
+            if mtime > latest:
+                latest = mtime
+        return (count, latest)
+    except Exception:
+        return (0, 0.0)

package/ui/api/__init__.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+Aesop UI API — shared mutation-request validation (wave-10 P0 split from handler.py).
+
+Every mutating endpoint (/submit, POST /api/tracker, POST /api/tracker/<id>)
+repeats the same two gates before touching domain logic: CSRF validation and
+a Content-Length bound check, followed by a JSON body parse. This module
+centralizes those two gates + the parse so they are directly unit-testable
+without an HTTP server (see tests/test_api_tracker.py).
+
+SAFETY NOTE (load-bearing): callers MUST check Content-Length is within
+[1, MAX_BODY_BYTES] *before* calling self.rfile.read() on the live socket --
+reading an attacker-declared length without a cap first is exactly the DoS
+hole this gate exists to close. validate_mutation() re-derives the same
+bound from headers (cheap, no I/O) so its error response matches what the
+caller already decided; callers should gate their own read using
+MAX_BODY_BYTES from this module so the two stay in lockstep. This module
+never touches the socket itself -- it only ever receives bytes the caller
+already obtained.
+
+Sibling modules (ui/api/tracker.py, ui/api/submit.py) that read config paths
+must do so live via `import config` at call time, never `from config import
+<path>` -- a frozen import goes stale after config.reload() (breaks
+test-fixture isolation). See ui/CLAUDE.md.
+"""
+import json
+
+from csrf import validate_csrf_request
+
+
+class NotFoundError(Exception):
+    """Raised when a tracker item is not found."""
+    pass
+
+
+# Mutating endpoints cap request bodies at 10KB. Kept as a shared constant so
+# handler.py's pre-read bound check and this module's own re-check never drift.
+MAX_BODY_BYTES = 10000
+
+
+def validate_mutation(headers, body_bytes, content_length_error="Invalid Content-Length"):
+    """Run the CSRF + Content-Length gates shared by every mutating endpoint,
+    then JSON-decode the body.
+
+    Args:
+        headers: dict-like HTTP headers (case-insensitive), as accepted by
+            csrf.validate_csrf_request.
+        body_bytes: raw request body bytes already read by the caller. The
+            caller must have bounded how many bytes it read using the same
+            Content-Length header (see SAFETY NOTE above) -- this function
+            performs no socket I/O itself.
+        content_length_error: exact error message to use on an out-of-range
+            Content-Length, so callers can preserve endpoint-specific wording
+            (e.g. /submit's "Invalid Content-Length (must be 1-10000 bytes)"
+            vs /api/tracker's "Invalid Content-Length").
+
+    Returns:
+        (True, parsed) where parsed is the decoded JSON value (typically a
+            dict) on success.
+        (False, (status_code, error_dict)) on a CSRF or Content-Length gate
+            failure -- callers should write this directly as the JSON error
+            response.
+
+    Note: a malformed JSON body raises json.JSONDecodeError rather than being
+    caught here, so callers can keep their historical per-endpoint handling
+    (some endpoints report 400 "Invalid JSON", others let the parse failure
+    fall through to a generic 500) -- see ui/api/tracker.py and
+    ui/api/submit.py callers in ui/handler.py.
+    """
+    is_valid, reason = validate_csrf_request(headers)
+    if not is_valid:
+        return False, (403, {"error": "CSRF protection: " + reason})
+
+    try:
+        content_length = int(headers.get('Content-Length', 0) or 0)
+    except (TypeError, ValueError):
+        content_length = 0
+
+    if content_length <= 0 or content_length > MAX_BODY_BYTES:
+        return False, (400, {"error": content_length_error})
+
+    body_str = (body_bytes or b'').decode('utf-8', errors='ignore')
+    parsed = json.loads(body_str)
+    return True, parsed