@intentius/chant 0.124.27 → 0.124.29

package/src/cli/main.test.ts

@@ -16,6 +16,13 @@ describe("parseArgs", () => {
     expect(() => parseArgs(["graph", "--traffic"])).toThrow(/--traffic needs a level/);
   });
 
+  test("--before-script is repeatable and keeps its order; --image takes a reference (#4002)", () => {
+    const args = parseArgs(["build", "--components", "--generate", "forgejo", "--image", "node:22-bookworm", "--before-script", "npm ci", "--before-script", "-x"]);
+    expect(args.image).toBe("node:22-bookworm");
+    expect(args.beforeScript).toEqual(["npm ci", "-x"]);
+    expect(() => parseArgs(["build", "--before-script"])).toThrow(/--before-script needs a shell line/);
+  });
+
   test("--skip-undeclarable reaches live import (#3911)", () => {
     expect(parseArgs(["import", "--from", "prod"]).skipUndeclarable).toBeUndefined();
     expect(parseArgs(["import", "--from", "prod", "--skip-undeclarable"]).skipUndeclarable).toBe(true);
@@ -821,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

@@ -114,6 +114,7 @@ const runOpApprove = lazyHandler(runHandlers, (m) => m.runOpApprove);
 const runOpSignalRenamed = lazyHandler(runHandlers, (m) => m.runOpSignalRenamed);
 const runOpCancel = lazyHandler(runHandlers, (m) => m.runOpCancel);
 const runOpLog = lazyHandler(runHandlers, (m) => m.runOpLog);
+const runOpEvents = lazyHandler(runHandlers, (m) => m.runOpEvents);
 const runWaveHandlers = () => import("./handlers/run-wave");
 const runOpWaveCommand = lazyHandler(runWaveHandlers, (m) => m.runOpWaveCommand);
 const operatorHandlers = () => import("./handlers/operator");
@@ -227,22 +228,82 @@ Commands:
                                           applied) and path. Read-only.
 
 CI:
-  ci last-green [--json]  The newest first-parent commit of ci.green's branch
-                        with a ci/green tag and no ci/revoked tag. Reads local
-                        tags only; fetch them first.
-  ci tick [--dry-run] [--forge github]  Tag each commit within ci.green's
-                        window whose required phases all passed ci/green/<sha>,
-                        and revoke a green one that now fails ci/revoked/<sha>.
-                        Reads check runs from the forge, pushes the tags.
+  ci last-green [--json] [--from <rev>]  The newest first-parent commit of
+                        ci.green's branch, or of --from, with a ci/green tag
+                        and no ci/revoked tag. Reads local tags only; fetch
+                        them first. With ci.green.signedSince, a tag without a
+                        valid runner statement is ignored and reported.
+  ci list [--json] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs]
+                        The first-parent commits of ci.green's branch within
+                        its window, newest first, each green, revoked or
+                        undecided with its required phases' results. Reads
+                        local tags; --forge reads check runs for undecided
+                        commits, and source runs reads the signed Op runs on
+                        the local chant/lifecycle. --since replaces the window.
+  ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>]
+                        Tag each commit within ci.green's window whose
+                        required phases all passed ci/green/<sha>, and revoke
+                        a green one that now fails ci/revoked/<sha>. Reads
+                        check runs from the forge, or with source runs
+                        (ci.green.source or --source) the Op runs on
+                        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 workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
+              [--runner-key-secret <NAME>]
                         .github/workflows/chant-ci-green.yml, which runs the
                         tick when a required workflow completes and every 15m.
                         --chant replaces the npx @intentius/chant pin the tick
                         runs; --install adds a step before it. --token-secret,
                         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.
+
+Releases:
+  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
+                        the actor's ssh key; an identity.gates release entry
+                        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.
+  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]
+                        Write the files the release recorded for <env>, each
+                        checked against its digest, at their recorded paths
+                        under <dir> (default: here), for a deploy to read.
 
 Change sets:
   change-set summary <file>  The grouped plan summary of a change-set
