amicus 4.9.7 → 4.9.8

package/src/council/run-server.js

@@ -21,10 +21,12 @@
  *      (opencode-client.js) passes only hostname/port/signal/config to
  *      `createOpencodeServer`. The server is directory-agnostic.
  *   2. Scoping is PER CALL: run-launch.js sets `directory: opts.project` on
- *      every launch, fanout threads it to each leg, and runHeadless turns it
- *      into `query.directory` on create/prompt/messages/status/abort (dirArgs,
- *      headless.js). A judge's calls carry `_scratch`; a Stage-1 leg's carry the
- *      run dir. One server answers both, scoped per request.
+ *      every launch except a stage-1 seat launch (`opts.role === 'seat'`,
+ *      P2-R11) that passes `opts.directory` — never a judge/debate/chair
+ *      leg's. fanout threads it to each leg, and runHeadless turns it into
+ *      `query.directory` on create/prompt/messages/status/abort (dirArgs,
+ *      headless.js). A judge's calls carry `_scratch`; a Stage-1 leg's carry
+ *      the run dir. One server answers both, scoped per request.
  *   3. The MCP surface is identical for both stages already: every council
  *      launch passes `noMcp: true` and nothing else MCP-related, and fanout's
  *      buildMcpConfig call receives no `projectDir`, so its result is a pure
@@ -216,7 +218,12 @@ async function acquireRunServer(o, deps = {}) {
   for (const notice of notices) { process.stderr.write(`Notice: ${notice}\n`); }
 
   try {
-    const { client, server } = await startFn(mcpServers, { models });
+    const { client, server } = await startFn(mcpServers, {
+      models,
+      // Spec 2026-09-11 §4: the run's two council agents (run.js computes them
+      // from the intent and --tools before this call).
+      ...(o.councilAgents ? { agents: o.councilAgents } : {}),
+    });
     logger.info('Council run using ONE shared OpenCode server',
       { runId: o.runId, url: server.url, models: models.length });
     // The POSITIVE, durable signal (see the ⚠️ above). `goPid` is the field that
@@ -227,6 +234,7 @@ async function acquireRunServer(o, deps = {}) {
       sharedServer: {
         acquired: true, at: new Date().toISOString(),
         goPid: (server && server.goPid) || null, models: models.length,
+        agents: Object.keys(o.councilAgents || {}),
       },
     }, 'sharedServer');
     return { serverClient: client, server };
@@ -262,4 +270,31 @@ async function releaseRunServer(shared) {
   try { await shared.server.close(); } catch { /* best-effort: the run is over */ }
 }
 
-module.exports = { acquireRunServer, releaseRunServer, resolveRunServerModels, recordServerFate };
+/**
+ * The tool ids the run's engine declares (spec 2026-09-11 §4): what `--tools`
+ * is validated against, read from the engine itself so the accepted set is
+ * never hand-listed. Best-effort and never throws: null means "could not ask"
+ * (no shared server, an engine without the endpoint, a transport error), and
+ * run.js refuses `--tools` on null rather than launching unvalidated.
+ * Measured 2026-09-12 on the pinned SDK 1.18.15 with a keyless server start
+ * (`GET /experimental/tool/ids`); the keyless probe suite
+ * `tests/council-agents-engine.integration.test.js`, added later in this PR,
+ * pins it in CI (P2-R12: this citation named that file before it existed).
+ * @param {{serverClient: object}|null} shared
+ * @param {string} directory the project directory the query is scoped to
+ * @returns {Promise<string[]|null>}
+ */
+async function listEngineToolIds(shared, directory) {
+  const client = shared && shared.serverClient;
+  if (!client || !client.tool || typeof client.tool.ids !== 'function') { return null; }
+  try {
+    const res = await client.tool.ids({ query: { directory } });
+    return (res && Array.isArray(res.data)) ? res.data.slice() : null;
+  } catch (err) {
+    const { logger } = require('../utils/logger');
+    logger.debug('Engine tool list unavailable', { error: err.message });
+    return null;
+  }
+}
+
+module.exports = { acquireRunServer, releaseRunServer, resolveRunServerModels, recordServerFate, listEngineToolIds };

package/src/council/run-stage1-launch.js

@@ -33,6 +33,11 @@ async function launchStage1(ctx) {
     // the chair (run-chair.js) and debate legs (run-debate.js) never receive
     // this, so they never substitute via chains.
     fallback: o.fallback, catalog: o.catalog,
+    // Spec 2026-09-11 §4: stage-1 legs are SEATS (council-seat); with a local
+    // tool opted in they are scoped to the project tree while their metadata
+    // stays in the run dir (`project: o.runDir` above).
+    role: 'seat',
+    ...(o.seatToolsLocal ? { directory: o.project } : {}),
   };
   const launches = [];
   const seated = []; // parallel to `launches`: what each one was SUPPOSED to seat
@@ -47,7 +52,7 @@ async function launchStage1(ctx) {
       seated.push({ waveId, models: [m], roster: seats.slice(i, i + 1) });
       launches.push(launchers.launchSolo({
         ...common, model: m, waveId, seats: seated[seated.length - 1].roster,
-        prompt: briefings.stage1LensBriefing(o.intent, { lens: o.lenses[i], briefing: o.briefing, date: o.date }),
+        prompt: briefings.stage1LensBriefing(o.intent, { lens: o.lenses[i], briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent }),
       }));
     });
   } else {
@@ -61,7 +66,7 @@ async function launchStage1(ctx) {
         roster: seats.filter(s => s.alias !== o.critic) });
       launches.push(launchers.launchWave({
         ...common, models: seats1, waveId: `${o.runId}-s1`, seats: seated[seated.length - 1].roster,
-        prompt: briefings.stage1SeatBriefing(o.intent, { briefing: o.briefing, date: o.date }),
+        prompt: briefings.stage1SeatBriefing(o.intent, { briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent }),
       }));
     }
     if (o.critic) {
@@ -70,7 +75,7 @@ async function launchStage1(ctx) {
         roster: seats.filter(s => s.alias === o.critic).slice(0, 1) });
       launches.push(launchers.launchSolo({
         ...common, model: o.critic, waveId: `${o.runId}-c1`, seats: seated[seated.length - 1].roster,
-        prompt: briefings.stage1CriticBriefing(o.intent, { briefing: o.briefing, date: o.date }),
+        prompt: briefings.stage1CriticBriefing(o.intent, { briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent }),
       }));
     }
   }

