@intentius/chant 0.57.0 → 0.59.0

package/src/cli/handlers/operator.ts

@@ -7,6 +7,9 @@
  * `loadProfiles` from the project's configured lexicons).
  */
 import { loadChantConfig } from "../../config";
+import { build } from "../../build";
+import { isResourceDeclarable } from "../../declarable";
+import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins";
 import { discoverOps } from "../../op/discover";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { parseDuration } from "../../op/local-executor";
@@ -15,18 +18,27 @@ import {
   runOperatorRound,
   runOperatorForever,
   formatRoundLine,
+  formatSignalLine,
   DEFAULT_OPERATOR_INTERVAL_MS,
+  type ChangeSubscriber,
+  type OperatorSignalEvent,
   type OperatorTickEvent,
 } from "../../op/operator";
 import { readLease, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease";
 import { readConvergeLedger, type ConvergeTickRecord } from "../../lifecycle/converge-ledger";
-import type { GateResolutionRecord } from "../../lifecycle/gate-ledger";
-import { appendGateResolution, readGateResolutions, latestResolutionSince, resolveApprovalUrl, isApprovalUrl } from "../../lifecycle/gate-ledger";
+import { readRunLedger } from "../../lifecycle/run-ledger";
+import type { OpRunRecord } from "../../op/runtime";
+import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger";
+import {
+  appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger,
+  latestResolutionSince, latestPendingGate, isPendingGateExpired,
+  resolveApprovalUrl, isApprovalUrl,
+} 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. */
+/** Load the activities a local tick needs, the same way a local run does: core's base 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 {
@@ -37,12 +49,82 @@ async function loadOperatorActivities() {
   return Promise.all([loadActivities(lexicons), loadProfiles()]);
 }
 
+/**
+ * Bind the change-signal seams (#1981) the daemon will keep subscribed, or an
+ * empty list.
+ *
+ * Three gates, in cost order, so a project that gains nothing from this pays
+ * nothing for it:
+ *
+ * 1. No configured lexicon implements `subscribeChanges`. Return immediately,
+ *    without loading config or building anything. This is every project today.
+ * 2. No `--env`. A subscription resolves the same cluster binding a read
+ *    does, and there is no binding to resolve without an environment. Said out
+ *    loud rather than silently skipped, because "why did it not wake" is
+ *    otherwise unanswerable.
+ * 3. The build that supplies the declared entities failed. Warn and fall back
+ *    to the timer. A subscription is an optimization; a build error here must
+ *    not stop the operator, which has its own per-tick build inside the tick.
+ */
+async function collectOperatorSubscribers(
+  ctx: CommandContext,
+  env: string | undefined,
+): Promise<ChangeSubscriber[]> {
+  if (!ctx.plugins.some((p) => typeof p.subscribeChanges === "function")) return [];
+
+  if (!env) {
+    console.error(formatWarning({
+      message: "a change signal needs an environment to resolve its binding, so this runs on the timer alone",
+      hint: "pass --env <env> to let a lexicon's subscribeChanges wake a tick early",
+    }));
+    return [];
+  }
+
+  const cwd = process.cwd();
+  try {
+    const { config } = await loadChantConfig(cwd);
+    const buildRoots = collectBuildRootContributors(
+      ctx.plugins,
+      config as unknown as Record<string, unknown>,
+      cwd,
+    );
+    const buildResult = await build(config.sourceDir ?? ".", ctx.serializers, undefined, { buildRoots });
+    if (buildResult.errors.length > 0) {
+      console.error(formatWarning({
+        message: "build failed while scoping the change signal, so this runs on the timer alone",
+      }));
+      return [];
+    }
+
+    // The declared estate, sliced per lexicon: the same slice
+    // `takeSnapshot` hands `describeResources`, and the bound on what any
+    // subscription may watch.
+    const entities = new Map<string, Map<string, { entityType: string; props: Record<string, unknown> }>>();
+    for (const [name, entity] of buildResult.entities) {
+      if (!isResourceDeclarable(entity)) continue;
+      let perLexicon = entities.get(entity.lexicon);
+      if (!perLexicon) entities.set(entity.lexicon, (perLexicon = new Map()));
+      perLexicon.set(name, {
+        entityType: entity.entityType,
+        props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+      });
+    }
+
+    return collectChangeSubscribers(ctx.plugins, { environment: env, cwd, entities });
+  } catch (err) {
+    console.error(formatWarning({
+      message: `could not scope the change signal, so this runs on the timer alone (${err instanceof Error ? err.message : String(err)})`,
+    }));
+    return [];
+  }
+}
+
 // ── 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
+ * ConvergeOps, locally, with no service to install (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.
@@ -92,6 +174,9 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(
       `chant operator: watching ${ops.length} ConvergeOp(s) every ${intervalMs}ms (Ctrl-C to stop)`,
     ));
+    // A change signal (#1981) only ever shortens the sleep above. Every round
+    // it wakes is the round the timer would have run.
+    const subscribers = await collectOperatorSubscribers(ctx, ctx.args.env);
     await runOperatorForever({
       env: ctx.args.env,
       intervalMs,
@@ -100,6 +185,8 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
       profiles,
       signal: controller.signal,
       onRound: printRound,
+      subscribers,
+      onSignalEvent: (event: OperatorSignalEvent) => console.error(formatInfo(formatSignalLine(event))),
     });
     return 0;
   } finally {
@@ -113,11 +200,37 @@ interface OpStatusLine {
   op: string;
   env: string;
   lastTick?: ConvergeTickRecord;
-  /** `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 }[];
+  /** `url` (#2028) is the gate's approval surface, when whatever recorded it knew one — what a renderer points its approve affordance at instead of a shell command. `rule` is present only for a gate a converge rule's dispatch reached; a gate an ordinary `chant run` stopped at has none. */
+  pendingGates: { rule?: string; op?: string; gate: string; url?: string; expiresAt?: string; description?: string }[];
   lease?: { holder: string; expiresAt: string };
 }
 
+/**
+ * Every gate an op is currently standing at, read from its own gate ledger
+ * (#2119) — a live (unexpired) pending fact with no resolution newer than it.
+ *
+ * Ledger-first, so `chant operator status` sees a gate any run recorded, not
+ * only one a converge tick's dispatch reached. Before this, a plain `chant run
+ * <op>` could not produce a pending gate at all (the executor refused the op
+ * outright), so reading the converge ledger's `gated` outcomes was the whole
+ * story; now it is one source among the ops' own.
+ */
+export async function pendingGatesFor(
+  opName: string,
+  opts: { cwd?: string; now?: string } = {},
+): Promise<PendingGateRecord[]> {
+  const now = opts.now ?? new Date().toISOString();
+  const { resolutions, pending } = await readGateLedger(opName, { cwd: opts.cwd });
+  const standing: PendingGateRecord[] = [];
+  for (const gate of new Set(pending.map((p) => p.gate))) {
+    const latest = latestPendingGate(pending, gate);
+    if (!latest || isPendingGateExpired(latest, now)) continue;
+    if (latestResolutionSince(resolutions, gate, latest.timestamp)) continue;
+    standing.push(latest);
+  }
+  return standing.sort((a, b) => a.gate.localeCompare(b.gate));
+}
+
 async function statusFor(opName: string, env: string, cwd?: string): Promise<OpStatusLine> {
   const [{ records }, { record: lease }] = await Promise.all([
     readConvergeLedger(env, { cwd }),
@@ -127,19 +240,47 @@ async function statusFor(opName: string, env: string, cwd?: string): Promise<OpS
   const lastTick = ownRecords.at(-1);
 
   const pendingGates: OpStatusLine["pendingGates"] = [];
+  const seen = new Set<string>();
+
+  // The dispatched ops this ConvergeOp's last tick recorded as gated, plus the
+  // ConvergeOp itself — a gate can sit on either.
+  const gateOps = new Set<string>([opName]);
+  const ruleFor = new Map<string, string>();
+  for (const outcome of lastTick?.outcomes ?? []) {
+    if (outcome.action !== "gated" || !outcome.gateName || !outcome.op) continue;
+    gateOps.add(outcome.op);
+    ruleFor.set(`${outcome.op}\0${outcome.gateName}`, outcome.ruleId);
+  }
+
+  for (const gateOp of [...gateOps].sort()) {
+    for (const record of await pendingGatesFor(gateOp, { cwd })) {
+      seen.add(`${gateOp}\0${record.gate}`);
+      pendingGates.push({
+        op: gateOp,
+        gate: record.gate,
+        expiresAt: record.expiresAt,
+        ...(ruleFor.get(`${gateOp}\0${record.gate}`) ? { rule: ruleFor.get(`${gateOp}\0${record.gate}`) } : {}),
+        ...(record.description ? { description: record.description } : {}),
+        ...(record.url ? { url: record.url } : {}),
+      });
+    }
+  }
+
+  // A tick that recorded a `gated` outcome before the executor started writing
+  // pending facts (#2119) still has nothing in `_gates` to read; fall back to
+  // the outcome itself so an in-flight gate isn't dropped on upgrade.
   if (lastTick) {
     for (const outcome of lastTick.outcomes) {
       if (outcome.action !== "gated" || !outcome.gateName || !outcome.op) continue;
+      if (seen.has(`${outcome.op}\0${outcome.gateName}`)) 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,
-          ...(outcome.url ? { url: outcome.url } : {}),
-        });
-      }
+      if (latestResolutionSince(resolutions, outcome.gateName, lastTick.timestamp)) continue;
+      pendingGates.push({
+        rule: outcome.ruleId,
+        op: outcome.op,
+        gate: outcome.gateName,
+        ...(outcome.url ? { url: outcome.url } : {}),
+      });
     }
   }
 
@@ -152,6 +293,15 @@ async function statusFor(opName: string, env: string, cwd?: string): Promise<OpS
   };
 }
 
+/** One op standing at a gate that no ConvergeOp row above already reported (#2119) — an ordinary `chant run <op>` records these now, so they belong on this page even where no converge tick was ever involved. */
+export interface StandaloneGateLine {
+  op: string;
+  gate: string;
+  description?: string;
+  expiresAt: string;
+  url?: string;
+}
+
 /**
  * `chant operator status [--env <env>] [--json]` — last tick, outcome
  * counts, and pending gates, read from the `chant/lifecycle` orphan branch
@@ -159,22 +309,46 @@ async function statusFor(opName: string, env: string, cwd?: string): Promise<OpS
  * 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.
+ *
+ * Pending gates are read from every discovered op's own gate ledger, not only
+ * from a converge tick's `gated` outcomes (#2119) — a gate an ordinary `chant
+ * run <op>` stopped at is the same standing fact and shows up the same way,
+ * under "pending gates" for ops with no converge tick behind them.
  */
 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) {
+  const rows = await Promise.all(
+    ops.map((d) => statusFor(d.config.name, d.config.labels?.Env ?? "unknown")),
+  );
+
+  // Every other discovered op that is standing at a gate. `discoverOps` sees
+  // the whole project, so an ApplyOp someone ran by hand this morning is here
+  // even though no ConvergeOp ever dispatched it.
+  const covered = new Set(rows.flatMap((r) => r.pendingGates.map((g) => `${g.op ?? r.op} ${g.gate}`)));
+  const { ops: allOps } = await discoverOps();
+  const standalone: StandaloneGateLine[] = [];
+  for (const opName of [...allOps.keys()].sort()) {
+    for (const record of await pendingGatesFor(opName)) {
+      if (covered.has(`${opName} ${record.gate}`)) continue;
+      standalone.push({
+        op: opName,
+        gate: record.gate,
+        expiresAt: record.expiresAt,
+        ...(record.description ? { description: record.description } : {}),
+        ...(record.url ? { url: record.url } : {}),
+      });
+    }
+  }
+
+  if (ops.length === 0 && standalone.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));
+    console.log(JSON.stringify(standalone.length > 0 ? { rows, pendingGates: standalone } : rows, null, 2));
     return 0;
   }
 
