amicus 0.3.0__tar.gz → 0.5.0__tar.gz

{amicus-0.3.0 → amicus-0.5.0}/.claude-plugin/marketplace.json

@@ -7,7 +7,12 @@
   "plugins": [
     {
       "name": "amicus",
-      "source": "./",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/briandconnelly/amicus.git",
+        "ref": "v0.4.0",
+        "sha": "970905ad7141d2d3e650b7401685b893abf258db"
+      },
       "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter."
     }
   ]

{amicus-0.3.0 → amicus-0.5.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter.",
   "author": { "name": "Brian Connelly", "url": "https://github.com/briandconnelly" },
   "homepage": "https://github.com/briandconnelly/amicus",

{amicus-0.3.0 → amicus-0.5.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter.",
   "author": { "name": "Brian Connelly", "url": "https://github.com/briandconnelly" },
   "homepage": "https://github.com/briandconnelly/amicus",

{amicus-0.3.0 → amicus-0.5.0}/.github/dependabot.yml

@@ -15,6 +15,17 @@ updates:
         dependency-type: "development"
       python-runtime:
         dependency-type: "production"
+    # pyproject.toml caps fastmcp and mcp to a minor line because fastmcp
+    # documents breaking changes in minor releases. Widening a cap is a
+    # hand-written upgrade PR (#106), so Dependabot is told not to propose the
+    # minor or major that would move it; patch releases inside the cap still
+    # arrive through the python-runtime group. `ignore` also covers security
+    # updates, which changes nothing: the cap already excludes those versions.
+    ignore:
+      - dependency-name: "fastmcp"
+        update-types: ["version-update:semver-minor", "version-update:semver-major"]
+      - dependency-name: "mcp"
+        update-types: ["version-update:semver-minor", "version-update:semver-major"]
 
   # GitHub Actions used in workflows (keeps SHA pins current).
   - package-ecosystem: "github-actions"

{amicus-0.3.0 → amicus-0.5.0}/.github/workflows/test.yml

@@ -37,3 +37,20 @@ jobs:
         run: uv run lint-imports
       - name: Test (95% coverage floor)
         run: uv run pytest
+
+  marketplace-pointer:
+    name: marketplace pointer
+    # Only a pull request has a base to compare the pointer against.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # Full history and tags: the pointer's tag is checked, and the base commit is read.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: The marketplace pointer is consistent and never moves backwards
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: uv run python scripts/check_release_state.py --base "$BASE_SHA"

{amicus-0.3.0 → amicus-0.5.0}/.mcp.json

@@ -4,7 +4,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "git+https://github.com/briandconnelly/amicus.git@v0.2.0",
+        "git+https://github.com/briandconnelly/amicus.git@v0.5.0",
         "amicus-mcp"
       ],
       "env_vars": [

{amicus-0.3.0 → amicus-0.5.0}/AGENTS.md

@@ -29,12 +29,13 @@ The rules bind; the context after them explains and points elsewhere.
 17. Never edit a sibling checkout (`~/projects/codex-in-claude`, `~/projects/moonbridge`, `~/projects/claude-in-codex`, `~/projects/pontonier`).
 18. Never write a prompt input — every field in `INPUT_FIELDS` (`src/amicus/request.py`): `question`, `task`, `extra_context`, `instructions_append`, `focus`, `target`, `evidence` — to disk, to a worker's argv or to a log; it travels over the worker's stdin.
     This binds amicus's own handling and everything it commits, including host captures and eval prompt bodies, which are recorded as an id and a `sha256` instead.
-    A backend's own native carrier is exempt where that backend offers no alternative and the carrier is disclosed in its `CARRIERS` string and surfaced on `amicus_backends`; the two that exist today are Kimi's handshake file, because kimi ignores stdin, and Codex's `-c developer_instructions` argv token.
+    A backend's own native carrier is exempt where no documented or observed way to avoid it has been found on the backend CLI release an amicus release is validated against, re-checked before every amicus release on the CLI versions its rule-20 evidence is recorded on, and the carrier is disclosed in its `CARRIERS` string and surfaced on `amicus_backends`; the three that exist today are Kimi's handshake file, the kimi CLI's own session store, and Codex's `-c developer_instructions` argv token.
     Prompt text that a test or capture script assembles entirely from its own literals is exempt, including the `build_*_prompt` output committed in `tests/fixtures/*_differentials.json`; it stays verbatim, because a differential must show what changed and a hash cannot.
-    No exemption reaches text that was copied, derived or replayed from a prompt anyone sent: that stays bound however it is later stored or relabelled.
+    No exemption reaches text that amicus itself, or anyone working in this repository, copies, derives or replays from a prompt anyone sent: that stays bound however it is later stored or relabelled.
+    A backend's answer, and the result amicus builds from it — its parsed fields and, for a delegate, the diff captured from the worktree — is output, not a prompt input, even where it quotes or paraphrases one: amicus keeps it only on the job record (`result.json`, written through a staging file in the same directory), under the job retention the tool surface discloses (`AMICUS_JOB_TTL`, the per-workspace cap, `amicus_job_consume_result`), and writes it to no log, argv or other file; what this repository commits of an answer stays bound by the sentence before this one wherever the answer repeats a prompt anyone sent.
 19. Release in two PRs: the work lands with the version literals untouched, then a `chore(release):` PR moves them together and rolls `## [Unreleased]` in `CHANGELOG.md` into a dated section.
-    The literals are `pyproject.toml`, `src/amicus/__init__.py`, `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`.
-    `.mcp.json`'s pin is NOT one of them; rule 24 governs it, and a release must not touch it.
+    The literals are `pyproject.toml`, `src/amicus/__init__.py`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` and `.mcp.json`'s `--from` pin, which names the tag of the release being made; README's "Any other MCP client" example moves with that pin.
+    `.claude-plugin/marketplace.json`'s pointer is NOT one of them; rule 24 governs it, and a release must not touch it.
     `uv.lock` mirrors the version rather than declaring it: regenerate it in that same PR with `uv lock`, or the `uv lock --check` hook fails.
     Only the maintainer merges that PR, and only the maintainer pushes the tag.
     Push the matching tag before any other work follows that merge: until it exists, `main` declares a version that has no release.
@@ -47,18 +48,27 @@ The rules bind; the context after them explains and points elsewhere.
     Never move a release check into the `pypi` job: GitHub holds every step of an environment job behind that environment's required reviewer, so a check placed there runs only after the approval it exists to inform.
 23. Never describe the rule-20 record, in any document or output, as proof that the live gates ran.
     It is the maintainer's assertion, machine-checked for shape and for naming the tagged commit; the runs happen on the maintainer's machine and the record is written there.
-24. `.mcp.json`'s `--from` pin names a release that is already published, never the one being released, and it may never name a version newer than the one the tree declares.
-    A release PR under rule 19 leaves it untouched; move it to the new tag in its own `chore(release):` PR after that tag is published and its install has been checked.
+24. `.claude-plugin/marketplace.json`'s plugin entry names a release that is already published, by `ref` and a `sha` equal to that tag's peeled commit, never the one being released, and it may never name a version newer than the one the tree declares.
+    A release PR under rule 19 leaves it untouched; advance it to the new tag in its own `chore(release):` PR after that tag is published and its install has been checked, and a release is not complete until that PR merges.
     That PR is not a release: it needs no rule-20 evidence, because it moves a pointer to a tag that already exists.
+    Until the 0.4.0 pointer PR merges the entry's `source` is `"./"`; for 0.4.0 only, nothing else merges to `main` between the release PR and that pointer PR.
 
 ## Context
 
 ### What this is
 
-One MCP server for every second-opinion model: a verb-first tool surface with the backend as a parameter, built on FastMCP and the [pontonier](https://github.com/briandconnelly/pontonier) backend SDK.
+One MCP server for every second-opinion model: a verb-first tool surface with the backend as a parameter, built on FastMCP and its own in-tree backend SDK, `amicus.sdk`.
 The package is `amicus` under `src/`; each backend is a plugin under `src/amicus/backends/<id>/` behind the `BackendPlugin` seam in `src/amicus/plugin.py`.
+`amicus.sdk` (under `src/amicus/sdk/`) is the backend-facing layer: the backend protocol and contract, the error vocabulary, annotations and preflight, the subprocess runtime with stream capping, redaction, path-alias sanitizing and a bounded JSON reader, and the conformance kit a plugin must pass before the registry will use it.
+It was copied from [pontonier](https://github.com/briandconnelly/pontonier) v0.9.0, and amicus no longer depends on pontonier (ADR 0029).
+ADR 0030 holds it to that role, so what only the server uses lives in the amicus package that owns it: the job store is `amicus.jobs`, worktrees and diff gathering are `amicus.orchestration`, and the fingerprint mechanics are `amicus.schemas.fingerprint`.
 Import boundaries between layers are enforced by the import-linter contracts in `pyproject.toml`.
-A backend's own prompt carriers (for Codex, the developer-instructions argv token and the stdin prompt) are disclosed on `amicus_backends`.
+A backend's own prompt carriers (for Codex, the developer-instructions argv token and the stdin prompt; for Kimi, the handshake file and the CLI's own session store) are disclosed on `amicus_backends`.
+Rule 18's exemption is bounded by evidence rather than by proof, because whether a closed-source CLI offers an alternative cannot be proven, only looked for: the condition is that none was found, documented or observed, and the looking is repeated before every amicus release, on the exact CLI versions the rule-20 evidence run uses.
+It is tied to the release rather than to a change in a backend's supported-version set because that set is coarse: a kimi patch release still parses as its minor, and every claude 2.x release is covered by major 2, so a new CLI release can become supported without the set ever changing.
+Kimi's handshake file exists because kimi ignores stdin.
+Codex's argv token exists because `codex exec --help` (0.155.1) offers the prompt, on stdin, and no flag for developer-role instructions, which leaves the `developer_instructions` config value, set with `-c` on argv or from a config file; argv is the one that leaves nothing on disk.
+Kimi's session store is different in kind: the CLI rather than amicus writes it, it outlives the run, and amicus does not delete it; the 0.43.1 probe that found no way to switch it off, and what that probe did not test, are recorded in `docs/kimi-help/0.43.1/FINDINGS.md`.
 
 ### The gate
 
@@ -76,12 +86,14 @@ The README's "Where things are" table indexes the rest.
 
 ### Releases
 
-`.mcp.json` pins `git+https://github.com/briandconnelly/amicus.git@v{version}`, and that pin is what a fresh plugin install actually fetches: users add this repository as a marketplace, so the manifest they read is the one on `main`.
-Rule 24 therefore keeps it naming a release that is already published rather than the one being released.
-A manifest on `main` cannot name an artifact that only exists after `main` has moved, and pinning the version under release meant every release broke a fresh install for the interval between the release merge and the tag push.
-Rule 24 removes that interval rather than shortening it.
-Two facts decided the shape, and both were established by probe rather than argued: a commit SHA resolves over the same git transport a tag does, so the install path can be rehearsed before any tag exists; and `uvx` reuses a cached tool environment without querying any index, so the version in the requirement string is what makes an existing user pick up a new release — which is why an unpinned source was rejected rather than adopted.
-0.1.0 was the bootstrap, tagged and published on 2026-09-09; it named the tag it created because no earlier release existed, and that case cannot recur.
+Users add this repository as a plugin marketplace, and a host copies the plugin into a directory keyed by `plugin.json`'s version, re-reading it only when that version changes.
+ADR 0031 is shaped by that fact, established by probe on Claude Code and Codex, and it supersedes ADR 0015, which had assumed a host re-reads `.mcp.json`.
+Under ADR 0015 the pin trailed the release, so an install taken before the pin-move PR, or anywhere mid-cycle, kept running an older server than its own skills (issue #117).
+So `.mcp.json` names its own release, and from 0.4.0 the marketplace entry pins a published tag by `ref` and `sha`, so hosts install that self-consistent tag snapshot rather than `main`.
+Until the 0.4.0 pointer PR merges, the entry is still `"./"` and hosts install `main`, which is why rule 24 bars anything else from merging during that one transition.
+Rule 24's invariant, that the pointer users follow names an already-published release, moved with it from `.mcp.json` to the marketplace entry.
+`sha` is required because a host serves `sha` over a disagreeing `ref` without complaint, and the `v*` ruleset's admin bypass means a tag can be moved.
+`uvx` reuses a cached tool environment without querying any index, so the version in `.mcp.json`'s requirement string is still what makes an existing install pick up a new server.
 Rule 20 is a local pre-tag gate rather than a CI job: hosted runners have no authenticated `codex`, `kimi` or `claude`, so the evidence is recorded on the maintainer's machine against the exact commit to be tagged.
 That evidence is an honest-mistake guard, not an attestation; it is a local file its author can write by hand.
 Rule 21 covers creation as well as update and deletion because pushing a `v*` tag is by itself what triggers `.github/workflows/publish.yml`: an identity that can create one can publish a release without rules 19 and 20 ever being satisfied, and a moved tag silently changes what users install under a version they already trust.
@@ -101,6 +113,7 @@ Those are held by the platform controls around the release — rule 21's ruleset
 ### Siblings
 
 The sibling checkouts named in rule 17 are read for porting, and their virtualenvs are used to capture differential fixtures (`scripts/capture_codex_differentials.py` runs inside codex-in-claude's).
+`~/projects/pontonier` is a sibling in the same sense: amicus no longer depends on it, its `v0.9.0` tag is where `amicus.sdk` came from, and it stays published only for the three older siblings until they are archived (ADR 0029).
 
 ### Local hooks
 

{amicus-0.3.0 → amicus-0.5.0}/CHANGELOG.md

@@ -20,6 +20,308 @@ per-change, as its own lead says.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-20
+
+Across this release the discovery surface moves `amicus/0.1/schema-35`, what 0.4.0 shipped, to
+`amicus/0.1/schema-39`, and stored job results move `RESULT_FORMAT` 7 to 9, so a job result 0.4.0
+stored cannot be delivered after upgrading. The entries labelled **Breaking** are the changes a
+caller or operator using 0.4.0 has to handle, and `docs/MIGRATION.md` ("Upgrading from 0.4.0")
+walks through each. It was checked against codex-cli 0.155, Kimi Code 2.0 and Claude Code 2.1.278.
+
+### Changed
+
+- Kimi Code 2.0 is a supported version, so `amicus_backends` no longer warns on it. Kimi Code
+  went from 0.43.1 to 2.0.2 in one upgrade; amicus has seen no 1.x and claims none. It was
+  checked against the 0.43.1 capture at zero spend: `--help` differs by one new subcommand and no
+  option, the `provider list --json` shape is identical, and `kimi session` still offers `list`
+  only and still reads the existing session store, so no new way to avoid that carrier was
+  found. The kimi live suite then passed on 2.0.2, which exercises consult, the read-only tool
+  profile, review and delegate; whether 2.0.2 still writes to the session store was not looked
+  at in that run (#202).
+- Releasing now checks the backend CLIs first. `docs/RELEASING.md` gains a precondition, run
+  immediately before the release evidence: bring `codex`, `kimi` and `claude` to their latest
+  releases, run the new zero-spend `scripts/check_backend_compat.py` (installed and latest
+  version, the warnings `amicus_backends` would raise, and the flags each `--help` declares
+  against the newest committed capture), and do the AGENTS.md rule-18 carrier re-check by
+  reading, which no script can. Codex gains its first committed help capture (0.155.1), held
+  to the flags amicus always sends as Kimi's and Claude's already were, and Claude gains one for
+  2.1.278. Nothing about how amicus runs changes (#188).
+- codex-cli 0.155 is a supported version, so `amicus_backends` no longer warns on it. It was
+  checked against 0.154.0 at zero spend: `--help`, `exec --help`, `exec review --help` and
+  `login --help` are byte-identical, the unknown-feature error and the logged-out `login status`
+  line are unchanged, both features amicus disables on every run are still `stable`, the cached
+  model list is the same seven slugs in the same order, the tool list sent to `gpt-5.5` is
+  identical with and without those disables, and the four config keys amicus pins with `-c` are
+  accepted under `--strict-config` while an unknown key is still rejected in the form amicus
+  parses. No paid call was part of the check (#187).
+
+### Removed
+
+- **Breaking.** `amicus_dry_run`, the deprecated alias of `amicus_review_changes_dry_run`, is
+  removed. It was deprecated in 0.3.0 (#98) with a marker in its lifecycle `_meta`, on its
+  `amicus_capabilities` row and at the head of its description, each naming 0.5.0, and ADR 0028
+  removes a tool at the end of its window. Call `amicus_review_changes_dry_run` with the same
+  arguments. The server now lists 18 tools, and no tool carries a deprecation marker; the
+  mechanism and `amicus_capabilities.deprecation_policy` stay (#204).
+
+### Fixed
+
+- **Surface.** A replayed keyed `_async` call can hand back a job that is already terminal, and
+  its handle's `follow_up` still said `poll_job_status` / `amicus_job_status`, which the skill's
+  own rules forbid for a finished job. A terminal handle now carries `next_step:
+  fetch_job_result` and `tool: amicus_job_result` with the same `job_id` and `workspace_root`; a
+  running handle is unchanged. The two are separate correlated shapes in the output schema, so
+  no mismatched step/tool pair is admitted. `fetch_job_result` is a new `repair.next_step`
+  value. A caller that went by `status`, as the 0.4.0 descriptions told it to, changes nothing
+  (#103).
+- **Surface.** The `idempotency_key` parameter description said the key is scoped to "this tool
+  + backend + workspace", which reads as though the same key on another backend were a separate
+  identity. It never was: the key is scoped to the tool and the workspace, and `backend` is one
+  of the arguments that must match, so that call is an `idempotency_conflict`. The description
+  now says so; behaviour is unchanged (#178).
+- **Breaking.** An answer file amicus refuses to read is no longer delivered as an empty answer.
+  The bounded reader accepts only a regular file within 1,000,000 bytes (ADR 0009), and a file
+  it refused was indistinguishable from a backend that wrote nothing: a Codex review came back
+  `invalid_json`, and a Codex consult came back `ok: true` with "(the backend returned no
+  message)". Both are now the new error `answer_unavailable`, with `error.details.reason` one of
+  `artifact_oversize` (carrying `limit_bytes` and, when known, `actual_bytes`),
+  `artifact_not_regular` or `artifact_unreadable`, never the path. It is temporary only for an
+  unreadable file whose cause passes (descriptor or memory exhaustion); oversize repairs with
+  `reduce_input`. Every other failure is still reported as itself, a refusal
+  standing in only for a clean exit diagnosed as empty. A Kimi run whose stream carried the
+  answer, captured whole, is delivered with a `meta.security_warnings` entry. A delegate with no
+  such answer keeps its captured diff, with amicus's own summary saying the backend's could not
+  be read and `raw_response.text` left null. An absent or empty file is unchanged: that is the
+  backend saying nothing. The reader also now reads to the end of the file, where one short
+  `read` could have delivered a prefix as the whole answer. The new error code is one of the two changes that move
+  `RESULT_FORMAT` in this release, since an older reader's closed set of codes rejects it (#162).
+- **Breaking.** A finding that cited one of amicus's own temporary files no longer carries it.
+  Kimi is handed its prompt as a file, so a finding could come back with `file` set to
+  `<tmp>/amicus-kimi-handshake-…/prompt.md` and `line` set to an offset into amicus's framing:
+  a path deleted before the result is read, and a line into nothing the caller supplied. Every
+  reference to a run's own staged files is now replaced by `[amicus temporary file]`, in the
+  summary, the prose lists, a finding's text and `raw_response.text`, before the result is
+  built or stored; a `file` that named one is null together with its `line`; and
+  `findings_diagnostics.reasons` reports `backend_artifact_reference_removed` at `dropped: 0`.
+  It never moves a verdict, and a failed run's error message is scrubbed the same way. Only the
+  run's own staged paths match, the files it listed and anything under Kimi's per-run handshake
+  directory, at path boundaries, so a workspace file that merely looks like one is untouched.
+  A JSON answer is judged by what it decodes to, object keys included, whatever spelling it
+  used; an answer that is prose around a JSON fragment is never decoded, so there the `\/` and
+  `\u002f` spellings of a separator are recognised and a path spelled wholly in `\uXXXX` is
+  not (#207). The new reason is the other change that moves `RESULT_FORMAT`, so a job result
+  0.4.0 stored is `job_result_incompatible` after upgrading: fetch it first
+  (`docs/MIGRATION.md`, "Upgrading from 0.4.0") (#140).
+
+- The codex live gate, whose passing run is part of the evidence a release is tagged on, could
+  pass on a codex version amicus had never checked: it asserted only the `codex-cli` prefix, as
+  0.3.0's run on 0.154.0 showed. It now requires the installed minor to be in the built-in
+  `SUPPORTED_VERSIONS` and `amicus_backends` to report no warnings, so neither an ambient
+  `AMICUS_CODEX_SUPPORTED_VERSIONS` nor an unparseable version string can vouch for one (#113).
+- Kimi's `carriers` disclosure on `amicus_backends(detail="full")` now names the kimi CLI's own
+  session store (observed under `~/.kimi-code/sessions`), whose files can hold the whole prompt and
+  any answer produced. amicus does not delete it, and `AMICUS_JOB_TTL`, the per-workspace cap and
+  `amicus_job_consume_result` never reach it. Kimi's `readonly_honesty` no longer says Kimi
+  "cannot MODIFY anything": read-only removes the agent's shell and write tools, not the CLI's
+  own session files. Nothing about what is written changed; only what is said about it (#179).
+- A relative `AMICUS_STATE_DIR`, `AMICUS_CODEX_BIN`, `AMICUS_KIMI_BIN` or `AMICUS_CLAUDE_BIN` is
+  now refused instead of being resolved against the process's working directory. The server and
+  each job worker resolve configuration separately, and a worker runs from its job directory, so
+  a relative value named one place to the server and another to the worker. With a relative
+  state directory the server now refuses to start, naming the variable on stderr: falling back
+  to the default would keep whole answers somewhere the operator did not choose. A relative
+  binary override makes that backend report the override as unusable, as a missing file already
+  did. Absolute values are unchanged, and so is a leading `~` in `AMICUS_STATE_DIR`, which is
+  still expanded. `$XDG_CACHE_HOME` is different: a value that is not absolute as written,
+  `~/cache` included, is ignored and never expanded, as the XDG Base Directory specification
+  requires (#173).
+- `config.settings()` no longer documents itself as never raising: it never raises on a
+  malformed or conflicting setting, and an unresolvable home directory is a startup failure
+  (#147).
+
+## [0.4.0] - 2026-09-18
+
+Across this release the discovery surface moves `amicus/0.1/schema-30`, what 0.3.0 shipped, to
+`amicus/0.1/schema-35`, and stored job results move `RESULT_FORMAT` 6 to 7, so a job result 0.3.0
+stored cannot be delivered after upgrading. The entries labelled **Breaking** are the changes a
+caller or operator using 0.3.0 has to handle, and `docs/MIGRATION.md` ("Upgrading from 0.3.0")
+walks through each.
+
+### Added
+
+- The `collaborating-with-amicus` skill gains a blind-comparison workflow
+  (`references/blind-comparison.md`): two or more finalized candidates, compared by a backend
+  that wrote none of them, blinded, against criteria fixed before the call, returning
+  per-criterion reasons and one preference the host verifies as a finding rather than a score it
+  adopts. A new root rule says a backend's stated preference never stands in for the decision.
+  No tool or server surface changes and `FINGERPRINT` does not move.
+
+### Changed
+
+- Every paid tool, sync and async, and the `detail` parameter now disclose that the job record
+  keeps the backend's whole answer whatever `detail` delivered it, that the answer can quote the
+  caller's inputs, and what ends it: expiry under `AMICUS_JOB_TTL` (an expired record is removed
+  on a later job call, not by a daemon), the per-workspace cap or `amicus_job_consume_result`
+  (#163, ADR 0035). Nothing stored or delivered changes: the record has kept the answer since M2,
+  and the decision recorded is that rule 18 binds the inputs amicus writes, not the answer a
+  backend returns. **Surface**: `FINGERPRINT` moves to schema-35 for the description text.
+- amicus no longer depends on `pontonier`. Its backend SDK is now part of amicus, as
+  `amicus.sdk` (#13, ADR 0029): the same code as pontonier 0.9.0, copied from its `v0.9.0`
+  tag with the imports rewritten. Nothing on the wire or in a stored job result changes, and
+  `FINGERPRINT` does not move. A third-party backend distribution imports the SDK types from
+  `amicus.sdk` instead of `pontonier` and declares plugin API version 2: `PLUGIN_API_VERSION`
+  moved from 1 to 2, so the registry rejects a plugin that pins `api_version=1` (#115 covers
+  one that leaves it unset). No release can enable a third-party backend yet, so no running
+  deployment is affected. SDK log records are no longer named `pontonier.*` in stderr and
+  `AMICUS_LOG_FILE`, since the log format prints the logger name, which matters for an
+  operator who filters logs by name: they are named `amicus.sdk.*`, except the job store and
+  its idempotency index, which are `amicus.jobs.store` and `amicus.jobs.idempotency`. These
+  `amicus.sdk` import paths are not yet stable for a third-party backend. ADR 0030 settles
+  where they end up, and this release leaves that move finished (#118–#123): `amicus.sdk`
+  holds what a backend imports — the backend protocol and contract, the error vocabulary,
+  annotations and preflight, the subprocess runtime, stream capping, redaction, path-alias
+  sanitizing and a bounded JSON reader — plus the conformance kit, which is the one thing
+  there that a backend does not import: the registry imports it and runs it against a plugin
+  before it will use one. The job store, the git layer, the fingerprint mechanics and the
+  prompt framings live in the amicus package that owns each. Of the pontonier-named literals
+  the copy brought with it, one was visible outside the code: the throwaway directory amicus
+  creates to run git with its hooks disabled is now named `amicus-nohooks-*` under the system
+  temp dir, not `pontonier-nohooks-*`. Nothing keys on that name.
+
+### Removed
+
+- **Breaking.** The three siblings' environment names — `CODEX_IN_CLAUDE_*`, `MOONBRIDGE_*`
+  and `CLAUDE_IN_CODEX_*` — are no longer read (#176), as 0.3.0's warnings and
+  `docs/MIGRATION.md` said they would not be from 0.4.0. An operator who still sets one gets
+  the `AMICUS_*` default instead of the value, which for `CODEX_IN_CLAUDE_ISOLATION` or
+  `CLAUDE_IN_CODEX_CLAUDE_CONFIG` is looser than what was set. Each former name is now a
+  tombstone on the `AMICUS_*` declaration that replaced it: a name still set is reported by
+  `amicus_backends`, in `env_warnings` for a global setting and in the backend's
+  `status.warnings` for a backend one (so only while that backend is enabled and loaded),
+  naming the `AMICUS_*` name to set; its value is never read, not even to recognise a
+  placeholder, so it neither supplies the setting nor conflicts with the `AMICUS_*` value,
+  and the conflict error of the window is gone with it. The tombstones have no removal window: they
+  are the migration table's data and a diagnostic, not a compatibility path. The shim itself
+  (`EnvVar.legacy`) and the release guard that refuses a release at or past
+  `LEGACY_REMOVAL_VERSION` while an alias is declared both stay, so a later rename gets the
+  same window. `FINGERPRINT` moves to `schema-34` only because the `amicus_backends`
+  description no longer says "legacy-env warnings"; no schema changes.
+
+### Fixed
+
+- **Surface.** A Claude budget stop no longer reports `input_tokens: 0` and
+  `output_tokens: 0` beside a nonzero `cost_usd` (#158). claude prints its top-level `usage`
+  block zeroed on that envelope while `modelUsage` carries the real counts, and its own
+  result schema names `modelUsage` as the accounting field, so `meta.usage` now comes from
+  `modelUsage` (summed across models) whenever at least one of its entries is an object,
+  and from the top-level block only when none is (ADR 0034). A field is read from one
+  block, never both: once `modelUsage` is in use, a field any one entry leaves out is
+  `null`, and a non-object entry beside an object one makes every count `null`. So an older
+  envelope whose `modelUsage` has no cache keys now reports `cached_input_tokens` and
+  `cache_creation_input_tokens` as `null` where it used to copy the block's numbers.
+  `budget_exceeded`'s message and repair, the `max_budget_usd` option description and the
+  `AMICUS_CLAUDE_MAX_BUDGET_USD` description now say claude checks the threshold only
+  between model calls, so one call can carry the estimated cost past it; none states an
+  overshoot bound, and the repair no longer suggests a 0.10-0.20 floor it had no evidence
+  for. The recorded 2.1.274 budget-stop envelope is `tests/fixtures/claude_budget_stop_envelope.json`,
+  documented in `docs/claude-help/2.1.274/`. `RESULT_FORMAT` does not move.
+
+- Every tool that resolves a workspace no longer fails as a retryable `internal_error`
+  (`FileNotFoundError`) when the server process's working directory has been deleted under
+  it, as happens when the Claude Code worktree the server was started in is removed (#170).
+  The resolver now reads the process cwd only on the one branch where it decides the
+  outcome (no `workspace_root`, no client root, and `AMICUS_ALLOW_CWD_WORKSPACE=1`), so a
+  call that names its workspace never consults it. When that branch is reached and the cwd
+  is gone, the call fails as a non-temporary `invalid_workspace_root` whose message says to
+  pass `workspace_root`, configure an MCP root, or restart the server from an existing
+  directory, instead of a `retry_then_report` repair that could never succeed. No error
+  code was added and `FINGERPRINT` does not move.
+
+- Codex usage-limit failures without a parseable relative delay now report
+  `retry_after_ms: null` with an `inspect_and_retry` repair instead of inventing a
+  60-second delay for a reset that may be days away (#165). When codex states the reset
+  as a clock time (`try again at Sep 19th, 2026 8:37 AM.` or `try again at 12:39 PM.`),
+  that phrase is echoed in `error.message`, `error.details.reason` and the repair, marked
+  as a clock time with no time zone stated when it names none, so the caller can read the
+  reset it must wait for. Only a clock-time shape is echoed; other wording gets the generic
+  guidance. Explicit relative delays and the 60-second fallback for ordinary rate limits are
+  unchanged.
+
+- Codex failure classification now reads backend error events and stderr instead of
+  matching authentication, contract-drift and rate-limit terms in model answers or tool
+  output (#166). Model prose can no longer override the backend's diagnosis or retry delay.
+  Generic failure details also exclude model and tool items, preventing that text from
+  being copied into a background job's stored error.
+  Plain-text startup diagnostics and error events containing only an HTTP status remain
+  supported. Neither `FINGERPRINT` nor `RESULT_FORMAT` moves.
+
+- `amicus_backends` no longer reports `authenticated: false` whenever the Codex login-status
+  probe exits nonzero (#169). Only a recognized authentication failure reports `false`; a
+  configuration error or other probe failure reports `authenticated: null` and adds a sanitized
+  diagnostic to the backend's warnings. `FINGERPRINT` does not move.
+
+- **Surface.** `amicus_review_changes` on the `claude` backend now defaults to
+  `backend_options.access = "readonly"` (#116, ADR 0032). On the previous `toolless` default a
+  review had no tool to read the code it was judging, and answered with tool-call markup
+  instead of the review: amicus reported `invalid_json`, or under the default
+  `config_mode = "inherit"` ran to the budget stop. A Claude review that omits `access` can now
+  read files with `Read`, `Grep` and `Glob`, inside and outside the workspace, which bypasses
+  diff redaction; pass `access: "toolless"` to keep the old behaviour for one call.
+  `amicus_consult` and `amicus_adversarial_review` still default to `toolless`, and setting
+  `AMICUS_CLAUDE_ACCESS` sets the default for every verb, reviews included. A structured Claude
+  review also now carries the output guardrails adversarial reviews already had, telling the
+  model never to simulate a tool call. `amicus_backends` reports `access` under
+  `default_by_verb`. `FINGERPRINT` moves to `amicus/0.1/schema-31`.
+- **Breaking.** A review whose answer amicus cannot read as one JSON object is no longer
+  discarded (#139, ADR 0033). `amicus_review_changes` and `amicus_adversarial_review` used to
+  return `invalid_json` or `schema_violation`. They kept a 300-character preview of the answer,
+  lost the rest, and prescribed a retry that could fail the same way. They now return
+  `ok: true` with the new `review_status: unstructured`: `verdict` and `confidence` are
+  `unknown`, `findings` and the prose lists are empty with diagnostics saying nothing was
+  parsed, and the whole answer, redacted, is `raw_response.text`, at `detail="full"` on the call
+  or free from `amicus_job_result`. A caller that read the verdict after checking `ok` must now
+  handle this value. An answer that wraps exactly one object in a preamble, a fence or a
+  sign-off is now read as that object. A repeated key is still refused (#51). Only an empty
+  answer is still an error (`invalid_json`, or `empty_response` on Kimi), and
+  `schema_violation` is no longer a review outcome. `empty_response`, which Kimi already
+  returned for an empty answer, is now listed in the `error_codes` of every paid tool that can
+  select Kimi.
+  `RESULT_FORMAT` moves to 7 and `FINGERPRINT` to `amicus/0.1/schema-32`.
+
+- A plugin install no longer runs an older release's server than its bundled skills (#117,
+  ADR 0031, superseding ADR 0015). Hosts key an installed plugin by `plugin.json`'s version and
+  do not re-read it until that version changes, so a plugin whose `.mcp.json` named the previous
+  release kept launching that older server. `.mcp.json` now names its own release, and after
+  0.4.0 is published the marketplace entry pins that tag by `ref` and `sha`, so the installed
+  skills and server come from one release snapshot. Installs already stuck on an older server
+  recover when the 0.4.0 version change reaches them.
+
+- **Security.** An exception's own text can no longer reach a background job's `stderr.log`
+  (#128). The job worker never called `obs.configure`, so nothing in that process installed
+  the handlers that withhold exception text, and an `amicus.*` record fell through to
+  `logging.lastResort` — which renders the exception's `str()` and a full traceback. The
+  worker's stdout and stderr are both `<job_dir>/stderr.log`, so that text was written to a
+  file the job keeps. The reachable call site is the SDK runtime's
+  `logger.error("stdout capture failed: %s", exc, exc_info=True)` on a capture failure, and
+  an exception raised inside a backend adapter can embed the prompt text that provoked it,
+  which AGENTS.md rule 18 forbids writing to a log. `_worker.main` now configures logging
+  before anything else it does, so such a record renders as the exception's type and its
+  frame locations, the same policy the server has always applied. The worker inherits the
+  server's environment, so it honours the same `AMICUS_LOG_LEVEL` and `AMICUS_LOG_FILE` —
+  except a *relative* `AMICUS_LOG_FILE`, which it drops: `logging.FileHandler` resolves a
+  relative path against the process's cwd, and the worker's cwd is the job directory, so
+  honouring it would leave a differently-located log file inside every job directory instead
+  of adding to the one file the operator asked for. An absolute path is honoured, and the
+  server's own handler is unaffected either way. Nothing about a job's result, status or
+  wire shape changes, and `FINGERPRINT` does not move.
+- A `codex` run that hit its usage limit could fail as `backend_auth_required` instead of
+  `backend_rate_limited` (#160). The classifier checks authentication first and matched the bare
+  substring `401`, so any output carrying those digits, such as a token count of 14012, read as
+  "not authenticated". The repair then told the caller to log in again, and marked the failure
+  not temporary. A `401` now counts only as an HTTP status, and codex's own "could not be
+  refreshed" token failures are recognized as authentication failures. `FINGERPRINT` does not
+  move.
+
 ## [0.3.0] - 2026-09-15
 
 Across this release the discovery surface moves `amicus/0.1/schema-13`, what 0.2.0 shipped, to
@@ -532,7 +834,9 @@ per-change rather than net, so they also name intermediate states that no releas
 - The tagged publish path to pypi.org has never run. Only the TestPyPI dispatch path has been exercised.
 - Eval scenario S6 in `skills/collaborating-with-amicus/tests/scenarios.md` passed on one run (status: `pass`, validated by that run alone); an M7 follow-up run against the current skill text did not isolate the still-open F3 finding, so F3 remains open. S7 (real-host approval friction) has failed both of its recorded runs (status: `fail`); an M7 zero-spend recheck reached neither a pass nor a fail and is recorded as inconclusive, so it does not move S7's status. See their `status` fields and ADR 0012.
 
-[Unreleased]: https://github.com/briandconnelly/amicus/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/briandconnelly/amicus/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/briandconnelly/amicus/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/briandconnelly/amicus/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/briandconnelly/amicus/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/briandconnelly/amicus/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/briandconnelly/amicus/releases/tag/v0.1.0