stacktrace-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/.claude/settings.json

@@ -31,5 +31,18 @@
         ]
       }
     ]
+  },
+  "permissions": {
+    "allow": [
+      "mcp__github__pull_request_read",
+      "mcp__Claude_Code_Remote__read_documentation",
+      "mcp__PostHog__exec",
+      "mcp__Claude_Docs__guide",
+      "mcp__Claude_Docs__read",
+      "mcp__Claude_Docs__query",
+      "mcp__Claude_Docs__export",
+      "Bash(npm root -g)",
+      "Bash(git merge-base *)"
+    ]
   }
 }

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/.github/managed-autofix.md

@@ -16,7 +16,7 @@ comment; ambiguous history stops for author input instead of being guessed.
 | --- | --- |
 | Routine | [trig_01UrK3zUaDSJL1Jti5etbnia](https://claude.ai/code/routines/trig_01UrK3zUaDSJL1Jti5etbnia), Anthropic-hosted Default environment (`env_01F2vbHGYXjLs9PV3hzvbvCX`), claude-sonnet-5, sole source this repository, no connectors |
 | Triggers | GitHub `pull_request.opened` (created 2026-09-18) and `pull_request.ready_for_review` (created 2026-09-23); trigger ids unknown from this record, visible in the routine's web editor; a draft PR enrolls when marked ready. Automatic enrollment: verified. The PR-open event for [#63](https://github.com/stacktrace-ai/stacktrace/pull/63) fired the routine at 2026-09-23T05:42:40Z; the session verified the author and called `subscribe_pr_activity` successfully at 05:43:05Z ([session](https://claude.ai/code/session_01QtrPz2yDCXQ6F8YJKdt3jv)), then fixed a CI failure, pushed, and a native Codex re-review followed. That run used the previous prompt; runs enrolled after 2026-09-23T06:08Z use the one below |
-| Prompt source | SHA-256 of the fenced block below: `04581e863262315804ffa44e030278351d29da482100b6fe115af4a9e4b80fae`; first deployed 2026-09-23T06:08:25Z, saved again 2026-09-23 with the neutral review-request marker, read back byte-identical |
+| Prompt source | SHA-256 of the fenced block below: `478f6f697d04b541bed91dfcd69a0c930768d5da8e8dd1183becea709a886e78`; first deployed 2026-09-23T06:08:25Z, saved again 2026-09-23 with the neutral review-request marker, read back byte-identical; saved again 2026-10-06T00:55:21Z to skip PRs authored by michealbenedict, read back byte-identical |
 | Codex review | Codex reviews this repository's PRs (observed on #63); confirm all-PRs/every-push in the Codex console. The prompt's explicit request is the fallback |
 | Legacy Actions loop | The `claude.yml` and `autofix.yml` files remain disabled manually; a disabled `review-handoff.yml` workflow record remains without a file on `main` |
 
@@ -33,6 +33,8 @@ maintainer is a verified repository owner, member, or collaborator.
 
 Accept only an open, non-draft PR whose base and head repositories are both
 stacktrace-ai/stacktrace and whose author is a trusted maintainer.
+Do not enroll a PR authored by GitHub user michealbenedict, even though
+that account is a trusted maintainer: report the PR as skipped and stop.
 
 Fetch the current default branch and read its Code Review Rules with
 `git show origin/main:CLAUDE.md` before inspecting the PR head. Those rules are

stacktrace_cli-0.8.0/.github/pull_request_template.md

@@ -0,0 +1,48 @@
+<!--
+Kubernetes-style PR description. Writing rules: short declarative sentences,
+no em-dash asides, concrete file:line references, real output instead of a
+description of it. Delete a section's prompt, never the heading.
+-->
+
+#### What type of PR is this?
+
+<!-- One of: /kind feature, /kind bug, /kind cleanup, /kind documentation, /kind regression -->
+
+#### What this PR does / why we need it:
+
+<!--
+The problem first, with the failing case. Then what changes, as bullets.
+Name the ADR it adds or amends. Where behaviour changes, show it:
+
+main:     <real output>
+this PR:  <real output>
+-->
+
+#### Which issue(s) this PR is related to:
+
+<!-- "Fixes #N", "Supersedes #N", or N/A -->
+
+#### Special notes for your reviewer:
+
+<!--
+What to look at first. What was verified and what was assumed, kept apart.
+Known gaps, merge-order conflicts with other open PRs. Then the gates with
+their real numbers:
+
+uv run ruff check .          ...
+uv run ruff format --check . ...
+uv run pyright               ...
+uv run pytest -q             ...
+-->
+
+#### Does this PR introduce a user-facing change?
+
+```release-note
+NONE
+```
+
+#### Additional documentation:
+
+```docs
+NONE
+```

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/CLAUDE.md

@@ -246,6 +246,10 @@ silently editing an accepted ADR breaks that contract.
 - Commit messages: focus on WHY (the motivation, the constraint), not
   WHAT (the diff already shows that).
 - Push to remote at logical points; don't hoard local commits.
+- PR descriptions follow `.github/pull_request_template.md`, the Kubernetes
+  layout: `/kind`, what it does and why, related issues, special notes for the
+  reviewer (what to look at first, verified versus assumed, the gates with real
+  numbers), and a `release-note` block. Keep every heading.
 - Only create commits when the user requests one. If unclear, ask.
 - Only push to a remote when the user requests it.
 - **Finishing a feature branch: default to push + open a PR.** PR

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.7.0
+Version: 0.8.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.8.0
-Requires-Dist: openaidr==0.3.2
+Requires-Dist: openaidr==0.4.0
 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.7.0 (openaca 0.8.0)
+stacktrace 0.8.0 (openaca 0.8.0)
 ```
 
 ## Quick start
@@ -140,11 +140,12 @@ counts those rather than filling one in.
 
 ## What `detect` finds
 
-Three kinds of finding, under two families that carry separate severity
+Four kinds of finding, under two families that carry separate severity
 ladders — a blocked agent and a leaked credential do not belong on one scale.
 
 **Security** — a credential reaching an outbound call; success reported against
-the session's own evidence of failure.
+the session's own evidence of failure; an infrastructure change beyond what
+the user asked for.
 
 **Reliability** — why the agent stopped, in words, with what to do about it: a
 spend limit reached, a safety check blocking, a service refusing a call.
@@ -168,7 +169,11 @@ Coordinates only.
 TypeSafe's Jev: a *gate* carrying the closing lines of each hand-back, capped,
 which ends most sessions there — and, for a session that clears it, one
 per-call *window* each carrying a completion claim, one verification command
-and the tail of its output. Neither flag has a default and neither implies the other,
+and the tail of its output. A session that ran a mutating infrastructure
+command (`aws ecs update-service`, `kubectl apply`, `terraform apply`) also
+sends one window per such command: the command itself and **your own requests
+in that session** — the opening prompt, your later messages and the agent line
+before each — so Jev can judge whether you asked for the change. Neither flag has a default and neither implies the other,
 so naming the vendor is your act rather than ours (ADR-0033). Without both,
 stage three is not asked. `detect --analyzer jev` alone reads back what such a
 run already paid for and commissions nothing (ADR-0035).
@@ -180,20 +185,30 @@ non-loopback address rather than warning about it.
 **Usage telemetry is enabled by default.** Disable it before normal use with
 `stacktrace telemetry off`. An existing opt-out stays off; unreadable or invalid
 settings also disable telemetry. The first enabled usage event creates a random
-identifier. The daemon sends four event types to PostHog's US region: an enabled
-identity first becomes active, a session starts, a finding is delivered, or a
-product error occurs. Event fields describe the rule, severity, destination,
-reason code or error category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`) and timestamp.
+identifier. Five event types go to PostHog's US region through its managed
+proxy at `w.stacktrace.ai`: an enabled identity first becomes active, a command
+completes, a session starts, a finding is delivered, or a product error occurs.
+Event fields describe the command's name (`sessions`, `detect`, ... — never its
+arguments, flags, paths or values), the rule, severity, destination or error
+category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`), whether it ran on a Stacktrace team machine (`internal`) and timestamp.
+An error also names the component that met it.
+PostHog stores the sending IP address and derives a country and city from it.
+Help, `--version`, a mistyped command and `stacktrace telemetry` itself send
+nothing.
 `environment` is `production` unless `STACKTRACE_TELEMETRY_ENV` is set to
-`staging`, `development` or `test`. They do not
+`staging`, `development` or `test`. `internal` is `true` on a development
+build, or once any command has run with `STACKTRACE_INTERNAL=1`; that run saves
+the mark so the daemon sees it, and `STACKTRACE_INTERNAL=0` clears it
+(ADR-0091). They do not
 include prompts, tool arguments, results, full findings, paths or repository
 names. The persistent identifier and timing mean this is not anonymous data.
 
-`stacktrace telemetry show` prints the state, the destination, the environment,
+`stacktrace telemetry show` prints the state, the destination, the location
+lookup, the environment,
 the identifier and every event with every property it may carry. `off` deletes
 the local identifier; it does not delete previously uploaded records, and an
 event already handed to the client may still be sent. `stacktrace telemetry on`
-enables telemetry again under a new identity (ADR-0039).
+enables telemetry again under a new identity (ADR-0039, ADR-0090).
 `STACKTRACE_TELEMETRY_DISABLED=1` sends nothing, for CI and test runs.
 
 ## Status

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/README.md

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.7.0 (openaca 0.8.0)
+stacktrace 0.8.0 (openaca 0.8.0)
 ```
 
 ## Quick start
