shipper_get_issue_runtime

shipper_get_issue_runtime

Poll one complete, local-only current runtime snapshot for a managed issue without consulting GitHub or changing ordinary issue detail. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.

When to use

Poll this focused local-only inspection when an operator needs one complete current snapshot of a managed issue worker, phase, waits, descendants, and active-agent transcript freshness. It supports open and closed records and never calls GitHub, mutates state, retains snapshot history, or changes shipper_get_issue. Assessment is exactly one of healthy_active, intentional_wait, stopped, suspected_hang, indeterminate, and not_applicable. Phase is exactly one of agent_turn, verification, verification_queue_wait, github_retry_wait, checks_wait, review_wait, awaiting_operator, finalizing, unknown, and none; specific current-run verification or wait evidence outranks generic activity, and conflicts remain unknown. suspected_hang is only a suspicion after the issue-lock holder is alive and not OS-stopped, verification/retry/check waits are inactive, no active descendant exists at any depth, and the active model transcript is unchanged for at least 600_000 ms; missing evidence is indeterminate. Worker identity is the issue-lock-holding ship/stage worker, including a daemon-dispatched forked worker—not the daemon, MCP server, supervisor, or model child. Spawn time, semantic version, build identity, liveness, OS state, descendant activity, and transcript evidence preserve field-level uncertainty independently. When ownership ends, use shipper_get_session_logs for post-mortem history.

Behavior hints

• readOnlyHint: true — The tool reads only local current-run authority and never mutates it.
• idempotentHint: true — Repeated polling has no side effects; naturally changing runtime evidence may change the snapshot.
• openWorldHint: false — The tool never consults GitHub or any other remote service.

Input schema

Name	Type	Required	Default	Description
issue	integer | string	yes	-	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.
repository_path	string	no	-	Optional repository path to an existing local git checkout to select for this read only. Omit it to read the active repository.

Output schema

object

Example call

{
  "issue": "S#42"
}

Example result

{
  "schema_version": 1,
  "captured_at": "2026-09-04T12:20:00.000Z",
  "issue": {
    "local_id": 42,
    "display_id": "S#42",
    "github_issue_number": 123,
    "title": "Generate MCP reference",
    "record_status": "open"
  },
  "assessment": {
    "value": "healthy_active",
    "reason": "Affirmative current workflow activity is recorded.",
    "observations": []
  },
  "phase": {
    "value": "verification",
    "detail": "type-check",
    "sources": [{ "kind": "verification_capacity", "status": "active", "detail": "type-check" }]
  },
  "worker": {
    "status": "present",
    "role": "issue_lock_holder",
    "pid": 4242,
    "lock_acquired_at": "2026-09-04T12:00:00.000Z",
    "spawn_time": { "status": "observed", "value": "2026-09-04T11:59:59.000Z" },
    "semantic_version": { "status": "observed", "value": "4.3.2" },
    "build_identity": {
      "status": "unknown",
      "reason": "Source-tree execution has no immutable installed generation."
    }
  },
  "worker_liveness": {
    "status": "observed",
    "value": "alive",
    "observed_at": "2026-09-04T12:20:00.000Z"
  },
  "os_process_state": {
    "status": "observed",
    "value": "sleeping",
    "observed_at": "2026-09-04T12:20:00.000Z",
    "raw_state": "S",
    "cpu_activity": false
  },
  "descendant_activity": {
    "value": "active",
    "reason": "A correlated verification runner is active.",
    "active_pids": [{ "pid": 4300, "kind": "verification" }]
  },
  "transcript": {
    "status": "observed",
    "agent": "codex",
    "source_kind": "codex_rollout",
    "last_write_at": "2026-09-04T12:19:58.000Z",
    "age_ms": 2000
  }
}

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.
• Issue cannot be resolved locally: Could not find the requested issue in the local issue-state replica.
• Safe snapshot cannot be formed: Current local identity is contradictory and no safe snapshot can be formed.

Related tools

• shipper_get_issue
• shipper_get_session_logs