@mnemom/mnemom 0.12.1 → 0.14.0

package/dist/lib/api.js

@@ -26,15 +26,95 @@ function validateUrl(url) {
 export function newIdempotencyKey() {
     return randomUUID();
 }
+/**
+ * Extract the human message + code + details from a raw error body,
+ * tolerating all three live envelope shapes (prefer nested).
+ */
+export function normalizeApiError(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    let message;
+    let code;
+    let details;
+    const e = raw.error;
+    if (e && typeof e === "object") {
+        // Nested {error:{code,message,details}} (enforce-hook).
+        message = typeof e.message === "string" ? e.message : undefined;
+        code = typeof e.code === "string" ? e.code : undefined;
+        details = e.details;
+    }
+    else if (typeof e === "string") {
+        // Flat {error:"message"} (+ optional top-level code on auth routes).
+        message = e;
+    }
+    // Fallbacks: top-level message/code/details when the above didn't populate.
+    if (!message && typeof raw.message === "string")
+        message = raw.message;
+    if (!code && typeof raw.code === "string")
+        code = raw.code;
+    if (details === undefined)
+        details = raw.details;
+    const spec_deviation = raw.spec_deviation && typeof raw.spec_deviation === "object" ? raw.spec_deviation : undefined;
+    return { message, code, details, conflict_agent_id: raw.conflict_agent_id, spec_deviation };
+}
+/** Parse a non-OK Response body into normalized error fields (never throws). */
+export async function parseApiErrorBody(response) {
+    const raw = (await response.json().catch(() => null));
+    return normalizeApiError(raw);
+}
+/**
+ * Structured API error. `message` is the human-readable server message (or a
+ * fallback); `.status`/`.code`/`.details`/`.conflictAgentId` give callers a
+ * structured surface to branch on without parsing the message string.
+ * `instanceof MnemomApiError` narrows in command-layer catch blocks.
+ */
+export class MnemomApiError extends Error {
+    /** The wire HTTP status — may be a synthetic 500 from the enforce hook. */
+    status;
+    /**
+     * The TRUE intended status: `spec_deviation.original_status ?? status`. The
+     * enforce hook can rewrite an undocumented status to a synthetic 500; command
+     * layers MUST branch on `effectiveStatus` (not `status`) for 404/empty-state
+     * detection or they'll be fooled by the rewrite.
+     */
+    effectiveStatus;
+    code;
+    details;
+    conflictAgentId;
+    /** Top-level enforce-hook sibling (present only on a spec-rewritten body). */
+    specDeviation;
+    constructor(status, message, opts = {}) {
+        super(message);
+        this.name = "MnemomApiError";
+        this.status = status;
+        this.code = opts.code;
+        this.details = opts.details;
+        this.conflictAgentId = opts.conflictAgentId;
+        this.specDeviation = opts.specDeviation;
+        this.effectiveStatus = opts.specDeviation?.original_status ?? status;
+    }
+}
+/**
+ * Read a non-OK Response into a MnemomApiError, preferring the server message
+ * and falling back to `${fallback}: ${status}` when the body carried none.
+ * Captures the enforce-hook `spec_deviation` sibling so `.effectiveStatus`
+ * reflects the true intended status behind any synthetic-500 rewrite.
+ */
+export async function readApiError(response, fallback) {
+    const parsed = await parseApiErrorBody(response);
+    const message = parsed.message || `${fallback}: ${response.status}`;
+    return new MnemomApiError(response.status, message, {
+        code: parsed.code,
+        details: parsed.details,
+        conflictAgentId: parsed.conflict_agent_id,
+        specDeviation: parsed.spec_deviation,
+    });
+}
 async function fetchApi(endpoint) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
     const response = await fetch(url);
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return response.json();
 }
