@intentius/chant 0.90.0 → 0.91.0

package/src/workspace/reason-codes.ts

@@ -57,6 +57,10 @@ export const REASONS = {
   "gates-no-ledger": "The checkout has no chant/lifecycle branch, so there is no gate ledger to read.",
   "gates-no-gate-ledger": "The branch has no gate ledger for the member: no run of it has reached a gate.",
   "gates-ledger-unreadable": "Reading the member's gate ledger failed, so no gate is listed.",
+  // A member's stewards status can't fully list (status, #2731).
+  "stewards-unreadable": "An *.op.ts file could not be imported, so a steward it declares may be missing.",
+  "stewards-conflict": "A steward was dropped: its name, or an Op it lists, belongs to another steward.",
+  "steward-runs-unreadable": "Reading an Op's run ledger failed, so its last run is null.",
   // A record that isn't valid (records).
   "record-unparseable": "No front matter, a YAML error or a value outside the JSON subset of YAML, or for a JSON kind a file that is not one object or repeats a member name.",
   "record-schema-invalid": "The record's front matter, or its JSON object, does not match the kind's schema.",
@@ -82,6 +86,10 @@ export const REASONS = {
   "work-done-unpinned": "A work record is done and its evidence list is empty: nothing shows the work was done.",
   "work-closed-without-date": "A work record is done or dropped and has no closing date.",
   "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
+  // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
+  "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
+  "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",
+  "answer-point-changed": "The point's declaration changed since the question was asked, so the answer is to an older version of the question.",
   // A verdict the quorum does not count (records, #2671, #2672).
   "review-decider": "The verdict is the decider's own, and the quorum counts verdicts besides the decider's.",
   "review-agent": "The reviewer holds the agent role in the trust policy at base.",
@@ -121,6 +129,14 @@ export const REASONS = {
   // A review given in a session (records review --session, #2693).
   "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",
   "session-not-open": "--session names a session in a closed state, which takes no more verdicts.",
+  // Decision points (points, points ask, points answer, ws-058, #2739).
+  "points-undeclared": "No record kind with an answers block is declared, or given with --kind, so there is no points file to ask.",
+  "points-invalid": "The points file an answer kind names can't be read, or does not match decision-points.schema.json and the rules checked in code.",
+  "point-unknown": "No points file declares the point asked, or the one an answer names.",
+  "point-inputs-invalid": "The inputs given to an ask are not a JSON object of the point's declared inputs.",
+  "point-decider-failed": "A model decider that fails closed (unreachable: fail) could not answer, so the ask wrote nothing.",
+  "answer-not-candidate": "The people's answer is not one of the question's candidates.",
+  "quorum-not-met": "Too few of the people who answered count toward the point's quorum: distinct, not holding the agent role, and holding one of its roles when it names any.",
   // records --since that fails (#2673).
   "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",
   "since-session-unknown": "--since has the shape of a session id and names no commit, and no session the kind or the declaration reads has that id.",
@@ -159,6 +175,23 @@ export const REASONS = {
   "environments-none-declared": "The member's chant.config.ts declares no environments, so only local and the environments in its ledger are listed.",
   "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
   "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
+  // A box that holds a credential (check, #2726). Each is also a WSP finding.
+  "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
+  "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
+  // The work lease (chant workspace work claim|renew|release, #2732): why the command could not run.
+  "work-kind-missing": "No work kind to find the item in: --kind names a kind with no work block, or the declaration names no work kind.",
+  "work-kind-ambiguous": "More than one declared work kind has a record with the id, so --kind must name one.",
+  "work-item-unknown": "No work record has the id, so there is nothing to lease.",
+  "work-item-closed": "A claim on a work item in a closed state, such as done or dropped: there is no work left to claim.",
+  // The work lease: why a claim, renew or release was refused (exit 2).
+  "lease-held": "Someone holds a live lease on the work item: another worker, or, for a claim, the same one.",
+  "lease-not-held": "Nobody holds a live lease on the work item: it expired, was released or was never claimed.",
+  "lease-token-mismatch": "The live lease on the work item carries another fencing token than the one given.",
+  "lease-race": "Another writer changed the lease between this command's read and its write.",
+  "lease-push-rejected": "The remote refused the lease push: another clone claimed the item first, or the remote could not be reached.",
+  // A box whose isolation fails (check, #2727). Each is also a WSP finding.
+  "box-isolation-collision": "Two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset.",
+  "box-isolation-literal": "A host's stateRoot or a box's state entry is a literal machine path instead of one derived from an environment reference and the box's name.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",

package/src/workspace/record-assets.test.ts

@@ -18,6 +18,7 @@ import { constraintCovers, isWorkspacePath, memberHolding, WORKSPACE_PATH_PATTER
 import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
 import { parseFrontMatter, RECORD_WARNING_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
+import { ANSWER_WARNING_CODES } from "./points";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import recordsSchema from "./records.schema.json";
@@ -170,8 +171,8 @@ describe("chant workspace records checks each pin", () => {
 
   test("the schema lists exactly the warning codes", () => {
     // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
-    // and records adds record-unattested for an author seal under a signers file at base (#2688).
-    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...SEAL_WARNING_CODES]);
+    // an answer kind's the answer warnings (ws-058), and records adds record-unattested for an author seal under a signers file at base (#2688).
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

package/src/workspace/record-assets.ts

@@ -81,7 +81,10 @@ export function checkPins(pins: { path: string; sha256: string }[], tree: Worksp
     const state: PinState = actual === null ? "missing" : actual === pin.sha256 ? "pinned" : "drifted";
     assets.push({ ...pin, actual, state });
     if (state === "missing") {
-      warnings.push({ code: "asset-missing", message: `evidence pins ${pin.path}, which does not exist${tree.label}` });
+      // Worded the same for the working tree and a revision (#2745): a missing
+      // file is missing either way, and `tree.label` would otherwise make the
+      // same finding read differently depending on which one was read.
+      warnings.push({ code: "asset-missing", message: `evidence pins ${pin.path}, which does not exist` });
     } else if (state === "drifted") {
       warnings.push({
         code: "asset-drift",

package/src/workspace/records-cli.ts

@@ -92,6 +92,13 @@ export type RecordView = RecordEntry & {
   /** true when the record's seal verifies for its author against the signers at base; false when it fails, or is missing under an active policy; null when nothing here can say (#2688). */
   attested?: boolean | null;
   attestation?: VerdictAttestation;
+  /**
+   * For a work kind read in the working tree (#2732): the item's active work
+   * lease, or null when nobody holds one. Read from the local lease refs of
+   * the ledger owning the kind, without fetching. Absent under `--at`, since a
+   * lease is live state and not part of a revision.
+   */
+  lease?: { holder: string; token: string; acquiredAt: string; expiresAt: string } | null;
 };
 
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
@@ -304,6 +311,11 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       ...(seals ? authorSeal(loaded.kind, r, policy, seals.checkRecordSeal) : {}),
     }));
     if (loaded.kind.work && query.workGaps !== false && top) await raiseWorkGaps(loaded, records, { root, workspaceRoot, at: query.at });
+    if (loaded.kind.work && at === null && top) {
+      const { activeWorkLeases } = await import("../lifecycle/work-lease");
+      const leases = await activeWorkLeases(loaded.file);
+      for (const r of records) if (r.id !== null) r.lease = leases.get(r.id) ?? null;
+    }
     return {
       $schema: RECORDS_OUTPUT_SCHEMA_ID,
       contract: RECORDS_CONTRACT_VERSION,
@@ -596,7 +608,8 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     if (r.ready !== undefined) {
       const blocked = (r.blockedBy ?? []).map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
       const implemented = (r.implements ?? []).map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ");
-      const status = [r.ready ? "ready" : blocked ? `blocked by ${blocked}` : "", implemented ? `implements ${implemented}` : ""].filter(Boolean).join("; ");
+      const held = r.lease ? `held by ${r.lease.holder} until ${r.lease.expiresAt}` : "";
+      const status = [r.ready ? "ready" : blocked ? `blocked by ${blocked}` : "", implemented ? `implements ${implemented}` : "", held].filter(Boolean).join("; ");
       if (status) lines.push(`${" ".repeat(idWidth + 2)}${status}`);
     }
     for (const reason of r.reasons) lines.push(`${" ".repeat(idWidth + 2)}${reason.code}: ${reason.message} (${r.path})`);
@@ -620,7 +633,7 @@ export async function runWorkspaceUnknown(ctx: CommandContext): Promise<number>
   console.error(
     formatError({
       message: sub ? `Unknown workspace subcommand: ${sub}` : "chant workspace needs a subcommand",
-      hint: `Workspace subcommands: audit, build, check, graph, init, lineage, lint, ls, records, status, upgrade, verify. Run "chant --help" for their options.`,
+      hint: `Workspace subcommands: audit, build, check, graph, init, lineage, lint, ls, records, status, upgrade, verify, work. Run "chant --help" for their options.`,
     }),
   );
   return 1;

package/src/workspace/records-contract.test.ts

@@ -13,6 +13,7 @@ import { afterAll, describe, expect, test } from "vitest";
 import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
 import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, recordTextDigest, REVIEW_REASON_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
+import { ANSWER_WARNING_CODES } from "./points";
 import schema from "./records.schema.json";
 import { PROVENANCE_LEVELS } from "./trust/attestor";
 
@@ -149,8 +150,8 @@ describe("records output schema", () => {
 
   test("lists exactly the warning codes the code can return", () => {
     // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
-    // and records adds record-unattested for an author seal under a signers file at base (#2688).
-    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...SEAL_WARNING_CODES]);
+    // an answer kind's the answer warnings (ws-058), and records adds record-unattested for an author seal under a signers file at base (#2688).
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES]);
   });
 
   test("every failure validates with its code", async () => {

package/src/workspace/records.schema.json

@@ -177,6 +177,10 @@
           "description": "Added in contract 1 by #2683, on every parsed record of a work kind. Each decision the record implements, with its state now; null for an id no decision has.",
           "type": "array",
           "items": { "$ref": "#/$defs/workLink" }
+        },
+        "lease": {
+          "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]
         }
       },
       "allOf": [
@@ -187,6 +191,16 @@
         }
       ]
     },
+    "workLease": {
+      "type": "object",
+      "required": ["holder", "token", "acquiredAt", "expiresAt"],
+      "properties": {
+        "holder": { "type": "string", "description": "Who holds the lease, as --holder gave it." },
+        "token": { "type": "string", "description": "The fencing token: new on every claim, kept by every renew." },
+        "acquiredAt": { "type": "string", "description": "When the lease was claimed, ISO 8601." },
+        "expiresAt": { "type": "string", "description": "When the lease expires unless renewed, ISO 8601." }
+      }
+    },
     "asset": {
       "type": "object",
       "required": ["path", "sha256", "actual", "state"],
@@ -217,6 +231,9 @@
             "work-done-unpinned",
             "work-closed-without-date",
             "work-done-gap-open",
+            "answer-points-unreadable",
+            "answer-point-unknown",
+            "answer-point-changed",
             "record-unattested"
           ]
         },

package/src/workspace/records.ts

@@ -32,6 +32,7 @@ import type { RecordSource } from "./record-source";
 import { sourceBlock, sourceBlockProblems, transcriptDrift } from "./source-block";
 import type { WorkspaceTree } from "./tree";
 import type { DecisionWork, WorkLink, WorkWarningCode } from "./work";
+import type { AnswerWarningCode } from "./points";
 
 // ── Reason codes ─────────────────────────────────────────────────────────────
 
@@ -175,8 +176,8 @@ export interface VerdictAttestation {
 }
 
 export interface RecordWarning {
-  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), and `records` adds `SEAL_WARNING_CODES` (#2688). */
-  code: RecordWarningCode | WorkWarningCode | SealWarningCode;
+  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), and `records` adds `SEAL_WARNING_CODES` (#2688). */
+  code: RecordWarningCode | WorkWarningCode | SealWarningCode | AnswerWarningCode;
   message: string;
 }
 
@@ -360,6 +361,17 @@ export const recordKindSchema = z
       })
       .strict()
       .optional(),
+    /**
+     * An answer kind (ws-058, #2739): the decision points file its records
+     * answer, relative to this kind file. The records are written by `chant
+     * workspace points ask` and `points answer` in the shape of
+     * `point-answer.schema.json`, with an `id`, the states `escalated`,
+     * `proposed` and `answered`, and `answered` closed. With it, `records`
+     * warns about an answer whose point is gone or changed, `check` validates
+     * the points file (WSP116), and `points` lists the open questions.
+     * Optional.
+     */
+    answers: z.object({ points: z.string().min(1) }).strict().optional(),
   })
   .strict()
   .refine((k) => (k.idField === undefined) !== (k.idFrom === undefined), {
@@ -393,7 +405,23 @@ export const recordKindSchema = z
   .refine((k) => !k.work || (k.states !== undefined && k.states.includes(k.work.open) && k.states.includes(k.work.done)), {
     message: "a work kind must have states, and its work open and done states must be listed in them",
     path: ["work"],
-  });
+  })
+  .refine(
+    (k) =>
+      !k.answers ||
+      (k.format === "markdown-front-matter" &&
+        k.idField === "id" &&
+        k.stateField === "state" &&
+        ANSWER_STATES.every((s) => k.states?.includes(s)) &&
+        (k.closedStates ?? []).includes("answered")),
+    {
+      message: 'an answer kind is markdown-front-matter with idField "id", stateField "state", the states escalated, proposed and answered, and answered closed',
+      path: ["answers"],
+    },
+  );
+
+/** The states of an answer kind's records (ws-058): open for people, proposed by a model, answered by a table, people, or a confirmed proposal. */
+export const ANSWER_STATES = ["escalated", "proposed", "answered"] as const;
 
 export type RecordKind = z.infer<typeof recordKindSchema>;
 
@@ -1250,6 +1278,8 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   joinSessions(kind, entries, texts, options.subjects ?? null);
   // A work kind's links, ready and blocked (#2683), from every record before --current.
   const work = kind.work ? await (await import("./work")).applyWork(loaded, entries, options) : undefined;
+  // An answer kind's points (ws-058): an answer whose point is gone or changed is warned about.
+  if (kind.answers) (await import("./points")).applyAnswers(loaded, entries, options);
 
   for (const e of entries) e.valid = e.reasons.length === 0;
   const records = options.current ? entries.filter((e) => e.supersededBy === null) : entries;

package/src/workspace/status-contract.test.ts

@@ -22,10 +22,15 @@ import {
   STATUS_GATE_REASON_CODES,
   STATUS_OUTPUT_SCHEMA_ID,
   STATUS_REASON_CODES,
+  STATUS_STEWARD_REASON_CODES,
   workspaceStatus,
   type StatusDocument,
 } from "./status";
 import schema from "./status.schema.json";
+import { appendRunRecord } from "../lifecycle/run-ledger";
+import { acquireStewardLease } from "../op/operator";
+import { stewardWorkHolder } from "../op/work-lease-run";
+import { claimWorkLease } from "../lifecycle/work-lease";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
 
@@ -148,6 +153,7 @@ describe("status output schema", () => {
     expect(schema.$defs.environment.properties.reason.oneOf[1].properties!.code.enum).toEqual([...STATUS_REASON_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...STATUS_ERROR_CODES]);
     expect(schema.$defs.gateLedger.properties.reason.oneOf[1].properties!.code.enum).toEqual([...STATUS_GATE_REASON_CODES]);
+    expect(schema.$defs.member.properties.stewardReasons.items.properties.code.enum).toEqual([...STATUS_STEWARD_REASON_CODES]);
   });
 });
 
