@matt82198/aesop 0.1.0 → 0.2.0

package/tools/secret_scan.py

@@ -8,7 +8,7 @@ Modes:
   secret_scan.py --history [--repo PATH]             Scan all blobs in git history
   secret_scan.py PATH [PATH...]                      Scan files/dirs directly (recurse dirs)
 
-Exit codes: 0=clean, 1=findings, 2=usage error
+Exit codes: 0=clean, 1=findings, 2=error (file unreadable/git failure/scan error)
 Output: one line per finding or summary (never prints full secrets)
 
 Pragma escape hatch (STRICTLY SCOPED to doc-shaped rules):
@@ -145,6 +145,12 @@ class GitScanError(Exception):
     printed CLEAN and exited 0 on an unresolvable range)."""
 
 
+class ScanError(Exception):
+    """Raised when a file cannot be scanned due to read/permission/OS errors.
+    Callers MUST treat this as fail-CLOSED (block / exit 2) -- a file the
+    scanner cannot read must block the push, not sail through as CLEAN."""
+
+
 def has_pragma(filepath):
     """Check if file has 'secretscan: allow-pattern-docs' pragma in first 10 lines."""
     try:
@@ -230,6 +236,9 @@ def scan_file(filepath):
     Large files (>1MB) and binary files are scanned for FATAL_RULES patterns:
     - Large files: scan first 1MB; emit SKIPPED-LARGE to stderr if file is larger
     - Binary files: decode as latin-1; emit SKIPPED-BINARY to stderr if not fully scanned
+
+    Raises ScanError if file cannot be read (permission denied, vanished, etc.)
+    to fail CLOSED rather than reporting the file clean.
     """
     SIZE_THRESHOLD = 1024 * 1024  # 1MB
     MAX_READ_SIZE = 2 * 1024 * 1024  # 2MB max to read
@@ -240,6 +249,7 @@ def scan_file(filepath):
         return findings
 
     # Check for pragma (applies only to specific rule-based findings, not filename findings)
+    # has_pragma() already swallows its own exceptions, so safe to call
     has_file_pragma = has_pragma(filepath)
 
     # Check if filename matches credential patterns (always fatal, pragma does NOT apply)
@@ -251,13 +261,21 @@ def scan_file(filepath):
             )
             break
 
+    # File stat and type detection — not wrapped in try/except so errors propagate
     try:
-        # Check file size and binary status
         stat = filepath.stat()
         file_size = stat.st_size
+    except (OSError, PermissionError, FileNotFoundError) as e:
+        raise ScanError(f"Cannot stat {filepath}: {e}")
+
+    try:
         is_binary = is_binary_file(filepath)
-        is_large = file_size > SIZE_THRESHOLD
+    except (OSError, PermissionError, FileNotFoundError) as e:
+        raise ScanError(f"Cannot check if binary {filepath}: {e}")
+
+    is_large = file_size > SIZE_THRESHOLD
 
+    try:
         if is_binary:
             # Binary file (any size): scan as-is for FATAL_RULES only
             with open(filepath, "rb") as f:
@@ -289,31 +307,26 @@ def scan_file(filepath):
             # Large text file: scan entire file in chunks for all rules
             print(f"SKIPPED-LARGE {filepath} (scanned in chunks)", file=sys.stderr)
             line_num = 0
-            try:
-                with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
-                    # Read in 1MB chunks to avoid loading entire large file into memory
-                    for chunk in iter(lambda: f.read(1024 * 1024), ""):
-                        for chunk_line in chunk.split("\n"):
-                            line_num += 1
-                            for rule_name, (pattern, flags) in PATTERNS.items():
-                                # Skip env_assignment rule if not an .env-like file
-                                if rule_name == "env_assignment" and not is_env_file(filepath):
-                                    continue
+            with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                # Read in 1MB chunks to avoid loading entire large file into memory
+                for chunk in iter(lambda: f.read(1024 * 1024), ""):
+                    for chunk_line in chunk.split("\n"):
+                        line_num += 1
+                        for rule_name, (pattern, flags) in PATTERNS.items():
+                            # Skip env_assignment rule if not an .env-like file
+                            if rule_name == "env_assignment" and not is_env_file(filepath):
+                                continue
 
