agent-postmortem 0.3.4__py3-none-any.whl

agent_postmortem/detectors/attempt_failed.py

@@ -0,0 +1,261 @@
+"""attempt_failed: names the cause of a workflow attempt the journal closed
+with a `failed` event (.reviews/proposals/2026-09-v0.2-guided-rescue.md
+section 4.2). The cause is read from exactly one place: the attempt's own
+last transcript entry (not counting trailing attachment entries), never a
+wider window and never a user-authored prompt -- a fixture whose prompt
+merely mentions "API Error" must still come back unattributed
+(tests/fixtures/runs/attempt_failed_causes's af-decoy key, docs/DESIGN.md 4.3's disposition N6).
+docs/DESIGN.md 4.13.2 (v0.3 N1): the four runtime-cause markers and the kill sentinel are read as
+anchored, not-in-payload MarkerHits on the attempt's own last event, never
+Event.text.startswith directly -- the registry's own permitted shapes
+already restrict these ids to the attempt's final transcript entry (the
+four causes) or a user entry (the sentinel), so an anchored hit there is, by
+construction, on the last event whenever the last event itself carries one.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .. import severity as severity_rules
+from ..markers import USAGE_LIMIT_SESSION, USAGE_LIMIT_WEEKLY
+from ..models import Attempt, Event, Finding, Run
+from .base import (
+    KINDS_BOTH,
+    Detector,
+    anchored_marker_hits,
+    evidence_line,
+    final_event,
+    make_finding_id,
+    relative_path,
+)
+
+ID = "attempt_failed"
+SEVERITY = "major"  # the highest row; the real severity comes from the `recovered` input
+RULE_ID_USAGE_LIMIT = "R-USAGE-LIMIT"
+
+_RESET_TIME_LIMIT = 40
+# F3: a reset time is kept only from characters in this set (stripped of
+# anything else) -- an untrusted remainder past the marker should never let
+# an arbitrary character ride into the title or exported metrics.
+# What a reset time may contain: digits, letters, ":", ".", ",", " ", and
+# the "/", "_", "(", ")" a zone name such as "(America/Los_Angeles)" needs.
+_RESET_TIME_DISALLOWED_RE = re.compile(r"[^0-9A-Za-z:., /_()-]")
+
+
+def _clean_reset_time(remainder: str) -> str:
+    return _RESET_TIME_DISALLOWED_RE.sub("", remainder).strip()[:_RESET_TIME_LIMIT]
+
+# (canonical marker id, title phrase, retry_now) -- one row per
+# runtime-produced marker a `failed` attempt's last transcript entry can
+# carry (docs/DESIGN.md 4.3, 4.13.2). Order does not matter: the four ids
+# are mutually exclusive by construction (each anchors on a distinct,
+# non-overlapping prefix of the same final entry).
+_CAUSE_TABLE: tuple[tuple[str, str, str], ...] = (
+    ("usage_limit_session", "session usage limit reached", "no"),
+    ("usage_limit_weekly", "weekly usage limit reached", "no"),
+    ("machine_sleep", "the machine went to sleep", "yes"),
+    ("api_error", "a server error occurred", "yes"),
+)
+
+# The two usage-limit markers alone carry a reset time after the fixed
+# prefix; machine_sleep and api_error do not.
+_RESET_TIME_FRAGMENTS = {
+    "usage_limit_session": USAGE_LIMIT_SESSION[0],
+    "usage_limit_weekly": USAGE_LIMIT_WEEKLY[0],
+}
+
+
+def _anchored_on_event(attempt: Attempt, marker: str, event: Event) -> bool:
+    """Whether attempt carries an anchored, not-in-payload MarkerHit for
+    marker whose event_line is event's own line (docs/DESIGN.md 4.13.2)."""
+    return any(hit.event_line == event.line_no for hit in anchored_marker_hits(attempt, marker))
+
+
+def _cause_from_last_event(attempt: Attempt, event: Event) -> tuple[str, str, str | None] | None:
+    """(cause, title phrase, reset_time) from the caller's own last
+    transcript entry, checked only there, never anywhere else (docs/
+    DESIGN.md 4.3): the registry's final_assistant_entry shape already
+    restricts usage_limit_session/weekly, machine_sleep, and api_error to
+    exactly this entry, so an anchored hit for one of them is never
+    misattributed to a marker merely quoted inside ordinary prose elsewhere.
+    Returns None when none of the four ids anchor there."""
+    for marker, phrase, _retry in _CAUSE_TABLE:
+        if not _anchored_on_event(attempt, marker, event):
+            continue
+        reset_time = None
+        fragment = _RESET_TIME_FRAGMENTS.get(marker)
+        # docs/DESIGN.md 4.13.2: the anchored check this loop just passed is
+        # computed on the flattened text after leading whitespace is
+        # stripped; the reset-time extraction must read the same stripped
+        # text, not the raw excerpt, so the two can never disagree about
+        # where the fragment starts.
+        stripped_text = event.text.lstrip(" \t\r\n")
+        if fragment is not None and stripped_text.startswith(fragment):
+            remainder = stripped_text[len(fragment):]
+            reset_time = _clean_reset_time(remainder) or None
+            if reset_time:
+                phrase = f"{phrase}, resets {reset_time}"
+        return marker, phrase, reset_time
+    return None
+
+
+def _retry_now_for(cause: str) -> str:
+    """'no' for both usage limits, 'yes' for machine_sleep and api_error,
+    'unknown' for interrupted and unattributed (docs/DESIGN.md 4.3)."""
+    for table_cause, _phrase, retry_now in _CAUSE_TABLE:
+        if table_cause == cause:
+            return retry_now
+    return "unknown"
+
+
+# F4: the three tails docs/DESIGN.md 4.3 distinguishes, keyed by
+# (a later attempt exists, one of them completed).
+_TAIL_NOT_RETRIED = "the key was not retried"
+_TAIL_RETRIED_INCOMPLETE = "retried, no later attempt completed"
+_TAIL_RETRIED_COMPLETED = "a later attempt completed"
+
+
+def _retry_outcome(run: Run, attempt: Attempt) -> tuple[str, str]:
+    """(tail phrase, severity) for attempt's title (docs/DESIGN.md 4.3, 4.13.4).
+    The severity comes from the `recovered` input; the tail reads the same input,
+    so the two cannot disagree: no later attempt for the key at all ("the key was
+    not retried"); a later attempt exists but none was closed with a result
+    ("retried, no later attempt completed" -- a `failed, started, failed` and a
+    `failed, started` (still open) sequence both land here); a later attempt was
+    closed with a result ("a later attempt completed"). "Later" means a higher
+    ordinal of the same key."""
+    recovered = severity_rules.recovered(run, attempt, include_self=False)
+    severity = severity_rules.resolve(run, ID, recovered=recovered)
+    has_later = attempt.key is not None and any(
+        sibling.key == attempt.key and sibling.ordinal > attempt.ordinal
+        for sibling in run.attempts
+    )
+    if not has_later:
+        return _TAIL_NOT_RETRIED, severity
+    if recovered == "yes":
+        return _TAIL_RETRIED_COMPLETED, severity
+    return _TAIL_RETRIED_INCOMPLETE, severity
+
+
+class AttemptFailed:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_BOTH
+
+    def run(self, run: Run) -> list[Finding]:
+        findings: list[Finding] = []
+
+        if run.kind == "session":
+            return self._session_findings(run)
+
+        for attempt in run.attempts:
+            if attempt.outcome != "failed":
+                continue
+
+            # docs/DESIGN.md 4.13.2: trailing attachment entries do not count as the
+            # attempt's final entry (the reader's marker shape skips them the same way).
+            last_event = final_event(attempt.events)
+            cause = "unattributed"
+            phrase: str | None = None
+            reset_time: str | None = None
+
+            if last_event is not None:
+                if last_event.kind == "user" and _anchored_on_event(
+                    attempt, "kill_sentinel", last_event
+                ):
+                    cause = "interrupted"
+                    phrase = "interrupted before finishing"
+                elif last_event.kind == "assistant":
+                    matched = _cause_from_last_event(attempt, last_event)
+                    if matched is not None:
+                        cause, phrase, reset_time = matched
+
+            retry_now = _retry_now_for(cause)
+            tail, severity = _retry_outcome(run, attempt)
+
+            if cause == "unattributed":
+                title = (
+                    f"{attempt.label} attempt {attempt.ordinal} failed, "
+                    f"cause not recorded in the transcript; {tail}"
+                )
+            else:
+                title = f"{attempt.label} attempt {attempt.ordinal} failed: {phrase}; {tail}"
+
+            evidence = [evidence_line(run, last_event)] if last_event is not None else []
+            rule_id = (
+                RULE_ID_USAGE_LIMIT
+                if cause in ("usage_limit_session", "usage_limit_weekly")
+                else None
+            )
+
+            findings.append(
+                Finding(
+                    detector=ID,
+                    severity=severity,
+                    title=title,
+                    run_id=run.run_id,
+                    agent_id=attempt.agent_id,
+                    evidence=evidence,
+                    metrics={"cause": cause, "retry_now": retry_now, "reset_time": reset_time},
+                    rule_id=rule_id,
+                    finding_id=make_finding_id(
+                        run.run_id, ID, attempt.agent_id, evidence[0] if evidence else None
+                    ),
+                )
+            )
+
+        return findings
+
+
+    def _session_findings(self, run: Run) -> list[Finding]:
+        """docs/DESIGN.md 4.3 (G1c, v0.3.1): one major finding per session subagent whose
+        `return_state` is `reported_failed`; `reported_killed` adds none. The cause names what
+        decided it (a synchronous launch result or a task notification), the retry advice is
+        unknown, and the severity is the table's row for `recovered=unknown`."""
+        findings: list[Finding] = []
+        for attempt in run.attempts:
+            if attempt.return_state != "reported_failed" or attempt.return_evidence is None:
+                continue
+            source, path, line = attempt.return_evidence
+            cause = (
+                "launch_result_failed" if source == "launch_result" else "task_notification_failed"
+            )
+            phrase = _SESSION_CAUSE_PHRASES[cause]
+            event = next(
+                (
+                    candidate
+                    for holder in (run.main, *run.attempts) if holder is not None
+                    for candidate in holder.events
+                    if candidate.path == path and candidate.line_no == line
+                ),
+                None,
+            )
+            pointer = (
+                evidence_line(run, event) if event is not None
+                else f"{relative_path(run, path)}:{line}"
+            )
+            severity = severity_rules.resolve(run, ID, recovered="unknown")
+            title = f"{attempt.label or 'subagent'} failed: {phrase}"
+            findings.append(
+                Finding(
+                    detector=ID,
+                    severity=severity,
+                    title=title,
+                    run_id=run.run_id,
+                    agent_id=attempt.agent_id,
+                    evidence=[pointer],
+                    metrics={"cause": cause, "retry_now": "unknown", "reset_time": None},
+                    rule_id=None,
+                    finding_id=make_finding_id(run.run_id, ID, attempt.agent_id, pointer),
+                )
+            )
+        return findings
+
+
+_SESSION_CAUSE_PHRASES = {
+    "launch_result_failed": "its launch result reported failure",
+    "task_notification_failed": "its task notification reported failure",
+}
+
+DETECTOR: Detector = AttemptFailed()

