stacktrace-cli 0.5.1__tar.gz → 0.5.3__tar.gz

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.5.1
+Version: 0.5.3
 Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
@@ -51,7 +51,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.5.1 (openaca 0.7.0)
+stacktrace 0.5.3 (openaca 0.7.0)
 ```
 
 ## Quick start
@@ -70,6 +70,7 @@ stacktrace monitor       # the same, live in a browser
 | `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. |
+| `webhook` | Send eligible daemon findings to a host-level HTTPS endpoint. |
 | `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. |
@@ -78,6 +79,33 @@ The last three are composition analysis, supplied by
 [`openaca`](https://pypi.org/project/openaca/) and available under either
 name.
 
+### Webhook notifications
+
+Configure one host-level endpoint; the running daemon delivers retained eligible
+findings and new findings automatically:
+
+```bash
+stacktrace webhook configure --url https://alerts.example.com/stacktrace
+stacktrace webhook status
+stacktrace webhook disable
+```
+
+`configure` prompts for an optional HMAC-SHA256 signing secret without echoing
+it. The endpoint receives a narrow JSON document containing the event ID, rule,
+severity, confidence and session identity—not transcript content, finding prose
+or evidence. Delivery is at least once, so receivers should deduplicate on
+`event_id`. The URL and secret are stored in a mode-0600 host configuration
+file. HTTP is accepted only for loopback development endpoints.
+
+Failed deliveries retry without a limit while enabled. Outages can grow the
+local backlog, bounded by the local retention window—findings older than that
+when the endpoint next accepts requests are not sent. Changing the endpoint
+sends the remaining backlog to the new destination; rotating its signing
+secret preserves progress. Configure and disable take effect from the next
+request: one already in flight may still complete with the previous
+configuration. Re-enabling resumes only pending findings still within the
+retention window, not already-delivered findings.
+
 ## What it looks like
 
 ```console

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/README.md

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.5.1 (openaca 0.7.0)
+stacktrace 0.5.3 (openaca 0.7.0)
 ```
 
 ## Quick start
@@ -43,6 +43,7 @@ stacktrace monitor       # the same, live in a browser
 | `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. |
+| `webhook` | Send eligible daemon findings to a host-level HTTPS endpoint. |
 | `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. |
@@ -51,6 +52,33 @@ The last three are composition analysis, supplied by
 [`openaca`](https://pypi.org/project/openaca/) and available under either
 name.
 
+### Webhook notifications
+
+Configure one host-level endpoint; the running daemon delivers retained eligible
+findings and new findings automatically:
+
+```bash
+stacktrace webhook configure --url https://alerts.example.com/stacktrace
+stacktrace webhook status
+stacktrace webhook disable
+```
+
+`configure` prompts for an optional HMAC-SHA256 signing secret without echoing
+it. The endpoint receives a narrow JSON document containing the event ID, rule,
+severity, confidence and session identity—not transcript content, finding prose
+or evidence. Delivery is at least once, so receivers should deduplicate on
+`event_id`. The URL and secret are stored in a mode-0600 host configuration
+file. HTTP is accepted only for loopback development endpoints.
+
+Failed deliveries retry without a limit while enabled. Outages can grow the
+local backlog, bounded by the local retention window—findings older than that
+when the endpoint next accepts requests are not sent. Changing the endpoint
+sends the remaining backlog to the new destination; rotating its signing
+secret preserves progress. Configure and disable take effect from the next
+request: one already in flight may still complete with the previous
+configuration. Re-enabling resumes only pending findings still within the
+retention window, not already-delivered findings.
+
 ## What it looks like
 
 ```console

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/docs/adrs/0031-one-host-daemon-observes-native-session-logs.md

@@ -6,7 +6,7 @@ date: 2026-09-17
 supersedes: null
 superseded-by: null
 amends: 0006
-amended-by: 0032, 0036, 0037, 0038, 0039, 0045, 0046
+amended-by: 0032, 0036, 0037, 0038, 0039, 0045, 0046, 0066, 0072
 ---
 
 ## Context

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/docs/adrs/0036-deliver-eligible-findings-to-slack-from-the-daemon.md

@@ -6,7 +6,7 @@ date: 2026-09-20
 supersedes: null
 superseded-by: null
 amends: 0031
