@mnemom/mnemom 0.17.19 → 0.17.20

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

@@ -52,6 +52,9 @@ export declare function assertCodeEnabled(orgId: string, orgLabel: string): Prom
 /** Ensures a Mnemom session exists (injected so tests never touch the real login flow). */
 export type EnsureSession = (opts: {
     interactive?: boolean;
+    /** The invitation being redeemed — carried into the browser sign-in so a new
+     *  invitee's sign-up skips the confirmation email. */
+    inviteToken?: string;
 }) => Promise<boolean>;
 /** The accept route's 403 codes (mnemom-api `product-invite-accept.ts`). */
 export declare const INVITE_ACCOUNT_MISMATCH = "invite_account_mismatch";

package/dist/commands/agent-invite.js

@@ -210,7 +210,7 @@ export async function agentInviteCommand(token, opts = {}) {
     }
     const interactive = opts.interactive ?? isInteractive();
     const ensureSession = opts.ensureSession ?? defaultEnsureSession;
-    const haveSession = await ensureSession({ interactive });
+    const haveSession = await ensureSession({ interactive, inviteToken: trimmed });
     if (!haveSession) {
         throw new Error("mnemom agent --invite: redeeming needs a Mnemom account.\n" +
             "  Sign in:   mnemom login\n" +

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

@@ -218,6 +218,7 @@ export declare function isQuietPreambleExit(err: unknown): boolean;
  */
 export declare function ensureMnemomSession(opts?: {
     interactive?: boolean;
+    inviteToken?: string;
 }): Promise<boolean>;
 /**
  * Enforce a positive Mnemom Units balance on the org the agent lives in.

package/dist/commands/agent-setup.js

@@ -621,16 +621,26 @@ export async function ensureMnemomSession(opts = {}) {
     if (!(await askYesNo("Sign in or create your account now?", true)))
         return false;
     const device = headlessEnv();
+    // The device-code page has no way to carry the invitation, so a NEW invitee
+    // signing up there gets the confirmation email — say so instead of dropping
+    // the invitation silently. (The browser path carries it; see loginWithLoopback.)
+    const deviceSignIn = async () => {
+        if (opts.inviteToken) {
+            say(fmt.dim("  New to Mnemom? Signing up from a device code asks you to confirm your email first."));
+            say(fmt.dim("  To skip that, open the link in your invitation email on a machine with a browser."));
+        }
+        await loginWithDeviceFlow();
+    };
     try {
         if (device)
-            await loginWithDeviceFlow();
+            await deviceSignIn();
         else
-            await loginWithBrowser();
+            await loginWithBrowser({ inviteToken: opts.inviteToken });
     }
     catch (err) {
         if (!device) {
             say(fmt.dim("  Browser sign-in didn't work here — falling back to a device code…"));
-            await loginWithDeviceFlow();
+            await deviceSignIn();
         }
         else {
             throw err;

package/dist/commands/agent.d.ts

@@ -124,6 +124,13 @@ export interface AgentOptions {
      * session-config header's `experimental` array. Absent/empty ⇒ none of the three.
      */
     experimental?: readonly ExperimentalId[];
+    /**
+     * Load the "Mnemom for Claude Code" plugin (`plugins/mnemom`: the Mnemom band,
+     * `/mnemom`, the gateway guard, Mnemom attribution) into the launched Claude Code.
+     * Default OFF (not published yet); `--plugin` ⇒ true; `--no-plugin` ⇒ false; undefined ⇒
+     * MNEMOM_AGENT_PLUGIN decides (lib/claude-plugin).
+     */
+    plugin?: boolean;
     passthrough?: string[];
     /** Print the resolved launch plan and exit — no key read, no spawn. */
     dryRun?: boolean;
@@ -335,6 +342,8 @@ export declare function buildCliArgs(options: AgentOptions, ctx: {
     allowCliFlags: boolean;
     ccSessionId?: string;
     handoffMcpConfigPath?: string;
+    /** The bundled Mnemom plugin folder → `--plugin-dir <dir>` (lib/claude-plugin). */
+    pluginDir?: string;
 }): string[];
 /**
  * The Claude Code session id a launch runs under, from the caller's passthrough (implicit-goal
@@ -365,6 +374,8 @@ export declare function logLaunch(ctx: {
     envelope: SealedContractEnvelope | null;
     goalMode: string | null;
     cli: ResolvedCli;
+    /** The plugin line (`pluginPlanLine`): `off`, `off (<why>)` or `<name> (<dir>)`. */
+    plugin: string;
 }): void;
 /** The launch line for the yolo default: permission prompts are skipped, and how to keep them. */
 export declare function permissionPromptsLine(cli: ResolvedCli): string;
