@akanjs/devkit 3.0.0-beta.16 → 3.0.0-beta.18

package/codeAgent/tools/McpServerConfig.ts

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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 {
+  ref: CodeAgentMcpServerRef;
+  disabled: boolean;
+  scope: McpServerScope;
+}
+
+interface ServerFileEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  type?: string;
+  disabled?: boolean;
+  headers?: Record<string, string>;
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
+}
+
+interface ServerFile {
+  mcpServers?: Record<string, ServerFileEntry>;
+  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.
+ */
+export class McpServerConfig {
+  static file(workspaceRoot: string, scope: McpServerScope = "workspace") {
+    return scope === "global" ? akanCodePaths.globalMcpFile() : akanCodePaths.mcpFile(workspaceRoot);
+  }
+
+  /** Both files, in the order they are merged — global first, so the workspace's entry lands on top of it. */
+  static files(workspaceRoot: string): { scope: McpServerScope; file: string }[] {
+    return [
+      { scope: "global", file: McpServerConfig.file(workspaceRoot, "global") },
+      { scope: "workspace", file: McpServerConfig.file(workspaceRoot, "workspace") },
+    ];
+  }
+
+  static read(workspaceRoot: string): CodeAgentMcpServerRef[] {
+    return McpServerConfig.declared(workspaceRoot)
+      .filter((entry) => !entry.disabled)
+      .map((entry) => entry.ref);
+  }
+
+  /** Every declared server including the disabled ones, which is what a listing has to show. */
+  static declared(workspaceRoot: string): McpDeclaredServer[] {
+    const byName = new Map<string, McpDeclaredServer>();
+    for (const { scope } of McpServerConfig.files(workspaceRoot))
+      for (const [name, entry] of Object.entries(McpServerConfig.#parse(workspaceRoot, scope).map))
+        byName.set(name, { ref: McpServerConfig.#refOf(name, entry), disabled: !!entry.disabled, scope });
+    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.
+   */
+  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.");
+    const entry: ServerFileEntry = /^https?:\/\//.test(head) ? { url: head } : { command: head, args: rest };
+    const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
+    const next = { ...map, [name]: entry };
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
+    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()) {
+      const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
+      if (!(name in map)) continue;
+      const next = { ...map };
+      delete next[name];
+      writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
+      return scope;
+    }
+    return false;
+  }
+
+  static #refOf(name: string, entry: ServerFileEntry): CodeAgentMcpServerRef {
+    return {
+      name,
+      transport: entry.url ? "http" : "stdio",
+      ...(entry.command ? { command: entry.command } : {}),
+      ...(entry.args ? { args: entry.args } : {}),
+      ...(entry.url ? { url: entry.url } : {}),
+      ...(entry.env ? { env: entry.env } : {}),
+      ...(entry.headers ? { headers: entry.headers } : {}),
+      ...(entry.oauth ? { oauth: entry.oauth } : {}),
+    };
+  }
+
+  /** 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(" ");
+  }
+
+  /** Why a file yielded nothing, when it exists and yielded nothing — a listing has to say which. */
+  static problem(workspaceRoot: string) {
+    for (const { file } of McpServerConfig.files(workspaceRoot)) {
+      if (!existsSync(file)) continue;
+      try {
+        JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        return `${file} is not valid JSON — ${String(error)}`;
+      }
+    }
+    return undefined;
+  }
+
+  static #parse(workspaceRoot: string, scope: McpServerScope) {
+    const file = McpServerConfig.file(workspaceRoot, scope);
+    const empty = { file, key: "mcpServers" as const, map: {} as Record<string, ServerFileEntry> };
+    if (!existsSync(file)) return empty;
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as ServerFile;
+      if (parsed.servers && !parsed.mcpServers) return { file, key: "servers" as const, map: parsed.servers };
+      return { ...empty, map: parsed.mcpServers ?? {} };
+    } catch {
+      // A malformed file costs its servers, not the session; `problem` is what says so on the listing.
+      return empty;
+    }
+  }
+}

package/codeAgent/tools/McpSignIn.ts

@@ -0,0 +1,161 @@
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { McpOAuth, type McpOAuthServer } from "./McpOAuth";
+import { McpOAuthLoopback } from "./McpOAuthLoopback";
+import { type McpStoredAuth, McpTokenStore } from "./McpTokenStore";
+
+export interface McpSignInOptions {
+  /** How the host reaches a browser. A host with none must not call {@link McpSignIn.run}. */
+  open: (url: string) => void;
+  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.
+   */
+  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;
+    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,
+        // 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 } : {}),
+      });
+      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.
+   */
+  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);
+    const server = await McpOAuth.discover(ref.url, challenge);
+    const stored = McpTokenStore.read(ref.name);
+    const reusable = stored && stored.issuer === server.issuer && !ref.oauth?.clientId ? stored : undefined;
+    const loopback = McpOAuthLoopback.bind(McpSignIn.#portOf(reusable?.redirectUri));
+    try {
+      const redirectUri = loopback.redirectUri;
+      const client = await McpSignIn.#client(ref, server, redirectUri, reusable);
+      options.onNotice?.(`Opening a browser to sign in to "${ref.name}"…`);
+      const scope = McpOAuth.scopeOf(ref, server);
+      const tokens = await McpOAuth.authorize({
+        server,
+        clientId: client.clientId,
+        ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+        redirectUri,
+        ...(scope ? { scope } : {}),
+        open: options.open,
+        wait: () => loopback.wait(),
+      });
+      const auth: McpStoredAuth = {
+        issuer: server.issuer,
+        tokenEndpoint: server.tokenEndpoint,
+        resource: server.resource,
+        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 } : {}),
+      };
+      McpTokenStore.write(ref.name, auth);
+      return auth;
+    } finally {
+      loopback.close();
+    }
+  }
+
+  /**
+   * 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.
+   */
+  static async challenge(ref: CodeAgentMcpServerRef) {
+    if (!ref.url) return null;
+    try {
+      const response = await fetch(ref.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+          ...ref.headers,
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 0,
+          method: "initialize",
+          params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "akan-code", version: "1" } },
+        }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      return response.status === 401 ? (response.headers.get("www-authenticate") ?? "") : null;
+    } catch {
+      // Unreachable is not unauthenticated. Discovery will try the well-known urls and report its own failure.
+      return null;
+    }
+  }
+
+  static async #client(
+    ref: CodeAgentMcpServerRef,
+    server: McpOAuthServer,
+    redirectUri: string,
+    reusable: McpStoredAuth | undefined,
+  ) {
+    if (ref.oauth?.clientId)
+      return {
+        clientId: ref.oauth.clientId,
+        ...(ref.oauth.clientSecret ? { clientSecret: ref.oauth.clientSecret } : {}),
+      };
+    if (reusable && reusable.redirectUri === redirectUri)
+      return {
+        clientId: reusable.clientId,
+        ...(reusable.clientSecret ? { clientSecret: reusable.clientSecret } : {}),
+      };
+    return await McpOAuth.register(server, redirectUri, ref.name);
+  }
+
+  static #portOf(redirectUri: string | undefined) {
+    if (!redirectUri) return undefined;
+    const port = Number(new URL(redirectUri).port);
+    return Number.isFinite(port) && port > 0 ? port : undefined;
+  }
+}

