agent-postmortem 0.3.4__py3-none-any.whl

agent_postmortem/config.py

@@ -0,0 +1,435 @@
+"""User configuration: quiet a detector without losing it from JSON or trend
+(docs/DESIGN.md 4.10), and declare per-repo rescue checks (docs/DESIGN.md
+4.11, unit M4).
+
+`${XDG_CONFIG_HOME:-~/.config}/agent-postmortem/config.toml`, overridable by
+`AGENT_POSTMORTEM_CONFIG` (a path, tests only). Section `[detectors]`, key
+`off = ["<detector id>", ...]`. A silenced detector still runs: its findings
+still populate `--json` (each finding gains a `silenced` bool) and `trend`'s
+counts; text renderers (`run`, `scan`'s reason lines and top detector,
+`demo`) drop them entirely -- never a STORIES entry, never in `--verbose`
+FINDINGS, never in WHAT TO DO, never in the account sentence, never in the
+verdict -- and a hook never notifies one or counts it toward the hook
+verdict word (docs/DESIGN.md 4.6/4.7/7.2).
+
+A critical-severity detector id in `off` is never actually silenced -- a
+silenced critical would change the exit code (docs/DESIGN.md 4.6), which is
+the one thing a config file must never be able to do quietly. `load_config()`
+drops it from `detectors_off` unconditionally and records it in
+`critical_rejected` instead of `warnings`, so a caller can tell the two
+apart: the CLI (`run`/`scan`/`demo`) turns a non-empty `critical_rejected`
+into a stderr message and exit 1 (refusing to run with a config that tried
+to do this at all); a hook just proceeds without those ids ever landing in
+`detectors_off`, silently, since a hook must never fail a turn.
+
+Missing file: nothing silenced, no warnings. Malformed TOML, a non-list
+`off`, a non-string entry, or an unknown detector id: a warning on stderr
+(the caller's job to print, redacted), nothing silenced for that entry;
+these never raise and never change any exit code.
+
+`[[repos]]` tables (docs/DESIGN.md 4.11), each `{path = "...", checks =
+[...]}`: the commands `rescue plan`/`rescue status` treat as this repo's
+declared checks, matched by comparing the observed git toplevel (normalized,
+`~`-expanded) against `path`, normalized the same way at load time. A
+declared check that contains `&&`, `||`, `;`, `|`, a newline, or starts with
+`cd ` is a compound or directory-changing command this tool must never be
+handed to run verbatim from a fixed repo root; it is rejected at load with a
+warning naming it and is never listed as declared. `checks_for_repo()` is the
+one place that match happens; nothing else in this module or rescue.py
+re-derives it.
+
+`[[adopted]]` tables (docs/DESIGN.md 9, unit M6), each `{rule = "R-...",
+date = "YYYY-MM-DD", target = "..."}`: a rule the owner has already put into
+a prompt, a hook, or a project's own instructions, by hand, outside this
+tool -- `rules review` uses the date to split a run's own detector rate into
+before/after windows. `rule` must name a rule in `rules.RULES`; `date` must
+parse as a calendar date; `target` is free text (where the owner put it),
+never checked against the filesystem. A malformed table, or one naming an
+unknown rule or an unparsable date, adds one warning and is dropped; every
+other well-formed `[[adopted]]` table is still kept.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from . import detectors as _detectors
+from .models import Finding
+from .rules import RULES
+
+_CONFIG_ENV = "AGENT_POSTMORTEM_CONFIG"
+_XDG_ENV = "XDG_CONFIG_HOME"
+
+# docs/DESIGN.md 4.11: a declared check containing any of these, or starting
+# with "cd ", is rejected at load -- this tool runs a declared check as one
+# fixed argument list from the repo root (rescue's own protocol step 3), and
+# a compound or directory-changing command could route around that.
+_FORBIDDEN_CHECK_FRAGMENTS = ("&&", "||", ";", "|", "\n")
+
+
+def _check_is_rejected(check: str) -> bool:
+    if any(fragment in check for fragment in _FORBIDDEN_CHECK_FRAGMENTS):
+        return True
+    return check.lstrip().startswith("cd ")
+
+
+@dataclass(frozen=True)
+class WarningPart:
+    """One piece of a config warning (docs/DESIGN.md 5.1; F fix 8, W8-10). `kind` is `text` (the
+    tool's own fixed words, kept as they are), `path` (the config file or a `[[repos]]` path field,
+    rendered once as one value by `display_path`) or `untrusted` (a value that came from the file:
+    a rule id, a detector id, a date, a parser message, a rejected command; it goes through the
+    free-text scan as one piece)."""
+
+    kind: str
+    value: str
+
+
+class ConfigWarning(str):
+    """A warning as the text it is plus the typed parts it was built from. It IS the assembled
+    string (so a caller that only prints or compares it is unchanged); `Config.shown_warnings`
+    renders from `parts` and never splits the assembled text."""
+
+    parts: tuple[WarningPart, ...]
+
+    def __new__(cls, *parts: WarningPart) -> "ConfigWarning":
+        warning = super().__new__(cls, "".join(part.value for part in parts))
+        warning.parts = tuple(parts)
+        return warning
+
+
+def _t(value: object) -> WarningPart:
+    return WarningPart("text", str(value))
+
+
+def _p(value: object) -> WarningPart:
+    return WarningPart("path", str(value))
+
+
+def _u(value: object) -> WarningPart:
+    return WarningPart("untrusted", str(value))
+
+
+def _warn(path: object, *rest: WarningPart) -> ConfigWarning:
+    """`agent-postmortem: <config path>: <rest>`, the shape of every warning."""
+    return ConfigWarning(_t("agent-postmortem: "), _p(path), _t(": "), *rest)
+
+
+@dataclass(frozen=True)
+class RepoConfig:
+    """One `[[repos]]` table (docs/DESIGN.md 4.11): `path`, normalized and
+    `~`-expanded at load time so `checks_for_repo` is a plain string
+    comparison, and `checks`, already filtered of any rejected command."""
+
+    path: str
+    checks: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AdoptedRule:
+    """One `[[adopted]]` table (docs/DESIGN.md 9): a rule the owner already
+    put somewhere by hand, outside this tool. `date` is a plain "YYYY-MM-DD"
+    string, already validated as a real calendar date at load time."""
+
+    rule: str
+    date: str
+    target: str = ""
+
+
+@dataclass(frozen=True)
+class Config:
+    detectors_off: frozenset[str]
+    warnings: list[str] = field(default_factory=list)
+    # A critical detector id named in [detectors].off, never honored (see
+    # module docstring). Kept separate from `warnings` so a caller can tell
+    # "silence this unknown id anyway, just warn" from "refuse to run".
+    critical_rejected: tuple[str, ...] = ()
+    # docs/DESIGN.md 4.11: every successfully parsed [[repos]] table, a
+    # rejected check already dropped from its own `checks` (with a warning
+    # recorded above, not here).
+    repos: tuple[RepoConfig, ...] = ()
+    # docs/DESIGN.md 9: every successfully parsed [[adopted]] table --
+    # `rules review`'s own input, alongside the state store's legacy
+    # `applied` entries (7.5).
+    adopted: tuple[AdoptedRule, ...] = ()
+    # The config file the warnings name (N3b C4): lets a renderer replace it,
+    # and every [[repos]] path, by its own display before the text is shown.
+    config_file: str = ""
+
+    def shown_warnings(
+        self, display: Callable[[str], str], scan: Callable[[str], str] | None = None,
+    ) -> list[str]:
+        """`warnings` as they are shown (docs/DESIGN.md 5.1; F fix 8, W8-10): a warning is built
+        from typed parts when the parser creates it (`ConfigWarning`). A `text` part is kept, a
+        `path` part (the config file, a `[[repos]]` path) is rendered once as one value by
+        display(path), and an `untrusted` part goes through `scan` as one piece when one is given.
+        The assembled warning is never split again and never scanned as a whole, so a repository
+        path that is a prefix of a longer untrusted path cannot leave a tail unscanned, and a
+        rendered `~/name` is not read as a path start that hides the words after it. A warning
+        with no parts (a hand-built one) is one untrusted piece."""
+        return ["".join(self._shown_piece(part, display, scan) for part in _parts_of(warning))
+                for warning in self.warnings]
+
+    @staticmethod
+    def _shown_piece(
+        part: WarningPart, display: Callable[[str], str], scan: Callable[[str], str] | None,
+    ) -> str:
+        if part.kind == "path":
+            return display(part.value)
+        if part.kind == "untrusted" and scan is not None and part.value:
+            return scan(part.value)
+        return part.value
+
+
+def _parts_of(warning: str) -> tuple[WarningPart, ...]:
+    if isinstance(warning, ConfigWarning):
+        return warning.parts
+    return (WarningPart("untrusted", str(warning)),)
+
+
+_EMPTY = Config(detectors_off=frozenset(), warnings=[])
+
+# Process-level cache keyed by the resolved config path (the same pattern
+# reader.ParentIndex uses for a parent transcript): re-reading the same path
+# twice in one process is wasted work, but a different path (a test's own
+# tmp_path, via AGENT_POSTMORTEM_CONFIG) always gets its own fresh parse.
+_cache: dict[str, Config] = {}
+
+
+def config_path() -> Path:
+    """`$AGENT_POSTMORTEM_CONFIG`, else
+    `${XDG_CONFIG_HOME:-~/.config}/agent-postmortem/config.toml` (docs/
+    DESIGN.md 4.8/4.10)."""
+    override = os.environ.get(_CONFIG_ENV, "").strip()
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get(_XDG_ENV, "").strip()
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / "agent-postmortem" / "config.toml"
+
+
+def _known_detector_ids() -> frozenset[str]:
+    return frozenset(detector.id for detector in _detectors.all_detectors())
+
+
+def _critical_detector_ids() -> frozenset[str]:
+    return frozenset(
+        detector.id for detector in _detectors.all_detectors()
+        if detector.severity_default == "critical"
+    )
+
+
+def _parse_repos(data: dict, path: Path, warnings: list[str]) -> list[RepoConfig]:
+    """Every usable `[[repos]]` table (docs/DESIGN.md 4.11): a malformed
+    table, a malformed `path`, a malformed `checks` list, or an individual
+    rejected check each add one warning and are dropped -- never raise,
+    never abort parsing the rest of the file."""
+    raw_repos = data.get("repos")
+    if raw_repos is None:
+        return []
+    if not isinstance(raw_repos, list):
+        warnings.append(_warn(path, _t("[[repos]] must be an array of tables")))
+        return []
+
+    repos: list[RepoConfig] = []
+    for entry in raw_repos:
+        if not isinstance(entry, dict):
+            warnings.append(_warn(path, _t("a [[repos]] entry must be a table")))
+            continue
+        raw_path = entry.get("path")
+        if not isinstance(raw_path, str) or not raw_path:
+            warnings.append(_warn(path, _t("a [[repos]] table needs a non-empty 'path'")))
+            continue
+        norm_path = os.path.normpath(os.path.expanduser(raw_path))
+
+        raw_checks = entry.get("checks", [])
+        if not isinstance(raw_checks, list):
+            warnings.append(_warn(
+                path, _t("[[repos]] 'checks' must be a list of strings ("), _p(norm_path), _t(")"),
+            ))
+            raw_checks = []
+
+        checks: list[str] = []
+        for check in raw_checks:
+            if not isinstance(check, str) or not check.strip():
+                warnings.append(_warn(
+                    path, _t("a declared check must be a non-empty string ("), _p(norm_path),
+                    _t(")"),
+                ))
+                continue
+            if _check_is_rejected(check):
+                warnings.append(_warn(
+                    path,
+                    _t("declared check rejected, compound or directory-changing command: "),
+                    _u(repr(check)),
+                ))
+                continue
+            checks.append(check)
+
+        repos.append(RepoConfig(path=norm_path, checks=tuple(checks)))
+    return repos
+
+
+def _parse_adopted(data: dict, path: Path, warnings: list[str]) -> list[AdoptedRule]:
+    """Every usable `[[adopted]]` table (docs/DESIGN.md 9): a malformed
+    table, an unknown rule id, or an unparsable date each add one warning
+    and are dropped -- never raise, never abort parsing the rest of the
+    file."""
+    raw_adopted = data.get("adopted")
+    if raw_adopted is None:
+        return []
+    if not isinstance(raw_adopted, list):
+        warnings.append(_warn(path, _t("[[adopted]] must be an array of tables")))
+        return []
+
+    adopted: list[AdoptedRule] = []
+    for entry in raw_adopted:
+        if not isinstance(entry, dict):
+            warnings.append(_warn(path, _t("an [[adopted]] entry must be a table")))
+            continue
+        rule_id = entry.get("rule")
+        if not isinstance(rule_id, str) or not rule_id:
+            warnings.append(_warn(path, _t("an [[adopted]] table needs a non-empty 'rule'")))
+            continue
+        if rule_id not in RULES:
+            warnings.append(_warn(
+                path, _t("unknown rule id '"), _u(rule_id), _t("' in [[adopted]]"),
+            ))
+            continue
+
+        date = entry.get("date")
+        if not isinstance(date, str):
+            warnings.append(_warn(
+                path, _t("an [[adopted]] table needs 'date' as YYYY-MM-DD ("), _u(rule_id), _t(")"),
+            ))
+            continue
+        try:
+            datetime.strptime(date, "%Y-%m-%d")
+        except ValueError:
+            warnings.append(_warn(
+                path, _t("[[adopted]] 'date' is not a valid YYYY-MM-DD date ("), _u(rule_id),
+                _t(": "), _u(repr(date)), _t(")"),
+            ))
+            continue
+
+        target = entry.get("target", "")
+        if not isinstance(target, str):
+            warnings.append(_warn(
+                path, _t("[[adopted]] 'target' must be a string ("), _u(rule_id), _t(")"),
+            ))
+            target = ""
+
+        adopted.append(AdoptedRule(rule=rule_id, date=date, target=target))
+    return adopted
+
+
+def _parse(path: Path) -> Config:
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return _EMPTY
+
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError) as exc:
+        return Config(
+            detectors_off=frozenset(),
+            warnings=[_warn(path, _t("could not parse config: "), _u(exc))],
+            config_file=str(path),
+        )
+
+    warnings: list[str] = []
+    critical_rejected: list[str] = []
+    kept: set[str] = set()
+
+    detectors_section = data.get("detectors")
+    if detectors_section is not None:
+        if not isinstance(detectors_section, dict):
+            warnings.append(_warn(path, _t("[detectors] must be a table")))
+        else:
+            off = detectors_section.get("off", [])
+            if not isinstance(off, list):
+                warnings.append(_warn(path, _t("[detectors].off must be a list of strings")))
+            else:
+                known = _known_detector_ids()
+                critical = _critical_detector_ids()
+                for item in off:
+                    if not isinstance(item, str) or not item:
+                        warnings.append(_warn(
+                            path, _t("[detectors].off entries must be non-empty strings"),
+                        ))
+                        continue
+                    if item in critical:
+                        critical_rejected.append(item)
+                        continue
+                    if item not in known:
+                        warnings.append(_warn(
+                            path, _t("unknown detector id '"), _u(item), _t("' in [detectors].off"),
+                        ))
+                        continue
+                    kept.add(item)
+
+    repos = _parse_repos(data, path, warnings)
+    adopted = _parse_adopted(data, path, warnings)
+
+    return Config(
+        detectors_off=frozenset(kept),
+        warnings=warnings,
+        critical_rejected=tuple(critical_rejected),
+        repos=tuple(repos),
+        adopted=tuple(adopted),
+        config_file=str(path),
+    )
+
+
+def load_config() -> Config:
+    """The active Config, cached per process by resolved path (docs/
+    DESIGN.md 4.10). Never raises: a missing file, a malformed one, or one
+    naming an unknown or critical detector id all return a usable Config,
+    the problem (if any) recorded in `warnings`/`critical_rejected` for the
+    caller to print."""
+    path = config_path()
+    key = str(path)
+    cached = _cache.get(key)
+    if cached is not None:
+        return cached
+    parsed = _parse(path)
+    _cache[key] = parsed
+    return parsed
+
+
+def partition_silenced(
+    findings: list[Finding], config: Config,
+) -> tuple[list[Finding], list[Finding]]:
+    """(shown, silenced): findings whose detector id is in
+    config.detectors_off go to `silenced`, everything else to `shown`, both
+    in the findings' original order. The one split every renderer (docs/
+    DESIGN.md 4.6/4.7) and every hook (7.2) uses, so "what counts as
+    silenced" is never redefined twice."""
+    shown: list[Finding] = []
+    silenced: list[Finding] = []
+    for finding in findings:
+        if finding.detector in config.detectors_off:
+            silenced.append(finding)
+        else:
+            shown.append(finding)
+    return shown, silenced
+
+
+def checks_for_repo(cfg: Config, repo_root: str) -> list[str]:
+    """The declared checks for repo_root (docs/DESIGN.md 4.11): the observed
+    git toplevel, normalized and `~`-expanded the same way `_parse_repos`
+    normalized every `[[repos]]` table's own `path` at load time, so this is
+    a plain string comparison. `[]` when no `[[repos]]` table names this
+    repo -- rescue.py's own "no checks declared" wording, not this
+    function's job."""
+    norm_root = os.path.normpath(os.path.expanduser(repo_root))
+    for repo in cfg.repos:
+        if repo.path == norm_root:
+            return list(repo.checks)
+    return []

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000001.jsonl