-                                matches = re.finditer(pattern, chunk_line, flags)
-                                for match in matches:
-                                    match_str = match.group(0)
+                            matches = re.finditer(pattern, chunk_line, flags)
+                            for match in matches:
+                                match_str = match.group(0)
 
-                                    # Skip if it's a placeholder
-                                    if is_placeholder(match_str):
-                                        continue
+                                # Skip if it's a placeholder
+                                if is_placeholder(match_str):
+                                    continue
 
-                                    is_fatal = _classify_finding(rule_name, has_file_pragma)
-                                    findings.append((line_num, rule_name, match_str, is_fatal))
-            except (IOError, OSError) as e:
-                # FAIL CLOSED: if we cannot fully scan a large text file, exit with error
-                print(f"FATAL: Cannot fully scan large text file {filepath}: {e}", file=sys.stderr)
-                sys.exit(1)
+                                is_fatal = _classify_finding(rule_name, has_file_pragma)
+                                findings.append((line_num, rule_name, match_str, is_fatal))
 
         else:
             # Normal small text file: scan all rules
@@ -335,8 +348,9 @@ def scan_file(filepath):
                             is_fatal = _classify_finding(rule_name, has_file_pragma)
                             findings.append((line_num, rule_name, match_str, is_fatal))
 
-    except Exception:
-        pass
+    except (OSError, PermissionError, FileNotFoundError, IOError) as e:
+        # FAIL CLOSED: if file cannot be read, raise error (not return clean)
+        raise ScanError(f"Cannot scan file {filepath}: {e}")
 
     return findings
 
@@ -528,7 +542,11 @@ def get_range_files(repo_path, commit_range):
 
 
 def get_history_files(repo_path):
-    """Get all file contents from git history via git log -p."""
+    """Get all file contents from git history via git log -p.
+
+    Raises GitScanError if git log fails (corrupt repo, git crash, etc.).
+    This mirrors get_range_files() and get_staged_files() which already
+    fail closed on git errors."""
     files_content = []
     try:
         # Use git log -p to get full diff history
@@ -539,38 +557,96 @@ def get_history_files(repo_path):
             text=True,
             timeout=60,
         )
-        if result.returncode == 0:
-            # Parse the git log output: each file appears as +++ b/path/to/file followed by its content
-            current_file = None
-            current_content = []
-            for line in result.stdout.split("\n"):
-                if line.startswith("+++ b/"):
-                    if current_file and current_content:
-                        files_content.append((current_file, "\n".join(current_content)))
-                    current_file = line[6:]  # Remove "+++ b/"
-                    current_content = []
-                elif current_file and line.startswith("+") and not line.startswith("+++"):
-                    # Content line (added), strip the leading +
-                    current_content.append(line[1:])
-                elif current_file and line.startswith(" "):
-                    # Context line, keep it as-is (strip leading space)
-                    current_content.append(line[1:])
+    except Exception as e:
+        raise GitScanError(f"git log raised {e!r}")
+
+    if result.returncode != 0:
+        raise GitScanError(
+            f"git log failed (rc={result.returncode}): {result.stderr.strip()}"
+        )
+
+    # Parse the git log output: each file appears as +++ b/path/to/file followed by its content
+    current_file = None
+    current_content = []
+    for line in result.stdout.split("\n"):
+        if line.startswith("+++ b/"):
             if current_file and current_content:
                 files_content.append((current_file, "\n".join(current_content)))
-    except Exception:
-        pass
+            current_file = line[6:]  # Remove "+++ b/"
+            current_content = []
+        elif current_file and line.startswith("+") and not line.startswith("+++"):
+            # Content line (added), strip the leading +
+            current_content.append(line[1:])
+        elif current_file and line.startswith(" "):
+            # Context line, keep it as-is (strip leading space)
+            current_content.append(line[1:])
+    if current_file and current_content:
+        files_content.append((current_file, "\n".join(current_content)))
+
     return files_content
 
 
