@akanjs/devkit 3.0.0-beta.15 → 3.0.0-beta.17

package/codeAgent/agent/AkanCodeServices.ts

@@ -1,14 +1,8 @@
 import { existsSync, mkdirSync } from "node:fs";
-import {
-  AuthStorage,
-  type InlineExtension,
-  ModelRegistry,
-  SessionManager,
-  SettingsManager,
-} from "@earendil-works/pi-coding-agent";
+import { type InlineExtension, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentProfile } from "akanjs/common";
 import { AkanEnvKeys } from "../tools/AkanEnvKeys";
-import { AkanAuthStorageBackend } from "./AkanAuthStorageBackend";
+import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
 import { akanCodePaths } from "./akanCodePaths";
 import { akanSystemPrompt } from "./akanSystemPrompt";
 import { CodeSessionIndex } from "./CodeSessionIndex";
@@ -24,8 +18,8 @@ export interface AkanCodeServicesOptions {
 /**
  * Assembles the engine's injectable services from akan's own storage.
  *
- * Every one of the five is passed explicitly. Leave any of them out and the engine falls back to `~/.pi/` —
- * measured: with all five injected it writes nothing outside the paths named here.
+ * Every one of the four is passed explicitly. Leave any of them out and the engine falls back to `~/.pi/` —
+ * measured: with all four injected it writes nothing outside the paths named here.
  */
 export class AkanCodeServices {
   static settings() {
@@ -41,15 +35,21 @@ export class AkanCodeServices {
     });
   }
 
-  static auth(workspaceRoot: string) {
+  /**
+   * The model catalogue and the credentials behind it, both under `~/.akan/`.
+   *
+   * `authPath` is the whole of what akan's own credential file used to need a storage backend for: the engine
+   * locks and rewrites that file itself, so a second `akan code` refreshing an OAuth token at the same moment
+   * cannot clobber the first. Nothing lands in `~/.pi/`, and a user who removes akan takes their keys with them.
+   */
+  static async runtime(workspaceRoot: string) {
     mkdirSync(akanCodePaths.globalDir(), { recursive: true, mode: 0o700 });
-    const authStorage = AuthStorage.fromStorage(new AkanAuthStorageBackend(akanCodePaths.authFile()));
-    AkanEnvKeys.apply(authStorage, workspaceRoot);
-    return authStorage;
-  }
-
-  static models(authStorage: AuthStorage) {
-    return ModelRegistry.create(authStorage, akanCodePaths.modelsFile());
+    const runtime = await ModelRuntime.create({
+      authPath: akanCodePaths.authFile(),
+      modelsPath: akanCodePaths.modelsFile(),
+    });
+    await AkanEnvKeys.apply(runtime, workspaceRoot);
+    return runtime;
   }
 
   static sessions(workspaceRoot: string, cwd: string, profile: CodeAgentProfile, resume?: string) {
@@ -95,6 +95,15 @@ export class AkanCodeServices {
       noPromptTemplates: true,
       noThemes: true,
       noContextFiles: !options.profile.context.projectFiles,
+      // The engine takes one context file per directory and looks at no editor's own rules, so a repo whose
+      // conventions live in a `CLAUDE.md` or under `.cursor/rules` hands this agent less than it hands the
+      // editor beside it — see {@link AkanContextFiles}. Gated on the same flag, so a profile that wants no
+      // project context still gets none.
+      agentsFilesOverride: ({ agentsFiles }: { agentsFiles: AkanContextFile[] }) => ({
+        agentsFiles: options.profile.context.projectFiles
+          ? AkanContextFiles.extend(agentsFiles, { workspaceRoot: options.workspaceRoot, cwd: options.cwd })
+          : agentsFiles,
+      }),
       appendSystemPrompt: [akanSystemPrompt(options.profile)],
       additionalExtensionPaths: present(akanCodePaths.extensionsDir(options.workspaceRoot)),
       additionalSkillPaths: AkanCodeServices.#skillPaths(options.profile, options.workspaceRoot),

package/codeAgent/agent/AkanContextFiles.ts

@@ -0,0 +1,117 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export interface AkanContextFile {
+  path: string;
+  content: string;
+}
+
+export interface AkanContextFilesOptions {
+  workspaceRoot: string;
+  cwd: string;
+}
+
+/**
+ * The workspace-authored rules the engine's own discovery leaves behind.
+ *
+ * It walks the ancestors of `cwd` and takes **one** file per directory, first match of
+ * `AGENTS.override.md · AGENTS.md · AGENTS.MD · CLAUDE.md · CLAUDE.MD` — so a repo carrying both an `AGENTS.md`
+ * and a `CLAUDE.md` has the second one silently dropped, and a `.cursor/rules` tree is never looked at. Both
+ * are files a developer wrote expecting an agent to obey them, and an agent that reads one editor's copy and
+ * not another's follows rules that disagree with the repo it is in.
+ *
+ * Added rather than replaced: the base list keeps its order and its precedence, and these land after it.
+ */
+export class AkanContextFiles {
+  /** Cursor's frontmatter block, which is metadata for its own rule picker and not instruction for a model. */
+  static readonly #frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+  static extend(base: AkanContextFile[], options: AkanContextFilesOptions): AkanContextFile[] {
+    const seen = new Set(base.map((file) => file.path));
+    // Keyed by content as well as by path, because the usual way to carry both names is to make one a symlink
+    // to the other or a one-line pointer at it — and the same guide twice is the same guide twice.
+    const contents = new Set(base.map((file) => file.content.trim()));
+    const added: AkanContextFile[] = [];
+    for (const file of [...AkanContextFiles.#claude(base), ...AkanContextFiles.#cursor(options)]) {
+      if (seen.has(file.path) || contents.has(file.content.trim()) || !file.content.trim()) continue;
+      seen.add(file.path);
+      contents.add(file.content.trim());
+      added.push(file);
+    }
+    return [...base, ...added];
+  }
+
+  /**
+   * The `CLAUDE.md` beside an `AGENTS.md` the engine already took.
+   *
+   * Not beside an `AGENTS.override.md`: that name means "ignore what this directory would otherwise say", so
+   * reinstating the file it was written to displace is the one case where loading both is wrong.
+   */
+  static #claude(base: AkanContextFile[]) {
+    const files: AkanContextFile[] = [];
+    for (const file of base) {
+      if (!/^AGENTS\.(md|MD)$/.test(path.basename(file.path))) continue;
+      for (const name of ["CLAUDE.md", "CLAUDE.MD"]) {
+        const candidate = path.join(path.dirname(file.path), name);
+        const content = AkanContextFiles.#read(candidate);
+        if (content !== undefined) files.push({ path: candidate, content });
+      }
+    }
+    return files;
+  }
+
+  /**
+   * Cursor's always-on rules, from the workspace root and from the session's own directory.
+   *
+   * Only `alwaysApply: true` is taken. Cursor's other three kinds are conditional — `globs` attaches a rule to
+   * the files it names, a bare `description` offers it for the model to ask for, and neither means the rule is
+   * loaded manually — so putting them in a system prompt applies rules their author scoped away. A file with
+   * no frontmatter at all is the `.cursorrules` shape, which was never conditional.
+   */
+  static #cursor(options: AkanContextFilesOptions) {
+    const files: AkanContextFile[] = [];
+    const roots = [...new Set([options.workspaceRoot, options.cwd])];
+    for (const root of roots) {
+      const legacy = AkanContextFiles.#read(path.join(root, ".cursorrules"));
+      if (legacy !== undefined) files.push({ path: path.join(root, ".cursorrules"), content: legacy });
+      for (const file of AkanContextFiles.#mdcFiles(path.join(root, ".cursor", "rules"))) {
+        const raw = AkanContextFiles.#read(file);
+        if (raw === undefined) continue;
+        const body = AkanContextFiles.#applied(raw);
+        if (body !== undefined) files.push({ path: file, content: body });
+      }
+    }
+    return files;
+  }
+
+  /** The rule body when the rule applies unconditionally, and nothing when its author scoped it. */
+  static #applied(raw: string) {
+    const match = AkanContextFiles.#frontmatter.exec(raw);
+    if (!match) return raw;
+    if (!/^\s*alwaysApply\s*:\s*true\s*$/m.test(match[1] ?? "")) return undefined;
+    return raw.slice(match[0].length);
+  }
+
+  /** Sorted, because the order rules reach the model in is otherwise the order a directory happens to list. */
+  static #mdcFiles(dir: string) {
+    if (!existsSync(dir)) return [];
+    try {
+      return readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".mdc"))
+        .map((entry) => path.join(entry.parentPath ?? dir, entry.name))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  static #read(file: string) {
+    try {
+      if (!existsSync(file) || !statSync(file).isFile()) return undefined;
+      return readFileSync(file, "utf8").replace(/^/, "");
+    } catch {
+      // A rule file that cannot be read costs its own rules. It must not cost the session its start.
+      return undefined;
+    }
+  }
+}

