@lifeaitools/clauth 1.16.9 → 1.18.0

package/.clauth-skill/SKILL.md

@@ -9,49 +9,49 @@ Hardware-bound credential vault for the LIFEAI stack. Your machine is the second
 
 ---
 
-## How Claude Interfaces with clauth
-
-> **CRITICAL:** Agents should use the local daemon for credential discovery and
-> exact secret retrieval. Do not ask the user for the vault password just to get
-> a key, do not use interactive prompts, and do not walk every service.
-
-### Method 1 — Local daemon (preferred for agents)
-
-Discover services without reading secrets:
-
-```bash
-curl -s http://127.0.0.1:52437/ping
-curl -s http://127.0.0.1:52437/knowledge
-curl -s http://127.0.0.1:52437/list-services
-```
-
-Retrieve exactly one credential only when the next command needs it:
-
-```bash
-curl -s http://127.0.0.1:52437/v/<service>
-```
-
-`/knowledge` is safe to cache for a session: it returns service metadata and
-`has_key`, but no raw secrets and no Vault secret names. `/status` uses the same
-short metadata cache and can be forced with `?refresh=1`.
-
-### Method 2 — CLI with `--pw` flag (admin/setup only)
-
-All clauth commands accept `-p` / `--pw <password>` to skip the interactive
-password prompt. Use this for local admin/setup tasks, not routine agent secret
-retrieval:
-
-```bash
-clauth status -p "YourPassword"
-clauth test -p "YourPassword"
-clauth enable github -p "YourPassword"
-clauth write key github -p "YourPassword"   # still prompts for the key value
-```
-
-### Method 3 — Direct API calls (implementation/debugging only)
-
-Call the auth-vault Edge Function directly only when debugging clauth internals.
-Normal agents should not bypass the daemon metadata cache.
+## How Claude Interfaces with clauth
+
+> **CRITICAL:** Agents should use the local daemon for credential discovery and
+> exact secret retrieval. Do not ask the user for the vault password just to get
+> a key, do not use interactive prompts, and do not walk every service.
+
+### Method 1 — Local daemon (preferred for agents)
+
+Discover services without reading secrets:
+
+```bash
+curl -s http://127.0.0.1:52437/ping
+curl -s http://127.0.0.1:52437/knowledge
+curl -s http://127.0.0.1:52437/list-services
+```
+
+Retrieve exactly one credential only when the next command needs it:
+
+```bash
+curl -s http://127.0.0.1:52437/v/<service>
+```
+
+`/knowledge` is safe to cache for a session: it returns service metadata and
+`has_key`, but no raw secrets and no Vault secret names. `/status` uses the same
+short metadata cache and can be forced with `?refresh=1`.
+
+### Method 2 — CLI with `--pw` flag (admin/setup only)
+
+All clauth commands accept `-p` / `--pw <password>` to skip the interactive
+password prompt. Use this for local admin/setup tasks, not routine agent secret
+retrieval:
+
+```bash
+clauth status -p "YourPassword"
+clauth test -p "YourPassword"
+clauth enable github -p "YourPassword"
+clauth write key github -p "YourPassword"   # still prompts for the key value
+```
+
+### Method 3 — Direct API calls (implementation/debugging only)
+
+Call the auth-vault Edge Function directly only when debugging clauth internals.
+Normal agents should not bypass the daemon metadata cache.
 
 **Base URL:** `https://<project-ref>.supabase.co/functions/v1/auth-vault`
 **Auth header:** `Authorization: Bearer <supabase-anon-key>`
@@ -97,12 +97,12 @@ const timestamp = window * windowMs;
 
 All auth routes require: `machine_hash`, `token`, `timestamp`, `password`.
 
