@intentius/chant 0.124.34 → 0.124.35

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

@@ -531,3 +531,36 @@ describe("chant ci list (#4021)", () => {
     }
   });
 });
+
+describe("chant ci tick walks compose branches (#4168 4.3)", () => {
+  test("judges composed commits, names their branch in the tag, and warns when a source they carry is revoked", async () => {
+    const { root, origin } = workspace();
+    const a = commitAt(root, 5, "app/a.txt");
+    const b = commitAt(root, 4, "app/b.txt");
+    push(root);
+    // A composed commit on a, picking b.
+    git(root, "checkout", "-q", "-b", "chant/compose/hf", a);
+    writeFiles(root, { "app/b.txt": "app/b.txt 4\n" });
+    gitAt(root, hoursAgo(2), "add", "-A");
+    gitAt(root, hoursAgo(2), "commit", "-q", "-m", `app/b.txt\n\nChant-Composed-From: ${b}`);
+    const c = git(root, "rev-parse", "HEAD");
+    git(root, "push", "-q", "origin", "chant/compose/hf");
+    git(root, "checkout", "-q", "main");
+
+    const runs = new Map([
+      [a, PASSING],
+      [b, PASSING],
+      [c, PASSING],
+    ]);
+    const first = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
+    expect(first.composed.map((x) => [x.branch, x.commits.map((k) => k.sha)])).toEqual([["chant/compose/hf", [c]]]);
+    expect(first.made.sort()).toEqual([`ci/green/${a}`, `ci/green/${b}`, `ci/green/${c}`].sort());
+    const note = git(origin, "tag", "-l", "--format=%(contents)", `ci/green/${c}`);
+    expect(JSON.parse(note.slice(note.indexOf("{")))).toMatchObject({ tag: "green", commit: c, branch: "chant/compose/hf" });
+
+    runs.set(b, [...PASSING, run(9, "lint", "failure")]);
+    const revoke = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
+    expect(revoke.made).toEqual([`ci/revoked/${b}`]);
+    expect(revoke.warnings.join("\n")).toContain(`chant/compose/hf carries it as ${c.slice(0, 12)}`);
+  });
+});

package/src/workspace/ci-green.ts

@@ -71,6 +71,7 @@ import { gitRevisionSource } from "./record-source";
 import { emptyPolicy, readTrustPolicy } from "./trust/policy";
 import { loadRunnerKey } from "./trust/dsse";
 import { signCiTagRecord, verifyCiTagStatement, CI_TAG_SIGNER_ROLE, type CiTagFailure, type CiTagRecord, type CiTagSigner } from "./trust/ci-tag-statement";
+import { COMPOSE_BRANCH_PREFIX, composedIncluding, isComposeBranch, remoteComposeBranches } from "../lifecycle/compose-refs";
 
 /** The environment variable a tick (#4031) and `chant run` (#4044) read a runner key from, as PEM, when `--key` is not given. */
 export const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
@@ -478,7 +479,9 @@ export function readCiTags(top: string, green: CiGreen | null = null, base: stri
       continue;
     }
     const p = policyAtBase();
-    const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: green!.branch }, p.runners, p.roles);
+    // A tag the tick made walking a compose branch (#4168 4.3) is checked against that branch.
+    const walked = isComposeBranch(t.record?.branch) ? (t.record!.branch as string) : green!.branch;
+    const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: walked }, p.runners, p.roles);
     if (v.status === "signed") counted(v.signer);
     else ignore(v.status, `${v.reason}; ci.green.signedSince is ${green!.signedSince}, so a tag on a commit that is not a strict first-parent ancestor of it needs one`);
   }
@@ -501,7 +504,7 @@ export function signedRunsRequired(cwd: string): string | null {
 }
 
 /** The declaration's `ci.green`, read where `cwd` is, and the git top. */