agent_postmortem/detectors/base.py

@@ -0,0 +1,319 @@
+"""The contract every detector module must satisfy, plus the small pieces of
+logic every detector needs and none of them owns: formatting an evidence
+line, deciding whether an event is a Bash call, and summing an attempt's
+wall-clock span. These used to be copy-pasted into every detector module;
+a fix to the evidence-format contract (docs/DESIGN.md 4.1) had as many call
+sites to update as there were detectors, and nothing caught a site that was
+missed. A detector module lives in this package and exports exactly one
+module-level instance named DETECTOR. detectors/__init__.py finds it by
+iterating the package; there is no registry list to edit by hand.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol
+
+from ..models import Attempt, Event, Finding, MarkerHit, Run
+
+# docs/DESIGN.md 4.4: how close a parent-transcript TaskStop or kill sentinel
+# has to land to a child's own kill timestamp to count as evidence of that
+# cause, rather than coincidence. 30s comfortably covers both of the two
+# sources of slop between two files written by two different processes: the
+# runtime buffers transcript writes rather than fsyncing per line, and
+# timestamps are only as fine-grained as the clock the two writers share.
+# Kept as two named constants, not one, because 4.4 evaluates them against
+# different things (a TaskStop's timestamp vs. a second file's own kill
+# sentinel) and a future revision may need to tune them independently.
+PARENT_STOP_WINDOW_SECONDS = 30
+PARENT_SENTINEL_WINDOW_SECONDS = 30
+
+# docs/DESIGN.md 4.3: which run kinds a detector applies to. silent_retry is
+# workflow-only (a session's subagents are never retried in a way v0.1 can
+# observe -- 4.3's own note); every other detector applies to both kinds.
+KINDS_WORKFLOW_ONLY: frozenset[str] = frozenset({"workflow"})
+KINDS_BOTH: frozenset[str] = frozenset({"workflow", "session"})
+
+
+class Detector(Protocol):
+    id: str
+    severity_default: str
+    kinds: frozenset[str]  # run kinds this detector applies to (4.3)
+
+    def run(self, run: Run) -> list[Finding]:
+        """Inspect one Run and return zero or more Findings."""
+        ...
+
+
+def tooling_attempts(run: Run) -> list[Attempt]:
+    """The attempts a tooling detector must scan (docs/DESIGN.md 4.3): a
+    session's own main thread first (it is where a session's -p invocation
+    and its own tool calls live, and it is excluded from run.attempts by
+    design -- see models.Run), then every child attempt. A workflow run has
+    no main, so this is just run.attempts for one.
+
+    The seven tooling detectors (bash_backgrounded, bash_timeout,
+    tool_json_error, structured_output_failure, codex_write_denied,
+    classifier_unavailable, git_cwd_mismatch) all use this instead of
+    iterating run.attempts directly, so a marker in a session's main thread
+    is never silently invisible to them. mislabeled_kill and missing_artifact
+    stay on run.attempts only: a session's main-thread interrupt is not
+    attributable (4.3's own documented limit) and a session has no
+    'first user event' of the kind missing_artifact looks for."""
+    attempts = [run.main] if run.main is not None else []
+    attempts.extend(run.attempts)
+    return attempts
+
+
+def relative_path(run: Run, path: Path) -> str:
+    """path relative to run.path, or just its name if it is not underneath
+    (for example a transcript from a fixture loaded by a bare, non-standard
+    path) or is run.path itself -- a session's cause_evidence (docs/DESIGN.md
+    4.4) can point at the main transcript, and for a session run.path is
+    that same file, so a literal relative_to would collapse to '.', not a
+    path a reader could use at all."""
+    try:
+        relative = path.relative_to(run.path)
+    except ValueError:
+        return path.name
+    return str(relative) if str(relative) != "." else path.name
+
+
+def evidence_line(run: Run, event: Event, limit: int = 160) -> str:
+    """'relative/path:line: excerpt' (<=160 chars), the evidence format
+    docs/DESIGN.md 4.1 requires of every Finding."""
+    excerpt = " ".join(event.text.split())[:limit]
+    return f"{relative_path(run, event.path)}:{event.line_no}: {excerpt}"
+
+
+def make_finding_id(
+    run_id: str, detector: str, agent_id: str | None, first_evidence: str | None,
+) -> str:
+    """sha256(run_id, detector, agent_id, first evidence path:line)[:12]
+    (docs/DESIGN.md 4.1). first_evidence is a full 'path:line: excerpt'
+    evidence line, or None; only its 'path:line' prefix goes into the hash,
+    so a later change to excerpt wording or truncation does not change a
+    finding's identity. Every detector module calls this to fill
+    Finding.finding_id; nothing else computes one."""
+    path_line = (first_evidence or "").split(": ", 1)[0]
+    payload = "\x1f".join((run_id, detector, agent_id or "", path_line))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:12]
+
+
+def single_agent_id(agent_ids) -> str | None:
+    """The agent id when every hit of a run-wide tooling finding belongs to
+    the one agent, else None (docs/DESIGN.md 4.3, 4.7): a finding that counts
+    hits across several agents is not any one agent's story."""
+    distinct = set(agent_ids)
+    return distinct.pop() if len(distinct) == 1 else None
+
+
+def anchored_marker_hits(attempt: Attempt, marker: str) -> list[MarkerHit]:
+    """Every MarkerHit on attempt with this canonical id that is anchored
+    and not in_payload (docs/DESIGN.md 4.13.2): the only hits a detector may
+    ever treat as evidence. A detector never reads Event.markers directly
+    (kept only for compatibility); it reads Attempt.marker_hits through this
+    helper instead."""
+    return [
+        hit for hit in attempt.marker_hits
+        if hit.marker == marker and hit.anchored and not hit.in_payload
+    ]
+
+
+def event_for_marker_hit(attempt: Attempt, hit: MarkerHit) -> Event | None:
+    """The Event a MarkerHit was built from (docs/DESIGN.md 4.13.2): matched
+    by (line_no, tool_use_id) for a tool_result shape -- a single user entry
+    can carry more than one tool_result block on the same physical line, so
+    line_no alone cannot disambiguate them -- or by line_no plus kind for a
+    whole-entry shape (kill_sentinel, the final-assistant-entry markers,
+    sandbox_write_denied's assistant form), where the first matching 'user'
+    or 'assistant' event is the one the hit's own entry-level flattening
+    rule reads from (its first text block)."""
+    if hit.tool_use_id is not None:
+        for event in attempt.events:
+            if event.line_no == hit.event_line and event.tool_use_id == hit.tool_use_id:
+                return event
+        return None
+    for event in attempt.events:
+        if event.line_no == hit.event_line and event.kind in ("user", "assistant"):
+            return event
+    return None
+
+
+def is_bash_event(event: Event) -> bool:
+    """A tool_result the reader resolved to the Bash tool. A generic
+    substring match on an attachment's text (a hook result, not necessarily
+    tied to Bash at all) is not reliable evidence of a Bash call."""
+    return event.kind == "tool_result" and event.tool_name == "Bash"
+
+
+_COMMAND_EXCERPT_LIMIT = 160
+
+
+def preceding_bash_command(attempt: Attempt, index: int) -> str:
+    """The command text of the Bash tool_use immediately before
+    attempt.events[index], or "" if none is found. Shared by
+    bash_backgrounded (which quotes it, redacted, in a finding's metrics)
+    and codex_write_denied (docs/DESIGN.md 4.3's D-C: a marker only counts
+    on a Bash tool_result whose own command mentions "codex")."""
+    for event in reversed(attempt.events[:index]):
+        if event.kind == "tool_use" and event.tool_name == "Bash":
+            try:
+                data = json.loads(event.text)
+            except (json.JSONDecodeError, TypeError, ValueError, RecursionError):
+                return event.text[:_COMMAND_EXCERPT_LIMIT]
+            command = data.get("command") if isinstance(data, dict) else None
+            return command if isinstance(command, str) else event.text[:_COMMAND_EXCERPT_LIMIT]
+    return ""
+
+
+def attempt_seconds(attempt: Attempt) -> float:
+    """An attempt's wall-clock span, or 0.0 if either endpoint is unknown."""
+    if attempt.first_ts is None or attempt.last_ts is None:
+        return 0.0
+    return max((attempt.last_ts - attempt.first_ts).total_seconds(), 0.0)
+
+
+# docs/DESIGN.md 4.3 (FA5): the outcomes of an attempt that ended without a result.
+NO_RESULT_OUTCOMES = frozenset({"killed", "failed", "superseded"})
+
+
+def wasted_attempts(attempts: list[Attempt]) -> list[Attempt]:
+    """The attempts of ONE logical agent whose wall-clock is wasted (docs/DESIGN.md
+    4.3, FA5), each once: every attempt but the last (a retry, whatever its
+    outcome) plus the last one when its outcome is killed, failed, or superseded.
+    An open final attempt that may still be running is not counted (its outcome
+    is completed or unknown)."""
+    ordered = sorted(attempts, key=lambda attempt: attempt.ordinal)
+    if not ordered:
+        return []
+    final = ordered[-1]
+    wasted = ordered[:-1]
+    if final.outcome in NO_RESULT_OUTCOMES:
+        wasted.append(final)
+    return wasted
+
+
+def run_wasted_attempts(run: Run) -> list[Attempt]:
+    """wasted_attempts over every logical agent of the run, in agent order."""
+    return [attempt for agent in run.agents for attempt in wasted_attempts(agent.attempts)]
+
+
+def format_duration(seconds: float) -> str:
+    """2h13m for an hour or more, 41m for a minute or more, else 58s."""
+    total = max(int(round(seconds)), 0)
+    hours, remainder = divmod(total, 3600)
+    minutes, secs = divmod(remainder, 60)
+    if hours:
+        return f"{hours}h{minutes:02d}m"
+    if minutes:
+        return f"{minutes}m"
+    return f"{secs}s"
+
+
+def final_event(events: Sequence[Event]) -> Event | None:
+    """The last event whose raw_type is not exactly "attachment" (docs/DESIGN.md
+    4.13.2). Shared by attempt_failed and watch so both read one cause source."""
+    return next((ev for ev in reversed(events) if ev.raw_type != "attachment"), None)
+
+
+def meaningful_event_before(attempt: Attempt, index: int) -> Event | None:
+    """The last event before attempt.events[index] worth calling "preceding"
+    (docs/DESIGN.md 4.5): a reader.py-and-detector-shared notion of evidence
+    quality, not just reader.py's own interrupt-building.
+
+    Walks backward skipping 'thinking' and 'attachment' events and any event
+    whose text is empty once harness noise has been stripped (reader.py
+    strips <system-reminder>, <total_tokens>, and [harness: ...] spans before
+    an Event's text is set, so this is a plain emptiness check here, not a
+    second strip). A 'compaction' event stops the walk outright and this
+    returns None: a context reset makes whatever came before it not
+    "preceding" in any sense a caller can use (silence across a compaction is
+    not silence, and evidence from before one is not evidence of what
+    happened after)."""
+    for i in range(index - 1, -1, -1):
+        event = attempt.events[i]
+        if event.kind == "compaction":
+            return None
+        if event.kind in ("thinking", "attachment"):
+            continue
+        if not event.text.strip():
+            continue
+        return event
+    return None
+
+
+def _task_stop_matches(attempt: Attempt, task_stop, kill_ts) -> bool:
+    """docs/DESIGN.md 4.4 clause 1: named directly, or landing within
+    PARENT_STOP_WINDOW_SECONDS before the kill (a TaskStop with no timestamp
+    of its own can still match by name, just never by window)."""
+    if attempt.agent_id in task_stop.ids:
+        return True
+    if task_stop.ts is None or kill_ts is None:
+        return False
+    delta = (kill_ts - task_stop.ts).total_seconds()
+    return 0 <= delta <= PARENT_STOP_WINDOW_SECONDS
+
+
+def _task_stop_evidence(parent_index, task_stop) -> Event:
+    return Event(
+        path=parent_index.path, line_no=task_stop.line_no, ts=task_stop.ts,
+        kind="tool_use", raw_type="assistant", tool_name="TaskStop",
+        text=task_stop.text, exit_code=None, duration_ms=None, is_error=False,
+        usage={}, markers=frozenset(),
+    )
+
+
+def _kill_sentinel_evidence(parent_index, sentinel) -> Event:
+    return Event(
+        path=parent_index.path, line_no=sentinel.line_no, ts=sentinel.ts,
+        kind="user", raw_type="user", tool_name=None,
+        text=sentinel.text, exit_code=None, duration_ms=None, is_error=False,
+        usage={}, markers=frozenset(),
+    )
+
+
+def attribute_interrupt(run: Run, attempt: Attempt, parent_index) -> tuple[str, Event | None]:
+    """cause and cause_evidence for attempt.interrupt, evaluated against
+    parent_index (a reader.ParentIndex; duck-typed here rather than imported,
+    since reader.py imports this module) in the exact order docs/DESIGN.md
+    4.4 specifies, first match wins:
+
+    1. parent_stop: a parent TaskStop names this attempt (docs/DESIGN.md 4.2
+       flattens every string value of a TaskStop's input into `ids`, so an
+       "agent_id" or a "task_id" field both work the same way here), or any
+       TaskStop lands within PARENT_STOP_WINDOW_SECONDS before the kill.
+    2. human: a parent kill sentinel lands within
+       PARENT_SENTINEL_WINDOW_SECONDS of the kill, either side (the owner's
+       Escape and the child's own kill timestamp are two different files'
+       clocks, not a strict before/after).
+    3. runtime: workflow kind only, and this attempt's key has a later
+       attempt -- the restart itself is affirmative evidence the runtime
+       killed and replaced it, never conjecture.
+    4. unattributed: everything else.
+
+    Returns (cause, cause_evidence); cause_evidence is only ever set for
+    parent_stop and human (docs/DESIGN.md 4.1's Interrupt.cause_evidence)."""
+    interrupt = attempt.interrupt
+    kill_ts = interrupt.kill_ts if interrupt is not None else None
+
+    for task_stop in parent_index.task_stops:
+        if _task_stop_matches(attempt, task_stop, kill_ts):
+            return "parent_stop", _task_stop_evidence(parent_index, task_stop)
+
+    if kill_ts is not None:
+        for sentinel in parent_index.kill_sentinels:
+            if sentinel.ts is None:
+                continue
+            if abs((kill_ts - sentinel.ts).total_seconds()) <= PARENT_SENTINEL_WINDOW_SECONDS:
+                return "human", _kill_sentinel_evidence(parent_index, sentinel)
+
+    if run.kind == "workflow" and attempt.key is not None:
+        siblings = run.attempts
+        if any(s.ordinal > attempt.ordinal for s in siblings if s.key == attempt.key):
+            return "runtime", None
+
+    return "unattributed", None

