@intentius/chant 0.90.0 → 0.93.0

package/src/op/steward-points.ts

@@ -0,0 +1,194 @@
+/**
+ * A decision point asked inside an Op run (#2749), and in a steward's turn in
+ * particular.
+ *
+ * An Op that needs a decision (the factory's builder tier, whether to ship)
+ * calls {@link askPointInRun} from one of its activities, such as the decide
+ * activity (#2740). It asks the point through `askPoint` (ws-058,
+ * `../workspace/decide.ts`), which records the question and its answer as a
+ * record, and then:
+ *
+ * - an `answered` question returns its answer, and the Op goes on;
+ * - an `escalated` or `proposed` question is open, so the activity throws
+ *   {@link PointWait}. The executor ends the run there with status `waiting`,
+ *   as a gate ends it with `gated`: no later step runs, no `onFailure` phase
+ *   runs, and the run ledger records the question the run is waiting on.
+ *
+ * The question stays open in the workspace, where `chant workspace points
+ * --open`, MCP's `workspace-points` and hud read it, and a person answers it
+ * with `points answer`. Nothing waits in the meantime: the next run asks the
+ * same point with the same inputs, finds the answer record, and goes on. A
+ * local steward re-runs a waiting Op on the first round after its question is
+ * answered (`./operator.ts`).
+ *
+ * ## In a steward's turn
+ *
+ * A steward runs unattended, so two more rules hold when the process is a
+ * steward's turn (`./steward-turn.ts`):
+ *
+ * - The model call goes through the broker. The caller supplies the call as a
+ *   {@link BrokeredModelAsk}, which is handed the box capability to reach the
+ *   model through, and only a capability the steward declares
+ *   (`declareSteward({ capabilities })`, #2726). A steward that names none,
+ *   or holds a vault, makes no model call: the model decider is recorded as
+ *   not reached and the question goes to people.
+ * - The question is written on the `chant/lifecycle` branch, not in the
+ *   checkout (#2786): the working tree is the coding agent's, and an Op's
+ *   leased worktree goes when the run ends. `points` reads it from there
+ *   (`../workspace/answers-ledger.ts`), and a person's answer goes there too.
+ * - The question names the steward and its run in its source block, and
+ *   neither the steward's turn nor the steward's name can answer it: `points
+ *   answer` refuses inside a steward's turn (`answer-in-steward-turn`) and
+ *   leaves the asking steward out of the quorum.
+ *
+ * The question never goes to the steward's own thread: on Fountain that thread
+ * is the steward's, and nobody reads it for questions.
+ */
+
+import type { ModelAsk, ModelRequest, WireAnswer } from "../workspace/points";
+import type { QuestionView } from "../workspace/decide";
+import { currentStewardTurn, type StewardTurn } from "./steward-turn";
+
+/** The box capability a model call goes through when the caller names none. */
+export const DEFAULT_INFERENCE_CAPABILITY = "inference";
+
+/** The open question a run stopped on, as the run ledger records it. */
+export interface WaitingPoint {
+  /** The answer record's id: what `points answer` and hud name. */
+  id: string;
+  /** The point asked. */
+  point: string;
+  /** Its state when the run stopped: `escalated` to people, or `proposed` by a model and waiting for a person to confirm it. */
+  state: "escalated" | "proposed";
+  /** The answer record, from the repository root. */
+  path: string;
+  /** What the question is about, or null. */
+  subject: string | null;
+  /** The steward whose turn asked it, or null. */
+  steward: string | null;
+}
+
+/** The marker {@link PointWait} carries, so a copy of core linked twice still recognises it. */
+const POINT_WAIT = Symbol.for("chant.op.PointWait");
+
+/**
+ * Thrown by an activity whose decision point is open. Not a failure: the
+ * executor ends the run with status `waiting` (see the module doc).
+ */
+export class PointWait extends Error {
+  readonly [POINT_WAIT] = true;
+  constructor(readonly question: WaitingPoint) {
+    super(
+      `waiting on decision point ${question.point} (${question.id}, ${question.state}): ` +
+        `a person answers it through hud or \`chant workspace points answer ${question.id}\``,
+    );
+    this.name = "PointWait";
+  }
+}
+
+/** Is this a {@link PointWait}? Duck-typed on the shared symbol. */
+export function isPointWait(err: unknown): err is PointWait {
+  return !!err && typeof err === "object" && (err as Record<symbol, unknown>)[POINT_WAIT] === true && "question" in err;
+}
+
+/**
+ * The model call, supplied by the caller (the decide activity, #2740, or a
+ * test's stub), made through a box capability. `via.capability` is the
+ * capability to reach the model through and `via.broker` the broker the
+ * member's box block names for it, when that is known. The function holds no
+ * credential: the broker does.
+ */
+export type BrokeredModelAsk = (
+  request: ModelRequest,
+  via: { capability: string; broker: string | null },
+) => Promise<{ model: string; answer: WireAnswer }>;
+
+export interface AskPointInRunOptions {
+  /** Where the workspace and the answer kind are found. */
+  cwd: string;
+  point: string;
+  inputs: unknown;
+  subject?: string;
+  /** The answer kind file, or a declared kind's name. */
+  kind?: string;
+  /** The model call. Without it, a model decider is not asked. */
+  ask?: BrokeredModelAsk;
+  /** The box capability the model call goes through. Default `inference`. */
+  capability?: string;
+  /** The broker the member's box block names for the capability, when the caller has read it. */
+  broker?: string | null;
+  /** The date written as asked_on, YYYY-MM-DD. */
+  on?: string;
+  /** The steward turn, when the caller has it. Default: this process's (`currentStewardTurn`). */
+  turn?: StewardTurn | null;
+}
+
+/** What a steward reaches through its broker, read from its declaration when the turn named only the steward. */
+async function stewardCapabilities(turn: StewardTurn, cwd: string): Promise<{ capabilities: readonly string[]; vault: string | null }> {
+  if (turn.capabilities !== undefined) return { capabilities: turn.capabilities, vault: turn.vault ?? null };
+  const { discoverStewards } = await import("./discover");
+  const found = (await discoverStewards({ cwd })).stewards.get(turn.steward)?.declaration;
+  return { capabilities: found?.capabilities ?? [], vault: found?.vault ?? null };
+}
+
+/**
+ * The {@link ModelAsk} a point is asked with. In a steward's turn the call is
+ * made only through a capability the steward declares; otherwise it throws,
+ * which the chain records as the model not being reached.
+ */
+export async function brokeredModelAsk(
+  ask: BrokeredModelAsk,
+  opts: { capability?: string; broker?: string | null; turn?: StewardTurn | null; cwd: string },
+): Promise<ModelAsk> {
+  const capability = opts.capability ?? DEFAULT_INFERENCE_CAPABILITY;
+  const via = { capability, broker: opts.broker ?? null };
+  const turn = opts.turn === undefined ? currentStewardTurn() : opts.turn;
+  if (!turn) return (request) => ask(request, via);
+  const { capabilities, vault } = await stewardCapabilities(turn, opts.cwd);
+  if (!capabilities.includes(capability)) {
+    const why =
+      vault !== null
+        ? `the steward ${turn.steward} holds the vault ${vault} and names no brokered capabilities, and a steward's model call goes through the broker`
+        : `the steward ${turn.steward} does not name the brokered capability ${capability}` +
+          (capabilities.length ? ` (it names ${capabilities.join(", ")})` : "") +
+          `, and a steward holds no credential of its own`;
+    return async () => {
+      throw new Error(why);
+    };
+  }
+  return (request) => ask(request, via);
+}
+
+/**
+ * Ask a decision point from inside an Op run. Resolves with the answer when
+ * the question is answered, and throws {@link PointWait} when it is open.
+ * Any other problem (the points can't be read, the inputs are wrong, a model
+ * declared `unreachable: "fail"` could not answer) throws an ordinary error,
+ * which fails the step.
+ */
+export async function askPointInRun(opts: AskPointInRunOptions): Promise<{ answer: string | boolean; question: QuestionView }> {
+  const turn = opts.turn === undefined ? currentStewardTurn() : opts.turn;
+  const ask = opts.ask ? await brokeredModelAsk(opts.ask, { capability: opts.capability, broker: opts.broker, turn, cwd: opts.cwd }) : undefined;
+  const { askPoint } = await import("../workspace/decide");
+  const doc = await askPoint({
+    cwd: opts.cwd,
+    point: opts.point,
+    inputs: opts.inputs,
+    ...(opts.subject !== undefined ? { subject: opts.subject } : {}),
+    ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+    ...(ask ? { ask } : {}),
+    ...(opts.on !== undefined ? { on: opts.on } : {}),
+    ...(turn ? { steward: { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } } : {}),
+  });
+  if ("error" in doc) throw new Error(`decision point ${opts.point}: ${doc.error.code}: ${doc.error.message}`);
+  const q = doc.question;
+  if (q.state === "answered" && q.answer !== null) return { answer: q.answer, question: q };
+  throw new PointWait({
+    id: q.id,
+    point: q.point,
+    state: q.state === "proposed" ? "proposed" : "escalated",
+    path: q.path,
+    subject: q.subject,
+    steward: q.askedBy?.steward ?? null,
+  });
+}

