@intentius/chant 0.124.27 → 0.124.29

package/src/cli/handlers/intent-trace.e2e.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The why chain of `graph --intent` (#4023), from work item to production
+ * release. Everything runs in a temp repo with no remote, so nothing is
+ * pushed: a workspace with a work item, a commit whose trailer links it, a
+ * green tag, a real cut, a real `components promote --release` into prod that
+ * stops at its release gate, a real `chant approve`, and the promote that
+ * follows. Only the capability registry is replaced, so no deploy step
+ * reaches a cloud, and the member's graph, so the resource node resolves to
+ * its component file without building the member.
+ */
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CapabilityRegistry, type DeployContext } from "../../components/capability";
+import type { DriverComponent } from "../../components/driver";
+import type { ParsedArgs } from "../registry";
+import { appendReleaseRecord, readReleaseLedger } from "../../lifecycle/release-ledger";
+import { readGateLedger } from "../../lifecycle/gate-ledger";
+import { cutRelease } from "../../lifecycle/release-cut";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+import { contract, REPO } from "../../workspace/__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument } from "../../workspace/intent";
+import intentSchema from "../../workspace/intent.schema.json";
+import type { ReleaseArtifact } from "../../lifecycle/release-store";
+import type { CompiledTarget, TargetCompiler } from "../../components/release-compile";
+
+const DIGEST = `sha256:${"0123456789abcdef".repeat(4)}`;
+
+const api: DriverComponent = {
+  name: "api",
+  deploy: [
+    { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+    { phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply", template: "dist/api.template.json", imageRef: "@Publish.digest" }] },
+  ],
+};
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+vi.mock("../../components/cli-support", () => ({
+  isComponentList: () => false,
+  resolveComponentTargets: async () => ({ success: true, targets: [api] }),
+}));
+vi.mock("../../components/fan-out-support", () => ({
+  fanOutRegistry: async () => {
+    const registry = new CapabilityRegistry();
+    registry.register({ kind: "publish-image", async run(_ctx: DeployContext) { return { digest: DIGEST, uri: `reg/api@${DIGEST}` }; } } as never);
+    registry.register({ kind: "apply", async run() { return {}; } } as never);
+    return registry;
+  },
+}));
+vi.mock("../../op/discover", () => ({ discoverOps: async () => ({ errors: [], ops: new Map() }) }));
+vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
+
+const { runComponentsPromote } = await import("./promote");
+const { recordGateApproval } = await import("./approve");
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/** A compiler that compiles each environment to its own template and builds one image. */
+const compiler: TargetCompiler = {
+  async compile(env): Promise<CompiledTarget> {
+    return {
+      env,
+      params: [],
+      components: ["api"],
+      buildSteps: { api: [{ kind: "docker-build", context: "api", into: "api.tar" }] },
+      buildInputs: { api: ["api"] },
+      componentFiles: { api: "api.component.ts" },
+      templates: [{ component: "api", path: "dist/api.template.json", content: `{"env":"${env}"}\n` }],
+    };
+  },
+  async buildArtifacts(_env, components): Promise<ReleaseArtifact[]> {
+    return components.map((c) => ({ component: c, kind: "image" as const, path: `${c}.tar`, digest: DIGEST }));
+  },
+};
+
+function args(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "components", path: "promote", format: "", fix: false, watch: false, verbose: false, help: false, live: false,
+    migrateFrom: "staging", migrateTo: "prod", actor: "bob", runId: "run-9", ...overrides,
+  } as ParsedArgs;
+}
+const ctx = (a: Partial<ParsedArgs>) => ({ args: args(a), plugins: [] }) as never;
+
+const REF = join(REPO, "reference-workspace");
+const KIND_FILES: Record<string, string> = {
+  "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+  "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+  "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+  "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+};
+const W001 = `---\n${JSON.stringify({ schema: 1, id: "W-001", title: "Ship the api to prod", state: "open", implements: [], needs: [], constrains: ["path:api.component.ts"], evidence: [], opened_on: "2026-10-16", supersedes: [] }, null, 2)}\n---\n\n# W-001\n`;
+const DECLARATION = JSON.stringify({ name: "shop", schema: 1, members: [{ name: "api", dir: ".", kind: "other", because: "the api and its component" }] });
+const intent = contract(intentSchema);
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+describe("the why chain from work item to production release (#4023)", () => {
+  const cwd = process.cwd();
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+    vi.restoreAllMocks();
+  });
+
+  test(
+    "the trace from the api's resource node walks W-001, the linked commit, its green tag, the cut, the release gate approval and the prod deploy",
+    async () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      await withTestDir(async (dir) => {
+        git(dir, "init", "-q", "-b", "main");
+        git(dir, "config", "user.email", "t@chant.dev");
+        git(dir, "config", "user.name", "T");
+        const files: Record<string, string> = {
+          "chant.workspace.json": DECLARATION,
+          "chant.config.ts": `export default { environments: ["dev", "staging", "prod"] };\n`,
+          "api.component.ts": "export const api = {};\n",
+          "work/W-001-ship.md": W001,
+          ...KIND_FILES,
+        };
+        for (const [path, text] of Object.entries(files)) {
+          mkdirSync(join(dir, path, ".."), { recursive: true });
+          writeFileSync(join(dir, path), text);
+        }
+        git(dir, "add", ".");
+        git(dir, "commit", "-q", "-m", "the api and W-001");
+        // The work: a commit whose trailer names W-001, made green.
+        writeFileSync(join(dir, "api.component.ts"), "export const api = { port: 8081 };\n");
+        git(dir, "commit", "-q", "-am", "serve the api on 8081", "--trailer", "Chant-Record: work:W-001");
+        const sha = git(dir, "rev-parse", "HEAD");
+        git(dir, "tag", `ci/green/${sha}`, sha);
+        process.chdir(dir);
+
+        // The release is cut from the green commit, and promoted to prod through its release gate.
+        const cut = await cutRelease({ cwd: dir, compiler, label: "v1.0.0", actor: "alice", env: {}, now: () => new Date("2026-10-16T10:00:00.000Z") });
+        const releaseDigest = cut.release.releaseDigest;
+        await appendReleaseRecord({ component: "api", env: "staging", digest: DIGEST, gitSha: sha, runId: "run-1", timestamp: "2026-10-16T10:30:00.000Z", actor: "ci" }, { cwd: dir });
+        expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(3);
+        expect((await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" })).ok).toBe(true);
+        expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(0);
+        const [deploy] = (await readReleaseLedger("prod", { cwd: dir })).records;
+        const [resolution] = (await readGateLedger("release", { cwd: dir })).resolutions;
+
+        const walk = async (region: string): Promise<Result> => {
+          const { doc } = await intentGraph({
+            cwd: dir,
+            region,
+            kinds: [join(dir, "work/work.kind.mjs")],
+            resolveNode: async (_cwd, _at, member, id) => (member === "api" && id === "api/api" ? { file: "api.component.ts", line: null } : null),
+          });
+          intent.expectValid(doc);
+          if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+          return doc;
+        };
+
+        // From the resource node: who asked for it, and who let it ship, in one read.
+        const doc = await walk("api/api");
+        expect(doc.nodes[0]).toMatchObject({ kind: "region", path: "api.component.ts", node: "api/api" });
+        const trace = doc.trace!;
+        expect(trace.reasons).toEqual([]);
+        const c = trace.commits.find((x) => x.sha === sha)!;
+        expect(c.work).toEqual({ state: "linked", items: [{ id: "work:W-001", node: "record:work/W-001", source: { ref: sha, field: "Chant-Record", value: "work:W-001" } }], problems: [] });
+        expect(c.tag).toMatchObject({ state: "green", green: { tag: `ci/green/${sha}` } });
+        expect(c.releases).toEqual([{ release: releaseDigest, link: "cut-from", source: { ref: `chant/lifecycle:_releases/${releaseDigest.replace(/:/g, "_")}.json`, field: "commit", value: sha } }]);
+        expect(c.deploys.map((d) => [d.env, d.link])).toEqual([["prod", "built-from"], ["staging", "built-from"]]);
+
+        const [release] = trace.releases;
+        expect(trace.releases).toHaveLength(1);
+        expect(release).toMatchObject({ releaseDigest, label: "v1.0.0", commit: sha, tag: { state: "green" }, cuts: [{ label: "v1.0.0", actor: "alice" }] });
+        // The gate approval: who, on which channel, when, and the change set the promote stored for it (#4022).
+        expect(release.gates).toEqual([
+          expect.objectContaining({ op: "release", gate: "prod-release", environment: "prod", resolvedBy: "alice", channel: "cli", at: resolution.timestamp, planDigest: resolution.planDigest, changeSet: resolution.planDigest, empty: false }),
+        ]);
+        expect(release.gates[0].changeSetSource).toEqual({ ref: `chant/lifecycle:_change-sets/${resolution.planDigest!.replace(/:/g, "_")}.json`, field: "planDigest", value: resolution.planDigest });
+
+        // The prod deploy record, admitted by that resolution.
+        const prod = trace.deploys.find((d) => d.env === "prod")!;
+        expect(release.deploys).toEqual([prod.id]);
+        expect(prod).toMatchObject({ component: "api", runId: deploy.runId, gitSha: sha, release: releaseDigest, approver: "alice", admittedBy: { op: "release", gate: "prod-release", resolvedBy: "alice", at: resolution.timestamp } });
+        // Staging was a plain deploy of the same commit: it names no release.
+        expect(trace.deploys.find((d) => d.env === "staging")).toMatchObject({ release: null, admittedBy: null });
+
+        // The same chain from the commit itself.
+        const byCommit = await walk(sha);
+        expect(byCommit.trace!.commits).toEqual([c]);
+        expect(byCommit.trace!.releases).toEqual(trace.releases);
+      });
+    },
+    240_000,
+  );
+});

