@intentius/chant 0.124.30 → 0.124.32

package/src/op/local-executor.ts

@@ -56,6 +56,7 @@ import { LiveRun, currentLiveRun, withLiveRun } from "./run-live";
 import { runEnvOf } from "../lifecycle/run-ledger";
 import { resolveCommitSha } from "../lifecycle/commit-sha";
 import { resolveCiRun, type RunOrigin } from "../lifecycle/release-ledger";
+import { redactDeep, redactText, type Redact } from "./redact";
 import { runEventsOfStepRecord, type RunEventKind, type RunEventRuntime, type RunEventSkipReason } from "../run-event";
 import { openRunEventStore, teeLines } from "../run-event-store";
 import { openRunEventStream, runEventRunOf, type RunEventSink, type RunEventStream } from "../run-event-stream";
@@ -1377,6 +1378,17 @@ export interface RunOpOptions {
    * needs one. The local runtime passes the configured lexicons' contracts.
    */
   contracts?: ReadonlyMap<string, ActivityContract>;
+  /**
+   * Redacts secret values (#4096) from what the run writes about itself:
+   * each {@link runEvents} line and each line kept on this host, each
+   * {@link stepOutput} line and step label, and the run record, its step
+   * records and its `failure`, before {@link signRecord} signs it and the
+   * ledger stores it. The step records on the result are redacted too. This
+   * is the one place a run's writes pass through, so a writer added here
+   * later is redacted with the rest. `chant ci run` passes one built from
+   * the host's secrets file (../workspace/ci-secrets.ts).
+   */
+  redact?: Redact;
 }
 
 /**
@@ -1437,7 +1449,11 @@ export async function runOpLocally(
   const events: { stream?: RunEventStream } = {};
   try {
     const stepConsole = options.stepOutput
-      ? { write: options.stepOutput, ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}) }
+      ? {
+          write: options.stepOutput,
+          ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}),
+          ...(options.redact ? { redact: options.redact } : {}),
+        }
       : undefined;
     return await withLiveRun(live, () =>
       withRunConsole(stepConsole, () =>
@@ -1478,7 +1494,10 @@ async function runOpInTurn(
   const store = options.ledger
     ? await openRunEventStore(options.ledger.cwd ?? options.cwd ?? process.cwd(), runId)
     : undefined;
-  const eventsWrite = teeLines(options.runEvents?.write, store?.write.bind(store));
+  const teed = teeLines(options.runEvents?.write, store?.write.bind(store));
+  // #4096: every event line, to the caller and to this host's store alike, is redacted once, here.
+  const redact = options.redact;
+  const eventsWrite = teed && redact ? (line: string) => teed(redactText(line, redact)) : teed;
   const stream = eventsWrite
     ? openRunEventStream(
         runEventRunOf({
@@ -1620,7 +1639,7 @@ async function runOpInTurn(
     point?: WaitingPoint,
   ): Promise<OpRunRecord> => {
     const ended = options.now ?? new Date().toISOString();
-    const input = buildRunRecord(config, settled, {
+    let input = buildRunRecord(config, settled, {
       started: startedAt,
       ended,
       status,
@@ -1638,6 +1657,15 @@ async function runOpInTurn(
       const failure = options.describeFailure(settled);
       if (failure) input.failure = failure;
     }
+    // #4096: the record is redacted before it is signed, so the stored record is the one the statement covers.
+    // The step records on the result are redacted in place, so a caller printing them prints no secret.
+    if (redact) {
+      input = redactDeep(input, redact);
+      for (const r of settled) {
+        if (r.error !== undefined) r.error = redact(r.error);
+        if (r.args) r.args = redactDeep(r.args, redact);
+      }
+    }
     let record: OpRunRecord = { version: 1, ...input, id: runId };
     if (options.signRecord) {
       try {

package/src/op/op-waves-run.ts

@@ -68,6 +68,7 @@ import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger"
 import type { GatePointAsker } from "../point-decision";
 import type { WaitingPoint } from "./steward-points";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
+import { isLifecycleLocalNote } from "../lifecycle/local-note";
 import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
 import type { TrustPolicy } from "../workspace/trust/policy";
 import type { GateSigners } from "../workspace/trust/gate-seal";
@@ -1721,11 +1722,22 @@ async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed:
   }
 }
 
+/**
+ * Throws unless a spend's record reached the remote the next run reads
+ * (#3985). Without that, the next run reads the approval or override as
+ * unspent. A ledger with no remote is the whole ledger, so a line recorded
+ * there is spent.
+ */
+function requireSpendPushed(result: { pushed: boolean; pushWarning?: string }): void {
+  if (result.pushed || isLifecycleLocalNote(result.pushWarning)) return;
+  throw new Error(`the record did not reach the remote the next run reads: ${result.pushWarning ?? "the push did not land"}`);
+}
+
 /**
  * Record each override the wave is about to apply under (#3821), in
  * `_gates/policy-override/applied.jsonl`, which spends it: written before
- * anything applies, once. False when the lines could not be written: the
- * wave then fails and applies nothing.
+ * anything applies, once. False when the lines could not be written or did
+ * not reach the remote (#3985): the wave then fails and applies nothing.
  */
 async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promise<boolean> {
   const used = decision.members.filter((m) => m.override);
@@ -1738,7 +1750,7 @@ async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promi
     if (!port.appendApplied) throw new Error("this gate ledger cannot record an applied override");
     for (const m of used) {
       const record = og.appliedOverride({ subject: m.member, digest: m.override!.digest, at: m.override!.at, by: m.override!.by }, { timestamp: now });
-      await port.appendApplied(record as unknown as AppliedGateRecord);
+      requireSpendPushed(await port.appendApplied(record as unknown as AppliedGateRecord));
     }
   } catch (err) {
     failed(ctx, `wave ${k} (${wave.name}) could not record the overrides it applies under, so nothing applied: ${err instanceof Error ? err.message : String(err)}`);
@@ -2153,9 +2165,11 @@ async function applyStage(
  * Record that the wave applies under its approval (#3784), which spends it:
  * one line in `_gates/<name>/applied.jsonl`, before anything applies, as
  * terragucci's wave gate writes it. Only an approved wave under the spend
- * rule records, and only once. False when the line could not be written: the
+ * rule records, and only once. False when the line could not be written, or
+ * was written but did not reach the remote the next run reads (#3985): the
  * wave then fails and applies nothing, since an apply the record misses
- * would leave its approval standing.
+ * would leave its approval standing. A ledger with no remote is the whole
+ * ledger, so a line recorded there is spent.
  */
 async function spendApproval(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<boolean> {
   if (!decision.spend || decision.status !== "approved" || decision.spentAt || !decision.approvedAt) return true;
@@ -2177,6 +2191,7 @@ async function spendApproval(options: RunOpWaveOptions, ctx: WaveContext, decisi
   try {
     if (!port.appendApplied) throw new Error("this gate ledger cannot record an applied approval");
     const pushed = await port.appendApplied(record);
+    requireSpendPushed(pushed);
     if (!pushed.pushed && pushed.pushWarning) log(`wave ${k} (${wave.name}): ${pushed.pushWarning}`);
   } catch (err) {
     failed(ctx, `wave ${k} (${wave.name}) could not record that it applies under the approval by ${record.approvedBy}, so nothing applied: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -17,6 +17,8 @@ import {
 } from "./op-waves-run";
 import { memoryGateLedgerPort } from "./gate";
 import { waveSetDigest } from "../gated-waves";
+import type { AppliedGateRecord } from "../lifecycle/gate-applied";
+import { LIFECYCLE_LOCAL_NOTE } from "../lifecycle/local-note";
 
 const spec: OpWavesSpec = {
   name: "migrations",
@@ -475,6 +477,39 @@ describe("spent approvals (#3784)", () => {
     h.done();
   });
 
+  test("a spend whose record does not reach the remote applies nothing, and the approval stays unspent (#3985)", async () => {
+    const h = harness(spending);
+    const memory = memoryGateLedgerPort({ resolutions: [approval] });
+    const gates = {
+      ...memory,
+      async appendApplied(record: AppliedGateRecord) {
+        await memory.appendApplied!(record);
+        return { pushed: false, pushWarning: 'the push of chant/lifecycle to "origin" failed' };
+      },
+    };
+    const result = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 1, applied: [] });
+    expect(result.decision?.spentAt).toBeUndefined();
+    expect(h.applies()).toBe(0);
+    h.done();
+  });
+
+  test("with no remote the local ledger is the whole ledger, so a spend recorded there applies (#3985)", async () => {
+    const h = harness(spending);
+    const memory = memoryGateLedgerPort({ resolutions: [approval] });
+    const gates = {
+      ...memory,
+      async appendApplied(record: AppliedGateRecord) {
+        await memory.appendApplied!(record);
+        return { pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE };
+      },
+    };
+    const result = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 0, decision: { status: "approved", spentAt: "2026-10-11T00:00:00Z" } });
+    expect(memory.applied).toHaveLength(1);
+    h.done();
+  });
+
   test("a wave that cannot record the approval applies nothing", async () => {
     const h = harness(spending);
     const gates = { ...memoryGateLedgerPort({ resolutions: [approval] }), appendApplied: undefined };
@@ -878,6 +913,20 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     other.done();
   });
 
+  test("an override spend whose record does not reach the remote applies nothing (#3985)", async () => {
+    const { overrideDigest } = await import("../override-gate");
+    const od = overrideDigest("vpc", digest("1"), ["no-public-s3"]);
+    const h = harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2"), empty: true } }, { extra: { overriders: ["github:carol"] }, atBase: { ...tg, waves: [{ ...tg.waves[0]!, gate: "never" }] } });
+    const memory = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "policy-override", gate: "vpc", resolvedBy: "github:carol", timestamp: "2026-10-10T00:00:00Z", planDigest: od, note: "the bucket is the public docs site" }],
+    });
+    const gates = { ...memory, appendApplied: async () => ({ pushed: false, pushWarning: 'the push of chant/lifecycle to "origin" failed' }) };
+    const result = await run(h, gates);
+    expect(result).toMatchObject({ exitCode: 1, applied: [] });
+    expect(h.calls.some((c) => c.startsWith("tg apply"))).toBe(false);
+    h.done();
+  });
+
   test("a plans file's overridersSource names the list in the refusal and the decision record (#3848)", async () => {
     const mk = (extra: Record<string, unknown>) => harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2") } }, { extra });
     const logs: string[] = [];

package/src/op/operator.ts

@@ -399,8 +399,8 @@ const STEWARD_TURN_POLL_MS = 150;
  *
  * Contention never queues past `waitMs` (0 by default): consistent with a
  * round's own leases, which skip and report rather than wait (see this
- * module's doc), and with the fountain form, whose busy teammate is likewise
- * refused rather than retried. A caller that wants to ride out a race with a
+ * module's doc), and with the fountain form, whose busy steward conversation
+ * is likewise refused rather than retried. A caller that wants to ride out a race with a
  * turn about to end passes `waitMs`, and this polls every
  * {@link STEWARD_TURN_POLL_MS} until it acquires or the wait runs out.
  */

package/src/op/redact.ts

@@ -0,0 +1,93 @@
+/**
+ * Redaction of secret values (#4096): what a run writes about itself, with
+ * each secret value replaced by `***`.
+ *
+ * The executor (./local-executor.ts) takes a {@link Redact} and applies it
+ * where a run writes: each run-event line, each line a step prints, and the
+ * run record before it is signed and stored. `chant ci run` builds one from
+ * the host's secrets file and the job's secret-looking variables
+ * (../workspace/ci-secrets.ts).
+ *
+ * A value shorter than {@link REDACT_MIN_LENGTH} characters is not
+ * redacted: a two- or three-character value matches too much ordinary text.
+ */
+
+/** What every redacted value is replaced with. */
+export const REDACTED = "***";
+
+/** The shortest value redacted. Shorter values are left as they are. */
+export const REDACT_MIN_LENGTH = 4;
+
+/** A text with every secret value it contains replaced by {@link REDACTED}. */
+export type Redact = (text: string) => string;
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The redactor for `values`, or undefined when none is long enough to
+ * redact. A value that spans lines is also redacted line by line, since
+ * step output reaches a reader one line at a time.
+ */
+export function redactorOf(values: Iterable<string>): Redact | undefined {
+  const all = new Set<string>();
+  const add = (v: string): void => {
+    if (v.length < REDACT_MIN_LENGTH) return;
+    all.add(v);
+    // As a JSON string spells it, for a value with a quote, a backslash or a control character in it.
+    all.add(JSON.stringify(v).slice(1, -1));
+  };
+  for (const value of values) {
+    add(value);
+    if (value.includes("\n")) for (const line of value.split(/\r?\n/)) add(line.trim());
+  }
+  if (all.size === 0) return undefined;
+  // Longest first, so a value that contains another is replaced whole.
+  const pattern = new RegExp([...all].sort((a, b) => b.length - a.length).map(escapeRegExp).join("|"), "g");
+  return (text) => (typeof text === "string" && text.length >= REDACT_MIN_LENGTH ? text.replace(pattern, REDACTED) : text);
+}
+
+/** `value` with `redact` applied to every string in it, keys included. Numbers, booleans and nulls are kept. */
+export function redactDeep<T>(value: T, redact: Redact): T {
+  if (typeof value === "string") return redact(value) as T;
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, redact)) as T;
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[redact(k)] = redactDeep(v, redact);
+    return out as T;
+  }
+  return value;
+}
+
+/**
+ * A JSON value's text, as `JSON.stringify` wrote it, with `redact` applied to
+ * its strings: parsed, redacted and written again, so a short value such as
+ * `true` that is also a secret doesn't break the document. Undefined when
+ * `text` is not JSON.
+ */
+function redactJsonText(text: string, redact: Redact): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const indent = /^[[{]\r?\n(\s+)/.exec(text)?.[1]?.length;
+  const trailing = /\s*$/.exec(text)?.[0] ?? "";
+  return `${JSON.stringify(redactDeep(parsed, redact), null, indent)}${trailing}`;
+}
+
+/**
+ * A file's or line's text redacted: a JSON document as JSON, each line of a
+ * JSON Lines text as JSON, and any other text, or line, as text. The text
+ * comes back unchanged when it holds no secret.
+ */
+export function redactText(text: string, redact: Redact): string {
+  if (redact(text) === text) return text;
+  const whole = redactJsonText(text, redact);
+  if (whole !== undefined) return whole;
+  return text
+    .split("\n")
+    .map((line) => (redact(line) === line ? line : (redactJsonText(line, redact) ?? redact(line))))
+    .join("\n");
+}

package/src/op/step-console.ts

@@ -41,6 +41,8 @@ interface StepConsole {
 export interface RunConsole {
   write: (line: string) => void;
   heartbeatMs?: number;
+  /** Applied to each line before it is written, and to a step's call before it is cut to a label (#4096). */
+  redact?: (text: string) => string;
 }
 
 const store = new AsyncLocalStorage<StepConsole>();
@@ -60,7 +62,10 @@ function formatArgs(args: Record<string, unknown>): string {
 /** The name a step's lines carry: its id, else `fn(args)` on one line, cut to {@link MAX_LABEL}. */
 export function stepLabel(fn: string, args: Record<string, unknown>, id?: string): string {
   if (id) return id;
-  const call = `${fn}(${formatArgs(args)})`.replace(/\s+/g, " ");
+  // A secret in the call is redacted before the label is cut, so a cut never leaves part of one.
+  const redact = runStore.getStore()?.redact;
+  const raw = `${fn}(${formatArgs(args)})`;
+  const call = (redact ? redact(raw) : raw).replace(/\s+/g, " ");
   return call.length > MAX_LABEL ? `${call.slice(0, MAX_LABEL - 4)}...)` : call;
 }
 
@@ -72,7 +77,7 @@ export function stepLabel(fn: string, args: Record<string, unknown>, id?: string
 export async function withStepConsole<T>(opts: { phase: string; label: string }, fn: () => Promise<T>): Promise<T> {
   const run = runStore.getStore();
   if (!run) return fn();
-  const { write } = run;
+  const write = run.redact ? (line: string) => run.write(run.redact!(line)) : run.write;
   const prefix = `[${opts.phase}] ${opts.label}`;
   const started = Date.now();
   let spoke = false;

package/src/op/steward.ts

@@ -5,9 +5,11 @@
  * A steward runs a fixed list of Ops, each on its own `schedule` when it has
  * one, one Op at a time. Where it runs is its form:
  *
- * - `fountain`: the fountain lexicon's `Steward` composite, an `acp` Agent on
- *   a persistent sandbox bound to a Teammate, with a Fountain `Schedule` per
- *   scheduled Op. A turn is one `chant run <op>` on the teammate's thread.
+ * - `fountain`: the fountain lexicon's `Steward` composite, an `acp` Agent
+ *   whose runs `chant run <op> --on fountain` sends to one long-lived
+ *   conversation, resumed by channel_id. A turn is one `chant run <op>` in
+ *   that conversation. Managoat has no scheduler, so a scheduled Op's cron
+ *   fires from a clock outside it (a CI schedule, a CronJob).
  * - `local`: `chant operator --steward <name>` in the box itself, for a box
  *   with no Fountain behind it (a docker compose box, a Sprites box). The same
  *   Ops on the same crons, each run under its operator lease, and the steward
@@ -129,7 +131,7 @@ export interface StewardBeside {
 }
 
 export interface StewardDeclarationConfig {
-  /** The steward's name. On Fountain, the Agent's and the Teammate's. */
+  /** The steward's name. On Fountain, the Agent's, and the key of its conversation. */
   name: string;
   /** The Ops it runs. A scheduled one runs on its cron; any other runs when asked. */
   ops: StewardOpInput[];

package/src/op/work-lease-run.test.ts

@@ -342,9 +342,10 @@ describe("an Op that changes the checkout", () => {
       expect(result.workLease).toMatchObject({ item: "W-7", branch: "chant/work/W-7", released: true, outcome: "done" });
       expect(result.workLease?.holder).toBe(stewardWorkHolder("box", "dispatch", "h1"));
 
-      // The worktree sat under the git directory and is gone; the branch keeps the build.
-      expect(worktree.startsWith(join(dir, ".git"))).toBe(true);
+      // The worktree sat at .chant/work/<item> in the checkout and is gone, with the directories it left empty; the branch keeps the build.
+      expect(worktree).toBe(join(dir, ".chant", "work", "W-7"));
       expect(existsSync(worktree)).toBe(false);
+      expect(existsSync(join(dir, ".chant"))).toBe(false);
       expect(git(["show", "chant/work/W-7:app/feature.ts"], dir).stdout).toBe("export const feature = true;\n");
 
       // The coding agent's checkout: its edit, its lock, HEAD and the index, as they were.
@@ -403,3 +404,88 @@ describe("an Op that changes the checkout", () => {
     });
   });
 });
+
+describe("where the worktree is (#2893)", () => {
+  const record = (seen: { worktree?: string; status?: string }) =>
+    new Map<string, ActivityFn>([
+      [
+        "build",
+        async (args) => {
+          seen.worktree = String(args.worktree);
+          writeFileSync(join(seen.worktree, "app", "feature.ts"), "export const feature = true;\n");
+          seen.status = git(["status", "--porcelain", "--untracked-files=all"], dir()).stdout;
+          return {};
+        },
+      ],
+    ]);
+  let current = "";
+  const dir = () => current;
+  const op = (item: string) => dispatchOp({ workLease: { item }, changesCheckout: true }, [step("build", { worktree: workLeaseOutput("worktree") })]);
+
+  test("it is .chant/work/<item> in the checkout, info/exclude gets /.chant/work/ once, and git status stays clean while it is there", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      const seen: { worktree?: string; status?: string } = {};
+      const first = await run(op("W-20"), record(seen), d);
+      expect(first.workLease).toMatchObject({ released: true, outcome: "done" });
+      expect(seen.worktree).toBe(join(d, ".chant", "work", "W-20"));
+      expect(seen.status).toBe("");
+      const exclude = () => readFileSync(join(d, ".git", "info", "exclude"), "utf-8").split("\n").filter((l) => l === "/.chant/work/");
+      expect(exclude()).toHaveLength(1);
+      await run(op("W-21"), record(seen), d);
+      expect(exclude()).toHaveLength(1);
+      expect(git(["status", "--porcelain", "--untracked-files=all"], d).stdout).toBe("");
+      expect(git(["worktree", "list", "--porcelain"], d).stdout).not.toContain(".chant/work");
+    });
+  });
+
+  test("info/exclude is left alone when the project already ignores .chant/work", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      writeFileSync(join(d, ".gitignore"), ".chant/\n");
+      git(["add", ".gitignore"], d);
+      git(["commit", "-q", "-m", "ignore"], d);
+      const before = existsSync(join(d, ".git", "info", "exclude")) ? readFileSync(join(d, ".git", "info", "exclude"), "utf-8") : "";
+      const seen: { worktree?: string; status?: string } = {};
+      await run(op("W-22"), record(seen), d);
+      expect(seen.status).toBe("");
+      const after = existsSync(join(d, ".git", "info", "exclude")) ? readFileSync(join(d, ".git", "info", "exclude"), "utf-8") : "";
+      expect(after).toBe(before);
+    });
+  });
+
+  test("a worktree a crashed run left under .git/chant-work with the branch checked out is removed, and the run goes on from the branch", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      const old = join(d, ".git", "chant-work", "W-23");
+      expect(git(["worktree", "add", "-q", "-b", "chant/work/W-23", old, "HEAD"], d).status).toBe(0);
+      writeFileSync(join(old, "app", "earlier.ts"), "export const earlier = 1;\n");
+      git(["add", "-A"], old);
+      git(["commit", "-q", "-m", "an earlier run"], old);
+      const seen: { worktree?: string; status?: string } = {};
+      const result = await run(op("W-23"), record(seen), d);
+      expect(result.workLease).toMatchObject({ released: true, outcome: "done" });
+      expect(seen.worktree).toBe(join(d, ".chant", "work", "W-23"));
+      expect(existsSync(old)).toBe(false);
+      expect(git(["worktree", "list", "--porcelain"], d).stdout).not.toContain("chant-work");
+      expect(git(["show", "chant/work/W-23:app/earlier.ts"], d).stdout).toBe("export const earlier = 1;\n");
+    });
+  });
+
+  test("a worktree a crashed run left at .chant/work with the branch checked out is replaced", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      const left = join(d, ".chant", "work", "W-24");
+      expect(git(["worktree", "add", "-q", "-b", "chant/work/W-24", left, "HEAD"], d).status).toBe(0);
+      writeFileSync(join(left, "app", "stray.ts"), "stray\n");
+      const seen: { worktree?: string; status?: string } = {};
+      const result = await run(op("W-24"), record(seen), d);
+      expect(result.workLease).toMatchObject({ released: true, outcome: "done" });
+      expect(existsSync(left)).toBe(false);
+    });
+  });
+});

package/src/op/work-lease-run.ts

@@ -39,10 +39,11 @@
  *
  * An Op with `changesCheckout` (applying a build, `chant workspace upgrade`)
  * must declare `workLease`, and its leased steps get a git worktree of their
- * own: `chant/work/<item>` checked out under the repository's git directory,
- * from the checkout's HEAD, or from the branch as an earlier run left it. The
- * worktree is removed when the run ends and the branch keeps whatever the
- * steps committed, for the runner to deliver. The checkout a coding agent is
+ * own: `chant/work/<item>` checked out at `.chant/work/<item>` in the
+ * checkout (#2893), which `<git-common-dir>/info/exclude` keeps out of
+ * `git status`, from the checkout's HEAD or from the branch as an earlier run
+ * left it. The worktree is removed when the run ends and the branch keeps
+ * whatever the steps committed, for the runner to deliver. The checkout a coding agent is
  * editing, its index and its uncommitted files, are never touched.
  *
  * A run that ends `not_done` keeps its attempt aside (#3147): whatever the
@@ -54,7 +55,7 @@
  */
 
 import { existsSync, rmSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, resolve, sep } from "node:path";
 import { getRuntime } from "../runtime-adapter";
 import {
   claimWorkLease,
@@ -69,6 +70,7 @@ import {
   type WorkLease,
 } from "../lifecycle/work-lease";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { excludeWorkDir, legacyWorkWorktreePath, LEGACY_WORK_DIR, removeEmptyWorkDirs, WORK_DIR, workWorktreePath } from "../lifecycle/work-dir";
 import { currentHolderId } from "../lifecycle/lease";
 import { parseDuration } from "./duration";
 import { isStepOutputRef, stepOutput, type StepOutputRef } from "./step-output-ref";
@@ -271,21 +273,36 @@ export class RunWorkLease {
   }
 
   /**
-   * A worktree for `id` on `chant/work/[<member>/]<id>`, under the git
-   * directory so the checkout's own `git status` never lists it. Starts from
-   * the branch when an earlier run left it, from HEAD otherwise.
+   * A worktree for `id` on `chant/work/[<member>/]<id>`, at
+   * `<checkout>/.chant/work/[<member>/]<id>` (#2893): inside the checkout, so
+   * a coding agent may write there and `node_modules` resolves, and in
+   * `<git-common-dir>/info/exclude`, so the checkout's own `git status` never
+   * lists it. Starts from the branch when an earlier run left it, from HEAD
+   * otherwise. A worktree an earlier run left on the branch, here or where
+   * older versions made it under the git directory, is removed first.
    */
   private async makeWorktree(id: string, members: readonly string[]): Promise<{ worktree: string; branch: string }> {
     const cwd = this.opts.cwd;
     const common = await git(["rev-parse", "--git-common-dir"], cwd);
     if (!common.ok) throw new Error(`Op "${this.config.name}" changes the checkout, but ${cwd} is not a git checkout: ${common.stderr}`);
     const commonDir = isAbsolute(common.stdout) ? common.stdout : resolve(cwd, common.stdout);
+    // The top as the caller spells it (git's --show-toplevel resolves symbolic links).
+    const cdup = await git(["rev-parse", "--show-cdup"], cwd);
+    if (!cdup.ok) throw new Error(`Op "${this.config.name}" changes the checkout, but ${cwd} has no working tree: ${cdup.stderr}`);
+    const top = resolve(cwd, cdup.stdout);
     const scope = members.join("/");
     const branch = `${WORK_BRANCH_PREFIX}${scope ? `${scope}/` : ""}${id}`;
-    const worktree = join(commonDir, "chant-work", ...members, id);
-    if (existsSync(worktree)) {
-      await git(["worktree", "remove", "--force", worktree], cwd);
-      rmSync(worktree, { recursive: true, force: true });
+    const worktree = workWorktreePath(top, members, id);
+    const ignored = (await git(["check-ignore", "-q", `${WORK_DIR}/${id}`], top)).ok;
+    excludeWorkDir(commonDir, ignored);
+    for (const stale of await this.staleWorktrees(branch, commonDir, members, id)) {
+      await git(["worktree", "remove", "--force", stale], cwd);
+      rmSync(stale, { recursive: true, force: true });
+    }
+    for (const dir of [worktree, legacyWorkWorktreePath(commonDir, members, id)]) {
+      if (!existsSync(dir)) continue;
+      await git(["worktree", "remove", "--force", dir], cwd);
+      rmSync(dir, { recursive: true, force: true });
     }
     await git(["worktree", "prune"], cwd);
     const exists = (await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd)).ok;
@@ -298,6 +315,28 @@ export class RunWorkLease {
     return { worktree, branch };
   }
 
+  /**
+   * The registered worktrees that have `branch` checked out at a path chant
+   * makes work worktrees at: `.chant/work/[<member>/]<id>` in any checkout,
+   * or `<git-common-dir>/chant-work/[<member>/]<id>` where versions before
+   * #2893 made them. A run that crashed leaves one behind, and `git worktree
+   * add` then refuses the branch as already checked out.
+   */
+  private async staleWorktrees(branch: string, commonDir: string, members: readonly string[], id: string): Promise<string[]> {
+    const list = await git(["worktree", "list", "--porcelain"], this.opts.cwd);
+    if (!list.ok) return [];
+    const tail = [...members, id].join("/");
+    const legacy = legacyWorkWorktreePath(commonDir, members, id).split(sep).join("/");
+    const out: string[] = [];
+    for (const block of list.stdout.split(/\n\s*\n/)) {
+      const path = /^worktree (.+)$/m.exec(block)?.[1];
+      if (!path || !block.split("\n").includes(`branch refs/heads/${branch}`)) continue;
+      const posixPath = path.split(sep).join("/");
+      if (posixPath.endsWith(`/${WORK_DIR}/${tail}`) || posixPath === legacy || posixPath.endsWith(`/${LEGACY_WORK_DIR}/${tail}`)) out.push(path);
+    }
+    return out;
+  }
+
   private lose(why: string): void {
     if (this.lost !== undefined) return;
     this.lost = why;
@@ -408,6 +447,7 @@ export class RunWorkLease {
     if (lease.worktree) {
       await git(["worktree", "remove", "--force", lease.worktree], this.opts.cwd).catch(() => undefined);
       rmSync(lease.worktree, { recursive: true, force: true });
+      removeEmptyWorkDirs(lease.worktree);
       await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
     }
     if (this.lost !== undefined) return base;

package/src/pr-forge-bundle.test.ts

@@ -34,7 +34,7 @@ describe("the pr-forge bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual(["packages/core/src/pr-forge.ts"]);
-    // About 27 KB today.
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(32 * 1024);
+    // About 33 KB today, after the pull request authors (#4000).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(36 * 1024);
   });
 });