@intentius/chant 0.124.27 → 0.124.29

package/src/pr-report-url.ts

@@ -0,0 +1,209 @@
+/**
+ * `pr-plan --report-url` and `pr-apply --report-url` (#4007): copy a stage's
+ * report, its change set and its run events where a reader outside CI can
+ * fetch them, keyed by pull request and commit.
+ *
+ * ```
+ * <url>/<pr>/<commit>/pr-<stage>.json
+ * <url>/<pr>/<commit>/change-set.json
+ * <url>/<pr>/<commit>/pr-<stage>.events.jsonl   (with --events-json)
+ * ```
+ *
+ * `<pr>` is the pull or merge request number, or `unknown` when pr-apply
+ * found none, and `<commit>` is the full sha the stage ran on: the pull
+ * request's head for pr-plan, the pushed commit for pr-apply. A workspace
+ * member's loop (`--member`) adds `/<member>` after the commit. There is no
+ * index: a reader that knows the pull request and the commit knows the key.
+ * The events file is named for its stage because pr-plan and pr-apply run on
+ * the same commit when a pull request merges by fast-forward.
+ *
+ * The events file is uploaded again, whole, each time a wave, a component or
+ * the run settles, so a reader polling the URL sees each wave as it applies.
+ * One upload of it is in flight at a time: a settle while one is in flight
+ * asks for one more after it, with everything written by then. A failed
+ * upload is a warning and the run goes on. The last upload, after the run
+ * settles, carries the whole stream, and the report and the change set go
+ * with it.
+ *
+ * Two schemes. `file://<dir>` writes under a directory, each file through a
+ * temporary name and a rename, so a reader never sees half a file. `s3://
+ * <bucket>/<prefix>` runs the AWS CLI (`aws s3 cp - <s3 url>`, the body on
+ * its stdin), which reads its credentials, region and endpoint from the
+ * environment the job gives it, the way the aws lexicon's `s3-sync` does.
+ * chant passes it no credential and prints none: a failed upload prints the
+ * CLI's own error line.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Where `--report-url` points. */
+export type ReportTarget =
+  | { scheme: "file"; url: string; dir: string }
+  | { scheme: "s3"; url: string; bucket: string; prefix: string };
+
+/** `--report-url` read, or why it can't be. */
+export function parseReportUrl(raw: string): ReportTarget | { error: string } {
+  const url = raw.trim();
+  if (url.startsWith("file://")) {
+    let dir: string;
+    try {
+      dir = fileURLToPath(url);
+    } catch (err) {
+      return { error: `--report-url ${url}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!isAbsolute(dir)) return { error: `--report-url ${url}: a file URL names an absolute directory` };
+    return { scheme: "file", url: url.replace(/\/+$/, ""), dir };
+  }
+  const s3 = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
+  if (s3) {
+    const prefix = s3[2]!.replace(/\/+$/, "");
+    return { scheme: "s3", url: `s3://${s3[1]}${prefix ? `/${prefix}` : ""}`, bucket: s3[1]!, prefix };
+  }
+  return { error: `--report-url ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
+}
+
+/** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */
+export function reportKey(pr: number | null, commit: string, member?: string): string {
+  return [pr === null ? "unknown" : String(pr), commit, ...(member ? [member] : [])].join("/");
+}
+
+/** The events file of a stage. */
+export const reportEventsFile = (stage: "plan" | "apply"): 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>;
+
+/** Runs the AWS CLI with `args` and `stdin`, rejecting with its error line on a non-zero exit. */
+export type AwsCli = (args: string[], stdin: string) => Promise<void>;
+
+const AWS_BINARY = "aws";
+
+/** The AWS CLI on PATH. */
+export const realAwsCli: AwsCli = (args, stdin) =>
+  new Promise((resolvePut, reject) => {
+    const child = spawn(AWS_BINARY, args, { stdio: ["pipe", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderr.length < 4096) stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      reject(new Error(err.code === "ENOENT" ? "the AWS CLI (aws) is not on PATH; an s3 report URL is uploaded with it" : err.message)),
+    );
+    child.on("close", (code) => {
+      if (code === 0) return resolvePut();
+      const line = stderr.trim().split("\n").filter(Boolean).at(-1) ?? "";
+      reject(new Error(`aws s3 cp exited ${code}${line ? `: ${line.slice(0, 300)}` : ""}`));
+    });
+    child.stdin.on("error", () => {
+      // The CLI exited before reading its input; its exit says why.
+    });
+    child.stdin.end(stdin);
+  });
+
+/** A put for `target`. `aws` replaces the AWS CLI in a test. */
+export function reportPut(target: ReportTarget, aws: AwsCli = realAwsCli): ReportPut {
+  if (target.scheme === "file") {
+    return async (key, body) => {
+      const path = join(target.dir, ...key.split("/"));
+      mkdirSync(dirname(path), { recursive: true });
+      const temp = `${path}.${process.pid}.tmp`;
+      writeFileSync(temp, body);
+      renameSync(temp, path);
+    };
+  }
+  return (key, body, contentType) => {
+    const object = `s3://${target.bucket}/${target.prefix ? `${target.prefix}/` : ""}${key}`;
+    return aws(["s3", "cp", "-", object, "--content-type", contentType, "--only-show-errors"], body);
+  };
+}
+
+/** A stage's upload: its events as they are written, and its files at the end. */
+export interface PrReportUpload {
+  /** The folder the stage's files go to: `<url>/<key>`. */
+  readonly where: string;
+  /** One line of the stage's run-event stream. A wave, component or run settle uploads the events. */
+  line(line: string): void;
+  /** A file to upload when the stage closes, replacing one of the same name. */
+  file(name: string, body: string): void;
+  /** Wait for the upload in flight, then upload the whole stream and the files. Never throws. */
+  close(): Promise<void>;
+}
+
+const UPLOAD_ON = new Set(["wave-settle", "component-settle", "run-settle"]);
+const NDJSON = "application/x-ndjson";
+const JSON_TYPE = "application/json";
+
+const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** Open a stage's upload to `target` under `key`. `warn` prints a warning line. */
+export function openPrReportUpload(input: {
+  target: ReportTarget;
+  key: string;
+  stage: "plan" | "apply";
+  warn: (message: string) => void;
+  put?: ReportPut;
+}): PrReportUpload {
+  const put = input.put ?? reportPut(input.target);
+  const where = `${input.target.url}/${input.key}`;
+  const eventsKey = `${input.key}/${reportEventsFile(input.stage)}`;
+  const files = new Map<string, string>();
+  let events = "";
+  let inFlight: Promise<void> | undefined;
+  let again = false;
+  let warned = false;
+
+  const pushEvents = (): void => {
+    if (inFlight) {
+      again = true;
+      return;
+    }
+    inFlight = put(eventsKey, events, NDJSON)
+      .catch((err) => {
+        if (warned) return;
+        warned = true;
+        input.warn(`could not upload the run's events to ${where} as the run went: ${messageOf(err)}. The run goes on, and its end tries again.`);
+      })
+      .finally(() => {
+        inFlight = undefined;
+        if (again) {
+          again = false;
+          pushEvents();
+        }
+      });
+  };
+
+  return {
+    where,
+    line(line) {
+      events += line;
+      let type: unknown;
+      try {
+        type = (JSON.parse(line) as { type?: unknown }).type;
+      } catch {
+        return;
+      }
+      if (typeof type === "string" && UPLOAD_ON.has(type)) pushEvents();
+    },
+    file(name, body) {
+      files.set(name, body);
+    },
+    async close() {
+      again = false;
+      while (inFlight) await inFlight;
+      const uploads: Array<[string, string, string]> = [
+        ...(events ? [[eventsKey, events, NDJSON] as [string, string, string]] : []),
+        ...[...files].map(([name, body]): [string, string, string] => [`${input.key}/${name}`, body, JSON_TYPE]),
+      ];
+      for (const [key, body, type] of uploads) {
+        try {
+          await put(key, body, type);
+        } catch (err) {
+          input.warn(`could not upload ${key.slice(input.key.length + 1)} to ${where}: ${messageOf(err)}`);
+        }
+      }
+    },
+  };
+}

package/src/provenance.ts

@@ -297,6 +297,6 @@ export interface BuildParamProvenance {
   name: string;
   /** The resolved, type-coerced value actually bound to `params.<name>` for this build. */
   value: string | number | boolean;
-  /** Which input supplied the value. */
-  source: "cli" | "params-file" | "env" | "default";
+  /** Which input supplied the value: `flag:<name>` names the workspace flag record it came from (#4024). */
+  source: "cli" | "params-file" | "env" | "default" | `flag:${string}`;
 }

package/src/run-event-store.test.ts

@@ -0,0 +1,144 @@
+/**
+ * #4042: a run's events kept on this host, replayed, and followed while the
+ * run is in progress. No servers: a temp git checkout, the real executor and
+ * the real writer, and a short poll.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { runOpLocally } from "./op/local-executor";
+import { memoryGateLedgerPort } from "./op/gate";
+import type { ActivityFn } from "./op/activity-registry";
+import type { OpConfig } from "./op/types";
+import type { RunEvent } from "./run-event";
+import { openRunEventStream, runEventRunOf } from "./run-event-stream";
+import { findStoredRun, listStoredRuns, openRunEventStore, readRunEvents, runEventsDir } from "./run-event-store";
+import { checkRunEventLines } from "./workspace/__fixtures__/run-event-check";
+
+const dirs: string[] = [];
+// These tests read the store a temp checkout keeps under its own git directory.
+beforeEach(() => void vi.stubEnv("CHANT_RUN_EVENTS_DIR", ""));
+afterEach(() => {
+  vi.unstubAllEnvs();
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function checkout(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "run-event-store-")));
+  dirs.push(dir);
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: dir });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+  return dir;
+}
+
+const op: OpConfig = {
+  name: "deploy-api",
+  overview: "",
+  phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }] }],
+};
+const ok: ActivityFn = async () => ({ done: true });
+const PROFILES = { fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } } };
+
+describe("a settled run's events", () => {
+  test("a run that records to the ledger keeps its stream, and it replays as the writer wrote it", async () => {
+    const dir = checkout();
+    await runOpLocally(op, new Map([["make", ok]]), PROFILES, undefined, {
+      runId: "r-settled",
+      ledger: { cwd: dir },
+      cwd: dir,
+      gates: memoryGateLedgerPort(),
+    });
+    const stored = (await findStoredRun(dir, "r-settled"))!;
+    expect(stored.file.startsWith(join(dir, ".git", "chant", "run-events"))).toBe(true);
+    expect(stored.name).toBe("deploy-api");
+
+    const lines: string[] = [];
+    const settle = await readRunEvents(stored.file, (_e, line) => lines.push(line));
+    const events = checkRunEventLines(lines);
+    expect(settle?.type).toBe("run-settle");
+    expect(events.map((e) => e.type)).toContain("step-settle");
+    expect(lines.join("")).toBe(readFileSync(stored.file, "utf8"));
+  });
+
+  test("an Op name stands for its newest run", async () => {
+    const dir = checkout();
+    for (const runId of ["r-1", "r-2"]) {
+      await runOpLocally(op, new Map([["make", ok]]), PROFILES, undefined, { runId, ledger: { cwd: dir }, cwd: dir, gates: memoryGateLedgerPort() });
+      await new Promise((r) => setTimeout(r, 15));
+    }
+    expect((await findStoredRun(dir, "deploy-api"))?.runId).toBe("r-2");
+    expect((await listStoredRuns(dir)).map((r) => r.runId)).toEqual(["r-2", "r-1"]);
+    expect(await findStoredRun(dir, "nothing")).toBeNull();
+  });
+
+  test("a run with no ledger (--no-record) keeps nothing", async () => {
+    const dir = checkout();
+    await runOpLocally(op, new Map([["make", ok]]), PROFILES, undefined, { runId: "r-none", cwd: dir, gates: memoryGateLedgerPort() });
+    const events = await runEventsDir(dir);
+    expect(events === null || !existsSync(events)).toBe(true);
+  });
+});
+
+describe("a run in progress", () => {
+  async function inFlight() {
+    const dir = checkout();
+    const store = (await openRunEventStore(dir, "r-live"))!;
+    const stream = openRunEventStream(runEventRunOf({ kind: "op", name: "deploy-api", runId: "r-live" }), store.write);
+    return { dir, store, stream };
+  }
+
+  test("replays what has been written so far, and not a half-written last line", async () => {
+    const { store, stream } = await inFlight();
+    stream.emit({ type: "run-start", waves: null });
+    stream.emit({ type: "phase-start", component: null, phase: "Build" });
+    appendFileSync(store.path, '{"type":"step-st');
+    const seen: RunEvent[] = [];
+    const settle = await readRunEvents(store.path, (e) => seen.push(e));
+    expect(settle).toBeUndefined();
+    expect(seen.map((e) => e.type)).toEqual(["run-start", "phase-start"]);
+  });
+
+  test("--follow streams each event as it is written and ends at run-settle", async () => {
+    const { store, stream } = await inFlight();
+    stream.emit({ type: "run-start", waves: null });
+    const seen: string[] = [];
+    const follow = readRunEvents(store.path, (e) => seen.push(`${e.seq}:${e.type}`), { follow: true, pollMs: 5, idleMs: 3000 });
+
+    await new Promise((r) => setTimeout(r, 30));
+    expect(seen).toEqual(["0:run-start"]);
+    stream.emit({ type: "phase-start", component: null, phase: "Build" });
+    stream.emit({ type: "step-start", component: null, phase: "Build", step: "make" });
+    await new Promise((r) => setTimeout(r, 30));
+    expect(seen).toEqual(["0:run-start", "1:phase-start", "2:step-start"]);
+    stream.settle("ok");
+
+    const settle = await follow;
+    expect(settle?.type).toBe("run-settle");
+    expect(seen.at(-1)).toBe("3:run-settle");
+  });
+
+  test("--follow waits for a file that is not there yet", async () => {
+    const dir = checkout();
+    const file = join((await runEventsDir(dir))!, "later.jsonl");
+    const seen: string[] = [];
+    const follow = readRunEvents(file, (e) => seen.push(e.type), { follow: true, pollMs: 5, idleMs: 3000 });
+    await new Promise((r) => setTimeout(r, 20));
+    const store = (await openRunEventStore(dir, "later"))!;
+    const stream = openRunEventStream(runEventRunOf({ kind: "op", name: "x", runId: "later" }), store.write);
+    stream.settle("failed", "boom");
+    expect((await follow)?.type).toBe("run-settle");
+    expect(seen).toEqual(["run-start", "run-settle"]);
+  });
+
+  test("an aborted follow returns without a verdict", async () => {
+    const { store, stream } = await inFlight();
+    stream.emit({ type: "run-start", waves: null });
+    const ac = new AbortController();
+    const follow = readRunEvents(store.path, () => {}, { follow: true, pollMs: 5, signal: ac.signal });
+    setTimeout(() => ac.abort(), 20);
+    expect(await follow).toBeUndefined();
+  });
+});

package/src/run-event-store.ts

@@ -0,0 +1,273 @@
+/**
+ * Where a run's events are kept on this host, and how to read them back
+ * (#4042). `chant run events <run>` replays a run from here and `--follow`
+ * tails it.
+ *
+ * Each run gets one file, `<git-common-dir>/chant/run-events/<run id>.jsonl`,
+ * holding the lines the one writer (`./run-event.ts`) produced, byte for byte
+ * as `--events-json` prints them. It sits beside the in-flight records
+ * (`./op/run-live.ts`), outside the working tree and off `chant/lifecycle`:
+ * the run ledger's growth is #4036's concern and these files add none to it.
+ * Unlike the in-flight record they are kept after the run settles, until
+ * `chant lifecycle gc --yes` deletes the ones its retention policy lets go
+ * (#4036, {@link planRunEventPrune}).
+ *
+ * Every write is best-effort. A run whose events cannot be kept still runs.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitCommonDir } from "./op/run-live";
+import type { RunEvent } from "./run-event";
+
+/** The directory name under `<git-common-dir>/chant/` that holds the files. */
+export const RUN_EVENTS_DIR = "run-events";
+
+/** The file name a run id is kept under: anything that is not a plain file-name character becomes `_`. */
+export function runEventFileName(runId: string): string {
+  return `${runId.replace(/[^A-Za-z0-9._@-]/g, "_")}.jsonl`;
+}
+
+/**
+ * The environment variable that names the directory run events are kept in,
+ * in place of the checkout's. The test suite sets it to a per-run temp
+ * directory, so no test writes to the real repository's store (worktrees
+ * share one git directory).
+ */
+export const RUN_EVENTS_DIR_ENV = "CHANT_RUN_EVENTS_DIR";
+
+/** The directory the checkout at `cwd` keeps run events in (`CHANT_RUN_EVENTS_DIR` when set), or null outside a checkout. */
+export async function runEventsDir(cwd: string): Promise<string | null> {
+  const override = process.env[RUN_EVENTS_DIR_ENV];
+  if (override) return override;
+  const common = await gitCommonDir(cwd);
+  return common ? join(common, "chant", RUN_EVENTS_DIR) : null;
+}
+
+/** An open file a run's lines are appended to. */
+export interface RunEventStore {
+  readonly path: string;
+  /** Append one line (it already ends with a newline). Never throws. */
+  write(line: string): void;
+}
+
+/** Open the file for `runId`, or undefined outside a checkout or where it cannot be created. */
+export async function openRunEventStore(cwd: string, runId: string): Promise<RunEventStore | undefined> {
+  let dir: string | null;
+  try {
+    dir = await runEventsDir(cwd);
+  } catch {
+    return undefined;
+  }
+  if (!dir) return undefined;
+  const path = join(dir, runEventFileName(runId));
+  try {
+    mkdirSync(dir, { recursive: true });
+    // A run id used again (a re-run of the same CI run) replaces the earlier stream.
+    writeFileSync(path, "");
+  } catch {
+    return undefined;
+  }
+  return {
+    path,
+    write(line) {
+      try {
+        appendFileSync(path, line);
+      } catch {
+        // The directory is gone or unwritable: the line is dropped.
+      }
+    },
+  };
+}
+
+/** A write function that hands each line to every function given, or undefined when none is. */
+export function teeLines(...writes: Array<((line: string) => void) | undefined>): ((line: string) => void) | undefined {
+  const live = writes.filter((w): w is (line: string) => void => w !== undefined);
+  if (live.length === 0) return undefined;
+  if (live.length === 1) return live[0];
+  return (line) => {
+    for (const w of live) w(line);
+  };
+}
+
+/** The events in `text`, one per whole line. Returns what is left of an unfinished last line. */
+export function parseRunEventLines(text: string): { events: RunEvent[]; rest: string } {
+  const events: RunEvent[] = [];
+  const parts = text.split("\n");
+  const rest = parts.pop() ?? "";
+  for (const part of parts) {
+    if (part.trim() === "") continue;
+    try {
+      events.push(JSON.parse(part) as RunEvent);
+    } catch {
+      // A line that is not JSON is not an event: skipped.
+    }
+  }
+  return { events, rest };
+}
+
+/** A stored run, as far as its first line says. */
+export interface StoredRun {
+  runId: string;
+  name: string;
+  file: string;
+  /** The file's last write, in ms. */
+  mtimeMs: number;
+}
+
+/** The runs stored for the checkout at `cwd`, newest first. */
+export async function listStoredRuns(cwd: string): Promise<StoredRun[]> {
+  const dir = await runEventsDir(cwd);
+  if (!dir || !existsSync(dir)) return [];
+  const runs: StoredRun[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const file = join(dir, entry);
+    try {
+      const first = readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+      if (first === "") continue;
+      const head = JSON.parse(first) as Partial<RunEvent>;
+      if (typeof head.runId !== "string") continue;
+      runs.push({ runId: head.runId, name: String(head.name ?? ""), file, mtimeMs: statSync(file).mtimeMs });
+    } catch {
+      // Unreadable or not an event file: not listed.
+    }
+  }
+  return runs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+
+/**
+ * The file for `ref`: a run id, else the name of an Op or a component
+ * selection, for which the newest stored run of that name stands. Null when
+ * nothing matches (a run that has not written its first line yet included).
+ */
+export async function findStoredRun(cwd: string, ref: string): Promise<StoredRun | null> {
+  const dir = await runEventsDir(cwd);
+  if (!dir) return null;
+  const direct = join(dir, runEventFileName(ref));
+  if (existsSync(direct)) {
+    const byId = (await listStoredRuns(cwd)).find((r) => r.file === direct);
+    return byId ?? { runId: ref, name: "", file: direct, mtimeMs: statSync(direct).mtimeMs };
+  }
+  return (await listStoredRuns(cwd)).find((r) => r.name === ref) ?? null;
+}
+
+/** Whether `event` ends a stream. */
+export const isRunSettle = (event: RunEvent): boolean => event.type === "run-settle";
+
+/**
+ * Read `file` from the start and hand each event to `onEvent` (with its raw
+ * line). Without `follow` it stops at the end of the file. With it, it keeps
+ * reading what is appended, by polling every `pollMs`, until `run-settle` is
+ * read, `signal` aborts, or `idleMs` passes with nothing new (when given).
+ * Resolves with the `run-settle` event, or undefined when the stream had
+ * none (a replay of a run still going, or a follow that was cut short).
+ */
+export async function readRunEvents(
+  file: string,
+  onEvent: (event: RunEvent, line: string) => void,
+  opts: { follow?: boolean; pollMs?: number; idleMs?: number; signal?: AbortSignal } = {},
+): Promise<RunEvent | undefined> {
+  const pollMs = opts.pollMs ?? 100;
+  let offset = 0;
+  let rest = "";
+  let lastGrowth = Date.now();
+  for (;;) {
+    let size = 0;
+    try {
+      size = statSync(file).size;
+    } catch {
+      // Not there yet (a follow started before the run opened its file).
+    }
+    if (size > offset) {
+      const buf = readFileSync(file);
+      const chunk = buf.subarray(offset, size).toString("utf8");
+      offset = size;
+      lastGrowth = Date.now();
+      const text = rest + chunk;
+      const parts = text.split("\n");
+      rest = parts.pop() ?? "";
+      for (const part of parts) {
+        if (part.trim() === "") continue;
+        let event: RunEvent;
+        try {
+          event = JSON.parse(part) as RunEvent;
+        } catch {
+          continue;
+        }
+        onEvent(event, `${part}\n`);
+        if (isRunSettle(event)) return event;
+      }
+    } else if (!opts.follow) {
+      return undefined;
+    } else if (opts.signal?.aborted) {
+      return undefined;
+    } else if (opts.idleMs !== undefined && Date.now() - lastGrowth > opts.idleMs) {
+      return undefined;
+    } else {
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, pollMs);
+        opts.signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+      });
+    }
+  }
+}
+
+/** One run's event file, as retention sees it (#4036). */
+export interface RunEventFile {
+  file: string;
+  bytes: number;
+  /** The file's last write, ISO-8601. */
+  modified: string;
+}
+
+/** What {@link planRunEventPrune} would delete and keep. */
+export interface RunEventPrune {
+  /** The directory read, or null outside a checkout. */
+  dir: string | null;
+  remove: RunEventFile[];
+  keep: RunEventFile[];
+}
+
+/**
+ * Which run event files the policy lets go (#4036): every file older than
+ * `days` by its last write, apart from the newest `keep`. A run still going
+ * writes its file as it goes, so it is never older than the window. Reads
+ * only; {@link pruneRunEvents} deletes.
+ */
+export async function planRunEventPrune(cwd: string, policy: { days: number; keep: number }, now: Date): Promise<RunEventPrune> {
+  const dir = await runEventsDir(cwd);
+  if (!dir || !existsSync(dir)) return { dir, remove: [], keep: [] };
+  const files: Array<RunEventFile & { ms: number }> = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const file = join(dir, entry);
+    try {
+      const st = statSync(file);
+      if (!st.isFile()) continue;
+      files.push({ file, bytes: st.size, modified: new Date(st.mtimeMs).toISOString(), ms: st.mtimeMs });
+    } catch {
+      // Gone between the listing and the stat.
+    }
+  }
+  files.sort((a, b) => b.ms - a.ms || (a.file < b.file ? -1 : 1));
+  const cutoff = now.getTime() - policy.days * 86_400_000;
+  const remove: RunEventFile[] = [];
+  const keep: RunEventFile[] = [];
+  files.forEach(({ ms, ...f }, i) => (i >= policy.keep && ms < cutoff ? remove : keep).push(f));
+  return { dir, remove, keep };
+}
+
+/** Delete the files a plan lets go. Returns how many were deleted; a file already gone is not counted. */
+export function pruneRunEvents(plan: RunEventPrune): number {
+  let n = 0;
+  for (const f of plan.remove) {
+    try {
+      rmSync(f.file);
+      n++;
+    } catch {
+      // Already gone.
+    }
+  }
+  return n;
+}