package/codeAgent/agent/CodeAgent.ts

@@ -13,6 +13,7 @@ import {
   type CodeAgentEvent,
   type CodeAgentEventBody,
   type CodeAgentImage,
+  type CodeAgentMcpStatus,
   type CodeAgentProfile,
   type CodeAgentQuestion,
   type CodeAgentSessionInfo,
@@ -82,6 +83,8 @@ export class CodeAgent {
   #disposed = false;
   #sessionDir: string | undefined;
   #mailbox: CodeMailbox | undefined;
+  #mcp: CodeAgentMcpStatus[] = [];
+  #workspaceRoot = "";
   /**
    * The frames of the turn in flight, so a host that reconnects mid-turn can be handed what it missed.
    *
@@ -102,9 +105,8 @@ export class CodeAgent {
     const cwd = options.cwd ?? workspaceRoot;
     const agent = new CodeAgent(options.profile);
     const settingsManager = AkanCodeServices.settings();
-    const authStorage = AkanCodeServices.auth(workspaceRoot);
-    const modelRegistry = AkanCodeServices.models(authStorage);
-    const model = await akanCodeModel(modelRegistry, options.model);
+    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot);
+    const model = await akanCodeModel(modelRuntime, options.model);
     const compaction = DEFAULT_COMPACTION_SETTINGS;
     const modelWarnings = akanCodeModelWarnings(model, compaction.reserveTokens + compaction.keepRecentTokens);
 
@@ -118,6 +120,7 @@ export class CodeAgent {
       currentSessionId: () => agent.sessionId,
       mailbox: () => agent.#mailbox,
       onNotice: (message) => agent.#emit({ type: "notice", level: "warning", message }),
+      onAgents: (agents) => agent.#emit({ type: "subagent", agents }),
     });
 
     const resourceLoader = new DefaultResourceLoader({
@@ -136,8 +139,7 @@ export class CodeAgent {
     const { session } = await createAgentSession({
       cwd,
       agentDir: akanCodePaths.globalDir(),
-      authStorage,
-      modelRegistry,
+      modelRuntime,
       settingsManager,
       resourceLoader,
       model,
@@ -147,6 +149,8 @@ export class CodeAgent {
       customTools: options.customTools,
     });
     agent.#disposePlugins = akan.dispose;
+    agent.#mcp = akan.mcp;
+    agent.#workspaceRoot = workspaceRoot;
     if (options.profile.session.store === "file") agent.#sessionDir = akanCodePaths.sessionsDir(workspaceRoot);
     await agent.#attach(session, options.mode ?? "print");
     if (agent.#sessionDir) agent.#openMail(akanCodePaths.mailDir(workspaceRoot), cwd);
@@ -169,6 +173,21 @@ export class CodeAgent {
     return this.#sessionDir ? CodeSessionIndex.list(this.#sessionDir) : [];
   }
 
+  /** The repo, which is not `profile.paths.root` — that one is narrowed to an app by `akan code --app`. */
+  get workspaceRoot() {
+    return this.#workspaceRoot;
+  }
+
+  /**
+   * The MCP servers this session was built against, and what each one published.
+   *
+   * Read from the assembly rather than from the live session: the tool allowlist is fixed when the session is
+   * created, so a server declared afterwards is not one this agent can reach however the file now reads.
+   */
+  mcpServers(): CodeAgentMcpStatus[] {
+    return this.#mcp;
+  }
+
   /** The other `akan code` sessions running in this workspace right now. */
   peers() {
     return this.#mailbox?.peers() ?? [];
@@ -383,7 +402,7 @@ export class CodeAgent {
 
   async setModel(ref: CodeAgentModelRef) {
     const session = this.#require();
-    const model = await akanCodeModel(session.modelRegistry, ref);
+    const model = await akanCodeModel(session.modelRuntime, ref);
     if (!model) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
     await session.setModel(model);
     this.#emit({ type: "session", info: this.info });

package/codeAgent/agent/CodeAgentStreamPrinter.ts

@@ -54,6 +54,10 @@ export class CodeAgentStreamPrinter {
       case "queue":
       case "context":
         return;
+      // The rail is a live status for a screen that redraws. A stream has no row to update, and the pool
+      // already says on the transcript when a child starts and what it spent when it stops.
+      case "subagent":
+        return;
       case "question":
         return this.#line(chalk.yellow(`? ${event.question.prompt}`));
       case "approval":

package/codeAgent/agent/SubagentPool.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
-import { type CodeAgentProfile, codeAgentReadOnlyBuiltins } from "akanjs/common";
+import { type CodeAgentProfile, type CodeAgentSubagent, codeAgentReadOnlyBuiltins } from "akanjs/common";
 import { Type } from "typebox";
 import type { Workspace } from "../../commandDecorators";
 
@@ -10,10 +10,21 @@ export interface SubagentPoolOptions {
   depth: number;
   /** Progress and refusals reach the parent's host through this rather than through a new event kind. */
   onNotice?: (message: string) => void;
+  /** The running children, whole, for a host that draws them as a rail beside the prompt. */
+  onAgents?: (agents: CodeAgentSubagent[]) => void;
 }
 
 const maxResultChars = 8_000;
 
+/**
+ * How often the running children are re-reported while none of them starts or finishes.
+ *
+ * A child spends tokens for minutes between the two frames its lifetime would otherwise produce, and the
+ * number that decides whether to let it keep going is the one climbing in between. One frame a second for at
+ * most a handful of rows is far below what a single streaming turn already puts on the wire.
+ */
+const tickMs = 1_000;
+
 export type SubagentKind = keyof typeof SubagentPool.kinds;
 
 /**
@@ -47,8 +58,14 @@ export class SubagentPool {
   static readonly defaultKind: SubagentKind = "explore";
 
   readonly #options: SubagentPoolOptions;
+  /** Keyed by the `task` call that opened each child. `agent` lands once it exists, and reports live tokens. */
+  readonly #children = new Map<
+    string,
+    { kind: SubagentKind; description: string; startedAt: number; agent?: { tokensUsed: number } }
+  >();
   #running = 0;
   #spent = 0;
+  #ticker: ReturnType<typeof setInterval> | null = null;
 
   constructor(options: SubagentPoolOptions) {
     this.#options = options;
@@ -82,19 +99,23 @@ export class SubagentPool {
           ),
         ),
       }),
-      execute: async (_id, params, signal) => {
+      execute: async (id, params, signal) => {
         const kind = (params.type ?? SubagentPool.defaultKind) as SubagentKind;
         const refusal = this.#refuse();
         if (refusal) return { content: [{ type: "text", text: refusal }], details: undefined, isError: true };
         this.#running += 1;
+        this.#children.set(id, { kind, description: params.description, startedAt: Date.now() });
+        this.#report();
         // Said before it starts, not only when it ends: a turn that goes quiet for a minute while a child
         // reads the repo is otherwise indistinguishable from a turn that has stopped responding.
         this.#options.onNotice?.(`${kind} sub-agent · ${params.description}`);
         try {
-          const text = await this.#run(kind, params.prompt, signal);
+          const text = await this.#run(id, kind, params.prompt, signal);
           return { content: [{ type: "text", text }], details: undefined };
         } finally {
           this.#running -= 1;
+          this.#children.delete(id);
+          this.#report();
         }
       },
     });
@@ -137,7 +158,35 @@ export class SubagentPool {
     };
   }
 
-  async #run(kind: SubagentKind, prompt: string, signal: AbortSignal | undefined) {
+  /**
+   * The running children as a list, and the ticker that keeps it moving.
+   *
+   * The ticker is owned by the report rather than by the tool call: two children overlapping must not each
+   * start one, and the last one to finish is what stops it. It is unref'd because a pool with a child still
+   * registered is a bug that should end the process, not hold it open.
+   */
+  #report() {
+    const onAgents = this.#options.onAgents;
+    if (!onAgents) return;
+    onAgents(
+      [...this.#children].map(([id, child]) => ({
+        id,
+        kind: child.kind,
+        description: child.description,
+        startedAt: child.startedAt,
+        tokens: child.agent?.tokensUsed ?? 0,
+      })),
+    );
+    if (this.#children.size && !this.#ticker) {
+      this.#ticker = setInterval(() => this.#report(), tickMs);
+      this.#ticker.unref?.();
+    } else if (!this.#children.size && this.#ticker) {
+      clearInterval(this.#ticker);
+      this.#ticker = null;
+    }
+  }
+
+  async #run(id: string, kind: SubagentKind, prompt: string, signal: AbortSignal | undefined) {
     const { CodeAgent } = await import("./CodeAgent");
     const budget = this.#options.parent.tools.subagent;
     const child = SubagentPool.childOf(this.#options.parent, kind);
@@ -148,6 +197,8 @@ export class SubagentPool {
       apps: [],
       depth: this.#options.depth + 1,
     });
