@mnemom/mnemom 0.17.32-next.4 → 0.17.33

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

@@ -44,7 +44,16 @@ export interface FuelDeps {
     readCommitted(root: string, path: string): string;
     out(line: string): void;
     err(line: string): void;
+    /** Wait this many seconds (a 429's Retry-After); injected so tests never sleep. */
+    sleep?(seconds: number): Promise<void>;
 }
+/**
+ * How many times a 429 (the org's seal budget, Doors W5.9) is waited out before giving up. Each
+ * resend carries the same key, so a refused batch is sealed exactly once when it gets through.
+ */
+export declare const RATE_LIMIT_RETRIES = 5;
+/** Seconds to wait before resending, for a 429; null for anything else. */
+export declare function rateLimitWait(error: unknown): number | null;
 /** A contract the lead drafted, checked and hashed locally before anything is sent. */
 interface DraftedContract {
     contract: Contract;

package/dist/commands/agent-fuel.js

@@ -16,6 +16,21 @@ import { dirname, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { listMyOrgs, MnemomApiError, newIdempotencyKey, sealContractBatch, } from "../lib/api.js";
 import { checkContract, contractFileText, contractRepoPath, contractSha256, } from "../lib/contract-hash.js";
+/**
+ * How many times a 429 (the org's seal budget, Doors W5.9) is waited out before giving up. Each
+ * resend carries the same key, so a refused batch is sealed exactly once when it gets through.
+ */
+export const RATE_LIMIT_RETRIES = 5;
+/** The longest single wait, whatever Retry-After says; the api's window is 60 s. */
+const RATE_LIMIT_WAIT_MAX_S = 60;
+/** Seconds to wait before resending, for a 429; null for anything else. */
+export function rateLimitWait(error) {
+    if (!(error instanceof MnemomApiError) || error.effectiveStatus !== 429)
+        return null;
+    const after = error.details?.retry_after_s;
+    const seconds = typeof after === "number" && Number.isFinite(after) && after > 0 ? after : 1;
+    return Math.min(Math.ceil(seconds), RATE_LIMIT_WAIT_MAX_S);
+}
 /** `owner/name` as GitHub issues it, the same rule the api applies: never `.` or `..` as a name. */
 const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/(?!\.\.?$)[A-Za-z0-9_.-]{1,100}$/;
 /** The batch size the api enforces. */
@@ -142,16 +157,32 @@ export async function agentFuelCommand(file, opts, deps) {
         source: "cli",
         contracts: drafted.map((d) => d.jobKey ? { contract: d.contract, job_key: d.jobKey } : { contract: d.contract }),
     };
+    // A 429 is the org's seal budget (W5.9): wait out Retry-After and resend the same request, so a
+    // burst is delayed, never dropped. The api refused it before writing anything.
+    const send = async () => {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await deps.seal(orgId, body, key, githubToken);
+            }
+            catch (error) {
+                const wait = rateLimitWait(error);
+                if (wait === null || attempt >= RATE_LIMIT_RETRIES)
+                    throw error;
+                deps.err(`The organization's seal budget is spent; resending in ${wait} s.`);
+                await (deps.sleep ?? sleepSeconds)(wait);
+            }
+        }
+    };
     let result;
     try {
-        result = await deps.seal(orgId, body, key, githubToken);
+        result = await send();
     }
     catch (error) {
         // A 5xx or a network fault may have reached the api, so retry once with the same key. A 4xx
         // is the api's answer and is not retried.
         if (!(error instanceof MnemomApiError) || error.effectiveStatus >= 500) {
             try {
-                result = await deps.seal(orgId, body, key, githubToken);
+                result = await send();
             }
             catch (retryError) {
                 // The api may have sealed before failing; the same key replays that batch, never a second one.
@@ -238,6 +269,9 @@ export function resolveGithubToken(env = process.env, gh = ghAuthToken) {
 export function readFuelInput(path, read = readFileSync) {
     return read(path === "-" ? 0 : path, "utf8");
 }
+function sleepSeconds(seconds) {
+    return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
 export const liveFuelDeps = {
     readInput: (path) => readFuelInput(path),
     listOrgs: () => listMyOrgs(),

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

@@ -0,0 +1,50 @@
+/**
+ * `mnemom agent run --watch|--once` (ruling 34.12; Doors W-L13, W3.11, W4.4, W4.12): the thin
+ * runner's driver.
+ *
+ * Everything that decides an outcome lives in lib/runner (and holds no prompts); this file only
+ * wires it to the world: the credential (env key, or the --oidc exchange), the executor client,
+ * the job's working copy, the phases' child processes, the PR, and SIGTERM/SIGINT. Usage and config
+ * errors exit 2 with no outcome line; every outcome line goes to stdout, every log to stderr.
+ *
+ * The GitHub token (GH_TOKEN, GITHUB_TOKEN, else `gh auth token`) is the runner's own: it reaches
+ * git only through GIT_CONFIG_* env (never argv) and the phases never see it (phaseEnv).
+ */
+import { type FetchFn, type RunnerApi } from "../lib/runner/executor-client.js";
+import type { JobDeps, Workspace } from "../lib/runner/job.js";
+import { type PhaseInvocation } from "../lib/runner/phases.js";
+import { type RunFlags } from "../lib/runner/options.js";
+export interface RunDeps {
+    env: NodeJS.ProcessEnv;
+    fetch: FetchFn;
+    apiUrl: string;
+    /** stdout: one outcome line per job. */
+    emit(line: string): void;
+    /** stderr. */
+    err(line: string): void;
+    /** Aborted by SIGTERM or SIGINT. */
+    stop: AbortSignal;
+    jobDeps(api: RunnerApi): JobDeps;
+}
+/** Resolves the process exit code; never throws for a usage, config or Mnemom error. */
+export declare function agentRunCommand(flags: RunFlags, deps: RunDeps): Promise<number>;
+export declare const GITHUB_API = "https://api.github.com";
+/** git's env with the token as an http extra header: it never reaches argv or the remote URL. */
+export declare function gitAuthEnv(parent: NodeJS.ProcessEnv, token: string | null): NodeJS.ProcessEnv;
+export type Git = (cwd: string | undefined, args: string[]) => Promise<string>;
+export declare function liveGit(env: NodeJS.ProcessEnv): Git;
+/** A fresh clone on a job branch, plus a fresh, empty HOME for the phases. */
+export declare function prepareWorkspace(git: Git, cloneUrl: string, sessionId: string, root?: string): Promise<Workspace>;
+export declare function cleanupWorkspace(ws: Workspace): Promise<void>;
+/** Push the job branch and open its PR against the repo's default branch; resolves its URL. */
+export declare function openPr(git: Git, fetch: FetchFn, token: string | null, repo: string, ws: Workspace, title: string): Promise<string>;
+/** merge_on_green: GitHub's auto-merge on the PR (squash). */
+export declare function enableAutoMerge(fetch: FetchFn, token: string | null, prUrl: string): Promise<void>;
+/** Run one phase's process in the job's working copy; stdout goes to our stderr, never stdout. */
+export declare function runPhaseProcess(inv: PhaseInvocation, ws: Workspace, modelUrl: string, signal: AbortSignal, parentEnv?: NodeJS.ProcessEnv): Promise<number>;
+export declare function liveJobDeps(api: RunnerApi, opts: {
+    fetch: FetchFn;
+    env: NodeJS.ProcessEnv;
+}): JobDeps;
+/** The process wiring: signals, stdout and stderr. Resolves the exit code. */
+export declare function runAgentRun(flags: RunFlags): Promise<number>;

package/dist/commands/agent-run.js

@@ -0,0 +1,221 @@
+/**
+ * `mnemom agent run --watch|--once` (ruling 34.12; Doors W-L13, W3.11, W4.4, W4.12): the thin
+ * runner's driver.
+ *
+ * Everything that decides an outcome lives in lib/runner (and holds no prompts); this file only
+ * wires it to the world: the credential (env key, or the --oidc exchange), the executor client,
+ * the job's working copy, the phases' child processes, the PR, and SIGTERM/SIGINT. Usage and config
+ * errors exit 2 with no outcome line; every outcome line goes to stdout, every log to stderr.
+ *
+ * The GitHub token (GH_TOKEN, GITHUB_TOKEN, else `gh auth token`) is the runner's own: it reaches
+ * git only through GIT_CONFIG_* env (never argv) and the phases never see it (phaseEnv).
+ */
+import { spawn, execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getApiUrl, getGatewayUrl } from "../lib/config.js";
+import { runnerApi } from "../lib/runner/executor-client.js";
+import { runOnce, runWatch } from "../lib/runner/loop.js";
+import { exchangeOidc } from "../lib/runner/oidc.js";
+import { exitCodeFor, outcomeLine, refusedOutcome, USAGE_EXIT_CODE, } from "../lib/runner/outcome.js";
+import { phaseEnv } from "../lib/runner/phases.js";
+import { resolveRunPlan } from "../lib/runner/options.js";
+import { startModelProxy } from "../lib/runner/proxy.js";
+import { resolveGithubToken } from "./agent-fuel.js";
+/** Resolves the process exit code; never throws for a usage, config or Mnemom error. */
+export async function agentRunCommand(flags, deps) {
+    const resolved = resolveRunPlan(flags, deps.env);
+    if (!resolved.ok) {
+        deps.err(resolved.usage);
+        return USAGE_EXIT_CODE;
+    }
+    const plan = resolved.plan;
+    for (const w of plan.warnings)
+        deps.err(w);
+    let executorKey;
+    if (plan.credential.kind === "oidc") {
+        const ex = await exchangeOidc({
+            fetch: deps.fetch,
+            apiUrl: deps.apiUrl,
+            requestUrl: plan.credential.requestUrl,
+            requestToken: plan.credential.requestToken,
+        });
+        if (!ex.ok) {
+            // No job is held yet: fail closed whatever --fail-mode says (34.12 (6)).
+            deps.err(`mnemom agent run: refused (${ex.reason}): ${ex.detail}`);
+            const o = refusedOutcome({}, ex.reason);
+            deps.emit(outcomeLine(o));
+            return exitCodeFor(o.outcome);
+        }
+        executorKey = ex.executorKey;
+    }
+    else {
+        executorKey = plan.credential.key;
+    }
+    const api = runnerApi({ apiUrl: deps.apiUrl, executorKey, fetch: deps.fetch });
+    const loop = { failMode: plan.failMode, stop: deps.stop, emit: deps.emit };
+    const job = deps.jobDeps(api);
+    return plan.form === "once" ? runOnce(job, loop) : runWatch(job, loop);
+}
+// ── GitHub and git, for the live driver ──────────────────────────────────────
+export const GITHUB_API = "https://api.github.com";
+/** git's env with the token as an http extra header: it never reaches argv or the remote URL. */
+export function gitAuthEnv(parent, token) {
+    const env = { ...parent, GIT_TERMINAL_PROMPT: "0" };
+    if (!token)
+        return env;
+    const basic = Buffer.from(`x-access-token:${token}`, "utf8").toString("base64");
+    return {
+        ...env,
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: "http.https://github.com/.extraheader",
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${basic}`,
+    };
+}
+export function liveGit(env) {
+    return (cwd, args) => new Promise((resolve, reject) => execFile("git", args, { cwd, env, encoding: "utf8" }, (e, out, stderr) => e
+        ? reject(new Error(`git ${args[0]}: ${String(stderr).trim() || e.message}`))
+        : resolve(out.trim())));
+}
+/** A fresh clone on a job branch, plus a fresh, empty HOME for the phases. */
+export async function prepareWorkspace(git, cloneUrl, sessionId, root = tmpdir()) {
+    const dir = await mkdtemp(join(root, "mnemom-job-"));
+    const home = await mkdtemp(join(root, "mnemom-home-"));
+    const branch = `mnemom/job-${sessionId.slice(0, 8)}`;
+    try {
+        await git(undefined, ["clone", "--quiet", "--depth", "50", "--", cloneUrl, dir]);
+        await git(dir, ["checkout", "--quiet", "-b", branch]);
+        // A phase that commits needs an identity; HOME is empty, so it is set on the repo.
+        await git(dir, ["config", "user.name", "mnemom runner"]);
+        await git(dir, ["config", "user.email", "runner@mnemom.ai"]);
+    }
+    catch (e) {
+        await cleanupWorkspace({ dir, home, branch });
+        throw e;
+    }
+    return { dir, home, branch };
+}
+export async function cleanupWorkspace(ws) {
+    await Promise.all([ws.dir, ws.home].map((d) => rm(d, { recursive: true, force: true })));
+}
+async function github(fetch, token, method, path, body) {
+    if (!token)
+        throw new Error("no GitHub token (set GH_TOKEN or GITHUB_TOKEN)");
+    const res = await fetch(`${GITHUB_API}${path}`, {
+        method,
+        headers: {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${token}`,
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    let json = {};
+    try {
+        json = JSON.parse(await res.text());
+    }
+    catch {
+        // an empty or non-JSON answer: the status decides
+    }
+    return { status: res.status, json };
+}
+/** Push the job branch and open its PR against the repo's default branch; resolves its URL. */
+export async function openPr(git, fetch, token, repo, ws, title) {
+    await git(ws.dir, ["push", "--quiet", "origin", `HEAD:refs/heads/${ws.branch}`]);
+    const meta = await github(fetch, token, "GET", `/repos/${repo}`);
+    const base = meta.json.default_branch;
+    if (meta.status !== 200 || typeof base !== "string") {
+        throw new Error(`reading ${repo} answered ${meta.status}`);
+    }
+    const pr = await github(fetch, token, "POST", `/repos/${repo}/pulls`, {
+        title,
+        head: ws.branch,
+        base,
+    });
+    const url = pr.json.html_url;
+    if (pr.status !== 201 || typeof url !== "string") {
+        throw new Error(`opening the PR answered ${pr.status}`);
+    }
+    return url;
+}
+const PR_URL_RE = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)$/;
+/** merge_on_green: GitHub's auto-merge on the PR (squash). */
+export async function enableAutoMerge(fetch, token, prUrl) {
+    const m = PR_URL_RE.exec(prUrl);
+    if (!m)
+        throw new Error(`not a GitHub PR URL: ${prUrl}`);
+    const pr = await github(fetch, token, "GET", `/repos/${m[1]}/pulls/${m[2]}`);
+    if (pr.status !== 200 || typeof pr.json.node_id !== "string") {
+        throw new Error(`reading the PR answered ${pr.status}`);
+    }
+    const r = await github(fetch, token, "POST", "/graphql", {
+        query: "mutation($id: ID!) { enablePullRequestAutoMerge(input: {pullRequestId: $id, mergeMethod: SQUASH}) { clientMutationId } }",
+        variables: { id: pr.json.node_id },
+    });
+    if (r.status !== 200 || r.json.errors !== undefined) {
+        throw new Error(`enabling auto-merge answered ${r.status}`);
+    }
+}
+/** Run one phase's process in the job's working copy; stdout goes to our stderr, never stdout. */
+export function runPhaseProcess(inv, ws, modelUrl, signal, parentEnv = process.env) {
+    return new Promise((resolve, reject) => {
+        let started = false;
+        const child = spawn(inv.command, inv.args, {
+            cwd: ws.dir,
+            env: phaseEnv(parentEnv, ws.home, modelUrl),
+            stdio: ["pipe", "pipe", "inherit"],
+            signal,
+        });
+        child.on("spawn", () => {
+            started = true;
+            child.stdin?.end(inv.stdin ?? "");
+        });
+        child.stdout?.pipe(process.stderr, { end: false });
+        child.on("error", (e) => {
+            if (!started)
+                reject(e);
+        });
+        child.on("close", (code) => resolve(code ?? -1));
+    });
+}
+export function liveJobDeps(api, opts) {
+    const token = resolveGithubToken(opts.env);
+    const git = liveGit(gitAuthEnv(opts.env, token));
+    return {
+        api,
+        nonce: randomUUID(),
+        newSpawnId: () => randomUUID(),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        log: (line) => process.stderr.write(`mnemom agent run: ${line}\n`),
+        gatewayUrl: `${getGatewayUrl()}/anthropic`,
+        startProxy: (state) => startModelProxy(`${getGatewayUrl()}/anthropic`, state),
+        prepareWorkspace: (repo, sessionId) => prepareWorkspace(git, `https://github.com/${repo}.git`, sessionId),
+        runPhase: (inv, ws, modelUrl, signal) => runPhaseProcess(inv, ws, modelUrl, signal, opts.env),
+        openPr: (repo, ws, title) => openPr(git, opts.fetch, token, repo, ws, title),
+        enableAutoMerge: (prUrl) => enableAutoMerge(opts.fetch, token, prUrl),
+        cleanup: cleanupWorkspace,
+    };
+}
+/** The process wiring: signals, stdout and stderr. Resolves the exit code. */
+export function runAgentRun(flags) {
+    const stop = new AbortController();
+    const onSignal = () => stop.abort();
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+    const fetch = globalThis.fetch;
+    return agentRunCommand(flags, {
+        env: process.env,
+        fetch,
+        apiUrl: getApiUrl(),
+        emit: (line) => process.stdout.write(`${line}\n`),
+        err: (line) => process.stderr.write(`${line}\n`),
+        stop: stop.signal,
+        jobDeps: (api) => liveJobDeps(api, { fetch, env: process.env }),
+    }).finally(() => {
+        process.off("SIGTERM", onSignal);
+        process.off("SIGINT", onSignal);
+    });
+}

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

@@ -316,14 +316,19 @@ interface PublishOpts {
  */
 export declare function keptPrincipal(own: unknown, opts: Pick<PublishOpts, "orgId" | "ownOrg">): Record<string, unknown>;
 /**
- * `mnemom agent setup [--agent <slug|mnm-id>] [--governance …]` — the explicit provisioning entry
- * point. An id (`--agent mnm-<uuid>`, or launcher.toml `agent_id`) refreshes that pinned agent's
- * cards and never claims or births; a malformed `mnm-…` refuses.
+ * `mnemom agent setup [--agent <slug|mnm-id>] [--governance …] [--auth …]` — the explicit
+ * provisioning entry point. An id (`--agent mnm-<uuid>`, or launcher.toml `agent_id`) refreshes
+ * that pinned agent's cards and never claims or births; a malformed `mnm-…` refuses.
+ *
+ * The auth mode resolves as a launch's does (`--auth`, else MNEMOM_AGENT_AUTH, which launcher.toml
+ * `auth` folds into, else api-key). A subscription setup asks for no Anthropic key: the identity
+ * anchors on the Mnemom API key, exactly as the subscription launch it provisions for (MNE-9282).
  */
 export declare function agentSetupCommand(opts?: {
     agent?: string;
     agentId?: string;
     governance?: GovernanceOptIn;
+    auth?: string;
 }): Promise<void>;
 /** Thrown when the agent's org has no spendable MU balance. The user-facing
  *  top-up guidance is already printed when this is thrown — callers exit quietly. */

package/dist/commands/agent-setup.js

@@ -36,13 +36,13 @@
  * reinventing it.
  */
 import { claimAgent, getAgent, getAgentByName, getCardSources, getMe, getMuBalance, getMyPersonalOrg, listMyAgents, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
-import { getAuthInfo, loginWithBrowser, loginWithDeviceFlow, resolveAuth } from "../lib/auth.js";
+import { getAuthInfo, hasExpiredStoredSession, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
 import { getApiUrl, getGatewayUrl, getWebsiteUrl, MNEMOM_DIR } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
 import { malformedAgentIdMessage, parseAgentRef, resolveAnthropicDoor, resolveGatewayHost, sanitizeAgentName, singleCellError, } from "../lib/agent.js";
-import { readMnemomKey, resolveSubscriptionMnemomKey } from "../lib/subscription-login.js";
+import { readMnemomKey, resolveAgentAuth, resolveSubscriptionMnemomKey, sayRetiredConsoleNotice, } from "../lib/subscription-login.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
 import { IdentityRouteMissingError, resolveServedIdentity, resolveServedIdentityDetail, } from "../lib/agent-identity-route.js";
 import { readConfirmedAgent, readServedAgent, servedFingerprint, writeConfirmedAgent, writeServedAgent, } from "../lib/served-agent-cache.js";
@@ -964,9 +964,13 @@ async function publishDefaultCards(agentId, modes, opts = {}) {
     }
 }
 /**
- * `mnemom agent setup [--agent <slug|mnm-id>] [--governance …]` — the explicit provisioning entry
- * point. An id (`--agent mnm-<uuid>`, or launcher.toml `agent_id`) refreshes that pinned agent's
- * cards and never claims or births; a malformed `mnm-…` refuses.
+ * `mnemom agent setup [--agent <slug|mnm-id>] [--governance …] [--auth …]` — the explicit
+ * provisioning entry point. An id (`--agent mnm-<uuid>`, or launcher.toml `agent_id`) refreshes
+ * that pinned agent's cards and never claims or births; a malformed `mnm-…` refuses.
+ *
+ * The auth mode resolves as a launch's does (`--auth`, else MNEMOM_AGENT_AUTH, which launcher.toml
+ * `auth` folds into, else api-key). A subscription setup asks for no Anthropic key: the identity
+ * anchors on the Mnemom API key, exactly as the subscription launch it provisions for (MNE-9282).
  */
 export async function agentSetupCommand(opts = {}) {
     const rawRef = opts.agent?.trim() || opts.agentId?.trim() || "";
@@ -974,6 +978,9 @@ export async function agentSetupCommand(opts = {}) {
     if (ref?.kind === "malformed-id") {
         throw new Error(malformedAgentIdMessage(ref.raw, opts.agent?.trim() ? "--agent" : "agent_id").replace("mnemom agent:", "mnemom agent setup:"));
     }
+    // Validated up front, as a launch does, so a bad --auth fails before any sign-in.
+    const auth = resolveAgentAuth(opts.auth, process.env);
+    sayRetiredConsoleNotice(opts.auth, process.env, say);
     const gatewayHost = resolveGatewayHost(process.env);
     const cellError = singleCellError({
         door: resolveAnthropicDoor(process.env),
@@ -993,13 +1000,23 @@ export async function agentSetupCommand(opts = {}) {
             process.exit(1); // guidance already printed
         throw err;
     }
-    const anthropicKey = await resolveAnthropicKey(process.env, { allowPrompt: true });
+    // The credentials resolve as the launch's do (agentCommand): a subscription launch has no
+    // Anthropic key and anchors on a Mnemom key (minted once if there is none); an api-key one
+    // sends this machine's existing Mnemom key beside its Anthropic key, minting only for a pin.
+    const subscription = auth === "subscription";
+    const anthropicKey = subscription
+        ? undefined
+        : await resolveAnthropicKey(process.env, { allowPrompt: true });
+    const subscriptionKey = subscription
+        ? await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps())
+        : undefined;
     if (ref?.kind === "id") {
         const pinned = await resolvePinnedAgent(ref.id);
         await ensureClaimedServedAgent({
             slug: pinned.slug,
             anthropicKey,
-            mnemomKey: await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps(), "pinning an agent"),
+            mnemomKey: subscriptionKey ??
+                (await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps(), "pinning an agent")),
             pin: pinned.id,
             gatewayHost,
             orgId: account.orgId,
@@ -1017,8 +1034,9 @@ export async function agentSetupCommand(opts = {}) {
     await ensureClaimedServedAgent({
         slug,
         anthropicKey,
-        // Asked the way a launch asks: with this machine's Mnemom key when it has one (never minted).
-        mnemomKey: readMnemomKey(defaultMnemomKeyDeps()),
+        // Asked the way a launch asks: an api-key launch with this machine's Mnemom key when it has
+        // one (never minted).
+        mnemomKey: subscriptionKey ?? readMnemomKey(defaultMnemomKeyDeps()),
         gatewayHost,
         orgId: account.orgId,
         orgLabel: account.orgLabel,
@@ -1182,6 +1200,11 @@ export async function ensureSessionAndBalance(opts) {
     const interactive = opts.interactive ?? isInteractive();
     const haveSession = await ensureMnemomSession({ interactive });
     if (!haveSession) {
+        // A stored session whose refresh was rejected needs a fresh login, not an
+        // account: the generic message below sent signed-in users to the waitlist.
+        if (hasExpiredStoredSession()) {
+            throw new Error("Your Mnemom session expired. Run `mnemom login` to sign in again (or set MNEMOM_API_KEY).");
+        }
         throw new Error("mnemom agent needs a Mnemom account — it runs your coding session governed and on your org's µ balance.\n" +
             "  Sign in:     mnemom login   (or set MNEMOM_API_KEY)\n" +
             "  Invited?     mnemom agent --invite <token>   (signs you in and unlocks Mnemom Agent)\n" +

package/dist/commands/agent-share-fixture.d.ts

@@ -17,4 +17,6 @@ export declare const FIXTURE_CARD_VALID: ShareCardLike;
 export declare const FIXTURE_CARD_PERIOD_REVERT: ShareCardLike;
 /** Real candidate lines plus two that must be refused. */
 export declare const FIXTURE_CANDIDATES: CandidateLine[];
-export declare const fixtureAgentShareParts: Pick<AgentShareDeps, "source" | "issuer">;
+/** Public half of the aip TEST key (seed 0x2a) that signed the fixture cards. Test only. */
+export declare const FIXTURE_TEST_PUBLIC_KEY = "197f6b23e16c8532c6abc838facd5ea789be0c76b2920334039bfa8b3d368d61";
+export declare const fixtureAgentShareParts: Pick<AgentShareDeps, "source" | "issuer" | "renderer">;

package/dist/commands/agent-share-fixture.js

@@ -10,6 +10,7 @@
  * the refusal path can be shown. This is not a real issuer: a production source and signer
  * are a separate, human-gated change.
  */
+import { aipLineRenderer } from "./agent-share-render.js";
 export const AGENT_SHARE_FIXTURE_ENV = "MNEMOM_AGENT_SHARE_FIXTURE";
 export function agentShareFixtureEnabled(env = process.env) {
     return env.MNEMOM_AGENT_SHARE === "1" && env[AGENT_SHARE_FIXTURE_ENV] === "1";
@@ -25,11 +26,11 @@ export const FIXTURE_CARD_VALID = {
     signing_key_id: "test-sharecard-key-1",
     statements: [
         {
-            typ: "AAP-Statement/v1",
+            typ: "AAP-ConductRecord/v1",
             hash: "1111111111111111111111111111111111111111111111111111111111111111",
         },
         {
-            typ: "AAP-Statement/v1",
+            typ: "AAP-ConductRecord/v1",
             hash: "2222222222222222222222222222222222222222222222222222222222222222",
         },
     ],
@@ -49,7 +50,7 @@ export const FIXTURE_CARD_VALID = {
             statement_hash: "2222222222222222222222222222222222222222222222222222222222222222",
         },
     ],
-    signature: "qsHSChAxBEnEyNoQQLQMFXZ6LKxruMyijxA5s3h9oPKl4OijJqxFm3QC0rteDXJsYwJCMeKyk_0xzGTDc3wDAQ",
+    signature: "PCa6dhIMUJrJoA9A_v50FTXWxmRSADYs1F_iZWWJrJiujUbsxPkadHQhS8cQvug0ChRQpkOrtNkQJ48opcK-Cg",
 };
 export const FIXTURE_CARD_PERIOD_REVERT = {
     typ: "AAP-ShareCard/v1",
@@ -62,15 +63,15 @@ export const FIXTURE_CARD_PERIOD_REVERT = {
     signing_key_id: "test-sharecard-key-1",
     statements: [
         {
-            typ: "AAP-Statement/v1",
+            typ: "AAP-ConductRecord/v1",
             hash: "1111111111111111111111111111111111111111111111111111111111111111",
         },
         {
-            typ: "AAP-Statement/v1",
+            typ: "AAP-ConductRecord/v1",
             hash: "2222222222222222222222222222222222222222222222222222222222222222",
         },
         {
-            typ: "AAP-Statement/v1",
+            typ: "AAP-ConductRecord/v1",
             hash: "3333333333333333333333333333333333333333333333333333333333333333",
         },
     ],
@@ -97,7 +98,7 @@ export const FIXTURE_CARD_PERIOD_REVERT = {
             statement_hash: "3333333333333333333333333333333333333333333333333333333333333333",
         },
     ],
-    signature: "OQf-4xgUQbIxOef_BsJeTehfpqLPPR2GTv8_y6EbxPX9UkFp2PpE2pnETh2VqcwDfV1U_4bSR8Pwrpsch3DwCw",
+    signature: "0aUrWIfIYKlp2H40Ovh4AYE6MgWokOrjfLjd7Wm9-tT0UHTEvPvo4a5lAy-WQ5iRBUI9JJncNJS9zpVPY2X6DA",
 };
 const FIXTURE_CARDS = [FIXTURE_CARD_VALID, FIXTURE_CARD_PERIOD_REVERT];
 const HASH_E = "e".repeat(64);
@@ -120,7 +121,10 @@ const same = (a, b) => a.length === b.length &&
         const m = b.find((x) => x.id === l.id);
         return m !== undefined && JSON.stringify(m) === JSON.stringify(l);
     });
+/** Public half of the aip TEST key (seed 0x2a) that signed the fixture cards. Test only. */
+export const FIXTURE_TEST_PUBLIC_KEY = "197f6b23e16c8532c6abc838facd5ea789be0c76b2920334039bfa8b3d368d61";
 export const fixtureAgentShareParts = {
+    renderer: aipLineRenderer(FIXTURE_TEST_PUBLIC_KEY),
     source: { listLines: async () => FIXTURE_CANDIDATES },
     issuer: {
         issue: async (lines) => {

package/dist/commands/agent-share-render.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bridge from `mnemom agent share` to the aip verifier (`@mnemom/aip-verifier`, aip#192/#178):
+ * the renderer (`renderLines`) and claim-lint (`lintRendering`) are the ONLY source of what a
+ * card may say. No word lists live here. The package is a devDependency pinned to the aip
+ * release tarball and is loaded lazily, so the default CLI path never touches it; if it is
+ * absent at runtime the share command fails closed with a clear message.
+ */
+import type { LineRenderer, SharedCardLine } from "./agent-share.js";
+import type * as AipMain from "@mnemom/aip-verifier";
+import type * as AipRender from "@mnemom/aip-verifier/render-lines";
+export interface VerifierModules {
+    lintRendering: typeof AipMain.lintRendering;
+    renderLines: typeof AipRender.renderLines;
+}
+/** Loader seam: tests swap it to simulate a missing or broken package. */
+export type VerifierLoader = () => Promise<VerifierModules>;
+/**
+ * `publicKey` is the trusted Ed25519 key (hex) that must have signed the card. Without one the
+ * renderer fails closed (missing_key), so an unsigned or foreign-signed card is never linked.
+ */
+export declare function aipLineRenderer(publicKey: string | undefined, load?: VerifierLoader): LineRenderer;
+/** claim-lint one candidate line as the share card would show it; a reason when it fails. */
+export declare function aipLineScreen(line: SharedCardLine, load?: VerifierLoader): Promise<string | null>;

package/dist/commands/agent-share-render.js

@@ -0,0 +1,72 @@
+/**
+ * Bridge from `mnemom agent share` to the aip verifier (`@mnemom/aip-verifier`, aip#192/#178):
+ * the renderer (`renderLines`) and claim-lint (`lintRendering`) are the ONLY source of what a
+ * card may say. No word lists live here. The package is a devDependency pinned to the aip
+ * release tarball and is loaded lazily, so the default CLI path never touches it; if it is
+ * absent at runtime the share command fails closed with a clear message.
+ */
+const defaultLoader = async () => {
+    const [main, render] = await Promise.all([
+        import("@mnemom/aip-verifier"),
+        import("@mnemom/aip-verifier/render-lines"),
+    ]);
+    return { lintRendering: main.lintRendering, renderLines: render.renderLines };
+};
+/** Keep the real cause: "not installed" only for a genuinely missing module. */
+async function loadVerifier(load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        const e = error;
+        if (e.code === "ERR_MODULE_NOT_FOUND" || e.code === "MODULE_NOT_FOUND") {
+            throw new Error("the aip verifier (@mnemom/aip-verifier) is not installed: run `npm install https://github.com/mnemom/aip/releases/download/aip-verifier-v0.6.0/mnemom-aip-verifier-0.6.0.tgz`", { cause: error });
+        }
+        throw new Error(`the aip verifier (@mnemom/aip-verifier) failed to load: ${e.message ?? error}`, { cause: error });
+    }
+}
+/**
+ * `publicKey` is the trusted Ed25519 key (hex) that must have signed the card. Without one the
+ * renderer fails closed (missing_key), so an unsigned or foreign-signed card is never linked.
+ */
+export function aipLineRenderer(publicKey, load = defaultLoader) {
+    return {
+        async renderLines(card, opts) {
+            const { renderLines } = await loadVerifier(load);
+            const r = await renderLines(card, {
+                enabled: true,
+                surface: opts?.period ? "period_card" : "share_card",
+                ...(publicKey ? { publicKey } : {}),
+            });
+            if (!r.ok)
+                throw new Error(`the card did not render (${r.reasons.join(", ")})`);
+            return r.lines.map((l) => ({
+                text: l.text,
+                kind: l.class,
+                ...(l.coverage ? { coverage: `${l.coverage.judged} of ${l.coverage.total}` } : {}),
+            }));
+        },
+    };
+}
+/** claim-lint one candidate line as the share card would show it; a reason when it fails. */
+export async function aipLineScreen(line, load = defaultLoader) {
+    let v;
+    try {
+        v = await loadVerifier(load);
+    }
+    catch (error) {
+        return error.message;
+    }
+    const text = `${line.label}: ${line.value}`;
+    let res;
+    try {
+        res = v.lintRendering({
+            surface: "share_card",
+            lines: [{ class: line.kind === "revert" ? "outcome" : "measured", text }],
+        });
+    }
+    catch (error) {
+        return `claim-lint could not run (${error.message})`;
+    }
+    return res.ok ? null : `claim-lint rejects it (${res.violations.map((x) => x.rule).join(", ")})`;
+}