@intentius/chant 0.94.0 → 0.95.0

package/src/cli/handlers/operator-steward-signal.e2e.test.ts

@@ -0,0 +1,97 @@
+/**
+ * #2872 — `chant operator --steward` releases its lease on a repeated
+ * SIGTERM.
+ *
+ * A supervisor that signals both a process group and a child (arugula-salad
+ * /studio's box smoke does exactly this) sends a second SIGTERM close behind
+ * the first. `process.once("SIGTERM", onSigint)` tears the listener down the
+ * instant it fires the first time — before `onSigint` even runs, let alone
+ * before the `finally` block that releases the steward's lease — so that
+ * second signal finds nothing listening and takes Node's default
+ * disposition: the process ends right there. The next `chant operator
+ * --steward` then refuses with "already running (lease held by ...)" until
+ * the stale lease expires.
+ *
+ * This spawns the real CLI (not the handler in-process) so a broken fix
+ * kills only the child, never the test runner itself, the way `process.once`
+ * would if it were still there. See ../../cli/handlers/operator.ts around
+ * "chant operator --steward" for the fix (`process.on`, kept registered for
+ * the whole shutdown).
+ */
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, repo, REPO } from "../../workspace/__fixtures__/contract-repo";
+import { readLease } from "../../lifecycle/lease";
+import { stewardLeaseName } from "../../op/steward";
+
+const MAIN = join(REPO, "packages/core/src/cli/main.ts");
+const LOADER = pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href;
+const CHANT = [process.execPath, "--import", LOADER, MAIN];
+
+/** The shape `declareSteward({ name: "box-steward", ops: [] })` returns — written as a literal so the fixture's `ops/steward.op.ts` needs no import to resolve. */
+const STEWARD_DECLARATION = {
+  kind: "Chant::Steward",
+  name: "box-steward",
+  ops: [],
+  form: { default: "local", environments: {} },
+};
+
+afterAll(() => cleanScratch());
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe("chant operator --steward — a repeated SIGTERM (#2872)", () => {
+  test("a second and third SIGTERM sent in quick succession still release the steward's lease", async () => {
+    const dir = repo(
+      {
+        "chant.config.ts": "export default { lexicons: [] };\n",
+        "ops/steward.op.ts": `export const steward = ${JSON.stringify(STEWARD_DECLARATION)};\n`,
+      },
+      true,
+    );
+
+    const child = spawn(
+      CHANT[0],
+      [...CHANT.slice(1), "operator", "--steward", "--interval", "200ms"],
+      { cwd: dir, env: { ...process.env, NO_COLOR: "1", TSX_DISABLE_CACHE: "1" } },
+    );
+    let stderr = "";
+    child.stderr.on("data", (d) => (stderr += d));
+    const exited = new Promise<number | null>((resolve) => child.on("close", resolve));
+
+    // Wait until the steward has actually acquired its lease — a running,
+    // mid-loop process — rather than firing signals at one still starting up
+    // (tsx's cold start is not instant).
+    const deadline = Date.now() + 15_000;
+    for (;;) {
+      const { record } = await readLease(stewardLeaseName("box-steward"), { cwd: dir });
+      if (record) break;
+      if (Date.now() > deadline) {
+        child.kill("SIGKILL");
+        throw new Error(`the steward never acquired its lease; stderr so far:\n${stderr}`);
+      }
+      await sleep(50);
+    }
+
+    // Three SIGTERMs, each given a moment to actually reach the child's event
+    // loop before the next: with `process.once`, the first one's auto-removal
+    // happens the instant it fires, so the second (or third) finds no
+    // listener left and the process exits right there, skipping the
+    // `finally` that releases the lease.
+    child.kill("SIGTERM");
+    await sleep(30);
+    child.kill("SIGTERM");
+    await sleep(30);
+    child.kill("SIGTERM");
+
+    const code = await exited;
+    expect(code, `chant operator --steward did not exit cleanly; stderr:\n${stderr}`).toBe(0);
+
+    const { record } = await readLease(stewardLeaseName("box-steward"), { cwd: dir });
+    expect(record, "the steward's lease was not released").toBeUndefined();
+  }, 20_000);
+});

package/src/cli/handlers/operator.ts

@@ -12,7 +12,7 @@ import { build } from "../../build";
 import { isResourceDeclarable } from "../../declarable";
 import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins";
 import { discoverOps, discoverStewards } from "../../op/discover";
