stacktrace-cli 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
-"""Placeholder CLI package for Stacktrace.ai."""
+"""The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

stacktrace_cli/monitor/render.py

@@ -176,6 +176,12 @@ def _banners(analysis: Analysis) -> list[str]:
     A blank column and a clean run render identically, which is the one
     confusion this page refuses: a reader who cannot tell "nothing happened"
     from "nothing could be read" has been told nothing.
+
+    Both banners are about a *reader* that came back with nothing. A kind with
+    no composition is not one of those and no longer appears: the calls it
+    accounts for are read, and the page shows what it can place them to.
+    `view.without_composition` is still reported by `stacktrace correlate`,
+    where the record rather than the console is the subject.
     """
     banners: list[str] = []
     for failure in analysis.run.collection_failures:
@@ -183,8 +189,6 @@ def _banners(analysis: Analysis) -> list[str]:
     anonymous = len(analysis.view.kind_anonymous)
     if anonymous:
         banners.append(f"{anonymous} session(s) skipped: no agent kind to attribute them to")
-    for kind in analysis.view.without_composition:
-        banners.append(f"{kind}: no composition, so every call reads as unresolved")
     return banners
 
 

stacktrace_cli/monitor/site/app.js

@@ -145,16 +145,20 @@ function renderBanners(banners) {
 
 function renderCounts(state) {
   const summary = state.summary || {};
-  /* Coverage is a fraction, never a bare percentage: 1 of 1 and 400 of 400 are
-   * both "100%" and say very different things about how much this page knows.
-   * And it is `null` until correlation has run, which is the first second or
-   * so — said as "placing…" rather than shown as 0/0, which would read as
-   * "nothing placed" instead of "not counted yet". */
-  const coverage = summary.coverage;
+  /* Sessions and actions, and no coverage fraction. `6,867/7,055 placed` is
+   * the count of what this page leaves off, stated: the gap between the two
+   * numbers is exactly the unplaceable rows, so the header reinstated by
+   * arithmetic what the rows below had stopped saying. The snapshot still
+   * carries it — `stacktrace correlate` is where coverage is the subject.
+   *
+   * Actions are counted off the rows this page keeps rather than read from
+   * `summary.actions`, which is the server's total over every call in the
+   * window. Read straight through, the header claimed more actions than the
+   * feed below it could account for. */
+  const actions = eventsFrom(state.sessions || []).length;
   text(el("live-counts"),
     " — " + plural(summary.sessions || 0, "session") +
-    " · " + plural(summary.actions || 0, "action") +
-    " · " + (coverage ? coverage.resolved + "/" + coverage.total + " placed" : "placing…"));
+    " · " + plural(actions, "action"));
 }
 
 /* --- the demo's vocabulary ----------------------------------------------- */
@@ -209,7 +213,6 @@ const RULE_PLAIN = {
   "stacktrace-credential-egress": "A password or token was sent to an outside service.",
   "stacktrace-capability-crossing": "Private data was read, then sent outside.",
   "stacktrace-intent-drift": "It acted on something nobody asked about.",
-  "stacktrace-unsanctioned-mcp-tool-use": "A tool ran that isn't in your installed set.",
   "stacktrace-guardrail-modification": "A session changed the agent's own rules or settings.",
   "stacktrace-injection-marker": "Injected-instruction markers were found in what the agent read.",
   "stacktrace-destructive-action": "A destructive action was taken (deleting or overwriting).",
@@ -227,20 +230,32 @@ const KIND_TAG = {
   subagent: ["sub-agent", "kt-sub"],
   mcp: ["mcp", "kt-conn"],
   command: ["command", "kt-cmd"],
-  unresolved: ["⚠ unresolved", "kt-warn"],
 };
 
 /* Plural, because every one of these labels a count. */
 const KIND_LABEL = {
   mcp: "MCP servers", skill: "Skills", command: "Commands",
-  subagent: "Sub-agents", tool: "Built-in tools", unresolved: "Unresolved",
+  subagent: "Sub-agents", tool: "Built-in tools",
 };
 
 /* Most consequential first, rather than by count: sorted by count the
  * built-ins win every window and push the MCP servers — the only category
  * describing a call that left the machine — under a number three orders of
  * magnitude larger. */
-const KIND_ORDER = ["mcp", "skill", "command", "subagent", "tool", "unresolved"];
+const KIND_ORDER = ["mcp", "skill", "command", "subagent", "tool"];
+
+/* The category the correlator gives a call it could not place. Every surface
+ * on this page drops these rows: an unplaceable call names no component, so
+ * the row could only say that something happened and nothing here claims it,
+ * which is not a thing a reader can act on. The count is still computed
+ * server-side and still reaches the detector — this is a decision about the
+ * page, not about the record. */
+const UNPLACEABLE = "unresolved";
+
+/* Whether the snapshot row is one of those. */
+function unplaceable(row) {
+  return row.category === UNPLACEABLE;
+}
 const TOP_PER_KIND = 3;
 
 const SEVERITY_WORD = { critical: "Serious", high: "High", medium: "Medium", low: "Low" };
@@ -294,10 +309,13 @@ function evParts(e) {
       provenance: "a link to an outside service",
     };
   }
