@intentius/chant 0.124.25 → 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.
@@ -31,6 +37,7 @@ 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";
@@ -47,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";
 
@@ -78,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
@@ -105,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 {
@@ -151,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 ────────────────────────────────────────────────────────────────��─
@@ -547,6 +582,14 @@ interface GateContext {
   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;
+  };
 }
 
 /**
@@ -679,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, {
@@ -690,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
@@ -721,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.
@@ -737,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))) }
     : {};
@@ -952,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,
@@ -960,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);
@@ -1039,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.
@@ -1184,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>;
 }
 
 /**
@@ -1355,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 {
@@ -1389,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 };
@@ -1406,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.
@@ -1429,6 +1597,7 @@ async function runOpInTurn(
         startedAt,
         record,
         ...(await finishWork("ok")),
+        ...resumeFields(),
       };
     }
 
@@ -1447,6 +1616,7 @@ async function runOpInTurn(
         point: err.question,
         record,
         ...(await finishWork("waiting")),
+        ...resumeFields(),
       };
     }
 
@@ -1467,6 +1637,7 @@ async function runOpInTurn(
         ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
         record,
         ...(await finishWork("gated")),
+        ...resumeFields(),
       };
     }
 
@@ -1541,6 +1712,7 @@ async function runOpInTurn(
         startedAt,
         record: failed,
         ...(await finishWork("fail")),
+        ...resumeFields(),
       },
       { cause: err },
     );
@@ -1555,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/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. */

package/src/op/runtimes/local.ts

@@ -22,6 +22,8 @@ import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { loadActivities, loadProfiles } from "../activity-registry";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "../local-executor";
+import { loadActivityContracts } from "../activity-contract-registry";
+import { resumeGatesOf } from "../gate-checkpoint";
 import { stepHeartbeatMs } from "../step-console";
 import { runComponents } from "../../components/cli-support";
 import { discoverOps } from "../discover";
@@ -139,6 +141,8 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
       }
 
       const [activities, profiles] = await Promise.all([loadActivities(lexicons), loadProfiles()]);
+      // #3947: a gate that resumes stores no output a contract marks secret.
+      const contracts = resumeGatesOf(op).length > 0 ? await loadActivityContracts(lexicons) : undefined;
 
       // A caller that names the run (#3539: `chant acp` on fountain passes the
       // conversation id) gets its id on the record; otherwise one is minted.
@@ -179,6 +183,7 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
               stepOutput: (line) => process.stderr.write(`${line}\n`),
               stepHeartbeatMs: stepHeartbeatMs(process.env, (message) => process.stderr.write(`warning: ${message}\n`)),
               ...(startOpts.work ? { work: startOpts.work } : {}),
+              ...(contracts ? { contracts } : {}),
               onWorkLeaseWarning: (message) =>
                 process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),
             },

package/src/op/types.ts

