@mnemom/mnemom 0.12.1 → 0.14.0

package/dist/commands/agents.d.ts

@@ -1 +1,37 @@
-export declare function agentsListCommand(): Promise<void>;
+export interface AgentsListOptions {
+    /** Scope to a single org. When omitted, aggregates across every org you belong to. */
+    org?: string;
+}
+export declare function agentsListCommand(options?: AgentsListOptions): Promise<void>;
+export interface AgentsClaimOptions {
+    /** Org slug OR org_id to claim into. Omit → land in your personal org (the API default). */
+    org?: string;
+    /** The agent's provider API key — the CLI derives the hash proof from it. */
+    key?: string;
+    /** A pre-computed 64-hex hash proof (advanced/CI; alternative to --key). */
+    hashProof?: string;
+    /**
+     * The name the agent was provisioned with, used in the proof derivation
+     * `sha256(`${key}|${name}`)`. Defaults to a name-shaped positional arg, else
+     * the agent is treated as an unnamed singleton (`sha256(key)`).
+     */
+    name?: string;
+    json?: boolean;
+}
+/**
+ * Derive the full 64-hex hash proof the claim endpoint expects:
+ * `sha256(`${apiKey}|${agentName}`)` for a named agent, or `sha256(apiKey)`
+ * for an unnamed singleton. This mirrors the gateway's provisioning
+ * derivation (gateway/src/index.ts) and agent-proof.ts on the API side.
+ */
+export declare function deriveHashProof(apiKey: string, agentName?: string): string;
+/**
+ * `mnemom agents claim <id-or-name> [--org <slug>] (--key <k> | --hash-proof <h>)`
+ *
+ * Claims an agent into an org (ADR-062). Possession of the agent's key (via
+ * `--key`, from which the CLI derives the proof) or a pre-computed
+ * `--hash-proof` authenticates the claim; `--org` selects the landing org
+ * (omit → your personal org). On a not-a-member 403 the command teaches by
+ * listing your claimable orgs.
+ */
+export declare function agentsClaimCommand(idOrName: string, options?: AgentsClaimOptions): Promise<void>;

package/dist/commands/agents.js

