@intentius/chant 0.124.25 → 0.124.27

package/src/op/gate.ts

@@ -55,6 +55,8 @@ import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requ
 import { parseDuration } from "./duration";
 import { resolveGateRunLocator } from "./gate-run-locator";
 import { refuseGateWithoutRecording } from "../lifecycle/no-record";
+import { gateCheckpointDigest, gateCheckpointText, readGateCheckpointText, writeGateCheckpoint, type GateCheckpoint } from "../lifecycle/gate-checkpoint";
+import type { ResolvedGateAlias } from "./gate-alias";
 
 /**
  * What appending a pending fact learned about reaching the remote.
@@ -100,6 +102,15 @@ export interface GateLedgerPort {
   readApplied?(op: string): Promise<AppliedGateRecord[]>;
   /** Record that a wave is about to apply under an approval (#3784), which spends it. */
   appendApplied?(record: AppliedGateRecord): Promise<{ pushed: boolean; pushWarning?: string }>;
+  /**
+   * Store the checkpoint of a run that stops at a gate that resumes (#3947),
+   * at `_gates/<op>/checkpoints/<runId>.json`. Written before the pending
+   * fact that names its digest, and pushed with it. Absent on a port that
+   * keeps none, and the gate then doesn't resume.
+   */
+  writeCheckpoint?(checkpoint: GateCheckpoint): Promise<void>;
+  /** The text of a run's checkpoint, or null when there is none (#3947). */
+  readCheckpoint?(op: string, runId: string): Promise<string | null>;
 }
 
 /** A workspace's rule for which approvals of a gate count (#3163): a signed approval, from a class when it names one. */
@@ -148,6 +159,13 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { record } = await appendPendingGate(input, opts);
       return { record, ...(await pushLifecycleReport(opts)) };
     },
