@intentius/chant 0.104.4 → 0.105.1

package/src/op/factory.e2e.test.ts

@@ -1,7 +1,9 @@
 /**
  * The factory reference Op (#3406, ws-087), run through the local executor
  * with stub hooks on a small workspace that carries the reference
- * workspace's decision, work and answer kinds and its points: one item from
+ * workspace's decision, work, answer and contract kinds and its points, its
+ * work kind linked to the contracts, as the factory builds only an item that
+ * names a contract, an ask or an intent build (#3503): one item from
  * pick to done, one retry after a failed build, and one ask the understand
  * point refuses. The rules themselves are tested in
  * ../workspace/factory-rules.test.ts.
@@ -53,10 +55,19 @@ function workspace(dir: string): void {
   git(["config", "user.email", "t@chant.dev"], dir);
   git(["config", "user.name", "T"], dir);
   git(["config", "commit.gpgsign", "false"], dir);
-  for (const d of ["decisions", "work", "answers"]) mkdirSync(join(dir, d), { recursive: true });
+  for (const d of ["decisions", "work", "answers", "contracts"]) mkdirSync(join(dir, d), { recursive: true });
   for (const f of ["decisions/decision.kind.mjs", "decisions/decision.schema.json", "decisions/points.json", "work/work.kind.mjs", "work/work.schema.json", "answers/answer.kind.mjs", "answers/answer.schema.json"]) {
     cpSync(join(REF, f), join(dir, f));
   }
+  for (const f of ["contract.kind.mjs", "contract.schema.json"]) cpSync(join(REF, "design", "contracts", f), join(dir, "contracts", f));
+  const kindFile = join(dir, "work", "work.kind.mjs");
+  const answers = 'answers: "../answers/answer.kind.mjs",';
+  if (!readFileSync(kindFile, "utf-8").includes(answers)) throw new Error("the reference work kind no longer names its answer kind as the fixture expects");
+  writeFileSync(kindFile, readFileSync(kindFile, "utf-8").replace(answers, `${answers}\n    contract: { field: "contract", kind: "../contracts/contract.kind.mjs" },`));
+  writeFileSync(
+    join(dir, "contracts", "C-001-the-feature.md"),
+    `---\n${JSON.stringify({ schema: 1, id: "C-001", title: "The feature", state: "approved", criteria: [{ id: "AC-1", text: "the feature exists" }], checks: [], reviews: [], approved_by: "alice" }, null, 2)}\n---\n\n# The feature\n`,
+  );
   writeFileSync(
     join(dir, "chant.workspace.json"),
     JSON.stringify({
@@ -71,8 +82,8 @@ function workspace(dir: string): void {
   mkdirSync(join(dir, "hooks"), { recursive: true });
   writeFileSync(join(dir, "hooks", "builder.cjs"), BUILDER);
   writeFileSync(join(dir, "hooks", "check.cjs"), CHECK);
-  writeFileSync(join(dir, "work", "W-101-the-feature.md"), item("W-101", { acceptance: [{ id: "AC-1", text: "app/W-101.txt exists", verification: "unit" }] }));
-  writeFileSync(join(dir, "work", "W-102-the-retried-one.md"), item("W-102", { acceptance: [{ id: "AC-1", text: "app/W-102.txt exists", verification: "unit" }] }));
+  writeFileSync(join(dir, "work", "W-101-the-feature.md"), item("W-101", { contract: "C-001", acceptance: [{ id: "AC-1", text: "app/W-101.txt exists", verification: "unit" }] }));
+  writeFileSync(join(dir, "work", "W-102-the-retried-one.md"), item("W-102", { contract: "C-001", acceptance: [{ id: "AC-1", text: "app/W-102.txt exists", verification: "unit" }] }));
   writeFileSync(join(dir, "work", "W-103-an-ask.md"), item("W-103", { state: "proposed", source: { ask: { said: "Make the page purple.", by: "alice", via: "hud" } } }));
   git(["add", "-A"], dir);
   git(["commit", "-q", "-m", "the workspace"], dir);
@@ -177,7 +188,7 @@ describe("the factory Op's seams for an orchestrator (studio#382)", () => {
       // The prepare hook writes W-110 in the checkout and leaves it uncommitted; the others are taken out of the way.
       writeFileSync(
         join(dir, "hooks", "prepare.cjs"),
-        `require("node:fs").writeFileSync("work/W-110-prepared.md", ${JSON.stringify(item("W-110", { acceptance: [{ id: "AC-1", text: "one", verification: "unit" }, { id: "AC-2", text: "two", verification: "unit" }] }))});`,
+        `require("node:fs").writeFileSync("work/W-110-prepared.md", ${JSON.stringify(item("W-110", { contract: "C-001", acceptance: [{ id: "AC-1", text: "one", verification: "unit" }, { id: "AC-2", text: "two", verification: "unit" }] }))});`,
       );
       for (const id of ["W-101", "W-102"]) writeFileSync(join(dir, ".fail-" + id), "");
       git(["add", "-A"], dir);

package/src/workspace/agent-cli.ts

@@ -3,7 +3,8 @@
  * an agent session reloads from, read from the repository alone.
  *
  * A session is declared in the declaration's `agents` list and bound to one
- * member. This prints the session, its member, its write scope (the files
+ * member or several (ws-101). This prints the session, its members, its
+ * write scope (the files
  * and the record kinds, with their verbs, it may write) and the spec: the
  * `spec` block `chant workspace records --current --json` prints (#2546). An
  * agent that resumes needs nothing else: no memory of an earlier run, no
@@ -45,6 +46,13 @@ export interface AgentKindScope {
   verbs: WriteVerb[];
 }
 
+/** A member an agent session is bound to. */
+export interface AgentMember {
+  name: string;
+  dir: string;
+  kind: string;
+}
+
 interface Head {
   $schema: string;
   contract: number;
@@ -54,11 +62,18 @@ interface Head {
 export type AgentDocument =
   | (Head & {
       workspace: { name: string; root: string; scopeFrom: "base" | "working-tree" };
-      agent: { name: string; member: { name: string; dir: string; kind: string }; principals: string[] };
+      agent: {
+        name: string;
+        /** The first member the session is bound to, kept for readers of a one-member session. */
+        member: AgentMember;
+        /** Every member the session is bound to, in the order it names them (ws-101). */
+        members: AgentMember[];
+        principals: string[];
+      };
       scope: {
-        /** The one member whose files the session writes. */
+        /** The members whose files the session writes. */
         members: string[];
-        /** Every declared kind in reach: the workspace's own and the member's. */
+        /** Every declared kind in reach: the workspace's own, then each member's. */
         records: AgentKindScope[];
         /** The paths writeScope.agent.protected keeps the session from writing, with the JSON keys each still allows (#3146). */
         protected: { path: string; except: string[] }[];
@@ -81,13 +96,14 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
     const decl = source.declaration;
     const writer = resolveWriter(decl, source.policy, { agent: q.name }, source.classes);
     const agent = writer.agent!;
-    const member = decl.members.find((m) => m.name === agent.member)!;
+    const bound = agent.members.map((name) => decl.members.find((m) => m.name === name)!);
+    const members: AgentMember[] = bound.map((m) => ({ name: m.name, dir: m.dir, kind: m.kind }));
     const scope = scopeOf(decl, writer)!;
     const rules = scope.records;
     // The spec query, over every declared kind in the working tree.
     const set = await queryDeclaredRecords(declaredKindFiles(q.cwd), { cwd: q.cwd, current: true });
     const loadedName = new Map(set.kinds.map((k) => [k.declared.path, "error" in k ? null : k.kind.name]));
-    const records: AgentKindScope[] = [...decl.records, ...member.records].map((d) => {
+    const records: AgentKindScope[] = [...decl.records, ...bound.flatMap((m) => m.records)].map((d) => {
       const kind = loadedName.get(d.path) ?? null;
       const names = [kind, d.name].filter((n): n is string => n !== null);
       const verbs = rules === null ? [...WRITE_VERBS] : WRITE_VERBS.filter((v) => names.some((n) => (rules[n] ?? []).includes(v)));
@@ -96,8 +112,8 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
     return {
       ...head,
       workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
-      agent: { name: agent.name, member: { name: member.name, dir: member.dir, kind: member.kind }, principals: agent.principals },
-      scope: { members: [member.name], records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
+      agent: { name: agent.name, member: members[0], members, principals: agent.principals },
+      scope: { members: members.map((m) => m.name), records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
       spec: set.spec ?? { kinds: [], records: [] },
       reload: [`chant workspace agent ${agent.name} --json`, "chant workspace records --current --json"],
     };
@@ -127,7 +143,8 @@ export async function runWorkspaceAgent(ctx: CommandContext): Promise<number> {
   }
   if (args.json || args.format === "json") return 0;
   const out: string[] = [];
-  out.push(`agent     ${doc.agent.name}, bound to member ${doc.agent.member.name} (${doc.agent.member.dir}), scope read from ${doc.workspace.scopeFrom}`);
+  const bound = doc.agent.members.map((m) => `${m.name} (${m.dir})`).join(", ");
+  out.push(`agent     ${doc.agent.name}, bound to ${doc.agent.members.length === 1 ? "member" : "members"} ${bound}, scope read from ${doc.workspace.scopeFrom}`);
   for (const r of doc.scope.records) out.push(`records   ${r.name ?? r.kind ?? r.path} (${r.path}): ${r.verbs.length > 0 ? r.verbs.join(", ") : "not writable"}`);
   for (const p of doc.scope.protected) out.push(`protected ${p.path}${p.except.length > 0 ? ` (except ${p.except.join(", ")})` : ""}`);
   out.push(`spec      ${doc.spec.records.length} current records of ${doc.spec.kinds.length} spec kinds`);

package/src/workspace/agent.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json",
   "title": "chant workspace agent output",
-  "description": "What `chant workspace agent <name> --json` prints (#2524 D20, #2548, ws-067): an agent session, the one member it is bound to, its write scope and the spec, read from the repository alone, so a session that resumes rebuilds its context from this and nothing else. The session and its scope are read from the declaration at base, as the write paths and check --changes read them; the spec from the working tree. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, and every one is in the one closed list of `reason-codes.ts`. Contract version 1; this document was added to it by #2548.",
+  "description": "What `chant workspace agent <name> --json` prints (#2524 D20, #2548, ws-067): an agent session, the members it is bound to (one, or several since ws-101), its write scope and the spec, read from the repository alone, so a session that resumes rebuilds its context from this and nothing else. The session and its scope are read from the declaration at base, as the write paths and check --changes read them; the spec from the working tree. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, and every one is in the one closed list of `reason-codes.ts`. Contract version 1; this document was added to it by #2548.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -72,23 +72,16 @@
               "type": "string"
             },
             "member": {
-              "type": "object",
-              "required": [
-                "name",
-                "dir",
-                "kind"
-              ],
-              "properties": {
-                "name": {
-                  "type": "string"
-                },
-                "dir": {
-                  "type": "string"
-                },
-                "kind": {
-                  "type": "string"
-                }
-              }
+              "$ref": "#/$defs/member",
+              "description": "The first member the session is bound to, the only one for a session that names one member."
+            },
+            "members": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/member"
+              },
+              "description": "Added in contract 1 by #3505. Every member the session is bound to, in the order its declaration names them (ws-101); the first is member."
             },
             "principals": {
               "type": "array",
@@ -111,11 +104,11 @@
               "items": {
                 "type": "string"
               },
-              "description": "The one member whose files the session writes."
+              "description": "The members whose files the session writes: every member it is bound to, in the order its declaration names them."
             },
             "records": {
               "type": "array",
-              "description": "Every declared record kind in the session's reach: the workspace's own kinds, then the member's.",
+              "description": "Every declared record kind in the session's reach: the workspace's own kinds, then each member's, in the order of members.",
               "items": {
                 "type": "object",
                 "required": [
@@ -168,7 +161,7 @@
             },
             "protected": {
               "type": "array",
-              "description": "Added in contract 1 by #3146. The paths writeScope.agent.protected keeps the session from writing even inside its member, each a glob from the workspace root that also covers everything under a directory it matches, with the top-level keys of a JSON file a write may still change in except. Empty when none is listed. check --changes reports a write to one with write-scope-protected.",
+              "description": "Added in contract 1 by #3146. The paths writeScope.agent.protected keeps the session from writing even inside its members, each a glob from the workspace root that also covers everything under a directory it matches, with the top-level keys of a JSON file a write may still change in except. Empty when none is listed. check --changes reports a write to one with write-scope-protected.",
               "items": {
                 "type": "object",
                 "required": [
@@ -337,6 +330,25 @@
         "scope": false
       }
     },
+    "member": {
+      "type": "object",
+      "required": [
+        "name",
+        "dir",
+        "kind"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "dir": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string"
+        }
+      }
+    },
     "asset": {
       "type": "object",
       "required": [

package/src/workspace/broker-protocol.schema.json

@@ -35,14 +35,16 @@
     },
     "declarationReport": {
       "type": "object",
-      "description": "POST /api/box/declaration: the capabilities chant workspace status --json lists for the box's block, sent by the box's steward with the box's own token. At most 32 KB. Each report replaces the last.",
+      "description": "POST /api/box/declaration: the capabilities chant workspace status --json lists for the box's block, sent by the box's steward with the box's own token, and, optionally, the box's listing and this month's spend (#3508, ws-102). At most 32 KB. Each report replaces the last.",
       "required": ["capabilities"],
       "properties": {
         "capabilities": {
           "type": "array",
           "maxItems": 20,
           "items": { "$ref": "#/$defs/capability" }
-        }
+        },
+        "listing": { "$ref": "#/$defs/listing" },
+        "spend": { "$ref": "#/$defs/spend" }
       }
     },
     "declarationKept": {
@@ -63,9 +65,49 @@
           }
         },
         "at": { "type": "string", "minLength": 1, "description": "An ISO 8601 time." },
-        "payer": { "$ref": "#/$defs/payer" }
+        "payer": { "$ref": "#/$defs/payer" },
+        "listing": { "$ref": "#/$defs/listing", "description": "The report's listing, when the broker keeps one." },
+        "spend": { "$ref": "#/$defs/spend", "description": "The report's spend, when the broker keeps one." }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "description": "Optional in a report, added within version 1 by #3508 (ws-102). The box block's listing (ws-077) as chant workspace status --json prints it, less the cover: what a broker that lists boxes lists this one under. The bounds are the ones chant workspace box listing set writes with. A broker that lists no boxes ignores it.",
+      "required": ["title", "line"],
+      "properties": {
+        "published": { "type": "boolean", "description": "Whether the box is listed for people other than its owner. Absent means true." },
+        "title": { "type": "string", "maxLength": 60, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" },
+        "line": { "type": "string", "maxLength": 140, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }
+      }
+    },
+    "spend": {
+      "type": "object",
+      "description": "Optional in a report, added within version 1 by #3508 (ws-102). What the box's run records (chant workspace runs --json, ws-076) say it spent in one calendar month, by each run's startedAt: the month's totals, and the same per principal the runs worked for. Only USD costs are summed: a run with no USD cost is counted in unpriced, never as zero. spendFromRuns in broker-protocol.ts computes it. A broker that reports no spend ignores it.",
+      "required": ["month", "usd", "runs", "unpriced", "byPrincipal"],
+      "properties": {
+        "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "The month, YYYY-MM, in UTC." },
+        "usd": { "$ref": "#/$defs/spendUsd" },
+        "runs": { "$ref": "#/$defs/spendCount" },
+        "unpriced": { "$ref": "#/$defs/spendCount" },
+        "byPrincipal": {
+          "type": "array",
+          "maxItems": 50,
+          "description": "Per principal, as the run records' by names them (ws-080's form), at most 50; principal is null for the runs that name none.",
+          "items": {
+            "type": "object",
+            "required": ["principal", "usd", "runs", "unpriced"],
+            "properties": {
+              "principal": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 },
+              "usd": { "$ref": "#/$defs/spendUsd" },
+              "runs": { "$ref": "#/$defs/spendCount" },
+              "unpriced": { "$ref": "#/$defs/spendCount" }
+            }
+          }
+        }
       }
     },
+    "spendUsd": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000, "description": "The sum of the priced runs' USD costs." },
+    "spendCount": { "type": "integer", "minimum": 0, "exclusiveMaximum": 1000000000, "description": "A count of runs: all of them under runs, those with no USD cost under unpriced." },
     "payer": {
       "type": "object",
       "description": "Whose credential pays for the box's model calls (#3474, ws-098), when the broker says. shared: a credential neither the box's owner nor its visitor owns, such as a house or operator key. owner: the box owner's own. visitor: the credential a person brought for this box. principal is the payer in ws-080's form (github:<login>) when the broker knows them, else null. Optional: a broker that does not say leaves it out, and a box treats that as unknown. The same fact rides on each answer from /llm/anthropic and /decide as the chant-payer header.",

package/src/workspace/broker-protocol.test.ts

@@ -12,6 +12,7 @@ import {
   parsePayerHeader,
   payerOf,
   refusalMessage,
+  spendFromRuns,
   STANDARD_CAPABILITIES,
 } from "./broker-protocol";
 
@@ -120,3 +121,47 @@ describe("a grant (#3477)", () => {
     for (const bad of ["", "has space", "line\nbreak", "x".repeat(GRANT_MAX_LENGTH + 1), 42, null]) expect(isGrantValue(bad), String(bad).slice(0, 20)).toBe(false);
   });
 });
+
+describe("a report's listing and spend (#3508)", () => {
+  const spend = { month: "2026-10", usd: 1.84, runs: 3, unpriced: 1, byPrincipal: [{ principal: "github:octo", usd: 1.84, runs: 2, unpriced: 0 }, { principal: null, usd: 0, runs: 1, unpriced: 1 }] };
+
+  test("are kept when well formed, with published defaulting to true, and left out when absent", () => {
+    expect(parseDeclarationReport({ capabilities: [], listing: { title: "Salad", line: "a salad app" }, spend }, "lobby")).toEqual({
+      capabilities: [],
+      listing: { published: true, title: "Salad", line: "a salad app" },
+      spend,
+    });
+    expect(parseDeclarationReport({ capabilities: [] }, "lobby")).toEqual({ capabilities: [] });
+  });
+
+  test("a malformed listing or spend refuses the report", () => {
+    for (const listing of [[], { title: "x".repeat(61) }, { title: "a\nb" }, { line: "x".repeat(141) }, { published: "yes" }]) {
+      expect(parseDeclarationReport({ capabilities: [], listing }, "lobby"), JSON.stringify(listing)).toHaveProperty("error");
+    }
+    for (const bad of [{ ...spend, month: "2026-13" }, { ...spend, usd: -1 }, { ...spend, runs: 1.5 }, { ...spend, byPrincipal: [{ principal: "", usd: 0, runs: 0, unpriced: 0 }] }]) {
+      expect(parseDeclarationReport({ capabilities: [], spend: bad }, "lobby"), JSON.stringify(bad)).toHaveProperty("error");
+    }
+  });
+
+  test("spend sums a month's runs per principal, with a run that has no USD cost unpriced, never zero", () => {
+    const runs = [
+      { startedAt: "2026-10-02T10:00:00Z", by: "github:octo", cost: { amount: 1.5, currency: "USD", source: "x" } },
+      { startedAt: "2026-10-03T10:00:00Z", by: "github:octo", cost: { amount: 0.34, currency: "USD", source: "x" } },
+      { startedAt: "2026-10-03T11:00:00Z", by: null, cost: null },
+      { startedAt: "2026-10-04T11:00:00Z", by: "github:ada", cost: { amount: 2, currency: "EUR", source: "x" } },
+      { startedAt: "2026-09-30T23:00:00Z", by: "github:octo", cost: { amount: 9, currency: "USD", source: "x" } },
+    ];
+    expect(spendFromRuns({ runs }, "2026-10")).toEqual({
+      month: "2026-10",
+      usd: 1.84,
+      runs: 4,
+      unpriced: 2,
+      byPrincipal: [
+        { principal: "github:octo", usd: 1.84, runs: 2, unpriced: 0 },
+        { principal: null, usd: 0, runs: 1, unpriced: 1 },
+        { principal: "github:ada", usd: 0, runs: 1, unpriced: 1 },
+      ],
+    });
+    expect(spendFromRuns({ error: { code: "x" } }, "2026-10")).toBeNull();
+  });
+});

package/src/workspace/broker-protocol.ts

@@ -30,6 +30,10 @@
  * decide answer ({@link BrokerPayer}). It is optional within version 1.
  * A box names whose turn a request is with a `chant-grant` header the broker
  * issued (#3477, ws-099); the broker then may spend that person's credential.
+ * A report may carry the box's listing and this month's spend from its run
+ * records (#3508, ws-102), {@link BoxListing} and {@link BoxSpend}; both are
+ * optional within version 1, and a broker that has no use for them ignores
+ * them.
  *
  * The rule every broker keeps: a request that needs scope word `w` of
  * capability `c` is refused with a 403 unless the box's last report holds an
@@ -266,14 +270,132 @@ export interface KeptDeclaration {
   capabilities: KeptCapability[];
   at: string;
   payer?: BrokerPayer;
+  /** The report's listing, when the broker keeps it (#3508). */
+  listing?: BoxListing;
+  /** The report's spend, when the broker keeps it (#3508). */
+  spend?: BoxSpend;
 }
 
 /**
- * A report's body, checked, kept to the entries that name `broker`; or the
- * reason it is refused with a 400. The same rules as studio's lobby
- * (`lobby/capabilities.mjs`).
+ * The box block's listing (ws-077) as a report carries it (#3508, ws-102):
+ * what `chant workspace status --json` prints under the box member's
+ * `box.listing`, less the cover. A broker that lists boxes lists the box
+ * under it; the repository keeps it, and the broker only a cache.
  */
-export function parseDeclarationReport(body: unknown, broker: string): { capabilities: KeptCapability[] } | { error: string } {
+export interface BoxListing {
+  /** Whether people other than the owner see the box listed. Absent in a report means true. */
+  published: boolean;
+  title: string;
+  line: string;
+}
+
+/** The bounds on a reported listing: the ones `chant workspace box listing set` writes with. */
+export const LISTING_LIMITS = { title: 60, line: 140 } as const;
+
+/** One principal's share of a month's spend, or the month's totals without `principal`. */
+export interface SpendFigures {
+  /** The sum of the priced runs' USD costs, rounded to 1/10000 of a dollar. */
+  usd: number;
+  runs: number;
+  /** Runs with no USD cost: left out of `usd`, never counted as zero. */
+  unpriced: number;
+}
+
+/**
+ * What the box's run records (ws-076) say it spent in one month (#3508,
+ * ws-102), as a report carries it: the month's totals and the same per
+ * principal the runs worked for. {@link spendFromRuns} computes it.
+ */
+export interface BoxSpend extends SpendFigures {
+  /** `YYYY-MM`, in UTC, matched against each run's `startedAt`. */
+  month: string;
+  /** At most {@link SPEND_LIMITS.principals}, in the order the runs first name them; `principal` null for runs that name none. */
+  byPrincipal: (SpendFigures & { principal: string | null })[];
+}
+
+/** The bounds on a reported spend. */
+export const SPEND_LIMITS = { principals: 50, principalLength: 200, figure: 1e9 } as const;
+
+const SPEND_MONTH = /^\d{4}-(0[1-9]|1[0-2])$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const roundUsd = (usd: number) => Math.round(usd * 1e4) / 1e4;
+
+/**
+ * A box's spend in `month` (`YYYY-MM`) from the runs `chant workspace runs
+ * --json` prints (`doc.runs`): every run whose `startedAt` falls in the
+ * month, summed per the principal in its `by`. Only a USD `cost` is summed; a
+ * run with none, or with another currency, is unpriced. Null when `doc` holds
+ * no runs list.
+ */
+export function spendFromRuns(doc: unknown, month: string): BoxSpend | null {
+  const runs = (doc as { runs?: unknown } | null)?.runs;
+  if (!Array.isArray(runs)) return null;
+  const total: SpendFigures = { usd: 0, runs: 0, unpriced: 0 };
+  const people = new Map<string | null, SpendFigures & { principal: string | null }>();
+  for (const r of runs as { startedAt?: unknown; by?: unknown; cost?: { currency?: unknown; amount?: unknown } | null }[]) {
+    if (!String(r?.startedAt ?? "").startsWith(month)) continue;
+    const principal = typeof r.by === "string" && r.by.length > 0 ? r.by.slice(0, SPEND_LIMITS.principalLength) : null;
+    let p = people.get(principal);
+    if (!p) {
+      p = { principal, usd: 0, runs: 0, unpriced: 0 };
+      people.set(principal, p);
+    }
+    const amount = r.cost?.amount;
+    const usd = r.cost?.currency === "USD" && typeof amount === "number" && Number.isFinite(amount) && amount >= 0 ? amount : null;
+    for (const o of [total, p]) {
+      o.runs++;
+      if (usd === null) o.unpriced++;
+      else o.usd += usd;
+    }
+  }
+  const byPrincipal = [...people.values()].slice(0, SPEND_LIMITS.principals).map((p) => ({ ...p, usd: roundUsd(p.usd) }));
+  return { month, usd: roundUsd(total.usd), runs: total.runs, unpriced: total.unpriced, byPrincipal };
+}
+
+/** A reported listing, checked as studio's lobby checks it: undefined when none was reported, or the reason it is refused. */
+function parseListing(raw: unknown): { listing?: BoxListing } | { error: string } {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw !== "object" || Array.isArray(raw)) return { error: 'The listing is { "published", "title", "line" }.' };
+  const { published, title = "", line = "" } = raw as { published?: unknown; title?: unknown; line?: unknown };
+  if (typeof title !== "string" || title.length > LISTING_LIMITS.title || CONTROL.test(title)) return { error: `The listing's title is a string of at most ${LISTING_LIMITS.title} characters with no control character.` };
+  if (typeof line !== "string" || line.length > LISTING_LIMITS.line || CONTROL.test(line)) return { error: `The listing's line is a string of at most ${LISTING_LIMITS.line} characters with no control character.` };
+  if (published !== undefined && typeof published !== "boolean") return { error: "The listing's published is true or false." };
+  return { listing: { published: published !== false, title, line } };
+}
+
+/** A reported spend, checked as studio's lobby checks it: undefined when none was reported, or the reason it is refused. */
+function parseSpend(raw: unknown): { spend?: BoxSpend } | { error: string } {
+  if (raw === undefined || raw === null) return {};
+  const bad = { error: 'The spend is { "month", "usd", "runs", "unpriced", "byPrincipal": [{ "principal", "usd", "runs", "unpriced" }] }, from chant workspace runs --json.' };
+  const money = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0 && v < SPEND_LIMITS.figure;
+  const count = (v: unknown): v is number => Number.isInteger(v) && (v as number) >= 0 && (v as number) < SPEND_LIMITS.figure;
+  const figures = (o: { usd?: unknown; runs?: unknown; unpriced?: unknown }): SpendFigures | null =>
+    money(o.usd) && count(o.runs) && count(o.unpriced) ? { usd: roundUsd(o.usd), runs: o.runs, unpriced: o.unpriced } : null;
+  if (typeof raw !== "object" || Array.isArray(raw)) return bad;
+  const r = raw as { month?: unknown; byPrincipal?: unknown };
+  const total = figures(raw as object);
+  if (!SPEND_MONTH.test(String(r.month)) || total === null) return bad;
+  const list = r.byPrincipal ?? [];
+  if (!Array.isArray(list) || list.length > SPEND_LIMITS.principals) return bad;
+  const byPrincipal: BoxSpend["byPrincipal"] = [];
+  for (const one of list as { principal?: unknown; usd?: unknown; runs?: unknown; unpriced?: unknown }[]) {
+    if (!one || typeof one !== "object") return bad;
+    const principal = one.principal;
+    if (principal !== null && (typeof principal !== "string" || principal.length === 0 || principal.length > SPEND_LIMITS.principalLength)) return bad;
+    const f = figures(one);
+    if (f === null) return bad;
+    byPrincipal.push({ principal, ...f });
+  }
+  return { spend: { month: r.month as string, ...total, byPrincipal } };
+}
+
+/**
+ * A report's body, checked, kept to the entries that name `broker`, with its
+ * listing and spend when it carries them (#3508); or the reason it is refused
+ * with a 400. The same rules as studio's lobby (`lobby/capabilities.mjs`).
+ */
+export function parseDeclarationReport(body: unknown, broker: string): { capabilities: KeptCapability[]; listing?: BoxListing; spend?: BoxSpend } | { error: string } {
   const list = (body as { capabilities?: unknown } | null)?.capabilities;
   if (!Array.isArray(list)) return { error: 'The body is { "capabilities": [{ "name", "broker", "scope" }] }.' };
   if (list.length > DECLARATION_LIMITS.capabilities) return { error: `At most ${DECLARATION_LIMITS.capabilities} capabilities.` };
@@ -289,7 +411,11 @@ export function parseDeclarationReport(body: unknown, broker: string): { capabil
     for (const w of scope as string[]) if (!seen.scope.includes(w)) seen.scope.push(w);
     kept.set(c.name, seen);
   }
-  return { capabilities: [...kept.values()] };
+  const listed = parseListing((body as { listing?: unknown }).listing);
+  if ("error" in listed) return listed;
+  const spent = parseSpend((body as { spend?: unknown }).spend);
+  if ("error" in spent) return spent;
+  return { capabilities: [...kept.values()], ...listed, ...spent };
 }
 
 /**

package/src/workspace/conformance/__fixtures__/reference-broker.ts

@@ -108,7 +108,9 @@ export async function startReferenceBroker(env: BrokerConformanceEnv): Promise<S
         }
         const parsed = parseDeclarationReport(body, env.broker);
         if ("error" in parsed) return refuse(res, 400, parsed.error);
-        const kept: KeptDeclaration = { capabilities: parsed.capabilities, at: new Date().toISOString() };
+        // It keeps the listing and spend a report carries (#3508) and answers with them, as studio's lobby does.
+        const { capabilities, listing, spend } = parsed;
+        const kept: KeptDeclaration = { capabilities, at: new Date().toISOString(), ...(listing ? { listing } : {}), ...(spend ? { spend } : {}) };
         reports.set(box, kept);
         return send(res, 200, { ...kept, payer });
       }

package/src/workspace/conformance/broker.ts

@@ -350,6 +350,28 @@ export const BROKER_CHECKS: readonly BrokerCheck[] = [
       return refusalProblems(r, [], 400);
     },
   },
+  {
+    id: "declaration-listing-spend",
+    capability: "declaration",
+    title: "a report that also carries the box's listing and this month's spend (#3508) is answered 200, and an answer that echoes them echoes them unchanged",
+    async run(ctx) {
+      const body = {
+        capabilities: [{ name: "inference", broker: ctx.env.broker, scope: ["agent", "decide"] }],
+        listing: { published: true, title: "Conformance", line: "a box the broker conformance suite reports" },
+        spend: { month: "2026-10", usd: 1.25, runs: 3, unpriced: 1, byPrincipal: [{ principal: "github:conformance", usd: 1.25, runs: 2, unpriced: 0 }, { principal: null, usd: 0, runs: 1, unpriced: 1 }] },
+      };
+      const problems = ctx.validate("declarationReport", body).map((p) => `the suite's own report: ${p}`);
+      const r = await ctx.call(A, "POST", BROKER_ROUTES.declaration, { body });
+      if (r.status !== 200) return [...problems, `expected 200, got ${r.status}: ${r.text.slice(0, 200)}`];
+      problems.push(...ctx.validate("declarationKept", r.json));
+      const answer = r.json as { capabilities?: { name: string }[]; listing?: unknown; spend?: unknown };
+      if (!(answer.capabilities ?? []).some((c) => c.name === "inference")) problems.push("it did not keep the report's inference entry");
+      for (const key of ["listing", "spend"] as const) {
+        if (answer[key] !== undefined && !isDeepStrictEqual(answer[key], body[key])) problems.push(`the answer's ${key} is ${JSON.stringify(answer[key])}, not the ${key} reported`);
+      }
+      return problems;
+    },
+  },
   {
     id: "unreported-refused",
     capability: "declaration",

package/src/workspace/declaration.schema.json

@@ -133,7 +133,7 @@
     },
     "agents": {
       "type": "array",
-      "description": "The agent sessions the workspace declares (#2524 D20, #2548, ws-067). Each is bound to one member: it writes that member's files and the records of kinds that member or the workspace declares, as writeScope.agent allows. A session resumes from chant workspace agent <name> --json, which prints its member, its scope and the spec, read from the repository alone. A write names its session with the CHANT_AGENT environment variable, or a commit with a Chant-Agent trailer. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer.",
+      "description": "The agent sessions the workspace declares (#2524 D20, #2548, ws-067, ws-101). Each is bound to the members it names, one with member or several with members: it writes the files of any of them and the records of kinds any of them or the workspace declares, as writeScope.agent allows. A session resumes from chant workspace agent <name> --json, which prints its member, its scope and the spec, read from the repository alone. A write names its session with the CHANT_AGENT environment variable, or a commit with a Chant-Agent trailer. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer.",
       "items": {
         "$ref": "#/$defs/agent"
       }
@@ -1322,7 +1322,7 @@
     },
     "agentScope": {
       "type": "object",
-      "description": "The agent class's write scope. Its members are always its session's one member, so only the record kinds and the protected paths can be set.",
+      "description": "The agent class's write scope. Its members are always the members its session is bound to, so only the record kinds and the protected paths can be set.",
       "properties": {
         "protected": {
           "type": "array",
@@ -1343,10 +1343,27 @@
     },
     "agent": {
       "type": "object",
-      "description": "An agent session (#2548).",
+      "description": "An agent session (#2548). It names its members with exactly one of member and members (ws-101).",
       "required": [
-        "name",
-        "member"
+        "name"
+      ],
+      "oneOf": [
+        {
+          "properties": {
+            "member": true
+          },
+          "required": [
+            "member"
+          ]
+        },
+        {
+          "properties": {
+            "members": true
+          },
+          "required": [
+            "members"
+          ]
+        }
       ],
       "properties": {
         "name": {
@@ -1355,7 +1372,16 @@
         },
         "member": {
           "$ref": "#/$defs/name",
-          "description": "The one member the session is bound to. It must be a declared member, not an example group."
+          "description": "The one member the session is bound to. It must be a declared member, not an example group. A session bound to several names them with members instead."
+        },
+        "members": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/name"
+          },
+          "description": "The members the session is bound to, when it writes in more than one, such as a factory that builds an app and writes its evidence records in a design member (ws-101, arugula-salad/studio#402). Each must be a declared member, not an example group. The session may write the files of any of them and the records of kinds any of them or the workspace declares, and the write scope is judged against all of them together. Added in schema 1 by chant 0.105.0, so a declaration that uses it sets minReader to 0.105.0 or newer."
         },
         "principals": {
           "type": "array",