@@ -58,16 +138,22 @@ export async function postApi(endpoint, body, opts = {}) {
         body: JSON.stringify(body),
     });
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: `HTTP ${response.status}`,
-        })));
-        const msg = "message" in error ? error.message : JSON.stringify(error);
-        // Preserve conflict_agent_id in the error message for 409 handling upstream
-        if (response.status === 409 && "conflict_agent_id" in error) {
-            throw new Error(`409: ${msg} (conflict: ${error.conflict_agent_id})`);
+        const parsed = await parseApiErrorBody(response);
+        const msg = parsed.message || `HTTP ${response.status}`;
+        // Preserve the 409 conflict_agent_id surface: carry it structurally on the
+        // error (.conflictAgentId) AND keep it in the message for back-compat with
+        // any callers still string-matching the old "409: ... (conflict: ...)" form.
+        if (response.status === 409 && parsed.conflict_agent_id) {
+            throw new MnemomApiError(409, `409: ${msg} (conflict: ${parsed.conflict_agent_id})`, {
+                code: parsed.code,
+                details: parsed.details,
+                conflictAgentId: parsed.conflict_agent_id,
+            });
         }
-        throw new Error(`${response.status}: ${msg}`);
+        throw new MnemomApiError(response.status, `${response.status}: ${msg}`, {
+            code: parsed.code,
+            details: parsed.details,
+        });
     }
     return response.json();
 }
