@intentius/chant 0.52.2 → 0.53.1

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

@@ -54,7 +54,7 @@ vi.mock("../../lifecycle/git", async () => {
 });
 
 // Imported after the mocks above are registered.
-const { runOperator, runOperatorStatus, runApprove } = await import("./operator");
+const { runOperator, runOperatorStatus, runOperatorLog, runApprove } = await import("./operator");
 
 function ctx(args: Partial<ParsedArgs>) {
   return {
@@ -180,6 +180,77 @@ describe("runOperatorStatus", () => {
     logSpy.mockRestore();
   });
 
+  // #2028 — the pending fact is the one a human has to act on, so it is the
+  // one that has to carry a link. Before this the row was {rule, op, gate}
+  // and the only affordance a renderer could offer was a shell command.
+  test("a gated outcome's approval url rides onto the pending-gate row", 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",
+            url: "https://github.com/INTENTIUS/chant/pull/2028",
+          }],
+          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: [], 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([
+      { rule: "drift-apply", op: "fountain-apply", gate: "rollout-gate", url: "https://github.com/INTENTIUS/chant/pull/2028" },
+    ]);
+    logSpy.mockRestore();
+  });
+
+  test("the human render prints the address under the pending gate", 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", url: "https://pr.example/1" }],
+          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: [], malformed: 0 });
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runOperatorStatus(ctx({}));
+    const out = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("approve at: https://pr.example/1");
+    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" } } }],
@@ -239,6 +310,57 @@ describe("runApprove", () => {
     errSpy.mockRestore();
   });
 
+  // #2028 — the resolution's link is typed, so a reader is not sniffing
+  // free-text `note` for something that looks like a URL.
+  test("--url is recorded typed, alongside --note's prose", async () => {
+    vi.stubEnv("GITHUB_REF_NAME", "");
+    vi.stubEnv("GITHUB_REPOSITORY", "");
+    vi.stubEnv("CI_MERGE_REQUEST_PROJECT_URL", "");
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", url: "https://github.com/org/repo/pull/9" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({
+      path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex",
+      note: "rolled staging first", url: "https://github.com/org/repo/pull/9",
+    }));
+
+    expect(code).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(
+      expect.objectContaining({ note: "rolled staging first", url: "https://github.com/org/repo/pull/9" }),
+    );
+    errSpy.mockRestore();
+    vi.unstubAllEnvs();
+  });
+
+  test("without --url, the surrounding PR/MR job is itself the address", async () => {
+    vi.stubEnv("GITHUB_SERVER_URL", "https://github.com");
+    vi.stubEnv("GITHUB_REPOSITORY", "INTENTIUS/chant");
+    vi.stubEnv("GITHUB_REF_NAME", "2028/merge");
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "g", 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: "g", actor: "alex" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(
+      expect.objectContaining({ url: "https://github.com/INTENTIUS/chant/pull/2028" }),
+    );
+    errSpy.mockRestore();
+    vi.unstubAllEnvs();
+  });
+
+  test("a --url that is not an absolute http/https link is refused, and nothing is written", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "g", url: "org/repo/pull/1" }));
+    expect(code).toBe(1);
+    expect(appendGateResolutionMock).not.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({
@@ -253,3 +375,182 @@ describe("runApprove", () => {
     errSpy.mockRestore();
   });
 });
