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

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

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

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

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

stacktrace_cli-0.5.3/docs/adrs/0074-a-window-selects-findings-by-when-they-happened.md

@@ -0,0 +1,115 @@
+---
+id: 0074
+title: A window selects findings by when they happened
+status: accepted
+date: 2026-09-28
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+`--since` reads as a claim about findings, and was a claim about files.
+Collection selects whole transcripts by file mtime, so a session written inside
+the window is collected entire and every rule walks all of its turns. What a
+reader gets is therefore *every finding in every session whose file was touched
+in the range*, which is not what any of the three commands say.
+
+Found on a live monitor. The window was `06:10:11 → 06:15:11`, five minutes,
+and the page showed two findings: a `credential-egress` at `06:14:12`, correctly
+in range, and an `agent-blocked` at `05:56:52` — eighteen minutes before the
+window began. That finding belongs to a 538-turn session started the previous
+night and still being typed into, so its transcript was written a minute before
+the pass and the whole session came with it. `summary.detections` was 2, so this
+was the pipeline's answer and not the page's.
+
+The reverse reading is the same mistake and does not occur: a finding's clock
+comes from the turns it cites and a transcript's mtime is its last write, so
+mtime is never earlier than `occurred_end`. A finding inside the window always
+sits in a file the mtime rule already admitted. The rule over-admits and never
+under-admits.
+
+## Decision
+
+A window selects findings by **when they happened**. `analyse` reports a
+finding when its own `occurred_end` reaches into the window, and `detect`,
+`monitor` and `sync detect` all reach it through that one call — `cli.py`
+already states the invariant that the three must not be able to disagree about
+what was found.
+
+Overlap decides, and both ends are tested. `occurred_end` against the start, so
+a rule firing across a run of turns belongs in the window its last citation
+reaches — what a reader asking *what is happening now* means. `occurred_start`
+against the end, so a finding straddling the boundary is not dropped for
+finishing late.
+
+The upper bound is not ceremony. `analyse` takes `window_end` *before*
+collection, deliberately, so a window cannot claim to cover a session that
+started while the pipeline ran — and collection then reads files that may have
+been appended to in between. A finding can therefore carry a clock later than
+the end the caller is shown, and reporting it would contradict the heading the
+window prints.
+
+A finding carrying no clock, or one whose clock is naive and cannot be compared
+against an aware bound, is reported rather than judged; hiding a real finding
+over a missing field is the more expensive mistake.
+
+**`analyse_sessions` is deliberately excluded.** The daemon passes a watermark
+deciding which transcripts to re-read, not a range a person chose, and its
+docstring already says it "stamps it as `window_start` and analyses the view
+whole". Its findings are the record that feeds the store, the webhook and Fleet,
+where narrowing by a window would lose a finding rather than hide it.
+
+## Alternatives considered
+
+- **Filter while rendering the monitor.** Rejected, and this was tried first.
+  It gives the page an admission rule of its own, so `detect --since 5m` prints
+  a finding `monitor --since 5m` hides. ADR-0026 clause 2 and the monitor spec's
+  robustness bar — "a page that can invent, alter or suppress a detection" —
+  both forbid it.
+- **Carry findings forward in the page, or in the snapshot beside it.** Rejected.
+  Retention in the browser makes the answer depend on how long a tab has been
+  open: a reload and an open tab disagree about the same window. Moving the
+  carry-forward into the watcher relocates the same violation from the renderer
+  to the server, since a snapshot would then carry findings the current pass did
+  not produce. Both were attempted on the branch that became this ADR and both
+  are reverted.
+- **Admit sessions by their events rather than their mtime, at collection.**
+  Rejected as unnecessary rather than wrong. It would reach the same result by
+  reading more files, and the asymmetry above means there is nothing to gain:
+  no finding inside the window lives in a file the mtime rule excluded.
+- **Exempt `sync detect`, so only the two read-only views scope.** Rejected. It
+  is a view of a range someone asked for, and `cli.py`'s invariant does not
+  allow two of the three to mean one thing and the third another. What must not
+  be scoped is the daemon's record, and that is a different entry point.
+
+## Consequences
+
+`--since` means one thing in all three commands, and the page's window agrees
+with its own heading.
+
+The cost is that **`sync detect` uploads become window-scoped**, which is a
+change to something that leaves the machine. A finding older than the window is
+no longer uploaded by that command even when its session was touched inside the
+range. This is the intended reading of `--since 7d` — findings from the last
+seven days — but it is a narrowing, and an operator who wants everything must
+say so with a wider window. The daemon's own upload path is unaffected and
+remains the durable record.
+
+One test moved with the semantics rather than around them:
+`test_an_anonymous_session_does_not_take_a_known_agents_findings_with_it` builds
+its session at the shared fixture moment, about a month before any realistic
+window, and now declares a window wide enough to reach it. Its subject is
+routing, not recency.
+
+## When to revisit
+
+- **If a finding's clock ever becomes unreliable** — a reader that cannot date
+  its turns, an imported or replayed transcript whose mtime is rewritten — the
+  asymmetry this rests on ("mtime is never earlier than `occurred_end`") stops
+  holding, and admission would need to read events rather than trust the file.
+- **If `sync detect` grows a separate "upload everything" mode**, the
+  window-scoping decided here stops being the whole story for that command and
+  the split should be recorded rather than inferred from a flag.

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/docs/adrs/INDEX.md

