stacktrace-cli 0.2.2__py3-none-any.whl → 0.3.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.2.2"
+__version__ = "0.3.0"

stacktrace_cli/analysis.py

@@ -106,7 +106,7 @@ def analyse(
     project_map: tuple[str, ...] = (),
     root: Path | None = None,
     session_ids: tuple[str, ...] = (),
-    escalate: bool = False,
+    reasoning: bool = False,
     budget: int = DEFAULT_BUDGET,
     sample_budget: int = DEFAULT_SAMPLE_BUDGET,
     cache: VerdictCache | None = None,
@@ -123,7 +123,7 @@ def analyse(
     pass; a one-shot command passes nothing and gets the default.
 
     `session_ids` narrows the window to named sessions. Empty means the whole
-    window, which is what every command passes; monitor's escalate button is
+    window, which is what every command passes; monitor's reasoning button is
     what needs the narrowing, and needs it to be structural.
 
     `since` is the window's spelling — `parse_since` reads it — or the cutoff
@@ -142,7 +142,7 @@ def analyse(
     )
     run = run_detector(
         acquired.view,
-        escalate=escalate,
+        reasoning=reasoning,
         budget=budget,
         sample_budget=sample_budget,
         cache=cache,
@@ -287,11 +287,11 @@ def analyse_progressively(
     exists to prevent.
 
     `cache` is read and never written. A session graded by an earlier
-    `detect --escalate` shows that grade here; this path never commissions one.
+    `detect --reasoning` shows that grade here; this path never commissions one.
 
-    **No `escalate` parameter, deliberately.** Stage 3's budget is per *run*, so
+    **No `reasoning` parameter, deliberately.** Stage 3's budget is per *run*, so
     judging in batches would give each batch its own budget and spend a multiple
-    of what was authorised. A streaming escalation needs a budget shared across
+    of what was authorised. A streaming reasoning run needs a budget shared across
     batches; until it has one, this path does not offer the option rather than
     offering it wrongly.
     """
@@ -358,8 +358,8 @@ def analyse_progressively(
     for index in range(0, len(ordered), step):
         judged = run_detector(
             CorrelatedView(sessions=tuple(ordered[index : index + step])),
-            # Read, never written, and never escalating: a session an earlier
-            # `detect --escalate` graded renders with that grade here, and this
+            # Read, never written, and never requesting: a session an earlier
+            # `detect --reasoning` graded renders with that grade here, and this
             # path commissions nothing (ADR-0026 clause 2).
             cache=cache,
         )
@@ -367,7 +367,7 @@ def analyse_progressively(
             detections=accumulated.detections + judged.detections,
             unknowns=accumulated.unknowns + judged.unknowns,
             sessions=accumulated.sessions + judged.sessions,
-            escalated=accumulated.escalated + judged.escalated,
+            requested=accumulated.requested + judged.requested,
             analysed=accumulated.analysed + judged.analysed,
             cache_hits=accumulated.cache_hits + judged.cache_hits,
             collection_failures=failures,

stacktrace_cli/cli.py

@@ -223,16 +223,19 @@ def sessions(
     help="Show every detection and all of its evidence. Default: the summary alone.",
 )
 @click.option(
-    "--escalate/--no-escalate",
-    default=True,
-    show_default=True,
-    help="Send flagged sessions to the agent's own CLI for semantic analysis. On "
-    "by default, capped by --budget. It is the only stage that sends anything "
+    "--reasoning",
+    is_flag=True,
+    default=False,
+    help="Analyse flagged sessions with a reasoning model, run through the "
+    "agent's own CLI. Off by default: it is the only stage that sends anything "
     "session-derived off this machine, and it spends the developer's own "
-    "provider quota, so --no-escalate turns it off and the cap keeps a noisy "
-    "day bounded. It does not make the run offline: correlation runs first "
-    "either way and matches advisories by sending the package coordinates of "
-    "the components a session invoked to osv.dev.",
+    "provider quota, so a run that does neither is the one to reach for first. "
+    "--reasoning turns it on "
+    "and --budget caps a noisy day. Leaving it off does not make the run "
+    "offline: correlation runs first either way and matches advisories by "
+    "sending the package coordinates of the components a session invoked to "
+    "osv.dev. Sessions that qualified are still counted, and named in "
+    "--format json, so the run says what it did not do.",
 )
 @click.option(
     "--budget",
@@ -279,7 +282,7 @@ def detect(
     bom_paths: tuple[Path, ...],
     output_format: str,
     detail: bool,
-    escalate: bool,
+    reasoning: bool,
     budget: int,
     sample_budget: int,
     cache: bool,
@@ -295,18 +298,20 @@ def detect(
     families carry their own severity ladders, because a stalled loop and a
     leaked credential cannot share one (ADR-0010).
 
-    Two stages need no model or credential. The third sends flagged sessions to
-    the agent's own CLI: on by default and capped by --budget, with
-    --no-escalate to turn it off.
+    Two stages need no model or credential, and they are the two that run by
+    default. The third sends flagged sessions to the agent's own CLI:
+    --reasoning turns it on, capped by --budget. Sessions that qualified for it
+    are counted either way, and named in --format json, so a run without it
+    says so rather than reading as a clean one.
 
     That third stage is the one that sends session content off this machine:
     the agent's own CLI hands the prompts, arguments and results a rule needs
     to the provider it is already authenticated against (ADR-0004 -- provider
     affinity, so a transcript goes back to the vendor that produced it, and
-    there is no fallback to any other). --no-escalate leaves the two stages
-    that send nothing.
+    there is no fallback to any other). Without --reasoning the run is the two
+    stages that send nothing.
 
-    One network call happens before any of them regardless of --no-escalate:
+    One network call happens before any of them, with or without --reasoning:
     correlation matches advisories by sending the package coordinates of the
     components a session invoked to osv.dev. Coordinates only -- never a
     prompt, an argument or a result.
@@ -321,12 +326,16 @@ def detect(
             bom_paths=bom_paths,
             project_map=project_map,
             root=root,
-            escalate=escalate,
+            reasoning=reasoning,
             budget=budget,
             sample_budget=sample_budget,
-            # Only ever consulted when stage 3 runs: there is nothing to reuse
-            # otherwise, and opening a directory to discover that is waste.
-            cache=VerdictCache(default_directory()) if cache and escalate else None,
+            # Not gated on `reasoning`. A verdict already paid for is an
+            # answer this run has, and `reasoning` governs whether new ones may
+            # be commissioned, not whether old ones may be read -- the rule
+            # `run_detector` states at its cache pass. Gating it here made a
+            # session read as graded or ungraded depending on a flag that
+            # spent nothing either way.
+            cache=VerdictCache(default_directory()) if cache else None,
         )
     except ValueError as error:
         raise click.ClickException(str(error)) from error
@@ -360,11 +369,11 @@ def detect(
     "entirely when nothing on disk has changed.",
 )
 @click.option(
-    "--escalate/--no-escalate",
+    "--reasoning",
+    is_flag=True,
     default=False,
-    show_default=True,
-    help="Let the page send one session to the agent's own CLI for semantic "
-    "analysis. Off by default: stage 3 spends your provider quota, and a page "
+    help="Let the page analyse one session with a reasoning model, run through "
+    "the agent's own CLI. Off by default: stage 3 spends your provider quota, and a page "
     "left open is the wrong place for that to be implicit. Capped by --budget.",
 )
 @click.option(
@@ -372,7 +381,7 @@ def detect(
     type=click.IntRange(min=1),
     default=DEFAULT_BUDGET,
     show_default=True,
-    help="Escalations this monitor may spend in total, if --escalate is on.",
+    help="Reasoning runs this monitor may spend in total, if --reasoning is on.",
 )
 @click.option(
     "--no-open", is_flag=True, default=False, help="Print the URL, do not open a browser."
@@ -413,7 +422,7 @@ def monitor(
     port: int,
     host: str,
     interval: float,
-    escalate: bool,
+    reasoning: bool,
     budget: int,
     no_open: bool,
     agent_kinds: tuple[str, ...],
@@ -431,7 +440,7 @@ def monitor(
 
     Loopback only, and free to leave open: a pass is skipped when nothing has
     changed, advisory lookups are asked once per component, and the two stages
-    that need no model are the only ones that run. --escalate adds a button
+    that need no model are the only ones that run. --reasoning adds a button
     that spends your provider quota, off unless asked for.
     """
     try:
@@ -439,7 +448,7 @@ def monitor(
             host=host,
             port=port,
             interval=interval,
-            escalate=escalate,
+            reasoning=reasoning,
             budget=budget,
             open_browser=not no_open,
             echo=click.echo,

stacktrace_cli/correlate/acquire.py

@@ -16,13 +16,23 @@ answer naming a component that was never involved.
 
 from __future__ import annotations
 
+import base64
+import hashlib
 import json
+import os
 import subprocess
+import sys
 import tempfile
 from collections.abc import Callable, Sequence
 from collections.abc import Set as AbstractSet
 from dataclasses import dataclass
 from datetime import UTC, datetime
+from importlib.metadata import (
+    Distribution,
+    PackageNotFoundError,
+    PackagePath,
+    distribution,
+)
 from pathlib import Path
 from typing import Any
 
@@ -36,6 +46,140 @@ from stacktrace_cli.correlate.composition import (
 
 _AGENT_KIND_PROPERTY = "openaca:agent_kind"
 
+#: The name OpenACA publishes its console script under. `.exe` on Windows
+#: because that is the launcher installers write there, and this package claims
+#: `Operating System :: OS Independent`.
+_SCRIPT = "openaca.exe" if os.name == "nt" else "openaca"
+
+
+def _openaca() -> str:
+    """The OpenACA console script this package pins, addressed by path.
+
+    The bare string `"openaca"` is a `PATH` lookup, and `PATH` is not where the
+    pinned copy lives: `uv tool install stacktrace-cli` links only the
+    `stacktrace` entry point out of the tool environment, so the OpenACA that
+    `[project.dependencies]` resolved sits in `bin/` reachable but unnamed. A
+    bare name therefore selects whichever global, `pipx` or `--user` copy the
+    machine carries — a stale one silently does the work and its version need
+    not be the one this package depends on — or, on a machine with none,
+    nothing at all. This is the rule `docs/specs/cli-composition.md` states for
+    the mounted commands, applied to the one path that reaches OpenACA as a
+    subprocess.
+
+    **The path is the one the pinned distribution's own install recorded, not a
+    guess from this interpreter's location.** Python defines separate prefix,
+    virtual-environment, user and home installation schemes, and only the first
+    two put console scripts beside the interpreter: `pip install --user
+    stacktrace-cli` puts them under `site.USER_BASE` while `sys.executable`
+    stays the base interpreter. Deriving the path from `sys.executable` alone
+    therefore names a file that does not exist under a supported install, and
+    `detect` dies at process launch before it can build anything.
+    `importlib.metadata` answers instead: it resolves the OpenACA on *this*
+    interpreter's `sys.path` — the pinned one, by construction — and that
+    install's `RECORD` names the script file it wrote, wherever its scheme put
+    it.
+
+    **The only thing run is a file that install recorded writing, still holding
+    the contents it recorded.** Nothing is run for being named `openaca` in a
+    directory the distribution merely shares: an installation scheme pairs a
+    library directory with a scripts directory, but that scripts directory holds
+    the launchers of *every* distribution installed into the scheme and records
+    nothing about which one wrote any of them, so co-location establishes where
+    installers put scripts in general and never that this distribution put this
+    one there. Nor does a recorded path settle it on its own, because a record
+    describes what an install wrote rather than reserving where it wrote it: the
+    scripts directory stays shared afterwards, so a later install of another
+    distribution can overwrite that very file while the record still names it.
+    A stale, global, independently managed or overwritten launcher of that name
+    reintroduces exactly the version skew this addressing exists to remove, and
+    it does so invisibly — a wrong-version OpenACA can return a structurally
+    valid BOM. Where ownership cannot be established the answer is a
+    `RuntimeError` naming why, which `_build` renders as a legible CLI error.
+
+    Still the published console script, so the ADR-0007 seam is unchanged: this
+    module imports no OpenACA internals and `tests/test_seam_boundary.py` holds
+    that line.
+    """
+    try:
+        installed = distribution("openaca")
+    except PackageNotFoundError as error:
+        raise RuntimeError(
+            "the OpenACA this package pins is not installed on "
+            f"{sys.executable}'s import path, so no {_SCRIPT!r} on this machine "
+            "can be known to be it; reinstalling stacktrace-cli restores it"
+        ) from error
+    recorded = _recorded_script(installed)
+    if recorded is not None:
+        return str(recorded)
+    raise RuntimeError(
+        f"the pinned OpenACA installed at {installed.locate_file('')} records no "
+        f"{_SCRIPT!r} console script of its own that still holds the contents it "
+        "recorded; a copy found by name alone — by sharing a directory with that "
+        "install, or by having replaced a file it wrote — need not be the version "
+        "this package depends on, so none is run; reinstalling stacktrace-cli "
+        "restores it"
+    )
+
+
+def _recorded_script(installed: Distribution) -> Path | None:
+    """The console script the pinned OpenACA's install recorded, if it did.
+
+    A `RECORD` entry says the distribution `[project.dependencies]` resolved
+    wrote a file of these contents at this path — which is more than a directory
+    a scheme suggested can say, and less than the path alone would suggest,
+    because the two halves age differently: the path stays shared, the contents
+    do not. Scripts live outside `site-packages` and are recorded relative to
+    it, so the entry resolves correctly under every scheme.
+
+    Absent when the install enumerated no files: `importlib.metadata` answers
+    `None` when the metadata that lists them is missing — `RECORD` for a
+    `dist-info` install — and an `egg-info` install lists the sources it was
+    built from rather than the scripts it wrote. That is a distribution that
+    cannot name its own launcher, not licence to run someone else's: the only
+    other thing available about such an install is where it sits, and a
+    directory is shared by everything installed alongside it.
+
+    Absent, too, when the file at the recorded path is not the file that was
+    recorded there. Every candidate is authenticated against its own recorded
+    digest, because the two halves of an entry answer different questions: the
+    path says where the install wrote a launcher, and the digest says what it
+    wrote. Only the second survives another install overwriting the shared
+    scripts directory afterwards.
+    """
+    for recorded in installed.files or ():
+        if recorded.name == _SCRIPT:
+            candidate = Path(str(installed.locate_file(recorded))).resolve()
+            if _holds_recorded_contents(recorded, candidate):
+                return candidate
+    return None
+
+
+def _holds_recorded_contents(recorded: PackagePath, candidate: Path) -> bool:
+    """Whether the file now at a recorded path hashes to what was recorded for it.
+
+    Fails closed on every reason the question cannot be answered — no digest,
+    a digest naming an algorithm this interpreter does not implement, an
+    unreadable file — because "we could not check" and "it matches" differ by
+    exactly the guarantee this locator exists to give, and the unchecked case
+    fails invisibly: a wrong-version OpenACA returns a structurally valid BOM.
+    The digest field is optional in a `RECORD` row, so an install can decline
+    to say what it wrote; that install cannot then be shown to own the file
+    sitting at the path it names, and a reinstall is what restores the
+    evidence.
+
+    Digests are base64url without padding, so the padding is stripped from
+    both sides rather than assumed absent from either.
+    """
+    digest = recorded.hash
+    if digest is None:
+        return False
+    try:
+        computed = hashlib.new(digest.mode, candidate.read_bytes()).digest()
+    except (ValueError, TypeError, OSError):
+        return False
+    encoded = base64.urlsafe_b64encode(computed).decode("ascii")
+    return encoded.rstrip("=") == digest.value.rstrip("=")
+
 
 def load_bom(path: Path) -> tuple[str, Built]:
     """Read a supplied Agent BOM, or say why it cannot be used.
@@ -95,7 +239,7 @@ def build_bom(
     with tempfile.TemporaryDirectory() as scratch:
         directory = Path(scratch)
         argv = [
-            "openaca",
+            _openaca(),
             "bom",
             "endpoint",
             "--kind",
@@ -291,8 +435,16 @@ def _scan(
     array, and a family we do not read is a fact about the scan rather than a
     fault in it.
     """
+    try:
+        openaca = _openaca()
+    except RuntimeError:
+        # The same answer as an unreadable response, for the same reason: with no
+        # OpenACA that can be known to be the pinned one, this scan did not run.
+        # A `--bom` run reaches here without having built anything, so this is
+        # the first place that can be discovered — and `{}` would say we looked.
+        return None
     result = subprocess.run(
-        ["openaca", "scan", "bom", "--input", str(bom_path), "--format", "json"],
+        [openaca, "scan", "bom", "--input", str(bom_path), "--format", "json"],
         capture_output=True,
         text=True,
         check=False,

stacktrace_cli/detector/analyzer.py

@@ -64,7 +64,7 @@ _TIMEOUT = 180
 #: run /login"* and exits 1, on a machine whose CLI is authenticated and working.
 #: That is the same premise `--bare` is avoided for (ADR-0004: the developer's
 #: own CLI, already authenticated), broken through the environment instead of
-#: through a flag. The failure mode is the dangerous kind: every escalation
+#: through a flag. The failure mode is the dangerous kind: every reasoning request
 #: returns `analyzer_error`, the pipeline records `Unknown`, and stage 3 looks
 #: like it ran. `LOGNAME` accompanies it as the same identity on systems that
 #: set that instead.

stacktrace_cli/detector/cache.py

@@ -3,7 +3,7 @@
 Authorized by ADR-0011, which amends ADR-0006's persistence clause. The argument
 is narrow: a reasoning verdict is an **expensive pure function of an immutable,
 ended session**. `stacktrace detect` is a command a person runs repeatedly, each
-escalation costs roughly $0.09 and 9 seconds, and the answer cannot change once
+reasoning request costs roughly $0.09 and 9 seconds, and the answer cannot change once
 the session has stopped growing.
 
 Three properties carry the whole design, and each exists because its absence was
@@ -116,7 +116,7 @@ class CachedVerdict:
 
 @dataclass(frozen=True)
 class CachedOutcome:
-    """One escalation's stored answer: provenance, plus whichever rules fired.
+    """One reasoning request's stored answer: provenance, plus whichever rules fired.
 
     Provenance sits here rather than on each verdict because ADR-0011
     constraint 1 lists it as part of what an entry *carries*, not only what it is
@@ -132,7 +132,7 @@ class CachedOutcome:
 
 def cache_key(
     session: SessionLike,
-    escalation: object,
+    request: object,
     rule_ids: Sequence[str],
     prompt_version: str,
     identity: tuple[str, str],
@@ -143,17 +143,17 @@ def cache_key(
     ADR-0011 constraint 3 states them apart, and neither is a field `serialise()`
     shows the analyzer — so a fingerprint built only from analyzer-visible
     content would let two distinct sessions with byte-identical rendered turns
-    and escalation context share one verdict.
+    and reasoning-request context share one verdict.
 
     **Reasons and spans are hashed in their given order, never sorted.**
     `_why()` joins each collection in order and puts the result straight into
     the prompt, so the same members in a different order are two different
     prompts. Sorting first would merge them.
 
-    **Which rule cited which span, not only the merged set.** `escalation.spans`
-    is a deduplicated union over every escalating reason, so it cannot say
+    **Which rule cited which span, not only the merged set.** `request.spans`
+    is a deduplicated union over every requesting reason, so it cannot say
     whether a span was the injection marker's evidence or the credential rule's
-    — and `serialise_injection()` reads exactly that, from `escalation.stage_one`,
+    — and `serialise_injection()` reads exactly that, from `request.stage_one`,
     to decide which results and arguments the transcript carries. Two builds
     that attribute overlapping spans differently produce the same union and
     wholly different transcripts, so without this a verdict computed from one
@@ -181,12 +181,12 @@ def cache_key(
             {
                 "session_id": session.session_id,
                 "turn_count": session.turn_count,
-                "reasons": list(getattr(escalation, "reasons", ()) or ()),
-                "spans": list(getattr(escalation, "spans", ()) or ()),
-                "stage_one": _cited_per_rule(escalation),
+                "reasons": list(getattr(request, "reasons", ()) or ()),
+                "spans": list(getattr(request, "spans", ()) or ()),
+                "stage_one": _cited_per_rule(request),
                 "coverage": [
-                    getattr(getattr(escalation, "coverage", None), "total", None),
-                    getattr(getattr(escalation, "coverage", None), "resolved", None),
+                    getattr(getattr(request, "coverage", None), "total", None),
+                    getattr(getattr(request, "coverage", None), "resolved", None),
                 ],
                 "prompt_version": prompt_version,
                 "verdict_logic_version": _VERDICT_LOGIC_VERSION,
@@ -201,7 +201,7 @@ def cache_key(
     return digest.hexdigest()
 
 
-def _cited_per_rule(escalation: object) -> list[list[object]]:
+def _cited_per_rule(request: object) -> list[list[object]]:
     """Which stage-one rule cited which spans, in the order they were found.
 
     Descriptors only, and only the two a prompt reads: `serialise_injection()`
@@ -212,13 +212,13 @@ def _cited_per_rule(escalation: object) -> list[list[object]]:
 
     Order is preserved rather than sorted. Nothing downstream reads it — the
     spans become a set — so the worst a preserved order can do is separate two
-    escalations that would have produced one prompt, which costs a miss. The
+    requests that would have produced one prompt, which costs a miss. The
     opposite mistake merges two prompts under one key, and that is the one
     ADR-0011 constraint 5 forbids.
     """
     return [
         [finding.rule_id, [evidence.span for evidence in finding.evidence]]
-        for finding in getattr(escalation, "stage_one", ()) or ()
+        for finding in getattr(request, "stage_one", ()) or ()
     ]
 
 

stacktrace_cli/detector/deterministic.py

@@ -2,7 +2,7 @@
 
 Every rule here is one a responder can verify by looking at the session. That is
 the bar for this stage, and it is why the stage emits directly rather than
-escalating: nothing a slower stage adds changes *this string looks like a
+requesting reasoning: nothing a slower stage adds changes *this string looks like a
 credential and it went to an outbound call*.
 
 Two asymmetries carry most of the precision:

stacktrace_cli/detector/finding.py

@@ -150,7 +150,7 @@ class Evidence:
 class Verdict:
     """What produced a finding, so two machines' answers are comparable.
 
-    Recorded for every stage, not only escalated ones: knowing a finding came
+    Recorded for every stage, not only requested ones: knowing a finding came
     from `priors` rather than `reasoning` is what tells a reader whether a model
     was involved at all.
     """
@@ -340,9 +340,9 @@ class Unknown:
     reason: UnknownReason
     spans: tuple[str, ...] = ()
     detail: str = ""
-    #: For an escalation that qualified for stage 3 but never reached it, the
+    #: For a reasoning request that qualified for stage 3 but never reached it, the
     #: priors that would have been analysed. Kept so a budget-limited or
-    #: `--no-escalate` run still shows *why* the session was of interest.
+    #: run without `--reasoning` still shows *why* the session was of interest.
     reasons: tuple[str, ...] = field(default_factory=tuple)
     #: Reasoning-stage only: whether this unknown was raised **after** the
     #: session was actually sent to the analyzer. `run_detector` counts a

stacktrace_cli/detector/markers.py

@@ -27,7 +27,7 @@ from data to instruction.
 
 Finding the characters is not finding an attack, and the difference is
 measurable. On 621 real sessions this rule fired three times — the only
-evidence-backed escalations in the whole corpus — and all three were one file:
+evidence-backed reasoning requests in the whole corpus — and all three were one file:
 another agent-security tool's own detector, whose source reads
 `_BIDI_OVERRIDE_CHARS = frozenset('\u202d\u202e')`. Security work names the
 alphabet of the attacks it looks for, and so do specifications, test fixtures