@intentius/chant 0.70.0 → 0.71.0

package/src/lifecycle/affected.ts

@@ -15,8 +15,19 @@
  * be judged from a source diff — reported as **indeterminate**, not silently
  * included or excluded.
  *
- * This returns the set; it does not act. Fanning `lifecycle plan` / `ApplyOp`
- * over it is an Op the user composes.
+ * ## What "stack" means here depends on the project
+ *
+ * A project that declares `stacks` in `chant.config.ts` gets each declared
+ * stack's own source built, and the answer names stacks. A single-root project
+ * has no such partition to build, so its answer names lexicon partitions, which
+ * is the only granularity it has. The difference matters downstream: a
+ * component's deploy step names a stack, so only the first kind of answer can
+ * be joined to components (#2420).
+ *
+ * This returns the set; it does not act. `chant components fan-out`
+ * (../cli/handlers/fan-out.ts) is the command that acts on it, and fanning
+ * `lifecycle plan` / `ApplyOp` over it by hand is still an Op the user
+ * composes.
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -140,10 +151,92 @@ async function withWorktree<T>(repoRoot: string, ref: string, fn: (dir: string)
   }
 }
 
+/** One independently-deployed stack, as `ChantConfig.stacks` declares it. */
+export interface StackSource {
+  /** The deployed stack name — what a component's deploy step names. */
+  name: string;
+  /** Source directory to build for this stack, relative to the project root. */
+  src: string;
+}
+
+/**
+ * Build each declared stack's own source directory and key the result by
+ * **stack name**.
+ *
+ * Without this, one build of the project root produces a map keyed by lexicon
+ * partition, so an aws-only estate of fifteen stacks answers "aws changed" no
+ * matter which one moved. That answer cannot be joined to anything: a
+ * component's deploy step names a stack, not a lexicon, so
+ * `componentsForUnits` (../components/fan-out.ts) would claim none of it and
+ * a fan-out derived from it would be empty. The two halves have to speak the
+ * same names for either to be worth having.
+ *
+ * A stack that serializes through more than one lexicon folds its partitions
+ * into one artifact, because the unit being deployed is the stack.
+ */
+async function stackArtifacts(
+  root: string,
+  serializers: Serializer[],
+  stacks: readonly StackSource[],
+  /**
+   * Whether a missing `src` is an error. True for the head side, where every
+   * declared stack must exist; false for the base side, where a stack added
+   * since then legitimately has no source yet and reads as an empty artifact,
+   * which is what makes it `changed`.
+   */
+  requireSrc: boolean,
+): Promise<{ artifacts: Map<string, string>; externalInput: string[] }> {
+  const artifacts = new Map<string, string>();
+  const externalInput: string[] = [];
+  for (const stack of stacks) {
+    const src = resolve(root, stack.src);
+    // `build()` on a directory that is not there returns empty outputs rather
+    // than throwing, so a typo in `src` would make both sides build nothing,
+    // match, and report the stack as unchanged forever. A silent answer of
+    // exactly that shape is what this whole path exists to prevent.
+    if (requireSrc && !existsSync(src)) {
+      throw new Error(
+        `stack "${stack.name}" declares src "${stack.src}", which does not exist under ${root}. ` +
+          `Fix chant.config.ts's stacks[] entry: a source directory that is not there builds to nothing, ` +
+          `and a stack that builds to nothing can never be reported as changed.`,
+      );
+    }
+    const built = await build(src, serializers);
+    artifacts.set(
+      stack.name,
+      [...built.outputs.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([lexicon, output]) => `${lexicon}\n${getPrimaryOutput(output as string)}`)
+        .join("\n"),
+    );
+    if (externalInputStacks(built.entities).length > 0) externalInput.push(stack.name);
+  }
+  return { artifacts, externalInput: externalInput.sort() };
+}
+
 export interface AffectedStacksOptions {
   /** Project source directory to scope (the head/working-tree build root). */
   projectPath: string;
   serializers: Serializer[];
+  /**
+   * The project's independently-deployed stacks (`ChantConfig.stacks`). With
+   * them, each stack's own source is built and the answer names stacks; without
+   * them, one build of `projectPath` answers by lexicon partition, which is the
+   * only granularity a single-root project has.
+   *
+   * `dependents` is always empty in this mode, and that is not an omission: the
+   * build holds cross-*lexicon* edges, and the relation between two deployed
+   * stacks is stated by a component's `dependsOn` and `stackOutput`, which
+   * `chant components fan-out` walks for itself. Inventing stack edges from
+   * lexicon ones would be a guess dressed as a graph.
+   *
+   * Each `src` resolves against `projectPath`, so in this mode `projectPath`
+   * has to be the project root that `ChantConfig.stacks` is written relative
+   * to. A `sourceDir` that narrows the build root does not apply here: the
+   * stacks already say which source belongs to which of them, which is the
+   * narrowing, and applying both would look for `<sourceDir>/<stack.src>`.
+   */
+  stacks?: readonly StackSource[];
   /** Base git ref to diff against (built in a throwaway worktree). */
   baseRef?: string;
   /** Head git ref. Defaults to the working tree (built in place — no worktree). */
@@ -175,28 +268,39 @@ export async function affectedStacks(opts: AffectedStacksOptions): Promise<Affec
   // Head: the in-place build of the working tree, unless an explicit headRef is
   // given (then a throwaway worktree — removed before the base worktree, so at
   // most one exists at a time).
+  const perStack = opts.stacks && opts.stacks.length > 0 ? opts.stacks : undefined;
+  // No cross-stack graph in per-stack mode, by construction: see `stacks` above.
+  const EMPTY_GRAPH: StackGraph = { nodes: [], edges: [], order: [], waves: [], cycles: [] };
+  /** One build root in, its artifact map and external-input set out, at whichever granularity applies. */
+  const readArtifacts = async (
+    root: string,
+    isHead: boolean,
+  ): Promise<{ artifacts: Map<string, string>; externalInput: string[]; graph: StackGraph }> => {
+    if (perStack) return { ...(await stackArtifacts(root, opts.serializers, perStack, isHead)), graph: EMPTY_GRAPH };
+    const built = await build(root, opts.serializers);
+    return {
+      artifacts: artifactMap(built.outputs),
+      externalInput: externalInputStacks(built.entities),
+      graph: built.manifest.stackGraph,
+    };
+  };
+
   const head = opts.headRef
-    ? await withWorktree(repoRoot, opts.headRef, (dir) => build(join(dir, relProject), opts.serializers))
-    : await build(projectPath, opts.serializers);
-  const headMap = artifactMap(head.outputs);
-  const externalInput = externalInputStacks(head.entities);
+    ? await withWorktree(repoRoot, opts.headRef, (dir) => readArtifacts(join(dir, relProject), true))
+    : await readArtifacts(projectPath, true);
 
   // Base: caller-supplied dir (cheapest), else a single worktree at baseRef.
   let baseMap: Map<string, string>;
   if (opts.baseDir) {
-    const baseBuild = await build(resolve(opts.baseDir), opts.serializers);
-    baseMap = artifactMap(baseBuild.outputs);
+    baseMap = (await readArtifacts(resolve(opts.baseDir), false)).artifacts;
   } else if (opts.baseRef) {
-    baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => {
-      const baseBuild = await build(join(dir, relProject), opts.serializers);
-      return artifactMap(baseBuild.outputs);
-    });
+    baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => (await readArtifacts(join(dir, relProject), false)).artifacts);
   } else {
     throw new Error("affectedStacks requires either baseDir or baseRef");
   }
 
