stacktrace-cli 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
 """The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

stacktrace_cli/analysis.py

@@ -19,11 +19,12 @@ path's tests already pin.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Iterator
 from dataclasses import dataclass, replace
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
-from typing import Any
+from typing import Any, Final
 
 from stacktrace_cli.correlate.orchestrate import Acquired, acquire_correlated_view
 from stacktrace_cli.correlate.project_map import parse_mapping
@@ -63,25 +64,55 @@ class Analysis:
     placed: bool = True
 
 
+#: A count and an optional unit, anchored. Anchored rather than searched
+#: because the tolerance this parser owes the upload path is about the *unit*
+#: being omissible, not about the value being loosely shaped: `int` alone would
+#: read `'5 m'` as five (it strips whitespace before parsing) and a signed
+#: `'-1h'` as a negative window, so the shape is pinned here and the count is
+#: parsed from digits already known to be digits.
+_SINCE_SPELLING: Final = re.compile(r"^(\d+)([mhd]?)$")
+
+#: The unit suffixes, and the `timedelta` keyword each one names. The empty
+#: key is the bare count -- `'7'`, which the upload path's config value has
+#: always spelled without a unit and which has always meant days.
+_SINCE_UNITS: Final = {"m": "minutes", "h": "hours", "d": "days", "": "days"}
+
+#: One message for every way the spelling can be wrong, because they are one
+#: user mistake: a window that does not name a positive amount of time. Shared
+#: with `cli.py`'s stricter parser so a reader meets the same vocabulary
+#: whichever of the two refused them.
+SINCE_HINT: Final = "like '5m', '2h' or '7d'"
+
+
 def parse_since(value: str) -> datetime:
-    """`7d` or `7` -> an aware UTC cut-off.
+    """`5m`, `2h`, `7d` or `7` -> an aware UTC cut-off.
+
+    Sub-day units are here rather than only at the command line because the
+    window reaches this module as a *string* from every caller that has one --
+    `monitor` hands it over untouched and parses it on the watcher thread, so a
+    unit the command line accepted and this parser did not would raise where no
+    request is left to answer.
 
     Raises `ValueError`, never a Click or transport exception: this module is
     below both. The message is the upload path's, which its tests pin.
     """
-    text = value.strip().lower()
+    match = _SINCE_SPELLING.match(value.strip().lower())
+    if not match:
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}")
     try:
-        days = int(text[:-1]) if text.endswith("d") else int(text)
+        count = int(match.group(1))
     except ValueError:
-        raise ValueError(f"--since must be a positive day count, not {value!r}") from None
-    if days <= 0:
-        raise ValueError(f"--since must be a positive day count, not {value!r}")
+        # `int` refuses a string past its default digit-conversion limit. The
+        # same user mistake as a non-numeric value, so the same diagnostic.
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}") from None
+    if count <= 0:
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}")
     try:
-        return datetime.now(UTC) - timedelta(days=days)
+        return datetime.now(UTC) - timedelta(**{_SINCE_UNITS[match.group(2)]: count})
     except OverflowError:
         # `timedelta` takes any `int` but overflows past `timedelta.max.days`.
         # The same user mistake as a non-numeric value, so the same diagnostic.