+    const running = this.#children.get(id);
+    if (running) running.agent = agent;
     const abort = () => void agent.abort();
     signal?.addEventListener("abort", abort, { once: true });
     try {

package/codeAgent/agent/akanCodeModel.ts

@@ -1,11 +1,11 @@
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
 /**
  * The engine's `Model` type lives in `@earendil-works/pi-ai` and is not re-exported from the package we depend
  * on, so it is recovered from the one public function that returns it rather than by adding a dependency on a
  * transitive package whose version we do not control.
  */
-export type CodeAgentModel = NonNullable<ReturnType<ModelRegistry["find"]>>;
+export type CodeAgentModel = NonNullable<ReturnType<ModelRuntime["getModel"]>>;
 
 export interface CodeAgentModelRef {
   provider: string;
@@ -42,17 +42,17 @@ const correctInputs = (model: CodeAgentModel | undefined) => {
  * An empty API key produces a request that succeeds with no content rather than an error, so a provider with no
  * configured auth is skipped here instead of answering with nothing three seconds later.
  */
-export const akanCodeModel = async (registry: ModelRegistry, ref?: CodeAgentModelRef) => {
+export const akanCodeModel = async (runtime: ModelRuntime, ref?: CodeAgentModelRef) => {
   if (ref) {
-    const requested = registry.find(ref.provider, ref.id);
+    const requested = runtime.getModel(ref.provider, ref.id);
     if (!requested) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
-    if (!registry.hasConfiguredAuth(requested))
+    if (!runtime.hasConfiguredAuth(ref.provider))
       throw new Error(`No API key configured for ${ref.provider}. Set ${ref.provider.toUpperCase()}_API_KEY.`);
     return correctInputs(requested);
   }
-  const fallback = registry.find(akanCodeDefaultModel.provider, akanCodeDefaultModel.id);
-  if (fallback && registry.hasConfiguredAuth(fallback)) return correctInputs(fallback);
-  return correctInputs(registry.getAvailable()[0]);
+  const fallback = runtime.getModel(akanCodeDefaultModel.provider, akanCodeDefaultModel.id);
+  if (fallback && runtime.hasConfiguredAuth(fallback.provider)) return correctInputs(fallback);
+  return correctInputs((await runtime.getAvailable())[0]);
 };
 
 /** A screenshot is worth attaching only to a model that can see it — after the catalogue has been corrected. */

package/codeAgent/agent/akanContextFiles.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
+
+const roots: string[] = [];
+
+const workspace = (files: Record<string, string>) => {
+  const root = mkdtempSync(path.join(tmpdir(), "akan-context-"));
+  roots.push(root);
+  for (const [name, content] of Object.entries(files)) {
+    const file = path.join(root, name);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, content);
+  }
+  return root;
+};
+
+/** What the engine hands over: the one context file it took for that directory. */
+const loaded = (root: string, name = "AGENTS.md"): AkanContextFile[] => [
+  { path: path.join(root, name), content: "the workspace guide" },
+];
+
+const namesOf = (files: AkanContextFile[], root: string) => files.map((file) => path.relative(root, file.path));
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("workspace context files", () => {
+  test("a CLAUDE.md beside the AGENTS.md the engine took is loaded too", () => {
+    const root = workspace({ "AGENTS.md": "the workspace guide", "CLAUDE.md": "comments override" });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual(["AGENTS.md", "CLAUDE.md"]);
+    expect(files[1]?.content).toBe("comments override");
+  });
+
+  test("an AGENTS.override.md keeps the CLAUDE.md it was written to displace out", () => {
+    const root = workspace({ "AGENTS.override.md": "instead of that", "CLAUDE.md": "the old one" });
+    const files = AkanContextFiles.extend(loaded(root, "AGENTS.override.md"), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual(["AGENTS.override.md"]);
+  });
+
+  test("the same guide under two names is loaded once", () => {
+    const root = workspace({ "AGENTS.md": "the workspace guide" });
+    symlinkSync(path.join(root, "AGENTS.md"), path.join(root, "CLAUDE.md"));
+    expect(namesOf(AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root }), root)).toEqual([
+      "AGENTS.md",
+    ]);
+  });
+
+  test("an always-on cursor rule is loaded without its frontmatter", () => {
+    const root = workspace({
+      ".cursor/rules/house.mdc": "---\ndescription: house style\nalwaysApply: true\n---\nnever use any\n",
+    });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual(["AGENTS.md", ".cursor/rules/house.mdc"]);
+    expect(files[1]?.content).toBe("never use any\n");
+  });
+
+  /** Cursor's other three kinds are conditional; applying one always is applying a rule its author scoped. */
+  test("a scoped cursor rule is left to cursor", () => {
+    const root = workspace({
+      ".cursor/rules/ui.mdc": "---\nglobs: ui/**/*.tsx\n---\nno inline colours\n",
+      ".cursor/rules/ask.mdc": "---\ndescription: for migrations\n---\nread the plan\n",
+      ".cursor/rules/off.mdc": "---\nalwaysApply: false\n---\nnot this one\n",
+    });
+    expect(namesOf(AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root }), root)).toEqual([
+      "AGENTS.md",
+    ]);
+  });
+
+  test("a rule with no frontmatter at all is unconditional, and so is .cursorrules", () => {
+    const root = workspace({ ".cursor/rules/plain.mdc": "just do it", ".cursorrules": "the legacy file" });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root).sort()).toEqual([".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort());
+  });
+
+  test("rules nested under the rules directory are found, in a stable order", () => {
+    const root = workspace({
+      ".cursor/rules/b.mdc": "---\nalwaysApply: true\n---\nsecond\n",
+      ".cursor/rules/a.mdc": "---\nalwaysApply: true\n---\nfirst\n",
+      ".cursor/rules/deep/c.mdc": "---\nalwaysApply: true\n---\nthird\n",
+    });
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
+    expect(namesOf(files, root)).toEqual([
+      "AGENTS.md",
+      ".cursor/rules/a.mdc",
+      ".cursor/rules/b.mdc",
+      ".cursor/rules/deep/c.mdc",
+    ]);
+  });
+
+  test("the session's own directory carries its rules as well as the workspace root", () => {
+    const root = workspace({
+      ".cursor/rules/root.mdc": "---\nalwaysApply: true\n---\nworkspace wide\n",
+      "apps/akan/.cursor/rules/app.mdc": "---\nalwaysApply: true\n---\napp only\n",
+    });
+    const cwd = path.join(root, "apps", "akan");
+    const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd });
+    expect(namesOf(files, root)).toEqual(["AGENTS.md", ".cursor/rules/root.mdc", "apps/akan/.cursor/rules/app.mdc"]);
+  });
+
+  test("an empty rule file adds nothing", () => {
+    const root = workspace({ ".cursor/rules/empty.mdc": "---\nalwaysApply: true\n---\n\n" });
+    expect(AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root })).toHaveLength(1);
+  });
+
+  test("nothing to add leaves the list exactly as the engine built it", () => {
+    const root = workspace({ "AGENTS.md": "the workspace guide" });
+    const base = loaded(root);
+    expect(AkanContextFiles.extend(base, { workspaceRoot: root, cwd: root })).toEqual(base);
+  });
+});

package/codeAgent/index.ts

@@ -8,7 +8,6 @@
  * `globalThis.console`, and it has to be the first import of an RPC entry rather than a re-export of this one.
  */
 
-export * from "./agent/AkanAuthStorageBackend";
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
 export * from "./agent/akanCodePaths";

package/codeAgent/tools/AkanCodePlugins.ts

@@ -1,5 +1,5 @@
 import type { InlineExtension } from "@earendil-works/pi-coding-agent";
-import type { CodeAgentProfile } from "akanjs/common";
+import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentSubagent } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import type { CodeMailbox } from "../agent/CodeMailbox";
 import { SubagentPool } from "../agent/SubagentPool";
@@ -28,6 +28,7 @@ export interface AkanCodePluginsOptions {
   /** Late, because the session this announces to its peers does not exist yet when the pack is built. */
   mailbox: () => CodeMailbox | undefined;
   onNotice?: (message: string) => void;
+  onAgents?: (agents: CodeAgentSubagent[]) => void;
 }
 
 /**
@@ -40,6 +41,8 @@ export interface AkanCodePluginsResult {
   extensions: InlineExtension[];
   /** Names the session's tool allowlist has to carry, or the model is told these tools do not exist. */
   toolNames: string[];
+  /** Every declared MCP server and what it published, including the ones that published nothing. */
+  mcp: CodeAgentMcpStatus[];
   /** Closes anything the pack holds open — currently the MCP server connections. */
   dispose: () => void;
 }