@@ -251,6 +312,10 @@ Change sets:
                                           replacement, failure and hole named.
                                           markdown fits an MR/PR note of --limit
                                           characters (default 65536). Read-only.
+  change-set show <digest>  The change set a pull-request or release gate
+                        [--member <name>] [--json]  bound, stored on
+                                          chant/lifecycle under its digest, each
+                                          entry with its graph node. Read-only.
 
 Ops:
   run <name>            Run an Op on the resolved runtime (--on; local by default)
@@ -260,11 +325,18 @@ Ops:
                         its Drift outcome is true (WatchOp failOn: "drift")
                         --no-record: a test run that records nothing on
                         chant/lifecycle and pushes nothing (local runtime)
+                        --key <runner key.pem>, or the PEM in
+                        CHANT_RUNNER_KEY: sign the run's record with a runner
+                        key, so ci tick from runs counts it (#4044)
   run list              List all Ops with the runtime's state for each
   run status <name>     Show the runtime's state for one Op's latest run
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run events <run>      Replay a run's events kept on this host (a run id, or
+                        an Op or component name for its newest run). --json
+                        prints the run-event lines; --follow streams a run in
+                        progress until run-settle (#4042)
   run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
                         waves spec (#3679): the job a generated waves
                         pipeline runs. --decide plans and decides only;
@@ -293,12 +365,19 @@ 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
                         progress instead of tailing raw logs (additive; run
                         semantics/exit code unchanged)
+                        --events-json: stream the run's events instead, one
+                        run-event.schema.json line each, with the run id,
+                        commit and runtime on every line (#4041). Also on
+                        run <op>, components promote|rollback|redeploy,
+                        fan-out, pr-plan and pr-apply
   operator               Run scheduled ticks for discovered ConvergeOps
                         locally (#1485): acquire/renew a per-op
                         lease (git ref CAS), tick on --interval, record every
@@ -387,6 +466,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
@@ -664,7 +750,13 @@ Workspace (level 1, #2524):
                         the severity (warn by default) and ignore globs. When
                         the declaration at base has writeScope or agents, each
                         commit that writes outside its writer's scope fails
-                        the check (write-scope-member, write-scope-kind)
+                        the check (write-scope-member, write-scope-kind). Each
+                        first-parent commit of the range should name its work
+                        item in a Chant-Record: <work kind>:<id> or a
+                        Chant-Lease trailer. commit-unlinked is a commit that
+                        names none, commit-wrongly-linked one whose trailers
+                        name no work item that exists; both follow the
+                        severity
   workspace patch <base>..<head>|<base>...<head>|<commit> [--path <p>...] [--max-bytes <n>] [--json]
   workspace patch [<commit>] --worktree [--path <p>...] [--max-bytes <n>] [--json]
                         The hunks of a diff, file by file: a range, a work
@@ -695,7 +787,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.
@@ -734,6 +826,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
@@ -772,7 +871,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>]);
@@ -787,13 +890,18 @@ Component release ledger + status:
                             byte-for-byte plus a self-describing manifest.json
   components promote        Deploy the digests one environment's release
                             ledger records to another, without a build
-                            (--from <env> --to <env> [--component <name>
-                             [--digest <sha256:...>]]; --dry-run prints the
-                             plan; the target's gates still apply)
+                            (--to <env> [--from <env>] [--allow-skip]
+                             [--release <label|digest>]
+                             [--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)
   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:...>];
@@ -934,7 +1042,7 @@ Options:
                         chant.config.ts's build.sandbox: true; #1045)
   --param <name=value>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy) Bind a
+                        components redeploy, release cut) Bind a
                         declared build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
@@ -946,7 +1054,7 @@ Options:
                         chant.template.json declares instead (#2627).
   --params-file <path>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy) JSON file
+                        components redeploy, release cut) JSON file
                         of { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
                         init --from refuses it: pass --param instead.
@@ -1195,10 +1303,22 @@ export const commandRegistry: CommandDef[] = [
   { name: "carve status", handler: runCarveStatus },
   // #3573 — which commits passed CI, kept as ci/green and ci/revoked tags (ws-103). Imported on first use.
   { name: "ci last-green", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiLastGreen(ctx) },
+  { 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) },
+  // #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) },
   // #3188 — the grouped plan summary of a change-set document. Reads one file; imported on first use.
   { name: "change-set summary", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetSummary(ctx) },
+  // #4022: the change set a gate bound, read from chant/lifecycle by its digest.
+  { name: "change-set show", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetShow(ctx) },
   { name: "init", handler: runInit, runsNoConfig: true },
   { name: "init lexicon", handler: runInitLexicon },
 { name: "update", handler: runUpdate },
@@ -1220,6 +1340,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "run signal", handler: runOpSignalRenamed },
   { name: "run cancel", handler: runOpCancel },
   { name: "run log", handler: runOpLog },
+  { name: "run events", handler: runOpEvents },
   { name: "run wave", handler: runOpWaveCommand },
   // #3683 — start the CI jobs that wait at gates whose approval arrived. Imported on first use.
   { name: "run resume", handler: async (ctx) => (await import("./handlers/gate-resume")).runResumeCommand(ctx) },
@@ -1249,6 +1370,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) },
@@ -1299,6 +1422,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
@@ -1335,6 +1460,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
   { name: "components", handler: runComponentsUnknown },
