@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/commands/agent.js

@@ -26,7 +26,7 @@
  * an argv value.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync, } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync, } from "node:fs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname } from "node:os";
 import { basename, join, dirname } from "node:path";
@@ -39,8 +39,10 @@ import { ALLOW_AUTOCOMPACT_OFF_ENV, dropAutocompactOffEnv, hasOwnSettingsFlag, m
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey } from "../lib/api.js";
 import { recordOrgFor } from "../lib/record-org.js";
-import { defaultSessionKeyDeps, mintSessionGatewayKey, revokeSessionGatewayKey, } from "../lib/session-key.js";
-import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, sayRetiredConsoleNotice, readMnemomKey, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
+import { httpDoorAllowed } from "../durable/test-mode.mjs";
+import { defaultSessionKeyDeps, mintSessionGatewayKey, revokeSessionGatewayKey, startSessionKeyRenewal, } from "../lib/session-key.js";
+import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, sayRetiredConsoleNotice, readMnemomKey, resolveSubscriptionMnemomKey, launchChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
+import { clearLaunching, liveLaunchingDeps, markLaunching } from "../lib/durable/launching.js";
 import { LEDGER_FILE, appendSessionRecord, findResumeCandidate, readSessionRecords, resolveRetentionDays, resumedContextProfile, toLedgerContract, } from "../lib/agent-ledger.js";
 import { isLoggedIn } from "../lib/auth.js";
 import { loadCliConfig } from "../lib/cli-config.js";
@@ -57,6 +59,9 @@ 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";
+import { attachToSeat, firstTurnRow, locksAfterFirstTurn, planDurableLaunch, preReadRegistry, } from "../lib/durable/launch.js";
+import { liveDurableApi, liveHomeFacts, livePlanDeps, liveRegistryReads, liveSeatDeps, liveLockAfterFirstTurn, lockInsteadOfSpawn, createLockedInsteadOfSpawn, liveParentAfterChildEnded, registerDurableSession, saveTtyMode, } from "../lib/durable/live.js";
+import { mayBeHandover } from "../lib/durable/handover.js";
 import { fetchTierIndex, profileMayMisfit, profileTierWarning, resolveTier, tierLaunchModel, } from "../lib/model-tier.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
 const CODE_STORE = LAUNCHER_STORE_PATH;
@@ -175,8 +180,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     liftPassthroughName(options.passthrough ?? []);
     // ── session name + goal ── (a bare `mnemom agent` in a terminal asks for the name;
     // goal alignment is resolved upstream: --goal seals a contract, implicit alignment
