@intentius/chant 0.91.0 → 0.93.0

package/src/op/steward.test.ts

@@ -4,16 +4,16 @@
  * scheduled Ops under its own lease, and the rule that a steward turn and a
  * coding agent share one checkout without colliding.
  */
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import type { OpConfig } from "./types";
-import { declareSteward, isStewardDeclaration, pickSteward, stewardFormFor, stewardLeaseName } from "./steward";
+import { declareSteward, isStewardDeclaration, pickSteward, stewardFormFor, stewardLeaseName, stewardTurnLeaseName } from "./steward";
 import { discoverOps, discoverStewards } from "./discover";
-import { runOperatorRound, acquireStewardLease, formatRoundLine } from "./operator";
+import { runOperatorRound, acquireStewardLease, acquireStewardTurn, formatRoundLine } from "./operator";
 import { readLease } from "../lifecycle/lease";
 import { readRunLedger } from "../lifecycle/run-ledger";
 
@@ -210,3 +210,87 @@ describe("a local steward round", () => {
     });
   });
 });
+
+describe("a hand run waits its turn (#2750)", () => {
+  test("a round holds the turn lease for exactly the length of its tick — a concurrent hand run sees it held, then free again once the tick ends", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      let releaseTurn: () => void = () => {};
+      const gate = new Promise<void>((resolve) => { releaseTurn = resolve; });
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *", "slowTurn")] });
+      const activities = new Map<string, ActivityFn>([
+        ["slowTurn", async () => { await gate; return { ok: true }; }],
+      ]);
+      // Real time on both sides here, deliberately: a fixed `now` on only one
+      // of the round's and the hand run's leases would make one see the
+      // other's lease as already expired by wall-clock time, which is not
+      // the race this test is about.
+      const roundPromise = runOperatorRound({ cwd: dir, holder: "steward-proc", steward, activities, profiles: PROFILES });
+
+      // Wait for the round to actually be mid-tick, holding the turn lease.
+      await vi.waitFor(async () => {
+        const turn = await readLease(stewardTurnLeaseName("box-steward"), { cwd: dir });
+        expect(turn.record?.holder).toBe("steward-proc");
+      });
+
+      // A hand run's own attempt (no `waitMs`) sees it taken and gives up
+      // without retrying — this is what `chant run <op>` names in its refusal.
+      const midTurn = await acquireStewardTurn("box-steward", "hand-run", { cwd: dir });
+      expect(midTurn.acquired).toBe(false);
+      expect(midTurn.heldBy?.holder).toBe("steward-proc");
+
+      releaseTurn();
+      const events = await roundPromise;
+      expect(events.map((e) => e.kind)).toEqual(["ticked"]);
+
+      // The tick released the turn the moment it finished — succeeds again
+      // right away, not only once the whole steward process stops.
+      const afterTurn = await acquireStewardTurn("box-steward", "hand-run", { cwd: dir });
+      expect(afterTurn.acquired).toBe(true);
+    });
+  });
+
+  test("a hand run's turn blocks a round: it reports turn-busy and ticks nothing, and releases the op lease it had just taken", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+      const held = await acquireStewardTurn("box-steward", "hand-run", { cwd: dir });
+      expect(held.acquired).toBe(true);
+
+      const log: string[] = [];
+      const now = () => new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "steward-proc", steward, activities: turns(log), profiles: PROFILES, now });
+
+      expect(events).toEqual([{ kind: "turn-busy", op: "box-converge", env: "local", steward: "box-steward", heldBy: "hand-run" }]);
+      expect(formatRoundLine(events[0])).toContain("turn-held:hand-run");
+      expect(log).toEqual([]);
+      // The op's own lease, freshly acquired before the turn check, was let go again.
+      expect((await readLease("box-converge", { cwd: dir })).record).toBeUndefined();
+    });
+  });
+
+  test("a stale .lock on the turn ref reports lease-error, never a thrown exception out of the round, and still releases the op lease it had just taken (#1959 finding 2, applied to #2750's turn lease)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+
+      // A previous holder of the turn lease was killed mid-write — its
+      // `.lock` file is still sitting there, blocking every future write to
+      // `_turns/box-steward`, the same way #1959 finding 2 covers the
+      // per-op lease.
+      mkdirSync(join(dir, ".git", "refs", "chant", "lease", "_turns"), { recursive: true });
+      writeFileSync(join(dir, ".git", "refs", "chant", "lease", "_turns", "box-steward.lock"), "");
+
+      const log: string[] = [];
+      const now = () => new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "steward-proc", steward, activities: turns(log), profiles: PROFILES, now });
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toMatchObject({ kind: "lease-error", op: "_turns/box-steward", env: "local" });
+      expect((events[0] as { error: string }).error).toContain("box-steward.lock");
+      expect(log).toEqual([]);
+      // The op's own lease, freshly acquired before the failed turn attempt, was let go again.
+      expect((await readLease("box-converge", { cwd: dir })).record).toBeUndefined();
+    });
+  });
+});

package/src/op/steward.ts

