Lift runOverhead into @relayburn/sdk (closes #235)

[willwashburn]

Closes #235. Follow-up to #232 (which made @relayburn/sdk the canonical in-process query surface). Applies the same pattern — CLI verb → pure SDK function + thin presenter — to burn overhead and burn overhead trim.

What changed

@relayburn/sdk — two new functions, both in-process pure data:

const result = await overhead({ project, since?, kind?, ledgerHome?, onLog? });
// → { project, files, perFile, grandTotal }

const trim = await overheadTrim({ project, since?, kind?, top?, includeDiff?, sinceLabel?, ... });
// → { project, since, recommendations, summary }

Both reuse the loadTurnsViaArchive helper from #232 so they get the same archive-with-fallback strategy summary / sessionCost already have. overheadTrim includes a unified-diff string per recommendation by default (matches burn overhead trim --json); pass includeDiff: false to skip the per-file disk reads when only recommendation rows are needed.

New types declared in index.d.ts so consumers don't have to reach into @relayburn/analyze for the attribution shape: OverheadFileSummary, OverheadPerFileEntry, OverheadSectionCost, OverheadAttributionDetail, plus the OverheadResult / OverheadTrimResult / option types.

@relayburn/cli — adds @relayburn/sdk as a workspace dep. runOverhead / runTrim drop ~280 lines of inline gather + attribution + JSON shaping; both now call the SDK and only own flag parsing, --since string→ISO conversion, and TTY/diff rendering. CLI keeps a narrow OverheadDeps { ingestAll? } injection seam (only ingest, not the whole pipeline) so tests can stub out the real ingest pass — without it, an isolated RELAYBURN_HOME test still triggers a real read of the user's ~/.claude / ~/.codex / ~/.opencode stores.

Wire shape unchanged. Both burn overhead --json and burn overhead trim --json emit the same payload they did before; the existing JSON-mode test was rewritten to use a real ledger (appendTurns into a tmp RELAYBURN_HOME) instead of dep-injection of queryAll/loadPricing, and asserts the same exact shape.

Test plan

• pnpm run build clean
• pnpm run test — 889/889 pass
• Overhead JSON-mode test (the only structured assertion this verb has) passes against the SDK-backed implementation
• Manual: burn overhead and burn overhead trim --top 3 against a real project produce the same TTY output as before

Out of scope

• Adding a burn__overhead MCP tool. That's a separate PR — should be ~30 lines once this lands (zod schema → await sdk.overhead(input) → return).
• The CLI commands listed in Lift runCompare into @relayburn/sdk as compare() #233 (compare) and Lift runHotspots into @relayburn/sdk as hotspots() (proper) #234 (hotspots) — same refactor pattern, separate PRs.

🤖 Generated with Claude Code

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f7ea96ef7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Parse relative --since values before ledger query

overhead()/overheadTrim() document since as accepting relative windows like 30d, but this code forwards opts.since directly into the ledger query. The ledger filter compares timestamps lexicographically (e.g. turn.ts < q.since in packages/ledger/src/adapters/file-adapter.ts), so passing 30d/7d silently filters out essentially all turns and returns near-zero attribution. This makes the new SDK API produce incorrect results for documented inputs unless callers pre-convert to ISO themselves.

Useful? React with 👍 / 👎.

[willwashburn]

Fixed in 9fa7e45 — the SDK now normalizes since (accepts both ISO timestamps and relative ranges like 7d/4w/2m) before passing to the ledger query. Direct SDK callers get the same forgiving shape CLI users have. Also tightened the .d.ts doc to describe the accepted forms.