feat(cli): structured error envelope (extra + next_steps on the wire)

[vvillait88]

Summary

CliError carries extra (structured recovery context) and nextSteps (action + suggestion) for deterministic agent recovery, but neither field reached the wire. The bridge to incur's IncurError accepts only {code, message, hint?, retryable?, exitCode?} and incur's renderer surfaces {code, message, retryable, fieldErrors?}. Agents reading --json got code and message but never the structured context they needed (e.g. extra.valid_keys, extra.chain, extra.held_chains, next_steps.action).

This PR wraps cli.serve() so the originating CliError is captured before the bridge erases it, then re-emits the wire envelope through incur's own Formatter.format(...) with extra and next_steps as proper fields. Format negotiation (toon/json/yaml/md/jsonl) and --full-output wrapping stay consistent with the success path.

Before:

{ "code": "no_wallet", "message": "No keystore for base (X).", "retryable": false }

After:

{
  "code": "no_wallet",
  "message": "No keystore for base (X).",
  "retryable": false,
  "extra": { "chain": "base", "name": "X" }
}

Full-output JSON parses incur's actual envelope and swaps just the error body, preserving the real meta.command (e.g. "wallet remove") and meta.duration.

Carve-outs (intentional passthrough — no enrichment)

Path	Reason
--mcp stdio mode	Loops forever; per-tool-call enrichment isn't reachable, post-serve enrichment would emit a stale envelope after session close
Human-TTY context (no explicit format/full-output)	Preserve incur's friendly Error (code): message one-liner; multi-line TOON dumps with extras are an agent need, not a human one
--token-count / --token-limit / --token-offset	Token / pagination flags ask incur for sized or sliced rendering; enrichment would defeat the purpose
Non-CliError errors (Parse, Validation, COMMAND_NOT_FOUND)	Flow through incur unchanged

Sync-throw bypass (also fixed)

withCliErrors(() => fundEstimate({headers: parseHeaders(...)})) was a non-async arrow. A sync parseHeaders throw bypassed .catch() (the throw happened before the inner promise was returned), reaching incur as a raw Error → code: UNKNOWN. Switched to Promise.resolve().then(fn).catch(...) so both sync and async throws route through the same handler. All 21 non-async call sites are uniformly protected. Verified live: fund-estimate with malformed -H now correctly returns code: invalid_input instead of UNKNOWN.

Doc cleanup

Three pre-existing inaccuracies became false-claims-into-true-claims with this wrap:

• README.md:73 — Errors emit { code, message, retryable, hint? } on stderr was wrong on both counts. Now states the real shape on stdout with extra? / next_steps?. The hint? field was never reachable by the renderer.
• README.md:184/210 — Python and TypeScript code examples read the error envelope from stderr; switched to stdout and corrected the compact-mode shape (err['code'], not err['error']['code']).
• agent-guide.ts:json_mode — same stderr / hint? mistake; corrected.

Plus a new contract entry: agent-guide now has a top-level error_envelope field with channel / shape / full_output_shape / human_tty_shape. Agents reading agent-guide --json get an explicit wire-shape contract alongside the existing identity_error_recovery and exit_codes blocks.

Pin

incur ^0.4.5 → 0.4.5. The wrap depends on incur internals (wire envelope shape, Formatter.format API, IncurError.Options, cli.serve overrides, Mcp.serve, formatHumanError, format flag precedence). Any minor / patch bump could silently shift any of these. Mirrors the viem 2.48.7 exact-pin pattern for load-bearing deps. Upgrade verification protocol captured in the team's incur-upgrade-checklist memory.

Tests

tests/error-envelope.test.ts — 67 tests across 9 describe blocks:

• Compact JSON error envelope (10) — code+message+retryable, every extras source, next_steps, both-fields-present, omission when absent
• Compact non-JSON formats (5) — TOON / YAML / MD / JSONL render extras and next_steps via Formatter.format
• Full-output (3) — JSON parse-and-swap preserves meta.command + meta.duration; YAML synthesizes
• Format precedence (3) — last-wins both directions, default TOON
• Non-CliError passthrough (4) — COMMAND_NOT_FOUND, --version, --help, --llms
• exitCodeForError mapping (27) — every ErrorCode → expected exit code
• isRetryable (3) — retryable / non-retryable codes, RETRYABLE_CODES set consistency
• Sync-throw protection (2) — fund-estimate + check with malformed -H
• Token-flag passthrough (3) — --token-count, --token-limit, --token-offset on errors
• Human-TTY passthrough (3) — TTY + no flag preserves formatHumanError; TTY + --json enriches; pipe + no flag enriches
• Wrap-internal correctness (4) — success passthrough, full-output success, pendingError leak prevention, exit-code-1 across multiple error paths

Plus 2 new tests in tests/agent-guide.test.ts locking in the doc fixes.

Sabotage-verified non-spurious: temporarily clearing the pendingError stash makes 15 wrap-dependent tests fail; restoring makes all 67 pass.

Test plan

• bun run typecheck clean
• bun run lint clean
• bunx vitest run — 434 pass / 2 skipped / 0 fail across 42 test files
• Live binary smoke across 31+ scenarios — every output format, full-output mode, MCP short-circuit, human-TTY (via script), --version, --help, --llms, COMMAND_NOT_FOUND, and the sync-throw fix
• Lefthook pre-commit (eslint) + pre-push (typecheck) both pass
• CI green
• Tag v0.1.0-rc.19 after merge to trigger npm publish

🤖 Generated with Claude Code