@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.3

package/dist/base-url-proxy.mjs

@@ -15,7 +15,10 @@
 // (> WAIT_MS) → the request is forwarded without it (the gateway then behaves as before).
 //
 // CONFIG (env, none secret)
-//   MNEMOM_AGENT_BU_DOOR         gateway door URL (required, https only), e.g. https://gateway.mnemom.ai/anthropic
+//   MNEMOM_AGENT_BU_DOOR         gateway door URL (required), e.g. https://gateway.mnemom.ai/anthropic;
+//                                https; http only with MNEMOM_AGENT_BU_HTTP_DOOR=1 and on a
+//                                loopback literal (127.0.0.1, [::1], localhost: the C17-R16 seam)
+//   MNEMOM_AGENT_BU_HTTP_DOOR    "1" allows that http door; set by the launcher (see the gate below)
 //   MNEMOM_AGENT_BU_CWD          the session cwd (Claude Code's transcript lives under its slug)
 //   MNEMOM_AGENT_BU_LOG          append log lines here instead of stderr (optional)
 //   MNEMOM_AGENT_BU_PARENT_PID   exit when this pid is gone
@@ -43,7 +46,18 @@ try {
 } catch {
   die("MNEMOM_AGENT_BU_DOOR is required and must be a URL");
 }
-if (DOOR.protocol !== "https:") die("MNEMOM_AGENT_BU_DOOR must be https");
+/** S1 LOOPBACK_HOSTS: the exact hostnames an http door may name (look-alikes such as 127.0.0.1.nip.io fail). */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+// The C17-R16 http-door seam (T3). The launcher (commands/agent.ts startBaseUrlProxy) sets
+// MNEMOM_AGENT_BU_HTTP_DOOR=1 only when test-mode.mjs testSeamsHonoured / httpDoorAllowed hold, and
+// strips an inherited value otherwise; this proxy reads no test-mode env itself. A proxy spawned
+// directly trusts its parent's flag: the worst case is still http to a loopback literal only.
+const httpDoorAllowed = env.MNEMOM_AGENT_BU_HTTP_DOOR === "1" && LOOPBACK_HOSTS.has(DOOR.hostname);
+if (DOOR.protocol === "http:") {
+  if (!httpDoorAllowed)
+    die("MNEMOM_AGENT_BU_DOOR must be https (http only on a loopback literal with the door flag)");
+} else if (DOOR.protocol !== "https:") die("MNEMOM_AGENT_BU_DOOR must be https");
+const transport = DOOR.protocol === "http:" ? http : https;
 const LOGFILE = env.MNEMOM_AGENT_BU_LOG || "";
 const PARENT = Number(env.MNEMOM_AGENT_BU_PARENT_PID || 0);
 const PORT = Number(env.MNEMOM_AGENT_BU_PORT || 0);
@@ -101,7 +115,7 @@ function recordState(h) {
   }
 }
 
-const agent = new https.Agent({ keepAlive: true, maxSockets: 32 });
+const agent = new transport.Agent({ keepAlive: true, maxSockets: 32 });
 const doorPath = DOOR.pathname.replace(/\/$/, "");
 const isMessages = (u) => u === "/v1/messages" || u.startsWith("/v1/messages?");
 
