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

package/abstractDoc.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import type { SysExecutor } from "./executors";
 
 export type AbstractKind = "domain" | "service" | "scalar" | "other";
@@ -25,7 +26,9 @@ export class AbstractDoc {
     return folder.startsWith("_") ? "service" : "domain";
   }
   static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
-    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`))
+      .map((filePath) => filePath.split(path.sep).join("/"))
+      .sort();
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module) return docs;
     return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);

package/akanApp/akanApp.host.ts

@@ -621,28 +621,37 @@ export class AkanAppHost {
     );
   }
   /**
-   * Another process's RSS, read from the OS rather than asked of the process. `/proc` where it exists,
-   * `ps` otherwise (macOS has no `/proc`). Null when it cannot be read, which callers treat as
-   * "no new information" rather than as zero.
+   * Another process's RSS, read from the OS rather than asked of the process. `tasklist` on Windows, `/proc`
+   * where it exists, `ps` otherwise (macOS has no `/proc`). Null when it cannot be read, which callers treat
+   * as "no new information" rather than as zero.
    */
   static async readProcessRssBytes(pid: number): Promise<number | null> {
+    if (process.platform === "win32")
+      return await AkanAppHost.#readRssKbVia(
+        ["tasklist", "/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"],
+        AkanAppHost.#tasklistRssKb,
+      );
     const status = await Bun.file(`/proc/${pid}/status`)
       .text()
       .catch(() => null);
     const vmRssKb = status === null ? null : /VmRSS:\s+(\d+) kB/.exec(status)?.[1];
     if (vmRssKb) return Number(vmRssKb) * 1024;
-    return await AkanAppHost.#readRssViaPs(pid);
+    return await AkanAppHost.#readRssKbVia(["ps", "-o", "rss=", "-p", String(pid)], (output) => Number(output.trim()));
   }
   /**
-   * `ps`, bounded. An absent `ps` is already handled — it answers `null`, which callers read as "no new
-   * information" — but a `ps` that never answers was not: the only caller awaits it after a 20s settle,
+   * `ps` or `tasklist`, bounded. An absent tool is already handled — it answers `null`, which callers read as
+   * "no new information" — but a `ps` that never answers was not: the only caller awaits it after a 20s settle,
    * so the recycle it was about to commit simply never happened, silently. The harness has hit exactly
    * this hang while shelling out to `ps` under load.
    */
-  static async #readRssViaPs(pid: number, timeoutMs = PS_RSS_TIMEOUT_MS): Promise<number | null> {
+  static async #readRssKbVia(
+    command: string[],
+    parseKb: (output: string) => number,
+    timeoutMs = PS_RSS_TIMEOUT_MS,
+  ): Promise<number | null> {
     let proc: Bun.Subprocess<"ignore", "pipe", "ignore">;
     try {
-      proc = Bun.spawn(["ps", "-o", "rss=", "-p", String(pid)], { stdio: ["ignore", "pipe", "ignore"] });
+      proc = Bun.spawn(command, { stdio: ["ignore", "pipe", "ignore"] });
     } catch {
       return null;
     }
@@ -650,7 +659,7 @@ export class AkanAppHost {
     try {
       const output = await new Response(proc.stdout).text();
       await proc.exited;
-      const rssKb = Number(output.trim());
+      const rssKb = parseKb(output);
       return Number.isFinite(rssKb) && rssKb > 0 ? rssKb * 1024 : null;
     } catch {
       return null;
@@ -658,6 +667,11 @@ export class AkanAppHost {
       clearTimeout(killer);
     }
   }
+  /** `Mem Usage` is the working set — what `process.memoryUsage.rss()` reports on Windows — in locale-grouped KB. */
+  static #tasklistRssKb(output: string): number {
+    const memUsage = /"([^"]*)"\s*$/m.exec(output)?.[1];
+    return memUsage ? Number(memUsage.replace(/\D/g, "")) : Number.NaN;
+  }
   #cancelRssRecycle(): void {
     this.#rssRecycleReason = null;
     this.#rssRecycleOver = null;

package/akanConfig/akanConfig.test.ts

@@ -249,31 +249,65 @@ describe("AkanAppConfig", () => {
       ...akanPackageJson.dependencies,
       ...akanPackageJson.peerDependencies,
     };
-    const singleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "single" }, baseDevEnv);
-    const multipleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "multiple" }, baseDevEnv);
-    const clusterConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "cluster" }, baseDevEnv);
-
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("ioredis");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("bullmq");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("postgres");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("protobufjs");
-
-    expect(multipleConfig.getProductionPackageJson().dependencies).toMatchObject({
-      "@libsql/client": runtimeDependencies["@libsql/client"],
+    const configOf = (database: { modes: ("single" | "multiple" | "cluster")[] }) =>
+      new AkanAppConfig(app, [], packageJson, { database }, baseDevEnv);
+    const dependenciesOf = (config: AkanAppConfig) => config.getProductionPackageJson().dependencies ?? {};
+    const singleConfig = configOf({ modes: ["single"] });
+    const multipleConfig = configOf({ modes: ["multiple"] });
+    const clusterConfig = configOf({ modes: ["cluster"] });
+    const edgeAndCloud = configOf({ modes: ["single", "cluster"] });
+
+    for (const driver of ["ioredis", "bullmq", "postgres", "@libsql/client", "protobufjs"])
+      expect(dependenciesOf(singleConfig)).not.toHaveProperty(driver);
+    expect(dependenciesOf(multipleConfig)).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
       ioredis: runtimeDependencies.ioredis,
-      protobufjs: runtimeDependencies.protobufjs,
     });
-    expect(multipleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("postgres");
-
-    expect(clusterConfig.getProductionPackageJson().dependencies).toMatchObject({
+    expect(dependenciesOf(clusterConfig)).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
       ioredis: runtimeDependencies.ioredis,
       postgres: runtimeDependencies.postgres,
-      protobufjs: runtimeDependencies.protobufjs,
     });
-    expect(clusterConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
+    // multiple opens the same SQLite as single and Redis replaced protobuf on the wire, so neither ships by default.
+    for (const config of [multipleConfig, clusterConfig])
+      for (const driver of ["@libsql/client", "protobufjs"]) expect(dependenciesOf(config)).not.toHaveProperty(driver);
+    expect(dependenciesOf(multipleConfig)).not.toHaveProperty("postgres");
+    // One image for an edge site and a cloud cluster carries both modes' drivers, and says which it carries.
+    expect(dependenciesOf(edgeAndCloud)).toMatchObject({ postgres: runtimeDependencies.postgres });
+    expect(edgeAndCloud.dockerfile).toContain("ENV AKAN_DATABASE_MODES=single,cluster");
+    expect(singleConfig.dockerfile).toContain("ENV AKAN_DATABASE_MODES=single");
+  });
+
+  test("runs single when the app declares no mode", () => {
+    expect(new AkanAppConfig(app, [], packageJson, {}, baseDevEnv).database.modes).toEqual(["single"]);
+  });
+
+  test("refuses a mode name that is not one of the three, naming the file", () => {
+    expect(
+      () => new AkanAppConfig(app, [], packageJson, { database: { modes: ["clsuter" as "cluster"] } }, baseDevEnv),
+    ).toThrow("database.modes in apps/portal/akan.config.ts");
+  });
+
+  test("resolves a command's mode within the declared ones", () => {
+    const previous = process.env.AKAN_DATABASE_MODE;
+    try {
+      const config = new AkanAppConfig(
+        app,
+        [],
+        packageJson,
+        { database: { modes: ["single", "cluster"] } },
+        baseDevEnv,
+      );
+      delete process.env.AKAN_DATABASE_MODE;
+      expect(config.resolveDatabaseMode()).toBe("single");
+      process.env.AKAN_DATABASE_MODE = "cluster";
+      expect(config.resolveDatabaseMode()).toBe("cluster");
+      process.env.AKAN_DATABASE_MODE = "multiple";
+      expect(() => config.resolveDatabaseMode()).toThrow('Add "multiple" to database.modes');
+    } finally {
+      if (previous === undefined) delete process.env.AKAN_DATABASE_MODE;
+      else process.env.AKAN_DATABASE_MODE = previous;
+    }
   });
 
   test("resolves database mode runtime packages and missing install specs", () => {
@@ -300,20 +334,11 @@ describe("AkanAppConfig", () => {
     );
 
     expect(config.getDatabaseModeRuntimePackages("single")).toEqual([]);
-    expect(config.getDatabaseModeRuntimePackages("multiple")).toEqual([
-      "@libsql/client",
-      "bullmq",
-      "ioredis",
-      "protobufjs",
-    ]);
-    expect(config.getDatabaseModeRuntimePackages("cluster")).toEqual(["bullmq", "ioredis", "postgres", "protobufjs"]);
-    expect(config.getMissingDatabaseModeDependencySpecs("multiple")).toEqual([
-      `@libsql/client@${runtimeDependencies["@libsql/client"]}`,
-      `protobufjs@${runtimeDependencies.protobufjs}`,
-    ]);
+    expect(config.getDatabaseModeRuntimePackages("multiple")).toEqual(["bullmq", "ioredis"]);
+    expect(config.getDatabaseModeRuntimePackages("cluster")).toEqual(["bullmq", "ioredis", "postgres"]);
+    expect(config.getMissingDatabaseModeDependencySpecs("multiple")).toEqual([]);
     expect(config.getMissingDatabaseModeDependencySpecs("cluster")).toEqual([
       `postgres@${runtimeDependencies.postgres}`,
-      `protobufjs@${runtimeDependencies.protobufjs}`,
     ]);
     // The workspace-root install covers the toolchain/runtime plus every app Capacitor plugin
     // (deduped — "@capacitor/core" appears in both source lists).

package/akanConfig/akanConfig.ts

@@ -2,7 +2,7 @@ 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 { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
@@ -11,6 +11,7 @@ import type { BaseDevEnv, PackageJson } from "../types";
 import {
   type AkanApiConfig,
   type AkanAssetsConfig,
+  type AkanDatabaseConfig,
   type AkanMobileConfig,
   type AkanMobileTargetConfig,
   type AkanRouteConfig,
@@ -93,16 +94,6 @@ const MOBILE_APP_CAPACITOR_PLUGINS = [
   "@capacitor/push-notifications",
   "capacitor-plugin-safe-area",
 ] as const;
-const DATABASE_MODE_RUNTIME_PACKAGES = {
-  single: [],
-  multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
-  cluster: ["bullmq", "ioredis", "postgres", "protobufjs"],
-} satisfies Record<DatabaseMode, readonly string[]>;
-const AKAN_RUNTIME_PACKAGES = new Set<string>([
-  ...SSR_RUNTIME_PACKAGES,
-  ...MOBILE_RUNTIME_PACKAGES,
-  ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat(),
-]);
 const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
   deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
   imageSizes: [32, 48, 64, 96, 128, 256, 384],
@@ -211,7 +202,7 @@ export class AkanAppConfig implements AppConfigResult {
   docker: DockerConfig;
   /** The Dockerfile `akan build` writes: the declared string verbatim, or one assembled from the parts. */
   dockerfile: string;
-  defaultDatabaseMode: DatabaseMode;
+  database: AkanDatabaseConfig;
   web: AkanWebConfig;
   externalLibs: string[];
   barrelImports: string[];
@@ -250,7 +241,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.baseDevEnv = baseDevEnv;
     this.plugins = plugins;
     this.#applyRoutes(config?.routes);
-    this.defaultDatabaseMode = config?.defaultDatabaseMode ?? "single";
+    this.database = AkanAppConfig.#database(app, config);
     this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libContributions.externalLibs])];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
@@ -458,6 +449,7 @@ 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_DATABASE_MODES=${this.database.modes.join(",")}
 ENV AKAN_LOG_TO_FILE=0
 ${webEnvLines}
 CMD [${command.map((c) => `"${c}"`).join(",")}]`;
