@mnemom/mnemom 0.17.32-next.4 → 0.17.33

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

@@ -43,9 +43,15 @@ export interface RenderedLinePreview {
     coverage?: string;
     kind: string;
 }
-/** The aip `renderLines` contract, injected (not yet published). */
+/**
+ * The aip `renderLines` contract, injected. Resolves to the lines the card may show; REJECTS
+ * (with the renderer's reasons) when the card is not verifiable or breaks claim-lint, in which
+ * case no link is printed. `period` asks for the period-card surface (reverts always shown).
+ */
 export interface LineRenderer {
-    renderLines(card: unknown): RenderedLinePreview[];
+    renderLines(card: unknown, opts?: {
+        period?: boolean;
+    }): RenderedLinePreview[] | Promise<RenderedLinePreview[]>;
 }
 export interface StatementSource {
     listLines(): Promise<CandidateLine[]>;
@@ -56,6 +62,11 @@ export interface CardIssuer {
 }
 export interface AgentShareDeps {
     source: StatementSource;
+    /**
+     * Optional claim-lint screen (aip `lintRendering`) run on each candidate before it is
+     * offered; returns a reason when the line must not be shared. Word lists live in aip only.
+     */
+    screen?: (line: SharedCardLine) => Promise<string | null> | string | null;
     issuer: CardIssuer;
     renderer: LineRenderer;
     /** Interactive picker: returns the chosen line ids. */
@@ -66,6 +77,8 @@ export interface AgentShareDeps {
     err: (line: string) => void;
 }
 export interface AgentShareFlags {
+    /** Period card: every offered revert line is included, and a card without one is refused. */
+    period?: boolean;
     lines?: string;
     list?: boolean;
     json?: boolean;

package/dist/commands/agent-share.js

@@ -17,6 +17,7 @@
 import { createInterface } from "node:readline/promises";
 import { getWebsiteUrl } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
+import { aipLineRenderer, aipLineScreen } from "./agent-share-render.js";
 export const AGENT_SHARE_ENV = "MNEMOM_AGENT_SHARE";
 export function agentShareEnabled(env = process.env) {
     return env[AGENT_SHARE_ENV] === "1";
@@ -132,10 +133,16 @@ export async function agentShareCommand(flags, deps, env = process.env) {
     const refused = [];
     for (const c of candidates) {
         const r = refuseReason(c);
-        if (r)
+        if (r) {
             refused.push(r);
+            continue;
+        }
+        const shared = toSharedLine(c);
+        const lint = deps.screen ? await deps.screen(shared) : null;
+        if (lint)
+            refused.push({ id: shared.id, reason: "estimate", detail: lint });
         else
-            offered.push(toSharedLine(c));
+            offered.push(shared);
     }
     if (flags.list) {
         if (flags.json) {
@@ -175,6 +182,15 @@ export async function agentShareCommand(flags, deps, env = process.env) {
         deps.err(fmt.error("No lines picked."));
         return 1;
     }
+    if (flags.period) {
+        for (const l of offered)
+            if (l.kind === "revert" && !ids.includes(l.id))
+                ids.push(l.id);
+        if (!offered.some((l) => l.kind === "revert")) {
+            deps.err(fmt.error("A period card always shows reverts, and none are available to share."));
+            return 1;
+        }
+    }
     const chosen = [];
     for (const id of ids) {
         const r = refused.find((x) => x.id === id);
@@ -202,13 +218,22 @@ export async function agentShareCommand(flags, deps, env = process.env) {
         deps.err(fmt.error(`Refusing to share: ${problem}.`));
         return 1;
     }
+    // The renderer is the gate: nothing is linked unless aip renders the card (verified, lint clean).
+    let rendered;
+    try {
+        rendered = await deps.renderer.renderLines(card, { period: flags.period === true });
+    }
+    catch (error) {
+        deps.err(fmt.error(`Refusing to share: ${error.message}.`));
+        return 1;
+    }
     const link = buildShareLink(card, deps.websiteBase());
     if (flags.json) {
         deps.out(JSON.stringify({ link, lines: chosen }, null, 2));
         return 0;
     }
     deps.out("Your card:");
-    for (const r of deps.renderer.renderLines(card)) {
+    for (const r of rendered) {
         deps.out(`  ${r.text}${r.coverage ? ` (${r.coverage})` : ""}`);
     }
     deps.out("");
@@ -224,12 +249,8 @@ const notConnected = () => {
 export const liveAgentShareDeps = {
     source: { listLines: async () => notConnected() },
     issuer: { issue: async () => notConnected() },
-    renderer: {
-        renderLines: (card) => (card.lines ?? []).map((l) => ({
-            text: `${l.label}: ${l.value}`,
-            kind: l.kind,
-        })),
-    },
+    renderer: aipLineRenderer(undefined),
+    screen: aipLineScreen,
     pick: async (lines) => {
         const rl = createInterface({ input: process.stdin, output: process.stderr });
         try {

package/dist/commands/agent.d.ts

@@ -417,15 +417,30 @@ export interface BaseUrlProxyOptions {
  */
 export declare function startBaseUrlProxy(door: string, done: (baseUrl: string | null, recordStatePath?: string) => void, opts?: BaseUrlProxyOptions): void;
 /**
- * The three secret lines the Remote Control proxy reads on stdin (anthropic, mnemom, openai). The
- * Mnemom key rides line 2 on BOTH auth modes when the launch has one — the proxy forwards it as
- * x-mnemom-api-key either way; a subscription launch always has one, an api-key launch has one
- * when this machine stores one or the launch pins. Never logged.
+ * The four lines the Remote Control proxy reads on stdin (anthropic, mnemom, openai, proxy
+ * credential). The Mnemom key rides line 2 on BOTH auth modes when the launch has one — the proxy
+ * forwards it as x-mnemom-api-key either way; a subscription launch always has one, an api-key
+ * launch has one when this machine stores one or the launch pins. Line 4 is this session's proxy
+ * credential ({@link newRcProxyCredential}). Never logged.
  */
 export declare function rcProxyStdin(ctx: {
     anthropicKey?: string;
     mnemomKey?: string;
+    proxyCredential: string;
 }): string;
+/**
+ * MNE-9233: a fresh per-session credential for the Remote Control proxy. The proxy injects the
+ * owner's keys and its loopback port is reachable by every local process, so it serves only a
+ * caller that presents this value as `Proxy-Authorization: Basic` (rc-proxy.mjs). 32 random bytes,
+ * hex: URL-safe in the HTTPS_PROXY userinfo without escaping.
+ */
+export declare function newRcProxyCredential(): string;
+/**
+ * The HTTPS_PROXY value for the Remote Control child: the proxy's loopback port, with this
+ * session's credential as the userinfo. Claude Code sends it as `Proxy-Authorization` on CONNECT
+ * and on absolute-form requests. The user name must match rc-proxy.mjs's PROXY_USER.
+ */
+export declare function rcProxyUrl(port: string, proxyCredential: string): string;
 /**
  * The agent id a launch pins, or undefined for a name launch: `--agent` when it is a full
  * `mnm-<uuid>` (any case), else launcher.toml `agent_id` (only when no `--agent` was given —

package/dist/commands/agent.js

@@ -27,7 +27,7 @@
  */
 import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync, } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -1620,13 +1620,31 @@ export function startBaseUrlProxy(door, done, opts = {}) {
 // Remote Control launch (terminal RC + headless server) — behind the bundled proxy
 // ───────────────────────────────────────────────────────────────────────────
 /**
- * The three secret lines the Remote Control proxy reads on stdin (anthropic, mnemom, openai). The
- * Mnemom key rides line 2 on BOTH auth modes when the launch has one — the proxy forwards it as
- * x-mnemom-api-key either way; a subscription launch always has one, an api-key launch has one
- * when this machine stores one or the launch pins. Never logged.
+ * The four lines the Remote Control proxy reads on stdin (anthropic, mnemom, openai, proxy
+ * credential). The Mnemom key rides line 2 on BOTH auth modes when the launch has one — the proxy
+ * forwards it as x-mnemom-api-key either way; a subscription launch always has one, an api-key
+ * launch has one when this machine stores one or the launch pins. Line 4 is this session's proxy
+ * credential ({@link newRcProxyCredential}). Never logged.
  */
 export function rcProxyStdin(ctx) {
-    return `${ctx.anthropicKey ?? ""}\n${ctx.mnemomKey ?? ""}\n\n`;
+    return `${ctx.anthropicKey ?? ""}\n${ctx.mnemomKey ?? ""}\n\n${ctx.proxyCredential}\n`;
+}
+/**
+ * MNE-9233: a fresh per-session credential for the Remote Control proxy. The proxy injects the
+ * owner's keys and its loopback port is reachable by every local process, so it serves only a
+ * caller that presents this value as `Proxy-Authorization: Basic` (rc-proxy.mjs). 32 random bytes,
+ * hex: URL-safe in the HTTPS_PROXY userinfo without escaping.
+ */
+export function newRcProxyCredential() {
+    return randomBytes(32).toString("hex");
+}
+/**
+ * The HTTPS_PROXY value for the Remote Control child: the proxy's loopback port, with this
+ * session's credential as the userinfo. Claude Code sends it as `Proxy-Authorization` on CONNECT
+ * and on absolute-form requests. The user name must match rc-proxy.mjs's PROXY_USER.
+ */
+export function rcProxyUrl(port, proxyCredential) {
+    return `http://mnemom:${proxyCredential}@127.0.0.1:${port}`;
 }
 /**
  * The agent id a launch pins, or undefined for a name launch: `--agent` when it is a full
@@ -1652,6 +1670,8 @@ function launchRemoteControl(ctx) {
         }
     }
     const proxyScript = resolveProxyScript();
+    // MNE-9233: only the child launched below may use this session's proxy (stdin line 4 + HTTPS_PROXY).
+    const proxyCredential = newRcProxyCredential();
     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");
@@ -1718,9 +1738,9 @@ function launchRemoteControl(ctx) {
         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
+    // Secrets on stdin — four lines (anthropic, mnemom, openai, proxy credential). 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
     // user's OAuth bearer is what pays). openai is always empty on this Anthropic-only door.
     // A proxy that exits before reading them turns this write into an EPIPE; that is
     // not a failure of its own — the exited-before-READY check below refuses the
@@ -1731,7 +1751,7 @@ function launchRemoteControl(ctx) {
         say(`mnemom agent: could not hand the secrets to the Remote Control proxy: ${err.message}`);
         void onExit().finally(() => process.exit(1));
     });
-    proxy.stdin?.end(rcProxyStdin(ctx));
+    proxy.stdin?.end(rcProxyStdin({ ...ctx, proxyCredential }));
     let stdoutBuf = "";
     const start = Date.now();
     const tryStart = () => {
@@ -1748,7 +1768,7 @@ function launchRemoteControl(ctx) {
                 void onExit().finally(() => process.exit(1));
                 return;
             }
-            spawnRcCli({ ...ctx, port, ca, onExit });
+            spawnRcCli({ ...ctx, port, ca, proxyCredential, onExit });
             return;
         }
         if (proxy.exitCode !== null) {
@@ -1805,8 +1825,8 @@ function spawnRcCli(ctx) {
     // 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.HTTPS_PROXY = rcProxyUrl(ctx.port, ctx.proxyCredential);
+    childEnv.https_proxy = childEnv.HTTPS_PROXY;
     childEnv.NODE_EXTRA_CA_CERTS = ctx.ca;
     childEnv[SESSION_NAME_ENV] = rcName;
     // Autocompact guard (lib/autocompact-guard.ts). The interactive shape gets the --settings layer

package/dist/index.js

@@ -19,6 +19,7 @@ import { agentShareFixtureEnabled, fixtureAgentShareParts, } from "./commands/ag
 import { agentSessionsCommand, agentShowCommand, liveSessionDeps, } from "./commands/agent-sessions.js";
 import { agentGoalPinCommand, agentGoalResetCommand, agentGoalShowCommand, liveGoalDeps, } from "./commands/agent-goal.js";
 import { agentFuelCommand, liveFuelDeps } from "./commands/agent-fuel.js";
+import { runAgentRun } from "./commands/agent-run.js";
 import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -339,6 +340,8 @@ const agentCmd = program
                     configAgentId: cfg.agentId,
                 }),
                 governance,
+                // Setup provisions for the launch, so it authenticates the way the launch will.
+                auth: opts.auth,
             });
             return;
         }
@@ -919,6 +922,7 @@ agentCmd
     .command("share", { hidden: true })
     .description("Build a shareable card from lines of your signed statements and print the share-page link (card in the URL fragment; nothing is posted). Needs MNEMOM_AGENT_SHARE=1")
     .option("--lines <ids>", "Comma-separated line ids to include (skips the picker)")
+    .option("--period", "Period card: always include reverts (refused if none are available)")
     .option("--list", "List the lines available to share and exit")
     .option("--json", "Print JSON instead of text")
     .action(async (opts) => {
@@ -1019,6 +1023,22 @@ agentCmd
         process.exit(1);
     }
 });
+// `mnemom agent run --watch|--once` — the thin runner (ruling 34.12; Doors W-L13): claim served-phase
+// jobs from the org's ready pool and run their signed phases. Exit 0 done/no_job, 1 failed,
+// 2 usage, 3 refused.
+agentCmd
+    .command("run", { hidden: hiddenUnless("dispatch") })
+    .description("EXPERIMENTAL (`mnemom experimental enable dispatch`): run served-phase jobs from your org's pool. " +
+    "The executor key comes from MNEMOM_EXECUTOR_KEY (or --oidc in GitHub Actions); each job prints one outcome line")
+    .option("--watch", "Keep claiming jobs until SIGTERM or SIGINT (the container form)")
+    .option("--once", "Run at most one job, then exit (the CI form)")
+    .option("--fail-mode <mode>", "closed (default) or open; also MNEMOM_RUNNER_FAIL_MODE")
+    .option("--json", "Print only outcome lines on stdout; logs go to stderr")
+    .option("--oidc", "With --once: exchange the GitHub Actions ID token for a one-job key")
+    .hook("preAction", () => requireExperimental("`mnemom agent run`", "dispatch"))
+    .action(async (opts) => {
+    process.exitCode = await runAgentRun(opts);
+});
 // `mnemom agent fuel <file>` — the fuel step (Doors W3.2): one confirmation seals a batch of job
 // contracts through the batch-seal endpoint and commits them to the repo.
 agentCmd

package/dist/lib/api.js

@@ -212,7 +212,23 @@ export async function getAgent(id) {
  */
 export async function listAgents() {
     const data = await gFetch("/v1/agents?limit=100", {}, { fallback: "Failed to list agents" });
-    return data.agents ?? [];
+    return (data.agents ?? []).map(toListItem);
+}
+/**
+ * An org-scoped API key gets its org's fleet from `GET /v1/agents` (`get_org_agent_fleet`), whose
+ * rows carry `agent_id`/`agent_name`; a personal key gets `id`/`name`. Read both as one shape.
+ */
+function toListItem(a) {
+    if (!("agent_id" in a))
+        return a;
+    return {
+        id: a.agent_id,
+        name: a.agent_name ?? null,
+        email: a.owner_email ?? null,
+        created_at: a.created_at,
+        last_seen: a.last_seen ?? null,
+        containment_status: a.containment_status ?? null,
+    };
 }
 /**
  * Every agent the caller OWNS, across all their orgs — `GET /v1/agents?scope=all`: rows whose

package/dist/lib/auth.d.ts

@@ -67,6 +67,12 @@ export declare function getAccessToken(): Promise<string | null>;
  * actual exp, or server-side revocation). Force a refresh and retry once.
  */
 export declare function forceRefreshAccessToken(): Promise<string | null>;
+/**
+ * True when auth.json holds a session whose access token has expired. After
+ * getAccessToken() returned null this means the refresh was rejected (or was
+ * impossible), so the remedy is `mnemom login`, not creating an account.
+ */
+export declare function hasExpiredStoredSession(): boolean;
 /**
  * Get a valid access token or exit with a helpful message.
  */

package/dist/lib/auth.js

@@ -15,11 +15,24 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { MNEMOM_DIR } from "./config.js";
-import { loginWithLoopback, loginWithDevice, refreshTokens as oauthRefreshTokens, } from "./oauth.js";
+import { loginWithLoopback, loginWithDevice, refreshTokens as oauthRefreshTokens, refreshWorstCaseMs, } from "./oauth.js";
 // ============================================================================
 // Auth Store (persisted to ~/.mnemom/auth.json)
 // ============================================================================
 const AUTH_FILE = path.join(MNEMOM_DIR, "auth.json");
+/**
+ * Held while one process refreshes the stored tokens (MNE-9232). The AS rotates
+ * refresh tokens, so two processes refreshing with the same one race: the first
+ * wins and the second gets invalid_grant. The lock serialises them, and the
+ * waiter re-reads auth.json under it and picks up the winner's tokens.
+ */
+const AUTH_LOCK_FILE = `${AUTH_FILE}.lock`;
+const AUTH_LOCK_POLL_MS = 100;
+/** A stored access token this close to expiry (seconds) is treated as expired. */
+const EXPIRY_BUFFER_S = 60;
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
 function loadAuthStore() {
     try {
         if (!fs.existsSync(AUTH_FILE))
@@ -112,9 +125,7 @@ export async function getAccessToken() {
     const auth = getAuthInfo();
     if (!auth)
         return null;
-    // Check expiry (with 60s buffer)
-    const now = Math.floor(Date.now() / 1000);
-    if (auth.expiresAt > now + 60) {
+    if (auth.expiresAt > nowSeconds() + EXPIRY_BUFFER_S) {
         return auth.accessToken;
     }
     // Auto-refresh. A *thrown* error from refreshStoredTokens() (transient
@@ -152,6 +163,15 @@ export async function forceRefreshAccessToken() {
     const refreshed = await refreshStoredTokens(auth);
     return refreshed?.accessToken ?? null;
 }
+/**
+ * True when auth.json holds a session whose access token has expired. After
+ * getAccessToken() returned null this means the refresh was rejected (or was
+ * impossible), so the remedy is `mnemom login`, not creating an account.
+ */
+export function hasExpiredStoredSession() {
+    const auth = getAuthInfo();
+    return auth !== null && auth.expiresAt <= nowSeconds() + EXPIRY_BUFFER_S;
+}
 /**
  * Get a valid access token or exit with a helpful message.
  */
@@ -232,11 +252,113 @@ export async function loginWithDeviceFlow() {
 // ============================================================================
 // Token refresh (OAuth refresh_token grant)
 // ============================================================================
+/** True when `pid` names a running process (EPERM: it runs as another user). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * A lock is stale when its holder has exited or it has been held longer than a
+ * refresh can take. Age and holder are read through one descriptor so both
+ * describe the same lock file. A lock that vanished first is not stale: the
+ * next create attempt decides.
+ */
+function authLockIsStale(staleMs) {
+    let mtimeMs;
+    let holder;
+    let fd;
+    try {
+        fd = fs.openSync(AUTH_LOCK_FILE, "r");
+    }
+    catch {
+        return false;
+    }
+    try {
+        mtimeMs = fs.fstatSync(fd).mtimeMs;
+        holder = fs.readFileSync(fd, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    if (Date.now() - mtimeMs >= staleMs)
+        return true;
+    const pid = Number(holder.trim());
+    return Number.isInteger(pid) && pid > 0 && !pidAlive(pid);
+}
+/**
+ * Take the refresh lock with O_EXCL (the update.lock pattern in
+ * lib/update/state.ts), waiting while another live process holds it. A stale
+ * lock is taken over. Waiting past the longest a refresh can take throws, which
+ * callers treat as a transient failure, never as revoked credentials.
+ *
+ * Two waiters can both judge one lock stale and both take it over. That only
+ * puts back the pre-lock race, which the invalid_grant re-read in
+ * refreshStoredTokens() still recovers from.
+ */
+async function acquireAuthLock() {
+    const staleMs = refreshWorstCaseMs();
+    const deadline = Date.now() + staleMs;
+    const owner = String(process.pid);
+    for (;;) {
+        try {
+            fs.mkdirSync(MNEMOM_DIR, { recursive: true, mode: 0o700 });
+            fs.writeFileSync(AUTH_LOCK_FILE, owner, { flag: "wx", mode: 0o600 });
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        if (authLockIsStale(staleMs)) {
+            fs.rmSync(AUTH_LOCK_FILE, { force: true });
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for another mnemom process to refresh the Mnemom session ` +
+                `(${AUTH_LOCK_FILE}). Re-run the command.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, AUTH_LOCK_POLL_MS));
+    }
+    return () => {
+        // Remove the lock only while it is still ours: if this process stalled past
+        // staleMs another process may have taken it over.
+        try {
+            if (fs.readFileSync(AUTH_LOCK_FILE, "utf-8") === owner) {
+                fs.rmSync(AUTH_LOCK_FILE, { force: true });
+            }
+        }
+        catch {
+            /* already gone */
+        }
+    };
+}
+/** True when `candidate` holds a different, unexpired access token than `seen`. */
+function isNewerSession(candidate, seen) {
+    return (candidate.accessToken !== seen.accessToken &&
+        candidate.expiresAt > nowSeconds() + EXPIRY_BUFFER_S);
+}
 /**
  * Refresh the stored tokens via the OAuth refresh_token grant. Requires both a
  * refresh token and the client_id they were issued to; returns null (rather
  * than throwing) when refresh isn't possible so callers degrade to re-login.
  *
+ * Runs under AUTH_LOCK_FILE and works from auth.json as it is once the lock is
+ * held, not from the caller's earlier read (MNE-9232):
+ *   - another process already refreshed (a different, unexpired access token
+ *     on disk) → return its tokens, no network call;
+ *   - the session was removed (`mnemom logout`) → null, never resurrected;
+ *   - invalid_grant/invalid_client → re-read once; if a writer that does not
+ *     take this lock (an older CLI) stored a different refresh token meanwhile,
+ *     use its session or refresh once with its refresh token.
+ *
  * Note: oauthRefreshTokens() returns null ONLY on a definitive revoke
  * (invalid_grant/invalid_client) or missing credentials; on transient
  * exhaustion (repeated 5xx / network faults) or any other non-revoke 4xx it
@@ -250,14 +372,39 @@ export async function loginWithDeviceFlow() {
 async function refreshStoredTokens(auth) {
     if (!auth.refreshToken || !auth.clientId)
         return null;
-    const refreshed = await oauthRefreshTokens(auth.refreshToken, auth.clientId);
-    if (!refreshed)
-        return null;
-    const stored = fromOAuthTokens(refreshed, auth.clientId);
-    // Preserve any legacy identity fields so whoami/status keep working across a
-    // refresh of a token set that still carries them.
-    stored.userId = auth.userId;
-    stored.email = auth.email;
-    saveAuthTokens(stored);
-    return stored;
+    const release = await acquireAuthLock();
+    try {
+        const current = getAuthInfo();
+        if (current && isNewerSession(current, auth))
+            return current;
+        if (!current?.refreshToken || !current.clientId)
+            return null;
+        let base = current;
+        let clientId = current.clientId;
+        let refreshed = await oauthRefreshTokens(current.refreshToken, current.clientId);
+        if (!refreshed) {
+            const latest = getAuthInfo();
+            if (!latest?.refreshToken || !latest.clientId)
+                return null;
+            if (latest.refreshToken === current.refreshToken)
+                return null;
+            if (isNewerSession(latest, current))
+                return latest;
+            base = latest;
+            clientId = latest.clientId;
+            refreshed = await oauthRefreshTokens(latest.refreshToken, latest.clientId);
+            if (!refreshed)
+                return null;
+        }
+        const stored = fromOAuthTokens(refreshed, clientId);
+        // Preserve any legacy identity fields so whoami/status keep working across a
+        // refresh of a token set that still carries them.
+        stored.userId = base.userId;
+        stored.email = base.email;
+        saveAuthTokens(stored);
+        return stored;
+    }
+    finally {
+        release();
+    }
 }

package/dist/lib/experimental.d.ts

@@ -12,7 +12,7 @@
  * Everything here is pure or dependency-injected; index.ts and the command
  * modules are the thin drivers.
  */
-export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "measured-savings" | "record" | "fuel" | "durable";
+export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "measured-savings" | "record" | "fuel" | "durable" | "dispatch";
 /**
  * Features that used to be experimental and are now on by default for everyone. Their ids are
  * no longer in the registry, but `mnemom experimental enable|disable <id>` still accepts them

package/dist/lib/experimental.js

@@ -120,6 +120,19 @@ export const EXPERIMENTAL_FEATURES = [
             env: [],
         },
     },
+    {
+        // The thin runner (Doors W-L13, ruling 34.12 (4)). Off: `agent run` exits 2 with the gate
+        // pointer before reading any credential.
+        id: "dispatch",
+        summary: "The thin runner: `mnemom agent run --watch|--once` claims served-phase jobs and runs them",
+        since: "0.17.32",
+        gates: {
+            flags: [],
+            configKeys: [],
+            commands: ["mnemom agent run"],
+            env: [],
+        },
+    },
 ];
 export const EXPERIMENTAL_IDS = EXPERIMENTAL_FEATURES.map((f) => f.id);
 export const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";

package/dist/lib/oauth.d.ts

@@ -26,6 +26,13 @@
  * positive integer (capped at 5 min), else the default.
  */
 export declare function oauthHttpTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * The longest one refreshTokens() call can legitimately take (ms): discovery
+ * plus REFRESH_MAX_ATTEMPTS token requests, each at the per-request deadline,
+ * plus the backoff sleeps between attempts. lib/auth.ts uses it to bound how
+ * long a process waits on another process's refresh lock (MNE-9232).
+ */
+export declare function refreshWorstCaseMs(env?: NodeJS.ProcessEnv): number;
 /** The name carried by an error thrown when an AS round-trip hit its deadline. */
 export declare const OAUTH_TIMEOUT_ERROR = "OAuthTimeoutError";
 export interface AuthServerMetadata {

package/dist/lib/oauth.js

@@ -86,6 +86,19 @@ export function oauthHttpTimeoutMs(env = process.env) {
     }
     return OAUTH_HTTP_TIMEOUT_MS;
 }
+/**
+ * The longest one refreshTokens() call can legitimately take (ms): discovery
+ * plus REFRESH_MAX_ATTEMPTS token requests, each at the per-request deadline,
+ * plus the backoff sleeps between attempts. lib/auth.ts uses it to bound how
+ * long a process waits on another process's refresh lock (MNE-9232).
+ */
+export function refreshWorstCaseMs(env = process.env) {
+    let backoff = 0;
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS - 1; attempt++) {
+        backoff += REFRESH_BACKOFF_BASE_MS * 2 ** attempt;
+    }
+    return oauthHttpTimeoutMs(env) * (1 + REFRESH_MAX_ATTEMPTS) + backoff;
+}
 /** The name carried by an error thrown when an AS round-trip hit its deadline. */
 export const OAUTH_TIMEOUT_ERROR = "OAuthTimeoutError";
 function isTimeout(err) {