stacktrace-cli 0.5.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 # 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/cli.py

@@ -40,6 +40,7 @@ from .sessions.access import collect_sessions
 from .sessions.render import render_json, render_text
 from .telemetry import emit_error
 from .telemetry.cli import telemetry as telemetry_cmd
+from .webhook.cli import webhook as webhook_cmd
 
 PASSTHROUGH: Final = ("scan", "bom", "policy")
 
@@ -586,3 +587,4 @@ main.add_command(monitor)
 main.add_command(daemon_cmd, "daemon")
 main.add_command(findings)
 main.add_command(telemetry_cmd, "telemetry")
+main.add_command(webhook_cmd, "webhook")

stacktrace_cli/cloud/__init__.py

@@ -0,0 +1,39 @@
+"""One entry point for a Claude Code cloud environment's setup script.
+
+A cloud environment's setup script runs once, as root, before the filesystem is
+snapshotted and reused by every later session. What a session needs that is not
+the CLI itself — the per-session boot hook and the asset identity — has to be
+laid down there so it lands inside the snapshot.
+
+Rather than paste that into the setup-script box, a setup script installs the
+CLI and runs this:
+
+    UV_TOOL_DIR=/usr/local/share/uv-tools UV_TOOL_BIN_DIR=/usr/local/bin \
+      uv tool install stacktrace-cli
+    stacktrace-cloud-setup
+
+Both variables matter: setup runs as root, and `uv tool install`'s root
+defaults put the tool's environment under `/root/.local/share/uv/tools` and the
+linked executable under `/root/.local/bin` — both inside `/root`, which a later
+non-root session user cannot traverse. `UV_TOOL_BIN_DIR` alone moves the
+symlink but not the environment it points into, so `command -v stacktrace` would
+find the binary while running it still fails; both must move.
+
+The work itself is `setup.sh`, shipped beside this module so it travels in the
+wheel. This shim only locates it and hands off, so the logic stays one auditable
+bash file rather than being reimplemented in Python.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    script = Path(__file__).with_name("setup.sh")
+    # execvp so the process *becomes* bash: its exit status is the setup
+    # script's, which is what the environment reads to decide the session may
+    # start, and there is no Python frame left to swallow a signal.
+    os.execvp("bash", ["bash", str(script), *sys.argv[1:]])

stacktrace_cli/cloud/setup.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Lay down everything a Claude Code cloud session needs, at environment setup.
+#
+# Run once by the environment's setup script, as root, before the filesystem is
+# snapshotted. Two things, both of which must be inside that snapshot because
+# the setup script does not run again for later sessions:
+#
+#   1. /usr/local/bin/stacktrace-boot.sh — the per-session hook that configures
+#      the remote and starts the daemon. Registered as a SessionStart hook in
+#      every home so it fires whichever user the session runs as.
+#   2. The asset identity, in every home's ~/.config/stacktrace/asset-id, so
+#      `stacktrace remote sync` resolves it at the persisted rung (ADR-0065)
+#      instead of minting a fresh asset per session.
+#
+# The telemetry install id is deliberately NOT seeded here. Seeding it would
+# make `read_install_id()` non-None before any event runs, so the one-time
+# `installed` event (which `emit()` synthesizes only when the id is absent)
+# would never fire. Left unseeded, the daemon's first in-session event mints the
+# id and fires `installed` once per VM, correctly attributed `remote=true`
+# because it runs inside the session. Counting one install per VM rather than
+# per environment is ADR-0043's documented cloud tradeoff; per-environment is
+# not cleanly achievable for an ephemeral VM (a setup-time emit would carry the
+# wrong `remote` value and could not flush from a one-shot process).
+#
+# Every home rather than $HOME: setup runs as root and the user a session runs
+# as is not documented, so writing all of them removes the guess. The asset id
+# is unconditional — each environment instance gets its own, and a leftover from
+# a previous snapshot must not win.
+#
+# Scope (ADR-0070): this seeds the snapshot and starts the daemon per session.
+# It does not own daemon lifetime across a supervisor — that is ADR-0066, and a
+# cloud VM is one session per VM, so the daemon dying with the VM is correct.
+# The environment this targets is a fresh, single-tenant snapshot: it does not
+# defend against adversarial or pre-existing symlinks and special files in a
+# home, because that home does not exist until this run creates it.
+#
+# Options (all optional):
+#   --asset-id VALUE   use this asset id instead of minting one; also taken
+#                      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.
+set -uo pipefail
+
+ASSET_ID="${STACKTRACE_ASSET_EXTERNAL_ID:-}"
+ROOT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    # `$# -ge 2` before the shift: without it, `--root` with no operand leaves
+    # the positional parameters unchanged under `set -u` with no `set -e`, and
+    # 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 ;;
+    *) echo "✗ unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+LOG="${ROOT}/var/log/stacktrace-cloud-setup.log"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+exec > >(tee -a "$LOG") 2>&1
+echo "=== stacktrace cloud setup $(date -u +%FT%TZ) ==="
+
+# ---- identities ----------------------------------------------------------
+_uuid() {
+  if [ -r /proc/sys/kernel/random/uuid ]; then
+    cat /proc/sys/kernel/random/uuid
+  else
+    python3 -c 'import uuid; print(uuid.uuid4())'
+  fi
+}
+
+[ -n "$ASSET_ID" ] || ASSET_ID="cloud-$(_uuid)"
+# remote/identity.py:_is_identifier rejects whitespace, non-printable
+# characters, and anything over 255 characters. A value this accepts but the
+# runtime rejects is worse than no file: every session reads it, rejects it,
+# and mints a fresh asset — the per-session proliferation this exists to stop.
+case "$ASSET_ID" in
+  *[[:space:]]*|"") echo "✗ asset id must be non-empty with no whitespace" >&2; exit 2 ;;
+esac
+if [ "${#ASSET_ID}" -gt 255 ]; then
+  echo "✗ asset id must be 255 characters or fewer" >&2
+  exit 2
+fi
+if ! python3 -c 'import sys; sys.exit(0 if sys.argv[1].isprintable() else 1)' "$ASSET_ID"; then
+  echo "✗ asset id must contain no non-printable characters" >&2
+  exit 2
+fi
+# ---- the per-session boot hook -------------------------------------------
+# Failing hard here: if the hook cannot be written, every session's SessionStart
+# command points at a file that does not exist and the daemon never starts —
+# a silent total failure worse than a setup that stops and says so.
+BOOT="${ROOT}/usr/local/bin/stacktrace-boot.sh"
+mkdir -p "$(dirname "$BOOT")" || { echo "✗ cannot create $(dirname "$BOOT")" >&2; exit 1; }
+cat > "$BOOT" <<'BOOTSCRIPT' || { echo "✗ cannot write $BOOT" >&2; exit 1; }
+#!/usr/bin/env bash
+# Configure the remote and start the daemon for this cloud session. No-op
+# anywhere else. The asset id is already on disk from setup, so this does not
+# touch it: it only configures the token and starts the daemon, which resolves
+# the persisted asset id and mints the telemetry id on its first event.
+#
+# `daemon run` is started detached, not through a supervisor: a cloud VM runs
+# one session, so the daemon's lifetime is the VM's (ADR-0070). Where a host
+# runs several sessions, ADR-0066's `daemon start` replaces this one line.
+set -u
+[ "${CLAUDE_CODE_REMOTE:-}" = "true" ] || exit 0
+command -v stacktrace >/dev/null 2>&1 || exit 0
+[ -n "${STACKTRACE_REMOTE_TOKEN:-}" ] || exit 0
+
+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
+
+# 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.
+if ! stacktrace daemon status 2>/dev/null | grep -q '^running: yes'; then
+  setsid nohup stacktrace daemon run </dev/null >>"$STATE/daemon.log" 2>&1 &
+fi
+exit 0
+BOOTSCRIPT
+chmod 755 "$BOOT" || { echo "✗ cannot chmod $BOOT" >&2; exit 1; }
+echo "✓ $BOOT"
+
+# ---- seed every home -----------------------------------------------------
+# Every existing home is seeded because the future session user is unknown, so a
+# home that exists but cannot be seeded is a failure, not a skip: the session
+# might run as exactly that user and find no daemon. `failed` records any such
+# home and fails the whole run at the end, covering the mixed-success case where
+# one home seeds and another does not. A candidate that is not a directory (the
+# `/home/*` glob with no match, a stray file) is a genuine skip, not a home.
+seeded=0
+failed=0
+for home in "${ROOT}"/root "${ROOT}"/home/*; do
+  [ -d "$home" ] || continue
+
+  cfg="$home/.config/stacktrace"
+  if ! install -d -m 700 "$cfg" 2>/dev/null; then
+    echo "✗ cannot create $cfg — not seeding $home" >&2; failed=1; continue
+  fi
+
+  if ! printf '%s\n' "$ASSET_ID" > "$cfg/asset-id" 2>/dev/null; then
+    echo "✗ cannot write $cfg/asset-id — not seeding $home" >&2; failed=1; continue
+  fi
+  chmod 600 "$cfg/asset-id" 2>/dev/null || true
+
+  # Register the SessionStart hook, merging so any existing settings survive.
+  # The hook is the point of seeding a home — a home whose registration fails
+  # (an unwritable path, or a settings.json that is valid JSON of an unexpected
+  # shape) is a failure, not a skip, or setup would exit 0 having left that
+  # session with no daemon.
+  if ! python3 - "$home" <<'PY'
+import json, pathlib, sys
+home = pathlib.Path(sys.argv[1])
+p = home / ".claude" / "settings.json"
+command = "/usr/local/bin/stacktrace-boot.sh"
+try:
+    p.parent.mkdir(parents=True, exist_ok=True)
+    if p.exists():
+        # Present but unreadable or not valid JSON: do not clobber a real file.
+        s = json.loads(p.read_text())
+    else:
+        s = {}
+except Exception:
+    sys.exit(1)
+# A settings.json Claude Code accepts is a JSON object with object-shaped
+# `hooks` and a list-shaped `SessionStart`; anything else is a shape this must
+# not silently rewrite, so it fails the home rather than guessing.
+if not isinstance(s, dict):
+    sys.exit(1)
+hooks = s.setdefault("hooks", {})
+if not isinstance(hooks, dict):
+    sys.exit(1)
+starts = hooks.setdefault("SessionStart", [])
+if not isinstance(starts, list):
+    sys.exit(1)
+# Dedup only against an entry that actually fires on the events we need. An
+# existing entry carrying this command under a narrower matcher (say `compact`)
+# does not start the daemon at session start, so it must not suppress the
+# `startup|resume` registration. A matcher covers us when it names both events,
+# or when it is absent/empty — Claude Code treats that as matching every event.
+required = {"startup", "resume"}
+
+
+def covers(entry):
+    matcher = entry.get("matcher")
+    if matcher is None or matcher == "":
+        return True
+    return required.issubset({t.strip() for t in str(matcher).split("|")})
+
+
+already = any(
+    isinstance(e, dict)
+    and covers(e)
+    and any(isinstance(h, dict) and h.get("command") == command for h in e.get("hooks", []))
+    for e in starts
+)
+if not already:
+    starts.append({"matcher": "startup|resume",
+                   "hooks": [{"type": "command", "command": command}]})
+try:
+    p.write_text(json.dumps(s, indent=2) + "\n")
+except Exception:
+    sys.exit(1)
+PY
+  then
+    echo "✗ could not register the hook in $home — not seeding it" >&2
+    failed=1
+    continue
+  fi
+
+  # Root created these directories, so they are root-owned; give them to the
+  # home's owner or the session user cannot write its own config. The parent
+  # `.config` that `install -d` created is chowned as well as the leaf, since a
+  # root-owned .config blocks the user from creating any other config beneath it.
+  for d in "$home/.config" "$cfg" "$home/.claude"; do
+    [ -e "$d" ] && chown --reference="$home" "$d" 2>/dev/null || true
+  done
+  chown --reference="$home" "$cfg/asset-id" \
+    "$home/.claude/settings.json" 2>/dev/null || true
+
+  echo "✓ seeded $home"
+  seeded=$((seeded + 1))
+done
+
+if [ "$seeded" -eq 0 ]; then
+  echo "✗ no home directory was writable — every session will mint its own identity" >&2
+  exit 1
+fi
+
+if [ "$failed" -ne 0 ]; then
+  echo "✗ one or more home directories could not be seeded — a session running as" \
+       "that user would have no daemon, so failing the whole setup rather than" \
+       "accepting a snapshot that works for some users and not others" >&2
+  exit 1
+fi
+
+command -v stacktrace >/dev/null 2>&1 || echo "! stacktrace is not on PATH yet; the boot hook waits for it" >&2
+
+echo "✓ asset id:     $ASSET_ID"
+echo "✓ homes seeded: $seeded"
+exit 0

stacktrace_cli/daemon/activity_log.py

@@ -50,9 +50,9 @@ class _PrivateRotatingFileHandler(RotatingFileHandler):
 
     def doRollover(self) -> None:
         super().doRollover()
-        # `ensure_daemon` pointed this process's stdout and stderr at the file
-        # just renamed away. Follow it, or a crash traceback lands in the
-        # backup and is deleted with it at the next rollover.
+        # The detached launcher points this process's stdout and stderr at
+        # the file just renamed away. Follow it, or a crash traceback lands in
+        # the backup and is deleted with it at the next rollover.
         if self._own_std_streams and self.stream is not None:
             sys.stdout.flush()
             sys.stderr.flush()

stacktrace_cli/daemon/cli.py

@@ -6,7 +6,11 @@ import json
 import os
 import sqlite3
 import sys
+import time
+from collections.abc import Callable
 from datetime import UTC, datetime
+from pathlib import Path
+from typing import TypeVar
 
 import click
 
@@ -15,13 +19,61 @@ from .paths import RuntimePaths
 from .presentation import render_finding
 from .store import FindingStore, SessionKey
 
+_T = TypeVar("_T")
+
 
 @click.group()
 def daemon() -> None:
     """Manage automatic session detection."""
 
 
-@daemon.command("run", hidden=True)
+#: Bounds how long `status`/`stop` retry a control request against a daemon
+#: whose lock is held but that has not yet answered. The accept loop starts
+#: before composition startup, but the lock is taken earlier than that
+#: (version lookup, opening the store, binding the socket). A request in
+#: that gap would otherwise see its control timeout expire with nobody yet
+#: reading it. Comfortably larger than the gap so an ordinary start never
+#: surfaces as unresponsive.
+_STARTUP_GRACE_SECONDS = 10.0
+
+#: How long `stop` waits for the singleton lock once shutdown has been
+#: accepted. Its own budget, not shared with `_STARTUP_GRACE_SECONDS`:
+#: retrying during startup must not eat the time the in-progress tick needs.
+#: Accepting shutdown only sets the stop event. The tick — a scan, then
+#: Fleet drain and BOM upload — runs to completion before the loop notices,
+#: and the lock stays held through that work, the telemetry flush, and
+#: `compositions.close()`. Fleet's HTTP client allows 30s per attempt and
+#: three attempts (~95s for one call), and one tick can make several. A 10s
+#: budget expired during an ordinary pass, so `stop` reported failure and
+#: dropped the transition lock while the process was still shutting down;
+#: the next `start` then saw `ALREADY_RUNNING`. 600s covers several retried
+#: cloud calls plus the scan and the shutdown tail, and still gives up when
+#: the process is stuck.
+_STOP_TIMEOUT_SECONDS = 600.0
+
+
+def _retry_while_starting(
+    lock_path: Path, call: Callable[[], _T], errors: tuple[type[Exception], ...]
+) -> _T:
+    """Retry a lifecycle control request while the daemon lock is held.
+
+    Treats an early failure as evidence of the startup gap described above,
+    not as proof the daemon is actually unresponsive -- as long as the lock
+    is still held, that gap closes on its own within a few seconds.
+    """
+    from .lifecycle import daemon_lock_held
+
+    deadline = time.monotonic() + _STARTUP_GRACE_SECONDS
+    while True:
+        try:
+            return call()
+        except errors:
+            if not daemon_lock_held(lock_path) or time.monotonic() >= deadline:
+                raise
+            time.sleep(0.1)
+
+
+@daemon.command("run")
 # No `envvar=` on any of these. Click resolves an environment variable *into*
 # the parameter, so a value that came from the environment would arrive here
 # indistinguishable from one typed on the command line — and `daemon status`
@@ -53,6 +105,12 @@ def daemon() -> None:
     " that fallback: a finding still uploads immediately when the scan commits it."
     " Defaults to STACKTRACE_FLEET_INTERVAL, then 5m.",
 )
+@click.option(
+    "--webhook-interval",
+    default=None,
+    help="How often to retry configured webhook delivery. 0 disables only the fallback;"
+    " new findings still wake delivery. Defaults to STACKTRACE_WEBHOOK_INTERVAL, then 1m.",
+)
 @click.option(
     "--bom-interval",
     default=None,
@@ -64,8 +122,10 @@ def run_command(
     scan_since: str | None,
     agent_kinds: tuple[str, ...],
     fleet_interval: str | None,
+    webhook_interval: str | None,
     bom_interval: str | None,
 ) -> None:
+    """Run the daemon in the foreground for a host supervisor."""
     _, _, run_daemon = _runtime()
     paths = RuntimePaths.from_environment()
     try:
@@ -74,14 +134,21 @@ def run_command(
             scan_since=scan_since,
             agent_kinds=agent_kinds,
             fleet_interval=fleet_interval,
+            webhook_interval=webhook_interval,
             bom_interval=bom_interval,
         )
         _reject_unobservable_kinds(config)
     except ValueError as error:
         raise click.ClickException(str(error)) from error
-    # The real daemon process: its stdout and stderr are the log file
-    # (`ensure_daemon`), so they follow it across a rollover (ADR-0048).
-    run_daemon(paths, config, own_std_streams=True)
+    from .lifecycle import DETACHED_ENV
+
+    status = run_daemon(
+        paths,
+        config,
+        own_std_streams=os.environ.get(DETACHED_ENV) == "1",
+    )
+    if status:
+        raise click.exceptions.Exit(status)
 
 
 def _reject_unobservable_kinds(config: DaemonConfig) -> None:
@@ -112,18 +179,30 @@ def status() -> None:
     grows means retention is not pruning; and a configuration without its source
     makes fleet-wide drift undebuggable (`docs/specs/daemon-scanning.md`).
     """
