@intentius/chant 0.46.0 → 0.50.0

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

@@ -821,6 +821,120 @@ describe("runLifecyclePlan", () => {
     expect(byName["sg-0abc123"].name).toBe("sg-0abc123");
   });
 
+  // #1832 — effect receipts are declared, diffed, and observed like any
+  // resource, but observe-only to the generic apply path: the plan compares
+  // live value to resolved expectation and proposes the fire, never a create.
+  describe("effect receipts (#1832)", () => {
+    const receiptEntity = (lexicon: string) => ({
+      lexicon,
+      entityType: lexicon === "chant" ? "Chant::EffectReceipt" : `${lexicon}::Receipt`,
+      name: "dbMigrated",
+      effect: "db-migrate",
+      flavor: "existence" as const,
+      inputs: {},
+      [Symbol.for("chant.declarable")]: true,
+      [Symbol.for("chant.effect-receipt")]: true,
+    });
+
+    const buildWithReceipt = (lexicon: string): BuildResult => {
+      const base = makeBuildResult({ aws: ["bucket"] });
+      base.entities.set("dbMigrated", receiptEntity(lexicon) as unknown as Parameters<typeof base.entities.set>[1]);
+      if (lexicon !== "aws") (base.manifest.lexicons as string[]).push(lexicon);
+      return base;
+    };
+
+    test("an absent receipt is an effect row, never a create", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("aws"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: async () => ({
+            observation: "v1" as const,
+            resources: { bucket: meta() },
+            // dbMigrated neither returned nor unobserved: confirmed absent.
+          }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const row = plan.entries.find((e: { name: string }) => e.name === "dbMigrated");
+      expect(row).toMatchObject({ action: "effect", effect: "db-migrate", effectReason: "receipt-absent", lexicon: "aws" });
+      expect(plan.entries.filter((e: { name: string; action: string }) => e.name === "dbMigrated")).toHaveLength(1);
+    });
+
+    test("a live receipt carrying the existence marker is a clean noop, and the render says nothing fires", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("aws"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: async () => ({
+            observation: "v1" as const,
+            resources: {
+              bucket: meta(),
+              dbMigrated: meta({ type: "aws::Receipt", attributes: { value: "chant.effect-receipt:exists" } }),
+            },
+          }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod" }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("0 effect");
+      expect(stdoutBuf.join("\n")).not.toContain("effect will fire");
+    });
+
+    test("a stale receipt renders effect will fire", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("aws"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: async () => ({
+            observation: "v1" as const,
+            resources: {
+              bucket: meta(),
+              dbMigrated: meta({ type: "aws::Receipt", attributes: { value: "something-else" } }),
+            },
+          }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod" }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("effect will fire: db-migrate");
+    });
+
+    test("a receipt no loaded lexicon observes is unobserved, loudly", async () => {
+      buildMock.mockResolvedValue(buildWithReceipt("chant"));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({ bucket: meta() }) }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const row = plan.entries.find((e: { name: string }) => e.name === "dbMigrated");
+      expect(row).toMatchObject({ action: "unobserved", unobservedReason: "unsupported-kind" });
+      expect(stderrBuf.join("\n")).toContain("could not be observed");
+    });
+  });
+
   // #1166 — plan is always a live read (no `--live` flag of its own), so a
   // declared environment endpoint applies here exactly as it does for
   // `chant graph --live` / `chant lifecycle diff --live`.
@@ -1279,7 +1393,7 @@ describe("runLifecycleTeardown (#1222 — plan only)", () => {
     const out = stdoutBuf.join("\n");
     expect(out).toContain("Outcomes:");
     expect(out).toContain("deleted");
-    expect(out).toContain("1 deleted, 0 failed, 0 not prunable, 0 skipped");
+    expect(out).toContain("1 deleted, 0 failed, 0 not prunable, 0 retained, 0 skipped");
     expect(out).not.toContain("plan only");
   });
 

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,
@@ -18,6 +19,8 @@ import {
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
 import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
+import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
+import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
 import {
   formatUnobserved,
   mergeObservations,
@@ -53,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 ?? ".");
 }
 
@@ -358,6 +361,10 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   // committed set. Absent is the normal state (nothing accepted yet).
   const baseline = args.live ? await readObservationBaseline(environment) : null;
   const accepted: Record<string, DeviationToAccept[]> = {};
+  // Effect receipts across every target's build (#1833) — `--update-baseline`
+  // refuses to accept drift on them (the effect step is their only writer),
+  // and recognition is marker-based so materialized lexicon rows are caught.
+  const receiptEntities = new Set<string>();
 
   // #1166 — an environment can declare its own endpoint (a local emulator like
   // Floci), so `--live` is self-sufficient even when the ambient shell never
@@ -430,6 +437,9 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
         for (const [lexicon, deviations] of Object.entries(r.toAccept)) {
           (accepted[lexicon] ??= []).push(...deviations);
         }
+        if (args.updateBaseline) {
+          for (const name of collectEffectReceipts(buildResult.entities).keys()) receiptEntities.add(name);
+        }
         if (json) {
           if (target.stack) perStackJson[target.stack] = r.byLexicon;
           else combinedLexiconsJson = r.byLexicon;
@@ -443,7 +453,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
     // accepted, so it stops re-alerting. Runs before the summary lines so the
     // "no drift" verdict below still describes the run that produced it.
     if (args.live && args.updateBaseline) {
-      await recordAcceptedBaseline(environment, baseline, accepted, json);
+      await recordAcceptedBaseline(environment, baseline, accepted, json, receiptEntities);
     }
 
     if (args.live) {
@@ -495,6 +505,7 @@ async function recordAcceptedBaseline(
   existing: ObservationBaseline | null,
   accepted: Record<string, DeviationToAccept[]>,
   json: boolean,
+  receipts?: ReadonlySet<string>,
 ): Promise<void> {
   const total = Object.values(accepted).reduce((n, d) => n + d.length, 0);
   if (total === 0) {
@@ -505,11 +516,14 @@ async function recordAcceptedBaseline(
     }
     return;
   }
-  let next = existing ?? emptyBaseline(environment);
-  for (const [lexicon, deviations] of Object.entries(accepted)) {
-    next = acceptDeviations(next, lexicon, deviations);
-  }
   try {
+    // `acceptDeviations` throws on an effect-receipt deviation (#1833) —
+    // inside the try so the refusal reaches the operator as a formatted
+    // error, with no baseline written at all.
+    let next = existing ?? emptyBaseline(environment);
+    for (const [lexicon, deviations] of Object.entries(accepted)) {
+      next = acceptDeviations(next, lexicon, deviations, { receipts });
+    }
     await writeObservationBaseline(next);
     const pushed = await pushLifecycle();
     if (!json) {
@@ -520,7 +534,7 @@ async function recordAcceptedBaseline(
     }
   } catch (err) {
     console.error(formatError({
-      message: `--update-baseline: could not write the baseline — ${err instanceof Error ? err.message : String(err)}`,
+      message: `--update-baseline: baseline not updated — ${err instanceof Error ? err.message : String(err)}`,
     }));
   }
 }
@@ -790,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 } : {}),
         });
       }
     }