+  { name: "release", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseUnknown(ctx) },
   { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceUnknown(ctx) },
 ];
 

package/src/cli/mcp/never-over-mcp.test.ts

@@ -217,6 +217,8 @@ describe("neverOverMcp (chant#3447)", () => {
   const gateOnlyOps: Array<{ op: string; gate: string }> = [
     { op: "workspace-upgrade", gate: "." },
     { op: "pr-12", gate: "pr-apply" },
+    // #4045: a release gate approves a change to an environment, as a pull request's does.
+    { op: "release", gate: "prod-release" },
   ];
 
   for (const { op, gate } of gateOnlyOps) {

package/src/cli/mcp/workspace-tools.ts

@@ -126,7 +126,7 @@ export const workspaceReadTools: ToolDefinition[] = [
   {
     name: "workspace-changes",
     description:
-      "The forward coverage check over a diff: chant workspace check --changes <range> --json (changes.schema.json, #2773). Each changed path with the current records whose constrains cover it, and a change-uncovered or change-out-of-scope finding for each gap, at the severity the declaration's changes block sets. Returns the document unchanged.",
+      "The forward coverage check over a diff: chant workspace check --changes <range> --json (changes.schema.json, #2773). Each changed path with the current records whose constrains cover it, and a change-uncovered or change-out-of-scope finding for each gap, at the severity the declaration's changes block sets. links says whether each trunk commit of the range names its work item, with commit-unlinked and commit-wrongly-linked findings at the same severity. Returns the document unchanged.",
     inputSchema: {
       type: "object",
       properties: {

package/src/cli/parse-args.ts

@@ -48,6 +48,8 @@ const BOOLEAN_FLAGS = new Set([
   "--local",
   "--json",
   "--progress-json",
+  "--events-json",
+  "--follow",
   "--update-snapshot",
   "--update-baseline",
   "--run-examples",
@@ -71,11 +73,16 @@ const BOOLEAN_FLAGS = new Set([
   "--current",
   "--uncommitted",
   "--allow-code",
+  "--allow-skip",
+  "--allow-unsigned",
+  "--require-provenance",
   "--root-only",
   "--generated",
   "--decide",
   "--record-plans",
   "--loopback",
+  "--artifacts",
+  "--push",
 ]);
 
 /**
@@ -191,8 +198,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.overlayAnchor = v;
     } else if (arg === "--from") {
       // Shared by `migrate --from <lexicon>`, `import --from <env>`,
-      // `components promote --from <env>` and `init --from <repo>@<ref>`;
-      // the commands never run together, so one field carries all four.
+      // `components promote --from <env>`, `init --from <repo>@<ref>` and
+      // `ci last-green --from <rev>` (#4031); the commands never run
+      // together, so one field carries all five.
       result.migrateFrom = args[++i];
     } else if (arg === "--kustomize") {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
@@ -243,6 +251,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") {
@@ -370,8 +381,23 @@ 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 === "--before-script") {
+      const line = args[++i];
+      if (line === undefined || line === "") throw new Error("--before-script needs a shell line: --before-script '<line>'");
+      (result.beforeScript ??= []).push(line);
     } else if (arg === "--resume") {
       // `chant approve <op> <gate> --resume` (#3683) takes no value; the
       // fan-out and pull-request apply take the attempt file they resume.
@@ -384,6 +410,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.json = true;
     } else if (arg === "--progress-json") {
       result.progressJson = true;
+    } else if (arg === "--events-json") {
+      result.eventsJson = true;
+    } else if (arg === "--follow") {
+      // `chant run events <run> --follow` (#4042): tail a run in progress on this host.
+      result.follow = true;
     } else if (arg === "--gated-exit") {
       // `chant run <op> --gated-exit <code>` (#2243) — remap only the gated
       // outcome's exit code. Parsed as a number here and range-checked in the
@@ -413,11 +444,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;
@@ -502,6 +533,10 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--app-key-secret") {
       result.ciAppKeySecret = args[++i];
       if (!result.ciAppKeySecret || result.ciAppKeySecret.startsWith("-")) throw new Error("--app-key-secret needs the secret holding the App's private key: --app-key-secret <NAME>");
+    } else if (arg === "--runner-key-secret") {
+      // `chant ci workflow --runner-key-secret <NAME>` (#4031): the secret holding the runner key the tick signs its tags with.
+      result.ciRunnerKeySecret = args[++i];
+      if (!result.ciRunnerKeySecret || result.ciRunnerKeySecret.startsWith("-")) throw new Error("--runner-key-secret needs the repository secret holding the runner key, such as CHANT_RUNNER_KEY: --runner-key-secret <NAME>");
     } else if (arg === "--verdict") {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
@@ -588,6 +623,17 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (result.digest !== undefined) (result.digests ??= []).push(result.digest);
     } else if (arg === "--release-plan") {
       result.releasePlanFile = args[++i];
+    } else if (arg === "--release") {
+      // `chant components promote --release <label|digest>` (#4026)
+      result.release = args[++i];
+      if (!result.release || result.release.startsWith("-")) throw new Error("--release needs a release's label or digest: --release <label|digest>");
+    } else if (arg === "--build") {
+      // `chant release cut --build <command>` (#4026)
+      result.buildCommand = args[++i];
+      if (!result.buildCommand) throw new Error("--build needs a shell command: --build '<command>'");
+    } else if (arg === "--artifacts") {
+      // `chant release compile --artifacts` (#4026, internal)
+      result.artifacts = true;
     } else if (arg === "--git-sha") {
       result.gitSha = args[++i];
     } else if (arg === "--run-id") {
@@ -712,10 +758,15 @@ export function parseArgs(args: string[]): ParsedArgs {
       // #2550 — `chant workspace upgrade` runs a template's code migrations
       // only when asked to.
       result.allowCode = true;
+    } else if (arg === "--allow-skip") {
+      // #4030 — `chant components promote` skips a step of the member's
+      // declared promotion order only when asked to.
+      result.allowSkip = true;
     } else if (arg === "--source") {
       // #2551 — `chant workspace upgrade --source <repo>[#<member>]`.
       result.source = args[++i];
-      if (!result.source || result.source.startsWith("-")) throw new Error("--source needs a template: --source <repo>[#<member>]");
+      // #4044: also `chant ci tick|list --source checks|runs`.
+      if (!result.source || result.source.startsWith("-")) throw new Error("--source needs a template: --source <repo>[#<member>] for workspace upgrade, or a source for ci tick and ci list: --source checks|runs");
     } else if (arg === "--tags") {
       // #2551 — `chant workspace adopt-lineage --tags <glob>`, also hash-index and versions.
       result.tags = args[++i];

package/src/cli/registry.ts

@@ -72,6 +72,16 @@ export interface ParsedArgs {
    * unchanged; omitted (undefined, not false) when the flag isn't passed.
    */
   progressJson?: boolean;
+  /**
+   * `--events-json` (#4041) — stream the run's events to stdout, one
+   * `run-event.schema.json` line each (`../../run-event.ts`), on `chant run
+   * <op>`, `chant run --components`, `components promote|rollback|redeploy`,
+   * `components fan-out` and `components pr-plan|pr-apply`. Refused beside
+   * `--progress-json`, which prints the older shapes to the same stdout.
+   */
+  eventsJson?: boolean;
+  /** `chant run events <run> --follow` (#4042) — stream the run's events as they happen, until `run-settle`. */
+  follow?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
   migrateFrom?: string;
@@ -137,6 +147,12 @@ export interface ParsedArgs {
   namespace?: string;
   /** `chant workspace upgrade --allow-code` (#2550) — run migrations whose body is the template's own code. */
   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. */
@@ -152,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`. */
@@ -160,15 +178,21 @@ export interface ParsedArgs {
   verbatim?: boolean;
   /** `chant import --skip-undeclarable` — import what can be declared and warn about the live objects that cannot, instead of failing */
   skipUndeclarable?: boolean;
-  /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */
+  /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands. Also `chant release cut --src <dir>` (#4046): the build root of a project with no components. */
   src?: string;
   /** `--env <name>` — active environment: sets CHANT_ENV so env-aware source
    * re-evaluates for that environment (`build` + `graph`), and drives policy. */
   env?: string;
   /** `chant emulator up --port <container-port>=<host-port>`, repeatable (#3673); a bare `<host-port>` when one emulator is selected. */
   port?: string[];
-  /** `chant emulator up --image <ref>` (#3952): the image to start, when one emulator is selected. */
+  /**
+   * `chant emulator up --image <ref>` (#3952): the image to start, when one
+   * emulator is selected. `chant build --components --generate --image <ref>`
+   * (#4002): the image every generated job runs in.
+   */
   image?: string;
+  /** `chant build --components --generate --before-script <line>`, repeatable (#4002): shell lines every generated job runs before its command. */
+  beforeScript?: string[];
   /** `chant emulator up --network <name>` (#3952): the Docker network each started container joins. */
   network?: string;
   /** `chant emulator up --setting <KEY>=<VALUE>`, repeatable (#3952): an emulator setting such as `FLOCI_<NAME>`, passed as `-e`. */
@@ -290,6 +314,12 @@ 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
@@ -386,7 +416,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;
@@ -434,6 +464,8 @@ export interface ParsedArgs {
   ciAppIdVar?: string;
   /** `chant ci workflow --app-key-secret <NAME>` (#3573): the secret holding that App's private key. */
   ciAppKeySecret?: string;
+  /** `chant ci workflow --runner-key-secret <NAME>` (#4031): the secret holding the runner key the tick signs its tags with. */
+  ciRunnerKeySecret?: string;
   /**
    * `chant workspace records review <id> --by <principal>` (#2670): the
    * reviewer, as the caller names them. Also `chant workspace records new
@@ -460,7 +492,7 @@ export interface ParsedArgs {
   prefix?: string;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */
   require?: string;
-  /** `chant workspace evidence sign --key` (a runner's Ed25519 PEM) and `signers sign --key` (an ssh private key) (#2553). */
+  /** `chant workspace evidence sign --key` (a runner's Ed25519 PEM) and `signers sign --key` (an ssh private key) (#2553). Also `chant ci tick --key` (#4031): the runner key the tick signs its tags with. */
   key?: string;
   /** `chant workspace evidence sign --check-id <id>` (#2553): the check the evidence is for. */
   checkId?: string;
@@ -541,6 +573,12 @@ 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 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;
+  /** `chant release compile --artifacts` (#4026, internal): build the artifacts of `--component` instead of compiling the environment. */
+  artifacts?: boolean;
   /** Every `--digest` value, in order (#2602). `chant components promote --digest <component>=<sha256:...>` is repeatable, one per component; the other commands read the single {@link digest}. */
   digests?: string[];
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
@@ -634,7 +672,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;