-### Password Handling
-
-- Do not ask the user for their clauth password for routine credential lookup
-- Use the unlocked local daemon whenever possible
-- Never log or echo the password
-- If the daemon is locked, ask the user to unlock `http://127.0.0.1:52437`
+### Password Handling
+
+- Do not ask the user for their clauth password for routine credential lookup
+- Use the unlocked local daemon whenever possible
+- Never log or echo the password
+- If the daemon is locked, ask the user to unlock `http://127.0.0.1:52437`
 
 ---
 
@@ -165,14 +165,14 @@ See `references/keys-guide.md` for where to find every credential.
 ```
 clauth install [--ref R] [--pat P]     First-time: provision Supabase + install skill
 clauth setup [--admin-token T] [-p P]  Register this machine
-clauth status [-p P]                   All services + state
-clauth test [-p P]                     Verify HMAC connection
-clauth list [-p P]                     Service names
-clauth search <query> [-p P]           Search names and metadata
-clauth search <query> --addresses [-p P]
-                                      Also search redacted address hints (may read multiple secrets)
-
-clauth write key <service> [-p P]      Store a credential
+clauth status [-p P]                   All services + state
+clauth test [-p P]                     Verify HMAC connection
+clauth list [-p P]                     Service names
+clauth search <query> [-p P]           Search names and metadata
+clauth search <query> --addresses [-p P]
+                                      Also search redacted address hints (may read multiple secrets)
+
+clauth write key <service> [-p P]      Store a credential
 clauth write pw [-p P]                 Change password
 clauth enable <svc|all> [-p P]         Activate service
 clauth disable <svc|all> [-p P]        Suspend service
@@ -201,65 +201,65 @@ Service type `fileserver` — mount configuration for fs tools (UI-only config).
 
 ---
 
-## Daemon Metadata Cache
-
-When discovering service names, do not retrieve secrets. Use the daemon metadata
-cache:
-
-```bash
-curl -s http://127.0.0.1:52437/knowledge
-curl -s http://127.0.0.1:52437/list-services
-```
-
-`/knowledge` is agent-safe: it returns service metadata and `has_key`, but no
-raw secrets and no Vault secret names. Fetch `GET /v/<service>` only for the one
-exact credential needed by the next command. Never walk every service and never
-bulk-fetch all secrets.
-
-## MCP Server (v1.16.9+)
-
-clauth runs as an MCP server with five namespaced paths and safe
-credential-discovery tools:
-
-| Path | Namespace | Tools |
-|------|-----------|-------|
-| `/clauth` | `clauth_*` + runtime helpers | 23 default live tools, including `clauth_knowledge` |
-| `/gws` | `gws_*` | 6 Google Workspace tools |
-| `/fs` | `fs_*` | 20 filesystem and git-safe file tools |
-| `/chitchat` | `chitchat_*` | 7 collaboration relay tools |
-| `/codevelop` | `codevelop_*` | 7 peer development tools |
-| `/mcp` | all | 63 tools combined |
-
-The default live `/clauth` surface includes credential tools plus
-`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`.
-Admin write tools are gated by write-mode.
+## Daemon Metadata Cache
+
+When discovering service names, do not retrieve secrets. Use the daemon metadata
+cache:
+
+```bash
+curl -s http://127.0.0.1:52437/knowledge
+curl -s http://127.0.0.1:52437/list-services
+```
+
+`/knowledge` is agent-safe: it returns service metadata and `has_key`, but no
+raw secrets and no Vault secret names. Fetch `GET /v/<service>` only for the one
+exact credential needed by the next command. Never walk every service and never
+bulk-fetch all secrets.
+
+## MCP Server (v1.16.9+)
+
+clauth runs as an MCP server with five namespaced paths and safe
+credential-discovery tools:
+
+| Path | Namespace | Tools |
+|------|-----------|-------|
+| `/clauth` | `clauth_*` + runtime helpers | 23 default live tools, including `clauth_knowledge` |
+| `/gws` | `gws_*` | 6 Google Workspace tools |
+| `/fs` | `fs_*` | 20 filesystem and git-safe file tools |
+| `/chitchat` | `chitchat_*` | 7 collaboration relay tools |
+| `/codevelop` | `codevelop_*` | 7 peer development tools |
+| `/mcp` | all | 63 tools combined |
+
+The default live `/clauth` surface includes credential tools plus
+`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`.
+Admin write tools are gated by write-mode.
 
 ### claude.ai Connector URLs (noauth mode)
-- `https://clauth.regendevcorp.com/clauth` — credential tools
-- `https://clauth.regendevcorp.com/gws` — Google Workspace
-- `https://clauth.regendevcorp.com/chitchat` — collaboration relay tools
-- `https://clauth.regendevcorp.com/codevelop` — peer development tools
-- `https://fs.regendevcorp.com/fs` — filesystem tools
-
-Noauth mode: fresh domains that return 404 on OAuth endpoints. claude.ai connects directly (Anthropic OAuth proxy bug workaround).
-
-Use `clauth_knowledge` or `clauth_status` for discovery. Use `clauth_get` only
-for one exact secret. `clauth_search` is metadata-only by default; pass
-`addresses: true` only when redacted address hints are intentionally needed.
-`clauth_inject` is guarded against accidental bulk vault sweeps.
-
-### FS Tools
-`fs_read` `fs_write` `fs_stat` `fs_append` `fs_write_chunk` `fs_ingest_url`
-`fs_import_git_files` `fs_list` `fs_grep` `fs_glob` `fs_delete` `fs_mkdir`
-`fs_edit` `fs_move` `fs_copy` `fs_mounts` `fs_repo_status` `fs_use_branch`
-`fs_commit` `fs_diff`
+- `https://clauth.regendevcorp.com/clauth` — credential tools
+- `https://clauth.regendevcorp.com/gws` — Google Workspace
+- `https://clauth.regendevcorp.com/chitchat` — collaboration relay tools
+- `https://clauth.regendevcorp.com/codevelop` — peer development tools
+- `https://fs.regendevcorp.com/fs` — filesystem tools
+
+Noauth mode: fresh domains that return 404 on OAuth endpoints. claude.ai connects directly (Anthropic OAuth proxy bug workaround).
+
+Use `clauth_knowledge` or `clauth_status` for discovery. Use `clauth_get` only
+for one exact secret. `clauth_search` is metadata-only by default; pass
+`addresses: true` only when redacted address hints are intentionally needed.
+`clauth_inject` is guarded against accidental bulk vault sweeps.
+
+### FS Tools
+`fs_read` `fs_write` `fs_stat` `fs_append` `fs_write_chunk` `fs_ingest_url`
+`fs_import_git_files` `fs_list` `fs_grep` `fs_glob` `fs_delete` `fs_mkdir`
+`fs_edit` `fs_move` `fs_copy` `fs_mounts` `fs_repo_status` `fs_use_branch`
+`fs_commit` `fs_diff`
 
 Path-jail security: all paths resolved against mount root. Permission flags (r/w/d) per mount. Uses `@vscode/ripgrep` for grep, `fast-glob` for glob.
 
