amicus 0.3.0__tar.gz → 0.4.0__tar.gz

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

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

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "0.3.0",
+  "version": "0.4.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.4.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.4.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.4.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.4.0",
         "amicus-mcp"
       ],
       "env_vars": [

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

@@ -31,10 +31,11 @@ The rules bind; the context after them explains and points elsewhere.
     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.
     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,16 +48,20 @@ 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`.
 
@@ -76,12 +81,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 +108,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.4.0}/CHANGELOG.md

@@ -20,6 +20,189 @@ per-change, as its own lead says.
 
 ## [Unreleased]
 
+## [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 +715,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.3.0...HEAD
+[Unreleased]: https://github.com/briandconnelly/amicus/compare/v0.4.0...HEAD
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: amicus
-Version: 0.3.0
+Version: 0.4.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
@@ -24,7 +24,6 @@ Requires-Python: >=3.11
 Requires-Dist: anyio>=4
 Requires-Dist: fastmcp<4.1,>=4.0
 Requires-Dist: mcp<2.3,>=2.1
-Requires-Dist: pontonier==0.9.0
 Requires-Dist: pydantic>=2
 Description-Content-Type: text/markdown
 
@@ -74,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.2.0", "amicus-mcp"]
+      "args": ["--from", "git+https://github.com/briandconnelly/amicus.git@v0.4.0", "amicus-mcp"]
     }
   }
 }
@@ -115,7 +114,9 @@ anything.
 
 ## The tools
 
-Nineteen tools, in five groups, one of them a deprecated alias. Everything paid has a free way to inspect it first.
+Nineteen tools, in five groups, one of them a deprecated alias. Discovery, previews and job
+management are free; the verbs and their background twins invoke the selected backend and spend
+its quota.
 
 | Group | Tools |
 | --- | --- |
@@ -133,13 +134,10 @@ Not every backend does everything:
 | `delegate` | yes | yes | no |
 | `adversarial_review` | no | no | yes |
 
-A `no` is amicus's routing decision, not a claim about the model. `delegate` is absent on Claude
-by a deliberate review-only policy. `adversarial_review` is scoped to Claude for v1, but the verb
-is amicus's own: the prompt it builds and the result shape it returns are amicus's for any
-backend, and what Claude contributes is a critic stance layered on top. So nothing about
-Codex or Kimi stops either from reviewing adversarially — ask them through `consult` or
-`review_changes` and supply the adversarial stance yourself. What the verb adds is that stance
-fixed, plus its `target` and `evidence` carriers.
+A `no` is amicus's routing policy, not a model limitation. Claude is review-only, and the
+dedicated adversarial-review verb is scoped to Claude. To ask Codex or Kimi for an adversarial
+review, use `consult` or `review_changes` and supply the stance yourself; the dedicated verb adds
+a fixed critic stance and the `target` and `evidence` inputs.
 
 Asking a backend for something it does not support returns a `feature_unsupported` error naming
 the backend and the feature, rather than failing obscurely.
@@ -154,6 +152,11 @@ the backend and the feature, rather than failing obscurely.
   annotations — see [`docs/MIGRATION.md`](docs/MIGRATION.md).
 - **Your prompts go to whichever provider you selected**, through that provider's own CLI. Each
   backend discloses how it carries your text — visible on `amicus_backends`.
+- **A paid call's whole answer stays on disk** in the job record under `AMICUS_STATE_DIR`,
+  whatever `detail` delivered it and after only best-effort secret redaction, until it expires
+  (`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)).
 
 ## Configuration
 
