@mnemom/mnemom 0.17.0-next.2 → 0.17.0-next.3

package/dist/commands/code-doctor.d.ts

@@ -11,8 +11,22 @@
  * live), Remote-Control capability (node + openssl + the --remote-control flag),
  * and claude.ai login (informational — Remote Control needs it).
  */
+type Mark = "ok" | "warn" | "miss" | "info";
 export interface DoctorOptions {
     cli?: string;
 }
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
 export declare function codeDoctorCommand(options?: DoctorOptions): Promise<void>;
+export interface CodeAccessProbe {
+    mark: Mark;
+    text: string;
+    hint?: string;
+}
+/**
+ * The invited-cohort gate, as the doctor reports it. Signed out → info (we can't
+ * check without a session); enabled → ok with the reason; a determined
+ * `code_not_enabled` → MISS with the api's hint (a launch WOULD be blocked);
+ * anything inconclusive → info, never a MISS (the launch preamble fails open too).
+ */
+export declare function probeCodeAccess(): Promise<CodeAccessProbe>;
+export {};

package/dist/commands/code-doctor.js

@@ -16,6 +16,10 @@ import { existsSync } from "node:fs";
 import { anthropicKeySource, checkRcCapability, resolveCliBin, } from "./code.js";
 import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost, } from "../lib/code.js";
 import { CODE_CONFIG_PATH } from "../lib/code-config.js";
+import { getCodeEntitlement, MnemomApiError } from "../lib/api.js";
+import { isLoggedIn } from "../lib/auth.js";
+import { getActiveOrg } from "../lib/cli-config.js";
+import { isCodeNotEnabled, sourceLabel } from "./code-invite.js";
 const MARK = { ok: "[ ok ]", warn: "[warn]", miss: "[MISS]", info: "[info]" };
 const out = (line = "") => console.log(line);
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
@@ -78,6 +82,9 @@ export async function codeDoctorCommand(options = {}) {
                 add("info", "claude.ai login: could not determine");
         }
     }
+    // ── Mnemom Code access (invited cohort gate) ──
+    const gate = await probeCodeAccess();
+    add(gate.mark, gate.text, gate.hint);
     // ── render ──
     const door = resolveAnthropicDoor(env);
     out("mnemom code doctor");
@@ -136,3 +143,36 @@ function claudeLoggedIn(bin) {
         return null;
     }
 }
+/**
+ * The invited-cohort gate, as the doctor reports it. Signed out → info (we can't
+ * check without a session); enabled → ok with the reason; a determined
+ * `code_not_enabled` → MISS with the api's hint (a launch WOULD be blocked);
+ * anything inconclusive → info, never a MISS (the launch preamble fails open too).
+ */
+export async function probeCodeAccess() {
+    if (!(await isLoggedIn())) {
+        return {
+            mark: "info",
+            text: "Mnemom Code access: sign in to check",
+            hint: "run `mnemom login`; @mnemom.ai accounts are enabled by default, others need an invitation (mnemom code --invite <token>)",
+        };
+    }
+    const org = getActiveOrg();
+    const orgLabel = org ? `${org.name} (${org.slug})` : "your personal org";
+    try {
+        const ent = await getCodeEntitlement(org?.org_id);
+        return { mark: "ok", text: `Mnemom Code access: enabled for ${orgLabel} (${sourceLabel(ent.source)})` };
+    }
+    catch (err) {
+        if (isCodeNotEnabled(err)) {
+            const hint = err.details?.hint;
+            return {
+                mark: "miss",
+                text: `Mnemom Code access: not enabled for ${orgLabel}`,
+                hint: typeof hint === "string" && hint ? hint : "redeem an invitation: mnemom code --invite <token>",
+            };
+        }
+        const detail = err instanceof MnemomApiError || err instanceof Error ? err.message : String(err);
+        return { mark: "info", text: `Mnemom Code access: could not determine (${detail})` };
+    }
+}

package/dist/commands/code-invite.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Mnemom Code — the invited-cohort gate + `mnemom code --invite <token>`.
+ *
+ * `mnemom code` is open by default to Mnemom's own people (@mnemom.ai) and to
+ * customers who redeemed an invitation. The api decides
+ * (`GET /v1/code/entitlement`); this module is the CLI side of that:
+ *
+ *   - `assertCodeEnabled(orgId, orgLabel)` runs in the launch preamble (right
+ *     after sign-in, before the µ-balance check). A determined
+ *     `code_not_enabled` BLOCKS with the api's own hint; anything inconclusive
+ *     (network, 5xx, a membership 403) fails OPEN — the gate is a friendly
+ *     pre-check, the api/gateway remain the real enforcement.
+ *   - `codeInviteCommand(token)` redeems a `pinv_…` invitation
+ *     (`POST /v1/invites/accept`): signs the customer in first (creating a free
+ *     account in the same flow if needed), unlocks Mnemom Code for them, and
+ *     reports whether the starter µ landed. Backs both `mnemom code --invite
+ *     <token> [scenario]` and the `mnemom code invite <token>` sub-verb.
+ *
+ * All narration goes to stderr (the `mnemom code` convention — stdout is for
+ * the dry-run plan only). Copy says "µ", never "MU".
+ */
+import { MnemomApiError, type AcceptProductInviteResult, type CodeEntitlement } from "../lib/api.js";
+/** Thrown when the org is determined NOT enabled. The guidance is already printed
+ *  when this is thrown — callers exit quietly (same contract as MuInsufficientError). */
+export declare class CodeNotEnabledError extends Error {
+    readonly orgLabel: string;
+    constructor(orgLabel: string);
+}
+/** `pinv_` + base64url — the product-invite token shape the api mints. */
+export declare const INVITE_TOKEN_RE: RegExp;
+export declare function looksLikeInviteToken(value: unknown): value is string;
+/** Drop control characters (ANSI escapes included) from an api-supplied string before
+ *  it reaches the terminal — defense in depth; the value is first-party but printed raw. */
+export declare function sanitizeTerminalText(s: string): string;
+/** Human label for the gate's `source`. */
+export declare function sourceLabel(source: CodeEntitlement["source"]): string;
+/** The api's `code_not_enabled` 403 — the ONE case that blocks. */
+export declare function isCodeNotEnabled(err: unknown): err is MnemomApiError;
+/**
+ * Enforce the Mnemom Code gate for the org the launch targets. Blocks (prints
+ * guidance + throws CodeNotEnabledError) ONLY on a determined `code_not_enabled`;
+ * every other failure is inconclusive and fails open with a dim note.
+ */
+export declare function assertCodeEnabled(orgId: string, orgLabel: string): Promise<void>;
+/** Ensures a Mnemom session exists (injected so tests never touch the real login flow). */
+export type EnsureSession = (opts: {
+    interactive?: boolean;
+}) => Promise<boolean>;
+/** Map an accept failure to the sentence the customer needs. Null = not ours to explain. */
+export declare function explainAcceptError(err: unknown): string | null;
+/** Print the outcome of a successful accept. */
+export declare function printAccepted(res: AcceptProductInviteResult): void;
+/**
+ * `mnemom code --invite <token>` / `mnemom code invite <token>`: sign in, redeem,
+ * report. Throws with a clear message on a bad token, no session, or an accept
+ * failure the customer can act on; rethrows anything else.
+ */
+export declare function codeInviteCommand(token: string | undefined, opts?: {
+    interactive?: boolean;
+    ensureSession?: EnsureSession;
+}): Promise<AcceptProductInviteResult>;
+export declare const NO_SCENARIO_MESSAGE = "mnemom code: a <scenario> slug is required (e.g. `mnemom code onboarding`) \u2014 or redeem an invitation with `mnemom code --invite <token>`.";
+export interface CodeInvocation {
+    /** The positional `[scenario]` (may be a reserved sub-verb such as "invite"). */
+    scenario?: string;
+    /** Everything after the scenario. */
+    passthrough: string[];
+    /** `--invite <token>`. */
+    inviteFlag?: string;
+}
+export interface CodeInvocationDeps {
+    redeem: (token: string | undefined) => Promise<unknown>;
+    launch: (scenario: string) => Promise<void>;
+}
+/**
+ * How the `code` command's positional + `--invite` compose — kept OUT of
+ * index.ts so it is unit-testable:
+ *   - `mnemom code invite <token>`            → redeem, done (sub-verb; "invite" is reserved)
+ *   - `mnemom code --invite <token>`          → redeem, done
+ *   - `mnemom code --invite <token> <scen>`   → redeem, then launch
+ *   - `mnemom code <scen>`                    → launch
+ *   - `mnemom code`                           → error with guidance
+ */
+export declare function runCodeInvocation(input: CodeInvocation, deps: CodeInvocationDeps): Promise<void>;