package/codeAgent/tools/McpTokenStore.ts

@@ -0,0 +1,92 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+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;
+  /** Kept with the token so a refresh at connect costs no discovery round trip before the first tool call. */
+  tokenEndpoint: string;
+  /** RFC 8707: what the token was minted for, which a refresh has to restate. */
+  resource: string;
+  clientId: string;
+  clientSecret?: string;
+  /** Registered with the client, so a later sign-in binds the same loopback port or registers again. */
+  redirectUri: string;
+  accessToken: string;
+  refreshToken?: string;
+  /** Epoch ms. Absent when the server issued no lifetime, which the spec allows and means "until refused". */
+  expiresAt?: number;
+  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.
+ */
+export class McpTokenStore {
+  static file() {
+    return akanCodePaths.mcpAuthFile();
+  }
+
+  static read(name: string): McpStoredAuth | undefined {
+    return McpTokenStore.#all()[name];
+  }
+
+  static names() {
+    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.
+   */
+  static write(name: string, auth: McpStoredAuth) {
+    McpTokenStore.#save({ ...McpTokenStore.#all(), [name]: auth });
+  }
+
+  static clear(name: string) {
+    const all = McpTokenStore.#all();
+    if (!(name in all)) return false;
+    delete all[name];
+    McpTokenStore.#save(all);
+    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;
+  }
+
+  /** A token is treated as spent this long before it actually is, so a call never races its own expiry. */
+  static readonly skewMs = 60_000;
+
+  static #all(): Record<string, McpStoredAuth> {
+    const file = McpTokenStore.file();
+    if (!existsSync(file)) return {};
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as { servers?: Record<string, McpStoredAuth> };
+      return parsed.servers ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  static #save(servers: Record<string, McpStoredAuth>) {
+    const file = McpTokenStore.file();
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ servers }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    // `rename` keeps the temp file's mode, but an existing target written by an older build may be looser.
+    chmodSync(file, 0o600);
+  }
+}

