stacktrace-cli 0.5.3__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.3"
+__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

@@ -348,32 +348,6 @@ 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.
 
@@ -482,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.
 
@@ -634,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,
@@ -647,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
@@ -59,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,49p' "$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
@@ -78,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
@@ -146,8 +150,12 @@ 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
@@ -176,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
@@ -248,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,6 +161,7 @@ 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:
@@ -331,12 +357,77 @@ 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:

stacktrace_cli/daemon/config.py

@@ -14,6 +14,7 @@ import os
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from datetime import timedelta
+from decimal import Decimal, InvalidOperation
 
 #: Every setting, as `(attribute, environment variable, default spelling)`.
 #: One table so a flag, its environment variable and its default cannot drift
@@ -25,6 +26,10 @@ SETTINGS: tuple[tuple[str, str, str], ...] = (
     ("fleet_interval", "STACKTRACE_FLEET_INTERVAL", "5m"),
     ("webhook_interval", "STACKTRACE_WEBHOOK_INTERVAL", "1m"),
     ("bom_interval", "STACKTRACE_BOM_INTERVAL", "6h"),
+    # ADR-0081: opt-in only. A detached `start` inherits this the same way it
+    # already inherits TYPESAFE_API_KEY -- by setting the environment
+    # variable before forking, not by re-typing the flag.
+    ("reasoning", "STACKTRACE_REASONING", "false"),
 )
 
 _UNITS: dict[str, int] = {"s": 1, "m": 60, "h": 3600, "d": 86400}
@@ -41,6 +46,20 @@ _UNITS: dict[str, int] = {"s": 1, "m": 60, "h": 3600, "d": 86400}
 #: close to this limit.
 _MAX_DURATION_SECONDS = 1e9
 
+#: A duration this small is never a legitimate cadence — every real scan,
+#: fleet, webhook, or BOM interval this repo suggests is measured in minutes
+#: to hours, and `0` (disabled) is handled separately. Rejecting it here,
+#: rather than only bounding it above, closes a class of review findings a
+#: `Job` deep in the scheduler kept surfacing one instance of at a time: a
+#: value small enough relative to a `monotonic()` reading in the millions of
+#: seconds (a long-running host's uptime) makes `now - anchor` divided by
+#: `interval` overflow to infinity, or round back to `anchor` on the float
+#: grid, either way breaking arithmetic that assumes `interval` is a sane,
+#: representable step. Validating the input at this boundary means that
+#: arithmetic never has to defend itself against a value that should not have
+#: reached it.
+_MIN_POSITIVE_DURATION_SECONDS = 1.0
+
 
 def parse_duration(value: str) -> float:
     """`5s`, `3d`, `6h`, or a bare count of seconds. `0` means disabled.
@@ -64,14 +83,52 @@ def parse_duration(value: str) -> float:
         ) from None
     if not math.isfinite(amount) or amount < 0:
         raise ValueError(f"duration must be a non-negative, finite number: {value!r}")
+    if amount == 0.0:
+        # `float()` underflows a positive-but-tiny literal to exactly `0.0`
+        # well before it would otherwise hit `_MIN_POSITIVE_DURATION_SECONDS`
+        # below (the smallest subnormal float is ~4.9e-324) -- silently
+        # accepting that as `scaled == 0` turns a mistyped positive interval
+        # into "disabled" rather than refusing it. `Decimal` parses the same
+        # literal exactly, with no binary-float rounding, telling a real zero
+        # apart from one that only looks like zero once converted -- except
+        # an exponent extreme enough to underflow `float()` (unlike `float`,
+        # which clamps) can still exceed `Decimal`'s own representable range
+        # and raise `InvalidOperation` rather than return a value to compare;
+        # that is exactly as not-a-literal-zero as any other reading here.
+        try:
+            is_literal_zero = Decimal(digits) == 0
+        except InvalidOperation:
+            is_literal_zero = False
+        if not is_literal_zero:
+            raise ValueError(
+                f"duration is too small ({value!r}); the minimum is "
+                f"{_MIN_POSITIVE_DURATION_SECONDS:.0f} second, or 0 to disable"
+            )
     scaled = amount * unit
     if not math.isfinite(scaled) or scaled > _MAX_DURATION_SECONDS:
         raise ValueError(
             f"duration is too large ({value!r}); the limit is {_MAX_DURATION_SECONDS:.0f} seconds"
         )
+    if 0 < scaled < _MIN_POSITIVE_DURATION_SECONDS:
+        raise ValueError(
+            f"duration is too small ({value!r}); the minimum is "
+            f"{_MIN_POSITIVE_DURATION_SECONDS:.0f} second, or 0 to disable"
+        )
     return scaled
 
 
+def parse_reasoning(value: str) -> bool:
+    """`true` or `false`, case-insensitively. Anything else -- `TRUE`, `1`, a
+    typo like `treu` -- is a mistyped opt-in and must fail loudly rather than
+    silently resolve to off, the same way a mistyped duration fails rather
+    than silently falling back to a default.
+    """
+    normalized = value.strip().lower()
+    if normalized not in ("true", "false"):
+        raise ValueError(f"reasoning must be 'true' or 'false', not {value!r}")
+    return normalized == "true"
+
+
 @dataclass(frozen=True)
 class Setting:
     """One resolved value, the text it was resolved from, and where that came from."""
@@ -90,6 +147,7 @@ class DaemonConfig:
     fleet_interval: Setting
     webhook_interval: Setting
     bom_interval: Setting
+    reasoning: Setting
 
     @property
     def scan_interval_seconds(self) -> float:
@@ -111,6 +169,10 @@ class DaemonConfig:
     def bom_interval_seconds(self) -> float:
         return parse_duration(self.bom_interval.value)
 
+    @property
+    def reasoning_enabled(self) -> bool:
+        return parse_reasoning(self.reasoning.value)
+
     @property
     def kinds(self) -> tuple[str, ...]:
         """The agent kinds to observe, in the order given, without repeats."""
@@ -125,9 +187,14 @@ class DaemonConfig:
 
     @classmethod
     def from_document(cls, document: Mapping[str, object]) -> DaemonConfig:
-        """Read back what a running daemon wrote. Anything unreadable falls back
-        to the default, because a status surface that raises on a malformed file
-        tells the operator less than one that says what the default is."""
+        """Read back what a running daemon wrote. A malformed entry falls back
+        to the default, because a status surface that raises on a corrupt file
+        tells the operator less than one that says what the default is -- but a
+        key missing from the document entirely is a different claim: the
+        incumbent daemon predates this setting and never had anything to
+        report, it did not choose the default. Reporting the default for that
+        case would let `daemon status` claim a value the incumbent, not-yet-
+        restarted process during a rolling upgrade may not be honoring."""
         resolved: dict[str, Setting] = {}
         for name, _variable, default in SETTINGS:
             entry = document.get(name)
@@ -136,7 +203,12 @@ class DaemonConfig:
                 if isinstance(value, str) and isinstance(source, str):
                     resolved[name] = Setting(value, source)
                     continue
-            resolved[name] = Setting(default, "default")
+            if name in document:
+                resolved[name] = Setting(default, "default")
+            else:
+                resolved[name] = Setting(
+                    "unknown", "not reported by the running daemon (restart to report)"
+                )
         return cls(**resolved)
 
     @classmethod
@@ -149,6 +221,7 @@ class DaemonConfig:
         fleet_interval: str | None = None,
         webhook_interval: str | None = None,
         bom_interval: str | None = None,
+        reasoning: bool | None = None,
         environment: Mapping[str, str] | None = None,
     ) -> DaemonConfig:
         """Flag, then environment, then default — and validate here, not later.
@@ -166,13 +239,19 @@ class DaemonConfig:
             "fleet_interval": fleet_interval,
             "webhook_interval": webhook_interval,
             "bom_interval": bom_interval,
+            "reasoning": None if reasoning is None else ("true" if reasoning else "false"),
         }
         resolved: dict[str, Setting] = {}
         for name, variable, default in SETTINGS:
             flag = flags[name]
             if flag is not None:
                 resolved[name] = Setting(flag, "flag")
-            elif environ.get(variable):
+            elif variable in environ:
+                # Presence, not truthiness: `STACKTRACE_REASONING=""` (an
+                # unset-variable interpolation gone wrong, say) is the
+                # operator setting this to an empty string, not leaving it
+                # unset -- it must reach the same validation below as any
+                # other spelling, not quietly take the default.
                 resolved[name] = Setting(environ[variable], f"environment ({variable})")
             else:
                 resolved[name] = Setting(default, "default")
@@ -185,6 +264,7 @@ class DaemonConfig:
             config.fleet_interval_seconds,
             config.webhook_interval_seconds,
             config.bom_interval_seconds,
+            config.reasoning_enabled,
         )
         if not config.kinds:
             raise ValueError("--agent-kind must name at least one agent kind")