+def _git_committable_set(dir_path):
+    """Return the set of resolved absolute paths that git tracks or would
+    consider committable (tracked + untracked-but-not-ignored) for the repo
+    containing `dir_path`, or None if dir_path is not inside a git work tree
+    or git is unavailable/errors.
+
+    Built from `git ls-files --cached --others --exclude-standard`, which lists
+    exactly the tracked files plus untracked files that are NOT git-ignored.
+    A tracked file is ALWAYS included (even a force-added one that matches an
+    ignore rule), so filtering by this set never skips a committable file --
+    only ephemeral, git-ignored runtime files (which can never be pushed and
+    therefore can't leak a secret through git) are excluded.
+    """
+    try:
+        top = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=str(dir_path), capture_output=True, text=True, timeout=10,
+        )
+        if top.returncode != 0:
+            return None
+        toplevel = Path(top.stdout.strip())
+        listing = subprocess.run(
+            ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+            cwd=str(toplevel), capture_output=True, text=True, timeout=60,
+        )
+        if listing.returncode != 0:
+            return None
+    except Exception:
+        return None
+
+    committable = set()
+    for rel in listing.stdout.split("\0"):
+        if rel:
+            committable.add((toplevel / rel).resolve())
+    return committable
+
+
 def scan_paths(paths):
-    """Recursively scan paths (files and directories)."""
+    """Recursively scan paths (files and directories).
+
+    For a DIRECTORY argument inside a git work tree, git-ignored files are
+    skipped: a full-tree scan (e.g. CI's `secret_scan.py .`) must not flag
+    ephemeral, git-ignored runtime files -- such as state/.ui-session-token --
+    that can never be committed or pushed and therefore cannot leak a secret
+    through git. Filtering uses the tracked+untracked-not-ignored set from
+    `git ls-files`, so a committable file is never skipped. When a directory is
+    not inside a git repo (or git errors), NO filtering is applied and every
+    file is walked (fail OPEN toward more scanning, never less). Explicitly
+    named FILE arguments are always scanned, even if git-ignored.
+    """
     files_to_scan = []
     for path_str in paths:
         path = Path(path_str).resolve()
         if path.is_file():
             files_to_scan.append(path)
         elif path.is_dir():
-            files_to_scan.extend(path.rglob("*"))
+            candidates = [p for p in path.rglob("*") if p.is_file()]
+            committable = _git_committable_set(path)
+            if committable is not None:
+                candidates = [p for p in candidates if p.resolve() in committable]
+            files_to_scan.extend(candidates)
     return [p for p in files_to_scan if p.is_file()]
 
 
@@ -690,7 +766,13 @@ def main():
     elif args.history:
         # History scanning mode: unaffected by the blob-scan fix above, since
         # it already walks committed diff content via `git log -p`.
-        history_files = get_history_files(args.repo)
+        try:
+            history_files = get_history_files(args.repo)
+        except GitScanError as e:
+            print(f"FATAL: could not scan git history: {e}", file=sys.stderr)
+            print("Failing CLOSED: refusing to report CLEAN when git history cannot be read.", file=sys.stderr)
+            sys.exit(2)
+
         file_count = len(set(f for f, _ in history_files))
         for filepath, content in history_files:
             findings = scan_content(content)
@@ -703,7 +785,12 @@ def main():
         files = scan_paths(args.paths)
         file_count = len(files)
         for filepath in files:
-            findings = scan_file(filepath)
+            try:
+                findings = scan_file(filepath)
+            except ScanError as e:
+                print(f"FATAL: cannot scan file {filepath}: {e}", file=sys.stderr)
+                print("Failing CLOSED: refusing to report CLEAN when a file cannot be read.", file=sys.stderr)
+                sys.exit(2)
             for line_num, rule, match_str, is_fatal in findings:
                 all_findings.append((filepath, line_num, rule, match_str, is_fatal))
                 if is_fatal:

package/tools/self_stats.py

@@ -502,6 +502,26 @@ class StatsCounter:
         data = json.loads(self.json())
         data["generated_at"] = datetime.now(timezone.utc).isoformat()
         data["loc"] = self.git.lines_of_code
+
+        # Add cost economics metrics (requires cost_econ module)
+        try:
+            from cost_econ import calculate_economics, get_metric_honesty_caveats
+            # Infer state directory from repo root or config
+            repo_path = Path(self.git.repo_root)
+            state_dir = repo_path / "state"
+
+            economics = calculate_economics(
+                repo_root=str(repo_path),
+                state_dir=str(state_dir) if state_dir.exists() else None,
+                config_file=None
+            )
+
+            data["economics"] = economics
+            data["economics_caveats"] = get_metric_honesty_caveats()
+        except Exception:
+            # Graceful fallback: if cost_econ unavailable, skip economics metrics
+            pass
+
         return data
 
     def save_stats(self, output_file: str = "stats.json") -> None:

