stacktrace-cli 0.9.0__tar.gz → 0.10.0__tar.gz

stacktrace_cli-0.10.0/.github/workflows/bedrock-live.yml

@@ -0,0 +1,55 @@
+# Live Bedrock test in the sandbox account. Run by hand from the Actions tab.
+# Credentials come from GitHub's OIDC token, exchanged for a one-hour session
+# on a role that can only call Bedrock and read the invocation-logs bucket
+# (integrations/bedrock/tofu/ci.tf). No AWS key is stored anywhere.
+name: bedrock-live
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Branch, tag or SHA holding the test to run. Dispatch from main; this is what gets checked out.
+        required: false
+        default: main
+      model:
+        description: Inference profile ID. Empty picks a Claude Sonnet profile.
+        required: false
+        default: ""
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  live:
+    runs-on: ubuntu-latest
+    # The role trusts only jobs in this environment.
+    environment: bedrock-sandbox
+    timeout-minutes: 30
+    steps:
+      # GitHub dispatches only workflows on the default branch, and only to
+      # other refs after a first run, so the test's ref is an input instead.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: astral-sh/setup-uv@v6
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.BEDROCK_ROLE_ARN }}
+          aws-region: ${{ vars.BEDROCK_REGION || 'us-east-1' }}
+          role-duration-seconds: 3600
+      - run: uv sync
+      - name: Call each Bedrock API, read the logs back, run the rules
+        run: >
+          uv run --with boto3 python integrations/bedrock/live_test.py
+          --bucket "${{ vars.BEDROCK_LOGS_BUCKET }}"
+          --region "${{ vars.BEDROCK_REGION || 'us-east-1' }}"
+          ${{ inputs.model && format('--model {0}', inputs.model) || '' }}
+          --out bedrock-live
+      # Synthetic traffic only: scripted calls and a fake token.
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: bedrock-live
+          path: bedrock-live/
+          retention-days: 3

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/CLAUDE.md

@@ -279,9 +279,10 @@ silently editing an accepted ADR breaks that contract.
 - Calibrate priority by impact and urgency:
   - P0: critical, broadly applicable failure requiring immediate action.
   - P1: serious defect that should be fixed before this change lands.
-  - P2: normal-priority defect eligible for automatic fixing.
+  - P2: normal-priority defect.
   - P3: low-priority suggestion.
-  Do not inflate priority to make a finding eligible for automatic fixing.
+- Report only P0 and P1 findings. Do not post P2 or P3 findings, inline or
+  in the review summary. Do not inflate priority to get a finding reported.
 - On subsequent reviews, verify earlier fixes and inspect their effects on
   callers and dependencies. Older code within the PR remains reviewable.
 - When review history supports it, identify a finding as:

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.9.0
+Version: 0.10.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>
@@ -20,8 +20,8 @@ Classifier: Topic :: Security
 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.4.0
+Requires-Dist: openaca==0.10.1
+Requires-Dist: openaidr==0.6.1
 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.9.0 (openaca 0.8.0)
+stacktrace 0.10.0 (openaca 0.10.1)
 ```
 
 ## Quick start
@@ -178,6 +178,21 @@ 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).
 
+**With Fleet configured** (`stacktrace remote configure`), the daemon sends
+its findings, and its token usage for the cost ledger: tokens per run,
+session, model and minute, and per run the repository's name (`owner/repo`,
+from its `origin` remote), the branch, the session's own title (never the
+prompt) and the opaque id of the account the agent is signed into, Claude
+Code's or Devin's. With each account go its display name (else the part of its
+email before the `@`), its plan, and a key that groups one person's accounts:
+a hash of the email and the Fleet organization, never the email itself. A
+finding carries its session's account the same way. Prompts, tool arguments,
+results and paths are not sent (ADR-0096, ADR-0104, ADR-0101, ADR-0112).
+
+To learn who Devin is signed in as, `stacktrace` runs Devin's own `devin auth
+status`, which asks Devin's server. It asks again only after Devin's sign-in
+changes, or ten minutes after an ask that named no one (ADR-0110).
+
 `sessions` omits prompts, tool arguments and results unless you pass
 `--include-content`. `monitor` binds to loopback only, and refuses a
 non-loopback address rather than warning about it.
@@ -215,9 +230,10 @@ enables telemetry again under a new identity (ADR-0039, ADR-0090).
 
 Beta, and under active development.
 
-`sessions`, `detect` and `monitor` work end to end today. Session collection
-currently reads Claude Code transcripts; further agent kinds are in progress
-upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).
+`sessions`, `detect` and `monitor` work end to end today, for Claude Code and
+Devin sessions alike (Devin CLI and Devin Desktop's local agent). Session collection is
+[OpenAIDR](https://github.com/open-agent-security/openaidr)'s, and further agent
+kinds arrive with it. The daemon observes every kind it reads, sub-agents included.
 
 ## Built on
 

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/README.md

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.9.0 (openaca 0.8.0)
+stacktrace 0.10.0 (openaca 0.10.1)
 ```
 
 ## Quick start