@@ -52,6 +55,7 @@ export class AkanCodePlugins {
       ...(options.onNotice ? { onNotice: options.onNotice } : {}),
     });
     const dispose = () => mcp?.close();
+    const mcpStatus = mcp?.status ?? [];
     const web = new WebToolPack({ profile: options.profile });
     const webExtension = web.extension();
     const sessions = new SessionToolPack({
@@ -67,6 +71,7 @@ export class AkanCodePlugins {
       return {
         extensions: [mcp?.extension(), webExtension, sessionExtension, mailExtension].filter((entry) => !!entry),
         toolNames: [...(mcp?.toolNames ?? []), ...web.names(), ...sessions.names(), ...mail.names()],
+        mcp: mcpStatus,
         dispose,
       };
     const readOnly = !options.profile.tools.builtin.includes("write");
@@ -82,6 +87,7 @@ export class AkanCodePlugins {
       parent: options.profile,
       depth: options.depth,
       ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+      ...(options.onAgents ? { onAgents: options.onAgents } : {}),
     });
     if (subagent) extensions.push(subagent);
     const sources = await AkanCodePlugins.#sources(options, readOnly);
@@ -106,6 +112,7 @@ export class AkanCodePlugins {
         ...sessions.names(),
         ...mail.names(),
       ],
+      mcp: mcpStatus,
       dispose,
     };
   }

