@intentius/chant 0.124.31 → 0.124.32

package/src/workspace/ci-run-index.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json",
   "title": "chant ci run index",
-  "description": "The runs the chant runner has run, kept at <report-url>/runs/index.json (#4098, epic #4101) so a reader outside CI finds them without a forge or a workflow file. `chant ci run` adds an entry to the front after each job settles when --report-url is set, so the list is newest first, and keeps the newest 200 entries unless --run-index-limit says otherwise. `chant ci runs --json` prints the same document. An entry's `key` is the folder the job's report is under, below the report URL. The update is a read, a change and a write of the whole file, through the same s3:// and file:// paths the report upload uses; a file:// write goes through a temporary name and a rename. Two runners updating one index at once can lose an entry. That is out of scope, because `chant ci serve` is one host. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version. Written by chant 0.124.31 and newer.",
+  "description": "The runs the chant runner has run, kept at <report-url>/runs/index.json (#4098, epic #4101) so a reader outside CI finds them without a forge or a workflow file. `chant ci run` adds an entry to the front after each job settles when --report-url is set, so the list is newest first, and keeps the newest 200 entries unless --run-index-limit says otherwise. `chant ci runs --json` prints the same document. An entry's `key` is the folder the job's report is under, below the report URL. The update is a read, a change and a write of the whole file, through the same s3:// and file:// paths the report upload uses; a file:// write goes through a temporary name and a rename. Two runners updating one index at once can lose an entry. That is out of scope, because `chant ci serve` is one host. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version. Written by chant 0.124.31 and newer. Added within contract 1 at chant 0.124.32: an entry's signer (#4156) and exitCode (#4165); an entry from an older chant lacks them.",
   "type": "object",
   "required": ["$schema", "contract", "chant", "updated", "runs"],
   "properties": {
@@ -38,11 +38,13 @@
         "ended": { "type": "string", "description": "ISO-8601 instant the job settled." },
         "runId": { "type": "string", "description": "The Op run id, as in the run ledger on chant/lifecycle." },
         "key": { "type": "string", "description": "reportKey(pr, commit): <pr>/<commit>, with /<member> after for a member, and unknown for a missing pr. The job's report is <report-url>/<key>/pr-<job>.json." },
+        "signer": { "type": ["string", "null"], "description": "Added within contract 1 by #4156, written by chant 0.124.32 and newer. The runner whose key signed the run's record, or null for an unsigned run. Signing is optional, and an unsigned run is listed like any other." },
+        "exitCode": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Added within contract 1 by #4165, written by chant 0.124.32 and newer. The code chant ci run exited with for the job: 0 for a passed job, else the command's own code when it is 1 to 255, such as 3 for a plan that moved after review or a wave waiting at its gate, else 1. A reader tells a held run from a failed one by it when the report carries no refusal. An entry from an older chant lacks it." },
         "runOrigin": {
           "type": "object",
           "required": ["forge"],
-          "description": "Where the run says it ran. { forge: \"chant\" } for a job the chant runner ran.",
-          "properties": { "forge": { "type": "string" } }
+          "description": "Where the run says it ran. { forge: \"chant\" } for a job the chant runner ran. From chant 0.124.32 a forge job that runs chant ci run names the forge's run (#4156): forge github (GitHub and Forgejo) or gitlab, with repo, url, jobId and attempt when the forge gives them.",
+          "properties": { "forge": { "type": "string" }, "repo": { "type": "string" }, "url": { "type": "string" }, "jobId": { "type": "string" }, "attempt": { "type": "integer", "minimum": 1 } }
         }
       }
     }

package/src/workspace/ci-run-index.test.ts

