#1264 Consolidate error-message extraction on toolbelt.errors' describeError

[williamthorsen]

What

Consolidates error-message extraction across the workspace on @williamthorsen/toolbelt.errors, replacing the local copies each package had defined under its own name. The repository's exact-version dependency rule now accepts shared pins (via catalog:) as an alternative and enforces sharing over duplication. The packages that stated no Node requirement now declare the workspace's Node 24 minimum.

Why

The expression error instanceof Error ? error.message : String(error) had been rewritten nine times across four packages, five of those as module-private helpers under three different names. A reader had to learn three names for one behavior, and each copy was free to drift from the others. The behavior also has edge cases worth getting right once — an Error carrying an empty message, and a value String() cannot render — which no local copy handled.

Details

🐛 Bug fixes

• mcp and run-core were the only packages in the workspace declaring no engines floor, while every sibling and the root manifest declare Node 24. Both now declare it. run-core is bound for publication and its dependencies require Node 24, so a consumer on an older runtime previously had nothing to warn them at install time.

♻️ Refactoring

• describeError replaces all nine occurrences of the ternary in factory, fleet, mcp, and run-core, called directly at each site with no local alias or wrapper. The five helper definitions it displaces are deleted: errorMessage (run-core, twice), getErrorMessage (factory), and readMessage (fleet, twice).
• Two sites are supersets of the pattern and keep their extra branches, delegating only their terminal fallback: fleet's readErrorText, which prefers accumulated stderr, and run-core's pick-demo-runs.ts, which prefers a parse error's category.
• Three factory sites that test instanceof Error but fall back to a domain string or to an Error object are a different construct and are unchanged. Routing them through describeError would degrade user-visible messages.
• The three bin launcher scripts keep their inline copy. A top-level import resolves before their build-first gate runs, so importing the helper would replace their diagnostic with ERR_MODULE_NOT_FOUND whenever the install is incomplete.

📦 Dependencies

• @williamthorsen/toolbelt.errors reaches six consumers — agents, factory, fleet, kb, mcp, and run-core — more than any other external dependency here, so it becomes the workspace's first catalog: entry. It is pinned once at 0.2.0 in pnpm-workspace.yaml and every consumer declares catalog:; agents and kb move off the literal pins they already carried. The other sixteen shared dependencies stay literal.

📚 Documentation

• AGENTS.md's exact-version rule now records the catalog as the sanctioned alternative to a literal pin, and instructs that a package taking on a cataloged dependency declares catalog: rather than re-pinning the literal.
• kb's bin launcher gains the comment its two siblings already carry, stating that the file's imports must stay builtins-only and what breaks otherwise.

Closes #1264

[github-actions]

Dependency audit

Production dependency audit passed.