chore: bump @socketsecurity/lib to 5.24.0 and adopt error helpers

- package.json: 5.21.0 → 5.24.0.
- scripts/utils/error-message.mts: drop the local
  `instanceof Error ? .message : String` shim and re-export
  errorMessage from @socketsecurity/lib/errors. The library version
  walks the `cause` chain and supplies the UNKNOWN_ERROR sentinel —
  strictly better than the local one.
- CLAUDE.md: add the caught-value helpers list (isError /
  isErrnoException / errorMessage / errorStack) — scoped to
  **scripts** only; `src/` stays on its primordial-guarded
  `src/error.ts` helpers for DoS-hardening.
- docs/references/error-messages.md: pick up the new "Working with
  caught values" section.

Out of scope:
- src/error.ts and src/result.ts continue to use primordials
  (`StringPrototypeCharCodeAt`, etc.) and local `instanceof Error`
  narrowing. Adding external imports there contradicts the
  prototype-pollution hardening model for the published library.
- scripts/publish.mts and scripts/utils/run-command.mts `'code' in e`
  checks read numeric spawn exit codes, not errno strings.

Author: jdalton

CLAUDE.md

@@ -114,6 +114,13 @@ Rules for every message:
 - Bloat check: if removing a word keeps the information, drop it.
 - For allowed-set / conflict lists, use `joinAnd` / `joinOr` from `@socketsecurity/lib/arrays` — `must be one of: ${joinOr(allowed)}` reads better than a hand-formatted list.
 
+Caught-value helpers from `@socketsecurity/lib/errors` (prefer these in **scripts** over hand-rolled checks; `src/` uses primordial-guarded helpers from `src/error.ts` instead):
+
+- `isError(e)` — replaces `e instanceof Error`. Cross-realm-safe.
+- `isErrnoException(e)` — replaces `'code' in err` guards. Narrows to `NodeJS.ErrnoException`.
+- `errorMessage(e)` — replaces `e instanceof Error ? e.message : String(e)` and any `'Unknown error'` fallback. Walks the `cause` chain.
+- `errorStack(e)` — cause-aware stack or `undefined`.
+
 Examples:
 
 - ✗ `Error: invalid config` → ✓ `config.json: part 3 is missing "filename". Add a lowercase filename (e.g. "parsing").`

docs/references/error-messages.md

@@ -98,6 +98,62 @@ Both wrap `Intl.ListFormat`, so the Oxford comma and one-/two-item cases come ou
 
 Use `joinOr` whenever the error is "must be one of X", `joinAnd` whenever it's "all of X are required / missing / in conflict".
 
+## Working with caught values
+
+`catch (e)` binds `unknown`. The helpers in `@socketsecurity/lib/errors` cover the four patterns that recur everywhere:
+
+```ts
+import {
+  errorMessage,
+  errorStack,
+  isError,
+  isErrnoException,
+} from '@socketsecurity/lib/errors'
+```
+
+### `isError(value)` — replaces `value instanceof Error`
+
+Cross-realm-safe. Uses the native ES2025 `Error.isError` when the engine ships it, falls back to a spec-compliant shim otherwise. Catches Errors from worker threads, `vm` contexts, and iframes that same-realm `instanceof Error` silently misses.
+
+- ✗ `if (e instanceof Error) { … }`
+- ✓ `if (isError(e)) { … }`
+
+### `isErrnoException(value)` — replaces `'code' in err` guards
+
+Narrows to `NodeJS.ErrnoException` (an Error with a string `code` set by libuv/syscalls like `ENOENT`, `EACCES`, `EBUSY`, `EPERM`). Builds on `isError`, so it's also cross-realm-safe, and it checks that `code` is a string — a merely branded Error without a real errno code returns `false`.
+
+- ✗ `if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') { … }`
+- ✓ `if (isErrnoException(e) && e.code === 'ENOENT') { … }`
+
+### `errorMessage(value)` — replaces the `instanceof Error ? e.message : String(e)` pattern
+
+Walks the `cause` chain via `messageWithCauses`, coerces primitives and objects to string, and returns the shared `UNKNOWN_ERROR` sentinel (the string `'Unknown error'`) for `null`, `undefined`, empty strings, `[object Object]`, or Errors with no message.
+
+That last bullet is the important one: **every `|| 'Unknown error'` fallback in the fleet should collapse into a single `errorMessage(e)` call.**
+
+- ✗ `` `Failed: ${e instanceof Error ? e.message : String(e)}` ``
+- ✗ `` `Failed: ${(e as Error)?.message ?? 'Unknown error'}` ``
+- ✗ `` `Failed: ${e instanceof Error ? e.message : 'Unknown error'}` ``
+- ✓ `` `Failed: ${errorMessage(e)}` ``
+
+When you want to preserve the cause chain upstream (recommended), pair it with `{ cause }`:
+
+```ts
+try {
+  await readConfig(path)
+} catch (e) {
+  throw new Error(`Failed to read ${path}: ${errorMessage(e)}`, { cause: e })
+}
+```
+
+### `errorStack(value)` — cause-aware stack, or `undefined`
+
+Returns the cause-walking stack for Errors; returns `undefined` for non-Errors so logger calls stay safe:
+
+```ts
+logger.error(`rebuild failed: ${errorMessage(e)}`, { stack: errorStack(e) })
+```
+
 ## Voice & tone
 
 - Imperative for the fix: `rename`, `add`, `remove`, `set`.

package.json

@@ -71,7 +71,7 @@
     "@anthropic-ai/claude-code": "2.1.92",
     "@babel/parser": "7.29.0",
     "@oxlint/migrate": "1.51.0",
-    "@socketsecurity/lib": "5.21.0",
+    "@socketsecurity/lib": "5.24.0",
     "@socketsecurity/registry": "2.0.2",
     "@socketsecurity/sdk": "4.0.1",
     "@types/node": "24.9.2",

pnpm-lock.yaml

@@ -1,26 +1,13 @@
 /**
- * @fileoverview Unwrap a readable message string from a thrown value.
+ * @fileoverview Re-export of the canonical `errorMessage` helper.
  *
- * Mirrors src/error.ts#errorMessage so scripts (which do not depend on
- * the compiled library) have the same helper. Keep the two in sync if
- * either changes.
- */
-
-/**
- * Extract a readable message string from any thrown value.
+ * `@socketsecurity/lib/errors` walks the `cause` chain, coerces primitives,
+ * and returns the shared `UNKNOWN_ERROR` sentinel for null/undefined/empty
+ * — covers every case the old local shim handled and more.
  *
- * Returns `e.message` for Error instances, a coerced string for other
- * non-nullish values, and `'Unknown error'` for nullish or
- * empty-message cases. Use at boundaries where `catch (e: unknown)`
- * needs to surface a message (log lines, error payloads, summaries)
- * without a per-call-site type ladder.
+ * The library helper is not used inside `src/` (that code path uses
+ * primordial-guarded helpers from `src/error.ts` for DoS-hardening); this
+ * file is only for build-time scripts outside the published surface.
  */
-export function errorMessage(e: unknown): string {
-  if (e instanceof Error) {
-    return e.message || 'Unknown error'
-  }
-  if (e === null || e === undefined) {
-    return 'Unknown error'
-  }
-  return String(e) || 'Unknown error'
-}
+
+export { errorMessage } from '@socketsecurity/lib/errors'