Document get's real paid_required JSON (#982)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code:claude-opus-5-5

Fixes #982

Root cause

CLI_CONTRACT.md documents a paid-plan outcome that no command emits: envelope status: "paidRequired" with a failed event tagged paid_required, from "get/scan". What actually ships:

• get --json prints its legacy shape {"status": "paid_required", "found", "downloaded": 0, "applied": 0, "patches": [...]}, with no events and no error, and exits 0. Two code paths (search with no accessible patch, and get <uuid> on the public proxy) hand-wrote it separately.
• scan never reports it. It leaves paid patches out of the selection and counts them in paidPatches / canAccessPaidPatches.
• Status::PaidRequired was never constructed outside tests.

A client that matches status == "paidRequired" never takes its "upgrade your plan" branch.

Change (no behavior change)

• Contract: the paid_required row now describes get's real shape and exit code and says scan never reports it. paidRequired is dropped from the envelope status enum.
• json_envelope::Status::PaidRequired is removed, along with its two test references.
• get's two paid JSON blocks now share one emitter, paid_required_json.
• New tests/contract_paid_required.rs pins the contract row and the enum against the source, in the style of contract_gradle_codes.rs.

Tests (red → green)

• CLI_CONTRACT.md documents status paidRequired for get and scan, but get emits "paid_required" and scan never reports it #982: contract_paid_required::contract_paid_required_row_matches_get and ::get_writes_the_paid_required_shape_once (new). On main, both fail: the row says status=paidRequired, and get.rs writes the paid shape twice. Both pass on this branch.
• The existing --test get paid tests still pin the emitted paid_required shape and exit 0.

Commands run

• cargo test -p socket-patch-cli --all-features --lib --test contract_paid_required --test get --test covgap_commands_get --test cli_get_silent: all pass.
• cargo fmt --all -- --check and cargo clippy --locked --workspace --all-features -- -D warnings: clean. This PR also formats one test in redirect/upstream/mod.rs that main left unformatted.

The hosted-e2e / e2e_safety_pnpm / Bun native legs are red on main too, because of the withdrawn minimist patch (#1293). That failure is not caused by this diff.

---

Note

Low Risk
Documentation and internal refactor only; paid JSON shape and exit code are unchanged and covered by existing and new contract tests.

Overview
Aligns CLI_CONTRACT.md with what get actually emits for paid-only results: the legacy top-level "status": "paid_required" JSON (exit 0, no unified envelope events/error), and documents that scan never reports this outcome. The unused envelope status paidRequired is removed from the contract and from json_envelope::Status.

get consolidates its two paid JSON code paths behind a shared paid_required_json helper (no intended runtime behavior change). New contract_paid_required tests pin the contract row and single emitter against the source. A small test formatting tweak in redirect/upstream/mod.rs.

^{Reviewed by Cursor Bugbot for commit d69066e. Configure here.}

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[cursor]

Stale Bugbot comment from a previous run.

[Mikola Lysenko (mikolalysenko)]

[agent] hosted-e2e and e2e (ubuntu-latest, e2e_safety_pnpm) (and so ci-ok) are red on this PR. The cause is not this PR: production stopped serving the free minimist@1.2.2 patch these suites are pinned to (#1293), and the same jobs fail on main and every other open PR. This diff doesn't touch the hosted patch service or the pinned fixtures. No fix exists yet. #1293 needs a maintainer to republish the patch, or to set HOSTED_E2E_DISABLED and repin the suites. I'm not re-running the jobs: they will fail the same way until #1293 is resolved.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

bugbot run

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit d69066e. Configure here.}

[Mikola Lysenko (mikolalysenko)]

Ready for review at d69066e74f55.

• CI: required checks ci-ok and clippy green; 7 check suites succeeded.
• Mergeable against main, no CHANGELOG.md change.
• Bugbot reviewed this head; no unresolved review threads.

Labeled Ready for review by the burn-down agent. Slack announcement pending (connector unavailable this run).

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ci-ok on 40f1a5c (the main merge) is red only because its CI run was cancelled: 14 jobs cancelled, no test failed. The cancellation landed as the PR was re-queued. I re-ran that run once (attempt 2). Nothing in this PR's diff changed.

---

Generated by Claude Code