@@ -0,0 +1,5 @@
+{"type":"user","timestamp":"2026-01-06T19:00:00.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":null,"agentId":"ac200000000000001","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":"Implement the silent-alpha module and add a test."}}
+{"type":"assistant","timestamp":"2026-01-06T19:00:05.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000001","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"assistant","content":[{"type":"text","text":"Running the test suite first."},{"type":"tool_use","id":"toolu_silent_c_1","name":"Bash","input":{"command":"pytest tests/test_silent_alpha.py -q"}}],"usage":{"input_tokens":100,"output_tokens":30,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}
+{"type":"user","timestamp":"2026-01-06T19:00:06.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000001","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_silent_c_1","content":"1 passed in 0.02s","is_error":false}]}}
+{"type":"assistant","timestamp":"2026-01-06T19:03:04.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000001","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"assistant","content":[{"type":"text","text":"Tests pass. Writing the implementation now."}],"usage":{"input_tokens":90,"output_tokens":20,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}
+{"type":"user","timestamp":"2026-01-06T19:10:00.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000001","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":"[Request interrupted by user]"}}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000001.meta.json

@@ -0,0 +1,8 @@
+{
+  "agentType": "general-purpose",
+  "description": "Implement the silent-alpha module.",
+  "workflowPhase": "Implement",
+  "spawnDepth": "1",
+  "requestShape": "single",
+  "requestNonInteractive": "true"
+}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000002.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-01-06T19:10:05.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":null,"agentId":"ac200000000000002","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":"You may be a retry after a killed attempt. Implement the silent-alpha module and add a test."}}
+{"type":"assistant","timestamp":"2026-01-06T19:25:05.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000002","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"assistant","content":[{"type":"text","text":"Done. Implemented silent-alpha with a passing test."}],"usage":{"input_tokens":160,"output_tokens":45,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000002.meta.json

@@ -0,0 +1,8 @@
+{
+  "agentType": "general-purpose",
+  "description": "Implement the silent-alpha module.",
+  "workflowPhase": "Implement",
+  "spawnDepth": "1",
+  "requestShape": "single",
+  "requestNonInteractive": "true"
+}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000003.jsonl

@@ -0,0 +1,5 @@
+{"type":"user","timestamp":"2026-01-06T19:30:00.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":null,"agentId":"ac200000000000003","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":"Implement the silent-beta module and add a test."}}
+{"type":"assistant","timestamp":"2026-01-06T19:30:05.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000003","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"assistant","content":[{"type":"text","text":"Running the test suite first."},{"type":"tool_use","id":"toolu_silent_e_1","name":"Bash","input":{"command":"pytest tests/test_silent_beta.py -q"}}],"usage":{"input_tokens":100,"output_tokens":30,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}
+{"type":"user","timestamp":"2026-01-06T19:30:06.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000003","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_silent_e_1","content":"1 passed in 0.02s","is_error":false}]}}
+{"type":"assistant","timestamp":"2026-01-06T19:33:04.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000003","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"assistant","content":[{"type":"text","text":"Tests pass. Writing the implementation now."}],"usage":{"input_tokens":90,"output_tokens":20,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}
+{"type":"user","timestamp":"2026-01-06T19:40:00.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000003","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":"[Request interrupted by user]"}}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000003.meta.json

