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

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")

stacktrace_cli/daemon/jobs.py

@@ -25,6 +25,7 @@ the interval's, unchanged.
 from __future__ import annotations
 
 import hashlib
+import math
 import socket
 from collections.abc import Callable
 from contextlib import suppress
@@ -66,6 +67,19 @@ class Job:
     #: Whether anything wakes this job. `False` for the BOM job, which nothing
     #: does, so `--bom-interval 0` genuinely disables it.
     wakeable: bool = False
+    #: Whether this job's very first run keeps its staggered `_due_at`'s phase
+    #: for every run after, instead of collapsing onto `now`. Set for a
+    #: one-time startup kick (the BOM job): without it, that first `run_if_due`
+    #: would re-anchor `_due_at` on the moment every host happened to start
+    #: (or, if the initial scan runs long, the moment it finished) rather than
+    #: each host's `stagger()` slot, defeating the fleet-wide spread on every
+    #: run after the first, not just that one. Keyed on "first run ever"
+    #: rather than on whether `_due_at` is still ahead of `now` at execution
+    #: time, since a slow tick can put a low-offset host's `_due_at` in the
+    #: past before this ever runs. Fleet/webhook don't set this — they're
+    #: woken repeatedly by real events for the life of the daemon, where
+    #: collapsing onto `now` is the right call every time, not just the first.
+    preserve_stagger: bool = False
     _due_at: float | None = field(default=None, init=False)
     _woken: bool = field(default=False, init=False)
     _ran_at: float | None = field(default=None, init=False)
@@ -125,8 +139,10 @@ class Job:
         # run is about work that run may not have seen, so it must survive into
         # the next pass rather than being cleared by the one it raced.
         self._woken = False
+        is_first_run = self._ran_at is None
         self._ran_at = now
-        if self.interval > 0:
+        preserve_this_run = self.preserve_stagger and is_first_run and self._due_at is not None
+        if self.interval > 0 and not preserve_this_run:
             self._due_at = now + self.interval
         try:
             self.run()
@@ -138,6 +154,37 @@ class Job:
             # job's, which every other job's own error already survives.
             with suppress(Exception):
                 self.on_error(self.name, error)
+        finally:
+            if preserve_this_run and self.interval > 0:
+                # The job's first run ever -- the BOM startup kick, however
+                # late it actually lands (a slow initial scan can push `now`
+                # well past this job's staggered `_due_at` before the tick
+                # loop ever reaches it, so comparing `_due_at` to `now` here
+                # cannot tell early from late). Keep that slot's phase --
+                # advanced by however many whole intervals the delay ate,
+                # never fewer than one -- rather than starting a fresh,
+                # unstaggered cadence from whenever this run happened.
+                # Measured against the clock *after* `run()` returns, not
+                # before: the run itself (an actual upload) can eat into the
+                # margin a pre-run measurement assumed was safe, and with a
+                # short `--bom-interval` that margin can be smaller than the
+                # run takes.
+                original_due_at = self._due_at
+                assert original_due_at is not None
+                after = self.clock()
+                # `floor(x) + 1`, not `ceil(x)`: when the delay lands on an
+                # exact multiple of the interval, `ceil` leaves this equal to
+                # `after` rather than past it, and `now >= _due_at` reads that
+                # as due again immediately. `floor(x) + 1 > x` always, for
+                # every real `x`, so the result is strictly future-facing
+                # with no boundary case left to special-case. This division
+                # assumes `interval` is `0` or a sane positive duration --
+                # `parse_duration` (`config.py`) refuses anything smaller,
+                # which is where that assumption belongs, not a defensive
+                # catch here for a value that should never reach a `Job` at
+                # all.
+                periods = max(1, math.floor((after - original_due_at) / self.interval) + 1)
+                self._due_at = original_due_at + periods * self.interval
         return True
 
 

stacktrace_cli/daemon/observer.py