@@ -162,12 +165,10 @@ reasoning effort, and binary path (`AMICUS_CODEX_MODEL`, `AMICUS_KIMI_REASONING_
 `AMICUS_CLAUDE_BIN`, and so on), and there are limits for timeouts, job retention and payload
 sizes. The full list is the `env_vars` array in [`.mcp.json`](.mcp.json).
 
-Logging goes to stderr, and `AMICUS_LOG_FILE` mirrors amicus's own records to a file. The
-`fastmcp` and `mcp` libraries' records also reach stderr, but never below WARNING whatever
-`AMICUS_LOG_LEVEL` says, never the file, and with every unaudited FastMCP server record
-reduced to its level, logger and exception type. That is deliberate (ADR 0023): those
-libraries can log a caller's prompt text, so a FastMCP-side failure is diagnosed from the
-exception type and frames rather than its message.
+Logging goes to stderr, and `AMICUS_LOG_FILE` mirrors amicus's own records to a file. To reduce
+the risk of prompt text leaking through dependency logs, `fastmcp` and `mcp` records are limited
+to WARNING or higher on stderr, reduced to non-message diagnostics, and never written to that
+file (ADR 0023).
 
 ## Coming from codex-in-claude, moonbridge, or claude-in-codex
 
@@ -176,20 +177,16 @@ the new ones.
 
 ## Status and known limits
 
-0.3.0 is the current release, and it is a breaking one: the discovery surface moved from
-`amicus/0.1/schema-13` to `amicus/0.1/schema-30` and stored job results from `RESULT_FORMAT` 4 to
-`6`, so a job result 0.2.0 stored cannot be read after upgrading.
-[`docs/MIGRATION.md`](docs/MIGRATION.md#upgrading-from-020) walks through what a caller written
-against 0.2.0 has to change, and [`CHANGELOG.md`](CHANGELOG.md) lists everything that moved. The
-server's wire contract is exercised by the test suite and by host captures against Claude Code and
-Codex, but:
-
-- Two router-skill evaluation scenarios are unresolved — S6 (diff-safety wording) and S7 (approval
-  friction) — recorded in [`docs/adr/0012-m6-packaging-decisions.md`](docs/adr/0012-m6-packaging-decisions.md).
-  Neither is a defect in the server's wire contract.
-- A third-party backend distribution loads through the `amicus.backends` entry-point group, but
-  cannot yet be enabled or called: `AMICUS_BACKENDS` and the `backend` parameter accept only the
-  in-tree ids.
+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.
+
+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`
+parameter accept only the three in-tree ids.
 
 ## Development
 
@@ -203,7 +200,7 @@ version.
 
 | Question | Read |
 | --- | --- |
-| What is being built and why | `docs/superpowers/specs/2026-09-04-amicus-design.md` |
+| What is being built and why | `docs/superpowers/specs/2026-09-04-amicus-design.md`; for M8, `docs/superpowers/specs/2026-09-15-amicus-M8-sdk-in-tree-design.md` |
 | How milestones are executed by agents | `docs/superpowers/plans/2026-09-04-amicus-execution-model.md` |
 | Architecture decisions | `docs/adr/` |
 | How a release is cut | `docs/RELEASING.md` |

{amicus-0.3.0 → amicus-0.4.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.2.0", "amicus-mcp"]
+      "args": ["--from", "git+https://github.com/briandconnelly/amicus.git@v0.4.0", "amicus-mcp"]
     }
   }
 }
@@ -85,7 +85,9 @@ anything.
 
 ## The tools
 
-Nineteen tools, in five groups, one of them a deprecated alias. Everything paid has a free way to inspect it first.
+Nineteen tools, in five groups, one of them a deprecated alias. Discovery, previews and job
+management are free; the verbs and their background twins invoke the selected backend and spend
+its quota.
 
 | Group | Tools |
 | --- | --- |
@@ -103,13 +105,10 @@ Not every backend does everything:
 | `delegate` | yes | yes | no |
 | `adversarial_review` | no | no | yes |
 
-A `no` is amicus's routing decision, not a claim about the model. `delegate` is absent on Claude
-by a deliberate review-only policy. `adversarial_review` is scoped to Claude for v1, but the verb
-is amicus's own: the prompt it builds and the result shape it returns are amicus's for any
-backend, and what Claude contributes is a critic stance layered on top. So nothing about
-Codex or Kimi stops either from reviewing adversarially — ask them through `consult` or
-`review_changes` and supply the adversarial stance yourself. What the verb adds is that stance
-fixed, plus its `target` and `evidence` carriers.
+A `no` is amicus's routing policy, not a model limitation. Claude is review-only, and the
+dedicated adversarial-review verb is scoped to Claude. To ask Codex or Kimi for an adversarial
+review, use `consult` or `review_changes` and supply the stance yourself; the dedicated verb adds
+a fixed critic stance and the `target` and `evidence` inputs.
 
 Asking a backend for something it does not support returns a `feature_unsupported` error naming
 the backend and the feature, rather than failing obscurely.