@@ -526,14 +518,31 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
   }
   #getProductionRuntimePackages() {
-    return [...this.externalLibs, ...SSR_RUNTIME_PACKAGES, ...this.getDatabaseModeRuntimePackages()];
+    return [
+      ...this.externalLibs,
+      ...SSR_RUNTIME_PACKAGES,
+      ...this.database.modes.flatMap((mode) => this.getDatabaseModeRuntimePackages(mode)),
+    ];
   }
-  getDatabaseModeRuntimePackages(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
-    return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
+  getDatabaseModeRuntimePackages(databaseMode: DatabaseMode) {
+    return [...DatabaseModes.drivers[databaseMode]];
   }
-  getMissingDatabaseModeDependencySpecs(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
+  getMissingDatabaseModeDependencySpecs(databaseMode: DatabaseMode) {
     return this.#getMissingDependencySpecs(this.getDatabaseModeRuntimePackages(databaseMode));
   }
+  /** The mode a CLI command runs this app in: the shell's `AKAN_DATABASE_MODE` if the app declares it, else the first. */
+  resolveDatabaseMode() {
+    return DatabaseModes.resolve({
+      requested: process.env.AKAN_DATABASE_MODE,
+      declared: this.database.modes.join(","),
+      local: true,
+    });
+  }
+  static #database(app: App, config: AppConfigDeclaration): AkanDatabaseConfig {
+    const declared = config?.database?.modes?.filter((mode): mode is DatabaseMode => !!mode);
+    const modes = declared?.length ? declared : ["single"];
+    return { modes: DatabaseModes.parseList(modes.join(","), `database.modes in apps/${app.name}/akan.config.ts`) };
+  }
   getMobileRuntimePackages() {
     // The app Capacitor plugins are installed at the workspace root too, so bun can resolve the
     // app's "*" declarations to a hoisted, peer-pinned version instead of fetching latest.
@@ -558,6 +567,9 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
         return `${lib}@${version}`;
       });
   }
