@mnemom/mnemom 0.16.1 → 0.16.3

package/dist/lib/oauth.js

@@ -39,6 +39,14 @@ const LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000;
 // both interactive login poll loops emit, so a multi-minute browser sign-in
 // doesn't read as a hung CLI (matches the card-write retry tick in try-me).
 const LOGIN_HEARTBEAT_MS = 15 * 1000;
+// Refresh-token retry policy (R6 / MNE-7394). A transient AS 5xx or a dropped
+// network connection during refresh must be retried with bounded exponential
+// backoff rather than collapsed into the re-login signal — a one-second AS
+// hiccup or a flaky Wi-Fi moment must not invalidate a valid, long-lived
+// session. Per-attempt delay is REFRESH_BACKOFF_BASE_MS * 2**attemptIndex →
+// ~1s / 2s / 4s across REFRESH_MAX_ATTEMPTS attempts.
+const REFRESH_MAX_ATTEMPTS = 3;
+const REFRESH_BACKOFF_BASE_MS = 1000;
 let cachedMetadata = null;
 /**
  * Fetch (and process-cache) the AS metadata document. We resolve it relative to
@@ -359,40 +367,101 @@ async function pollDeviceToken(meta, clientId, authz, sleep, display) {
 // Refresh (RFC 6749 §6)
 // ============================================================================
 /**
- * Exchange a refresh token for a fresh access token. Returns null if refresh is
- * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
- * so callers can fall back to prompting for re-login rather than crashing.
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Failure classification (R6 / MNE-7394) — a transient failure must never be
+ * indistinguishable from a revoked credential:
+ *   - 2xx → return the fresh tokens (carrying the prior refresh token forward
+ *     per RFC 6749 §6 when the AS omits a new one).
+ *   - A 4xx whose OAuth body `error` is `invalid_grant` / `invalid_client` →
+ *     return `null`, the re-login signal. RFC 6749 §5.2 defines these as the
+ *     errors that mean the presented grant/client credential is genuinely no
+ *     longer valid, so a fresh login is the correct remedy. No retry.
+ *   - Any other 4xx (e.g. `invalid_request`, `429`, an unrecognized/absent body
+ *     error, a non-JSON body) → throw. Something is wrong, but it does NOT mean
+ *     the credentials are revoked, so we must not discard the session.
+ *   - `res.status >= 500` or a fetch/network exception → retry with bounded
+ *     exponential backoff (~1s/2s/4s, REFRESH_MAX_ATTEMPTS attempts); if the
+ *     retries are exhausted, throw. Exhausting transient retries must NOT
+ *     masquerade as "credentials revoked" (fail-closed, MNE-442) — throwing
+ *     preserves the stored session so a later invocation can succeed once the
+ *     AS recovers.
+ *
+ * `null` is therefore narrowed to exactly the two re-login errors; every other
+ * outcome is a success, a retry, or a thrown error. `opts.sleep` is injectable
+ * so tests drive the backoff without real timers.
  */
-export async function refreshTokens(refreshToken, clientId) {
+export async function refreshTokens(refreshToken, clientId, opts) {
     if (!refreshToken || !clientId)
         return null;
-    try {
-        const meta = await discover();
-        const res = await fetch(meta.token_endpoint, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/x-www-form-urlencoded",
-                Accept: "application/json",
-            },
-            body: new URLSearchParams({
-                grant_type: "refresh_token",
-                refresh_token: refreshToken,
-                client_id: clientId,
-            }),
-        });
-        if (!res.ok)
+    const sleep = opts?.sleep ?? defaultSleep;
+    // Discovery is not part of the refresh retry budget; a discovery failure
+    // propagates as it does today (it is already thrown by discover()).
+    const meta = await discover();
+    let lastTransient = "";
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS; attempt++) {
+        let res;
+        try {
+            res = await fetch(meta.token_endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                    client_id: clientId,
+                }),
+            });
+        }
+        catch (err) {
+            // Network/fetch exception (DNS failure, connection reset, timeout) — this
+            // is unrelated to the validity of the refresh token, so retry it.
+            lastTransient = err instanceof Error ? err.message : String(err);
+            if (attempt < REFRESH_MAX_ATTEMPTS - 1) {
+                await sleep(REFRESH_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+        if (res.ok) {
+            const data = (await res.json());
+            const tokens = tokensFromResponse(data);
+            // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in
+            // which case the old one remains valid — preserve it so the next refresh
+            // works.
+            if (!tokens.refreshToken)
+                tokens.refreshToken = refreshToken;
+            return tokens;
+        }
+        if (res.status >= 500) {
+            // Transient AS outage — retry with backoff, then fall through to the
+            // "exhausted" throw once no attempts remain.
+            lastTransient = `HTTP ${res.status}`;
+            if (attempt < REFRESH_MAX_ATTEMPTS - 1) {
+                await sleep(REFRESH_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+        // 4xx — a definitive client-side rejection, never retried. Only
+        // invalid_grant / invalid_client map to the null re-login signal; every
+        // other 4xx surfaces as a thrown error rather than a silent null that would
+        // wrongly discard a valid session.
+        const body = (await res.json().catch(() => ({})));
+        if (body.error === "invalid_grant" || body.error === "invalid_client") {
             return null;
-        const data = (await res.json());
-        const tokens = tokensFromResponse(data);
-        // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in which
-        // case the old one remains valid — preserve it so the next refresh works.
-        if (!tokens.refreshToken)
-            tokens.refreshToken = refreshToken;
-        return tokens;
-    }
-    catch {
-        return null;
+        }
+        const detail = body.error
+            ? body.error + (body.error_description ? ` — ${body.error_description}` : "")
+            : `HTTP ${res.status}`;
+        throw new Error(`Token refresh failed: ${detail}`);
     }
+    // Retries exhausted on a 5xx or a network exception (fail-closed, MNE-442):
+    // throw rather than return null so the session is preserved for a later retry.
+    throw new Error(`Token refresh failed after ${REFRESH_MAX_ATTEMPTS} attempts ` +
+        `(last error: ${lastTransient || "unknown transient failure"}).`);
 }
 // ============================================================================
 // Helpers

package/dist/lib/protection-drift.d.ts

@@ -0,0 +1,117 @@
+/**
+ * protection-drift.ts — pure comparison between a COMMITTED protection-card
+ * snapshot (a file under `cards/`) and the LIVE canonical protection card
+ * returned by the platform.
+ *
+ * Split follows the convention `mnemom-api/src/composition/reconcile-flat-columns.ts`
+ * established: the decision logic is a pure, network-free module so it can be
+ * unit-tested exhaustively; the thin driver that actually fetches the live card
+ * lives in the command layer (`commands/protection.ts` → `mnemom protection drift`).
+ *
+ * WHAT IS BEING COMPARED (read this before extending):
+ *   - `committed` is a repo SNAPSHOT of the agent-scope card — human-authored,
+ *     declared intent. See `cards/README.md`.
+ *   - `live` is the CANONICAL COMPOSED card (`GET /v1/protection/agent/:id`,
+ *     via `getProtectionCard()`), i.e. the OUTPUT of
+ *     `composeProtectionCard(platform, org, teams…, agent)` with strictest-wins
+ *     mode resolution.
+ *   These are NOT the same object. A snapshot field matching the composed card
+ *   means "the effective posture is what the repo says it should be" — it does
+ *   NOT mean "publishing this snapshot would reproduce the live card". A
+ *   stricter scope upstream (org / team / platform floor) can raise the composed
+ *   mode above whatever the agent-scope card asks for.
+ */
+/**
+ * Fields on the canonical card that are re-derived on every compose and
+ * therefore carry no posture meaning. Comparing them would make any drift check
+ * permanently red.
+ *
+ *   - `card_version`: `compose.ts` sets it to
+ *     `protection/${new Date().toISOString().slice(0, 10)}` — a wall-clock stamp
+ *     of the LAST COMPOSE, not a semantic version. It changes whenever anything
+ *     recomposes, and never changes while the card sits untouched.
+ *   - `content_hash` / `composed_at` / `agent_protection_card_id` /
+ *     `updated_at` / `created_at` / `needs_recompose`: storage + provenance
+ *     bookkeeping written by the composer and the canonical-write RPC.
+ *
+ * The first version of this list was written from the composer's own field
+ * names. That was the wrong source: the list has to match what the SERIALIZER
+ * emits. A live read of `GET /v1/protection/agent/:id` on us-1 (2026-07-28)
+ * returns exactly:
+ *
+ *   mode, card_id, agent_id, issued_at, thresholds, card_version,
+ *   screen_surfaces, trusted_sources, protected_surface, _composition,
+ *   content_hash, version
+ *
+ * so `composed_at`, `created_at`, `updated_at`, `needs_recompose` and
+ * `agent_protection_card_id` never appear at all (kept below anyway — harmless,
+ * and they do appear on the raw DB row some callers pass in), while four
+ * derived fields the serializer DOES emit were missing: `card_id` (the
+ * server-stamped canonical id, provenance `kind: server_stamped`), `issued_at`
+ * (a compose-time stamp), `_composition` (the whole provenance envelope,
+ * `layer: derived` throughout, and itself containing `_composition.composed_at`)
+ * and `version` (the serializer's envelope version, not a posture field).
+ * Without them `--strict` reports four permanent `unrecorded` holes that no
+ * snapshot can ever close, which is precisely the state that would make an
+ * operator stop trusting the check.
+ *
+ * KNOWN COST of ignoring `version`: it is the serializer's envelope version, so
+ * a schema bump (2 → 3) passes silently here. That is the intended trade — a
+ * serializer version is not a posture claim, and an envelope change that alters
+ * a posture field will still surface as a mismatch or an unrecorded field. If
+ * the envelope version ever starts carrying posture semantics, drop it from
+ * this list.
+ */
+export declare const VOLATILE_FIELDS: readonly string[];
+export interface FieldMismatch {
+    /** Dotted path, e.g. `mode` or `screen_surfaces.tool_calls`. */
+    path: string;
+    committed: unknown;
+    live: unknown;
+}
+export interface DriftResult {
+    /**
+     * A field is present in BOTH the snapshot and the live card but the values
+     * differ. This is unambiguous drift: the repo's declared posture is not the
+     * posture actually in force. Always a failure.
+     */
+    mismatches: FieldMismatch[];
+    /**
+     * A top-level field the LIVE card carries that the snapshot does not record
+     * at all. Not a value conflict — a COVERAGE hole: that part of the live
+     * posture has no committed representation, so it could change with no diff.
+     * Reported always; fatal only under `strict`.
+     */
+    unrecorded: string[];
+    /**
+     * A top-level field the SNAPSHOT declares that the live card does not carry.
+     * The declared intent is simply not in force. Always a failure — treated as a
+     * mismatch against `undefined` would lose the distinction, so it is its own
+     * bucket.
+     */
+    missingLive: string[];
+    /** Volatile fields skipped, for transparency in the report. */
+    ignored: string[];
+}
+/**
+ * Compare a committed snapshot against the live canonical card.
+ *
+ * Pure: no I/O, no clock, no env. Both arguments are already-parsed objects.
+ */
+export declare function compareProtectionCards(committed: Record<string, unknown>, live: Record<string, unknown>): DriftResult;
+/**
+ * Policy: does this result fail the check?
+ *
+ * `mismatches` and `missingLive` always fail — the repo says one thing and the
+ * live posture is another. `unrecorded` is a coverage gap: reported by default,
+ * fatal only under `--strict`, so the check can go green today on a partial
+ * snapshot while still surfacing exactly which parts of the live posture remain
+ * unversioned. See `cards/README.md`.
+ */
+export declare function isDrift(result: DriftResult, opts?: {
+    strict?: boolean;
+}): boolean;
+/** Human-readable multi-line report. Returned, not printed, so it is testable. */
+export declare function formatDriftReport(result: DriftResult, opts?: {
+    strict?: boolean;
+}): string;

package/dist/lib/protection-drift.js

@@ -0,0 +1,180 @@
+/**
+ * protection-drift.ts — pure comparison between a COMMITTED protection-card
+ * snapshot (a file under `cards/`) and the LIVE canonical protection card
+ * returned by the platform.
+ *
+ * Split follows the convention `mnemom-api/src/composition/reconcile-flat-columns.ts`
+ * established: the decision logic is a pure, network-free module so it can be
+ * unit-tested exhaustively; the thin driver that actually fetches the live card
+ * lives in the command layer (`commands/protection.ts` → `mnemom protection drift`).
+ *
+ * WHAT IS BEING COMPARED (read this before extending):
+ *   - `committed` is a repo SNAPSHOT of the agent-scope card — human-authored,
+ *     declared intent. See `cards/README.md`.
+ *   - `live` is the CANONICAL COMPOSED card (`GET /v1/protection/agent/:id`,
+ *     via `getProtectionCard()`), i.e. the OUTPUT of
+ *     `composeProtectionCard(platform, org, teams…, agent)` with strictest-wins
+ *     mode resolution.
+ *   These are NOT the same object. A snapshot field matching the composed card
+ *   means "the effective posture is what the repo says it should be" — it does
+ *   NOT mean "publishing this snapshot would reproduce the live card". A
+ *   stricter scope upstream (org / team / platform floor) can raise the composed
+ *   mode above whatever the agent-scope card asks for.
+ */
+/**
+ * Fields on the canonical card that are re-derived on every compose and
+ * therefore carry no posture meaning. Comparing them would make any drift check
+ * permanently red.
+ *
+ *   - `card_version`: `compose.ts` sets it to
+ *     `protection/${new Date().toISOString().slice(0, 10)}` — a wall-clock stamp
+ *     of the LAST COMPOSE, not a semantic version. It changes whenever anything
+ *     recomposes, and never changes while the card sits untouched.
+ *   - `content_hash` / `composed_at` / `agent_protection_card_id` /
+ *     `updated_at` / `created_at` / `needs_recompose`: storage + provenance
+ *     bookkeeping written by the composer and the canonical-write RPC.
+ *
+ * The first version of this list was written from the composer's own field
+ * names. That was the wrong source: the list has to match what the SERIALIZER
+ * emits. A live read of `GET /v1/protection/agent/:id` on us-1 (2026-07-28)
+ * returns exactly:
+ *
+ *   mode, card_id, agent_id, issued_at, thresholds, card_version,
+ *   screen_surfaces, trusted_sources, protected_surface, _composition,
+ *   content_hash, version
+ *
+ * so `composed_at`, `created_at`, `updated_at`, `needs_recompose` and
+ * `agent_protection_card_id` never appear at all (kept below anyway — harmless,
+ * and they do appear on the raw DB row some callers pass in), while four
+ * derived fields the serializer DOES emit were missing: `card_id` (the
+ * server-stamped canonical id, provenance `kind: server_stamped`), `issued_at`
+ * (a compose-time stamp), `_composition` (the whole provenance envelope,
+ * `layer: derived` throughout, and itself containing `_composition.composed_at`)
+ * and `version` (the serializer's envelope version, not a posture field).
+ * Without them `--strict` reports four permanent `unrecorded` holes that no
+ * snapshot can ever close, which is precisely the state that would make an
+ * operator stop trusting the check.
+ *
+ * KNOWN COST of ignoring `version`: it is the serializer's envelope version, so
+ * a schema bump (2 → 3) passes silently here. That is the intended trade — a
+ * serializer version is not a posture claim, and an envelope change that alters
+ * a posture field will still surface as a mismatch or an unrecorded field. If
+ * the envelope version ever starts carrying posture semantics, drop it from
+ * this list.
+ */
+export const VOLATILE_FIELDS = [
+    "_composition",
+    "agent_protection_card_id",
+    "card_id",
+    "card_version",
+    "composed_at",
+    "content_hash",
+    "created_at",
+    "issued_at",
+    "needs_recompose",
+    "updated_at",
+    "version",
+];
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Structural equality good enough for card values (scalars, arrays, nested objects). */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ka = Object.keys(a).sort();
+        const kb = Object.keys(b).sort();
+        return ka.length === kb.length && ka.every((k, i) => k === kb[i] && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Recurse into nested objects so a one-surface flip reports as
+ * `screen_surfaces.tool_calls` rather than dumping both whole objects.
+ * Keys the live side has but the snapshot does not, BELOW the top level, are
+ * reported as nested `unrecorded` paths (same coverage-hole semantics).
+ */
+function walk(committed, live, prefix, out) {
+    for (const key of Object.keys(committed)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (!prefix && VOLATILE_FIELDS.includes(key)) {
+            out.ignored.push(path);
+            continue;
+        }
+        const c = committed[key];
+        const l = live[key];
+        if (!(key in live)) {
+            out.missingLive.push(path);
+            continue;
+        }
+        if (isPlainObject(c) && isPlainObject(l)) {
+            walk(c, l, path, out);
+            continue;
+        }
+        if (!deepEqual(c, l)) {
+            out.mismatches.push({ path, committed: c, live: l });
+        }
+    }
+    for (const key of Object.keys(live)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (!prefix && VOLATILE_FIELDS.includes(key)) {
+            if (!out.ignored.includes(path))
+                out.ignored.push(path);
+            continue;
+        }
+        if (!(key in committed))
+            out.unrecorded.push(path);
+    }
+}
+/**
+ * Compare a committed snapshot against the live canonical card.
+ *
+ * Pure: no I/O, no clock, no env. Both arguments are already-parsed objects.
+ */
+export function compareProtectionCards(committed, live) {
+    const out = { mismatches: [], unrecorded: [], missingLive: [], ignored: [] };
+    walk(committed, live, "", out);
+    out.mismatches.sort((a, b) => a.path.localeCompare(b.path));
+    out.unrecorded.sort();
+    out.missingLive.sort();
+    out.ignored.sort();
+    return out;
+}
+/**
+ * Policy: does this result fail the check?
+ *
+ * `mismatches` and `missingLive` always fail — the repo says one thing and the
+ * live posture is another. `unrecorded` is a coverage gap: reported by default,
+ * fatal only under `--strict`, so the check can go green today on a partial
+ * snapshot while still surfacing exactly which parts of the live posture remain
+ * unversioned. See `cards/README.md`.
+ */
+export function isDrift(result, opts = {}) {
+    if (result.mismatches.length > 0 || result.missingLive.length > 0)
+        return true;
+    return opts.strict === true && result.unrecorded.length > 0;
+}
+/** Human-readable multi-line report. Returned, not printed, so it is testable. */
+export function formatDriftReport(result, opts = {}) {
+    const lines = [];
+    for (const m of result.mismatches) {
+        lines.push(`MISMATCH  ${m.path}: committed=${JSON.stringify(m.committed)} live=${JSON.stringify(m.live)}`);
+    }
+    for (const p of result.missingLive) {
+        lines.push(`MISSING   ${p}: declared in the committed snapshot, absent from the live card`);
+    }
+    for (const p of result.unrecorded) {
+        const tag = opts.strict === true ? "UNRECORDED" : "unrecorded";
+        lines.push(`${tag.padEnd(9)} ${p}: present on the live card, not represented in the snapshot`);
+    }
+    if (result.ignored.length > 0) {
+        lines.push(`ignored   volatile/derived fields: ${result.ignored.join(", ")}`);
+    }
+    if (lines.length === 0)
+        lines.push("no differences");
+    return lines.join("\n");
+}

package/dist/lib/skills.js

@@ -42,23 +42,36 @@ export const SKILLS = [
     },
     {
         name: "onboard",
-        status: "planned",
-        ref: "MNE-933",
-        summary: "Self-onboard the calling agent end-to-end (scan → claim → declare → badge).",
-        usage: "mnemom onboard",
+        status: "available",
+        summary: "Self-onboard the calling agent end-to-end (scan → claim → declare → rating → badge).",
+        usage: "mnemom onboard [--agent <id>] [--key <key>] [--hash-proof <hex>] [--yes] [--json] [--no-open]",
         description: "Runs the sovereignty path for the calling agent itself: scan its trust posture, " +
-            "claim its identity, declare an alignment card, and earn a verifiable Trust Rating — " +
-            "one command, no manifest. Planned (MNE-933).",
+            "claim its identity (as its own device-grant principal), declare a starter alignment " +
+            "card, and surface a Trust Rating + public badge URL — one command, no manifest. " +
+            "The Trust Rating is provisional until the observer pipeline generates traces (the " +
+            "signed rating + rendered badge are computed server-side, post-hoc). Idempotent: " +
+            "re-running skips an already-claimed identity and replays an unchanged card.",
+        examples: [
+            "npx @mnemom/mnemom@latest onboard",
+            "mnemom onboard --json",
+            "mnemom onboard --agent mnm-... --key <agent-api-key>",
+        ],
     },
     {
         name: "wrap",
-        status: "planned",
-        ref: "MNE-935",
+        status: "available",
         summary: "Instrument an existing production agent through the Mnemom gateway.",
-        usage: "mnemom wrap",
-        description: "Points an existing agent's provider calls at the Mnemom gateway, claims/births its " +
-            "identity, and seeds starter alignment + protection cards — bring-your-own-agent " +
-            "onboarding. Planned (MNE-935).",
+        usage: "mnemom wrap [--provider <anthropic|openai|gemini>] [--framework <python|node>] " +
+            "[--name <name>] [--provider-key <key>] [--yes] [--json]",
+        description: "Points an existing agent's provider calls at the Mnemom gateway " +
+            "(`gateway.mnemom.ai/<provider>` + `x-mnemom-agent` header), births its identity, " +
+            "and seeds starter alignment + protection cards — bring-your-own-agent onboarding. " +
+            "Emits a drop-in code snippet for your provider SDK and next-step claim instructions.",
+        examples: [
+            "npx @mnemom/mnemom@latest wrap",
+            "mnemom wrap --provider anthropic --framework python --name my-agent",
+            "mnemom wrap --json",
+        ],
     },
 ];
 /** All registered skills, in registry order. */

package/dist/lib/version-gate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimum-CLI-version enforcement.
+ *
+ * The Mnemom API advertises the lowest fully-supported CLI version on every
+ * response via the `X-Mnemom-Min-CLI` header (mnemom-api MIN_CLI_VERSION). This
+ * module reads that header off any API response and, if THIS CLI is below the
+ * floor, prints a loud upgrade instruction and hard-exits.
+ *
+ * Why hard-fail: an outdated CLI can silently drop request fields a newer server
+ * expects and produce a wrong-but-successful result with no error. The canonical
+ * case that motivated this: a CLI predating claim-to-org (ADR-062) accepted
+ * `--org` but never sent `org_id`, so `agents claim … --org <slug>` cheerfully
+ * landed the agent in the caller's personal org. Failing loudly beats a silent
+ * wrong outcome.
+ */
+/**
+ * Compare dotted numeric versions. Returns true iff `current` is strictly below
+ * `floor`. Prerelease/build suffixes (after `-` or `+`) are ignored — the floor
+ * is expressed as a plain release, and a prerelease of that release is treated
+ * as the release for gating purposes (we don't block `-rc` builds of a good ver).
+ */
+export declare function isBelowVersion(current: string, floor: string): boolean;
+/**
+ * Enforce the server-advertised minimum CLI version against `response`.
+ * No-op when the header is absent (older server, or a non-API response) or when
+ * this CLI is at/above the floor. Otherwise writes a clear message to stderr and
+ * exits with code 1.
+ *
+ * @param exit  injectable for tests; defaults to process.exit
+ * @param write injectable for tests; defaults to process.stderr.write
+ */
+export declare function enforceMinCliVersion(response: Pick<Response, "headers">, exit?: (code: number) => never, write?: (chunk: string) => void): void;
+/**
+ * Drop-in wrapper around global fetch for Mnemom API calls: issues the request,
+ * enforces the advertised minimum CLI version on the response, then returns it.
+ */
+export declare function mnemomFetch(input: string | URL, init?: RequestInit): Promise<Response>;

package/dist/lib/version-gate.js

@@ -0,0 +1,84 @@
+/**
+ * Minimum-CLI-version enforcement.
+ *
+ * The Mnemom API advertises the lowest fully-supported CLI version on every
+ * response via the `X-Mnemom-Min-CLI` header (mnemom-api MIN_CLI_VERSION). This
+ * module reads that header off any API response and, if THIS CLI is below the
+ * floor, prints a loud upgrade instruction and hard-exits.
+ *
+ * Why hard-fail: an outdated CLI can silently drop request fields a newer server
+ * expects and produce a wrong-but-successful result with no error. The canonical
+ * case that motivated this: a CLI predating claim-to-org (ADR-062) accepted
+ * `--org` but never sent `org_id`, so `agents claim … --org <slug>` cheerfully
+ * landed the agent in the caller's personal org. Failing loudly beats a silent
+ * wrong outcome.
+ */
+import { CLI_VERSION } from "../version.js";
+const MIN_CLI_HEADER = "x-mnemom-min-cli";
+/**
+ * Compare dotted numeric versions. Returns true iff `current` is strictly below
+ * `floor`. Prerelease/build suffixes (after `-` or `+`) are ignored — the floor
+ * is expressed as a plain release, and a prerelease of that release is treated
+ * as the release for gating purposes (we don't block `-rc` builds of a good ver).
+ */
+export function isBelowVersion(current, floor) {
+    const parse = (v) => v
+        .trim()
+        .split(/[-+]/)[0]
+        .split(".")
+        .map((n) => {
+        const parsed = Number.parseInt(n, 10);
+        return Number.isNaN(parsed) ? 0 : parsed;
+    });
+    const c = parse(current);
+    const f = parse(floor);
+    const len = Math.max(c.length, f.length);
+    for (let i = 0; i < len; i++) {
+        const cv = c[i] ?? 0;
+        const fv = f[i] ?? 0;
+        if (cv < fv)
+            return true;
+        if (cv > fv)
+            return false;
+    }
+    return false; // equal → supported
+}
+// Guard so a command issuing several requests exits exactly once.
+let exited = false;
+/**
+ * Enforce the server-advertised minimum CLI version against `response`.
+ * No-op when the header is absent (older server, or a non-API response) or when
+ * this CLI is at/above the floor. Otherwise writes a clear message to stderr and
+ * exits with code 1.
+ *
+ * @param exit  injectable for tests; defaults to process.exit
+ * @param write injectable for tests; defaults to process.stderr.write
+ */
+export function enforceMinCliVersion(response, exit = process.exit, write = (chunk) => void process.stderr.write(chunk)) {
+    // Defensive: some callers/tests provide a Response-like object without a real
+    // Headers instance. Treat a missing/incompatible headers bag as "no floor".
+    const headers = response?.headers;
+    const floor = typeof headers?.get === "function" ? headers.get(MIN_CLI_HEADER) : null;
+    if (!floor)
+        return;
+    if (!isBelowVersion(CLI_VERSION, floor))
+        return;
+    if (exited)
+        return;
+    exited = true;
+    write(`\n✖ Your Mnemom CLI (v${CLI_VERSION}) is too old for this server (minimum v${floor}).\n` +
+        `  Old CLIs can silently drop newer request fields — e.g. \`--org\` on \`mnemom agents claim\`.\n\n` +
+        `  Upgrade:  npm i -g @mnemom/mnemom@latest\n\n`);
+    exit(1);
+}
+/**
+ * Drop-in wrapper around global fetch for Mnemom API calls: issues the request,
+ * enforces the advertised minimum CLI version on the response, then returns it.
+ */
+export async function mnemomFetch(input, init) {
+    // Preserve the exact call shape: fetch(input) when no init, so callers and
+    // tests that assert a single-arg fetch stay valid.
+    const response = init === undefined ? await fetch(input) : await fetch(input, init);
+    enforceMinCliVersion(response);
+    return response;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
     "smoltbot": "./dist/smoltbot-shim.js"
   },
   "scripts": {
-    "build": "npm install && npm install --prefix ../shared/policy-engine && npm run build --prefix ../shared/policy-engine && tsc",
+    "build": "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",
@@ -19,15 +19,15 @@
     "@mnemom/policy-engine": "^0.3.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "^4.3.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",
-    "@vitest/coverage-v8": "^1.6.1",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.0"
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "files": [
     "dist",