shipper_recover

shipper_recover

Recover an eligible failed Shipper issue while preserving work and check evidence, or restore one exact live superseded-work occurrence to ordinary branches.

When to use

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. 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. 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: 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 requires one nonblank fix or reasoned won’t-fix disposition for each outstanding local finding and supplied unresolved external thread, durably delivers successes, and applies configured best-effort resolution. An unreadable pin or incomplete dispositions after one correction fail without advancing. Merge rework requires no review replies. All situations reuse the preserved branch and open pull request without changing 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. Failed Rework recovery can restore Rework from durable failed-entry evidence after the stage label was cleared; it retains the exact trigger, requires current-policy package evidence, and adds no new review-rework entry or reconstructed correction text. On macOS, this tool prevents idle system sleep while it reconstructs or launches progress-capable recovery work; saved state alone holds no lease. See Keep the Mac awake during active work. Use this when a failed issue has a saved grooming question session, preserved groom output, or packaged work. Session recovery asks no questions and runs no agent: it clears failed state, returns the issue to New, reports the preserved answered-round count, and keeps the no-expiry conversation with its recorded owner unchanged. MCP can resume normally only when it owns the session; another owner requires takeover, and an unowned session must be claimed through takeover. A session plus groom output prefers the session and retains both; a session plus packaged work is ambiguous. Groom-output recovery validates first and, only if needed, runs one unattended correction. Except for failed Rework, packaged recovery accepts a pinned local change or open linked pull request regardless of current repository posture and returns storage to shipper:pr-open while preserving completed work. With superseded_event_id, it instead restores every preserved tip for that live occurrence to a deterministic ordinary branch, reports created/reused branches, acknowledges the occurrence, and leaves workflow stage/failure state unchanged. Live occurrences and hidden refs have no age-based expiry while the issue is active. Completion, not-planned or external closure, unadoption, and reset-to-New release the managed hidden refs; ordinary restored branches survive issue release, and managed ref names are never exposed.

Behavior hints

• openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	integer | string	yes	-	Shipper issue reference. S# (GitHub #) accepts ordinary surrounding whitespace and requires the current mirror. Bare numbers are Shipper local IDs first; S# is accepted; gh: and # explicitly target a mapped GitHub issue; GitHub issue URLs are accepted. Responses return S# first with GitHub # second when mapped.
superseded_event_id	string	no	-	Optional exact live supersession event ID. Restores its preserved tips to deterministic ordinary local branches, acknowledges the occurrence, and does not require failed issue state.

Example call

{
  "issue": "S#42"
}

Example result

Resolved issue: S#42 (GitHub #123): Resume interrupted grooming
Recovered S#42 (GitHub #123) from a saved grooming question session with 2 answered rounds. The conversation remains saved and owned by Desktop; Desktop can resume it normally, while MCP or terminal must take it over first.

Error modes

• Not eligible: S# (GitHub #) is not eligible for recovery.
• Continuation context unavailable: Read-only recovery verification requires an authoritative stage and branch context.
• Closure held: The issue is closure-held and cannot be recovered until the hold is resolved.
• Nothing preserved: There is no preserved completed work to recover. Run shipper reset to continue from the failed state.
• Ambiguous artifacts: Recovery state is ambiguous because a saved grooming question session or preserved grooming output coexists with a packaged change.
• Pull request no longer open: The packaged change linked as # is no longer open. Run shipper reset to continue.
• Source branch missing: Source branch <branch> no longer exists. Run shipper reset to discard the stale packaged record.
• Packaged revision unreachable: Packaged revision is no longer reachable from source branch <branch>. Run shipper reset to discard the stale packaged record.
• Active lock: S# (GitHub #) is locked by PID , acquired at . Use ‘shipper unlock S# —force’ to force unlock it.
• Projection warning: Local recovery succeeded, but projection failed: . Run shipper issue reconcile --repair to repair GitHub projections.
• Supersession unavailable: Supersession event '' is blank, stale, acknowledged, reset-superseded, missing preserved refs, or conflicts with an existing recovery branch.

Related tools

• shipper_get_issue
• shipper_reset