-    daemon_is_running, _, _ = _runtime()
-    from .runtime import last_error, read_run_state
+    from stacktrace_cli.build import version_label
 
-    paths = RuntimePaths.from_environment()
-    running = daemon_is_running(paths.socket)
-    run_state = read_run_state(paths)
+    from .client import ProtocolError, request_status
+    from .lifecycle import daemon_lock_held
+    from .runtime import last_error
 
-    click.echo(f"running: {'yes' if running else 'no'}")
-    if isinstance(run_state, dict):
-        click.echo(f"pid: {run_state.get('pid')}")
-        click.echo(f"version: {run_state.get('version')}")
-        click.echo(f"started: {run_state.get('started_at')}")
+    paths = RuntimePaths.from_environment()
+    live = None
+    try:
+        live = _retry_while_starting(
+            paths.lock,
+            lambda: request_status(paths.socket),
+            (ConnectionError, OSError, ProtocolError),
+        )
+    except (ConnectionError, OSError, ProtocolError):
+        pass
+    if live is None and daemon_lock_held(paths.lock):
+        click.echo("running: unresponsive")
+    else:
+        click.echo(f"running: {'yes' if live is not None else 'no'}")
+    if live is not None:
+        click.echo(f"version: {live.build}")
+        click.echo(f"installed: {version_label()}")
+        click.echo(f"started: {live.started_at}")
 
     try:
         # One `_store()` call apiece, all against the same file: if the first
