shipper_unlock

shipper_unlock

Release an issue lock. With issue: release that issue’s lock. With stale=true: sweep all stale locks across the repo. Exactly one of issue or stale must be provided.

When to use

Use this when a machine-local Shipper issue owner is preventing workflow progress. Choose either one issue or a stale-lock sweep. A targeted run owner returns PID and acquisition time; an operator pause returns owner kind and pause time with no PID. Both require the returned confirmation token before force unlock. Stale sweeps exclude valid operator pauses; Resume is the normal way to release one.

Behavior hints

• idempotentHint: true — Retrying the same call is expected to be safe once the target state is reached.
• openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	integer | string	no	-	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.
stale	boolean	no	-	When true, release every stale shipper lock in the repository.
force	boolean	no	-	Retry a targeted live-lock release after inspecting its holder.
confirmation_token	string	no	-	Opaque token returned by the immediately preceding force_required result.

Output schema

Name	Type	Required	Default	Description
status	enum: missing, released, force_required	yes	-	-
local_id	integer	no	-	-
issue_display_ref	string	no	-	-
owner_kind	enum: run, operator-pause	no	-	-
holder_pid	integer	no	-	-
acquired_at	string	no	-	-
paused_at	string	no	-	-
confirmation_token	string	no	-	-
remedy	string	no	-	-
released_count	integer	no	-	-

Example call

{
  "issue": 42
}

Example result

Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages
Released lock on S#42 (GitHub #123).

Error modes

• Invalid target/force combination: Valid combinations: supply stale: true alone, or supply canonical input issue with optional force; confirmation_token requires force: true, and stale mode forbids issue, force, and confirmation_token.
• Lock release or list failure: Lock release/list failure:
• Active owner requires confirmation: S# (GitHub #) is locked by PID , acquired at . Retry shipper_unlock with force: true and confirmation_token: .
• Operator pause requires confirmation: S# (GitHub #) is deliberately paused by an operator since . Retry shipper_unlock with force: true and confirmation_token: only to deliberately override it.

Related tools

• shipper_reset
• shipper_unblock