Audit cleanup: dw.json atomicity, output discipline, timer leaks, ANSI palette

[clavery]

Summary

Outcomes from a multi-package code review across b2c-cli, b2c-tooling-sdk, b2c-dx-mcp, mrt-utilities, and b2c-vs-extension. Fixes correctness and consistency issues; no new features. Calibrated against source — items where the audit was overly cautious were intentionally left alone; the change set is the diff that's actually load-bearing.

Driven by a four-wave plan (HIGH risk first → focused refactors → MEDIUM cleanup → LOW polish).

What changed

Concurrency / data integrity (SDK)

• dw.json mutations (addInstance, removeInstance, setActiveInstance) now serialize through a per-path async lock. saveDwJson writes via tmp-file + atomic rename with orphan cleanup.
• stateful-store.setStoredSession removes an exists-then-mkdir TOCTOU; orphan tmp file is cleaned up if rename fails.

Resource cleanup (SDK)

• code deploy/download progress intervals run inside a withProgress helper that always tears down on exception.
• jobs/run.ts JobAlreadyRunning detection no longer silently swallows text() failure — falls through to normal error path with a debug log.
• code/download.ts replaces Map.get(name)! non-null assertions with explicit guards.

Output discipline (CLI)

• 9 sandbox commands now route output through this.log so --json mode and test stdout silencing work as documented.
• no-console ESLint rule scoped to src/commands/** to prevent regression. Prophet IDE template exempt (it serializes JS source for an external runtime).

Shared CLI palette (SDK + CLI)

• New @salesforce/b2c-tooling-sdk/cli ANSI palette (LEVEL_COLORS, colorLevel, colorDim, colorHighlight).
• utils/logs/format.ts and utils/mrt-logs/format.ts consume the shared palette instead of re-declaring it.

Public-API hygiene (CLI)

• Dropped formatApiError re-export aliases in utils/slas/client.ts and utils/scapi/schemas.ts; 7 call sites now import getApiErrorMessage from the SDK directly.
• Removed redundant alias-passthrough test.

Other

• mrt-utilities proxy onError guards res.headersSent before writeHead so it doesn't mask the original error when upstream begins streaming before erroring.
• vs-extension renderTemplate ordering bug: ${pageName}Data was being orphaned because the broader ${pageName} replacement ran first and stripped the placeholder boundary.
• Trimmed a duplicated docstring paragraph in mrt-utilities/ssr-proxying.ts and re-tagged the diff-with-instance comment in vs-extension as an intentional stub rather than a stale TODO.

What was deliberately not changed

The audit also flagged a number of issues that, on inspection of the source, were either false positives or contractually-correct behavior. Notable calibrations:

• OAuth token cache "race" — PENDING_TOKEN_REQUESTS singleflight is already in place; residual check-then-delete in getCachedOAuthToken is single-thread safe.
• MCP registry.ts duplicate-tool registration — registeredToolNames Set already dedupes both toolset and --tools paths.
• MCP waitForHalt "lost wakeup" — waiter is pushed synchronously inside the Promise executor; no interleaving possible.
• VS-extension realm polling "race" — same.
• mrt tail-logs heartbeat orphaning — open/error/close listeners are attached synchronously; close always clears the heartbeat.
• Several "brittle test" findings actually verify legitimate contracts (auth-token literal output, fixture-data assertions, ANSI code presence).
• pollUntil extraction — deferred. waitForJob and waitForSandbox have distinct error types and stage-specific logging; net DRY gain is small relative to regression risk on well-tested polling paths.
• Test infrastructure overhaul (over-mocked CLI command tests) — deferred to a focused effort.

Changeset

Included: .changeset/wave-review-cleanup.md — patch bumps for @salesforce/b2c-tooling-sdk, @salesforce/b2c-cli, @salesforce/mrt-utilities, and b2c-vs-extension.

Test plan

• pnpm run lint:agent — clean across all packages
• pnpm run typecheck:agent — clean
• pnpm run test:agent — SDK 1722 / CLI 1215 / MCP 720 / MRT 516 passing
• Manual: b2c sandbox ips, b2c sandbox usage <id>, b2c sandbox settings <id> — verify human output and --json modes both work
• Manual: b2c setup auth and a subsequent stateful-auth command — confirm session file round-trips
• Manual: parallel b2c setup auth invocations against the same dw.json — confirm no entries are lost (the dw.json serializer is in-process; multi-process remains best-effort but writes themselves are atomic via rename)
• Manual: b2c code deploy against a sandbox — confirm progress messages still appear at the expected cadence