shipper_advance

Advance an issue by one workflow stage (shipper next). Dispatches to the appropriate stage command based on the current label. Runs in headless mode — may take several minutes for implementation and PR review stages. For a fresh shipper:new issue, use shipper_groom first.

When to use

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. On macOS, this tool prevents idle system sleep while it performs progress-capable work; a durable saved session with no live worker does not. See Keep the Mac awake during active work. Use this for the normal one-step workflow progression once an issue has moved past intake. Fresh shipper:new issues still require shipper_groom. When New has a saved question session, advance delegates to the ordinary grooming boundary: an MCP-owned session may resume, while a foreign or unowned session returns a neutral Status: refused stand-down without changing stage, failure state, or saved content. An operator-paused issue refuses by default. Set override_pause: true only to authorize this exact named manual advance and its matching answer rounds; the durable pause remains visible and effective before, during, and after the operation and cannot be reused by later or automatic work. A graceful Stop returns Status: stopped after retaining the completed stage or saved question boundary. A completed design or plan reject is a successful stage outcome, not a failure or a new verdict; when its rollback reaches shipper:new, the issue has returned cleanly for grooming and remains unfailed. A shipper:designed issue whose stored route is simple runs one combined implementation-and-delivery step instead of planning; on acceptance it reports shipper:designed -> shipper:pr-open (accept), and on rejection it succeeds at shipper:designed and adds a Route: simple -> complex (permanent) line, meaning the next advance runs planning. Exactly one stage runs per call either way. Design assigns the route: an accepted design result must declare simple or complex with a nonblank one-line reason, and omitting either is invalid stage output rather than a silent default. The accepted design review states the decision under an ## Issue Route heading, and the durable audit trail is the route_change entry in the workflow history for that issue. Routes are monotonic — simple may escalate to complex, but complex never returns to simple. The configured agentTimeoutMinutes limit applies independently to each agent attempt; MCP adds no stage-wide deadline, so ordinary retries, corrections, cleanup, projection, run recording, and finalization remain child-owned. Time paused awaiting product-owner answers consumes no agent-running timeout. A terminal timeout returns only after authoritative local agent_timeout history, failed workflow state, terminal MCP-attributed run status, and ownership-safe release of that run’s issue lock. In mirror-on mode, projection debt never rolls back the local failure or retains the lock and is explicitly repairable with shipper issue reconcile --repair. The timeout report identifies the stage, per-attempt limit, attempt count, available session log, discarded staged/unstaged/untracked work, and exact same-stage reset command. When commits survived, that matching reset preserves only the recorded unchanged workflow branch revision—not the physical worktree—and the next groom or scaffold run continues from it; a missing or moved ref invalidates continuation.

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.
override_pause	boolean	no	false	Authorize only this named manual advance and its answer rounds while retaining the durable operator pause.

Example call

{
  "issue": 42
}

Example result

Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages
Stage: shipper:planned -> shipper:pr-open (accept)
PR: https://github.com/owner/repo/pull/17

---
Implementation complete.

Session log: /tmp/shipper/session.log

Error modes

Grooming required: S# (GitHub #) is at shipper:new. Use shipper_groom to groom the issue; once it moves past shipper:new, retry this tool.
Saved session owned by another surface: Status: refused. The saved grooming session owner or unowned state, last-saved time, answered-round count, and pending-batch presence are reported without question or answer content. Use shipper_groom with deliberate takeover only after human confirmation.
Enriched completion summary unavailable: After the worker completes, a post-completion label, session, or linked-PR lookup can fail. The tool returns the plain observed worker result, any locally resolved final message and session log, plus Enriched completion summary unavailable. and Reason: <underlying error>; an exit-0 worker remains successful.
Mirror-on pre-completion GitHub lookup failure: When issue mirroring is enabled, a GitHub lookup that fails before worker completion remains a tool error: Command failed: gh
Operator paused: S# (GitHub #) is deliberately paused by an operator since . Resume it or use ‘shipper unlock S# —force’ to force unlock it.
Timed out worker: [timed out] shipper next —mode headless
Failed worker: [exit ] shipper next —mode headless


Adopted PR closed or superseded: Adopted PR # for S# (GitHub #) is no longer open or was superseded. Re-adopt the current PR with shipper adopt <pr-number>; Shipper will not guess a replacement automatically.


Related tools
Section titled “Related tools”

shipper_get_issue
shipper_get_pr
shipper_answer_question