fix(rollback): surface missing-blob aborts in the JSON envelope

[Mikola Lysenko (mikolalysenko)]

Problem

When rollback aborted because beforeHash blobs were missing (--offline) or undownloadable (online 404), the --json envelope was contentless and self-contradictory: exit 1 with {"status":"partial_failure","rolledBack":0,"failed":0,"warnings":[],"results":[]} — failed: 0 on a failed run, no error field, nothing on stderr. Human mode explained the failure fine. A JSON consumer learned nothing. (Found on every apply leg of the 2026-08-18 pnpm e2e matrix; the bug is ecosystem-independent.)

Two smaller issues rode along: the "No SOCKET_API_TOKEN set" advisory printed twice per invocation (once per internal ApiClient construction), and the abort error string hand-copied the engine's first-blocking-file shape.

Fix

• Both pre-flight abort paths now synthesize one failed RollbackResult per gated package: purl, filesVerified records with the engine's existing missing_blob status naming the missing hash, the offline-gate or per-hash download reason, and the socket-patch repair hint. Counters follow apply's per-package semantics (failed: N, exit 1). Created-by-patch sentinels (empty beforeHash) are excluded; output is purl-sorted. No new JSON keys — only when the documented results[]/failed fields are populated changed.
• The abort error string is built by a new cannot_rollback_error() shared with the engine's emission site, so the two shapes cannot drift.
• The rollback path threads its ApiClient through instead of constructing a second one; the token advisory prints once.

Deliberately not changed: the snake_case partial_failure status. CLI_CONTRACT.md pins rollback as a pre-v3.0 legacy envelope whose snake_case status is the documented consumer discriminator, and rates a status-string change MAJOR — the tracked fix is the unified-envelope migration.

Verification

• New integration tests: json-mode missing-before-blob offline abort → exit 1 with blob hash + repair hint + failed:1; human-mode parity; token note printed exactly once. Unit tests for the abort-result synthesis.
• Rollback/remove consumer suites green (rollback_invariants, cli_rollback_silent, cli_parse_rollback, remove_invariants, remove_rollback_api_overrides).
• Manual smoke with the release binary: offline and dead-registry online aborts both render purl + hash + reason + repair hint, failed:1, exit 1.

🤖 Generated with Claude Code

---

Note

Low Risk
Rollback CLI/JSON diagnostics only; no changes to patch application, auth, or blob storage semantics beyond populating existing envelope fields on abort paths.

Overview
Fixes rollback --json when the run exits before the rollback loop because beforeHash blobs are missing (--offline) or still missing after a failed download. Previously that path returned exit 1 with partial_failure, failed: 0, and empty results[] while stderr was muted under --json—machine consumers got no package, hash, or remedy.

Both pre-flight abort paths now call missing_blob_abort_results, which emits one failed RollbackResult per gated package (purl-sorted, empty beforeHash sentinels skipped): filesVerified with missing_blob, targetHash, offline or per-hash download reasons, and socket-patch repair hints; failed matches apply’s per-package semantics.

cannot_rollback_error in core centralizes the Cannot rollback: {file} - {why} string so synthesized aborts match mid-run engine failures. rollback_patches_inner accepts the telemetry ApiClient from run() so blob fetch does not build a second client (dedupes the No SOCKET_API_TOKEN advisory); the remove delegation still builds on demand when None.

Tests lock the new envelope shape, human-mode parity, and client-notice count.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue.}

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

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