feat: add portable claim-readiness diagnostics fixture and test [0x954dB727f224dAabeA2A506C8aE92029b25339cE]

[waterWang]

Summary

Add committed fixtures and a deterministic test for the solver-facing claim-readiness response so an agent can see reward, refundable bond, external spend, gross cash margin, and one actionable blocker before signing.

Changes

New files

• scripts/next-agent-claim-readiness.mjs — Portable implementation that validates a claim-readiness response and produces a canonical result with profit outlook
• benchmarks/direct-v1/claim-readiness/test.mjs — Test runner with fixture-based test cases
• benchmarks/direct-v1/claim-readiness/self-test.mjs — Self-test that validates the test runner catches real bugs

Test scenarios

Scenario	Status	Can claim	Profit outlook
Healthy direct bounty	ready	✅	profitable
Recovery-reserved bounty	recovery_reserved	❌	blocked
Unprofitable bounty	ready	❌	unprofitable
Non-creator failure	non_creator	❌	blocked

Acceptance criteria

• ✅ 4 scenarios covered (healthy, recovery-reserved, unprofitable, non-creator)
• ✅ Each result exposes exact next action, never requests private key/seed phrase
• ✅ Gross cash margin clearly distinguished from guaranteed net profit
• ✅ Test rejects results that describe a plan, signature, transaction hash, or hosted row as payment
• ✅ Offline, replayable, exits 0

Verification

node benchmarks/direct-v1/claim-readiness/test.mjs claim-readiness /workspace
node benchmarks/direct-v1/claim-readiness/self-test.mjs

Both pass cleanly.

Closes #682

[NSPG13]

Thanks for the substantial fixture coverage. The four requested scenarios, fail-closed parsing, private-key avoidance, and payment-language checks are useful.

Changes are required before main:

• The PR says it adds committed fixtures, but every fixture is generated in a temporary directory. Commit the four canonical response fixtures so API, MCP, and SDK consumers can replay the same contract.
• scripts/next-agent-claim-readiness.mjs validates a standalone JSON formatter rather than the production API/MCP response, so it can pass while the real product regresses. Drive the fixtures through the real claim-readiness projection or deserialize the production schema in its owning Rust crate.
• external_spend currently accepts negative values and the code trusts the supplied gross_cash_margin while separately calculating profit_outlook. This allows contradictory or inflated economics. Require unsigned external spend and derive/assert gross_cash_margin = solver_reward - required_external_spend; keep it explicitly distinct from guaranteed net profit.
• Add the focused replay to scripts/check.py.

Please run the focused test and python scripts/check.py --platform posix. A collaboration branch is reasonable after these production-contract and economics issues are fixed. #682 is not canonically funded; only BountySettled proves payment.

[NSPG13]

This PR remains in manual-security review with requested changes. What passed: it targets issue #682. What blocks main: diagnostics must remain advisory and the PR overlaps #697, #746, and #763. Action: resolve existing review threads, consolidate scope, run cargo run -p cli -- docs-contract-check and focused diagnostics tests, and add stale/malformed/unfunded/ready fixtures. Done when the output gives a safe next action without authorizing a claim or payment. Thanks for helping the community grow, and sorry for the review friction.