-amended-by: null
+amended-by: 0067
 ---
 
 Subsystem: the daemon and its delivery sinks. The integration view across the

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/docs/adrs/0045-scan-every-session-and-outlive-them.md

@@ -6,7 +6,7 @@ date: 2026-09-22
 supersedes: null
 superseded-by: null
 amends: 0031, 0037, 0038
-amended-by: 0056, 0058
+amended-by: 0056, 0058, 0066, 0072
 ---
 
 ## Context

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/docs/adrs/0046-the-finding-store-is-an-append-only-queue.md

@@ -6,7 +6,7 @@ date: 2026-09-22
 supersedes: null
 superseded-by: null
 amends: 0031
-amended-by: 0057, 0058
+amended-by: 0057, 0058, 0067
 ---
 
 ## Context

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/docs/adrs/0058-one-word-for-a-finding-columns-for-a-counter-and-a-push-that-does-not-wait.md

@@ -6,7 +6,7 @@ date: 2026-09-23
 supersedes: null
 superseded-by: null
 amends: 0045, 0046, 0047, 0057
-amended-by: 0059
+amended-by: 0059, 0066, 0072
 ---
 
 ## Context

{stacktrace_cli-0.5.1 → stacktrace_cli-0.5.3}/docs/adrs/0059-the-daemon-does-not-decide-whether-it-should-be-running.md

@@ -1,10 +1,10 @@
 ---
 id: 0059
 title: The daemon does not decide whether it should be running
-status: accepted
+status: superseded
 date: 2026-09-23
 supersedes: 0056
-superseded-by: null
+superseded-by: 0066
 amends: 0058
 amended-by: null
 ---

stacktrace_cli-0.5.3/docs/adrs/0066-host-owned-daemon-supervision.md