@@ -392,5 +403,7 @@ export declare function printPlan(ctx: {
     sessionConfig: Record<string, string>;
     /** The experimental features on for this launch (the header's `experimental` array). */
     experimental?: readonly string[];
+    /** The bundled Claude Code plugin line (`pluginPlanLine`); always printed, like the launch log. */
+    plugin: string;
 }): void;
 export {};

package/dist/commands/agent.js

@@ -48,6 +48,8 @@ import { defaultAgentSlug, ensureClaimedServedAgent, ensureSessionAndBalance, is
 import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
+import { appendPluginDirsEnv, applyPluginEnv, pluginEnabled, pluginPlanLine, resolvePluginDir, } from "../lib/claude-plugin.js";
+import { CLI_VERSION } from "../version.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
 const CODE_STORE = LAUNCHER_STORE_PATH;
 const say = (line = "") => console.error(line);
@@ -194,6 +196,13 @@ export async function agentCommand(scenarioArg, options = {}) {
     if (cellError)
         throw new Error(cellError);
     const cellNote = isProdGateway(env) ? "us-2/prod" : `custom (${gatewayHost})`;
+    // ── the bundled Claude Code plugin (lib/claude-plugin) ── resolved up front so the dry-run plan
+    // and the launch log print the same line. Only Claude Code proper takes `--plugin-dir`.
+    const pluginWanted = pluginEnabled(options.plugin, env);
+    const bundledPluginDir = pluginWanted ? resolvePluginDir() : null;
+    const pluginFor = (cliName) => cliName !== "claude" && pluginWanted
+        ? { dir: null, line: `off (${cliName} is not Claude Code)` }
+        : { dir: bundledPluginDir, line: pluginPlanLine(bundledPluginDir, pluginWanted) };
     const yolo = options.yolo !== false; // default ON
     const contextHint = options.contextHint !== false; // default ON
     // Context profile: none (null — the cell's own default, no fold key sent) unless
@@ -303,6 +312,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             compactAt,
             sessionConfig,
             experimental,
+            plugin: pluginFor(planCli.name).line,
         });
         if (auth === "subscription") {
             say("mnemom agent: auth = subscription — Claude Code would use your claude.ai login (Team/Enterprise plans only) with a Mnemom API key; no Anthropic key.");
@@ -516,7 +526,46 @@ export async function agentCommand(scenarioArg, options = {}) {
         contextProfile,
         compactAt: contextProfile === "off" ? null : compactAt,
     });
-    logLaunch({ shape, door, agent, conversationId, cellNote, envelope, goalMode, cli });
+    const launchPlugin = pluginFor(cli.name);
+    logLaunch({
+        shape,
+        door,
+        agent,
+        conversationId,
+        cellNote,
+        envelope,
+        goalMode,
+        cli,
+        plugin: launchPlugin.line,
+    });
+    if (pluginWanted && cli.name === "claude" && !bundledPluginDir) {
+        say(fmt.warn("mnemom agent: the Mnemom plugin folder is not in this install (it is not published yet; run from a source checkout) — launching without the Mnemom band and /mnemom."));
+    }
+    // Non-secret launch facts for the plugin's band and `/mnemom status`. Built here, applied to the
+    // child env by each launch shape AFTER it has built that env (lib/claude-plugin, PLUGIN_ENV).
+    const plugin = launchPlugin.dir
+        ? {
+            dir: launchPlugin.dir,
+            launch: {
+                gatewayHost,
+                apiUrl: getApiUrl(),
+                agent,
+                conversationId,
+                cellNote,
+                shape,
+                contractSha: envelope?.sha,
+                contract: envelope?.canonical,
+                goalMode,
+                scenario,
+                launcherVersion: CLI_VERSION,
+                // The mod re-runs this CLI (`agent show --json`, `agent goal show --json`) for the live
+                // goal state; execArgv keeps a `tsx`/`--import` dev launch runnable the same way.
+                launcherExec: process.argv[1]
+                    ? [process.execPath, ...process.execArgv, process.argv[1]]
+                    : [],
+            },
+        }
+        : undefined;
     if (expNotice)
         say(expNotice);
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
@@ -586,6 +635,7 @@ export async function agentCommand(scenarioArg, options = {}) {
                 ccSessionId: id,
             }),
             knownCcSessionId: cc.id ?? continuedCcSessionId,
+            plugin,
         });
         return; // launchTerminal exits the process
     }
@@ -602,6 +652,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         goalMode,
         sessionConfigB64,
         handoffMcpConfigPath,