-### Testing
-```bash
-node test-tools.mjs    # MCP tool execution smoke tests
-```
+### Testing
+```bash
+node test-tools.mjs    # MCP tool execution smoke tests
+```
 
 ---
 

package/README.md

@@ -27,37 +27,37 @@ At the end it prints a **bootstrap token** — save it for the next step.
 
 ---
 
-## After Install — Register Your Machine
-
-```bash
-clauth setup
-```
+## After Install — Register Your Machine
+
+```bash
+clauth setup
+```
 
 Prompts for: machine label, password, bootstrap token (from `clauth install`).
 
-Then verify:
-```bash
-clauth test      # → PASS
-clauth status    # → 12 services, all NO KEY
-```
-
-### Add A New Computer
-
-On an old computer where clauth is already registered:
-
-```bash
-clauth enroll --label "Dave-New-Laptop"
-```
-
-This creates a one-time enrollment code tied to the same `install_id` and writes
-a one-time PowerShell setup script. Move that script to the new computer and run
-it. The script installs clauth, enrolls the computer, installs startup, then
-deletes itself. Setup defaults the machine label to the computer name and only
-asks you to set the new computer's local clauth password.
-
-The enrollment code does not copy repo credentials into the script. It lets the
-new hardware-bound `machine_hash` join the shared Supabase Vault once. After the
-code is redeemed, it cannot be used again.
+Then verify:
+```bash
+clauth test      # → PASS
+clauth status    # → 12 services, all NO KEY
+```
+
+### Add A New Computer
+
+On an old computer where clauth is already registered:
+
+```bash
+clauth enroll --label "Dave-New-Laptop"
+```
+
+This creates a one-time enrollment code tied to the same `install_id` and writes
+a one-time PowerShell setup script. Move that script to the new computer and run
+it. The script installs clauth, enrolls the computer, installs startup, then
+deletes itself. Setup defaults the machine label to the computer name and only
+asks you to set the new computer's local clauth password.
+
+The enrollment code does not copy repo credentials into the script. It lets the
+new hardware-bound `machine_hash` join the shared Supabase Vault once. After the
+code is redeemed, it cannot be used again.
 
 ---
 