package/tools/transcript_digest.py

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""
+transcript_digest.py — Digest agent transcripts into compact briefs.
+
+Reads agent-*.jsonl transcripts from a session subagents directory and appends
+compact ~200-byte per-agent briefs to state/ledger/transcripts-brief.jsonl.
+
+Usage:
+  python -m tools.transcript_digest --transcripts-dir /path/to/session/subagents \
+    --wave rc.6 [--state-root /path/to/state]
+
+Briefs include: agent label, files touched, tool-call count, pass/fail outcome,
+token count, and a 1-2 sentence summary. Aggressive redaction removes absolute
+paths, usernames, emails, tokens, and repo names.
+
+Deterministic + idempotent (skips agents already in the ledger).
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+
+# Redaction patterns (derived from secret_scan.py)
+REDACTION_PATTERNS = {  # secretscan: allow-pattern-docs
+    "pem_private_key": (r"-----BEGIN .* PRIVATE " r"KEY-----.*?-----END .* PRIVATE " r"KEY-----", re.DOTALL | re.IGNORECASE),
+    "aws_access_key": (r"AKIA[0-9A-Z]{16}", 0),
+    "aws_secret_pattern": (r"aws[_-]?secret[_-]?access[_-]?key\s*[:=]\s*[^\s\$\<\{]", re.IGNORECASE),
+    "github_token": (r"(ghp_|gho_|ghu_|ghs_|ghr_|github_pat_)[A-Za-z0-9_]{20,}", 0),
+    "slack_token": (r"xox[baprs]-[A-Za-z0-9-]{10,}", 0),
+    "openai_anthropic_key": (r"sk-[A-Za-z0-9_\-]{20,}", 0),
+    "connection_string": (r"://[^:]+:[^@/\s]+@(?!localhost|127\.|example|test)[^\s]+", 0),
+}
+
+# Patterns to redact by category
+EMAIL_PATTERN = r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"
+# Windows path: C:\ or POSIX path: /
+PATH_PATTERN = r"[A-Za-z]:\\[^\\/:*<>|]*|/[^/:*<>|]*"
+REPO_NAME_PATTERN = r"\b(?:aesop|conductor3|tr-sample-tracker|ecm-ai|TR-Automation-Scripts)\b"
+USERNAME_PATTERN = r"\b(?:matt8|matt82198|John|Jack|Doe)\b"
+
+
+def redact_text(text: str) -> str:
+    """Aggressively redact secrets, paths, emails, usernames, and repo names."""
+    if not text:
+        return text
+
+    # Redact keys and credentials
+    for pattern, flags in REDACTION_PATTERNS.values():
+        text = re.sub(pattern, "[REDACTED]", text, flags=flags)
+
+    # Redact emails
+    text = re.sub(EMAIL_PATTERN, "[EMAIL]", text, flags=re.IGNORECASE)
+
+    # Redact absolute paths (Windows and POSIX)
+    text = re.sub(PATH_PATTERN, "[PATH]", text)
+
+    # Redact repo names
+    text = re.sub(REPO_NAME_PATTERN, "[REPO]", text, flags=re.IGNORECASE)
+
+    # Redact usernames
+    text = re.sub(USERNAME_PATTERN, "[USER]", text, flags=re.IGNORECASE)
+
+    return text
+
+
+def infer_outcome(messages: List[Dict], errors: List[Dict]) -> str:
+    """Infer outcome from transcript structure: completed|stalled|failed|timeout."""
+    # Check for explicit timeout markers first
+    if errors:
+        if any("timeout" in e.get("message", "").lower() for e in errors):
+            return "timeout"
+        return "stalled"
+
+    if not messages:
+        return "failed"
+
+    last_msg = messages[-1] if isinstance(messages, list) else {}
+    msg_type = last_msg.get("type", "")
+
+    # If last message is a tool result with error, mark as stalled
+    if msg_type == "tool_result" and "error" in last_msg:
+        return "stalled"
+
+    # Default to completed
+    return "completed"
+
+
+def extract_files_from_calls(messages: List[Dict]) -> Tuple[Set[str], Set[str]]:
+    """Extract created and modified file paths from tool calls."""
+    created = set()
+    modified = set()
+
+    if not isinstance(messages, list):
+        return created, modified
+
+    for msg in messages:
+        if msg.get("type") == "tool_result" or "content" in msg:
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                # Look for Write, Edit, Read operations in logs
+                if "Write" in content or "write" in content:
+                    # Heuristic: files mentioned after write ops are likely created
+                    matches = re.findall(r"(?:Write|write|created?|added?)\s+(?:to\s+)?['\"]?([^\s'\"]+\.(?:py|js|md|json|sh))", content)
+                    created.update(matches)
+                if "Edit" in content or "edit" in content or "modified?" in content:
+                    matches = re.findall(r"(?:Edit|edit|modified?|updated?)\s+(?:file\s+)?['\"]?([^\s'\"]+\.(?:py|js|md|json|sh))", content)
+                    modified.update(matches)
+
+    # Redact file paths
+    created = {redact_text(f) for f in created}
+    modified = {redact_text(f) for f in modified}
+
+    return created, modified
+
+
+def extract_tool_calls(messages: List[Dict]) -> Tuple[List[str], int]:
+    """Extract tool call types and count."""
+    tools = {}
+
+    if not isinstance(messages, list):
+        return [], 0
+
+    for msg in messages:
+        if msg.get("type") == "tool_use":
+            tool_name = msg.get("name", "Unknown")
+            tools[tool_name] = tools.get(tool_name, 0) + 1
+
+    # Sort by frequency, take top 3
+    top_tools = sorted(tools.keys(), key=lambda t: tools[t], reverse=True)[:3]
+    total_calls = sum(tools.values())
+
+    return top_tools, total_calls
+
+
+def extract_errors(messages: List[Dict]) -> List[Dict]:
+    """Extract error messages with timestamps."""
+    errors = []
+
+    if not isinstance(messages, list):
+        return errors
+
+    for i, msg in enumerate(messages):
+        if msg.get("type") == "tool_result" and msg.get("is_error"):
+            error_msg = msg.get("content", "Unknown error")
+            # Redact sensitive data from error messages
+            error_msg = redact_text(error_msg)
+            # Truncate to ~100 chars
+            error_msg = error_msg[:100]
+            errors.append({
+                "tool": msg.get("name", "Unknown"),
+                "at_sec": i * 5,  # Rough estimate: ~5 sec per message
+                "message": error_msg
+            })
+
+    return errors[:3]  # Keep top 3 errors
+
+
+def extract_token_usage(metadata: Dict) -> Dict:
+    """Extract token usage from metadata."""
+    usage = metadata.get("usage", {})
+    return {
+        "input": usage.get("input_tokens", 0),
+        "output": usage.get("output_tokens", 0),
+        "model": metadata.get("model", "haiku")
+    }
+
+
+def generate_brief(
+    messages: List[Dict],
+    tool_calls: List[str],
+    files_created: Set[str],
+    files_modified: Set[str],
+    errors: List[Dict]
+) -> str:
+    """Generate a 1-2 sentence summary of the transcript."""
+    parts = []
+
+    if tool_calls:
+        parts.append(f"Used {len(tool_calls)} tool types ({', '.join(tool_calls[:2])})")
+
+    total_files = len(files_created) + len(files_modified)
+    if total_files > 0:
+        parts.append(f"modified {total_files} file(s)")
+
+    if errors:
+        parts.append(f"encountered {len(errors)} error(s)")
+    else:
+        parts.append("completed without errors")
+
+    brief = "; ".join(parts) + "."
+
+    # Truncate to ~150 chars max
+    if len(brief) > 150:
+        brief = brief[:147] + "..."
+
+    return brief
+
+
+def stream_jsonl_transcripts(transcripts_dir: Path) -> Dict[str, Tuple[Dict, List]]:
+    """Stream parse all agent-*.jsonl files in directory."""
+    agents = {}
+
+    if not transcripts_dir.exists():
+        return agents
+
+    for jsonl_file in sorted(transcripts_dir.glob("agent-*.jsonl")):
+        agent_id = jsonl_file.stem.replace("agent-", "")
+        messages = []
+        metadata = {}
+
+        try:
+            with open(jsonl_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        obj = json.loads(line)
+                        if obj.get("type") == "metadata":
+                            metadata = obj
+                        else:
+                            messages.append(obj)
+                    except json.JSONDecodeError:
+                        continue
+        except Exception:
+            continue
+
+        if messages or metadata:
+            agents[agent_id] = (metadata, messages)
+
+    return agents
+
+
+def create_brief(
+    wave: str,
+    agent_id: str,
+    metadata: Dict,
+    messages: List[Dict]
+) -> Dict:
+    """Create a brief dict from transcript data."""
+    start_time = metadata.get("start_time", datetime.now(timezone.utc).isoformat())
+    end_time = metadata.get("end_time", datetime.now(timezone.utc).isoformat())
+
+    # Parse timestamps to compute duration
+    try:
+        start = datetime.fromisoformat(start_time.replace("Z", "+00:00"))
+        end = datetime.fromisoformat(end_time.replace("Z", "+00:00"))
+        duration_sec = int((end - start).total_seconds())
+    except Exception:
+        duration_sec = 0
+
+    tool_calls, tool_count = extract_tool_calls(messages)
+    files_created, files_modified = extract_files_from_calls(messages)
+    errors = extract_errors(messages)
+    outcome = infer_outcome(messages, errors)
+    token_usage = extract_token_usage(metadata)
+    brief_text = generate_brief(messages, tool_calls, files_created, files_modified, errors)
+
+    return {
+        "wave": wave,
+        "agent_id": agent_id,
+        "start_time": start_time,
+        "end_time": end_time,
+        "duration_sec": duration_sec,
+        "outcome": outcome,
+        "top_tool_calls": tool_calls,
+        "files_created": sorted(list(files_created)),
+        "files_modified": sorted(list(files_modified)),
+        "errors": errors,
+        "token_usage": token_usage,
+        "brief": brief_text,
+        "brief_schema_version": 1
+    }
+
+
+def get_existing_agent_ids(ledger_path: Path) -> Set[str]:
+    """Read already-digested agent IDs from ledger."""
+    agent_ids = set()
+
+    if not ledger_path.exists():
+        return agent_ids
+
+    try:
+        with open(ledger_path, "r", encoding="utf-8") as f:
+            for line in f:
+                if not line.strip():
+                    continue
+                try:
+                    obj = json.loads(line)
+                    agent_ids.add(obj.get("agent_id", ""))
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    return agent_ids
+
+
+def append_briefs(ledger_path: Path, briefs: List[Dict]) -> int:
+    """Append briefs to ledger file (create parent dir if needed)."""
+    if not briefs:
+        return 0
+
+    # Ensure parent directory exists
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Append briefs
+    try:
+        with open(ledger_path, "a", encoding="utf-8") as f:
+            for brief in briefs:
+                f.write(json.dumps(brief) + "\n")
+        return len(briefs)
+    except Exception:
+        return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        "--transcripts-dir",
+        type=Path,
+        required=True,
+        help="Directory containing agent-*.jsonl files"
+    )
+    parser.add_argument(
+        "--wave",
+        default="unknown",
+        help="Wave ID for the briefs (default: unknown)"
+    )
+    parser.add_argument(
+        "--state-root",
+        type=Path,
+        default=Path(os.environ.get("AESOP_STATE_ROOT", "./state")),
+        help="State directory root (default: $AESOP_STATE_ROOT or ./state)"
+    )
+
+    args = parser.parse_args()
+
+    # Resolve paths
+    transcripts_dir = args.transcripts_dir.resolve()
+    ledger_path = args.state_root / "ledger" / "transcripts-brief.jsonl"
+
+    if not transcripts_dir.exists():
+        print(f"ERROR: transcripts directory not found: {transcripts_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    # Read existing agent IDs (for idempotency)
+    existing_ids = get_existing_agent_ids(ledger_path)
+
+    # Stream and digest transcripts
+    agents = stream_jsonl_transcripts(transcripts_dir)
+    briefs_to_append = []
+
+    for agent_id, (metadata, messages) in sorted(agents.items()):
+        # Skip if already digested
+        if agent_id in existing_ids:
+            continue
+
+        brief = create_brief(args.wave, agent_id, metadata, messages)
+        briefs_to_append.append(brief)
+
+    # Append to ledger
+    count = append_briefs(ledger_path, briefs_to_append)
+
+    if count > 0:
+        print(f"Appended {count} brief(s) to {ledger_path}")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()