@intentius/chant 0.124.46 → 0.124.48

package/src/cli/main.ts

@@ -183,7 +183,14 @@ Commands:
                         the resources and snapshots each lexicon observed, Op
                         runs, gates, deploys, releases and cuts, loaded into
                         node:sqlite (schema v1, listed in chant_schema).
-                        --member <name> keeps members; --json prints rows
+                        --member <name> keeps members; --json prints rows.
+                        For a read contract, use chant ledger
+  ledger <table> [dir]  One ledger's rows from chant/lifecycle as a read
+                        contract (resources, snapshots, runs, gates, deploys,
+                        releases, cuts; the columns chant query loads).
+                        --where <field><op><value> (= != < <= > >= ~,
+                        repeatable), --since <time|7d>, --at <rev> of
+                        chant/lifecycle, --member <name>, --json
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -626,7 +633,7 @@ Workspace (level 1, #2524):
                         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]
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--where <field><op><value>]... [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
@@ -639,7 +646,9 @@ Workspace (level 1, #2524):
                         asset-drift or asset-missing. In the working tree,
                         each record says whether it is committed, modified
                         or new against HEAD, with the branch and base;
-                        --uncommitted lists only the modified and new ones
+                        --uncommitted lists only the modified and new ones;
+                        --where keeps the records a typed filter matches
+                        (id, path, state, valid, data.<key>, ...)
   workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
@@ -709,14 +718,16 @@ Workspace (level 1, #2524):
                         a url or a path pinned by hash) is appended to the
                         item's pins through records amend. Prints the
                         work-evidence document and never commits
-  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--json]
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--where <field><op><value>]... [--follow-squash] [--json]
                         The agent runs in the run ledger on chant/lifecycle, each
                         with its model, tokens, cost and the commits it made,
                         and totals per work item, decision and principal; a run
                         that reports no cost is listed as unpriced, never zero.
                         Read-only, never fetches; --follow-squash joins each
                         squash merge to its pull request's runs, fetching a
-                        missing refs/pull/<n>/head from origin
+                        missing refs/pull/<n>/head from origin; --where keeps
+                        the runs a typed filter matches (state, model,
+                        startedAt, cost.amount, ...) before the totals
   workspace runs start --from <file|->
                         Record that an agent run started: who it worked for,
                         its harness, model, work item and lease. Prints the run
@@ -888,7 +899,7 @@ Workspace (level 1, #2524):
   workspace admit <return id> [--note <text>] [--dry-run] [--json]
                         Admit the signers of a return in .chant/trust.json, so
                         its signed work reads as attested once merged
-  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]
+  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>] [--forge-repos <file>]
                         Fail on an unreadable lineage lock or an open manual
                         step, and, in a declared workspace, on a WSP check of
                         the declaration, member ledgers, pipelines or
@@ -900,7 +911,10 @@ Workspace (level 1, #2524):
                         resolves each declared member link against the live
                         graph of <env> (each chant member runs chant graph
                         --live, which reaches the account) and reports
-                        WSP141 and WSP142
+                        WSP141 and WSP142. --forge-repos reads a forge's
+                        repository list from a file and reports repos an
+                        org workspace lacks (WSP014) or names that the
+                        forge no longer has (WSP015)
   workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]
                         Map each path the diff changes to the current records
                         whose constrains cover it: change-uncovered when none
@@ -928,9 +942,12 @@ Workspace (level 1, #2524):
                         its own chant, one process per toolchain. -o <dir>
                         writes <dir>/<member>.json; --member narrows the run;
                         --dry-run prints which chant runs which project
-  workspace lint [dir] [--format stylish|json|sarif] [--member <name>]
+  workspace lint [dir] [--format stylish|json|sarif] [--member <name>] [--cross-root]
                         Lint every chant member and example project with its
-                        own chant; sarif writes one run per member
+                        own chant; sarif writes one run per member.
+                        --cross-root adds the disagreement lint (LNK001 and
+                        the lexicons' cross-root checks) over every member's
+                        graph, where declared links and the graphs disagree
   workspace audit [dir] [--json] [--member <name>]
                         Audit each chant member with its own .chant-audit.json;
                         every finding carries a member field
@@ -967,6 +984,29 @@ Workspace (level 1, #2524):
                         One decision's intent walk over every path: and member:
                         entry it constrains: the commits in its window, each
                         own, worked, within-other or unexplained, with counts
+  workspace run <member>/<op>... [--env <env>] [--gate <name>] [--on <lexicon>] [--dry-run] [--json]
+                        Run Ops that span members (#2554): each target's chant
+                        run <op> in the member's directory, under its own
+                        chant, producers before the members that link to them.
+                        OPS019 checks every target against the composed graph
+                        first. Member run records cite the workspace run,
+                        whose record goes under _members/_workspace/<env>/.
+                        Exits 3 when a step stops at a gate
+  workspace run --dependents-of <member> --op <op> [--env <env>] [--gate <name>] [--dry-run] [--json]
+                        Run <op> in every member that links to <member>,
+                        directly or not, nearest first; members without the
+                        Op are listed as skipped
+  workspace run approve <gate> [--plan <digest>] [--approver <principal>]
+                        Approve a workspace gate's pending fact. It stands in
+                        for a member gate only when it covers that member's
+                        plan and the member sets acceptWorkspaceGates at base
+  workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json]
+                        Record a release train: one cut release of every
+                        chant member (the newest, unless --pin picks one),
+                        under _members/_workspace/<env>/trains.jsonl. Refuses
+                        when a member has no release
+  workspace train list <env> [--json]
+                        The release trains recorded for <env>, oldest first
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
@@ -1040,7 +1080,9 @@ Component release ledger + status:
                             from the report pr-plan --no-status wrote
                             (--pr <n> --head <sha> --env <env> --forge
                             <kind>), in a job that runs none of the
-                            change's code (#4295)
+                            change's code (#4295); --open posts every
+                            open merge request's from a GitLab pipeline
+                            of the target branch (#4328)
   components pr-record     On merge (#4168): plan the same members again,
                             store the change set and write the merge record
                             _merges/<commit>.json; applies and refuses
@@ -1198,12 +1240,16 @@ Options:
                         JSON (lifecycle plan)
                         OR '--report markdown': emit a reviewer-facing markdown
                         render, holes and disruption included (lifecycle plan)
-  --from <name>         Source lexicon for migrate (default: github)
-  --to <name>           Target lexicon for migrate (default: gitlab)
-  --emit <fmt>          Migration output format: yaml (default) or ts
+  --from <name>         Source for migrate: a lexicon, or lexicon/dialect such
+                        as sql/postgres (default: github)
+  --to <name>           Target for migrate, same form, such as sql/clickhouse
+                        (default: gitlab)
+  --emit <fmt>          Migration output format: yaml (default), ts, or sql;
+                        sql/clickhouse defaults to ts
   --strict              Escalate needs-review/validation to errors (migrate);
                         exit nonzero on an unresolved identity (lifecycle whoami)
-  --validate            Run external validator (glci/glab) after migrate
+  --validate            Run external validator after migrate: glci/glab, or the
+                        ClickHouse emulator for sql/clickhouse
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
                         lexicon resources (list, describe, graph, build, run)
@@ -1498,6 +1544,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "search", handler: runSearch },
   // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
   { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query")).runQueryCommand(ctx) },
+  { name: "ledger", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/ledger")).runLedgerCommand(ctx) },
   // chant#2591 — `import --agents` and `audit` read chant.config statically
   // and never evaluate it (chant#2589 for audit, which audits code it must not run).
   { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1629,6 +1676,10 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace audit", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "audit") },
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
   // #4374 — chant search in every member, under its own chant, composed with workspace graph's ids: the search document.
+  // #2554 — Ops that span members, as <member>/<op> targets, each run under its member's own chant.
+  { name: "workspace run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/workspace-run")).runWorkspaceRun(ctx) },
+  // #2554 — a release train: one release of every chant member, pinned in the workspace ledger.
+  { name: "workspace train", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-train")).runWorkspaceTrain(ctx) },
   { name: "workspace search", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/search-cli")).runWorkspaceSearch(ctx) },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },

package/src/cli/parse-args.ts

@@ -47,6 +47,7 @@ const BOOLEAN_FLAGS = new Set([
   "--up",
   "--down",
   "--include-dependents",
+  "--cross-root",
   "--local",
   "--json",
   "--progress-json",
@@ -380,6 +381,19 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.head = args[++i];
     } else if (arg === "--include-dependents") {
       result.includeDependents = true;
+    } else if (arg === "--cross-root") {
+      // `chant workspace lint --cross-root` (#2549): the disagreement lint over every member's graph.
+      result.crossRoot = true;
+    } else if (arg === "--dependents-of") {
+      // `chant workspace run --dependents-of <member> --op <op>` (#2554).
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--dependents-of needs a member name: --dependents-of <member>");
+      result.dependentsOf = value;
+    } else if (arg === "--pin") {
+      // `chant workspace train <env> --pin <member>=<label|digest>` (#2554), repeatable.
+      const value = args[++i];
+      if (!value || value.startsWith("-") || !value.includes("=")) throw new Error("--pin needs a member and a release: --pin <member>=<label|digest>");
+      (result.pins ??= []).push(value);
     } else if (arg === "--from-affected") {
       result.fromAffected = args[++i];
     } else if (arg === "--gate") {
@@ -932,8 +946,8 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--expire") {
       result.expire = true;
     } else if (arg === "--role") {
-      // #2508 — a role the approver claims, which a gate's policy sees. A
-      // quorum reads roles from .chant/trust.json at base instead (#4290).
+      // #2508 — a role the approver claims, recorded on the approval. A quorum
+      // (#4290) and a gate policy (#4324) read roles from .chant/trust.json at base.
       // Repeatable, and a comma list works too.
       const value = args[++i] ?? "";
       result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
@@ -971,6 +985,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // #2537 — `chant build` and `chant lint` at a declared workspace root
       // run on the root project alone instead of refusing with WSP000.
       result.rootOnly = true;
+    } else if (arg === "--forge-repos") {
+      // #3168 — `chant workspace check --forge-repos <file>`: the forge's
+      // repository list, as a warden reads it, for an org workspace's checks.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--forge-repos needs a file: --forge-repos <repos.json>");
+      result.forgeRepos = value;
     } else if (arg === "--generated") {
       // #2641 — `chant workspace check --generated` runs each declared
       // generator and compares its output with the file in the tree.
@@ -991,6 +1011,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.url = args[++i];
     } else if (arg === "--op") {
       result.op = args[++i];
+    } else if (arg === "--where") {
+      // #4363 — a typed filter on a contract read; repeatable, every clause has to hold.
+      const value = args[++i];
+      if (value === undefined || value.startsWith("--")) throw new Error("--where needs a clause: --where <field><op><value>");
+      result.where = [...(result.where ?? []), value];
     } else if (arg === "--since") {
       result.since = args[++i];
     } else if (arg === "--limit") {

package/src/cli/registry.ts

@@ -83,7 +83,7 @@ export interface ParsedArgs {
   /** `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") */
+  /** `chant migrate --from <name>` (default "github"); `lexicon/dialect` for the sql lexicon */
   migrateFrom?: string;
   /** `chant import --kustomize <dir>` — render the kustomization, then import (#1548) */
   kustomize?: string;
@@ -103,9 +103,9 @@ export interface ParsedArgs {
   write?: boolean;
   /** `chant carve apply --write-source` — stamp the ownership marker into the emitted source */
   writeSource?: boolean;
-  /** `chant migrate --to <name>` (default "gitlab") */
+  /** `chant migrate --to <name>` (default "gitlab"); `lexicon/dialect` for the sql lexicon */
   migrateTo?: string;
-  /** `chant migrate --emit yaml|ts` */
+  /** `chant migrate --emit yaml|ts|sql` */
   emit?: string;
   /** Escalate needs-review diagnostics to errors (migrate command) */
   strict?: boolean;
@@ -263,6 +263,12 @@ export interface ParsedArgs {
   head?: string;
   /** `chant lifecycle affected --include-dependents` — add downstream consumers */
   includeDependents?: boolean;
+  /** `chant workspace run --dependents-of <member> --op <op>` (#2554): run the Op in every member that links to this one, directly or not. */
+  dependentsOf?: string;
+  /** `chant workspace lint --cross-root` (#2549): also run the disagreement lint and the lexicons' cross-root checks over every member's graph. */
+  crossRoot?: boolean;
+  /** `chant workspace train <env> --pin <member>=<label|digest>` (#2554), repeatable: the release a train pins for that member instead of its newest. */
+  pins?: string[];
   /**
    * `chant components fan-out --from-affected <file>` (#2420) — read the
    * stack-level change signal from the JSON `chant lifecycle affected --json`
@@ -640,6 +646,8 @@ export interface ParsedArgs {
    * generators run member code.
    */
   generated?: boolean;
+  /** `chant workspace check --forge-repos <file>` (#3168): the forge's repository list, checked against an org workspace's repo members (WSP014, WSP015). */
+  forgeRepos?: string;
   /**
    * `chant workspace build|lint|audit|graph --member <name>` (#2537): run only
    * the named members or example groups. Repeatable, and a comma list works too.
@@ -788,7 +796,7 @@ export interface ParsedArgs {
    * on a model-authored channel.
    */
   allowSameOrigin?: boolean;
-  /** `chant approve --role <name>` (#2508) — roles the approver claims, which a gate's policy sees. A quorum never counts them (#4290): its roles come from `.chant/trust.json` at base. Repeatable; a comma list also works. */
+  /** `chant approve --role <name>` (#2508) — roles the approver claims, recorded on the approval. Nothing trusts them: a quorum (#4290) and a gate policy (#4324) read roles from `.chant/trust.json` at base, for a sealed approval. Repeatable; a comma list also works. */
   roles?: string[];
   /** `chant approve --agent` (#2508) — record the approval as an agent's. An agent never counts toward a quorum; it passes a gate only through a policy permit in `enforce` mode. */
   agent?: boolean;
@@ -798,6 +806,8 @@ export interface ParsedArgs {
   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 workspace metrics --since <date>` (#4039) — the start of the window the metrics count. */
   since?: string;
+  /** `chant ledger`, `chant workspace records` and `chant workspace runs --where <field><op><value>` (#4363): typed filters, repeatable, all of which have to hold. */
+  where?: string[];
   /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
   limit?: number;
   /** `chant approve <op> <gate> --url <url>` (#2028) — the address this resolution happened at (the PR/MR that carried the change), recorded typed on the gate-resolution fact so a reader is not sniffing `--note` for something link-shaped. Defaults to the PR/MR the surrounding CI job is for, when there is one. Must be an absolute http/https URL. */

package/src/components/builders.ts

@@ -19,6 +19,8 @@ import type {
   ZipPackageInput,
   JvmBuildInput,
   GenerateSbomInput,
+  PublishImageInput,
+  PublishArtifactInput,
   SignInput,
   AttestProvenanceInput,
   VerifyInput,
@@ -64,6 +66,12 @@ export const vulnGate = step<VulnGateInput>("vuln-gate");
 // The cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`)
 // ship as builders from the aws lexicon, alongside their capabilities.
 export const waitClusterHealthy = step<WaitClusterHealthyInput>("wait-cluster-healthy");
+// ── publish (core owns the verb; each cloud lexicon contributes a registry login backend) ──
+export const publishImage = step<PublishImageInput>("publish-image");
+export const publishArtifact = step<PublishArtifactInput>("publish-artifact");
+/** Alias for {@link publishArtifact}. */
+export const publishAsset = publishArtifact;
+
 export const waitEndpoint = step<WaitEndpointInput>("wait-endpoint");
 export const healthGate = step<HealthGateInput>("health-gate");
 

package/src/components/capability-plugin-loader.ts

@@ -26,6 +26,8 @@ import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import type { CapabilityPlugin } from "./capability-plugin";
 import { isCapabilityPlugin } from "./capability-plugin";
 import { starterCapabilityPlugin } from "./starter-plugin";
+import { isRegistryBackendConsumer, type RegistryLoginBackend } from "./verbs/publish-image";
+import { isStorageBackendConsumer, type ArtifactStorageBackend } from "./verbs/publish-artifact";
 
 /** Thrown when a dynamically-imported capability package does not satisfy `CapabilityPlugin` — the "malformed capability package" case #559 asks doctor/validation to detect. */
 export class MalformedCapabilityPluginError extends Error {
@@ -165,9 +167,19 @@ export function registerCapabilityPlugins(
     }
   }
 
+  const backends: RegistryLoginBackend[] = [];
+  for (const plugin of plugins) backends.push(...(plugin.registryBackends?.() ?? []));
+  const storage: ArtifactStorageBackend[] = [];
+  for (const plugin of plugins) storage.push(...(plugin.storageBackends?.() ?? []));
+
   for (const plugin of plugins) {
     for (const capability of plugin.capabilities()) {
-      registry.register(capability);
+      // A capability that consumes registry login backends (`publish-image`)
+      // is re-bound to the backends of the plugins loaded for this registry.
+      let bound = capability;
+      if (isRegistryBackendConsumer(bound)) bound = bound.withRegistryBackends(backends) as typeof bound;
+      if (isStorageBackendConsumer(bound)) bound = bound.withStorageBackends(storage) as typeof bound;
+      registry.register(bound);
     }
   }
   return registry;

package/src/components/capability-plugin.ts

@@ -32,6 +32,8 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Capability } from "./capability";
+import type { RegistryLoginBackend } from "./verbs/publish-image";
+import type { ArtifactStorageBackend } from "./verbs/publish-artifact";
 
 /**
  * Manifest for a packaged capability plugin — the capability-side analogue
@@ -88,6 +90,20 @@ export interface CapabilityPlugin {
   /** Capability kinds grouped by family, informational — mirrors `STARTER_VERB_FAMILIES` (./registry.ts) shape for third-party plugins that want to publish the same grouping. */
   families?(): Record<string, readonly string[]>;
 
+  /**
+   * Registry login backends this plugin contributes to core's `publish-image`
+   * verb (aws: ECR, azure: ACR, gcp: Artifact Registry). Not capabilities, so
+   * several plugins may contribute without a duplicate-kind clash.
+   */
+  registryBackends?(): RegistryLoginBackend[];
+
+  /**
+   * Object-storage backends this plugin contributes to core's
+   * `publish-artifact` verb (aws: S3, azure: Blob, gcp: GCS). Like
+   * `registryBackends`, not capabilities, so several plugins may contribute.
+   */
+  storageBackends?(): ArtifactStorageBackend[];
+
   /** Optional initialization hook, called once after load (mirrors `LexiconPlugin.init`). */
   init?(): void | Promise<void>;
 }

package/src/components/pr-hooks.test.ts

@@ -8,6 +8,7 @@ import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSy
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { parseDeclaration, WorkspaceReadError } from "../workspace/declaration";
+import { PR_LOOP_HOOK_MOMENTS } from "../op/op-waves";
 import { prLoopHooksAt, prLoopHooksOf, runPrHooks } from "./pr-hooks";
 import type { OpWaveExec } from "../op/op-waves-run";
 
@@ -30,6 +31,12 @@ const declaration = (hooks: unknown, memberHooks?: unknown) => ({
 });
 
 describe("ci.hooks in the declaration (#4288)", () => {
+  test("accepts after.gate, and runs it after the plan-side moments (#4323)", () => {
+    const d = parseDeclaration(JSON.stringify(declaration({ after: { gate: [{ name: "report", command: ["report"] }] } }, { after: { gate: [{ name: "member-report", command: ["mr"] }] } })), "chant.workspace.json", "0.124.41");
+    expect(prLoopHooksOf(d, "infra")["after-gate"]!.map((h) => h.name)).toEqual(["report", "member-report"]);
+    expect(PR_LOOP_HOOK_MOMENTS).toContain("after-gate");
+  });
+
   test("parses at the top level and on a member; the member's run after the top level's", () => {
     const d = parseDeclaration(
       JSON.stringify(declaration({ before: { observe: [{ name: "init", command: ["init"] }] } }, { before: { observe: [{ name: "member-init", command: ["mi"], targets: ["db*"] }] } })),
@@ -43,7 +50,7 @@ describe("ci.hooks in the declaration (#4288)", () => {
 
   test("refuses hooks a pull-request job cannot run", () => {
     const read = (hooks: unknown) => () => parseDeclaration(JSON.stringify(declaration(hooks)), "chant.workspace.json", "0.124.41");
-    expect(read({ after: { gate: [{ command: ["x"] }] } })).toThrow(WorkspaceReadError);
+    expect(read({ before: { plan: [{ command: ["x"], onFailure: "bogus" }] } })).toThrow(WorkspaceReadError);
     expect(read({ before: { plan: [{ command: [] }] } })).toThrow(/must be a command as argv/);
     expect(read({ apply: { runBy: "apply" } })).toThrow(/runBy is for an Op waves spec/);
   });
@@ -84,7 +91,7 @@ describe("prLoopHooksAt (#4288)", () => {
 });
 
 describe("runPrHooks (#4288)", () => {
-  test("runs a moment for the selected components, writes the runs and plan files, and reports a failure", () => {
+  test("runs a moment for the selected components, writes the runs and plan files, and reports a failure", async () => {
     const cwd = tmp();
     const calls: Array<{ argv: string; env?: Record<string, string> }> = [];
     const exec: OpWaveExec = (argv, _dir, env) => {
@@ -95,7 +102,7 @@ describe("runPrHooks (#4288)", () => {
       base: "b".repeat(40),
       hooks: { "after-plan": [{ name: "check", command: ["check", "{target}", "{plan}"], perRun: true, targets: ["api", "web"] }] },
     };
-    const ran = runPrHooks(read, "after-plan", { op: "pr-7", env: "prod", stage: "plan", dir: ".chant/pr", cwd, exec, log: () => {} }, ["api", "db", "web"], {
+    const ran = await runPrHooks(read, "after-plan", { op: "pr-7", env: "prod", stage: "plan", dir: ".chant/pr", cwd, exec, log: () => {} }, ["api", "db", "web"], {
       members: [{ member: "api", component: "api", planDigest: "sha256:1", status: "planned", counts: { create: 1, update: 0, replace: 0, delete: 0 } }],
       plans: { api: { api: { file: "plan.bin" } } },
     });
@@ -110,9 +117,70 @@ describe("runPrHooks (#4288)", () => {
     expect(ran.failed).toBe("after-plan hook check (web) exited 1");
   });
 
-  test("a moment with no hooks runs nothing and writes nothing", () => {
+  test("a moment with no hooks runs nothing and writes nothing", async () => {
     const cwd = tmp();
-    const ran = runPrHooks({ base: "b", hooks: {} }, "before-apply", { op: "pr-7", env: "prod", stage: "apply", dir: ".chant/pr", cwd, log: () => {} }, ["api"]);
+    const ran = await runPrHooks({ base: "b", hooks: {} }, "before-apply", { op: "pr-7", env: "prod", stage: "apply", dir: ".chant/pr", cwd, log: () => {} }, ["api"]);
     expect(ran).toEqual({ outcomes: [], holds: [] });
   });
+
+  const holdBody = { gate: "db-migrate", digest: "sha256:m1", op: "other-op" };
+  /** An exec for a hook that holds on db-migrate until CHANT_HOLD_APPROVED is set. */
+  const holdingExec = (cwd: string, calls: Array<Record<string, string> | undefined>): OpWaveExec => (argv, _dir, env) => {
+    calls.push(env);
+    if (env?.CHANT_HOLD_APPROVED) return 0;
+    writeFileSync(join(cwd, env!.CHANT_HOLD!), JSON.stringify(holdBody));
+    return argv[0] === "hold" ? 1 : 0;
+  };
+  const gateHooks = { "after-gate": [{ name: "migrate", command: ["hold"], onFailure: "approve" as const }] };
+  const place = (cwd: string, exec: OpWaveExec) => ({ op: "pr-7", env: "prod", stage: "apply" as const, dir: ".chant/pr", cwd, exec, log: () => {} });
+
+  test("an after-gate hook gets the gate's decision in its environment (#4323)", async () => {
+    const cwd = tmp();
+    const calls: Array<Record<string, string> | undefined> = [];
+    const exec: OpWaveExec = (_argv, _dir, env) => (calls.push(env), 0);
+    const read = { base: "b", hooks: { "after-gate": [{ name: "report", command: ["report"] }] } };
+    const decision = { CHANT_GATE_STATUS: "approved", CHANT_GATE_OP: "pr-7", CHANT_GATE: "pr-apply", CHANT_GATE_DIGEST: "sha256:p" };
+    const ran = await runPrHooks(read, "after-gate", place(cwd, exec), ["api"], undefined, { env: decision });
+    expect(calls[0]).toMatchObject({ CHANT_HOOK: "after-gate", ...decision });
+    expect(ran.outcomes).toEqual([{ moment: "after-gate", name: "report", exit: 0, outcome: "passed" }]);
+  });
+
+  test("a hold on another gate clears once that gate is approved: the hook runs again with CHANT_HOLD_APPROVED (#4323)", async () => {
+    const cwd = tmp();
+    const calls: Array<Record<string, string> | undefined> = [];
+    let approved = false;
+    const asked: string[] = [];
+    const settle = async (hold: { request: { gate: string; digest: string; op?: string } }) => {
+      asked.push(`${hold.request.op} / ${hold.request.gate} @ ${hold.request.digest}`);
+      return approved ? { status: "approved" as const, approvedBy: "alice", approvedAt: "2026-10-23T00:00:00Z" } : { status: "waiting" as const };
+    };
+    const read = { base: "b", hooks: gateHooks };
+    const first = await runPrHooks(read, "after-gate", place(cwd, holdingExec(cwd, calls)), ["api"], undefined, { settle });
+    expect(first.failed).toMatch(/^after-gate hook migrate waits on other-op \/ db-migrate, which nobody approved at sha256:m1\. Approve: /);
+    expect(first.holds).toEqual([]);
+
+    approved = true;
+    calls.length = 0;
+    const second = await runPrHooks(read, "after-gate", place(cwd, holdingExec(cwd, calls)), ["api"], undefined, { settle });
+    expect(second.failed).toBeUndefined();
+    expect(second.holds).toEqual([]);
+    expect(asked).toEqual(["other-op / db-migrate @ sha256:m1", "other-op / db-migrate @ sha256:m1"]);
+    expect(JSON.parse(calls[1]!.CHANT_HOLD_APPROVED!)).toEqual({ op: "other-op", gate: "db-migrate", digest: "sha256:m1", approvedBy: "alice", approvedAt: "2026-10-23T00:00:00Z" });
+    expect(second.outcomes.map((o) => o.outcome)).toEqual(["held", "passed"]);
+  });
+
+  test("a re-run that holds on a gate already approved fails the stage (#4323)", async () => {
+    const cwd = tmp();
+    const exec: OpWaveExec = (_argv, _dir, env) => (writeFileSync(join(cwd, env!.CHANT_HOLD!), JSON.stringify(holdBody)), 1);
+    const settle = async () => ({ status: "approved" as const, approvedBy: "alice", approvedAt: "t" });
+    const ran = await runPrHooks({ base: "b", hooks: gateHooks }, "after-gate", place(cwd, exec), ["api"], undefined, { settle });
+    expect(ran.failed).toMatch(/holds again on other-op \/ db-migrate at sha256:m1, which is already approved/);
+  });
+
+  test("without a settler a hold on another gate stays a plain hold", async () => {
+    const cwd = tmp();
+    const ran = await runPrHooks({ base: "b", hooks: gateHooks }, "after-gate", place(cwd, holdingExec(cwd, [])), ["api"]);
+    expect(ran.holds).toEqual(["after-gate hook migrate (on other-op / db-migrate)"]);
+    expect(ran.failed).toBeUndefined();
+  });
 });