@intentius/chant 0.124.27 → 0.124.29

package/dist/cli/main.js

@@ -104,6 +104,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.js");
 const runOpWaveCommand = lazyHandler(runWaveHandlers, (m) => m.runOpWaveCommand);
 const operatorHandlers = () => import("./handlers/operator.js");
@@ -214,22 +215,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
@@ -238,6 +299,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)
@@ -247,11 +312,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;
@@ -280,12 +352,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
@@ -374,6 +453,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
@@ -651,7 +737,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
@@ -682,7 +774,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.
@@ -721,6 +813,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
@@ -759,7 +858,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>]);
@@ -774,13 +877,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:...>];
@@ -921,7 +1029,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.
@@ -933,7 +1041,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.
@@ -1178,10 +1286,22 @@ export const commandRegistry = [
     { 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.js")).runCiLastGreen(ctx) },
+    { name: "ci list", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiList(ctx) },
     { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiTick(ctx) },
     { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).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.js")).runReleaseCut(ctx) },
+    // #4027: publish a cut release, to the targets #4047 declares.
+    { name: "release publish", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleasePublish(ctx) },
+    // #4049: check a release's signature offline.
+    { name: "release verify", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseVerify(ctx) },
+    { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseList(ctx) },
+    { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseExport(ctx) },
+    { name: "release compile", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).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.js")).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.js")).runChangeSetShow(ctx) },
     { name: "init", handler: runInit, runsNoConfig: true },
     { name: "init lexicon", handler: runInitLexicon },
     { name: "update", handler: runUpdate },
@@ -1201,6 +1321,7 @@ export const commandRegistry = [
     { 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.js")).runResumeCommand(ctx) },
@@ -1227,6 +1348,8 @@ export const commandRegistry = [
     { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli.js")).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.js")).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.js")).runWorkspaceMetrics(ctx) },
     { name: "workspace status", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/status.js")).runWorkspaceStatus(ctx) },
     { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli.js")).runWorkspaceLineage(ctx) },
     { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli.js")).runWorkspaceUpgrade(ctx) },
@@ -1276,6 +1399,8 @@ export const commandRegistry = [
     { 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.js")).runLifecycleGc(ctx) },
     // Plan scenarios (#1292) — fully offline, no plugin network calls, but
     // requiresPlugins:true so the build step has serializers to partition
     // against, same as every other build-then-something verb.
@@ -1307,6 +1432,7 @@ export const commandRegistry = [
     { name: "dev", handler: runDevUnknown },
     { name: "serve", handler: runServeUnknown },
     { name: "components", handler: runComponentsUnknown },
+    { name: "release", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseUnknown(ctx) },
     { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli.js")).runWorkspaceUnknown(ctx) },
 ];
 /**

package/dist/cli/mcp/workspace-tools.js

@@ -100,7 +100,7 @@ export const workspaceReadTools = [
     },
     {
         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.",
+        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. 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/dist/cli/parse-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../src/cli/parse-args.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0E7C;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAitBpD"}
+{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../src/cli/parse-args.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiF7C;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA6vBpD"}

package/dist/cli/parse-args.js

@@ -46,6 +46,8 @@ const BOOLEAN_FLAGS = new Set([
     "--local",
     "--json",
     "--progress-json",
+    "--events-json",
+    "--follow",
     "--update-snapshot",
     "--update-baseline",
     "--run-examples",
@@ -69,11 +71,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",
 ]);
 /**
  * Parse command line arguments
@@ -205,8 +212,9 @@ export function parseArgs(args) {
         }
         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") {
@@ -279,6 +287,10 @@ export function parseArgs(args) {
         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;
         }
@@ -470,9 +482,30 @@ export function parseArgs(args) {
         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 ?? (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.
@@ -491,6 +524,13 @@ export function parseArgs(args) {
         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
@@ -529,14 +569,14 @@ export function parseArgs(args) {
             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>");
+                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)
@@ -661,6 +701,12 @@ export function parseArgs(args) {
             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];
@@ -785,6 +831,22 @@ export function parseArgs(args) {
         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];
         }
@@ -952,11 +1014,17 @@ export function parseArgs(args) {
             // 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];
+            // #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>]");
+                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.

package/dist/cli/registry.d.ts

@@ -71,6 +71,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;
@@ -136,6 +146,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. */
@@ -151,6 +167,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`. */
@@ -159,15 +177,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`. */
@@ -289,6 +313,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
@@ -385,7 +415,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;
@@ -433,6 +463,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
@@ -459,7 +491,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;
@@ -539,6 +571,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. */
@@ -632,7 +670,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;