@intentius/chant 0.89.0 → 0.91.0

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 } : {}),
   };
 }

package/src/op/op-verb-class.ts

@@ -47,6 +47,10 @@ const READ_ONLY_ACTIVITY_FNS: ReadonlySet<string> = new Set([
   "spriteListDir",
   "listCheckpoints",
   "convergeTick",
+  "spriteUrl",
+  "spriteServiceGet",
+  "spriteServiceList",
+  "spriteServiceLogs",
 ]);
 
 /** Activity function names that always delete/destroy, regardless of args. */
@@ -57,6 +61,8 @@ const ALWAYS_DESTRUCTIVE_ACTIVITY_FNS: ReadonlySet<string> = new Set([
   "awsDelete",
   "gcpDelete",
   "spriteDestroy",
+  "spriteDelete",
+  "spriteServiceDelete",
   "k3dDown",
   "k3sUninstall",
 ]);

package/src/op/operator.ts

@@ -39,6 +39,9 @@ import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import { discoverOps, type DiscoveredOp } from "./discover";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "./local-executor";
 import { acquireLease, stillHoldsLease, currentHolderId, DEFAULT_LEASE_TTL_MS, type LeaseRecord, type AcquireLeaseResult } from "../lifecycle/lease";
+import { runEnvOf } from "../lifecycle/run-ledger";
+import { stewardLeaseName, type StewardDeclaration } from "./steward";
+import { stewardWorkHolder } from "./work-lease-run";
 import { StaleLockError } from "../lifecycle/git";
 import { cronMatches, cronDueBetween } from "./cron";
 import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS, type WakeReason } from "./change-signal";
@@ -94,7 +97,14 @@ export type OperatorTickEvent =
    * back off silently forever instead of surfacing the fix. One op's lease
    * error never aborts the round for every other op.
    */