package/src/op/steward-turn.ts

@@ -0,0 +1,79 @@
+/**
+ * Whether this process is a steward's turn, and whose (#2749).
+ *
+ * A steward runs unattended. In the local form, `chant operator --steward`
+ * is the steward for as long as it runs; on Fountain, the Agent's `chant acp
+ * --steward <name>` session is. Two things read this: a decision point asked
+ * during the turn (`./steward-points.ts`), which records the steward on the
+ * question and makes its model call through the steward's brokered
+ * capability, and `points answer`, which refuses to record an answer from a
+ * steward's own turn, as the gate ledger's origin rule refuses a gate
+ * resolved on the channel that reached it.
+ *
+ * Like the gate origin (`../lifecycle/gate-origin.ts`) this is a property of
+ * the process, set once at its entry point, not a parameter threaded through
+ * every executor and activity. It is also exported to child processes as
+ * `CHANT_STEWARD`, so a `chant workspace points answer` an Op shells out to
+ * is refused the same way.
+ */
+
+/** The environment variable a steward's turn carries into child processes. */
+export const STEWARD_ENV = "CHANT_STEWARD";
+
+/** A steward's turn, as the process knows it. */
+export interface StewardTurn {
+  /** The steward's name. */
+  steward: string;
+  /**
+   * The box capabilities the steward reaches through the broker (#2726), or
+   * undefined when the process was told only the steward's name (a child
+   * process, or `chant acp --steward <name>`): the declaration is then read
+   * from the project's `*.op.ts` files when a model call needs it.
+   */
+  capabilities?: readonly string[];
+  /** The vault the steward holds, by name, when it is not behind a broker. */
+  vault?: string | null;
+  /** The run the steward is in, when an Op is running. */
+  run?: string;
+}
+
+let ambient: StewardTurn | undefined;
+
+/**
+ * Declare that this process is a steward's turn. Called once by `chant
+ * operator --steward` and `chant acp --steward`; also exports
+ * {@link STEWARD_ENV} so a child process knows it too.
+ */
+export function setStewardTurn(turn: StewardTurn): void {
+  ambient = { ...turn };
+  process.env[STEWARD_ENV] = turn.steward;
+}
+
+/**
+ * Be a steward's turn until the returned function is called, which puts back
+ * whatever was there before. `chant operator --steward` enters one per Op run,
+ * naming the run, so a question asked during it names the run too.
+ */
+export function enterStewardTurn(turn: StewardTurn): () => void {
+  const before = ambient;
+  const envBefore = process.env[STEWARD_ENV];
+  setStewardTurn(turn);
+  return () => {
+    ambient = before;
+    if (envBefore === undefined) delete process.env[STEWARD_ENV];
+    else process.env[STEWARD_ENV] = envBefore;
+  };
+}
+
+/** The steward whose turn this process is, or undefined. */
+export function currentStewardTurn(): StewardTurn | undefined {
+  if (ambient) return ambient;
+  const name = process.env[STEWARD_ENV];
+  return name && name.trim() !== "" ? { steward: name.trim() } : undefined;
+}
+
+/** Forget the turn. For tests, which must not leak a steward into each other. */
+export function resetStewardTurn(): void {
+  ambient = undefined;
+  delete process.env[STEWARD_ENV];
+}

