@intentius/chant 0.100.0 → 0.102.0

package/src/op/local-executor.ts

@@ -29,6 +29,7 @@ import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
 import type { ResolvedGateApproval } from "./gate-approval";
+import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPointWait, type WaitingPoint } from "./steward-points";
 import { isGateWait } from "./gate-wait";
@@ -416,9 +417,11 @@ async function runStep(
       if (step.id) resultsById.set(step.id, result);
       const record: StepRecord = { ...base, status: "ok", durationMs: Date.now() - start };
       const attrs = outcomeAttributesOf(step);
-      if (attrs.length > 0) {
-        record.outcomes = attrs.map((a) => ({ name: a.name, value: resolvePath(result, a.from) }));
-        record.outcome = record.outcomes[0];
+      // An attribute whose path the result does not hold is left off, rather than recorded as undefined.
+      const outcomes = attrs.map((a) => ({ name: a.name, value: resolvePath(result, a.from) })).filter((o) => o.value !== undefined);
+      if (outcomes.length > 0) {
+        record.outcomes = outcomes;
+        record.outcome = outcomes[0];
       }
       return { record, result };
     } catch (err) {
@@ -482,6 +485,8 @@ interface GateContext {
   runId?: string;
   /** Called once per settled step, in production order (#2121) — what `--progress-json` streams from. */
   onRecord?: (record: StepRecord) => void;
+  /** The run context's list of passed gates (#2522). A gate that passes is appended here. */
+  passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
 }
@@ -643,6 +648,17 @@ async function runGateStep(
 
   if (check.satisfied) {
     const { resolution } = check;
+    const passedApproval: NonNullable<StepRecord["approval"]> = {
+      gate: gateName(step),
+      resolvedBy: resolution.resolvedBy,
+      timestamp: resolution.timestamp,
+      ...(resolution.url ? { url: resolution.url } : {}),
+      ...(check.via ? { via: check.via } : {}),
+      ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
+    };
+    // #2522: a later step reads this gate's approval from the run context
+    // rather than re-tallying the ledger, so it sees the decision this run made.
+    gates.passed?.push({ gate: gateName(step), approval: passedApproval });
     return {
       record: {
         phase: phaseName,
@@ -650,14 +666,7 @@ async function runGateStep(
         args: {},
         status: "ok",
         durationMs: Date.now() - start,
-        approval: {
-          gate: gateName(step),
-          resolvedBy: resolution.resolvedBy,
-          timestamp: resolution.timestamp,
-          ...(resolution.url ? { url: resolution.url } : {}),
-          ...(check.via ? { via: check.via } : {}),
-          ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
-        },
+        approval: passedApproval,
       },
     };
   }
@@ -971,6 +980,12 @@ export interface RunOpOptions {
   now?: string;
   /** Identifies this run on any pending fact it records. */
   runId?: string;
+  /**
+   * The environment the run was started for (`--env`, #2522). The executor
+   * only hands it to activities through the run context (`./run-context.ts`).
+   * The run ledger path still comes from the Op's `labels.Env`.
+   */
+  env?: string;
   /**
    * Called once per settled step, in the order the records are produced
    * (#2121) — what the local op runtime (./runtimes/local.ts) feeds
@@ -1039,6 +1054,13 @@ export async function runOpLocally(
   const turn = currentStewardTurn();
   const steward = options.steward ?? turn?.steward;
   const restore = turn && turn.run !== runId ? enterStewardTurn({ ...turn, run: runId }) : undefined;
+  // #2522: every activity in this run can read the run it is in.
+  const run: OpRunContext = {
+    op: config.name,
+    runId,
+    ...(options.env !== undefined ? { env: options.env } : {}),
+    passedGates: [],
+  };
   // A run that writes to the ledger also says what it is doing while it runs
   // (./run-live.ts), and removes that once its record is written.
   const live = options.ledger
@@ -1052,7 +1074,11 @@ export async function runOpLocally(
       })
     : undefined;
   try {
-    return await withLiveRun(live, () => runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }));
+    return await withLiveRun(live, () =>
+      withOpRunContext(run, () =>
+        runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }, run),
+      ),
+    );
   } finally {
     live?.close();
     restore?.();
@@ -1065,6 +1091,7 @@ async function runOpInTurn(
   profiles: Record<string, ActivityProfile>,
   signal: AbortSignal | undefined,
   options: RunOpOptions & { runId: string },
+  run: OpRunContext,
 ): Promise<OpRunResult> {
   const runId = options.runId;
 
@@ -1074,6 +1101,7 @@ async function runOpInTurn(
     ...(options.now ? { now: options.now } : {}),
     runId,
     ...(options.onRecord ? { onRecord: options.onRecord } : {}),
+    passed: run.passedGates,
   };
 
   // Effect steps are ordered (read-compare-run-write): refuse them in a

package/src/op/local-output.ts

@@ -66,7 +66,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
       : work.released
         ? `released ${work.outcome}`
         : "not released; it runs out on its own";
-    write(`[work] ${work.item} held by ${work.holder}${work.branch ? ` on ${work.branch}` : ""}: ${end}`);
+    write(`[work] ${work.item} held by ${work.holder}${work.branch ? ` on ${work.branch}` : ""}: ${end}${work.kept ? `; the attempt is kept at ${work.kept}` : ""}`);
   } else if (work?.refusal) {
     write(`[work] nothing claimed: ${work.refusal}`);
   }

package/src/op/operator.ts

@@ -577,6 +577,10 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     try {
       const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
         runId,
+        // #2522: the environment the operator was started for (`--env`, or a
+        // steward's environment) reaches the activities through the run
+        // context, as `chant run --env` does.
+        ...(opts.env ?? opts.stewardEnv ? { env: opts.env ?? opts.stewardEnv } : {}),
         ...(steward ? { steward: steward.name } : {}),
         ledger: { cwd: opts.cwd },
         // A steward's turn claims work leases as `<steward>/<op>@<holder>`

package/src/op/run-context.test.ts

@@ -0,0 +1,141 @@
+/**
+ * The run context an activity reads (#2522): the Op, the run id the run
+ * ledger records, `--env`, and the gates the run has passed.
+ */
+import { describe, test, expect } from "vitest";
+import type { OpConfig } from "./types";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import { runOpLocally } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { currentOpRun, type OpRunContext } from "./run-context";
+import { gatePolicyVersion, type GatePolicyRef, type ResolvedGateApproval } from "./gate-approval";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
+};
+const NOW = "2026-09-05T12:00:00.000Z";
+
+function op(steps: OpConfig["phases"][number]["steps"]): OpConfig {
+  return { name: "release", overview: "", phases: [{ name: "main", steps }] };
+}
+
+describe("the Op run context (#2522)", () => {
+  test("an activity reads the Op, the run id and --env", async () => {
+    let seen: OpRunContext | undefined;
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => { await Promise.resolve(); seen = currentOpRun(); }],
+    ]);
+    const result = await runOpLocally(op([{ kind: "activity", fn: "deploy" }]), activities, PROFILES, undefined, {
+      runId: "local-123",
+      env: "staging",
+    });
+    expect(seen).toEqual({ op: "release", runId: "local-123", env: "staging", passedGates: [] });
+    expect(result.record?.id).toBe("local-123");
+  });
+
+  test("without --env the context carries none, and outside a run there is no context", async () => {
+    let seen: OpRunContext | undefined;
+    const activities = new Map<string, ActivityFn>([["deploy", async () => { seen = currentOpRun(); }]]);
+    await runOpLocally(op([{ kind: "activity", fn: "deploy" }]), activities, PROFILES, undefined, { runId: "r1" });
+    expect(seen).toEqual({ op: "release", runId: "r1", passedGates: [] });
+    expect(currentOpRun()).toBeUndefined();
+  });
+
+  test("a step after a passed gate reads the gate's approval", async () => {
+    const seen: OpRunContext[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["plan", async () => { seen.push(currentOpRun()!); }],
+      ["apply", async () => { seen.push(currentOpRun()!); }],
+    ]);
+    const port = memoryGateLedgerPort({
+      pending: [{
+        version: 1, kind: "pending", op: "release", gate: "ship",
+        timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z",
+      }],
+      resolutions: [{ version: 1, op: "release", gate: "ship", resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z" }],
+    });
+    const result = await runOpLocally(
+      op([
+        { kind: "activity", fn: "plan" },
+        { kind: "gate", gate: "ship" },
+        { kind: "activity", fn: "apply" },
+      ]),
+      activities,
+      PROFILES,
+      undefined,
+      { gates: port, now: NOW, runId: "r2" },
+    );
+    expect(result.status).toBe("ok");
+    expect(seen[0]!.passedGates).toEqual([]);
+    expect(seen[1]!.passedGates).toEqual([
+      { gate: "ship", approval: { gate: "ship", resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z" } },
+    ]);
+    expect(seen[1]!.passedGates[0]!.approval).toEqual(result.records.find((r) => r.fn === "gate:ship")?.approval);
+  });
+
+  describe("a policy permit and the gates a run passed (#2512)", () => {
+    const TEXT = 'permit (principal is Chant::Agent, action, resource) when { context.risk == "low" };\n';
+    const POLICY: GatePolicyRef = { kind: "gate-policy", lexicon: "cedar", name: "ship", version: gatePolicyVersion(TEXT), text: TEXT };
+    const enforce: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
+    const permit = (mode: "log-only" | "enforce"): GateResolutionRecord => ({
+      version: 1, op: "release", gate: "ship", resolvedBy: "release-bot", timestamp: "2026-09-05T11:00:00.000Z",
+      approver: { kind: "agent" },
+      policyDecision: { policy: "ship", version: POLICY.version, mode, decision: "allow", determining: ["ship-0"], errors: [] },
+    });
+
+    async function run(mode: "log-only" | "enforce") {
+      const seen: OpRunContext[] = [];
+      const activities = new Map<string, ActivityFn>([["apply", async () => { seen.push(currentOpRun()!); }]]);
+      const port = memoryGateLedgerPort({
+        pending: [{
+          version: 1, kind: "pending", op: "release", gate: "ship",
+          timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z",
+          approval: { ...enforce, mode },
+        }],
+        resolutions: [permit(mode)],
+      });
+      const result = await runOpLocally(
+        op([
+          { kind: "gate", gate: "ship", approval: { policy: POLICY, mode: "enforce" } },
+          { kind: "activity", fn: "apply" },
+        ]),
+        activities,
+        PROFILES,
+        undefined,
+        { gates: port, now: NOW, runId: "r3" },
+      );
+      return { result, seen };
+    }
+
+    test("an enforce-mode permit passes the gate, and the next step sees it as passed by policy", async () => {
+      const { result, seen } = await run("enforce");
+      expect(result.status).toBe("ok");
+      expect(seen[0]!.passedGates.map((g) => [g.gate, g.approval.via])).toEqual([["ship", "policy"]]);
+    });
+
+    test("a permit recorded under log-only does not pass the enforced gate, so no step sees it as passed", async () => {
+      const { result, seen } = await run("log-only");
+      expect(result.status).toBe("gated");
+      expect(seen).toEqual([]);
+      expect(result.records.find((r) => r.fn === "gate:ship")?.approval).toBeUndefined();
+    });
+  });
+
+  test("two runs in flight at once each see their own context", async () => {
+    const seen = new Map<string, string | undefined>();
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        const ctx = currentOpRun()!;
+        seen.set(ctx.runId, ctx.env);
+      }],
+    ]);
+    const config = op([{ kind: "activity", fn: "deploy" }]);
+    await Promise.all([
+      runOpLocally(config, activities, PROFILES, undefined, { runId: "a", env: "staging" }),
+      runOpLocally(config, activities, PROFILES, undefined, { runId: "b", env: "prod" }),
+    ]);
+    expect(Object.fromEntries(seen)).toEqual({ a: "staging", b: "prod" });
+  });
+});

package/src/op/run-context.ts

@@ -0,0 +1,51 @@
+/**
+ * The run an activity is part of (#2522).
+ *
+ * An activity is called as `fn(args, signal)`, which says nothing about the
+ * run around it. An activity that deploys somewhere needs the environment the
+ * run was asked for, one that appends a ledger record of its own needs the run
+ * id to name the run that made it, and a step after a gate may need to know the
+ * gate passed and who approved it.
+ *
+ * `runOpLocally` (`./local-executor.ts`) sets this for the whole run, and
+ * {@link currentOpRun} reads it from inside an activity. It is backed by
+ * `AsyncLocalStorage`, so it follows the activity through every `await` and is
+ * `undefined` outside a run.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { StepRecord } from "./local-executor";
+
+/** A gate this run has passed, with the approval that passed it. */
+export interface PassedGate {
+  gate: string;
+  approval: NonNullable<StepRecord["approval"]>;
+}
+
+/** What an activity can read about the run it is in. */
+export interface OpRunContext {
+  /** The Op's name. */
+  op: string;
+  /** The run id the run ledger record carries. */
+  runId: string;
+  /** `--env`, as handed to `OpRuntimeProvider.start`. Absent when the run was started without one. */
+  env?: string;
+  /** Every gate this run has passed so far, in the order it passed them. */
+  passedGates: PassedGate[];
+}
+
+const store = new AsyncLocalStorage<OpRunContext>();
+
+/**
+ * The run the calling activity is part of, or `undefined` outside a run.
+ * `passedGates` is a copy taken at the time of the call.
+ */
+export function currentOpRun(): OpRunContext | undefined {
+  const ctx = store.getStore();
+  return ctx ? { ...ctx, passedGates: [...ctx.passedGates] } : undefined;
+}
+
+/** Run `fn` with `ctx` as the current run. The executor calls this. A runtime that calls activities itself can too. */
+export function withOpRunContext<T>(ctx: OpRunContext, fn: () => T): T {
+  return store.run(ctx, fn);
+}