@@ -151,6 +151,21 @@ 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).
 
+**With Fleet configured** (`stacktrace remote configure`), the daemon sends
+its findings, and its token usage for the cost ledger: tokens per run,
+session, model and minute, and per run the repository's name (`owner/repo`,
+from its `origin` remote), the branch, the session's own title (never the
+prompt) and the opaque id of the account the agent is signed into, Claude
+Code's or Devin's. With each account go its display name (else the part of its
+email before the `@`), its plan, and a key that groups one person's accounts:
+a hash of the email and the Fleet organization, never the email itself. A
+finding carries its session's account the same way. Prompts, tool arguments,
+results and paths are not sent (ADR-0096, ADR-0104, ADR-0101, ADR-0112).
+
+To learn who Devin is signed in as, `stacktrace` runs Devin's own `devin auth
+status`, which asks Devin's server. It asks again only after Devin's sign-in
+changes, or ten minutes after an ask that named no one (ADR-0110).
+
 `sessions` omits prompts, tool arguments and results unless you pass
 `--include-content`. `monitor` binds to loopback only, and refuses a
 non-loopback address rather than warning about it.
@@ -188,9 +203,10 @@ enables telemetry again under a new identity (ADR-0039, ADR-0090).
 
 Beta, and under active development.
 
-`sessions`, `detect` and `monitor` work end to end today. Session collection
-currently reads Claude Code transcripts; further agent kinds are in progress
-upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).
+`sessions`, `detect` and `monitor` work end to end today, for Claude Code and
+Devin sessions alike (Devin CLI and Devin Desktop's local agent). Session collection is
+[OpenAIDR](https://github.com/open-agent-security/openaidr)'s, and further agent
+kinds arrive with it. The daemon observes every kind it reads, sub-agents included.
 
 ## Built on
 

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0006-trust-boundary-and-detection-upload.md

@@ -5,7 +5,7 @@ status: accepted
 date: 2026-08-28
 supersedes: null
 superseded-by: null
-amended-by: 0011, 0027, 0031, 0039, 0064, 0084, 0086, 0096
+amended-by: 0011, 0027, 0031, 0039, 0064, 0084, 0086, 0096, 0109
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0031-one-host-daemon-observes-native-session-logs.md

@@ -6,7 +6,7 @@ date: 2026-09-17
 supersedes: null
 superseded-by: null
 amends: 0006
-amended-by: 0032, 0036, 0037, 0038, 0039, 0045, 0046, 0066, 0072
+amended-by: 0032, 0036, 0037, 0038, 0039, 0045, 0046, 0066, 0072, 0107, 0113
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0037-reuse-openaidr-append-cursors-in-the-daemon.md

@@ -6,7 +6,7 @@ date: 2026-09-18
 supersedes: null
 superseded-by: null
 amends: 0031
-amended-by: 0038, 0045
+amended-by: 0038, 0045, 0107
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0038-poll-normalized-sessions-for-supplemental-changes.md

@@ -6,7 +6,7 @@ date: 2026-09-21
 supersedes: null
 superseded-by: null
 amends: 0031, 0037
-amended-by: 0045
+amended-by: 0045, 0107
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0045-scan-every-session-and-outlive-them.md

@@ -6,7 +6,7 @@ date: 2026-09-22
 supersedes: null
 superseded-by: null
 amends: 0031, 0037, 0038
-amended-by: 0056, 0058, 0066, 0072
+amended-by: 0056, 0058, 0066, 0072, 0107
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0061-the-drain-sends-findings-only.md

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

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.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: 0078
+amended-by: 0078, 0105
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0078-a-seeded-display-prefix-replaces-the-hostname-label.md

@@ -6,7 +6,7 @@ date: 2026-09-30
 supersedes: null
 superseded-by: null
 amends: 0065
-amended-by: null
+amended-by: 0105
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0092-cost-is-its-own-rule-family.md

@@ -6,7 +6,7 @@ date: 2026-10-05
 supersedes: null
 superseded-by: null
 amends: null
-amended-by: null
+amended-by: 0113
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0093-environment-cost-baselines-count-tokens-keyed-by-model.md

@@ -6,7 +6,7 @@ date: 2026-10-05
 supersedes: null
 superseded-by: null
 amends: null
-amended-by: 0099
+amended-by: 0099, 0113, 0114
 ---
 
 ## Context

{stacktrace_cli-0.9.0 → stacktrace_cli-0.10.0}/docs/adrs/0096-cost-usage-may-leave-as-token-totals-and-work-identifiers.md

@@ -6,7 +6,7 @@ date: 2026-10-06
 supersedes: null
 superseded-by: null
 amends: 0006
-amended-by: null
+amended-by: 0103, 0109, 0115, 0116
 ---
 
 ## Context

stacktrace_cli-0.10.0/docs/adrs/0101-what-names-a-run-in-fleet.md

@@ -0,0 +1,111 @@
+---
+id: 0101
+title: A run is named in Fleet by its own title, its repo's name, its branch and the account seen running it
+status: proposed
+date: 2026-10-08
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: 0109, 0110, 0112
+---
+
+## Context
+
+[ADR-0096](0096-cost-usage-may-leave-as-token-totals-and-work-identifiers.md)
+allows four names per run on the usage upload: repo, branch, title and the
+Anthropic account. It says what each may not be: a path, a working directory,
+a machine name, or a prompt. It does not say where each comes from, and the
+code offers a wrong answer for three of them:
+
+- **Repo.** The only repo the code has is `working_directory`, which the cost
+  cohort keys on. It is a path, and the monitor shows it as one.
+- **Title.** The monitor labels a run with the title a person set, then the
+  one the client generated, then the opening request (`render._topic`). The
+  third is the prompt.
+- **Account.** No transcript records who was signed in. `login_type` reads
+  `oauthAccount.billingType` from Claude Code's config, today's value, and the
+  baseline marks it `assumed` for history.
+
+## Decision
+
+1. **Title: the session's own, cleaned, never the prompt.** The main session's
+   `title`, else its `generated_title`. Control characters are removed,
+   whitespace collapsed, and the result capped at 80 characters. It is dropped
+   when, case and spacing aside, it appears in the opening request, or the
+   opening request appears in it. A run with no title of its own sends none.
+2. **Repo: a name, from the remote.** The `origin` remote of the git repository
+   holding the main session's working directory, as its last two path segments
+   (`owner/repo`), without `.git`, userinfo or host. With no `origin`, the
+   repository's top-level directory name. Outside a repository, none. Read by
+   the daemon from `.git/config`, never by running `git`.
+3. **Branch: as the session records it** (`git_branch`).
+4. **Account: an opaque id, read live, and only for work seen live.** The
+   daemon reads `oauthAccount.accountUuid` from the same config `login_type`
+   reads: stable per Anthropic account, it tells two people on a shared box
+   apart and names neither. A run takes the account signed in the first time
+   the daemon sees a response of it at or after the daemon's start, and keeps
+   it. A run whose responses all predate the start, including the 30-day
+   backfill, sends none.
+5. **Each name passes the gate or travels as null.** Repo, branch, title,
+   account and model are checked with `enforce_usage_upload_contract`'s string
+   rules before they are stored, so a branch that looks like a path never costs
+   a page.
+
+The cost cohort keeps `working_directory`. It is local, and a cohort per
+checkout is what Phase 1 measures.
+
+## Alternatives considered
+
+- **The working directory's last component as the repo.** Rejected: outside a
+  repository it is often the home directory, so it names the user, and two
+  machines' checkouts of one repository get different names, which defeats
+  Fleet's "by repo" view.
+- **Run `git remote get-url origin`.** Rejected: a subprocess per run per
+  pass, from a daemon that otherwise execs nothing, to read one line of a file.
+- **The opening request, shortened, when there is no title.** Rejected:
+  ADR-0096 clause 3. A shortened prompt is a prompt.
+- **Drop a title only when it equals the prompt.** Rejected: a generated title
+  that copies the first words of the request carries them verbatim. Dropping
+  any title found inside the request loses some good titles, which is the safe
+  direction.
+- **Assume today's account for history**, as the baseline's `login` does.
+  Rejected for the wire: the account is what names a person on a shared box,
+  and a guess names the wrong one. The baseline's mark is local and says
+  `assumed`.
+- **The account's email.** Rejected: it names the person directly, and
+  personal data that need not leave the machine does not. Unique and readable
+  per person is exactly what makes an identifier name someone, so no readable
+  field of `oauthAccount` is a safe alternative.
+- **The account's display name, or the local username.** Rejected: both are
+  a person's name, neither is unique, and on a shared dev box or CI runner
+  the username is the same for everyone.
+- **A hash of the UUID.** Not taken. It would stop anyone mapping the id to a
+  person, including an org that wants to. The UUID already names no one; only
+  someone with access to the org's Anthropic account can map it.
+
+## Consequences
+
+- Fleet's "by repo" view joins checkouts across machines by their remote.
+- Backfilled history is attributed to the Fleet key only. A shared box's past
+  30 days cannot be split by person.
+- Fleet shows the account as a readable label derived from the UUID, such as
+  `account brave-otter-7f3a`, keyed by the UUID so two accounts never merge.
+  An org that wants names attaches one to an account inside Fleet. That is
+  Fleet's to build; nothing more travels for it.
+- The field name `accountUuid` is the one Claude Code writes: its
+  `oauthAccount` builder sets it beside `emailAddress` and `organizationUuid`
+  (checked against the shipped 2.1.294 binary on 2026-10-08). Claude Code
+  reads a legacy `.config.json` in its configuration directory before
+  `.claude.json`, and so does the daemon. A missing field reads as no account,
+  never as an error.
+- A title is still the easiest place for conversation to leak (ADR-0096). Watch
+  generated titles that quote a file name or an error message.
+
+## When to revisit
+
+- If Claude Code records the signed-in account in transcripts, read it there
+  and send it for history too.
+- If an org asks for titles off, through Task 12's policy field, add the switch
+  then.
+- If titles are found to carry conversation in practice, narrow clause 1 rather
+  than add a filter per case.

stacktrace_cli-0.10.0/docs/adrs/0102-token-use-is-never-compared-with-a-providers-usage-api.md

@@ -0,0 +1,55 @@
+---
+id: 0102
+title: Token use is never compared with a provider's usage API
+status: accepted
+date: 2026-10-08
+supersedes: null
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+`cost-phase-2.md` listed a reconciliation: Fleet would compare each org's
+daily token totals with the provider's usage API and show the share of
+usage Stacktrace did not see. `cost.md` said Phase 2 would measure that
+coverage gap this way, and its Phase 4 was done when each agent's recorded
+tokens reconciled with the provider's counts. The spec left one question open:
+whether to ask each org for an Anthropic admin key, which the usage API
+needs. On 2026-10-08 the product owner answered it: drop the feature
+completely, because Stacktrace doesn't do that.
+
+## Decision
+
+Stacktrace never compares, reconciles or checks its token figures against a
+provider's usage API, billing export or invoice, in the environment or in
+Fleet. It never asks an org for a provider admin key. Every figure is what the
+transcripts record (ADR-0099), and the gap between that and what the provider
+saw is stated in words where it matters, never measured.
+
+## Alternatives considered
+
+- **Reconcile daily totals with the Anthropic usage API, given an admin key.**
+  Rejected by the product owner. It would also make Fleet hold a credential
+  with organisation-wide reach on the provider's side, for a comparison the
+  product doesn't need.
+- **Reconcile only for orgs that offer a key.** Rejected with it: the feature
+  is dropped, not made optional.
+- **Compare against an uploaded billing export.** Rejected for the same
+  reason, and it brings money into a product measured in tokens (ADR-0099).
+
+## Consequences
+
+- No provider credential is asked for or held, in either repo.
+- Usage from machines without Stacktrace, or from other tools on the same
+  key, stays invisible, and nothing estimates how much there is. The specs say
+  so rather than promising a measurement.
+- Plan 017's Task 6 is removed, and with it Fleet's daily comparison and
+  "unattributed share".
+- Phase 4 is done when Codex and Cursor sessions are counted by the same
+  rules as Claude Code's, not when anyone's totals match a provider's.
+
+## When to revisit
+
+If the product owner asks for a comparison with a provider's figures.

stacktrace_cli-0.10.0/docs/adrs/0103-finished-runs-may-leave-as-numbers-for-org-baselines.md

@@ -0,0 +1,91 @@
+---
+id: 0103
+title: A finished run may leave as its baseline numbers, for org-wide baselines
+status: accepted
+date: 2026-10-08
+supersedes: null
+superseded-by: null
+amends: 0096
+amended-by: 0114, 0115
+---
+
+## Context
+
+Cost Phase 2 gives an environment with fewer than 20 similar sessions of its
+own the org's baselines for the same repo, entrypoint and model, so its waste
+rules work from day one (`cost-phase-2.md` §2, plan 017 Task 12). Fleet can
+build those only from the figures each environment's baseline is made of: per
+finished run, its tokens by active minute, its burn and its behaviour measures
+(ADR-0093). [ADR-0096](0096-cost-usage-may-leave-as-token-totals-and-work-identifiers.md)
+closes what the usage upload may carry to token totals and a short list of work
+identifiers, so none of these may leave today. The product owner asked for the
+amendment on 2026-10-08, on one condition: aggregate numbers only, never any of
+the trace itself.
+
+## Decision
+
+This amends ADR-0096 clause 2 for the cost usage upload alone. Clauses 1 and 3,
+and the rest of ADR-0006, stay in force.
+
+1. **Per finished run, its baseline numbers.** For each run the environment's
+   baseline holds (ADR-0093), and only once it has finished, the upload may
+   carry these and nothing else:
+   - `tokens`: recorded tokens, the run's total;
+   - `curve`: cumulative recorded tokens at the end of each active minute, at
+     most 240 values;
+   - `burn`: recorded tokens in the 5 minutes ending at each active minute, at
+     most 240 values;
+   - `subagents_in_10m`: the most sub-agents started within 10 minutes;
+   - `repeats`: how many times the most repeated call returned an unchanged
+     result, as a count;
+   - `input_per_response`: the 90th percentile of tokens sent per call;
+   - `lowest_cache_share`: the lowest cache-read share over 5 calls in a row on
+     a large context, or null;
+   - `cache_rewrites`: how many times the cache was rewritten on a large
+     context;
+   - the run's cohort: its repo as ADR-0101 names it (`owner/repo` or a
+     directory name, never a path), its entrypoint, and the model that carried
+     most of its tokens;
+   - the time of its last response, and a revision.
+2. **Numbers, never trace.** Each figure is a count, a token total or a ratio
+   the environment computes from the transcript. No call, tool name, argument,
+   result, file name, prompt, title or message travels with it, and none can be
+   recovered from it: `repeats` says how often, never what repeated. The
+   baseline's day slots (tokens by quarter hour of the day) stay on the
+   machine.
+3. **Back from Fleet, percentiles only.** Fleet returns, beside the policy
+   document, each cohort's percentiles over the org's last 30 days (p5, p50,
+   p95, p99 of each measure, and p50, p95, p99 of the curve and the burn at
+   each active minute) for cohorts with at least 20 runs. Never a run's own
+   figures, and never who ran it.
+4. **Runs a cost finding was raised on stay home.** They leave the local
+   baseline (ADR-0093), so they are not sent for the org's either.
+
+## Alternatives considered
+
+- **Send the day slots too, for an org day curve.** Rejected: they say when a
+  person works, the day curve is `personal-anomaly`'s, and Fleet already has
+  each owner's day from the token buckets.
+- **Send which call repeated, or the tools a run used.** Rejected: that is the
+  trace. The rules need how often, not what.
+- **Compute the org's percentiles from the token buckets alone.** Rejected:
+  buckets carry tokens per minute, not the behaviour measures the waste rules
+  judge (sub-agents, repeats, input per call, the cache).
+- **Ship each environment's own percentiles and merge them in Fleet.**
+  Rejected: percentiles do not merge, and an environment below 20 runs, the
+  case this exists for, has none.
+
+## Consequences
+
+- `usage-upload.md` declares `run_figures`, and `enforce_usage_upload_contract`
+  refuses any key or string beyond it. A test walks the declared shape and
+  fails on any field that is not a number, other than the cohort names, the run
+  id and the time.
+- An environment's evidence says "the org's runs" when an org cohort judged it,
+  never "this developer's".
+- Fleet holds 30 days of per-run numbers per org.
+
+## When to revisit
+
+If any figure is found to carry content, or a new waste rule needs a measure
+not listed here: amend clause 1, never widen it by implication.

stacktrace_cli-0.10.0/docs/adrs/0104-usage-is-its-own-upload.md

@@ -0,0 +1,92 @@
+---
+id: 0104
+title: Usage is its own upload, with its own job, its own gate and the store as its backlog
+status: proposed
+date: 2026-10-08
+supersedes: null
+superseded-by: null
+amends: 0061
+amended-by: null
+---
+
+## Context
+
+Cost Phase 2 needs every environment's tokens in Fleet (`cost-phase-2.md` §1).
+[ADR-0096](0096-cost-usage-may-leave-as-token-totals-and-work-identifiers.md)
+decides what may leave: token totals per run, session, model and minute, and a
+closed set of names per run. It does not decide how.
+
+Three things already in the code push on that:
+
+- ADR-0061 made the findings drain send findings and unknowns, nothing else,
+  and stopped the daemon capturing counters at all, because nothing read them.
+- The detect-run gate (`enforce_detect_upload_contract`) declares one document's
+  shape and refuses every key outside it. It cannot pass a usage document, and
+  should not learn to.
+- The findings queue is append-only and drained by a `seq` cursor (ADR-0046). A
+  usage bucket is not an event: it changes in place as a response grows
+  (OpenAIDR ADR-0014), so a cursor over it needs an append per change.
+
+## Decision
+
+1. **A new endpoint**, `POST /api/v1/usage`, one request per agent kind, in the
+   shape [`usage-upload.md`](../specs/usage-upload.md) declares. `detect-runs`
+   is unchanged.
+2. **A new job**, on its own thread, beside the findings drain and the BOM job.
+   It shares only the asset-transition lock with them (both can re-register an
+   asset). It is woken by the cost pass when a bucket changes, at most every
+   10 s, and runs every 60 s as a heartbeat otherwise.
+3. **The daemon captures counters again, for this reader.** This amends
+   ADR-0061 clause 2, which stopped capture because nothing read it. Token
+   usage is a different counter with a reader, kept in its own tables
+   (`usage_buckets`, `usage_runs`, `usage_state`), additive under ADR-0057.
+   Clause 1 stands: the drain sends findings only.
+4. **The store is the backlog.** Each row keeps its revision and the revision
+   Fleet last accepted. A row whose two differ is pending. Buckets merge by
+   max, so every writer commutes and a count never falls.
+5. **Its own gate**, `enforce_usage_upload_contract`, built from the same walk
+   and the same three refusals as the detect-run gate: an undeclared key, a
+   rooted path or a URI naming a place, a credential. The producer checks each
+   name before the gate and sends `null` for one that would be refused.
+6. **No bisection and no parking.** A 422 holds every row and is reported.
+   Usage carries counts and names checked locally, so a refusal is a wire
+   mismatch, and splitting a page cannot isolate one.
+
+## Alternatives considered
+
+- **Put usage on the findings drain.** Rejected, as ADR-0096 already rejected
+  it: ADR-0061 keeps the detection document one shape, and a usage backlog
+  would hold findings behind it.
+- **A `seq` cursor over an append-only usage log.** Rejected: every rewrite of a
+  growing response appends a row, and the reader must collapse them to the
+  latest per key before it sends. A revision per row is the collapsed form.
+- **Replace on write.** Rejected: the backfill thread and the pass both write,
+  and an older read landing last would lower a bucket Fleet already holds at a
+  higher count, at a higher revision Fleet would then keep.
+- **Widen `_DETECT_RUN_SHAPE` to cover both documents.** Rejected: a declared
+  shape is what makes "a key it does not name is refused" mean something. One
+  shape for two documents lets a usage field ride on a detect run.
+- **Reuse the drain's bisection.** Rejected: it exists to isolate one bad
+  finding among good ones. Usage has no row-shaped failure the producer can
+  reach, and bisecting a wire mismatch spends log₂(n) requests to refuse them
+  all.
+- **Send usage through `remote sync`, daemon-less.** Not built. A cron cannot
+  keep a 10-second cadence or a heartbeat, and the backlog needs the store.
+
+## Consequences
+
+- Fleet's Task 3 implements the endpoint against `usage-upload.md`. Until it
+  ships, a configured machine meets a 404, re-registers once, and backs off for
+  an hour. `personal-anomaly` keeps running, since its retirement waits for an
+  accepted request.
+- A row Fleet refuses holds the backlog until the cause is fixed. `daemon
+  status` names it.
+- The store grows by one row per session, model and active minute, pruned at 7
+  days once sent and at 30 days regardless.
+- A bucket that genuinely shrinks never says so. No case of one is known.
+
+## When to revisit
+
+- If Fleet answers usage refusals per row, bisection becomes worth its code.
+- If a second producer, such as a daemon-less posture, needs to send usage, the
+  backlog cannot stay in the daemon's store alone.