@intentius/chant 0.124.24 → 0.124.26

package/src/op/local-executor.ts

@@ -14,6 +14,12 @@
  * ledger, so `chant approve <op> <gate>` followed by `chant run <op>` is the
  * whole loop.
  *
+ * A gate with `resume: true` (#3947) also stores a checkpoint of the step
+ * outputs the steps after it read, and the next run after the approval starts
+ * at the gate instead of the first phase. It re-runs the step that produced
+ * the gate's plan first, and starts at the first phase after all when the
+ * plan moved. See `./gate-checkpoint.ts`.
+ *
  * The executor is deliberately decoupled from any lexicon: activity
  * implementations and profiles are passed in (loaded dynamically by the CLI),
  * so core never statically depends on one.
@@ -23,12 +29,15 @@ import { outcomeAttributesOf } from "./types";
 import type { OpConfig, PhaseDefinition, ActivityStep, GateStep, EffectStep, StepDefinition } from "./types";
 import { resolveActivity, type ActivityFn, type ActivityProfile } from "./activity-registry";
 import type { ReceiptReadResult } from "./receipt-store";
-import { isStepOutputRef } from "./step-output-ref";
+import { collectStepOutputRefs, isStepOutputRef } from "./step-output-ref";
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
 import { parseDuration } from "./duration";
 import { stepLabel, withRunConsole, withStepConsole } from "./step-console";
 import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
+import { resolveGateAliases } from "./gate-alias";
 import { gatePointOf } from "./gate-point";
 import { evaluatePointGate, workspaceGatePointAsker, type GatePointAsker } from "./gate-point-run";
 import type { ResolvedGateApproval } from "./gate-approval";
@@ -45,6 +54,11 @@ import { RunWorkLease, LEASE_LOST, workLeaseProblems, workLeaseNeedsRunItem, typ
 import { WORK_LEASE_STEP_ID } from "./types";
 import { LiveRun, currentLiveRun, withLiveRun } from "./run-live";
 import { runEnvOf } from "../lifecycle/run-ledger";
+import { getHeadCommit } from "../lifecycle/git";
+import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
+import type { GateCheckpoint } from "../lifecycle/gate-checkpoint";
+import type { ActivityContract } from "./activity-contract";
+import { buildGateCheckpoint, decideGateResume, resumeGatesOf, type GateResumeDecision, type ResumeGate } from "./gate-checkpoint";
 
 export { parseDuration } from "./duration";
 
@@ -76,12 +90,17 @@ export interface StepRecord {
     resolvedBy: string;
     timestamp: string;
     url?: string;
-    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. `"point"` on a gate that asks a decision point (#3170). */
-    via?: "quorum" | "policy" | "point";
+    /**
+     * On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. `"point"` on a gate that asks a decision point (#3170).
+     * `"alias"` (#3949) when an approval recorded under one of the gate's aliases counted, on any gate.
+     */
+    via?: "quorum" | "policy" | "point" | "alias";
     /** On a gate with a quorum (#2508): every approver who counted toward it. */
     approvers?: string[];
     /** On a gate that asks a decision point (#3170): the answer record that passed it, which the gate ledger's resolution cites too. */
     answer?: GateAnswerRef;
+    /** With `via: "alias"` (#3949): the approvals carried from an alias, each by the op, gate and time it was recorded under. */
+    carriedFrom?: Array<{ op: string; gate: string; resolvedBy: string; timestamp: string }>;
   };
   /**
    * Why a step declined to proceed on something that is not a failure
@@ -103,6 +122,12 @@ export interface StepRecord {
    * approve` takes. The step's status is `skipped` and the run's is `gated`.
    */
   gate?: { op: string; gate: string };
+  /**
+   * Set on a step this run did not execute because it resumed at a gate
+   * (#3947): the run whose checkpoint supplied the step's output, and the
+   * gate. The step's status is `skipped`.
+   */
+  resumed?: { run: string; gate: string };
 }
 
 export interface OpRunResult {
@@ -149,6 +174,18 @@ export interface OpRunResult {
    * was released and with which outcome, or why it was lost.
    */
   workLease?: WorkLeaseRunResult;
+  /**
+   * Set when this run resumed at an approved gate (#3947): the gate, the run
+   * whose checkpoint it carried on from, and that checkpoint's digest.
+   */
+  resumed?: { gate: string; run: string; checkpoint: string };
+  /**
+   * Why a gate that resumes did not (#3947), one line each: an approved gate
+   * whose checkpoint failed a check, so the run started at the first phase,
+   * or a gate this run stopped at that stored no checkpoint. Absent when
+   * there is nothing to say.
+   */
+  resumeNotes?: string[];
 }
 
 // ── Errors ────────────────────────────────────────────────────────────────��─
@@ -278,6 +315,48 @@ function resolveStepOutputRefs(value: unknown, resultsById: ReadonlyMap<string,
   return value;
 }
 
+/** The activity steps a step runs: itself, or an effect's nested ones. */
+function activitiesOf(step: ActivityStep | EffectStep): ActivityStep[] {
+  return isEffect(step) ? step.steps.filter(isActivity) : [step];
+}
+
+/**
+ * The first step a compensation step references that has not completed in
+ * this run (#3948 decision A6), or `undefined` when every one did. A failure
+ * can stop the run before the step that a rollback reads, and calling the
+ * rollback with `undefined` in place of that value would undo the wrong
+ * thing, or nothing, while reporting `ok`.
+ */
+function unfinishedSource(step: ActivityStep | EffectStep, resultsById: ReadonlyMap<string, unknown>): string | undefined {
+  for (const activity of activitiesOf(step)) {
+    const missing = collectStepOutputRefs(activity.args).find((ref) => !resultsById.has(ref.step));
+    if (missing) return missing.step;
+  }
+  return undefined;
+}
+
+/** The skipped record of a compensation step whose source did not complete. */
+function unfinishedSourceRecord(step: ActivityStep | EffectStep, phaseName: string, source: string): StepRecord {
+  const record = isEffect(step) ? skippedRecord(phaseName, `effect:${step.receipt.name}`) : skippedRecord(phaseName, step.fn, step.args);
+  return { ...record, refusal: `step "${source}" did not complete in this run, so this compensation step, which reads its output, was skipped` };
+}
+
+/**
+ * The digest of the step outputs an effect's nested steps read (#3948), or
+ * `undefined` when they read none. The receipt store folds it into the
+ * expectation, so a changed value re-fires the effect instead of the receipt
+ * matching on the declared inputs alone. An existence receipt says only that
+ * the effect ran once, so it takes none.
+ */
+function effectOutputsDigest(step: EffectStep, resultsById: ReadonlyMap<string, unknown>): string | undefined {
+  if (step.receipt.flavor === "existence") return undefined;
+  const read = activitiesOf(step).flatMap((a) =>
+    collectStepOutputRefs(a.args).map((ref) => ({ step: ref.step, path: ref.path ?? "", value: resolveStepOutputRefs(ref, resultsById) })),
+  );
+  if (read.length === 0) return undefined;
+  return contentDigest(canonicalJson(read));
+}
+
 /**
  * Find the first `policyGate` step anywhere in the Op (phases + `onFailure`,
  * including steps nested inside effect steps), if any.
@@ -464,13 +543,14 @@ async function runStep(
 /** The step data the executor synthesizes to read a receipt through the store
  * activities (`receiptRead`/`receiptWrite` — provided by the receipt row's
  * lexicon, #1835, or a mock store in tests via `receiptActivities`). */
-function receiptReadStep(step: EffectStep): ActivityStep {
+function receiptReadStep(step: EffectStep, outputs?: string): ActivityStep {
   return {
     kind: "activity",
     fn: "receiptRead",
     args: {
       receipt: step.receipt,
       ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+      ...(outputs !== undefined ? { outputs } : {}),
     },
     profile: "fastIdempotent",
     outcomeAttribute: { name: "EffectApplied", from: "applied" },
@@ -496,10 +576,20 @@ interface GateContext {
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
+  /** Set in `onFailure` phases (#3948): a step whose referenced step did not complete is skipped. */
+  compensating?: boolean;
   /** How a gate that names a decision point asks it (#3170). */
   points?: GatePointAsker;
   /** The environment the run was started for, a point gate's `gate.env` input. */
   env?: string;
+  /** The Op's gates that resume (#3947), and what a checkpoint at one needs. Absent when it has none. */
+  resume?: {
+    config: OpConfig;
+    gates: Map<GateStep, ResumeGate>;
+    commit: string | undefined;
+    contracts?: ReadonlyMap<string, ActivityContract>;
+    note: (line: string) => void;
+  };
 }
 
 /**
@@ -632,6 +722,22 @@ async function runGateStep(
   const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
   const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
   const approval = resolveGateApproval(step, resultsById);
+  // #3947: a gate that resumes stores the outputs the steps after it read.
+  const resumeAt = gates.resume?.gates.get(step);
+  let checkpoint: GateCheckpoint | undefined;
+  let blocked: string | undefined;
+  if (resumeAt && gates.resume) {
+    const built = buildGateCheckpoint(gates.resume.config, resumeAt, {
+      runId: gates.runId ?? "",
+      commit: gates.resume.commit,
+      ...(gates.env !== undefined ? { environment: gates.env } : {}),
+      ...(planDigest !== undefined ? { planDigest } : {}),
+      outputs: resultsById,
+      ...(gates.resume.contracts ? { contracts: gates.resume.contracts } : {}),
+    });
+    if ("blocked" in built) blocked = built.blocked;
+    else checkpoint = built.checkpoint;
+  }
   let check: GateCheck;
   try {
     check = await evaluateGate(gates.port, {
@@ -643,6 +749,8 @@ async function runGateStep(
       ...(planDigest !== undefined ? { planDigest } : {}),
       ...(approval ? { approval } : {}),
       ...(gates.now ? { now: gates.now } : {}),
+      ...(checkpoint ? { checkpoint } : {}),
+      ...(step.aliases?.length ? { aliases: resolveGateAliases(step, gates.op) } : {}),
     });
   } catch (err) {
     // Deciding a gate reads and writes the `chant/lifecycle` branch, so it
@@ -674,6 +782,9 @@ async function runGateStep(
       ...(resolution.url ? { url: resolution.url } : {}),
       ...(check.via ? { via: check.via } : {}),
       ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
+      ...(check.carried?.length
+        ? { carriedFrom: check.carried.map((r) => ({ op: r.carriedFrom!.op, gate: r.carriedFrom!.gate, resolvedBy: r.resolvedBy, timestamp: r.carriedFrom!.timestamp })) }
+        : {}),
     };
     // #2522: a later step reads this gate's approval from the run context
     // rather than re-tallying the ledger, so it sees the decision this run made.
@@ -690,6 +801,7 @@ async function runGateStep(
     };
   }
 
+  if (blocked) gates.resume?.note(`gate "${gateName(step)}" stored no checkpoint, so it won't resume: ${blocked}`);
   const refusal = check.mismatch
     ? { refusal: describeGateMismatch(gates.op, gateName(step), check.mismatch, await gateIsSealed(gateName(step))) }
     : {};
@@ -790,7 +902,15 @@ async function runEffectStep(
 }> {
   const records: StepRecord[] = [];
 
-  const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, signal);
+  let outputs: string | undefined;
+  try {
+    outputs = effectOutputsDigest(step, resultsById);
+  } catch (err) {
+    // A resolved value JSON cannot hold (canonicalJson refuses it) would be a wrong expectation.
+    pushRecord(records, gates, { phase: phaseName, fn: `effect:${step.receipt.name}`, args: {}, status: "fail", durationMs: 0, error: errMessage(err) });
+    return { records, failed: true };
+  }
+  const read = await runStep(receiptReadStep(step, outputs), phaseName, activities, profiles, resultsById, signal);
   pushRecord(records, gates, read.record);
   if (read.record.status === "fail") return { records, failed: true };
 
@@ -897,6 +1017,8 @@ async function runEffectStep(
 /**
  * Run a phase. Throws `PhaseFailure` (with the records so far) if any step
  * fails, or `GateStop` if a `gate` step in it is still pending approval.
+ * `from` starts a sequential phase at that step, for a run that resumes at a
+ * gate in it (#3947); the steps before it are the caller's to record.
  */
 async function runPhase(
   phase: PhaseDefinition,
@@ -905,6 +1027,7 @@ async function runPhase(
   resultsById: Map<string, unknown>,
   gates: GateContext,
   signal?: AbortSignal,
+  from = 0,
 ): Promise<StepRecord[]> {
   if (phase.parallel) {
     const eff = phase.steps.find(isEffect);
@@ -950,7 +1073,10 @@ async function runPhase(
       }
     }
     const steps = phase.steps.filter(isActivity);
-    const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
+    const settled = await Promise.all(steps.map((s) => {
+      const source = gates.compensating ? unfinishedSource(s, resultsById) : undefined;
+      return source ? { record: unfinishedSourceRecord(s, phase.name, source) } as RanStep : runStep(s, phase.name, activities, profiles, resultsById, signal);
+    }));
     const ran = settled.map((r) => r.record);
     for (const r of ran) gates.onRecord?.(r);
     const records = gateRecords.concat(ran);
@@ -981,7 +1107,7 @@ async function runPhase(
     }
   };
 
-  for (let i = 0; i < steps.length; i++) {
+  for (let i = from; i < steps.length; i++) {
     const step = steps[i];
     // The work lease (#2748): claimed here when it is due, and checked before
     // every step, so no step starts once the lease is lost.
@@ -1011,6 +1137,11 @@ async function runPhase(
       }
       continue;
     }
+    const source = gates.compensating ? unfinishedSource(step, resultsById) : undefined;
+    if (source) {
+      pushRecord(records, gates, unfinishedSourceRecord(step, phase.name, source));
+      continue;
+    }
     if (isEffect(step)) {
       const { records: effRecords, failed, pending, pushed, pushWarning, point } = await runEffectStep(
         step, phase.name, activities, profiles, resultsById, gates, signal,
@@ -1121,6 +1252,19 @@ export interface RunOpOptions {
   stepOutput?: (line: string) => void;
   /** How long a step may be quiet before the still-running line. Default 60s; `0` turns it off. */
   stepHeartbeatMs?: number;
+  /**
+   * The commit the checkout is at, for an Op with a gate that resumes
+   * (#3947). A checkpoint records it and a resumed run must match it.
+   * Default: `git rev-parse HEAD` in `cwd`, and none when that fails, so no
+   * gate resumes.
+   */
+  commit?: string;
+  /**
+   * The activity contracts the run knows (#3947). A gate that resumes stores
+   * no output a contract marks secret, and doesn't resume when a later step
+   * needs one. The local runtime passes the configured lexicons' contracts.
+   */
+  contracts?: ReadonlyMap<string, ActivityContract>;
 }
 
 /**
@@ -1292,12 +1436,12 @@ async function runOpInTurn(
   const start = Date.now();
   // Each phase's wall-clock time, for the run record and the in-flight one.
   const phaseDurations: Record<string, number> = {};
-  const timedPhase = async (phase: PhaseDefinition, ctx: GateContext, phaseSignal: AbortSignal | undefined): Promise<StepRecord[]> => {
+  const timedPhase = async (phase: PhaseDefinition, ctx: GateContext, phaseSignal: AbortSignal | undefined, from = 0): Promise<StepRecord[]> => {
     const live = currentLiveRun();
     const t0 = Date.now();
     live?.phaseStarted(phase.name);
     try {
-      const ran = await runPhase(phase, activities, profiles, resultsById, ctx, phaseSignal);
+      const ran = await runPhase(phase, activities, profiles, resultsById, ctx, phaseSignal, from);
       live?.phaseEnded(phase.name, phaseVerdict(ran), Date.now() - t0);
       return ran;
     } finally {
@@ -1326,6 +1470,7 @@ async function runOpInTurn(
       ...(gate ? { gate: { name: gate.gate, since: gate.timestamp, ...(gate.op !== config.name ? { op: gate.op } : {}) } } : {}),
       ...(point ? { point: { ...point, since: ended } } : {}),
       ...(options.steward ? { steward: options.steward } : {}),
+      ...(resumed ? { resumed } : {}),
       phaseDurations,
     });
     const record: OpRunRecord = { version: 1, ...input, id: runId };
@@ -1343,10 +1488,96 @@ async function runOpInTurn(
   // values before reaching an activity function — see `runStep`.
   const resultsById = new Map<string, unknown>();
 
+  // #3947: the gates that resume. Each stores a checkpoint when the run stops
+  // at it, and the run may start at one of them.
+  let resumed: OpRunResult["resumed"];
+  const resumeNotes: string[] = [];
+  const resumeGates = resumeGatesOf(config);
+  if (resumeGates.length > 0) {
+    gates.resume = {
+      config,
+      gates: new Map(resumeGates.map((g) => [g.step, g])),
+      commit: options.commit ?? (await getHeadCommit(options.cwd ? { cwd: options.cwd } : undefined).catch(() => undefined)),
+      ...(options.contracts ? { contracts: options.contracts } : {}),
+      note: (line) => resumeNotes.push(line),
+    };
+  }
+  const resumeFields = (): Pick<OpRunResult, "resumed" | "resumeNotes"> => ({
+    ...(resumed ? { resumed } : {}),
+    ...(resumeNotes.length > 0 ? { resumeNotes: [...resumeNotes] } : {}),
+  });
+
+  /**
+   * Resume at the gate `decision` names (#3947): seed the checkpoint's
+   * outputs, record every step before the gate as resumed, and run the step
+   * that produced the gate's plan again. Returns where the phases pick up, or
+   * undefined when the plan moved and the run starts at the first phase.
+   */
+  const resumeAt = async (
+    decision: Extract<GateResumeDecision, { kind: "resume" }>,
+  ): Promise<{ phaseIndex: number; stepIndex: number } | undefined> => {
+    const { gate, checkpoint } = decision;
+    for (const [id, value] of Object.entries(checkpoint.outputs)) resultsById.set(id, value);
+    const marker = { run: checkpoint.runId, gate: gate.name };
+    const prefix: StepRecord[] = [];
+    for (const [pi, phase] of config.phases.entries()) {
+      if (pi > gate.phaseIndex) break;
+      const steps = pi < gate.phaseIndex ? phase.steps : phase.parallel ? [] : phase.steps.slice(0, gate.stepIndex);
+      for (const [si, step] of steps.entries()) {
+        if (gate.planStep && pi === gate.planStep.phaseIndex && si === gate.planStep.stepIndex) {
+          const ran = await runStep(gate.planStep.step, phase.name, activities, profiles, resultsById, stepSignal);
+          prefix.push(ran.record);
+          if (ran.record.status === "fail" || ran.pending || ran.record.point) {
+            for (const r of prefix) gates.onRecord?.(r);
+            if (ran.pending) throw new GateStop(prefix, ran.pending, phase.name);
+            if (ran.record.point) throw new PointStop(prefix, ran.record.point, phase.name);
+            throw new PhaseFailure(prefix);
+          }
+          continue;
+        }
+        const skipped = isEffect(step)
+          ? skippedRecord(phase.name, `effect:${step.receipt.name}`)
+          : isGate(step)
+            ? skippedRecord(phase.name, gateFn(step))
+            : skippedRecord(phase.name, step.fn, step.args);
+        prefix.push({ ...skipped, resumed: marker });
+      }
+    }
+    // The plan the run would approve now against the one approved: a moved
+    // plan is live drift since the approval, and starts the run over.
+    const resolved = resolveStepOutputRefs(gate.step.plan, resultsById);
+    const planned = typeof resolved === "string" && resolved !== "" ? resolved : undefined;
+    if (!samePlanDigest(planned, decision.pending.planDigest)) {
+      resultsById.clear();
+      resumeNotes.push(
+        `gate "${gate.name}" is approved, and the run starts at the first phase: the plan moved since the approval ` +
+          `(approved ${describePlanDigest(decision.pending.planDigest)}, planned ${planned ?? "(none)"})`,
+      );
+      return undefined;
+    }
+    records.push(...prefix);
+    for (const r of prefix) gates.onRecord?.(r);
+    resumed = { gate: gate.name, run: checkpoint.runId, checkpoint: decision.digest };
+    return { phaseIndex: gate.phaseIndex, stepIndex: config.phases[gate.phaseIndex]!.parallel ? 0 : gate.stepIndex };
+  };
+
   try {
-    for (const phase of config.phases) {
+    let from: { phaseIndex: number; stepIndex: number } | undefined;
+    if (gates.resume) {
+      const decision = await decideGateResume(gates.port, config, {
+        now: options.now ?? new Date().toISOString(),
+        commit: gates.resume.commit,
+        ...(options.env !== undefined ? { environment: options.env } : {}),
+      });
+      if (decision.kind === "refused") {
+        resumeNotes.push(`gate "${decision.gate}" is approved, and the run starts at the first phase: ${decision.reason}`);
+      } else if (decision.kind === "resume") {
+        from = await resumeAt(decision);
+      }
+    }
+    for (let pi = from?.phaseIndex ?? 0; pi < config.phases.length; pi++) {
       if (signal?.aborted) throw new PhaseFailure([]);
-      records.push(...(await timedPhase(phase, gates, stepSignal)));
+      records.push(...(await timedPhase(config.phases[pi]!, gates, stepSignal, pi === from?.phaseIndex ? from.stepIndex : 0)));
     }
     // The last renewal before the run is recorded (#2748): a run whose lease
     // was lost is never recorded as done.
@@ -1366,6 +1597,7 @@ async function runOpInTurn(
         startedAt,
         record,
         ...(await finishWork("ok")),
+        ...resumeFields(),
       };
     }
 
@@ -1384,6 +1616,7 @@ async function runOpInTurn(
         point: err.question,
         record,
         ...(await finishWork("waiting")),
+        ...resumeFields(),
       };
     }
 
@@ -1404,6 +1637,7 @@ async function runOpInTurn(
         ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
         record,
         ...(await finishWork("gated")),
+        ...resumeFields(),
       };
     }
 
@@ -1444,7 +1678,7 @@ async function runOpInTurn(
     // Compensation: run onFailure phases in reverse order (best-effort). Skipped
     // on abort (Ctrl-C) — the user asked to stop, so don't start new work.
     // It runs whatever the work lease did, so it takes no work boundary.
-    const compensation: GateContext = { ...gates, work: undefined };
+    const compensation: GateContext = { ...gates, work: undefined, compensating: true };
     if (!signal?.aborted) {
       for (const phase of [...(config.onFailure ?? [])].reverse()) {
         try {
@@ -1478,6 +1712,7 @@ async function runOpInTurn(
         startedAt,
         record: failed,
         ...(await finishWork("fail")),
+        ...resumeFields(),
       },
       { cause: err },
     );
@@ -1492,6 +1727,7 @@ async function runOpInTurn(
     startedAt,
     record,
     ...(await finishWork("ok")),
+    ...resumeFields(),
   };
 }
 

package/src/op/local-output.ts

@@ -28,6 +28,10 @@ function formatDuration(ms: number): string {
  * stays clean for piping (the `--json` renderer owns stdout).
  */
 export function renderHuman(result: OpRunResult, write: Writer = stderr, sealed = false): void {
+  // #3947: a run that resumed at a gate says where it picked up.
+  if (result.resumed) {
+    write(`[resume] at gate "${result.resumed.gate}", from run ${result.resumed.run}'s checkpoint ${result.resumed.checkpoint}`);
+  }
   let currentPhase: string | undefined;
   for (const record of result.records) {
     if (record.phase !== currentPhase) {
@@ -36,7 +40,9 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr, sealed
     }
     const mark = record.status === "ok" ? "✓" : record.status === "fail" ? "✗" : "•";
     const call = `${record.fn}(${formatArgs(record.args ?? {})})`;
-    if (record.status === "skipped") {
+    if (record.status === "skipped" && record.resumed) {
+      write(`  ${mark} ${call}   from run ${record.resumed.run}`);
+    } else if (record.status === "skipped") {
       write(`  ${mark} ${call}   skipped`);
     } else {
       write(`  ${mark} ${call}   ${formatDuration(record.durationMs)}`);
@@ -47,6 +53,10 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr, sealed
     if (record.approval) {
       write(`    [approved] ${record.approval.resolvedBy} at ${record.approval.timestamp}` +
         (record.approval.url ? ` (${record.approval.url})` : ""));
+      // #3949: an approval carried from one of the gate's aliases names where it came from.
+      for (const c of record.approval.carriedFrom ?? []) {
+        write(`    [carried] ${c.resolvedBy}'s approval of ${c.op}/${c.gate} at ${c.timestamp}`);
+      }
     }
     if (record.refusal) {
       write(`    [refused] ${record.refusal}`);
@@ -72,6 +82,8 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr, sealed
     write(`[work] nothing claimed: ${work.refusal}`);
   }
 
+  for (const note of result.resumeNotes ?? []) write(`[resume] ${note}`);
+
   const total = `${(result.totalMs / 1000).toFixed(1)}s`;
   if (result.status === "ok") {
     write(`Op "${result.op}" completed in ${total}`);
@@ -104,6 +116,8 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr, sealed
   write(`  approve : ${approveCommand(gate.op, gate.gate, undefined, gate.planDigest, sealed)}`);
   if (gate.url) write(`  approve at: ${gate.url}`);
   write(`  expires : ${gate.expiresAt}`);
+  // #3947: the approval also lets the next run start here.
+  if (gate.checkpointDigest) write(`  resume  : once approved, the next run starts at this gate (checkpoint ${gate.checkpointDigest})`);
   // #2310: this run's own append reached only the local chant/lifecycle
   // branch, not the remote. The pending fact is still correct — the gate is
   // still right to stand — but an operator working from a clone of the
@@ -139,7 +153,9 @@ export function renderJson(result: OpRunResult, write: Writer = stdout, sealed =
   const push = result.gatePushed === false
     ? { pushed: false, pushWarning: result.gatePushWarning ?? "the pending fact was recorded locally only" }
     : {};
-  write(JSON.stringify({ ...result.record, ...approve, ...push }));
+  // #3947: why a gate that resumes did not, beside the record like `push`.
+  const notes = result.resumeNotes ? { resumeNotes: result.resumeNotes } : {};
+  write(JSON.stringify({ ...result.record, ...approve, ...push, ...notes }));
 }
 
 export type { OpRunResult, StepRecord };

package/src/op/op-ir.test.ts

@@ -257,6 +257,31 @@ describe("op.json IR", () => {
     expect(serializeOpIR(reconstructed)).toBe(text);
   });
 
+  // #3947: a gate that resumes says so in op.json, for a runtime that reads it.
+  it("carries a gate's resume through op.json and back", () => {
+    const config: OpConfig = {
+      name: "live-apply",
+      overview: "o",
+      phases: [phase("Gate", [{ kind: "gate", gate: "approve-live-apply", resume: true }])],
+    };
+    const text = serializeOpIR(config);
+    expect((JSON.parse(text) as OpIR).phases[0].steps[0]).toMatchObject({ kind: "gate", resume: true });
+    expect(opConfigFromIR(JSON.parse(text) as OpIR).phases[0]!.steps[0]).toMatchObject({ kind: "gate", resume: true });
+  });
+
+  // #3949: a gate's aliases travel in op.json, so a runtime that reads it counts the same approvals.
+  it("carries a gate's aliases through op.json and back", () => {
+    const aliases = [{ op: "upgrade-tier-1", gate: "approve" }, { gate: "approve-old" }];
+    const config: OpConfig = {
+      name: "upgrade",
+      overview: "o",
+      phases: [phase("Gate", [{ kind: "gate", gate: "approve-tier-1", plan: "jcs1-sha256:" + "a".repeat(64), aliases }])],
+    };
+    const text = serializeOpIR(config);
+    expect((JSON.parse(text) as OpIR).phases[0].steps[0]).toMatchObject({ kind: "gate", aliases });
+    expect(opConfigFromIR(JSON.parse(text) as OpIR).phases[0]!.steps[0]).toMatchObject({ kind: "gate", aliases });
+  });
+
   it("round-trips a minimal Op (no gate, effect, onFailure or labels) too", () => {
     const original: OpConfig = { name: "minimal", overview: "o", phases: [phase("Only", [shell("echo hi")])] };
     const text = serializeOpIR(original);

package/src/op/op-ir.ts

@@ -151,6 +151,10 @@ export interface OpIRGateStep {
   approval?: GateStep["approval"];
   /** The decision point the gate asks (#3170), carried as authored. Absent on a gate that `chant approve` passes. */
   point?: GateStep["point"];
+  /** The gate resumes once approved (#3947). Absent on a gate that starts its run again at the first phase. */
+  resume?: true;
+  /** The gate's old names (#3949), carried as authored. Absent on a gate that has none. */
+  aliases?: GateStep["aliases"];
 }
 
 export interface OpIREffectStep {
@@ -263,6 +267,8 @@ function irGateStep(step: GateStep): OpIRGateStep {
     ...(step.plan !== undefined ? { plan: step.plan } : {}),
     ...(step.approval !== undefined ? { approval: step.approval } : {}),
     ...(step.point !== undefined ? { point: step.point } : {}),
+    ...(step.resume ? { resume: true as const } : {}),
+    ...(step.aliases !== undefined && step.aliases.length > 0 ? { aliases: step.aliases } : {}),
   };
 }
 
@@ -419,6 +425,8 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       ...(step.plan !== undefined ? { plan: step.plan } : {}),
       ...(step.approval !== undefined ? { approval: step.approval } : {}),
       ...(step.point !== undefined ? { point: step.point } : {}),
+      ...(step.resume ? { resume: true } : {}),
+      ...(step.aliases !== undefined && step.aliases.length > 0 ? { aliases: step.aliases } : {}),
     };
   }
   return {

package/src/op/receipt-store.ts

@@ -34,6 +34,8 @@ import {
   referenceInputPaths,
   type EffectReceiptDeclaration,
   type EffectReceiptFlavor,
+  declaredExpectation,
+  withStepOutputs,
 } from "../effect-receipt";
 
 /**
@@ -101,7 +103,14 @@ export function receiptCheckInput(receipt: EffectReceiptDeclaration): ReceiptChe
 // ── Activity contracts ────────────────────────────────────────────────────────
 
 /** Args of the `receiptRead` activity, as the effect step's codegen emits them. */
-export interface ReceiptReadArgs extends ReceiptCheckInput {}
+export interface ReceiptReadArgs extends ReceiptCheckInput {
+  /**
+   * The digest of the step outputs the effect's nested steps read (#3948),
+   * when they read any. Folded into the expectation by {@link withStepOutputs}.
+   */
+  outputs?: string;
+}
+
 
 /** Result of the `receiptRead` activity. `current` is `null` (not `undefined`)
  * for an absent receipt so the value survives JSON transport. */
@@ -183,7 +192,8 @@ export function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOpt
 
   return {
     async receiptRead(args: ReceiptReadArgs): Promise<ReceiptReadResult> {
-      const expectation = await expectationOf(args);
+      const declared = await expectationOf(args);
+      const expectation = args.outputs !== undefined ? withStepOutputs(declared, args.outputs) : declared;
       const current = await store.read(args.receipt);
       return { current: current ?? null, expectation, applied: current === expectation };
     },
@@ -201,7 +211,7 @@ export function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOpt
         const current = await store.read(input.receipt);
         if (current === undefined) {
           findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "absent", expected });
-        } else if (current !== expected) {
+        } else if (declaredExpectation(current) !== expected) {
           findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "differs", expected, current });
         }
       }

package/src/op/runtime.ts

@@ -59,6 +59,8 @@ export interface OpRunStepRecord {
   point?: WaitingPoint;
   /** The gate this step's command stopped at (#2779), for a step skipped because of it. */
   gate?: { op: string; gate: string };
+  /** The run whose checkpoint supplied this step's output, for a step a resumed run skipped (#3947). */
+  resumed?: { run: string; gate: string };
 }
 
 /** One phase's steps and the verdict they add up to. */
@@ -151,6 +153,12 @@ export interface OpRunRecord {
   point?: WaitingPoint & { since: string };
   /** The steward whose turn the run was, when a steward ran it (#2749). */
   steward?: string;
+  /**
+   * The gate this run resumed at (#3947), the run whose checkpoint it carried
+   * on from, and the checkpoint's digest. Absent on a run that started at the
+   * first phase.
+   */
+  resumed?: { gate: string; run: string; checkpoint: string };
 }
 
 /** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */