@mnemom/mnemom 0.9.1 → 0.11.0

package/dist/lib/api.js

@@ -52,6 +52,7 @@ export async function postApi(endpoint, body, opts = {}) {
         headers["X-Mnemom-Api-Key"] = cred.key;
     }
     const response = await fetch(url, {
+        // lgtm[js/file-data-url]
         method: "POST",
         headers,
         body: JSON.stringify(body),
@@ -127,12 +128,313 @@ export async function listAgents() {
         if (response.status === 401) {
             throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
-        const err = await response.json().catch(() => ({ error: "unknown" }));
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
         throw new Error(err.message || `Failed to list agents: ${response.status}`);
     }
-    const data = await response.json();
+    const data = (await response.json());
     return data.agents ?? [];
 }
+/**
+ * GET /v1/orgs — list every org the user is a member of, including the
+ * personal-org-of-one (per ADR-044 Option A, GitHub model). Personal sorts
+ * 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 Error("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}`);
+    }
+    const data = (await response.json());
+    return data.orgs ?? [];
+}
+/**
+ * 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() {
+    const url = validateUrl(`${API_BASE}/v1/auth/me/personal-org`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/orgs/:org_id/teams for every org the user is a member of,
+ * concatenated. The CLI consumer that just wants "every team I can see"
+ * doesn't need to know about org boundaries; team_id is unique anyway.
+ * Returns the flat list with org_name attached for display.
+ */
+export async function listMyTeams() {
+    const orgs = await listMyOrgs();
+    const teams = [];
+    for (const org of orgs) {
+        const url = validateUrl(`${API_BASE}/v1/orgs/${org.org_id}/teams`);
+        const response = await fetchWithAuthRetry(url, async () => ({
+            headers: await authHeaders(),
+        }));
+        if (!response.ok) {
+            // Skip orgs the user can't read teams from (e.g., role doesn't permit).
+            // The list call should succeed at the member level, but tolerate edge cases.
+            continue;
+        }
+        const data = (await response.json());
+        for (const t of data.teams ?? []) {
+            teams.push({ ...t, org_id: t.org_id ?? org.org_id, org_name: org.name });
+        }
+    }
+    return teams;
+}
+/**
+ * GET /v1/teams/:team_id — fetch a single team's row. Returns the team
+ * detail including org_id (which the CLI uses to disambiguate team_id
+ * collisions across orgs in error messages).
+ */
+export async function getTeam(teamId) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        if (response.status === 404) {
+            throw new Error(`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}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/teams/:team_id/(alignment|protection)-template — read the
+ * current team-scope template + its enabled flag. Returns the wire body
+ * verbatim. Empty for teams that have no template set yet (template:
+ * null, enabled: false).
+ */
+export async function getTeamTemplate(teamId, kind) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/${kind}-template`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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.`);
+        }
+        if (response.status === 404) {
+            throw new Error(`Team '${teamId}' not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `API request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/**
+ * PUT /v1/teams/:team_id/(alignment|protection)-template — write the
+ * team-scope template. Body is YAML or JSON template content; the API
+ * accepts either via Content-Type. Idempotency-Key is required (per the
+ * idempotency-with-body-hash discipline in the API).
+ *
+ * On success returns the post-write team template body, including
+ * agents_flagged_for_recompose so the caller can surface the fan-out
+ * count to the user.
+ */
+export async function putTeamTemplate(teamId, kind, yamlBody) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/${kind}-template`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "PUT",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "text/yaml",
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+        body: yamlBody,
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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.`);
+        }
+        if (response.status === 404) {
+            throw new Error(`Team '${teamId}' not found.`);
+        }
+        if (response.status === 413) {
+            throw new Error(`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}`);
+    }
+    return (await response.json());
+}
+/**
+ * DELETE /v1/teams/:team_id/(alignment|protection)-template — clear the
+ * template. Idempotent (deleting an already-cleared template is a 200).
+ * Returns the post-delete team template body with deleted=true and the
+ * recompose fan-out count.
+ */
+export async function deleteTeamTemplate(teamId, kind) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/${kind}-template`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "DELETE",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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.`);
+        }
+        if (response.status === 404) {
+            throw new Error(`Team '${teamId}' not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `API request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/**
+ * POST /v1/teams/:team_id/(alignment|protection)-template/preview-compose
+ * — dry-run the composer with the supplied draft against the team's
+ * current org+platform context. Returns the composed canonical output
+ * plus per-field conflicts where the draft was tightened by the
+ * org/platform floor. No DB writes.
+ */
+export async function previewComposeTeamTemplate(teamId, kind, yamlBody) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/${kind}-template/preview-compose`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "text/yaml",
+            Accept: "application/json",
+        },
+        body: yamlBody,
+    }));
+    if (!response.ok) {
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Preview failed: ${response.status}`);
+    }
+    const body = (await response.json());
+    return { composed: body.composed, conflicts: body.conflicts };
+}
+/**
+ * POST /v1/teams/:team_id/admins — grant team_admin role on a team.
+ *
+ * Per ADR-046 §3: callable by org_owner / org_admin only. The target
+ * user must already be a member of the team's org; cross-org grants 403.
+ * Idempotent — re-granting an already-active grant returns 200 with
+ * `idempotent_noop: true`.
+ */
+export async function grantTeamAdmin(teamId, userId) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/admins`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+        body: JSON.stringify({ user_id: sanitizeForHttp(userId) }),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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.`);
+        }
+        if (response.status === 404) {
+            throw new Error(`Team '${teamId}' not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `API request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/**
+ * DELETE /v1/teams/:team_id/admins/:user_id — revoke a team_admin grant.
+ *
+ * Per ADR-046 §3: callable by org_owner / org_admin OR self-revoke (the
+ * team_admin revokes their own grant — the only self-mutation). Idempotent
+ * — revoking an absent or already-revoked grant returns 200 with
+ * `idempotent_noop: true` and no audit row.
+ */
+export async function revokeTeamAdmin(teamId, userId) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/admins/${userId}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "DELETE",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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.`);
+        }
+        if (response.status === 404) {
+            throw new Error(`Team '${teamId}' not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `API request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/teams/:team_id/admins — list active team_admin grants on a team.
+ * Any member of the team's org can read.
+ */
+export async function listTeamAdmins(teamId) {
+    const url = validateUrl(`${API_BASE}/v1/teams/${teamId}/admins`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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.`);
+        }
+        if (response.status === 404) {
+            throw new Error(`Team '${teamId}' not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `API request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
 /**
  * Look up an agent in the authenticated user's account by name.
  * Tries exact match first, then single partial match.
@@ -143,14 +445,14 @@ export async function listAgents() {
 export async function getAgentByName(name) {
     const agents = await listAgents();
     const lower = name.toLowerCase();
-    const exact = agents.find(a => a.name?.toLowerCase() === lower);
+    const exact = agents.find((a) => a.name?.toLowerCase() === lower);
     if (exact)
         return exact;
-    const partials = agents.filter(a => a.name?.toLowerCase().includes(lower));
+    const partials = agents.filter((a) => a.name?.toLowerCase().includes(lower));
     if (partials.length === 1)
         return partials[0];
     if (partials.length > 1) {
-        const names = partials.map(a => a.name ?? a.id).join(", ");
+        const names = partials.map((a) => a.name ?? a.id).join(", ");
         throw new Error(`Multiple agents match '${name}': ${names}. Use a more specific name.`);
     }
     return null;
@@ -491,3 +793,580 @@ export async function resolveAgentId(agentName) {
     console.error("List your agents with: mnemom agents\n");
     process.exit(1);
 }
+/** GET /v1/postures — list visible postures. */
+export async function listPostures(opts) {
+    const params = new URLSearchParams();
+    if (opts.orgId)
+        params.set("org_id", opts.orgId);
+    if (opts.includePlatform === false)
+        params.set("include_platform", "false");
+    if (opts.includeDeleted)
+        params.set("include_deleted", "true");
+    const qs = params.toString();
+    const url = validateUrl(`${API_BASE}/v1/postures${qs ? `?${qs}` : ""}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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}'.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `API request failed: ${response.status}`);
+    }
+    const data = (await response.json());
+    return data.postures ?? [];
+}
+/** GET /v1/postures/:id — read posture with current revision body. */
+export async function getPosture(postureId) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        if (response.status === 404)
+            throw new Error(`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}`);
+    }
+    return (await response.json());
+}
+/** 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 Error("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}`);
+    }
+    const data = (await response.json());
+    return data.revisions ?? [];
+}
+/** GET /v1/postures/:id/diff?from=N&to=M — structural diff. */
+export async function diffPostureRevisions(postureId, fromNo, toNo) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}/diff?from=${fromNo}&to=${toNo}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 404) {
+            const errBody = (await response.json().catch(() => ({})));
+            throw new Error(errBody.message || `Posture or revision not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Diff failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/** POST /v1/postures — create new posture (org-scope only via REST). */
+export async function createPosture(input) {
+    const url = validateUrl(`${API_BASE}/v1/postures`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+        body: JSON.stringify(input),
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403) {
+            throw new Error(`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.`);
+        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}`);
+    }
+    return (await response.json());
+}
+/** PUT /v1/postures/:id — write a new revision (forward-only). */
+export async function updatePosture(postureId, input) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "PUT",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+        body: JSON.stringify(input),
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("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).`);
+        }
+        if (response.status === 404)
+            throw new Error(`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}`);
+    }
+    return (await response.json());
+}
+/** POST /v1/postures/:id/clone — clone source to org-scope. */
+export async function clonePosture(postureId, input) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}/clone`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+        body: JSON.stringify(input),
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error(`Forbidden: org owner/admin required on target org.`);
+        if (response.status === 404)
+            throw new Error(`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}`);
+    }
+    return (await response.json());
+}
+/** DELETE /v1/postures/:id — soft-delete (refuses if assigned). */
+export async function deletePosture(postureId) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "DELETE",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error(`Forbidden: platform defaults are immutable.`);
+        if (response.status === 404)
+            throw new Error(`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.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Delete failed: ${response.status}`);
+    }
+}
+/** POST /v1/postures/:id/assign — assign to a team. */
+export async function assignPosture(postureId, teamId, pinRevisionNo) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}/assign`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+        body: JSON.stringify({ team_id: teamId, pin_revision_no: pinRevisionNo ?? null }),
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error(`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 err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Assign failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/** DELETE /v1/postures/:id/assignments/:team_id — remove an assignment. */
+export async function unassignPosture(postureId, teamId) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}/assignments/${teamId}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "DELETE",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            "Idempotency-Key": newIdempotencyKey(),
+        },
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error(`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}').`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Unassign failed: ${response.status}`);
+    }
+}
+/** POST /v1/postures/:id/preview-compose — preview effective for a team. */
+export async function previewComposePosture(postureId, teamId) {
+    const url = validateUrl(`${API_BASE}/v1/postures/${postureId}/preview-compose`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify({ team_id: teamId }),
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 404) {
+            const errBody = (await response.json().catch(() => ({})));
+            throw new Error(errBody.message || `Posture or team not found.`);
+        }
+        const err = (await response.json().catch(() => ({ error: "unknown" })));
+        throw new Error(err.message || `Preview-compose failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/agents/:id/sideband-advisories
+ *
+ * Lists pending_advisories rows where source LIKE 'sideband.%' for the
+ * given agent. Default page 50, max 200. Optional ?since=<ISO> filter.
+ */
+export async function listSidebandAdvisoriesForAgent(agentId, opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    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 Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/teams/:id/sideband-advisories
+ *
+ * Lists pending_advisories rows for any agent that is a current member of
+ * the team. Default page 100, max 500. Optional ?since=<ISO> filter.
+ */
+export async function listSidebandAdvisoriesForTeam(teamId, opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    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 Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/teams/:id/sideband-coverage
+ *
+ * Compliance-grade proof-of-coverage for a team — last 30 days of
+ * per-axis sweep aggregates + heartbeat. Returns per-axis summary +
+ * 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 Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+/**
+ * GET /v1/admin/safe-house/harness-state — fetch the most recent
+ * harness run per lane (full + fast). Powers `mnemom validate
+ * safe-house`. Admin-gated; returns 403 for non-mnemom-staff.
+ */
+export async function getSafeHouseHarnessState() {
+    const url = validateUrl(`${API_BASE}/v1/admin/safe-house/harness-state`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "GET",
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+function buildSignalListQuery(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.source)
+        params.set("source", opts.source);
+    if (opts.severity)
+        params.set("severity", opts.severity);
+    if (opts.status)
+        params.set("status", opts.status);
+    if (opts.scope)
+        params.set("scope", opts.scope);
+    if (opts.pattern_type)
+        params.set("pattern_type", opts.pattern_type);
+    if (opts.since)
+        params.set("since", opts.since);
+    if (opts.limit)
+        params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+async function gFetch(path, init = {}, notFoundLabel) {
+    const url = validateUrl(`${API_BASE}${path}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: init.method ?? "GET",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            ...(init.body ? { "Content-Type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+        },
+        body: init.body,
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new Error("Not authenticated.");
+        if (response.status === 403)
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+export async function listGovernanceSignalsForOrg(orgId, opts = {}) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Org");
+}
+export async function listGovernanceSignalsForTeam(teamId, opts = {}) {
+    return gFetch(`/v1/teams/${encodeURIComponent(teamId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Team");
+}
+export async function listGovernanceSignalsForAgent(agentId, opts = {}) {
+    return gFetch(`/v1/agents/${encodeURIComponent(agentId)}/governance/signals${buildSignalListQuery(opts)}`, {}, "Agent");
+}
+export async function getGovernanceSignal(id) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}`, {}, "Signal");
+}
+export async function acknowledgeGovernanceSignal(id, body = {}) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/acknowledge`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+}
+export async function resolveGovernanceSignal(id, body) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/resolve`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+}
+export async function dismissGovernanceSignal(id, body = {}) {
+    return gFetch(`/v1/governance/signals/${encodeURIComponent(id)}/dismiss`, { method: "POST", body: JSON.stringify(body) }, "Signal");
+}
+export async function listGovernanceDestinations(orgId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, {}, "Org");
+}
+export async function createGovernanceDestination(orgId, body) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations`, { method: "POST", body: JSON.stringify(body) }, "Org");
+}
+export async function deleteGovernanceDestination(orgId, destinationId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/notification-destinations/${encodeURIComponent(destinationId)}`, { method: "DELETE" }, "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");
+}
+export async function listGovernanceRules(orgId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, {}, "Org");
+}
+export async function createGovernanceRule(orgId, body) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules`, { method: "POST", body: JSON.stringify(body) }, "Org");
+}
+export async function deleteGovernanceRule(orgId, ruleId) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/governance/escalation-rules/${encodeURIComponent(ruleId)}`, { method: "DELETE" }, "Rule");
+}
+// ─── api-keys (ADR-049) ─────────────────────────────────────────────────
+/**
+ * Capability-based scope vocabulary (ADR-049). Mirrors the API's
+ * VALID_SCOPES exactly. Update both surfaces together when the
+ * vocabulary changes.
+ */
+export const API_KEY_SCOPES = [
+    "gateway",
+    "api:read",
+    "api:write",
+    "admin:org",
+    "admin:platform",
+];
+export const DEFAULT_API_KEY_SCOPES = [
+    "gateway",
+    "api:read",
+    "api:write",
+];
+/**
+ * Recognize legacy two-scope sets so the CLI can annotate pre-ADR-049
+ * keys appropriately. Mirror of mnemom-api `expandLegacyScopes` logic
+ * for display purposes; the auth gate handles the actual aliasing.
+ */
+export function isLegacyScopeSet(scopes) {
+    if (!scopes || scopes.length === 0)
+        return false;
+    if (scopes.length === 2 && scopes.includes("gateway") && scopes.includes("api")) {
+        return true;
+    }
+    if (scopes.length === 1 && scopes[0] === "api")
+        return true;
+    return false;
+}
+/**
+ * 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 Error("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}`);
+    }
+    const data = (await response.json());
+    return data.keys ?? [];
+}
+/**
+ * POST /v1/api-keys — mint a new personal API key with explicit scopes.
+ *
+ * Returns the full secret only on this call. The mint-time ceiling
+ * rejects admin scopes the caller is not eligible for (admin:platform
+ * for non-staff, admin:org for users not in any org-admin role).
+ */
+export async function createApiKey(name, scopes) {
+    const url = validateUrl(`${API_BASE}/v1/api-keys`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: { ...(await authHeaders()), "Content-Type": "application/json" },
+        body: JSON.stringify({ name, scopes }),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        const body = await response.text().catch(() => "");
+        if (response.status === 403) {
+            throw new Error(`Mint-time ceiling rejected scope: ${body}`);
+        }
+        if (response.status === 400) {
+            throw new Error(`Invalid scope(s): ${body}`);
+        }
+        throw new Error(`Failed to create api key: ${response.status} ${body}`);
+    }
+    return (await response.json());
+}
+/**
+ * POST /v1/api-keys/{key_id}/rotate — atomic mint-new + revoke-old.
+ * Returns the full new secret only on this call. The new key inherits
+ * the old key's name and scopes verbatim; the old key is revoked the
+ * moment this returns.
+ */
+export async function rotateApiKey(keyId) {
+    const url = validateUrl(`${API_BASE}/v1/api-keys/${encodeURIComponent(keyId)}/rotate`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: { ...(await authHeaders()), "Content-Type": "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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}`);
+    }
+    return (await response.json());
+}
+/**
+ * DELETE /v1/api-keys/{key_id} — soft-revoke. The key row stays for
+ * audit; `is_active` flips to false and `revoked_at` is timestamped.
+ */
+export async function revokeApiKey(keyId) {
+    const url = validateUrl(`${API_BASE}/v1/api-keys/${encodeURIComponent(keyId)}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "DELETE",
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("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}`);
+    }
+}