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

stacktrace_cli/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.5.2"
+__version__ = "0.6.0"
 
 # 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/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(
@@ -347,30 +348,63 @@ def _acquire(
     )
 
 
-def _correlated(
-    *,
-    agent_kinds: tuple[str, ...],
-    window_start: datetime,
-    bom_paths: tuple[Path, ...],
-    project_map: tuple[str, ...],
-    root: Path | None,
-    session_ids: tuple[str, ...],
-    attach_advisories: Any,
-    build_all: Any = None,
-) -> Acquired:
-    """Everything up to the judging, shared by both entry points."""
-    return _acquire(
-        _collected(
-            agent_kinds=agent_kinds,
-            window_start=window_start,
-            root=root,
-            session_ids=session_ids,
-        ),
-        bom_paths=bom_paths,
-        project_map=project_map,
-        attach_advisories=attach_advisories,
-        build_all=build_all,
+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:
@@ -422,6 +456,7 @@ def analyse_progressively(
     history: DriftHistory | None = None,
     reasoning: bool = False,
     budget: int = DEFAULT_BUDGET,
+    exclude_from_reasoning: frozenset[tuple[str, str]] = frozenset(),
 ) -> Iterator[Analysis]:
     """The same pipeline, delivered in instalments.
 
@@ -498,11 +533,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
@@ -572,12 +609,20 @@ def analyse_progressively(
     if not reasoning or not ordered:
         return
 
-    # One more instalment, one run, one budget. Everything above has already
-    # been published, so the page is complete and readable while this is in
-    # flight — on a large window it is several hundred sequential requests and
-    # holding the first paint behind it is what made the page look hung.
+    excluded_count = 0
+    if exclude_from_reasoning:
+        kept = tuple(
+            s
+            for s in view.sessions
+            if (s.session.session_id, s.session.agent_kind) not in exclude_from_reasoning
+        )
+        excluded_count = len(view.sessions) - len(kept)
+        reasoning_view = replace(view, sessions=kept) if excluded_count else view
+    else:
+        reasoning_view = view
+
     judged = run_detector(
-        view,
+        reasoning_view,
         reasoning=True,
         budget=budget,
         cache=cache,
@@ -585,4 +630,23 @@ def analyse_progressively(
         jev_key=jev_key,
         history=history,
     )
+
+    if excluded_count:
+        extra_detections = tuple(
+            d
+            for d in accumulated.detections
+            if (d.session.session_id, d.session.agent_kind) in exclude_from_reasoning
+        )
+        extra_unknowns = tuple(
+            u
+            for u in accumulated.unknowns
+            if (u.session.session_id, u.session.agent_kind) in exclude_from_reasoning
+        )
+        judged = replace(
+            judged,
+            detections=judged.detections + extra_detections,
+            unknowns=judged.unknowns + extra_unknowns,
+            sessions=judged.sessions + excluded_count,
+        )
+
     yield _stage(judged, tuple(ordered))

stacktrace_cli/cloud/__init__.py

@@ -12,6 +12,16 @@ CLI and runs this:
       uv tool install stacktrace-cli
     stacktrace-cloud-setup
 
+Or, equivalently, one hosted line that wraps exactly those two steps (see
+`stacktrace-site`'s `public/remote-install.sh`). Download before running rather
+than piping directly into `sh`: without `pipefail` (the default in the `sh`
+that a setup-script box runs), a failed `curl` still lets `sh` read an empty
+script and exit 0, so a broken download would otherwise snapshot an
+environment with neither the CLI nor the boot hook and report success:
+
+    curl -fsSL https://stacktrace.ai/remote-install.sh -o /tmp/remote-install.sh \
+      && sh /tmp/remote-install.sh
+
 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

stacktrace_cli/cloud/setup.sh

@@ -10,7 +10,10 @@
 #      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.
+#      instead of minting a fresh asset per session. Beside it,
+#      asset-display-prefix makes the fleet label `cloud (<id>)` rather than
+#      the image's hostname (`vm`), which is the same on every box. Label
+#      only: the key above is what identifies the asset.
 #
 # 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
@@ -39,9 +42,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 +62,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,52p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) echo "✗ unknown argument: $1" >&2; exit 2 ;;
   esac
 done
@@ -73,6 +81,7 @@ _uuid() {
   fi
 }
 
+DISPLAY_PREFIX="cloud"
 [ -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
@@ -108,19 +117,45 @@ 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.
+# --no-reasoning is explicit, not just `run`'s own default (ADR-0081): this
+# hook never provisions TYPESAFE_API_KEY itself, but a cloud VM's ambient
+# environment is not something this script controls or can audit ahead of
+# time, and this surface has nobody present to notice if that changed.
 if ! stacktrace daemon status 2>/dev/null | grep -q '^running: yes'; then
-  setsid nohup stacktrace daemon run </dev/null >>"$STATE/daemon.log" 2>&1 &
+  setsid nohup stacktrace daemon run --no-reasoning </dev/null >>"$STATE/daemon.log" 2>&1 &
 fi
 exit 0
 BOOTSCRIPT
@@ -149,6 +184,11 @@ for home in "${ROOT}"/root "${ROOT}"/home/*; do
   fi
   chmod 600 "$cfg/asset-id" 2>/dev/null || true
 
+  if ! printf '%s\n' "$DISPLAY_PREFIX" > "$cfg/asset-display-prefix" 2>/dev/null; then
+    echo "✗ cannot write $cfg/asset-display-prefix — not seeding $home" >&2; failed=1; continue
+  fi
+  chmod 600 "$cfg/asset-display-prefix" 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
@@ -221,7 +261,7 @@ PY
   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" \
+  chown --reference="$home" "$cfg/asset-id" "$cfg/asset-display-prefix" \
     "$home/.claude/settings.json" 2>/dev/null || true
 
   echo "✓ seeded $home"

stacktrace_cli/correlate/observed.py

@@ -1381,9 +1381,13 @@ _SEPARATORS = ("&&", "||", ";", "|", "\n")
 _WORD_START_BEFORE_COMMENT = frozenset(" \t\n;&|<>()")
 
 
-def _split_on_separators(command: str) -> list[str]:
+def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
     """The commands in a shell line, split only where the shell would split it.
 
+    Returns ``(segment_text, preceding_operator)`` pairs.  The first segment's
+    operator is ``None``; every later segment carries the ``&&``, ``||``, ``;``,
+    ``|`` or ``\\n`` that separated it from the one before it.
+
     A control operator is an operator **only unquoted and unescaped** — that is
     the shell's own grammar, and it is verified against `bash` itself in
     `tests/test_shell_separators_match_the_shell.py` rather than asserted here.
@@ -1420,10 +1424,11 @@ def _split_on_separators(command: str) -> list[str]:
     left in, `shlex` hands the caller a bare newline where the next word should
     be, and `git \\<newline> push` loses its subcommand to it.
     """
-    parts: list[str] = []
+    parts: list[tuple[str, str | None]] = []
     current: list[str] = []
     index = 0
     quote: str | None = None
+    preceding_op: str | None = None
     #: Whether a `#` here would open a comment. True at the start of the string
     #: and after anything that ends a word; false after any character a word is
     #: made of, quotes included -- `echo "a"#b` prints `a#b`.
@@ -1475,11 +1480,20 @@ def _split_on_separators(command: str) -> list[str]:
             index += 1
             at_word_start = char in _WORD_START_BEFORE_COMMENT
             continue
-        parts.append("".join(current))
+        segment_text = "".join(current)
+        if segment_text.strip():
+            parts.append((segment_text, preceding_op))
+            preceding_op = separator
+        else:
+            # Two separators with nothing between them (e.g. "&&\n"):
+            # keep the conditional operator over a plain terminator so
+            # the next real segment inherits the right dependency.
+            if separator in ("&&", "||") or preceding_op is None:
+                preceding_op = separator
         current = []
         index += len(separator)
         at_word_start = True
-    parts.append("".join(current))
+    parts.append(("".join(current), preceding_op))
     return parts
 
 
@@ -1521,7 +1535,7 @@ def _segments_of(text: str, depth: int) -> tuple[tuple[str, tuple[str, ...]], ..
     `command_segments` would run the masks a second time on their own output.
     """
     found: list[tuple[str, tuple[str, ...]]] = []
-    for part in _split_on_separators(text):
+    for part, _op in _split_on_separators(text):
         # Comments are gone: `_split_on_separators` discards one at the word
         # start that opens it, which is the only place the shell begins one.
         # This used to skip a segment *beginning* with `#`, which caught the
@@ -1567,6 +1581,48 @@ def _segments_of(text: str, depth: int) -> tuple[tuple[str, tuple[str, ...]], ..
     return tuple(found)
 
 
+def command_segments_with_ops(
+    command: object, depth: int = 0
+) -> tuple[tuple[str, tuple[str, ...], str | None], ...]:
+    """Like `command_segments`, but each entry also carries the shell operator
+    that preceded it (``None`` for the first segment, then ``&&``, ``||``,
+    ``;``, ``|`` or ``\\n``).
+
+    Only `_resolve_rm_targets` in the deterministic detector needs the operator
+    context — to decide whether an inline ``cd`` reliably changed the directory
+    and whether an ``rm`` segment is unconditionally reachable.  Every other
+    caller uses the plain `command_segments`, which discards the operator.
+    """
+    if not isinstance(command, str) or not command:
+        return ()
+    text = _readable_commands(command, depth)
+    found: list[tuple[str, tuple[str, ...], str | None]] = []
+    for part, preceding_op in _split_on_separators(text):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            tokens = shlex.split(part)
+        except ValueError:
+            continue
+        while tokens and (_ASSIGNMENT.match(tokens[0]) or tokens[0] in _NOT_A_BINARY):
+            if tokens.pop(0) == "time":
+                while tokens and tokens[0] in _TIME_OPTIONS:
+                    tokens.pop(0)
+        if not tokens:
+            continue
+        head = tokens[0].rsplit("/", 1)[-1]
+        if not head or all(char in _OPERATOR_CHARS for char in head):
+            continue
+        arguments = tuple(tokens[1:])
+        found.append((head, arguments, preceding_op))
+        if head in _SHELLS and depth < _MAX_SHELL_DEPTH:
+            body = _shell_command_body(arguments)
+            if body is not None:
+                found.extend(command_segments_with_ops(body, depth + 1))
+    return tuple(found)
+
+
 def redirect_targets(command: object) -> tuple[str, ...]:
     """Files a shell command redirects its output into.
 
@@ -1604,7 +1660,7 @@ def redirect_targets(command: object) -> tuple[str, ...]:
     # body, an arithmetic comparison, a `case` frame or the body of a function
     # nothing called is not a redirection, and each was named as a file before
     # its mask existed.
-    for part in _split_on_separators(_readable_commands(command, 0)):
+    for part, _op in _split_on_separators(_readable_commands(command, 0)):
         part = part.strip()
         if not part:
             continue

stacktrace_cli/daemon/cli.py

@@ -14,7 +14,7 @@ from typing import TypeVar
 
 import click
 
-from .config import DaemonConfig
+from .config import DaemonConfig, parse_reasoning
 from .paths import RuntimePaths
 from .presentation import render_finding
 from .store import FindingStore, SessionKey
@@ -117,6 +117,24 @@ def _retry_while_starting(
     help="How often to upload endpoint composition. 0 disables it."
     " Defaults to STACKTRACE_BOM_INTERVAL, then 6h.",
 )
+@click.option(
+    "--reasoning/--no-reasoning",
+    # Declared `False`, not `None`: `test_the_reasoning_stage_is_off_by_
+    # default_everywhere_it_can_be_asked_for` reads this literal value off
+    # every command in the tree, on the theory that a default legible only
+    # after tracing what `DaemonConfig.resolve` does with `None` is exactly
+    # the kind of default that drifts unnoticed (ADR-0029). Whether the flag
+    # was actually typed is recovered below via `get_parameter_source`, the
+    # same "flag beats environment beats default" ladder every other option
+    # here gets from `resolve` seeing `None` -- Click just won't hand this one
+    # a `None` to pass through.
+    default=False,
+    hidden=True,
+    help="Analyse changed sessions with a reasoning model (stage three). Off"
+    " by default: pass --reasoning to opt in, and set TYPESAFE_API_KEY so"
+    " there is something to answer with. Defaults to STACKTRACE_REASONING,"
+    " then false.",
+)
 def run_command(
     scan_interval: str | None,
     scan_since: str | None,
@@ -124,10 +142,17 @@ def run_command(
     fleet_interval: str | None,
     webhook_interval: str | None,
     bom_interval: str | None,
+    reasoning: bool,
 ) -> None:
     """Run the daemon in the foreground for a host supervisor."""
     _, _, run_daemon = _runtime()
     paths = RuntimePaths.from_environment()
+    ctx = click.get_current_context()
+    reasoning_flag = (
+        reasoning
+        if ctx.get_parameter_source("reasoning") is click.core.ParameterSource.COMMANDLINE
+        else None
+    )
     try:
         config = DaemonConfig.resolve(
             scan_interval=scan_interval,
@@ -136,17 +161,32 @@ def run_command(
             fleet_interval=fleet_interval,
             webhook_interval=webhook_interval,
             bom_interval=bom_interval,
+            reasoning=reasoning_flag,
         )
         _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)
 
@@ -317,13 +357,79 @@ def _database_line(paths: RuntimePaths) -> str:
     return f"{store.database_size()} bytes ({paths.state})"
 
 
+_JEV_KEY_ENV = "TYPESAFE_API_KEY"
+
+
+def _ensure_jev_key() -> None:
+    """Prompt for the jev key when it is not already in the environment.
+
+    Sets the key in ``os.environ`` so the forked daemon inherits it.
+    An empty response or a non-interactive terminal skips — reasoning
+    degrades gracefully when the analyzer reports unavailable.
+    """
+    if os.environ.get(_JEV_KEY_ENV):
+        return
+    if not sys.stdin.isatty():
+        return
+    key = click.prompt(
+        "TYPESAFE_API_KEY for reasoning (Enter to skip)",
+        default="",
+        hide_input=True,
+        show_default=False,
+    )
+    if key:
+        os.environ[_JEV_KEY_ENV] = key
+
+
 @daemon.command()
-def start() -> None:
+@click.option(
+    "--reasoning/--no-reasoning",
+    default=False,
+    hidden=True,
+    help="Analyse changed sessions with a reasoning model (stage three). Off"
+    " by default: pass --reasoning to opt in for this run, and set"
+    " TYPESAFE_API_KEY so there is something to answer with.",
+)
+def start(reasoning: bool) -> None:
     """Start one detached daemon when no host service manager is available."""
     _runtime()
     from .lifecycle import StartOutcome, start_daemon, transition_lock
 
+    # `start_daemon` forks/execs inheriting `os.environ` as it stands right
+    # here -- the same route `_ensure_jev_key` uses to hand the detached
+    # process a key it just prompted for, and now the only route
+    # `--reasoning`/`--no-reasoning` has to reach that process's own
+    # `DaemonConfig.resolve()` too, which reads `STACKTRACE_REASONING`. When
+    # the flag was not actually typed, the same "flag beats environment beats
+    # default" ladder `run_command` gets from `resolve()` applies here too:
+    # an operator who already exported `STACKTRACE_REASONING=true` before
+    # calling `start` (the documented way to opt in a detached daemon,
+    # config.py's own comment on `SETTINGS`) must not have that silently
+    # overwritten by this command's unrelated `False` click default.
+    ctx = click.get_current_context()
+    explicit = ctx.get_parameter_source("reasoning") is click.core.ParameterSource.COMMANDLINE
+    if explicit:
+        enabled = reasoning
+    else:
+        inherited = os.environ.get("STACKTRACE_REASONING")
+        try:
+            enabled = inherited is not None and parse_reasoning(inherited)
+        except ValueError as error:
+            raise click.ClickException(str(error)) from error
+    if enabled:
+        _ensure_jev_key()
+        os.environ["STACKTRACE_REASONING"] = "true"
+    else:
+        # An explicit --no-reasoning, or no opt-in at all: either way, do not
+        # let a key already present in the *caller's* environment (a shell
+        # profile, an exported var) reach the daemon and reason anyway --
+        # that is exactly the implicit activation this opt-in exists to
+        # prevent.
+        os.environ.pop(_JEV_KEY_ENV, None)
+        os.environ["STACKTRACE_REASONING"] = "false"
+
     paths = RuntimePaths.from_environment()
+    click.echo("Starting Stacktrace daemon...", err=True)
     try:
         with transition_lock(paths.transition_lock):
             outcome = start_daemon(paths)
@@ -342,6 +448,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 +523,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 +559,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: