@intentius/chant 0.124.31 → 0.124.33

package/src/op/activities/shell.test.ts

@@ -10,7 +10,7 @@
 
 import { describe, test, expect } from "vitest";
 import { z } from "zod";
-import { shellCmd } from "./shell";
+import { containerCommand, imageProblem, shellCmd } from "./shell";
 import { shellCmdContract } from "./activity-contracts";
 import { shell } from "../builders";
 import { activity, phase } from "../builders";
@@ -244,3 +244,46 @@ describe("a step's own timeout (#2787)", () => {
     }
   });
 });
+
+describe("shellCmd in a container (#4015)", () => {
+  const PINNED = `alpine:3.21@sha256:${"e".repeat(64)}`;
+
+  test("builds a docker run --rm line: workspace read-only, env by name, the command under sh -c", () => {
+    const line = containerCommand({ cmd: "make test", image: PINNED, env: { TOKEN: "x", MODE: "ci" } }, { cwd: "/src/app" });
+    expect(line).toBe(`docker run --rm -v '/src/app:/workspace:ro' -w /workspace -e 'TOKEN' -e 'MODE' '${PINNED}' sh -c 'make test'`);
+  });
+
+  test("mounts each output directory writable over a read-only workspace, and none over a writable one", () => {
+    const ro = containerCommand({ cmd: "npm run build", image: PINNED, outputs: ["dist", "./reports/"] }, { cwd: "/src/app", cli: "podman", user: "501:20" });
+    expect(ro).toBe(
+      `podman run --rm --user 501:20 -v '/src/app:/workspace:ro' -v '/src/app/dist:/workspace/dist:rw' -v '/src/app/reports:/workspace/reports:rw' -w /workspace '${PINNED}' sh -c 'npm run build'`,
+    );
+    const rw = containerCommand({ cmd: "make", image: PINNED, mounts: { workspace: "rw" }, outputs: ["dist"] }, { cwd: "/src/app" });
+    expect(rw).toBe(`docker run --rm -v '/src/app:/workspace:rw' -w /workspace '${PINNED}' sh -c 'make'`);
+  });
+
+  test("an image is pinned by digest, as a literal string", () => {
+    expect(imageProblem(PINNED)).toBeUndefined();
+    expect(imageProblem("alpine:3.21")).toMatch(/not pinned by digest/);
+    expect(imageProblem(`alpine@sha256:${"E".repeat(64)}`)).toMatch(/not pinned by digest/);
+    expect(imageProblem(42)).toMatch(/literal string/);
+  });
+
+  test("refuses before running anything: a tag, an output outside the working directory, outputs without an image", async () => {
+    await expect(shellCmd({ cmd: "true", image: "alpine:3.21" })).rejects.toThrow(/not pinned by digest/);
+    await expect(shellCmd({ cmd: "true", image: PINNED, outputs: ["../escape"] })).rejects.toThrow(/inside the working directory/);
+    await expect(shellCmd({ cmd: "true", image: PINNED, outputs: ["/etc"] })).rejects.toThrow(/inside the working directory/);
+    await expect(shellCmd({ cmd: "true", outputs: ["dist"] })).rejects.toThrow(/give the step an image/);
+  });
+
+  test("the contract accepts image, mounts and outputs", () => {
+    expect(shellCmdContract.args.safeParse({ cmd: "x", image: PINNED, mounts: { workspace: "rw" }, outputs: ["dist"] }).success).toBe(true);
+    expect(shellCmdContract.args.safeParse({ cmd: "x", mounts: { workspace: "rwx" } }).success).toBe(false);
+  });
+
+  test("the shell() builder passes them through to the step", () => {
+    const step = shell("npm test", { image: PINNED, outputs: ["coverage"] });
+    expect(step.args).toEqual({ cmd: "npm test", image: PINNED, outputs: ["coverage"] });
+  });
+});
+

package/src/op/activities/shell.ts

@@ -1,4 +1,6 @@
 import { exec } from "node:child_process";
+import { mkdir, readdir } from "node:fs/promises";
+import { isAbsolute, join, normalize, resolve } from "node:path";
 import { promisify } from "node:util";
 import { GateWait, asPendingGate } from "../gate-wait";
 import type { PendingGateRecord } from "../../lifecycle/gate-ledger";
