@intentius/chant 0.124.32 → 0.124.33

package/src/op/activities/shell-container.e2e.test.ts

@@ -0,0 +1,67 @@
+/**
+ * A `shell()` step in a container (#4015), run for real with `docker run
+ * --rm`. Skipped when Docker is not running. The containers are `--rm` and
+ * mount only host directories, so nothing is left behind.
+ */
+import { execSync } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { shellCmd } from "./shell";
+
+// alpine 3.21, pinned by its index digest.
+const IMAGE = process.env.CHANT_SHELL_E2E_IMAGE ?? "alpine:3.21@sha256:ce64758a109eb420d874a118f87920e625e12d3634e03b4a5573fd9f6e5d3507";
+
+function available(cmd: string): boolean {
+  try {
+    execSync(cmd, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hasDocker = available("docker info");
+const skipReason = hasDocker ? "" : " (skipped: Docker is not running)";
+
+describe.skipIf(!hasDocker)(`shellCmd with an image${skipReason}`, () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), "chant-shell-e2e-"));
+    await writeFile(join(dir, "input.txt"), "from the host\n");
+    execSync(`docker pull -q ${IMAGE}`, { stdio: "ignore" });
+  }, 120_000);
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("runs in the image, reads the workspace read-only, sees env by name, and writes its output directory on the host", async () => {
+    process.env.CHANT_SHELL_E2E_HOST_ONLY = "leaked";
+    try {
+      const result = await shellCmd({
+        cmd: 'cat /etc/alpine-release >/dev/null && echo "$GREETING:$CHANT_SHELL_E2E_HOST_ONLY" && cat input.txt > out/copy.txt; touch input.txt 2>/dev/null || echo read-only',
+        image: IMAGE,
+        cwd: dir,
+        env: { GREETING: "hi" },
+        outputs: ["out"],
+      });
+      expect(result.stdout.split("\n")).toEqual(["hi:", "read-only"]);
+      expect(await readFile(join(dir, "out", "copy.txt"), "utf8")).toBe("from the host\n");
+    } finally {
+      delete process.env.CHANT_SHELL_E2E_HOST_ONLY;
+    }
+  }, 60_000);
+
+  test("a declared output directory the command left empty fails the step", async () => {
+    await expect(shellCmd({ cmd: "true", image: IMAGE, cwd: dir, outputs: ["empty"] })).rejects.toThrow(/left it empty/);
+  }, 60_000);
+
+  test("keeps the command's exit status, and okExit still applies", async () => {
+    await expect(shellCmd({ cmd: "exit 4", image: IMAGE, cwd: dir })).rejects.toThrow(/command exited 4/);
+    const ok = await shellCmd({ cmd: "echo done; exit 1", image: IMAGE, cwd: dir, okExit: [0, 1] });
+    expect(ok).toMatchObject({ stdout: "done", exitCode: 1 });
+  }, 60_000);
+});

package/src/op/activities/shell.test.ts

@@ -10,7 +10,7 @@
 
 import { describe, test, expect } from "vitest";
 import { z } from "zod";
-import { shellCmd } from "./shell";
+import { containerCommand, imageProblem, shellCmd } from "./shell";
 import { shellCmdContract } from "./activity-contracts";
 import { shell } from "../builders";
 import { activity, phase } from "../builders";
@@ -244,3 +244,46 @@ describe("a step's own timeout (#2787)", () => {
     }
   });
 });
