@intentius/chant 0.94.0 → 0.95.1

package/src/op/steward-beside.test.ts

@@ -0,0 +1,267 @@
+/**
+ * An Op a steward runs beside its turns (#2861): the declaration, a long run
+ * that holds none of the steward's turns up, a hand run that takes the Op's
+ * lease and not the turn, and the operator stopping the runs it started.
+ */
+import { describe, test, expect, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { ActivityStep, OpConfig } from "./types";
+import { declareSteward, readinessKeys, stewardBesideFor, stewardTurnOps, stewardTurnLeaseName } from "./steward";
+import { createBesideState, formatRoundLine, runOperatorForever, runOperatorRound, waitForBesideRuns, type OperatorTickEvent } from "./operator";
+import { askReady, holdBesideLease, inProcessBesideLauncher, type BesideLauncher } from "./steward-beside";
+import { stepOutput } from "./step-output-ref";
+import { readLease } from "../lifecycle/lease";
+import { readRunLedger } from "../lifecycle/run-ledger";
+
+const PROFILES: Record<string, ActivityProfile> = {};
+
+function op(name: string, cron?: string, fn = "tick"): OpConfig {
+  return {
+    name,
+    overview: `${name} fixture`,
+    phases: [{ name: "Run", steps: [{ kind: "activity", fn, args: {} }] }],
+    ...(cron ? { schedule: { cron, overlap: "skip" as const } } : {}),
+  };
+}
+
+const ready = (fn = "ready"): ActivityStep => ({ kind: "activity", fn, args: {} });
+
+function git(args: string[], cwd: string): void {
+  spawnSync("git", args, { cwd, encoding: "utf-8" });
+}
+
+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);
+  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);
+}
+
+const kinds = (events: OperatorTickEvent[]) => events.map((e) => [e.kind, e.op]);
+
+describe("declareSteward's beside (#2861)", () => {
+  test("lists the Ops beside the turns after its turns' Ops, and names them", () => {
+    const steward = declareSteward({
+      name: "box-steward",
+      ops: [op("converge", "* * * * *")],
+      beside: [{ op: op("dispatch", undefined, "build"), ready: ready() }, op("rebuild", "0 3 * * *")],
+    });
+    expect(steward.ops.map((o) => o.name)).toEqual(["converge", "dispatch", "rebuild"]);
+    expect(steward.beside).toEqual([{ op: "dispatch", ready: ready() }, { op: "rebuild", ready: null }]);
+    expect(stewardTurnOps(steward).map((o) => o.name)).toEqual(["converge"]);
+    expect(stewardBesideFor(steward, "dispatch")?.ready).toEqual(ready());
+    expect(stewardBesideFor(steward, "converge")).toBeUndefined();
+    // A declaration from before #2861 has no beside, and every Op is a turn.
+    const { beside: _dropped, ...older } = steward;
+    expect(stewardTurnOps(older as typeof steward).map((o) => o.name)).toEqual(["converge", "dispatch", "rebuild"]);
+  });
+
+  test("refuses an Op both in ops and beside, a ready that is not one activity step, and one that reads a step's output", () => {
+    const converge = op("converge", "* * * * *");
+    expect(() => declareSteward({ name: "s", ops: [converge], beside: [converge] })).toThrow(/listed twice/);
+    expect(() =>
+      declareSteward({ name: "s", ops: [], beside: [{ op: op("dispatch"), ready: { kind: "gate", gate: "g" } as unknown as ActivityStep }] }),
+    ).toThrow(/ready is one activity step/);
+    expect(() =>
+      declareSteward({ name: "s", ops: [], beside: [{ op: op("dispatch"), ready: { kind: "activity", fn: "shellCmd", args: { cmd: stepOutput("pick", "json") } } }] }),
+    ).toThrow(/reads another step's output/);
+    // Started on its own, it can't be handed the work item a run names.
+    const leased: OpConfig = { ...op("dispatch"), changesCheckout: true, workLease: {} };
+    expect(() => declareSteward({ name: "s", ops: [], beside: [{ op: leased, ready: ready() }] })).toThrow(/workLease names no item/);
+  });
+
+  test("a ready step's answer: a list of keys, a string, true, or no work", () => {
+    expect(readinessKeys({ stdout: "", json: ["W-1:0", "intent:ws-1"] })).toEqual({ ready: true, keys: ["W-1:0", "intent:ws-1"] });
+    expect(readinessKeys([{ item: "W-2" }])).toEqual({ ready: true, keys: ['{"item":"W-2"}'] });
+    expect(readinessKeys("W-3")).toEqual({ ready: true, keys: ["W-3"] });
+    expect(readinessKeys(true)).toEqual({ ready: true, keys: [] });
+    for (const none of [false, null, "", [], { json: null }]) expect(readinessKeys(none)).toEqual({ ready: false, keys: [] });
+    expect(readinessKeys({ ready: [] })).toBeNull();
+  });
+
+  test("askReady reports a step that fails, answers in another shape, or isn't loaded", async () => {
+    const acts = new Map<string, ActivityFn>([
+      ["boom", async () => { throw new Error("no factory here"); }],
+      ["odd", async () => ({ ready: [{ item: "W-1" }], held: null })],
+    ]);
+    expect(await askReady(ready("boom"), acts)).toEqual({ error: "no factory here" });
+    expect(await askReady(ready("odd"), acts)).toMatchObject({ error: expect.stringContaining("neither true") });
+    expect(await askReady(ready("missing"), acts)).toMatchObject({ error: expect.stringContaining('"missing" is not loaded') });
+  });
+});
+
+describe("an Op beside a steward's turns (#2861)", () => {
+  test("a long run beside a per-minute converge: converge ticks every minute while it runs, and no work is started twice", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      let finish: () => void = () => {};
+      const building = new Promise<void>((resolve) => { finish = resolve; });
+      const log: string[] = [];
+      const activities = new Map<string, ActivityFn>([
+        ["tick", async () => { log.push("converge"); return { ok: true }; }],
+        ["build", async () => { log.push("build:start"); await building; log.push("build:end"); return { built: true }; }],
+        ["ready", async () => ({ stdout: "", json: ["W-1:0"] })],
+      ]);
+      const steward = declareSteward({
+        name: "box-steward",
+        ops: [op("converge", "* * * * *")],
+        beside: [{ op: op("dispatch", undefined, "build"), ready: ready() }],
+      });
+      const besideState = createBesideState();
+      const scheduleState = new Map<string, Date>();
+      const launchBeside = inProcessBesideLauncher(activities, PROFILES);
+      // Cron minutes are local time, so the rounds are too. The leases use the
+      // wall clock, so a fixed `now` is only handed to the cron.
+      let minute = 1;
+      const round = () => {
+        const at = new Date(2026, 8, 25, 10, minute++, 0);
+        return runOperatorRound({ cwd: dir, holder: "op1", steward, activities, profiles: PROFILES, besideState, scheduleState, launchBeside, now: () => at });
+      };
+
+      // 10:01: converge ticks as a turn; the ready step names work, and dispatch starts beside it.
+      const first = await round();
+      expect(kinds(first)).toEqual([["ticked", "converge"], ["beside-started", "dispatch"]]);
+      expect(first[1]).toMatchObject({ why: "ready", keys: ["W-1:0"], holder: "box-steward/dispatch@op1" });
+      expect(formatRoundLine(first[1])).toBe('operator: dispatch@local started=1(beside:ready) holder="box-steward/dispatch@op1" keys="W-1:0"');
+      await vi.waitFor(() => expect(log).toContain("build:start"));
+
+      // Mid-build the run holds the Op's own lease, and not the steward's turn.
+      expect((await readLease("dispatch", { cwd: dir })).record?.holder).toBe("box-steward/dispatch@op1");
+      expect((await readLease(stewardTurnLeaseName("box-steward"), { cwd: dir })).record).toBeUndefined();
+
+      // 10:02 and 10:03: converge ticks each minute while the build runs, and no second run starts.
+      for (let i = 0; i < 2; i++) {
+        const mid = await round();
+        expect(kinds(mid)).toEqual([["ticked", "converge"], ["beside-running", "dispatch"]]);
+      }
+      expect(log.filter((l) => l === "converge")).toHaveLength(3);
+      expect(log).not.toContain("build:end");
+
+      finish();
+      await waitForBesideRuns(besideState);
+      expect((await readLease("dispatch", { cwd: dir })).record).toBeUndefined();
+      const run = (await readRunLedger("local", "dispatch", { cwd: dir })).records.at(-1)!;
+      expect(run).toMatchObject({ status: "ok", steward: "box-steward" });
+
+      // 10:04: the end is reported, and the same work still named is not started again.
+      const after = await round();
+      expect(after).toEqual([
+        { kind: "beside-ended", op: "dispatch", env: "local", code: 0 },
+        expect.objectContaining({ kind: "ticked", op: "converge" }),
+        { kind: "skipped-not-ready", op: "dispatch", env: "local", already: ["W-1:0"] },
+      ]);
+      expect(log.filter((l) => l === "build:start")).toHaveLength(1);
+    });
+  });
+
+  test("a hand run holds the Op's lease and not the turn: converge still ticks, and the operator starts no second run", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const log: string[] = [];
+      const activities = new Map<string, ActivityFn>([
+        ["tick", async () => { log.push("converge"); return { ok: true }; }],
+        ["ready", async () => true],
+      ]);
+      const steward = declareSteward({
+        name: "box-steward",
+        ops: [op("converge", "* * * * *")],
+        beside: [{ op: op("dispatch", undefined, "build"), ready: ready() }],
+      });
+      const launched: string[] = [];
+      const launchBeside: BesideLauncher = (start) => {
+        launched.push(start.op.name);
+        return { done: Promise.resolve({ code: 0 }), stop: () => {} };
+      };
+
+      // What `chant run dispatch` takes for an Op beside the turns.
+      const hand = await holdBesideLease("dispatch", "hand-run", { cwd: dir });
+      expect(hand.acquired).toBe(true);
+      expect((await readLease(stewardTurnLeaseName("box-steward"), { cwd: dir })).record).toBeUndefined();
+
+      const at = new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "op1", steward, activities, profiles: PROFILES, launchBeside, now: () => at });
+      expect(events.map((e) => e.kind)).toEqual(["ticked", "beside-running"]);
+      expect(events[1]).toEqual({ kind: "beside-running", op: "dispatch", env: "local", heldBy: "hand-run" });
+      expect(log).toEqual(["converge"]);
+      expect(launched).toEqual([]);
+
+      // A second hand run is refused while the first holds the lease.
+      expect(await holdBesideLease("dispatch", "hand-run-2", { cwd: dir })).toEqual({ acquired: false, heldBy: "hand-run" });
+      if (hand.acquired) await hand.release();
+      expect((await readLease("dispatch", { cwd: dir })).record).toBeUndefined();
+      const next = await runOperatorRound({ cwd: dir, holder: "op1", steward, activities, profiles: PROFILES, launchBeside, now: () => at });
+      expect(next.map((e) => e.kind)).toContain("beside-started");
+      expect(launched).toEqual(["dispatch"]);
+    });
+  });
+
+  test("the lease a long run holds is renewed while it runs", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const held = await holdBesideLease("dispatch", "h", { cwd: dir, ttlMs: 900 });
+      expect(held.acquired).toBe(true);
+      if (!held.acquired) return;
+      const first = held.lease.expiresAt;
+      await vi.waitFor(async () => {
+        const now = (await readLease("dispatch", { cwd: dir })).record;
+        expect(now?.token).toBe(held.lease.token);
+        expect(now!.expiresAt > first).toBe(true);
+      }, { timeout: 3000 });
+      await held.release();
+    });
+  });
+
+  test("a cron fire starts it, and one that fires while a run is in flight is dropped", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [], beside: [op("nightly", "0 3 * * *")] });
+      let end: () => void = () => {};
+      const launchBeside: BesideLauncher = () => ({ done: new Promise((resolve) => { end = () => resolve({ code: 0 }); }), stop: () => {} });
+      const besideState = createBesideState();
+      const scheduleState = new Map<string, Date>();
+      const round = (h: number, m: number) =>
+        runOperatorRound({ cwd: dir, holder: "op1", steward, activities: new Map(), profiles: PROFILES, besideState, scheduleState, launchBeside, now: () => new Date(2026, 8, 25, h, m, 0) });
+      expect(kinds(await round(2, 59))).toEqual([["skipped-not-due", "nightly"]]);
+      expect(await round(3, 0)).toEqual([expect.objectContaining({ kind: "beside-started", op: "nightly", why: "cron" })]);
+      expect(kinds(await round(3, 1))).toEqual([["beside-running", "nightly"]]);
+      end();
+      await waitForBesideRuns(besideState);
+      expect(kinds(await round(3, 2))).toEqual([["beside-ended", "nightly"], ["skipped-not-due", "nightly"]]);
+    });
+  });
+
+  test("the operator stops the runs it started when it stops", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [], beside: [{ op: op("dispatch"), ready: ready() }] });
+      const controller = new AbortController();
+      const stopped: string[] = [];
+      const launchBeside: BesideLauncher = (start) => {
+        let end: (code: number) => void = () => {};
+        const done = new Promise<{ code: number }>((resolve) => { end = (code) => resolve({ code }); });
+        return { done, stop: () => { stopped.push(start.op.name); end(1); } };
+      };
+      await runOperatorForever({
+        cwd: dir,
+        holder: "op1",
+        steward,
+        activities: new Map<string, ActivityFn>([["ready", async () => true]]),
+        profiles: PROFILES,
+        launchBeside,
+        intervalMs: 10,
+        signal: controller.signal,
+        onRound: (events) => {
+          if (events.some((e) => e.kind === "beside-started")) controller.abort();
+        },
+      });
+      expect(stopped).toEqual(["dispatch"]);
+    });
+  });
+});

