@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.11

package/mobile/updateUploader.ts

@@ -1,4 +1,8 @@
+import { readdir } from "node:fs/promises";
 import path from "node:path";
+import type { UpdateEnvelope, UpdateManifest } from "@akanjs/native/api";
+import { isRecord, trimTrailingSlashes } from "akanjs/common";
+import { UpdatePackFolder } from "./updatePackFolder";
 
 /** What the uploader needs of an S3 client; Bun.S3Client is one. */
 export interface UpdateBucket {
@@ -11,6 +15,15 @@ export interface UpdateUploadResult {
   skipped: number;
 }
 
+/** The release one `publish-update` wrote, as it reports it. */
+export interface PublishedUpdate {
+  /** `<updates>/<os>-<arch>` for a desktop app, `<updates>/<platform>` for a phone's web bundle. */
+  dir: string;
+  channel: string;
+  /** Its manifest's `bundle`, which tells it from the other manifests of the channel there. */
+  bundle: string;
+}
+
 //* A manifest names files that must already be there, so they go first and the manifests last, each signature before
 //* its manifest as `publish-update` writes them. A release file never changes once published (its name carries its
 //* hash), so one the bucket holds is skipped; a manifest is always written.
@@ -19,9 +32,9 @@ export class UpdateUploader {
 
   /** `s3://bucket/prefix`: the credentials and endpoint come from S3_* (or AWS_*) in the environment. */
   static parseTarget(target: string): { bucket: string; prefix: string } {
-    const match = /^s3:\/\/([^/]+)\/?(.*)$/.exec(target.trim());
+    const match = /^s3:\/\/([^/]+)(?:\/(.*))?$/.exec(target.trim());
     if (!match?.[1]) throw new Error(`--upload takes s3://<bucket>/<prefix>, not ${JSON.stringify(target)}.`);
-    return { bucket: match[1], prefix: (match[2] ?? "").replace(/\/+$/, "") };
+    return { bucket: match[1], prefix: trimTrailingSlashes(match[2] ?? "") };
   }
 
   static order(files: string[]): { releases: string[]; manifests: string[] } {
@@ -34,6 +47,64 @@ export class UpdateUploader {
     };
   }
 
+  //* Never the whole folder: pack-update's records sit there too, and so do manifests of other channels and native
+  //* APIs, which a later publish from another machine may have replaced.
+  static async releaseFiles(updatesDir: string, { dir, channel, bundle }: PublishedUpdate): Promise<string[]> {
+    const keyOf = (file: unknown) => UpdateUploader.#keyOf(updatesDir, dir, file);
+    const desktop = await UpdateUploader.#read<UpdateManifest>(path.join(dir, `${channel}.json`));
+    if (desktop?.bundle === bundle) {
+      const archive = desktop.archive?.url;
+      const patches = UpdateUploader.#field(desktop.patches, "url");
+      return [archive, ...patches, `${channel}.json.sig`, `${channel}.json`].map(keyOf);
+    }
+    const names = await readdir(path.join(dir, channel)).catch(() => [] as string[]);
+    for (const name of names.filter((name) => name.endsWith(".json"))) {
+      const envelope = await UpdateUploader.#read<UpdateEnvelope>(path.join(dir, channel, name));
+      const manifest =
+        typeof envelope?.manifest === "string"
+          ? UpdateUploader.#parse<UpdateManifest>(Buffer.from(envelope.manifest, "base64").toString("utf8"))
+          : null;
+      if (manifest?.bundle !== bundle) continue;
+      const hashes = [...new Set(UpdateUploader.#field(manifest.files, "sha256"))];
+      if (!hashes.every((hash): hash is string => typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash)))
+        throw new Error(
+          `${path.join(dir, channel, name)} lists a file whose sha256 is not 64 hex digits; nothing was uploaded.`,
+        );
+      return [...hashes.map((hash) => `${UpdatePackFolder.filesDir}/${hash}`), `${channel}/${name}`].map(keyOf);
+    }
+    throw new Error(`${dir} holds no ${channel} manifest of release ${bundle}; nothing was uploaded.`);
+  }
+
+  static #keyOf(updatesDir: string, dir: string, file: unknown) {
+    const resolved = typeof file === "string" ? path.resolve(dir, file) : "";
+    const key = path.relative(updatesDir, resolved);
+    if (!resolved.startsWith(`${path.resolve(dir)}${path.sep}`) || key.startsWith("..") || path.isAbsolute(key))
+      throw new Error(
+        `The release in ${dir} names ${typeof file === "string" ? JSON.stringify(file) : "a file with no path"}, which is not inside that folder; nothing was uploaded.`,
+      );
+    return key.split(path.sep).join("/");
+  }
+
+  static #field(list: unknown, key: string): unknown[] {
+    return Array.isArray(list) ? list.map((item) => (isRecord(item) ? item[key] : undefined)) : [];
+  }
+
+  static async #read<T>(file: string) {
+    const text = await Bun.file(file)
+      .text()
+      .catch(() => "");
+    return UpdateUploader.#parse<T>(text);
+  }
+
+  static #parse<T>(text: string): Partial<T> | null {
+    try {
+      const value: unknown = JSON.parse(text);
+      return isRecord(value) ? (value as Partial<T>) : null;
+    } catch {
+      return null;
+    }
+  }
+
   constructor(
     readonly bucket: UpdateBucket,
     readonly prefix: string,
@@ -44,12 +115,8 @@ export class UpdateUploader {
     return new UpdateUploader(new Bun.S3Client({ bucket }), prefix);
   }
 
-  async upload(dir: string): Promise<UpdateUploadResult> {
-    const files: string[] = [];
-    for await (const file of new Bun.Glob("**/*").scan({ cwd: dir, onlyFiles: true })) {
-      if (!file.endsWith(".tmp")) files.push(file.split(path.sep).join("/"));
-    }
-    const { releases, manifests } = UpdateUploader.order(files);
+  async upload(updatesDir: string, release: PublishedUpdate): Promise<UpdateUploadResult> {
+    const { releases, manifests } = UpdateUploader.order(await UpdateUploader.releaseFiles(updatesDir, release));
     const keyOf = (file: string) => (this.prefix ? `${this.prefix}/${file}` : file);
     let uploaded = 0;
     let skipped = 0;
@@ -58,12 +125,12 @@ export class UpdateUploader {
         skipped++;
         continue;
       }
-      await this.bucket.write(keyOf(file), Bun.file(path.join(dir, file)));
+      await this.bucket.write(keyOf(file), Bun.file(path.join(updatesDir, file)));
       uploaded++;
     }
     for (const file of manifests) {
       const type = file.endsWith(".json") ? "application/json" : "text/plain";
-      await this.bucket.write(keyOf(file), Bun.file(path.join(dir, file)), { type });
+      await this.bucket.write(keyOf(file), Bun.file(path.join(updatesDir, file)), { type });
       uploaded++;
     }
     return { uploaded, skipped };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.1",
+  "version": "3.1.0-rc.11",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -40,31 +40,31 @@
     "./*": "./*.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",
-    "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.1.0-rc.1",
-    "chalk": "^5.6.2",
-    "commander": "^14.0.3",
-    "dayjs": "^1.11.20",
-    "fontaine": "^0.8.0",
+    "@earendil-works/pi-agent-core": "1.3.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-codemode": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-mcp": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
+    "@inquirer/prompts": "^8.7.3",
+    "@tailwindcss/node": "^4.3.3",
+    "akanjs": "3.1.0-rc.11",
+    "chalk": "^6.0.1",
+    "commander": "^15.0.0",
+    "dayjs": "^1.11.23",
+    "fontaine": "^1.0.1",
     "fonteditor-core": "^2.6.3",
-    "ignore": "^7.0.5",
-    "ora": "^9.4.0",
+    "ignore": "^7.0.12",
+    "ora": "^9.4.1",
     "ssh2": "^1.17.0",
-    "subset-font": "^2.5.0",
+    "subset-font": "^2.9.0",
     "tailwind-scrollbar": "^4.0.2",
-    "tailwindcss": "^4.3.0",
-    "typebox": "1.1.38",
+    "tailwindcss": "^4.3.3",
+    "typebox": "1.3.37",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "react": "19.3.0"
+    "react": "19.3.1"
   },
   "peerDependenciesMeta": {
     "react": {

package/piDependencyPins.test.ts

@@ -2,31 +2,24 @@ 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.
+//? PackageRunner re-declares pi's sibling pins because neither our `overrides` nor pi's own ranges reach a
+//? consumer's install. The source of truth is pi's `dependencies`: since 1.3.0 it pins every sibling exactly, where
+//? 0.86.1 floated `^0.86.1` and only the (now removed) `npm-shrinkwrap.json` held the resolved version.
 
 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);
+const siblingEntries = async () => {
+  const { dependencies = {} } = await readJson<PackageJson>(`${piDir}/package.json`);
+  return Object.entries(dependencies).filter(([name]) => /^@earendil-works\/[^/]+$/.test(name));
 };
 
 describe("pi dependency pins", () => {
-  test("the shrinkwrap read here belongs to the coding agent we publish", async () => {
+  test("the package 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}`);
@@ -34,13 +27,19 @@ describe("pi dependency pins", () => {
     }
   });
 
-  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);
+  test("the coding agent pins each sibling exactly", async () => {
+    const siblings = await siblingEntries();
+    expect(siblings.length).toBeGreaterThan(0);
+    const floating = siblings.filter(([, version]) => !/^\d+\.\d+\.\d+/.test(version));
+    expect(floating).toEqual([]);
+  });
+
+  test("every sibling pi package is published at the version the coding agent pins", async () => {
+    const siblings = await siblingEntries();
     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 });
+      const declared = Object.fromEntries(siblings.map(([name]) => [name, dependencies[name]]));
+      expect({ file, ...declared }).toEqual({ file, ...Object.fromEntries(siblings) });
     }
   });
 });