@@ -123,7 +137,7 @@ function handle(req, res) {
 
   const forward = (note) => {
     const target = new URL(DOOR.origin + doorPath + req.url);
-    const up = https.request(target, { method: req.method, headers, agent }, (ur) => {
+    const up = transport.request(target, { method: req.method, headers, agent }, (ur) => {
       recordState(ur.headers);
       res.writeHead(ur.statusCode, ur.headers);
       ur.pipe(res);

package/dist/commands/agent-config.js

@@ -56,7 +56,8 @@ function listConfig(enabled) {
         out("Set one with:  mnemom agent config set <key> <value>");
         out("");
         out("Settable keys:");
-        for (const spec of CONFIG_KEYS)
+        // The durable key is listed only while `durable` is on (hidden like its verbs; C17).
+        for (const spec of CONFIG_KEYS.filter((k) => k.key !== "durable" || enabled.includes("durable")))
             out(`  ${spec.key.padEnd(22)} ${spec.describe}${configKeyMark(spec.key, undefined, enabled)}`);
         return;
     }
@@ -199,6 +200,9 @@ function deleteKey(cfg, key) {
         case "compaction_intercept":
             delete cfg.compactionIntercept;
             break;
+        case "durable":
+            delete cfg.durable;
+            break;
         case "context_profile":
             delete cfg.contextProfile;
             break;

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

@@ -17,6 +17,15 @@ export interface DoctorOptions {
     cli?: string;
     /** The agent slug a launch would use (--agent / launcher.toml); default agent-<handle>. */
     agent?: string;
+    /**
+     * The durable lock lines (commands/durable-doctor.ts), passed only while the experimental
+     * `durable` gate is on; absent, the doctor is exactly as before.
+     */
+    durable?: () => Promise<Array<{
+        mark: "ok" | "warn" | "info";
+        text: string;
+        hint?: string;
+    }>>;
 }
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
 export declare function agentDoctorCommand(options?: DoctorOptions): Promise<void>;

package/dist/commands/agent-doctor.js

@@ -125,6 +125,10 @@ export async function agentDoctorCommand(options = {}) {
     // ── CLI auto-update ──
     const upd = await probeUpdateStatus();
     add(upd.mark, upd.text, upd.hint);
+    // ── durable lock preconditions (gate on only): never a MISS ──
+    if (options.durable)
+        for (const l of await options.durable())
+            add(l.mark, l.text, l.hint);
     // ── render ──
     const door = resolveAnthropicDoor(env);
     out("mnemom agent doctor");

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

@@ -11,6 +11,7 @@
  * 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 GithubBases } from "../lib/runner/github-base.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";
@@ -24,27 +25,34 @@ export interface RunDeps {
     err(line: string): void;
     /** Aborted by SIGTERM or SIGINT. */
     stop: AbortSignal;
-    jobDeps(api: RunnerApi): JobDeps;
+    /** The text of this host's executor-state.json, or null when there is none. */
+    readExecutorState?(): Promise<string | null>;
+    jobDeps(api: RunnerApi, executorId: string | null, github: GithubBases): 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 declare const GITHUB_API: string;
+/**
+ * git's env with the token as an http extra header for the web base only: it never reaches argv
+ * or the remote URL.
+ */
+export declare function gitAuthEnv(parent: NodeJS.ProcessEnv, token: string | null, web?: string): 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>;
+export declare function openPr(git: Git, fetch: FetchFn, token: string | null, repo: string, ws: Workspace, title: string, apiBase?: 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>;
+export declare function enableAutoMerge(fetch: FetchFn, token: string | null, prUrl: string, bases?: GithubBases): 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;
+    executorId: string | null;
+    github: GithubBases;
 }): 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

@@ -12,11 +12,14 @@
  */
 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 { mkdtemp, readFile, rm } from "node:fs/promises";
+import { homedir, 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 { resolveClaudeBin } from "../lib/claude-bin.js";
+import { executorIdFromState } from "../lib/runner/executor-state.js";
+import { GITHUB_BASES, prUrlPattern, resolveGithubBases, } from "../lib/runner/github-base.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";
@@ -24,6 +27,7 @@ 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";
+import { executorStatePath } from "../vendor/durable-contract/index.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);
@@ -34,7 +38,11 @@ export async function agentRunCommand(flags, deps) {
     const plan = resolved.plan;
     for (const w of plan.warnings)
         deps.err(w);
+    const gh = resolveGithubBases(deps.env);
+    if (gh.warning)
+        deps.err(gh.warning);
     let executorKey;
+    let executorId = plan.executorId;
     if (plan.credential.kind === "oidc") {
         const ex = await exchangeOidc({
             fetch: deps.fetch,
@@ -50,19 +58,28 @@ export async function agentRunCommand(flags, deps) {
             return exitCodeFor(o.outcome);
         }
         executorKey = ex.executorKey;
+        executorId ??= ex.executorId;
     }
     else {
         executorKey = plan.credential.key;
     }
+    // The env id wins, then the exchange answer's; else this host's executor-state.json, when it
+    // holds the key in use.
+    if (executorId === null && deps.readExecutorState) {
+        executorId = executorIdFromState(await deps.readExecutorState(), executorKey) ?? executorId;
+    }
     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);
+    const job = deps.jobDeps(api, executorId, gh.bases);
     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) {
+export const GITHUB_API = GITHUB_BASES.api;
+/**
+ * git's env with the token as an http extra header for the web base only: it never reaches argv
+ * or the remote URL.
+ */
+export function gitAuthEnv(parent, token, web = GITHUB_BASES.web) {
     const env = { ...parent, GIT_TERMINAL_PROMPT: "0" };
     if (!token)
         return env;
@@ -70,7 +87,7 @@ export function gitAuthEnv(parent, token) {
     return {
         ...env,
         GIT_CONFIG_COUNT: "1",
-        GIT_CONFIG_KEY_0: "http.https://github.com/.extraheader",
+        GIT_CONFIG_KEY_0: `http.${web}/.extraheader`,
         GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${basic}`,
     };
 }
@@ -100,10 +117,10 @@ export async function prepareWorkspace(git, cloneUrl, sessionId, root = tmpdir()
 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) {
+async function github(fetch, token, method, path, body, apiBase) {
     if (!token)
         throw new Error("no GitHub token (set GH_TOKEN or GITHUB_TOKEN)");
-    const res = await fetch(`${GITHUB_API}${path}`, {
+    const res = await fetch(`${apiBase}${path}`, {
         method,
         headers: {
             accept: "application/vnd.github+json",
@@ -122,38 +139,33 @@ async function github(fetch, token, method, path, body) {
     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) {
+export async function openPr(git, fetch, token, repo, ws, title, apiBase = GITHUB_BASES.api) {
     await git(ws.dir, ["push", "--quiet", "origin", `HEAD:refs/heads/${ws.branch}`]);
-    const meta = await github(fetch, token, "GET", `/repos/${repo}`);
+    const meta = await github(fetch, token, "GET", `/repos/${repo}`, undefined, apiBase);
     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 pr = await github(fetch, token, "POST", `/repos/${repo}/pulls`, { title, head: ws.branch, base }, apiBase);
     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);
+export async function enableAutoMerge(fetch, token, prUrl, bases = GITHUB_BASES) {
+    const m = prUrlPattern(bases.web).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]}`);
+    const pr = await github(fetch, token, "GET", `/repos/${m[1]}/pulls/${m[2]}`, undefined, bases.api);
     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 },
-    });
+    }, bases.api);
     if (r.status !== 200 || r.json.errors !== undefined) {
         throw new Error(`enabling auto-merge answered ${r.status}`);
     }
@@ -162,7 +174,9 @@ export async function enableAutoMerge(fetch, token, prUrl) {
 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, {
+        // A capabilities phase's `claude` is the pinned one: MNEMOM_AGENT_CLI when absolute, else PATH.
+        const command = inv.command === "claude" ? (resolveClaudeBin(parentEnv) ?? "claude") : inv.command;
+        const child = spawn(command, inv.args, {
             cwd: ws.dir,
             env: phaseEnv(parentEnv, ws.home, modelUrl),
             stdio: ["pipe", "pipe", "inherit"],
@@ -181,10 +195,12 @@ export function runPhaseProcess(inv, ws, modelUrl, signal, parentEnv = process.e
     });
 }
 export function liveJobDeps(api, opts) {
+    const gh = opts.github;
     const token = resolveGithubToken(opts.env);
-    const git = liveGit(gitAuthEnv(opts.env, token));
+    const git = liveGit(gitAuthEnv(opts.env, token, gh.web));
     return {
         api,
+        executorId: opts.executorId,
         nonce: randomUUID(),
         newSpawnId: () => randomUUID(),
         now: () => Date.now(),
@@ -192,10 +208,10 @@ export function liveJobDeps(api, opts) {
         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),
+        prepareWorkspace: (repo, sessionId) => prepareWorkspace(git, `${gh.web}/${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),
+        openPr: (repo, ws, title) => openPr(git, opts.fetch, token, repo, ws, title, gh.api),
+        enableAutoMerge: (prUrl) => enableAutoMerge(opts.fetch, token, prUrl, gh),
         cleanup: cleanupWorkspace,
     };
 }
@@ -213,7 +229,8 @@ export function runAgentRun(flags) {
         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 }),
+        readExecutorState: () => readFile(executorStatePath(homedir()), "utf8").catch(() => null),
+        jobDeps: (api, executorId, github) => liveJobDeps(api, { fetch, env: process.env, executorId, github }),
     }).finally(() => {
         process.off("SIGTERM", onSignal);
         process.off("SIGINT", onSignal);

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

@@ -12,8 +12,7 @@
  * (`x-mnemom-contract`). Implicit alignment — the goal inferred from your own
  * messages (`x-mnemom-goal-mode: implicit`, no contract) — is the experimental
  * `implicit` feature: while it is on a bare launch runs implicit, while it is off
- * (the default) a bare launch runs with alignment off. On a prerelease (`next`)
- * build a bare launch runs implicit unless it is headless `-p` (T16). `--no-implicit` (or
+ * (the default) a bare launch runs with alignment off. `--no-implicit` (or
  * launcher.toml `goal_mode = "off"`) turns it off. The mode is resolved upstream
  * (`resolveImplicit`) and announced on the launch line.
  *

package/dist/commands/agent-session.js

@@ -12,8 +12,7 @@
  * (`x-mnemom-contract`). Implicit alignment — the goal inferred from your own
  * messages (`x-mnemom-goal-mode: implicit`, no contract) — is the experimental
  * `implicit` feature: while it is on a bare launch runs implicit, while it is off
- * (the default) a bare launch runs with alignment off. On a prerelease (`next`)
- * build a bare launch runs implicit unless it is headless `-p` (T16). `--no-implicit` (or
+ * (the default) a bare launch runs with alignment off. `--no-implicit` (or
  * launcher.toml `goal_mode = "off"`) turns it off. The mode is resolved upstream
  * (`resolveImplicit`) and announced on the launch line.
  *

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

@@ -288,6 +288,12 @@ export declare function resolvePinnedAgent(id: string): Promise<{
     id: string;
     slug: string;
 }>;
+/**
+ * The x-mnemom-agent value for a pinned agent: its stored name exactly, when that name is a
+ * header-safe token (every api-valid name is: AGENT_NAME_REGEX allows only letters, digits and
+ * hyphens); "" otherwise, which refuses the launch.
+ */
+export declare function pinnedSlugOf(name: string | null | undefined): string;
 /**
  * One line for an api failure that keeps the parts an operator can act on: the
  * message, the error code, and the scope the endpoint said it needed

package/dist/commands/agent-setup.js

@@ -696,12 +696,23 @@ export async function resolvePinnedAgent(id) {
         throw new UnclaimedAgentError(`mnemom agent: agent ${id} is not claimed, and mnemom agent never runs on an unclaimed agent. ` +
             `Claim it first: \`mnemom agent claim ${id} --key <key>\`.`);
     }
-    const slug = sanitizeAgentName(agent.name ?? "");
+    // The stored name goes out verbatim: the gateway compares the pin's name exactly
+    // (agent-identity.ts), and the api allows uppercase and hyphen runs, which sanitizeAgentName
+    // would rewrite (mnemom-test #1061). sanitizeAgentName is for new names only.
+    const slug = pinnedSlugOf(agent.name);
     if (!slug) {
         throw new UnclaimedAgentError(`mnemom agent: agent ${id} has no usable name to send as x-mnemom-agent; rename it, or launch by name.`);
     }
     return { id, slug };
 }
+/**
+ * The x-mnemom-agent value for a pinned agent: its stored name exactly, when that name is a
+ * header-safe token (every api-valid name is: AGENT_NAME_REGEX allows only letters, digits and
+ * hyphens); "" otherwise, which refuses the launch.
+ */
+export function pinnedSlugOf(name) {
+    return typeof name === "string" && /^[A-Za-z0-9-]+$/.test(name) ? name : "";
+}
 /** The refusal for a pinned launch the gateway did not (or could not) honour. */
 function pinRefusal(err, pin, slug) {
     const head = `mnemom agent: the gateway would not run this launch as ${pin}`;

package/dist/commands/agent-share-test-issuer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TEST-CELL card issuer for `mnemom agent share`. Lets the share-card flow
+ * (AAP-ShareCard/v1) run end to end against the TEST cell before the production signing
+ * endpoint (MNE-9440) exists. It does NOT replace that endpoint and never touches a prod key.
+ *
+ * Gating is by the environment the CLI TARGETS, not by a flag: the issuer is selected only
+ * when BOTH the resolved API base is the test cell API and the resolved website base is the
+ * test website (see `isTestCellTarget`). Anything else (prod, www, local, a mixed target such
+ * as test website + prod API, an unparseable URL) is "not test" and gets no test signing.
+ * `agentShareCommand` re-checks this after issuance, so a test-signed card can never be
+ * linked from a non-test target even if a different issuer returned one.
+ *
+ * HOW A TEST-SIGNED CARD IS IDENTIFIED. The card is a normal, v1-valid AAP-ShareCard/v1:
+ * `signing_key_id` is the aip TEST key id `test-sharecard-key-1`. Every test key id starts with
+ * `test-` (TEST_KEY_ID_PREFIX); production ids start `aap-prod-`. `signing_key_id` sits inside
+ * the signed canonical JSON, so the marker cannot be stripped or forged without breaking the
+ * signature, and v1 verification is unchanged. Consumers label a card test-signed with
+ * `isTestSignedKeyId(card.signing_key_id)`.
+ *
+ * KEY. The seed is the public test seed (32 bytes of 0x2a) that mnemom/aip uses for its
+ * fixtures (aip packages/verifier/test/helpers/sharecard-fixtures.ts: TEST_SEED, TEST_KEY_ID).
+ * It is not a secret and has no relation to any production key. Its public half is
+ * TEST_SHARECARD_PUBLIC_KEY_HEX / TEST_SHARECARD_JWKS below, which a verifier must be given
+ * explicitly as the trusted key; the production JWKS never contains it.
+ */
+import type * as AipVerifier from "@mnemom/aip-verifier";
+import type { AgentShareDeps, CardIssuer } from "./agent-share.js";
+/** aip test key id; ids of every test key start with this prefix. */
+export declare const TEST_KEY_ID = "test-sharecard-key-1";
+export declare const TEST_KEY_ID_PREFIX = "test-";
+/** Public half of the test key, hex (same value the fixture verifier trusts). */
+export declare const TEST_SHARECARD_PUBLIC_KEY_HEX = "197f6b23e16c8532c6abc838facd5ea789be0c76b2920334039bfa8b3d368d61";
+/** The same public key as a JWKS (RFC 8037 OKP/Ed25519). Never serve this from a product JWKS. */
+export declare const TEST_SHARECARD_JWKS: {
+    readonly keys: readonly [{
+        readonly kty: "OKP";
+        readonly crv: "Ed25519";
+        readonly kid: "test-sharecard-key-1";
+        readonly alg: "EdDSA";
+        readonly use: "sig";
+        readonly x: string;
+    }];
+};
+export declare const TEST_CELL_API_HOST = "api-az-test.mnemom.ai";
+export declare const TEST_CELL_WEBSITE_HOST = "test.mnemom.ai";
+export declare function isTestSignedKeyId(keyId: unknown): boolean;
+/**
+ * True only when the CLI targets the test cell: API base AND website base both resolve to the
+ * test cell hosts (exact match, https). Fails closed on anything else, including a retired
+ * environment name that makes config resolution throw.
+ */
+export declare function isTestCellTarget(api?: () => string, website?: () => string): boolean;
+type Verifier = typeof AipVerifier;
+export interface TestIssuerOptions {
+    now?: () => Date;
+    cardId?: () => string;
+    loadVerifier?: () => Promise<Pick<Verifier, "shareCardSigningInput">>;
+}
+/** Issues AAP-ShareCard/v1 cards signed with the aip TEST key. Construct only for a test target. */
+export declare function createTestCardIssuer(opts?: TestIssuerOptions): CardIssuer;
+/**
+ * Choose the dependency set for `mnemom agent share`. Pure function of the target: the test
+ * issuer (and fixture candidate lines, since no real statement source exists on test yet) are
+ * wired only for a test target. The fixture env flag on a non-test target is refused loudly.
+ */
+export declare function selectAgentShareDeps(live: AgentShareDeps, env: Record<string, string | undefined>, isTest?: () => boolean): AgentShareDeps;
+export {};

package/dist/commands/agent-share-test-issuer.js

@@ -0,0 +1,139 @@
+/**
+ * TEST-CELL card issuer for `mnemom agent share`. Lets the share-card flow
+ * (AAP-ShareCard/v1) run end to end against the TEST cell before the production signing
+ * endpoint (MNE-9440) exists. It does NOT replace that endpoint and never touches a prod key.
+ *
+ * Gating is by the environment the CLI TARGETS, not by a flag: the issuer is selected only
+ * when BOTH the resolved API base is the test cell API and the resolved website base is the
+ * test website (see `isTestCellTarget`). Anything else (prod, www, local, a mixed target such
+ * as test website + prod API, an unparseable URL) is "not test" and gets no test signing.
+ * `agentShareCommand` re-checks this after issuance, so a test-signed card can never be
+ * linked from a non-test target even if a different issuer returned one.
+ *
+ * HOW A TEST-SIGNED CARD IS IDENTIFIED. The card is a normal, v1-valid AAP-ShareCard/v1:
+ * `signing_key_id` is the aip TEST key id `test-sharecard-key-1`. Every test key id starts with
+ * `test-` (TEST_KEY_ID_PREFIX); production ids start `aap-prod-`. `signing_key_id` sits inside
+ * the signed canonical JSON, so the marker cannot be stripped or forged without breaking the
+ * signature, and v1 verification is unchanged. Consumers label a card test-signed with
+ * `isTestSignedKeyId(card.signing_key_id)`.
+ *
+ * KEY. The seed is the public test seed (32 bytes of 0x2a) that mnemom/aip uses for its
+ * fixtures (aip packages/verifier/test/helpers/sharecard-fixtures.ts: TEST_SEED, TEST_KEY_ID).
+ * It is not a secret and has no relation to any production key. Its public half is
+ * TEST_SHARECARD_PUBLIC_KEY_HEX / TEST_SHARECARD_JWKS below, which a verifier must be given
+ * explicitly as the trusted key; the production JWKS never contains it.
+ */
+import { createPrivateKey, randomBytes, sign as edSign } from "node:crypto";
+import { getApiUrl, getWebsiteUrl } from "../lib/config.js";
+import { aipLineRenderer } from "./agent-share-render.js";
+import { FIXTURE_CANDIDATES } from "./agent-share-fixture.js";
+/** aip test key id; ids of every test key start with this prefix. */
+export const TEST_KEY_ID = "test-sharecard-key-1";
+export const TEST_KEY_ID_PREFIX = "test-";
+/** Public aip fixture seed (0x2a x 32). TEST ONLY. */
+const TEST_SEED = Buffer.alloc(32, 0x2a);
+/** Public half of the test key, hex (same value the fixture verifier trusts). */
+export const TEST_SHARECARD_PUBLIC_KEY_HEX = "197f6b23e16c8532c6abc838facd5ea789be0c76b2920334039bfa8b3d368d61";
+/** The same public key as a JWKS (RFC 8037 OKP/Ed25519). Never serve this from a product JWKS. */
+export const TEST_SHARECARD_JWKS = {
+    keys: [
+        {
+            kty: "OKP",
+            crv: "Ed25519",
+            kid: TEST_KEY_ID,
+            alg: "EdDSA",
+            use: "sig",
+            x: Buffer.from(TEST_SHARECARD_PUBLIC_KEY_HEX, "hex").toString("base64url"),
+        },
+    ],
+};
+export const TEST_CELL_API_HOST = "api-az-test.mnemom.ai";
+export const TEST_CELL_WEBSITE_HOST = "test.mnemom.ai";
+export function isTestSignedKeyId(keyId) {
+    return typeof keyId === "string" && keyId.startsWith(TEST_KEY_ID_PREFIX);
+}
+function hostOf(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === "https:" ? u.hostname.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True only when the CLI targets the test cell: API base AND website base both resolve to the
+ * test cell hosts (exact match, https). Fails closed on anything else, including a retired
+ * environment name that makes config resolution throw.
+ */
+export function isTestCellTarget(api = getApiUrl, website = getWebsiteUrl) {
+    try {
+        return hostOf(api()) === TEST_CELL_API_HOST && hostOf(website()) === TEST_CELL_WEBSITE_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+// PKCS#8 wrapper for a raw Ed25519 seed.
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+/** Issues AAP-ShareCard/v1 cards signed with the aip TEST key. Construct only for a test target. */
+export function createTestCardIssuer(opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    const cardId = opts.cardId ?? (() => `card-test-${randomBytes(6).toString("hex")}`);
+    const load = opts.loadVerifier ?? (() => import("@mnemom/aip-verifier"));
+    return {
+        async issue(lines) {
+            const { shareCardSigningInput } = await load();
+            const at = now();
+            const day = (d) => d.toISOString().slice(0, 10);
+            const hashes = [...new Set(lines.map((l) => l.statement_hash))];
+            const unsigned = {
+                typ: "AAP-ShareCard/v1",
+                card_id: cardId(),
+                period: { start: day(new Date(at.getTime() - 6 * 86_400_000)), end: day(at) },
+                issued_at: at.toISOString(),
+                signing_key_id: TEST_KEY_ID,
+                statements: hashes.map((hash) => ({ typ: "AAP-ConductRecord/v1", hash })),
+                lines: lines.map((l) => ({ ...l })),
+            };
+            const key = createPrivateKey({
+                key: Buffer.concat([PKCS8_ED25519_PREFIX, TEST_SEED]),
+                format: "der",
+                type: "pkcs8",
+            });
+            const signature = edSign(null, Buffer.from(shareCardSigningInput(unsigned), "utf8"), key);
+            return {
+                ...unsigned,
+                signature: signature.toString("base64url"),
+            };
+        },
+    };
+}
+/**
+ * Choose the dependency set for `mnemom agent share`. Pure function of the target: the test
+ * issuer (and fixture candidate lines, since no real statement source exists on test yet) are
+ * wired only for a test target. The fixture env flag on a non-test target is refused loudly.
+ */
+export function selectAgentShareDeps(live, env, isTest = isTestCellTarget) {
+    if (isTest()) {
+        return {
+            ...live,
+            source: { listLines: async () => FIXTURE_CANDIDATES },
+            issuer: createTestCardIssuer(),
+            renderer: aipLineRenderer(TEST_SHARECARD_PUBLIC_KEY_HEX),
+            targetsTestCell: () => true,
+        };
+    }
+    if (env.MNEMOM_AGENT_SHARE_FIXTURE === "1") {
+        return {
+            ...live,
+            source: {
+                listLines: async () => {
+                    throw new Error("fixture mode only runs against the test cell");
+                },
+            },
+            targetsTestCell: () => false,
+        };
+    }
+    return { ...live, targetsTestCell: () => false };
+}

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

@@ -6,7 +6,11 @@
  * (W6.2 — the share offer never auto-posts).
  *
  * Gated by MNEMOM_AGENT_SHARE=1 (not experimental-registry; off by default, so default CLI
- * behaviour is unchanged). Everything outside the process is injected:
+ * behaviour is unchanged), EXCEPT when the CLI targets the test cell (MNEMOM_RING=test, or API
+ * and website both resolving to api-az-test.mnemom.ai / test.mnemom.ai): there it is on without
+ * the flag. The test target is detected once, by `isTestCellTarget` (agent-share-test-issuer.ts),
+ * and reaches the command as `deps.targetsTestCell`. Prod and every other ring stay gated.
+ * Everything outside the process is injected:
  *   - `source`   lists candidate lines from the user's signed statements,
  *   - `issuer`   returns the SIGNED AAP-ShareCard/v1 for the chosen lines (the CLI never holds
  *                a signing key),
@@ -73,6 +77,8 @@ export interface AgentShareDeps {
     pick: (lines: SharedCardLine[]) => Promise<string[]>;
     isTTY: () => boolean;
     websiteBase: () => string;
+    /** True only when the CLI targets the test cell. Absent means "not test". */
+    targetsTestCell?: () => boolean;
     out: (line: string) => void;
     err: (line: string) => void;
 }