@intentius/chant 0.109.0 → 0.111.0

package/src/workspace/declaration-write.ts

@@ -0,0 +1,275 @@
+/**
+ * `chant workspace member add|remove` and `chant workspace host set` (#3596):
+ * a declaration's members and hosts, written through chant.
+ *
+ * ws-074 lets a tool write the repo only through chant. A local lobby keeps
+ * one member per box it runs, each with a box block whose isolation chant
+ * resolves, and the host those boxes run on; before these writes it edited
+ * `chant.workspace.json` itself to plant, retire and start a box. Each write
+ * changes one entry of `members` or `hosts` in place, so the file keeps its
+ * formatting, key order and, in a `.jsonc` file, its comments, as `box
+ * listing set` does (#3308).
+ *
+ * A write is refused, and nothing written, when the declaration it would
+ * write does not read (`write-input-invalid`, with the read's own message),
+ * when it adds a collision between two boxes on one host or a literal
+ * machine path (`box-isolation-collision`, `box-isolation-literal`, the codes
+ * `chant workspace check` reports as WSP123 and WSP124), and when the write
+ * scope at base keeps the writer off the declaration (`judgePath`, with the
+ * change, so a protected entry's `except` can allow `members` or `hosts`).
+ * Each holds the working tree's write lock (#3173, ws-089), prints one JSON
+ * document (`member-write.schema.json`) and never commits.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { boxCollisions, boxLiterals } from "./box-isolation";
+import { parseDeclaration, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration } from "./declaration";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity";
+import { appendElement, removeElement, setElement, setProperty, valueAt } from "./json-edit";
+import { parseJsonText } from "./jsonc";
+import type { ReasonCode } from "./reason-codes";
+import { locateWorkspace } from "./which-chant";
+import { judgePath, resolveWriter, scopeSource, unknownClassVerdict, WriteScopeError } from "./write-scope";
+import { withWriteLockSync, WriteLockError, WRITE_LOCK_CODES } from "./write-lock";
+
+/** The version of the document these writes print. */
+export const DECLARATION_WRITE_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for what the member and host writes print, shipped beside this file. */
+export const DECLARATION_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/member-write/v1/member-write.schema.json";
+
+/** The writes. */
+export const DECLARATION_WRITE_ACTIONS = ["member add", "member remove", "host set"] as const;
+export type DeclarationWriteAction = (typeof DECLARATION_WRITE_ACTIONS)[number];
+
+/** Why a member or host write wrote nothing. Closed. */
+export const DECLARATION_WRITE_ERROR_CODES = [
+  ...WORKSPACE_ERROR_CODES,
+  "write-usage-invalid",
+  "write-input-invalid",
+  "member-exists",
+  "member-unknown",
+  "box-isolation-collision",
+  "box-isolation-literal",
+  "write-scope-member",
+  "write-scope-protected",
+  "write-scope-class-unknown",
+  "agent-unknown",
+  ...IDENTITY_CODES,
+  ...WRITE_LOCK_CODES,
+] as const satisfies readonly ReasonCode[];
+export type DeclarationWriteErrorCode = (typeof DECLARATION_WRITE_ERROR_CODES)[number];
+
+type Head = { $schema: string; contract: number; chant: string; action: DeclarationWriteAction; name: string | null };
+
+/** What `member add`, `member remove` and `host set` print. */
+export type DeclarationWriteDocument =
+  | (Head & {
+      name: string;
+      /** The declaration file, from the repository root, and the sha256 of its bytes after the write (or as it would be, with dryRun). */
+      declaration: { path: string; sha256: string };
+      /** The declaration, from the repository root, when the write changed it; else empty. */
+      paths: string[];
+      changed: boolean;
+      dryRun: boolean;
+      /** The entry before the write, as the file held it, or null when there was none. */
+      previous: Record<string, unknown> | null;
+      /** The entry after the write, as the file holds it, or null after a remove. */
+      entry: Record<string, unknown> | null;
+    })
+  | (Head & { error: { code: DeclarationWriteErrorCode; message: string } });
+
+export interface DeclarationWriteRequest {
+  cwd: string;
+  action: DeclarationWriteAction;
+  /** The member's or host's name. */
+  name: string;
+  /** The entry as JSON text (`--from`), for member add and host set. */
+  entry?: string;
+  /** Who is writing (`--by`). */
+  by?: string;
+  /** The agent session (`CHANT_AGENT`). */
+  agent?: string;
+  dryRun?: boolean;
+}
+
+class DeclarationWriteError extends Error {
+  constructor(
+    readonly code: DeclarationWriteErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const toPosix = (p: string) => (sep === "/" ? p : p.split(sep).join("/"));
+const sha256 = (b: string) => createHash("sha256").update(b).digest("hex");
+const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** The entry given with --from: a JSON object whose name, if it has one, is the one the command names. The name goes first. */
+function readEntry(text: string | undefined, req: DeclarationWriteRequest): Record<string, unknown> {
+  const what = req.action === "host set" ? "host" : "member";
+  if (text === undefined || text.trim() === "") throw new DeclarationWriteError("write-usage-invalid", `${req.action} needs the ${what}'s entry: --from <file|->`);
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (err) {
+    throw new DeclarationWriteError("write-input-invalid", `the ${what} entry is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!isObject(value)) throw new DeclarationWriteError("write-input-invalid", `the ${what} entry is a JSON object, as the declaration's ${what}s hold it`);
+  if ("name" in value && value.name !== req.name) {
+    throw new DeclarationWriteError("write-input-invalid", `the ${what} entry is named ${JSON.stringify(value.name)}, and the command names ${req.name}; leave name out or make them the same`);
+  }
+  const { name: _name, ...rest } = value;
+  return { name: req.name, ...rest };
+}
+
+/** Write `text` to `file` through a sibling temporary file, so a reader never sees half of it. */
+function writeAtomically(file: string, text: string): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.chant-${process.pid}.tmp`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, file);
+}
+
+const collisionKeys = (d: Declaration) =>
+  new Map(boxCollisions(d).map((c) => [`${c.host} ${c.what} ${c.value} ${c.holders.map((h) => `${h.box}.${h.name}`).join(",")}`, c]));
+
+/** Run the write and build the document it prints. Never throws for a refusal. */
+export function declarationWrite(req: DeclarationWriteRequest): DeclarationWriteDocument {
+  const head: Head = { $schema: DECLARATION_WRITE_SCHEMA_ID, contract: DECLARATION_WRITE_CONTRACT_VERSION, chant: readerVersion(), action: req.action, name: req.name || null };
+  try {
+    return withWriteLockSync(req.cwd, { verb: req.action, by: req.by ?? null, agent: req.agent || null }, req.dryRun, () => write(req, head));
+  } catch (err) {
+    const fail = (code: DeclarationWriteErrorCode, message: string): DeclarationWriteDocument => ({ ...head, error: { code, message } });
+    if (err instanceof DeclarationWriteError) return fail(err.code, err.message);
+    if (err instanceof WriteScopeError) return fail(err.code as DeclarationWriteErrorCode, err.message);
+    if (err instanceof IdentityError) return fail(err.code, err.message);
+    if (err instanceof WriteLockError) return fail(err.code, err.message);
+    if (err instanceof WorkspaceReadError) return fail(err.code as DeclarationWriteErrorCode, err.describe());
+    throw err;
+  }
+}
+
+function write(req: DeclarationWriteRequest, head: Head): DeclarationWriteDocument {
+  if (!req.name) throw new DeclarationWriteError("write-usage-invalid", `${req.action} needs the name of the ${req.action === "host set" ? "host" : "member"}`);
+  if (req.action === "member remove" && req.entry !== undefined) throw new DeclarationWriteError("write-usage-invalid", "member remove takes no --from: it removes the member's whole entry");
+  const given = req.action === "member remove" ? null : readEntry(req.entry, req);
+
+  const located = locateWorkspace(req.cwd);
+  const declaration = readDeclaration(located.tree);
+  const repoBase = located.top ?? located.rootOnDisk;
+  const declPath = toPosix(relative(repoBase, join(located.rootOnDisk, declaration.file)));
+  const declFile = join(located.rootOnDisk, declaration.file);
+  const before = readFileSync(declFile, "utf-8");
+  const jsonc = declaration.file.endsWith(".jsonc");
+  const parsed = parseJsonText(before, { jsonc });
+  if (!parsed.ok) throw new WorkspaceReadError("declaration-unparseable", parsed.message);
+  const expected = structuredClone(parsed.value) as Record<string, unknown>;
+
+  // The edit, made twice: in place in the text, and on the parsed value it must read back as.
+  let after = before;
+  let previous: Record<string, unknown> | null = null;
+  if (req.action === "host set") {
+    const hosts = valueAt(parsed.value, "/hosts");
+    const index = Array.isArray(hosts) ? hosts.findIndex((h) => isObject(h) && h.name === req.name) : -1;
+    if (index >= 0) {
+      previous = (hosts as Record<string, unknown>[])[index];
+      if (!isDeepStrictEqual(previous, given)) {
+        after = setElement(after, jsonc, "/hosts", index, given);
+        (expected.hosts as unknown[])[index] = given;
+      }
+    } else if (Array.isArray(hosts)) {
+      after = appendElement(after, jsonc, "/hosts", given);
+      (expected.hosts as unknown[]).push(given);
+    } else {
+      after = setProperty(after, jsonc, "", "hosts", [given]);
+      expected.hosts = [given];
+    }
+  } else {
+    const entries = valueAt(parsed.value, "/members");
+    const list = Array.isArray(entries) ? (entries as unknown[]) : [];
+    const index = list.findIndex((e) => isObject(e) && e.name === req.name);
+    if (req.action === "member add") {
+      if (index >= 0) {
+        previous = list[index] as Record<string, unknown>;
+        if (!isDeepStrictEqual(previous, given)) {
+          throw new DeclarationWriteError("member-exists", `the declaration already has an entry named ${req.name} (/members/${index}); member add writes a new member, so remove that one first or give its entry as it is`);
+        }
+      } else if (Array.isArray(entries)) {
+        after = appendElement(after, jsonc, "/members", given);
+        (expected.members as unknown[]).push(given);
+      } else {
+        after = setProperty(after, jsonc, "", "members", [given]);
+        expected.members = [given];
+      }
+    } else {
+      const member = declaration.members.find((m) => m.name === req.name);
+      if (!member || index < 0) {
+        const isGroup = declaration.groups.some((g) => g.name === req.name);
+        throw new DeclarationWriteError(
+          "member-unknown",
+          isGroup
+            ? `${req.name} is an example group, not a member; member remove removes members`
+            : `no member is named ${req.name}; the declaration's members are ${declaration.members.map((m) => m.name).join(", ") || "none"}`,
+        );
+      }
+      previous = list[index] as Record<string, unknown>;
+      after = removeElement(after, jsonc, "/members", index);
+      (expected.members as unknown[]).splice(index, 1);
+    }
+  }
+  const reread = parseJsonText(after, { jsonc });
+  if (!reread.ok || !isDeepStrictEqual(reread.value, expected)) {
+    // An edit that does not read back as the value meant is never written.
+    throw new Error(`${req.action}: editing ${declaration.file} in place did not give the declaration intended; nothing was written`);
+  }
+
+  // The declaration it would write reads, and adds no collision or literal path.
+  let next: Declaration;
+  try {
+    next = parseDeclaration(after, declaration.file);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) throw new DeclarationWriteError("write-input-invalid", `the ${req.action} would make the declaration invalid: ${err.describe()}`);
+    throw err;
+  }
+  const had = collisionKeys(declaration);
+  const added = [...collisionKeys(next)].filter(([k]) => !had.has(k)).map(([, c]) => c);
+  if (added.length > 0) {
+    const c = added[0];
+    throw new DeclarationWriteError(
+      "box-isolation-collision",
+      `the ${req.action} would give ${c.holders.map((h) => `${h.box}.${h.name}`).join(" and ")} the same ${c.what} ${c.value} on host ${c.host}; give the box a slot no other box holds`,
+    );
+  }
+  const literalsBefore = new Set(boxLiterals(declaration).map((l) => l.message));
+  const literal = boxLiterals(next).find((l) => !literalsBefore.has(l.message));
+  if (literal) throw new DeclarationWriteError("box-isolation-literal", `the ${req.action} would add a literal machine path: ${literal.message}`);
+
+  // The write scope at base, and who --by names.
+  const source = scopeSource(req.cwd);
+  if (req.by !== undefined) refuseUnidentified(source, [req.by], "--by", { agent: req.agent });
+  if (after !== before && (source.declaration !== null || (req.agent !== undefined && req.agent !== ""))) {
+    const writer = resolveWriter(source.declaration, source.policy, { agent: req.agent || null, principal: req.by ?? null }, source.classes);
+    const unknown = unknownClassVerdict(source.declaration, writer, source.classes);
+    if (!unknown.ok) throw new WriteScopeError(unknown.code, unknown.message);
+    const verdict = judgePath(source.declaration, writer, declaration.file, { before: () => before, after: () => after });
+    if (!verdict.ok) throw new DeclarationWriteError(verdict.code as DeclarationWriteErrorCode, verdict.message);
+  }
+
+  const changed = after !== before;
+  if (changed && !req.dryRun) writeAtomically(declFile, after);
+  return {
+    ...head,
+    name: req.name,
+    declaration: { path: declPath, sha256: sha256(after) },
+    paths: changed ? [declPath] : [],
+    changed,
+    dryRun: req.dryRun === true,
+    previous,
+    entry: given,
+  };
+}

