feat(sdk): add discriminated errors, type guards, toJSON, withRetry

[MajorTal]

Summary

The April 2026 SDK DX consultation called out instanceof Run402Error as fragile across SDK copies and realms. Identity-based checks fail silently when the consumer's runtime holds a different copy of the SDK — duplicate npm installs, bundler chunk splits, ESM/CJS interop, and V8-isolate boundaries are all common in agent-controlled environments.

This change adds value-based discriminators alongside the existing class hierarchy. All additions are non-breaking — instanceof continues to work in the simple single-copy case.

What's added

	New
Run402ErrorKind	Discriminated union of seven literal strings (one per subclass)
Run402Error.kind	Abstract field; concrete subclasses provide a literal
Run402Error.isRun402Error	Structural brand (true as const); survives realm/copy boundaries
Run402Error.toJSON()	Canonical envelope; JSON.stringify(error) returns populated object instead of "{}"
Type guards	isRun402Error, isPaymentRequired, isProjectNotFound, isUnauthorized, isApiError, isNetworkError, isLocalError, isDeployError, isRetryableRun402Error
withRetry(fn, opts?)	Exponential-backoff helper using isRetryableRun402Error as the default policy. Defaults: 3 attempts, 250ms base, 5s cap. Throws LAST error after exhausting attempts.

Recommended pattern

import {
  run402,
  withRetry,
  isPaymentRequired,
  isDeployError,
} from "@run402/sdk/node";

const r = run402();

try {
  const release = await withRetry(
    () => r.deploy.apply(spec, { idempotencyKey: "deploy-2026-05-01" }),
    { attempts: 3, onRetry: (_e, n, ms) => console.warn(`retry ${n} in ${ms}ms`) },
  );
} catch (e) {
  if (isPaymentRequired(e)) { /* ... */ }
  else if (isDeployError(e)) console.error(JSON.stringify(e));
  else throw e;
}

Side fix: npm test glob quoting

Found while wiring the new tests: package.json's test script had unquoted globs (sdk/src/**/*.test.ts). The shell expanded these without globstar, silently dropping every depth-1 test in core/src, sdk/src, and src. Local npm test reported 266; CI's inline quoted-glob command saw 566. Quoted the globs so local matches CI — 300 previously-hidden tests now run.

CI is unaffected (the workflow uses its own inline quoted command); this just makes local match.

Test plan

• 217 SDK unit tests pass (node --test --import tsx 'sdk/src/**/*.test.ts').
• 45 new tests cover kind literals, brand, every guard's narrowing, isRetryableRun402Error policy across status codes / flags / kinds, toJSON envelope including subclass fields, instanceof back-compat, withRetry happy-path / retryable / non-retryable / last-error / custom retryIf / onRetry ordering and buggy-logger isolation / exponential-backoff timing / closure idempotency-key passthrough.
• npm test (root) — 566 tests pass, plus test:docs green (21 TS snippets across 3 docs compile).
• npm run check:docs --workspace=@run402/sdk — green (rewritten error/retry examples in sdk/README.md and sdk/llms-sdk.txt compile).

Reviewer focus

1. instanceof continues to work. No prototype-chain changes. Existing if (e instanceof PaymentRequired) { ... } call sites in MCP / CLI / OpenClaw are not touched.
2. Anonymous Run402Error subclasses fixed. Two class extends Run402Error {} instances in sdk/src/namespaces/projects.ts were rejected by TypeScript once kind became abstract — replaced with LocalError (the correct class for local-config-missing).
3. withRetry defaults are sane (3 attempts × 250ms base × 5s cap matches p-retry/axios-retry).
4. Docs lead with the new pattern but don't deprecate instanceof.

Spec lives at run402-private/openspec/changes/sdk-error-discrimination/.

🤖 Generated with Claude Code