-import { pickSteward, stewardFormFor, stewardLeaseName, DEFAULT_STEWARD_ENV } from "../../op/steward";
+import { pickSteward, stewardBesideOf, stewardFormFor, stewardLeaseName, stewardTurnOps, DEFAULT_STEWARD_ENV } from "../../op/steward";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { parseDuration } from "../../op/local-executor";
 import {
@@ -23,6 +23,8 @@ import {
   formatSignalLine,
   DEFAULT_OPERATOR_INTERVAL_MS,
   acquireStewardLease,
+  createBesideState,
+  waitForBesideRuns,
   type ChangeSubscriber,
   type OperatorSignalEvent,
   type OperatorTickEvent,
@@ -168,11 +170,21 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
   const leaseTtlMs = ctx.args.leaseTtl ? parseDuration(ctx.args.leaseTtl) : DEFAULT_LEASE_TTL_MS;
 
   const controller = new AbortController();
+  // `process.on`, not `.once`: a `.once` listener is gone the instant it
+  // fires, so a second SIGINT arriving while shutdown is still in flight
+  // (the `finally` below hasn't run yet) has no listener left and takes
+  // Node's default disposition — the process ends right there, before
+  // whatever the `finally` was going to do. Kept registered for the whole
+  // shutdown and only removed once it's actually over; `stopping` makes a
+  // repeat signal a no-op rather than a second `abort()`/log line (#2872).
+  let stopping = false;
   const onSigint = () => {
+    if (stopping) return;
+    stopping = true;
     console.error(formatWarning({ message: "interrupted — stopping operator" }));
     controller.abort();
   };
-  process.once("SIGINT", onSigint);
+  process.on("SIGINT", onSigint);
 
   const printRound = (events: OperatorTickEvent[]) => {
     for (const event of events) console.error(formatInfo(formatRoundLine(event)));
@@ -268,30 +280,54 @@ export async function runStewardOperator(ctx: CommandContext): Promise<number> {
   }
 
   const controller = new AbortController();
+  // `process.on`, not `.once` (#2872): a supervisor that signals both a
+  // process group and a child sends a second SIGTERM close behind the
+  // first. A `.once` listener has already unregistered itself by then, so
+  // that second signal takes Node's default disposition and ends the
+  // process immediately — before the `finally` below releases the
+  // steward's lease. Kept registered for the whole shutdown and removed
+  // only once it's over, so a second, third or later signal is a no-op
+  // (`stopping` guards against re-aborting or re-logging) rather than a
+  // fast exit that skips the release.
+  let stopping = false;
   const onSigint = () => {
+    if (stopping) return;
+    stopping = true;
     console.error(formatWarning({ message: "interrupted — stopping steward" }));
     controller.abort();
   };
-  process.once("SIGINT", onSigint);
-  process.once("SIGTERM", onSigint);
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigint);
 
   const printRound = (events: OperatorTickEvent[]) => {
     for (const event of events) console.error(formatInfo(formatRoundLine(event)));
   };
 
-  const scheduled = steward.ops.filter((op) => op.schedule !== undefined);
+  const turnOps = stewardTurnOps(steward);
+  const scheduled = turnOps.filter((op) => op.schedule !== undefined);
+  const beside = stewardBesideOf(steward).map((b) => b.op);
   try {
     if (ctx.args.once) {
-      const events = await runOperatorRound({ steward, holder, leaseTtlMs, activities, profiles, signal: controller.signal });
+      // One round, and the runs it started beside the turns (#2861) to their end.
+      const besideState = createBesideState();
+      const events = await runOperatorRound({ steward, holder, leaseTtlMs, activities, profiles, signal: controller.signal, besideState, stewardEnv: env });
       printRound(events);
-      return events.some((e) => e.kind === "tick-failed" || e.kind === "steward-busy") ? 1 : 0;
+      await waitForBesideRuns(besideState);
+      const ended = besideState.ended.splice(0);
+      printRound(ended);
+      return events.some((e) => e.kind === "tick-failed" || e.kind === "steward-busy" || e.kind === "ready-failed") ||
+        ended.some((e) => e.kind === "beside-ended" && e.code !== 0 && e.code !== 3)
+        ? 1
+        : 0;
     }
     console.error(formatInfo(
-      `chant operator: steward ${steward.name} (local) runs ${scheduled.length} scheduled Op(s) of ${steward.ops.length}, ` +
-        `checking every ${intervalMs}ms (Ctrl-C to stop)`,
+      `chant operator: steward ${steward.name} (local) runs ${scheduled.length} scheduled Op(s) of ${turnOps.length} as its turns` +
+        (beside.length > 0 ? `, and ${beside.join(", ")} beside them` : "") +
+        `, checking every ${intervalMs}ms (Ctrl-C to stop)`,
     ));
     await runOperatorForever({
       steward,
+      stewardEnv: env,
       holder,
       intervalMs,
       leaseTtlMs,
@@ -302,11 +338,17 @@ export async function runStewardOperator(ctx: CommandContext): Promise<number> {
     });
     return 0;
   } finally {
-    process.removeListener("SIGINT", onSigint);
-    process.removeListener("SIGTERM", onSigint);
+    // The listeners stay registered through this whole `finally`, not just
+    // the `try` above (#2872): the lease release below is itself async (two
+    // more git plumbing calls), and a repeat signal landing in that window
+    // is exactly the shape the issue reported — removing the listeners
+    // first, before awaiting the release, would reopen the same hole one
+    // step later. `stopping` (set already) makes every repeat here a no-op.
     // A courtesy: the lease expires on its own if this never runs.
     const { record } = await readLease(stewardLeaseName(steward.name)).catch(() => ({ record: undefined }));
     if (record?.holder === holder) await releaseLease(stewardLeaseName(steward.name), holder, record.token).catch(() => false);
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigint);
   }
 }
 

package/src/cli/handlers/run.test.ts

@@ -11,6 +11,7 @@ const discoverOpsMock = vi.fn();
 // default is what every other call sees.
 const discoverStewardsMock = vi.fn().mockResolvedValue({ stewards: new Map(), errors: [], conflicts: [] });
 const acquireStewardTurnMock = vi.fn();
+const holdBesideLeaseMock = vi.fn();
 const releaseLeaseMock = vi.fn();
 const loadChantConfigMock = vi.fn();
 const writeFileSyncMock = vi.fn();
@@ -33,6 +34,10 @@ vi.mock("../../op/operator", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../../op/operator")>();
   return { ...actual, acquireStewardTurn: (...args: unknown[]) => acquireStewardTurnMock(...args) };
 });