package/codeAgent/tools/AkanEnvKeys.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import type { AuthStorage } from "@earendil-works/pi-coding-agent";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
 /**
  * Loads provider keys from the workspace's `.env` into the session, without persisting them anywhere.
@@ -12,12 +12,14 @@ import type { AuthStorage } from "@earendil-works/pi-coding-agent";
  * asked for.
  */
 export class AkanEnvKeys {
-  static apply(authStorage: AuthStorage, workspaceRoot: string) {
+  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;
-      authStorage.setRuntimeApiKey(provider, value);
+      // 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.
+      await runtime.setRuntimeApiKey(provider, value);
       applied.push(provider);
     }
     return applied;

package/codeAgent/tools/McpServerConfig.ts

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { akanCodePaths } from "../agent/akanCodePaths";
+
+interface ServerFileEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  type?: string;
+  disabled?: boolean;
+}
+
+interface ServerFile {
+  mcpServers?: Record<string, ServerFileEntry>;
+  servers?: Record<string, ServerFileEntry>;
+}
+
+/**
+ * The workspace's declared MCP servers, in the shape the editors already write.
+ *
+ * `.akan/code/mcp.json` holds 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 the 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) {
+    return akanCodePaths.mcpFile(workspaceRoot);
+  }
+
+  static read(workspaceRoot: string): CodeAgentMcpServerRef[] {
+    const entries = Object.entries(McpServerConfig.#parse(workspaceRoot).map);
+    return entries.filter(([, entry]) => !entry.disabled).map(([name, entry]) => McpServerConfig.#refOf(name, entry));
+  }
+
+  /** Every declared server including the disabled ones, which is what a listing has to show. */
+  static declared(workspaceRoot: string) {
+    return Object.entries(McpServerConfig.#parse(workspaceRoot).map).map(([name, entry]) => ({
+      ref: McpServerConfig.#refOf(name, entry),
+      disabled: !!entry.disabled,
+    }));
+  }
+
+  /**
+   * Declares one server, replacing an entry of the same name.
+   *
+   * 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[]) {
+    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);
+    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);
+  }
+
+  static remove(workspaceRoot: string, name: string) {
+    const { file, key, map } = McpServerConfig.#parse(workspaceRoot);
+    if (!(name in map)) return false;
+    const next = { ...map };
+    delete next[name];
+    writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
+    return true;
+  }
+
+  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 } : {}),
+    };
+  }
+
+  /** 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 the file yielded nothing, when it exists and yielded nothing — a listing has to say which. */
+  static problem(workspaceRoot: string) {
+    const file = McpServerConfig.file(workspaceRoot);
+    if (!existsSync(file)) return undefined;
+    try {
+      JSON.parse(readFileSync(file, "utf8"));
+      return undefined;
+    } catch (error) {
+      return `${file} is not valid JSON — ${String(error)}`;
+    }
+  }
+
+  static #parse(workspaceRoot: string) {
+    const file = McpServerConfig.file(workspaceRoot);
+    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/McpToolPack.ts

