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

package/codeAgent/agent/codeMailbox.test.ts

@@ -33,15 +33,12 @@ describe("CodeMailbox", () => {
     one.send("bbbb2222", "the adapter moved to srvkit");
     await Bun.sleep(CodeMailbox.pollMs + 400);
     expect(got).toEqual(["the adapter moved to srvkit"]);
-    // The poll runs again; a message already handed over must not be handed over twice.
     await Bun.sleep(CodeMailbox.pollMs + 200);
     expect(got).toEqual(["the adapter moved to srvkit"]);
   });
 
-  /** What was already in the inbox belongs to an earlier run, which read it or never will. */
   test("a session opening on a full inbox does not replay it", async () => {
     const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
-    // Opened once to create the directories, then closed, then seeded the way a previous run would have.
     open(dir, "cccc3333", "seeded").close();
     const inbox = path.join(dir, "inbox", "cccc3333.jsonl");
     writeFileSync(inbox, `${JSON.stringify({ from: "x", fromName: "x", text: "old" })}\n`);
@@ -67,7 +64,6 @@ describe("CodeMailbox", () => {
     open(dir, "bbbb3333", "store-other");
     expect(one.find("store-work")?.id).toBe("bbbb2222");
     expect(one.find("bbbb2")?.id).toBe("bbbb2222");
-    // Two names starting with `store` — sending to the wrong session is worse than not sending.
     expect(one.find("store")).toBeUndefined();
   });
 

package/codeAgent/agent/codeSessionFork.test.ts

@@ -34,7 +34,6 @@ describe("CodeSessionFork", () => {
     const copied = records(forked.file);
     expect(copied.find((record) => record.type === "session")?.id).toBe(forked.id);
     expect(copied.filter((record) => record.type === "message").length).toBe(1);
-    // Two live agents sharing one id would share one inbox, one presence entry and one resume target.
     expect(CodeSessionIndex.fileOf(dir, forked.id)).toBe(forked.file);
     expect(CodeSessionIndex.fileOf(dir, id)).toBe(file);
   });
@@ -49,7 +48,6 @@ describe("CodeSessionFork", () => {
   test("the copy says it is one, and takes a name when given one", () => {
     const { dir, id } = seed();
     expect(records(CodeSessionFork.fork(dir, id).file).at(-1)?.name).toBe("read-the-guard-fork");
-    // A name somebody typed is kept as typed, the way `/name` keeps one; only a derived name is kebabed.
     expect(records(CodeSessionFork.fork(dir, id, "try the other guard").file).at(-1)?.name).toBe("try the other guard");
   });
 

package/codeAgent/agent/codeSessionIndex.test.ts

@@ -27,7 +27,6 @@ describe("CodeSessionIndex", () => {
       assistant("done"),
       user("now wire it up"),
       { type: "session_info", name: "add-a-comment-module" },
-      // A rename appends rather than editing, so the last entry has to win.
       { type: "session_info", name: "comment-module" },
     ]);
     const [entry] = CodeSessionIndex.list(dir);
@@ -45,11 +44,19 @@ describe("CodeSessionIndex", () => {
     expect(CodeSessionIndex.list(dir).map((entry) => entry.id)).toEqual(["s3"]);
   });
 
+  test("a session past the read limit is still listed, from its opening lines", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-sessions-"));
+    const filler = assistant("x".repeat(64 * 1024));
+    write(dir, "big", [session("big"), user("port the dashboard"), ...Array.from({ length: 10 }, () => filler)]);
+    const [entry] = CodeSessionIndex.list(dir);
+    expect(entry?.id).toBe("big");
+    expect(entry?.opening).toBe("port the dashboard");
+  });
+
   test("an id resolves to its file, and an unknown one to nothing", () => {
     const dir = mkdtempSync(path.join(tmpdir(), "akan-sessions-"));
     const file = write(dir, "s4", [session("s4"), user("hi")]);
     expect(CodeSessionIndex.fileOf(dir, "s4")).toBe(file);
-    // Resuming a typo has to fail rather than open a new session that looks like one that lost its history.
     expect(CodeSessionIndex.fileOf(dir, "s5")).toBeUndefined();
   });
 
@@ -61,12 +68,10 @@ describe("CodeSessionIndex", () => {
 describe("codeAgentSessionName", () => {
   test("names a session after what it was asked, in one glanceable line", () => {
     expect(codeAgentSessionName("Add a comment module to apps/minimal")).toBe("add-a-comment-module-to-apps-minimal");
-    // Cut on a word, never mid-word: half a word reads as a typo rather than a shortening.
     expect(codeAgentSessionName("Add a comment module to apps/minimal and wire up its dictionary")).toBe(
       "add-a-comment-module-to-apps-minimal-and",
     );
     expect(codeAgentSessionName("안녕, 모듈 하나 만들어줘")).toBe("안녕-모듈-하나-만들어줘");
-    // A prompt that is all code says nothing about itself; a name is still better than none.
     expect(codeAgentSessionName("```ts\nconst a = 1;\n```")).toBe("session");
   });
 });

package/codeAgent/agent/consoleToStderr.ts

@@ -1,17 +1,7 @@
 import { Console } from "node:console";
 
-/**
- * Sends every `console.*` call in this process to stderr, so stdout carries the RPC protocol and nothing else.
- *
- * The engine already installs a guard that rewrites `process.stdout.write`, which is enough on Node because
- * `console.log` routes through it there. Bun's global `console` is native and writes to fd 1 directly, so it
- * sails straight past that guard and corrupts the JSONL stream — measured: 203 non-JSON lines in one turn that
- * logged while a tool ran.
- *
- * **This is a side-effect module and must be the first import of any RPC entry.** An assignment written beside
- * the static imports would run *after* them: ESM hoists imports and evaluates those modules first, so anything
- * the engine logs at module-evaluation time would already have escaped.
- */
+// Bun's native `console` writes to fd 1 directly, past the engine's stdout guard, corrupting the RPC stream.
+// Must be the first import of an RPC entry: ESM evaluates imports first, so an inline assignment runs too late.
 globalThis.console = new Console({
   stdout: process.stderr,
   stderr: process.stderr,

package/codeAgent/agent/jsonLines.ts

@@ -0,0 +1,29 @@
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+
+const readHead = (file: string, maxBytes: number) => {
+  const fd = openSync(file, "r");
+  try {
+    const head = Buffer.alloc(maxBytes);
+    return head.subarray(0, readSync(fd, head, 0, maxBytes, 0)).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+};
+
+export const readJsonLines = (file: string, maxBytes?: number) => {
+  try {
+    const text =
+      maxBytes !== undefined && statSync(file).size > maxBytes ? readHead(file, maxBytes) : readFileSync(file, "utf8");
+    return text.split("\n").filter((line) => !!line.trim());
+  } catch {
+    return [];
+  }
+};
+
+export const parseJsonLine = <T>(line: string) => {
+  try {
+    return JSON.parse(line) as T;
+  } catch {
+    return undefined;
+  }
+};

package/codeAgent/agent/stringArg.ts

@@ -0,0 +1,5 @@
+export const stringArg = (args: unknown, key: "path" | "command") => {
+  if (!args || typeof args !== "object") return undefined;
+  const value = (args as Record<string, unknown>)[key];
+  return typeof value === "string" && value ? value : undefined;
+};

package/codeAgent/feedback/DevLogFeedback.ts

@@ -15,14 +15,7 @@ export interface DevLogFeedbackOptions {
 const errorPattern = /\bERROR\b|\bFATAL\b|\[stderr\]|error:|Error:|✖|Unhandled|Cannot find|is not a function/;
 const noisePattern = /DEBUG|\bWARN\b|MCP catalogue|rate limit/;
 
-/**
- * Feeds back what the dev server said after a turn edited code.
- *
- * `akan start` writes `local/apps/<app>/runtime/dev.log` with no ANSI, nothing truncated, and every process of
- * the app in arrival order including the dev host's own build output — which reaches no other file. That is the
- * one thing a coding agent working on an akan app has and a general one does not: lint and typecheck can both
- * pass on code that dies the moment it runs.
- */
+// dev.log is the only file carrying the dev host's own build output; lint and typecheck pass on code that dies at run.
 export class DevLogFeedback implements TurnFeedbackSource {
   readonly key = "dev-server";
   readonly #options: Required<DevLogFeedbackOptions>;
@@ -41,9 +34,7 @@ export class DevLogFeedback implements TurnFeedbackSource {
   async observe() {
     const running = this.#options.apps.filter((app) => existsSync(this.#pathOf(app)));
     if (!running.length) return undefined;
-    // A turn that wrote nothing cannot have broken the running app. Without this, one line from a dev server
-    // somebody else is driving reopens a turn that only read a file — and a reopened turn looks, from the
-    // transcript, exactly like an agent that will not stop.
+    // A turn that wrote nothing cannot have broken the app; without this gate another person's dev server reopens it.
     if (!(await AkanEditScope.since(this.#options.cwd, this.#baseline)).paths.length) return undefined;
     await Bun.sleep(this.#options.graceMs);
     const reports: string[] = [];
@@ -77,12 +68,7 @@ export class DevLogFeedback implements TurnFeedbackSource {
     return path.join(this.#options.workspaceRoot, "local", "apps", app, "runtime", "dev.log");
   }
 
-  /**
-   * The dev server's own URL, read back from the line `akan start` prints when the app comes up.
-   *
-   * The port is allocated, not predicted — a second checkout or a stale listener shifts it — so the log is the
-   * only place that knows which one this session actually got.
-   */
+  /** The port is allocated, not predicted, so the log's `ready` line is the only record of this session's URL. */
   static async previewUrl(workspaceRoot: string, app: string) {
     const file = path.join(workspaceRoot, "local", "apps", app, "runtime", "dev.log");
     if (!existsSync(file)) return undefined;
@@ -90,7 +76,6 @@ export class DevLogFeedback implements TurnFeedbackSource {
     return matches.at(-1)?.[1];
   }
 
-  /** A dev server that is not running has no log, which is not an error — the source simply reports nothing. */
   static #sizeOf(file: string) {
     return existsSync(file) ? statSync(file).size : 0;
   }

package/codeAgent/feedback/PreviewChrome.ts

@@ -2,13 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 
-/**
- * Which `Bun.WebView` backend the preview probe runs on, and what an image needs to carry one.
- *
- * `webkit` is the macOS system framework — zero install, and it throws on every other platform — so anywhere
- * else the probe drives Chrome. The generated akan image installs `ca-certificates` and `tzdata` and nothing
- * else, which is why the install steps are named here instead of being reinvented per image.
- */
+// Bun.WebView's `webkit` backend is the macOS system framework and throws on every other platform.
 export class PreviewChrome {
   /** Read by `Bun.WebView` itself; listed so the availability check agrees with what the launcher will do. */
   static readonly pathEnvKey = "BUN_CHROME_PATH";
@@ -27,12 +21,7 @@ export class PreviewChrome {
     "chrome",
   ];
 
-  /**
-   * macOS keeps browsers in app bundles, off PATH, and Bun looks inside these before reporting none.
-   *
-   * The list has to match Bun's or the two disagree in the expensive direction: refusing to probe on a machine
-   * whose browser the launcher would have found.
-   */
+  /** Must match the macOS app bundles Bun searches, or the probe refuses a browser the launcher would find. */
   static readonly appBundles = [
     "Google Chrome.app/Contents/MacOS/Google Chrome",
     "Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
@@ -67,29 +56,16 @@ export class PreviewChrome {
     return PreviewChrome.backend === "webkit" ? process.platform === "darwin" : !!PreviewChrome.executable();
   }
 
-  /**
-   * The `backend` value to construct a view with.
-   *
-   * Two flags are added on the Chrome path, and Bun adds neither:
-   * - Chromium refuses to run as uid 0 unless its sandbox is off, and uid 0 is the ordinary uid in a container.
-   * - Docker gives a container 64MB of `/dev/shm` by default, below what Chromium's renderer allocates, and the
-   *   crash it produces looks like a page that never loads rather than a resource limit.
-   */
   static backendOption() {
     if (PreviewChrome.backend === "webkit") return "webkit";
+    // Docker's default 64MB /dev/shm is below what Chromium's renderer allocates; the crash looks like a hung load.
     const argv = ["--disable-dev-shm-usage"];
+    // Chromium refuses uid 0 with its sandbox on, and uid 0 is the ordinary uid in a container.
     if (process.getuid?.() === 0) argv.push("--no-sandbox");
     return { type: "chrome" as const, argv };
   }
 
-  /**
-   * `RUN` bodies for an image whose agent has to look at the page it just changed — an akan app's
-   * `docker.preRuns`, or a coding-agent pod.
-   *
-   * The font packages are not decoration: a container with no fonts renders every glyph as a box, so a
-   * screenshot says nothing and the "text is the same colour as its background" probe reads a blank page.
-   * `fonts-noto-cjk` is what keeps a Korean UI legible.
-   */
+  /** The generated image has no browser or fonts; a fontless container renders every glyph as a box. */
   static readonly dockerRuns = [
     "apt-get update && apt-get install -y --no-install-recommends chromium fonts-liberation fonts-noto-color-emoji fonts-noto-cjk && rm -rf /var/lib/apt/lists/*",
   ];

package/codeAgent/feedback/PreviewFeedback.ts

@@ -8,18 +8,11 @@ export interface PreviewFeedbackOptions {
   previewUrl?: string;
   /** Every akan route sits under `/:lang`, so a bare path renders nothing. */
   routes?: string[];
-  /** Only a model whose input includes images gets one attached; a screenshot is ~83KB per shot. */
+  /** Only a model whose input includes images gets a screenshot attached. */
   canSeeImages?: boolean;
 }
 
-/**
- * Looks at the page after a turn changed the UI.
- *
- * akan is a UI framework, so "does it run" is half the question. The default findings are **text** — page
- * console errors, an empty body, an error overlay, horizontal overflow, a dropped colour slot — because they
- * cost a few hundred tokens, work with any model, and name the defect rather than depicting it. A screenshot is
- * attached only when the active model can actually read one.
- */
+// Findings are text, not screenshots: a few hundred tokens, readable by any model, and naming the defect.
 export class PreviewFeedback implements TurnFeedbackSource {
   readonly key = "preview";
   readonly #options: PreviewFeedbackOptions;

package/codeAgent/feedback/PreviewView.ts

@@ -18,22 +18,13 @@ interface WebViewLike {
   readonly title: string;
 }
 
-/**
- * Opens a page headlessly and reports what is wrong with it.
- *
- * `Bun.WebView` rather than a downloaded browser: on macOS the `webkit` backend is the system framework, so
- * there is no Chromium to fetch and no executable path to track, and everywhere else it drives whatever Chrome
- * the image carries. It is marked experimental, which is why the whole surface is behind this adapter — a Bun
- * minor that changes it should break one file.
- *
- * Which backend, and what an image needs for it, is {@link PreviewChrome}.
- */
+// Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
+// It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
 export class PreviewView {
   static get available() {
     return typeof (Bun as unknown as { WebView?: unknown }).WebView === "function" && PreviewChrome.available;
   }
 
-  /** Why `available` is false, for a host that should say so rather than skip the check in silence. */
   static unavailableReason() {
     if (typeof (Bun as unknown as { WebView?: unknown }).WebView !== "function")
       return "This Bun build has no WebView, so the page preview is off.";
@@ -76,10 +67,7 @@ export class PreviewView {
   }
 }
 
-/**
- * `evaluate` takes an expression, not a statement list — `const x = 1; x` is a `SyntaxError` — so each probe is
- * wrapped in an IIFE. Only one may be in flight per view.
- */
+// evaluate() takes one expression (a statement list is a SyntaxError), hence the IIFEs; one call in flight per view.
 const pageErrorsExpression = `(() => {
   const found = [];
   const root = document.getElementById("__next") || document.body;

package/codeAgent/feedback/TurnFeedback.ts

@@ -26,20 +26,8 @@ export interface TurnFeedbackOptions {
   onNotice?: (message: string) => void;
 }
 
-/**
- * Closes the loop between what a turn did and what the agent knows about it.
- *
- * The agent cannot see that the dev server died, that a generated barrel went stale, or that the page it built
- * renders blank — so it finishes, satisfied, on a broken tree. Each source watermarks at the start of a run and
- * reports at the end; a report is delivered as a follow-up message, which opens a new turn.
- *
- * **It is a follow-up, not a veto.** `agent_end` has no result type — of the engine's hooks only
- * `before_agent_start`, `message_end`, `tool_call`, `tool_result`, `input`, `user_bash`, the `session_before_*`
- * pair, `context` and `resources_discover` can change an outcome — so there is no way to refuse to end a turn.
- *
- * **The budget goes in before the feature.** A source that reports the same unfixable error every turn would
- * otherwise loop until the context window or the wallet runs out, and the loop looks like progress from outside.
- */
+// The engine's `agent_end` hook cannot veto the end of a turn, so a finding is a follow-up that opens a new one.
+// The budget is load-bearing: without it one unfixable error reopens turns until the context or the wallet runs out.
 export class TurnFeedback {
   readonly #sources: TurnFeedbackSource[];
   readonly #options: TurnFeedbackOptions;
@@ -65,7 +53,6 @@ export class TurnFeedback {
     };
   }
 
-  /** Exposed so a host can drive the same machine without an engine session behind it. */
   async collect() {
     const texts: string[] = [];
     const images: TurnFeedbackImage[] = [];
@@ -90,8 +77,6 @@ export class TurnFeedback {
       }
     }
     if (!texts.length) return undefined;
-    // Said out loud, because the turn that follows is one nobody asked for: the transcript shows more tool
-    // calls after the answer and carries nothing that names who sent the agent back to work.
     this.#options.onNotice?.(`${reopened.join(" · ")} reopened the turn — esc stops it`);
     const text = [
       "The previous turn left problems you cannot see from the transcript. Fix them, then stop.",

package/codeAgent/feedback/VerifyFeedback.ts

@@ -8,13 +8,7 @@ export interface VerifyFeedbackOptions {
   readOnly?: boolean;
 }
 
-/**
- * Runs the validation chain over whatever a turn changed and feeds the failures back.
- *
- * The model has a verification tool and the observed failure is that it finishes without calling it — so this
- * is not a second tool but a hook. Detection reads git rather than tool events, because an edit made through
- * `bash` produces no write tool call and is exactly the kind a model forgets to verify.
- */
+// A hook, not a reliance on the akan_verify tool: the observed failure is a model finishing without calling it.
 export class VerifyFeedback implements TurnFeedbackSource {
   readonly key = "verify";
   readonly #options: VerifyFeedbackOptions;

package/codeAgent/feedback/previewChrome.test.ts

@@ -67,7 +67,7 @@ describe("PreviewChrome", () => {
     const step = PreviewChrome.dockerRuns.join(" ");
     expect(step).toContain("chromium");
     expect(step).toContain("fonts-noto-cjk");
-    // Leaving the apt lists behind adds ~40MB to every layer of every image that takes this step.
+    // Leftover apt lists bloat every image layer that takes this step.
     expect(step).toContain("rm -rf /var/lib/apt/lists/*");
   });
 });

package/codeAgent/index.ts

@@ -1,13 +1,5 @@
-/**
- * The akan coding agent: the engine wrapper, the tools it is given, and the feedback that reopens a turn.
- *
- * Importing this barrel loads the engine, which costs ~122MiB resident. A host that only needs the cheap
- * pieces — the model reference, the stream printer, the sub-agent kinds — reaches for the owning module
- * instead (`@akanjs/devkit/codeAgent/agent/akanCodeModel`), the same way `@akanjs/devkit` itself asks to be
- * used. `agent/consoleToStderr` is deliberately absent: it is a side-effect module that takes over
- * `globalThis.console`, and it has to be the first import of an RPC entry rather than a re-export of this one.
- */
-
+// Importing this barrel loads the engine (~122MiB resident); a host needing cheap pieces imports the owning module.
+// agent/consoleToStderr is deliberately absent: it takes over globalThis.console, so an RPC entry imports it first.
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
 export * from "./agent/akanCodePaths";

package/codeAgent/skills/akan-code/SKILL.md

@@ -15,8 +15,9 @@ which command makes it take effect.
 
 ## MCP servers
 
-Declared in **`.akan/code/mcp.json`**, in the same `mcpServers` shape Claude, Cursor and VS Code already
-write, so a block can be pasted across rather than translated. VS Code's `servers` spelling is read too, and
+Declared in **`~/.akan/code/mcp.json`**, which every repo reads, or in this repo's **`.akan/code/mcp.json`**,
+which wins a name both declare — in the same `mcpServers` shape Claude, Cursor and VS Code already write, so a
+block can be pasted across rather than translated. VS Code's `servers` spelling is read too, and
 whichever key the file already uses is the one a write goes back into.
 
 ```jsonc
@@ -41,7 +42,9 @@ From the prompt:
 /mcp <name>               the tools that one server published
 /mcp add <name> <command> [args…]
 /mcp add <name> <https://…>
-/mcp remove <name>
+/mcp add --local <name> … this repo's file only, not ~/.akan/code/mcp.json
+/mcp remove <name>        this repo's file first, else ~/.akan/code/mcp.json
+/mcp remove --local <name>
 /mcp login <name>         OAuth, in the browser
 /mcp logout <name>        forget the token, leaving the server declared
 /mcp reload               reopen this session so the file takes effect
@@ -52,11 +55,16 @@ session is created, so `add`, `remove`, `login` and `logout` all reload by thems
 said nothing yet has nothing on disk to reopen, and says so. If you edit `mcp.json` yourself, tell the user to
 run `/mcp reload`.
 
+`/mcp remove` on a name both files declare takes this repo's entry and leaves the home file's in force; its
+notice says so, and running it again removes that one too.
+
 Sign-in is discovered, not configured: the server's `401` names its resource metadata, that names the
 authorization server, and most hosted servers register a client on demand — so a url is usually the whole
 entry. For a provider that issues client ids by hand, add `"oauth": { "clientId": "…", "scope": "…" }`.
 Tokens are stored per server in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, and refreshed
-silently; `/mcp` shows `sign-in needed` when a server wants one.
+silently — at connect when one has expired, and mid-session when a server refuses one, after which the call is
+retried once. When a refresh cannot fix it, `/mcp` shows `sign-in needed` and that server's tools answer with
+`/mcp login <name>` until the user signs in; the sign-in reloads the session, which brings the server back.
 
 ## Sessions
 

package/codeAgent/tools/AkanCli.ts

@@ -9,13 +9,7 @@ export interface AkanCliResult {
   output: string;
 }
 
-/**
- * Runs `akan` as a child process and captures what it printed.
- *
- * The runners behind these commands write straight to an inherited stdio and return nothing, so there is no
- * in-process call that yields text to hand back to a model. A subprocess also isolates a crash in a build or a
- * typechecker from the agent's own turn.
- */
+// A subprocess: the akan runners print to inherited stdio and return nothing; it also isolates their crashes.
 export class AkanCli {
   readonly #cwd: string;
   readonly #entry: string;
@@ -39,19 +33,13 @@ export class AkanCli {
       proc.exited,
     ]);
     clearTimeout(timer);
-    // `NO_COLOR` reaches akan's own output but not every tool it shells out to — tsgo colours regardless, and
-    // escape sequences in a tool result are tokens the model pays for and cannot read.
+    // tsgo colours regardless of NO_COLOR, and escape sequences are tokens the model pays for and cannot read.
     const output = stripAnsi(`${stdout}${stderr}`).trim();
     return { command: `akan ${args.join(" ")}`, ok: exitCode === 0, exitCode, output };
   }
 
-  /**
-   * Bundling rewrites `import.meta.dir` to the output directory, where devkit is inlined into the CLI and the
-   * entry is `index.js` beside this module; from source the entry belongs to the neighbouring package and is
-   * still TypeScript. `Bun.main` is the last resort and is only right when the CLI is the process — an SDK
-   * embedder's main is its own. The path is written out rather than resolved through the package name because
-   * devkit does not depend on the CLI, and must not start.
-   */
+  // Bundled, import.meta.dir is the CLI's output dir with index.js beside it; Bun.main fits only when the CLI is the
+  // process. The path is written out because devkit does not depend on the CLI, and must not start.
   static #resolveEntry() {
     const candidates = [
       path.join(import.meta.dir, "index.js"),

package/codeAgent/tools/AkanCodePlugins.ts

@@ -2,7 +2,7 @@ import type { InlineExtension } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentQuestion, CodeAgentSubagent } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import type { CodeMailbox } from "../agent/CodeMailbox";
-import { SubagentPool } from "../agent/SubagentPool";
+import { SubagentPool, type SubagentSpend } from "../agent/SubagentPool";
 import { DevLogFeedback } from "../feedback/DevLogFeedback";
 import { PreviewFeedback } from "../feedback/PreviewFeedback";
 import { PreviewView } from "../feedback/PreviewView";
@@ -24,6 +24,8 @@ export interface AkanCodePluginsOptions {
   canSeeImages: boolean;
   /** How many `task` levels deep the owning agent is. */
   depth: number;
+  /** The tally of the sub-agent tree the owning agent belongs to, when a `task` opened it. */
+  subagentSpend?: SubagentSpend;
   /** Reading the current session back would spend its own window twice, so it is excluded from search. */
   currentSessionId: () => string;
   /** Late, because the session this announces to its peers does not exist yet when the pack is built. */
@@ -34,12 +36,6 @@ export interface AkanCodePluginsOptions {
   onAsk?: (question: Omit<CodeAgentQuestion, "questionId">) => Promise<string | undefined>;
 }
 
-/**
- * Assembles the akan capability pack for one profile.
- *
- * Gating happens here rather than at run time: a capability the profile excludes is never constructed, so the
- * model cannot call it and it costs nothing in the system prompt either.
- */
 export interface AkanCodePluginsResult {
   extensions: InlineExtension[];
   /** Names the session's tool allowlist has to carry, or the model is told these tools do not exist. */
@@ -50,6 +46,7 @@ export interface AkanCodePluginsResult {
   dispose: () => void;
 }
 
+// Gated at assembly, not at call time: a capability the profile excludes is never built and costs no prompt tokens.
 export class AkanCodePlugins {
   static async build(options: AkanCodePluginsOptions): Promise<AkanCodePluginsResult> {
     const mcp = await McpToolPack.connect({
@@ -60,34 +57,28 @@ export class AkanCodePlugins {
     const dispose = () => mcp?.close();
     const mcpStatus = mcp?.status ?? [];
     const web = new WebToolPack({ profile: options.profile });
-    const webExtension = web.extension();
     const sessions = new SessionToolPack({
       workspaceRoot: options.workspace.workspaceRoot,
       cwd: options.cwd,
       profile: options.profile,
       currentSessionId: options.currentSessionId,
     });
-    const sessionExtension = sessions.extension();
     const mail = new MailToolPack({ profile: options.profile, mailbox: options.mailbox });
-    const mailExtension = mail.extension();
     const onAsk = options.onAsk;
     const ask = onAsk ? new AskToolPack({ profile: options.profile, ask: onAsk }) : undefined;
-    const askExtension = ask?.extension();
-    if (!options.profile.tools.akan)
-      return {
-        extensions: [mcp?.extension(), webExtension, sessionExtension, mailExtension, askExtension].filter(
-          (entry) => !!entry,
-        ),
-        toolNames: [
-          ...(mcp?.toolNames ?? []),
-          ...web.names(),
-          ...sessions.names(),
-          ...mail.names(),
-          ...(ask?.names() ?? []),
-        ],
-        mcp: mcpStatus,
-        dispose,
-      };
+    const shared = {
+      extensions: [mcp?.extension(), web.extension(), sessions.extension(), mail.extension(), ask?.extension()].filter(
+        (entry) => !!entry,
+      ),
+      toolNames: [
+        ...(mcp?.toolNames ?? []),
+        ...web.names(),
+        ...sessions.names(),
+        ...mail.names(),
+        ...(ask?.names() ?? []),
+      ],
+    };
+    if (!options.profile.tools.akan) return { ...shared, mcp: mcpStatus, dispose };
     const readOnly = !options.profile.tools.builtin.includes("write");
     const pack = new AkanToolPack({
       workspace: options.workspace,
@@ -100,6 +91,7 @@ export class AkanCodePlugins {
       cwd: options.cwd,
       parent: options.profile,
       depth: options.depth,
+      ...(options.subagentSpend ? { spend: options.subagentSpend } : {}),
       ...(options.onNotice ? { onNotice: options.onNotice } : {}),
       ...(options.onAgents ? { onAgents: options.onAgents } : {}),
     });
@@ -112,22 +104,9 @@ export class AkanCodePlugins {
           ...(options.onNotice ? { onNotice: options.onNotice } : {}),
         }).extension(),
       );
-    if (mcp) extensions.push(mcp.extension());
-    if (webExtension) extensions.push(webExtension);
-    if (sessionExtension) extensions.push(sessionExtension);
-    if (mailExtension) extensions.push(mailExtension);
-    if (askExtension) extensions.push(askExtension);
     return {
-      extensions,
-      toolNames: [
-        ...(await pack.names()),
-        ...(subagent ? [SubagentPool.toolName] : []),
-        ...(mcp?.toolNames ?? []),
-        ...web.names(),
-        ...sessions.names(),
-        ...mail.names(),
-        ...(ask?.names() ?? []),
-      ],
+      extensions: [...extensions, ...shared.extensions],
+      toolNames: [...(await pack.names()), ...(subagent ? [SubagentPool.toolName] : []), ...shared.toolNames],
       mcp: mcpStatus,
       dispose,
     };
@@ -140,8 +119,7 @@ export class AkanCodePlugins {
     ];
     const previewUrl = await AkanCodePlugins.#previewUrl(options);
     if (!previewUrl) return sources;
-    // A dev server is up and the agent still cannot look at the page. Said once, at assembly, because the
-    // alternative is a UI turn that quietly skips its only visual check and reads as a clean run.
+    // Said once here, or a UI turn silently skips its only visual check and reads as a clean run.
     const reason = PreviewView.unavailableReason();
     if (reason) options.onNotice?.(reason);
     else sources.push(new PreviewFeedback({ cwd: options.cwd, previewUrl, canSeeImages: options.canSeeImages }));

package/codeAgent/tools/AkanEditScope.ts

@@ -9,16 +9,10 @@ export interface AkanEditScopeResult {
 
 const empty: AkanEditScopeResult = { paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false };
 
-/**
- * What the working tree says changed, and which akan targets that implicates.
- *
- * Read from git rather than from tool events on purpose: a model that edits through `bash` — a heredoc, `sed`,
- * a codemod — produces no write tool call at all, and a verification gate that trusts tool events would wave
- * exactly those turns through.
- */
+// Read from git, not tool events: an edit made through `bash` (a heredoc, sed, a codemod) produces no write tool call.
 export class AkanEditScope {
   static async since(cwd: string, baseline: ReadonlySet<string>): Promise<AkanEditScopeResult> {
-    const current = await AkanEditScope.#status(cwd);
+    const current = await AkanEditScope.baseline(cwd);
     const changed = [...current].filter((line) => !baseline.has(line));
     if (!changed.length) return empty;
     const entries = changed.map((line) => ({ code: line.slice(0, 2), file: line.slice(3).split(" -> ").at(-1) ?? "" }));
@@ -34,10 +28,6 @@ export class AkanEditScope {
 
   /** The porcelain lines before a turn, so the turn is judged on what it changed rather than on a dirty tree. */
   static async baseline(cwd: string) {
-    return await AkanEditScope.#status(cwd);
-  }
-
-  static async #status(cwd: string) {
     const proc = Bun.spawn(["git", "status", "--porcelain=v1", "--untracked-files=all"], {
       cwd,
       stdout: "pipe",