@mnemom/mnemom 0.17.32 → 0.17.34-next.1

package/dist/commands/scan.js

@@ -0,0 +1,238 @@
+/**
+ * `mnemom scan`: a read-only local scan of GitHub PR metadata. Runs entirely on this machine; nothing is
+ * uploaded in this build. The share-level prompt gates what a later upload step may send, and the chosen
+ * payload is printed so the user sees exactly what would leave. Pure logic is exported so each reject
+ * arm is unit-testable without Commander (same pattern as commands/usage.ts).
+ */
+import { isValidRepoSlug, resolveCredential, } from "../lib/scan/credential.js";
+import { failureText } from "../lib/scan/failure.js";
+import { runLocalScan } from "../lib/scan/scan.js";
+import { askInput, askSelect } from "../lib/prompt.js";
+import { isSpendTiersEnabled, NOT_ENABLED_MSG, parseMonthlySpendUsd, selectSpend, SPEND_INVALID_MSG, SPEND_NO_TERMINAL_MSG, } from "../lib/scan/spend/spend-tiers.js";
+import { ADMIN_KEY_ENV, AnthropicUsageError, fetchMeasuredUsage, isAdminKeyShape, usageFailureText, } from "../lib/scan/spend/anthropic-usage.js";
+import { getAuthInfo } from "../lib/auth.js";
+import { listMyOrgs } from "../lib/api.js";
+import { fetchRecordTotals, isOrgId, } from "../lib/scan/record.js";
+import { RECORD_NO_ORG_NOTE, renderRecordSection } from "../lib/scan/report.js";
+import { buildEmailBody, buildEmailReport, DRY_RUN_MSG, UNAVAILABLE_MSG, failureMessage, ReportEmailError, sendReportEmail, } from "../lib/scan/report-email.js";
+import { buildSharePayload, parseShareLevel, promptShareLevel, } from "../lib/scan/share.js";
+/** Parses repeated/comma-separated `--repo owner/name`. Returns null on any invalid slug. */
+export function parseRepoFlags(raw) {
+    const out = (raw ?? [])
+        .flatMap((r) => r.split(","))
+        .map((r) => r.trim())
+        .filter(Boolean);
+    return out.length > 0 && out.every(isValidRepoSlug) ? out : null;
+}
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,255}\.[^\s@]{2,63}$/;
+export const isEmail = (v) => typeof v === "string" && v.length <= 320 && EMAIL.test(v.trim());
+/** The runner's email (mnemom login, else asked) and the CTO's (flag, else "are you the CTO?"). */
+export async function resolveRecipients(o) {
+    if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
+        throw new Error("--cto-email must be a valid email address");
+    let runner = o.runnerEmail ?? getAuthInfo()?.email ?? "";
+    if (!isEmail(runner))
+        runner = (await askInput("Your email (the report is sent to you):")).trim();
+    if (!isEmail(runner))
+        throw new Error("a valid runner email is required");
+    runner = runner.trim();
+    if (o.ctoEmail !== undefined)
+        return { runner_email: runner, cto_email: o.ctoEmail.trim() };
+    const isCto = await askSelect("Are you the CTO?", ["Yes, I am the CTO", "No, someone else is"]);
+    if (isCto === null)
+        throw new Error("--cto-email is required when you are not the CTO");
+    if (isCto.startsWith("Yes"))
+        return { runner_email: runner, cto_email: runner };
+    const cto = (await askInput("CTO email (the report is sent to them too):")).trim();
+    if (!isEmail(cto))
+        throw new Error("--cto-email is required when you are not the CTO");
+    return { runner_email: runner, cto_email: cto };
+}
+/** The CTO's figure in USD, or null for none. Throws fixed text only; the input is never echoed. */
+export async function resolveSelfReportedSpend(o) {
+    if (o.monthlySpend === undefined && !o.noAnthropicUsage)
+        return null;
+    if (!isSpendTiersEnabled(o.env))
+        throw new Error(NOT_ENABLED_MSG);
+    let text = o.monthlySpend;
+    if (text === undefined) {
+        if (!(o.isTty ?? process.stdin.isTTY))
+            throw new Error(SPEND_NO_TERMINAL_MSG);
+        text = await askInput("Approximate monthly AI spend in USD (blank to skip; kept in memory only):");
+        if (text.trim() === "")
+            return null;
+    }
+    const n = parseMonthlySpendUsd(text);
+    if (n === null)
+        throw new Error(SPEND_INVALID_MSG);
+    return n;
+}
+export const NO_ADMIN_KEY_TERMINAL_MSG = "Set ANTHROPIC_ADMIN_KEY (there is no terminal to ask on).";
+export const TIER1_FALLBACK_NOTE = "Tier 1 skipped: falling back to the next tier.";
+/**
+ * Tier 1: read measured usage with the CTO's Anthropic admin key, locally. The key comes from
+ * ANTHROPIC_ADMIN_KEY or a masked prompt (--anthropic-admin-key; never a value on argv), lives only in this
+ * call, and goes only to api.anthropic.com. Returns null for "no key" and for every failure, after printing a
+ * fixed sentence: the key, the thrown value and the response never reach the terminal. The caller then falls
+ * back to tier 2, then tier 3.
+ */
+export async function resolveMeasuredUsage(o, period) {
+    if (o.anthropicAdminKey && !isSpendTiersEnabled(o.env))
+        throw new Error(NOT_ENABLED_MSG);
+    if (!isSpendTiersEnabled(o.env) || o.noAnthropicUsage)
+        return null;
+    // An explicit typed figure is the user's choice of tier 2: an ambient env key must not override it.
+    if (o.monthlySpend !== undefined && !o.anthropicAdminKey)
+        return null;
+    let key = (o.env ?? process.env)[ADMIN_KEY_ENV];
+    if (o.anthropicAdminKey) {
+        if (!(o.isTty ?? process.stdin.isTTY))
+            throw new Error(NO_ADMIN_KEY_TERMINAL_MSG);
+        key = await askInput("Anthropic admin key (kept in memory only, sent only to Anthropic):", true);
+    }
+    if (key === undefined || key.trim() === "")
+        return null;
+    if (!isAdminKeyShape(key)) {
+        console.log(usageFailureText("key_invalid"));
+        console.log(TIER1_FALLBACK_NOTE);
+        return null;
+    }
+    try {
+        return await fetchMeasuredUsage(key, period, o.anthropicDeps);
+    }
+    catch (e) {
+        console.log(usageFailureText(e instanceof AnthropicUsageError ? e.reason : "upstream"));
+        console.log(TIER1_FALLBACK_NOTE);
+        return null;
+    }
+}
+/**
+ * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
+ * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
+ * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
+ * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ */
+export async function resolveScanOrg(o) {
+    if (o.org !== undefined) {
+        if (!isOrgId(o.org))
+            throw new Error(INVALID_ORG_MSG);
+        return o.org;
+    }
+    let orgs;
+    try {
+        orgs = (await (o.listOrgs ?? listMyOrgs)()).filter((x) => !x.is_personal);
+    }
+    catch {
+        throw new Error("Could not look up your org to email the report to. Sign in with `mnemom login`, or pass --org <org_id>.");
+    }
+    if (orgs.length === 1 && isOrgId(orgs[0].org_id))
+        return orgs[0].org_id;
+    if (orgs.length === 0)
+        throw new Error("You belong to no organization, so the report has nowhere to be emailed from. Pass --org <org_id>.");
+    throw new Error(`You belong to ${orgs.length} organizations; pass --org <org_id> (${orgs.map((x) => x.org_id).join(", ")}).`);
+}
+export const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";
+/**
+ * The Record read for the preview: null when the flag gate is off (no read, no output, as before).
+ * With the gate on and no --org it is a note, not a guess. 404 becomes a note; 401/403 throw
+ * RecordAuthError (fail closed); every other failure becomes a fixed note. Nothing is stored.
+ */
+export async function resolveRecordOutcome(o) {
+    if (!isSpendTiersEnabled(o.env))
+        return null;
+    if (o.org === undefined)
+        return "no_org";
+    if (!isOrgId(o.org))
+        throw new Error(INVALID_ORG_MSG);
+    return fetchRecordTotals(o.org, o.recordDeps);
+}
+export async function scanCommand(o) {
+    if (o.share !== undefined && parseShareLevel(o.share) === null) {
+        throw new Error("--share must be one of: summary, full, none");
+    }
+    if (o.repos.length === 0)
+        throw new Error("--repo owner/name is required (repeatable)");
+    // The report is emailed on every scan, so resolve the org before any scan work; failure is loud.
+    const emailOrg = await resolveScanOrg(o);
+    if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
+        throw new Error("--cto-email must be a valid email address");
+    const selfReported = await resolveSelfReportedSpend(o);
+    const now = o.now ?? Date.now;
+    const end = new Date(now()).toISOString().slice(0, 10);
+    const period = o.period ?? { start: end, end };
+    const measured = await resolveMeasuredUsage(o, period);
+    const credential = o.credential ?? (await resolveCredential().catch(() => null));
+    if (!credential)
+        throw new Error(failureText("credential"));
+    // Before the local scan: a refused credential fails closed without spending the GitHub reads.
+    const record = await resolveRecordOutcome(o);
+    const outcome = await runLocalScan({ credential, now, ...o.deps }, { repos: o.repos, period });
+    if (outcome.status === "withheld")
+        throw new Error(`Scan withheld: ${failureText(outcome.reason)}`);
+    const { result } = outcome;
+    console.log("Local scan (read-only)");
+    console.log(`PRs examined: ${result.totals.examined} of ${result.totals.prs} merged (${result.coverage.windowStart} to ${result.coverage.windowEnd})`);
+    console.log(`Coverage: ${result.coverage.complete ? "complete" : `partial${result.coverage.stoppedBy ? ` (stopped by ${result.coverage.stoppedBy})` : ""}`}`);
+    // Flag off: the line as before. Flag on: the tier chosen, or no line at all when evidence is thin.
+    const tiers = isSpendTiersEnabled(o.env);
+    const spend = tiers
+        ? selectSpend({
+            measuredUsd: measured?.usd ?? o.anthropicUsageUsd,
+            over200kShare: measured ? measured.over200kShare : o.anthropicOver200kShare,
+            selfReportedUsd: selfReported,
+            estimate: result.spend,
+        })
+        : null;
+    const spendLine = spend ? spend.line : result.spend.line;
+    if (spendLine !== null)
+        console.log(spendLine);
+    if (record === "no_org")
+        console.log(RECORD_NO_ORG_NOTE);
+    else if (record !== null)
+        for (const line of renderRecordSection(record))
+            console.log(line);
+    const level = parseShareLevel(o.share) ?? (await promptShareLevel());
+    // Every successful scan emails the report to the person who ran it, at every share level, no opt-out.
+    // Mnemom keeps nothing from a share=none send (the server sends the email and does nothing else).
+    const emailFailure = await emailReport(o, emailOrg, result, level, period, spend);
+    if (level === "none") {
+        console.log("Share level: nothing. No share payload is built; Mnemom keeps nothing (the report email is only sent to you).");
+        if (emailFailure)
+            throw new ReportEmailError(emailFailure);
+        return;
+    }
+    const payload = buildSharePayload(level, result, await resolveRecipients(o), spend ? (spend.shareable ? spend.line : null) : undefined);
+    console.log(`Share level: ${level}. Upload is not wired in this build; this is what would be sent:`);
+    console.log(JSON.stringify(payload, null, 2));
+    if (emailFailure)
+        throw new ReportEmailError(emailFailure);
+}
+/**
+ * Emails the report. Loud on every failure: prints the reason name, never the server's words, and
+ * returns it so the caller exits non-zero after the local report is shown.
+ */
+async function emailReport(o, org, result, level, period, spend) {
+    const fail = (f) => {
+        console.log(failureMessage(f));
+        return f;
+    };
+    const report = buildEmailReport(result, {
+        orgId: org,
+        period,
+        now: o.now ?? Date.now,
+        sendSpendRange: spend ? spend.shareable && spend.tier === 3 : true,
+    });
+    const body = buildEmailBody(report, level, result.coverage.complete, o.ctoEmail?.trim());
+    const outcome = await sendReportEmail(org, body, o.emailDeps);
+    if (outcome.status === "failed")
+        return fail(outcome.reason);
+    if (outcome.status === "unavailable") {
+        // Org Scan is off by default: the gate's 404 is not a failure and must not break the scan.
+        console.log(UNAVAILABLE_MSG);
+        return null;
+    }
+    console.log(outcome.status === "dry_run"
+        ? DRY_RUN_MSG
+        : `Report emailed to you (${outcome.recipients} recipient${outcome.recipients === 1 ? "" : "s"}).`);
+    return null;
+}

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";
@@ -48,6 +49,7 @@ import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
 import { usageCommand, parseNumericFlag, parseDaysFlag } from "./commands/usage.js";
