@intentius/chant 0.124.30 → 0.124.32

package/src/cli/parse-args.ts

@@ -66,6 +66,12 @@ const BOOLEAN_FLAGS = new Set([
   "--confirm-prod",
   "--once",
   "--rerun-failed",
+  "--setup-key",
+  "--trust",
+  "--unsigned",
+  "--in-place",
+  "--no-push",
+  "--no-require-review",
   "--expire",
   "--check-live",
   "--check-snapshot",
@@ -388,6 +394,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       const url = args[++i];
       if (!url || url.startsWith("-")) throw new Error("--report-url needs a URL: --report-url s3://<bucket>/<prefix> or file://<directory>");
       result.reportUrl = url;
+    } else if (arg === "--no-status") {
+      // `chant ci run|serve --no-status` (#4097): post no commit status for the job.
+      result.noStatus = true;
+    } else if (arg === "--status-url") {
+      // `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries, in place of an https --report-url.
+      result.statusUrl = args[++i];
+      if (!result.statusUrl || result.statusUrl.startsWith("-")) throw new Error("--status-url needs a URL template: --status-url https://host/reports/{key}");
     } else if (arg === "--allow-unsigned") {
       // `chant release publish --allow-unsigned` (#4049).
       result.allowUnsigned = true;
@@ -536,10 +549,19 @@ export function parseArgs(args: string[]): ParsedArgs {
       const name = args[++i];
       if (!name || name.startsWith("-")) throw new Error("--pass-env needs a variable's name, such as AWS_PROFILE: --pass-env <NAME>");
       (result.passEnv ??= []).push(name);
+    } else if (arg === "--secrets") {
+      // `chant ci run|serve --secrets <file>` (#4096): the host's secrets file, readable only by its owner.
+      result.ciSecrets = args[++i];
+      if (!result.ciSecrets || result.ciSecrets.startsWith("-")) throw new Error("--secrets needs the host's secrets file, a dotenv or JSON file only its owner can read: --secrets <file>");
     } else if (arg === "--repo") {
       // `chant ci serve --repo <owner/repo>` (#4095): the repository whose pull requests and target branch it polls.
       result.ciRepo = args[++i];
       if (!result.ciRepo || !/^[^/\s-][^/\s]*\/[^/\s]+$/.test(result.ciRepo)) throw new Error("--repo needs the repository as owner/name: --repo <owner/repo>");
+    } else if (arg === "--run-index-limit") {
+      // `chant ci run --run-index-limit <n>` (#4098): how many runs the index at the report URL keeps.
+      const n = Number(args[++i]);
+      if (!Number.isInteger(n) || n < 1) throw new Error("--run-index-limit needs a whole number of runs, 1 or more: --run-index-limit <n>");
+      result.runIndexLimit = n;
     } else if (arg === "--max-jobs") {
       // `chant ci serve --max-jobs <n>` (#4095): how many jobs run at once.
       const n = Number(args[++i]);
@@ -576,6 +598,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
       if (!result.verdict || result.verdict.startsWith("-")) throw new Error("--verdict needs agree, dissent or abstain");
+    } else if (arg === "--class") {
+      // `chant workspace trust runner add <principal> --class runner|service` (#3510).
+      result.runnerClass = args[++i];
+      if (!result.runnerClass || result.runnerClass.startsWith("-")) throw new Error("--class needs runner or service: --class <class>");
     } else if (arg === "--by") {
       // `chant workspace records review <id> --by <principal>` (#2670): whoever the caller says.
       result.by = args[++i];
@@ -748,6 +774,28 @@ export function parseArgs(args: string[]): ParsedArgs {
       }
     } else if (arg === "--once") {
       result.once = true;
+    } else if (arg === "--setup-key") {
+      // `chant ci serve|run --setup-key` (#4099): make the host's runner key and print its public half.
+      result.setupKey = true;
+    } else if (arg === "--trust") {
+      // `chant ci serve|run --setup-key --trust` (#4099): list the key in .chant/trust.json on a branch.
+      result.trustKey = true;
+    } else if (arg === "--in-place") {
+      // `chant ci run --in-place` (#4156): run the job in this checkout, as a generated forge job does.
+      result.ciInPlace = true;
+    } else if (arg === "--no-push") {
+      // `chant ci run --no-push` (#4156): keep the run record on the local chant/lifecycle.
+      result.noPush = true;
+    } else if (arg === "--no-require-review") {
+      // `chant ci run apply --no-require-review` (#4156): the apply without pr-apply's --require-review.
+      result.requireReview = false;
+    } else if (arg === "--unsigned") {
+      // `chant ci serve --unsigned` (#4099): serve without a runner key listed at the target's head.
+      result.unsigned = true;
+    } else if (arg === "--principal") {
+      // `chant ci serve|run --setup-key --trust --principal <name>` (#4099): the runner's principal.
+      result.ciPrincipal = args[++i];
+      if (!result.ciPrincipal || result.ciPrincipal.startsWith("-")) throw new Error("--principal needs the runner's principal: --principal <name>");
     } else if (arg === "--work") {
       // `chant run <op> --work <id>` (#2748)
       const value = args[++i];

package/src/cli/registry.ts

@@ -23,7 +23,7 @@ export interface ParsedArgs {
   /** `--version` / `-V` (#2701): print the installed chant's version. */
   version?: boolean;
   report?: boolean;
-  /** `chant run` — force the local in-process executor (the default). */
+  /** `chant run` — force the local in-process executor (the default). `chant ci run --local` (#4161): run the job on this machine with no push, status or report upload. */
   local?: boolean;
   /**
    * `chant run <op> --on <lexicon>` (#2121) — which runtime hosts the run.
@@ -311,7 +311,8 @@ export interface ParsedArgs {
   /**
    * `chant components pr-apply --require-review` (#3183) — count an approval
    * only when its approver has a standing approving review on the pull
-   * request. Needs `--forge`.
+   * request. Needs `--forge`. `chant ci run apply --no-require-review`
+   * (#4156) sets it false, for a pipeline generated with `requireReview: false`.
    */
   requireReview?: boolean;
   /**
@@ -462,8 +463,16 @@ export interface ParsedArgs {
   commit?: string;
   /** `chant ci run --pass-env <NAME>`, repeatable (#4094): a variable of the runner's environment the job gets, beside the few it always gets. */
   passEnv?: string[];
+  /** `chant ci run|serve --secrets <file>` (#4096): the host's secrets file. Default the file `CHANT_CI_SECRETS` names. */
+  ciSecrets?: string;
   /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. Also `chant ci run --chant` (#4094): what runs chant in the job. */
   ciChant?: string;
+  /** `chant ci run|serve --no-status` (#4097): post no commit status for the job. `chant components pr-plan|pr-apply --no-status` (#4161): post neither the status nor the note. */
+  noStatus?: boolean;
+  /** `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries. `{key}` is `<pr>/<commit>[/<member>]`, as `--report-url` keys it. */
+  statusUrl?: string;
+  /** `chant ci run --run-index-limit <n>` (#4098): how many runs the index at the report URL keeps. Default 200. */
+  runIndexLimit?: number;
   /** `chant ci serve --repo <owner/repo>` (#4095): the repository it polls. */
   ciRepo?: string;
   /** `chant ci serve --max-jobs <n>` (#4095): how many jobs run at once. Default 1. */
@@ -490,6 +499,24 @@ export interface ParsedArgs {
    * `records-write.ts`.
    */
   by?: string;
+  /** `chant ci serve|run --setup-key` (#4099): make the host's runner key in the state directory and print its public half. */
+  setupKey?: boolean;
+  /** `chant ci serve|run --setup-key --trust` (#4099): list the runner key in .chant/trust.json on a branch pushed for review. */
+  trustKey?: boolean;
+  /**
+   * `chant ci serve --unsigned` (#4099): serve without signing. Since #4156
+   * that is the default without a trusted key, so it only skips the key, and
+   * is ignored when ci.green.signedSince requires signed runs.
+   */
+  unsigned?: boolean;
+  /** `chant ci run --in-place` (#4156): run the job in this checkout at HEAD, as a generated forge job does. */
+  ciInPlace?: boolean;
+  /** `chant ci run --no-push` (#4156): write the run record on the local chant/lifecycle and push nothing. */
+  noPush?: boolean;
+  /** `chant ci serve|run --setup-key --trust --principal <name>` (#4099): the principal the runner key is listed for. */
+  ciPrincipal?: string;
+  /** `chant workspace trust runner add <principal> --class runner|service` (#3510): the runner entry's class. */
+  runnerClass?: string;
   /**
    * `chant workspace records review <id> --sign [<key file>]` (#2687): the key that seals the verdict, or true for git's user.signingkey.
    * On `records new` and `records amend`, the key that seals the record's author (#2688).
@@ -739,8 +766,12 @@ export interface ResolvedCommand {
  * Supports compound commands like "dev generate" where args.command="dev"
  * and args.path="generate". Falls back to simple command matching.
  */
-/** Short command aliases. `chant lc …` is sugar for `chant lifecycle …`. */
-const COMMAND_ALIASES: Record<string, string> = { lc: "lifecycle" };
+/**
+ * Command aliases. `chant lc …` is sugar for `chant lifecycle …`, and
+ * `chant sync` for `chant update`, the command that syncs lexicon types
+ * (chant #3988).
+ */
+const COMMAND_ALIASES: Record<string, string> = { lc: "lifecycle", sync: "update" };
 
 export function resolveCommand(args: ParsedArgs, registry: CommandDef[]): ResolvedCommand | null {
   const command = COMMAND_ALIASES[args.command] ?? args.command;

package/src/codegen/generate-post-synth-barrel.ts

@@ -14,7 +14,7 @@
  */
 
 import { createRequire } from "module";
-import { listRuleFiles } from "../lint/discover";
+import { listRuleFiles, ruleModuleBase } from "../lint/discover";
 import { isPostSynthCheck } from "../lint/post-synth";
 
 export interface BarrelEntry {
@@ -34,7 +34,7 @@ export function scanPostSynthChecks(dir: string, importMetaUrl: string): BarrelE
   const require = createRequire(importMetaUrl);
   const entries: BarrelEntry[] = [];
   for (const file of listRuleFiles(dir)) {
-    const base = file.replace(/\.ts$/, "");
+    const base = ruleModuleBase(file);
     let mod: Record<string, unknown>;
     try {
       mod = require(`${dir}/${base}`) as Record<string, unknown>;

package/src/codegen/lexicon-regen.ts

@@ -402,7 +402,7 @@ function runExampleHarness(lexiconDir: string, verbose: boolean): RegenFailure |
 /**
  * Extract the fresh surface from the generated artifacts in the lexicon directory.
  */
-function extractFreshSurface(lexiconDir: string): SurfaceSnapshot | null {
+export function extractFreshSurface(lexiconDir: string): SurfaceSnapshot | null {
   const generatedDir = join(lexiconDir, "src", "generated");
   if (!existsSync(generatedDir)) return null;
 

package/src/codegen/pinned-upgrade.ts

@@ -29,7 +29,7 @@ import { regenLexicon, type RegenResult } from "./lexicon-regen";
 import { fetchWithRetry } from "./fetch";
 import { isLexiconPlugin, type UpstreamPin } from "../lexicon";
 import { importLexiconPackage } from "../lexicon-module";
-import { ensureTypeScriptLoader } from "../ts-loader";
+import { ensureTypeScriptLoaderFor } from "../ts-loader";
 
 // ── Public types ──────────────────────────────────────────────────────
 
@@ -252,7 +252,7 @@ export async function loadUpstreamPins(lexicon: LexiconId, lexiconDir?: string):
   const entry = lexiconDir ? lexiconEntry(lexiconDir) : null;
   if (entry) {
     try {
-      ensureTypeScriptLoader();
+      ensureTypeScriptLoaderFor(entry);
       const pins = pinsOf((await import(pathToFileURL(entry).href)) as Record<string, unknown>);
       if (pins.length > 0) return pins;
     } catch {

package/src/codegen/post-synth-barrel-guards.test.ts

@@ -26,17 +26,12 @@ describe("post-synth barrel is exported", () => {
   test.each(lexiconDirs)("%s exports ./lint/post-synth", (lexicon) => {
     const pkg = JSON.parse(readFileSync(join(lexiconsDir, lexicon, "package.json"), "utf-8"));
     const entry = pkg.exports?.["./lint/post-synth"];
-    // Lexicons shipping .d.ts use a conditional export — `types` resolves to the
-    // emitted declaration for external consumers; `development`/`default` keep
-    // runtime resolution on source (in-repo and published alike). Lexicons not
-    // yet building dist keep the plain source string.
-    if (typeof entry === "string") {
-      expect(entry).toBe("./src/lint/post-synth/index.ts");
-    } else {
-      expect(entry?.development).toBe("./src/lint/post-synth/index.ts");
-      expect(entry?.types).toBe("./dist/lint/post-synth/index.d.ts");
-      expect(entry?.default).toBe("./src/lint/post-synth/index.ts");
-    }
+    // A conditional export: `types` resolves to the emitted declaration,
+    // `development` keeps the repository's own resolution on source, and
+    // `default` is the compiled JS the package publishes (#3981).
+    expect(entry?.development).toBe("./src/lint/post-synth/index.ts");
+    expect(entry?.types).toBe("./dist/lint/post-synth/index.d.ts");
+    expect(entry?.default).toBe("./dist/lint/post-synth/index.js");
   });
 });
 

package/src/components/capability.ts

@@ -43,7 +43,9 @@ export interface DeployContext {
    * (#3049), keyed by {@link CapabilityPlan.member}. Set by a gated-wave
    * fan-out and by a pull request's apply (#3183). A capability whose `run`
    * finds its own member here applies that plan, the one the approver
-   * approved, instead of planning again.
+   * approved, instead of planning again. A `run` that finds the target moved
+   * since that plan refuses with an error {@link isPlanMovedError} accepts
+   * (#3997), and the command that applied it exits 3, as for a moved digest.
    */
   plans?: Record<string, unknown>;
   /**
@@ -90,6 +92,27 @@ export interface CapabilityPlan {
    * still counts toward the digest, with no entries.
    */
   changeSet?: ChangeSetPart;
+  /**
+   * The outputs `run` will expose once it applies this plan (#3999), as far
+   * as the plan can tell. A pull request's plan reads a dependent's
+   * `stackOutput()` references into this member from here when both are in
+   * the change, instead of from the outputs standing now. Absent when the
+   * plan cannot say: every output of the step is then known only after it
+   * applies.
+   */
+  outputs?: PlannedOutputs;
+}
+
+/**
+ * What a plan says about the outputs its apply will leave (#3999). An
+ * output named in neither field is known only after apply, the same as one
+ * in `unknown`.
+ */
+export interface PlannedOutputs {
+  /** Each output whose value the plan knows, by name: what `run` will expose. */
+  known: Record<string, unknown>;
+  /** Outputs the plan names whose value is known only after apply, sorted. */
+  unknown: string[];
 }
 
 /**
@@ -136,8 +159,11 @@ export interface Capability<In = unknown, Out = unknown> {
   /**
    * Optional: the outputs `run` exposed when it last ran, read without
    * changing anything (#3183). A pull request's plan reads them for each
-   * component a planned one depends on, so a `stackOutput()` wiring resolves
-   * to the value standing now. The shape is `run`'s `outputs` field.
+   * component a planned one depends on that the change does not plan
+   * (#4104), so a `stackOutput()` wiring resolves to the value standing now.
+   * A dependency the change plans is read from its plan's
+   * {@link CapabilityPlan.outputs} instead (#3999). The shape is `run`'s
+   * `outputs` field.
    */
   outputs?(ctx: DeployContext, input: In): Promise<Record<string, unknown>>;
   /**
@@ -160,6 +186,28 @@ export type CapabilityInput<C> = C extends Capability<infer In, unknown> ? In :
 /** Extract a capability's `Out` type. */
 export type CapabilityOutput<C> = C extends Capability<unknown, infer Out> ? Out : never;
 
+/**
+ * The exit code of a command whose capability step refused a plan that moved
+ * since it was approved: 3, the code `pr-apply` gives a moved digest and a
+ * run gives a gate (#3997).
+ */
+export const PLAN_MOVED_EXIT_CODE = 3;
+
+/**
+ * Whether `err` is a `run`'s refusal to apply a plan from
+ * `DeployContext.plans` because the target moved since it was planned
+ * (#3997). The mark is a `planMoved: true` property, not a class, so a
+ * lexicon built against an older core can set it. An `exitCode` of
+ * {@link PLAN_MOVED_EXIT_CODE} on the error is the same mark. Any other
+ * `exitCode` is ignored: a failed step exits 1, so a capability can't pick
+ * the process's exit code.
+ */
+export function isPlanMovedError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as { planMoved?: unknown; exitCode?: unknown };
+  return e.planMoved === true || e.exitCode === PLAN_MOVED_EXIT_CODE;
+}
+
 /**
  * Thrown by a stub `run`/`rollback` — the verb is specified and typed but has
  * no cloud implementation yet. Distinguishes "not implemented" from a runtime

package/src/components/changed-files.test.ts

@@ -9,7 +9,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
-import { changedFilesBetween } from "./changed-files";
+import { changedFilesBetween, EMPTY_TREE_SHA, resolveMergeBase } from "./changed-files";
 
 const repo = mkdtempSync(join(tmpdir(), "chant-changed-files-"));
 afterAll(() => rmSync(repo, { recursive: true, force: true }));
@@ -56,3 +56,18 @@ describe("changedFilesBetween", () => {
     ]);
   });
 });
+
+describe("the empty tree as the base (a root commit, #4004)", () => {
+  test("is its own merge base, and every file the head holds counts as changed", async () => {
+    expect(await resolveMergeBase(repo, EMPTY_TREE_SHA, "HEAD")).toBe(EMPTY_TREE_SHA);
+    expect(await changedFilesBetween(repo, EMPTY_TREE_SHA)).toEqual([
+      "apps/web/main.tf",
+      "infra/network/roots/vpc/main.tf",
+      "shared/modules/base/main.tf",
+    ]);
+  });
+
+  test("is git's own empty tree", () => {
+    expect(git("hash-object", "-t", "tree", "/dev/null")).toBe(EMPTY_TREE_SHA);
+  });
+});

package/src/components/changed-files.ts

@@ -20,13 +20,21 @@ async function git(cwd: string, args: string[]): Promise<string> {
   return stdout;
 }
 
+/**
+ * Git's empty tree. A root commit has no parent, so a push of one is measured
+ * from this (#4004): every file it holds counts as changed.
+ */
+export const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
 /**
  * The commit a change is measured from: the merge base of `base` and `head`.
  * A pull request's head that branched before `base` moved is measured from
  * where it branched, so the other changes on `base` are not counted as its
- * own; a merge commit's first parent is its own merge base.
+ * own; a merge commit's first parent is its own merge base. The empty tree
+ * has no merge base with anything and is returned as it is.
  */
 export async function resolveMergeBase(cwd: string, base: string, head = "HEAD"): Promise<string> {
+  if (base === EMPTY_TREE_SHA) return base;
   try {
     return (await git(cwd, ["merge-base", base, head])).trim();
   } catch (err) {

package/src/components/driver.test.ts

@@ -11,7 +11,7 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { CapabilityRegistry, type DeployContext } from "./capability";
+import { CapabilityRegistry, isPlanMovedError, type DeployContext } from "./capability";
 import { stubCapability } from "./verbs/stub";
 import { describeGateMismatch, memoryGateLedgerPort } from "../op/gate";
 import { componentPlanDigest } from "./gate-plan";
@@ -22,6 +22,7 @@ import {
   UnknownDependencyError,
   accumulateComponentOutputs,
   collectComponentOutputs,
+  failedRunExitCode,
   resolveComponentGraph,
   resolveWiring,
   runComponentDeploy,
@@ -1173,3 +1174,37 @@ describe("unresolvedWiringSources (#4084)", () => {
     ).toEqual([]);
   });
 });
+
+describe("a step that refuses a moved plan (#3997)", () => {
+  it.each([
+    ["planMoved: true", { planMoved: true }, true],
+    ["exitCode 3", { exitCode: 3 }, true],
+    ["exitCode 7", { exitCode: 7 }, false],
+    ['exitCode "3"', { exitCode: "3" }, false],
+    ["planMoved: \"yes\"", { planMoved: "yes" }, false],
+    ["no mark", {}, false],
+  ])("isPlanMovedError reads an error with %s", (_label, mark, moved) => {
+    expect(isPlanMovedError(Object.assign(new Error("refused"), mark))).toBe(moved);
+  });
+
+  it("is not fooled by a non-object", () => {
+    expect(isPlanMovedError(null)).toBe(false);
+    expect(isPlanMovedError("planMoved")).toBe(false);
+  });
+
+  it("marks the failed step's record, and failedRunExitCode answers 3 for it and 1 for any other failure", async () => {
+    const run = async (mark: object) => {
+      const registry = new CapabilityRegistry();
+      registry.register(fakeCapability("apply", { run: () => { throw Object.assign(new Error("refused"), mark); } }).capability);
+      const component: DriverComponent = { name: "c", deploy: [{ phase: "Apply", steps: [{ kind: "apply" }] }] };
+      return runComponentDeploy(component, { env: "dev", component: "c" }, registry, {});
+    };
+    const moved = await run({ exitCode: 3 });
+    expect(moved.records[0]).toMatchObject({ status: "fail", planMoved: true });
+    expect(failedRunExitCode([moved])).toBe(3);
+    const other = await run({ exitCode: 7 });
+    expect(other.records[0]).not.toHaveProperty("planMoved");
+    expect(failedRunExitCode([other])).toBe(1);
+    expect(failedRunExitCode([other, moved])).toBe(3);
+  });
+});

package/src/components/driver.ts

@@ -54,6 +54,7 @@ import { GateNotRecordableError } from "../lifecycle/no-record";
 import { componentPlanDigest } from "./gate-plan";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
+import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
 import { isPromotedArtifact } from "./auto-release";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent } from "./run-progress";
@@ -154,6 +155,8 @@ export interface DriverStepRecord {
   durationMs: number;
   output?: unknown;
   error?: string;
+  /** Set on a failed step whose capability refused a plan that moved since it was approved (`isPlanMovedError`, #3997). */
+  planMoved?: true;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
   approval?: {
     gate: string;
@@ -356,12 +359,51 @@ export function unresolvedWiringSources(
   input: Record<string, unknown>,
   componentOutputs: Record<string, Record<string, unknown>>,
 ): string[] {
-  const found = new Set<string>();
+  return [...new Set(unresolvedWiringReferences(input, componentOutputs).map((r) => r.source))].sort();
+}
+
+/** One cross-component reference a step input makes: whose output, and which. */
+export interface WiringReference {
+  /** The component or stack whose output it reads. */
+  source: string;
+  /** `<stack>.<name>` for `stackOutput()`, `<component>.publish.<field>` for an artifact. */
+  ref: string;
+  /**
+   * Whether it reads a published artifact's identity (#3999): an
+   * `@<component>.publish.*` reference, or a `stackOutput()` whose name is
+   * under `publish`. The driver namespaces every publish-family output there
+   * (`collectComponentOutputs`), whatever capability wrote it.
+   */
+  publish: boolean;
+}
+
+/**
+ * Every cross-component reference in `input` that has no value in
+ * `componentOutputs`, sorted by `ref` and each once (#3999). A pull
+ * request's plan names these when the output is known only after its
+ * upstream applies.
+ */
+export function unresolvedWiringReferences(
+  input: Record<string, unknown>,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): WiringReference[] {
+  return wiringReferences(input).filter((r) => r.value(componentOutputs) === undefined).map(({ source, ref, publish }) => ({ source, ref, publish }));
+}
+
+/**
+ * Every cross-component reference in `input`, each once, sorted by `ref`,
+ * with the value it resolves to against a given outputs map.
+ */
+function wiringReferences(input: Record<string, unknown>): Array<WiringReference & { value: (outputs: Record<string, Record<string, unknown>>) => unknown }> {
+  const found = new Map<string, WiringReference & { value: (outputs: Record<string, Record<string, unknown>>) => unknown }>();
   const walk = (value: unknown): void => {
     if (typeof value === "string") {
       if (PRIOR_STEP_REF.test(value)) return;
       const ref = value.match(COMPONENT_ARTIFACT_REF);
-      if (ref && resolvePath(componentOutputs[ref[1]]?.publish, ref[2]) === undefined) found.add(ref[1]);
+      if (ref) {
+        const [, source, field] = ref;
+        found.set(`${source}.publish.${field}`, { source, ref: `${source}.publish.${field}`, publish: true, value: (o) => resolvePath(o[source]?.publish, field) });
+      }
       return;
     }
     if (Array.isArray(value)) {
@@ -371,14 +413,29 @@ export function unresolvedWiringSources(
     if (value && typeof value === "object") {
       if ("stackOutput" in value) {
         const { stack, name } = (value as { stackOutput: { stack: string; name: string } }).stackOutput;
-        if (resolvePath(componentOutputs[stack], name) === undefined) found.add(stack);
+        found.set(`${stack}.${name}`, { source: stack, ref: `${stack}.${name}`, publish: name === "publish" || name.startsWith("publish."), value: (o) => resolvePath(o[stack], name) });
         return;
       }
       Object.values(value as Record<string, unknown>).forEach(walk);
     }
   };
   walk(input);
-  return [...found].sort();
+  return [...found.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+}
+
+/**
+ * The cross-component references in `input` that resolve to another value
+ * against `now` than against `read`, sorted (#3999). A pull request's apply
+ * holds back a member whose plan read `read` when its upstream applied and
+ * left `now`.
+ */
+export function movedWiringReferences(
+  input: Record<string, unknown>,
+  read: Record<string, Record<string, unknown>>,
+  now: Record<string, Record<string, unknown>>,
+): WiringReference[] {
+  const same = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+  return wiringReferences(input).filter((r) => !same(r.value(read), r.value(now))).map(({ source, ref, publish }) => ({ source, ref, publish }));
 }
 
 // ── Step + phase execution ───────────────────────────────────────────────
@@ -501,6 +558,7 @@ async function runCapabilityStep(
         status: "fail",
         durationMs: Date.now() - start,
         error: errMessage(err),
+        ...(isPlanMovedError(err) ? { planMoved: true as const } : {}),
       },
       resolvedInput,
     };
@@ -995,6 +1053,20 @@ function findStackOutputs(
   return found;
 }
 
+/** Whether a step in `results` refused a plan that moved since it was approved (#3997). */
+export function planMovedIn(results: readonly DriverComponentResult[]): boolean {
+  return results.some((r) => r.records.some((s) => s.planMoved === true));
+}
+
+/**
+ * The exit code of a run that failed: {@link PLAN_MOVED_EXIT_CODE} when a
+ * step refused a plan that moved since it was approved, 1 otherwise. Every
+ * command that runs capability steps ends a failed run with it.
+ */
+export function failedRunExitCode(results: readonly DriverComponentResult[]): number {
+  return planMovedIn(results) ? PLAN_MOVED_EXIT_CODE : 1;
+}
+
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }

package/src/components/fan-out-record.ts

@@ -38,7 +38,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { readWaveRecords, writeWaveRecordFile, type WaveRecord } from "../wave-engine";
 import type { ChangeSetDocument } from "../change-set";
-import type { PrMember } from "../pr-loop";
+import type { PrMember, PrWave } from "../pr-loop";
 
 /** What a pull request's apply approved, kept so a re-run can finish it (#3464). */
 export interface PrApplyRecord {
@@ -59,6 +59,11 @@ export interface PrApplyRecord {
    * against them again, so an unchanged member plans to the same digest.
    */
   planOutputs: Record<string, Record<string, unknown>>;
+  /**
+   * With `--wave-gate` (#4003): each wave reached so far and the approval it
+   * applied or waits under, so the next wave's job reports every wave.
+   */
+  waves?: PrWave[];
 }
 
 export interface FanOutAttempt {
@@ -100,6 +105,7 @@ function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
   if (isRecord(planOutputs)) {
     for (const [name, v] of Object.entries(planOutputs)) if (isRecord(v)) outputs[name] = v;
   }
+  const waves = Array.isArray(value.waves) ? value.waves.map(readPrWave).filter((w): w is PrWave => w !== undefined) : [];
   return {
     op,
     gate,
@@ -109,6 +115,28 @@ function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
     members: members as unknown as PrMember[],
     changeSet: changeSet as unknown as ChangeSetDocument,
     planOutputs: outputs,
+    ...(waves.length > 0 ? { waves } : {}),
+  };
+}
+
+const WAVE_STATUSES: ReadonlySet<string> = new Set(["applied", "failed", "plan-failed", "waiting"]);
+
+/** One `prApply.waves` entry, or `undefined` when it is malformed. */
+function readPrWave(value: unknown): PrWave | undefined {
+  if (!isRecord(value)) return undefined;
+  const { wave, components, status, approval, gate, digest } = value;
+  if (typeof wave !== "number" || !isStringArray(components) || typeof status !== "string" || !WAVE_STATUSES.has(status)) return undefined;
+  if ((approval !== "pull-request" && approval !== "wave") || typeof gate !== "string" || typeof digest !== "string") return undefined;
+  return {
+    wave,
+    components,
+    status: status as PrWave["status"],
+    approval,
+    gate,
+    digest,
+    ...(isStringArray(value.approvedBy) ? { approvedBy: value.approvedBy } : {}),
+    ...(typeof value.approved === "string" ? { approved: value.approved } : {}),
+    ...(isStringArray(value.moved) ? { moved: value.moved } : {}),
   };
 }
 

package/src/components/fan-out-run.test.ts

@@ -209,3 +209,38 @@ describe("one approval over the whole set", () => {
     expect(ran.sort()).toEqual(["app-one", "app-three", "app-two", "cluster-b"]);
   });
 });
+
+describe("holding a component back (#3999)", () => {
+  test("a held component and what is downstream of it do not run and settle waiting; independent branches run", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith();
+    const events: Array<{ type: string; component?: string; status?: string }> = [];
+    const asked: Array<[string, string[]]> = [];
+    const result = await runFanOut(plan, ESTATE, registry, {
+      ...opts(),
+      onRunEvent: (e) => events.push(e as never),
+      hold: (name, outputs) => {
+        asked.push([name, Object.keys(outputs).sort()]);
+        return name === "cluster-a" ? "its plan read net.id before that output applied as another value" : undefined;
+      },
+    });
+    expect(result.status).toBe("ok");
+    expect(ran).not.toContain("cluster-a");
+    expect(ran).not.toContain("app-one");
+    expect(ran).toContain("app-three");
+    expect(result.held).toEqual([
+      { component: "cluster-a", reason: "its plan read net.id before that output applied as another value" },
+      { component: "app-one", reason: "its plan read net.id before that output applied as another value", heldBy: "cluster-a" },
+      { component: "app-two", reason: "its plan read net.id before that output applied as another value", heldBy: "cluster-a" },
+    ].sort((a, b) => plan.order.indexOf(a.component) - plan.order.indexOf(b.component)));
+    // Asked once per component as its wave starts, never for one already held.
+    expect(asked.map(([name]) => name).sort()).toEqual(["app-three", "cluster-a", "cluster-b", "net"]);
+    expect(events.filter((e) => e.type === "component-settle" && e.status === "waiting").map((e) => e.component).sort()).toEqual(["app-one", "app-two", "cluster-a"]);
+  });
+
+  test("with no hook, or a hook that holds nothing, the result has no held list", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    expect((await runFanOut(plan, ESTATE, registryWith().registry, opts())).held).toBeUndefined();
+    expect((await runFanOut(plan, ESTATE, registryWith().registry, { ...opts(), hold: () => undefined })).held).toBeUndefined();
+  });
+});