agent-postmortem 0.3.4__py3-none-any.whl

agent_postmortem/detectors/bash_timeout.py

@@ -0,0 +1,94 @@
+"""Detects a Bash command the runtime hard-killed after its timeout.
+
+DESIGN.md 4.3: minor severity, fires when a Bash tool_result shows exit code
+143 (BASH_TIMEOUT_EXIT_CODE, read from Event.exit_code directly -- never a
+marker) or carries an anchored, not-in-payload 'bash_timeout' MarkerHit
+(docs/DESIGN.md 4.13.2: the registry's own predicate already requires
+line1 == 'Exit code 143' and line2 to start with 'Command timed out after').
+These two triggers are independent (M1 review): an exit code alone, with no
+explanatory second line (an in-memory build, a truncated result), must still
+count. metrics: count. rule_id: R-NO-LONG-BASH.
+
+Title (field milestone F, P10): "hit a hard timeout" only when every hit carries the anchored
+marker; when any hit is the exit code alone, "ended with exit code 143 (a hard timeout or
+another termination)". Severity and metrics do not change.
+"""
+
+from __future__ import annotations
+
+from .. import severity as severity_rules
+from ..markers import BASH_TIMEOUT_EXIT_CODE
+from ..models import Event, Finding, Run
+from .base import (
+    KINDS_BOTH,
+    Detector,
+    anchored_marker_hits,
+    event_for_marker_hit,
+    evidence_line,
+    is_bash_event,
+    make_finding_id,
+    single_agent_id,
+    tooling_attempts,
+)
+
+ID = "bash_timeout"
+SEVERITY = "minor"
+RULE_ID = "R-NO-LONG-BASH"
+
+
+class BashTimeout:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_BOTH
+
+    def run(self, run: Run) -> list[Finding]:
+        hits: list[Event] = []
+        exit_code_only = False  # P10: some hit has no anchored timeout marker
+        hit_agents: list[str] = []
+        for attempt in tooling_attempts(run):
+            marker_events = {
+                id(event)
+                for hit in anchored_marker_hits(attempt, ID)
+                if (event := event_for_marker_hit(attempt, hit)) is not None
+            }
+            for event in attempt.events:
+                if not is_bash_event(event):
+                    continue
+                if event.exit_code == BASH_TIMEOUT_EXIT_CODE or id(event) in marker_events:
+                    hits.append(event)
+                    if id(event) not in marker_events:
+                        exit_code_only = True
+                    hit_agents.append(attempt.agent_id)
+        if not hits:
+            return []
+        agent_id = single_agent_id(hit_agents)
+
+        count = len(hits)
+        plural = "s" if count != 1 else ""
+        if exit_code_only:
+            title = (
+                f"{count} Bash command{plural} ended with exit code 143 "
+                "(a hard timeout or another termination)"
+            )
+        else:
+            title = f"{count} Bash command{plural} hit a hard timeout"
+        evidence = [evidence_line(run, event) for event in hits]
+
+        return [
+            Finding(
+                detector=ID,
+                severity=severity_rules.resolve(run, ID),
+                title=title,
+                run_id=run.run_id,
+                agent_id=agent_id,
+                evidence=evidence,
+                metrics={"count": count},
+                rule_id=RULE_ID,
+                finding_id=make_finding_id(
+                    run.run_id, ID, agent_id, evidence[0] if evidence else None
+                ),
+            )
+        ]
+
+
+DETECTOR: Detector = BashTimeout()

agent_postmortem/detectors/claim_contradiction.py

