@intentius/chant 0.104.3 → 0.105.0

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",

package/src/workspace/declaration.ts

@@ -119,7 +119,7 @@ export type WriteVerb = (typeof WRITE_VERBS)[number];
 
 /** One principal class's entry in the declaration's `writeScope` (#2548, ws-067). */
 export interface ClassScope {
-  /** The members whose files the class may write, or null for every path. Always null for the agent class: a session writes its own member. */
+  /** The members whose files the class may write, or null for every path. Always null for the agent class: a session writes the members it is bound to. */
   members: string[] | null;
   /** Kind name to the verbs the class may write it with, or null for every kind in reach with every verb. */
   records: Record<string, WriteVerb[]> | null;
@@ -164,9 +164,16 @@ export interface IdentityPolicy {
   gates: Record<string, SignedGate>;
 }
 
-/** An agent session the declaration names (#2524 D20, #2548): bound to one member. */
+/**
+ * An agent session the declaration names (#2524 D20, #2548): bound to the
+ * members it lists, one or more (ws-101). It writes the files of each, and
+ * the records of kinds any of them or the workspace declares.
+ */
 export interface AgentDeclaration {
   name: string;
+  /** The members the session is bound to, in file order: `members`, or the one `member` names. Never empty. */
+  members: string[];
+  /** The first of `members`, kept for readers of a one-member session. */
   member: string;
   /** Principals that write only as this session. */
   principals: string[];
@@ -952,8 +959,8 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
 
 /**
  * The `agents` list, already validated, with the rules the schema can't say
- * (#2548): names are unique, each names a declared member, and a principal
- * is listed by one session at most.
+ * (#2548, ws-101): names are unique, every member a session names is a
+ * declared member, and a principal is listed by one session at most.
  */
 /** The `identity` block, already validated by the schema (#3163). */
 function identityOf(raw: unknown): IdentityPolicy | null {
@@ -967,23 +974,30 @@ function identityOf(raw: unknown): IdentityPolicy | null {
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
-  const agents = ((raw as { name: string; member: string; principals?: string[] }[] | undefined) ?? []).map((a, i) => ({
-    name: a.name,
-    member: a.member,
-    principals: [...(a.principals ?? [])],
-    pointer: `/agents/${i}`,
-  }));
+  const agents = ((raw as { name: string; member?: string; members?: string[]; principals?: string[] }[] | undefined) ?? []).map((a, i) => {
+    // The schema requires exactly one of member and members (ws-101).
+    const bound = a.members !== undefined ? [...a.members] : [a.member!];
+    return {
+      name: a.name,
+      members: bound,
+      member: bound[0],
+      principals: [...(a.principals ?? [])],
+      pointer: `/agents/${i}`,
+      listed: a.members !== undefined,
+    };
+  });
   const byName = new Map<string, AgentDeclaration>();
   const byPrincipal = new Map<string, AgentDeclaration>();
-  for (const a of agents) {
+  for (const { listed, ...a } of agents) {
     const first = byName.get(a.name);
     if (first) throw new WorkspaceReadError("declaration-invalid", `the agent name ${JSON.stringify(a.name)} is already used by the agent at ${first.pointer}`, at(`${a.pointer}/name`));
     byName.set(a.name, a);
-    if (!members.some((m) => m.name === a.member)) {
+    for (const [i, name] of a.members.entries()) {
+      if (members.some((m) => m.name === name)) continue;
       throw new WorkspaceReadError(
         "declaration-invalid",
-        `agent ${a.name} is bound to ${JSON.stringify(a.member)}, which is not a declared member; an agent session is bound to one member, not an example group`,
-        at(`${a.pointer}/member`),
+        `agent ${a.name} is bound to ${JSON.stringify(name)}, which is not a declared member; an agent session is bound to members, not an example group`,
+        at(listed ? `${a.pointer}/members/${i}` : `${a.pointer}/member`),
       );
     }
     for (const [i, p] of a.principals.entries()) {
@@ -992,7 +1006,7 @@ function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: b
       byPrincipal.set(p, a);
     }
   }
-  return agents;
+  return [...byName.values()];
 }
 
 /** The `changes` block, already validated, with its defaults (#2773). */

package/src/workspace/export.ts

@@ -414,9 +414,16 @@ export async function exportWorkspace(o: ExportOptions): Promise<ExportResult> {
           return keep.length > 0 ? { ...rest, links: keep } : rest;
         });
     } else if (key === "agents") {
-      const agents = value as { name: string; member: string }[];
-      for (const a of agents) if (!names.has(a.member)) dropped.agents.push(a.name);
-      outDecl.agents = agents.filter((a) => names.has(a.member));
+      // A session bound to several members (ws-101) keeps those that go, and is dropped when none does.
+      const agents = value as { name: string; member?: string; members?: string[] }[];
+      const kept: Record<string, unknown>[] = [];
+      for (const a of agents) {
+        const bound = a.members ?? (a.member !== undefined ? [a.member] : []);
+        const going = bound.filter((m) => names.has(m));
+        if (going.length === 0) dropped.agents.push(a.name);
+        else kept.push(a.members !== undefined ? { ...a, members: going } : a);
+      }
+      outDecl.agents = kept;
     } else if (key === "pins") {
       const pins = value as { path?: string; package?: string }[];
       for (const p of pins) if (p.path !== undefined) dropped.pins.push(p.path);

package/src/workspace/factory-rules.test.ts

@@ -8,7 +8,7 @@ import { describe, expect, test } from "vitest";
 import { isAsk, pickable, retryState, doneVerdict, proposeImplements, understandOutcome, type FactoryContext, type FactoryItem } from "./factory-rules";
 
 describe("the factory's rules", () => {
-  const base: FactoryItem = { id: "W-1", state: "open", openState: "open", proposedState: "proposed", ready: true, data: {}, tier: null, contract: null, warnings: [], answers: [], leased: false };
+  const base: FactoryItem = { id: "W-1", state: "open", openState: "open", proposedState: "proposed", ready: true, data: {}, tier: null, contract: { id: "C-1", state: "approved" }, warnings: [], answers: [], leased: false };
   const ctx: FactoryContext = { intentDecided: null, claims: [], attempts: { exhausted: false }, branch: null, questions: { tier: null, understand: null } };
   const hold = (i: Partial<FactoryItem>, c: Partial<FactoryContext> = {}) => {
     const v = pickable({ ...base, ...i }, { ...ctx, ...c });
@@ -19,6 +19,11 @@ describe("the factory's rules", () => {
     expect(hold({})).toBe("ok");
     expect(hold({}, { intentDecided: false })).toBe("intent-undecided");
     expect(hold({ ready: false })).toBe("not-ready");
+    // Only an item that names a contract, an ask or an intent build is the factory's (#3503).
+    expect(hold({ contract: null })).toBe("no-contract");
+    expect(hold({ contract: null, data: { source: { kind: "finding", finding: "F-1" } } })).toBe("no-contract");
+    expect(hold({ contract: null, data: { source: { ask: { said: "x", by: "a" } } } })).toBe("ok");
+    expect(hold({ contract: null, data: { source: { intent: { answer: "x" } } } })).toBe("ok");
     expect(hold({ ready: false, state: "proposed", data: { source: { ask: { said: "x", by: "a" } } } })).toBe("ok");
     expect(hold({ contract: { id: "C-1", state: "draft" }, warnings: ["work-contract-undecided"] })).toBe("contract-not-approved");
     expect(hold({}, { branch: { state: "done", applied: false } })).toBe("built-not-applied");

package/src/workspace/factory-rules.ts

@@ -4,8 +4,11 @@
  * reference Op (`../op/factory.ts`) runs them; an orchestrator supplies only
  * execution (the builder, the context, the check).
  *
- * - Readiness ({@link pickable}): on top of the work kind's `ready`, the box's
- *   intent is decided, a contract the item builds is approved and in force,
+ * - Readiness ({@link pickable}): the item names a contract, or is an ask or
+ *   the box's first build from its intent ({@link isAsk}); a work item a
+ *   person wrote by hand or a finding's triage item stays with its author
+ *   (#3503). On top of the work kind's `ready`, the box's intent is decided,
+ *   a contract the item builds is approved and in force,
  *   the item is under its attempt limit, it is not done and waiting to be
  *   applied on its branch, its slice-tier and understand questions are not
  *   open, an understand answer of redraft or ask holds it, and a failed last
@@ -37,6 +40,7 @@ export type UnderstandAnswer = (typeof UNDERSTAND_ANSWERS)[number];
 /** Why an item is not picked. Closed. */
 export const FACTORY_HOLDS = [
   "not-ready",
+  "no-contract",
   "intent-undecided",
   "contract-not-approved",
   "attempts-exhausted",
@@ -133,7 +137,9 @@ export function understandOutcome(answer: unknown): "dropped" | "redraft" | "ask
 const OPEN = new Set(["escalated", "proposed"]);
 
 /**
- * Whether the factory picks `item` now, or why not. Asks are candidates while
+ * Whether the factory picks `item` now, or why not. The factory builds an
+ * item that names a contract, an ask, or an intent build, as studio's queue
+ * did (#3503); any other item is its author's. Asks are candidates while
  * proposed as well as open; any other item only when the work kind reads it
  * ready.
  */
@@ -142,6 +148,7 @@ export function pickable(item: FactoryItem, ctx: FactoryContext): { ok: true } |
   if (ctx.intentDecided === false) return no("intent-undecided", "the box's intent is not decided yet, so nothing is picked");
   if (item.leased) return no("leased", `${item.id} is leased`);
   const ask = isAsk(item.data);
+  if (!item.contract && !ask) return no("no-contract", `${item.id} names no contract and is not an ask or an intent build, so it is left to its author`);
   const candidate = item.ready || (ask && item.proposedState !== null && item.state === item.proposedState);
   if (!candidate) return no("not-ready", `${item.id} is ${item.state ?? "in no state"} and not ready`);
   if (item.contract && (item.warnings.includes("work-contract-undecided") || item.warnings.includes("work-contract-unknown"))) {

package/src/workspace/reason-codes.ts

@@ -141,7 +141,7 @@ export const REASONS = {
   "write-lock-timeout": "Another write held the working tree's write lock for longer than the write waits (CHANT_WRITE_LOCK_WAIT_MS); the refusal names the holder. Run the write again.",
   "write-lock-not-held": "CHANT_WRITE_LOCK names a batch's lock token that no longer holds the working tree's write lock: the batch released it, or it expired and another writer took it.",
   // Write scope (#2548): a records write that is refused, and a commit check --changes reports, outside the writer's scope.
-  "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only its own member, and writeScope.<class>.members leaves the member out.",
+  "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only the members it is bound to, and writeScope.<class>.members leaves the member out.",
   "write-scope-kind": "The write is to a record kind writeScope.<class>.records does not list, with a verb it does not list for the kind, or deletes a record.",
   "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside the top-level keys or JSON Pointers the entry's except allows (#3146, #3308).",
   "write-scope-class-unknown": "The declaration's writeScope at base names a principal class no pinned package supplies, and the writer is judged human, so it may be in that class; the write is refused until the package is installed at the pinned version or the entry removed (#3080).",

package/src/workspace/write-scope.test.ts

@@ -127,6 +127,9 @@ describe("the declaration's writeScope and agents (#2548)", () => {
     ["a principal two sessions list", declaration(SCOPE, [{ name: "a", member: "app", principals: ["p"] }, { name: "b", member: "design", principals: ["p"] }]), /already listed by agent a/],
     ["two sessions with one name", declaration(SCOPE, [{ name: "a", member: "app" }, { name: "a", member: "design" }]), /already used/],
     ["a members list on the agent class", declaration({ agent: { members: ["app"] } }), /members/],
+    ["an agent naming an undeclared member among several", declaration(SCOPE, [{ name: "a", members: ["app", "nowhere"] }]), /"nowhere", which is not a declared member/],
+    ["an agent with both member and members", declaration(SCOPE, [{ name: "a", member: "app", members: ["design"] }]), /oneOf|exactly one|must match/],
+    ["an agent with an empty members list", declaration(SCOPE, [{ name: "a", members: [] }]), /fewer than 1|minItems|members/],
     ["an unknown verb", declaration({ agent: { records: { decision: ["delete"] } } }), /must be equal to one of the allowed values|delete/],
   ])("refuse %s", (_, text, message) => {
     let err: unknown;
@@ -210,6 +213,19 @@ describe("judging a write", () => {
     expect(judgeRecord(decl, human, screen, "delete")).toEqual({ ok: true });
   });
 
+  test("an agent bound to several members writes in any of them, and its scope is their union (ws-101)", () => {
+    const d = parseDeclaration(declaration(SCOPE, [...AGENTS, { name: "factory", members: ["app", "design"] }]), "chant.workspace.json");
+    expect(d.agents.find((a) => a.name === "factory")).toMatchObject({ members: ["app", "design"], member: "app" });
+    expect(d.agents.find((a) => a.name === "app-agent")).toMatchObject({ members: ["app"], member: "app" });
+    const factory = resolveWriter(d, policy, { agent: "factory" });
+    expect(judgePath(d, factory, "app/server.mjs")).toEqual({ ok: true });
+    expect(judgePath(d, factory, "design/spec.md")).toEqual({ ok: true });
+    expect(judgePath(d, factory, "chant.workspace.json")).toMatchObject({ ok: false, code: "write-scope-member", message: expect.stringContaining("agent session factory, bound to members app, design,") });
+    expect(judgeRecord(d, factory, screen, "new")).toEqual({ ok: true });
+    expect(judgeRecord(d, factory, ws, "new")).toEqual({ ok: true });
+    expect(judgeRecord(d, factory, screen, "amend")).toMatchObject({ ok: false, code: "write-scope-kind" });
+  });
+
   test("the declared name of a kind is a key for its records rule too", () => {
     const d = parseDeclaration(declaration({ agent: { records: { screen: ["new"] } } }), "chant.workspace.json");
     const design = resolveWriter(d, policy, { agent: "design-agent" });
@@ -335,7 +351,8 @@ describe("chant workspace agent: what a session reloads from (#2548)", () => {
     agent.expectValid(doc);
     if ("error" in doc) throw new Error(doc.error.message);
     expect(doc.workspace).toEqual({ name: "studio", root: ".", scopeFrom: "base" });
-    expect(doc.agent).toEqual({ name: "design-agent", member: { name: "design", dir: "design", kind: "other" }, principals: [] });
+    const design = { name: "design", dir: "design", kind: "other" };
+    expect(doc.agent).toEqual({ name: "design-agent", member: design, members: [design], principals: [] });
     expect(doc.scope).toEqual({
       members: ["design"],
       records: [

package/src/workspace/write-scope.ts

@@ -1,14 +1,16 @@
 /**
  * Write scope per member and record kind, for each principal class, and the
- * agent sessions bound to one member (#2524 D5, D20; #2548; ws-067).
+ * agent sessions bound to the members they name (#2524 D5, D20; #2548;
+ * ws-067, ws-101).
  *
  * The declaration's `writeScope` block gives a restricted class the members
  * whose files it may write and the record kinds it may write, with which
  * verbs (`new`, `amend`, `review`, `close`). A class with no entry is not
  * restricted. The declaration's `agents` list names agent sessions, each
- * bound to one member: a session writes that member's files, and the records
- * of kinds that member or the workspace declares, as `writeScope.agent`
- * allows. An agent's members can't be widened.
+ * bound to one member or several (ws-101): a session writes the files of any
+ * of its members, and the records of kinds any of them or the workspace
+ * declares, as `writeScope.agent` allows. The scope is the union of its
+ * members, and `writeScope.agent` can't widen it.
  *
  * Two places apply it, both reading the scope from the base revision so a
  * change can't widen its own scope (#2524 threat model):
@@ -170,7 +172,7 @@ export function unknownClassVerdict(declaration: Declaration | null, writer: Wri
   };
 }
 
-/** The scope that applies to `writer`, or null when its class is not restricted. An agent is always restricted to its member. */
+/** The scope that applies to `writer`, or null when its class is not restricted. An agent is always restricted to its members. */
 export function scopeOf(declaration: Declaration | null, writer: Writer): ClassScope | null {
   const entry = declaration?.writeScope?.[writer.class];
   if (writer.class === "agent") return { members: null, records: entry?.records ?? null, protected: entry?.protected ?? [], pointer: entry?.pointer ?? "/agents" };
@@ -185,14 +187,17 @@ export type RecordVerdict = { ok: true } | { ok: false; code: Exclude<WriteScope
 const OK = { ok: true } as const;
 
 function who(writer: Writer): string {
-  if (writer.agent) return `agent session ${writer.agent.name}, bound to member ${writer.agent.member},`;
+  if (writer.agent) {
+    const bound = writer.agent.members;
+    return `agent session ${writer.agent.name}, bound to ${bound.length === 1 ? "member" : "members"} ${bound.join(", ")},`;
+  }
   const name = writer.principal !== null ? `${writer.principal} (${writer.class})` : `a ${writer.class} writer`;
   return writer.class === "agent" ? `${name}, which no agent session lists,` : name;
 }
 
-/** Whether `writer` may write in `member` (null: a path in no member). */
+/** Whether `writer` may write in `member` (null: a path in no member). An agent session may write in any member it is bound to (ws-101). */
 function memberAllowed(writer: Writer, scope: ClassScope, member: string | null): boolean {
-  if (writer.class === "agent") return member !== null && member === writer.agent?.member;
+  if (writer.class === "agent") return member !== null && (writer.agent?.members.includes(member) ?? false);
   return scope.members === null || (member !== null && scope.members.includes(member));
 }
 
@@ -219,7 +224,7 @@ export function judgeRecord(declaration: Declaration | null, writer: Writer, kin
     return {
       ok: false,
       code: "write-scope-member",
-      message: `${who(writer)} may not write ${kind.name} records, which are ${where}: ${writer.class === "agent" ? "an agent session writes only its own member" : `writeScope.${writer.class}.members leaves it out`}`,
+      message: `${who(writer)} may not write ${kind.name} records, which are ${where}: ${writer.class === "agent" ? "an agent session writes only the members it is bound to" : `writeScope.${writer.class}.members leaves it out`}`,
     };
   }
   if (verb === "delete") {
@@ -319,7 +324,7 @@ export function judgePath(declaration: Declaration | null, writer: Writer, path:
     return {
       ok: false,
       code: "write-scope-member",
-      message: `${who(writer)} may not write ${path}, which ${where}: ${writer.class === "agent" ? "an agent session writes only its own member" : `writeScope.${writer.class}.members leaves it out`}`,
+      message: `${who(writer)} may not write ${path}, which ${where}: ${writer.class === "agent" ? "an agent session writes only the members it is bound to" : `writeScope.${writer.class}.members leaves it out`}`,
     };
   }
   const guarded = protectedEntry(scope.protected, path);