@@ -145,9 +224,9 @@ def status() -> None:
     click.echo(f"last error: {last_error(paths.log) or 'none reported'}")
 
     try:
-        config = _effective_config(run_state)
+        config = _effective_config(live.config if live is not None else None)
     except ValueError as exc:
-        # No readable run-state means `resolve()`'s own environment fallback
+        # No live status means `resolve()`'s own environment fallback
         # ran, and its validation is exactly what could be *why* the daemon
         # never started -- the one diagnostic surface for that case must not
         # itself crash on it. `from_document` above already never raises for
@@ -159,7 +238,7 @@ def status() -> None:
             click.echo(f"  {name}: {entry['value']} ({entry['source']})")
 
 
-def _effective_config(run_state: dict[str, object] | None) -> DaemonConfig:
+def _effective_config(document: dict[str, object] | None) -> DaemonConfig:
     """What the daemon resolved, when it is there to say so.
 
     Falling back to this process's own environment is a worse answer and is
@@ -167,8 +246,8 @@ def _effective_config(run_state: dict[str, object] | None) -> DaemonConfig:
     printing nothing, because the common case for an operator running `status`
     is a daemon that is not running at all.
     """
-    if isinstance(run_state, dict) and isinstance(run_state.get("config"), dict):
-        return DaemonConfig.from_document(run_state["config"])  # type: ignore[arg-type]
+    if document is not None:
+        return DaemonConfig.from_document(document)
     return DaemonConfig.resolve()
 
 