@@ -12,7 +12,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, contract, declaration, git, repoFixture, scratchDir, validSchema, writeFiles } from "./__fixtures__/contract-repo";
-import { ciRun } from "./ci-run";
+import { ciJobExitCode, ciRun } from "./ci-run";
 import { readCiSecrets } from "./ci-secrets";
 import {
   addRunEntry,
@@ -123,6 +123,13 @@ describe("the ci-run-index schema (#4098)", () => {
     expect(contract(schema).validate(doc)).toBe(false);
     expectValid({ ...doc, runs: [{ ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
   });
+
+  test("exitCode is an integer from 0 to 255, and an index whose older entries lack it validates (#4165)", () => {
+    const doc = { $schema: CI_RUN_INDEX_SCHEMA_ID, contract: 1, chant: "0.124.32", updated: "2026-10-18T12:00:00.000Z" };
+    // A newer entry beside two from chant 0.124.31, which wrote neither signer nor exitCode.
+    expectValid({ ...doc, runs: [{ ...ENTRY, runId: "r2", signer: null, exitCode: 0 }, { ...ENTRY, runId: "r1" }, { ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
+    for (const exitCode of [-1, 256, 1.5, "3"]) expect(contract(schema).validate({ ...doc, runs: [{ ...ENTRY, exitCode }] })).toBe(false);
+  });
 });
 
 describe("chant ci run with --report-url keeps the run index (#4098)", () => {
@@ -149,6 +156,10 @@ describe("chant ci run with --report-url keeps the run index (#4098)", () => {
       key: `7/${w.sha}/app`,
       member: "app",
       runOrigin: { forge: "chant" },
+      // #4156: no key, and the run is listed all the same, with no signer.
+      signer: null,
+      // #4165: the code ci run exited with.
+      exitCode: 0,
     });
     // The apply found its pull request in its own report.
     expect(index.runs[0]).toMatchObject({ job: "apply", pr: 7, key: `7/${w.sha}/app` });
@@ -179,7 +190,7 @@ describe("chant ci run with --report-url keeps the run index (#4098)", () => {
     const failed = await job(w, dir, { runId: "run-fail", hostEnv: { ...HOST, FAKE_EXIT: "3" }, passEnv: ["FAKE_EXIT"] });
     expect(failed.status).toBe("fail");
     const [run] = indexOf(dir).runs;
-    expect(run).toMatchObject({ status: "fail", failure: { code: "command-failed" }, runId: "run-fail" });
+    expect(run).toMatchObject({ status: "fail", failure: { code: "command-failed" }, runId: "run-fail", exitCode: 3 });
     expectValid(indexOf(dir));
 
     const refused = await job(w, dir, {
@@ -189,7 +200,35 @@ describe("chant ci run with --report-url keeps the run index (#4098)", () => {
       passEnv: ["FAKE_EXIT", "FAKE_REPORT"],
     });
     expect(refused.status).toBe("fail");
-    expect(indexOf(dir).runs[0]).toMatchObject({ failure: { code: "not-approved" } });
+    expect(indexOf(dir).runs[0]).toMatchObject({ failure: { code: "not-approved" }, exitCode: 1 });
+  });
+
+  test("each entry records the code ci run exited with: 0, 1, and 3 for a moved plan or a waiting wave (#4165)", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const run = (runId: string, exit: string, report: object) =>
+      job(w, dir, { job: "apply", runId, hostEnv: { ...HOST, FAKE_EXIT: exit, FAKE_REPORT: JSON.stringify({ pr: 7, ...report }) }, passEnv: ["FAKE_EXIT", "FAKE_REPORT"] });
+    const passed = await run("run-ok", "0", { status: "applied" });
+    const failed = await run("run-failed", "1", { status: "failed" });
+    const moved = await run("run-moved", "3", { status: "refused", refusal: "plan-changed", message: "the plan changed after review" });
+    const waiting = await run("run-waiting", "3", { status: "waiting", waves: [{ wave: 2, status: "waiting" }] });
+    expect([passed, failed, moved, waiting].map((r) => ciJobExitCode(r))).toEqual([0, 1, 3, 3]);
+    const index = indexOf(dir);
+    expectValid(index);
+    expect(index.runs.map((r) => [r.runId, r.status, r.exitCode])).toEqual([
+      ["run-waiting", "fail", 3],
+      ["run-moved", "fail", 3],
+      ["run-failed", "fail", 1],
+      ["run-ok", "ok", 0],
+    ]);
+    expect(index.runs[1]!.failure).toEqual({ code: "plan-changed" });
+  });
+
+  test("a fail with no code from its command, or one outside 1 to 255, is 1, and a pass is 0 (#4165)", () => {
+    expect(ciJobExitCode({ status: "fail" })).toBe(1);
+    expect(ciJobExitCode({ status: "fail", exitCode: 0 })).toBe(1);
+    expect(ciJobExitCode({ status: "fail", exitCode: 300 })).toBe(1);
+    expect(ciJobExitCode({ status: "ok", exitCode: 3 })).toBe(0);
   });
 
   test("a secret the job's report names as its failure never reaches the index (#4096)", async () => {

package/src/workspace/ci-run-index.ts

@@ -29,6 +29,7 @@
 import type { RunOrigin } from "../lifecycle/release-ledger";
 import type { CommandContext } from "../cli/registry";
 import { formatError } from "../cli/format";
+import { reportUrlOf } from "./ci-report-url";
 import { parseReportUrl, reportGet, reportPut, type ReportGet, type ReportPut, type ReportTarget } from "../pr-report-url";
 import { readerVersion } from "./declaration";
 
@@ -57,6 +58,18 @@ export interface CiRunIndexEntry {
   /** The folder the job's report is under, below the report URL: `<pr>/<commit>[/<member>]`. */
   key: string;
   runOrigin: RunOrigin;
+  /**
+   * The runner whose key signed the run's record, or null for an unsigned
+   * run (#4156). Written by chant 0.124.32 and newer; an entry from an older
+   * chant lacks it.
+   */
+  signer?: string | null;
+  /**
+   * The code `chant ci run` exited with for the job: 0, its command's own
+   * code such as 3 for a moved plan or a waiting wave, else 1 (#4165).
+   * Written by chant 0.124.32 and newer; an entry from an older chant lacks it.
+   */
+  exitCode?: number;
 }
 
 export interface CiRunIndex {
@@ -167,18 +180,19 @@ export function formatCiRunIndex(index: CiRunIndex): string {
     .map((r) => {
       const pr = r.pr === null ? "no PR" : `PR ${r.pr}`;
       const why = r.status === "fail" ? ` (${r.failure?.code ?? "failed"})` : "";
-      return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}`;
+      return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}${r.signer ? `  signed by ${r.signer}` : ""}`;
     })
     .join("\n");
 }
 
-const RUNS_USAGE = "chant ci runs --report-url <s3://<bucket>/<prefix> | file://<directory>> [--json]";
+const RUNS_USAGE = "chant ci runs [--report-url <s3://<bucket>/<prefix> | file://<directory>>] [--json]";
 
 /** `chant ci runs` (#4098): list the index at the report URL. */
 export async function runCiRuns(ctx: CommandContext): Promise<number> {
   try {
-    const raw = ctx.args.reportUrl;
-    if (!raw) throw new Error("--report-url names where the index is kept");
+    // #4160: without --report-url, the declaration's ci.reportUrl.
+    const raw = await reportUrlOf(ctx.args.reportUrl, process.cwd());
+    if (!raw) throw new Error("--report-url names where the index is kept, unless the workspace declares ci.reportUrl");
     const target = parseReportUrl(raw);
     if ("error" in target) throw new Error(target.error);
     const index = await readCiRunIndex(target);

package/src/workspace/ci-run.test.ts

@@ -17,9 +17,9 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { cleanScratch, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
 import { checkRunEventLines } from "./__fixtures__/run-event-check";
-import { ciJobCommand, ciJobEnv, ciJobFailure, ciJobOp, ciRun, CiRunError, ciStatusContext, ciStatusFromEnv, ciStatusUrl, formatCiRun } from "./ci-run";
+import { ciJobCommand, ciJobEnv, ciJobFailure, ciJobOp, ciLoopOptions, ciRun, CiRunError, ciStatusContext, ciStatusFromEnv, ciStatusUrl, formatCiRun } from "./ci-run";
 import type { CommitStatus } from "../pr-forge";
-import { ciTick, evaluateCommit, readOpRunSource, revokedAnnotation } from "./ci-green";
+import { ciList, ciTick, evaluateCommit, readOpRunSource, revokedAnnotation } from "./ci-green";
 import type { StepRecord } from "../op/local-executor";
 import { sshFromEd25519 } from "./trust/dsse";
 import { verifyOpRunStatement } from "./trust/op-run-statement";
@@ -199,6 +199,20 @@ describe("the job as an Op (#4094)", () => {
     expect(args).toMatchObject({ command: "ci", path: "run", extraPositional: "apply", env: "prod", base: "abc", commit: "def", passEnv: ["AWS_PROFILE", "AWS_REGION"], ciChant: "npx chant", key: "k.pem" });
     expect(() => parseArgs(["ci", "run", "plan", "--commit"])).toThrow(/--commit needs/);
   });
+
+  test("--wave-gate (#4003): the apply job runs pr-apply --wave-gate, the waves in order with no --wave, and the plan passes the gate for its note", () => {
+    for (const path of ["run", "serve"]) {
+      const args = parseArgs(["ci", path, ...(path === "run" ? ["apply"] : []), "--env", "prod", "--gate", "infra", "--wave-gate", "release"]);
+      expect(ciLoopOptions(args)).toEqual({ gate: "infra", waveGate: "release" });
+    }
+    const [plan, apply] = prLoopJobs("forgejo", "prod", ciLoopOptions(parseArgs(["ci", "run", "apply", "--env", "prod", "--wave-gate", "release"])));
+    expect(apply!.command).toContain("--require-review --wave-gate release --resume .chant/pr-resume/pr-apply.json");
+    expect(apply!.command).not.toContain("--wave ");
+    expect(plan!.command).toContain("--wave-gate release");
+    expect(plan!.command).not.toContain("--wave ");
+    const op = ciJobOp({ job: apply!, env: "prod", cwd: "/w", jobEnv: {}, setup: [], build: [] });
+    expect(op.phases.map((p) => p.name)).toEqual(["apply"]);
+  });
 });
 
 describe("chant ci run, then ci tick from runs (#4094)", () => {
@@ -296,8 +310,8 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
     expect(record.phases.apply![0]).toMatchObject({ name: "pr-apply", opRun: { id: apply.record.id, signer: "chant-runner" } });
   });
 
-  test("a failing job is recorded failed, and a key from the environment that trust.json does not list leaves it unsigned", async () => {
-    const { app, base } = workspace();
+  test("a failing job is recorded failed, and a key from the environment that trust.json does not list leaves it unsigned, quietly", async () => {
+    const { root, app, base } = workspace();
     const stranger = runnerKey();
     const lines: string[] = [];
     const r = await ciRun({ image: JOB_IMAGE,
@@ -319,17 +333,30 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
     expect(r.record.status).toBe("fail");
     expect(r.record.statement).toBeUndefined();
     expect(r.signer).toBeNull();
-    expect(r.warnings[0]).toMatch(/CHANT_RUNNER_KEY is set, and the run will not be signed: .*lists no runner with this key/);
+    // #4156: signing is opt-in, so an unlisted key is a note for --verbose, not a warning.
+    expect(r.warnings).toEqual([]);
+    expect(r.notes[0]).toMatch(/CHANT_RUNNER_KEY is set, and the run will not be signed: .*lists no runner with this key/);
+    // The command's exit code is the job's, as a forge job's was before it ran through ci run.
+    expect(r.exitCode).toBe(3);
     expect(r.failure).toMatchObject({ phase: "apply", error: expect.stringContaining("command exited 3") });
     // The report says nothing about a failure, so the record names the command.
     expect(r.record.failure).toMatchObject({ code: "command-failed", phase: "apply", exitCode: 3, reason: expect.stringContaining("command exited 3") });
     expect(lines.some((l) => l.includes("fake pr-apply ran"))).toBe(true);
     expect(r.report).not.toBeNull();
-    expect(formatCiRun(r)).toContain("unsigned, so ci tick from runs does not count it");
+    expect(formatCiRun(r)).toContain("on chant/lifecycle, unsigned");
 
-    // The same key given with --key refuses the run before anything runs.
+    // The same key given with --key refuses the run before anything runs, and so does a key that is not one.
     await expect(ciRun({ image: JOB_IMAGE, cwd: app, job: "apply", env: "prod", forge: "github", base, chant: fakeChant(), hostEnv: HOST, runnerKey: stranger.pem, push: false })).rejects.toThrow(/would not be signed/);
+    await expect(ciRun({ image: JOB_IMAGE, cwd: app, job: "apply", env: "prod", forge: "github", base, chant: fakeChant(), hostEnv: HOST, runnerKey: "not a key", runnerKeyFromEnv: true, push: false })).rejects.toThrow(/in CHANT_RUNNER_KEY is not an Ed25519 private key in PEM/);
     expect((await readRunLedger("prod", "pr-apply", { cwd: app })).records).toHaveLength(1);
+
+    // With ci.green.signedSince the same run warns, and so does one with no key.
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: { ...GREEN, signedSince: base } } }) });
+    const opted = { image: JOB_IMAGE, cwd: app, job: "apply" as const, env: "prod", forge: "github" as const, base, chant: fakeChant(), hostEnv: HOST, push: false, output: join(scratchDir("chant-ci-run-out-"), "pr") };
+    const warned = await ciRun({ ...opted, runnerKey: stranger.pem, runnerKeyFromEnv: true });
+    expect(warned.warnings[0]).toMatch(/CHANT_RUNNER_KEY is set, and the run will not be signed: [\s\S]*, and ci.green.signedSince is [0-9a-f]{40}, so it will not count/);
+    const keyless = await ciRun(opted);
+    expect(keyless.warnings).toEqual([expect.stringMatching(/^there is no runner key, so the run's record is unsigned, and ci.green.signedSince is/)]);
   });
 
   test("--pr-build runs the job's build and lint lines after --before-script and before the command, and a failing build fails the job", async () => {
@@ -714,3 +741,154 @@ describe("the job's secrets from the host (#4096)", () => {
     expect(formatCiRun(r)).toContain("not-approved in apply, exit 3: the deploy failed with ***");
   });
 });
+
+describe("a generated forge job runs ci run --in-place (#4156)", () => {
+  // What a GitHub or Forgejo job has in its environment: the forge's run, job and attempt, and the secret.
+  const FORGE = { GITHUB_RUN_ID: "4242", GITHUB_RUN_ATTEMPT: "2", GITHUB_JOB: "apply", GITHUB_REPOSITORY: "acme/estate", GITHUB_SERVER_URL: "http://forgejo.localhost" };
+
+  test("the generated job's line parses to the same job, and --in-place, --no-push, --no-require-review and --wave reach it", () => {
+    const [plan, apply] = prLoopJobs("forgejo", "prod", { events: true, reportUrl: "s3://b/p", requireReview: false, waveGate: "release", branch: "trunk" });
+    expect(plan!.run.command).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge forgejo --wave-gate release --events-json --report-url "s3://b/p"');
+    const args = parseArgs(apply!.run.command.replace(/"\$BASE_SHA"/, "b".repeat(40)).replace(/"/g, "").split(" ").slice(1).concat(["--wave", "2"]));
+    expect(args).toMatchObject({ ciInPlace: true, requireReview: false, wave: 2, waveGate: "release", branch: "trunk", eventsJson: true, reportUrl: "s3://b/p" });
+    expect(ciLoopOptions(args)).toEqual({ gate: "pr-apply", branch: "trunk", events: true, reportUrl: "s3://b/p", waveGate: "release", requireReview: false });
+    expect(parseArgs(["ci", "run", "plan", "--no-push"]).noPush).toBe(true);
+    // ci run rebuilds pr-apply from those options: the very command the job ran before #4156.
+    expect(prLoopJobs("forgejo", "prod", ciLoopOptions(args))[1]!.command).toBe(apply!.command);
+    expect(apply!.run.env.CHANT_RUNNER_KEY).toBe("${{ secrets.CHANT_RUNNER_KEY }}");
+  });
+
+  test("in the job's own checkout, with its environment less the key, a signed record names the forge's run and verifies, and ci list sees it", async () => {
+    const { root, app, base, sha } = workspace();
+    const chant = fakeChant();
+    const before = git(root, "worktree", "list", "--porcelain");
+    const r = await ciRun({ cwd: app, job: "apply", env: "prod", forge: "forgejo", base, chant, hostEnv: { ...HOST, ...FORGE }, runnerKey: BOT.pem, runnerKeyFromEnv: true, inPlace: true, runId: "forge-apply-1" });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toEqual([]);
+    expect(r.signer).toBe("chant-runner");
+    expect(r.pushed).toBe(true);
+
+    // In place: no worktree, the report where the forge keeps it, and no setup phase.
+    expect(git(root, "worktree", "list", "--porcelain")).toBe(before);
+    expect(readFileSync(join(app, ".chant/pr/pr-apply.pwd"), "utf-8").trim()).toBe(realpathSync(app));
+    expect(r.report).toBe(join(realpathSync(app), ".chant/pr"));
+    expect(r.record.phases.map((p) => p.name)).toEqual(["apply"]);
+    const argv = readFileSync(join(app, ".chant/pr/pr-apply.args"), "utf-8").trimEnd().split("\n");
+    expect(argv).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--require-review", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    // The forge job's whole environment reaches the step, but never the runner key.
+    const env = envFile(join(app, ".chant/pr"), "pr-apply");
+    expect(env).toMatchObject({ NOT_FOR_JOBS: "leak", GITHUB_RUN_ID: "4242", BASE_SHA: base, GITHUB_SHA: sha });
+    expect(env).not.toHaveProperty("CHANT_RUNNER_KEY");
+
+    // The record: the forge's run, job and attempt as runOrigin, signed, and it verifies against trust.json.
+    const origin = { forge: "github", repo: "acme/estate", url: "http://forgejo.localhost/acme/estate/actions/runs/4242", jobId: "apply", attempt: 2 };
+    expect(r.record).toMatchObject({ op: "pr-apply", gitSha: sha, id: "forge-apply-1", runOrigin: origin });
+    const stored = (await readRunLedger("prod", "pr-apply", { cwd: app })).records.at(-1)!;
+    expect(verifyOpRunStatement(stored, RUNNERS, { runner: ["chant-runner"] })).toMatchObject({ status: "signed", signer: "chant-runner" });
+    expect(git(root, "ls-remote", "origin", "chant/lifecycle")).toContain(git(root, "rev-parse", "chant/lifecycle"));
+
+    const list = (await ciList({ cwd: app, now: NOW })) as Extract<Awaited<ReturnType<typeof ciList>>, { commits: unknown }>;
+    const listed = list.commits.find((c) => c.sha === sha)!;
+    expect(listed.phases.find((p) => p.phase === "apply")!.runs).toEqual([expect.objectContaining({ name: "pr-apply", opRun: { id: "forge-apply-1", env: "prod", signer: "chant-runner" } })]);
+  });
+
+  test("with no key the job runs, warns of nothing, and its unsigned record counts in ci list and the run index", async () => {
+    const { app, base, sha } = workspace();
+    const reports = scratchDir("chant-ci-run-index-");
+    const { CHANT_RUNNER_KEY: _key, ...keyless } = HOST;
+    const r = await ciRun({ cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: { ...keyless, ...FORGE, GITHUB_JOB: "plan" }, inPlace: true, push: false, runId: "forge-plan-1", loop: { reportUrl: `file://${reports}` } });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toEqual([]);
+    expect(r.notes).toEqual(["there is no runner key, so the run's record is unsigned"]);
+    expect(r.signer).toBeNull();
+    expect(r.record.statement).toBeUndefined();
+    expect(r.record.runOrigin).toMatchObject({ forge: "github", jobId: "plan", attempt: 2 });
+    // --no-push: the plan's record stays on this checkout's chant/lifecycle.
+    expect(r.pushed).toBe(false);
+
+    const list = (await ciList({ cwd: app, now: NOW })) as Extract<Awaited<ReturnType<typeof ciList>>, { commits: unknown }>;
+    const plan = list.commits.find((c) => c.sha === sha)!.phases.find((p) => p.phase === "plan")!;
+    expect(plan.result).toBe("pass");
+    expect(plan.runs[0]).toMatchObject({ name: "pr-plan", opRun: { id: "forge-plan-1", signer: null } });
+
+    const index = JSON.parse(readFileSync(join(reports, "runs", "index.json"), "utf-8")) as { runs: Record<string, unknown>[] };
+    expect(index.runs[0]).toMatchObject({ job: "plan", runId: "forge-plan-1", signer: null, runOrigin: { forge: "github", jobId: "plan", attempt: 2 } });
+  });
+
+  test("a failed command's exit code is the job's, and --wave reaches pr-apply", async () => {
+    const { app, base } = workspace();
+    const r = await ciRun({ cwd: app, job: "apply", env: "prod", forge: "github", base, chant: fakeChant(), hostEnv: { ...HOST, ...FORGE, FAKE_EXIT: "3" }, inPlace: true, push: false, loop: { waveGate: "release" }, wave: 2 });
+    expect(r.status).toBe("fail");
+    expect(r.exitCode).toBe(3);
+    const argv = readFileSync(join(app, ".chant/pr/pr-apply.args"), "utf-8").trimEnd().split("\n");
+    expect(argv.slice(-4)).toEqual(["--resume", ".chant/pr-resume/pr-apply.json", "--wave", "2"]);
+    await expect(ciRun({ cwd: app, job: "plan", env: "prod", forge: "github", base, pr: 1, chant: fakeChant(), hostEnv: HOST, inPlace: true, push: false, wave: 2 })).rejects.toThrow(/--wave names the one wave an apply runs/);
+    // In place runs HEAD only.
+    await expect(ciRun({ cwd: app, job: "apply", env: "prod", forge: "github", base, commit: base, chant: fakeChant(), hostEnv: HOST, inPlace: true, push: false })).rejects.toThrow(/--in-place runs the checkout's HEAD/);
+  });
+});
+
+describe("ci run --local (#4161)", () => {
+  test("the job runs on this machine: no push, no status, no report upload or run index, a local record ci tick ignores, and events that say local", async () => {
+    const { root, app, base, sha } = workspace();
+    const reports = scratchDir("chant-ci-run-local-");
+    const remoteBefore = git(root, "ls-remote", "origin");
+    const posts: CommitStatus[] = [];
+    const events: string[] = [];
+    const r = await ciRun({
+      image: JOB_IMAGE,
+      cwd: app,
+      job: "plan",
+      env: "prod",
+      forge: "forgejo",
+      base,
+      pr: 7,
+      chant: fakeChant(),
+      hostEnv: HOST,
+      runnerKey: BOT.pem,
+      runnerKeyFromEnv: true,
+      local: true,
+      runId: "local-plan-1",
+      output: join(scratchDir("chant-ci-run-local-out-"), "pr"),
+      loop: { reportUrl: `file://${reports}`, events: true },
+      status: { client: { async setCommitStatus(_sha, status) { posts.push(status); } } },
+      runEvents: (line) => events.push(line),
+    });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toEqual([]);
+    expect(r.local).toBe(true);
+
+    // Nothing left this machine: origin is as it was, the fake forge saw no status, and the report URL holds nothing.
+    expect(r.pushed).toBe(false);
+    expect(git(root, "ls-remote", "origin")).toBe(remoteBefore);
+    expect(posts).toEqual([]);
+    expect(readdirSync(reports)).toEqual([]);
+    // The command got --no-status and no --report-url, so pr-plan posts and uploads nothing either.
+    const argv = readFileSync(join(r.report!, "pr-plan.args"), "utf-8").trimEnd().split("\n");
+    expect(argv).toContain("--no-status");
+    expect(argv).not.toContain("--report-url");
+    expect(argv).toContain("--events-json");
+
+    // The record is on this checkout's chant/lifecycle, and says local.
+    expect(r.record).toMatchObject({ op: "pr-plan", gitSha: sha, id: "local-plan-1", runOrigin: { forge: "local" } });
+    const stored = (await readRunLedger("prod", "pr-plan", { cwd: app })).records.at(-1)!;
+    expect(stored).toMatchObject({ id: "local-plan-1", runOrigin: { forge: "local" } });
+    expect(formatCiRun(r)).toContain("local run: the record stays on this machine");
+
+    // The events stream as the job runs, and say where it ran.
+    const stream = checkRunEventLines(events);
+    expect(stream[0]).toMatchObject({ type: "run-start", kind: "pipeline", runtime: "local", runId: "local-plan-1", gitSha: sha, runOrigin: { forge: "local" } });
+    expect(stream.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+
+    // A local run is never CI's verdict, signed or not.
+    const runs = await readOpRunSource(app, root, git(root, "rev-parse", "HEAD"));
+    expect(runs.checkRuns(sha)).toEqual([]);
+    expect(runs.ignored.get(sha)).toBeUndefined();
+  });
+
+  test("--local with --in-place is refused before anything runs, and the flag parses", async () => {
+    const { app, base } = workspace();
+    await expect(ciRun({ cwd: app, job: "plan", env: "prod", forge: "github", base, pr: 1, chant: fakeChant(), hostEnv: HOST, inPlace: true, local: true })).rejects.toThrow(/--in-place .* --local/);
+    expect(parseArgs(["ci", "run", "plan", "--local"]).local).toBe(true);
+  });
+});