@intentius/chant-lexicon-fly 0.90.0 → 0.93.0

package/src/op/activities/sprite-service-converge.test.ts

@@ -0,0 +1,268 @@
+/**
+ * #2778 — a box's services as resources a ConvergeOp observes and converges.
+ *
+ * `sprite-env` here is a stand-in with the command line a sprite's has (and
+ * the studio kit's has): `services list` prints `name<TAB>state`, and
+ * `restart`/`stop`/`start` flip the state kept in a directory. A small HTTP
+ * server answers each service's health URL with 200 while it runs. `chant`
+ * on PATH stands in for `chant run <op>`: it runs what the dispatched
+ * `restart-service` Op would, `sprite-env services restart
+ * "$CHANT_CONVERGE_RESOURCE"`, and records the call.
+ */
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { ConvergeOp, declareSteward, eq, loadActivities, run, runOpLocally, when, type ActivityFn, type OpConfig, type ResourceSymptom } from "@intentius/chant/op";
+import { convergeTick } from "@intentius/chant/op/activities";
+import { readConvergeLedger } from "@intentius/chant/lifecycle/converge-ledger";
+import { readMemberStewards } from "@intentius/chant/workspace/status-stewards";
+import { createSpritesFake } from "./sprites-fake";
+import { spriteCreate } from "./sprites";
+import { spriteServiceCreate, spriteServiceStop } from "./sprite-services";
+import { parseServicesList, spriteServiceRestart, spriteServicesObserve } from "./sprite-service-converge";
+import { spriteServicesObserve as observeStep } from "../builders";
+
+let dir: string;
+let bin: string;
+let state: string;
+let server: Server;
+let port = 0;
+const saved = { PATH: process.env.PATH, cwd: process.cwd(), STATE: process.env.FAKE_SPRITE_STATE, RESOURCE: process.env.CHANT_CONVERGE_RESOURCE };
+
+const SPRITE_ENV = `#!/usr/bin/env node
+const { readdirSync, readFileSync, writeFileSync, existsSync } = require("node:fs");
+const { join } = require("node:path");
+const dir = process.env.FAKE_SPRITE_STATE;
+const [group, verb, name] = process.argv.slice(2);
+if (group !== "services") process.exit(2);
+const file = (n) => join(dir, n);
+if (verb === "list") {
+  for (const n of readdirSync(dir).sort()) console.log(n + "\\t" + readFileSync(file(n), "utf8").trim() + "\\t-\\t-\\tcmd");
+} else if (["restart", "start", "stop"].includes(verb)) {
+  if (!existsSync(file(name))) { console.error("sprite-env: no service " + name); process.exit(1); }
+  writeFileSync(file(name), verb === "stop" ? "stopped" : "running");
+} else process.exit(2);
+`;
+
+const CHANT = `#!/bin/sh
+# chant run <op> --json, as far as a converge dispatch goes.
+echo "$2 $CHANT_CONVERGE_RESOURCE" >> "$FAKE_SPRITE_STATE/../dispatched"
+exec sprite-env services restart "$CHANT_CONVERGE_RESOURCE"
+`;
+
+function git(...args: string[]): void {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+}
+
+const health = (name: string) => `http://127.0.0.1:${port}/${name}`;
+const setState = (name: string, value: string) => writeFileSync(join(state, name), value);
+
+beforeAll(async () => {
+  dir = mkdtempSync(join(tmpdir(), "chant-sprite-converge-"));
+  bin = join(dir, ".bin");
+  state = join(dir, ".state", "services");
+  mkdirSync(bin, { recursive: true });
+  mkdirSync(state, { recursive: true });
+  writeFileSync(join(bin, "sprite-env"), SPRITE_ENV);
+  writeFileSync(join(bin, "chant"), CHANT);
+  chmodSync(join(bin, "sprite-env"), 0o755);
+  chmodSync(join(bin, "chant"), 0o755);
+  server = createServer((req, res) => {
+    const name = (req.url ?? "/").slice(1);
+    const up = existsSync(join(state, name)) && readFileSync(join(state, name), "utf8").trim() === "running";
+    res.writeHead(up ? 200 : 503).end(up ? "ok" : "down");
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  port = (server.address() as AddressInfo).port;
+  process.env.PATH = `${bin}:${process.env.PATH}`;
+  process.env.FAKE_SPRITE_STATE = state;
+  git("init", "-q", "-b", "main");
+  git("config", "user.email", "converge@example.com");
+  git("config", "user.name", "Converge Test");
+  git("config", "commit.gpgsign", "false");
+  writeFileSync(join(dir, "chant.config.json"), "{}\n");
+  writeFileSync(join(dir, ".gitignore"), ".bin\n.state\n");
+  git("add", "-A");
+  git("commit", "-q", "-m", "c0");
+});
+
+afterAll(async () => {
+  process.chdir(saved.cwd);
+  process.env.PATH = saved.PATH;
+  if (saved.STATE === undefined) delete process.env.FAKE_SPRITE_STATE;
+  else process.env.FAKE_SPRITE_STATE = saved.STATE;
+  if (saved.RESOURCE === undefined) delete process.env.CHANT_CONVERGE_RESOURCE;
+  else process.env.CHANT_CONVERGE_RESOURCE = saved.RESOURCE;
+  await new Promise<void>((r) => server.close(() => r()));
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("parseServicesList", () => {
+  test("reads a sprite-env's JSON and a stand-in's table", () => {
+    expect(parseServicesList(JSON.stringify([{ name: "app", cmd: "x", state: { name: "app", status: "running" } }, { name: "hud", status: "stopped" }]))).toEqual(
+      new Map([["app", "running"], ["hud", "stopped"]]),
+    );
+    expect(parseServicesList("app\trunning\t-\t-\tnode a\nsite\tstarting\t-\t-\tnode s\n")).toEqual(new Map([["app", "running"], ["site", "starting"]]));
+    expect(parseServicesList("")).toEqual(new Map());
+  });
+});
+
+describe("spriteServicesObserve through sprite-env (#2778)", () => {
+  test("in sync, stopped, not answering, not defined, optional, and a supervisor that can't be read", async () => {
+    setState("app", "running");
+    setState("hud", "stopped");
+    setState("door", "running");
+    const services = [
+      { name: "app", health: health("app") },
+      { name: "hud", health: health("hud") },
+      { name: "door", health: `http://127.0.0.1:${port}/nothing-here` },
+      { name: "extra" },
+      { name: "site", health: health("site"), optional: true },
+    ];
+    const seen = await spriteServicesObserve({ services, probes: 2, probeIntervalMs: 10 });
+    expect(seen.skipped).toEqual(["site"]);
+    expect(seen.resources.map((r) => [r.name, r.status])).toEqual([
+      ["app", "in-sync"],
+      ["hud", "drifted"],
+      ["door", "drifted"],
+      ["extra", "drifted"],
+    ]);
+    expect(seen.resources[2].detail).toMatch(/does not answer 200 after 2 tries/);
+    expect(seen.resources[3].detail).toMatch(/no such service/);
+
+    const unread = await spriteServicesObserve({ services: [{ name: "app" }], spriteEnv: join(dir, "missing-sprite-env") });
+    expect(unread.resources).toEqual([{ name: "app", status: "unknown", detail: expect.stringMatching(/could not be read/) }]);
+
+    // The declared list can live in a file the box already has.
+    writeFileSync(join(dir, "services.json"), JSON.stringify({ services: [{ name: "app", health: health("app") }] }));
+    const fromFile = await spriteServicesObserve({ servicesFile: join(dir, "services.json"), probes: 1 });
+    expect(fromFile.resources).toEqual([{ name: "app", status: "in-sync", detail: expect.stringContaining("answers 200") }]);
+  });
+
+  test("spriteServiceRestart restarts the resource a converge rule dispatched it for, and waits for its health", async () => {
+    setState("hud", "stopped");
+    process.env.CHANT_CONVERGE_RESOURCE = "hud";
+    try {
+      await expect(spriteServiceRestart({ services: [{ name: "hud", health: health("hud") }], waitMs: 2000 })).resolves.toEqual({ name: "hud", healthy: true });
+    } finally {
+      delete process.env.CHANT_CONVERGE_RESOURCE;
+    }
+    expect(readFileSync(join(state, "hud"), "utf8")).toBe("running");
+    await expect(spriteServiceRestart({})).rejects.toThrow(/CHANT_CONVERGE_RESOURCE/);
+    await expect(spriteServiceRestart({ name: "nope" })).rejects.toThrow(/no service nope/);
+  });
+});
+
+describe("spriteServicesObserve through the Sprites API (#2778)", () => {
+  test("reads each service's state, and restarts one with stop and start", async () => {
+    const fake = await createSpritesFake();
+    try {
+      await spriteCreate({ name: "box-1", endpoint: fake.url });
+      await spriteServiceCreate({ id: "box-1", name: "app", cmd: "node app.js", endpoint: fake.url });
+      await spriteServiceCreate({ id: "box-1", name: "hud", cmd: "node hud.js", endpoint: fake.url });
+      await spriteServiceStop({ id: "box-1", name: "hud", endpoint: fake.url });
+      const seen = await spriteServicesObserve({ id: "box-1", endpoint: fake.url, services: [{ name: "app" }, { name: "hud" }] });
+      expect(seen.resources.map((r) => [r.name, r.status])).toEqual([["app", "in-sync"], ["hud", "drifted"]]);
+      await spriteServiceRestart({ id: "box-1", endpoint: fake.url, name: "hud" });
+      const after = await spriteServicesObserve({ id: "box-1", endpoint: fake.url, services: [{ name: "app" }, { name: "hud" }] });
+      expect(after.resources.every((r) => r.status === "in-sync")).toBe(true);
+    } finally {
+      await fake.close();
+    }
+  });
+});
+
+describe("a ConvergeOp over a box's services (#2778)", () => {
+  test("records the stopped service drifted, dispatches the restart its rule names, and records the next tick in sync", async () => {
+    const activities = await loadActivities(["fly"]);
+    expect(activities.has("spriteServicesObserve")).toBe(true);
+    expect(activities.has("spriteServiceRestart")).toBe(true);
+    const run$ = new Map<string, ActivityFn>([...activities, ["convergeTick", convergeTick as unknown as ActivityFn]]);
+
+    setState("app", "running");
+    setState("hud", "running");
+    rmSync(join(state, "door"), { force: true });
+    rmSync(join(state, "extra"), { force: true });
+    const services = [
+      { name: "app", health: health("app") },
+      { name: "hud", health: health("hud") },
+    ];
+    const { op } = ConvergeOp({
+      name: "box-converge",
+      env: "box",
+      dial: "apply",
+      observe: observeStep({ services, probes: 1 }),
+      rules: [
+        when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), {
+          id: "restart-drifted",
+          why: "A declared service that stopped or stopped answering is restarted through its supervisor.",
+        }),
+        when<ResourceSymptom>(eq("status", "unknown"), { kind: "report", reason: "a service could not be observed" }, {
+          id: "report-unknown",
+          why: "unknown never remediates.",
+        }),
+      ],
+    });
+    const config = (op as unknown as { props: OpConfig }).props;
+
+    // Stop one of the two.
+    spawnSync("sprite-env", ["services", "stop", "app"], { env: process.env });
+    const steward = declareSteward({ name: "box-steward", ops: [config] });
+    mkdirSync(join(dir, "ops"), { recursive: true });
+    writeFileSync(join(dir, "ops", "steward.op.ts"), `export const steward = ${JSON.stringify(steward)};\n`);
+    const lastTick = async () => {
+      const status = await readMemberStewards(dir, "local", new Date().toISOString());
+      expect(status.reasons).toEqual([]);
+      return status.stewards[0].ops[0];
+    };
+
+    process.chdir(dir);
+    try {
+      const first = await runOpLocally(config, run$, {}, undefined, { cwd: dir, ledger: { cwd: dir } });
+      expect(first.status).toBe("ok");
+      // workspace status shows the converge Op's last tick, with the rule that fired and for which service.
+      const afterFirst = await lastTick();
+      expect(afterFirst.lastRun).toMatchObject({ status: "ok" });
+      expect(afterFirst.lastTick).toMatchObject({
+        firedRuleIds: ["restart-drifted"],
+        outcomes: [{ ruleId: "restart-drifted", action: "ran", op: "restart-service", resource: "app", reason: null }],
+        resources: [{ name: "app", status: "drifted", detail: "stopped" }, { name: "hud", status: "in-sync" }],
+      });
+      const second = await runOpLocally(config, run$, {}, undefined, { cwd: dir, ledger: { cwd: dir } });
+      expect(second.status).toBe("ok");
+    } finally {
+      process.chdir(saved.cwd);
+    }
+
+    expect(readFileSync(join(dir, ".state", "dispatched"), "utf8").trim().split("\n")).toEqual(["restart-service app"]);
+    const ticks = (await readConvergeLedger("box", { cwd: dir })).records;
+    expect(ticks).toHaveLength(2);
+    expect(ticks[0]).toMatchObject({
+      op: "box-converge",
+      firedRuleIds: ["restart-drifted"],
+      outcomes: [{ ruleId: "restart-drifted", action: "ran", op: "restart-service", resource: "app" }],
+      resources: [
+        { name: "app", status: "drifted" },
+        { name: "hud", status: "in-sync" },
+      ],
+      summary: { drifted: 1, remediated: 1 },
+    });
+    expect(ticks[1]).toMatchObject({
+      firedRuleIds: [],
+      outcomes: [],
+      resources: [
+        { name: "app", status: "in-sync" },
+        { name: "hud", status: "in-sync" },
+      ],
+      summary: { drifted: 0, remediated: 0 },
+    });
+
+    expect((await lastTick()).lastTick).toMatchObject({ firedRuleIds: [], outcomes: [], resources: [{ name: "app", status: "in-sync" }, { name: "hud", status: "in-sync" }] });
+  });
+});

package/src/op/activities/sprite-service-converge.ts

@@ -0,0 +1,268 @@
+/**
+ * A sprite's services as resources a `ConvergeOp` observes and converges
+ * (#2778).
+ *
+ * A box runs its app, hud, door and site as services a supervisor keeps
+ * running: sprite-env on a sprite, and a stand-in with the same command line
+ * elsewhere. No lexicon declares them, so a ConvergeOp can't observe them
+ * through an environment. It can through an observer step:
+ *
+ * - `spriteServicesObserve` reads the supervisor's list and probes each
+ *   declared service's health URL, and returns one verdict per service,
+ *   `in-sync`, `drifted` or `unknown`: the `ResourceObservation` a
+ *   `ConvergeOp({ observe })` evaluates its rules against, once per service.
+ * - `spriteServiceRestart` restarts one service through the supervisor and
+ *   waits for its health URL. It is the step of the Op a rule dispatches; the
+ *   service is the one the rule fired for, which the dispatched run reads
+ *   from `CHANT_CONVERGE_RESOURCE`.
+ *
+ * Both work in one of two ways. With no sprite `id`, they run inside the
+ * sprite and call `sprite-env services` (found on PATH or in /.sprite/bin,
+ * or at `spriteEnv`). With an `id`, they go through the Sprites API
+ * (`spriteServiceList`, `spriteServiceStop` and `spriteServiceStart`).
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { spriteServiceList, spriteServiceStart, spriteServiceStop } from "./sprite-services";
+import type { SpritesHttp } from "./sprites";
+import { defaultSpritesHttp } from "./sprites";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The variable a ConvergeOp's dispatched run reads its resource from
+ * (core's `CONVERGE_RESOURCE_ENV`). Spelled out here so the lexicon runs
+ * against a core that predates the export.
+ */
+const CONVERGE_RESOURCE_ENV = "CHANT_CONVERGE_RESOURCE";
+
+/** One service a box declares. */
+export interface DeclaredSpriteService {
+  name: string;
+  /** A URL that answers 200 while the service works. Without one, the supervisor's state decides. */
+  health?: string;
+  /** Not defined yet is not drift: the service is left out until it exists (a site before its first release). */
+  optional?: boolean;
+}
+
+interface Via {
+  /** The sprite, for the Sprites API. Without it, `sprite-env` inside the sprite. */
+  id?: string;
+  /** The `sprite-env` binary. Default: the one on PATH, else /.sprite/bin/sprite-env. */
+  spriteEnv?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServicesObserveArgs extends Via {
+  /** The declared services. */
+  services?: DeclaredSpriteService[];
+  /** A JSON file of `{ services: [...] }`, relative to the working directory, read on each tick. */
+  servicesFile?: string;
+  /** Health probes before a service counts as drifted. Default 3. */
+  probes?: number;
+  /** Time between probes, ms. Default 1000. */
+  probeIntervalMs?: number;
+}
+
+export interface SpriteServicesObserveResult {
+  resources: { name: string; status: "in-sync" | "drifted" | "unknown"; detail: string }[];
+  /** Optional services that aren't defined yet. */
+  skipped: string[];
+}
+
+export interface SpriteServiceRestartArgs extends Via {
+  /** The service. Default: the resource a ConvergeOp dispatched this run for (`CHANT_CONVERGE_RESOURCE`). */
+  name?: string;
+  /** Its health URL. Default: the one `services` or `servicesFile` declares for it. */
+  health?: string;
+  services?: DeclaredSpriteService[];
+  servicesFile?: string;
+  /** How long to wait for the health URL after the restart, ms. Default 60000. */
+  waitMs?: number;
+}
+
+export interface SpriteServiceRestartResult {
+  name: string;
+  /** Whether its health URL answered, or null when it declares none. */
+  healthy: boolean | null;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** The services declared inline and in `servicesFile`, inline first. */
+export function declaredServices(args: { services?: DeclaredSpriteService[]; servicesFile?: string }, cwd = process.cwd()): DeclaredSpriteService[] {
+  const out = [...(args.services ?? [])];
+  if (args.servicesFile) {
+    const parsed = JSON.parse(readFileSync(resolve(cwd, args.servicesFile), "utf8")) as { services?: unknown };
+    if (!Array.isArray(parsed.services)) throw new Error(`${args.servicesFile} has no "services" array`);
+    for (const s of parsed.services as DeclaredSpriteService[]) {
+      if (!s || typeof s.name !== "string") throw new Error(`${args.servicesFile}: a service has no name`);
+      out.push(s);
+    }
+  }
+  return out;
+}
+
+/** The sprite-env binary, or null when there is none. */
+export function findSpriteEnv(explicit?: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  if (explicit) return explicit;
+  for (const dir of (env.PATH ?? "").split(":").concat("/.sprite/bin")) {
+    if (dir && existsSync(join(dir, "sprite-env"))) return join(dir, "sprite-env");
+  }
+  return null;
+}
+
+/**
+ * `sprite-env services list` as name to state. A sprite's sprite-env prints
+ * JSON (an array of services with `state.status`); a stand-in may print a
+ * tab-separated table whose second column is the state. Pure.
+ */
+export function parseServicesList(text: string): Map<string, string | null> {
+  const out = new Map<string, string | null>();
+  const trimmed = text.trim();
+  if (!trimmed) return out;
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    const parsed = JSON.parse(trimmed) as unknown;
+    const list = Array.isArray(parsed) ? parsed : ((parsed as { services?: unknown }).services ?? []);
+    for (const s of list as { name?: unknown; status?: unknown; state?: { status?: unknown } }[]) {
+      if (typeof s?.name !== "string") continue;
+      const status = typeof s.state?.status === "string" ? s.state.status : typeof s.status === "string" ? s.status : null;
+      out.set(s.name, status);
+    }
+    return out;
+  }
+  for (const line of trimmed.split("\n")) {
+    const cols = line.split("\t");
+    if (!cols[0]) continue;
+    out.set(cols[0].trim(), cols[1]?.trim() || null);
+  }
+  return out;
+}
+
+async function listServices(via: Via, signal?: AbortSignal, http?: SpritesHttp): Promise<Map<string, string | null>> {
+  if (via.id) {
+    const list = await spriteServiceList({ id: via.id, endpoint: via.endpoint, token: via.token }, signal, http ?? defaultSpritesHttp(via.token));
+    return new Map(list.map((s) => [s.name, s.state?.status ?? null]));
+  }
+  const bin = findSpriteEnv(via.spriteEnv);
+  if (!bin) throw new Error("no sprite-env on PATH or in /.sprite/bin, and no sprite id to reach the Sprites API with");
+  const { stdout } = await execFileAsync(bin, ["services", "list"], { signal, timeout: 60_000, maxBuffer: 16 * 1024 * 1024 });
+  return parseServicesList(stdout);
+}
+
+/** One GET of a health URL: true on 200. */
+export async function probeHealth(url: string, signal?: AbortSignal): Promise<boolean> {
+  try {
+    const timeout = AbortSignal.timeout(3000);
+    const res = await fetch(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, redirect: "manual" });
+    await res.arrayBuffer().catch(() => undefined);
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+const DOWN = new Set(["stopped", "failed", "stopping"]);
+
+/**
+ * Observe the declared services: one verdict each, for a ConvergeOp's rules.
+ * A service the supervisor doesn't have, or has stopped, is drifted; one
+ * with a health URL is in sync when the URL answers 200 within `probes`
+ * tries and drifted when it doesn't; one without is in sync while it runs.
+ * When the supervisor can't be read, every service is unknown, and unknown
+ * never remediates.
+ */
+export async function spriteServicesObserve(
+  args: SpriteServicesObserveArgs,
+  signal?: AbortSignal,
+  http?: SpritesHttp,
+): Promise<SpriteServicesObserveResult> {
+  const declared = declaredServices(args);
+  const probes = Math.max(1, args.probes ?? 3);
+  const interval = args.probeIntervalMs ?? 1000;
+  let states: Map<string, string | null>;
+  try {
+    states = await listServices(args, signal, http);
+  } catch (err) {
+    const why = err instanceof Error ? err.message.split("\n")[0] : String(err);
+    return {
+      resources: declared.filter((s) => !s.optional).map((s) => ({ name: s.name, status: "unknown" as const, detail: `the supervisor could not be read: ${why}` })),
+      skipped: declared.filter((s) => s.optional).map((s) => s.name),
+    };
+  }
+
+  const resources: SpriteServicesObserveResult["resources"] = [];
+  const skipped: string[] = [];
+  for (const service of declared) {
+    if (!states.has(service.name)) {
+      if (service.optional) skipped.push(service.name);
+      else resources.push({ name: service.name, status: "drifted", detail: "declared, but the supervisor has no such service" });
+      continue;
+    }
+    const state = states.get(service.name) ?? null;
+    if (state !== null && DOWN.has(state)) {
+      resources.push({ name: service.name, status: "drifted", detail: state });
+      continue;
+    }
+    if (service.health) {
+      let ok = false;
+      for (let i = 0; i < probes && !ok; i++) {
+        if (i > 0) await sleep(interval);
+        ok = await probeHealth(service.health, signal);
+      }
+      resources.push(
+        ok
+          ? { name: service.name, status: "in-sync", detail: `${state ?? "listed"}, ${service.health} answers 200` }
+          : { name: service.name, status: "drifted", detail: `${state ?? "listed"}, ${service.health} does not answer 200 after ${probes} tries` },
+      );
+      continue;
+    }
+    resources.push(
+      state === "running"
+        ? { name: service.name, status: "in-sync", detail: "running" }
+        : { name: service.name, status: "unknown", detail: `${state ?? "no state"}, and no health URL to probe` },
+    );
+  }
+  return { resources, skipped };
+}
+
+/**
+ * Restart one service through its supervisor and wait for its health URL.
+ * The service is `name`, or the resource the ConvergeOp's rule fired for.
+ * Throws when neither names one, when the supervisor refuses, or when the
+ * service does not answer its health URL within `waitMs`.
+ */
+export async function spriteServiceRestart(
+  args: SpriteServiceRestartArgs,
+  signal?: AbortSignal,
+  http?: SpritesHttp,
+): Promise<SpriteServiceRestartResult> {
+  const name = args.name ?? process.env[CONVERGE_RESOURCE_ENV];
+  if (!name) {
+    throw new Error(`spriteServiceRestart: no service named: pass \`name\`, or run the Op from a ConvergeOp rule, which sets ${CONVERGE_RESOURCE_ENV}`);
+  }
+  const health = args.health ?? (args.services || args.servicesFile ? declaredServices(args).find((s) => s.name === name)?.health : undefined);
+
+  if (args.id) {
+    const client = http ?? defaultSpritesHttp(args.token);
+    await spriteServiceStop({ id: args.id, name, endpoint: args.endpoint, token: args.token }, signal, client);
+    await spriteServiceStart({ id: args.id, name, endpoint: args.endpoint, token: args.token }, signal, client);
+  } else {
+    const bin = findSpriteEnv(args.spriteEnv);
+    if (!bin) throw new Error("no sprite-env on PATH or in /.sprite/bin, and no sprite id to reach the Sprites API with");
+    await execFileAsync(bin, ["services", "restart", name], { signal, timeout: 120_000 });
+  }
+  console.log(`restarted: ${name}`);
+  if (!health) return { name, healthy: null };
+
+  const until = Date.now() + (args.waitMs ?? 60_000);
+  do {
+    if (await probeHealth(health, signal)) return { name, healthy: true };
+    await sleep(500);
+  } while (Date.now() < until && !signal?.aborted);
+  throw new Error(`${name} was restarted and does not answer ${health}`);
+}

package/src/op/activities/sprites-fake.ts

@@ -70,6 +70,12 @@ interface ExecResult {
   stdout: string;
   stderr: string;
   exitCode: number;
+  /**
+   * Fake-only timing hook (#2765): how long `runExec` should hold the frames
+   * before sending them, set by the `sleep` form below. Lets a test prove
+   * `spriteExec`'s `timeoutMs` fires without a slow real exec.
+   */
+  delayMs?: number;
 }
 
 /**
@@ -77,11 +83,24 @@ interface ExecResult {
  * small set of forms so a test (and the example `guarded-task` Op) can write a
  * key, then overwrite/fail it, and prove restore rewinds. Segments split on
  * `;` run in order; the exit code is the last segment's (shell `;` semantics).
+ *
+ * `opts.env`/`opts.dir` (#2765) are the `env`/`dir` exec options after they
+ * cross the wire (`env` as `KEY=VALUE` strings, mirroring what the query
+ * params carry) — `env` and `pwd` below echo them back so a test can prove
+ * they reached the command. Real spritzer only wires `env`/`dir` through in
+ * container exec mode (real processes); its interpreter mode — what
+ * `fakeExec` otherwise mirrors — has no notion of either, so this pair of
+ * forms is fake-only, proven separately from the container-mode docker test.
  */
-export function fakeExec(sprite: SpriteState, cmd: string): ExecResult {
+export function fakeExec(
+  sprite: SpriteState,
+  cmd: string,
+  opts: { env?: string[]; dir?: string } = {},
+): ExecResult {
   let stdout = "";
   let stderr = "";
   let exitCode = 0;
+  let delayMs: number | undefined;
 
   for (const raw of cmd.split(";")) {
     const seg = raw.trim();
@@ -109,6 +128,19 @@ export function fakeExec(sprite: SpriteState, cmd: string): ExecResult {
       exitCode = 1;
     } else if (seg === "true") {
       exitCode = 0;
+    } else if (seg === "env") {
+      // Prints the passed env, sorted `KEY=VALUE` lines, like the real command.
+      stdout += [...(opts.env ?? [])].sort().map((kv) => `${kv}\n`).join("");
+      exitCode = 0;
+    } else if (seg === "pwd") {
+      stdout += `${opts.dir ?? "/"}\n`;
+      exitCode = 0;
+    } else if ((m = seg.match(/^sleep\s+(\d+)$/))) {
+      // Fake-only timing hook (#2765): the argument is milliseconds, not
+      // seconds like the real command — just enough to hold the exec open
+      // past a short `timeoutMs` without a slow test.
+      exitCode = 0;
+      delayMs = Number(m[1]);
     } else if (seg === "./risky.sh") {
       // A scripted failing job: mutates the workspace, then exits non-zero, so
       // the example guarded-task Op demonstrates checkpoint-as-compensation.
@@ -122,7 +154,7 @@ export function fakeExec(sprite: SpriteState, cmd: string): ExecResult {
     }
   }
 
-  return { stdout, stderr, exitCode };
+  return { stdout, stderr, exitCode, ...(delayMs !== undefined ? { delayMs } : {}) };
 }
 
 function unquote(s: string): string {
@@ -228,14 +260,25 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
     }
     // argv arrives as repeated `cmd` params; reconstruct the script the small
     // interpreter understands (the tokens round-trip for the space-separated
-    // command forms the example Ops use).
+    // command forms the example Ops use). `dir`/`env` (#2765) mirror
+    // spriteExecWsUrl's encoding: `dir` a single param, `env` repeated
+    // `KEY=VALUE` params.
     const argv = url.searchParams.getAll("cmd");
     const script = argv.join(" ");
-    const result = fakeExec(sprite, script);
-    if (result.stdout) ws.send(frame(STREAM_STDOUT, Buffer.from(result.stdout)));
-    if (result.stderr) ws.send(frame(STREAM_STDERR, Buffer.from(result.stderr)));
-    ws.send(frame(STREAM_EXIT, Buffer.of(result.exitCode & 0xff)));
-    ws.close();
+    const dir = url.searchParams.get("dir") ?? undefined;
+    const env = url.searchParams.getAll("env");
+    const result = fakeExec(sprite, script, { dir, env });
+    const send = (): void => {
+      // The client may already have aborted/timed out and closed its end;
+      // sending on a closed socket would throw, so this is a plain no-op.
+      if (ws.readyState !== ws.OPEN) return;
+      if (result.stdout) ws.send(frame(STREAM_STDOUT, Buffer.from(result.stdout)));
+      if (result.stderr) ws.send(frame(STREAM_STDERR, Buffer.from(result.stderr)));
+      ws.send(frame(STREAM_EXIT, Buffer.of(result.exitCode & 0xff)));
+      ws.close();
+    };
+    if (result.delayMs) setTimeout(send, result.delayMs);
+    else send();
   }
 
   async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {

package/src/op/activities/sprites.integration.test.ts

@@ -14,6 +14,7 @@ import {
   type OpConfig,
 } from "@intentius/chant/op";
 import { createSpritesFake } from "./sprites-fake";
+import { spriteCreate as createImpl, spriteExec as execImpl } from "./sprites";
 
 // End-to-end against the in-process fake (S7) — no Docker, runs in CI. The
 // activities resolve by name through `loadActivities(["fly"])` and reach
@@ -154,3 +155,32 @@ describe("guarded-task — checkpoint-as-compensation (S5)", () => {
     expect(state.fs).toEqual({ "/state": "bad" });
   });
 });
+
+describe("spriteExec: timeoutMs, env, dir (#2765)", () => {
+  test("timeoutMs aborts a hung exec and throws a clear timeout error", async () => {
+    await createImpl({ name: "to-1", endpoint: fake.url });
+    // The fake's fake-only `sleep <ms>` form holds the response open past the
+    // timeout, so this proves the abort — not a slow real command.
+    await expect(execImpl({ id: "to-1", cmd: "sleep 500", timeoutMs: 30, endpoint: fake.url })).rejects.toThrow(
+      /timed out after 30ms/,
+    );
+  });
+
+  test("an exec that finishes under timeoutMs still succeeds", async () => {
+    await createImpl({ name: "to-2", endpoint: fake.url });
+    const res = await execImpl({ id: "to-2", cmd: "echo hi", timeoutMs: 5000, endpoint: fake.url });
+    expect(res.stdout).toBe("hi\n");
+  });
+
+  test("env reaches the command", async () => {
+    await createImpl({ name: "env-1", endpoint: fake.url });
+    const res = await execImpl({ id: "env-1", cmd: "env", env: { FOO: "bar", BAZ: "qux" }, endpoint: fake.url });
+    expect(res.stdout.split("\n").filter(Boolean).sort()).toEqual(["BAZ=qux", "FOO=bar"]);
+  });
+
+  test("dir reaches the command", async () => {
+    await createImpl({ name: "dir-1", endpoint: fake.url });
+    const res = await execImpl({ id: "dir-1", cmd: "pwd", dir: "/work/app", endpoint: fake.url });
+    expect(res.stdout).toBe("/work/app\n");
+  });
+});