-        raise ValueError(f"--since must be a positive day count, not {value!r}") from None
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}") from None
 
 
 def _only(

stacktrace_cli/cli.py

@@ -24,7 +24,7 @@ from typing import Final
 import click
 from openaca.cli import main as openaca_cli
 
-from .analysis import analyse, parse_since
+from .analysis import _SINCE_UNITS, SINCE_HINT, analyse, parse_since
 from .build import version_label
 from .daemon.cli import daemon as daemon_cmd
 from .daemon.cli import findings
@@ -45,15 +45,33 @@ PASSTHROUGH: Final = ("scan", "bom", "policy")
 
 HOMEPAGE = "https://stacktrace.ai"
 
-_SINCE_PATTERN = re.compile(r"^(\d+)d$")
+#: The unit is required here and optional in `analysis.parse_since`. That is
+#: the whole of the difference between the two spellings, and it is deliberate:
+#: the forgiving parser also answers the upload path, whose value comes from a
+#: config file rather than a shell, so a bare `7` has to keep meaning days
+#: there while staying a usage error here.
+_SINCE_PATTERN = re.compile(r"^(\d+)([mhd])$")
 
 
 def _parse_since(value: str) -> datetime:
-    """`14d` -> an aware UTC cut-off."""
+    """`5m`, `2h` or `14d` -> an aware UTC cut-off.
+
+    A zero count is a window that covers nothing, not a usage error: `sessions`
+    and `detect` have always read `0d` that way, and the units beside it answer
+    to the same rule. `monitor` is the one that refuses it, and it refuses it
+    through the second parser `_day_count` applies.
+    """
     match = _SINCE_PATTERN.match(value.strip())
     if not match:
-        raise click.BadParameter(f"expected a day count like '14d', got {value!r}")
-    return datetime.now(UTC) - timedelta(days=int(match.group(1)))
+        raise click.BadParameter(f"expected a window {SINCE_HINT}, got {value!r}")
+    try:
+        return datetime.now(UTC) - timedelta(**{_SINCE_UNITS[match.group(2)]: int(match.group(1))})
+    except (OverflowError, ValueError):
+        # `timedelta` takes any `int` but overflows past `timedelta.max.days`, and
+        # `int` itself refuses a string past its default digit-conversion limit.
+        # Both are the same user mistake as a non-numeric value, so the same
+        # diagnostic.
+        raise click.BadParameter(f"expected a window {SINCE_HINT}, got {value!r}") from None
 
 
 def _window_start(ctx: click.Context, param: click.Parameter, value: str) -> datetime:
@@ -202,7 +220,12 @@ def main() -> None:
     multiple=True,
     help="Only this agent kind. Repeatable. Default: every kind.",
 )