@@ -0,0 +1,8 @@
+{
+  "agentType": "general-purpose",
+  "description": "Implement the silent-beta module.",
+  "workflowPhase": "Implement",
+  "spawnDepth": "1",
+  "requestShape": "single",
+  "requestNonInteractive": "true"
+}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000004.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","timestamp":"2026-01-06T19:40:05.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":null,"agentId":"ac200000000000004","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"user","content":"You may be a retry after a killed attempt. Implement the silent-beta module and add a test."}}
+{"type":"assistant","timestamp":"2026-01-06T19:55:05.000Z","uuid":"00000000-0000-4000-8000-000000000000","parentUuid":"00000000-0000-4000-8000-000000000000","agentId":"ac200000000000004","cwd":"/home/user/project","sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","message":{"role":"assistant","content":[{"type":"text","text":"Done. Implemented silent-beta with a passing test."}],"usage":{"input_tokens":160,"output_tokens":45,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/agent-ac200000000000004.meta.json

@@ -0,0 +1,8 @@
+{
+  "agentType": "general-purpose",
+  "description": "Implement the silent-beta module.",
+  "workflowPhase": "Implement",
+  "spawnDepth": "1",
+  "requestShape": "single",
+  "requestNonInteractive": "true"
+}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000/subagents/workflows/wf_00000000-d30/journal.jsonl

@@ -0,0 +1,7 @@
+{"type":"launched","timestamp":"2026-01-06T18:59:59.000Z"}
+{"type":"started","timestamp":"2026-01-06T19:00:00.000Z","key":"v2:silent-alpha","agentId":"ac200000000000001","label":"impl:silent-alpha","phase":"Implement"}
+{"type":"started","timestamp":"2026-01-06T19:10:05.000Z","key":"v2:silent-alpha","agentId":"ac200000000000002","label":"impl:silent-alpha","phase":"Implement"}
+{"type":"result","timestamp":"2026-01-06T19:25:05.000Z","agentId":"ac200000000000002","key":"v2:silent-alpha","outcome":"completed"}
+{"type":"started","timestamp":"2026-01-06T19:30:00.000Z","key":"v2:silent-beta","agentId":"ac200000000000003","label":"impl:silent-beta","phase":"Implement"}
+{"type":"started","timestamp":"2026-01-06T19:40:05.000Z","key":"v2:silent-beta","agentId":"ac200000000000004","label":"impl:silent-beta","phase":"Implement"}
+{"type":"result","timestamp":"2026-01-06T19:55:05.000Z","agentId":"ac200000000000004","key":"v2:silent-beta","outcome":"completed"}

agent_postmortem/demo/-home-user-project/00000000-0000-4000-8000-000000000000.jsonl

@@ -0,0 +1,4 @@
+{"type":"user","message":{"role":"user","content":"Implement the silent-alpha and silent-beta modules."},"sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","cwd":"/home/user/project","timestamp":"2026-01-06T18:59:40.000Z"}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_demo0001","name":"Workflow","input":{"description":"implement silent modules"}}],"usage":{"input_tokens":12,"output_tokens":6}},"sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","cwd":"/home/user/project","timestamp":"2026-01-06T18:59:50.000Z"}
+{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_demo0001","content":"Launched workflow. Run ID: wf_00000000-d30"}]},"toolUseResult":{"runId":"wf_00000000-d30","taskId":"demo-task-1","status":"async_launched"},"sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","cwd":"/home/user/project","timestamp":"2026-01-06T18:59:58.000Z"}
+{"type":"user","message":{"role":"user","content":"<task-notification>\n<task-id>demo-task-1</task-id>\n<tool-use-id>toolu_demo0001</tool-use-id>\n<output-file>/tmp/demo-output</output-file>\n<status>completed</status>\n</task-notification>"},"origin":{"kind":"task-notification"},"sessionId":"00000000-0000-4000-8000-000000000000","version":"2.1.267","cwd":"/home/user/project","timestamp":"2026-01-06T19:56:00.000Z"}

agent_postmortem/detectors/__init__.py

@@ -0,0 +1,98 @@
+"""Detector registry.
+
+Adding a detector means adding a module to this package that exports a
+module-level DETECTOR instance; nothing here needs to change. all_detectors()
+imports every module in the package and collects the ones that export it.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import TYPE_CHECKING
+
+from .base import Detector
+
+if TYPE_CHECKING:
+    from ..models import Finding, Run
+
+__all__ = [
+    "Detector", "all_detectors", "run_detectors", "run_tooling_detectors", "TOOLING_DETECTOR_IDS",
+]
+
+# docs/DESIGN.md 4.3: the eight tooling detectors, scanned by a session's
+# main thread as well as every child attempt. Named here once so a caller
+# that must run only these (docs/DESIGN.md 7.2's session-end hook, D5) does
+# not have to spell the list out itself.
+TOOLING_DETECTOR_IDS: frozenset[str] = frozenset({
+    "bash_backgrounded",
+    "bash_timeout",
+    "tool_json_error",
+    "structured_output_failure",
+    "codex_write_denied",
+    "classifier_unavailable",
+    "git_cwd_mismatch",
+    "codex_unavailable",
+})
+
+
+# docs/DESIGN.md 4.13.7 step 1 (N7): discovery runs once per process, not once
+# per run; `scan` used to repeat it for every run it analyzed.
+_REGISTRY: list[Detector] | None = None
+
+
+def all_detectors() -> list[Detector]:
+    """Return every registered detector, sorted by id.
+
+    Discovered on the first call and cached for the process; each call hands
+    out a new list, so a caller that edits its list cannot change what the next
+    caller sees. Returns an empty list when the package holds no detector
+    modules (v0 ships this package with base.py only; detector modules land
+    later).
+    """
+    global _REGISTRY
+    if _REGISTRY is None:
+        found: list[Detector] = []
+        for module_info in pkgutil.iter_modules(__path__):
+            if module_info.name in ("base", "__init__"):
+                continue
+            module = importlib.import_module(f"{__name__}.{module_info.name}")
+            detector = getattr(module, "DETECTOR", None)
+            if detector is not None:
+                found.append(detector)
+        _REGISTRY = sorted(found, key=lambda detector: detector.id)
+    return list(_REGISTRY)
+
+
+def _reset_registry() -> None:
+    """Forget the cached discovery, so the next all_detectors() call discovers
+    again. A documented test hook (docs/DESIGN.md 4.13.11 "N7"); production code
+    never calls it."""
+    global _REGISTRY
+    _REGISTRY = None
+
+
+def run_detectors(run: "Run") -> list["Finding"]:
+    """Every finding from every registered detector whose kinds include
+    run.kind (docs/DESIGN.md 4.3): the one place cli.py, report.py, and
+    trend.py all get findings from, so a run kind's applicable detectors are
+    never decided in more than one place.
+    """
+    findings: list[Finding] = []
+    for detector in all_detectors():
+        if run.kind in detector.kinds:
+            findings.extend(detector.run(run))
+    return findings
+
+
+def run_tooling_detectors(run: "Run") -> list["Finding"]:
+    """Every finding from just the eight tooling detectors (docs/
+    DESIGN.md 4.3, TOOLING_DETECTOR_IDS), for a caller that must not run
+    mislabeled_kill or missing_artifact -- docs/DESIGN.md 7.2's session-end
+    hook (D5), which analyzes only the main thread and has no children to
+    attribute an interrupt or a missing artifact to."""
+    findings: list[Finding] = []
+    for detector in all_detectors():
+        if detector.id in TOOLING_DETECTOR_IDS and run.kind in detector.kinds:
+            findings.extend(detector.run(run))
+    return findings