shipper_clear_dispatch_ownership

shipper_clear_dispatch_ownership

Inspect and deliberately clear the active repository’s dispatch ownership. A tokenless call never mutates state: when ownership is held it returns the full holder facts, a concurrent-schedulers warning, and an opaque confirmation token. Echo that exact token in a second call to clear only the ownership that was shown. This does not change desired state, contact GitHub, or start or attach to a daemon.

When to use

Use this local recovery operation only when shipper_status reports held dispatch ownership whose holder can no longer be trusted to release it. The active repository identity is the entire scope. First call with no input to inspect all five public holder facts and receive an opaque token. Then, only after reviewing the concurrent-schedulers warning, echo that exact token as confirmation_token. The confirmed call deletes only the stable owner identity that was shown. A holder refresh or liveness-probe change does not invalidate the token, but replacement, removal, or death returns changed and deletes nothing. Make a new tokenless call after changed; never reuse or invent a token. The tool calls local core storage directly and does not start, attach to, or command a daemon, call GitHub, register a checkout, change desired state, or apply any time-based expiry.

Behavior hints

• readOnlyHint: false — The tokenless preview is read-only, but the confirmed second call can delete the exact local ownership record shown.
• destructiveHint: true — Discarding dispatch ownership held by a genuinely running holder means two schedulers will dispatch for this repository concurrently.
• idempotentHint: true — Repeated previews are safe; a confirmed target can be cleared once and later calls return a no-op or changed result without deleting a successor.
• openWorldHint: false — The tool uses only local repository state and does not contact GitHub or a daemon.

Input schema

Name	Type	Required	Default	Description
confirmation_token	string	no	-	Opaque token returned by the immediately preceding tokenless preview.

Output schema

Name	Type	Required	Default	Description
repository	string	yes	-	-
status	enum: nothing_to_clear, confirmation_required, cleared, changed, unavailable	yes	-	-
observed_dispatch_ownership	-	yes	-	-
confirmation_token	string	no	-	-
warning	string	no	-	-
message	string	yes	-	-

Example call

{}

Example result

{
  "content": [{ "type": "text", "text": "Dispatch ownership is held for owner/repo. Review the holder facts and warning before confirming." }],
  "structuredContent": {
    "repository": "owner/repo",
    "status": "confirmation_required",
    "observed_dispatch_ownership": {
      "status": "held",
      "holder": {
        "surface": "terminal",
        "pid": 4242,
        "acquiredAt": "2026-08-07T11:59:00.000Z",
        "liveness": "running",
        "lastRefreshAt": "2026-08-07T12:00:00.000Z"
      }
    },
    "confirmation_token": "<opaque>",
    "warning": "Discarding dispatch ownership held by a genuinely running holder means two schedulers will dispatch for this repository concurrently.",
    "message": "Dispatch ownership is held for owner/repo. Review the holder facts and warning before confirming."
  }
}

Confirmed call: { "confirmation_token": "<opaque>" } returns status "cleared" with the removed held projection.

No-owner result: { "repository": "owner/repo", "status": "nothing_to_clear", "observed_dispatch_ownership": { "status": "not-held" }, "message": "No dispatch ownership was present for owner/repo. Nothing was cleared." }

Changed-owner result: { "repository": "owner/repo", "status": "changed", "observed_dispatch_ownership": { "status": "held", "holder": { "surface": "unrecognized", "pid": 5252, "acquiredAt": "2026-08-07T12:01:00.000Z", "liveness": "could-not-determine", "lastRefreshAt": "2026-08-07T12:01:00.000Z" } }, "message": "Dispatch ownership changed for owner/repo. Nothing was cleared. Inspect the current owner and retry." }

Unavailable result: { "repository": "owner/repo", "status": "unavailable", "observed_dispatch_ownership": { "status": "unavailable", "message": "<underlying ownership read error>" }, "message": "Dispatch ownership could not be inspected for owner/repo. Nothing was cleared." }

Error modes

• Canonical repository identity unavailable: Could not derive a canonical repository identity for .
• Ownership changed: The current observed ownership is returned with status changed. Nothing was cleared; make a fresh tokenless preview.
• Inspection unavailable: The unavailable projection and underlying read message are returned. Nothing was cleared; resolve the local read failure rather than guessing a holder.

Related tools

• shipper_status
• shipper_switch_repo