@@ -124,6 +123,11 @@ the backend and the feature, rather than failing obscurely.
   annotations — see [`docs/MIGRATION.md`](docs/MIGRATION.md).
 - **Your prompts go to whichever provider you selected**, through that provider's own CLI. Each
   backend discloses how it carries your text — visible on `amicus_backends`.
+- **A paid call's whole answer stays on disk** in the job record under `AMICUS_STATE_DIR`,
+  whatever `detail` delivered it and after only best-effort secret redaction, until it expires
+  (`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)).
 
 ## Configuration
 
@@ -132,12 +136,10 @@ reasoning effort, and binary path (`AMICUS_CODEX_MODEL`, `AMICUS_KIMI_REASONING_
 `AMICUS_CLAUDE_BIN`, and so on), and there are limits for timeouts, job retention and payload
 sizes. The full list is the `env_vars` array in [`.mcp.json`](.mcp.json).
 
-Logging goes to stderr, and `AMICUS_LOG_FILE` mirrors amicus's own records to a file. The
-`fastmcp` and `mcp` libraries' records also reach stderr, but never below WARNING whatever
-`AMICUS_LOG_LEVEL` says, never the file, and with every unaudited FastMCP server record
-reduced to its level, logger and exception type. That is deliberate (ADR 0023): those
-libraries can log a caller's prompt text, so a FastMCP-side failure is diagnosed from the
-exception type and frames rather than its message.
+Logging goes to stderr, and `AMICUS_LOG_FILE` mirrors amicus's own records to a file. To reduce
+the risk of prompt text leaking through dependency logs, `fastmcp` and `mcp` records are limited
+to WARNING or higher on stderr, reduced to non-message diagnostics, and never written to that
+file (ADR 0023).
 
 ## Coming from codex-in-claude, moonbridge, or claude-in-codex
 
@@ -146,20 +148,16 @@ the new ones.
 
 ## Status and known limits
 
-0.3.0 is the current release, and it is a breaking one: the discovery surface moved from
-`amicus/0.1/schema-13` to `amicus/0.1/schema-30` and stored job results from `RESULT_FORMAT` 4 to
-`6`, so a job result 0.2.0 stored cannot be read after upgrading.
-[`docs/MIGRATION.md`](docs/MIGRATION.md#upgrading-from-020) walks through what a caller written
-against 0.2.0 has to change, and [`CHANGELOG.md`](CHANGELOG.md) lists everything that moved. The
-server's wire contract is exercised by the test suite and by host captures against Claude Code and
-Codex, but:
-
-- Two router-skill evaluation scenarios are unresolved — S6 (diff-safety wording) and S7 (approval
-  friction) — recorded in [`docs/adr/0012-m6-packaging-decisions.md`](docs/adr/0012-m6-packaging-decisions.md).
-  Neither is a defect in the server's wire contract.
-- A third-party backend distribution loads through the `amicus.backends` entry-point group, but
-  cannot yet be enabled or called: `AMICUS_BACKENDS` and the `backend` parameter accept only the
-  in-tree ids.
+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.
+
+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`
+parameter accept only the three in-tree ids.
 
 ## Development
 
@@ -173,7 +171,7 @@ version.
 
 | Question | Read |
 | --- | --- |
-| What is being built and why | `docs/superpowers/specs/2026-09-04-amicus-design.md` |
+| What is being built and why | `docs/superpowers/specs/2026-09-04-amicus-design.md`; for M8, `docs/superpowers/specs/2026-09-15-amicus-M8-sdk-in-tree-design.md` |
 | How milestones are executed by agents | `docs/superpowers/plans/2026-09-04-amicus-execution-model.md` |
 | Architecture decisions | `docs/adr/` |
 | How a release is cut | `docs/RELEASING.md` |