@intentius/chant 0.90.0 → 0.91.0

package/src/op/discover.ts

@@ -5,6 +5,7 @@ import type { OpConfig } from "./types";
 import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
 import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
+import { isStewardDeclaration, type StewardDeclaration } from "./steward";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -152,6 +153,9 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
       const mod = (await import(filePath)) as Record<string, unknown>;
       const exported = opsExportedBy(mod);
 
+      // A file may hold a steward and no Op (#2731): the steward sits beside
+      // the Ops it runs, and `discoverStewards` reads it from here.
+      if (exported.length === 0 && Object.values(mod).some(isStewardDeclaration)) continue;
       if (exported.length === 0) {
         errors.push(
           `${filePath}: exports no Op. Expected \`export default Op({...})\` or a named export such as \`export const deploy = Op({...})\``,
@@ -180,3 +184,70 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   return { ops, errors };
 }
+
+export interface DiscoveredSteward {
+  declaration: StewardDeclaration;
+  filePath: string;
+  exportName: string;
+}
+
+export interface StewardDiscoveryResult {
+  stewards: Map<string, DiscoveredSteward>;
+  /** Files that could not be imported. */
+  errors: string[];
+  /** Stewards dropped because they would be a second writer: a name or an Op another steward already has. */
+  conflicts: string[];
+}
+
+/**
+ * Every steward declared in the project's `*.op.ts` files (#2731), found the
+ * way {@link discoverOps} finds Ops, keyed by the steward's name.
+ *
+ * Refuses, as errors, the two ways a project could end up with two writers:
+ * two stewards of one name, and one Op listed by two stewards. The steward
+ * declared first (in file walk order) keeps its entry; the other is dropped
+ * and reported in `conflicts`.
+ */
+export async function discoverStewards(opts?: { cwd?: string }): Promise<StewardDiscoveryResult> {
+  const errors: string[] = [];
+  const conflicts: string[] = [];
+  const stewards = new Map<string, DiscoveredSteward>();
+  const opOwner = new Map<string, string>();
+
+  const root = await findDiscoveryRoot(opts?.cwd);
+  const files = await collectOpFiles(root);
+
+  for (const filePath of files) {
+    let mod: Record<string, unknown>;
+    try {
+      mod = (await import(filePath)) as Record<string, unknown>;
+    } catch (err) {
+      errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    const seen = new Set<unknown>();
+    const exportNames = ["default", ...Object.keys(mod).filter((k) => k !== "default")];
+    for (const exportName of exportNames) {
+      const value = mod[exportName];
+      if (!isStewardDeclaration(value) || seen.has(value)) continue;
+      seen.add(value);
+      const prior = stewards.get(value.name);
+      if (prior) {
+        conflicts.push(`Duplicate steward "${value.name}" in ${filePath} and ${prior.filePath}`);
+        continue;
+      }
+      const claimed = value.ops.find((op) => opOwner.has(op.name));
+      if (claimed) {
+        conflicts.push(
+          `${filePath}: steward "${value.name}" lists op "${claimed.name}", which steward "${opOwner.get(claimed.name)}" already runs. ` +
+            `Two stewards running one Op are two writers; list it on one of them.`,
+        );
+        continue;
+      }
+      for (const op of value.ops) opOwner.set(op.name, value.name);
+      stewards.set(value.name, { declaration: value, filePath, exportName });
+    }
+  }
+
+  return { stewards, errors, conflicts };
+}

package/src/op/index.ts

@@ -15,8 +15,12 @@ export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-life
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
-export type { OpConfig, OpSchedule, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
-export { outcomeAttributesOf } from "./types";
+export type { OpConfig, OpSchedule, OpWorkLease, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
+export { outcomeAttributesOf, WORK_LEASE_STEP_ID } from "./types";
+export {
+  RunWorkLease, workLeaseOutput, stewardWorkHolder, workLeaseProblems, workLeaseNeedsRunItem, LEASE_LOST, WORK_BRANCH_PREFIX,
+} from "./work-lease-run";
+export type { WorkLeaseOutput, WorkLeaseRunResult, WorkClaimOutcome, RunWorkLeaseOptions } from "./work-lease-run";
 export { isValidCronExpression, cronSyntaxMessage, cronMatches, cronDueBetween } from "./cron";
 export {
   WatchOp, ReconcileOp, ApplyOp, ConvergeOp,
@@ -100,8 +104,17 @@ export type {
 } from "./converge-rule";
 export {
   discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
-  formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS,
+  formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS, acquireStewardLease,
 } from "./operator";
+export {
+  declareSteward, isStewardDeclaration, stewardFormFor, stewardOpConfig, normaliseStewardForm, stewardLeaseName,
+  STEWARD_KIND, STEWARD_FORMS, STEWARD_NAME_PATTERN, DEFAULT_STEWARD_ENV,
+} from "./steward";
+export type {
+  StewardDeclaration, StewardDeclarationConfig, StewardForm, StewardFormSpec, StewardOpInput,
+} from "./steward";
+export { discoverStewards } from "./discover";
+export type { DiscoveredSteward, StewardDiscoveryResult } from "./discover";
 export type {
   OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions,
   ChangeSubscriber, OperatorSignalEvent,

package/src/op/lifecycle-receipt-store.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { lifecycleReceiptFile, lifecycleReceiptStore } from "./lifecycle-receipt-store";
+import { receiptActivities, type EffectReceiptRef } from "./receipt-store";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+function initRepo(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+const RECEIPT: EffectReceiptRef = { name: "fly-migration:shop/001_init.sql", effect: "fly-migrate", flavor: "hash", inputs: {} };
+
+describe("lifecycleReceiptStore", () => {
+  test("a receipt is absent, then written under <env>/receipts on chant/lifecycle", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const store = lifecycleReceiptStore({ environment: "prod", cwd: dir });
+      expect(await store.read(RECEIPT)).toBeUndefined();
+      await store.write(RECEIPT, "sha256:abc");
+      expect(await store.read(RECEIPT)).toBe("sha256:abc");
+      const shown = git(["show", `chant/lifecycle:prod/${lifecycleReceiptFile(RECEIPT.name)}`], dir);
+      expect(shown.exitCode).toBe(0);
+      expect(shown.stdout.trim()).toBe("sha256:abc");
+      // Another environment has its own receipts.
+      expect(await lifecycleReceiptStore({ environment: "dev", cwd: dir }).read(RECEIPT)).toBeUndefined();
+    });
+  });
+
+  test("bound to core's receipt activities, the effect step's read-compare-write goes through it", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const acts = receiptActivities(lifecycleReceiptStore({ environment: "prod", cwd: dir }));
+      const first = await acts.receiptRead({ receipt: RECEIPT, expectation: "sha256:1" });
+      expect(first).toEqual({ current: null, expectation: "sha256:1", applied: false });
+      await acts.receiptWrite({ receipt: RECEIPT, expectation: "sha256:1" });
+      expect((await acts.receiptRead({ receipt: RECEIPT, expectation: "sha256:1" })).applied).toBe(true);
+    });
+  });
+
+  test("with no environment and no CHANT_ENV it refuses rather than guessing", async () => {
+    const store = lifecycleReceiptStore({ env: {} });
+    await expect(store.read(RECEIPT)).rejects.toThrow(/no environment/);
+  });
+
+  test("receipt names become safe file names", () => {
+    expect(lifecycleReceiptFile("fly-migration:app/002 add.sql")).toBe("receipts/fly-migration_app_002_add.sql.receipt");
+  });
+});

package/src/op/lifecycle-receipt-store.ts

@@ -0,0 +1,61 @@
+/**
+ * A receipt store on the `chant/lifecycle` branch (#2736, ws-056).
+ *
+ * The aws and k8s rows keep receipts in the cloud they deploy to (an SSM
+ * parameter, a ConfigMap). A target with no store of its own, such as a Fly
+ * Machine, keeps them next to the release ledger instead: one file per receipt
+ * at `<env>/receipts/<name>.receipt` on the lifecycle branch, written through
+ * the same plumbing as the release and build ledgers (../lifecycle/git.ts), so
+ * a workspace member's receipts land under its own `_members/<member>/` prefix.
+ *
+ * The receipt is per environment, not per checkout: every checkout that
+ * fetches the branch sees which effects have fired there. Writing is local;
+ * the ledger push that follows a recorded release (or `chant lifecycle push`)
+ * carries it to the remote.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "../lifecycle/git";
+import type { EffectReceiptRef, ReceiptStore } from "./receipt-store";
+
+/** Options for {@link lifecycleReceiptStore}. */
+export interface LifecycleReceiptStoreOptions {
+  /** The environment whose ledger directory holds the receipts. Omitted, `CHANT_ENV` answers. */
+  environment?: string;
+  /** The checkout whose lifecycle branch is written. Defaults to the working directory. */
+  cwd?: string;
+  /** Environment record the `CHANT_ENV` fallback reads. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+}
+
+/** The file name a receipt is kept under: its name with anything outside `[A-Za-z0-9_.-]` replaced. */
+export function lifecycleReceiptFile(name: string): string {
+  return `receipts/${name.replace(/[^a-zA-Z0-9_.-]/g, "_")}.receipt`;
+}
+
+/**
+ * A {@link ReceiptStore} over the lifecycle branch. The environment is resolved
+ * at first use, so constructing the store reads nothing; with none given and no
+ * `CHANT_ENV`, a read or write fails rather than guessing a directory.
+ */
+export function lifecycleReceiptStore(options: LifecycleReceiptStoreOptions = {}): ReceiptStore {
+  const environment = (): string => {
+    const env = options.environment ?? (options.env ?? process.env).CHANT_ENV;
+    if (!env) {
+      throw new Error(
+        "lifecycle receipt store: no environment. Receipts are kept per environment on chant/lifecycle; " +
+          "run with --env <name>, set CHANT_ENV, or pass the environment explicitly.",
+      );
+    }
+    return env;
+  };
+  const opts = options.cwd ? { cwd: options.cwd } : undefined;
+  return {
+    async read(receipt: EffectReceiptRef): Promise<string | undefined> {
+      const content = await readBlobFromPath(environment(), lifecycleReceiptFile(receipt.name), opts);
+      return content === null ? undefined : content.trim();
+    },
+    async write(receipt: EffectReceiptRef, expectation: string): Promise<void> {
+      await writeBlobToPath(environment(), lifecycleReceiptFile(receipt.name), `${expectation}\n`, `Receipt ${receipt.name}`, opts);
+    },
+  };
+}

package/src/op/local-executor.ts

@@ -32,6 +32,8 @@ import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger";
 import type { OpRunRecord } from "./runtime";
 import { randomUUID } from "node:crypto";
+import { RunWorkLease, LEASE_LOST, workLeaseProblems, workLeaseNeedsRunItem, type WorkLeaseRunResult } from "./work-lease-run";
+import { WORK_LEASE_STEP_ID } from "./types";
 
 export { parseDuration } from "./duration";
 
@@ -110,6 +112,12 @@ export interface OpRunResult {
    * document.
    */
   record: OpRunRecord;
+  /**
+   * How the run's work lease went, for an Op that declares `workLease`
+   * (#2748): the item it claimed, or why it claimed none, whether the lease
+   * was released and with which outcome, or why it was lost.
+   */
+  workLease?: WorkLeaseRunResult;
 }
 
 // ── Errors ────────────────────────────────────────────────────────────────��─
@@ -165,6 +173,23 @@ class GateStop extends Error {
   }
 }
 
+/**
+ * Internal: a step boundary found the run can't go on under its work lease
+ * (#2748). `lost` false is a claim that found nothing to claim: not a
+ * failure, the run ends `ok` with the rest skipped. `lost` true is a lease
+ * that was lost: the run fails with `lease-lost`.
+ */
+class WorkStop extends Error {
+  constructor(
+    public readonly records: StepRecord[],
+    public readonly phase: string,
+    public readonly lost: boolean,
+  ) {
+    super(lost ? LEASE_LOST : "nothing to claim");
+    this.name = "WorkStop";
+  }
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────��─
 
 const DEFAULT_PROFILE = "fastIdempotent";
@@ -391,6 +416,68 @@ interface GateContext {
   runId?: string;
   /** Called once per settled step, in production order (#2121) — what `--progress-json` streams from. */
   onRecord?: (record: StepRecord) => void;
+  /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
+  work?: RunWorkLease;
+}
+
+/**
+ * The work lease at a step boundary (#2748): claim it when it is due, and
+ * say whether the run can go on. The claim's record is pushed onto `sink`.
+ * Returns `undefined` to go on, `"unclaimed"` when nothing could be claimed,
+ * and `"lost"` when the lease was lost.
+ */
+async function workBoundary(
+  phaseName: string,
+  ctx: GateContext,
+  resultsById: Map<string, unknown>,
+  sink: StepRecord[],
+): Promise<"unclaimed" | "lost" | undefined> {
+  const work = ctx.work;
+  if (!work) return undefined;
+  if (work.due(resultsById)) {
+    const start = Date.now();
+    let claimed: Awaited<ReturnType<RunWorkLease["claim"]>>;
+    try {
+      claimed = await work.claim(resultsById);
+    } catch (err) {
+      pushRecord(sink, ctx, {
+        phase: phaseName,
+        fn: "workLease:claim",
+        args: {},
+        status: "fail",
+        durationMs: Date.now() - start,
+        error: errMessage(err),
+      });
+      throw new PhaseFailure(sink);
+    }
+    if (claimed.kind === "unclaimed") {
+      pushRecord(sink, ctx, {
+        phase: phaseName,
+        fn: "workLease:claim",
+        args: { items: claimed.tried },
+        status: "skipped",
+        durationMs: Date.now() - start,
+        refusal: claimed.refusal,
+        outcome: { name: "WorkItem", value: null },
+        outcomes: [{ name: "WorkItem", value: null }],
+      });
+      return "unclaimed";
+    }
+    resultsById.set(WORK_LEASE_STEP_ID, claimed.lease);
+    pushRecord(sink, ctx, {
+      phase: phaseName,
+      fn: "workLease:claim",
+      args: { items: claimed.tried },
+      status: "ok",
+      durationMs: Date.now() - start,
+      outcome: { name: "WorkItem", value: claimed.lease.item },
+      outcomes: [
+        { name: "WorkItem", value: claimed.lease.item },
+        { name: "WorkLeaseToken", value: claimed.lease.token },
+      ],
+    });
+  }
+  return work.lost !== undefined ? "lost" : undefined;
 }
 
 /** Collect records and hand each to the caller's progress sink in one move. */
@@ -666,6 +753,13 @@ async function runPhase(
     // read of the ledger, not work, and starting activities that a pending
     // gate is about to strand would defeat the point of stopping at it.
     const gateRecords: StepRecord[] = [];
+    const stop = await workBoundary(phase.name, gates, resultsById, gateRecords);
+    if (stop) {
+      for (const skipped of phase.steps) {
+        pushRecord(gateRecords, gates, isGate(skipped) ? skippedRecord(phase.name, gateFn(skipped)) : skippedRecord(phase.name, (skipped as ActivityStep).fn, (skipped as ActivityStep).args));
+      }
+      throw new WorkStop(gateRecords, phase.name, stop === "lost");
+    }
     for (const step of phase.steps.filter(isGate)) {
       const { record, pending, pushed, pushWarning } = await runGateStep(step, phase.name, gates, resultsById);
       pushRecord(gateRecords, gates, record);
@@ -711,6 +805,13 @@ async function runPhase(
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
+    // The work lease (#2748): claimed here when it is due, and checked before
+    // every step, so no step starts once the lease is lost.
+    const stop = await workBoundary(phase.name, gates, resultsById, records);
+    if (stop) {
+      skipRemaining(i);
+      throw new WorkStop(records, phase.name, stop === "lost");
+    }
     if (isGate(step)) {
       const { record, pending, pushed, pushWarning } = await runGateStep(step, phase.name, gates, resultsById);
       pushRecord(records, gates, record);
@@ -789,6 +890,15 @@ export interface RunOpOptions {
    * never promoted into a run failure.
    */
   onLedgerError?: (err: unknown) => void;
+  /**
+   * For an Op that declares `workLease` (#2748): the item this run is for
+   * (`chant run <op> --work <id>`), which takes the place of the Op's own, and
+   * who holds the lease (a steward's turn passes `stewardWorkHolder`).
+   * Defaults: the Op's item, and this process's holder id.
+   */
+  work?: { item?: string; holder?: string };
+  /** Called when a work-lease renewal fails without losing the lease; the next beat retries it. */
+  onWorkLeaseWarning?: (message: string) => void;
 }
 
 /**
@@ -839,6 +949,68 @@ export async function runOpLocally(
     }
   }
 
+  // The work lease (#2748). An Op that changes the checkout without one, or
+  // whose lease names no item and whose run names none, is refused before
+  // anything runs.
+  const workProblems = workLeaseProblems(config);
+  if (workProblems.length > 0) throw new Error(workProblems.join("\n"));
+  if (workLeaseNeedsRunItem(config) && !options.work?.item) {
+    throw new Error(
+      `Op "${config.name}" runs under a work item's lease and names no item: pass one with \`chant run ${config.name} --work <id>\``,
+    );
+  }
+  const work = config.workLease
+    ? new RunWorkLease(config, {
+        cwd: options.ledger?.cwd ?? options.cwd ?? process.cwd(),
+        ...(options.work?.holder ? { holder: options.work.holder } : {}),
+        ...(options.work?.item ? { item: options.work.item } : {}),
+        ...(options.onWorkLeaseWarning ? { onRenewError: options.onWorkLeaseWarning } : {}),
+      })
+    : undefined;
+  if (work) gates.work = work;
+
+  // Steps run under a signal that also fires when the work lease is lost, so
+  // the step in flight stops (chud's dispatcher stopped its agent the same way).
+  let stepSignal = signal;
+  if (work) {
+    const both = new AbortController();
+    const forward = () => both.abort();
+    if (signal?.aborted) both.abort();
+    else signal?.addEventListener("abort", forward, { once: true });
+    work.lostSignal.addEventListener("abort", forward, { once: true });
+    stepSignal = both.signal;
+  }
+
+  /** Release (or not) the work lease once the run's outcome is settled. */
+  const finishWork = async (status: OpRunResult["status"]): Promise<{ workLease?: WorkLeaseRunResult }> =>
+    work ? { workLease: await work.finish(status, resultsById) } : {};
+
+  /** The record a lost lease leaves, naming why. */
+  const lostRecord = (): StepRecord => ({
+    phase: UNATTRIBUTED_PHASE,
+    fn: "workLease:lost",
+    args: {},
+    status: "fail",
+    durationMs: 0,
+    error: `${LEASE_LOST}: ${work?.lost ?? "the lease was lost"}. The run stopped and was not recorded as done.`,
+  });
+
+  const skipLaterPhases = (after: string) => {
+    const stoppedAt = config.phases.findIndex((p) => p.name === after);
+    if (stoppedAt < 0) return;
+    for (const phase of config.phases.slice(stoppedAt + 1)) {
+      for (const step of phase.steps) {
+        records.push(
+          isEffect(step)
+            ? skippedRecord(phase.name, `effect:${step.receipt.name}`)
+            : isGate(step)
+              ? skippedRecord(phase.name, gateFn(step))
+              : skippedRecord(phase.name, step.fn, step.args),
+        );
+      }
+    }
+  };
+
   const records: StepRecord[] = [];
   const start = Date.now();
   const startedAt = options.now ?? new Date(start).toISOString();
@@ -877,25 +1049,35 @@ export async function runOpLocally(
   try {
     for (const phase of config.phases) {
       if (signal?.aborted) throw new PhaseFailure([]);
-      records.push(...(await runPhase(phase, activities, profiles, resultsById, gates, signal)));
+      records.push(...(await runPhase(phase, activities, profiles, resultsById, gates, stepSignal)));
     }
+    // The last renewal before the run is recorded (#2748): a run whose lease
+    // was lost is never recorded as done.
+    if (work && !(await work.fence())) throw new WorkStop([], UNATTRIBUTED_PHASE, true);
   } catch (err) {
+    // Nothing to claim, or every candidate held (#2748): not a failure. The
+    // rest of the run is skipped and the claim's record says why.
+    if (err instanceof WorkStop && !err.lost) {
+      records.push(...err.records);
+      skipLaterPhases(err.phase);
+      const record = await settle(records, "ok");
+      return {
+        op: config.name,
+        records,
+        totalMs: Date.now() - start,
+        status: "ok",
+        startedAt,
+        record,
+        ...(await finishWork("ok")),
+      };
+    }
+
     // A pending gate ends the run where it stands: no later phase, and no
     // `onFailure` compensation — nothing failed, so there is nothing to undo.
     if (err instanceof GateStop) {
       records.push(...err.records);
-      const stoppedAt = config.phases.findIndex((p) => p.name === err.phase);
-      for (const phase of config.phases.slice(stoppedAt + 1)) {
-        for (const step of phase.steps) {
-          records.push(
-            isEffect(step)
-              ? skippedRecord(phase.name, `effect:${step.receipt.name}`)
-              : isGate(step)
-                ? skippedRecord(phase.name, gateFn(step))
-                : skippedRecord(phase.name, step.fn, step.args),
-          );
-        }
-      }
+      skipLaterPhases(err.phase);
+      const record = await settle(records, "gated", err.pending);
       return {
         op: config.name,
         records,
@@ -905,11 +1087,17 @@ export async function runOpLocally(
         gate: err.pending,
         ...(err.pushed !== undefined ? { gatePushed: err.pushed } : {}),
         ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
-        record: await settle(records, "gated", err.pending),
+        record,
+        ...(await finishWork("gated")),
       };
     }
 
-    if (err instanceof PhaseFailure) {
+    if (err instanceof WorkStop) {
+      // The lease was lost (#2748): the rest is skipped, and the lost record
+      // below says why.
+      records.push(...err.records);
+      skipLaterPhases(err.phase);
+    } else if (err instanceof PhaseFailure) {
       records.push(...err.records);
     } else {
       // Everything else the phase loop can throw (#2301). `PhaseFailure` and
@@ -934,12 +1122,18 @@ export async function runOpLocally(
       });
     }
 
+    // A step that failed because the lease was lost mid-step, or a lease lost
+    // at any boundary: one record names it (#2748).
+    if (work?.lost !== undefined) records.push(lostRecord());
+
     // Compensation: run onFailure phases in reverse order (best-effort). Skipped
     // on abort (Ctrl-C) — the user asked to stop, so don't start new work.
+    // It runs whatever the work lease did, so it takes no work boundary.
+    const compensation: GateContext = { ...gates, work: undefined };
     if (!signal?.aborted) {
       for (const phase of [...(config.onFailure ?? [])].reverse()) {
         try {
-          records.push(...(await runPhase(phase, activities, profiles, resultsById, gates, signal)));
+          records.push(...(await runPhase(phase, activities, profiles, resultsById, compensation, signal)));
         } catch (compErr) {
           if (compErr instanceof PhaseFailure || compErr instanceof GateStop) {
             records.push(...compErr.records);
@@ -959,6 +1153,7 @@ export async function runOpLocally(
       }
     }
 
+    const failed = await settle(records, "fail");
     throw new OpRunFailure(
       {
         op: config.name,
@@ -966,19 +1161,22 @@ export async function runOpLocally(
         totalMs: Date.now() - start,
         status: "fail",
         startedAt,
-        record: await settle(records, "fail"),
+        record: failed,
+        ...(await finishWork("fail")),
       },
       { cause: err },
     );
   }
 
+  const record = await settle(records, "ok");
   return {
     op: config.name,
     records,
     totalMs: Date.now() - start,
     status: "ok",
     startedAt,
-    record: await settle(records, "ok"),
+    record,
+    ...(await finishWork("ok")),
   };
 }
 

package/src/op/local-output.ts

@@ -55,6 +55,19 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
     }
   }
 
+  // The work lease (#2748): which item the run held, and how it ended.
+  const work = result.workLease;
+  if (work?.item) {
+    const end = work.lost
+      ? `lost (${work.lost})`
+      : 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}`);
+  } else if (work?.refusal) {
+    write(`[work] nothing claimed: ${work.refusal}`);
+  }
+
   const total = `${(result.totalMs / 1000).toFixed(1)}s`;
   if (result.status === "ok") {
     write(`Op "${result.op}" completed in ${total}`);

package/src/op/op-ir.ts

@@ -86,6 +86,7 @@ import type {
   OutcomeAttribute,
   OpConfig,
   OpSchedule,
+  OpWorkLease,
   PhaseDefinition,
   StepDefinition,
   ActivityStep,
@@ -187,6 +188,15 @@ export interface OpIR {
    * additive optional key, so it needs no `formatVersion` bump.
    */
   schedule?: OpSchedule;
+  /**
+   * The work item the Op runs under (#2748) — `OpConfig.workLease` verbatim,
+   * a step-output reference in `item` or `outcome` in the same
+   * `{ kind: "step-output-ref", step, path }` shape as in args. Absent when it
+   * declares none. A runtime that can't take the lease must not run the Op.
+   */
+  workLease?: OpWorkLease;
+  /** `OpConfig.changesCheckout` (#2748), present only when true. */
+  changesCheckout?: true;
   phases: OpIRPhase[];
   onFailure: OpIRPhase[];
   /** Every activity profile referenced by a step in this Op, keyed by profile name — from the registry passed to {@link buildOpIR}, empty when none was. */
@@ -350,6 +360,8 @@ export function buildOpIR(
     depends: config.depends ?? [],
     labels: config.labels ?? {},
     ...(config.schedule ? { schedule: config.schedule } : {}),
+    ...(config.workLease ? { workLease: config.workLease } : {}),
+    ...(config.changesCheckout ? { changesCheckout: true as const } : {}),
     phases: config.phases.map((p) => irPhase(p, contractRegistry)),
     onFailure: (config.onFailure ?? []).map((p) => irPhase(p, contractRegistry)),
     activityProfiles: sortedEntries(profiles),
@@ -428,5 +440,7 @@ export function opConfigFromIR(ir: OpIR): OpConfig {
     ...(ir.onFailure.length > 0 ? { onFailure: ir.onFailure.map(opPhaseFromIR) } : {}),
     ...(Object.keys(ir.labels).length > 0 ? { labels: ir.labels } : {}),
     ...(ir.schedule ? { schedule: ir.schedule } : {}),
+    ...(ir.workLease ? { workLease: ir.workLease } : {}),
+    ...(ir.changesCheckout ? { changesCheckout: true } : {}),
   };
 }