@@ -298,6 +298,38 @@ export interface GateStepBase {
    * `./gate-point.ts`.
    */
   point?: string | GatePoint;
+  /**
+   * A run that stops at this gate can be resumed here once it is approved
+   * (#3947), rather than starting again at the first phase. The run stores
+   * the step outputs a later step references in a checkpoint on
+   * `chant/lifecycle`, and the next run after `chant approve` re-runs the
+   * step that produced the gate's `plan`, checks the checkpoint, and carries
+   * on from the gate. Any check that fails starts the run at the first phase,
+   * and the run says why. See `./gate-checkpoint.ts`.
+   *
+   * Only a gate at the top of a main phase resumes, and not one that asks a
+   * decision point or sits in an Op with a `workLease`. OPS016 refuses the
+   * rest at build.
+   */
+  resume?: boolean;
+  /**
+   * The names this gate had before an Op was restructured (#3949), so the
+   * approvals already recorded under them still count. `op` defaults to this
+   * Op. An approval recorded under an alias counts toward this gate when it
+   * answers that name's standing pending fact, the fact hasn't expired, it
+   * is for the plan this run planned and the same environment, it hasn't
+   * been spent, it passes this gate's `identity.gates` rule, and a person
+   * made it. The run then writes it again under this gate's name, citing
+   * the line it came from (`carriedFrom`). Only a gate bound to a `plan`
+   * takes aliases, and OPS017 refuses an alias that is still a gate.
+   */
+  aliases?: GateAlias[];
+}
+
+/** A name a gate had before (#3949): a gate of `op`, or of the gate's own Op when `op` is absent. */
+export interface GateAlias {
+  op?: string;
+  gate: string;
 }
 
 /**

package/src/workspace/trust/gate-seal.test.ts

@@ -11,7 +11,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
-import { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, sshKeyFingerprint, verifySshSignatureWith, type GateSigners, type SealedGateApproval } from "./gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, gateSealVersion, sshKeyFingerprint, verifySshSignatureWith, type GateSigners, type SealedGateApproval } from "./gate-seal";
 import { checkGateSeal } from "./seal";
 import { emptyPolicy, parseAllowedSigners, type TrustPolicy } from "./policy";
 import { hasSshKeygen } from "./test-repo";
@@ -96,7 +96,7 @@ describe.skipIf(!hasSshKeygen)("an SSHSIG checked with node:crypto", () => {
     const policy = policyOf(`alice ${k.pub}\n`);
     const seal = { signer: "alice", key: "SHA256:x", signature };
     expect(both(policy, { ...a, seal })).toEqual({ ours: null, keygen: true });
-    for (const edited of [{ planDigest: "jcs1-sha256:other" }, { timestamp: "2026-10-12T00:00:00.000Z" }, { relayedBy: "bot" }, { environment: "prod" }]) {
+    for (const edited of [{ planDigest: "jcs1-sha256:other" }, { timestamp: "2026-10-12T00:00:00.000Z" }, { relayedBy: "bot" }, { environment: "prod" }, { checkpointDigest: "jcs1-sha256:added" }]) {
       const res = both(policy, { ...a, ...edited, seal });
       expect(res.keygen).toBe(false);
       expect(res.ours).toMatch(/does not verify for alice/);
@@ -137,6 +137,33 @@ describe.skipIf(!hasSshKeygen)("an SSHSIG checked with node:crypto", () => {
   });
 });
 
+// #3947: seal version 2 signs the checkpoint digest as one more line, so the
+// outputs a resumed run carries on with are covered, and a version 1 payload
+// is unchanged.
+describe("seal version 2 covers the checkpoint", () => {
+  test("the payload adds a checkpoint line only when the approval carries one", () => {
+    const a = approval({ relayedBy: "bot" });
+    expect(gateSealVersion(a)).toBe(1);
+    expect(gateSealPayload(a).toString()).toBe("migrations\nmigrations-wave-1\n\njcs1-sha256:abc\nalice\n2026-10-11T00:00:00.000Z\nrelayed-by bot");
+    const b = approval({ relayedBy: "bot", checkpointDigest: "jcs1-sha256:cp" });
+    expect(gateSealVersion(b)).toBe(2);
+    expect(gateSealPayload(b).toString()).toBe(`${gateSealPayload(a).toString()}\ncheckpoint jcs1-sha256:cp`);
+  });
+
+  test.skipIf(!hasSshKeygen)("a version 2 seal verifies, and swapping or removing the checkpoint stops it", () => {
+    const k = key("alice-cp", ["-t", "ed25519"]);
+    const a = approval({ checkpointDigest: "jcs1-sha256:cp" });
+    const seal = { signer: "alice", key: "SHA256:x", signature: sign(k, gateSealPayload(a)), version: 2 };
+    const policy = policyOf(`alice ${k.pub}\n`);
+    expect(both(policy, { ...a, seal })).toEqual({ ours: null, keygen: true });
+    for (const edited of [{ checkpointDigest: "jcs1-sha256:other" }, { checkpointDigest: undefined }]) {
+      const res = both(policy, { ...a, ...edited, seal });
+      expect(res.keygen).toBe(false);
+      expect(res.ours).toMatch(/does not verify for alice/);
+    }
+  });
+});
+
 describe("the refusals that need no signature", () => {
   const signers = (over: Partial<GateSigners> = {}): GateSigners => ({ base: "a".repeat(40), signersPath: ".chant/allowed_signers", active: true, signers: [], problems: [], ...over });