@intentius/chant 0.124.27 → 0.124.28

package/src/op/run-events.test.ts

@@ -0,0 +1,166 @@
+/**
+ * #4041: the local executor's run-event stream (`chant run <op>
+ * --events-json`). Every line passes the schema; each step's start comes
+ * before its settle under the same step id; and the cases an old
+ * `StepRecord` could not tell apart come out as `gated`, `skip: "receipt"`
+ * and `skip: "not-run"`.
+ */
+
+import { describe, expect, test, vi } from "vitest";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { OpRunFailure, runOpLocally, type RunOpOptions } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { receiptActivities, type ReceiptStore } from "./receipt-store";
+import { EffectReceipt, receiptExpectation } from "../effect-receipt";
+import { effect } from "./builders";
+import type { RunEvent } from "../run-event";
+import { checkRunEventLines, stepKey, stepTrail } from "../workspace/__fixtures__/run-event-check";
+
+vi.mock("./gate", async () => {
+  const actual = await vi.importActual<typeof import("./gate")>("./gate");
+  return { ...actual, gateIsSealed: async () => false };
+});
+
+const PROFILES: Record<string, ActivityProfile> = { fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } } };
+const NOW = "2026-10-16T12:00:00.000Z";
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+
+const op = (partial: Partial<OpConfig>): OpConfig => ({ name: "deploy-api", overview: "", phases: [], ...partial });
+const ok: ActivityFn = async () => ({ done: true });
+
+/** Run an Op with its events captured, settling whether it resolves or rejects. */
+async function run(config: OpConfig, activities: Map<string, ActivityFn>, options: RunOpOptions = {}) {
+  const lines: string[] = [];
+  let status: string;
+  try {
+    status = (await runOpLocally(config, activities, PROFILES, undefined, {
+      gates: memoryGateLedgerPort(),
+      now: NOW,
+      runId: "local-1",
+      commit: SHA,
+      runEvents: { write: (l) => lines.push(l) },
+      ...options,
+    })).status;
+  } catch (err) {
+    if (!(err instanceof OpRunFailure)) throw err;
+    status = err.result.status;
+  }
+  return { status, events: checkRunEventLines(lines) };
+}
+
+describe("the local runtime's run events", () => {
+  test("a run that passes: run, phases and steps, each step started before it settles, named as the run record names it", async () => {
+    const { status, events } = await run(
+      op({ phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }] }, { name: "Ship", steps: [{ kind: "activity", fn: "push" }] }] }),
+      new Map([["make", ok], ["push", ok]]),
+    );
+    expect(status).toBe("ok");
+    // In a CI job the run keeps its own id and names the CI run as its origin, as its run record does (#4020).
+    const ci = Boolean(process.env.GITHUB_RUN_ID || process.env.CI_PIPELINE_ID);
+    expect(events[0]).toMatchObject({ runId: "local-1", kind: "op", name: "deploy-api", gitSha: SHA, runtime: ci ? "ci" : "local" });
+    expect(events[0]!.runOrigin.forge).toBe(process.env.GITHUB_RUN_ID ? "github" : process.env.CI_PIPELINE_ID ? "gitlab" : "local");
+    expect(events.map((e) => e.type)).toEqual([
+      "run-start",
+      "phase-start", "step-start", "step-settle", "phase-settle",
+      "phase-start", "step-start", "step-settle", "phase-settle",
+      "run-settle",
+    ]);
+    expect(events.at(-1)).toMatchObject({ status: "ok" });
+  });
+
+  test("a step's start is emitted before its settle, with the same step id", async () => {
+    const { events } = await run(
+      op({ phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }, { kind: "activity", fn: "make" }] }] }),
+      new Map([["make", ok]]),
+    );
+    const steps = events.filter((e): e is Extract<RunEvent, { type: "step-start" | "step-settle" }> => e.type === "step-start" || e.type === "step-settle");
+    // Two steps of one phase share a name; the index keeps them apart.
+    expect(steps.map((e) => [e.type, stepKey(e)])).toEqual([
+      ["step-start", JSON.stringify([null, "Build", "make", 0])],
+      ["step-settle", JSON.stringify([null, "Build", "make", 0])],
+      ["step-start", JSON.stringify([null, "Build", "make", 1])],
+      ["step-settle", JSON.stringify([null, "Build", "make", 1])],
+    ]);
+    expect(steps[0]!.seq).toBeLessThan(steps[1]!.seq);
+  });
+
+  test("a parallel phase starts each step before any settles, and tells two steps of one name apart by index", async () => {
+    const { events } = await run(
+      op({ phases: [{ name: "Fan", parallel: true, steps: [{ kind: "activity", fn: "probe", args: { at: 1 } }, { kind: "activity", fn: "probe", args: { at: 2 } }] }] }),
+      new Map([["probe", ok]]),
+    );
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "probe"], ["step-start", "probe"], ["step-settle", "probe", "ok"], ["step-settle", "probe", "ok"],
+    ]);
+    expect(events.filter((e) => e.type === "step-settle").map((e) => (e as { index?: number }).index)).toEqual([0, 1]);
+  });
+
+  test("an unapproved gate settles gated after gate-waiting; the steps after it settle skipped as not-run", async () => {
+    const { status, events } = await run(
+      op({ phases: [{ name: "Ship", steps: [{ kind: "activity", fn: "before" }, { kind: "gate", gate: "approve-prod" }, { kind: "activity", fn: "after" }] }] }),
+      new Map([["before", ok], ["after", ok]]),
+    );
+    expect(status).toBe("gated");
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "before"], ["step-settle", "before", "ok"],
+      ["step-start", "gate:approve-prod"], ["gate-waiting", "gate:approve-prod"], ["step-settle", "gate:approve-prod", "gated"],
+      ["step-settle", "after", "skipped:not-run"],
+    ]);
+    expect(events.find((e) => e.type === "gate-waiting")).toMatchObject({ op: "deploy-api", gate: "approve-prod", point: null, index: 1 });
+    expect(events.find((e) => e.type === "phase-settle")).toMatchObject({ status: "gated" });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "gated" });
+  });
+
+  test("an approved gate resolves, naming who approved it", async () => {
+    const gates = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "deploy-api", gate: "approve-prod", resolvedBy: "alex", timestamp: "2026-10-16T11:00:00.000Z" }],
+    });
+    const { status, events } = await run(op({ phases: [{ name: "Ship", steps: [{ kind: "gate", gate: "approve-prod" }] }] }), new Map(), { gates });
+    expect(status).toBe("ok");
+    expect(events.find((e) => e.type === "gate-resolved")).toMatchObject({ gate: "approve-prod", resolvedBy: "alex", via: null, index: 0 });
+  });
+
+  test("a failed step fails its phase and the run, with its error, and the rest of its phase is not-run", async () => {
+    const boom: ActivityFn = async () => { throw new Error("disk full"); };
+    const { status, events } = await run(
+      op({ phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }, { kind: "activity", fn: "pack" }] }] }),
+      new Map([["make", boom], ["pack", ok]]),
+    );
+    expect(status).toBe("fail");
+    expect(stepTrail(events)).toEqual([["step-start", "make"], ["step-settle", "make", "failed"], ["step-settle", "pack", "skipped:not-run"]]);
+    expect(events.find((e) => e.type === "phase-settle")).toMatchObject({ status: "failed" });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed", error: "disk full" });
+  });
+
+  test("an effect whose receipt matched settles its steps skipped with skip: receipt", async () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { version: 3 } });
+    const values = new Map<string, string>([["seeded", receiptExpectation(seeded)]]);
+    const store: ReceiptStore = {
+      read: async (r) => values.get(r.name),
+      write: async (r, e) => void values.set(r.name, e),
+    };
+    const { receiptRead, receiptWrite } = receiptActivities(store);
+    const { status, events } = await run(
+      op({ phases: [{ name: "Seed", steps: [effect(seeded, [{ kind: "activity", fn: "seed" }])] }] }),
+      new Map<string, ActivityFn>([["seed", ok], ["receiptRead", receiptRead as unknown as ActivityFn], ["receiptWrite", receiptWrite as unknown as ActivityFn]]),
+    );
+    expect(status).toBe("ok");
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "receiptRead"], ["step-settle", "receiptRead", "ok"],
+      ["step-settle", "seed", "skipped:receipt"],
+    ]);
+  });
+
+  test("a run that throws before its first phase still ends its stream, failed with the reason", async () => {
+    const lines: string[] = [];
+    await expect(
+      runOpLocally(op({ phases: [{ name: "P", parallel: true, steps: [effect(EffectReceipt("r", { effect: "e", flavor: "existence", inputs: {} }), [])] }] }), new Map(), PROFILES, undefined, {
+        gates: memoryGateLedgerPort(), now: NOW, commit: SHA, runEvents: { write: (l) => lines.push(l) },
+      }),
+    ).rejects.toThrow(/cannot run in a parallel phase/);
+    const events = checkRunEventLines(lines);
+    expect(events.map((e) => e.type)).toEqual(["run-start", "run-settle"]);
+    expect(events.at(-1)).toMatchObject({ status: "failed", error: expect.stringMatching(/cannot run in a parallel phase/) });
+  });
+});

