@mnemom/mnemom 0.13.0 → 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.js

@@ -807,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/protection.js

@@ -578,8 +578,11 @@ export async function protectionEditCommand(agentName, options = {}) {
             },
             trusted_sources: { domains: [], agent_ids: [], ip_ranges: [] },
         }, { lineWidth: 120, noRefs: true });
-    const tmpDir = os.tmpdir();
-    const tmpFile = path.join(tmpDir, `mnemom-protection-${agentId}.yaml`);
+    // Per-invocation temp dir via 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-protection-"));
+    const tmpFile = path.join(tmpDir, `${agentId}.yaml`);
     fs.writeFileSync(tmpFile, cardYaml);
     const editor = process.env.EDITOR || process.env.VISUAL || "vi";
     console.log(`Opening ${editor}...`);

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+import { program } from "commander";
+export { program };

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { pathToFileURL } from "node:url";
 import { program } from "commander";
 import { CLI_VERSION } from "./version.js";
 import { statusCommand } from "./commands/status.js";
@@ -8,7 +9,7 @@ import { licenseActivateCommand, licenseStatusCommand, licenseDeactivateCommand,
 import { cardShowCommand, cardPublishCommand, cardValidateCommand, cardEditCommand, cardEvaluateCommand, } from "./commands/card.js";
 import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyListCommand, policyTestCommand, policyEvaluateCommand, } from "./commands/policy.js";
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, } from "./commands/protection.js";
-import { agentsListCommand } from "./commands/agents.js";
+import { agentsListCommand, agentsClaimCommand } from "./commands/agents.js";
 import { orgListCommand, orgShowCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -295,12 +296,36 @@ policyCmd
 // ============================================================================
 // Agent management
 // ============================================================================
-program
+const agentsCmd = program
     .command("agents")
-    .description("List agents in your account")
-    .action(async () => {
+    .description("List agents across the orgs you belong to (ADR-062 org-scoped)")
+    .option("--org <id>", "Scope to a single org (default: all orgs you belong to)")
+    .action(async (opts) => {
     try {
-        await agentsListCommand();
+        await agentsListCommand({ org: opts.org });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentsCmd
+    .command("claim <id-or-name>")
+    .description("Claim an agent into an org (ADR-062 claim-to-org)")
+    .option("--org <slug>", "Org slug or id to claim into (default: your personal org)")
+    .option("--key <key>", "The agent's provider API key — the CLI derives the hash proof from it")
+    .option("--hash-proof <hex>", "A pre-computed 64-hex SHA-256 proof (advanced/CI; alternative to --key)")
+    .option("--name <name>", "Provisioned agent name used in proof derivation (defaults to a name-shaped positional arg)")
+    .option("--json", "Output JSON instead of human-readable text")
+    .action(async (idOrName, opts) => {
+    try {
+        await agentsClaimCommand(idOrName, {
+            org: opts.org,
+            key: opts.key,
+            hashProof: opts.hashProof,
+            name: opts.name,
+            json: opts.json,
+        });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -1296,4 +1321,13 @@ program
         process.exit(1);
     }
 });
-program.parse();
+// Export the fully-assembled commander program so tooling (e.g. the
+// command-tree snapshot generator in scripts/gen-command-tree.mjs) can
+// statically introspect the command surface WITHOUT executing the CLI.
+export { program };
+// Parse argv only when invoked as the CLI entrypoint — not when imported.
+// (ESM has no `require.main`; compare this module's URL to argv[1].)
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    program.parse();
+}

package/dist/lib/api.d.ts

@@ -207,6 +207,13 @@ export interface AgentListItem {
     containment_status: string | null;
     key_prefix?: string | null;
 }
+/**
+ * @deprecated Legacy per-user listing — `GET /v1/agents` is scoped by the
+ * caller's `claimed_by` rows, which ADR-062 retired as an authorization /
+ * listing boundary (org_id is now the sole boundary). New code must list via
+ * {@link listOrgAgents} (org-scoped). Retained only for back-compat callers;
+ * the `mnemom agents` command and name resolution no longer use it.
+ */
 export declare function listAgents(): Promise<AgentListItem[]>;
 export interface OrgListItem {
     org_id: string;
@@ -231,6 +238,85 @@ export interface PersonalOrgRef {
  * first; multi-user orgs follow.
  */
 export declare function listMyOrgs(): Promise<OrgListItem[]>;
+/**
+ * One agent row from the org-scoped fleet (`get_org_agent_fleet`). Mirrors the
+ * website's `OrgFleetAgent` shape so the CLI and dashboard read the same
+ * surface. This is the ADR-062-canonical listing: every agent has exactly one
+ * governing org, and the fleet is keyed on `org_id` (not `claimed_by`).
+ */
+export interface OrgFleetAgent {
+    agent_id: string;
+    agent_name: string;
+    owner_email: string | null;
+    last_seen: string | null;
+    created_at: string;
+    integrity_score: number;
+    coverage_ratio: number;
+    latest_verdict: string | null;
+    active_drift_alerts: number;
+    worst_drift_severity: string | null;
+    check_count: number;
+    containment_status?: string | null;
+    avatar_url?: string | null;
+}
+/**
+ * GET /v1/orgs/:org_id/agents — the org-scoped agent fleet (ADR-062). Any
+ * member of the org may read it; non-members get 403.
+ */
+export declare function fetchOrgFleet(orgId: string): Promise<OrgFleetAgent[]>;
+/** An {@link AgentListItem} tagged with the org it belongs to. */
+export interface OrgAgentRow extends AgentListItem {
+    org_id: string;
+    org_name: string;
+}
+/**
+ * List agents the ADR-062 way: scoped by org membership, never by `claimed_by`.
+ *
+ * - With `orgId`: lists that single org's fleet.
+ * - Without `orgId`: aggregates the fleet across every org the caller belongs
+ *   to (the same pattern as {@link listAllTeams}), tagging each row with its
+ *   org. Orgs the caller can't read (403/404) are skipped silently so one
+ *   inaccessible org doesn't fail the whole listing.
+ */
+export declare function listOrgAgents(orgId?: string): Promise<OrgAgentRow[]>;
+/**
+ * Result of a successful agent claim (ADR-062). Mirrors the locked
+ * `POST /v1/agents/:id/claim` 200 body verbatim — only the fields the
+ * endpoint actually returns. `org_id` is the org the agent ACTUALLY landed
+ * in (resolved server-side: the requested org, or the caller's personal org
+ * when none was supplied), so the CLI can confirm placement without a
+ * follow-up read. Optional/defaulted on the type so a mid-deploy CLI pointed
+ * at an older API that omits a field degrades to a sane value rather than
+ * crashing.
+ */
+export interface ClaimAgentResult {
+    claimed: boolean;
+    agent_id: string;
+    /** Resolved landing org (may differ from the request); null if unscoped. */
+    org_id: string | null;
+    /** ISO-8601 claim timestamp; null if the server omits it. */
+    claimed_at: string | null;
+}
+/**
+ * POST /v1/agents/:id/claim — claim an agent into an org (ADR-062).
+ *
+ * Body is `{ hash_proof, org_id? }`. `hash_proof` (the agent's full SHA-256
+ * proof) authenticates the caller as the agent's owner; the user's own auth
+ * header rides along too so the platform can validate org membership and link
+ * the principal. Omit `orgId` to land in the caller's personal org (the
+ * platform default); a supplied `orgId` is validated against the caller's
+ * memberships server-side (a non-member gets a 403 the command layer turns
+ * into a teaching error listing claimable orgs).
+ *
+ * An Idempotency-Key is minted (and held across the 401-refresh retry) so a
+ * retried claim replays the same logical operation server-side.
+ */
+export declare function claimAgent(agentId: string, body: {
+    hashProof: string;
+    orgId?: string;
+}, opts?: {
+    idempotencyKey?: string;
+}): Promise<ClaimAgentResult>;
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the
@@ -369,11 +455,11 @@ export declare function revokeTeamAdmin(teamId: string, userId: string): Promise
  */
 export declare function listTeamAdmins(teamId: string): Promise<TeamAdminListResponse>;
 /**
- * Look up an agent in the authenticated user's account by name.
+ * Look up an agent by name across the caller's org fleets (ADR-062-scoped via
+ * {@link listOrgAgents}, not the legacy `claimed_by` list).
  * Tries exact match first, then single partial match.
  * Throws if multiple agents partially match (ambiguous).
  * Returns null if no match found.
- * Note: capped at 100 agents by listAgents().
  */
 export declare function getAgentByName(name: string): Promise<AgentListItem | null>;
 /**

package/dist/lib/api.js

@@ -205,6 +205,13 @@ async function fetchWithAuthRetry(url, buildInit) {
 export async function getAgent(id) {
     return fetchApi(`/v1/agents/${id}`);
 }
+/**
+ * @deprecated Legacy per-user listing — `GET /v1/agents` is scoped by the
+ * caller's `claimed_by` rows, which ADR-062 retired as an authorization /
+ * listing boundary (org_id is now the sole boundary). New code must list via
+ * {@link listOrgAgents} (org-scoped). Retained only for back-compat callers;
+ * the `mnemom agents` command and name resolution no longer use it.
+ */
 export async function listAgents() {
     const url = validateUrl(`${API_BASE}/v1/agents?limit=100`);
     const response = await fetchWithAuthRetry(url, async () => ({
@@ -238,6 +245,127 @@ export async function listMyOrgs() {
     const data = (await response.json());
     return data.orgs ?? [];
 }
+/**
+ * GET /v1/orgs/:org_id/agents — the org-scoped agent fleet (ADR-062). Any
+ * member of the org may read it; non-members get 403.
+ */
+export async function fetchOrgFleet(orgId) {
+    const url = validateUrl(`${API_BASE}/v1/orgs/${encodeURIComponent(orgId)}/agents`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json" },
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        throw await readApiError(response, "Failed to list org agents");
+    }
+    const data = (await response.json());
+    return data.agents ?? [];
+}
+function fleetToRow(a, org) {
+    return {
+        id: a.agent_id,
+        name: a.agent_name ?? null,
+        email: a.owner_email ?? null,
+        created_at: a.created_at,
+        last_seen: a.last_seen ?? null,
+        containment_status: a.containment_status ?? null,
+        org_id: org.org_id,
+        org_name: org.name,
+    };
+}
+/**
+ * List agents the ADR-062 way: scoped by org membership, never by `claimed_by`.
+ *
+ * - With `orgId`: lists that single org's fleet.
+ * - Without `orgId`: aggregates the fleet across every org the caller belongs
+ *   to (the same pattern as {@link listAllTeams}), tagging each row with its
+ *   org. Orgs the caller can't read (403/404) are skipped silently so one
+ *   inaccessible org doesn't fail the whole listing.
+ */
+export async function listOrgAgents(orgId) {
+    let orgs;
+    if (orgId) {
+        // Resolve a friendly name if the caller is a member; fall back to the id.
+        const mine = await listMyOrgs().catch(() => []);
+        const match = mine.find((o) => o.org_id === orgId);
+        orgs = [{ org_id: orgId, name: match?.name ?? orgId }];
+    }
+    else {
+        orgs = (await listMyOrgs()).map((o) => ({ org_id: o.org_id, name: o.name }));
+    }
+    const rows = [];
+    const seen = new Set();
+    for (const org of orgs) {
+        let fleet;
+        try {
+            fleet = await fetchOrgFleet(org.org_id);
+        }
+        catch (err) {
+            // A specific --org that we can't read is a real error worth surfacing;
+            // a skipped org during aggregation is not.
+            if (orgId)
+                throw err;
+            continue;
+        }
+        for (const a of fleet) {
+            if (seen.has(a.agent_id))
+                continue;
+            seen.add(a.agent_id);
+            rows.push(fleetToRow(a, org));
+        }
+    }
+    return rows;
+}
+/**
+ * POST /v1/agents/:id/claim — claim an agent into an org (ADR-062).
+ *
+ * Body is `{ hash_proof, org_id? }`. `hash_proof` (the agent's full SHA-256
+ * proof) authenticates the caller as the agent's owner; the user's own auth
+ * header rides along too so the platform can validate org membership and link
+ * the principal. Omit `orgId` to land in the caller's personal org (the
+ * platform default); a supplied `orgId` is validated against the caller's
+ * memberships server-side (a non-member gets a 403 the command layer turns
+ * into a teaching error listing claimable orgs).
+ *
+ * An Idempotency-Key is minted (and held across the 401-refresh retry) so a
+ * retried claim replays the same logical operation server-side.
+ */
+export async function claimAgent(agentId, body, opts = {}) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${encodeURIComponent(agentId)}/claim`);
+    const payload = {
+        hash_proof: sanitizeForHttp(body.hashProof),
+    };
+    if (body.orgId)
+        payload.org_id = sanitizeForHttp(body.orgId);
+    const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "POST",
+        headers: {
+            ...(await authHeaders()),
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "Idempotency-Key": idempotencyKey,
+        },
+        body: JSON.stringify(payload),
+    }));
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new MnemomApiError(401, "Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
+        }
+        throw await readApiError(response, "Failed to claim agent");
+    }
+    const data = (await response.json());
+    return {
+        claimed: data.claimed ?? true,
+        agent_id: data.agent_id ?? agentId,
+        // Reflect what the server resolved — null (not "") when absent/unscoped,
+        // matching the locked SDK contract so the two surfaces don't drift.
+        org_id: data.org_id ?? null,
+        claimed_at: data.claimed_at ?? null,
+    };
+}
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the
@@ -511,14 +639,14 @@ export async function listTeamAdmins(teamId) {
     return (await response.json());
 }
 /**
- * Look up an agent in the authenticated user's account by name.
+ * Look up an agent by name across the caller's org fleets (ADR-062-scoped via
+ * {@link listOrgAgents}, not the legacy `claimed_by` list).
  * Tries exact match first, then single partial match.
  * Throws if multiple agents partially match (ambiguous).
  * Returns null if no match found.
- * Note: capped at 100 agents by listAgents().
  */
 export async function getAgentByName(name) {
-    const agents = await listAgents();
+    const agents = await listOrgAgents();
     const lower = name.toLowerCase();
     const exact = agents.find((a) => a.name?.toLowerCase() === lower);
     if (exact)
@@ -607,7 +735,10 @@ export async function getTraces(id, limit = 10) {
  */
 export async function getAlignmentCard(agentId, format = "yaml") {
     const accept = format === "yaml" ? "text/yaml" : "application/json";
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/alignment-card`);
+    // Canonical Resources × Scope × Verb surface (ADR-062 / cards-as-primitive
+    // W1.2b). The legacy `/v1/agents/:id/alignment-card` only 308-redirects to
+    // this — first-party callers target canonical directly (no legacy shapes).
+    const url = validateUrl(`${API_BASE}/v1/alignment/agent/${encodeURIComponent(agentId)}`);
     const response = await fetch(url, {
         headers: { Accept: accept, ...(await authHeaders()) },
     });
@@ -628,7 +759,10 @@ export const ALIGNMENT_CARD_MAX_BYTES = 128 * 1024;
  * Accepts YAML or JSON body; set contentType accordingly.
  */
 export async function putAlignmentCard(agentId, body, contentType = "text/yaml", opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/alignment-card`);
+    // Canonical Resources × Scope × Verb surface (ADR-062 / cards-as-primitive
+    // W1.2b). The legacy `/v1/agents/:id/alignment-card` only 308-redirects to
+    // this — first-party callers target canonical directly (no legacy shapes).
+    const url = validateUrl(`${API_BASE}/v1/alignment/agent/${encodeURIComponent(agentId)}`);
     // Lock in a single Idempotency-Key for this logical mutation. If the auth
     // token is stale and the first attempt returns 401, fetchWithAuthRetry
     // refreshes the token and retries — but the Idempotency-Key must be the
@@ -662,7 +796,9 @@ export async function putAlignmentCard(agentId, body, contentType = "text/yaml",
  */
 export async function getProtectionCard(agentId, format = "yaml") {
     const accept = format === "yaml" ? "text/yaml" : "application/json";
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/protection-card`);
+    // Canonical surface (ADR-062 / W1.2b); legacy `/v1/agents/:id/protection-card`
+    // only 308-redirects here. First-party callers use canonical directly.
+    const url = validateUrl(`${API_BASE}/v1/protection/agent/${encodeURIComponent(agentId)}`);
     const response = await fetch(url, {
         headers: { Accept: accept, ...(await authHeaders()) },
     });
@@ -682,7 +818,9 @@ export const PROTECTION_CARD_MAX_BYTES = 64 * 1024;
  * Publish (create or update) a protection card.
  */
 export async function putProtectionCard(agentId, body, contentType = "text/yaml", opts = {}) {
-    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/protection-card`);
+    // Canonical surface (ADR-062 / W1.2b); legacy `/v1/agents/:id/protection-card`
+    // only 308-redirects here. First-party callers use canonical directly.
+    const url = validateUrl(`${API_BASE}/v1/protection/agent/${encodeURIComponent(agentId)}`);
     // See putAlignmentCard for why the Idempotency-Key is computed once outside
     // the retry closure.
     const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -10,6 +10,8 @@
   "scripts": {
     "build": "npm install --prefix ../shared/policy-engine && npm run build --prefix ../shared/policy-engine && tsc",
     "dev": "tsx src/index.ts",
+    "gen:command-tree": "tsx scripts/gen-command-tree.mjs",
+    "check:command-tree": "tsx scripts/gen-command-tree.mjs --check",
     "test": "vitest"
   },
   "dependencies": {