stacktrace-cli 0.5.2__tar.gz → 0.6.0__tar.gz

stacktrace_cli-0.6.0/.claude/skills/pr-review-loop/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: pr-review-loop
+description: Autonomous code → commit → push → PR → review monitoring → fix → thumbsup loop. Use when the user wants end-to-end delivery of code changes through Codex review approval.
+---
+
+# pr-review-loop
+
+End-to-end autonomous loop: generate code, commit, push, create or update a PR,
+monitor Codex review, fix findings, and iterate until the PR receives a thumbsup
+or approval with no actionable findings remaining.
+
+**Announce at start:** "I'm using the pr-review-loop skill to deliver this change
+through review."
+
+## When to invoke
+
+User says any of: "ship this", "get this to thumbsup", "run the review loop",
+"deliver through review", or asks for code changes with instructions to
+autonomously handle the PR review cycle.
+
+## Inputs
+
+1. **Branch name** — inferred from the current branch, or ask the user.
+2. **PR number** — if a PR already exists for the branch, use it. Otherwise
+   create a new one.
+3. **Base branch** — defaults to `main`.
+
+## Phase 1: Code generation
+
+1. Implement the requested changes following the repo's conventions (CLAUDE.md):
+   - TDD for business logic (red → green → refactor)
+   - Surgical changes — touch only what you must
+   - Simplicity first — no speculative abstractions
+2. Run all four gates before committing:
+   ```bash
+   uv run ruff check .
+   uv run ruff format --check .
+   uv run pyright
+   uv run pytest -q
+   ```
+3. Fix any failures. If a gate reveals a design decision, go with the
+   recommendation and log the decision.
+
+## Phase 2: Commit, push, PR
+
+1. Stage only the files your changes touch — never `git add -A`.
+2. Commit with a descriptive message explaining WHY, not WHAT.
+3. Push to remote. If rejected, stop and report it as a blocker — fetch and
+   look at what changed, but do not rebase or force-push to resolve it
+   automatically (see "Never force-push, rebase published commits" below).
+4. If no PR exists for this branch, create one with `gh pr create`. Include a
+   summary, list of changes, and a test plan.
+5. If a PR already exists, update its description if the scope changed.
+
+## Phase 3: Monitor review
+
+Poll for review status using a dynamic loop (`/loop`). On each tick:
+
+1. Check CI status:
+   ```bash
+   gh pr checks <PR_NUMBER>
+   ```
+2. Check for new review comments:
+   ```bash
+   gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments --paginate
+   gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews
+   ```
+3. If CI fails, read the logs and fix the issue. Push a new commit.
+4. If Codex or a human reviewer left comments:
+   - Read each comment thread.
+   - For P0/P1/P2 findings: fix them. Push a new commit.
+   - For P3 findings: defer unless the user approved them.
+   - If you disagree with a finding: reply on the PR explaining why,
+     with evidence. Do not silently skip it.
+5. If a reviewer requested changes, address them and re-request review.
+
+### Decisions during review
+
+- **Make autonomous decisions** for: code style fixes, test additions,
+  lint/format fixes, obvious bug fixes, naming improvements.
+- **Log but proceed** for: architecture choices between reasonable alternatives,
+  threshold values, which invariant test to extend.
+- **Stop and ask** for: design-level questions flagged for the user, scope
+  changes that would significantly alter the PR, removing existing tests or
+  changing public interfaces.
+
+### Stopping conditions
+
+- **Success:** CI passes, the latest head has been reviewed, and no actionable
+  P0/P1/P2 findings remain. Report the result.
+- **Cap reached:** After 7 automated fix rounds without a human corrective
+  commit, stop and post a message in the PR (per CLAUDE.md review rules).
+- **Blocked:** A finding requires human judgment (design decision, scope change).
+  Post a summary comment and notify the user.
+
+## Phase 4: Summary
+
+When the loop exits, report:
+1. Total commits pushed.
+2. Review rounds completed.
+3. Decisions made autonomously (with brief justification for each).
+4. Any remaining P3 suggestions that were deferred.
+5. Final PR status (approved / changes requested / commented).
+
+## Conventions
+
+- Never force-push, rebase published commits, or skip hooks.
+- Every fix is a new commit, not an amend.
+- Batch related fixes into one commit when possible.
+- Run all four gates before every push.
+- Count fix rounds per CLAUDE.md: 7 rounds without a human corrective commit
+  triggers the cap.
+
+## What this skill does NOT do
+
+- **Doesn't merge the PR.** That's always a human action.
+- **Doesn't approve its own PR.** It can only push fixes and respond to review.
+- **Doesn't modify CI/CD, branch protection, or permissions.**
+- **Doesn't override human reviewer decisions.** If a human says "don't fix
+  this", it stays unfixed.

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.5.2
+Version: 0.6.0
 Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
 Requires-Dist: click>=8.1
 Requires-Dist: httpx<1.0.dev0,>=0.28.1
 Requires-Dist: openaca==0.7.0
