@intentius/chant 0.80.0 → 0.81.0

package/src/cli/handlers/promote.test.ts

@@ -1,5 +1,6 @@
 /**
- * `chant components promote` (#2530), with the ledger, discovery and the
+ * `chant components promote` (#2530), `rollback` (#2531) and `redeploy`
+ * (#2604), with the ledger, discovery and the
  * capability registry replaced by fakes.
  */
 
@@ -66,7 +67,7 @@ vi.mock("../../op/gate", async () => {
 // The run handler pulls in every runtime; the promote needs only its exit code.
 vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
 
-const { runComponentsPromote, runComponentsRollback } = await import("./promote");
+const { runComponentsPromote, runComponentsRollback, runComponentsRedeploy } = await import("./promote");
 
 const api: DriverComponent = {
   name: "api",
@@ -197,6 +198,37 @@ describe("chant components promote", () => {
     expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({ component: "api", env: "prod" });
   });
 
+  test("--digest <component>=<digest> promotes the pinned release, not the latest one (#2602)", async () => {
+    const web: DriverComponent = { ...api, name: "web" };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [api, web] });
+    // Another pipeline recorded sha256:newer after this one recorded sha256:api.
+    readReleaseLedgerMock.mockResolvedValue({
+      records: [staging, { ...staging, digest: "sha256:newer", timestamp: "2026-01-03T00:00:00.000Z", runId: "run-8" }, { ...staging, component: "web" }],
+      malformed: 0,
+    });
+    expect(await runComponentsPromote(ctx({ digests: ["api=sha256:api"] }))).toBe(0);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({
+      component: "api",
+      env: "prod",
+      digest: "sha256:api",
+      promotedFrom: { env: "staging", runId: "run-7" },
+    });
+  });
+
+  test("an empty pinned digest fails and deploys nothing (#2602)", async () => {
+    expect(await runComponentsPromote(ctx({ digests: ["api="] }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--digest api= names no digest/);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("a bare --digest without --component is refused", async () => {
+    expect(await runComponentsPromote(ctx({ digest: "sha256:api", digests: ["sha256:api"] }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/needs --component/);
+    expect(ran).toEqual([]);
+  });
+
   test("a component with no publish step is refused before anything runs", async () => {
     resolveTargetsMock.mockResolvedValue({
       success: true,
@@ -259,3 +291,87 @@ describe("chant components rollback", () => {
     expect(errors.join("\n")).toMatch(/chant approve api rollback-ok/);
   });
 });
+
+describe("chant components redeploy", () => {
+  const prod = (digest: string, timestamp: string, runId: string): ReleaseRecord =>
+    ({ ...staging, env: "prod", digest, timestamp, runId });
+
+  beforeEach(() => {
+    readReleaseLedgerMock.mockResolvedValue({
+      records: [prod("sha256:old", "2026-01-01T00:00:00.000Z", "run-1"), prod("sha256:new", "2026-01-02T00:00:00.000Z", "run-2")],
+      malformed: 0,
+    });
+  });
+
+  const rd = (a: Partial<ParsedArgs>) => ctx({ migrateFrom: undefined, migrateTo: undefined, path: "redeploy", extraPositional: "prod", component: "api", ...a });
+
+  test("an environment and --component are required", async () => {
+    expect(await runComponentsRedeploy(rd({ extraPositional: undefined }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--component <name> are required/);
+    expect(errors.join("\n")).toMatch(/chant components redeploy <env>/);
+  });
+
+  test("redeploys the current release from its recorded digest and records it", async () => {
+    expect(await runComponentsRedeploy(rd({}))).toBe(0);
+    expect(readReleaseLedgerMock).toHaveBeenCalledWith("prod");
+    // Neither a build nor a publish: the environment already has the artifact.
+    expect(ran).toEqual(["prod:apply"]);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    const written = appendReleaseRecordMock.mock.calls[0][0];
+    expect(written).toMatchObject({
+      component: "api",
+      env: "prod",
+      digest: "sha256:new",
+      runId: "run-9",
+      actor: "bob",
+      redeploys: { env: "prod", runId: "run-2", timestamp: "2026-01-02T00:00:00.000Z" },
+    });
+    expect(written).not.toHaveProperty("restores");
+    expect(written).not.toHaveProperty("promotedFrom");
+    expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
+    expect(errors.join("\n")).toMatch(/Redeployed .*api.* in prod at sha256:new/);
+  });
+
+  test("the same digest rollback refuses is the one redeploy accepts", async () => {
+    expect(await runComponentsRollback(rd({ path: "rollback", digest: "sha256:new" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/already the current release/);
+    expect(await runComponentsRedeploy(rd({ digest: "sha256:new" }))).toBe(0);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({ digest: "sha256:new" });
+  });
+
+  test("a --digest other than the current one is refused before anything runs", async () => {
+    expect(await runComponentsRedeploy(rd({ digest: "sha256:old" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/sha256:old is not the current release/);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("--dry-run prints the plan and deploys nothing", async () => {
+    expect(await runComponentsRedeploy(rd({ dryRun: true, json: true }))).toBe(0);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    const plan = JSON.parse(logs.join("\n"));
+    expect(plan).toMatchObject({ from: "prod", to: "prod" });
+    expect(plan.items).toEqual([expect.objectContaining({ component: "api", digest: "sha256:new", notRun: ["docker-build", "publish-image"] })]);
+  });
+
+  test("the environment's gate applies to a redeploy", async () => {
+    const gated: DriverComponent = {
+      ...api,
+      deploy: [...api.deploy.slice(0, 2), { phase: "Apply", steps: [{ kind: "gate", gate: "redeploy-ok" }, { kind: "apply" }] }],
+    };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [gated] });
+    expect(await runComponentsRedeploy(rd({}))).toBe(3);
+    expect(ran).not.toContain("prod:apply");
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(errors.join("\n")).toMatch(/chant approve api redeploy-ok/);
+    expect(errors.join("\n")).toMatch(/then run the same redeploy again/);
+  });
+
+  test("a failed redeploy records nothing and exits 1", async () => {
+    failApplyFor = "api";
+    expect(await runComponentsRedeploy(rd({}))).toBe(1);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(errors.join("\n")).toMatch(/redeploy failed at "api"/);
+  });
+});

package/src/cli/handlers/promote.ts

@@ -1,8 +1,10 @@
 /**
- * `chant components promote --from <env> --to <env>` (#2530) and `chant
- * components rollback <env>` (#2531): deploy digests a release ledger already
- * records, without a build. A promote takes them from another environment's
- * ledger; a rollback takes an earlier release from the environment's own. The
+ * `chant components promote --from <env> --to <env>` (#2530), `chant
+ * components rollback <env>` (#2531) and `chant components redeploy <env>`
+ * (#2604): deploy digests a release ledger already records, without a build.
+ * A promote takes them from another environment's ledger; a rollback takes an
+ * earlier release from the environment's own, and a redeploy the release it
+ * records as current. The
  * mechanism lives in ../../components/promote.ts; these handlers read the
  * ledger, print the plan, run it, and append the release records.
  *
@@ -29,34 +31,39 @@ import { fanOutRegistry } from "../../components/fan-out-support";
 import { renderDriverHuman } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
 import {
+  parseDigestPins,
   planPromotion,
   planRollback,
+  planRedeploy,
   withoutBuildSteps,
   runPromotion,
   promotionRecord,
   rollbackRecord,
+  redeployRecord,
   gateApprover,
   type DeployRunInfo,
   type PromotionItem,
   type PromotionPlan,
 } from "../../components/promote";
 import type { DriverComponent } from "../../components/driver";
-import { writeGatedRunSummary } from "../../op/gate-summary";
-import { approveCommand } from "../../op/gate";
+import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
+import { approveCommand, describeGateMismatch } from "../../op/gate";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { GATED_EXIT_CODE } from "./run";
 import type { CommandContext } from "../registry";
 
 const PROMOTE_USAGE =
-  "chant components promote --from <env> --to <env> [--component <name> [--digest <sha256:...>]] [--dry-run] [--json]";
+  "chant components promote --from <env> --to <env> [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
 const ROLLBACK_USAGE =
   "chant components rollback <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
+const REDEPLOY_USAGE =
+  "chant components redeploy <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
 
-type Verb = "promote" | "rollback";
+type Verb = "promote" | "rollback" | "redeploy";
 
 function renderPlan(verb: Verb, plan: PromotionPlan, removed: Map<string, string[]>): void {
-  console.error(formatBold(verb === "promote" ? `promote ${plan.from} -> ${plan.to}` : `rollback ${plan.to}`));
+  console.error(formatBold(verb === "promote" ? `promote ${plan.from} -> ${plan.to}` : `${verb} ${plan.to}`));
   for (const item of plan.items) {
     console.error(`  ${item.component}  ${item.digest}`);
     console.error(`    released to ${plan.from} at ${item.source.timestamp} (run ${item.source.runId}, git ${item.source.gitSha.slice(0, 12)})`);
@@ -117,9 +124,9 @@ async function readLedger(env: string): Promise<ReleaseRecord[]> {
 }
 
 /**
- * Prepare, run and record a plan. Shared by promote and rollback, which differ
- * only in how the plan was chosen, whether the publish step runs, and which
- * field names the earlier release on the new record.
+ * Prepare, run and record a plan. Shared by promote, rollback and redeploy,
+ * which differ only in how the plan was chosen, whether the publish step runs,
+ * and which field names the earlier release on the new record.
  */
 async function deployPlan(
   ctx: CommandContext,
@@ -135,7 +142,12 @@ async function deployPlan(
   const removed = new Map<string, string[]>();
   const refusals: string[] = [];
   for (const item of plan.items) {
-    const result = withoutBuildSteps(byName.get(item.component)!, verb === "rollback" ? { pinDigest: item.digest } : {});
+    // A rollback and a redeploy deploy a release this environment already
+    // received, so neither runs the publish step.
+    const result = withoutBuildSteps(
+      byName.get(item.component)!,
+      verb === "promote" ? {} : { pinDigest: item.digest, verb: `a ${verb}` },
+    );
     if ("error" in result) refusals.push(result.error);
     else {
       prepared.push(result.component);
@@ -217,7 +229,9 @@ async function deployPlan(
       console.error(formatSuccess(
         verb === "promote"
           ? `Promoted ${formatBold(r.component)} ${plan.from} -> ${plan.to}: ${r.digest}`
-          : `Rolled back ${formatBold(r.component)} in ${plan.to} to ${r.digest}`,
+          : verb === "rollback"
+            ? `Rolled back ${formatBold(r.component)} in ${plan.to} to ${r.digest}`
+            : `Redeployed ${formatBold(r.component)} in ${plan.to} at ${r.digest}`,
       ));
     }
   }
@@ -233,7 +247,11 @@ async function deployPlan(
   if (run.status === "gated" && run.gate) {
     const pending = run.gate;
     console.error(formatWarning({ message: `component "${run.gatedComponent}" is gated on "${pending.gate}" — pending approval` }));
-    console.error(formatInfo(`approve : ${approveCommand(pending.op, pending.gate)}`));
+    // #2574: an approval stands, but for another environment, plan or none.
+    if (run.gateMismatch) {
+      console.error(formatWarning({ message: describeGateMismatch(pending.op, pending.gate, run.gateMismatch) }));
+    }
+    console.error(formatInfo(`approve : ${approveCommand(pending.op, pending.gate, pending.environment)}`));
     console.error(formatInfo(`then run the same ${verb} again`));
     writeGatedRunSummary({
       op: pending.op,
@@ -242,6 +260,8 @@ async function deployPlan(
       expiresAt: pending.expiresAt,
       ...(pending.url ? { url: pending.url } : {}),
       ...(pending.planDigest ? { planDigest: pending.planDigest } : {}),
+      ...(await summaryLedgerPrefix()),
+      ...(pending.environment ? { environment: pending.environment } : {}),
     });
     return GATED_EXIT_CODE;
   }
@@ -280,6 +300,23 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
   const project = await loadProject(ctx, args.component ?? "all");
   if (typeof project === "number") return project;
 
+  // Without --component, each --digest is <component>=<digest> (#2602): a
+  // generated promote job pins every component to the release its own
+  // pipeline run recorded, rather than whatever is latest in --from.
+  const digests = args.digests ?? (args.digest ? [args.digest] : []);
+  let pins: Record<string, string> | undefined;
+  if (!args.component && digests.length > 0) {
+    const parsed = parseDigestPins(digests);
+    if ("error" in parsed) {
+      console.error(formatError({ message: parsed.error, hint: PROMOTE_USAGE }));
+      return 1;
+    }
+    pins = parsed.pins;
+  } else if (args.component && digests.length > 1) {
+    console.error(formatError({ message: "--component takes one --digest", hint: PROMOTE_USAGE }));
+    return 1;
+  }
+
   await fetchLifecycle().catch(() => false);
   const plan = planPromotion({
     from,
@@ -287,7 +324,8 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
     sourceRecords: await readLedger(from),
     declared: project.targets.map((c) => c.name),
     ...(args.component ? { component: args.component } : {}),
-    ...(args.digest ? { digest: args.digest } : {}),
+    ...(args.component && args.digest ? { digest: args.digest } : {}),
+    ...(pins ? { pins } : {}),
   });
   if ("error" in plan) {
     console.error(formatError({ message: plan.error, hint: PROMOTE_USAGE }));
@@ -323,3 +361,31 @@ export async function runComponentsRollback(ctx: CommandContext): Promise<number
   }
   return deployPlan(ctx, "rollback", plan, project, who.actor, rollbackRecord);
 }
+
+export async function runComponentsRedeploy(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const env = args.extraPositional;
+  if (!env || !args.component) {
+    console.error(formatError({ message: "an environment and --component <name> are required", hint: REDEPLOY_USAGE }));
+    return 1;
+  }
+  const who = actorOrRefuse(ctx);
+  if (typeof who === "number") return who;
+
+  const project = await loadProject(ctx, args.component);
+  if (typeof project === "number") return project;
+
+  await fetchLifecycle().catch(() => false);
+  const plan = planRedeploy({
+    env,
+    records: await readLedger(env),
+    declared: project.targets.map((c) => c.name),
+    component: args.component,
+    ...(args.digest ? { digest: args.digest } : {}),
+  });
+  if ("error" in plan) {
+    console.error(formatError({ message: plan.error, hint: REDEPLOY_USAGE }));
+    return 1;
+  }
+  return deployPlan(ctx, "redeploy", plan, project, who.actor, redeployRecord);
+}

package/src/cli/handlers/run-generate-member.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `chant run --generate` inside a workspace member (#2542). Discovery is
+ * stubbed; the lexicon plugins are the real ones.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import type { ParsedArgs } from "../registry";
+import type { OpConfig } from "../../op/types";
+import { twoMemberWorkspace } from "../../workspace/__fixtures__/two-member-workspace";
+
+const discovered = new Map<string, { config: Partial<OpConfig>; filePath: string; exportName: string }>();
+vi.mock("../../op/discover", () => ({
+  discoverOps: async () => ({ ops: discovered, errors: [] }),
+}));
+
+const { runOp } = await import("./run");
+const { generateOpsPipeline } = await import("../../op/generate-pipeline");
+const { parseArgs } = await import("../main");
+
+function ctx(argv: string[]) {
+  return { args: parseArgs(argv) as ParsedArgs, plugins: [], serializers: [] };
+}
+
+let repo: string;
+let cwd: string;
+let logs: string[];
+beforeEach(() => {
+  repo = twoMemberWorkspace();
+  cwd = process.cwd();
+  discovered.clear();
+  discovered.set("nightly-audit", {
+    config: { name: "nightly-audit", phases: [], schedule: { cron: "0 6 * * *" } } as Partial<OpConfig>,
+    filePath: "nightly-audit.op.ts",
+    exportName: "default",
+  });
+  logs = [];
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation((s: string) => {
+    logs.push(s);
+  });
+});
+afterEach(() => {
+  process.chdir(cwd);
+  vi.restoreAllMocks();
+  rmSync(repo, { recursive: true, force: true });
+});
+
+describe("chant run --generate in a workspace member", () => {
+  test("github: the file is named after the member, at the repository root, and recorded", async () => {
+    process.chdir(join(repo, "services/api"));
+    expect(await runOp(ctx(["run", "--generate", "github"]))).toBe(0);
+
+    expect(readdirSync(join(repo, ".github/workflows"))).toEqual(["api-nightly-audit.yml"]);
+    expect(existsSync(join(repo, "services/api/.github"))).toBe(false);
+    const member = { name: "api", dir: "services/api", fileDir: ".github/workflows" };
+    const direct = await generateOpsPipeline([{ name: "nightly-audit" }], "github", { member });
+    const text = readFileSync(join(repo, ".github/workflows/api-nightly-audit.yml"), "utf-8");
+    expect(text).toBe(
+      "# Generated by chant — do not edit directly. Regenerate with: chant run --generate github (in the member's directory)\n" + direct.files![0].yaml,
+    );
+    const record = JSON.parse(readFileSync(join(repo, "services/api/.chant/generated.json"), "utf-8"));
+    expect(record.files).toEqual([{ path: ".github/workflows/api-nightly-audit.yml", command: "chant run --generate github" }]);
+  });
+
+  test("gitlab: the member's file goes in .gitlab/ci", async () => {
+    process.chdir(join(repo, "apps/web"));
+    expect(await runOp(ctx(["run", "--generate", "gitlab"]))).toBe(0);
+    const text = readFileSync(join(repo, ".gitlab/ci/web-ops.gitlab-ci.yml"), "utf-8");
+    expect(text).toContain("web-nightly-audit:");
+    expect(text).toContain("cd apps/web");
+  });
+
+  test("--format json names the member and writes nothing", async () => {
+    process.chdir(join(repo, "services/api"));
+    expect(await runOp(ctx(["run", "--generate", "forgejo", "--format", "json"]))).toBe(0);
+    const out = JSON.parse(logs.join("\n"));
+    expect(out.member).toBe("api");
+    expect(out.files.map((f: { path: string }) => f.path)).toEqual([".forgejo/workflows/api-nightly-audit.yml"]);
+    expect(existsSync(join(repo, ".forgejo"))).toBe(false);
+  });
+});

package/src/cli/handlers/run-generate.test.ts

@@ -86,16 +86,14 @@ describe("chant run --generate <provider>", () => {
     }
   });
 
-  test("each github workflow is named after its Op (#2580); forgejo workflows carry no name", async () => {
+  test("each github (#2580) and forgejo (#2601) workflow is named after its Op", async () => {
     for (const provider of ["github", "forgejo"]) {
       expect(await runOp(ctx(["run", "--generate", provider, "--output", join(dir, provider)]))).toBe(0);
-    }
-    const header = `# ${GENERATED_MARKER}. Regenerate with: chant run --generate github\n`;
-    for (const op of ["nightly-audit", "weekly-report"]) {
-      const github = readFileSync(join(dir, "github", `${op}.yml`), "utf-8");
-      expect(github.startsWith(`${header}name: ${op}\n\non:\n`)).toBe(true);
-      const forgejo = readFileSync(join(dir, "forgejo", `${op}.yml`), "utf-8");
-      expect(forgejo).not.toMatch(/^name:/m);
+      const header = `# ${GENERATED_MARKER}. Regenerate with: chant run --generate ${provider}\n`;
+      for (const op of ["nightly-audit", "weekly-report"]) {
+        const written = readFileSync(join(dir, provider, `${op}.yml`), "utf-8");
+        expect(written.startsWith(`${header}name: ${op}\n\non:\n`)).toBe(true);
+      }
     }
   });
 

package/src/cli/handlers/run-generate.ts

@@ -28,6 +28,7 @@ import { dirname, join, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { generateOpsPipeline } from "../../op/generate-pipeline";
 import { GENERATED_MARKER } from "../../discovery/files";
+import { findWorkspaceRoot } from "../../project-root";
 import type { ComponentPipelineOptions, ScheduledOpSpec } from "../../lexicon";
 import { formatBold, formatError, formatSuccess } from "../format";
 import type { CommandContext } from "../registry";
@@ -104,12 +105,46 @@ export async function runOpGenerate(ctx: CommandContext): Promise<number> {
     }
   }
 
-  const result = await generateOpsPipeline(ops, provider, options);
+  // Inside a workspace member (#2542), the files are the member's: filtered
+  // to its paths, run in its directory, named after it at the repository
+  // root's forge directory, and recorded as its generated files. The
+  // workspace module loads only when a declaration was found.
+  const found = findWorkspaceRoot(process.cwd());
+  let plan: import("../../workspace/member-pipeline").MemberOpPlan | undefined;
+  let memberPipeline: typeof import("../../workspace/member-pipeline") | undefined;
+  if (found) {
+    memberPipeline = await import("../../workspace/member-pipeline");
+    try {
+      plan = memberPipeline.planMemberOpPipelines({ projectDir: process.cwd(), found, provider, output: args.output, specFile: specPath });
+    } catch (err) {
+      console.error(formatError({ message: memberPipeline.describeError(err) }));
+      return 1;
+    }
+  }
+
+  const result = await generateOpsPipeline(ops, provider, plan ? { ...options, member: plan.member } : options);
   if (!result.success) {
     console.error(formatError({ message: result.error ?? "Failed to generate Op pipelines" }));
     return 1;
   }
 
+  if (plan && memberPipeline) {
+    const header = memberPipeline.generatedHeader(plan.command);
+    if (args.format === "json") {
+      const files = (result.files ?? []).map((f) => ({
+        name: f.name,
+        path: memberPipeline.repoRelative(plan.ctx, join(plan.outDir, f.name)),
+        content: header + f.yaml,
+      }));
+      console.log(JSON.stringify({ member: plan.member.name, files, jobs: result.jobs ?? [] }, null, 2));
+      return 0;
+    }
+    for (const path of memberPipeline.writeMemberOpPipelines(plan, result.files ?? [])) {
+      console.error(formatSuccess(`wrote ${formatBold(path)} for member ${formatBold(plan.member.name)}`));
+    }
+    return 0;
+  }
+
   const header = opPipelineHeader(provider, specPath);
   const outDir = args.output ?? DEFAULT_OP_PIPELINE_DIRS[provider] ?? ".";
   const files = (result.files ?? []).map((f) => ({

package/src/cli/handlers/run.test.ts

@@ -1157,6 +1157,53 @@ describe("runOpComponents", () => {
       vi.restoreAllMocks();
     });
 
+    test("--digest-file writes <component>=<digest> for each release the run recorded (#2602)", async () => {
+      runComponentsMock.mockResolvedValue({
+        success: true,
+        selected: ["svc", "infra"],
+        run: {
+          order: ["svc", "infra"],
+          waves: [["svc", "infra"]],
+          results: [
+            { component: "svc", ok: true, status: "ok", records: [] },
+            { component: "infra", ok: true, status: "ok", records: [] },
+          ],
+          ok: true,
+          status: "ok",
+        },
+      });
+      maybeRecordAutoReleaseMock.mockImplementation(async (info: { component: string }) =>
+        info.component === "svc"
+          ? { recorded: true, commit: "a".repeat(40), record: { version: 1, component: "svc", env: "staging", digest: "sha256:abc", gitSha: "x", runId: "local-1", timestamp: "t", actor: "a" } }
+          : { recorded: false, reason: "no-digest" });
+      writeFileSyncMock.mockClear();
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+      const exit = await runOpComponents({ args: makeArgs({ path: "all", env: "staging", digestFile: "out/svc.digest" }), plugins: [], serializers: [] });
+
+      expect(exit).toBe(0);
+      const call = writeFileSyncMock.mock.calls.find(([path]) => String(path).endsWith("out/svc.digest"));
+      expect(call?.[1]).toBe("svc=sha256:abc\n");
+      vi.restoreAllMocks();
+    });
+
+    test("--digest-file is written empty when nothing was recorded (#2602)", async () => {
+      runComponentsMock.mockResolvedValue({
+        success: true,
+        selected: ["svc"],
+        run: { order: ["svc"], waves: [["svc"]], results: [{ component: "svc", ok: true, status: "ok", records: [] }], ok: true, status: "ok" },
+      });
+      maybeRecordAutoReleaseMock.mockResolvedValue({ recorded: false, reason: "opted-out" });
+      writeFileSyncMock.mockClear();
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+      await runOpComponents({ args: makeArgs({ path: "svc", digestFile: "svc.digest" }), plugins: [], serializers: [] });
+
+      const call = writeFileSyncMock.mock.calls.find(([path]) => String(path).endsWith("svc.digest"));
+      expect(call?.[1]).toBe("");
+      vi.restoreAllMocks();
+    });
+
     test("a release-write error is surfaced as a warning but does not change the exit code", async () => {
       runComponentsMock.mockResolvedValue({
         success: true,

package/src/cli/handlers/run.ts

@@ -6,8 +6,8 @@ import { discoverOps } from "../../op/discover";
 import type { OpConfig } from "../../op/types";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { runOpLocally, findPolicyGateStep, OpRunFailure, type StepRecord } from "../../op/local-executor";
-import { approveCommand } from "../../op/gate";
-import { writeGatedRunSummary, type GatedRunSummary } from "../../op/gate-summary";
+import { approveCommand, describeGateMismatch } from "../../op/gate";
+import { summaryLedgerPrefix, writeGatedRunSummary, type GatedRunSummary } from "../../op/gate-summary";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
 import type { OpRuntimeProvider, OpRunStatus } from "../../op/runtime";
 import { renderHuman, renderJson } from "../../op/local-output";
@@ -21,6 +21,7 @@ import { ndjsonProgressSink } from "../../components/run-progress";
 import { maybeRecordAutoRelease } from "../../components/auto-release";
 import { maybePersistBuildManifest } from "../../components/manifest-persistence";
 import type { DriverComponentResult } from "../../components/driver";
+import type { ReleaseRecord } from "../../lifecycle/release-ledger";
 import { runOpGenerate } from "./run-generate";
 
 /**
@@ -588,13 +589,16 @@ export async function runOp(ctx: CommandContext): Promise<number> {
  * ledger for work `chant run --components` records. Each result is filtered on
  * its own `ok`, so a fan-out that partly succeeded records exactly the
  * components that did.
+ *
+ * Returns the records it wrote, for `--digest-file` (#2602).
  */
 export async function recordAutoReleasesForRun(
   results: DriverComponentResult[],
   env: string,
   runId: string,
   disabled: boolean,
-): Promise<void> {
+): Promise<ReleaseRecord[]> {
+  const recorded: ReleaseRecord[] = [];
   for (const componentResult of results) {
     if (!componentResult.ok) continue;
     const outcome = await maybeRecordAutoRelease(
@@ -614,6 +618,7 @@ export async function recordAutoReleasesForRun(
         message: `release record for "${componentResult.component}"@${env} was not recorded: ${outcome.error}`,
       }));
     } else if (outcome.recorded) {
+      recorded.push(outcome.record);
       console.error(formatInfo(
         `Recorded release: ${formatBold(componentResult.component)}@${env} -> ${outcome.record.digest} (commit ${outcome.commit.slice(0, 7)})`,
       ));
@@ -633,6 +638,7 @@ export async function recordAutoReleasesForRun(
       ));
     }
   }
+  return recorded;
 }
 
 // ── chant run --components <name|all> ────────────────────────────────────────
@@ -760,7 +766,12 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     console.error(formatWarning({
       message: `component "${result.gated.component}" is gated on "${gate.gate}" — pending approval`,
     }));
-    console.error(formatInfo(`approve : ${approveCommand(gate.op, gate.gate)}`));
+    // #2574: an approval stands, but for another plan or for none. Say so,
+    // with the command that replaces it.
+    if (result.gated.mismatch) {
+      console.error(formatWarning({ message: describeGateMismatch(gate.op, gate.gate, result.gated.mismatch) }));
+    }
+    console.error(formatInfo(`approve : ${approveCommand(gate.op, gate.gate, gate.environment)}`));
     if (gate.url) console.error(formatInfo(`approve at: ${gate.url}`));
     console.error(formatInfo(`expires : ${gate.expiresAt}`));
     // #2310: this run's own append reached only the local chant/lifecycle
@@ -782,6 +793,8 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
         ...(gate.url ? { url: gate.url } : {}),
         ...(result.gated.pushed === false ? { pushed: false, pushWarning: result.gated.pushWarning } : {}),
         ...(gate.planDigest ? { planDigest: gate.planDigest } : {}),
+        ...(await summaryLedgerPrefix()),
+        ...(gate.environment ? { environment: gate.environment } : {}),
       },
       gatedExit,
     );
@@ -790,7 +803,16 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
 
   if (result.success && result.run) {
     const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord);
-    await recordAutoReleasesForRun(result.run.results, env, `local-${Date.now()}`, disabled);
+    const recorded = await recordAutoReleasesForRun(result.run.results, env, `local-${Date.now()}`, disabled);
+    // `--digest-file` (#2602): the releases this run recorded, one
+    // `<component>=<digest>` line each, the form `chant components promote
+    // --digest` takes. A generated promote job reads it to promote exactly
+    // what this job built, not whatever is latest in the environment.
+    if (ctx.args.digestFile) {
+      const digestPath = resolve(ctx.args.digestFile);
+      mkdirSync(dirname(digestPath), { recursive: true });
+      writeFileSync(digestPath, recorded.map((r) => `${r.component}=${r.digest}\n`).join(""));
+    }
   }
 
   return result.success ? 0 : 1;
@@ -903,6 +925,7 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
               ? { pushed: false, pushWarning: status.result.gatePushWarning }
               : {}),
             ...(pending?.planDigest ? { planDigest: pending.planDigest } : {}),
+            ...(await summaryLedgerPrefix()),
           },
           gatedExit,
         );