@@ -238,6 +317,58 @@ def _database_line(paths: RuntimePaths) -> str:
     return f"{store.database_size()} bytes ({paths.state})"
 
 
+@daemon.command()
+def start() -> None:
+    """Start one detached daemon when no host service manager is available."""
+    _runtime()
+    from .lifecycle import StartOutcome, start_daemon, transition_lock
+
+    paths = RuntimePaths.from_environment()
+    try:
+        with transition_lock(paths.transition_lock):
+            outcome = start_daemon(paths)
+    except (OSError, RuntimeError) as error:
+        raise click.ClickException(f"could not start daemon: {error}") from error
+    if outcome is StartOutcome.ALREADY_RUNNING:
+        click.echo("Stacktrace daemon is already running.")
+    else:
+        click.echo("Stacktrace daemon started.")
+
+
+@daemon.command()
+def stop() -> None:
+    """Ask the running daemon to shut down cleanly."""
+    from .client import ProtocolError, request_shutdown
+    from .lifecycle import daemon_lock_held, transition_lock
+
+    paths = RuntimePaths.from_environment()
+    with transition_lock(paths.transition_lock):
+        if not daemon_lock_held(paths.lock):
+            click.echo("Stacktrace daemon is not running.")
+            return
+        try:
+            _retry_while_starting(
+                paths.lock,
+                lambda: request_shutdown(paths.socket),
+                (ConnectionError, OSError, ProtocolError),
+            )
+        except (ConnectionError, OSError, ProtocolError) as error:
+            if not daemon_lock_held(paths.lock):
+                click.echo("Stacktrace daemon stopped.")
+                return
+            raise click.ClickException(
+                "daemon is running but unresponsive; restart it through its host "
+                "supervisor or use OS process tools"
+            ) from error
+        deadline = time.monotonic() + _STOP_TIMEOUT_SECONDS
+        while time.monotonic() < deadline:
+            if not daemon_lock_held(paths.lock):
+                click.echo("Stacktrace daemon stopped.")
+                return
+            time.sleep(0.1)
+    raise click.ClickException(f"daemon did not stop; see {paths.log}")
+
+
 @daemon.command()
 @click.option(
     "--agent-kind",