@intentius/chant 0.89.0 → 0.91.0

package/src/cli/main.ts

@@ -54,6 +54,7 @@ import type { LexiconPlugin } from "../lexicon";
  */
 const BOOLEAN_FLAGS = new Set([
   "--help",
+  "--open",
   "--version",
   "--agents",
   "--agent",
@@ -392,6 +393,27 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records review <id> --by <principal>` (#2670): whoever the caller says.
       result.by = args[++i];
       if (!result.by || result.by.startsWith("-")) throw new Error("--by needs the reviewer: --by <principal>");
+      // Repeatable for `workspace points answer` (#2739): each person who answered.
+      (result.bys ??= []).push(result.by);
+    } else if (arg === "--open") {
+      // `chant workspace points --open` (#2739): only the questions still open.
+      result.open = true;
+    } else if (arg === "--inputs") {
+      // `chant workspace points ask <point> --inputs <file|->` (#2739)
+      result.inputs = args[++i];
+      if (!result.inputs || (result.inputs.startsWith("-") && result.inputs !== "-")) throw new Error("--inputs needs a JSON file, or - for standard input: --inputs <file|->");
+    } else if (arg === "--response") {
+      // `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got.
+      result.response = args[++i];
+      if (!result.response || result.response.startsWith("-")) throw new Error("--response needs a JSON file: --response <file>");
+    } else if (arg === "--subject") {
+      // `chant workspace points ask <point> --subject <id>` (#2739): what the question is about.
+      result.subject = args[++i];
+      if (!result.subject || result.subject.startsWith("-")) throw new Error("--subject needs what the question is about, such as a work item id: --subject <id>");
+    } else if (arg === "--answer") {
+      // `chant workspace points answer <id> --answer <value>` (#2739)
+      result.answer = args[++i];
+      if (result.answer === undefined || result.answer === "") throw new Error("--answer needs one of the question's candidates: --answer <value>");
     } else if (arg === "--sign") {
       // `chant workspace records review <id> --sign [<key file>]` (#2687): seal the verdict.
       // `records new` and `records amend` take it too, to seal the record's author (#2688).
@@ -431,6 +453,8 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--digest") {
       result.digest = args[++i];
       if (result.digest !== undefined) (result.digests ??= []).push(result.digest);
+    } else if (arg === "--release-plan") {
+      result.releasePlanFile = args[++i];
     } else if (arg === "--git-sha") {
       result.gitSha = args[++i];
     } else if (arg === "--run-id") {
@@ -483,8 +507,28 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.interval = args[++i];
     } else if (arg === "--lease-ttl") {
       result.leaseTtl = args[++i];
+    } else if (arg === "--steward") {
+      // #2731 — the name is optional: a project with one steward runs it
+      // with a bare `--steward`.
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        result.steward = next;
+        i++;
+      } else {
+        result.steward = "";
+      }
     } else if (arg === "--once") {
       result.once = true;
+    } else if (arg === "--work") {
+      // `chant run <op> --work <id>` (#2748)
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--work needs a work item id: --work <id>");
+      result.work = value;
+    } else if (arg === "--holder" || arg === "--ttl" || arg === "--token" || arg === "--outcome") {
+      // `chant workspace work claim|renew|release <id>` (#2732)
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error(`${arg} needs a value: ${arg} <${arg.slice(2)}>`);
+      result[arg.slice(2) as "holder" | "ttl" | "token" | "outcome"] = value;
     } else if (arg === "--note") {
       result.note = args[++i];
     } else if (arg === "--expire") {
@@ -664,6 +708,8 @@ Commands:
 
 Ops:
   run <name>            Run an Op on the resolved runtime (--on; local by default)
+                        [--work <id>] [--holder <name>]: the work item an Op
+                        with a work lease runs under, and who holds it
   run list              List all Ops with the runtime's state for each
   run status <name>     Show the runtime's state for one Op's latest run
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
@@ -691,7 +737,10 @@ Ops:
                         environment; --interval <dur> (default 60s) and
                         --lease-ttl <dur> (default 5m) tune cadence; --once
                         runs a single round and exits (cron/systemd-timer/
-                        CronJob invokers use this instead of the daemon)
+                        CronJob invokers use this instead of the daemon).
+                        --steward [<name>] runs a declared steward's local
+                        form instead (#2731): its scheduled Ops on their
+                        crons, under the steward's own lease
   operator status        Last tick, outcomes, and pending gates per
                         ConvergeOp, read from the chant/lifecycle orphan
                         branch alone — no daemon needs to be running
@@ -802,6 +851,25 @@ Workspace (level 1, #2524):
                         closing commit and seal, in one write. Without
                         --kind, the one session kind the declaration names.
                         Prints {path, id, changed, seal, closedRev}
+  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]
+                        Take, heartbeat or give back the lease on a work item:
+                        refs/chant/lease/work/<id>, a compare-and-set ref with a
+                        fencing token and an expiry, pushed to the remote so
+                        separate clones coordinate. A claim is refused, exit 2,
+                        while anyone holds it live. Each change appends to
+                        _leases/<id>.jsonl on chant/lifecycle
+  workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]
+                        List the decision points the declared answer kinds'
+                        points files declare, and the questions asked of them;
+                        --open keeps the escalated and proposed ones (ws-058)
+  workspace points ask <point> --inputs <file|-> [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]
+                        Ask a point's table, model and quorum deciders and
+                        record the answer: proposed from a model, escalated to
+                        people below its threshold. --response is a POST
+                        /v1/systemone response the caller got; chant calls no model
+  workspace points answer <id> --answer <value> --by <name>... [--kind <kind file>] [--dry-run]
+                        Record people's answer to an open question, or confirm
+                        a model's proposal, once the point's quorum is met
   workspace verify [--base <rev>] [--head <rev>] [--require attested]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file
