@intentius/chant 0.124.28 → 0.124.30

package/src/cli/handlers/run.ts

@@ -15,7 +15,7 @@ import { pointAnswerCommand, renderHuman, renderJson } from "../../op/local-outp
 import { loadPlugins } from "../plugins";
 import { recordGateApproval } from "./operator";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
-import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
+import { parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
 import { stewardBesideFor, stewardFormFor, stewardTurnLeaseName, DEFAULT_STEWARD_ENV, type StewardDeclaration } from "../../op/steward";
 import { holdBesideLease } from "../../op/steward-beside";
@@ -470,7 +470,13 @@ async function runOpLogOnRuntime(ctx: CommandContext, name: string): Promise<num
 export function humanRunEventLine(e: RunEvent): string {
   const x = e as unknown as Record<string, unknown>;
   const where = [x.component, x.phase, x.step].filter((v): v is string => typeof v === "string").join("/");
-  const detail = [where, typeof x.status === "string" ? x.status : "", typeof x.error === "string" ? x.error : ""].filter(Boolean).join(" ");
+  const detail = [
+    where,
+    typeof x.status === "string" ? x.status : "",
+    // A blocked component (#4007) names what held it back.
+    typeof x.blockedBy === "string" ? `by ${x.blockedBy}` : "",
+    typeof x.error === "string" ? x.error : "",
+  ].filter(Boolean).join(" ");
   return `${String(x.at ?? "")}  ${String(x.type).padEnd(16)}${detail}`.trimEnd();
 }
 
@@ -926,6 +932,7 @@ export async function recordAutoReleasesForRun(
   runId: string,
   disabled: boolean,
   runOrigin: RunOrigin = { forge: "local" },
+  releaseDigest?: string,
 ): Promise<ReleaseRecord[]> {
   const recorded: ReleaseRecord[] = [];
   for (const componentResult of results) {
@@ -942,6 +949,8 @@ export async function recordAutoReleasesForRun(
         // #1035, #4020: who approved at the gate and which resolution admitted the deploy.
         ...(gateApprover(componentResult) ? { approver: gateApprover(componentResult) } : {}),
         ...(gateAdmission(componentResult) ? { admission: gateAdmission(componentResult) } : {}),
+        // #4043: the release the deploy was made under, when `--release` named one.
+        ...(releaseDigest !== undefined ? { releaseDigest } : {}),
       },
       { disabled },
     );
@@ -1051,6 +1060,44 @@ function refusesNoRecordOn(runtime: Pick<OpRuntimeProvider, "name">): boolean {
   return true;
 }
 
+/**
+ * Resolve the release `chant run --components --release` names (#4043), or the
+ * reason it can't be used. The run builds from the checked-out commit, so the
+ * release's commit must be HEAD, and the release needs a target for `env`.
+ */
+export async function resolveRunRelease(ref: string, env: string, cwd: string) {
+  const { fetchLifecycle, getHeadCommit } = await import("../../lifecycle/git");
+  const { resolveRelease } = await import("../../lifecycle/release-store");
+  const { targetFor } = await import("../../components/release-promote");
+  await fetchLifecycle({ cwd }).catch(() => false);
+  const found = await resolveRelease(ref, { cwd });
+  if (!found) return `no release is labelled or digested "${ref}" in this member`;
+  const name = found.label ?? found.release.releaseDigest;
+  const head = await getHeadCommit({ cwd });
+  if (found.release.commit !== head) {
+    return `release ${name} was cut from ${found.release.commit.slice(0, 12)} and this checkout is at ${head.slice(0, 12)}; run builds from the checkout, so check out the release's commit, or deploy it with \`chant components promote --release\``;
+  }
+  const target = targetFor(found.release, env);
+  if ("error" in target) return target.error;
+  return { releaseDigest: found.release.releaseDigest, label: found.label, release: found.release };
+}
+
+/** A rebuilt image need not digest as the release's own did; say so, as promote does. Never fails the run. */
+async function warnOnArtifactMismatch(release: import("../../lifecycle/release-store").Release, recorded: readonly ReleaseRecord[]): Promise<void> {
+  try {
+    const { releaseArtifactMismatches } = await import("../../components/release-promote");
+    const { readBuildManifest } = await import("../../lifecycle/build-ledger-store");
+    const mismatches = await releaseArtifactMismatches(
+      release,
+      recorded.map((r) => ({ component: r.component, source: r })),
+      (digest) => readBuildManifest(digest).catch(() => null),
+    );
+    for (const message of mismatches) console.error(formatWarning({ message }));
+  } catch {
+    // The record is written; a manifest that can't be read is not worth failing the run for.
+  }
+}
+
 async function runComponentSelection(ctx: CommandContext): Promise<number> {
   const selector = ctx.args.path;
   if (!selector || selector === ".") {
@@ -1066,11 +1113,13 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
 
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
-  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+  // #4024: with --env, a workspace member's flag records back their parameters.
+  const { resolveFlaggedBuildParams } = await import("../../flag-params");
+  const paramsResolution = await resolveFlaggedBuildParams(projectPath, config.buildParams, {
     cli: parseParamFlags(ctx.args.param),
     paramsFile: ctx.args.paramsFile,
     verbose: ctx.args.verbose,
-  });
+  }, ctx.args.env);
   if (!paramsResolution.success) {
     for (const message of paramsResolution.errors) console.error(message);
     return 1;
@@ -1088,6 +1137,20 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
   }
 
   const env = ctx.args.env ?? "local";
+
+  // #4043: `--release <label|digest>` says this run deploys that release. The
+  // run builds from the checked-out commit, so the release must have been cut
+  // from it, and must have a target for the environment. Both are checked
+  // before anything deploys; nothing is inferred when the flag is absent.
+  let underRelease: { releaseDigest: string; label: string | null; release: import("../../lifecycle/release-store").Release } | undefined;
+  if (ctx.args.release) {
+    const refused = await resolveRunRelease(ctx.args.release, env, projectPath);
+    if (typeof refused === "string") {
+      console.error(formatError({ message: refused, hint: "List the releases with: chant release list" }));
+      return 1;
+    }
+    underRelease = refused;
+  }
   // Seed cross-component/cross-stack outputs from upstream jobs' dumped files
   // (`--seed-outputs`), so a single-component run resolves references to a
   // component that ran in an earlier CI job.
@@ -1207,7 +1270,8 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
   if (result.success && result.run) {
     // #3955: a run that records nothing has no release to report either.
     const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord) || ledgerRecordingOff();
-    const recorded = await recordAutoReleasesForRun(result.run.results, env, release.runId, disabled, release.runOrigin);
+    const recorded = await recordAutoReleasesForRun(result.run.results, env, release.runId, disabled, release.runOrigin, underRelease?.releaseDigest);
+    if (underRelease) await warnOnArtifactMismatch(underRelease.release, recorded);
     // `--digest-file` (#2602): the releases this run recorded, one
     // `<component>=<digest>` line each, the form `chant components promote
     // --digest` takes. A generated promote job reads it to promote exactly

package/src/cli/main.test.ts

@@ -828,6 +828,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace ls",
       "workspace member",
       "workspace member-run",
+      "workspace metrics",
       "workspace patch",
       "workspace pin",
       "workspace points",

package/src/cli/main.ts

@@ -249,6 +249,33 @@ CI:
                         chant/lifecycle that a runner key signed. Pushes the
                         tags. --key, or the PEM in CHANT_RUNNER_KEY, signs
                         each tag with a runner key.
+  ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>]
+              [--forge github|gitlab|forgejo] [--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>] [-o <dir>]
+                        Run the pull-request pipeline's plan 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, signed with
+                        --key or CHANT_RUNNER_KEY, so ci tick from runs counts
+                        it, and copies the report to -o (default .chant/pr).
+  ci serve --forge forgejo|github --repo <owner/repo> --env <env>
+              [--interval <s>] [--max-jobs <n>] [--state <dir>]
+              [--author <login>]... [--once] [--rerun-failed]
+              [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
+                        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
+                        poll and waits for its jobs. --rerun-failed runs a
+                        failed apply or plan again.
   ci workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
@@ -263,12 +290,18 @@ CI:
                         signs its tags with.
 
 Releases:
-  release cut [<label>] [--build <command>] [--param <k=v>] [--params-file <file>]
-              [--src <dir>] [-o <file>] [--lexicon <name>] [--sign [<key file>]]
-                        Cut a release of this member from HEAD, which must
-                        carry a ci/green tag: compile every environment in
-                        the config's environments, build the artifacts once,
-                        and store it on chant/lifecycle under its digest.
+  release cut [<label>] [--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
+                        must be clean, on trunk and pushed, and carry a
+                        ci/green tag: compile every environment in the
+                        config's environments and print what the cut would
+                        build, record and tag, and what publishes where.
+                        --yes cuts: builds the artifacts once, stores the
+                        release on chant/lifecycle under its digest, records
+                        the actor and run id, tags the commit release/<label>
+                        here, and prints the next command.
                         --build runs before each environment's templates are
                         read, with CHANT_ENV set; {env} in --params-file is
                         replaced by the environment. --sign signs the cut with
@@ -277,6 +310,21 @@ Releases:
                         what chant build --env <env> writes: --src <dir> is
                         the build root, -o <file> the output (dist/build.yaml),
                         --lexicon narrows it.
+  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.
+  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 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]
@@ -344,7 +392,9 @@ Ops:
                         run, and prints that order first (#3950).
                         On success, auto-emits a release-ledger record per
                         component that published a digest (default: on;
-                        --no-release-record to opt out; #597)
+                        --no-release-record to opt out; #597).
+                        --release <label|digest>: the run is of that release,
+                        cut from this checkout's commit; the records name it (#4043)
                         --progress-json: stream one NDJSON RunProgressEvent
                         per line to stdout while the run executes, for a
                         consumer to render live wave/component/phase/step
@@ -443,6 +493,13 @@ Workspace (level 1, #2524):
                         beside it and marks the members whose digests differ.
                         Read only; never fetches. --json prints the
                         read-contract document
+  workspace metrics [dir] [--env <env>] [--member <name>] [--since <date>] [--json]
+                        The four DORA metrics per member and environment
+                        (#4039): deployment frequency, lead time from commit
+                        to running release, change failure rate and time to
+                        restore, from the deploy records, releases and ci
+                        revoked tags. Eight weeks back by default. Read only;
+                        never fetches. --json prints the read-contract document
   workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
@@ -757,7 +814,7 @@ Workspace (level 1, #2524):
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance
                         with none lists an empty set
-  workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
+  workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
                         The intent graph over one region: the commits that
                         touched it, the decisions whose constrains cover it,
                         the artifacts they pin, and findings with closed codes.
@@ -796,6 +853,13 @@ Lifecycle (alias: lc):
                             executes the plan (production-like names also need
                             --confirm-prod, or an interactive confirmation)
   lifecycle log [env]       History of lifecycle snapshots
+  lifecycle gc [--yes] [--push] [--json]
+                            Prune stored change sets, releases and run event
+                            files by the retention policy (#4036). A dry run
+                            without --yes; --yes writes one commit removing
+                            them on the local chant/lifecycle and deletes the
+                            run event files; --push pushes it. History is
+                            never rewritten, and the ledgers are never pruned
 
 Plan scenarios (#1292):
   scenario check            Evaluate every declared Scenario's expect clause
@@ -834,7 +898,11 @@ Component release ledger + status:
                             --member <name>, both commands: a workspace
                             member's loop, gate op pr-<n>-<member>;
                             --resume <file> finishes an apply that failed
-                            partway under the same approval)
+                            partway under the same approval;
+                            --events-json, both commands: the run-event
+                            stream on stdout; --report-url <s3 or file URL>,
+                            both commands: copy the report, the change set
+                            and the events to <url>/<pr>/<commit>/)
   components release <env> Append one immutable release record
                             (--component <name> --digest <sha256:...>
                              [--git-sha <sha>] [--run-id <id>] [--actor <name>]);
@@ -858,7 +926,9 @@ Component release ledger + status:
   components rollback <env> Redeploy an earlier release of an environment
                             from its recorded digest (--component <name>
                             [--digest <sha256:...>]; defaults to the release
-                            before the current one; --dry-run prints the plan)
+                            before the current one; --dry-run prints the plan).
+                            --release <label|digest> restores every component
+                            of that release through the release gate (#4035)
   components redeploy <env> Redeploy the release an environment's ledger
                             records as current, after a deploy that failed
                             partway (--component <name> [--digest <sha256:...>];
@@ -1263,8 +1333,15 @@ 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) },
+  // #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) },
+  { 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.
   { name: "release cut", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCut(ctx) },
+  // #4027: publish a cut release, to the targets #4047 declares.
+  { 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 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) },
@@ -1323,6 +1400,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli")).runWorkspaceWork(ctx) },
   // #3033 — the agent run record: what each run cost and which commits it made. chant records runs and never starts one.
   { name: "workspace runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/runs-cli")).runWorkspaceRuns(ctx) },
+  // #4039 — DORA metrics from the deploy, release and revocation records.
+  { name: "workspace metrics", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/delivery-metrics")).runWorkspaceMetrics(ctx) },
   { name: "workspace status", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },
@@ -1373,6 +1452,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
   { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
+  // #4036 — retention's garbage collection. Imported on first use.
+  { name: "lifecycle gc", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/lifecycle-gc")).runLifecycleGc(ctx) },
 
   // Plan scenarios (#1292) — fully offline, no plugin network calls, but
   // requiresPlugins:true so the build step has serializers to partition

package/src/cli/parse-args.ts

@@ -42,6 +42,7 @@ const BOOLEAN_FLAGS = new Set([
   "--composites",
   "--stacks",
   "--components",
+  "--pr-build",
   "--up",
   "--down",
   "--include-dependents",
@@ -64,6 +65,7 @@ const BOOLEAN_FLAGS = new Set([
   "--yes",
   "--confirm-prod",
   "--once",
+  "--rerun-failed",
   "--expire",
   "--check-live",
   "--check-snapshot",
@@ -74,12 +76,15 @@ const BOOLEAN_FLAGS = new Set([
   "--uncommitted",
   "--allow-code",
   "--allow-skip",
+  "--allow-unsigned",
+  "--require-provenance",
   "--root-only",
   "--generated",
   "--decide",
   "--record-plans",
   "--loopback",
   "--artifacts",
+  "--push",
 ]);
 
 /**
@@ -248,6 +253,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.dryRun = true;
     } else if (arg === "--yes") {
       result.yes = true;
+    } else if (arg === "--push") {
+      // `chant lifecycle gc --yes --push` (#4036): push the prune commit.
+      result.push = true;
     } else if (arg === "--confirm-prod") {
       result.confirmProd = true;
     } else if (arg === "--strict") {
@@ -375,8 +383,26 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.forge || result.forge.startsWith("-")) throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
     } else if (arg === "--require-review") {
       result.requireReview = true;
+    } else if (arg === "--report-url") {
+      // `chant components pr-plan|pr-apply --report-url <url>` (#4007).
+      const url = args[++i];
+      if (!url || url.startsWith("-")) throw new Error("--report-url needs a URL: --report-url s3://<bucket>/<prefix> or file://<directory>");
+      result.reportUrl = url;
+    } else if (arg === "--allow-unsigned") {
+      // `chant release publish --allow-unsigned` (#4049).
+      result.allowUnsigned = true;
+    } else if (arg === "--require-provenance") {
+      // `chant release publish --require-provenance` (#4049).
+      result.requireProvenance = true;
     } else if (arg === "--pr-loop") {
       result.prLoop = 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 === "--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>'");
+      result.prBuildCommand = line;
     } else if (arg === "--before-script") {
       const line = args[++i];
       if (line === undefined || line === "") throw new Error("--before-script needs a shell line: --before-script '<line>'");
@@ -427,11 +453,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace graph --composites` (#2662)
       result.composites = true;
     } else if (arg === "--intent") {
-      // `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651), or `--intent --record <id>` with no region.
+      // `chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha>` (#2651), or `--intent --record <id>` with no region.
       const value = args[i + 1];
       if (value !== undefined && !value.startsWith("-")) result.intent = args[++i];
       else if (args.includes("--record")) result.intent = "";
-      else throw new Error("--intent needs a region: --intent <path[:start-end]|path#symbol>, or --intent --record <id>");
+      else throw new Error("--intent needs a region: --intent <path[:start-end]|path#symbol|member/node|sha>, or --intent --record <id>");
     } else if (arg === "--follow-squash") {
       // `chant workspace graph --intent ... --follow-squash` and `chant workspace runs --follow-squash` (#3035)
       result.followSquash = true;
@@ -501,6 +527,32 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant ci workflow --chant <command>` (#3573): what the tick step runs chant with.
       result.ciChant = args[++i];
       if (!result.ciChant || result.ciChant.startsWith("-")) throw new Error("--chant needs the command that runs chant, such as \"npx tsx packages/core/src/cli/main.ts\": --chant <command>");
+    } else if (arg === "--commit") {
+      // `chant ci run plan|apply --commit <sha>` (#4094): the commit the job runs at.
+      result.commit = args[++i];
+      if (!result.commit || result.commit.startsWith("-")) throw new Error("--commit needs the commit the job runs at: --commit <sha>");
+    } else if (arg === "--pass-env") {
+      // `chant ci run --pass-env <NAME>`, repeatable (#4094): a variable of the runner's environment the job gets.
+      const name = args[++i];
+      if (!name || name.startsWith("-")) throw new Error("--pass-env needs a variable's name, such as AWS_PROFILE: --pass-env <NAME>");
+      (result.passEnv ??= []).push(name);
+    } else if (arg === "--repo") {
+      // `chant ci serve --repo <owner/repo>` (#4095): the repository whose pull requests and target branch it polls.
+      result.ciRepo = args[++i];
+      if (!result.ciRepo || !/^[^/\s-][^/\s]*\/[^/\s]+$/.test(result.ciRepo)) throw new Error("--repo needs the repository as owner/name: --repo <owner/repo>");
+    } else if (arg === "--max-jobs") {
+      // `chant ci serve --max-jobs <n>` (#4095): how many jobs run at once.
+      const n = Number(args[++i]);
+      if (!Number.isInteger(n) || n < 1) throw new Error("--max-jobs needs a whole number of jobs, 1 or more: --max-jobs <n>");
+      result.maxJobs = n;
+    } else if (arg === "--author") {
+      // `chant ci serve --author <login>`, repeatable (#4095): plan only pull requests these people opened.
+      const login = args[++i];
+      if (!login || login.startsWith("-")) throw new Error("--author needs a forge login: --author <login>");
+      (result.ciAuthors ??= []).push(login);
+    } else if (arg === "--rerun-failed") {
+      // `chant ci serve --rerun-failed` (#4095): run again the failed apply at the target branch's head, and failed plans of open heads.
+      result.rerunFailed = true;
     } else if (arg === "--install") {
       // `chant ci workflow --install <command>` (#3573): a step before the tick that installs what --chant runs.
       result.ciInstall = args[++i];

package/src/cli/registry.ts

@@ -149,6 +149,10 @@ export interface ParsedArgs {
   allowCode?: boolean;
   /** `chant components promote --allow-skip` (#4030): promote past a step of the member's declared promotion order. */
   allowSkip?: boolean;
+  /** `chant release publish --allow-unsigned` (#4049): publish a release with no signature that verifies, with a warning. Never overrides identity.gates.release. */
+  allowUnsigned?: boolean;
+  /** `chant release publish --require-provenance` (#4049): refuse a run with no OIDC token, where it warns. */
+  requireProvenance?: boolean;
   /** `chant workspace upgrade --source <repo>[#<member>]` (#2551): move the scope to another template. */
   source?: string;
   /** `chant workspace adopt-lineage --tags <glob>` and `hash-index --tags` (#2551): the tags to compare. */
@@ -164,6 +168,8 @@ export interface ParsedArgs {
   /** `chant lifecycle teardown <env> --yes` — execute the planned deletion
    * (#1222). Without it the command plans and stops. */
   yes?: boolean;
+  /** `chant lifecycle gc --yes --push` (#4036): push the commit the prune wrote to chant/lifecycle. Without it the prune stays local. */
+  push?: boolean;
   /** `chant lifecycle teardown <env> --yes --confirm-prod` — the non-interactive
    * form of the extra confirmation a production-like environment name demands
    * (#1222). Meaningless without `--yes`. */
@@ -308,12 +314,22 @@ export interface ParsedArgs {
    * request. Needs `--forge`.
    */
   requireReview?: boolean;
+  /**
+   * `chant components pr-plan|pr-apply --report-url <url>` (#4007) — copy
+   * the stage's report, change set and run events to `<url>/<pr>/<commit>/`,
+   * an `s3://` or `file://` URL, the events as each wave and component settles.
+   */
+  reportUrl?: string;
   /**
    * `chant build --components --generate <lexicon> --pr-loop` (#3183) —
    * generate the pull-request pipeline: plan on the pull request, apply on
    * merge bound to the approved digest.
    */
   prLoop?: boolean;
+  /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
+  prBuild?: boolean;
+  /** `chant build --pr-loop --pr-build-command <line>` (#4088) — the build line to run in place of `chant build --env <env>`. */
+  prBuildCommand?: string;
   /**
    * `chant components fan-out --resume <file>` (#2420) — the attempt record
    * this fan-out reads before it starts and writes when it finishes. Repeating
@@ -404,7 +420,7 @@ export interface ParsedArgs {
   noCache?: boolean;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
-  /** `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651): the region the intent graph is over. Empty with `--record`. */
+  /** `chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha>` (#2651): the region the intent graph is over. Empty with `--record`. */
   intent?: string;
   /** `chant workspace graph --intent` and `chant workspace runs` (#3035): follow squash merges to their pull requests' original commits, fetching missing pull request refs. */
   followSquash?: boolean;
@@ -442,8 +458,20 @@ export interface ParsedArgs {
   branch?: string;
   /** `chant ci workflow --workflow <name>`, repeatable (#3573): a workflow whose completion triggers a tick, beside those the scan finds. */
   ciWorkflows?: string[];
-  /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. */
+  /** `chant ci run plan|apply --commit <sha>` (#4094): the commit the job runs at. Default `HEAD`. */
+  commit?: string;
+  /** `chant ci run --pass-env <NAME>`, repeatable (#4094): a variable of the runner's environment the job gets, beside the few it always gets. */
+  passEnv?: string[];
+  /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. Also `chant ci run --chant` (#4094): what runs chant in the job. */
   ciChant?: string;
+  /** `chant ci serve --repo <owner/repo>` (#4095): the repository it polls. */
+  ciRepo?: string;
+  /** `chant ci serve --max-jobs <n>` (#4095): how many jobs run at once. Default 1. */
+  maxJobs?: number;
+  /** `chant ci serve --author <login>`, repeatable (#4095): plan only pull requests these logins opened. */
+  ciAuthors?: string[];
+  /** `chant ci serve --rerun-failed` (#4095): run again the failed apply at the target's head and failed plans of open heads. */
+  rerunFailed?: boolean;
   /** `chant ci workflow --install <command>` (#3573): a step before the tick that installs what `--chant` runs. */
   ciInstall?: string;
   /** `chant ci workflow --token-secret <NAME>` (#3573): the repository secret the tick's tag push authenticates with. */
@@ -561,7 +589,7 @@ export interface ParsedArgs {
   digest?: string;
   /** `chant components release record --release-plan <file>` (ws-055, #2733) — path to a release plan JSON file, persisted content-addressed to `_plans/<digest>.json` on chant/lifecycle and read back through the read contract (`chant workspace status --json`). The plan's own `digest` field supplies `--digest` when it is omitted, and must match it when both are given. Distinct from `--plan` (#2300, below), the Op gate-approval plan digest. */
   releasePlanFile?: string;
-  /** `chant components promote --release <label|digest>` (#4026): deploy under that release, reading the templates its target for `--to` recorded. */
+  /** `chant components promote --release <label|digest>` (#4026): deploy under that release, reading the templates its target for `--to` recorded. `chant run --components --release <label|digest>` (#4043): the run is of that release, which must have been cut from the checked-out commit and have a target for `--env`; the release records the run writes name it. */
   release?: string;
   /** `chant release cut --build <command>` (#4026): the shell command run in the member's directory before each environment's templates are read, with `CHANT_ENV` set to the environment. */
   buildCommand?: string;
@@ -660,7 +688,7 @@ export interface ParsedArgs {
   plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
   op?: string;
-  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. `chant workspace records --since <rev>` (#2673) — the revision to compare the records with. */
+  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. `chant workspace records --since <rev>` (#2673) — the revision to compare the records with. `chant workspace metrics --since <date>` (#4039) — the start of the window the metrics count. */
   since?: string;
   /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
   limit?: number;

package/src/cli/run-events.ts

@@ -37,18 +37,21 @@ export const stdoutLine = (line: string): void => void process.stdout.write(line
 
 /**
  * The run's stream on stdout when `--events-json` was passed, else
- * undefined. The run is named by `runId` when the caller has one (so a
+ * undefined. Each line goes to stdout, to this host's store and to `also`
+ * when given. The run is named by `runId` when the caller has one (so a
  * release record and the stream name the same run), else by the CI run or a
  * local id.
  */
 export async function openCliRunEvents(
   args: Pick<ParsedArgs, "eventsJson">,
   run: { kind: RunEventKind; name: string; runId?: string; cwd?: string },
+  also?: (line: string) => void,
 ): Promise<RunEventStream | undefined> {
   if (!args.eventsJson) return undefined;
   const resolved = await resolveRunEventRun(run);
   // #4042: the stream is also kept on this host, so `chant run events <run>`
   // replays it. Only a command that was asked for a stream keeps one.
   const store = await openRunEventStore(run.cwd ?? process.cwd(), resolved.runId);
-  return openRunEventStream(resolved, teeLines(stdoutLine, store?.write.bind(store))!);
+  // `also`: a third copy of each line, such as `--report-url`'s upload (#4007).
+  return openRunEventStream(resolved, teeLines(stdoutLine, store?.write.bind(store), also)!);
 }

package/src/components/auto-release.test.ts

@@ -108,6 +108,15 @@ describe("maybeRecordAutoRelease", () => {
     expect(input).toMatchObject({ runId: "9001", runOrigin: { forge: "github", repo: "acme/app" }, approver: "alice", admission });
   });
 
+  test("a run under a release records its releaseDigest, and one under none records none (#4043)", async () => {
+    appendReleaseRecordMock.mockResolvedValue({ commit: "c".repeat(40), record: { version: 1 } });
+    const releaseDigest = `jcs1-sha256:${"c".repeat(64)}`;
+    await maybeRecordAutoRelease({ component: "svc", env: "dev", success: true, records: [publishRecord("sha256:abc")], runId: "r", releaseDigest }, { actor: "alice" });
+    await maybeRecordAutoRelease({ component: "svc", env: "dev", success: true, records: [publishRecord("sha256:abc")], runId: "r" }, { actor: "alice" });
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({ releaseDigest });
+    expect(appendReleaseRecordMock.mock.calls[1][0]).not.toHaveProperty("releaseDigest");
+  });
+
   test("an ungated deploy records neither", async () => {
     appendReleaseRecordMock.mockResolvedValue({ commit: "c".repeat(40), record: { version: 1 } });
     await maybeRecordAutoRelease({ component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "r" }, { actor: "alice" });

package/src/components/auto-release.ts

@@ -101,6 +101,8 @@ export interface AutoReleaseRunInfo {
   profileOverride?: string;
   /** The deploy's input-side digest, when `digest` is a rendered-content identity (a pinned helm deploy, chant #1242) — recorded as the release record's `inputDigest` so ledger queries can still join on inputs across clusters whose bytes legitimately differ. */
   inputDigest?: string;
+  /** The release the deploy was made under (#4043), recorded as the release record's `releaseDigest`. Set only when the caller named a release; never inferred. */
+  releaseDigest?: string;
 }
 
 /** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
@@ -191,6 +193,7 @@ export async function maybeRecordAutoRelease(
         ...(run.admission ? { admission: run.admission } : {}),
         ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
         ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
+        ...(run.releaseDigest ? { releaseDigest: run.releaseDigest } : {}),
       },
       { cwd: options.cwd },
     );

package/src/components/capability.ts

@@ -61,6 +61,15 @@ export interface DeployContext {
    * Absent outside a fan-out that writes a record.
    */
   carry?: (member: string, value: unknown) => void;
+  /**
+   * Set when a step is planned (#4084): the components or stacks whose
+   * outputs this step's input reads through `stackOutput()` or
+   * `@<component>.publish.*` and which had nothing to read yet, so the input
+   * holds `undefined` there. Their values are known only when the run
+   * applies them. A `plan` that needs them can say so instead of planning
+   * against missing values.
+   */
+  unresolvedInputs?: string[];
 }
 
 /**