@intentius/chant 0.80.0 → 0.81.0

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

@@ -23,6 +23,7 @@ const awsEmulatorStub = {
 const getHeadCommitMock = vi.fn();
 const fetchLifecycleMock = vi.fn();
 const pushLifecycleMock = vi.fn();
+const readSnapshotMock = vi.fn();
 
 const appendReleaseRecordMock = vi.fn();
 const readReleaseLedgerMock = vi.fn();
@@ -38,6 +39,8 @@ vi.mock("../../lifecycle/git", () => ({
   getHeadCommit: (...args: unknown[]) => getHeadCommitMock(...args),
   fetchLifecycle: (...args: unknown[]) => fetchLifecycleMock(...args),
   pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+  readSnapshot: (...args: unknown[]) => readSnapshotMock(...args),
+  snapshotStorageKey: (lexicon: string, stack?: string) => (stack ? `${stack}__${lexicon}` : lexicon),
   StaleLifecycleBranchError: class StaleLifecycleBranchError extends Error {},
 }));
 
@@ -125,6 +128,7 @@ describe("components handlers", () => {
     getHeadCommitMock.mockReset().mockResolvedValue("abc123headsha");
     fetchLifecycleMock.mockReset().mockResolvedValue(true);
     pushLifecycleMock.mockReset().mockResolvedValue(true);
+    readSnapshotMock.mockReset().mockResolvedValue(null);
     appendReleaseRecordMock.mockReset();
     readReleaseLedgerMock.mockReset().mockResolvedValue({ records: [], malformed: 0 });
     listReleaseEnvironmentsMock.mockReset().mockResolvedValue([]);
@@ -567,6 +571,129 @@ describe("components handlers", () => {
       });
     });
 
+    // #2513: `--live` could never report `drifted` — the change set was built
+    // with no prior observation, so a live, declared entity was always `noop`,
+    // and nothing compared the live identity with the recorded release. These
+    // go through the handler end to end with a fake lexicon.
+    describe("drifted (#2513)", () => {
+      const released = {
+        version: 1,
+        component: "svc",
+        env: "prod",
+        digest: "sha256:released",
+        gitSha: "1111111aaaaaaa",
+        runId: "run-1",
+        timestamp: "2026-02-01T00:00:00.000Z",
+        actor: "alice",
+      };
+
+      async function statusRow(
+        resources: Record<string, ResourceMetadata>,
+        opts: { snapshot?: { timestamp: string; resources: Record<string, ResourceMetadata> }; failRead?: boolean } = {},
+      ) {
+        readReleaseLedgerMock.mockResolvedValue({ records: [released], malformed: 0 });
+        buildMock.mockResolvedValue(makeBuildResult({ aws: ["svc"] }));
+        readSnapshotMock.mockImplementation(async (env: string, key: string) =>
+          opts.snapshot && env === "prod" && key === "aws"
+            ? JSON.stringify({ lexicon: "aws", environment: "prod", commit: "c", ...opts.snapshot })
+            : null,
+        );
+        const plugins: LexiconPlugin[] = [
+          createMockPlugin({
+            name: "aws",
+            emulator: awsEmulatorStub,
+            describeResources: opts.failRead
+              ? async () => { throw new Error("credentials expired"); }
+              : staticDescribeResources(resources),
+          }),
+        ];
+        stdoutBuf.length = 0;
+        const exit = await runComponentsStatus({
+          args: makeArgs({ extraPositional: "prod", live: true, json: true }),
+          plugins,
+          serializers: plugins.map((p) => p.serializer),
+        });
+        expect(exit).toBe(0);
+        return JSON.parse(stdoutBuf.join(""))[0];
+      }
+
+      test("reconciled: live identity matches the recorded digest and git sha", async () => {
+        const row = await statusRow({ svc: meta({ attributes: { digest: "sha256:released", gitSha: "1111111" } }) });
+        expect(row).toMatchObject({ component: "svc", reconciliation: "reconciled", live: true });
+      });
+
+      test("drifted: live resource reports a digest other than the recorded one", async () => {
+        const row = await statusRow({ svc: meta({ attributes: { digest: "sha256:foreign" } }) });
+        expect(row).toMatchObject({ component: "svc", reconciliation: "drifted", live: true });
+        expect(row.detail).toContain("sha256:foreign");
+      });
+
+      test("drifted: live resource reports a different git sha", async () => {
+        const row = await statusRow({ svc: meta({ attributes: { gitSha: "2222222bbbbbbb" } }) });
+        expect(row).toMatchObject({ reconciliation: "drifted" });
+        expect(row.detail).toContain("2222222bbbbbbb");
+      });
+
+      test("drifted: live attributes changed since a snapshot taken after the release", async () => {
+        const row = await statusRow(
+          { svc: meta({ attributes: { revision: "7" } }) },
+          { snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta({ attributes: { revision: "6" } }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "drifted" });
+        expect(row.detail).toContain("attributes.revision");
+      });
+
+      test("drifted: chant's ownership marker disappeared since a post-release snapshot", async () => {
+        const row = await statusRow(
+          { svc: meta({ ownership: "foreign" }) },
+          { snapshot: { timestamp: "2026-02-02T00:00:00.000Z", resources: { svc: meta({ ownership: "owned" }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "drifted" });
+        expect(row.detail).toContain("ownership marker");
+      });
+
+      test("reconciled: a snapshot older than the release does not attribute the release's own change to drift", async () => {
+        const row = await statusRow(
+          { svc: meta({ attributes: { revision: "7" } }) },
+          { snapshot: { timestamp: "2026-01-15T00:00:00.000Z", resources: { svc: meta({ attributes: { revision: "6" } }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "reconciled" });
+      });
+
+      test("reconciled: unchanged since the snapshot, and no identity reported (no identity is not drift)", async () => {
+        const row = await statusRow(
+          { svc: meta() },
+          { snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta() } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "reconciled" });
+      });
+
+      test("stale: recorded, and the provider confirmed nothing live", async () => {
+        const row = await statusRow(
+          {},
+          { snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta({ attributes: { digest: "sha256:foreign" } }) } } },
+        );
+        expect(row).toMatchObject({ reconciliation: "stale", live: false });
+      });
+
+      test("unknown: a failed read is never drifted, whatever the snapshot says", async () => {
+        const row = await statusRow(
+          {},
+          {
+            failRead: true,
+            snapshot: { timestamp: "2026-02-01T00:05:00.000Z", resources: { svc: meta({ attributes: { digest: "sha256:foreign" } }) } },
+          },
+        );
+        expect(row).toMatchObject({ reconciliation: "unknown" });
+        expect(row).not.toHaveProperty("live");
+      });
+
+      test("reads the same unstacked snapshot `lifecycle plan` reads", async () => {
+        await statusRow({ svc: meta() });
+        expect(readSnapshotMock).toHaveBeenCalledWith("prod", "aws");
+      });
+    });
+
     test("reports malformed ledger lines as a warning without failing", async () => {
       readReleaseLedgerMock.mockResolvedValue({ records: [], malformed: 2 });
       const ctx = { args: makeArgs({ extraPositional: "prod" }), plugins: [], serializers: [] };

package/src/cli/handlers/components.ts

@@ -28,7 +28,8 @@
  */
 import { resolve, join, dirname } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { getHeadCommit, fetchLifecycle, pushLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { getHeadCommit, fetchLifecycle, pushLifecycle, readSnapshot, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
+import type { LifecycleSnapshot } from "../../lifecycle/types";
 import {
   appendReleaseRecord,
   readReleaseLedger,
@@ -37,7 +38,7 @@ import {
   resolveRunId,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
-import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
+import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence, type EntityLiveRead } from "../../lifecycle/status";
 import { commandBuildParams } from "../build-params-cli";
 import { buildChangeSet } from "../../lifecycle/change-set";
 import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
@@ -51,11 +52,12 @@ import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import type { LexiconPlugin } from "../../lexicon";
+import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import { normalizeObservation, mergeObservations, unobservedAll, type NormalizedObservation } from "../../observation";
 import type { Phase, Component } from "../../components/component";
 import { deployUnits } from "../../components/deploy-units";
 import { sortedJsonReplacer } from "../../utils";
+import { withoutReadFlags } from "../../lifecycle/legacy-digest";
 
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
@@ -276,7 +278,8 @@ export async function runComponentsExport(ctx: CommandContext): Promise<number>
     }
   }
 
-  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(manifest, sortedJsonReplacer, 2));
+  // The exported manifest is the recorded one; read-side flags (#2514) stay out of it.
+  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(withoutReadFlags(manifest), sortedJsonReplacer, 2));
 
   const missing = results.filter((r) => r.status === "missing");
 
@@ -284,6 +287,7 @@ export async function runComponentsExport(ctx: CommandContext): Promise<number>
     console.log(JSON.stringify({
       component: manifest.component,
       manifestDigest: manifest.manifestDigest,
+      ...(manifest.flags ? { flags: manifest.flags } : {}),
       outDir: targetDir,
       entries: results,
     }, null, 2));
@@ -318,6 +322,7 @@ interface StatusJsonRow {
     runId: string;
     timestamp: string;
     actor: string;
+    flags?: string[];
   } | null;
   build: {
     manifestDigest: string;
@@ -464,6 +469,42 @@ async function observeComponentStacks(
   return evidence;
 }
 
+/**
+ * The last lifecycle snapshot(s) for one lexicon, as `components status --live`
+ * reads them for its drift baseline (#2513). Reads the stack-keyed snapshot for
+ * each stack the status read targets and the unstacked one `lifecycle plan`
+ * reads, merging resources (a stack's own snapshot wins) and remembering, per
+ * entity, which snapshot's timestamp it came from. A missing or unreadable
+ * snapshot is no baseline, never an error: with none, nothing can have changed
+ * since, and the status falls back to identity and presence.
+ */
+async function readStatusBaseline(
+  environment: string,
+  lexicon: string,
+  stacks: Array<string | undefined>,
+): Promise<{ resources: Record<string, ResourceMetadata> | undefined; timestamps: Map<string, string> }> {
+  const keys = [...new Set([...stacks.filter((s): s is string => !!s).map((s) => snapshotStorageKey(lexicon, s)), snapshotStorageKey(lexicon)])];
+  let resources: Record<string, ResourceMetadata> | undefined;
+  const timestamps = new Map<string, string>();
+  for (const key of keys) {
+    let snap: LifecycleSnapshot | undefined;
+    try {
+      const content = await readSnapshot(environment, key);
+      snap = content ? (JSON.parse(content) as LifecycleSnapshot) : undefined;
+    } catch {
+      snap = undefined;
+    }
+    if (!snap?.resources) continue;
+    resources ??= {};
+    for (const [name, meta] of Object.entries(snap.resources)) {
+      if (Object.prototype.hasOwnProperty.call(resources, name)) continue;
+      resources[name] = meta;
+      if (snap.timestamp) timestamps.set(name, snap.timestamp);
+    }
+  }
+  return { resources, timestamps };
+}
+
 export async function runComponentsStatus(ctx: CommandContext): Promise<number> {
   const { args, plugins, serializers } = ctx;
   const requestedEnv = args.extraPositional;
@@ -554,6 +595,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
         for (const stack of config.stacks ?? []) componentStackNames.add(stack.name);
         const readTargets: Array<string | undefined> = componentStackNames.size ? [...componentStackNames] : [undefined];
         const merged: { env: string; entries: import("../../lifecycle/change-set").ChangeSetEntry[] } = { env: environment, entries: [] };
+        const observations = new Map<string, EntityLiveRead>();
         for (const plugin of plugins) {
           if (!plugin.describeResources) continue;
           const declared = new Set<string>();
@@ -593,15 +635,29 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
             console.error(formatWarning({ message: `${plugin.name}: describeResources failed — ${message} (components in this lexicon report unknown, not stale)` }));
             observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {}, sources: {}, notes: [] };
           }
+          // The last lifecycle snapshot is the prior observation drift is
+          // measured against (#2513) — the same one `lifecycle plan` reads, so
+          // `drifted` here means what `update` means there. Without it every
+          // live, declared entity classified `noop` and `drifted` could not be
+          // reached. Each entity remembers its snapshot's timestamp so the
+          // status join can ignore a change made before the release.
+          const baseline = await readStatusBaseline(environment, plugin.name, readTargets);
           const cs = buildChangeSet(environment, {
             declared,
             observedNow: observed.resources,
-            observedThen: undefined,
+            observedThen: baseline.resources,
             unobserved: observed.unobserved,
           }, { lexicon: plugin.name });
           merged.entries.push(...cs.entries);
+          for (const entry of cs.entries) {
+            observations.set(entry.name, {
+              now: observed.resources[entry.name],
+              then: baseline.resources?.[entry.name],
+              thenAt: baseline.timestamps.get(entry.name),
+            });
+          }
         }
-        liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping);
+        liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping, { observations });
 
         // Multi-stack component projects (each component owns its own stack) are
         // invisible to the entity-keyed, single-stack `describeResources` above —
@@ -652,6 +708,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
               runId: row.recorded.runId,
               timestamp: row.recorded.timestamp,
               actor: row.recorded.actor,
+              ...(row.recorded.flags ? { flags: row.recorded.flags } : {}),
             }
           : null,
         build: row.build
@@ -729,14 +786,19 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
       row.env.padEnd(12) +
       digestShort.padEnd(20) +
       row.reconciliation.padEnd(14) +
-      row.detail,
+      row.detail +
+      (row.recorded?.flags?.length ? ` [${row.recorded.flags.join(", ")}]` : ""),
     );
   }
 
   if (comparisons) {
     console.log(`\n${formatBold(`Cross-check: ${requestedEnv} vs ${args.compareTo}`)}`);
     for (const c of comparisons) {
-      const verdict = c.same ? "same build" : "DIFFERENT builds";
+      const verdict = c.same
+        ? "same build"
+        : c.mixedDigestForms
+          ? "different digests, one recorded before real SHA-256 (legacy-digest), so this cannot tell"
+          : "DIFFERENT builds";
       console.log(`  ${c.component}: ${c.digestA ?? "(none)"} vs ${c.digestB ?? "(none)"} — ${verdict}`);
     }
   }

package/src/cli/handlers/dev.ts

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import { formatError, formatSuccess } from "../format";
+import { formatError, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runDevGenerate(ctx: CommandContext): Promise<number> {
@@ -34,8 +34,10 @@ export async function runDevOnboard(ctx: CommandContext): Promise<number> {
 
   const { onboardCommand, printOnboardResult } = await import("../commands/onboard");
   // chant#2578 — so a lexicon the project declares by path is recognised.
-  const { recordProjectLexicons } = await import("../plugins");
-  await recordProjectLexicons(process.cwd());
+  // chant#2591 — read without running chant.config.ts.
+  const { recordProjectLexicons, unknownPathLexiconsNotice } = await import("../plugins");
+  const notice = unknownPathLexiconsNotice(recordProjectLexicons(process.cwd()));
+  if (notice !== undefined) console.error(formatWarning({ message: notice }));
   const result = onboardCommand({ name, verbose: ctx.args.verbose });
   await printOnboardResult(result, name);
   return result.success ? 0 : 1;

package/src/cli/handlers/fan-out.ts

@@ -43,7 +43,8 @@ import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
 import { runFanOut } from "../../components/fan-out-run";
 import { renderFanOutHuman, renderFanOutJson, renderFanOutPlan } from "../../components/fan-out-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
-import { writeGatedRunSummary } from "../../op/gate-summary";
+import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
+import { approveCommand } from "../../op/gate";
 import { remainingFanOut, type ChangedUnits, type FanOutProgress } from "../../components/fan-out";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
@@ -320,7 +321,11 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
 
   if (result.status === "gated" && result.gate) {
     const pending = result.gate;
-    console.error(formatInfo(`approve : chant approve ${pending.op} ${pending.gate} --plan ${result.plan.digest}`));
+    // The pending fact's own plan: the fan-out's digest for the gate over the
+    // set, or a component's plan and environment for a gate inside one (#2574).
+    console.error(formatInfo(
+      `approve : ${approveCommand(pending.op, pending.gate, pending.environment)} --plan ${pending.planDigest ?? result.plan.digest}`,
+    ));
     writeGatedRunSummary({
       op: pending.op,
       gate: pending.gate,
@@ -328,6 +333,8 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       expiresAt: pending.expiresAt,
       ...(pending.url ? { url: pending.url } : {}),
       ...(pending.planDigest ? { planDigest: pending.planDigest } : {}),
+      ...(await summaryLedgerPrefix()),
+      ...(pending.environment ? { environment: pending.environment } : {}),
     });
     return GATED_EXIT_CODE;
   }

package/src/cli/handlers/init.ts

@@ -1,9 +1,11 @@
-import { formatError } from "../format";
+import { formatError, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runInit(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 
+  if (args.migrateFrom !== undefined) return runInitFrom(ctx);
+
   if (!args.lexicon) {
     console.error(formatError({
       message: "Missing --lexicon flag",
@@ -47,3 +49,54 @@ export async function runInitLexicon(ctx: CommandContext): Promise<number> {
   await printInitLexiconResult(result);
   return result.success ? 0 : 1;
 }
+
+/**
+ * `chant init --from <repo>@<ref>[#<member>] [--param <name>=<value>]... [path]`
+ * (#2540, #2627): copy a template repository at a ref, substitute the
+ * parameters its `chant.template.json` declares, and record its lineage.
+ * The template brings its own lexicons and configuration, so `--lexicon` and
+ * `--template` do not apply.
+ */
+async function runInitFrom(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const usage = "Usage: chant init --from <repo>@<ref>[#<member>] [--param <name>=<value>]... [path]";
+  if (!args.migrateFrom) {
+    console.error(formatError({ message: "--from needs a template: <repo>@<ref>[#<member>]", hint: usage }));
+    return 1;
+  }
+  if (args.lexicon || args.template) {
+    console.error(formatError({ message: "--from cannot be combined with --lexicon or --template", hint: usage }));
+    return 1;
+  }
+  if (args.paramsFile) {
+    console.error(formatError({ message: "--params-file does not apply to init --from; pass each value with --param <name>=<value>", hint: usage }));
+    return 1;
+  }
+  const { parseParamArgs } = await import("../../workspace/template-manifest");
+  let params: Record<string, string>;
+  try {
+    params = parseParamArgs(args.param ?? []);
+  } catch (err) {
+    console.error(formatError({ message: (err as Error).message, hint: usage }));
+    return 1;
+  }
+  const { initFromCommand } = await import("../../workspace/lineage-init");
+  const result = await initFromCommand({
+    from: args.migrateFrom,
+    path: args.path === "." ? undefined : args.path,
+    force: args.force,
+    params,
+  });
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? "init --from failed", hint: usage }));
+    return 1;
+  }
+  for (const warning of result.warnings) console.error(formatWarning({ message: warning }));
+  console.log(formatSuccess("Created:"));
+  for (const file of result.createdFiles) console.log(`  ${file}`);
+  console.log("");
+  console.log(`Lineage: ${result.spec!.id} at ${result.spec!.ref} (${result.commit!.slice(0, 12)}), recorded in .chant/workspace.lock.json`);
+  const parameters = Object.entries(result.parameters ?? {});
+  if (parameters.length > 0) console.log(`Parameters: ${parameters.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(", ")}`);
+  return 0;
+}

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

@@ -897,6 +897,74 @@ describe("runApprove — the resolution names the plan it approves (#2300)", ()
   });
 });
 
+/**
+ * #2574 — a component's gate ledger holds every environment's pending facts.
+ * The approval records the environment it answers, and `--env` picks it.
+ */
+describe("runApprove — a component gate approval names its environment (#2574)", () => {
+  const PLAN_STAGING = `sha256:${"c".repeat(64)}`;
+  const PLAN_PROD = `sha256:${"d".repeat(64)}`;
+  function seedTwoEnvironments(): void {
+    readGateLedgerMock.mockResolvedValue({
+      resolutions: [],
+      pending: [
+        {
+          version: 1, kind: "pending", op: "search-service", gate: "release",
+          timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z",
+          planDigest: PLAN_STAGING, environment: "staging",
+        },
+        {
+          version: 1, kind: "pending", op: "search-service", gate: "release",
+          timestamp: "2026-01-02T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z",
+          planDigest: PLAN_PROD, environment: "prod",
+        },
+      ],
+      malformed: 0,
+    });
+    appendGateResolutionMock.mockImplementation(async (input: object) => ({ commit: "sha", record: { version: 1, ...input } }));
+  }
+
+  test("without --env it approves the newest pending fact and records its environment", async () => {
+    seedTwoEnvironments();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "search-service", extraPositional: "release", actor: "alex" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ planDigest: PLAN_PROD, environment: "prod" }));
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain(`approves the plan ${PLAN_PROD} in environment "prod"`);
+    errSpy.mockRestore();
+  });
+
+  test("--env picks that environment's pending fact", async () => {
+    seedTwoEnvironments();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "search-service", extraPositional: "release", actor: "alex", env: "staging" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ planDigest: PLAN_STAGING, environment: "staging" }));
+    errSpy.mockRestore();
+  });
+
+  test("--env with no pending fact there refuses and writes nothing", async () => {
+    seedTwoEnvironments();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "search-service", extraPositional: "release", actor: "alex", env: "dev" }))).toBe(1);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain('no pending fact in environment "dev"');
+    errSpy.mockRestore();
+  });
+
+  test("--env is ignored for a gate whose pending facts record no environment", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockImplementation(async (input: object) => ({ commit: "sha", record: { version: 1, ...input } }));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", env: "prod" }))).toBe(0);
+    expect(appendGateResolutionMock.mock.calls[0][0]).toMatchObject({ planDigest: PLAN_A });
+    expect(appendGateResolutionMock.mock.calls[0][0]).not.toHaveProperty("environment");
+    errSpy.mockRestore();
+  });
+});
+
 describe("runApprove — the ledger branch is read before it is appended to (#2303)", () => {
   test("reads the branch before recording the resolution", async () => {
     seedPending("fountain-apply", "rollout-gate", PLAN_A);

package/src/cli/handlers/operator.ts

@@ -44,7 +44,7 @@ import {
   type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
 } from "../../op/gate-approval";
 import { approverOf, tallyGateApprovals } from "../../op/gate";
-import { FAN_OUT_GATE_OP } from "../../op/gate-name";
+import { FAN_OUT_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
 import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
@@ -689,7 +689,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(
       opName === FAN_OUT_GATE_OP
         ? `The next \`chant components fan-out\` decides this gate from scratch and records a fresh pending fact.`
-        : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
+        : opName === WORKSPACE_UPGRADE_GATE_OP
+          ? `The next \`chant workspace upgrade ${gate}\` decides this gate from scratch and records a fresh pending fact.`
+          : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
     ));
     return 0;
   }
@@ -703,6 +705,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     note: ctx.args.note,
     url: ctx.args.url,
     plan: ctx.args.plan,
+    ...(ctx.args.env !== undefined ? { environment: ctx.args.env } : {}),
     allowSameOrigin: ctx.args.allowSameOrigin,
     ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
     ...(ctx.args.agent ? { agent: true } : {}),
@@ -713,7 +716,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     `This records the resolution as a fact; it does not itself re-run anything. ` +
       (opName === FAN_OUT_GATE_OP
         ? `Repeat the \`chant components fan-out\` command and it walks through gate "${gate}".`
-        : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`),
+        : opName === WORKSPACE_UPGRADE_GATE_OP
+          ? `Repeat \`chant workspace upgrade ${gate}\` with the same target, and it applies the patch this approval names.`
+          : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`),
   ));
   return 0;
 }
@@ -747,6 +752,13 @@ export interface GateApprovalOptions {
    * stays one command: run, read what it planned, approve it.
    */
   plan?: string;
+  /**
+   * `--env <env>` (#2574) — which environment's pending fact a component gate
+   * approval answers. A component's gate ledger holds every environment's
+   * facts, so without it the newest one is approved. Ignored for a gate whose
+   * pending facts record no environment (every Op gate).
+   */
+  environment?: string;
   /** `--role` (#2508) — roles the approver claims. */
   roles?: string[];
   /**
@@ -786,7 +798,7 @@ export async function recordGateApproval(
   // `fan-out` is the op name every `chant components fan-out` gate is recorded
   // under (../handlers/fan-out.ts). It is a command rather than a declaration,
   // so there is no `*.op.ts` to find and nothing is wrong when none is there.
-  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP) {
+  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP) {
     console.error(formatWarning({
       message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
     }));
@@ -826,6 +838,18 @@ export async function recordGateApproval(
   // third fallback: approving with no plan in sight is the behaviour
   // INTENTIUS/choudoufu#1026 measured, where the resolution authorised the
   // next run rather than anything anyone had seen.
+  // #2574: a component gate's pending facts carry the environment they were
+  // recorded in, and an approval answers one environment. `--env` picks it;
+  // without it, the newest standing fact decides, and the success line below
+  // names the environment it chose.
+  const ledgerBefore = await readGateLedger(opName);
+  const pendingFor = (all: PendingGateRecord[]): PendingGateRecord[] => {
+    const bound = all.some((p) => p.gate === gate && p.environment !== undefined);
+    return bound && opts.environment !== undefined ? all.filter((p) => p.environment === opts.environment) : all;
+  };
+  const standing = latestPendingGate(pendingFor(ledgerBefore.pending), gate);
+  const environment = standing?.environment;
+
   let planDigest: string | undefined;
   if (opts.plan !== undefined) {
     if (!isPlanDigest(opts.plan)) {
@@ -837,10 +861,12 @@ export async function recordGateApproval(
     }
     planDigest = opts.plan;
   } else {
-    const standing = latestPendingGate((await readGateLedger(opName)).pending, gate);
     if (!standing) {
       console.error(formatError({
-        message: `Gate "${gate}" on "${opName}" has no pending fact, so there is no plan to approve`,
+        message:
+          opts.environment !== undefined && ledgerBefore.pending.some((p) => p.gate === gate && p.environment !== undefined)
+            ? `Gate "${gate}" on "${opName}" has no pending fact in environment "${opts.environment}", so there is no plan to approve`
+            : `Gate "${gate}" on "${opName}" has no pending fact, so there is no plan to approve`,
         hint:
           `Run \`chant run ${opName}\` first — it plans, stops at the gate, and records the plan this ` +
           `approval would be for. To approve a plan you already have the digest for, pass ` +
@@ -859,7 +885,7 @@ export async function recordGateApproval(
   // the way #2300 refuses a plan nobody approved.
   const origin = opts.origin ?? currentGateOrigin();
   const ledger = await readGateLedger(opName);
-  const standingForOrigin = latestPendingGate(ledger.pending, gate);
+  const standingForOrigin = latestPendingGate(pendingFor(ledger.pending), gate);
   const refusal = sameOriginRefusal(standingForOrigin?.origin, origin);
   if (refusal && !opts.allowSameOrigin) {
     console.error(formatError({
@@ -935,6 +961,7 @@ export async function recordGateApproval(
     ...(opts.note ? { note: opts.note } : {}),
     ...(url ? { url } : {}),
     ...(planDigest !== undefined ? { planDigest } : {}),
+    ...(environment !== undefined ? { environment } : {}),
     origin,
     ...(refusal && opts.allowSameOrigin ? { sameOriginOverride: true } : {}),
   });
@@ -950,8 +977,9 @@ export async function recordGateApproval(
   ));
   if (record.planDigest) {
     console.error(formatInfo(
-      `This approves the plan ${record.planDigest}, and only that plan. A run whose fresh plan ` +
-        "differs refuses rather than applying it.",
+      `This approves the plan ${record.planDigest}` +
+        (record.environment !== undefined ? ` in environment "${record.environment}"` : "") +
+        ", and only that plan. A run whose fresh plan differs refuses rather than applying it.",
     ));
   }
   if (approval) {