shipper_set_auto_ship
shipper_set_auto_ship
Section titled “shipper_set_auto_ship”Change the active repository’s machine-global auto-ship desired state in one atomic write. Supply at least one of enabled, worker_count, or halt_requested. Fields not supplied are preserved exactly, so enabling never clears a halt; supply halt_requested: false in the same call for an atomic combined enable-and-clear. This local machine state mutation requires successful checkout registration before recording the entire requested enable patch. Registration failure means enablement did not complete and preserves the prior enabled setting and every other supplied field. Unreadable registrations are preserved unchanged; use a build able to read them or restore the damaged file. An explicit enable then makes a bounded attempt to provide a supervisor, and reports exactly one availability outcome: available, not-started, incompatible, or indeterminate. Host availability is separate from repository supervision/pickup and automaticWork. Successful recording can have Pickup unconfirmed; check shipper_status after roughly five seconds. Switch to the repository checkout and explicitly enable Auto-ship to recover missing registration. Other mutations do not start or attach to a supervisor; a running supervisor normally observes them within roughly five seconds. Every durable record write returns status recorded or refused. Recorded results use the core applied/unchanged outcomes and disclose any lossless version 1 or 2 migration to version 3. A future schema is retained unchanged and refused with a request for a human operator to re-run Shipper installation or reconnect with a current Shipper client; a valid foreign repository identity is retained unchanged and refused with a request to resolve the file outside Shipper. Refusals contain only status, repository, and conflict—never previous, resulting, outcomes, migration, supervisor, or dispatch facts—and neither conflict has a Shipper repair, reset, or discard gesture. Corrupt replaceable records remain recoverable. Halt, disable, and the automatic safety stop are three distinct states. A halt is a persistent operator-requested repository hold: it preserves enablement and worker settings, survives idle periods, safe-checkpoint wind-down, and process or machine restarts, and ends only through an explicit clear with shipper_clear_auto_ship_halt or a halt_requested false patch. Disable sets enabled false, drains current automatic work, and prevents dispatch until auto-ship is enabled again; neither disabling nor enabling clears a halt, and enabling preserves every field the patch does not supply. The safety stop is an automatic failure safeguard with its own durable latch, its own status, and shipper_resume_auto_ship as its only recovery gesture; safety recovery never clears a halt. Automatic pre-start launch failures use a separate durable launchFailureRetries ledger: attempts one through four wait 30, 60, 120, and 240 seconds, the fifth enters recovery-only quiescence, and cooled-scope changes or the ordinary heartbeat authorize sparse probes without a manual recovery action. A successful automatic or manual start clears the repository episode and that issue episode, issue ineligibility retires issue scope, and disable followed by re-enable clears the enablement ledger. A halt or disabled state requests repository-control Stops for running automatic Ships at safe checkpoints and withdraws queued automatic work. Once enabled and unhalted is observed, unconsumed repository-control requests are retracted while explicit per-run Pause and Stop gestures remain intact. Consumed stops and withdrawn queue entries are not revived; only ordinary future dispatch may make their issues eligible again. Setting halt_requested false records cancellation intent only: there may be no live supervisor, and this response reports no retraction count or observed runtime outcome. Explicit manual work stays available under a repository halt, including hand-driven workflow advances and per-run Pause and Stop actions. Non-enable changes to untracked repositories persist, but no supervisor acts on them and there is no board surface to observe or stop anything. Enabled means requested, not dispatching: an availability outcome, a persistent halt, a launch-retry posture, or a durable safety stop can show that dispatch is not active without changing the recorded enablement value. Inspect shipper_status.autoShip.launchFailureRetries and suppression before concluding dispatch is occurring. Auto-merge is separate and must be enabled by the operator before anything merges. This machine-global operator state follows the machine, is not committed repository configuration, and is not shared with collaborators.
When to use
Section titled “When to use”Use this state-changing local operation only when the operator wants to change the active repository’s auto-ship desired state. It returns status: recorded after a successful write, with core outcomes and optional migration, or status: refused with only repository and conflict when retained bytes cannot safely be interpreted. Future schemas remain byte-for-byte unchanged and use the current-client/install remedy; valid foreign identities remain unchanged and require external file resolution. Neither refusal offers a Shipper repair, reset, or discard command. Explicit enable requires successful registration before the entire desired-state patch, then attempts bounded supervisor availability, and reports available, not-started, incompatible, or indeterminate; an incompatible daemon result is separate from record compatibility and includes all protocol version facts. When enablement succeeds but Terminal or an unrecognized compatible holder currently owns repository dispatch, the optional factual dispatchDeferral reports its surface, PID, acquisition and last-refresh timestamps, and liveness. This deferral is independent of supervisorAvailability: the supervisor may be available while only this repository’s new dispatch waits, and desired state remains enabled. Other mutations never start or attach to a supervisor. Every field is literal: fields the patch does not supply are preserved exactly, so enabling never clears a halt. Supply only worker_count to preserve enablement and halt, supply halt_requested: true for a persistent repository hold, supply halt_requested: false alone as an explicit halt clear, or combine enabled: true with halt_requested: false for an atomic enable-and-clear. Enabled and halted is a valid desired state and is not refused. Halt and disable request repository-control Stops for running automatic Ships at safe checkpoints and withdraw queued work. Once enabled and unhalted is observed, only unconsumed repository-control requests are retracted; explicit per-run Pause and Stop gestures survive, and stopped runs or withdrawn entries are not revived. A cancellation response records intent only and reports no retraction count or observed runtime outcome because no live supervisor may exist. A halt recorded while disabled is accepted, preserved, and inert until a supervisor observes it. Re-enabling an already-enabled repository leaves enablement unchanged and clears neither a durable safety stop nor a halt. Every request that sets halt_requested: true reports whether durable halt intent changed or was already set, states that the hold persists until it is explicitly cleared, and includes the normalized automaticWork evidence it actually observed: draining, idle and held, in flight without confirmed draining, or unavailable. No response describes a halt as consumed or automatically cleared. Use shipper_clear_auto_ship_halt for the discoverable halt-specific clear gesture. Quiescent remote watch is a quiet scheduling mode, not safety suppression, and is separate from observation health: it leaves enabled true, self-clears when work or the heartbeat arrives, and has no resume tool or desired-state mutation. Use shipper_resume_auto_ship only to clear an engaged durable safety stop directly without rewriting desired state. A genuine not-enabled-to-enabled transition remains the other valid safety-stop clear gesture. Observe desired state, suppression, advisory daemon facts, automatic-work counts, remoteWatch, and quotaPressure without mutation through shipper_status. Remote watch reports inactive, active, or quiescent with nextHeartbeatAt; quota reports healthy, guarded, severe, floor, or unknown with nextObservationAt. Unavailable markers mean unknown rather than zero or false, and status remains local-only with no GitHub call or daemon start/attachment. Registration refusal is a tool error before the entire combined patch, including worker and halt fields, and before supervisor startup. The previous enabled setting stays exactly intact, including when already enabled. Unreadable registration bytes are preserved unchanged with compatible-build, valid-copy restoration, or access/lock guidance. If intent recording fails later, successful registration remains and is disclosed in text, including on compatibility refusals whose structured keys remain status/repository/conflict only. Successful enable output includes supervision and automaticWork separately from supervisorAvailability; recording success with Pickup unconfirmed is valid. No checkout sidecar is required to establish membership.
Behavior hints
Section titled “Behavior hints”- readOnlyHint: false — The tool intentionally changes machine-global operator state for the active repository.
- destructiveHint: false — The tool records desired state and explicit enable may register the checkout and start a supervisor, without deleting repository or workflow artifacts.
- idempotentHint: true — Repeating a patch that already matches the recorded state returns unchanged outcomes.
- openWorldHint: false — The tool writes only local machine state and does not contact GitHub or another external system.
Input schema
Section titled “Input schema”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| enabled | boolean | no | - | Resulting requested enablement. Enabling preserves an existing halt; enabled and halted is a valid state. |
| worker_count | integer | no | - | Resulting whole-number worker count from 1 through 4. |
| halt_requested | boolean | no | - | Resulting persistent repository halt. true holds the repository until explicitly cleared; false is an explicit halt clear. |
Deprecated input aliases (one-release compatibility)
Section titled “Deprecated input aliases (one-release compatibility)”The following deprecated aliases are accepted for this release only:
workerCount→worker_counthaltRequested→halt_requested
An alias-only call succeeds and prepends this warning text for each alias:
- Deprecated input “workerCount” was accepted as “worker_count”; it is supported for this release only and will be rejected in the next release.
- Deprecated input “haltRequested” was accepted as “halt_requested”; it is supported for this release only and will be rejected in the next release.
The same ordered warnings are returned in _meta["shipper/deprecation-warnings"] as { alias, replacement, removal: "next-release" } entries.
Supplying both an alias and its canonical input is rejected, even when their values are equal.
These aliases will be rejected in the next release; use the canonical inputs now.
Output schema
Section titled “Output schema”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| status | enum: recorded, refused | yes | - | - |
| repository | string | yes | - | - |
| resulting | object (auto-ship desired state) | no | - | - |
| previous | object (auto-ship desired state) | no | - | - |
| outcomes | object | no | - | - |
| migration | object | no | - | - |
| supervision | object | no | - | - |
| supervisorAvailability | - | no | - | - |
| dispatchDeferral | object | no | - | - |
| automaticWork | object (available automatic-work status) | object (automatic-work unavailable marker) | no | - | - |
| conflict | - | no | - | - |
Example call
Section titled “Example call”{ "enabled": true}Example result
Section titled “Example result”{ "content": [{ "type": "text", "text": "Auto-ship desired state recorded for repository owner/repo.\nPrevious: {\"enabled\":false,\"workerCount\":2,\"haltRequested\":false}\nResulting: {\"enabled\":true,\"workerCount\":2,\"haltRequested\":false}\nOutcomes: {\"enabled\":\"applied\",\"workerCount\":\"unchanged\",\"haltRequested\":\"unchanged\"}\nThe desired state is recorded and a usable supervisor host was reached; repository pickup and running work are reported separately. Pickup unconfirmed.\n\nThis local machine state mutation requires successful checkout registration before recording the entire requested enable patch. Registration failure means enablement did not complete and preserves the prior enabled setting and every other supplied field. Unreadable registrations are preserved unchanged; use a build able to read them or restore the damaged file. An explicit enable then makes a bounded attempt to provide a supervisor, and reports exactly one availability outcome: available, not-started, incompatible, or indeterminate. Host availability is separate from repository supervision/pickup and automaticWork. Successful recording can have Pickup unconfirmed; check shipper_status after roughly five seconds. Switch to the repository checkout and explicitly enable Auto-ship to recover missing registration. Other mutations do not start or attach to a supervisor; a running supervisor normally observes them within roughly five seconds. Every durable record write returns status recorded or refused. Recorded results use the core applied/unchanged outcomes and disclose any lossless version 1 or 2 migration to version 3. A future schema is retained unchanged and refused with a request for a human operator to re-run Shipper installation or reconnect with a current Shipper client; a valid foreign repository identity is retained unchanged and refused with a request to resolve the file outside Shipper. Refusals contain only status, repository, and conflict—never previous, resulting, outcomes, migration, supervisor, or dispatch facts—and neither conflict has a Shipper repair, reset, or discard gesture. Corrupt replaceable records remain recoverable. Halt, disable, and the automatic safety stop are three distinct states. A halt is a persistent operator-requested repository hold: it preserves enablement and worker settings, survives idle periods, safe-checkpoint wind-down, and process or machine restarts, and ends only through an explicit clear with shipper_clear_auto_ship_halt or a halt_requested false patch. Disable sets enabled false, drains current automatic work, and prevents dispatch until auto-ship is enabled again; neither disabling nor enabling clears a halt, and enabling preserves every field the patch does not supply. The safety stop is an automatic failure safeguard with its own durable latch, its own status, and shipper_resume_auto_ship as its only recovery gesture; safety recovery never clears a halt. Automatic pre-start launch failures use a separate durable launchFailureRetries ledger: attempts one through four wait 30, 60, 120, and 240 seconds, the fifth enters recovery-only quiescence, and cooled-scope changes or the ordinary heartbeat authorize sparse probes without a manual recovery action. A successful automatic or manual start clears the repository episode and that issue episode, issue ineligibility retires issue scope, and disable followed by re-enable clears the enablement ledger. A halt or disabled state requests repository-control Stops for running automatic Ships at safe checkpoints and withdraws queued automatic work. Once enabled and unhalted is observed, unconsumed repository-control requests are retracted while explicit per-run Pause and Stop gestures remain intact. Consumed stops and withdrawn queue entries are not revived; only ordinary future dispatch may make their issues eligible again. Setting halt_requested false records cancellation intent only: there may be no live supervisor, and this response reports no retraction count or observed runtime outcome. Explicit manual work stays available under a repository halt, including hand-driven workflow advances and per-run Pause and Stop actions. Non-enable changes to untracked repositories persist, but no supervisor acts on them and there is no board surface to observe or stop anything. Enabled means requested, not dispatching: an availability outcome, a persistent halt, a launch-retry posture, or a durable safety stop can show that dispatch is not active without changing the recorded enablement value. Inspect shipper_status.autoShip.launchFailureRetries and suppression before concluding dispatch is occurring. Auto-merge is separate and must be enabled by the operator before anything merges. This machine-global operator state follows the machine, is not committed repository configuration, and is not shared with collaborators." }], "structuredContent": { "status": "recorded", "repository": "owner/repo", "resulting": { "enabled": true, "workerCount": 2, "haltRequested": false }, "previous": { "enabled": false, "workerCount": 2, "haltRequested": false }, "outcomes": { "enabled": "applied", "workerCount": "unchanged", "haltRequested": "unchanged" }, "supervisorAvailability": { "status": "available" }, "supervision": {"diagnosis":"pickup-unconfirmed","repository":"owner/repo","enabled":true,"observedAt":"2026-10-17T00:00:00.000Z","registration":"registered","addresses":[{"key":"registered-owner-repo","source":"mcp","address":{"kind":"local","path":"/checkout/owner/repo"},"attribution":"mcp-key","matchesRepository":true,"resolution":"usable","reason":null}],"pickup":{"confirmed":false,"hostInstanceId":null,"source":"none"},"reasons":["Available evidence cannot establish the cause."],"recovery":[{"kind":"refresh","desktop":"Refresh after the normal roughly five-second reconciliation. If pickup remains unconfirmed, inspect daemon status and logs.","terminal":"Check `shipper status` after roughly five seconds. If pickup remains unconfirmed, inspect daemon status and logs.","mcp":"Check shipper_status after roughly five seconds. If pickup remains unconfirmed, inspect daemon status and logs."}]}, "automaticWork": { "status": "unavailable", "reason": "repository-not-reported", "message": "The running daemon did not report this repository." } }}
Compatibility refusal: { "status": "refused", "repository": "owner/repo", "conflict": { "kind": "repository-identity-mismatch", "recordPath": "<retained path>", "requestedRepository": { "kind": "named", "repo": "owner/repo", "storageKey": "owner-repo" }, "retainedRepository": { "kind": "named", "repo": "other/repo", "storageKey": "other-repo" } } }. It contains no previous, resulting, outcomes, migration, supervisorAvailability, or dispatchDeferral fields.Error modes
Section titled “Error modes”- No desired-state field supplied: At least one of enabled, worker_count, or halt_requested must be supplied.
- Invalid worker count: worker_count must be a whole number from 1 through 4.
- Canonical repository identity unavailable: Could not derive a canonical repository identity for
. - Desired-state persistence failure:
- Registration refusal before enable: Enablement did not complete. The entire requested patch was skipped; the previous enabled setting is unchanged. Unreadable registrations were preserved unchanged. Use a build able to read the registrations, restore a damaged file from a valid copy, or correct the reported access/lock problem. Switch to the repository checkout and explicitly enable Auto-ship.
- Supervisor could not be started after enable: The desired state remains recorded and the call succeeds with supervisorAvailability.status not-started.
- Supervisor compatibility mismatch after enable: The desired state remains recorded and the call succeeds with supervisorAvailability.status incompatible, version facts, and staleSide.