package/src/op/runtimes/local.test.ts

@@ -81,6 +81,20 @@ describe("the local op runtime", () => {
     expect(status.records?.map((r) => r.fn)).toEqual(["ok"]);
   });
 
+  test("an activity reads --env and the run id the ledger records (#2522)", async () => {
+    const { currentOpRun } = await import("../run-context");
+    let seen: ReturnType<typeof currentOpRun>;
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => { seen = currentOpRun(); })]]));
+    const runtime = createLocalOpRuntime();
+
+    const handle = await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), { env: "staging" });
+    const status = await handle.result();
+
+    expect(seen?.env).toBe("staging");
+    expect(seen?.runId).toBe(handle.runId);
+    expect(status.result?.record?.id).toBe(handle.runId);
+  });
+
   test("the project's configured lexicons decide which appliers load", async () => {
     loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
     const runtime = createLocalOpRuntime();

package/src/op/runtimes/local.ts

@@ -152,6 +152,8 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
             startOpts.signal,
             {
               runId,
+              // #2522: `--env` reaches the activities through the run context.
+              ...(startOpts.env !== undefined ? { env: startOpts.env } : {}),
               // The run's outcome is a durable fact (#2118): the executor
               // appends it here, at the one seam every local run passes
               // through, rather than in the CLI handler above it.

package/src/op/steward-beside.ts

@@ -118,6 +118,8 @@ export function inProcessBesideLauncher(
       try {
         const result = await runOpLocally(start.op, activities, profiles, controller.signal, {
           steward: start.steward,
+          // #2522: the same `--env` the spawned launcher passes on the command line.
+          ...(start.env ? { env: start.env } : {}),
           ledger: { cwd: start.cwd },
           work: { holder: start.holder },
         });

package/src/op/types.ts

@@ -91,8 +91,12 @@ export interface OpWorkLease {
   ttl?: string;
   /**
    * How the release records a run that ended `ok`: a reference to a step
-   * output holding a short string (`done`, `not_done`, ...). Default `done`;
-   * a failed run releases `not_done` and a gated one `gated`.
+   * output holding one of the closed list of lease outcomes
+   * (`WORK_LEASE_OUTCOMES` in `../lifecycle/work-lease.ts`, #3147: `done`,
+   * `not_done`, `abandoned`, `gated`, `waiting`, `dropped`, `redraft`,
+   * `ask`). Default `done`; a failed run releases `not_done`, a gated one
+   * `gated` and one waiting on a decision point `waiting`. A word outside
+   * the list is released `not_done`, with a note naming it.
    */
   outcome?: StepOutputRef;
 }
@@ -178,7 +182,8 @@ export interface ActivityStep {
    *
    * `from` is a dot-path into the return value (e.g. `"drifted"` for
    * `{ drifted: boolean }`); when omitted, the whole return value is
-   * recorded.
+   * recorded. An attribute whose path the result does not hold (an optional
+   * field left out) is not recorded, rather than recorded as `undefined`.
    */
   outcomeAttribute?: OutcomeAttribute | OutcomeAttribute[];
 }

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

@@ -342,4 +342,51 @@ describe("an Op that changes the checkout", () => {
       expect(git(["status", "--porcelain"], dir).stdout).toBe(" M app/index.ts\n");
     });
   });
+
+  test("a run that ends not_done keeps its attempt at refs/chant/kept/<item>/<token>, committed and uncommitted work, and the branch goes back (#3147)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = git(["rev-parse", "HEAD"], dir).stdout.trim();
+      const activities = new Map<string, ActivityFn>([
+        [
+          "build",
+          async (args) => {
+            const worktree = String(args.worktree);
+            writeFileSync(join(worktree, "app", "feature.ts"), "export const feature = true;\n");
+            expect(git(["add", "-A"], worktree).status).toBe(0);
+            expect(git(["commit", "-q", "-m", "half a build"], worktree).status).toBe(0);
+            writeFileSync(join(worktree, "app", "notes.md"), "left uncommitted\n");
+            throw new Error("the check fails");
+          },
+        ],
+      ]);
+      const result = await run(dispatchOp({ workLease: { item: "W-8" }, changesCheckout: true }, [step("build", { worktree: workLeaseOutput("worktree") })]), activities, dir);
+      expect(result.status).toBe("fail");
+      const token = result.workLease!.token!;
+      const kept = `refs/chant/kept/W-8/${token}`;
+      expect(result.workLease).toMatchObject({ item: "W-8", released: true, outcome: "not_done", kept });
+      // Both the commit and the uncommitted file are in the kept attempt; the branch is where the run started.
+      expect(git(["show", `${kept}:app/feature.ts`], dir).stdout).toBe("export const feature = true;\n");
+      expect(git(["show", `${kept}:app/notes.md`], dir).stdout).toBe("left uncommitted\n");
+      expect(git(["rev-parse", "chant/work/W-8"], dir).stdout.trim()).toBe(head);
+      expect(git(["rev-parse", "HEAD"], dir).stdout.trim()).toBe(head);
+    });
+  });
+
+  test("a run whose step names a lease outcome releases it, and keeps nothing when it changed nothing; a word outside the list is not_done (#3147)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      let word = "dropped";
+      const activities = new Map<string, ActivityFn>([["record", async () => ({ outcome: word })]]);
+      const op = () => dispatchOp({ workLease: { item: "W-9", outcome: stepOutput("record", "outcome") }, changesCheckout: true }, [step("record", {}, { id: "record" })]);
+      const dropped = await run(op(), activities, dir);
+      expect(dropped.workLease).toMatchObject({ released: true, outcome: "dropped", kept: null });
+      word = "skipped";
+      const other = await run(op(), activities, dir);
+      expect(other.workLease).toMatchObject({ released: true, outcome: "not_done", kept: null });
+      const last = (await readLeaseHistory("W-9", { cwd: dir })).records.at(-1);
+      expect(last).toMatchObject({ event: "release", outcome: "not_done" });
+      expect(last?.note).toMatch(/"skipped" is not a work lease outcome/);
+    });
+  });
 });

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

