@intentius/chant 0.70.1 → 0.71.0

package/src/lifecycle/affected.test.ts

@@ -138,6 +138,124 @@ describe("affectedStacks — baseDir (caller-supplied)", () => {
   });
 });
 
+// A second lexicon, so a stack that serializes through two of them can be shown
+// folding into one artifact.
+const fakeSerializer2: Serializer = {
+  name: "fake2",
+  rulePrefix: "FAKE2",
+  serialize: (entities) =>
+    JSON.stringify([...entities.keys()].sort().map((k) => ({ k, t: entities.get(k)!.entityType }))),
+};
+
+function otherWidget(type: string): string {
+  return `export const bar = { lexicon: "fake2", entityType: "${type}", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+function deployTimeParam(): string {
+  return `export const p = { lexicon: "fake", entityType: "Param", parameterType: "String", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+describe("affectedStacks — per-stack mode (#2420)", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-affected-stacks-"));
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  // A project root holding one source directory per stack, as ChantConfig.stacks
+  // describes it: { api: <infra.ts contents>, worker: ... }.
+  const project = (name: string, sources: Record<string, string>): string => {
+    const dir = join(root, name);
+    for (const [stack, content] of Object.entries(sources)) {
+      mkdirSync(join(dir, stack), { recursive: true });
+      writeFileSync(join(dir, stack, "infra.ts"), content);
+    }
+    return dir;
+  };
+
+  const stacks = [
+    { name: "api-stack", src: "api" },
+    { name: "worker-stack", src: "worker" },
+  ];
+
+  test("a stacks[] entry whose src is not there is refused by name at head", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget") });
+    await expect(
+      affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks }),
+    ).rejects.toThrow(/stack "worker-stack" declares src "worker", which does not exist/);
+  });
+
+  test("a stack added since base is changed, rather than refused for having no base source", async () => {
+    const base = project("base", { api: widget("Widget") });
+    const head = project("head", { api: widget("Widget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual(["worker-stack"]);
+  });
+
+  test("names the changed stack, not its lexicon — and leaves the untouched stack out", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual(["api-stack"]);
+    expect(r.changed).not.toContain("fake"); // the lexicon name is not an answer
+  });
+
+  test("a no-output-change refactor in the changed stack's own directory is NOT affected", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: "// a harmless refactor\n" + widget("Widget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual([]);
+  });
+
+  test("a stack spanning two lexicons folds into one artifact keyed by the stack", async () => {
+    const both = (type: string) => widget("Widget") + otherWidget(type);
+    const base = project("base", { api: both("Topic"), worker: widget("Queue") });
+    // Only the second lexicon's partition moves; the stack is still what changed.
+    const head = project("head", { api: both("Bus"), worker: widget("Queue") });
+    const r = await affectedStacks({
+      projectPath: head,
+      baseDir: base,
+      serializers: [fakeSerializer, fakeSerializer2],
+      stacks,
+    });
+    expect(r.changed).toEqual(["api-stack"]);
+  });
+
+  test("a deploy-time Parameter is reported as indeterminate under the stack name", async () => {
+    const base = project("base", { api: deployTimeParam(), worker: widget("Queue") });
+    const head = project("head", { api: deployTimeParam(), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.indeterminate).toEqual(["api-stack"]);
+  });
+
+  test("dependents stay empty — the stack-to-stack relation is not in the build", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget"), worker: widget("Queue") });
+    const r = await affectedStacks({
+      projectPath: head,
+      baseDir: base,
+      serializers: [fakeSerializer],
+      stacks,
+      includeDependents: true,
+    });
+    expect(r.changed).toEqual(["api-stack"]);
+    expect(r.dependents).toEqual([]);
+  });
+
+  test("an empty stacks list keeps the single-root, lexicon-keyed answer", async () => {
+    const base = project("base", { api: widget("Widget") });
+    const head = project("head", { api: widget("Gadget") });
+    const r = await affectedStacks({
+      projectPath: join(head, "api"),
+      baseDir: join(base, "api"),
+      serializers: [fakeSerializer],
+      stacks: [],
+    });
+    expect(r.changed).toEqual(["fake"]);
+  });
+});
+
 describe("affectedStacks — baseRef (git worktree)", () => {
   let repo: string;
   beforeEach(async () => {

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.