shipper_get_session_logs

shipper_get_session_logs

List every recorded agent session transcript for a Shipper issue, newest first, with its workflow stage, optional final-preparation sub-step, start time, and outcome. Supports active, completed, and not-planned issues and optional exact stage filtering. 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

Omit repository_path to use the active repository, or supply a local checkout path in repository_path to select that repository for this call only. Explicit targets remain usable when active startup is degraded, do not count as active-repository work, and never change ambient server state. The successful response shape is identical for active and targeted calls. Use this local-only tool to find agent session transcripts when debugging or performing a post-mortem. It returns transcript locations and identifying context, not transcript contents or the consolidated workflow event log. Results include every recorded rerun across all stages without a default cap, newest first, and work for active, completed, and not-planned issue records. Only runs with a regular transcript file are returned; metadata/result-only runs are omitted, so an absent stage does not prove that stage never ran. Persisted reject and fail verdicts are reported exactly, and accept is reported only when process metadata does not record a nonzero exit. A nonzero process exit is error, while a zero-exit or transcript-only run without a valid verdict is incomplete. Historical timeouts are not separately recoverable and appear as error when nonzero exit metadata exists. A resolved issue with no matching transcripts is a successful logs: [] response.

Behavior hints

• readOnlyHint: true — The tool reads local issue identity and session files without changing workflow, issue, or GitHub state.
• idempotentHint: true — Repeated calls return the same recorded session history until another run occurs.
• openWorldHint: false — The tool reads only local Shipper state and session files.

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.
stage	string	no	-	Optional trimmed, non-blank recorded session stage token. Exact matches only; active values include new, groom, design, plan, implement, and pr_review; historical records may contain pr_open or pr_remediate. Omit stage first to discover the tokens recorded for an issue.
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

Name	Type	Required	Default	Description
logs	array	yes	-	-

Example call

{
  "issue": "S#42",
  "stage": "implement",
  "repository_path": "/absolute/path/to/selected/checkout"
}

Example result

{
  "content": [
    {
      "type": "text",
      "text": "Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages\nSession logs (2, newest first):\n\nLog 1\nstarted_at: 2026-07-23T20:03:00.000Z\nstage: implement\noutcome: error\npath: /home/user/.shipper/sessions/owner-repo/s42-implement-2026-07-23T20-03-00-000Z.jsonl\n\nLog 2\nstarted_at: 2026-07-23T19:42:00.000Z\nstage: implement\noutcome: accept\npath: /home/user/.shipper/sessions/owner-repo/123-implement-2026-07-23T19-42-00-000Z.jsonl"
    }
  ],
  "structuredContent": {
    "logs": [
      {
        "path": "/home/user/.shipper/sessions/owner-repo/s42-implement-2026-07-23T20-03-00-000Z.jsonl",
        "stage": "implement",
        "started_at": "2026-07-23T20:03:00.000Z",
        "outcome": "error"
      },
      {
        "path": "/home/user/.shipper/sessions/owner-repo/123-implement-2026-07-23T19-42-00-000Z.jsonl",
        "stage": "implement",
        "started_at": "2026-07-23T19:42:00.000Z",
        "outcome": "accept"
      }
    ]
  }
}

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 reference not found: Could not find Shipper issue S# in the local issue-state replica for owner/repo.
• Session store unreadable:
• Invalid or unready repository target: Repository identity could not be established for . The repository has no commits. Create an initial commit. Correct this condition and retry the repository read with repository_path.

Related tools

• shipper_get_issue
• shipper_get_issue_runtime