+vi.mock("../../op/steward-beside", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../op/steward-beside")>();
+  return { ...actual, holdBesideLease: (...args: unknown[]) => holdBesideLeaseMock(...args) };
+});
 vi.mock("../../lifecycle/lease", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../../lifecycle/lease")>();
   return { ...actual, releaseLease: (...args: unknown[]) => releaseLeaseMock(...args) };
@@ -438,6 +443,72 @@ describe("runOp: a steward's turn (#2750)", () => {
   });
 });
 
+/**
+ * chant #2861: `chant run <op>` for an Op a steward runs beside its turns
+ * takes the Op's own lease, as `--holder`, and never the steward's turn.
+ * `holdBesideLease` is stubbed; `op/steward-beside.test.ts` runs it against a
+ * real repo.
+ */
+describe("runOp: an Op beside a steward's turns (#2861)", () => {
+  function stewardBeside(opName: string, name: string) {
+    return {
+      stewards: new Map([[name, {
+        declaration: {
+          kind: "Chant::Steward", name, ops: [{ name: "converge", phases: [] }, { name: opName, phases: [] }],
+          beside: [{ op: opName, ready: null }],
+          form: { default: "local", environments: {} }, capabilities: [], vault: null,
+        },
+        filePath: "ops/steward.op.ts", exportName: "steward",
+      }]]),
+      errors: [], conflicts: [],
+    };
+  }
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: {} });
+    loadPluginsMock.mockReset().mockResolvedValue([]);
+    acquireStewardTurnMock.mockReset();
+    holdBesideLeaseMock.mockReset();
+    releaseLeaseMock.mockReset().mockResolvedValue(true);
+  });
+
+  test("takes the Op's lease as --holder, not the turn, runs, and releases it once the run is over", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("dispatch", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    discoverStewardsMock.mockResolvedValueOnce(stewardBeside("dispatch", "box-steward"));
+    const release = vi.fn(async () => {});
+    holdBesideLeaseMock.mockResolvedValue({ acquired: true, lease: { op: "dispatch", holder: "h", token: "t1", acquiredAt: "x", expiresAt: "y" }, release });
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = await runOp({ args: makeArgs({ path: "dispatch", holder: "box-steward/dispatch@op1" }), plugins: [], serializers: [] });
+    stderrWrite.mockRestore();
+
+    expect(exit).toBe(0);
+    expect(acquireStewardTurnMock).not.toHaveBeenCalled();
+    expect(holdBesideLeaseMock).toHaveBeenCalledWith("dispatch", "box-steward/dispatch@op1");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  test("a run of it in progress: refused, naming the holder, nothing runs", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("dispatch", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    discoverStewardsMock.mockResolvedValueOnce(stewardBeside("dispatch", "box-steward"));
+    holdBesideLeaseMock.mockResolvedValue({ acquired: false, heldBy: "box-steward/dispatch@op1" });
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "dispatch" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain(`runs beside steward "box-steward"'s turns`);
+    expect(out).toContain("box-steward/dispatch@op1");
+    expect(acquireStewardTurnMock).not.toHaveBeenCalled();
+  });
+});
+
 /**
  * chant #2243 — a gated run's exit code is the one thing `--gated-exit`
  * remaps, and the gate is reported where CI can see it without opening a log.

package/src/cli/handlers/run.ts

@@ -17,7 +17,8 @@ import { recordGateApproval } from "./operator";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
-import { stewardFormFor, stewardTurnLeaseName, DEFAULT_STEWARD_ENV, type StewardDeclaration } from "../../op/steward";
+import { stewardBesideFor, stewardFormFor, stewardTurnLeaseName, DEFAULT_STEWARD_ENV, type StewardDeclaration } from "../../op/steward";
+import { holdBesideLease } from "../../op/steward-beside";
 import { acquireStewardTurn, STEWARD_TURN_WAIT_MS } from "../../op/operator";
 import { releaseLease, currentHolderId, type AcquireLeaseResult } from "../../lifecycle/lease";
 import { StaleLockError } from "../../lifecycle/git";
@@ -557,6 +558,12 @@ type StewardTurnGate =
  * hand. Ctrl-C already means "abort my own run" here; it must not also mean
  * "give up waiting for someone else's turn".
  *
+ * An Op the steward runs beside its turns (#2861) takes the Op's own lease
+ * instead, renewed for as long as the run lasts, and never the turn: the run
+ * is one at a time with the runs the operator starts of it, and holds none
+ * of the steward's other Ops up. Held already, it refuses at once, naming
+ * the holder.
+ *
  * `undefined` (via the caller checking `owner`) when no steward lists this
  * op — the ordinary, untouched path.
  */