+
+describe("shellCmd in a container (#4015)", () => {
+  const PINNED = `alpine:3.21@sha256:${"e".repeat(64)}`;
+
+  test("builds a docker run --rm line: workspace read-only, env by name, the command under sh -c", () => {
+    const line = containerCommand({ cmd: "make test", image: PINNED, env: { TOKEN: "x", MODE: "ci" } }, { cwd: "/src/app" });
+    expect(line).toBe(`docker run --rm -v '/src/app:/workspace:ro' -w /workspace -e 'TOKEN' -e 'MODE' '${PINNED}' sh -c 'make test'`);
+  });
+
+  test("mounts each output directory writable over a read-only workspace, and none over a writable one", () => {
+    const ro = containerCommand({ cmd: "npm run build", image: PINNED, outputs: ["dist", "./reports/"] }, { cwd: "/src/app", cli: "podman", user: "501:20" });
+    expect(ro).toBe(
+      `podman run --rm --user 501:20 -v '/src/app:/workspace:ro' -v '/src/app/dist:/workspace/dist:rw' -v '/src/app/reports:/workspace/reports:rw' -w /workspace '${PINNED}' sh -c 'npm run build'`,
+    );
+    const rw = containerCommand({ cmd: "make", image: PINNED, mounts: { workspace: "rw" }, outputs: ["dist"] }, { cwd: "/src/app" });
+    expect(rw).toBe(`docker run --rm -v '/src/app:/workspace:rw' -w /workspace '${PINNED}' sh -c 'make'`);
+  });
+
+  test("an image is pinned by digest, as a literal string", () => {
+    expect(imageProblem(PINNED)).toBeUndefined();
+    expect(imageProblem("alpine:3.21")).toMatch(/not pinned by digest/);
+    expect(imageProblem(`alpine@sha256:${"E".repeat(64)}`)).toMatch(/not pinned by digest/);
+    expect(imageProblem(42)).toMatch(/literal string/);
+  });
+
+  test("refuses before running anything: a tag, an output outside the working directory, outputs without an image", async () => {
+    await expect(shellCmd({ cmd: "true", image: "alpine:3.21" })).rejects.toThrow(/not pinned by digest/);
+    await expect(shellCmd({ cmd: "true", image: PINNED, outputs: ["../escape"] })).rejects.toThrow(/inside the working directory/);
+    await expect(shellCmd({ cmd: "true", image: PINNED, outputs: ["/etc"] })).rejects.toThrow(/inside the working directory/);
+    await expect(shellCmd({ cmd: "true", outputs: ["dist"] })).rejects.toThrow(/give the step an image/);
+  });
+
+  test("the contract accepts image, mounts and outputs", () => {
+    expect(shellCmdContract.args.safeParse({ cmd: "x", image: PINNED, mounts: { workspace: "rw" }, outputs: ["dist"] }).success).toBe(true);
+    expect(shellCmdContract.args.safeParse({ cmd: "x", mounts: { workspace: "rwx" } }).success).toBe(false);
+  });
+
+  test("the shell() builder passes them through to the step", () => {
+    const step = shell("npm test", { image: PINNED, outputs: ["coverage"] });
+    expect(step.args).toEqual({ cmd: "npm test", image: PINNED, outputs: ["coverage"] });
+  });
+});
+

package/src/op/activities/shell.ts

@@ -1,4 +1,6 @@
 import { exec } from "node:child_process";
+import { mkdir, readdir } from "node:fs/promises";
+import { isAbsolute, join, normalize, resolve } from "node:path";
 import { promisify } from "node:util";
 import { GateWait, asPendingGate } from "../gate-wait";
 import type { PendingGateRecord } from "../../lifecycle/gate-ledger";
