@mnemom/mnemom 0.16.1 → 0.16.3

package/dist/lib/auth.js

@@ -117,7 +117,14 @@ export async function getAccessToken() {
     if (auth.expiresAt > now + 60) {
         return auth.accessToken;
     }
-    // Auto-refresh
+    // Auto-refresh. A *thrown* error from refreshStoredTokens() (transient
+    // exhaustion / non-revoke 4xx from oauthRefreshTokens(), MNE-7394) is
+    // intentionally allowed to propagate here rather than being coerced to the
+    // `null` re-login signal — a momentary AS outage must not masquerade as
+    // "credentials revoked". Only a genuine invalid_grant/invalid_client returns
+    // null (see refreshStoredTokens). Refining caller-side handling (distinguish
+    // propagate-vs-degrade) is tracked under MNE-7394's parent lane card
+    // (keith/oauth-token-lifetime).
     const refreshed = await refreshStoredTokens(auth);
     if (refreshed)
         return refreshed.accessToken;
@@ -139,6 +146,9 @@ export async function forceRefreshAccessToken() {
     const auth = getAuthInfo();
     if (!auth?.refreshToken)
         return null;
+    // As in getAccessToken, a thrown transient-exhaustion / non-revoke error from
+    // refreshStoredTokens() propagates rather than being coerced to null (MNE-7394;
+    // caller-side refinement tracked under keith/oauth-token-lifetime).
     const refreshed = await refreshStoredTokens(auth);
     return refreshed?.accessToken ?? null;
 }
@@ -226,6 +236,16 @@ export async function loginWithDeviceFlow() {
  * Refresh the stored tokens via the OAuth refresh_token grant. Requires both a
  * refresh token and the client_id they were issued to; returns null (rather
  * than throwing) when refresh isn't possible so callers degrade to re-login.
+ *
+ * Note: oauthRefreshTokens() returns null ONLY on a definitive revoke
+ * (invalid_grant/invalid_client) or missing credentials; on transient
+ * exhaustion (repeated 5xx / network faults) or any other non-revoke 4xx it
+ * *throws* (MNE-7394 / R6). That thrown error is intentionally allowed to
+ * propagate through this function to its callers rather than being coerced to
+ * null, so a momentary blip never presents as "credentials revoked". Refining
+ * the caller-side handling (propagate-vs-degrade in
+ * getAccessToken/forceRefreshAccessToken) is tracked under MNE-7394's parent
+ * lane card (keith/oauth-token-lifetime).
  */
 async function refreshStoredTokens(auth) {
     if (!auth.refreshToken || !auth.clientId)

package/dist/lib/cli-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Persistent CLI preference store — ~/.mnemom/config.json.
+ *
+ * Deliberately SEPARATE from auth.ts → auth.json: auth.json holds bearer
+ * credentials and is wiped on logout; config.json holds preferences that
+ * survive re-login. Today it holds one preference: the ACTIVE ORG.
+ *
+ * Why an active org exists at all: `mnemom login` binds no org — the OAuth
+ * token carries only scope + expiry (see lib/auth.ts), so every org-scoped
+ * command historically needed an explicit `--org` or silently defaulted to
+ * the caller's personal org (the "why did my agent land in Personal?"
+ * footgun). `mnemom org use <slug>` records a durable default; commands
+ * resolve org as: explicit flag > active org > loud personal-org fallback.
+ *
+ * The stored value is the VALIDATED membership snapshot ({org_id, slug,
+ * name}) so consumers can send org_id without a per-command round-trip.
+ * Membership can change after it's stored — consumers must treat a server
+ * 403 as the truth (the claim path already renders the teaching list).
+ */
+export interface ActiveOrg {
+    org_id: string;
+    slug: string;
+    name: string;
+}
+export interface CliConfig {
+    activeOrg?: ActiveOrg;
+}
+/** Load the config; a missing or corrupt file degrades to `{}`. */
+export declare function loadCliConfig(): CliConfig;
+/** Persist (or with `null`, clear) the active org. */
+export declare function setActiveOrg(org: ActiveOrg | null): void;
+/** The active org, or undefined when none is set. */
+export declare function getActiveOrg(): ActiveOrg | undefined;

package/dist/lib/cli-config.js

@@ -0,0 +1,70 @@
+/**
+ * Persistent CLI preference store — ~/.mnemom/config.json.
+ *
+ * Deliberately SEPARATE from auth.ts → auth.json: auth.json holds bearer
+ * credentials and is wiped on logout; config.json holds preferences that
+ * survive re-login. Today it holds one preference: the ACTIVE ORG.
+ *
+ * Why an active org exists at all: `mnemom login` binds no org — the OAuth
+ * token carries only scope + expiry (see lib/auth.ts), so every org-scoped
+ * command historically needed an explicit `--org` or silently defaulted to
+ * the caller's personal org (the "why did my agent land in Personal?"
+ * footgun). `mnemom org use <slug>` records a durable default; commands
+ * resolve org as: explicit flag > active org > loud personal-org fallback.
+ *
+ * The stored value is the VALIDATED membership snapshot ({org_id, slug,
+ * name}) so consumers can send org_id without a per-command round-trip.
+ * Membership can change after it's stored — consumers must treat a server
+ * 403 as the truth (the claim path already renders the teaching list).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MNEMOM_DIR } from "./config.js";
+function configFile() {
+    return path.join(MNEMOM_DIR, "config.json");
+}
+/** Load the config; a missing or corrupt file degrades to `{}`. */
+export function loadCliConfig() {
+    try {
+        if (!fs.existsSync(configFile()))
+            return {};
+        const parsed = JSON.parse(fs.readFileSync(configFile(), "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function saveCliConfig(config) {
+    if (!fs.existsSync(MNEMOM_DIR)) {
+        // 0700 to match the auth store — the directory also holds credentials.
+        fs.mkdirSync(MNEMOM_DIR, { recursive: true, mode: 0o700 });
+    }
+    const resolvedPath = path.resolve(configFile());
+    const tmpFile = `${resolvedPath}.${process.pid}.tmp`;
+    // No secrets in here, but keep the same owner-only posture as auth.json —
+    // the active org is still account metadata. Write-then-rename = atomic.
+    fs.writeFileSync(tmpFile, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        fs.chmodSync(tmpFile, 0o600);
+    }
+    catch {
+        /* best effort on platforms without POSIX perms */
+    }
+    fs.renameSync(tmpFile, resolvedPath);
+}
+/** Persist (or with `null`, clear) the active org. */
+export function setActiveOrg(org) {
+    const config = loadCliConfig();
+    if (org === null) {
+        delete config.activeOrg;
+    }
+    else {
+        config.activeOrg = org;
+    }
+    saveCliConfig(config);
+}
+/** The active org, or undefined when none is set. */
+export function getActiveOrg() {
+    return loadCliConfig().activeOrg;
+}

package/dist/lib/config.d.ts

@@ -13,6 +13,18 @@ export type Environment = "production" | "staging" | "local";
  * Defaults to production.
  */
 export declare function getEnvironment(): Environment;
+export type CellRing = "us-1";
+/** Explicitly select a ring for this process (clears on undefined). Wins over MNEMOM_RING. */
+export declare function setRing(ring: CellRing | undefined): void;
+/**
+ * Resolve the active ring, if any: an explicit `setRing()` call wins over
+ * the `MNEMOM_RING` env var. Returns undefined for an unset or unrecognized
+ * value — an unknown ring name is deliberately NOT resolved to production;
+ * callers fall through to the existing Environment-based URLs instead.
+ */
+export declare function getRing(): CellRing | undefined;
+/** Override the active API base for this process (clears on undefined/empty). */
+export declare function setApiUrlOverride(url: string | undefined): void;
 export declare function getApiUrl(): string;
 export declare function getGatewayUrl(): string;
 export declare function getWebsiteUrl(): string;

package/dist/lib/config.js

@@ -34,12 +34,64 @@ export function getEnvironment() {
         return env;
     return "production";
 }
+const RING_URLS = {
+    "us-1": {
+        api: "https://api-us1.mnemom.ai",
+        gateway: "https://gateway-us1.mnemom.ai",
+        website: "https://preview.mnemom.ai",
+    },
+};
+function isCellRing(value) {
+    return Object.prototype.hasOwnProperty.call(RING_URLS, value);
+}
+let ringOverride;
+/** Explicitly select a ring for this process (clears on undefined). Wins over MNEMOM_RING. */
+export function setRing(ring) {
+    ringOverride = ring;
+}
+/**
+ * Resolve the active ring, if any: an explicit `setRing()` call wins over
+ * the `MNEMOM_RING` env var. Returns undefined for an unset or unrecognized
+ * value — an unknown ring name is deliberately NOT resolved to production;
+ * callers fall through to the existing Environment-based URLs instead.
+ */
+export function getRing() {
+    if (ringOverride)
+        return ringOverride;
+    const env = process.env.MNEMOM_RING?.trim();
+    return env && isCellRing(env) ? env : undefined;
+}
+// Process-level base overrides. MNEMOM_ENV only selects prod/staging/local;
+// to target an arbitrary ring (preview/us-1, test) a command can set an
+// explicit override (e.g. `try-me --api <ring>`) or the operator can export
+// MNEMOM_API_URL / MNEMOM_GATEWAY_URL / MNEMOM_WEBSITE_URL. Crucially these
+// flow through EVERY surface — including OAuth discovery + the one-click claim
+// login — so a non-prod ring's sign-in no longer falls back to the prod AS.
+//
+// Precedence (highest wins): apiUrlOverride > raw MNEMOM_*_URL env >
+// ring (setRing()/MNEMOM_RING) > Environment table. A ring only fills the
+// gap the raw overrides leave — it never has to be perfectly bypass-able,
+// because the raw overrides above it in the chain always can.
+let apiUrlOverride;
+/** Override the active API base for this process (clears on undefined/empty). */
+export function setApiUrlOverride(url) {
+    const trimmed = url?.trim().replace(/\/+$/, "");
+    apiUrlOverride = trimmed || undefined;
+}
+function envBase(name) {
+    const v = process.env[name]?.trim();
+    return v ? v.replace(/\/+$/, "") : undefined;
+}
+function ringUrls() {
+    const ring = getRing();
+    return ring ? RING_URLS[ring] : undefined;
+}
 export function getApiUrl() {
-    return API_URLS[getEnvironment()];
+    return (apiUrlOverride ?? envBase("MNEMOM_API_URL") ?? ringUrls()?.api ?? API_URLS[getEnvironment()]);
 }
 export function getGatewayUrl() {
-    return GATEWAY_URLS[getEnvironment()];
+    return envBase("MNEMOM_GATEWAY_URL") ?? ringUrls()?.gateway ?? GATEWAY_URLS[getEnvironment()];
 }
 export function getWebsiteUrl() {
-    return WEBSITE_URLS[getEnvironment()];
+    return envBase("MNEMOM_WEBSITE_URL") ?? ringUrls()?.website ?? WEBSITE_URLS[getEnvironment()];
 }

package/dist/lib/keyed-identity.d.ts

@@ -0,0 +1,35 @@
+import { type ValidationCheck } from "../commands/protection.js";
+export declare const KEYED_MODES: readonly ["observe", "nudge", "enforce"];
+export type KeyedMode = (typeof KEYED_MODES)[number];
+export declare const EVAL_BATTERY_MODEL: "claude-opus-5";
+export interface KeyedModeEntry {
+    label?: unknown;
+    mode?: unknown;
+    model?: unknown;
+    agent_id?: unknown;
+    agent_hash?: unknown;
+    secret_ref?: unknown;
+    snapshot?: unknown;
+}
+export interface KeyedDirectLane {
+    label?: unknown;
+    mode?: unknown;
+    path?: unknown;
+    secret_ref?: unknown;
+    model?: unknown;
+    snapshot?: unknown;
+    agent_id?: unknown;
+    agent_hash?: unknown;
+}
+/**
+ * Validate the keyed-mode manifest against the three parsed snapshots.
+ *
+ * @param manifest  Parsed `cards/keyed-modes.manifest.yaml` (`{ entries: [...] }`).
+ * @param snapshots Map of snapshot filename → parsed protection card, keyed by
+ *                  the `snapshot:` value each manifest entry declares.
+ * @returns Flat list of `{ name, passed, message }` checks (mirrors
+ *          ValidationCheck) so callers can render/aggregate. A returned list
+ *          with every `passed === true` means the record is internally
+ *          consistent; any `passed === false` is a failing invariant.
+ */
+export declare function validateKeyedModeManifest(manifest: Record<string, unknown>, snapshots: Record<string, Record<string, unknown>>): ValidationCheck[];

package/dist/lib/keyed-identity.js

@@ -0,0 +1,363 @@
+// ============================================================================
+// Keyed-mode identity manifest validator (issue #1429 / MNE-5522)
+//
+// Pure, I/O-free validator for the three-mode keyed-identity record: the
+// `cards/keyed-modes.manifest.yaml` binding plus the three protection-card
+// snapshots it references. It asserts the CROSS-ENTRY invariant — exactly the
+// three modes {observe, nudge, enforce}, one each, distinct identities, each
+// snapshot valid and matching the manifest — and REUSES `validateProtectionCard`
+// (cli/src/commands/protection.ts) for per-card ADR-037 validation rather than
+// re-implementing card rules (MNE-437: no logic-bearing duplication).
+//
+// No I/O, no process.exit: callers read the returned ValidationCheck[] and
+// render/aggregate. This is the deterministic guard exercised by the manifest
+// `test` verb (cli vitest): against inline fixtures AND against the real
+// committed cards/ files (the on-disk integration test in
+// cli/src/__tests__/keyed-identity.test.ts).
+// ============================================================================
+import { validateProtectionCard } from "../commands/protection.js";
+// The three enforcement modes a keyed identity may be pinned to. `off` is a
+// valid protection-card mode but NOT a keyed-mode target — a keyed identity
+// exists precisely to exercise one of the three ACTIVE modes side-by-side.
+export const KEYED_MODES = ["observe", "nudge", "enforce"];
+// The evaluation-battery model, pinned as ONE config fact (issue #1460 / D13 /
+// MNE-5707). This is the compile-time mirror of the AUTHORITATIVE `model:` field
+// in cards/keyed-modes.manifest.yaml — the manifest is the single source of
+// truth; this constant lets the validator (and its drift-guard test) assert the
+// manifest has not silently diverged from the value the codebase expects.
+// Holding the model fixed across all four lanes is what keeps the downstream
+// cost probe valid; a changed model invalidates it. Re-opening the model choice
+// is OUT of scope (MNE-5707).
+export const EVAL_BATTERY_MODEL = "claude-opus-5";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Validate the keyed-mode manifest against the three parsed snapshots.
+ *
+ * @param manifest  Parsed `cards/keyed-modes.manifest.yaml` (`{ entries: [...] }`).
+ * @param snapshots Map of snapshot filename → parsed protection card, keyed by
+ *                  the `snapshot:` value each manifest entry declares.
+ * @returns Flat list of `{ name, passed, message }` checks (mirrors
+ *          ValidationCheck) so callers can render/aggregate. A returned list
+ *          with every `passed === true` means the record is internally
+ *          consistent; any `passed === false` is a failing invariant.
+ */
+export function validateKeyedModeManifest(manifest, snapshots) {
+    const checks = [];
+    const rawEntries = manifest.entries;
+    if (!Array.isArray(rawEntries)) {
+        checks.push({
+            name: "manifest.entries",
+            passed: false,
+            message: "Required: manifest must have an `entries` array (one object per keyed identity).",
+        });
+        return checks;
+    }
+    const entries = rawEntries;
+    // ── Pinned battery model: one authoritative config fact, no lane divergence ──
+    // `manifest.model` must be present, a string, and equal to the codebase's
+    // EVAL_BATTERY_MODEL mirror; any entry declaring its OWN `model` must match it
+    // (a divergent per-lane model would invalidate the cost probe — MNE-440).
+    checks.push(...modelConsistencyChecks(manifest, entries));
+    // ── Per-snapshot ADR-037 validation (reuse validateProtectionCard) ──
+    // Each entry references a snapshot by filename; validate the referenced card.
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        const snapshotName = entry.snapshot;
+        if (typeof snapshotName !== "string" || snapshotName.length === 0) {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: false,
+                message: "Required: entry must reference a snapshot filename (string).",
+            });
+            continue;
+        }
+        const card = snapshots[snapshotName];
+        if (!isObject(card)) {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: false,
+                message: `Snapshot "${snapshotName}" was not provided (or did not parse to an object).`,
+            });
+            continue;
+        }
+        const cardChecks = validateProtectionCard(card);
+        const failed = cardChecks.filter((c) => !c.passed);
+        if (failed.length > 0) {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: false,
+                message: `Snapshot "${snapshotName}" is not a valid protection card: ${failed
+                    .map((f) => `${f.name}: ${f.message}`)
+                    .join("; ")}`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: true,
+                message: `${snapshotName} is a valid protection card`,
+            });
+        }
+    }
+    // ── Mode coverage: exactly {observe, nudge, enforce}, one each ──
+    const modeCounts = new Map();
+    for (const entry of entries) {
+        if (typeof entry.mode === "string") {
+            modeCounts.set(entry.mode, (modeCounts.get(entry.mode) ?? 0) + 1);
+        }
+    }
+    const missing = KEYED_MODES.filter((m) => !modeCounts.has(m));
+    const duplicated = KEYED_MODES.filter((m) => (modeCounts.get(m) ?? 0) > 1);
+    const unexpected = [...modeCounts.keys()].filter((m) => !KEYED_MODES.includes(m));
+    if (missing.length === 0 && duplicated.length === 0 && unexpected.length === 0) {
+        checks.push({
+            name: "modes.coverage",
+            passed: true,
+            message: `covers exactly ${KEYED_MODES.join(", ")}, one each`,
+        });
+    }
+    else {
+        const problems = [];
+        if (missing.length > 0)
+            problems.push(`missing: ${missing.join(", ")}`);
+        if (duplicated.length > 0)
+            problems.push(`duplicated: ${duplicated.join(", ")}`);
+        if (unexpected.length > 0)
+            problems.push(`unexpected: ${unexpected.join(", ")}`);
+        checks.push({
+            name: "modes.coverage",
+            passed: false,
+            message: `Must cover exactly ${KEYED_MODES.join(", ")}, one each. ${problems.join("; ")}.`,
+        });
+    }
+    // ── Distinct agent_id across entries ──
+    checks.push(distinctnessCheck(entries, "agent_id"));
+    // ── Distinct agent_hash across entries ──
+    checks.push(distinctnessCheck(entries, "agent_hash"));
+    // ── Each entry's mode equals its referenced snapshot's mode ──
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        const snapshotName = entry.snapshot;
+        if (typeof snapshotName !== "string")
+            continue; // already reported above
+        const card = snapshots[snapshotName];
+        if (!isObject(card))
+            continue; // already reported above
+        if (entry.mode !== card.mode) {
+            checks.push({
+                name: `${label}.mode`,
+                passed: false,
+                message: `Manifest mode "${String(entry.mode)}" does not match snapshot "${snapshotName}" mode "${String(card.mode)}".`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.mode`,
+                passed: true,
+                message: `mode "${String(entry.mode)}" matches snapshot`,
+            });
+        }
+    }
+    // ── Each entry's agent_id matches its referenced snapshot's agent_id ──
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        const snapshotName = entry.snapshot;
+        if (typeof snapshotName !== "string")
+            continue; // already reported above
+        const card = snapshots[snapshotName];
+        if (!isObject(card))
+            continue; // already reported above
+        if (entry.agent_id !== card.agent_id) {
+            checks.push({
+                name: `${label}.agent_id`,
+                passed: false,
+                message: `Manifest agent_id "${String(entry.agent_id)}" does not match snapshot "${snapshotName}" agent_id "${String(card.agent_id)}".`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.agent_id`,
+                passed: true,
+                message: `agent_id "${String(entry.agent_id)}" matches snapshot`,
+            });
+        }
+    }
+    // ── Direct (true-off) calibration lane shape ──
+    checks.push(...validateDirectLane(manifest, entries));
+    return checks;
+}
+/**
+ * Model-consistency checks: the manifest pins one authoritative `model`, and no
+ * entry may declare a divergent per-lane `model`. Returns one `model.pinned`
+ * check plus, for any entry that declares its own `model`, one per-entry check.
+ */
+function modelConsistencyChecks(manifest, entries) {
+    const checks = [];
+    const model = manifest.model;
+    if (typeof model !== "string" || model.length === 0) {
+        checks.push({
+            name: "model.pinned",
+            passed: false,
+            message: "Required: manifest must pin `model` (a non-empty string) — the single evaluation-battery model held fixed across all lanes.",
+        });
+        return checks;
+    }
+    if (model !== EVAL_BATTERY_MODEL) {
+        checks.push({
+            name: "model.pinned",
+            passed: false,
+            message: `Manifest model "${model}" does not equal EVAL_BATTERY_MODEL "${EVAL_BATTERY_MODEL}". The pinned battery model must not silently diverge (MNE-5707).`,
+        });
+    }
+    else {
+        checks.push({
+            name: "model.pinned",
+            passed: true,
+            message: `model pinned to "${model}" (matches EVAL_BATTERY_MODEL)`,
+        });
+    }
+    // Any entry that declares its own `model` must match the authoritative value.
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.model === undefined)
+            continue; // no per-lane override (the norm)
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        if (entry.model !== model) {
+            checks.push({
+                name: `${label}.model`,
+                passed: false,
+                message: `Entry model "${String(entry.model)}" diverges from the pinned manifest model "${model}". All lanes must use the identical model (MNE-440).`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.model`,
+                passed: true,
+                message: `entry model matches the pinned "${model}"`,
+            });
+        }
+    }
+    return checks;
+}
+/**
+ * Validate the fourth, DIRECT (true-off) calibration lane. It is a distinct
+ * top-level section, kept OUT of the three-mode `entries` coverage count. Asserts
+ * it declares exactly the direct-lane shape (`mode: off`, `path: direct`, a
+ * non-empty `secret_ref` distinct from every entry's) and declares NONE of the
+ * gateway-only fields (`snapshot`/`agent_id`/`agent_hash`) nor a per-lane `model`
+ * — the direct lane never touches the gateway, so any of those would be
+ * misleading dead config (MNE-440).
+ */
+function validateDirectLane(manifest, entries) {
+    const checks = [];
+    const raw = manifest.direct_lane;
+    if (!isObject(raw)) {
+        checks.push({
+            name: "direct_lane",
+            passed: false,
+            message: "Required: manifest must declare a `direct_lane` object (the true-off calibration path that bypasses the gateway).",
+        });
+        return checks;
+    }
+    const lane = raw;
+    // mode must be exactly "off" (true-off calibration).
+    if (lane.mode !== "off") {
+        checks.push({
+            name: "direct_lane.mode",
+            passed: false,
+            message: `direct_lane.mode must be "off" (true-off calibration); got "${String(lane.mode)}".`,
+        });
+    }
+    else {
+        checks.push({ name: "direct_lane.mode", passed: true, message: 'mode "off" (true-off)' });
+    }
+    // path must be exactly "direct".
+    if (lane.path !== "direct") {
+        checks.push({
+            name: "direct_lane.path",
+            passed: false,
+            message: `direct_lane.path must be "direct" (it bypasses the gateway); got "${String(lane.path)}".`,
+        });
+    }
+    else {
+        checks.push({ name: "direct_lane.path", passed: true, message: 'path "direct"' });
+    }
+    // secret_ref must be a non-empty string, distinct from every entry's.
+    if (typeof lane.secret_ref !== "string" || lane.secret_ref.length === 0) {
+        checks.push({
+            name: "direct_lane.secret_ref",
+            passed: false,
+            message: "direct_lane.secret_ref must be a non-empty string (secret-store reference name).",
+        });
+    }
+    else {
+        const entryRefs = new Set(entries.map((e) => e.secret_ref).filter((r) => typeof r === "string"));
+        if (entryRefs.has(lane.secret_ref)) {
+            checks.push({
+                name: "direct_lane.secret_ref",
+                passed: false,
+                message: `direct_lane.secret_ref "${lane.secret_ref}" must be distinct from every entry's secret_ref (the direct lane uses its own provider key).`,
+            });
+        }
+        else {
+            checks.push({
+                name: "direct_lane.secret_ref",
+                passed: true,
+                message: `secret_ref "${lane.secret_ref}" is distinct from all entry secret_refs`,
+            });
+        }
+    }
+    // Forbidden gateway-only / per-lane fields: declaring any is misleading dead
+    // config, because the direct lane never traverses the gateway (MNE-440).
+    const forbidden = ["snapshot", "agent_id", "agent_hash", "model"].filter((f) => lane[f] !== undefined);
+    if (forbidden.length > 0) {
+        checks.push({
+            name: "direct_lane.forbidden_fields",
+            passed: false,
+            message: `direct_lane must NOT declare ${forbidden.join(", ")}: it never traverses the gateway (no identity/card) and uses the authoritative top-level manifest.model. Remove the field(s) to avoid misleading dead config (MNE-440).`,
+        });
+    }
+    else {
+        checks.push({
+            name: "direct_lane.forbidden_fields",
+            passed: true,
+            message: "declares no gateway-only identity/card/model fields",
+        });
+    }
+    return checks;
+}
+/** Assert a field is present and mutually distinct across all entries. */
+function distinctnessCheck(entries, field) {
+    const values = entries.map((e) => e[field]);
+    if (values.some((v) => typeof v !== "string" || v.length === 0)) {
+        return {
+            name: `${field}.distinct`,
+            passed: false,
+            message: `Every entry must declare a non-empty ${field}.`,
+        };
+    }
+    const seen = new Set();
+    const dupes = new Set();
+    for (const v of values) {
+        if (seen.has(v))
+            dupes.add(v);
+        seen.add(v);
+    }
+    if (dupes.size > 0) {
+        return {
+            name: `${field}.distinct`,
+            passed: false,
+            message: `${field} must be distinct across entries; repeated: ${[...dupes].join(", ")}.`,
+        };
+    }
+    return {
+        name: `${field}.distinct`,
+        passed: true,
+        message: `${values.length} distinct ${field} value(s)`,
+    };
+}

package/dist/lib/oauth.d.ts

@@ -105,11 +105,33 @@ export declare function loginWithDevice(opts?: {
     sleep?: (ms: number) => Promise<void>;
 }): Promise<DeviceResult>;
 /**
- * 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 declare function refreshTokens(refreshToken: string, clientId: string): Promise<OAuthTokens | null>;
+export declare function refreshTokens(refreshToken: string, clientId: string, opts?: {
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<OAuthTokens | null>;
 /**
  * Open `url` in the user's default browser WITHOUT a shell. The URL is always
  * passed as a separate argv element (never concatenated into a command string),