-@click.option("--since", default="14d", show_default=True, help="Window, as a day count.")
+@click.option(
+    "--since",
+    default="14d",
+    show_default=True,
+    help="Window, as a count and a unit: 5m, 2h or 14d.",
+)
 @click.option(
     "--include-content",
     is_flag=True,
@@ -254,7 +277,7 @@ def sessions(
     default="7d",
     show_default=True,
     callback=_window_start,
-    help="How far back to read.",
+    help="How far back to read, as a count and a unit: 5m, 2h or 7d.",
 )
 @click.option(
     "--bom",
@@ -461,11 +484,15 @@ def detect(
     default="3d",
     show_default=True,
     callback=_day_count,
-    help="How far back to read. Shorter than `detect`'s week deliberately: the "
-    "whole window is collected and correlated before the page can render "
-    "anything — measured at ~2.5s for a day and ~6s for a week of a busy "
-    "machine — and a live view is about what is happening rather than what "
-    "happened. Widen it when you want the history.",
+    help="How far back to read, as a count and a unit: 5m, 2h or 3d. Shorter "
+    "than `detect`'s week deliberately: the whole window is collected and "
+    "correlated before the page can render anything — measured at ~2.5s for a "
+    "day and ~6s for a week of a busy machine — and a live view is about what "
+    "is happening rather than what happened. Widen it when you want the "
+    "history; narrow it to a sub-day window when a finding from a session that "
+    "ended yesterday is noise rather than news. A window none of the page's "
+    "buttons names gets one of its own, so it stays reachable after you have "
+    "clicked away from it.",
 )
 @click.option(
     "--bom",

stacktrace_cli/daemon/cli.py

@@ -9,6 +9,7 @@ import sys
 import click
 
 from .paths import RuntimePaths
+from .presentation import render_finding
 from .store import FindingStore, SessionKey
 
 
@@ -100,7 +101,4 @@ def findings(agent_kind: str, session_id: str, output_format: str) -> None:
         click.echo("No Stacktrace findings for this session.")
         return
     for finding in stored:
-        click.echo(
-            f"{str(finding.get('severity', 'unknown')).upper()} "
-            f"{finding.get('rule_id', 'unknown-rule')}: {finding.get('title', 'Finding')}"
-        )
+        click.echo(render_finding(finding))

stacktrace_cli/daemon/presentation.py

@@ -0,0 +1,68 @@
+"""Explain durable findings without reintroducing discarded transcript prose."""
+
+from __future__ import annotations
+
+import json
+
+from stacktrace_cli.detector.blocked import REASON_CODES, reason_for
+
+# Notification prose is selected by rule ID only (ADR-0031). In particular,
+# finding titles, component names and evidence never supply notification text.
+_GUIDANCE = {
+    "stacktrace-credential-egress": (
+        "Credential-shaped material appeared in an outbound tool call",
+        (
+            "Treat the credential as potentially exposed: revoke or rotate it, "
+            "then inspect why the outbound tool received it."
+        ),
+    ),
+    "stacktrace-deceptive-completion": (
+        "A success claim conflicts with verification evidence",
+        "Inspect the cited verification results before relying on the completion claim.",
+    ),
+    "stacktrace-agent-blocked": (
+        "The agent encountered a block while working",
+        "Inspect the recorded block reason before retrying the task.",
+    ),
+}
+
+
+def rule_guidance(rule_id: str) -> tuple[str, str]:
+    return _GUIDANCE.get(
+        rule_id,
+        ("A finding was recorded", "Inspect the retained evidence in the local session."),
+    )
+
+
+def render_finding(finding: dict[str, object]) -> str:
+    """Render the old, title-less ledger as well as newly recorded findings."""
+    rule_id = str(finding.get("rule_id", "unknown-rule"))
+    title, remedy = rule_guidance(rule_id)
+    evidence = finding.get("evidence", [])
+    items = (
+        [item for item in evidence if isinstance(item, dict)] if isinstance(evidence, list) else []
+    )
+    if rule_id == "stacktrace-agent-blocked" and items:
+        code = items[0].get("kind")
+        if isinstance(code, str) and code in REASON_CODES:
+            reason = reason_for(code)
+            title, remedy = reason.title, reason.remedy
+
+    lines = [
+        f"{str(finding.get('severity', 'unknown')).upper()} {rule_id}: {title}",
+        f"  Confidence: {finding.get('confidence', 'unknown')}",
+    ]
+    for item in items:
+        # Quote stored descriptors as data, including escaped terminal controls.
+        kind = json.dumps(item.get("kind"), ensure_ascii=True)
+        detail = json.dumps(item.get("detail"), ensure_ascii=True)
+        span = json.dumps(item.get("span"), ensure_ascii=True)
+        lines.extend((f"  Evidence ({kind}): {detail}", f"    Location: {span}"))
+    if not items:
+        lines.append("  Evidence: no descriptors were retained.")
+    lines.append(f"  Next step: {remedy}")
+    lines.append(
+        "  Tool/component names and raw call content are not retained in this ledger; "
+        "inspect the cited locations in the local session for attribution."
+    )
+    return "\n".join(lines)

stacktrace_cli/daemon/store.py

@@ -17,6 +17,8 @@ from stacktrace_cli.detector.rules import scope_of
 from stacktrace_cli.private_state import ensure_private_directory
 from stacktrace_cli.telemetry import emit_derived
 
+from .presentation import rule_guidance
+
 
 @dataclass(frozen=True)
 class SessionKey:
@@ -266,10 +268,16 @@ class FindingStore:
         identity = f"{session.agent_kind}\0{session.session_id}\0{rule_id}\0{anchor}".encode()
         return f"stn_{hashlib.sha256(identity).hexdigest()[:24]}"
 
+    #: Severities that earn a notification. `Severity` is `low | medium | high`;
+    #: `critical` is carried because the gate has always tested for it, though
+    #: no rule emits it. `low` stays silent.
+    _NOTIFIABLE_SEVERITIES = frozenset({"medium", "high", "critical"})
+
     @staticmethod
     def _eligible(finding: dict[str, object]) -> bool:
         return (
-            finding.get("severity") in {"high", "critical"} and finding.get("confidence") == "high"
+            finding.get("severity") in FindingStore._NOTIFIABLE_SEVERITIES
+            and finding.get("confidence") == "high"
         )
 
     @staticmethod
@@ -302,13 +310,17 @@ class FindingStore:
         severity = finding["severity"]
         assert isinstance(rule_id, str)
         assert isinstance(severity, str)
+        explanation, _ = rule_guidance(rule_id)
         return Notification(
             event_id=event_id,
             session=session,
             rule_id=rule_id,
             severity=severity,
-            title=f"Stacktrace detected a {severity}-severity finding",
-            body=f"{rule_id} in this agent session. Run /stacktrace:findings for details.",
+            title=f"Stacktrace: {explanation}",
+            body=(
+                f"Severity: {severity}. Rule: {rule_id}. "
+                "Run /stacktrace:findings for evidence and next steps."
+            ),
         )
 
     @staticmethod

stacktrace_cli/detector/deterministic.py

@@ -276,9 +276,13 @@ def _blocked_remediation(
     if reason.terminal:
         parts.append("It holds for the rest of the session, so retrying only spends the run.")
     if repeated:
+        # How many and for how long, never between which turns. The ordinal is
+        # the detector's cursor and reads here as an address a reader could
+        # follow; the run's extent is already on the card as a clock, and the
+        # positions themselves now travel per citation as `Evidence.turn`.
         parts.append(
             f"The agent sat on it, saying the same thing {len(repeated)} times over, "
-            f"turns {repeated[0]} to {repeated[-1]}, doing no work in between."
+            f"doing no work in between."
         )
     scale = "once" if events == 1 else f"{events} times"
     parts.append(
@@ -384,7 +388,7 @@ def _agent_blocked(session: SessionLike, ref: SessionRef) -> tuple[Detection, ..
                         span=_block_span(session, turn),
                         kind=reason.code,
                         detail=_blocked_detail(
-                            f"turn {turn.position}, in a reply that made no call",
+                            "in a reply that made no call",
                             reason.specific(turn.text),
                         ),
                     )
@@ -441,7 +445,7 @@ def _agent_blocked(session: SessionLike, ref: SessionRef) -> tuple[Detection, ..
                     span=call.span,
                     kind=reason.code,
                     detail=_blocked_detail(
-                        f"{tool_name_for(call)}, turn {turn.position}",
+                        tool_name_for(call),
                         reason.specific(_block_body(call)),
                     ),
                 )

stacktrace_cli/detector/finding.py

@@ -193,6 +193,21 @@ class Evidence:
     #: none -- or where the transcript dated nothing. Attached at the same seam
     #: as the detection's range, never by a rule.
     turn_occurred_at: datetime | None = None
+    #: Which turn issued this span, as the session's own ordinal.
+    #:
+    #: **A field rather than a phrase, and that is the whole point of it.** Two
+    #: rules used to write `turn {position}` into `detail`, where it read as an
+    #: address a reader could follow. It is not one -- nothing a consumer draws
+    #: numbers turns -- and on a measured corpus the ordinals ran past a
+    #: thousand while the commonest citation on the page spent a third of its
+    #: length on one. Here it is what it actually is: the session's ordering of
+    #: its own work, for a consumer that wants to sort or to say how far in
+    #: something happened, and never prose.
+    #:
+    #: `None` where the citation resolves to no turn, on the same terms as
+    #: `turn_occurred_at` -- and set by a rule rather than at that seam, because
+    #: unlike the clock it is already in the rule's hand when it cites.
+    turn: int | None = None
 
 
 def _is_unit(value: object) -> bool:

stacktrace_cli/detector/reasoning.py

@@ -1698,16 +1698,19 @@ def _cited_call(span: str, session: SessionLike) -> tuple[str, int] | None:
 def _verdict_evidence(
     span: str, confidence: str, session: SessionLike, scores: Mapping[str, float]
 ) -> str:
-    """One row: which call, at which turn, and how sure the analyzer was.
+    """One row: which call, and how sure the analyzer was.
 
     The score is included where there is one. A windowed analyzer answers with
     a probability per span and nothing else, so it is the only quantity behind
     the grade — and a reader comparing three cited calls wants to know which of
     them the analyzer was least comfortable with.
+
+    The turn's position used to be in this sentence and is now `Evidence.turn`.
+    It reads as an address and is not one; see that field.
     """
     grade = _VERDICT_DETAIL[confidence]
     named = _cited_call(span, session)
-    where = f"{named[0]}, turn {named[1]}" if named else "a call this session made"
+    where = named[0] if named else "a call this session made"
     score = scores.get(span)
     return f"{where} — {grade}" + (f" (scored {score:.2f})" if score is not None else "")
 

stacktrace_cli/detector/render.py

@@ -139,6 +139,10 @@ def detection_json(detection) -> dict[str, object]:
                 "kind": e.kind,
                 "detail": e.detail,
                 "occurred_at": e.turn_occurred_at.isoformat() if e.turn_occurred_at else None,
+                # The position, beside the sentence rather than inside it. A
+                # consumer that wants to say how far into a session something
+                # happened reads this; `detail` stays a sentence.
+                "turn": e.turn,
             }
             for e in detection.evidence
         ],

stacktrace_cli/detector/run.py

@@ -84,7 +84,7 @@ from stacktrace_cli.detector.reasoning import (
 )
 from stacktrace_cli.detector.secrets import find_secrets
 from stacktrace_cli.sessions.index import turns_by_span
-from stacktrace_cli.sessions.protocols import ToolCallLike
+from stacktrace_cli.sessions.protocols import ToolCallLike, TurnLike
 
 #: The analyzers a run may be asked for, by the name `--analyzer` takes.
 #: `jev` is TypeSafe's Jev, a boundary the flag must name (ADR-0033).
@@ -264,11 +264,18 @@ class DetectorRun:
     analyzer: str = NO_ANALYZER
 
 
-#: A finding paired with its producing session's own span -> turn-time map.
+#: A finding paired with its producing session's own span -> turn map.
 #: The pairing is the invariant: a producer cannot add a finding to the run
-#: without saying which session's clock dates it, because the list holds no
+#: without saying which session's turns place it, because the list holds no
 #: other shape and `pyright` refuses a bare `Detection`.
-Produced = tuple[Detection, Mapping[str, datetime | None]]
+#:
+#: The turn itself rather than its time, because a citation carries two facts
+#: derived from it -- when it ran and where in the session it sat -- and two
+#: maps would be two chances for a producer to supply one and not the other.
+#: That is exactly what happened while the position was set per rule: two of
+#: the five producers never set it, and `None` stopped meaning "resolves to no
+#: turn" and started also meaning "nobody wired this site up".
+Produced = tuple[Detection, Mapping[str, TurnLike]]
 
 
 def _finish(produced: Sequence[Produced]) -> tuple[Detection, ...]:
@@ -298,9 +305,14 @@ def _finish(produced: Sequence[Produced]) -> tuple[Detection, ...]:
     range at all, which is why the two bounds are always null together.
     """
     finished: list[Detection] = []
-    for detection, times in produced:
+    for detection, turns in produced:
         evidence = tuple(
-            replace(item, turn_occurred_at=times.get(item.span)) for item in detection.evidence
+            replace(
+                item,
+                turn_occurred_at=(found := turns.get(item.span)) and found.occurred_at,
+                turn=found.position if found else None,
+            )
+            for item in detection.evidence
         )
         moments = sorted(item.turn_occurred_at for item in evidence if item.turn_occurred_at)
         finished.append(
@@ -359,7 +371,7 @@ def run_detector(
     #: does; this dict is built and drained within one `run_detector` call,
     #: over sessions `correlated.sessions` holds live throughout, so nothing
     #: here is freed and reused before the lookups that need it are done.
-    times_by_session: dict[int, dict[str, datetime | None]] = {}
+    turns_by_session: dict[int, dict[str, TurnLike]] = {}
 
     for session in correlated.sessions:
         stage_one, stage_one_unknowns = run_deterministic(session.session)
@@ -370,16 +382,12 @@ def run_detector(
         # rule that never sees the record cannot say.
         coverage = Coverage(total=session.coverage.total, resolved=session.coverage.resolved)
         index = _SessionIndex.of(session)
-        session_times = {
-            span: turn.occurred_at for span, turn in turns_by_span(session.session).items()
-        }
+        session_turns = dict(turns_by_span(session.session))
         # A narration-only block cites a span no call ever carries
         # (`block_spans_by_turn`), so it resolves to no turn here unless it is
         # added the same way a call-backed one already is.
-        session_times.update(
-            {span: turn.occurred_at for span, turn in block_spans_by_turn(session.session).items()}
-        )
-        times_by_session[id(session.session)] = session_times
+        session_turns.update(block_spans_by_turn(session.session))
+        turns_by_session[id(session.session)] = session_turns
         stage_one = tuple(
             replace(
                 d,
@@ -390,7 +398,7 @@ def run_detector(
             )
             for d in stage_one
         )
-        produced.extend((d, session_times) for d in stage_one)
+        produced.extend((d, session_turns) for d in stage_one)
         unknowns.extend(stage_one_unknowns)
 
         stage_two_unknowns, request = run_priors(session, stage_one)
@@ -554,7 +562,7 @@ def run_detector(
                 ),
             ):
                 produced.extend(
-                    (d, times_by_session.get(id(session), {})) for d in _from_cache(cached, request)
+                    (d, turns_by_session.get(id(session), {})) for d in _from_cache(cached, request)
                 )
                 maps.extend(_maps_from_cache(cached, request))
                 cache_hits += 1
@@ -660,7 +668,7 @@ def run_detector(
     for position, outcome in sorted(outcomes):
         request, session, chosen = runnable[position]
         produced.extend(
-            (d, times_by_session.get(id(session), {}))
+            (d, turns_by_session.get(id(session), {}))
             for d in outcome.findings  # type: ignore[attr-defined]
         )
         unknowns.extend(outcome.unknowns)  # type: ignore[attr-defined]

stacktrace_cli/monitor/render.py

@@ -173,8 +173,26 @@ _TOPIC_CHARS = 90
 
 
 def _topic(session: Any) -> str | None:
-    """The session's opening request, first line, capped. None when there is none."""
-    text = getattr(session, "initial_prompt", None)
+    """What to call a session: its own title, else its opening request.
+
+    **The title first, because it was chosen to identify the session** -- by
+    the person or by the agent -- while an opening request merely happens to be
+    first. Measured on a 76-session corpus the prompt is frequently the worse
+    label by a wide margin: the orchestrator opened with the word "hello", and
+    its 75 sub-agents all opened with the same harness template about fetching
+    origin/main, so the prompt told two of them apart in neither direction. The
+    one session carrying a title was the one whose prompt was "hello".
+
+    Both are `LOCAL_ONLY` upstream and stay on this page only, the same
+    asymmetry `working_directory` has (ADR-0006).
+
+    Read through `getattr`, like `working_directory` below it: `title` arrives
+    with a version of OpenAIDR newer than the pinned one, and a session without
+    it falls through to the prompt exactly as before rather than raising.
+    """
+    text = getattr(session, "title", None)
+    if not text:
+        text = getattr(session, "initial_prompt", None)
     if not text:
         text = next(
             (