@intentius/chant 0.90.0 → 0.93.0

package/src/op/local-output.ts

@@ -50,16 +50,42 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
     if (record.refusal) {
       write(`    [refused] ${record.refusal}`);
     }
+    if (record.point) {
+      write(`    [waiting] decision point ${record.point.point}: ${record.point.id} is ${record.point.state}`);
+    }
     if (record.error) {
       write(`    ${record.error}`);
     }
   }
 
+  // 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}`);
     return;
   }
+  if (result.status === "waiting" && result.point) {
+    // An open decision point (#2749): a fact like a gate. A person answers the
+    // question, through hud or at a shell, and the next run reads the answer.
+    const { point } = result;
+    write(`Op "${result.op}" is waiting on decision point "${point.point}" after ${total}`);
+    write(`  question: ${point.id} (${point.state}) at ${point.path}`);
+    if (point.subject) write(`  subject : ${point.subject}`);
+    write(`  answer  : ${pointAnswerCommand(point.id)}`);
+    return;
+  }
   if (result.status === "fail" || !result.gate) {
     write(`Op "${result.op}" failed after ${total}`);
     return;
@@ -74,7 +100,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
   // #2300: the plan the approval will be bound to. Printed before the
   // command, because it is what the command approves.
   if (gate.planDigest) write(`  plan    : ${gate.planDigest}`);
-  write(`  approve : ${approveCommand(gate.op, gate.gate)}`);
+  write(`  approve : ${approveCommand(gate.op, gate.gate, undefined, gate.planDigest)}`);
   if (gate.url) write(`  approve at: ${gate.url}`);
   write(`  expires : ${gate.expiresAt}`);
   // #2310: this run's own append reached only the local chant/lifecycle
@@ -102,7 +128,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
  * the gate doesn't have to reassemble it from the op and gate names.
  */
 export function renderJson(result: OpRunResult, write: Writer = stdout): void {
-  const approve = result.gate ? { approve: approveCommand(result.gate.op, result.gate.gate) } : {};
+  const approve = result.gate ? { approve: approveCommand(result.gate.op, result.gate.gate, undefined, result.gate.planDigest) } : {};
   // #2310: whether this run's own append reached the remote — not part of
   // the persisted ledger record (a replay has nothing new to report), but a
   // live run's JSON consumer needs it exactly where the human render shows it.
@@ -113,3 +139,8 @@ export function renderJson(result: OpRunResult, write: Writer = stdout): void {
 }
 
 export type { OpRunResult, StepRecord };
+
+/** The command a person answers an open decision point with (#2749). */
+export function pointAnswerCommand(id: string): string {
+  return `chant workspace points answer ${id} --answer <answer> --by <your name>`;
+}

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

@@ -112,6 +112,16 @@ describe("op.json IR", () => {
     expect(serializeOpIR(reconstructed)).toBe(text);
   });
 
+  it("carries a step's own timeout, and round-trips it (#2787)", () => {
+    const original: OpConfig = { name: "dispatch", overview: "o", phases: [phase("Build", [shell("./build.sh", { timeout: "45m" }), shell("echo hi")])] };
+    const ir = buildOpIR(original);
+    const steps = ir.phases[0].steps as { profile: string; timeout?: string }[];
+    expect(steps[0]).toMatchObject({ profile: "atMostOnce", timeout: "45m" });
+    expect(steps[1]).not.toHaveProperty("timeout");
+    const text = serializeOpIR(original);
+    expect(serializeOpIR(opConfigFromIR(JSON.parse(text) as OpIR))).toBe(text);
+  });
+
   it("two serializations of the same config are byte-identical (determinism)", () => {
     const config = representativeOp();
     expect(serializeOpIR(config)).toBe(serializeOpIR(config));

package/src/op/op-ir.ts

@@ -86,6 +86,7 @@ import type {
   OutcomeAttribute,
   OpConfig,
   OpSchedule,
+  OpWorkLease,
   PhaseDefinition,
   StepDefinition,
   ActivityStep,
@@ -117,6 +118,8 @@ export interface OpIRActivityStep {
   args: Record<string, unknown>;
   /** Resolved to its effective value — `ActivityStep.profile ?? "fastIdempotent"`. */
   profile: string;
+  /** The step's own timeout, replacing its profile's (#2787). Absent when the profile's applies. */
+  timeout?: string;
   /**
    * What this step's effect touches in the estate (#2022): the string values
    * of the args its contract declares as entity-identifying
@@ -187,6 +190,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. */
@@ -230,6 +242,7 @@ function irActivityStep(step: ActivityStep, contracts: ReadonlyMap<string, Activ
     fn: step.fn,
     args: step.args ?? {},
     profile: effectiveProfile(step),
+    ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
     ...(entities ? { entities } : {}),
     ...(step.outcomeAttribute ? { outcomeAttribute: step.outcomeAttribute } : {}),
   };
@@ -350,6 +363,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),
@@ -382,6 +397,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       fn: step.fn,
       args: step.args,
       profile: step.profile as ActivityStep["profile"],
+      ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
       ...(step.outcomeAttribute ? { outcomeAttribute: step.outcomeAttribute } : {}),
     };
   }
@@ -428,5 +444,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

@@ -51,6 +51,7 @@ const READ_ONLY_ACTIVITY_FNS: ReadonlySet<string> = new Set([
   "spriteServiceGet",
   "spriteServiceList",
   "spriteServiceLogs",
+  "spriteServicesObserve",
 ]);
 
 /** Activity function names that always delete/destroy, regardless of args. */

package/src/op/operator.ts

@@ -38,7 +38,13 @@
 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 { acquireLease, releaseLease, stillHoldsLease, currentHolderId, DEFAULT_LEASE_TTL_MS, type LeaseRecord, type AcquireLeaseResult } from "../lifecycle/lease";
+import { randomUUID } from "node:crypto";
+import { readRunLedger, runEnvOf } from "../lifecycle/run-ledger";
+import { readGateLedger, latestResolutionSince } from "../lifecycle/gate-ledger";
+import { enterStewardTurn } from "./steward-turn";
+import { stewardLeaseName, stewardTurnLeaseName, 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";
@@ -76,7 +82,36 @@ export async function discoverConvergeOps(
 
 /** One discovered ConvergeOp's outcome for one round — what `chant operator`'s one-line-per-tick log (and its tests) key off of. */
 export type OperatorTickEvent =
-  | { kind: "ticked"; op: string; env: string; result: OpRunResult }
+  /**
+   * The Op ran. `resumed` names the decision point question it was waiting on
+   * (#2749) when a steward ran it because that question is now answered,
+   * rather than because its cron fired.
+   */
+  | {
+      kind: "ticked";
+      op: string;
+      env: string;
+      result: OpRunResult;
+      resumed?: string;
+      /**
+       * The gate the Op's last run stopped at (#2779), when a steward ran it
+       * because that gate is now approved rather than because its cron fired.
+       */
+      approved?: { op: string; gate: string };
+    }
+  /**
+   * A steward's Op whose last run stopped on an open decision point (#2749),
+   * and the question is still open, so the Op is not run this round. A person
+   * answers it through hud or `points answer`; the steward never does.
+   */
+  | { kind: "waiting-on-point"; op: string; env: string; point: string; question: string; state: string }
+  /**
+   * A steward's Op whose last run stopped at a gate (#2779), and nobody has
+   * approved it since, so the Op is not run this round. `gateOp` is the op
+   * the gate is recorded under: the Op's own, or a command's such as
+   * `workspace-upgrade`.
+   */
+  | { kind: "waiting-on-gate"; op: string; env: string; gateOp: string; gate: string }
   | { kind: "skipped-lease-held"; op: string; env: string; heldBy?: string }
   /** The Op declares its own `schedule.cron` (#2120) and this round did not land on a firing minute — the lease was never touched. An Op without a cron is never reported this way: it ticks every round, on `--interval`. */
   | { kind: "skipped-not-due"; op: string; env: string; cron: string }
@@ -94,7 +129,24 @@ 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 }
+  /**
+   * A local steward's round (#2750) found its turn lease
+   * (`stewardTurnLeaseName`) held by someone else already mid-run — a `chant
+   * run <op>` typed by hand, or another round somehow still finishing one.
+   * Nothing ticked: the round stops here rather than trying its remaining
+   * ops, since every one of them would fail the same check (the turn is one
+   * lease for the whole steward, not one per op). The next round tries
+   * again.
+   */
+  | { kind: "turn-busy"; op: string; env: string; steward: string; heldBy?: string };
 
 export interface OperatorRoundOptions {
   cwd?: string;
@@ -119,6 +171,179 @@ 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;
+  /**
+   * How a steward's round reads the state of the questions its waiting runs
+   * stopped on (#2749): question id to state, or null when they can't be
+   * read. Defaults to the workspace's `points` read; a test injects one.
+   */
+  readQuestions?: (cwd: string) => Promise<Map<string, string> | null>;
+}
+
+/** A steward's Op whose last run waits on a decision point (#2749). */
+interface WaitState {
+  /** The answer record's id. */
+  question: string;
+  point: string;
+  /** The question's state now, or the one the run recorded when it can't be read. */
+  state: string;
+  /** The question is answered, or its record is gone, so the Op runs again. */
+  answered: boolean;
+}
+
+/**
+ * The steward's Ops whose newest run is the steward's own and stopped on a
+ * decision point, with that question's state now. The questions are read
+ * from the workspace the way `points` reads them; a workspace that can't be
+ * read leaves every run waiting.
+ */
+async function stewardWaits(steward: StewardDeclaration, opts: OperatorRoundOptions): Promise<Map<string, WaitState>> {
+  const out = new Map<string, WaitState>();
+  const runs: { op: string; question: string; point: string; state: string }[] = [];
+  for (const op of steward.ops) {
+    try {
+      const newest = (await readRunLedger(runEnvOf(op), op.name, { cwd: opts.cwd })).records.at(-1);
+      if (newest?.status === "waiting" && newest.point && newest.steward === steward.name) {
+        runs.push({ op: op.name, question: newest.point.id, point: newest.point.point, state: newest.point.state });
+      }
+    } catch {
+      // A ledger that can't be read has no waiting run to resume.
+    }
+  }
+  if (runs.length === 0) return out;
+  const states = await (opts.readQuestions ?? readQuestionStates)(opts.cwd ?? process.cwd());
+  for (const r of runs) {
+    const now = states?.get(r.question);
+    const answered = states !== null && (now === undefined || now === "answered");
+    out.set(r.op, { question: r.question, point: r.point, state: now ?? r.state, answered });
+  }
+  return out;
+}
+
+/** A steward's Op whose last run stopped at a gate (#2779). */
+interface GateWaitState {
+  /** The op the gate is recorded under. */
+  gateOp: string;
+  gate: string;
+  /** Someone approved the gate since the run stopped there, so the Op runs again. */
+  approved: boolean;
+}
+
+/**
+ * The steward's Ops whose newest run is the steward's own and stopped at a
+ * gate, and whether the gate has been approved since. A gate ledger that
+ * can't be read leaves the run where it stopped.
+ */
+async function stewardGates(steward: StewardDeclaration, opts: OperatorRoundOptions): Promise<Map<string, GateWaitState>> {
+  const out = new Map<string, GateWaitState>();
+  for (const op of steward.ops) {
+    try {
+      const newest = (await readRunLedger(runEnvOf(op), op.name, { cwd: opts.cwd })).records.at(-1);
+      if (newest?.status !== "gated" || !newest.gate || newest.steward !== steward.name) continue;
+      const gateOp = newest.gate.op ?? op.name;
+      const { resolutions } = await readGateLedger(gateOp, { cwd: opts.cwd });
+      const approved = latestResolutionSince(resolutions, newest.gate.name, newest.gate.since) !== undefined;
+      out.set(op.name, { gateOp, gate: newest.gate.name, approved });
+    } catch {
+      // A ledger that can't be read has no gated run to resume.
+    }
+  }
+  return out;
+}
+
+/** Every question's state in the workspace, by id, or null when the workspace's points can't be read. */
+async function readQuestionStates(cwd: string): Promise<Map<string, string> | null> {
+  try {
+    const { workspacePoints } = await import("../workspace/points-cli");
+    const doc = await workspacePoints({ cwd });
+    if (!("questions" in doc)) return null;
+    // An answer kind that could not be read might hold the question: say
+    // nothing rather than resume a run whose question may still be open.
+    if (doc.sources.some((s) => s.reason !== null)) return null;
+    return new Map(doc.questions.map((q) => [q.id, q.state]));
+  } catch {
+    return null;
+  }
+}
+
+/** 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 });
+}
+
+/**
+ * How long a caller contending for a steward's turn lease
+ * (`acquireStewardTurn`) retries before giving up (#2750). Long enough to
+ * ride out a race with a turn that is just ending; short enough that a
+ * genuinely busy steward is reported back promptly. A round never waits
+ * (`waitMs` omitted there): it already runs on its own timer and simply
+ * tries the turn again next round, exactly as it already does for a busy
+ * per-op lease. `chant run <op>` (`../cli/handlers/run.ts`) is the caller
+ * that waits, since a human is standing at the terminal for the answer.
+ */
+export const STEWARD_TURN_WAIT_MS = 2_000;
+
+/** How often {@link acquireStewardTurn} retries while it waits. */
+const STEWARD_TURN_POLL_MS = 150;
+
+/**
+ * Take the steward's turn lease (#2750): the lease every run of one of its
+ * Ops — a round's scheduled tick, or `chant run <op>` typed by hand — holds
+ * for exactly as long as that one run takes, so the two are never beside each
+ * other. Distinct from {@link acquireStewardLease}, which one `chant operator
+ * --steward` process holds for its whole life: this one is held per-run, so a
+ * hand run succeeds the moment a round's tick ends, not only once the daemon
+ * itself stops.
+ *
+ * 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
+ * turn about to end passes `waitMs`, and this polls every
+ * {@link STEWARD_TURN_POLL_MS} until it acquires or the wait runs out.
+ */
+export async function acquireStewardTurn(
+  steward: string,
+  holder: string,
+  opts: { cwd?: string; ttlMs?: number; now?: () => Date; waitMs?: number } = {},
+): Promise<AcquireLeaseResult> {
+  const deadline = Date.now() + (opts.waitMs ?? 0);
+  for (;;) {
+    const result = await acquireLease(stewardTurnLeaseName(steward), holder, {
+      cwd: opts.cwd,
+      ttlMs: opts.ttlMs ?? DEFAULT_LEASE_TTL_MS,
+      now: opts.now,
+    });
+    if (result.acquired || result.reason !== "held" || Date.now() >= deadline) return result;
+    await new Promise((r) => setTimeout(r, STEWARD_TURN_POLL_MS));
+  }
+}
+
+/** Release a steward's turn lease, best-effort — a run whose turn was never actually acquired (or already lost) has nothing to release. */
+async function releaseStewardTurn(steward: string, holder: string, token: string, opts: { cwd?: string } = {}): Promise<void> {
+  await releaseLease(stewardTurnLeaseName(steward), holder, token, opts).catch(() => false);
+}
+
+/**
+ * The Ops one round considers: a steward's Ops, or every ConvergeOp. A
+ * steward's Op with no schedule is considered only to resume a run of the
+ * steward's that waits on a decision point.
+ */
+async function roundOps(opts: OperatorRoundOptions): Promise<DiscoveredOp["config"][]> {
+  if (opts.steward) return [...opts.steward.ops];
+  const { ops } = await discoverConvergeOps({ cwd: opts.cwd, env: opts.env });
+  return ops.map((d) => d.config);
 }
 
 /**
@@ -129,11 +354,66 @@ 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;
+
+  // A steward's Ops whose last run waits on a decision point (#2749), read
+  // once per round, and the state of those questions now.
+  const waiting = steward ? await stewardWaits(steward, opts) : new Map<string, WaitState>();
+  // And those whose last run stopped at a gate (#2779), with whether it has
+  // been approved since.
+  const gated = steward ? await stewardGates(steward, opts) : new Map<string, GateWaitState>();
 
-  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");
+    const wait = waiting.get(config.name);
+    const stopped = gated.get(config.name);
+    let resumed: string | undefined;
+    let approved: { op: string; gate: string } | undefined;
+
+    // A run waiting on a question that is now answered is resumed on this
+    // round, whatever its cron says. One whose question is still open is left
+    // until a person answers it, unless its cron fires, which asks again.
+    if (wait?.answered) resumed = wait.question;
+    // The same for a run stopped at a gate that is now approved (#2779).
+    if (stopped?.approved) approved = { op: stopped.gateOp, gate: stopped.gate };
+    const standing: OperatorTickEvent | undefined = wait
+      ? { kind: "waiting-on-point", op: config.name, env, point: wait.point, question: wait.question, state: wait.state }
+      : stopped
+        ? { kind: "waiting-on-gate", op: config.name, env, gateOp: stopped.gateOp, gate: stopped.gate }
+        : undefined;
+    const resuming = resumed !== undefined || approved !== undefined;
 
     // 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
@@ -147,10 +427,15 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
       const lastSeen = opts.scheduleState?.get(config.name);
       const due = lastSeen === undefined ? cronMatches(cron, now) : cronDueBetween(cron, lastSeen, now);
       opts.scheduleState?.set(config.name, now);
-      if (!due) {
-        events.push({ kind: "skipped-not-due", op: config.name, env, cron });
+      if (!due && !resuming) {
+        events.push(standing ?? { kind: "skipped-not-due", op: config.name, env, cron });
         continue;
       }
+    } else if (steward && !resuming) {
+      // An unscheduled Op runs when someone asks for it; the steward runs it
+      // only to resume its own waiting or gated run.
+      if (standing) events.push(standing);
+      continue;
     }
 
     let acquired: AcquireLeaseResult;
@@ -177,9 +462,48 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     }
 
     const lease = acquired.lease as LeaseRecord;
+
+    // A local steward is one turn at a time (#2750): a hand run (`chant run
+    // <op>`) holds this same lease for as long as it runs, so a round never
+    // ticks beside one. It is one lease for the whole steward, not one per
+    // op, so finding it held stops the round outright — every op still ahead
+    // of it in `roundOps` would fail the identical check.
+    let turn: AcquireLeaseResult | undefined;
+    if (steward) {
+      try {
+        turn = await acquireStewardTurn(steward.name, holder, { cwd: opts.cwd, ttlMs: opts.leaseTtlMs, now: opts.now });
+      } catch (err) {
+        // Not turn contention — the acquire attempt itself failed (most
+        // likely a StaleLockError). Same shape as the per-op acquire's own
+        // catch above: report it and stop, rather than let it propagate and
+        // leak the per-op lease this round just took.
+        await releaseLease(config.name, holder, lease.token, { cwd: opts.cwd }).catch(() => false);
+        const message = err instanceof StaleLockError ? err.message : err instanceof Error ? err.message : String(err);
+        events.push({ kind: "lease-error", op: stewardTurnLeaseName(steward.name), env, error: message });
+        break;
+      }
+      if (!turn.acquired) {
+        await releaseLease(config.name, holder, lease.token, { cwd: opts.cwd }).catch(() => false);
+        events.push({ kind: "turn-busy", op: config.name, env, steward: steward.name, heldBy: turn.heldBy?.holder });
+        break;
+      }
+    }
+
+    // The run is the steward's turn (#2749): a decision point it asks names the
+    // steward and makes its model call through the steward's broker, and an
+    // answer from inside the turn is refused.
+    const runId = randomUUID();
+    const restoreTurn = steward
+      ? enterStewardTurn({ steward: steward.name, capabilities: steward.capabilities, vault: steward.vault, run: runId })
+      : undefined;
     try {
       const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
+        runId,
+        ...(steward ? { steward: steward.name } : {}),
         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
@@ -195,7 +519,18 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
           }),
       });
       const held = await stillHoldsLease(config.name, holder, lease.token, { cwd: opts.cwd });
-      events.push(held ? { kind: "ticked", op: config.name, env, result } : { kind: "fenced", op: config.name, env });
+      events.push(
+        held
+          ? {
+              kind: "ticked",
+              op: config.name,
+              env,
+              result,
+              ...(resumed !== undefined ? { resumed } : {}),
+              ...(approved !== undefined ? { approved } : {}),
+            }
+          : { kind: "fenced", op: config.name, env },
+      );
     } catch (err) {
       // #2301: "see its ledger record" was the whole message, and it sent the
       // reader to an artifact that a failed ledger append means is missing —
@@ -209,7 +544,11 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
             ? err.message
             : String(err);
       events.push({ kind: "tick-failed", op: config.name, env, error: message });
+    } finally {
+      restoreTurn?.();
+      if (steward && turn?.acquired) await releaseStewardTurn(steward.name, holder, turn.lease!.token, { cwd: opts.cwd });
     }
+    if (!(await holdSteward())) break;
   }
 
   return events;
@@ -419,7 +758,14 @@ export function formatRoundLine(event: OperatorTickEvent): string {
   switch (event.kind) {
     case "ticked":
       return `operator: ${event.op}@${event.env} ticked=1 status=${event.result.status}` +
-        (event.result.gate ? ` gate="${event.result.gate.gate}"` : "");
+        (event.result.gate ? ` gate="${event.result.gate.gate}"` : "") +
+        (event.result.point ? ` point="${event.result.point.id}"` : "") +
+        (event.resumed ? ` resumed="${event.resumed}"` : "") +
+        (event.approved ? ` approved="${event.approved.op}/${event.approved.gate}"` : "");
+    case "waiting-on-point":
+      return `operator: ${event.op}@${event.env} waiting=1(point:${event.question}:${event.state})`;
+    case "waiting-on-gate":
+      return `operator: ${event.op}@${event.env} gated=1(gate:${event.gateOp}/${event.gate})`;
     case "skipped-lease-held":
       return `operator: ${event.op}@${event.env} skipped=1(lease-held${event.heldBy ? `:${event.heldBy}` : ""})`;
     case "skipped-not-due":
@@ -430,5 +776,9 @@ 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}` : ""})`;
+    case "turn-busy":
+      return `operator: ${event.op}@${event.env} skipped=1(turn-held${event.heldBy ? `:${event.heldBy}` : ""}, steward "${event.steward}" is already mid-turn)`;
   }
 }