shipper ship

Usage: shipper ship [options] [issue]

Run the full workflow end-to-end

Arguments

Argument	Required	Description	Choices
[issue]	no	Shipper issue ID, gh:, or GitHub URL	-

Flags

Long	Short	Value	Default	Description	Choices
—merge	-	-	false	merge the ready change after reaching shipper:ready	-
—auto	-	-	false	run autonomous continuous shipping loop	-
—parallel	-		-	number of parallel slots (requires —auto)	-
—ignore-dispatch-lease	-	-	false	bypass the auto-ship startup guard for unsupported concurrent operation	-
—mode	-		default	execution mode: headless, interactive, or default	headless, interactive, default
—agent	-		-	agent to use: claude, codex, copilot, grok, or opencode	claude, codex, copilot, grok, opencode
—model	-		-	model to use for the agent CLI	-
—reasoning-effort	-		-	reasoning effort to pass to the agent CLI	-
—disable-mcp	-	-	-	disable MCP server loading for this run	-
—enable-mcp	-	-	-	enable MCP server loading for this run	-

Examples

Run S#42 through the workflow and merge it.

shipper ship S#42 --merge

Run the autonomous shipping loop with three parallel slots.

shipper ship --auto --parallel 3

Exit Codes

Code	When
0	The issue or auto run completes without a terminal failure.
1	Preflight, validation, stage execution, an immediate durable merge condition, or auto-ship execution fails, including a selection-time Ready exclusion or repository safety stop engaged or observed after startup and durable-state storage failures.
75	A single-issue ship run pauses because the pause sentinel is present.
76	A single-issue ship run encounters an active retriable merge failure.
77	A merge failure is successfully routed to Rework or PR Open.
78	A single-issue ship run returns a typed merge deferral, including pending checks or an untimed run skip.
79	Clean GitHub-outage waiting is exhausted. The issue retains its stage, is skipped for the current run, and remains eligible in a later run.
80	CLI auto-ship is refused before any issue attempt because a running or could-not-determine dispatch holder exists. This outcome records neither progress nor a qualifying condition in the durable safety ledger.
81	CLI auto-ship is refused before any issue attempt because the durable repository safety stop is already engaged. This non-bypassable refusal takes precedence over exit 80.
82	An attended TTY agent session actually starts but ends without complete valid artifacts. The issue retains its entry stage as a neutral operator cancellation.