@@ -585,6 +592,8 @@ async function stewardTurnGate(opName: string, ctx: CommandContext): Promise<Ste
     };
   }
 
+  if (stewardBesideFor(owner, opName)) return besideLeaseGate(opName, owner.name, ctx);
+
   const holder = currentHolderId();
   let turn: AcquireLeaseResult;
   try {
@@ -619,6 +628,36 @@ async function stewardTurnGate(opName: string, ctx: CommandContext): Promise<Ste
   return { ok: true, release: async () => { await releaseLease(stewardTurnLeaseName(stewardName), holder, lease.token).catch(() => false); } };
 }
 
+/**
+ * The lease a `chant run` of an Op beside a steward's turns holds (#2861):
+ * the Op's own, as `--holder` (the operator passes `<steward>/<op>@<its
+ * holder>`) or this process.
+ */
+async function besideLeaseGate(opName: string, steward: string, ctx: CommandContext): Promise<StewardTurnGate> {
+  const holder = ctx.args.holder ?? currentHolderId();
+  let held;
+  try {
+    held = await holdBesideLease(opName, holder);
+  } catch (err) {
+    return {
+      ok: false,
+      message: `Op "${opName}" runs beside steward "${steward}"'s turns, and its lease could not be read`,
+      hint:
+        `${err instanceof StaleLockError ? err.message : err instanceof Error ? err.message : String(err)} ` +
+        `This can happen when a process was killed mid-write; check refs/chant/lease/${opName} for a stale lock.`,
+    };
+  }
+  if (!held.acquired) {
+    return {
+      ok: false,
+      message: `Op "${opName}" runs beside steward "${steward}"'s turns, one run at a time, and a run of it is in progress` +
+        (held.heldBy ? ` (held by ${held.heldBy})` : ""),
+      hint: `Wait for that run to end and re-run \`chant run ${opName}\`; \`chant workspace status --json\` lists it under the steward. Its lease expires on its own if the process holding it died.`,
+    };
+  }
+  return { ok: true, release: held.release };
+}
+
 export async function runOp(ctx: CommandContext): Promise<number> {
   if (ctx.args.generate) {
     if (ctx.args.components) {
@@ -975,20 +1014,35 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
   // runs under; it is taken where the run executes, which for a hosted
   // runtime is not this process.
   const work = await resolveRunWork(ctx, config, runtime.name);
-  if (work === null) return 1;
+  if (work === null) {
+    await stewardGate?.release?.();
+    return 1;
+  }
 
   // `--progress-json` streams one NDJSON StepRecord per settled step, fed by
   // whatever the runtime reports through `progress`.
   const progress = ctx.args.progressJson ? ndjsonProgressSink<StepRecord>() : undefined;
 
-  // Ctrl-C aborts in-flight activities (kills their child processes) instead of
-  // orphaning them. The handler is removed in `finally` so it never leaks.
+  // Ctrl-C, or a SIGTERM (the signal a steward's operator sends this process
+  // when it runs beside the steward's turns and the operator itself stops,
+  // and what a plain `kill <pid>` sends with no signal named), aborts
+  // in-flight activities (kills their child processes) instead of orphaning
+  // them. `process.on`, not `.once` (chant#2872's shape, here too): a second
+  // signal arriving before the `finally` below has released this run's lease
+  // (`stewardGate`, for a beside run) must not fall through to Node's default
+  // disposition and skip that release. `stopping` makes a repeat a no-op; the
+  // listeners are removed only after the release, at the very end of
+  // `finally`, not before it.
   const controller = new AbortController();
+  let stopping = false;
   const onSigint = () => {
+    if (stopping) return;
+    stopping = true;
     console.error(formatWarning({ message: "interrupted — stopping Op" }));
     controller.abort();
   };
-  process.once("SIGINT", onSigint);
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigint);
 
   try {
     const handle = await runtime.start(config, {
@@ -1065,10 +1119,14 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
   } finally {
-    process.removeListener("SIGINT", onSigint);
     // The turn is over, win or lose — free it so the steward's next round,
-    // or the next hand run, doesn't wait out this run's own TTL (#2750).
+    // or the next hand run, doesn't wait out this run's own TTL (#2750). The
+    // listeners stay registered until after this release (chant#2872): it is
+    // itself async, and removing them first would let a repeat signal in
+    // that window fall through to Node's default disposition and skip it.
     await stewardGate?.release?.();
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigint);
   }
 }
 

package/src/cli/main.ts

@@ -90,6 +90,7 @@ const BOOLEAN_FLAGS = new Set([
   "--no-release-record",
   "--fold",
   "--no-fold",
+  "--no-cache",
   "--sandbox",
   "--yes",
   "--confirm-prod",
@@ -481,6 +482,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.noReleaseRecord = true;
     } else if (arg === "--fold") {
       result.fold = true;
+    } else if (arg === "--no-cache") {
+      // `chant workspace graph --no-cache` (#2876): read every member.
+      result.noCache = true;
     } else if (arg === "--no-fold") {
       // chant #1134 — fold is the default build path; this is the explicit
       // opt-out, and like --fold it beats chant.config.ts's build.fold.
@@ -748,7 +752,9 @@ Ops:
                         CronJob invokers use this instead of the daemon).
                         --steward [<name>] runs a declared steward's local
                         form instead (#2731): its scheduled Ops on their
-                        crons, under the steward's own lease
+                        crons, under the steward's own lease, and its
+                        beside Ops as chant run processes of their own
+                        (#2861)
   operator status        Last tick, outcomes, and pending gates per
                         ConvergeOp, read from the chant/lifecycle orphan
                         branch alone — no daemon needs to be running
@@ -841,10 +847,12 @@ Workspace (level 1, #2524):
                         Set top-level fields of one record. A closed record
                         never changes, and an approved one changes only its
                         state (upward), pins and reviews; anything else is
-                        refused with amend-supersede-instead. --sign seals
-                        the author again; without it an amendment removes
-                        the author seal and says so. Prints
-                        {path, id, changed}
+                        refused with amend-supersede-instead. Moving a
+                        record to its kind's ratified state (ratified for
+                        decisions) is refused with ratify-quorum-not-met
+                        until its quorum is met. --sign seals the author
+                        again; without it an amendment removes the author
+                        seal and says so. Prints {path, id, changed}
   workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]
                         Append a review to one record, dated and bound to
                         the digest of the record text. A dissent needs
@@ -931,7 +939,10 @@ Workspace (level 1, #2524):
                         with <member>/<id> ids and groups.byMember: the
                         read-contract document. --at <rev> runs each member's
                         source as it was at that commit; --kind adds the
-                        records' asset and constrains links
+                        records' asset and constrains links. A member whose
+                        source and toolchain are unchanged is served from
+                        the cache in $CHANT_CACHE_DIR or ~/.cache/chant;
+                        --no-cache reads every member
   workspace graph --composites [--at <rev>] [--member <name>] [-o <file>]
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance

package/src/cli/mcp/workspace-tools.ts

@@ -195,7 +195,7 @@ export const workspaceWriteTools: ToolDefinition[] = [
   {
     name: "records-amend",
     description:
-      "Set top-level fields of a record: chant workspace records amend. A closed record never changes, and an approved one changes only in its state, evidence and reviews: anything else, its reasoning included, is a new record that supersedes it. A source block given in the fields records that the change came through MCP. " +
+      "Set top-level fields of a record: chant workspace records amend. A closed record never changes, and an approved one changes only in its state, evidence and reviews: anything else, its reasoning included, is a new record that supersedes it. A record moves to its kind's ratified state only once its review quorum is met (ratify-quorum-not-met). A source block given in the fields records that the change came through MCP. " +
       PROTOCOL,
     inputSchema: {
       type: "object",

package/src/cli/registry.ts

@@ -299,6 +299,8 @@ export interface ParsedArgs {
   subject?: string;
   /** `chant workspace points answer <id> --answer <value>` (#2739): the people's answer. */
   answer?: string;
+  /** `chant workspace graph --no-cache` (#2876): read every member, bypassing the per-member cache. */
+  noCache?: boolean;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
   /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */

package/src/cli/static-config-read.test.ts

@@ -72,7 +72,9 @@ afterEach(() => {
 function chant(args: string[], cwd: string): string {
   const result = spawnSync(process.execPath, ["--import", tsxLoader, mainTs, ...args], {
     cwd,
-    env: { PATH: process.env.PATH ?? "", HOME: home },
+    // TMPDIR passes through so tsx caches under the run's temp directory
+    // (chant#2864), not the machine-wide default this scrubbed env would give.
+    env: { PATH: process.env.PATH ?? "", HOME: home, TMPDIR: tmpdir() },
     encoding: "utf-8",
     input: "n\n",
     timeout: 60_000,
@@ -105,7 +107,11 @@ describe("commands that read path lexicons statically run no project code", () =
 
   test("a config it cannot read is reported, and still not run", () => {
     writeConfig(`process.env.CI ? ["github"] : [{ name: "github", module: "./gh/index.ts" }]`);
-    const output = chant(["dev", "onboard", "github"], project);
+    // `import --agents` rather than `dev onboard`: with the config unread,
+    // github is treated as a package, and onboard then patches the chant
+    // repo it runs from (its CI workflow, chant#2863). Both commands print
+    // the notice from the same recordProjectLexicons read.
+    const output = chant(["import", "--agents", "--lexicon", "github", "--output", join(root, "out")], project);
     expect(output).toContain("could not read the lexicons in");
     expect(output).toContain("treated as a package");
     expect(existsSync(marker)).toBe(false);

package/src/meta/source-is-text.test.ts

@@ -27,11 +27,28 @@ import { fileURLToPath } from "node:url";
  */
 const SRC = fileURLToPath(new URL("../", import.meta.url));
 
+/**
+ * Run `read`, or return undefined when the path is gone. Other test files
+ * create and delete fixtures under src while this one walks it
+ * (lint/config.test.ts's `__test_config__`, chant#2870), so an entry listed a
+ * moment ago may no longer exist.
+ */
+function unlessGone<T>(read: () => T): T | undefined {
+  try {
+    return read();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw err;
+  }
+}
+
 /** Every TypeScript file under core's src, tests and fixtures included. */
 function sourceFiles(dir: string): string[] {
-  return readdirSync(dir).flatMap((entry) => {
+  return (unlessGone(() => readdirSync(dir)) ?? []).flatMap((entry) => {
     const path = join(dir, entry);
-    if (statSync(path).isDirectory()) return entry === "node_modules" ? [] : sourceFiles(path);
+    const stat = unlessGone(() => statSync(path));
+    if (stat === undefined) return [];
+    if (stat.isDirectory()) return entry === "node_modules" ? [] : sourceFiles(path);
     return /\.(ts|mts|cts)$/.test(entry) ? [path] : [];
   });
 }
@@ -40,7 +57,8 @@ describe("source files are text, not binary (chant#2280)", () => {
   test("no shipped source file contains a NUL byte", () => {
     const offenders: string[] = [];
     for (const file of sourceFiles(SRC)) {
-      const buf = readFileSync(file);
+      const buf = unlessGone(() => readFileSync(file));
+      if (buf === undefined) continue;
       const at = buf.indexOf(0);
       if (at !== -1) offenders.push(`${relative(SRC, file)} (first at byte ${at})`);
     }

package/src/okf.test.ts

@@ -155,7 +155,12 @@ const exampleCases: Array<[string, string]> = [
 
 describe("buildOkfBundle over shipped examples", () => {
   for (const [name, rel] of exampleCases) {
-    test(`${name} emits a conformant, snapshot-stable bundle`, async () => {
+    // The test's own `expect` names the snapshot after this test. The global
+    // one names it after whichever test is current, so when a slow discover
+    // outlives its timeout and the next case starts, a late call records
+    // under the next case's name and the checkout gains a "... 2" snapshot
+    // (chant#2863).
+    test(`${name} emits a conformant, snapshot-stable bundle`, async ({ expect }) => {
       const projectPath = resolve(repoRoot, rel);
       const result = await discover(projectPath);
       expect(result.errors).toEqual([]);

package/src/op/builders.ts

@@ -916,10 +916,21 @@ export const spriteApplyNetworkPolicy = (args: {
   return activity("spriteApplyNetworkPolicy", rest, profile ?? "fastIdempotent");
 };
 
-/** Reconcile a sprite's background services (create-or-update, optionally start). Defaults to the `fastIdempotent` profile (override via `profile`). */
+/**
+ * Reconcile a sprite's background services (create-or-update, optionally
+ * start). With an `id`, through the Sprites API and its `services`; without
+ * one, inside the sprite through sprite-env, applying the box block's
+ * services (`box: true`, #2880): `only` names some of them, `start` starts
+ * the applied ones that are not running, `restart` restarts the converged
+ * ones. Defaults to the `fastIdempotent` profile (override via `profile`).
+ */
 export const spriteApplyServices = (args: {
-  id: string;
-  services: Array<{
+  id?: string;
+  box?: boolean;
+  only?: string[];
+  restart?: boolean;
+  spriteEnv?: string;
+  services?: Array<{
     name: string;
     cmd: string;
     args?: string[];

package/src/op/index.ts

@@ -109,15 +109,21 @@ export type {
 export {
   discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
   formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS, acquireStewardLease,
-  acquireStewardTurn, STEWARD_TURN_WAIT_MS,
+  acquireStewardTurn, STEWARD_TURN_WAIT_MS, createBesideState, waitForBesideRuns, stopBesideRuns,
 } from "./operator";
+export type { BesideState } from "./operator";
+export {
+  spawnBesideRun, inProcessBesideLauncher, holdBesideLease, askReady, DEFAULT_READY_TIMEOUT_MS,
+} from "./steward-beside";
+export type { BesideStart, BesideExit, BesideHandle, BesideLauncher, BesideWhy, HeldBesideLease, ReadyAnswer } from "./steward-beside";
 export {
   declareSteward, isStewardDeclaration, stewardFormFor, stewardOpConfig, normaliseStewardForm, stewardLeaseName,
-  stewardTurnLeaseName,
+  stewardTurnLeaseName, stewardBesideOf, stewardBesideFor, stewardTurnOps, readinessKeys,
   STEWARD_KIND, STEWARD_FORMS, STEWARD_NAME_PATTERN, DEFAULT_STEWARD_ENV,
 } from "./steward";
 export type {
   StewardDeclaration, StewardDeclarationConfig, StewardForm, StewardFormSpec, StewardOpInput,
+  StewardBeside, StewardBesideInput,
 } from "./steward";
 export { discoverStewards } from "./discover";
 export {