shipper recover

shipper recover

Usage: shipper recover [options]

Recover an eligible failed issue while preserving completed work and check evidence

Arguments

Argument	Required	Description	Choices
	yes	Shipper issue ID, gh:, or GitHub URL	-

Flags

Long	Short	Value	Default	Description	Choices
—superseded	-		-	restore one live superseded-work occurrence	-

Examples

Recover a failed issue while preserving completed groom or packaged work.

shipper recover S#42

Restore one live superseded-work occurrence to ordinary local branches.

shipper recover S#42 --superseded <event-id>

Required-check failures

New automatic check stops apply only to independently acquired hosted checks. Hosted-check external obstruction and unchanged-revision stalled remediation enter Failed over Rework while retaining useful fixes, package/branch/PR identity, answers, evidence and delivery debt. Obstruction requires concrete evidence, cause, external remedy and final-HEAD applicability after same-pass fixes; red status, main-branch match or missing tools alone are insufficient. The mechanical backstop requires a completed current V4 check-only review with retained answers and identical fresh failures on unchanged HEAD after refresh/rerun/flake opportunities. Nits are neutral; changed/passed/new/material/pending/unavailable evidence and request-changes bodies veto it. Sandbox limitations remain ordinary investigation. A skipped review consumes no allowance and each stop counts once toward terminal safety. No report, answer, resolution or retry waives required checks or permits red ship/merge. Remedy/restart alone stays Failed. Preserving shipper reset S#123 --to rework and eligible shipper recover S#123 renew allowance on unchanged HEAD, preserve unpublished work and history, and require fresh normal verification. Existing eligibility, locks, closure holds and confirmation rules apply. Missing/divergent retained refs refuse retry. Read current or historical diagnosis, local procedures and pending delivery with issue view/get-issue, including roundless failures. Local verification uses existing prose summaries and relevant comments, without a structured local evidence report. Every attempted non-permission local failure, including apparently unrelated or pre-existing failures, requires an anchored 🔴 must-fix: comment on the most relevant changed line and REQUEST_CHANGES, then ordinary Rework fixes or prose replies. Permission-denied and unattempted checks are limitations, never passes or waivers; all previously required checks stay required. Local-only workflows have no local-evidence automatic stop; the ordinary review-round cap still applies. Historical local observations and failure records remain readable without migration. Outstanding historical local findings receive ordinary prose replies and never authorize a new automatic stop. Upgrade alone does not clear findings, renew allowance, or recover Failed. Publication and hook diagnostics and required hook execution remain unchanged.

Exit Codes

Code	When
0	Recovery commits locally and projections succeed or warn.
1	The issue is ineligible, locked, invalid, or recovery fails.

Constraints

