@intentius/chant 0.124.32 → 0.124.34

package/src/lifecycle/release-publish.test.ts

@@ -1,8 +1,11 @@
 /**
  * #4027: `chant release publish`'s contract. It refuses a release no cut
- * names, a revoked one, and one with no verified signature (#4049; under
- * identity.gates.release even with --allow-unsigned); it warns when the run has no OIDC token; and with no
- * publish target declared it has nothing to publish. With a target (#4047)
+ * names, a revoked one, and under identity.gates.release (even with
+ * --allow-unsigned) or the verified-releases security group (#4049, #4168)
+ * one with no verified signature; under supply-chain it warns when the run
+ * has no OIDC token. With no group a missing signature or OIDC token says
+ * nothing (#4168). With no publish target declared it has nothing to
+ * publish. With a target (#4047)
  * it reads them from release.publish and refuses a checkout that is not the
  * release's commit with a clean tree.
  */
@@ -76,26 +79,37 @@ describe("provenance", () => {
 });
 
 describe("chant release publish", () => {
-  test("warns on a workstation that what it publishes carries no provenance, and has no target to publish to", async () => {
+  test("publishes an unsigned release on a workstation quietly, records it unsigned, and has no target to publish to (#4168)", async () => {
     const { r } = setup(null);
     await cut(r, "v1");
-    const plan = await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION, allowUnsigned: true });
+    const plan = await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION });
     expect(refusal(plan)).toBeNull();
     const p = plan as PublishPlan;
     expect(p.label).toBe("v1");
     expect(p.signature.status).toBe("unsigned");
     expect(p.provenance.oidc).toBe(false);
+    expect(p.warning).toBeNull();
+    expect(p.signatureWarning).toBeNull();
+    expect(p.requireSbom).toBe(false);
+    expect(p.targets).toEqual([]);
+    expect(p.releaseTag).toBe("release/v1");
+  });
+
+  test("under supply-chain, warns on a workstation that what it publishes carries no provenance, and not in CI with OIDC (#4168)", async () => {
+    const { r } = setup({ security: ["supply-chain"] });
+    await cut(r, "v1");
+    const plan = await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION });
+    expect(refusal(plan)).toBeNull();
+    const p = plan as PublishPlan;
+    expect(p.requireSbom).toBe(true);
     expect(p.warning).toBe(
       "this publish runs without OIDC, so what it publishes carries no provenance: this run is not in CI, and a workstation has no OIDC token. Publish from CI to get provenance.",
     );
-    expect(p.targets).toEqual([]);
-    expect(p.releaseTag).toBe("release/v1");
 
     const inCi = (await preparePublish({
       cwd: r.dir,
       ref: p.release.releaseDigest,
       env: { GITHUB_ACTIONS: "true", ACTIONS_ID_TOKEN_REQUEST_URL: "https://x", ACTIONS_ID_TOKEN_REQUEST_TOKEN: "t" },
-      allowUnsigned: true,
     })) as PublishPlan;
     expect(inCi.warning).toBeNull();
     expect(inCi.label).toBe("v1");
@@ -146,12 +160,14 @@ describe("chant release publish", () => {
     expect(refusal(await preparePublish({ cwd: r.dir, ref: "v2", env: WORKSTATION, allowUnsigned: true }))?.code).toBe("release-signature-unverified");
   });
 
