@matt82198/aesop 0.1.0 → 0.3.1

package/tools/stall_check.py

@@ -4,6 +4,7 @@ Automated silent-hang detection for agent transcripts.
 
 Usage:
   stall_check.py [--transcripts-root DIR] [--threshold-seconds SEC] [--json] [--exit-nonzero-on-stall]
+                 [--active-from DIR] [--emit-recovery] [--recovery-dir DIR]
 
 Options:
   --transcripts-root DIR       Root directory to scan for agent-*.jsonl transcripts.
@@ -12,11 +13,24 @@ Options:
                                Transcripts older than this are flagged as stalled.
   --json                       Output as JSON list of {agent_id, age_seconds, stalled, last_mtime}.
   --exit-nonzero-on-stall      Exit 1 if any agent is detected as stalled; default exit 0 always.
+  --active-from DIR            Optional. When set, an agent is ACTIVE only if a matching task/status
+                               file exists in DIR (named <agent_id>.task or <agent_id>.status).
+                               STALLED = stale mtime AND active. Default behavior (no flag):
+                               STALLED = stale mtime only.
+  --emit-recovery              When set, emit recovery advisory JSON for each STALLED agent.
+                               Advisory includes: agent, verdict, age_s, suggested_action (list).
+                               Output as JSON blocks (one per STALLED agent).
+  --recovery-dir DIR           Optional; only used with --emit-recovery. When set, write one
+                               recovery-<agent>.json file per STALLED agent to DIR (idempotent).
+                               No files written when none stalled.
 
 Behavior:
   - Walks transcripts-root for files matching agent-*.jsonl.
   - For each file, computes age = now - file mtime (seconds).
-  - Reports agents as stalled if age > threshold-seconds.
+  - Without --active-from: Reports agents as stalled if age > threshold-seconds (legacy).
+  - With --active-from: Reports agents as stalled if age > threshold-seconds AND active file exists.
+  - With --emit-recovery: Emits JSON advisory for each STALLED agent (to stdout).
+  - With --recovery-dir: Additionally writes recovery-<agent>.json files (idempotent, overwrite).
   - Default output: human-readable table; add --json for structured output.
   - Gracefully reports "no transcripts found" if root is missing or empty.
   - Exit code: 0 always (unless --exit-nonzero-on-stall specified and stalls detected).
@@ -27,9 +41,50 @@ import os
 import time
 import json
 import argparse
+import re
 from pathlib import Path
 
 
+def sanitize_agent_id(agent_id, filename):
+    """Validate and sanitize agent ID to prevent path traversal (CWE-22).
+
+    Args:
+        agent_id: Extracted agent ID from filename
+        filename: Original filename for warning message
+
+    Returns:
+        Sanitized agent_id if valid, None if invalid (caller should skip entry)
+    """
+    # Allowlist: only alphanumeric, underscore, dash
+    if not re.match(r"^[A-Za-z0-9_-]+$", agent_id):
+        # Log warning with filename only, never echo raw agent_id into a path
+        sys.stderr.write(f"Warning: Skipping transcript with invalid agent ID in file: {filename}\n")
+        return None
+    return agent_id
+
+
+def verify_path_containment(resolved_path, base_dir):
+    """Verify that a path is contained within a base directory (defense-in-depth).
+
+    Args:
+        resolved_path: Resolved absolute path to verify
+        base_dir: Base directory that path must be contained in
+
+    Returns:
+        True if path is safely contained, False if escape attempted
+    """
+    # Resolve BOTH sides: an unresolved 8.3 short-form candidate compared
+    # against a resolved long-form base raises ValueError and reads as an
+    # escape (windows-runner regression: stale+active reported ok).
+    resolved_base = Path(base_dir).resolve()
+    try:
+        Path(resolved_path).resolve().relative_to(resolved_base)
+        return True
+    except ValueError:
+        # Path is outside base_dir
+        return False
+
+
 def get_transcripts_root():
     """Resolve transcripts root from env var or default to ~/.claude/projects."""
     if os.environ.get("AESOP_TRANSCRIPTS_ROOT"):
