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

stacktrace_cli/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 
 # 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(
@@ -373,6 +374,65 @@ def _correlated(
     )
 
 
+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:
     """The sessions as read, before anything has been correlated or judged.
 
@@ -498,11 +558,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

stacktrace_cli/cli.py

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

stacktrace_cli/cloud/__init__.py

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

stacktrace_cli/cloud/setup.sh

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

stacktrace_cli/daemon/activity_log.py

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