agent_postmortem/detectors/bash_backgrounded.py

@@ -0,0 +1,72 @@
+"""Detects a Bash command the runtime moved to the background after its timeout.
+
+DESIGN.md 4.3: minor severity, fires on every anchored, not-in-payload
+'bash_backgrounded' MarkerHit (docs/DESIGN.md 4.13.2: the registry's own
+predicate already requires both BASH_BACKGROUNDED fragments, line1-anchored,
+on a tool_result paired to Bash). metrics: count only (docs/DESIGN.md 5.3's
+D3: the evidence lines already show the marker line the detector fired on;
+a finding's metrics never carries a second copy of transcript-derived free
+text alongside them). rule_id: R-NO-LONG-BASH. Never consults
+Event.read_only_output (docs/DESIGN.md 4.3: a timed-out `cat` is still a
+timed-out command).
+"""
+
+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,
+    single_agent_id,
+    tooling_attempts,
+)
+
+ID = "bash_backgrounded"
+SEVERITY = "minor"
+RULE_ID = "R-NO-LONG-BASH"
+
+
+class BashBackgrounded:
+    id = ID
+    severity_default = SEVERITY
+    kinds = KINDS_BOTH
+
+    def run(self, run: Run) -> list[Finding]:
+        hits: list[tuple[Attempt, Event]] = []
+        for attempt in tooling_attempts(run):
+            for hit in anchored_marker_hits(attempt, ID):
+                event = event_for_marker_hit(attempt, hit)
+                if event is not None:
+                    hits.append((attempt, event))
+        if not hits:
+            return []
+
+        count = len(hits)
+        evidence = [evidence_line(run, event) for _, event in hits]
+        plural = "s" if count != 1 else ""
+        title = f"{count} Bash command{plural} timed out and moved to the background"
+
+        agent_id = single_agent_id(attempt.agent_id for attempt, _ 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 = BashBackgrounded()