@intentius/chant 0.124.46 → 0.124.48

package/src/cli/handlers/migrate.ts

@@ -1,4 +1,4 @@
-import { migrateCommand, printMigrateResult } from "../commands/migrate";
+import { lexiconOfSide, migrateCommand, printMigrateResult } from "../commands/migrate";
 import { formatError } from "../format";
 import { loadPlugins } from "../plugins";
 import type { CommandContext } from "../registry";
@@ -16,30 +16,39 @@ export async function runMigrate(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // A side is a lexicon, or a lexicon and a dialect: `sql/clickhouse` (#4399).
+  const toName = args.migrateTo ?? "gitlab";
+  const fromName = args.migrateFrom ?? "github";
+
+  // The sql pair writes declarations, so ts is its default; yaml is the gitlab pair's.
+  const emit = (args.emit as "yaml" | "ts" | "sql" | undefined) ?? (lexiconOfSide(toName) === "sql" ? "ts" : "yaml");
+  if (emit !== "yaml" && emit !== "ts" && emit !== "sql") {
+    console.error(formatError({ message: `Invalid --emit value: ${emit}. Expected 'yaml', 'ts' or 'sql'.` }));
+    return 1;
+  }
+
+  if (emit === "sql" && lexiconOfSide(toName) !== "sql") {
+    console.error(formatError({ message: `--emit sql writes DDL, and ${toName} is not a sql target`, hint: "use --emit yaml or --emit ts" }));
+    return 1;
+  }
+
   // migrate does not require a chant project context. Load the target
   // lexicon directly by name.
-  const toName = args.migrateTo ?? "gitlab";
   let plugins;
   try {
-    plugins = await loadPlugins([toName]);
+    plugins = await loadPlugins([lexiconOfSide(toName)]);
   } catch (err) {
     console.error(formatError({
       message: `Cannot load target lexicon "${toName}": ${err instanceof Error ? err.message : String(err)}`,
-      hint: `Install @intentius/chant-lexicon-${toName} or pass --to <other-lexicon>`,
+      hint: `Install @intentius/chant-lexicon-${lexiconOfSide(toName)} or pass --to <other-lexicon>`,
     }));
     return 1;
   }
 
-  const emit = (args.emit as "yaml" | "ts" | undefined) ?? "yaml";
-  if (emit !== "yaml" && emit !== "ts") {
-    console.error(formatError({ message: `Invalid --emit value: ${emit}. Expected 'yaml' or 'ts'.` }));
-    return 1;
-  }
-
   const result = await migrateCommand({
     sourceFile: args.path,
-    from: args.migrateFrom ?? "github",
-    to: args.migrateTo ?? "gitlab",
+    from: fromName,
+    to: toName,
     emit,
     strict: args.strict ?? false,
     validate: args.validate ?? false,

package/src/cli/handlers/misc.ts

@@ -384,10 +384,19 @@ export async function runImport(ctx: CommandContext): Promise<number> {
     force: ctx.args.force,
     lexicon: ctx.args.lexicon,
     parserOptions: ctx.args.parserOption,
+    validate: ctx.args.validate,
   });
 
   printImportResult(result);
-  return result.success ? 0 : 1;
+  if (!result.success) return 1;
+  // The review report and `--strict` (#4398): the parser's diagnostics, as `chant migrate` reports its own.
+  if (ctx.args.reportFile) {
+    const { writeImportReport } = await import("../commands/import-report");
+    const failed = writeImportReport(ctx.args.reportFile, resolve(ctx.args.path), result.diagnostics ?? [], CHANT_VERSION);
+    if (failed) console.error(formatWarning({ message: failed }));
+  }
+  const { importExitCode } = await import("../commands/import-report");
+  return importExitCode(result.diagnostics, ctx.args.strict === true);
 }
 
 export async function runUpdate(ctx: CommandContext): Promise<number> {

package/src/cli/handlers/pr-env.ts

@@ -241,10 +241,10 @@ function componentsPrEnvAdapter(p: Prepared, run: { planAll: typeof import("./pr
     },
     async apply(target) {
       const planned = set!;
-      const hookStop = run.runStageHook(p, "before-apply", p.plan.order, planned);
+      const hookStop = await run.runStageHook(p, "before-apply", p.plan.order, planned);
       if (hookStop) return { status: "stopped", rows: rows(target, () => "planned"), message: hookStop };
       const applied = await applyPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: target.env, set: planned, gate: PR_ENV_GATE });
-      const afterHook = run.runStageHook(p, "after-apply", p.plan.order, planned, "the environment stands as applied");
+      const afterHook = await run.runStageHook(p, "after-apply", p.plan.order, planned, "the environment stands as applied");
       const status = (component: string) => applied.members.find((m) => m.component === component)?.status ?? "planned";
       return {
         status: applied.status === "applied" ? "applied" : applied.status === "waiting" ? "waiting" : "failed",

package/src/cli/handlers/pr.ts

@@ -65,8 +65,8 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { resolveCommit, resolveMergeBase } from "../../components/changed-files";
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
@@ -90,7 +90,8 @@ import { blockedMembers, blockedWords, settleEarlierWaves, type WaveMemberOutcom
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt, type PrApplyRecord } from "../../components/fan-out-record";
 import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs";
 import { samePlanDigest } from "../../lifecycle/plan-digest";
-import { gateIsSealed, gitGateLedgerPort, type GateCheck } from "../../op/gate";
+import { evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "../../op/gate";
+import type { OtherGateHold } from "../../op/stage-hooks";
 import { emitGateStep, gateEventsOf, GATE_PHASE, type RunEventSink, type RunEventStream } from "../../run-event-stream";
 import type { RunEventBody, RunEventComponentSettle, RunEventSettleStatus } from "../../run-event";
 import { openCliRunEvents, refusesEventsWithJson } from "../run-events";
@@ -130,8 +131,8 @@ import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out
 import { failedRunExitCode, type DriverComponent } from "../../components/driver";
 import type { CapabilityRegistry } from "../../components/capability";
 import type { ComponentEnvironmentDeclaration } from "../../components/component";
-import { prLoopHooksAt, runPrHooks, type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks";
-import { decidePrPolicyOverride, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrLoopPolicy } from "../../components/pr-policy";
+import { prLoopHooksAt, runPrHooks, type PrHoldSettled, type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks";
+import { decidePrPolicyOverride, policyReviewOf, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrLoopPolicy } from "../../components/pr-policy";
 import type { OpWaveHookMoment } from "../../op/op-waves";
 import type { PrHookOutcome } from "../../pr-loop";
 
@@ -320,9 +321,19 @@ export function placeHooks(ctx: CommandContext, p: Prepared, stage: PrHookPlace[
  * when no hook failed. A hold is logged: the pull request's gate already
  * waits for a person's approval of the digest.
  */
-export function runStageHook(p: Prepared, moment: OpWaveHookMoment, components: readonly string[], planned?: PrPlanSet, what = "nothing was applied"): string | undefined {
+export async function runStageHook(
+  p: Prepared,
+  moment: OpWaveHookMoment,
+  components: readonly string[],
+  planned?: PrPlanSet,
+  what = "nothing was applied",
+  env?: Record<string, string>,
+): Promise<string | undefined> {
   if (!p.hookPlace || components.length === 0) return undefined;
-  const ran = runPrHooks(p.hooks, moment, p.hookPlace, components, planned ? { members: planned.members, plans: planned.plans } : undefined);
+  const ran = await runPrHooks(p.hooks, moment, p.hookPlace, components, planned ? { members: planned.members, plans: planned.plans } : undefined, {
+    ...(env ? { env } : {}),
+    settle: (hold) => settleHeldGate(p, hold),
+  });
   p.hookOutcomes.push(...ran.outcomes);
   for (const hold of ran.holds) console.error(formatInfo(`${hold} held, and the pull request's gate asks for an approval of the digest either way`));
   if (!ran.failed) return undefined;
@@ -330,6 +341,46 @@ export function runStageHook(p: Prepared, moment: OpWaveHookMoment, components:
   return p.hookFailed;
 }
 
+/**
+ * Settle a hook's hold on another gate (#4323), the way an Op waves job does:
+ * an approval of that gate and digest under its `identity.gates` rule read at
+ * base, else a pending fact for it. The plan stage writes nothing, so there
+ * it only reads.
+ */
+async function settleHeldGate(p: Prepared, hold: OtherGateHold): Promise<PrHoldSettled> {
+  const real = gitGateLedgerPort();
+  const ledger = p.hookPlace?.stage === "plan" ? readOnlyLedger(real) : real;
+  const port: GateLedgerPort = ledger.approvalRule ? { ...ledger, approvalRule: (g: string) => ledger.approvalRule!(g, { base: p.base }) } : ledger;
+  const op = hold.request.op ?? p.hookPlace?.op ?? "";
+  const check = await evaluateGate(port, {
+    op,
+    gate: hold.request.gate,
+    planDigest: hold.request.digest,
+    description: hold.request.description ?? `${hold.label} holds the pull request on it`,
+    fields: { ...hold.request.pending, approvalMode: "ledger", heldBy: { hook: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}) } },
+  });
+  if (check.satisfied) return { status: "approved", approvedBy: check.resolution.resolvedBy, approvedAt: check.resolution.timestamp };
+  for (const { resolution: r, reason } of check.refused ?? []) console.error(formatInfo(`${op} / ${hold.request.gate}: the approval by ${r.resolvedBy} at ${r.timestamp} does not count: ${reason}`));
+  return { status: "waiting" };
+}
+
+/**
+ * Run the `after-gate` hooks once the pull request's gate decided (#4323),
+ * whatever it decided. `CHANT_GATE_STATUS` is `approved`, or `waiting` when no
+ * approval of the digest stands; `CHANT_GATE_OP`, `CHANT_GATE` and
+ * `CHANT_GATE_DIGEST` name the gate. Returns the failure message, as
+ * {@link runStageHook} does; the caller ignores it when the gate did not let
+ * the apply through, since the stage ends there anyway.
+ */
+export function runGateHook(p: Prepared, at: { op: string; digest: string; satisfied: boolean }, components: readonly string[]): Promise<string | undefined> {
+  return runStageHook(p, "after-gate", components, undefined, "nothing was applied", {
+    CHANT_GATE_STATUS: at.satisfied ? "approved" : "waiting",
+    CHANT_GATE_OP: at.op,
+    CHANT_GATE: p.gate,
+    CHANT_GATE_DIGEST: at.digest,
+  });
+}
+
 const EMPTY_SET = (): PrPlanSet => ({ doc: composeChangeSet([]), members: [], plans: {}, outputs: {}, failed: true });
 
 /**
@@ -338,11 +389,11 @@ const EMPTY_SET = (): PrPlanSet => ({ doc: composeChangeSet([]), members: [], pl
  * set, so the stage reports `plan-failed` and nothing applies.
  */
 async function hookedPlan(p: Prepared, components: readonly string[], plan: () => Promise<PrPlanSet>): Promise<PrPlanSet> {
-  if (runStageHook(p, "before-observe", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
-  if (runStageHook(p, "before-plan", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
+  if (await runStageHook(p, "before-observe", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
+  if (await runStageHook(p, "before-plan", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
   const set = await plan();
   if (set.failed) return set;
-  if (runStageHook(p, "after-plan", components, set)) return { ...set, failed: true };
+  if (await runStageHook(p, "after-plan", components, set)) return { ...set, failed: true };
   return set;
 }
 
@@ -570,7 +621,9 @@ interface PolicyJudged {
  * read only at the plan stage, and recorded for an override at the apply.
  */
 async function judgePolicy(p: Prepared, at: { stage: "plan" | "apply"; op: string; pr: number | null; set: PrPlanSet }): Promise<PolicyJudged> {
-  const verdict = runPrPolicy(p.policy, { version: 1, stage: at.stage, op: at.op, gate: p.gate, env: p.env, pr: at.pr, base: p.base, head: p.head, changeSet: at.set.doc });
+  // The review is read only when a policy will run: a workspace with no policy makes no forge call for it.
+  const review = p.policy.settings ? await policyReviewOf(p.forge, at.pr) : undefined;
+  const verdict = runPrPolicy(p.policy, { version: 1, stage: at.stage, op: at.op, gate: p.gate, env: p.env, pr: at.pr, base: p.base, head: p.head, changeSet: at.set.doc, ...(review ? { review } : {}) });
   if (!verdict) return { held: false };
   const report = prPolicyReport(verdict, p.policy.base);
   p.policyReport = report;
@@ -712,27 +765,8 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
  * `pr-post` asks instead, reading the Ops at the target branch's commit.
  */
 async function overdueOps(forge: PrForge | undefined, member: string | undefined): Promise<PrOverdue[]> {
-  if (!forge?.scheduledRuns) return [];
-  try {
-    const { discoverOps } = await import("../../op/discover");
-    const { scheduledWatches, checkOverdueOps } = await import("../../op/schedule-overdue");
-    const discovered = await discoverOps({ cwd: resolve(".") });
-    const watches = scheduledWatches([...discovered.ops.values()].map((d) => d.config));
-    if (watches.length === 0) return [];
-    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
-    if (top.status !== 0) return [];
-    return await checkOverdueOps({
-      watches,
-      forge,
-      repoRoot: top.stdout.trim(),
-      ...(member ? { member } : {}),
-      now: new Date(),
-      log: (line) => console.error(formatWarning({ message: line })),
-    });
-  } catch (err) {
-    console.error(formatWarning({ message: `could not check the scheduled Ops, so none is reported overdue: ${err instanceof Error ? err.message : String(err)}` }));
-    return [];
-  }
+  const { overdueOpsAt } = await import("../../op/schedule-overdue");
+  return overdueOpsAt({ forge, cwd: resolve("."), ...(member ? { member } : {}), log: (line) => console.error(formatWarning({ message: line })) });
 }
 
 /** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
@@ -881,6 +915,9 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
     if (judged.stop) return stop(prReport({ ...base, approval: { status: "pending" }, status: "refused", refusal: judged.stop.refusal, message: judged.stop.message }), judged.stop.code);
     const decided = await decideApplyGate(p, { op, pr, set, events, held: judged.held, ...(green ? { green } : {}) });
     approval = decided.approval;
+    // #4323: the after-gate hooks hear the decision, a refusal too; only a failure that would have applied changes the outcome.
+    const afterGate = await runGateHook(p, { op, digest: set.doc.digest, satisfied: decided.satisfied }, p.plan.order);
+    if (afterGate && decided.satisfied) return stop(prReport({ ...base, approval, status: "failed", message: afterGate }), 1);
     if (!decided.satisfied) return stop(prReport({ ...base, approval, status: "refused", refusal: decided.refusal, message: decided.message }), GATED_EXIT_CODE);
     via = decided.via;
   }
@@ -935,7 +972,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
 
   // #4288: the before-apply hooks, once the gate and the review let the apply through.
   const toApply = (resumed?.plan ?? p.plan).order.filter((name) => !completedSoFar.has(name));
-  const beforeFailed = runStageHook(p, "before-apply", toApply);
+  const beforeFailed = await runStageHook(p, "before-apply", toApply);
   if (beforeFailed) return stop(prReport({ ...base, approval, status: "failed", message: beforeFailed }), 1);
 
   // #3999: a round planned after an upstream applied waits on a gate of its
@@ -994,7 +1031,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
   });
   recordAttempt();
   // #4288: the after-apply hooks, for the components that applied.
-  const afterFailed = runStageHook(p, "after-apply", toApply.filter((name) => applied.run.completed.includes(name)), undefined, "the apply counts as failed though its components applied");
+  const afterFailed = await runStageHook(p, "after-apply", toApply.filter((name) => applied.run.completed.includes(name)), undefined, "the apply counts as failed though its components applied");
   await recordAutoReleasesForRun(applied.run.results, p.env, release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), release.runOrigin, undefined, undefined, prAppliedDigests(p, applied.members));
   const report = prReport({
     ...base,
@@ -1787,6 +1824,9 @@ async function prApplyWaves(
     if (judged.stop) return stop(report({ status: "refused", refusal: judged.stop.refusal, message: judged.stop.message }), judged.stop.code);
     const decided = await decideApplyGate(p, { op, pr, set, events, held: judged.held, ...(green ? { green } : {}) });
     approval = decided.approval;
+    // #4323: the after-gate hooks hear the decision, a refusal too.
+    const afterGate = await runGateHook(p, { op, digest: set.doc.digest, satisfied: decided.satisfied }, p.plan.order);
+    if (afterGate && decided.satisfied) return stop(report({ status: "failed", message: afterGate }), 1);
     if (!decided.satisfied) return stop(report({ status: "refused", refusal: decided.refusal, message: decided.message }), GATED_EXIT_CODE);
     via = decided.via;
     planned = set;
@@ -1944,7 +1984,7 @@ async function prApplyWaves(
     }
 
     // #4288: the wave's apply-side hooks, around its apply.
-    const waveBefore = runStageHook(p, "before-apply", wavePlan.order, undefined, `nothing in wave ${k} was applied`);
+    const waveBefore = await runStageHook(p, "before-apply", wavePlan.order, undefined, `nothing in wave ${k} was applied`);
     if (waveBefore) {
       setWave({ ...entry, status: "failed" });
       return stop(report({ status: "failed", message: waveBefore }), 1);
@@ -1979,7 +2019,7 @@ async function prApplyWaves(
       const outputs = applied.run.componentOutputs[name];
       if (outputs) outputsSoFar[name] = outputs;
     }
-    const waveAfter = runStageHook(p, "after-apply", wavePlan.order.filter((name) => applied.run.completed.includes(name)), undefined, `wave ${k} counts as failed though its components applied`);
+    const waveAfter = await runStageHook(p, "after-apply", wavePlan.order.filter((name) => applied.run.completed.includes(name)), undefined, `wave ${k} counts as failed though its components applied`);
     setWave({ ...entry, status: applied.status === "applied" && !waveAfter ? "applied" : "failed" });
     await recordAutoReleasesForRun(applied.run.results, p.env, at.release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), at.release.runOrigin, undefined, undefined, prAppliedDigests(p, applied.members));
     if (applied.status !== "applied") {
@@ -2023,6 +2063,7 @@ function writeWaveChangeSet(ctx: CommandContext, wave: number, doc: PrPlanSet["d
 
 /**
  * chant components pr-post --pr <n> --head <sha> --env <env> --forge <kind> [--member <name>] [--output <dir>] [--result <result>] (#4295)
+ * chant components pr-post --open --env <env> --forge gitlab [--branch <branch>] [--member <name>] [--output <dir>] (#4328)
  *
  * Post the plan note and the `chant/plan` status from the report a plan job
  * wrote with `pr-plan --no-status`, in a job that runs none of the change's
@@ -2033,6 +2074,7 @@ function writeWaveChangeSet(ctx: CommandContext, wave: number, doc: PrPlanSet["d
  */
 export async function runComponentsPrPost(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
+  if (args.open) return runComponentsPrPostOpen(ctx);
   if (args.pr === undefined) return fail("pr-post needs the pull or merge request: --pr <n>");
   if (!args.head || !/^[0-9a-f]{40}$/.test(args.head)) return fail("pr-post needs the full commit the plan job checked out: --head <sha>");
   if (!args.env) return fail("pr-post needs the environment the plan was for: --env <env>");
@@ -2062,3 +2104,63 @@ export async function runComponentsPrPost(ctx: CommandContext): Promise<number>
   console.error(formatInfo(`pr-post: ${prStatusContext("plan", member)} ${posted.state}: ${posted.description}${posted.noted ? "; note posted" : ""}`));
   return 0;
 }
+
+/**
+ * `pr-post --open` (#4328): in a pipeline of the target branch on GitLab,
+ * post the plan note and status of every open merge request into it whose
+ * plan job settled, reading each report from the plan job's artifacts
+ * (`postOpenPlanReports`, ../../pr-post.ts). The branch is `--branch`, else
+ * the pipeline's own (`CI_COMMIT_BRANCH`). The plan job is `plan`, or
+ * `<member>-plan` with `--member`, as the gitlab lexicon names it, and the
+ * artifact path is `--output` from the repository root. It exits 0 once it
+ * has posted, as `pr-post` does.
+ */
+async function runComponentsPrPostOpen(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.pr !== undefined || args.head) return fail("pr-post --open finds each merge request and its head itself, so it takes no --pr or --head");
+  if (!args.env) return fail("pr-post needs the environment the plan was for: --env <env>");
+  if (args.forge !== "gitlab") return fail("pr-post --open is for a GitLab pipeline of the target branch: --forge gitlab");
+  if (args.members && args.members.length > 1) return fail(`pr-post takes one --member, not ${args.members.join(", ")}`);
+  const branch = args.branch ?? process.env.CI_COMMIT_BRANCH;
+  if (!branch) return fail("pr-post --open posts for the merge requests into a branch: run it in a branch pipeline, or pass --branch <branch>");
+  let forge: PrForge;
+  try {
+    forge = forgeFromEnv("gitlab");
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
+  if (top.status !== 0) return fail("pr-post --open reads the plan report's path from the repository root, and this directory is not in a git repository");
+  const member = args.members?.[0];
+  const artifactDir = relative(realpathSync(top.stdout.trim()), resolve(args.output ?? PR_REPORT_DIR)).split(sep).join("/");
+  const { postOpenPlanReports } = await import("../../pr-post");
+  const { gitlabPlanJobName } = await import("../../components/pr-pipeline");
+  let done: Awaited<ReturnType<typeof postOpenPlanReports>>;
+  try {
+    done = await postOpenPlanReports({
+      forge,
+      branch,
+      job: gitlabPlanJobName(member),
+      artifactDir,
+      env: args.env,
+      ...(member ? { member } : {}),
+      // #4289: the Ops at the commit this pipeline checked out, the target branch's.
+      overdue: () => overdueOps(forge, member),
+    });
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  for (const message of done.warnings) console.error(formatWarning({ message }));
+  for (const p of done.posts) {
+    if (p.skipped) {
+      console.error(formatInfo(`pr-post: !${p.pr}: ${p.skipped}`));
+      continue;
+    }
+    const posted = p.posted!;
+    for (const message of posted.warnings) console.error(formatWarning({ message: `!${p.pr}: ${message}` }));
+    if (posted.refused) console.error(formatWarning({ message: `!${p.pr}: the plan report was not used: ${posted.refused}` }));
+    console.error(formatInfo(`pr-post: !${p.pr} ${prStatusContext("plan", member)} ${posted.state}: ${posted.description}${posted.noted ? "; note posted" : ""}`));
+  }
+  if (done.posts.length === 0) console.error(formatInfo(`pr-post: no open merge request into ${branch} has a ${gitlabPlanJobName(member)} job`));
+  return 0;
+}

package/src/cli/handlers/query.ts

@@ -18,11 +18,23 @@ import { findWorkspaceRoot } from "../../project-root";
 
 const USAGE = 'chant query "<sql>" [dir] [--member <name>] [--json]';
 
-/** The ledgers `chant query` reads from `cwd`: every member's in a workspace, else the project's own. */
-export async function queryLedgers(cwd: string, members?: readonly string[]): Promise<QueryLedger[]> {
+/**
+ * The ledgers `chant query` and `chant ledger` read from `cwd`: every
+ * member's in a workspace, else the project's own. With `at`, a commit of
+ * `chant/lifecycle` (`chant ledger --at`, #4363), each is read as that commit
+ * held it rather than at the branch tip.
+ */
+export async function queryLedgers(cwd: string, members?: readonly string[], at?: string): Promise<QueryLedger[]> {
   const { gitLedgerReadPort } = await import("../../lifecycle/git");
   const found = findWorkspaceRoot(cwd);
-  if (!found) return [{ member: null, port: gitLedgerReadPort({ cwd }) }];
+  const atPort = at === undefined ? undefined : await (async () => {
+    const { resolveLedgerRevision, revisionLedgerReadPort } = await import("../../lifecycle/ledger-read");
+    const { memberLedgerPrefix } = await import("../../lifecycle/member-ledger");
+    const repo = found?.dir ?? cwd;
+    const commit = resolveLedgerRevision(repo, at);
+    return (member: string | null) => revisionLedgerReadPort(repo, commit, member === null ? "" : memberLedgerPrefix([member]));
+  })();
+  if (!found) return [{ member: null, port: atPort ? atPort(null) : gitLedgerReadPort({ cwd }) }];
   // Workspace code loads only when there is a workspace, so a level-0 project never pays for it.
   const { readDeclaration, WorkspaceReadError } = await import("../../workspace/declaration");
   const { workingTree } = await import("../../workspace/tree");
@@ -41,7 +53,7 @@ export async function queryLedgers(cwd: string, members?: readonly string[]): Pr
   }
   return declaration.members
     .filter((m) => !wanted || wanted.has(m.name))
-    .map((m) => ({ member: m.name, port: gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
+    .map((m) => ({ member: m.name, port: atPort ? atPort(m.dir === "." ? null : m.name) : gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
 }
 
 export async function runQueryCommand(ctx: CommandContext): Promise<number> {

package/src/cli/handlers/release.ts

@@ -174,9 +174,12 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       const { scopeSource } = await import("../../workspace/write-scope");
       const { releaseRuleFrom } = await import("../../workspace/identity");
       const source = scopeSource(cwd);
-      trunk = ws.resolveTrunk(top, source.declaration?.ci?.green?.branch ?? null);
+      const greenDecl = source.declaration?.ci?.green ?? null;
+      const primary = ws.resolveTrunk(top, greenDecl?.branch ?? null);
+      trunk = primary;
       try {
-        ws.checkOnTrunk(top, commit, trunk);
+        // #4325: a commit of a branch ci.green also judges (one ci.branches routes members to) is cut like trunk's.
+        trunk = ws.checkOnGreenBranches(top, commit, primary, (greenDecl?.branches ?? []).slice(1));
       } catch (err) {
         // #4168 4.3: a commit of a pushed compose branch is cut too, and the cut records what it carries.
         if (!(err instanceof ws.WorkstationCheckError) || err.code !== "release-commit-not-on-trunk") throw err;
@@ -552,7 +555,7 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
  */
 export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
   const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
-  const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}) });
+  const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}), ...(ctx.args.branch ? { branch: ctx.args.branch } : {}) });
   if (ctx.args.json) {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;

package/src/cli/handlers/search.ts

@@ -22,6 +22,7 @@ import { collectBuildRootContributors, loadPlugins, resolveProjectLexicons } fro
 import { declaredBuildRootContributors, mergeDeclaredBuildRoots, withLexiconEdges } from "./declared-graph";
 import { parseCountBy, countGroups, countsJson, formatCounts, groupMembers, hasManyTerraformRoots, type CountBy } from "./search-count";
 import { formatError, formatWarning } from "../format";
+import { adjacencyOf, walkBreadthFirst } from "../../graph-walk";
 import type { CommandContext } from "../registry";
 import { SEARCH_CONTRACT_VERSION, SEARCH_OUTPUT_SCHEMA_ID, type SearchErrorCode, type SearchFailure, type SearchHead } from "../../workspace/search-contract";
 
@@ -1870,13 +1871,7 @@ const adjacency = new WeakMap<GraphIR, { out: Map<string, IREdge[]>; in: Map<str
 function edgeIndex(ir: GraphIR): { out: Map<string, IREdge[]>; in: Map<string, IREdge[]> } {
   let idx = adjacency.get(ir);
   if (!idx) {
-    idx = { out: new Map(), in: new Map() };
-    for (const e of ir.edges ?? []) {
-      if (!idx.out.has(e.from)) idx.out.set(e.from, []);
-      idx.out.get(e.from)!.push(e);
-      if (!idx.in.has(e.to)) idx.in.set(e.to, []);
-      idx.in.get(e.to)!.push(e);
-    }
+    idx = adjacencyOf(ir.edges ?? []);
     adjacency.set(ir, idx);
   }
   return idx;
@@ -1894,17 +1889,14 @@ function sameName(a: string | undefined, b: string): boolean {
  * the target leaf (any node when the term has none) at a depth inside the
  * term's range. A plain `->`/`<-` is the range 1..1.
  *
- * Termination on a cycle: a state is (node, depth capped at the range's
- * minimum). Past the minimum, arriving at a node again by a longer walk can
- * reach nothing the first arrival could not, so it is not queued twice. The
- * state space is finite and the walk always ends.
+ * The walk is `walkBreadthFirst` (graph-walk.ts), shared with carve's
+ * reachability (#2325); it is what terminates on a cycle.
  */
 function findPath(n: IRNode, t: Term, ir: GraphIR, byId: Map<string, IRNode>): PathHop[] | null {
   if (t.kind !== "edge") return null;
   const { min, max } = t.depth ?? { min: 1, max: 1 };
   const idx = edgeIndex(ir);
   const out = t.dir === "out";
-  type State = { id: string; depth: number; hops: PathHop[] };
   // A capability edge (#4375) stands for the hops that proved it.
   const steps = (id: string): { far: string; hops: PathHop[] }[] => {
     if (t.capability !== undefined) return capabilitySteps(id, t.capability, out, ir);
@@ -1915,28 +1907,15 @@ function findPath(n: IRNode, t: Term, ir: GraphIR, byId: Map<string, IRNode>): P
         hops: [{ from: e.from, ...(e.viaAttr ? { fromAttr: e.viaAttr } : {}), to: e.to, ...(e.toAttr ? { toAttr: e.toAttr } : {}) }],
       })));
   };
-  const seen = new Set<string>([`${n.id}|0`]);
-  let frontier: State[] = [{ id: n.id, depth: 0, hops: [] }];
-  while (frontier.length > 0) {
-    const next: State[] = [];
-    for (const s of frontier) {
-      if (s.depth >= max) continue;
-      for (const step of steps(s.id)) {
-        const farId = step.far;
-        const far = byId.get(farId);
-        if (!far) continue;
-        const depth = s.depth + 1;
-        const hops = [...s.hops, ...step.hops];
-        if (depth >= min && (!t.sub || matchTerm(far, t.sub, ir, byId))) return hops;
-        const key = `${farId}|${Math.min(depth, min)}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        next.push({ id: farId, depth, hops });
-      }
-    }
-    frontier = next;
-  }
-  return null;
+  // A node the graph does not hold is no step at all, and the match is the
+  // first arrival in range that satisfies the target leaf (#4359).
+  const found = walkBreadthFirst<PathHop>(n.id, {
+    min,
+    max,
+    steps: (id) => steps(id).filter((step) => byId.has(step.far)),
+    arrive: ({ id }) => !t.sub || matchTerm(byId.get(id)!, t.sub, ir, byId),
+  });
+  return found ? found.hops : null;
 }
 
 function bareId(id: string): string {

package/src/cli/main.test.ts

@@ -869,10 +869,12 @@ describe("workspace init and ls (#2534)", () => {
       "workspace pin",
       "workspace points",
       "workspace records",
+      "workspace run",
       "workspace runs",
       "workspace search",
       "workspace signers",
       "workspace status",
+      "workspace train",
       "workspace trust",
       "workspace upgrade",
       "workspace verify",
@@ -882,6 +884,19 @@ describe("workspace init and ls (#2534)", () => {
     ]);
   });
 
+  test("run and train take their targets and flags (#2554)", () => {
+    const run = parseArgs(["workspace", "run", "api/deploy", "web/deploy", "--gate", "release", "--env", "prod"]);
+    expect(run).toMatchObject({ command: "workspace", path: "run", positionals: ["run", "api/deploy", "web/deploy"], gate: "release", env: "prod" });
+    expect(resolveCommand(run, commandRegistry)?.def.name).toBe("workspace run");
+    expect(parseArgs(["workspace", "run", "--dependents-of", "network", "--op", "deploy"])).toMatchObject({ dependentsOf: "network", op: "deploy" });
+    expect(() => parseArgs(["workspace", "run", "--dependents-of"])).toThrow(/--dependents-of needs a member/);
+    const train = parseArgs(["workspace", "train", "prod", "--pin", "api=v2", "--pin", "web=v1"]);
+    expect(train).toMatchObject({ positionals: ["train", "prod"], pins: ["api=v2", "web=v1"] });
+    expect(resolveCommand(train, commandRegistry)?.def.name).toBe("workspace train");
+    expect(() => parseArgs(["workspace", "train", "prod", "--pin", "api"])).toThrow(/--pin needs a member and a release/);
+    expect(parseArgs(["workspace", "lint", "--cross-root", "--format", "json"])).toMatchObject({ path: "lint", crossRoot: true, format: "json" });
+  });
+
   test("adopt-lineage, hash-index, versions and upgrade --source take their flags (#2551)", () => {
     const adopt = parseArgs(["workspace", "adopt-lineage", "app", "--from", "acme/starter#svc", "--tags", "v*", "--index", "i.json", "--param", "name=x", "--dry-run"]);
     expect(adopt).toMatchObject({ command: "workspace", path: "adopt-lineage", extraPositional: "app", migrateFrom: "acme/starter#svc", tags: "v*", index: "i.json", param: ["name=x"], dryRun: true });