@intentius/chant 0.124.30 → 0.124.32

package/dist/workspace/ci-serve.d.ts

@@ -15,12 +15,34 @@
  *   the one `chant operator` holds) named for `prApplyGroup`, renews it while
  *   it runs and releases it after. An apply that finds it held waits for a
  *   later poll, as a forge's concurrency group queues it.
+ * - Merged pull request. An apply asks the forge for the pull request whose
+ *   merge commit the new head is (`pullRequestFor`, as pr-apply does) and
+ *   passes it as `--pr`, so its commit status link and run index use
+ *   `<pr>/<commit>`. With none found it runs without `--pr`.
  * - Resume records. Each apply gets `<state>/resume/<prApplyRecordKey>.json`
  *   as its `--resume` record, so a re-run of a failed apply at the same
  *   commit finishes under the approval it has. This replaces the forge's CI
  *   cache.
+ * - A gate per wave (#4003). With `--wave-gate` the apply job runs
+ *   `pr-apply --wave-gate`, which applies the waves in order and stops at
+ *   the first whose moved plan waits on its own gate. The job fails, and the
+ *   resume record keeps the waves that applied; once the wave's plan is
+ *   approved, `rerunFailed` runs the apply again and it carries on from
+ *   that wave.
  * - Capacity. At most `maxJobs` jobs run at once. A job over the limit is not
  *   recorded, so a later poll starts it.
+ * - Fast-forwards only (#4122). An apply runs only when the target's new head
+ *   descends from the head seen before it. Any other move, such as a force
+ *   push back to an older commit, is recorded as seen and not applied.
+ * - `[skip ci]` (#4122). A target head or pull request head whose commit
+ *   message says `[skip ci]` or `[ci skip]` is recorded as seen and not run,
+ *   as Actions does.
+ * - The forge's ledger (#4121). Before each job, when no other job of this
+ *   serve runs, the clone's `chant/lifecycle` follows the forge's: it is
+ *   deleted when the forge has none, and reset to the forge's when neither
+ *   contains the other. Each is a warning. A local branch ahead of the
+ *   forge's keeps its facts, and the job's push sends them. Nothing here
+ *   pushes the ledger.
  *
  * Host mode only: each job runs in a fresh worktree on this host as this
  * user, with the clean environment `ciRun` gives it. A pull request from a
@@ -40,6 +62,8 @@ export type CiServeForgeKind = "github" | "forgejo";
 export interface CiServeForge {
     openPullRequests(base: string): Promise<OpenPullRequest[]>;
     branchHead(branch: string): Promise<string | undefined>;
+    /** The merged pull request that produced a commit, as pr-apply finds it (`pullRequestFor`). Without it an apply gets no `--pr`. */
+    pullRequestFor?(sha: string): Promise<number | null>;
 }
 /** A job the forge's state calls for: the plan of a pull request's head, or the apply of a target-branch commit. */
 export type CiServeTrigger = {
@@ -79,9 +103,11 @@ export interface CiServeState {
     env: string;
     branch: string;
     member?: string;
-    /** The target branch's head the last apply was measured to, or the head the first poll found. */
+    /** The target branch's head the last apply was measured to, or the last head seen and not applied. */
     target?: string;
     jobs: Record<string, CiServeJobState>;
+    /** Plans seen and not run, by state key, with why (#4122). */
+    skipped?: Record<string, "skip-ci">;
 }
 /** What a pass did, in order, for the log. */
 export type CiServeEvent = {
@@ -119,6 +145,19 @@ export type CiServeEvent = {
     status: "ok" | "fail";
     failure?: string;
     report?: string;
+} | {
+    type: "not-run";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    reason: "not-fast-forward" | "skip-ci";
+    branch?: string;
+    from?: string;
+} | {
+    type: "ledger";
+    action: "deleted" | "reset";
+    local: string;
+    forge?: string;
 } | {
     type: "error";
     message: string;
@@ -162,17 +201,34 @@ export declare function ciServeKey(t: {
     commit: string;
     pr?: number;
 }): string;
+/**
+ * Make the clone's `chant/lifecycle` follow the forge's (#4121). The clone's
+ * branch outlives the forge's, so a ledger the forge deleted or rewrote would
+ * make the next pr-apply find the two diverged and stall.
+ *
+ * - The forge has none: the local branch and its remote-tracking ref go.
+ * - Neither contains the other: the local branch and its remote-tracking ref
+ *   are reset to the forge's tip.
+ * - The local branch is ahead of the forge's, or behind it, or the same: it
+ *   is left, and an apply's push sends what it holds that the forge lacks.
+ *
+ * Nothing is pushed, so a rewritten ledger never goes back to the forge. A
+ * forge that can't be reached leaves everything as it is; the job's own
+ * fetch says why.
+ */
+export declare function reconcileCiServeLedger(top: string): CiServeEvent | undefined;
 /** Where a serve keeps its state when `--state` names nowhere: beside the run events, in the repository's common git directory. */
 export declare function defaultCiServeStateDir(cwd: string): string;
 /** The state file, or a new one. */
 export declare function readCiServeState(file: string, fresh: Omit<CiServeState, "schema" | "jobs">): CiServeState;
 /**
  * One poll of the forge, as triggers: an apply when the target's head moved
- * since the last apply (none on the first poll, which only notes the head),
+ * since the last apply by a fast-forward (none on the first poll, which only
+ * notes the head, and none for a head whose message says `[skip ci]`),
  * then a plan for each open pull request head not yet planned, oldest pull
  * request first. A job already in the state file is left out unless it
- * failed and `rerunFailed` is set. The first poll's head is written to the
- * state file.
+ * failed and `rerunFailed` is set. The first poll's head, and a head seen
+ * and not applied, are written to the state file.
  */
 export declare function ciServeObserve(opts: CiServeOptions, rt?: CiServeRuntime): Promise<{
     triggers: CiServeTrigger[];
@@ -207,6 +263,13 @@ export declare function ciServeLoop(opts: CiServeOptions & {
 }): Promise<void>;
 /** One line for an event, as `ci serve` prints it. */
 export declare function formatCiServeEvent(e: CiServeEvent): string;
+/**
+ * `chant ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]` (#4099):
+ * make the host's runner key when there is none, print its public half on
+ * stdout, and say whether the target's head lists it. With --trust, commit
+ * the runner entry on a branch of its own and push it for review.
+ */
+export declare function runnerKeySetupCommand(ctx: CommandContext): number;
 /** `--interval`: seconds, or a duration such as `30s` or `2m`. Default 30 seconds. */
 export declare function ciServeInterval(value: string | undefined): number;
 /** `chant ci serve` (#4095). */

package/dist/workspace/ci-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-serve.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-serve.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ci-serve.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAMH,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAKtD,OAAO,EAA0F,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAKvK,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpD,gHAAgH;AAChH,MAAM,WAAW,YAAY;IAC3B,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC3D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxD,mIAAmI;IACnI,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtD;AAED,oHAAoH;AACpH,MAAM,MAAM,cAAc,GACtB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1E;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpE,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,MAAM,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,CAAC,CAAC;IACV,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACtC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACrC;AAED,8CAA8C;AAC9C,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5G;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/H;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1H;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxI;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,mHAAmH;AACnH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,cAAc,GAAG,OAAO,CAAC,CAAC;AAErJ,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,gBAAgB,CAAC;IACxB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iHAAiH;IACjH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,2FAA2F;IAC3F,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gFAAgF;IAChF,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CACnD;AAED,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;CACjD;AAED,eAAO,MAAM,iBAAiB,QAAO,cAA2C,CAAC;AAEjF,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,CAAC,EAAE;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAErF;AAsBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAwB5E;AAuBD,mIAAmI;AACnI,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAsBD,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,YAAY,CAOzG;AAaD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,GAAE,cAAoC,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAqEpK;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;IACpC,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,EAAE,GAAE,cAAoC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+EpK;AAgDD,iFAAiF;AACjF,wBAAsB,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,GAAE,cAAoC,EAAE,IAAI,UAAO,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC,CAM3K;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBpH;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CA0B1D;AAID;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAkBjE;AAUD,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKjE;AAED,gCAAgC;AAChC,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsFrE"}

package/dist/workspace/ci-serve.js

@@ -15,12 +15,34 @@
  *   the one `chant operator` holds) named for `prApplyGroup`, renews it while
  *   it runs and releases it after. An apply that finds it held waits for a
  *   later poll, as a forge's concurrency group queues it.
+ * - Merged pull request. An apply asks the forge for the pull request whose
+ *   merge commit the new head is (`pullRequestFor`, as pr-apply does) and
+ *   passes it as `--pr`, so its commit status link and run index use
+ *   `<pr>/<commit>`. With none found it runs without `--pr`.
  * - Resume records. Each apply gets `<state>/resume/<prApplyRecordKey>.json`
  *   as its `--resume` record, so a re-run of a failed apply at the same
  *   commit finishes under the approval it has. This replaces the forge's CI
  *   cache.
+ * - A gate per wave (#4003). With `--wave-gate` the apply job runs
+ *   `pr-apply --wave-gate`, which applies the waves in order and stops at
+ *   the first whose moved plan waits on its own gate. The job fails, and the
+ *   resume record keeps the waves that applied; once the wave's plan is
+ *   approved, `rerunFailed` runs the apply again and it carries on from
+ *   that wave.
  * - Capacity. At most `maxJobs` jobs run at once. A job over the limit is not
  *   recorded, so a later poll starts it.
+ * - Fast-forwards only (#4122). An apply runs only when the target's new head
+ *   descends from the head seen before it. Any other move, such as a force
+ *   push back to an older commit, is recorded as seen and not applied.
+ * - `[skip ci]` (#4122). A target head or pull request head whose commit
+ *   message says `[skip ci]` or `[ci skip]` is recorded as seen and not run,
+ *   as Actions does.
+ * - The forge's ledger (#4121). Before each job, when no other job of this
+ *   serve runs, the clone's `chant/lifecycle` follows the forge's: it is
+ *   deleted when the forge has none, and reset to the forge's when neither
+ *   contains the other. Each is a warning. A local branch ahead of the
+ *   forge's keeps its facts, and the job's push sends them. Nothing here
+ *   pushes the ledger.
  *
  * Host mode only: each job runs in a fresh worktree on this host as this
  * user, with the clean environment `ciRun` gives it. A pull request from a
@@ -31,17 +53,19 @@
  * {@link ciServeObserve} is the poll that makes them; a webhook handler would
  * turn a checked payload into the same triggers and schedule them.
  */
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline.js";
 import { forgeFromEnv } from "../pr-forge.js";
 import { formatError, formatWarning } from "../cli/format.js";
 import { acquireLease, currentHolderId, releaseLease, DEFAULT_LEASE_TTL_MS } from "../lifecycle/lease.js";
 import { parseDuration } from "../op/duration.js";
-import { CI_JOB_OPS, ciJobPlace, ciRun, CiRunError } from "./ci-run.js";
-import { RUNNER_KEY_ENV } from "./ci-green.js";
+import { reportUrlOf } from "./ci-report-url.js";
+import { CI_JOB_OPS, ciJobPlace, ciLoopOptions, ciSecretsOf, ciRun, ciStatusFromEnv, CiRunError } from "./ci-run.js";
+import { RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green.js";
 import { gitTop } from "./tree.js";
+import { ciServeRunnerKey, formatRunnerKeySetup, setupRunnerKey } from "./ci-runner-key.js";
 export const newCiServeRuntime = () => ({ inflight: new Map() });
 /** The state key of a job. */
 export function ciServeKey(t) {
@@ -56,6 +80,79 @@ function tryGit(cwd, args) {
         return undefined;
     }
 }
+const LEDGER = "chant/lifecycle";
+/** Where the forge's ledger tip is fetched to, a ref only this module writes. */
+const FORGE_LEDGER = "refs/chant/ci-serve/forge-ledger";
+/** `git` with its exit status, for the calls whose answer is the status. */
+function gitStatus(cwd, args) {
+    const r = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LC_ALL: "C" } });
+    return { code: r.status ?? -1, out: (r.stdout ?? "").trim() };
+}
+/**
+ * Make the clone's `chant/lifecycle` follow the forge's (#4121). The clone's
+ * branch outlives the forge's, so a ledger the forge deleted or rewrote would
+ * make the next pr-apply find the two diverged and stall.
+ *
+ * - The forge has none: the local branch and its remote-tracking ref go.
+ * - Neither contains the other: the local branch and its remote-tracking ref
+ *   are reset to the forge's tip.
+ * - The local branch is ahead of the forge's, or behind it, or the same: it
+ *   is left, and an apply's push sends what it holds that the forge lacks.
+ *
+ * Nothing is pushed, so a rewritten ledger never goes back to the forge. A
+ * forge that can't be reached leaves everything as it is; the job's own
+ * fetch says why.
+ */
+export function reconcileCiServeLedger(top) {
+    const local = tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${LEDGER}^{commit}`]);
+    const listed = gitStatus(top, ["ls-remote", "--exit-code", "origin", `refs/heads/${LEDGER}`]);
+    if (listed.code === 2) {
+        // A remote-tracking ref left from a deleted branch would be the next push's lease, and refuse it.
+        tryGit(top, ["update-ref", "-d", `refs/remotes/origin/${LEDGER}`]);
+        if (!local)
+            return undefined;
+        tryGit(top, ["update-ref", "-d", `refs/heads/${LEDGER}`, local]);
+        return { type: "ledger", action: "deleted", local };
+    }
+    if (listed.code !== 0 || !local)
+        return undefined;
+    const forge = listed.out.split(/\s+/)[0];
+    if (!forge || forge === local)
+        return undefined;
+    if (gitStatus(top, ["fetch", "--quiet", "--no-tags", "origin", `+refs/heads/${LEDGER}:${FORGE_LEDGER}`]).code !== 0)
+        return undefined;
+    try {
+        const ahead = gitStatus(top, ["merge-base", "--is-ancestor", forge, local]).code === 0;
+        const behind = gitStatus(top, ["merge-base", "--is-ancestor", local, forge]).code === 0;
+        if (ahead || behind)
+            return undefined;
+        tryGit(top, ["update-ref", `refs/heads/${LEDGER}`, forge, local]);
+        tryGit(top, ["update-ref", `refs/remotes/origin/${LEDGER}`, forge]);
+        return { type: "ledger", action: "reset", local, forge };
+    }
+    finally {
+        tryGit(top, ["update-ref", "-d", FORGE_LEDGER]);
+    }
+}
+/** A commit message that asks for no CI run, as Actions and GitLab read it. */
+const SKIP_CI = /\[(?:skip ci|ci skip)\]/i;
+/** Whether `commit`'s message asks for no CI run. A commit this clone can't read is not skipped. */
+function skipsCi(top, commit) {
+    const body = tryGit(top, ["log", "-1", "--format=%B", commit]);
+    return body !== undefined && SKIP_CI.test(body);
+}
+/**
+ * How the target branch moved from `from` to `head` (#4122): `fast-forward`
+ * when `head` descends from `from`, `other` when it does not, and `unknown`
+ * when `head` could not be fetched. Once `head` is here its history is too,
+ * so a `from` this clone lacks is not in that history.
+ */
+function targetMove(top, branch, from, head) {
+    tryGit(top, ["fetch", "--quiet", "--no-tags", "origin", branch]);
+    if (gitStatus(top, ["cat-file", "-e", `${head}^{commit}`]).code !== 0)
+        return "unknown";
+    return gitStatus(top, ["merge-base", "--is-ancestor", from, head]).code === 0 ? "fast-forward" : "other";
+}
 /** Where a serve keeps its state when `--state` names nowhere: beside the run events, in the repository's common git directory. */
 export function defaultCiServeStateDir(cwd) {
     const common = tryGit(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
@@ -93,15 +190,23 @@ function writeState(file, state) {
 const failedEntry = (entry, key, rt) => !!entry && (entry.status === "fail" || (entry.status === "running" && !rt.inflight.has(key)));
 /**
  * One poll of the forge, as triggers: an apply when the target's head moved
- * since the last apply (none on the first poll, which only notes the head),
+ * since the last apply by a fast-forward (none on the first poll, which only
+ * notes the head, and none for a head whose message says `[skip ci]`),
  * then a plan for each open pull request head not yet planned, oldest pull
  * request first. A job already in the state file is left out unless it
- * failed and `rerunFailed` is set. The first poll's head is written to the
- * state file.
+ * failed and `rerunFailed` is set. The first poll's head, and a head seen
+ * and not applied, are written to the state file.
  */
 export async function ciServeObserve(opts, rt = newCiServeRuntime()) {
     const place = servePlace(opts);
-    const state = readCiServeState(place.stateFile, { forge: opts.forge, repo: opts.repo, env: opts.env, branch: place.branch, ...(place.member ? { member: place.member } : {}) });
+    const fresh = { forge: opts.forge, repo: opts.repo, env: opts.env, branch: place.branch, ...(place.member ? { member: place.member } : {}) };
+    const state = readCiServeState(place.stateFile, fresh);
+    // Read again at the write: a job of this serve may have settled while the forge answered.
+    const update = (fn) => {
+        const s = readCiServeState(place.stateFile, fresh);
+        fn(s);
+        writeState(place.stateFile, s);
+    };
     const triggers = [];
     const events = [];
     const [head, prs] = await Promise.all([opts.client.branchHead(place.branch), opts.client.openPullRequests(place.branch)]);
@@ -110,14 +215,27 @@ export async function ciServeObserve(opts, rt = newCiServeRuntime()) {
     }
     else if (state.target === undefined) {
         // What the branch held before this runner watched it was applied by whatever ran then.
-        state.target = head;
-        writeState(place.stateFile, state);
+        update((s) => {
+            s.target = head;
+        });
         events.push({ type: "baseline", commit: head });
     }
     else if (head !== state.target) {
+        const from = state.target;
+        const move = targetMove(place.top, place.branch, from, head);
         const entry = state.jobs[ciServeKey({ job: "apply", commit: head })];
-        if (!entry)
-            triggers.push({ job: "apply", commit: head, base: state.target });
+        if (move === "unknown") {
+            events.push({ type: "error", message: `${place.branch} is at ${head.slice(0, 12)} on the forge, and that commit could not be fetched; the next poll tries again` });
+        }
+        else if (move === "other" || (!entry && skipsCi(place.top, head))) {
+            // #4122: a move that is not a fast-forward, or a head that asks for no run, is seen and not applied.
+            update((s) => {
+                s.target = head;
+            });
+            events.push({ type: "not-run", job: "apply", commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch: place.branch, from } : {}) });
+        }
+        else if (!entry)
+            triggers.push({ job: "apply", commit: head, base: from });
         else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt))
             triggers.push({ job: "apply", commit: head, base: entry.base, rerun: true });
     }
@@ -140,10 +258,21 @@ export async function ciServeObserve(opts, rt = newCiServeRuntime()) {
         const key = ciServeKey({ job: "plan", commit: pr.headSha, pr: pr.number });
         const entry = state.jobs[key];
         const base = pr.baseSha ?? head;
-        if (!base)
+        if (!base || state.skipped?.[key])
             continue;
-        if (!entry)
-            triggers.push({ job: "plan", commit: pr.headSha, base, pr: pr.number });
+        if (!entry) {
+            // #4122: a head whose message asks for no run is seen and not planned.
+            if (gitStatus(place.top, ["cat-file", "-e", `${pr.headSha}^{commit}`]).code !== 0)
+                tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", `refs/pull/${pr.number}/head`]);
+            if (skipsCi(place.top, pr.headSha)) {
+                update((s) => {
+                    s.skipped = { ...s.skipped, [key]: "skip-ci" };
+                });
+                events.push({ type: "not-run", job: "plan", commit: pr.headSha, pr: pr.number, reason: "skip-ci" });
+            }
+            else
+                triggers.push({ job: "plan", commit: pr.headSha, base, pr: pr.number });
+        }
         else if (opts.rerunFailed && failedEntry(entry, key, rt))
             triggers.push({ job: "plan", commit: pr.headSha, base: entry.base, pr: pr.number, rerun: true });
     }
@@ -199,6 +328,12 @@ export async function ciServeSchedule(opts, triggers, rt = newCiServeRuntime())
             }
             lease = got.lease;
         }
+        // #4121: with no other job of this serve writing it, the clone's ledger follows the forge's.
+        if (rt.inflight.size === 0) {
+            const ledger = reconcileCiServeLedger(place.top);
+            if (ledger)
+                emit(ledger);
+        }
         const previous = readCiServeState(place.stateFile, fresh).jobs[key];
         const attempt = (previous?.attempts ?? 0) + 1;
         const runId = `chant-serve-${now().getTime()}-${t.job}-${t.commit.slice(0, 8)}`;
@@ -238,10 +373,14 @@ async function runJob(opts, place, t, paths, held) {
         }, Math.max(1000, Math.floor(held.ttlMs / 3)))
         : undefined;
     renew?.unref?.();
+    let merged;
     try {
         // The pull request's head is on the forge's refs/pull/<n>/head, the target's on the branch.
         tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", t.job === "plan" ? `refs/pull/${t.pr}/head` : place.branch]);
         const hostEnv = { ...(opts.job?.hostEnv ?? process.env), GITHUB_REPOSITORY: opts.repo };
+        // An apply is for a merge: pass the pull request whose merge commit it is, so the commit status link and the run index use `<pr>/<commit>`. None found, or a forge that errs, is today's behaviour.
+        if (t.job === "apply" && opts.client.pullRequestFor)
+            merged = (await opts.client.pullRequestFor(t.commit).catch(() => null)) ?? undefined;
         const run = opts.run ?? ciRun;
         const r = await run({
             ...opts.job,
@@ -251,17 +390,17 @@ async function runJob(opts, place, t, paths, held) {
             env: opts.env,
             forge: opts.forge,
             base: t.base,
-            ...(t.job === "plan" ? { pr: t.pr } : {}),
+            ...(t.job === "plan" ? { pr: t.pr } : merged !== undefined ? { pr: merged } : {}),
             commit: t.commit,
             output: paths.report,
             runId: paths.runId,
             ...(paths.resume ? { resumeRecord: paths.resume } : {}),
         });
         const why = r.record.failure ? `${r.record.failure.code}: ${r.record.failure.reason}` : r.failure ? `${r.failure.phase}: ${r.failure.error.split("\n")[0]}` : undefined;
-        return { status: r.status === "ok" ? "ok" : "fail", ...(why && r.status !== "ok" ? { failure: why } : {}), ...(r.report ? { report: r.report } : {}) };
+        return { status: r.status === "ok" ? "ok" : "fail", ...(merged !== undefined ? { pr: merged } : {}), ...(why && r.status !== "ok" ? { failure: why } : {}), ...(r.report ? { report: r.report } : {}) };
     }
     catch (err) {
-        return { status: "fail", failure: message(err) };
+        return { status: "fail", ...(merged !== undefined ? { pr: merged } : {}), failure: message(err) };
     }
     finally {
         if (renew)
@@ -319,14 +458,50 @@ export function formatCiServeEvent(e) {
             return `${at(e.job, e.commit, e.pr)} started, run ${e.runId}, attempt ${e.attempt}${e.resume ? ", resuming" : ""}`;
         case "settled":
             return `${at(e.job, e.commit, e.pr)} ${e.status === "ok" ? "passed" : `failed${e.failure ? `: ${e.failure}` : ""}`}${e.report ? `; report ${e.report}` : ""}`;
+        case "not-run":
+            return e.reason === "skip-ci"
+                ? `${at(e.job, e.commit, e.pr)} is not run: its commit message says [skip ci]`
+                : `${e.branch ?? "the target branch"} moved from ${e.from?.slice(0, 12) ?? "a commit"} to ${e.commit.slice(0, 12)}, which is not a fast-forward, so ${e.commit.slice(0, 12)} is recorded as seen and not applied`;
+        case "ledger":
+            return e.action === "deleted"
+                ? `the forge has no ${LEDGER}, so this clone's, at ${e.local.slice(0, 12)}, was deleted`
+                : `the forge's ${LEDGER} at ${e.forge.slice(0, 12)} does not contain this clone's at ${e.local.slice(0, 12)}, so this clone's was reset to the forge's and not pushed`;
         case "error":
             return `error: ${e.message}`;
     }
 }
 // ── The command ──────────────────────────────────────────────────────────────
-const USAGE = "chant ci serve --forge forgejo|github --repo <owner/repo> --env <env> [--interval <s>] [--max-jobs <n>] [--state <dir>] " +
-    "[--author <login>]... [--once] [--rerun-failed] [--gate <name>] [--branch <name>] [--events-json] [--report-url <url>] " +
-    "[--image <image>] [--before-script <line>]... [--pr-build] [--pr-build-command <line>] [--chant <command>] [--pass-env <NAME>]... [--key <runner key.pem>]";
+/**
+ * `chant ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]` (#4099):
+ * make the host's runner key when there is none, print its public half on
+ * stdout, and say whether the target's head lists it. With --trust, commit
+ * the runner entry on a branch of its own and push it for review.
+ */
+export function runnerKeySetupCommand(ctx) {
+    const { args } = ctx;
+    const cwd = process.cwd();
+    const top = gitTop(cwd);
+    if (!top)
+        throw new CiRunError("the runner key is kept in the repository's git directory, and this directory is not in a git repository");
+    if (args.ciPrincipal !== undefined && !args.trustKey)
+        throw new CiRunError("--principal names who --trust lists the key for; give --trust with it");
+    const branch = args.branch ?? "main";
+    const setup = setupRunnerKey({
+        top,
+        stateDir: args.statePath ? resolve(args.statePath) : defaultCiServeStateDir(cwd),
+        branch,
+        ...(args.ciPrincipal ? { principal: args.ciPrincipal } : {}),
+        ...(args.trustKey ? { trust: true } : {}),
+        ...(args.by ? { by: args.by } : {}),
+    });
+    console.log(setup.key.publicKey);
+    console.error(formatRunnerKeySetup(setup, branch));
+    return 0;
+}
+const USAGE = "chant ci serve --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>] | " +
+    "chant ci serve --forge forgejo|github --repo <owner/repo> --env <env> [--interval <s>] [--max-jobs <n>] [--state <dir>] " +
+    "[--author <login>]... [--once] [--rerun-failed] [--gate <name>] [--wave-gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--no-status] [--status-url <url template>] " +
+    "[--image <image>] [--before-script <line>]... [--pr-build] [--pr-build-command <line>] [--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [--unsigned]";
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** `--interval`: seconds, or a duration such as `30s` or `2m`. Default 30 seconds. */
 export function ciServeInterval(value) {
@@ -341,6 +516,8 @@ export function ciServeInterval(value) {
 export async function runCiServe(ctx) {
     const { args } = ctx;
     try {
+        if (args.setupKey)
+            return runnerKeySetupCommand(ctx);
         const forge = args.forge;
         if (forge !== "forgejo" && forge !== "github")
             throw new CiRunError(`--forge names the forge ci serve polls: --forge forgejo|github${forge ? `, not ${JSON.stringify(forge)}` : ""}`);
@@ -352,41 +529,69 @@ export async function runCiServe(ctx) {
             if (!ENV_NAME.test(name))
                 throw new CiRunError(`--pass-env takes a variable's name, not ${JSON.stringify(name)}`);
         const intervalMs = ciServeInterval(args.interval);
-        const fromFlag = args.key !== undefined;
-        const runnerKey = fromFlag ? readFileSync(resolve(args.key), "utf-8") : process.env[RUNNER_KEY_ENV] || undefined;
+        const cwd = process.cwd();
+        const top = gitTop(cwd);
+        if (!top)
+            throw new CiRunError("ci serve runs in a clone of the repository it serves, and this directory is not in a git repository");
+        const stateDir = args.statePath ? resolve(args.statePath) : defaultCiServeStateDir(cwd);
+        const branch = args.branch ?? "main";
+        // #4099: the host's key, checked against .chant/trust.json at the target's head before the first poll.
+        // #4156: signing is opt-in. Without ci.green.signedSince no key is quiet, and an untrusted one warns once and serves unsigned.
+        const keyed = ciServeRunnerKey({
+            top,
+            stateDir,
+            branch,
+            ...(args.key !== undefined ? { keyFile: resolve(args.key) } : {}),
+            envKey: process.env[RUNNER_KEY_ENV] || undefined,
+            unsigned: args.unsigned,
+            required: signedRunsRequired(cwd),
+        });
+        const fromFlag = keyed.fromFlag;
+        const runnerKey = keyed.pem;
+        if (keyed.warning)
+            console.error(formatWarning({ message: keyed.warning }));
+        if (runnerKey !== undefined)
+            console.error(`ci serve: signing runs with the runner key from ${keyed.source}`);
+        else if (keyed.note && args.verbose)
+            console.error(`ci serve: ${keyed.note}`);
+        // #4096: read once, so a loose or broken secrets file stops the serve before its first poll.
+        const secrets = ciSecretsOf(args.ciSecrets);
+        // #4160: without --report-url, the declaration's ci.reportUrl.
+        const reportUrl = await reportUrlOf(args.reportUrl, cwd);
+        if (reportUrl && !args.reportUrl)
+            console.error(`ci serve: reports and the run index go to ${reportUrl}, the declaration's ci.reportUrl`);
         const hostEnv = { ...process.env, GITHUB_REPOSITORY: args.ciRepo };
         const client = forgeFromEnv(forge, hostEnv);
+        const { status, warning } = ciStatusFromEnv({ forge, hostEnv, noStatus: args.noStatus, statusUrl: args.statusUrl });
+        if (warning)
+            console.error(formatWarning({ message: warning }));
         if (!client.openPullRequests || !client.branchHead)
             throw new CiRunError(`the ${forge} client cannot list pull requests`);
         const opts = {
-            cwd: process.cwd(),
+            cwd,
             forge,
             repo: args.ciRepo,
             env: args.env,
-            client: { openPullRequests: client.openPullRequests.bind(client), branchHead: client.branchHead.bind(client) },
-            ...(args.statePath ? { stateDir: isAbsolute(args.statePath) ? args.statePath : resolve(args.statePath) } : {}),
+            client: { openPullRequests: client.openPullRequests.bind(client), branchHead: client.branchHead.bind(client), pullRequestFor: client.pullRequestFor.bind(client) },
+            stateDir,
             ...(args.maxJobs ? { maxJobs: args.maxJobs } : {}),
             ...(args.ciAuthors?.length ? { authors: args.ciAuthors } : {}),
             ...(args.rerunFailed ? { rerunFailed: true } : {}),
             job: {
-                loop: {
-                    ...(args.gate ? { gate: args.gate } : {}),
-                    ...(args.branch ? { branch: args.branch } : {}),
-                    ...(args.eventsJson ? { events: true } : {}),
-                    ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
-                    ...(args.prBuild ? { build: true } : {}),
-                    ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
-                },
+                loop: ciLoopOptions(reportUrl ? { ...args, reportUrl } : args),
+                ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),
                 ...(args.image ? { image: args.image } : {}),
                 ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
                 ...(args.ciChant ? { chant: args.ciChant } : {}),
                 ...(args.passEnv?.length ? { passEnv: args.passEnv } : {}),
+                ...(status ? { status } : {}),
+                ...(secrets ? { secrets } : {}),
                 ...(runnerKey !== undefined ? { runnerKey, runnerKeyFromEnv: !fromFlag } : {}),
                 ...(args.eventsJson ? { runEvents: (line) => void process.stdout.write(line) } : {}),
                 hostEnv,
                 stepOutput: (line) => void process.stderr.write(`${line}\n`),
             },
-            log: (e) => console.error(e.type === "error" ? formatWarning({ message: formatCiServeEvent(e) }) : `ci serve: ${formatCiServeEvent(e)}`),
+            log: (e) => console.error(e.type === "error" || e.type === "ledger" ? formatWarning({ message: formatCiServeEvent(e) }) : `ci serve: ${formatCiServeEvent(e)}`),
         };
         if (args.once) {
             const pass = await ciServePass(opts);

package/dist/workspace/declaration.d.ts

@@ -171,6 +171,14 @@ export type CiSource = "checks" | "runs";
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
     green: CiGreen | null;
+    /**
+     * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
+     * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
+     * An `s3://` or `file://` URL, as `--report-url` takes, without a trailing
+     * slash. The commands that take `--report-url` default to it. Null when
+     * the declaration sets none.
+     */
+    reportUrl: string | null;
 }
 export interface MemberRole {
     name: string;