@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.21

package/mobile/nativeWebDir.ts

@@ -0,0 +1,62 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import type { AkanMobileTargetConfig } from "akanjs";
+
+export interface NativeWebDirSources {
+  /** The target's CSR bundle: one HTML file with its scripts and styles inlined. */
+  html: string;
+  /** The build's own copy of `public/`, already pruned of fonts nothing reads. */
+  publicDir?: string;
+  /** Subset fonts, served from `/_akan/fonts` as the page's `<FontFace>` names them. */
+  fontsDir?: string;
+}
+
+export class NativeWebDir {
+  //* The runtime serves its bridge from this prefix and refuses a web root that has one of its own.
+  static readonly reservedEntry = "__akan_native";
+
+  constructor(readonly dir: string) {}
+
+  //* The bundle is inlined into this page and its own code names the global, so only the tag marks an injection;
+  //* it goes first in <head>, ahead of every script, because the page reads it as it boots.
+  static injectTarget(html: string, target: Pick<AkanMobileTargetConfig, "name" | "basePath" | "indexPath">) {
+    if (html.includes(NativeWebDir.#targetTag)) return html;
+    const basePath = target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
+    const script = `${NativeWebDir.#targetTag}${JSON.stringify({
+      name: target.name,
+      basePath,
+      indexPath: target.indexPath,
+    })};</script>`;
+    const head = /<head(?:\s[^>]*)?>/i.exec(html);
+    if (!head) return `${script}\n${html}`;
+    const at = head.index + head[0].length;
+    return `${html.slice(0, at)}\n${script}${html.slice(at)}`;
+  }
+  static readonly #targetTag = "<script>window.__AKAN_MOBILE_TARGET__=";
+
+  /** Rebuilds the folder from scratch and answers its files as web paths: relative, `/`-separated and sorted. */
+  async assemble(target: AkanMobileTargetConfig, { html, publicDir, fontsDir }: NativeWebDirSources) {
+    if (!(await Bun.file(html).exists()))
+      throw new Error(`CSR html for mobile target '${target.name}' not found: ${html}`);
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+    if (publicDir && (await NativeWebDir.#isDir(publicDir))) await cp(publicDir, this.dir, { recursive: true });
+    if (fontsDir && (await NativeWebDir.#isDir(fontsDir)))
+      await cp(fontsDir, path.join(this.dir, "_akan", "fonts"), { recursive: true });
+    if (await NativeWebDir.#isDir(path.join(this.dir, NativeWebDir.reservedEntry)))
+      throw new Error(`public/${NativeWebDir.reservedEntry} is reserved for the native runtime.`);
+    await Bun.write(path.join(this.dir, "index.html"), NativeWebDir.injectTarget(await Bun.file(html).text(), target));
+    const files = await Array.fromAsync(new Bun.Glob("**/*").scan({ cwd: this.dir, onlyFiles: true, dot: true }));
+    //? Bun.Glob answers with the platform's separator, so a Windows scan reads `_akan\fonts\…`.
+    return files.map((file) => file.split(path.sep).join("/")).sort();
+  }
+
+  static async #isDir(dir: string) {
+    try {
+      return (await stat(dir)).isDirectory();
+    } catch {
+      // A missing folder is a source the build did not produce, not an error.
+      return false;
+    }
+  }
+}

package/mobile/placeholderAppId.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test";
+import { isPlaceholderAppId } from "./placeholderAppId";
+
+describe("isPlaceholderAppId", () => {
+  test("flags placeholder bundle identifiers that Apple's portal already claims", () => {
+    for (const appId of ["com.myapp.app", "com.myorg.myapp", "com.example.foo", "com.changeme.app", ""]) {
+      expect(isPlaceholderAppId(appId)).toBe(true);
+    }
+    for (const appId of ["com.minimal.app", "com.nearthlab.leadingflight", "io.akanjs.demo"]) {
+      expect(isPlaceholderAppId(appId)).toBe(false);
+    }
+  });
+});

package/mobile/placeholderAppId.ts

@@ -0,0 +1,16 @@
+// Placeholder bundle IDs are already claimed on Apple's portal, so device signing fails with "cannot be registered
+// to your development team".
+export const PLACEHOLDER_APP_IDS = [
+  "com.myapp.app",
+  "com.myorg.myapp",
+  "com.example.app",
+  "com.example.myapp",
+] as const;
+const placeholderAppIdSegment = /^(example|examples|myorg|myapp|mycompany|myorganization|changeme|todo|sample|test)$/;
+
+export const isPlaceholderAppId = (appId: string | null | undefined): boolean => {
+  const normalized = appId?.trim().toLowerCase() ?? "";
+  if (!normalized) return true;
+  if ((PLACEHOLDER_APP_IDS as readonly string[]).includes(normalized)) return true;
+  return normalized.split(".").some((segment) => placeholderAppIdSegment.test(segment));
+};

package/mobile/usageDescriptions.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
+
+describe("toIosInfoPlistUsageDescriptions", () => {
+  test("writes Apple's real Info.plist keys, not NS + the description name", () => {
+    expect(
+      toIosInfoPlistUsageDescriptions({
+        cameraUsageDescription: "camera",
+        photoAddUsageDescription: "add",
+        photoUsageDescription: "read",
+        locationAlwaysUsageDescription: "always",
+      }),
+    ).toEqual({
+      NSCameraUsageDescription: "camera",
+      NSPhotoLibraryAddUsageDescription: "add",
+      NSPhotoLibraryUsageDescription: "read",
+      NSLocationAlwaysAndWhenInUseUsageDescription: "always",
+      NSLocationAlwaysUsageDescription: "always",
+    });
+  });
+
+  test("keeps the NS prefix convention for a key it does not know", () => {
+    expect(toIosInfoPlistUsageDescriptions({ bluetoothAlwaysUsageDescription: "ble" })).toEqual({
+      NSBluetoothAlwaysUsageDescription: "ble",
+    });
+  });
+});

package/mobile/usageDescriptions.ts

@@ -0,0 +1,24 @@
+import { capitalize } from "akanjs/common";
+
+//* Apple's Info.plist keys do not follow the description names (photo → NSPhotoLibrary…), so each one is spelled out.
+const iosUsageDescriptionKeys = {
+  cameraUsageDescription: ["NSCameraUsageDescription"],
+  photoAddUsageDescription: ["NSPhotoLibraryAddUsageDescription"],
+  photoUsageDescription: ["NSPhotoLibraryUsageDescription"],
+  contactsUsageDescription: ["NSContactsUsageDescription"],
+  //? iOS 11+ reads the AlwaysAndWhenInUse key; the Always key only serves iOS 10 and below.
+  locationAlwaysUsageDescription: ["NSLocationAlwaysAndWhenInUseUsageDescription", "NSLocationAlwaysUsageDescription"],
+  locationWhenInUseUsageDescription: ["NSLocationWhenInUseUsageDescription"],
+  microphoneUsageDescription: ["NSMicrophoneUsageDescription"],
+  speechRecognitionUsageDescription: ["NSSpeechRecognitionUsageDescription"],
+} as const;
+
+export const toIosInfoPlistUsageDescriptions = (descriptions: { [key: string]: string }) =>
+  Object.fromEntries(
+    Object.entries(descriptions).flatMap(([key, value]) => {
+      const plistKeys: readonly string[] = Object.hasOwn(iosUsageDescriptionKeys, key)
+        ? iosUsageDescriptionKeys[key as keyof typeof iosUsageDescriptionKeys]
+        : [`NS${capitalize(key)}`];
+      return plistKeys.map((plistKey) => [plistKey, value]);
+    }),
+  );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.21",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -28,6 +28,7 @@
     "./akanConfig": "./akanConfig/index.ts",
     "./artifact": "./artifact/index.ts",
     "./cloud": "./cloud/index.ts",
+    "./codeAgent": "./codeAgent/index.ts",
     "./commandDecorators": "./commandDecorators/index.ts",
     "./frontendBuild": "./frontendBuild/index.ts",
     "./incrementalBuilder": "./incrementalBuilder/index.ts",
@@ -38,13 +39,15 @@
     "./*": "./*.ts"
   },
   "dependencies": {
+    "@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",
-    "@langchain/core": "^1.1.47",
-    "@langchain/deepseek": "^1.0.26",
-    "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
-    "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.2",
+    "akanjs": "3.0.0-beta.21",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -56,16 +59,13 @@
     "subset-font": "^2.5.0",
     "tailwind-scrollbar": "^4.0.2",
     "tailwindcss": "^4.3.0",
+    "typebox": "1.1.38",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@capacitor/cli": "^8.3.4",
     "react": "19.2.7"
   },
   "peerDependenciesMeta": {
-    "@capacitor/cli": {
-      "optional": true
-    },
     "react": {
       "optional": true
     }

package/packageExports.test.ts

@@ -3,30 +3,17 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { PackageExportsMap } from "@akanjs/devkit/packageExportsMap";
 
-// Guards the published shape of this package, which the monorepo cannot exercise on its own.
-//
-// Inside the monorepo Bun resolves `@akanjs/devkit/executors` through the root tsconfig `paths`
-// (`@akanjs/devkit/*` -> `pkgs/@akanjs/devkit/*`), and that resolver probes extensions and directory
-// indexes. A published consumer has no such mapping: it goes through this package's `exports` map,
-// whose targets are matched *exactly*. So `"./*": "./*"` type-checked, built, and passed every test
-// here while every subpath import failed at runtime for anyone installing the tarball:
-//
-//   error: Cannot find module '@akanjs/devkit/executors' from
-//     '<consumer>/node_modules/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts'
-//
-// `PackageRunner.verifyDistPackage` runs the same check against the built dist tree of every
-// publishable package at release time; these tests keep this package honest on every run.
+//? The monorepo resolves subpaths through tsconfig `paths`, which probe extensions; a published consumer goes through
+//? the exports map, matched exactly — so `"./*": "./*"` passed every test here and broke every installed subpath.
 
 const packageDir = import.meta.dir;
 const exportsMap = await PackageExportsMap.from(packageDir);
 
-/** Every facet the root barrel re-exports, as the subpath a consumer would import. */
 const barrelFacets = async (): Promise<string[]> => {
   const barrel = await Bun.file(path.join(packageDir, "index.ts")).text();
   return [...barrel.matchAll(/^export (?:type )?\* from "\.\/([^"]+)";$/gm)].map((match) => `./${match[1]}`);
 };
 
-/** Every `@akanjs/devkit/<subpath>` specifier written anywhere in the two packages that use them. */
 const importedSubpaths = async (): Promise<string[]> => {
   const repoRoot = path.resolve(packageDir, "../../..");
   const glob = new Bun.Glob("pkgs/@akanjs/{cli,devkit}/**/*.{ts,tsx}");
@@ -53,9 +40,7 @@ describe("published exports map", () => {
   });
 
   test("covers both facet shapes and keeps explicit extensions intact", () => {
-    // A single wildcard cannot serve all three: `./*` -> `./*.ts` reaches bare files, directory
-    // facets need their own literal entry, and `./*.ts` -> `./*.ts` keeps an already-suffixed
-    // specifier from becoming `./cloud/cloudApi.ts.ts`.
+    // One wildcard cannot serve bare files, directory facets and already-suffixed specifiers (no `.ts.ts`) at once.
     expect(exportsMap.resolve("./executors")).toBe("./executors.ts");
     expect(exportsMap.resolve("./frontendBuild")).toBe("./frontendBuild/index.ts");
     expect(exportsMap.resolve("./cloud/cloudApi.ts")).toBe("./cloud/cloudApi.ts");

package/packageExportsMap.ts

@@ -7,17 +7,9 @@ export interface UnreachableSubpath {
   target: string | null;
 }
 
-/**
- * The subset of Node's `exports` resolution that Bun applies to a published package.
- *
- * Exports targets are matched **exactly**: no extension is appended and no `index.ts` is probed. That
- * is invisible inside this monorepo, where `@akanjs/devkit/*` and `akanjs/*` resolve through the root
- * tsconfig `paths` instead — a resolver that *does* probe both. A map of `{"./*": "./*"}` therefore
- * type-checks, builds, and passes every test while every subpath import fails for anyone who installs
- * the tarball. This class exists so that gap can be asserted against before publishing.
- */
+// Bun matches exports targets exactly (no extension, no index.ts), while this monorepo resolves `akanjs/*` through
+// tsconfig paths, which probe both — so a broken map passes every in-repo test and fails for every installer.
 export class PackageExportsMap {
-  /** Reads `<packageDir>/package.json` and builds the map from its `exports` field. */
   static async from(packageDir: string) {
     const manifest = (await Bun.file(path.join(packageDir, "package.json")).json()) as { exports?: unknown };
     return new PackageExportsMap(packageDir, manifest.exports);
@@ -60,7 +52,6 @@ export class PackageExportsMap {
     // wins over `./*`, which is what keeps an already-suffixed specifier from gaining a second `.ts`.
     this.#patterns.sort((a, b) => b.prefix.length - a.prefix.length || b.suffix.length - a.suffix.length);
   }
-  /** Returns the target an `exports` lookup yields, or null when the subpath is unexported. */
   resolve(subpath: string): string | null {
     const literal = this.#literals.get(subpath);
     if (literal) return literal;
@@ -71,20 +62,13 @@ export class PackageExportsMap {
     }
     return null;
   }
-  /**
-   * Resolves a subpath and reports whether the target it yields is a readable file.
-   *
-   * A directory does not count. `{"./*": "./*"}` maps `./commandDecorators` onto the directory of
-   * that name, which exists but is not a module — an `existsSync` check here reports such a subpath
-   * as reachable while the import still fails.
-   */
+  // A directory does not count: `{"./*": "./*"}` maps `./commandDecorators` onto a folder, which is not importable.
   resolveToFile(subpath: string): { target: string | null; exists: boolean } {
     const target = this.resolve(subpath);
     if (!target) return { target: null, exists: false };
     const stat = statSync(path.join(this.#packageDir, target), { throwIfNoEntry: false });
     return { target, exists: !!stat?.isFile() };
   }
-  /** Returns the given subpaths that no consumer could import, in input order. */
   findUnreachable(subpaths: Iterable<string>): UnreachableSubpath[] {
     const unreachable: UnreachableSubpath[] = [];
     for (const subpath of subpaths) {

package/piDependencyPins.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { PackageJson } from "@akanjs/devkit/types";
+
+//? A published install reads neither pi's npm-shrinkwrap.json nor our overrides, so PackageRunner re-declares pi's
+//? sibling pins (a floating 0.80.x once broke every global install); this keeps them equal to the shrinkwrap.
+
+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 nested `node_modules/` key is another package's placement, not ours to pin.
+  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/platformTest/BunTestReport.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { BunTestReport } from "./BunTestReport";
+
+describe("BunTestReport", () => {
+  test("reads the final summary and attributes each failure to the file header above it", () => {
+    const report = new BunTestReport(
+      [
+        "bun test v1.4.2 (744846f84)",
+        "",
+        "server\\artifact\\routeSeedIndex.test.ts:",
+        "(pass) route seed index > keeps seeds [0.40ms]",
+        "(fail) route seed index > restores relative seed paths [1.20ms]",
+        "",
+        "lib/linter.test.ts:",
+        "\u001b[31m(fail) Linter > finds biome [3.00ms]\u001b[0m",
+        "",
+        "2 tests failed:",
+        "(fail) route seed index > restores relative seed paths [1.20ms]",
+        "(fail) Linter > finds biome [3.00ms]",
+        "",
+        " 1 pass",
+        " 3 skip",
+        " 2 fail",
+        " 1 error",
+        "Ran 6 tests across 2 files. [120.00ms]",
+      ].join("\r\n"),
+    );
+
+    expect(report.hasSummary).toBe(true);
+    expect([report.pass, report.fail, report.skip, report.errors, report.files]).toEqual([1, 2, 3, 1, 2]);
+    expect(report.failures).toEqual([
+      { file: "server/artifact/routeSeedIndex.test.ts", name: "route seed index > restores relative seed paths" },
+      { file: "lib/linter.test.ts", name: "Linter > finds biome" },
+    ]);
+    expect(report.passed).toBe(false);
+  });
+
+  test("a run with no summary is not passed, and counts what it saw before it stopped", () => {
+    const report = new BunTestReport(
+      [
+        "server/akanApp.test.ts:",
+        "(pass) AkanApp > boots [1ms]",
+        "(pass) AkanApp > relays [2ms]",
+        "panic(main thread)",
+      ].join("\n"),
+    );
+
+    expect(report.hasSummary).toBe(false);
+    expect(report.passed).toBe(false);
+    expect(report.pass).toBe(2);
+    expect(report.lastFile).toBe("server/akanApp.test.ts");
+  });
+
+  test("a clean summary passes", () => {
+    const report = new BunTestReport(" 4 pass\n 0 fail\nRan 4 tests across 1 file. [12.00ms]\n");
+
+    expect(report.passed).toBe(true);
+    expect(report.files).toBe(1);
+  });
+});

package/platformTest/BunTestReport.ts

@@ -0,0 +1,65 @@
+import { stripVTControlCharacters } from "node:util";
+
+export interface BunTestFailure {
+  file: string | null;
+  name: string;
+}
+
+export class BunTestReport {
+  static readonly #fileHeaderPattern = /^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/;
+  //? After the last file, bun repeats every failure under an "N tests failed:" line — those belong to no header.
+  static readonly #relistPattern = /^\d+ tests? failed:$/;
+  static readonly #durationSuffix = /\s+\[[\d.]+m?s\]$/;
+
+  readonly pass: number;
+  readonly fail: number;
+  readonly skip: number;
+  readonly errors: number;
+  readonly files: number;
+  readonly hasSummary: boolean;
+  readonly failures: BunTestFailure[];
+  readonly lastFile: string | null;
+
+  constructor(output: string) {
+    const lines = stripVTControlCharacters(output).split(/\r?\n/);
+    let currentFile: string | null = null;
+    let lastFile: string | null = null;
+    let relisted = false;
+    const failures = new Map<string, BunTestFailure>();
+    for (const line of lines) {
+      if (BunTestReport.#relistPattern.test(line)) relisted = true;
+      const header = BunTestReport.#fileHeaderPattern.exec(line);
+      if (header?.[1] && !relisted) {
+        currentFile = header[1].replaceAll("\\", "/");
+        lastFile = currentFile;
+        continue;
+      }
+      if (!line.startsWith("(fail) ")) continue;
+      const name = line.slice("(fail) ".length).replace(BunTestReport.#durationSuffix, "");
+      if (!failures.has(name)) failures.set(name, { file: relisted ? null : currentFile, name });
+    }
+    const ran = lines.findLast((line) => /^Ran \d+ tests? across \d+ files?/.test(line));
+    this.hasSummary = !!ran;
+    this.files = ran ? Number(/across (\d+) files?/.exec(ran)?.[1] ?? 0) : 0;
+    this.failures = [...failures.values()];
+    this.lastFile = lastFile;
+    this.pass = ran
+      ? BunTestReport.#lastCount(lines, /^\s*(\d+) pass$/)
+      : lines.filter((line) => line.startsWith("(pass) ")).length;
+    this.fail = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) fail$/) : this.failures.length;
+    this.skip = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) skip$/) : 0;
+    this.errors = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) errors?$/) : 0;
+  }
+
+  get passed() {
+    return this.hasSummary && this.fail === 0 && this.errors === 0;
+  }
+
+  static #lastCount(lines: string[], pattern: RegExp) {
+    for (const line of lines.toReversed()) {
+      const count = pattern.exec(line)?.[1];
+      if (count) return Number(count);
+    }
+    return 0;
+  }
+}

package/platformTest/IdleWatchedProcess.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs } from "../testHelpers";
+import { IdleWatchedProcess } from "./IdleWatchedProcess";
+
+const makeRoot = tempDirs("akan-idle-watch-");
+const makeLogPath = async () => path.join(await makeRoot(), "nested", "run.log");
+
+describe("IdleWatchedProcess", () => {
+  test("tees the output of a command that finishes into the log and reports its exit code", async () => {
+    const logPath = await makeLogPath();
+    const result = await new IdleWatchedProcess(
+      [process.execPath, "--eval", "console.log('out'); console.error('err'); process.exit(3)"],
+      { logPath, idleMs: 10_000 },
+    ).run();
+
+    expect(result.exitCode).toBe(3);
+    expect(result.hung).toBe(false);
+    expect(result.output).toContain("out");
+    expect(result.output).toContain("err");
+    expect(await readFile(logPath, "utf8")).toContain("out");
+  });
+
+  test("gives up on a command that goes quiet, after asking the caller to clean up", async () => {
+    const logPath = await makeLogPath();
+    let cleanedUp = false;
+    const result = await new IdleWatchedProcess(
+      [process.execPath, "--eval", "console.log('started'); setInterval(() => {}, 1000)"],
+      {
+        logPath,
+        idleMs: 400,
+        onIdle: async () => {
+          cleanedUp = true;
+        },
+      },
+    ).run();
+
+    expect(result.hung).toBe(true);
+    expect(result.exitCode).toBeNull();
+    expect(cleanedUp).toBe(true);
+    expect(result.output).toContain("started");
+  });
+
+  test("a command that keeps talking is not idle, but still stops at the total budget", async () => {
+    const logPath = await makeLogPath();
+    const result = await new IdleWatchedProcess(
+      [process.execPath, "--eval", "setInterval(() => console.log('tick'), 50)"],
+      { logPath, idleMs: 5_000, totalMs: 500 },
+    ).run();
+
+    expect(result.hung).toBe(false);
+    expect(result.timedOut).toBe(true);
+    expect(result.exitCode).toBeNull();
+  });
+});

package/platformTest/IdleWatchedProcess.ts

@@ -0,0 +1,73 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export interface IdleWatchedResult {
+  exitCode: number | null;
+  hung: boolean;
+  timedOut: boolean;
+  output: string;
+  ms: number;
+}
+
+interface IdleWatchedOptions {
+  logPath: string;
+  idleMs: number;
+  totalMs?: number;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  onIdle?: () => Promise<void>;
+  onOutput?: (text: string) => void;
+}
+
+// Silence is the only reliable hang signal: a runner stuck in a synchronous loop never lets bun's test timeout fire.
+export class IdleWatchedProcess {
+  readonly #command: string[];
+  readonly #options: IdleWatchedOptions;
+
+  constructor(command: string[], options: IdleWatchedOptions) {
+    this.#command = command;
+    this.#options = options;
+  }
+
+  async run(): Promise<IdleWatchedResult> {
+    const { logPath, idleMs, totalMs, cwd, env, onIdle, onOutput } = this.#options;
+    await mkdir(path.dirname(logPath), { recursive: true });
+    const log = Bun.file(logPath).writer();
+    const startedAt = performance.now();
+    let lastOutputAt = startedAt;
+    let output = "";
+    let hung = false;
+    let timedOut = false;
+    const proc = Bun.spawn(this.#command, { cwd, env, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    const pump = async (stream: ReadableStream<Uint8Array>) => {
+      const decoder = new TextDecoder();
+      for await (const chunk of stream) {
+        lastOutputAt = performance.now();
+        const text = decoder.decode(chunk, { stream: true });
+        output += text;
+        log.write(chunk);
+        onOutput?.(text);
+      }
+    };
+    const pumping = Promise.all([pump(proc.stdout), pump(proc.stderr)]);
+    const watch = setInterval(
+      () => {
+        const now = performance.now();
+        if (now - lastOutputAt >= idleMs) hung = true;
+        else if (totalMs !== undefined && now - startedAt >= totalMs) timedOut = true;
+        else return;
+        clearInterval(watch);
+        void (async () => {
+          await onIdle?.().catch(() => undefined);
+          proc.kill();
+        })();
+      },
+      Math.max(50, Math.min(1000, idleMs / 4)),
+    );
+    const exitCode = await proc.exited;
+    clearInterval(watch);
+    await pumping;
+    await log.end();
+    return { exitCode: hung || timedOut ? null : exitCode, hung, timedOut, output, ms: performance.now() - startedAt };
+  }
+}