amicus 4.9.6 → 4.9.8

package/src/sidecar/electron-layout.js

@@ -18,8 +18,11 @@
  * caller already hashed and writes `dist/` by extract-into-incoming + promote
  * (see `promoteDist`).
  *
- * TRUE LEAF: `path` only, with `fs` and the extractor injected by the caller —
- * so electron-provision.js requires it too without any risk of a cycle.
+ * NEAR-LEAF: `path` and `crypto`, plus the true leaf `./electron-exe-rel` (the
+ * one `path.txt` rule, shared with `resolveElectronBinary` since v4.9.7 — A1),
+ * with `fs` and the extractor injected by the caller — so electron-provision.js
+ * requires it too without any risk of a cycle. `platformExe` is re-exported
+ * from here because it was defined here through v4.9.6.
  *
  * @module sidecar/electron-layout
  */
@@ -28,24 +31,7 @@
 
 const crypto = require('crypto');
 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';
-  }
-}
-
-/** 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));
-}
+const { platformExe, writePathTxt, distHeldExe } = require('./electron-exe-rel');
 
 /**
  * The two litter prefixes this module creates, and how long one may survive.
@@ -154,19 +140,26 @@ function sweepPromoteLitter({
  * and the caller then downloaded 138 MB and repeated the same promote.
  *
  * So the in-place removal now happens ONLY when there is nothing to lose: a
- * `dist/` that holds no `platformExe` is not an install, and destroying it costs
- * the user nothing they had. When the old tree DOES hold an executable, the
- * promote REFUSES and that tree is untouched — the repair fails, which is
- * strictly better than a working GUI becoming no GUI.
+ * `dist/` that holds NEITHER the exe `path.txt` names NOR `platformExe` is not
+ * an install, and destroying it costs the user nothing they had. When the old
+ * tree DOES hold an executable, the promote REFUSES and that tree is untouched —
+ * the repair fails, which is strictly better than a working GUI becoming no GUI.
  *
  * THE GUARANTEE, stated so it is checkable:
- *   **A promote never removes a `dist/` that held an executable unless the new
- *   tree is already in its place.**
+ *   **A promote never removes a `dist/` that HELD an executable — under the name
+ *   `path.txt` gives it, or `platformExe` when `path.txt` is absent, unreadable
+ *   or blank — unless the new tree is already in its place.**
+ * "HELD" means a FILE INSIDE `dist/`; `electron-exe-rel.js :: distHeldExe` owns
+ * that rule and carries what each of its bounds was measured to cost (A1).
  * The one exit that can still leave a user without a usable `dist/` is both
  * renames failing after step 1 SUCCEEDED. The old tree is then whole and
  * undeleted at `.amicus-retired-<hex>`, and the thrown message names it so the
  * user can rename it back.
  *
+ * WHICH VALUE THE GUARD READS (A1): `raw`, captured BEFORE step 0 — not
+ * `replaced`, and never a re-read. `electron-exe-rel.js` carries why, the
+ * `ELECTRON_OVERRIDE_DIST_PATH` ruling, and the measurements behind both.
+ *
  * `path.txt` IS WRITTEN FIRST (B2). Writing it LAST made "dist but no path.txt"
  * unobservable only while that write SUCCEEDED, and it ran after the old tree was
  * retired AND DELETED, so one ENOSPC/EPERM/AV-locked 12-byte write left a `dist/`
@@ -189,8 +182,10 @@ function sweepPromoteLitter({
 function promoteDist({ electronDir, incomingDist, platform, fs }) {
   const distDir = path.join(electronDir, 'dist');
   const pathFile = path.join(electronDir, 'path.txt');
-  let replaced = null;                    // step 0's overwritten DIFFERENT value
-  try { replaced = fs.readFileSync(pathFile, 'utf8'); } catch { /* absent or unreadable */ }
+  let raw = null;                         // path.txt BEFORE step 0 overwrites it
+  let unreadable = false;                 // a read that failed for a reason other than ENOENT
+  try { raw = fs.readFileSync(pathFile, 'utf8'); } catch (e) { unreadable = !e || e.code !== 'ENOENT'; }
+  let replaced = raw;                     // step 0's overwritten DIFFERENT value
   try {
     if (replaced === platformExe(platform)) { replaced = null; } else {
       try { writePathTxt({ electronDir, platform, fs }); } catch (e) {
@@ -205,10 +200,15 @@ function promoteDist({ electronDir, incomingDist, platform, fs }) {
         retiredExists = true;
       } catch (e) {
         // The old tree cannot be moved. Removing it in place is irreversible, so
-        // it is allowed only when the tree is not an install anyway.
-        if (fs.existsSync(path.join(distDir, platformExe(platform)))) {
+        // it is allowed only when the tree is an install under NEITHER name (A1).
+        if (unreadable) {
+          throw new Error(`${(e && e.message) || e} — path.txt could not be read, so which exe `
+            + 'dist/ holds is unknown and it was left exactly as it was');
+        }
+        const held = distHeldExe({ distDir, raw, platform, fs });
+        if (held) {
           throw new Error(`${(e && e.message) || e} — the existing dist/ holds a usable `
-            + `${platformExe(platform)} and was left exactly as it was`);
+            + `${held} and was left exactly as it was`);
         }
         fs.rmSync(distDir, { recursive: true, force: true });
       }

package/src/sidecar/electron-native-plan.js

@@ -80,6 +80,17 @@ function cleanDir(fs, dir) {
 /**
  * Walk the platform's native plan until one strategy leaves files in `dir`.
  *
+ * `cwd` IS THE INCOMING TREE, and it is a containment measure with an honest
+ * label: MEASURED NEUTRAL, not measured needed. Across 18 paired runs no shipped
+ * strategy wrote anything cwd-relative, so this changes no observed behaviour.
+ * It costs one line and adds no decision surface, and it converts a hypothetical
+ * cwd-relative write from "the user's own repo, under npx, forever" into "the
+ * incoming tree, which `extractBytesToDist`'s `finally` deletes unconditionally
+ * and `sweepPromoteLitter` takes if a kill skipped that". `unzip.js ::
+ * robustExtract`'s native loop deliberately does NOT get the same treatment: its
+ * `dir` is not inside a tree amicus deletes unconditionally, so binding a cwd
+ * there would point a child's working directory at the user's install.
+ *
  * The verdicts are unzip.js's, because they were right there: a spawn error or
  * an external signal-kill (`status: null` — SIGKILL, an OOM) is a FAILURE even
  * if files landed, a non-zero exit is a failure, and a clean exit that produced
@@ -87,12 +98,14 @@ function cleanDir(fs, dir) {
  * strategy starts from an empty directory.
  * @returns {string|null} the strategy name that worked, or null
  */
-function runNativePlan({ zip, dir, platform, fs, spawn, maxMs, log }) {
+function runNativePlan({ zip, dir, cwd, platform, fs, spawn, maxMs, log }) {
   const failures = [];
   for (const strat of nativeUnzipPlan(zip, dir, platform)) {
     let res;
     try {
-      res = spawn(strat.cmd, strat.args, { stdio: 'ignore', windowsHide: true, timeout: maxMs });
+      res = spawn(strat.cmd, strat.args, {
+        stdio: 'ignore', windowsHide: true, timeout: maxMs, cwd,
+      });
     } catch (e) {
       failures.push(`${strat.name}: spawn ${(e && e.code) || (e && e.message) || 'threw'}`);
       continue;
@@ -118,6 +131,11 @@ function runNativePlan({ zip, dir, platform, fs, spawn, maxMs, log }) {
  * will find it — so a rescue lands in `dist/` by the SAME single rename, with the
  * same litter sweep, and this module never touches the promote at all.
  *
+ * `namesComplete`/`namesChecked` are REQUIRED and deliberately have no defaults:
+ * they drive a disclosure, and a caller that forgot to thread them must not get
+ * the reassuring branch by omission. `announceNativeRescue` treats `undefined` as
+ * "not complete" for the same reason.
+ *
  * `flag: 'wx'` is a real control and a small one: `O_EXCL` refuses to write
  * through a name that already exists, INCLUDING a symlink someone pre-planted at
  * it. It does nothing about a substitution AFTER the write — that window is the
@@ -126,14 +144,14 @@ function runNativePlan({ zip, dir, platform, fs, spawn, maxMs, log }) {
  * `extractBytesToDist` removes the whole incoming tree regardless.
  * @returns {string|null} the strategy name that recovered the archive, or null
  */
-function nativeRescue({ bytes, dir, reason, platform, fs, spawn, maxMs, log }) {
+function nativeRescue({ bytes, dir, reason, namesComplete, namesChecked, platform, fs, spawn, maxMs, log }) {
   const incoming = path.dirname(dir);
   if (!path.basename(incoming).startsWith(INCOMING_PREFIX)) {
     log(`[amicus] the native-extractor rescue was NOT attempted: ${collapseExcerpt(dir, PATH_EXCERPT_CHARS)} is not inside an amicus incoming directory.`);
     return null;
   }
   const zip = path.join(incoming, RESCUE_ZIP);
-  announceNativeRescue({ zip, reason, log });
+  announceNativeRescue({ zip, reason, namesComplete, namesChecked, log });
   try {
     fs.writeFileSync(zip, bytes, { flag: 'wx', mode: 0o600 });
   } catch (e) {
@@ -144,7 +162,7 @@ function nativeRescue({ bytes, dir, reason, platform, fs, spawn, maxMs, log }) {
     // The failed extractor's partial tree is evidence of nothing and would be
     // promoted as if it were a rescue. It goes before the child runs.
     cleanDir(fs, dir);
-    const strategy = runNativePlan({ zip, dir, platform, fs, spawn, maxMs, log });
+    const strategy = runNativePlan({ zip, dir, cwd: incoming, platform, fs, spawn, maxMs, log });
     if (strategy) {
       log(`[amicus] recovered via the native extractor (${strategy}). These bytes were NOT re-hashed; the result is marked unverified.`);
     }

package/src/sidecar/electron-native-rescue.js

@@ -118,6 +118,7 @@ const { nativeRescue, RESCUE_ZIP, INCOMING_PREFIX } = require('./electron-native
 const { offerNativeRescue } = require('./electron-rescue-notice');
 // The read-only name walk the boundary consults before it trusts a verdict.
 const { scanEntryNames } = require('./zip-name-scan');
+const { scanLocalNames } = require('./zip-local-name-scan');
 const { collapseExcerpt } = require('../utils/text-sanitize');
 
 /** The ONE extractor verdict a rescue may act on. See the docblock's boundary. */
@@ -144,27 +145,46 @@ function isRescuableFailure(err) {
  * unadvertised, left in place, exactly as if the archive had had nothing wrong
  * with it but that entry.
  *
- * THE RESIDUAL, STATED RATHER THAN ENGINEERED AWAY. The scan reads the central
- * directory; an archive whose central directory is unreadable — a truncated zip,
- * the commonest thing this rescue exists for — declares no names it can see, and
- * that archive still reaches the native extractor. Nothing here covers a SYMLINK
- * whose target escapes either: that is a payload, not a name. In both cases the
- * only remaining check is the extractor's own, which `tar` and `Expand-Archive`
- * were MEASURED to have (`ditto` and Info-ZIP `unzip` are unmeasured), and
- * `cleanDir` sweeps only inside `dir` — anything a native tool wrote outside it
- * would survive a failed strategy. `docs/configuration.md` says the same thing to
+ * BOTH TABLES, BECAUSE THE STRATEGIES DO NOT AGREE ON WHICH ONE THEY READ (B3).
+ * Through v4.9.6 this asked the CENTRAL directory only, so an archive that blinds
+ * yauzl there — a truncation, or any of four ONE-FIELD forgeries of a COMPLETE
+ * end-of-central-directory record — declared no names amicus could see and went
+ * to the native extractor anyway. MEASURED: seven such archives carrying
+ * `../../../PWNED-BY-NATIVE.txt` reached a real spawn, and on two the rescue ran
+ * to COMPLETION and promoted. Only the Windows tools' own `..` guards stopped the
+ * escape — the exact reliance this module says amicus will not make.
+ * And the tables can DISAGREE: on an archive declaring one name locally and
+ * another centrally, `tar.exe` wrote the LOCAL name while `Expand-Archive` wrote
+ * the CENTRAL one. So a refusal in EITHER table refuses the archive.
+ *
+ * THE RESIDUALS THAT REMAIN. Neither walk sees a SYMLINK whose target escapes:
+ * that is a payload, not a name. And an archive that defeats BOTH walks still
+ * reaches the extractor — rarer than before, but not impossible — so the notice
+ * printed before the spawn now says WHICH names were checked, rather than letting
+ * the user assume they all were. `docs/configuration.md` says the same thing to
  * the user who has to decide whether to set the flag.
+ *
+ * WHEN A NAME CHECK CANNOT SEE IT, the only check left is the extractor's own —
+ * and that claim is now RE-MEASURED on every CI run rather than asserted once
+ * (`tests/sidecar/native-extractor-containment.test.js`, 12 escape shapes per
+ * strategy). `tar.exe`, `Expand-Archive` and Info-ZIP `unzip` all contain their
+ * own escapes; GNU `tar` cannot read a zip at all; `ditto` is the one strategy
+ * still unmeasured, and that suite measures it the first time it runs on a Mac.
+ * What a failed strategy can still leave behind is ONLY a write to an ABSOLUTE
+ * path outside the incoming tree: everything else the rescue writes lives under
+ * that tree, which `extractBytesToDist`'s `finally` deletes unconditionally (B2).
+ * @param {{central:object, local:object}} seen the two walks' results
  * @returns {Error|null} a terminal UNZIP_UNSAFE_ARCHIVE, or null
  */
-async function hostileName(bytes, log) {
-  const seen = await scanEntryNames(bytes);
-  if (!seen.refusal) { return null; }
+function hostileName(seen, log) {
+  const refusal = seen.central.refusal || seen.local.refusal;
+  if (!refusal) { return null; }
   log('[amicus] REFUSING to rescue this archive: amicus could not read it, and while asking what');
   log('[amicus] it contains it found an entry that tries to write OUTSIDE the destination:');
-  log(`[amicus]   ${collapseExcerpt(seen.refusal)}`);
+  log(`[amicus]   ${collapseExcerpt(refusal)}`);
   log('[amicus] A native extractor may have no such check, so it is not offered this archive.');
   return Object.assign(
-    new Error(`refusing to extract this archive: ${collapseExcerpt(seen.refusal)}`),
+    new Error(`refusing to extract this archive: ${collapseExcerpt(refusal)}`),
     { code: 'UNZIP_UNSAFE_ARCHIVE' },
   );
 }
@@ -200,7 +220,8 @@ function withNativeRescue({
       // ...and the one class that IS rescuable is asked what names it declares
       // first, because the exclusion above keys on the refusal yauzl FORMED and
       // an earlier bad entry stops it forming one. See `hostileName`.
-      const hostile = await hostileName(bytes, log);
+      const seen = { central: await scanEntryNames(bytes), local: scanLocalNames(bytes) };
+      const hostile = hostileName(seen, log);
       if (hostile) { throw hostile; }
       if (!policy.allowUnverified) {
         // `offered` IS THE OFFER'S RECEIPT, and the cache route is required to
@@ -214,7 +235,25 @@ function withNativeRescue({
         throw err;
       }
       const strategy = nativeRescue({
-        bytes, dir: o.dir, reason: (err && err.message) || '', platform, fs, spawn, maxMs, log,
+        bytes,
+        dir: o.dir,
+        reason: (err && err.message) || '',
+        // WHAT THE NOTICE MAY CLAIM. Three states, not two: a real artifact
+        // truncated by a few KB has BOTH walks incomplete while the local walk
+        // read and cleared every name it found, so `central.read || local.complete`
+        // would print "nothing checked its entries" over 73 checked entries.
+        // BOTH, NOT EITHER. The two tables carry DIFFERENT names and the two
+        // strategies read different ones, so a disjunction cannot mean "every
+        // name was checked". MEASURED: a local walk stopped at entry 1 with a
+        // readable, benign central directory reported TRUE and printed nothing,
+        // while `tar.exe` reached a `../../../` entry only the local table had.
+        namesComplete: seen.central.read && seen.local.complete,
+        namesChecked: seen.local.names,
+        platform,
+        fs,
+        spawn,
+        maxMs,
+        log,
       });
       // A rescue that failed leaves the ORIGINAL classified error in flight, so
       // a genuinely bad archive is still evicted exactly as it was before.

package/src/sidecar/electron-rescue-notice.js

@@ -62,9 +62,26 @@ function offerNativeRescue({ reason, log = () => {} }) {
  * instead of reassuring anyone about it — the rescue is not safe, and the words a
  * user reads while it happens have to say so.
  */
-function announceNativeRescue({ zip, reason, log = () => {} }) {
+function announceNativeRescue({
+  zip, reason, namesComplete, namesChecked = 0, log = () => {},
+}) {
   log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — running the NATIVE-EXTRACTOR RESCUE.');
   log(`[amicus]   amicus could not read the archive itself: ${collapseExcerpt(reason)}`);
+  // THREE STATES, NOT TWO, and the middle one is the common one: a real artifact
+  // truncated by a few KB leaves both walks incomplete while the local walk still
+  // read and cleared every name it reached. Saying "nothing checked its entries"
+  // there would be a FALSE disclosure on the shape this rescue exists for.
+  // `namesComplete` is undefined-means-no on purpose (see `nativeRescue`).
+  if (!namesComplete && namesChecked > 0) {
+    log(`[amicus]   IT CHECKED ${namesChecked} ENTRY NAMES AND COULD NOT CONFIRM IT SAW THEM ALL:`);
+    log('[amicus]   the archive stopped amicus part-way through its own tables, so an entry that');
+    log('[amicus]   writes OUTSIDE dist/ could sit past the point it reached.');
+  } else if (!namesComplete) {
+    log('[amicus]   AND IT COULD NOT READ THE ENTRY NAMES EITHER: neither this archive\'s central');
+    log('[amicus]   directory nor its local file headers could be walked, so NOTHING checked its');
+    log('[amicus]   entries for paths that write OUTSIDE dist/. The extractor below is the only');
+    log('[amicus]   check left.');
+  }
   log('[amicus] THE WINDOW THIS OPENS, stated plainly. amicus has written the bytes it hashed to');
   log(`[amicus]   ${collapseExcerpt(zip, PATH_EXCERPT_CHARS)}`);
   log('[amicus] and is about to hand that PATH to a native extractor it does not control. Between');

package/src/sidecar/fanout.js

@@ -46,6 +46,7 @@ const { deriveLegIds } = require('./leg-ids');
  *     to run this wave's legs on. Both or neither. When supplied this wave never
  *     starts a server and never closes one — see the seam comment in step 4.
  *     NOT `client`, which is the client TYPE string on this function.)
+ *   serverAgents? (spec 2026-09-11 §4: agents to register if this wave starts its own server)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -218,7 +219,12 @@ async function runFanout(options) {
     logger.debug('Using external server (shared server mode)', { waveId, url: server.url });
   } else {
     try {
-      ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
+      ({ client, server } = await startOpenCodeServer(mcpServers, {
+        models: validated.serverModels || okLegs.map(l => l.model),
+        // Spec 2026-09-11 §4: a wave that starts its own server still needs the
+        // council agents registered on it. Spread-guarded: byte-identical otherwise.
+        ...(options.serverAgents ? { agents: options.serverAgents } : {}),
+      }));
     } catch (err) {
       writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
       return errorWave(waveId, `Failed to start server: ${err.message}`, waveDir);

package/src/sidecar/heartbeat.js

@@ -0,0 +1,46 @@
+// src/sidecar/heartbeat.js
+'use strict';
+// HEARTBEAT_INTERVAL + createHeartbeat — moved verbatim from session-utils.js
+// (size-gate split, spec 2026-09-11 §4 PR 2: that file was already at the
+// 300-line ceiling before this task's additions). Zero behavior change; both
+// re-exported from session-utils.js's existing module.exports, so no caller
+// (start.js, resume.js, continue.js, fanout.js, index.js, and their tests)
+// needs to change — see tests/sidecar/session-utils.test.js and
+// tests/sidecar/start.test.js, which exercise these through that re-export.
+
+/** Standard heartbeat interval in milliseconds */
+const HEARTBEAT_INTERVAL = 15000;
+
+/**
+ * Create a heartbeat that writes status to stderr periodically.
+ * When sessionDir is provided, includes message count and latest activity.
+ *
+ * @param {number} [interval=HEARTBEAT_INTERVAL] - Interval in milliseconds
+ * @param {string} [sessionDir] - Session directory to read progress from
+ * @returns {{ stop: () => void }}
+ */
+function createHeartbeat(interval = HEARTBEAT_INTERVAL, sessionDir) {
+  const startTime = Date.now();
+  const intervalId = setInterval(() => {
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    const mins = Math.floor(elapsed / 60);
+    const secs = elapsed % 60;
+    const ts = mins > 0 ? `${mins}m${secs}s` : `${secs}s`;
+
+    if (sessionDir) {
+      const { readProgress } = require('./progress');
+      const progress = readProgress(sessionDir);
+      process.stderr.write(`[amicus] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
+    } else {
+      process.stderr.write(`[amicus] still running... ${ts} elapsed\n`);
+    }
+  }, interval);
+
+  return {
+    stop() {
+      clearInterval(intervalId);
+    }
+  };
+}
+
+module.exports = { HEARTBEAT_INTERVAL, createHeartbeat };

package/src/sidecar/session-utils.js

@@ -20,8 +20,10 @@ const {
   resolveExistingSessionDir
 } = require('../session-manager');
 
-/** Standard heartbeat interval in milliseconds */
-const HEARTBEAT_INTERVAL = 15000;
+// HEARTBEAT_INTERVAL + createHeartbeat live in ./heartbeat (size-gate split:
+// this file was already at the 300-line ceiling — spec 2026-09-11 §4 PR 2).
+// Re-exported below so no caller changes.
+const { HEARTBEAT_INTERVAL, createHeartbeat } = require('./heartbeat');
 
 /** Session path utilities - eliminates magic strings across modules */
 const SessionPaths = {
@@ -122,38 +124,6 @@ function outputSummary(summary) {
   console.log(fenceSidecarOutput(summary));
 }
 
-/**
- * Create a heartbeat that writes status to stderr periodically.
- * When sessionDir is provided, includes message count and latest activity.
- *
- * @param {number} [interval=HEARTBEAT_INTERVAL] - Interval in milliseconds
- * @param {string} [sessionDir] - Session directory to read progress from
- * @returns {{ stop: () => void }}
- */
-function createHeartbeat(interval = HEARTBEAT_INTERVAL, sessionDir) {
-  const startTime = Date.now();
-  const intervalId = setInterval(() => {
-    const elapsed = Math.round((Date.now() - startTime) / 1000);
-    const mins = Math.floor(elapsed / 60);
-    const secs = elapsed % 60;
-    const ts = mins > 0 ? `${mins}m${secs}s` : `${secs}s`;
-
-    if (sessionDir) {
-      const { readProgress } = require('./progress');
-      const progress = readProgress(sessionDir);
-      process.stderr.write(`[amicus] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
-    } else {
-      process.stderr.write(`[amicus] still running... ${ts} elapsed\n`);
-    }
-  }, interval);
-
-  return {
-    stop() {
-      clearInterval(intervalId);
-    }
-  };
-}
-
 /**
  * Execute sidecar in either headless or interactive mode
  * Consolidates the if/else pattern duplicated across start, resume, continue
@@ -228,6 +198,7 @@ async function executeMode(options) {
  * @param {string} [options.client] - Client type (e.g. 'cowork', 'code-local')
  * @param {string} [options.systemPrompt] - System prompt to set on agent config (hidden from UI)
  * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
+ * @param {Object<string, object>} [options.agents] - Extra agents to register (council seat agents)
  * @param {string[]} [options.models] - Resolved executable id(s) actually launched on this
  *   server (#61 Task 4.6/7.3 sole-input invariant) — a multi-model shared server (fanout)
  *   has no single default `config.model`, so this registers ALL of them in provider.models
@@ -257,6 +228,8 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.models) { serverOptions.models = options.models; }
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
+  // Spec 2026-09-11 §4: the council's two agents ride into buildServerOptions.
+  if (options.agents) { serverOptions.agents = options.agents; }
   // Explicit per-call override only. Unset is the normal case and is correct:
   // buildServerOptions resolves AMICUS_SERVER_START_TIMEOUT_MS / the platform
   // default downstream, so forwarding `undefined` here would change nothing.

package/src/sidecar/zip-from-buffer.js

@@ -40,11 +40,22 @@
  * extraction root is REFUSED here and is not by extract-zip, and it is resolved
  * against the REALPATH of the directory the link lands in because the lexical
  * `path.dirname` was measured to be defeated outright by a chain of
- * directory-symlink entries earlier in the same archive. That is a behaviour
- * change on a shape amicus cannot test on this machine (the darwin `.app` bundle
- * is the only electron artifact with real symlinks), so it is refused in the
- * same `Out of bound path` wording, exercised against synthetic archives, and
- * named in the report as unverified on macOS.
+ * directory-symlink entries earlier in the same archive. It is refused in the
+ * same `Out of bound path` wording and exercised against synthetic archives
+ * here; the darwin `.app` bundle is the only electron artifact with real
+ * symlinks, and since v4.9.7 `.github/workflows/darwin-bundle.yml` runs this
+ * path over the REAL artifact on a real Mac. The v4.9.6 worry that the check
+ * might REJECT a working layout is refuted by measurement: the real
+ * `electron-v43.1.1-darwin-arm64.zip` declares 585 records and 14 symlinks,
+ * every target relative, none carrying a `..` component, none absolute, and 0
+ * of the 585 entry names traversing a symlinked component. The linux artifacts
+ * hold ZERO symlink entries, so `writeSymlink` is unreachable there at all.
+ *
+ * `root = fs.realpathSync(dir)` below is load-bearing for that answer and no
+ * Windows probe would ever show it: on macOS the extraction root usually sits
+ * under `/var`, which is itself a symlink to `/private/var`, so comparing a
+ * resolved target against an UNRESOLVED root would read every link in a real
+ * `.app` as an escape.
  *
  * ── ERROR CODES ARE A CAUSAL CLAIM ───────────────────────────────────────
  * `UNZIP_BUFFER_FAILED` = the ARCHIVE is bad. `UNZIP_DEST_FAILED` = the