@@ -103,4 +103,5 @@ supersedes anything yet.
 - [0071](0071-render-the-allowlisted-payload-per-destination.md) — **Render the allowlisted payload per destination, without widening it.** Amends ADR-0067. `webhook.toml` gains `format`: `stacktrace` (the ADR-0067 JSON body) or `slack` (the same allowlisted facts as the flat `text` body Slack's Incoming Webhooks require). Absence means `stacktrace`, so existing configs are untouched. Both shapes render from `_payload()`, never the stored row, so rendering for a human reader cannot reach titles, remediation, evidence or spans — which is exactly where someone will next propose widening the allowlist. `configure` resolves the format from the URL host by default, storing the settled value rather than `auto`, because Slack accepts exactly one body shape and requiring `--format slack` only asks the user to restate the single answer that can work. An explicit `--format stacktrace` against a Slack host is still refused: Slack answers that body with HTTP 400 `no_text` and ADR-0068 removed the retry limit, so the pairing retries an identical rejected payload forever. `--format` remains for endpoints that take a Slack body without being Slack (Mattermost, Discord's `/slack` path), which no host detection can recognise. Read before adding a format, before letting a renderer read the stored row, or before treating a destination that needs more than the allowlisted facts as a format rather than an amendment to ADR-0067.
 
 - [0072](0072-host-supervisors-own-daemon-restarts.md) — **Host supervisors own daemon restarts.** `daemon run` is the foreground service; `daemon start` fully detaches and execs it once, with readiness but no restart loop. `stop` and `status` use stable controls on the existing Unix socket, while one daemon lock and one short transition lock replace PID records, supervisor locks and disable markers. Read before adding a restart loop, PID signalling, a second control socket, automatic upgrade exits, or lifecycle side effects to an agent adapter.
