@intentius/chant 0.124.32 → 0.124.34

package/src/cli/handlers/release-verify.e2e.test.ts

@@ -3,8 +3,10 @@
  * (#4049), in a temp repo with a temp bare remote and throwaway ssh keys. A
  * release cut signed with a key `.chant/allowed_signers` lists verifies, and a
  * publish takes it; an unsigned one and one signed by a key the file does not
- * list fail `release verify`, and a publish refuses them unless
- * `--allow-unsigned`. Nothing is published: the member declares no target.
+ * list fail `release verify`. With no release gate or verified-releases
+ * group a publish takes them and records their status (#4168);
+ * release-publish.test.ts covers the refusals under the group. Nothing is
+ * published: the member declares no target.
  */
 
 import { describe, expect, test } from "vitest";
@@ -42,7 +44,7 @@ const BUILD = `mkdir -p dist && printf '{"env":"%s"}' "$CHANT_ENV" > dist/api.te
 
 describe("chant release verify", () => {
   test.skipIf(!hasSshKeygen)(
-    "passes for a signed release, fails for an unsigned one and for one signed by an unlisted key; a publish refuses both unless --allow-unsigned",
+    "passes for a signed release, fails for an unsigned one and for one signed by an unlisted key; a publish with no security group takes both and records their status",
     () => {
       const root = mkdtempSync(join(tmpdir(), "chant-release-verify-"));
       try {
@@ -89,10 +91,10 @@ describe("chant release verify", () => {
         expect(unsigned.code).toBe(1);
         expect(unsigned.stderr).toMatch(/v2.* does not verify: no cut of the release carries a signature \[release-unsigned\]/);
         expect(JSON.parse(chant(dir, ["release", "verify", "v2", "--json"]).stdout)).toMatchObject({ status: "unsigned", error: { code: "release-unsigned" } });
-        const pubUnsigned = chant(dir, ["release", "publish", "v2"]);
-        expect(pubUnsigned.code).toBe(1);
-        expect(pubUnsigned.stderr).toMatch(/\[release-unsigned\]/);
-        expect(chant(dir, ["release", "publish", "v2", "--allow-unsigned"]).code).toBe(0);
+        // #4168: with no release gate or verified-releases group, a publish takes it and records it unsigned.
+        const pubUnsigned = chant(dir, ["release", "publish", "v2", "--json"]);
+        expect(pubUnsigned.code, pubUnsigned.stderr).toBe(0);
+        expect(JSON.parse(pubUnsigned.stdout)).toMatchObject({ signature: { status: "unsigned" }, warnings: [] });
 
         // v3: signed by mallory, whom the signers file does not list.
         next("v3");
@@ -101,9 +103,9 @@ describe("chant release verify", () => {
         const unlisted = chant(dir, ["release", "verify", "v3"]);
         expect(unlisted.code).toBe(1);
         expect(unlisted.stderr).toMatch(/mallory has no key in \.chant\/allowed_signers at [0-9a-f]{12}.*\[release-signature-unverified\]/);
-        const pubUnlisted = chant(dir, ["release", "publish", "v3"]);
-        expect(pubUnlisted.code).toBe(1);
-        expect(pubUnlisted.stderr).toMatch(/\[release-signature-unverified\]/);
+        const pubUnlisted = chant(dir, ["release", "publish", "v3", "--json"]);
+        expect(pubUnlisted.code, pubUnlisted.stderr).toBe(0);
+        expect(JSON.parse(pubUnlisted.stdout)).toMatchObject({ signature: { status: "unverified" }, warnings: [] });
 
         const missing = chant(dir, ["release", "verify", "v9"]);
         expect(missing.code).toBe(1);

package/src/cli/handlers/release.e2e.test.ts

@@ -128,8 +128,8 @@ describe("chant release cut, publish and list", () => {
         expect(result.release.releaseDigest).toBe(dryJson.releaseDigest);
         expect(result.release.commit).toBe(sha);
         expect(result.release.targets).toEqual([
-          { env: "dev", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"dev"}`) }] },
-          { env: "prod", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"prod"}`) }] },
+          { env: "dev", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"dev"}`) }], trees: [] },
+          { env: "prod", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"prod"}`) }], trees: [] },
         ]);
         expect(result.cut).toMatchObject({ actor: "t@chant.dev", runId: expect.stringMatching(/^local-\d+$/), runOrigin: { forge: "local" }, signature: null });
         expect(result.next).toEqual(["git push origin release/v1", "chant release publish v1", "chant components promote --release v1 --to dev"]);
@@ -151,41 +151,32 @@ describe("chant release cut, publish and list", () => {
         expect(doc.releases[0]).toMatchObject({ releaseDigest: result.release.releaseDigest, label: "v1", environments: [] });
         expect(doc.releases[0].cuts[0]).toMatchObject({ runId: result.cut.runId, runOrigin: { forge: "local" } });
 
-        // #4049: the cut is not signed, so a publish refuses it unless --allow-unsigned.
-        const unsignedPub = chant(dir, ["release", "publish", "v1"]);
-        expect(unsignedPub.code).toBe(1);
-        expect(unsignedPub.stderr).toMatch(/v1 has no signed cut.*\[release-unsigned\]/);
-        expect(unsignedPub.stderr).toContain("pass --allow-unsigned");
-
+        // #4168: the cut is not signed, and with no release gate or verified-releases group a publish takes it quietly.
         // A publish is a dry run without --yes, as a cut is.
-        const dryPub = chant(dir, ["release", "publish", "v1", "--allow-unsigned"]);
+        const dryPub = chant(dir, ["release", "publish", "v1"]);
         expect(dryPub.code, dryPub.stderr).toBe(0);
-        expect(dryPub.stderr).toContain("v1 has no signed cut; publishing it anyway under --allow-unsigned");
+        expect(dryPub.stderr).not.toContain("release-unsigned");
+        expect(dryPub.stderr).not.toContain("no signed cut");
         expect(dryPub.stdout).toContain("What would be published where:\n  nothing: this member declares no publish target (release.publish in chant.config.ts)");
-        expect(dryPub.stderr).toContain("Dry run: nothing was published. Run again with --yes to publish: chant release publish v1 --allow-unsigned --yes");
+        expect(dryPub.stderr).toContain("Dry run: nothing was published. Run again with --yes to publish: chant release publish v1 --yes");
 
-        // Publish from the workstation: the warning comes before anything else is said about publishing.
-        const pub = chant(dir, ["release", "publish", "v1", "--allow-unsigned", "--yes"]);
+        // Publish from the workstation: with no supply-chain group there is no OIDC warning either.
+        const pub = chant(dir, ["release", "publish", "v1", "--yes"]);
         expect(pub.code, pub.stderr).toBe(0);
-        const warning = pub.stderr.indexOf("this publish runs without OIDC, so what it publishes carries no provenance");
-        const nothing = pub.stderr.indexOf("Nothing was published: this member declares no publish target (release.publish in chant.config.ts).");
-        expect(warning).toBeGreaterThan(-1);
-        expect(nothing).toBeGreaterThan(warning);
+        expect(pub.stderr).not.toContain("without OIDC");
+        expect(pub.stderr).toContain("Nothing was published: this member declares no publish target (release.publish in chant.config.ts).");
         expect(pub.stderr).toContain("chant components promote --release v1 --to dev");
 
-        // In GitHub Actions with id-token: write there is no warning.
+        // The --json document records what is missing: no signature and no OIDC provenance.
+        const asJson = chant(dir, ["release", "publish", "v1", "--json"]);
+        expect(asJson.code, asJson.stderr).toBe(0);
+        expect(JSON.parse(asJson.stdout)).toMatchObject({ dryRun: true, label: "v1", signature: { status: "unsigned" }, provenance: { oidc: false }, warnings: [], targets: [], published: [] });
+
+        // In GitHub Actions with id-token: write the provenance is OIDC.
         const oidc = { GITHUB_ACTIONS: "true", ACTIONS_ID_TOKEN_REQUEST_URL: "https://token.example", ACTIONS_ID_TOKEN_REQUEST_TOKEN: "t" };
-        const fromCi = chant(dir, ["release", "publish", "v1", "--allow-unsigned", "--json"], oidc);
+        const fromCi = chant(dir, ["release", "publish", "v1", "--json"], oidc);
         expect(fromCi.code, fromCi.stderr).toBe(0);
-        expect(fromCi.stderr).not.toContain("without OIDC");
-        expect(JSON.parse(fromCi.stdout)).toMatchObject({
-          dryRun: true,
-          label: "v1",
-          provenance: { oidc: true, ci: "github" },
-          warnings: ["v1 has no signed cut; publishing it anyway under --allow-unsigned, so chant release verify v1 will fail for it"],
-          targets: [],
-          published: [],
-        });
+        expect(JSON.parse(fromCi.stdout)).toMatchObject({ dryRun: true, label: "v1", provenance: { oidc: true, ci: "github" }, warnings: [], targets: [], published: [] });
 
         const unknown = chant(dir, ["release", "publish", "v9"]);
         expect(unknown.code).toBe(1);

package/src/cli/handlers/release.ts

@@ -1,7 +1,7 @@
 /**
  * `chant release` (#4026, ws-104): the release is what graduates.
  *
- *   release cut [<label>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
+ *   release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
  *       a dry run of a cut of this member from the checkout's HEAD, which must be
  *       clean, on trunk and pushed, and green (#4027); `--yes` cuts, records,
  *       and tags the commit `release/<label>` locally;
@@ -17,6 +17,9 @@
  *   release verify <label|digest> [--json]
  *       check the release's signature offline against .chant/allowed_signers
  *       at the release's commit (#4049)
+ *   release candidates [--env <env>] [--json]
+ *       the green commits of trunk a release can be cut from, each with what it
+ *       would ship, and what each environment runs (#4168 4.2)
  *   release list [--json]
  *       every release of this member with its targets, its cuts and where it runs;
  *       `--json` prints the read contract's `releases` document
@@ -39,13 +42,19 @@ import { parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
 
 const USAGE =
-  "chant release cut [<label>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
+  "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
 
 /** The build inputs `release cut` and `release compile` share. */
-function compileInputs(ctx: CommandContext, params: Record<string, string> | undefined): import("../../components/release-compile").CompileInputs {
+function compileInputs(
+  ctx: CommandContext,
+  params: Record<string, string> | undefined,
+  projectDir: string = resolve("."),
+  releaseLabel?: string | null,
+): import("../../components/release-compile").CompileInputs {
   const { args } = ctx;
   return {
-    projectDir: resolve("."),
+    projectDir,
+    ...(releaseLabel ? { releaseLabel } : {}),
     ...(args.buildCommand ? { buildCommand: args.buildCommand } : {}),
     ...(params ? { params } : {}),
     ...(args.paramsFile ? { paramsFile: args.paramsFile } : {}),
@@ -102,6 +111,11 @@ function describeActorSource(source: import("../../lifecycle/release-workstation
  * would record, build and tag, and what publishes where. With `--yes` it
  * cuts, signs with `--sign`, records the cut with its actor and run id,
  * tags the commit locally and prints the next command.
+ *
+ * `--at <sha>` (#4168 4.2) cuts that commit instead of `HEAD`, from a
+ * temporary worktree (../../lifecycle/release-at.ts), so the checkout need
+ * not be clean or at the commit. The label reaches every compile and
+ * artifact build as `CHANT_RELEASE_LABEL` (decision 5).
  */
 export async function runReleaseCut(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
@@ -124,6 +138,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: `${message} [${code}]`, ...(fix ? { hint: fix } : {}) }));
     return 1;
   };
+  const at = await import("../../lifecycle/release-at");
+  let checkout: import("../../lifecycle/release-at").CommitCheckout | null = null;
 
   try {
     // The workstation checks come first, in the order #4027 lists them; the
@@ -139,9 +155,16 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     let trunk: import("../../lifecycle/release-workstation").Trunk | null = null;
     let signers: readonly import("../../workspace/trust/trust-files").Signer[] = [];
     let member: string | null = null;
+    if (args.at !== undefined && !top) {
+      return fail("not-a-git-repository", "--at names a commit, and this directory is not in a git repository");
+    }
     if (top) {
-      commit = await getHeadCommit({ cwd });
-      ws.checkCleanTree(top, commit);
+      if (args.at !== undefined) {
+        commit = at.resolveCutCommit(top, args.at);
+      } else {
+        commit = await getHeadCommit({ cwd });
+        ws.checkCleanTree(top, commit);
+      }
       const { scopeSource } = await import("../../workspace/write-scope");
       const { releaseRuleFrom } = await import("../../workspace/identity");
       const source = scopeSource(cwd);
@@ -179,8 +202,11 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     const tag = label !== null && commit !== null && top ? { name: ws.releaseTagName(member, label), state: ws.checkReleaseTag(top, ws.releaseTagName(member, label), commit) } : null;
     const ci = resolveCiRun(process.env);
     const params = parseParamFlags(args.param);
-    const compiler = spawnTargetCompiler(compileInputs(ctx, params));
-    const request = { cwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) };
+    // --at: the cut reads, compiles and builds the commit's tree, not the checkout's.
+    if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
+    const cutCwd = checkout?.memberDir ?? cwd;
+    const compiler = spawnTargetCompiler(compileInputs(ctx, params, cutCwd, label));
+    const request = { cwd: cutCwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) };
 
     if (dryRun) {
       const plan = await planRelease(request);
@@ -195,7 +221,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       const ref = plan.label ?? plan.alreadyCut ?? plan.releaseDigest;
       const provenance = detectProvenance();
       // The targets release publish would run, as the config here declares them; their files are read at publish.
-      const publishTargets = await releasePublishTargets(cwd).then(
+      const publishTargets = await releasePublishTargets(cutCwd).then(
         (ts) => ts.map((t) => `${t.name} to ${t.destination}`),
         (err: unknown) => (err instanceof Error ? err : new Error(String(err))),
       );
@@ -207,6 +233,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
         actorSource: who.source,
         run: ci ? { runId: ci.runId, runOrigin: ci.runOrigin } : { runId: null, runOrigin: { forge: "local" as const } },
         trunk,
+        at: args.at !== undefined ? { ref: args.at, commit } : null,
         sign: args.sign !== undefined ? { key: publicKey !== null ? publicKey.split(" ")[0] : null, readable: publicKey !== null } : null,
         tag: tag ? { name: tag.name, exists: tag.state === "present" } : null,
         publish: { targets: Array.isArray(publishTargets) ? publishTargets : [], provenance },
@@ -294,7 +321,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     if (tagWarning) console.error(formatWarning({ message: tagWarning }));
     return 0;
   } catch (err) {
-    if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError) {
+    if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError || err instanceof at.CutAtError) {
       return fail(err.code, err.message, err.fix);
     }
     if (err instanceof ReleaseLabelError) return fail(err.code, err.message);
@@ -303,6 +330,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       return 1;
     }
     throw err;
+  } finally {
+    checkout?.remove();
   }
 }
 
@@ -480,6 +509,47 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * `release candidates [--env <env>] [--json]` (#4168 4.2): the green commits
+ * of trunk a release can be cut from, newest first, each with what it would
+ * ship since the previous one, and what each environment runs. `--json`
+ * prints the read contract's `release-candidates` document.
+ */
+export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
+  const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
+  const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}) });
+  if (ctx.args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.message} [${doc.error.code}]`, hint: USAGE }));
+    return 1;
+  }
+  for (const e of doc.environments) {
+    const runs = e.running.map((r) => `${r.label ?? r.releaseDigest.slice(0, 19)}${r.commit ? ` at ${r.commit.slice(0, 12)}` : ""}`).join(", ");
+    console.log(`${e.env}: ${runs || "runs no release yet"}`);
+  }
+  if (!doc.tip) {
+    console.error(`No candidates: this clone knows no ${doc.branch}. Fetch it: git fetch origin ${doc.branch} --tags`);
+    return 0;
+  }
+  if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not green yet`);
+  if (doc.candidates.length === 0) console.log(`No green commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
+  for (const c of doc.candidates) {
+    const tags = [...(c.newFor.length > 0 ? [`new for ${c.newFor.join(", ")}`] : []), ...(c.cut.length > 0 ? [`cut as ${c.cut.join(", ")}`] : [])];
+    console.log(`${c.commit.slice(0, 12)}  ${c.subject}${tags.length > 0 ? `  (${tags.join("; ")})` : ""}`);
+    for (const ch of c.changes) {
+      const links = [...(ch.pr !== null ? [`#${ch.pr}`] : []), ...ch.work.map((w) => `work:${w}`)];
+      console.log(`    ${ch.commit.slice(0, 12)}  ${ch.subject}${links.length > 0 ? `  [${links.join(", ")}]` : ""}`);
+    }
+    for (const f of c.flags) console.log(`    flag ${f.id} (${f.member} ${f.param}) changed`);
+  }
+  for (const sk of doc.skipped) console.log(`skipped ${sk.commit.slice(0, 12)}  ${sk.subject}  (revoked)`);
+  if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>`);
+  return 0;
+}
+
 export async function runReleaseList(ctx: CommandContext): Promise<number> {
   const { releasesDocument } = await import("../../workspace/releases");
   const doc = await releasesDocument({ cwd: resolve(".") });
@@ -540,7 +610,7 @@ export async function runReleaseExport(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: target.error }));
     return 1;
   }
-  const read = await targetFiles(found.release, target.target, (digest) => readReleaseTemplate(digest));
+  const read = await targetFiles(found.release, target.target, (digest, encoding) => readReleaseTemplate(digest, undefined, encoding));
   if ("errors" in read) {
     for (const e of read.errors) console.error(formatError({ message: e }));
     return 1;

package/src/cli/main.ts

@@ -249,22 +249,28 @@ CI:
                         chant/lifecycle; with ci.green.signedSince, the ones a
                         runner key signed. Pushes the
                         tags. --key, or the PEM in CHANT_RUNNER_KEY, signs
-                        each tag with a runner key.
+                        each tag with a runner key. A cancelled run leaves a
+                        commit unbuilt, not red, and a failed run is run
+                        again once. A phase with build: newest leaves the
+                        commits a newer run superseded unbuilt, and a red
+                        one starts a bisect: a ci/build/<sha> tag the tick
+                        starts the phase's workflow at. Each commit judged
+                        gets a _ci/<sha>.json record on chant/lifecycle.
   ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>]
               [--forge github|gitlab|forgejo] [--gate <name>] [--wave-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>]... [--secrets <file>] [--key <runner key.pem>]
-              [-o <dir>] [--wave <k>] [--no-require-review]
+              [-o <dir>] [--wave <k>] [--require-review]
               [--no-status] [--status-url <url template>]
-              [--in-place | --local] [--no-push] [--verbose]
-                        Run the pull-request pipeline's plan or apply job as
+              [--in-place | --local] [--no-push] [--require-runner-start] [--verbose]
+                        Run the pull-request pipeline's plan, record or apply job as
                         a pipeline Op in a fresh worktree of --commit (default
                         HEAD) with a clean environment. --base and --pr stand
                         in for the forge's event values. --pr-build runs
                         the job's build and lint lines first. Records the run as
-                        pr-plan or pr-apply on chant/lifecycle, which ci tick
+                        pr-plan, pr-record or pr-apply on chant/lifecycle, which ci tick
                         from runs counts, signed when --key or CHANT_RUNNER_KEY
                         gives a runner key, and copies the report to -o
                         (default .chant/pr). --in-place runs in this checkout
@@ -286,17 +292,39 @@ CI:
                         kept on the local chant/lifecycle with runOrigin
                         local and is never pushed, no status is set, nothing
                         goes under a report URL, and ci tick does not count it.
+                        --require-runner-start refuses the job before its
+                        first step unless a runner-start statement, signed by
+                        a runner key .chant/trust.json at --base lists, names
+                        this forge job.
+  ci runner-start sign --key <runner key.pem> --principal <name> --job <json|@file> [-o <file>]
+                        For the provisioner that starts a runner for one job:
+                        sign the job's system, repo, run, attempt, job,
+                        commit and runner name, and print the envelope.
+  ci runner-start verify [--base <rev>] [--commit <sha>] [--json]
+                        In the job: check the statement in CHANT_RUNNER_START,
+                        or the file CHANT_RUNNER_START_FILE names (default
+                        /run/chant/runner-start.json), against the forge's
+                        variables and .chant/trust.json at --base (default
+                        origin/HEAD). Exits 1 unless it verifies.
+  ci run --at <sha>     Ask for every required phase at a commit of the
+                        green branch with a ci/build/<sha> tag, and start the
+                        workflows holding them there on GitHub when a token
+                        is set; otherwise the next tick, or ci serve
+                        --build-command, does.
   ci runs [--report-url <url>] [--json]
                         List the runs in the index at the report URL (default
                         the workspace's ci.reportUrl), newest first.
   ci serve --forge forgejo|github --repo <owner/repo> --env <env>
               [--interval <s>] [--max-jobs <n>] [--state <dir>]
               [--author <login>]... [--once] [--rerun-failed] [--unsigned]
-              [ci run's job flags]
+              [--apply-on-merge] [--build-command <line>] [ci run's job flags]
                         Poll the forge for open pull requests and the target
                         branch's head, and run ci run plan for each new pull
-                        request head and ci run apply for each new commit on
-                        the branch. Dedupes on job and commit in a state file
+                        request head and ci run record for each new commit on
+                        the branch, then ci tick from the runs when the
+                        workspace declares ci.green. A merge deploys nothing;
+                        --apply-on-merge runs ci run apply in place of the
+                        record, and --wave-gate needs it. Dedupes on job and commit in a state file
                         under --state, takes a lease per apply group, keeps
                         each apply's resume record there, and runs at most
                         --max-jobs (default 1) jobs at once. --once runs one
@@ -304,13 +332,22 @@ CI:
                         failed apply or plan again. Signs runs with a runner
                         key when .chant/trust.json at the target's head lists
                         it, and serves unsigned otherwise; with
-                        ci.green.signedSince it refuses to start without one
+                        ci.green.signedSince it refuses to start without one.
+                        --build-command runs <line> once per ci/build/<sha>
+                        tag, in a fresh worktree of the commit, with
+                        CHANT_BUILD_COMMIT and CHANT_BUILD_PHASES set
   ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]
                         Make the host's runner key (Ed25519, mode 0600) in the
                         state directory when there is none and print its public
                         key. --trust commits its runner entry on a branch of its
                         own and pushes it for review; the target branch is never
                         written
+  ci init --workflow trunk-curated|trunk-curated+apply-on-merge
+              [--forge github|gitlab|forgejo] [--security <group>]... [--yes]
+                        Set the workspace up for a prescribed delivery workflow:
+                        print what it would write as a diff, then write it on
+                        --yes or a yes at the prompt and run the generators. A
+                        rerun proposes only what workspace check still reports
   ci workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
@@ -322,10 +359,14 @@ CI:
                         or a GitHub App's id and key, pushes the tags with a
                         token that may tag commits changing workflow files.
                         --runner-key-secret hands the tick the runner key it
-                        signs its tags with.
+                        signs its tags with. For each phase that sets build,
+                        it also writes the triggers and concurrency of the
+                        workflows holding it: newest builds on pushes and by
+                        hand, one run at a time, and every gives each commit
+                        a run of its own.
 
 Releases:
-  release cut [<label>] [--yes] [--build <command>] [--param <k=v>]
+  release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>]
               [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>]
               [--actor <name>] [--sign [<key file>]] [--json]
                         A dry run of a cut of this member from HEAD, which
@@ -344,22 +385,37 @@ Releases:
                         requires it. A project with no components releases
                         what chant build --env <env> writes: --src <dir> is
                         the build root, -o <file> the output (dist/build.yaml),
-                        --lexicon narrows it.
+                        --lexicon narrows it. --at <sha> cuts that commit of
+                        trunk from a temporary worktree instead of HEAD, so
+                        the checkout need not be clean. The label reaches
+                        every compile and build as CHANT_RELEASE_LABEL.
+  release candidates [--env <env>] [--json]
+                        The green commits of trunk a release can be cut from,
+                        newest first, each with the commits, work items, pull
+                        requests and flags it would ship, and what each
+                        environment runs.
   release publish <label|digest> [--yes] [--allow-unsigned]
                   [--require-provenance] [--json]
                         Publish a cut release to the targets release.publish
                         in chant.config.ts declares (npm, OCI registries,
-                        forge release assets), each with an SBOM and the
-                        release's provenance. A dry run without --yes.
-                        Refuses a revoked release, one whose signature does
-                        not verify against .chant/allowed_signers unless
-                        --allow-unsigned, and with a target a checkout that
-                        is not the release's commit. Warns first when the run
-                        has no OIDC token, so what it publishes carries no
-                        OIDC provenance; --require-provenance refuses instead.
+                        forge release assets), each with the release's
+                        provenance and an SBOM when it has a source. A dry
+                        run without --yes. Refuses a revoked release, and
+                        with a target a checkout that is not the release's
+                        commit. Under security verified-releases it refuses
+                        one whose signature does not verify against
+                        .chant/allowed_signers unless --allow-unsigned; under
+                        supply-chain it warns when the run has no OIDC token
+                        and refuses a target with no SBOM source.
+                        --require-provenance refuses a run with no OIDC.
   release verify <label|digest> [--json]
                         Check, offline, that the release was signed by a key
                         .chant/allowed_signers lists at the release's commit.
+  release workflow [--forge github|gitlab|forgejo] [--install <command>]
+              [--build <command>] [--chant <command>] [--output <file>]
+                        Write the publish workflow, run on a release/** tag.
+                        Under supply-chain it passes --require-provenance, and
+                        under verified-releases it runs release verify first
   release list [--json]  Every release of this member with its targets, its
                         cuts and the environments that run it.
   release export <label|digest> --env <env> [-o <dir>] [--json]
@@ -887,6 +943,10 @@ Lifecycle (alias: lc):
                             estate size rather than stack count (#2405)
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle health <env>    Whether each declared service is up, separate from
+                            drift: ECS running vs desired, Route 53 health
+                            checks, Container Apps revisions, Cloud Run Ready.
+                            A failed read is "not read", never unhealthy (--json)
   lifecycle whoami <env>    Who chant would act as in each configured lexicon,
                             and what that principal is scoped to — read-only,
                             before anything acts (--json, --strict)
@@ -931,7 +991,12 @@ Component release ledger + status:
                             report and note (--base <ref> --pr <n>
                             [--forge github|gitlab|forgejo] posts them);
                             applies nothing
-  components pr-apply      On merge: plan the same members again and apply
+  components pr-record     On merge (#4168): plan the same members again,
+                            store the change set and write the merge record
+                            _merges/<commit>.json; applies and refuses
+                            nothing, and a plan that differs from the
+                            approved one sets a failing chant/record status
+  components pr-apply      With --apply-on-merge: plan the same members again and apply
                             them only if an approval stands for that digest
                             (chant approve pr-<n> pr-apply --plan <digest>);
                             a moved plan refuses with exit 3
@@ -968,7 +1033,11 @@ Component release ledger + status:
                              [--component <name> [--digest <sha256:...>]];
                              --from defaults to the environment before --to
                              in the config's environments; --dry-run prints
-                             the plan; the target's gates still apply)
+                             the plan; the target's gates still apply. Under
+                             --release a dependent plans against its
+                             upstream's planned outputs and plans again once
+                             it applies; --wave-gate <gate> checks each wave
+                             at <gate>-wave-<k>; a stop writes --resume <file>)
   components rollback <env> Redeploy an earlier release of an environment
                             from its recorded digest (--component <name>
                             [--digest <sha256:...>]; defaults to the release
@@ -1383,9 +1452,12 @@ export const commandRegistry: CommandDef[] = [
   { name: "ci list", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiList(ctx) },
   { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiTick(ctx) },
   { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiWorkflow(ctx) },
+  { name: "ci init", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-init")).runCiInit(ctx) },
   // #4094: one pull-request job as a pipeline Op in a fresh checkout, the chant runner's first slice.
   { name: "ci run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run")).runCiRun(ctx) },
   // #4098: the run index at the report URL.
+  // #4147: a provisioner's signed word that it started a runner for one job, signed and checked.
+  { name: "ci runner-start", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-runner-start")).runCiRunnerStart(ctx) },
   { name: "ci runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run-index")).runCiRuns(ctx) },
   { name: "ci serve", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-serve")).runCiServe(ctx) },
   // #4026: the release cut from a green commit (ws-104). Imported on first use.
@@ -1394,6 +1466,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "release publish", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleasePublish(ctx) },
   // #4049: check a release's signature offline.
   { name: "release verify", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseVerify(ctx) },
+  { name: "release workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-workflow")).runReleaseWorkflow(ctx) },
+  { name: "release candidates", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCandidates(ctx) },
   { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseList(ctx) },
   { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseExport(ctx) },
   { name: "release compile", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCompile(ctx) },
@@ -1504,6 +1578,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
   { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
+  // #4177 — runtime health, separate from drift. Imported on first use.
+  { name: "lifecycle health", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-health")).runLifecycleHealth(ctx) },
   { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
   // #4036 — retention's garbage collection. Imported on first use.
@@ -1519,6 +1595,7 @@ export const commandRegistry: CommandDef[] = [
   // #3183 — the pull-request loop the generated CI runs. Imported on first use.
   { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
   { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
+  { name: "components pr-record", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrRecord(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },

package/src/cli/parse-args.ts

@@ -70,6 +70,7 @@ const BOOLEAN_FLAGS = new Set([
   "--trust",
   "--unsigned",
   "--in-place",
+  "--require-runner-start",
   "--no-push",
   "--no-require-review",
   "--expire",
@@ -409,9 +410,17 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.requireProvenance = true;
     } else if (arg === "--pr-loop") {
       result.prLoop = true;
+    } else if (arg === "--apply-on-merge") {
+      // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
+      result.applyOnMerge = true;
     } else if (arg === "--pr-build") {
       // `chant build --pr-loop --pr-build` (#4088), and `chant ci run --pr-build` (#4094).
       result.prBuild = true;
+    } else if (arg === "--build-command") {
+      // `chant ci serve --build-command <line>` (#4169): the line that builds a requested commit.
+      const line = args[++i];
+      if (line === undefined || line === "") throw new Error("--build-command needs a shell line: --build-command '<line>'");
+      result.ciBuildCommand = line;
     } else if (arg === "--pr-build-command") {
       const line = args[++i];
       if (line === undefined || line === "") throw new Error("--pr-build-command needs a shell line: --pr-build-command '<line>'");
@@ -531,6 +540,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace wip --branch <branch>` (#3172)
       result.branch = args[++i];
       if (!result.branch || result.branch.startsWith("-")) throw new Error("--branch needs a branch name: --branch <branch>");
+    } else if (arg === "--security") {
+      // `chant ci init --security <group>`, repeatable (#4168 step 6): a security group to turn on.
+      const group = args[++i];
+      if (!group || group.startsWith("-")) throw new Error("--security needs a group: --security verified-releases|supply-chain|who-ran-it|review-rules|isolated-runners");
+      result.securityGroups = [...(result.securityGroups ?? []), group];
     } else if (arg === "--workflow") {
       // `chant ci workflow --workflow <name>`, repeatable (#3573)
       const name = args[++i];
@@ -783,11 +797,18 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--in-place") {
       // `chant ci run --in-place` (#4156): run the job in this checkout, as a generated forge job does.
       result.ciInPlace = true;
+    } else if (arg === "--require-runner-start") {
+      // `chant ci run --require-runner-start` (#4147): refuse the job unless a provisioner's runner-start statement names it.
+      result.requireRunnerStart = true;
+    } else if (arg === "--job") {
+      // `chant ci runner-start sign --job <json|@file>` (#4147): the CI job a runner was started for.
+      result.ciJob = args[++i];
+      if (!result.ciJob || result.ciJob.startsWith("-")) throw new Error("--job needs the job as JSON or @<file>: --job @job.json");
     } else if (arg === "--no-push") {
       // `chant ci run --no-push` (#4156): keep the run record on the local chant/lifecycle.
       result.noPush = true;
     } else if (arg === "--no-require-review") {
-      // `chant ci run apply --no-require-review` (#4156): the apply without pr-apply's --require-review.
+      // `chant ci run apply --no-require-review` (#4156): the apply without pr-apply's --require-review, the default since #4168.
       result.requireReview = false;
     } else if (arg === "--unsigned") {
       // `chant ci serve --unsigned` (#4099): serve without a runner key listed at the target's head.