@intentius/chant 0.49.0 → 0.51.0

package/src/cli/handlers/op-progress.ts

@@ -0,0 +1,192 @@
+/**
+ * Per-phase progress reconstructed from a Temporal Op workflow's history
+ * (chant #1676) — the durable-path counterpart to the local executor's
+ * `StepRecord[]` (op/local-executor.ts), so `chant run <name> --temporal
+ * --progress-json` and `op-status` can report the same shape `chant run
+ * <name> --json` already does for the local path, instead of the two raw
+ * `ActivityTaskScheduled`/`ActivityTaskCompleted` counts.
+ *
+ * A step is joined to its declared (phase, fn) by position, not by name: the
+ * declared step list (`declaredStepOrder`, mirroring the serializer's own
+ * `collectActivitySteps` traversal — main phases, then `onFailure` phases
+ * *reversed*, matching how the generated workflow actually runs them) is
+ * walked in order, and each step consumes the next not-yet-consumed
+ * `ActivityTaskScheduled` event whose activity type matches its `fn` — a
+ * per-fn FIFO queue, not a global "does this name appear anywhere" scan.
+ * Two steps calling the same activity therefore each get their own
+ * scheduled event instead of the later one overwriting the earlier
+ * (the collision the prior `run-report.ts` join had). A step whose queue is
+ * empty never ran this execution — an untaken effect branch, or an
+ * `onFailure` phase on a run that succeeded.
+ */
+
+import type { OpConfig, PhaseDefinition } from "../../op/types";
+import type { StepRecord } from "../../op/local-executor";
+import type { WorkflowHistoryRaw, HistoryEvent, WorkflowHandleRaw } from "./run-client";
+
+// Synthesized step names an effect step's read-compare-run-write compiles
+// to (lexicons/temporal/src/op/serializer.ts's RECEIPT_READ_STEP/
+// RECEIPT_WRITE_STEP) — duplicated here rather than imported so this module
+// stays lexicon-free, same constraint as op/local-executor.ts.
+const RECEIPT_READ_FN = "receiptRead";
+const RECEIPT_WRITE_FN = "receiptWrite";
+
+interface DeclaredStep {
+  phase: string;
+  fn: string;
+}
+
+function flattenPhases(phases: PhaseDefinition[]): DeclaredStep[] {
+  const out: DeclaredStep[] = [];
+  for (const phase of phases) {
+    for (const step of phase.steps) {
+      if (step.kind === "activity") {
+        out.push({ phase: phase.name, fn: step.fn });
+      } else if (step.kind === "effect") {
+        out.push({ phase: phase.name, fn: RECEIPT_READ_FN });
+        for (const nested of step.steps) {
+          if (nested.kind === "activity") out.push({ phase: phase.name, fn: nested.fn });
+        }
+        out.push({ phase: phase.name, fn: RECEIPT_WRITE_FN });
+      }
+      // Gate steps schedule no activity — nothing to join them to.
+    }
+  }
+  return out;
+}
+
+/** Declared order matching actual scheduling order: main phases, then `onFailure` reversed (compensation runs last-declared-first — serializer.ts's `renderPhases([...config.onFailure].reverse())`). */
+function declaredStepOrder(config: OpConfig): DeclaredStep[] {
+  return [...flattenPhases(config.phases), ...flattenPhases([...(config.onFailure ?? [])].reverse())];
+}
+
+interface ScheduledEntry {
+  scheduledEventId: string;
+  scheduledAt?: Date;
+}
+
+/** Every `ActivityTaskScheduled` event, grouped by activity type name, in chronological order. */
+function scheduledQueues(events: HistoryEvent[]): Map<string, ScheduledEntry[]> {
+  const byFn = new Map<string, ScheduledEntry[]>();
+  for (const e of events) {
+    if (e.eventType !== "ActivityTaskScheduled") continue;
+    const attrs = e.activityTaskScheduledEventAttributes;
+    if (!attrs) continue;
+    const fn = attrs.activityType?.name ?? "unknown";
+    if (!byFn.has(fn)) byFn.set(fn, []);
+    byFn.get(fn)!.push({ scheduledEventId: e.eventId ?? "", scheduledAt: e.eventTime });
+  }
+  return byFn;
+}
+
+interface TerminalOutcome {
+  status: "ok" | "fail";
+  at?: Date;
+  error?: string;
+}
+
+/**
+ * The terminal outcome of each scheduled activity, keyed by the scheduling
+ * event's own id. A retried activity emits one `ActivityTaskFailed` per
+ * attempt under the same `scheduledEventId`; walking events in order and
+ * always overwriting on a later event leaves whichever came last —
+ * `ActivityTaskCompleted` on an eventual success, otherwise the final
+ * attempt's failure.
+ */
+function terminalOutcomes(events: HistoryEvent[]): Map<string, TerminalOutcome> {
+  const out = new Map<string, TerminalOutcome>();
+  for (const e of events) {
+    if (e.eventType === "ActivityTaskCompleted" && e.activityTaskCompletedEventAttributes) {
+      const id = e.activityTaskCompletedEventAttributes.scheduledEventId;
+      if (id) out.set(id, { status: "ok", at: e.eventTime });
+    } else if (e.eventType === "ActivityTaskFailed" && e.activityTaskFailedEventAttributes) {
+      const id = e.activityTaskFailedEventAttributes.scheduledEventId;
+      if (id) {
+        out.set(id, {
+          status: "fail",
+          at: e.eventTime,
+          error: e.activityTaskFailedEventAttributes.failure?.message ?? "unknown error",
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Reconstruct per-step progress records from a workflow's history, in
+ * declared order. Only settled steps (matched to a scheduled event that has
+ * since completed or failed) produce a record — a step that hasn't been
+ * scheduled yet simply isn't in the result, so a live poll only ever
+ * appends. Pass `final: true` once the workflow has reached a terminal
+ * status to also emit a `"skipped"` record for every declared step that
+ * never got a matching scheduled event (an untaken effect branch, or an
+ * `onFailure` phase on a run that succeeded) — never before, or a
+ * still-running Op would show its not-yet-reached steps as skipped.
+ */
+export function extractStepRecords(
+  config: OpConfig,
+  history: WorkflowHistoryRaw,
+  opts: { final?: boolean } = {},
+): StepRecord[] {
+  const events = history.events ?? [];
+  const queues = scheduledQueues(events);
+  const terminals = terminalOutcomes(events);
+  const nextIndex = new Map<string, number>();
+
+  const records: StepRecord[] = [];
+  for (const step of declaredStepOrder(config)) {
+    const queue = queues.get(step.fn);
+    const idx = nextIndex.get(step.fn) ?? 0;
+    const entry = queue?.[idx];
+    if (!entry) {
+      if (opts.final) records.push({ phase: step.phase, fn: step.fn, status: "skipped", durationMs: 0 });
+      continue;
+    }
+    nextIndex.set(step.fn, idx + 1);
+
+    const terminal = terminals.get(entry.scheduledEventId);
+    if (!terminal) continue; // scheduled but not yet settled
+
+    const durationMs =
+      entry.scheduledAt && terminal.at ? terminal.at.getTime() - entry.scheduledAt.getTime() : 0;
+    records.push({
+      phase: step.phase,
+      fn: step.fn,
+      status: terminal.status,
+      durationMs,
+      ...(terminal.error ? { error: terminal.error } : {}),
+    });
+  }
+  return records;
+}
+
+/** `{completed, scheduled}` activity counts for the summary line `chant run status`/`op-status` show alongside the full record list. */
+export function countActivities(history: WorkflowHistoryRaw): { completed: number; scheduled: number } {
+  const events = history.events ?? [];
+  return {
+    completed: events.filter((e) => e.eventType === "ActivityTaskCompleted").length,
+    scheduled: events.filter((e) => e.eventType === "ActivityTaskScheduled").length,
+  };
+}
+
+/** The `gateState` workflow query's result (op/serializer.ts's `emitGate`) — the gate currently blocking the workflow, or `null` when none is pending. */
+export interface GateQueryResult {
+  signalName: string;
+  description?: string;
+  since: string;
+}
+
+/**
+ * Best-effort `gateState` query. `undefined` (as opposed to `null`) means
+ * the query itself failed — an Op with no gate steps never registers a
+ * `gateState` handler, so querying it is expected to fail, not an error
+ * worth surfacing.
+ */
+export async function queryGateState(handle: WorkflowHandleRaw): Promise<GateQueryResult | null | undefined> {
+  try {
+    return await handle.query<GateQueryResult | null>("gateState");
+  } catch {
+    return undefined;
+  }
+}

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

package/src/cli/handlers/operator.ts

@@ -0,0 +1,240 @@
+/**
+ * `chant operator` / `chant operator status` / `chant approve` (#1485,
+ * epic #1487) — the CLI surface for the native durable-tick operator. See
+ * `../../op/operator.ts` for the loop itself; this module is the thin CLI
+ * shell around it (discover, load activities, print), mirroring
+ * `run.ts`'s `runOpLocal` shape (SIGINT → AbortController, `loadActivities`/
+ * `loadProfiles` from the project's configured lexicons).
+ */
+import { loadChantConfig } from "../../config";
+import { discoverOps } from "../../op/discover";
+import { loadActivities, loadProfiles } from "../../op/activity-registry";
+import { parseDuration } from "../../op/local-executor";
+import {
+  discoverConvergeOps,
+  runOperatorRound,
+  runOperatorForever,
+  formatRoundLine,
+  DEFAULT_OPERATOR_INTERVAL_MS,
+  type OperatorTickEvent,
+} from "../../op/operator";
+import { readLease, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease";
+import { readConvergeLedger, type ConvergeTickRecord } from "../../lifecycle/converge-ledger";
+import { appendGateResolution, readGateResolutions, latestResolutionSince } from "../../lifecycle/gate-ledger";
+import { pushLifecycle } from "../../lifecycle/git";
+import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
+import type { CommandContext } from "../registry";
+
+/** Load the activities a local tick needs, the same way `runOpLocal` does: base temporal activities plus whatever the project's configured lexicons contribute. Best-effort on the lexicon list — an unreadable `chant.config.ts` falls back to base activities only. */
+async function loadOperatorActivities() {
+  let lexicons: string[] = [];
+  try {
+    lexicons = (await loadChantConfig(process.cwd())).config.lexicons ?? [];
+  } catch {
+    // No/invalid chant.config — fall back to base activities only.
+  }
+  return Promise.all([loadActivities(lexicons), loadProfiles()]);
+}
+
+// ── chant operator ──────────────────────────────────────────────────────────
+
+/**
+ * `chant operator [--env <env>] [--interval <duration>] [--lease-ttl
+ * <duration>] [--once]` — run scheduled ticks for this project's discovered
+ * ConvergeOps, locally, with no Temporal installed (issue's own worked
+ * example). `--once` runs a single round and exits (also the offline test
+ * story, and what a cron/systemd-timer/k8s-CronJob invoker uses instead of
+ * leaving the daemon running); omitted, the daemon loops until Ctrl-C.
+ */
+export async function runOperator(ctx: CommandContext): Promise<number> {
+  const { ops, errors } = await discoverConvergeOps({ env: ctx.args.env });
+  for (const err of errors) console.error(formatWarning({ message: err }));
+
+  if (ops.length === 0) {
+    console.error(formatWarning({
+      message: ctx.args.env
+        ? `No ConvergeOp declarations found for env "${ctx.args.env}"`
+        : "No ConvergeOp declarations found (*.op.ts built with ConvergeOp(...))",
+    }));
+    return 0;
+  }
+
+  let activities, profiles;
+  try {
+    [activities, profiles] = await loadOperatorActivities();
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+
+  const intervalMs = ctx.args.interval ? parseDuration(ctx.args.interval) : DEFAULT_OPERATOR_INTERVAL_MS;
+  const leaseTtlMs = ctx.args.leaseTtl ? parseDuration(ctx.args.leaseTtl) : DEFAULT_LEASE_TTL_MS;
+
+  const controller = new AbortController();
+  const onSigint = () => {
+    console.error(formatWarning({ message: "interrupted — stopping operator" }));
+    controller.abort();
+  };
+  process.once("SIGINT", onSigint);
+
+  const printRound = (events: OperatorTickEvent[]) => {
+    for (const event of events) console.error(formatInfo(formatRoundLine(event)));
+  };
+
+  try {
+    if (ctx.args.once) {
+      const events = await runOperatorRound({ env: ctx.args.env, leaseTtlMs, activities, profiles, signal: controller.signal });
+      printRound(events);
+      return events.some((e) => e.kind === "tick-failed") ? 1 : 0;
+    }
+
+    console.error(formatInfo(
+      `chant operator: watching ${ops.length} ConvergeOp(s) every ${intervalMs}ms (Ctrl-C to stop)`,
+    ));
+    await runOperatorForever({
+      env: ctx.args.env,
+      intervalMs,
+      leaseTtlMs,
+      activities,
+      profiles,
+      signal: controller.signal,
+      onRound: printRound,
+    });
+    return 0;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}
+
+// ── chant operator status ───────────────────────────────────────────────────
+
+interface OpStatusLine {
+  op: string;
+  env: string;
+  lastTick?: ConvergeTickRecord;
+  pendingGates: { rule: string; op?: string; gate: string }[];
+  lease?: { holder: string; expiresAt: string };
+}
+
+async function statusFor(opName: string, env: string, cwd?: string): Promise<OpStatusLine> {
+  const [{ records }, { record: lease }] = await Promise.all([
+    readConvergeLedger(env, { cwd }),
+    readLease(opName, { cwd }),
+  ]);
+  const ownRecords = records.filter((r) => r.op === opName);
+  const lastTick = ownRecords.at(-1);
+
+  const pendingGates: OpStatusLine["pendingGates"] = [];
+  if (lastTick) {
+    for (const outcome of lastTick.outcomes) {
+      if (outcome.action !== "gated" || !outcome.gateName || !outcome.op) continue;
+      const { records: resolutions } = await readGateResolutions(outcome.op, { cwd });
+      const resolved = latestResolutionSince(resolutions, outcome.gateName, lastTick.timestamp);
+      if (!resolved) pendingGates.push({ rule: outcome.ruleId, op: outcome.op, gate: outcome.gateName });
+    }
+  }
+
+  return {
+    op: opName,
+    env,
+    lastTick,
+    pendingGates,
+    lease: lease ? { holder: lease.holder, expiresAt: lease.expiresAt } : undefined,
+  };
+}
+
+/**
+ * `chant operator status [--env <env>] [--json]` — last tick, outcome
+ * counts, and pending gates, read from the `chant/lifecycle` orphan branch
+ * alone (issue acceptance criterion). No live query, no daemon needs to be
+ * running: everything here was already durably recorded by whichever
+ * process (this operator, a bare `chant run <op>`, or another machine's
+ * operator) ran the last tick.
+ */
+export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
+  const { ops, errors } = await discoverConvergeOps({ env: ctx.args.env });
+  for (const err of errors) console.error(formatWarning({ message: err }));
+
+  if (ops.length === 0) {
+    console.error(formatWarning({ message: "No ConvergeOp declarations found" }));
+    return 0;
+  }
+
+  const rows = await Promise.all(
+    ops.map((d) => statusFor(d.config.name, d.config.searchAttributes?.Env ?? "unknown")),
+  );
+
+  if (ctx.args.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+
+  for (const row of rows) {
+    console.log(formatBold(`${row.op} (${row.env})`));
+    if (!row.lastTick) {
+      console.log("  no ticks recorded yet");
+    } else {
+      console.log(`  last tick : ${row.lastTick.timestamp}`);
+      console.log(`  ${row.lastTick.log}`);
+    }
+    console.log(`  lease     : ${row.lease ? `held by ${row.lease.holder} (expires ${row.lease.expiresAt})` : "free"}`);
+    if (row.pendingGates.length > 0) {
+      console.log(`  pending gates:`);
+      for (const g of row.pendingGates) {
+        console.log(`    - ${g.op ?? row.op} gate "${g.gate}" (rule ${g.rule}) — resolve: chant approve ${g.op ?? row.op} ${g.gate}`);
+      }
+    }
+    console.log("");
+  }
+
+  return 0;
+}
+
+// ── chant approve <op> <gate> ───────────────────────────────────────────────
+
+/**
+ * `chant approve <op> <gate> [--actor <name>] [--note <text>]` — record the
+ * out-of-band resolution fact for a gate a converge tick recorded as gated
+ * (issue: "resolution is an out-of-band act that writes the counterpart
+ * fact"). Per the issue's own leaning on open question 3 ("local trust in
+ * v1"), this performs no authorization check beyond "you can run `chant
+ * approve` locally" — see `../../lifecycle/gate-ledger.ts`'s doc for what
+ * this record does and, just as importantly, does not (yet) do: it does
+ * not retroactively unblock the gated op's own local dispatch, which the
+ * local executor still refuses unconditionally.
+ */
+export async function runApprove(ctx: CommandContext): Promise<number> {
+  const opName = ctx.args.path;
+  const gate = ctx.args.extraPositional;
+  if (!opName || opName === "." || !gate) {
+    console.error(formatError({ message: "Usage: chant approve <op> <gate>" }));
+    return 1;
+  }
+
+  const { ops } = await discoverOps();
+  if (!ops.has(opName)) {
+    console.error(formatWarning({
+      message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
+    }));
+  }
+
+  const resolvedBy = ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+
+  const { record } = await appendGateResolution({
+    op: opName,
+    gate,
+    resolvedBy,
+    timestamp: new Date().toISOString(),
+    ...(ctx.args.note ? { note: ctx.args.note } : {}),
+  });
+  await pushLifecycle().catch(() => undefined);
+
+  console.error(formatSuccess(
+    `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy} at ${record.timestamp}`,
+  ));
+  console.error(formatInfo(
+    "This records the resolution as a fact; it does not itself re-run the gated dispatch — " +
+      "the local executor still refuses any op with a gate. Re-run it with --temporal, or via the PR that carries the change.",
+  ));
+  return 0;
+}