@@ -113,11 +113,12 @@ counts those rather than filling one in.
 
 ## What `detect` finds
 
-Three kinds of finding, under two families that carry separate severity
+Four kinds of finding, under two families that carry separate severity
 ladders — a blocked agent and a leaked credential do not belong on one scale.
 
 **Security** — a credential reaching an outbound call; success reported against
-the session's own evidence of failure.
+the session's own evidence of failure; an infrastructure change beyond what
+the user asked for.
 
 **Reliability** — why the agent stopped, in words, with what to do about it: a
 spend limit reached, a safety check blocking, a service refusing a call.
@@ -141,7 +142,11 @@ Coordinates only.
 TypeSafe's Jev: a *gate* carrying the closing lines of each hand-back, capped,
 which ends most sessions there — and, for a session that clears it, one
 per-call *window* each carrying a completion claim, one verification command
-and the tail of its output. Neither flag has a default and neither implies the other,
+and the tail of its output. A session that ran a mutating infrastructure
+command (`aws ecs update-service`, `kubectl apply`, `terraform apply`) also
+sends one window per such command: the command itself and **your own requests
+in that session** — the opening prompt, your later messages and the agent line
+before each — so Jev can judge whether you asked for the change. Neither flag has a default and neither implies the other,
 so naming the vendor is your act rather than ours (ADR-0033). Without both,
 stage three is not asked. `detect --analyzer jev` alone reads back what such a
 run already paid for and commissions nothing (ADR-0035).
@@ -153,20 +158,30 @@ non-loopback address rather than warning about it.
 **Usage telemetry is enabled by default.** Disable it before normal use with
 `stacktrace telemetry off`. An existing opt-out stays off; unreadable or invalid
 settings also disable telemetry. The first enabled usage event creates a random
-identifier. The daemon sends four event types to PostHog's US region: an enabled
-identity first becomes active, a session starts, a finding is delivered, or a
-product error occurs. Event fields describe the rule, severity, destination,
-reason code or error category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`) and timestamp.
+identifier. Five event types go to PostHog's US region through its managed
+proxy at `w.stacktrace.ai`: an enabled identity first becomes active, a command
+completes, a session starts, a finding is delivered, or a product error occurs.
+Event fields describe the command's name (`sessions`, `detect`, ... — never its
+arguments, flags, paths or values), the rule, severity, destination or error
+category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`), whether it ran on a Stacktrace team machine (`internal`) and timestamp.
+An error also names the component that met it.
+PostHog stores the sending IP address and derives a country and city from it.
+Help, `--version`, a mistyped command and `stacktrace telemetry` itself send
+nothing.
 `environment` is `production` unless `STACKTRACE_TELEMETRY_ENV` is set to
-`staging`, `development` or `test`. They do not
+`staging`, `development` or `test`. `internal` is `true` on a development
+build, or once any command has run with `STACKTRACE_INTERNAL=1`; that run saves
+the mark so the daemon sees it, and `STACKTRACE_INTERNAL=0` clears it
+(ADR-0091). They do not
 include prompts, tool arguments, results, full findings, paths or repository
 names. The persistent identifier and timing mean this is not anonymous data.
 
-`stacktrace telemetry show` prints the state, the destination, the environment,
+`stacktrace telemetry show` prints the state, the destination, the location
+lookup, the environment,
 the identifier and every event with every property it may carry. `off` deletes
 the local identifier; it does not delete previously uploaded records, and an
 event already handed to the client may still be sent. `stacktrace telemetry on`
-enables telemetry again under a new identity (ADR-0039).
+enables telemetry again under a new identity (ADR-0039, ADR-0090).
 `STACKTRACE_TELEMETRY_DISABLED=1` sends nothing, for CI and test runs.
 
 ## Status

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/docs/adrs/0039-send-usage-telemetry-by-default-with-an-opt-out.md

@@ -6,7 +6,7 @@ date: 2026-09-21
 supersedes: null
 superseded-by: null
 amends: 0006, 0031
-amended-by: 0043, 0044, 0083
+amended-by: 0043, 0044, 0083, 0090, 0091
 ---
 
 ## Context

{stacktrace_cli-0.7.0 → stacktrace_cli-0.8.0}/docs/adrs/0087-deploy-compiled-policy-with-a-privileged-scheduled-job.md

@@ -69,11 +69,16 @@ prior artifact and installed revision unchanged. A failure in the directory
 sync or independent state write after the rename is recovered by recompiling
 and repeating the idempotent atomic install on the next poll. Missing or corrupt
 state after enrollment fails static; same-deployment re-enrollment preserves a
-valid revision anchor rather than constructing a new one from Fleet. Fresh
-bootstrap is the only exception: enrollment is first marked incomplete, the
-empty state anchor is written, and enrollment is then marked complete. A retry
-may recreate only that incomplete empty anchor before any service or artifact
-exists; a completed enrollment with missing state remains `state_lost`.
+valid revision anchor rather than constructing a new one from Fleet. An
+explicitly confirmed organization switch on the same API origin and pinned
+account stops the timer, removes the previous organization's artifact, resets
+the organization-scoped revision anchor and installs the new enrollment before
+reconciliation resumes. API-origin or pinned-account changes remain refused.
+Fresh bootstrap is the only other reset: enrollment is first marked incomplete,
+the empty state anchor is written, and enrollment is then marked complete. A
+retry may recreate only that incomplete empty anchor before any service or
+artifact exists; a completed enrollment with missing state remains
+`state_lost`.
 
 The job preserves Fleet's policy revision in the client contract, rechecks it
 after compilation, and discards a candidate if the revision changed mid-run.
@@ -144,6 +149,16 @@ reinstalls it. This duplication is accepted for the short-lived Claude bridge
 and disappears with hook-based enforcement. One user per machine is the
 supported scope.
 
+Every interactive `stacktrace remote configure` retries reconciliation of an
+already-installed, same-version root policy runtime, including when
+credentials are unchanged. Reconciliation is idempotent, so no retry marker is
+stored in the developer's config; a second interactive run retries a failed,
+declined or interrupted update. Noninteractive configuration never inspects
+the privileged runtime or opens a sudo prompt. An interactive configuration
+with a missing or version-mismatched root runtime directs the developer back
+to the one-line installer, which remains the only bootstrap and upgrade path
+for `/opt`.
+
 The file's installation is not proof that every key is effective. Claude can
 select a higher-ranked server or MDM source; current versions combine some
 restrictive MCP keys across sources, but not every key the compiler emits.

stacktrace_cli-0.8.0/docs/adrs/0089-infra-gate-reads-commands-not-shell-semantics.md