+        plugin,
         options: launchOptions,
         yolo,
         ccSessionId,
@@ -1081,6 +1132,7 @@ function launchTerminal(ctx) {
         allowCliFlags: true,
         ccSessionId: ctx.ccSessionId,
         handoffMcpConfigPath: ctx.handoffMcpConfigPath,
+        pluginDir: ctx.plugin?.dir,
     });
     // Claude Code logged in via claude.ai (OAuth) PREEMPTS ANTHROPIC_API_KEY, so
     // it is force-unset; the real key rides in ANTHROPIC_CUSTOM_HEADERS and
@@ -1102,6 +1154,9 @@ function launchTerminal(ctx) {
     // Both auth arms point ANTHROPIC_BASE_URL at the gateway door, which makes Claude Code turn
     // tool search off and inline every tool schema on every request — unless told otherwise.
     applyToolSearchDefault(childEnv);
+    // The plugin's non-secret launch facts (MNEMOM_CC_*): never a key, never a header value.
+    if (ctx.plugin)
+        applyPluginEnv(childEnv, ctx.plugin.launch);
     const sessionName = passthroughName(ctx.options.passthrough ?? []) ?? sessionDisplayName(ctx.agent, ctx.scenario);
     childEnv[SESSION_NAME_ENV] = sessionName;
     // Exact compaction signal for the gateway (x-claude-code-request-class: compaction), on every
@@ -1397,6 +1452,10 @@ function spawnRcCli(ctx) {
     if (ctx.handoffMcpConfigPath && ctx.anthropicKey) {
         childEnv[HANDOFF_RC_KEY_ENV_NAME] = ctx.anthropicKey;
     }
+    // The plugin's non-secret launch facts (MNEMOM_CC_*), also after the strip loop: not an
+    // ANTHROPIC_* var, so the RC gate ignores them, and nothing here is a key or a header value.
+    if (ctx.plugin)
+        applyPluginEnv(childEnv, ctx.plugin.launch);
     let args;
     if (ctx.shape === "server") {
         // Headless dispatcher: no --model/--effort/--trim-mcp/yolo flags; the model
@@ -1408,6 +1467,10 @@ function spawnRcCli(ctx) {
             say("mnemom agent: --slack is not applied to a headless server (a channel server needs an interactive confirmation); use the terminal or remote-control shape.");
         }
         args = ["remote-control", "--name", rcName, ...passthrough];
+        // No `--plugin-dir` on the headless server: the env path list loads the plugin into every
+        // session it spawns instead (a user's own list is kept).
+        if (ctx.plugin)
+            appendPluginDirsEnv(childEnv, ctx.plugin.dir);
         // Additive, never `--strict-mcp-config`: --trim-mcp is not applied under --server (every
         // dispatched session keeps its full MCP set, unrestricted — see warnServerDrops below), so
         // the handoff tool rides in on TOP of that set rather than replacing it.
@@ -1424,6 +1487,7 @@ function spawnRcCli(ctx) {
             allowCliFlags: true,
             ccSessionId: ctx.ccSessionId,
             handoffMcpConfigPath: ctx.handoffMcpConfigPath,
+            pluginDir: ctx.plugin?.dir,
         });
         args = ["--remote-control", rcName, ...flagArgs];
         if (ctx.options.slack)
@@ -1540,6 +1604,8 @@ export function buildCliArgs(options, ctx) {
             args.push("--dangerously-skip-permissions");
         if (ctx.ccSessionId)
             args.push("--session-id", ctx.ccSessionId);
+        if (ctx.pluginDir)
+            args.push("--plugin-dir", ctx.pluginDir);
     }
     if (options.passthrough?.length)
         args.push(...options.passthrough);
@@ -1650,6 +1716,7 @@ export function goalAlignmentMode(envelope, goalMode) {
 }
 export function logLaunch(ctx) {
     say(`mnemom agent: routing ${ctx.cli.name} through ${ctx.door} [${ctx.cellNote}] as '${ctx.agent}' (conversation ${ctx.conversationId}).`);
+    say(`mnemom agent: plugin: ${ctx.plugin}`);
     if (ctx.envelope) {
         say(`mnemom agent: contract statement: ${ctx.envelope.contract.statement}`);
         say(`mnemom agent: contract sha256[0:16]: ${ctx.envelope.sha}`);
@@ -1673,6 +1740,7 @@ export function printPlan(ctx) {
     L.push("mnemom agent — launch plan (dry run)");
     L.push(`  scenario:      ${ctx.scenario}`);
     L.push(`  cli:           ${ctx.cli.name} (${ctx.cli.bin})`);
+    L.push(`  plugin:        ${ctx.plugin}`);
     L.push(`  shape:         ${ctx.shape}`);
     L.push(`  door:          ${ctx.door}  [${ctx.cellNote}]`);
     L.push(`  agent:         ${ctx.agent}`);

package/dist/index.js

@@ -182,6 +182,11 @@ const agentCmd = program
     .option("--no-governance", "Turn governance OFF for the agent's cards, autonomy policy checks included (by default new agents run autonomy observe, rules only; a card refresh otherwise keeps an existing agent's modes)")
     .option("--no-yolo", "Do NOT pass --dangerously-skip-permissions (yolo is on by default)")
     .option("--no-context-hint", "Do NOT seed Claude Code's context-hint feature flag before launch")
+    // The Mnemom plugin lands dark: off by default and not in the published package, so its two
+    // flags stay out of --help until the shipping PR turns it on (lib/claude-plugin.ts). They still
+    // parse, for a source checkout.
+    .addOption(new Option("--plugin", "Load the Mnemom plugin (the Mnemom band, /mnemom, the gateway guard) into Claude Code — off by default and not in the published package yet (needs a source checkout; MNEMOM_AGENT_PLUGIN=1 does the same)").hideHelp())
+    .addOption(new Option("--no-plugin", "Do NOT load the Mnemom plugin even when MNEMOM_AGENT_PLUGIN=1").hideHelp())
     .addOption(new Option("--slack", "EXPERIMENTAL (`mnemom experimental enable slack`): attach the Slack channel — messages addressed to this session arrive in it, and it can reply (see `mnemom agent slack`)").hideHelp(hiddenUnless("slack")))
     .option("--context", "Force context folding ON for this launch even when launcher.toml (context = false) or MNEMOM_AGENT_CONTEXT turns it off")
     .option("--no-context", "Disable context folding for this launch (folding is on by default; tells the gateway to skip it for this session)")
@@ -366,6 +371,7 @@ const agentCmd = program
             trimMcp: opts.trimMcp,
             yolo: opts.yolo,
             contextHint: opts.contextHint,
+            plugin: opts.plugin,
             slack: opts.slack ?? cfg.slackListen,
             context: opts.context,
             contextProfile: opts.contextProfile,

package/dist/lib/auth.d.ts

@@ -99,7 +99,9 @@ export declare function isLoggedIn(): Promise<boolean>;
  * loopback redirect (the `wrangler login` pattern). Persists the resulting
  * SCOPED tokens (plus the client_id needed to refresh) to ~/.mnemom/auth.json.
  */
-export declare function loginWithBrowser(): Promise<AuthTokens>;
+export declare function loginWithBrowser(opts?: {
+    inviteToken?: string;
+}): Promise<AuthTokens>;
 /**
  * Headless login: RFC 8628 device authorization grant. Shows a user_code +
  * verification_uri for the user to approve in any browser (possibly on another

package/dist/lib/auth.js

@@ -212,8 +212,8 @@ export async function isLoggedIn() {
  * loopback redirect (the `wrangler login` pattern). Persists the resulting
  * SCOPED tokens (plus the client_id needed to refresh) to ~/.mnemom/auth.json.
  */
-export async function loginWithBrowser() {
-    const { tokens, clientId } = await loginWithLoopback();
+export async function loginWithBrowser(opts = {}) {
+    const { tokens, clientId } = await loginWithLoopback(undefined, opts);
     const stored = fromOAuthTokens(tokens, clientId);
     saveAuthTokens(stored);
     return stored;

package/dist/lib/claude-plugin.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The bundled "Mnemom for Claude Code" plugin (`cli/plugins/mnemom`): a Claude Code
+ * mod + skill + MCP config that `mnemom agent` loads into the Claude Code it launches, so the
+ * session SHOWS it is governed — the Mnemom band above the prompt, `/mnemom` commands, the ◆ sign
+ * on the spinner, Mnemom trailers in commit attribution, and a guard that keeps the routing in
+ * place.
+ *
+ * The launcher tells the mod about the launch through NON-SECRET env vars. They carry a distinct
+ * `MNEMOM_CC_*` prefix so they can never be confused with the launcher's own `MNEMOM_AGENT_*`
+ * inputs, and none of them is a key, a header value or anything derived from one: the mod reads
+ * them by literal name (`claude plugin validate` lists every name), and a stray `env` dump of the
+ * child shows nothing it should not.
+ *
+ * Only Claude Code proper (`cli.name === "claude"`) understands `--plugin-dir`; every other
+ * adapter launches without the plugin.
+ *
+ * OFF BY DEFAULT, AND NOT IN THE PUBLISHED PACKAGE YET. The plugin is committed under
+ * `cli/plugins/` but `package.json` `files` leaves it out of the npm tarball, so an installed
+ * `mnemom` has no folder to load and never looks for one. `--plugin` or
+ * MNEMOM_AGENT_PLUGIN=1|true|yes|on opts a launch in (`--no-plugin` or 0|false|off|no wins over
+ * the env); from a source checkout that loads the folder, from an install it says the folder is
+ * not there and launches without it. Turning it on for everyone later is two edits: `plugins`
+ * back into `files`, and `pluginEnabled`'s default to true. It never blocks the launch.
+ */
+/** The plugin's `name` in its plugin.json, and its folder under `cli/plugins/`. */
+export declare const CLAUDE_PLUGIN_NAME = "mnemom";
+/** The env Claude Code reads a path list of extra plugin folders from (where no flag can be given). */
+export declare const CLAUDE_PLUGIN_DIRS_ENV = "CLAUDE_CODE_PLUGIN_DIRS";
+/** The env vars the launcher exports for the mod. Every value is non-secret. */
+export declare const PLUGIN_ENV: {
+    /** `https://gateway.mnemom.ai` (no path): presence = the session is governed. */
+    readonly gatewayHost: "MNEMOM_CC_GATEWAY_HOST";
+    /** The public API origin the Trust Rating is read from (`https://api.mnemom.ai`). */
+    readonly apiUrl: "MNEMOM_CC_API_URL";
+    /** The governed agent's name (the `x-mnemom-agent` header's value). */
+    readonly agent: "MNEMOM_CC_AGENT";
+    readonly conversationId: "MNEMOM_CC_CONVERSATION_ID";
+    /** The cell note the launch log prints (`us-2/prod`, or `custom (<host>)`). */
+    readonly cell: "MNEMOM_CC_CELL";
+    /** `terminal` | `remote-control` | `server`. */
+    readonly shape: "MNEMOM_CC_SHAPE";
+    /** `sealed` (a contract rides in the header) | `implicit` | `off`. */
+    readonly goalMode: "MNEMOM_CC_GOAL_MODE";
+    /** The sealed contract's sha256[0:16]; empty unless sealed. */
+    readonly contractSha: "MNEMOM_CC_CONTRACT_SHA";
+    /**
+     * The sealed contract itself — the canonical JSON the gateway hashes (statement, requirements,
+     * allowed/forbidden paths, ceilings). Empty unless sealed. It is what `--goal`/`--requirement`/…
+     * said on the command line: the person's own words, no secret in it.
+     */
+    readonly contract: "MNEMOM_CC_CONTRACT";
+    /**
+     * The implicit mode's guardrail ceilings, `max_turns=N; budget_usd=X; stall_turns=N` (the
+     * `x-mnemom-goal-mode` header minus its leading `implicit`). Empty unless implicit with ceilings.
+     */
+    readonly guardrails: "MNEMOM_CC_GUARDRAILS";
+    /**
+     * How to run this very `mnemom` again, as a JSON argv (`[node, ...execArgv, script]`): the mod
+     * runs `mnemom agent show <conversation> --json` / `mnemom agent goal show …` through it to read
+     * the live goal state (the sealed verdict, the inferred goal, guardrail usage). The CLI
+     * authenticates with the launch key from its own ledger; the mod never holds the key.
+     */
+    readonly launcherExec: "MNEMOM_CC_LAUNCHER_EXEC";
+    /** The `mnemom agent <session>` scenario name. */
+    readonly session: "MNEMOM_CC_SESSION";
+    readonly launcherVersion: "MNEMOM_CC_LAUNCHER_VERSION";
+};
+export type PluginEnvName = (typeof PLUGIN_ENV)[keyof typeof PLUGIN_ENV];
+/**
+ * Whether this launch loads the plugin: `--plugin` / `--no-plugin` (an explicit boolean) wins,
+ * then MNEMOM_AGENT_PLUGIN (1/true/yes/on ⇒ on), else OFF: the plugin is not published yet.
+ */
+export declare function pluginEnabled(optionPlugin: boolean | undefined, env: NodeJS.ProcessEnv): boolean;
+/**
+ * The bundled plugin's folder (the one holding `.claude-plugin/plugin.json`), or null when it is
+ * missing. Lives at `<package>/plugins/mnemom`, next to `dist/` and `src/`, so it is
+ * found from a built `dist/lib/` and from `src/lib/` under tsx alike.
+ */
+export declare function resolvePluginDir(baseDirOverride?: string): string | null;
+/** What the launcher knows about a launch that the mod shows. */
+export interface PluginLaunch {
+    gatewayHost: string;
+    apiUrl: string;
+    agent: string;
+    conversationId: string;
+    cellNote: string;
+    shape: "terminal" | "remote-control" | "server";
+    /** The sealed contract's sha (envelope.sha) when one rides along. */
+    contractSha?: string;
+    /** The sealed contract's canonical JSON (envelope.canonical) when one rides along. */
+    contract?: string;
+    /**
+     * The launcher's goal-mode header when no contract is sealed (`implicit[; max_turns=N; …]`),
+     * or null.
+     */
+    goalMode?: string | null;
+    /** The argv that runs this `mnemom` again (`[process.execPath, ...process.execArgv, process.argv[1]]`). */
+    launcherExec?: readonly string[];
+    scenario: string;
+    launcherVersion: string;
+}
+/**
+ * The `MNEMOM_CC_*` block for the child env. Pure: no key, no header, nothing the gateway
+ * authenticates with — just what the launch log already prints to stderr.
+ */
+export declare function buildPluginEnv(launch: PluginLaunch): Record<PluginEnvName, string>;
+/** Writes the block onto a child env in place (the launch shapes all build their env first). */
+export declare function applyPluginEnv(childEnv: NodeJS.ProcessEnv, launch: PluginLaunch): void;
+/**
+ * Appends the plugin folder to CLAUDE_CODE_PLUGIN_DIRS (for the headless `remote-control` server,
+ * which takes no `--plugin-dir`): a user's own list is kept, the folder is added once.
+ */
+export declare function appendPluginDirsEnv(childEnv: NodeJS.ProcessEnv, pluginDir: string): void;
+/** The line the launch log and the dry-run plan print for the plugin. */
+export declare function pluginPlanLine(pluginDir: string | null | undefined, enabled: boolean): string;

package/dist/lib/claude-plugin.js

@@ -0,0 +1,149 @@
+/**
+ * The bundled "Mnemom for Claude Code" plugin (`cli/plugins/mnemom`): a Claude Code
+ * mod + skill + MCP config that `mnemom agent` loads into the Claude Code it launches, so the
+ * session SHOWS it is governed — the Mnemom band above the prompt, `/mnemom` commands, the ◆ sign
+ * on the spinner, Mnemom trailers in commit attribution, and a guard that keeps the routing in
+ * place.
+ *
+ * The launcher tells the mod about the launch through NON-SECRET env vars. They carry a distinct
+ * `MNEMOM_CC_*` prefix so they can never be confused with the launcher's own `MNEMOM_AGENT_*`
+ * inputs, and none of them is a key, a header value or anything derived from one: the mod reads
+ * them by literal name (`claude plugin validate` lists every name), and a stray `env` dump of the
+ * child shows nothing it should not.
+ *
+ * Only Claude Code proper (`cli.name === "claude"`) understands `--plugin-dir`; every other
+ * adapter launches without the plugin.
+ *
+ * OFF BY DEFAULT, AND NOT IN THE PUBLISHED PACKAGE YET. The plugin is committed under
+ * `cli/plugins/` but `package.json` `files` leaves it out of the npm tarball, so an installed
+ * `mnemom` has no folder to load and never looks for one. `--plugin` or
+ * MNEMOM_AGENT_PLUGIN=1|true|yes|on opts a launch in (`--no-plugin` or 0|false|off|no wins over
+ * the env); from a source checkout that loads the folder, from an install it says the folder is
+ * not there and launches without it. Turning it on for everyone later is two edits: `plugins`
+ * back into `files`, and `pluginEnabled`'s default to true. It never blocks the launch.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The plugin's `name` in its plugin.json, and its folder under `cli/plugins/`. */
+export const CLAUDE_PLUGIN_NAME = "mnemom";
+/** The env Claude Code reads a path list of extra plugin folders from (where no flag can be given). */
+export const CLAUDE_PLUGIN_DIRS_ENV = "CLAUDE_CODE_PLUGIN_DIRS";
+/** The env vars the launcher exports for the mod. Every value is non-secret. */
+export const PLUGIN_ENV = {
+    /** `https://gateway.mnemom.ai` (no path): presence = the session is governed. */
+    gatewayHost: "MNEMOM_CC_GATEWAY_HOST",
+    /** The public API origin the Trust Rating is read from (`https://api.mnemom.ai`). */
+    apiUrl: "MNEMOM_CC_API_URL",
+    /** The governed agent's name (the `x-mnemom-agent` header's value). */
+    agent: "MNEMOM_CC_AGENT",
+    conversationId: "MNEMOM_CC_CONVERSATION_ID",
+    /** The cell note the launch log prints (`us-2/prod`, or `custom (<host>)`). */
+    cell: "MNEMOM_CC_CELL",
+    /** `terminal` | `remote-control` | `server`. */
+    shape: "MNEMOM_CC_SHAPE",
+    /** `sealed` (a contract rides in the header) | `implicit` | `off`. */
+    goalMode: "MNEMOM_CC_GOAL_MODE",
+    /** The sealed contract's sha256[0:16]; empty unless sealed. */
+    contractSha: "MNEMOM_CC_CONTRACT_SHA",
+    /**
+     * The sealed contract itself — the canonical JSON the gateway hashes (statement, requirements,
+     * allowed/forbidden paths, ceilings). Empty unless sealed. It is what `--goal`/`--requirement`/…
+     * said on the command line: the person's own words, no secret in it.
+     */
+    contract: "MNEMOM_CC_CONTRACT",
+    /**
+     * The implicit mode's guardrail ceilings, `max_turns=N; budget_usd=X; stall_turns=N` (the
+     * `x-mnemom-goal-mode` header minus its leading `implicit`). Empty unless implicit with ceilings.
+     */
+    guardrails: "MNEMOM_CC_GUARDRAILS",
+    /**
+     * How to run this very `mnemom` again, as a JSON argv (`[node, ...execArgv, script]`): the mod
+     * runs `mnemom agent show <conversation> --json` / `mnemom agent goal show …` through it to read
+     * the live goal state (the sealed verdict, the inferred goal, guardrail usage). The CLI
+     * authenticates with the launch key from its own ledger; the mod never holds the key.
+     */
+    launcherExec: "MNEMOM_CC_LAUNCHER_EXEC",
+    /** The `mnemom agent <session>` scenario name. */
+    session: "MNEMOM_CC_SESSION",
+    launcherVersion: "MNEMOM_CC_LAUNCHER_VERSION",
+};
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/**
+ * Whether this launch loads the plugin: `--plugin` / `--no-plugin` (an explicit boolean) wins,
+ * then MNEMOM_AGENT_PLUGIN (1/true/yes/on ⇒ on), else OFF: the plugin is not published yet.
+ */
+export function pluginEnabled(optionPlugin, env) {
+    if (optionPlugin !== undefined)
+        return optionPlugin;
+    const raw = (env.MNEMOM_AGENT_PLUGIN ?? "").trim().toLowerCase();
+    return TRUTHY.has(raw);
+}
+/**
+ * The bundled plugin's folder (the one holding `.claude-plugin/plugin.json`), or null when it is
+ * missing. Lives at `<package>/plugins/mnemom`, next to `dist/` and `src/`, so it is
+ * found from a built `dist/lib/` and from `src/lib/` under tsx alike.
+ */
+export function resolvePluginDir(baseDirOverride) {
+    const here = baseDirOverride ?? dirname(fileURLToPath(import.meta.url));
+    const dir = join(here, "..", "..", "plugins", CLAUDE_PLUGIN_NAME);
+    return existsSync(join(dir, ".claude-plugin", "plugin.json")) ? dir : null;
+}
+/** Header-free, newline-free: a value that ends up in a child env and, later, on a band. */
+function clean(v) {
+    return v.replace(/[\r\n]+/g, " ").trim();
+}
+/**
+ * The `MNEMOM_CC_*` block for the child env. Pure: no key, no header, nothing the gateway
+ * authenticates with — just what the launch log already prints to stderr.
+ */
+export function buildPluginEnv(launch) {
+    const sealed = Boolean(launch.contractSha);
+    const implicit = !sealed && /^implicit(\s*;|$)/.test((launch.goalMode ?? "").trim());
+    const goalMode = sealed ? "sealed" : implicit ? "implicit" : "off";
+    // `implicit; max_turns=40; budget_usd=5` → `max_turns=40; budget_usd=5`.
+    const guardrails = implicit
+        ? clean(launch.goalMode ?? "")
+            .replace(/^implicit\s*;?\s*/, "")
+            .trim()
+        : "";
+    const exec = (launch.launcherExec ?? []).map(clean).filter(Boolean);
+    return {
+        [PLUGIN_ENV.gatewayHost]: clean(launch.gatewayHost).replace(/\/+$/, ""),
+        [PLUGIN_ENV.apiUrl]: clean(launch.apiUrl).replace(/\/+$/, ""),
+        [PLUGIN_ENV.agent]: clean(launch.agent),
+        [PLUGIN_ENV.conversationId]: clean(launch.conversationId),
+        [PLUGIN_ENV.cell]: clean(launch.cellNote),
+        [PLUGIN_ENV.shape]: launch.shape,
+        [PLUGIN_ENV.goalMode]: goalMode,
+        [PLUGIN_ENV.contractSha]: clean(launch.contractSha ?? ""),
+        [PLUGIN_ENV.contract]: sealed ? clean(launch.contract ?? "") : "",
+        [PLUGIN_ENV.guardrails]: guardrails,
+        [PLUGIN_ENV.launcherExec]: exec.length > 0 ? JSON.stringify(exec) : "",
+        [PLUGIN_ENV.session]: clean(launch.scenario),
+        [PLUGIN_ENV.launcherVersion]: clean(launch.launcherVersion),
+    };
+}
+/** Writes the block onto a child env in place (the launch shapes all build their env first). */
+export function applyPluginEnv(childEnv, launch) {
+    for (const [k, v] of Object.entries(buildPluginEnv(launch)))
+        childEnv[k] = v;
+}
+/**
+ * Appends the plugin folder to CLAUDE_CODE_PLUGIN_DIRS (for the headless `remote-control` server,
+ * which takes no `--plugin-dir`): a user's own list is kept, the folder is added once.
+ */
+export function appendPluginDirsEnv(childEnv, pluginDir) {
+    const have = (childEnv[CLAUDE_PLUGIN_DIRS_ENV] ?? "").split(delimiter).filter(Boolean);
+    if (have.includes(pluginDir))
+        return;
+    childEnv[CLAUDE_PLUGIN_DIRS_ENV] = [...have, pluginDir].join(delimiter);
+}
+/** The line the launch log and the dry-run plan print for the plugin. */
+export function pluginPlanLine(pluginDir, enabled) {
+    if (!enabled)
+        return "off";
+    if (!pluginDir)
+        return "off (the plugin folder is not in this install — run from a source checkout)";
+    return `${CLAUDE_PLUGIN_NAME} (${pluginDir})`;
+}

package/dist/lib/oauth.d.ts

@@ -83,7 +83,9 @@ export interface LoopbackResult {
  * for refresh). `openUrl` is injectable so tests can drive the flow without
  * spawning a real browser.
  */
-export declare function loginWithLoopback(openUrl?: (url: string) => void): Promise<LoopbackResult>;
+export declare function loginWithLoopback(openUrl?: (url: string) => void, opts?: {
+    inviteToken?: string;
+}): Promise<LoopbackResult>;
 export interface DeviceResult {
     tokens: OAuthTokens;
     clientId: string;

package/dist/lib/oauth.js

@@ -146,7 +146,7 @@ function tokensFromResponse(data) {
  * for refresh). `openUrl` is injectable so tests can drive the flow without
  * spawning a real browser.
  */
-export async function loginWithLoopback(openUrl = openBrowser) {
+export async function loginWithLoopback(openUrl = openBrowser, opts = {}) {
     const meta = await discover();
     const pkce = generatePkce();
     const state = crypto.randomBytes(16).toString("hex");
@@ -164,6 +164,12 @@ export async function loginWithLoopback(openUrl = openBrowser) {
     authUrl.searchParams.set("state", state);
     authUrl.searchParams.set("code_challenge", pkce.challenge);
     authUrl.searchParams.set("code_challenge_method", pkce.method);
+    // A Mnemom Agent invitation (`mnemom agent --invite`) rides along so a NEW
+    // invitee who signs up in this browser round-trip skips the confirmation
+    // email: the AS ignores the param but bounces a signed-out browser to /login
+    // with this exact URL as return_to, and sign-up forwards the token to the api.
+    if (opts.inviteToken)
+        authUrl.searchParams.set("invite_token", opts.inviteToken);
     console.log("Opening browser to authenticate...");
     console.log(`If the browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
     openUrl(authUrl.toString());
@@ -234,6 +240,12 @@ function startLoopbackServer(expectedState) {
                 close: () => {
                     clearTimeout(timeout);
                     server.close();
+                    // The browser keeps idle keep-alive sockets (incl. Chrome's spare
+                    // preconnect) open while the tab stays up; server.close() alone waits
+                    // on them, so `mnemom login` printed success and then sat there until
+                    // the tab was closed. Drop them — the callback response is already sent.
+                    // Optional call: closeAllConnections() landed in Node 18.2 (engines allow 18.0).
+                    server.closeAllConnections?.();
                 },
             });
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.19",
+  "version": "0.17.20",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {