@intentius/chant 0.124.31 → 0.124.33

package/src/lifecycle/release-ledger.ts

@@ -58,11 +58,23 @@ export interface RunOrigin {
   repo?: string;
   /** Resolved link to the run, when the environment provided enough to build one. */
   url?: string;
+  /**
+   * The forge's id for the job within the run (#4156): `GITHUB_JOB` on GitHub
+   * and Forgejo, the job's key in the workflow, and `CI_JOB_ID` on GitLab.
+   * Only `chant ci run` in a forge job writes it ({@link resolveCiJob}),
+   * from {@link RUN_ORIGIN_JOB_FLOOR}.
+   */
+  jobId?: string;
+  /** The run's attempt, `GITHUB_RUN_ATTEMPT` on GitHub and Forgejo (#4156). GitLab gives a retried job a new `jobId` instead. */
+  attempt?: number;
 }
 
 /** The first chant that writes `runOrigin.forge: "chant"`, for a job `chant ci run` ran (#4094). */
 export const RUN_ORIGIN_CHANT_FLOOR = "0.124.30";
 
+/** The first chant that writes `runOrigin.jobId` and `runOrigin.attempt`, for a forge job that ran `chant ci run` (#4156). */
+export const RUN_ORIGIN_JOB_FLOOR = "0.124.32";
+
 /**
  * The gate resolution that admitted a deploy (#4020): the gate's address in the
  * gate ledger (`_gates/<op>.jsonl`, `op` and `gate`) and when the resolution
@@ -310,6 +322,28 @@ export function resolveCiRun(env: NodeJS.ProcessEnv = process.env): { runId: str
   return undefined;
 }
 
+/**
+ * The CI run the environment names, as {@link resolveCiRun} has it, with the
+ * job within the run and the run's attempt when the forge gives them
+ * (#4156). `chant ci run` in a forge job records this as its run's origin;
+ * a release record keeps {@link resolveCiRun}'s shape.
+ */
+export function resolveCiJob(env: NodeJS.ProcessEnv = process.env): { runId: string; runOrigin: RunOrigin } | undefined {
+  const ci = resolveCiRun(env);
+  if (!ci) return undefined;
+  const github = ci.runOrigin.forge === "github";
+  const jobId = github ? env.GITHUB_JOB : env.CI_JOB_ID;
+  const attempt = github ? Number(env.GITHUB_RUN_ATTEMPT) : NaN;
+  return {
+    runId: ci.runId,
+    runOrigin: {
+      ...ci.runOrigin,
+      ...(jobId ? { jobId } : {}),
+      ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
+    },
+  };
+}
+
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before

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/lifecycle/work-dir.test.ts

@@ -0,0 +1,77 @@
+/**
+ * #2893: work worktrees live at `.chant/work/[<member>/]<item>` in the
+ * checkout, excluded through `<git-common-dir>/info/exclude`, and the
+ * hand-written walkers skip them.
+ */
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { excludeWorkDir, isWorkDir, removeEmptyWorkDirs, workWorktreePath, legacyWorkWorktreePath, WORK_DIR_EXCLUDE } from "./work-dir";
+import { listFiles } from "../workspace/export";
+
+describe("the work directory", () => {
+  test("a worktree is .chant/work/[<member>/]<item> in the checkout; older versions made it under the git directory", () => {
+    expect(workWorktreePath("/repo", [], "W-1")).toBe(join("/repo", ".chant", "work", "W-1"));
+    expect(workWorktreePath("/repo", ["app"], "W-1")).toBe(join("/repo", ".chant", "work", "app", "W-1"));
+    expect(legacyWorkWorktreePath("/repo/.git", ["app"], "W-1")).toBe(join("/repo/.git", "chant-work", "app", "W-1"));
+  });
+
+  test("isWorkDir is .chant/work at the walk's root or below it, and nothing else in .chant", () => {
+    expect(isWorkDir(".chant/work")).toBe(true);
+    expect(isWorkDir("members/app/.chant/work")).toBe(true);
+    expect(isWorkDir(".chant")).toBe(false);
+    expect(isWorkDir(".chant/factory")).toBe(false);
+    expect(isWorkDir("x.chant/work")).toBe(false);
+  });
+
+  test("the exclude line is written once, after any last line without a newline, and not when git already ignores the directory", async () => {
+    await withTestDir(async (dir) => {
+      const common = join(dir, "git");
+      expect(excludeWorkDir(common, false)).toBe(true);
+      expect(readFileSync(join(common, "info", "exclude"), "utf-8")).toBe(`${WORK_DIR_EXCLUDE}\n`);
+      expect(excludeWorkDir(common, false)).toBe(false);
+      expect(readFileSync(join(common, "info", "exclude"), "utf-8")).toBe(`${WORK_DIR_EXCLUDE}\n`);
+
+      const other = join(dir, "other");
+      mkdirSync(join(other, "info"), { recursive: true });
+      writeFileSync(join(other, "info", "exclude"), "*.log");
+      expect(excludeWorkDir(other, false)).toBe(true);
+      expect(readFileSync(join(other, "info", "exclude"), "utf-8")).toBe(`*.log\n${WORK_DIR_EXCLUDE}\n`);
+
+      const ignored = join(dir, "ignored");
+      expect(excludeWorkDir(ignored, true)).toBe(false);
+      expect(existsSync(join(ignored, "info", "exclude"))).toBe(false);
+    });
+  });
+
+  test("removing a worktree takes the empty directories above it up to .chant, and stops at one that holds anything", async () => {
+    await withTestDir(async (dir) => {
+      // The worktree itself is gone already: removed, its parent left empty.
+      const tree = workWorktreePath(dir, ["app"], "W-1");
+      mkdirSync(dirname(tree), { recursive: true });
+      mkdirSync(workWorktreePath(dir, [], "W-2"), { recursive: true });
+      removeEmptyWorkDirs(tree);
+      expect(existsSync(dirname(tree))).toBe(false);
+      expect(existsSync(join(dir, ".chant", "work", "W-2"))).toBe(true);
+
+      const only = join(dir, "only");
+      mkdirSync(join(only, ".chant", "work"), { recursive: true });
+      removeEmptyWorkDirs(workWorktreePath(only, [], "W-3"));
+      expect(existsSync(join(only, ".chant"))).toBe(false);
+      expect(existsSync(only)).toBe(true);
+    });
+  });
+});
+
+describe("walkers skip .chant/work", () => {
+  test("export's file list outside git leaves out a work worktree and keeps the rest of .chant", async () => {
+    await withTestDir(async (dir) => {
+      for (const p of ["a.ts", ".chant/workspace.lock.json", ".chant/work/W-1/a.ts", "m/.chant/work/W-2/a.ts"]) {
+        mkdirSync(dirname(join(dir, p)), { recursive: true });
+        writeFileSync(join(dir, p), "x");
+      }
+      expect(listFiles(dir)).toEqual([".chant/workspace.lock.json", "a.ts"]);
+    });
+  });
+});

package/src/lifecycle/work-dir.ts

@@ -0,0 +1,82 @@
+/**
+ * Where an Op that changes the checkout makes its work worktrees (#2893).
+ *
+ * A work item's worktree is `<checkout>/.chant/work/[<member>/]<item>`. It
+ * sits inside the checkout, so a coding agent whose project root is the
+ * checkout may write there, and `node_modules` above it still resolves. It
+ * used to be `<git-common-dir>/chant-work/...`, where Claude Code refuses
+ * every write. `/.chant/work/` goes in `<git-common-dir>/info/exclude`, so the
+ * checkout's `git status` never lists it, and the rest of `.chant/` (the
+ * workspace lock, the factory's check logs) stays tracked.
+ *
+ * This module imports nothing from the workspace or the Op runner, so the
+ * hand-written walkers can ask it which directory to skip.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+
+/** The work directory, relative to a checkout's top, `/`-separated. */
+export const WORK_DIR = ".chant/work";
+
+/** The line `<git-common-dir>/info/exclude` gets, anchored at each checkout's top. */
+export const WORK_DIR_EXCLUDE = `/${WORK_DIR}/`;
+
+/** The directory where earlier versions made work worktrees, under the git common directory. */
+export const LEGACY_WORK_DIR = "chant-work";
+
+/**
+ * Whether a directory, given as a `/`-separated path relative to the root a
+ * walker started from, is a work directory: `.chant/work` at that root or at
+ * any depth below it. A walker skips it, since each worktree in it is a whole
+ * copy of the checkout.
+ */
+export function isWorkDir(rel: string): boolean {
+  return rel === WORK_DIR || rel.endsWith(`/${WORK_DIR}`);
+}
+
+/** The worktree for `id` under the checkout whose top is `top`. */
+export function workWorktreePath(top: string, members: readonly string[], id: string): string {
+  return join(top, ...WORK_DIR.split("/"), ...members, id);
+}
+
+/** The worktree an earlier version made for `id`, under the git common directory. */
+export function legacyWorkWorktreePath(commonDir: string, members: readonly string[], id: string): string {
+  return join(commonDir, LEGACY_WORK_DIR, ...members, id);
+}
+
+/**
+ * Add {@link WORK_DIR_EXCLUDE} to `<commonDir>/info/exclude` unless the file
+ * already has it, or `ignored` says git already ignores the work directory
+ * (a `.gitignore` of the project's, or the global excludes file). Returns
+ * whether it wrote the line.
+ */
+export function excludeWorkDir(commonDir: string, ignored: boolean): boolean {
+  const file = join(commonDir, "info", "exclude");
+  const text = existsSync(file) ? readFileSync(file, "utf-8") : "";
+  if (text.split(/\r?\n/).some((l) => l.trim() === WORK_DIR_EXCLUDE)) return false;
+  if (ignored) return false;
+  mkdirSync(join(commonDir, "info"), { recursive: true });
+  appendFileSync(file, `${text === "" || text.endsWith("\n") ? "" : "\n"}${WORK_DIR_EXCLUDE}\n`);
+  return true;
+}
+
+/**
+ * After a work worktree is removed, remove the directories above it that are
+ * left empty, up to and including the checkout's `.chant`, so a run leaves
+ * nothing behind in a checkout that had no `.chant` before it.
+ */
+export function removeEmptyWorkDirs(worktree: string): void {
+  const marker = `${sep}${WORK_DIR.split("/").join(sep)}${sep}`;
+  const at = worktree.lastIndexOf(marker);
+  if (at < 0) return;
+  const stop = worktree.slice(0, at);
+  for (let dir = dirname(worktree); dir.length > stop.length; dir = dirname(dir)) {
+    try {
+      if (readdirSync(dir).length > 0) return;
+      rmdirSync(dir);
+    } catch {
+      return;
+    }
+  }
+}