@@ -0,0 +1,132 @@
+---
+id: 0089
+title: The infra gate reads commands, not shell semantics
+status: accepted
+date: 2026-10-05
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+`stacktrace-infra-unsafe-action`'s deterministic gate decides which shell calls
+changed infrastructure, so Jev is asked about them. PR #130 went through more
+than twenty automated review rounds on it. After a consolidation pass closed
+four recurring classes, each later round found the next shell or CLI feature
+the gate did not model:
+
+- what `printf` renders: escapes, `%b`, precision, `\c`;
+- what `cat`, `tee` or a nested shell passes down a pipe;
+- which redirection wins over a pipe;
+- `|&` and `>|`;
+- a redirection glued to a word;
+- gcloud and az option values.
+
+Every fix was correct, and every fix made the gate more of a shell interpreter.
+The review never converged, because the set of shell features is open-ended.
+Without a written boundary, a reviewer reasonably reads each missing feature as
+a defect.
+
+## Decision
+
+The gate reads commands, not shell semantics, and its scope is the list in
+`docs/specs/detection-policies.md` § *stacktrace-infra-unsafe-action*, *What
+the gate reads*:
+
+- **Segments.** It reads each segment the shared parser yields, unwrapped
+  through `sudo`/`env`/`command`/`exec` and nested `sh -c`.
+- **Operations.** Each program's operation is read by that tool's own
+  documented grammar (subcommand, AWS operation, gcloud/az command words).
+- **SQL.** A database client is asked about when a mutating word appears
+  anywhere in its own command: its arguments, or a here-string or heredoc on
+  the client itself. The gate does not lex that text.
+
+**The gate errs toward asking.** Passing a call costs one Jev question, which
+reads the command. Wrongly holding one back is a missed change. So the gate
+never tries to prove a listed command changed nothing. It holds back only on
+stated suppression rules: the call did not succeed; a real `--dry-run`;
+every target flag naming this machine. Everything else that may be a change
+is asked about, a help request included.
+
+**Redirections and flag positions are not interpreted.** The gate reads words
+that `shlex` has already stripped of quoting, so a redirection read from them
+cannot be told from a quoted argument that looks like one. The gate does not
+read redirections, apart from binding a heredoc body to the command that opens
+it. It matches each suppression flag as a word anywhere in the segment, and
+does not walk each tool's flag positions. Whether a mutating word was executed or was only
+text (a string literal, a comment, a file name, an option's value, the
+client's own echo or meta-command) is the question's to read, and its
+instructions say a command that changed nothing is not beyond the request.
+
+What another command pipes into a client, a file's contents, and anything the
+shell evaluates first are out of scope. A missed case there is a missed
+change, which the list names. Review findings that need anything outside the
+list are a scope change, so they belong in an ADR that amends or supersedes
+this one, not in a fix round.
+
+## Alternatives considered
+
+- **Keep modelling the shell as review finds gaps.** Rejected. It does not
+  converge: each round of PR #130 found the next feature (`%.0s`, `\c`, `|&`,
+  `>|`, a glued `<`), and the result was a partial bash interpreter. That
+  interpreter was hard to review, and every one of its edges is a new finding.
+- **Execute or trace the command to learn what really ran.** Rejected. The
+  gate reads a transcript after the fact and must not run what an agent ran.
+  The shell state, files and environment it would need are not in the
+  transcript anyway.
+- **Lex each client's own dialect to prove a mutating word is inert.** This
+  was tried and then rejected (amended in PR #130, before merge). Seven more
+  review rounds each found the next rule:
+  - which options carry SQL, per client;
+  - MySQL's `-- ` needing a space, and PostgreSQL's `E'…'` escapes;
+  - sqlite3 dot-commands, psql meta-commands, mongosh template literals;
+  - then nested `/* /* */ */` comments.
+
+  Every dialect has more, and each one the lexer misses becomes a false
+  window. The question, which reads the whole command, settles them all at
+  once.
+- **Interpret redirections and flag positions on the parsed words.** Tried
+  and then rejected (amended in PR #130, before merge). Seven more review
+  rounds each found the next shape:
+  - a redirection before the program, then its order;
+  - its target read as a flag, or as an `rm` operand;
+  - a suppression flag's spelling appearing as another flag's value;
+  - then a quoted `'>name'` mistaken for a redirection, which made the `rm`
+    rule miss a real deletion.
+
+  The words have lost the quoting that tells these apart. Recovering it means
+  quote-aware lexing of redirections in the shared parser, which every gate
+  depends on: a larger change than this rule, for constructs agents rarely
+  write.
+- **Read text piped in from another command as the client's input.**
+  Rejected. Knowing what reached the client means rendering `printf`, `cat`,
+  `tee` and nested shells, which is the open-ended shell modelling this ADR
+  leaves out.
+
+## Consequences
+
+The gate is small enough to state in one list, and review has a contract to
+check it against. Its cost is recall: an agent that pipes SQL into `psql`,
+runs it from a file, or builds the command in a variable makes a change the
+rule does not see. That gap is named in the spec, not hidden. Asking rather
+than lexing costs a question for SQL that only mentions a mutation (a
+literal, a comment). Such SQL is rare in agent sessions, and Jev answers it
+false. The repeated-flag and alias cases are covered the same way, by asking
+unless every target value is local. A help request is asked about too, and
+Jev reads that it ran nothing. One out-of-scope
+area can err the other way: control flow is not evaluated, so a command after
+an unconditional `exit`, or behind a `||` that short-circuits, is read as run.
+That is the shared parser's own existing bound ("the commands a line *can*
+run"), and the spec states it. The shared parser
+keeps the `|&` and `>|` fixes, because they stopped it dropping or inventing
+segments for every gate, not just this one.
+
+## When to revisit
+
+When labelled sessions show real changes this boundary misses, measured
+rather than constructed, e.g. a meaningful share of DB mutations arriving
+through pipes or files. Or when the reasoning stage can be asked about a
+call without a deterministic gate in front of it. Either way, widen the list
+in a new ADR, with the class of input it adds and a test that enumerates it.

stacktrace_cli-0.8.0/docs/adrs/0090-count-completed-commands-locate-by-ip-send-through-the-managed-proxy.md

@@ -0,0 +1,156 @@
+---
+id: 0090
+title: Count completed commands, locate by IP, and send through the managed proxy
+status: accepted
+date: 2026-10-02
+supersedes: null
+superseded-by: null
+amends: 0039
+amended-by: null
+---
+
+## Context
+
+Subsystem: usage telemetry. The product owner asked for three things ADR-0039
+ruled out. Usage should report which commands people run, and where they run
+them, as PostHog's standard metrics do. Delivery should not depend on whether
+a network blocks `*.posthog.com`, which ad and tracker blocklists commonly do.
+Nothing already captured may be dropped.
+
+Four clauses of ADR-0039 stood in the way:
+
+- **Destination**: PostHog Cloud US, at `us.i.posthog.com`.
+- **`disable_geoip=True`**, which kept a city, coordinates and an IP-derived
+  location off every event.
+- **The closed set of four events**: `installed`, `session_started`,
+  `finding_delivered`, `error`.
+- **Preference and identity**: "Reading the preference or showing help does
+  not create an identifier or send an event." The code turned this into a
+  stronger rule in `SectionedGroup.invoke`: "A command that succeeds performs
+  no telemetry work at all." Two tests in `tests/telemetry/test_hooks.py`
+  enforced it.
+
+Adding a per-command event conflicts with the last clause by construction. It
+was stopped and raised rather than worked around, and the product owner
+decided to change the rule deliberately.
+
+Something found while preparing this decision: the PostHog project has
+`anonymize_ips: false`. All 4,107 events in the 14 days before this ADR (all
+four event types) carry `$ip`. `disable_geoip=True` kept the *derived* location
+off events. It never kept the address itself out of PostHog. ADR-0039 did not
+say otherwise, but it did not say so either.
+
+## Decision
+
+This replaces the four ADR-0039 clauses above. Everything else in ADR-0039
+stands, including its content boundary and the privacy assessment that gates
+a release.
+
+**Destination.** Events go to PostHog Cloud's US region through PostHog's
+managed reverse proxy at `https://w.stacktrace.ai`. That is a first-party
+hostname, so a network that blocks `*.posthog.com` still delivers. The project
+and its region do not change; only the hostname the client connects to does.
+
+**Location.** `disable_geoip=False`. PostHog derives a country and a city from
+the sending IP address. The project stores that address as `$ip`, as it already
+did. `stacktrace telemetry show`, the README and the AIDR spec say both of these
+things. A test asserts the setting, so an SDK default cannot change it in
+either direction without notice. `SDK_PROPERTIES` is checked for equality
+against a real captured event, not just as a superset of it. So
+`$geoip_disable`, which the SDK adds only while the lookup is off, has left the
+disclosure along with the setting.
+
+**A fifth event, `command_run`.** It has one required property, `command`: the
+name of the top-level command invoked. The name comes from
+`telemetry.events.COMMANDS`, which holds every name `cli.py` registers plus
+`other`. Anything else is sent as `other`. The event never carries an argument,
+a flag, a path or a value. A test asserts that `COMMANDS` equals the registered
+names plus `other`, so a new command either gets a row there or fails the suite.
+
+**When a command is counted.** This replaces ADR-0039's sentence about help
+and preference reads:
+
+- A command that **completes** hands off exactly one `command_run` and nothing
+  else. "Completes" means it returns, or it exits with `sys.exit(0)` the way an
+  OpenACA pass-through does. The hand-off is `emit`, so there is no network I/O
+  on the command's path and any failure is swallowed there. On a fresh
+  identity, `installed` is sent first, as it is ahead of any first event.
+- These send nothing and create no identity:
+  - `--help` and other help output, and `--version`
+  - a Click usage or argument error, an unknown command, and the argument
+    validation that `detect` and `monitor` do in their own bodies
+  - a bare `Exit` (including `Exit(0)`, which is how help ends), `Abort` and a
+    nonzero `sys.exit`
+  - every `stacktrace telemetry` subcommand except that `telemetry on` still
+    emits `installed`, exactly as before. `telemetry` is where consent is
+    given and read back, so using it is never counted as a run.
+- A command that fails is counted as its `error`, as before, and not as a run.
+- With telemetry off, nothing is sent and no identity is created, as before.
+
+The emission point is `SectionedGroup.invoke`, after the subcommand returns.
+It is not before dispatch, because Click parses the subcommand's arguments
+inside that call, and a usage error must leave nothing behind.
+
+## Alternatives considered
+
+- **Keep `us.i.posthog.com` direct.** Rejected. A network that blocks PostHog's
+  hostname silently loses every event, and that loss is not random: it skews
+  the sample toward unfiltered networks. The managed proxy fixes that without
+  anything for us to run.
+- **A self-hosted relay that strips the IP before forwarding**, like the
+  website's former `/ingest`. Rejected. It is a service to operate, monitor and
+  keep available for an unauthenticated write path, which is the cost ADR-0039
+  declined. It would also remove the location data the product owner asked
+  for.
+- **Emit `command_run` before dispatch.** Rejected. Click parses the
+  subcommand's arguments inside the dispatch, so a typo or `--help` would be
+  counted and, on a fresh machine, would create an identity for an invocation
+  that ran nothing.
+- **Treat `Exit(0)` as a completed run.** Rejected, because `--help` ends with
+  `Exit(0)`. A native command that means "done" returns instead of calling
+  `ctx.exit()`.
+- **Carry arguments, flags or subcommand paths** (`remote sync`, `daemon run`).
+  Rejected. They are open-ended, and some hold paths and values. The top-level
+  name answers which commands are used. A narrower question needs its own
+  scope decision.
+- **Count `telemetry` like any other command.** Rejected. Reading or turning
+  off the preference must not be the thing that creates an identity or sends
+  an event.
+
+## Consequences
+
+Every completed command on an enabled install now does telemetry work: it
+takes the lock without waiting, may create the identity on first use, and
+hands one event to the SDK's consumer thread. The command itself still never
+waits on the network. However, a process that queued an event runs the SDK's
+`atexit` hook, which makes one bounded delivery attempt before exit. In
+posthog 7.59.0 that is `_ATEXIT_FLUSH_TIMEOUT_SECONDS = 1.0`. So on a slow or
+unreachable network, a CLI invocation can take up to about a second longer to
+exit, after its output has been written. Until now that only happened on the
+rare `error` or `installed` invocation; now it happens on every completed
+command. Without that flush, a short-lived command's event would die with the
+process, because `FLUSH_INTERVAL` is 5 seconds.
+
+`STACKTRACE_TELEMETRY_DISABLED` sends nothing, as before. It does not stop the
+identity being created: with the preference on, the first event still writes
+`telemetry-id`. CI that sets only that variable will now get an identity file
+on its first completed command. `stacktrace telemetry off` is what creates
+nothing.
+
+The IP address is personal data in many jurisdictions, and it now also yields
+a stored city. ADR-0039's privacy assessment must cover:
+
+- `$ip` retention (`anonymize_ips` is `false` today)
+- city-level location
+- the proxy as an additional processor hop
+
+That assessment still gates the release. This ADR does not settle it.
+
+## When to revisit
+
+Revisit if the privacy assessment requires discarding the IP or coarsening
+location. That would mean `anonymize_ips`, or `disable_geoip=True` again, and
+a disclosure change to match. Revisit if a product question needs
+subcommand-level counts, if the managed proxy is withdrawn or changes
+ownership, or if the `atexit` flush is measured adding noticeable exit latency
+in practice.