@@ -1,9 +1,14 @@
-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 { McpServerConfig } from "./McpServerConfig";
 
 export interface McpToolPackOptions {
   workspaceRoot: string;
@@ -11,15 +16,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 +26,37 @@ 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) };
       try {
         const client = await new McpClient(ref).connect();
-        pack.#clients.push({ client, tools: await client.listTools() });
+        const tools = await client.listTools();
+        pack.#clients.push({ client, tools });
+        pack.#status.push({ ...base, tools: tools.map((tool) => McpToolPack.#nameOf(ref.name, tool.name)) });
       } catch (error) {
         // 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 +65,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 +109,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 () => {

package/codeAgent/tools/mcpServerConfig.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { McpServerConfig } from "./McpServerConfig";
+
+const roots: string[] = [];
+
+const workspace = (file?: string) => {
+  const root = mkdtempSync(path.join(tmpdir(), "akan-mcp-"));
+  roots.push(root);
+  if (file === undefined) return root;
+  const target = McpServerConfig.file(root);
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, file);
+  return root;
+};
+
+const written = (root: string) =>
+  JSON.parse(readFileSync(McpServerConfig.file(root), "utf8")) as Record<string, object>;
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("MCP server config", () => {
+  test("an editor's own block is read as it is written", () => {
+    const root = workspace(
+      JSON.stringify({
+        mcpServers: {
+          github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+          linear: { url: "https://mcp.linear.app/sse" },
+        },
+      }),
+    );
+    expect(McpServerConfig.read(root)).toEqual([
+      { name: "github", transport: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+      { name: "linear", transport: "http", url: "https://mcp.linear.app/sse" },
+    ]);
+  });
+
+  test("a disabled server is declared but never connected", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { off: { command: "x", disabled: true } } }));
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.declared(root)).toEqual([
+      { ref: { name: "off", transport: "stdio", command: "x" }, disabled: true },
+    ]);
+  });
+
+  test("a url is an http server and anything else is a command with its argv", () => {
+    const root = workspace();
+    expect(McpServerConfig.add(root, "linear", ["https://mcp.linear.app/sse"])).toEqual({
+      name: "linear",
+      transport: "http",
+      url: "https://mcp.linear.app/sse",
+    });
+    expect(McpServerConfig.add(root, "github", ["npx", "-y", "server-github"])).toEqual({
+      name: "github",
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "server-github"],
+    });
+    expect(Object.keys(written(root).mcpServers ?? {})).toEqual(["linear", "github"]);
+  });
+
+  /** The file is shared with whatever editor wrote it, so the key it already uses is the key a write goes into. */
+  test("a VS Code file keeps its own spelling through a write", () => {
+    const root = workspace(JSON.stringify({ servers: { a: { command: "a" } } }));
+    McpServerConfig.add(root, "b", ["b"]);
+    const file = written(root);
+    expect(Object.keys(file)).toEqual(["servers"]);
+    expect(Object.keys(file.servers ?? {})).toEqual(["a", "b"]);
+  });
+
+  test("adding the same name twice replaces the entry rather than doubling it", () => {
+    const root = workspace();
+    McpServerConfig.add(root, "a", ["old"]);
+    McpServerConfig.add(root, "a", ["new", "--flag"]);
+    expect(McpServerConfig.read(root)).toEqual([{ name: "a", transport: "stdio", command: "new", args: ["--flag"] }]);
+  });
+
+  test("removing says whether it removed anything", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { a: { command: "a" } } }));
+    expect(McpServerConfig.remove(root, "nope")).toBe(false);
+    expect(McpServerConfig.remove(root, "a")).toBe(true);
+    expect(McpServerConfig.read(root)).toEqual([]);
+  });
+
+  test("a server with nothing to reach it by is refused", () => {
+    expect(() => McpServerConfig.add(workspace(), "a", [])).toThrow();
+  });
+
+  test("a malformed file costs its servers and is named rather than thrown", () => {
+    const root = workspace("{ not json");
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.problem(root)).toContain("not valid JSON");
+  });
+
+  test("no file at all is not a problem", () => {
+    const root = workspace();
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.problem(root)).toBeUndefined();
+  });
+
+  test("a server reads back as the one line it is reached at", () => {
+    expect(McpServerConfig.targetOf({ name: "a", transport: "stdio", command: "npx", args: ["-y", "x"] })).toBe(
+      "npx -y x",
+    );
+    expect(McpServerConfig.targetOf({ name: "a", transport: "http", url: "https://x" })).toBe("https://x");
+  });
+});

package/executors.ts

@@ -1832,6 +1832,11 @@ export class PkgExecutor extends Executor {
     };
     const rootVersion = rootDeps[dep];
     if (rootVersion) return rootVersion;