+  get akanVersion() {
+    return getAkanPackageJson().version;
+  }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
     return {
       name: this.app.name,

package/akanConfig/types.ts

@@ -2,6 +2,7 @@ export type {
   AkanApiConfig,
   AkanAssetsConfig,
   AkanConfigFile,
+  AkanDatabaseConfig,
   AkanExecutor,
   AkanMobileConfig,
   AkanMobileTargetConfig,

package/applicationBuildRunner.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
 
 describe("ApplicationBuildRunner", () => {
@@ -16,8 +18,8 @@ describe("ApplicationBuildRunner", () => {
   });
 
   test("a bundler that mangles identifiers loses the class name a Logger reads", async () => {
-    const dir = `${process.env.TMPDIR ?? "/tmp"}/akan-minify-${Bun.randomUUIDv7()}`;
-    const entry = `${dir}/entry.ts`;
+    const dir = path.join(os.tmpdir(), `akan-minify-${Bun.randomUUIDv7()}`);
+    const entry = path.join(dir, "entry.ts");
     await Bun.write(
       entry,
       `const serve = () => class Service { readonly name = this.constructor.name; };
@@ -26,7 +28,7 @@ console.info(new SampleService().name);
 `,
     );
     const build = async (minify: Bun.BuildConfig["minify"]) => {
-      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: `${dir}/out` });
+      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: path.join(dir, "out") });
       expect(result.success).toBe(true);
       const proc = Bun.spawn([process.execPath, result.outputs[0].path], { stdout: "pipe" });
       return (await new Response(proc.stdout).text()).trim();

package/applicationBuildRunner.ts

@@ -191,9 +191,29 @@ export class ApplicationBuildRunner {
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
       this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
+      this.#app.dist.writeJson("akan.build.json", {
+        buildId: await this.#resolveBuildId(),
+        akanVersion: akanConfig.akanVersion,
+        builtAt: new Date().toISOString(),
+      }),
     ]);
   }
 
