@mnemom/mnemom 0.16.2 → 0.16.3

package/dist/lib/api.js

@@ -1,7 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { getApiUrl } from "./config.js";
 import { forceRefreshAccessToken, resolveAuth } from "./auth.js";
+import { mnemomFetch } from "./version-gate.js";
 export const API_BASE = getApiUrl();
+const NOT_AUTHENTICATED_MSG = "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.";
 /** Sanitize file-sourced data before use in outbound HTTP requests. */
 function sanitizeForHttp(data) {
     return String(data).trim();
@@ -112,7 +114,7 @@ export async function readApiError(response, fallback) {
 }
 async function fetchApi(endpoint) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
-    const response = await fetch(url);
+    const response = await mnemomFetch(url);
     if (!response.ok) {
         throw await readApiError(response, "API request failed");
     }
@@ -120,18 +122,12 @@ async function fetchApi(endpoint) {
 }
 export async function postApi(endpoint, body, opts = {}) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
-    const cred = await resolveAuth();
     const headers = {
         "Content-Type": "application/json",
         "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
+        ...(await authHeaders()),
     };
-    if (cred.type === "jwt") {
-        headers["Authorization"] = `Bearer ${cred.token}`;
-    }
-    else if (cred.type === "api-key") {
-        headers["X-Mnemom-Api-Key"] = cred.key;
-    }
-    const response = await fetch(url, {
+    const response = await mnemomFetch(url, {
         // lgtm[js/file-data-url]
         method: "POST",
         headers,
@@ -193,13 +189,13 @@ async function authHeaders() {
  * server-side reservation by design.
  */
 async function fetchWithAuthRetry(url, buildInit) {
-    const first = await fetch(url, await buildInit());
+    const first = await mnemomFetch(url, await buildInit());
     if (first.status !== 401)
         return first;
     const refreshed = await forceRefreshAccessToken();
     if (!refreshed)
         return first;
-    return fetch(url, await buildInit());
+    return mnemomFetch(url, await buildInit());
 }
 export async function getAgent(id) {
     return fetchApi(`/v1/agents/${id}`);
@@ -212,17 +208,7 @@ export async function getAgent(id) {
  * routing here avoids the false "Not authenticated" error (MNE-194 F10).
  */
 export async function listAgents() {
-    const url = validateUrl(`${API_BASE}/v1/agents?limit=100`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        headers: await authHeaders(),
-    }));
-    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 agents");
-    }
-    const data = (await response.json());
+    const data = await gFetch("/v1/agents?limit=100", {}, { fallback: "Failed to list agents" });
     return data.agents ?? [];
 }
 /**
@@ -231,17 +217,7 @@ export async function listAgents() {
  * first; multi-user orgs follow.
  */
 export async function listMyOrgs() {
-    const url = validateUrl(`${API_BASE}/v1/orgs`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        headers: await authHeaders(),
-    }));
-    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, "API request failed");
-    }
-    const data = (await response.json());
+    const data = await gFetch("/v1/orgs", {}, { fallback: "API request failed" });
     return data.orgs ?? [];
 }
 /**
@@ -249,17 +225,7 @@ export async function listMyOrgs() {
  * 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());
+    const data = await gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/agents`, {}, { fallback: "Failed to list org agents" });
     return data.agents ?? [];
 }
 function fleetToRow(a, org) {
@@ -351,7 +317,7 @@ export async function claimAgent(agentId, body, opts = {}) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         throw await readApiError(response, "Failed to claim agent");
     }
@@ -366,22 +332,48 @@ export async function claimAgent(agentId, body, opts = {}) {
     };
 }
 /**
- * GET /v1/auth/me/personal-org — accessor for the user's personal org.
- * Idempotent: lazily provisions for legacy accounts that pre-date the
- * mnemom-api migration 161 backfill.
+ * POST /v1/agents/:id/move — role-based relocation between orgs.
+ *
+ * The role-based counterpart to claimAgent's re-claim: the server requires
+ * the caller to be an owner/admin of BOTH the agent's current org and
+ * `destOrgId` — no hash proof / agent key involved. Moving to the current
+ * org is an idempotent no-op (`moved: false`). An Idempotency-Key is minted
+ * (held across the 401-refresh retry) like every mutation.
  */
-export async function getMyPersonalOrg() {
-    const url = validateUrl(`${API_BASE}/v1/auth/me/personal-org`);
+export async function moveAgent(agentId, destOrgId, opts = {}) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${encodeURIComponent(agentId)}/move`);
+    const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();
     const response = await fetchWithAuthRetry(url, async () => ({
-        headers: await authHeaders(),
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": idempotencyKey,
+        },
+        body: JSON.stringify({ dest_org_id: sanitizeForHttp(destOrgId) }),
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
-        throw await readApiError(response, "API request failed");
+        throw await readApiError(response, "Failed to move agent");
     }
-    return (await response.json());
+    const data = (await response.json());
+    return {
+        moved: data.moved ?? true,
+        agent_id: data.agent_id ?? agentId,
+        from_org_id: data.from_org_id ?? null,
+        to_org_id: data.to_org_id ?? null,
+    };
+}
+/**
+ * GET /v1/auth/me/personal-org — accessor for the user's personal org.
+ * Idempotent: lazily provisions for legacy accounts that pre-date the
+ * mnemom-api migration 161 backfill.
+ */
+export async function getMyPersonalOrg() {
+    return gFetch("/v1/auth/me/personal-org", {}, { fallback: "API request failed" });
 }
 /**
  * GET /v1/orgs/:org_id/teams for every org the user is a member of,
@@ -421,7 +413,7 @@ export async function getTeam(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 404) {
             throw new MnemomApiError(404, `Team '${teamId}' not found or not accessible.`);
@@ -443,7 +435,7 @@ export async function getTeamTemplate(teamId, kind) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: not a member of team '${teamId}'s org.`);
@@ -479,7 +471,7 @@ export async function putTeamTemplate(teamId, kind, yamlBody) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: org admin or owner role required to write a team template.`);
@@ -512,7 +504,7 @@ export async function deleteTeamTemplate(teamId, kind) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: org admin or owner role required to clear a team template.`);
@@ -570,7 +562,7 @@ export async function grantTeamAdmin(teamId, userId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: org owner or admin role required, and target user must be in the team's org.`);
@@ -602,7 +594,7 @@ export async function revokeTeamAdmin(teamId, userId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: revoke requires org owner/admin, or self-revoke with an active grant.`);
@@ -625,7 +617,7 @@ export async function listTeamAdmins(teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: requires membership in the team's org.`);
@@ -672,17 +664,10 @@ export async function getAgentByName(name) {
  * path from PR #200 so a stale local expiresAt heals transparently.
  */
 export async function getIntegrity(id) {
-    const url = validateUrl(`${API_BASE}/v1/integrity/${id}`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        headers: await authHeaders(),
-    }));
-    if (!response.ok) {
-        throw await readApiError(response, "API request failed");
-    }
+    const body = await gFetch(`/v1/integrity/${id}`, {}, { fallback: "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
     // the RPC path; flagged for a follow-up API normalization.
-    const body = (await response.json());
     const row = Array.isArray(body) ? (body[0] ?? emptyIntegrityRow(id)) : body;
     // Fill in agent_id when the API didn't (RPC path) so the field is always
     // populated for consumers regardless of which API path served the request.
@@ -714,14 +699,7 @@ function emptyIntegrityRow(agentId) {
  * don't need a special case for it.
  */
 export async function getTraces(id, limit = 10) {
-    const url = validateUrl(`${API_BASE}/v1/traces?agent_id=${id}&limit=${limit}`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        headers: await authHeaders(),
-    }));
-    if (!response.ok) {
-        throw await readApiError(response, "API request failed");
-    }
-    const data = (await response.json());
+    const data = await gFetch(`/v1/traces?agent_id=${id}&limit=${limit}`, {}, { fallback: "API request failed" });
     // Accept both the envelope shape (current API) and a bare array (defensive
     // — staging is mid-deploy when a CLI smoke runs against an older API).
     if (Array.isArray(data))
@@ -741,7 +719,7 @@ export async function getAlignmentCard(agentId, format = "yaml") {
     // 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, {
+    const response = await mnemomFetch(url, {
         headers: { Accept: accept, ...(await authHeaders()) },
     });
     if (!response.ok) {
@@ -801,7 +779,7 @@ export async function getProtectionCard(agentId, format = "yaml") {
     // 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, {
+    const response = await mnemomFetch(url, {
         headers: { Accept: accept, ...(await authHeaders()) },
     });
     if (!response.ok) {
@@ -869,7 +847,7 @@ export async function previewComposeAgentCard(agentId, kind, body, contentType =
     }
     // 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.");
+        throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
     }
     // 400 / 422 → the card is invalid: an expected validation outcome, not an
     // exception. Surface the care-framed findings structurally.
@@ -917,7 +895,7 @@ export async function resolveAgentId(agentName) {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.includes("Not authenticated")) {
-            console.error(`\nNot authenticated. Run \`mnemom login\` or set MNEMOM_API_KEY.\n`);
+            console.error(`\n${NOT_AUTHENTICATED_MSG}\n`);
             process.exit(1);
         }
     }
@@ -945,7 +923,7 @@ export async function listPostures(opts) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: not a member of org '${opts.orgId}'.`);
@@ -963,7 +941,7 @@ export async function getPosture(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 404)
             throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
@@ -975,18 +953,7 @@ export async function getPosture(postureId) {
 }
 /** GET /v1/postures/:id/revisions — list revisions, newest first. */
 export async function listPostureRevisions(postureId) {
-    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}/revisions`);
-    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.");
-        if (response.status === 404)
-            throw new MnemomApiError(404, `Posture '${postureId}' not found.`);
-        throw await readApiError(response, "API request failed");
-    }
-    const data = (await response.json());
+    const data = await gFetch(`/v1/postures/${postureId}/revisions`, {}, { notFoundLabel: `Posture '${postureId}'`, fallback: "API request failed" });
     return data.revisions ?? [];
 }
 /** GET /v1/postures/:id/diff?from=N&to=M — structural diff. */
@@ -997,7 +964,7 @@ export async function diffPostureRevisions(postureId, fromNo, toNo) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 404) {
             const errBody = await parseApiErrorBody(response);
             throw new MnemomApiError(404, errBody.message || `Posture or revision not found.`, {
@@ -1025,7 +992,7 @@ export async function createPosture(input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: org owner/admin role required (or scope=platform reserved for migrations).`);
         }
@@ -1052,7 +1019,7 @@ export async function updatePosture(postureId, input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403) {
             throw new MnemomApiError(403, `Forbidden: org owner/admin required, or this is a Mnemom-shipped platform default (immutable — clone first).`);
         }
@@ -1079,7 +1046,7 @@ export async function clonePosture(postureId, input) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403)
             throw new MnemomApiError(403, `Forbidden: org owner/admin required on target org.`);
         if (response.status === 404)
@@ -1103,7 +1070,7 @@ export async function deletePosture(postureId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403)
             throw new MnemomApiError(403, `Forbidden: platform defaults are immutable.`);
         if (response.status === 404)
@@ -1129,7 +1096,7 @@ export async function assignPosture(postureId, teamId, pinRevisionNo) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403)
             throw new MnemomApiError(403, `Forbidden: org owner/admin required on team's org.`);
         if (response.status === 404) {
@@ -1153,7 +1120,7 @@ export async function unassignPosture(postureId, teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403)
             throw new MnemomApiError(403, `Forbidden: org owner/admin required.`);
         if (response.status === 404) {
@@ -1176,7 +1143,7 @@ export async function previewComposePosture(postureId, teamId) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 404) {
             const errBody = await parseApiErrorBody(response);
             throw new MnemomApiError(404, errBody.message || `Posture or team not found.`, {
@@ -1202,21 +1169,7 @@ export async function listSidebandAdvisoriesForAgent(agentId, opts = {}) {
     if (opts.since)
         params.set("since", opts.since);
     const qs = params.toString() ? `?${params.toString()}` : "";
-    const url = validateUrl(`${API_BASE}/v1/agents/${encodeURIComponent(agentId)}/sideband-advisories${qs}`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        method: "GET",
-        headers: { ...(await authHeaders()), Accept: "application/json" },
-    }));
-    if (!response.ok) {
-        if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
-        if (response.status === 403)
-            throw new MnemomApiError(403, "Permission denied (need org membership).");
-        if (response.status === 404)
-            throw new MnemomApiError(404, `Agent '${agentId}' not found.`);
-        throw await readApiError(response, "List advisories failed");
-    }
-    return (await response.json());
+    return gFetch(`/v1/agents/${encodeURIComponent(agentId)}/sideband-advisories${qs}`, {}, { notFoundLabel: `Agent '${agentId}'`, fallback: "List advisories failed" });
 }
 /**
  * GET /v1/teams/:id/sideband-advisories
@@ -1231,21 +1184,7 @@ export async function listSidebandAdvisoriesForTeam(teamId, opts = {}) {
     if (opts.since)
         params.set("since", opts.since);
     const qs = params.toString() ? `?${params.toString()}` : "";
-    const url = validateUrl(`${API_BASE}/v1/teams/${encodeURIComponent(teamId)}/sideband-advisories${qs}`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        method: "GET",
-        headers: { ...(await authHeaders()), Accept: "application/json" },
-    }));
-    if (!response.ok) {
-        if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
-        if (response.status === 403)
-            throw new MnemomApiError(403, "Permission denied (need org membership).");
-        if (response.status === 404)
-            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
-        throw await readApiError(response, "List advisories failed");
-    }
-    return (await response.json());
+    return gFetch(`/v1/teams/${encodeURIComponent(teamId)}/sideband-advisories${qs}`, {}, { notFoundLabel: `Team '${teamId}'`, fallback: "List advisories failed" });
 }
 /**
  * GET /v1/teams/:id/sideband-coverage
@@ -1255,21 +1194,7 @@ export async function listSidebandAdvisoriesForTeam(teamId, opts = {}) {
  * raw rows.
  */
 export async function getTeamSidebandCoverage(teamId) {
-    const url = validateUrl(`${API_BASE}/v1/teams/${encodeURIComponent(teamId)}/sideband-coverage`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        method: "GET",
-        headers: { ...(await authHeaders()), Accept: "application/json" },
-    }));
-    if (!response.ok) {
-        if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
-        if (response.status === 403)
-            throw new MnemomApiError(403, "Permission denied (need org membership).");
-        if (response.status === 404)
-            throw new MnemomApiError(404, `Team '${teamId}' not found.`);
-        throw await readApiError(response, "Coverage fetch failed");
-    }
-    return (await response.json());
+    return gFetch(`/v1/teams/${encodeURIComponent(teamId)}/sideband-coverage`, {}, { notFoundLabel: `Team '${teamId}'`, fallback: "Coverage fetch failed" });
 }
 /**
  * GET /v1/admin/safe-house/harness-state — fetch the most recent
@@ -1284,7 +1209,7 @@ export async function getSafeHouseHarnessState() {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login`.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403)
             throw new MnemomApiError(403, "Permission denied — `mnemom validate safe-house` is mnemom-staff only.");
         throw await readApiError(response, "Harness state fetch failed");
@@ -1310,7 +1235,7 @@ function buildSignalListQuery(opts = {}) {
     const qs = params.toString();
     return qs ? `?${qs}` : "";
 }
-async function gFetch(path, init = {}, notFoundLabel) {
+async function gFetch(path, init = {}, opts = {}) {
     const url = validateUrl(`${API_BASE}${path}`);
     const response = await fetchWithAuthRetry(url, async () => ({
         method: init.method ?? "GET",
@@ -1324,56 +1249,56 @@ async function gFetch(path, init = {}, notFoundLabel) {
     }));
     if (!response.ok) {
         if (response.status === 401)
-            throw new MnemomApiError(401, "Not authenticated.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         if (response.status === 403)
             throw new MnemomApiError(403, "Permission denied (need org admin / membership).");
-        if (response.status === 404 && notFoundLabel)
-            throw new MnemomApiError(404, `${notFoundLabel} not found.`);
-        throw await readApiError(response, "Request failed");
+        if (response.status === 404 && opts.notFoundLabel)
+            throw new MnemomApiError(404, `${opts.notFoundLabel} not found.`);
+        throw await readApiError(response, opts.fallback ?? "Request failed");
     }
     return (await response.json());
 }
 export async function listGovernanceSignalsForOrg(orgId, opts = {}) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Org");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/signals${buildSignalListQuery(opts)}`, {}, { notFoundLabel: "Org" });
 }
 export async function listGovernanceSignalsForTeam(teamId, opts = {}) {
-    return gFetch(`/v1/teams/${encodeURIComponent(teamId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Team");
+    return gFetch(`/v1/teams/${encodeURIComponent(teamId)}/governance/signals${buildSignalListQuery(opts)}`, {}, { notFoundLabel: "Team" });
 }
 export async function listGovernanceSignalsForAgent(agentId, opts = {}) {
-    return gFetch(`/v1/agents/${encodeURIComponent(agentId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Agent");
+    return gFetch(`/v1/agents/${encodeURIComponent(agentId)}/governance/signals${buildSignalListQuery(opts)}`, {}, { notFoundLabel: "Agent" });
 }
 export async function getGovernanceSignal(id) {
-    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}`, {}, "Signal");
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}`, {}, { notFoundLabel: "Signal" });
 }
 export async function acknowledgeGovernanceSignal(id, body = {}) {
-    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/acknowledge`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/acknowledge`, { method: "POST", body: JSON.stringify(body) }, { notFoundLabel: "Signal" });
 }
 export async function resolveGovernanceSignal(id, body) {
-    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/resolve`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/resolve`, { method: "POST", body: JSON.stringify(body) }, { notFoundLabel: "Signal" });
 }
 export async function dismissGovernanceSignal(id, body = {}) {
-    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/dismiss`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/dismiss`, { method: "POST", body: JSON.stringify(body) }, { notFoundLabel: "Signal" });
 }
 export async function listGovernanceDestinations(orgId) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, {}, "Org");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, {}, { notFoundLabel: "Org" });
 }
 export async function createGovernanceDestination(orgId, body) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, { method: "POST", body: JSON.stringify(body) }, "Org");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, { method: "POST", body: JSON.stringify(body) }, { notFoundLabel: "Org" });
 }
 export async function deleteGovernanceDestination(orgId, destinationId) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}`, { method: "DELETE" }, "Destination");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}`, { method: "DELETE" }, { notFoundLabel: "Destination" });
 }
 export async function testGovernanceDestination(orgId, destinationId) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}/test`, { method: "POST", body: JSON.stringify({}) }, "Destination");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}/test`, { method: "POST", body: JSON.stringify({}) }, { notFoundLabel: "Destination" });
 }
 export async function listGovernanceRules(orgId) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, {}, "Org");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, {}, { notFoundLabel: "Org" });
 }
 export async function createGovernanceRule(orgId, body) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, { method: "POST", body: JSON.stringify(body) }, "Org");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, { method: "POST", body: JSON.stringify(body) }, { notFoundLabel: "Org" });
 }
 export async function deleteGovernanceRule(orgId, ruleId) {
-    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules/${encodeURIComponent(ruleId)}`, { method: "DELETE" }, "Rule");
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules/${encodeURIComponent(ruleId)}`, { method: "DELETE" }, { notFoundLabel: "Rule" });
 }
 // ─── api-keys (ADR-049) ─────────────────────────────────────────────────
 /**
@@ -1408,17 +1333,7 @@ export function isLegacyScopeSet(scopes) {
  * GET /v1/api-keys — list the caller's active personal API keys.
  */
 export async function listApiKeys() {
-    const url = validateUrl(`${API_BASE}/v1/api-keys`);
-    const response = await fetchWithAuthRetry(url, async () => ({
-        headers: await authHeaders(),
-    }));
-    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 api keys");
-    }
-    const data = (await response.json());
+    const data = await gFetch("/v1/api-keys", {}, { fallback: "Failed to list api keys" });
     return data.keys ?? [];
 }
 /**
@@ -1437,7 +1352,7 @@ export async function createApiKey(name, scopes) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         const parsed = await parseApiErrorBody(response);
         const detail = parsed.message || `HTTP ${response.status}`;
@@ -1465,7 +1380,7 @@ export async function rotateApiKey(keyId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 404)
             throw new MnemomApiError(404, `Key not found: ${keyId}`);
@@ -1486,7 +1401,7 @@ export async function revokeApiKey(keyId) {
     }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
         }
         if (response.status === 404)
             throw new MnemomApiError(404, `Key not found: ${keyId}`);
@@ -1514,7 +1429,7 @@ export async function revokeApiKey(keyId) {
  */
 export async function validateLicense(jwt, instanceId, instanceMetadata = {}) {
     const url = validateUrl(`${API_BASE}/v1/license/validate`);
-    const response = await fetch(url, {
+    const response = await mnemomFetch(url, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -1531,3 +1446,33 @@ export async function validateLicense(jwt, instanceId, instanceMetadata = {}) {
 export async function reportRecipeFnFp(recipeId, input) {
     return postApi(`/v1/recipes/${encodeURIComponent(recipeId)}/report`, input);
 }
+/** The only windows the endpoint accepts (`days` enum in `openapi.json`). */
+export const USAGE_ALLOWED_DAYS = [7, 30, 90];
+/**
+ * GET /v1/orgs/:org_id/usage/by-person — consumption by person/provider/model.
+ *
+ * Role-gated to owner/admin/auditor; member and viewer get a real 403.
+ *
+ * Gated by USAGE_ATTRIBUTION_API_ENABLED, which returns **404, not 403**, when
+ * off — deliberately, so a disabled endpoint is indistinguishable from one that
+ * does not exist. That makes 404 ambiguous by design (flag off OR unknown org
+ * OR no access), so no `notFoundLabel` is passed here: a caller must not tell
+ * the user "org not found" on what is most often just the flag being off.
+ */
+export async function getOrgUsage(orgId, opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.days !== undefined)
+        params.set("days", String(opts.days));
+    if (opts.personId)
+        params.set("person_id", opts.personId);
+    if (opts.provider)
+        params.set("provider", opts.provider);
+    if (opts.model)
+        params.set("model", opts.model);
+    if (opts.limit !== undefined)
+        params.set("limit", String(opts.limit));
+    if (opts.cursor)
+        params.set("cursor", opts.cursor);
+    const qs = params.toString() ? `?${params.toString()}` : "";
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/usage/by-person${qs}`, {}, { fallback: "Failed to fetch usage" });
+}