Map burn's tool-call-pattern findings to relaywash__* recommendations

[willwashburn]

Context

AgentWorkforce/burn#224 (merged) lands a vendor-neutral tool-call-pattern detector in burn hotspots. Burn surfaces five categories of vanilla call patterns with consolidatable overhead, but it deliberately does not name a specific replacement tool — that mapping belongs here.

This issue covers building the wash-side consumer that closes the loop: take burn's findings, map each category to the matching relaywash__* tool, and produce an "install relaywash to save N tokens" advisory the way the original burn PR did before we split it.

Status of upstream prerequisites (all landed)

• ✅ burn#218 — @relayburn/sdk programmatic surface published
• ✅ burn#219 — _meta.replaces / _meta.collapsedCalls annotations recognized on ingest
• ✅ burn#224 — tool-call-pattern detector merged, exposed via hotspots() in the SDK

So this issue is now fully unblocked — no more --json shelling required.

Status on the wash side

• src/burn/sdk.js is still a local stub of relayburn/sdk with a header comment claiming it is "blocked on burn#218." That blocker is gone — we should swap the stub for the real @relayburn/sdk npm dep as part of this work (or in a small precursor PR).
• scripts/relaywash-savings/run.js (the /relaywash-savings slash command) already calls summary({ session }) from the SDK. That is the post-install ledger report (how much you saved with relaywash already running). This issue is the complementary pre-install advisory (how much you would save if you installed relaywash) — different command, same SDK.
• The relaywash tools (src/tools/{search,edit,git-state,test-run,gh-pr}.js) already emit _meta.replaces / _meta.collapsedCalls via src/burn/meta.js, so once the advise command re-prices, it can pull tool-specific footprints from those annotations directly.

Burn's output (what we consume)

hotspots({ patterns: ['tool-call-pattern'] }) returns an array of findings, each shaped roughly like:

{
  source: 'claude-code' | 'opencode' | 'codex',
  sessionId: string,
  category:
    | 'search-sequence'      // Glob → Grep → Read in one turn (≥3 per session)
    | 'edit-cluster'          // ≥3 edits to same file in 5-turn window
    | 'bash-git-state'        // git status/diff/log
    | 'bash-test-run'         // pnpm test, pytest, jest, etc.
    | 'bash-gh-pr',           // gh pr <verb>, gh api
  occurrenceCount: number,
  estimatedTokensSaved: number,   // burn's conservative per-occurrence estimate
  estimatedUsdSaved: number,      // priced at session's dominant model rate
  sampleTurnIndexes: number[],
  evidence: string[],
}

patterns also accepts tool-output-bloat and ghost-surface if we later want to layer recommendations on those.

Mapping table

Burn category	relaywash tool
search-sequence	relaywash__Search
edit-cluster	relaywash__Edit (batched)
bash-git-state	relaywash__GitState
bash-test-run	relaywash__TestRun
bash-gh-pr	relaywash__GhPR

All five replacement tools exist today under src/tools/.

Proposed shape

A relaywash advise command (likely a new slash command alongside /relaywash-savings) that:

1. Imports hotspots from @relayburn/sdk (replacing the local stub) and calls it with { patterns: ['tool-call-pattern'] }. No more burn hotspots --json shell-out.
2. Joins each finding to its relaywash__* mapping.
3. Re-prices the savings using the relaywash tool's actual per-call token footprint instead of burn's conservative flat rates. The _meta.replaces / _meta.collapsedCalls annotations the tools already emit are the source of truth here (now that burn#219 is in).
4. Emits a per-session "you'd save $N by installing/enabling these tools" report. Markdown PR-comment / CLAUDE.md snippet output mode would let CI surface it on PRs the way burn-compare already does.

Why split it this way

Burn's value prop is observability — it should report the pattern and the overhead estimate without picking a vendor. wash's value prop is the consolidated tools — it owns the recommendation layer and the marketing copy ("install relaywash to save $X"). This keeps burn vendor-neutral and lets multiple consolidation libraries layer on top of the same burn signal.

Acceptance

• src/burn/sdk.js stub replaced with a real @relayburn/sdk dependency (or the stub explicitly kept as a tested-fallback with a clear reason).
• Advise command runs against live hotspots({ patterns: ['tool-call-pattern'] }) output and emits per-session recommendations.
• Mapping table covers all five categories.
• Re-pricing uses tool-specific numbers from _meta.replaces / _meta.collapsedCalls, not burn's flat estimates.
• Tested against fixture sessions for each of the five categories (the fixtures/corpus/ setup used by burn-compare is a good starting point).

[willwashburn]

Update: burn#224 now also exposes the three side-channel detectors via @relayburn/sdk, so the wash consumer can run in-process via:

import { hotspots } from '@relayburn/sdk';
const findings = await hotspots({ patterns: ['tool-call-pattern'] });

Findings come back already adapted to the WasteFinding shape — no need to shell out to burn hotspots --json. The patterns array also accepts tool-output-bloat and ghost-surface if you want to layer recommendations on top of those too.