package/src/workspace/declaration.ts

@@ -945,7 +945,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     integrity: p.integrity ?? null,
   }));
 
-  return {
+  const declaration: Declaration = {
     name: obj.name as string,
     schema: obj.schema as number,
     minReader: (obj.minReader as string | undefined) ?? null,
@@ -965,6 +965,24 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     ci,
     file,
   };
+  written.set(declaration, raw);
+  return declaration;
+}
+
+/** Each parsed declaration's JSON as written, for its x- keys (#3595). */
+const written = new WeakMap<Declaration, unknown>();
+
+/**
+ * The `x-` keys of the object at `pointer` in the declaration as written
+ * (#3595), in file order: what a reader of `status --json` or `ls --json`
+ * gets back on the object the declaration holds them on. Empty when the
+ * pointer names no object, and for a declaration not read through
+ * {@link parseDeclaration}.
+ */
+export function extensionsAt(declaration: Declaration, pointer: string): Record<string, unknown> {
+  const value = valueAt(written.get(declaration), pointer);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter(([k]) => k.startsWith("x-")));
 }
 
 /**

package/src/workspace/json-edit.ts

@@ -140,3 +140,74 @@ export function removeProperty(text: string, jsonc: boolean, objectPointer: stri
   const comma = skipTrivia(text, prev.end);
   return text.slice(0, comma) + text.slice(child.end);
 }
+
+/**
+ * Add `value` to the end of the array at `arrayPointer` (#3596), indented
+ * like the element before it, or on its own line in an empty array. An array
+ * on one line stays on one line. Throws a {@link JsonEditError} when there is
+ * no array at the pointer.
+ */
+export function appendElement(text: string, jsonc: boolean, arrayPointer: string, value: unknown): string {
+  const r = parse(text, jsonc);
+  const arr = valueAt(r.value, arrayPointer);
+  if (!Array.isArray(arr)) throw new JsonEditError(`there is no array at ${arrayPointer || "the root"}`);
+  const { eol, unit } = style(text);
+  const span = r.span(arrayPointer)!;
+  const parentIndent = lineIndent(text, span.key ?? span.start);
+  if (arr.length === 0) {
+    // Inside the brackets, after anything already there, such as a comment.
+    const indent = parentIndent + unit;
+    const inside = text.slice(span.start + 1, span.end - 1).replace(/\s+$/, "");
+    return `${text.slice(0, span.start)}[${inside}${eol}${indent}${render(value, indent, unit, eol)}${eol}${parentIndent}]${text.slice(span.end)}`;
+  }
+  const last = r.span(`${arrayPointer}/${arr.length - 1}`)!;
+  const next = skipTrivia(text, last.end);
+  const trailingComma = text[next] === ",";
+  if (lineStart(text, last.start) === lineStart(text, span.start)) {
+    const entry = JSON.stringify(value);
+    return trailingComma ? `${text.slice(0, next + 1)} ${entry},${text.slice(next + 1)}` : `${text.slice(0, last.end)}, ${entry}${text.slice(last.end)}`;
+  }
+  const indent = lineIndent(text, last.start);
+  const after = trailingComma ? next + 1 : last.end;
+  const eolAt = text.indexOf("\n", after);
+  const lineEnd = eolAt < 0 ? text.length : text[eolAt - 1] === "\r" ? eolAt - 1 : eolAt;
+  const at = /^[ \t]*(\/\/.*)?$/.test(text.slice(after, lineEnd)) ? lineEnd : after;
+  const entry = `${eol}${indent}${render(value, indent, unit, eol)}`;
+  if (trailingComma) return `${text.slice(0, at)}${entry},${text.slice(at)}`;
+  return `${text.slice(0, last.end)},${text.slice(last.end, at)}${entry}${text.slice(at)}`;
+}
+
+/** Replace the element at `index` of the array at `arrayPointer` with `value` (#3596). Throws a {@link JsonEditError} when there is none. */
+export function setElement(text: string, jsonc: boolean, arrayPointer: string, index: number, value: unknown): string {
+  const r = parse(text, jsonc);
+  const arr = valueAt(r.value, arrayPointer);
+  if (!Array.isArray(arr) || index < 0 || index >= arr.length) throw new JsonEditError(`there is no element ${index} in an array at ${arrayPointer || "the root"}`);
+  const { eol, unit } = style(text);
+  const span = r.span(arrayPointer)!;
+  const child = r.span(`${arrayPointer}/${index}`)!;
+  const value_ = lineStart(text, child.start) === lineStart(text, span.start) ? JSON.stringify(value) : render(value, lineIndent(text, child.start), unit, eol);
+  return text.slice(0, child.start) + value_ + text.slice(child.end);
+}
+
+/** Remove the element at `index` of the array at `arrayPointer`, with the comma that went with it (#3596). Throws a {@link JsonEditError} when there is none. */
+export function removeElement(text: string, jsonc: boolean, arrayPointer: string, index: number): string {
+  const r = parse(text, jsonc);
+  const arr = valueAt(r.value, arrayPointer);
+  if (!Array.isArray(arr) || index < 0 || index >= arr.length) throw new JsonEditError(`there is no element ${index} in an array at ${arrayPointer || "the root"}`);
+  const child = r.span(`${arrayPointer}/${index}`)!;
+  const next = skipTrivia(text, child.end);
+  if (text[next] === "," || arr.length === 1) {
+    const start = lineStart(text, child.start);
+    const ownLine = /^[ \t]*$/.test(text.slice(start, child.start));
+    // The only element may have no comma after it.
+    let to = text[next] === "," ? next + 1 : child.end;
+    const eolAt = text.indexOf("\n", to);
+    if (ownLine && /^[ \t\r]*$/.test(text.slice(to, eolAt < 0 ? text.length : eolAt))) to = eolAt < 0 ? text.length : eolAt + 1;
+    else while (text[to] === " ") to++;
+    return text.slice(0, ownLine ? start : child.start) + text.slice(to);
+  }
+  // The last element, with no trailing comma: remove from the comma after the one before it.
+  const prev = r.span(`${arrayPointer}/${index - 1}`)!;
+  const comma = skipTrivia(text, prev.end);
+  return text.slice(0, comma) + text.slice(child.end);
+}

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

@@ -352,3 +352,56 @@ describe("chant workspace ls: generated files and job names (#3050)", () => {
     expect(doc.members[0].generated).toEqual([{ path: ".github/workflows/x.yml", command: "c", env: null, jobs: null }]);
   });
 });
+
+describe("chant workspace ls: each member's agent sessions (#3615)", () => {
+  const jsonc = (agents: unknown[]) =>
+    [
+      "// the lobby's declaration",
+      "{",
+      '  "name": "acme", "schema": 1,',
+      '  "members": [{ "name": "app", "dir": "app", "kind": "other", "because": "b" }, { "name": "design", "dir": "design", "kind": "other", "because": "b" }, { "name": "docs", "dir": "docs", "kind": "other", "because": "b" },],',
+      `  "agents": ${JSON.stringify(agents)},`,
+      "}",
+    ].join("\n");
+  const sessions = (doc: LsDocument) => Object.fromEntries(result(doc).members.map((m) => [m.name, m.agents]));
+
+  test("reads a .jsonc declaration in the working tree when there is no base", () => {
+    const root = repo({
+      "chant.workspace.jsonc": jsonc([
+        { name: "app-agent", member: "app" },
+        { name: "factory", members: ["app", "design"] },
+      ]),
+      "app/a.txt": "",
+      "design/d.txt": "",
+      "docs/d.txt": "",
+    });
+    const doc = listWorkspace({ cwd: root });
+    expectValid(doc);
+    expect(sessions(doc)).toEqual({ app: ["app-agent", "factory"], design: ["factory"], docs: [] });
+    expect(result(doc).workspace.agentsFrom).toBe("working-tree");
+  });
+
+  test("reads them at base, as workspace agent does, and at the revision under --at", () => {
+    const root = repo({
+      "chant.workspace.jsonc": jsonc([{ name: "app-agent", member: "app" }]),
+      "app/a.txt": "",
+      "design/d.txt": "",
+      "docs/d.txt": "",
+    });
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "one");
+    git(root, "branch", "-M", "main");
+    // A session added in the working tree binds nothing until it reaches base.
+    writeFileSync(join(root, "chant.workspace.jsonc"), jsonc([{ name: "app-agent", member: "app" }, { name: "docs-agent", member: "docs" }]));
+    const doc = listWorkspace({ cwd: join(root, "docs") });
+    expectValid(doc);
+    expect(sessions(doc)).toEqual({ app: ["app-agent"], design: [], docs: [] });
+    expect(result(doc).workspace.agentsFrom).toBe("base");
+    git(root, "commit", "-q", "-am", "two");
+    const at = listWorkspace({ cwd: root, at: "HEAD~1" });
+    expectValid(at);
+    expect(sessions(at)).toEqual({ app: ["app-agent"], design: [], docs: [] });
+    expect(result(at).workspace.agentsFrom).toBe("at");
+    expect(sessions(listWorkspace({ cwd: root }))).toEqual({ app: ["app-agent"], design: [], docs: ["docs-agent"] });
+  });
+});