package/pipeline/PipelineCompiler.test.ts

@@ -337,7 +337,28 @@ describe("PipelineCompiler", () => {
     ]);
     const e2e = plan.phases.at(-1);
     expect(e2e).toMatchObject({ id: "e2e", timeoutSeconds: 3600, milestone: "finish" });
-    expect(e2e?.stages.map((stage) => [stage.id, stage.name, stage.app])).toEqual([["e2e:api", "api", "api"]]);
+    expect(e2e?.stages.map((stage) => [stage.id, stage.name, stage.app])).toEqual([["e2e.apps.api", "api", "api"]]);
+  });
+
+  test("a matrix copy's id never collides with an app's own stage or a post step", () => {
+    const stageIds = (plan: PipelinePlan) => plan.phases.flatMap((phase) => phase.stages.map((stage) => stage.id));
+    const plan = planOf(
+      compile({
+        workspace: { after: [{ name: "Web", matrix: "apps", sh: "bun run e2e $AKAN_CI_APP" }] },
+        apps: { web: { stages: [{ use: "build" }, { name: "API", sh: "bun run test:api" }] } },
+      }),
+    );
+    expect(stageIds(plan)).toEqual(expect.arrayContaining(["web:api", "web.apps.api", "web.apps.web"]));
+    expect(new Set(stageIds(plan)).size).toBe(stageIds(plan).length);
+    const post = planOf(
+      compile({
+        ctx: context({ apps: ["success"] }),
+        workspaceApps: ["success"],
+        workspace: { after: [{ name: "Post", matrix: "apps", sh: "x" }], post: { success: ["y"] } },
+      }),
+    );
+    expect(stageIds(post)).toContain("post.apps.success");
+    expect(post.post.success.map((step) => step.id)).toEqual(["post.success/1"]);
   });
 
   test("env is workspace, then app, then stage, then step; secrets are each step's union", () => {
@@ -571,6 +592,10 @@ describe("PipelineCompiler", () => {
       expect(codes(appResult({ stages: [{ name: "x", sh: "x", secrets: ["lower"] }] }))).toContain(
         "pipeline.secret.name",
       );
+      const pasted = appResult({ stages: [{ name: "x", sh: "x", secrets: ["NPM_TOKEN", "npm_live_value"] }] });
+      const secretName = pasted.diagnostics.find((diagnostic) => diagnostic.code === "pipeline.secret.name");
+      expect(secretName?.path).toEndWith(".secrets[1]");
+      expect(secretName?.message).not.toContain("npm_live_value");
       expect(codes(appResult({ stages: [{ name: "x", steps: [{ sh: "x", cwd: "../up" }] }] }))).toContain(
         "pipeline.cwd.outside",
       );
@@ -604,6 +629,30 @@ describe("PipelineCompiler", () => {
       );
     });
 
+    test("a parallel branch may not take the id of a post list's steps", () => {
+      const refused = compile({
+        workspace: { before: [{ name: "Post", parallel: [{ name: "Success", sh: "x" }] }], post: { success: ["y"] } },
+      });
+      expect(refused.ok).toBe(false);
+      expect(refused.diagnostics).toEqual([
+        expect.objectContaining({
+          code: "pipeline.id.reserved",
+          file: "akan.config.ts",
+          path: "pipeline.before[0].parallel[0].name",
+        }),
+      ]);
+      expect(
+        compile({
+          workspace: { after: [{ id: "post", name: "Checks", parallel: [{ id: "always", name: "A", sh: "x" }] }] },
+        }).diagnostics,
+      ).toEqual([expect.objectContaining({ code: "pipeline.id.reserved", path: "pipeline.after[0].parallel[0].id" })]);
+      const otherBranch = compile({
+        workspace: { before: [{ name: "Post", parallel: [{ name: "Lint", sh: "x" }] }], post: { success: ["y"] } },
+      });
+      expect(otherBranch.ok).toBe(true);
+      expect(compile({ workspace: { after: [{ name: "Post", sh: "x" }], post: { success: ["y"] } } }).ok).toBe(true);
+    });
+
     test("loading and sampling", () => {
       const thrown = appResult(() => {
         throw new Error("boom");
@@ -620,6 +669,113 @@ describe("PipelineCompiler", () => {
       expect(codes(sampled)).toContain("pipeline.function.sampled");
     });
 
+    test("a function returning nothing, an async one, and a falsy pipeline are errors, never a default", async () => {
+      const refused = (result: PipelinePlanResult, file: string) => {
+        expect(result.ok).toBe(false);
+        expect(result.diagnostics).toContainEqual(
+          expect.objectContaining({ severity: "error", code: "pipeline.schema.invalid", file, path: "pipeline" }),
+        );
+        return result.diagnostics.map((diagnostic) => diagnostic.message).join("\n");
+      };
+      const onMainOnly = ((ctx: { branch: string }) =>
+        ctx.branch === "main" ? { stages: [{ use: "build" }] } : undefined) as unknown as AppPipelineConfig;
+      expect(appResult(onMainOnly).ok).toBe(true);
+      const develop = compile({ ctx: context({ branch: "develop", apps: ["web"] }), apps: { web: onMainOnly } });
+      expect(refused(develop, "apps/web/akan.config.ts")).toContain("returned nothing");
+      expect(refused(compile({ workspace: (() => undefined) as never }), "akan.config.ts")).toContain(
+        "returned nothing",
+      );
+      expect(refused(compile({ workspace: (async () => ({ before: [] })) as never }), "akan.config.ts")).toContain(
+        "Promise",
+      );
+      const rejecting = (async () => {
+        throw new Error("boom");
+      }) as unknown as AppPipelineConfig;
+      expect(refused(appResult(rejecting), "apps/web/akan.config.ts")).toContain("Promise");
+      await Bun.sleep(1);
+      expect(refused(appResult(false as never), "apps/web/akan.config.ts")).toContain("must be an object");
+      expect(refused(compile({ workspace: 0 as never }), "akan.config.ts")).toContain("must be an object");
+    });
+
+    test("a plan larger than an executor reads, as written, is refused", () => {
+      const steps = Array.from({ length: 20 }, () => "x".repeat(60_000));
+      const result = appResult({ stages: [{ use: "build" }, { name: "Big", steps }] });
+      expect(result.ok).toBe(false);
+      expect(result.diagnostics).toContainEqual(
+        expect.objectContaining({ code: "pipeline.limit.exceeded", file: null, path: null }),
+      );
+    });
+
+    test("conditions", () => {
+      expect(appResult({ stages: [{ use: "build", when: { trigger: [] } }] }).diagnostics).toContainEqual(
+        expect.objectContaining({ code: "pipeline.schema.invalid", path: "pipeline.stages[0].when.trigger" }),
+      );
+      const branch = Array.from({ length: 6 }, (_, idx) => `release/${String(idx).repeat(240)}`);
+      const plan = planOf(
+        compile({
+          ctx: context({ branch: "develop", env: "develop", apps: ["web"] }),
+          apps: { web: { stages: [{ use: "build", when: { branch } }] } },
+        }),
+      );
+      const reason = plan.phases[0]?.stages[0]?.skip?.reason ?? "";
+      expect(reason.startsWith('branch "develop" does not match "release/')).toBe(true);
+      expect(reason.endsWith("…")).toBe(true);
+      expect(reason.length).toBeLessThanOrEqual(1024);
+    });
+
+    test("a value the plan would refuse is reported where it was written", () => {
+      expect(
+        appResult({ stages: [{ use: "build" }, { name: "x", sh: "x", env: { BIG: "x".repeat(64 * 1024 + 1) } }] })
+          .diagnostics,
+      ).toContainEqual(
+        expect.objectContaining({ code: "pipeline.limit.exceeded", path: "pipeline.stages[1].env.BIG" }),
+      );
+      const unset = compile({ workspace: { before: [{ name: "Checks", parallel: undefined as never }] } });
+      expect(unset.ok).toBe(false);
+      expect(unset.diagnostics).toEqual([
+        expect.objectContaining({
+          code: "pipeline.schema.invalid",
+          file: "akan.config.ts",
+          path: "pipeline.before[0].parallel",
+        }),
+      ]);
+    });
+
+    test("a key set to undefined is the key left out", () => {
+      const stage = { name: "Test", sh: "bun test", use: undefined, parallel: undefined, matrix: undefined };
+      const plan = planOf(
+        compile({
+          workspace: {
+            before: [stage as never, { name: "Checks", parallel: [{ name: "Lint", sh: "x", use: undefined }] }],
+          },
+          apps: { web: { stages: [{ use: "build", targets: undefined } as never, stage as never] } },
+        }),
+      );
+      expect(phaseIds(plan)).toEqual(["test", "checks", "build", "after-build", "docker", "deploy"]);
+      expect(appResult({ stages: [{ use: undefined } as never] }).diagnostics).toContainEqual(
+        expect.objectContaining({ code: "pipeline.schema.invalid", path: "pipeline.stages[0].use" }),
+      );
+    });
+
+    test("a value JSON cannot hold is reported, never thrown", () => {
+      const cyclic: Record<string, unknown> = {};
+      cyclic.self = cyclic;
+      const result = appResult({ stages: [{ use: "build", timeout: 10n as never }, { use: cyclic as never }] });
+      expect(result.ok).toBe(false);
+      expect(result.diagnostics.map((diagnostic) => [diagnostic.code, diagnostic.message.split(" ")[0]])).toEqual([
+        ["pipeline.duration.invalid", "10n"],
+        ["pipeline.schema.invalid", "[object"],
+      ]);
+    });
+
+    test("a long first line names its step without splitting a surrogate pair", () => {
+      const plan = planOf(
+        appResult({ stages: [{ use: "build" }, { name: "Emoji", sh: `${"a".repeat(78)}${"😀".repeat(5)}` }] }),
+      );
+      const name = plan.phases.find((phase) => phase.id === "after-build")?.stages[0]?.steps[0]?.name;
+      expect(name).toBe(`${"a".repeat(78)}…`);
+    });
+
     test("milestones that move backwards are a warning", () => {
       const result = appResult({
         stages: [{ use: "build" }, { use: "docker" }, { name: "Late", sh: "x", milestone: "verify" }],

package/pipeline/PipelineCompiler.ts

@@ -25,19 +25,21 @@ import {
   pipelineActions,
   pipelineMilestones,
   pipelineOtaPlatforms,
+  pipelinePlanLimits,
   pipelinePlanVersion,
+  toError,
 } from "akanjs/common";
-import {
-  type PipelineActionStageRule,
-  type PipelineAppRule,
-  PipelineInputReader,
-  type PipelinePostRule,
-  type PipelineShellStageRule,
-  type PipelineStepRule,
-  type PipelineWhenRule,
-  type PipelineWorkspaceRule,
-  type PipelineWorkspaceStageRule,
-} from "./PipelineInputReader";
+import { PipelineInputReader } from "./PipelineInputReader";
+import type {
+  PipelineActionStageRule,
+  PipelineAppRule,
+  PipelinePostRule,
+  PipelineShellStageRule,
+  PipelineStepRule,
+  PipelineWhenRule,
+  PipelineWorkspaceRule,
+  PipelineWorkspaceStageRule,
+} from "./PipelineRules";
 
 export interface PipelineSourceFile<T> {
   /** Relative to the workspace root, with `/`. */
@@ -59,7 +61,6 @@ export interface PipelineCompileInput {
   akanVersion: string;
   /** Function forms run against a sample context (`validate`), which is said once per file. */
   sampled?: boolean;
-  /** What loading the files already found. */
   diagnostics?: readonly PipelineDiagnostic[];
 }
 
@@ -87,7 +88,6 @@ interface StageOptions {
   timeoutSeconds?: number | null;
 }
 
-/** Composes the workspace's and each app's rules into one plan for one run. */
 export class PipelineCompiler {
   static readonly #slotAfter = {
     build: "after-build",
@@ -112,6 +112,8 @@ export class PipelineCompiler {
   static readonly #reservedPhaseId =
     /^(?:build|docker|deploy|ota|(?:before-build|after-build|after-docker|after-deploy|after-ota)(?:-\d+)?)$/;
   static readonly #actionStepNames = { build: "akan build", docker: "image", deploy: "deploy", ota: "ota" } as const;
+  //? PipelinePlanSchema reads at most 1024 characters of a skip reason.
+  static readonly #reasonChars = 1024;
 
   static compile(input: PipelineCompileInput): PipelinePlanResult {
     return new PipelineCompiler(input).#compile();
@@ -130,13 +132,9 @@ export class PipelineCompiler {
     const { context, workspaceApps } = this.#input;
     this.#checkContext();
     const pipelineContext: PipelineContext = {
-      branch: context.branch,
-      env: context.env,
+      ...context,
       apps: [...context.apps],
       workspaceApps: [...workspaceApps],
-      trigger: context.trigger,
-      buildNum: context.buildNum,
-      commit: context.commit,
     };
     const workspace = this.#readWorkspace(pipelineContext);
     const lanes = new Map<string, AppLane>();
@@ -164,11 +162,23 @@ export class PipelineCompiler {
     try {
       PipelinePlanSchema.parse(plan);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = toError(error).message;
       this.#error(message.includes("at most") ? "pipeline.limit.exceeded" : "pipeline.internal", message, null, null);
       return this.#failed();
     }
-    return { ok: true, plan, diagnostics: this.#diagnostics };
+    const result: PipelinePlanResult = { ok: true, plan, diagnostics: this.#diagnostics };
+    //? Sized as `akan pipeline plan --out` writes it, since that text is what an executor's parseText bounds.
+    const bytes = new TextEncoder().encode(`${JSON.stringify(result, null, 2)}\n`).length;
+    if (bytes > pipelinePlanLimits.planBytes) {
+      this.#error(
+        "pipeline.limit.exceeded",
+        `the plan is ${bytes} bytes as written, and an executor reads at most ${pipelinePlanLimits.planBytes}`,
+        null,
+        null,
+      );
+      return this.#failed();
+    }
+    return result;
   }
 
   #checkContext() {
@@ -184,11 +194,11 @@ export class PipelineCompiler {
 
   #readWorkspace(context: PipelineContext): PipelineWorkspaceRule | null {
     const source = this.#input.workspace;
-    if (!source?.pipeline) return null;
-    const value = this.#evaluate(source.pipeline, context, source.file);
-    if (value === undefined) return null;
+    if (source?.pipeline == null) return null;
+    const evaluated = this.#evaluate(source.pipeline, context, source.file);
+    if (!evaluated) return null;
     const reader = new PipelineInputReader(source.file);
-    const rule = reader.workspace(value);
+    const rule = reader.workspace(evaluated.value);
     this.#diagnostics.push(...reader.diagnostics);
     return rule;
   }
@@ -197,34 +207,55 @@ export class PipelineCompiler {
     const source = this.#input.apps.get(app);
     if (!source) return null;
     const appContext: AppPipelineContext = { ...context, app };
-    const value = source.pipeline ? this.#evaluate(source.pipeline, appContext, source.file) : defaultAppPipeline;
-    if (value === undefined) return null;
+    const evaluated =
+      source.pipeline == null
+        ? { value: defaultAppPipeline }
+        : this.#evaluate(source.pipeline, appContext, source.file);
+    if (!evaluated) return null;
     const reader = new PipelineInputReader(source.file);
-    const rule = reader.app(value);
+    const rule = reader.app(evaluated.value);
     this.#diagnostics.push(...reader.diagnostics);
     return rule ? this.#lane(app, rule, source.file) : null;
   }
 
-  #evaluate<C>(config: unknown, context: C, file: string): unknown {
-    if (typeof config !== "function") return config;
-    if (this.#input.sampled)
-      this.#warning(
-        "pipeline.function.sampled",
-        "a function form was checked against one sample context; other branches, triggers or apps may differ",
-        file,
-        "pipeline",
-      );
-    try {
-      return (config as (context: C) => unknown)(context);
-    } catch (error) {
+  #evaluate<C>(config: unknown, context: C, file: string): { value: unknown } | null {
+    let value = config;
+    if (typeof config === "function") {
+      if (this.#input.sampled)
+        this.#warning(
+          "pipeline.function.sampled",
+          "a function form was checked against one sample context; other branches, triggers or apps may differ",
+          file,
+          "pipeline",
+        );
+      try {
+        value = (config as (context: C) => unknown)(context);
+      } catch (error) {
+        this.#error("pipeline.load.failed", `the pipeline function threw: ${toError(error).message}`, file, "pipeline");
+        return null;
+      }
+      if (value === undefined) {
+        this.#error(
+          "pipeline.schema.invalid",
+          "the pipeline function returned nothing for this run: return a pipeline on every path",
+          file,
+          "pipeline",
+        );
+        return null;
+      }
+    }
+    if (typeof (value as PromiseLike<unknown> | null)?.then === "function") {
+      //? Handled so a rejection cannot end the CLI before it writes the envelope.
+      void Promise.resolve(value).catch(() => undefined);
       this.#error(
-        "pipeline.load.failed",
-        `the pipeline function threw: ${error instanceof Error ? error.message : String(error)}`,
+        "pipeline.schema.invalid",
+        "is a Promise, which the planner cannot wait for: return the pipeline itself, not from an async function",
         file,
         "pipeline",
       );
-      return undefined;
+      return null;
     }
+    return { value };
   }
 
   #lane(app: string, rule: PipelineAppRule, file: string): AppLane {
@@ -552,7 +583,9 @@ export class PipelineCompiler {
         maxParallel: stage.maxParallel,
         failFast: false,
         timeoutSeconds: stage.timeoutSeconds,
-        stages: apps.map((app) => this.#shellStage(copy, { id: `${stage.id}:${app}`, name: app, app, milestone, env })),
+        stages: apps.map((app) =>
+          this.#shellStage(copy, { id: `${stage.id}.apps.${app}`, name: app, app, milestone, env }),
+        ),
       },
     ];
   }
@@ -603,10 +636,11 @@ export class PipelineCompiler {
 
   #skipOf(when: PipelineWhenRule): PipelineSkip | null {
     const { branch, trigger } = this.#input.context;
+    const skip = (reason: string) => ({ reason: PipelineInputReader.clip(reason, PipelineCompiler.#reasonChars) });
     if (when.branch && !PipelinePattern.matches(when.branch, branch))
-      return { reason: `branch "${branch}" does not match ${when.branch.map((glob) => `"${glob}"`).join(", ")}` };
+      return skip(`branch "${branch}" does not match ${when.branch.map((glob) => `"${glob}"`).join(", ")}`);
     if (when.trigger && !when.trigger.includes(trigger))
-      return { reason: `trigger "${trigger}" is not ${when.trigger.map((name) => `"${name}"`).join(" or ")}` };
+      return skip(`trigger "${trigger}" is not ${when.trigger.map((name) => `"${name}"`).join(" or ")}`);
     return null;
   }
 
@@ -615,7 +649,7 @@ export class PipelineCompiler {
     const sourceOf = (source: PipelineSourceFile<unknown>): PipelinePlanSource => ({
       file: source.file,
       sha256: source.sha256,
-      declared: source.pipeline !== null,
+      declared: source.pipeline != null,
     });
     return {
       workspace: workspace ? sourceOf(workspace) : null,