@@ -951,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}`);
       }
     }
   }
@@ -1126,6 +1147,15 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   const merged: ChangeSet = { env: environment, entries: [] };
   let checked = 0;
 
+  // Effect receipts (#1832): declared, diffed, and observed like any resource,
+  // but observe-only to the generic apply path — the plan compares live value
+  // to resolved expectation and proposes the fire, never a create/update.
+  const receipts = collectEffectReceipts(buildResult.entities);
+  const receiptReadings = new Map<string, ReceiptReading>();
+  // Every lexicon's observed resources merged, for resolving a receipt's
+  // reference inputs against observed values / stack outputs at plan time.
+  const allObservedResources: Record<string, ResourceMetadata> = {};
+
   // #1166 — same self-sufficiency as `chant graph --live`: an environment can
   // declare its own endpoint, applied here unless the ambient shell already
   // set it. `chant lifecycle plan` is always a live read (no `--live` flag of
@@ -1156,11 +1186,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
       const declared = new Set<string>();
       const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
       for (const [name, entity] of buildResult.entities) {
-        if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
+        // A receipt has no `props` payload of its own but is declared, diffed,
+        // and observed like any resource (#1832) — it joins the declared axis
+        // so its lexicon's observation can confirm presence or absence.
+        if (entity.lexicon === lexiconName && (isResourceDeclarable(entity) || isEffectReceipt(entity))) {
           declared.add(name);
           entities.set(name, {
             entityType: entity.entityType,
-            props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            props: (isResourceDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
           });
         }
       }
@@ -1185,6 +1218,37 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         ...(args.namespace ? { namespace: args.namespace } : {}),
       });
 
+      Object.assign(allObservedResources, observed.resources);
+      for (const [receiptName, receipt] of receipts) {
+        if (receipt.lexicon !== lexiconName) continue;
+        const live = observed.resources[receiptName];
+        const hole = observed.unobserved[receiptName];
+        if (live) {
+          receiptReadings.set(receiptName, {
+            observed: true,
+            present: true,
+            value: readReceiptValue(live.attributes),
+            type: live.type,
+            ...(live.physicalId ? { physicalId: live.physicalId } : {}),
+            lexicon: lexiconName,
+          });
+        } else if (hole) {
+          receiptReadings.set(receiptName, {
+            observed: false,
+            present: false,
+            lexicon: lexiconName,
+            ...(hole.type ? { type: hole.type } : {}),
+            unobservedReason: hole.reason,
+            ...(hole.detail ? { unobservedDetail: hole.detail } : {}),
+          });
+        } else {
+          // Neither returned nor named unobserved: the lexicon looked and
+          // confirmed the receipt absent — the same claim the change set
+          // reads off a bare observation (#1089).
+          receiptReadings.set(receiptName, { observed: true, present: false, lexicon: lexiconName });
+        }
+      }
+
       const content = await readSnapshot(environment, lexiconName);
       const observedThen = content ? (JSON.parse(content) as LifecycleSnapshot).resources : undefined;
 
@@ -1214,6 +1278,16 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // Receipt classification (#1832): live value vs resolved expectation.
+  // Absent/stale proposes the fire; unobservable is a loud hole; whatever the
+  // generic classification proposed for a receipt (a create, a delete) is
+  // replaced — the effect step is the sole writer, and a receipt is never a
+  // prune candidate.
+  if (receipts.size > 0) {
+    const receiptEntries = planReceipts(receipts, receiptReadings, observedValueResolver(allObservedResources));
+    mergeReceiptEntries(merged, receipts, receiptEntries);
+  }
+
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
@@ -1250,7 +1324,7 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
  * with the requested env identity. Stateless — live markers only, no build, no
  * snapshot. Without `--yes` nothing is deleted; with it the planned set is
  * executed per lexicon with one bounded retry pass over failures, and every
- * candidate's outcome is reported (deleted / failed / not-prunable / skipped —
+ * candidate's outcome is reported (deleted / failed / not-prunable / retained / skipped —
  * never silence). A production-like environment name additionally requires an
  * interactive confirmation, or `--confirm-prod` non-interactively.
  */
@@ -1410,10 +1484,11 @@ export async function runLifecycleTeardown(ctx: CommandContext): Promise<number>
     }
   }
 
-  const counts = { deleted: 0, failed: 0, "not-prunable": 0, skipped: 0 };
+  const counts = { deleted: 0, failed: 0, "not-prunable": 0, retained: 0, skipped: 0 };
   for (const o of report.outcomes) counts[o.outcome]++;
   console.log(
-    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ${counts.skipped} skipped`,
+    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ` +
+    `${counts.retained} retained, ${counts.skipped} skipped`,
   );
 
   if (report.unimplemented.length > 0) {
@@ -1421,6 +1496,12 @@ export async function runLifecycleTeardown(ctx: CommandContext): Promise<number>
       message: `Not executed (no teardown execution in these lexicons yet): ${report.unimplemented.join(", ")} — their candidates are reported as skipped, not deleted.`,
     }));
   }
+  if (counts.retained > 0) {
+    console.error(formatWarning({
+      message: `${counts.retained} resource(s) retained — owned by this env but deliberately kept (generated-once secrets are never swept). ` +
+        `The environment is NOT clean while they exist; delete them explicitly (e.g. kubectl delete) if you mean to.`,
+    }));
+  }
   if (plan.holes.length > 0) {
     console.error(formatWarning({
       message: "This teardown ran over an incomplete plan (holes above) — the environment cannot be called clean.",

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();
+  });
+});