@intentius/chant 0.105.0 → 0.106.1

package/src/components/pr-run.ts

@@ -18,9 +18,22 @@
  * it against the new value. A change that must carry a moved output through
  * its dependents in one rollout is what gated waves are for (#3049): each
  * wave is planned after the one before it applied.
+ *
+ * ## Finishing an apply that failed partway
+ *
+ * {@link resumePrSet} (#3464) is fan-out's resume (#2417, #3049) for a pull
+ * request. The attempt record (`./fan-out-record.ts`) keeps the change set
+ * the gate approved and the components that applied. A re-run on the same
+ * commit narrows the derivation to what is left (`remainingFanOut`), plans
+ * only that against the outputs the approved plans read, and checks each
+ * member it plans against the approved set. When every one is covered, the
+ * gate is decided against the approved digest, which still stands, and only
+ * the rest applies. Planning everything again would give the applied members
+ * empty plans and the set a new digest, and so ask for a second approval of
+ * work already approved.
  */
 
-import { composeChangeSet, type ChangeSetDocument, type ChangeSetPart } from "../change-set";
+import { composeChangeSet, verifyChangeSetDigest, type ChangeSetDocument, type ChangeSetEntry, type ChangeSetPart } from "../change-set";
 import { evaluateGate, type GateCheck, type GateLedgerPort } from "../op/gate";
 import {
   memberCounts,
@@ -32,10 +45,11 @@ import {
   type PrReport,
   type PrStatus,
 } from "../pr-loop";
-import { deployContext, type DriverComponent } from "./driver";
+import { deployContext, type DriverComponent, type DriverComponentResult } from "./driver";
 import { deployUnits } from "./deploy-units";
 import { runFanOut, type FanOutRunResult } from "./fan-out-run";
-import type { ComponentChangeSignal, FanOutPlan } from "./fan-out";
+import { remainingFanOut, type ComponentChangeSignal, type FanOutPlan } from "./fan-out";
+import type { PrApplyRecord } from "./fan-out-record";
 import type { CapabilityRegistry } from "./capability";
 import type { RunProgressEvent } from "./run-progress";
 import { planWaveComponent, readComponentOutputs } from "./wave-plan";
@@ -189,9 +203,17 @@ export interface PrApplyOptions {
   registry: CapabilityRegistry;
   env: string;
   vars?: Record<string, unknown>;
-  /** The set {@link planPrSet} planned and the gate approved. */
+  /** The set {@link planPrSet} planned and the gate approved, or {@link resumePrSet}'s set. */
   set: PrPlanSet;
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * What an earlier attempt at this approved set applied (#3464): its
+   * components, which are reported applied and not run again, and the
+   * outputs they left.
+   */
+  resumed?: { completed: string[]; outputs: Record<string, Record<string, unknown>> };
+  /** Called as each component settles, so an attempt record survives a kill (`runFanOut`). */
+  onComponentSettled?: (result: DriverComponentResult, outputs: Record<string, unknown> | undefined) => void;
 }
 
 const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
@@ -208,8 +230,19 @@ export async function applyPrSet(options: PrApplyOptions): Promise<{ members: Pr
     plans: options.set.plans,
     componentOutputs: { ...before },
     ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+    ...(options.onComponentSettled ? { onComponentSettled: options.onComponentSettled } : {}),
   });
   const completed = new Set(run.completed);
+  const priorCompleted = new Set(options.resumed?.completed ?? []);
+  /**
+   * Whether a dependency's outputs moved from what the plans read: by this
+   * run's apply, or by the earlier attempt's when the record kept them.
+   */
+  const movedBy = (dep: string): boolean => {
+    if (completed.has(dep)) return !sameJson(before[dep], run.componentOutputs[dep]);
+    const earlier = options.resumed?.outputs;
+    return priorCompleted.has(dep) && earlier !== undefined && dep in earlier && !sameJson(before[dep], earlier[dep]);
+  };
   const blocked = new Set(run.blocked.map((b) => b.component));
   const errorOf = (component: string): string | undefined => {
     const result = run.results.find((r) => r.component === component);
@@ -218,9 +251,10 @@ export async function applyPrSet(options: PrApplyOptions): Promise<{ members: Pr
   };
   const byName = new Map(options.components.map((c) => [c.name, c]));
   const members = options.set.members.map((m): PrMember => {
+    if (priorCompleted.has(m.component)) return { ...m, status: "applied" };
     if (completed.has(m.component)) {
       const moved = (byName.get(m.component)?.dependsOn ?? [])
-        .filter((dep) => completed.has(dep) && !sameJson(before[dep], run.componentOutputs[dep]))
+        .filter(movedBy)
         .sort();
       return { ...m, status: "applied", ...(moved.length > 0 ? { inputsMoved: moved } : {}) };
     }
@@ -231,10 +265,163 @@ export async function applyPrSet(options: PrApplyOptions): Promise<{ members: Pr
   return { members, status: run.status === "ok" ? "applied" : "failed", run };
 }
 
+const entryKey = (e: Pick<ChangeSetEntry, "member" | "address" | "deposed">): string => `${e.member}\u0000${e.address}\u0000${e.deposed ?? ""}`;
+
+/**
+ * Why `member`'s fresh plan is not covered by the approved change set, or
+ * `undefined` when it is. A member left over from a partial apply is covered
+ * when it plans to the digest that was approved, or when every change it
+ * plans now is one the approved plan made:
+ *
+ * - an entry at the same address with the same action, or a `create` or a
+ *   `delete` where a `replace` was approved (the other half applied);
+ * - each attribute it writes was written by the approved entry, to the same
+ *   value or to one the approved plan knew only after apply. A sensitive
+ *   attribute carries no value to compare, so it is covered only where the
+ *   approved entry wrote that attribute as sensitive too. On a `create` left
+ *   from a `replace`, an attribute the replace did not change is not compared;
+ * - each side effect is one the approved plan ran.
+ *
+ * A member with holes the approved plan did not have is never covered by its
+ * entries, since its entries may not say everything it will do.
+ */
+export function planCoveredBy(approved: ChangeSetDocument, fresh: ChangeSetDocument, member: string): string | undefined {
+  const was = approved.members.find((m) => m.member === member);
+  const now = fresh.members.find((m) => m.member === member);
+  if (!now) return undefined;
+  if (!was) return `${member} was not in the approved plan`;
+  if (now.status === "failed" || now.planDigest === null) return `${member} failed to plan${now.error ? `: ${now.error}` : ""}`;
+  if (was.planDigest !== null && now.planDigest === was.planDigest) return undefined;
+  if (was.status === "failed") return `${member} had no approved plan`;
+  const knownHoles = new Set(was.holes.map((h) => h.address));
+  const newHole = now.holes.find((h) => !knownHoles.has(h.address));
+  if (newHole) return `${member} cannot read ${newHole.address} (${newHole.reason}), so its plan cannot be checked against the approved one`;
+
+  const approvedEntries = new Map(approved.entries.filter((e) => e.member === member).map((e) => [entryKey(e), e]));
+  for (const e of fresh.entries) {
+    if (e.member !== member || e.action === "no-op" || e.action === "read") continue;
+    // A create-before-destroy replace whose create applied leaves the old
+    // object deposed, and the plan now deletes it under a deposed key.
+    const a =
+      approvedEntries.get(entryKey(e)) ??
+      (e.action === "delete" && e.deposed ? approvedEntries.get(entryKey({ ...e, deposed: undefined })) : undefined);
+    if (!a) return `${member} now plans to ${e.action} ${e.address}, which the approved plan did not`;
+    const halfReplace = a.action === "replace" && (e.action === "create" || e.action === "delete");
+    if (a.action !== e.action && !halfReplace) {
+      return `${member} now plans to ${e.action} ${e.address}, where the approved plan would ${a.action} it`;
+    }
+    const approvedAttrs = new Map(a.attributes.map((attr) => [attr.path, attr]));
+    for (const attr of e.attributes) {
+      const at = `${e.address}.${attr.path}`;
+      const prior = approvedAttrs.get(attr.path);
+      if (!prior) {
+        if (halfReplace && e.action === "create") continue;
+        return `${member} now writes ${at}, which the approved plan did not`;
+      }
+      if (attr.sensitive) {
+        if (!prior.sensitive) return `${member} now writes ${at} as sensitive, so it cannot be compared with the approved value`;
+        continue;
+      }
+      if (prior.sensitive) return `${member} writes ${at}, which the approved plan wrote as sensitive, so it cannot be compared`;
+      if (prior.unknown) continue;
+      if (attr.unknown) return `${member} now writes ${at} with a value known only after apply, where the approved plan knew it`;
+      if (!sameJson(attr.after, prior.after)) return `${member} now writes ${at} to a different value than the approved plan`;
+    }
+  }
+  const approvedEffects = new Set(
+    (approved.sideEffects ?? []).filter((s) => s.member === member).map((s) => JSON.stringify([s.address, s.type, s.trigger ?? null, s.event ?? null])),
+  );
+  for (const s of fresh.sideEffects ?? []) {
+    if (s.member !== member) continue;
+    if (!approvedEffects.has(JSON.stringify([s.address, s.type, s.trigger ?? null, s.event ?? null]))) {
+      return `${member} now runs ${s.address}, which the approved plan did not`;
+    }
+  }
+  return undefined;
+}
+
+export interface PrResumeOptions {
+  components: DriverComponent[];
+  /** The fan-out the change derives now. The caller has checked it is the one the record was made from. */
+  plan: FanOutPlan;
+  registry: CapabilityRegistry;
+  env: string;
+  vars?: Record<string, unknown>;
+  seededOutputs?: Record<string, Record<string, unknown>>;
+  /** The approved set, from the attempt record. */
+  record: PrApplyRecord;
+  /** Components an earlier attempt applied. */
+  completed: string[];
+}
+
+export type PrResume =
+  | {
+      ok: true;
+      /** The derivation narrowed to what is left. */
+      plan: FanOutPlan;
+      /** The approved set, carrying fresh plans for the members left. Its digest is the approved one. */
+      set: PrPlanSet;
+      /** What the fresh plans of the members left came to. */
+      fresh: PrPlanSet;
+    }
+  | {
+      ok: false;
+      /** Why the approved set does not cover what is left, one line per member. */
+      reasons: string[];
+      fresh?: PrPlanSet;
+    };
+
+/**
+ * Plan what an apply that failed partway left (#3464): narrow the plan by
+ * the components that applied, plan the rest against the outputs the
+ * approved plans read, and check each member against the approved change
+ * set ({@link planCoveredBy}). Covered, the result is the approved set with
+ * the new plans in it, to decide the gate against `record.digest` and hand
+ * to {@link applyPrSet}. Not covered, it says why, and the caller plans
+ * everything and asks for a fresh approval.
+ *
+ * The record now travels between CI jobs through a cache (#3543), so its
+ * change set has to be the one its digest names: the document's own digest
+ * is `record.digest`, and its members' plan digests give that digest.
+ */
+export async function resumePrSet(options: PrResumeOptions): Promise<PrResume> {
+  const { record } = options;
+  if (record.changeSet.digest !== record.digest || !verifyChangeSetDigest(record.changeSet)) {
+    return { ok: false, reasons: [`the record's change set is not the one its digest ${record.digest} names`] };
+  }
+  const plan = remainingFanOut(options.plan, options.components, { completed: options.completed });
+  const fresh = await planPrSet({
+    components: options.components,
+    plan,
+    registry: options.registry,
+    env: options.env,
+    ...(options.vars ? { vars: options.vars } : {}),
+    seededOutputs: { ...(options.seededOutputs ?? {}), ...options.record.planOutputs },
+  });
+  const reasons = fresh.doc.members
+    .map((m) => planCoveredBy(options.record.changeSet, fresh.doc, m.member))
+    .filter((r): r is string => r !== undefined);
+  if (reasons.length > 0) return { ok: false, reasons, fresh };
+  return {
+    ok: true,
+    plan,
+    fresh,
+    set: {
+      doc: options.record.changeSet,
+      members: options.record.members.map((m) => ({ ...m, status: "planned" as const })),
+      plans: fresh.plans,
+      outputs: options.record.planOutputs,
+      failed: false,
+    },
+  };
+}
+
 export interface PrReportInput {
   stage: "plan" | "apply";
   pr: number | null;
   env: string;
+  /** The workspace member whose pipeline runs the stage (#3465). */
+  member?: string;
   base: string;
   head: string;
   op: string;
@@ -247,6 +434,8 @@ export interface PrReportInput {
   members?: PrMember[];
   refusal?: PrRefusal;
   message?: string;
+  /** Components an earlier attempt at the approved set applied (#3464). */
+  resumed?: string[];
 }
 
 /** The report a stage writes. */
@@ -258,6 +447,7 @@ export function prReport(input: PrReportInput): PrReport {
     stage: input.stage,
     pr: input.pr,
     env: input.env,
+    ...(input.member ? { member: input.member } : {}),
     base: input.base,
     head: input.head,
     op: input.op,
@@ -266,6 +456,7 @@ export function prReport(input: PrReportInput): PrReport {
     status: input.status,
     ...(input.refusal ? { refusal: input.refusal } : {}),
     ...(input.message ? { message: input.message } : {}),
+    ...(input.resumed ? { resumed: { applied: [...input.resumed].sort() } } : {}),
     approval: input.approval,
     selection: {
       changed: input.plan.order.filter((c) => changed.has(c)),

package/src/gated-waves.test.ts

@@ -115,4 +115,15 @@ describe("wave records", () => {
     expect(line).toContain("nothing in it was applied");
     expect(line).toContain("chant approve fan-out release-wave-2 --plan");
   });
+
+  test("the approve hint on an unsealed gate has no --sign", () => {
+    const line = describeChangedWave(record);
+    expect(line).not.toContain("--sign");
+    expect(line.endsWith(`--plan ${record.digest}`)).toBe(true);
+  });
+
+  test("the approve hint on a sealed gate ends in --sign", () => {
+    const line = describeChangedWave(record, true);
+    expect(line.endsWith(`--plan ${record.digest} --sign`)).toBe(true);
+  });
 });

package/src/gated-waves.ts

@@ -230,11 +230,16 @@ export function withWaveRecord(records: readonly WaveRecord[], record: WaveRecor
 /**
  * The refusal for a wave whose set changed after it was approved: the digest
  * that was approved, the one planned now, and that nothing in the wave ran.
+ * On a sealed gate the approve hint ends in `--sign`.
  */
-export function describeChangedWave(record: Pick<WaveRecord, "wave" | "op" | "gate" | "digest" | "approved">): string {
+export function describeChangedWave(
+  record: Pick<WaveRecord, "wave" | "op" | "gate" | "digest" | "approved">,
+  /** True when the gate is sealed (`identity.gates`): an approval without `--sign` doesn't count, so the hint says to sign. */
+  sealed = false,
+): string {
   return (
     `wave ${record.wave} changed after it was approved, so nothing in it was applied. ` +
     `approved: ${record.approved ?? "(none)"}; planned now: ${record.digest}. ` +
-    `Read the new plan, then approve it: chant approve ${record.op} ${record.gate} --plan ${record.digest}`
+    `Read the new plan, then approve it: chant approve ${record.op} ${record.gate} --plan ${record.digest}${sealed ? " --sign" : ""}`
   );
 }

package/src/lexicon.ts

@@ -41,6 +41,7 @@ export type {
   OpRunHandle,
   OpRunRecord,
   OpRunStartOptions,
+  OpGateResolveOptions,
   OpRunState,
   OpRunStatus,
 } from "./op/runtime";
@@ -562,6 +563,12 @@ export interface ComponentPipelineOptions {
    * GitLab's job rules) are limited to the member's files and the pipeline
    * file. Its jobs run in the member's directory, and its names carry the
    * member's name so two members' pipelines never collide.
+   *
+   * A pull-request pipeline (`prLoop`, #3465) takes no path filter: a change
+   * outside the member can reach it (a module it calls in another member),
+   * so its plan runs on every pull request and selects from the whole
+   * change. Its commands pass `--member`, which gives the member its own
+   * gate op, note and statuses on the pull request.
    */
   member?: PipelineMember;
 }
@@ -913,7 +920,12 @@ export interface ChangedUnitsContext {
   projectRoot: string;
   /** The resolved project configuration, for the lexicon's own namespace. */
   config: Record<string, unknown>;
-  /** Files the change added, modified or deleted, relative to `projectRoot`, with `/` separators. */
+  /**
+   * Files the change added, modified or deleted, relative to `projectRoot`,
+   * with `/` separators. Files outside `projectRoot` are listed too, as
+   * `../...`, so a unit that calls code outside the project (another
+   * workspace member's module, #3465) can claim them.
+   */
   changedFiles: string[];
 }
 

package/src/lifecycle/gate-ledger.ts

@@ -41,7 +41,7 @@
  * (absent on the resolution lines written before #2119, which is why
  * `"resolution"` is the default reading).
  */
-import { FAN_OUT_GATE_OP } from "../op/gate-name";
+import { isNeverOverMcpGateOp } from "../op/gate-name";
 import { samePlanDigest } from "./plan-digest";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
@@ -342,8 +342,9 @@ export async function appendPendingGate(
     kind: "pending",
     origin: currentGateOrigin(),
     // chant#3485: an Op MCP cannot discover declares nothing, so the gate
-    // records the rule for it. Every fan-out gate is one.
-    ...(input.op === FAN_OUT_GATE_OP ? { neverOverMcp: true as const } : {}),
+    // records the rule for it: fan-out, workspace-upgrade (chant#3513) and
+    // the pull-request gate's `pr-<number>` op.
+    ...(isNeverOverMcpGateOp(input.op) ? { neverOverMcp: true as const } : {}),
     ...input,
   };
   const commit = await appendGateLine(record, "Pending gate record", opts);

package/src/op/activities/factory.ts

@@ -111,6 +111,12 @@ function sameKind(file: string, kind: string, cwd: string): boolean {
 }
 
 /** The work kind's items and the box's intent, read through the read contract. */
+/** The contract an item's own field names, when the kind links no contract kind: its state is unknown to chant. */
+function contractField(data: Record<string, unknown> | null, field: string | undefined): { id: string; state: string | null } | null {
+  const value = data?.[field ?? "contract"];
+  return typeof value === "string" && value.trim() !== "" ? { id: value.trim(), state: null } : null;
+}
+
 async function readWork(cwd: string, kind?: string): Promise<WorkRead> {
   const { declaredKindFiles, queryDeclaredRecords } = await import("../../workspace/records-cli");
   const { loadRecordKind } = await import("../../workspace/records");
@@ -142,7 +148,9 @@ async function readWork(cwd: string, kind?: string): Promise<WorkRead> {
         ready: r.ready ?? false,
         data,
         tier: typeof tier === "string" ? tier : null,
-        contract: r.contract ?? null,
+        // The kind's contract link, else the item's own contract field (#3503): a kind whose contracts aren't
+        // a chant record kind yet, such as studio's markdown contracts, still names the contract an item builds.
+        contract: r.contract ?? contractField(data, work.contract?.field),
         warnings: r.warnings.map((w) => w.code),
         answers: (r.answers ?? []).map((a) => ({ id: a.id, point: a.point, state: a.state, answer: a.answer })),
         leased: !!r.lease,

package/src/op/gate-name.ts

@@ -37,6 +37,23 @@ export const FAN_OUT_GATE_OP = "fan-out";
  */
 export const WORKSPACE_UPGRADE_GATE_OP = "workspace-upgrade";
 
+/**
+ * The pull-request loop records its gate under `pr-<number>`, or
+ * `pr-<number>-<member>` in a workspace member (`prOp` in `pr-loop.ts`), and
+ * no `*.op.ts` stands behind that name either.
+ */
+const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
+
+/**
+ * Whether gates recorded under this op name are never resolved over MCP or ACP
+ * (chant#3485, chant#3513). These are the gate-only names MCP cannot discover:
+ * `fan-out`, `workspace-upgrade` and the pull-request gate `pr-<number>`. With
+ * no Op config to read `neverOverMcp` from, the pending record carries it.
+ */
+export function isNeverOverMcpGateOp(op: string): boolean {
+  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || PR_GATE_OP.test(op);
+}
+
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */
 export interface GateNamed {
   gate?: string;

package/src/op/gate-summary.test.ts

@@ -107,3 +107,15 @@ describe("writeGatedRunSummary surfaces (#2243, #2256)", () => {
     expect(writeGatedRunSummary(summary, { CHANT_GATE_SUMMARY: "/no/such/dir/gate.md" })).toBeUndefined();
   });
 });
+
+describe("gatedRunSummaryMarkdown on a sealed gate (#3521)", () => {
+  test("the approve line carries --sign when sealed", () => {
+    const md = gatedRunSummaryMarkdown({ ...summary, sealed: true });
+    expect(md).toContain("chant approve app-apply approve-app-apply --sign --approver <you>");
+  });
+
+  test("the approve line has no --sign when unsealed", () => {
+    expect(gatedRunSummaryMarkdown({ ...summary, sealed: false })).not.toContain("--sign");
+    expect(gatedRunSummaryMarkdown(summary)).not.toContain("--sign");
+  });
+});

package/src/op/gate-summary.ts

@@ -57,6 +57,8 @@ export interface GatedRunSummary {
    * Absent at level 0 and for the root member.
    */
   ledgerPrefix?: string;
+  /** Whether the workspace seals this gate, so the `chant approve` line carries `--sign`. */
+  sealed?: boolean;
   /** The environment a component gate's pending fact was recorded in (#2574). The `chant approve` line names it. */
   environment?: string;
 }
@@ -101,7 +103,7 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
     "Approve it, then re-run this workflow:",
     "",
     "```",
-    `${approveCommand(summary.op, summary.gate, summary.environment)} --approver <you>`,
+    `${approveCommand(summary.op, summary.gate, summary.environment, undefined, summary.sealed === true)} --approver <you>`,
     "```",
     "",
     `Ledger: \`${gateLedgerPath(summary.op, summary.ledgerPrefix)}\` on the \`chant/lifecycle\` branch.`,

package/src/op/gate.test.ts

@@ -16,7 +16,7 @@ import { writeFileSync } from "node:fs";
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import { approveCommand, describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedgerPort } from "./gate";
 import { appendGateResolution, readGateLedger } from "../lifecycle/gate-ledger";
 import {
   requireLifecycleLedger,
@@ -612,3 +612,17 @@ describe("op/gate — a rejected ledger push is reported, not swallowed (#2310)"
     expect(check.pending.gate).toBe("approve-live-apply");
   });
 });
+
+describe("op/gate — the approve hint on a sealed gate (#3521)", () => {
+  test("approveCommand adds --sign last, only when sealed", () => {
+    expect(approveCommand("app", "ship")).toBe("chant approve app ship");
+    expect(approveCommand("app", "ship", "prod", "sha256:abc", true)).toBe("chant approve app ship --env prod --plan sha256:abc --sign");
+    expect(approveCommand("app", "ship", undefined, undefined, false)).toBe("chant approve app ship");
+  });
+
+  test("describeGateMismatch names --sign when sealed, and not when unsealed", () => {
+    const mismatch = { approved: "sha256:old", planned: "sha256:new", resolvedBy: "alex", timestamp: "2026-09-08T00:00:00Z" } as GateDigestMismatch;
+    expect(describeGateMismatch("app", "ship", mismatch, true)).toMatch(/chant approve app ship --sign$/);
+    expect(describeGateMismatch("app", "ship", mismatch)).not.toContain("--sign");
+  });
+});

package/src/op/gate.ts

@@ -235,7 +235,7 @@ export interface GateDigestMismatch {
  * have changed — the record simply never said what it approved, which is
  * every record written before #2300.
  */
-export function describeGateMismatch(op: string, gate: string, mismatch: GateDigestMismatch): string {
+export function describeGateMismatch(op: string, gate: string, mismatch: GateDigestMismatch, sealed = false): string {
   const why =
     mismatch.approved === undefined
       ? mismatch.environment !== undefined
@@ -249,7 +249,7 @@ export function describeGateMismatch(op: string, gate: string, mismatch: GateDig
     `Gate "${gate}" is approved, but not for this plan. ` +
     `approved: ${describePlanDigest(mismatch.approved)} (by ${mismatch.resolvedBy} at ${mismatch.timestamp}); ` +
     `planned: ${mismatch.planned}. ` +
-    `${why} ${approveCommand(op, gate, mismatch.environment)}`
+    `${why} ${approveCommand(op, gate, mismatch.environment, undefined, sealed)}`
   );
 }
 
@@ -512,8 +512,25 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
  * plan the reader was shown and not whatever is pending by the time they run
  * it.
  */
-export function approveCommand(op: string, gate: string, environment?: string, planDigest?: string): string {
+export function approveCommand(op: string, gate: string, environment?: string, planDigest?: string, sealed = false): string {
   return `chant approve ${op} ${gate}` +
     (environment === undefined ? "" : ` --env ${environment}`) +
-    (planDigest === undefined ? "" : ` --plan ${planDigest}`);
+    (planDigest === undefined ? "" : ` --plan ${planDigest}`) +
+    (sealed ? " --sign" : "");
+}
+
+/**
+ * Whether the workspace seals `gate` (`identity.gates`), so an approval
+ * without `--sign` doesn't count. Callers pass the answer to
+ * {@link approveCommand} so the hint names the flag. Loaded on demand, as the
+ * git ledger port does: the workspace modules import the Op modules. A read
+ * that throws counts as unsealed, since the hint is advice and not the check.
+ */
+export async function gateIsSealed(gate: string, cwd: string = process.cwd()): Promise<boolean> {
+  try {
+    const { gateAdmission } = await import("../workspace/identity");
+    return gateAdmission(cwd, gate) !== null;
+  } catch {
+    return false;
+  }
 }

package/src/op/index.ts

@@ -62,7 +62,7 @@ export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
 export { currentOpRun, withOpRunContext } from "./run-context";
 export type { OpRunContext, PassedGate } from "./run-context";
-export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch } from "./gate";
+export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch, gateIsSealed } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch, GateQuorumProgress, GateTally } from "./gate";
 export { tallyGateApprovals, approverOf } from "./gate";
 export {
@@ -80,7 +80,7 @@ export type { GateNamed } from "./gate-name";
 export { createLocalOpRuntime } from "./runtimes/local";
 export { runStateOf } from "./runtime";
 export type {
-  OpRuntimeProvider, OpRunHandle, OpRunStartOptions, OpRunState, OpRunStatus,
+  OpRuntimeProvider, OpRunHandle, OpRunStartOptions, OpGateResolveOptions, OpRunState, OpRunStatus,
   OpRunRecord, OpRunRecordInput, OpRunPhaseRecord, OpRunStepRecord,
 } from "./runtime";
 export { buildOpIR, serializeOpIR, opConfigFromIR, OP_IR_FORMAT_VERSION } from "./op-ir";

package/src/op/local-executor.test.ts

@@ -9,6 +9,14 @@ import {
 import { memoryGateLedgerPort, type GateLedgerPort } from "./gate";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import { renderHuman } from "./local-output";
+
+// #3521: whether the workspace seals a gate is read from identity.gates in the
+// working directory; a test says which gates are sealed instead.
+const sealedGates = new Set<string>();
+vi.mock("./gate", async () => {
+  const actual = await vi.importActual<typeof import("./gate")>("./gate");
+  return { ...actual, gateIsSealed: async (gate: string) => sealedGates.has(gate) };
+});
 import type { GateResolutionRecord, PendingGateRecord, PendingGateInput } from "../lifecycle/gate-ledger";
 import { stepOutput } from "./step-output-ref";
 
@@ -778,6 +786,33 @@ describe("runOpLocally — a gate approves a plan, not the next run (#2300)", ()
     expect(lines.some((l) => l.includes("[refused]") && l.includes("not for this plan"))).toBe(true);
   });
 
+  describe("the refusal's approve command (#3521)", () => {
+    async function refusalOnRename(): Promise<string | undefined> {
+      const { root, activities, config, digestOf } = harness();
+      const gates = approvableLedger();
+      await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW });
+      gates.approve("approve-live-apply", digestOf("aws_s3_bucket.original"), "2026-09-09T12:05:00.000Z");
+      root.address = "aws_s3_bucket.renamed";
+      const second = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-09-09T12:10:00.000Z" });
+      return second.records.find((r) => r.fn === "gate:approve-live-apply")?.refusal;
+    }
+
+    test("unsealed gate: the refusal's approve command has no --sign", async () => {
+      const refusal = await refusalOnRename();
+      expect(refusal).toContain("chant approve live-apply approve-live-apply");
+      expect(refusal).not.toContain("--sign");
+    });
+
+    test("sealed gate: the refusal's approve command ends in --sign", async () => {
+      sealedGates.add("approve-live-apply");
+      try {
+        expect(await refusalOnRename()).toContain("chant approve live-apply approve-live-apply --sign");
+      } finally {
+        sealedGates.clear();
+      }
+    });
+  });
+
   test("approve, re-run with the root unchanged — it applies", async () => {
     const { applied, activities, config, digestOf } = harness();
     const gates = approvableLedger();

package/src/op/local-executor.ts

@@ -26,7 +26,7 @@ import type { ReceiptReadResult } from "./receipt-store";
 import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
 import { stepTimeoutProblem } from "./activity-profiles";
-import { describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
+import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
 import type { ResolvedGateApproval } from "./gate-approval";
 import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
@@ -672,7 +672,7 @@ async function runGateStep(
   }
 
   const refusal = check.mismatch
-    ? { refusal: describeGateMismatch(gates.op, gateName(step), check.mismatch) }
+    ? { refusal: describeGateMismatch(gates.op, gateName(step), check.mismatch, await gateIsSealed(gateName(step))) }
     : {};
   return {
     record: {

package/src/op/local-output.test.ts

@@ -207,3 +207,23 @@ describe("renderJson", () => {
     expect(parsed.pushed).toBeUndefined();
   });
 });
+
+describe("a sealed gate's approve line carries --sign (#3521)", () => {
+  test("renderHuman prints --sign when sealed, and not when unsealed", () => {
+    const sealed: string[] = [];
+    renderHuman(GATED_WITH_PLAN, (l) => sealed.push(l), true);
+    expect(sealed.join("\n")).toContain(`approve : chant approve prod-apply rollout-gate --plan ${GATED_WITH_PLAN.gate!.planDigest} --sign`);
+    const unsealed: string[] = [];
+    renderHuman(GATED_WITH_PLAN, (l) => unsealed.push(l), false);
+    expect(unsealed.join("\n")).not.toContain("--sign");
+  });
+
+  test("renderJson's approve field carries --sign when sealed, and not when unsealed", () => {
+    const sealed: string[] = [];
+    renderJson(GATED, (l) => sealed.push(l), true);
+    expect(JSON.parse(sealed[0]).approve).toBe("chant approve prod-apply rollout-gate --sign");
+    const unsealed: string[] = [];
+    renderJson(GATED, (l) => unsealed.push(l), false);
+    expect(JSON.parse(unsealed[0]).approve).toBe("chant approve prod-apply rollout-gate");
+  });
+});