-Requires-Dist: openaidr==0.3.0
+Requires-Dist: openaidr==0.3.2
 Requires-Dist: posthog<8,>=7.0
 Description-Content-Type: text/markdown
 
@@ -51,7 +51,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.5.2 (openaca 0.7.0)
+stacktrace 0.6.0 (openaca 0.7.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/README.md

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.5.2 (openaca 0.7.0)
+stacktrace 0.6.0 (openaca 0.7.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/docs/adrs/0029-stage-three-returns-to-opt-in.md

@@ -1,10 +1,10 @@
 ---
 id: 0029
 title: Stage three returns to opt-in
-status: accepted
+status: superseded
 date: 2026-09-09
 supersedes: null
-superseded-by: null
+superseded-by: 0076
 amends: 0004
 amended-by: null
 ---

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/docs/adrs/0033-a-third-party-analyzer-only-by-a-flag-that-names-it.md

@@ -1,10 +1,10 @@
 ---
 id: 0033
 title: A third-party analyzer is reached only by a flag that names it, and its output is numbers
-status: accepted
+status: superseded
 date: 2026-09-17
 supersedes: null
-superseded-by: null
+superseded-by: 0076
 amends: 0004, 0011
 amended-by: 0034, 0035
 ---

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/docs/adrs/0035-naming-an-analyzer-selects-stored-answers.md

@@ -6,7 +6,7 @@ date: 2026-09-19
 supersedes: null
 superseded-by: null
 amends: 0033
-amended-by: null
+amended-by: 0076
 ---
 
 ## Context

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/docs/adrs/0060-two-upload-postures-not-one-command-with-two-sources.md

@@ -6,7 +6,7 @@ date: 2026-09-23
 supersedes: null
 superseded-by: null
 amends: null
-amended-by: null
+amended-by: 0077
 ---
 
 ## Context

{stacktrace_cli-0.5.2 → stacktrace_cli-0.6.0}/docs/adrs/0065-asset-external-id-resolves-by-a-ladder.md

@@ -6,7 +6,7 @@ date: 2026-09-24
 supersedes: null
 superseded-by: null
 amends: null
-amended-by: null
+amended-by: 0078
 ---
 
 ## Context

stacktrace_cli-0.6.0/docs/adrs/0074-a-window-selects-findings-by-when-they-happened.md

@@ -0,0 +1,115 @@
+---
+id: 0074
+title: A window selects findings by when they happened
+status: accepted
+date: 2026-09-28
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+`--since` reads as a claim about findings, and was a claim about files.
+Collection selects whole transcripts by file mtime, so a session written inside
+the window is collected entire and every rule walks all of its turns. What a
+reader gets is therefore *every finding in every session whose file was touched
+in the range*, which is not what any of the three commands say.
+
+Found on a live monitor. The window was `06:10:11 → 06:15:11`, five minutes,
+and the page showed two findings: a `credential-egress` at `06:14:12`, correctly
+in range, and an `agent-blocked` at `05:56:52` — eighteen minutes before the
+window began. That finding belongs to a 538-turn session started the previous
+night and still being typed into, so its transcript was written a minute before
+the pass and the whole session came with it. `summary.detections` was 2, so this
+was the pipeline's answer and not the page's.
+
+The reverse reading is the same mistake and does not occur: 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 always
+sits in a file the mtime rule already admitted. The rule over-admits and never
+under-admits.
+
+## Decision
+
+A window selects findings by **when they happened**. `analyse` reports a
+finding when its own `occurred_end` reaches into the window, and `detect`,
+`monitor` and `sync detect` all reach it through that one call — `cli.py`
+already states the invariant that the three must not be able to disagree about
+what was found.
+
+Overlap decides, and both ends are tested. `occurred_end` against the start, so
+a rule firing across a run of turns belongs in the window its last citation
+reaches — what a reader asking *what is happening now* means. `occurred_start`
+against the end, so a finding straddling the boundary is not 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 carrying 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.
+
+**`analyse_sessions` is deliberately excluded.** The daemon passes a watermark
+deciding which transcripts to re-read, not a range a person chose, and its
+docstring already says it "stamps it as `window_start` and analyses the view
+whole". Its findings are the record that feeds the store, the webhook and Fleet,
+where narrowing by a window would lose a finding rather than hide it.
+
+## Alternatives considered
+
+- **Filter while rendering the monitor.** Rejected, and this was tried first.
+  It gives the page an admission rule of its own, so `detect --since 5m` prints
+  a finding `monitor --since 5m` hides. ADR-0026 clause 2 and the monitor spec's
+  robustness bar — "a page that can invent, alter or suppress a detection" —
+  both forbid it.
+- **Carry findings forward in the page, or in the snapshot beside it.** Rejected.
+  Retention in the browser makes the answer depend on how long a tab has been
+  open: a reload and an open tab disagree about the same window. Moving the
+  carry-forward into the watcher relocates the same violation from the renderer
+  to the server, since a snapshot would then carry findings the current pass did
+  not produce. Both were attempted on the branch that became this ADR and both
+  are reverted.
+- **Admit sessions by their events rather than their mtime, at collection.**
+  Rejected as unnecessary rather than wrong. It would reach the same result by
+  reading more files, and the asymmetry above means there is nothing to gain:
+  no finding inside the window lives in a file the mtime rule excluded.
+- **Exempt `sync detect`, so only the two read-only views scope.** Rejected. It
+  is a view of a range someone asked for, and `cli.py`'s invariant does not
+  allow two of the three to mean one thing and the third another. What must not
+  be scoped is the daemon's record, and that is a different entry point.
+
+## Consequences
+
+`--since` means one thing in all three commands, and the page's window agrees
+with its own heading.
+
+The cost is that **`sync detect` uploads become window-scoped**, which is a
+change to something that leaves the machine. A finding older than the window is
+no longer uploaded by that command even when its session was touched inside the
+range. This is the intended reading of `--since 7d` — findings from the last
+seven days — but it is a narrowing, and an operator who wants everything must
+say so with a wider window. The daemon's own upload path is unaffected and
+remains the durable record.
+
+One test moved with the semantics rather than around them:
+`test_an_anonymous_session_does_not_take_a_known_agents_findings_with_it` builds
+its session at the shared fixture moment, about a month before any realistic
+window, and now declares a window wide enough to reach it. Its subject is
+routing, not recency.
+
+## When to revisit
+
+- **If a finding's clock ever becomes unreliable** — a reader that cannot date
+  its turns, an imported or replayed transcript whose mtime is rewritten — the
+  asymmetry this rests on ("mtime is never earlier than `occurred_end`") stops
+  holding, and admission would need to read events rather than trust the file.
+- **If `sync detect` grows a separate "upload everything" mode**, the
+  window-scoping decided here stops being the whole story for that command and
+  the split should be recorded rather than inferred from a flag.

stacktrace_cli-0.6.0/docs/adrs/0076-two-phase-detection-pipeline.md

@@ -0,0 +1,164 @@
+---
+id: 0076
+title: Collapse detector to two phases with conditional reasoning
+status: accepted
+date: 2026-09-27
+supersedes: 0029, 0033
+superseded-by: null
+amends: 0035
+amended-by: 0081
+---
+
+## Context
+
+The detector has three stages: deterministic (2 rules), priors (0 rules — all
+five withdrawn), and reasoning (cache-only — daemon hardcodes
+`reasoning=False`). Stage 2 contains no detection logic, only routing and two
+data-quality metrics. The daemon never activates new reasoning. Adding new
+rules (10 total) requires cleaning up this structure.
+
+Three problems force the change now:
+
+1. **Stage 2 is empty.** `run_priors` has no rules. What remains is
+   `low_coverage` (a data-quality metric), `_missing_mcp_transport` (same),
+   and routing logic that builds `ReasoningRequest`s. None of that is
+   detection.
+
+2. **The daemon never reasons.** `analyse_batch()` hardcodes
+   `reasoning=False`. New reasoning rules (`stacktrace-infra-unsafe-action`,
+   `stacktrace-unrequested-publication`) will never fire in the background.
+
+3. **Reasoning blocks the tick.** A 1–3s Jev call per session, run
+   synchronously in a 5s tick, blocks the daemon.
+
+## Decision
+
+Collapse to two phases and one orchestrator. Phase 1 is deterministic (no
+model, no vendor boundary — predominantly μs, with the exception of
+`stacktrace-vulnerable-dep-invoked` which queries cached advisory data and degrades
+to async enrichment on a cold cache). Phase 2 is reasoning (seconds,
+requires `TYPESAFE_API_KEY`). The orchestrator sits between them and
+builds the reasoning queue from gate trips, solo routes, and the
+EVERY_SESSION route.
+
+### Phase collapse
+
+Stage 2's remnants move:
+
+| Function | Destination |
+|---|---|
+| `low_coverage` | Session-level metric (not a rule) |
+| `_missing_mcp_transport` | Per-rule coverage metadata on the analysis result |
+| Routing (`_solo_routes`, `ReasoningRequest`) | Orchestrator inside `run_detector` |
+
+### Conditional reasoning activation
+
+`TYPESAFE_API_KEY` in the environment is the only switch. No `--reasoning`
+flag, no `--analyzer jev`. If the key is absent, `reasoning=False` — no
+model, no cost, no vendor boundary. If present, Phase 2 runs only when
+Phase 1 produces a non-empty reasoning queue.
+
+Budget: `DEFAULT_DAEMON_BUDGET = 50`. It caps *sessions* dispatched to
+Phase 2 per tick, not Jev calls — `stacktrace-deceptive-completion` alone
+issues one gate call plus one call per verification call with a covering
+claim, so a session's actual cost scales with its checks. At $0.0006/session
+(one gate call) and typical <20 sessions/tick, normal operation is nowhere
+near the cap; $0.03/tick is that single-call estimate at the budget ceiling,
+not a hard spend cap — a tick of sessions with many verification calls can
+exceed it.
+
+### Async Phase 2
+
+Phase 1 runs synchronously in the tick. Phase 2 dispatches to
+`ThreadPoolExecutor(_WORKERS=4)` and returns immediately. The next tick
+does not wait. When a verdict arrives, findings are recorded and
+`on_commit` wakes the fleet/webhook jobs.
+
+```
+tick()
+├─ Synchronous (μs–ms)
+│  ├─ enumerate + collect + correlate
+│  ├─ Phase 1: deterministic → findings recorded immediately
+│  ├─ orchestrator → reasoning queue
+│  └─ record(findings, unknowns, pending=queue)
+│
+├─ Asynchronous (ThreadPoolExecutor, background)
+│  └─ for each ReasoningRequest:
+│      build windows → Jev call → evaluate → store.record_reasoning()
+│
+└─ Scheduler.tick()
+```
+
+### Rule placement
+
+| Rule | Phase | Rationale |
+|---|---|---|
+| `stacktrace-credential-egress` | 1 | Regex on call arguments |
+| `stacktrace-agent-blocked` | 1 | Refused-call channel match |
+| `stacktrace-destructive-action` | 1 | Path resolution on delete commands |
+| `stacktrace-credential-persisted` | 1 | Secret match on a Write/Edit call's own content |
+| `stacktrace-mcp-transient-failure` | 1 | MCP call sequence pattern |
+| `stacktrace-tool-retry-storm` | 1 | Counter with reset |
+| `stacktrace-vulnerable-dep-invoked` | 1 | Package list × osv.dev |
+| `stacktrace-deceptive-completion` | 2 | Gate (Jev) + per-call nouls. EVERY_SESSION route. |
+| `stacktrace-infra-unsafe-action` | 1 gate → 2 | Gate: mutating command. Model: beyond_request + shared_target. |
+| `stacktrace-unrequested-publication` | 1 gate → 2 | Gate: publication verb. Model: beyond_request. |
+
+## Alternatives considered
+
+- **Keep three stages, add rules to stage 2.** Rejected because stage 2 has
+  no rules and its abstraction boundary is accidental — it exists because the
+  function signature existed, not because the domain has three kinds of work.
+
+- **Separate `--reasoning` and `--analyzer` flags.** Rejected because the
+  consent decision is setting `TYPESAFE_API_KEY` — the operator named a
+  vendor by placing its key. Two flags that must be typed together, where one
+  is meaningless without the other, is ceremony that protects nothing.
+
+- **Synchronous reasoning in the tick with a short budget.** Rejected because
+  even a budget of 3 blocks the tick for 3–9 seconds. The daemon goes deaf,
+  and the tick interval (5s) is shorter than a single Jev call.
+
+## Consequences
+
+- 7 of 10 rules fire on every tick with no model dependency.
+- Reasoning activates automatically when a key is present and a gate trips.
+- The tick never blocks on inference.
+- `ThreadPoolExecutor(4)` caps Jev API pressure at 4 concurrent calls.
+
+**Costs:**
+
+- Async Phase 2 requires a daemon-owned executor with these invariants:
+  (1) bounded in-flight work — cap queued futures, not just the budget;
+  (2) in-flight deduplication — a session already pending reasoning is not
+  re-queued; (3) revision-aware commits — a reasoning result is committed
+  only if its session fingerprint matches the current analysis, so a stale
+  result from a slow Jev call never overwrites a newer deterministic pass;
+  (4) retry on transient Jev failure, with backoff, capped at 3 attempts;
+  (5) on daemon restart, pending reasoning is re-derived from Phase 1 on
+  the next tick rather than persisted across restarts;
+  (6) on daemon stop or upgrade, cancel queued futures and observe
+  cancellation between per-window requests in active workers — the executor
+  must not outlive the daemon's stop deadline (600s), so shutdown joins only
+  the work already in flight, never the full queue.
+- New rules send data the original consent did not envision (shell commands,
+  user requests). Documentation should describe what each rule sends. This
+  ADR amends the consent model established in ADR-0033; key-as-consent is a
+  product decision that should be documented as such. Cached verdicts from
+  prior runs remain readable when the key is present, independent of whether
+  new reasoning is commissioned — this preserves the `--analyzer jev`
+  read-only behavior. Cached Jev verdicts remain readable without a key:
+  the cache is keyed by analyzer identity and prompt version, not by the
+  presence of a runtime credential, so removing or rotating
+  `TYPESAFE_API_KEY` stops commissioning new work but does not discard
+  already-paid findings.
+
+## When to revisit
+
+- If a second reasoning provider is added (Jev is the only one today), the
+  key-as-consent model needs per-provider consent.
+- If Phase 2 latency exceeds 10s per session, the ThreadPoolExecutor design
+  may need a persistent queue with retry.
+- If cross-rule incident grouping becomes urgent (credentials written,
+  committed, and pushed = three findings for one mistake), the orchestrator
+  needs a post-Phase-2 deduplication pass.