+    async writeCheckpoint(checkpoint) {
+      await writeGateCheckpoint(checkpoint, opts);
+    },
+    async readCheckpoint(op, runId) {
+      await requireLifecycleLedger(opts);
+      return readGateCheckpointText(op, runId, opts);
+    },
     async readApplied(op) {
       await requireLifecycleLedger(opts);
       const { dir, file } = appliedGatePath(op);
@@ -181,16 +199,30 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
 /** A gate ledger held in memory — what a test, or a caller that has already read the ledger, hands {@link evaluateGate}. */
 export function memoryGateLedgerPort(
   seed: { resolutions?: GateResolutionRecord[]; pending?: PendingGateRecord[]; applied?: AppliedGateRecord[] } = {},
-): GateLedgerPort & { appended: PendingGateRecord[]; resolved: GateResolutionRecord[]; applied: AppliedGateRecord[] } {
+): GateLedgerPort & {
+  appended: PendingGateRecord[];
+  resolved: GateResolutionRecord[];
+  applied: AppliedGateRecord[];
+  /** Checkpoint texts by `<op>/<runId>` (#3947). */
+  checkpoints: Map<string, string>;
+} {
   const resolutions = [...(seed.resolutions ?? [])];
   const pending = [...(seed.pending ?? [])];
   const appended: PendingGateRecord[] = [];
   const resolved: GateResolutionRecord[] = [];
   const applied: AppliedGateRecord[] = [...(seed.applied ?? [])];
+  const checkpoints = new Map<string, string>();
   return {
     appended,
     resolved,
     applied,
+    checkpoints,
+    async writeCheckpoint(checkpoint) {
+      checkpoints.set(`${checkpoint.op}/${checkpoint.runId}`, gateCheckpointText(checkpoint));
+    },
+    async readCheckpoint(op, runId) {
+      return checkpoints.get(`${op}/${runId}`) ?? null;
+    },
     async readApplied(op) {
       return applied.filter((a) => a.op === op);
     },
@@ -271,6 +303,24 @@ export interface GateCheckInput {
   fields?: Record<string, unknown>;
   /** The pending fact it records carries `neverOverMcp` (#3821, chant#3485). */
   neverOverMcp?: boolean;
+  /**
+   * The checkpoint of a run at a gate that resumes (#3947). Given, a pending
+   * fact this records first stores it through the port's `writeCheckpoint`
+   * and carries its digest as `checkpointDigest`. A standing fact with no
+   * checkpoint is recorded again, so the gate gets one.
+   */
+  checkpoint?: GateCheckpoint;
+  /**
+   * The gate's old names (#3949), each with its Op filled in
+   * (`resolveGateAliases` in `./gate-alias.ts`). Read only on a gate bound
+   * to a plan. A person's approval recorded under one counts toward this
+   * gate when it answers that name's standing pending fact, the fact hasn't
+   * expired, it is for `planDigest` and `environment`, neither name has
+   * spent it, and it passes this gate's approval rule. An approval this
+   * counts is written again under this gate (`carriedFrom`), and a line
+   * carried earlier counts only while its alias is still declared.
+   */
+  aliases?: readonly ResolvedGateAlias[];
 }
 
 /**
@@ -335,11 +385,14 @@ export type GateCheck =
       /**
        * Set on a gate that declares `approval` (#2508). `"quorum"` when enough
        * human approvals were recorded, `"policy"` when an `enforce`-mode permit
-       * passed it on its own.
+       * passed it on its own. `"alias"` (#3949) when an approval recorded
+       * under one of the gate's aliases counted, on any gate.
        */
-      via?: "quorum" | "policy";
+      via?: "quorum" | "policy" | "alias";
       /** Every approval that counted toward the quorum. Set with `via`. */
       approvals?: GateResolutionRecord[];
+      /** The approvals this run carried from an alias and wrote under the gate's name (#3949). Set when `via` is `"alias"`. */
+      carried?: GateResolutionRecord[];
     }
   | {
       satisfied: false;
@@ -500,6 +553,103 @@ export function humanQuorumSince(pending: readonly PendingGateRecord[], standing
   return anchor.timestamp;
 }
 
+/**
+ * The approvals that answer `standing` (#3949): of its gate, environment and
+ * plan, recorded since it, or on a gate with an `approval` block since the
+ * human quorum's anchor ({@link humanQuorumSince}). The rule
+ * `resolutionAnswering` (`./gate-resume.ts`) decides by, without the tally:
+ * each one counts on its own toward a gate an alias names.
+ */
+export function approvalsAnswering(
+  resolutions: readonly GateResolutionRecord[],
+  standing: PendingGateRecord,
+  pending: readonly PendingGateRecord[] = [standing],
+): GateResolutionRecord[] {
+  const since = new Date(standing.approval ? humanQuorumSince(pending, standing) : standing.timestamp).getTime();
+  return resolutions.filter(
+    (r) =>
+      r.gate === standing.gate && r.environment === standing.environment && samePlanDigest(r.planDigest, standing.planDigest) &&
+      new Date(r.timestamp).getTime() >= since,
+  );
+}
+
+/**
+ * The line a run writes for an approval it carries from an alias (#3949):
+ * the approval under `op`/`gate` at `now`, citing the line it came from.
+ * The approver, plan, environment, relay and seal are the original's. A
+ * policy decision is left behind, since it was evaluated against another
+ * gate, and so is a checkpoint digest, which moves onto `carriedFrom`: the
+ * approver saw that checkpoint, not one this gate stores, so a carried
+ * approval never lets a run resume.
+ */
+export function carriedApproval(r: GateResolutionRecord, op: string, gate: string, now: string): GateResolutionInput {
+  return {
+    op,
+    gate,
+    resolvedBy: r.resolvedBy,
+    ...(r.relayedBy !== undefined ? { relayedBy: r.relayedBy } : {}),
+    timestamp: now,
+    ...(r.note ? { note: r.note } : {}),
+    ...(r.url ? { url: r.url } : {}),
+    ...(r.planDigest !== undefined ? { planDigest: r.planDigest } : {}),
+    ...(r.environment !== undefined ? { environment: r.environment } : {}),
+    ...(r.origin ? { origin: r.origin } : {}),
+    ...(r.sameOriginOverride ? { sameOriginOverride: true } : {}),
+    approver: approverOf(r),
+    ...(r.seal ? { seal: r.seal } : {}),
+    carriedFrom: {
+      op: r.op,
+      gate: r.gate,
+      timestamp: r.timestamp,
+      ...(r.checkpointDigest !== undefined ? { checkpointDigest: r.checkpointDigest } : {}),
+    },
+  };
+}
+
+/**
+ * The approvals recorded under `input.aliases` that may count toward this
+ * gate (#3949), oldest first. Each answers its alias's standing pending
+ * fact, which hasn't expired and was recorded for this plan and
+ * environment. Each is a person's, is spent under neither name, hasn't been
+ * carried already (`ledger` is this gate's own, so a carried line that was
+ * spent keeps its original from being carried again), and passes `rule`,
+ * whose seal check reads the names the approval was signed under. One the
+ * rule refuses is added to `refused`.
+ */
+async function aliasApprovals(
+  port: GateLedgerPort,
+  input: GateCheckInput & { aliases: readonly ResolvedGateAlias[] },
+  ledger: readonly GateResolutionRecord[],
+  rule: GateApprovalRule | null,
+  now: string,
+  refused: GateRefusedApproval[],
+): Promise<GateResolutionRecord[]> {
+  const at = (iso: string) => new Date(iso).getTime();
+  const carried = ledger.filter((r) => r.gate === input.gate && r.carriedFrom !== undefined);
+  const wasCarried = (r: GateResolutionRecord) =>
+    carried.some((c) => c.carriedFrom!.op === r.op && c.carriedFrom!.gate === r.gate && at(c.carriedFrom!.timestamp) === at(r.timestamp) && c.resolvedBy === r.resolvedBy);
+  const ledgers = new Map<string, Awaited<ReturnType<GateLedgerPort["read"]>>>();
+  const out: GateResolutionRecord[] = [];
+  for (const alias of input.aliases) {
+    let other = ledgers.get(alias.op);
+    if (!other) ledgers.set(alias.op, (other = await port.read(alias.op)));
+    const pending = other.pending.filter((p) => p.environment === input.environment);
+    const standing = latestPendingGate(pending, alias.gate);
+    if (!standing || isPendingGateExpired(standing, now) || !samePlanDigest(standing.planDigest, input.planDigest)) continue;
+    const spent = alias.op === input.op && input.spent ? input.spent : ((await port.readApplied?.(alias.op)) ?? []);
+    for (const r of approvalsAnswering(other.resolutions, standing, pending)) {
+      if (r.carriedFrom !== undefined || approverOf(r).kind !== "human" || isApprovalSpent(spent, r) || wasCarried(r)) continue;
+      const reason = rule?.refuses(r) ?? null;
+      if (reason !== null) {
+        refused.push({ resolution: r, reason: `carried from ${alias.op}/${alias.gate}: ${reason}` });
+        continue;
+      }
+      out.push(r);
+    }
+  }
+  return out.sort((a, b) => at(a.timestamp) - at(b.timestamp));
+}
+
 /** Whether two resolved approval blocks are the same, so a standing pending fact still describes this gate. */
 function sameApproval(a: ResolvedGateApproval | undefined, b: ResolvedGateApproval | undefined): boolean {
   return JSON.stringify(a ?? null, sortedJsonReplacer) === JSON.stringify(b ?? null, sortedJsonReplacer);
@@ -546,6 +696,9 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   const rule = (await port.approvalRule?.(input.gate)) ?? null;
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;
+  // #3949: aliases admit only approvals of this run's plan, and carrying one writes a line.
+  const aliases = input.planDigest !== undefined && port.appendResolution ? (input.aliases ?? []) : [];
+  const aliased = (from: { op: string; gate: string }) => aliases.some((a) => a.op === from.op && a.gate === from.gate);
   // #3841: an approval of this plan the rule refuses is named, so a wait says why.
   const refused: GateRefusedApproval[] = [];
   const resolutions = (
@@ -553,6 +706,8 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       ? ledger.resolutions
       : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)
   )
+    // #3949: a carried approval counts only while the gate still names its alias.
+    .filter((r) => r.gate !== input.gate || r.carriedFrom === undefined || aliased(r.carriedFrom))
     .filter((r) => input.spent === undefined || r.gate !== input.gate || !isApprovalSpent(input.spent, r))
     .filter((r) => {
       if (rule === null || r.gate !== input.gate) return true;
@@ -561,8 +716,16 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       if (samePlanDigest(r.planDigest, input.planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime()) refused.push({ resolution: r, reason });
       return false;
     });
+  const fromAliases = aliases.length > 0 ? await aliasApprovals(port, { ...input, aliases }, ledger.resolutions, rule, now, refused) : [];
   refused.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime());
 
+  // #3949: write the approvals that counted from an alias under this gate.
+  const carry = async (records: readonly GateResolutionRecord[]): Promise<GateResolutionRecord[]> => {
+    const written: GateResolutionRecord[] = [];
+    for (const r of records) written.push((await port.appendResolution!(carriedApproval(r, input.op, input.gate, now))).record);
+    return written;
+  };
+
   let mismatched: GateResolutionRecord | undefined;
   let quorum: GateQuorumProgress | undefined;
   if (input.approval) {
@@ -587,9 +750,28 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     }
     mismatched = tally.mismatched;
     quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need };
+    // #3949: old and new approvals add up toward one quorum, each approver once.
+    const counted = new Set(tally.counted.map((r) => r.resolvedBy));
+    const extra = fromAliases.filter((r) => !counted.has(r.resolvedBy));
+    if (extra.length > 0) {
+      const asCarried = new Map(extra.map((r) => [{ version: 1, ...carriedApproval(r, input.op, input.gate, now) } as GateResolutionRecord, r]));
+      const combined = tallyGateApprovals([...resolutions, ...asCarried.keys()], input.gate, since, input.planDigest, input.approval, humansSince);
+      if (combined.counted.length >= combined.need) {
+        const written = await carry(combined.counted.filter((r) => asCarried.has(r)).map((r) => asCarried.get(r)!));
+        const approvals = [...combined.counted.filter((r) => !asCarried.has(r)), ...written];
+        return { satisfied: true, resolution: written[written.length - 1]!, via: "alias", approvals, carried: written };
+      }
+      quorum = { approvers: combined.counted.map((r) => r.resolvedBy), need: combined.need };
+    }
   } else {
     const found = latestResolutionForPlan(resolutions, input.gate, since, input.planDigest);
     if (found.resolution) return { satisfied: true, resolution: found.resolution };
+    // #3949: else the newest approval an alias admits passes it, written under this gate.
+    const newest = fromAliases[fromAliases.length - 1];
+    if (newest) {
+      const written = await carry([newest]);
+      return { satisfied: true, resolution: written[0]!, via: "alias", carried: written };
+    }
     mismatched = found.mismatched;
   }
 
@@ -614,13 +796,24 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // The same holds for the approval block (#2508): a pending fact recorded
   // under another policy version or another context would have `chant
   // approve` evaluate the policy against something this run no longer has.
+  // #3947: and for the checkpoint, so a gate that resumes gets one. A fact
+  // that already carries a checkpoint stands: an approval copies that one.
   if (
     standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) &&
-    sameApproval(standing.approval, input.approval)
+    sameApproval(standing.approval, input.approval) &&
+    (input.checkpoint === undefined || port.writeCheckpoint === undefined || standing.checkpointDigest !== undefined)
   ) {
     return { satisfied: false, pending: standing, recorded: false, ...asMismatch };
   }
 