package/dist/commands/code-invite.js

@@ -0,0 +1,193 @@
+/**
+ * Mnemom Code — the invited-cohort gate + `mnemom code --invite <token>`.
+ *
+ * `mnemom code` is open by default to Mnemom's own people (@mnemom.ai) and to
+ * customers who redeemed an invitation. The api decides
+ * (`GET /v1/code/entitlement`); this module is the CLI side of that:
+ *
+ *   - `assertCodeEnabled(orgId, orgLabel)` runs in the launch preamble (right
+ *     after sign-in, before the µ-balance check). A determined
+ *     `code_not_enabled` BLOCKS with the api's own hint; anything inconclusive
+ *     (network, 5xx, a membership 403) fails OPEN — the gate is a friendly
+ *     pre-check, the api/gateway remain the real enforcement.
+ *   - `codeInviteCommand(token)` redeems a `pinv_…` invitation
+ *     (`POST /v1/invites/accept`): signs the customer in first (creating a free
+ *     account in the same flow if needed), unlocks Mnemom Code for them, and
+ *     reports whether the starter µ landed. Backs both `mnemom code --invite
+ *     <token> [scenario]` and the `mnemom code invite <token>` sub-verb.
+ *
+ * All narration goes to stderr (the `mnemom code` convention — stdout is for
+ * the dry-run plan only). Copy says "µ", never "MU".
+ */
+import { acceptProductInvite, CODE_NOT_ENABLED, getCodeEntitlement, MnemomApiError, } from "../lib/api.js";
+import { fmt } from "../lib/format.js";
+import { isInteractive } from "../lib/prompt.js";
+const say = (line = "") => console.error(line);
+/** Thrown when the org is determined NOT enabled. The guidance is already printed
+ *  when this is thrown — callers exit quietly (same contract as MuInsufficientError). */
+export class CodeNotEnabledError extends Error {
+    orgLabel;
+    constructor(orgLabel) {
+        super("Mnemom Code is not enabled for this organization");
+        this.orgLabel = orgLabel;
+        this.name = "CodeNotEnabledError";
+    }
+}
+/** `pinv_` + base64url — the product-invite token shape the api mints. */
+export const INVITE_TOKEN_RE = /^pinv_[A-Za-z0-9_-]{8,}$/;
+export function looksLikeInviteToken(value) {
+    return typeof value === "string" && INVITE_TOKEN_RE.test(value.trim());
+}
+const FALLBACK_HINT = "Ask your Mnemom contact for a Mnemom Code invitation, then run: mnemom code --invite <token>";
+/** Drop control characters (ANSI escapes included) from an api-supplied string before
+ *  it reaches the terminal — defense in depth; the value is first-party but printed raw. */
+export function sanitizeTerminalText(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u001f\u007f]/g, "");
+}
+/** Human label for the gate's `source`. */
+export function sourceLabel(source) {
+    switch (source) {
+        case "internal_cohort":
+            return "internal cohort";
+        case "staff":
+            return "Mnemom staff";
+        case "invitation":
+            return "invitation";
+        default:
+            return String(source);
+    }
+}
+/** The api's `code_not_enabled` 403 — the ONE case that blocks. */
+export function isCodeNotEnabled(err) {
+    return (err instanceof MnemomApiError && err.effectiveStatus === 403 && err.code === CODE_NOT_ENABLED);
+}
+function hintFrom(err) {
+    const d = err.details;
+    return typeof d?.hint === "string" && d.hint.trim()
+        ? sanitizeTerminalText(d.hint)
+        : FALLBACK_HINT;
+}
+function printNotEnabled(orgLabel, hint) {
+    say();
+    say(fmt.warn(`Mnemom Code isn't enabled for ${orgLabel} yet.`));
+    say(fmt.dim("  mnemom code is rolling out to an invited cohort. If you have an invitation token"));
+    say(fmt.dim("  (pinv_…), redeem it and you're in:"));
+    say();
+    say("    mnemom code --invite <token>");
+    say();
+    say(fmt.dim(`  ${hint}`));
+}
+/**
+ * Enforce the Mnemom Code gate for the org the launch targets. Blocks (prints
+ * guidance + throws CodeNotEnabledError) ONLY on a determined `code_not_enabled`;
+ * every other failure is inconclusive and fails open with a dim note.
+ */
+export async function assertCodeEnabled(orgId, orgLabel) {
+    try {
+        await getCodeEntitlement(orgId);
+    }
+    catch (err) {
+        if (isCodeNotEnabled(err)) {
+            printNotEnabled(orgLabel, hintFrom(err));
+            throw new CodeNotEnabledError(orgLabel);
+        }
+        say(fmt.dim(`  (Could not verify Mnemom Code access — ${err instanceof Error ? err.message : String(err)}. Continuing.)`));
+    }
+}
+async function defaultEnsureSession(opts) {
+    // Lazy import: code-setup imports assertCodeEnabled from THIS module, so a static
+    // import here would be a cycle.
+    const { ensureMnemomSession } = await import("./code-setup.js");
+    return ensureMnemomSession(opts);
+}
+/** Map an accept failure to the sentence the customer needs. Null = not ours to explain. */
+export function explainAcceptError(err) {
+    if (!(err instanceof MnemomApiError))
+        return null;
+    switch (err.effectiveStatus) {
+        case 404:
+            return "No invitation found for that token — check it was copied completely.";
+        case 410:
+            return "This invitation has expired or was revoked — ask your Mnemom contact for a new one.";
+        case 403:
+            return "This invitation was issued to a different account — sign in with the email it was sent to (mnemom logout, then mnemom login).";
+        case 409:
+            return "The invitation changed while redeeming — run the command again.";
+        default:
+            return null;
+    }
+}
+/** Print the outcome of a successful accept. */
+export function printAccepted(res) {
+    if (res.already_accepted) {
+        say(fmt.success("This invitation was already accepted — Mnemom Code is unlocked for you."));
+    }
+    else {
+        say(fmt.success("Mnemom Code is unlocked for your account."));
+    }
+    if (res.grant === "fired") {
+        say(fmt.dim("  Your starter µ has been credited."));
+    }
+    else if (res.grant === "deferred") {
+        say(fmt.dim("  Your starter µ credit is pending — you can start now; if it hasn't landed shortly, contact support@mnemom.ai."));
+    }
+    say(fmt.dim("  Start a governed session:  mnemom code <scenario>"));
+}
+/**
+ * `mnemom code --invite <token>` / `mnemom code invite <token>`: sign in, redeem,
+ * report. Throws with a clear message on a bad token, no session, or an accept
+ * failure the customer can act on; rethrows anything else.
+ */
+export async function codeInviteCommand(token, opts = {}) {
+    const trimmed = (token ?? "").trim();
+    if (!looksLikeInviteToken(trimmed)) {
+        throw new Error("mnemom code --invite: expected a Mnemom Code invitation token (pinv_…) — copy it from your invitation email.");
+    }
+    const interactive = opts.interactive ?? isInteractive();
+    const ensureSession = opts.ensureSession ?? defaultEnsureSession;
+    const haveSession = await ensureSession({ interactive });
+    if (!haveSession) {
+        throw new Error("mnemom code --invite: redeeming needs a Mnemom account.\n" +
+            "  Sign in:   mnemom login\n" +
+            "  Then run the same --invite command again.");
+    }
+    say(fmt.dim("  Redeeming your Mnemom Code invitation…"));
+    let result;
+    try {
+        result = await acceptProductInvite(trimmed);
+    }
+    catch (err) {
+        const explained = explainAcceptError(err);
+        if (explained)
+            throw new Error(`mnemom code --invite: ${explained}`, { cause: err });
+        throw err;
+    }
+    printAccepted(result);
+    return result;
+}
+// ── `mnemom code` entry dispatch ─────────────────────────────────────────────
+export const NO_SCENARIO_MESSAGE = "mnemom code: a <scenario> slug is required (e.g. `mnemom code onboarding`) — or redeem an invitation with `mnemom code --invite <token>`.";
+/**
+ * How the `code` command's positional + `--invite` compose — kept OUT of
+ * index.ts so it is unit-testable:
+ *   - `mnemom code invite <token>`            → redeem, done (sub-verb; "invite" is reserved)
+ *   - `mnemom code --invite <token>`          → redeem, done
+ *   - `mnemom code --invite <token> <scen>`   → redeem, then launch
+ *   - `mnemom code <scen>`                    → launch
+ *   - `mnemom code`                           → error with guidance
+ */
+export async function runCodeInvocation(input, deps) {
+    if (input.scenario === "invite") {
+        await deps.redeem(input.passthrough[0]);
+        return;
+    }
+    if (input.inviteFlag) {
+        await deps.redeem(input.inviteFlag);
+        if (!input.scenario)
+            return;
+    }
+    if (!input.scenario)
+        throw new Error(NO_SCENARIO_MESSAGE);
+    await deps.launch(input.scenario);
+}

