@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/codeAgent/tools/AkanEnvKeys.ts

@@ -2,23 +2,15 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
-/**
- * Loads provider keys from the workspace's `.env` into the session, without persisting them anywhere.
- *
- * Bun auto-loads `.env` from the **current directory**, so `akan code` run from a subdirectory — or embedded in
- * a process started elsewhere — sees none of the workspace's keys and fails with "No API key found" for a key
- * that is plainly there. They are applied as runtime overrides rather than stored credentials: the key belongs
- * to the repo's env file, and copying it into `~/.akan/code/auth.json` would give it a second lifetime nobody
- * asked for.
- */
+// Bun auto-loads .env from the current directory only, so a run from a subdirectory sees none of the workspace's keys.
+// Applied as runtime overrides, never stored: copying a key into ~/.akan/code/auth.json gives it a second lifetime.
 export class AkanEnvKeys {
   static async apply(runtime: ModelRuntime, workspaceRoot: string) {
     const applied: string[] = [];
     for (const [name, value] of AkanEnvKeys.#entries(workspaceRoot)) {
       const provider = AkanEnvKeys.#providerOf(name);
       if (!provider || !value) continue;
-      // Serially, not through `Promise.all`: the runtime queues credential operations against the same file,
-      // and a key written while another is mid-write is the one that goes missing.
+      // Serially: the runtime's credential writes share one file, and a key written mid-write goes missing.
       await runtime.setRuntimeApiKey(provider, value);
       applied.push(provider);
     }

package/codeAgent/tools/AkanToolPack.ts

@@ -11,13 +11,7 @@ export interface AkanToolPackOptions {
   mode: "readonly" | "plan" | "apply";
 }
 
-/**
- * Publishes the workspace's own agent tools — context inspection, workflows, repair, validation — to the model.
- *
- * These already exist as the akan MCP catalogue, dispatched in-process by `ContextRunner.callMcpTool`. Wrapping
- * that dispatcher is the whole implementation: a second copy of "what does add-field do" would drift from the
- * one the editors already talk to.
- */
+// Wraps the akan MCP catalogue's in-process dispatcher (ContextRunner.callMcpTool); a second copy would drift from it.
 export class AkanToolPack {
   readonly #options: AkanToolPackOptions;
 
@@ -29,18 +23,8 @@ export class AkanToolPack {
     return { name: "akan-tools", factory: async (pi) => await this.#register(pi) };
   }
 
-  /**
-   * The names this pack will register.
-   *
-   * A `tools` allowlist on the session is an allowlist over *every* tool, extension ones included — pass only
-   * the built-ins and the model is told the akan tools do not exist, which is exactly what it then reports.
-   */
-  /**
-   * The CLI's own MCP catalogue is what these tools are, so this pack is the one place devkit reaches back
-   * into the executable package. `ContextRunner` composes the repair and workflow runners and cannot move
-   * here; the path is written out because devkit does not depend on the CLI and must not start. Both packages
-   * are bundled into one at publish, so the specifier resolves at build time either way.
-   */
+  // The session allowlist covers extension tools too; a name missing here tells the model the tool does not exist.
+  // devkit must not depend on the CLI, so ContextRunner is reached by relative path; publishing bundles both.
   async names() {
     const { ContextRunner } = await import("../../../cli/context/context.runner");
     return [
@@ -61,15 +45,15 @@ export class AkanToolPack {
         name: tool.name,
         label: tool.name,
         description,
-        // Without a snippet a custom tool is left out of the system prompt's tool list entirely, and a model
-        // whose built-ins are narrowed then reads "Available tools: (none)" and stops trusting the list.
+        // Without a snippet the engine leaves a custom tool out of the system prompt's tool list entirely.
         promptSnippet: `${tool.name}: ${description.split(".")[0] ?? description}`,
         parameters: Type.Unsafe<Record<string, unknown>>(tool.inputSchema),
         execute: async (_id, params) => {
           const result = await runner.callMcpTool(this.#options.workspace, tool.name, params ?? {}, {
             mode: this.#options.mode,
           });
-          return { content: [{ type: "text", text: AkanToolPack.#render(result) }], details: undefined };
+          const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+          return { content: [{ type: "text", text }], details: undefined };
         },
       });
     }
@@ -97,7 +81,6 @@ export class AkanToolPack {
     });
   }
 
-  /** The guideline list is a directory read, so a model cannot name one without being handed the enum. */
   static async #guidelineNames() {
     try {
       const { Prompter } = await import("../../prompter");
@@ -106,9 +89,4 @@ export class AkanToolPack {
       return [];
     }
   }
-
-  static #render(result: unknown) {
-    if (typeof result === "string") return result;
-    return JSON.stringify(result, null, 2);
-  }
 }

package/codeAgent/tools/AkanVerifier.ts

@@ -7,14 +7,6 @@ export interface AkanVerifyReport {
   scope: AkanEditScopeResult;
 }
 
-/**
- * Runs the workspace's own validation chain over whatever a turn changed.
- *
- * The order is the one the guide names and it is not interchangeable: `sync` first because a stale generated
- * barrel makes `typecheck` report a missing symbol whose real cause is a file that was added, which sends the
- * model editing the wrong place. `lint` before `typecheck` because it rewrites formatting and import order,
- * and a typecheck run against the pre-format text reports positions that no longer exist.
- */
 export class AkanVerifier {
   readonly #cli: AkanCli;
 
@@ -25,6 +17,7 @@ export class AkanVerifier {
   async verify(scope: AkanEditScopeResult): Promise<AkanVerifyReport> {
     const steps: AkanCliResult[] = [];
     const targets = [...scope.apps, ...scope.libs];
+    // Order matters: a stale barrel reads to typecheck as a missing symbol, and lint moves the positions it reports.
     if (scope.needsSync) for (const target of targets) steps.push(await this.#cli.run(["sync", target]));
     for (const target of targets) steps.push(await this.#cli.run(["lint", target]));
     for (const app of scope.apps) steps.push(await this.#cli.run(["typecheck", app]));

package/codeAgent/tools/AskToolPack.ts

@@ -8,17 +8,7 @@ export interface AskToolPackOptions {
   ask: (question: Omit<CodeAgentQuestion, "questionId">) => Promise<string | undefined>;
 }
 
-/**
- * The `ask_user` tool: put a decision back to the person instead of guessing at it.
- *
- * It exists only where somebody is watching. A pod and a sub-agent both set `ui.canPrompt` false, and on those
- * the tool is never constructed — a model that cannot see it does not spend a turn calling something that can
- * only answer "nobody is here", and it costs no prompt tokens either.
- *
- * **Questions are asked one at a time even when several are sent.** The host draws one question block at the
- * bottom of the screen, and an answer is frequently what decides whether the next question is still the right
- * one to ask; a batch drawn at once would also have nowhere to put the second prompt.
- */
+// One question at a time even when several are sent: the host draws one block, and an answer can change the next.
 export class AskToolPack {
   static readonly toolName = "ask_user";
   /** Four is what fits on a screen without the transcript disappearing behind the questions. */
@@ -96,12 +86,10 @@ export class AskToolPack {
             kind: options.length ? "select" : "text",
             ...(options.length ? { options } : {}),
             ...(entry.multiSelect ? { multiSelect: true } : {}),
-            // On by default: a list the model wrote is a guess at what the choices are, and the person is the
-            // one who knows when none of them is the answer.
+            // On by default: the model's options are a guess, and only the person knows when none of them fits.
             freeText: entry.freeText ?? true,
           });
-          // Said as a skip rather than left blank: an unanswered question read as an empty answer is how a
-          // model concludes the user wanted nothing, which is the one reading they did not choose.
+          // Spelled out as a skip: a blank answer reads to a model as "the user wanted nothing".
           answers.push(`${entry.question}\n→ ${answer ?? "(skipped — decide this yourself and say what you chose)"}`);
         }
         return { content: [{ type: "text", text: answers.join("\n\n") }], details: undefined };

package/codeAgent/tools/MailToolPack.ts

@@ -9,15 +9,6 @@ export interface MailToolPackOptions {
   mailbox: () => CodeMailbox | undefined;
 }
 
-/**
- * Lets the agent reach the other `akan code` sessions running in this workspace.
- *
- * The person can already do it with `/peers` and `/msg`; this is the half that makes it *coordination* — one
- * session asking another to take a piece of the work, or telling it the file they both touch has moved.
- *
- * A message arrives at the other end as a prompt, so the tool's cost is a whole turn of somebody else's
- * window. That is why the description says what it says: it is for handing over work, not for chatting.
- */
 export class MailToolPack {
   static readonly toolNames = ["list_peers", "send_peer_message"];
 

package/codeAgent/tools/McpClient.ts

@@ -14,12 +14,7 @@ interface JsonRpcResponse {
 
 const protocolVersion = "2025-06-18";
 
-/**
- * A server that answered correctly and asked who is calling.
- *
- * Its own class because the caller has to tell it apart from every other connect failure: this one is fixed by
- * signing in, and reporting it as "unavailable" sends someone to debug a server that is working.
- */
+// Its own class: a 401 is fixed by signing in, and calling it "unavailable" sends someone to debug a working server.
 export class McpUnauthorized extends Error {
   /** The `WWW-Authenticate` value, which names the resource metadata discovery starts from. */
   readonly challenge: string;
@@ -31,13 +26,6 @@ export class McpUnauthorized extends Error {
   }
 }
 
-/**
- * A client for one MCP server, over stdio or streamable HTTP.
- *
- * **Every failure is non-fatal.** A server that will not start, answers nothing, or dies mid-session costs its
- * own tools and nothing else: an agent that cannot finish a turn because an unrelated integration is down is
- * worse than one with fewer tools.
- */
 export class McpClient {
   /** A ceiling on a server that never stops paging; 50 pages is 5,000 tools at the usual page size. */
   static readonly maxToolPages = 50;
@@ -67,14 +55,7 @@ export class McpClient {
     return this;
   }
 
-  /**
-   * Every page of the server's tool list, not the first one.
-   *
-   * `tools/list` is paginated: a server holding more tools than its page size answers a `nextCursor` and
-   * expects to be asked again. Reading one page looks like it worked — the tools are sorted, so what goes
-   * missing is the tail of the alphabet rather than anything a caller would notice as absent. An akan server
-   * pages at 100 by default (`option.setMcp({ pageSize })`), so any app past 100 endpoints hit this.
-   */
+  /** Every page: `tools/list` pages by `nextCursor` (an akan server at 100), and one page silently drops the tail. */
   async listTools(): Promise<McpToolInfo[]> {
     const tools: McpToolInfo[] = [];
     let cursor: string | undefined;
@@ -108,7 +89,6 @@ export class McpClient {
     this.#proc = Bun.spawn([this.ref.command, ...(this.ref.args ?? [])], {
       stdin: "pipe",
       stdout: "pipe",
-      // A server's diagnostics belong in its own stderr, never mixed into the JSON-RPC stream.
       stderr: "ignore",
       env: { ...process.env, ...this.ref.env },
     });
@@ -177,8 +157,7 @@ export class McpClient {
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(30_000),
     });
-    // Raised rather than returned as a JSON-RPC error: a 401 carries no body worth reading, and the whole of
-    // what the caller needs is in the header that came with it.
+    // Thrown, not returned as a JSON-RPC error: a 401's body says nothing, and the caller needs its header.
     if (response.status === 401)
       throw new McpUnauthorized(this.ref.name, response.headers.get("www-authenticate") ?? "");
     this.#sessionId = response.headers.get("mcp-session-id") ?? this.#sessionId;

package/codeAgent/tools/McpOAuth.ts

@@ -30,30 +30,13 @@ interface TokenResponse {
   error_description?: string;
 }
 
-/**
- * The client half of the MCP authorization spec: discovery, registration, and the authorization code flow.
- *
- * Every step is discovered rather than configured. A `401` names the resource metadata, that names the
- * authorization server, and its RFC 8414 document names the endpoints — so connecting to a server nobody has
- * described here needs no entry beyond its url. `pkgs/akanjs/server/mcp/McpAuth.ts` is the other half of the
- * same contract, and an akan app is therefore a server this can sign in to with nothing declared at all.
- *
- * **PKCE is mandatory and `S256` is the only method.** OAuth 2.1 drops `plain`, and the spec requires a client
- * to refuse a server whose metadata does not offer `S256` rather than fall back — a downgrade a network
- * attacker would otherwise choose on the client's behalf.
- */
+// Every endpoint is discovered from the 401 challenge; `pkgs/akanjs/server/mcp/McpAuth.ts` is the server half.
 export class McpOAuth {
   /** RFC 9728. A client tries the path-inserted spelling first and the bare one second. */
   static readonly resourceWellKnown = "/.well-known/oauth-protected-resource";
   static readonly serverWellKnown = "/.well-known/oauth-authorization-server";
   static readonly openidWellKnown = "/.well-known/openid-configuration";
-  /**
-   * Loopback ports tried in order, and why there is a fixed list rather than an ephemeral port.
-   *
-   * A registered client is bound to the exact `redirect_uri` it was registered with, so a port chosen afresh
-   * every time would invalidate the registration on every sign-in. The port that was used is stored with the
-   * client; this list is only what a first sign-in reaches for.
-   */
+  /** A fixed list, not an ephemeral port: a registered client is bound to its exact `redirect_uri`. */
   static readonly ports = [33418, 33419, 33420, 33421, 33422];
   static readonly callbackPath = "/callback";
   /** How long the browser half may take before the loopback server gives the port back. */
@@ -63,12 +46,7 @@ export class McpOAuth {
     return response.json() as Promise<Record<string, unknown>>;
   }
 
-  /**
-   * The `resource_metadata` a `WWW-Authenticate` challenge points at.
-   *
-   * Taken from the header when it is there rather than derived, because a resource served under a path has
-   * its path inserted into the well-known url and only the server knows which spelling it published.
-   */
+  /** The challenge's `resource_metadata` wins over derived urls: only the server knows which spelling it published. */
   static resourceMetadataUrls(serverUrl: string, challenge?: string | null) {
     const named = challenge ? /resource_metadata="([^"]+)"/.exec(challenge)?.[1] : undefined;
     if (named) return [named];
@@ -91,12 +69,7 @@ export class McpOAuth {
     ];
   }
 
-  /**
-   * Everything needed to run the flow, from the server url and whatever its `401` said.
-   *
-   * A resource that publishes no metadata is not refused: plenty of servers implement the token half of the
-   * spec and not the discovery half, and for those the server's own origin is the issuer to try.
-   */
+  /** A resource with no metadata falls back to its own origin as issuer: many servers skip the discovery half. */
   static async discover(serverUrl: string, challenge?: string | null): Promise<McpOAuthServer> {
     const resourceDoc = await McpOAuth.#first(McpOAuth.resourceMetadataUrls(serverUrl, challenge));
     const resource = typeof resourceDoc?.resource === "string" ? resourceDoc.resource : serverUrl;
@@ -107,8 +80,7 @@ export class McpOAuth {
       const doc = await McpOAuth.#first(McpOAuth.serverMetadataUrls(issuer));
       if (!doc) continue;
       const methods = McpOAuth.#strings(doc.code_challenge_methods_supported);
-      // The spec says refuse rather than downgrade: a metadata document that omits S256 is either a server
-      // too old for OAuth 2.1 or one a network attacker rewrote, and both answers are "do not send a code".
+      // Refuse rather than downgrade (OAuth 2.1): a document without S256 is too old or rewritten by an attacker.
       if (methods.length && !methods.includes("S256"))
         throw new Error(`${issuer} does not offer PKCE S256, which is the only method this client will use.`);
       const authorizationEndpoint = typeof doc.authorization_endpoint === "string" ? doc.authorization_endpoint : "";
@@ -155,13 +127,6 @@ export class McpOAuth {
     return { clientId: body.client_id, ...(body.client_secret ? { clientSecret: body.client_secret } : {}) };
   }
 
-  /**
-   * The authorization code flow, start to finish, against a loopback redirect.
-   *
-   * The browser is opened by the caller: this module has no opinion about how a host reaches one, and a pod
-   * has no browser at all. `state` is checked on the way back, and `iss` too whenever the server sends it —
-   * without that check a response from one authorization server can be replayed at another.
-   */
   static async authorize(options: {
     server: McpOAuthServer;
     clientId: string;
@@ -195,6 +160,7 @@ export class McpOAuth {
     if (error) throw new Error(`${error}: ${params.get("error_description") ?? "the authorization was refused"}`);
     if (params.get("state") !== state) throw new Error("The authorization response carried the wrong state.");
     const iss = params.get("iss");
+    // Without the iss check a response from one authorization server can be replayed at another.
     if (iss && iss !== options.server.issuer)
       throw new Error(`The authorization response came from ${iss}, not ${options.server.issuer}.`);
     const code = params.get("code");
@@ -245,7 +211,6 @@ export class McpOAuth {
     };
   }
 
-  /** The first url that answers a JSON document; a 404 on one spelling is the normal case, not a failure. */
   static async #first(urls: string[]) {
     for (const url of urls) {
       try {

package/codeAgent/tools/McpOAuthLoopback.ts

@@ -1,12 +1,5 @@
 import { McpOAuth } from "./McpOAuth";
 
-/**
- * The loopback address the authorization server redirects back to.
- *
- * A native client has no url of its own, so the redirect goes to a server this process runs for the length of
- * one sign-in. It binds `127.0.0.1` rather than `0.0.0.0`: the code in that redirect is a credential, and a
- * port open to the network is a port anything on the network can race the browser to.
- */
 export class McpOAuthLoopback {
   readonly #server: ReturnType<typeof Bun.serve>;
   readonly #port: number;
@@ -20,18 +13,13 @@ export class McpOAuthLoopback {
     });
     this.#server = Bun.serve({
       port,
+      // Never 0.0.0.0: the redirect carries a credential that anything on the network could race the browser for.
       hostname: "127.0.0.1",
       fetch: (request) => this.#handle(request),
     });
   }
 
-  /**
-   * Binds the port a client was registered against, or the first free one from the list.
-   *
-   * A registration names its `redirect_uri` exactly, so a second sign-in that landed on a different port would
-   * be refused by the server — which is why the port that worked is stored with the client rather than chosen
-   * afresh. When it cannot be had, the caller registers again against whatever this did bind.
-   */
+  /** The registered port first, else the first free one; a caller that lost its port registers again. */
   static bind(preferred?: number) {
     const ports = preferred ? [preferred, ...McpOAuth.ports.filter((port) => port !== preferred)] : McpOAuth.ports;
     const failures: string[] = [];
@@ -66,7 +54,6 @@ export class McpOAuthLoopback {
     if (url.pathname !== McpOAuth.callbackPath) return new Response("Not found", { status: 404 });
     this.#resolve?.(url.searchParams);
     const failed = url.searchParams.get("error");
-    // The page is the only thing the person sees at the end of the flow, so it says which window to go back to.
     return new Response(
       `<!doctype html><meta charset="utf-8"><title>akan code</title><body style="font:16px system-ui;padding:3rem">
 <h1>${failed ? "Sign-in failed" : "Signed in"}</h1>

package/codeAgent/tools/McpServerConfig.ts

@@ -3,7 +3,6 @@ import path from "node:path";
 import type { CodeAgentMcpServerRef } from "akanjs/common";
 import { akanCodePaths } from "../agent/akanCodePaths";
 
-/** Which of the two files a server is declared in — see {@link McpServerConfig}. */
 export type McpServerScope = "global" | "workspace";
 
 export interface McpDeclaredServer {
@@ -28,21 +27,8 @@ interface ServerFile {
   servers?: Record<string, ServerFileEntry>;
 }
 
-/**
- * The declared MCP servers, in the shape the editors already write, from two files.
- *
- * `~/.akan/code/mcp.json` is the person's, and `<repo>/.akan/code/mcp.json` is the checkout's. **The global
- * file is where a server normally goes**: a server is an integration with an account, the token for it
- * already lives in the home directory, and declaring it per repo means declaring and signing in again in
- * every checkout. The workspace file is for a server that is genuinely this repo's — one it starts itself, or
- * one only its team reaches — and a name declared in both resolves to the workspace's, because the more
- * specific declaration is the one that knew about the other.
- *
- * Both hold an `mcpServers` map — the block a developer already has in their Claude, Cursor or VS Code config
- * — so the file can be pasted rather than translated. `servers` is read as well because VS Code spells it
- * that way, and whichever key a file already uses is the one a write goes back into: rewriting it to our
- * preferred spelling would silently break the editor sharing the file.
- */
+// Global is the default home: a server's token already lives there, so one declaration serves every checkout.
+// VS Code spells the key `servers`; a write keeps the file's own key, or it breaks the editor sharing the file.
 export class McpServerConfig {
   static file(workspaceRoot: string, scope: McpServerScope = "workspace") {
     return scope === "global" ? akanCodePaths.globalMcpFile() : akanCodePaths.mcpFile(workspaceRoot);
@@ -71,12 +57,7 @@ export class McpServerConfig {
     return [...byName.values()];
   }
 
-  /**
-   * Declares one server, replacing an entry of the same name in the file it is written to.
-   *
-   * A url is an http server and anything else is a command with its argv, which is the whole of the guess: a
-   * transport asked for as a third argument is a thing to get wrong, and the two shapes are already distinct.
-   */
+  /** Replaces a same-name entry in the target file; a url is an http server, anything else a command and argv. */
   static add(workspaceRoot: string, name: string, target: string[], scope: McpServerScope = "global") {
     const [head, ...rest] = target;
     if (!head) throw new Error("Give the server a command to run, or a url to reach.");
@@ -88,9 +69,10 @@ export class McpServerConfig {
     return McpServerConfig.#refOf(name, entry);
   }
 
-  /** Removes it from whichever file declares it, and says which — a name can only be in one at a time. */
-  static remove(workspaceRoot: string, name: string): McpServerScope | false {
-    for (const { scope } of [...McpServerConfig.files(workspaceRoot)].reverse()) {
+  /** Removes it from the file `only` names, else the workspace file and then the global one; false when none has it. */
+  static remove(workspaceRoot: string, name: string, only?: McpServerScope): McpServerScope | false {
+    const candidates = McpServerConfig.files(workspaceRoot).filter(({ scope }) => !only || scope === only);
+    for (const { scope } of candidates.reverse()) {
       const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
       if (!(name in map)) continue;
       const next = { ...map };
@@ -114,7 +96,6 @@ export class McpServerConfig {
     };
   }
 
-  /** What a server is reached at, as one line: the argv or the url. */
   static targetOf(ref: CodeAgentMcpServerRef) {
     return ref.url ?? [ref.command, ...(ref.args ?? [])].filter(Boolean).join(" ");
   }

package/codeAgent/tools/McpSignIn.ts

@@ -1,4 +1,5 @@
 import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { ConfigLock } from "../../cloud/configLock";
 import { McpOAuth, type McpOAuthServer } from "./McpOAuth";
 import { McpOAuthLoopback } from "./McpOAuthLoopback";
 import { type McpStoredAuth, McpTokenStore } from "./McpTokenStore";
@@ -9,59 +10,64 @@ export interface McpSignInOptions {
   onNotice?: (message: string) => void;
 }
 
-/**
- * Signing one MCP server in, and keeping it signed in.
- *
- * The two halves are deliberately apart. {@link token} runs at connect and is allowed to do anything that
- * needs no person — read a stored token, refresh an expired one — while {@link run} opens a browser and is
- * only ever called by a host that has somebody in front of it.
- *
- * Connecting must never block on a sign-in. `McpToolPack.connect` happens inside `CodeAgent.create`, before
- * the first frame is drawn, so a browser round trip there would hold the whole session on a screen that does
- * not exist yet. A server that needs a credential and has none is reported, not waited for.
- */
 export class McpSignIn {
-  /**
-   * The bearer token to connect with, or undefined when there is none to be had without asking.
-   *
-   * A refresh that fails is not an error here: the stored grant was revoked or expired past refreshing, and
-   * the answer is the same as having no token at all — the server will say so, and the host will offer a
-   * sign-in. Throwing would cost the session every other server's tools.
-   */
+  // A server that rotates refresh tokens may revoke the whole grant when one is presented twice.
+  static readonly #refreshing = new Map<string, Promise<string | undefined>>();
+
+  /** The token to connect with, or undefined when none is had without asking; a failed refresh is not a throw. */
   static async token(ref: CodeAgentMcpServerRef, onNotice?: (message: string) => void) {
     const stored = McpTokenStore.read(ref.name);
     if (!stored) return undefined;
     if (!McpTokenStore.isExpired(stored)) return stored.accessToken;
+    return await McpSignIn.#refreshOnce(ref, stored, onNotice);
+  }
+
+  /** After a server answered `refused` with 401: a token another session stored since, else one refresh. */
+  static async retryToken(ref: CodeAgentMcpServerRef, refused: string, onNotice?: (message: string) => void) {
+    const stored = McpTokenStore.read(ref.name);
+    if (!stored) return undefined;
+    if (stored.accessToken !== refused && !McpTokenStore.isExpired(stored)) return stored.accessToken;
+    return await McpSignIn.#refreshOnce(ref, stored, onNotice);
+  }
+
+  static async #refreshOnce(ref: CodeAgentMcpServerRef, stored: McpStoredAuth, onNotice?: (message: string) => void) {
+    const key = `${ref.name}\n${stored.refreshToken}`;
+    let pending = McpSignIn.#refreshing.get(key);
+    if (!pending) {
+      pending = McpSignIn.#refreshed(ref, stored, onNotice).finally(() => McpSignIn.#refreshing.delete(key));
+      McpSignIn.#refreshing.set(key, pending);
+    }
+    return await pending;
+  }
+
+  static async #refreshed(ref: CodeAgentMcpServerRef, stored: McpStoredAuth, onNotice?: (message: string) => void) {
     if (!stored.refreshToken) return undefined;
     try {
-      const server: McpOAuthServer = {
-        issuer: stored.issuer,
-        authorizationEndpoint: "",
-        tokenEndpoint: stored.tokenEndpoint,
-        resource: stored.resource,
-      };
-      const tokens = await McpOAuth.refresh(server, stored);
-      McpTokenStore.write(ref.name, {
-        ...stored,
-        accessToken: tokens.accessToken,
+      return await ConfigLock.run(McpTokenStore.lockFile(), async () => {
+        // Another `akan code` may have refreshed while this one waited: take its token, never its spent refresh token.
+        const current = McpTokenStore.read(ref.name);
+        if (!current) return undefined;
+        if (current.accessToken !== stored.accessToken && !McpTokenStore.isExpired(current)) return current.accessToken;
+        const server: McpOAuthServer = {
+          issuer: current.issuer,
+          authorizationEndpoint: "",
+          tokenEndpoint: current.tokenEndpoint,
+          resource: current.resource,
+        };
+        const tokens = await McpOAuth.refresh(server, current);
+        // `expires_in` is optional (RFC 6749 §5.1): the spent token's expiry must not outlive it on the new one.
+        const { expiresAt: _spent, ...grant } = current;
         // A server that rotates refresh tokens invalidates the old one, so keeping it would sign us out.
-        ...(tokens.refreshToken ? { refreshToken: tokens.refreshToken } : {}),
-        ...(tokens.expiresAt ? { expiresAt: tokens.expiresAt } : {}),
-        ...(tokens.scope ? { scope: tokens.scope } : {}),
+        McpTokenStore.write(ref.name, { ...grant, ...tokens });
+        return tokens.accessToken;
       });
-      return tokens.accessToken;
     } catch (error) {
       onNotice?.(`MCP server "${ref.name}" needs signing in again — ${String(error)}`);
       return undefined;
     }
   }
 
-  /**
-   * The whole interactive flow: discover, register if needed, open a browser, store the token.
-   *
-   * The client registration is reused across sign-ins when the server it was made against has not moved, so a
-   * second sign-in to the same provider creates no second client entry in whatever account page lists them.
-   */
+  /** Interactive: discover, register unless the stored client is reusable, open a browser, store the token. */
   static async run(ref: CodeAgentMcpServerRef, options: McpSignInOptions): Promise<McpStoredAuth> {
     if (!ref.url) throw new Error(`"${ref.name}" is a stdio server: give it its credential through "env".`);
     const challenge = await McpSignIn.challenge(ref);
@@ -90,10 +96,7 @@ export class McpSignIn {
         clientId: client.clientId,
         ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
         redirectUri,
-        accessToken: tokens.accessToken,
-        ...(tokens.refreshToken ? { refreshToken: tokens.refreshToken } : {}),
-        ...(tokens.expiresAt ? { expiresAt: tokens.expiresAt } : {}),
-        ...(tokens.scope ? { scope: tokens.scope } : {}),
+        ...tokens,
       };
       McpTokenStore.write(ref.name, auth);
       return auth;
@@ -102,13 +105,7 @@ export class McpSignIn {
     }
   }
 
-  /**
-   * What the server answers an unauthenticated `initialize` with, or null when it wants no credential.
-   *
-   * Asked before discovery because the challenge names the resource metadata, and a server serving it under a
-   * path publishes a url no client can derive. A server that answers anything but `401` is one that does not
-   * need signing in, which is worth saying rather than running a flow against.
-   */
+  /** The `WWW-Authenticate` of an unauthenticated `initialize`, or null when the server answers anything but 401. */
   static async challenge(ref: CodeAgentMcpServerRef) {
     if (!ref.url) return null;
     try {

package/codeAgent/tools/McpTokenStore.ts

@@ -2,7 +2,6 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSy
 import path from "node:path";
 import { akanCodePaths } from "../agent/akanCodePaths";
 
-/** One server's credential, and the client registration it was issued against. */
 export interface McpStoredAuth {
   /** The authorization server that minted it, so a server that moves issuer invalidates rather than misuses it. */
   issuer: string;
@@ -21,19 +20,16 @@ export interface McpStoredAuth {
   scope?: string;
 }
 
-/**
- * The MCP bearer tokens, in the home directory and readable only by their owner.
- *
- * Never in the workspace: `.akan/code/mcp.json` is shared with the editors and routinely committed, and a
- * refresh token there is a credential in the repo. The file is written whole through a rename so a crash
- * mid-write cannot leave a truncated one, and a read that cannot parse it costs the sign-ins rather than the
- * session — a corrupt file re-authenticates, which is recoverable, where a thrown error is not.
- */
+// Home directory only, mode 0600: `.akan/code/mcp.json` is shared with the editors and routinely committed.
 export class McpTokenStore {
   static file() {
     return akanCodePaths.mcpAuthFile();
   }
 
+  static lockFile() {
+    return `${McpTokenStore.file()}.lock`;
+  }
+
   static read(name: string): McpStoredAuth | undefined {
     return McpTokenStore.#all()[name];
   }
@@ -42,13 +38,7 @@ export class McpTokenStore {
     return Object.keys(McpTokenStore.#all());
   }
 
-  /**
-   * Writes one entry, re-reading immediately before the write.
-   *
-   * Two sessions signing in to different servers at the same moment would otherwise each write the map they
-   * read at the start of their own flow — minutes earlier, across a browser round trip — and the second would
-   * drop the first's token.
-   */
+  /** Re-reads right before writing, or two concurrent sign-ins each drop the other's token. */
   static write(name: string, auth: McpStoredAuth) {
     McpTokenStore.#save({ ...McpTokenStore.#all(), [name]: auth });
   }
@@ -61,7 +51,6 @@ export class McpTokenStore {
     return true;
   }
 
-  /** Expired, or close enough that a call started now would land after it — see {@link skewMs}. */
   static isExpired(auth: McpStoredAuth) {
     return auth.expiresAt !== undefined && auth.expiresAt <= Date.now() + McpTokenStore.skewMs;
   }