@@ -88,13 +88,13 @@ clauth get github
 ## Command Reference
 
 ```
-clauth install              Provision Supabase + install Claude skill
-clauth setup                Register this machine with the vault
-clauth enroll               Create one-time code to add another computer
-clauth status               All services + state
-clauth search <query>       Find services by name, project, description, or type
-clauth search <query> --addresses
-                            Also search redacted address hints (may read multiple secrets)
+clauth install              Provision Supabase + install Claude skill
+clauth setup                Register this machine with the vault
+clauth enroll               Create one-time code to add another computer
+clauth status               All services + state
+clauth search <query>       Find services by name, project, description, or type
+clauth search <query> --addresses
+                            Also search redacted address hints (may read multiple secrets)
 clauth test                 Verify connection
 
 clauth write key <service>  Store a credential
@@ -137,81 +137,81 @@ Nothing stored locally. Password never persisted. Machine hash is one-way only.
 
 clauth runs as an HTTP daemon on `http://127.0.0.1:52437`. The daemon provides:
 
-- **Web UI** — unlock vault, manage services, configure mounts
-- **REST API** — `GET /knowledge`, `GET /status`, `GET /v/<service>`, `GET /ping`, `POST /restart`, `GET /shutdown`
-- **MCP server** — Model Context Protocol for Claude Code and claude.ai
-- **Cloudflare Tunnel** — exposes MCP endpoints publicly for claude.ai connectors
-
-Start: `clauth serve start` (starts locked, auto-opens browser for unlock).
-
-Full daemon operations reference: see `regen-root/.claude/rules/clauth.md`.
-
-### Safe Metadata Cache
-
-Agents and scripts must discover services through metadata endpoints, not by
-walking every secret endpoint. The daemon caches service metadata for 30 seconds:
-
-```bash
-curl -s http://127.0.0.1:52437/knowledge      # sanitized, agent-safe metadata
-curl -s http://127.0.0.1:52437/list-services  # names only
-curl -s http://127.0.0.1:52437/status         # full daemon metadata, cached
-```
-
-`/knowledge` returns service names, labels, key types, enabled state, project,
-description, timestamps, and `has_key`. It never returns raw secrets or Vault
-secret names. Use `GET /v/<service>` only for the one exact secret needed by the
-next command. Do not bulk-fetch every service.
+- **Web UI** — unlock vault, manage services, configure mounts
+- **REST API** — `GET /knowledge`, `GET /status`, `GET /v/<service>`, `GET /ping`, `POST /restart`, `GET /shutdown`
+- **MCP server** — Model Context Protocol for Claude Code and claude.ai
+- **Cloudflare Tunnel** — exposes MCP endpoints publicly for claude.ai connectors
+
+Start: `clauth serve start` (starts locked, auto-opens browser for unlock).
+
+Full daemon operations reference: see `regen-root/.claude/rules/clauth.md`.
+
+### Safe Metadata Cache
+
+Agents and scripts must discover services through metadata endpoints, not by
+walking every secret endpoint. The daemon caches service metadata for 30 seconds:
+
+```bash
+curl -s http://127.0.0.1:52437/knowledge      # sanitized, agent-safe metadata
+curl -s http://127.0.0.1:52437/list-services  # names only
+curl -s http://127.0.0.1:52437/status         # full daemon metadata, cached
+```
+
+`/knowledge` returns service names, labels, key types, enabled state, project,
+description, timestamps, and `has_key`. It never returns raw secrets or Vault
+secret names. Use `GET /v/<service>` only for the one exact secret needed by the
+next command. Do not bulk-fetch every service.
 
 ---
 