package/src/council/run.js

@@ -38,13 +38,13 @@ const { finishRun } = require('./run-finish');
 /**
  * @param {object} options {briefing, models, chair, critic?, lenses?, project, runId,
  *   runDir, timeout?, maxCost?, gateway?, noValidateModel?, date, debate?, noCostGate?,
- *   councilName?, fallback?, catalog?} councilName (v4.3 Task 3) = preset name when
- *   launched via `--council <preset>`, else null — threaded via ctx.o into every
- *   launchWave/launchSolo for leg ledger attribution. fallback/catalog (v4.3 Task 18
- *   §6.2): ctx.o carries both, but only run-stages.js's stage launches read them —
- *   the chair/debate legs never substitute via chains.
+ *   councilName?, fallback?, catalog?, tools?: string[], agent?: 'Plan'|'Build'} councilName
+ *   (v4.3 Task 3) = preset name when launched via `--council <preset>`, else null —
+ *   threaded via ctx.o into every launchWave/launchSolo for leg ledger attribution.
+ *   fallback/catalog (v4.3 Task 18 §6.2): ctx.o carries both, but only run-stages.js's
+ *   stage launches read them — the chair/debate legs never substitute via chains.
  * @param {object} [deps] {launchers?, appendRunFn?, statsFn?, installSignalAbortFn?,
- *   startOpenCodeServerFn? (v4.4.1 Task 0.5 test seam, see ./run-server)}
+ *   startOpenCodeServerFn?, listEngineToolIdsFn? (v4.4.1 Task 0.5 / spec 2026-09-11 §4 test seams, see ./run-server)}
  * @returns {Promise<{exitCode: number, run: object}>}
  */
 async function runCouncil(options, deps = {}) {
@@ -70,22 +70,13 @@ async function runCouncil(options, deps = {}) {
   // below (a getter, because the launchers are built first); null = as before.
   let sharedServer = null;
   const launchers = deps.launchers
-    || createLaunchers({ remainingBudget, reserveBudget, onBudgetRefusal: noteBudgetRefusal, sharedServer: () => sharedServer });
+    || createLaunchers({ remainingBudget, reserveBudget, onBudgetRefusal: noteBudgetRefusal, sharedServer: () => sharedServer,
+      councilAgents: () => o.councilAgents || null, agentOverride: () => o.agent }); // spec 2026-09-11 §4: getters, decided below.
 
   runState.initCouncilRun(o); // run.json seed + sessions-dir pointer (run-state.js)
 
-  // dropped-members (spec §5, Plan 4): a seat the user's preset requested that
-  // never resolved is a lost seat — announced like every other loss. Fires
-  // once per member, before any launch (zero spend), for BOTH transports.
-  for (const dm of o.droppedMembers || []) {
-    degrade.note({
-      channel: 'dropped-members',
-      what: `seat ${dm.member} was not seated`,
-      why: dm.reason,
-      effect: 'the bench is smaller than the preset requested; the run will exit degraded (2)',
-      data: { member: dm.member, reason: dm.reason },
-    });
-  }
+  // dropped-members announcement lives in ./run-degrade (300-line gate, P2-R14).
+  require('./run-degrade').noteDroppedMembers(degrade, o.droppedMembers);
 
   emitRunStarted(o.runDir, o.runId, { bench: o.models, chair: o.chair }, o.follow);
 
@@ -113,8 +104,15 @@ async function runCouncil(options, deps = {}) {
     return { exitCode: code, run };
   };
 
+  // Spec 2026-09-11 §4 (PR 2): seat tools decided + refused pre-spend, checked below.
+  const st = require('./run-seat-tools').preflightSeatTools(o);
+  if (st.error) { return finalize(1, st.error); }
+  Object.assign(o, { seatTools: st.seatTools, seatToolsLocal: st.seatToolsLocal, councilAgents: st.councilAgents });
+
   // Injected launchers bring their own transport. Never throws — degrades to null.
   if (!deps.launchers) { sharedServer = await require('./run-server').acquireRunServer({ ...o, degrade }, deps); }
+  const ev = await require('./run-seat-tools').validateSeatToolsAgainstEngine(o, sharedServer, deps);
+  if (ev.error) { return finalize(1, ev.error); }
 
   const ctx = { o, launchers, addWave, overBudget, degrade, scratchDir: path.join(o.runDir, '_scratch') };
 
@@ -142,11 +140,13 @@ async function runCouncil(options, deps = {}) {
     o.seats = seatPre.seats;
     o.criticSeat = seatPre.criticSeat;
     runState.checkpoint(o.runDir, { seats: o.seats, criticSeat: o.criticSeat,
-      ...(o.intent === 'task' ? { intent: 'task' } : {}) });   // v4.9 W5.3: emit-when-'task', never 'review'
+      ...(o.intent === 'task' ? { intent: 'task' } : {}),   // v4.9 W5.3: emit-when-'task', never 'review'
+      // spec §4: seatTools emit-when-non-empty, agentOverride emit-when-set.
+      ...(o.seatTools && o.seatTools.length ? { seatTools: o.seatTools } : {}), ...(o.agent ? { agentOverride: o.agent } : {}) });
 
     // Composed Stage-1 seat briefing persisted for auditability (spec §4 layout).
     fs.writeFileSync(path.join(o.runDir, 'briefing-stage1.md'),
-      briefings.stage1SeatBriefing(o.intent, { briefing: o.briefing, date: o.date }), { mode: 0o600 });
+      briefings.stage1SeatBriefing(o.intent, { briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent }), { mode: 0o600 });
 
     // ---- Stage 1: independent reviews ----
     // Lens mode launches one solo per seat instead of a `-s1` seat wave, so it

