@mnemom/mnemom 0.12.0 → 0.13.0

package/dist/commands/card.d.ts

@@ -29,7 +29,10 @@ export declare function cardShowCommand(agentName?: string): Promise<void>;
 export declare function cardPublishCommand(file: string, agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;
-export declare function cardValidateCommand(file: string): Promise<void>;
+export declare function cardValidateCommand(file: string, opts?: {
+    offline?: boolean;
+    agent?: string;
+}): Promise<void>;
 export declare function cardEditCommand(agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;

package/dist/commands/card.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 import yaml from "js-yaml";
-import { ALIGNMENT_CARD_MAX_BYTES, getAlignmentCard, putAlignmentCard, resolveAgentId, } from "../lib/api.js";
+import { ALIGNMENT_CARD_MAX_BYTES, getAlignmentCard, putAlignmentCard, resolveAgentId, getAgentByName, previewComposeAgentCard, MnemomApiError, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
@@ -194,6 +194,28 @@ export function validateUnifiedCard(card) {
     else {
         const v = card.values;
         const decl = v.declared;
+        // A declared entry is a non-empty STRING or a parameterized OBJECT
+        // { id, ...string params } — mirrors mnemom-api/src/composition/validate.ts
+        // `declaredValueRefId`. (#8 DELTA-1: the old `decl.every(typeof === "string")`
+        // rejected the valid object form, making the CLI STRICTER than the server —
+        // a false-negative that blocked good cards in pre-flight.)
+        const declRefId = (entry) => {
+            if (typeof entry === "string")
+                return entry.length > 0 ? entry : null;
+            if (!isObj(entry))
+                return null;
+            const o = entry;
+            if (typeof o.id !== "string" || o.id.length === 0)
+                return null;
+            for (const [k, pv] of Object.entries(o)) {
+                if (k === "id")
+                    continue;
+                if (typeof pv !== "string")
+                    return null;
+            }
+            return o.id;
+        };
+        const declIds = [];
         if (decl.length === 0) {
             checks.push({
                 name: "values.declared",
@@ -201,21 +223,32 @@ export function validateUnifiedCard(card) {
                 message: "Must contain at least one value.",
             });
         }
-        else if (!decl.every((s) => typeof s === "string")) {
-            checks.push({
-                name: "values.declared",
-                passed: false,
-                message: "All entries must be strings.",
-            });
-        }
         else {
-            checks.push({
-                name: "values.declared",
-                passed: true,
-                message: `${decl.length} value(s) declared`,
+            let badRef = false;
+            decl.forEach((entry, i) => {
+                const id = declRefId(entry);
+                if (id === null) {
+                    checks.push({
+                        name: `values.declared[${i}]`,
+                        passed: false,
+                        message: "Must be a non-empty string or an object with a non-empty string `id` and string-only parameters.",
+                    });
+                    badRef = true;
+                }
+                else {
+                    declIds.push(id);
+                }
             });
+            if (!badRef) {
+                checks.push({
+                    name: "values.declared",
+                    passed: true,
+                    message: `${decl.length} value(s) declared`,
+                });
+            }
         }
-        // definitions ⊆ declared (ADR-039 Decision 10)
+        // definitions ⊆ declared (ADR-039 Decision 10) — build the subset Set from
+        // the RESOLVED declared ids (string entries + each object's `id`).
         if (v.definitions !== undefined) {
             if (!isObj(v.definitions)) {
                 checks.push({
@@ -225,7 +258,7 @@ export function validateUnifiedCard(card) {
                 });
             }
             else {
-                const declSet = new Set(decl.filter((s) => typeof s === "string"));
+                const declSet = new Set(declIds);
                 for (const key of Object.keys(v.definitions)) {
                     if (!declSet.has(key)) {
                         checks.push({
@@ -626,7 +659,27 @@ export async function cardPublishCommand(file, agentName, options = {}) {
         process.exit(1);
     }
 }
-export async function cardValidateCommand(file) {
+const AGENT_ID_RE = /^(smolt-[0-9a-f]{8}|mnm-[0-9a-f-]{36})$/;
+/**
+ * Soft agent resolution for `validate`: returns an agent id WITHOUT exiting the
+ * process (unlike resolveAgentId). Returns null when no agent is configured, or
+ * the name can't be resolved (not authenticated / not found) — the caller then
+ * falls back to offline validation.
+ */
+async function softResolveAgentId(agent) {
+    const name = agent ?? process.env.MNEMOM_AGENT;
+    if (!name)
+        return null;
+    if (AGENT_ID_RE.test(name))
+        return name;
+    try {
+        return (await getAgentByName(name))?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function cardValidateCommand(file, opts = {}) {
     // Resolve file path
     const filePath = path.resolve(file);
     if (!fs.existsSync(filePath)) {
@@ -643,7 +696,35 @@ export async function cardValidateCommand(file) {
         console.log("\n" + fmt.error(`Could not parse file: ${msg}`) + "\n");
         process.exit(1);
     }
-    // Validate the parsed object
+    // Prefer server-authoritative validation (composes against the agent's
+    // org/platform floor — catches conflicts the offline validator cannot) when
+    // online + an agent is available. Fall back to the local validator on
+    // 401/network. `--offline` forces local-only (#9).
+    if (!opts.offline) {
+        const agentId = await softResolveAgentId(opts.agent);
+        if (agentId) {
+            const contentType = parsed.format === "yaml" ? "text/yaml" : "application/json";
+            try {
+                const result = await previewComposeAgentCard(agentId, "alignment", parsed.raw, contentType);
+                renderServerCardValidation(result, filePath, parsed.format);
+                return;
+            }
+            catch (err) {
+                if (err instanceof MnemomApiError && err.status !== 401) {
+                    // 403 / 5xx — a genuine server error, not the offline-fallback case.
+                    console.log("\n" + fmt.error(`Server validation failed: ${err.message}`) + "\n");
+                    process.exit(1);
+                }
+                // 401 or network error → fall through to offline validation.
+                process.stderr.write(fmt.warn("offline validation — server rules may differ") + "\n");
+            }
+        }
+        else if (!opts.agent && !process.env.MNEMOM_AGENT) {
+            process.stderr.write(fmt.dim("tip: pass --agent <name> to validate against the server (org/platform floor)") +
+                "\n");
+        }
+    }
+    // Offline / fallback path: the local hand-rolled validator (also `--offline`).
     const checks = validateUnifiedCard(parsed.parsed);
     const allPassed = checks.every((c) => c.passed);
     const passCount = checks.filter((c) => c.passed).length;
@@ -670,6 +751,38 @@ export async function cardValidateCommand(file) {
         process.exit(1);
     }
 }
+/** Render a server-authoritative preview-compose result; exit 1 if invalid. */
+function renderServerCardValidation(result, filePath, format) {
+    console.log(fmt.header("Card Validation (server-authoritative)"));
+    console.log();
+    console.log(fmt.label("  File:", ` ${filePath}`));
+    console.log(fmt.label("  Format:", ` ${format.toUpperCase()}`));
+    console.log();
+    if (result.valid) {
+        console.log(fmt.success("Server accepted and composed the card."));
+        const conflicts = result.conflicts ?? [];
+        if (conflicts.length > 0) {
+            console.log(fmt.warn(`${conflicts.length} field(s) tightened by the org/platform floor:`));
+            console.log(fmt.json(conflicts));
+        }
+        const coherence = result.coherence_violations ?? [];
+        if (coherence.length > 0) {
+            console.log(fmt.warn(`${coherence.length} coherence finding(s):`));
+            console.log(fmt.json(coherence));
+        }
+        console.log();
+        return;
+    }
+    console.log(fmt.error(`Server rejected the card${result.error?.code ? ` (${result.error.code})` : ""}:`));
+    if (result.error?.message)
+        console.log(`  ${result.error.message}`);
+    if (result.error?.details !== undefined) {
+        console.log();
+        console.log(fmt.json(result.error.details));
+    }
+    console.log();
+    process.exit(1);
+}
 export async function cardEditCommand(agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     await requireAuth();

package/dist/commands/integrity.js

@@ -1,4 +1,4 @@
-import { resolveAgentId, getIntegrity } from "../lib/api.js";
+import { resolveAgentId, getIntegrity, MnemomApiError } from "../lib/api.js";
 import { fmt } from "../lib/format.js";
 export async function integrityCommand(agentName) {
     const agentId = await resolveAgentId(agentName);
@@ -25,8 +25,11 @@ export async function integrityCommand(agentName) {
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
+        // A 404 means no integrity record exists yet — render the friendly empty state.
+        // Branch on effectiveStatus (not status): the enforce hook rewrites an
+        // undocumented 404 to a synthetic 500 carrying spec_deviation.original_status,
+        // and effectiveStatus surfaces the true status (=== status when documented).
+        if (error instanceof MnemomApiError && error.effectiveStatus === 404) {
             console.log(fmt.header("Integrity Score"));
             console.log(`  ${fmt.label("Score:     ", "N/A")}`);
             console.log(`  ${fmt.label("Total:     ", "0 traces")}`);
@@ -35,6 +38,7 @@ export async function integrityCommand(agentName) {
             console.log("\nNo traces recorded yet. Start using Claude to build your integrity score.\n");
         }
         else {
+            const message = error instanceof Error ? error.message : String(error);
             console.log("\n" + fmt.error(`Failed to fetch integrity score: ${message}`) + "\n");
             process.exit(1);
         }

package/dist/commands/license.js

@@ -1,10 +1,7 @@
 import { getLicenseJwt, saveLicenseJwt, clearLicenseJwt } from "../lib/auth.js";
-import { API_BASE } from "../lib/api.js";
+import { validateLicense, MnemomApiError } from "../lib/api.js";
 import { fmt } from "../lib/format.js";
-/** Sanitize file-sourced data before use in outbound HTTP requests. */
-function sanitizeForHttp(data) {
-    return String(data).trim();
-}
+import { CLI_VERSION } from "../version.js";
 /**
  * Decode a JWT payload without verifying the signature.
  */
@@ -34,39 +31,37 @@ export async function licenseActivateCommand(jwt) {
         process.exit(1);
     }
     console.log("\nActivating enterprise license...\n");
-    // Validate against API (if reachable)
+    // Validate against the API via the canonical lib helper (UNAUTH by design —
+    // the JWT is the credential). validateLicense throws MnemomApiError on non-2xx,
+    // so we render `.message` (the old hand-rolled `err.error` string-coerced the
+    // nested {code,message} envelope object → the live "[object Object]" bug).
     const hostname = (await import("node:os")).hostname();
     try {
-        const licenseUrl = new URL(`${API_BASE}/v1/license/validate`).href;
-        const response = await fetch(licenseUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                license: jwt,
-                instance_id: hostname,
-                instance_metadata: {
-                    hostname,
-                    platform: process.platform,
-                    cli_version: "2.1.0",
-                },
-            }),
+        const result = await validateLicense(jwt, hostname, {
+            hostname,
+            platform: process.platform,
+            cli_version: CLI_VERSION,
         });
-        if (response.ok) {
-            const result = (await response.json());
+        if (result.valid) {
             console.log("  License validated successfully!\n");
-            if (result.warning) {
-                console.log(`  Warning: ${result.warning}\n`);
-            }
         }
         else {
-            const err = (await response.json());
-            console.log(`  Warning: Validation returned ${response.status}: ${err.error || "unknown"}`);
-            console.log("  License stored locally (will retry validation).\n");
+            // 2xx body with valid:false — grace period / activation limit reached.
+            console.log("  Note: server returned valid:false (grace period or activation limit).\n");
+        }
+        if (result.warning) {
+            console.log(`  Warning: ${result.warning}\n`);
         }
     }
-    catch {
-        console.log("  Warning: Could not reach API for validation.");
-        console.log("  License stored locally (offline mode).\n");
+    catch (err) {
+        if (err instanceof MnemomApiError) {
+            console.log(`  Warning: Validation returned ${err.status}: ${err.message}`);
+            console.log("  License stored locally (will retry validation).\n");
+        }
+        else {
+            console.log("  Warning: Could not reach API for validation.");
+            console.log("  License stored locally (offline mode).\n");
+        }
     }
     // Store in auth store
     saveLicenseJwt(jwt);
@@ -131,24 +126,17 @@ export async function licenseDeactivateCommand() {
         console.log("\nNo enterprise license to deactivate.\n");
         return;
     }
-    // Try to deactivate via API
+    // Try to deactivate via API (best-effort, fire-and-forget — reuses the
+    // validate endpoint with deactivating:true; local removal below is the source
+    // of truth). Ignore both the result and any MnemomApiError.
     const claims = decodeJwtPayload(licenseJwt);
     if (claims) {
         try {
             const hostname = (await import("node:os")).hostname();
-            const deactivateUrl = new URL(`${API_BASE}/v1/license/validate`).href;
-            await fetch(deactivateUrl, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: sanitizeForHttp(JSON.stringify({
-                    license: String(licenseJwt),
-                    instance_id: hostname,
-                    instance_metadata: { deactivating: true },
-                })),
-            });
+            await validateLicense(String(licenseJwt), hostname, { deactivating: true });
         }
         catch {
-            // Best-effort
+            // Best-effort — ignore.
         }
     }
     // Remove from auth store

package/dist/commands/logs.js

@@ -1,4 +1,4 @@
-import { resolveAgentId, getTraces } from "../lib/api.js";
+import { resolveAgentId, getTraces, MnemomApiError } from "../lib/api.js";
 import { getGatewayUrl } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 export async function logsCommand(options = {}) {
@@ -23,12 +23,16 @@ export async function logsCommand(options = {}) {
         console.log(`Dashboard: https://mnemon.ai/dashboard/${agentId}\n`);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
+        // A 404 means the agent isn't registered yet — treat as the empty state.
+        // Branch on effectiveStatus (not status): the enforce hook rewrites an
+        // undocumented 404 to a synthetic 500 carrying spec_deviation.original_status;
+        // effectiveStatus surfaces the true status (=== status when documented).
+        if (error instanceof MnemomApiError && error.effectiveStatus === 404) {
             console.log(fmt.header("No traces found"));
             console.log("\nStart using Claude to generate traces.\n");
         }
         else {
+            const message = error instanceof Error ? error.message : String(error);
             console.log("\n" + fmt.error(`Failed to fetch traces: ${message}`) + "\n");
             process.exit(1);
         }
@@ -36,16 +40,28 @@ export async function logsCommand(options = {}) {
 }
 function displayTrace(trace) {
     const timestamp = formatTimestamp(trace.timestamp);
-    const statusMsg = trace.verified ? fmt.success(timestamp) : fmt.error(`${timestamp} [VIOLATION]`);
+    // `verification` is null when the trace hasn't been verified yet — that is NOT
+    // a violation. Only flag [VIOLATION] when verification exists AND verified===false.
+    // (The old flat `trace.verified` was always undefined on the nested wire → every
+    // trace was mis-flagged [VIOLATION] and the action rendered as "[object Object]".)
+    const verified = trace.verification?.verified ?? true;
+    const statusMsg = verified ? fmt.success(timestamp) : fmt.error(`${timestamp} [VIOLATION]`);
     console.log(`\n  ${statusMsg}`);
-    console.log(`  ${fmt.label("Action:", ` ${trace.action}`)}`);
-    if (trace.tool_name) {
-        console.log(`  ${fmt.label("Tool:  ", ` ${trace.tool_name}`)}`);
+    // action.name is the canonical label (the tool name lives here in the AIP-nested
+    // shape); fall back to the action type, then a dash.
+    const actionLabel = trace.action?.name ?? trace.action?.type ?? "—";
+    console.log(`  ${fmt.label("Action:", ` ${actionLabel}`)}`);
+    if (trace.action?.category) {
+        console.log(`  ${fmt.label("Type:  ", ` ${trace.action.category}`)}`);
     }
-    if (trace.reasoning) {
-        const preview = truncate(trace.reasoning, 60);
+    const reasoning = trace.decision?.selection_reasoning;
+    if (reasoning) {
+        const preview = truncate(reasoning, 60);
         console.log(`  ${fmt.label("Reason:", ` ${preview}`)}`);
     }
+    if (trace.verification && trace.verification.violations.length > 0) {
+        console.log(`  ${fmt.label("Issues:", ` ${trace.verification.violations.join(", ")}`)}`);
+    }
 }
 function formatTimestamp(iso) {
     try {

package/dist/commands/protection.d.ts

@@ -16,7 +16,10 @@ export declare function protectionShowCommand(agentName?: string): Promise<void>
 export declare function protectionPublishCommand(file: string, agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;
-export declare function protectionValidateCommand(file: string): Promise<void>;
+export declare function protectionValidateCommand(file: string, opts?: {
+    offline?: boolean;
+    agent?: string;
+}): Promise<void>;
 export declare function protectionEditCommand(agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;

package/dist/commands/protection.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 import yaml from "js-yaml";
-import { PROTECTION_CARD_MAX_BYTES, getProtectionCard, putProtectionCard, resolveAgentId, } from "../lib/api.js";
+import { PROTECTION_CARD_MAX_BYTES, getProtectionCard, putProtectionCard, resolveAgentId, getAgentByName, previewComposeAgentCard, MnemomApiError, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
@@ -443,7 +443,28 @@ export async function protectionPublishCommand(file, agentName, options = {}) {
         process.exit(1);
     }
 }
-export async function protectionValidateCommand(file) {
+// Agent-resolution regex (distinct from the trusted-sources AGENT_ID_RE above,
+// which validates card-embedded agent ids). This matches the gateway agent-id
+// shapes used by resolveAgentId so we can use a value directly without a lookup.
+const RESOLVE_AGENT_ID_RE = /^(smolt-[0-9a-f]{8}|mnm-[0-9a-f-]{36})$/;
+/**
+ * Soft agent resolution for `validate`: returns an agent id WITHOUT exiting the
+ * process. null ⇒ no agent configured / unresolvable → offline fallback.
+ */
+async function softResolveAgentId(agent) {
+    const name = agent ?? process.env.MNEMOM_AGENT;
+    if (!name)
+        return null;
+    if (RESOLVE_AGENT_ID_RE.test(name))
+        return name;
+    try {
+        return (await getAgentByName(name))?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function protectionValidateCommand(file, opts = {}) {
     const filePath = path.resolve(file);
     if (!fs.existsSync(filePath)) {
         console.log("\n" + fmt.error(`File not found: ${filePath}`) + "\n");
@@ -458,6 +479,30 @@ export async function protectionValidateCommand(file) {
         console.log("\n" + fmt.error(`Could not parse file: ${msg}`) + "\n");
         process.exit(1);
     }
+    // Prefer server-authoritative validation when online + an agent is available;
+    // fall back to the local validator on 401/network. `--offline` forces local. (#9)
+    if (!opts.offline) {
+        const agentId = await softResolveAgentId(opts.agent);
+        if (agentId) {
+            const contentType = parsed.format === "yaml" ? "text/yaml" : "application/json";
+            try {
+                const result = await previewComposeAgentCard(agentId, "protection", parsed.raw, contentType);
+                renderServerProtectionValidation(result, filePath, parsed.format);
+                return;
+            }
+            catch (err) {
+                if (err instanceof MnemomApiError && err.status !== 401) {
+                    console.log("\n" + fmt.error(`Server validation failed: ${err.message}`) + "\n");
+                    process.exit(1);
+                }
+                process.stderr.write(fmt.warn("offline validation — server rules may differ") + "\n");
+            }
+        }
+        else if (!opts.agent && !process.env.MNEMOM_AGENT) {
+            process.stderr.write(fmt.dim("tip: pass --agent <name> to validate against the server (org/platform floor)") +
+                "\n");
+        }
+    }
     const checks = validateProtectionCard(parsed.parsed);
     const allPassed = checks.every((c) => c.passed);
     const passCount = checks.filter((c) => c.passed).length;
@@ -484,6 +529,33 @@ export async function protectionValidateCommand(file) {
         process.exit(1);
     }
 }
+/** Render a server-authoritative preview-compose result; exit 1 if invalid. */
+function renderServerProtectionValidation(result, filePath, format) {
+    console.log(fmt.header("Protection Card Validation (server-authoritative)"));
+    console.log();
+    console.log(fmt.label("  File:", ` ${filePath}`));
+    console.log(fmt.label("  Format:", ` ${format.toUpperCase()}`));
+    console.log();
+    if (result.valid) {
+        console.log(fmt.success("Server accepted and composed the card."));
+        const conflicts = result.conflicts ?? [];
+        if (conflicts.length > 0) {
+            console.log(fmt.warn(`${conflicts.length} field(s) tightened by the org/platform floor:`));
+            console.log(fmt.json(conflicts));
+        }
+        console.log();
+        return;
+    }
+    console.log(fmt.error(`Server rejected the card${result.error?.code ? ` (${result.error.code})` : ""}:`));
+    if (result.error?.message)
+        console.log(`  ${result.error.message}`);
+    if (result.error?.details !== undefined) {
+        console.log();
+        console.log(fmt.json(result.error.details));
+    }
+    console.log();
+    process.exit(1);
+}
 export async function protectionEditCommand(agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     await requireAuth();

package/dist/commands/recipes.js

@@ -23,7 +23,7 @@
  *     filed" anchor and the candidate_id is the primary track-handle.
  */
 import chalk from "chalk";
-import { reportRecipeFnFp, } from "../lib/api.js";
+import { reportRecipeFnFp } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 async function readSummary(opts) {
     if (typeof opts.summary === "string" && opts.summary.trim()) {
@@ -42,7 +42,7 @@ async function readSummary(opts) {
         if (piped)
             return piped;
     }
-    throw new Error("summary required: pass --summary \"…\" or pipe text on stdin.");
+    throw new Error('summary required: pass --summary "…" or pipe text on stdin.');
 }
 async function runReport(recipeId, type, opts) {
     await requireAuth();

package/dist/commands/status.js

@@ -1,5 +1,5 @@
 import { getGatewayUrl } from "../lib/config.js";
-import { resolveAgentId, getAgent, getIntegrity, getTraces } from "../lib/api.js";
+import { resolveAgentId, getAgent, getIntegrity, getTraces, MnemomApiError } from "../lib/api.js";
 import { isLoggedIn, getAuthInfo } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 const DASHBOARD_URL = "https://mnemom.ai";
@@ -133,8 +133,10 @@ async function checkApiConnectivity(agentId) {
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
+        // 404 = agent not registered yet. Branch on effectiveStatus (enforce hook may
+        // rewrite an undocumented 404 → synthetic 500 + spec_deviation.original_status;
+        // effectiveStatus === status when documented). getAgent → fetchApi → MnemomApiError.
+        if (error instanceof MnemomApiError && error.effectiveStatus === 404) {
             return {
                 name: "API",
                 status: "warning",
@@ -142,7 +144,13 @@ async function checkApiConnectivity(agentId) {
                 details: "Will register on first traced API call",
             };
         }
-        if (message.includes("timeout") || message.includes("TIMEOUT")) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Transport-level timeout (no HTTP status, not an envelope error) — detect by
+        // the AbortSignal.timeout error name, with a message fallback for runtimes that
+        // don't set it.
+        if ((error instanceof Error && error.name === "TimeoutError") ||
+            message.includes("timeout") ||
+            message.includes("TIMEOUT")) {
             return {
                 name: "API",
                 status: "error",