-## MCP Server — 5 Namespaces, 63 Tools
-
-clauth is the single MCP interface for all local tools. One process, namespaced paths:
-
-| Path | Namespace | Tools | Description |
-|------|-----------|-------|-------------|
-| `/clauth` | `clauth_*` + runtime helpers | 23 | Credential vault operations, safe metadata cache, and agent runtime helpers |
-| `/gws` | `gws_*` | 6 | Google Workspace (Gmail, Calendar, Drive) |
-| `/fs` | `fs_*` | 20 | Filesystem plus guarded git/local-branch tools |
-| `/chitchat` | `chitchat_*` | 7 | Collaboration relay sessions |
-| `/codevelop` | `codevelop_*` | 7 | Peer development sessions |
-| `/mcp` | all | 63 | All namespaces combined (Claude Code) |
-
-The default live `/clauth` surface includes 13 credential tools plus
-`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`
-runtime helpers. Admin write tools such as enable/disable/project/token actions
-are gated by write-mode.
-
-### clauth MCP Usage
-
-Use `clauth_knowledge` or `clauth_status` for discovery. They use cached
-metadata and never retrieve raw secrets. `clauth_search` is metadata-only by
-default; pass `addresses: true` only when you intentionally need redacted address
-hints from connstrings/fileserver/oauth secrets. `clauth_get` is for one exact
-secret. `clauth_inject` refuses more than five services unless `allow_many: true`
-is explicitly supplied, to prevent accidental rate-limit lockouts from bulk
-secret sweeps.
+## MCP Server — 5 Namespaces, 63 Tools
+
+clauth is the single MCP interface for all local tools. One process, namespaced paths:
+
+| Path | Namespace | Tools | Description |
+|------|-----------|-------|-------------|
+| `/clauth` | `clauth_*` + runtime helpers | 23 | Credential vault operations, safe metadata cache, and agent runtime helpers |
+| `/gws` | `gws_*` | 6 | Google Workspace (Gmail, Calendar, Drive) |
+| `/fs` | `fs_*` | 20 | Filesystem plus guarded git/local-branch tools |
+| `/chitchat` | `chitchat_*` | 7 | Collaboration relay sessions |
+| `/codevelop` | `codevelop_*` | 7 | Peer development sessions |
+| `/mcp` | all | 63 | All namespaces combined (Claude Code) |
+
+The default live `/clauth` surface includes 13 credential tools plus
+`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`
+runtime helpers. Admin write tools such as enable/disable/project/token actions
+are gated by write-mode.
+
+### clauth MCP Usage
+
+Use `clauth_knowledge` or `clauth_status` for discovery. They use cached
+metadata and never retrieve raw secrets. `clauth_search` is metadata-only by
+default; pass `addresses: true` only when you intentionally need redacted address
+hints from connstrings/fileserver/oauth secrets. `clauth_get` is for one exact
+secret. `clauth_inject` refuses more than five services unless `allow_many: true`
+is explicitly supplied, to prevent accidental rate-limit lockouts from bulk
+secret sweeps.
 
 ### FS Tools
 