@@ -0,0 +1,197 @@
+---
+id: 0066
+title: Put daemon lifetime under host-owned supervision
+status: superseded
+date: 2026-09-23
+supersedes: 0059
+superseded-by: 0072
+amends: 0031, 0045, 0058
+amended-by: null
+---
+
+## Context
+
+ADR-0031 tied daemon lifetime to subscribers, and ADR-0045 made the daemon
+resident without changing who starts it. The plugin monitor still calls
+`ensure_daemon()`, which forks `daemon run` as the monitor's child. Starting a
+new session keeps terminal signals away from the child, but does not remove it
+from the monitor's process tree.
+
+That distinction caused an outage on 2026-09-22. Ending one Claude session
+killed its monitor's entire descendant tree, including the daemon that other
+sessions were using. Their monitors lost the socket and one eventually started
+a replacement. The terminated daemon wrote no traceback, skipped shutdown
+cleanup, left its socket behind and did not flush telemetry. A focused
+reproduction showed why: `setsid` survives a signal to the parent or its
+process group, but not a tree kill that follows parent identifiers.
+
+The first subscriber therefore cannot own a machine-wide service. The hosts
+also provide no single supervisor API. Laptops have launchd or systemd;
+Niteshift has declared services; Claude Code and Codex cloud sandboxes have no
+usable user systemd; Claude Managed Agents expose no startup hook. Except for
+Managed Agents, each environment can still run owner-controlled setup or
+session-start commands.
+
+Cloud probes established the portable minimum. A process survives into the
+agent phase when its launcher calls `setsid`, double-forks, redirects standard
+streams and closes every inherited descriptor. On Codex, leaving even one
+runner descriptor open prevents setup from finishing. Cached Codex containers
+can also run setup and maintenance starters together, so concurrent starts are
+normal rather than exceptional.
+
+ADR-0059 removed every lifecycle command in favor of a future external
+supervisor. That is sufficient on a host with launchd, systemd or a declared
+service, but it leaves cloud sandboxes without a lifecycle owner even though
+their setup hooks can safely launch a fully detached process. This decision
+supersedes ADR-0059: the daemon still does not decide whether it should run,
+but Stacktrace supplies a portable supervisor for hosts that do not have one.
+
+## Decision
+
+Daemon lifecycle belongs to host configuration. Agent adapters and monitors
+only connect; they never create a daemon as a side effect of subscribing. A
+host may invoke Stacktrace's detached supervisor from a setup or SessionStart
+hook, but the resulting process is not owned by that agent session.
+
+1. **`stacktrace daemon run` is the foreground service.** It remains attached
+   to its caller until it stops, so an external supervisor or container
+   entrypoint can observe it directly. SIGTERM and SIGINT stop the tick loop,
+   flush telemetry, close compositions, remove the socket and return the
+   deliberate shutdown status. If another daemon holds `daemon.lock`, `run`
+   returns without taking ownership. The running process continues to write
+   its pid, version and effective configuration to the run-state file, and
+   `daemon status` reads that record rather than re-deriving configuration from
+   its own environment.
+2. **`stacktrace daemon start` launches a detached supervisor.** The launcher
+   calls `setsid`, double-forks, redirects stdin from `/dev/null`, sends stdout
+   and stderr to the daemon log and closes every caller-provided descriptor. A
+   private readiness channel may survive long enough to report that the
+   detached process acquired `supervisor.lock`, but it is closed before
+   `start` returns. Two concurrent starts therefore converge on one supervisor
+   and both commands succeed. The supervisor keeps only descriptors it owns.
+3. **Every daemon child starts through a fresh exec of the installed CLI.** The
+   supervisor never forks an already-imported daemon or calls it in-process.
+   This is the boundary that makes a restart load newly installed code while
+   allowing the small supervisor loop itself to remain old.
+4. **Exit status controls supervision.** Zero means the daemon chose to stay
+   down; non-zero means start it again. `daemon stop` and a recorded
+   `daemon disable` return zero. Lock contention and an already-live socket
+   return non-zero instead: they mean another process already holds the role,
+   not that the role is deliberately unfilled, and nothing here confirms that
+   process has a supervisor of its own. This is the case a host hits the first
+   time it layers this supervisor onto a daemon still running from the
+   pre-ADR-0066 `ensure_daemon()` path — treating that as "stay down" would
+   exit the only supervisor watching the machine and strand the daemon the
+   moment it later exits for its own `version_label()` restart. A stop meant
+   to hold through that retry window must be `daemon disable`: its marker is
+   checked before every fresh-exec'd child opens a socket, supervisor retries
+   included, while `daemon stop` reaches only the process it signals — the
+   incumbent, not a supervisor waiting behind it, so the supervisor still
+   takes over once the incumbent is gone. An unhandled crash also returns
+   non-zero. Version divergence from ADR-0045 returns a dedicated non-zero
+   restart code. Stop and disable take precedence if they race with an
+   upgrade. External supervisor recipes use restart-on-failure semantics.
+5. **The detached supervisor restarts with bounded backoff.** It waits one
+   second after a non-zero exit, doubles to at most thirty seconds, and resets
+   the delay after the child has stayed up for sixty seconds. SIGTERM sent to
+   the supervisor is forwarded to the child, whose exit is awaited before the
+   supervisor exits. A zero child exit ends the supervisor.
+6. **Subscribing has no lifecycle side effect.** `ensure_daemon()` is deleted.
+   `daemon subscribe` reports once that no daemon is running, keeps retrying and
+   reports when it reconnects. The socket handshake carries an integer protocol
+   version: a compatibility epoch, not a package or build version. Only an
+   exact match proceeds. On a mismatch the daemon returns
+   `unsupported_version` and closes that connection; the subscriber reports
+   that the agent session must be restarted and exits instead of retrying. The
+   daemon remains running because one incompatible subscriber must not disrupt
+   other sessions. Daemon code freshness remains the separate
+   `version_label()` exit-and-restart decision from ADR-0045.
+7. **The host decides when to call `start`.** A person does so on a laptop. A
+   repository SessionStart hook may do so in Claude Code cloud, and Codex cloud
+   may do so from setup and maintenance scripts. Niteshift and containers run
+   `daemon run` under their native supervisor. These are deployment recipes,
+   not plugin behavior.
+
+This replaces ADR-0031 decision 6 and ADR-0045's assumption that
+`ensure_daemon()` remains the daemon's starter. ADR-0031's routing,
+persistence and delivery decisions, and ADR-0045's scanning, stop and disable
+decisions, remain in force. It supersedes ADR-0059's removal of lifecycle
+commands: host configuration still owns the decision, while `daemon start`
+provides the supervisor on hosts that lack a native one.
+
+## Alternatives considered
+
+- **Install launchd and systemd units.** Rejected for now. Neither helps in the
+  cloud sandboxes, and a daemon needed only while agents run does not yet
+  justify platform-specific install, detection and uninstall paths. Revisit
+  when laptops need pre-session or reboot persistence.
+- **Expose only detached `daemon start`.** Rejected because native supervisors
+  need a foreground process whose lifetime and exit status they own. A forking
+  service conflicts with systemd control groups, launchd process groups,
+  declared sandbox services and container entrypoints.
+- **Keep `ensure_daemon()` and make its child detach correctly.** Rejected
+  because it fixes ancestry but not ownership. Connection would still decide
+  whether the machine-wide service exists, and host configuration could not
+  choose its start boundary.
+- **Start the daemon from the plugin's own SessionStart hook.** Rejected. A
+  host-owned hook may invoke `start`, but daemon availability is not a plugin
+  responsibility and other agent adapters must not copy that behavior.
+- **Use launchd or systemd socket activation.** Rejected because the daemon
+  would have to adopt inherited sockets on both platforms, while the sandbox
+  hosts would still need another lifecycle mechanism.
+- **Require `daemon start --restart` after every upgrade.** Rejected because it
+  is easy to omit and leaves every monitor reporting an obsolete daemon until
+  someone intervenes. The fresh-exec restart code makes the installed upgrade
+  take effect without adding a provisioning step.
+- **Compare package or build versions during the socket handshake.** Rejected
+  because code freshness and wire compatibility are different facts. Commit
+  labels are not orderable, while compatible package releases should not end a
+  working subscription. The protocol epoch changes only when the wire becomes
+  incompatible.
+- **Stop both processes on a protocol mismatch.** Rejected because the daemon
+  is shared across sessions. A stale subscriber may end its own connection and
+  process; it cannot take down delivery for compatible subscribers.
+
+## Consequences
+
+An agent session can end, crash or have its descendant tree killed without
+taking down the daemon used by other sessions. Adapters become strict clients,
+which gives later Codex and Cursor integrations the same lifecycle boundary as
+Claude.
+
+The portable supervisor is intentionally small, but nothing supervises that
+supervisor. If it dies, its current child can continue, but no replacement is
+launched after that child exits until the host calls `start` again. A laptop
+also needs another `start` after logout or reboot.
+
+Full descriptor closure is part of correctness. A test must hold a pipe on an
+extra descriptor across `start` and observe EOF. A second test must replace the
+installed version, cause version divergence and prove that the next child
+executes the new code rather than the supervisor's imported code.
+
+Protocol tests must prove that an exact epoch match subscribes, a mismatch
+ends the subscriber with restart guidance, and the daemon remains available to
+a subsequent compatible subscriber.
+
+A migration test must start a daemon directly, the way the deleted
+`ensure_daemon()` did, then start the supervisor against it and prove the
+supervisor keeps retrying with backoff rather than exiting, and that it takes
+over once the direct process exits. A second case must prove `daemon disable`
+recorded during that retry window keeps the supervisor down, while a bare
+`daemon stop` against the direct process only ends that process and does not
+stop the waiting supervisor from taking over.
+
+The host must run Stacktrace as the same user as the agents it observes. The
+daemon reads that user's agent logs and binds below `/tmp/stacktrace-$UID/`.
+Claude Managed Agents cannot run this daemon until they expose a startup or
+supervised-service mechanism; self-hosted environments can use their image
+entrypoint.
+
+## When to revisit
+
+- Add launchd or systemd installation when laptops need automatic startup or
+  reboot persistence.
+- Prefer a sandbox's native service manager whenever it provides one.
+- Reconsider the portable supervisor if its own failures become material.
+- Revisit cloud deployment if an agent host removes owner-controlled startup
+  commands or supplies a first-class replacement.