@@ -119,6 +205,13 @@ async function fetchWithAuthRetry(url, buildInit) {
 export async function getAgent(id) {
     return fetchApi(`/v1/agents/${id}`);
 }
+/**
+ * @deprecated Legacy per-user listing — `GET /v1/agents` is scoped by the
+ * caller's `claimed_by` rows, which ADR-062 retired as an authorization /
+ * listing boundary (org_id is now the sole boundary). New code must list via
+ * {@link listOrgAgents} (org-scoped). Retained only for back-compat callers;
+ * the `mnemom agents` command and name resolution no longer use it.
+ */
 export async function listAgents() {
     const url = validateUrl(`${API_BASE}/v1/agents?limit=100`);
     const response = await fetchWithAuthRetry(url, async () => ({
@@ -126,10 +219,9 @@ export async function listAgents() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Failed to list agents: ${response.status}`);
+        throw await readApiError(response, "Failed to list agents");
     }
     const data = (await response.json());
     return data.agents ?? [];
@@ -146,14 +238,134 @@ export async function listMyOrgs() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     return data.orgs ?? [];
 }
+/**
+ * GET /v1/orgs/:org_id/agents — the org-scoped agent fleet (ADR-062). Any
+ * member of the org may read it; non-members get 403.
+ */
+export async function fetchOrgFleet(orgId) {
+    const url = validateUrl(`${API_BASE}/v1/orgs/${encodeURIComponent(orgId)}/agents`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        throw await readApiError(response, "Failed to list org agents");
+    }
+    const data = (await response.json());
+    return data.agents ?? [];
+}
+function fleetToRow(a, org) {
+    return {
+        id: a.agent_id,
+        name: a.agent_name ?? null,
+        email: a.owner_email ?? null,
+        created_at: a.created_at,
+        last_seen: a.last_seen ?? null,
+        containment_status: a.containment_status ?? null,
+        org_id: org.org_id,
+        org_name: org.name,
+    };
+}
+/**
+ * List agents the ADR-062 way: scoped by org membership, never by `claimed_by`.
+ *
+ * - With `orgId`: lists that single org's fleet.
+ * - Without `orgId`: aggregates the fleet across every org the caller belongs
+ *   to (the same pattern as {@link listAllTeams}), tagging each row with its
+ *   org. Orgs the caller can't read (403/404) are skipped silently so one
+ *   inaccessible org doesn't fail the whole listing.
+ */
+export async function listOrgAgents(orgId) {
+    let orgs;
+    if (orgId) {
+        // Resolve a friendly name if the caller is a member; fall back to the id.
+        const mine = await listMyOrgs().catch(() => []);
+        const match = mine.find((o) => o.org_id === orgId);
+        orgs = [{ org_id: orgId, name: match?.name ?? orgId }];
+    }
+    else {
+        orgs = (await listMyOrgs()).map((o) => ({ org_id: o.org_id, name: o.name }));
+    }
+    const rows = [];
+    const seen = new Set();
+    for (const org of orgs) {
+        let fleet;
+        try {
+            fleet = await fetchOrgFleet(org.org_id);
+        }
+        catch (err) {
+            // A specific --org that we can't read is a real error worth surfacing;
+            // a skipped org during aggregation is not.
+            if (orgId)
+                throw err;
+            continue;
+        }
+        for (const a of fleet) {
+            if (seen.has(a.agent_id))
+                continue;
+            seen.add(a.agent_id);
+            rows.push(fleetToRow(a, org));
+        }
+    }
+    return rows;
+}
+/**
+ * POST /v1/agents/:id/claim — claim an agent into an org (ADR-062).
+ *
+ * Body is `{ hash_proof, org_id? }`. `hash_proof` (the agent's full SHA-256
+ * proof) authenticates the caller as the agent's owner; the user's own auth
+ * header rides along too so the platform can validate org membership and link
+ * the principal. Omit `orgId` to land in the caller's personal org (the
+ * platform default); a supplied `orgId` is validated against the caller's
+ * memberships server-side (a non-member gets a 403 the command layer turns
+ * into a teaching error listing claimable orgs).
+ *
+ * An Idempotency-Key is minted (and held across the 401-refresh retry) so a
+ * retried claim replays the same logical operation server-side.
+ */
+export async function claimAgent(agentId, body, opts = {}) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${encodeURIComponent(agentId)}/claim`);
+    const payload = {
+        hash_proof: sanitizeForHttp(body.hashProof),
+    };
+    if (body.orgId)
+        payload.org_id = sanitizeForHttp(body.orgId);
+    const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": idempotencyKey,
+        },
+        body: JSON.stringify(payload),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        throw await readApiError(response, "Failed to claim agent");
+    }
+    const data = (await response.json());
+    return {
+        claimed: data.claimed ?? true,
+        agent_id: data.agent_id ?? agentId,
+        // Reflect what the server resolved — null (not "") when absent/unscoped,
+        // matching the locked SDK contract so the two surfaces don't drift.
+        org_id: data.org_id ?? null,
+        claimed_at: data.claimed_at ?? null,
+    };
+}
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the
@@ -166,10 +378,9 @@ export async function getMyPersonalOrg() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -211,13 +422,12 @@ export async function getTeam(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found or not accessible.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found or not accessible.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -234,16 +444,15 @@ export async function getTeamTemplate(teamId, kind) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: not a member of team '${teamId}'s org.`);
+            throw new MnemomApiError(403, `Forbidden: not a member of team '${teamId}'s org.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -271,19 +480,18 @@ export async function putTeamTemplate(teamId, kind, yamlBody) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: org admin or owner role required to write a team template.`);
+            throw new MnemomApiError(403, `Forbidden: org admin or owner role required to write a team template.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
         if (response.status === 413) {
-            throw new Error(`Template too large (server limit: 128 KiB alignment / 64 KiB protection).`);
+            throw new MnemomApiError(413, `Template too large (server limit: 128 KiB alignment / 64 KiB protection).`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -305,16 +513,15 @@ export async function deleteTeamTemplate(teamId, kind) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: org admin or owner role required to clear a team template.`);
+            throw new MnemomApiError(403, `Forbidden: org admin or owner role required to clear a team template.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -337,8 +544,7 @@ export async function previewComposeTeamTemplate(teamId, kind, yamlBody) {
         body: yamlBody,
     }));
     if (!response.ok) {
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Preview failed: ${response.status}`);
+        throw await readApiError(response, "Preview failed");
     }
     const body = (await response.json());
     return { composed: body.composed, conflicts: body.conflicts };
@@ -365,16 +571,15 @@ export async function grantTeamAdmin(teamId, userId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: org owner or admin role required, and target user must be in the team's org.`);
+            throw new MnemomApiError(403, `Forbidden: org owner or admin role required, and target user must be in the team's org.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -398,16 +603,15 @@ export async function revokeTeamAdmin(teamId, userId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: revoke requires org owner/admin, or self-revoke with an active grant.`);
+            throw new MnemomApiError(403, `Forbidden: revoke requires org owner/admin, or self-revoke with an active grant.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -422,28 +626,27 @@ export async function listTeamAdmins(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: requires membership in the team's org.`);
+            throw new MnemomApiError(403, `Forbidden: requires membership in the team's org.`);
         }
         if (response.status === 404) {
-            throw new Error(`Team '${teamId}' not found.`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
 /**
- * Look up an agent in the authenticated user's account by name.
+ * Look up an agent by name across the caller's org fleets (ADR-062-scoped via
+ * {@link listOrgAgents}, not the legacy `claimed_by` list).
  * Tries exact match first, then single partial match.
  * Throws if multiple agents partially match (ambiguous).
  * Returns null if no match found.
- * Note: capped at 100 agents by listAgents().
  */
 export async function getAgentByName(name) {
-    const agents = await listAgents();
+    const agents = await listOrgAgents();
     const lower = name.toLowerCase();
     const exact = agents.find((a) => a.name?.toLowerCase() === lower);
     if (exact)
@@ -472,11 +675,7 @@ export async function getIntegrity(id) {
         headers: await authHeaders(),
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     // Accept both the canonical docs shape (object) and the RPC-wrapped shape
     // (array of one row). The latter is what prod actually returns today on
@@ -518,11 +717,7 @@ export async function getTraces(id, limit = 10) {
         headers: await authHeaders(),
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     // Accept both the envelope shape (current API) and a bare array (defensive
@@ -531,105 +726,6 @@ export async function getTraces(id, limit = 10) {
         return data;
     return data.traces ?? [];
 }
-export async function getCard(agentId) {
-    try {
-        return await fetchApi(`/v1/agents/${agentId}/card`);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
-            return null;
-        }
-        throw error;
-    }
-}
-export async function updateCard(agentId, cardJson, opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/card`);
-    const response = await fetch(url, {
-        method: "PATCH",
-        headers: {
-            "Content-Type": "application/json",
-            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
-            ...(await authHeaders()),
-        },
-        body: sanitizeForHttp(JSON.stringify({ card_json: cardJson })),
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Card update failed: ${response.status}`);
-    }
-    return response.json();
-}
-export async function reverifyAgent(agentId, opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/reverify`);
-    const response = await fetch(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
-            ...(await authHeaders()),
-        },
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Reverify failed: ${response.status}`);
-    }
-    return response.json();
-}
-export async function getPolicy(agentId) {
-    try {
-        return await fetchApi(`/v1/agents/${agentId}/policy`);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
-            return null;
-        }
-        throw error;
-    }
-}
-export async function publishPolicy(agentId, policyJson, opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/policy`);
-    const response = await fetch(url, {
-        method: "PUT",
-        headers: {
-            "Content-Type": "application/json",
-            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
-            ...(await authHeaders()),
-        },
-        body: sanitizeForHttp(JSON.stringify({ policy_json: policyJson })),
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Policy publish failed: ${response.status}`);
-    }
-    return response.json();
-}
-export async function testPolicyHistorical(agentId, policyJson, limit = 50) {
-    const url = validateUrl(`${API_BASE}/v1/policies/evaluate/historical`);
-    const response = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
-        body: sanitizeForHttp(JSON.stringify({ agent_id: agentId, policy_json: policyJson, limit })),
-    });
-    if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Historical evaluation failed: ${response.status}`);
-    }
-    return response.json();
-}
 // ============================================================================
 // Unified Card API (UC-4+)
 // ============================================================================
@@ -639,7 +735,10 @@ export async function testPolicyHistorical(agentId, policyJson, limit = 50) {
  */
 export async function getAlignmentCard(agentId, format = "yaml") {
     const accept = format === "yaml" ? "text/yaml" : "application/json";
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/alignment-card`);
+    // Canonical Resources × Scope × Verb surface (ADR-062 / cards-as-primitive
+    // W1.2b). The legacy `/v1/agents/:id/alignment-card` only 308-redirects to
+    // this — first-party callers target canonical directly (no legacy shapes).
+    const url = validateUrl(`${API_BASE}/v1/alignment/agent/${encodeURIComponent(agentId)}`);
     const response = await fetch(url, {
         headers: { Accept: accept, ...(await authHeaders()) },
     });