-- [0073](0073-name-what-fired-and-which-component.md) — **Name what fired and which component, and render it where Slack shows colour.** Amends ADR-0067 and ADR-0071. `title`, `subject.component_type`/`subject.name` and deduplicated `evidence[].kind` as `evidence_kinds` join the projection for every format, additively and optionally, because `drain` retries a row whose mapping raises without limit and a required new field would wedge delivery. What makes `title` safe is **not** one title per rule — `stacktrace-agent-blocked` selects among four reason titles, and a corpus holding one of them is how that weaker premise first reached an ADR — but that every title is a string literal this package owns (`_TITLES` by rule id, a per-reason literal in `blocked.py`, or a literal at the detection site, falling back to the rule id), never interpolated from session content; `tests/test_title_disclosure_invariant.py` walks the detector's AST to enforce that over the source rather than a corpus. An `unplaced` subject's name is excluded outright and every mapped name is `find_secrets`-scanned whatever its kind, since a component alias comes from the agent's own `.mcp.json`. `subject.identity`, remediation, evidence `detail` and spans stay out; every mapped string is bounded at 200 characters. For Slack the body becomes an attachment — `attachments[].color` is the only colour Slack exposes anywhere, so the bar carries severity — with no top-level `text` (it rendered the title twice), no inline `code` (Slack tints it a fixed red that would fight the bar) and mrkdwn control characters escaped, because `subject.name` reaches a parser that reads `<url|label>` as a link. The rule id and event id leave the Slack body; the event id stays on `X-Stacktrace-Event-ID` for receivers that deduplicate. Sends real component names to a third party, deliberately. The boundary rule is now *a literal from this package's own catalogue, or a short identifier naming a component or classifier, secret-scanned and bounded* — never a field written about this particular session. Read before mapping a fourth field.
+- [0073](0073-name-what-fired-and-which-component.md) — **Name what fired and which component, and render it where Slack shows colour.** Amends ADR-0067 and ADR-0071. `title`, `subject.component_type`/`subject.name` and deduplicated `evidence[].kind` as `evidence_kinds` join the projection for every format, additively and optionally, because `drain` retries a row whose mapping raises without limit and a required new field would wedge delivery. What makes `title` safe is **not** one title per rule — `stacktrace-agent-blocked` selects among four reason titles, and a corpus holding one of them is how that weaker premise first reached an ADR — but that every title is a string literal this package owns (`_TITLES` by rule id, a per-reason literal in `blocked.py`, or a literal at the detection site, falling back to the rule id), never interpolated from session content; `tests/test_title_disclosure_invariant.py` walks the detector's AST to enforce that over the source rather than a corpus. An `unplaced` subject's name is excluded outright and every mapped name is `find_secrets`-scanned whatever its kind, since a component alias comes from the agent's own `.mcp.json`. `subject.identity`, remediation, evidence `detail` and spans stay out; every mapped string is bounded at 200 characters. For Slack the body becomes an attachment — `attachments[].color` is the only colour Slack exposes anywhere, so the bar carries severity — with no top-level `text` (it rendered the title twice), no inline `code` (Slack tints it a fixed red that would fight the bar) and mrkdwn control characters escaped, because `subject.name` reaches a parser that reads `<url|label>` as a link. The rule id and event id leave the Slack body; the event id stays on `X-Stacktrace-Event-ID` for receivers that deduplicate. Sends real component names to a third party, deliberately. The boundary rule is now *a literal from this package's own catalogue, or a short identifier naming a component or classifier, secret-scanned and bounded* — never a field written about this particular session. Read before mapping a fourth field.
+- [0074](0074-a-window-selects-findings-by-when-they-happened.md) — **A window selects findings by when they happened.** `--since` read as a claim about findings and was a claim about files: collection selects whole transcripts by mtime, so a session written inside the window is collected entire and every rule walks all of its turns. A 538-turn session still being typed into put an 18-minute-old finding in a five-minute window. `analyse` now reports a finding when its own `occurred_end` reaches into the window, so `detect`, `monitor` and `sync detect` cannot disagree about one `--since` (`cli.py`'s invariant). Overlap decides and both ends are tested: `occurred_end` against the start, so a run of turns belongs in the window its last citation reaches, and `occurred_start` against the end, because `window_end` is taken *before* collection and a file appended in between can carry a clock past it. An undated or naive clock is reported rather than judged. Only ever narrows, and that is structural: a transcript's mtime is its last write and a finding's clock comes from the turns it cites, so mtime is never earlier than `occurred_end` and nothing in-window was ever excluded. `analyse_sessions` is excluded deliberately — the daemon's `since` is a watermark, and its findings are the record behind the store, the webhook and Fleet. The cost is stated: `sync detect` uploads become window-scoped. Read before filtering findings in a renderer, carrying them forward in a page or a snapshot, or scoping the daemon's record.

stacktrace_cli-0.5.3/docs/releases/v0.5.3.md

@@ -0,0 +1,70 @@
+# 0.5.3 — a window means what it says
+
+`--since` read as a claim about findings and was a claim about files.
+Collection selects whole transcripts by mtime, so a session written inside the
+window was collected entire and every rule walked all of its turns. A
+`credential-egress` at 14:12, correctly in range, beside an `agent-blocked` at
+05:56 — eighteen minutes before the window began, carried in by a long-running
+session whose file happened to be touched inside the window.
+
+This release moves the filter from the file to the finding. `analyse` now
+reports a finding when its own `occurred_end` reaches into the window, and every
+surface that shows a time range — `detect`, `monitor`, `sync detect` — reaches
+the pipeline through that one call. A window heading that says 06:10–06:15
+no longer includes a finding from 05:56.
+
+## Window semantics
+
+A finding belongs to the window when its time range overlaps the window's:
+`occurred_end >= window_start` and `occurred_start <= window_end`. Both ends are
+tested, not only the start — a finding straddling the boundary is not dropped
+for finishing late, and a finding whose file was touched inside the window but
+whose clock is entirely outside it is no longer included.
+
+Undated findings and findings with naive clocks are unchanged: reported rather
+than judged.
+
+## The monitor answers a range switch immediately
+
+Clicking a different range in the monitor queued the window and returned; the
+loop then slept the whole interval before the pass that would answer it. At the
+default four seconds that is up to four seconds of a page doing nothing visible.
+The wait between passes now ends early when a reader asks for a different range,
+so the click is answered on the next pass rather than after the next sleep.
+
+## Cloud webhook configuration moves to the boot hook
+
+A cloud VM's webhook was configured in the setup script, which runs once when
+the environment is built. `stacktrace-cloud-setup` now seeds only the boot
+hook, and the boot hook configures the webhook per-session — so a token rotation
+or a new webhook URL takes effect on the next session without rebuilding the
+environment.
+
+Webhook-only sessions — those with no Fleet subscription — can now reach
+configuration, where before the configuration path required a subscription
+handshake that a webhook-only session could not complete.
+
+## Bug fixes
+
+Supersession claimed before the pass completing it was finished, a retained
+card offering controls its session could no longer serve, the renderer's own
+window rule disagreeing with the pipeline's, daemon stop's progress line
+serialised behind the transition lock, and daemon lifecycle events not visible
+in the log.
+
+## Install
+
+`uv tool install stacktrace-cli==0.5.3` or `pip install stacktrace-cli==0.5.3`.
+Python 3.11 or newer; macOS and Linux.
+
+## Compatibility
+
+Beta — no back-compat hedging.
+
+- **A time window now filters by finding time, not file time.** `detect
+  --since`, `monitor` and `sync detect` may return fewer findings than before —
+  specifically, the ones whose clock was outside the window but whose file was
+  inside it. This is the intended behavior; the previous output was wrong.
+- **The monitor responds to range switches faster.** The improvement is
+  user-visible but requires no action.
+- **A monitor and a CLI of the same version are still required.**

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stacktrace-cli"
-version = "0.5.2"
+version = "0.5.3"
 description = "CLI for Stacktrace — Detection and Response platform for AI Agents."
 readme = "README.md"
 requires-python = ">=3.11"

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/src/stacktrace_cli/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 
 # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
 # logged in any other process would reach Python's last-resort handler and

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/src/stacktrace_cli/analysis.py

@@ -204,7 +204,7 @@ def analyse(
         root=root,
         session_ids=session_ids,
     )
-    return _analyse_sessions(
+    found = _analyse_sessions(
         sessions,
         window_start=window_start,
         window_end=window_end,
@@ -220,6 +220,7 @@ def analyse(
         jev_key=jev_key,
         history=history,
     )
+    return scoped_to_window(found)
 
 
 def analyse_sessions(
@@ -373,6 +374,65 @@ def _correlated(
     )
 
 
+def _reaches(detection: Any, window_start: datetime, window_end: datetime) -> bool:
+    """Whether this finding's own span overlaps the window.
+
+    Both ends are tested, because both can be crossed. `occurred_end` against
+    the start, so a rule firing across a run of turns belongs in the window
+    its last citation reaches; `occurred_start` against the end, so a finding
+    straddling the boundary is still reported rather than dropped for
+    finishing late.
+
+    The upper bound is not ceremony. `analyse` takes `window_end` *before*
+    collection -- deliberately, so a window cannot claim to cover a session
+    that started while the pipeline ran -- and collection then reads files
+    that may have been appended to in between. A finding can therefore carry
+    a clock later than the end the caller is shown, and reporting it would
+    contradict the heading the window prints.
+
+    A finding with no clock, or one whose clock is naive and cannot be
+    compared against an aware bound, is reported rather than judged: hiding a
+    real finding over a missing field is the more expensive mistake.
+    """
+    end = detection.occurred_end or detection.occurred_start
+    start = detection.occurred_start or detection.occurred_end
+    if end is None or start is None or end.tzinfo is None or start.tzinfo is None:
+        return True
+    return end >= window_start and start <= window_end
+
+
+def scoped_to_window(analysis: Analysis) -> Analysis:
+    """The same analysis, reporting only the findings the window reaches.
+
+    A window selects whole transcripts by file mtime, so a session written
+    inside it is collected entire and every rule walks all of its turns. A
+    long session still being typed into therefore carried its whole history
+    into whatever range the caller asked for: a 538-turn session last active a
+    minute ago put an 18-minute-old block in a five-minute window.
+
+    Only ever narrowing, and that is not a coincidence. A finding's clock
+    comes from the turns it cites, and a transcript's mtime is its last write,
+    so mtime is never earlier than `occurred_end`. A finding inside the window
+    therefore always sits in a file the window already admitted -- this can
+    drop what the mtime rule over-admitted, and can never need to recover
+    anything it excluded.
+
+    Applied by `analyse`, so `detect`, `monitor` and `sync detect` cannot
+    disagree about one `--since` (`cli.py` states that invariant). Not by
+    `analyse_sessions`: the daemon passes a watermark rather than a range a
+    person chose, and its findings are the record that feeds the store, the
+    webhook and Fleet, where a window has no business narrowing anything.
+    """
+    kept = tuple(
+        d
+        for d in analysis.run.detections
+        if _reaches(d, analysis.window_start, analysis.window_end)
+    )
+    if len(kept) == len(analysis.run.detections):
+        return analysis
+    return replace(analysis, run=replace(analysis.run, detections=kept))
+
+
 def _unplaced(sessions: SessionView, *, window_start: datetime, window_end: datetime) -> Analysis:
     """The sessions as read, before anything has been correlated or judged.
 
@@ -498,11 +558,13 @@ def analyse_progressively(
         stage carrying fewer sessions than the preview did would make the count
         on the page go backwards.
         """
-        return Analysis(
-            run=run,
-            view=replace(view, sessions=sessions),
-            window_start=window_start,
-            window_end=window_end,
+        return scoped_to_window(
+            Analysis(
+                run=run,
+                view=replace(view, sessions=sessions),
+                window_start=window_start,
+                window_end=window_end,
+            )
         )
 
     # The detector derives these from the view, and a stage that has not judged

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/src/stacktrace_cli/cloud/setup.sh

@@ -39,9 +39,14 @@
 #                      from STACKTRACE_ASSET_EXTERNAL_ID in the environment
 #   --root DIR         treat DIR as / (for testing)
 #
-# The remote token and API URL are read by the boot hook at session time from
-# STACKTRACE_REMOTE_TOKEN and STACKTRACE_REMOTE_API_URL, not here: they belong
-# to the environment's variables, not to the snapshot this seeds.
+# The remote token and API URL, and the Slack webhook URL, are read by the boot
+# hook at session time from STACKTRACE_REMOTE_TOKEN, STACKTRACE_REMOTE_API_URL
+# and STACKTRACE_SLACK_WEBHOOK_URL, not here: they belong to the environment's
+# variables, not to the snapshot this seeds. The webhook in particular must be
+# configured by the boot hook and not by this script, because
+# `webhook configure` writes `$HOME/.config/stacktrace/webhook.toml` and this
+# script runs as root — a webhook configured here would land in /root and the
+# daemon, running as the session user, would read a home that has none.
 set -uo pipefail
 
 ASSET_ID="${STACKTRACE_ASSET_EXTERNAL_ID:-}"
@@ -54,7 +59,7 @@ while [ $# -gt 0 ]; do
     # the loop spins forever — a malformed invocation would hang setup.
     --asset-id) [ $# -ge 2 ] || { echo "✗ --asset-id needs a value" >&2; exit 2; }; ASSET_ID="$2"; shift 2 ;;
     --root) [ $# -ge 2 ] || { echo "✗ --root needs a value" >&2; exit 2; }; ROOT="$2"; shift 2 ;;
-    -h|--help) sed -n '2,44p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -h|--help) sed -n '2,49p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) echo "✗ unknown argument: $1" >&2; exit 2 ;;
   esac
 done
@@ -108,14 +113,36 @@ cat > "$BOOT" <<'BOOTSCRIPT' || { echo "✗ cannot write $BOOT" >&2; exit 1; }
 set -u
 [ "${CLAUDE_CODE_REMOTE:-}" = "true" ] || exit 0
 command -v stacktrace >/dev/null 2>&1 || exit 0
-[ -n "${STACKTRACE_REMOTE_TOKEN:-}" ] || exit 0
+# A webhook is an independent subscriber, not a Fleet feature (ADR-0067): a
+# session with only STACKTRACE_SLACK_WEBHOOK_URL set still needs the daemon
+# running to drain it, so the remote token gates `remote configure` alone,
+# never this whole hook.
+if [ -z "${STACKTRACE_REMOTE_TOKEN:-}" ] && [ -z "${STACKTRACE_SLACK_WEBHOOK_URL:-}" ]; then
+  exit 0
+fi
 
 STATE="$HOME/.local/state/stacktrace"
 mkdir -p "$STATE" && chmod 700 "$STATE"
 
-stacktrace remote configure \
-  --token "$STACKTRACE_REMOTE_TOKEN" \
-  --api-url "${STACKTRACE_REMOTE_API_URL:-https://api.stacktrace.ai}" >/dev/null 2>&1 || true
+if [ -n "${STACKTRACE_REMOTE_TOKEN:-}" ]; then
+  stacktrace remote configure \
+    --token "$STACKTRACE_REMOTE_TOKEN" \
+    --api-url "${STACKTRACE_REMOTE_API_URL:-https://api.stacktrace.ai}" >/dev/null 2>&1 || true
+fi
+
+# The Slack endpoint is session-time configuration like the token above, not
+# part of the snapshot: written here it lands in the session user's home, which
+# is the home the daemon started below reads `webhook.toml` from. Rotating the
+# URL is then an environment-variable change, with no snapshot to rebuild.
+# `--secret` is always passed explicitly, empty if unset: the option prompts
+# when neither it nor STACKTRACE_WEBHOOK_SECRET is given, and a prompt in a hook
+# with no terminal aborts the command. Configured before the daemon starts, so
+# the daemon reads the endpoint at startup rather than waiting for a drain.
+if [ -n "${STACKTRACE_SLACK_WEBHOOK_URL:-}" ]; then
+  stacktrace webhook configure \
+    --url "$STACKTRACE_SLACK_WEBHOOK_URL" \
+    --secret "${STACKTRACE_WEBHOOK_SECRET:-}" >/dev/null 2>&1 || true
+fi
 
 # Streams redirected because own_std_streams only re-points fd 1/2 on log
 # rollover; without this the daemon inherits the hook's pipe to Claude Code.

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/src/stacktrace_cli/daemon/cli.py

@@ -140,13 +140,27 @@ def run_command(
         _reject_unobservable_kinds(config)
     except ValueError as error:
         raise click.ClickException(str(error)) from error
-    from .lifecycle import DETACHED_ENV
+    from .lifecycle import DETACHED_ENV, StartOutcome
+
+    detached = os.environ.get(DETACHED_ENV) == "1"
+
+    def report_ready() -> None:
+        if not detached:
+            click.echo(
+                "Stacktrace daemon is running in the foreground. Press Ctrl-C to stop.",
+                err=True,
+            )
 
     status = run_daemon(
         paths,
         config,
-        own_std_streams=os.environ.get(DETACHED_ENV) == "1",
+        own_std_streams=detached,
+        on_ready=report_ready,
     )
+    if status is StartOutcome.ALREADY_RUNNING:
+        if not detached:
+            click.echo("Stacktrace daemon is already running.")
+        return
     if status:
         raise click.exceptions.Exit(status)
 
@@ -324,6 +338,7 @@ def start() -> None:
     from .lifecycle import StartOutcome, start_daemon, transition_lock
 
     paths = RuntimePaths.from_environment()
+    click.echo("Starting Stacktrace daemon...", err=True)
     try:
         with transition_lock(paths.transition_lock):
             outcome = start_daemon(paths)
@@ -342,6 +357,7 @@ def stop() -> None:
     from .lifecycle import daemon_lock_held, transition_lock
 
     paths = RuntimePaths.from_environment()
+    click.echo("Stopping Stacktrace daemon...", err=True)
     with transition_lock(paths.transition_lock):
         if not daemon_lock_held(paths.lock):
             click.echo("Stacktrace daemon is not running.")
@@ -416,6 +432,7 @@ def flush() -> None:
             "no daemon is running, so there is no queue to drain; this endpoint "
             "uploads by scanning instead — run `stacktrace remote sync detect`"
         )
+    click.echo("Flushing queued findings...", err=True)
     try:
         result = request_flush(paths.socket)
     except (OSError, ProtocolError) as error:
@@ -451,6 +468,7 @@ def sync_bom() -> None:
         raise click.ClickException(
             "no daemon is running; to upload without one, run `stacktrace remote sync endpoint`"
         )
+    click.echo("Syncing endpoint composition...", err=True)
     try:
         result = request_sync_bom(paths.socket)
     except (OSError, ProtocolError) as error:

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/src/stacktrace_cli/daemon/runtime.py

@@ -15,7 +15,7 @@ from contextlib import ExitStack, contextmanager, suppress
 from datetime import UTC, datetime
 from pathlib import Path
 from types import FrameType
-from typing import TextIO, TypeVar
+from typing import Literal, TextIO, TypeVar
 
 from stacktrace_cli.build import version_label
 from stacktrace_cli.correlate.orchestrate import build_compositions
@@ -98,13 +98,18 @@ def follow_notifications(
     maximum_delay: float = 2.0,
 ) -> None:
     reported_disconnect = False
+    subscribed_once = False
     delay = reconnect_delay
 
     def _on_subscribed() -> None:
-        nonlocal reported_disconnect, delay
+        nonlocal reported_disconnect, subscribed_once, delay
         if reported_disconnect:
             stderr.write("Stacktrace monitor reconnected\n")
             stderr.flush()
+        elif not subscribed_once:
+            stderr.write("Stacktrace monitor connected\n")
+            stderr.flush()
+        subscribed_once = True
         reported_disconnect = False
         delay = reconnect_delay
 
@@ -192,8 +197,12 @@ def _await_initial_compositions(
 
 
 def run_daemon(
-    paths: RuntimePaths, config: DaemonConfig | None = None, *, own_std_streams: bool = False
-) -> int:
+    paths: RuntimePaths,
+    config: DaemonConfig | None = None,
+    *,
+    own_std_streams: bool = False,
+    on_ready: Callable[[], None] = lambda: None,
+) -> int | Literal[StartOutcome.ALREADY_RUNNING]:
     """The resident process: a socket, a scan cadence, and two ways to stop.
 
     `config` is resolved by the caller (`daemon/cli.py`) so a bad value fails
@@ -203,10 +212,10 @@ def run_daemon(
     with _daemon_lock(paths.lock) as acquired:
         if not acquired:
             report_start(StartOutcome.ALREADY_RUNNING)
-            return 0
+            return StartOutcome.ALREADY_RUNNING
         if daemon_is_running(paths.socket):
             report_start(StartOutcome.ALREADY_RUNNING)
-            return 0
+            return StartOutcome.ALREADY_RUNNING
         # Opened only by the lock holder: two processes rotating one file
         # would each rename the other's writes away (ADR-0048).
         handler = activity_log.configure(paths.log, own_std_streams=own_std_streams)
@@ -425,7 +434,12 @@ def run_daemon(
             # that raises must not skip `compositions.close()`.
             webhook_worker.start()
             try:
-                service.run(on_ready=lambda: report_start(StartOutcome.STARTED))
+
+                def ready() -> None:
+                    report_start(StartOutcome.STARTED)
+                    on_ready()
+
+                service.run(on_ready=ready)
             finally:
                 webhook_worker.close()
                 try:

{stacktrace_cli-0.5.2 → stacktrace_cli-0.5.3}/src/stacktrace_cli/monitor/watch.py

@@ -29,6 +29,7 @@ from collections.abc import Callable, Iterable
 from dataclasses import replace
 from pathlib import Path
 from threading import Lock
+from time import monotonic
 from typing import Any
 
 from stacktrace_cli.analysis import Analysis, analyse_progressively
@@ -103,6 +104,13 @@ def _last_active(analysis: Analysis, by_stem: dict[str, float]) -> dict[tuple[st
     return dated
 
 
+#: How long the wait between passes sleeps at a time. Short enough that a
+#: reader clicking a range is answered as if there were no wait at all, long
+#: enough that an idle monitor is not spinning: ten wake-ups a second on a
+#: thread that does nothing with them.
+_WAKE_SLICE = 0.1
+
+
 class Watcher:
     """Runs the pipeline when the machine has changed, and publishes the result."""
 
@@ -133,6 +141,9 @@ class Watcher:
         #: because the tick reads those on another thread and a change landing
         #: mid-pass would give one snapshot two windows.
         self._pending_window: str | None = None
+        #: Set when a reader asks for a different range, so the wait between
+        #: passes ends and the new window is read now rather than next tick.
+        self._wake = threading.Event()
         #: Bumped by everything that says "the last answer is stale". The
         #: fingerprint alone cannot carry that: computing one is a walk of
         #: every transcript, and an invalidation arriving during the walk would
@@ -254,6 +265,9 @@ class Watcher:
                 return
             self._pending_window = since
             self._invalidate_locked()
+        # Outside the lock: the waiting thread takes it at the top of a tick,
+        # and setting an event is not work worth holding a lock for.
+        self._wake.set()
 
     def _take_pending_window(self) -> int:
         """Apply the newest asked-for window, once, at the top of a tick.
@@ -549,10 +563,32 @@ class Watcher:
         Waits on the event rather than sleeping, so a shutdown is immediate
         instead of taking up to one interval — the difference between Ctrl-C
         feeling instant and feeling broken.
+
+        A range the reader asked for cuts the wait the same way. Without that
+        the click was answered by the *next* scheduled pass, so a switch cost
+        up to a whole interval of nothing happening before the work even
+        started, on top of the pass itself.
         """
         while not stop.is_set():
+            self._wake.clear()
             self.tick()
-            stop.wait(self._interval)
+            self._wait_between_passes(stop)
+
+    def _wait_between_passes(self, stop: threading.Event) -> None:
+        """Sleep off the interval, ending early for a stop or a new range.
+
+        Polled in slices rather than waited on directly: `stop` belongs to the
+        caller — a test builds its own — so it cannot be made to signal this
+        watcher's wake, and waiting on the wake alone would leave a shutdown
+        sitting out the interval. The slice is what buys both, and it is short
+        enough that a click is answered as if the wait were not there.
+        """
+        deadline = monotonic() + self._interval
+        while not stop.is_set() and not self._wake.is_set():
+            remaining = deadline - monotonic()
+            if remaining <= 0:
+                return
+            stop.wait(min(_WAKE_SLICE, remaining))
 
     def start(self) -> tuple[threading.Thread, threading.Event]:
         stop = threading.Event()