-20 filesystem tools with path-jail security:
-- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_edit`, `fs_move`, `fs_copy`, `fs_mounts`, `fs_repo_status`, `fs_use_branch`, `fs_commit`, `fs_diff`
+20 filesystem tools with path-jail security:
+- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_edit`, `fs_move`, `fs_copy`, `fs_mounts`, `fs_repo_status`, `fs_use_branch`, `fs_commit`, `fs_diff`
 - Uses `node:fs/promises` (async), `@vscode/ripgrep` (shipped binary), `fast-glob`
 - Permission flags per mount: `r` (read), `w` (write), `d` (delete)
 - Mount config stored as "fileserver" service type in vault — only configurable through web UI
-- Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
-- Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
-
-### Collaboration Tools
-
-Chitchat tools: `chitchat_start`, `chitchat_list`, `chitchat_send`, `chitchat_recv`, `chitchat_reply`, `chitchat_poll`, `chitchat_stop`
-
-Codevelop tools: `codevelop_start`, `codevelop_join`, `codevelop_send`, `codevelop_poll`, `codevelop_status`, `codevelop_stream`, `codevelop_stop`
-
-### GWS Tools
-
-6 Google Workspace tools: `gws_run`, `gws_gmail_list`, `gws_gmail_read`, `gws_gmail_send`, `gws_calendar_list`, `gws_drive_list`
-- Calls `gws` CLI via `execSync` with `shell: 'bash'` (fixes Windows cmd.exe JSON quoting)
+- Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
+- Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
+
+### Collaboration Tools
+
+Chitchat tools: `chitchat_start`, `chitchat_list`, `chitchat_send`, `chitchat_recv`, `chitchat_reply`, `chitchat_poll`, `chitchat_stop`
+
+Codevelop tools: `codevelop_start`, `codevelop_join`, `codevelop_send`, `codevelop_poll`, `codevelop_status`, `codevelop_stream`, `codevelop_stop`
+
+### GWS Tools
+
+6 Google Workspace tools: `gws_run`, `gws_gmail_list`, `gws_gmail_read`, `gws_gmail_send`, `gws_calendar_list`, `gws_drive_list`
+- Calls `gws` CLI via `execSync` with `shell: 'bash'` (fixes Windows cmd.exe JSON quoting)
 
 ---
 
@@ -235,11 +235,11 @@ Full OAuth 2.1 protocol implementation is present for future use when Anthropic
 
 | Connector | URL |
 |-----------|-----|
-| clauth | `https://clauth.regendevcorp.com/clauth` |
-| gws | `https://clauth.regendevcorp.com/gws` |
-| chitchat | `https://clauth.regendevcorp.com/chitchat` |
-| codevelop | `https://clauth.regendevcorp.com/codevelop` |
-| fs | `https://fs.regendevcorp.com/fs` |
+| clauth | `https://clauth.regendevcorp.com/clauth` |
+| gws | `https://clauth.regendevcorp.com/gws` |
+| chitchat | `https://clauth.regendevcorp.com/chitchat` |
+| codevelop | `https://clauth.regendevcorp.com/codevelop` |
+| fs | `https://fs.regendevcorp.com/fs` |
 
 ---
 
@@ -252,9 +252,9 @@ Full OAuth 2.1 protocol implementation is present for future use when Anthropic
 
 ## Testing
 
-```bash
-node test-tools.mjs    # MCP tool execution smoke tests
-```
+```bash
+node test-tools.mjs    # MCP tool execution smoke tests
+```
 
 Tests actual MCP tool calls (not just OAuth + listing).
 

package/cli/api.classify.test.js

