@matt82198/aesop 0.1.0-beta.5 → 0.1.0

package/ui/CLAUDE.md

@@ -14,6 +14,7 @@
 - **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)
 
@@ -90,6 +91,7 @@ Configuration is resolved in this order (first match wins):
 - `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)**:

package/ui/agents.py

@@ -9,6 +9,53 @@ from pathlib import Path
 import config
 
 
+def _path_is_contained(child, root):
+    """Check if child path is contained within root path (no traversal).
+
+    Returns True if child is under root, False if it escapes (e.g., via ..).
+    Uses Path.is_relative_to (Python 3.9+) with a fallback for older runtimes.
+
+    Args:
+        child: Path object (typically resolved)
+        root: Path object (typically resolved)
+
+    Returns:
+        bool: True if child is contained within root, False otherwise
+    """
+    try:
+        return child.is_relative_to(root.resolve())
+    except AttributeError:
+        # Path.is_relative_to requires Python 3.9+; fall back for older runtimes.
+        try:
+            child.relative_to(root.resolve())
+            return True
+        except ValueError:
+            return False
+
+
+def sanitize_agents_for_broadcast(agents):
+    """Strip large prompt fields from agents before SSE broadcast.
+
+    Wave-19 fix: Remove promptFull, dispatch_prompt, and other multi-KB fields
+    from agents snapshots before sending via SSE. The React app never reads
+    these full prompts (it lazy-fetches them via /agent?id= endpoint), so
+    stripping them saves bandwidth on every tick. Keeps summary fields only.
+    """
+    sanitized = []
+    for agent in agents:
+        if not isinstance(agent, dict):
+            sanitized.append(agent)
+            continue
+        # Drop only the multi-KB prompt fields; keep everything else the
+        # frontend Agent contract reads (ui/web/src/lib/types.ts) — id,
+        # project, status, age_s, hint, startedAt, lastActivity,
+        # runtimeSeconds, tokensUsed, taskLabel.
+        strip_fields = {"promptFull", "dispatch_prompt"}
+        summary = {k: v for k, v in agent.items() if k not in strip_fields}
+        sanitized.append(summary)
+    return sanitized
+
+
 def get_fleet_agents():
     """Detect running subagents by calling dash-extra.mjs --json.
 
@@ -30,6 +77,8 @@ def get_fleet_agents():
             ["node", str(dash_extra_path), "--json"],
             capture_output=True,
             text=True,
+            encoding='utf-8',
+            errors='replace',
             timeout=5
         )
         if result.returncode == 0 and result.stdout:
@@ -53,6 +102,272 @@ def get_fleet_agents():
 
 _AGENT_ID_FORBIDDEN = re.compile(r'\.\.|[/\\*?\[\]]')
 
+# Transcript-tail bounds (defense against loading a whole multi-MB transcript
+# into memory and against emitting an unbounded payload to the browser).
+TRANSCRIPT_TAIL_LINES = 40          # last N NDJSON lines rendered in the drawer
+TRANSCRIPT_TAIL_MAX_BYTES = 256 * 1024   # only ever seek-read this much from EOF
+TRANSCRIPT_TAIL_ENTRY_MAXLEN = 2000      # per-entry text cap (chars)
+
+# Best-effort credential redaction for the transcript tail. These are the
+# high-confidence, unambiguous secret FORMATS (mirroring the fatal rules in
+# tools/secret_scan.py) plus bearer/authorization values. This is defense in
+# depth, NOT a guarantee: a novel or bespoke credential format can still slip
+# through, so the tail is a read-only convenience, never an audited-clean feed.
+# tools/secret_scan.py is deliberately NOT imported (it is not on the UI import
+# path and pulling it in would couple the dashboard to the push-gate tool); the
+# patterns are duplicated here in a tiny, stdlib-only form.
+_REDACTION_PATTERNS = [
+    re.compile(r'-----BEGIN[^\n]*PRIVATE KEY-----', re.IGNORECASE),
+    re.compile(r'AKIA[0-9A-Z]{16}'),
+    re.compile(r'(?:ghp_|gho_|ghu_|ghs_|ghr_|github_pat_)[A-Za-z0-9_]{20,}'),
+    re.compile(r'xox[baprs]-[A-Za-z0-9-]{10,}'),
+    re.compile(r'sk-[A-Za-z0-9_\-]{20,}'),
+    re.compile(r'(?i:bearer)\s+[A-Za-z0-9._\-]{20,}'),
+    # key/secret/password/token = <value> (quoted or bare) — mask the value.
+    re.compile(
+        r'(?i)((?:api[_-]?key|secret|password|passwd|token|authorization)'
+        r'\s*[:=]\s*)([^\s"\',}]{12,})'
+    ),
+]
+
+
+def _redact_secrets(text):
+    """Best-effort masking of high-confidence credential formats in free text.
+
+    Returns text with any matched secret replaced by a short prefix + a
+    REDACTED marker (so an operator can still eyeball that *something* was
+    there). Never raises. See _REDACTION_PATTERNS for the (intentionally
+    limited) coverage and its documented limits.
+    """
+    if not text:
+        return text
+
+    def _mask(match):
+        groups = match.groups()
+        if len(groups) == 2:
+            # key/value form: keep the "key = " prefix, mask only the value.
+            return f"{groups[0]}***REDACTED***"
+        token = match.group(0)
+        prefix = token[:4] if len(token) > 8 else ""
+        return f"{prefix}***REDACTED***"
+
+    for pat in _REDACTION_PATTERNS:
+        try:
+            text = pat.sub(_mask, text)
+        except re.error:
+            continue
+    return text
+
+
+def _resolve_transcript_path(agent_id):
+    """Resolve an agent id to its on-disk transcript file, path-traversal-safe.
+
+    Shared by extract_agent_dispatch_prompt() and get_agent_detail() so the
+    security contract (reject `.. / \\ * ? [ ]` before any glob, then verify the
+    resolved match stays inside config.TRANSCRIPTS_ROOT) can never drift between
+    the two endpoints.
+
+    Returns (Path, None) on a clean match, or (None, error_dict) otherwise.
+    error_dict carries "invalid": True for a rejected input (caller maps to
+    HTTP 400); its absence means a well-formed id that simply had no transcript
+    (caller maps to HTTP 404). Never raises for the expected failure modes.
+    """
+    if not agent_id or _AGENT_ID_FORBIDDEN.search(agent_id):
+        return None, {"error": "invalid agent id", "invalid": True}
+
+    if not config.TRANSCRIPTS_ROOT.exists():
+        return None, {"error": f"transcripts root not found at {config.TRANSCRIPTS_ROOT}"}
+
+    matches = sorted(
+        config.TRANSCRIPTS_ROOT.glob(f"**/agent-{agent_id}*.jsonl"),
+        key=lambda p: p.stat().st_mtime, reverse=True,
+    )
+    if not matches:
+        return None, {"error": f"transcript not found for {agent_id}"}
+
+    output_file = matches[0]
+    if not _path_is_contained(output_file.resolve(), config.TRANSCRIPTS_ROOT):
+        return None, {"error": "resolved path outside transcripts root", "invalid": True}
+
+    return output_file, None
+
+
+def _read_tail_lines(path, max_lines=TRANSCRIPT_TAIL_LINES,
+                     max_bytes=TRANSCRIPT_TAIL_MAX_BYTES):
+    """Return roughly the last `max_lines` text lines of a file, bounded.
+
+    Seeks to at most `max_bytes` from EOF so a huge transcript is never fully
+    read into memory. Decodes utf-8 with errors='replace' (wave-27 lesson) so
+    undecodable bytes never raise. When the read started mid-file the first
+    (probably partial) line is dropped. Returns (lines, truncated) where
+    truncated is True if the file was larger than the window we read.
+    """
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return [], False
+    to_read = min(size, max_bytes)
+    try:
+        with open(path, 'rb') as f:
+            if size > to_read:
+                f.seek(size - to_read)
+            raw = f.read()
+    except OSError:
+        return [], False
+    text = raw.decode('utf-8', errors='replace')
+    lines = text.splitlines()
+    windowed = size > to_read
+    if windowed and len(lines) > 1:
+        lines = lines[1:]  # drop the partial leading line
+    truncated = windowed or len(lines) > max_lines
+    return lines[-max_lines:], truncated
+
+
+def _extract_line_text(obj):
+    """Pull a readable text summary out of one parsed transcript record.
+
+    Handles the shapes Claude Code emits: message.content as a plain string, or
+    as a list of content blocks (text / tool_use / tool_result / thinking).
+    Returns a plain string (never HTML); the frontend renders it as text.
+    """
+    msg = obj.get("message")
+    content = msg.get("content") if isinstance(msg, dict) else None
+    if content is None:
+        content = obj.get("content")
+
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict):
+                btype = block.get("type")
+                if btype == "text" and isinstance(block.get("text"), str):
+                    parts.append(block["text"])
+                elif btype == "thinking" and isinstance(block.get("thinking"), str):
+                    parts.append(f"[thinking] {block['thinking']}")
+                elif btype == "tool_use":
+                    parts.append(f"[tool_use: {block.get('name', '?')}]")
+                elif btype == "tool_result":
+                    parts.append("[tool_result]")
+        return "\n".join(p for p in parts if p)
+    return ""
+
+
+def _summarize_transcript_line(raw_line):
+    """Turn one NDJSON line into a {"type", "text"} tail entry, or None to skip.
+
+    Robust to non-JSON / non-dict lines (returned as a "raw" entry). Text is
+    secret-redacted and length-capped so the payload stays bounded and XSS-safe
+    (plain strings only — the client escapes on render).
+    """
+    raw_line = raw_line.strip()
+    if not raw_line:
+        return None
+    try:
+        obj = json.loads(raw_line)
+    except (json.JSONDecodeError, ValueError):
+        return {"type": "raw", "text": _redact_secrets(raw_line[:TRANSCRIPT_TAIL_ENTRY_MAXLEN])}
+    if not isinstance(obj, dict):
+        return {"type": "raw", "text": _redact_secrets(str(obj)[:TRANSCRIPT_TAIL_ENTRY_MAXLEN])}
+    entry_type = str(obj.get("type", "unknown"))
+    text = _extract_line_text(obj)
+    text = _redact_secrets(text[:TRANSCRIPT_TAIL_ENTRY_MAXLEN])
+    return {"type": entry_type, "text": text}
+
+
+def get_agent_detail(agent_id, tail_lines=TRANSCRIPT_TAIL_LINES):
+    """Agent detail for the inspector drawer: dispatch prompt + bounded tail.
+
+    Read-only. Reuses _resolve_transcript_path() for the same path-traversal /
+    glob-injection protection as extract_agent_dispatch_prompt(), then reads
+    ONLY the last ~tail_lines lines of the transcript (never the whole file) and
+    returns them as a list of {type, text} entries with best-effort credential
+    redaction applied.
+
+    Success shape:
+        {id, dispatch_prompt, dispatcher, model, message_count, first_seen,
+         last_activity, transcript_tail: [{type, text}, ...], tail_truncated}
+
+    Error shape (same convention as extract_agent_dispatch_prompt):
+        {"error": str}                 -> caller returns 404
+        {"error": str, "invalid": True} -> caller returns 400
+    Never raises: an unexpected failure degrades to a generic error dict.
+    """
+    try:
+        output_file, err = _resolve_transcript_path(agent_id)
+        if err is not None:
+            return err
+
+        stat = output_file.stat()
+        first_seen = int(stat.st_mtime)
+        last_activity = int(stat.st_mtime)
+
+        dispatch_prompt = None
+        model = None
+        parent_uuid = None
+        message_count = 0
+
+        # Header parse: first line = dispatch prompt; scan a few for the model.
+        # Bounded read of just the head lines (the tail is read separately).
+        try:
+            with open(output_file, 'r', encoding='utf-8', errors='replace') as f:
+                head = []
+                for i, line in enumerate(f):
+                    if i < 20:
+                        head.append(line)
+                    message_count += 1
+            if head:
+                try:
+                    first = json.loads(head[0])
+                    if first.get('type') == 'user':
+                        msg = first.get('message', {})
+                        dispatch_prompt = msg.get('content', '')
+                        parent_uuid = first.get('parentUuid')
+                except (json.JSONDecodeError, KeyError):
+                    pass
+                for line in head[1:]:
+                    try:
+                        obj = json.loads(line)
+                        if obj.get('type') == 'assistant' and not model and 'model' in obj:
+                            model = obj.get('model')
+                    except (json.JSONDecodeError, KeyError):
+                        pass
+        except OSError:
+            pass
+
+        # dispatch_prompt may be a content-block list; normalise to a string.
+        if isinstance(dispatch_prompt, list):
+            dispatch_prompt = _extract_line_text({"content": dispatch_prompt})
+        dispatch_prompt = _redact_secrets(dispatch_prompt or "")
+
+        tail_raw, truncated = _read_tail_lines(output_file, max_lines=tail_lines)
+        transcript_tail = []
+        for line in tail_raw:
+            entry = _summarize_transcript_line(line)
+            if entry is not None:
+                transcript_tail.append(entry)
+
+        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,
+            "transcript_tail": transcript_tail,
+            "tail_truncated": truncated,
+        }
+    except Exception as e:
+        print(f"[get_agent_detail] Uncaught exception: {e}", file=sys.stderr)
+        return {"error": "Failed to load agent detail"}
+
+
 def extract_agent_dispatch_prompt(agent_id):
     """
     Extract dispatch prompt and metadata from agent jsonl transcript.
@@ -70,37 +385,12 @@ def extract_agent_dispatch_prompt(agent_id):
     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}
+        # Path-traversal / glob-injection protection + prefix-match resolution
+        # live in the shared _resolve_transcript_path() so this endpoint and the
+        # inspector's get_agent_detail() can never drift apart on security.
+        output_file, err = _resolve_transcript_path(agent_id)
+        if err is not None:
+            return err
 
         dispatch_prompt = None
         message_count = 0
@@ -110,7 +400,7 @@ def extract_agent_dispatch_prompt(agent_id):
         last_activity = None
 
         # Parse NDJSON (one JSON per line)
-        with open(output_file, 'r', encoding='utf-8', errors='ignore') as f:
+        with open(output_file, 'r', encoding='utf-8', errors='replace') as f:
             lines = f.readlines()
             message_count = len(lines)
 
@@ -143,6 +433,14 @@ def extract_agent_dispatch_prompt(agent_id):
         if not dispatch_prompt:
             return {"error": f"no dispatch prompt found"}
 
+        # dispatch_prompt may be a content-block list; normalise to a string,
+        # then redact credentials before this leaves the process (same
+        # contract as get_agent_detail() — wave-32 fix, this endpoint had
+        # drifted and was returning secrets unredacted).
+        if isinstance(dispatch_prompt, list):
+            dispatch_prompt = _extract_line_text({"content": dispatch_prompt})
+        dispatch_prompt = _redact_secrets(dispatch_prompt or "")
+
         # Infer dispatcher: if parentUuid is null, it's main thread; otherwise parent agent
         dispatcher = "main thread" if parent_uuid is None else "parent agent"
 
@@ -156,7 +454,8 @@ def extract_agent_dispatch_prompt(agent_id):
             "last_activity": last_activity,
         }
     except Exception as e:
-        return {"error": str(e)}
+        print(f"[extract_agent_dispatch_prompt] Uncaught exception: {e}", file=sys.stderr)
+        return {"error": "Failed to extract dispatch prompt"}
 
 def _transcripts_fingerprint():
     """Cheap fs-stat-only fingerprint of the transcripts tree.

package/ui/api/tracker.py

@@ -33,7 +33,9 @@ def list_items(status=None, priority=None):
         items = get_tracker_items(status=status, priority=priority)
         return 200, items
     except Exception as e:
-        return 500, {"error": str(e)}
+        import sys
+        print(f"[tracker.list_items] Uncaught exception: {e}", file=sys.stderr)
+        return 500, {"error": "Internal server error"}
 
 
 def create(headers, body_bytes):
@@ -59,7 +61,9 @@ def create(headers, body_bytes):
     except json.JSONDecodeError:
         return 400, {"error": "Invalid JSON"}
     except Exception as e:
-        return 500, {"error": str(e)}
+        import sys
+        print(f"[tracker.create] Uncaught exception: {e}", file=sys.stderr)
+        return 500, {"error": "Internal server error"}
 
 
 def update(item_id, body_bytes):
@@ -83,14 +87,16 @@ def update(item_id, body_bytes):
             preserves the pre-split handler's behavior).
     """
     try:
-        body_str = (body_bytes or b'').decode('utf-8', errors='ignore')
+        body_str = (body_bytes or b'').decode('utf-8', errors='replace')
         update_data = json.loads(body_str)
         item = update_tracker_item(item_id, update_data)
         return 200, item
     except Exception as e:
+        import sys
         if "404" in str(e):
-            return 404, {"error": str(e)}
-        return 500, {"error": str(e)}
+            return 404, {"error": "404 Item not found"}
+        print(f"[tracker.update] Uncaught exception: {e}", file=sys.stderr)
+        return 500, {"error": "Internal server error"}
 
 
 def delete(item_id):
@@ -111,6 +117,8 @@ def delete(item_id):
         item = delete_tracker_item(item_id)
         return 200, item
     except Exception as e:
+        import sys
         if "404" in str(e):
-            return 404, {"error": str(e)}
-        return 500, {"error": str(e)}
+            return 404, {"error": "404 Item not found"}
+        print(f"[tracker.delete] Uncaught exception: {e}", file=sys.stderr)
+        return 500, {"error": "Internal server error"}

package/ui/collectors.py

@@ -233,7 +233,7 @@ def get_main_thread_messages():
             return messages
 
         newest = jsonl_files[0]
-        with open(newest, 'r', encoding='utf-8', errors='ignore') as f:
+        with open(newest, 'r', encoding='utf-8', errors='replace') as f:
             lines = f.readlines()
             # Get last 30 lines to extract ~12 message turns
             for line in lines[-30:]:
@@ -639,6 +639,85 @@ def _snapshot_orchestrator_status():
         print(f"[status] Snapshot error: {e}", file=sys.stderr)
         return {"orchestrators": []}
 
+def _recover_stranded_inbox_files():
+    """Defect 3 fix: Recovery sweep for .tracker-inbox.jsonl.processing-* files.
+
+    If drain_tracker_inbox crashes mid-process, it leaves a .processing-* file.
+    This sweep re-ingests those files on the next drain call, preventing silent
+    data loss. Returns list of items recovered.
+    """
+    recovered = []
+    try:
+        for processing_file in sorted(config.STATE_DIR.glob(".tracker-inbox.jsonl.processing-*")):
+            if not processing_file.exists():
+                continue
+            try:
+                content = processing_file.read_text(encoding='utf-8')
+                if not content.strip():
+                    try:
+                        processing_file.unlink()
+                    except Exception:
+                        pass
+                    continue
+
+                # Build dedup hash set from both tracker.json and event store
+                existing_hashes = set()
+
+                # Check rendered tracker.json
+                tracker_json = load_tracker()
+                for item in tracker_json.get("items", []):
+                    source = item.get("source", "")
+                    title = item.get("title", "")
+                    h = hashlib.sha256((source + ":" + title).encode()).hexdigest()
+                    existing_hashes.add(h)
+
+                # Check event store projection
+                try:
+                    api = _tracker_api()
+                    projected = api.project("tracker")
+                    for item in projected.get("items", []):
+                        source = item.get("source", "")
+                        title = item.get("title", "")
+                        h = hashlib.sha256((source + ":" + title).encode()).hexdigest()
+                        existing_hashes.add(h)
+                except Exception as e:
+                    print(f"[inbox] Recovery: failed to project tracker state: {e}", file=sys.stderr)
+
+                # Reprocess lines from the recovered file
+                lines = content.strip().splitlines()
+                for line in lines:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        if not isinstance(entry, dict):
+                            continue
+                        source = entry.get("source", "")
+                        title = entry.get("title", "")
+                        h = hashlib.sha256((source + ":" + title).encode()).hexdigest()
+
+                        if h not in existing_hashes:
+                            item = create_tracker_item(entry)
+                            recovered.append(item)
+                            existing_hashes.add(h)
+                    except (json.JSONDecodeError, Exception):
+                        pass
+
+                # Only delete after successful re-ingest
+                try:
+                    processing_file.unlink()
+                except Exception as e:
+                    print(f"[inbox] Recovery: failed to unlink {processing_file}: {e}", file=sys.stderr)
+
+            except Exception as e:
+                print(f"[inbox] Recovery sweep error on {processing_file}: {e}", file=sys.stderr)
+    except Exception as e:
+        print(f"[inbox] Recovery sweep failed: {e}", file=sys.stderr)
+
+    return recovered
+
+
 def drain_tracker_inbox():
     """Drain .tracker-inbox.jsonl, create items idempotently.
 
@@ -646,31 +725,40 @@ def drain_tracker_inbox():
     to ensure only one caller processes it under concurrent access. Strengthen
     dedup to check both tracker.json AND api.project("tracker") so items
     in the event store but not yet rendered are also excluded.
+
+    Defect 3 fix: Before processing the current inbox, perform a recovery sweep
+    to re-ingest leftover .tracker-inbox.jsonl.processing-* files from any
+    previous crashes. This prevents silent data loss if a crash happens
+    mid-drain: stranded files are recovered on the next drain call.
     """
     inbox_file = config.STATE_DIR / ".tracker-inbox.jsonl"
+
+    # Defect 3: Recovery sweep for stranded .processing-* files from prior crashes.
+    created = _recover_stranded_inbox_files()
+
+    # Now process the current inbox if it exists
     if not inbox_file.exists():
-        return []
+        return created
 
-    created = []
+    # Defect 1: Atomically rename inbox to unique processing name first.
+    # This ensures only one caller wins; others see no file.
+    processing_file = inbox_file.with_name(
+        f".tracker-inbox.jsonl.processing-{secrets.token_hex(8)}"
+    )
     try:
-        # Defect 1: Atomically rename inbox to unique processing name first.
-        # This ensures only one caller wins; others see no file.
-        processing_file = inbox_file.with_name(
-            f".tracker-inbox.jsonl.processing-{secrets.token_hex(8)}"
-        )
-        try:
-            os.replace(str(inbox_file), str(processing_file))
-        except FileNotFoundError:
-            # Another caller already renamed it; nothing to process
-            return []
-        except Exception as e:
-            print(f"[inbox] Failed to rename inbox: {e}", file=sys.stderr)
-            return []
+        os.replace(str(inbox_file), str(processing_file))
+    except FileNotFoundError:
+        # Another caller already renamed it; nothing to process
+        return created
+    except Exception as e:
+        print(f"[inbox] Failed to rename inbox: {e}", file=sys.stderr)
+        return created
 
+    try:
         content = processing_file.read_text(encoding='utf-8')
         if not content.strip():
             processing_file.unlink()
-            return []
+            return created
 
         lines = content.strip().splitlines()
 
@@ -707,29 +795,34 @@ def drain_tracker_inbox():
                 continue
             try:
                 entry = json.loads(line)
-                if not isinstance(entry, dict):
-                    rejects.append(line)
-                    continue
-
-                source = entry.get("source", "")
-                title = entry.get("title", "")
-                h = hashlib.sha256((source + ":" + title).encode()).hexdigest()
-
-                if h not in existing_hashes:
-                    item = create_tracker_item(entry)
-                    created.append(item)
-                    existing_hashes.add(h)
             except json.JSONDecodeError:
                 rejects.append(line)
-            except Exception as e:
-                rejects.append(line + " # " + str(e))
+                continue
+
+            if not isinstance(entry, dict):
+                rejects.append(line)
+                continue
+
+            source = entry.get("source", "")
+            title = entry.get("title", "")
+            h = hashlib.sha256((source + ":" + title).encode()).hexdigest()
+
+            if h not in existing_hashes:
+                # create_tracker_item can raise real errors (not malformed JSON)
+                # let those bubble up rather than silently adding to rejects
+                item = create_tracker_item(entry)
+                created.append(item)
+                existing_hashes.add(h)
 
         if rejects:
             rejects_file = inbox_file.with_name(".tracker-inbox.rejects")
             rejects_file.write_text("\n".join(rejects) + "\n", encoding='utf-8')
 
+        # Only delete the processing file after successful completion.
+        # If an exception occurs, the file is left behind for recovery.
         processing_file.unlink()
     except Exception as e:
-        print(f"[inbox] Drain error: {e}", file=sys.stderr)
+        print(f"[inbox] Drain error: {e}; processing file {processing_file.name} left for recovery", file=sys.stderr)
+        # Don't delete the file on error; let recovery sweep handle it next time
 
     return created