@akanjs/devkit 3.0.0-alpha.88 → 3.0.0-alpha.89

package/DEV_RUNTIME_KNOBS.md

@@ -77,6 +77,33 @@ which is the one case where replacing it again cannot help; it says that too, an
 | `AKAN_MEMORY_LOG_INTERVAL_MS` | `60000` | How often that report is written. |
 | `AKAN_MEMORY_GC_ON_REPORT` | off | `=1` forces a GC before each report, so the number is retained memory rather than garbage. Costs a full GC per report. |
 
+## Several apps at once
+
+`akan start a,b` runs one dev host per app under a supervisor, so **every number above multiplies by the number
+of apps** — there is no shared builder and no shared RSC worker. Measured on this repo, right after both apps
+finished booting:
+
+| process | akan | minimal |
+|---|---|---|
+| dev host | 101MB | 94MB |
+| incremental builder | 596MB | 532MB |
+| backend | 35MB | 38MB |
+| RSC worker | 190MB | 81MB |
+
+Plus ~51MB for the supervisor itself: **~1.7GB for two apps at their peak.** The builders are almost all of
+that, and they are also the part that goes away — `AKAN_DEV_IDLE_SUSPEND_MS` releases each one independently, so
+a session where you are editing one app settles to roughly one builder plus ~190MB per idle app. **Multi-app is
+sized against idle suspend being on**; setting it to `0` keeps every builder resident for the whole session.
+
+Two things bound the peak rather than the floor:
+
+- **`--concurrency` (default 1).** Apps boot in waves, and the next wave starts only once the previous one
+  reports ready. A cold boot build is the builder's peak, so booting `n` apps at once means `n` overlapping
+  peaks — which is what OOM-kills a container that would have been fine with them staggered.
+- **`AKAN_MEMORY_LIMIT` is per process, not per session.** Each dev host derives its builder and RSC-worker
+  ceilings from it independently, so a limit sized for one app does not become a budget for four. Divide it
+  yourself, or leave it unset on a laptop.
+
 ## Sizing a small sandbox
 
 A worked example, for a 1.2GB container:

package/akanApp/akanApp.host.ts

@@ -7,7 +7,7 @@ import { WorkspaceExecutor } from "../executors";
 // tailwind stack, which is exactly what a suspended dev host must not be holding.
 import { HmrWatcher } from "../frontendBuild/hmrWatcher";
 import { WatchRootResolver } from "../frontendBuild/watchRootResolver";
-import { IncrementalBuilderHost } from "../incrementalBuilder";
+import { type DevStdioMode, IncrementalBuilderHost } from "../incrementalBuilder";
 import { BuilderRequestRouter } from "../incrementalBuilder/builderRequestRouter";
 import { BackendImportGraph } from "./BackendImportGraph";
 import {
@@ -17,9 +17,12 @@ import {
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
+  type DevHostEvent,
+  type DevHostState,
   decideBuilderRssRecycle,
   decideBuilderRssSettle,
   decideIdleSuspend,
+  devHostStateOf,
   filesChangedSince,
   hasAnyBuildFailure,
   hasBuildFailureForGeneration,
@@ -89,9 +92,11 @@ interface LastGoodFrontendState {
 
 export class AkanAppHost {
   logger = new Logger("AkanAppHost");
-  readonly withInk: boolean;
+  readonly stdio: DevStdioMode;
   readonly env: Record<string, string>;
-  #backend: Bun.Subprocess<"ignore", "inherit", "inherit"> | null = null;
+  readonly #onDevEvent: ((event: DevHostEvent) => void) | null;
+  #lastDevState: DevHostState | null = null;
+  #backend: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #builder: IncrementalBuilderHost | null = null;
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
@@ -134,12 +139,22 @@ export class AkanAppHost {
   readonly #builderRequests = new BuilderRequestRouter();
   constructor(
     private readonly app: App,
-    { env, withInk = false }: { env: Record<string, string>; withInk?: boolean },
+    {
+      env,
+      stdio = "inherit",
+      onDevEvent,
+    }: { env: Record<string, string>; stdio?: DevStdioMode; onDevEvent?: (event: DevHostEvent) => void },
   ) {
     this.env = env;
-    this.withInk = withInk;
+    this.stdio = stdio;
+    this.#onDevEvent = onDevEvent ?? null;
     this.#backendGraph = new BackendImportGraph(app, this.logger);
   }
+  #emitDevEvent(state: DevHostState, detail?: string) {
+    if (!this.#onDevEvent || state === this.#lastDevState) return;
+    this.#lastDevState = state;
+    this.#onDevEvent({ app: this.app.name, state, ...(detail ? { detail } : {}) });
+  }
   async start() {
     if (this.#backend) await this.#stopBackend();
     if (this.#builder) this.#stopBuilder();
@@ -195,7 +210,7 @@ export class AkanAppHost {
     this.#backendStderrTail = [];
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
-      stdio: this.withInk ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
+      stdio: this.stdio === "pipe" ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
       env: this.env,
       ipc: (msg: BuilderMessage) => {
         if (!msg || typeof msg !== "object") return;
@@ -235,9 +250,9 @@ export class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
-    if (this.withInk) {
-      // Ink mode pipes backend stdio to keep the TUI clean; drain the pipes and surface
-      // them through the logger so runtime errors are not silently swallowed.
+    if (this.stdio === "pipe") {
+      // A piped backend writes to nobody unless the pipes are drained; surface them through the logger
+      // so a runtime error is not silently swallowed, and so the tail kept for a boot failure still fills.
       void this.#forwardBackendStream(backend.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
       void this.#forwardBackendStream(backend.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
     }
@@ -250,19 +265,23 @@ export class AkanAppHost {
       this.#backendStderrTail.splice(0, this.#backendStderrTail.length - BACKEND_STDERR_TAIL_LIMIT);
     }
   }
+  /**
+   * A piped child is written through verbatim rather than re-logged: a level floor here would swallow
+   * what the runtime printed, and re-rendering would double the timestamp the child already wrote. So
+   * `"pipe"` looks exactly like `"inherit"` to whoever owns this process's stdout — the only difference
+   * is `#backendStderrTail`, which is what the crash-loop diagnostic reads.
+   */
   async #forwardBackendStream(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
     if (!stream) return;
     const decoder = new TextDecoder();
     try {
       for await (const chunk of stream) {
         const text = decoder.decode(chunk, { stream: true });
-        if (!text.trim()) continue;
+        if (!text) continue;
         if (kind === "stderr") {
           this.#recordBackendStderr(text);
-          this.logger.warn(`[backend] ${text.trimEnd()}`);
-        } else {
-          this.logger.verbose(`[backend] ${text.trimEnd()}`);
-        }
+          process.stderr.write(text);
+        } else process.stdout.write(text);
       }
     } catch {
       // The stream closes when the backend exits; nothing further to surface here.
@@ -315,6 +334,7 @@ export class AkanAppHost {
     const prev = this.#backendLifecycleState;
     this.#backendLifecycleState = next;
     this.logger.verbose(`[backend-lifecycle] ${prev} -> ${next}${detail ? ` ${detail}` : ""}`);
+    this.#emitDevEvent(devHostStateOf(next, this.#backendGaveUp), detail);
   }
   #sendToBackend(message: BuilderMessage) {
     if (!this.#backend || !this.#backendReady) {
@@ -695,6 +715,7 @@ export class AkanAppHost {
       return;
     }
     this.#suspended = true;
+    this.#emitDevEvent("suspended", `idle ${Math.round(idleMs / 1000)}s`);
     this.#stopBuilder();
     this.#openBuilderGap("idle suspend");
     this.logger.info(
@@ -779,6 +800,9 @@ export class AkanAppHost {
       this.#wokeAtMono = performance.now();
       this.#flushPendingBuilderMessages();
       this.#armIdleSuspend();
+      // A wake often leaves the backend's own state untouched, so nothing else would report that the
+      // app came back and a supervisor would show it suspended for the rest of the session.
+      this.#emitDevEvent(devHostStateOf(this.#backendLifecycleState, this.#backendGaveUp));
     }
   }
   async #applyIdleWake(batch: ChangeBatch | null): Promise<void> {
@@ -1221,9 +1245,17 @@ export class AkanAppHost {
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
     for (let attempt = 1; attempt <= BUILDER_START_MAX_ATTEMPTS; attempt++) {
-      this.#builder = await IncrementalBuilderHost.create(this.app, this.env, (msg) => {
-        this.#enqueueBuilderMessage(msg);
-      });
+      this.#builder = await IncrementalBuilderHost.create(
+        this.app,
+        this.env,
+        (msg) => {
+          this.#enqueueBuilderMessage(msg);
+        },
+        {
+          stdio: this.stdio,
+          onOutput: (kind, text) => void (kind === "stderr" ? process.stderr : process.stdout).write(text),
+        },
+      );
       try {
         await this.#waitForBuilderReady(attempt, { announceBootState });
         this.app.verbose(`[cli] base build ready in ${Date.now() - startTime}ms — starting backend`);

package/akanApp/devHostPolicy.ts

@@ -69,6 +69,36 @@ export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, {
 
 export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
 
+/**
+ * What a dev host tells a supervising process about itself. Reported rather than scraped: the parent
+ * gets one pipe of interleaved child output, in which "this app is up" is indistinguishable from a line
+ * that merely mentions it.
+ */
+export type DevHostState = "starting" | "ready" | "restarting" | "recovering" | "suspended" | "failed" | "stopped";
+
+export interface DevHostEvent {
+  app: string;
+  state: DevHostState;
+  detail?: string;
+}
+
+const devHostStateByBackendState = {
+  starting: "starting",
+  ready: "ready",
+  "restart-pending": "restarting",
+  recovering: "recovering",
+  stopping: "stopped",
+  stopped: "stopped",
+} as const satisfies { [key in BackendLifecycleState]: DevHostState };
+
+/**
+ * The backend's own lifecycle collapsed to what a supervisor can act on. `stopped` is the one state
+ * that is ambiguous on its own — a planned shutdown and a crash loop that ran out of retries both land
+ * there — so the give-up flag is what separates "gone" from "broken".
+ */
+export const devHostStateOf = (state: BackendLifecycleState, gaveUp: boolean): DevHostState =>
+  state === "stopped" && gaveUp ? "failed" : devHostStateByBackendState[state];
+
 export interface BackendRestartReason {
   generation?: number;
   files: string[];

package/akanConfig/akanConfig.ts

@@ -2,12 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AkanPlugin } from "akanjs";
+import { normalizeRoutePrefix } from "akanjs/base";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";
 import type { BaseDevEnv, PackageJson } from "../types";
 import {
+  type AkanApiConfig,
   type AkanAssetsConfig,
   type AkanMobileConfig,
   type AkanMobileTargetConfig,
@@ -216,6 +218,7 @@ export class AkanAppConfig implements AppConfigResult {
   optimizeImports: string[];
   images: AkanImageConfig;
   i18n: AkanI18nConfig;
+  api: AkanApiConfig;
   publicEnv: string[];
   mobile: AkanMobileConfig;
   /** True only when the app's akan.config.ts explicitly declares a `mobile` section (vs. the synthesized default). */
@@ -260,6 +263,12 @@ export class AkanAppConfig implements AppConfigResult {
     this.i18n = resolveAkanI18nConfig(config?.i18n);
     process.env.AKAN_PUBLIC_DEFAULT_LOCALE = this.i18n.defaultLocale;
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
+    this.api = {
+      prefix: normalizeRoutePrefix(config?.api?.prefix) ?? "/api",
+      websocketPrefix: normalizeRoutePrefix(config?.api?.websocketPrefix) ?? "/ws",
+    };
+    process.env.AKAN_PUBLIC_API_PREFIX = this.api.prefix;
+    process.env.AKAN_PUBLIC_WS_PREFIX = this.api.websocketPrefix;
     this.publicEnv = (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
     this.secrets = (config?.secrets as string[] | undefined) ?? ([] as string[]);
     this.assets = {
@@ -446,6 +455,8 @@ ENV AKAN_PUBLIC_ENV=${this.baseDevEnv.env}
 ${this.basePaths.size ? `ENV AKAN_PUBLIC_BASE_PATHS=${[...this.basePaths].join(",")}` : ""}
 ENV AKAN_PUBLIC_DEFAULT_LOCALE=${this.i18n.defaultLocale}
 ENV AKAN_PUBLIC_LOCALES=${this.i18n.locales.join(",")}
+ENV AKAN_PUBLIC_API_PREFIX=${this.api.prefix}
+ENV AKAN_PUBLIC_WS_PREFIX=${this.api.websocketPrefix}
 ENV AKAN_PUBLIC_OPERATION_MODE=cloud
 ENV AKAN_LOG_TO_FILE=0
 ${webEnvLines}

package/akanConfig/types.ts

@@ -1,4 +1,5 @@
 export type {
+  AkanApiConfig,
   AkanAssetsConfig,
   AkanConfigFile,
   AkanExecutor,

package/appSelectionMemory.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { FileSys } from "./fileSys";
+
+interface StoredSelection {
+  apps: string[];
+}
+
+/**
+ * The apps the last interactive pick chose, so `akan start` + Enter repeats a multi-app session instead
+ * of re-ticking it. Advisory only: a missing, unreadable or stale file just means nothing is pre-ticked.
+ */
+export class AppSelectionMemory {
+  static pathIn(workspaceRoot: string) {
+    return path.join(workspaceRoot, "local", ".akan", "lastStart.json");
+  }
+  static async read(workspaceRoot: string): Promise<string[]> {
+    const stored = await Bun.file(AppSelectionMemory.pathIn(workspaceRoot))
+      .json()
+      .catch(() => null);
+    const apps = (stored as StoredSelection | null)?.apps;
+    return Array.isArray(apps) ? apps.filter((name): name is string => typeof name === "string") : [];
+  }
+  static async write(workspaceRoot: string, apps: string[]) {
+    await FileSys.writeJson(AppSelectionMemory.pathIn(workspaceRoot), { apps } satisfies StoredSelection).catch(
+      () => undefined,
+    );
+  }
+}

package/codegenLock.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodegenLock } from "./codegenLock";
+
+const roots: string[] = [];
+const makeRoot = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "akan-codegen-lock-"));
+  roots.push(root);
+  return root;
+};
+const seedHolder = async (root: string, holder: unknown) => {
+  const lockPath = CodegenLock.pathIn(root);
+  await Bun.write(lockPath, typeof holder === "string" ? holder : JSON.stringify(holder));
+  return lockPath;
+};
+/** A pid that cannot be alive: `kill(0)` on it is ESRCH on every platform this runs on. */
+const deadPid = 0x7ffffff;
+
+afterEach(async () => {
+  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true });
+});
+
+describe("CodegenLock", () => {
+  test("serializes concurrent callers in the same process", async () => {
+    const root = await makeRoot();
+    const order: string[] = [];
+    const body = async (name: string) => {
+      order.push(`${name}:in`);
+      await Bun.sleep(20);
+      order.push(`${name}:out`);
+    };
+    await Promise.all([
+      CodegenLock.run(root, "a", () => body("a")),
+      CodegenLock.run(root, "b", () => body("b")),
+      CodegenLock.run(root, "c", () => body("c")),
+    ]);
+    for (const name of ["a", "b", "c"]) {
+      const enter = order.indexOf(`${name}:in`);
+      const leave = order.indexOf(`${name}:out`);
+      expect(leave).toBe(enter + 1);
+    }
+  });
+
+  test("releases the lock file even when the body throws", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    await expect(
+      CodegenLock.run(root, "boom", async () => {
+        expect(await Bun.file(lockPath).exists()).toBe(true);
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+    expect(await Bun.file(lockPath).exists()).toBe(false);
+  });
+
+  test("writes a holder naming this process", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    const holder = await CodegenLock.run(root, "scan:minimal", async () => await readFile(lockPath, "utf8"));
+    expect(JSON.parse(holder)).toMatchObject({ pid: process.pid, label: "scan:minimal" });
+  });
+
+  test("reclaims a lock whose holder is gone", async () => {
+    const root = await makeRoot();
+    const lockPath = await seedHolder(root, { pid: deadPid, at: Date.now(), label: "crashed" });
+    const started = Date.now();
+    const holder = await CodegenLock.run(root, "next", async () => await readFile(lockPath, "utf8"));
+    expect(JSON.parse(holder).pid).toBe(process.pid);
+    expect(Date.now() - started).toBeLessThan(CodegenLock.waitTimeoutMs);
+  });
+
+  test("respects a live holder until the wait expires, then proceeds without the lock", async () => {
+    const root = await makeRoot();
+    const lockPath = await seedHolder(root, { pid: process.pid, at: Date.now(), label: "other-session" });
+    const waitTimeoutMs = CodegenLock.waitTimeoutMs;
+    Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: 150, configurable: true });
+    try {
+      let ran = false;
+      await CodegenLock.run(root, "blocked", async () => {
+        ran = true;
+        // The foreign holder is left in place: nothing may delete a lock it does not hold.
+        expect(JSON.parse(await readFile(lockPath, "utf8")).label).toBe("other-session");
+      });
+      expect(ran).toBe(true);
+      expect(await Bun.file(lockPath).exists()).toBe(true);
+    } finally {
+      Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+    }
+  });
+
+  test("keeps a young unreadable lock but reclaims a stale one", async () => {
+    const young = await makeRoot();
+    await seedHolder(young, "");
+    const waitTimeoutMs = CodegenLock.waitTimeoutMs;
+    Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: 150, configurable: true });
+    try {
+      await CodegenLock.run(young, "young", async () => undefined);
+      expect(await Bun.file(CodegenLock.pathIn(young)).exists()).toBe(true);
+    } finally {
+      Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+    }
+
+    const stale = await makeRoot();
+    const stalePath = await seedHolder(stale, "");
+    const aged = new Date(Date.now() - CodegenLock.unknownHolderStaleMs - 1_000);
+    await utimes(stalePath, aged, aged);
+    const holder = await CodegenLock.run(stale, "stale", async () => await readFile(stalePath, "utf8"));
+    expect(JSON.parse(holder).pid).toBe(process.pid);
+  });
+
+  test("blocks a second process for as long as it holds the lock", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    const script = path.join(root, "holder.ts");
+    await writeFile(
+      script,
+      `import { CodegenLock } from ${JSON.stringify(path.resolve(import.meta.dir, "codegenLock.ts"))};
+await CodegenLock.run(${JSON.stringify(root)}, "child", async () => {
+  process.stdout.write("held\\n");
+  await Bun.sleep(400);
+});
+`,
+    );
+    const child = Bun.spawn(["bun", script], { stdio: ["ignore", "pipe", "inherit"] });
+    const reader = child.stdout.getReader();
+    await reader.read();
+    reader.releaseLock();
+
+    const started = Date.now();
+    await CodegenLock.run(root, "parent", async () => undefined);
+    expect(Date.now() - started).toBeGreaterThan(100);
+    await child.exited;
+    expect(await stat(lockPath).catch(() => null)).toBeNull();
+  });
+});

package/codegenLock.ts

@@ -0,0 +1,136 @@
+import { mkdir, open, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+
+interface LockHolder {
+  pid: number;
+  at: number;
+  label: string;
+}
+
+/**
+ * A workspace-wide mutex over the generated source files every dev server in the workspace rewrites.
+ *
+ * `WatchRootResolver` narrows the `apps/` container to one app but keeps `libs/` whole on purpose, so
+ * with two dev servers up a save under `libs/` reaches both builders and both regenerate the same
+ * barrel. Whichever watcher is mid-scan then reads a half-written file back as a user edit, which is a
+ * rebuild per rewrite. `scanSync` writes the same files at boot for every mounting app.
+ *
+ * A wait that expires proceeds *without* the lock rather than failing: this sits on the dev server's
+ * hot path, and stalling the file watcher is worse than the torn read `FileSys.writeTextAtomic` already
+ * prevents on its own.
+ */
+export class CodegenLock {
+  static readonly fileName = "codegen.lock";
+  static readonly waitTimeoutMs = 10_000;
+  /**
+   * How long an unreadable lock file is respected. It covers the window between the exclusive create
+   * and the holder write, where the file exists but names no pid yet — a young one is somebody else
+   * mid-acquire, not a corpse.
+   */
+  static readonly unknownHolderStaleMs = 60_000;
+  static readonly #pollMs = 25;
+  static readonly #logger = new Logger("CodegenLock");
+  /** Serializes callers inside this process, which one `O_EXCL` file cannot tell apart. */
+  static #queue: Promise<void> = Promise.resolve();
+
+  static pathIn(workspaceRoot: string) {
+    return path.join(workspaceRoot, "local", ".akan", CodegenLock.fileName);
+  }
+
+  static async run<T>(workspaceRoot: string, label: string, fn: () => Promise<T>): Promise<T> {
+    const ahead = CodegenLock.#queue;
+    let done!: () => void;
+    CodegenLock.#queue = new Promise<void>((resolve) => {
+      done = resolve;
+    });
+    try {
+      await CodegenLock.#waitForQueue(ahead, label);
+      return await CodegenLock.#withFileLock(workspaceRoot, label, fn);
+    } finally {
+      done();
+    }
+  }
+
+  static async #waitForQueue(ahead: Promise<void>, label: string) {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const expired = new Promise<"expired">((resolve) => {
+      timer = setTimeout(() => resolve("expired"), CodegenLock.waitTimeoutMs);
+    });
+    try {
+      if ((await Promise.race([ahead.then(() => "done" as const), expired])) === "expired")
+        CodegenLock.#logger.warn(
+          `codegen lock queued past ${CodegenLock.waitTimeoutMs}ms in this process; continuing without waiting (${label})`,
+        );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  static async #withFileLock<T>(workspaceRoot: string, label: string, fn: () => Promise<T>): Promise<T> {
+    const lockPath = CodegenLock.pathIn(workspaceRoot);
+    await mkdir(path.dirname(lockPath), { recursive: true }).catch(() => undefined);
+    const held = await CodegenLock.#acquire(lockPath, label);
+    try {
+      return await fn();
+    } finally {
+      if (held) await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  static async #acquire(lockPath: string, label: string): Promise<boolean> {
+    const deadline = Date.now() + CodegenLock.waitTimeoutMs;
+    for (;;) {
+      const handle = await open(lockPath, "wx").catch(() => null);
+      if (handle) {
+        await handle
+          .writeFile(JSON.stringify({ pid: process.pid, at: Date.now(), label } satisfies LockHolder))
+          .catch(() => undefined);
+        await handle.close().catch(() => undefined);
+        return true;
+      }
+      if (await CodegenLock.#reclaimIfAbandoned(lockPath)) continue;
+      if (Date.now() >= deadline) {
+        CodegenLock.#logger.warn(
+          `codegen lock at ${lockPath} held past ${CodegenLock.waitTimeoutMs}ms; continuing without it (${label})`,
+        );
+        return false;
+      }
+      await Bun.sleep(CodegenLock.#pollMs);
+    }
+  }
+
+  /** A live holder is never reclaimed — the wait timeout is what bounds a pathologically slow one. */
+  static async #reclaimIfAbandoned(lockPath: string): Promise<boolean> {
+    const info = await stat(lockPath).catch(() => null);
+    if (!info) return true;
+    const holder = CodegenLock.#parseHolder(await readFile(lockPath, "utf8").catch(() => ""));
+    if (holder) {
+      if (CodegenLock.#isAlive(holder.pid)) return false;
+    } else if (Date.now() - info.mtimeMs < CodegenLock.unknownHolderStaleMs) return false;
+    await rm(lockPath, { force: true }).catch(() => undefined);
+    return true;
+  }
+
+  static #parseHolder(raw: string): LockHolder | null {
+    try {
+      const parsed = JSON.parse(raw) as Partial<LockHolder>;
+      if (typeof parsed.pid !== "number" || typeof parsed.at !== "number") return null;
+      return { pid: parsed.pid, at: parsed.at, label: typeof parsed.label === "string" ? parsed.label : "" };
+    } catch {
+      // A truncated holder file names no pid, so it is aged by mtime instead.
+      return null;
+    }
+  }
+
+  static #isAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM is a pid that exists under another user, which still holds the lock.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  }
+}

package/commandDecorators/argMeta.ts

@@ -12,7 +12,7 @@ import { COMMAND_META, type CommandCls } from "./targetMeta";
 export const argTypes = ["Argument", "Option"] as const;
 export type ArgType = (typeof argTypes)[number];
 
-export const internalArgTypes = ["Workspace", "App", "Lib", "Sys", "Pkg", "Module", "Exec"] as const;
+export const internalArgTypes = ["Workspace", "App", "Apps", "Lib", "Sys", "Pkg", "Module", "Exec"] as const;
 export type InternalArgType = (typeof internalArgTypes)[number];
 
 export type PrimitiveArgType = StringConstructor | NumberConstructor | BooleanConstructor;
@@ -83,6 +83,14 @@ export const normalizePrimitiveArgType = (type: PrimitiveArgType): NormalizedPri
 export const App = createInternalArgToken<AppExecutor, "App">("App");
 export type App = AppExecutor;
 
+/**
+ * One or more apps, from a variadic positional (`akan start a b`, `akan start a,b`, `akan start all`)
+ * or a checkbox when none is named. Reach for it only where running several is meaningful — every other
+ * command takes `App`, whose single-select is unchanged.
+ */
+export const Apps = createInternalArgToken<AppExecutor[], "Apps">("Apps");
+export type Apps = AppExecutor[];
+
 export const Lib = createInternalArgToken<LibExecutor, "Lib">("Lib");
 export type Lib = LibExecutor;