@intentius/chant 0.49.0 → 0.50.0

package/src/cli/handlers/components.ts

@@ -26,20 +26,23 @@
  * `componentBom` fall back to `null` exactly as before — no regression for
  * ledgers with no persisted manifests at all.
  */
-import { resolve } from "node:path";
+import { resolve, join, dirname } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { getHeadCommit, fetchLifecycle, pushLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
 import {
   appendReleaseRecord,
   readReleaseLedger,
   listReleaseEnvironments,
+  latestPerComponent,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
 import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
 import { commandBuildParams } from "../build-params-cli";
 import { buildChangeSet } from "../../lifecycle/change-set";
 import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
-import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-store";
+import { findBuildManifestByArtifactDigest, readBuildManifest } from "../../lifecycle/build-ledger-store";
 import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
+import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isResourceDeclarable } from "../../declarable";
@@ -51,6 +54,7 @@ import type { LexiconPlugin } 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";
 
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
@@ -147,6 +151,159 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   }
 }
 
+/** One entry of `chant components export`'s per-entry result (text and `--json` output). */
+interface ExportEntryResult {
+  kind: string;
+  path: string;
+  digest: string;
+  status: "materialized" | "missing";
+  /** Set only when `status` is "missing" — why the source file couldn't be read. */
+  reason?: string;
+}
+
+/**
+ * chant components export <env> --component <name> [--digest <manifestDigest>]
+ *   -o <dir> [--json]
+ *
+ * Materializes a persisted `BuildArchiveManifest` (#609,
+ * ../../lifecycle/build-ledger-store.ts) to a portable directory: every
+ * `image`/`template`/`asset`/`sbom` entry is copied byte-for-byte from where
+ * the build that produced it left it on disk (its `path`, resolved against
+ * the current working directory — the same directory a component's
+ * `docker-build`/`addArchiveTemplate`/etc. step wrote it into) under that
+ * same archive-relative path in `-o <dir>`, plus a `manifest.json` so the
+ * directory is self-describing without chant. No re-synthesis: this reads
+ * bytes a prior `chant build`/`run --components` already produced, never
+ * regenerates them (#929) — the "byte-identical, promote-by-digest" contract
+ * the build archive is built on (see ../../components/verbs/build-archive.ts).
+ *
+ * Manifest resolution:
+ *  - `--digest <manifestDigest>` reads it directly (`readBuildManifest`),
+ *    independent of any environment/release record.
+ *  - Otherwise resolves "the manifest behind this component's most recent
+ *    successful run" in `<env>`: the latest release record's own
+ *    `manifestDigest` when it was recorded, else a reverse lookup by its
+ *    promoted artifact digest (`findBuildManifestByArtifactDigest`) — the
+ *    same join `chant components status` already performs.
+ *
+ * A source file missing on disk (the build that produced the manifest ran
+ * somewhere else, or its output was since cleaned) is reported per entry
+ * rather than silently dropped; the command exits non-zero so an incomplete
+ * export is never mistaken for a complete one.
+ */
+export async function runComponentsExport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const environment = args.extraPositional;
+  const component = args.component;
+  const outDir = args.output;
+  const usage = "chant components export <env> --component <name> [--digest <manifestDigest>] -o <dir>";
+
+  if (!outDir) {
+    console.error(formatError({ message: "-o/--output <dir> is required", hint: usage }));
+    return 1;
+  }
+
+  await fetchLifecycle();
+
+  let manifest: BuildArchiveManifest;
+
+  if (args.digest) {
+    const resolved = await readBuildManifest(args.digest);
+    if (!resolved) {
+      console.error(formatError({ message: `No persisted build manifest found for digest ${args.digest}` }));
+      return 1;
+    }
+    if (component && resolved.component !== component) {
+      console.error(formatWarning({
+        message: `--component ${component} does not match the resolved manifest's component (${resolved.component}) — exporting the manifest at --digest ${args.digest} anyway`,
+      }));
+    }
+    manifest = resolved;
+  } else {
+    if (!environment || !component) {
+      console.error(formatError({
+        message: "Environment and --component are required unless --digest <manifestDigest> is given",
+        hint: usage,
+      }));
+      return 1;
+    }
+    const ledger = await readReleaseLedger(environment);
+    const latest = latestPerComponent(ledger.records).get(component);
+    if (!latest) {
+      console.error(formatError({
+        message: `No release record for component "${component}" in environment "${environment}"`,
+      }));
+      return 1;
+    }
+    const resolved = latest.manifestDigest
+      ? await readBuildManifest(latest.manifestDigest)
+      : await findBuildManifestByArtifactDigest(latest.digest);
+    if (!resolved) {
+      console.error(formatError({
+        message: `No persisted build manifest found for ${component}@${environment}'s recorded digest ${latest.digest}`,
+        hint: "The build predates #609, or was recorded via `chant components release` alone with no corresponding `chant build`/`run --components`.",
+      }));
+      return 1;
+    }
+    manifest = resolved;
+  }
+
+  const targetDir = resolve(outDir);
+  const sourceRoot = resolve(".");
+  await mkdir(targetDir, { recursive: true });
+
+  const entries = [...manifest.contents].sort((a, b) => a.path.localeCompare(b.path));
+  const results: ExportEntryResult[] = [];
+  for (const entry of entries) {
+    try {
+      const bytes = await readFile(resolve(sourceRoot, entry.path));
+      const target = join(targetDir, entry.path);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, bytes);
+      results.push({ kind: entry.kind, path: entry.path, digest: entry.digest, status: "materialized" });
+    } catch (err) {
+      results.push({
+        kind: entry.kind,
+        path: entry.path,
+        digest: entry.digest,
+        status: "missing",
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(manifest, sortedJsonReplacer, 2));
+
+  const missing = results.filter((r) => r.status === "missing");
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      component: manifest.component,
+      manifestDigest: manifest.manifestDigest,
+      outDir: targetDir,
+      entries: results,
+    }, null, 2));
+  } else {
+    console.log(formatBold(`${manifest.component} (${manifest.manifestDigest}) -> ${targetDir}`));
+    for (const r of results) {
+      const status = r.status === "materialized" ? formatSuccess("ok") : formatError({ message: r.reason ?? "missing" });
+      console.log(`  ${r.kind.padEnd(10)}${r.path.padEnd(40)}${status}`);
+    }
+    console.log(`  ${"manifest".padEnd(10)}${"manifest.json".padEnd(40)}${formatSuccess("ok")}`);
+  }
+
+  if (missing.length > 0) {
+    console.error(formatError({
+      message: `${missing.length} of ${results.length} archive entr${missing.length === 1 ? "y" : "ies"} not found on disk — export incomplete`,
+      hint: `Run this from the checkout where the build that produced ${manifest.manifestDigest} still has its output on disk.`,
+    }));
+    return 1;
+  }
+
+  console.error(formatSuccess(`Exported ${results.length} entr${results.length === 1 ? "y" : "ies"} + manifest.json to ${targetDir}`));
+  return 0;
+}
+
 /** One row of `chant components status` JSON output. */
 interface StatusJsonRow {
   component: string;
@@ -595,7 +752,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
 export async function runComponentsUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown components subcommand: ${ctx.args.path}`,
-    hint: "Available: chant components status [env], chant components release <env>",
+    hint: "Available: chant components status [env], chant components release <env>, chant components export <env>",
   }));
   return 1;
 }

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

@@ -431,6 +431,26 @@ describe("runGraph", () => {
       expect(discoverMock).not.toHaveBeenCalled();
     });
 
+    test("--components --format ir carries declared composites (#1492); undeclared components have no composites attr", async () => {
+      lintMock.mockResolvedValue({ success: true });
+      componentGraphMock.mockResolvedValue({
+        success: true,
+        order: ["shared-foundation", "loom-backend"],
+        waves: [["shared-foundation"], ["loom-backend"]],
+        edges: [{ from: "loom-backend", to: "shared-foundation" }],
+        files: {},
+        composites: { "shared-foundation": ["ArtifactBucket", "OperatorRole"] },
+      });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.find((n: { id: string }) => n.id === "shared-foundation").attrs.composites).toEqual([
+        "ArtifactBucket",
+        "OperatorRole",
+      ]);
+      expect("composites" in ir.nodes.find((n: { id: string }) => n.id === "loom-backend").attrs).toBe(false);
+    });
+
     test("--components --format mermaid lanes the components by wave", async () => {
       lintMock.mockResolvedValue({ success: true });
       componentGraphClean();

package/src/cli/handlers/graph.ts

@@ -580,7 +580,16 @@ async function runComponentGraphView(
       // `liveNames` (#1491): the resources this component owns — declared, or
       // the contract's `[name]` identity fallback — so a consumer can join
       // the component DAG to the resource graph instead of guessing at kinds.
-      attrs: { wave: waveOf.get(name) ?? null, liveNames: graph.liveNames?.[name] ?? [name] },
+      // `composites` (#1492): the composite kind(s) this component's
+      // resources come from, when the component declared them explicitly —
+      // omitted from attrs (not defaulted) when it didn't, so a consumer
+      // knows to fall back to its own naming-convention guess rather than
+      // reading "no composites" from an empty array.
+      attrs: {
+        wave: waveOf.get(name) ?? null,
+        liveNames: graph.liveNames?.[name] ?? [name],
+        ...(graph.composites?.[name] ? { composites: graph.composites[name] } : {}),
+      },
       // Deep-link the node to its `*.component.ts` (behold's inspect panel).
       ...(graph.files?.[name] ? { sourceLoc: { file: graph.files[name] } } : {}),
     })),

package/src/cli/handlers/lifecycle.ts

@@ -3,8 +3,9 @@ import { commandBuildParams } from "../build-params-cli";
 import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
-import { deepDiffForLexicon } from "../../lifecycle/deep-observe";
+import { deepDiffForLexicon, type DeclaredEntities } from "../../lifecycle/deep-observe";
 import { countPropertyDrift, type DeepDiffResult } from "../../lifecycle/deep-diff";
+import { describePathOrigin, getPathProvenance } from "../../provenance";
 import {
   acceptDeviations,
   baselineForLexicon,
@@ -55,7 +56,7 @@ import type { ChantConfig } from "../../config";
  * then `config.sourceDir`, then "." (the root). Snapshot/diff/plan all use this
  * so their build digests stay consistent.
  */
-function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
+export function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
   return resolve(args.src ?? config.sourceDir ?? ".");
 }
 
@@ -803,13 +804,17 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
     // declared name the reader can never resolve reads as missing (see
     // lifecycle/observe.ts).
     const declared = new Set<string>();
-    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+    const entities: DeclaredEntities = new Map();
     for (const [name, entity] of args.buildResult.entities) {
       if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
         declared.add(name);
+        // Path origins are carried across explicitly (#1443): this map is plain
+        // objects, and the symbol-keyed provenance channel does not survive it.
+        const pathOrigins = getPathProvenance(entity);
         entities.set(name, {
           entityType: entity.entityType,
           props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+          ...(pathOrigins ? { pathOrigins } : {}),
         });
       }
     }
@@ -964,7 +969,10 @@ function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
         const declared = "declared" in change ? formatValue(change.declared) : "<undeclared>";
         const live = "live" in change ? formatValue(change.live) : "<absent>";
         const baseline = "baseline" in change ? ` [accepted: ${formatValue(change.baseline)}]` : "";
-        console.log(`      ${change.path}: ${declared} → ${live}${baseline}`);
+        // Both sides of the attribution, where each is known (#1443/#1189).
+        const from = change.origin ? ` [from: ${describePathOrigin(change.origin)}]` : "";
+        const owner = change.owner ? ` [owner: ${change.owner}]` : "";
+        console.log(`      ${change.path}: ${declared} → ${live}${baseline}${from}${owner}`);
       }
     }
   }

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

@@ -0,0 +1,255 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { ParsedArgs } from "../registry";
+
+const discoverConvergeOpsMock = vi.fn();
+const runOperatorRoundMock = vi.fn();
+const runOperatorForeverMock = vi.fn();
+const discoverOpsMock = vi.fn();
+const loadActivitiesMock = vi.fn();
+const loadProfilesMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+const readLeaseMock = vi.fn();
+const readConvergeLedgerMock = vi.fn();
+const appendGateResolutionMock = vi.fn();
+const readGateResolutionsMock = vi.fn();
+const pushLifecycleMock = vi.fn();
+
+vi.mock("../../op/operator", async () => {
+  const actual = await vi.importActual<typeof import("../../op/operator")>("../../op/operator");
+  return {
+    ...actual,
+    discoverConvergeOps: (...args: unknown[]) => discoverConvergeOpsMock(...args),
+    runOperatorRound: (...args: unknown[]) => runOperatorRoundMock(...args),
+    runOperatorForever: (...args: unknown[]) => runOperatorForeverMock(...args),
+  };
+});
+vi.mock("../../op/discover", () => ({ discoverOps: () => discoverOpsMock() }));
+vi.mock("../../op/activity-registry", () => ({
+  loadActivities: (...args: unknown[]) => loadActivitiesMock(...args),
+  loadProfiles: (...args: unknown[]) => loadProfilesMock(...args),
+}));
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
+});
+vi.mock("../../lifecycle/lease", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/lease")>("../../lifecycle/lease");
+  return { ...actual, readLease: (...args: unknown[]) => readLeaseMock(...args) };
+});
+vi.mock("../../lifecycle/converge-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/converge-ledger")>("../../lifecycle/converge-ledger");
+  return { ...actual, readConvergeLedger: (...args: unknown[]) => readConvergeLedgerMock(...args) };
+});
+vi.mock("../../lifecycle/gate-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/gate-ledger")>("../../lifecycle/gate-ledger");
+  return {
+    ...actual,
+    appendGateResolution: (...args: unknown[]) => appendGateResolutionMock(...args),
+    readGateResolutions: (...args: unknown[]) => readGateResolutionsMock(...args),
+  };
+});
+vi.mock("../../lifecycle/git", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
+  return { ...actual, pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args) };
+});
+
+// Imported after the mocks above are registered.
+const { runOperator, runOperatorStatus, runApprove } = await import("./operator");
+
+function ctx(args: Partial<ParsedArgs>) {
+  return {
+    args: { command: "", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...args } as ParsedArgs,
+    plugins: [],
+    serializers: [],
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  loadChantConfigMock.mockResolvedValue({ config: { lexicons: [] } });
+  loadActivitiesMock.mockResolvedValue(new Map());
+  loadProfilesMock.mockResolvedValue({});
+  discoverOpsMock.mockResolvedValue({ ops: new Map([["fountain-apply", {}]]), errors: [] });
+  pushLifecycleMock.mockResolvedValue(true);
+});
+
+describe("runOperator", () => {
+  test("prints a warning and exits 0 when no ConvergeOps are discovered", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [], errors: [] });
+    const code = await runOperator(ctx({}));
+    expect(code).toBe(0);
+    expect(runOperatorRoundMock).not.toHaveBeenCalled();
+    expect(runOperatorForeverMock).not.toHaveBeenCalled();
+  });
+
+  test("--once runs exactly one round and exits 0 when nothing failed", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [{ config: { name: "staging-converge" } }], errors: [] });
+    runOperatorRoundMock.mockResolvedValue([{ kind: "ticked", op: "staging-converge", env: "staging", result: { op: "staging-converge", records: [], totalMs: 1, ok: true } }]);
+
+    const code = await runOperator(ctx({ once: true }));
+    expect(code).toBe(0);
+    expect(runOperatorRoundMock).toHaveBeenCalledTimes(1);
+    expect(runOperatorForeverMock).not.toHaveBeenCalled();
+  });
+
+  test("--once exits 1 when any op's tick failed this round", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [{ config: { name: "staging-converge" } }], errors: [] });
+    runOperatorRoundMock.mockResolvedValue([{ kind: "tick-failed", op: "staging-converge", env: "staging", error: "boom" }]);
+
+    const code = await runOperator(ctx({ once: true }));
+    expect(code).toBe(1);
+  });
+
+  test("without --once, runs the daemon loop (runOperatorForever) and exits 0 when it returns", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [{ config: { name: "staging-converge" } }], errors: [] });
+    runOperatorForeverMock.mockResolvedValue(undefined);
+
+    const code = await runOperator(ctx({}));
+    expect(code).toBe(0);
+    expect(runOperatorForeverMock).toHaveBeenCalledTimes(1);
+    expect(runOperatorRoundMock).not.toHaveBeenCalled();
+  });
+
+  test("--interval and --lease-ttl are parsed as durations and threaded through", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [{ config: { name: "staging-converge" } }], errors: [] });
+    runOperatorForeverMock.mockResolvedValue(undefined);
+
+    await runOperator(ctx({ interval: "30s", leaseTtl: "2m" }));
+    const passed = runOperatorForeverMock.mock.calls[0][0];
+    expect(passed.intervalMs).toBe(30_000);
+    expect(passed.leaseTtlMs).toBe(120_000);
+  });
+
+  test("--env is passed through to discovery and the round/loop", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [{ config: { name: "prod-converge" } }], errors: [] });
+    runOperatorRoundMock.mockResolvedValue([]);
+
+    await runOperator(ctx({ once: true, env: "prod" }));
+    expect(discoverConvergeOpsMock).toHaveBeenCalledWith({ env: "prod" });
+    expect(runOperatorRoundMock.mock.calls[0][0].env).toBe("prod");
+  });
+
+  test("a failure loading activities is reported and exits 1", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [{ config: { name: "staging-converge" } }], errors: [] });
+    loadActivitiesMock.mockRejectedValue(new Error("no activities registered"));
+
+    const code = await runOperator(ctx({ once: true }));
+    expect(code).toBe(1);
+  });
+});
+
+describe("runOperatorStatus", () => {
+  test("prints a warning and exits 0 when no ConvergeOps are discovered", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [], errors: [] });
+    const code = await runOperatorStatus(ctx({}));
+    expect(code).toBe(0);
+  });
+
+  test("--json emits one row per discovered ConvergeOp with last tick, lease, and pending gates", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({
+      ops: [{ config: { name: "staging-converge", searchAttributes: { Env: "staging" } } }],
+      errors: [],
+    });
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [
+        {
+          version: 1,
+          op: "staging-converge",
+          env: "staging",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          firedRuleIds: ["drift-apply"],
+          outcomes: [{ ruleId: "drift-apply", action: "gated", op: "fountain-apply", gateName: "rollout-gate" }],
+          summary: { drifted: 1, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0, gated: 1 },
+          log: "converge(staging): ...",
+        },
+      ],
+      malformed: 0,
+    });
+    readLeaseMock.mockResolvedValue({ sha: "abc", record: { op: "staging-converge", holder: "op-a", token: "t1", acquiredAt: "x", expiresAt: "y" } });
+    readGateResolutionsMock.mockResolvedValue({ records: [], malformed: 0 }); // no resolution yet — still pending
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const code = await runOperatorStatus(ctx({ json: true }));
+    expect(code).toBe(0);
+
+    const printed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(printed).toHaveLength(1);
+    expect(printed[0].op).toBe("staging-converge");
+    expect(printed[0].lease).toEqual({ holder: "op-a", expiresAt: "y" });
+    expect(printed[0].pendingGates).toEqual([{ rule: "drift-apply", op: "fountain-apply", gate: "rollout-gate" }]);
+    logSpy.mockRestore();
+  });
+
+  test("a gate resolved after the tick that recorded it is no longer pending", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({
+      ops: [{ config: { name: "staging-converge", searchAttributes: { Env: "staging" } } }],
+      errors: [],
+    });
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [
+        {
+          version: 1,
+          op: "staging-converge",
+          env: "staging",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          firedRuleIds: ["drift-apply"],
+          outcomes: [{ ruleId: "drift-apply", action: "gated", op: "fountain-apply", gateName: "rollout-gate" }],
+          summary: { drifted: 1, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0, gated: 1 },
+          log: "converge(staging): ...",
+        },
+      ],
+      malformed: 0,
+    });
+    readLeaseMock.mockResolvedValue({ sha: null, record: undefined });
+    readGateResolutionsMock.mockResolvedValue({
+      records: [{ version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-02T00:00:00.000Z" }],
+      malformed: 0,
+    });
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runOperatorStatus(ctx({ json: true }));
+    const printed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(printed[0].pendingGates).toEqual([]);
+    logSpy.mockRestore();
+  });
+});
+
+describe("runApprove", () => {
+  test("requires both <op> and <gate>", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(await runApprove(ctx({ path: "." }))).toBe(1);
+    expect(await runApprove(ctx({ path: "fountain-apply" }))).toBe(1);
+    errSpy.mockRestore();
+  });
+
+  test("appends a gate-resolution record and pushes, resolving --actor over env fallbacks", async () => {
+    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);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", note: "https://pr/1" }));
+
+    expect(code).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(
+      expect.objectContaining({ op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", note: "https://pr/1" }),
+    );
+    expect(pushLifecycleMock).toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
+  test("warns (but still records) when the op isn't among discovered *.op.ts declarations", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "unknown-op", gate: "g", resolvedBy: "unknown", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "unknown-op", extraPositional: "g" }));
+    expect(code).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+});