+import { scanCommand, parseRepoFlags } from "./commands/scan.js";
 import { updateCommand } from "./commands/update.js";
 import { runAction } from "./lib/update/action.js";
 import { configListCommand, configGetCommand, configSetCommand, configUnsetCommand, } from "./commands/config.js";
@@ -339,6 +341,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 +923,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 +1024,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
@@ -2176,6 +2197,40 @@ program
         process.exit(1);
     }
 });
+program
+    .command("scan")
+    .description("Read-only local scan of GitHub PR metadata; the report is emailed to you every time (counts only, no repo names) and Mnemom keeps nothing at share level none")
+    .option("--repo <owner/name...>", "Repo to scan (repeatable or comma-separated)")
+    .option("--start <YYYY-MM-DD>", "Period start (default: today)")
+    .option("--end <YYYY-MM-DD>", "Period end (default: today)")
+    .option("--share <level>", "summary | full | none (default: ask)")
+    .option("--cto-email <email>", "CTO who receives the report (required unless you are the CTO; asked when omitted)")
+    .option("--monthly-spend <usd>", "Your own approximate monthly AI spend (self-reported; never sent or saved; needs MNEMOM_ORG_SCAN_MODE=true)")
+    .option("--anthropic-admin-key", "Ask (masked) for your Anthropic admin key and read measured usage with it, locally; or set ANTHROPIC_ADMIN_KEY. Never stored, logged or sent anywhere but api.anthropic.com (needs MNEMOM_ORG_SCAN_MODE=true)")
+    .option("--no-anthropic-usage", "Decline Anthropic usage and be asked for a monthly figure (needs MNEMOM_ORG_SCAN_MODE=true)")
+    .option("--org <org_id>", "Your org id; the report is emailed to you for this org (default: your only organization, else the scan stops and asks). Also selects the Record totals preview (needs MNEMOM_ORG_SCAN_MODE=true)")
+    .action(async (options) => {
+    try {
+        const repos = parseRepoFlags(options.repo);
+        if (!repos)
+            throw new Error("--repo owner/name is required (repeatable)");
+        const today = new Date().toISOString().slice(0, 10);
+        await scanCommand({
+            repos,
+            period: { start: options.start ?? options.end ?? today, end: options.end ?? today },
+            share: options.share,
+            ctoEmail: options.ctoEmail,
+            monthlySpend: options.monthlySpend,
+            noAnthropicUsage: options.anthropicUsage === false,
+            anthropicAdminKey: options.anthropicAdminKey === true,
+            org: options.org,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : "scan failed");
+        process.exit(1);
+    }
+});
 // ============================================================================
 // update + config — CLI auto-update (channel latest|next, mode auto|notify|off)
 //

package/dist/lib/api.d.ts

@@ -450,6 +450,19 @@ export interface RecordTotals {
     row_count: number;
 }
 export declare function getRecordTotals(orgId: string, lineageKey: string, signal?: AbortSignal): Promise<RecordTotals>;
+/** The window form of the totals read (contract i2-totals-window v1.2), the fields the scan preview uses. */
+export interface RecordWindowTotals {
+    model_cost_mmu: string;
+    mu_charged_mmu: string | null;
+    row_count: number;
+    as_of: string | null;
+}
+/**
+ * GET /v1/orgs/{org_id}/record/totals?from=&to= — the org's total over a window (at most 30 days,
+ * `to` not in the future). Returns the raw body: the caller shape-checks it. A 404 means the org is
+ * not in the Record cohort.
+ */
+export declare function getRecordWindowTotals(orgId: string, from: string, to: string, signal?: AbortSignal): Promise<unknown>;
 /**
  * Report one commit to Record's commit index (Doors W1.8, lib/commit-report.ts):
  * `POST /v1/orgs/{org}/record/commits`, body RecordCommit/v1. Returns the HTTP

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
@@ -411,6 +427,14 @@ export async function getMe() {
 export async function getRecordTotals(orgId, lineageKey, signal) {
     return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/record/totals?lineage_key=${encodeURIComponent(lineageKey)}`, signal ? { signal } : {}, { notFoundLabel: "Record totals", fallback: "Could not read record totals" });
 }
+/**
+ * GET /v1/orgs/{org_id}/record/totals?from=&to= — the org's total over a window (at most 30 days,
+ * `to` not in the future). Returns the raw body: the caller shape-checks it. A 404 means the org is
+ * not in the Record cohort.
+ */
+export async function getRecordWindowTotals(orgId, from, to, signal) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/record/totals?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`, signal ? { signal } : {}, { notFoundLabel: "Record totals", fallback: "Could not read record totals" });
+}
 /**
  * Report one commit to Record's commit index (Doors W1.8, lib/commit-report.ts):
  * `POST /v1/orgs/{org}/record/commits`, body RecordCommit/v1. Returns the HTTP

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";