@intentius/chant 0.124.22 → 0.124.24

package/src/lifecycle/git.ts

@@ -7,6 +7,7 @@
 import { getRuntime } from "../runtime-adapter";
 import { memberLedgerPrefix, resolveMemberLedger } from "./member-ledger";
 import { LIFECYCLE_LOCAL_NOTE } from "./local-note";
+import { ledgerRecordingOff, NO_RECORD_PUSH_NOTE, overlayTip, setOverlayTip } from "./no-record";
 import type { LedgerReadPort } from "./ledger-port";
 
 const STATE_BRANCH = "chant/lifecycle";
@@ -346,6 +347,23 @@ export async function writeLedgerFiles(
     // local race two concurrent writers used to hit silently (whoever called
     // update-ref last simply overwrote the other's tree, no error). A
     // conflict here throws RefCASConflictError instead of clobbering.
+    // #3955: a run that records nothing moves its in-memory tip instead of
+    // the branch, under the same compare-and-swap: nothing awaits between the
+    // read of the tip and the move, so two writes in this process cannot both
+    // parent on the same commit.
+    if (ledgerRecordingOff()) {
+      const key = await overlayKey(cwd);
+      const branch = overlayTip(key) === undefined ? await readRefSha(`refs/heads/${STATE_BRANCH}`, { cwd }) : null;
+      // Read again after the await: another write may have moved the tip meanwhile.
+      const moved = overlayTip(key);
+      const current = moved !== undefined ? moved : branch;
+      if (current === parentRef) {
+        setOverlayTip(key, commitSha, files.map((f) => f.path), commitMessage);
+        return commitSha;
+      }
+      lastErr = new RefCASConflictError(`refs/heads/${STATE_BRANCH}`, parentRef, `the run's unrecorded tip is ${current ?? "(none)"}`);
+      continue;
+    }
     try {
       await updateRefCAS(`refs/heads/${STATE_BRANCH}`, commitSha, parentRef, { cwd });
       return commitSha;
@@ -374,7 +392,7 @@ export async function readBlobFromPath(
   const rt = getRuntime();
   const dir = await ledgerDir(environment, opts);
   const result = await rt.spawn(
-    ["git", "show", `${STATE_BRANCH}:${dir}/${filename}`],
+    ["git", "show", `${await ledgerRevision(opts?.cwd)}:${dir}/${filename}`],
     { cwd: opts?.cwd },
   );
   if (result.exitCode !== 0) return null;
@@ -396,7 +414,7 @@ export async function readPathSha(
   const rt = getRuntime();
   const dir = await ledgerDir(environment, opts);
   const result = await rt.spawn(
-    ["git", "rev-parse", "--verify", `${STATE_BRANCH}:${dir}/${filename}`],
+    ["git", "rev-parse", "--verify", `${await ledgerRevision(opts?.cwd)}:${dir}/${filename}`],
     { cwd: opts?.cwd },
   );
   if (result.exitCode !== 0) return null;
@@ -566,7 +584,7 @@ export async function listLedgerTrees(opts?: LedgerLocation): Promise<string[]>
   // `--full-tree`: from a subdirectory, a bare `ls-tree` lists only that
   // subdirectory's part of the tree (#2550).
   const rootResult = await rt.spawn(
-    ["git", "ls-tree", "--full-tree", base === "" ? STATE_BRANCH : `${STATE_BRANCH}:${base}`],
+    ["git", "ls-tree", "--full-tree", base === "" ? tip : `${tip}:${base}`],
     { cwd: opts?.cwd },
   );
   if (rootResult.exitCode !== 0) return [];
@@ -592,7 +610,7 @@ export async function listFilesInDir(dir: string, opts?: LedgerLocation): Promis
   const rt = getRuntime();
   const path = await ledgerDir(dir, opts);
   const lsResult = await rt.spawn(
-    ["git", "ls-tree", "--full-tree", "--name-only", `${STATE_BRANCH}:${path}/`],
+    ["git", "ls-tree", "--full-tree", "--name-only", `${tip}:${path}/`],
     { cwd: opts?.cwd },
   );
   if (lsResult.exitCode !== 0) return [];
@@ -612,7 +630,7 @@ export async function readEnvironmentSnapshots(
   // List files in the environment directory
   const dir = await ledgerDir(environment, opts);
   const lsResult = await rt.spawn(
-    ["git", "ls-tree", "--full-tree", "--name-only", `${STATE_BRANCH}:${dir}/`],
+    ["git", "ls-tree", "--full-tree", "--name-only", `${await ledgerRevision(opts?.cwd)}:${dir}/`],
     { cwd: opts?.cwd },
   );
   if (lsResult.exitCode !== 0) return snapshots;
@@ -641,7 +659,7 @@ export async function listSnapshots(
   const base = await ledgerDir("", opts);
   const result = await rt.spawn(
     // `:(top)`: a pathspec is otherwise relative to the directory git runs in.
-    ["git", "log", "--format=%H %aI %s", STATE_BRANCH, ...(base === "" ? [] : ["--", `:(top)${base}`])],
+    ["git", "log", "--format=%H %aI %s", await ledgerRevision(opts?.cwd), ...(base === "" ? [] : ["--", `:(top)${base}`])],
     { cwd: opts?.cwd },
   );
   if (result.exitCode !== 0) return [];
@@ -702,6 +720,8 @@ export async function getRemoteLifecycleBranchSha(
 export type LifecyclePushStatus =
   | { status: "pushed"; remote: string; commit: string }
   | { status: "no-remote" }
+  /** Recording is off for this process (#3955, ./no-record.ts): nothing was written to the branch, so nothing was pushed. */
+  | { status: "not-recorded" }
   | { status: "stale"; remote: string; expected: string | null; stderr: string }
   | { status: "failed"; remote: string; stderr: string };
 
@@ -733,6 +753,7 @@ async function trackRemoteLifecycle(remote: string, sha: string, cwd?: string):
  * is the throwing form most callers use.
  */
 export async function pushLifecycleStatus(opts?: { cwd?: string }): Promise<LifecyclePushStatus> {
+  if (ledgerRecordingOff()) return { status: "not-recorded" };
   const rt = getRuntime();
   const cwd = opts?.cwd;
   const found = await ledgerRemote(cwd);
@@ -799,6 +820,8 @@ export function describeLifecyclePush(result: LifecyclePushStatus): string | nul
       return null;
     case "no-remote":
       return `this repository has no remote, so ${STATE_BRANCH} stays local`;
+    case "not-recorded":
+      return NO_RECORD_PUSH_NOTE;
     case "stale":
       return `"${result.remote}" holds ${STATE_BRANCH} commits this checkout has not fetched, so the push was refused; fetch ${STATE_BRANCH} and write again${said(result.stderr)}`;
     case "failed":
@@ -820,6 +843,8 @@ export async function pushLifecycleReport(opts?: { cwd?: string }): Promise<{ pu
         return { pushed: true };
       case "no-remote":
         return { pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE };
+      case "not-recorded":
+        return { pushed: false, pushWarning: NO_RECORD_PUSH_NOTE };
       case "stale":
         return { pushed: false, pushWarning: new StaleLifecycleBranchError(result.expected, result.stderr).message };
       case "failed":
@@ -1276,6 +1301,9 @@ export type PushRefStatus = "pushed" | "no-remote" | "rejected";
  * `pushed`.
  */
 export async function pushRefStatus(ref: string, opts?: { cwd?: string; expect?: string | null }): Promise<PushRefStatus> {
+  // #3955: a run that records nothing pushes nothing, a lease ref included.
+  // The lease still holds in this checkout, the way it does in one with no remote.
+  if (ledgerRecordingOff()) return "no-remote";
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
   if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return "no-remote";
@@ -1382,6 +1410,10 @@ interface TreeLine {
 }
 
 async function getStateBranchTip(cwd?: string): Promise<string | null> {
+  if (ledgerRecordingOff()) {
+    const tip = overlayTip(await overlayKey(cwd));
+    if (tip !== undefined) return tip;
+  }
   const rt = getRuntime();
   const result = await rt.spawn(
     ["git", "rev-parse", "--verify", `refs/heads/${STATE_BRANCH}`],
@@ -1391,6 +1423,29 @@ async function getStateBranchTip(cwd?: string): Promise<string | null> {
   return result.stdout.trim();
 }
 
+/**
+ * What a read names to see the ledger: `chant/lifecycle`, or, in a run that
+ * records nothing (#3955), the in-memory tip its own writes built, once it
+ * has written. Reads outside this module that name the branch themselves go
+ * through here so they see the run's writes too.
+ */
+export async function ledgerRevision(cwd?: string): Promise<string> {
+  if (!ledgerRecordingOff()) return STATE_BRANCH;
+  return overlayTip(await overlayKey(cwd)) ?? STATE_BRANCH;
+}
+
+/** The repository a run's in-memory ledger tip belongs to (#3955): its common git directory, so worktrees and members share one. */
+const overlayKeys = new Map<string, string>();
+async function overlayKey(cwd?: string): Promise<string> {
+  const from = cwd ?? process.cwd();
+  const cached = overlayKeys.get(from);
+  if (cached !== undefined) return cached;
+  const result = await getRuntime().spawn(["git", "rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: from, env: C_LOCALE_ENV });
+  const key = result.exitCode === 0 && result.stdout.trim() !== "" ? result.stdout.trim() : from;
+  overlayKeys.set(from, key);
+  return key;
+}
+
 /**
  * The entries of directory `dir` (branch-relative, `""` for the root) in
  * commit `tip`, or an empty map when it does not exist. Always pinned to the

package/src/lifecycle/no-record.test.ts

@@ -0,0 +1,175 @@
+/**
+ * #3955: a run that records nothing leaves `chant/lifecycle` exactly as it
+ * found it, locally and on the remote, while reading its own writes back.
+ */
+import { afterEach, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { listFilesInDir, pushLifecycleStatus, pushRefStatus, readBlobFromPath, writeBlobToPath } from "./git";
+import { appendReleaseRecord } from "./release-ledger";
+import { GateNotRecordableError, ledgerRecordingOff, noRecordEndNote, resetNoRecordLedger, unrecordedWrites } from "./no-record";
+import { runOpLocally } from "../op/local-executor";
+import { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort } from "../op/gate";
+import { lifecycleReceiptStore } from "../op/lifecycle-receipt-store";
+import type { OpConfig } from "../op/types";
+
+const dirs: string[] = [];
+
+afterEach(() => {
+  delete process.env.CHANT_NO_RECORD;
+  resetNoRecordLedger();
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+
+function tmp(name: string): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), `no-record-${name}-`)));
+  dirs.push(dir);
+  return dir;
+}
+
+/** A clone of a bare remote, with a `chant/lifecycle` holding one recorded release and pushed. */
+async function recordedCheckout(): Promise<{ dir: string; remote: string }> {
+  const remote = tmp("remote");
+  git(["init", "-q", "--bare", "-b", "main"], remote);
+  const dir = tmp("checkout");
+  git(["clone", "-q", remote, dir], tmpdir());
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+  git(["push", "-q", "origin", "main"], dir);
+  await writeBlobToPath("prod", "releases.jsonl", '{"seed":true}\n', "seed", { cwd: dir });
+  expect((await pushLifecycleStatus({ cwd: dir })).status).toBe("pushed");
+  return { dir, remote };
+}
+
+function refs(dir: string, remote: string): { local: string; remote: string } {
+  return {
+    local: git(["rev-parse", "refs/heads/chant/lifecycle"], dir),
+    remote: git(["rev-parse", "refs/heads/chant/lifecycle"], remote),
+  };
+}
+
+describe("CHANT_NO_RECORD", () => {
+  test("is off unless set to something other than empty, 0 or false", () => {
+    expect(ledgerRecordingOff({})).toBe(false);
+    expect(ledgerRecordingOff({ CHANT_NO_RECORD: "" })).toBe(false);
+    expect(ledgerRecordingOff({ CHANT_NO_RECORD: "0" })).toBe(false);
+    expect(ledgerRecordingOff({ CHANT_NO_RECORD: "false" })).toBe(false);
+    expect(ledgerRecordingOff({ CHANT_NO_RECORD: "1" })).toBe(true);
+    expect(ledgerRecordingOff({ CHANT_NO_RECORD: "yes" })).toBe(true);
+  });
+
+  test("writes stay in memory and read back, and the ledger ref and the remote are unchanged", async () => {
+    const { dir, remote } = await recordedCheckout();
+    const before = refs(dir, remote);
+
+    process.env.CHANT_NO_RECORD = "1";
+    await writeBlobToPath("prod", "receipts/x.receipt", "sha256:1\n", "Receipt x", { cwd: dir });
+    await appendReleaseRecord(
+      { component: "api", env: "prod", digest: "sha256:abc", actor: "ci", gitSha: "0".repeat(40), runId: "r1", timestamp: "2026-10-12T00:00:00.000Z" } as never,
+      { cwd: dir },
+    );
+
+    // The run sees its own writes on top of what was recorded before it.
+    expect(await readBlobFromPath("prod", "receipts/x.receipt", { cwd: dir })).toBe("sha256:1\n");
+    const releases = (await readBlobFromPath("prod", "releases.jsonl", { cwd: dir }))!;
+    expect(releases).toContain('{"seed":true}');
+    expect(releases).toContain("sha256:abc");
+    expect(await listFilesInDir("prod", { cwd: dir })).toEqual(expect.arrayContaining(["receipts", "releases.jsonl"]));
+
+    // Nothing reaches the branch or the remote, a lease ref included.
+    expect(await pushLifecycleStatus({ cwd: dir })).toEqual({ status: "not-recorded" });
+    git(["update-ref", "refs/chant/lease/x", git(["rev-parse", "HEAD"], dir)], dir);
+    expect(await pushRefStatus("refs/chant/lease/x", { cwd: dir })).toBe("no-remote");
+    expect(git(["ls-remote", remote, "refs/chant/lease/x"], dir)).toBe("");
+    expect(refs(dir, remote)).toEqual(before);
+    expect(unrecordedWrites().map((w) => w.path)).toEqual(["prod/receipts/x.receipt", "prod/releases.jsonl"]);
+    expect(noRecordEndNote("--no-record")).toContain("2 ledger writes were dropped (2 files)");
+
+    // Once the run is over, the ledger reads as it was.
+    delete process.env.CHANT_NO_RECORD;
+    resetNoRecordLedger();
+    expect(await readBlobFromPath("prod", "receipts/x.receipt", { cwd: dir })).toBeNull();
+    expect(await readBlobFromPath("prod", "releases.jsonl", { cwd: dir })).toBe('{"seed":true}\n');
+  });
+
+  test("an Op run records no run, no receipt and no push, and its steps still read their own receipts", async () => {
+    const { dir, remote } = await recordedCheckout();
+    const before = refs(dir, remote);
+    const receipts = lifecycleReceiptStore({ environment: "prod", cwd: dir });
+    const ref = { name: "migrate:001", effect: "migrate", flavor: "hash", inputs: {} } as const;
+    let readBack: string | undefined;
+    const op = {
+      name: "migrate",
+      overview: "migrate",
+      phases: [{ name: "Apply", steps: [{ kind: "activity", fn: "apply", args: {} }, { kind: "activity", fn: "check", args: {} }] }],
+    } as unknown as OpConfig;
+    const activities = new Map([
+      ["apply", async () => { await receipts.write(ref, "sha256:1"); return {}; }],
+      ["check", async () => { readBack = await receipts.read(ref); return {}; }],
+    ]);
+
+    process.env.CHANT_NO_RECORD = "1";
+    const result = await runOpLocally(op, activities as never, {}, undefined, { runId: "r1", ledger: { cwd: dir }, cwd: dir });
+
+    expect(result.status).toBe("ok");
+    expect(readBack).toBe("sha256:1");
+    expect(refs(dir, remote)).toEqual(before);
+    // The run record was written, and dropped with the receipt.
+    expect(unrecordedWrites().some((w) => w.path.startsWith("local/runs__migrate"))).toBe(true);
+  });
+
+  test("a gate step fails, writes no pending fact, and nothing after it runs but onFailure", async () => {
+    const { dir, remote } = await recordedCheckout();
+    const before = refs(dir, remote);
+    const ran: string[] = [];
+    const op = {
+      name: "release",
+      overview: "release",
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "plan", args: {} }] },
+        { name: "Apply", steps: [{ kind: "gate", gate: "approve-prod" }, { kind: "activity", fn: "apply", args: {} }] },
+      ],
+      onFailure: [{ name: "Undo", steps: [{ kind: "activity", fn: "undo", args: {} }] }],
+    } as unknown as OpConfig;
+    const activities = new Map([
+      ["plan", async () => { ran.push("plan"); return {}; }],
+      ["apply", async () => { ran.push("apply"); return {}; }],
+      ["undo", async () => { ran.push("undo"); return {}; }],
+    ]);
+
+    process.env.CHANT_NO_RECORD = "1";
+    let result;
+    try {
+      result = await runOpLocally(op, activities as never, {}, undefined, { runId: "r1", ledger: { cwd: dir }, cwd: dir, gates: gitGateLedgerPort({ cwd: dir }) });
+    } catch (err) {
+      result = (err as { result: Awaited<ReturnType<typeof runOpLocally>> }).result;
+    }
+
+    expect(result.status).toBe("fail");
+    // A failing step like any other: onFailure runs, and nothing after the gate does.
+    expect(ran).toEqual(["plan", "undo"]);
+    const gate = result.records.find((r) => r.fn.includes("approve-prod"));
+    expect(gate).toMatchObject({ status: "fail" });
+    expect(gate!.error).toContain('gate "approve-prod" of "release" cannot be passed under --no-record');
+    expect(unrecordedWrites().some((w) => w.path.startsWith("_gates/"))).toBe(false);
+    expect(refs(dir, remote)).toEqual(before);
+  });
+
+  test("a standing approval does not pass the gate", async () => {
+    const port = memoryGateLedgerPort({
+      resolutions: [{ op: "release", gate: "approve-prod", resolvedBy: "alice", timestamp: "2026-10-12T00:00:00.000Z" } as never],
+    });
+    expect((await evaluateGate(port, { op: "release", gate: "approve-prod" })).satisfied).toBe(true);
+    process.env.CHANT_NO_RECORD = "1";
+    await expect(evaluateGate(port, { op: "release", gate: "approve-prod" })).rejects.toBeInstanceOf(GateNotRecordableError);
+  });
+});

package/src/lifecycle/no-record.ts

@@ -0,0 +1,108 @@
+/**
+ * A run that records nothing on `chant/lifecycle` (#3955): `chant run
+ * --no-record`, or `CHANT_NO_RECORD=1` in the environment.
+ *
+ * Test and claim runs used to leave real records on the ledger and push them
+ * to origin, because every write path in `./git.ts` appends and pushes. In
+ * this mode the run still executes every step, and every ledger write still
+ * builds its commit, but the commit goes onto an in-memory tip instead of the
+ * branch ref:
+ *
+ * - `refs/heads/chant/lifecycle` is never updated, so the branch is exactly
+ *   what it was before the run.
+ * - Nothing is pushed: neither the ledger branch nor a lease ref.
+ * - Reads in the same process see the run's own writes, so a step that reads
+ *   back what an earlier step wrote (an effect receipt, a work lease) behaves
+ *   as it would in a recorded run. The tip is dropped when the process exits.
+ *
+ * A gate cannot be passed in this mode ({@link GateNotRecordableError}). An
+ * approval lives on the ledger, and passing a gate spends it: a run that
+ * passed a gate here would apply under an approval while leaving it unspent
+ * for the next run, and a pending fact it wrote could never be approved.
+ *
+ * The state is per process and keyed by the repository's git directory, so a
+ * workspace member and the root share one tip. A child `chant` process gets
+ * the mode through the environment and keeps its own tip.
+ *
+ * Kept free of git and the runtime adapter so the gate deciders and the run
+ * renderers can import it without loading `./git.ts`.
+ */
+
+/** The environment variable that turns recording off for every chant process that inherits it. */
+export const NO_RECORD_ENV = "CHANT_NO_RECORD";
+
+/** Whether this process records nothing on `chant/lifecycle`: `CHANT_NO_RECORD` set to anything but empty, `0` or `false`. */
+export function ledgerRecordingOff(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env[NO_RECORD_ENV]?.trim().toLowerCase();
+  return value !== undefined && value !== "" && value !== "0" && value !== "false";
+}
+
+/** The line a run prints before its first step when it records nothing. `source` is what turned recording off. */
+export function noRecordStartNote(source: string): string {
+  return `not recording (${source}): nothing this run writes goes on chant/lifecycle, and nothing is pushed. A gate step fails.`;
+}
+
+/** The push warning a ledger write reports in this mode, in place of a push. */
+export const NO_RECORD_PUSH_NOTE = "not recorded (--no-record): chant/lifecycle was not written or pushed";
+
+/** What the in-memory ledger holds for one repository: its tip, and the files written to it. */
+interface Overlay {
+  tip: string | null;
+  writes: { path: string; message: string }[];
+}
+
+const overlays = new Map<string, Overlay>();
+
+/** The tip this process's writes have built for the repository at `key`, or `undefined` before its first write. */
+export function overlayTip(key: string): string | null | undefined {
+  return overlays.get(key)?.tip;
+}
+
+/** Move the in-memory tip for `key` to `commit`, noting what the commit wrote. */
+export function setOverlayTip(key: string, commit: string, paths: readonly string[], message: string): void {
+  const overlay = overlays.get(key) ?? { tip: null, writes: [] };
+  overlay.tip = commit;
+  for (const path of paths) overlay.writes.push({ path, message });
+  overlays.set(key, overlay);
+}
+
+/** Every ledger file this process wrote and did not record, in write order, across repositories. */
+export function unrecordedWrites(): { path: string; message: string }[] {
+  return [...overlays.values()].flatMap((o) => o.writes);
+}
+
+/** The line a run prints after its last step: that nothing was recorded, and how many ledger writes it dropped. */
+export function noRecordEndNote(source: string): string {
+  const writes = unrecordedWrites();
+  const files = new Set(writes.map((w) => w.path)).size;
+  const dropped =
+    writes.length === 0
+      ? "the run made no ledger writes"
+      : `${writes.length} ledger write${writes.length === 1 ? " was" : "s were"} dropped (${files} file${files === 1 ? "" : "s"})`;
+  return `not recorded (${source}): nothing went on chant/lifecycle and nothing was pushed; ${dropped}.`;
+}
+
+/** Forget every in-memory tip. For tests, and for an in-process caller that runs twice. */
+export function resetNoRecordLedger(): void {
+  overlays.clear();
+}
+
+/** Thrown when a run that records nothing reaches a gate. The executor turns it into a failing gate step. */
+export class GateNotRecordableError extends Error {
+  constructor(
+    public readonly op: string,
+    public readonly gate: string,
+  ) {
+    super(
+      `gate "${gate}" of "${op}" cannot be passed under --no-record: a gate is decided and approved on ` +
+        "chant/lifecycle, which this run does not write. " +
+        "Run without --no-record (and without CHANT_NO_RECORD) to stop at the gate for approval.",
+    );
+    this.name = "GateNotRecordableError";
+  }
+}
+
+/** Throw {@link GateNotRecordableError} when recording is off. Called by every gate decider before it reads the ledger. */
+export function refuseGateWithoutRecording(op: string, gate: string): void {
+  if (ledgerRecordingOff()) throw new GateNotRecordableError(op, gate);
+}

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/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 });