package/src/workspace/ls.schema.json

@@ -44,6 +44,7 @@
         "error": false,
         "workspace": {
           "type": "object",
+          "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds at the top level, with its value as written." } },
           "required": ["name", "root", "file", "schema", "minReader", "pins"],
           "properties": {
             "name": { "type": "string", "description": "The declared name. With the revision, it identifies the workspace." },
@@ -71,6 +72,10 @@
               "description": "Added in contract 1 by #2680. The workspace's own record kinds, from the declaration's top-level records, in file order.",
               "type": "array",
               "items": { "$ref": "#/$defs/recordKind" }
+            },
+            "agentsFrom": {
+              "description": "Added in contract 1 by #3615. Where the members' agents were read: base, the declaration at the base revision (origin/HEAD, main or master), as chant workspace agent and the write paths read it; working-tree, when there is no base or no declaration at it; at, the declaration at the --at revision.",
+              "enum": ["base", "working-tree", "at"]
             }
           }
         },
@@ -114,6 +119,7 @@
     },
     "member": {
       "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
       "required": ["name", "dir", "kind", "roles", "upstream", "because", "readable", "reason"],
       "properties": {
         "name": { "type": "string" },
@@ -143,6 +149,11 @@
           "type": "array",
           "items": { "$ref": "#/$defs/generatedFile" }
         },
+        "agents": {
+          "description": "Added in contract 1 by #3615. The names of the agent sessions the declaration binds to the member (agents[].member or agents[].members), in declaration order, read where workspace.agentsFrom says. Empty when none is. A session bound to several members is listed on each.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
         "reason": {
           "oneOf": [
             { "type": "null" },

package/src/workspace/ls.ts

@@ -26,6 +26,7 @@ import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import {
   declaredDiagrams,
+  extensionsAt,
   readDeclaration,
   readerVersion,
   resolveGroups,
@@ -41,6 +42,7 @@ import { memberGenerated, type LsGenerated } from "./ls-generated";
 import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { handToRootChant, locateWorkspace } from "./which-chant";
+import { declaredSessions } from "./write-scope";
 import type { DeclaredKindReasonCode } from "./declared-kinds";
 
 /** The version of the `ls` output this chant writes. */
@@ -113,6 +115,8 @@ export interface LsMember {
   records: LsRecordKind[];
   /** The files the member generates, and the job names inside its forge CI files (#3050). */
   generated: LsGenerated[];
+  /** The agent sessions bound to the member, in declaration order (#3615); empty when none is. */
+  agents: string[];
 }
 
 /**
@@ -167,6 +171,12 @@ export type LsDocument =
         pins: Declaration["pins"];
         /** The workspace's own record kinds, from the top-level `records` (#2680). */
         records: LsRecordKind[];
+        /**
+         * Where the members' `agents` were read (#3615): the declaration at
+         * base, else the working tree's, as `chant workspace agent` reads
+         * them; under `--at`, the declaration at that revision.
+         */
+        agentsFrom: "base" | "working-tree" | "at";
       };
       members: LsMember[];
       groups: LsGroup[];
@@ -247,6 +257,9 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
     const kinds = query.kinds ?? loadKindRegistry(declaration.pins, rootOnDisk).registry;
     const groups = resolveGroups(declaration, tree);
     const repoPrefix = isAbsolute(located.root) ? "." : located.root;
+    // Sessions are read where the write paths read them, at base (#3615); a
+    // listing at a revision reads them there, so it describes one commit.
+    const sessions = at !== null ? { agents: declaration.agents, from: "at" as const } : (declaredSessions(query.cwd) ?? { agents: declaration.agents, from: "working-tree" as const });
     const members: LsMember[] = declaration.members.map((m) => {
       const reason = memberReason(m, tree, kinds);
       return {
@@ -260,6 +273,9 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
         reason,
         records: unloaded(m.records),
         generated: memberGenerated(m, tree, repoPrefix),
+        agents: sessions.agents.filter((a) => a.members.includes(m.name)).map((a) => a.name),
+        // The member's x- keys, as declared (#3595).
+        ...extensionsAt(declaration, m.pointer),
       };
     });
     const lsGroups: LsGroup[] = groups.map((g) => ({
@@ -292,6 +308,8 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
         minReader: declaration.minReader,
         pins: declaration.pins,
         records: unloaded(declaration.records),
+        agentsFrom: sessions.from,
+        ...extensionsAt(declaration, ""),
       },
       members,
       groups: lsGroups,