@@ -36,6 +36,7 @@ from stacktrace_cli.correlate.orchestrate import (
     advisory_attacher,
 )
 from stacktrace_cli.detector.render import detection_json, unknown_json
+from stacktrace_cli.detector.run import NO_ANALYZER
 from stacktrace_cli.sessions.access import IncrementalSessions, SessionView
 
 from .store import FindingStore, Notification, SessionKey
@@ -502,6 +503,17 @@ class ClaudeSessionObserver:
                 underbuilt_now = True
         else:
             underbuilt_now = False
+        budget_exhausted_now = any(u.get("reason") == "budget_exhausted" for u in result.unknowns)
+        if budget_exhausted_now:
+            underbuilt_now = True
+        # `reasoning_not_requested` deliberately gets no such marker (ADR-0080).
+        # With reasoning off by default (ADR-0081) it is the routine outcome
+        # for a gate-tripping session, not the rare one `_underbuilt` was
+        # sized for -- mirroring `budget_exhausted` here would retry every
+        # such session on every tick, indefinitely, for as long as reasoning
+        # stays off. Enabling reasoning starts coverage from that point
+        # forward; it does not requeue what was already scanned while it was
+        # off.
         notifications = self.store.record(
             collected.session,
             result.findings,
@@ -521,7 +533,8 @@ class ClaudeSessionObserver:
         )
         for notification in notifications:
             self.publish(notification)
-        self._fingerprints[collected.session] = collected.fingerprint
+        if not budget_exhausted_now:
+            self._fingerprints[collected.session] = collected.fingerprint
         self._scanned_generations[collected.session] = collected.composition_generation
         self._scanned_pending[collected.session] = underbuilt_now
         self._session_views[collected.session] = collected.view
@@ -554,12 +567,22 @@ def merge_views(collected: Iterable[Collected]) -> SessionView:
     )
 
 
+#: ADR-0076's daemon-specific reasoning ceiling, "docs/adrs/0076-two-phase-
+#: detection-pipeline.md" § *Async Phase 2*: `DEFAULT_BUDGET` (10) is sized
+#: for a one-shot `detect`/`monitor` invocation, not a long-running scan whose
+#: batches can be larger; leaving it at the generic default meant sessions
+#: past the tenth in a batch got `budget_exhausted` on every tick.
+DEFAULT_DAEMON_BUDGET = 50
+
+
 def analyse_batch(
     view: SessionView,
     collected: tuple[Collected, ...],
     since: datetime,
     *,
     agent_kinds: tuple[str, ...],
+    reasoning: bool = False,
+    analyzer: str = NO_ANALYZER,
     attach_advisories: Any = None,
     build_all: Any = None,
 ) -> dict[SessionKey, ScanResult]:
