amicus 4.9.7 → 4.10.0

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 };

package/src/headless.js

@@ -877,6 +877,29 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // block comment beside `sessionId`) so the catch-all return can carry it.
     let toolStalled = false; // B53: distinct from completed/timedOut/aborted — see resolveTerminalState
     let lastSettledToolCount = 0; // B4: tool calls observed reaching a terminal status
+    // 2026-09-11 spec §3: what session.status said on the most recent read this
+    // poll. The stable-idle heuristic below defers to it — a busy engine with no
+    // live tool is a model still answering, not a dead leg (study run D0: three
+    // deliverables discarded 39–107 s before they finished while this said busy).
+    let lastSdkStatus = 'unread';
+    // One trace line per flat stretch the veto holds open (spec §3 as amended 2026-09-11):
+    // cleared whenever a poll progresses, set on the first vetoed poll of the stretch.
+    let vetoLoggedThisStretch = false;
+    // Council #246 (2026-09-11): the `next` half of the bound finding. When session.status
+    // is `retry`, the engine's own timestamp for the next attempt — epoch ms: opencode's
+    // session/processor.ts sets `next: Date.now() + delay`. If it lies past this leg's
+    // deadline, waiting cannot produce a
+    // deliverable; the leg ends at once with the named reason RETRY_BEYOND_DEADLINE and the
+    // session is aborted post-loop like the backstop path. Under a relative reading of
+    // `next` the comparison stays inert (a delay in ms never exceeds an epoch deadline),
+    // so the only failure mode is "no early exit". Named mutant "NEXTIGNORED" (drop the
+    // comparison) reddens exactly the retry-beyond-deadline case in headless-idle-completion
+    // — measured 1 of 13, killed by that case's own 10 s jest timeout because the leg then
+    // runs to its 60 s --timeout instead. "FINISHEDRETRYEXIT" (drop the assistantFinished
+    // guard) reddens the finalized-plus-retry case. "RETRYOVERTOOL" (drop the
+    // liveTools guard) reddens the retry-with-live-tool case.
+    let lastSdkRetryNext = null;
+    let retryBeyondDeadline = false;
 
     // ---- v4.4 B4 part 1: the tool-settle deferral -----------------------------
     // Recomputed once per poll (see the loop body) so every completion gate in a
@@ -1201,9 +1224,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           break;
         }
 
-        // Authoritative idle signal from the OpenCode SDK (preferred over the heuristic).
-        // Gate on real output so a pre-processing 'idle' cannot end the run early.
-        // Best-effort: on any error, fall back to the activity heuristic below.
+        // Authoritative signal from the OpenCode SDK: `idle` ends the leg here; `busy` or
+        // `retry` vetoes the activity heuristic below (2026-09-11 spec §3) unless a tool
+        // call is live, in which case the B4 ceiling governs. Once the message has finalized
+        // the stable-finished path ends it regardless of status. Gate on real output so a
+        // pre-processing 'idle' cannot end the run early. On any error the heuristic
+        // runs as the fallback it was always meant to be.
         if (mirror.output.length > 0) {
           try {
             const remainingForStatus = deadline - Date.now();
@@ -1213,6 +1239,26 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
               'getSessionStatus'
             );
             const s = (statusData && statusData.type) ? statusData : (statusData && statusData[sessionId]);
+            lastSdkStatus = (s && typeof s.type === 'string') ? s.type : 'other';
+            lastSdkRetryNext = (s && s.type === 'retry' && Number.isFinite(s.next)) ? s.next : null;
+            // Council #246 round 2 (C1/B2): never on a finalized last message — the
+            // stable-finished path ends that leg in two polls whatever the session-level
+            // status says (a `retry` here belongs to the engine's next step), and its text
+            // must not be discarded. Named mutant "FINISHEDRETRYEXIT" (drop
+            // `!assistantFinished`) reddens the finalized-plus-retry case.
+            // Council #246 round 3 (D1): never while a tool call is live either — the B4
+            // bounded tool-settle ceiling governs a live tool everywhere else in this loop and
+            // must here too; a retry-with-live-tool is not a shape the engine produces, but a
+            // lagging mirror can show one. Named mutant "RETRYOVERTOOL" (drop the liveTools
+            // guard) reddens the live-tool case.
+            if (!assistantFinished && liveTools.length === 0 && lastSdkRetryNext !== null && lastSdkRetryNext > deadline) {
+              retryBeyondDeadline = true;
+              sessionError = `RETRY_BEYOND_DEADLINE: the engine schedules the next attempt at ${new Date(lastSdkRetryNext).toISOString()}, after this leg's deadline ${new Date(deadline).toISOString()}${formatSessionStatusSuffix(s)}`;
+              logger.warn('Provider backoff exceeds the leg deadline; ending the leg now instead of waiting', {
+                taskId, attempt: s.attempt, next: lastSdkRetryNext, deadline,
+              });
+              break;
+            }
             if (s && s.type === 'idle' && !deferForUnsettledTools('sdk-idle')) {
               logger.debug('Session reported idle by SDK — completing', { sessionId });
               completed = true;
@@ -1220,6 +1266,8 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             }
           } catch (statusErr) {
             logger.debug('session.status unavailable; using activity heuristic', { error: statusErr.message });
+            lastSdkStatus = 'unavailable';
+            lastSdkRetryNext = null;
           }
         }
 