@@ -647,11 +746,7 @@ export async function getAlignmentCard(agentId, format = "yaml") {
         if (response.status === 404) {
             return { body: "", contentType: "" };
         }
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to fetch alignment card: ${response.status}`);
+        throw await readApiError(response, "Failed to fetch alignment card");
     }
     const ct = response.headers.get("content-type") ?? "";
     const body = await response.text();
@@ -664,7 +759,10 @@ export const ALIGNMENT_CARD_MAX_BYTES = 128 * 1024;
  * Accepts YAML or JSON body; set contentType accordingly.
  */
 export async function putAlignmentCard(agentId, body, contentType = "text/yaml", opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/alignment-card`);
+    // Canonical Resources × Scope × Verb surface (ADR-062 / cards-as-primitive
+    // W1.2b). The legacy `/v1/agents/:id/alignment-card` only 308-redirects to
+    // this — first-party callers target canonical directly (no legacy shapes).
+    const url = validateUrl(`${API_BASE}/v1/alignment/agent/${encodeURIComponent(agentId)}`);
     // Lock in a single Idempotency-Key for this logical mutation. If the auth
     // token is stale and the first attempt returns 401, fetchWithAuthRetry
     // refreshes the token and retries — but the Idempotency-Key must be the
@@ -689,11 +787,7 @@ export async function putAlignmentCard(agentId, body, contentType = "text/yaml",
         body: sanitizedBody,
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to publish alignment card: ${response.status}`);
+        throw await readApiError(response, "Failed to publish alignment card");
     }
     return response.json();
 }
@@ -702,7 +796,9 @@ export async function putAlignmentCard(agentId, body, contentType = "text/yaml",
  */
 export async function getProtectionCard(agentId, format = "yaml") {
     const accept = format === "yaml" ? "text/yaml" : "application/json";
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/protection-card`);
+    // Canonical surface (ADR-062 / W1.2b); legacy `/v1/agents/:id/protection-card`
+    // only 308-redirects here. First-party callers use canonical directly.
+    const url = validateUrl(`${API_BASE}/v1/protection/agent/${encodeURIComponent(agentId)}`);
     const response = await fetch(url, {
         headers: { Accept: accept, ...(await authHeaders()) },
     });