-    // is on by default while the `implicit` experimental feature is on, and on a `next`
-    // build for every launch but `-p` (T16).
+    // is on by default only while the `implicit` experimental feature is on.
     const session = await resolveSessionSetup({
         scenario: scenarioArg,
         goal: options.goal,
@@ -187,8 +191,24 @@ export async function agentCommand(scenarioArg, options = {}) {
         askYesNo: (q, d) => askYesNo(q, d),
     });
     const scenario = session.scenario;
+    // ── durable (gate on only): read the registry FIRST, before any other API call, so a registry
+    // that is down refuses with session_registry_unavailable within REGISTRY_TIMEOUT_MS and nothing
+    // is minted, spawned or written (C01-R18). The plan below decides from these rows; a caller not
+    // signed in yet (401) is read again by the plan after sign-in.
+    // A server-shape launch hosts many Claude Code sessions and pins none: it is never registered
+    // (legacy), so neither the read nor the plan runs for it.
     const env = process.env;
     let shape = resolveLaunchShape({ remoteControl: options.remoteControl, server: options.server }, env);
+    const durableLaunch = Boolean(options.durable && scenario) && shape !== "server";
+    // Until the session registers, a lock by this name answers first_turn_pending, not "no session".
+    if (durableLaunch && scenario && !options.dryRun) {
+        const ld = liveLaunchingDeps(MNEMOM_DIR);
+        markLaunching(scenario, process.pid, ld);
+        process.on("exit", () => clearLaunching(scenario, ld));
+    }
+    const durableRows = durableLaunch && scenario && !options.dryRun
+        ? await preReadRegistry(liveRegistryReads(liveDurableApi()), scenario)
+        : undefined;
     const shapeExplicit = launchPreferenceExplicit({ remoteControl: options.remoteControl, server: options.server }, env);
     // How Claude Code authenticates: an Anthropic key (default) or the user's claude.ai
     // subscription login (Team/Enterprise; lib/subscription-login.ts).
@@ -260,7 +280,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     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 pluginWanted = pluginEnabled(options.plugin, env, options.durable !== undefined);
     const bundledPluginDir = pluginWanted ? resolvePluginDir() : null;
     const pluginFor = (cliName) => cliName !== "claude" && pluginWanted
         ? { dir: null, line: `off (${cliName} is not Claude Code)` }
@@ -519,20 +539,83 @@ export async function agentCommand(scenarioArg, options = {}) {
     // so the goal the gateway inferred there is still the one it steers by. Resolved here, after
     // sign-in and the agent refresh, because a resume needs the org, agent and gateway host to
     // match the earlier launch.
-    const continuation = await resolveLaunchContinuation({
-        session: scenario,
-        orgId: account.orgId,
-        agent,
-        gatewayHost,
-        explicit: options.conversationId,
-        implicit: goalAlignmentMode(envelope, goalMode) === "implicit",
-        passthrough: options.passthrough ?? [],
-        interactive: isInteractive(),
-        records: () => readSessionRecords({ dir: MNEMOM_DIR }),
-        askYesNo: (q, d) => askYesNo(q, d),
-        ccSessionExists: (id) => ccSessionTranscriptExists(id, process.env),
-    });
+    // ── durable (gate on only) ── the server registry decides continue / new / attach before the
+    // local ledger does (C01-R01); a registry-backed plan replaces the ledger continuation.
+    let durablePlan = null;
+    // The launcher key of a durable plan: durablePlan is only ever set under options.durable.
+    let durableKey = "off";
+    if (options.durable && scenario && durableLaunch) {
+        durableKey = options.durable.launcherKey;
+        const plan = await planDurableLaunch({
+            name: scenario,
+            newFlag: options.durable.newSession,
+            launcherKey: options.durable.launcherKey,
+            passthrough: options.passthrough ?? [],
+            goalGiven: Boolean(options.goal?.trim()),
+            explicitAgentId: pin ? servedAgentId : null,
+            interactive: isInteractive(),
+            home: await liveHomeFacts(),
+            rows: durableRows,
+            explicitConversationId: options.conversationId ?? null,
+        }, livePlanDeps(servedAgentId, (id) => ccSessionTranscriptExists(id, process.env), (q, d) => askYesNo(q, d)));
+        if (plan.kind === "attach") {
+            process.exitCode = await attachToSeat(plan.row, scenario, [], liveSeatDeps(options.durable.launcherKey));
+            return;
+        }
+        if (plan.kind === "spawn")
+            durablePlan = plan;
+    }
+    const continuation = durablePlan
+        ? {
+            conversationId: durablePlan.conversationId,
+            resumeCcSessionId: durablePlan.resumeCcSessionId,
+        }
+        : await resolveLaunchContinuation({
+            session: scenario,
+            orgId: account.orgId,
+            agent,
+            gatewayHost,
+            explicit: options.conversationId,
+            implicit: goalAlignmentMode(envelope, goalMode) === "implicit",
+            passthrough: options.passthrough ?? [],
+            interactive: isInteractive(),
+            records: () => readSessionRecords({ dir: MNEMOM_DIR }),
+            askYesNo: (q, d) => askYesNo(q, d),
+            ccSessionExists: (id) => ccSessionTranscriptExists(id, process.env),
+        });
     const conversationId = continuation.conversationId;
+    // The registered row of a durable launch: its child's SIGKILL may be a handover (C02-R26 step 7).
+    let durableRow = null;
+    // A lock on a new CC session waits for its first turn (dogfood B5): claude spawns attended first.
+    let lockAfterFirstTurn = false;
+    if (durablePlan) {
+        options = {
+            ...options,
+            passthrough: durablePlan.newCcSessionId
+                ? [...durablePlan.passthrough, "--session-id", durablePlan.newCcSessionId]
+                : durablePlan.passthrough,
+        };
+        // Register (new) and, under `always` / ask-yes, lock instead of spawning (C02-R23 c, e). A lock
+        // refusal prints the refusal and its fix, then falls through to the tracked spawn below. A new
+        // CC session has no transcript to resume yet: it spawns, and locks after its first turn (B5).
+        // B5a (as amended): a new CC session on a durable-only agent is created locked in one request
+        // and attached; it never registers tracked or runs an attended first turn.
+        if (durablePlan.durableOnly && locksAfterFirstTurn(durablePlan)) {
+            process.exitCode = await createLockedInsteadOfSpawn(durablePlan, scenario, servedAgentId, durableKey, { model: options.model, effort: options.effort, trimMcp: options.trimMcp });
+            return;
+        }
+        const row = await registerDurableSession(durablePlan, scenario, servedAgentId);
+        clearLaunching(scenario, liveLaunchingDeps(MNEMOM_DIR));
+        durableRow = firstTurnRow(row, durablePlan);
+        lockAfterFirstTurn = locksAfterFirstTurn(durablePlan);
+        if (durablePlan.lock && !lockAfterFirstTurn) {
+            const locked = await lockInsteadOfSpawn(row, scenario, durableKey, durablePlan.durableOnly);
+            if (locked !== null) {
+                process.exitCode = locked;
+                return;
+            }
+        }
+    }
     // A relaunch that continues an earlier conversation resumes that Claude Code session, so the
     // same CC session id keeps owning the conversation's main goal on the gateway (a fresh
     // --session-id would land on a new, empty m.<sha16> thread). The server shape hosts many
@@ -612,6 +695,8 @@ export async function agentCommand(scenarioArg, options = {}) {
     // org is the key owner's personal org, where the agent does not exist, so the API answers 404
     // and the launch would fail closed (door1-path run 40400479127). Same read as Record's.
     let sessionKeyId;
+    // What a Remote Control launch needs to re-mint before the 24h expiry (startSessionKeyRenewal).
+    let sessionKeyRenewal;
     // One read of the served agent's org serves the mint and Record; each says why in its own
     // words when the read fails and the account org is used instead.
     let servedOrg;
@@ -632,13 +717,15 @@ export async function agentCommand(scenarioArg, options = {}) {
                 say(fmt.warn(`mnemom agent: could not read ${servedAgentId}'s org (${o.fallback}); minting the session key under ${account.orgId}.`));
             mintOrgId = o.orgId;
         }
-        const minted = await mintSessionGatewayKey(defaultSessionKeyDeps(say), {
+        const mintArgs = {
             agentId: servedAgentId,
             orgId: mintOrgId,
             sessionId: cc.id ?? undefined,
-        });
+        };
+        const minted = await mintSessionGatewayKey(defaultSessionKeyDeps(say), mintArgs);
         mnemomKey = minted.key;
         sessionKeyId = minted.keyId;
+        sessionKeyRenewal = { expiresAt: minted.expiresAt, mintArgs };
     }
     // ── 1M context window by default ── the model this launch runs on gets `[1m]` when it has no
     // window suffix and supports 1M (resolveWindowModel); an explicit choice — the
@@ -700,6 +787,7 @@ export async function agentCommand(scenarioArg, options = {}) {
                 goalMode,
                 scenario,
                 launcherVersion: CLI_VERSION,
+                ...(options.durable ? { durable: true } : {}),
                 // 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]
@@ -799,6 +887,16 @@ export async function agentCommand(scenarioArg, options = {}) {
             }),
             knownCcSessionId: cc.id ?? continuedCcSessionId,
             plugin,
+            ...(durableRow && options.durable
+                ? {
+                    durableHandover: {
+                        row: durableRow,
+                        name: scenario,
+                        launcherKey: options.durable.launcherKey,
+                        lockAfterFirstTurn,
+                    },
+                }
+                : {}),
             receipt: experimental.includes("record")
                 ? { orgId: recordOrgId, agentId: servedAgentId }
                 : undefined,
@@ -828,6 +926,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         yolo,
         ccSessionId,
         sessionKeyId,
+        sessionKeyRenewal,
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
@@ -1308,30 +1407,14 @@ function launchTerminal(ctx) {
         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
-    // ANTHROPIC_AUTH_TOKEN is a fixed non-secret placeholder.
-    //
-    // A subscription launch (no Anthropic key) sets NO auth token: Claude Code then sends its
-    // own claude.ai login to the gateway (lib/subscription-login.ts).
-    let childEnv;
+    // The api-key arm (key in ANTHROPIC_CUSTOM_HEADERS, placeholder auth token, ANTHROPIC_API_KEY
+    // unset) or the subscription arm (Claude Code's own claude.ai login), shared with durable seats
+    // (lib/subscription-login.ts launchChildEnv). MNE-8245 defense-in-depth: the owner's own Mnemom
+    // credential must never ride through to the session just because it happened to sit in the
+    // CLI's OWN process env — the session's only Mnemom credential is the minted key already
+    // spliced into `headers` above (ctx.mnemomKey).
+    const childEnv = launchChildEnv(process.env, ctx.door, headers, ctx.anthropicKey);
     let feed = null;
-    if (ctx.anthropicKey) {
-        childEnv = { ...process.env };
-        delete childEnv.ANTHROPIC_API_KEY;
-        childEnv.ANTHROPIC_BASE_URL = ctx.door;
-        childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
-        childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
-    }
-    else {
-        childEnv = subscriptionChildEnv(process.env, ctx.door, headers);
-    }
-    // MNE-8245 defense-in-depth: the owner's own Mnemom credential must never ride
-    // through to the session just because it happened to sit in the CLI's OWN
-    // process env (a shell MNEMOM_API_KEY / MNEMOM_TOKEN export, or a leftover
-    // MNEMOM_AGENT_MNEMOM_KEY) — the session's only Mnemom credential is the
-    // minted key already spliced into `headers` above (ctx.mnemomKey).
-    stripOwnerCredentialEnv(childEnv);
     // 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);
@@ -1341,10 +1424,9 @@ function launchTerminal(ctx) {
     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
-    // terminal launch — interactive and `-p` passthrough alike; a user's own value wins. The
-    // user's CLAUDE_AUTOCOMPACT_PCT_OVERRIDE / CLAUDE_CODE_AUTO_COMPACT_WINDOW ride through
-    // untouched in the copied env (USER_AUTOCOMPACT_ENV).
-    applyGatewayHintHeaders(childEnv);
+    // terminal launch — interactive and `-p` passthrough alike; a user's own value wins: set by
+    // launchChildEnv above (shared with durable seats). The user's CLAUDE_AUTOCOMPACT_PCT_OVERRIDE /
+    // CLAUDE_CODE_AUTO_COMPACT_WINDOW ride through untouched in the copied env (USER_AUTOCOMPACT_ENV).
     if (ctx.options.slack)
         args.push(...slackChannelArgs(sessionName));
     // The status-bar segment (lib/statusline.ts). Claude Code only; the user's own
@@ -1389,8 +1471,12 @@ function launchTerminal(ctx) {
     }
     let recordStatePath;
     const run = () => {
+        const savedTty = ctx.durableHandover ? saveTtyMode() : null;
         const launchedSec = Math.floor(Date.now() / 1000);
         const child = spawn(ctx.cli.bin, args, { stdio: "inherit", env: childEnv });
+        const firstTurn = ctx.durableHandover?.lockAfterFirstTurn ? ctx.durableHandover : null;
+        if (firstTurn)
+            void liveLockAfterFirstTurn(firstTurn.row, firstTurn.name, firstTurn.launcherKey, () => child.exitCode === null && child.signalCode === null);
         // W1.8: report the session's commits while it runs; no record state (no proxy) → no reports.
         const commits = ctx.commitReport && ctx.orgId && recordStatePath
             ? startCommitReporter({
@@ -1411,6 +1497,14 @@ function launchTerminal(ctx) {
                 if (ctx.sessionKeyId) {
                     await revokeSessionGatewayKey(defaultSessionKeyDeps(say), ctx.sessionKeyId);
                 }
+                // A lock handover SIGKILLs the frozen claude once the daemon's seat runs the conversation:
+                // attach to it instead of dying with the child (C02-R26 step 7). Never relaunches claude.
+                const h = ctx.durableHandover;
+                if (mayBeHandover(h !== undefined, signal) && h) {
+                    const attached = await liveParentAfterChildEnded(h.row, h.name, h.launcherKey, savedTty);
+                    if (attached !== null)
+                        process.exit(attached);
+                }
                 if (signal) {
                     process.kill(process.pid, signal);
                     return;
@@ -1557,6 +1651,8 @@ export function turnProxyWanted(env) {
     const raw = (env.MNEMOM_AGENT_TURN_HEADER ?? "").trim().toLowerCase();
     return !["0", "off", "false", "no"].includes(raw);
 }
+/** The flag that lets base-url-proxy.mjs use an http door on a loopback literal (C17-R16 T3). */
+export const BU_HTTP_DOOR_ENV = "MNEMOM_AGENT_BU_HTTP_DOOR";
 /**
  * Start base-url-proxy.mjs in front of `door`; calls `done` exactly once with its
  * `http://127.0.0.1:<port>` base URL, or with null (after a one-line warning) when it does not
@@ -1582,6 +1678,13 @@ export function startBaseUrlProxy(door, done, opts = {}) {
     };
     // MNE-8245 defense-in-depth: the proxy reads none of the owner's own Mnemom credential vars.
     stripOwnerCredentialEnv(proxyEnv);
+    // C17-R16 T3: the proxy never reads TEST_MODE itself (one test-mode module per repo), so the seam
+    // decision is made here and handed over as a non-secret flag; an inherited flag never passes.
+    // httpDoorAllowed answers true for any https door, so the flag is set for an http door only.
+    if (/^http:/i.test(door) && httpDoorAllowed(door, process.env))
+        proxyEnv.MNEMOM_AGENT_BU_HTTP_DOOR = "1";
+    else
+        delete proxyEnv.MNEMOM_AGENT_BU_HTTP_DOOR;
     const proxy = spawn(opts.node ?? process.execPath, [script], {
         env: proxyEnv,
         stdio: ["ignore", "pipe", "ignore"],
@@ -1688,13 +1791,28 @@ function launchRemoteControl(ctx) {
         MNEMOM_AGENT_RC_PARENT_PID: String(process.pid),
         MNEMOM_AGENT_RC_AUTH: ctx.anthropicKey ? "api-key" : "subscription",
     };
+    // The minted key expires after 24h and an RC seat outlives that: renew it over a control pipe
+    // (fd 3) — the new key never touches argv, env or disk. Only its id and expiry ride in the env.
+    const renewing = Boolean(ctx.sessionKeyId && ctx.sessionKeyRenewal && ctx.mnemomKey);
+    if (renewing) {
+        proxyEnv.MNEMOM_AGENT_RC_CONTROL_FD = "3";
+        proxyEnv.MNEMOM_AGENT_RC_MNEMOM_KEY_ID = ctx.sessionKeyId;
+        proxyEnv.MNEMOM_AGENT_RC_MNEMOM_KEY_EXPIRES_AT = ctx.sessionKeyRenewal?.expiresAt;
+    }
     // MNE-8245 defense-in-depth: the proxy gets the session's (minted) Mnemom key on stdin only
     // and reads none of the owner's own Mnemom credential vars, so they never ride into its env.
     stripOwnerCredentialEnv(proxyEnv);
     const proxy = spawn("node", [proxyScript], {
         env: proxyEnv,
-        stdio: ["pipe", "pipe", "inherit"],
+        stdio: ["pipe", "pipe", "inherit", renewing ? "pipe" : "ignore"],
     });
+    const renewal = renewing
+        ? startRcSessionKeyRenewal(proxy, proxyLog, {
+            keyId: ctx.sessionKeyId,
+            expiresAt: ctx.sessionKeyRenewal?.expiresAt,
+            mintArgs: ctx.sessionKeyRenewal?.mintArgs,
+        })
+        : undefined;
     let stopped = false;
     const stopProxyAndTempDir = () => {
         if (!proxy.killed) {
@@ -1721,9 +1839,12 @@ function launchRemoteControl(ctx) {
         if (stopped)
             return;
         stopped = true;
+        renewal?.stop();
         stopProxyAndTempDir();
-        if (ctx.sessionKeyId) {
-            await revokeSessionGatewayKey(defaultSessionKeyDeps(say), ctx.sessionKeyId);
+        // After a renewal the proxy holds a newer key than the one minted at launch: revoke that one.
+        const keyId = renewal?.currentKeyId() ?? ctx.sessionKeyId;
+        if (keyId) {
+            await revokeSessionGatewayKey(defaultSessionKeyDeps(say), keyId);
         }
     };
     // Last-resort SYNC fallback only — Node's "exit" handlers cannot await, so this branch never
@@ -1736,6 +1857,7 @@ function launchRemoteControl(ctx) {
         if (stopped)
             return;
         stopped = true;
+        renewal?.stop();
         stopProxyAndTempDir();
     });
     // Secrets on stdin — four lines (anthropic, mnemom, openai, proxy credential). An api-key launch
@@ -1755,8 +1877,9 @@ function launchRemoteControl(ctx) {
     let stdoutBuf = "";
     const start = Date.now();
     const tryStart = () => {
-        // Cleanup already ran (a refusal, or the exit fallback reaped the proxy): stop polling, so a
-        // proxy killed by a signal (exitCode stays null) never reaches the 15s refusal afterwards.
+        // Torn down already (a refusal, the sync exit fallback, or an awaited onExit() from the proxy's
+        // error / stdin paths): stop polling, so a proxy killed by a signal (exitCode stays null) never
+        // reaches the 15s refusal and no later arm can call process.exit(1) a second time.
         if (stopped)
             return;
         const m = stdoutBuf.match(/^READY (\d+) (.+)$/m);
@@ -1793,6 +1916,58 @@ function launchRemoteControl(ctx) {
     });
     tryStart();
 }
+/** The longest line the proxy sends the launcher (`remint <key id>`) is far shorter than this. */
+export const RC_CONTROL_LINE_MAX = 1024;
+/**
+ * Renew the Remote Control proxy's session key over its control pipe (fd 3; rc-proxy.mjs SESSION
+ * KEY RENEWAL): a `key <id> <expires> <key>` line before each expiry, a `remint <id>` line from the
+ * proxy when the gateway rejects its key, answered with a new key or `key-failed`. Renewal events
+ * go to the proxy log (the terminal belongs to Claude Code by then), as key ids and expiry times.
+ */
+export function startRcSessionKeyRenewal(proxy, proxyLog, initial, makeDeps = defaultSessionKeyDeps) {
+    const control = proxy.stdio?.[3];
+    if (!control)
+        return undefined;
+    const logLine = (line) => {
+        try {
+            appendFileSync(proxyLog, `${new Date().toISOString()} launcher: ${line}\n`);
+        }
+        catch {
+            /* best effort: the log dir may be gone at exit */
+        }
+    };
+    control.on("error", () => {
+        /* the proxy exited: the next delivery fails and is logged */
+    });
+    const renewal = startSessionKeyRenewal({
+        deps: makeDeps(logLine),
+        mintArgs: initial.mintArgs,
+        initial: { keyId: initial.keyId, expiresAt: initial.expiresAt },
+        deliver: (minted) => {
+            if (control.destroyed || !control.writable)
+                throw new Error("the proxy's control pipe is closed");
+            control.write(`key ${minted.keyId} ${minted.expiresAt} ${minted.key}\n`);
+        },
+        refuse: (reason) => {
+            if (!control.destroyed && control.writable)
+                control.write(`key-failed ${reason}\n`);
+        },
+    });
+    let buf = "";
+    control.on("data", (chunk) => {
+        buf += chunk.toString("utf8");
+        let i;
+        while ((i = buf.indexOf("\n")) >= 0) {
+            const [cmd, keyId] = buf.slice(0, i).split(" ");
+            buf = buf.slice(i + 1);
+            if (cmd === "remint")
+                void renewal.renew("rejected", keyId);
+        }
+        if (buf.length > RC_CONTROL_LINE_MAX)
+            buf = ""; // a runaway line, never a real request
+    });
+    return renewal;
+}
 function spawnRcCli(ctx) {
     // Session name for the claude.ai session list: "<agent>-<scenario>", unless
     // the caller passed their own name after `--` (`--name x`, `--name=x`, `-n x`; lifted out here).

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

@@ -0,0 +1,50 @@
+/**
+ * The durable lines of `mnemom agent doctor` (BACKBONE C1 "doctor (MFA, branch protection)";
+ * C02-R19): for each of the caller's open sessions, the MFA and branch-protection verdicts lock would
+ * compute at that moment, with the same probes and codes. The API computes them (S1 lock.ts steps
+ * `mfa` and `protection`); the doctor only renders. Read-only: one GET per session, never a POST.
+ *
+ * Not frozen by S1 (A2 owns it; gaps/c1-doctor-lock-preflight.md):
+ *   GET /v1/agent/sessions/{cid}/lock?agent_id=&dry_run=true
+ *     200 {mfa, repos: [{repo, verdict | protected | reason, pushable?}]}  (read defensively), or the
+ *     lock refusal envelope of the first failing step (403 durable_lock_mfa_required, 409
+ *     durable_lock_branch_unprotected {refusals}, 503 durable_precondition_unavailable, ...).
+ * A route that is absent (404/405) prints one info line; nothing here is ever a MISS, so the doctor's
+ * exit status keeps meaning "launch-ready".
+ */
+import { type ApiAnswer, type RegistryRow } from "../lib/durable/api.js";
+export interface DoctorApi {
+    listSessions(filter: {
+        name?: string;
+        agentId?: string;
+    }): Promise<RegistryRow[]>;
+    lockPreflight(cid: string, agentId: string): Promise<ApiAnswer>;
+}
+export interface DoctorLine {
+    mark: "ok" | "warn" | "info";
+    text: string;
+    hint?: string;
+}
+export type RepoState = "protected" | "unprotected" | "unsupported_host" | "unknown";
+export type PreflightVerdict = {
+    kind: "verdict";
+    mfa: "ok" | "missing" | "unknown";
+    repos: Array<{
+        repo: string;
+        state: RepoState;
+    }>;
+} | {
+    kind: "absent";
+} | {
+    kind: "unavailable";
+    detail: string;
+} | {
+    kind: "earlier";
+    code: string;
+};
+/** At most this many open sessions are checked (one GET each). */
+export declare const DOCTOR_SESSION_CAP = 5;
+/** Read a preflight answer into the verdict the doctor prints. */
+export declare function preflightVerdict(a: ApiAnswer): PreflightVerdict;
+/** The doctor's durable lines: one block per open session (newest first as listed), capped. */
+export declare function durableDoctorLines(api: DoctorApi): Promise<DoctorLine[]>;