@@ -190,13 +364,28 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
     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}`);
+        const op = g.op ?? row.op;
+        console.log(
+          `    - ${op} gate "${g.gate}"${g.rule ? ` (rule ${g.rule})` : ""} — resolve: chant approve ${op} ${g.gate}`,
+        );
+        if (g.expiresAt) console.log(`      expires: ${g.expiresAt}`);
         if (g.url) console.log(`      approve at: ${g.url}`);
       }
     }
     console.log("");
   }
 
+  if (standalone.length > 0) {
+    console.log(formatBold("pending gates (no converge tick)"));
+    for (const g of standalone) {
+      console.log(`  - ${g.op} gate "${g.gate}" — resolve: chant approve ${g.op} ${g.gate}`);
+      if (g.description) console.log(`    ${g.description}`);
+      console.log(`    expires: ${g.expiresAt}`);
+      if (g.url) console.log(`    approve at: ${g.url}`);
+    }
+    console.log("");
+  }
+
   return 0;
 }
 
@@ -205,17 +394,20 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
 /** 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 };
+  | { kind: "gate-resolution"; timestamp: string; record: GateResolutionRecord }
+  /** One Op run (#2118), timestamped at the instant it ended — the tick that dispatched it precedes it. */
+  | { kind: "run"; timestamp: string; record: OpRunRecord };
 
 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.
+   * Unreadable lines behind this answer, per ledger. `readConvergeLedger`,
+   * `readGateResolutions` and `readRunLedger` all 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 };
+  malformed: { converge: number; gates: number; runs: number };
 }
 
 /**
@@ -234,7 +426,7 @@ export async function collectOperatorLog(
   const sinceMs = opts.since ? new Date(opts.since).getTime() : undefined;
 
   const entries: OperatorLogEntry[] = [];
-  const malformed = { converge: 0, gates: 0 };
+  const malformed = { converge: 0, gates: 0, runs: 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
@@ -263,11 +455,23 @@ export async function collectOperatorLog(
     }
   }
 
+  // The runs each discovered Op recorded (#2118). Keyed `<env>/runs__<op>`,
+  // so unlike the converge ledger this is one read per (env, op) pair rather
+  // than per env — a ConvergeOp's own ticks and its own runs interleave here.
+  for (const { name, env } of wanted) {
+    const { records, malformed: bad } = await readRunLedger(env, name, { cwd: opts.cwd });
+    malformed.runs += bad;
+    for (const record of records) {
+      entries.push({ kind: "run", timestamp: record.ended, record });
+    }
+  }
+
+  // Within one instant: the tick first (it is what dispatched anything else),
+  // then the run it dispatched, then the gate resolution against that run.
+  const rank: Record<OperatorLogEntry["kind"], number> = { tick: 0, run: 1, "gate-resolution": 2 };
   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);
+    return delta !== 0 ? delta : rank[a.kind] - rank[b.kind];
   });
   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);
@@ -276,6 +480,17 @@ export async function collectOperatorLog(
 }
 
 function renderLogEntry(entry: OperatorLogEntry): string[] {
+  if (entry.kind === "run") {
+    const { record } = entry;
+    const id = `[${record.id.slice(0, 8)}]`;
+    const outcomes = Object.entries(record.outcomes).map(([k, v]) => `${k}=${String(v)}`).join(" ");
+    const steps = record.phases.reduce((n, p) => n + p.steps.length, 0);
+    return [
+      `${record.ended}  ${record.op}@${record.env}  ${id}  run ${record.status} ` +
+        `phases=${record.phases.length} steps=${steps}${outcomes ? `  ${outcomes}` : ""}`,
+    ];
+  }
+
   if (entry.kind === "gate-resolution") {
     const { record } = entry;
     return [
@@ -335,7 +550,7 @@ export async function runOperatorLog(ctx: CommandContext): Promise<number> {
   }
 
   const { entries, malformed } = await collectOperatorLog(
-    ops.map((d) => ({ name: d.config.name, env: d.config.searchAttributes?.Env ?? "unknown" })),
+    ops.map((d) => ({ name: d.config.name, env: d.config.labels?.Env ?? "unknown" })),
     { op: ctx.args.op, since: ctx.args.since, limit: ctx.args.limit },
   );
 
@@ -344,16 +559,16 @@ export async function runOperatorLog(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
-  const unreadable = malformed.converge + malformed.gates;
+  const unreadable = malformed.converge + malformed.gates + malformed.runs;
   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})`,
+        `(converge: ${malformed.converge}, gates: ${malformed.gates}, runs: ${malformed.runs})`,
     }));
   }
 
   if (entries.length === 0) {
-    console.error(formatWarning({ message: "No converge ticks recorded yet" }));
+    console.error(formatWarning({ message: "No converge ticks or Op runs recorded yet" }));
     return 0;
   }
 
@@ -366,16 +581,22 @@ export async function runOperatorLog(ctx: CommandContext): Promise<number> {
 // ── chant approve <op> <gate> ───────────────────────────────────────────────
 
 /**
- * `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
- * 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.
+ * `chant approve <op> <gate> [--actor <name>] [--note <text>] [--url <url>]
+ * [--expire]` — record the out-of-band resolution fact for a gate a run
+ * stopped at (issue #1485: "resolution is an out-of-band act that writes the
+ * counterpart fact"). Per that issue's leaning on open question 3 ("local
+ * trust in v1"), this performs no authorization check beyond "you can run
+ * `chant approve` locally".
+ *
+ * Since #2119 this closes the loop rather than just narrating it: the next
+ * `chant run <op>` reads the resolution, finds it newer than the gate's
+ * pending fact, and walks through.
+ *
+ * `--expire` is the other half — clear a standing pending fact *without*
+ * approving anything, for a gate that was recorded against a run nobody
+ * intends to finish. It writes no resolution; it appends a pending fact that
+ * is already expired, which supersedes the standing one on an append-only
+ * ledger, so the next run decides the gate from scratch.
  */
 export async function runApprove(ctx: CommandContext): Promise<number> {
   const opName = ctx.args.path;
@@ -385,6 +606,75 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  if (ctx.args.expire) {
+    const now = new Date().toISOString();
+    const standing = latestPendingGate((await readGateLedger(opName)).pending, gate);
+    if (!standing || isPendingGateExpired(standing, now)) {
+      console.error(formatWarning({
+        message: `Gate "${gate}" on "${opName}" has no standing pending fact — nothing to expire`,
+      }));
+      return 0;
+    }
+    await appendPendingGate({
+      op: opName,
+      gate,
+      timestamp: now,
+      expiresAt: now,
+      ...(standing.description ? { description: standing.description } : {}),
+    });
+    await pushLifecycle().catch(() => undefined);
+    console.error(formatSuccess(`Gate "${gate}" on "${opName}" expired at ${now} — not approved`));
+    console.error(formatInfo(
+      `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
+    ));
+    return 0;
+  }
+
+  // `--approver` wins over `--actor`, the same precedence `chant run approve`
+  // has applied since #2126 (`../handlers/run.ts`'s `runOpApprove`). Reading
+  // only `--actor` here meant every README that teaches `--approver you`
+  // recorded the shell user instead (#2192).
+  const outcome = await recordGateApproval(opName, gate, {
+    actor: ctx.args.approver ?? ctx.args.actor,
+    note: ctx.args.note,
+    url: ctx.args.url,
+  });
+  if (!outcome.ok) return 1;
+
+  console.error(formatInfo(
+    `This records the resolution as a fact; it does not itself re-run anything. ` +
+      `Run \`chant run ${opName}\` and it walks through gate "${gate}".`,
+  ));
+  return 0;
+}
+
+/** What a caller supplies alongside the op and gate names. */
+export interface GateApprovalOptions {
+  /** `--actor`/`--approver`; falls back to the CI or shell identity. */
+  actor?: string;
+  /** `--note` — free-text prose. */
+  note?: string;
+  /** `--url` — the approval surface, validated as absolute http/https. */
+  url?: string;
+}
+
+export type GateApprovalOutcome =
+  | { ok: true; record: GateResolutionRecord }
+  | { ok: false };
+
+/**
+ * The ledger write behind `chant approve` — extracted so `chant run approve`
+ * (#2121) records the identical fact before waking the runtime that hosts the
+ * gated run, instead of growing a second, drifting writer.
+ *
+ * Prints the same warning for an undiscovered op and the same success line as
+ * `chant approve` always did; the caller adds whatever it does next.
+ */
+export async function recordGateApproval(
+  opName: string,
+  gate: string,
+  opts: GateApprovalOptions,
+): Promise<GateApprovalOutcome> {
   const { ops } = await discoverOps();
   if (!ops.has(opName)) {
     console.error(formatWarning({
@@ -392,18 +682,18 @@ 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";
+  const resolvedBy = opts.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();
+  const url = opts.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;
+    return { ok: false };
   }
 
   const { record } = await appendGateResolution({
@@ -411,7 +701,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     gate,
     resolvedBy,
     timestamp: new Date().toISOString(),
-    ...(ctx.args.note ? { note: ctx.args.note } : {}),
+    ...(opts.note ? { note: opts.note } : {}),
     ...(url ? { url } : {}),
   });
   await pushLifecycle().catch(() => undefined);
@@ -420,9 +710,5 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     `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 — " +
-      "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;
+  return { ok: true, record };
 }