@@ -56,6 +58,84 @@ export interface ShellCmdArgs {
    * something else. Empty stdout is `null`.
    */
   json?: boolean;
+  /**
+   * Run the command in a container (#4015) instead of on the host: an image
+   * pinned by digest, `<ref>@sha256:<64 hex>`, so the step names the
+   * toolchain it ran with. The step's working directory is mounted at
+   * `/workspace`, which is the command's working directory; the container
+   * sees `env` by name and nothing of this process's environment, whatever
+   * `inheritEnv` says. Run with `docker run --rm`, or the command
+   * `CHANT_CONTAINER_CLI` names (`podman`).
+   */
+  image?: string;
+  /** How the container mounts the working directory (#4015). Default `{ workspace: "ro" }`. */
+  mounts?: { workspace?: "ro" | "rw" };
+  /**
+   * Directories under the working directory the containerized command writes
+   * (#4015). Each is created on the host if missing and mounted writable at
+   * the same path, so what the command leaves there stays on the host. A
+   * directory still empty when the command ends fails a step that otherwise
+   * passed. Only with `image`.
+   */
+  outputs?: string[];
+}
+
+/** An image reference pinned by digest (#4015): anything, then `@sha256:` and 64 lowercase hex digits. */
+export const PINNED_IMAGE = /^[^\s@]+@sha256:[0-9a-f]{64}$/;
+
+/** Why `image` can't run, or undefined when it is a reference pinned by digest. */
+export function imageProblem(image: unknown): string | undefined {
+  if (typeof image !== "string") return "image must be a literal string, an image reference pinned by digest";
+  if (!PINNED_IMAGE.test(image)) return `image ${JSON.stringify(image)} is not pinned by digest: name it as <ref>@sha256:<digest>`;
+  return undefined;
+}
+
+/** Why an `outputs` path can't be copied back, or undefined when it is a relative path inside the working directory. */
+function outputProblem(path: string): string | undefined {
+  const n = normalize(path);
+  if (path === "" || isAbsolute(path) || n === ".." || n.startsWith("../") || n === ".") return `output ${JSON.stringify(path)} must be a relative path inside the working directory`;
+  return undefined;
+}
+
+function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Where a containerized command sees the working directory. */
+const WORKSPACE = "/workspace";
+
+/**
+ * The `docker run --rm` line for a step with `image` (#4015). The working
+ * directory is mounted at `/workspace`, read-only by default, and each
+ * declared output directory is mounted writable on top of it.
+ */
+export function containerCommand(args: ShellCmdArgs & { image: string }, where: { cwd: string; cli?: string; user?: string }): string {
+  const mode = args.mounts?.workspace ?? "ro";
+  const outputs = mode === "ro" ? (args.outputs ?? []).map((p) => normalize(p).replace(/\/+$/, "")) : [];
+  return [
+    where.cli ?? "docker",
+    "run",
+    "--rm",
+    ...(where.user ? ["--user", where.user] : []),
+    "-v",
+    shellQuote(`${where.cwd}:${WORKSPACE}:${mode}`),
+    ...outputs.flatMap((p) => ["-v", shellQuote(`${join(where.cwd, p)}:${WORKSPACE}/${p}:rw`)]),
+    "-w",
+    WORKSPACE,
+    ...Object.keys(args.env ?? {}).flatMap((name) => ["-e", shellQuote(name)]),
+    shellQuote(args.image),
+    "sh",
+    "-c",
+    shellQuote(args.cmd),
+  ].join(" ");
+}
+
+/** Throw when a declared output directory is still empty after a command that passed. */
+async function checkOutputs(outputs: readonly string[], cwd: string): Promise<void> {
+  for (const p of outputs) {
+    const entries = await readdir(join(cwd, normalize(p))).catch(() => []);
+    if (entries.length === 0) throw new Error(`the step declares output ${JSON.stringify(p)}, and the command left it empty`);
+  }
 }
 
 /**
@@ -130,12 +210,20 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
   };
   const out = stepLineSplitter();
   const err = stepLineSplitter();
+  if (args.image === undefined && (args.outputs !== undefined || args.mounts !== undefined)) {
+    throw new Error("outputs and mounts apply only to a step that runs in a container: give the step an image");
+  }
+  const container = args.image !== undefined ? await prepareContainer(args) : undefined;
   try {
-    const running = execAsync(args.cmd, {
+    const running = execAsync(container?.cmd ?? 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).
-      env: { ...(args.inheritEnv === false ? {} : process.env), ...liveRunEnv(), ...args.env },
+      // file the command appends activity lines to (../run-live.ts). Under
+      // `image` the container CLI gets this process's environment, so it can
+      // reach its daemon, and the container gets `env` alone, by name.
+      env: container
+        ? { ...process.env, ...args.env }
+        : { ...(args.inheritEnv === false ? {} : process.env), ...liveRunEnv(), ...args.env },
       maxBuffer: MAX_STDOUT_BYTES,
       signal,
     });
@@ -152,6 +240,7 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
     }
     const { stdout, stderr } = settled;
     printStderr(stderr);
+    if (container) await checkOutputs(args.outputs ?? [], container.cwd);
     return withJson({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }, args);
   } catch (caught) {
     const failure = caught as ExecFailure;
@@ -179,6 +268,24 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
   }
 }
 
+/** The container line for a step with `image` (#4015), checked first, with each output directory made on the host. */
+async function prepareContainer(args: ShellCmdArgs): Promise<{ cmd: string; cwd: string }> {
+  const problem = imageProblem(args.image) ?? (args.outputs ?? []).map(outputProblem).find((p) => p !== undefined);
+  if (problem) throw new Error(problem);
+  const cwd = resolve(args.cwd ?? process.cwd());
+  // A writable mount inside a read-only one needs its mountpoint to exist already.
+  for (const p of args.outputs ?? []) await mkdir(join(cwd, normalize(p)), { recursive: true });
+  // The host's uid and gid, so what the command writes belongs to whoever
+  // runs chant rather than to the image's root.
+  const user = typeof process.getuid === "function" && typeof process.getgid === "function" ? `${process.getuid()}:${process.getgid()}` : undefined;
+  const cmd = containerCommand(args as ShellCmdArgs & { image: string }, {
+    cwd,
+    ...(process.env.CHANT_CONTAINER_CLI ? { cli: process.env.CHANT_CONTAINER_CLI } : {}),
+    ...(user ? { user } : {}),
+  });
+  return { cmd, cwd };
+}
+
 /** The pending fact a command's stdout carries: the whole of it as JSON, or its last line. */
 function pendingFromStdout(stdout: string): PendingGateRecord | undefined {
   const lines = stdout.split("\n");

package/src/op/builders.ts

@@ -391,6 +391,13 @@ export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedAct
  * twenty minutes, and keeps the profile's retries: `shell("./build.sh", {
  * timeout: "45m" })`. At most six hours (`MAX_STEP_TIMEOUT`).
  *
+ * `image` runs the command in a container instead of on the host (#4015),
+ * pinned by digest, with the working directory mounted read-only at
+ * `/workspace` unless `mounts` says `rw`, and each `outputs` directory
+ * mounted writable:
+ * `shell("npm run build", { image: "node:24@sha256:<digest>", outputs: ["dist"] })`.
+ * OPS018 refuses an image that is not pinned by digest.
+ *
  * `cmd` stays a plain `string` and takes no references. A value spliced into
  * a command line is a quoting decision chant would then be making on the
  * author's behalf, and `env` carries the same value into the same command

package/src/op/discover-root.test.ts

@@ -15,13 +15,15 @@ import { discoverOps } from "./discover";
  * with whatever the current test set (`realpath`ed, since macOS's tmpdir is a
  * symlink and the walk compares resolved paths).
  */
-let fakeGitRoot = "";
+let fakeGitRoot: string | undefined = "";
 vi.mock("../runtime-adapter", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../runtime-adapter")>()),
   getRuntime: () => ({
     spawn: async (cmd: string[]) =>
       cmd[0] === "git" && cmd[1] === "rev-parse"
-        ? { stdout: fakeGitRoot, stderr: "", exitCode: 0 }
+        ? fakeGitRoot === undefined
+          ? { stdout: "", stderr: "fatal: not a git repository", exitCode: 128 }
+          : { stdout: fakeGitRoot, stderr: "", exitCode: 0 }
         : { stdout: "", stderr: "", exitCode: 0 },
   }),
 }));
@@ -68,6 +70,33 @@ describe("discoverOps — the scan root is the project, not the checkout (#2058)
   });
 });
 
+describe("discoverOps outside a git repository (#2504)", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-op-nogit-")));
+    fakeGitRoot = undefined;
+    mkdirSync(join(dir, "demo", "ops"), { recursive: true });
+    writeFileSync(join(dir, "demo", "ops", "apply.op.ts"), OP_FILE("k3d-apply"));
+  });
+  afterEach(() => {
+    fakeGitRoot = "";
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a chant.config names the project root, so no git root is needed", async () => {
+    writeFileSync(join(dir, "demo", "chant.config.json"), JSON.stringify({ lexicons: ["k8s"] }));
+    const { ops, errors } = await discoverOps({ cwd: join(dir, "demo", "ops") });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["k3d-apply"]);
+  });
+
+  test("with neither a config nor a git root, discovery says both are missing", async () => {
+    await expect(discoverOps({ cwd: join(dir, "demo") })).rejects.toThrow(
+      /Not in a git repository, and no chant\.config/,
+    );
+  });
+});
+
 /**
  * #2171. An Op may be exported by name, not only as the file's default.
  *

package/src/op/discover.ts

@@ -25,10 +25,11 @@ export interface OpDiscoveryResult {
   errors: string[];
 }
 
-async function findGitRoot(cwd?: string): Promise<string> {
+/** The git root `cwd` is inside, or undefined when it is in no repository. */
+async function findGitRoot(cwd?: string): Promise<string | undefined> {
   const rt = getRuntime();
   const result = await rt.spawn(["git", "rev-parse", "--show-toplevel"], { cwd });
-  if (result.exitCode !== 0) throw new Error("Not in a git repository");
+  if (result.exitCode !== 0) return undefined;
   return result.stdout.trim();
 }
 
@@ -43,17 +44,26 @@ async function findGitRoot(cwd?: string): Promise<string> {
  * file is the project boundary, the same one entity discovery respects.
  * With no config anywhere up to the git root, the git root stands —
  * #1675's original scope, kept for configless layouts.
+ *
+ * Outside any git repository the walk goes to the filesystem root, and the
+ * config is all discovery needs (#2504): a demo copy, an unpacked tarball or
+ * a fresh `chant init` before `git init`. Only a directory with neither a
+ * config above it nor a git root has no Op root, and that is the error.
  */
 async function findDiscoveryRoot(cwd?: string): Promise<string> {
-  const gitRoot = resolve(await findGitRoot(cwd));
+  const found = await findGitRoot(cwd);
+  const gitRoot = found === undefined ? undefined : resolve(found);
   let dir = resolve(cwd ?? process.cwd());
   for (;;) {
     if (existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json"))) return dir;
     if (dir === gitRoot) break;
     const parent = dirname(dir);
-    if (parent === dir) break; // filesystem root — cwd was outside the git root
+    if (parent === dir) break; // filesystem root — cwd was outside the git root, or there is none
     dir = parent;
   }
+  if (gitRoot === undefined) {
+    throw new Error("Not in a git repository, and no chant.config.ts or chant.config.json above the current directory");
+  }
   return gitRoot;
 }
 

package/src/op/gate.test.ts

@@ -613,6 +613,36 @@ describe("op/gate — a rejected ledger push is reported, not swallowed (#2310)"
   });
 });
 
+describe("op/gate — an applied record is written on the remote's ledger (#3985)", () => {
+  test("appendApplied fetches first, so a remote another writer moved still takes the push", async () => {
+    const { remote, author } = await clonePair();
+    const other = tmp("other");
+    git(["clone", "-q", remote, other], tmpdir());
+    git(["config", "user.email", "other@chant.dev"], other);
+    git(["config", "user.name", "Other"], other);
+
+    const port = gitGateLedgerPort({ cwd: author });
+    const pending = { op: "migrations", gate: "migrations-wave-1", timestamp: "2026-10-10T00:00:00.000Z", expiresAt: "2026-10-11T00:00:00.000Z" };
+    expect((await port.appendPending(pending)).pushed).toBe(true);
+
+    // Another writer moves the remote past what `author` holds.
+    git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], other);
+    expect((await gitGateLedgerPort({ cwd: other }).appendPending({ ...pending, gate: "migrations-wave-2" })).pushed).toBe(true);
+
+    const line = {
+      version: 1 as const, kind: "applied" as const, op: "migrations", gate: "migrations-wave-1", planDigest: "sha256:aa",
+      approvedAt: "2026-10-10T01:00:00.000Z", approvedBy: "alice", timestamp: "2026-10-10T02:00:00.000Z",
+    };
+    expect(await port.appendApplied!(line)).toEqual({ pushed: true });
+
+    // The remote holds the applied line and the other writer's pending fact.
+    const reader = ciCheckout(remote);
+    const readerPort = gitGateLedgerPort({ cwd: reader });
+    expect(await readerPort.readApplied!("migrations")).toEqual([line]);
+    expect((await readerPort.read("migrations")).pending.map((p) => p.gate)).toEqual(["migrations-wave-1", "migrations-wave-2"]);
+  });
+});
+
 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");

package/src/op/gate.ts

@@ -176,6 +176,9 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
     async appendApplied(record) {
       const { dir, file } = appliedGatePath(record.op);
       const line = JSON.stringify(record, sortedJsonReplacer);
+      // #3985: write on top of the remote's ledger, not a local copy another
+      // writer has since moved past, so the push that follows can land.
+      await requireLifecycleLedger(opts);
       let lastErr: unknown;
       // The same append-and-retry as a ledger line: another writer to the branch is the ordinary case.
       for (let attempt = 1; attempt <= 5; attempt++) {

package/src/op/op-waves-run.ts

@@ -68,6 +68,7 @@ import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger"
 import type { GatePointAsker } from "../point-decision";
 import type { WaitingPoint } from "./steward-points";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
+import { isLifecycleLocalNote } from "../lifecycle/local-note";
 import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
 import type { TrustPolicy } from "../workspace/trust/policy";
 import type { GateSigners } from "../workspace/trust/gate-seal";
@@ -1721,11 +1722,22 @@ async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed:
   }
 }
 
+/**
+ * Throws unless a spend's record reached the remote the next run reads
+ * (#3985). Without that, the next run reads the approval or override as
+ * unspent. A ledger with no remote is the whole ledger, so a line recorded
+ * there is spent.
+ */
+function requireSpendPushed(result: { pushed: boolean; pushWarning?: string }): void {
+  if (result.pushed || isLifecycleLocalNote(result.pushWarning)) return;
+  throw new Error(`the record did not reach the remote the next run reads: ${result.pushWarning ?? "the push did not land"}`);
+}
+
 /**
  * Record each override the wave is about to apply under (#3821), in
  * `_gates/policy-override/applied.jsonl`, which spends it: written before
- * anything applies, once. False when the lines could not be written: the
- * wave then fails and applies nothing.
+ * anything applies, once. False when the lines could not be written or did
+ * not reach the remote (#3985): the wave then fails and applies nothing.
  */
 async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promise<boolean> {
   const used = decision.members.filter((m) => m.override);
@@ -1738,7 +1750,7 @@ async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promi
     if (!port.appendApplied) throw new Error("this gate ledger cannot record an applied override");
     for (const m of used) {
       const record = og.appliedOverride({ subject: m.member, digest: m.override!.digest, at: m.override!.at, by: m.override!.by }, { timestamp: now });
-      await port.appendApplied(record as unknown as AppliedGateRecord);
+      requireSpendPushed(await port.appendApplied(record as unknown as AppliedGateRecord));
     }
   } catch (err) {
     failed(ctx, `wave ${k} (${wave.name}) could not record the overrides it applies under, so nothing applied: ${err instanceof Error ? err.message : String(err)}`);
@@ -2153,9 +2165,11 @@ async function applyStage(
  * Record that the wave applies under its approval (#3784), which spends it:
  * one line in `_gates/<name>/applied.jsonl`, before anything applies, as
  * terragucci's wave gate writes it. Only an approved wave under the spend
- * rule records, and only once. False when the line could not be written: the
+ * rule records, and only once. False when the line could not be written, or
+ * was written but did not reach the remote the next run reads (#3985): the
  * wave then fails and applies nothing, since an apply the record misses
- * would leave its approval standing.
+ * would leave its approval standing. A ledger with no remote is the whole
+ * ledger, so a line recorded there is spent.
  */
 async function spendApproval(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<boolean> {
   if (!decision.spend || decision.status !== "approved" || decision.spentAt || !decision.approvedAt) return true;
@@ -2177,6 +2191,7 @@ async function spendApproval(options: RunOpWaveOptions, ctx: WaveContext, decisi
   try {
     if (!port.appendApplied) throw new Error("this gate ledger cannot record an applied approval");
     const pushed = await port.appendApplied(record);
+    requireSpendPushed(pushed);
     if (!pushed.pushed && pushed.pushWarning) log(`wave ${k} (${wave.name}): ${pushed.pushWarning}`);
   } catch (err) {
     failed(ctx, `wave ${k} (${wave.name}) could not record that it applies under the approval by ${record.approvedBy}, so nothing applied: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -17,6 +17,8 @@ import {
 } from "./op-waves-run";
 import { memoryGateLedgerPort } from "./gate";
 import { waveSetDigest } from "../gated-waves";
+import type { AppliedGateRecord } from "../lifecycle/gate-applied";
+import { LIFECYCLE_LOCAL_NOTE } from "../lifecycle/local-note";
 
 const spec: OpWavesSpec = {
   name: "migrations",
@@ -475,6 +477,39 @@ describe("spent approvals (#3784)", () => {
     h.done();
   });
 
+  test("a spend whose record does not reach the remote applies nothing, and the approval stays unspent (#3985)", async () => {
+    const h = harness(spending);
+    const memory = memoryGateLedgerPort({ resolutions: [approval] });
+    const gates = {
+      ...memory,
+      async appendApplied(record: AppliedGateRecord) {
+        await memory.appendApplied!(record);
+        return { pushed: false, pushWarning: 'the push of chant/lifecycle to "origin" failed' };
+      },
+    };
+    const result = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 1, applied: [] });
+    expect(result.decision?.spentAt).toBeUndefined();
+    expect(h.applies()).toBe(0);
+    h.done();
+  });
+
+  test("with no remote the local ledger is the whole ledger, so a spend recorded there applies (#3985)", async () => {
+    const h = harness(spending);
+    const memory = memoryGateLedgerPort({ resolutions: [approval] });
+    const gates = {
+      ...memory,
+      async appendApplied(record: AppliedGateRecord) {
+        await memory.appendApplied!(record);
+        return { pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE };
+      },
+    };
+    const result = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 0, decision: { status: "approved", spentAt: "2026-10-11T00:00:00Z" } });
+    expect(memory.applied).toHaveLength(1);
+    h.done();
+  });
+
   test("a wave that cannot record the approval applies nothing", async () => {
     const h = harness(spending);
     const gates = { ...memoryGateLedgerPort({ resolutions: [approval] }), appendApplied: undefined };
@@ -878,6 +913,20 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     other.done();
   });
 
+  test("an override spend whose record does not reach the remote applies nothing (#3985)", async () => {
+    const { overrideDigest } = await import("../override-gate");
+    const od = overrideDigest("vpc", digest("1"), ["no-public-s3"]);
+    const h = harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2"), empty: true } }, { extra: { overriders: ["github:carol"] }, atBase: { ...tg, waves: [{ ...tg.waves[0]!, gate: "never" }] } });
+    const memory = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "policy-override", gate: "vpc", resolvedBy: "github:carol", timestamp: "2026-10-10T00:00:00Z", planDigest: od, note: "the bucket is the public docs site" }],
+    });
+    const gates = { ...memory, appendApplied: async () => ({ pushed: false, pushWarning: 'the push of chant/lifecycle to "origin" failed' }) };
+    const result = await run(h, gates);
+    expect(result).toMatchObject({ exitCode: 1, applied: [] });
+    expect(h.calls.some((c) => c.startsWith("tg apply"))).toBe(false);
+    h.done();
+  });
+
   test("a plans file's overridersSource names the list in the refusal and the decision record (#3848)", async () => {
     const mk = (extra: Record<string, unknown>) => harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2") } }, { extra });
     const logs: string[] = [];

package/src/op/operator.ts

@@ -399,8 +399,8 @@ const STEWARD_TURN_POLL_MS = 150;
  *
  * Contention never queues past `waitMs` (0 by default): consistent with a
  * round's own leases, which skip and report rather than wait (see this
- * module's doc), and with the fountain form, whose busy teammate is likewise
- * refused rather than retried. A caller that wants to ride out a race with a
+ * module's doc), and with the fountain form, whose busy steward conversation
+ * is likewise refused rather than retried. A caller that wants to ride out a race with a
  * turn about to end passes `waitMs`, and this polls every
  * {@link STEWARD_TURN_POLL_MS} until it acquires or the wait runs out.
  */

package/src/op/runtime.ts

@@ -62,6 +62,8 @@ export interface OpRunStepRecord {
   gate?: { op: string; gate: string };
   /** The run whose checkpoint supplied this step's output, for a step a resumed run skipped (#3947). */
   resumed?: { run: string; gate: string };
+  /** The image a `shellCmd` step ran in (#4015), pinned by digest, for a step that ran in a container. */
+  image?: string;
 }
 
 /** One phase's steps and the verdict they add up to. */

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

@@ -118,13 +118,15 @@ describe("a quiet step says it is still running (#3956)", () => {
 
   test("a step printing output is not interrupted by the still-running line", async () => {
     const out = recorder();
-    const chatty = `node -e "let n = 0; const t = setInterval(() => { console.log('tick ' + n); if (++n === 6) clearInterval(t); }, 40)"`;
+    // sh, not node: node's start can outlast the heartbeat on a loaded runner,
+    // and the gap before the first line is what the heartbeat measures.
+    const chatty = `sh -c 'for n in 0 1 2 3 4 5; do echo "tick $n"; sleep 0.04; done'`;
     await runOpLocally(
       { name: "chatty", overview: "", phases: [phase("Go", [shell(chatty, { id: "ticks" })])] },
       new Map([["shellCmd", shellFn]]),
       ACTIVITY_PROFILES,
       undefined,
-      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 100 },
+      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 400 },
     );
     expect(out.lines.filter((l) => l.text.includes("still running"))).toEqual([]);
     expect(out.lines.map((l) => l.text)).toContain("[Go] ticks | tick 5");

package/src/op/steward.ts

@@ -5,9 +5,11 @@
  * A steward runs a fixed list of Ops, each on its own `schedule` when it has
  * one, one Op at a time. Where it runs is its form:
  *
- * - `fountain`: the fountain lexicon's `Steward` composite, an `acp` Agent on
- *   a persistent sandbox bound to a Teammate, with a Fountain `Schedule` per
- *   scheduled Op. A turn is one `chant run <op>` on the teammate's thread.
+ * - `fountain`: the fountain lexicon's `Steward` composite, an `acp` Agent
+ *   whose runs `chant run <op> --on fountain` sends to one long-lived
+ *   conversation, resumed by channel_id. A turn is one `chant run <op>` in
+ *   that conversation. Managoat has no scheduler, so a scheduled Op's cron
+ *   fires from a clock outside it (a CI schedule, a CronJob).
  * - `local`: `chant operator --steward <name>` in the box itself, for a box
  *   with no Fountain behind it (a docker compose box, a Sprites box). The same
  *   Ops on the same crons, each run under its operator lease, and the steward
@@ -129,7 +131,7 @@ export interface StewardBeside {
 }
 
 export interface StewardDeclarationConfig {
-  /** The steward's name. On Fountain, the Agent's and the Teammate's. */
+  /** The steward's name. On Fountain, the Agent's, and the key of its conversation. */
   name: string;
   /** The Ops it runs. A scheduled one runs on its cron; any other runs when asked. */
   ops: StewardOpInput[];