@@ -1271,7 +1319,51 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         if (!progressed) {
           // Require real output before counting toward completion — the SDK creates an
           // empty assistant-message placeholder on promptAsync that is NOT a finished response.
-          if (currentAssistantMsgId !== null && mirror.output.length > 0) {
+          //
+          // 2026-09-11 spec §3: the heuristic is the FALLBACK for when session.status is
+          // unavailable, not a second opinion on it. While the engine says `busy` or
+          // `retry` (provider backoff — the engine has not given up; utils/session-status.js
+          // reads the same arm) and no tool call is live, the model is generating —
+          // in-flight parts are invisible to this poller (measured: in-flight parts never
+          // grow outputLength — 0 for the whole stream without tools, A1/E1; flat at the
+          // narration length with them, D0), so flat output here is not silence.
+          // `liveTools.length === 0` keeps the v4.4 B4 bounded tool-settle ceiling (below)
+          // in charge whenever a tool IS live: that path fires through this gate while busy,
+          // then aborts the session (LC-2). The trace line fires on the first vetoed poll of
+          // each flat stretch and whenever a non-zero count is reset, and "Polling loop
+          // exited" carries the last SDK status, so a leg that is held and then dies by
+          // --timeout leaves a record of what the engine said.
+          // Named mutants, ALL RE-MEASURED 2026-09-11 for the council #246 fix set — every
+          // count below is what was observed, not what was expected. "BUSYIGNORED" (the veto
+          // never fires: replace the SDK-status test with `false`) reddens FIVE cases in
+          // headless-idle-completion — the three D0-shape cases (busy, retry, settled tool
+          // part) plus the wedge-until-timeout and status-flip-flop cases this fix set added
+          // — and nothing else in the four suites (5 failed / 149). "VETOOVERCEILING" (drop
+          // the liveTools guard) reddens the 12 B4 ceiling/abort tests in premature-completion,
+          // every `stuck()` call site, and NOT the ALREADY-terminal case (12 failed / 42).
+          // "RETRYHARVEST" (drop the retry arm) reddens exactly the retry case (1 of 13) — the
+          // retry-beyond-deadline case SURVIVES it, because that exit fires in the status-read
+          // block above, before this gate ever runs. "FLAPSILENT" (drop `|| stablePolls > 0`
+          // from the latch below) reddens exactly the flip-flop case (1 of 13). Three further
+          // mutants are documented at their own sites and were measured in the same pass:
+          // "FALLBACKSILENT" (2 of 13, the stable-idle exit below), "NEXTIGNORED" (1 of 13, the
+          // status-read block above) and "BACKOFFNOTFORCED" (1 of 13, failedWithNoUsableOutput
+          // at the finalization). "FINISHEDVETO" (drop
+          // `!assistantFinished`) is pinned by premature-completion "message FINALIZES" and
+          // "ALREADY terminal" and by headless.test.js's BL-7 case: a finalized message with
+          // a session-level `busy` must still end on the stable-finished path. A tool part
+          // with no `state` is
+          // not live here (pendingTools > 0, liveTools === 0), so that mock-only shape is now
+          // bounded by B53's stall detector rather than the 30-poll heuristic; the SDK always
+          // carries `state`.
+          if (currentAssistantMsgId !== null && mirror.output.length > 0
+              && !assistantFinished && (lastSdkStatus === 'busy' || lastSdkStatus === 'retry') && liveTools.length === 0) {
+            if (!vetoLoggedThisStretch || stablePolls > 0) {
+              logger.debug('Idle heuristic reset: SDK busy, no live tools', { taskId, stablePolls, sdkStatus: lastSdkStatus });
+              vetoLoggedThisStretch = true;
+            }
+            stablePolls = 0;
+          } else if (currentAssistantMsgId !== null && mirror.output.length > 0) {
             stablePolls++;
             const threshold = assistantFinished ? stableFinishedPolls : stableIdlePolls;
             // v4.4 B4 part 1 — THE MEASURED DEFECT SITE. This is the gate that
@@ -1288,6 +1380,20 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             // Gating it would add pure hang risk for no truth gained.
             if (stablePolls >= threshold
                 && !(!assistantFinished && deferForUnsettledTools('stable-idle'))) {
+              if (!assistantFinished && liveTools.length === 0) {
+                // Council #246 C2/D2: the fallback ended an UNFINALIZED message with no tool
+                // live — the D0 shape the veto exists for — reachable only because
+                // session.status did not say busy/retry (the read threw, or returned a type
+                // this gate does not know). Loud at warn level, so a stuttering status
+                // endpoint cannot re-open the mid-answer harvest silently. A live tool is
+                // excluded because that exit is the B4 ceiling, which is loud on its own.
+                // Named mutant "FALLBACKSILENT" (drop this warning, keep the `if`) reddens
+                // exactly the two fallback-warning cases in headless-idle-completion
+                // (measured 2 of 13).
+                logger.warn('Idle heuristic ended an unfinalized message on the fallback path', {
+                  taskId, stablePolls, sdkStatus: lastSdkStatus, outputLength: mirror.output.length,
+                });
+              }
               logger.debug('Session appears complete (idle)', { stablePolls, assistantFinished });
               completed = true;
               break;
@@ -1299,6 +1405,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           }
         } else {
           stablePolls = 0;
+          vetoLoggedThisStretch = false;
         }
         lastAssistantMsgId = currentAssistantMsgId;
 
@@ -1328,6 +1435,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       aborted,
       pollCount,
       stablePolls,
+      sdkStatus: lastSdkStatus,
       outputLength: mirror.output.length,
       elapsed: Date.now() - startTime,
       hasAssistantMsg: lastAssistantMsgId !== null,
@@ -1343,7 +1451,13 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // signal per leg: statusFromResult() (src/utils/result-schema.js) checks
     // timedOut BEFORE error, so a leg carrying both would misreport as an
     // ordinary 'timeout' instead of the distinctly-named backstop reason.
-    if (!completed && !aborted && !backstopFired && (Date.now() - startTime) >= timeoutMs) {
+    // Council #246 re-review: `!retryBeyondDeadline` for the same reason as
+    // `!backstopFired`. The status read that sets it may legally return
+    // at deadline−ε (its budget runs to the deadline), and without
+    // this guard a same-pass timeout would double-classify the named
+    // RETRY_BEYOND_DEADLINE error as `timeout` in run.json and abort the
+    // session twice; its own block below aborts exactly once.
+    if (!completed && !aborted && !backstopFired && !retryBeyondDeadline && (Date.now() - startTime) >= timeoutMs) {
       timedOut = true;
       logger.warn('Task timed out', { taskId, elapsed: Date.now() - startTime });
 
@@ -1371,6 +1485,18 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       }
     }
 
+    // Council #246: a retry scheduled past the deadline ended the leg early. Abort the
+    // session exactly like the backstop path — the engine would otherwise keep retrying.
+    if (retryBeyondDeadline && !completed && !aborted) {
+      try {
+        const { abortSession } = require('./opencode-client');
+        await abortSession(client, sessionId, ...dirArgs);
+        logger.info('Session aborted after retry-beyond-deadline exit', { taskId, sessionId });
+      } catch (abortErr) {
+        logger.warn('Failed to abort session after retry-beyond-deadline exit', { error: abortErr.message });
+      }
+    }
+
     watchdog.cancel();
     if (uninstallSignals) { uninstallSignals(); }
 
@@ -1661,7 +1787,11 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // #218 PR 3: an OUTPUT_LENGTH death can have a non-empty mirror.output -- a
     // tool loop's earlier message text, or reasoning promoted before the answer
     // was known -- and must still fail.
-    const failedWithNoUsableOutput = !!(sessionError && (!mirror.output || pollFailureBail || toolStalled || outputLengthDeath));
+    // Council #246 (2026-09-11): `|| retryBeyondDeadline` names the retry-past-deadline death
+    // through the same channel — without it the leg left as Incomplete with its narration
+    // promoted and the reason lost. Named mutant "BACKOFFNOTFORCED" (drop it) reddens exactly
+    // the beyond-deadline case in headless-idle-completion (measured 1 of 13).
+    const failedWithNoUsableOutput = !!(sessionError && (!mirror.output || pollFailureBail || toolStalled || outputLengthDeath || retryBeyondDeadline));
     const { resolveTerminalState } = require('./sidecar/session-finalize');
     const terminalStage = resolveTerminalState({
       completed,

package/src/mcp-council-pack-map.js

@@ -0,0 +1,24 @@
+/**
+ * @module mcp-council-pack-map
+ * COUNCIL_PACK_PARAM_MAP, split out of mcp-council-run.js for the 300-line size gate (P2-R16).
+ */
+
+'use strict';
+
+/**
+ * v4.5 Task 15 (B7/F5): maps amicus_council_run's MCP input keys to the CLI
+ * arg-key names applyPackToArgs's knob tables use (pack-resolve.js), so
+ * applyPackToMcpInput can reuse those tables unchanged. `template` has no
+ * Zod-declared counterpart on this tool (MCP has no template param of its
+ * own — template/apply.js's own docblock: "MCP has no template params of its
+ * own") — a pack's briefing.template is the ONLY way a template reaches this
+ * handler, carried through as a plain (non-schema) `input.template` property
+ * consumed by the render step in mcp-council-run.js.
+ */
+const COUNCIL_PACK_PARAM_MAP = {
+  models: 'models', council: 'council', chair: 'chair', critic: 'critic', lenses: 'lenses',
+  debate: 'debate', timeoutMinutes: 'timeout', maxCost: 'max-cost', gateway: 'gateway',
+  template: 'template',
+};
+
+module.exports = { COUNCIL_PACK_PARAM_MAP };