stacktrace-cli 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

stacktrace_cli/__init__.py

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

@@ -38,12 +38,19 @@ from .options import analyzer_option, resolve_analyzer
 from .remote.cli import main as remote_cmd
 from .sessions.access import collect_sessions
 from .sessions.render import render_json, render_text
-from .telemetry import emit_error
+from .telemetry import command_of, emit, emit_error
 from .telemetry.cli import telemetry as telemetry_cmd
+from .telemetry.events import remember_internal
 from .webhook.cli import webhook as webhook_cmd
 
 PASSTHROUGH: Final = ("scan", "bom", "policy")
 
+#: Commands whose runs are never counted as `command_run` (ADR-0090).
+#: `telemetry` is where the answer is given and read back: reading the
+#: preference or turning it off must not send an event or create an identity,
+#: and `telemetry on` already says what it did with `installed`.
+UNCOUNTED: Final = frozenset({"telemetry"})
+
 HOMEPAGE = "https://stacktrace.ai"
 
 #: The unit is required here and optional in `analysis.parse_since`. That is
@@ -129,13 +136,24 @@ class SectionedGroup(click.Group):
     """
 
     def invoke(self, ctx: click.Context) -> object:
-        """Run the command; count an exception on the way out, and only an exception.
-
-        Click's own control flow travels as exceptions too -- `Exit` from a
-        pass-through's exit code, `Abort` on Ctrl-C, `UsageError` on a typo --
-        and a bare one is not an error in this program. Everything else is,
-        and only an allowlisted class name or `other` leaves (ADR-0039). A
-        command that succeeds performs no telemetry work at all.
+        """Run the command; count a completed run, or an exception, on the way out.
+
+        A command that completes -- returns, or ends with `sys.exit(0)` the way
+        an OpenACA pass-through does -- hands off exactly one `command_run`
+        naming it from `telemetry.events.COMMANDS`, and nothing else
+        (ADR-0090). That hand-off is `emit`: no network I/O on this path, and
+        a failure of any kind is swallowed there. `UNCOUNTED` commands hand
+        off nothing.
+
+        Click's own control flow travels as exceptions too -- `Exit` from help
+        or a pass-through's exit code, `Abort` on Ctrl-C, `UsageError` on a
+        typo -- and a bare one is neither a completed run nor an error in this
+        program, so it sends nothing and creates no identity. That includes
+        `Exit(0)`: it is how `--help` ends, so a command that means "done"
+        returns rather than calling `ctx.exit()`. `--version` and the group's
+        own help end before this method runs. Everything else is an error,
+        and only an allowlisted class name or `other` leaves (ADR-0039); a
+        failed command is counted as its `error`, not as a run.
 
         A `ClickException` or an `Exit` a command site raised to wrap a real
         failure (`raise click.ClickException(...) from exc`, or
@@ -158,21 +176,35 @@ class SectionedGroup(click.Group):
         invalid arguments from the `error` metric. This package's own
         operational wrappers always raise a bare `click.ClickException`, never
         `UsageError`, to carry a real cause.
+
+        `UNCOUNTED` is checked on every path that would otherwise call
+        `emit_error`, not only `_count_run`'s: `telemetry off` wraps a failed
+        preference write in a caused `ClickException` the same way any other
+        operational wrapper does, and ADR-0090 requires that using `telemetry`
+        itself never creates an identity or sends an event, whether it
+        completes or fails (Codex review, PR #153).
         """
         try:
-            return super().invoke(ctx)
+            result = super().invoke(ctx)
+        except SystemExit as exit_:
+            if exit_.code in (None, 0):
+                _count_run(ctx)
+            raise
         except click.exceptions.Abort:
             raise
         except click.UsageError:
             raise
         except (click.exceptions.Exit, click.ClickException) as error:
             cause = error.__cause__
-            if cause is not None:
-                emit_error(cause)
+            if cause is not None and ctx.invoked_subcommand not in UNCOUNTED:
+                emit_error(cause, "cli")
             raise
         except Exception as error:
-            emit_error(error)
+            if ctx.invoked_subcommand not in UNCOUNTED:
+                emit_error(error, "cli")
             raise
+        _count_run(ctx)
+        return result
 
     def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
         commands: list[tuple[str, click.Command]] = []
@@ -201,6 +233,12 @@ class SectionedGroup(click.Group):
                 formatter.write_dl(rows)
 
 