+  // The checkpoint is written before the fact that names it, so a fact never
+  // points at a file that isn't there.
+  let checkpointDigest: string | undefined;
+  if (input.checkpoint !== undefined && port.writeCheckpoint) {
+    checkpointDigest = gateCheckpointDigest(input.checkpoint);
+    await port.writeCheckpoint(input.checkpoint);
+  }
+
   const url = resolveApprovalUrl();
   // #3683: in CI, where this job runs, so an approval can start it again.
   const resume = resolveGateRunLocator();
@@ -637,6 +830,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(url ? { url } : {}),
     ...(resume ? { resume } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
     ...(env !== undefined ? { environment: env } : {}),
     ...(input.approval ? { approval: input.approval } : {}),
     ...(input.neverOverMcp ? { neverOverMcp: true as const } : {}),

package/src/op/index.ts

@@ -156,9 +156,12 @@ export type {
 export { renderHuman, renderJson } from "./local-output";
 export {
   activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES,
-  pathExistsInSchema,
+  pathExistsInSchema, readsSecretOutput,
 } from "./activity-contract";
 export type { ActivityContract, ActivityContractIssue } from "./activity-contract";
+export { validateGateResume, resumeGatesOf, decideGateResume } from "./gate-checkpoint";
+export type { ResumeGate, GateResumeDecision } from "./gate-checkpoint";
+export type { GateCheckpoint } from "../lifecycle/gate-checkpoint";
 export { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope, makeOutProxy } from "./step-output-ref";
 export type { StepOutputRef, WithStepRefs } from "./step-output-ref";
 export type { NamedActivityStep } from "./builders";

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