shipper reset

Usage: shipper reset [options]

Reset local workflow state to a valid recovery stage

Arguments

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

Flags

Long	Short	Value	Default	Description	Choices
—force	-f	-	-	skip confirmation prompt	-
—to	-		-	reset to a specific workflow stage	-

Examples

Reset S#42 without prompting.

shipper reset S#42 --to groomed --force

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.

Publication failures and reset scope

A terminal publication report is written only after an attempted Git push remains unsuccessful under the existing retry policy. An observed nonzero pre-push hook status establishes local pre-push rejection. A Git rejection naming the attempted destination establishes remote rejection; GitHub is named only when the repository/destination evidence supports that attribution. Affirmative transport evidence establishes transport failure. Otherwise the cause is unavailable. Executor failure or capacity denial alone does not establish transport or hook rejection. Preparation, PR-service, teardown, and local-only failures remain separate. A failed publication does not establish missing or invalid agent output or invent a failing check.

The report captures independently available source branch, checkout path, full commit ID, and observation time immediately before the terminal attempt. Its approximate plain reachable-commit count compares the tip with the locally available destination remote-tracking ref. Only proven local absence selects the labelled configured-base fallback. A failed comparison leaves the count/ref/fallback unavailable with separate reasons. These diagnostic reads perform no remote lookup, fetch, staleness analysis, topology assessment, or uncommitted-file inventory.

The combined raw excerpt, including omission markers, is limited to 4096 UTF-8 bytes without splitting characters. Metadata, full paths, tips, and unavailable reasons sit outside that limit. Publication evidence files are under ~/.shipper/logs/ and show their actual path plus complete, incomplete, or unavailable status. An available path alone does not imply complete evidence. Agent/session logs are separately labelled and are not the publication evidence log.

Destructive reset discovers exactly the selected/invoking checkout plus the existing named managed clone. Local lineage repositories have only their selected checkout. Missing managed clones are not created or refreshed, and arbitrary clones are not searched. Checkouts sharing a canonical Git common directory are one branch set with their aliases displayed; separate clones with identical branch names remain distinct plans. Existing branch-recognition tiers are unchanged.

Before deletion, the preview shows each branch’s owning checkout, full tip or tip-unavailable reason, delete/retain/skip disposition, aliases, and discovery limitations. Normal main/user/linked checkouts holding a recognized branch are protected and retained; eligible issue worktrees are removed before branch deletion. Unknown identity, eligibility, or safety is skipped with a reason and reported as incomplete discovery. An unavailable tip alone does not prohibit an otherwise eligible deletion. CLI force skips confirmation only and still prints this preview. MCP dry-run is read-only; direct confirmed execution displays the same captured scan before its outcomes and preserves existing confirm_discard semantics. Desktop confirmation consumes its displayed plan; a missing or consumed preview requires a fresh preview.

Operations identify their owning checkout and distinguish successful deletion, intentional retention, already-absent/missing skips, and failed discovery or cleanup. Safe cleanup continues in other known locations after failures; scan, prune, deletion, or required-holder removal failures prevent full-success wording and the final success transition. PR/remote cleanup remains once per issue under existing guards. A later reset invocation rescans for retry. There is no added local tip/identity/safety re-verification between a captured preview and deletion; existing operation-level reclamation and PR guards still apply.

New validated publication-failure comment groups and captured run-history diagnosis survive reset as historical evidence. A reset, later transition, or newer different failure makes the older report historical rather than restoring current Failed state. Older Agent Failure headings are not inferred or rewritten. Preserving Rework keeps its existing eligibility, token, package, branch, and history behavior with empty destructive plans. These observations and best-effort cleanup provide no new retention or recovery guarantee.

Exit Codes

