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

{stacktrace_cli-0.2.0 → stacktrace_cli-0.2.2}/CLAUDE.md

@@ -11,8 +11,8 @@ and by CI pipelines that invoke `stacktrace`, and it builds on the open-source
 It is also the **design home for Stacktrace Detect** — the AIDR product this CLI
 grows into. The specs in `docs/specs/` and the decisions in `docs/adrs/` describe
 the whole system: session input, correlation against the composition graph, the
-three-stage detector, and the combined report. The code here is the placeholder that
-precedes them.
+three-stage detector, and the combined report. The code here implements them
+incrementally.
 
 ## Common commands
 
@@ -52,11 +52,13 @@ the single source of truth for the version string reported by `--version`.
 
 Build backend is hatchling with a src layout; the wheel's contents are declared
 explicitly by `[tool.hatch.build.targets.wheel] packages = ["src/stacktrace_cli"]`.
-The only runtime dependency is `openaca>=0.4.0`, which supplies the Agent
-Composition Analysis primitives this CLI is intended to drive.
+Runtime dependencies are `openaca` for the Agent Composition Analysis
+primitives this CLI drives, `openaidr` for session collection, and `httpx` for
+the remote channel. Each is pinned exactly before a release; see
+`docs/cutover-openaca-remote.md`.
 
-The package is currently pre-alpha: `main()` reports its version and points at
-the docs. Real functionality lands in later releases.
+`sessions`, `detect`, `monitor` and `remote` are native; `bom`, `policy` and
+`scan` are OpenACA's own command objects.
 
 **The design that functionality implements is in this repo.** Read
 `docs/specs/aidr.md` first — it is the umbrella: components, contracts, the two
@@ -121,6 +123,25 @@ nothing about detection.
   a review names a site, fix the invariant and extend the exhaustive test — a
   second finding of the same class means the first fix was at the wrong level.
 
+## Adding a command
+
+A command is a **pass-through** or it is **native**, never both — and a
+pass-through never gains a flag of its own. See
+[ADR-0021](docs/adrs/0021-two-command-kinds.md) for why.
+
+- **Pass-through** — add one string to `PASSTHROUGH` in
+  `src/stacktrace_cli/cli.py`, having decided it belongs. The loop registers
+  OpenACA's own command object under that name; there is nothing else to
+  write and nothing to keep in step with OpenACA.
+- **Native** — write a Click command or group and `add_command` it, the way
+  `remote` is. If it needs OpenACA it calls `openaca.core`
+  ([ADR-0020](docs/adrs/0020-openaca-consumption-boundary.md)), and whatever
+  it names there is added to the contract test in `tests/remote/`, because it
+  now holds duplicated knowledge of an interface.
+
+The section a command lands under in `--help` follows from which kind it is;
+there is no second list to update.
+
 ---
 
 ## Behavioral guidelines

