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

{stacktrace_cli-0.4.1 → stacktrace_cli-0.5.1}/.gitignore

@@ -6,3 +6,6 @@ __pycache__/
 
 # Local git worktrees
 .worktrees/
+
+# Local research handoffs, kept on disk and out of the repo.
+HANDOFF-*.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.4.1
+Version: 0.5.1
 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.4.1 (openaca 0.7.0)
+stacktrace 0.5.1 (openaca 0.7.0)
 ```
 
 ## Quick start

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

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.4.1 (openaca 0.7.0)
+stacktrace 0.5.1 (openaca 0.7.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.4.1 → stacktrace_cli-0.5.1}/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, 0031, 0039
+amended-by: 0011, 0027, 0031, 0039, 0064
 ---
 
 ## Context

{stacktrace_cli-0.4.1 → stacktrace_cli-0.5.1}/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
+amended-by: 0032, 0036, 0037, 0038, 0039, 0045, 0046
 ---
 
 ## Context

{stacktrace_cli-0.4.1 → stacktrace_cli-0.5.1}/docs/adrs/0037-reuse-openaidr-append-cursors-in-the-daemon.md

@@ -6,7 +6,7 @@ date: 2026-09-18
 supersedes: null
 superseded-by: null
 amends: 0031
-amended-by: 0038
+amended-by: 0038, 0045
 ---
 
 ## Context

{stacktrace_cli-0.4.1 → stacktrace_cli-0.5.1}/docs/adrs/0038-poll-normalized-sessions-for-supplemental-changes.md

@@ -6,7 +6,7 @@ date: 2026-09-21
 supersedes: null
 superseded-by: null
 amends: 0031, 0037
-amended-by: null
+amended-by: 0045
 ---
 
 ## Context

stacktrace_cli-0.5.1/docs/adrs/0045-scan-every-session-and-outlive-them.md

@@ -0,0 +1,137 @@
+---
+id: 0045
+title: Scan every session on a watermark, and outlive all of them
+status: accepted
+date: 2026-09-22
+supersedes: null
+superseded-by: null
+amends: 0031, 0037, 0038
+amended-by: 0056, 0058
+---
+
+## Context
+
+ADR-0031 gave the daemon a subscriber-shaped life. `DaemonService.tick()` takes
+its work list from `server.active_sessions()`, which returns
+`tuple(self._subscriptions)` — literally the set of connected adapters — and
+`should_exit()` ends the process once that set has been non-empty and is now
+empty. Both follow from how the daemon starts: `ensure_daemon()` is called from
+the plugin monitor's reconnect loop, so a session forks it and the process must
+not outlive the session that did.
+
+Two things make that shape wrong now. The daemon is becoming the machine's
+detection engine rather than one session's helper, so a finding for a session
+nobody subscribed to is still a finding worth having. And it is acquiring
+scheduled work — uploads on a cadence — which has no session to keep it alive
+and stops entirely on a quiet machine.
+
+The subscription set is also doing two unrelated jobs at once: deciding *what
+gets analysed* and deciding *where a notification goes*. Only the second is
+what ADR-0031 argued for.
+
+## Decision
+
+The daemon has no concept of an active session. Work comes from the filesystem
+on a cadence, and the process's lifetime is independent of any session.
+
+1. `active_sessions()` is removed from the work path. Every `--scan-interval`
+   the daemon enumerates transcripts changed since a **persisted watermark**,
+   together with recently-live sessions due ADR-0038's supplemental poll, and
+   analyses those.
+2. The first scan, with no watermark on disk, is bounded by `--scan-since`
+   (default 3 days). Every scan after that is bounded by the watermark, which
+   advances to *the scan's start time* — not the newest mtime seen, or a file
+   written during the scan is jumped over. A few seconds of overlap absorbs
+   mtime granularity and clock skew.
+3. `should_exit()`, `_connected_once` and `startup_grace` are **deleted**, not
+   flagged. So are `_last_seen`, `_absent_since` and `disconnect_grace`: they
+   exist to track subscribers, and the scan window already keeps a
+   just-ended session in view for days rather than five seconds.
+4. The daemon instead exits when told to (`daemon stop`, a recorded
+   `daemon disable`), when the machine goes away, or when its running
+   `version_label()` diverges from the installed distribution.
+5. One `analyse_sessions` call per tick for the whole batch, not one per
+   session. `collect()` stays per transcript so a malformed file loses only its
+   own session.
+6. `NotificationServer._subscriptions` is untouched and remains the delivery
+   routing table. **Subscriptions decide where a finding goes, never whether it
+   is found.**
+
+This amends ADR-0031's implicit use of subscription as a work source and its
+process-lifetime rule; its routing, persistence and delivery decisions stay in
+force. ADR-0037's cursor ownership is untouched — the append cursors remain
+OpenAIDR's, in-memory, for the collector's lifetime. ADR-0038's supplemental
+poll survives as the second input to the work list.
+
+## Alternatives considered
+
+- **Keep subscription as the work source and union it with a scan.** Rejected:
+  two sources for one list, and the union can only ever equal the scan, since
+  any subscribed session's transcript is by definition recent. It preserves the
+  coupling while adding a second mechanism.
+- **A `--resident` flag that pins `should_exit()` to `False`.** Rejected, and
+  this was the first design. A flag keeps the coupling and hides it behind a
+  default. Removal is clean instead: `daemon run` is `hidden=True`, an internal
+  command `ensure_daemon()` invokes rather than something a user runs expecting
+  it to return, and `should_exit` has no production caller outside `run()`. The
+  only fallout is assertions in `tests/daemon/test_service.py` that test the
+  behaviour being removed.
+- **Keep `disconnect_grace`.** Rejected because it is subsumed, not merely
+  unused. Its window was carefully anchored to the first absent poll rather than
+  the last-seen time, because a slow `tick()` could otherwise consume the whole
+  budget. With a scan window measured in days, a session that ended a minute ago
+  is still enumerated; the intricacy and the bug class it guarded both stop
+  existing.
+- **`--scan-since` as a standing window rather than a bootstrap horizon.**
+  Rejected: it re-reads the same days forever, and it forces a "has this daemon
+  run before" special case to avoid doing so. A watermark removes the special
+  case and closes downtime gaps for free — a daemon down for a week resumes and
+  enumerates a week.
+- **Enumerate by mtime only.** Rejected: it silently regresses ADR-0038. A
+  session whose transcript is stable but whose MCP logs moved would never be
+  looked at again.
+- **Per-session `analyse_sessions` calls, as today.** Rejected: correlation and
+  advisory lookups are per-run work, so N calls repeat them N times.
+  `analyse_sessions` already takes tuples and already shares
+  `_analyse_sessions` with the cold path.
+- **Keep the per-transcript `mtime - 1 minute` cutoff as `since`.** Rejected as
+  unnecessary: `_analyse_sessions` does not filter on `since`; it stamps it as
+  `window_start` metadata and analyses the view whole. The watermark is a
+  simpler value with the same effect, and batching therefore cannot starve a
+  session-wide rule (ADR-0016) of turns.
+
+## Consequences
+
+Enables detection on a machine where no adapter ever connects, and gives
+scheduled work a process that is still alive to do it. Removes more code than it
+adds.
+
+Costs, honestly:
+
+- **Nothing restarts the daemon.** With supervision out of scope, a crash means
+  the endpoint is down until the next `ensure_daemon()` fork. The
+  version-divergence exit is what stops a long-lived process holding stale code,
+  replacing the garbage-collection that exit-on-idle was accidentally providing.
+- **Collector memory now tracks transcripts seen since start**, not sessions
+  open now. ADR-0037's collector holds one cursor per file for the process
+  lifetime, and the process is now long-lived. If it bites, evict by last-touch
+  inside the seam — not by persisting cursors, which ADR-0037 places upstream.
+- **A wedge lasts all day.** No idle exit and no supervisor means a hang
+  persists until logout. A maximum lifetime is worth having as a safety valve.
+- **Telemetry's `session_started` changes character.** The bootstrap fires it
+  once per session in the horizon. It means "the daemon first saw this session",
+  not "a user started one" (ADR-0039).
+- **Scan cost is a new standing cost.** Bounded in steady state by the
+  watermark; the bootstrap is the expensive pass.
+
+## When to revisit
+
+- When external supervision lands: the version-divergence exit becomes one of
+  several restart triggers rather than the only one, and exit codes need
+  defining before `KeepAlive` is wired — `run_daemon()` currently returns exit
+  `0` on lock contention and on a live socket, which a supervisor would read as
+  "do not restart".
+- If enumeration cost on a large `~/.claude` proves material, which would make
+  a filesystem-event source worth its complexity.
+- If a second agent kind lands, since the observer map and the scan root are
+  both still Claude-shaped.

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

@@ -0,0 +1,139 @@
+---
+id: 0046
+title: Make the finding store an append-only queue of detection revisions
+status: accepted
+date: 2026-09-22
+supersedes: null
+superseded-by: null
+amends: 0031
+amended-by: 0057, 0058
+---
+
+## Context
+
+ADR-0031 gave the daemon durable, content-free findings and delivery state, and
+`FindingStore` implements that as one JSON document rewritten whole on every
+`record()`. That is adequate for the sessions a human happened to subscribe to.
+ADR-0045 makes the daemon analyse every session on the machine, and a later
+deliverable will drain findings to Fleet on a cadence — which needs something
+the document cannot express: *what is new since I last looked?*
+
+Two properties of the existing store block that.
+
+`_durable_finding()` is lossy. `observer.py` produces
+`detection_json(detection)` — the whole detection — and `record()` keeps
+`rule_id`, `severity`, `confidence`, `session_id` and evidence spans, discarding
+the rest. Everything an upload mapper needs (`scope`, `subject`, `involved`,
+component identities, occurrence range) is gone before it reaches disk.
+
+And a finding's identity is stable while its content is not. `_event_id()`
+hashes `(agent_kind, session_id, rule_id, anchor)`; for a session-scoped rule
+the anchor *is* the session id, so one identity covers the whole session however
+many times the rule fires. A session-wide rule such as stall grouping (ADR-0016)
+legitimately accumulates cited turns and widens its occurrence range across
+scans. Today that is `stored[event_id] = …`, last-write-wins in place, which is
+invisible because nothing reads by position.
+
+## Decision
+
+The finding store becomes a SQLite **queue**: an append-only log of detection
+revisions on a monotonic axis, with a cursor per reader. The interface
+`FindingStore` presents to its callers does not change.
+
+1. `findings(seq INTEGER PRIMARY KEY AUTOINCREMENT, event_id, content_hash,
+   agent_kind, session_id, detection_json, delivered_at, acked_at, created_at)`
+   with `UNIQUE (event_id, content_hash)` and an index on `(session_id, seq)`.
+   `seq` is the cursor axis. `event_id` is **not** unique.
+2. A row is **one detection revision**. When a scan produces content differing
+   from the last stored revision of that `event_id`, a new row is appended with
+   a new `seq`. `content_hash` — over canonically serialised `detection_json` —
+   is what distinguishes "this finding again, unchanged" from "this finding, now
+   different", so an unchanged re-derivation writes nothing.
+3. The row stores the **detection**, not any consumer's rendering of it. Each
+   reader renders at send time.
+4. Exactly one writer, so insert order is commit order and a reader taking
+   `max(seq)` cannot skip a row committed later with a lower value. WAL, so
+   `stacktrace findings` and `daemon status` read without blocking it.
+5. `cursors(subscriber, partition, last_seq)` exists with no rows. A reader that
+   is not configured holds **no cursor row at all** — retention prunes below the
+   cursor floor, and a row pinned at zero would make a machine accumulate
+   findings forever.
+6. `daemon-v1.json` is **deleted, not imported**. Nothing is carried across:
+   the product is new, the file holds a few days of content-free findings, and
+   no code outside `daemon/` reads it. A newer `schema_meta` version fails
+   closed rather than reading a newer schema partially.
+
+This amends ADR-0031's persistence clause. Its routing, delivery and lifecycle
+decisions stay in force, and the socket path is untouched: `record()` still
+publishes inline and `pending()` still drains on subscribe.
+
+## Alternatives considered
+
+- **`event_id UNIQUE` with `INSERT OR IGNORE`.** Rejected, and it is the
+  obvious-looking choice: `event_id` *is* the stable identity, and it is exactly
+  what makes redelivery idempotent. It only breaks once a cursor exists — the
+  first thin revision is kept and every later, richer one is lost. The failure
+  is silent and presents as "Fleet has the thin version of some findings".
+- **Update the row in place.** Rejected for the mirror-image reason: the content
+  changes but `seq` does not move, so a reader that has already passed the row
+  never sees the update. Both write strategies lose data; only appending does
+  not.
+- **Store a pre-rendered `upload_json`.** Rejected. `detection_json()` and
+  `_detection_for_upload()` are two renderings of the same `Detection`, each
+  keeping what its own audience needs — the local one adds `stage`, `label` and
+  `title`; the Cloud one adds `scope` and participants and deliberately omits
+  what the Cloud computes. Neither derives from the other, so a rendered column
+  freezes one consumer's wire format into the queue and starves the next one.
+  The defect was that `_durable_finding()` is lossy, not that rendering happens
+  late. Cost accepted: `_detection_for_upload()` takes a `Detection`, not a
+  dict, so either the stored record rehydrates or both renderers learn to read
+  the canonical dict.
+- **A `sessions` table.** Rejected. A session is an `(agent_kind, session_id)`
+  pair carried on each row — enough to partition a cursor and route a frame.
+  More would be a model of the machine, which is what the queue is not. The
+  scan watermark (ADR-0045) is separate and no reader touches it.
+- **A per-`(event_id, sink)` delivery table.** Rejected as redundant with a
+  watermark: within a partition the single writer produces in `seq` order and
+  delivery is sequential, so "below is done, above is pending" is complete.
+  Retry needs no column — a failed delivery simply does not advance the cursor.
+- **Import the JSON document's contents.** Rejected as unearned: an importer,
+  a dedupe path and a crash-window argument, to preserve state nothing reads
+  except `stacktrace findings` on a session that is still open. The cost is a
+  notification lost for a session live at the moment of upgrade.
+- **Keep the JSON document and add a sidecar index.** Rejected: the whole-file
+  rewrite is the cost that does not survive scanning every session, and two
+  stores disagree the first time one write succeeds and the other does not.
+
+## Consequences
+
+Enables a reader to ask "what is new", which is the whole point, and stops the
+store discarding fields nobody can recover later.
+
+Costs and cautions:
+
+- **`seq` has gaps.** Verified against SQLite: an `INSERT OR IGNORE` that hits
+  the constraint still consumes the `AUTOINCREMENT` value. Harmless to a
+  `seq > last_seq` cursor, but nothing may assume contiguity. Reading the last
+  revision before inserting avoids churning the sequence on quiet ticks.
+- **Canonical serialisation is load-bearing.** Key ordering alone would produce
+  phantom revisions at scan cadence.
+- **One finding can occupy several rows**, so a batch holding two revisions of
+  one `event_id` should send only the later, and pruning must keep the newest
+  revision rather than the oldest.
+- **The database grows with no reader to prune behind it**, until the
+  deliverable that adds one.
+- Storing more per row widens what sits on disk for a retention window. ADR-0006
+  is unchanged — the added fields are catalogue text, identities, counts and
+  timestamps — but the invariant now deserves an exhaustive test in the manner
+  of `test_untrusted_content_never_travels.py`.
+
+## When to revisit
+
+- If a second writer becomes necessary — for instance if `sync detect` becomes
+  "drain the cursor now" and is implemented by opening the database rather than
+  asking the daemon over its socket. That would break the ordering invariant the
+  cursor rests on.
+- If revision churn proves costly on long sessions, which would argue for
+  collapsing superseded revisions at write time rather than at prune time.
+- If a reader ever needs a finding's full history rather than its latest state,
+  which the append-only shape happens to preserve but nothing currently uses.

stacktrace_cli-0.5.1/docs/adrs/0047-capture-activity-during-correlation-or-lose-it.md

@@ -0,0 +1,108 @@
+---
+id: 0047
+title: Capture activity counters during correlation, or lose them
+status: superseded
+date: 2026-09-22
+supersedes: null
+superseded-by: 0061
+amends: null
+amended-by: 0058
+---
+
+## Context
+
+A detect run uploads three things per agent kind: `detections`, `unknowns` and
+`activity` (`docs/specs/detection-upload.md`). Activity is per-session
+invocation counters — how many times each bucket of tooling actually ran —
+and the Cloud sums composition coverage from it.
+
+ADR-0046 makes the daemon's store a queue of detection revisions, and a later
+deliverable drains that queue to Fleet. Detections fit the queue naturally: they
+are events, appended, read by a monotonic cursor. Activity does not. It is a
+**rollup** — counters that change — and a `seq` cursor cannot express "send me
+the counters that moved".
+
+The tempting simplification is to leave activity out: keep one mechanism, carry
+findings only, and revisit if the console misses it. That was the working
+recommendation until `_collect_detect_run` was read closely:
+
+> Every activity row is built here, while the correlated record is in hand: a
+> `Detection` carries no counters, and the record is the only place the
+> `(call, resolution)` pairs exist.
+
+## Decision
+
+Activity counters are extracted during analysis, in the same transaction as
+that session's findings, and persisted as an upserted table keyed
+`(agent_kind, session_id, bucket)` carrying `updated_at`. A reader sends rows
+touched since its last drain — a selection rule alongside, not on, the `seq`
+axis.
+
+`agent_kind` is part of the key because `build_detect_payloads` groups activity
+by kind while an individual row carries none: the grouping exists only as a dict
+key at build time, so a reader rebuilding the payload from storage has no other
+way to recover it.
+
+The daemon's observer must stop discarding the analysis result after taking
+detections from it.
+
+**It lands with the store, not with the reader.** "Cannot be backfilled" is a
+statement about a *scan*, not a release — capture started at any time yields
+counters from then on — so deferring it to the consuming deliverable would be
+defensible. It is not done, for two reasons: the store is meant to hold
+everything the upload needs, so splitting the schema across deliverables buys a
+migration later; and the first upload would otherwise ship against an empty
+counter table, reporting zero coverage until enough scans had run. `_scan_claude_session` currently keeps only
+`tuple(detection_json(d) for d in result.run.detections)`; the correlated record
+that `activity_for_upload()` needs is in hand at that moment and thrown away.
+
+## Alternatives considered
+
+- **Leave activity out of the queue and revisit later.** Rejected on a fact,
+  having first been the recommendation. The counters exist only while the
+  correlated record is live, so omitting them is a **per-scan discard, not a
+  deferral**. Recovering them later means re-analysing transcripts that
+  retention may have outlived. "We can add it when someone asks" is false here.
+- **Rebuild activity from stored detections at send time.** Rejected because it
+  is not possible: a `Detection` carries no counters, and the `(call,
+  resolution)` pairs live only in the correlated record.
+- **Send detections with an empty `activity[]`.** Rejected as a silent product
+  regression. The Cloud sums coverage from `activity[]`, so every daemon-driven
+  run would report zero coverage — indistinguishable, to a reader of the
+  console, from an endpoint that genuinely ran nothing.
+- **Force activity onto the `seq` axis as append-only rows.** Rejected: a
+  counter that changes would append a row per bucket per scan, and a reader
+  would have to reduce the log to get the current value. The rollup is the
+  natural shape; pretending otherwise to preserve one mechanism costs more than
+  the second selection rule does.
+- **Re-collect sessions at upload time to recompute activity.** Rejected: it
+  reintroduces exactly the collection cost the cursor exists to remove, and
+  makes the upload path depend on transcripts still being present.
+
+## Consequences
+
+Coverage keeps working on a daemon-driven endpoint, and the counters survive
+transcript pruning because they are captured when they exist.
+
+Costs:
+
+- **A second selection rule.** A reader drains findings by `seq` and activity by
+  `updated_at`. The queue is no longer one mechanism, and that is accepted
+  deliberately rather than discovered.
+- **The store deliverable is not pure substitution.** It changes the observer,
+  not only the persistence layer, because the capture point is upstream of the
+  store.
+- Activity rows are not versioned. A drain sends the current value of a counter,
+  so a reader that misses a drain sees a jump rather than a series. That matches
+  what a rollup is and what the Cloud does with it, but it means activity has no
+  equivalent of ADR-0046's revision history.
+
+## When to revisit
+
+- If the Cloud ever distinguishes "no activity reported" from "no activity", the
+  simplification rejected here becomes available again.
+- If activity acquires a per-drain delta shape rather than a running total, at
+  which point it becomes an event and belongs on the `seq` axis after all.
+- If correlation is ever restructured so counters survive on the `Detection`
+  itself, which would remove the capture-point constraint this ADR exists to
+  record.

stacktrace_cli-0.5.1/docs/adrs/0048-the-daemon-keeps-a-leveled-content-free-activity-log.md

@@ -0,0 +1,59 @@
+---
+id: 0048
+title: The daemon keeps a leveled, content-free, size-capped activity log
+status: accepted
+date: 2026-09-23
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+`daemon.log` held only failures. On 2026-09-22 a daemon that had been healthy
+for hours, tracking 14 sessions, had a 90-byte log. There was no way to tell it
+from a stuck one. Telemetry was worse: `emit` drops events silently (opted out,
+lock busy, inadmissible, no key, refused by the SDK), and the SDK's `on_error`
+was a no-op.
+
+## Decision
+
+The daemon logs through stdlib `logging` to `daemon.log`, at DEBUG unless
+`STACKTRACE_DAEMON_LOG_LEVEL` says otherwise.
+
+1. **INFO:** start, stop, subscriber connect and disconnect, notification
+   delivered and acknowledged, composition refreshed.
+   **DEBUG:** each scan, with its reason and counts.
+   **WARNING:** analysis and refresh failures, and failed uploads.
+2. **Every telemetry event is `queued` or `dropped` with a reason.**
+   `queued` means the SDK returned a uuid. The reasons are a closed set:
+   `inadmissible`, `underivable`, `opted_out`, `lock_busy`,
+   `state_unwritable`, `no_project_key`, `sdk_refused` and `sdk_error`.
+3. **No content.** A line holds kinds, counts, class names and event ids. It
+   never holds a finding's title or body, an exception message, or transcript
+   text. Peer-supplied session ids are written with `%r`, so a newline in one
+   cannot forge a line.
+4. **Capped and private.** A 0600 `RotatingFileHandler`, 5 MiB plus one
+   backup. Only the daemon holding the lock opens it. After a rollover the
+   daemon moves its stdout and stderr onto the new file, so a crash traceback
+   is not lost.
+5. **Silent elsewhere.** The `stacktrace_cli` logger has a `NullHandler`, so
+   CLI processes print nothing new.
+
+## Alternatives considered
+
+- **Log "sent" on delivery:** not possible. posthog 7.59 reports failed
+  uploads through `on_error` and has no success hook, so `queued` is the
+  strongest true claim.
+- **Default to INFO:** rejected. The log exists to debug a daemon that looks
+  quiet, and the cap bounds what DEBUG costs.
+- **Log finding titles:** rejected. The untrusted-content test polices
+  findings, not log files, and the `event_id` is enough to look a finding up.
+- **Log per-session tracking in `DaemonService`:** deferred. ADR-0045 (PR #63)
+  removes subscriptions from the work path.
+
+## When to revisit
+
+If anything starts parsing `daemon.log`, move it to versioned JSONL. If the
+SDK gains a delivery hook, log `sent`.

stacktrace_cli-0.5.1/docs/adrs/0056-stop-a-resident-daemon-by-record-and-signal.md

@@ -0,0 +1,124 @@
+---
+id: 0056
+title: Stop a resident daemon by record and signal, and notice an upgrade by metadata
+status: superseded
+date: 2026-09-23
+supersedes: null
+superseded-by: 0059
+amends: 0045
+amended-by: null
+---
+
+## Context
+
+ADR-0045 made the daemon resident and named two ways for it to end: an explicit
+stop, and `version_label()` diverging from the installed distribution. It did
+not say how either is done, and both have a plausible-looking implementation
+that is wrong.
+
+**The version check.** `version_label()` is `__version__` plus, on an editable
+install, a commit read by shelling out to `git`. Two things follow. It is
+constant for the life of a process — `__version__` is an imported module
+constant, and the label is `functools.cache`d — so comparing it against itself
+is trivially equal and detects nothing. And re-computing it is a subprocess,
+which `docs/specs/daemon-scanning.md` explicitly forbids putting on the scan
+loop: *"it stays resolved once before the socket opens and cached. The scan
+loop must not move it onto a per-tick path."* The spec names the value to
+compare without naming what to compare it *against*, and the only thing that
+moves under a running process is the installed distribution's own metadata.
+
+**The stop.** A resident daemon needs an off switch that is not "kill it and
+hope". The obvious three are a control frame on the existing socket, a marker
+file the scan loop polls, and a signal. The first two each break something the
+deliverable holds fixed.
+
+**The status surface.** `daemon status` must report the *effective
+configuration and its source*, because fleet-wide drift is undebuggable without
+it. `daemon run` is `hidden=True` and is forked by `ensure_daemon()`, so its
+settings arrive from whatever environment that fork inherited — which is not
+necessarily the environment of the shell someone later runs `status` in.
+
+## Decision
+
+Four things, each the cheapest mechanism that does not break a constraint the
+deliverable already holds.
+
+1. **Version divergence compares the installed distribution version**, re-read
+   from `importlib.metadata` on each check, against the `__version__` half of
+   the `version_label()` resolved once before the socket opened. A distribution
+   with no record answers "not diverged".
+2. **`daemon stop` is `SIGTERM` to a recorded pid**, handled into setting the
+   loop's stop event so the composition thread closes and the socket file is
+   removed. It refuses to signal unless something is listening on the socket,
+   which is what bounds pid reuse.
+3. **`daemon disable` is a marker file** under the state directory, read before
+   the socket opens by `run_daemon()` *and* before the fork by
+   `ensure_daemon()`. `daemon enable` removes it.
+4. **The running daemon writes its effective configuration to a run-state
+   file** at startup — pid, started-at, version, and every setting with its
+   source — and `daemon status` reads that. The file is removed on a clean
+   exit, so a stale one is the signature of a crash.
+
+## Alternatives considered
+
+- **Re-compute `version_label()` on each check**, which is what the spec's
+  wording reads as literally. Rejected: it puts a `git` subprocess on the scan
+  loop, which the same spec forbids two paragraphs earlier, and it still cannot
+  detect a version change, because the `__version__` half is a module constant
+  the running process cannot re-import.
+- **Compare the whole label including the commit.** Rejected: the installed
+  metadata never carries a commit, so a build from a branch would read as
+  diverged on its first tick and the daemon would exit-loop.
+- **Build a maximum lifetime instead of, or as well as, the version check.**
+  Not built. The spec asks for the choice to be made deliberately rather than
+  for both mechanisms, and a restart trigger belongs with the external
+  supervision that is already deferred. The cost is recorded in ADR-0045 and
+  stands: a wedged process lasts until logout.
+- **A `stop` control frame on the notification socket.** Rejected: the wire
+  protocol and the plugin that speaks it are an explicit non-goal of this
+  deliverable, and a stop verb on a subscriber-facing protocol is a stop verb
+  any subscriber can send.
+- **A stop marker file the scan loop polls.** Rejected for latency: it costs up
+  to one `--scan-interval`, and the point of an off switch is that it works now.
+  The *disable* marker is a file for the opposite reason — it must be writable
+  when there is no process to signal.
+- **Record the stop pid in the existing flock file.** Rejected: the lock is
+  opened append-only and its emptiness is not load-bearing anywhere; a separate
+  run-state file carries the pid alongside the configuration `status` needs, so
+  one file answers both questions.
+- **Have `daemon status` re-derive the configuration from its own
+  environment.** Rejected: it would print the reader's settings labelled as the
+  daemon's, which is precisely the drift the row exists to expose. It remains
+  the *fallback* when no daemon is running, where the sources it reports are
+  honestly its own.
+
+## Consequences
+
+An upgrade is picked up within one scan interval of the new distribution
+landing, without a subprocess on the loop. An operator can stop, disable and
+inspect an endpoint without reading a log or hunting a pid.
+
+Costs, honestly:
+
+- **An editable checkout whose commit moves without a version bump is not
+  noticed.** This is the development case, where the developer restarts the
+  daemon anyway; it is the case the version check is least needed for.
+- **A second and third file in the state directory** (`daemon.disabled`,
+  `daemon-run.json`), both 0600 in the existing 0700 directory.
+- **Pid reuse is bounded, not eliminated.** A live socket is evidence that
+  *some* daemon is running, not proof that the recorded pid is that one. A
+  crashed daemon leaves a stale run-state file, and the socket check is what
+  stops it being acted on.
+- **`SIGINT` is handled the same as `SIGTERM`**, so a foreground `daemon run`
+  shuts down cleanly on Ctrl-C rather than leaving a socket file behind.
+
+## When to revisit
+
+- When external supervision lands: the stop signal becomes one of several
+  things a supervisor does, and exit codes have to be defined first —
+  `run_daemon()` still returns `0` on lock contention and on a live socket,
+  which `KeepAlive` would read as "do not restart".
+- If a wedged process is observed in the field, which is the trigger for adding
+  the maximum lifetime this ADR declined to build.
+- If the daemon ever needs to be stopped by something that is not the same user
+  on the same machine, which is the assumption the signal rests on.