+  /* A category this build has never heard of. Named as itself rather than
+   * described: anything else this function said about it would be invented,
+   * and the one category it used to describe no longer reaches the page. */
   return {
     name: e.name,
-    action: "used a tool nothing here claims",
-    provenance: "no component on this machine declares it",
+    action: "used " + (e.tool || "a tool"),
+    provenance: e.kind ? "category " + e.kind : "",
   };
 }
 
@@ -321,6 +339,7 @@ function eventsFrom(sessions) {
     const activity = session.activity || [];
     for (let index = 0; index < activity.length; index += 1) {
       const row = activity[index];
+      if (unplaceable(row)) continue;
       events.push({
         id: row.span,
         kind: row.category,
@@ -336,11 +355,6 @@ function eventsFrom(sessions) {
          * the skills a reader had just run sat under MCP calls from half a day
          * earlier. Named for what it is, because it is not the start. */
         at: session.last_active || session.started_at,
-        /* Both worth a reader's attention; only the first is a claim about
-         * attribution. Correlation keeps a refused call's resolution, so the
-         * row beside the label names the component it would have reached. */
-        unplaced: row.category === "unresolved",
-        refused: row.status === "denied",
         order: index,
       });
     }
@@ -356,7 +370,8 @@ function compositionOf(sessions) {
   const seen = new Set();
   for (const session of sessions) {
     for (const row of session.activity || []) {
-      const type = row.component_type || (row.category === "unresolved" ? null : row.category);
+      if (unplaceable(row)) continue;
+      const type = row.component_type || row.category;
       const key = type + "\n" + (row.component_identity || row.component_name || row.tool_name);
       if (!type || seen.has(key)) continue;
       seen.add(key);
@@ -372,6 +387,7 @@ function activitySummaryOf(sessions) {
   const named = {};
   for (const session of sessions) {
     for (const row of session.activity || []) {
+      if (unplaceable(row)) continue;
       byKind[row.category] = (byKind[row.category] || 0) + 1;
       if (!named[row.category]) named[row.category] = new Map();
       const label = entryLabel(row);
@@ -531,9 +547,9 @@ let revealTimer = null;
  * Routine built-ins (Bash, Read, Edit) are the constant background of every
  * session: 5,795 of one window's 7,065 calls. They collapse **per project**
  * into one counting row for the agent. Notable events — skills, MCP servers,
- * sub-agents, commands, and anything unresolved — are rare and important, so
- * each gets its own row, keyed by span and never coalesced: two runs of
- * `superpowers:brainstorming` are two things that happened.
+ * sub-agents and commands — are rare and important, so each gets its own row,
+ * keyed by span and never coalesced: two runs of `superpowers:brainstorming`
+ * are two things that happened.
  *
  * Grouping by tool name instead gave `Bash ×38 / Read ×16 / Bash ×3 / Edit
  * ×20` per session, with every skill and connector buried under it. */
@@ -609,14 +625,6 @@ function countAgain(entry, e) {
       entry.timeEl.textContent = fmtRange(entry.first, entry.last);
     }
   }
-  /* A refusal is worth seeing and was not worth a row of its own: `Bash ×3
-   * denied` beside `Bash ×38` was half the noise. It rides the row instead. */
-  if (e.refused) {
-    entry.refused += 1;
-    entry.node.classList.add("warn");
-    entry.warnEl.hidden = false;
-    entry.warnEl.textContent = "⚠ " + plural(entry.refused, "refusal");
-  }
   /* Animated where it sits, never hoisted. Hoisting the most recently counted
    * row would rank a busy week-old session above a quiet one from this
    * morning: during a backfill, "counted just now" is a fact about the drain
@@ -656,14 +664,19 @@ function place(entry) {
 
 function newRow(e, signature) {
   const parts = evParts(e);
-  const kind = KIND_TAG[e.kind] || KIND_TAG.unresolved;
+  /* A category this build has never heard of takes its own name and the
+   * neutral tag: nothing on this page knows enough about it to warn. */
+  const kind = KIND_TAG[e.kind] || [e.kind || "", "kt-tool"];
   /* The placeholder goes as soon as there is a real row — otherwise it rides
    * the list and counts against the trim. */
   if (!feedOrder.length) activityFeed.innerHTML = "";
 
+  /* No row this feed builds is reddened. The two sources of it were a call
+   * the correlator could not place — which no longer reaches the feed — and a
+   * refusal, which `outcome.py` is explicit is a guardrail working as
+   * intended: painting it red reports the permission prompt as the incident. */
   const node = document.createElement("div");
   node.className = "ev fresh";
-  if (e.unplaced || e.refused) node.classList.add("warn");
 
   const countEl = element("span", "evcount", "");
   countEl.hidden = true;
@@ -674,16 +687,6 @@ function newRow(e, signature) {
   first.appendChild(element("span", "evact", parts.action));
   first.appendChild(countEl);
 
-  const warnEl = element("span", "ev-warn", "");
-  warnEl.hidden = true;
-  if (e.unplaced) {
-    warnEl.hidden = false;
-    warnEl.textContent = "unplaced";
-  } else if (e.refused) {
-    warnEl.hidden = false;
-    warnEl.textContent = e.kind === "tool" ? "⚠ 1 refusal" : "refused";
-  }
-
   const lastEl = element("span", "evlast", "");
   const timeEl = element("span", "ev-time", fmtAgo(e.at));
 
@@ -692,15 +695,14 @@ function newRow(e, signature) {
   second.appendChild(element("span", "ev-prov", parts.provenance));
   second.appendChild(lastEl);
   second.appendChild(timeEl);
-  second.appendChild(warnEl);
 
   node.appendChild(first);
   node.appendChild(second);
 
   const started = Date.parse(e.at);
   const entry = {
-    node: node, countEl: countEl, warnEl: warnEl, lastEl: lastEl, timeEl: timeEl,
-    count: 1, refused: e.refused ? 1 : 0, key: keyOf(e), signature: signature,
+    node: node, countEl: countEl, lastEl: lastEl, timeEl: timeEl,
+    count: 1, key: keyOf(e), signature: signature,
     first: Number.isNaN(started) ? Infinity : started,
     last: Number.isNaN(started) ? -Infinity : started,
   };

stacktrace_cli/monitor/site/index.html

@@ -74,8 +74,6 @@
 
   <div class="legend" id="live-legend">
     <span><b class="lg-conn">MCP</b> = a link to an outside service</span>
-    <span><b class="lg-ok">&#10003;</b> resolved to something you installed</span>
-    <span><b class="lg-warn">&#9888;</b> unresolved &mdash; nothing on this machine claims it</span>
   </div>
 
   <div class="logs">

stacktrace_cli-0.2.2.dist-info/METADATA

@@ -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.0.dist-info → stacktrace_cli-0.2.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-stacktrace_cli/__init__.py,sha256=zFmwu-uAxGO6WN6at3FvWvkcCPmqX5B-jaZNzGTzcf0,72
+stacktrace_cli/__init__.py,sha256=7-HhS3y6stqt0b0tldy0IhMr_bOjUk_HMTHwNj4LgyI,111
 stacktrace_cli/__main__.py,sha256=F_tqj3PRzeBtY-uvBs923H8oc-s9bebhIh6UnAUwNYc,448
 stacktrace_cli/analysis.py,sha256=PECyhd_398fDVjg3K78HVzB4xHYS7sfLNXpASRXNRsY,15303
 stacktrace_cli/cli.py,sha256=tJjGtGlaI6OB4bdlgX3q63VffZxRIjwiCwH54kzxRAo,17032
@@ -32,13 +32,13 @@ stacktrace_cli/detector/prompts/v1/stacktrace-injected-instruction-followed.md,s
 stacktrace_cli/detector/prompts/v1/stacktrace-intent-drift.md,sha256=1dI4bUIonwm6t2x32GnV-yGNfb1jGibeBo6Wli62WZI,455
 stacktrace_cli/monitor/__init__.py,sha256=akhxzlSGyvbG-3WyC-5Ch5nuYP1E6xga8rzkJ6Tn-AU,469
 stacktrace_cli/monitor/escalate.py,sha256=tpkp88xKyHX0BRVFow8b9_8YswduAAofidMiZBpRix4,7398
-stacktrace_cli/monitor/render.py,sha256=0Wb3Q6y6VRo6GCkULuyqvC7huzCdOejyjeMInxz1DTg,9835
+stacktrace_cli/monitor/render.py,sha256=oR3Sr2Tlk2_NtpVmJfLnU_IH-bkXIs7p4a27OZgn4mY,10064
 stacktrace_cli/monitor/server.py,sha256=ZTKUy3Ct-7rfsErN3Cpr5PaaZ5SX_OMw-ExFe6FKL9w,19683
 stacktrace_cli/monitor/state.py,sha256=UVTLpAecypsLTBs5IdWlY55dyJTf-2jI8lDAWoH9PP4,4157
 stacktrace_cli/monitor/verdicts.py,sha256=V6IK2C9eVxZ2RXjWkfDdmfvN8f-Ol67U-N5c1kXx8rQ,2275
 stacktrace_cli/monitor/watch.py,sha256=LrbS6RnZg322tbESQ4u2rTVxhkxsNI5UwdhpTEO3GgE,15546
-stacktrace_cli/monitor/site/app.js,sha256=zk_dVPLp174NTaHcBi0SEQGkGxl4fiOIf4Y77MHnKKc,43668
-stacktrace_cli/monitor/site/index.html,sha256=7zOdxjo6GkfaG56kwvP8Zm66ITyO-Wadn6kO99qVpDM,4169
+stacktrace_cli/monitor/site/app.js,sha256=CM28lPaxuy-oourHb85jw35NDhqnFpYxc0bKgQsLrX0,43898
+stacktrace_cli/monitor/site/index.html,sha256=OhbyY9Dnvec90IMc9a8iGBZdgfk38aNmbyhwhrrLXYM,3985
 stacktrace_cli/monitor/site/styles.css,sha256=ol_sSrn2Jwk5xAtz9Avq2itUp9r1Z-nv6sf7KSwNSlU,35603
 stacktrace_cli/monitor/site/fonts/OFL.txt,sha256=3eGN4fg4dKG6QBHOpLJobIeUAs3eQnmZBiykH5b-TGY,9975
 stacktrace_cli/monitor/site/fonts/dm-mono-400-latin.woff2,sha256=_XUh81MaXM_GVbJcTyLphx3z7BQa15uyf94g0N80e20,8688
@@ -61,7 +61,7 @@ stacktrace_cli/sessions/access.py,sha256=mpKMdRufPGTZNJCVPa2MoKWdM8eOYzaYMDsGqob
 stacktrace_cli/sessions/outcome.py,sha256=IQUrOoigPAFHnoA26LlOjSSB8hnSQUIJ8E5tQ0LdUJk,2632
 stacktrace_cli/sessions/protocols.py,sha256=rvQsVd77AekNGhp73masMa61-DbG62QF8Y6hDSwQ9bU,6630
 stacktrace_cli/sessions/render.py,sha256=SCu9Fx-7hWQWOsy3O7zbYzJqCNomaMp_19V7NQTkSm0,14001
-stacktrace_cli-0.2.0.dist-info/METADATA,sha256=iEleN0DaSaEryusQgOIzHwhGw-u2cLLZ4o6b6NQdwzo,10384
-stacktrace_cli-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-stacktrace_cli-0.2.0.dist-info/entry_points.txt,sha256=OYDmb2CtEjd8TV78zxiGB1XVrLrC6vvayAPXa79_tJ0,60
-stacktrace_cli-0.2.0.dist-info/RECORD,,
+stacktrace_cli-0.2.2.dist-info/METADATA,sha256=uAgSCLSXgp-IdFJ8L3jwRT9Z_GEjNQeFv7608lCBcQY,5459
+stacktrace_cli-0.2.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+stacktrace_cli-0.2.2.dist-info/entry_points.txt,sha256=OYDmb2CtEjd8TV78zxiGB1XVrLrC6vvayAPXa79_tJ0,60
+stacktrace_cli-0.2.2.dist-info/RECORD,,

stacktrace_cli-0.2.0.dist-info/METADATA

@@ -1,228 +0,0 @@
-Metadata-Version: 2.5
-Name: stacktrace-cli
-Version: 0.2.0
-Summary: Placeholder CLI for Stacktrace.ai — installs the `stacktrace` command.
-Project-URL: Homepage, https://stacktrace.ai
-Author-email: Prasanth G <prasanth@openaca.dev>
-License-Expression: LicenseRef-Proprietary
-Keywords: agent-security,ai-security,openaca,stacktrace
-Classifier: Development Status :: 2 - Pre-Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-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
-
-Command-line interface for [Stacktrace.ai](https://stacktrace.ai).
-
-The PyPI distribution is named `stacktrace-cli`  Installing this package provides
-the `stacktrace` executable.
-
-```bash
-pip install stacktrace-cli
-stacktrace --version
-```
-
-This is an early placeholder release. It depends on
-[`openaca`](https://pypi.org/project/openaca/), the open-source Agent
-Composition Analysis toolkit that Stacktrace.ai builds on.
-
-## Design
-
-This repository is the design home for Stacktrace Detect — the agentic AI
-detection and response product this CLI grows into. OpenACA answers *what is
-installed and what could it do*; Stacktrace Detect adds *what did it actually
-do*, by joining agent session activity to the composition graph.
-
-| Document | Covers |
-|---|---|
-| [docs/specs/aidr.md](docs/specs/aidr.md) | Umbrella — components, contracts, tenets, delivery |
-| [docs/specs/session-input.md](docs/specs/session-input.md) | The seam over OpenAIDR, which collects sessions |
-| [docs/specs/correlation.md](docs/specs/correlation.md) | The join: sessions against the composition graph |
-| [docs/specs/detector.md](docs/specs/detector.md) | Three-stage detection and the finding family |
-
-Decisions are in [docs/adrs/](docs/adrs/).
-
-Built on two Apache-2.0 packages, neither of which depends on this one:
-[`openaca`](https://pypi.org/project/openaca/) for composition analysis, and
-[`openaidr`](https://github.com/open-agent-security/openaidr) for session
-collection.
-
-## Status
-
-`stacktrace` is one front door over two kinds of command:
-
-```
-Analysis (OpenACA):
-  bom     Generate an Agent BOM for a repository or endpoint.
-  policy  Validate and compile restrictive endpoint policies.
-  scan    Scan a repository or endpoint for agent-composition findings.
-
-Stacktrace:
-  detect    Find security and reliability findings in what agents did.
-  remote    Configure remote endpoint services.
-  sessions  Print what the agents on this machine actually did.
-```
-
-`stacktrace` is the entry point for hosted-product users. OpenACA remains the
-tool itself and stays independently installable — with it installed, both
-`openaca scan` and `stacktrace scan` work and do exactly the same thing,
-because they are the same Click command object running in one process.
-`stacktrace --version` reports both versions, which turns "which did you run?"
-into one answered question.
-
-**Pre-alpha, and not installable from PyPI yet.** `stacktrace sessions` works —
-it reads what the agents on this machine did, through
-[OpenAIDR](https://github.com/open-agent-security/openaidr):
-
-```console
-$ uv run 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.
-```
-
-The blank status on the second row is the collector's `unknown`, not a pending
-call: the client recorded no outcome it could establish, and the closing line
-says how many of those there were rather than filling one in.
-
-The next step is the join: resolving what ran to the components the agent is
-built from. `detect` performs it — it correlates the collected sessions against
-an Agent BOM before it judges anything — but there is no longer a command that
-prints the correlated view on its own. `stacktrace correlate` was withdrawn; the
-correlation code stays, as the stage `detect` is built on.
-
-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.
-
-## 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.
-
-
-## Development
-
-`uv sync` and the four gates — `ruff check`, `ruff format --check`, `pyright`,
-`pytest` — need nothing beside this repository. `openaca` resolves from PyPI at
-the floor `pyproject.toml` declares. A sibling `../openaca` checkout is no
-longer read: the interim `[tool.uv.sources]` path source retired at the 0.6.0
-cutover.
-
-## 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.