@@ -163,6 +169,8 @@ describe("chant workspace status on built workspaces", () => {
     expect(web.environments[0].ledger).toEqual({ layout: "members", path: "_members/web/staging/releases.jsonl", shared: false });
     // The later of the two records wins.
     expect(web.environments[0].releases.map((r) => [r.component, r.digest, r.gitSha])).toEqual([["web", D("a"), "a".repeat(40)]]);
+    // No plan was ever written for these digests (ws-055, #2733): the field is present, and null.
+    expect(web.environments[0].releases.map((r) => r.plan)).toEqual([null]);
     // api has no _members/api/ yet, so it falls back to the flat ledger, which the root member reads too.
     expect(api.environments[0].ledger).toEqual({ layout: "flat", path: "staging/releases.jsonl", shared: true });
     expect(site.environments[0].ledger).toEqual({ layout: "flat", path: "staging/releases.jsonl", shared: true });
@@ -199,6 +207,33 @@ describe("chant workspace status on built workspaces", () => {
     expect(text).toContain("3 members, 3 with a release in staging, 2 differ from prod, 0 unreadable");
   });
 
+  test("resolves a release's plan from _plans/<digest>.json, member-scoped per #2524 D7 (ws-055, #2733)", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "site", dir: ".", kind: "other", because: "the root project" },
+        { name: "web", dir: "apps/web", kind: "chant" },
+      ]),
+      "apps/web/chant.config.ts": "",
+    });
+    const webPlan = { digest: D("a"), release: "r-web", units: [{ id: "w-1" }] };
+    const apiPlan = { digest: D("b"), release: "r-api", units: [] };
+    lifecycle(root, {
+      "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), "a".repeat(40))),
+      [`_members/web/_plans/sha256_${"a".repeat(64)}.json`]: JSON.stringify(webPlan),
+      "staging/releases.jsonl": jsonl(release("api", "staging", D("b"), "b".repeat(40)), release("worker", "staging", D("c"), "c".repeat(40))),
+      [`_plans/sha256_${"b".repeat(64)}.json`]: JSON.stringify(apiPlan),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging" }));
+    expectValid(doc);
+    const web = doc.members.find((m) => m.name === "web")!;
+    const site = doc.members.find((m) => m.name === "site")!;
+    expect(web.environments[0].releases[0].plan).toEqual(webPlan);
+    const byComponent = new Map(site.environments[0].releases.map((r) => [r.component, r]));
+    expect(byComponent.get("api")?.plan).toEqual(apiPlan);
+    // worker has no plan stored under its digest: reads null, not an error.
+    expect(byComponent.get("worker")?.plan).toBeNull();
+  });
+
   test("compares on the input digest when a release has one", async () => {
     const root = repo({ "chant.workspace.json": declaration([{ name: "chart", dir: "chart", kind: "other", because: "helm" }]) });
     lifecycle(root, {
@@ -253,6 +288,33 @@ describe("chant workspace status on built workspaces", () => {
     expect(formatStatus(doc)).toContain("web     -          no release");
   });
 
+  test("each member lists its box block: the capability, its broker and its scope (#2726)", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "web", dir: "web", kind: "chant" },
+        {
+          name: "box",
+          dir: "box",
+          kind: "other",
+          because: "the box's declarations",
+          box: { capabilities: [{ name: "fountain", broker: "lobby", scope: ["agent", "vault", "conversations", "sandboxes"] }, { name: "inference" }] },
+        },
+      ]),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "prod" }));
+    expectValid(doc);
+    expect(doc.members.map((m) => m.box)).toEqual([
+      null,
+      {
+        capabilities: [
+          { name: "fountain", broker: "lobby", scope: ["agent", "vault", "conversations", "sandboxes"] },
+          { name: "inference", broker: null, scope: [] },
+        ],
+        isolation: null,
+      },
+    ]);
+  });
+
   test("every failure validates with its code", async () => {
     const empty = repo({});
     const outside = realpathSync(mkdtempSync(join(tmpdir(), "chant-status-nogit-")));
@@ -459,6 +521,122 @@ describe("gate state in chant workspace status --json (#2674)", () => {
   });
 });
 
+describe("stewards in chant workspace status --json (#2731)", () => {
+  const op = (name: string, cron?: string) => ({
+    name,
+    overview: name,
+    phases: [{ name: "Run", steps: [{ kind: "activity", fn: "noop", args: {} }] }],
+    ...(cron ? { schedule: { cron, overlap: "skip" } } : {}),
+  });
+
+  /** A box member declaring one steward, local by default and fountain on fountain-k3d. */
+  function stewarded(): string {
+    const steward = {
+      kind: "Chant::Steward",
+      name: "box-steward",
+      ops: [
+        op("box-converge", "* * * * *"),
+        op("box-release"),
+        { ...op("box-dispatch", "*/5 * * * *"), workLease: { item: ["W-1", "W-2"] }, changesCheckout: true },
+      ],
+      form: { default: "local", environments: { "fountain-k3d": "fountain" } },
+      capabilities: ["fountain", "inference"],
+      vault: null,
+    };
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "box", dir: "box", kind: "chant", box: { capabilities: [{ name: "fountain", broker: "lobby", scope: ["agent", "vault"] }] } },
+        { name: "notes", dir: "notes", kind: "other", because: "prose" },
+      ]),
+      "box/chant.config.ts": "export default {};\n",
+      "box/ops/steward.op.ts": `export const steward = ${JSON.stringify(steward)};\n`,
+      "notes/README.md": "notes\n",
+    });
+    lifecycle(root, { "README": "ledger\n" });
+    return root;
+  }
+
+  test("names the steward, its form in the environment asked for, its Ops, schedules, last runs and lease", async () => {
+    const root = stewarded();
+    const box = join(root, "box");
+    await appendRunRecord(
+      { op: "box-converge", env: "local", started: "2026-09-25T10:00:00.000Z", ended: "2026-09-25T10:00:05.000Z", status: "ok", labels: {}, outcomes: {}, phases: [] },
+      { cwd: box },
+    );
+    expect((await acquireStewardLease("box-steward", "box-host:1:abc", { cwd: box, now: () => new Date("2026-09-25T10:00:00.000Z") })).acquired).toBe(true);
+    // #2748: the dispatch turn holds W-1; someone else holds W-2.
+    const turn = await claimWorkLease("W-1", stewardWorkHolder("box-steward", "box-dispatch", "box-host:1:abc"), { cwd: box, ttlMs: 600_000, now: () => new Date("2026-09-25T10:00:30.000Z") });
+    expect(turn.ok).toBe(true);
+    expect((await claimWorkLease("W-2", "someone-else", { cwd: box, ttlMs: 600_000, now: () => new Date("2026-09-25T10:00:30.000Z") })).ok).toBe(true);
+
+    const doc = result(await workspaceStatus({ cwd: root, env: "minimal", now: "2026-09-25T10:01:00.000Z" }));
+    expectValid(doc);
+    const [boxMember, notes] = doc.members;
+    expect(notes.stewards).toEqual([]);
+    expect(boxMember.stewardReasons).toEqual([]);
+    expect(boxMember.stewards).toHaveLength(1);
+    const s = boxMember.stewards[0];
+    expect(s).toMatchObject({
+      name: "box-steward",
+      file: "ops/steward.op.ts",
+      form: "local",
+      forms: { default: "local", environments: { "fountain-k3d": "fountain" } },
+      // #2726: the steward holds no credential; its capabilities join the box block.
+      vault: null,
+      capabilities: [
+        { name: "fountain", broker: "lobby", declared: true },
+        { name: "inference", broker: null, declared: false },
+      ],
+      lease: { holder: "box-host:1:abc", acquiredAt: "2026-09-25T10:00:00.000Z", live: true },
+    });
+    expect(s.ops).toEqual([
+      {
+        name: "box-converge",
+        schedule: { cron: "* * * * *", overlap: "skip" },
+        env: "local",
+        lastRun: { id: expect.any(String), status: "ok", started: "2026-09-25T10:00:00.000Z", ended: "2026-09-25T10:00:05.000Z", gate: null },
+        changesCheckout: false,
+        workLease: null,
+      },
+      { name: "box-release", schedule: null, env: "local", lastRun: null, changesCheckout: false, workLease: null },
+      {
+        name: "box-dispatch",
+        schedule: { cron: "*/5 * * * *", overlap: "skip" },
+        env: "local",
+        lastRun: null,
+        changesCheckout: true,
+        workLease: {
+          kind: null,
+          held: [
+            {
+              item: "W-1",
+              holder: "box-steward/box-dispatch@box-host:1:abc",
+              token: turn.ok ? turn.lease.token : "",
+              acquiredAt: "2026-09-25T10:00:30.000Z",
+              expiresAt: "2026-09-25T10:10:30.000Z",
+              state: "active",
+            },
+          ],
+        },
+      },
+    ]);
+
+    const k3d = result(await workspaceStatus({ cwd: root, env: "fountain-k3d", now: "2026-09-25T11:00:00.000Z" }));
+    expectValid(k3d);
+    expect(k3d.members[0].stewards[0].form).toBe("fountain");
+    expect(k3d.members[0].stewards[0].lease!.live).toBe(false);
+  });
+
+  test("an op file that can't be imported is a reason, and the read still succeeds", async () => {
+    const root = stewarded();
+    writeFileSync(join(root, "box", "ops", "broken.op.ts"), "export const x = ;\n");
+    const doc = result(await workspaceStatus({ cwd: root, env: "minimal" }));
+    expectValid(doc);
+    expect(doc.members[0].stewards.map((s) => s.name)).toEqual(["box-steward"]);
+    expect(doc.members[0].stewardReasons.map((r) => r.code)).toEqual(["stewards-unreadable"]);
+  });
+});
+
 describe("chant workspace status on the chant repo (#2557)", () => {
   test("validates and lists every declared member", async () => {
     const doc = result(await workspaceStatus({ cwd: join(REPO, "packages", "core"), env: "prod", compareTo: "staging" }));