@@ -24,9 +24,11 @@
  *   the lease is still this run's, with the same token. Refused, the run is
  *   recorded as failed with `lease-lost`, never as done.
  * - Release. When the run ends, the lease is given back with the run's
- *   outcome (`done`, `not_done`, `gated`, or the Op's own `outcome`), which
- *   lands on `_leases/<id>.jsonl`. A lost lease is not released: it isn't
- *   this run's to give back.
+ *   outcome (`done`, `not_done`, `gated`, `waiting`, or the Op's own
+ *   `outcome`), which lands on `_leases/<id>.jsonl`. Outcomes are a closed
+ *   list (`WORK_LEASE_OUTCOMES`, #3147): an Op's own outcome outside it is
+ *   released `not_done`, with a note naming it. A lost lease is not
+ *   released: it isn't this run's to give back.
  *
  * Steps read the lease through {@link workLeaseOutput}: its item, holder,
  * token and expiry, and for an Op that changes the checkout, the worktree and
@@ -42,6 +44,13 @@
  * 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
+ * steps committed on the branch since the run started, and anything they
+ * left uncommitted in the worktree, is committed to
+ * `refs/chant/kept/[<member>/]<item>/<token>`, and the branch goes back to
+ * where the run started. The next attempt starts clean, and the earlier one
+ * stays readable by its lease token (`chant workspace work history`).
  */
 
 import { existsSync, rmSync } from "node:fs";
@@ -50,6 +59,8 @@ import { getRuntime } from "../runtime-adapter";
 import {
   claimWorkLease,
   DEFAULT_WORK_LEASE_TTL_MS,
+  isWorkLeaseOutcome,
+  keptAttemptRef,
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
@@ -97,8 +108,10 @@ export interface WorkLeaseRunResult {
   branch: string | null;
   /** Whether the lease was given back. False when it was lost, or never claimed. */
   released: boolean;
-  /** The outcome the release recorded, or null when there was no release. */
+  /** The outcome the release recorded, one of `WORK_LEASE_OUTCOMES`, or null when there was no release. */
   outcome: string | null;
+  /** For an Op that changes the checkout and ended `not_done`: the ref that keeps the attempt's work, or null when there was nothing to keep. */
+  kept: string | null;
   /** Why the lease was lost, or null when it wasn't. */
   lost: string | null;
   /** Why nothing was claimed, or null when something was. */
@@ -159,6 +172,8 @@ export class RunWorkLease {
   attempted = false;
   lease: WorkLeaseOutput | undefined;
   refusal: string | undefined;
+  /** For an Op that changes the checkout: the branch's commit when the run started, and the members its branch is scoped by. */
+  private start: { base: string; members: readonly string[] } | undefined;
   lost: string | undefined;
 
   private readonly spec: NonNullable<OpConfig["workLease"]>;
@@ -277,6 +292,8 @@ export class RunWorkLease {
       ? await git(["worktree", "add", "--quiet", worktree, branch], cwd)
       : await git(["worktree", "add", "--quiet", "-b", branch, worktree, "HEAD"], cwd);
     if (!add.ok) throw new Error(`Op "${this.config.name}": could not make the worktree for ${id} on ${branch}: ${add.stderr}`);
+    const base = await git(["rev-parse", "HEAD"], worktree);
+    if (base.ok) this.start = { base: base.stdout, members };
     return { worktree, branch };
   }
 
@@ -365,28 +382,73 @@ export class RunWorkLease {
       branch: lease?.branch ?? null,
       released: false,
       outcome: null,
+      kept: null,
       lost: this.lost ?? null,
       refusal: this.refusal ?? null,
     };
     if (!lease) return base;
+    let outcome = status === "ok" ? "done" : status === "gated" || status === "waiting" ? status : "not_done";
+    let note = `op ${this.config.name}`;
+    if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
+      const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
+      if (typeof declared === "string" && declared.trim() !== "") {
+        const word = declared.trim();
+        if (isWorkLeaseOutcome(word)) outcome = word;
+        else {
+          outcome = "not_done";
+          note = `op ${this.config.name}: its outcome ${JSON.stringify(word.slice(0, 80))} is not a work lease outcome`;
+        }
+      }
+    }
+    let kept: string | null = null;
+    if (lease.worktree && this.lost === undefined && outcome === "not_done") {
+      kept = await this.keepAttempt(lease).catch(() => null);
+    }
     if (lease.worktree) {
       await git(["worktree", "remove", "--force", lease.worktree], this.opts.cwd).catch(() => undefined);
       rmSync(lease.worktree, { recursive: true, force: true });
       await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
     }
     if (this.lost !== undefined) return base;
-    let outcome = status === "ok" ? "done" : status === "gated" || status === "waiting" ? status : "not_done";
-    if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
-      const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
-      if (typeof declared === "string" && declared.trim() !== "") outcome = declared.trim();
-    }
     const released = await releaseWorkLease(lease.item, this.holder, {
       cwd: this.ledgerCwd,
       token: lease.token,
       outcome,
-      note: `op ${this.config.name}`,
+      note,
     }).catch(() => undefined);
-    return { ...base, released: released?.ok === true, outcome: released?.ok ? outcome : null };
+    return { ...base, kept, released: released?.ok === true, outcome: released?.ok ? outcome : null };
+  }
+
+  /**
+   * Keep a `not_done` attempt aside (#3147): commit what the steps left in
+   * the worktree, committed or not, at `refs/chant/kept/.../<item>/<token>`,
+   * and move the branch back to where the run started. Returns the ref, or
+   * null when the attempt changed nothing.
+   */
+  private async keepAttempt(lease: WorkLeaseOutput): Promise<string | null> {
+    const dir = lease.worktree;
+    const start = this.start;
+    if (!dir || !start) return null;
+    const head = await git(["rev-parse", "HEAD"], dir);
+    if (!head.ok) return null;
+    if (!(await git(["add", "-A"], dir)).ok) return null;
+    const tree = await git(["write-tree"], dir);
+    const headTree = await git(["rev-parse", `${head.stdout}^{tree}`], dir);
+    if (!tree.ok || !headTree.ok) return null;
+    let commit = head.stdout;
+    if (tree.stdout !== headTree.stdout) {
+      // An identity only when git has none, so a configured one is kept.
+      const ident = (await git(["var", "GIT_COMMITTER_IDENT"], dir)).ok && (await git(["var", "GIT_AUTHOR_IDENT"], dir)).ok;
+      const who = ident ? [] : ["-c", "user.name=chant", "-c", "user.email=chant@localhost"];
+      const made = await git([...who, "commit-tree", tree.stdout, "-p", head.stdout, "-m", `${lease.item}: not done, kept (lease ${lease.token})`], dir);
+      if (!made.ok) return null;
+      commit = made.stdout;
+    }
+    if (commit === start.base) return null;
+    const ref = keptAttemptRef(lease.item, lease.token, start.members);
+    if (!(await git(["update-ref", ref, commit], dir)).ok) return null;
+    await git(["reset", "-q", "--hard", start.base], dir);
+    return ref;
   }
 }
 

package/src/provenance.ts

@@ -177,6 +177,41 @@ export function originOfPath(
   return best === undefined ? undefined : paths[best];
 }
 
+const INTERPOLATION_FIELDS = Symbol.for("chant.interpolationFields");
+
+/**
+ * For an entity a tagged template built: which of its `props` paths each
+ * interpolation fed, by interpolation index (chant #3212). Element `i` lists
+ * the paths the `i`-th `${...}` landed in, in {@link EntityProvenance.paths}'
+ * grammar (dotted names, no array segments). An interpolation that fed no
+ * field the author typed, such as a reference to another entity, lists none.
+ *
+ * Only the tag can say this. It is the tag that parsed the text, so a
+ * `${props.ttlDays}` inside `TTL ts + INTERVAL ${props.ttlDays} DAY` is known
+ * to have fed `ttl` only there. When a composite factory interpreted at fold
+ * time writes the template, `discovery/fold-import.ts` joins these paths with
+ * the factory parameters each interpolation reads, which is what lets drift on
+ * such a field be reported against the parameter. A tag that never calls this
+ * leaves its fields `unknown`, the honest answer, rather than claiming either.
+ *
+ * Stored like provenance itself: non-enumerable and symbol-keyed, so no
+ * serializer, spread or comparison of the output ever sees it.
+ */
+export function setInterpolationFields(entity: object, fields: ReadonlyArray<readonly string[]>): void {
+  if (!Object.isExtensible(entity)) return;
+  Object.defineProperty(entity, INTERPOLATION_FIELDS, {
+    value: Object.freeze(fields.map((paths) => Object.freeze([...paths]))),
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** What {@link setInterpolationFields} recorded on an entity, if anything. */
+export function getInterpolationFields(entity: object): ReadonlyArray<readonly string[]> | undefined {
+  return (entity as Record<symbol, unknown>)[INTERPOLATION_FIELDS] as ReadonlyArray<readonly string[]> | undefined;
+}
+
 /** One-line rendering of an origin, for diff output. */
 export function describePathOrigin(origin: PathOrigin): string {
   switch (origin.kind) {