Enriched list --json and batch-show for warm-graph integrations (depends on #18)

[dan-huminology]

Summary

This PR adds opt-in read projections so integrations can hydrate task metadata and bodies without N× show / show --body round trips through ergo serve.

It builds on the warm in-memory Graph from #18. Default behavior is unchanged: list --json without new flags still emits version 1 JSON identical to today.

Both features ship in this PR:

• Feature 1 — list --json --with-meta [--with-body] — version 2 items with timestamps, claim fields, depends_on, and optional lossless body
• Feature 2 — batch-show --json <id>… — one JSON document keyed by task id (max 256 ids); missing ids omitted with stderr warnings
• Serve wire — existing list payload carries new flags; new batch_show method; warnings travel on wire stderr and print to the client
• No JSONL schema changes — read-only projections from the derived graph

Depends on #18 (resident serve).

Problem

Even with ergo serve, watch and console integrations still need fields that list --json omits (created_at, depends_on, stored body, …). Workarounds replay backlog.jsonl in TypeScript or fall back to paired show + show --body calls — duplicating ergo’s reducer and multiplying socket traffic on hot paths.

The missing piece is not a new store; it is supported CLI projections that reuse the warm graph #18 already holds.

Approach

Feature 1 — enriched list JSON

New flags on list (both require --json):

Flag	Adds to each items[] row
--with-meta	created_at, updated_at, claimed_at (null when unset), claimed_by (null when unset), depends_on (string[], may be empty)
--with-body	body (lossless stored bytes, same as show --body)

When either flag is set, document version is 2. When neither is set, output remains version 1.

depends_on lists prerequisites (this task depends on these ids), from Graph.Dependencies(id) — same edges as show’s “depends on” section.

Example row (all flags on):

{
  "id": "W2KEE7",
  "title": "agent:write-test-plan",
  "kind": "task",
  "state": "todo",
  "ready": true,
  "epic_id": "MDINNW",
  "created_at": "2026-08-22T21:58:01.276626138Z",
  "updated_at": "2026-08-22T21:58:01.276626138Z",
  "claimed_at": null,
  "claimed_by": null,
  "depends_on": ["YDX3YB"],
  "body": "…"
}

Keys for flags that are off are omitted (not "body": null unless --with-body is on and the stored body is empty).

Feature 2 — batch-show

ergo batch-show [--json] <id> [<id>…]

Always JSON. Returns:

{
  "version": 1,
  "tasks": {
    "ABC12": {
      "id": "ABC12",
      "title": "run:ci",
      "kind": "task",
      "state": "todo",
      "epic_id": "LAND1",
      "created_at": "2026-08-30T00:00:54.717284613Z",
      "updated_at": "2026-08-30T01:05:36.336Z",
      "claimed_at": null,
      "claimed_by": null,
      "depends_on": ["PREV1"],
      "body": "…"
    }
  }
}

• Max 256 ids per invocation (usage error above that)
• Missing or pruned ids omitted from the map; stderr warns once per missing id; exit code 0 unless usage error
• Proxies as wire method batch_show with payload {"ids":[…],"with_body":true}

Serve / proxy

• Existing list wire method carries extended ListRequest (JSONWithMeta, JSONWithBody)
• writeWireOK now includes optional stderr; proxied clients echo server stderr before stdout (batch-show missing-id warnings)
• Upgrade note: restart ergo serve after installing this binary so it understands batch_show. Old serve continues to handle list / show; unknown methods return a structured wire error.

Operator UX

# After #18 is merged and serve is running — restart serve when upgrading to this build
ergo --dir /path/to/repo list --ready --json --with-meta --with-body
ergo --dir /path/to/repo batch-show --json GATE1 GATE2 GATE3

# One-shot path still works (--no-server or no socket); pays full inspectEventLog cost
ergo --dir /path/to/repo --no-server list --json --with-meta --with-body

Tests

go test ./...

Area	File
List v1 unchanged; v2 meta (depends_on, timestamps, null claim); v2 body matches ShowBody	internal/ergo/list_json_test.go
Batch-show missing id, epic row, body parity	internal/ergo/batch_show_test.go
Proxied enriched list + batch-show match --no-server stdout	cmd/ergo/serve_roundtrip_test.go
Help / quickstart / command inventory	internal/ergo/help.txt, quickstart.txt, cmd/ergo/manual_test.go

Reviewer notes

• Shared projection helpers live in internal/ergo/list_projection.go (projectTaskJSON, taskDependsOnJSON, …)
• batch_show_json.go owns BatchShowRequest, Application.BatchShow, and JSON render
• List v2 uses []map[string]any items so unset claim fields serialize as JSON null
• Wire protocol version unchanged (protocolVersion = 1); only new method + extended list payload
• Intended merge order: Optional resident serve mode for warm backlog reads (addresses #13) #18 first, then this PR

— Dan's AI Helper