@@ -38,10 +93,44 @@ def get_transcripts_root():
     return Path.home() / ".claude" / "projects"
 
 
-def scan_transcripts(transcripts_root, threshold_seconds):
+def is_agent_active(agent_id, active_from_dir):
+    """Check if an agent is active by looking for task/status files.
+
+    Args:
+        agent_id: Agent identifier (e.g., 'abc123') - must be pre-sanitized
+        active_from_dir: Directory to scan for <agent_id>.task or <agent_id>.status files
+
+    Returns:
+        True if any matching task/status file exists, False otherwise.
+    """
+    if not active_from_dir:
+        return None  # Flag not provided
+
+    active_from_path = Path(active_from_dir)
+    if not active_from_path.exists():
+        return False
+
+    # Check for <agent_id>.task or <agent_id>.status files with containment verification
+    for pattern in [f"{agent_id}.task", f"{agent_id}.status"]:
+        candidate_path = (active_from_path / pattern)
+        # Defense-in-depth: verify path is contained in active_from_path
+        if verify_path_containment(candidate_path, active_from_path):
+            if candidate_path.exists():
+                return True
+
+    return False
+
+
+def scan_transcripts(transcripts_root, threshold_seconds, active_from_dir=None):
     """Scan transcripts root for agent-*.jsonl files and compute staleness.
 
-    Returns: list of dicts {agent, transcript, mtime_age_s, verdict, suggested_action, last_mtime (ISO)}
+    Args:
+        transcripts_root: Root directory to scan
+        threshold_seconds: Staleness threshold in seconds
+        active_from_dir: Optional. When set, agent is ACTIVE only if task/status file exists.
+                        STALLED = stale mtime AND active. Default (None): STALLED = stale mtime only.
+
+    Returns: list of dicts {agent, transcript, mtime_age_s, verdict, suggested_action, last_mtime (ISO), active}
     """
     transcripts_root = Path(transcripts_root)
 
@@ -66,16 +155,35 @@ def scan_transcripts(transcripts_root, threshold_seconds):
         # Extract agent_id from filename (e.g., agent-abc123.jsonl -> abc123)
         agent_id = jsonl_file.stem.replace("agent-", "")
 
+        # Sanitize agent_id to prevent path traversal (CWE-22)
+        agent_id = sanitize_agent_id(agent_id, str(jsonl_file))
+        if agent_id is None:
+            # Invalid agent_id, skip this entry
+            continue
+
+        # Check active status if flag is provided
+        active = is_agent_active(agent_id, active_from_dir)
+
         # Determine verdict
         if age_seconds <= STALE_THRESHOLD:
             verdict = "ok"
             suggested_action = None
         elif age_seconds <= DEAD_THRESHOLD:
-            verdict = "stale"
-            suggested_action = "monitor for progress or investigate why transcript is stalled"
+            # If active_from_dir is set, only stale if also active
+            if active_from_dir is not None and not active:
+                verdict = "ok"
+                suggested_action = None
+            else:
+                verdict = "stale"
+                suggested_action = "monitor for progress or investigate why transcript is stalled"
         else:
-            verdict = "dead"
-            suggested_action = "investigate immediately; agent may be hung or crashed"
+            # If active_from_dir is set, only dead if also active
+            if active_from_dir is not None and not active:
+                verdict = "ok"
+                suggested_action = None
+            else:
+                verdict = "dead"
+                suggested_action = "investigate immediately; agent may be hung or crashed"
 
         results.append({
             "agent": agent_id,
@@ -84,11 +192,107 @@ def scan_transcripts(transcripts_root, threshold_seconds):
             "verdict": verdict,
             "suggested_action": suggested_action,
             "last_mtime": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(mtime)),
+            "active": active if active_from_dir is not None else None,
         })
 
     return results
 
 
+def emit_recovery_advisories(results):
+    """Emit recovery advisory JSON blocks for stalled agents.
+
+    Yields JSON strings (one per stalled agent) with advisory structure:
+    {
+        "agent": <agent_id>,
+        "verdict": <verdict>,
+        "age_s": <seconds>,
+        "suggested_action": [<ordered list of actions>]
+    }
+    """
+    if not results:
+        return
+
+    stalled_entries = [r for r in results if r["verdict"] in ("stale", "dead")]
+
+    for entry in stalled_entries:
+        # Build ordered list of suggested actions
+        actions = []
+
+        if entry["verdict"] == "stale":
+            actions.append("SendMessage resume with scope recap")
+            actions.append("TaskStop + relaunch from journal")
+            actions.append("inspect transcript tail")
+        elif entry["verdict"] == "dead":
+            actions.append("TaskStop immediately")
+            actions.append("inspect transcript for crash/error")
+            actions.append("relaunch from last known-good checkpoint")
+
+        advisory = {
+            "agent": entry["agent"],
+            "verdict": entry["verdict"],
+            "age_s": entry["mtime_age_s"],
+            "suggested_action": actions,
+        }
+
+        yield json.dumps(advisory)
+
+
+def write_recovery_files(results, recovery_dir):
+    """Write recovery-<agent>.json files for each stalled agent (idempotent).
+
+    Args:
+        results: List of scan results
+        recovery_dir: Directory to write recovery files to
+
+    Returns:
+        Count of files written
+    """
+    if not results or not recovery_dir:
+        return 0
+
+    recovery_path = Path(recovery_dir)
+    recovery_path.mkdir(parents=True, exist_ok=True)
+
+    files_written = 0
+    stalled_entries = [r for r in results if r["verdict"] in ("stale", "dead")]
+
+    for entry in stalled_entries:
+        # Build ordered list of suggested actions
+        actions = []
+
+        if entry["verdict"] == "stale":
+            actions.append("SendMessage resume with scope recap")
+            actions.append("TaskStop + relaunch from journal")
+            actions.append("inspect transcript tail")
+        elif entry["verdict"] == "dead":
+            actions.append("TaskStop immediately")
+            actions.append("inspect transcript for crash/error")
+            actions.append("relaunch from last known-good checkpoint")
+
+        advisory = {
+            "agent": entry["agent"],
+            "verdict": entry["verdict"],
+            "age_s": entry["mtime_age_s"],
+            "suggested_action": actions,
+        }
+
+        recovery_file = recovery_path / f"recovery-{entry['agent']}.json"
+
+        # Defense-in-depth: verify recovery_file is contained in recovery_path
+        if not verify_path_containment(recovery_file, recovery_path):
+            sys.stderr.write(f"Warning: Recovery file path escape detected, skipping: {entry['agent']}\n")
+            continue
+
+        try:
+            recovery_file.write_text(json.dumps(advisory, indent=2), encoding='utf-8')
+            files_written += 1
+        except Exception as e:
+            # Fail-open: log error but continue
+            sys.stderr.write(f"Warning: Failed to write {recovery_file}: {e}\n")
+
+    return files_written
+
+
 def print_human_table(results):
     """Print results as a human-readable table."""
     if not results:
@@ -140,6 +344,21 @@ def main():
         action="store_true",
         help="Exit 1 if any agent is stalled (default: always exit 0)",
     )
+    parser.add_argument(
+        "--active-from",
+        default=None,
+        help="Optional. Directory to scan for task/status files. Agent is ACTIVE only if file exists.",
+    )
+    parser.add_argument(
+        "--emit-recovery",
+        action="store_true",
+        help="Emit recovery advisory JSON blocks to stdout for each STALLED agent",
+    )
+    parser.add_argument(
+        "--recovery-dir",
+        default=None,
+        help="Optional; only used with --emit-recovery. Write recovery-<agent>.json files to this directory",
+    )
 
     args = parser.parse_args()
 
@@ -147,16 +366,28 @@ def main():
     transcripts_root = args.transcripts_root if args.transcripts_root else get_transcripts_root()
 
     # Scan transcripts