stacktrace_cli-0.5.3/docs/adrs/0067-a-webhook-is-an-independent-queue-subscriber.md

@@ -0,0 +1,100 @@
+---
+id: 0067
+title: A webhook is an independent queue subscriber with an allowlisted payload
+status: accepted
+date: 2026-09-24
+supersedes: null
+superseded-by: null
+amends: 0036, 0046
+amended-by: 0068, 0071, 0073
+---
+
+## Context
+
+The daemon already delivers eligible findings to the active agent session and
+to Fleet. A host owner also needs a generic integration point for destinations
+such as an incident router or automation service, without installing an
+agent-specific adapter or making Fleet availability a prerequisite.
+
+The finding queue now has a monotonic sequence and a cursor per subscriber and
+agent-kind partition. That makes the generic sink a queue reader, not another
+branch on the scan path. The stored finding is intentionally richer than any
+outbound payload, so forwarding it directly would also widen the data boundary
+to detector prose, evidence descriptors, spans and component details.
+
+## Decision
+
+One optional host-level webhook is a subscriber named `webhook`.
+
+- It reads every queue revision in order and advances its own cursor only after
+  an HTTP 2xx. A failed request holds that row for retry and cannot move or
+  block the Fleet cursor.
+- Only the exact revision that first crossed the local notification gate is
+  delivered. Later revisions still advance the cursor but do not ring again.
+- Configuration time is the lower delivery bound. Enabling a webhook does not
+  replay findings that predate the configuration.
+- The JSON body is an allowlist: schema version, event type, event ID, rule ID,
+  severity, confidence, agent kind and native session ID. Stored titles,
+  remediation, evidence, spans, participants and unknown records never enter
+  the mapper.
+- Delivery is at least once. A process can stop after the remote endpoint
+  accepts a request and before SQLite commits the cursor, so receivers use the
+  stable event ID as their idempotency key.
+- The endpoint is HTTPS, except that HTTP is accepted on loopback for local
+  development. Userinfo and fragments are refused. An optional secret signs
+  the exact request bytes with HMAC-SHA256.
+- The URL, optional signing secret and configuration time live in a private
+  host file. CLI output and daemon logs never print the URL path, query,
+  secret, response body or exception message.
+- A scan commit wakes a single webhook worker thread; the daemon's scan and
+  scheduler thread never waits on HTTP. Wakes coalesce while a delivery is in
+  progress. A one-minute job is the retry fallback; setting its interval to
+  zero disables only that fallback.
+
+This amends ADR-0036's proposed fan-out implementation. The independence and
+per-destination acknowledgement rules remain, but SQLite cursors introduced by
+ADR-0046 are the durable fan-out mechanism for resident subscribers; no shared
+sink registry or per-event acknowledgement map is added.
+
+## Alternatives considered
+
+- **Send from the scanner callback.** Rejected: network latency and failure
+  would enter the detection hot path, and a crash after the scan would lose the
+  only delivery attempt.
+- **Reuse Fleet's cursor.** Rejected: whichever destination acknowledged first
+  would skip work for the other, and a slow webhook would block Fleet.
+- **Forward the stored finding.** Rejected: storage is not a wire contract and
+  contains fields this destination does not need. The allowlist is the data
+  boundary.
+- **Add a delivery row for every `(event_id, sink)`.** Rejected: delivery is
+  ordered within each agent-kind partition, so the existing subscriber cursor
+  already represents every acknowledgement below it.
+- **Replay the retained backlog when configured.** Rejected: configuration is
+  consent for future delivery, not consent to export findings retained before
+  that choice.
+- **Exactly-once delivery.** Rejected: it requires the receiver to participate
+  in a transaction with the local database. Stable event IDs make receiver-side
+  deduplication possible without claiming an impossible transport guarantee.
+
+## Consequences
+
+A webhook outage accumulates work behind only its own cursor. Retention keeps
+that backlog while the subscriber remains configured, so a permanently broken
+endpoint can increase local database use until it is disabled.
+
+Receivers get enough information to route and deduplicate an alert, but not a
+human-readable explanation. They use the event ID and session identity to link
+back to the local finding rather than asking the endpoint to export more data.
+
+Changing the endpoint starts a new consent boundary at the new configuration
+time. Re-entering the same endpoint preserves that time so rotating its signing
+secret does not silently skip a retry already in progress.
+
+## When to revisit
+
+- If more than one generic webhook per host is required; each needs its own
+  stable subscriber identity and cursor.
+- If receivers need more context; widening the payload requires a new data-
+  boundary decision and exhaustive non-leak tests.
+- If queue partitions can be delivered concurrently; ordering and cursor
+  advancement would need a lease or another claim mechanism.