package/src/cli/handlers/lifecycle-gc.test.ts

@@ -0,0 +1,126 @@
+/** #4036: `chant lifecycle gc [--yes] [--push] [--json]`, in temp repos. */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { runLifecycleGc } from "./lifecycle-gc";
+import { writeLedgerFiles } from "../../lifecycle/git";
+import { makeRelease } from "../../lifecycle/release-store";
+import type { GcReport } from "../../lifecycle/retention";
+
+function args(o: Partial<ParsedArgs>): ParsedArgs {
+  return { command: "lifecycle", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...o };
+}
+
+const git = (cwd: string, ...a: string[]) => execFileSync("git", a, { cwd, encoding: "utf-8" }).trim();
+
+let dir: string;
+let cwd: string;
+let out: string[];
+let err: string[];
+beforeEach(() => {
+  cwd = process.cwd();
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "lifecycle-gc-")));
+  vi.stubEnv("CHANT_RUN_EVENTS_DIR", join(dir, ".events"));
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "t@t");
+  git(dir, "config", "user.name", "t");
+  process.chdir(dir);
+  out = [];
+  err = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(String(s)));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(String(s)));
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  process.chdir(cwd);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function commitAll(): string {
+  writeFileSync(join(dir, "README.md"), "x\n");
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  return git(dir, "rev-parse", "HEAD");
+}
+
+const changeSet = `_change-sets/jcs1-sha256_${"1".repeat(64)}.json`;
+const ctx = (o: Partial<ParsedArgs>) => ({ args: args(o), plugins: [], serializers: [] });
+const report = (): GcReport => JSON.parse(out.join("\n")) as GcReport;
+
+describe("chant lifecycle gc", () => {
+  test("a dry run by default; --yes prunes in one local commit and pushes nothing", async () => {
+    writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [], retention: { changeSets: { days: 0 } } }));
+    commitAll();
+    await writeLedgerFiles([{ path: changeSet, content: "{}\n", expectPriorSha: null }], "fixture", { cwd: dir });
+    const tip = git(dir, "rev-parse", "chant/lifecycle");
+
+    expect(await runLifecycleGc(ctx({}))).toBe(0);
+    expect(out[0]).toMatch(/^chant\/lifecycle at [0-9a-f]{12}: would remove 1 change set\(s\), 0 release\(s\) and 0 template\(s\)/);
+    expect(err.join("\n")).toContain("Dry run: nothing was removed");
+    expect(git(dir, "rev-parse", "chant/lifecycle")).toBe(tip);
+
+    out = [];
+    expect(await runLifecycleGc(ctx({ yes: true, json: true }))).toBe(0);
+    const r = report();
+    expect(r.dryRun).toBe(false);
+    expect(r.policy.changeSets.days).toBe(0);
+    expect(r.lifecycle.remove.map((f) => f.path)).toEqual([changeSet]);
+    expect(r.lifecycle.commit).toBe(git(dir, "rev-parse", "chant/lifecycle"));
+    expect(git(dir, "rev-parse", "chant/lifecycle^")).toBe(tip);
+    expect(r.lifecycle.pushed).toBe(false);
+  });
+
+  test("outside a workspace the defaults apply, and a release of a revoked commit is not promotable", async () => {
+    const head = commitAll();
+    const cut = (commit: string) => {
+      const r = makeRelease({ member: null, commit, artifactDigests: [], targets: [{ env: "prod", templates: [], params: [] }] });
+      return { r, line: JSON.stringify({ version: 1, releaseDigest: r.releaseDigest, label: null, actor: "a", timestamp: new Date().toISOString(), runOrigin: null, signature: null }) };
+    };
+    const revoked = cut(head);
+    const fine = cut("b".repeat(40));
+    const file = (d: string) => `_releases/${d.replace(/:/g, "_")}.json`;
+    await writeLedgerFiles(
+      [
+        { path: changeSet, content: "{}\n" },
+        { path: file(revoked.r.releaseDigest), content: `${JSON.stringify(revoked.r)}\n` },
+        { path: file(fine.r.releaseDigest), content: `${JSON.stringify(fine.r)}\n` },
+        { path: "_releases/cuts.jsonl", content: `${revoked.line}\n${fine.line}\n` },
+      ],
+      "fixture",
+      { cwd: dir },
+    );
+    git(dir, "tag", `ci/revoked/${head}`, head);
+
+    expect(await runLifecycleGc(ctx({ json: true }))).toBe(0);
+    const r = report();
+    expect(r.policy.releases).toEqual({ days: 14, keep: 10 });
+    expect(r.lifecycle.remove.map((f) => f.path)).toEqual([file(revoked.r.releaseDigest)]);
+    expect(r.lifecycle.keep.map((f) => [f.path, f.reasons.map((x) => x.code)])).toEqual(
+      expect.arrayContaining([[changeSet, ["within-window"]], [file(fine.r.releaseDigest), ["newest", "within-window"]]]),
+    );
+  });
+
+  test("a workspace whose declaration can't be read prunes nothing", async () => {
+    writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [], retention: { changeSets: { days: -1 } } }));
+    commitAll();
+    expect(await runLifecycleGc(ctx({ yes: true }))).toBe(1);
+    expect(err.join("\n")).toContain("its retention policy is unknown and nothing is pruned");
+  });
+
+  test("a directory outside git is refused", async () => {
+    const plain = realpathSync(mkdtempSync(join(tmpdir(), "lifecycle-gc-plain-")));
+    try {
+      process.chdir(plain);
+      expect(await runLifecycleGc(ctx({}))).toBe(1);
+      expect(err.join("\n")).toContain("not in a git repository");
+    } finally {
+      process.chdir(dir);
+      rmSync(plain, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/handlers/lifecycle-gc.ts

@@ -0,0 +1,146 @@
+/**
+ * `chant lifecycle gc [--yes] [--push] [--json] [--verbose]` (#4036): prune
+ * stored change sets, releases and their templates from `chant/lifecycle`, and
+ * run event files from this host, by the retention policy.
+ *
+ * Without `--yes` it is a dry run: it prints what it would remove and changes
+ * nothing. With `--yes` it writes one commit to the local `chant/lifecycle`
+ * that removes those files, and deletes the run event files. It pushes only
+ * with `--push`. History is never rewritten, so a pruned file stays in the
+ * branch's earlier commits. The rules are in ../../lifecycle/retention.ts.
+ *
+ * The policy is the defaults, overridden by the `retention` block of the
+ * workspace declaration at base when the checkout is a workspace. The prune
+ * covers the whole branch, every member, from wherever in the repository it
+ * runs.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { formatError, formatSuccess, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import type { RetentionPolicy } from "../../lifecycle/retention-policy";
+
+const USAGE = "chant lifecycle gc [--yes] [--push] [--json] [--verbose]";
+
+function tryGit(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a workspace declaration sits in `cwd` or a directory above it, up to the repository's top. */
+function inWorkspace(cwd: string, top: string): boolean {
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "chant.workspace.json")) || existsSync(join(dir, "chant.workspace.jsonc"))) return true;
+    if (dir === top || dirname(dir) === dir) return false;
+  }
+}
+
+/** Every commit with a `ci/revoked/<sha>` tag, counted as `chant release cut` counts it. */
+async function revokedCommits(cwd: string, top: string, green: import("../../workspace/declaration").CiGreen | null, workspace: boolean): Promise<Set<string>> {
+  if (workspace) {
+    const { readCiTags } = await import("../../workspace/ci-green");
+    const base = green
+      ? (tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${green.branch}^{commit}`]) ??
+        tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]) ??
+        tryGit(top, ["rev-parse", "HEAD"]))
+      : null;
+    return new Set(readCiTags(top, green, base).revoked.keys());
+  }
+  // With no declaration every tag counts, as readCiTags counts them without `ci.green`.
+  const out = tryGit(cwd, ["for-each-ref", "--format=%(refname:lstrip=4)", "refs/tags/ci/revoked/"]) ?? "";
+  return new Set(out.split("\n").filter((s) => /^[0-9a-f]{40,64}$/.test(s)));
+}
+
+const kb = (bytes: number): string => (bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${(bytes / 1024).toFixed(1)} KB`);
+
+export async function runLifecycleGc(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.extraPositional) {
+    console.error(formatError({ message: `lifecycle gc takes no argument, and was given "${args.extraPositional}"`, hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(".");
+  const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top) {
+    console.error(formatError({ message: "lifecycle gc prunes the chant/lifecycle branch, and this directory is not in a git repository", hint: USAGE }));
+    return 1;
+  }
+  const dryRun = args.yes !== true;
+
+  const { resolveRetention } = await import("../../lifecycle/retention-policy");
+  let policy: RetentionPolicy = resolveRetention(null);
+  let green: import("../../workspace/declaration").CiGreen | null = null;
+  const workspace = inWorkspace(cwd, top);
+  if (workspace) {
+    const { scopeSource } = await import("../../workspace/write-scope");
+    const source = scopeSource(cwd);
+    if (!source.declaration) {
+      console.error(formatError({ message: `the workspace declaration can't be read, so its retention policy is unknown and nothing is pruned: ${source.failure?.message ?? "no declaration"}` }));
+      return 1;
+    }
+    policy = resolveRetention(source.declaration.retention);
+    green = source.declaration.ci?.green ?? null;
+  }
+
+  // Read the remote's facts first: a prune planned on a stale branch could
+  // remove what a newer gate binds, and a forked branch must not be pushed over.
+  const { fetchLifecycleStatus } = await import("../../lifecycle/git");
+  const fetched = await fetchLifecycleStatus({ cwd });
+  if (fetched.status === "diverged" || fetched.status === "unreachable") {
+    const why = fetched.status === "diverged" ? `the local chant/lifecycle and ${fetched.remote}'s have forked` : `${fetched.remote} did not answer: ${fetched.stderr}`;
+    if (!dryRun) {
+      console.error(formatError({ message: `nothing was pruned: ${why}`, hint: "Bring chant/lifecycle up to date with its remote, then run again." }));
+      return 1;
+    }
+    if (!args.json) console.error(formatWarning({ message: `planned on the local branch only: ${why}` }));
+  }
+
+  const { runLifecycleGc: run } = await import("../../lifecycle/retention");
+  const report = await run({
+    cwd,
+    policy,
+    now: new Date(),
+    revokedCommits: await revokedCommits(cwd, top, green, workspace),
+    dryRun,
+    push: args.push === true,
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  const lc = report.lifecycle;
+  const count = (list: ReadonlyArray<{ kind: string }>, kind: string) => list.filter((f) => f.kind === kind).length;
+  const bytes = lc.remove.reduce((n, f) => n + f.bytes, 0);
+  const verb = dryRun ? "would remove" : "removed";
+  if (!lc.tip) {
+    console.error("No chant/lifecycle branch: nothing stored to prune.");
+  } else {
+    console.log(
+      `chant/lifecycle at ${lc.tip.slice(0, 12)}: ${verb} ${count(lc.remove, "change-set")} change set(s), ${count(lc.remove, "release")} release(s) and ${count(lc.remove, "template")} template(s), ${kb(bytes)}; ` +
+        `keeps ${count(lc.keep, "change-set")}, ${count(lc.keep, "release")} and ${count(lc.keep, "template")}`,
+    );
+    console.log(`  tree at the tip: ${lc.before.files} file(s), ${kb(lc.before.bytes)} before; ${lc.after.files} file(s), ${kb(lc.after.bytes)} after. The ledgers (${kb(lc.before.ledgers.bytes)}) are never pruned, and history keeps every removed file.`);
+    if (args.verbose) for (const f of lc.remove) console.log(`  - ${f.path}`);
+  }
+  const ev = report.runEvents;
+  if (ev.dir) {
+    console.log(`  run events in ${ev.dir}: ${verb} ${ev.remove.length} file(s), ${kb(ev.remove.reduce((n, f) => n + f.bytes, 0))}; keeps ${ev.kept.files}`);
+    if (args.verbose) for (const f of ev.remove) console.log(`  - ${f.file}`);
+  }
+  if (dryRun) {
+    console.error("Dry run: nothing was removed. Run again with --yes to prune.");
+  } else if (lc.commit) {
+    console.error(formatSuccess(`Pruned in commit ${lc.commit.slice(0, 12)} on chant/lifecycle`));
+    if (lc.pushed) console.error("  pushed");
+    else if (lc.pushWarning) console.error(formatWarning({ message: lc.pushWarning }));
+    else console.error("  not pushed: run with --push, or push chant/lifecycle yourself");
+  }
+  return 0;
+}

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

@@ -850,6 +850,43 @@ describe("runApprove — the resolution names the plan it approves (#2300)", ()
     errSpy.mockRestore();
   });
 
+  // #4020: the resolution names the commit and run the gate waited on, off the fact it answers.
+  test("it copies the standing fact's commit and run onto the resolution", async () => {
+    readGateLedgerMock.mockResolvedValue({
+      resolutions: [],
+      pending: [{
+        version: 1, kind: "pending", op: "fountain-apply", gate: "rollout-gate",
+        timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z",
+        planDigest: PLAN_A, gitSha: "f".repeat(40), runId: "9001",
+      }],
+      malformed: 0,
+    });
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ gitSha: "f".repeat(40), runId: "9001" }));
+    errSpy.mockRestore();
+  });
+
+  test("a standing fact from before the commit was recorded gives a resolution without one", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+    const written = appendGateResolutionMock.mock.calls.at(-1)![0] as Record<string, unknown>;
+    expect(written).not.toHaveProperty("gitSha");
+    expect(written).not.toHaveProperty("runId");
+    errSpy.mockRestore();
+  });
+
   test("--plan names one explicitly, and wins over the standing fact's", async () => {
     const other = `sha256:${"b".repeat(64)}`;
     seedPending("fountain-apply", "rollout-gate", PLAN_A);