@intentius/chant 0.124.23 → 0.124.25

package/src/op/activities/shell.ts

@@ -3,6 +3,7 @@ import { promisify } from "node:util";
 import { GateWait, asPendingGate } from "../gate-wait";
 import type { PendingGateRecord } from "../../lifecycle/gate-ledger";
 import { liveRunEnv } from "../run-live";
+import { hasStepConsole, stepLineSplitter } from "../step-console";
 
 const execAsync = promisify(exec);
 
@@ -114,8 +115,17 @@ interface ExecFailure extends Error {
  */
 export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<ShellCmdResult> {
   const okExit = args.okExit ?? [0];
+  // #3956: under a step console (../step-console.ts) every line the command
+  // writes, stdout and stderr, is printed as it arrives; the result still
+  // carries both whole. Without one, stderr is printed when the command ends.
+  const streamed = hasStepConsole();
+  const printStderr = (text: string) => {
+    if (text && !streamed) console.error(text);
+  };
+  const out = stepLineSplitter();
+  const err = stepLineSplitter();
   try {
-    const { stdout, stderr } = await execAsync(args.cmd, {
+    const running = execAsync(args.cmd, {
       cwd: args.cwd,
       // In a run that keeps an in-flight record, CHANT_RUN_ACTIVITY names the
       // file the command appends activity lines to (../run-live.ts).
@@ -123,10 +133,22 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
       maxBuffer: MAX_STDOUT_BYTES,
       signal,
     });
-    if (stderr) console.error(stderr);
+    if (streamed) {
+      running.child.stdout?.on("data", (chunk: string | Buffer) => out.push(chunk));
+      running.child.stderr?.on("data", (chunk: string | Buffer) => err.push(chunk));
+    }
+    let settled: { stdout: string; stderr: string };
+    try {
+      settled = await running;
+    } finally {
+      out.end();
+      err.end();
+    }
+    const { stdout, stderr } = settled;
+    printStderr(stderr);
     return withJson({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }, args);
-  } catch (err) {
-    const failure = err as ExecFailure;
+  } catch (caught) {
+    const failure = caught as ExecFailure;
     const exitCode = typeof failure.code === "number" ? failure.code : undefined;
     // A signal kill (Ctrl-C, the profile's timeout, a maxBuffer overflow) is
     // not an exit status the author declared anything about, so it rethrows
@@ -134,12 +156,12 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
     const died = failure.killed === true || typeof failure.signal === "string" || signal?.aborted === true;
     if (exitCode !== undefined && !died && args.gatedExit !== undefined && exitCode === args.gatedExit) {
       const stderrText = (failure.stderr ?? "").trim();
-      if (stderrText) console.error(stderrText);
+      printStderr(stderrText);
       throw new GateWait(await commandGate(args, (failure.stdout ?? "").trim(), exitCode));
     }
     if (exitCode !== undefined && !died && okExit.includes(exitCode)) {
       const stderrText = (failure.stderr ?? "").trim();
-      if (stderrText) console.error(stderrText);
+      printStderr(stderrText);
       return withJson({ stdout: (failure.stdout ?? "").trim(), stderr: stderrText, exitCode }, args);
     }
     if (exitCode !== undefined && !died) {

package/src/op/effect-step.test.ts

@@ -12,7 +12,8 @@
  *   differing receipts as findings and never writes.
  */
 import { describe, test, expect, vi } from "vitest";
-import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION } from "../effect-receipt";
+import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION, declaredExpectation, withStepOutputs } from "../effect-receipt";
+import { stepOutput } from "./step-output-ref";
 import { INTRINSIC_MARKER, type Intrinsic } from "../intrinsic";
 import { effect, phase } from "./builders";
 import {
@@ -324,3 +325,96 @@ describe("runOpLocally — effect steps", () => {
     ).rejects.toThrow(/parallel phase/);
   });
 });
+
+// ── Step outputs inside an effect (#3948) ───────────────────────────────────
+
+describe("runOpLocally — an effect's nested steps read step outputs (#3948)", () => {
+  function refOp(): OpConfig {
+    return {
+      name: "seed-op",
+      overview: "",
+      phases: [
+        phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }]),
+        phase("Seed", [effect(seeded, [step("runSeed", { file: stepOutput("pick", "file") })])]),
+      ],
+    };
+  }
+
+  test("the resolved value reaches the nested step, and the receipt holds its digest", async () => {
+    const { store, values } = memStore();
+    const received: unknown[] = [];
+    let file = "a.sql";
+    const activities = activityMap(store, {
+      pick: async () => ({ file }),
+      runSeed: async (args) => void received.push(args),
+    });
+    const first = await runOpLocally(refOp(), activities, PROFILES);
+    expect(first.status).toBe("ok");
+    expect(received).toEqual([{ file: "a.sql" }]);
+    const written = values.get("seeded")!;
+    expect(written).not.toBe(receiptExpectation(seeded));
+    expect(declaredExpectation(written)).toBe(receiptExpectation(seeded));
+
+    // The same value: the receipt matches and the effect is skipped.
+    const second = await runOpLocally(refOp(), activities, PROFILES);
+    expect(received).toHaveLength(1);
+    expect(second.records.find((r) => r.fn === "receiptRead")?.outcome).toEqual({ name: "EffectApplied", value: true });
+
+    // A changed value fires the effect again, though the declared inputs did not change.
+    file = "b.sql";
+    await runOpLocally(refOp(), activities, PROFILES);
+    expect(received).toEqual([{ file: "a.sql" }, { file: "b.sql" }]);
+    expect(values.get("seeded")).not.toBe(written);
+  });
+
+  test("a receipt written before the effect read outputs re-fires the effect once", async () => {
+    const { store, values } = memStore({ seeded: receiptExpectation(seeded) });
+    const ran = vi.fn();
+    const activities = activityMap(store, { pick: async () => ({ file: "a.sql" }), runSeed: async () => { ran(); } });
+    await runOpLocally(refOp(), activities, PROFILES);
+    expect(ran).toHaveBeenCalledTimes(1);
+    expect(declaredExpectation(values.get("seeded")!)).toBe(receiptExpectation(seeded));
+  });
+
+  test("an existence receipt takes no outputs: it says the effect ran once", async () => {
+    const booted = EffectReceipt("booted", { effect: "bootstrap", flavor: "existence" });
+    const config: OpConfig = {
+      name: "boot-op",
+      overview: "",
+      phases: [
+        phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }]),
+        phase("Boot", [effect(booted, [step("boot", { file: stepOutput("pick", "file") })])]),
+      ],
+    };
+    const { store, values } = memStore();
+    const activities = activityMap(store, { pick: async () => ({ file: "a.sql" }), boot: async () => {} });
+    await runOpLocally(config, activities, PROFILES);
+    expect(values.get("booted")).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  test("an effect in onFailure whose source step did not complete is skipped whole (A6)", async () => {
+    const config: OpConfig = {
+      name: "seed-op",
+      overview: "",
+      phases: [phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }])],
+      onFailure: [phase("Undo", [effect(seeded, [step("unseed", { file: stepOutput("pick", "file") })])])],
+    };
+    const { store, writes } = memStore();
+    const ran = vi.fn();
+    const activities = activityMap(store, { pick: async () => { throw new Error("boom"); }, unseed: async () => { ran(); } });
+    const failure = (await runOpLocally(config, activities, PROFILES).catch((e) => e)) as OpRunFailure;
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect(ran).not.toHaveBeenCalled();
+    expect(writes).toEqual([]);
+    const skipped = failure.result.records.find((r) => r.fn === "effect:seeded");
+    expect(skipped?.status).toBe("skipped");
+    expect(skipped?.refusal).toMatch(/step "pick" did not complete/);
+  });
+
+  test("receiptStaleness compares the declared part of a value written with outputs", async () => {
+    const expected = receiptExpectation(seeded);
+    const { store } = memStore({ seeded: withStepOutputs(expected, "sha256:abc") });
+    const { receiptStaleness } = receiptActivities(store);
+    expect(await receiptStaleness({ receipts: [receiptCheckInput(seeded)] })).toEqual({ stale: false, findings: [] });
+  });
+});

package/src/op/emulator-lifecycle.test.ts

@@ -26,7 +26,7 @@ vi.mock("node:child_process", async () => {
   return { ...actual, exec: execStub, execFile: execFileStub };
 });
 
-const { clientHosts, emulatorLifecycle, endpointOnHost, hostPortInUse, parsePublishedAddresses, pickReachableEndpoint } =
+const { checkSettings, clientHosts, emulatorLifecycle, endpointOnHost, hostPortInUse, parsePublishedAddresses, pickReachableEndpoint } =
   await import("./emulator-lifecycle");
 
 describe("emulatorLifecycle command builders", () => {
@@ -60,6 +60,29 @@ describe("emulatorLifecycle command builders", () => {
     );
   });
 
+  test("network, settings and loopback go before the image (#3952)", () => {
+    const e = emulatorLifecycle({ name: "n", image: "img:1", containerPort: 80, healthPath: "/h", settingsPrefix: "X_" });
+    expect(e.runCommand({ network: "loom", settings: { X_MODE: "memory", X_TTL: "30" }, loopback: true })).toBe(
+      "docker run -d --rm --name n -p 127.0.0.1:80:80 --network loom -e X_MODE=memory -e X_TTL=30 img:1",
+    );
+  });
+
+  test("a setting value with spaces or shell syntax is quoted as one word (#3952)", () => {
+    const e = emulatorLifecycle({ name: "n", image: "img:1", containerPort: 80, healthPath: "/h", settingsPrefix: "X_" });
+    expect(e.runCommand({ settings: { X_A: "a b; rm -rf /", X_B: "it's" } })).toBe(
+      "docker run -d --rm --name n -p 80:80 -e 'X_A=a b; rm -rf /' -e 'X_B=it'\\''s' img:1",
+    );
+  });
+
+  test("settings outside the prefix, or on a spec without one, are refused (#3952)", () => {
+    const e = emulatorLifecycle({ name: "n", image: "img:1", containerPort: 80, healthPath: "/h", settingsPrefix: "X_" });
+    expect(() => e.runCommand({ settings: { PATH: "/tmp" } })).toThrow(/setting PATH is not a X_\* variable/);
+    expect(() => e.runCommand({ settings: { X_: "1" } })).toThrow(/not a X_\* variable/);
+    expect(() => e.runCommand({ settings: { "X_A;B": "1" } })).toThrow(/not a X_\* variable/);
+    expect(() => emu.runCommand({ settings: { X_A: "1" } })).toThrow(/takes no settings/);
+    expect(() => checkSettings({ name: "n", image: "i", containerPort: 1, settingsPrefix: "X_" }, {})).not.toThrow();
+  });
+
   test("exists / rm / health / endpoint", () => {
     expect(emu.existsCommand("n")).toBe("docker ps -q -f name=n");
     expect(emu.rmCommand("n")).toBe("docker rm -f n");

package/src/op/emulator-lifecycle.ts

@@ -41,6 +41,13 @@ export interface EmulatorSpec {
   ready?: (healthBody: string) => boolean;
   /** Extra `docker run` args inserted before the image (e.g. a socket mount). */
   runArgs?: readonly string[];
+  /**
+   * The prefix every key of {@link EmulatorUpArgs.settings} must start with,
+   * e.g. `FLOCI_` (#3952). Settings reach the container as `-e KEY=VALUE`, and
+   * the prefix keeps them to the emulator's own configuration instead of
+   * arbitrary env. An emulator without one takes no settings.
+   */
+  settingsPrefix?: string;
   /**
    * Where {@link image} is published, so how far behind the pin is can be
    * answered (#1345).
@@ -245,6 +252,43 @@ export interface EmulatorUpArgs {
   intervalMs?: number;
   /** Additional `docker run` args for this call (after `spec.runArgs`, before the image). */
   extraArgs?: readonly string[];
+  /** Docker network the container joins (`--network <name>`) (#3952). */
+  network?: string;
+  /**
+   * Emulator settings passed as `-e KEY=VALUE` (#3952). Every key must start
+   * with the spec's {@link EmulatorSpec.settingsPrefix}; see {@link checkSettings}.
+   */
+  settings?: Record<string, string>;
+  /** Publish the port on 127.0.0.1 only, instead of every host interface (#3952). */
+  loopback?: boolean;
+}
+
+/**
+ * Refuse settings an emulator does not take (#3952): a key outside the spec's
+ * {@link EmulatorSpec.settingsPrefix}, a key that is not an env-var name, or
+ * any setting at all for an emulator that declares no prefix. Throws with the
+ * first problem found.
+ */
+export function checkSettings(spec: EmulatorSpec, settings: Record<string, string> | undefined): void {
+  const keys = Object.keys(settings ?? {});
+  if (keys.length === 0) return;
+  const prefix = spec.settingsPrefix;
+  if (!prefix) {
+    throw new Error(`emulator "${spec.name}" takes no settings; got ${keys.join(", ")}`);
+  }
+  for (const key of keys) {
+    if (!key.startsWith(prefix) || key.length === prefix.length || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new Error(`emulator "${spec.name}": setting ${key} is not a ${prefix}* variable; only ${prefix}<NAME> keys reach the container`);
+    }
+  }
+}
+
+/**
+ * Quote one `docker run` word for the shell `up` runs it through: a setting's
+ * value or a network name can hold spaces or shell syntax.
+ */
+function shellWord(word: string): string {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
 }
 
 /** The shared lifecycle a per-cloud wrapper adapts. */
@@ -277,10 +321,14 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
     const name = args.name ?? spec.name;
     const port = args.port ?? spec.containerPort;
     const image = args.image ?? spec.image;
+    checkSettings(spec, args.settings);
+    const bind = args.loopback ? `127.0.0.1:${port}:${spec.containerPort}` : `${port}:${spec.containerPort}`;
     return [
-      "docker", "run", "-d", "--rm", "--name", name, "-p", `${port}:${spec.containerPort}`,
+      "docker", "run", "-d", "--rm", "--name", name, "-p", bind,
+      ...(args.network ? ["--network", args.network] : []),
+      ...Object.entries(args.settings ?? {}).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
       ...(spec.runArgs ?? []), ...(args.extraArgs ?? []), image,
-    ].join(" ");
+    ].map(shellWord).join(" ");
   };
   const existsCommand = (name: string): string => `docker ps -q -f name=${name}`;
   const rmCommand = (name: string): string => `docker rm -f ${name}`;
@@ -314,6 +362,8 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
     const port = args.port ?? spec.containerPort;
     const timeoutMs = args.timeoutMs ?? 60_000;
     const intervalMs = args.intervalMs ?? 2_000;
+    // Before the reuse check, so a bad key is refused whether or not a container runs.
+    checkSettings(spec, args.settings);
 
     let running = false;
     try {
@@ -330,6 +380,12 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
       // Progress → stderr, so a `--json` consumer (chant emulator, behold) reads
       // clean JSON on stdout. runOp/Op activities capture both streams regardless.
       console.error(`emulator container "${name}" already running — reusing`);
+      if (args.image || args.network || args.loopback || Object.keys(args.settings ?? {}).length) {
+        console.error(
+          `emulator "${name}": the image, network, settings and loopback options apply when a container starts, not to this running one. ` +
+            `Run \`chant emulator down\` first to start it with them.`,
+        );
+      }
       let published: PublishedAddress[] = [];
       try {
         const { stdout } = await execFileAsync("docker", ["port", name, `${spec.containerPort}/tcp`], { signal });

package/src/op/gate.ts

@@ -54,6 +54,7 @@ import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from
 import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 import { resolveGateRunLocator } from "./gate-run-locator";
+import { refuseGateWithoutRecording } from "../lifecycle/no-record";
 
 /**
  * What appending a pending fact learned about reaching the remote.
@@ -531,6 +532,8 @@ const EPOCH = new Date(0).toISOString();
  *   recorded" from "still standing".
  */
 export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput): Promise<GateCheck> {
+  // #3955: a run that records nothing cannot be approved or spend an approval.
+  refuseGateWithoutRecording(input.op, input.gate);
   const now = input.now ?? new Date().toISOString();
   const ledger = await port.read(input.op);
   // #2574: a component's ledger holds every environment's facts. This run

package/src/op/index.ts

@@ -11,7 +11,7 @@ export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, he
          spritesUp, spritesDown } from "./builders";
 export { OpResource } from "./resource";
 export { sleep } from "./activity-runtime";
-export { clientHosts, emulatorLifecycle, emulatorsOf, endpointEnvVars, endpointOnHost, hostPortInUse, parsePublishedAddresses, pickReachableEndpoint } from "./emulator-lifecycle";
+export { checkSettings, clientHosts, emulatorLifecycle, emulatorsOf, endpointEnvVars, endpointOnHost, hostPortInUse, parsePublishedAddresses, pickReachableEndpoint } from "./emulator-lifecycle";
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorIdentity, EmulatorUpArgs, EmulatorLifecycle, PublishedAddress } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";

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

@@ -459,6 +459,71 @@ describe("runOpLocally — gate as fact (#2119)", () => {
   });
 });
 
+describe("runOpLocally — step-output references in onFailure (#3948)", () => {
+  const failing: ActivityFn = async () => { throw new Error("boom"); };
+
+  test("a compensation step receives the value a main-phase step returned", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => ({ previous: "v1" })],
+      ["migrate", failing],
+      ["restore", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] },
+        { name: "Migrate", steps: [{ kind: "activity", fn: "migrate" }] },
+      ],
+      onFailure: [{ name: "Rollback", steps: [{ kind: "activity", fn: "restore", args: { revision: stepOutput("deploy", "previous") } }] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    expect(received).toEqual([{ revision: "v1" }]);
+  });
+
+  test("a compensation step whose source step did not complete is skipped, and the record says why (A6)", async () => {
+    const ran: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", failing],
+      ["restore", async () => void ran.push("restore")],
+      ["notify", async () => void ran.push("notify")],
+    ]);
+    const config = op({
+      phases: [{ name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] }],
+      onFailure: [{ name: "Rollback", steps: [
+        { kind: "activity", fn: "restore", args: { revision: stepOutput("deploy", "previous") } },
+        { kind: "activity", fn: "notify" },
+      ] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    // The skip is not a failure of compensation: the next step still runs.
+    expect(ran).toEqual(["notify"]);
+    const restore = err.result.records.find((r: { fn: string }) => r.fn === "restore");
+    expect(restore.status).toBe("skipped");
+    expect(restore.refusal).toMatch(/step "deploy" did not complete/);
+  });
+
+  test("the skip applies in a parallel compensation phase too", async () => {
+    const ran: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", failing],
+      ["restore", async () => void ran.push("restore")],
+      ["notify", async () => void ran.push("notify")],
+    ]);
+    const config = op({
+      phases: [{ name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] }],
+      onFailure: [{ name: "Rollback", parallel: true, steps: [
+        { kind: "activity", fn: "restore", args: { revision: stepOutput("deploy") } },
+        { kind: "activity", fn: "notify" },
+      ] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(ran).toEqual(["notify"]);
+    expect(err.result.records.find((r: { fn: string }) => r.fn === "restore").status).toBe("skipped");
+  });
+});
+
 describe("runOpLocally — step-output references (#1290)", () => {
   test("a later step receives the producer's resolved value, not the placeholder", async () => {
     const received: unknown[] = [];

package/src/op/local-executor.ts

@@ -23,8 +23,11 @@ import { outcomeAttributesOf } from "./types";
 import type { OpConfig, PhaseDefinition, ActivityStep, GateStep, EffectStep, StepDefinition } from "./types";
 import { resolveActivity, type ActivityFn, type ActivityProfile } from "./activity-registry";
 import type { ReceiptReadResult } from "./receipt-store";
-import { isStepOutputRef } from "./step-output-ref";
+import { collectStepOutputRefs, isStepOutputRef } from "./step-output-ref";
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
 import { parseDuration } from "./duration";
+import { stepLabel, withRunConsole, withStepConsole } from "./step-console";
 import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
@@ -277,6 +280,48 @@ function resolveStepOutputRefs(value: unknown, resultsById: ReadonlyMap<string,
   return value;
 }
 
+/** The activity steps a step runs: itself, or an effect's nested ones. */
+function activitiesOf(step: ActivityStep | EffectStep): ActivityStep[] {
+  return isEffect(step) ? step.steps.filter(isActivity) : [step];
+}
+
+/**
+ * The first step a compensation step references that has not completed in
+ * this run (#3948 decision A6), or `undefined` when every one did. A failure
+ * can stop the run before the step that a rollback reads, and calling the
+ * rollback with `undefined` in place of that value would undo the wrong
+ * thing, or nothing, while reporting `ok`.
+ */
+function unfinishedSource(step: ActivityStep | EffectStep, resultsById: ReadonlyMap<string, unknown>): string | undefined {
+  for (const activity of activitiesOf(step)) {
+    const missing = collectStepOutputRefs(activity.args).find((ref) => !resultsById.has(ref.step));
+    if (missing) return missing.step;
+  }
+  return undefined;
+}
+
+/** The skipped record of a compensation step whose source did not complete. */
+function unfinishedSourceRecord(step: ActivityStep | EffectStep, phaseName: string, source: string): StepRecord {
+  const record = isEffect(step) ? skippedRecord(phaseName, `effect:${step.receipt.name}`) : skippedRecord(phaseName, step.fn, step.args);
+  return { ...record, refusal: `step "${source}" did not complete in this run, so this compensation step, which reads its output, was skipped` };
+}
+
+/**
+ * The digest of the step outputs an effect's nested steps read (#3948), or
+ * `undefined` when they read none. The receipt store folds it into the
+ * expectation, so a changed value re-fires the effect instead of the receipt
+ * matching on the declared inputs alone. An existence receipt says only that
+ * the effect ran once, so it takes none.
+ */
+function effectOutputsDigest(step: EffectStep, resultsById: ReadonlyMap<string, unknown>): string | undefined {
+  if (step.receipt.flavor === "existence") return undefined;
+  const read = activitiesOf(step).flatMap((a) =>
+    collectStepOutputRefs(a.args).map((ref) => ({ step: ref.step, path: ref.path ?? "", value: resolveStepOutputRefs(ref, resultsById) })),
+  );
+  if (read.length === 0) return undefined;
+  return contentDigest(canonicalJson(read));
+}
+
 /**
  * Find the first `policyGate` step anywhere in the Op (phases + `onFailure`,
  * including steps nested inside effect steps), if any.
@@ -409,7 +454,8 @@ async function runStep(
   // The in-flight record names the step while it runs.
   const ended = currentLiveRun()?.stepStarted(step.fn, step.id);
   try {
-    return await attempts();
+    // #3956: its output printed as it arrives, and a line while it is quiet.
+    return await withStepConsole({ phase: phaseName, label: stepLabel(step.fn, args, step.id) }, attempts);
   } finally {
     ended?.();
   }
@@ -462,13 +508,14 @@ async function runStep(
 /** The step data the executor synthesizes to read a receipt through the store
  * activities (`receiptRead`/`receiptWrite` — provided by the receipt row's
  * lexicon, #1835, or a mock store in tests via `receiptActivities`). */
-function receiptReadStep(step: EffectStep): ActivityStep {
+function receiptReadStep(step: EffectStep, outputs?: string): ActivityStep {
   return {
     kind: "activity",
     fn: "receiptRead",
     args: {
       receipt: step.receipt,
       ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+      ...(outputs !== undefined ? { outputs } : {}),
     },
     profile: "fastIdempotent",
     outcomeAttribute: { name: "EffectApplied", from: "applied" },
@@ -494,6 +541,8 @@ interface GateContext {
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
+  /** Set in `onFailure` phases (#3948): a step whose referenced step did not complete is skipped. */
+  compensating?: boolean;
   /** How a gate that names a decision point asks it (#3170). */
   points?: GatePointAsker;
   /** The environment the run was started for, a point gate's `gate.env` input. */
@@ -788,7 +837,15 @@ async function runEffectStep(
 }> {
   const records: StepRecord[] = [];
 
-  const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, signal);
+  let outputs: string | undefined;
+  try {
+    outputs = effectOutputsDigest(step, resultsById);
+  } catch (err) {
+    // A resolved value JSON cannot hold (canonicalJson refuses it) would be a wrong expectation.
+    pushRecord(records, gates, { phase: phaseName, fn: `effect:${step.receipt.name}`, args: {}, status: "fail", durationMs: 0, error: errMessage(err) });
+    return { records, failed: true };
+  }
+  const read = await runStep(receiptReadStep(step, outputs), phaseName, activities, profiles, resultsById, signal);
   pushRecord(records, gates, read.record);
   if (read.record.status === "fail") return { records, failed: true };
 
@@ -948,7 +1005,10 @@ async function runPhase(
       }
     }
     const steps = phase.steps.filter(isActivity);
-    const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
+    const settled = await Promise.all(steps.map((s) => {
+      const source = gates.compensating ? unfinishedSource(s, resultsById) : undefined;
+      return source ? { record: unfinishedSourceRecord(s, phase.name, source) } as RanStep : runStep(s, phase.name, activities, profiles, resultsById, signal);
+    }));
     const ran = settled.map((r) => r.record);
     for (const r of ran) gates.onRecord?.(r);
     const records = gateRecords.concat(ran);
@@ -1009,6 +1069,11 @@ async function runPhase(
       }
       continue;
     }
+    const source = gates.compensating ? unfinishedSource(step, resultsById) : undefined;
+    if (source) {
+      pushRecord(records, gates, unfinishedSourceRecord(step, phase.name, source));
+      continue;
+    }
     if (isEffect(step)) {
       const { records: effRecords, failed, pending, pushed, pushWarning, point } = await runEffectStep(
         step, phase.name, activities, profiles, resultsById, gates, signal,
@@ -1109,6 +1174,16 @@ export interface RunOpOptions {
   work?: { item?: string; holder?: string };
   /** Called when a work-lease renewal fails without losing the lease; the next beat retries it. */
   onWorkLeaseWarning?: (message: string) => void;
+  /**
+   * Where a running step's output goes, line by line, as it arrives (#3956):
+   * `[<phase>] <step> | <line>` for each line a `shellCmd` command writes, and
+   * `[<phase>] <step>: still running after <n>s` for a step quiet for
+   * `stepHeartbeatMs` (./step-console.ts). The local runtime passes a writer
+   * to stderr. Omitted, nothing is printed while a step runs.
+   */
+  stepOutput?: (line: string) => void;
+  /** How long a step may be quiet before the still-running line. Default 60s; `0` turns it off. */
+  stepHeartbeatMs?: number;
 }
 
 /**
@@ -1165,9 +1240,14 @@ export async function runOpLocally(
       })
     : undefined;
   try {
+    const stepConsole = options.stepOutput
+      ? { write: options.stepOutput, ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}) }
+      : undefined;
     return await withLiveRun(live, () =>
-      withOpRunContext(run, () =>
-        runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }, run),
+      withRunConsole(stepConsole, () =>
+        withOpRunContext(run, () =>
+          runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }, run),
+        ),
       ),
     );
   } finally {
@@ -1427,7 +1507,7 @@ async function runOpInTurn(
     // Compensation: run onFailure phases in reverse order (best-effort). Skipped
     // on abort (Ctrl-C) — the user asked to stop, so don't start new work.
     // It runs whatever the work lease did, so it takes no work boundary.
-    const compensation: GateContext = { ...gates, work: undefined };
+    const compensation: GateContext = { ...gates, work: undefined, compensating: true };
     if (!signal?.aborted) {
       for (const phase of [...(config.onFailure ?? [])].reverse()) {
         try {