stacktrace-cli 0.3.1__tar.gz → 0.4.0__tar.gz

{stacktrace_cli-0.3.1 → stacktrace_cli-0.4.0}/.agents/skills/release-stacktrace/SKILL.md

@@ -42,11 +42,12 @@ git rev-parse --verify "v<version>" 2>/dev/null    # MUST FAIL — tag must not
 test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
 ```
 
-`tests/test_release_readiness.py -m release_gate` is **not** run here: it
-requires `openaca`/`openaidr` pinned exactly, which is not true of a normal
-checkout (both float on `>=` between releases) and is only made true by
-Step 4. Running it against an unpinned tree would fail on every release, not
-just a broken one. It runs at the end of Step 4, once its precondition holds.
+The `release_gate` marker is **not** run here: `test_release_readiness.py`'s
+share of it requires `openaca`/`openaidr` pinned exactly, which is not true of
+a normal checkout (both float on `>=` between releases) and is only made true
+by Step 4. Running it against an unpinned tree would fail on every release,
+not just a broken one. It runs at the end of Step 4, once its precondition
+holds.
 
 PyPI versions are immutable, including yanked ones. If `<version>` is
 already on PyPI, the only path forward is a new version number:
@@ -146,16 +147,20 @@ openaidr_version=$(grep -A1 '^name = "openaidr"' uv.lock | grep version | cut -d
 sed -i.bak -E "s/^    \"openaca(>=|==)[^\"]*\"/    \"openaca==${openaca_version}\"/" pyproject.toml && rm pyproject.toml.bak
 sed -i.bak -E "s/^    \"openaidr(>=|==)[^\"]*\"/    \"openaidr==${openaidr_version}\"/" pyproject.toml && rm pyproject.toml.bak
 uv lock                                            # refresh uv.lock for the exact pin
-uv run pytest tests/test_release_readiness.py -m release_gate
+uv run pytest -m release_gate
 ```
 
