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

package/tools/verify_submit_encoding.py

@@ -0,0 +1,194 @@
+"""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)
+    (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-button, real
+            # CSRF token (window.__AESOP_CSRF_TOKEN__ injected server-side).
+            page.wait_for_selector("#inbox-input", timeout=8000)
+            page.fill("#inbox-input", MARKER)
+            page.click("#inbox-button")
+
+            # 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,109 @@
+# 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-9 split: serve.py monolith decomposed into focused modules)
+
+- **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).**
+- **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).
+- **render.py** — Renders `templates/dashboard.html`, substituting the CSRF token via a unique sentinel (no `.format`/% — the CSS/JS is full of `{}`/`%`).
+- **handler.py** — `DashboardHandler` (HTTP routing + all GET/POST endpoints incl. /api/tracker) and `run_server()`. Reads `config.X` / `csrf.SESSION_TOKEN` at call time.
+- **templates/dashboard.html** — The dashboard HTML/CSS/JS (extracted from the serve.py string), incl. tracker panel + orchestrator-status panel + audit-cycle ASCII banner.
+- **README.md** — User guide and configuration reference.
+
+## API Package (ui/api/)
+
+Shared mutation-request validation and domain-logic handlers (wave-10 split from handler.py). Every mutating endpoint (`/submit`, `POST /api/tracker`, `POST /api/tracker/<id>`) gates requests identically: CSRF token validation, Content-Length bounds-check, then JSON decode. This module centralizes those gates so they are directly unit-testable without HTTP coupling.
+
+- **__init__.py** — Shared mutation gate (`validate_mutation()`). Performs CSRF validation + Content-Length bounds-check (10 KB cap) + JSON decode. Returns `(True, parsed_json)` on success or `(False, (status_code, error_dict))` on gate failure. **Load-bearing rule**: callers must bound the socket read using the same Content-Length header before invoking, to prevent DoS; MAX_BODY_BYTES is re-derived here for validation but socket read is caller's responsibility.
+- **submit.py** — Inbox-append logic (`append_to_inbox(text)`). Appends one timestamped line to `config.INBOX_FILE`, rejects symlinks (TOCTOU defense), creates file with header if missing.
+- **tracker.py** — Tracker CRUD handlers (`list_items()`, `create()`, `update()`, `delete()`). Calls `collectors` tracker functions; returns `(status_code, response_dict)` for direct HTTP response writing. **Load-bearing**: all tracker mutations pass through `validate_mutation()` in create; update/delete check CSRF via `csrf.validate_csrf_request()` performed by caller before path is parsed.
+
+**Key invariant**: All three modules read `config.X` live via `import config` at call time, never `from config import X`. A frozen import goes stale after `config.reload()` (breaks test-fixture isolation). See ui/CLAUDE.md "load-bearing rule" note above.
+
+## 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
+
+## Server-Sent Events (SSE) Model
+
+**Realtime streaming via GET /events**:
+- ThreadingHTTPServer required (SSE holds one connection per client)
+- Streams JSON frames: `event: data|backlog|agents` / `data: <json>`
+- Keepalive comment-line (`: keepalive`) sent every ~15s to prevent timeout
+- Read-only stream; no mutations
+
+**Sections emitted** (only on content change):
+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)
+
+## Background Collector Thread
+
+**Lifecycle**:
+- Started idempotently on first HTTP request (via `start_collector_thread()`)
+- Runs as daemon thread (terminates when main process exits)
+- Single-instance guard via `_collector_lock` (prevents double-start)
+
+**Polling strategy**:
+- Wakes every `COLLECTOR_INTERVAL` seconds (default: 1.0, overridable via `AESOP_UI_COLLECT_INTERVAL`)
+- Polls cheap sources: heartbeat file mtimes, log tails, file fingerprints
+- Only re-derives sections when underlying input changed (mtime/fingerprint gate)
+- Only emits to clients when section content-hash changed (avoids redundant broadcasts)
+
+**Cached data**:
+- Last computed hash per section (data/backlog/agents)
+- Last mtime of AUDIT-BACKLOG.md
+- Last fingerprint of transcripts directory (to detect agent activity changes)
+- Cached parsed backlog and agent snapshot (reused until inputs change)
+
+**Content-change detection**:
+- Mtime-gated: backlog section re-derived only if AUDIT-BACKLOG.md mtime changed
+- Fingerprint-gated: agents section re-derived only if transcripts directory content changed
+- Hash-gated: broadcast only sent if content-hash differs from last broadcast
+- This avoids expensive operations (subprocess for dash-extra.mjs, directory walk) on every tick
+
+## 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,179 @@
+#!/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 output file.
+    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 supplies
+    truncated agent IDs; files on disk carry full IDs (e.g., a77b995bcdb953e9c.output).
+    """
+    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_id*.output
+        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_id}*.output"),
+            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

package/ui/api/submit.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""
+Aesop UI API — inbox-submit logic (wave-10 P0 split from handler.py).
+
+Free function: given already-validated, non-empty text, append it to the UI
+inbox file. UTF-8/LF-safe (matches the encoding used to read the file back
+elsewhere) and guarded against a symlinked inbox file (TOCTOU defense --
+reject rather than follow a symlink another local user/process may have
+planted at config.INBOX_FILE).
+
+Reads config.INBOX_FILE live via `import config` at call time, never
+`from config import INBOX_FILE` -- a frozen import goes stale after
+config.reload() (breaks test-fixture isolation). See ui/CLAUDE.md.
+"""
+import os
+from datetime import datetime
+
+import config
+
+
+def append_to_inbox(text):
+    """Append one inbox line for `text` to config.INBOX_FILE.
+
+    Creates the file (with a header comment) if it doesn't exist yet.
+
+    Args:
+        text: non-empty, already-stripped text to record (caller is
+            responsible for validating it's non-empty -- this function does
+            not re-check).
+
+    Returns:
+        (True, None) on success.
+        (False, (400, {"error": "..."})) if config.INBOX_FILE exists and is
+            a symlink (rejected for security).
+    """
+    inbox_content = f"- [{datetime.now().isoformat()}] {text}\n"
+
+    # Security: reject symlinks (TOCTOU defense) FIRST — check islink independent
+    # of exists(). Path.exists() follows the link, so a DANGLING symlink (target
+    # not yet created) returns False and would otherwise skip this check, then
+    # open(...,'w') would follow the link and create the attacker's target.
+    if os.path.islink(str(config.INBOX_FILE)):
+        return False, (400, {"error": "Inbox file is a symlink (rejected for security)"})
+
+    if not config.INBOX_FILE.exists():
+        config.INBOX_FILE.parent.mkdir(parents=True, exist_ok=True)
+        # Must match the encoding (utf-8) AND newline convention (LF) of the
+        # append below -- text-mode write_text() with no encoding= falls back
+        # to the locale-preferred encoding (cp1252 on Windows), which mangles
+        # non-ASCII bytes like the em-dash and leaves the file as a whole not
+        # valid UTF-8 for anything that reads it with encoding="utf-8".
+        with open(config.INBOX_FILE, 'w', encoding='utf-8', newline='\n') as f:
+            f.write("# UI Inbox — orchestrator reads each turn / on /power\n\n")
+
+    with open(config.INBOX_FILE, 'a', encoding='utf-8') as f:
+        f.write(inbox_content)
+
+    return True, None