+    // A transitive dependency the workspace pins rather than imports is only ever written as an override, and
+    // that pin has to reach the published package: neither an override nor a dependency's own shrinkwrap is
+    // applied to a consumer's install, so the version has to be a dependency of what we publish.
+    const overrideVersion = rootPackageJson.overrides?.[dep];
+    if (typeof overrideVersion === "string") return overrideVersion;
 
     try {
       const packageJsonPath = `pkgs/${dep}/package.json`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.15",
+  "version": "3.0.0-beta.17",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -39,11 +39,16 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.6",
+    "@earendil-works/chord": "0.86.1",
+    "@earendil-works/pi-agent-core": "0.86.1",
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-telemetry": "0.86.1",
+    "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.15",
+    "akanjs": "3.0.0-beta.17",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/piDependencyPins.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { PackageJson } from "@akanjs/devkit/types";
+
+// Guards the published dependency closure of the code agent, which the monorepo cannot exercise on its own.
+//
+// `@earendil-works/pi-coding-agent` asks for `^0.80.6` of its three sibling packages and ships an
+// `npm-shrinkwrap.json` pinning them to the exact version it was built against. Bun reads neither that file nor
+// this workspace's `overrides` when somebody installs the published CLI, so `^0.80.6` resolved to the newest
+// 0.80.x — 0.80.10, which dropped `getOAuthApiKey` from `pi-ai/oauth` while the pinned coding agent still
+// imports it. A global install died on its first import:
+//
+//   Export named 'getOAuthApiKey' not found in module '.../@earendil-works/pi-ai/dist/oauth.js'.
+//
+// `PackageRunner` therefore re-declares pi's own pins as dependencies of what we publish; this keeps the two
+// equal, so bumping the coding agent without moving the pins fails here rather than at a user's first run.
+
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const piName = "@earendil-works/pi-coding-agent";
+const piDir = `${repoRoot}/node_modules/${piName}`;
+const publishedPackages = ["pkgs/@akanjs/devkit/package.json", "pkgs/@akanjs/cli/package.json"];
+
+interface Shrinkwrap {
+  packages: Record<string, { version?: string }>;
+}
+
+const readJson = async <T>(file: string) => (await Bun.file(file).json()) as T;
+
+const shrinkwrappedPins = async () => {
+  const { packages } = await readJson<Shrinkwrap>(`${piDir}/npm-shrinkwrap.json`);
+  // Top-level entries only: a key with a second `node_modules/` in it is a *nested placement* of some other
+  // package's dependency, which a consumer's resolver reaches on its own and we have no business pinning.
+  const entries = Object.entries(packages)
+    .filter(([key]) => /^node_modules\/@earendil-works\/[^/]+$/.test(key))
+    .map(([key, entry]) => [key.replace(/^node_modules\//, ""), entry.version ?? ""] as const);
+  return Object.fromEntries(entries);
+};
+
+describe("pi dependency pins", () => {
+  test("the shrinkwrap read here belongs to the coding agent we publish", async () => {
+    const installed = await readJson<PackageJson>(`${piDir}/package.json`);
+    for (const file of publishedPackages) {
+      const { dependencies = {} } = await readJson<PackageJson>(`${repoRoot}/${file}`);
+      expect({ file, [piName]: dependencies[piName] }).toEqual({ file, [piName]: installed.version });
+    }
+  });
+
+  test("every sibling pi package is published at the version the coding agent shrinkwrapped", async () => {
+    const pins = await shrinkwrappedPins();
+    expect(Object.keys(pins).length).toBeGreaterThan(0);
+    for (const file of publishedPackages) {
+      const { dependencies = {} } = await readJson<PackageJson>(`${repoRoot}/${file}`);
+      const declared = Object.fromEntries(Object.keys(pins).map((name) => [name, dependencies[name]]));
+      expect({ file, ...declared }).toEqual({ file, ...pins });
+    }
+  });
+});

package/types.ts

@@ -10,6 +10,7 @@ export interface PackageJson {
   peerDependencies?: Record<string, string>;
   peerDependenciesMeta?: Record<string, { optional?: boolean }>;
   optionalDependencies?: Record<string, string>;
+  overrides?: Record<string, string>;
   engines?: Record<string, string>;
   exports?: Record<string, string | Record<string, string>>;
   bun?: {

package/codeAgent/agent/AkanAuthStorageBackend.ts

@@ -1,105 +0,0 @@
-import {
-  closeSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import path from "node:path";
-import type { AuthStorageBackend } from "@earendil-works/pi-coding-agent";
-
-/**
- * Credential store for `akan code`, in akan's own file rather than the engine's.
- *
- * The engine only asks for a locked read-modify-write over one opaque string, so satisfying its interface with
- * our own file keeps every key under `~/.akan/` — nothing lands in `~/.pi/` and a user who removes akan takes
- * their credentials with them.
- *
- * The lock is an exclusive-create sentinel rather than an advisory flock: two `akan code` processes refreshing
- * an OAuth token at the same moment would otherwise each write a token the other invalidates.
- */
-export class AkanAuthStorageBackend implements AuthStorageBackend {
-  readonly #authPath: string;
-  readonly #lockPath: string;
-
-  constructor(authPath: string) {
-    this.#authPath = authPath;
-    this.#lockPath = `${authPath}.lock`;
-  }
-
-  withLock<T>(fn: (current: string | undefined) => { result: T; next?: string }) {
-    this.#acquire();
-    try {
-      const { result, next } = fn(this.#read());
-      if (next !== undefined) this.#write(next);
-      return result;
-    } finally {
-      this.#release();
-    }
-  }
-
-  async withLockAsync<T>(fn: (current: string | undefined) => Promise<{ result: T; next?: string }>) {
-    this.#acquire();
-    try {
-      const { result, next } = await fn(this.#read());
-      if (next !== undefined) this.#write(next);
-      return result;
-    } finally {
-      this.#release();
-    }
-  }
-
-  #read() {
-    if (!existsSync(this.#authPath)) return undefined;
-    const text = readFileSync(this.#authPath, "utf8");
-    return text.trim() ? text : undefined;
-  }
-
-  #write(next: string) {
-    mkdirSync(path.dirname(this.#authPath), { recursive: true, mode: 0o700 });
-    const temp = `${this.#authPath}.${process.pid}.tmp`;
-    writeFileSync(temp, next, { mode: 0o600 });
-    renameSync(temp, this.#authPath);
-  }
-
-  #acquire() {
-    mkdirSync(path.dirname(this.#lockPath), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + 5_000;
-    for (;;) {
-      try {
-        closeSync(openSync(this.#lockPath, "wx"));
-        return;
-      } catch {
-        // A lock left behind by a killed process would block every later run, so it expires.
-        if (this.#lockIsStale() || Date.now() > deadline) {
-          try {
-            unlinkSync(this.#lockPath);
-          } catch {
-            // Another process won the race to clear it; retry the create.
-          }
-          continue;
-        }
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-      }
-    }
-  }
-
-  #lockIsStale() {
-    try {
-      return Date.now() - Bun.file(this.#lockPath).lastModified > 30_000;
-    } catch {
-      return true;
-    }
-  }
-
-  #release() {
-    try {
-      unlinkSync(this.#lockPath);
-    } catch {
-      // Already gone — a stale-lock sweep by another process.
-    }
-  }
-}