-The gate is not covered by `.github/workflows/publish-pypi.yml`, which runs
-the default `uv run pytest -q` — and `pyproject.toml`'s `addopts` excludes
-`release_gate` from that default run on purpose (it fails throughout normal
-development, before this step pins the floors). This skill is the only place
-it runs before a tag is pushed, so skipping it here is the one way a version
-with an unpinned `openaidr`/`openaca` requirement reaches PyPI. Stop and ask
-if it fails.
+By marker, not by file: a second `release_gate` test can be added anywhere
+under `tests/` (as `tests/telemetry/test_release_gate.py` was, checking that
+PostHog's project key is set) and this command picks it up without the skill
+needing to name it. The gate is not covered by `.github/workflows/publish-pypi.yml`,
+which runs the default `uv run pytest -q` — and `pyproject.toml`'s `addopts`
+excludes `release_gate` from that default run on purpose (it fails throughout
+normal development, before this step pins the floors and, for the PostHog key,
+before Micheal fills it in). This skill is the only place any `release_gate`
+test runs before a tag is pushed, so skipping it here, or naming only one file
+here, is the one way an unpinned `openaidr`/`openaca` requirement or an unset
+PostHog key reaches PyPI. Stop and ask if it fails.
 
 ### Step 5. Release-prep commit + PR
 

{stacktrace_cli-0.3.1 → stacktrace_cli-0.4.0}/.github/workflows/claude.yml

@@ -99,6 +99,16 @@ jobs:
         id: claude
         uses: anthropics/claude-code-action@v1
         with:
+          # Keep pre-push checks attached to the session until they finish.
+          # Background pushes can be abandoned when the model ends its turn.
+          settings: |
+            {
+              "env": {
+                "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "1",
+                "BASH_DEFAULT_TIMEOUT_MS": "600000"
+              }
+            }
+
           # Subscription-tied OAuth path. Provision via `claude setup-token`
           # CLI and store as the CLAUDE_CODE_OAUTH_TOKEN repo secret.
           #

{stacktrace_cli-0.3.1 → stacktrace_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.3.1
+Version: 0.4.0
 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>
@@ -10,7 +10,8 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: Other/Proprietary License
-Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -19,8 +20,9 @@ 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
+Requires-Dist: openaca==0.7.0
+Requires-Dist: openaidr==0.3.0
+Requires-Dist: posthog<8,>=7.0
 Description-Content-Type: text/markdown
 
 # stacktrace-cli
@@ -49,7 +51,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.3.1 (openaca 0.6.0)
+stacktrace 0.4.0 (openaca 0.7.0)
 ```
 
 ## Quick start
@@ -81,10 +83,10 @@ name.
 ```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.
+  2026-08-29T12:00:00+00:00  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.
+  2026-08-29T12:00:00+00:00  assistant: Filing the release-notes follow-up.
                         -  github/create_issue
 
 Summary — 1 sessions, 2 turns, 2 tool calls
@@ -110,31 +112,61 @@ 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.
+Three kinds of finding, under two families that carry separate severity
+ladders — a blocked agent 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.
+**Security** — a credential reaching an outbound call; success reported against
+the session's own evidence of failure.
 
-**Reliability** — a loop that stalled; a call that hung.
+**Reliability** — why the agent stopped, in words, with what to do about it: a
+spend limit reached, a safety check blocking, a service refusing a call.
 
-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.
+Findings are correlated against an Agent BOM before they are reported, so one
+that names a component names the one a call actually reached.
 
 ## What leaves your machine
 
-Two of `detect`'s three stages run entirely locally and need no model or
-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 `--reasoning`, capped by
-`--budget`.
+**On a default run**, `detect` reads the record on this machine. It needs no
+model, no credential and no account, and nothing derived from a session — no
+prompt, no tool argument, no result — is sent anywhere.
+
+One network call is made even then, and it is worth stating because *nothing
+leaves* is not what happens: correlation matches advisories by sending the
+package coordinates of the components a session invoked to osv.dev.
+Coordinates only.
+
+**One flag pair changes that, and it has to be typed in full.** `detect
+--reasoning --analyzer jev` adds a third stage that sends two small states to
+TypeSafe's Jev: a *gate* carrying the closing lines of each hand-back, capped,
+which ends most sessions there — and, for a session that clears it, one
+per-call *window* each carrying a completion claim, one verification command
+and the tail of its output. Neither flag has a default and neither implies the other,
+so naming the vendor is your act rather than ours (ADR-0033). Without both,
+stage three is not asked. `detect --analyzer jev` alone reads back what such a
+run already paid for and commissions nothing (ADR-0035).
 
 `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 analyses nothing with a model unless
-`--reasoning` is given.
+`--include-content`. `monitor` binds to loopback only, and refuses a
+non-loopback address rather than warning about it.
+
+**Usage telemetry is enabled by default.** Disable it before normal use with
+`stacktrace telemetry off`. An existing opt-out stays off; unreadable or invalid
+settings also disable telemetry. The first enabled usage event creates a random
+identifier. The daemon sends four event types to PostHog's US region: an enabled
+identity first becomes active, a session starts, a finding is delivered, or a
+product error occurs. Event fields describe the rule, severity, destination,
+reason code or error category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`) and timestamp.
+`environment` is `production` unless `STACKTRACE_TELEMETRY_ENV` is set to
+`staging`, `development` or `test`. They do not
+include prompts, tool arguments, results, full findings, paths or repository
+names. The persistent identifier and timing mean this is not anonymous data.
+
+`stacktrace telemetry show` prints the state, the destination, the environment,
+the identifier and every event with every property it may carry. `off` deletes
+the local identifier; it does not delete previously uploaded records, and an
+event already handed to the client may still be sent. `stacktrace telemetry on`
+enables telemetry again under a new identity (ADR-0039).
+`STACKTRACE_TELEMETRY_DISABLED=1` sends nothing, for CI and test runs.
 
 ## Status
 

stacktrace_cli-0.4.0/README.md

@@ -0,0 +1,160 @@
+# 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.4.0 (openaca 0.7.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
+  2026-08-29T12:00:00+00:00  assistant: Reading the changelog before drafting the release notes.
+    ok                28c  Read
+        result: ## 0.4.0 - correlate, detect
+  2026-08-29T12:00:00+00:00  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
+
+Three kinds of finding, under two families that carry separate severity
+ladders — a blocked agent and a leaked credential do not belong on one scale.
+
+**Security** — a credential reaching an outbound call; success reported against
+the session's own evidence of failure.
+
+**Reliability** — why the agent stopped, in words, with what to do about it: a
+spend limit reached, a safety check blocking, a service refusing a call.
+
+Findings are correlated against an Agent BOM before they are reported, so one
+that names a component names the one a call actually reached.
+
+## What leaves your machine
+
+**On a default run**, `detect` reads the record on this machine. It needs no
+model, no credential and no account, and nothing derived from a session — no
+prompt, no tool argument, no result — is sent anywhere.
+
+One network call is made even then, and it is worth stating because *nothing
+leaves* is not what happens: correlation matches advisories by sending the
+package coordinates of the components a session invoked to osv.dev.
+Coordinates only.
+
+**One flag pair changes that, and it has to be typed in full.** `detect
+--reasoning --analyzer jev` adds a third stage that sends two small states to
+TypeSafe's Jev: a *gate* carrying the closing lines of each hand-back, capped,
+which ends most sessions there — and, for a session that clears it, one
+per-call *window* each carrying a completion claim, one verification command
+and the tail of its output. Neither flag has a default and neither implies the other,
+so naming the vendor is your act rather than ours (ADR-0033). Without both,
+stage three is not asked. `detect --analyzer jev` alone reads back what such a
+run already paid for and commissions nothing (ADR-0035).
+
+`sessions` omits prompts, tool arguments and results unless you pass
+`--include-content`. `monitor` binds to loopback only, and refuses a
+non-loopback address rather than warning about it.
+
+**Usage telemetry is enabled by default.** Disable it before normal use with
+`stacktrace telemetry off`. An existing opt-out stays off; unreadable or invalid
+settings also disable telemetry. The first enabled usage event creates a random
+identifier. The daemon sends four event types to PostHog's US region: an enabled
+identity first becomes active, a session starts, a finding is delivered, or a
+product error occurs. Event fields describe the rule, severity, destination,
+reason code or error category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`) and timestamp.
+`environment` is `production` unless `STACKTRACE_TELEMETRY_ENV` is set to
+`staging`, `development` or `test`. They do not
+include prompts, tool arguments, results, full findings, paths or repository
+names. The persistent identifier and timing mean this is not anonymous data.
+
+`stacktrace telemetry show` prints the state, the destination, the environment,
+the identifier and every event with every property it may carry. `off` deletes
+the local identifier; it does not delete previously uploaded records, and an
+event already handed to the client may still be sent. `stacktrace telemetry on`
+enables telemetry again under a new identity (ADR-0039).
+`STACKTRACE_TELEMETRY_DISABLED=1` sends nothing, for CI and test runs.
+
+## 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.3.1 → stacktrace_cli-0.4.0}/docs/adrs/0004-three-stage-detector.md

@@ -6,7 +6,7 @@ date: 2026-08-27
 supersedes: null
 superseded-by: null
 amends: null
-amended-by: 0029
+amended-by: 0029, 0033
 ---
 
 ## Context

{stacktrace_cli-0.3.1 → stacktrace_cli-0.4.0}/docs/adrs/0006-trust-boundary-and-detection-upload.md

@@ -5,7 +5,7 @@ status: accepted
 date: 2026-08-28
 supersedes: null
 superseded-by: null
-amended-by: 0011, 0027
+amended-by: 0011, 0027, 0031, 0039
 ---
 
 ## Context

{stacktrace_cli-0.3.1 → stacktrace_cli-0.4.0}/docs/adrs/0011-verdict-cache.md

@@ -6,6 +6,7 @@ date: 2026-08-31
 supersedes: null
 superseded-by: null
 amends: 0006
+amended-by: 0033
 ---
 
 ## Context

stacktrace_cli-0.4.0/docs/adrs/0030-a-detection-is-dated-by-the-turns-it-cites.md

@@ -0,0 +1,104 @@
+---
+id: 0030
+title: A detection is dated by the turns it cites
+status: accepted
+date: 2026-09-15
+supersedes: null
+superseded-by: null
+---
+
+## Context
+
+A finding carried no time of its own. `Detection` had no timestamp, `Evidence`
+was `(span, kind, detail)`, and `SessionRef` carried the session's `started_at`
+— so every surface answered "when did this happen" with the session's start.
+
+That is wrong by however long the session ran. OpenAIDR takes `started_at` from
+the transcript's earliest record, so a session left open for a day dates its last
+finding by its first minute, and a session resumed across a fortnight dates
+today's finding two weeks ago. The local console worked around it with the
+transcript file's modification time; the receiving service works around it by
+admitting a finding on the later of the session start and its own receipt time.
+Both are compensating for a value this package never produced.
+
+OpenAIDR now carries `Turn.occurred_at` (its ADR-0010). The question this ADR
+settles is which turns date a finding, and what shape that date takes.
+
+## Decision
+
+A detection is dated by **the turns its evidence cites**: `occurred_start` is the
+MIN and `occurred_end` the MAX over its citations' turn times, and each
+`Evidence` carries the time of its own turn beside it. A finding citing one turn
+has equal bounds, which is the correct answer rather than a degenerate one.
+
+Citations that resolve to no turn — `ContextItem` spans, which take the literal
+turn key `context` — contribute nothing and do not undate a finding its other
+citations can date. A finding with no dated citation carries no range, and the
+consuming surface falls back to the clocks it used before.
+
+Dating is applied **once**, at the seam where a detector run is assembled, not at
+each of the five sites that extend the finding list.
+
+## Alternatives considered
+
+- **Date a finding by its session's start.** The status quo, and the thing being
+  fixed. Rejected: wrong by the session's whole duration, and worst exactly where
+  it matters — the long, busy sessions that produce the most findings.
+- **Date a finding by the anchor citation alone** (`evidence[0]`). Rejected: the
+  anchor is *what the finding is about*, not *when it happened*. A session-scoped
+  rule accumulates citations as the session grows, so the anchor would freeze a
+  live finding at its oldest evidence.
+- **A single instant per detection — the newest cited turn.** Specified first,
+  then cut. It answers "how recent" but destroys "over what span", and the span
+  is the question for a multi-turn episode: a finding whose citations run from
+  turn 12 to turn 47 is telling a story about an interval, and collapsing it to
+  turn 47 discards the part a responder reconstructs the incident from.
+- **Per-turn start *and* end, carried on every citation.** Also specified, then
+  cut. It requires OpenAIDR to model a turn end, which needs the ambiguous
+  call-id join and a rule for a turn holding a still-running call — and it
+  answers a question nobody asked. A consumer wanting the span of an episode
+  gets it from the first and last turn it cites, which is exactly this decision.
+- **Put the range on `SessionRef`.** Rejected twice. `SessionRef`'s four fields
+  mirror OpenAIDR's outward-carriage descriptor, and widening one without the
+  other breaks the mirror. More decisively, a time on `SessionRef` would be
+  shared by every detection from that session — which is the bug restated, not
+  fixed.
+- **Let the receiving service derive the range from the evidence rows it
+  stores.** Rejected: it forces a join to answer the commonest filter, and the
+  producer already holds the values. The range is denormalised onto the
+  detection for exactly that reason.
+- **Re-derive the turn from the span string.** The span embeds its turn key, so
+  parsing it would work. Rejected: span construction is OpenAIDR's (its
+  ADR-0001), and a consumer that parses it takes a dependency on a format it does
+  not own and cannot be told has changed. The lookup walks the turns instead.
+
+## Consequences
+
+A responder can see when a finding happened, and for a multi-turn finding, over
+what interval. The monitor and the receiving service both get a device-side clock
+that is a property of the session rather than of the file holding it.
+
+Every consumer must treat equal bounds as ordinary and print one time rather than
+a range — most findings cite one turn, so this is the common path, not an edge.
+
+Nulls propagate honestly and therefore have to be handled honestly: a finding
+citing only context spans is undated, and a surface that renders that as "just
+now" or as the session's start has reintroduced the defect this fixes.
+
+The wire shape grows three nullable keys. Because the upload contract is an
+exhaustive allowlist, they must be added to it in the same commit as the
+producer, or every upload fails locally before it is sent.
+
+## When to revisit
+
+If a rule family appears whose citations are not tool calls — a finding about a
+session's shape rather than its actions — the span-to-turn lookup would return
+nothing for it, and dating would need a second source.
+
+If undated findings turn out to be common rather than rare in practice, which
+would mean context-only citations matter more than measured, and would justify
+dating a `ContextItem` upstream.
+
+If the range is ever used to *admit* a finding to a window rather than to
+display it, the null-together property and the fallback chain need restating for
+that use before it is relied on.

stacktrace_cli-0.4.0/docs/adrs/0031-one-host-daemon-observes-native-session-logs.md

@@ -0,0 +1,115 @@
+---
+id: 0031
+title: Let one host daemon observe native session logs and deliver findings
+status: accepted
+date: 2026-09-17
+supersedes: null
+superseded-by: null
+amends: 0006
+amended-by: 0032, 0036, 0037, 0038, 0039
+---
+
+## Context
+
+Automatic detection needs to work while an agent session is active without
+making every agent integration implement the detector. Claude exposes lifecycle
+hooks and an experimental session monitor, but other hosts expose different
+surfaces. Hooks also describe lifecycle boundaries rather than the completion of
+an asynchronous detection pass: starting detached work on every turn creates
+overlapping workers, while waiting in the hook delays the agent.
+
+The native session log is already the complete local event ledger consumed
+through OpenAIDR. Reading it requires no proxy, SDK wrapper, provider
+instrumentation or change to the user's agent configuration beyond installing
+an adapter. The missing piece is a process that notices changes, runs the
+existing pipeline incrementally, and routes the result back to the one session
+that caused it.
+
+That process needs durable delivery state. ADR-0006 permits findings to travel
+but says session models and correlation records do not persist; ADR-0011 makes a
+narrow exception for verdicts and explicitly says another kind of
+session-derived state needs its own case. A content-free finding and its delivery
+receipt are that second case.
+
+## Decision
+
+One per-user, host-level Stacktrace daemon observes native session logs, runs the
+existing in-process analysis pipeline, persists content-free findings, and
+delivers eligible notification events over a local Unix socket.
+
+1. Agent adapters identify a native session and subscribe to the daemon. They do
+   not parse transcripts or run detection. The daemon routes only by exact
+   `(host, native session id)`; current directory and newest-session heuristics
+   are never routing keys.
+2. OpenAIDR remains the only session-log parsing boundary. The daemon narrows
+   analysis to subscribed sessions and re-runs it only when that session's file
+   size or modification time changes.
+3. The socket protocol is versioned newline-delimited JSON. Notification
+   delivery is at least once: the subscriber acknowledges only after flushing
+   the tagged event to its host, and reconnecting subscribers receive unacknowledged
+   events with the same stable event id.
+4. This amends ADR-0006 to permit one durable local ledger containing the
+   already-published, content-free detection shape, stable event ids, native
+   session ids, transcript size and modification time, and delivery status. It
+   never stores turns, prompts, tool arguments, tool results, correlation
+   records, compositions, evidence excerpts or analyzer explanations.
+5. Notification prose is generated from Stacktrace-owned rule identifiers and
+   grades. Transcript text and finding-provided titles are not copied into the
+   host-facing notification channel.
+6. The daemon exists while at least one adapter is subscribed, plus a short
+   final-flush grace after disconnect. A lock admits one daemon per user, and an
+   adapter reconnects after daemon replacement.
+
+## Alternatives considered
+
+- **Run detection from Stop and SessionEnd hooks.** Rejected because a turn
+  boundary is not a detection boundary. Detached hooks create overlapping
+  workers and lose their results; attached hooks delay the agent. Hosts without
+  equivalent hooks would also need another architecture.
+- **Put a session watcher and detector inside every plugin.** Rejected because
+  every active session would own duplicate parsing, policy and durable state,
+  and each new host adapter would copy the same engine.
+- **Require OTEL, OpenInference, an MCP proxy or an SDK wrapper.** Rejected for
+  the default path because each requires instrumentation or traffic-path changes
+  before Stacktrace can observe an existing agent. They may become additional
+  inputs, but not an installation prerequisite.
+- **Persist transcripts or normalized session events and process only appended
+  bytes.** Rejected because it widens the local data boundary and duplicates the
+  parser's state model. The first increment is the session selector plus the
+  file fingerprint: only a changed subscribed session is reparsed, and stable
+  finding identity prevents duplicate work at the delivery boundary.
+- **Send findings to whichever subscriber shares a working directory.**
+  Rejected because parallel sessions commonly share a project. A plausible
+  notification delivered to the wrong conversation is a security failure, not
+  a cosmetic race.
+
+## Consequences
+
+Agent plugins become small adapters: identify the native session, maintain one
+local subscription, and teach the host how to render a tagged Stacktrace event.
+The analysis engine, policy, persistence and delivery semantics remain in one
+place and can serve later Codex or Cursor adapters without moving them.
+
+The persisted ledger weakens ADR-0006's former absolute local-persistence rule,
+but only with the same content-free finding object already allowed to travel.
+Tests must continue to prove notification text cannot contain attacker-controlled
+finding titles and that sessions cannot receive one another's events.
+
+The first increment reparses the changed session rather than parsing an append
+stream. That keeps OpenAIDR as the format owner and is simpler to recover after
+partial writes, at the cost of work proportional to one growing session. If
+that cost threatens the notification objective, the incremental cursor belongs
+in OpenAIDR's per-kind reader contract rather than in the daemon.
+
+The model-mediated host notification is best effort: a host that is unavailable
+cannot render it. Findings remain durable, so an independent notification
+adapter can be added without changing observation or detection.
+
+## When to revisit
+
+Revisit the file-fingerprint increment when measured changed-session analysis
+cannot meet the notification objective. Revisit native-log observation when a
+host offers a stable, complete event stream requiring no user instrumentation.
+Revisit Unix sockets if supported hosts require Windows. Do not revisit merely
+because one host adds another lifecycle hook; hooks do not change the ownership
+or asynchronous-boundary arguments.