+  //* Read back at runtime as `buildId` on the ops channel; a deployment's own AKAN_BUILD_ID still wins over it there.
+  async #resolveBuildId() {
+    const fromEnv = process.env.AKAN_BUILD_ID?.trim();
+    if (fromEnv) return fromEnv;
+    const root = this.#app.workspace.workspaceRoot;
+    const sha = Bun.spawnSync(["git", "rev-parse", "--short=12", "HEAD"], { cwd: root, stderr: "ignore" });
+    if (sha.exitCode !== 0) return null;
+    const dirty = Bun.spawnSync(["git", "status", "--porcelain", "--untracked-files=no"], {
+      cwd: root,
+      stderr: "ignore",
+    });
+    const suffix = dirty.exitCode === 0 && dirty.stdout.toString().trim() ? "-dirty" : "";
+    return `${sha.stdout.toString().trim()}${suffix}`;
+  }
+
   async #buildBackend() {
     const akanConfig = await this.#app.getConfig();
     const backendExternals = [
@@ -204,15 +224,21 @@ export class ApplicationBuildRunner {
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
     }
-    const backendResult = await this.#buildOrThrow("backend", {
-      entrypoints: backendEntryPoints,
+    const backendConfig = {
       outdir: this.#app.dist.cwdPath,
       target: "bun",
       minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
       plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
-    });
+    } satisfies Omit<Bun.BuildConfig, "entrypoints">;
+    //* Built apart so main.js keeps its own module copies; splitting moves lazy vendor `import()`s out of the boot
+    //* parse (minimal: server.js import 79ms → 24ms, 59MB → 36MB RSS).
+    const [mainResult, serverResult] = [
+      await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[0]] }),
+      await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[1]], splitting: true }),
+    ];
+    const backendResult = { outputs: [...mainResult.outputs, ...serverResult.outputs] };
     // Nothing spawns the RSC worker without SSR, so an api-only image does not carry it.
     const rscWorkerResult = web.ssr
       ? await this.#buildOrThrow("rsc-worker", {

