Skip to content
Shipper

shipper_pause_issue

shipper_pause_issue

Section titled “shipper_pause_issue”

Place the shared Desktop/MCP operator pause on one local issue. Running checkpoint-capable work is asked to stop safely and reports pending; queued automatic work is withdrawn before the durable pause is acknowledged.

When to use

Section titled “When to use”

Use to place the shared issue-level operator pause. Idle issues become durable immediately, queued automatic work is withdrawn transactionally, and a registered live worker reports pending until its safe checkpoint releases ownership.

Behavior hints

Section titled “Behavior hints”
  • readOnlyHint: false — The tool may intentionally modify repository or workflow state.
  • destructiveHint: false — The tool is not expected to remove or rewrite workflow artifacts.
  • idempotentHint: true — Retrying the same call is expected to be safe once the target state is reached.
  • openWorldHint: false — The tool does not reach GitHub or other external systems outside the MCP server.

Input schema

Section titled “Input schema”
NameTypeRequiredDefaultDescription
issueinteger | stringyes-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.

Output schema

Section titled “Output schema”

object

Example call

Section titled “Example call”
{
  "issue": "S#42"
}

Example result

Section titled “Example result”
{
  "status": "paused",
  "issue": "S#42",
  "pause": { "state": "durable", "paused_at": "2026-09-04T12:00:00.000Z" },
  "changed": true
}

Error modes

Section titled “Error modes”
  • Local issue-state replica not initialized: Local issue-state replica is not initialized for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
  • Local issue-state replica present but not fully reconciled: Local issue-state replica is present but not fully reconciled for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
  • Local issue-state replica schema unsupported: Local issue-state replica has an unsupported schema for owner/repo. Locally reconstructable older replicas migrate automatically on first issue-state access. Run shipper issue reconcile --repair for supported local-ID V3 blocker imports requiring GitHub data or ordinary current-store repair. Numeric snapshots in issues/<GitHub-number>.json or _pending-blocker-imports/legacy/<GitHub-number>.json refuse the entire store, listing all affected records and leaving existing local issue state unchanged. This Shipper version no longer migrates GitHub-number issue snapshots. Use a Shipper release from before this change to migrate the store before retrying this version. Fresh or recreated stores retain initial blocked-state imports and interrupted-import retries after metadata becomes reconciled; local-ID V3 stored blocker lists can complete locally in store-only mode.
  • Local issue-state replica malformed: Local issue-state replica is malformed for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
  • Running issue-state reader stale: The running Shipper issue-state reader is stale for owner/repo: observed store schema v10 is newer than supported schema v9. Restart or reconnect the MCP client and server. If a freshly launched server remains incompatible, update the installed Shipper release or rebuild the source checkout before reconnecting. Preserve the issue-state store unchanged.
  • Worker not checkpoint-capable: Pause is refused without stopping the worker; use shipper_stop_issue for guidance.
  • Queued supervisor unavailable: No hold is created unless the exact queued session can be withdrawn.
Section titled “Related tools”