@@ -1,13 +1,14 @@
-import { listAgents } from "../lib/api.js";
+import { createHash } from "node:crypto";
+import { listOrgAgents, listMyOrgs, getAgentByName, claimAgent, MnemomApiError, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
-export async function agentsListCommand() {
+export async function agentsListCommand(options = {}) {
     await requireAuth();
     console.log(fmt.header("Agents"));
     console.log();
     let agents;
     try {
-        agents = await listAgents();
+        agents = await listOrgAgents(options.org);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -15,24 +16,248 @@ export async function agentsListCommand() {
         process.exit(1);
     }
     if (agents.length === 0) {
-        console.log("  No agents found.\n");
+        console.log(options.org ? `  No agents found in org '${options.org}'.\n` : "  No agents found.\n");
         return;
     }
-    // Table header
+    // Show the Org column only when aggregating across orgs; with --org it's redundant.
+    const showOrg = !options.org;
     const nameW = 24;
     const idW = 40;
     const seenW = 14;
     const statusW = 14;
-    const header = "Name".padEnd(nameW) + "ID".padEnd(idW) + "Last Seen".padEnd(seenW) + "Containment";
+    const orgW = 22;
+    let header = "Name".padEnd(nameW) +
+        "ID".padEnd(idW) +
+        "Last Seen".padEnd(seenW) +
+        "Containment".padEnd(statusW);
+    if (showOrg)
+        header += "Org";
     console.log(`  ${header}`);
-    console.log(`  ${"─".repeat(nameW + idW + seenW + statusW)}`);
+    console.log(`  ${"─".repeat(nameW + idW + seenW + statusW + (showOrg ? orgW : 0))}`);
     for (const agent of agents) {
         const name = (agent.name ?? "-").slice(0, nameW - 2).padEnd(nameW);
         const id = agent.id.padEnd(idW);
         const lastSeen = agent.last_seen ? new Date(agent.last_seen).toLocaleDateString() : "-";
         const seen = lastSeen.padEnd(seenW);
-        const containment = agent.containment_status ?? "-";
-        console.log(`  ${name}${id}${seen}${containment}`);
+        const containment = (agent.containment_status ?? "-").padEnd(statusW);
+        const org = showOrg ? agent.org_name.slice(0, orgW - 2) : "";
+        console.log(`  ${name}${id}${seen}${containment}${org}`);
     }
     console.log(`\n  Total: ${agents.length} agent(s)\n`);
 }
+// ─── agents claim (ADR-062 claim-to-org) ──────────────────────────────────
+/** Matches the canonical agent-id shapes (mirrors resolveAgentId in lib/api). */
+const AGENT_ID_RE = /^(smolt-[0-9a-f]{8}|mnm-[0-9a-f-]{36})$/;
+/** A presented hash proof is the full 64-hex SHA-256 digest. */
+const FULL_PROOF_RE = /^[0-9a-f]{64}$/;
+// SHA-256 → lowercase hex. NOTE the apiKey-derived input below: this is NOT
+// password-at-rest hashing — it's the platform's deterministic proof-of-
+// possession (`hash_proof`). It MUST equal the server's stored value, which the
+// gateway + mnemom-api/src/auth/agent-proof.ts compute as plain SHA-256 of
+// `${apiKey}|${name}`. A slow KDF (bcrypt/scrypt) would produce a different
+// digest and break the claim handshake entirely, so SHA-256 is mandated by the
+// protocol — the "insufficient computational effort" alert is a false positive.
+function sha256Hex(input) {
+    // lgtm[js/insufficient-password-hash] — protocol proof, not password storage (see note above)
+    return createHash("sha256").update(input, "utf8").digest("hex"); // codeql[js/insufficient-password-hash]
+}
+/**
+ * Derive the full 64-hex hash proof the claim endpoint expects:
+ * `sha256(`${apiKey}|${agentName}`)` for a named agent, or `sha256(apiKey)`
+ * for an unnamed singleton. This mirrors the gateway's provisioning
+ * derivation (gateway/src/index.ts) and agent-proof.ts on the API side.
+ */
+export function deriveHashProof(apiKey, agentName) {
+    const key = apiKey.trim();
+    const name = agentName?.trim();
+    return name ? sha256Hex(`${key}|${name}`) : sha256Hex(key);
+}
+/**
+ * Resolve an `--org <slug>` value to an org_id. Accepts either a slug or a raw
+ * org_id (both are matched against the caller's memberships). Returns the
+ * resolved org_id, or throws a teaching error listing the caller's orgs when
+ * the value matches none of them.
+ */
+function resolveOrgId(slugOrId, orgs) {
+    const needle = slugOrId.trim();
+    const match = orgs.find((o) => o.slug === needle) ?? orgs.find((o) => o.org_id === needle);
+    if (match)
+        return match.org_id;
+    const choices = orgs.map((o) => `    ${o.slug.padEnd(24)} ${o.name}`).join("\n");
+    throw new Error(`No org of yours matches '${needle}'. You can claim into one of:\n${choices}\n` +
+        `  Pass --org <slug>, or omit --org to land in your personal org.`);
+}
+/** The not-a-member 403 code emitted by the merged endpoint. */
+const NOT_A_MEMBER_CODE = "agent_org_not_member";
+/**
+ * Distinguish a not-a-member 403 (the requested org isn't one of yours) from
+ * the other 403s this endpoint emits — `invalid_hash_proof` and
+ * `agent_cross_tenant` (already claimed by a different owner) — which should
+ * fall through to the generic error. Source-verified against #713: the
+ * not-a-member 403 carries `code: "agent_org_not_member"` and
+ * `details.claimable_orgs`. A loose match guards against minor drift.
+ */
+function isNotAMemberError(err) {
+    if (err.code === NOT_A_MEMBER_CODE)
+        return true;
+    if (extractClaimableOrgs(err.details).length > 0)
+        return true;
+    return /org_not_member|not_a_member|not_org_member/.test(err.code ?? "");
+}
+/** Pull the server-provided claimable-org list off a 403 body, if present. */
+function extractClaimableOrgs(details) {
+    const list = details?.claimable_orgs;
+    if (!Array.isArray(list))
+        return [];
+    return list.filter((o) => !!o && typeof o === "object" && typeof o.org_id === "string");
+}
+/**
+ * `mnemom agents claim <id-or-name> [--org <slug>] (--key <k> | --hash-proof <h>)`
+ *
+ * Claims an agent into an org (ADR-062). Possession of the agent's key (via
+ * `--key`, from which the CLI derives the proof) or a pre-computed
+ * `--hash-proof` authenticates the claim; `--org` selects the landing org
+ * (omit → your personal org). On a not-a-member 403 the command teaches by
+ * listing your claimable orgs.
+ */
+export async function agentsClaimCommand(idOrName, options = {}) {
+    await requireAuth();
+    // 1. Resolve the agent id to claim. An UNCLAIMED agent is not in your org
+    //    fleet yet, so a name can only be resolved for agents you can already
+    //    see; the reliable path for a fresh claim is to pass the agent id.
+    const looksLikeId = AGENT_ID_RE.test(idOrName);
+    let agentId = idOrName;
+    let derivationName = options.name;
+    if (!looksLikeId) {
+        // A name-shaped arg: try the fleet, else guide the user to the id.
+        const found = await getAgentByName(idOrName).catch(() => null);
+        if (found) {
+            agentId = found.id;
+            derivationName = derivationName ?? found.name ?? idOrName;
+        }
+        else {
+            // The arg names an agent we can't see yet (unclaimed agents aren't in
+            // your fleet), so we have no id to address the claim — guide to the id.
+            console.log(fmt.error(`Could not resolve '${idOrName}' to an agent id you can see yet — unclaimed agents are not in your fleet.`));
+            console.log(fmt.dim(`  Pass the agent id directly: mnemom agents claim mnm-... --key <key> [--name ${idOrName}]`) + "\n");
+            process.exit(1);
+            return;
+        }
+    }
+    // 2. Establish the hash proof: --hash-proof (raw) takes precedence, else
+    //    derive from --key. Exactly one source is needed.
+    let hashProof;
+    if (options.hashProof) {
+        const proof = options.hashProof.trim().toLowerCase();
+        if (!FULL_PROOF_RE.test(proof)) {
+            console.log(fmt.error("--hash-proof should be the full 64-character hex SHA-256 proof.") + "\n");
+            process.exit(1);
+            return;
+        }
+        hashProof = proof;
+    }
+    else if (options.key) {
+        hashProof = deriveHashProof(options.key, derivationName);
+    }
+    else {
+        console.log(fmt.error("Claiming needs proof you hold the agent's key.") + "\n");
+        console.log(fmt.dim("  Pass --key <agent-api-key> (the CLI derives the proof), or --hash-proof <64-hex> directly.") + "\n");
+        process.exit(1);
+        return;
+    }
+    // 3. Resolve --org slug → org_id (omit → server default / personal org).
+    let orgId;
+    let orgs = [];
+    if (options.org) {
+        try {
+            orgs = await listMyOrgs();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(fmt.error(`Failed to read your orgs: ${msg}`) + "\n");
+            process.exit(1);
+            return;
+        }
+        try {
+            orgId = resolveOrgId(options.org, orgs);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(fmt.error(msg) + "\n");
+            process.exit(1);
+            return;
+        }
+    }
+    // 4. Claim.
+    let result;
+    try {
+        result = await claimAgent(agentId, { hashProof, orgId });
+    }
+    catch (err) {
+        if (err instanceof MnemomApiError && err.effectiveStatus === 403 && isNotAMemberError(err)) {
+            // Teaching error: list the orgs the caller can actually claim into.
+            // Prefer `mnemom org list` data (listMyOrgs) — it carries slugs, so we
+            // can print the actionable `--org <slug>`. The server's
+            // `details.claimable_orgs` (org_id + name, NO slug) is the fallback when
+            // the membership list is unavailable.
+            const memberOrgs = orgs.length ? orgs : await listMyOrgs().catch(() => []);
+            console.log(fmt.error(`You are not a member of '${options.org}', so the agent can't land there.`));
+            if (memberOrgs.length) {
+                console.log("\n  You can claim into one of (use the slug):");
+                for (const o of memberOrgs) {
+                    const tag = o.is_personal ? " (personal)" : "";
+                    console.log(`    ${o.slug.padEnd(24)} ${o.name}${tag}`);
+                }
+                console.log(`\n  Re-run with --org <slug>, or omit --org to land in your personal org.\n`);
+            }
+            else {
+                const fromServer = extractClaimableOrgs(err.details);
+                if (fromServer.length) {
+                    console.log("\n  You can claim into one of (use the org id):");
+                    for (const o of fromServer) {
+                        const tag = o.is_personal ? " (personal)" : "";
+                        console.log(`    ${o.org_id.padEnd(40)} ${o.name}${tag}`);
+                    }
+                    console.log(`\n  Re-run with --org <id>, or omit --org to land in your personal org.\n`);
+                }
+                else {
+                    console.log(fmt.dim("  Run `mnemom org list` to see the orgs you belong to.") + "\n");
+                }
+            }
+            process.exit(1);
+            return;
+        }
+        if (err instanceof MnemomApiError && err.effectiveStatus === 503) {
+            // The platform is still provisioning the caller's personal org. Transient.
+            console.log(fmt.warn("Your personal org is still being set up. Give it a moment and run claim again."));
+            console.log("");
+            process.exit(1);
+            return;
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(fmt.error(`Failed to claim agent: ${msg}`) + "\n");
+        process.exit(1);
+        return;
+    }
+    // 5. Report where it landed.
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Map the resolved org_id to a friendly name when we can.
+    const landed = result.org_id;
+    let where;
+    if (!landed) {
+        where = "your personal org (default scope)";
+    }
+    else {
+        const named = (orgs.length ? orgs : await listMyOrgs().catch(() => [])).find((o) => o.org_id === landed);
+        where = named ? `${named.name} (${named.slug})` : landed;
+    }
+    console.log(fmt.success(`Claimed ${result.agent_id}.`));
+    console.log(fmt.label("  Landed in:", where));
+    if (result.claimed_at) {
+        console.log(fmt.label("  Claimed at:", new Date(result.claimed_at).toLocaleString()));
+    }
+    console.log();
+}

package/dist/commands/card.d.ts

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

package/dist/commands/card.js

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

package/dist/commands/integrity.js

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

package/dist/commands/license.js

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