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

package/dist/commands/code-doctor.js

@@ -98,7 +98,7 @@ export async function codeDoctorCommand(options = {}) {
     out("");
     const launchReady = !lines.some((l) => l.mark === "miss");
     if (launchReady) {
-        out("  Ready to launch:  mnemom code <scenario>");
+        out("  Ready to launch:  mnemom code");
     }
     else {
         out("  Not launch-ready — resolve the [MISS] items above.");

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

@@ -59,7 +59,6 @@ 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;
@@ -70,7 +69,8 @@ export interface CodeInvocation {
 }
 export interface CodeInvocationDeps {
     redeem: (token: string | undefined) => Promise<unknown>;
-    launch: (scenario: string) => Promise<void>;
+    /** The launch half; `undefined` = no session name given (the launcher prompts in a terminal). */
+    launch: (scenario: string | undefined) => Promise<void>;
 }
 /**
  * How the `code` command's positional + `--invite` compose — kept OUT of
@@ -79,6 +79,6 @@ export interface CodeInvocationDeps {
  *   - `mnemom code --invite <token>`          → redeem, done
  *   - `mnemom code --invite <token> <scen>`   → redeem, then launch
  *   - `mnemom code <scen>`                    → launch
- *   - `mnemom code`                           → error with guidance
+ *   - `mnemom code`                           → launch (the launcher asks for a name + goal)
  */
 export declare function runCodeInvocation(input: CodeInvocation, deps: CodeInvocationDeps): Promise<void>;

package/dist/commands/code-invite.js

@@ -132,7 +132,7 @@ export function printAccepted(res) {
     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>"));
+    say(fmt.dim("  Start a governed session:  mnemom code"));
 }
 /**
  * `mnemom code --invite <token>` / `mnemom code invite <token>`: sign in, redeem,
@@ -166,8 +166,6 @@ export async function codeInviteCommand(token, opts = {}) {
     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:
@@ -175,7 +173,7 @@ export const NO_SCENARIO_MESSAGE = "mnemom code: a <scenario> slug is required (
  *   - `mnemom code --invite <token>`          → redeem, done
  *   - `mnemom code --invite <token> <scen>`   → redeem, then launch
  *   - `mnemom code <scen>`                    → launch
- *   - `mnemom code`                           → error with guidance
+ *   - `mnemom code`                           → launch (the launcher asks for a name + goal)
  */
 export async function runCodeInvocation(input, deps) {
     if (input.scenario === "invite") {
@@ -187,7 +185,5 @@ export async function runCodeInvocation(input, deps) {
         if (!input.scenario)
             return;
     }
-    if (!input.scenario)
-        throw new Error(NO_SCENARIO_MESSAGE);
     await deps.launch(input.scenario);
 }

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

@@ -0,0 +1,52 @@
+/**
+ * `mnemom code` with no session name — the interactive first-run setup.
+ *
+ * The daily command is just `mnemom code` (the Claude Code pattern: install
+ * once, then the bare command). When the positional session name is omitted in
+ * a terminal we ask two things, explaining each in a sentence:
+ *
+ *   1. a SESSION NAME — labels the session in traces and the claude.ai session
+ *      list (defaults to the current folder's name);
+ *   2. an optional GOAL — one line. With a goal, Mnemom seals a goal contract
+ *      for the session and the judge nudges the agent back when it drifts (a
+ *      little µ per turn). Without one, the session runs governed but with goal
+ *      alignment OFF: no contract header is sent, so the gateway's goal hook is
+ *      simply not engaged for the conversation.
+ *
+ * Non-interactive runs (pipes, CI) never prompt — they get a clear error asking
+ * for a name. `--goal` on the command line always wins over the prompt. Pure
+ * apart from the injected `ask` functions, so every arm is unit-tested.
+ */
+export interface SessionAsk {
+    askInput(question: string): Promise<string>;
+    askYesNo(question: string, defaultYes: boolean): Promise<boolean>;
+}
+export interface SessionSetupInput {
+    /** The positional `[scenario]` (session name), if given. */
+    scenario?: string;
+    /** `--goal <statement>`, if given — skips the goal prompt. */
+    goal?: string;
+    interactive: boolean;
+    /** For the default session name (tests inject one). */
+    cwd?: string;
+    /** Narration sink (stderr by default; tests capture). */
+    say?: (line?: string) => void;
+}
+export interface SessionSetup {
+    scenario: string;
+    /** The goal statement to seal, or undefined = goal alignment off. */
+    goal?: string;
+    goalAlignment: "on" | "off";
+    /** True when the terminal prompts ran. */
+    prompted: boolean;
+}
+export declare const NO_SESSION_NAME_MESSAGE: string;
+/** Current folder name, sanitised like an agent slug; "session" when that is empty. */
+export declare function defaultSessionName(cwd?: string): string;
+/** The one-line status printed at launch so the customer always knows the mode. */
+export declare function goalAlignmentLine(on: boolean): string;
+/**
+ * Resolve the session name + goal for this launch. See the module doc for the
+ * rules. Throws NO_SESSION_NAME_MESSAGE when no name was given and we cannot ask.
+ */
+export declare function resolveSessionSetup(input: SessionSetupInput, ask: SessionAsk): Promise<SessionSetup>;

package/dist/commands/code-session.js

@@ -0,0 +1,78 @@
+/**
+ * `mnemom code` with no session name — the interactive first-run setup.
+ *
+ * The daily command is just `mnemom code` (the Claude Code pattern: install
+ * once, then the bare command). When the positional session name is omitted in
+ * a terminal we ask two things, explaining each in a sentence:
+ *
+ *   1. a SESSION NAME — labels the session in traces and the claude.ai session
+ *      list (defaults to the current folder's name);
+ *   2. an optional GOAL — one line. With a goal, Mnemom seals a goal contract
+ *      for the session and the judge nudges the agent back when it drifts (a
+ *      little µ per turn). Without one, the session runs governed but with goal
+ *      alignment OFF: no contract header is sent, so the gateway's goal hook is
+ *      simply not engaged for the conversation.
+ *
+ * Non-interactive runs (pipes, CI) never prompt — they get a clear error asking
+ * for a name. `--goal` on the command line always wins over the prompt. Pure
+ * apart from the injected `ask` functions, so every arm is unit-tested.
+ */
+import { basename } from "node:path";
+import { sanitizeAgentName } from "../lib/code.js";
+export const NO_SESSION_NAME_MESSAGE = "mnemom code: a session name is required here (e.g. `mnemom code onboarding`). " +
+    "In a terminal, plain `mnemom code` asks for one.";
+/** Current folder name, sanitised like an agent slug; "session" when that is empty. */
+export function defaultSessionName(cwd = process.cwd()) {
+    return sanitizeAgentName(basename(cwd)) || "session";
+}
+/** The one-line status printed at launch so the customer always knows the mode. */
+export function goalAlignmentLine(on) {
+    return on
+        ? "mnemom code: goal alignment: on (the judge nudges the agent back when it drifts from your goal)"
+        : "mnemom code: goal alignment: off (no goal set — pass --goal or set one when prompted)";
+}
+const defaultSay = (line = "") => console.error(line);
+/**
+ * Resolve the session name + goal for this launch. See the module doc for the
+ * rules. Throws NO_SESSION_NAME_MESSAGE when no name was given and we cannot ask.
+ */
+export async function resolveSessionSetup(input, ask) {
+    const say = input.say ?? defaultSay;
+    const flagGoal = (input.goal ?? "").trim();
+    const given = (input.scenario ?? "").trim();
+    if (given) {
+        return {
+            scenario: given,
+            goal: flagGoal || undefined,
+            goalAlignment: flagGoal ? "on" : "off",
+            prompted: false,
+        };
+    }
+    if (!input.interactive)
+        throw new Error(NO_SESSION_NAME_MESSAGE);
+    // ── 1. session name ──
+    const fallback = defaultSessionName(input.cwd);
+    say();
+    say("Session name — labels this session in your traces and the claude.ai session list.");
+    say(`  (Next time you can pass it directly: mnemom code <name>.)`);
+    const typed = await ask.askInput(`Session name [${fallback}]:`);
+    const scenario = sanitizeAgentName(typed.trim()) || fallback;
+    // ── 2. goal (skipped when --goal was given) ──
+    if (flagGoal) {
+        return { scenario, goal: flagGoal, goalAlignment: "on", prompted: true };
+    }
+    say();
+    say("Goal alignment — an optional one-line goal for this session.");
+    say("  With a goal, Mnemom's judge watches each turn and nudges the agent back when it drifts");
+    say("  (a little µ per turn). Without one, the session runs governed with goal alignment off.");
+    const wantsGoal = await ask.askYesNo("Set a goal for this session?", true);
+    if (!wantsGoal) {
+        return { scenario, goalAlignment: "off", prompted: true };
+    }
+    const goal = (await ask.askInput("Goal (one line):")).trim();
+    if (!goal) {
+        say("  No goal entered — continuing with goal alignment off.");
+        return { scenario, goalAlignment: "off", prompted: true };
+    }
+    return { scenario, goal, goalAlignment: "on", prompted: true };
+}

package/dist/commands/code-setup.js

@@ -23,7 +23,7 @@
  * birthThroughGateway (wrap.ts), deriveHashProof (agents.ts), claimAgent +
  * putAlignmentCard/putProtectionCard (lib/api.ts) — rather than reinventing it.
  */
-import { claimAgent, getAgentByName, getMuBalance, getMyPersonalOrg, MnemomApiError, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
+import { claimAgent, getAgentByName, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
 import { getAuthInfo, isLoggedIn, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
 import { getWebsiteUrl } from "../lib/config.js";
@@ -63,8 +63,18 @@ export async function ensureGovernedAgent(opts) {
     const loggedIn = await isLoggedIn();
     if (loggedIn) {
         const existing = await getAgentByName(slug).catch(() => null);
-        if (existing)
+        if (existing) {
+            // On an EXPLICIT `mnemom code setup`, repair/complete the cards on the
+            // already-claimed agent (e.g. a protection card that failed on a prior run
+            // before we minted its one-time grant). A bare launch leaves it alone.
+            if (opts.setup === true) {
+                say(fmt.dim(`mnemom code: '${slug}' is already claimed — refreshing its cards.`));
+                await publishDefaultCards(existing.id);
+                persistAgentSlug(slug);
+                return { slug, provisioned: true };
+            }
             return { slug, provisioned: false };
+        }
     }
     // 2. Are we allowed to provision here?
     const canProvision = opts.setup === true || (opts.setup !== false && interactive);
@@ -138,6 +148,18 @@ async function tryPublishCard(name, write) {
 /** 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"));
+    // Protection is the "locked door": it needs a one-time cards:write:protection
+    // grant that the claim does NOT include (alignment rides a standing cap). Mint
+    // it with our human login JWT — the "Provision and claim?" confirm is the
+    // explicit human approval, and the mint endpoint accepts a human operator (only
+    // agent OAuth principals are rejected). The next write consumes the grant. A
+    // mint failure falls through to the write's retry + graceful degrade.
+    try {
+        await mintProtectionCapability(agentId);
+    }
+    catch {
+        // best effort — the protection write below surfaces the real, actionable error
+    }
     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)."));
@@ -148,7 +170,9 @@ async function publishDefaultCards(agentId) {
     for (const c of [align, prot]) {
         if (c.ok)
             continue;
-        const publishCmd = c.name === "alignment" ? "mnemom card publish" : "mnemom protection publish";
+        // Alignment rides a standing cap, so `mnemom card publish` finishes it; the
+        // protection grant is one-time, so re-running setup (which re-mints) is the fix.
+        const publishCmd = c.name === "alignment" ? "mnemom card publish" : "mnemom code setup";
         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}\`.`));
     }

package/dist/commands/code.d.ts

@@ -64,8 +64,8 @@ export interface CodeOptions {
     /** Print the resolved launch plan and exit — no key read, no spawn. */
     dryRun?: boolean;
 }
-/** Entry point for `mnemom code <scenario>`. Throws on fatal misconfig. */
-export declare function codeCommand(scenario: string, options?: CodeOptions): Promise<void>;
+/** Entry point for `mnemom code [scenario]`. Throws on fatal misconfig. */
+export declare function codeCommand(scenarioArg: string | undefined, options?: CodeOptions): Promise<void>;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
  * customer adoption), in order:

package/dist/commands/code.js

@@ -34,16 +34,18 @@ 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 { goalAlignmentLine, resolveSessionSetup } from "./code-session.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");
 const say = (line = "") => console.error(line);
-/** Entry point for `mnemom code <scenario>`. Throws on fatal misconfig. */
-export async function codeCommand(scenario, options = {}) {
-    if (!scenario || !scenario.trim()) {
-        throw new Error("mnemom code: a <scenario> slug is required (e.g. `mnemom code onboarding`).");
-    }
+/** Entry point for `mnemom code [scenario]`. Throws on fatal misconfig. */
+export async function codeCommand(scenarioArg, options = {}) {
+    // ── session name + goal ── (a bare `mnemom code` in a terminal asks for both,
+    // explaining goal alignment; no goal ⇒ no contract header ⇒ goal alignment off)
+    const session = await resolveSessionSetup({ scenario: scenarioArg, goal: options.goal, interactive: isInteractive() }, { askInput: (q) => askInput(q), askYesNo: (q, d) => askYesNo(q, d) });
+    const scenario = session.scenario;
     const env = process.env;
     let shape = resolveLaunchShape({ remoteControl: options.remoteControl, server: options.server }, env);
     const shapeExplicit = launchPreferenceExplicit({ remoteControl: options.remoteControl, server: options.server }, env);
@@ -58,7 +60,7 @@ export async function codeCommand(scenario, options = {}) {
     const conversationId = resolveConversationId(options.conversationId);
     // ── contract (built only if a contract flag was given; --goal then required) ──
     const envelope = assembleContract({
-        goal: options.goal,
+        goal: session.goal,
         requirement: options.requirement,
         allow: options.allow,
         forbid: options.forbid,
@@ -107,7 +109,17 @@ export async function codeCommand(scenario, options = {}) {
             bin: "(not found — pass --cli <path> or `mnemom code config set cli <path>`)",
             name: basename((options.cli || env.MNEMOM_CODE_CLI || "claude").trim()),
         };
-        printPlan({ scenario, shape, agent, conversationId, door, cellNote, envelope, yolo, cli: planCli });
+        printPlan({
+            scenario,
+            shape,
+            agent,
+            conversationId,
+            door,
+            cellNote,
+            envelope,
+            yolo,
+            cli: planCli,
+        });
         return;
     }
     // Real launch: make sure we actually have a CLI to run. If we couldn't find it,
@@ -163,6 +175,7 @@ export async function codeCommand(scenario, options = {}) {
         }
     }
     logLaunch({ shape, door, agent, conversationId, cellNote, envelope, cli });
+    say(goalAlignmentLine(envelope !== null));
     if (shape === "terminal") {
         launchTerminal({
             cli,

package/dist/index.js

@@ -82,7 +82,7 @@ program
 });
 // ── code — first-class governed coding-agent launcher ────────────────────────
 //
-// `mnemom code <scenario>` launches your coding-agent CLI (Claude Code in v1) with
+// `mnemom code [scenario]` launches your coding-agent CLI (Claude Code in v1) with
 // its dev-time model traffic routed through the Mnemom gateway's /anthropic door
 // for observability + governance, under a governed agent identity (the
 // program-level `--agent`, default "code-agent") and an optional per-conversation
@@ -101,7 +101,7 @@ const collectRepeatable = (value, previous) => {
 };
 program
     .command("code [scenario] [passthrough...]")
-    .description("Launch a governed coding agent through the Mnemom gateway (governed identity + optional sealed contract). " +
+    .description("Launch a governed coding agent through the Mnemom gateway (governed identity + optional sealed contract). Plain `mnemom code` asks for a session name and an optional goal. " +
     "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, [])
@@ -125,7 +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("--invite <token>", "Redeem a Mnemom Code invitation (pinv_…): unlocks Mnemom Code for you + credits your starter µ; launches too when a session name 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)")

package/dist/lib/api.d.ts

@@ -394,6 +394,16 @@ export interface MuBalance {
     enforcementPausedReason?: string | null;
 }
 export declare function getMuBalance(orgId?: string): Promise<MuBalance>;
+/**
+ * Mint the one-time `cards:write:protection` capability for an agent — the
+ * "locked door" that a plain claim does NOT grant (alignment is a standing cap;
+ * protection is one-time, 15-min TTL, single-use). `POST
+ * /v1/agents/:id/protection-capability` (MNE-876) requires a HUMAN operator
+ * (rejects agent OAuth principals) with org co-manage of the agent, so the CLI's
+ * own login JWT can mint it — no browser grant needed. Consumed by the very next
+ * protection-card write.
+ */
+export declare function mintProtectionCapability(agentId: string): Promise<void>;
 export interface TeamListItem {
     team_id: string;
     name: string;

package/dist/lib/api.js

@@ -379,6 +379,18 @@ export async function getMuBalance(orgId) {
     const q = orgId ? `?org_id=${encodeURIComponent(orgId)}` : "";
     return gFetch(`/v1/billing/mu${q}`, {}, { fallback: "Could not read MU balance" });
 }
+/**
+ * Mint the one-time `cards:write:protection` capability for an agent — the
+ * "locked door" that a plain claim does NOT grant (alignment is a standing cap;
+ * protection is one-time, 15-min TTL, single-use). `POST
+ * /v1/agents/:id/protection-capability` (MNE-876) requires a HUMAN operator
+ * (rejects agent OAuth principals) with org co-manage of the agent, so the CLI's
+ * own login JWT can mint it — no browser grant needed. Consumed by the very next
+ * protection-card write.
+ */
+export async function mintProtectionCapability(agentId) {
+    await gFetch(`/v1/agents/${encodeURIComponent(agentId)}/protection-capability`, { method: "POST" }, { fallback: "Could not mint the protection capability" });
+}
 /**
  * GET /v1/orgs/:org_id/teams for every org the user is a member of,
  * concatenated. The CLI consumer that just wants "every team I can see"

package/package.json

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