package/dist/commands/code-setup.d.ts

@@ -66,6 +66,12 @@ export declare class MuInsufficientError extends Error {
     readonly orgLabel: string;
     constructor(orgLabel: string);
 }
+/**
+ * The preamble errors whose guidance is ALREADY printed when thrown — callers
+ * exit 1 quietly instead of re-printing them as "Error: …". One predicate so the
+ * two catch sites (`mnemom code` and `mnemom code setup`) cannot drift.
+ */
+export declare function isQuietPreambleExit(err: unknown): boolean;
 /**
  * Ensure the customer has a Mnemom session, the way `mnemom try-me` does: if
  * they are not signed in, offer a one-click browser sign-in (device-flow

package/dist/commands/code-setup.js

@@ -34,6 +34,7 @@ import { configKeySpec, loadCodeConfig, writeCodeConfig } from "../lib/code-conf
 import { deriveHashProof } from "./agents.js";
 import { birthThroughGateway } from "./wrap.js";
 import { resolveAnthropicKey } from "./code.js";
+import { assertCodeEnabled, CodeNotEnabledError } from "./code-invite.js";
 const say = (line = "") => console.error(line);
 /**
  * The default governed-agent slug for the current customer: `code-<handle>`,
@@ -99,13 +100,59 @@ export async function ensureGovernedAgent(opts) {
     const agentId = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
     const hashProof = deriveHashProof(opts.anthropicKey, slug);
     await claimAgent(agentId, { hashProof, orgId: org?.org_id });
-    await putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId)), "application/json");
-    await putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId)), "application/json");
-    say(fmt.success(`mnemom code: provisioned + claimed '${slug}' (${agentId}) in ${orgLabel} — observe posture published (goal contracts nudge).`));
+    say(fmt.success(`mnemom code: claimed '${slug}' (${agentId}) in ${orgLabel}.`));
+    // Publish the observe-only cards. A card write that can't complete (propagation
+    // right after the claim, or a missing cards:write scope) does NOT abort the
+    // provision — the agent is claimed and governed on whatever landed; we warn how
+    // to finish it. So `provisioned` reflects the claim, not a perfect card set.
+    await publishDefaultCards(agentId);
     // 6. Remember the slug so future launches skip straight to usable.
     persistAgentSlug(slug);
     return { slug, provisioned: true };
 }
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Write one card with a brief retry to absorb the org-membership propagation that
+ * can transiently 401/403/409 a write right after a claim (the same window
+ * `mnemom try-me` guards). A write that still fails returns ok:false rather than
+ * throwing, so provisioning degrades gracefully.
+ */
+async function tryPublishCard(name, write) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await write();
+            return { name, ok: true };
+        }
+        catch (err) {
+            const status = err instanceof MnemomApiError ? err.status : undefined;
+            const maybeTransient = status === undefined || status === 401 || status === 403 || status === 409;
+            if (attempt === 0 && maybeTransient) {
+                await sleep(1500); // let the claim's org-membership propagate, then retry once
+                continue;
+            }
+            return { name, ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    return { name, ok: false, error: "unknown error" };
+}
+/** Publish both default observe-only cards; never throws — warns on a card that can't be written. */
+async function publishDefaultCards(agentId) {
+    const align = await tryPublishCard("alignment", () => putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId)), "application/json"));
+    const prot = await tryPublishCard("protection", () => putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId)), "application/json"));
+    if (align.ok && prot.ok) {
+        say(fmt.success("mnemom code: observe posture published (alignment + protection observe; goal contracts nudge)."));
+        return;
+    }
+    if (align.ok)
+        say(fmt.success("mnemom code: alignment card published (observe)."));
+    for (const c of [align, prot]) {
+        if (c.ok)
+            continue;
+        const publishCmd = c.name === "alignment" ? "mnemom card publish" : "mnemom protection publish";
+        say(fmt.warn(`mnemom code: couldn't publish the ${c.name} card — ${c.error}`));
+        say(fmt.dim(`  The agent is claimed and running; finish it later with \`${publishCmd}\`.`));
+    }
+}
 /** `mnemom code setup [--agent <slug>]` — the explicit provisioning entry point. */
 export async function codeSetupCommand(opts = {}) {
     const gatewayHost = resolveGatewayHost(process.env);
@@ -114,8 +161,8 @@ export async function codeSetupCommand(opts = {}) {
         await ensureSessionAndBalance({});
     }
     catch (err) {
-        if (err instanceof MuInsufficientError)
-            process.exit(1);
+        if (isQuietPreambleExit(err))
+            process.exit(1); // guidance already printed
         throw err;
     }
     const anthropicKey = await resolveAnthropicKey(process.env, { allowPrompt: true });
@@ -154,6 +201,14 @@ export class MuInsufficientError extends Error {
         this.name = "MuInsufficientError";
     }
 }
+/**
+ * The preamble errors whose guidance is ALREADY printed when thrown — callers
+ * exit 1 quietly instead of re-printing them as "Error: …". One predicate so the
+ * two catch sites (`mnemom code` and `mnemom code setup`) cannot drift.
+ */
+export function isQuietPreambleExit(err) {
+    return err instanceof MuInsufficientError || err instanceof CodeNotEnabledError;
+}
 /** Best-effort detection of a headless/SSH box where a browser can't open. */
 function headlessEnv() {
     const e = process.env;
@@ -274,6 +329,9 @@ export async function ensureSessionAndBalance(opts) {
     const active = getActiveOrg();
     const orgId = active?.org_id ?? (await getMyPersonalOrg()).org_id;
     const orgLabel = active ? `${active.name} (${active.slug})` : "your personal org";
+    // Invited-cohort gate FIRST: an org that is not enabled for Mnemom Code gets
+    // the invite guidance, not a top-up message (the µ check would be moot).
+    await assertCodeEnabled(orgId, orgLabel);
     await assertMuBalance(orgId, orgLabel);
     return { orgId, orgLabel };
 }

package/dist/commands/code.js

@@ -34,7 +34,7 @@ import { MNEMOM_DIR } from "../lib/config.js";
 import { configKeySpec, loadCodeConfig, writeCodeConfig } from "../lib/code-config.js";
 import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
-import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, MuInsufficientError, } from "./code-setup.js";
+import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, } from "./code-setup.js";
 import { assembleContract, buildCustomHeaders, isProdGateway, launchPreferenceExplicit, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, sanitizeAgentName, } from "../lib/code.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/code.json, 0600. */
 const CODE_STORE = join(MNEMOM_DIR, "code.json");
@@ -132,8 +132,8 @@ export async function codeCommand(scenario, options = {}) {
         await ensureSessionAndBalance({ interactive: isInteractive() });
     }
     catch (err) {
-        if (err instanceof MuInsufficientError)
-            process.exit(1); // top-up message already printed
+        if (isQuietPreambleExit(err))
+            process.exit(1); // guidance already printed
         throw err;
     }
     // Now that a session exists, a defaulted slug can use the real login handle
@@ -287,6 +287,11 @@ export function resolveCliBin(cliOpt, env) {
         throw new Error(`mnemom code: --cli path '${requested}' not found.`);
     }
     for (const dir of (env.PATH || "").split(":")) {
+        // Skip ephemeral cmux CLI shims: they only work inside a cmux session and,
+        // when spawned standalone, fall back to `exec claude` on a shim-stripped PATH
+        // and fail with "claude not found in PATH". They're never a durable target.
+        if (dir.includes("cmux-cli-shims"))
+            continue;
         const cand = join(dir || ".", requested);
         if (existsSync(cand))
             return { bin: cand, name };

package/dist/index.js

@@ -24,6 +24,7 @@ import { codeCommand } from "./commands/code.js";
 import { codeConfigCommand } from "./commands/code-config.js";
 import { codeDoctorCommand } from "./commands/code-doctor.js";
 import { codeSetupCommand } from "./commands/code-setup.js";
+import { codeInviteCommand, runCodeInvocation } from "./commands/code-invite.js";
 import { applyConfigToEnv, loadCodeConfig } from "./lib/code-config.js";
 import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
@@ -99,9 +100,9 @@ const collectRepeatable = (value, previous) => {
     return previous;
 };
 program
-    .command("code <scenario> [passthrough...]")
+    .command("code [scenario] [passthrough...]")
     .description("Launch a governed coding agent through the Mnemom gateway (governed identity + optional sealed contract). " +
-    "Sub-verbs: `mnemom code setup` provisions your governed agent; `mnemom code doctor` preflights prerequisites; `mnemom code config …` manages persistent settings (~/.mnemom/code.toml).")
+    "Sub-verbs: `mnemom code setup` provisions your governed agent; `mnemom code doctor` preflights prerequisites; `mnemom code config …` manages persistent settings (~/.mnemom/code.toml); `mnemom code invite <token>` redeems a Mnemom Code invitation.")
     .option("--goal <statement>", "Contract goal statement (required if any contract flag is given)")
     .option("--requirement <text>", "Contract requirement (repeatable)", collectRepeatable, [])
     .option("--allow <glob>", "Allowed path/glob (repeatable)", collectRepeatable, [])
@@ -124,6 +125,7 @@ program
     "max",
 ]))
     .option("--trim-mcp", "Launch the CLI with no MCP servers (--strict-mcp-config + empty --mcp-config)")
+    .option("--invite <token>", "Redeem a Mnemom Code invitation (pinv_…): unlocks Mnemom Code for you + credits your starter µ; launches too when a <scenario> is given")
     .option("--setup", "Provision + claim the governed agent before launch (non-interactive opt-in)")
     .option("--no-setup", "Skip governed-agent provisioning entirely for this launch")
     .option("--no-yolo", "Do NOT pass --dangerously-skip-permissions (yolo is on by default)")
@@ -131,6 +133,17 @@ program
     .option("--dry-run", "Print the resolved launch plan and exit — no key read, no spawn")
     .action(async (scenario, passthrough, opts) => {
     try {
+        // Invitation redemption — `mnemom code invite <token>` (sub-verb) or
+        // `mnemom code --invite <token> [scenario]` — composes with the launch in
+        // runCodeInvocation (commands/code-invite.ts, unit-tested); everything below
+        // is the launch half, running only when a real scenario was given.
+        await runCodeInvocation({ scenario, passthrough, inviteFlag: opts.invite }, { redeem: (token) => codeInviteCommand(token), launch: (scenario) => launchCode(scenario) });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+    async function launchCode(scenario) {
         // Sub-verb: `mnemom code config …` manages persistent settings and never
         // launches. (A scenario literally named "config" is reserved for this.)
         if (scenario === "config") {
@@ -191,10 +204,6 @@ program
             dryRun: opts.dryRun,
         });
     }
-    catch (error) {
-        console.error("Error:", error instanceof Error ? error.message : error);
-        process.exit(1);
-    }
 });
 // ── wrap (MNE-935, A4) — instrument an existing agent through the gateway ────
 //

package/dist/lib/api.d.ts

@@ -1182,4 +1182,31 @@ export interface OrgUsageQuery {
  * the user "org not found" on what is most often just the flag being off.
  */
 export declare function getOrgUsage(orgId: string, opts?: OrgUsageQuery): Promise<OrgUsageResponse>;
+/** `GET /v1/code/entitlement` 200 body — why Mnemom Code is enabled for the org. */
+export interface CodeEntitlement {
+    org_id: string;
+    enabled: true;
+    source: "internal_cohort" | "staff" | "invitation";
+}
+/** The machine-readable code on the gate's 403 when the org is not enabled. */
+export declare const CODE_NOT_ENABLED = "code_not_enabled";
+/**
+ * Is Mnemom Code enabled for `orgId` (default: the caller's primary org)?
+ * Resolves on 200; throws MnemomApiError with `.code === "code_not_enabled"`
+ * (and `.details.hint`) when the org is not enabled, or a plain MnemomApiError
+ * for membership/transport failures.
+ */
+export declare function getCodeEntitlement(orgId?: string): Promise<CodeEntitlement>;
+/** `POST /v1/invites/accept` 200 body. Never carries an amount — only whether the
+ *  starter grant fired or was deferred for a later backfill. */
+export interface AcceptProductInviteResult {
+    accepted: boolean;
+    already_accepted?: boolean;
+    account_type: "user" | "org";
+    account_id: string;
+    products: string[];
+    grant?: "fired" | "deferred";
+}
+/** Redeem a `pinv_…` product invite (a Mnemom Code invitation) for the signed-in user. */
+export declare function acceptProductInvite(token: string): Promise<AcceptProductInviteResult>;
 export {};

package/dist/lib/api.js

@@ -1480,3 +1480,50 @@ export async function getOrgUsage(orgId, opts = {}) {
     const qs = params.toString() ? `?${params.toString()}` : "";
     return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/usage/by-person${qs}`, {}, { fallback: "Failed to fetch usage" });
 }
+// ─── Mnemom Code — feature gate + invitation redemption ──────────────────────
+//
+// `mnemom code` is rolling out to an invited cohort. Two api calls back that:
+// the per-org gate (`GET /v1/code/entitlement`) the launch preamble checks, and
+// the product-invite accept (`POST /v1/invites/accept`) behind
+// `mnemom code --invite <token>`. Both go through `codeFetch` rather than
+// `gFetch`: gFetch flattens EVERY 403 into "Permission denied (need org admin /
+// membership)", but the gate's 403 carries a machine-readable
+// `code_not_enabled` + a hint the command layer must print verbatim, and the
+// accept route's 403/404/409/410 each mean something specific to the user.
+// So non-OK responses here are parsed with readApiError (code + details kept)
+// and only the 401 keeps gFetch's canonical not-authenticated message.
+async function codeFetch(path, init = {}, fallback) {
+    const url = validateUrl(`${API_BASE}${path}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: init.method ?? "GET",
+        headers: {
+            ...(await authHeaders()),
+            Accept: "application/json",
+            ...(init.body ? { "Content-Type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+        },
+        body: init.body,
+    }));
+    if (!response.ok) {
+        if (response.status === 401)
+            throw new MnemomApiError(401, NOT_AUTHENTICATED_MSG);
+        throw await readApiError(response, fallback);
+    }
+    return (await response.json());
+}
+/** The machine-readable code on the gate's 403 when the org is not enabled. */
+export const CODE_NOT_ENABLED = "code_not_enabled";
+/**
+ * Is Mnemom Code enabled for `orgId` (default: the caller's primary org)?
+ * Resolves on 200; throws MnemomApiError with `.code === "code_not_enabled"`
+ * (and `.details.hint`) when the org is not enabled, or a plain MnemomApiError
+ * for membership/transport failures.
+ */
+export async function getCodeEntitlement(orgId) {
+    const q = orgId ? `?org_id=${encodeURIComponent(orgId)}` : "";
+    return codeFetch(`/v1/code/entitlement${q}`, {}, "Could not check Mnemom Code access");
+}
+/** Redeem a `pinv_…` product invite (a Mnemom Code invitation) for the signed-in user. */
+export async function acceptProductInvite(token) {
+    return codeFetch("/v1/invites/accept", { method: "POST", body: JSON.stringify({ token }) }, "Could not redeem the invitation");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.0-next.2",
+  "version": "0.17.0-next.3",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {