@intentius/chant 0.124.39 → 0.124.41

package/dist/cli/handlers/pr.js

@@ -63,6 +63,7 @@
  * all it uses one for; pr-apply still reads the pull request and its reviews
  * through `--forge`.
  */
+import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadChantConfig, resolveAutoReleaseDisabled } from "../../config.js";
@@ -71,10 +72,11 @@ import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support.j
 import { applyPrSet, approvalOf, approversWhoAuthored, approversWithoutReview, decidePrGate, planPrSet, prReport, readOnlyLedger, prWavePlan, resumePrSet, waveNotCovered, } from "../../components/pr-run.js";
 import { composeChangeSet, verifyChangeSetDigest } from "../../change-set.js";
 import { waveGateName } from "../../gated-waves.js";
+import { blockedMembers, blockedWords, settleEarlierWaves } from "../../wave-blocked.js";
 import { readFanOutAttempt, writeFanOutAttempt } from "../../components/fan-out-record.js";
 import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs.js";
 import { samePlanDigest } from "../../lifecycle/plan-digest.js";
-import { gitGateLedgerPort } from "../../op/gate.js";
+import { gateIsSealed, gitGateLedgerPort } from "../../op/gate.js";
 import { emitGateStep, gateEventsOf, GATE_PHASE } from "../../run-event-stream.js";
 import { openCliRunEvents, refusesEventsWithJson } from "../run-events.js";
 import { openPrReportUpload, parseReportUrl, reportKey } from "../../pr-report-url.js";
@@ -88,15 +90,19 @@ import { findWorkspaceRoot } from "../../project-root.js";
 import { resolveChangedUnits } from "./fan-out.js";
 import { coverByMerges, greenOp } from "../../components/green-cover.js";
 import { GATED_EXIT_CODE, autoReleaseRun, recordAutoReleasesForRun } from "./run.js";
+import { appliedDigestOf } from "../../components/auto-release.js";
+import { withComponentEndpoint } from "../component-endpoint.js";
 import { failedRunExitCode } from "../../components/driver.js";
+import { prLoopHooksAt, runPrHooks } from "../../components/pr-hooks.js";
+import { decidePrPolicyOverride, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride } from "../../components/pr-policy.js";
 /** Where the reports land unless `--output` says. */
 export const PR_REPORT_DIR = ".chant/pr";
 const fail = (message, hint) => {
     console.error(formatError({ message, ...(hint ? { hint } : {}) }));
     return 1;
 };
-/** Everything both stages share: the change and the derivation. Each stage plans the members itself. */
-async function prepare(ctx, stage) {
+/** 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, stage) {
     const { args } = ctx;
     const projectPath = resolve(".");
     const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} }));
@@ -176,8 +182,31 @@ async function prepare(ctx, stage) {
             return fail(`--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // #4288: the stage hooks, read from the declaration at base so the change cannot edit what its own jobs run.
+    let hooks;
+    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;
+    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,
@@ -187,12 +216,97 @@ async function prepare(ctx, stage) {
         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, p, stage, op) {
+    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, moment, components, planned, what = "nothing was applied") {
+    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 = () => ({ 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, components, plan) {
+    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, stage, projectPath, member, base, forge) {
+    const { scopeSource } = await import("../../workspace/write-scope.js");
+    const { appliesFrom, plansUnderLabels, pushedBranchFromEnv } = await import("../../workspace/ci-branches.js");
+    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;
+    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
@@ -221,8 +335,11 @@ async function checkMember(projectPath, names) {
     }
     return name;
 }
-/** Plan every member the derivation selects. */
-function planAll(p, onRunEvent) {
+/** Plan every member the derivation selects, between the plan-side hooks (#4288). */
+export function planAll(p, onRunEvent) {
+    return hookedPlan(p, p.plan.order, () => planBare(p, onRunEvent));
+}
+export function planBare(p, onRunEvent) {
     return planPrSet({
         components: p.components,
         plan: p.plan,
@@ -284,7 +401,7 @@ async function publish(forge, report, note) {
         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")
+    if (report.member && report.status === "nothing" && !report.overdue?.length)
         return;
     try {
         await forge.upsertNote(report.pr, prNoteMarker(report.env, report.member), note);
@@ -306,6 +423,15 @@ function printMembers(report) {
     }
 }
 async function finish(ctx, p, report, upload) {
+    // #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)
@@ -352,11 +478,90 @@ function openUpload(events, stage, pr, p) {
     });
     return events.upload;
 }
+/**
+ * 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, at) {
+    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;
+    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, judged, head) {
+    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) {
     if (refusesEventsWithJson(ctx.args, "the stage's report"))
         return Promise.resolve(1);
-    return withStageEvents("pr-plan", ctx, (events) => prPlan(ctx, events));
+    return withStageEvents("pr-plan", ctx, (events) => withComponentEndpoint(ctx, () => prPlan(ctx, events)));
 }
 async function prPlan(ctx, stage) {
     if (ctx.args.pr === undefined) {
@@ -366,12 +571,15 @@ async function prPlan(ctx, stage) {
     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 = { status: "pending" };
     if (p.plan.order.length > 0) {
         try {
@@ -383,7 +591,8 @@ async function prPlan(ctx, stage) {
         }
     }
     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,
@@ -399,6 +608,7 @@ async function prPlan(ctx, stage) {
         status,
         ...(ctx.args.waveGate ? { waveGate: ctx.args.waveGate } : {}),
     });
+    const report = 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);
@@ -408,13 +618,49 @@ async function prPlan(ctx, stage) {
         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, member) {
+    if (!forge?.scheduledRuns)
+        return [];
+    try {
+        const { discoverOps } = await import("../../op/discover.js");
+        const { scheduledWatches, checkOverdueOps } = await import("../../op/schedule-overdue.js");
+        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>] */
 export function runComponentsPrApply(ctx) {
     if (refusesEventsWithJson(ctx.args, "the stage's report"))
         return Promise.resolve(1);
-    return withStageEvents("pr-apply", ctx, (events) => prApply(ctx, events));
+    return withStageEvents("pr-apply", ctx, (events) => withComponentEndpoint(ctx, () => prApply(ctx, events)));
 }
 async function prApply(ctx, stage) {
     // #4168: the review-rules security group turns --require-review on, read from the declaration at base.
@@ -424,6 +670,9 @@ async function prApply(ctx, stage) {
         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.js");
+    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>");
@@ -453,6 +702,7 @@ async function prApply(ctx, stage) {
         }
     }
     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()}`);
@@ -460,6 +710,15 @@ async function prApply(ctx, stage) {
     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 = { 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
@@ -519,11 +778,16 @@ async function prApply(ctx, stage) {
     await storeChangeSetForGate(ctx, p, set.doc);
     let approval;
     let via = "gate";
+    // #4294: the policy at base, before the gate. A resume runs under the decision of the attempt it finishes.
+    let judged = { 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);
@@ -537,6 +801,9 @@ async function prApply(ctx, stage) {
         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.
     const prior = resumed ? { completed: resumed.completed, outputs: resumed.outputs } : { completed: [], outputs: {} };
@@ -567,6 +834,11 @@ async function prApply(ctx, stage) {
         });
     };
     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();
@@ -623,11 +895,13 @@ async function prApply(ctx, stage) {
             : {}),
     });
     recordAttempt();
-    await recordAutoReleasesForRun(applied.run.results, p.env, release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), release.runOrigin);
+    // #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 } : {}),
@@ -636,19 +910,47 @@ async function prApply(ctx, stage) {
     // 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")
+    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, pr) {
+    const { heldTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock.js");
+    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) => (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, members) {
+    return appliedDigestOf({ components: p.components, env: p.env, projectRoot: resolve("."), members });
+}
 /** chant components pr-record --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrRecord(ctx) {
     if (refusesEventsWithJson(ctx.args, "the stage's report"))
         return Promise.resolve(1);
-    return withStageEvents("pr-record", ctx, (events) => prRecord(ctx, events));
+    return withStageEvents("pr-record", ctx, (events) => withComponentEndpoint(ctx, () => prRecord(ctx, events)));
 }
 /**
  * The record stage (#4168 step 1): what a merge does unless apply on merge
@@ -675,6 +977,7 @@ async function prRecord(ctx, stage) {
         }
     }
     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;
@@ -727,33 +1030,36 @@ async function prRecord(ctx, stage) {
     });
     const { mergeSourceOf, writeMergeRecord, MERGE_RECORD_SCHEMA_ID, MERGE_RECORD_CONTRACT } = await import("../../lifecycle/merge-record.js");
     const { pushLifecycleReport } = await import("../../lifecycle/git.js");
-    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);
     return stop(report, status === "plan-failed" ? 1 : 0);
@@ -794,7 +1100,12 @@ async function greenTargetOf(ctx) {
 async function decideApplyGate(p, at) {
     const { op, pr, set, events, green } = at;
     let uncovered = [];
-    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`));
@@ -1175,8 +1486,28 @@ async function prApplyWaves(ctx, p, at) {
     const completed = new Set(carry?.completed ?? []);
     const outputsSoFar = { ...(carry?.outputs ?? {}) };
     const inputsSoFar = Object.fromEntries([...completed].filter((n) => inputsNow[n] !== undefined).map((n) => [n, inputsNow[n]]));
-    const failedSoFar = new Set();
+    // #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((carry ? attempt?.failed ?? [] : []).filter((name) => !completed.has(name)));
     let waves = 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 = () => {
+        const out = new Map();
+        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();
     const after = new Map();
     const leftIn = (k) => (p.plan.waves[k - 1] ?? []).filter((name) => !completed.has(name));
     const firstLeft = () => p.plan.waves.findIndex((_, i) => leftIn(i + 1).length > 0) + 1;
@@ -1191,14 +1522,33 @@ async function prApplyWaves(ctx, p, at) {
         const members = set.members.map((m) => {
             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;
+                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",
             refusal: "earlier-wave",
@@ -1207,6 +1557,7 @@ async function prApplyWaves(ctx, p, at) {
         }), 1);
     }
     let planned;
+    let judged = { 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) => {
@@ -1225,7 +1576,11 @@ async function prApplyWaves(ctx, p, at) {
             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);
@@ -1241,6 +1596,9 @@ async function prApplyWaves(ctx, p, at) {
         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 = () => {
         if (!resumePath)
             return;
@@ -1270,10 +1628,31 @@ async function prApplyWaves(ctx, p, at) {
     recordAttempt();
     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;
+    let planFailedIn;
     for (let k = from; k <= to; k++) {
-        const wavePlan = prWavePlan(p.plan, p.components, k, [...completed]);
-        if (wavePlan.order.length === 0)
+        // #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:
         // they are the approved set's. Every other wave is planned again, against
@@ -1290,19 +1669,25 @@ async function prApplyWaves(ctx, p, at) {
         }
         else {
             const notApplied = Object.fromEntries(Object.entries(approvedSet.outputs).filter(([name]) => !completed.has(name)));
-            const fresh = await planPrSet({
+            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) => events.emit(body) } : {}),
-            });
+            }));
             if (fresh.failed) {
-                for (const m of fresh.members)
+                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 ?? (planFailedIn = k);
+                continue;
             }
             const moved = waveNotCovered(approvedSet.doc, fresh.doc, approvedSet.members);
             set = fresh;
@@ -1351,6 +1736,12 @@ async function prApplyWaves(ctx, p, at) {
                 entry = { wave: k, components: wavePlan.order, status: "applied", approval: "wave", gate, digest, moved, ...(waveApproval.approvedBy ? { approvedBy: waveApproval.approvedBy } : {}) };
             }
         }
+        // #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,
@@ -1367,6 +1758,7 @@ async function prApplyWaves(ctx, p, at) {
             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)
@@ -1386,13 +1778,28 @@ async function prApplyWaves(ctx, p, at) {
             if (outputs)
                 outputsSoFar[name] = outputs;
         }
-        setWave({ ...entry, status: applied.status === "applied" ? "applied" : "failed" });
-        await recordAutoReleasesForRun(applied.run.results, p.env, at.release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), at.release.runOrigin);
+        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);
@@ -1407,3 +1814,52 @@ function writeWaveChangeSet(ctx, wave, doc, upload) {
     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) {
+    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.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;
+    try {
+        forge = forgeFromEnv(args.forge);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+    const { postPlanReport } = await import("../../pr-post.js");
+    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;
+}