package/codeAgent/tools/McpToolPack.ts

@@ -1,9 +1,15 @@
-import { existsSync, readFileSync } from "node:fs";
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
-import { type CodeAgentMcpServerRef, type CodeAgentProfile, codeAgentClip, codeAgentOutputChars } from "akanjs/common";
+import {
+  type CodeAgentMcpServerRef,
+  type CodeAgentMcpStatus,
+  type CodeAgentProfile,
+  codeAgentClip,
+  codeAgentOutputChars,
+} from "akanjs/common";
 import { Type } from "typebox";
-import { akanCodePaths } from "../agent/akanCodePaths";
-import { McpClient, type McpToolInfo } from "./McpClient";
+import { McpClient, type McpToolInfo, McpUnauthorized } from "./McpClient";
+import { McpServerConfig } from "./McpServerConfig";
+import { McpSignIn } from "./McpSignIn";
 
 export interface McpToolPackOptions {
   workspaceRoot: string;
@@ -11,15 +17,6 @@ export interface McpToolPackOptions {
   onNotice?: (message: string) => void;
 }
 
-interface ServerFileEntry {
-  command?: string;
-  args?: string[];
-  env?: Record<string, string>;
-  url?: string;
-  type?: string;
-  disabled?: boolean;
-}
-
 /**
  * Connects the workspace's MCP servers and publishes their tools.
  *
@@ -30,31 +27,49 @@ interface ServerFileEntry {
  * and a collision that silently shadows one of them is invisible from the model's side.
  */
 export class McpToolPack {
-  readonly #options: McpToolPackOptions;
   readonly #clients: { client: McpClient; tools: McpToolInfo[] }[] = [];
+  readonly #status: CodeAgentMcpStatus[] = [];
 
-  private constructor(options: McpToolPackOptions) {
-    this.#options = options;
-  }
+  /** Only {@link connect} may build one: a pack whose servers were never reached publishes broken tools. */
+  private constructor() {}
 
   /**
    * Connects every declared server before the session exists, because the session's tool allowlist has to name
    * these tools and their names are only knowable from a live `tools/list`.
+   *
+   * A pack comes back whenever anything was declared, including when every server failed: what went wrong is
+   * the answer `/mcp` exists to give, and a pack that dissolves on failure has nowhere to keep it.
    */
   static async connect(options: McpToolPackOptions) {
     const refs = McpToolPack.#refs(options);
     if (!refs.length) return undefined;
-    const pack = new McpToolPack(options);
+    const pack = new McpToolPack();
     for (const ref of refs) {
+      const base = { name: ref.name, transport: ref.transport, target: McpServerConfig.targetOf(ref) };
+      // Stored or refreshed, never asked for: connecting runs inside `CodeAgent.create`, and a browser round
+      // trip there would hold the session on a screen that has not been drawn yet — see {@link McpSignIn}.
+      const token = ref.transport === "http" ? await McpSignIn.token(ref, options.onNotice) : undefined;
       try {
-        const client = await new McpClient(ref).connect();
-        pack.#clients.push({ client, tools: await client.listTools() });
+        const client = await new McpClient(ref, token).connect();
+        const tools = await client.listTools();
+        pack.#clients.push({ client, tools });
+        pack.#status.push({
+          ...base,
+          tools: tools.map((tool) => McpToolPack.#nameOf(ref.name, tool.name)),
+          auth: token ? "authorized" : "none",
+        });
       } catch (error) {
+        if (error instanceof McpUnauthorized) {
+          options.onNotice?.(`MCP server "${ref.name}" needs signing in — /mcp login ${ref.name}`);
+          pack.#status.push({ ...base, tools: [], auth: "required" });
+          continue;
+        }
         // One unreachable integration must not cost the agent its turn, so it costs only its own tools.
         options.onNotice?.(`MCP server "${ref.name}" is unavailable: ${String(error)}`);
+        pack.#status.push({ ...base, tools: [], error: String(error) });
       }
     }
-    return pack.#clients.length ? pack : undefined;
+    return pack;
   }
 
   get toolNames() {
@@ -63,6 +78,11 @@ export class McpToolPack {
     );
   }
 
+  /** What each declared server turned out to be, for a host that offers to show it. */
+  get status(): CodeAgentMcpStatus[] {
+    return this.#status;
+  }
+
   extension(): InlineExtension {
     return { name: "akan-mcp", factory: (pi: ExtensionAPI) => this.#register(pi) };
   }
@@ -102,33 +122,6 @@ export class McpToolPack {
   static #refs(options: McpToolPackOptions): CodeAgentMcpServerRef[] {
     if (options.profile.tools.mcp === "off") return [];
     const declared = Array.isArray(options.profile.tools.mcp) ? options.profile.tools.mcp : [];
-    return [...McpToolPack.#fromFile(options.workspaceRoot), ...declared];
-  }
-
-  static #fromFile(workspaceRoot: string): CodeAgentMcpServerRef[] {
-    const file = akanCodePaths.mcpFile(workspaceRoot);
-    if (!existsSync(file)) return [];
-    try {
-      const parsed = JSON.parse(readFileSync(file, "utf8")) as {
-        mcpServers?: Record<string, ServerFileEntry>;
-        servers?: Record<string, ServerFileEntry>;
-      };
-      const entries = Object.entries(parsed.mcpServers ?? parsed.servers ?? {});
-      return entries
-        .filter(([, entry]) => !entry.disabled)
-        .map(([name, entry]): CodeAgentMcpServerRef => {
-          const transport = entry.url ? "http" : "stdio";
-          return {
-            name,
-            transport,
-            ...(entry.command ? { command: entry.command } : {}),
-            ...(entry.args ? { args: entry.args } : {}),
-            ...(entry.url ? { url: entry.url } : {}),
-            ...(entry.env ? { env: entry.env } : {}),
-          };
-        });
-    } catch {
-      return [];
-    }
+    return [...McpServerConfig.read(options.workspaceRoot), ...declared];
   }
 }

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -231,8 +231,13 @@ describe("AkanEnvKeys", () => {
     tempRoots.push(root);
     await writeText(path.join(root, ".env"), '# comment\nDEEPSEEK_API_KEY="sk-test"\nSOMETHING_ELSE=1\n');
     const applied: [string, string][] = [];
-    const fake = { setRuntimeApiKey: (provider: string, key: string) => applied.push([provider, key]) };
-    const providers = AkanEnvKeys.apply(fake as never, root);
+    const fake = {
+      setRuntimeApiKey: (provider: string, key: string) => {
+        applied.push([provider, key]);
+        return Promise.resolve();
+      },
+    };
+    const providers = await AkanEnvKeys.apply(fake as never, root);
     expect(providers).toContain("deepseek");
     expect(applied).toContainEqual(["deepseek", "sk-test"]);
   });
@@ -296,6 +301,29 @@ describe("SubagentPool", () => {
     expect(reader.tools.builtin).not.toContain("bash");
   });
 
+  /**
+   * A refused call opens no child, so it must leave no row behind either — a rail that shows a sub-agent the
+   * pool never started reads as work in flight, and the budget it was refused over says the opposite.
+   */
+  test("a refusal reports no running sub-agent", async () => {
+    const parent = codeAgentPresets.local("/tmp/akan");
+    const spent = { ...parent, tools: { ...parent.tools, subagent: { maxConcurrent: 0, maxDepth: 2, budget: 0 } } };
+    const frames: unknown[][] = [];
+    const extension = SubagentPool.extensionFor({
+      workspace,
+      cwd: "/tmp/akan",
+      parent: spent,
+      depth: 0,
+      onAgents: (agents) => frames.push(agents),
+    });
+    const tools: { execute: (id: string, params: never) => Promise<{ isError?: boolean }> }[] = [];
+    if (extension && "factory" in extension)
+      extension.factory({ registerTool: (spec: never) => tools.push(spec) } as never);
+    const result = await tools[0]?.execute("c0", { description: "d", prompt: "p" } as never);
+    expect(result?.isError).toBe(true);
+    expect(frames).toEqual([]);
+  });
+
   /** Nothing a sub-agent does belongs in the workspace's session tree, and nobody is there to answer it. */
   test("a child keeps no session and cannot ask a human", () => {
     const child = SubagentPool.childOf(codeAgentPresets.local("/tmp/akan"), "explore");
@@ -367,8 +395,13 @@ for await (const line of console) {
       profile: codeAgentPresets.local(root),
       onNotice: (message) => notices.push(message),
     });
-    expect(pack).toBeUndefined();
+    expect(pack?.toolNames).toEqual([]);
     expect(notices.join(" ")).toContain("broken");
+    // The pack survives the failure so `/mcp` can say what went wrong; a pack that dissolved would leave the
+    // server indistinguishable from one nobody declared.
+    expect(pack?.status).toEqual([
+      { name: "broken", transport: "stdio", target: "/nonexistent/binary", tools: [], error: expect.any(String) },
+    ]);
   });
 
   test("declares nothing when the profile turns MCP off", async () => {