stacktrace-cli 0.0.1__tar.gz → 0.1.0__tar.gz

stacktrace_cli-0.1.0/.agents/skills/release-stacktrace/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: release-stacktrace
+description: Use when cutting a new stacktrace-cli PyPI release. Walks through version bump, release-notes drafting, pre-flight checks, tag, and push — enforces the publish-pypi.yml notes-file gate so the GitHub Releases page can't silently drift from PyPI.
+---
+
+# release-stacktrace
+
+End-to-end release procedure for the `stacktrace-cli` distribution.
+`.github/workflows/publish-pypi.yml` enforces the machine-checkable gates
+(tag on main, tag matches both version strings, notes file present, four
+CI gates green). This skill is the human-side counterpart: it drafts the
+notes with judgment, runs the pre-flight checks, and pushes the tag.
+
+**Announce at start:** "I'm using the release-stacktrace skill to cut a new
+stacktrace-cli release."
+
+## When to invoke
+
+User says any of: "cut a release", "ship 0.0.N", "release stacktrace",
+"tag a new version", or starts editing `pyproject.toml`'s version field
+in this repo.
+
+## Inputs
+
+1. **Target version** (e.g. `0.1.0`). Inferred from `pyproject.toml` if
+   the user already bumped it; otherwise ask.
+2. **Theme** — the H1 line of the notes file. Ask the user; a commit log
+   can't infer it.
+
+## Procedure
+
+### Step 1. Pre-flight checks
+
+Run from the repo root. Stop and ask if any fails — do not "fix" a dirty
+tree or out-of-sync main automatically, those signal in-flight work.
+
+```bash
+git rev-parse --abbrev-ref HEAD                    # must be main
+git status --porcelain                             # must be empty
+git fetch --tags origin
+git rev-parse --verify "v<version>" 2>/dev/null    # MUST FAIL — tag must not exist
+test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
+```
+
+`tests/test_release_readiness.py -m release_gate` is **not** run here: it
+requires `openaca`/`openaidr` pinned exactly, which is not true of a normal
+checkout (both float on `>=` between releases) and is only made true by
+Step 4. Running it against an unpinned tree would fail on every release, not
+just a broken one. It runs at the end of Step 4, once its precondition holds.
+
+PyPI versions are immutable, including yanked ones. If `<version>` is
+already on PyPI, the only path forward is a new version number:
+
+```bash
+curl -s https://pypi.org/pypi/stacktrace-cli/json | python3 -c 'import json,sys; print(sorted(json.load(sys.stdin)["releases"]))'
+```
+
+### Step 2. Gather the commit log
+
+```bash
+prev_tag=$(git describe --tags --abbrev=0)         # empty on the first release
+git log --oneline "${prev_tag}..HEAD"
+```
+
+Raw material only — do not dump it into the notes file verbatim.
+
+### Step 3. Draft `docs/releases/v<version>.md`
+
+Follow the shape of the existing files in `docs/releases/`:
+
+```markdown
+# <version> — <theme>
+
+## Highlights
+
+- **<Theme A>.** 1-3 sentences pitched at someone who installs the CLI.
+  Reference ADRs by number when a design doc backs the change.
+- **Bug fixes.** Combine small fixes into one bullet, comma-separated.
+
+## Install
+
+`uv tool install stacktrace-cli==<version>` or `pip install stacktrace-cli==<version>`.
+
+## Compatibility
+
+<Behavior changes existing users will notice. Say "pre-alpha, no
+back-compat hedging" while that's still true.>
+```
+
+**Judgment guidelines (apply ruthlessly):**
+
+- **Group by theme, not by commit.** Five commits adding one capability
+  are one bullet.
+- **Lead with user-visible impact**, not implementation.
+- **Cut chore/format/docs-only and release-machinery commits.** They
+  aren't release-visible.
+- **Acknowledge breaking changes explicitly** under `## Compatibility` —
+  a renamed subcommand or changed output shape goes there.
+
+Show the draft to the user and iterate until they agree it captures what
+shipped.
+
+### Step 4. Bump the version, pin workspace dependencies, and gate
+
+`pyproject.toml`'s `version` and `src/stacktrace_cli/__init__.py`'s
+`__version__` are separate sources; the workflow fails the build if they
+disagree with the tag. Move them together:
+
+```bash
+sed -i.bak 's/^version = ".*"/version = "<version>"/' pyproject.toml && rm pyproject.toml.bak
+sed -i.bak 's/^__version__ = ".*"/__version__ = "<version>"/' src/stacktrace_cli/__init__.py && rm src/stacktrace_cli/__init__.py.bak
+```
+
+`openaca` and `openaidr` are developed alongside this package and float on
+`>=` during normal development, but a prior release will have left them
+pinned exactly with `==` (see below), which would stop `uv lock` from ever
+resolving a newer release. Loosen both back to a floor first — the
+replacement matches either operator, so this is safe to run whether the tree
+is currently floating or still pinned from last time:
+
+```bash
+sed -i.bak -E 's/^    "openaca(>=|==)[^"]*"/    "openaca>=0"/' pyproject.toml && rm pyproject.toml.bak
+sed -i.bak -E 's/^    "openaidr(>=|==)[^"]*"/    "openaidr>=0"/' pyproject.toml && rm pyproject.toml.bak
+uv lock                                            # refresh uv.lock, now free to pick the newest release
+uv run stacktrace --version                        # sanity: prints <version>
+```
+
+Now pin both to whatever `uv lock` just resolved — the one point in the
+procedure where the lockfile has just picked the newest available versions
+and a release is actually being cut:
+
+```bash
+openaca_version=$(grep -A1 '^name = "openaca"' uv.lock | grep version | cut -d'"' -f2)
+openaidr_version=$(grep -A1 '^name = "openaidr"' uv.lock | grep version | cut -d'"' -f2)
+sed -i.bak -E "s/^    \"openaca(>=|==)[^\"]*\"/    \"openaca==${openaca_version}\"/" pyproject.toml && rm pyproject.toml.bak
+sed -i.bak -E "s/^    \"openaidr(>=|==)[^\"]*\"/    \"openaidr==${openaidr_version}\"/" pyproject.toml && rm pyproject.toml.bak
+uv lock                                            # refresh uv.lock for the exact pin
+uv run pytest tests/test_release_readiness.py -m release_gate
+```
+
+The gate is not covered by `.github/workflows/publish-pypi.yml`, which runs
+the default `uv run pytest -q` — and `pyproject.toml`'s `addopts` excludes
+`release_gate` from that default run on purpose (it fails throughout normal
+development, before this step pins the floors). This skill is the only place
+it runs before a tag is pushed, so skipping it here is the one way a version
+with an unpinned `openaidr`/`openaca` requirement reaches PyPI. Stop and ask
+if it fails.
+
+### Step 5. Release-prep commit + PR
+
+If the user's original request did not explicitly ask to cut, ship, or
+publish a release, stop before the push and ask. Editing the version
+field is enough to invoke this skill; it is not permission to publish.
+
+```bash
+git checkout -b release/<version>
+git add pyproject.toml uv.lock src/stacktrace_cli/__init__.py docs/releases/v<version>.md
+git status --porcelain          # inspect anything still unstaged; stage intentionally or stop
+git commit -m "release: <version> — <theme>"
+git push -u origin release/<version>
+```
+
+Opening the PR needs its own explicit ask. Then:
+
+```bash
+gh pr create --title "release: <version>" --body "Release prep for <version>.
+
+- Bumps \`pyproject.toml\` and \`__version__\` to <version>
+- Adds release notes at \`docs/releases/v<version>.md\`
+- After merge: tag \`v<version>\` on main and push to trigger PyPI publish + GitHub Release"
+```
+
+Surface the PR URL. **Stop here.** The user reviews and merges.
+
+### Step 6. After merge: tag + push
+
+After the user confirms the PR merged, on a clean main:
+
+```bash
+git checkout main
+git pull --ff-only
+git tag v<version>
+git push origin v<version>
+```
+
+The tag-triggered run registers asynchronously, so `--limit 1` can grab a
+stale earlier run. Poll for the run tied to the tagged commit:
+
+```bash
+tag_sha=$(git rev-parse "v<version>^{commit}")
+run_id=""
+until [ -n "$run_id" ]; do
+  run_id=$(gh run list --repo stacktrace-ai/stacktrace \
+    --workflow publish-pypi.yml --commit "$tag_sha" \
+    --json databaseId --jq '.[0].databaseId // empty')
+  [ -z "$run_id" ] && sleep 5
+done
+gh run watch --repo stacktrace-ai/stacktrace "$run_id"
+```
+
+### Step 7. Verify
+
+```bash
+curl -s https://pypi.org/pypi/stacktrace-cli/json | python3 -c 'import json,sys; print(sorted(json.load(sys.stdin)["releases"]))'
+gh release view v<version> --repo stacktrace-ai/stacktrace --json name,body
+uvx --from stacktrace-cli==<version> stacktrace --version    # installs from PyPI, must print <version>
+```
+
+All three must succeed. If any fails, surface the workflow run URL rather
+than guessing.
+
+## Failure modes this prevents
+
+1. **On PyPI but not on GitHub Releases.** The workflow's notes-file gate
+   runs before publish: no notes file at the tag → no PyPI upload.
+2. **Notes file is a raw commit dump.** Step 3's judgment guidelines.
+3. **Tagging a non-main commit.** The workflow's "Verify tag is on main".
+4. **Tag ≠ `pyproject.toml` version, or `__version__` drift.** Two
+   separate workflow steps; Step 4 keeps them moving together.
+5. **Forgetting to refresh `uv.lock`.** `uv sync --frozen` fails in the
+   build job; Step 4 bumps the lock to avoid the round-trip.
+
+## What this skill does NOT do
+
+- **Doesn't publish to PyPI directly.** The workflow does, via Trusted
+  Publishing (OIDC). There is no PyPI token anywhere in this repo, and
+  none should be added.
+- **Doesn't create the GitHub Release directly.** The workflow's
+  `release-github` job does, from the notes file.
+- **Doesn't write a CHANGELOG.md.** The convention is per-release files
+  under `docs/releases/`.
+- **Doesn't yank.** PyPI versions are immutable; a broken release is
+  fixed by shipping the next version, not by re-uploading.

stacktrace_cli-0.1.0/.codex/hooks.json

@@ -0,0 +1,34 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE COMPACTION ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/INDEX.md ]; then printf '=== ARCHITECTURE DECISIONS (docs/adrs/) ===\\n\\nRead a full ADR before changing logic in the area it covers.\\n\\n'; cat docs/adrs/INDEX.md; fi"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE SESSION END ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

{stacktrace_cli-0.0.1 → stacktrace_cli-0.1.0}/.github/workflows/autofix.yml

@@ -111,7 +111,7 @@ jobs:
       # two string representations depending on which API you read.
       - name: Cap auto-address iterations (max 7)
         run: |
-          MAX=7
+          MAX=15
           CLAUDE_RUNS=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
             --jq '[.comments[] | select(.author.login == "claude")] | length')
           if [ "$CLAUDE_RUNS" -ge "$MAX" ]; then

{stacktrace_cli-0.0.1 → stacktrace_cli-0.1.0}/.github/workflows/claude.yml

@@ -100,10 +100,16 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           # Subscription-tied OAuth path. Provision via `claude setup-token`
-          # CLI and store as the CLAUDE_CODE_OAUTH_TOKEN repo secret. To use
-          # the pay-per-use API-key path instead, replace this line with
-          # `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}` and create
-          # a key at https://platform.claude.com/settings/workspaces/default/keys.
+          # CLI and store as the CLAUDE_CODE_OAUTH_TOKEN repo secret.
+          #
+          # This ran on the pay-per-use API key for one day (d2c62b0) to escape
+          # the throttling the subscription's shared session window imposes on
+          # long review runs, and the spend was not worth it: this workflow is
+          # fired by every review comment on an open PR, so an active
+          # review loop bills per round with no ceiling of its own. Throttling
+          # is the cheaper failure. To switch back, replace this line with
+          # `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}` (the secret is
+          # still provisioned) and set a workspace spend limit first.
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
           # Lets Claude read CI results on PRs.

{stacktrace_cli-0.0.1 → stacktrace_cli-0.1.0}/CLAUDE.md

@@ -8,11 +8,21 @@ unrelated project). It is consumed by developers who `pip install stacktrace-cli
 and by CI pipelines that invoke `stacktrace`, and it builds on the open-source
 `openaca` Agent Composition Analysis toolkit.
 
+It is also the **design home for Stacktrace Detect** — the AIDR product this CLI
+grows into. The specs in `docs/specs/` and the decisions in `docs/adrs/` describe
+the whole system: session input, correlation against the composition graph, the
+three-stage detector, and the combined report. The code here is the placeholder that
+precedes them.
+
 ## Common commands
 
 ```bash
 uv sync                                    # install / update deps
 uv run stacktrace --version                # run the CLI from the working tree
+uv run stacktrace sessions                 # what the agents on this machine did
+uv run stacktrace sessions --format json   # the same, machine-readable
+uv run stacktrace detect                   # what ran, correlated and judged
+uv run stacktrace detect --bom b.json      # against a supplied Agent BOM
 uv build                                   # build sdist + wheel into dist/
 uvx --from 'twine>=7' twine check dist/*   # validate artifacts (twine <7 rejects Metadata-Version 2.5)
 ```
@@ -48,6 +58,24 @@ Composition Analysis primitives this CLI is intended to drive.
 The package is currently pre-alpha: `main()` reports its version and points at
 the docs. Real functionality lands in later releases.
 
+**The design that functionality implements is in this repo.** Read
+`docs/specs/aidr.md` first — it is the umbrella: components, contracts, the two
+modes, and what comes from where. Then the component specs:
+
+| Spec | Covers |
+|---|---|
+| `docs/specs/aidr.md` | Umbrella — components, contracts, tenets, delivery |
+| `docs/specs/session-input.md` | The seam over OpenAIDR, which collects sessions |
+| `docs/specs/correlation.md` | The join: sessions against the composition graph |
+| `docs/specs/detector.md` | Three-stage detection and the finding family |
+
+Two dependencies, both Apache-2.0 and neither depending on this package:
+`openaca` for composition, and `openaidr`
+(https://github.com/open-agent-security/openaidr) for session collection, which
+wraps Uber's third-party `adr-sensor`. Nothing proprietary flows into either
+(ADR-0007); the one thing we need from OpenACA is graph caching, and it names
+nothing about detection.
+
 ## Repo conventions
 
 - **Four names, deliberately not identical.** PyPI distribution
@@ -75,6 +103,23 @@ the docs. Real functionality lands in later releases.
   API token exists in this repo, and none should be added), then creates the
   GitHub Release from the notes file. The `release-stacktrace` skill drives
   the human side.
+- **OpenACA carries nothing AIDR** (ADR-0006). No finding family, no output row
+  type, no scan flag, no rule namespace upstream. Detection rule identifiers are
+  `stacktrace-*`, never `openaca-*`, and the combined report is assembled here.
+- **Session collection is not ours** (ADR-0002). It lives in `openaidr`, open
+  source. Its types stop at our adapter; parsing an agent format here would
+  duplicate the thing the split exists to prevent.
+- **A class-shaped review finding is closed with an invariant, not a patch.**
+  Four classes of finding recurred across this branch's review rounds — a denied
+  call counted as evidence, untrusted text echoed into a finding, an
+  unvalidated field in an external document, a prompt field missing from the
+  cache key — because each was fixed at the site a reviewer happened to read
+  while the *rule* stayed in the reviewer's head. Each is now enforced by a test
+  that asks about every site or every field rather than the one that bit us:
+  `tests/test_call_status_conventions.py`, `test_untrusted_content_never_travels.py`,
+  `test_bom_shape.py`, `test_fingerprint_covers_what_the_analyzer_reads.py`. When
+  a review names a site, fix the invariant and extend the exhaustive test — a
+  second finding of the same class means the first fix was at the wrong level.
 
 ---
 

stacktrace_cli-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: stacktrace-cli
+Version: 0.1.0
+Summary: Placeholder CLI for Stacktrace.ai — installs the `stacktrace` command.
+Project-URL: Homepage, https://stacktrace.ai
+Author-email: Prasanth G <prasanth@openaca.dev>
+License-Expression: LicenseRef-Proprietary
+Keywords: agent-security,ai-security,openaca,stacktrace
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+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.6.0
+Requires-Dist: openaidr==0.1.0
+Description-Content-Type: text/markdown
+
+# stacktrace-cli
+
+Command-line interface for [Stacktrace.ai](https://stacktrace.ai).
+
+The PyPI distribution is named `stacktrace-cli`  Installing this package provides
+the `stacktrace` executable.
+
+```bash
+pip install stacktrace-cli
+stacktrace --version
+```
+
+This is an early placeholder release. It depends on
+[`openaca`](https://pypi.org/project/openaca/), the open-source Agent
+Composition Analysis toolkit that Stacktrace.ai builds on.
+
+## Design
+
+This repository is the design home for Stacktrace Detect — the agentic AI
+detection and response product this CLI grows into. OpenACA answers *what is
+installed and what could it do*; Stacktrace Detect adds *what did it actually
+do*, by joining agent session activity to the composition graph.
+
+| Document | Covers |
+|---|---|
+| [docs/specs/aidr.md](docs/specs/aidr.md) | Umbrella — components, contracts, tenets, delivery |
+| [docs/specs/session-input.md](docs/specs/session-input.md) | The seam over OpenAIDR, which collects sessions |
+| [docs/specs/correlation.md](docs/specs/correlation.md) | The join: sessions against the composition graph |
+| [docs/specs/detector.md](docs/specs/detector.md) | Three-stage detection and the finding family |
+
+Decisions are in [docs/adrs/](docs/adrs/).
+
+Built on two Apache-2.0 packages, neither of which depends on this one:
+[`openaca`](https://pypi.org/project/openaca/) for composition analysis, and
+[`openaidr`](https://github.com/open-agent-security/openaidr) for session
+collection.
+
+## Status
+
+`stacktrace` is one front door over two kinds of command:
+
+```
+Analysis (OpenACA):
+  bom     Generate an Agent BOM for a repository or endpoint.
+  policy  Validate and compile restrictive endpoint policies.
+  scan    Scan a repository or endpoint for agent-composition findings.
+
+Stacktrace:
+  detect    Find security and reliability findings in what agents did.
+  remote    Configure remote endpoint services.
+  sessions  Print what the agents on this machine actually did.
+```
+
+`stacktrace` is the entry point for hosted-product users. OpenACA remains the
+tool itself and stays independently installable — with it installed, both
+`openaca scan` and `stacktrace scan` work and do exactly the same thing,
+because they are the same Click command object running in one process.
+`stacktrace --version` reports both versions, which turns "which did you run?"
+into one answered question.
+
+**Pre-alpha, and not installable from PyPI yet.** `stacktrace sessions` works —
+it reads what the agents on this machine did, through
+[OpenAIDR](https://github.com/open-agent-security/openaidr):
+
+```console
+$ uv run stacktrace sessions --since 2d --include-content
+claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
+  assistant: Reading the changelog before drafting the release notes.
+    ok                28c  Read
+        result: ## 0.4.0 - correlate, detect
+  assistant: Filing the release-notes follow-up.
+                        -  github/create_issue
+
+Summary — 1 sessions, 2 turns, 2 tool calls
+
+  agent kinds
+          1  claude-code
+
+  tools called (2 distinct)
+          1  Read
+          1  github/create_issue
+
+  MCP servers reached (1 distinct)
+          1  github
+
+  0 subagent turns · 0 results abridged upstream · 1 ok
+
+1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.
+```
+
+The blank status on the second row is the collector's `unknown`, not a pending
+call: the client recorded no outcome it could establish, and the closing line
+says how many of those there were rather than filling one in.
+
+The next step is the join: resolving what ran to the components the agent is
+built from. `detect` performs it — it correlates the collected sessions against
+an Agent BOM before it judges anything — but there is no longer a command that
+prints the correlated view on its own. `stacktrace correlate` was withdrawn; the
+correlation code stays, as the stage `detect` is built on.
+
+Both `openaca` and `openaidr` resolve from PyPI now, like any other
+dependency — no sibling checkout, no `[tool.uv.sources]` override. What still
+gates a release is narrower: both float on `>=` during normal development but
+must be pinned exactly (`==`) before a version is published, so a built wheel
+names precisely what it was tested against.
+`uv run pytest tests/test_release_readiness.py -m release_gate` checks that —
+the `release-stacktrace` skill runs it as part of cutting a release.
+
+## Adding a command
+
+A command is a **pass-through** or it is **native**, never both — and a
+pass-through never gains a flag of its own. See
+[ADR-0021](docs/adrs/0021-two-command-kinds.md) for why.
+
+- **Pass-through** — add one string to `PASSTHROUGH` in
+  `src/stacktrace_cli/cli.py`, having decided it belongs. The loop registers
+  OpenACA's own command object under that name; there is nothing else to
+  write and nothing to keep in step with OpenACA.
+- **Native** — write a Click command or group and `add_command` it, the way
+  `remote` is. If it needs OpenACA it calls `openaca.core`
+  ([ADR-0020](docs/adrs/0020-openaca-consumption-boundary.md)), and whatever
+  it names there is added to the contract test in `tests/remote/`, because it
+  now holds duplicated knowledge of an interface.
+
+The section a command lands under in `--help` follows from which kind it is;
+there is no second list to update.
+
+
+## Development
+
+`uv sync` and the four gates — `ruff check`, `ruff format --check`, `pyright`,
+`pytest` — need nothing beside this repository. `openaca` resolves from PyPI at
+the floor `pyproject.toml` declares. A sibling `../openaca` checkout is no
+longer read: the interim `[tool.uv.sources]` path source retired at the 0.6.0
+cutover.
+
+## Cutover from `openaca remote`
+
+`stacktrace remote` is the hosted-service client OpenACA is removing. The
+behaviour, the payload and the Cloud endpoints are unchanged; only the code
+that produces them moved. Machines already running `openaca remote sync
+endpoint` need four steps each.
+
+1. **Have the collector token to hand, or mint a new one.** A collector token
+   cannot be recovered from the Cloud — it is returned once at issuance and
+   only a hash and its last four characters are kept — so it has to come from
+   wherever it was stored (an MDM secret store, a password manager). If it was
+   not stored, mint a new one and deploy that; nothing goes down while you do,
+   because the existing token keeps working until it is revoked.
+2. **Configure this machine.** `stacktrace remote configure --token …`, or set
+   `STACKTRACE_REMOTE_TOKEN` and `STACKTRACE_REMOTE_API_URL` for a scripted
+   deployment.
+3. **Repoint whatever schedules the sync** at `stacktrace remote sync
+   endpoint`.
+4. **Delete `~/.config/openaca/remote.toml`.** Once OpenACA has no `remote`
+   command, that file is an unused plaintext credential sitting on disk.
+   Nothing breaks if it stays, which is exactly why it will be forgotten.
+
+### What takes care of itself
+
+- **The asset converges.** Registration is idempotent on `(org, asset_type,
+  external_id)` with the host name as `external_id`, so registering from here
+  resolves to the same asset OpenACA registered — one extra round trip on the
+  first run, no duplicate machine in the console.
+- **Both commands may coexist during the overlap**, producing two BOM rows per
+  sync. That is noise rather than corruption.
+
+> These two statements, and the unrecoverability of a collector token in step
+> 1, describe what the deployed Cloud does. They have **not** been confirmed
+> against the running service for this release — they are read from the
+> hosted side's design, which records what some revision implements rather
+> than what production does today. Confirm them before an operator acts on
+> step 1 in particular: discarding the only copy of a token on the strength of
+> an unverified sentence leaves no recovery.
+
+### What does not
+
+- **A pending OpenACA spool is orphaned.** Its files are in
+  `~/.local/state/openaca`, and this channel never reads them. Drain it by
+  running the old command once before cutting over, or accept losing what it
+  holds. Do not assume that is one sync's worth: the spool keeps one file per
+  failed agent and accumulates across offline runs, so count the files first.
+- **The MDM deploy scripts and the scheduled agent** do not exist here yet.
+
+## Release obligations
+
+Finishing the remote-sync work was **not** the same as being releasable, and
+the gap was structural rather than a matter of polish: while `pyproject.toml`
+carried a path source to a sibling checkout, `pip install stacktrace-cli` from
+PyPI would have resolved an `openaca` without the consumption facade, and every
+`remote` command would have failed at import.
+
+All three are discharged, at `openaca` 0.6.0 — the first release carrying the
+facade:
+
+1. `[tool.uv.sources]` is gone; `uv.lock` resolves `openaca` from PyPI.
+2. `.github/workflows/ci.yml` checks out this repository alone. The sibling
+   checkout and its pinned-revision assertion went with the path source.
+3. The floor is `openaca>=0.6.0`, which is where plan 005 Task 1's
+   required-import probe first reports no missing name. Re-run that probe
+   against any candidate release before moving the floor again; it passes only
+   when it reports nothing missing.
+
+One proof retired with them. The payload-equivalence test imported openaca's
+`tools.remote` — the module 0.6.0 removed — so it cannot run against any
+release that carries the facade. What it established is a fact about the
+migration, not a property that a later release could re-check.