package/src/op/run-live.ts

@@ -86,7 +86,7 @@ function keyOf(prefix: string, env: string, op: string): string {
 }
 
 /** The checkout's shared git directory (the same for every worktree), or null outside a checkout. */
-async function gitCommonDir(cwd: string): Promise<string | null> {
+export async function gitCommonDir(cwd: string): Promise<string | null> {
   try {
     const { stdout } = await execFileAsync("git", ["rev-parse", "--git-common-dir"], { cwd });
     const dir = stdout.trim();

package/src/op/runtime.ts

@@ -20,6 +20,7 @@ import type { OpConfig } from "./types";
 import type { StepRecord, OpRunResult } from "./local-executor";
 import type { WaitingPoint } from "./steward-points";
 import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import type { RunOrigin } from "../lifecycle/release-ledger";
 import type { RunComponentsOptions, RunComponentsResult } from "../components/cli-support";
 
 /**
@@ -159,6 +160,29 @@ export interface OpRunRecord {
    * first phase.
    */
   resumed?: { gate: string; run: string; checkpoint: string };
+  /**
+   * The commit the run built from (#4020): the checkout's `HEAD`, else the
+   * commit the CI job started for. Gate facts the run writes carry the same
+   * commit, so a run and its gate join on it. Absent on a record written
+   * before 0.124.28 and when the run knew no commit.
+   */
+  gitSha?: string;
+  /**
+   * The CI run this Op ran in (#4020), as a deploy record's `runOrigin` names
+   * its run, so the two name a run the same way. `id` is still the Op's own
+   * run id. Absent outside CI and on a record written before 0.124.28.
+   */
+  runOrigin?: RunOrigin;
+  /**
+   * The run's statement (#4044): a DSSE envelope over an in-toto statement
+   * (`https://intentius.io/chant/op-run/v1`) a runner key signed at the end
+   * of the run, naming the run, its commit and the SHA-256 of this record
+   * without the statement (`../workspace/trust/op-run-statement.ts`).
+   * `chant ci tick` with `ci.green.source: "runs"` counts only a run that
+   * carries one. Absent on a run given no runner key, and on a record
+   * written before 0.124.28.
+   */
+  statement?: { payloadType: string; payload: string; signatures: { keyid: string; sig: string }[] };
 }
 
 /** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */
@@ -187,6 +211,14 @@ export interface OpRunStartOptions {
   profile?: string;
   /** Called once per settled step, so `--progress-json` can stream. */
   progress?: (record: StepRecord) => void;
+  /**
+   * Where the run's event stream goes (#4041, `--events-json`): one
+   * `run-event.schema.json` line at a time, written through the one writer
+   * (`createRunEventWriter`). The local runtime writes `runtime: "local"`
+   * events (`ci` in a CI job); a hosted runtime writes its own, as fountain
+   * writes `runtime: "steward"` ones. A runtime that cannot stream omits it.
+   */
+  runEvents?: (line: string) => void;
   /** Aborts in-flight work (Ctrl-C). */
   signal?: AbortSignal;
   /**
@@ -205,6 +237,13 @@ export interface OpRunStartOptions {
    * and the run `chant run status --on fountain` reports carry the same id.
    */
   runId?: string;
+  /**
+   * Signs the run's record when it settles (#4044), for `chant run <op>
+   * --key` or `CHANT_RUNNER_KEY`: the local runtime stores what it returns
+   * on the record as `statement`. A runtime that writes no record here
+   * ignores it.
+   */
+  signRecord?: (record: OpRunRecord) => NonNullable<OpRunRecord["statement"]>;
 }
 
 /** What a caller hands {@link OpRuntimeProvider.resolveGate} besides the resolution. */

package/src/op/runtimes/local.test.ts

@@ -51,6 +51,7 @@ vi.mock("../../lifecycle/run-ledger", async () => {
 });
 
 const { createLocalOpRuntime } = await import("./local");
+const { checkRunEventLines, stepTrail } = await import("../../workspace/__fixtures__/run-event-check");
 
 function op(name: string, steps: unknown[]): OpConfig {
   return {
@@ -145,6 +146,21 @@ describe("the local op runtime", () => {
     expect(seen).toEqual(["ok", "ok"]);
   });
 
+  test("runEvents gets the run's event stream, named by the handle's run id (#4041)", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
+    const runtime = createLocalOpRuntime();
+    const lines: string[] = [];
+
+    const handle = await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), { runEvents: (l) => lines.push(l) });
+    await handle.result();
+
+    const events = checkRunEventLines(lines);
+    expect(events[0]).toMatchObject({ type: "run-start", runId: handle.runId, kind: "op", name: "hello" });
+    expect(events[0]!.runtime).toBe(process.env.GITHUB_RUN_ID || process.env.CI_PIPELINE_ID ? "ci" : "local");
+    expect(stepTrail(events)).toEqual([["step-start", "ok"], ["step-settle", "ok", "ok"]]);
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+  });
+
   test("a gated Op settles as gated, naming the gate, and runs nothing after it (#2119)", async () => {
     const after = vi.fn(async () => ({}));
     loadActivitiesMock.mockResolvedValue(new Map([["after", after]]));

package/src/op/runtimes/local.ts

@@ -176,6 +176,15 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
                     `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`,
                 ),
               ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+              ...(startOpts.runEvents ? { runEvents: { write: startOpts.runEvents } } : {}),
+              // #4044: a runner key signs the record as the run settles.
+              ...(startOpts.signRecord
+                ? {
+                    signRecord: startOpts.signRecord,
+                    onSignError: (err: unknown) =>
+                      process.stderr.write(`warning: run "${runId}" of "${op.name}" was not signed: ${err instanceof Error ? err.message : String(err)}\n`),
+                  }
+                : {}),
               // #3956: a running step's output, and a still-running line while
               // it is quiet, on stderr as they happen; stdout stays the
               // `--json` record's and `--progress-json`'s.

package/src/point-decision.ts

@@ -36,7 +36,7 @@ import { parseDuration } from "./op/duration";
 import type { GateLedgerPort } from "./op/gate";
 import { DEFAULT_GATE_POINT_PASS, defaultGatePointStore, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts, type GatePointStore } from "./op/gate-point";
 import type { WaitingPoint } from "./op/steward-points";
-import { resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
+import { ciCommitFromEnv, ciRunIdFromEnv, resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
 import { refuseGateWithoutRecording } from "./lifecycle/no-record";
 
 export {
@@ -102,6 +102,13 @@ export interface GatePointAsker {
   ask(request: GatePointRequest): Promise<GatePointQuestion>;
 }
 
+/** The run and commit a gate record names (#4020): the input's own, else the CI job's. */
+function runStamp(input: { runId?: string; gitSha?: string }): { runId?: string; gitSha?: string } {
+  const runId = input.runId || ciRunIdFromEnv();
+  const gitSha = input.gitSha || ciCommitFromEnv();
+  return { ...(runId ? { runId } : {}), ...(gitSha ? { gitSha } : {}) };
+}
+
 /** What the run needs to decide a gate that asks a point. */
 export interface PointGateInput {
   op: string;
@@ -112,6 +119,8 @@ export interface PointGateInput {
   description?: string;
   timeout?: string;
   runId?: string;
+  /** The commit the run is at (#4020). Default: the commit the CI job started for, when it runs in CI. */
+  gitSha?: string;
   planDigest?: string;
   /** The environment the run was started for: the `gate.env` input. Op gate facts on the ledger record none. */
   env?: string;
@@ -202,6 +211,7 @@ export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePo
       resolvedBy: resolvedByOf(q),
       timestamp: now,
       note: `answered through decision point ${q.point} (${q.id})`,
+      ...runStamp(input),
       ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
       approver: { kind: q.decider === "quorum" || q.answeredBy.length > 0 ? "human" : "agent" },
       answer,
@@ -228,7 +238,7 @@ export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePo
     timestamp: now,
     expiresAt: new Date(new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY)).toISOString(),
     ...(input.description ? { description: input.description } : {}),
-    ...(input.runId ? { runId: input.runId } : {}),
+    ...runStamp(input),
     ...(url ? { url } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
     ...(resume ? { resume } : {}),

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();
+  });
+});