stacktrace_cli-0.2.2/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: stacktrace-cli
+Version: 0.2.2
+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>
+License-Expression: LicenseRef-Proprietary
+Keywords: agent-security,ai-security,openaca,stacktrace
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx<1.0.dev0,>=0.28.1
+Requires-Dist: openaca==0.6.0
+Requires-Dist: openaidr==0.1.0
+Description-Content-Type: text/markdown
+
+# stacktrace-cli
+
+Detection and response for AI coding agents, from the command line.
+
+Coding agents read files, run shell commands and call MCP servers on their own
+initiative, and they write a transcript of every bit of it to disk.
+`stacktrace` reads those transcripts, correlates what ran against the
+components the agent is built from, and reports the security and reliability
+findings in it — locally, on the machine the agent worked on.
+
+The PyPI distribution is `stacktrace-cli`; the command it installs is
+`stacktrace`. The two names differ because the bare `stacktrace` name on PyPI
+belongs to an unrelated project.
+
+## Installation
+
+```bash
+uv tool install stacktrace-cli     # isolated; recommended
+# or
+pip install stacktrace-cli
+```
+
+Requires Python 3.11 or newer.
+
+```console
+$ stacktrace --version
+stacktrace 0.2.1 (openaca 0.6.0)
+```
+
+## Quick start
+
+```bash
+stacktrace sessions      # what the agents on this machine did
+stacktrace detect        # what is wrong with it
+stacktrace monitor       # the same, live in a browser
+```
+
+## Commands
+
+| Command | |
+|---|---|
+| `sessions` | Print what the agents on this machine actually did. |
+| `detect` | Find security and reliability findings in what agents did. |
+| `monitor` | Watch this machine's agents in a browser, live. |
+| `remote` | Configure remote endpoint services and upload to Stacktrace Cloud. |
+| `scan` | Scan a repository or endpoint for agent-composition findings. |
+| `bom` | Generate an Agent BOM for a repository or endpoint. |
+| `policy` | Validate and compile restrictive endpoint policies. |
+
+The last three are composition analysis, supplied by
+[`openaca`](https://pypi.org/project/openaca/) and available under either
+name.
+
+## What it looks like
+
+```console
+$ stacktrace sessions --since 2d --include-content
+claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
+  assistant: Reading the changelog before drafting the release notes.
+    ok                28c  Read
+        result: ## 0.4.0 - correlate, detect
+  assistant: Filing the release-notes follow-up.
+                        -  github/create_issue
+
+Summary — 1 sessions, 2 turns, 2 tool calls
+
+  agent kinds
+          1  claude-code
+
+  tools called (2 distinct)
+          1  Read
+          1  github/create_issue
+
+  MCP servers reached (1 distinct)
+          1  github
+
+  0 subagent turns · 0 results abridged upstream · 1 ok
+
+1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.
+```
+
+A blank status column is the collector's `unknown`, not a pending call: the
+client recorded no outcome that could be established, and the closing line
+counts those rather than filling one in.
+
+## What `detect` finds
+
+Four kinds of finding, under two families that carry separate severity
+ladders — a stalled loop and a leaked credential do not belong on one scale.
+
+**Security** — a credential reaching an outbound call; an injected instruction
+the agent then followed; a vulnerable component actually reached, with the
+vulnerability behind it.
+
+**Reliability** — a loop that stalled; a call that hung.
+
+Findings are correlated against an Agent BOM before they are judged, so a
+vulnerable component is reported when something actually used it rather than
+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.
+
+`sessions` omits prompts, tool arguments and results unless you pass
+`--include-content`. `monitor` binds to loopback only, refuses a non-loopback
+address rather than warning about it, and escalates nothing unless `--escalate`
+is given.
+
+## Status
+
+Beta, and under active development.
+
+`sessions`, `detect` and `monitor` work end to end today. Session collection
+currently reads Claude Code transcripts; further agent kinds are in progress
+upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).
+
+## Built on
+
+Two Apache-2.0 packages, neither of which depends on this one:
+[`openaca`](https://pypi.org/project/openaca/) for agent composition analysis,
+and [`openaidr`](https://pypi.org/project/openaidr/) for session collection.
+
+## Licence
+
+Proprietary. © Stacktrace AI, Inc. — [stacktrace.ai](https://stacktrace.ai)

stacktrace_cli-0.2.2/README.md

@@ -0,0 +1,129 @@
+# stacktrace-cli
+
+Detection and response for AI coding agents, from the command line.
+
+Coding agents read files, run shell commands and call MCP servers on their own
+initiative, and they write a transcript of every bit of it to disk.
+`stacktrace` reads those transcripts, correlates what ran against the
+components the agent is built from, and reports the security and reliability
+findings in it — locally, on the machine the agent worked on.
+
+The PyPI distribution is `stacktrace-cli`; the command it installs is
+`stacktrace`. The two names differ because the bare `stacktrace` name on PyPI
+belongs to an unrelated project.
+
+## Installation
+
+```bash
+uv tool install stacktrace-cli     # isolated; recommended
+# or
+pip install stacktrace-cli
+```
+
+Requires Python 3.11 or newer.
+
+```console
+$ stacktrace --version
+stacktrace 0.2.1 (openaca 0.6.0)
+```
+
+## Quick start
+
+```bash
+stacktrace sessions      # what the agents on this machine did
+stacktrace detect        # what is wrong with it
+stacktrace monitor       # the same, live in a browser
+```
+
+## Commands
+
+| Command | |
+|---|---|
+| `sessions` | Print what the agents on this machine actually did. |
+| `detect` | Find security and reliability findings in what agents did. |
+| `monitor` | Watch this machine's agents in a browser, live. |
+| `remote` | Configure remote endpoint services and upload to Stacktrace Cloud. |
+| `scan` | Scan a repository or endpoint for agent-composition findings. |
+| `bom` | Generate an Agent BOM for a repository or endpoint. |
+| `policy` | Validate and compile restrictive endpoint policies. |
+
+The last three are composition analysis, supplied by
+[`openaca`](https://pypi.org/project/openaca/) and available under either
+name.
+
+## What it looks like
+
+```console
+$ stacktrace sessions --since 2d --include-content
+claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
+  assistant: Reading the changelog before drafting the release notes.
+    ok                28c  Read
+        result: ## 0.4.0 - correlate, detect
+  assistant: Filing the release-notes follow-up.
+                        -  github/create_issue
+
+Summary — 1 sessions, 2 turns, 2 tool calls
+
+  agent kinds
+          1  claude-code
+
+  tools called (2 distinct)
+          1  Read
+          1  github/create_issue
+
+  MCP servers reached (1 distinct)
+          1  github
+
+  0 subagent turns · 0 results abridged upstream · 1 ok
+
+1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.
+```
+
+A blank status column is the collector's `unknown`, not a pending call: the
+client recorded no outcome that could be established, and the closing line
+counts those rather than filling one in.
+
+## What `detect` finds
+
+Four kinds of finding, under two families that carry separate severity
+ladders — a stalled loop and a leaked credential do not belong on one scale.
+
+**Security** — a credential reaching an outbound call; an injected instruction
+the agent then followed; a vulnerable component actually reached, with the
+vulnerability behind it.
+
+**Reliability** — a loop that stalled; a call that hung.
+
+Findings are correlated against an Agent BOM before they are judged, so a
+vulnerable component is reported when something actually used it rather than
+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.
+
+`sessions` omits prompts, tool arguments and results unless you pass
+`--include-content`. `monitor` binds to loopback only, refuses a non-loopback
+address rather than warning about it, and escalates nothing unless `--escalate`
+is given.
+
+## Status
+
+Beta, and under active development.
+
+`sessions`, `detect` and `monitor` work end to end today. Session collection
+currently reads Claude Code transcripts; further agent kinds are in progress
+upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).
+
+## Built on
+
+Two Apache-2.0 packages, neither of which depends on this one:
+[`openaca`](https://pypi.org/project/openaca/) for agent composition analysis,
+and [`openaidr`](https://pypi.org/project/openaidr/) for session collection.
+
+## Licence
+
+Proprietary. © Stacktrace AI, Inc. — [stacktrace.ai](https://stacktrace.ai)

stacktrace_cli-0.2.2/docs/adrs/0028-the-console-shows-what-it-placed.md

@@ -0,0 +1,108 @@
+---
+id: 0028
+title: The console shows what it placed, and states no coverage
+status: accepted
+date: 2026-09-08
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+A reader opened `stacktrace monitor` on their own machine and asked why the
+busiest row on the page was red. The row was the grouped built-in row for one
+project — 4,467 calls over five days — and it carried `⚠ 16 refusals`. All 16
+were `user-rejected` in the transcript, and their recorded reasons were the
+Bash gate rather than a person: 29 `contains multiple operations`, 28 `requires
+approval`, 6 `changes directory before running git`, 3 `brace with quote
+character (expansion obfuscation)`, 2 `parser aborted`, 1 `contains
+for_statement` across the project's 70 denials. Nothing reached a tool.
+
+`sessions/outcome.py` already states the rule: *a denied call reached nothing,
+so it is evidence of nothing* — written after six sites had each grown their own
+`status == "rejected"` test. The page took that rule for its counters and then
+painted the row red anyway, which reports the permission prompt as the
+incident. ADR-0025 left this open deliberately: its Consequences name "a second
+counter every activity read surface must decide whether to show".
+
+The same page led with `⚠ unresolved` rows, an `Unresolved` row in the overview
+table, a legend line, and a `6,867/7,055 placed` header fraction. `unresolved`
+is a fact about the *record*, with four causes the reader cannot distinguish and
+none of which they can act on: absent from the composition, no composition for
+that agent kind, an ambiguous match, or a matched component whose type the
+category map does not know. The row names no component — `classify_call`
+returns no name for it by design (ADR-0027 admits a name at one position, and an
+activity row is not one) — so what reached the reader was "something happened
+and nothing here claims it", set in the page's warning colour.
+
+The rule that would have made such a call actionable, `unsanctioned-mcp-tool-use`,
+was withdrawn by ADR-0015. So no live rule is about an unplaceable call, and the
+page was warning about something it could not then explain.
+
+## Decision
+
+The console renders only activity it could place, and states no coverage
+figure. Rows whose category is `unresolved` are dropped at the page boundary;
+the `N/M placed` fraction and its `placing…` placeholder are gone from the
+header, which now counts sessions and the actions it actually shows; a refusal
+is counted in a row's `×N` and carries no badge and no colour; the
+no-composition banner is gone, leaving the two banners that report a *reader*
+which came back with nothing.
+
+The snapshot contract does not change. `_activity` still emits unresolved rows,
+`summary.coverage` and each session's `coverage` are still computed and still
+sent, `activity_for_upload` and the `denied` counter are untouched, and every
+detector rule reads what it always read. `stacktrace correlate` remains the
+surface where coverage and unplaceability are the subject; ADR-0026's clause
+holds, because a page that shows less has still invented nothing.
+
+## Alternatives considered
+
+- **Filter in `_activity`, server-side** — rejected. The snapshot is also the
+  `/api/state` contract and the thing `tests/monitor/test_render.py` holds; a
+  page decision that narrows the record makes the two disagree, and the next
+  surface built on the snapshot would inherit a filter it never asked for.
+- **Keep the rows, drop only the warning framing** — rejected by the person the
+  page is for. Neutral wording does not give the row a subject: with no
+  component name there is nothing for a reader to look up, so a quiet row is
+  the same non-answer in a calmer colour.
+- **Keep the coverage fraction** — rejected. The gap between numerator and
+  denominator *is* the count of rows the page no longer shows, so the header
+  restated by arithmetic exactly what the feed had stopped saying.
+- **Keep the red on refusals alone** — rejected. It is the page asserting the
+  opposite of `outcome.py`'s rule about the same call, and the measured reasons
+  above are a guardrail working, not an endpoint under attack.
+- **Reword the no-composition banner rather than remove it** — rejected after
+  trying it. "No Agent BOM found, so its components are not identified" is the
+  same claim one step back, and it sends a reader looking for rows that are no
+  longer there.
+
+## Consequences
+
+The page stops answering one question it used to answer badly: how much of the
+window it could not attribute. A reader who wants that runs `stacktrace
+correlate`, where the figure is the subject and the four causes are named
+separately; the fleet still receives it, because the upload path is untouched.
+
+The costs are real and worth naming. An agent kind with no Agent BOM now shows
+fewer categories in the overview table and says nothing about why — the built-in
+preview rows still appear, so the page does not go blank, but the absence is
+silent. A responder cannot see from the console that an MCP call went to a
+server no scan can find. And a denied-heavy endpoint — ADR-0025's own example of
+a fact visible on no surface — is still visible on none.
+
+**Watch for:** a second page-side filter added the same way, without an ADR,
+because this one made it look routine; and the header regaining any derived
+ratio, which is the shape this decision removed.
+
+## When to revisit
+
+If ADR-0015's `unsanctioned-mcp-tool-use` returns, revisit immediately: its
+evidence is exactly the rows this decision hides, and a finding whose subject
+cannot be seen on the page it is reported on is worse than either state alone.
+Also if the console gains an affordance for *why something is missing* — a
+per-kind detail view, say — which is where the coverage figure and the four
+causes belong, or if a remote surface starts reading the local snapshot and
+assuming the page's filtering rather than the record's contents.

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

@@ -60,3 +60,4 @@ supersedes anything yet.
 - [0026](0026-the-console-becomes-a-product-surface.md) — **The console becomes a product surface, served by the engine.** Supersedes ADR-0008 on its own stated condition: the engine came first, 0.1.0 shipped, and the data is only useful if a person can follow it. `stacktrace monitor` serves a loopback page from in-process calls, so the wheel now carries a `site/` asset — the cost 0008 refused, accepted here explicitly. What survives from 0008 is the clause that matters: the console renders and never computes, so a finding on the page is one `detect` would print. Read before adding anything to the console that the detector does not produce.
 - [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.

stacktrace_cli-0.2.2/docs/cutover-openaca-remote.md

@@ -0,0 +1,87 @@
+# The openaca 0.6.0 cutover
+
+Moved out of `README.md`, which is the PyPI long description and therefore a
+public page: this is operator and maintainer detail for a private repository.
+
+## Dependency resolution
+
+Both `openaca` and `openaidr` resolve from PyPI now, like any other
+dependency — no sibling checkout, no `[tool.uv.sources]` override. What still
+gates a release is narrower: both float on `>=` during normal development but
+must be pinned exactly (`==`) before a version is published, so a built wheel
+names precisely what it was tested against.
+`uv run pytest tests/test_release_readiness.py -m release_gate` checks that —
+the `release-stacktrace` skill runs it as part of cutting a release.
+
+
+## Cutover from `openaca remote`
+
+`stacktrace remote` is the hosted-service client OpenACA is removing. The
+behaviour, the payload and the Cloud endpoints are unchanged; only the code
+that produces them moved. Machines already running `openaca remote sync
+endpoint` need four steps each.
+
+1. **Have the collector token to hand, or mint a new one.** A collector token
+   cannot be recovered from the Cloud — it is returned once at issuance and
+   only a hash and its last four characters are kept — so it has to come from
+   wherever it was stored (an MDM secret store, a password manager). If it was
+   not stored, mint a new one and deploy that; nothing goes down while you do,
+   because the existing token keeps working until it is revoked.
+2. **Configure this machine.** `stacktrace remote configure --token …`, or set
+   `STACKTRACE_REMOTE_TOKEN` and `STACKTRACE_REMOTE_API_URL` for a scripted
+   deployment.
+3. **Repoint whatever schedules the sync** at `stacktrace remote sync
+   endpoint`.
+4. **Delete `~/.config/openaca/remote.toml`.** Once OpenACA has no `remote`
+   command, that file is an unused plaintext credential sitting on disk.
+   Nothing breaks if it stays, which is exactly why it will be forgotten.
+
+### What takes care of itself
+
+- **The asset converges.** Registration is idempotent on `(org, asset_type,
+  external_id)` with the host name as `external_id`, so registering from here
+  resolves to the same asset OpenACA registered — one extra round trip on the
+  first run, no duplicate machine in the console.
+- **Both commands may coexist during the overlap**, producing two BOM rows per
+  sync. That is noise rather than corruption.
+
+> These two statements, and the unrecoverability of a collector token in step
+> 1, describe what the deployed Cloud does. They have **not** been confirmed
+> against the running service for this release — they are read from the
+> hosted side's design, which records what some revision implements rather
+> than what production does today. Confirm them before an operator acts on
+> step 1 in particular: discarding the only copy of a token on the strength of
+> an unverified sentence leaves no recovery.
+
+### What does not
+
+- **A pending OpenACA spool is orphaned.** Its files are in
+  `~/.local/state/openaca`, and this channel never reads them. Drain it by
+  running the old command once before cutting over, or accept losing what it
+  holds. Do not assume that is one sync's worth: the spool keeps one file per
+  failed agent and accumulates across offline runs, so count the files first.
+- **The MDM deploy scripts and the scheduled agent** do not exist here yet.
+
+## Release obligations
+
+Finishing the remote-sync work was **not** the same as being releasable, and
+the gap was structural rather than a matter of polish: while `pyproject.toml`
+carried a path source to a sibling checkout, `pip install stacktrace-cli` from
+PyPI would have resolved an `openaca` without the consumption facade, and every
+`remote` command would have failed at import.
+
+All three are discharged, at `openaca` 0.6.0 — the first release carrying the
+facade:
+
+1. `[tool.uv.sources]` is gone; `uv.lock` resolves `openaca` from PyPI.
+2. `.github/workflows/ci.yml` checks out this repository alone. The sibling
+   checkout and its pinned-revision assertion went with the path source.
+3. The floor is `openaca>=0.6.0`, which is where plan 005 Task 1's
+   required-import probe first reports no missing name. Re-run that probe
+   against any candidate release before moving the floor again; it passes only
+   when it reports nothing missing.
+
+One proof retired with them. The payload-equivalence test imported openaca's
+`tools.remote` — the module 0.6.0 removed — so it cannot run against any
+release that carries the facade. What it established is a fact about the
+migration, not a property that a later release could re-check.

stacktrace_cli-0.2.2/docs/releases/v0.2.1.md

@@ -0,0 +1,49 @@
+# 0.2.1 — the page in front of the CLI
+
+For a distribution, the PyPI listing is the product surface a reader meets
+first. This release treats it as one. Nothing about what `stacktrace` does
+changes here — no command, flag, rule or output shape moves — and the whole
+delta is what the page in front of it claims.
+
+## Highlights
+
+- **The package metadata describes the product rather than a placeholder.**
+  The summary line said "Placeholder CLI for Stacktrace.ai — installs the
+  `stacktrace` command", written when that was true and left standing after
+  0.1.0 and 0.2.0 made it false. It now says what the CLI is for. Authorship
+  moves from an individual to Stacktrace AI, Inc., and
+  `Development Status :: 2 - Pre-Alpha` becomes `4 - Beta`, matching the
+  README's own Status section rather than contradicting it two clicks away.
+  `Operating System :: OS Independent` and per-minor Python classifiers for
+  3.11, 3.12 and 3.13 are added, so PyPI's own filters can find the package
+  under the versions `requires-python` already accepted.
+
+- **The README is written for someone deciding whether to install.** It was a
+  contributor's design document — Design, Adding a command, Development,
+  Release obligations — that happened to be the `readme` field, so the long
+  description on PyPI opened by explaining the repository to people who
+  already had it checked out. It now opens with what the tool does in three
+  sentences and continues into install, a three-command quick start, the
+  command table, real sample output, what `detect` finds, and what leaves your
+  machine. That last section is the one a security reader arrives looking for
+  and previously had to infer.
+
+- **The contributor material moved rather than being deleted.** The design and
+  workflow content is in `CLAUDE.md`, and the openaca 0.6.0 cutover notes and
+  release obligations are in `docs/cutover-openaca-remote.md`. Both stay in the
+  repository and neither is in the wheel.
+
+## Install
+
+`uv tool install stacktrace-cli==0.2.1` or `pip install stacktrace-cli==0.2.1`.
+
+## Compatibility
+
+Nothing to do. This release changes no behaviour: the CLI's commands, flags,
+output and upload payloads are identical to 0.2.0, and an existing install has
+no reason to upgrade beyond the version string.
+
+One note on the `Development Status :: 4 - Beta` classifier. It is a claim
+about the project's stage, not a back-compat promise — the terms 0.2.0 shipped
+under still hold, and interfaces can still change between releases without a
+deprecation window.

stacktrace_cli-0.2.2/docs/releases/v0.2.2.md

@@ -0,0 +1,76 @@
+# 0.2.2 — what the console shows
+
+`stacktrace monitor` shipped in 0.2.0 with two kinds of warning on it, and this
+release removes both. Neither pointed at something a reader could act on: one
+marked a call the correlator could not attribute, which names no component by
+design, and the other marked a call a permission prompt had already blocked.
+The engine is untouched — no rule, payload field, command or output shape
+moves — and the whole delta is what one page renders.
+
+## Highlights
+
+- **A blocked call is no longer an alarm.** A refusal is counted in its row's
+  `×N` and says nothing more: no `⚠ N refusals` badge, no red row. On the
+  machine that prompted this, 16 declined `Bash` calls out of 4,467 turned the
+  busiest row on the page red — and all 16 were the Bash gate refusing a
+  compound command, a `cd` before `git`, or an obfuscated brace. Nothing
+  reached a tool. `sessions/outcome.py` has held since 0.1.0 that a denied call
+  reached nothing, so it is evidence of nothing; the page took that rule for
+  its counters and then reddened the row anyway, which reports the permission
+  prompt as the incident. ADR-0025 left this to each surface deliberately, and
+  the console now answers it.
+
+- **The console shows only activity it could place.** The `⚠ unresolved` rows,
+  the `Unresolved` row in the overview table and the legend line describing
+  them are gone. An unplaced row carries no component name — that is a design
+  constraint, not an omission (ADR-0027 admits a name at one position, and an
+  activity row is not one) — so what reached the reader was "something happened
+  and nothing here claims it", with four causes behind it they could not
+  distinguish and none they could act on. The rule that would have made such a
+  call actionable was withdrawn by ADR-0015, so nothing on the page could
+  explain the warning it was showing.
+
+- **The header states no coverage figure.** `6,867/7,055 placed` and the
+  `placing…` placeholder it used while correlation ran are both gone: the gap
+  between those two numbers *is* the count of rows the page withholds, so the
+  header restated by arithmetic exactly what the rows had stopped saying. It
+  now reports sessions and the actions it actually shows — previously it read
+  `summary.actions`, the total over every call in the window, and so claimed
+  more actions than the feed below it could account for.
+
+- **A legend line that described nothing.** `✓ resolved to something you
+  installed` is removed. The page has never drawn that checkmark: the glyph
+  appeared in the legend and in no row, summary or card.
+
+- **The decision is recorded rather than implied.** ADR-0028 states it, lists
+  the five alternatives and is explicit about the costs — an agent kind with no
+  Agent BOM is now silent on the page, and ADR-0025's denied-heavy endpoint is
+  still visible on no surface. `docs/specs/monitor.md` said the opposite in four
+  places and now describes what ships.
+
+## Install
+
+`uv tool install stacktrace-cli==0.2.2` or `pip install stacktrace-cli==0.2.2`.
+
+## Compatibility
+
+Nothing to do, and nothing outside the console changes. `stacktrace detect`,
+`stacktrace correlate` and `stacktrace sync detect` produce byte-identical
+output to 0.2.1, the upload payload is unchanged, and every detector rule reads
+what it always read. No finding is suppressed — ADR-0026's clause that the
+console renders and never judges still holds, and a page that shows fewer
+activity rows invents nothing.
+
+The `/api/state` document is also unchanged: it still carries the unplaced
+activity rows and both coverage figures. The filter is applied in the page, so
+anything reading that endpoint sees the same record 0.2.1 served.
+
+Two things you will notice if you relied on them. Coverage is no longer on the
+console — run `stacktrace correlate`, where it is the subject and the four
+causes of an unplaced call are named separately. And an agent kind with no
+Agent BOM no longer raises a banner: its built-in rows still appear, so the
+page does not go blank, but the absence is reported by `correlate` rather than
+on screen.
+
+Still pre-alpha, with no back-compat hedging: interfaces can change between
+releases without a deprecation window.