-  test("refuses an unsigned release with no release gate, and publishes it under --allow-unsigned with a warning", async () => {
-    const { r } = setup(null);
+  test("under verified-releases, refuses an unsigned release with no release gate, and publishes it under --allow-unsigned with a warning", async () => {
+    const { r } = setup({ security: ["verified-releases"] });
     await cut(r, "v1");
     const refused = refusal(await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION }));
     expect(refused?.code).toBe("release-unsigned");
-    expect(refused?.message).toBe("v1 has no signed cut, and chant release publish publishes only a release signed by a key in .chant/allowed_signers");
+    expect(refused?.message).toBe(
+      "v1 has no signed cut, and the workspace opts into verified-releases (security in chant.workspace.json), which publishes only a release signed by a key in .chant/allowed_signers",
+    );
     expect(refused?.fix).toContain("chant release cut v1 --sign --yes");
     expect(refused?.fix).toContain("--allow-unsigned");
 
@@ -161,8 +177,12 @@ describe("chant release publish", () => {
     expect(allowed.cut).toMatchObject({ actor: "alice", label: "v1", signature: null });
   });
 
-  test.skipIf(!hasSshKeygen)("with no release gate, publishes a release signed by a listed key and refuses one signed by a key the signers file does not list", async () => {
-    const { r, alice, bob } = setup(null, { signers: true });
+  test.skipIf(!hasSshKeygen)("under verified-releases with no release gate, publishes a release signed by a listed key and refuses one signed by a key the signers file does not list", async () => {
+    const { r, alice, bob } = setup({ security: ["verified-releases"] });
+    // Only alice is a signer.
+    r.write(".chant/allowed_signers", `alice ${alice.pub}\n`);
+    const head = r.commit("only alice signs");
+    r.git(["tag", `ci/green/${head}`]);
     await cut(r, "v1", alice);
     const signed = (await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION })) as PublishPlan;
     expect(refusal(signed)).toBeNull();
@@ -180,6 +200,16 @@ describe("chant release publish", () => {
     expect(unlisted?.message).toMatch(/bob has no key in \.chant\/allowed_signers at base/);
   });
 
+  test.skipIf(!hasSshKeygen)("with no security group, publishes a release whose signature does not verify, records it unverified, and says nothing (#4168)", async () => {
+    const { r, bob } = setup(null, { signers: true });
+    await cut(r, "v1", bob, "bob");
+    const p = (await preparePublish({ cwd: r.dir, ref: "v1", env: WORKSTATION })) as PublishPlan;
+    expect(refusal(p)).toBeNull();
+    expect(p.signature.status).toBe("unverified");
+    expect(p.signatureWarning).toBeNull();
+    expect(p.warning).toBeNull();
+  });
+
   test("--require-provenance refuses a run with no OIDC token and passes one in CI", async () => {
     const { r } = setup(null);
     await cut(r, "v1");

package/src/lifecycle/release-publish.ts

@@ -7,16 +7,23 @@
  *
  * - a release no cut names (`release-not-found`);
  * - a release cut from a revoked commit (`release-revoked`, #4033);
- * - a release none of whose cuts carries a signature that verifies for its
- *   actor against `.chant/allowed_signers` at base (`release-unsigned` or
- *   `release-signature-unverified`, #4049), and under an `identity.gates`
- *   entry for `release` (#4031) one whose signer is not in the gate's class.
- *   `--allow-unsigned` publishes one with no verified signature anyway, with
- *   a warning, except under the release gate, which it never overrides.
+ * - under an `identity.gates` entry for `release` (#4031), a release with no
+ *   cut signed by a signer in the gate's class (`release-unsigned` or
+ *   `release-signature-unverified`);
+ * - when the workspace opts into `verified-releases` (`security` in
+ *   chant.workspace.json, #4168), a release none of whose cuts carries a
+ *   signature that verifies for its actor against `.chant/allowed_signers`
+ *   at base (#4049). `--allow-unsigned` publishes it anyway, with a warning;
+ *   it never overrides the release gate.
+ *
+ * With neither, an unsigned release publishes quietly, and the plan records
+ * its `signature` status (#4168: security features are opt-in).
  *
  * It then says whether the run has an OIDC token to sign provenance with
- * ({@link detectProvenance}), and warns when it has none, before any target
- * runs; `--require-provenance` refuses instead (`publish-provenance-missing`).
+ * ({@link detectProvenance}). Under `supply-chain` it warns when there is
+ * none, before any target runs; `--require-provenance` refuses instead
+ * (`publish-provenance-missing`). Without either, provenance is only the
+ * plan's `provenance` field.
  * The targets come from {@link releasePublishTargets}: the member declares them under `release.publish` in its `chant.config.ts` (#4047).
  * With a target, the checkout must be the release's commit with a clean
  * tree ({@link checkCheckoutIsRelease}), every target is planned before any
@@ -154,6 +161,12 @@ export interface PublishContext {
   redactor: Redactor;
   /** Print one line of progress. The line is redacted. */
   log(line: string): void;
+  /**
+   * Whether a target with no SBOM source refuses (`publish-sbom-missing`),
+   * as under the `supply-chain` group (#4168). False or absent: it publishes
+   * without an SBOM. A declared `sbom` file is attached either way.
+   */
+  requireSbom?: boolean;
 }
 
 /** A target refused or failed. The message never holds a credential. */
@@ -252,7 +265,7 @@ export interface PublishPlan {
   /** The verified cut's signature when one verifies, else the newest cut's. */
   signature: { status: "verified" | "unsigned" | "unverified"; actor: string | null; key: string | null; reason: string };
   provenance: ProvenanceCheck;
-  /** The warning printed before publishing, when the run has no OIDC token. */
+  /** The warning printed before publishing, when the run has no OIDC token and the workspace opts into `supply-chain` (#4168). */
   warning: string | null;
   /** The warning printed before publishing a release with no verified signature under `--allow-unsigned` (#4049). */
   signatureWarning: string | null;
@@ -263,6 +276,8 @@ export interface PublishPlan {
   targets: PublishTarget[];
   /** Masks the run's credentials in what the publish prints. */
   redactor: Redactor;
+  /** Whether a target with no SBOM source is refused (`publish-sbom-missing`): the workspace opts into `supply-chain` (#4168). Otherwise it publishes without one. */
+  requireSbom: boolean;
 }
 
 /**
@@ -270,9 +285,10 @@ export interface PublishPlan {
  * whether it may be published, reading the local `chant/lifecycle` branch,
  * the local tags and the declaration at base. Fetches nothing.
  *
- * `allowUnsigned` publishes a release with no verified signature, which is
- * refused otherwise (#4049); it does not override the release gate.
- * `requireProvenance` refuses a run with no OIDC token, where it warns.
+ * `allowUnsigned` publishes a release with no verified signature, which
+ * `verified-releases` refuses otherwise (#4049, #4168); it does not override
+ * the release gate. `requireProvenance` refuses a run with no OIDC token,
+ * where `supply-chain` warns and no group says nothing.
  */
 export async function preparePublish(req: {
   cwd: string;
@@ -287,6 +303,7 @@ export async function preparePublish(req: {
   const { scopeSource } = await import("../workspace/write-scope");
   const { releaseRuleFrom } = await import("../workspace/identity");
   const { checkReleaseSignature } = await import("../workspace/identity-gate-rule");
+  const { securityGroupsIn } = await import("../workspace/security");
   const { cwd, ref } = req;
   const found = await resolveRelease(ref, { cwd });
   if (!found) return { refusal: { code: "release-not-found", message: `no release is labelled or digested "${ref}" in this member`, fix: "List them with: chant release list" } };
@@ -304,7 +321,9 @@ export async function preparePublish(req: {
     };
   }
 
-  const rule = releaseRuleFrom(scopeSource(cwd));
+  const source = scopeSource(cwd);
+  const rule = releaseRuleFrom(source);
+  const groups = securityGroupsIn(source, cwd);
   const cuts = (await readCuts({ cwd })).cuts.filter((c) => c.releaseDigest === release.releaseDigest);
   const checks = cuts.map((c) => ({
     cut: c,
@@ -323,9 +342,9 @@ export async function preparePublish(req: {
       },
     };
   }
-  // #4049: with or without the gate, a publish refuses a release whose signature does not verify, unless --allow-unsigned.
+  // #4049, #4168: under verified-releases a publish refuses a release whose signature does not verify, unless --allow-unsigned. Without it an unsigned release publishes quietly.
   let signatureWarning: string | null = null;
-  if (!verified) {
+  if (!verified && groups.has("verified-releases")) {
     const why = unsigned
       ? `${name} has no signed cut`
       : `no cut of ${name} carries a signature that verifies against the signers file at base: ${checks.map((c) => c.check.reason).join("; ")}`;
@@ -333,7 +352,7 @@ export async function preparePublish(req: {
       return {
         refusal: {
           code: unsigned ? "release-unsigned" : "release-signature-unverified",
-          message: `${why}, and chant release publish publishes only a release signed by a key in .chant/allowed_signers`,
+          message: `${why}, and the workspace opts into verified-releases (security in chant.workspace.json), which publishes only a release signed by a key in .chant/allowed_signers`,
           fix: `Cut it signed with a key .chant/allowed_signers lists for the chant-release namespace: chant release cut ${label ?? "<label>"} --sign --yes. To publish it unsigned anyway, pass --allow-unsigned.`,
         },
       };
@@ -371,7 +390,7 @@ export async function preparePublish(req: {
       },
     };
   }
-  const warning = provenance.oidc
+  const warning = provenance.oidc || !groups.has("supply-chain")
     ? null
     : `this publish runs without OIDC, so what it publishes carries no provenance: ${provenance.reason}. Publish from CI to get provenance.`;
   const { resolveMemberLedger } = await import("./member-ledger");
@@ -380,7 +399,7 @@ export async function preparePublish(req: {
   const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
   const releaseTag = label !== null ? releaseTagName(member, label) : null;
   const redactor = createRedactor(env, targets.flatMap((t) => t.credentialEnv));
-  return { release, label, signature, provenance, warning, signatureWarning, cut, releaseTag, targets, redactor };
+  return { release, label, signature, provenance, warning, signatureWarning, cut, releaseTag, targets, redactor, requireSbom: groups.has("supply-chain") };
 }
 
 /**
@@ -432,6 +451,7 @@ export function publishContext(plan: PublishPlan, req: { cwd: string; env?: Node
     env: req.env ?? process.env,
     redactor: plan.redactor,
     log: (line) => req.log(plan.redactor.redact(line)),
+    requireSbom: plan.requireSbom,
   };
 }
 

package/src/lifecycle/release-store.ts

@@ -14,6 +14,7 @@
  *   _releases/<releaseDigest>.json      the release, written once and never rewritten
  *   _releases/cuts.jsonl                one line per cut, with the release's label
  *   _releases/templates/<digest>.txt    each template's bytes, by content digest
+ *   _releases/templates/<digest>.b64    a file that is not UTF-8, base64 (#4155)
  *
  * `:` is written as `_` in file names, as `_plans/` and `_builds/` do. A
  * workspace member's copy sits under `_members/<member>/` through the same
@@ -24,6 +25,14 @@
  * (ws-104 question 5). They are named by content digest, so a template that
  * two environments or two releases share is stored once.
  *
+ * Since #4155 a cut records every local file a deploy step deploys from, not
+ * only `template`, `manifest` and `values` files: a chart, a kustomize
+ * directory, a site's tree. A directory is recorded as one template per file
+ * under it, and named in the target's `trees`, so a promote deploys the
+ * recorded tree. A target with `trees` is one such cut; a target without the
+ * field was cut before #4155, and a promote of it reads directories and the
+ * other fields from the checkout, as it did then.
+ *
  * `releaseDigest` is `computePlanDigest("release", subject)` over the member,
  * the commit, the artifact digests and each target's env, templates and the
  * name and value of each param. A param's `source`, the label, the actor, the
@@ -32,7 +41,7 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
-import { contentDigest } from "../content-digest";
+import { contentDigest, sha256Hex } from "../content-digest";
 import { computePlanDigest } from "./plan-digest";
 import {
   ledgerDir,
@@ -74,6 +83,15 @@ export interface ReleaseTemplate {
   path: string;
   /** `sha256:<hex>` of the file's bytes. */
   digest: string;
+  /** `base64` for a file that is not UTF-8 (#4155): its stored copy is base64. Absent for text. */
+  encoding?: "base64";
+}
+
+/** A directory a component's deploy names, whose files the target records as templates under its path (#4155). */
+export interface ReleaseTree {
+  component: string | null;
+  /** The directory as the deploy step names it, relative to the member's directory. */
+  path: string;
 }
 
 /** One resolved build parameter of a target. */
@@ -89,6 +107,8 @@ export interface ReleaseTarget {
   env: string;
   templates: ReleaseTemplate[];
   params: ReleaseParam[];
+  /** The directories the target records (#4155). Absent on a target cut before #4155. */
+  trees?: ReleaseTree[];
 }
 
 /** The release file, `_releases/<releaseDigest>.json`. */
@@ -147,9 +167,12 @@ export function normalizeRelease<T extends ReleaseSubject>(release: T): T {
       .map((t) => ({
         env: t.env,
         templates: [...t.templates]
-          .map(({ component, path, digest }) => ({ component, path, digest }))
+          .map(({ component, path, digest, encoding }) => ({ component, path, digest, ...(encoding ? { encoding } : {}) }))
           .sort((a, b) => byString(a.component ?? "", b.component ?? "") || byString(a.path, b.path)),
         params: [...t.params].map(({ name, value, source }) => ({ name, value, source })).sort((a, b) => byString(a.name, b.name)),
+        ...(t.trees
+          ? { trees: [...t.trees].map(({ component, path }) => ({ component, path })).sort((a, b) => byString(a.component ?? "", b.component ?? "") || byString(a.path, b.path)) }
+          : {}),
       }))
       .sort((a, b) => byString(a.env, b.env)),
   };
@@ -162,7 +185,12 @@ export function releaseHashInput(release: ReleaseSubject): unknown {
     member: n.member,
     commit: n.commit,
     artifactDigests: n.artifactDigests,
-    targets: n.targets.map((t) => ({ env: t.env, templates: t.templates, params: t.params.map(({ name, value }) => ({ name, value })) })),
+    targets: n.targets.map((t) => ({
+      env: t.env,
+      templates: t.templates,
+      params: t.params.map(({ name, value }) => ({ name, value })),
+      ...(t.trees ? { trees: t.trees } : {}),
+    })),
   };
 }
 
@@ -184,7 +212,12 @@ export function verifyReleaseDigest(release: Release): boolean {
 
 const stem = (digest: string): string => digest.replace(/:/g, "_");
 const releaseFile = (digest: string): string => `${stem(digest)}.json`;
-const templateFile = (digest: string): string => `${stem(digest)}.txt`;
+const templateFile = (digest: string, encoding?: "base64"): string => `${stem(digest)}.${encoding === "base64" ? "b64" : "txt"}`;
+
+/** The digest of a template's bytes: its text, or what its base64 decodes to. */
+export function templateBytesDigest(content: string, encoding?: "base64"): string {
+  return encoding === "base64" ? `sha256:${sha256Hex(Buffer.from(content, "base64"))}` : contentDigest(content);
+}
 
 /** A label names a release in commands such as `chant release cut <label>`, so it is one plain word. */
 const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/;
@@ -209,7 +242,9 @@ export class ReleaseLabelError extends Error {
 /** A release's template bytes, as the cut read them. */
 export interface TemplateContent {
   digest: string;
+  /** The text, or the base64 of the bytes when `encoding` is `base64`. */
   content: string;
+  encoding?: "base64";
 }
 
 /**
@@ -226,7 +261,7 @@ export async function persistRelease(
     throw new Error(`release ${release.releaseDigest} does not hash to its own digest; refusing to store it`);
   }
   for (const t of templates) {
-    if (contentDigest(t.content) !== t.digest) throw new Error(`template bytes do not hash to ${t.digest}; refusing to store them`);
+    if (templateBytesDigest(t.content, t.encoding) !== t.digest) throw new Error(`template bytes do not hash to ${t.digest}; refusing to store them`);
   }
   const dir = await ledgerDir(RELEASES_DIR, opts);
   const files: LedgerFileWrite[] = [];
@@ -235,10 +270,11 @@ export async function persistRelease(
   if (!exists) files.push({ path: releasePath, content: `${JSON.stringify(release, sortedJsonReplacer)}\n`, expectPriorSha: null });
   const seen = new Set<string>();
   for (const t of templates) {
-    if (seen.has(t.digest)) continue;
-    seen.add(t.digest);
-    if ((await readPathSha(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(t.digest), opts)) !== null) continue;
-    files.push({ path: `${dir}/${TEMPLATES_SUBDIR}/${templateFile(t.digest)}`, content: t.content, expectPriorSha: null });
+    const file = templateFile(t.digest, t.encoding);
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if ((await readPathSha(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, file, opts)) !== null) continue;
+    files.push({ path: `${dir}/${TEMPLATES_SUBDIR}/${file}`, content: t.content, expectPriorSha: null });
   }
   if (files.length === 0) return { commit: null, written: false };
   try {
@@ -274,7 +310,15 @@ export function parseRelease(text: string): Release | null {
         t &&
         typeof t.env === "string" &&
         Array.isArray(t.templates) &&
-        t.templates.every((x) => x && (x.component === null || typeof x.component === "string") && typeof x.path === "string" && typeof x.digest === "string") &&
+        t.templates.every(
+          (x) =>
+            x &&
+            (x.component === null || typeof x.component === "string") &&
+            typeof x.path === "string" &&
+            typeof x.digest === "string" &&
+            (x.encoding === undefined || x.encoding === "base64"),
+        ) &&
+        (t.trees === undefined || (Array.isArray(t.trees) && t.trees.every((x) => x && (x.component === null || typeof x.component === "string") && typeof x.path === "string"))) &&
         Array.isArray(t.params) &&
         t.params.every((p) => p && typeof p.name === "string" && ["string", "number", "boolean"].includes(typeof p.value) && typeof p.source === "string"),
     );
@@ -414,9 +458,9 @@ export async function appendCut(
   throw lastErr;
 }
 
-/** A template's bytes by digest, or null when none is stored. */
-export async function readReleaseTemplate(digest: string, opts?: LedgerLocation): Promise<string | null> {
-  return readBlobFromPath(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(digest), opts);
+/** A template's bytes by digest, or null when none is stored. Under `base64` (#4155), the stored base64 of the bytes. */
+export async function readReleaseTemplate(digest: string, opts?: LedgerLocation, encoding?: "base64"): Promise<string | null> {
+  return readBlobFromPath(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(digest, encoding), opts);
 }
 
 /**

package/src/lifecycle/run-ledger.test.ts

@@ -92,6 +92,19 @@ describe("buildRunRecord", () => {
     expect(input.phases[1].steps.map((s) => s.status)).toEqual(["ok", "skipped"]);
   });
 
+  test("keeps a shell step's image on its record (#4015), and nothing for a step without one", () => {
+    const image = `node:24@sha256:${"c".repeat(64)}`;
+    const input = buildRunRecord(
+      { name: "build" },
+      [
+        { phase: "Build", fn: "shellCmd", args: { cmd: "npm test", image }, status: "ok", durationMs: 3 },
+        { phase: "Build", fn: "shellCmd", args: { cmd: "echo hi" }, status: "ok", durationMs: 1 },
+      ],
+      { started: "2026-01-01T00:00:00.000Z", ended: "2026-01-01T00:00:01.000Z", status: "ok" },
+    );
+    expect(input.phases[0].steps.map((s) => s.image)).toEqual([image, undefined]);
+  });
+
   test("carries the commit and the CI run origin when given (#4020), and neither when not", () => {
     const times = { started: "2026-01-01T00:00:00.000Z", ended: "2026-01-01T00:00:01.000Z", status: "ok" as const };
     const withBoth = buildRunRecord({ name: "ship" }, [], { ...times, gitSha: "a".repeat(40), runOrigin: { forge: "github", repo: "acme/app" } });

package/src/lifecycle/run-ledger.ts

@@ -119,6 +119,7 @@ export function buildRunRecord(
       ...(record.point ? { point: record.point } : {}),
       ...(record.gate ? { gate: record.gate } : {}),
       ...(record.resumed ? { resumed: record.resumed } : {}),
+      ...(record.fn === "shellCmd" && typeof record.args?.image === "string" ? { image: record.args.image } : {}),
     });
     if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
   }

package/src/lint/rules/op/index.ts

@@ -16,6 +16,7 @@ import { ops014 } from "./ops014-converge-rule-refusals";
 import { ops015 } from "./ops015-gate-approval";
 import { ops016 } from "./ops016-gate-resume";
 import { ops017Check } from "./ops017-gate-alias";
+import { ops018 } from "./ops018-shell-image-digest";
 import { sys010Check } from "./sys010-key-over-plain-http";
 import type { DecideBackend } from "../../../op/decide-config";
 
@@ -25,6 +26,7 @@ export { ops014 } from "./ops014-converge-rule-refusals";
 export { ops015 } from "./ops015-gate-approval";
 export { ops016 } from "./ops016-gate-resume";
 export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias";
+export { ops018 } from "./ops018-shell-image-digest";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http";
 
 export interface CoreOpCheckOptions {
@@ -36,9 +38,9 @@ export interface CoreOpCheckOptions {
 
 /**
  * Core's own post-synth checks over the Op model: OPS012, OPS013, OPS014,
- * OPS015, OPS016, OPS017 over the workspace's `identity.gates`, and SYS010
+ * OPS015, OPS016, OPS017 over the workspace's `identity.gates`, OPS018, and SYS010
  * over the `decide` steps and the configured decide backends.
  */
 export function coreOpChecks(opts: CoreOpCheckOptions = {}): PostSynthCheck[] {
-  return [ops012, ops013, ops014, ops015, ops016, ops017Check(opts.identityGates), sys010Check(opts.decideBackends)];
+  return [ops012, ops013, ops014, ops015, ops016, ops017Check(opts.identityGates), ops018, sys010Check(opts.decideBackends)];
 }

package/src/lint/rules/op/ops018-shell-image-digest.test.ts

@@ -0,0 +1,60 @@
+/**
+ * OPS018 (#4015): a shell step's image is pinned by digest.
+ */
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "../../post-synth";
+import { DECLARABLE_MARKER } from "../../../declarable";
+import { stepOutput } from "../../../op/step-output-ref";
+import { ops018 } from "./ops018-shell-image-digest";
+import { coreOpChecks } from "./index";
+
+const PINNED = `node:24@sha256:${"d".repeat(64)}`;
+
+function ctxWith(props: Record<string, unknown>): PostSynthContext {
+  const entities = new Map<string, unknown>([["build", {
+    [DECLARABLE_MARKER]: true,
+    entityType: "Chant::Op",
+    lexicon: "chant",
+    kind: "resource",
+    props: { name: "build", overview: "test", ...props },
+    attributes: {},
+  }]]);
+  return {
+    outputs: new Map([["chant", ""]]),
+    entities: entities as Map<string, never>,
+    buildResult: { outputs: new Map([["chant", ""]]), entities: entities as Map<string, never>, warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+const sh = (args: Record<string, unknown>) => ({ kind: "activity", fn: "shellCmd", args: { cmd: "npm test", ...args } });
+
+describe("OPS018", () => {
+  test("is one of core's Op checks", () => {
+    expect(coreOpChecks().map((c) => c.id)).toContain("OPS018");
+  });
+
+  test("a pinned image and a step with no image pass", () => {
+    expect(ops018.check(ctxWith({ phases: [{ name: "Build", steps: [sh({ image: PINNED }), sh({})] }] }))).toEqual([]);
+  });
+
+  test("a tag is refused, naming the Op, the phase and the fix", () => {
+    const [diag, ...rest] = ops018.check(ctxWith({ phases: [{ name: "Build", steps: [sh({ image: "node:24" })] }] }));
+    expect(rest).toEqual([]);
+    expect(diag?.checkId).toBe("OPS018");
+    expect(diag?.severity).toBe("error");
+    expect(diag?.message).toBe('Op "build", phase "Build", shellCmd: image "node:24" is not pinned by digest: name it as <ref>@sha256:<digest>');
+  });
+
+  test("an image read from another step is refused, since the record could not say what ran", () => {
+    const [diag] = ops018.check(ctxWith({ phases: [{ name: "Build", steps: [sh({ image: stepOutput("pick", "stdout") })] }] }));
+    expect(diag?.message).toContain("image must be a literal string");
+  });
+
+  test("onFailure and effect steps are checked too", () => {
+    const diags = ops018.check(ctxWith({
+      phases: [{ name: "Apply", steps: [{ kind: "effect", receipt: {}, steps: [sh({ image: "alpine" })] }] }],
+      onFailure: [{ name: "Rollback", steps: [sh({ image: "alpine:latest" })] }],
+    }));
+    expect(diags.map((d) => d.message.split(",")[1]?.trim())).toEqual(['phase "Apply"', 'phase "Rollback"']);
+  });
+});

package/src/lint/rules/op/ops018-shell-image-digest.ts

@@ -0,0 +1,48 @@
+/**
+ * OPS018: a `shellCmd` step that runs in a container (#4015) names its image
+ * pinned by digest, `<ref>@sha256:<digest>`, as a literal string. A tag can
+ * move between two runs of the same Op, and then the step record's image no
+ * longer says what ran. Checked over the main phases, `onFailure`, and the
+ * steps inside an effect.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import type { OpConfig, PhaseDefinition, StepDefinition } from "../../../op";
+import { imageProblem } from "../../../op/activities/shell";
+import { isOpEntity } from "./support";
+
+function activitySteps(steps: readonly StepDefinition[]): Array<{ fn: string; args?: Record<string, unknown> }> {
+  return steps.flatMap((step) =>
+    step.kind === "activity" ? [step] : step.kind === "effect" ? step.steps.filter((s) => s.kind === "activity") : [],
+  ) as Array<{ fn: string; args?: Record<string, unknown> }>;
+}
+
+export const ops018: PostSynthCheck = {
+  id: "OPS018",
+  description: "A shell step with an image names it pinned by digest, as a literal string",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [entityKey, entity] of ctx.entities) {
+      if (!isOpEntity(entity)) continue;
+      const rec = entity as unknown as Record<string, unknown>;
+      const props = ((entity as { props?: Record<string, unknown> }).props ?? {}) as unknown as OpConfig;
+      if (typeof props.name !== "string" || !Array.isArray(props.phases)) continue;
+      const phases: PhaseDefinition[] = [...props.phases, ...(props.onFailure ?? [])];
+      for (const phase of phases) {
+        for (const step of activitySteps(phase.steps ?? [])) {
+          if (step.fn !== "shellCmd" || step.args?.image === undefined) continue;
+          const problem = imageProblem(step.args.image);
+          if (!problem) continue;
+          diagnostics.push({
+            checkId: "OPS018",
+            severity: "error",
+            message: `Op "${props.name}", phase "${phase.name}", shellCmd: ${problem}`,
+            entity: entityKey,
+            lexicon: typeof rec.lexicon === "string" ? rec.lexicon : undefined,
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

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

@@ -59,6 +59,9 @@ export const shellCmdContract = activityContract(
     gatedExit: z.number().optional(),
     gate: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
     json: z.boolean().optional(),
+    image: z.string().optional(),
+    mounts: z.strictObject({ workspace: z.enum(["ro", "rw"]).optional() }).optional(),
+    outputs: z.array(z.string()).optional(),
   }),
   // `json` is stdout parsed, when the step sets `json` (#2787): whatever the
   // command printed, so its shape is the author's and only the whole value is