@@ -710,11 +806,7 @@ export async function getProtectionCard(agentId, format = "yaml") {
         if (response.status === 404) {
             return { body: "", contentType: "" };
         }
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to fetch protection card: ${response.status}`);
+        throw await readApiError(response, "Failed to fetch protection card");
     }
     const ct = response.headers.get("content-type") ?? "";
     const body = await response.text();
@@ -726,7 +818,9 @@ export const PROTECTION_CARD_MAX_BYTES = 64 * 1024;
  * Publish (create or update) a protection card.
  */
 export async function putProtectionCard(agentId, body, contentType = "text/yaml", opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/protection-card`);
+    // Canonical surface (ADR-062 / W1.2b); legacy `/v1/agents/:id/protection-card`
+    // only 308-redirects here. First-party callers use canonical directly.
+    const url = validateUrl(`${API_BASE}/v1/protection/agent/${encodeURIComponent(agentId)}`);
     // See putAlignmentCard for why the Idempotency-Key is computed once outside
     // the retry closure.
     const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();
@@ -744,14 +838,50 @@ export async function putProtectionCard(agentId, body, contentType = "text/yaml"
         body: sanitizedBody,
     }));
     if (!response.ok) {
-        const error = (await response.json().catch(() => ({
-            error: "unknown",
-            message: response.statusText,
-        })));
-        throw new Error(error.message || `Failed to publish protection card: ${response.status}`);
+        throw await readApiError(response, "Failed to publish protection card");
     }
     return response.json();
 }
+/**
+ * Dry-run validate + compose a card body against the server's authoritative
+ * pipeline. Returns a structured result — a 422/400 validation failure is an
+ * expected `valid:false` outcome (NOT a thrown error). 401 throws (caller
+ * should fall back to offline validation); 403/5xx throw a MnemomApiError.
+ */
+export async function previewComposeAgentCard(agentId, kind, body, contentType = "text/yaml") {
+    const url = validateUrl(`${API_BASE}/v1/${kind}/agent/${encodeURIComponent(agentId)}/preview-compose`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: { ...(await authHeaders()), "Content-Type": contentType, Accept: "application/json" },
+        body: sanitizeForHttp(body),
+    }));
+    if (response.ok) {
+        const data = (await response.json());
+        return {
+            valid: true,
+            status: response.status,
+            composed: data.composed,
+            conflicts: data.conflicts ?? [],
+            coherence_violations: data.coherence_violations ?? [],
+        };
+    }
+    // 401 → unauthenticated: signal the caller to fall back to offline validation.
+    if (response.status === 401) {
+        throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+    }
+    // 400 / 422 → the card is invalid: an expected validation outcome, not an
+    // exception. Surface the care-framed findings structurally.
+    if (response.status === 400 || response.status === 422) {
+        const parsed = await parseApiErrorBody(response);
+        return {
+            valid: false,
+            status: response.status,
+            error: { code: parsed.code, message: parsed.message, details: parsed.details },
+        };
+    }
+    // 403 / 5xx → a genuine error (e.g. not the owner, server fault).
+    throw await readApiError(response, "Card validation (preview-compose) failed");
+}
 // ============================================================================
 // Agent Resolution (server-side, no local config)
 // ============================================================================
