@intentius/chant 0.93.0 → 0.95.0

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
@@ -1284,9 +1295,10 @@ async function loadPluginsOrExit(path: string): Promise<import("../lexicon").Lex
  * #2700 — whether `path` is the root of a declared workspace and holds no
  * lexicon of its own: no `lexicons` in a root config, and no lexicon import in
  * the root's source, which leaves the members' directories out (#2527). A
- * generated chud repo is this shape: its lexicons are all in `delivery/`.
- * `chant serve mcp` starts there instead of refusing with "No lexicon
- * detected", and serves core with the chant members' lexicons.
+ * generated app repo can be this shape: its lexicons are all under a
+ * delivery directory, not the root. `chant serve mcp` starts there instead of
+ * refusing with "No lexicon detected", and serves core with the chant
+ * members' lexicons.
  *
  * A directory with no workspace declaration costs only `findWorkspaceRoot`'s
  * existence checks, so a level-0 project reaches `loadPluginsOrExit` as before.

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

@@ -2,12 +2,12 @@
  * #2700 — the lexicons `chant serve mcp` loads at the root of a declared
  * workspace that has no lexicon of its own.
  *
- * Such a root (a generated chud repo, say, whose lexicons are all in
- * `delivery/`) used to refuse with "No lexicon detected", so an agent started
- * there got none of chant's tools. The server now starts with core's tools and
- * resources, and with the lexicons of the workspace's members of kind chant,
- * each read from that member's own config the way `chant build` in the
- * member's directory reads it.
+ * Such a root (a generated app repo, say, whose lexicons are all under a
+ * delivery directory) used to refuse with "No lexicon detected", so an agent
+ * started there got none of chant's tools. The server now starts with core's
+ * tools and resources, and with the lexicons of the workspace's members of
+ * kind chant, each read from that member's own config the way `chant build`
+ * in the member's directory reads it.
  *
  * Loading is best effort, one member and one lexicon at a time: a member whose
  * config does not load, or a lexicon this chant cannot import, is left out and

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/serve-mcp-workspace.test.ts

@@ -73,8 +73,8 @@ describe("chant serve mcp at a workspace root with no lexicon of its own (#2700)
     expect(init.instructions).toContain("Member delivery (delivery/) declares docker.");
   }, TIMEOUT);
 
-  test("a chud-shaped root, lexicons only in a member, serves core and the lexicons that load", () => {
-    const root = join(scratch, "chud-shaped");
+  test("a lexiconless root, lexicons only in a member, serves core and the lexicons that load", () => {
+    const root = join(scratch, "lexiconless-shaped");
     mkdirSync(join(root, ".git"), { recursive: true });
     mkdirSync(join(root, "delivery"), { recursive: true });
     mkdirSync(join(root, "app"), { recursive: true });
@@ -87,9 +87,9 @@ describe("chant serve mcp at a workspace root with no lexicon of its own (#2700)
       ],
       pins: [],
     }));
-    // `chud` is not installed here, as it would not be for a chant without
-    // @intentius/chud: it is named as not loaded and the rest is served.
-    writeFileSync(join(root, "delivery", "chant.config.ts"), 'export default { lexicons: ["docker", "chud"] };\n');
+    // `acme` names a lexicon package that isn't installed here: it is named
+    // as not loaded and the rest is served.
+    writeFileSync(join(root, "delivery", "chant.config.ts"), 'export default { lexicons: ["docker", "acme"] };\n');
     writeFileSync(join(root, "app", "server.js"), "// not chant\n");
 
     const { status, stderr, init, tools } = initializeAndList(root);
@@ -97,7 +97,7 @@ describe("chant serve mcp at a workspace root with no lexicon of its own (#2700)
     for (const name of CORE_TOOLS) expect(tools).toContain(name);
     expect(tools).toContain("docker:diff");
     expect(init.instructions).toContain('workspace "t"');
-    expect(init.instructions).toContain("Lexicon chud did not load");
+    expect(init.instructions).toContain("Lexicon acme did not load");
     expect(init.instructions).toContain("Lexicon tools and resources served: docker.");
   }, TIMEOUT);
 

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/activities/decide.test.ts

@@ -65,6 +65,14 @@ afterAll(async () => {
 });
 
 describe("decide against the stub (#2740)", () => {
+  test("points --json carries each point's criteria, as the points file declares it (#2853)", async () => {
+    const doc = await workspacePoints({ cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.points.find((p) => p.name === "triage")?.criteria).toEqual({ true: "A person looks at it today.", false: "It can wait." });
+    expect(doc.points.find((p) => p.name === "route")?.criteria).toEqual({ platform: "The platform team.", app: "The app team.", docs: "The docs team." });
+    expect(doc.points.find((p) => p.name === "effort")?.criteria).toEqual(["low", "medium", "high"]);
+  });
+
   test("a noul: the model's answer at the threshold is recorded as proposed, and the run waits on it", async () => {
     script = { triage: { type: "noul", noul: 0.91 } };
     const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 5, "record.risky": true }, subject: "T-1" }));

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 {