@@ -904,7 +972,11 @@ Component release ledger + status:
                              <file> finishes an attempt that stopped)
   components release <env> Append one immutable release record
                             (--component <name> --digest <sha256:...>
-                             [--git-sha <sha>] [--run-id <id>] [--actor <name>])
+                             [--git-sha <sha>] [--run-id <id>] [--actor <name>]);
+                            --release-plan <file> takes --digest's place,
+                            persisting the release plan the file holds to
+                            _plans/<digest>.json (ws-055) and recording its
+                            own digest
   components export <env>  Materialize a persisted build archive manifest to
                             a portable directory (--component <name>
                             [--digest <manifestDigest>] -o <dir> [--json]);
@@ -1328,8 +1400,12 @@ export const commandRegistry: CommandDef[] = [
   // Workspace reads (#2524). Imported on first use, so a level-0 command never
   // loads anything under workspace/ (#2525 rule 5, pinned by #2526's goldens).
   { name: "workspace records", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceRecords(ctx) },
+  // ws-058 (#2739) — decision points and the questions asked of them; never calls a model.
+  { name: "workspace points", handler: async (ctx) => (await import("../workspace/points-cli")).runWorkspacePoints(ctx) },
   { name: "workspace init", handler: async (ctx) => (await import("../workspace/init")).runWorkspaceInit(ctx) },
   { name: "workspace ls", handler: async (ctx) => (await import("../workspace/ls")).runWorkspaceLs(ctx) },
+  // #2732 — the work lease: claim, renew and release a work item.
+  { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli")).runWorkspaceWork(ctx) },
   { name: "workspace status", handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },

package/src/cli/mcp/docs-parity.test.ts

@@ -39,8 +39,9 @@ const guideDoc = readFileSync(join(repoRoot, GUIDE_DOC), "utf8");
 const serverSrc = readFileSync(join(repoRoot, SERVER_SRC), "utf8");
 
 /** What a client is told when it asks, built from a server with no plugins loaded. */
-async function servedListing(method: "tools/list" | "resources/list"): Promise<string[]> {
-  const response = await new McpServer().handleRequest({ jsonrpc: "2.0", id: 1, method });
+async function servedListing(method: "tools/list" | "resources/list", inWorkspace = false): Promise<string[]> {
+  const server = inWorkspace ? new McpServer([], { workspace: { cwd: repoRoot } }) : new McpServer();
+  const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method });
   const result = response.result as { tools?: ToolDefinition[]; resources?: ResourceDefinition[] };
   const names = result.tools?.map((t) => t.name) ?? result.resources?.map((r) => r.uri);
   if (!names || names.length === 0) {
@@ -82,6 +83,23 @@ describe("the MCP docs describe the server that ships (#2385)", () => {
     ).toEqual(sorted(registered));
   });
 
+  test("cli/mcp.mdx's Workspace tools table lists exactly the tools a server inside a workspace adds (#2707)", async () => {
+    const core = await servedListing("tools/list");
+    // This repository declares a workspace, so a server started in it has them.
+    const registered = (await servedListing("tools/list", true)).filter((n) => !core.includes(n));
+    expect(registered.length).toBeGreaterThan(0);
+    const listed = firstColumnCells(section(mcpDoc, "## Workspace tools", MCP_DOC));
+    expect(sorted(listed), `${MCP_DOC}'s "Workspace tools" table and the workspace tools disagree`).toEqual(sorted(registered));
+  });
+
+  test("guide/agent-integration.mdx lists exactly the workspace tools (#2707)", async () => {
+    const core = await servedListing("tools/list");
+    const registered = (await servedListing("tools/list", true)).filter((n) => !core.includes(n));
+    expect(registered.length).toBeGreaterThan(0);
+    const listed = firstColumnCells(section(guideDoc, "### Workspace Tools", GUIDE_DOC));
+    expect(sorted(listed), `${GUIDE_DOC}'s "Workspace Tools" table and the workspace tools a server inside a workspace registers disagree`).toEqual(sorted(registered));
+  });
+
   test("guide/agent-integration.mdx lists exactly the tools the server registers", async () => {
     const registered = await servedListing("tools/list");
     const listed = firstColumnCells(section(guideDoc, "### Available Tools", GUIDE_DOC));

package/src/cli/mcp/server.ts

@@ -8,7 +8,9 @@ import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import { compositesTool, createCompositesHandler } from "./tools/composites";
 import type { LexiconPlugin } from "../../lexicon";
-import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import type { McpClientInfo, McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import { findWorkspaceRoot } from "../../project-root";
+import { createWorkspaceTools, type WorkspaceToolsOptions } from "./workspace-tools";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { setGateOrigin } from "../../lifecycle/gate-origin";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpApproveTool, createOpReportTool } from "./op-tools";
@@ -47,14 +49,14 @@ export function negotiateProtocolVersion(requested: string | undefined): string
  * sends on `initialize`. Read-side only — the server holds no handshake
  * state to update (#1194).
  */
-export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: { name: string; version?: string } } {
+export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: McpClientInfo } {
   const meta = (params._meta ?? {}) as McpRequestMeta;
   const protocolVersion =
     (typeof meta.protocolVersion === "string" ? meta.protocolVersion : undefined) ??
     (typeof params.protocolVersion === "string" ? params.protocolVersion : undefined);
   const clientInfo =
     meta["io.modelcontextprotocol/clientInfo"] ??
-    (params.clientInfo as { name: string; version?: string } | undefined);
+    (params.clientInfo as McpClientInfo | undefined);
   return { protocolVersion, clientInfo };
 }
 
@@ -94,14 +96,20 @@ export class McpServer {
   private pluginResources: Map<string, { definition: ResourceDefinition; handler: () => Promise<string> }> = new Map();
   private plugins: LexiconPlugin[];
   private instructions: string | undefined;
+  /** The `clientInfo` the client gave on `initialize`, for a request that carries none in `_meta` (#2707). */
+  private clientInfo: McpClientInfo | undefined;
 
   /**
    * `options.instructions` is sent as the `initialize` result's
    * `instructions`, the text a client may give its model about this server.
    * Only a workspace root with no lexicon of its own sets it (#2700), to say
    * which members' lexicons were loaded.
+   *
+   * `options.workspace` names the directory the server serves (#2707). When
+   * it is at or inside a declared workspace, the workspace read-contract and
+   * record-write tools are served too.
    */
-  constructor(plugins?: LexiconPlugin[], options: { instructions?: string } = {}) {
+  constructor(plugins?: LexiconPlugin[], options: { instructions?: string; workspace?: WorkspaceToolsOptions } = {}) {
     this.plugins = plugins ?? [];
     this.instructions = options.instructions;
     // Register core tools
@@ -126,6 +134,11 @@ export class McpServer {
       this.registerTool(t.definition, t.handler);
     }
 
+    // Workspace reads and record writes (#2707), inside a declared workspace only.
+    if (options.workspace && findWorkspaceRoot(options.workspace.cwd)) {
+      for (const t of createWorkspaceTools(options.workspace)) this.registerTool(t.definition, t.handler);
+    }
+
     // Register plugin contributions
     if (plugins) {
       for (const plugin of plugins) {
@@ -244,6 +257,8 @@ export class McpServer {
   private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
     switch (method) {
       case "initialize":
+        // Kept for a write's source block (#2707): a prior-revision client names itself only here.
+        this.clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
         // Answered for prior-revision clients too — negotiated, not hard-coded (#1194).
         return this.buildInitializeResult(params);
 
@@ -290,7 +305,9 @@ export class McpServer {
     }
 
     try {
-      const result = await handler(toolParams);
+      // The client, from this request's _meta (2026-07-28) or else from initialize.
+      const clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
+      const result = await handler(toolParams, clientInfo ? { clientInfo } : {});
       const isStructured = typeof result === "object" && result !== null;
       return {
         content: [
@@ -374,6 +391,6 @@ export async function startMcpServer(): Promise<void> {
     // Start without plugins if resolution fails
   }
 
-  const server = new McpServer(plugins);
+  const server = new McpServer(plugins, { workspace: { cwd: process.cwd() } });
   server.start();
 }

package/src/cli/mcp/types.ts

@@ -32,7 +32,7 @@ export interface McpResponse {
  */
 export interface McpRequestMeta {
   protocolVersion?: string;
-  "io.modelcontextprotocol/clientInfo"?: { name: string; version?: string };
+  "io.modelcontextprotocol/clientInfo"?: McpClientInfo;
 }
 
 /**
@@ -68,4 +68,17 @@ export interface ResourceDefinition {
   mimeType?: string;
 }
 
-export type ToolHandler = (params: Record<string, unknown>) => Promise<unknown>;
+/** The MCP client's `clientInfo`, as it gave it on `initialize` or in a request's `_meta`. */
+export interface McpClientInfo {
+  name: string;
+  version?: string;
+  title?: string;
+}
+
+/** What a handler knows about the call beyond its arguments (#2707). */
+export interface ToolContext {
+  /** The client that made the call, when it said. */
+  clientInfo?: McpClientInfo;
+}
+
+export type ToolHandler = (params: Record<string, unknown>, context?: ToolContext) => Promise<unknown>;

package/src/cli/mcp/workspace-tools.test.ts

@@ -0,0 +1,211 @@
+/**
+ * #2707 — chant serve mcp's workspace tools: served at or inside a declared
+ * workspace, reads that return the CLI's documents, and writes that keep the
+ * CLI's rules and say they came through MCP in the record's source block
+ * (#2708). Run against the workspace the reader conformance suite generates.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createConformanceWorkspace, defaultChantCommand, mcpToolCall, type ConformanceWorkspace } from "../../workspace/conformance";
+import { McpServer } from "./server";
+import { workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
+
+const KIND = "decisions/decision.kind.mjs";
+const chant = defaultChantCommand();
+
+let ws: ConformanceWorkspace;
+beforeAll(() => {
+  ws = createConformanceWorkspace({ chantCommand: chant });
+}, 300_000);
+afterAll(() => ws?.dispose());
+
+type Result = { isError?: boolean; structuredContent?: Record<string, unknown>; content: { text: string }[] };
+
+function server(cwd = ws.dir): McpServer {
+  return new McpServer([], { workspace: { cwd, chantCommand: chant } });
+}
+
+let nextId = 1;
+async function rpc(s: McpServer, method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+  const res = await s.handleRequest({ jsonrpc: "2.0", id: nextId++, method, params });
+  if (res.error) throw new Error(res.error.message);
+  return res.result;
+}
+
+async function call(s: McpServer, name: string, args: Record<string, unknown>, meta?: Record<string, unknown>): Promise<Result> {
+  return (await rpc(s, "tools/call", { name, arguments: args, ...(meta ? { _meta: meta } : {}) })) as Result;
+}
+
+function cli(argv: string[], env: NodeJS.ProcessEnv = {}): unknown {
+  let out: string;
+  try {
+    out = execFileSync(chant[0], [...chant.slice(1), ...argv], { cwd: ws.dir, encoding: "utf-8", env: { ...process.env, NO_COLOR: "1", ...env }, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (e) {
+    out = String((e as { stdout?: string }).stdout ?? "");
+  }
+  return JSON.parse(out);
+}
+
+/** A proposed decision's fields, with no id, state or source. */
+function proposal(title: string): Record<string, unknown> {
+  return {
+    schema: 1,
+    title,
+    area: "delivery",
+    question: "Where do the app's logs go?",
+    options: [
+      { id: "a", label: "stdout", how: "The app writes to stdout and the runtime collects it.", tradeoff: "Nothing to configure." },
+      { id: "b", label: "a file", how: "The app writes a file.", tradeoff: "A volume to manage." },
+    ],
+    choice: null,
+    rejected: [],
+    supersedes: [],
+    evidence: [],
+    decided_by: null,
+    decided_on: null,
+    reviews: [],
+    constrains: ["member:app"],
+  };
+}
+
+type RecordView = { id: string; state: string; valid: boolean; data: Record<string, unknown>; quorum?: { agreed: number; met: boolean } };
+function recordsOf(doc: unknown): RecordView[] {
+  return (doc as { records: RecordView[] }).records;
+}
+
+describe("which servers have the workspace tools", () => {
+  const names = [...workspaceReadTools, ...workspaceWriteTools].map((t) => t.name);
+
+  test("a server at or inside a declared workspace lists them", async () => {
+    for (const cwd of [ws.dir, join(ws.dir, "decisions")]) {
+      const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
+      expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
+    }
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-records", "workspace-points", "records-new", "records-amend", "records-review", "records-close", "points-answer"]);
+  });
+
+  test("a server outside any workspace, or given none, does not", async () => {
+    const outside = realpathSync(mkdtempSync(join(tmpdir(), "chant-mcp-no-ws-")));
+    try {
+      for (const s of [server(outside), new McpServer([])]) {
+        const { tools } = (await rpc(s, "tools/list")) as { tools: { name: string }[] };
+        expect(tools.map((t) => t.name).filter((n) => names.includes(n))).toEqual([]);
+      }
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  test("the descriptions say records are proposals and by names who decided", () => {
+    for (const t of workspaceWriteTools) expect(t.description).toMatch(/proposals until they are reviewed.*by must name the person or agent that actually decided/s);
+  });
+});
+
+describe("reads", () => {
+  test("workspace-records returns the document chant workspace records --json prints", async () => {
+    const s = server();
+    const res = await call(s, "workspace-records", { kind: KIND });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "records", "--kind", KIND, "--json"]));
+    const only = await call(s, "workspace-records", { kind: KIND, id: "fix-001" });
+    expect(recordsOf(only.structuredContent).map((r) => r.id)).toEqual(["fix-001"]);
+  }, 120_000);
+
+  test("workspace-points returns the document chant workspace points --json prints, and points-answer the write's (ws-058)", async () => {
+    const s = server();
+    const res = await call(s, "workspace-points", { open: true });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "points", "--open", "--json"]));
+    expect(res.structuredContent).toMatchObject({ open: true, sources: [], points: [], questions: [] });
+    // The generated workspace declares no answer kind, so there is nothing to answer.
+    const answered = await call(s, "points-answer", { id: "slice-tier-000000000000", answer: "small", by: ["alice"] });
+    expect(answered.structuredContent).toMatchObject({ verb: "answer", error: { code: "points-undeclared" } });
+    const bad = await call(s, "points-answer", { id: "slice-tier-000000000000", answer: "small", by: [] });
+    expect(bad.isError).toBe(true);
+  }, 120_000);
+
+  test("an error document is returned as a document, and a flag-shaped value is refused before chant runs", async () => {
+    const s = server();
+    const missing = await call(s, "workspace-records", { kind: "nowhere/none.kind.mjs" });
+    expect(missing.structuredContent).toMatchObject({ error: { code: "kind-unreadable" } });
+    const flag = await call(s, "workspace-ls", { at: "--output=/tmp/x" });
+    expect(flag.isError).toBe(true);
+    expect(flag.content[0].text).toMatch(/at may not start with -/);
+  }, 120_000);
+
+  test("the conformance suite's argv maps to the tool that answers it", () => {
+    expect(mcpToolCall(["workspace", "records", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { kind: KIND } });
+    expect(mcpToolCall(["workspace", "status", "dev", "--json"])).toEqual({ name: "workspace-status", arguments: { env: "dev" } });
+    expect(mcpToolCall(["workspace", "graph", "--intent", "a.mjs:1", "--kind", KIND, "--json"])).toEqual({ name: "workspace-graph", arguments: { intent: "a.mjs:1", kind: [KIND] } });
+    expect(mcpToolCall(["workspace", "graph", "--composites", "--json"])).toEqual({ name: "workspace-graph", arguments: { composites: true } });
+    expect(mcpToolCall(["workspace", "check", "--format", "json"])).toBeUndefined();
+  });
+});
+
+describe("writes", () => {
+  test("records-new proposes a decision with MCP in its source, records reads it, and reviews move its quorum", async () => {
+    const s = server();
+    await rpc(s, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "claude-code", version: "2.1.0" } });
+    const made = await call(s, "records-new", { kind: KIND, record: proposal("Where the logs go") });
+    expect(made.structuredContent).toMatchObject({ id: "fix-002", dryRun: false });
+    const read = recordsOf(cli(["workspace", "records", "--kind", KIND, "--json"])).find((r) => r.id === "fix-002")!;
+    expect(read).toMatchObject({ state: "proposed", valid: true });
+    expect(read.data.source).toEqual({ via: "mcp", client: { name: "claude-code", version: "2.1.0" } });
+
+    for (const by of ["bob", "carol"]) {
+      const res = await call(s, "records-review", { kind: KIND, id: "fix-002", verdict: "agree", by });
+      expect(res.structuredContent).toMatchObject({ review: { reviewer: by, verdict: "agree" } });
+    }
+    const after = await call(s, "workspace-records", { kind: KIND, id: "fix-002" });
+    expect(recordsOf(after.structuredContent)[0].quorum).toMatchObject({ agreed: 2, met: true });
+  }, 180_000);
+
+  test("a second client is recorded as itself, from the request's _meta", async () => {
+    const s = server();
+    await rpc(s, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "claude-code", version: "2.1.0" } });
+    const made = await call(s, "records-new", { kind: KIND, record: { ...proposal("Where the metrics go"), source: { kind: "workspace", member: "app" } } }, {
+      "io.modelcontextprotocol/clientInfo": { name: "codex", version: "0.40.0" },
+    });
+    const id = (made.structuredContent as { id: string }).id;
+    const read = recordsOf(cli(["workspace", "records", "--kind", KIND, "--json"])).find((r) => r.id === id)!;
+    expect(read.data.source).toEqual({ kind: "workspace", member: "app", via: "mcp", client: { name: "codex", version: "0.40.0" } });
+  }, 120_000);
+
+  test("keeps the CLI's rules: a record opens proposed, a decided record's reasoning stays, by and sign", async () => {
+    const s = server();
+    const decided = await call(s, "records-new", {
+      kind: KIND,
+      record: { ...proposal("Decided at once"), state: "decided", choice: { option: "a", reason: "Simplest." }, decided_by: "lex00", decided_on: "2026-09-25" },
+    });
+    expect(decided.structuredContent).toMatchObject({ error: { code: "record-state-not-initial", message: expect.stringContaining("opens proposed") } });
+
+    const reasoning = await call(s, "records-amend", { kind: KIND, id: "fix-001", fields: { question: "Something else?" } });
+    expect(reasoning.structuredContent).toMatchObject({ error: { code: "amend-supersede-instead" } });
+
+    const both = await call(s, "records-new", { kind: KIND, record: { ...proposal("Two authors"), decided_by: "alice" }, by: "bob", dryRun: true });
+    expect(both.structuredContent).toMatchObject({ error: { code: "write-input-invalid" } });
+    const by = await call(s, "records-new", { kind: KIND, record: proposal("One author"), by: "alice", dryRun: true });
+    expect(by.structuredContent, JSON.stringify(by.structuredContent)).toHaveProperty("text");
+    expect((by.structuredContent as { text: string }).text).toContain('decided_by: "alice"');
+
+    // No key configured on this host: the CLI's refusal and remedy.
+    const home = { GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+    const saved = { ...process.env };
+    Object.assign(process.env, home);
+    try {
+      const signed = await call(s, "records-new", { kind: KIND, record: proposal("Signed"), by: "alice", sign: true, dryRun: true });
+      expect(signed.structuredContent).toMatchObject({ error: { code: "record-sign-failed", message: expect.stringContaining("pass --sign <key file>") } });
+    } finally {
+      for (const k of Object.keys(home)) {
+        if (saved[k] === undefined) delete process.env[k];
+        else process.env[k] = saved[k];
+      }
+    }
+    // Nothing above wrote a file.
+    expect(readFileSync(join(ws.dir, "decisions", "fix-001-how-the-app-is-deployed.md"), "utf-8")).toContain('question: "What declares the app\'s deployment?"');
+  }, 180_000);
+});