@intentius/chant 0.124.40 → 0.124.41

package/src/cli/handlers/pr.ts

@@ -64,6 +64,7 @@
  * through `--forge`.
  */
 
+import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
@@ -85,10 +86,11 @@ import {
 } from "../../components/pr-run";
 import { composeChangeSet, verifyChangeSetDigest } from "../../change-set";
 import { waveGateName } from "../../gated-waves";
+import { blockedMembers, blockedWords, settleEarlierWaves, type WaveMemberOutcome } from "../../wave-blocked";
 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 { gitGateLedgerPort, type GateCheck } from "../../op/gate";
+import { gateIsSealed, gitGateLedgerPort, type GateCheck } from "../../op/gate";
 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";
@@ -105,9 +107,11 @@ import {
   renderPrNote,
   type PrApproval,
   type PrMember,
+  type PrPolicyReport,
   type PrReport,
   type PrWave,
   type PrRound,
+  type PrOverdue,
 } from "../../pr-loop";
 import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf, type ForgeKind, type PrForge } from "../../pr-forge";
 import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "../../plan-summary";
@@ -124,12 +128,16 @@ import { withComponentEndpoint } from "../component-endpoint";
 import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out";
 import { failedRunExitCode, type DriverComponent } from "../../components/driver";
 import type { CapabilityRegistry } from "../../components/capability";
+import { prLoopHooksAt, runPrHooks, type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks";
+import { decidePrPolicyOverride, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrLoopPolicy } from "../../components/pr-policy";
+import type { OpWaveHookMoment } from "../../op/op-waves";
+import type { PrHookOutcome } from "../../pr-loop";
 
 
 /** Where the reports land unless `--output` says. */
 export const PR_REPORT_DIR = ".chant/pr";
 
-interface Prepared {
+export interface Prepared {
   config: ChantConfig;
   env: string;
   /** The workspace member, with `--member` (#3465). */
@@ -148,6 +156,23 @@ interface Prepared {
   signal: ComponentChangeSignal;
   registry: CapabilityRegistry;
   seededOutputs: Record<string, Record<string, unknown>>;
+  /** `ci.hooks` from the declaration at base (#4288). */
+  hooks: PrLoopHooks;
+  /** Every hook the stage ran so far, for the report's `hooks`. */
+  hookOutcomes: PrHookOutcome[];
+  /** Set when a hook failed: the report's message. */
+  hookFailed?: string;
+  /** Where the stage's hooks run, once its op is known. */
+  hookPlace?: PrHookPlace;
+  /**
+   * Set when `ci.branches` or `ci.labels` (#4292) leave the member out of this
+   * stage: why. The plan is then empty, so the stage reports `nothing`.
+   */
+  routedAway?: string;
+  /** `ci.policy` from the declaration at base (#4294). */
+  policy: PrLoopPolicy;
+  /** What the policy said about the plan, for the report's `policy`. */
+  policyReport?: PrPolicyReport;
 }
 
 const fail = (message: string, hint?: string): number => {
@@ -155,8 +180,8 @@ const fail = (message: string, hint?: string): number => {
   return 1;
 };
 
-/** Everything both stages share: the change and the derivation. Each stage plans the members itself. */
-async function prepare(ctx: CommandContext, stage: "plan" | "apply" | "record"): Promise<Prepared | number> {
+/** Everything both stages share: the change and the derivation. Each stage plans the members itself. `pr-env up` (#4298) prepares as the plan does. */
+export async function prepare(ctx: CommandContext, stage: "plan" | "apply" | "record"): Promise<Prepared | number> {
   const { args } = ctx;
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
@@ -236,8 +261,27 @@ async function prepare(ctx: CommandContext, stage: "plan" | "apply" | "record"):
     }
   }
 
+  // #4288: the stage hooks, read from the declaration at base so the change cannot edit what its own jobs run.
+  let hooks: PrLoopHooks;
+  try {
+    hooks = prLoopHooksAt(projectPath, base);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  if (hooks.note) console.error(formatInfo(hooks.note));
+  // #4294: the policy, read from the declaration at base like the hooks.
+  let policy: PrLoopPolicy;
+  try {
+    policy = prLoopPolicyAt(projectPath, base);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  if (policy.note) console.error(formatInfo(policy.note));
+
   const env = args.env ?? "local";
   const registry = await fanOutRegistry(projectPath, config);
+  const routedAway = member ? await routing(ctx, stage, projectPath, member, base, forge) : undefined;
+  if (routedAway) console.error(formatInfo(routedAway));
   return {
     config,
     env,
@@ -247,13 +291,89 @@ async function prepare(ctx: CommandContext, stage: "plan" | "apply" | "record"):
     gate: args.gate ?? PR_APPLY_GATE,
     ...(forge ? { forge } : {}),
     components: derived.components,
-    plan: derived.plan,
+    plan: routedAway ? { ...derived.plan, order: [], waves: [], seeds: [], indeterminate: [] } : derived.plan,
     signal: derived.signal,
     registry,
     seededOutputs,
+    hooks,
+    hookOutcomes: [],
+    ...(routedAway ? { routedAway } : {}),
+    policy,
   };
 }
 
+/** Set where `p`'s hooks run, once the stage knows its op (#4288). */
+export function placeHooks(ctx: CommandContext, p: Prepared, stage: PrHookPlace["stage"], op: string): void {
+  p.hookPlace = { op, env: p.env, stage, dir: ctx.args.output ?? PR_REPORT_DIR, cwd: resolve("."), log: (line) => console.error(line) };
+}
+
+/**
+ * Run one moment's hooks for `components` (#4288), keeping their outcomes
+ * for the report. Returns the failure as the report's message, or undefined
+ * 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 {
+  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);
+  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;
+  p.hookFailed = `The ${ran.failed}, so ${what}.`;
+  return p.hookFailed;
+}
+
+const EMPTY_SET = (): PrPlanSet => ({ doc: composeChangeSet([]), members: [], plans: {}, outputs: {}, failed: true });
+
+/**
+ * Plan with the plan-side hooks around it (#4288): before-observe and
+ * before-plan, then the plan, then after-plan. A failed hook gives a failed
+ * 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();
+  const set = await plan();
+  if (set.failed) return set;
+  if (runStageHook(p, "after-plan", components, set)) return { ...set, failed: true };
+  return set;
+}
+
+/**
+ * Whether `ci.branches` or `ci.labels` (#4292), read from the declaration at
+ * base, leave `member` out of this stage: the reason, or undefined when the
+ * member runs. The record and apply stages read `ci.branches` against the
+ * pushed branch (`--branch`, else the forge's variables); the plan stage
+ * reads `ci.labels` against the pull request's labels. A label only narrows
+ * what is planned: the record and apply stages never read labels.
+ */
+async function routing(ctx: CommandContext, stage: "plan" | "apply" | "record", projectPath: string, member: string, base: string, forge: PrForge | undefined): Promise<string | undefined> {
+  const { scopeSource } = await import("../../workspace/write-scope");
+  const { appliesFrom, plansUnderLabels, pushedBranchFromEnv } = await import("../../workspace/ci-branches");
+  const ci = scopeSource(projectPath, base).declaration?.ci;
+  if (stage !== "plan") {
+    if (!ci?.branches) return undefined;
+    const pushed = ctx.args.branch ?? pushedBranchFromEnv();
+    if (!pushed) return undefined;
+    const route = appliesFrom(ci.branches, member, pushed);
+    if (!route.applies) return route.note;
+    console.error(formatInfo(route.note));
+    return undefined;
+  }
+  if (!ci?.labels || ctx.args.pr === undefined || !forge?.labels) return undefined;
+  let carried: string[];
+  try {
+    carried = await forge.labels(ctx.args.pr);
+  } catch (err) {
+    console.error(formatWarning({ message: `could not read the labels of #${ctx.args.pr}, so every member plans: ${err instanceof Error ? err.message : String(err)}` }));
+    return undefined;
+  }
+  const filter = plansUnderLabels(ci.labels, member, carried);
+  if (!filter.plans) return filter.note;
+  if (filter.note) console.error(formatInfo(filter.note));
+  return undefined;
+}
+
 /**
  * The one `--member` name, checked against the workspace member that owns
  * `projectPath`: a pipeline copied into another member would otherwise
@@ -280,8 +400,12 @@ async function checkMember(projectPath: string, names: string[]): Promise<string
   return name;
 }
 
-/** Plan every member the derivation selects. */
-function planAll(p: Prepared, onRunEvent?: RunEventSink): Promise<PrPlanSet> {
+/** Plan every member the derivation selects, between the plan-side hooks (#4288). */
+export function planAll(p: Prepared, onRunEvent?: RunEventSink): Promise<PrPlanSet> {
+  return hookedPlan(p, p.plan.order, () => planBare(p, onRunEvent));
+}
+
+export function planBare(p: Prepared, onRunEvent?: RunEventSink): Promise<PrPlanSet> {
   return planPrSet({
     components: p.components,
     plan: p.plan,
@@ -343,7 +467,7 @@ async function publish(forge: PrForge | undefined, report: PrReport, note: strin
   if (report.pr === null) return;
   // A member the change does not reach has nothing to say: one note per
   // member would put a line on every pull request for each member it skips.
-  if (report.member && report.status === "nothing") return;
+  if (report.member && report.status === "nothing" && !report.overdue?.length) return;
   try {
     await forge.upsertNote(report.pr, prNoteMarker(report.env, report.member), note);
   } catch (err) {
@@ -366,6 +490,11 @@ function printMembers(report: PrReport): void {
 }
 
 async function finish(ctx: CommandContext, p: Prepared, report: PrReport, upload?: PrReportUpload): Promise<void> {
+  // #4288: the hooks the stage ran, and a failed hook's message in place of the stage's own.
+  if (p.hookOutcomes.length > 0) report = { ...report, hooks: [...p.hookOutcomes] };
+  if (p.hookFailed) report = { ...report, message: p.hookFailed };
+  if (p.routedAway && report.status === "nothing" && !report.message) report = { ...report, message: p.routedAway };
+  if (p.policyReport) report = { ...report, policy: p.policyReport };
   const note = noteFor(report, p.forge);
   writeOutputs(ctx, report, note, upload);
   if (!ctx.args.noStatus) await publish(p.forge, report, note);
@@ -420,6 +549,86 @@ function openUpload(events: StageEvents, stage: "plan" | "apply" | "record", pr:
   return events.upload;
 }
 
+/** What the policy step decided (#4294): a stop, or whether the plan is held and the override it applies under. */
+interface PolicyJudged {
+  stop?: { refusal: "policy-denied" | "policy-error"; message: string; code: number };
+  held: boolean;
+  override?: NonNullable<PrPolicyReport["override"]>;
+}
+
+/**
+ * Run `ci.policy` at base over the planned set (#4294) and keep what it said
+ * on `p` for the report. A denial is decided against the override ledger:
+ * 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 });
+  if (!verdict) return { held: false };
+  const report = prPolicyReport(verdict, p.policy.base);
+  p.policyReport = report;
+  for (const w of verdict.warnings) console.error(formatWarning({ message: `policy warning: ${w}` }));
+  if (verdict.result === "error") {
+    return { held: false, stop: { refusal: "policy-error", code: 1, message: `The policy at ${p.policy.base.slice(0, 12)} could not be checked, so nothing was applied: ${verdict.error}` } };
+  }
+  const held = verdict.holds.length > 0;
+  for (const h of verdict.holds) console.error(formatInfo(`policy holds the plan for a person's approval (${h.rule}): ${h.message}`));
+  if (verdict.result !== "denied") return { held };
+  const denied = verdict.denials.map((d) => `${d.rule}: ${d.message}`).join("; ");
+  let decided: Awaited<ReturnType<typeof decidePrPolicyOverride>>;
+  try {
+    // The plan stage records nothing, and reads the applied records so a spent override reads as spent.
+    const real = gitGateLedgerPort();
+    const port = at.stage === "plan" ? { ...readOnlyLedger(real), ...(real.readApplied ? { readApplied: real.readApplied.bind(real) } : {}) } : real;
+    decided = await decidePrPolicyOverride({
+      port,
+      subject: at.op,
+      digest: at.set.doc.digest,
+      rules: verdict.rules,
+      base: p.base,
+      cwd: resolve("."),
+      sealed: await gateIsSealed(p.gate),
+      record: at.stage === "apply",
+      description: `${at.op}: plan ${at.set.doc.digest} denied by ${verdict.rules.join(", ")}`,
+    });
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    if (at.stage === "plan") {
+      console.error(formatWarning({ message: `could not read the override ledger, so no override reads as standing: ${why}` }));
+      return { held, stop: { refusal: "policy-denied", code: 1, message: `The policy denied this plan: ${denied}.` } };
+    }
+    return { held, stop: { refusal: "policy-denied", code: GATED_EXIT_CODE, message: `The policy denied this plan (${denied}), and the override ledger could not be read or written: ${why}. Nothing was applied.` } };
+  }
+  if (decided.status === "overridden") {
+    report.override = decided.override;
+    console.error(formatInfo(`the policy denial (${verdict.rules.join(", ")}) is overridden by ${decided.override.by} at ${decided.override.at}: ${decided.override.reason}`));
+    return { held, override: decided.override };
+  }
+  report.overrideCommand = decided.command;
+  for (const why of decided.refusals) console.error(formatInfo(`an override does not count: ${why}`));
+  const who = decided.overriders.length ? `${decided.overriders.join(", ")} may` : "nobody listed in .chant/overriders at base may";
+  const moved = decided.moved ? ` ${decided.moved.by} overrode an earlier plan or other rules, which counts for nothing here.` : "";
+  return {
+    held,
+    stop: {
+      refusal: "policy-denied",
+      code: at.stage === "plan" ? 1 : GATED_EXIT_CODE,
+      message: `The policy denied this plan: ${denied}.${moved} Nothing was applied. ${who} override it: ${decided.command}`,
+    },
+  };
+}
+
+/** Spend the override the apply runs under (#4294), before anything applies. The failure's message, or undefined. */
+async function spendPolicy(op: string, judged: PolicyJudged, head: string): Promise<string | undefined> {
+  if (!judged.override) return undefined;
+  try {
+    await spendPrPolicyOverride(gitGateLedgerPort(), op, judged.override, { commit: head });
+  } catch (err) {
+    return `Could not record the override this apply runs under, so nothing was applied: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  console.error(formatInfo(`applies under the override by ${judged.override.by}, which is now spent`));
+  return undefined;
+}
+
 /** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrPlan(ctx: CommandContext): Promise<number> {
   if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
@@ -433,12 +642,15 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
   const p = await prepare(ctx, "plan");
   if (typeof p === "number") return p;
   const op = prOp(ctx.args.pr, p.member);
+  placeHooks(ctx, p, "plan", op);
   const upload = openUpload(stage, "plan", ctx.args.pr, p);
   // `--events-json` (#4041): planning, then where the approval stands.
   const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") }, upload?.line);
   stage.stream = events;
   events?.emit({ type: "run-start", waves: p.plan.waves });
   const set = await planAll(p, events?.emit);
+  // #4294: the policy at base over the planned change set.
+  const judged = p.plan.order.length > 0 && !set.failed ? await judgePolicy(p, { stage: "plan", op, pr: ctx.args.pr, set }) : { held: false };
 
   let approval: PrApproval = { status: "pending" };
   if (p.plan.order.length > 0) {
@@ -452,7 +664,8 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
     }
   }
   const status = p.plan.order.length === 0 ? "nothing" : set.failed ? "plan-failed" : "planned";
-  const report = prReport({
+  const overdue = await overdueOps(p.forge, p.member);
+  const planned = prReport({
     stage: "plan",
     pr: ctx.args.pr,
     env: p.env,
@@ -468,6 +681,7 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
     status,
     ...(ctx.args.waveGate ? { waveGate: ctx.args.waveGate } : {}),
   });
+  const report: PrReport = overdue.length > 0 ? { ...planned, overdue } : planned;
   await finish(ctx, p, report, upload);
   // The plan stage settles on its planning: an approval still to come is what it reports, not a stop.
   events?.settle(settleOf(status), status === "plan-failed" ? "a member failed to plan" : undefined);
@@ -478,7 +692,39 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
     console.error(formatInfo(`plan    : ${report.digest}`));
     console.error(formatInfo(approval.status === "approved" ? `approved by ${(approval.approvedBy ?? []).join(", ")}` : `approve : ${prApproveCommand(report)}`));
   }
-  return status === "plan-failed" ? 1 : 0;
+  if (judged.stop) console.error(formatWarning({ message: judged.stop.message }));
+  return status === "plan-failed" || judged.stop ? 1 : 0;
+}
+
+/**
+ * The scheduled watch and reconcile Ops that stopped running (#4289,
+ * `op/schedule-overdue.ts`), asked of the forge. Without a forge, or when
+ * the Ops cannot be read, nothing is checked and the plan goes on. The
+ * generated plan holds no forge token (#4295), so there the plan-note job's
+ * `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 [];
+  }
 }
 
 /** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
@@ -493,6 +739,9 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   const reviewRules = !ctx.args.requireReview && securityGroupsAt(process.cwd(), ctx.args.base).has("review-rules");
   if (reviewRules && !ctx.args.forge) return fail("the workspace opts into review-rules, which reads the pull request's reviews, so pr-apply needs --forge <kind>");
   if (reviewRules) ctx = { ...ctx, args: { ...ctx.args, requireReview: true } };
+  // #4293: ci.locks, read at base like the security groups, so the change cannot turn its own locks off.
+  const { ciLocksAt } = await import("../../workspace/ci-locks");
+  const locks = ciLocksAt(process.cwd(), ctx.args.base);
   const { args } = ctx;
   if (args.requireReview && !args.forge) return fail("--require-review reads the pull request's reviews, so it needs --forge <kind>");
   if (args.wave !== undefined && !args.waveGate) return fail("--wave runs one wave of a --wave-gate apply, so it needs --wave-gate <name>");
@@ -517,6 +766,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
     }
   }
   const op = green ? greenOp(green.commit, p.member) : pr === null ? "pr-unknown" : prOp(pr, p.member);
+  placeHooks(ctx, p, "apply", op);
   // The run id the release records carry, chosen before the run so that
   // `--events-json` (#4041, #4007) names the run by it too.
   const release = autoReleaseRun(`${op}-${Date.now()}`);
@@ -524,6 +774,17 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   const events = await openCliRunEvents(args, { kind: "component", name: `pr-apply ${op}`, runId: release.runId, cwd: resolve(".") }, upload?.line);
   stage.stream = events;
   events?.emit({ type: "run-start", waves: p.plan.waves });
+  if (locks && p.plan.order.length > 0) {
+    const held = await heldLocksOf(p, pr);
+    if (typeof held === "number") return held;
+    if (held) {
+      const set: PrPlanSet = { doc: composeChangeSet([]), members: [], plans: {}, outputs: {}, failed: false };
+      return stopper(ctx, p, events, upload)(
+        prReport({ stage: "apply", pr, env: p.env, ...(p.member ? { member: p.member } : {}), base: p.base, head: p.head, op, gate: p.gate, plan: p.plan, signal: p.signal, set, approval: { status: "pending" }, status: "refused", refusal: "locked", message: held }),
+        GATED_EXIT_CODE,
+      );
+    }
+  }
   if (args.waveGate) return prApplyWaves(ctx, p, { pr, op, release, upload, events, ...(green ? { green } : {}) });
 
   // `--resume` (#3464): an earlier attempt at this change on this commit
@@ -593,10 +854,14 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
 
   let approval: PrApproval;
   let via: "merges" | "gate" = "gate";
+  // #4294: the policy at base, before the gate. A resume runs under the decision of the attempt it finishes.
+  let judged: PolicyJudged = { held: false };
   if (resumed) {
     approval = resumed.approval;
   } else {
-    const decided = await decideApplyGate(p, { op, pr, set, events, ...(green ? { green } : {}) });
+    judged = await judgePolicy(p, { stage: "apply", op, pr, set });
+    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;
     if (!decided.satisfied) return stop(prReport({ ...base, approval, status: "refused", refusal: decided.refusal, message: decided.message }), GATED_EXIT_CODE);
     via = decided.via;
@@ -609,6 +874,8 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
     emitReviewStop(events, review.message);
     return stop(prReport({ ...base, approval, status: "refused", refusal: review.refusal, message: review.message }), GATED_EXIT_CODE);
   }
+  const unspent = await spendPolicy(op, judged, p.head);
+  if (unspent) return stop(prReport({ ...base, approval, status: "refused", refusal: "policy-denied", message: unspent }), 1);
 
   // The record is written before the first component runs and again as each
   // one settles, so a run killed partway still knows what applied.
@@ -642,6 +909,11 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   };
   recordAttempt();
 
+  // #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);
+  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
   // own, under the same identity.gates rule and the same review checks.
   const roundLedger = gitGateLedgerPort();
@@ -697,11 +969,13 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
       : {}),
   });
   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");
   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,
     approval,
-    status: applied.status,
+    status: afterFailed ? "failed" : applied.status,
     members: applied.members,
     ...(resumed ? { resumed: resumed.completed } : {}),
     ...(applied.rounds ? { rounds: applied.rounds } : {}),
@@ -710,13 +984,36 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   // A component that stopped at a gate of its own leaves the apply waiting on
   // a person. A step that refused its plan because the target moved since
   // the approval exits 3, as a moved digest does before anything applies (#3997).
-  const exit = applied.status === "applied" ? 0 : applied.status === "waiting" ? GATED_EXIT_CODE : failedRunExitCode(applied.run.results);
+  const exit = afterFailed ? 1 : applied.status === "applied" ? 0 : applied.status === "waiting" ? GATED_EXIT_CODE : failedRunExitCode(applied.run.results);
   if (green && applied.status === "applied") await recordGreenApplied(p, green, set.doc.digest, approval, via);
   const code = await stop(report, exit, applied.run.status === "gated" ? "gated" : undefined);
-  if (applied.status === "applied") console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
+  if (applied.status === "applied" && !afterFailed) console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
   return code;
 }
 
+/**
+ * Under `ci.locks` (#4293): the refusal when another open pull request holds
+ * a lock on a component this apply reaches, else null. The targets are the
+ * selected components, the names `chant lock` takes. A lock whose pull
+ * request the forge says merged or closed reads as released; with no
+ * `--forge` every lock counts. A lock file that cannot be read stops the
+ * apply, since nothing then says the targets are free.
+ */
+async function heldLocksOf(p: Prepared, pr: number | null): Promise<string | null | number> {
+  const { heldTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
+  const isOpen = p.forge?.pullRequestOpen?.bind(p.forge);
+  let held;
+  try {
+    held = await heldTargetLocks(p.gate, p.plan.order, pr, { ...(isOpen ? { isOpen } : {}) });
+  } catch (err) {
+    return fail(`could not read the target locks of ${p.gate}, so nothing was applied: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (held.length === 0) return null;
+  const name = (n: number) => (p.forge?.kind === "gitlab" ? `merge request !${n}` : `pull request ${n}`);
+  const holders = [...new Set(held.map((h) => h.pr))].sort((a, b) => a - b);
+  return `${describeHeldTargetLocks(held, name)}, so nothing was applied. Apply again once ${holders.length === 1 ? "it merges or closes" : "they merge or close"}, or after \`chant unlock --pr ${holders[0]}${p.gate === PR_APPLY_GATE ? "" : ` --gate ${p.gate}`}\`${isOpen ? "" : ". Without --forge every lock counts as held"}.`;
+}
+
 /** #4274: a component that published nothing is recorded by the plan digest its approval bound. */
 function prAppliedDigests(p: Prepared, members: PrMember[]) {
   return appliedDigestOf({ components: p.components, env: p.env, projectRoot: resolve("."), members });
@@ -752,6 +1049,7 @@ async function prRecord(ctx: CommandContext, stage: StageEvents): Promise<number
     }
   }
   const op = pr === null ? "pr-unknown" : prOp(pr, p.member);
+  placeHooks(ctx, p, "record", op);
   const upload = openUpload(stage, "record", pr, p);
   const events = await openCliRunEvents(args, { kind: "component", name: `pr-record ${op}`, cwd: resolve(".") }, upload?.line);
   stage.stream = events;
@@ -808,31 +1106,34 @@ async function prRecord(ctx: CommandContext, stage: StageEvents): Promise<number
 
   const { mergeSourceOf, writeMergeRecord, MERGE_RECORD_SCHEMA_ID, MERGE_RECORD_CONTRACT } = await import("../../lifecycle/merge-record");
   const { pushLifecycleReport } = await import("../../lifecycle/git");
-  try {
-    const written = await writeMergeRecord({
-      $schema: MERGE_RECORD_SCHEMA_ID,
-      contract: MERGE_RECORD_CONTRACT,
-      commit: p.head,
-      base: p.base,
-      env: p.env,
-      ...(p.member ? { member: p.member } : {}),
-      source: mergeSourceOf(resolve("."), p.head, pr),
-      op: pr === null ? null : op,
-      gate: p.gate,
-      digest: nothing ? null : set.doc.digest,
-      plan: nothing ? "nothing" : set.failed ? "plan-failed" : approval.status === "approved" ? "approved" : approval.status === "changed" ? "changed" : "unapproved",
-      ...(approval.status === "changed" && approval.approved ? { approvedDigest: approval.approved } : {}),
-      approvedBy: approval.status === "approved" ? (approval.approvedBy ?? []) : [],
-      ...(authorApproved && authorApproved.length > 0 ? { authorApproved } : {}),
-      components: p.plan.order,
-      recordedAt: new Date().toISOString(),
-    });
-    if (written.written) {
-      const pushed = await pushLifecycleReport();
-      if (pushed.pushWarning) console.error(formatWarning({ message: pushed.pushWarning }));
+  // #4292: a member another branch applies has no merge on this one, so no record says it planned nothing here.
+  if (!p.routedAway) {
+    try {
+      const written = await writeMergeRecord({
+        $schema: MERGE_RECORD_SCHEMA_ID,
+        contract: MERGE_RECORD_CONTRACT,
+        commit: p.head,
+        base: p.base,
+        env: p.env,
+        ...(p.member ? { member: p.member } : {}),
+        source: mergeSourceOf(resolve("."), p.head, pr),
+        op: pr === null ? null : op,
+        gate: p.gate,
+        digest: nothing ? null : set.doc.digest,
+        plan: nothing ? "nothing" : set.failed ? "plan-failed" : approval.status === "approved" ? "approved" : approval.status === "changed" ? "changed" : "unapproved",
+        ...(approval.status === "changed" && approval.approved ? { approvedDigest: approval.approved } : {}),
+        approvedBy: approval.status === "approved" ? (approval.approvedBy ?? []) : [],
+        ...(authorApproved && authorApproved.length > 0 ? { authorApproved } : {}),
+        components: p.plan.order,
+        recordedAt: new Date().toISOString(),
+      });
+      if (written.written) {
+        const pushed = await pushLifecycleReport();
+        if (pushed.pushWarning) console.error(formatWarning({ message: pushed.pushWarning }));
+      }
+    } catch (err) {
+      console.error(formatWarning({ message: `could not write the merge record for ${p.head}: ${err instanceof Error ? err.message : String(err)}` }));
     }
-  } catch (err) {
-    console.error(formatWarning({ message: `could not write the merge record for ${p.head}: ${err instanceof Error ? err.message : String(err)}` }));
   }
 
   const stop = stopper(ctx, p, events, upload);
@@ -874,11 +1175,15 @@ async function greenTargetOf(ctx: CommandContext): Promise<GreenTarget | number>
  */
 async function decideApplyGate(
   p: Prepared,
-  at: { op: string; pr: number | null; set: PrPlanSet; events?: RunEventStream; green?: GreenTarget },
+  at: { op: string; pr: number | null; set: PrPlanSet; events?: RunEventStream; green?: GreenTarget; held?: boolean },
 ): Promise<{ approval: PrApproval; satisfied: true; via: "merges" | "gate" } | { approval: PrApproval; satisfied: false; refusal: "plan-changed" | "not-approved"; message: string }> {
   const { op, pr, set, events, green } = at;
   let uncovered: string[] = [];
-  if (green) {
+  // #4294: a plan the policy holds needs an approval of its own digest, so the merges' approvals do not cover it.
+  if (green && at.held) {
+    console.error(formatInfo(`the policy holds the plan at ${green.commit.slice(0, 12)}, so it needs an approval of its own digest and does not apply under the merges' approvals`));
+    uncovered = ["the policy holds this plan for an approval of its own digest"];
+  } else if (green) {
     const cover = coverByMerges(set.doc, green.approved);
     if (cover.covered) {
       console.error(formatInfo(`the approved plans of ${cover.coveredBy.length} merge${cover.coveredBy.length === 1 ? "" : "s"} cover the plan at ${green.commit.slice(0, 12)}, so it applies under them`));
@@ -1277,8 +1582,23 @@ async function prApplyWaves(
   const completed = new Set(carry?.completed ?? []);
   const outputsSoFar: Record<string, Record<string, unknown>> = { ...(carry?.outputs ?? {}) };
   const inputsSoFar: Record<string, string> = Object.fromEntries([...completed].filter((n) => inputsNow[n] !== undefined).map((n) => [n, inputsNow[n]!]));
-  const failedSoFar = new Set<string>();
+  // #4291: what failed in an earlier wave's job stays failed until it applies, so this job blocks its dependents and runs the rest.
+  const failedSoFar = new Set<string>((carry ? attempt?.failed ?? [] : []).filter((name) => !completed.has(name)));
   let waves: PrWave[] = carry?.record.waves ?? [];
+  const upstreams = new Map(p.components.map((c) => [c.name, c.dependsOn ?? []]));
+  /** Each component's outcome so far, past applied (#4291): failed, waiting, not-applied, or blocked by a failure. */
+  const outcomes = (): Map<string, WaveMemberOutcome> => {
+    const out = new Map<string, WaveMemberOutcome>();
+    for (const name of completed) out.set(name, { status: "applied" });
+    for (const name of failedSoFar) out.set(name, { status: "failed" });
+    for (const w of waves) {
+      if (w.status !== "waiting" && w.status !== "plan-failed" && w.status !== "failed") continue;
+      for (const name of w.components) if (!out.has(name)) out.set(name, { status: w.status === "waiting" ? "waiting" : "not-applied" });
+    }
+    return out;
+  };
+  /** Components a failure blocked (#4291), each with the component that failed. */
+  const blockedSoFar = new Map<string, string>();
   const after = new Map<string, PrMember>();
   const leftIn = (k: number): string[] => (p.plan.waves[k - 1] ?? []).filter((name) => !completed.has(name));
   const firstLeft = (): number => p.plan.waves.findIndex((_, i) => leftIn(i + 1).length > 0) + 1;
@@ -1293,15 +1613,32 @@ async function prApplyWaves(
     const set = approved ?? { doc: composeChangeSet([]), members: [], plans: {}, outputs: {}, failed: false };
     const members = set.members.map((m): PrMember => {
       const now = after.get(m.member);
-      if (now) return { ...m, status: now.status, ...(now.error ? { error: now.error } : {}) };
-      return completed.has(m.component) ? { ...m, status: "applied" } : m;
+      if (now) return { ...m, status: now.status, ...(now.error ? { error: now.error } : {}), ...(now.blockedBy ? { blockedBy: now.blockedBy } : {}) };
+      if (completed.has(m.component)) return { ...m, status: "applied" };
+      const by = blockedSoFar.get(m.component);
+      if (by !== undefined) return { ...m, status: "blocked", blockedBy: by };
+      return failedSoFar.has(m.component) ? { ...m, status: "failed" } : m;
     });
     return prReport({ ...reportBase, set, approval, members, waves, ...input });
   };
 
   // `--wave <k>` reached before an earlier wave applied: nothing runs, as `fan-out --wave` refuses.
+  // #4291: an earlier member that failed, or was blocked by one that failed, counts as settled; it blocks its dependents here.
   const left = firstLeft();
-  if (only !== undefined && left > 0 && left < only) {
+  const earlierWaiting = only !== undefined ? waves.find((w) => w.wave < only && w.status === "waiting" && w.components.some((name) => !completed.has(name))) : undefined;
+  if (earlierWaiting) {
+    return stop(
+      report({
+        status: "refused",
+        refusal: "earlier-wave",
+        message: `Wave ${only} does not run yet: wave ${earlierWaiting.wave} waits at its gate ${earlierWaiting.gate}. Nothing was applied. Approve that wave and run its job again, then this one.`,
+      }),
+      GATED_EXIT_CODE,
+    );
+  }
+  const settled = only !== undefined && left > 0 && left < only ? settleEarlierWaves(p.plan.waves, only, upstreams, outcomes()) : undefined;
+  if (settled) for (const [name, o] of settled.outcomes) if (o.status === "blocked" && o.by) blockedSoFar.set(name, o.by);
+  if (only !== undefined && left > 0 && left < only && (settled?.unsettled.length ?? 0) > 0) {
     return stop(
       report({
         status: "refused",
@@ -1315,6 +1652,7 @@ async function prApplyWaves(
   }
 
   let planned: PrPlanSet | undefined;
+  let judged: PolicyJudged = { held: false };
   if (carry) {
     // What the earlier waves applied settles first (#4007), each in its own wave, as a resumed apply's does.
     p.plan.waves.forEach((names, i) => {
@@ -1332,7 +1670,10 @@ async function prApplyWaves(
       return stop(report({ status: "plan-failed", message: "A member failed to plan, so there is no plan to compare with the approved one. Nothing was applied." }), 1);
     }
     await storeChangeSetForGate(ctx, p, set.doc);
-    const decided = await decideApplyGate(p, { op, pr, set, events, ...(green ? { green } : {}) });
+    // #4294: the policy at base judges the whole change set, before the pull request's gate.
+    judged = await judgePolicy(p, { stage: "apply", op, pr, set });
+    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;
     if (!decided.satisfied) return stop(report({ status: "refused", refusal: decided.refusal, message: decided.message }), GATED_EXIT_CODE);
     via = decided.via;
@@ -1347,6 +1688,8 @@ async function prApplyWaves(
     emitReviewStop(events, prReview.message);
     return stop(report({ status: "refused", refusal: prReview.refusal, message: prReview.message }), GATED_EXIT_CODE);
   }
+  const unspent = await spendPolicy(op, judged, p.head);
+  if (unspent) return stop(report({ status: "refused", refusal: "policy-denied", message: unspent }), 1);
 
   const recordAttempt = (): void => {
     if (!resumePath) return;
@@ -1377,9 +1720,27 @@ async function prApplyWaves(
 
   const from = only ?? (left || total + 1);
   const to = only ?? total;
+  /** The last apply in this job that failed (#4291): its results give the exit code once every wave ran. */
+  let lastFailure: { results: Parameters<typeof failedRunExitCode>[0]; gated: boolean } | undefined;
+  let planFailedIn: number | undefined;
   for (let k = from; k <= to; k++) {
-    const wavePlan = prWavePlan(p.plan, p.components, k, [...completed]);
-    if (wavePlan.order.length === 0) continue;
+    // #4291: a component of this wave whose upstream failed, or was blocked by a failure, is blocked; the rest of the wave runs.
+    const before = new Set(p.plan.waves.slice(0, k - 1).flat());
+    const mine = leftIn(k);
+    for (const name of mine) {
+      failedSoFar.delete(name);
+      blockedSoFar.delete(name);
+    }
+    const outcomesNow = outcomes();
+    for (const [name, by] of blockedSoFar) outcomesNow.set(name, { status: "blocked", by });
+    const blockedNow = blockedMembers(mine, upstreams, before, outcomesNow);
+    for (const [name, by] of blockedNow) blockedSoFar.set(name, by);
+    if (blockedNow.size > 0) console.error(formatWarning({ message: `wave ${k}: ${blockedWords(blockedNow)}, so not planned or applied`, hint: "A failure blocks only the members that depend on it; the rest of the wave goes on." }));
+    const wavePlan = prWavePlan(p.plan, p.components, k, [...completed, ...blockedNow.keys()]);
+    if (wavePlan.order.length === 0) {
+      if (blockedNow.size > 0) recordAttempt();
+      continue;
+    }
     const inThisWave = new Set(wavePlan.order);
 
     // Wave 1 of the apply that just planned every member applies those plans:
@@ -1396,18 +1757,26 @@ async function prApplyWaves(
       entry = { wave: k, components: wavePlan.order, status: "applied", approval: "pull-request", gate: p.gate, digest: approvedSet.doc.digest, ...(approval.approvedBy ? { approvedBy: approval.approvedBy } : {}) };
     } else {
       const notApplied = Object.fromEntries(Object.entries(approvedSet.outputs).filter(([name]) => !completed.has(name)));
-      const fresh = await planPrSet({
-        components: p.components,
-        plan: wavePlan,
-        registry: p.registry,
-        env: p.env,
-        seededOutputs: { ...p.seededOutputs, ...notApplied, ...outputsSoFar },
-        ...(events ? { onRunEvent: (body: RunEventBody) => events.emit(body) } : {}),
-      });
+      const fresh = await hookedPlan(p, wavePlan.order, () =>
+        planPrSet({
+          components: p.components,
+          plan: wavePlan,
+          registry: p.registry,
+          env: p.env,
+          seededOutputs: { ...p.seededOutputs, ...notApplied, ...outputsSoFar },
+          ...(events ? { onRunEvent: (body: RunEventBody) => events.emit(body) } : {}),
+        }),
+      );
       if (fresh.failed) {
-        for (const m of fresh.members) after.set(m.member, m);
+        for (const m of fresh.members) {
+          after.set(m.member, m);
+          if (m.status === "plan-failed") failedSoFar.add(m.component);
+        }
         setWave({ wave: k, components: wavePlan.order, status: "plan-failed", approval: "pull-request", gate: p.gate, digest: approvedSet.doc.digest });
-        return stop(report({ status: "plan-failed", message: `A member of wave ${k} failed to plan, so nothing in wave ${k} was applied.` }), 1);
+        // #4291: the later waves still run what does not depend on this wave.
+        console.error(formatWarning({ message: `A member of wave ${k} failed to plan, so nothing in wave ${k} was applied.`, hint: "The waves after it apply what does not depend on wave " + k + "." }));
+        planFailedIn ??= k;
+        continue;
       }
       const moved = waveNotCovered(approvedSet.doc, fresh.doc, approvedSet.members);
       set = fresh;
@@ -1462,6 +1831,12 @@ 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`);
+    if (waveBefore) {
+      setWave({ ...entry, status: "failed" });
+      return stop(report({ status: "failed", message: waveBefore }), 1);
+    }
     const applied = await applyPrSet({
       components: p.components,
       plan: wavePlan,
@@ -1477,6 +1852,7 @@ async function prApplyWaves(
       onComponentSettled: (settled, outputs) => {
         if (settled.status === "ok") {
           completed.add(settled.component);
+          failedSoFar.delete(settled.component);
           if (inputsNow[settled.component] !== undefined) inputsSoFar[settled.component] = inputsNow[settled.component]!;
           if (outputs) outputsSoFar[settled.component] = outputs;
         } else if (settled.status === "fail") {
@@ -1491,14 +1867,33 @@ async function prApplyWaves(
       const outputs = applied.run.componentOutputs[name];
       if (outputs) outputsSoFar[name] = outputs;
     }
-    setWave({ ...entry, status: applied.status === "applied" ? "applied" : "failed" });
+    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`);
+    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") {
-      return stop(report({ status: "failed" }), failedRunExitCode(applied.run.results), applied.run.status === "gated" ? "gated" : undefined);
+      // #4291: a failed member blocks only its dependents, so the later waves still run.
+      lastFailure = { results: applied.run.results, gated: applied.run.status === "gated" };
+      recordAttempt();
+      continue;
     }
+    if (waveAfter) return stop(report({ status: "failed", message: waveAfter }), 1);
     console.error(formatSuccess(`applied wave ${k} of ${total} under ${entry.approval === "pull-request" ? `the pull request's approval of ${approvedSet.doc.digest}` : `${entry.gate}, approved for ${entry.digest}`} by ${(entry.approvedBy ?? []).join(", ")}`));
   }
 
+  // #4291: a failure, or a member it blocked, fails the job once every other member applied.
+  const blockedHere = [...blockedSoFar.keys()].filter((name) => (only === undefined ? true : (p.plan.waves[only - 1] ?? []).includes(name)));
+  if (lastFailure || planFailedIn !== undefined || blockedHere.length > 0) {
+    const blockedLine = blockedSoFar.size > 0 ? ` Blocked: ${blockedWords(blockedSoFar)}.` : "";
+    const message = planFailedIn !== undefined && !lastFailure
+      ? `A member of wave ${planFailedIn} failed to plan, so nothing in wave ${planFailedIn} was applied.${blockedLine}`
+      : blockedLine ? blockedLine.trim() : undefined;
+    return stop(
+      report({ status: "failed", ...(message ? { message } : {}) }),
+      lastFailure ? failedRunExitCode(lastFailure.results) : 1,
+      lastFailure?.gated ? "gated" : undefined,
+    );
+  }
+
   const done = p.plan.order.every((name) => completed.has(name));
   if (green && done) await recordGreenApplied(p, green, approvedSet.doc.digest, approval, via);
   return stop(report({ status: done ? "applied" : "wave-applied" }), 0);
@@ -1513,3 +1908,45 @@ function writeWaveChangeSet(ctx: CommandContext, wave: number, doc: PrPlanSet["d
   writeFileSync(join(dir, name), body);
   upload?.file(name, body);
 }
+
+/**
+ * chant components pr-post --pr <n> --head <sha> --env <env> --forge <kind> [--member <name>] [--output <dir>] [--result <result>] (#4295)
+ *
+ * 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
+ * code. The pull request, the head, the environment and the member come from
+ * the flags, and a report that names others is refused (`../../pr-post.ts`).
+ * It exits 0 once it has posted, whatever the plan said, so the plan job's
+ * own result stays the one that fails the run.
+ */
+export async function runComponentsPrPost(ctx: CommandContext): Promise<number> {
+  const { args } = 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>");
+  if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail(`pr-post posts to a forge: --forge ${FORGE_KINDS.join("|")}`);
+  if (args.members && args.members.length > 1) return fail(`pr-post takes one --member, not ${args.members.join(", ")}`);
+  let forge: PrForge;
+  try {
+    forge = forgeFromEnv(args.forge as ForgeKind);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  const { postPlanReport } = await import("../../pr-post");
+  const member = args.members?.[0];
+  const posted = await postPlanReport({
+    forge,
+    dir: resolve(args.output ?? PR_REPORT_DIR),
+    pr: args.pr,
+    head: args.head,
+    env: args.env,
+    ...(member ? { member } : {}),
+    ...(args.planResult ? { result: args.planResult } : {}),
+    // #4289: the plan job could not ask the forge, so the note job does, from the Ops at the commit it checked out.
+    overdue: () => overdueOps(forge, member),
+  });
+  for (const message of posted.warnings) console.error(formatWarning({ message }));
+  if (posted.refused) console.error(formatWarning({ message: `the plan report was not used: ${posted.refused}` }));
+  console.error(formatInfo(`pr-post: ${prStatusContext("plan", member)} ${posted.state}: ${posted.description}${posted.noted ? "; note posted" : ""}`));
+  return 0;
+}