@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/cloud/cloudApi.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeJson, writeText } from "../testHelpers";
+
+// The cloud rotates a refresh token on every use and treats a second use as theft, revoking every session.
+class FakeCloud {
+  readonly server: ReturnType<typeof Bun.serve>;
+  readonly refreshes: string[] = [];
+  reused = false;
+  delayMs = 0;
+  hang: boolean = false;
+  readonly #refreshTokens = new Set(["refresh-0"]);
+  readonly #spent = new Set<string>();
+  readonly #jwts = new Set(["jwt-0"]);
+  #issued = 0;
+
+  constructor() {
+    this.server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (request) => this.#route(request) });
+  }
+
+  get host() {
+    return `http://127.0.0.1:${this.server.port}`;
+  }
+
+  async #route(request: Request) {
+    const url = new URL(request.url);
+    if (url.pathname === "/api/getRemoteSelf") {
+      const jwt = request.headers.get("authorization")?.replace(/^Bearer /, "") ?? "";
+      return Response.json(this.#jwts.has(jwt) ? { id: "u1", nickname: "akan" } : null);
+    }
+    if (url.pathname !== "/api/refreshAuthToken") return new Response("not found", { status: 404 });
+    const { refreshToken } = (await request.json()) as { refreshToken: string };
+    this.refreshes.push(refreshToken);
+    if (this.#spent.has(refreshToken)) this.reused = true;
+    if (!this.#refreshTokens.delete(refreshToken)) return Response.json({ error: "invalid" }, { status: 401 });
+    this.#spent.add(refreshToken);
+    this.#issued += 1;
+    const next = { jwt: `jwt-${this.#issued}`, refreshToken: `refresh-${this.#issued}` };
+    this.#refreshTokens.add(next.refreshToken);
+    this.#jwts.add(next.jwt);
+    if (this.hang) await new Promise(() => undefined);
+    await Bun.sleep(this.delayMs);
+    return Response.json({ ...next, expiresAt: new Date(Date.now() + 7 * 86_400_000).toISOString() });
+  }
+}
+
+const makeHome = tempDirs("akan-cloud-home-");
+const cloudIndex = path.resolve(import.meta.dir, "index.ts");
+let cloud: FakeCloud;
+
+afterEach(() => cloud.server.stop(true));
+
+// A separate `bun` per CLI process, with HOME pointing at a temp dir: the config path is fixed when the module loads.
+const cliRun = async (home: string, { callers = 1 } = {}) => {
+  const script = path.join(home, `cli-${crypto.randomUUID()}.ts`);
+  await writeText(
+    script,
+    `import { CloudApi, configPath } from ${JSON.stringify(cloudIndex)};
+if (!configPath.startsWith(${JSON.stringify(home)})) throw new Error("refusing to touch " + configPath);
+const workspace = { workspaceRoot: ${JSON.stringify(home)} };
+const selves = await Promise.all(
+  Array.from({ length: ${callers} }, async () => (await (await CloudApi.fromHost(workspace, ${JSON.stringify(cloud.host)})).getRemoteSelf())?.nickname ?? null),
+);
+process.stdout.write(JSON.stringify(selves));
+`,
+  );
+  return Bun.spawn(["bun", script], { env: { ...process.env, HOME: home }, stdout: "pipe", stderr: "pipe" });
+};
+const output = async (proc: Bun.Subprocess<"ignore", "pipe", "pipe">) => {
+  const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  expect(await proc.exited, stderr).toBe(0);
+  return JSON.parse(stdout) as (string | null)[];
+};
+
+const writerRun = async (home: string, waitTimeoutMs: number) => {
+  const script = path.join(home, `writer-${crypto.randomUUID()}.ts`);
+  await writeText(
+    script,
+    `import { GlobalConfig, configPath } from ${JSON.stringify(cloudIndex)};
+import { ConfigLock } from ${JSON.stringify(path.resolve(import.meta.dir, "configLock.ts"))};
+if (!configPath.startsWith(${JSON.stringify(home)})) throw new Error("refusing to touch " + configPath);
+Object.defineProperty(ConfigLock, "waitTimeoutMs", { value: ${waitTimeoutMs} });
+await GlobalConfig.setTestTargets({ linux: { cpus: 2 } });
+`,
+  );
+  const proc = Bun.spawn(["bun", script], { env: { ...process.env, HOME: home }, stdout: "pipe", stderr: "pipe" });
+  return { code: await proc.exited, stderr: await new Response(proc.stderr).text() };
+};
+
+const storeSession = async (home: string, { expiresInMs = 30 * 60_000, refreshToken = "refresh-0" } = {}) =>
+  await writeJson(path.join(home, ".akan", "config.json"), {
+    cloudHost: {
+      [cloud.host]: {
+        host: cloud.host,
+        auth: {
+          accessToken: { jwt: "jwt-0", refreshToken, expiresAt: new Date(Date.now() + expiresInMs).toISOString() },
+          self: { id: "u1", nickname: "akan" },
+        },
+      },
+    },
+  });
+const storedToken = async (home: string) => {
+  const config = JSON.parse(await readFile(path.join(home, ".akan", "config.json"), "utf8"));
+  return config.cloudHost[cloud.host].auth.accessToken as { jwt: string; refreshToken: string | null };
+};
+
+describe("CloudApi.fromHost token refresh", () => {
+  test("two CLI processes with a session in its last hour make exactly one refresh, and both use its result", async () => {
+    cloud = new FakeCloud();
+    cloud.delayMs = 300;
+    const home = await makeHome();
+    await storeSession(home);
+
+    const [first, second] = await Promise.all([
+      cliRun(home, { callers: 2 }).then(output),
+      cliRun(home, { callers: 2 }).then(output),
+    ]);
+
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+    expect(cloud.reused).toBe(false);
+    expect([...first, ...second]).toEqual(["akan", "akan", "akan", "akan"]);
+    expect(await storedToken(home)).toMatchObject({ jwt: "jwt-1", refreshToken: "refresh-1" });
+  }, 30_000);
+
+  test("a CLI started while another is mid-refresh waits for that refresh and uses its session", async () => {
+    cloud = new FakeCloud();
+    cloud.delayMs = 1_500;
+    const home = await makeHome();
+    await storeSession(home);
+
+    const first = cliRun(home).then(output);
+    for (let tries = 0; tries < 300 && (await storedToken(home)).refreshToken !== null; tries++) await Bun.sleep(10);
+    expect((await storedToken(home)).refreshToken).toBeNull();
+    const second = await cliRun(home).then(output);
+
+    expect(await first).toEqual(["akan"]);
+    expect(second).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+  }, 30_000);
+
+  test("a CLI killed while its refresh is in flight never lets the next one present that refresh token", async () => {
+    cloud = new FakeCloud();
+    cloud.hang = true;
+    const home = await makeHome();
+    await storeSession(home);
+
+    const killed = await cliRun(home);
+    for (let waited = 0; !cloud.refreshes.length && waited < 10_000; waited += 25) await Bun.sleep(25);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+    killed.kill("SIGKILL");
+    await killed.exited;
+    cloud.hang = false;
+
+    const started = Date.now();
+    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(Date.now() - started).toBeLessThan(10_000);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+    expect(cloud.reused).toBe(false);
+    expect((await storedToken(home)).refreshToken).toBeNull();
+  }, 30_000);
+
+  test("a refresh the cloud refuses is not presented again", async () => {
+    cloud = new FakeCloud();
+    const home = await makeHome();
+    await storeSession(home, { refreshToken: "refresh-unknown" });
+
+    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(cloud.refreshes).toEqual(["refresh-unknown"]);
+    expect((await storedToken(home)).refreshToken).toBeNull();
+  }, 30_000);
+
+  test("any other config write waits for the lock instead of writing around it", async () => {
+    cloud = new FakeCloud();
+    const home = await makeHome();
+    await storeSession(home);
+    const lockPath = path.join(home, ".akan", "config.json.lock");
+    await writeJson(lockPath, { pid: process.pid, at: Date.now() });
+
+    const blocked = await writerRun(home, 300);
+    expect(blocked.code).not.toBe(0);
+    expect(blocked.stderr).toContain(lockPath);
+    expect(JSON.parse(await readFile(path.join(home, ".akan", "config.json"), "utf8")).testTargets).toBeUndefined();
+
+    await rm(lockPath);
+    expect((await writerRun(home, 300)).code).toBe(0);
+    const config = JSON.parse(await readFile(path.join(home, ".akan", "config.json"), "utf8"));
+    expect(config.testTargets).toEqual({ linux: { cpus: 2 } });
+    expect(config.cloudHost[cloud.host].auth.accessToken.refreshToken).toBe("refresh-0");
+  }, 30_000);
+
+  test("a session with more than an hour left is used as it is", async () => {
+    cloud = new FakeCloud();
+    const home = await makeHome();
+    await storeSession(home, { expiresInMs: 2 * 86_400_000 });
+
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual([]);
+    expect(await storedToken(home)).toMatchObject({ jwt: "jwt-0", refreshToken: "refresh-0" });
+  }, 30_000);
+});

package/cloud/cloudApi.ts

@@ -2,6 +2,11 @@ import type { Workspace } from "../commandDecorators";
 import type { AccessToken, AccessTokenDto, HostConfig } from "./constants";
 import { GlobalConfig } from "./globalConfig";
 
+interface HttpRequestOptions {
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
 class HttpClient {
   readonly baseUrl: string;
   readonly headers: Record<string, string> = {};
@@ -9,15 +14,12 @@ class HttpClient {
     this.baseUrl = baseUrl;
     this.headers = headers;
   }
-  async get<T>(url: string, { headers }: { headers?: Record<string, string> } = {}): Promise<T> {
+  async get<T>(url: string, { headers, signal }: HttpRequestOptions = {}): Promise<T> {
     const response = await fetch(`${this.baseUrl}${url}`, {
-      headers: {
-        "Content-Type": "application/json",
-        ...this.headers,
-        ...headers,
-      },
+      headers: { "Content-Type": "application/json", ...this.headers, ...headers },
+      ...(signal ? { signal } : {}),
     });
-    return await response.json();
+    return await HttpClient.#body<T>(response, url);
   }
   async getFile(url: string, localPath: string, headers?: Record<string, string>): Promise<void> {
     const response = await fetch(`${this.baseUrl}${url}`, {
@@ -26,7 +28,7 @@ class HttpClient {
     if (!response.ok) throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
     await Bun.write(localPath, response);
   }
-  async post<T>(url: string, data: unknown, { headers }: { headers?: Record<string, string> } = {}): Promise<T> {
+  async post<T>(url: string, data: unknown, { headers, signal }: HttpRequestOptions = {}): Promise<T> {
     const isFormData = data instanceof FormData;
     const response = await fetch(`${this.baseUrl}${url}`, {
       method: "POST",
@@ -34,8 +36,15 @@ class HttpClient {
       headers: isFormData
         ? { ...this.headers, ...headers }
         : { "Content-Type": "application/json", ...this.headers, ...headers },
+      ...(signal ? { signal } : {}),
     });
-    return await response.json();
+    return await HttpClient.#body<T>(response, url);
+  }
+  // A missing route answers an HTML error page, so the status is read before the body is parsed as JSON.
+  static async #body<T>(response: Response, url: string): Promise<T> {
+    const text = await response.text();
+    if (!response.ok) throw new Error(`${response.status} ${response.statusText} from ${url}: ${text.slice(0, 200)}`);
+    return JSON.parse(text) as T;
   }
   setHeaders(headers: Record<string, string>) {
     Object.assign(this.headers, headers);
@@ -43,6 +52,27 @@ class HttpClient {
   }
 }
 
+export interface TunnelGrant {
+  code: string;
+  hostname: string;
+  url: string;
+  /** Named by the control plane (e.g. `wss://tunnel.akanjs.com`); the CLI never assumes one. */
+  gatewayUrl: string;
+  /** Whoever holds it becomes the origin behind `hostname`: never written to disk or logged. */
+  token: string;
+  expiresAt: string | null;
+}
+
+export interface TunnelSummary {
+  code: string;
+  hostname: string;
+  url: string;
+  name: string | null;
+  createdAt: string;
+  expiresAt: string | null;
+  connected: boolean;
+}
+
 export class CloudApi {
   readonly #api: HttpClient;
   #accessToken: AccessToken | null = null;
@@ -52,7 +82,14 @@ export class CloudApi {
 
   static async fromHost(workspace: Workspace, host?: string) {
     const hostConfig = await GlobalConfig.getHostConfig(host);
-    return new CloudApi(workspace, hostConfig);
+    const accessToken = hostConfig.auth?.accessToken;
+    // No refresh token on a session in its last hour can be another process's refresh in flight: wait on its lock.
+    if (!accessToken || !GlobalConfig.needRefreshToken(accessToken)) return new CloudApi(workspace, hostConfig);
+    const tokenless = new CloudApi(workspace, hostConfig);
+    const refreshed = await GlobalConfig.refreshHostAuth(hostConfig.host, (refreshToken) =>
+      tokenless.refreshAuthToken(refreshToken),
+    );
+    return new CloudApi(workspace, refreshed);
   }
   constructor(workspace: Workspace, hostConfig: HostConfig) {
     this.#workspace = workspace;
@@ -61,17 +98,20 @@ export class CloudApi {
     this.url = `${this.host}/api`;
     this.#api = new HttpClient(this.url);
     if (this.#accessToken && !GlobalConfig.needRefreshToken(this.#accessToken))
-      this.#api.setHeaders({
-        Authorization: `Bearer ${this.#accessToken.jwt}`,
-      });
+      this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
+  }
+
+  #authorize(accessTokenDto: AccessTokenDto) {
+    this.#accessToken = GlobalConfig.toAccessToken(accessTokenDto);
+    this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
+    return this.#accessToken;
   }
 
   async uploadEnv(devProjectId: string, file: File): Promise<boolean> {
     const formData = new FormData();
     formData.append("devProjectId", devProjectId);
     formData.append("file", file);
-    const data = await this.#api.post<boolean>(`/uploadEnv/${devProjectId}`, formData);
-    return data;
+    return await this.#api.post<boolean>(`/uploadEnv/${devProjectId}`, formData);
   }
   async downloadEnv(devProjectId: string): Promise<unknown> {
     const localPath = `${this.#workspace.workspaceRoot}/local/env.tar`;
@@ -80,38 +120,36 @@ export class CloudApi {
   }
   async getRemoteAuthToken(remoteId: string): Promise<AccessToken | null> {
     try {
-      const accessToken = await this.#api.get<AccessTokenDto>(`/getRemoteAuthToken/${remoteId}`);
-      this.#accessToken = GlobalConfig.toAccessToken(accessToken);
-      this.#api.setHeaders({
-        Authorization: `Bearer ${this.#accessToken.jwt}`,
-      });
-      return this.#accessToken;
+      return this.#authorize(await this.#api.get<AccessTokenDto>(`/getRemoteAuthToken/${remoteId}`));
     } catch (_) {
       return null;
     }
   }
-  async #ensureAccessTokenLive({
-    allowUnauthorized = false,
-  }: {
-    allowUnauthorized?: boolean;
-  } = {}): Promise<AccessToken> {
-    if (!this.#accessToken) throw new Error("No access token");
-    const needRefresh = GlobalConfig.needRefreshToken(this.#accessToken);
-    if (!needRefresh) return this.#accessToken;
-    const refreshToken = this.#accessToken?.refreshToken;
-    if (!refreshToken) throw new Error("No refresh token");
-    return await this.refreshAuthToken(refreshToken);
-  }
   async refreshAuthToken(refreshToken: string): Promise<AccessToken> {
-    const response = await this.#api.post<AccessTokenDto>(`/refreshAuthToken`, { refreshToken });
-    this.#accessToken = GlobalConfig.toAccessToken(response);
-    this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
-    return this.#accessToken;
+    return this.#authorize(
+      await this.#api.post<AccessTokenDto>(
+        `/refreshAuthToken`,
+        { refreshToken },
+        { signal: AbortSignal.timeout(20_000) },
+      ),
+    );
+  }
+  // `/tunnel` is the model's refName, which the `_cloud` service routes above lack; dropping it answers 404.
+  async requestTunnel(input: { name: string; ttlMinutes?: number }): Promise<TunnelGrant> {
+    return await this.#api.post<TunnelGrant>(`/tunnel/requestTunnel`, input);
+  }
+  /** The generated name of the model's own `inSelf` slice: a hand-written `listTunnels` would collide with it. */
+  async tunnelListInSelf(): Promise<TunnelSummary[]> {
+    return await this.#api.get<TunnelSummary[]>(`/tunnel/tunnelListInSelf`);
+  }
+  // Bounded: callers are on the way out and an unreachable control plane would hold the event loop open; a lost
+  // release costs nothing, since the share expires on its own TTL.
+  async revokeTunnel(code: string): Promise<boolean> {
+    return await this.#api.post<boolean>(`/tunnel/revokeTunnel`, { code }, { signal: AbortSignal.timeout(5_000) });
   }
   async getRemoteSelf(): Promise<{ id: string; nickname: string } | null> {
     try {
-      const data = await this.#api.get<{ id: string; nickname: string }>(`/getRemoteSelf`);
-      return data;
+      return await this.#api.get<{ id: string; nickname: string }>(`/getRemoteSelf`);
     } catch {
       return null;
     }

package/cloud/configLock.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs } from "../testHelpers";
+import { ConfigLock } from "./configLock";
+
+const makeRoot = tempDirs("akan-config-lock-");
+/** A pid that cannot be alive: `kill(0)` on it is ESRCH on every platform this runs on. */
+const deadPid = 0x7ffffff;
+const lockIn = async () => path.join(await makeRoot(), ".akan", "config.json.lock");
+
+const withWaitTimeout = async <T>(ms: number, fn: () => Promise<T>) => {
+  const waitTimeoutMs = ConfigLock.waitTimeoutMs;
+  Object.defineProperty(ConfigLock, "waitTimeoutMs", { value: ms, configurable: true });
+  try {
+    return await fn();
+  } finally {
+    Object.defineProperty(ConfigLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+  }
+};
+
+describe("ConfigLock", () => {
+  test("runs one caller at a time, in the same process too", async () => {
+    const lockPath = await lockIn();
+    const order: string[] = [];
+    const body = async (name: string) => {
+      order.push(`${name}:in`);
+      await Bun.sleep(30);
+      order.push(`${name}:out`);
+    };
+    await Promise.all(["a", "b", "c"].map((name) => ConfigLock.run(lockPath, () => body(name))));
+    for (const name of ["a", "b", "c"]) expect(order.indexOf(`${name}:out`)).toBe(order.indexOf(`${name}:in`) + 1);
+  });
+
+  test("releases the lock when the body throws", async () => {
+    const lockPath = await lockIn();
+    await expect(ConfigLock.run(lockPath, async () => Promise.reject(new Error("boom")))).rejects.toThrow("boom");
+    expect(await Bun.file(lockPath).exists()).toBe(false);
+  });
+
+  test("reclaims a lock whose holder died", async () => {
+    const lockPath = await lockIn();
+    await ConfigLock.run(lockPath, async () => undefined);
+    await writeFile(lockPath, JSON.stringify({ pid: deadPid, at: Date.now() }));
+    const holder = await ConfigLock.run(lockPath, async () => JSON.parse(await readFile(lockPath, "utf8")));
+    expect(holder.pid).toBe(process.pid);
+  });
+
+  test("waits out a live holder and then fails, rather than going ahead without the lock", async () => {
+    const lockPath = await lockIn();
+    await ConfigLock.run(lockPath, async () => undefined);
+    await writeFile(lockPath, JSON.stringify({ pid: process.pid, at: Date.now() }));
+    let ran = false;
+    await withWaitTimeout(150, async () => {
+      await expect(
+        ConfigLock.run(lockPath, async () => {
+          ran = true;
+        }),
+      ).rejects.toThrow(lockPath);
+    });
+    expect(ran).toBe(false);
+    expect(JSON.parse(await readFile(lockPath, "utf8")).pid).toBe(process.pid);
+  });
+});

package/cloud/configLock.ts

@@ -0,0 +1,96 @@
+import { mkdir, open, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+
+interface LockHolder {
+  pid: number;
+  at: number;
+}
+
+// Across processes, not only calls: two `akan` commands started together share one `~/.akan/config.json`. A live
+// holder is never reclaimed, so a wait that runs out fails rather than proceeding without the lock.
+export class ConfigLock {
+  static readonly waitTimeoutMs = 30_000;
+  // A holder-less lock file younger than this is someone between the exclusive create and the write.
+  static readonly #unknownHolderStaleMs = 10_000;
+  static readonly #pollMs = 50;
+
+  static async run<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+    await mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + ConfigLock.waitTimeoutMs;
+    while (!(await ConfigLock.#take(lockPath))) {
+      if (Date.now() >= deadline) {
+        const holder = (await ConfigLock.#holder(lockPath))?.pid ?? "unknown";
+        throw new Error(
+          `${lockPath} is held by process ${holder}; if no akan command is running, delete it and retry.`,
+        );
+      }
+      await ConfigLock.#reclaimIfAbandoned(lockPath);
+      await Bun.sleep(ConfigLock.#pollMs);
+    }
+    try {
+      return await fn();
+    } finally {
+      await rm(lockPath, { force: true });
+    }
+  }
+
+  static async #take(lockPath: string) {
+    const handle = await open(lockPath, "wx", 0o600).catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "EEXIST") return null;
+      throw error;
+    });
+    if (!handle) return false;
+    try {
+      await handle.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() } satisfies LockHolder));
+    } finally {
+      await handle.close();
+    }
+    return true;
+  }
+
+  // Exclusive too: a waiter acting on its own stale read could delete the lock another waiter took a moment later.
+  static async #reclaimIfAbandoned(lockPath: string) {
+    if (!(await ConfigLock.#abandoned(lockPath))) return;
+    const guard = `${lockPath}.reclaim`;
+    if (!(await ConfigLock.#take(guard))) {
+      if (await ConfigLock.#abandoned(guard)) await rm(guard, { force: true });
+      return;
+    }
+    try {
+      if (await ConfigLock.#abandoned(lockPath)) await rm(lockPath, { force: true });
+    } finally {
+      await rm(guard, { force: true });
+    }
+  }
+
+  static async #abandoned(lockPath: string) {
+    const info = await stat(lockPath).catch(() => null);
+    if (!info) return false;
+    const holder = await ConfigLock.#holder(lockPath);
+    if (!holder) return Date.now() - info.mtimeMs > ConfigLock.#unknownHolderStaleMs;
+    return !ConfigLock.#isAlive(holder.pid);
+  }
+
+  static async #holder(lockPath: string): Promise<LockHolder | null> {
+    try {
+      const parsed = JSON.parse(await readFile(lockPath, "utf8")) as Partial<LockHolder>;
+      return typeof parsed.pid === "number" && typeof parsed.at === "number"
+        ? { pid: parsed.pid, at: parsed.at }
+        : null;
+    } catch {
+      // Missing, or caught between the create and the write; either way it names no holder.
+      return null;
+    }
+  }
+
+  static #isAlive(pid: number) {
+    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 counts as holding the lock.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  }
+}

package/cloud/constants.ts

@@ -1,9 +1,9 @@
+import path from "node:path";
 import type { Dayjs } from "dayjs";
-import type { SupportedLlmModel } from "../aiEditor";
 import { GlobalConfig } from "./globalConfig";
 
-export const basePath = `${Bun.env.HOME ?? Bun.env.USERPROFILE}/.akan`;
-export const configPath = `${basePath}/config.json`;
+export const basePath = path.join(Bun.env.HOME ?? Bun.env.USERPROFILE ?? "", ".akan");
+export const configPath = path.join(basePath, "config.json");
 
 export interface HostConfig {
   host: string;
@@ -25,15 +25,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>;
-  llm: { model: SupportedLlmModel; apiKey: string } | null;
+  testTargets: TestTargetsConfig;
 }
 export const defaultAkanGlobalConfig: AkanGlobalConfig = {
   cloudHost: {},
   remoteEnvServers: {},
-  llm: null,
+  testTargets: {},
 };
 
 export interface AccessTokenDto {