package/src/council/seat-tools.js

@@ -0,0 +1,299 @@
+// src/council/seat-tools.js
+'use strict';
+
+/**
+ * @module council/seat-tools
+ * Per-run tool policy for council seats (spec 2026-09-11 §4, PR 2 of 3).
+ *
+ * The study (§1) found two of the three leg-loss classes share one precondition:
+ * a stage-1 seat reached for a tool it did not need (gemini grep/glob over the
+ * global install, cohere `task {}`). Tool access is a property of the RUN, set
+ * by the caller according to whether the seat must go and get its material
+ * (§2.1): task mode defaults to `webfetch`, review to nothing, `--tools` opts
+ * more in, and two ids are never available to a headless seat without the
+ * `--agent` override. This module is pure: it decides, and builds the two agent
+ * configs the run's OpenCode server registers (run-server.js). Nothing here
+ * talks to the engine — the engine's declared ids are passed IN (`declaredIds`)
+ * by run.js after the server is up, so the accepted set is never hand-listed.
+ */
+
+const { CHAIR_NO_TOOLS_LEAD } = require('./briefings-chair');
+
+/**
+ * Ids a council seat may never opt into. Hand-listed on purpose: each names why.
+ * Everything else is validated against the engine's own `tool.ids()`.
+ */
+const REFUSED_TOOL_IDS = Object.freeze({
+  task: 'spawns child sessions amicus cannot observe',
+  skill: 'is where a seat starts reading the harness instead of the brief',
+  question: 'asks a human, and a headless leg has none',
+  invalid: 'is the engine\'s error surface, not a tool',
+  edit: 'a council seat never modifies the tree',
+  write: 'a council seat never modifies the tree',
+  apply_patch: 'a council seat never modifies the tree',
+});
+
+/** Ids that never touch the local tree: the remote fetchers, plus the engine's own todo list. */
+const NON_LOCAL_TOOL_IDS = Object.freeze(['webfetch', 'websearch', 'todowrite']);
+const SEAT_READ_DENY_PATTERNS = Object.freeze(['*.env', '*.env.*', '*.envrc']); // measured 2026-09-12: patterns a granted `read` must never cover
+
+/**
+ * True if `tools` contains anything outside NON_LOCAL_TOOL_IDS. Single source for the
+ * local/remote predicate — resolveSeatTools and seatToolsSentence both call this
+ * instead of each re-writing the same `.some()` (review r1 P2-R8: before this fix,
+ * `buildCouncilAgents` accepted a `local` flag that could contradict its own `tools`,
+ * silently dropping `external_directory: 'deny'`; it now denies that key
+ * unconditionally and takes no `local` flag). A third caller (PR 2
+ * Task 5 review r1, P2-R19): cli-council-run-tools.js's out-dir fence, which decides
+ * whether a run's directory may sit outside the project tree.
+ * @param {string[]} tools @returns {boolean}
+ */
+function isLocal(tools) {
+  return tools.some((id) => !NON_LOCAL_TOOL_IDS.includes(id));
+}
+
+/**
+ * `--tools`/`--agent` are mutually exclusive (ruling P2-R28, supersedes P2-R25's
+ * MCP-only short-circuit): the override already runs every leg on its own agent.
+ * @param {string|null|undefined} agent @param {string[]|undefined} tools
+ * @returns {string|null} the refusal message, or null when there is no conflict
+ */
+function agentToolsConflict(agent, tools) {
+  if (!agent || !Array.isArray(tools) || !tools.length) { return null; }
+  return `--tools cannot be combined with --agent: the override runs every leg on the engine's own ${agent} agent with that agent's own tool set; drop one of them`;
+}
+
+const ESCAPE_HATCH = '--agent Build';
+const ID_SHAPE = /^[a-z][a-z0-9_]*$/;
+
+/** @param {'task'|undefined} intent @returns {string[]} */
+function defaultToolsFor(intent) {
+  return intent === 'task' ? ['webfetch'] : [];
+}
+
+/**
+ * Normalize raw values the way `--tools` does: String, trim, lowercase, drop empties.
+ * Shared by parseToolsFlag and resolveSeatTools so a value from EITHER door — the CLI
+ * flag's comma string or a direct `optIn` array (MCP arg, a config list) — is cleaned
+ * identically before it is ever compared against REFUSED_TOOL_IDS or ID_SHAPE.
+ * @param {unknown[]} raw @returns {string[]}
+ */
+function normalizeIds(raw) {
+  return raw.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
+}
+
+/**
+ * The one shape-error message text both doors use, so it has a single source.
+ * @param {string[]} ids @returns {string|null}
+ */
+function shapeErrorFor(ids) {
+  const bad = ids.filter((id) => !ID_SHAPE.test(id));
+  return bad.length ? `--tools: not a tool id: ${bad.join(', ')}` : null;
+}
+
+/**
+ * The `--tools` flag's value → ids. Shape only; refusals and the engine check
+ * live in resolveSeatTools so every door reaches them.
+ * @param {unknown} value
+ * @returns {{ok: true, ids: string[]}|{ok: false, message: string}}
+ */
+function parseToolsFlag(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    return { ok: false, message: '--tools requires a comma-separated list of tool ids (e.g. --tools webfetch,read)' };
+  }
+  const ids = [...new Set(normalizeIds(value.split(',')))];
+  if (!ids.length) { return { ok: false, message: '--tools requires at least one tool id' }; }
+  const shapeError = shapeErrorFor(ids);
+  if (shapeError) { return { ok: false, message: shapeError }; }
+  return { ok: true, ids };
+}
+
+/**
+ * The REFUSED_TOOL_IDS check, factored out of resolveSeatTools (review r1
+ * P2-R20) so it has one message and one caller list: resolveSeatTools (CLI
+ * defaults + opt-in) and resolveRemoteOnlyTools (the MCP door) must refuse
+ * `task`/`skill`/… identically — a permanently-refused id is refused for the
+ * SAME reason regardless of which door it arrived through, never described
+ * as a placement (local-vs-remote) problem the way an ordinary local tool is.
+ * `ids` must already be normalized (lowercase/trimmed) — every caller here
+ * goes through normalizeIds or parseToolsFlag first.
+ * @param {string[]} ids @returns {{ok: false, code: 'BAD_ARGS', message: string}|null}
+ */
+function refusalFor(ids) {
+  const refused = ids.filter((id) => Object.prototype.hasOwnProperty.call(REFUSED_TOOL_IDS, id));
+  if (!refused.length) { return null; }
+  return {
+    ok: false, code: 'BAD_ARGS',
+    message: `--tools: ${refused.map((id) => `${id} (${REFUSED_TOOL_IDS[id]})`).join('; ')} — refused for council seats; ` +
+      `${ESCAPE_HATCH} runs every leg on the engine's full Build agent instead`,
+  };
+}
+
+/**
+ * The MCP door's tool policy (spec 2026-09-11 §4, ledger P2-R2): over MCP the
+ * run directory must stay inside the project (the fence in mcp-council-run.js),
+ * so a seat cannot be placed there with a LOCAL tool — refused with a message
+ * naming the CLI command that DOES allow it (an out-of-project --out-dir). A
+ * PERMANENTLY-refused id (review r1 P2-R20: task/skill/question/invalid/edit/
+ * write/apply_patch) is refused first, with refusalFor's reason — it is not a
+ * placement problem, and NON_LOCAL_TOOL_IDS.includes(id) is false for every one
+ * of them, so without this check the local-tools branch below caught them too
+ * and suggested an --out-dir command that would ALSO fail (resolveSeatTools
+ * refuses these ids unconditionally, everywhere, run-directory or not).
+ * Tools that never touch the tree (webfetch, websearch, todowrite) carry no
+ * placement requirement and ride through. Shape-checked the same way the CLI flag is (parseToolsFlag), so
+ * `mcp-council-run.js` never re-implements comma-splitting/normalizing for an
+ * input that happens to arrive as an array instead of a flag string. An empty
+ * array is treated as absent (`{ok: true, ids: []}`) rather than the
+ * `--tools`-with-nothing-typed shape error parseToolsFlag('') would raise —
+ * the MCP schema's `z.array(z.string().min(1))` allows `[]` (`.min(1)`
+ * constrains each string, not the array), so a caller can send it without
+ * ever having typed a flag at all.
+ * @param {string[]|string} input MCP `tools` input: an array (the declared
+ *   schema shape) or a string (defense-in-depth for a caller that bypasses it).
+ * @returns {{ok: true, ids: string[]}|{ok: false, message: string}}
+ */
+function resolveRemoteOnlyTools(input) {
+  if (Array.isArray(input) && !input.length) { return { ok: true, ids: [] }; }
+  const parsed = parseToolsFlag(Array.isArray(input) ? input.join(',') : String(input));
+  if (!parsed.ok) { return { ok: false, message: parsed.message }; }
+  const refusal = refusalFor(parsed.ids);
+  if (refusal) { return { ok: false, message: refusal.message }; }
+  // Named mutant MCPLOCALLEAK: dropping this filter/refusal lets a local id
+  // (e.g. `read`) ride through as `ok: true`, reaching the spawned CLI child
+  // whose run dir is fenced INSIDE the project — the exact placement spec §4
+  // forbids. Reddens 'a local id is refused with a message naming the CLI
+  // (MCPLOCALLEAK target)' in tests/council/seat-tools.test.js and 'a local
+  // tool over MCP is refused before anything spawns — the MCP run dir must
+  // stay inside the project' in tests/mcp-council-run.test.js.
+  const local = parsed.ids.filter((id) => !NON_LOCAL_TOOL_IDS.includes(id));
+  if (local.length) {
+    return {
+      ok: false,
+      message: `tools: ${local.join(', ')} are local tools; over MCP the run directory must stay inside the project, ` +
+        'and a seat with local tools must not run there. Use `amicus council run --tools ' + parsed.ids.join(',') +
+        ' --out-dir <dir outside the project>` from the CLI.',
+    };
+  }
+  return { ok: true, ids: parsed.ids };
+}
+
+/**
+ * Decide the seat's tool list: `defaultToolsFor(intent) ∪ optIn`, minus nothing —
+ * a refused, malformed, or unknown id fails the whole run BEFORE any spend.
+ * @param {{intent?: 'task'|undefined, optIn?: string[], declaredIds?: string[]|null}} args
+ *   `declaredIds` null/absent = the engine has not been asked yet (shape + refusals only).
+ * @returns {{ok: true, tools: string[], local: boolean}|{ok: false, code: 'BAD_ARGS', message: string}}
+ */
+function resolveSeatTools({ intent, optIn = [], declaredIds = null } = {}) {
+  if (!Array.isArray(optIn)) { return { ok: false, code: 'BAD_ARGS', message: `--tools must be a list of tool ids (got ${typeof optIn})` }; }
+  // Normalize + shape-check optIn BEFORE anything else, so a door that never goes
+  // through parseToolsFlag (an MCP arg array, a config list) reaches the same gates
+  // the --tools flag does. Skipping this is a named mutant: OPTINRAW — 'Task' would
+  // then dodge the refusal check below (REFUSED_TOOL_IDS keys are lowercase) and
+  // '../x' would dodge the shape check whenever declaredIds is null; reddens 'a
+  // case-variant refused id is caught without the engine list' and 'an opted-in id
+  // with a bad shape is refused without the engine list' in seat-tools.test.js.
+  const normalizedOptIn = normalizeIds(optIn);
+  const shapeError = shapeErrorFor(normalizedOptIn);
+  if (shapeError) { return { ok: false, code: 'BAD_ARGS', message: shapeError }; }
+  const requested = [...new Set([...defaultToolsFor(intent), ...normalizedOptIn])];
+  const refusal = refusalFor(requested);
+  if (refusal) { return refusal; }
+  if (Array.isArray(declaredIds)) {
+    const unknown = requested.filter((id) => !declaredIds.includes(id));
+    if (unknown.length) {
+      const offered = declaredIds.filter((id) => !Object.prototype.hasOwnProperty.call(REFUSED_TOOL_IDS, id)).sort();
+      return {
+        ok: false, code: 'BAD_ARGS',
+        message: `--tools: the engine does not declare ${unknown.join(', ')}; it declares: ${offered.join(', ')}`,
+      };
+    }
+  }
+  const tools = requested.slice().sort();
+  return { ok: true, tools, local: isLocal(tools) };
+}
+
+/**
+ * The two agents the run's server registers (spec §4). `'*': false` is the
+ * engine's wildcard (measured 2026-09-12: renders a `*=deny` rule, and each
+ * `true` renders `<id>=allow` after it). The `webfetch` permission key below
+ * follows the `tools` map by construction, not by separate measurement — the
+ * 2026-09-12 pass measured `edit`/`bash`/`external_directory`, not `webfetch`;
+ * Task 7's engine probe is what asserts the map and the permission stay in
+ * agreement on the pinned engine.
+ *
+ * `.env` files (review r1 P2-R9, superseding the brief's "read[*.env]=ask → B53
+ * stall" sentence): the engine evaluates permission with `findLast` over the
+ * merged rule list (opencode v1.18.15, packages/opencode/src/permission/index.ts),
+ * and its own `read[*.env]=ask` default rule renders BEFORE the seat's tools-map
+ * `read=allow` — so a bare `tools.includes('read')` would let a seat granted
+ * `read` read `.env` outright, not stall; that is a secrets exposure, not a
+ * documented limitation. Measured fix: a nested `permission.read` object renders
+ * AFTER the tools map and wins under `findLast`. `read: { '*': 'allow', '*.env':
+ * 'deny', '*.env.*': 'deny' }` is measured to deny `.env`/`.env.*` and allow
+ * everything else; the `'*': 'allow'` entry is REQUIRED — measured without it,
+ * the object REPLACES rather than refines the tools-derived allow and ordinary
+ * reads fall through to `*=deny`. `grep` and `bash` have no such fence: opting
+ * either in trusts the seat with the tree's contents, `.env` included. Never
+ * emits `chat`.
+ * @param {{tools: string[]}} args
+ * @returns {{'council-seat': object, 'council-support': object}}
+ */
+function buildCouncilAgents({ tools = [] } = {}) {
+  const allow = Object.fromEntries(tools.map((id) => [id, true]));
+  return {
+    'council-support': {
+      description: 'Council support role (repair, judge, debate, chair): no tools — the material is in the briefing.',
+      mode: 'primary',
+      tools: { '*': false },
+      permission: { edit: 'deny', bash: 'deny', webfetch: 'deny', external_directory: 'deny' },
+    },
+    'council-seat': {
+      description: `Council stage-1 seat: tools ${tools.length ? tools.join(', ') : 'none'}.`,
+      mode: 'primary',
+      tools: { '*': false, ...allow },
+      permission: {
+        edit: 'deny',
+        bash: tools.includes('bash') ? 'allow' : 'deny',
+        webfetch: tools.includes('webfetch') ? 'allow' : 'deny',
+        // council-seat always denies external directories; a tree cannot own
+        // that key — even a webfetch-only seat gets this rule (measured 2026-09-12).
+        external_directory: 'deny',
+        // The '*': 'allow' entry is load-bearing, not decorative (measured 2026-09-12):
+        // a nested `read` object REPLACES, rather than refines, the tools-map's
+        // read=allow under the engine's findLast evaluation. Dropping it is a named
+        // mutant: ENVALLOWDROP — every ordinary read would then fall through to the
+        // wildcard *=deny; reddens 'a read seat gets a nested .env-denying read
+        // permission' in seat-tools.test.js.
+        ...(tools.includes('read') ? { read: { '*': 'allow', ...Object.fromEntries(SEAT_READ_DENY_PATTERNS.map((p) => [p, 'deny'])) } } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * The briefing line a seat gets about its tools (spec §4 "briefing lines").
+ * No tools → the shared no-tools sentence (briefings-chair.js), forked only on
+ * its last word, exactly like the chair's. Config enforces; this informs (E1:
+ * told not to, gemini complied). Under `--agent` (ruling P2-R31), `tools` is ignored.
+ * @param {string[]} tools @param {'review'|'answer'} kind @param {{agent?: string}} [opts]
+ */
+function seatToolsSentence(tools, kind, { agent } = {}) {
+  // Named mutant OVERRIDESENTENCEDROP: dropping this branch would brief an
+  // --agent-override seat as if a computed allowlist still applied.
+  if (agent) {
+    return `You run as the engine's ${agent} agent with its own tool set; use tools only where ` +
+      'the deliverable needs them; if research is incomplete, say so in the deliverable rather ' +
+      'than leave it unwritten.';
+  }
+  if (!tools || !tools.length) { return `${CHAIR_NO_TOOLS_LEAD}${kind}.`; }
+  const forbid = isLocal(tools) ? '' : ' — do not attempt to read files, search directories, or run commands';
+  return `Your tools: ${tools.join(', ')}. You have no others${forbid}; if research is incomplete, ` +
+    'say so in the deliverable rather than leave it unwritten.';
+}
+
+module.exports = {
+  REFUSED_TOOL_IDS, REMOTE_TOOL_IDS: NON_LOCAL_TOOL_IDS, NON_LOCAL_TOOL_IDS, SEAT_READ_DENY_PATTERNS, defaultToolsFor,
+  parseToolsFlag, resolveSeatTools, resolveRemoteOnlyTools, buildCouncilAgents, seatToolsSentence, isLocal, agentToolsConflict,
+};

package/src/council/verdict-seats-reviewed.js

@@ -14,15 +14,31 @@
  * repairs are not bench seats. `reviewed` is those whose leg completed: a
  * `timeout` is not a review any more than an `error` is.
  *
+ * `unverified` (#242 / spec §5, v4.9.8) is those bench seats whose findings came from a
+ * repair of a response with no parseable findings block — the LC-11 flag
+ * run-stages.js :: runStage1 sets on the row. The seat stays in `reviewed` (its leg
+ * completed) and is counted here too. ALWAYS written once the census is: 0 is a
+ * measurement, absence keeps its one meaning. Key order is reviewed / unverified / refused / of —
+ * the shape spec §5 names and the council-review check title prints. Not a stub count
+ * (study run B2: a real 19,064-byte review with a malformed trailing block carried the
+ * flag). A refused repair (`repairRefused`) is NOT counted under `unverified` — that seat
+ * tallied no findings at all — and since council #248 round 2 it has its OWN number,
+ * `refused` (P3-R17): a seat that contributed nothing is visible on the same gate surfaces
+ * (title, footer, stderr) and never reads as a full reviewer on them.
+ *
+ * `unverified ⊆ reviewed` and "bench rows only" are STRUCTURAL (council #248 round 1, B1/C2/D2):
+ * `isUnverifiedSeat` requires a bench role, `status: 'complete'` and the literal `true`, and
+ * report-lost-rows.js :: lostRowsOf uses that same function — so the census and the report agree
+ * on every input, engine-written or hand-assembled, and `unverified` can never exceed `reviewed`.
+ * On engine-written records the gate is a no-op: run-launch.js :: materializeReviews drops every
+ * non-complete leg before a repair can run, and seats.js :: buildSeats / run-stages.js :: roleFor
+ * mint only bench roles (V6/V14 show why hand-assembled records reach buildVerdict at all).
+ *
  * A LEAF: it requires nothing, matching its seat-loss sibling.
  */
 
 'use strict';
 
-/**
- * @param {Array<object>|undefined} runStats
- * @returns {{seatsReviewed?: {reviewed: number, of: number}}}
- */
 /**
  * Is this runStats row a BENCH seat — something that was asked to review?
  *
@@ -41,6 +57,47 @@ function isBenchRole(role) {
     || (typeof role === 'string' && role.startsWith('lens:'));
 }
 
+/**
+ * The ONE predicate for "this row is an unverified review", shared with
+ * report-lost-rows.js :: lostRowsOf so the census and the report can never disagree
+ * (council #248 round 1, B1/C2/D2: `unverified` counted flagged rows regardless of
+ * status, so a hand-assembled or MCP record could publish `reviewed 0 · unverified 1`
+ * and CI would print `seats 0/1 (1 unverified)`). STRUCTURAL, not producer trust: a
+ * bench role, a COMPLETED leg, and the literal `true` tally.js emits. A flagged row that
+ * is not a completed bench seat is an unverified review of nothing — counted nowhere and
+ * rendered nowhere; a real dead leg has the sink's own dead-leg row. `unverified` can
+ * therefore never exceed `reviewed` (V15/V16). Named mutant: SUBSETBLIND
+ * (`&& r.status === 'complete'` deleted from this function).
+ */
+// !Array.isArray: an array carrying named properties is not a row — lostRowsOf's own plain-object guard already skips it, and the census must agree.
+function isUnverifiedSeat(r) {
+  return !!r && typeof r === 'object' && !Array.isArray(r) && isBenchRole(r.role)
+    && r.status === 'complete' && r.findingsUnverified === true;
+}
+
+/** Its sibling for a refused repair: the same gate, and `repairRefused` a plain object. */
+function isRefusedSeat(r) {
+  return !!r && typeof r === 'object' && !Array.isArray(r) && isBenchRole(r.role) && r.status === 'complete'
+    && !!r.repairRefused && typeof r.repairRefused === 'object' && !Array.isArray(r.repairRefused);
+}
+
+/**
+ * The row's label on every human surface — the report rows and the end-of-run stderr line —
+ * so the two can never name one row differently (council #248 r2, A3): the seat id when the
+ * bench repeats an alias, else the alias (the `seat || model` rule the street-cred rows use in
+ * both renderers), and 'unknown' for a hand-assembled row carrying neither — silence would
+ * hide the flag.
+ */
+function seatLabel(r) {
+  if (r && typeof r.seat === 'string' && r.seat) { return r.seat; }
+  if (r && typeof r.model === 'string' && r.model) { return r.model; }
+  return 'unknown';
+}
+
+/**
+ * @param {Array<object>|undefined} runStats
+ * @returns {{seatsReviewed?: {reviewed: number, unverified: number, refused: number, of: number}}}
+ */
 function seatsReviewedOf(runStats) {
   // ⚠️ `Array.isArray`, NOT `runStats || []`. buildVerdict is reachable on
   // externally-supplied records that never touched tally() in-process — the MCP
@@ -49,12 +106,25 @@ function seatsReviewedOf(runStats) {
   // truthy non-array sails past `||` and throws on `.filter`, turning a missing
   // census into a crashed verdict build. The closed-literal comment further down
   // makes the same argument about the same caller.
-  const seats = (Array.isArray(runStats) ? runStats : []).filter(r => r && isBenchRole(r.role));
+  // A row is a PLAIN OBJECT: an array wearing row properties is not a seat (council #248 r2, A5) —
+  // the same guard the shared predicates carry, so of/reviewed/unverified/refused and the report
+  // rows all agree on every input.
+  const seats = (Array.isArray(runStats) ? runStats : [])
+    .filter(r => !!r && typeof r === 'object' && !Array.isArray(r) && isBenchRole(r.role));
   if (seats.length === 0) { return {}; }
   return { seatsReviewed: {
     reviewed: seats.filter(r => r.status === 'complete').length,
+    // The shared predicate (isUnverifiedSeat above): `=== true` matching tally.js's
+    // emit-when-true (V14), a completed leg (V15/V16). Named mutants: CENSUSZERO
+    // (`unverified: 0`) and SUBSETBLIND — tests/council/verdict.test.js.
+    unverified: seats.filter(isUnverifiedSeat).length,
+    // council #248 round 2 (A2/C2, ruling P3-R17): a refused repair — the seat tallied NO findings
+    // — was invisible on every gate surface while counting as a full reviewer. Its own number,
+    // always written, never more than `reviewed` (the same predicate gate), NOT folded into
+    // `unverified` (a seat with no findings has no unverified findings).
+    refused: seats.filter(isRefusedSeat).length,
     of: seats.length,
   } };
 }
 
-module.exports = { seatsReviewedOf };
+module.exports = { seatsReviewedOf, isBenchRole, isUnverifiedSeat, isRefusedSeat, seatLabel };