@@ -575,6 +598,10 @@ def analyse_batch(
     it as `window_start` and analyses the view whole, so a session-wide rule
     (ADR-0016) still sees the whole session and the old per-transcript
     `mtime - 1 minute` cutoff is not needed.
+
+    `reasoning`/`analyzer` default off (ADR-0081): the caller passes the
+    daemon's own resolved `DaemonConfig.reasoning_enabled`, so stage three
+    only runs when the operator opted in, `TYPESAFE_API_KEY` notwithstanding.
     """
     by_qualified_id = {item.qualified_id: item.session for item in collected}
     analysis = analyse_sessions(
@@ -582,7 +609,9 @@ def analyse_batch(
         agent_kinds=agent_kinds,
         since=since,
         session_ids=tuple(by_qualified_id),
-        reasoning=False,
+        reasoning=reasoning,
+        analyzer=analyzer,
+        budget=DEFAULT_DAEMON_BUDGET,
         sample_budget=0,
         attach_advisories=attach_advisories,
         build_all=build_all,

stacktrace_cli/daemon/presentation.py

@@ -24,6 +24,34 @@ _GUIDANCE = {
         "The agent encountered a block while working",
         "Inspect the recorded block reason before retrying the task.",
     ),
+    "stacktrace-destructive-action": (
+        "A recursive delete targeted a path outside the workspace",
+        "Check whether the deletion was intentional and restore from backup if not.",
+    ),
+    "stacktrace-credential-persisted": (
+        "Secret-shaped material was written to a file",
+        "Rotate the credential immediately and remove it from the file.",
+    ),
+    "stacktrace-infra-unsafe-action": (
+        "A mutating infrastructure command ran without explicit user request",
+        "Verify the action was intended and inspect its target environment.",
+    ),
+    "stacktrace-unrequested-publication": (
+        "Code or artifacts were published without explicit user request",
+        "Verify the publication was intended and inspect what was made public.",
+    ),
+    "stacktrace-mcp-transient-failure": (
+        "MCP auth failure followed by recovery on a server",
+        "Investigate whether the recovery involved a credential change or a transient issue.",
+    ),
+    "stacktrace-tool-retry-storm": (
+        "A tool was retried repeatedly with identical parameters",
+        "The agent did not adapt its approach after repeated failures.",
+    ),
+    "stacktrace-vulnerable-dep-invoked": (
+        "A dependency the agent used has a known vulnerability",
+        "Check the advisory and update the package if a fix is available.",
+    ),
 }
 
 

stacktrace_cli/daemon/runtime.py

@@ -15,10 +15,11 @@ 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
+from stacktrace_cli.detector.run import NO_ANALYZER
 from stacktrace_cli.private_state import ensure_private_directory
 from stacktrace_cli.telemetry import emit_error
 from stacktrace_cli.telemetry.posthog import flush as telemetry_flush
@@ -98,13 +99,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 +198,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 +213,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)
@@ -374,18 +384,29 @@ def run_daemon(
             # already parked on (`WebhookWorker._run`), independent of that
             # loop, so the drain this promises actually runs at once.
             server.on_webhook_wake = webhook_worker.wake
-            jobs = Scheduler(
-                (
-                    fleet,
-                    webhook,
-                    Job(
-                        name="bom",
-                        interval=settings.bom_interval_seconds,
-                        run=lambda: _log_bom(sync_bom()[0]),
-                        on_error=_log_job_error,
-                    ),
-                )
+            bom = Job(
+                name="bom",
+                interval=settings.bom_interval_seconds,
+                run=lambda: _log_bom(sync_bom()[0]),
+                on_error=_log_job_error,
+                preserve_stagger=True,
             )
+            # Woken once, unconditionally, right here -- the same reason
+            # `fleet`/`webhook` are above: a freshly started daemon should not
+            # sit on a machine's inventory for up to `--bom-interval` (default
+            # 6h) before its first upload. `preserve_stagger=True` keeps this
+            # from costing the thing `stagger()` exists for: without it,
+            # `run_if_due` would re-anchor `_due_at` on this wake's `now` and
+            # every run after would too, converging every host provisioned
+            # from one script onto the same upload instant forever, not just
+            # this first one. With it, this run lands early but the *next*
+            # due time still comes from the original staggered slot plus the
+            # interval, so the fleet-wide spread survives having its first
+            # upload moved up. `--bom-interval 0` is unaffected: `bom.enabled`
+            # is still `False` (nothing else wakes it, per `Job.wakeable`), so
+            # `Scheduler` below drops it before this wake can do anything.
+            bom.wake()
+            jobs = Scheduler((fleet, webhook, bom))
 
             def wake_delivery_jobs() -> None:
                 fleet.wake()
@@ -399,6 +420,8 @@ def run_daemon(
                     collected,
                     since,
                     agent_kinds=kinds,
+                    reasoning=settings.reasoning_enabled,
+                    analyzer="jev" if settings.reasoning_enabled else NO_ANALYZER,
                     attach_advisories=first.attach_advisories,
                     build_all=compositions,
                 ),
@@ -425,7 +448,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: