@intentius/chant 0.94.0 → 0.95.0

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([]);
+  });
+});

package/src/op/steward.ts

@@ -55,9 +55,36 @@
  * (`workLease`, #2748): its leased steps get a worktree of their own on
  * `chant/work/<item>`. `declareSteward` refuses such an Op without the lease,
  * and a scheduled Op whose lease leaves the item to the run.
+ *
+ * ## Beside the turns
+ *
+ * An Op listed under `beside` (#2861) is the steward's too, but its runs are
+ * not turns. A build that takes half an hour would otherwise hold every other
+ * Op of the steward, converge included, for its whole length. The local
+ * operator starts a run of it as a `chant run <op>` process of its own, with
+ * `CHANT_STEWARD` set so the run is still the steward's, and goes on with its
+ * rounds. One run at a time: the run holds the Op's own lease
+ * (`refs/chant/lease/<op>`), renewed while it runs, and never the turn lease.
+ * The operator starts one on the Op's cron, when its `ready` step says there
+ * is work, or to resume a run of the steward's that waited on a question now
+ * answered (or a gate now approved).
+ *
+ * ```ts
+ * export const steward = declareSteward({
+ *   name: "box-steward",
+ *   ops: [converge, release],
+ *   beside: [{ op: dispatch, ready: shell("node ops/ready.mjs", { json: true }) }],
+ * });
+ * ```
+ *
+ * `ops` on the normalised declaration is every Op the steward runs, beside
+ * ones last, so a reader that only asks "whose Op is this" (discovery's
+ * two-writers check, `chant run`, `workspace status`) needs nothing new.
+ * `beside` names the ones that run beside the turns.
  */
 
-import type { OpConfig } from "./types";
+import type { ActivityStep, OpConfig } from "./types";
+import { collectStepOutputRefs } from "./step-output-ref";
 import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 import { workLeaseNeedsRunItem, workLeaseProblems } from "./work-lease-decl";
 
@@ -83,11 +110,35 @@ export const STEWARD_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
  */
 export type StewardOpInput = OpConfig | { props: unknown };
 
+/**
+ * An Op that runs beside the steward's turns (#2861): the Op alone, or the
+ * Op with the step that says when there is work for it.
+ */
+export type StewardBesideInput = StewardOpInput | { op: StewardOpInput; ready?: ActivityStep };
+
+/** An Op that runs beside the steward's turns, normalised. */
+export interface StewardBeside {
+  /** The Op's name; its config is in the declaration's `ops`. */
+  readonly op: string;
+  /**
+   * The step the operator runs each round, while no run of the Op is in
+   * flight, to ask whether there is work: see {@link readinessKeys}. Null
+   * for an Op started only on its cron, to resume a run, or by hand.
+   */
+  readonly ready: ActivityStep | null;
+}
+
 export interface StewardDeclarationConfig {
   /** The steward's name. On Fountain, the Agent's and the Teammate's. */
   name: string;
   /** The Ops it runs. A scheduled one runs on its cron; any other runs when asked. */
   ops: StewardOpInput[];
+  /**
+   * Ops it runs beside its turns (#2861), each in a process of its own under
+   * the Op's own lease, so a long run holds none of `ops` up. See the module
+   * doc.
+   */
+  beside?: StewardBesideInput[];
   /** Where it runs. Default `local`. */
   form?: StewardFormSpec;
   /**
@@ -105,7 +156,13 @@ export interface StewardDeclarationConfig {
 export interface StewardDeclaration {
   readonly kind: typeof STEWARD_KIND;
   readonly name: string;
+  /** Every Op it runs: its turns' Ops, then those that run beside them. */
   readonly ops: readonly OpConfig[];
+  /**
+   * The Ops of `ops` that run beside its turns (#2861). Read it through
+   * {@link stewardBesideOf}: a declaration made by an older core has none.
+   */
+  readonly beside?: readonly StewardBeside[];
   readonly form: { readonly default: StewardForm; readonly environments: Readonly<Record<string, StewardForm>> };
   /** Brokered box capabilities its Ops use (#2726). Empty when it names none. */
   readonly capabilities: readonly string[];
@@ -140,11 +197,22 @@ export function normaliseStewardForm(steward: string, spec: StewardFormSpec | un
   return { default: checkForm(steward, spec.default, "form.default"), environments };
 }
 
+/** A `beside` entry's Op and ready step, whichever of the two forms it was given in. */
+function besideEntry(entry: StewardBesideInput): { op: OpConfig; ready: ActivityStep | null } {
+  const e = entry as { op?: unknown; ready?: ActivityStep; phases?: unknown; props?: unknown };
+  if (e && typeof e === "object" && e.op !== undefined && e.phases === undefined && e.props === undefined) {
+    return { op: stewardOpConfig(e.op as StewardOpInput), ready: e.ready ?? null };
+  }
+  return { op: stewardOpConfig(entry as StewardOpInput), ready: null };
+}
+
 /**
  * Declare a steward. Refuses what would make it more than one writer or a
  * promise it can't keep: an Op listed twice, a schedule whose overlap isn't
  * `skip` (a fire while a turn runs is dropped in both forms), a cron that
- * doesn't parse, and a name a lease ref can't hold.
+ * doesn't parse, and a name a lease ref can't hold. For an Op beside the
+ * turns (#2861), also a `ready` that is not one activity step, or that reads
+ * another step's output (it runs on its own, outside any run).
  */
 export function declareSteward(config: StewardDeclarationConfig): StewardDeclaration {
   const name = config.name;
@@ -153,7 +221,8 @@ export function declareSteward(config: StewardDeclarationConfig): StewardDeclara
       `Steward ${JSON.stringify(name)}: a steward's name is letters, digits, ".", "_" and "-", starting with a letter or digit`,
     );
   }
-  const ops = config.ops.map(stewardOpConfig);
+  const besides = (config.beside ?? []).map(besideEntry);
+  const ops = [...config.ops.map(stewardOpConfig), ...besides.map((b) => b.op)];
   const seen = new Set<string>();
   for (const op of ops) {
     if (!op || typeof op.name !== "string" || !Array.isArray(op.phases)) {
@@ -172,6 +241,22 @@ export function declareSteward(config: StewardDeclarationConfig): StewardDeclara
           `Name the item, candidates, or the step whose output picks it.`,
       );
     }
+    const beside = besides.find((b) => b.op === op);
+    if (beside?.ready) {
+      const ready = beside.ready;
+      if (!ready || ready.kind !== "activity" || typeof ready.fn !== "string") {
+        throw new Error(`Steward "${name}": op "${op.name}": ready is one activity step, such as shell("...", { json: true })`);
+      }
+      if (collectStepOutputRefs(ready.args ?? {}).length > 0) {
+        throw new Error(`Steward "${name}": op "${op.name}": its ready step reads another step's output, and it runs outside any run`);
+      }
+      if (workLeaseNeedsRunItem(op)) {
+        throw new Error(
+          `Steward "${name}": op "${op.name}" is started when its ready step says so, but its workLease names no item, and such a run can't be given one. ` +
+            `Name the item, candidates, or the step whose output picks it.`,
+        );
+      }
+    }
     const schedule = op.schedule;
     if (!schedule) continue;
     if (!isValidCronExpression(schedule.cron)) {
@@ -199,6 +284,7 @@ export function declareSteward(config: StewardDeclarationConfig): StewardDeclara
     kind: STEWARD_KIND,
     name,
     ops: Object.freeze([...ops]),
+    beside: Object.freeze(besides.map((b) => Object.freeze({ op: b.op.name, ready: b.ready }))),
     form: normaliseStewardForm(name, config.form),
     capabilities: Object.freeze(capabilities),
     vault,
@@ -219,6 +305,52 @@ export function isStewardDeclaration(value: unknown): value is StewardDeclaratio
   );
 }
 
+/** The Ops a steward runs beside its turns (#2861); none for a declaration without the field. */
+export function stewardBesideOf(steward: StewardDeclaration): readonly StewardBeside[] {
+  return Array.isArray(steward.beside) ? steward.beside : [];
+}
+
+/** The entry for `op` when the steward runs it beside its turns (#2861), or undefined. */
+export function stewardBesideFor(steward: StewardDeclaration, op: string): StewardBeside | undefined {
+  return stewardBesideOf(steward).find((b) => b.op === op);
+}
+
+/** The Ops a steward runs as its turns, one at a time: `ops` without the beside ones. */
+export function stewardTurnOps(steward: StewardDeclaration): OpConfig[] {
+  const beside = new Set(stewardBesideOf(steward).map((b) => b.op));
+  return steward.ops.filter((op) => !beside.has(op.name));
+}
+
+/**
+ * What a `ready` step's result says (#2861): the work keys it names, or null
+ * when its result is not one of the shapes below. The value read is the
+ * result's `json` when it has one (a `shell` step with `json: true`), or the
+ * result itself.
+ *
+ * - an array: one key per entry (a string as is, anything else as its JSON);
+ *   empty means no work;
+ * - a non-empty string: one key; `""` means no work;
+ * - `true` means work, with no key; `false` and `null` mean none.
+ *
+ * The operator starts a run when a key is one it has not started a run for
+ * yet, so a run that ends with the same work still ready is not started
+ * again for it. `true` has no key, so it starts a run whenever none is in
+ * flight.
+ */
+export function readinessKeys(result: unknown): { ready: boolean; keys: string[] } | null {
+  const value = result && typeof result === "object" && !Array.isArray(result) && "json" in result
+    ? (result as { json: unknown }).json
+    : result;
+  if (value === true) return { ready: true, keys: [] };
+  if (value === false || value === null || value === undefined) return { ready: false, keys: [] };
+  if (typeof value === "string") return value === "" ? { ready: false, keys: [] } : { ready: true, keys: [value] };
+  if (Array.isArray(value)) {
+    const keys = value.map((v) => (typeof v === "string" ? v : JSON.stringify(v)));
+    return { ready: keys.length > 0, keys };
+  }
+  return null;
+}
+
 /** The form a steward takes in `env` (`local` when none is named). */
 export function stewardFormFor(steward: StewardDeclaration, env: string = DEFAULT_STEWARD_ENV): StewardForm {
   return steward.form.environments[env] ?? steward.form.default;

package/src/workspace/box-services.test.ts

@@ -0,0 +1,129 @@
+/**
+ * #2880: a box block declares its services. The declaration reads them, a
+ * `needs` naming no service of the block or forming a cycle, a name given
+ * twice and a second httpPort each fail the read (declaration-invalid), so
+ * `chant workspace check` fails with WSP001, and `readBoxServices` gives the
+ * list of the member a process runs in.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { parseDeclaration, WorkspaceReadError } from "./declaration";
+import { readBoxServices } from "./box-services";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-box-services-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const declaration = (services: unknown[]) =>
+  JSON.stringify(
+    {
+      name: "acme",
+      schema: 1,
+      members: [
+        { name: "app", dir: "app", kind: "other", because: "the app" },
+        { name: "box", dir: "box", kind: "other", because: "the box's steward and its Ops", box: { services } },
+      ],
+    },
+    null,
+    2,
+  );
+
+const parse = (services: unknown[]) => parseDeclaration(declaration(services), "chant.workspace.json");
+
+/** The error a declaration's read fails with, as its code and message. */
+function readFailure(services: unknown[]): { code: string; message: string; line: number | undefined } {
+  try {
+    parse(services);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return { code: err.code, message: err.message, line: err.location?.line };
+    throw err;
+  }
+  throw new Error("the declaration read");
+}
+
+const TWO = [
+  { name: "app", cmd: "${HOME}/box/run-app.sh", duration: "3s", health: "http://127.0.0.1:5173/health" },
+  { name: "hud", cmd: "${HOME}/box/run-daemon.sh", needs: ["app"], httpPort: 8080 },
+];
+
+describe("the services of a box block (#2880)", () => {
+  test("two services, one needing the other, read with every field", () => {
+    expect(parse(TWO).members[1].box?.services).toEqual([
+      { name: "app", cmd: "${HOME}/box/run-app.sh", needs: [], httpPort: null, duration: "3s", health: "http://127.0.0.1:5173/health", optional: false, pointer: "/members/1/box/services/0" },
+      { name: "hud", cmd: "${HOME}/box/run-daemon.sh", needs: ["app"], httpPort: 8080, duration: null, health: null, optional: false, pointer: "/members/1/box/services/1" },
+    ]);
+    expect(parseDeclaration(JSON.stringify({ name: "a", schema: 1, members: [{ name: "b", dir: "b", kind: "other", because: "x", box: {} }] }), "chant.workspace.json").members[0].box?.services).toEqual([]);
+  });
+
+  test("a needs naming no service of the block is declaration-invalid, at the entry", () => {
+    const f = readFailure([TWO[0], { ...TWO[1], needs: ["api"] }]);
+    expect(f.code).toBe("declaration-invalid");
+    expect(f.message).toBe(`member box's box service hud needs "api", which the block does not declare; declared services: app, hud`);
+  });
+
+  test("needs that form a cycle are declaration-invalid, and so is a service that needs itself", () => {
+    const cycle = readFailure([
+      { name: "a", cmd: "a", needs: ["c"] },
+      { name: "b", cmd: "b", needs: ["a"] },
+      { name: "c", cmd: "c", needs: ["b"] },
+    ]);
+    expect(cycle).toMatchObject({ code: "declaration-invalid", message: "member box's box services need each other in a cycle: a -> c -> b -> a" });
+    expect(readFailure([{ name: "a", cmd: "a", needs: ["a"] }]).message).toMatch(/cycle: a -> a$/);
+  });
+
+  test("a name given twice, and a second httpPort, are declaration-invalid", () => {
+    expect(readFailure([TWO[0], { ...TWO[0], cmd: "other" }])).toMatchObject({ code: "declaration-invalid", message: expect.stringMatching(/declares the service app twice; the first is at \/members\/1\/box\/services\/0/) });
+    expect(readFailure([{ ...TWO[0], httpPort: 5173 }, TWO[1]]).message).toMatch(/gives both app \(port 5173\) and hud \(port 8080\) an httpPort/);
+  });
+
+  test("the schema refuses a service with no cmd, an unknown field, a malformed duration or a health that is no URL", () => {
+    expect(readFailure([{ name: "app" }]).code).toBe("declaration-invalid");
+    expect(readFailure([{ ...TWO[0], restart: "always" }]).message).toMatch(/unknown field "restart"/);
+    expect(readFailure([{ ...TWO[0], duration: "3 seconds" }]).code).toBe("declaration-invalid");
+    expect(readFailure([{ ...TWO[0], health: "/health" }]).code).toBe("declaration-invalid");
+  });
+
+  test("chant workspace check passes the valid block and fails the invalid one with WSP001 declaration-invalid", async () => {
+    const good = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/.keep": "" });
+    expect((await runDeclarationChecks(good)).diagnostics.filter((d) => d.ruleId === "WSP001")).toEqual([]);
+    const bad = repo({ "chant.workspace.json": declaration([TWO[0], { ...TWO[1], needs: ["api"] }]), "app/.keep": "", "box/.keep": "" });
+    const found = (await runDeclarationChecks(bad)).diagnostics;
+    expect(found.map((d) => [d.ruleId, d.severity, d.code])).toEqual([["WSP001", "error", "declaration-invalid"]]);
+    expect(found[0].message).toMatch(/needs "api", which the block does not declare/);
+  });
+});
+
+describe("readBoxServices (#2880)", () => {
+  test("reads the services of the member whose directory holds the working directory", () => {
+    const root = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/ops/.keep": "" });
+    const read = readBoxServices(join(root, "box", "ops"));
+    expect(read.member).toBe("box");
+    expect(read.root).toBe(root);
+    expect(read.services.map((s) => [s.name, s.needs])).toEqual([["app", []], ["hud", ["app"]]]);
+  });
+
+  test("a member with no box block, a directory no member holds, and no workspace are errors", () => {
+    const root = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/.keep": "", "elsewhere/.keep": "" });
+    expect(() => readBoxServices(join(root, "app"))).toThrow(/member app \(app\) has no box block/);
+    expect(() => readBoxServices(join(root, "elsewhere"))).toThrow(/no member of the workspace/);
+    const none = repo({ "x/.keep": "" });
+    expect(() => readBoxServices(join(none, "x"))).toThrow(/no chant.workspace.json/);
+  });
+});