stacktrace_cli-0.5.3/docs/adrs/0068-webhooks-retry-the-retained-backlog.md

@@ -0,0 +1,80 @@
+---
+id: 0068
+title: Webhooks retry the retained backlog without a configuration-time cutoff
+status: accepted
+date: 2026-09-25
+supersedes: null
+superseded-by: null
+amends: 0067
+amended-by: 0069
+---
+
+## Context
+
+ADR-0067 already provides durable delivery through an independent subscriber
+cursor. Its configuration-time lower bound adds timestamp validation and clock
+ordering to a queue that already has an ordered sequence. It also discards
+pending deliveries when the endpoint changes. These semantics are unnecessary
+for a single host-level destination whose purpose is reliable alerting.
+
+## Decision
+
+Amend ADR-0067's configuration-time lower bound, configuration fields and
+endpoint-change behavior. Its payload, eligibility, signing, independent cursor
+and asynchronous worker decisions remain in force.
+
+- First enable delivers eligible findings still retained in the queue. The CLI
+  explicitly states that configuration authorizes retained history as well as
+  new findings. There is no time cutoff; the private file contains only the URL
+  and optional signing secret. Legacy `configured_at` fields are ignored.
+- One worker reads sequentially within each partition. A successful HTTP 2xx
+  advances that row's durable cursor. Non-notifiable revisions advance without
+  sending. Any delivery failure leaves the failed row pending for the next
+  attempt. There is no retry count, discard threshold or separate retry queue.
+- A scan commit wakes the worker, and the existing default one-minute interval
+  retries while idle. Setting that interval to zero remains an explicit opt-out
+  from timed retries; commits and daemon restarts still wake delivery.
+- Changing the endpoint transfers the remaining backlog to the new destination.
+  Changing the signing secret preserves progress. Previously acknowledged rows
+  are not replayed for a new destination.
+- Configuration writes and each config-read/POST/cursor-advance span share one
+  cross-process file lock. The lock is released between rows. Configure/disable
+  waits for an in-flight request; after the command returns, subsequent requests
+  cannot use the old configuration. Direct file edits do not participate in this
+  coordination. HTTP requests use a ten-second timeout per HTTPX operation.
+- While enabled, pending partitions have retention floors, including before the
+  first delivery attempt and every retention sweep. Disable stops delivery and
+  releases those floors at the next drain or sweep, even if timed retries are
+  disabled. Disabling explicitly ends the pending-delivery guarantee. Re-enable
+  resumes from the saved acknowledgement position for whatever remains retained.
+- Invalid configuration stops delivery and preserves existing floors for repair.
+  Disable remains available to release them. No endpoint, secret, response body
+  or underlying HTTP error message is printed in delivery failures.
+
+## Alternatives considered
+
+- **Best effort with an in-memory queue.** Loses alerts during outages or daemon
+  restarts, weakening the purpose of a notification channel for unattended work.
+- **Keep the timestamp or replace it with a configuration-time sequence.** Both
+  maintain a second delivery boundary. Replaying retained history is an explicit
+  product choice that removes that state entirely.
+- **Discard after a retry limit or age limit while enabled.** Would silently
+  abandon undelivered alerts. Disable is the explicit way to release a backlog.
+- **Read config immediately before POST without a lock.** A concurrent command
+  can return between the read and request. A comparison after sending cannot
+  undo delivery to the old destination.
+- **Lock the entire backlog drain.** A large backlog would delay configuration
+  changes for many requests. Per-row locking preserves the same correctness
+  boundary without holding the lock across a whole drain.
+
+## Consequences
+
+First enable may send a burst of older findings. An unreachable or rejecting
+endpoint can retain a growing backlog indefinitely. Delivery resumes only when
+the endpoint accepts requests and the worker runs again; disable ends that
+obligation. A crash after acceptance but before cursor persistence can resend a
+finding, so receivers still deduplicate with the stable `event_id`. A transport
+timeout can also leave the receiver's outcome unknown.
+
+This introduces no database migration or second queue. The first notifiable
+revision remains the only revision sent for an event.