@@ -0,0 +1,75 @@
+// cli/api.classify.test.js
+// Regression tests for backend/external-resource error classification.
+//
+// WHY THIS EXISTS: on 2026-06-19 a saturated Postgres database made every
+// auth-vault verify call time out. clauth counted each timeout as an
+// authentication failure ([AUTH FAIL n/10]), hit the strike ceiling, and
+// hard-locked the vault — turning a transient DB blip into a full lockout that
+// blocked Claude/Codex from starting. A database timeout, a 5xx, a network
+// drop, or a rate-limit is NOT a wrong password and must never take a strike.
+// These tests pin that classification so the regression can't return.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  VaultBackendError,
+  classifyBackendError,
+  classifyServerReason,
+} from "./api.js";
+
+test("VaultBackendError marks failures as non-strike + retriable", () => {
+  const e = new VaultBackendError("timeout", "no response", { status: 504, detail: "abort" });
+  assert.equal(e.kind, "timeout");
+  assert.equal(e.isBackend, true);
+  assert.equal(e.retriable, true);
+  assert.equal(e.status, 504);
+  assert.ok(e instanceof Error);
+});
+
+test("classifyBackendError: AbortSignal.timeout shapes => 'timeout'", () => {
+  // This is the exact error that slipped through the old substring check.
+  assert.equal(classifyBackendError({ name: "TimeoutError", message: "The operation was aborted due to timeout" }), "timeout");
+  assert.equal(classifyBackendError({ name: "AbortError", message: "This operation was aborted" }), "timeout");
+  assert.equal(classifyBackendError(new Error("request timed out")), "timeout");
+});
+
+test("classifyBackendError: network/transport shapes => 'network'", () => {
+  assert.equal(classifyBackendError(new Error("fetch failed")), "network");
+  assert.equal(classifyBackendError(new Error("connect ECONNREFUSED 127.0.0.1:443")), "network");
+  assert.equal(classifyBackendError(new Error("getaddrinfo ENOTFOUND db.supabase.co")), "network");
+  assert.equal(classifyBackendError(new Error("read ECONNRESET")), "network");
+});
+
+test("classifyBackendError: a typed VaultBackendError passes its kind through", () => {
+  assert.equal(classifyBackendError(new VaultBackendError("rate_limited", "slow down")), "rate_limited");
+  assert.equal(classifyBackendError(new VaultBackendError("db_error", "pool exhausted")), "db_error");
+});
+
+test("classifyBackendError: a genuine credential error is NOT a backend error", () => {
+  assert.equal(classifyBackendError(new Error("Wrong password")), null);
+  assert.equal(classifyBackendError(new Error("invalid_token")), null);
+  assert.equal(classifyBackendError(null), null);
+  assert.equal(classifyBackendError(undefined), null);
+});
+
+test("classifyServerReason: rate-limit reasons => 'rate_limited'", () => {
+  assert.equal(classifyServerReason("rate_limited"), "rate_limited");
+  assert.equal(classifyServerReason("Rate limit: 38/30 per 60s"), "rate_limited");
+});
+
+test("classifyServerReason: database/backend reasons => 'db_error'", () => {
+  assert.equal(classifyServerReason("canceling statement due to statement timeout"), "db_error");
+  assert.equal(classifyServerReason("database connection pool exhausted"), "db_error");
+  assert.equal(classifyServerReason("internal server error"), "db_error");
+  assert.equal(classifyServerReason("service unavailable"), "db_error");
+});
+
+test("classifyServerReason: genuine auth verdicts are NOT backend errors (they strike)", () => {
+  assert.equal(classifyServerReason("invalid_token (3/5)"), null);
+  assert.equal(classifyServerReason("machine_locked"), null);
+  assert.equal(classifyServerReason("machine_disabled"), null);
+  assert.equal(classifyServerReason("machine_not_found"), null);
+  assert.equal(classifyServerReason("wrong_password"), null);
+  assert.equal(classifyServerReason(null), null);
+  assert.equal(classifyServerReason(""), null);
+});