amicus 0.4.0__tar.gz → 0.5.0__tar.gz

{amicus-0.4.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.4.0 → amicus-0.5.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.4.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.4.0 → amicus-0.5.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.4.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.4.0 → amicus-0.5.0}/.mcp.json

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

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

@@ -29,7 +29,7 @@ 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 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.
@@ -63,7 +63,12 @@ The package is `amicus` under `src/`; each backend is a plugin under `src/amicus
 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
 

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

@@ -20,6 +20,125 @@ 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
@@ -715,7 +834,8 @@ 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.4.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

{amicus-0.4.0 → amicus-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: amicus
-Version: 0.4.0
+Version: 0.5.0
 Summary: One MCP server for every second-opinion model: consult, review, and delegate with the backend as a parameter
 Project-URL: Homepage, https://github.com/briandconnelly/amicus
 Project-URL: Repository, https://github.com/briandconnelly/amicus
@@ -73,7 +73,7 @@ The plugins launch the server from a published release tag, pinned in
   "mcpServers": {
     "amicus": {
       "command": "uvx",
-      "args": ["--from", "git+https://github.com/briandconnelly/amicus.git@v0.4.0", "amicus-mcp"]
+      "args": ["--from", "git+https://github.com/briandconnelly/amicus.git@v0.5.0", "amicus-mcp"]
     }
   }
 }
@@ -114,7 +114,7 @@ anything.
 
 ## The tools
 
-Nineteen tools, in five groups, one of them a deprecated alias. Discovery, previews and job
+Eighteen tools, in five groups. Discovery, previews and job
 management are free; the verbs and their background twins invoke the selected backend and spend
 its quota.
 
@@ -122,7 +122,7 @@ its quota.
 | --- | --- |
 | Discovery — free | `amicus_backends`, `amicus_capabilities`, `amicus_models` |
 | Verbs — paid | `amicus_consult`, `amicus_review_changes`, `amicus_delegate`, `amicus_adversarial_review` |
-| Previews — free | `amicus_review_changes_dry_run` (review), `amicus_delegate_dry_run`; `amicus_dry_run` is the review preview's deprecated alias, removed at or after 0.5.0 |
+| Previews — free | `amicus_review_changes_dry_run` (review), `amicus_delegate_dry_run` |
 | Background twins — paid | the four verbs again, each with an `_async` suffix |
 | Jobs — free | `amicus_job_status`, `amicus_job_result`, `amicus_job_consume_result`, `amicus_job_list`, `amicus_job_cancel` |
 
@@ -157,6 +157,10 @@ the backend and the feature, rather than failing obscurely.
   (`AMICUS_JOB_TTL`, default 24h; an expired record is removed on a later job call, not by a
   daemon), the per-workspace cap evicts it or `amicus_job_consume_result` removes it. It can
   quote what you sent. Your inputs themselves are never written there ([ADR 0035](docs/adr/0035-a-backend-answer-is-kept-on-the-job-record.md)).
+- **Kimi keeps its own copy.** The kimi CLI writes its own session files (observed under
+  `~/.kimi-code/sessions`), which can hold the whole prompt and any answer produced. amicus found
+  no documented way to switch that off and does not delete them, and none of the retention controls above reach it; Codex and Claude
+  run with their session persistence disabled.
 
 ## Configuration
 
@@ -177,12 +181,13 @@ the new ones.
 
 ## Status and known limits
 
-0.4.0 is the current release, and it is a breaking one: sibling environment names are no longer
-read, and an unreadable review is now delivered as `review_status: unstructured` instead of an
-error. The discovery surface moved from `amicus/0.1/schema-30` to `amicus/0.1/schema-35` and stored
-job results from `RESULT_FORMAT` 6 to `7`, so a job result 0.3.0 stored cannot be read after
-upgrading. [`docs/MIGRATION.md`](docs/MIGRATION.md#upgrading-from-030) explains how to upgrade,
-and [`CHANGELOG.md`](CHANGELOG.md) lists every user-visible change.
+0.5.0 is the current release, and it is a breaking one: the deprecated `amicus_dry_run` alias is
+gone, an answer file amicus refuses to read is now the error `answer_unavailable` rather than an
+empty answer, and a finding that cited one of amicus's own temporary files no longer carries that
+path. The discovery surface moved from `amicus/0.1/schema-35` to `amicus/0.1/schema-39` and stored job results from `RESULT_FORMAT` 7 to
+`9`, so a job result 0.4.0 stored cannot be read after upgrading.
+[`docs/MIGRATION.md`](docs/MIGRATION.md#upgrading-from-040) explains how to upgrade, and
+[`CHANGELOG.md`](CHANGELOG.md) lists every user-visible change.
 
 One known limit: a third-party backend distribution can load through the `amicus.backends`
 entry-point group, but cannot yet be enabled or called. `AMICUS_BACKENDS` and the `backend`

{amicus-0.4.0 → amicus-0.5.0}/README.md

@@ -44,7 +44,7 @@ The plugins launch the server from a published release tag, pinned in
   "mcpServers": {
     "amicus": {
       "command": "uvx",
-      "args": ["--from", "git+https://github.com/briandconnelly/amicus.git@v0.4.0", "amicus-mcp"]
+      "args": ["--from", "git+https://github.com/briandconnelly/amicus.git@v0.5.0", "amicus-mcp"]
     }
   }
 }
@@ -85,7 +85,7 @@ anything.
 
 ## The tools
 
-Nineteen tools, in five groups, one of them a deprecated alias. Discovery, previews and job
+Eighteen tools, in five groups. Discovery, previews and job
 management are free; the verbs and their background twins invoke the selected backend and spend
 its quota.
 
@@ -93,7 +93,7 @@ its quota.
 | --- | --- |
 | Discovery — free | `amicus_backends`, `amicus_capabilities`, `amicus_models` |
 | Verbs — paid | `amicus_consult`, `amicus_review_changes`, `amicus_delegate`, `amicus_adversarial_review` |
-| Previews — free | `amicus_review_changes_dry_run` (review), `amicus_delegate_dry_run`; `amicus_dry_run` is the review preview's deprecated alias, removed at or after 0.5.0 |
+| Previews — free | `amicus_review_changes_dry_run` (review), `amicus_delegate_dry_run` |
 | Background twins — paid | the four verbs again, each with an `_async` suffix |
 | Jobs — free | `amicus_job_status`, `amicus_job_result`, `amicus_job_consume_result`, `amicus_job_list`, `amicus_job_cancel` |
 
@@ -128,6 +128,10 @@ the backend and the feature, rather than failing obscurely.
   (`AMICUS_JOB_TTL`, default 24h; an expired record is removed on a later job call, not by a
   daemon), the per-workspace cap evicts it or `amicus_job_consume_result` removes it. It can
   quote what you sent. Your inputs themselves are never written there ([ADR 0035](docs/adr/0035-a-backend-answer-is-kept-on-the-job-record.md)).
+- **Kimi keeps its own copy.** The kimi CLI writes its own session files (observed under
+  `~/.kimi-code/sessions`), which can hold the whole prompt and any answer produced. amicus found
+  no documented way to switch that off and does not delete them, and none of the retention controls above reach it; Codex and Claude
+  run with their session persistence disabled.
 
 ## Configuration
 
@@ -148,12 +152,13 @@ the new ones.
 
 ## Status and known limits
 
-0.4.0 is the current release, and it is a breaking one: sibling environment names are no longer
-read, and an unreadable review is now delivered as `review_status: unstructured` instead of an
-error. The discovery surface moved from `amicus/0.1/schema-30` to `amicus/0.1/schema-35` and stored
-job results from `RESULT_FORMAT` 6 to `7`, so a job result 0.3.0 stored cannot be read after
-upgrading. [`docs/MIGRATION.md`](docs/MIGRATION.md#upgrading-from-030) explains how to upgrade,
-and [`CHANGELOG.md`](CHANGELOG.md) lists every user-visible change.
+0.5.0 is the current release, and it is a breaking one: the deprecated `amicus_dry_run` alias is
+gone, an answer file amicus refuses to read is now the error `answer_unavailable` rather than an
+empty answer, and a finding that cited one of amicus's own temporary files no longer carries that
+path. The discovery surface moved from `amicus/0.1/schema-35` to `amicus/0.1/schema-39` and stored job results from `RESULT_FORMAT` 7 to
+`9`, so a job result 0.4.0 stored cannot be read after upgrading.
+[`docs/MIGRATION.md`](docs/MIGRATION.md#upgrading-from-040) explains how to upgrade, and
+[`CHANGELOG.md`](CHANGELOG.md) lists every user-visible change.
 
 One known limit: a third-party backend distribution can load through the `amicus.backends`
 entry-point group, but cannot yet be enabled or called. `AMICUS_BACKENDS` and the `backend`

{amicus-0.4.0 → amicus-0.5.0}/docs/MIGRATION.md

@@ -130,7 +130,7 @@ Most amicus tools take `backend` as a required parameter (no default); pick `"co
 ## Behavior deltas
 
 `amicus_dry_run` was renamed `amicus_review_changes_dry_run` (#98), and the sibling maps above point at the new name.
-The old name still works as a deprecated alias until 0.5.0, with the same arguments and the same result, whose `tool` stays `amicus_dry_run`.
+The old name worked as a deprecated alias in 0.3.x and 0.4.x, and 0.5.0 removed it at the end of that window (#204); the new name takes the same arguments.
 Call the new name in anything you write now.
 
 Review results and `amicus_review_changes_dry_run` carry a top-level `coverage` object, in the shape `codex_review_changes` returns (#65).
@@ -193,6 +193,33 @@ A `null` there means no loaded plugin declares one.
 The `amicus://backends/{backend}` resource is always the full entry.
 `amicus_capabilities(detail="contracts")` is removed: pass `include_tool_details=false` for the same rowless payload, and `detail` now selects only how much each `tool_details` row carries (`summary` is `name`, `cost`, `stability`, `backends`; `full` adds the rest, including `error_codes`).
 
+## Upgrading from 0.4.0
+
+The changes below are the ones an operator or caller using amicus 0.4.0 has to handle before running 0.5.0.
+`CHANGELOG.md`'s 0.5.0 section lists every user-visible change since 0.4.0, including the ones that require no migration.
+
+**A job result stored by 0.4.0 is no longer readable (#140, #162).**
+`RESULT_FORMAT` moved from 7 to 9: to 8 because `findings_diagnostics.reasons` gained `backend_artifact_reference_removed`, and to 9 because `error.code` gained `answer_unavailable`, each a value a 0.4.0 reader's closed enum rejects.
+`amicus_job_result` and `amicus_job_consume_result` return `job_result_incompatible` for a record 0.4.0 wrote.
+Fetch or consume any stored result you still need before upgrading; the record itself stays until `AMICUS_JOB_TTL` or the per-workspace cap evicts it.
+
+**A finding that cited one of amicus's own temporary files no longer carries it (#140).**
+On Kimi, which is handed its prompt as a file, a finding could come back with `file` set to that temporary path and `line` set to an offset into amicus's framing.
+Such a `file` is now null together with its `line`, the path is replaced by `[amicus temporary file]` wherever the answer's text named it, and `findings_diagnostics.reasons` says `backend_artifact_reference_removed` at `dropped: 0`.
+A caller that treated any non-null `findings_diagnostics` as loss should read the reason: this one loses nothing a caller could have opened.
+
+**`amicus_dry_run` is gone (#204).**
+It was the deprecated alias of `amicus_review_changes_dry_run` since 0.3.0 (#98), with a marker in its lifecycle `_meta` and on its `amicus_capabilities` row naming 0.5.0 as its removal, and ADR 0028 removes a tool at that release.
+Call `amicus_review_changes_dry_run` with the same arguments; the result is the same except that `tool` names the tool you called.
+A call to the old name now returns `isError: true` with the text `Unknown tool: 'amicus_dry_run'` and no `structuredContent`: it comes from the MCP layer, so there is no amicus error envelope and no `error.code` to branch on.
+
+**An answer file amicus refuses to read is `answer_unavailable`, not an empty answer (#162).**
+amicus reads a backend's answer file only if it is a regular file within a 1,000,000-byte limit.
+A refused file used to be indistinguishable from a backend that wrote nothing: a Codex review returned `invalid_json`, and a Codex consult returned `ok: true` with the summary "(the backend returned no message)".
+Both now return `answer_unavailable` with `error.details.reason` set to `artifact_oversize`, `artifact_not_regular` or `artifact_unreadable`; it is temporary only for an unreadable file whose cause passes, such as descriptor exhaustion, and for oversize its repair is `reduce_input`.
+A caller that treated "(the backend returned no message)" as the backend having nothing to say should branch on `ok` first, as it always should have.
+A delegate whose summary file was refused, and which has no other whole answer from the backend, is still `ok: true` when its diff was captured, with the diff and a `meta.security_warnings` entry.
+
 ## Upgrading from 0.3.0
 
 The changes below are the ones an operator or caller using amicus 0.3.0 has to handle before running 0.4.0.
@@ -206,7 +233,7 @@ The settings where this matters most are the ones whose default is looser than w
 **A review amicus cannot parse is delivered as `unstructured` (#139).**
 A review or critique whose answer is not one readable JSON object returned `invalid_json` or `schema_violation`; it now returns `ok: true` with `review_status: unstructured`, `verdict` and `confidence` set to `unknown`, and the whole answer in `raw_response.text` at `detail="full"`.
 Branch on `review_status` before reading the verdict, and read that text before paying for the same review again.
-Only an empty answer is still an error: `invalid_json`, or `empty_response` on Kimi, which detects it first.
+Only an answer amicus could not read at all is still an error: `invalid_json` for an empty one, or `empty_response` on Kimi, which detects it first, and, from 0.5.0, `answer_unavailable` for an answer file amicus refuses to read (see "Upgrading from 0.4.0").
 
 **A job result stored by 0.3.0 is no longer readable (#139).**
 `RESULT_FORMAT` moved from 6 to 7 for the unstructured review result, so `amicus_job_result` and `amicus_job_consume_result` return `job_result_incompatible` for a record 0.3.0 wrote rather than manufacturing the new shape for an older run.
@@ -237,18 +264,18 @@ Poll only while `status` is `running`; a caller that read a non-null hint as "st
 **A review amicus cannot parse is delivered as `unstructured` (#139).**
 A review or critique whose answer is not one readable JSON object returned `invalid_json` or `schema_violation`; it now returns `ok: true` with `review_status: unstructured`, `verdict` and `confidence` `unknown`, and the whole answer in `raw_response.text` at `detail="full"`.
 Branch on `review_status` before reading the verdict, and read that text before paying for the same review again.
-Only an empty answer is still an error: `invalid_json`, or `empty_response` on Kimi, which detects it first.
+Only an answer amicus could not read at all is still an error: `invalid_json` for an empty one, or `empty_response` on Kimi, which detects it first, and, from 0.5.0, `answer_unavailable` for an answer file amicus refuses to read (see "Upgrading from 0.4.0").
 
 **A job result stored by 0.2.0 is no longer readable (#65, #52, #139).**
-`RESULT_FORMAT` moved from 4 to 7, so `amicus_job_result` and `amicus_job_consume_result` return `job_result_incompatible` for a record 0.2.0 wrote, rather than a result whose new fields would answer for a run that never measured them.
+`RESULT_FORMAT` moved from 4 to 9, so `amicus_job_result` and `amicus_job_consume_result` return `job_result_incompatible` for a record 0.2.0 wrote, rather than a result whose new fields would answer for a run that never measured them.
 Fetch or consume any stored result you still need before upgrading; the record itself stays until `AMICUS_JOB_TTL` or the per-workspace cap evicts it.
 
 **An empty `idempotency_key` is rejected (#66).**
 The four `_async` tools accepted `""`; every paid tool now rejects it before spending as `invalid_arguments` (`minLength: 1`).
 Omit the key instead.
 
-**`amicus_dry_run` is a deprecated alias (#98).**
-Call `amicus_review_changes_dry_run`; the alias is removed at or after 0.5.0.
+**`amicus_dry_run` is a deprecated alias (#98), and 0.5.0 removed it (#204).**
+Call `amicus_review_changes_dry_run`.
 
 **Two workspace errors carry no `repair` (#42).**
 `invalid_workspace_root` and `workspace_outside_roots` return `error.repair: null`, because no call can supply the caller's directory; read `details.field` and `details.candidate_roots` instead.

{amicus-0.4.0 → amicus-0.5.0}/docs/RELEASING.md

@@ -83,6 +83,46 @@ Check two things by reading the file.
 First, its install section must not still carry the pre-release note saying amicus is unpublished and that the instructions work from the first tagged release onward — once you are releasing, that sentence is false and must be removed in the release PR.
 Second, its "Status and known limits" section must not claim anything the release contradicts, in particular the line stating amicus has never been published to PyPI.
 
+### The backend CLIs are current and checked
+
+A release vouches for the `codex`, `kimi` and `claude` that are installed when its rule-20 evidence is recorded, and those CLIs release far more often than amicus does.
+Do this last among the preconditions, immediately before the evidence run in the release sequence, because a check done a week earlier describes CLIs that have since moved.
+
+First bring each CLI to its latest release on the machine that will record the evidence.
+`codex` and `claude` are npm packages, so `npm view @openai/codex version` and `npm view @anthropic-ai/claude-code version` name the latest and the usual npm upgrade installs it.
+`kimi` is Kimi Code, which updates itself: run `kimi upgrade`.
+It is also published to npm, so `npm view @moonshot-ai/kimi-code version` names its latest; PyPI's `kimi-cli` is a different distribution whose version says nothing about it.
+Expect a major version number to mean less than it says: 0.43.1 was followed directly by 2.0.0, whose only major change was a command that opens the desktop app's page.
+
+Then run the mechanical half, which spends nothing: it runs `--version`, `--help` and each backend's free login probe, and sends no prompt.
+
+```sh
+uv run python scripts/check_backend_compat.py
+```
+
+Yes is exit status 0, with each backend reported as installed and authenticated, no `FAIL` line, and `same flags` against its newest committed capture.
+A `FAIL` line names what is wrong: a CLI that is not installed or not authenticated, a `--help` that could not be read, an installed version outside the supported versions of the contract amicus ships (read from the contract itself, so a `AMICUS_*_SUPPORTED_*` override in the environment cannot vouch for it), any warning `amicus_backends` would raise, a flag amicus always sends that `--help` no longer declares as an option, an installed prerelease or development build (`0.155.1-beta.1`, `0.155.1+local`), which is not the published release even where its numbers match, an installed version behind the latest release npm reports, or an npm lookup that failed.
+It fails closed: help that cannot be read, or a latest release that cannot be looked up, is a failure rather than a pass, and `--offline` exists to say out loud that the lookup was skipped, which is not good enough for a release.
+A flag counts only where `--help` declares it as an option, never where another option's description happens to name it.
+`FLAGS DIFFER` is not by itself a failure, since upstream adds flags constantly, but every removed flag must be looked up in that backend's `contract.py` before going on.
+`latest unknown` fails the check for every backend, because all three are on npm and it means the lookup failed rather than that the version matched.
+
+When a CLI's version has no capture of its own, commit one with the change that adds support for it, so the next release has something to compare against.
+
+```sh
+uv run python scripts/check_backend_compat.py --write
+```
+
+Adding a minor to a backend's `SUPPORTED_VERSIONS` is its own PR, made the way #112 and #194 were: a zero-spend comparison against the previous minor, recorded in the PR.
+`tests/test_codex_contract.py`, `tests/test_kimi_contract.py` and `tests/test_claude_contract.py` then hold every committed capture to the flags the contract sends.
+
+The script cannot do the other half, which AGENTS.md rule 18 requires before every release: the carrier re-check.
+Rule 18 exempts a backend's native prompt carrier only where no documented or observed way to avoid it has been found on the CLI release being validated.
+For each of the three versions the script printed, read that CLI's `--help` and its release notes since the previous amicus release (for kimi, the GitHub releases of `MoonshotAI/kimi-code`) for anything that would avoid a listed carrier: a flag or setting that stops kimi keeping a session, a way to hand kimi its prompt without a file, or a codex channel for developer instructions other than `-c` on argv.
+If one has appeared, the exemption no longer holds for that carrier, and using the new mechanism is a change to make before this release rather than after it.
+If none has, say so in the release PR, naming the three versions, so the next reader can see the looking was done and on what.
+The probe that stands behind kimi's session store, and what it did not test, is `docs/kimi-help/0.43.1/FINDINGS.md`.
+
 ## The release sequence
 
 Rules 19 and 20 together shape this sequence, and a future maintainer should not "simplify" it back.
@@ -110,6 +150,7 @@ The tag therefore deliberately points at a commit that is in `main`'s history bu
    Record the branch tip's SHA; call it the release commit, and note it well — it is the commit that gets tagged, and it will not be `main`'s head after the next step.
    If the PR C branch gains any commit after this point — an "Update branch" click, or a review pushing a change — this step must be redone from the new tip: the evidence would otherwise cover a commit that is no longer what step 4 actually merges.
    The evidence run below spends real quota on all three backends; a maintainer who has to redo this step must not reuse the earlier record, even though re-spending that quota is tempting.
+   Immediately before it, run the backend-CLI precondition above, `uv run python scripts/check_backend_compat.py` and the rule-18 carrier re-check, because the evidence vouches for exactly the CLI versions installed at this moment.
    Run `uv run python scripts/record_live_gate_evidence.py`.
    The script itself forces `AMICUS_REQUIRE_LIVE=1` into each backend's subprocess environment, so prefixing the command with it is optional; its own usage string documents `AMICUS_REQUIRE_LIVE=1 uv run python scripts/record_live_gate_evidence.py`, and either form runs the same live gates.
    This spends real quota on all three backends and requires the maintainer's authorization in the session where it runs.

{amicus-0.4.0 → amicus-0.5.0}/docs/adr/0033-an-unreadable-review-answer-is-delivered-unstructured.md

@@ -39,6 +39,7 @@ It would also keep a result that holds the backend's whole answer behind `ok: fa
 It stays `invalid_json` with the shared table's `retry_then_report`, which is honest there: an empty answer is the case a retry can plausibly change.
 Kimi detects an empty answer before a result is built and reports it as `empty_response`, with the same repair; that code was emitted but missing from every tool's `error_codes`, and is now listed on each paid tool that can select Kimi.
 An answer file amicus refuses to read, because it is not a regular file or exceeds the artifact cap, also reaches this path as empty, so the message says amicus read no answer rather than that the backend returned none.
+That sentence is superseded by ADR 0036 (#162): a refused answer file is `answer_unavailable`, and only a genuinely empty answer reaches this path.
 `schema_violation` is no longer a review outcome and leaves the review tools' `error_codes`.
 That also settles #116's point about a deterministic `invalid_json`: the deterministic cases now reach the caller as `unstructured`, carrying no retry advice.
 

{amicus-0.4.0 → amicus-0.5.0}/docs/adr/0035-a-backend-answer-is-kept-on-the-job-record.md

@@ -51,3 +51,4 @@ The boundary is checked by carrier, not by semantic derivation: `tests/test_sync
 Statements that were overbroad under the exception are narrowed to the input half: `request.py`'s module docstring and the design spec's "Jobs and tasks" section.
 `FINGERPRINT` moves to schema-35 for the description text; `RESULT_FORMAT` does not move, since nothing stored changes.
 Kimi's own session log, which keeps the full prompt and answer outside amicus's retention, is a separate disclosure gap filed as #179.
+That gap was closed by disclosure, not deletion: Kimi's `CARRIERS` and read-only statement now name the session store, and `docs/kimi-help/0.43.1/FINDINGS.md` records why amicus does not remove it.

amicus-0.5.0/docs/adr/0036-a-refused-answer-file-is-answer-unavailable.md

@@ -0,0 +1,69 @@
+# ADR 0036: an answer file amicus refuses to read is `answer_unavailable`
+
+**Status:** Accepted (2026-09-19)
+
+## Context
+
+amicus reads a backend's answer file through a bounded reader: `O_NOFOLLOW`, regular files only, at most 1,000,000 bytes (ADR 0009).
+The reader returned an empty string for a file it refused, and the run loop dropped empty texts, so a refusal was indistinguishable from a backend that wrote nothing (#162).
+ADR 0033 recorded the consequence for reviews, `invalid_json` with a message hedged to cover both cases.
+It did not record the worse one: a Codex consult in the same state returned `ok: true` with the summary "(the backend returned no message)".
+
+The reader also made a single `read` call, which may return short, so a prefix of an answer could be delivered as the whole of it.
+
+## Decision
+
+**A refusal is its own error, `answer_unavailable`.**
+No code in the closed catalog was honest for it.
+`empty_response` is declared per feature and listed only where Kimi can be selected, it means "exit 0 with no answer", and it repairs with a retry, which is wrong for a deterministic oversize.
+`invalid_json` is wrong for consult and delegate, `internal_error` says amicus broke, and `input_too_large` and `context_too_large` are about input.
+A Codex design consult reached the same conclusion, and the maintainer chose a new code over reusing one.
+
+**The code is amicus's own, not the SDK's.**
+It lives in `LOCAL_CODES` and `errors._LOCAL_RULES`, because `UNIVERSAL_CODES` is the intersection the sibling bridges emit and this comes from amicus's orchestration (ADR 0030).
+
+**`error.details.reason` is a fixed token, and nothing else identifies the file.**
+`artifact_oversize` carries `limit_bytes`, and `actual_bytes` when `fstat` knew the size; `artifact_not_regular` and `artifact_unreadable` stay apart, because one is a security invariant holding and the other an operational failure.
+The path, an errno and exception text never appear: a delegate's answer path is model-controlled (ADR 0009).
+Oversize and not-a-regular-file are never temporary: oversize repairs with `reduce_input`, the other with `inspect_and_retry`.
+`artifact_unreadable` is temporary only when the cause was: descriptor or memory exhaustion or an interrupted call (`EMFILE`, `ENFILE`, `ENOMEM`, `EINTR`, `EAGAIN`) passes, so the identical call may succeed and the repair is `retry_after_delay`, while a permission or I/O error is about the file and repairs with `inspect_and_retry`.
+The errno decides and stays internal; a second Copilot review caught the first version, which called every refusal permanent.
+A retry is a new paid run either way, since the refused run itself finished, and the repair prose says so.
+
+**An absent or empty file is not a refusal.**
+The backend writing nothing is a different fact from amicus refusing what it wrote, and keeps its old meaning.
+
+**Only a refusal of an answer artifact counts.**
+`PreparedRun.answer_artifacts` names them; Codex stages its input schema in `artifact_paths` too, and refusing that says nothing about the answer.
+
+**Every other failure wins, with one exception.**
+A non-zero exit, a timeout, a missing binary and any failure an inspector reports are the more accurate account.
+The exception is a clean exit an inspector diagnosed as `empty_response`: the refusal is why the run looked empty, so it is what is reported.
+The first draft superseded any clean-exit failure, which would have hidden an inspector's auth or rate-limit finding; a Codex review and a Copilot review both caught it.
+
+**Another channel is a substitute only if it was captured whole.**
+Kimi's stream can carry the answer when its answer file is refused.
+It is delivered, with a `meta.security_warnings` entry, only when the capture was neither truncated nor failed (`CommandRun.output_truncated` and `capture_failed`), because a damaged capture can lose the true final message while an earlier one still parses.
+That check is its own: `meta.truncated` reports a bounded review input or delegate diff, not stream capture, so a delivered stream answer can sit beside `meta.truncated: true` when the diff was over its limit.
+
+**A delegate keeps its diff.**
+The diff is captured from the worktree, not read from the answer file, so it is still the honest primary result.
+A whole stream answer comes first: a Kimi delegate whose stream survived keeps the backend's own summary and `raw_response.text`, as above.
+Only when no such answer exists is the summary amicus's own, and then it says so, `raw_response.text` stays null rather than carry amicus's words as the backend's, and the summary makes no claim about the diff's completeness, which `meta.truncated` and `meta.redacted_paths` describe.
+With no diff either, it is `answer_unavailable`.
+
+**Nothing is truncated to fit.**
+A truncated structured consult would fall into the prose branch and be delivered as a successful answer, and a truncated review cannot be parsed.
+
+**The reader reads to the end.**
+It loops up to one byte past the cap, which bounds memory, tolerates a short `read`, and notices a file that grew after `fstat`.
+
+## Consequences
+
+`error.code` is a closed enum, so a reader of the previous result format rejects a stored error carrying the new value: `RESULT_FORMAT` moves 8 to 9, and `FINGERPRINT` to schema-37.
+`tools/list` does not carry error codes, so its measured size does not move.
+The code is listed on every paid tool that can select a backend answering through a file, and not on adversarial review, which only Claude runs and which answers on stdout.
+ADR 0033's sentence about a refused answer file is superseded by this record.
+
+Not established: whether a real backend's answer file can reach the cap.
+Stdout is capped separately at 10 MB, and the short-read fix is a property of `read(2)` rather than an observed failure.