package/src/op/steward-beside.ts

@@ -0,0 +1,219 @@
+/**
+ * An Op a steward runs beside its turns (#2861): how a run of it is started,
+ * held and asked for.
+ *
+ * A local steward runs the Ops it lists one turn at a time (#2750). An Op
+ * listed under `beside` (`./steward.ts`) is the steward's too, but a run of it
+ * is not a turn: the operator (`./operator.ts`) starts it as a `chant run
+ * <op>` process of its own and goes on with its rounds, so converge keeps its
+ * cadence while a build of half an hour runs.
+ *
+ * - The run holds the Op's own lease (`refs/chant/lease/<op>`, the lease a
+ *   round's tick of any Op takes), renewed every third of its time to live
+ *   for as long as the run lasts, and released when it ends. That is what
+ *   makes it one run at a time, whoever starts it: the operator, or a person's
+ *   `chant run <op>`, which takes this lease and not the steward's turn.
+ * - The process the operator starts carries `CHANT_STEWARD`, so its run record
+ *   names the steward, a decision point it asks is the steward's, and the
+ *   operator resumes it once the question is answered, by starting another
+ *   such process. Its work lease holder is `<steward>/<op>@<operator>`, which
+ *   is how `workspace status` finds it under the steward.
+ */
+import { spawn } from "node:child_process";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import { runOpLocally, OpRunFailure } from "./local-executor";
+import type { ActivityStep, OpConfig } from "./types";
+import { parseDuration } from "./duration";
+import { acquireLease, releaseLease, DEFAULT_LEASE_TTL_MS, type LeaseRecord } from "../lifecycle/lease";
+import { readinessKeys } from "./steward";
+
+/** Why the operator started a run beside the turns. */
+export type BesideWhy = "cron" | "ready" | "resumed" | "approved";
+
+/** What the operator asks a launcher to start. */
+export interface BesideStart {
+  /** The Op. */
+  op: OpConfig;
+  /** The steward whose run it is. */
+  steward: string;
+  /** The operator's own `--env`, passed on so the run reads the steward's form the same way. */
+  env?: string;
+  /** The holder the run claims the Op's lease and any work lease as: `<steward>/<op>@<operator>`. */
+  holder: string;
+  /** The project directory. */
+  cwd: string;
+  /** How long the Op's lease lasts unless renewed. */
+  leaseTtlMs?: number;
+}
+
+/** How a started run ended: its exit code (0 ok, 3 gated or waiting, 1 failed), or the error that kept it from running. */
+export interface BesideExit {
+  code: number | null;
+  error?: string;
+}
+
+/** A run started beside the turns. */
+export interface BesideHandle {
+  /** Settles when the run ends; never rejects. */
+  done: Promise<BesideExit>;
+  /** Ask the run to stop, as Ctrl-C does: it stops its steps and releases its leases. */
+  stop(): void;
+}
+
+/** Starts a run beside the turns. The default is {@link spawnBesideRun}. */
+export type BesideLauncher = (start: BesideStart) => BesideHandle;
+
+/** The exit code `chant run` gives a run that stopped at a gate or on an open decision point. */
+const WAITING_EXIT = 3;
+
+/**
+ * Start `chant run <op>` as a process of its own: the same node, loader and
+ * entry script this process runs as, in the project directory, with
+ * `CHANT_STEWARD` naming the steward and `--holder` naming the holder.
+ */
+export function spawnBesideRun(start: BesideStart): BesideHandle {
+  const args = [
+    ...process.execArgv,
+    process.argv[1],
+    "run",
+    start.op.name,
+    "--holder",
+    start.holder,
+    ...(start.env ? ["--env", start.env] : []),
+  ];
+  const child = spawn(process.execPath, args, {
+    cwd: start.cwd,
+    env: { ...process.env, CHANT_STEWARD: start.steward },
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+  const done = new Promise<BesideExit>((resolve) => {
+    child.once("error", (err) => resolve({ code: null, error: err.message }));
+    child.once("exit", (code, signal) => resolve(signal ? { code: null, error: `stopped by ${signal}` } : { code }));
+  });
+  return {
+    done,
+    // `chant run` stops its Op and releases its leases on SIGINT.
+    stop: () => {
+      if (child.exitCode === null && child.signalCode === null) child.kill("SIGINT");
+    },
+  };
+}
+
+/**
+ * A launcher that runs the Op in this process, as an async task, under the
+ * same lease a `chant run` of it takes. For tests, and for an embedder whose
+ * activities are its own: the run does not enter the steward's turn (that is
+ * a property of the process, and the operator's own turns share it), so its
+ * record names the steward and a decision point it asks does not.
+ */
+export function inProcessBesideLauncher(
+  activities: Map<string, ActivityFn>,
+  profiles: Record<string, ActivityProfile>,
+): BesideLauncher {
+  return (start) => {
+    const controller = new AbortController();
+    const done = (async (): Promise<BesideExit> => {
+      const held = await holdBesideLease(start.op.name, start.holder, { cwd: start.cwd, ttlMs: start.leaseTtlMs });
+      if (!held.acquired) return { code: 1, error: `the lease of "${start.op.name}" is held by ${held.heldBy ?? "another holder"}` };
+      try {
+        const result = await runOpLocally(start.op, activities, profiles, controller.signal, {
+          steward: start.steward,
+          ledger: { cwd: start.cwd },
+          work: { holder: start.holder },
+        });
+        return { code: result.status === "gated" || result.status === "waiting" ? WAITING_EXIT : 0 };
+      } catch (err) {
+        return { code: 1, error: err instanceof OpRunFailure ? `Op "${start.op.name}" failed` : err instanceof Error ? err.message : String(err) };
+      } finally {
+        await held.release();
+      }
+    })();
+    return { done, stop: () => controller.abort() };
+  };
+}
+
+/** The Op's own lease, held for a run beside the turns. */
+export type HeldBesideLease =
+  | { acquired: true; lease: LeaseRecord; release: () => Promise<void> }
+  | { acquired: false; heldBy?: string };
+
+/**
+ * Take the Op's own lease for one run beside the steward's turns, and renew
+ * it every third of its time to live until `release` is called. A run of half
+ * an hour keeps it; a process that dies stops renewing and the lease expires.
+ * Refused when another holder has it: a run of the Op is in flight.
+ */
+export async function holdBesideLease(
+  op: string,
+  holder: string,
+  opts: { cwd?: string; ttlMs?: number } = {},
+): Promise<HeldBesideLease> {
+  const ttlMs = opts.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+  const first = await acquireLease(op, holder, { cwd: opts.cwd, ttlMs });
+  if (!first.acquired) return { acquired: false, ...(first.heldBy?.holder ? { heldBy: first.heldBy.holder } : {}) };
+  const lease = first.lease!;
+  // A renewal that fails is retried on the next beat; one the lease refuses
+  // means another holder took it after it expired, and there is nothing to renew.
+  const timer = setInterval(() => {
+    void acquireLease(op, holder, { cwd: opts.cwd, ttlMs, mode: "renew", token: lease.token }).catch(() => undefined);
+  }, Math.max(1, Math.floor(ttlMs / 3)));
+  timer.unref?.();
+  let released = false;
+  return {
+    acquired: true,
+    lease,
+    release: async () => {
+      if (released) return;
+      released = true;
+      clearInterval(timer);
+      await releaseLease(op, holder, lease.token, { cwd: opts.cwd }).catch(() => false);
+    },
+  };
+}
+
+/** How long a ready step may run when it names no `timeout`. */
+export const DEFAULT_READY_TIMEOUT_MS = 120_000;
+
+/** What one ready step said: whether there is work and its keys, or why it could not say. */
+export type ReadyAnswer = { ready: boolean; keys: string[] } | { error: string };
+
+/**
+ * Run a steward's `ready` step for an Op beside its turns (#2861) and read
+ * its answer with {@link readinessKeys}. The step is one activity call, with
+ * its own `timeout` or {@link DEFAULT_READY_TIMEOUT_MS}; it runs outside any
+ * run, so it writes no record, and it is the author's to keep it a read.
+ */
+export async function askReady(
+  step: ActivityStep,
+  activities: Map<string, ActivityFn>,
+  signal?: AbortSignal,
+): Promise<ReadyAnswer> {
+  const fn = activities.get(step.fn);
+  if (!fn) return { error: `its ready step's activity "${step.fn}" is not loaded` };
+  const timeoutMs = step.timeout ? parseDuration(step.timeout) : DEFAULT_READY_TIMEOUT_MS;
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const call = Promise.resolve(fn({ ...(step.args ?? {}) }, controller.signal));
+    call.catch(() => {});
+    const result = await Promise.race([
+      call,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new Error(`timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }),
+    ]);
+    const answer = readinessKeys(result);
+    if (!answer) return { error: "its ready step answered neither true, false, null, a string nor a list" };
+    return answer;
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  } finally {
+    if (timer) clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}

package/src/op/steward-points.test.ts

@@ -19,7 +19,8 @@ import { readMemberStewards } from "../workspace/status-stewards";
 import { readRunLedger } from "../lifecycle/run-ledger";
 import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import { runOpLocally } from "./local-executor";
-import { formatRoundLine, runOperatorRound } from "./operator";
+import { createBesideState, formatRoundLine, runOperatorRound, waitForBesideRuns } from "./operator";
+import { inProcessBesideLauncher } from "./steward-beside";
 import { declareSteward } from "./steward";
 import { askPointInRun, isPointWait, PointWait, type BrokeredModelAsk } from "./steward-points";
 import { enterStewardTurn, resetStewardTurn, STEWARD_ENV } from "./steward-turn";
@@ -362,3 +363,62 @@ describe("a waiting run of an Op the steward does not list (studio#137)", () =>
     expect(listed).not.toContain("factory-stranger");
   });
 });
+
+describe("a waiting run of an Op beside the steward's turns (#2861)", () => {
+  test("status lists it under the steward with its lease, and the operator resumes it beside the turns once a person answers", async () => {
+    const build = shipOp("box-build", "r-30");
+    const steward = declareSteward({
+      name: "build-steward",
+      ops: [],
+      beside: [{ op: build, ready: { kind: "activity", fn: "readyShip", args: {} } }],
+      capabilities: ["inference"],
+    });
+    const log: string[] = [];
+    const acts = new Map<string, ActivityFn>([
+      ...shipActivities(log),
+      ["askShip", async (args) => (await askPointInRun({ cwd: root, point: "ship-now", inputs: { release: args.release }, subject: String(args.release), on })).answer],
+      ["readyShip", async () => ["r-30"]],
+    ]);
+    const besideState = createBesideState();
+    const launchBeside = inProcessBesideLauncher(acts, PROFILES);
+    const round = () => runOperatorRound({ cwd: root, steward, activities: acts, profiles: PROFILES, holder: "box", besideState, launchBeside });
+
+    // The ready step names work: the run starts beside the turns, asks, and waits.
+    const first = await round();
+    expect(first).toEqual([expect.objectContaining({ kind: "beside-started", op: "box-build", why: "ready", keys: ["r-30"], holder: "build-steward/box-build@box" })]);
+    await waitForBesideRuns(besideState);
+    const waiting = (await readRunLedger("local", "box-build", { cwd: root })).records.at(-1)!;
+    expect(waiting).toMatchObject({ status: "waiting", steward: "build-steward" });
+    const question = waiting.point!.id;
+
+    // workspace status lists it under the steward, as one of its Ops, with its wait.
+    mkdirSync(join(root, "ops"), { recursive: true });
+    writeFileSync(join(root, "chant.config.json"), "{}\n");
+    writeFileSync(join(root, "ops", "build-steward.op.ts"), `export const steward = ${JSON.stringify(steward)};\n`);
+    const status = await readMemberStewards(root, "local", "2027-01-01T00:01:00Z");
+    const entry = status.stewards.find((s) => s.name === "build-steward")!;
+    const stewardShape = contract({ $schema: statusSchema.$schema, $id: "urn:test:status-steward-beside", $defs: statusSchema.$defs, $ref: "#/$defs/steward" });
+    stewardShape.expectValid(entry);
+    expect(entry.ops.map((o) => [o.name, o.beside])).toEqual([["box-build", { ready: true, lease: null }]]);
+    expect(entry.waiting).toEqual([
+      { op: "box-build", run: waiting.id, id: question, point: "ship-now", state: "escalated", path: waiting.point!.path, subject: "r-30", since: waiting.point!.since },
+    ]);
+
+    // Still open: the same work is not started again, and the round says what it waits on.
+    const second = await round();
+    expect(second).toEqual([
+      { kind: "beside-ended", op: "box-build", env: "local", code: 3 },
+      { kind: "waiting-on-point", op: "box-build", env: "local", point: "ship-now", question, state: "escalated" },
+    ]);
+
+    // A person answers; the next round starts the run again beside the turns.
+    const answered = await answerPoint({ cwd: root, id: question, answer: "yes", by: ["alice"], on });
+    expect("error" in answered).toBe(false);
+    const third = await round();
+    expect(third).toEqual([expect.objectContaining({ kind: "beside-started", op: "box-build", why: "resumed", resumed: question })]);
+    await waitForBesideRuns(besideState);
+    expect(log).toEqual(["ship"]);
+    expect((await readRunLedger("local", "box-build", { cwd: root })).records.at(-1)).toMatchObject({ status: "ok", steward: "build-steward" });
+    expect((await readMemberStewards(root, "local", "2027-01-01T00:11:00Z")).stewards.find((s) => s.name === "build-steward")!.waiting).toEqual([]);
+  });
+});