@@ -41,7 +41,8 @@
  * ## What a steward writes
  *
  * A steward's writes are chant writes: run, converge and gate records on the
- * `chant/lifecycle` branch and lease refs under `refs/chant/lease/`, all made
+ * `chant/lifecycle` branch, the answer records of the decision points its
+ * Ops ask (`_answers/`, #2786), and lease refs under `refs/chant/lease/`, all made
  * with git plumbing (`../lifecycle/git.ts`: `hash-object`, `mktree`,
  * `commit-tree`, `update-ref`). None of them reads or writes the checkout's
  * index or working tree, so a coding agent editing the app in the same
@@ -233,6 +234,29 @@ export function stewardLeaseName(steward: string): string {
   return `_stewards/${steward}`;
 }
 
+/**
+ * The lease a local steward holds for as long as one of its Ops is actually
+ * running: one turn (#2750). Distinct from {@link stewardLeaseName}, which one
+ * `chant operator --steward` process holds for its whole life (renewed
+ * between ticks, released only when the process stops) — this one is taken
+ * right before a run starts and released right after it ends, whether the
+ * run is a round's scheduled tick or `chant run <op>` typed by hand. That is
+ * what makes an on-request run wait its turn behind a turn already in
+ * progress, and succeed again the moment that turn ends, rather than only
+ * once the whole steward process stops.
+ *
+ * `_turns/<name>`, not `_stewards/<name>/turn`: a git ref name is a path
+ * component in the loose-refs tree, and `refs/chant/lease/_stewards/<name>`
+ * (the lease {@link stewardLeaseName} names) already exists as a *leaf* —
+ * git refuses to also create anything *under* it (`fatal: ... exists;
+ * cannot create ...`), so nesting the turn lease inside the steward lease's
+ * own name is unusable the moment both are live at once. A sibling
+ * top-level segment sidesteps that entirely.
+ */
+export function stewardTurnLeaseName(steward: string): string {
+  return `_turns/${steward}`;
+}
+
 /**
  * Pick the steward `--steward [<name>]` names, or the project's only one.
  * Returns the steward, or the message to refuse with.

package/src/op/types.ts

@@ -153,6 +153,13 @@ export interface ActivityStep {
    * Default: "fastIdempotent"
    */
   profile?: ActivityProfileName;
+  /**
+   * How long one attempt may run, such as `"45m"`, in place of the
+   * profile's timeout (#2787). The profile's retry policy is kept, so a
+   * `shell` step stays one attempt. At most `MAX_STEP_TIMEOUT` (six hours); a longer
+   * wait is a gate, not a step.
+   */
+  timeout?: string;
   /**
    * Surface this activity's return value as a named run outcome.
    *

package/src/op/work-lease-run.test.ts

@@ -14,7 +14,8 @@ import type { OpConfig, StepDefinition } from "./types";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "./local-executor";
 import { workLeaseOutput, workLeaseProblems, stewardWorkHolder, WORK_LEASE_STEP_ID } from "./work-lease-run";
 import { declareSteward } from "./steward";
-import { Op } from "./builders";
+import { Op, shell } from "./builders";
+import { shellCmd } from "./activities/shell";
 import { WORK_LEASE_ITEM_PATTERN } from "./work-lease-decl";
 import { runOperatorRound } from "./operator";
 import { stepOutput, validateStepOutputRefScope } from "./step-output-ref";
@@ -164,6 +165,24 @@ describe("a run under a work lease", () => {
     });
   });
 
+  test("a shell pick step that prints JSON hands the lease its candidates, and the next is claimed when the first is held (#2787)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await claimWorkLease("W-4", "other", { cwd: dir, ttlMs: 60_000 });
+      const pick = shell(`echo '["W-4","W-5"]'`, { id: "pick", json: true });
+      const op = dispatchOp({ workLease: { item: pick.out.json } }, [pick, step("build", { item: workLeaseOutput("item") })]);
+      const activities = new Map<string, ActivityFn>([
+        ["shellCmd", shellCmd as unknown as ActivityFn],
+        ["build", async () => ({})],
+      ]);
+      const result = await run(op, activities, dir);
+      expect(result.status).toBe("ok");
+      expect(result.records.map((r) => r.fn)).toEqual(["shellCmd", "workLease:claim", "build"]);
+      expect(result.records[2].args).toEqual({ item: "W-5" });
+      expect(result.workLease).toMatchObject({ item: "W-5", released: true });
+    });
+  });
+
   test("--work takes the place of the Op's item, and a failed run releases not_done", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);

package/src/op/work-lease-run.ts

@@ -354,7 +354,7 @@ export class RunWorkLease {
    * keeps what was committed), and give the lease back with the outcome
    * unless it was lost.
    */
-  async finish(status: "ok" | "fail" | "gated", resultsById: ReadonlyMap<string, unknown>): Promise<WorkLeaseRunResult> {
+  async finish(status: "ok" | "fail" | "gated" | "waiting", resultsById: ReadonlyMap<string, unknown>): Promise<WorkLeaseRunResult> {
     this.stopHeartbeat();
     await this.beat;
     const lease = this.lease;
@@ -375,7 +375,7 @@ export class RunWorkLease {
       await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
     }
     if (this.lost !== undefined) return base;
-    let outcome = status === "ok" ? "done" : status === "gated" ? "gated" : "not_done";
+    let outcome = status === "ok" ? "done" : status === "gated" || status === "waiting" ? status : "not_done";
     if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
       const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
       if (typeof declared === "string" && declared.trim() !== "") outcome = declared.trim();

package/src/workspace/__fixtures__/decide-workspace.ts

@@ -0,0 +1,129 @@
+/**
+ * A throwaway workspace for the decide tests: a git repository with an answer
+ * kind (the reference workspace's), a task kind the points read through the
+ * read contract, three points (a noul, a choice and a score), and a box member
+ * that declares one brokered capability and one without a broker.
+ */
+
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** The chant checkout the tests run in. */
+export const REPO = realpathSync(join(import.meta.dirname, "..", "..", "..", "..", ".."));
+const REF = join(REPO, "reference-workspace");
+
+export const MODEL = "jev-1.13.0";
+
+const model = (extra: Record<string, unknown> = {}) => ({ kind: "model", backend: "systemone", model: MODEL, threshold: 0.8, ...extra });
+
+export const POINTS = {
+  points: {
+    triage: {
+      title: "Does this task need a person now",
+      question: { type: "noul", instructions: "Does the task need a person to look at it today?", criteria: { true: "A person looks at it today.", false: "It can wait." } },
+      inputs: { "record.size": "the task's size in points", "record.risky": "whether the task touches production" },
+      deciders: [{ kind: "table", rows: [{ when: { "record.size": 0 }, answer: false }] }, model(), { kind: "quorum", count: 1 }],
+    },
+    route: {
+      title: "Which team takes this task",
+      question: { type: "choice", instructions: "Pick the team that takes the task.", criteria: { platform: "The platform team.", app: "The app team.", docs: "The docs team." } },
+      inputs: { "record.title": "the task's title", "record.size": "the task's size in points" },
+      deciders: [model({ unreachable: "fail" }), { kind: "quorum", count: 1 }],
+    },
+    effort: {
+      title: "How much effort this task takes",
+      question: { type: "score", instructions: "Rate the effort the task takes.", criteria: ["low", "medium", "high"] },
+      inputs: { "record.size": "the task's size in points", "member.kind": "the kind of the member the task is in" },
+      deciders: [model(), { kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+const TASK_KIND = `export const recordKind = {
+  name: "task",
+  location: { dir: ".", match: "^T-[0-9]+\\\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:test-task:1", path: "task.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["open", "done"],
+  closedStates: ["done"],
+};
+`;
+
+const TASK_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "urn:intentius:chant:test-task:1",
+  type: "object",
+  required: ["id", "title", "state"],
+  properties: {
+    id: { type: "string" },
+    title: { type: "string" },
+    state: { enum: ["open", "done"] },
+    size: { type: "integer" },
+    risky: { type: "boolean" },
+  },
+  additionalProperties: false,
+};
+
+const task = (id: string, title: string, size: number, risky: boolean) =>
+  `---\nid: "${id}"\ntitle: "${title}"\nstate: "open"\nsize: ${size}\nrisky: ${risky}\n---\n\n# ${title}\n`;
+
+const scratch: string[] = [];
+
+export function cleanScratch(): void {
+  for (const d of scratch.splice(0)) rmSync(d, { recursive: true, force: true });
+}
+
+export function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+/** Make the workspace and commit it. Returns its root. */
+export function workspace(points: unknown = POINTS): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-decide-")));
+  scratch.push(root);
+  const files: Record<string, string> = {
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "decide-test",
+        schema: 1,
+        members: [
+          { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+          {
+            name: "box",
+            dir: "box",
+            kind: "other",
+            because: "the box the steward runs in",
+            box: { capabilities: [{ name: "inference", broker: "lobby", scope: ["agent"] }, { name: "raw" }] },
+          },
+        ],
+        records: [{ kind: "answers/answer.kind.mjs" }, { kind: "tasks/task.kind.mjs" }],
+      },
+      null,
+      2,
+    ),
+    "app/server.mjs": "export const port = 8080;\n",
+    "box/README.md": "The box.\n",
+    "decisions/points.json": JSON.stringify(points, null, 2),
+    "tasks/task.kind.mjs": TASK_KIND,
+    "tasks/task.schema.json": JSON.stringify(TASK_SCHEMA, null, 2),
+    "tasks/T-1.md": task("T-1", "Rotate the deploy key", 5, true),
+    "tasks/T-2.md": task("T-2", "Fix a typo in the README", 1, false),
+  };
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  cpSync(join(REF, "answers", "answer.kind.mjs"), join(root, "answers", "answer.kind.mjs"));
+  cpSync(join(REF, "answers", "answer.schema.json"), join(root, "answers", "answer.schema.json"));
+  git(root, "init", "-q");
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "one");
+  return root;
+}
+
+/** The front matter text of a written record. */
+export const recordText = (root: string, path: string): string => readFileSync(join(root, path), "utf-8");