stacktrace-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
@@ -126,9 +126,10 @@ because it is installed.
 ## What leaves your machine
 
 Two of `detect`'s three stages run entirely locally and need no model or
-credential. The third sends flagged sessions to the agent's *own* CLI — the
-provider that produced the transcript, never a different one — capped by
-`--budget`; `--no-escalate` turns it off and leaves the two local stages.
+credential, and they are the two a bare `detect` runs. The third sends flagged
+sessions to the agent's *own* CLI — the provider that produced the transcript,
+never a different one — and runs only when you pass `--escalate`, capped by
+`--budget`.
 
 `sessions` omits prompts, tool arguments and results unless you pass
 `--include-content`. `monitor` binds to loopback only, refuses a non-loopback

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/README.md

@@ -101,9 +101,10 @@ because it is installed.
 ## What leaves your machine
 
 Two of `detect`'s three stages run entirely locally and need no model or
-credential. The third sends flagged sessions to the agent's *own* CLI — the
-provider that produced the transcript, never a different one — capped by
-`--budget`; `--no-escalate` turns it off and leaves the two local stages.
+credential, and they are the two a bare `detect` runs. The third sends flagged
+sessions to the agent's *own* CLI — the provider that produced the transcript,
+never a different one — and runs only when you pass `--escalate`, capped by
+`--budget`.
 
 `sessions` omits prompts, tool arguments and results unless you pass
 `--include-content`. `monitor` binds to loopback only, refuses a non-loopback

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/docs/adrs/0004-three-stage-detector.md

@@ -5,6 +5,8 @@ status: accepted
 date: 2026-08-27
 supersedes: null
 superseded-by: null
+amends: null
+amended-by: 0029
 ---
 
 ## Context

stacktrace_cli-0.2.3/docs/adrs/0029-stage-three-returns-to-opt-in.md