-function readGreen(cwd: string): { green: CiGreen; top: string; workspace: { name: string; root: string; file: string } } {
+export function readGreen(cwd: string): { green: CiGreen; top: string; workspace: { name: string; root: string; file: string } } {
   const located = locateWorkspace(cwd);
   const declaration = readDeclaration(located.tree);
   const green = declaration.ci?.green ?? null;
@@ -535,12 +538,21 @@ export interface TickRequest {
   runnerKey?: string;
 }
 
+/** One compose branch a tick walked (#4168 4.3): its composed commits within the window. */
+export interface ComposedBranchTick {
+  branch: string;
+  ref: string;
+  commits: TickCommit[];
+}
+
 export interface TickResult {
   branch: string;
   window: string;
   /** The ref the commits were read from. */
   ref: string;
   commits: TickCommit[];
+  /** The compose branches walked (#4168 4.3), each with its composed commits judged. Their tags are in `made`. */
+  composed: ComposedBranchTick[];
   /** The tags made and pushed, or that would be under `dryRun`. */
   made: string[];
   /** The builds asked for (#4169), as `ci/build/<sha>` tags made and pushed, or that would be under `dryRun`. */
@@ -596,7 +608,16 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
   const now = req.now ?? new Date();
   const tracking = `refs/remotes/${remote}/${green.branch}`;
   try {
-    git(top, ["fetch", "--quiet", "--no-tags", "--prune", remote, `+refs/heads/${green.branch}:${tracking}`, "+refs/tags/ci/*:refs/tags/ci/*"]);
+    git(top, [
+      "fetch",
+      "--quiet",
+      "--no-tags",
+      "--prune",
+      remote,
+      `+refs/heads/${green.branch}:${tracking}`,
+      `+refs/heads/${COMPOSE_BRANCH_PREFIX}*:refs/remotes/${remote}/${COMPOSE_BRANCH_PREFIX}*`,
+      "+refs/tags/ci/*:refs/tags/ci/*",
+    ]);
   } catch (err) {
     throw new Error(`could not fetch ${green.branch} and the ci tags from ${remote}: ${stderrOf(err)}`);
   }
@@ -648,6 +669,28 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
     signer,
   });
   if (links) for (const c of planned) c.work = links.get(c.sha);
+  // Compose branches (#4168 4.3): each composed commit within the window is judged as trunk's are, and its tags name its branch.
+  const composed: ComposedBranchTick[] = [];
+  for (const b of remoteComposeBranches(top, remote)) {
+    const own = git(top, ["log", "--first-parent", `--max-age=${cutoff}`, "--format=%H %ct", b.ref, `^${tracking}`])
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.split(" "))
+      .filter(([, ct]) => Number(ct) >= cutoff)
+      .map(([sha, ct]) => ({ sha, committed: iso(new Date(Number(ct) * 1000)) }));
+    if (own.length === 0) continue;
+    const judged = await planTick({
+      green: { ...green, branch: b.branch },
+      commits: own,
+      greenTags: new Set(tags.green.keys()),
+      revokedTags: new Set(tags.revoked.keys()),
+      ignored: tags.ignored,
+      checkRuns: async (sha) => (runs ? runs.checkRuns(sha) : await forge!.checkRuns(sha)),
+      now,
+      signer,
+    });
+    composed.push({ branch: b.branch, ref: b.ref, commits: judged });
+  }
   if (runs) {
     for (const c of planned) {
       const ignored = runs.ignored.get(c.sha);
@@ -658,7 +701,14 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
   const requests = readBuildRequests(top);
   const retryVia = green.source === "runs" ? "request" : forge?.rerun ? "forge" : null;
   const builds = planBuilds({ green, commits: planned, runs: runsBy, requests, records, now, retryVia });
-  const due = planned.filter((c) => c.made !== null);
+  const due = [...planned, ...composed.flatMap((b) => b.commits)].filter((c) => c.made !== null);
+  // Decision 4: revoking a trunk commit says which composed commits carry it; their own CI decides their releases.
+  for (const c of planned) {
+    if (!c.made?.tag.startsWith(CI_REVOKED_TAG_PREFIX)) continue;
+    for (const k of composedIncluding(top, c.sha, remote)) {
+      warnings.push(`${c.sha.slice(0, 12)} is revoked, and ${k.branch} carries it as ${k.commit.slice(0, 12)}; that composed commit's own CI decides whether its releases stand`);
+    }
+  }
   if (!req.dryRun && due.length > 0) {
     const ident = taggerConfig(top);
     for (const c of due) git(top, [...ident, "tag", "-a", "-m", c.made!.message, c.made!.tag, c.sha]);
@@ -683,6 +733,7 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
     ref: tracking,
     commits: planned,
     made: due.map((c) => c.made!.tag),
+    composed,
     requested: builds.requests,
     retried,
     recorded,
@@ -964,6 +1015,23 @@ export async function readOpRunSource(cwd: string, top: string, base: string, si
   return { checkRuns: (sha) => byCommit.get(sha) ?? [], ignored };
 }
 
+/**
+ * Judge `ci.green.preMerge` on `commit` from the Op run records on the ledger
+ * (#4168 4.4), as `ci serve --land` does before it moves the target. The
+ * trust policy is read at `base`, the target's head. An unsigned run counts
+ * as the tick counts one: always, unless `ci.green.signedSince` asks for a
+ * signature. Throws {@link CiGreenError} when the declaration has no
+ * `ci.green` or names no pre-merge phase.
+ */
+export async function judgePreMerge(req: { cwd: string; commit: string; base: string }): Promise<CommitVerdict> {
+  const { green, top } = readGreen(req.cwd);
+  const pre = green.preMerge ?? [];
+  if (pre.length === 0) throw new CiGreenError("ci-green-undeclared", "ci.green.preMerge names no phase, so nothing says which checks must pass before the branch moves");
+  const runs = await readOpRunSource(req.cwd, top, req.base, green.signedSince);
+  const latest = latestAttempts(runs.checkRuns(req.commit));
+  return commitVerdictOf(pre.map((name) => evaluatePhase(green.phases.find((p) => p.name === name)!, latest)));
+}
+
 /**
  * What `chant run <op> --key` signs a run's record with (#4044): the runner
  * key `.chant/trust.json` at the checkout's `HEAD` lists for a principal
@@ -1063,6 +1131,19 @@ export function formatTick(r: TickResult, dryRun = false): string {
     for (const r of c.ignoredRuns ?? []) lines.push(`      ignored run ${r.run} of ${r.op} in ${r.env} (${r.status}): ${r.reason}`);
     if (c.blocked) lines.push(`      did not make ${c.blocked}: an ignored tag holds the name. Delete it to let the tick tag the commit: git push origin :refs/tags/${c.blocked}`);
   }
+  for (const b of r.composed ?? []) {
+    lines.push(`${b.branch}, composed commits within ${r.window}: ${b.commits.length}`);
+    for (const c of b.commits) {
+      const what = c.made
+        ? `${dryRun ? "would make" : "made"} ${c.made.tag.slice(0, c.made.tag.lastIndexOf("/"))}`
+        : c.before !== "none"
+          ? c.before
+          : c.verdict?.verdict === "fail"
+            ? `failed: phase ${c.verdict.failure!.phase}`
+            : "undecided";
+      lines.push(`  ${c.sha.slice(0, 12)}  ${what}`);
+    }
+  }
   if (r.signer && r.made.length > 0) lines.push(`signed as ${r.signer}`);
   for (const q of r.requested) lines.push(`${dryRun ? "would ask" : "asked"} for ${q.phases.join(", ")} at ${q.commit.slice(0, 12)} (${q.reason}): ${q.tag}`);
   for (const x of r.retried) lines.push(`${dryRun ? "would run" : "ran"} ${x.run} at ${x.sha.slice(0, 12)} again`);

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

@@ -145,7 +145,7 @@ const envFile = (dir: string, stage: string): Record<string, string> =>
 
 describe("the job as an Op (#4094)", () => {
   test("the job's variables come from flags, literals and the runner's tokens, and nothing else of the runner's", () => {
-    const [plan, apply] = prLoopJobs("forgejo", "prod", { events: true });
+    const [plan, apply, record] = prLoopJobs("forgejo", "prod", { events: true });
     const env = ciJobEnv(plan!, { forge: "forgejo", env: "prod", values: { base: "b".repeat(40), pr: 7, commit: "c".repeat(40) }, hostEnv: HOST, passEnv: ["AWS_ACCESS_KEY_ID"] });
     expect(env).toMatchObject({
       BASE_SHA: "b".repeat(40),
@@ -162,10 +162,12 @@ describe("the job as an Op (#4094)", () => {
     expect(Object.values(env).some((v) => v.includes("${{"))).toBe(false);
 
     expect(() => ciJobEnv(plan!, { forge: "forgejo", env: "prod", values: { base: "b".repeat(40), commit: "c".repeat(40) }, hostEnv: {} })).toThrow(CiRunError);
-    expect(() => ciJobEnv(apply!, { forge: "forgejo", env: "prod", values: { commit: "c".repeat(40) }, hostEnv: {} })).toThrow(/pass --base <sha>/);
+    expect(() => ciJobEnv(record!, { forge: "forgejo", env: "prod", values: { commit: "c".repeat(40) }, hostEnv: {} })).toThrow(/pass --base <sha>/);
+    // #4168 step 9: the apply measures from the last applied green commit, so it needs no --base.
+    expect(ciJobEnv(apply!, { forge: "forgejo", env: "prod", values: { commit: "c".repeat(40) }, hostEnv: {} })).not.toHaveProperty("BASE_SHA");
 
-    const [, gitlabApply] = prLoopJobs("gitlab", "prod");
-    const gl = ciJobEnv(gitlabApply!, { forge: "gitlab", env: "prod", values: { base: "b".repeat(40), commit: "c".repeat(40) }, hostEnv: {} });
+    const [, , gitlabRecord] = prLoopJobs("gitlab", "prod");
+    const gl = ciJobEnv(gitlabRecord!, { forge: "gitlab", env: "prod", values: { base: "b".repeat(40), commit: "c".repeat(40) }, hostEnv: {} });
     expect(gl).toEqual({ BASE_SHA: "b".repeat(40), CHANT_ENV: "prod", CI_COMMIT_SHA: "c".repeat(40) });
   });
 
@@ -180,11 +182,13 @@ describe("the job as an Op (#4094)", () => {
     expect(last.args).toEqual({ cmd: `npx chant${plan!.command.slice("chant".length)}`, cwd: "/w/app", env: { BASE_SHA: "b" }, inheritEnv: false });
     expect(plan!.command).toContain("--member app");
 
-    // No setup or build lines: the job's phase alone. GitLab's apply keeps its base fallback in the command's shell.
-    const [, gitlabApply] = prLoopJobs("gitlab", "prod");
-    const bare = ciJobOp({ job: gitlabApply!, env: "prod", cwd: "/w", jobEnv: {}, setup: [], build: [] });
-    expect(bare.phases.map((p) => p.name)).toEqual(["apply"]);
-    expect(ciJobCommand(gitlabApply!)).toBe(`${gitlabApply!.setup![0]}\n${gitlabApply!.command}`);
+    // No setup or build lines: the job's phase alone. GitLab's record keeps its base fallback in the command's shell.
+    const [, gitlabApply, gitlabRecord] = prLoopJobs("gitlab", "prod");
+    const bare = ciJobOp({ job: gitlabRecord!, env: "prod", cwd: "/w", jobEnv: {}, setup: [], build: [] });
+    expect(bare.phases.map((p) => p.name)).toEqual(["record"]);
+    expect(ciJobCommand(gitlabRecord!)).toBe(`${gitlabRecord!.setup![0]}\n${gitlabRecord!.command}`);
+    // #4168 step 9: the apply's green checkout is the generated job's, never ci run's: it runs at the commit it was given.
+    expect(ciJobCommand(gitlabApply!)).toBe(gitlabApply!.command);
 
     // #4088's build and lint lines follow --before-script, with chant replaced in each.
     const [built] = prLoopJobs("forgejo", "prod", { build: true });
@@ -298,7 +302,7 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
 
     expect(apply.status).toBe("ok");
     const applyArgs = readFileSync(join(reports, "apply", "pr-apply.args"), "utf-8").trimEnd().split("\n");
-    expect(applyArgs).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    expect(applyArgs).toEqual(["components", "pr-apply", "--green", "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--resume", ".chant/pr-resume/pr-apply.json"]);
     expect(formatCiRun(apply)).toContain("signed by chant-runner");
   });
 
@@ -671,7 +675,8 @@ describe("the job's secrets from the host (#4096)", () => {
     const applyEnv = ciJobEnv(apply!, { forge: "forgejo", env: "prod", values: { base, commit: base }, hostEnv: HOST, secrets: ciSecretsFor(secrets, "apply") });
     expect(applyEnv).toMatchObject({ DB_PASSWORD: "hunter22-db", DEPLOY_KEY: "deploy-key-value" });
     // A secret can replace a forge token, and never the variables the runner sets.
-    const over = ciJobEnv(apply!, { forge: "forgejo", env: "prod", values: { base, commit: base }, hostEnv: HOST, secrets: { GITHUB_TOKEN: "from-file", BASE_SHA: "x", CHANT_RUNNER_KEY: "k" } });
+    const [, , record] = prLoopJobs("forgejo", "prod");
+    const over = ciJobEnv(record!, { forge: "forgejo", env: "prod", values: { base, commit: base }, hostEnv: HOST, secrets: { GITHUB_TOKEN: "from-file", BASE_SHA: "x", CHANT_RUNNER_KEY: "k" } });
     expect(over).toMatchObject({ GITHUB_TOKEN: "from-file", BASE_SHA: base });
     expect(over).not.toHaveProperty("CHANT_RUNNER_KEY");
     expect(() => ciJobEnv(apply!, { forge: "forgejo", env: "prod", values: { base, commit: base }, hostEnv: HOST, passEnv: ["CHANT_RUNNER_KEY"] })).toThrow(/never passed to a job/);
@@ -791,10 +796,10 @@ describe("a generated forge job runs ci run --in-place (#4156)", () => {
     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", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    expect(argv).toEqual(["components", "pr-apply", "--green", "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--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).toMatchObject({ NOT_FOR_JOBS: "leak", GITHUB_RUN_ID: "4242", 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.

package/src/workspace/ci-run.ts

@@ -423,6 +423,12 @@ export interface CiRunRequest {
   /** `--env`: the environment the pipeline is for. */
   env: string;
   forge: ForgeKind;
+  /**
+   * Run the job's command without `--forge` (#4016 gap 6): `ci serve --forge
+   * git` reads a plain git server, which has no API for the command to ask.
+   * `forge` then only shapes the job's variables.
+   */
+  noForge?: boolean;
   /** `--base`, `--pr` and `--commit` (default `HEAD`). */
   base?: string;
   pr?: number;
@@ -668,7 +674,8 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const isolated = !req.requireRunnerStart && !req.local && req.job === "apply" && securityGroupsAt(cwd).has("isolated-runners");
   const started = req.requireRunnerStart || isolated ? runnerStartFor(req, { top, commit, hostEnv }) : undefined;
   // A generated wave job's command, as prLoopWaveJobs writes it. #4161: a local job's command posts no status or note.
-  const command = `${found.command}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${req.local ? " --no-status" : ""}`;
+  const forgeCommand = req.noForge ? found.command.replace(` --forge ${req.forge}`, "") : found.command;
+  const command = `${forgeCommand}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${req.local ? " --no-status" : ""}`;
   const job = { ...found, command, ...(req.wave !== undefined ? { wave: req.wave } : {}) };
   const own = ciJobEnv(job, {
     forge: req.forge,

package/src/workspace/ci-serve-land.e2e.test.ts

@@ -0,0 +1,138 @@
+/**
+ * #4168 4.4 and #4016 gap 6 end to end: `chant ci serve --forge git --land`,
+ * as a process, against a bare git remote with no forge API, no runner key
+ * and no signers.
+ *
+ * The build command records an Op run named `check` on the land branch's
+ * head, which passes unless the head holds `red.txt`. The serve judges
+ * `ci.green.preMerge` from that record: a green land moves main and the land
+ * branch goes; a red one leaves both. Each serve gets a fresh state
+ * directory, so its first poll only notes main's head and runs no job.
+ */
+
+import { spawn } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, declaration, git, REPO, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+
+afterAll(cleanScratch);
+
+const LOADER = pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href;
+const GREEN = { branch: "main", phases: { check: ["check"], suites: ["suites"] }, require: ["check", "suites"], preMerge: ["check"], source: "runs" };
+
+/** Records an unsigned `check` run on the checkout's HEAD: it fails when `red.txt` is there. */
+const RECORD_CHECK = `
+import { existsSync } from "node:fs";
+import { runOpLocally, OpRunFailure } from ${JSON.stringify(join(REPO, "packages/core/src/op/local-executor.ts"))};
+const red = existsSync("red.txt");
+const op = { name: "check", overview: "check", labels: { Env: "ci" }, phases: [{ name: "Run", steps: [{ kind: "activity", fn: "step", args: {} }] }] };
+const fns = new Map([["step", async () => { if (red) throw new Error("red"); return {}; }]]);
+try {
+  await runOpLocally(op, fns, {}, undefined, { cwd: process.cwd(), ledger: { cwd: process.cwd() } });
+} catch (err) {
+  if (!(err instanceof OpRunFailure)) throw err;
+}
+`;
+
+function chant(cwd: string, ...args: string[]): Promise<{ code: number; out: string; err: string }> {
+  return new Promise((done) => {
+    const env: Record<string, string | undefined> = { ...process.env, GIT_TERMINAL_PROMPT: "0", NO_COLOR: "1" };
+    // No forge and no key: nothing here may lean on either.
+    for (const name of ["GITHUB_ACTIONS", "GITHUB_TOKEN", "GH_TOKEN", "CHANT_FORGE_TOKEN", "CHANT_RUNNER_KEY", "GITHUB_REPOSITORY"]) delete env[name];
+    const child = spawn(process.execPath, ["--import", LOADER, join(REPO, "packages/core/src/cli/main.ts"), ...args], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (c) => (out += c));
+    child.stderr.on("data", (c) => (err += c));
+    child.on("close", (code) => done({ code: code ?? 1, out, err }));
+  });
+}
+
+function commit(root: string, file: string): string {
+  writeFiles(root, { [file]: `${file}\n` });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", file);
+  return git(root, "rev-parse", "HEAD");
+}
+
+function pushLand(root: string, name: string, files: string[]): string {
+  git(root, "checkout", "-q", "-b", `land-${name}`, "main");
+  let sha = "";
+  for (const f of files) sha = commit(root, f);
+  git(root, "push", "-q", "origin", `${sha}:refs/heads/chant/land/${name}`);
+  git(root, "checkout", "-q", "main");
+  return sha;
+}
+
+const remote = (origin: string, ref: string): string | null => {
+  try {
+    return git(origin, "rev-parse", "--verify", "--quiet", ref);
+  } catch {
+    return null;
+  }
+};
+
+describe("ci serve --forge git --land, end to end (#4168 4.4, #4016 gap 6)", () => {
+  let root: string;
+  let origin: string;
+  let main: string;
+  let build: string;
+
+  beforeAll(() => {
+    origin = scratchDir("chant-land-e2e-origin-");
+    git(origin, "init", "-q", "--bare");
+    root = scratchDir("chant-land-e2e-work-");
+    git(root, "init", "-q");
+    git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+    git(root, "config", "user.name", "t");
+    git(root, "config", "user.email", "t@example.com");
+    git(root, "remote", "add", "origin", origin);
+    writeFiles(root, {
+      "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: GREEN } }),
+      "app/a.txt": "a\n",
+    });
+    main = commit(root, "init.txt");
+    git(root, "push", "-q", "origin", "main");
+    const script = join(scratchDir("chant-land-e2e-bin-"), "record-check.mts");
+    writeFileSync(script, RECORD_CHECK);
+    build = `${JSON.stringify(process.execPath)} --import ${JSON.stringify(LOADER)} ${JSON.stringify(script)}`;
+  });
+
+  const serve = (state: string) => chant(root, "ci", "serve", "--forge", "git", "--env", "prod", "--once", "--land", "--build-command", build, "--state", join(root, ".git", state));
+
+  test("a land whose pre-merge phase passes moves main to it, and the land branch is deleted", async () => {
+    const head = pushLand(root, "fix", ["fix-1.txt", "fix-2.txt"]);
+    const r = await serve("serve-green");
+    expect(r.err).toContain("no commit status is set");
+    expect(r.err).toContain(`chant/land/fix at ${head.slice(0, 12)} landed, and the land branch was deleted`);
+    expect(r.code).toBe(0);
+    expect(remote(origin, "refs/heads/main")).toBe(head);
+    expect(remote(origin, "refs/heads/chant/land/fix")).toBeNull();
+    main = head;
+  });
+
+  test("a land whose pre-merge phase fails leaves main and the land branch", async () => {
+    git(root, "fetch", "-q", "origin", "main");
+    git(root, "reset", "-q", "--hard", "origin/main");
+    const head = pushLand(root, "red", ["red.txt"]);
+    const r = await serve("serve-red");
+    expect(r.err).toContain(`chant/land/red at ${head.slice(0, 12)} was refused and left on the remote: the pre-merge phase check failed`);
+    expect(remote(origin, "refs/heads/main")).toBe(main);
+    expect(remote(origin, "refs/heads/chant/land/red")).toBe(head);
+  });
+
+  test("--land without a build command, or without ci.green.preMerge, is refused before the first poll", async () => {
+    const noBuild = await chant(root, "ci", "serve", "--forge", "git", "--env", "prod", "--once", "--land");
+    expect(noBuild.code).toBe(1);
+    expect(noBuild.err).toContain("--land runs each land branch's pre-merge phases with --build-command");
+
+    const bare = scratchDir("chant-land-e2e-nopre-");
+    git(bare, "init", "-q");
+    writeFiles(bare, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: { ...GREEN, preMerge: undefined } } }) });
+    const noPre = await chant(bare, "ci", "serve", "--forge", "git", "--env", "prod", "--once", "--land", "--build-command", "true");
+    expect(noPre.code).toBe(1);
+    expect(noPre.err).toContain("the declaration names none");
+  });
+});

package/src/workspace/ci-serve-land.test.ts

@@ -0,0 +1,176 @@
+/**
+ * #4168 4.4 — `ci serve --land` fast-forwards the target to a pushed
+ * `chant/land/<name>` branch once its pre-merge phases pass on it, and
+ * #4016 gap 6 — `ci serve --forge git` reads a plain git server's refs.
+ *
+ * Each test works in its own clone with a bare origin. The build and the
+ * judge are fakes; `ci-serve-land.e2e.test.ts` runs the real ones.
+ */
+
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { ciServeLands, formatCiServeEvent, gitCiServeForge, newCiServeRuntime, readCiServeState, type CiServeEvent, type CiServeOptions } from "./ci-serve";
+import type { CommitVerdict } from "./ci-green";
+
+afterAll(cleanScratch);
+
+function commit(root: string, file: string): string {
+  writeFiles(root, { [file]: `${file}\n` });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", file);
+  return git(root, "rev-parse", "HEAD");
+}
+
+/** A clone on main with a bare origin. */
+function clone(): { root: string; origin: string; main: string } {
+  const origin = scratchDir("chant-serve-land-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-serve-land-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "remote", "add", "origin", origin);
+  const main = commit(root, "a.txt");
+  git(root, "push", "-q", "origin", "main");
+  return { root, origin, main };
+}
+
+/** A commit on top of `from`, pushed as `chant/land/<name>`. */
+function pushLand(root: string, name: string, from: string, file: string): string {
+  git(root, "checkout", "-q", "--detach", from);
+  const sha = commit(root, file);
+  git(root, "push", "-q", "--force", "origin", `${sha}:refs/heads/chant/land/${name}`);
+  git(root, "checkout", "-q", "main");
+  return sha;
+}
+
+const verdict = (phases: Record<string, "pass" | "fail" | "pending">): CommitVerdict => {
+  const list = Object.entries(phases).map(([phase, v]) => ({ phase, verdict: v, runs: [], unmatched: [] }));
+  return { verdict: list.some((p) => p.verdict === "fail") ? "fail" : list.some((p) => p.verdict === "pending") ? "pending" : "pass", phases: list, failure: null };
+};
+
+function options(root: string, log: CiServeEvent[], extra: Partial<CiServeOptions> = {}): CiServeOptions & { built: { commit: string; phases: string[]; reason: string }[] } {
+  const built: { commit: string; phases: string[]; reason: string }[] = [];
+  return {
+    cwd: root,
+    forge: "git",
+    repo: "origin",
+    env: "prod",
+    client: gitCiServeForge(root),
+    stateDir: join(root, ".git", "serve"),
+    buildCommand: "true",
+    build: async ({ request }) => (built.push({ ...request }), 0),
+    land: { phases: ["check"] },
+    judgeLand: async () => verdict({ check: "pass" }),
+    log: (e) => log.push(e),
+    built,
+    ...extra,
+  };
+}
+
+const remoteHead = (origin: string, ref: string): string | undefined => {
+  try {
+    return git(origin, "rev-parse", "--verify", "--quiet", ref);
+  } catch {
+    return undefined;
+  }
+};
+
+describe("the git forge kind (#4016 gap 6)", () => {
+  test("reads the branch head through ls-remote, lists no pull requests, and says when the branch is missing", async () => {
+    const { root, main } = clone();
+    const forge = gitCiServeForge(root);
+    expect(await forge.branchHead("main")).toBe(main);
+    expect(await forge.branchHead("nope")).toBeUndefined();
+    expect(await forge.openPullRequests("main")).toEqual([]);
+    expect(forge.pullRequestFor).toBeUndefined();
+  });
+});
+
+describe("ci serve --land (#4168 4.4)", () => {
+  test("a land whose pre-merge phases pass moves the target to it and deletes the land branch, once", async () => {
+    const { root, origin, main } = clone();
+    const head = pushLand(root, "fix", main, "b.txt");
+    const log: CiServeEvent[] = [];
+    const opts = options(root, log);
+    const rt = newCiServeRuntime();
+    const pass = await ciServeLands(opts, rt);
+    await Promise.all(pass.started);
+
+    expect(opts.built).toEqual([{ commit: head, phases: ["check"], reason: "land" }]);
+    expect(remoteHead(origin, "refs/heads/main")).toBe(head);
+    expect(remoteHead(origin, "refs/heads/chant/land/fix")).toBeUndefined();
+    const state = readCiServeState(join(root, ".git", "serve", "chant-apply-prod.json"), { forge: "git", repo: "origin", env: "prod", branch: "main" });
+    expect(state.lands?.[`land:fix:${head}`]).toMatchObject({ branch: "chant/land/fix", commit: head, status: "landed" });
+    expect(log.map(formatCiServeEvent)).toContain(`chant/land/fix at ${head.slice(0, 12)} landed, and the land branch was deleted`);
+
+    // Nothing is left to serve.
+    expect((await ciServeLands(opts, rt)).started).toEqual([]);
+  });
+
+  test("a red pre-merge phase refuses the land and leaves the target and the land branch", async () => {
+    const { root, origin, main } = clone();
+    const head = pushLand(root, "red", main, "b.txt");
+    const log: CiServeEvent[] = [];
+    const opts = options(root, log, { judgeLand: async () => verdict({ check: "fail" }) });
+    await Promise.all((await ciServeLands(opts, newCiServeRuntime())).started);
+
+    expect(remoteHead(origin, "refs/heads/main")).toBe(main);
+    expect(remoteHead(origin, "refs/heads/chant/land/red")).toBe(head);
+    expect(log.map(formatCiServeEvent)).toContain(`chant/land/red at ${head.slice(0, 12)} was refused and left on the remote: the pre-merge phase check failed`);
+  });
+
+  test("a phase with no finished run, or a build that fails, refuses the land", async () => {
+    const { root, origin, main } = clone();
+    const a = pushLand(root, "norun", main, "b.txt");
+    const b = pushLand(root, "broken", main, "c.txt");
+    const log: CiServeEvent[] = [];
+    const opts = options(root, log, {
+      maxJobs: 2,
+      judgeLand: async () => verdict({ check: "pending" }),
+      build: async ({ request }) => (request.commit === b ? 3 : 0),
+    });
+    await Promise.all((await ciServeLands(opts, newCiServeRuntime())).started);
+
+    expect(remoteHead(origin, "refs/heads/main")).toBe(main);
+    const lines = log.map(formatCiServeEvent);
+    expect(lines).toContain(`chant/land/norun at ${a.slice(0, 12)} was refused and left on the remote: the build recorded no finished run for check`);
+    expect(lines).toContain(`chant/land/broken at ${b.slice(0, 12)} was refused and left on the remote: the build of check exited 3`);
+  });
+
+  test("a land that does not descend from the target is refused without a build, and a new push to it is tried again", async () => {
+    const { root, origin, main } = clone();
+    const stale = pushLand(root, "old", main, "b.txt");
+    const moved = commit(root, "c.txt");
+    git(root, "push", "-q", "origin", "main");
+    const log: CiServeEvent[] = [];
+    const opts = options(root, log);
+    const rt = newCiServeRuntime();
+    await Promise.all((await ciServeLands(opts, rt)).started);
+
+    expect(opts.built).toEqual([]);
+    expect(remoteHead(origin, "refs/heads/main")).toBe(moved);
+    expect(log.map(formatCiServeEvent)).toContain(
+      `chant/land/old at ${stale.slice(0, 12)} was refused and left on the remote: ${stale.slice(0, 12)} does not descend from main at ${moved.slice(0, 12)}; rebase chant/land/old onto it and push again`,
+    );
+    // The same head is not tried twice.
+    expect((await ciServeLands(opts, rt)).started).toEqual([]);
+
+    // Rebased and pushed again, it lands.
+    const rebased = pushLand(root, "old", moved, "b.txt");
+    await Promise.all((await ciServeLands(opts, rt)).started);
+    expect(remoteHead(origin, "refs/heads/main")).toBe(rebased);
+  });
+
+  test("lands wait for capacity", async () => {
+    const { root, main } = clone();
+    const head = pushLand(root, "fix", main, "b.txt");
+    const log: CiServeEvent[] = [];
+    const rt = newCiServeRuntime();
+    rt.inflight.set("busy", new Promise(() => {}));
+    expect((await ciServeLands(options(root, log), rt)).started).toEqual([]);
+    expect(log.map(formatCiServeEvent)).toContain(`chant/land/fix at ${head.slice(0, 12)} waits: --max-jobs jobs run`);
+  });
+});