feat(bidding): add update_ad_group_cpc_bid with a bid precondition guard

[mharnett]

The server had no bid write at any level, so max CPC changes were UI-only. This adds one, with the guard update_campaign_budget lacks.

Max CPC lives at ad group level in Bing (CpcBid.Amount) — there is no campaign-level max CPC — so changing "a campaign's max CPC" means one call per ad group.

Why two guards

A bid is the highest-blast-radius write this server exposes. A budget error is self-limiting (the daily cap bounds the loss); a bid error applies to every click in every auction with no ceiling.

Before — expected_current_bid is required, not defaulted. The live bid must match or the write is refused. A new bid is nearly always computed relative to the current one ("halve it", "back to $12") — exactly the reasoning that breaks silently when the current one has moved. update_campaign_budget will happily write from a stale read.

After — the value is read back and asserted. PartialErrors: [] does not mean a write landed on this API: a $400 budget write returned exactly that on 2026-08-24 and left the value at $100 for two days. Nothing reports success here without a re-read.

assertAdGroupBidPrecondition fails closed on a missing or unparseable live bid — treating "unknown" as "matches" would make the guard decoration.

Also rejects non-finite, non-positive, and >$500 bids. The ceiling is a misplaced-decimal catch, not a policy — the highest bid this account has ever carried is $24.

Enhanced CPC caveat, in the tool description

Under EnhancedCpc (or any auto strategy) CpcBid is a base bid Bing adjusts up and down, not a hard ceiling — and lowering it reduces ad rank, so it cuts volume as well as cost. The description says so, because "set max CPC to $10" reads like a cap and isn't one.

Tests

File	Covers
src/mutationRequests.test.ts	builder shape, fractional bids, non-positive / non-finite / over-ceiling rejection; guard match, drift, not-found, null-bid fail-closed, float tolerance
src/writeGate.test.ts	classified as a write tool, hidden without BING_ADS_MCP_WRITE, exposed with it, expected_current_bid in required
src/tools.contract.test.ts	tool name roster

RED:   9 failed | 7 passed    (both functions undefined)
GREEN: 16 passed
RED:   4 failed | 23 passed   (tool unregistered, not in WRITE_TOOLS)
GREEN: 156 passed

One unrelated pre-existing failure: the shared harness's npm audit check times out at 5s (network-dependent).

Verified live, not just green

Account 141522471, campaign bing_bofu_nonprofit_core. All three ad groups — Donation Software, Nonprofit Software, Nonprofit CRM — moved 24 → 10 with read-back confirmation. Then a deliberate replay carrying the now-stale expected_current_bid: 24 was refused:

Bid precondition failed for ad group "Donation Software" (1332610684483682):
expected 24, found 10. The ad group is not in the state this change was
computed against — re-read and retry.

So the guard is confirmed wired to the real call path with real arguments — not merely passing in isolation.

🤖 Generated with Claude Code