package/artifact/routeSeedIndex.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import path from "node:path";
 import { computeRouteSeedIndex, serializeRouteSeedIndexForArtifact } from "./routeSeedIndex";
 
 describe("computeRouteSeedIndex", () => {
@@ -19,10 +20,10 @@ describe("computeRouteSeedIndex", () => {
     ]);
 
     const leaf = index.entries.find((entry) => entry.routeId === "/:lang/foo");
-    expect(leaf?.seeds).toContain("/app/page/foo.tsx");
-    expect(leaf?.seeds).not.toContain("/app/page/foo/_layout.tsx");
-    expect(leaf?.seeds).toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
-    expect(leaf?.seeds).toContain("/app/page/_layout.tsx");
+    expect(leaf?.seeds).toContain(path.resolve("/app/page/foo.tsx"));
+    expect(leaf?.seeds).not.toContain(path.resolve("/app/page/foo/_layout.tsx"));
+    expect(leaf?.seeds).toContain(path.resolve("/app/.akan/generated/root-layouts/__root_layout.tsx"));
+    expect(leaf?.seeds).toContain(path.resolve("/app/page/_layout.tsx"));
 
     expect(() =>
       computeRouteSeedIndex([
@@ -42,8 +43,8 @@ describe("computeRouteSeedIndex", () => {
       { key: "./robots.txt.tsx", moduleAbsPath: "/app/page/robots.txt.tsx" },
     ]);
     const robots = index.entries.find((entry) => entry.routeId === "/robots.txt");
-    expect(robots?.seeds).not.toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
-    expect(robots?.seeds).not.toContain("/app/page/_layout.tsx");
+    expect(robots?.seeds).not.toContain(path.resolve("/app/.akan/generated/root-layouts/__root_layout.tsx"));
+    expect(robots?.seeds).not.toContain(path.resolve("/app/page/_layout.tsx"));
   });
 
   test("serializes seed paths relative to the artifact directory", () => {

package/capacitorApp.test.ts

@@ -235,7 +235,7 @@ describe("iOS native run helpers", () => {
     expect(deviceCommand.xcodebuildArgs).toContain("id=device-1");
     expect(deviceCommand.xcodebuildArgs).toContain("App QA");
     expect(deviceCommand.appPath).toBe(
-      "/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app",
+      path.join("/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app"),
     );
 
     const simulatorCommand = buildIosNativeRunCommand({
@@ -244,7 +244,7 @@ describe("iOS native run helpers", () => {
     });
     expect(simulatorCommand.xcodebuildArgs).toContain("platform=iOS Simulator,id=sim-1");
     expect(simulatorCommand.appPath).toBe(
-      "/repo/apps/minimal/ios/DerivedData/sim-1/Build/Products/Debug-iphonesimulator/App.app",
+      path.join("/repo/apps/minimal/ios/DerivedData/sim-1/Build/Products/Debug-iphonesimulator/App.app"),
     );
   });
 

package/cloud/constants.ts

@@ -24,13 +24,36 @@ export interface RemoteEnvServerConfig {
   username?: string;
   port?: number;
 }
+export type PlatformGatePolicy = "gate" | "warn";
+export interface LinuxTestTargetConfig {
+  cpus?: number;
+  memory?: string;
+  policy?: PlatformGatePolicy;
+}
+export interface WindowsTestTargetConfig {
+  host: string;
+  user: string;
+  identityFile: string;
+  knownHostsFile?: string;
+  utmVm?: string;
+  workRoot?: string;
+  tolerateScriptFailures?: string[];
+  policy?: PlatformGatePolicy;
+  greenStreak?: number;
+}
+export interface TestTargetsConfig {
+  linux?: LinuxTestTargetConfig;
+  windows?: WindowsTestTargetConfig;
+}
 export interface AkanGlobalConfig {
   cloudHost: { [key: string]: HostConfigDto };
   remoteEnvServers: Record<string, RemoteEnvServerConfig>;
+  testTargets: TestTargetsConfig;
 }
 export const defaultAkanGlobalConfig: AkanGlobalConfig = {
   cloudHost: {},
   remoteEnvServers: {},
+  testTargets: {},
 };
 
 export interface AccessTokenDto {

package/cloud/globalConfig.ts

@@ -12,6 +12,7 @@ import {
   type HostConfig,
   type HostConfigDto,
   type RemoteEnvServerConfig,
+  type TestTargetsConfig,
 } from "./constants";
 
 export class GlobalConfig {
@@ -27,6 +28,7 @@ export class GlobalConfig {
       ...akanConfig,
       cloudHost: akanConfig.cloudHost ?? defaultAkanGlobalConfig.cloudHost,
       remoteEnvServers: akanConfig.remoteEnvServers ?? defaultAkanGlobalConfig.remoteEnvServers,
+      testTargets: akanConfig.testTargets ?? defaultAkanGlobalConfig.testTargets,
     };
   }
   /**
@@ -71,6 +73,17 @@ export class GlobalConfig {
       remoteEnvServers,
     });
   }
+  static async getTestTargets(): Promise<TestTargetsConfig> {
+    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
+    return akanConfig.testTargets;
+  }
+  static async setTestTargets(testTargets: TestTargetsConfig) {
+    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
+    await GlobalConfig.#setAkanGlobalConfig({
+      ...akanConfig,
+      testTargets: { ...akanConfig.testTargets, ...testTargets },
+    });
+  }
   static needRefreshToken(accessToken: AccessToken): boolean {
     return !!accessToken?.expiresAt?.isBefore(dayjs().add(1, "hour"));
   }

package/codeAgent/agent/AkanCodeServices.ts

@@ -1,10 +1,13 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { type InlineExtension, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentProfile } from "akanjs/common";
 import { AkanEnvKeys } from "../tools/AkanEnvKeys";
 import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
 import { akanCodePaths } from "./akanCodePaths";
 import { akanSystemPrompt } from "./akanSystemPrompt";
+import type { CodeAgentProxy } from "./CodeAgentProxy";
 import { CodeSessionIndex } from "./CodeSessionIndex";
 
 export interface AkanCodeServicesOptions {
@@ -32,6 +35,10 @@ export class AkanCodeServices {
       enableInstallTelemetry: false,
       enableAnalytics: false,
       quietStartup: true,
+      // Twice the engine's 16,384. The reserve is all the room the response at the threshold gets — a request
+      // clamps its output to the window less the prompt less 4,096 — and 80% of it caps the summary. At 16k a
+      // reasoning model stops mid-thought there, and the recovery re-sends a near-full window to retry the turn.
+      compaction: { reserveTokens: 32_768 },
     });
   }
 
@@ -42,8 +49,18 @@ export class AkanCodeServices {
    * 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) {
+  static async runtime(workspaceRoot: string, proxy: CodeAgentProxy | null = null) {
     mkdirSync(akanCodePaths.globalDir(), { recursive: true, mode: 0o700 });
+    if (proxy) {
+      //* Behind a proxy neither `auth.json` nor an env key may reach a request, so credentials live in a throwaway
+      //* file and the only key the engine ever sends is the proxy token.
+      const runtime = await ModelRuntime.create({
+        authPath: path.join(mkdtempSync(path.join(tmpdir(), "akan-code-proxy-")), "auth.json"),
+        modelsPath: akanCodePaths.modelsFile(),
+      });
+      await proxy.apply(runtime);
+      return runtime;
+    }
     const runtime = await ModelRuntime.create({
       authPath: akanCodePaths.authFile(),
       modelsPath: akanCodePaths.modelsFile(),
@@ -53,7 +70,9 @@ export class AkanCodeServices {
   }
 
   static sessions(workspaceRoot: string, cwd: string, profile: CodeAgentProfile, resume?: string) {
-    if (profile.session.store !== "file") return SessionManager.inMemory(cwd);
+    //* `remote` has no store of its own yet, so it keeps a file session rather than none: a pod's worker is long-lived
+    //* and its suspended asks and resume need the file more than a laptop does.
+    if (profile.session.store === "memory") return SessionManager.inMemory(cwd);
     const dir = akanCodePaths.sessionsDir(workspaceRoot);
     mkdirSync(dir, { recursive: true });
     const manager = SessionManager.create(cwd, dir);