@@ -0,0 +1,251 @@
+"""claim_contradiction: a completed workflow attempt whose own self-reported
+result contradicts the outcome the journal recorded (.reviews/proposals/
+2026-09-v0.2-guided-rescue.md section 4.3, unit M1c).
+
+Reads only Attempt.reported (docs/DESIGN.md section 3/4.1), which the
+reader already restricted to an allowlisted set of self-reported claims --
+never a raw transcript scan, never the free-text keys ("note", "summary",
+...) a real result carries alongside them. The one filesystem check this
+detector performs (report_path existence) follows missing_artifact's own
+convention: severity.absence() on the path as reported. A relative
+report_path cannot be checked against anything the reader records today
+(Attempt/Event carry no cwd field in this milestone) and is reported
+'unverified' rather than counted as a contradiction.
+
+Severity (docs/DESIGN.md 4.3, 4.13.4): a tests, suite, ok, ready, or blockers
+clause is major; a report_path clause is info (the path is absent now, which
+says nothing about the end of the run). A finding takes the highest of its
+clauses, and a finding of report_path clauses alone carries the D2 title.
+
+G3 (v0.3.1): when no tests, suite, ok, ready or blockers clause holds, a result
+that carries a failure count of its own or `blocked: true` (the attempt's private
+claims.SelfReport, decided once by the reader through the shared predicate) adds the
+clause self_reported_failure or self_reported_blocked, major. Such a finding has a
+fixed title and a bare journal pointer as its evidence: no key name and no result
+text reaches it.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timedelta, timezone
+
+from .. import severity as severity_rules
+from ..claims import SelfReport
+from ..models import Finding, Run, TitleParts
+from .base import KINDS_WORKFLOW_ONLY, Detector, make_finding_id
+
+ID = "claim_contradiction"
+SEVERITY = "major"
+
+# Every clause this detector can emit (docs/DESIGN.md 4.13.4); severity.VOCAB["clause"] has
+# exactly these, and each has a row in severity.RULES.
+CLAUSE_IDS = (
+    "tests_failed", "suite_failed", "ok_false", "ready_false", "blockers",
+    "report_path_missing", "self_reported_failure", "self_reported_blocked",
+)
+_LEGACY_MAJOR = frozenset({"tests_failed", "suite_failed", "ok_false", "ready_false", "blockers"})
+
+# A report_path is checked on disk only while the file could still be
+# expected to exist. Reports land in temp directories that are cleaned up
+# days later: on the machine this was built on, 31 of the 50 findings this
+# detector produced over old runs were report_path clauses on runs weeks
+# old. For a run that ended more than this long ago the clause is not
+# evidence either way and is skipped; a run with no known end time is
+# treated as recent, since nothing says it is old.
+REPORT_PATH_MAX_AGE = timedelta(hours=72)
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _report_path_checkable(run: Run) -> bool:
+    if run.ended_at is None:
+        return True
+    ended = run.ended_at
+    if ended.tzinfo is None:
+        ended = ended.replace(tzinfo=timezone.utc)
+    return _now() - ended <= REPORT_PATH_MAX_AGE
+
+
+def _plural(n: int, word: str) -> str:
+    return word if n == 1 else f"{word}s"
+
+
+def _report_path_state(claims: dict) -> str | None:
+    """The absence of claims['report_path'] when it is set, absolute, and not
+    present on disk at analysis time: `absent_now`, or `unknown` when the stat
+    call itself failed. None otherwise. A relative path is never checked (no
+    attempt.cwd to resolve it against in this milestone) and never makes a
+    clause -- it is simply not evidence either way."""
+    report_path = claims.get("report_path")
+    if not isinstance(report_path, str) or not report_path:
+        return None
+    if not os.path.isabs(report_path):
+        return None
+    state = severity_rules.absence(report_path)
+    return None if state == "present_now" else state
+
+
+def _clauses(
+    claims: dict, check_report_path: bool = True, self_report: SelfReport | None = None,
+) -> list[tuple[str, str, str]]:
+    """(clause id, human phrase, absence) for every clause of docs/DESIGN.md 4.3
+    that holds over claims, in a fixed order. `absence` is "none" for every clause
+    but report_path_missing (not applicable). A non-empty `self_report` adds its one
+    clause (G3) only when no legacy major clause holds, so an attempt carries exactly
+    one major finding either way."""
+    clauses: list[tuple[str, str, str]] = []
+
+    tests_failed = claims.get("tests_failed")
+    if isinstance(tests_failed, int) and tests_failed > 0:
+        clauses.append((
+            "tests_failed", f"{tests_failed} failed {_plural(tests_failed, 'test')}", "none",
+        ))
+
+    suite_failed = claims.get("suite_failed")
+    if isinstance(suite_failed, int) and suite_failed > 0:
+        clauses.append((
+            "suite_failed", f"{suite_failed} failed suite {_plural(suite_failed, 'check')}",
+            "none",
+        ))
+
+    if claims.get("ok") is False:
+        clauses.append(("ok_false", "ok is false", "none"))
+
+    if claims.get("ready") is False:
+        clauses.append(("ready_false", "ready is false", "none"))
+
+    blockers_count = claims.get("blockers_count")
+    if isinstance(blockers_count, int) and blockers_count > 0:
+        clauses.append((
+            "blockers", f"{blockers_count} {_plural(blockers_count, 'blocker')}", "none",
+        ))
+
+    if check_report_path:
+        state = _report_path_state(claims)
+        if state is not None:
+            clauses.append(("report_path_missing", "a report_path that does not exist", state))
+
+    if self_report and not any(clause_id in _LEGACY_MAJOR for clause_id, _p, _a in clauses):
+        if self_report.failed_counts > 0:
+            n = self_report.failed_counts
+            clauses.append((
+                "self_reported_failure", f"{n} {_plural(n, 'failure count')}", "none",
+            ))
+        else:
+            clauses.append(("self_reported_blocked", "being blocked", "none"))
+
+    return clauses
+
+
+def _self_report_title(self_report: SelfReport) -> str:
+    """The fixed G3 title: no label, no key name, no value (the same at every level)."""
+    if self_report.failed_counts > 0:
+        n = self_report.failed_counts
+        return (
+            f"completed, but its own returned result reports failures in {n} {_plural(n, 'field')}"
+        )
+    return "completed, but its own returned result reports it was blocked"
+
+
+_ABSENT_TEMPLATE = (
+    "{path} is absent now; the tool cannot tell whether it existed when the run ended"
+)
+_UNCHECKED_TEMPLATE = (
+    "{path} could not be checked now; the tool cannot tell whether it existed "
+    "when the run ended"
+)
+
+
+def _report_path_title_parts(path: str, state: str) -> TitleParts:
+    """The D2 title of a finding whose only clause is an absent report_path, as a fixed template
+    and the path (F fix 7, W7-2): a renderer formats it once and never scans the result."""
+    template = _ABSENT_TEMPLATE if state == "absent_now" else _UNCHECKED_TEMPLATE
+    return TitleParts(template, path)
+
+
+def _report_path_title(path: str, state: str) -> str:
+    """The title with the real path (what `raw` prints)."""
+    return _report_path_title_parts(path, state).raw()
+
+
+class ClaimContradiction:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_WORKFLOW_ONLY
+
+    def run(self, run: Run) -> list[Finding]:
+        findings: list[Finding] = []
+        check_report_path = _report_path_checkable(run)
+
+        for attempt in run.attempts:
+            if attempt.outcome != "completed":
+                continue
+            reported = attempt.reported
+            if not isinstance(reported, dict) or reported.get("type") != "dict":
+                continue
+            claims = reported.get("claims", {})
+            self_report = attempt._self_report
+            if not isinstance(self_report, SelfReport):
+                self_report = None
+            clauses = _clauses(claims, check_report_path, self_report)
+            if not clauses:
+                continue
+
+            phrases = "; ".join(phrase for _clause_id, phrase, _absence in clauses)
+            title_parts = None
+            self_clause = any(
+                clause_id in ("self_reported_failure", "self_reported_blocked")
+                for clause_id, _p, _a in clauses
+            )
+            if self_clause:
+                title = _self_report_title(self_report)
+            elif all(clause_id == "report_path_missing" for clause_id, _p, _a in clauses):
+                title_parts = _report_path_title_parts(claims["report_path"], clauses[0][2])
+                title = title_parts.raw()
+            else:
+                title = (
+                    f"{attempt.label} attempt {attempt.ordinal} completed but its own "
+                    f"result reports {phrases}"
+                )
+            severity = severity_rules.worst([
+                severity_rules.resolve(run, ID, clause=clause_id, absence=absence)
+                for clause_id, _phrase, absence in clauses
+            ])
+            excerpt = " ".join(phrases.split())[:160]
+            line = attempt.reported_line
+            if self_clause:
+                evidence = [f"journal.jsonl:{line}"] if line is not None else []
+            else:
+                evidence = [f"journal.jsonl:{line}: {excerpt}"] if line is not None else []
+            metrics = {
+                "clauses": [clause_id for clause_id, _phrase, _absence in clauses],
+                "claims": claims,
+            }
+            if self_clause:
+                metrics["self_reported_failure_counts"] = self_report.failed_counts
+                metrics["self_reported_blocked"] = self_report.blocked
+
+            findings.append(
+                Finding(
+                    detector=ID,
+                    severity=severity,
+                    title=title,
+                    title_parts=title_parts,
+                    run_id=run.run_id,
+                    agent_id=attempt.agent_id,
+                    evidence=evidence,
+                    metrics=metrics,
+                    rule_id=None,
+                    finding_id=make_finding_id(
+                        run.run_id, ID, attempt.agent_id, evidence[0] if evidence else None
+                    ),
+                )
+            )
+
+        return findings
+
+
+DETECTOR: Detector = ClaimContradiction()

agent_postmortem/detectors/classifier_unavailable.py

@@ -0,0 +1,73 @@
+"""Detects the Bash-safety classifier going unavailable in auto mode.
+
+DESIGN.md 4.3: minor severity, fires on every anchored, not-in-payload
+'classifier_unavailable' MarkerHit (docs/DESIGN.md 4.13.2: the registry's
+own shape restricts this id to a tool_result paired to Bash). Not something
+a prompt or hook can fix, so there is no rule_id. metrics: count. Skips a
+read_only_output event (docs/DESIGN.md 4.3's self-reference rule): a
+Read/Grep/sed/etc. call quoting the outage sentence from a file on disk is
+not the classifier actually going unavailable during this agent's own Bash
+call.
+"""
+
+from __future__ import annotations
+
+from .. import severity as severity_rules
+from ..models import Event, Finding, Run
+from .base import (
+    KINDS_BOTH,
+    Detector,
+    anchored_marker_hits,
+    event_for_marker_hit,
+    evidence_line,
+    make_finding_id,
+    single_agent_id,
+    tooling_attempts,
+)
+
+ID = "classifier_unavailable"
+SEVERITY = "minor"
+
+
+class ClassifierUnavailable:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_BOTH
+
+    def run(self, run: Run) -> list[Finding]:
+        hits: list[Event] = []
+        hit_agents: list[str] = []
+        for attempt in tooling_attempts(run):
+            for hit in anchored_marker_hits(attempt, ID):
+                event = event_for_marker_hit(attempt, hit)
+                if event is None or event.read_only_output:
+                    continue
+                hits.append(event)
+                hit_agents.append(attempt.agent_id)
+        if not hits:
+            return []
+        agent_id = single_agent_id(hit_agents)
+
+        count = len(hits)
+        plural = "s" if count != 1 else ""
+        title = f"Bash-safety classifier was unavailable {count} time{plural}"
+        evidence = [evidence_line(run, event) for event in hits]
+
+        return [
+            Finding(
+                detector=ID,
+                severity=severity_rules.resolve(run, ID),
+                title=title,
+                run_id=run.run_id,
+                agent_id=agent_id,
+                evidence=evidence,
+                metrics={"count": count},
+                rule_id=None,
+                finding_id=make_finding_id(
+                    run.run_id, ID, agent_id, evidence[0] if evidence else None
+                ),
+            )
+        ]
+
+
+DETECTOR: Detector = ClassifierUnavailable()

agent_postmortem/detectors/codex_unavailable.py

@@ -0,0 +1,102 @@
+"""Detects a Codex companion call that could not start.
+
+DESIGN.md 4.3, 4.13.2, 4.13.4: one finding per attempt that holds at least one anchored,
+not-in-payload `codex_unavailable` MarkerHit (the main thread of a session included, its finding
+carrying no agent id). The marker's only permitted shape is a Bash tool_result whose command runs
+codex as a program or names codex-companion.mjs, and its predicate needs a line that starts with
+the companion's own sentence, so assistant prose and the output of a non-codex command (a `cat` of
+a notes file) never count.
+
+Severity goes through severity.py: major when the attempt's outcome is `completed` (it returned a
+result though its Codex call never started) and no companion call after the first failing one has
+a result without the marker; minor otherwise (a later call succeeded, or the attempt was killed or
+failed, which other findings carry). The title is a fixed sentence and carries no transcript text.
+A read_only_output event is skipped, as for codex_write_denied.
+"""
+
+from __future__ import annotations
+
+from .. import severity as severity_rules
+from ..models import Attempt, Event, Finding, Run
+from .base import (
+    KINDS_BOTH,
+    Detector,
+    anchored_marker_hits,
+    event_for_marker_hit,
+    evidence_line,
+    make_finding_id,
+    tooling_attempts,
+)
+
+ID = "codex_unavailable"
+SEVERITY = "major"
+RULE_ID = "R-CODEX-CONTRACT"
+
+
+def _attempt_hits(attempt: Attempt) -> list[tuple[Event, str]]:
+    """(event, tool_use_id) of every counted hit, in transcript order."""
+    ordered = sorted(
+        anchored_marker_hits(attempt, ID), key=lambda hit: (hit.event_line, hit.tool_use_id or ""),
+    )
+    found: list[tuple[Event, str]] = []
+    for hit in ordered:
+        event = event_for_marker_hit(attempt, hit)
+        if event is None or event.read_only_output or hit.tool_use_id is None:
+            continue
+        found.append((event, hit.tool_use_id))
+    return found
+
+
+def _later_success(attempt: Attempt, hits: list[tuple[Event, str]]) -> bool:
+    """Whether a Bash companion call after the first failing one has a result without the
+    marker."""
+    failed_ids = {tool_use_id for _event, tool_use_id in hits}
+    first = next((c for c in attempt.tool_calls if c.tool_use_id == hits[0][1]), None)
+    if first is None:
+        return False
+    for call in attempt.tool_calls:
+        if call.tool_name != "Bash" or call.line_no <= first.line_no:
+            continue
+        if not call.runs_codex_program:
+            continue
+        if call.result_line is not None and call.tool_use_id not in failed_ids:
+            return True
+    return False
+
+
+class CodexUnavailable:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_BOTH
+
+    def run(self, run: Run) -> list[Finding]:
+        findings: list[Finding] = []
+        for attempt in tooling_attempts(run):
+            hits = _attempt_hits(attempt)
+            if not hits:
+                continue
+            count = len(hits)
+            evidence = [evidence_line(run, event) for event, _id in hits]
+            agent_id = None if attempt is run.main else attempt.agent_id
+            findings.append(Finding(
+                detector=ID,
+                severity=severity_rules.resolve(
+                    run, ID,
+                    outcome="completed" if attempt.outcome == "completed" else "other",
+                    later_success="yes" if _later_success(attempt, hits) else "no",
+                ),
+                title=(
+                    f"{count} Codex companion {'call' if count == 1 else 'calls'} could not "
+                    "start: the Codex CLI is missing or lacks its runtime"
+                ),
+                run_id=run.run_id,
+                agent_id=agent_id,
+                evidence=evidence,
+                metrics={"count": count},
+                rule_id=RULE_ID,
+                finding_id=make_finding_id(run.run_id, ID, agent_id, evidence[0]),
+            ))
+        return findings
+
+
+DETECTOR: Detector = CodexUnavailable()

agent_postmortem/detectors/codex_write_denied.py

@@ -0,0 +1,100 @@
+"""Detects a Codex sandbox denying a write, or the workspace shell guard
+blocking a command outright.
+
+DESIGN.md 4.3, 4.13.4: minor severity, one finding per attempt, fires on every
+anchored, not-in-payload 'sandbox_write_denied' or 'shell_guard_block'
+MarkerHit (docs/DESIGN.md 4.13.2). The registry's own permitted shapes
+already encode what D-C used to check by hand: 'sandbox_write_denied' only
+ever anchors on a Bash tool_result whose own command runs codex as a program,
+or an assistant entry's own whole text when the attempt also has such a Bash
+call anywhere in it; 'shell_guard_block' only ever anchors on that same
+Bash-codex tool_result shape. A `user` event is never a permitted shape for
+either id (D-B): a review or spec pasted into a prompt that happens to quote
+WRITE_DENIED is not a sandbox denying anything.
+
+A denial alone does not show that a required write was blocked (when a
+required output is really missing, missing_artifact or claim_contradiction
+carries the severity), so the finding is always minor and carries both rules
+in one `rule_ids`: R-CODEX-CONTRACT first, then R-ASSERT-ARTIFACT. metrics:
+count, marker (the distinct marker labels matched), both per attempt.
+
+Skips a read_only_output event (docs/DESIGN.md 4.3's self-reference rule): a
+read-only Bash command (including one buried in a loop, D-B) quoting
+WRITE_DENIED or the shell-guard sentence from a file on disk is not a denial
+that happened to this agent.
+"""
+
+from __future__ import annotations
+
+from .. import severity as severity_rules
+from ..models import Attempt, Event, Finding, MarkerHit, Run
+from .base import (
+    KINDS_BOTH,
+    Detector,
+    anchored_marker_hits,
+    event_for_marker_hit,
+    evidence_line,
+    make_finding_id,
+    tooling_attempts,
+)
+
+ID = "codex_write_denied"
+SEVERITY = "minor"
+RULE_ID_DENIAL = "R-CODEX-CONTRACT"
+RULE_ID_ARTIFACT = "R-ASSERT-ARTIFACT"
+RULE_IDS = (RULE_ID_DENIAL, RULE_ID_ARTIFACT)
+_MARKER_IDS = ("sandbox_write_denied", "shell_guard_block")
+
+
+def _attempt_hits(attempt: Attempt) -> list[tuple[Event, str]]:
+    """(event, marker label) pairs for this attempt, in transcript order
+    (by event_line, then tool_use_id for a stable tie-break between two
+    tool_result blocks sharing a line)."""
+    candidates: list[tuple[int, str, MarkerHit]] = []
+    for marker in _MARKER_IDS:
+        for hit in anchored_marker_hits(attempt, marker):
+            candidates.append((hit.event_line, hit.tool_use_id or "", hit))
+    candidates.sort(key=lambda row: (row[0], row[1]))
+
+    hits: list[tuple[Event, str]] = []
+    for _line, _tie, hit in candidates:
+        event = event_for_marker_hit(attempt, hit)
+        if event is None or event.read_only_output:
+            continue
+        hits.append((event, hit.marker))
+    return hits
+
+
+class CodexWriteDenied:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_BOTH
+
+    def run(self, run: Run) -> list[Finding]:
+        findings: list[Finding] = []
+        for attempt in tooling_attempts(run):
+            hits = _attempt_hits(attempt)
+            if not hits:
+                continue
+            count = len(hits)
+            markers = sorted({marker for _, marker in hits})
+            evidence = [evidence_line(run, event) for event, _ in hits]
+            plural = "s" if count != 1 else ""
+            findings.append(Finding(
+                detector=ID,
+                severity=severity_rules.resolve(run, ID),
+                title=f"{count} sandboxed write{plural} denied",
+                run_id=run.run_id,
+                agent_id=attempt.agent_id,
+                evidence=evidence,
+                metrics={"count": count, "marker": markers},
+                rule_id=RULE_IDS[0],
+                rule_ids=RULE_IDS,
+                finding_id=make_finding_id(
+                    run.run_id, ID, attempt.agent_id, evidence[0] if evidence else None
+                ),
+            ))
+        return findings
+
+
+DETECTOR: Detector = CodexWriteDenied()