@@ -0,0 +1,115 @@
+---
+id: 0029
+title: Stage three returns to opt-in
+status: accepted
+date: 2026-09-09
+supersedes: null
+superseded-by: null
+amends: 0004
+amended-by: null
+---
+
+## Context
+
+ADR-0004 was amended on 2026-09-03 to default `--escalate` **on** for
+`stacktrace detect`. The reasoning was sound and the amendment said so plainly:
+a stage nobody turns on never runs, and rules that depend on it — `injection-
+marker` above all — can only ever be evaluated against zero verdicts. It also
+named its own exit: *"Revisit once there is a measured escalation rate and
+verdict yield to argue from; if the yield does not justify the spend, the
+honest move is back to opt-in rather than a narrower cap."*
+
+What forces the revisit now is not the yield. It is that the default was only
+ever changed in one of the three places that carry it, and the other two — plus
+everything we publish — kept saying the opposite:
+
+| Surface | Default |
+| --- | --- |
+| `run_detector()` | `escalate=False` |
+| `stacktrace monitor` | `False` — *"a page left open is the wrong place for that to be implicit"* |
+| `remote sync detect` | `False` (ADR-0023) |
+| `stacktrace detect` | `True` |
+
+The published quickstart tells a new user to run `stacktrace detect
+--no-escalate`, annotated *"# Investigate without model escalation"* — a
+documented first command whose only purpose is to undo the default. The site's
+data-handling section makes the same promise in prose: *"Start with detection
+that doesn't send session content to a model."* `docs/plans/004-detector.md`
+still describes the stage as opt-in. One surface out of four, contradicted by
+its own documentation, is not a default; it is a divergence.
+
+Be honest about the evidence this ADR does **not** have. The escalation rate is
+low — an audit on 2026-09-02 measured 3 escalations across 635 sessions, 1 on
+evidence and 2 sampled — but that audit predates the amendment and so describes
+behaviour under the opt-in default it is being used to restore. Verdict yield,
+the other half of what ADR-0004 asked for, has not been measured. Stage 3 has
+also still never run against a real analyzer: the `live_cli` test is opt-in and
+deselected. So this is not the evidence-based revisit ADR-0004 anticipated. It
+is a consistency and consent decision taken ahead of that evidence.
+
+## Decision
+
+`stacktrace detect` defaults `--escalate` off, matching `run_detector`,
+`monitor` and `sync detect`. A bare `stacktrace detect` sends no session content
+off the machine.
+
+Two things travel with it. The verdict cache is no longer gated on `escalate`:
+`run_detector` already states that a verdict already paid for is an answer this
+run *has*, and that `escalate` governs whether new ones may be commissioned, not
+whether old ones may be read — `cli.py` contradicted that, and flipping the
+default without fixing it would have made every stored verdict silently
+unreadable on the default path. And a run that declines to escalate still counts
+and names the sessions that qualified, as `reasoning_not_requested`, so a run
+without stage 3 does not read as a clean one.
+
+## Alternatives considered
+
+- **Leave it on and fix only the docs.** Rejected: the quickstart, the
+  data-handling copy and the plan all describe opt-in, and three of four code
+  surfaces implement it. Changing four things to match one is the wrong
+  direction, and the one is the surface that spends the user's money.
+- **Keep it on until verdict yield is measured, as ADR-0004 asked.** Rejected on
+  consent rather than evidence: the measurement requires a bare `detect` to keep
+  sending transcript content to a provider by default, and the same measurement
+  is obtainable from users who opt in. The amendment accepted that cost
+  deliberately; what it did not anticipate is that we would simultaneously
+  publish the opposite promise.
+- **A narrower cap instead of opt-in.** Rejected by ADR-0004 itself, in advance:
+  *"the honest move is back to opt-in rather than a narrower cap."*
+- **Prompt interactively on first run.** Rejected: `detect` is scriptable and
+  runs unattended; a prompt makes the non-interactive path either hang or pick a
+  default, which is this decision again with extra machinery.
+
+## Consequences
+
+A bare `stacktrace detect` is now local plus the osv.dev coordinate lookup, and
+nothing else leaves. That is the promise the site already makes, kept.
+
+The cost is the one the amendment identified and it returns in full: stage 3
+runs only when asked, so verdict yield and the rules that depend on it stay
+unmeasured unless we go and measure them. That work does not disappear — it
+moves from "collected passively from every user" to "collected deliberately",
+and it should be done, because `injection-marker` cannot be evaluated at all
+without it.
+
+Watch for the stage going dark again. `reasoning_not_requested` in the reasoning
+accounting is the signal: if it is the dominant outcome across real runs for a
+release or two, the stage is not being reached and the rules behind it are still
+untuned. That is the same failure the 2026-09-03 amendment reacted to, and the
+answer will need to be something other than flipping the default a second time.
+
+Users relying on the implicit default silently lose stage 3. `--no-escalate`
+keeps working, so no invocation breaks; the release note carries the change.
+
+## When to revisit
+
+- **Verdict yield gets measured** and justifies the spend — then this is a
+  candidate to revert, but with the docs and the other three surfaces changed in
+  the same commit, which is what went wrong the first time.
+- **`reasoning_not_requested` dominates** real runs for two releases, per above.
+- **Stage 3 runs against a real analyzer** and the `live_cli` test stops being
+  deselected — until then the default-on path was shipping the least-validated
+  stage.
+- **The escalation stops costing the user.** The whole argument is that the
+  stage spends someone else's quota and crosses a content boundary. A stage that
+  did neither would not need to be asked for.

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/docs/adrs/INDEX.md