package/src/op/steward.test.ts

@@ -0,0 +1,296 @@
+/**
+ * A steward's declaration and its local form (#2731): `declareSteward`'s
+ * refusals, discovery beside the Ops, a local round that runs the steward's
+ * scheduled Ops under its own lease, and the rule that a steward turn and a
+ * coding agent share one checkout without colliding.
+ */
+import { describe, test, expect, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { declareSteward, isStewardDeclaration, pickSteward, stewardFormFor, stewardLeaseName, stewardTurnLeaseName } from "./steward";
+import { discoverOps, discoverStewards } from "./discover";
+import { runOperatorRound, acquireStewardLease, acquireStewardTurn, formatRoundLine } from "./operator";
+import { readLease } from "../lifecycle/lease";
+import { readRunLedger } from "../lifecycle/run-ledger";
+
+const PROFILES: Record<string, ActivityProfile> = {};
+
+function op(name: string, cron?: string, fn = "fakeTurn"): OpConfig {
+  return {
+    name,
+    overview: `${name} fixture`,
+    phases: [{ name: "Run", steps: [{ kind: "activity", fn, args: {} }] }],
+    ...(cron ? { schedule: { cron, overlap: "skip" as const } } : {}),
+  };
+}
+
+function git(args: string[], cwd: string): { stdout: string; status: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", status: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  mkdirSync(join(dir, "app"), { recursive: true });
+  writeFileSync(join(dir, "app", "index.ts"), "export const hello = 1;\n");
+  git(["add", "app/index.ts"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+/** An `*.op.ts` file exporting a steward as a literal: the shape `declareSteward` returns, no imports. */
+function writeStewardFile(dir: string, file: string, name: string, ops: OpConfig[], form: unknown = { default: "local", environments: {} }): void {
+  mkdirSync(join(dir, "ops"), { recursive: true });
+  writeFileSync(
+    join(dir, "ops", file),
+    `export const steward = ${JSON.stringify({ kind: "Chant::Steward", name, ops, form })};\n`,
+  );
+}
+
+function turns(log: string[]): Map<string, ActivityFn> {
+  return new Map<string, ActivityFn>([
+    ["fakeTurn", async () => { log.push("turn"); return { ok: true }; }],
+  ]);
+}
+
+describe("declareSteward", () => {
+  test("normalises the form, local by default", () => {
+    const s = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+    expect(isStewardDeclaration(s)).toBe(true);
+    expect(s.form).toEqual({ default: "local", environments: {} });
+    expect(stewardFormFor(s)).toBe("local");
+  });
+
+  test("chooses the form per environment", () => {
+    const s = declareSteward({
+      name: "box-steward",
+      ops: [],
+      form: { default: "local", environments: { "fountain-k3d": "fountain" } },
+    });
+    expect(stewardFormFor(s, "minimal")).toBe("local");
+    expect(stewardFormFor(s, "fountain-k3d")).toBe("fountain");
+  });
+
+  test("reads an Op declaration through its props", () => {
+    const s = declareSteward({ name: "box-steward", ops: [{ props: op("box-release") }] });
+    expect(s.ops.map((o) => o.name)).toEqual(["box-release"]);
+  });
+
+  test("a brokered steward names its capabilities and holds no vault (#2726)", () => {
+    const s = declareSteward({ name: "a", ops: [], capabilities: ["fountain", "inference", "fountain"] });
+    expect(s.capabilities).toEqual(["fountain", "inference"]);
+    expect(s.vault).toBeNull();
+    expect(declareSteward({ name: "b", ops: [], vault: "creds" }).vault).toBe("creds");
+    expect(() => declareSteward({ name: "c", ops: [], capabilities: ["fountain"], vault: "creds" })).toThrow(/holds no credential/);
+  });
+
+  test("refuses what would make two writers or a promise it can't keep", () => {
+    expect(() => declareSteward({ name: "a", ops: [op("x"), op("x")] })).toThrow(/listed twice/);
+    expect(() => declareSteward({ name: "a", ops: [{ ...op("x"), schedule: { cron: "* * * * *", overlap: "buffer" as never } }] })).toThrow(/overlap "buffer"/);
+    expect(() => declareSteward({ name: "a", ops: [op("x", "not a cron")] })).toThrow(/Steward "a": op "x"/);
+    expect(() => declareSteward({ name: "../a", ops: [] })).toThrow(/steward's name/);
+    expect(() => declareSteward({ name: "a", ops: [], form: "cloud" as never })).toThrow(/"local" or "fountain"/);
+    expect(() => declareSteward({ name: "a", ops: [], form: { default: "local", environments: { "a/b": "fountain" } } })).toThrow(/can't be an environment/);
+  });
+});
+
+describe("discoverStewards", () => {
+  test("finds a steward in an *.op.ts file, and discoverOps doesn't call that file an error", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeStewardFile(dir, "steward.op.ts", "box-steward", [op("box-converge", "* * * * *")]);
+      const { stewards, errors } = await discoverStewards({ cwd: dir });
+      expect(errors).toEqual([]);
+      expect([...stewards.keys()]).toEqual(["box-steward"]);
+      expect(stewards.get("box-steward")!.exportName).toBe("steward");
+      expect((await discoverOps({ cwd: dir })).errors).toEqual([]);
+    });
+  });
+
+  test("refuses one Op listed by two stewards", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeStewardFile(dir, "a.op.ts", "first", [op("box-converge", "* * * * *")]);
+      writeStewardFile(dir, "b.op.ts", "second", [op("box-converge", "* * * * *")]);
+      const { stewards, errors, conflicts } = await discoverStewards({ cwd: dir });
+      expect([...stewards.keys()]).toEqual(["first"]);
+      expect(errors).toEqual([]);
+      expect(conflicts).toHaveLength(1);
+      expect(conflicts[0]).toMatch(/steward "second" lists op "box-converge", which steward "first" already runs/);
+    });
+  });
+
+  test("pickSteward takes the only steward, or the named one, and refuses otherwise", () => {
+    const one = new Map([["box-steward", { declaration: declareSteward({ name: "box-steward", ops: [] }) }]]);
+    expect(pickSteward(one, "")).toMatchObject({ name: "box-steward" });
+    expect(pickSteward(one, "other")).toMatch(/No steward "other"/);
+    expect(pickSteward(new Map(), "")).toMatch(/No steward is declared/);
+    const two = new Map([...one, ["b", { declaration: declareSteward({ name: "b", ops: [] }) }]]);
+    expect(pickSteward(two, "")).toMatch(/2 stewards are declared/);
+  });
+});
+
+describe("a local steward round", () => {
+  test("runs only the scheduled Ops, each on its cron, and records each run", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({
+        name: "box-steward",
+        ops: [op("box-converge", "* * * * *"), op("box-dispatch", "*/5 * * * *"), op("box-release")],
+      });
+      const log: string[] = [];
+      // 10:01 fires every minute, not every five.
+      const now = () => new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "h1", steward, activities: turns(log), profiles: PROFILES, now });
+      expect(events.map((e) => [e.kind, e.op])).toEqual([
+        ["ticked", "box-converge"],
+        ["skipped-not-due", "box-dispatch"],
+      ]);
+      // box-release has no schedule: it runs when asked, never on a round.
+      expect(log).toEqual(["turn"]);
+      expect((await readRunLedger("local", "box-converge", { cwd: dir })).records).toHaveLength(1);
+      expect((await readLease(stewardLeaseName("box-steward"), { cwd: dir })).record?.holder).toBe("h1");
+    });
+  });
+
+  test("a second holder of the same steward ticks nothing", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+      expect((await acquireStewardLease("box-steward", "h1", { cwd: dir })).acquired).toBe(true);
+      const log: string[] = [];
+      const events = await runOperatorRound({ cwd: dir, holder: "h2", steward, activities: turns(log), profiles: PROFILES });
+      expect(events).toEqual([{ kind: "steward-busy", op: "_stewards/box-steward", env: "-", steward: "box-steward", heldBy: "h1" }]);
+      expect(formatRoundLine(events[0])).toBe("operator: steward box-steward skipped=1(steward-lease-held:h1)");
+      expect(log).toEqual([]);
+    });
+  });
+
+  test("a coding agent edits app/ and holds the index lock during a steward turn, and neither collides", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = git(["rev-parse", "HEAD"], dir).stdout.trim();
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *", "agentEditsMidTurn")] });
+      const edited = "export const hello = 2; // the coding agent's edit\n";
+      const lock = join(dir, ".git", "index.lock");
+      const activities = new Map<string, ActivityFn>([
+        [
+          "agentEditsMidTurn",
+          async () => {
+            // The coding agent, mid-turn: an edit to the app, and a commit in
+            // progress that holds git's index lock.
+            writeFileSync(join(dir, "app", "index.ts"), edited);
+            writeFileSync(lock, "");
+            return { ok: true };
+          },
+        ],
+      ]);
+
+      const events = await runOperatorRound({ cwd: dir, holder: "h1", steward, activities, profiles: PROFILES });
+      expect(events.map((e) => e.kind)).toEqual(["ticked"]);
+
+      // The steward's writes landed where chant writes: the run ledger and the lease refs.
+      expect((await readRunLedger("local", "box-converge", { cwd: dir })).records).toHaveLength(1);
+      expect(git(["rev-parse", "--verify", "refs/heads/chant/lifecycle"], dir).status).toBe(0);
+
+      // And none of them touched the checkout: the agent's edit is intact, its
+      // lock is still its own, and HEAD and the index are where they were.
+      expect(readFileSync(join(dir, "app", "index.ts"), "utf-8")).toBe(edited);
+      expect(existsSync(lock)).toBe(true);
+      rmSync(lock); // the agent's commit finishes; git status needs the lock gone
+
+      expect(git(["rev-parse", "HEAD"], dir).stdout.trim()).toBe(head);
+      expect(git(["status", "--porcelain"], dir).stdout).toBe(" M app/index.ts\n");
+      expect(git(["diff", "--cached", "--name-only"], dir).stdout).toBe("");
+    });
+  });
+});
+
+describe("a hand run waits its turn (#2750)", () => {
+  test("a round holds the turn lease for exactly the length of its tick — a concurrent hand run sees it held, then free again once the tick ends", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      let releaseTurn: () => void = () => {};
+      const gate = new Promise<void>((resolve) => { releaseTurn = resolve; });
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *", "slowTurn")] });
+      const activities = new Map<string, ActivityFn>([
+        ["slowTurn", async () => { await gate; return { ok: true }; }],
+      ]);
+      // Real time on both sides here, deliberately: a fixed `now` on only one
+      // of the round's and the hand run's leases would make one see the
+      // other's lease as already expired by wall-clock time, which is not
+      // the race this test is about.
+      const roundPromise = runOperatorRound({ cwd: dir, holder: "steward-proc", steward, activities, profiles: PROFILES });
+
+      // Wait for the round to actually be mid-tick, holding the turn lease.
+      await vi.waitFor(async () => {
+        const turn = await readLease(stewardTurnLeaseName("box-steward"), { cwd: dir });
+        expect(turn.record?.holder).toBe("steward-proc");
+      });
+
+      // A hand run's own attempt (no `waitMs`) sees it taken and gives up
+      // without retrying — this is what `chant run <op>` names in its refusal.
+      const midTurn = await acquireStewardTurn("box-steward", "hand-run", { cwd: dir });
+      expect(midTurn.acquired).toBe(false);
+      expect(midTurn.heldBy?.holder).toBe("steward-proc");
+
+      releaseTurn();
+      const events = await roundPromise;
+      expect(events.map((e) => e.kind)).toEqual(["ticked"]);
+
+      // The tick released the turn the moment it finished — succeeds again
+      // right away, not only once the whole steward process stops.
+      const afterTurn = await acquireStewardTurn("box-steward", "hand-run", { cwd: dir });
+      expect(afterTurn.acquired).toBe(true);
+    });
+  });
+
+  test("a hand run's turn blocks a round: it reports turn-busy and ticks nothing, and releases the op lease it had just taken", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+      const held = await acquireStewardTurn("box-steward", "hand-run", { cwd: dir });
+      expect(held.acquired).toBe(true);
+
+      const log: string[] = [];
+      const now = () => new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "steward-proc", steward, activities: turns(log), profiles: PROFILES, now });
+
+      expect(events).toEqual([{ kind: "turn-busy", op: "box-converge", env: "local", steward: "box-steward", heldBy: "hand-run" }]);
+      expect(formatRoundLine(events[0])).toContain("turn-held:hand-run");
+      expect(log).toEqual([]);
+      // The op's own lease, freshly acquired before the turn check, was let go again.
+      expect((await readLease("box-converge", { cwd: dir })).record).toBeUndefined();
+    });
+  });
+
+  test("a stale .lock on the turn ref reports lease-error, never a thrown exception out of the round, and still releases the op lease it had just taken (#1959 finding 2, applied to #2750's turn lease)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+
+      // A previous holder of the turn lease was killed mid-write — its
+      // `.lock` file is still sitting there, blocking every future write to
+      // `_turns/box-steward`, the same way #1959 finding 2 covers the
+      // per-op lease.
+      mkdirSync(join(dir, ".git", "refs", "chant", "lease", "_turns"), { recursive: true });
+      writeFileSync(join(dir, ".git", "refs", "chant", "lease", "_turns", "box-steward.lock"), "");
+
+      const log: string[] = [];
+      const now = () => new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "steward-proc", steward, activities: turns(log), profiles: PROFILES, now });
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toMatchObject({ kind: "lease-error", op: "_turns/box-steward", env: "local" });
+      expect((events[0] as { error: string }).error).toContain("box-steward.lock");
+      expect(log).toEqual([]);
+      // The op's own lease, freshly acquired before the failed turn attempt, was let go again.
+      expect((await readLease("box-converge", { cwd: dir })).record).toBeUndefined();
+    });
+  });
+});