@@ -809,13 +939,12 @@ export async function listPostures(opts) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 403) {
-            throw new Error(`Forbidden: not a member of org '${opts.orgId}'.`);
+            throw new MnemomApiError(403, `Forbidden: not a member of org '${opts.orgId}'.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     return data.postures ?? [];
@@ -828,14 +957,13 @@ export async function getPosture(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
         if (response.status === 403)
-            throw new Error(`Forbidden: not visible to your account.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+            throw new MnemomApiError(403, `Forbidden: not visible to your account.`);
+        throw await readApiError(response, "API request failed");
     }
     return (await response.json());
 }
@@ -847,11 +975,10 @@ export async function listPostureRevisions(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `API request failed: ${response.status}`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
+        throw await readApiError(response, "API request failed");
     }
     const data = (await response.json());
     return data.revisions ?? [];
@@ -864,13 +991,16 @@ export async function diffPostureRevisions(postureId, fromNo, toNo) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 404) {
-            const errBody = (await response.json().catch(() => ({})));
-            throw new Error(errBody.message || `Posture or revision not found.`);
+            const errBody = await parseApiErrorBody(response);
+            throw new MnemomApiError(404, errBody.message || `Posture or revision not found.`, {
+                code: errBody.code,
+                details: errBody.details,
+                specDeviation: errBody.spec_deviation,
+            });
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Diff failed: ${response.status}`);
+        throw await readApiError(response, "Diff failed");
     }
     return (await response.json());
 }
@@ -889,16 +1019,15 @@ export async function createPosture(input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403) {
-            throw new Error(`Forbidden: org owner/admin role required (or scope=platform reserved for migrations).`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin role required (or scope=platform reserved for migrations).`);
         }
         if (response.status === 409)
-            throw new Error(`A posture with this slug already exists in the org.`);
+            throw new MnemomApiError(409, `A posture with this slug already exists in the org.`);
         if (response.status === 413)
-            throw new Error(`Posture body too large (server limit: 256 KiB).`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Create failed: ${response.status}`);
+            throw new MnemomApiError(413, `Posture body too large (server limit: 256 KiB).`);
+        throw await readApiError(response, "Create failed");
     }
     return (await response.json());
 }
@@ -917,16 +1046,15 @@ export async function updatePosture(postureId, input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403) {
-            throw new Error(`Forbidden: org owner/admin required, or this is a Mnemom-shipped platform default (immutable — clone first).`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required, or this is a Mnemom-shipped platform default (immutable — clone first).`);
         }
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
         if (response.status === 413)
-            throw new Error(`Posture body too large (server limit: 256 KiB).`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Update failed: ${response.status}`);
+            throw new MnemomApiError(413, `Posture body too large (server limit: 256 KiB).`);
+        throw await readApiError(response, "Update failed");
     }
     return (await response.json());
 }
@@ -945,15 +1073,14 @@ export async function clonePosture(postureId, input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: org owner/admin required on target org.`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required on target org.`);
         if (response.status === 404)
-            throw new Error(`Source posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Source posture '${postureId}' not found.`);
         if (response.status === 409)
-            throw new Error(`A posture with this slug already exists in the target org.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Clone failed: ${response.status}`);
+            throw new MnemomApiError(409, `A posture with this slug already exists in the target org.`);
+        throw await readApiError(response, "Clone failed");
     }
     return (await response.json());
 }
@@ -970,16 +1097,15 @@ export async function deletePosture(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: platform defaults are immutable.`);
+            throw new MnemomApiError(403, `Forbidden: platform defaults are immutable.`);
         if (response.status === 404)
