amicus 4.9.6 → 4.9.8

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

package/src/mcp-council-run.js

@@ -27,21 +27,11 @@ function textResult(text, isError) {
   return result;
 }
 
-/**
- * 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 below.
- */
-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',
-};
+// COUNCIL_PACK_PARAM_MAP lives in its own leaf (P2-R16, the 300-line size
+// gate: this file was at 298 with no room for Task 6's tools/agent block) —
+// re-exported below unchanged so tests/pack/mcp-pack-params.test.js's
+// existing `require('../../src/mcp-council-run')` import keeps working.
+const { COUNCIL_PACK_PARAM_MAP } = require('./mcp-council-pack-map');
 
 /**
  * amicus_council_run: validate → prep run dir → spawn CLI child → return
@@ -131,6 +121,14 @@ async function handleCouncilRunTool(input, project, helpers) {
       (typeof input.maxCost !== 'number' || !Number.isFinite(input.maxCost) || input.maxCost <= 0)) {
     return textResult('maxCost must be a positive number.', true);
   }
+  // Spec 2026-09-11 §4 (P2-R28 supersedes P2-R25): --tools/--agent are refused together, before either is consulted, on every door. Tools that never touch the tree (webfetch, websearch, todowrite) ride through; local tools are refused naming the CLI.
+  const toolsIn = (input.tools === undefined || input.tools === null) ? undefined : (Array.isArray(input.tools) ? input.tools : [String(input.tools)]);
+  const mcpWording = (m) => m.replace(/^--tools:/, 'tools:').replace(/--agent Build/g, 'agent: "Build"').replace(/(?<!run )--tools/g, 'tools').replace(/--agent/g, 'agent'); // C6 (P2-R35): rewrites flag wording EXCEPT inside an actual `council run --tools ...` CLI suggestion (resolveRemoteOnlyTools's local-tool message), which stays literal.
+  const conflict = require('./council/seat-tools').agentToolsConflict(input.agent, toolsIn);
+  if (conflict) { return textResult(mcpWording(conflict), true); }
+  const mt = (toolsIn !== undefined)
+    ? require('./council/seat-tools').resolveRemoteOnlyTools(toolsIn) : { ok: true, ids: [] };
+  if (!mt.ok) { return textResult(mcpWording(mt.message), true); }
 
   const { generateTaskId } = require('./sidecar/start');
   const runId = generateTaskId();
@@ -207,6 +205,10 @@ async function handleCouncilRunTool(input, project, helpers) {
   // v4.9 W5.2: emit-when-'task' — 'review' (the zod-declared default spelled
   // out) never reaches the child's argv; review-run argv stays byte-identical.
   if (input.intent === 'task') { args.push('--intent', 'task'); }
+  // Spec 2026-09-11 §4: remote tools + the Plan|Build override ride to the child as argv (the CLI door and runCouncil validate them again).
+  // Named mutant TOOLSEMITALWAYS: `mt.ids` (an array) is always truthy even when empty — swapping `.length` for a bare `mt.ids` check pushes `--tools ''` on every run; reddens 'absent tools/agent leave the argv byte-identical' in tests/mcp-council-run.test.js.
+  if (mt.ids.length) { args.push('--tools', mt.ids.join(',')); }
+  if (input.agent) { args.push('--agent', input.agent); }
 
   let child;
   try { child = helpers.spawnFn(args, runDir); } catch (err) {

package/src/mcp-server.js

@@ -229,8 +229,8 @@ const HEADLESS_STATUS_REMINDER = '<system-reminder>Preferred: call amicus_wait w
  * v4.5 Task 15 (B7/F5): map amicus_fanout / amicus_start'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 — see
- * src/mcp-council-run.js's COUNCIL_PACK_PARAM_MAP for the sibling map and its
- * fuller docblock. `includeContext` is the one inverted-polarity knob: the
+ * src/mcp-council-pack-map.js's COUNCIL_PACK_PARAM_MAP for the sibling map and
+ * its fuller docblock. `includeContext` is the one inverted-polarity knob: the
  * pack/CLI side is `no-context` (true = drop context), the MCP side is
  * `includeContext` (true = keep context, default true).
  */

package/src/mcp-tools.js

@@ -73,8 +73,8 @@ function getTools() {
       agent: z.enum(['Chat', 'Plan', 'Build']).optional()
         .describe(
           'Agent mode. Chat (interactive default; headless runs auto-convert ' +
-          'to Build): reads auto, writes ask permission. Plan: read-only ' +
-          'analysis. Build: full auto (all operations approved).'
+          'to Build): reads auto, writes ask permission. Plan: analysis without ' +
+          'edits (reads, searches and shell allowed). Build: full auto (all operations approved).'
         ),
       noUi: z.boolean().optional().describe(
         'Run headless without GUI. Default false (opens Electron window).'
@@ -345,7 +345,7 @@ function getTools() {
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
       ),
       agent: z.enum(['Plan', 'Build']).optional().describe(
-        'Agent mode for every leg. Build (default): full tool access. Plan: read-only analysis. Chat is not supported headless.'
+        'Agent mode for every leg. Build (default): full tool access. Plan: analysis without edits (reads, searches and shell allowed). Chat is not supported headless.'
       ),
       thinking: z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']).optional().describe(
         'Reasoning effort for every leg. Omitted: nothing is sent and each provider\'s own default effort governs. A leg whose model does not declare the level is refused before anything is spent; the other legs run. A leg whose model the engine\'s catalogue does not know in time is sent the level unverified.'
@@ -622,6 +622,17 @@ function getTools() {
         "run.json/verdict.json and kept out of the reliability ledger; 'review' is the " +
         'default and is never stored.'
       ),
+      tools: z.array(z.string().min(1)).max(12).optional().describe(
+        'Tool ids stage-1 seats may use, by the engine\'s own ids (task mode defaults to webfetch, review to none). ' +
+        'Over MCP only tools that never touch the tree (webfetch, websearch, todowrite) can be opted in: the MCP run ' +
+        'directory stays inside the project, and a seat with local tools must not run there — use the CLI with ' +
+        '--out-dir outside the project for read/grep/glob/bash. task, skill, question, invalid, edit, write and ' +
+        'apply_patch are always refused. Cannot be combined with agent.'
+      ),
+      agent: z.enum(['Plan', 'Build']).optional().describe(
+        'Escape hatch: run every leg on the engine\'s own agent instead of the council agents (no tool allowlist). ' +
+        'Cannot be combined with tools.'
+      ),
       ui: z.boolean().optional().describe(
         'Auto-open the Council Workspace window on this run. Default: opens when the client is ' +
         'Claude Code (local), Electron is installed, a display exists, and config workspace.autoOpen is ' +
@@ -742,7 +753,7 @@ Each leg is an ordinary session: read/resume/continue it by taskId.
 | Agent | Reads | Writes | Bash | Use When |
 |-------|-------|--------|------|----------|
 | Chat (interactive default*) | auto | asks | asks | Questions, analysis |
-| Plan | auto | denied | denied | Read-only analysis |
+| Plan | auto | denied | auto | Analysis without edits |
 | Build | auto | auto | auto | Implementation tasks |
 
 * Headless (\`noUi\`) runs auto-convert Chat to Build — Chat would otherwise stall waiting on write/bash approval with no UI to approve it.

package/src/opencode-client.js

@@ -530,6 +530,7 @@ function resolveServerStartTimeoutMs(options = {}, env, platform) {
  * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
  * @param {number|null} [options.outputBudget] - #218 PR 3: the per-leg output budget startServer
  *   already read; omitted means buildProviderModels reads config itself
+ * @param {Object<string, object>} [options.agents] - Extra agent configs to register (council seat agents, spec 2026-09-11 §4)
  * @returns {object} Server options ready for createOpencodeServer
  */
 function buildServerOptions(options = {}) {
@@ -655,6 +656,31 @@ function buildServerOptions(options = {}) {
     chat: chatAgent
   };
 
+  // Council seat agents (spec 2026-09-11 §4, PR 2): a per-run map of extra agents
+  // the caller already computed (council/seat-tools.js :: buildCouncilAgents).
+  // Merged AFTER `chat`, and a `chat` key is skipped outright (fix round 1 nit)
+  // so a caller genuinely can never displace the chat registration — without
+  // the skip, `agents: { chat: {...} }` would replace `config.agent.chat`
+  // with a brand-new object, detaching it from the `chatAgent` object the
+  // systemPrompt branch below still mutates by reference; seat-tools.js never
+  // emits a `chat` key, but the guard holds regardless of the caller. Absent,
+  // or not a plain object (arrays rejected too), this block is a no-op and
+  // every non-council server's config is byte-identical to today.
+  //
+  // council #247 round 6 (P2-R53): a council agent REPLACES any pre-existing
+  // same-name entry outright, rather than merging onto it — measured
+  // 2026-09-13 (probe-r6.js) that the old shallow merge below let a
+  // pre-existing entry's `prompt`/`temperature` survive and render on the
+  // seat. Named mutant AGENTMERGE: restoring the spread
+  // (`{ ...(config.agent[name] || {}), ...agentConfig }`) lets `prompt`
+  // survive again.
+  if (options.agents && typeof options.agents === 'object' && !Array.isArray(options.agents)) {
+    for (const [name, agentConfig] of Object.entries(options.agents)) {
+      if (name === 'chat') { continue; }
+      config.agent[name] = { ...agentConfig };
+    }
+  }
+
   // Set system prompt on the target agent's config (hidden from UI).
   // The promptAsync `system` field is rendered as a visible chat message,
   // but agent.prompt is injected as the system instruction invisibly.

package/src/pack/pack-validate.js

@@ -16,7 +16,9 @@ const KINDS = ['council', 'fanout', 'solo'];
 /** Per-kind allowed `options` keys (spec §5.1; solo UI-suppression key per Task 0's verified flag set).
  * v4.5 HOLD-gate decision 2 (final-review F1): `agent`/`thinking`/`summaryLength`
  * are inert on EVERY council surface — handleCouncilRun never reads a pack-filled
- * one, and the engine hardcodes agent 'Plan'/summaryLength 'verbose' regardless.
+ * one; `--agent` (CLI) / the MCP `agent` param are a council run's only agent
+ * setters (spec 2026-09-11 §4, v4.9.8), and summaryLength stays hardcoded
+ * 'verbose' on every council launch regardless of what a pack sets.
  * Dropped from `council` pre-release rather than shipped as dead weight a pack
  * author would reasonably expect to work; a council pack that still sets one now
  * fails save/run validation (PACK_INVALID) like any other unknown option for the

package/src/prompt-builder.js

@@ -234,7 +234,7 @@ ${context}`;
  * Note: Tool restrictions are now handled by OpenCode's native agent framework.
  * The agent parameter passed to OpenCode API controls permissions:
  *   - Build: Full tool access (default)
- *   - Plan: Read-only access
+ *   - Plan: Edits denied; reads, searches and shell allowed (measured, opencode 1.18.15)
  *   - Explore: Read-only subagent
  *   - General: Full-access subagent
  *
@@ -258,7 +258,7 @@ Tool permissions are managed by the OpenCode agent framework based on your agent
 // buildPlanModeEnvironment) have been removed. OpenCode's native agent framework now handles
 // tool permissions based on the agent type:
 //   - Build: Full tool access (default)
-//   - Plan: Read-only access
+//   - Plan: Edits denied; reads, searches and shell allowed
 //   - Explore: Read-only subagent
 //   - General: Full-access subagent
 // See: https://opencode.ai/docs/agents/

package/src/sidecar/electron-exe-rel.js

@@ -0,0 +1,131 @@
+/**
+ * WHICH exe a package resolves through, and whether a `dist/` HOLDS one.
+ *
+ * ONE RULE, ONE HOME. `resolveElectronBinary` (electron-install.js) decides what
+ * amicus will SPAWN; `promoteDist`'s retirement guard (electron-layout.js)
+ * decides what amicus may DELETE. Until v4.9.7 only the first one read
+ * `path.txt` — the second asked whether `dist/` held THIS HOST'S default exe —
+ * and a package cross-installed through `npm_config_platform` holds a different
+ * basename, so a failed promote destroyed a working tree (A1). Two copies of a
+ * rule are free to drift; this module exists so there is one.
+ *
+ * WHICH VALUE `promoteDist`'S GUARD MAY READ, since getting this wrong is how
+ * the fix would have been as blind as the defect:
+ *   - `raw`, the bytes `path.txt` held BEFORE the promote's step 0 — YES.
+ *   - `replaced` (electron-layout.js) — NO. It is nulled in exactly the branch
+ *     the guard most needs a name for, and it is untrimmed, so feeding it to
+ *     `path.join` fails OPEN on a trailing newline.
+ *   - A RE-READ of `path.txt` at the guard — NO, and this is the sharp one.
+ *     Step 0 has already written `platformExe` there, so a re-reading guard
+ *     reads its own writer's value and learns nothing. MEASURED: at the guard
+ *     the file says `electron.exe` even for a package cross-installed as
+ *     `electron`, and the tree is deleted exactly as before the fix. That is
+ *     failure mode #21, the echoed read-back.
+ *
+ * `ELECTRON_OVERRIDE_DIST_PATH` IS DELIBERATELY NOT PART OF THIS RULE, and
+ * `promoteDist` gains no `env`. The guard governs a DELETE of `distDir` and
+ * nothing else, so the only question is what THAT tree holds; under an override
+ * `resolveElectronBinary` does not look in `dist/` at all. Ignoring it can only
+ * make the guard readier to find an exe — the fail-CLOSED direction.
+ *
+ * TRUE LEAF: `path` only, with `fs` injected by the caller — so both callers can
+ * require it with no risk of a cycle.
+ *
+ * @module sidecar/electron-exe-rel
+ */
+
+'use strict';
+
+const path = require('path');
+
+/** Platform exe basename, matching electron's getPlatformPath(). */
+function platformExe(platform) {
+  switch (platform) {
+    case 'mas':
+    case 'darwin':
+      return path.join('Electron.app', 'Contents', 'MacOS', 'Electron');
+    case 'win32':
+      return 'electron.exe';
+    default:
+      return 'electron';
+  }
+}
+
+/**
+ * The relative exe path a package RESOLVES through, from `path.txt`'s RAW bytes.
+ *
+ * `resolveElectronBinary`'s rule, stated once: TRIM, and fall back to
+ * `platformExe` when the file is absent, unreadable OR blank. `null` is the
+ * caller's "the read threw".
+ *
+ * THE TRIM AND THE BLANK ARM ARE BOTH LOAD-BEARING, and the A1 filing named
+ * neither — it said "absent or unreadable". MEASURED: a guard that skips the
+ * trim deletes a real `dist/electron.exe` under a `path.txt` of
+ * `"electron.exe\n"`, because `existsSync(join(dist, 'electron.exe\n'))` is
+ * false on Windows; and one that returns a blank value names `dist/` ITSELF,
+ * which exists, so it would refuse every promote forever.
+ */
+function heldExeRel(raw, platform) {
+  const rel = typeof raw === 'string' ? raw.trim() : '';
+  return rel || platformExe(platform);
+}
+
+/**
+ * WHICH executable `distDir` holds — under either name it could resolve
+ * through — or `null` for a tree that is not an install under any of them.
+ *
+ * A UNION, NEVER A REPLACEMENT, and the union is why this returns a NAME. The
+ * filing's literal rule ("judge by what `path.txt` names") was MEASURED to open
+ * three new holes it does not mention: a whitespace-only `path.txt`, one with a
+ * trailing newline, and a TRUNCATED one (`electr` — the shape `promoteDist`'s
+ * own best-effort put-back can leave) each turned a real `dist/electron.exe`
+ * into "not an install, delete it". So `platformExe` is not replaced by the
+ * `path.txt` name; it is joined by it, and the set of trees this licenses
+ * deleting can only ever SHRINK.
+ *
+ * ARM 1 IS THE PRE-FIX RULE, BYTE FOR BYTE, and it runs first and
+ * unconditionally. That ordering is the guarantee: no tree the shipped guard
+ * protects today can be deleted by this one.
+ *
+ * ARM 2 CARRIES TWO BOUNDS THE FIRST DOES NOT NEED.
+ *   CONTAINED — a `path.txt` of `..`, `.`, `''` or `../SIBLING` joins to
+ *   something that EXISTS outside `dist/` (all MEASURED true), which would
+ *   refuse every promote forever while claiming `dist/` held an exe it never
+ *   held. The predicate is `zip-entry-write.js :: writeSymlink`'s, verbatim —
+ *   including the `path.sep`, whose absence MEASURABLY fails OPEN: a legal
+ *   `dist/..electron.exe` reads as escaping and the tree is deleted.
+ *   A FILE, NOT A DIRECTORY — every natural truncation of the darwin name
+ *   (`Electron.app`, `Electron.app/Contents`, `Electron.app/Contents/MacOS`) is
+ *   a real DIRECTORY in a real tree, and `existsSync` says true for all three.
+ *   Accepting one would wedge the self-heal permanently on the AV-quarantine
+ *   shape it exists for, printing "dist/ holds a usable Electron.app".
+ *
+ * A throwing `existsSync` (only an injected fs does this) reads as "I could not
+ * establish that this tree is empty", which refuses. Fail closed.
+ *
+ * @param {object} o
+ * @param {string} o.distDir
+ * @param {string|null} o.raw  path.txt's bytes BEFORE any writer touched them
+ * @param {string} o.platform
+ * @param {object} o.fs
+ * @returns {string|null} the exe path, relative to `distDir`, that was found
+ */
+function distHeldExe({ distDir, raw, platform, fs }) {
+  const fallback = platformExe(platform);
+  // ARM 1 — the pre-fix rule, unchanged and first.
+  try { if (fs.existsSync(path.join(distDir, fallback))) { return fallback; } } catch { return fallback; }
+  const held = heldExeRel(raw, platform);
+  if (held === fallback) { return null; }
+  // ARM 2 — the name path.txt gives, contained and required to be a file.
+  const full = path.join(distDir, held);
+  const inside = path.relative(distDir, full);
+  if (inside === '' || inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) { return null; }
+  try { return fs.statSync(full).isFile() ? held : null; } catch { return null; }
+}
+
+/** Write path.txt: the basename `electron/index.js` joins onto `dist/`. */
+function writePathTxt({ electronDir, platform, fs }) {
+  fs.writeFileSync(path.join(electronDir, 'path.txt'), platformExe(platform));
+}
+
+module.exports = { platformExe, writePathTxt, heldExeRel, distHeldExe };

package/src/sidecar/electron-install.js

@@ -16,7 +16,9 @@
  *
  * AT THE SIZE GATE, so pieces live next door: `./electron-custody` reads the
  * artifact into memory once, `./zip-from-buffer` extracts what was read,
- * `./electron-layout` holds `platformExe`/`writePathTxt`/`extractBytesToDist`
+ * `./electron-exe-rel` holds the ONE `path.txt` rule (`platformExe`/`heldExeRel`/
+ * `writePathTxt`/`distHeldExe`), shared with `promoteDist`'s retirement guard since
+ * v4.9.7 (A1); `./electron-layout` holds `promoteDist`/`extractBytesToDist`
  * (`platformExe` re-exported here for `ei.platformExe`), `./electron-refuse`
  * holds the refusal messages, `./electron-repair-cache` the whole cached-artifact
  * route, `./electron-provision` the pinned download. The arrow points one way out
@@ -32,7 +34,7 @@ const { cachedZip } = require('./electron-cache');
 const { isSafeArtifactName } = require('./electron-custody');
 const { avHint, verifyExtractOutcome: verifyQuarantine } = require('./electron-quarantine');
 const { acquireRepairLock } = require('./electron-lock');
-const { platformExe } = require('./electron-layout');
+const { platformExe, heldExeRel } = require('./electron-exe-rel');
 const { controlledProvision } = require('./electron-provision');
 const { repairFromCache } = require('./electron-repair-cache');
 const { isUnsafeArchive, refuseUnsafeArchive } = require('./electron-refuse');
@@ -61,16 +63,9 @@ function defaultElectronDir() {
  * @returns {string|null} resolved exe path, or null if path.txt is unreadable.
  */
 function resolveElectronBinary({ electronDir = defaultElectronDir(), env = process.env, platform = process.platform, fs = fsDefault } = {}) {
-  let exeRel;
-  const pathFile = path.join(electronDir, 'path.txt');
-  try {
-    exeRel = fs.readFileSync(pathFile, 'utf-8').trim();
-  } catch {
-    exeRel = '';
-  }
-  if (!exeRel) {
-    exeRel = platformExe(platform);
-  }
+  let raw = null;
+  try { raw = fs.readFileSync(path.join(electronDir, 'path.txt'), 'utf-8'); } catch { /* absent or unreadable */ }
+  const exeRel = heldExeRel(raw, platform);   // the ONE rule (electron-exe-rel.js)
   const override = env.ELECTRON_OVERRIDE_DIST_PATH;
   if (override) {
     return path.join(override, exeRel);