+def _count_run(ctx: click.Context) -> None:
+    name = ctx.invoked_subcommand
+    if name not in UNCOUNTED:
+        emit("command_run", command=command_of(name))
+
+
 @click.group(cls=SectionedGroup)
 @click.option(
     "--version",
@@ -212,6 +250,9 @@ class SectionedGroup(click.Group):
 )
 def main() -> None:
     """Stacktrace: agent composition analysis, detection and upload."""
+    # Before any command, so `STACKTRACE_INTERNAL` set in a shell reaches the
+    # daemon that command may start, which never reads a shell (ADR-0091).
+    remember_internal()
 
 
 @click.command()
@@ -365,9 +406,10 @@ def detect(
 ) -> None:
     """Find security and reliability findings in what agents did.
 
-    Three kinds of finding, under two families: a credential reaching an
-    outbound call and success reported against evidence of failure are
-    security; why the agent stopped, and who can unblock it, is reliability.
+    Four kinds of finding, under two families: a credential reaching an
+    outbound call, success reported against evidence of failure, and an
+    infrastructure change beyond what the user asked for are security; why
+    the agent stopped, and who can unblock it, is reliability.
     The two families carry their own severity ladders, because a blocked agent
     and a leaked credential cannot share one (ADR-0010).
 
@@ -378,7 +420,9 @@ def detect(
     "On a default run" is the whole of the qualification, and it is here rather
     than left to the flags: `--reasoning --analyzer jev` adds a third stage
     that sends per-call windows -- a completion claim, one verification command
-    and its output -- to TypeSafe's Jev (ADR-0033). Both flags must be typed,
+    and its output; and, for a mutating infrastructure command, that command
+    with the user's own requests in the session -- to TypeSafe's Jev
+    (ADR-0033). Both flags must be typed,
     neither has a default, and this output names them when a session is left
     unjudged, so it is a run a reader can ask for and therefore one this
     paragraph has to account for.

stacktrace_cli/correlate/observed.py

@@ -1334,18 +1334,6 @@ def observed_across(*calls: ToolCallLike | None) -> tuple[str, ...]:
     return tuple(sorted(names))
 
 
-def evidence_for(call: ToolCallLike, capability: str) -> dict[str, str] | None:
-    """What established this capability on this call, for a rule that cites it.
-
-    A grade alone tells a reader how sure to be; this tells them why, which is
-    what makes the grade checkable rather than an assertion.
-    """
-    for observation in observe(call):
-        if observation.capability == capability:
-            return dict(observation.evidence)
-    return None
-
-
 def command_heads(command: object) -> tuple[str, ...]:
     """Every program a shell command runs, without its arguments.
 
@@ -1361,8 +1349,10 @@ def command_heads(command: object) -> tuple[str, ...]:
 #: The control operators a command line is split on, longest first so `&&` is
 #: never read as one `&`. `&` alone is deliberately absent, as it was from the
 #: expression this replaces: backgrounding is under-split rather than
-#: mis-split, which costs a segment and never invents one.
-_SEPARATORS = ("&&", "||", ";", "|", "\n")
+#: mis-split, which costs a segment and never invents one. `|&` is a pipe that
+#: carries stderr too, and is reported as `|`: read as `|` and then `&`, its
+#: receiver began with `&` and was dropped as punctuation.
+_SEPARATORS = ("&&", "||", "|&", ";", "|", "\n")
 
 #: Characters after which the shell is at the start of a word, so a `#` there
 #: opens a comment. Blanks and the newline are the ordinary case; the operator
@@ -1386,7 +1376,8 @@ def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
 
     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.
+    ``|`` or ``\\n`` that separated it from the one before it (``|&`` is a
+    pipe, and carried as ``|``).
 
     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
@@ -1474,6 +1465,15 @@ def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
             newline = command.find("\n", index)
             index = len(command) if newline == -1 else newline
             continue
+        if command.startswith(">|", index):
+            # The clobbering redirection is one operator: its `|` is not a pipe.
+            # Read as one, `echo safe >| sqlite3 db 'DROP …'` -- which writes a
+            # file named `sqlite3` -- fabricated a piped `sqlite3` (P2, PR #130
+            # review).
+            current.append(">|")
+            index += 2
+            at_word_start = True
+            continue
         separator = next((s for s in _SEPARATORS if command.startswith(s, index)), None)
         if separator is None:
             current.append(char)
@@ -1481,15 +1481,16 @@ def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
             at_word_start = char in _WORD_START_BEFORE_COMMENT
             continue
         segment_text = "".join(current)
+        operator = "|" if separator == "|&" else separator
         if segment_text.strip():
             parts.append((segment_text, preceding_op))
