@mnemom/mnemom 0.17.32-next.2 → 0.17.32-next.4

package/dist/commands/agent.js

@@ -31,7 +31,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { FEED_ENV, statuslineLaunch } from "../lib/statusline.js";
+import { FEED_ENV, launchStatusLine, statuslineLaunch } from "../lib/statusline.js";
 import { startFeed } from "../lib/statusline-feed.js";
 import { isPrerelease } from "../lib/update/semver.js";
 import { attributionSettings, COMMIT_REPORT_ENV, commitReportEnabled, realGit, startCommitReporter, } from "../lib/commit-report.js";
@@ -39,6 +39,7 @@ 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 { LEDGER_FILE, appendSessionRecord, findResumeCandidate, readSessionRecords, resolveRetentionDays, resumedContextProfile, toLedgerContract, } from "../lib/agent-ledger.js";
 import { isLoggedIn } from "../lib/auth.js";
@@ -51,7 +52,7 @@ import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
 import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, } from "../lib/login-detect.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { defaultAgentSlug, ensureClaimedServedAgent, ensureSessionAndBalance, isQuietPreambleExit, readComposedProtection, resolveDefaultSlug, resolvePinnedAgent, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, HANDOFF_RC_MNEMOM_KEY_ENV_NAME, malformedAgentIdMessage, parseAgentRef, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, passthroughModel, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, liftPassthroughName, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, HANDOFF_RC_MNEMOM_KEY_ENV_NAME, malformedAgentIdMessage, parseAgentRef, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, passthroughModel, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, liftPassthroughName, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, stripOwnerCredentialEnv, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
 import { appendPluginDirsEnv, applyPluginEnv, pluginEnabled, pluginPlanLine, resolvePluginDir, } from "../lib/claude-plugin.js";
@@ -589,6 +590,56 @@ export async function agentCommand(scenarioArg, options = {}) {
     // hosts many sessions in one process, so it records none and injects nothing.
     const cc = shape === "server" ? { id: null, inject: false } : pickCcSessionId(options.passthrough ?? []);
     const ccSessionId = cc.inject && cc.id ? cc.id : undefined;
+    // ── MNE-8245: the LAUNCHED session must never hold the owner's own Mnemom
+    // key ── whenever `mnemomKey` above is set it is the owner's own credential:
+    // a subscription launch's identity anchor, or (since #2291's safe core) the
+    // stored/pinning key an api-key launch also sends. It is used ONLY for the
+    // claim call already made, and for nothing after this point: replace it here with a session-scoped, agent-bound,
+    // 24h `['gateway']`-only key minted fresh for THIS launch (MNE-8244's
+    // session-keys route), via the CLI PROCESS's own ambient auth — never
+    // anything read back out of the launched session. Minting is itself
+    // owner-gated server-side (a session key can never mint a broader one),
+    // so this closes the loop even if a future bug reintroduced a leak.
+    //
+    // FAILS CLOSED: `mintSessionGatewayKey` throws on ANY problem (network,
+    // non-2xx, malformed body, or scopes/kind not exactly a session-only
+    // `['gateway']` key); that throw is NOT caught here, so it propagates to
+    // index.ts's top-level handler, which prints the message and exits
+    // non-zero before anything is spawned. There is no fallback path back to
+    // `mnemomKey`'s original (owner) value.
+    //
+    // The mint names the served agent's org, not the account org: with an org API key the account
+    // 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;
+    // 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;
+    const readServedOrg = (accountOrgId) => 
+    // Every caller passes account.orgId, so the first call's fallback holds for the rest.
+    (servedOrg ??= (async () => {
+        let fallback;
+        const orgId = await recordOrgFor(servedAgentId, accountOrgId, {
+            onFallback: (reason) => (fallback = reason),
+        });
+        return { orgId, fallback };
+    })());
+    if (mnemomKey) {
+        let mintOrgId = account.orgId;
+        if (account.orgId) {
+            const o = await readServedOrg(account.orgId);
+            if (o.fallback)
+                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), {
+            agentId: servedAgentId,
+            orgId: mintOrgId,
+            sessionId: cc.id ?? undefined,
+        });
+        mnemomKey = minted.key;
+        sessionKeyId = minted.keyId;
+    }
     // ── 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
     // CLAUDE_CODE_DISABLE_1M_CONTEXT opt-out, a passthrough `-- --model`, a suffixed id — is kept.
@@ -713,8 +764,10 @@ export async function agentCommand(scenarioArg, options = {}) {
             commitReport: cli.name === "claude" && commitReportEnabled(process.env[COMMIT_REPORT_ENV], CLI_VERSION),
             fedStatusline: cli.name === "claude" && fedStatuslineWanted(CLI_VERSION, Boolean(goalMode), process.env),
         }) && account.orgId
-            ? await recordOrgFor(servedAgentId, account.orgId, {
-                onFallback: (reason) => say(fmt.warn(`mnemom agent: record: could not read ${servedAgentId}'s org (${reason}); using ${account.orgId}, which may hold none of this session's record.`)),
+            ? await readServedOrg(account.orgId).then((o) => {
+                if (o.fallback)
+                    say(fmt.warn(`mnemom agent: record: could not read ${servedAgentId}'s org (${o.fallback}); using ${account.orgId}, which may hold none of this session's record.`));
+                return o.orgId;
             })
             : account.orgId;
         launchTerminal({
@@ -734,6 +787,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             yolo,
             contextHint,
             ccSessionId,
+            sessionKeyId,
             handoffMcpConfigPath,
             resumeHint: (id) => resumeHintLine({
                 scenario,
@@ -773,6 +827,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         options: launchOptions,
         yolo,
         ccSessionId,
+        sessionKeyId,
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
@@ -1271,6 +1326,12 @@ function launchTerminal(ctx) {
     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);
@@ -1312,7 +1373,8 @@ function launchTerminal(ctx) {
         const ownSettings = hasOwnSettingsFlag(passthrough);
         const guard = applyAutocompactGuard(childEnv, ctx.options, !ownSettings);
         const extra = launchSettingsExtra({
-            statusline: sl?.settings ?? null,
+            // Fed: a timed redraw, so totals that land after the last turn still reach the screen.
+            statusline: launchStatusLine(sl?.settings ?? null, feed !== null),
             commitReport: Boolean(ctx.commitReport),
             ownSettings,
             conversationId: ctx.conversationId,
@@ -1343,24 +1405,30 @@ function launchTerminal(ctx) {
             process.exit(1);
         });
         child.on("exit", (code, signal) => {
-            if (signal)
-                process.kill(process.pid, signal);
-            else
-                void (async () => {
-                    // The conduct receipt and the last commit sweep run side by side, each under its own
-                    // hard deadline inside W1.3's exit budget; neither changes the exit code.
-                    const swept = commits?.finish().catch(() => undefined);
-                    if (ctx.receipt)
-                        await sayConductReceipt({ ...ctx.receipt, statePath: recordStatePath });
-                    await swept;
-                    // Claude Code's own last line is "Resume this session with: claude --resume <id>",
-                    // which reopens it OUTSIDE Mnemom (ungoverned, unbilled). Ours goes after it, last.
-                    if (code === 0 && ctx.resumeHint && wantsResumeHint(ctx.cli, args)) {
-                        const id = ctx.knownCcSessionId ?? newestCcSessionIn(process.cwd(), process.env);
-                        say(ctx.resumeHint(id));
-                    }
-                    process.exit(code ?? 0);
-                })();
+            void (async () => {
+                // MNE-8245: best-effort revoke of the minted session-scoped key — a failure
+                // here is non-fatal (the key is 24h-TTL'd regardless); never blocks exit.
+                if (ctx.sessionKeyId) {
+                    await revokeSessionGatewayKey(defaultSessionKeyDeps(say), ctx.sessionKeyId);
+                }
+                if (signal) {
+                    process.kill(process.pid, signal);
+                    return;
+                }
+                // The conduct receipt and the last commit sweep run side by side, each under its own
+                // hard deadline inside W1.3's exit budget; neither changes the exit code.
+                const swept = commits?.finish().catch(() => undefined);
+                if (ctx.receipt)
+                    await sayConductReceipt({ ...ctx.receipt, statePath: recordStatePath });
+                await swept;
+                // Claude Code's own last line is "Resume this session with: claude --resume <id>",
+                // which reopens it OUTSIDE Mnemom (ungoverned, unbilled). Ours goes after it, last.
+                if (code === 0 && ctx.resumeHint && wantsResumeHint(ctx.cli, args)) {
+                    const id = ctx.knownCcSessionId ?? newestCcSessionIn(process.cwd(), process.env);
+                    say(ctx.resumeHint(id));
+                }
+                process.exit(code ?? 0);
+            })();
         });
     };
     // Implicit goal mode: put the local base-URL proxy in front of the door so each main request
@@ -1503,16 +1571,19 @@ export function startBaseUrlProxy(door, done, opts = {}) {
     // The receipt's record state (lineage key, record URL: non-secret) lives beside the log and is
     // removed with it on exit, after the receipt has read it.
     const recordStatePath = opts.recordState ? join(logDir, "record.json") : undefined;
+    const proxyEnv = {
+        ...process.env,
+        MNEMOM_AGENT_BU_DOOR: door,
+        MNEMOM_AGENT_BU_CWD: process.cwd(),
+        MNEMOM_AGENT_BU_LOG: process.env.MNEMOM_AGENT_TURN_PROXY_LOG || join(logDir, "proxy.log"),
+        MNEMOM_AGENT_BU_PARENT_PID: String(process.pid),
+        ...(opts.turnHeader === false ? { MNEMOM_AGENT_TURN_HEADER: "0" } : {}),
+        ...(recordStatePath ? { MNEMOM_AGENT_BU_RECORD_STATE: recordStatePath } : {}),
+    };
+    // MNE-8245 defense-in-depth: the proxy reads none of the owner's own Mnemom credential vars.
+    stripOwnerCredentialEnv(proxyEnv);
     const proxy = spawn(opts.node ?? process.execPath, [script], {
-        env: {
-            ...process.env,
-            MNEMOM_AGENT_BU_DOOR: door,
-            MNEMOM_AGENT_BU_CWD: process.cwd(),
-            MNEMOM_AGENT_BU_LOG: process.env.MNEMOM_AGENT_TURN_PROXY_LOG || join(logDir, "proxy.log"),
-            MNEMOM_AGENT_BU_PARENT_PID: String(process.pid),
-            ...(opts.turnHeader === false ? { MNEMOM_AGENT_TURN_HEADER: "0" } : {}),
-            ...(recordStatePath ? { MNEMOM_AGENT_BU_RECORD_STATE: recordStatePath } : {}),
-        },
+        env: proxyEnv,
         stdio: ["ignore", "pipe", "ignore"],
     });
     process.on("exit", () => {
@@ -1584,27 +1655,28 @@ function launchRemoteControl(ctx) {
     const rcDir = mkdtempSync(join(rcStateRoot(), "mnemom-code-rc."));
     writeFileSync(join(rcDir, "owner.pid"), `${process.pid}\n`, { mode: 0o600 }); // rc-state.mjs sweep
     const proxyLog = process.env.MNEMOM_AGENT_RC_PROXY_LOG || join(rcDir, "proxy.log");
+    const proxyEnv = {
+        ...process.env,
+        MNEMOM_AGENT_RC_DOOR: ctx.door,
+        MNEMOM_AGENT_RC_AGENT: ctx.agent,
+        MNEMOM_AGENT_RC_AGENT_ID: ctx.agentId ?? "",
+        MNEMOM_AGENT_RC_CONVERSATION_ID: ctx.conversationId,
+        MNEMOM_AGENT_RC_CONTRACT_B64: ctx.envelope?.base64 ?? "",
+        MNEMOM_AGENT_RC_GOAL_MODE: ctx.goalMode ?? "",
+        MNEMOM_AGENT_RC_SESSION_CONFIG: ctx.sessionConfigB64 ?? "",
+        MNEMOM_AGENT_RC_PROXY_LOG: proxyLog,
+        MNEMOM_AGENT_RC_PARENT_PID: String(process.pid),
+        MNEMOM_AGENT_RC_AUTH: ctx.anthropicKey ? "api-key" : "subscription",
+    };
+    // 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: {
-            ...process.env,
-            MNEMOM_AGENT_RC_DOOR: ctx.door,
-            MNEMOM_AGENT_RC_AGENT: ctx.agent,
-            MNEMOM_AGENT_RC_AGENT_ID: ctx.agentId ?? "",
-            MNEMOM_AGENT_RC_CONVERSATION_ID: ctx.conversationId,
-            MNEMOM_AGENT_RC_CONTRACT_B64: ctx.envelope?.base64 ?? "",
-            MNEMOM_AGENT_RC_GOAL_MODE: ctx.goalMode ?? "",
-            MNEMOM_AGENT_RC_SESSION_CONFIG: ctx.sessionConfigB64 ?? "",
-            MNEMOM_AGENT_RC_PROXY_LOG: proxyLog,
-            MNEMOM_AGENT_RC_PARENT_PID: String(process.pid),
-            MNEMOM_AGENT_RC_AUTH: ctx.anthropicKey ? "api-key" : "subscription",
-        },
+        env: proxyEnv,
         stdio: ["pipe", "pipe", "inherit"],
     });
     let stopped = false;
-    const onExit = () => {
-        if (stopped)
-            return;
-        stopped = true;
+    const stopProxyAndTempDir = () => {
         if (!proxy.killed) {
             try {
                 proxy.kill("SIGTERM");
@@ -1620,7 +1692,32 @@ function launchRemoteControl(ctx) {
             /* best effort */
         }
     };
-    process.on("exit", onExit);
+    // MNE-8245 review-fix: this MUST be awaited by every call site below, and exit/re-signal must
+    // happen only after it settles — a fire-and-forget `void revokeSessionGatewayKey(...)`
+    // immediately followed by `process.exit()`/`process.kill()` never lets the revoke's fetch even
+    // start before the process dies. revokeSessionGatewayKey bounds itself internally (~3s via
+    // AbortSignal.timeout in lib/session-key.ts), so awaiting it here cannot hang the exit path.
+    const onExit = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        stopProxyAndTempDir();
+        if (ctx.sessionKeyId) {
+            await revokeSessionGatewayKey(defaultSessionKeyDeps(say), ctx.sessionKeyId);
+        }
+    };
+    // Last-resort SYNC fallback only — Node's "exit" handlers cannot await, so this branch never
+    // revokes the key (the 24h TTL covers it). It exists solely to guarantee the proxy child and
+    // temp dir are cleaned up on an exit path that didn't go through (and await) onExit() above,
+    // e.g. an unexpected top-level throw. Every normal exit path in this function calls onExit()
+    // directly and awaits it before exiting, so this is a no-op on the common paths (`stopped` is
+    // already true by the time it fires).
+    process.on("exit", () => {
+        if (stopped)
+            return;
+        stopped = true;
+        stopProxyAndTempDir();
+    });
     // Secrets on stdin — three lines (anthropic, mnemom, openai). An api-key launch sends the
     // Anthropic key, plus this machine's Mnemom key when it has one (the key principal; always
     // with a pin); a subscription launch sends the Mnemom key only (the identity anchor — the
@@ -1632,21 +1729,24 @@ function launchRemoteControl(ctx) {
         if (err.code === "EPIPE")
             return;
         say(`mnemom agent: could not hand the secrets to the Remote Control proxy: ${err.message}`);
-        onExit();
-        process.exit(1);
+        void onExit().finally(() => process.exit(1));
     });
     proxy.stdin?.end(rcProxyStdin(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.
+        if (stopped)
+            return;
         const m = stdoutBuf.match(/^READY (\d+) (.+)$/m);
         if (m) {
             const port = m[1];
             const ca = m[2].trim();
             if (!existsSync(ca)) {
                 say("mnemom agent: malformed READY line from the Remote Control proxy.");
-                onExit();
-                process.exit(1);
+                void onExit().finally(() => process.exit(1));
+                return;
             }
             spawnRcCli({ ...ctx, port, ca, onExit });
             return;
@@ -1654,13 +1754,13 @@ function launchRemoteControl(ctx) {
         if (proxy.exitCode !== null) {
             say("mnemom agent: the Remote Control proxy exited before it was ready — refusing to launch un-routed.");
             redactedProxyLog(proxyLog);
-            onExit();
-            process.exit(1);
+            void onExit().finally(() => process.exit(1));
+            return;
         }
         if (Date.now() - start > 15_000) {
             say("mnemom agent: the Remote Control proxy did not report READY within 15s.");
-            onExit();
-            process.exit(1);
+            void onExit().finally(() => process.exit(1));
+            return;
         }
         setTimeout(tryStart, 200);
     };
@@ -1669,8 +1769,7 @@ function launchRemoteControl(ctx) {
     });
     proxy.on("error", (err) => {
         say(`mnemom agent: failed to launch the Remote Control proxy: ${err.message}`);
-        onExit();
-        process.exit(1);
+        void onExit().finally(() => process.exit(1));
     });
     tryStart();
 }
@@ -1701,6 +1800,11 @@ function spawnRcCli(ctx) {
         if (!strip.has(k))
             childEnv[k] = v;
     }
+    // MNE-8245 defense-in-depth: see the identical call in launchTerminal — the owner's own
+    // Mnemom credential must never ride through just because it sits in the CLI's own process
+    // env. The RC gate forwards the Mnemom identity via the proxy's own auth plane, never from
+    // this child's env, so there is no legitimate use for these vars here either.
+    stripOwnerCredentialEnv(childEnv);
     childEnv.HTTPS_PROXY = `http://127.0.0.1:${ctx.port}`;
     childEnv.https_proxy = `http://127.0.0.1:${ctx.port}`;
     childEnv.NODE_EXTRA_CA_CERTS = ctx.ca;
@@ -1782,15 +1886,18 @@ function spawnRcCli(ctx) {
     const child = spawn(ctx.cli.bin, args, { stdio: "inherit", env: childEnv });
     child.on("error", (err) => {
         say(`mnemom agent: failed to launch ${ctx.cli.name} under Remote Control: ${err.message}`);
-        ctx.onExit();
-        process.exit(1);
+        void ctx.onExit().finally(() => process.exit(1));
     });
     child.on("exit", (code, signal) => {
-        ctx.onExit();
-        if (signal)
-            process.kill(process.pid, signal);
-        else
-            process.exit(code ?? 0);
+        // MNE-8245 review-fix: await the (internally bounded) revoke before exiting/re-signaling —
+        // the previous fire-and-forget `ctx.onExit()` immediately followed by exit/kill never let the
+        // revoke's fetch start before the process died, so it silently never ran on this path.
+        void ctx.onExit().finally(() => {
+            if (signal)
+                process.kill(process.pid, signal);
+            else
+                process.exit(code ?? 0);
+        });
     });
 }
 function warnServerDrops(options, yolo) {

package/dist/durable/adopt-api.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The A2 calls `sessions adopt` makes (BACKBONE A2: /v1/agent/sessions/{cid} get and lock).
+ *
+ *  - getSession: GET /v1/agent/sessions/{cid}?agent_id&org_id (the existing owner read, which A2
+ *    extends with durable_mode, state, effective_state and cc_session_id).
+ *  - lock: POST S1 ROUTES.own_lock with the closed S1 LockBody, under the caller's
+ *    Idempotency-Key (one per handover, reused on every retry) and LOCK_HTTP_TIMEOUT_MS.
+ *  - lockCheck (PRECHECK): C14-R25 step 1 runs the R17 sharing and R18 lock-precondition checks
+ *    before any SIGSTOP, and the C14 cases assert no request to a path ending in /lock for a
+ *    refused group. S1 freezes no non-mutating check route, so adopt asks
+ *    POST /v1/agent/sessions/{cid}/lock-preconditions with the same LockBody (an A2 assumption,
+ *    written up in the w1 gaps). A 404/405 with no durable code means the route is not served;
+ *    adopt then fails closed: the group is refused before any signal.
+ *
+ * Every answer is an ApiAnswer; nothing here throws on HTTP status.
+ */
+import type { ApiAnswer, AdoptApi } from "./adopt.js";
+export declare const PRECHECK_SUFFIX = "/lock-preconditions";
+export declare const ADOPT_HTTP_TIMEOUT_MS = 30000;
+/**
+ * The lock request's own timeout: below the api's 30 s window after which a pending
+ * Idempotency-Key reservation is taken over by the next call with that key. A same-key retry sent
+ * after a lock timeout therefore reaches the api while the first call's reservation still holds,
+ * and is answered 409 idempotency_key_in_flight (still pending) or with the replayed 2xx.
+ */
+export declare const LOCK_HTTP_TIMEOUT_MS = 20000;
+export interface HttpDeps {
+    base: string;
+    /** Auth headers for the owner (JWT or the owner's API key). */
+    auth(): Promise<Record<string, string>>;
+    fetch(url: string, init: RequestInit): Promise<Response>;
+    idempotencyKey(): string;
+    timeoutMs?: number;
+}
+/** A Response as an ApiAnswer: 2xx ok with its JSON body; else the error envelope's code and details. */
+export declare function answerOf(res: Response): Promise<ApiAnswer>;
+export declare function httpAdoptApi(deps: HttpDeps): AdoptApi;

package/dist/durable/adopt-api.js

@@ -0,0 +1,106 @@
+/**
+ * The A2 calls `sessions adopt` makes (BACKBONE A2: /v1/agent/sessions/{cid} get and lock).
+ *
+ *  - getSession: GET /v1/agent/sessions/{cid}?agent_id&org_id (the existing owner read, which A2
+ *    extends with durable_mode, state, effective_state and cc_session_id).
+ *  - lock: POST S1 ROUTES.own_lock with the closed S1 LockBody, under the caller's
+ *    Idempotency-Key (one per handover, reused on every retry) and LOCK_HTTP_TIMEOUT_MS.
+ *  - lockCheck (PRECHECK): C14-R25 step 1 runs the R17 sharing and R18 lock-precondition checks
+ *    before any SIGSTOP, and the C14 cases assert no request to a path ending in /lock for a
+ *    refused group. S1 freezes no non-mutating check route, so adopt asks
+ *    POST /v1/agent/sessions/{cid}/lock-preconditions with the same LockBody (an A2 assumption,
+ *    written up in the w1 gaps). A 404/405 with no durable code means the route is not served;
+ *    adopt then fails closed: the group is refused before any signal.
+ *
+ * Every answer is an ApiAnswer; nothing here throws on HTTP status.
+ */
+import { routePath } from "../vendor/durable-contract/index.js";
+export const PRECHECK_SUFFIX = "/lock-preconditions";
+export const ADOPT_HTTP_TIMEOUT_MS = 30_000;
+/**
+ * The lock request's own timeout: below the api's 30 s window after which a pending
+ * Idempotency-Key reservation is taken over by the next call with that key. A same-key retry sent
+ * after a lock timeout therefore reaches the api while the first call's reservation still holds,
+ * and is answered 409 idempotency_key_in_flight (still pending) or with the replayed 2xx.
+ */
+export const LOCK_HTTP_TIMEOUT_MS = 20_000;
+/** A Response as an ApiAnswer: 2xx ok with its JSON body; else the error envelope's code and details. */
+export async function answerOf(res) {
+    let body;
+    const text = await res.text();
+    try {
+        body = text === "" ? null : JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    if (res.ok)
+        return { kind: "ok", status: res.status, body };
+    const b = (body && typeof body === "object" ? body : {});
+    const err = (b.error && typeof b.error === "object" ? b.error : b);
+    return {
+        kind: "error",
+        status: res.status,
+        code: typeof err.code === "string" ? err.code : null,
+        details: err.details ?? null,
+        message: typeof err.message === "string"
+            ? err.message
+            : typeof b.error === "string"
+                ? b.error
+                : `HTTP ${res.status}`,
+    };
+}
+async function call(deps, path, init, timeoutMs = ADOPT_HTTP_TIMEOUT_MS) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), deps.timeoutMs ?? timeoutMs);
+    try {
+        const res = await deps.fetch(`${deps.base}${path}`, { ...init, signal: ctl.signal });
+        return await answerOf(res);
+    }
+    catch (e) {
+        if (ctl.signal.aborted)
+            return { kind: "timeout" };
+        return { kind: "network", message: e instanceof Error ? e.message : String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function httpAdoptApi(deps) {
+    const post = async (path, body, key = deps.idempotencyKey(), timeoutMs) => call(deps, path, {
+        method: "POST",
+        headers: {
+            ...(await deps.auth()),
+            "Content-Type": "application/json",
+            "Idempotency-Key": key,
+        },
+        body: JSON.stringify(body),
+    }, timeoutMs);
+    return {
+        async getSession(cid, facts) {
+            const q = new URLSearchParams();
+            if (facts.agentId)
+                q.set("agent_id", facts.agentId);
+            if (facts.orgId)
+                q.set("org_id", facts.orgId);
+            const qs = q.toString();
+            return call(deps, `/v1/agent/sessions/${encodeURIComponent(cid)}${qs ? `?${qs}` : ""}`, {
+                method: "GET",
+                headers: await deps.auth(),
+            });
+        },
+        lockCheck: (cid, body) => post(`/v1/agent/sessions/${encodeURIComponent(cid)}${PRECHECK_SUFFIX}`, body),
+        // One key per handover: the caller passes the same key to every retry of one lock.
+        async lock(cid, body, idempotencyKey) {
+            let path;
+            try {
+                path = routePath("own_lock", cid);
+            }
+            catch (e) {
+                // Never throw after the caller's SIGSTOP: an unroutable id is a refused commit.
+                return { kind: "error", status: 400, code: null, details: null, message: String(e) };
+            }
+            return post(path, body, idempotencyKey ?? deps.idempotencyKey(), LOCK_HTTP_TIMEOUT_MS);
+        },
+    };
+}

package/dist/durable/adopt-live.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The thin live driver for `sessions adopt`: real processes, files, HTTP and the terminal. The
+ * decisions live in adopt.ts (pure over AdoptDeps); this file only wires them to the machine.
+ */
+import { type ExecutorState, type LauncherKey } from "../vendor/durable-contract/index.js";
+import { type SessionRecord } from "../lib/agent-ledger.js";
+import type { AdoptDeps, LedgerFacts } from "./adopt.js";
+/** The ledger facts for a conversation: its newest record. */
+export declare function ledgerFactsFrom(records: readonly SessionRecord[], cid: string): LedgerFacts | null;
+/** The launcher key `durable` (MNEMOM_AGENT_DURABLE, then launcher.toml), default off. */
+export declare function launcherKeyFrom(env: Readonly<Record<string, string | undefined>>, tomlText: string | null): LauncherKey;
+/** The executor state file, or null when absent or not the frozen S1 shape. */
+export declare function executorStateFrom(text: string | null): ExecutorState | null;
+export declare function authHeaders(): Promise<Record<string, string>>;
+/** A [Y/n] answer: anything not starting with n is yes. */
+export declare function answerIsYes(a: string): boolean;
+export declare function liveAdoptDeps(): AdoptDeps;