+
+// ── chant operator log (#2029) ────────────────────────────────────────────────
+
+describe("runOperatorLog", () => {
+  function tick(over: Record<string, unknown> = {}) {
+    return {
+      version: 1,
+      id: "11111111-2222-3333-4444-555555555555",
+      op: "staging-converge",
+      env: "staging",
+      timestamp: "2026-01-01T00:00:00.000Z",
+      firedRuleIds: [],
+      outcomes: [],
+      summary: { drifted: 0, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0 },
+      log: "converge(staging): drifted=0",
+      ...over,
+    };
+  }
+
+  beforeEach(() => {
+    discoverConvergeOpsMock.mockResolvedValue({
+      ops: [{ config: { name: "staging-converge", searchAttributes: { Env: "staging" } } }],
+      errors: [],
+    });
+    readGateResolutionsMock.mockResolvedValue({ records: [], malformed: 0 });
+  });
+
+  test("--json emits the whole tick history, not just the newest row", async () => {
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [
+        tick({ id: "t1", timestamp: "2026-01-01T00:00:00.000Z" }),
+        tick({ id: "t2", timestamp: "2026-01-01T01:00:00.000Z" }),
+        tick({ id: "t3", timestamp: "2026-01-01T02:00:00.000Z" }),
+      ],
+      malformed: 0,
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    expect(await runOperatorLog(ctx({ json: true }))).toBe(0);
+
+    const printed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(printed.entries.map((e: { record: { id: string } }) => e.record.id)).toEqual(["t1", "t2", "t3"]);
+    expect(printed.malformed).toEqual({ converge: 0, gates: 0 });
+    logSpy.mockRestore();
+  });
+
+  test("carries the malformed-line count, so a short timeline is never silently short", async () => {
+    readConvergeLedgerMock.mockResolvedValue({ records: [tick()], malformed: 3 });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await runOperatorLog(ctx({ json: true }));
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string).malformed.converge).toBe(3);
+
+    logSpy.mockClear();
+    await runOperatorLog(ctx({}));
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain("3 ledger line(s) were unreadable");
+
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+  });
+
+  test("gate resolutions are merged into the timeline, in timestamp order after the tick that gated", async () => {
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [
+        tick({
+          id: "t1",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          outcomes: [{ ruleId: "drift-apply", action: "gated", op: "fountain-apply", gateName: "rollout-gate", url: "https://pr.example/1" }],
+        }),
+        tick({ id: "t2", timestamp: "2026-01-03T00:00:00.000Z" }),
+      ],
+      malformed: 0,
+    });
+    readGateResolutionsMock.mockResolvedValue({
+      records: [{ version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-02T00:00:00.000Z", url: "https://pr.example/1" }],
+      malformed: 0,
+    });
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runOperatorLog(ctx({ json: true }));
+    const printed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(printed.entries.map((e: { kind: string }) => e.kind)).toEqual(["tick", "gate-resolution", "tick"]);
+    expect(readGateResolutionsMock).toHaveBeenCalledWith("fountain-apply", expect.anything());
+    logSpy.mockRestore();
+  });
+
+  test("--since drops everything older, --limit keeps the newest n (still oldest-first)", async () => {
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [
+        tick({ id: "t1", timestamp: "2026-01-01T00:00:00.000Z" }),
+        tick({ id: "t2", timestamp: "2026-01-02T00:00:00.000Z" }),
+        tick({ id: "t3", timestamp: "2026-01-03T00:00:00.000Z" }),
+        tick({ id: "t4", timestamp: "2026-01-04T00:00:00.000Z" }),
+      ],
+      malformed: 0,
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await runOperatorLog(ctx({ json: true, since: "2026-01-02T00:00:00.000Z" }));
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string).entries.map((e: { record: { id: string } }) => e.record.id))
+      .toEqual(["t2", "t3", "t4"]);
+
+    logSpy.mockClear();
+    await runOperatorLog(ctx({ json: true, limit: 2 }));
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string).entries.map((e: { record: { id: string } }) => e.record.id))
+      .toEqual(["t3", "t4"]);
+
+    logSpy.mockRestore();
+  });
+
+  test("--op restricts to one ConvergeOp", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({
+      ops: [
+        { config: { name: "staging-converge", searchAttributes: { Env: "staging" } } },
+        { config: { name: "other-converge", searchAttributes: { Env: "staging" } } },
+      ],
+      errors: [],
+    });
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [tick({ id: "t1" }), tick({ id: "t2", op: "other-converge" })],
+      malformed: 0,
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runOperatorLog(ctx({ json: true, op: "other-converge" }));
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string).entries.map((e: { record: { id: string } }) => e.record.id))
+      .toEqual(["t2"]);
+    logSpy.mockRestore();
+  });
+
+  test("two ConvergeOps sharing one environment read that ledger once", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({
+      ops: [
+        { config: { name: "staging-converge", searchAttributes: { Env: "staging" } } },
+        { config: { name: "other-converge", searchAttributes: { Env: "staging" } } },
+      ],
+      errors: [],
+    });
+    readConvergeLedgerMock.mockResolvedValue({ records: [tick()], malformed: 2 });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runOperatorLog(ctx({ json: true }));
+    expect(readConvergeLedgerMock).toHaveBeenCalledTimes(1);
+    // ...and its malformed count is not double-counted.
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string).malformed.converge).toBe(2);
+    logSpy.mockRestore();
+  });
+
+  test("refuses an unparseable --since and a non-positive --limit without reading anything", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(await runOperatorLog(ctx({ since: "last tuesday" }))).toBe(1);
+    expect(await runOperatorLog(ctx({ limit: 0 }))).toBe(1);
+    expect(await runOperatorLog(ctx({ limit: 1.5 }))).toBe(1);
+    expect(readConvergeLedgerMock).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
+  test("prints the tick id, log line and gated outcomes in the human render", async () => {
+    readConvergeLedgerMock.mockResolvedValue({
+      records: [tick({
+        id: "abcdef01-2222-3333-4444-555555555555",
+        outcomes: [{ ruleId: "drift-apply", action: "gated", op: "fountain-apply", gateName: "rollout-gate", url: "https://pr.example/1" }],
+      })],
+      malformed: 0,
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runOperatorLog(ctx({}));
+    const out = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("[abcdef01]");
+    expect(out).toContain("converge(staging): drifted=0");
+    expect(out).toContain('gated  drift-apply → fountain-apply gate "rollout-gate"  https://pr.example/1');
+    logSpy.mockRestore();
+  });
+
+  test("exits 0 with a warning when no ConvergeOps are discovered", async () => {
+    discoverConvergeOpsMock.mockResolvedValue({ ops: [], errors: [] });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(await runOperatorLog(ctx({}))).toBe(0);
+    errSpy.mockRestore();
+  });
+});

package/src/cli/handlers/operator.ts

@@ -20,7 +20,8 @@ import {
 } 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 type { GateResolutionRecord } from "../../lifecycle/gate-ledger";
+import { appendGateResolution, readGateResolutions, latestResolutionSince, resolveApprovalUrl, isApprovalUrl } from "../../lifecycle/gate-ledger";
 import { pushLifecycle } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
@@ -112,7 +113,8 @@ interface OpStatusLine {
   op: string;
   env: string;
   lastTick?: ConvergeTickRecord;
-  pendingGates: { rule: string; op?: string; gate: string }[];
+  /** `url` (#2028) is the gate's approval surface, when the tick that recorded it knew one — what a renderer points its approve affordance at instead of a shell command. */
+  pendingGates: { rule: string; op?: string; gate: string; url?: string }[];
   lease?: { holder: string; expiresAt: string };
 }
 
@@ -130,7 +132,14 @@ async function statusFor(opName: string, env: string, cwd?: string): Promise<OpS
       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 });