Constraints

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.
—disable-mcp and —enable-mcp are mutually exclusive
After an attended TTY agent session actually starts, Shipper validates its artifacts once. Complete valid artifacts finish normally even after a nonzero agent exit; missing, partial, or invalid artifacts cancel with exit 82. Cancellation retains the entry stage with null repository-safety impact, runs no correction or agent retry, creates no failed or recovery state, and requires no recovery action. Saved headless groom questions remain resumable. Committed workflow-branch HEAD is reused with continuation context on a later invocation while uncommitted work is removed during teardown. Compound next, ship, and automatic grooming runs start no later stage or issue after cancellation. This terminal outcome is distinct from the resumable exit-75 pause. Non-interactive runs retain their bounded output correction, retry, failure, and recovery behavior.
—auto and an explicit issue argument are mutually exclusive
An issue argument is required unless —auto is used
—auto and —mode are mutually exclusive
—parallel requires —auto
—parallel must be a positive integer
SHIPPER_PAUSE_SENTINEL_FILE names a mode-0600 schema-v1 JSON record whose origin is operator-pause, operator-stop, or repository-control. Empty, malformed, or otherwise unrecognized legacy content falls back to operator-pause; the two Stop origins exit at a safe checkpoint without creating a durable operator hold.
Before checking dispatch ownership, CLI auto-ship reads the durable repository safety stop. An engaged stop refuses startup with exit 81 before any run, log directory, selection, or stage work begins, even when --ignore-dispatch-lease is present. Exit 81 takes precedence over the lease refusal at exit 80.
The safety-stop refusal names the canonical repository, all three distinct qualifying conditions, and whether this is the first engagement or how many times the stop has engaged. Repository conditions name the affected object without an observer issue; migrated entries say identity is unavailable.
There is no safety-stop override. To resume an engaged safety stop: run shipper auto-ship resume, select Resume next to Auto-ship in Desktop, or invoke the MCP tool shipper_resume_auto_ship.
Before choosing the sequential or parallel runner, a normal CLI auto-ship drain atomically claims repository dispatch ownership with the Terminal surface directly. At most one supported automatic drain runs per repository, whichever of Terminal, Desktop, or the Shipper daemon arrived first. The exact Terminal ownership is released after normal completion, an error, SIGINT, or SIGTERM. A missing record or proven-dead holder is replaceable; running and could-not-determine holders remain occupied until normal release or deliberate operator recovery.
A complete holder-identity envelope from a newer version or an unknown surface remains occupied and is reported as unrecognized with its PID, acquisition time, and last refresh time. A canonical repository identity and positive holder PID with incomplete details, such as an invalid timestamp, still block dispatch while the process is alive or its liveness cannot be determined; public ownership is unavailable without guessed holder details. Invalid JSON, missing or invalid PID, incomplete repository identity, noncanonical identity, and wrong-repository identity are absent and healed by the next acquisition.
A dispatch refusal exits 80 and names Desktop, the Shipper daemon, Terminal, or an unrecognized holder surface, plus the holder PID, acquisition time, and last refresh as diagnostic context only. Use shipper auto-ship clear-dispatch to inspect the same holder facts and shipper auto-ship clear-dispatch --force only after reviewing the concurrent-schedulers warning. For Desktop or daemon, disabling Auto-ship remains a graceful alternative: running automatic Ships receive repository-control Stops at their next safe checkpoint and ownership is released after the supervisor observes the change. For Terminal, wait for the drain or interrupt its process. For an unrecognized surface, wait or stop the originating PID without guessing its surface.
--ignore-dispatch-lease bypasses only this startup guard for unsupported concurrent operation. It warns when a running or could-not-determine holder is actually overridden, but stays quiet when no held ownership exists. It does not coordinate schedulers, transfer or acquire ownership, or make concurrent operation supported.
An overriding --ignore-dispatch-lease drain only inspects ownership: it publishes no claim and releases nothing, so no supervisor stands down. Manual single-issue shipper ship S#42, shipper next, and shipper groom --auto neither inspect nor publish dispatch ownership and are unaffected.
Troubleshooting: failed issues and rollback loops
Troubleshooting: adopted PR closed or superseded
Troubleshooting: merge failure outcomes and exit codes
Auto-ship follows the canonical failure-outcome and repository-safety contract. Its repository safety stop engages after three distinct qualifying condition instances. Repeating one unchanged condition is a duplicate; a revision change or successful repository advancement makes a later observation a new instance.
A locally committed advancement whose GitHub content, labels, comments, or closure remain Mirror pending exits 0 and stays neutral for safety-stop accounting. A fully eligible successful advancement increments the durable progress generation; it does not clear earlier pending strikes.
Current qualifying identifiers are terminal-stage-failure, merge-retry-exhausted, pending-checks-exhausted, groom-output-invalid, worktree-setup-contention, and upstream-merge-wait. Historical safety records may retain merge-remediation-exhausted; no current producer emits it. Every producer supplies one current classification or explicit null; omission is rejected instead of defaulting to neutral or counted.
Blocked entry refusal and blocked post-work stop are explicit neutral outcomes. When post-work advancement is present, it advances the durable progress generation before the neutral blocked outcome is processed.
In a pull-request-disabled repository, auto-ship reports a Ready issue without a packaged local change as ⊘ excluded, records the same durable failed outcome as an attempted prerequisite failure, and starts no issue attempt. The command exits 1 because operator action is required, but the exclusion is neutral for the repository safety ledger: it records neither progress nor a condition.
Exit 79 is unsuccessful but neutral for the auto-ship safety stop: it records neither progress nor a qualifying condition.
Sequential and parallel auto-ship share the same durable repository-scoped rule. Parallel mode applies completed outcomes in receipt order, stops refilling slots once the threshold is reached, drains work already in flight, and abandons parked work. The early-stop summary lists the triggering conditions and any eligible issue that was not attempted.
At PR Open, background Auto-ship parks an issue before review when the current pull-request revision has not reached its configured review window or check readiness. The completed park outcome releases the issue lock and sequential or parallel worker slot, allowing other issues to run. Auto-ship probes the current head, resets its deadlines when that head changes, and starts a fresh issue run only when the current revision is ready. Shutdown, drain, or safety-stop abandonment is neutral: the issue remains at PR Open with no agent launch, failure, advancement, or safety condition.
CLI and supervisor submit to one file-locked durable ledger from strike one, so pending accounting survives process exit. Logical identity is qualifying kind, scope, condition type, and issue or repository subject; revisions and progress epochs distinguish changed/recurred instances. Admission generations fence completions after resume or re-enable.
A run that engages or observes the stop after startup exits 1 and reports the authoritative durable failures, first or repeat engagement count, and the terminal, Desktop, and MCP resume gestures. Exit 81 is reserved for a stop already engaged at startup. A safety-state read or write failure after startup also exits 1, stops new/resumed/unblock work, drains active work, and never falsely claims durable engagement.
The pending-check clock is keyed by PR head SHA and uses merge.pendingChecksTimeoutMinutes (default 60); a new SHA or process restart resets it.
Typed merge causes, never diagnostic reason text, select retry, Rework implementation, PR Open review, or immediate-failure behavior.
The pr_review pre-flight owns the initial review window, check settling, failed-check rerun, and flake decision at a revision-pinned pull-request head. A whole-rollup green rerun at the identical commit posts durable evidence, invokes no reviewer, and leaves the issue at PR Open. Failed, pending, unavailable, incomplete, or moved-head results consume no allowance. At most two successful decision cycles may be deferred for the lifetime of that issue and pull request across revisions, restarts, reset, and recovery; this counter is separate from merge retry accounting. Failed-check reruns use an independent clock from each request: 60 minutes for timer review and a 60-minute minimum in checks mode, honoring longer maxima or an unbounded explicit policy. Original deadlines survive retries. No reviewer launches while any tracked rerun is pending or unverifiable, including mixed pending/failed batches. Manual review and Ship return at finite expiry with PR Open and run links; Auto-ship parks, then defers for the current pass without an agent run and continues other issues. Retry shipper pr review S#42, shipper ship S#42, or a later Auto-ship run; same-revision retries observe the existing request. For ambiguous dispatch, inspect Actions and request the rerun there if necessary before retrying. Completed confirmed failures become must-fix findings and reach Rework even if the reviewer approves or the aggregate rollup is unavailable or contradictory. No-request confirmed failures still review. Successful all-green batch decisions count exactly once. Ordinary first-run pending-check behavior and local-only review remain unchanged.
Required approval is an untimed run skip: the issue remains Ready, consumes no retry attempt, and can merge after approval.
A fifth retryable merge failure retains the issue stage and failed flag, skips it only for this invocation, emits one issue-scoped safety condition keyed by its merge evidence and head revision, and is automatically eligible in a later invocation. Three distinct qualifying condition instances engage the repository safety stop.
Pending-check expiry remains a durable failure. Review and Rework routes create no merge-loop exhaustion; every other stage-retaining merge outcome is neutral for the repository safety stop.
Missing Ready prerequisites such as the packaged change, GitHub mirror, linked PR, or PR record fail durably with a concrete recovery command. No usable repository merge method also fails immediately with repository-setting guidance.
A design or plan reject that rolls an issue back to shipper:new is a clean successful return for grooming, never applies failed state by itself, and exits zero.
Auto mode reports that outcome distinctly as ↩ returned — grooming required, does not count it as pass or fail, and skips the issue for the rest of the current drain.
CLI Auto-ship immediately re-checks blocked, non-New direct dependents after each successful merged result. Targeting includes native Shipper blockers and GitHub issue numbers mapped to an active or tombstoned managed issue; it excludes transitive dependents and unmapped external GitHub blockers.
The targeted re-check does not wait for repository idleness or worker capacity, does not preempt running work, and does not promote the released issue. Safety, lock, pause, quota, and dispatch controls still apply. Remaining unresolved blockers stay silently Blocked. The idle untargeted sweep remains the backstop for unmapped external GitHub blockers and uses the same automatic-unblock status.
On macOS, manual Ship and Auto-ship prevent idle system sleep while they have running, draining, or deadline work. Durable halt and recovery-only quiescence do not. See Keep the Mac awake during active work.