-  return computeAffected(baseMap, headMap, head.manifest.stackGraph, {
+  return computeAffected(baseMap, head.artifacts, head.graph, {
     includeDependents: opts.includeDependents,
-    externalInput,
+    externalInput: head.externalInput,
   });
 }

package/src/op/activities/activity-contracts.ts

@@ -37,9 +37,25 @@ export const lifecycleDiffContract = activityContract(
   z.object({ output: z.string(), exitCode: z.number(), drifted: z.boolean() }),
 );
 
+/**
+ * The escape hatch (#2413). `returns` is what `shellCmd` captured and used to
+ * throw away: the trimmed stdout, the trimmed stderr, and the exit code —
+ * which only ever differs from `0` when the step named that code in `okExit`,
+ * since anything else still rejects.
+ *
+ * Running a command chant does not model in order to discard what it produced
+ * is the odd case, not the normal one, so the value a later step reads through
+ * `sh.out.stdout` is the point of the step rather than an extra.
+ */
 export const shellCmdContract = activityContract(
   "shellCmd",
-  z.strictObject({ cmd: z.string(), env: z.record(z.string(), z.string()).optional(), cwd: z.string().optional() }),
+  z.strictObject({
+    cmd: z.string(),
+    env: z.record(z.string(), z.string()).optional(),
+    cwd: z.string().optional(),
+    okExit: z.array(z.number()).optional(),
+  }),
+  z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number() }),
 );
 
 export const httpCheckContract = activityContract(

package/src/op/activities/index.ts

@@ -14,7 +14,7 @@ export type { WaitForStackArgs } from "./wait";
 // provides gitlabPipeline. The gitlabPipeline step builder stays in core.
 
 export { shellCmd } from "./shell";
-export type { ShellCmdArgs } from "./shell";
+export type { ShellCmdArgs, ShellCmdResult } from "./shell";
 
 export { httpCheck, statusOk } from "./http-check";
 export type { HttpCheckArgs, HttpFetch } from "./http-check";

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

@@ -0,0 +1,156 @@
+/**
+ * The escape hatch's safety properties (#2411, #2412) and what it publishes
+ * (#2413, #2414).
+ *
+ * `shellCmd` runs a command chant did not write and cannot model, which is
+ * what makes these different from every other activity: nothing here can know
+ * whether repeating the command is safe, how much it will say, or what a
+ * non-zero exit means.
+ */
+
+import { describe, test, expect } from "vitest";
+import { z } from "zod";
+import { shellCmd } from "./shell";
+import { shellCmdContract } from "./activity-contracts";
+import { shell } from "../builders";
+import { phase } from "../builders";
+import { collectStepOutputRefs, stepOutput, validateStepOutputRefs } from "../step-output-ref";
+import { ACTIVITY_PROFILES } from "../activity-profiles";
+import { runOpLocally } from "../local-executor";
+import { memoryGateLedgerPort } from "../gate";
+import type { ActivityFn } from "../activity-registry";
+import type { ShellCmdArgs, ShellCmdResult } from "./shell";
+
+describe("the at-most-once default (#2411)", () => {
+  test("shell() asks for a profile that does not retry", () => {
+    const step = shell("echo hi");
+    expect(step.profile).toBe("atMostOnce");
+    expect(ACTIVITY_PROFILES.atMostOnce.retry.maximumAttempts).toBe(1);
+  });
+
+  test("an author who knows the command is safe to repeat can still say so", () => {
+    // The direction that matters: retrying is opt-in, because it is the claim
+    // that needs evidence about the command.
+    expect(shell("echo hi", { profile: "fastIdempotent" }).profile).toBe("fastIdempotent");
+    expect(ACTIVITY_PROFILES.fastIdempotent.retry.maximumAttempts).toBeGreaterThan(1);
+  });
+
+  test("the profile allows a long command, since a shell step is often a build", () => {
+    expect(ACTIVITY_PROFILES.atMostOnce.timeout).toBe("20m");
+  });
+});
+
+describe("the stdout ceiling (#2412)", () => {
+  test("a command producing well over 1 MiB completes instead of rejecting", async () => {
+    // Node's default maxBuffer is 1 MiB and this activity was the only exec
+    // site leaving it unset. 4 MiB is comfortably past the old ceiling and
+    // far short of the new one.
+    const bytes = 4 * 1024 * 1024;
+    const out = await shellCmd({ cmd: `node -e "process.stdout.write('x'.repeat(${bytes}))"` });
+    expect(out.stdout.length).toBe(bytes);
+  });
+
+  test("stdout is returned trimmed, as before", async () => {
+    expect((await shellCmd({ cmd: "echo hello" })).stdout).toBe("hello");
+  });
+
+  test("cwd and env reach the command", async () => {
+    const out = await shellCmd({ cmd: "pwd && echo $CHANT_SHELL_TEST", cwd: "/tmp", env: { CHANT_SHELL_TEST: "set" } });
+    expect(out.stdout).toContain("set");
+  });
+});
+
+describe("what a shell step publishes (#2413)", () => {
+  test("the contract declares a return schema, so a later step may reference it", () => {
+    const returns = shellCmdContract.returns as z.ZodTypeAny | undefined;
+    expect(returns).toBeDefined();
+    expect(returns!.parse({ stdout: "a", stderr: "b", exitCode: 0 })).toEqual({ stdout: "a", stderr: "b", exitCode: 0 });
+  });
+
+  test("a step reading a shell step's stdout passes OPS013", () => {
+    const host = shell("echo db.internal", { id: "host" });
+    const smoke = shell("./smoke.sh", { env: { HOST: host.out.stdout } });
+    const issues = validateStepOutputRefs(
+      { name: "deploy", phases: [phase("Go", [host, smoke])] },
+      new Map([["shellCmd", shellCmdContract]]),
+    );
+    expect(issues).toEqual([]);
+  });
+
+  test("a path the shell result does not declare is still flagged", () => {
+    const host = shell("echo db.internal", { id: "host" });
+    const smoke = shell("./smoke.sh", { env: { HOST: stepOutput(host, "stdoutt") } });
+    const issues = validateStepOutputRefs(
+      { name: "deploy", phases: [phase("Go", [host, smoke])] },
+      new Map([["shellCmd", shellCmdContract]]),
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('output path "stdoutt"');
+  });
+
+  test("stderr survives the call instead of being printed and dropped", async () => {
+    const out = await shellCmd({ cmd: `node -e "process.stderr.write('warned')"` });
+    expect(out).toMatchObject({ stdout: "", stderr: "warned", exitCode: 0 });
+  });
+
+  test("a non-zero exit still rejects, and the code is in the message", async () => {
+    await expect(shellCmd({ cmd: "exit 3" })).rejects.toThrow(/exited 3 \(expected 0\)/);
+  });
+
+  test("a code the author named resolves, carrying output and the code", async () => {
+    // `diff` exits 1 to report a difference. Nothing about that is a failure,
+    // and before this the whole step was one.
+    const out = await shellCmd({ cmd: `node -e "process.stdout.write('changed'); process.exit(1)"`, okExit: [0, 1] });
+    expect(out).toEqual({ stdout: "changed", stderr: "", exitCode: 1 });
+  });
+
+  test("a code the author did not name still rejects", async () => {
+    await expect(shellCmd({ cmd: "exit 2", okExit: [0, 1] })).rejects.toThrow(/exited 2 \(expected 0, 1\)/);
+  });
+
+  test("a signal kill rejects even when its code is named", async () => {
+    // A timeout or Ctrl-C is not an exit status the author said anything
+    // about, so `okExit` must not swallow it.
+    const ac = new AbortController();
+    const running = shellCmd({ cmd: "sleep 5", okExit: [0, 1, 143] }, ac.signal);
+    ac.abort();
+    await expect(running).rejects.toThrow();
+  });
+});
+
+describe("a reference reaching the command (#2414)", () => {
+  test("a reference in env typechecks, which is the whole gap", () => {
+    const host = shell("echo db.internal", { id: "host" });
+    // No `as` cast: before #2414 `WithStepRefs` was shallow, so a reference
+    // inside `env`'s Record<string, string> was a type error even though the
+    // executor resolved it and the lint rule accepted it.
+    const smoke = shell("./smoke.sh", { env: { HOST: host.out.stdout, MODE: "ci" } });
+    expect(collectStepOutputRefs(smoke.args)).toEqual([
+      expect.objectContaining({ step: "host", path: "stdout" }),
+    ]);
+    expect((smoke.args as { env: Record<string, string> }).env.MODE).toBe("ci");
+  });
+
+  test("the executor carries it into the next command's environment, end to end", async () => {
+    const host = shell("echo db.internal", { id: "host" });
+    const smoke = shell("echo reached $HOST", { env: { HOST: host.out.stdout }, id: "smoke" });
+
+    const seen: ShellCmdResult[] = [];
+    const spy: ActivityFn = async (args, signal) => {
+      const out = await shellCmd(args as unknown as ShellCmdArgs, signal);
+      seen.push(out);
+      return out;
+    };
+
+    const result = await runOpLocally(
+      { name: "deploy", overview: "", phases: [phase("Go", [host, smoke])] },
+      new Map([["shellCmd", spy]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort() },
+    );
+
+    expect(result.status).toBe("ok");
+    expect(seen.map((s) => s.stdout)).toEqual(["db.internal", "reached db.internal"]);
+  });
+});

package/src/op/activities/shell.ts

@@ -9,18 +9,93 @@ export interface ShellCmdArgs {
   env?: Record<string, string>;
   /** Working directory. Default: process.cwd(). */
   cwd?: string;
+  /**
+   * Exit codes that count as success. Default `[0]`.
+   *
+   * Without this, `exitCode` in the result could only ever be `0` (#2413):
+   * every other code rejects, so nothing downstream can read it. Naming the
+   * codes a command uses to report a result — `diff`'s 1, `grep`'s 1,
+   * a migration tool's "nothing to do" — turns them into a value a later
+   * step can branch on instead of a failed Op.
+   */
+  okExit?: number[];
+}
+
+/**
+ * How much stdout a command may produce, matching every other exec site in
+ * the tree (`../activities/apply.ts`, the terraform lexicon's activities,
+ * `../../components/verbs/process-runner.ts`).
+ *
+ * Node's default is 1 MiB, and this was the only exec call leaving it unset
+ * (#2412) — on the one activity whose output chant cannot predict, because
+ * the command is the author's. A verbose test run, a playbook or a wide plan
+ * passes 1 MiB without trying, and the overflow is a rejection rather than a
+ * truncation, so the step fails for a reason that has nothing to do with the
+ * command.
+ */
+const MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+
+/**
+ * What a shell step publishes to the steps after it (#2413).
+ *
+ * `stdout` and `stderr` are trimmed, because the value an author wants from
+ * `echo $(terraform output -raw host)` is the host, not the host plus a
+ * newline, and a trailing newline in an `env` value or a gate argument is a
+ * bug that is very hard to see.
+ *
+ * `stderr` is here as well as on the console. It was captured and dropped
+ * before, so a command that reports on stderr — every tool that prints
+ * progress there — had no route to a later step at all.
+ */
+export interface ShellCmdResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Node hangs the exit status off the error as `code`, and a signal kill as `signal`. */
+interface ExecFailure extends Error {
+  code?: number | string;
+  signal?: string;
+  killed?: boolean;
+  stdout?: string;
+  stderr?: string;
 }
 
 /**
  * Run an arbitrary shell command.
- * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ *
+ * Runs under the `atMostOnce` profile by default (#2411): one attempt, since
+ * nothing here can know whether repeating the author's command is safe.
  */
-export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<string> {
-  const { stdout, stderr } = await execAsync(args.cmd, {
-    cwd: args.cwd,
-    env: { ...process.env, ...args.env },
-    signal,
-  });
-  if (stderr) console.error(stderr);
-  return stdout.trim();
+export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<ShellCmdResult> {
+  const okExit = args.okExit ?? [0];
+  try {
+    const { stdout, stderr } = await execAsync(args.cmd, {
+      cwd: args.cwd,
+      env: { ...process.env, ...args.env },
+      maxBuffer: MAX_STDOUT_BYTES,
+      signal,
+    });
+    if (stderr) console.error(stderr);
+    return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 };
+  } catch (err) {
+    const failure = err 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
+    // even if `okExit` happens to contain the code.
+    const died = failure.killed === true || typeof failure.signal === "string" || signal?.aborted === true;
+    if (exitCode !== undefined && !died && okExit.includes(exitCode)) {
+      const stderrText = (failure.stderr ?? "").trim();
+      if (stderrText) console.error(stderrText);
+      return { stdout: (failure.stdout ?? "").trim(), stderr: stderrText, exitCode };
+    }
+    if (exitCode !== undefined && !died) {
+      // `local-executor` records `error` as message text, so the code has to
+      // be in the message or it is gone (#2413).
+      failure.message = `command exited ${exitCode} (expected ${okExit.join(", ")}): ${failure.message}`;
+    }
+    throw failure;
+  }
 }

package/src/op/activity-profiles.test.ts

@@ -10,12 +10,26 @@ import { activity } from "./builders";
  * in an in-process step, so it did not come along.
  */
 describe("ACTIVITY_PROFILES", () => {
-  test("carries the six named profiles", () => {
+  test("carries the seven named profiles", () => {
     expect(Object.keys(ACTIVITY_PROFILES).sort()).toEqual(
-      ["argoSync", "fastIdempotent", "humanGate", "k8sWait", "longInfra", "policyCheck"],
+      ["argoSync", "atMostOnce", "fastIdempotent", "humanGate", "k8sWait", "longInfra", "policyCheck"],
     );
   });
 
+  test("atMostOnce runs once, and is the only non-gate profile that does (#2411)", () => {
+    expect(ACTIVITY_PROFILES.atMostOnce.retry.maximumAttempts).toBe(1);
+    // The two other single-attempt profiles carry semantics a shell step must
+    // not borrow: a gate's single attempt is about not re-asking a human, and
+    // a policy check's is about not re-running an evaluation. A run ledger
+    // that called a shell step either of those would be saying something
+    // false about what ran.
+    const singleAttempt = Object.entries(ACTIVITY_PROFILES)
+      .filter(([, p]) => p.retry.maximumAttempts === 1)
+      .map(([name]) => name)
+      .sort();
+    expect(singleAttempt).toEqual(["atMostOnce", "humanGate", "policyCheck"]);
+  });
+
   test("every profile has a timeout, and none has a worker-era field", () => {
     for (const [name, profile] of Object.entries(ACTIVITY_PROFILES)) {
       expect(typeof profile.timeout, `${name}.timeout`).toBe("string");

package/src/op/activity-profiles.ts

@@ -72,6 +72,24 @@ export const ACTIVITY_PROFILES = {
     },
   },
 
+  /**
+   * A command chant did not write and cannot know is safe to repeat (#2411).
+   *
+   * `shellCmd` is the escape hatch: its whole purpose is to run something
+   * outside the model, so nothing here can judge whether a second attempt is
+   * harmless or a second deployment. Every other activity carrying a retrying
+   * profile is one chant authored and knows the shape of.
+   *
+   * Twenty minutes, because a shell step is as likely to be a long build as a
+   * quick script, and one attempt, because retrying is the claim that needs
+   * evidence. An author who knows their command is idempotent names
+   * `fastIdempotent` or `longInfra` and gets retries back.
+   */
+  atMostOnce: {
+    timeout: "20m",
+    retry: { maximumAttempts: 1 },
+  },
+
   /**
    * Human-gate steps: waiting for an operator action (DNS delegation, approval).
    * Very long timeout, single attempt — no retry on human-gate timeouts.

package/src/op/builders.ts

@@ -306,16 +306,34 @@ export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedAct
   activity("lifecycleSnapshot", { env } satisfies LifecycleSnapshotArgs, opts?.id ? { id: opts.id } : undefined);
 
 /**
- * Run an arbitrary shell command. Tag long-running commands with a `profile`
- * (e.g. `longInfra` for a multi-GB image push) so they get the right
- * start-to-close timeout on whichever runtime hosts the run.
+ * Run an arbitrary shell command.
+ *
+ * Defaults to the `atMostOnce` profile: twenty minutes, one attempt (#2411).
+ * This is the one activity chant cannot know is idempotent, because its
+ * purpose is to run something chant does not model, so a failed command is
+ * not repeated unless the author says it may be. Name `fastIdempotent` or
+ * `longInfra` to get retries back for a command that is safe to repeat.
+ *
+ * Give the step an `id` and later steps can read what it produced —
+ * `sh.out.stdout`, `sh.out.stderr`, `sh.out.exitCode` (#2413) — and a value
+ * from an earlier step reaches the command through `env` (#2414):
+ *
+ * ```ts
+ * const host = shell("terraform output -raw host", { id: "host" });
+ * shell("./smoke.sh", { env: { HOST: host.out.stdout } });
+ * ```
+ *
+ * `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
+ * with the shell's own rules intact.
  */
 export const shell = (
   cmd: string,
   opts?: WithStepRefs<Omit<ShellCmdArgs, "cmd">> & StepOpts,
 ): NamedActivityStep => {
   const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
-  return activity("shellCmd", { cmd, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
+  return activity("shellCmd", { cmd, ...args }, { profile: profile ?? "atMostOnce", ...(id ? { id } : {}) });
 };
 
 /**

package/src/op/gate-name.ts

@@ -18,6 +18,17 @@
 
 import type { OpConfig, PhaseDefinition, StepDefinition } from "./types";
 
+/**
+ * The op name a `chant components fan-out` gate is recorded under (#2420).
+ *
+ * A fan-out is a command rather than an authored `*.op.ts`, so `chant approve`
+ * has nothing to discover for this name and must not report that as a problem.
+ * It lives here, next to the other thing that decides what a gate is called,
+ * so both the command that records the pending fact and the command that
+ * answers it read one constant instead of agreeing by hand.
+ */
+export const FAN_OUT_GATE_OP = "fan-out";
+
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */
 export interface GateNamed {
   gate?: string;

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

@@ -123,7 +123,10 @@ describe("op.json IR", () => {
 
     expect(ir.name).toBe("full-deploy");
     const [build, approve, deploy, seed, verify] = ir.phases;
-    expect(build.steps[0]).toMatchObject({ kind: "activity", fn: "shellCmd", profile: "fastIdempotent" });
+    // A shell step carries `atMostOnce` since #2411: the IR records the
+    // profile the builder named, and the builder names one precisely so a
+    // command chant cannot judge does not inherit a retrying default.
+    expect(build.steps[0]).toMatchObject({ kind: "activity", fn: "shellCmd", profile: "atMostOnce" });
     expect(approve.steps[0]).toMatchObject({
       kind: "gate",
       gate: "approve-deploy",

package/src/op/op.test.ts

@@ -266,10 +266,15 @@ describe("profile routing (opts.profile sets the step profile, never leaks into
     expect("profile" in (a.args ?? {})).toBe(false);
   });
 
-  it("shell() without profile leaves the step unprofiled (defaults apply downstream)", () => {
+  it("shell() without profile names atMostOnce, so the retrying default cannot apply (#2411)", () => {
+    // It used to leave the step unprofiled and let the executor's default
+    // apply, which meant the one activity chant cannot know is idempotent
+    // inherited three attempts by omission. The builder names its profile now,
+    // the way terraformPlan and terraformApply already did.
     const a = shell("echo hi", { env: { A: "1" } });
-    expect("profile" in a).toBe(false);
+    expect(a.profile).toBe("atMostOnce");
     expect(a.args?.env).toEqual({ A: "1" });
+    expect("profile" in (a.args ?? {})).toBe(false);
   });
 
   it("build() accepts a profile override and does not leak it into args", () => {

package/src/op/step-output-ref.ts

@@ -112,15 +112,36 @@ export interface StepOutputRef {
 }
 
 /**
- * `T` with every own property additionally accepting a {@link StepOutputRef}
- * in its place (chant #1288 Stage 2) — the authoring-time counterpart of
- * `args` accepting a reference anywhere in the structure (#1290): a typed
- * step-builder wrapper whose opts type is `WithStepRefs<SomeActivityArgs>`
- * lets an author pass `diff.out.driftedStacks` for any field without an
- * `as` cast, while runtime validation of the reference itself is still
- * `validateStepOutputRefs`' job, not this type's.
+ * `V`, or a {@link StepOutputRef} in its place, at every position inside it.
+ *
+ * Recurses through arrays and plain objects — including an index signature,
+ * which is the case that motivated it (#2414): `shell()`'s `env` is a
+ * `Record<string, string>`, and a reference in one of its values resolves at
+ * run time (`local-executor`'s `resolveStepOutputRefs` deep-walks `args`) and
+ * passes OPS012 (`activity-contract.ts` skips a reference at the issue path),
+ * so the compiler was the only one of the three layers rejecting it.
+ *
+ * Functions are left alone rather than mapped — nothing in an activity's args
+ * is callable, and mapping one would silently strip its call signature.
+ */
+type StepRefAt<V> =
+  | StepOutputRef
+  | (V extends Function ? V
+    : V extends readonly (infer E)[] ? (V extends unknown[] ? StepRefAt<E>[] : readonly StepRefAt<E>[])
+    : V extends object ? { [K in keyof V]: StepRefAt<V[K]> }
+    : V);
+
+/**
+ * `T` with every property — at any depth — additionally accepting a {@link
+ * StepOutputRef} in its place (chant #1288 Stage 2, deepened in #2414) — the
+ * authoring-time counterpart of `args` accepting a reference anywhere in the
+ * structure (#1290): a typed step-builder wrapper whose opts type is
+ * `WithStepRefs<SomeActivityArgs>` lets an author pass
+ * `diff.out.driftedStacks` for any field without an `as` cast, while runtime
+ * validation of the reference itself is still `validateStepOutputRefs`' job,
+ * not this type's.
  */
-export type WithStepRefs<T> = { [K in keyof T]: T[K] | StepOutputRef };
+export type WithStepRefs<T> = { [K in keyof T]: StepRefAt<T[K]> };
 
 /** Structural guard for a value produced by {@link stepOutput} (or `activity()`'s `.out`). */
 export function isStepOutputRef(value: unknown): value is StepOutputRef {