@@ -61,3 +61,4 @@ supersedes anything yet.
 - [0025](0025-a-denied-call-is-activity-never-an-invocation.md) — **A denied call is activity, and never an invocation.** ADR-0017 makes a declined repeat a stall while `outcome.py` keeps a denied call out of every count, so a denied-only session produced a finding with no activity and the Cloud rejected the whole run; a separate `denied` counter resolves it without either rule bending, and coverage keeps summing `invocations` alone. Read before changing what `activity[]` counts, or before folding `denied` into a coverage-like ratio.
 - [0027](0027-a-finding-may-name-what-it-could-not-place.md) — **A finding may name the component it could not place.** Narrows ADR-0006 constraint 3 for one field: an unplaced subject carries the name the session addressed it by, never as an identity. Read before removing a name from a finding on trust-boundary grounds, or before widening this to a second field.
 - [0028](0028-the-console-shows-what-it-placed.md) — **The console shows what it placed, and states no coverage.** Unplaceable rows, the `N/M placed` header fraction and the red on refusals are gone from `stacktrace monitor`: an unplaced row names no component, and `outcome.py`'s rule about a denied call makes reddening one the page contradicting its own counters. The snapshot contract, the upload and every rule are unchanged. Read before adding a page-side filter, before restoring a coverage ratio to the console, or if `unsanctioned-mcp-tool-use` returns.
+- [0029](0029-stage-three-returns-to-opt-in.md) — **Stage three returns to opt-in.** Amends ADR-0004: `stacktrace detect` defaults `--escalate` off, matching `run_detector`, `monitor` and `sync detect`, all of which never changed — the 2026-09-03 amendment landed in one of four surfaces while the quickstart, the data-handling copy and `plans/004` kept promising opt-in. Taken on consistency and consent, not on the verdict yield 0004 asked for, which is still unmeasured. The verdict cache is ungated from `escalate` in the same change. Read before changing an escalation default, or before arguing stage 3 should be on again.

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/docs/plans/007-detection-upload.md

@@ -243,8 +243,8 @@ rewrite*.
 - [x] **Step 1: Keep `sync endpoint`'s side-effect order.** Load config, refuse
   if unconfigured, client, replay spool, **detect**, register, upload per kind.
   Detecting before registering keeps a failed run from creating an asset.
-- [x] **Step 2: `--escalate` defaults off**, the inverse of `stacktrace detect`
-  (ADR-0023).
+- [x] **Step 2: `--escalate` defaults off** — a scheduled unattended run must
+  not spend provider quota or cross a content boundary implicitly (ADR-0023).
 - [x] **Step 3: `--dry-run` prints NDJSON from the same builder.**
 - [x] **Step 4: Cap evidence, refuse everything else.** Keep `evidence[0]` —
   the anchor the Cloud identifies a call-scoped detection by — and order, with

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/docs/plans/008-monitor.md

@@ -177,7 +177,7 @@ def analyse(
     return Analysis(run=run, view=acquired.view, window_start=window_start, window_end=window_end)
 ```
 
-- [x] **Step 4: Rewire `cli.py`'s `detect`.** Replace the three calls with one `analyse(...)`; keep the `try/except ValueError → ClickException` around it and the `VerdictCache(default_directory()) if cache and escalate else None` argument. Keep `_parse_since` as a thin alias if anything else imports it; delete it if nothing does.
+- [x] **Step 4: Rewire `cli.py`'s `detect`.** Replace the three calls with one `analyse(...)`; keep the `try/except ValueError → ClickException` around it and the `VerdictCache(default_directory()) if cache else None` argument — the cache is opened whenever `--cache` allows it and never gated on `escalate`, which governs whether new stage-3 work may be commissioned and not whether a verdict already paid for may be read. Keep `_parse_since` as a thin alias if anything else imports it; delete it if nothing does.
 
 - [x] **Step 5: Rewire `sync_detect.py`'s `_collect_detect_run`.** One `analyse(...)` call; keep `SyncError` translation, keep the working-directory collection and the per-kind activity walk, and read `window_start`/`window_end`/`collection_failures` off the `Analysis` instead of computing them.
 

stacktrace_cli-0.2.3/docs/releases/v0.2.3.md

@@ -0,0 +1,102 @@
+# 0.2.3 — stage three is opt-in
+
+`stacktrace detect` no longer sends anything session-derived off your machine
+unless you ask it to. The third stage — the one that hands flagged sessions to
+the agent's own CLI — is now behind `--escalate`, which is what the quickstart,
+the data-handling page and three of the four code surfaces already said it was.
+Alongside it, a fix worth reading if you installed with `install.sh`: `correlate`
+was reaching whichever OpenACA your PATH happened to name rather than the one
+this package pins.
+
+## Highlights
+
+- **`stacktrace detect` defaults `--escalate` off.** A bare run is the two
+  stages that need no model and no credential, plus the osv.dev advisory
+  lookup, which sends package coordinates only. `--escalate` turns the third
+  stage on and `--budget` still caps it. The default had been on since
+  2026-09-03 while `run_detector`, `stacktrace monitor` and `remote sync detect`
+  all defaulted it off and the published quickstart told new users to pass
+  `--no-escalate`; one surface out of four, contradicted by its own
+  documentation, was a divergence rather than a default. ADR-0029 records the
+  decision and is explicit that it is a consent decision taken ahead of the
+  verdict-yield evidence ADR-0004 asked for, which is still unmeasured.
+
+  A run that declines to escalate is not a clean run. Sessions that qualified
+  are counted in the reasoning accounting as `reasoning_not_requested`; the
+  session ids are in `--format json`, not the text output, which aggregates
+  them under the reason.
+
+- **A verdict you already paid for is readable on the default path.** Both
+  `detect` and `remote sync detect` built their verdict cache only when
+  escalation was on, so with the new default every stored verdict would have
+  gone unread and the same sessions would have been billed twice on the next
+  `--escalate` run. `run_detector` has always held that the flag governs whether
+  new verdicts may be commissioned, not whether old ones may be read; the two
+  call sites disagreed with it. An exhaustiveness test now covers every cache
+  construction site rather than the two that were found by hand.
+
+- **`correlate` runs the OpenACA this package pins.** Acquisition invoked the
+  bare name `openaca`, a PATH lookup — and `uv tool install stacktrace-cli`,
+  which is what `install.sh` runs, links only the `stacktrace` entry point, so
+  the pinned OpenACA sat one directory away, reachable but unnamed. A machine
+  with a stale global copy silently scanned with the wrong version; a machine
+  with none got a bare `FileNotFoundError`. `stacktrace --version` could not
+  reveal it, because it reports the metadata inside the environment while the
+  subprocess ran something else. The console script is now located through
+  `importlib.metadata`, authenticated against the digest its own install
+  recorded, and fails closed with a legible error where ownership cannot be
+  established. Verified against four real install topologies. The ADR-0007 seam
+  is unchanged.
+
+- **One default, stated once.** The escalation default had also drifted into
+  `docs/specs/detector.md`, `docs/specs/detection-upload.md`, test descriptions,
+  wrapped help text, and `docs/plans/008-monitor.md`, which still instructed the
+  cache gate this release removes. A test now reads the active specs, plans and
+  help text and fails on a stale wording, in any of the three names the repo
+  uses for the stage.
+
+- **The console names the log column `Agent Session Trace`,** dropping the
+  third word from `Agent Session Log Trace` — session, log and trace were three
+  words for one thing. The one-item legend above the columns (`MCP = a link to
+  an outside service`) is gone: an MCP row already carries its category tag and
+  names the server it reached.
+
+- **`detect` stops printing the per-reason "Could not settle" breakdown.** It
+  listed internal reason ids — `mcp_transport_unavailable` dominates on a normal
+  machine — at a reader who cannot act on them one call at a time. The unsettled
+  count stays in the summary line, `--format json` still carries every `Unknown`
+  whole with its spans and detail, and the reasoning stage still names its own
+  outcomes.
+
+## Install
+
+`uv tool install stacktrace-cli==0.2.3` or `pip install stacktrace-cli==0.2.3`.
+
+## Compatibility
+
+**One behaviour change, and the patch version does not signal it: `stacktrace
+detect` no longer escalates by default.** If you relied on a bare `detect`
+reaching stage 3, pass `--escalate` to restore it. Nothing breaks — the
+`--no-escalate` you may already be passing still means what it meant — but a
+default run now produces no reasoning-stage findings, and sessions that would
+have been analysed appear as `reasoning_not_requested` instead. `monitor` and
+`remote sync detect` are unaffected; they already defaulted off.
+
+If you had accumulated verdicts from earlier `--escalate` runs, they are served
+again on the default path rather than ignored, so a `detect` after upgrading may
+report reasoning findings without spending anything.
+
+Text output changes in two places: the `Could not settle:` block is gone, and
+the reasoning accounting's not-requested row names a flag rather than a reason
+id. `--format json` is unchanged — no field added, removed or renamed — and the
+upload payload is untouched, so anything parsing either sees what 0.2.2 served.
+
+On the console, the log column is renamed and the legend line is removed. No
+rule, finding, severity or payload field moves.
+
+If `install.sh` put stacktrace on your machine and you had separately installed
+or upgraded OpenACA to work around a scan failure, that workaround is no longer
+needed; the pinned 0.6.0 is what runs now.
+
+Still pre-alpha, with no back-compat hedging: interfaces can change between
+releases without a deprecation window.

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/docs/specs/detection-upload.md

@@ -291,7 +291,7 @@ Detecting before registering keeps a failed run from creating an asset.
 |---|---|---|
 | `--agent-kind`, `--bom`, `--budget`, `--sample-budget`, `--cache/--no-cache`, `--project-map`, `--root` | as `stacktrace detect` | |
 | `--since` | `7d` | |
-| `--escalate/--no-escalate` | **`--no-escalate`** | Inverse of `stacktrace detect`. Stage 3 spends the developer's provider quota and crosses a boundary; unattended is the wrong place for that to be implicit |
+| `--escalate/--no-escalate` | **`--no-escalate`** | Stage 3 spends the developer's provider quota and crosses a boundary; unattended is the wrong place for that to be implicit |
 | `--dry-run` | off | NDJSON via the same builder the real path uses, so the preview **is** the payload. ADR-0006 constraint 4 requires it |
 | `--quiet`, `--allow-offline-cache` | off | as `sync endpoint` |
 

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/docs/specs/detector.md

@@ -63,11 +63,11 @@ only stage that sends anything *session-derived* off the machine. Package
 coordinates travel either way; prompts, arguments and results travel only when
 escalation runs, and then to the session's own provider and no other.
 
-**`reasoning` is on by default and capped** (ADR-0004, amended). It shipped
-opt-in and consequently never ran, so its rules could not be tuned against any
-verdict at all; the default is inverted to gather that evidence. The `--budget`
-cap, the verdict cache and `--no-escalate` are what bound the cost of that
-decision.
+**`reasoning` is opt-in and capped** (ADR-0029). A stage that spends the
+developer's quota and crosses that content boundary is asked for rather than
+assumed, so it runs only under `--escalate`. Three things bound its cost when it
+is asked for: the `--budget` cap, the verdict cache — so an unchanged session is
+never paid for twice — and the flag itself.
 
 **The ordering is the unit economics.** Microseconds, then milliseconds, then —
 only for the residue neither could resolve — seconds of inference. The per-session

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stacktrace-cli"
-version = "0.2.2"
+version = "0.2.3"
 description = "CLI for Stacktrace — Detection and Response platform for AI Agents."
 readme = "README.md"
 requires-python = ">=3.11"

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/src/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.2.3"

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/src/stacktrace_cli/cli.py

@@ -224,15 +224,17 @@ def sessions(
 )
 @click.option(
     "--escalate/--no-escalate",
-    default=True,
+    default=False,
     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 "
-    "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.",
+    help="Send flagged sessions to the agent's own CLI for semantic analysis. 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 a run "
+    "that does neither is the one to reach for first. --escalate 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",
@@ -295,18 +297,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:
+    --escalate 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 --escalate 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 --escalate:
     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.
@@ -324,9 +328,13 @@ def detect(
             escalate=escalate,
             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 `escalate`. A verdict already paid for is an
+            # answer this run has, and `escalate` 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

{stacktrace_cli-0.2.2 → stacktrace_cli-0.2.3}/src/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,