shipper status

Usage: shipper status [options]

Show a read-only Shipper workflow dashboard

Arguments

Argument	Required	Description	Choices
None	-	-	-

Flags

Long	Short	Value	Default	Description	Choices
—json	-	-	false	output the status snapshot as JSON	-

Examples

Show a compact repository workflow dashboard.

shipper status

Print the same status snapshot as JSON.

shipper status --json

Exit Codes

Code	When
0	The summary is printed successfully, including when no matching issues exist or supervision delivery is degraded or unknown.
1	Prerequisite checks, local issue-state or auto-ship-state unavailability, malformed data, snapshot building, or rendering fails.

Constraints

The supervision diagnosis is unregistered, unresolvable, pickup-unconfirmed, supervised, or unknown. Missing registration says: Run shipper auto-ship enable from a checkout of owner/repo. Unresolvable aliases include the actual path/cause and restoration/access/replacement action. Pickup unconfirmed is neutral: check again after roughly five seconds; available evidence may not establish the cause. Current-host repository evidence and dispatch ownership confirm pickup; a host connection, owner alone, or zero running work does not. Unknown registry evidence is never an empty registry. An enabled repository leaving supervision produces a named daemon warning and auto-ship-supervision-lost diagnostic.
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.
The Auto-ship observation section reports the registry Auto-merge choice independently of daemon availability, locally observed Ready-stage work separately from verified remote merge eligibility, and each known active merge hold with its clearing action. Only an actual scheduled admission retry is shown as a merge retry. Change the durable choice with shipper auto-ship auto-merge on|off; new registrations start off.
Observation health reports normal, waiting, warning, error, inactive, or unconfirmed evidence with episode age, current reason and phase, and the next observation or explicit absence. Advisory health retains successful status exit behavior. Use shipper auto-ship retry-observation for deliberate recovery of unrelated unfinished observation.
Local eligibility is unverified immediately after a failed local read, with immediate diagnostics, warning after 30 seconds, and error after 120 seconds. Ordinary local checks retry approximately every four seconds; the first successful local check clears this condition automatically without Resume, acknowledgement, or restart, even if later GitHub work fails. localEligibility records verification, last success, first/latest failure, consecutive failed checks, cause, severity, and the separate next local check or blocking reason. heartbeat retains the original deadline, blocked/observing progress, last attempt, next remote opportunity, and last completed observation; overdue work completes once without catch-up bursts. Existing quota, ownership, safety, halt, pause, and capacity controls still apply. Disabled health is inactive with no retry promise; restart or re-enable begins unverified with a fresh episode while diagnostic history remains. Unrelated unexplained observation still warns after five minutes.
Read-only: does not advance workflow labels, acquire or release locks, create or remove worktrees, or edit GitHub issues or pull requests.
Pipeline counts include open Shipper-managed issues only. Mirror pending attention counts include active records and retained tombstones without returning tombstones to the pipeline.
Shows counts by stage and control state without per-issue enumeration. Held issues are counted separately from failed even when failed state is also preserved.
Mirror pending is the fifth attention condition and always includes total, repairable, and notCurrentlyRepairable. Human output uses the exact labels Mirror pending (repairable) and Mirror pending (not currently repairable) and points to shipper issue reconcile --repair when nonzero.
Human and JSON output include effective mirror mode, transport, pull-request, review-delivery, and base-integration policy.
The Auto-ship section is repository-state based and accurate without a running daemon. The headline distinguishes not enabled, enabled, enabled but suppressed, and suppressed (auto-ship not enabled). An engaged safety stop takes headline precedence over disabled desired state.
A durable operator halt is reported on its own Halt: line, independently of enablement and safety suppression, and names shipper auto-ship clear-halt, the Desktop Clear halt action, and the MCP tool shipper_clear_auto_ship_halt. The phase is derived from observed runtime evidence only: Draining when the daemon reports draining automatic work, Halted when it reports none, and Halt requested when in-flight work is unconfirmed or runtime facts are unavailable. No status ever reports that a halt was consumed or automatically cleared.
Suppression reports its engagement time, all three distinct qualifying conditions, their issue/repository/legacy scope and changed/recurred relation, and first versus repeat lifetime engagement wording. For recovery, run shipper auto-ship resume in a terminal, select Resume next to Auto-ship in Desktop, or invoke the MCP tool shipper_resume_auto_ship.
When launch-failure retry episodes are live, human output adds Launch retries entries with repository or issue scope, the latest issue identity, consecutive attempts, latest reason/command, and either the effective ISO next-attempt time or cooled-scope-change/heartbeat recovery conditions. JSON exposes the same strict launchFailureRetries projection. Auto-ship remains enabled, and there is no Resume or clear-retry gesture.
When merge-attemptability episodes are live, human output adds Merge waits entries. Backoff names the PR, current reason, attempt N of 5, and exact next ISO time. Parked names the last reason, wait start, retained Ready state, that no agent stage ran, and automatic re-evaluation when the pull request is attemptable or its head changes. JSON exposes the same strict mergeAttemptability projection. Auto-ship remains enabled; these waits are not failed and have no manual resume gesture.
JSON preserves the independent enabled, workerCount, haltRequested, and suppression facts rather than adding a lossy lifecycle enum, and carries the normalized automaticWork runtime status alongside them as a separate top-level fact with its own inFlight and drainInProgress values or an explicit unavailable marker.
Human output adds neutral Remote watch and Shared quota lines. Remote watch is inactive when disabled, active while observing normally, or quiescent (wakes automatically; next heartbeat <ISO time>) during a quiet interval. Quiescence is not safety suppression, does not make Auto-ship disabled, self-resolves with no resume action required, and is separate from observation health and its retry gesture.
JSON exposes repository-scoped remoteWatch and runtime-global quotaPressure directly. Quiescent remote watch includes nextHeartbeatAt; quota includes one of healthy, guarded, severe, floor, or unknown plus nextObservationAt, where 0 means observation is due now. It does not expose raw quota counters or derived admission-effect booleans.
Unavailable remote-watch or quota facts are explicit status: unavailable markers with a reason and message. They mean unknown, never inactive, healthy, zero, or false, and do not change an otherwise healthy status exit code.
Supervision delivery is healthy, degraded, or unknown. A connection is degraded only when a supervision state write accepted by the daemon remains incomplete for at least 10 seconds; equal accepted and completed progress remains healthy indefinitely during idle or quiescent operation. Degraded human output names every affected client, oldest scope, outstanding count, and oldest age. JSON additionally includes degradedConnectionCount, sorted activeScopes, attachment identity, socket liveness, outstandingStateDeliveryCount, and oldestOutstandingStateDelivery with the oldest acceptance time. Timing is omitted when no delivery is outstanding.
Supervision delivery is advisory: delivery-only degradation still exits 0 and clears immediately when overdue writes complete or the connection is removed. A peer or historical record without health fields is unknown (legacy-peer), never inferred healthy. Reachability remains independent from delivery health, and an open socket cannot override a degraded delivery.
Operational facts are advisory read-only observations without GitHub access. Status may briefly attach to a reachable daemon for current delivery health, closes the inspection connection, and can reset the daemon’s existing client-free idle grace period; it never starts or mutates the daemon.
The Dispatch ownership section is a local repository fact with distinct not-held, held, and unavailable states. Held output names the surface and PID, acquisition time, liveness, Last refresh (diagnostic context only), and this consequence: While dispatch ownership is held, any other scheduler on this machine stands down rather than dispatching for this repository.
A healthy held repository still exits 0. Held ownership is informational and repository-scoped; it does not by itself make status degraded.
Unavailable dispatch ownership means inspection is unknown, names no holder, and instructs the operator to resolve the read failure. It is never rendered as not held.
Use shipper auto-ship clear-dispatch for a non-mutating preview and add --force only after reviewing the exact holder and concurrent-schedulers warning. Recovery does not change Auto-ship desired state.
Unreadable auto-ship state is rendered explicitly unavailable, never as not enabled, and makes CLI status exit 1 while independently available workflow facts remain visible.
A future-schema or valid foreign-identity Auto-ship record is a compatibility conflict, not corruption. Human and JSON status include the retained path and structured conflict, omit enabled, worker-count, halt, and suppression defaults, preserve the bytes, and provide only the conflict-specific current-client/install or external-file remedy. There is no Shipper repair, reset, or discard command for either conflict.
When local issue state is unreadable, JSON represents each affected value with an explicit unavailable marker containing status, reason, message, and recoveryCommand; it never substitutes zero or false.
issueFetchLimitReached is no longer present in the JSON contract because local inventory reads are uncapped.
On degraded local state, this CLI command intentionally exits 1, while the MCP shipper_status tool returns a successful structured response with the same recovery pointer.
A healthy nonzero Mirror pending count does not change the status exit code and cannot be dismissed; local-state unavailability preserves the whole attention object as unavailable instead of showing a false zero.