-            preceding_op = separator
+            preceding_op = operator
         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
+                preceding_op = operator
         current = []
         index += len(separator)
         at_word_start = True
@@ -1871,22 +1872,47 @@ def _strip_heredocs(command: str) -> str:
     """Drop heredoc bodies, keeping the lines that introduce them.
 
     A heredoc the shell never sees closed consumes the rest of the input, and
-    so does this: the loop below runs off the end and everything after the
+    so does this: `_heredoc_lines` runs off the end and everything after the
     introducer is dropped. That is bash's own behaviour, not a fallback -- it
     reads to end-of-input looking for a terminator that is not there.
     """
-    kept: list[str] = []
+    return "\n".join(line for line, _bodies in _heredoc_lines(command))
+
+
+def heredoc_bodies(command: str) -> tuple[tuple[str, tuple[str, ...]], ...]:
+    """Each line of `command` that opens heredocs, with their bodies in the
+    order bash reads them.
+
+    What `_strip_heredocs` drops, kept: a body is the text the shell feeds a
+    program's stdin, which is what a caller asking what a program was *given*
+    -- SQL fed to a database client -- needs and `command_segments` never
+    returns. Arithmetic is masked first, as `_readable_commands` masks it, so a
+    `<<` inside `$(( … ))` opens nothing here either.
+    """
+    return tuple(
+        (line, tuple(bodies))
+        for line, bodies in _heredoc_lines(_mask_arithmetic(command))
+        if bodies
+    )
+
+
+def _heredoc_lines(command: str) -> list[tuple[str, list[str]]]:
+    """Each line that is not a heredoc body, with the bodies it opens."""
+    kept: list[tuple[str, list[str]]] = []
     lines = command.splitlines()
     index = 0
     while index < len(lines):
         line = lines[index]
-        kept.append(line)
+        bodies: list[str] = []
+        kept.append((line, bodies))
         index += 1
         # In order, because that is the order bash reads the bodies in: a line
         # opening two heredocs has the first body directly after it and the
         # second after that one's terminator.
         for dash, terminator in _heredoc_introducers(line):
+            start = index
             while index < len(lines) and not _closes_heredoc(lines[index], terminator, dash):
                 index += 1
+            bodies.append("\n".join(lines[start:index]))
             index += 1
-    return "\n".join(kept)
+    return kept

stacktrace_cli/daemon/cli.py

@@ -14,6 +14,7 @@ from typing import TypeVar
 
 import click
 
+from ..telemetry.events import ensure_internal_saved, follow_saved_internal_only
 from .config import DaemonConfig, parse_reasoning
 from .paths import RuntimePaths
 from .presentation import render_finding
@@ -145,6 +146,14 @@ def run_command(
     reasoning: bool,
 ) -> None:
     """Run the daemon in the foreground for a host supervisor."""
+    # This process outlives the shell that launched it, so it follows the
+    # saved mark only, and a later `STACKTRACE_INTERNAL=0` takes effect
+    # without a restart (ADR-0091). Save the launch value first, and say so
+    # in the daemon log if that fails.
+    warning = ensure_internal_saved()
+    if warning is not None:
+        click.echo(f"stacktrace: {warning}", err=True)
+    follow_saved_internal_only()
     _, _, run_daemon = _runtime()
     paths = RuntimePaths.from_environment()
     ctx = click.get_current_context()
@@ -210,14 +219,13 @@ def _reject_unobservable_kinds(config: DaemonConfig) -> None:
 
 
 @daemon.command()
-def status() -> None:
+@click.option("--verbose", is_flag=True, help="Include detailed daemon diagnostics.")
+def status(verbose: bool) -> None:
     """Report whether this endpoint is working, without reading a log.
 
-    Every row answers a question someone asks when a machine looks quiet: a
-    watermark hours old means the scanner has stopped; a queue that grows with
-    a reader attached means the reader is not draining; a database that only
-    grows means retention is not pruning; and a configuration without its source
-    makes fleet-wide drift undebuggable (`docs/specs/daemon-scanning.md`).
+    The default output is a quick health check. Pass ``--verbose`` for the
+    diagnostic details used to investigate a quiet or misconfigured machine
+    (`docs/specs/daemon-scanning.md`).
     """
     from stacktrace_cli.build import version_label
 
@@ -242,7 +250,8 @@ def status() -> None:
     if live is not None:
         click.echo(f"version: {live.build}")
         click.echo(f"installed: {version_label()}")