• Continuation lookup uncertainty stops the stage before preparation or agent launch, records ordinary Failed state when available, and returns nonzero. Diagnostics identify the issue, stage, and underlying history, state, or ref problem and say “continuation could not be determined.” Repair that problem, then explicitly run shipper recover S#123 before retry. Repair alone or restart does not clear persisted Failed. Ordinary Reset, including Rework and --force, is refused while this failure is active. Continuation-lookup recovery takes precedence over grooming and packaged recovery and restores the original raw workflow label (including PR Open or Ready), branch, evidence, route, and associations without renewing the review allowance. If failure state could not be recorded, explicit Recover verifies the unchanged stage and branch context read-only and acknowledges a definitive lookup without writing a reset event. Uncertainty still refuses recovery. Confirmed non-applicability permits ordinary execution without broadening eligibility. When applicable work was recorded but its branch is confirmed absent, run output states exactly: “S# : preserved work was recorded on , but that branch was not found.” This notice makes no claim of loss or safety. There is no automatic repair or new flag.
• Rework is the recommended preserving reset from PR Open, Ready, or Rework, and from a failed issue without a stage. It requires an open linked PR under GitHub PR policy or a reachable pinned local change under no-PR policy. Legacy reviewed labels normalize to PR Open for this check. All routes retain their route; early stages do not qualify merely because they hold a package. Missing, closed, merged, or unverifiable evidence refuses the reset without changes; inspect or repair the association with shipper issue reconcile --repair, or recover the local package first. Rework preserves the package, association, branches, worktrees, route and review history, and clears failure. Repeat Rework resets are real operations. Next, Ship, and auto-ship dispatch Rework to implementation, which freezes one situation for the run: a current held-round pin selects review rework; otherwise a newer roundless merge-conflict entry selects merge rework; every other case is a roundless continuation of the retained packaged change with no correction delta, new reset instruction, accepted plan, or accepted design. Review rework consumes the pinned round, outstanding local findings, and supplied unresolved external threads, requires one nonblank fix or reasoned won’t-fix disposition per target, and durably delivers successful replies with configured best-effort resolution. An unreadable pin or dispositions still missing after one correction fail without advancing. Merge rework requires no review replies. Every situation reuses the preserved branch and open pull request without editing its metadata. Every successful explicit packaged preserving reset and eligible active packaged-change recovery restarts the five-round review allowance, including repeated Rework resets, unchanged revisions, and exhausted allowances. Package identity, full review history, findings, dispositions, and Rework context are preserved; renewal resolves no findings and grants no approval. Eligibility, destinations, and independent retry limits are unchanged. Count completed approved, addressed, superseded, and zero-finding reviews since the latest established renewal in append order; attempts without a completed review consume nothing. The first five completed reviews may reject into Rework; a sixth rejection enters durable Failed over Rework and retains its round, while a sixth approval may advance under existing approval rules. Automatic transitions and rejections, ordinary retries, restart/resume, grooming recovery, superseded-branch restoration, refused actions, and cancellation do not renew. Renewal belongs to the local logical commit even when projection repair is pending; repair grants no second renewal. A committed pending action reports its operation ID and says not to repeat it: store access finishes the existing operation. Recovery uses Recovery committed; local recovery pending for this outcome. For pre-release retained packages, affirmative historical preserving reset or packaged-recovery evidence, including recorded Rework operator-reset history, establishes the latest renewal. Without such evidence the existing full count remains. Upgrade alone leaves Failed intact. Current-allowance progress can be 0 of 5 or 6 of 5; historical round numbers and order never change and may exceed six. Replacement package identities start independently.
• Recovery dispatches from a saved grooming question session, preserved groom output, a pinned local change, or an open linked pull request. A question session takes precedence over groom output and retains both records; a question session plus packaged work is rejected as ambiguous.
• Artifact recovery requires Failed; all recovery refuses closure-held issues. Preserved groom output is retained as one atomically replaced bundle per issue with no expiry.
• Session recovery asks no questions and runs no grooming agent. It clears failed state, returns the issue to shipper:new, retains the saved conversation, reports the number of preserved answered rounds, and preserves the recorded owner byte-for-byte. That owner can resume normally; another surface must take over first, while an unowned session must be claimed through takeover. Saved sessions also have no age-based expiry.
• Groom recovery validates the preserved input/output first. If still invalid, it allows exactly one unattended correction without restarting discovery or re-asking answered questions; another invalid result replaces the bundle and remains recoverable.
• The packaged revision must exist and remain reachable from its source branch. The source branch may advance past that revision; a missing, rewound, or divergent branch is ineligible and requires reset.
• Except for failed Rework, packaged-change recovery stores shipper:pr-open; there is no target picker. That stage is displayed as PR Open when pull requests are enabled and Change Packaged when they are disabled. Groom recovery applies the preserved groom result through normal groom post-flight.
• Packaged-change recovery does not consult the issue’s route. A failed simple-route issue holding a valid pull request or local packaged change recovers to the same review-entry state with its artifacts preserved, never passing through shipper:planned.
• Failed Rework recovery uses durable failed-entry evidence even when failure cleanup cleared the stage label, requires the same current-policy package evidence, clears failure while retaining Rework and its existing trigger, and appends no new review-rework entry or reconstructed correction text.
• The packaged revision, source and target branches, title, body, branches, worktrees, workflow history, and completed review rounds are preserved.
• A successful fresh groom or successful groom-output recovery deletes completed grooming records. Reset-to-New explicitly discards both preserved groom output and any saved question session; recovery never discards a saved session.
• Projection failures do not roll back local recovery; run shipper issue reconcile --repair to repair them.
• --superseded <event-id> selects one exact, live supersession occurrence and does not require the issue to be failed. It creates or reuses deterministic ordinary recovery branches, then acknowledges that occurrence so it is not announced again.
• Superseded-work recovery refuses blank, stale, acknowledged, reset-superseded, missing-ref, and conflicting-branch selections without altering workflow state. Restored ordinary branches survive issue release; Shipper-managed hidden preservation refs do not.
• Live superseded-work occurrences and their hidden refs have no age-based expiry. They remain available while the issue is active and are released only after completion, not-planned or external closure, unadoption, or reset-to-New commits.