Code	When
0	The issue is reset to the selected valid recovery stage and mirrored to GitHub.
1	Validation, issue lookup, confirmation, cleanup, store, or mirror 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.
Design, Plan, Implement, Review, Rework, and Ready name next work. Designed simple issues next Implement; complex or undecided issues next Plan. Packaged work next Review in either PR mode. Ready means ready for final integration, not shipped. New stays separate; held and failed are excluded (hold wins), while blocked, locked, paused, and running retain membership. CLI/MCP retain six next-step groups; desktop has five columns, with Implement combining Implement and Rework for the same population and attention exclusions. Current nextStep and nextStepPipeline are additive; completed-stage pipeline fields, labels, filters, commands, reset arguments, and historical records retain their meanings. Maintained label descriptions automatically refresh during next normal setup or maintenance, without separate initialization; successful cache skips repeats and force refresh reads again. Read-only status makes no label writes.
Reset wording leads with the next step and completed-stage target. Design drops target groomed and clear route; Plan drops target designed for complex or undecided and refuse simple without changing route; Implement drops prefer preserving rework when offered by existing reset eligibility, otherwise designed for simple, planned otherwise. The authoritative package preview can refuse confirmation without destructive fallback. Deliberate Start over is in the card Reset menu with cleanup confirmation. Review and Ready reject drops; non-failed same-column drops do nothing, including Rework in Implement. The current-state Rework badge disappears on return to Review; other bounces receive no badge. Plan column differs from —to planned, whose next step is Implement. Existing backward eligibility, failed retry, preserving Rework, active restrictions, confirmations, work-loss warnings, and preservation guarantees apply.
Every successful Rework reset appends durable local review-rework history with reason operator-reset; automatic review rejection records review-reject and pins its newly retained round, while merge conflicts use merge-conflict. Review rejection supersedes only older unaddressed, unsuperseded rounds for the current package and counts every completed current-package round since the latest renewal, including addressed and superseded rounds, toward the current five-round allowance. A zero-finding round is addressed but still counts. A sixth rejection enters durable Failed over Rework with its retained round pinned; shipper recover clears failure while preserving Rework and that pin. A replacement package starts a fresh count. Manual reset still selects the newest unaddressed, unsuperseded round, while a later roundless entry takes precedence, without inventing a rejection. PR identity and a durable local package UUID scope all retrieval. History survives restart. Before commitment, history failures leave prior state unchanged. After commitment, Reset committed; local recovery pending means store access will finish the existing journal operation; do not repeat reset. These entries publish no GitHub reviews or comments and add no history screen.
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.
Reset commits the target stage to the local issue-state store before mirroring workflow labels.
For earlier targets, later-stage workflow events remain in the local event log as superseded history; reset deletes only their GitHub comment projections and records projection repair state for reconcile.
Attributed issue notes are exempt from reset cleanup regardless of their attribution stage. They remain rendered locally and mirrored when enabled; only explicit note retraction can withdraw them.
Priority is preserved. Failed state is cleared.
For earlier targets, if an open linked pull request is present, reset closes it and clears its stored association. For an adopted pull request, the foreign head branch is preserved but the association is still cleared.
The destructive open-PR warning is printed even with --force; --force skips only the confirmation prompt.
Reset-to-New also warns before discarding preserved grooming output or a saved grooming question session, including with --force, and deletes them only after the local reset transition commits. The preview reports how many question rounds were answered.
shipper recover is the preferred non-destructive action for a failed issue whose question session, groom output, packaged local change, or linked pull request remains recoverable. Session recovery clears failed state while retaining the conversation and its recorded owner; another surface must take over before resuming it.
Branch cleanup recognizes local-ID branches under the current generatedBranchPrefix and the built-in shipper/ fallback. Legacy numeric branches are recognized only under shipper/; historical custom prefixes are not recognized.
Deleting a remote branch that reset already selected for cleanup skips Git’s pre-push hook, so pre-push verification never begins for that deletion and no verification record is created for it. A verification record always means a hook actually started, so its absence here is expected rather than missing evidence.
That exception is limited to reset cleanup deletion. Branch creation, branch updates, and branch deletion outside reset keep their existing pre-push verification, and no option, flag, or other reusable way to skip verification is exposed.
Outside Rework, same-stage reset is allowed only when the issue is failed and still carries that workflow stage label.
Outside the explicit preserving Rework source rules, non-failed same-stage reset and all forward targets remain rejected.
Reset targets are route-aware. Packaged complex and undecided issues offer Rework (recommended), Planned, Designed, Groomed, and New. Packaged simple issues offer Rework (recommended), Designed, Groomed, and New. Only eligible choices are shown.
A target refused because of the route is refused with a route-specific explanation naming the route, not the generic backward-only or invalid-target error, and the same explanation is used on the CLI, the MCP reset tool, and the desktop.
The stored route is cleared back to undecided exactly when Design will re-run — that is, at the Groomed and New targets. Resetting to Designed, Planned, or Rework preserves the stored route, including a route that was escalated from simple to complex.
Reset-driven route clearing writes its own route history entry recording reset as the source, the prior route, the resulting undecided route, and the reset target as the reason. The reset summary entry does not restate it.
Troubleshooting: failed issues and rollback loops