-        click.echo(f"started: {live.started_at}")
+        if verbose:
+            click.echo(f"started: {live.started_at}")
 
     try:
         # One `_store()` call apiece, all against the same file: if the first
@@ -251,9 +260,10 @@ def status() -> None:
         # them can print a partial line before that first failure.
         click.echo(f"watermark: {_watermark_line(paths)}")
         click.echo(f"queue depth: {_queue_line(paths)}")
-        click.echo(f"cursors: {_cursor_line(paths)}")
         click.echo(f"parked: {_parked_line(paths)}")
-        click.echo(f"database: {_database_line(paths)}")
+        if verbose:
+            click.echo(f"cursors: {_cursor_line(paths)}")
+            click.echo(f"database: {_database_line(paths)}")
     except (sqlite3.DatabaseError, ValueError) as exc:
         # A corrupt file or a schema newer than this build reads raises here
         # (`_check_version`'s own refusal) -- precisely the moment the daemon
@@ -263,6 +273,9 @@ def status() -> None:
         click.echo(f"database: unreadable — {exc}")
     click.echo(f"last error: {last_error(paths.log) or 'none reported'}")
 
+    if not verbose:
+        return
+
     try:
         config = _effective_config(live.config if live is not None else None)
     except ValueError as exc:
@@ -428,6 +441,9 @@ def start(reasoning: bool) -> None:
         os.environ.pop(_JEV_KEY_ENV, None)
         os.environ["STACKTRACE_REASONING"] = "false"
 
+    warning = ensure_internal_saved()
+    if warning is not None:
+        click.echo(f"stacktrace: {warning}", err=True)
     paths = RuntimePaths.from_environment()
     click.echo("Starting Stacktrace daemon...", err=True)
     try:

stacktrace_cli/daemon/fleet.py

@@ -56,7 +56,7 @@ from stacktrace_cli.remote.upload_contract import (
 )
 from stacktrace_cli.telemetry import emit_derived
 
-from .store import FINDING, FindingStore, QueuedRecord
+from .store import FINDING, FindingStore, QueuedRecord, native_session_id
 
 JsonObject = dict[str, Any]
 
@@ -622,7 +622,10 @@ class FleetSubscriber:
                     "severity": str(payload.get("severity")),
                     "sink": "fleet",
                     "agent_kind": kind,
-                    "session_id": str((payload.get("session") or {}).get("session_id", "")),  # type: ignore[union-attr]
+                    "session_id": native_session_id(
+                        kind,
+                        str((payload.get("session") or {}).get("session_id", "")),  # type: ignore[union-attr]
+                    ),
                 },
             )
 

stacktrace_cli/daemon/jobs.py

@@ -184,6 +184,12 @@ class Job:
                 # 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)
+                # That holds for real numbers, not floats: `(due + 200) - due`
+                # can round to `199.99999999999997`, so `floor` comes out one
+                # short and the deadline lands exactly on `after`. It is
+                # never more than one short, so one extra period is enough.
+                if original_due_at + periods * self.interval <= after:
+                    periods += 1
                 self._due_at = original_due_at + periods * self.interval
         return True
 

stacktrace_cli/daemon/runtime.py

@@ -595,8 +595,20 @@ def _log_webhook(report: WebhookReport) -> None:
     logger.info("webhook drain: %s", detail)
 
 
+#: The component each job name reports its errors under (ADR-0091). A name
+#: not here is `daemon`, which still says it was a scheduled job.
+_JOB_COMPONENTS = {
+    "fleet": "fleet",
+    "flush": "fleet",
+    "webhook": "webhook",
+    "bom": "bom",
+    "sync-bom": "bom",
+}
+
+
 def _log_job_error(name: str, error: Exception) -> None:
-    emit_error(error)
+    # `fleet:<kind>` is the Fleet drain for one agent kind.
+    emit_error(error, _JOB_COMPONENTS.get(name.split(":", 1)[0], "daemon"))
     # The class name only, never `str(error)`: an exception's message can
     # carry a local path, transcript-derived text, or a server response body,
     # all of which the activity log's content-free contract forbids.
@@ -647,7 +659,7 @@ def _log_error(session: SessionKey, error: Exception) -> None:
     # Dated by the handler's own formatter, because `daemon status` reports
     # the last one and "there was an error" without "when" cannot distinguish
     # a repeating failure from one that happened once, weeks ago.
-    emit_error(error)
+    emit_error(error, "observer")
     # `%r`, not `%s`: `session_id` is peer-supplied, and an embedded newline
     # under `%s` would let it forge its own fake log line.
     logger.warning(
@@ -684,7 +696,7 @@ def _log_composition_error(work: tuple[Scope, ...], error: Exception) -> None:
     """Every call here is a failure (unlike `_log_drain`/`_log_bom`, which
     also log a quiet success), so the marker is unconditional — a build that
     keeps failing must be visible to `daemon status`'s marker-only read."""
-    emit_error(error)
+    emit_error(error, "composition")
     # Never the path itself: `project` is a local filesystem path, the same
     # kind of content the activity log's contract forbids for an exception's
     # message. "project"/"user" keeps the shape (which scopes failed, and

stacktrace_cli/daemon/store.py

@@ -117,6 +117,18 @@ class Notification:
     body: str
 
 
+def native_session_id(agent_kind: str, qualified: str) -> str:
+    """The stored finding's `session_id` is `f"{agent_kind}:{native_id}"`
+    (`FindingStore._validate_session`). ADR-0067's payload allowlist is agent
+    kind and *native* session ID as separate fields, and telemetry's own
+    `session_id` domain is a bare UUID (`telemetry/events.py`), so the
+    qualifier must come off before either one sees it. Every subscriber that
+    reports a delivery reads it through here: Fleet's did not, and sent the
+    qualified form, which telemetry refused as `telemetry_failed` (ADR-0091)."""
+    prefix = f"{agent_kind}:"
+    return qualified.removeprefix(prefix) if qualified.startswith(prefix) else qualified
+
+
 class FindingStore:
     """Persist findings and at-least-once delivery state per exact session."""
 

stacktrace_cli/daemon/webhook.py

@@ -19,7 +19,7 @@ from stacktrace_cli.detector.secrets import find_secrets
 from stacktrace_cli.telemetry import emit_derived
 from stacktrace_cli.webhook.config import DEFAULT_FORMAT, ConfigError, load_webhook_config
 
-from .store import FindingStore, QueuedRecord
+from .store import FindingStore, QueuedRecord, native_session_id
 
 WEBHOOK_SUBSCRIBER = "webhook"
 
@@ -223,16 +223,6 @@ def _stop_reason(error: Exception) -> str:
     return f"delivery failed: {detail}"
 
 
-def _native_session_id(agent_kind: str, qualified: str) -> str:
-    """The stored finding's `session_id` is `f"{agent_kind}:{native_id}"`
-    (`FindingStore._validate_session`). ADR-0067's payload allowlist is agent
-    kind and *native* session ID as separate fields, and telemetry's own
-    `session_id` domain is a bare UUID (`telemetry/events.py`), so the
-    qualifier must come off before either one sees it."""
-    prefix = f"{agent_kind}:"
-    return qualified.removeprefix(prefix) if qualified.startswith(prefix) else qualified
-
-
 def _payload(agent_kind: str, row: QueuedRecord) -> dict[str, object]:
     document = row.payload
     session = document.get("session")
@@ -253,7 +243,7 @@ def _payload(agent_kind: str, row: QueuedRecord) -> dict[str, object]:
         "confidence": confidence,
         "session": {
             "agent_kind": agent_kind,
-            "session_id": _native_session_id(agent_kind, session_id),
+            "session_id": native_session_id(agent_kind, session_id),
         },
     }
     # Additive (ADR-0073), and deliberately not required: a row stored before
@@ -534,6 +524,6 @@ def _report_delivered(agent_kind: str, row: QueuedRecord) -> None:
             "severity": str(payload.get("severity")),
             "sink": "webhook",
             "agent_kind": agent_kind,
-            "session_id": _native_session_id(agent_kind, str(session_id)),
+            "session_id": native_session_id(agent_kind, str(session_id)),
         },
     )

stacktrace_cli/detector/analyzer.py

@@ -39,7 +39,7 @@ import os
 import shutil
 import subprocess
 from dataclasses import dataclass, field
-from typing import Literal, Protocol, runtime_checkable
+from typing import Protocol, runtime_checkable
 
 from stacktrace_cli.detector.finding import UnknownReason
 
@@ -203,5 +203,3 @@ class ClaudeCodeAnalyzer:
 #: A kind absent here yields `analyzer_unavailable`, never a fallback to another
 #: vendor's CLI.
 ANALYZERS: dict[str, Analyzer] = {"claude-code": ClaudeCodeAnalyzer()}
-
-Stage3Reason = Literal["refusal", "timeout", "malformed_verdict", "analyzer_error"]