-  | { kind: "lease-error"; op: string; env: string; error: string };
+  | { kind: "lease-error"; op: string; env: string; error: string }
+  /**
+   * A local steward's round (#2731) found the steward's own lease held by
+   * another live holder: another `chant operator --steward` for the same
+   * steward. Nothing ticked. `op` is the steward's lease name and `env` is
+   * `-`, so a log line keyed on either still reads.
+   */
+  | { kind: "steward-busy"; op: string; env: string; steward: string; heldBy?: string };
 
 export interface OperatorRoundOptions {
   cwd?: string;
@@ -119,6 +129,30 @@ export interface OperatorRoundOptions {
    * round makes up exactly one tick rather than a backlog.
    */
   scheduleState?: Map<string, Date>;
+  /**
+   * Run a local steward's Ops instead of every discovered ConvergeOp (#2731).
+   * Only its scheduled Ops tick, each on its own cron, because that is what
+   * the same steward does on Fountain: an Op with no schedule runs when
+   * someone asks for it. The round first takes (or renews) the steward's own
+   * lease, and ticks nothing when another holder has it.
+   */
+  steward?: StewardDeclaration;
+}
+
+/** Take or renew a local steward's own lease (#2731). */
+export async function acquireStewardLease(
+  steward: string,
+  holder: string,
+  opts: { cwd?: string; ttlMs?: number; now?: () => Date } = {},
+): Promise<AcquireLeaseResult> {
+  return acquireLease(stewardLeaseName(steward), holder, { ...opts, ttlMs: opts.ttlMs ?? DEFAULT_LEASE_TTL_MS });
+}
+
+/** The Ops one round considers: a steward's scheduled ones, or every ConvergeOp. */
+async function roundOps(opts: OperatorRoundOptions): Promise<DiscoveredOp["config"][]> {
+  if (opts.steward) return opts.steward.ops.filter((op) => op.schedule !== undefined);
+  const { ops } = await discoverConvergeOps({ cwd: opts.cwd, env: opts.env });
+  return ops.map((d) => d.config);
 }
 
 /**
@@ -129,11 +163,42 @@ export interface OperatorRoundOptions {
  */
 export async function runOperatorRound(opts: OperatorRoundOptions): Promise<OperatorTickEvent[]> {
   const holder = opts.holder ?? currentHolderId();
-  const { ops } = await discoverConvergeOps({ cwd: opts.cwd, env: opts.env });
   const events: OperatorTickEvent[] = [];
+  const steward = opts.steward;
+  const leaseOpts = { cwd: opts.cwd, ttlMs: opts.leaseTtlMs, now: opts.now };
+
+  // A local steward is one writer (#2731): its round runs only while it holds
+  // its own lease, renewed here and again after every tick, so a turn longer
+  // than the lease's TTL still keeps it.
+  const holdSteward = async (): Promise<boolean> => {
+    if (!steward) return true;
+    let acquired: AcquireLeaseResult;
+    try {
+      acquired = await acquireStewardLease(steward.name, holder, leaseOpts);
+    } catch (err) {
+      events.push({
+        kind: "lease-error",
+        op: stewardLeaseName(steward.name),
+        env: "-",
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return false;
+    }
+    if (acquired.acquired) return true;
+    events.push({
+      kind: "steward-busy",
+      op: stewardLeaseName(steward.name),
+      env: "-",
+      steward: steward.name,
+      ...(acquired.heldBy?.holder ? { heldBy: acquired.heldBy.holder } : {}),
+    });
+    return false;
+  };
+
+  if (!(await holdSteward())) return events;
 
-  for (const { config } of ops) {
-    const env = envOf(config) ?? "unknown";
+  for (const config of await roundOps(opts)) {
+    const env = steward ? runEnvOf(config) : (envOf(config) ?? "unknown");
 
     // An Op that declares its own cadence (#2120) is ticked on that cron
     // rather than on every round. Level-triggered: the question is whether a
@@ -180,6 +245,9 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     try {
       const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
         ledger: { cwd: opts.cwd },
+        // A steward's turn claims work leases as `<steward>/<op>@<holder>`
+        // (#2748), which is how `workspace status` finds the lease it holds.
+        ...(steward ? { work: { holder: stewardWorkHolder(steward.name, config.name, holder) } } : {}),
         // #2301: without a sink, `settle` catches a failed ledger append and
         // drops it. That is the failure this tick can least afford to lose —
         // the message below points the reader at the ledger record, which is
@@ -210,6 +278,7 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
             : String(err);
       events.push({ kind: "tick-failed", op: config.name, env, error: message });
     }
+    if (!(await holdSteward())) break;
   }
 
   return events;
@@ -430,5 +499,7 @@ export function formatRoundLine(event: OperatorTickEvent): string {
       return `operator: ${event.op}@${event.env} fenced=1(lease lost mid-tick — ledger record still written)`;
     case "lease-error":
       return `operator: ${event.op}@${event.env} error=1(lease acquire failed — ${event.error})`;
+    case "steward-busy":
+      return `operator: steward ${event.steward} skipped=1(steward-lease-held${event.heldBy ? `:${event.heldBy}` : ""})`;
   }
 }

package/src/op/runtime.ts

@@ -156,6 +156,12 @@ export interface OpRunStartOptions {
   progress?: (record: StepRecord) => void;
   /** Aborts in-flight work (Ctrl-C). */
   signal?: AbortSignal;
+  /**
+   * For an Op that declares `workLease` (#2748): the work item this run is
+   * for (`--work <id>`) and who holds its lease (`--holder`). Only the local
+   * runtime takes it; a hosted run's lease is taken where the run executes.
+   */
+  work?: { item?: string; holder?: string };
 }
 
 /**

package/src/op/runtimes/local.ts

@@ -166,6 +166,9 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
                     `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`,
                 ),
               ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+              ...(startOpts.work ? { work: startOpts.work } : {}),
+              onWorkLeaseWarning: (message) =>
+                process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),
             },
           );
           const status = statusFrom(op.name, runId, startedAt, result);

package/src/op/step-output-ref.ts

@@ -87,6 +87,7 @@
 
 import { z } from "zod";
 import type { ActivityStep, OpConfig, PhaseDefinition } from "./types";
+import { WORK_LEASE_STEP_ID } from "./types";
 import { pathExistsInSchema, schemaAtPath, primitiveKindOf, type ActivityContract, type ActivityContractIssue } from "./activity-contract";
 
 const STEP_OUTPUT_REF_BRAND = Symbol.for("chant.op.stepOutputRef");
@@ -308,7 +309,7 @@ function indexById(locations: StepLocation[]): { byId: Map<string, StepLocation>
  *    the same parallel phase).
  */
 export function validateStepOutputRefScope(
-  config: Pick<OpConfig, "name" | "phases" | "onFailure">,
+  config: Pick<OpConfig, "name" | "phases" | "onFailure"> & Partial<Pick<OpConfig, "workLease">>,
 ): ActivityContractIssue[] {
   const issues: ActivityContractIssue[] = [];
 
@@ -339,6 +340,9 @@ export function validateStepOutputRefScope(
   for (const consumer of locations) {
     const refs = collectStepOutputRefs(consumer.step.args);
     for (const ref of refs) {
+      // The run's work lease (#2748) is published under a reserved id once it
+      // is claimed; an Op that declares one may reference it from any step.
+      if (config.workLease && ref.step === WORK_LEASE_STEP_ID) continue;
       if (duplicateIds.has(ref.step)) {
         issues.push({
           opName: config.name,
@@ -395,7 +399,7 @@ export function validateStepOutputRefScope(
  *    schema (an empty `path` — the whole return value — is always valid).
  */
 export function validateStepOutputRefs(
-  config: Pick<OpConfig, "name" | "phases" | "onFailure">,
+  config: Pick<OpConfig, "name" | "phases" | "onFailure"> & Partial<Pick<OpConfig, "workLease">>,
   contracts: ReadonlyMap<string, ActivityContract>,
 ): ActivityContractIssue[] {
   const issues = validateStepOutputRefScope(config);