-            throw new Error(`Posture '${postureId}' not found.`);
+            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
         if (response.status === 409) {
-            throw new Error(`Cannot delete a posture that is currently assigned to one or more teams. Unassign first.`);
+            throw new MnemomApiError(409, `Cannot delete a posture that is currently assigned to one or more teams. Unassign first.`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Delete failed: ${response.status}`);
+        throw await readApiError(response, "Delete failed");
     }
 }
 /** POST /v1/postures/:id/assign — assign to a team. */
@@ -997,15 +1123,14 @@ export async function assignPosture(postureId, teamId, pinRevisionNo) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: org owner/admin required on team's org.`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required on team's org.`);
         if (response.status === 404) {
-            const errBody = (await response.json().catch(() => ({})));
-            throw new Error(errBody.message || `Posture, team, or pinned revision not found.`);
+            const errBody = await parseApiErrorBody(response);
+            throw new MnemomApiError(404, errBody.message || `Posture, team, or pinned revision not found.`, { code: errBody.code, details: errBody.details, specDeviation: errBody.spec_deviation });
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Assign failed: ${response.status}`);
+        throw await readApiError(response, "Assign failed");
     }
     return (await response.json());
 }
@@ -1022,14 +1147,13 @@ export async function unassignPosture(postureId, teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error(`Forbidden: org owner/admin required.`);
+            throw new MnemomApiError(403, `Forbidden: org owner/admin required.`);
         if (response.status === 404) {
-            throw new Error(`No matching assignment to remove (posture '${postureId}' is not assigned to team '${teamId}').`);
+            throw new MnemomApiError(404, `No matching assignment to remove (posture '${postureId}' is not assigned to team '${teamId}').`);
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Unassign failed: ${response.status}`);
+        throw await readApiError(response, "Unassign failed");
     }
 }
 /** POST /v1/postures/:id/preview-compose — preview effective for a team. */
@@ -1046,13 +1170,16 @@ export async function previewComposePosture(postureId, teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 404) {
-            const errBody = (await response.json().catch(() => ({})));
-            throw new Error(errBody.message || `Posture or team not found.`);
+            const errBody = await parseApiErrorBody(response);
+            throw new MnemomApiError(404, errBody.message || `Posture or team not found.`, {
+                code: errBody.code,
+                details: errBody.details,
+                specDeviation: errBody.spec_deviation,
+            });
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Preview-compose failed: ${response.status}`);
+        throw await readApiError(response, "Preview-compose failed");
     }
     return (await response.json());
 }
@@ -1076,13 +1203,12 @@ export async function listSidebandAdvisoriesForAgent(agentId, opts = {}) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org membership).");
+            throw new MnemomApiError(403, "Permission denied (need org membership).");
         if (response.status === 404)
-            throw new Error(`Agent '${agentId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `List advisories failed: ${response.status}`);
+            throw new MnemomApiError(404, `Agent '${agentId}' not found.`);
+        throw await readApiError(response, "List advisories failed");
     }
     return (await response.json());
 }
@@ -1106,13 +1232,12 @@ export async function listSidebandAdvisoriesForTeam(teamId, opts = {}) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org membership).");
+            throw new MnemomApiError(403, "Permission denied (need org membership).");
         if (response.status === 404)
-            throw new Error(`Team '${teamId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `List advisories failed: ${response.status}`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
+        throw await readApiError(response, "List advisories failed");
     }
     return (await response.json());
 }
@@ -1131,13 +1256,12 @@ export async function getTeamSidebandCoverage(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org membership).");
+            throw new MnemomApiError(403, "Permission denied (need org membership).");
         if (response.status === 404)
-            throw new Error(`Team '${teamId}' not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Coverage fetch failed: ${response.status}`);
+            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
+        throw await readApiError(response, "Coverage fetch failed");
     }
     return (await response.json());
 }
@@ -1154,11 +1278,10 @@ export async function getSafeHouseHarnessState() {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated. Run `mnemom login`.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login`.");
         if (response.status === 403)
-            throw new Error("Permission denied — `mnemom validate safe-house` is mnemom-staff only.");
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Harness state fetch failed: ${response.status}`);
+            throw new MnemomApiError(403, "Permission denied — `mnemom validate safe-house` is mnemom-staff only.");
+        throw await readApiError(response, "Harness state fetch failed");
     }
     return (await response.json());
 }
@@ -1195,13 +1318,12 @@ async function gFetch(path, init = {}, notFoundLabel) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new Error("Not authenticated.");
+            throw new MnemomApiError(401, "Not authenticated.");
         if (response.status === 403)
-            throw new Error("Permission denied (need org admin / membership).");
+            throw new MnemomApiError(403, "Permission denied (need org admin / membership).");
         if (response.status === 404 && notFoundLabel)
-            throw new Error(`${notFoundLabel} not found.`);
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Request failed: ${response.status}`);
+            throw new MnemomApiError(404, `${notFoundLabel} not found.`);
+        throw await readApiError(response, "Request failed");
     }
     return (await response.json());
 }