+      if (!resolved) {
+        pendingGates.push({
+          rule: outcome.ruleId,
+          op: outcome.op,
+          gate: outcome.gateName,
+          ...(outcome.url ? { url: outcome.url } : {}),
+        });
+      }
     }
   }
 
@@ -182,6 +191,7 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
       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}`);
+        if (g.url) console.log(`      approve at: ${g.url}`);
       }
     }
     console.log("");
@@ -190,10 +200,174 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+// ── chant operator log ──────────────────────────────────────────────────────
+
+/** One entry of the merged tick/gate timeline `chant operator log` prints. */
+export type OperatorLogEntry =
+  | { kind: "tick"; timestamp: string; record: ConvergeTickRecord }
+  | { kind: "gate-resolution"; timestamp: string; record: GateResolutionRecord };
+
+export interface OperatorLogResult {
+  entries: OperatorLogEntry[];
+  /**
+   * Unreadable lines behind this answer, per ledger. `readConvergeLedger` and
+   * `readGateResolutions` both skip a malformed line and count it rather than
+   * throwing, so a corrupted ledger renders a shorter timeline; without this a
+   * consumer could not tell that from a genuinely quiet environment.
+   */
+  malformed: { converge: number; gates: number };
+}
+
+/**
+ * Gather the converge/gate history a set of ConvergeOps has recorded, merged
+ * into one timestamp-ordered timeline, oldest first.
+ *
+ * `since` (inclusive) and `limit` are applied after the merge — `limit` keeps
+ * the *newest* n entries, since that is what a log is asked for, and then
+ * prints them oldest-first like every other log.
+ */
+export async function collectOperatorLog(
+  ops: { name: string; env: string }[],
+  opts: { op?: string; since?: string; limit?: number; cwd?: string } = {},
+): Promise<OperatorLogResult> {
+  const wanted = opts.op ? ops.filter((o) => o.name === opts.op) : ops;
+  const sinceMs = opts.since ? new Date(opts.since).getTime() : undefined;
+
+  const entries: OperatorLogEntry[] = [];
+  const malformed = { converge: 0, gates: 0 };
+
+  // One read per distinct environment — several ConvergeOps can share one
+  // `<env>/converge.jsonl`, and re-reading it per op would both cost more and
+  // double-count its malformed lines.
+  const envs = [...new Set(wanted.map((o) => o.env))].sort();
+  const opNames = new Set(wanted.map((o) => o.name));
+  const gateOps = new Set<string>();
+
+  for (const env of envs) {
+    const { records, malformed: bad } = await readConvergeLedger(env, { cwd: opts.cwd });
+    malformed.converge += bad;
+    for (const record of records) {
+      if (!opNames.has(record.op)) continue;
+      for (const outcome of record.outcomes) {
+        if (outcome.action === "gated" && outcome.op) gateOps.add(outcome.op);
+      }
+      entries.push({ kind: "tick", timestamp: record.timestamp, record });
+    }
+  }
+
+  for (const gateOp of [...gateOps].sort()) {
+    const { records, malformed: bad } = await readGateResolutions(gateOp, { cwd: opts.cwd });
+    malformed.gates += bad;
+    for (const record of records) {
+      entries.push({ kind: "gate-resolution", timestamp: record.timestamp, record });
+    }
+  }
+
+  let merged = entries.sort((a, b) => {
+    const delta = new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+    // A gate resolution recorded in the same instant as a tick reads after it:
+    // the tick is what made the gate pending in the first place.
+    return delta !== 0 ? delta : (a.kind === b.kind ? 0 : a.kind === "tick" ? -1 : 1);
+  });
+  if (sinceMs !== undefined) merged = merged.filter((e) => new Date(e.timestamp).getTime() >= sinceMs);
+  if (opts.limit !== undefined && merged.length > opts.limit) merged = merged.slice(-opts.limit);
+
+  return { entries: merged, malformed };
+}
+
+function renderLogEntry(entry: OperatorLogEntry): string[] {
+  if (entry.kind === "gate-resolution") {
+    const { record } = entry;
+    return [
+      `${record.timestamp}  gate-resolved  ${record.op}/${record.gate} by ${record.resolvedBy}` +
+        (record.url ? `  ${record.url}` : ""),
+    ];
+  }
+
+  const { record } = entry;
+  const id = record.id ? `[${record.id.slice(0, 8)}]` : "[--------]";
+  const lines = [`${record.timestamp}  ${record.op}@${record.env}  ${id}  ${record.log}`];
+  for (const outcome of record.outcomes) {
+    if (outcome.action !== "gated" || !outcome.gateName) continue;
+    lines.push(
+      `    gated  ${outcome.ruleId} → ${outcome.op ?? "?"} gate "${outcome.gateName}"` +
+        (outcome.url ? `  ${outcome.url}` : ""),
+    );
+  }
+  return lines;
+}
+
+/**
+ * `chant operator log [--env <env>] [--op <name>] [--since <iso>] [--limit
+ * <n>] [--json]` (#2029) — the converge tick history and the gate resolutions
+ * against it, read from the `chant/lifecycle` orphan branch alone.
+ *
+ * `readConvergeLedger` has always returned every tick for an environment;
+ * until this its only caller was `operator status`, which threw the history
+ * away and kept `.at(-1)`. A consumer wanting more than the newest row had to
+ * `git show chant/lifecycle:<env>/converge.jsonl` and parse it — which pins it
+ * to the orphan branch's name, the `<env>/converge.jsonl` path convention, the
+ * `_gates/<op>.jsonl` convention and the on-disk encoding, none of which are
+ * promised contracts. This is the read surface that makes those private again.
+ *
+ * Read-only: no lease, no dispatch, no daemon. Same `--json` discipline as
+ * `operator status` — one JSON document on stdout, diagnostics on stderr.
+ */
+export async function runOperatorLog(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;
+  }
+
+  if (ctx.args.since && Number.isNaN(new Date(ctx.args.since).getTime())) {
+    console.error(formatError({
+      message: `--since must be an ISO-8601 timestamp (got "${ctx.args.since}")`,
+      hint: "e.g. --since 2026-01-01T00:00:00Z",
+    }));
+    return 1;
+  }
+  if (ctx.args.limit !== undefined && (!Number.isInteger(ctx.args.limit) || ctx.args.limit < 1)) {
+    console.error(formatError({ message: `--limit must be a positive integer (got "${ctx.args.limit}")` }));
+    return 1;
+  }
+
+  const { entries, malformed } = await collectOperatorLog(
+    ops.map((d) => ({ name: d.config.name, env: d.config.searchAttributes?.Env ?? "unknown" })),
+    { op: ctx.args.op, since: ctx.args.since, limit: ctx.args.limit },
+  );
+
+  if (ctx.args.json) {
+    console.log(JSON.stringify({ entries, malformed }, null, 2));
+    return 0;
+  }
+
+  const unreadable = malformed.converge + malformed.gates;
+  if (unreadable > 0) {
+    console.error(formatWarning({
+      message: `${unreadable} ledger line(s) were unreadable and are missing from this timeline ` +
+        `(converge: ${malformed.converge}, gates: ${malformed.gates})`,
+    }));
+  }
+
+  if (entries.length === 0) {
+    console.error(formatWarning({ message: "No converge ticks recorded yet" }));
+    return 0;
+  }
+
+  for (const entry of entries) {
+    for (const line of renderLogEntry(entry)) console.log(line);
+  }
+  return 0;
+}
+
 // ── chant approve <op> <gate> ───────────────────────────────────────────────
 
 /**
- * `chant approve <op> <gate> [--actor <name>] [--note <text>]` — record the
+ * `chant approve <op> <gate> [--actor <name>] [--note <text>] [--url <url>]`
+ * — 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
@@ -220,17 +394,31 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
 
   const resolvedBy = ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
 
+  // #2028: the resolution's link is typed. `--url` wins; otherwise, running
+  // inside the PR/MR job that carries the change is itself the address, the
+  // same env fallback `--actor` uses. `--note` stays free-text prose.
+  const url = ctx.args.url ?? resolveApprovalUrl();
+  if (url && !isApprovalUrl(url)) {
+    console.error(formatError({
+      message: `--url must be an absolute http/https URL (got "${url}")`,
+      hint: "Pass the PR/MR link, or omit --url and put prose in --note.",
+    }));
+    return 1;
+  }
+
   const { record } = await appendGateResolution({
     op: opName,
     gate,
     resolvedBy,
     timestamp: new Date().toISOString(),
     ...(ctx.args.note ? { note: ctx.args.note } : {}),
+    ...(url ? { url } : {}),
   });
   await pushLifecycle().catch(() => undefined);
 
   console.error(formatSuccess(
-    `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy} at ${record.timestamp}`,
+    `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy} at ${record.timestamp}` +
+      (record.url ? ` (${record.url})` : ""),
   ));
   console.error(formatInfo(
     "This records the resolution as a fact; it does not itself re-run the gated dispatch — " +

package/src/cli/handlers/run.ts

@@ -22,7 +22,7 @@ import {
   type WorkflowHistoryRaw,
 } from "./run-client";
 import { generateReport, writeReport } from "./run-report";
-import { extractStepRecords, countActivities, queryGateState } from "./op-progress";
+import { extractIndexedStepRecords, stepRecordEmitter, countActivities, queryGateState } from "./op-progress";
 import { runComponents, resolveComponentTargets, findComponentGate, listComponents } from "../../components/cli-support";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
@@ -1293,17 +1293,15 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
   // `--progress-json` (chant #1676): stream one NDJSON StepRecord per line to
   // stdout as each declared step settles — the durable-path counterpart to
   // `chant run <name> --json`'s local-executor record shape (op-progress.ts).
-  // Purely additive: when the flag is absent `emitProgress` stays undefined
-  // and every `emitProgress?.(...)` call is a no-op, so poll-loop behavior
-  // is unchanged. `extractStepRecords` is stable and append-only across
-  // polls (same declared order, a growing history), so a plain emitted-count
-  // watermark is enough to emit only what's new each round.
+  // Purely additive: when the flag is absent `emitNewRecords` stays undefined
+  // and every call site is a no-op, so poll-loop behavior is unchanged.
+  //
+  // Dedup is by declared-step identity, not by an emitted count (chant #2032):
+  // the terminal `final: true` pass *inserts* a `"skipped"` record at each
+  // never-reached step's declared position, so the list is not append-only and
+  // a count watermark shifts off the end of it.
   const emitProgress = ctx.args.progressJson ? ndjsonProgressSink<StepRecord>() : undefined;
-  let emittedCount = 0;
-  const emitNewRecords = (records: StepRecord[]) => {
-    for (const record of records.slice(emittedCount)) emitProgress?.(record);
-    emittedCount = records.length;
-  };
+  const emitNewRecords = emitProgress ? stepRecordEmitter(emitProgress) : undefined;
 
   let finalDesc: WorkflowExecutionDescription | undefined;
   let finalHistory: WorkflowHistoryRaw | undefined;
@@ -1315,11 +1313,11 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
       const history = await fetchNormalizedHistory(handle);
 
       renderProgress(opName, history);
-      if (emitProgress) emitNewRecords(extractStepRecords(config, history));
+      emitNewRecords?.(extractIndexedStepRecords(config, history));
 
       if (TERMINAL_STATUSES.has(desc.status.name)) {
         process.stderr.write("\n");
-        if (emitProgress) emitNewRecords(extractStepRecords(config, history, { final: true }));
+        emitNewRecords?.(extractIndexedStepRecords(config, history, { final: true }));
         finalDesc = desc;
         finalHistory = history;
         break;

package/src/cli/main.test.ts

@@ -256,6 +256,25 @@ describe("parseArgs", () => {
     expect(result.json).toBe(true);
   });
 
+  test("parses --op, --since and --limit for operator log (#2029)", () => {
+    const result = parseArgs([
+      "operator", "log", "--env", "staging", "--op", "staging-converge",
+      "--since", "2026-01-01T00:00:00Z", "--limit", "20", "--json",
+    ]);
+    expect(result.command).toBe("operator");
+    expect(result.path).toBe("log");
+    expect(result.env).toBe("staging");
+    expect(result.op).toBe("staging-converge");
+    expect(result.since).toBe("2026-01-01T00:00:00Z");
+    expect(result.limit).toBe(20);
+    expect(result.json).toBe(true);
+  });
+
+  test("parses --url for approve (#2028)", () => {
+    const result = parseArgs(["approve", "fountain-apply", "rollout-gate", "--url", "https://github.com/org/repo/pull/1"]);
+    expect(result.url).toBe("https://github.com/org/repo/pull/1");
+  });
+
   // ── --no-release-record (#597) ───────────────────────────────────────────
 
   test("parses --no-release-record for run --components", () => {