@@ -56,6 +58,84 @@ export interface ShellCmdArgs {
    * something else. Empty stdout is `null`.
    */
   json?: boolean;
+  /**
+   * Run the command in a container (#4015) instead of on the host: an image
+   * pinned by digest, `<ref>@sha256:<64 hex>`, so the step names the
+   * toolchain it ran with. The step's working directory is mounted at
+   * `/workspace`, which is the command's working directory; the container
+   * sees `env` by name and nothing of this process's environment, whatever
+   * `inheritEnv` says. Run with `docker run --rm`, or the command
+   * `CHANT_CONTAINER_CLI` names (`podman`).
+   */
+  image?: string;
+  /** How the container mounts the working directory (#4015). Default `{ workspace: "ro" }`. */
+  mounts?: { workspace?: "ro" | "rw" };
+  /**
+   * Directories under the working directory the containerized command writes
+   * (#4015). Each is created on the host if missing and mounted writable at
+   * the same path, so what the command leaves there stays on the host. A
+   * directory still empty when the command ends fails a step that otherwise
+   * passed. Only with `image`.
+   */
+  outputs?: string[];
+}
+
+/** An image reference pinned by digest (#4015): anything, then `@sha256:` and 64 lowercase hex digits. */
+export const PINNED_IMAGE = /^[^\s@]+@sha256:[0-9a-f]{64}$/;
+
+/** Why `image` can't run, or undefined when it is a reference pinned by digest. */
+export function imageProblem(image: unknown): string | undefined {
+  if (typeof image !== "string") return "image must be a literal string, an image reference pinned by digest";
+  if (!PINNED_IMAGE.test(image)) return `image ${JSON.stringify(image)} is not pinned by digest: name it as <ref>@sha256:<digest>`;
+  return undefined;
+}
+
+/** Why an `outputs` path can't be copied back, or undefined when it is a relative path inside the working directory. */
+function outputProblem(path: string): string | undefined {
+  const n = normalize(path);
+  if (path === "" || isAbsolute(path) || n === ".." || n.startsWith("../") || n === ".") return `output ${JSON.stringify(path)} must be a relative path inside the working directory`;
+  return undefined;
+}
+
+function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Where a containerized command sees the working directory. */
+const WORKSPACE = "/workspace";
+
+/**
+ * The `docker run --rm` line for a step with `image` (#4015). The working
+ * directory is mounted at `/workspace`, read-only by default, and each
+ * declared output directory is mounted writable on top of it.
+ */
+export function containerCommand(args: ShellCmdArgs & { image: string }, where: { cwd: string; cli?: string; user?: string }): string {
+  const mode = args.mounts?.workspace ?? "ro";
+  const outputs = mode === "ro" ? (args.outputs ?? []).map((p) => normalize(p).replace(/\/+$/, "")) : [];
+  return [
+    where.cli ?? "docker",
+    "run",
+    "--rm",
+    ...(where.user ? ["--user", where.user] : []),
+    "-v",
+    shellQuote(`${where.cwd}:${WORKSPACE}:${mode}`),
+    ...outputs.flatMap((p) => ["-v", shellQuote(`${join(where.cwd, p)}:${WORKSPACE}/${p}:rw`)]),
+    "-w",
+    WORKSPACE,
+    ...Object.keys(args.env ?? {}).flatMap((name) => ["-e", shellQuote(name)]),
+    shellQuote(args.image),
+    "sh",
+    "-c",
+    shellQuote(args.cmd),
+  ].join(" ");
+}
+
+/** Throw when a declared output directory is still empty after a command that passed. */
+async function checkOutputs(outputs: readonly string[], cwd: string): Promise<void> {
+  for (const p of outputs) {
+    const entries = await readdir(join(cwd, normalize(p))).catch(() => []);
+    if (entries.length === 0) throw new Error(`the step declares output ${JSON.stringify(p)}, and the command left it empty`);
+  }
 }
 
 /**
@@ -130,12 +210,20 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
   };
   const out = stepLineSplitter();
   const err = stepLineSplitter();
+  if (args.image === undefined && (args.outputs !== undefined || args.mounts !== undefined)) {
+    throw new Error("outputs and mounts apply only to a step that runs in a container: give the step an image");
+  }
+  const container = args.image !== undefined ? await prepareContainer(args) : undefined;
   try {
-    const running = execAsync(args.cmd, {
+    const running = execAsync(container?.cmd ?? args.cmd, {
       cwd: args.cwd,
       // In a run that keeps an in-flight record, CHANT_RUN_ACTIVITY names the
-      // file the command appends activity lines to (../run-live.ts).
-      env: { ...(args.inheritEnv === false ? {} : process.env), ...liveRunEnv(), ...args.env },
+      // file the command appends activity lines to (../run-live.ts). Under
+      // `image` the container CLI gets this process's environment, so it can
+      // reach its daemon, and the container gets `env` alone, by name.
+      env: container
+        ? { ...process.env, ...args.env }
+        : { ...(args.inheritEnv === false ? {} : process.env), ...liveRunEnv(), ...args.env },
       maxBuffer: MAX_STDOUT_BYTES,
       signal,
     });
@@ -152,6 +240,7 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
     }
     const { stdout, stderr } = settled;
     printStderr(stderr);
+    if (container) await checkOutputs(args.outputs ?? [], container.cwd);
     return withJson({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }, args);
   } catch (caught) {
     const failure = caught as ExecFailure;
@@ -179,6 +268,24 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
   }
 }
 
+/** The container line for a step with `image` (#4015), checked first, with each output directory made on the host. */
+async function prepareContainer(args: ShellCmdArgs): Promise<{ cmd: string; cwd: string }> {
+  const problem = imageProblem(args.image) ?? (args.outputs ?? []).map(outputProblem).find((p) => p !== undefined);
+  if (problem) throw new Error(problem);
+  const cwd = resolve(args.cwd ?? process.cwd());
+  // A writable mount inside a read-only one needs its mountpoint to exist already.
+  for (const p of args.outputs ?? []) await mkdir(join(cwd, normalize(p)), { recursive: true });
+  // The host's uid and gid, so what the command writes belongs to whoever
+  // runs chant rather than to the image's root.
+  const user = typeof process.getuid === "function" && typeof process.getgid === "function" ? `${process.getuid()}:${process.getgid()}` : undefined;
+  const cmd = containerCommand(args as ShellCmdArgs & { image: string }, {
+    cwd,
+    ...(process.env.CHANT_CONTAINER_CLI ? { cli: process.env.CHANT_CONTAINER_CLI } : {}),
+    ...(user ? { user } : {}),
+  });
+  return { cmd, cwd };
+}
+
 /** The pending fact a command's stdout carries: the whole of it as JSON, or its last line. */
 function pendingFromStdout(stdout: string): PendingGateRecord | undefined {
   const lines = stdout.split("\n");

package/src/op/builders.ts

@@ -391,6 +391,13 @@ export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedAct
  * twenty minutes, and keeps the profile's retries: `shell("./build.sh", {
  * timeout: "45m" })`. At most six hours (`MAX_STEP_TIMEOUT`).
  *
+ * `image` runs the command in a container instead of on the host (#4015),
+ * pinned by digest, with the working directory mounted read-only at
+ * `/workspace` unless `mounts` says `rw`, and each `outputs` directory
+ * mounted writable:
+ * `shell("npm run build", { image: "node:24@sha256:<digest>", outputs: ["dist"] })`.
+ * OPS018 refuses an image that is not pinned by digest.
+ *
  * `cmd` stays a plain `string` and takes no references. A value spliced into
  * a command line is a quoting decision chant would then be making on the
  * author's behalf, and `env` carries the same value into the same command

package/src/op/runtime.ts

@@ -62,6 +62,8 @@ export interface OpRunStepRecord {
   gate?: { op: string; gate: string };
   /** The run whose checkpoint supplied this step's output, for a step a resumed run skipped (#3947). */
   resumed?: { run: string; gate: string };
+  /** The image a `shellCmd` step ran in (#4015), pinned by digest, for a step that ran in a container. */
+  image?: string;
 }
 
 /** One phase's steps and the verdict they add up to. */

package/src/op/step-console.test.ts

@@ -118,13 +118,15 @@ describe("a quiet step says it is still running (#3956)", () => {
 
   test("a step printing output is not interrupted by the still-running line", async () => {
     const out = recorder();
-    const chatty = `node -e "let n = 0; const t = setInterval(() => { console.log('tick ' + n); if (++n === 6) clearInterval(t); }, 40)"`;
+    // sh, not node: node's start can outlast the heartbeat on a loaded runner,
+    // and the gap before the first line is what the heartbeat measures.
+    const chatty = `sh -c 'for n in 0 1 2 3 4 5; do echo "tick $n"; sleep 0.04; done'`;
     await runOpLocally(
       { name: "chatty", overview: "", phases: [phase("Go", [shell(chatty, { id: "ticks" })])] },
       new Map([["shellCmd", shellFn]]),
       ACTIVITY_PROFILES,
       undefined,
-      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 100 },
+      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 400 },
     );
     expect(out.lines.filter((l) => l.text.includes("still running"))).toEqual([]);
     expect(out.lines.map((l) => l.text)).toContain("[Go] ticks | tick 5");

package/src/pr-loop.test.ts

@@ -229,6 +229,35 @@ describe("the note", () => {
   });
 });
 
+describe("the record stage (#4168)", () => {
+  const recorded: PrReport = { ...planReport, stage: "record", status: "recorded", approval: { status: "approved", approvedBy: ["github:rev"] } };
+  const moved: PrReport = { ...recorded, approval: { status: "changed", approved: changedDigest } };
+  const unapproved: PrReport = { ...recorded, approval: { status: "pending" } };
+
+  test("its reports validate", () => {
+    for (const report of [recorded, moved, unapproved]) expectValid(report);
+  });
+
+  test("a plan that differs from the approved one fails the chant/record status; an approved or unapproved one passes", () => {
+    expect(prStatusContext("record")).toBe("chant/record");
+    expect(prStatusContext("record", "net")).toBe("chant/record/net");
+    expect(prStatusState(recorded)).toBe("success");
+    expect(prStatusState(unapproved)).toBe("success");
+    expect(prStatusState(moved)).toBe("failure");
+    expect(prStatusDescription(recorded)).toMatch(/^recorded 2 members: the approved plan; plan [0-9a-f]{12}$/);
+    expect(prStatusDescription(moved)).toMatch(/^recorded 2 members: the plan differs from the approved one/);
+    expect(prStatusDescription(unapproved)).toMatch(/^recorded 2 members: no approval for this plan/);
+  });
+
+  test("the note says nothing applied and a release deploys it", () => {
+    const note = renderPrNote(unapproved);
+    expect(note).toContain("### chant record for `prod`");
+    expect(note).toContain("Recorded the plan of 2 members on merge. Nothing applied: a release that carries this commit deploys it.");
+    expect(note).toContain("No approval stands for this plan. The release gate decides before it deploys.");
+    expect(renderPrNote(moved)).toContain("the plan changed since it was approved");
+  });
+});
+
 describe("the status", () => {
   test("describes each stage in at most 140 characters", () => {
     expect(prStatusDescription(planReport)).toMatch(/^2 members: 1 to change, 0 to destroy or replace; plan [0-9a-f]{12}$/);

package/src/pr-loop.ts

@@ -68,6 +68,9 @@ export const PR_REPORT_WAVES_FLOOR = "0.124.32";
  */
 export const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
 
+/** The chant that writes the `record` stage and the `recorded` status (#4168 step 1). */
+export const PR_REPORT_RECORD_FLOOR = "0.124.33";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -97,11 +100,14 @@ export function prNoteMarker(env: string, member?: string): string {
   return member ? `<!-- chant-pr:${env}:${member} -->` : `<!-- chant-pr:${env} -->`;
 }
 
-/** The status contexts the two stages set on the commit. */
-export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply" } as const;
+/** The status contexts the stages set on the commit. */
+export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply", record: "chant/record" } as const;
+
+/** A pull-request loop stage: plan on the pull request, then record (#4168) or, opted in, apply on merge. */
+export type PrStage = keyof typeof PR_STATUS_CONTEXTS;
 
 /** A stage's status context: `chant/plan`, or `chant/plan/<member>` for a workspace member's pipeline. */
-export function prStatusContext(stage: "plan" | "apply", member?: string): string {
+export function prStatusContext(stage: PrStage, member?: string): string {
   return member ? `${PR_STATUS_CONTEXTS[stage]}/${member}` : PR_STATUS_CONTEXTS[stage];
 }
 
@@ -207,6 +213,12 @@ export interface PrApproval {
 export type PrStatus =
   /** Plan stage: every member planned. */
   | "planned"
+  /**
+   * Record stage (#4168): every member planned on the merged commit and the
+   * plan is kept with the merge record. Nothing applied; `approval` says
+   * whether the plan is the one approved.
+   */
+  | "recorded"
   /** Plan stage: a member failed to plan. Apply stage: the same, so nothing applied. */
   | "plan-failed"
   /** Nothing the change touches is deployed by a component. */
@@ -284,7 +296,7 @@ export interface PrWave {
 export interface PrReport {
   $schema: typeof PR_REPORT_SCHEMA_ID;
   contract: typeof PR_REPORT_CONTRACT;
-  stage: "plan" | "apply";
+  stage: PrStage;
   /** The pull or merge request number, when known. */
   pr: number | null;
   env: string;
@@ -406,6 +418,8 @@ function headline(report: PrReport): string {
       return "Nothing to plan: no component deploys what this change touches.";
     case "planned":
       return `Planned ${members}.`;
+    case "recorded":
+      return `Recorded the plan of ${members} on merge. Nothing applied: a release that carries this commit deploys it.`;
     case "plan-failed":
       return `Planning failed for ${report.members.filter((m) => m.status === "plan-failed").length} of ${members}, so nothing can apply.`;
     case "applied":
@@ -468,7 +482,7 @@ function approvalLines(report: PrReport, approver: string): string[] {
   const lines =
     a.status === "changed"
       ? [`An approval stands for ${code(a.approved ?? "(none)")}, not for this digest: the plan changed since it was approved.`]
-      : ["Not approved yet."];
+      : [report.stage === "record" ? "No approval stands for this plan. The release gate decides before it deploys." : "Not approved yet."];
   if (report.stage === "plan" && report.status === "planned") {
     lines.push(
       "",
@@ -478,7 +492,7 @@ function approvalLines(report: PrReport, approver: string): string[] {
       prApproveCommand(report, approver),
       "```",
       "",