@@ -1286,10 +1408,9 @@ export async function listApiKeys() {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = (await response.json().catch(() => ({ error: "unknown" })));
-        throw new Error(err.message || `Failed to list api keys: ${response.status}`);
+        throw await readApiError(response, "Failed to list api keys");
     }
     const data = (await response.json());
     return data.keys ?? [];
@@ -1310,16 +1431,17 @@ export async function createApiKey(name, scopes) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const body = await response.text().catch(() => "");
+        const parsed = await parseApiErrorBody(response);
+        const detail = parsed.message || `HTTP ${response.status}`;
         if (response.status === 403) {
-            throw new Error(`Mint-time ceiling rejected scope: ${body}`);
+            throw new MnemomApiError(403, `Mint-time ceiling rejected scope: ${detail}`);
         }
         if (response.status === 400) {
-            throw new Error(`Invalid scope(s): ${body}`);
+            throw new MnemomApiError(400, `Invalid scope(s): ${detail}`);
         }
-        throw new Error(`Failed to create api key: ${response.status} ${body}`);
+        throw new MnemomApiError(response.status, `Failed to create api key: ${response.status} ${detail}`);
     }
     return (await response.json());
 }
@@ -1337,12 +1459,12 @@ export async function rotateApiKey(keyId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404)
-            throw new Error(`Key not found: ${keyId}`);
-        const body = await response.text().catch(() => "");
-        throw new Error(`Failed to rotate api key: ${response.status} ${body}`);
+            throw new MnemomApiError(404, `Key not found: ${keyId}`);
+        const parsed = await parseApiErrorBody(response);
+        throw new MnemomApiError(response.status, `Failed to rotate api key: ${response.status} ${parsed.message ?? ""}`.trim());
     }
     return (await response.json());
 }
@@ -1358,14 +1480,48 @@ export async function revokeApiKey(keyId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         if (response.status === 404)
-            throw new Error(`Key not found: ${keyId}`);
-        const body = await response.text().catch(() => "");
-        throw new Error(`Failed to revoke api key: ${response.status} ${body}`);
+            throw new MnemomApiError(404, `Key not found: ${keyId}`);
+        const parsed = await parseApiErrorBody(response);
+        throw new MnemomApiError(response.status, `Failed to revoke api key: ${response.status} ${parsed.message ?? ""}`.trim());
     }
 }
+/**
+ * POST /v1/license/validate — validate a license JWT for an instance.
+ *
+ * UNAUTHENTICATED by design (the license JWT IS the credential; this is a
+ * pre-login path) — sends NO auth header. Source-verified at canonical ref
+ * c18491e6 (handleLicenseValidate): the request body keys are
+ * `{ license, instance_id, instance_metadata }` (NOT `jwt`) — sending `jwt`
+ * would 400 "license is required".
+ *
+ * Returns the parsed validation result on 2xx (including the grace-period
+ * `valid:false` 200 body); throws MnemomApiError on non-2xx so the command
+ * renders `.message`/`.status`. This fixes the live H1 "[object Object]" bug:
+ * the old command-layer `err.error || "unknown"` string-coerced the nested
+ * `{code,message}` object that the enforce hook puts on the wire.
+ *
+ * `license deactivate` may reuse this (best-effort, fire-and-forget) by
+ * catching the throw at the command layer.
+ */
+export async function validateLicense(jwt, instanceId, instanceMetadata = {}) {
+    const url = validateUrl(`${API_BASE}/v1/license/validate`);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            license: sanitizeForHttp(jwt),
+            instance_id: instanceId,
+            instance_metadata: instanceMetadata,
+        }),
+    });
+    if (!response.ok) {
+        throw await readApiError(response, "License validation failed");
+    }
+    return (await response.json());
+}
 export async function reportRecipeFnFp(recipeId, input) {
     return postApi(`/v1/recipes/${encodeURIComponent(recipeId)}/report`, input);
 }