-    results = scan_transcripts(transcripts_root, args.threshold_seconds)
-
-    # Output
-    if args.json:
-        print_json_output(results)
-    else:
-        if results is None:
-            print("no transcripts found")
+    results = scan_transcripts(transcripts_root, args.threshold_seconds, args.active_from)
+
+    # Emit recovery advisories if requested
+    if args.emit_recovery and results:
+        for advisory_json in emit_recovery_advisories(results):
+            print(advisory_json)
+
+    # Write recovery files if requested
+    if args.emit_recovery and args.recovery_dir and results:
+        write_recovery_files(results, args.recovery_dir)
+
+    # Output (human-readable or JSON)
+    # Note: if --emit-recovery was used, recovery advisories already printed above
+    if not args.emit_recovery:
+        # Only print human-readable/JSON if we're not emitting recovery advisories
+        if args.json:
+            print_json_output(results)
         else:
-            print_human_table(results)
+            if results is None:
+                print("no transcripts found")
+            else:
+                print_human_table(results)
 
     # Determine exit code
     exit_code = 0

package/tools/stateapi_lint.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""
+tools.stateapi_lint — Scanner for direct state file opens outside the API.
+
+Detects violations of the "reads go through state_store.read_api" rule by scanning
+ui/ and tools/ for direct opens of state files (tracker.json, orchestrator-status.json,
+heartbeat files, OUTCOMES-LEDGER.md) outside the read_api module.
+
+Writers (state_store/export.py, state_store/ingest.py, etc.) are allowlisted.
+
+RATCHET MODE (hardening):
+  Baseline is keyed by file + pattern-id (NOT line numbers).
+  Without --update-baseline flag:
+    - FAILS if baseline contains entries absent from current scan (stale baseline)
+    - FAILS if current violations missing from baseline (new violations)
+    - PASS only if: current violations exactly match baseline entries
+  With --update-baseline flag:
+    - Allows regenerating the baseline (sets current as new baseline)
+
+  CI MUST NEVER pass --update-baseline (hand-edits of baseline detected & fail).
+
+Exit codes:
+  0 = all checks pass
+  1 = violations detected or baseline mismatch
+  2 = error
+
+Usage:
+  python tools/stateapi_lint.py [--root REPO_ROOT] [--json] [--update-baseline]
+
+Options:
+  --root REPO_ROOT: Repository root (default: cwd)
+  --json: Output JSON instead of text
+  --update-baseline: Regenerate baseline from current violations (CI must never use)
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# State files that should only be read via the API
+STATE_FILES_TO_PROTECT = [
+    "tracker.json",
+    "orchestrator-status.json",
+    "OUTCOMES-LEDGER.md",
+    ".watchdog-heartbeat",
+    ".monitor-heartbeat",
+    ".orchestrator-heartbeat",
+]
+
+# File patterns that are WRITERS and allowed to access state files directly
+WRITER_ALLOWLIST = [
+    "state_store/export.py",
+    "state_store/ingest.py",
+    "state_store/read_api.py",  # The read API facade itself (reads the state files)
+    "state_store/write_api.py",  # The write API facade (reads/writes the projection atomically)
+    "ui/collectors.py",  # Some readers also export/flush
+    "tools/cost.py",  # Parses ledger
+]
+
+# Directories to scan for violations
+SCAN_DIRS = ["ui", "tools", "state_store"]  # Include state_store to catch internal issues
+
+
+def find_direct_opens(repo_root):
+    """Scan repo for direct opens of protected state files outside the API.
+
+    Returns violations keyed by file + pattern-id (not line numbers).
+    Pattern-id is the matched pattern index, making the key stable across line edits.
+
+    Args:
+        repo_root: Path to repository root
+
+    Returns:
+        list: List of violation keys (file@pattern-id format)
+    """
+    repo_root = Path(repo_root)
+    violations = []
+
+    # Pattern to detect file opens: Path(...).read_text(), open(...), json.load(open(...)), etc.
+    # Each pattern gets an ID for stable keying across line number changes
+    read_patterns = [
+        (r'["\']tracker\.json["\']', "tracker-json"),
+        (r'["\']orchestrator-status\.json["\']', "status-json"),
+        (r'["\']OUTCOMES-LEDGER\.md["\']', "ledger-md"),
+        (r'["\']\.watchdog-heartbeat["\']', "watchdog-hb"),
+        (r'["\']\.monitor-heartbeat["\']', "monitor-hb"),
+        (r'["\']\.orchestrator-heartbeat["\']', "orchestrator-hb"),
+        (r'state\s*/\s*tracker\.json', "state-tracker-json"),
+        (r'state\s*/\s*orchestrator-status', "state-status-json"),
+        (r'state\s*/\s*.*heartbeat', "state-heartbeat"),
+    ]
+
+    for scan_dir in SCAN_DIRS:
+        scan_path = repo_root / scan_dir
+        if not scan_path.exists():
+            continue
+
+        for py_file in scan_path.rglob("*.py"):
+            # Check if this file is in the allowlist
+            relative_path = py_file.relative_to(repo_root)
+            is_allowed = any(
+                str(relative_path).replace("\\", "/") == allow.replace("\\", "/")
+                for allow in WRITER_ALLOWLIST
+            )
+
+            if is_allowed:
+                continue
+
+            try:
+                content = py_file.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                continue
+
+            # Skip if file imports read_api (it's using the facade correctly)
+            if "from state_store.read_api import" in content or "import state_store.read_api" in content:
+                continue
+
+            # Scan for violations
+            for line_num, line in enumerate(content.split("\n"), 1):
+                for pattern, pattern_id in read_patterns:
+                    if re.search(pattern, line):
+                        # Additional filter: skip comment lines and string literals in docstrings
+                        if line.strip().startswith("#"):
+                            continue
+                        if '"""' in line or "'''" in line:
+                            continue
+
+                        # Key is file@pattern-id (stable across line edits)
+                        # Use posix separators for cross-platform consistency
+                        violation_key = f"{relative_path.as_posix()}@{pattern_id}"
+                        if violation_key not in violations:
+                            violations.append(violation_key)
+                        break  # Only report once per line per file
+
+    return sorted(violations)
+
+
+def save_baseline(baseline_file, data):
+    """Save violations baseline to JSON file.
+
+    Args:
+        baseline_file: Path to baseline file
+        data: dict with "violations" list
+    """
+    baseline_file = Path(baseline_file)
+    baseline_file.parent.mkdir(parents=True, exist_ok=True)
+    baseline_file.write_text(json.dumps(data, indent=2))
+
+
+def load_baseline(baseline_file):
+    """Load violations baseline from JSON file.
+
+    Returns:
+        dict with "violations" list, or empty dict if file missing.
+    """
+    baseline_file = Path(baseline_file)
+    if not baseline_file.exists():
+        return {"violations": []}
+
+    try:
+        return json.loads(baseline_file.read_text())
+    except Exception:
+        return {"violations": []}
+
+
+def normalize_key(key):
+    """Normalize violation keys to forward-slash separators for cross-platform consistency.
+
+    Converts backslash separators (legacy Windows baseline entries) to forward slashes.
+
+    Args:
+        key: Violation key string
+
+    Returns:
+        str: Key with forward-slash separators
+    """
+    return key.replace("\\", "/")
+
+
+def check_ratchet(baseline_violations, current_violations):
+    """Check ratchet: baseline and current must match exactly.
+
+    Fails if:
+      1. Baseline contains entries absent from current (stale baseline)
+      2. Current violations missing from baseline (new violations)
+
+    Only passes if current violations exactly match baseline (bidirectional check).
+    Normalizes both sets to forward-slash separators for cross-platform consistency.
+
+    Args:
+        baseline_violations: list of violation keys from baseline
+        current_violations: list of violation keys from current scan
+
+    Returns:
+        tuple: (is_ok, stale_entries, new_violations)
+          is_ok (bool): True only if baseline == current
+          stale_entries (list): Entries in baseline not in current
+          new_violations (list): Entries in current not in baseline
+    """
+    # Normalize both to forward slashes for comparison
+    baseline_set = set(normalize_key(v) for v in baseline_violations)
+    current_set = set(normalize_key(v) for v in current_violations)
+
+    stale = list(baseline_set - current_set)
+    new = list(current_set - baseline_set)
+
+    is_ok = (len(stale) == 0 and len(new) == 0)
+    return is_ok, sorted(stale), sorted(new)
+
+
+def main(argv=None):
+    """CLI entry point."""
+    argv = sys.argv[1:] if argv is None else argv
+
+    repo_root = None
+    output_format = "text"
+    baseline_file = None
+    update_baseline = False
+
+    # Parse arguments
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--root":
+            i += 1
+            if i < len(argv):
+                repo_root = argv[i]
+            i += 1
+        elif arg.startswith("--root="):
+            repo_root = arg[len("--root="):]
+            i += 1
+        elif arg == "--json":
+            output_format = "json"
+            i += 1
+        elif arg == "--baseline":
+            i += 1
+            if i < len(argv):
+                baseline_file = argv[i]
+            i += 1
+        elif arg == "--update-baseline":
+            update_baseline = True
+            i += 1
+        else:
+            print(f"Unknown argument: {arg}", file=sys.stderr)
+            return 2
+
+    if repo_root is None:
+        repo_root = Path.cwd()
+    else:
+        repo_root = Path(repo_root)
+
+    if baseline_file is None:
+        baseline_file = repo_root / ".stateapi-baseline.json"
+
+    # Scan for violations
+    violations = find_direct_opens(str(repo_root))
+
+    # Load baseline
+    baseline_data = load_baseline(str(baseline_file))
+    baseline_violations = baseline_data.get("violations", [])
+
+    # If --update-baseline, save current as baseline and exit
+    if update_baseline:
+        save_baseline(baseline_file, {"violations": violations})
+        if output_format == "json":
+            print(json.dumps({"ok": True, "message": "Baseline updated", "count": len(violations)}, indent=2))
+        else:
+            print(f"Baseline updated: {len(violations)} violation(s) recorded")
+        return 0
+
+    # Check ratchet: baseline must match current exactly
+    is_ok, stale_entries, new_violations = check_ratchet(baseline_violations, violations)
+
+    if output_format == "json":
+        result = {
+            "ok": is_ok,
+            "violations": violations,
+            "baseline_count": len(baseline_violations),
+            "current_count": len(violations),
+            "stale_entries": stale_entries,
+            "new_violations": new_violations,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        # Text format
+        print(f"State API lint: {len(violations)} violation(s) found")
+        if baseline_violations:
+            print(f"  (baseline: {len(baseline_violations)})")
+
+        if violations:
+            for v in sorted(violations):
+                print(f"  {v}")
+
+        # Report stale entries (in baseline but not current)
+        if stale_entries:
+            print(f"\nSTALE baseline entries ({len(stale_entries)}) — hand-edited or fixed?:")
+            for v in stale_entries:
+                print(f"  {v}")
+
+        # Report new violations (in current but not baseline)
+        if new_violations:
+            print(f"\nNEW violations ({len(new_violations)}):")
+            for v in new_violations:
+                print(f"  {v}")
+
+        # Final verdict
+        if is_ok:
+            if violations:
+                print(f"\nPASS: All {len(violations)} violations match baseline")
+            else:
+                print("\nPASS: No violations")
+            return 0
+        else:
+            if stale_entries and new_violations:
+                print(f"\nFAIL: {len(stale_entries)} stale + {len(new_violations)} new violation(s)")
+            elif stale_entries:
+                print(f"\nFAIL: {len(stale_entries)} stale baseline entries (hand-edited?)")
+            else:
+                print(f"\nFAIL: {len(new_violations)} new violation(s) detected")
+            return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())