-      "It applies on merge if the plan is still this one. If it moved, the apply refuses and names both digests.",
+      "On merge the plan is recorded, and a release deploys it. With apply on merge it applies if the plan is still this one; if it moved, the apply refuses and names both digests.",
     );
   }
   return lines;
@@ -494,7 +508,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   const limit = options.limit ?? GITHUB_COMMENT_LIMIT;
   const out: string[] = [
     prNoteMarker(report.env, report.member),
-    `### chant ${report.stage === "plan" ? "plan" : "apply"} for ${code(report.env)}${report.member ? ` in member ${code(report.member)}` : ""}`,
+    `### chant ${report.stage} for ${code(report.env)}${report.member ? ` in member ${code(report.member)}` : ""}`,
     "",
     `${headline(report)} Head ${code(short(report.head))}, measured from ${code(short(report.base))}.`,
   ];
@@ -594,6 +608,9 @@ export function prStatusDescription(report: PrReport): string {
     case "plan-failed":
       text = `a member failed to plan${digest}`;
       break;
+    case "recorded":
+      text = `recorded ${n} member${n === 1 ? "" : "s"}: ${report.approval.status === "approved" ? "the approved plan" : report.approval.status === "changed" ? "the plan differs from the approved one" : "no approval for this plan"}${digest}`;
+      break;
     case "applied":
       text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
       break;
@@ -627,6 +644,8 @@ export function prStatusDescription(report: PrReport): string {
 
 /** The commit status state for a report: success, failure, or pending while it waits on approval. */
 export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
+  // #4168 decision 1: a merge whose plan differs from the approved one is recorded, and its status fails.
+  if (report.status === "recorded") return report.approval.status === "changed" ? "failure" : "success";
   if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing") return "success";
   if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved")) return "pending";
   if (report.status === "waiting") return "pending";

package/src/pr-report-url.ts

@@ -71,7 +71,7 @@ export function reportKey(pr: number | null, commit: string, member?: string): s
 }
 
 /** The events file of a stage. */
-export const reportEventsFile = (stage: "plan" | "apply"): string => `pr-${stage}.events.jsonl`;
+export const reportEventsFile = (stage: "plan" | "apply" | "record"): string => `pr-${stage}.events.jsonl`;
 
 /** Puts one object: `key` below the URL. Rejects with a line a person can read. */
 export type ReportPut = (key: string, body: string, contentType: string) => Promise<void>;
@@ -194,7 +194,7 @@ const messageOf = (err: unknown): string => (err instanceof Error ? err.message
 export function openPrReportUpload(input: {
   target: ReportTarget;
   key: string;
-  stage: "plan" | "apply";
+  stage: "plan" | "apply" | "record";
   warn: (message: string) => void;
   put?: ReportPut;
 }): PrReportUpload {

package/src/runner-start-bundle.test.ts

@@ -0,0 +1,29 @@
+/**
+ * `@intentius/chant/runner-start` bundles small (#4147): a stage that runs
+ * as one bundled file checks its runner before it trades for credentials,
+ * so the verifier reaches nothing but itself, the DSSE helpers and
+ * `node:crypto` and `node:fs`.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+test("the runner-start verifier holds itself and the DSSE helpers, and imports only node:crypto and node:fs", async () => {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", "runner-start.ts")],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  const inputs = Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort();
+  const imports = [...new Set(Object.values(result.metafile.outputs).flatMap((o) => o.imports.map((i) => i.path)))].sort();
+  expect(inputs).toEqual(["packages/core/src/runner-start.ts", "packages/core/src/workspace/trust/dsse.ts"]);
+  expect(imports).toEqual(["node:crypto", "node:fs"]);
+  expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(24 * 1024);
+});