simt-dev 0.7.0 → 0.8.0

package/src/mcp/server.mjs

@@ -24,6 +24,8 @@ import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
 import { getPrompt, PROMPTS } from './prompts.mjs';
 import { RESOURCE_TEMPLATES, listResources, readResource } from './resources.mjs';
+import { paginate } from './paginate.mjs';
+import { check } from './schema.mjs';
 
 /**
  * Every protocol revision this server speaks, newest first.
@@ -49,6 +51,8 @@ export const RPC = {
   PARSE: -32700,
   REQUEST: -32600,
   METHOD: -32601,
+  /** Arguments that do not match the `inputSchema` the client was shown. */
+  INVALID_PARAMS: -32602,
   INTERNAL: -32603,
   /**
    * `UnsupportedProtocolVersionError`, renumbered to -32022 in 2026-07-28. The spec
@@ -86,6 +90,15 @@ const SERVER_INFO = { name: 'simt-dev', title: 'SIMT developer and agent tooling
  */
 const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
 
+/**
+ * The largest request line this server will answer, in bytes.
+ *
+ * One mebibyte, because the largest honest argument here is a task description or a path
+ * list and both are kilobytes: a line past this is a malformed request or a stream that
+ * lost its newline, and neither should be parsed in full.
+ */
+const MAX_LINE_BYTES = 1 << 20;
+
 /**
  * Handle one parsed request. Pure with respect to the process: returns the response
  * object or null (for a notification), and never writes anywhere. Testable without a
@@ -117,7 +130,17 @@ export async function handle(request, tools, { packageVersion, state, root, sign
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
+  // The envelope is checked before anything reads it. `jsonrpc:"2.0"` and an id that is
+  // a string, a number or absent are the three things every revision requires of a
+  // request. An object id used to be echoed back unchanged, which leaves the client
+  // holding an answer it cannot match to anything it sent (Q56).
+  if (request.jsonrpc !== '2.0') {
+    return error(null, RPC.REQUEST, 'request must carry jsonrpc:"2.0"');
+  }
   const { id, method, params } = request;
+  if (id !== undefined && id !== null && typeof id !== 'string' && typeof id !== 'number') {
+    return error(null, RPC.REQUEST, 'id must be a string, a number or absent');
+  }
   // A notification is a request with no id, and the spec's rule is unconditional: it
   // never gets a response, whatever its method. Answering one anyway desynchronises a
   // client that is waiting for the next real answer in the stream.
@@ -185,11 +208,15 @@ export async function handle(request, tools, { packageVersion, state, root, sign
       }
       return reply({});
 
-    case 'tools/list':
+    case 'tools/list': {
+      const page = paginate(tools, params?.cursor);
+      if (page === null) return badCursor(id);
       return reply({
-        tools: tools.map((t) => describe(t, v)),
+        tools: page.items.map((t) => describe(t, v)),
+        ...nextPage(page),
         ...(cacheable(v) ? LIST_CACHE : {}),
       });
+    }
 
     case 'tools/call': {
       const name = params?.name;
@@ -200,6 +227,15 @@ export async function handle(request, tools, { packageVersion, state, root, sign
         return error(id, RPC.METHOD, `no tool named "${name}"; call tools/list first`);
       }
       const args = params?.arguments ?? {};
+      // The schema in `tools/list` is the schema this server enforces. A tool that
+      // declares `required:['name']` and runs happily on `{}` answers a question nobody
+      // asked, and the answer looks like a real one - `skills_show` with no name used to
+      // be a lookup for the string "undefined" (Q56). Bad arguments are the client's
+      // mistake, so they are a protocol error and not a tool result.
+      const invalid = check(args, tool.inputSchema);
+      if (invalid !== null) {
+        return error(id, RPC.INVALID_PARAMS, `invalid arguments for ${name}: ${invalid}`);
+      }
       // The one impurity in this file, and scoped to it: progress has to reach
       // the client while the tool runs, not after it returns. Nothing else
       // writes here - diagnostics still go to stderr, never this stream.
@@ -222,30 +258,34 @@ export async function handle(request, tools, { packageVersion, state, root, sign
         // `outputSchema` and what it can index; the text block is what a client that
         // predates structured output reads. Emitting one without the other leaves half
         // the clients guessing, which is the state this release was filed for.
-        return reply({
-          content: [contentOf(payload)],
-          structuredContent: payload,
-          isError: false,
-        });
+        const shaped = bounded(payload);
+        return reply({ content: shaped.content, structuredContent: shaped.structuredContent, isError: false });
       } catch (failure) {
         // An error is a result too, and it carries the same two shapes: the remedy is
         // the part a model needs to act on, and it has to survive in whichever block the
         // client reads.
         const payload = { error: failure.message, remedy: failure.remedy ?? null };
-        return reply({ content: [contentOf(payload)], structuredContent: payload, isError: true });
+        const shaped = bounded(payload);
+        return reply({ content: shaped.content, structuredContent: shaped.structuredContent, isError: true });
       }
     }
 
-    case 'resources/list':
+    case 'resources/list': {
+      const page = paginate(await listResources(root), params?.cursor);
+      if (page === null) return badCursor(id);
       return reply(
-        cacheable(v) ? { resources: await listResources(root), ...LIST_CACHE } : { resources: await listResources(root) },
+        cacheable(v) ? { resources: page.items, ...nextPage(page), ...LIST_CACHE } : { resources: page.items, ...nextPage(page) },
       );
-    case 'resources/templates/list':
+    }
+    case 'resources/templates/list': {
+      const page = paginate(RESOURCE_TEMPLATES, params?.cursor);
+      if (page === null) return badCursor(id);
       return reply(
         cacheable(v)
-          ? { resourceTemplates: RESOURCE_TEMPLATES, ...LIST_CACHE }
-          : { resourceTemplates: RESOURCE_TEMPLATES },
+          ? { resourceTemplates: page.items, ...nextPage(page), ...LIST_CACHE }
+          : { resourceTemplates: page.items, ...nextPage(page) },
       );
+    }
     case 'resources/read': {
       // The code for a resource that is not there CHANGED, and a server that answers
       // with one code to both revisions is a server that is wrong to whichever half of
@@ -259,10 +299,13 @@ export async function handle(request, tools, { packageVersion, state, root, sign
         cacheable(v) ? { contents: [found], ...LIST_CACHE } : { contents: [found] },
       );
     }
-    case 'prompts/list':
+    case 'prompts/list': {
+      const page = paginate(PROMPTS, params?.cursor);
+      if (page === null) return badCursor(id);
       return reply(
-        cacheable(v) ? { prompts: PROMPTS, ...LIST_CACHE } : { prompts: PROMPTS },
+        cacheable(v) ? { prompts: page.items, ...nextPage(page), ...LIST_CACHE } : { prompts: page.items, ...nextPage(page) },
       );
+    }
     case 'prompts/get': {
       const name = params?.name;
       // `getPrompt` returns null only for a prompt this server does not have: its
@@ -275,13 +318,27 @@ export async function handle(request, tools, { packageVersion, state, root, sign
       if (found === null) return error(id, RPC.METHOD, `no prompt named "${String(name)}"; call prompts/list first`);
       return reply(found);
     }
+    case 'resources/subscribe':
+    case 'resources/unsubscribe':
+      // A named refusal, not `unknown method`. The capability block above says `resources:
+      // {}` - no subscriptions - so a well-behaved client never asks; one that asks anyway
+      // is asking a protocol question and deserves the reason rather than a message that
+      // reads as a typo and sends it hunting for a spelling.
+      return isNotification
+        ? null
+        : error(id, RPC.METHOD, `${method} is not supported: this server has no change source; resources/list is always current`);
+
     default:
       return isNotification ? null : error(id, RPC.METHOD, `unknown method "${method}"`);
   }
 }
 
+// One entry point, named the way a client names it. This used to spell the CLI command
+// (`simt skills brief`) while the tool description called itself THE entry point and the
+// prompt pointed at `brief` - three answers to "where do I start", and the one a model
+// read first was the only one it could not call (Q56).
 const INSTRUCTIONS =
-  `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`;
+  'Read-only. Every answer is JSON. Call `skills_brief` first: it returns the pre-assembled skill set for a task, plus what it deliberately left out and why, and it needs no index. Call `brief` for the repository packet once the index exists.';
 
 function serverInfo(packageVersion) {
   return { ...SERVER_INFO, version: packageVersion ?? '0.0.0' };
@@ -350,6 +407,22 @@ function decorate(value, version, { packageVersion }) {
   };
 }
 
+/** The cursor field, present only when there is a next page. */
+function nextPage(page) {
+  return page.nextCursor === null ? {} : { nextCursor: page.nextCursor };
+}
+
+/**
+ * A cursor this server did not issue.
+ *
+ * A protocol error, not an empty page: an empty page reads as "the list ended", which is
+ * a different fact from "your cursor is stale" and leads the client to show a partial
+ * estate as a complete one.
+ */
+function badCursor(id) {
+  return error(id, RPC.INVALID_PARAMS, 'invalid cursor: omit it to start at the first page');
+}
+
 function describe(tool, version) {
   const entry = {
     name: tool.name,
@@ -369,17 +442,28 @@ function describe(tool, version) {
   return entry;
 }
 
-/** Content is one text block. Bounded, and truncation is announced in the text itself -
- *  the same rule the CLI follows, because a model that cannot tell a truncated answer
- *  from a complete one will guess. */
-function contentOf(payload) {
-  let text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+/** Both blocks, bounded together.
+ *
+ * `maxBytes` used to cut the text block alone, so a client reading `structuredContent`
+ * got the whole payload beside a text block that said it had been truncated: two answers
+ * to one question, and the unannounced one was the larger. A truncated payload is not the
+ * payload, so the structured block says so in its own shape - a model validating against
+ * `outputSchema` reads a complete-looking object as complete and the missing part as
+ * absent, which is the one reading truncation must never produce (Q56). */
+function bounded(payload) {
+  const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
   const limit = typeof payload === 'object' && payload !== null ? payload.maxBytes : 0;
-  if (Number.isInteger(limit) && limit > 0 && Buffer.byteLength(text) > limit) {
-    const slice = Buffer.from(text).subarray(0, limit).toString('utf8');
-    text = `${slice}\nTRUNCATED ${Buffer.byteLength(text) - limit} bytes omitted; raise maxBytes`;
+  const size = Buffer.byteLength(text);
+  if (!Number.isInteger(limit) || limit <= 0 || size <= limit) {
+    return { content: [{ type: 'text', text }], structuredContent: payload };
   }
-  return { type: 'text', text };
+  const slice = Buffer.from(text).subarray(0, limit).toString('utf8');
+  const omitted = size - limit;
+  const cut = `${slice}\nTRUNCATED ${omitted} bytes omitted; raise maxBytes`;
+  return {
+    content: [{ type: 'text', text: cut }],
+    structuredContent: { truncated: true, omittedBytes: omitted, maxBytes: limit, text: cut },
+  };
 }
 
 function result(id, value) {
@@ -428,6 +512,16 @@ export async function serve(tools, { input = process.stdin, output = process.std
   try {
     for await (const line of rl) {
       if (line.trim() === '') continue;
+      // readline has already buffered this line, so the cap bounds what is parsed and
+      // answered rather than what is read. That is still the difference between a request
+      // the server refuses by name and one it takes apart for minutes: a 40 MB line used
+      // to reach `JSON.parse` and take the process with it (Q56).
+      if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+        output.write(
+          `${JSON.stringify(error(null, RPC.REQUEST, `request is larger than ${MAX_LINE_BYTES} bytes`))}\n`,
+        );
+        continue;
+      }
 
       // Parse and handling fail differently and must answer differently. A line that is
       // not JSON has no id to answer to, so it is a parse error with `id: null`; a

package/src/mcp/tools-facts.mjs

@@ -0,0 +1,326 @@
+// Half of the MCP tool list. The tools are read-only and answer through the commands.
+
+import { loadRegistry } from '../graph/load.mjs';
+import { provenanceDigest } from '../projection/project.mjs';
+import { discover } from '../compare/discover.mjs';
+import { buildRows, resolveConcurrency, summarise } from '../compare/row.mjs';
+import { GATES } from '../hooks/gates.mjs';
+import { checkRepo } from '../commands/sync.mjs';
+import { diagnose, serialisedFindings } from '../commands/doctor.mjs';
+import { rulesCatalogue, rulesWhyFacts } from '../commands/rules.mjs';
+import { skillsBriefFacts, skillsFindFacts, skillsShowFacts, skillsWhyFacts } from '../commands/skills.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+import { DEFAULT_BRIEF_BYTES } from '../brief/packet.mjs';
+import { federationAccess, readFederation } from '../federation/config.mjs';
+import { consult } from '../federation/query.mjs';
+import { planNext, planDone } from '../plan/index.mjs';
+import { buildPrBody } from '../prbody.mjs';
+import { configPaths, readUserConfig, resolveWorkspace } from '../workspace.mjs';
+import { measureSkill } from '../graph/load.mjs';
+import { CLI } from '../name.mjs';
+import { ERROR_SHAPE, GATE_KINDS, noArgs, output, rootArg } from './schemas.mjs';
+import { registry, rootOf } from './schemas.mjs';
+
+export const TOOLS_FACTS = [
+  {
+    outputSchema: output.check,
+    name: 'check',
+    description:
+      'The gate for one repository: region current, unmanaged, drifted or malformed, and rule files lacking an id. Read-only - it never repairs.',
+    inputSchema: rootArg,
+    async run(args) {
+      const root = rootOf(args);
+      const { ok, findings } = await checkRepo(root, {});
+      return { root, ok, findings };
+    },
+  },
+
+  {
+    outputSchema: output.compare,
+    name: 'compare',
+    description:
+      'The workspace matrix: adoption, region, SHA, hooks and gates per repo, plus problems. Pages with limit/cursor; honors progressToken and cancellation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'a workspace directory, or one repository' },
+        workspace: { type: 'string', description: 'workspace root when root is not given' },
+        limit: { type: 'number', description: 'page size; without it every row is built' },
+        cursor: { type: 'string', description: 'opaque page start from a previous partial answer' },
+        concurrency: { type: 'number', description: 'rows built at once (default 4)' },
+      },
+      required: [],
+    },
+    async run(args, ctx = {}) {
+      const root = args?.root ?? args?.workspace ?? (await resolveWorkspace(args ?? {})).root ?? process.cwd();
+      const found = await discover(root);
+      if (found.error) throw Object.assign(new Error(`${root}: ${found.error}`), { remedy: 'pass root' });
+      const expectedSha = await provenanceDigest();
+      const context = { expectedSha, gates: new Set(Object.keys(GATES)), gateKinds: GATE_KINDS };
+      // A page names its start as an index into discovery order, which is
+      // stable between calls on an unchanged estate; garbage parses to 0
+      // rather than erroring, because a dashboard that refuses to run over a
+      // stale cursor is worse than one that restarts the listing.
+      const start = Math.max(0, parseInt(typeof args?.cursor === 'string' ? args.cursor : '0', 10) || 0);
+      const limit = typeof args?.limit === 'number' && args.limit >= 1 ? Math.floor(args.limit) : null;
+      const page = limit === null ? found.repos : found.repos.slice(start, start + limit);
+      const rows = await buildRows(page, context, {
+        concurrency: resolveConcurrency(args ?? {}),
+        signal: ctx?.signal ?? null,
+        onBatch: ctx?.onProgress ? (done, total) => ctx.onProgress(start + done, found.repos.length) : null,
+      });
+      const next = limit !== null && start + page.length < found.repos.length ? String(start + page.length) : null;
+      return {
+        root,
+        shape: found.shape,
+        expectedSha,
+        summary: summarise(rows, { root, shape: found.shape, expectedSha }),
+        repos: rows,
+        worktrees: found.worktrees.map((w) => ({ name: w.name, owner: w.ownerName })),
+        directories: found.directories,
+        ...(limit === null ? {} : { partial: next !== null, cursor: next, total: found.repos.length }),
+      };
+    },
+  },
+  {
+    outputSchema: output.plan_next,
+    name: 'plan_next',
+    description: "The next queued slice whose dependencies are complete; its design section only. Pass id for one slice whether or not it is ready.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        id: { type: 'string', description: 'slice id; when given, return that slice' },
+      },
+      required: [],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const id = typeof args?.id === 'string' && args.id.length > 0 ? args.id : null;
+      const result = await planNext(root, id);
+      if (result.error) throw Object.assign(new Error(result.error), { remedy: result.remedy ?? null });
+      return { root: result.root, next: result.next, reason: result.reason };
+    },
+  },
+  {
+    outputSchema: output.plan_done,
+    name: 'plan_done',
+    // Same function as the command, and deliberately a preview. This surface does
+    // not write: the row change is a diff, and the command applies it behind --yes.
+    description: 'Preview the one-row rewrite for a slice. The write stays on the plan done command, behind --yes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        id: { type: 'string', description: 'slice id' },
+        sha: { type: 'string', description: 'commit sha that closed the slice' },
+        test: { type: 'string', description: 'test command that closed it' },
+        state: { type: 'string', description: 'target state; omitted means the completed state of the repository template (Complete for tracker)' },
+      },
+      required: ['id'],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const result = await planDone(root, args?.id, {
+        sha: args?.sha ?? null,
+        test: args?.test ?? null,
+        state: args?.state ?? null,
+        dryRun: true,
+      });
+      if (result.error) throw Object.assign(new Error(result.error), { remedy: result.remedy ?? null });
+      return {
+        root: result.root,
+        id: result.id,
+        doc: result.doc,
+        line: result.line,
+        from: result.from,
+        to: result.to,
+        wouldChange: result.wouldChange,
+        dryRun: true,
+        remedy: result.remedy,
+      };
+    },
+  },
+  // The PR-flow entry point over this surface: the same engine the `pr-body`
+  // command renders, returning JSON for a model. Read-only like everything
+  // here — it names the tree, reads the ledger and the check cache, and writes
+  // nothing, so the exit-code-never-carries-the-verdict contract stays intact.
+  {
+    outputSchema: output.pr_body,
+    name: 'pr_body',
+    // R41's 2 KB description budget is shared, not per tool: this sentence was
+    // paid for by shortening `brief` and `federation_query`, and the test on the
+    // total holds every future tool to the same trade.
+    description:
+      'The pull request body: ledger evidence for this tree, the decisions the diff touches, gate state, and the ADR-008 verdict with what was not reviewed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        base: { type: 'string', description: 'the ref the body diffs against; defaults to origin/main, then main' },
+      },
+      required: [],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const base = typeof args?.base === 'string' && args.base.length > 0 ? args.base : null;
+      const report = await buildPrBody(root, { base });
+      if (report.error !== null) {
+        throw Object.assign(new Error(report.error), {
+          remedy: `run: ${CLI} pr-body --base <ref> with a ref git knows`,
+        });
+      }
+      return {
+        root,
+        base: report.base,
+        tree: report.tree,
+        verdict: report.verdict,
+        unreviewed: report.unreviewed,
+        paths: report.paths,
+        decisions: report.decisions,
+        gates: report.gates,
+        evidence: report.evidence,
+      };
+    },
+  },
+  {
+    outputSchema: output.brief,
+    name: 'brief',
+    description:
+      'The packet for one task in prompt-sized bytes: kind, commands, files, tests, decisions, skills. With no task it describes the repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        task: { type: 'string', description: "what the agent is about to do, in the user's own words" },
+        paths: { type: 'string', description: 'comma-separated paths to scope the packet to, instead of the files git reports as modified' },
+        budget: { type: 'number', description: 'byte ceiling; 0 means the whole packet (default 2048)' },
+      },
+      required: [],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const budget = Number.isFinite(args?.budget) && args.budget >= 0 ? args.budget : DEFAULT_BRIEF_BYTES;
+      // Read, never build: every tool here declares itself read-only, and a call that
+      // indexed the tree would make that declaration false. A brief with no index to read
+      // says which command makes one - the same rule the delivered packet follows, so a
+      // pull and a push pay the same price and neither one writes.
+      const result = await assembleBrief({
+        root,
+        task: typeof args?.task === 'string' ? args.task : '',
+        paths: typeof args?.paths === 'string' ? args.paths : null,
+        budget,
+        build: false,
+      });
+      if (result.error) throw Object.assign(new Error('the index could not be read'), { remedy: `run: ${CLI} index` });
+      // A repository with no index is not a failed call. Every surface points here first,
+      // so the one tool told to be the entry point must answer in a repository that has
+      // never been indexed - it falls back to the skill packet, which is read from the
+      // package rather than the tree, and names the command that unlocks the rest (Q56).
+      if (result.cold) {
+        const task = typeof args?.task === 'string' ? args.task : '';
+        const facts = await skillsBriefFacts(root, { ...(args ?? {}), task });
+        // Through JSON once, so the packet carries exactly what the text block shows: a
+        // property whose value is `undefined` survives `stringify` as nothing at all, and
+        // the two blocks would then describe different objects.
+        const text = JSON.stringify(facts, null, 2);
+        const packet = JSON.parse(text);
+        const size = Buffer.byteLength(text);
+        return {
+          root,
+          kind: 'skills',
+          basis: 'registry',
+          task,
+          scope: [],
+          budget,
+          bytes: size,
+          before: size,
+          // The skill packet is one document and is not cut to fit: saying the floor held
+          // when the answer is over it is the class of claim this review exists to remove.
+          floorHeld: size <= budget,
+          cut: size <= budget ? [] : ['text'],
+          sections: { skills: (packet.resolved ?? []).map((s) => s.name) },
+          text,
+          note: `no index here, so this is the skill packet; run: ${CLI} index for the repository packet`,
+        };
+      }
+      return {
+        root: result.root,
+        kind: result.kind,
+        basis: result.basis,
+        task: result.task,
+        scope: result.scope,
+        budget: result.budget,
+        bytes: result.packed.after,
+        before: result.packed.before,
+        floorHeld: result.packed.floorHeld,
+        cut: result.packed.cut,
+        sections: result.sections,
+        text: result.packed.text,
+      };
+    },
+  },
+  {
+    outputSchema: output.federation_query,
+    name: 'federation_query',
+    description:
+      'Ask a declared code-graph server one structural question; the answer names the server. Starts only servers simt.json names; none declared is an error.',
+    // This tool spawns the repo manifest's `command`, so it is not read-only: a client
+    // that cached its answer as one would replay a process spawn as a pure read (Q13).
+    annotations: { readOnlyHint: false, openWorldHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        query: { type: 'string', description: "the structural question to ask, in the user's own words" },
+        server: { type: 'string', description: 'ask only this declared server, by name; omit to ask every one of them' },
+      },
+      required: ['query'],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const query = typeof args?.query === 'string' ? args.query.trim() : '';
+      if (query.length === 0) {
+        throw Object.assign(new Error('the query is empty'), {
+          remedy: 'pass a query, for example the symbol or file to look up',
+        });
+      }
+      const { servers, findings } = await readFederation(root);
+      if (servers.length === 0) {
+        throw Object.assign(new Error('this repository declares no federation server'), {
+          remedy: 'add a "federation" block naming a server to simt.json, or use the brief tool',
+        });
+      }
+      const only = typeof args?.server === 'string' && args.server.length > 0 ? args.server : null;
+      const chosen = only === null ? servers : servers.filter((server) => server.name === only);
+      if (only !== null && chosen.length === 0) {
+        throw Object.assign(new Error(`no declared federation server is named ${only}`), {
+          remedy: `declared servers: ${servers.map((server) => server.name).join(', ')}`,
+        });
+      }
+      // A model-supplied root can point at a directory with a crafted manifest, and a
+      // repo manifest alone must not authorise a spawn on the operator's machine (Q13).
+      const ws = await resolveWorkspace(args ?? {});
+      const user = await readUserConfig();
+      const denied = federationAccess({
+        root,
+        cwd: process.cwd(),
+        workspaceRoot: ws.root,
+        serverNames: chosen.map((server) => server.name),
+        userConfig: user.config,
+        configPath: user.path ?? configPaths()[0] ?? '~/.config/simt-dev/config.json',
+      });
+      if (denied !== null) {
+        throw Object.assign(new Error(denied.message), { remedy: denied.remedy });
+      }
+      const { answers, findings: failures } = await consult({ root, query, servers: chosen });
+      return {
+        root,
+        query,
+        servers: chosen.map((server) => server.name),
+        answers,
+        findings: [...findings, ...failures],
+      };
+    },
+  },
+];