stacktrace_cli-0.5.3/docs/adrs/0069-webhooks-deliver-what-retention-holds.md

@@ -0,0 +1,86 @@
+---
+id: 0069
+title: Webhooks deliver what retention holds, and configuration takes no lock
+status: accepted
+date: 2026-09-25
+supersedes: null
+superseded-by: null
+amends: 0068
+amended-by: null
+---
+
+## Context
+
+ADR-0068 gave a configured webhook retention floors, so a pending delivery
+could outlive the retention window, and serialized configuration changes with
+each POST through a cross-process file lock. Both made the daemon act on a
+reading of `webhook.toml` in ways that could lose or corrupt state.
+
+Clearing a floor was the daemon's inference from "no URL", so every way a read
+could come back empty — a missing, empty or truncated file, a dangling symlink,
+an unreadable directory, invalid UTF-8, a table without `url` — was a way to
+release a backlog for retention to delete. The floor also had to be reconciled
+inside the retention sweep, under the same lock as the POST, which put that lock
+on the scan thread's prune path and made optional webhook storage a dependency
+of base retention. Review of the implementation produced one finding after
+another in these two areas, each a new route to the same two invariants.
+
+## Decision
+
+Amend three clauses of ADR-0068. Its payload, eligibility, no-cutoff replay of
+retained history, sequential per-partition delivery, unbounded retry and
+endpoint-change behavior remain in force.
+
+- **No retention floors for the webhook.** Its cursor records delivery
+  progress only. Retention prunes by age, and by Fleet's cursors as before
+  ADR-0067; a finding older than the retention window when the endpoint next
+  accepts requests is not delivered. This replaces "while enabled, pending
+  partitions have retention floors", and "invalid configuration preserves
+  existing floors for repair" becomes "invalid configuration pauses delivery".
+- **Configuration is read before each request, without a lock.** `configure`
+  and `disable` replace or remove the file atomically and return at once. The
+  change applies from the next request; the one already in flight completes
+  with the configuration it read. This replaces the per-row cross-process lock.
+- **The daemon never removes a webhook cursor.** Nothing it reads can release
+  anything, so a configuration that cannot be read, or names no endpoint, only
+  pauses delivery. Disable deletes the file and keeps the cursor, so re-enable
+  resumes from the saved position for whatever is still retained, as ADR-0068
+  already states.
+
+URLs are validated by parsing them with `httpx.URL`, the client that sends, so
+`configure` cannot accept an endpoint delivery would refuse.
+
+## Alternatives considered
+
+- **Keep floors and make "disabled" explicit.** Have only `disable` clear the
+  cursor and never infer it from a read. Rejected: it keeps the reconcile in the
+  retention sweep and the lock on its path, the source of the other half of the
+  findings, to protect a backlog older than the window every other local
+  consumer already accepts losing.
+- **Keep the lock so a change is a hard cutoff.** Rejected: what it prevents is
+  one request, already in flight, carrying the allowlisted metadata payload to
+  the previous endpoint. That does not justify a cross-process lock, its failure
+  modes, and a CLI that waits on HTTP.
+- **Move the configuration into the daemon's SQLite store.** Would make
+  configure one transaction with cursor state. Rejected for now: with no floors
+  and no lock there is no cursor state for configure to keep consistent, and a
+  plain file keeps the CLI independent of the daemon's database.
+- **Reintroduce a configuration-time boundary as the cursor.** Rejected, as in
+  ADR-0068: replaying retained history is the product choice.
+
+## Consequences
+
+An endpoint unavailable for longer than the retention window misses the
+findings that aged out meanwhile; there is no longer an obligation that grows
+without bound while an endpoint rejects requests. A receiver can get one request
+after `disable` returns, or at the previous endpoint after `configure` returns.
+
+Base retention no longer depends on the webhook's storage or configuration,
+and the scan thread never takes a webhook lock.
+
+## When to revisit
+
+If a destination must never lose a finding to retention, give it its own
+durable queue rather than floors on the shared one. If a receiver must treat
+any request after `disable` as an incident, the hard cutoff needs a daemon-side
+acknowledgement, not a file lock.