amicus 1.9.0 → 2.0.0

package/electron/fold.js

@@ -9,6 +9,7 @@ const { logger } = require('../src/utils/logger');
 const { requestSummaryFromModel } = require('./summary');
 const { getSummaryTemplate } = require('../src/prompt-builder');
 const { tokenCss } = require('../src/design/tokens');
+const { buildFoldMarker, generateFoldNonce } = require('../src/utils/fold-marker');
 
 /**
  * Create a fold handler bound to the window state
@@ -19,9 +20,17 @@ const { tokenCss } = require('../src/design/tokens');
  * @param {string} state.sessionId - OpenCode session ID
  * @param {string} state.taskId - Sidecar task ID
  * @param {number} state.port - OpenCode server port
+ * @param {string} [state.nonce] - Per-run fold nonce (15b.3, #BL-7 residual). Set by
+ *   main.js from AMICUS_FOLD_NONCE — the SAME value baked into the system prompt's
+ *   fold instruction, so a completion this handler writes matches what the model was
+ *   actually asked to emit. Falls back to a freshly generated nonce when absent (e.g.
+ *   a caller/test that doesn't thread one through) — this is purely defensive: the
+ *   GUI fold path is exit-code driven, not marker-detected, so an un-advertised
+ *   fallback nonce here cannot be exploited the way headless.js's detector could.
  * @returns {{ triggerFold: Function, hasFolded: Function, isFolding: Function, hasCompleted: Function }}
  */
 function createFoldHandler(state) {
+  const nonce = state.nonce || generateFoldNonce();
   // `folded` is set synchronously at triggerFold ENTRY and covers both
   // "in flight" and "done" — this is `hasFolded()`'s existing external
   // contract (main.js wires it straight into createCloseGuard's `hasFolded`
@@ -52,7 +61,7 @@ function createFoldHandler(state) {
       }
 
       const output = [
-        '[SIDECAR_FOLD]',
+        buildFoldMarker(nonce),
         `Model: ${state.model}`,
         `Session: ${state.sessionId || state.taskId}`,
         `Client: ${state.client}`,

package/electron/ipc-setup.js

@@ -4,7 +4,10 @@
  * Extracted from main.js to keep file sizes under 300 lines.
  * Registers all setup-mode IPC handlers: validate-key, save-key,
  * remove-key, setup-done, save-config, get-config, get-api-keys,
- * fetch-models, get-catalog, and refresh-catalog.
+ * get-catalog, and refresh-catalog.
+ * (sidecar:fetch-models was retired in B33/#12 — Step 3's alias editor now
+ * shares the TTL-cached get-catalog data Step 2 loads instead of a second,
+ * uncached live fetch.)
  */
 
 const { ipcMain } = require('electron');
@@ -160,19 +163,6 @@ function registerSetupHandlers(getMainWindow) {
     }
   });
 
-  ipcMain.handle('sidecar:fetch-models', async () => {
-    try {
-      const { readApiKeyValues } = require('../src/utils/api-key-store');
-      const { fetchAllModels, groupModelsByFamily } = require('../src/utils/model-fetcher');
-      const keys = readApiKeyValues();
-      const models = await fetchAllModels(keys);
-      return groupModelsByFamily(models);
-    } catch (err) {
-      logger.error('fetch-models handler error', { error: err.message });
-      return [];
-    }
-  });
-
   // F5: wizard Step 2 reads the catalog CACHE (self-refreshing when stale).
   ipcMain.handle('sidecar:get-catalog', async () => {
     try {
@@ -206,7 +196,12 @@ function registerSetupHandlers(getMainWindow) {
       const catalog = await getCatalog();
       const free = listFreeModels(catalog);
       const suggested = new Set(suggestFreeCouncil(free, 3).map(r => r.id));
-      return free.map(r => ({ id: r.id, suggested: suggested.has(r.id) }));
+      return free.map(r => ({
+        id: r.id,
+        suggested: suggested.has(r.id),
+        name: r.name,
+        vendor: r.id.split('/')[1] || '',
+      }));
     } catch (_err) { return []; }
   });
 }

package/electron/main.js

@@ -15,7 +15,6 @@
 const { app, BrowserWindow, BrowserView, globalShortcut, ipcMain, screen } = require('electron');
 const path = require('path');
 const { logger } = require('../src/utils/logger');
-const { getCompatEnv } = require('../src/utils/env-compat');
 const { buildToolbarHTML, TOOLBAR_H, getBrandName } = require('./toolbar');
 const { createFoldHandler } = require('./fold');
 const { createCloseGuard } = require('./close-guard');
@@ -58,20 +57,25 @@ process.on('unhandledRejection', (reason) => {
 // Configuration from Environment (set by src/sidecar/start.js)
 // ============================================================================
 
-const MODE = getCompatEnv('MODE') || 'sidecar';
-const TASK_ID = getCompatEnv('TASK_ID') || 'unknown';
-const MODEL = getCompatEnv('MODEL') || 'unknown';
-const CWD = getCompatEnv('CWD') || process.cwd();
+const MODE = process.env.AMICUS_MODE || 'sidecar';
+const TASK_ID = process.env.AMICUS_TASK_ID || 'unknown';
+const MODEL = process.env.AMICUS_MODEL || 'unknown';
+const CWD = process.env.AMICUS_CWD || process.cwd();
 // The directory the OpenCode session was actually scoped to (#45). Set by the
 // interactive launcher as canonicalProjectPath(--cwd) so the Web-UI route is
 // built from the SAME directory createSession used. Falls back to CWD for
 // back-compat with launchers that predate this env var.
-const SESSION_DIRECTORY = getCompatEnv('SESSION_DIRECTORY') || CWD;
-const CLIENT = getCompatEnv('CLIENT') || 'code-local';
-const OPENCODE_PORT = parseInt(getCompatEnv('OPENCODE_PORT') || '4096', 10);
-const OPENCODE_SESSION_ID = getCompatEnv('SESSION_ID');
-const FOLD_SHORTCUT = getCompatEnv('FOLD_SHORTCUT') || 'CommandOrControl+Shift+F';
-const WINDOW_POSITION = getCompatEnv('WINDOW_POSITION') || 'right';
+const SESSION_DIRECTORY = process.env.AMICUS_SESSION_DIRECTORY || CWD;
+const CLIENT = process.env.AMICUS_CLIENT || 'code-local';
+const OPENCODE_PORT = parseInt(process.env.AMICUS_OPENCODE_PORT || '4096', 10);
+const OPENCODE_SESSION_ID = process.env.AMICUS_SESSION_ID;
+const FOLD_SHORTCUT = process.env.AMICUS_FOLD_SHORTCUT || 'CommandOrControl+Shift+F';
+const WINDOW_POSITION = process.env.AMICUS_WINDOW_POSITION || 'right';
+// 15b.3: per-run fold nonce (#BL-7 residual). Set by the interactive launcher
+// (src/sidecar/interactive-process.js buildElectronEnv) from the SAME value
+// baked into the system prompt's fold instruction. undefined when a launcher
+// predates this env var — fold.js falls back to the legacy bare marker.
+const FOLD_NONCE = process.env.AMICUS_FOLD_NONCE;
 
 const OPENCODE_URL = `http://localhost:${OPENCODE_PORT}`;
 
@@ -89,7 +93,8 @@ const foldHandler = createFoldHandler({
   cwd: CWD,
   sessionId: OPENCODE_SESSION_ID,
   taskId: TASK_ID,
-  port: OPENCODE_PORT
+  port: OPENCODE_PORT,
+  nonce: FOLD_NONCE
 });
 // Auto-fold on close (backlog B01): a user-initiated window close with no
 // fold yet run must not silently discard the session summary. See
@@ -128,7 +133,7 @@ function createAmicusWindow() {
 
   // Check for updates: prefer env var from CLI (cache is one-shot), fallback to direct check
   let updateInfo = null;
-  const updateInfoRaw = getCompatEnv('UPDATE_INFO');
+  const updateInfoRaw = process.env.AMICUS_UPDATE_INFO;
   if (updateInfoRaw) {
     try { updateInfo = JSON.parse(updateInfoRaw); } catch (_) {}
   }
@@ -201,7 +206,7 @@ function createAmicusWindow() {
   // silently hung process (the historical "Starting up... | 0 messages" bug).
   const failsafe = attachLoadFailsafe({
     webContents: contentView.webContents,
-    timeoutMs: parseInt(getCompatEnv('GUI_LOAD_TIMEOUT_MS') || '', 10) || undefined,
+    timeoutMs: parseInt(process.env.AMICUS_GUI_LOAD_TIMEOUT_MS || '', 10) || undefined,
     onFail: ({ reason, errorCode, errorDescription, validatedURL }) => {
       logger.error('OpenCode UI failed to load', {
         reason, errorCode, errorDescription, validatedURL, url: contentUrl
@@ -217,7 +222,7 @@ function createAmicusWindow() {
       // On timeout, show whatever is in flight rather than aborting the load.
       mainWindow.addBrowserView(contentView);
       updateContentBounds();
-      if (!process.env.SIDECAR_HEADLESS_TEST) {
+      if (!process.env.AMICUS_HEADLESS_TEST) {
         mainWindow.show();
       }
     }
@@ -234,7 +239,7 @@ function createAmicusWindow() {
         failsafe.cancel();
         mainWindow.addBrowserView(contentView);
         updateContentBounds();
-        if (!process.env.SIDECAR_HEADLESS_TEST) {
+        if (!process.env.AMICUS_HEADLESS_TEST) {
           mainWindow.show();
         }
       });

package/electron/preload-setup.js

@@ -20,7 +20,6 @@ contextBridge.exposeInMainWorld('sidecarSetup', {
       'sidecar:save-config',
       'sidecar:get-config',
       'sidecar:get-api-keys',
-      'sidecar:fetch-models',
       'sidecar:get-catalog',
       'sidecar:refresh-catalog',
       'sidecar:fetch-free-models'

package/electron/setup-ui-council.js

@@ -38,23 +38,77 @@ function buildCouncilScript() {
       else if (meta && !loaded) { meta.textContent = ''; }
     };
 
+    // Rows arrive pre-sorted by vendor (listFreeModels); group consecutive
+    // same-vendor runs into collapsible sections, mirroring the Step-3
+    // alias editor's .alias-group <details>/<summary> precedent.
+    function groupByVendor(rows) {
+      var groups = [];
+      var byVendor = {};
+      (rows || []).forEach(function(r) {
+        var v = r.vendor || (r.id.split('/')[1] || '');
+        if (!byVendor[v]) {
+          byVendor[v] = { vendor: v, rows: [] };
+          groups.push(byVendor[v]);
+        }
+        byVendor[v].rows.push(r);
+      });
+      return groups;
+    }
+
+    function vendorLabel(vendor) {
+      if (!vendor) { return 'Other'; }
+      return vendor.charAt(0).toUpperCase() + vendor.slice(1);
+    }
+
+    function buildRow(r, idx) {
+      var id = 'fc-' + idx;
+      var row = document.createElement('label');
+      row.className = 'council-row';
+      var cb = document.createElement('input');
+      cb.type = 'checkbox'; cb.value = r.id; cb.id = id; cb.checked = !!r.suggested;
+      var text = document.createElement('span');
+      text.className = 'council-row-text';
+      var nameEl = document.createElement('span');
+      nameEl.className = 'council-row-name'; nameEl.textContent = r.name || r.id;
+      var idEl = document.createElement('span');
+      idEl.className = 'council-row-id'; idEl.textContent = r.id;
+      text.appendChild(nameEl); text.appendChild(idEl);
+      row.appendChild(cb); row.appendChild(text);
+      return row;
+    }
+
+    function buildGroup(group, startIdx) {
+      var details = document.createElement('details');
+      details.className = 'council-group';
+      details.open = true;
+      var summary = document.createElement('summary');
+      var summaryLabel = document.createElement('span');
+      summaryLabel.textContent = vendorLabel(group.vendor);
+      var count = document.createElement('span');
+      count.className = 'council-group-count';
+      count.textContent = '(' + group.rows.length + ')';
+      summary.appendChild(summaryLabel); summary.appendChild(count);
+      details.appendChild(summary);
+      group.rows.forEach(function(r, i) { details.appendChild(buildRow(r, startIdx + i)); });
+      return details;
+    }
+
     async function loadFree() {
       if (loaded) { return; }
       try {
         var rows = await window.sidecarSetup.invoke('sidecar:fetch-free-models');
         loaded = true;
         results.innerHTML = '';
-        (rows || []).forEach(function(r, i) {
-          var id = 'fc-' + i;
-          var row = document.createElement('label');
-          row.className = 'council-row';
-          var cb = document.createElement('input');
-          cb.type = 'checkbox'; cb.value = r.id; cb.id = id; cb.checked = !!r.suggested;
-          var span = document.createElement('span'); span.textContent = r.id;
-          row.appendChild(cb); row.appendChild(span);
-          results.appendChild(row);
+        var groups = groupByVendor(rows);
+        var idx = 0;
+        groups.forEach(function(group) {
+          results.appendChild(buildGroup(group, idx));
+          idx += group.rows.length;
         });
-        if (meta) { meta.textContent = (rows || []).length + ' free models'; }
+        if (meta) {
+          meta.textContent = (rows || []).length + ' free models across ' + groups.length +
+            ' provider' + (groups.length === 1 ? '' : 's');
+        }
       } catch (_e) { if (meta) { meta.textContent = 'Could not load free models.'; } }
     }
 

package/electron/setup-ui-styles.js

@@ -357,9 +357,40 @@ function __rawWizardCSS() {
   /* Free council picker (Step 2) */
   .council-section { margin-top: 14px; }
   .council-toggle { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--text-muted); cursor: pointer; }
-  .council-results { max-height: 160px; overflow-y: auto; margin-top: 6px; }
-  .council-row { display: flex; align-items: center; gap: 8px; padding: 3px 0; font-size: 12px; color: var(--text); font-family: var(--font-mono); }
-  .council-row input[type="checkbox"] { accent-color: var(--accent); }
+  .council-results {
+    max-height: 220px; overflow-y: auto; margin-top: 6px;
+    border: 1px solid var(--border); border-radius: var(--r-6);
+  }
+  .council-results:empty { border: none; }
+  .council-group { margin: 0; border-bottom: 1px solid var(--border); }
+  .council-group:last-child { border-bottom: none; }
+  .council-group summary {
+    display: flex; align-items: center; gap: 6px; padding: 6px 10px;
+    cursor: pointer; font-size: 12px; font-weight: 500; color: var(--text-muted);
+    list-style: none; transition: color var(--dur-fast);
+  }
+  .council-group summary::-webkit-details-marker { display: none; }
+  .council-group summary::before {
+    content: '\\25B6'; font-size: 8px; color: var(--text-faint); transition: transform var(--dur-fast);
+  }
+  .council-group[open] summary::before { transform: rotate(90deg); }
+  .council-group summary:hover { color: var(--accent); }
+  .council-group-count { color: var(--text-faint); font-weight: 400; }
+  .council-row {
+    display: flex; align-items: center; gap: 8px;
+    padding: 5px 10px 5px 24px; font-size: 12px; color: var(--text); cursor: pointer;
+  }
+  .council-row:hover { background: var(--surface-hover); }
+  .council-row input[type="checkbox"] { accent-color: var(--accent); flex-shrink: 0; }
+  .council-row-text { display: flex; flex-direction: column; min-width: 0; }
+  .council-row-name {
+    color: var(--text); font-size: 12px; overflow: hidden;
+    text-overflow: ellipsis; white-space: nowrap;
+  }
+  .council-row-id {
+    color: var(--text-muted); font-size: 11px; font-family: var(--font-mono);
+    margin-top: 1px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
   .council-note { font-size: 10px; color: var(--text-faint); margin-top: 6px; line-height: 1.4; }
 
   /* Alias example-icon strokes — driven by class rules (var() is invalid as an SVG attribute) */

package/electron/setup-ui.js

@@ -9,6 +9,7 @@ const { buildCouncilSectionHTML, buildCouncilScript } = require('./setup-ui-coun
 const { getDefaultAliases } = require('../src/utils/config');
 const { getBrandName } = require('./toolbar');
 const { resolveQuickPicks } = require('../src/utils/quick-picks');
+const { PROVIDER_FAMILY_NAMES } = require('../src/utils/model-fetcher');
 
 /**
  * @param {object} [options={}]
@@ -30,6 +31,7 @@ function buildSetupHTML(options = {}) {
   const modelChoicesJson = JSON.stringify(quickPicks);
   const providerNamesJson = JSON.stringify(PROVIDER_NAMES);
   const defaultAliasesJson = JSON.stringify(getDefaultAliases());
+  const familyNamesJson = JSON.stringify(PROVIDER_FAMILY_NAMES);
   return `<!DOCTYPE html>
 <html><head><meta charset="utf-8"><title>Amicus Setup</title>
 <style>${css}</style></head><body>
@@ -51,11 +53,11 @@ function buildSetupHTML(options = {}) {
     </div>
   </div>
   <div class="footer"><div class="footer-brand"><svg width="15" height="15" viewBox="0 0 32 32" fill="none"><path d="M4 8H19"/><path d="M4 11H14L19 8"/><path d="M4 14H13L19 8"/><path d="M4 17H12L19 8"/><path d="M4 20H11L19 8"/><path d="M4 23H10L19 8"/><path class="brand-main" d="M19 8H28"/></svg> ${brandName}</div><div class="footer-nav"><button class="nav-btn" id="back-btn" style="display:none">Back</button><button class="nav-btn primary" id="next-btn" disabled>Next</button><button class="nav-btn primary" id="finish-btn" style="display:none">Finish</button></div></div>
-${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson)}
+${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson, familyNamesJson)}
 </body></html>`;
 }
 
-function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson) {
+function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson, familyNamesJson) {
   const keysJs = buildKeysScript();
   const aliasJs = buildAliasScript();
   const councilJs = buildCouncilScript();
@@ -69,6 +71,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   var modelChoicesData = ${modelChoicesJson};
   var providerNamesData = ${providerNamesJson};
   var defaultAliases = ${defaultAliasesJson};
+  var PROVIDER_FAMILY_NAMES = ${familyNamesJson};
   var routingChoices = {};
   var aliasEdits = {};
   var aliasDisplay = {};
@@ -178,7 +181,10 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     if (step === 2) { updateRoutingPills(); ensureCatalogLoaded(); window.refreshCouncilGating && window.refreshCouncilGating(); }
     if (step === 3) {
       updateAliasRoutes();
-      if (!window.availableModels) { fetchAvailableModels(); }
+      // B33 / #12: Step 3 shares Step 2's TTL-cached catalog load (single
+      // in-page cache: ensureCatalogLoaded no-ops if Step 2 already loaded
+      // it) instead of a separate live sidecar:fetch-models round-trip.
+      ensureCatalogLoaded();
     }
     updateNextState();
   }
@@ -393,15 +399,11 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     } catch (_e) { finishBtn.disabled = false; finishBtn.textContent = 'Finish'; }
   });
 
-  async function fetchAvailableModels() {
-    try {
-      var groups = await window.sidecarSetup.invoke('sidecar:fetch-models');
-      if (groups && groups.length > 0) { window.availableModels = groups; }
-    } catch (_e) {}
-  }
-
-  // ===== F5: searchable catalog picker (Step 2) =====
+  // ===== F5: searchable catalog picker (Step 2) + B33/#12: shared with Step 3 =====
   var catalogRows = null, catalogFetchedAt = null;
+  // #13: last-refresh outcome, so a stale cache (refresh keeps failing) is
+  // shown honestly instead of looking current.
+  var catalogLastRefreshAttempt = null, catalogLastRefreshError = null;
   window.customDefaultModel = null;
 
   async function ensureCatalogLoaded() {
@@ -412,9 +414,32 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     } catch (_e) {}
   }
 
+  // Re-derive Step 3's grouped {family, models} shape from the flat catalog
+  // rows client-side (mirrors src/utils/model-fetcher.js groupModelsByFamily
+  // keying: family name from the id prefix, falling back to the prefix
+  // itself for any provider not in PROVIDER_FAMILY_NAMES).
+  function groupCatalogByFamily(rows) {
+    if (!rows || rows.length === 0) { return []; }
+    var order = [], byFamily = {};
+    rows.forEach(function(m) {
+      var prefix = m.id.split('/')[0];
+      var family = PROVIDER_FAMILY_NAMES[prefix] || prefix;
+      if (!byFamily[family]) { byFamily[family] = []; order.push(family); }
+      byFamily[family].push(m);
+    });
+    return order.map(function(family) { return { family: family, models: byFamily[family] }; });
+  }
+
   function applyCatalog(info) {
     catalogRows = (info && info.models) || [];
     catalogFetchedAt = info && info.fetchedAt;
+    catalogLastRefreshAttempt = info && info.lastRefreshAttempt;
+    catalogLastRefreshError = info && info.lastRefreshError;
+    // Single shared in-page cache: Step 3's alias dropdown (buildModelSelect)
+    // reads window.availableModels, re-derived from the same catalog load
+    // Step 2 uses — no second get-catalog round-trip, and the refresh
+    // button (Step 2) re-applying here keeps Step 3's dropdown data current.
+    window.availableModels = groupCatalogByFamily(catalogRows);
     renderSearchMeta();
     renderSearchResults();
     if (catalogRows.length === 0) {
@@ -427,7 +452,14 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     var meta = $('model-search-meta');
     if (!meta) { return; }
     var when = catalogFetchedAt ? new Date(catalogFetchedAt).toLocaleString() : 'never';
-    meta.textContent = catalogRows.length + ' models \\u00b7 catalog fetched ' + when;
+    var text = catalogRows.length + ' models \\u00b7 catalog fetched ' + when;
+    // #13: one-line stale hint when the last refresh attempt failed AFTER
+    // the data currently shown was fetched (don't redesign Step 2 for this).
+    if (catalogLastRefreshError && catalogLastRefreshAttempt &&
+        (!catalogFetchedAt || catalogLastRefreshAttempt > catalogFetchedAt)) {
+      text += ' \\u2014 \\u26a0 refresh failed, showing last-known data';
+    }
+    meta.textContent = text;
   }
 
   function fmtCtx(n) { return n == null ? '' : ' \\u00b7 ctx ' + n; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
@@ -28,9 +28,7 @@
   "homepage": "https://bourbondog.github.io/amicus/",
   "bin": {
     "amicus": "./bin/amicus.js",
-    "am": "./bin/amicus.js",
-    "sidecar": "./bin/amicus.js",
-    "claude-sidecar": "./bin/amicus.js"
+    "am": "./bin/amicus.js"
   },
   "main": "src/index.js",
   "exports": {
@@ -85,7 +83,6 @@
   "devDependencies": {
     "chrome-remote-interface": "^0.33.3",
     "eslint": "^8.0.0",
-    "husky": "^9.1.7",
     "jest": "^29.0.0",
     "lint-staged": "^16.3.2",
     "puppeteer": "^24.36.0",

package/skills/second-opinion/MODEL-NOTES.md

@@ -25,8 +25,8 @@ injection, long-read failures, judge tool-wander; see changelog)._
 - **Transient provider errors** (502s, connection drops): re-run the affected leg (solo
   `amicus start --json`, same briefing file) or the wave — see per-model notes for
   model-specific signals. Never present a half-finished run as an answer.
-- **Credentials:** keys live in `~/.config/amicus/.env` (legacy `~/.config/sidecar/.env` still
-  read). Configure with `amicus setup`.
+- **Credentials:** keys live in `~/.config/amicus/.env`. The legacy `~/.config/sidecar/.env`
+  fallback was removed in v2.0.0 (see `docs/SHIMS.md`). Configure with `amicus setup`.
 - **PowerShell `--models` quoting (Windows):** always quote comma-separated model lists —
   `--models "gemini,gpt,deepseek"`. Unquoted, PowerShell splits on commas and amicus receives one
   mangled alias → instant arg-parse failure. (Now baked into every SKILL.md example.)

package/skills/second-opinion/SKILL.md

@@ -165,16 +165,16 @@ equivalent.
 
 Instruct models to emit the structured JSON verbatim after the prose, without preamble, so it parses cleanly.
 
-**After the wave returns, validate each leg's findings block** using `validateFindings` (Unit A — `src/council/findings.js`). If a leg's JSON fails validation:
+Save each leg's full output (prose + findings block) to the run folder as `review-<model>.md`
+(one file per reviewer) before moving on.
+
+**After the wave returns, validate each leg's findings block** by running `amicus council validate <leg-file> --json` (a thin CLI wrapper over `validateFindings`, Unit A — `src/council/findings.js`). It reads the leg's saved `review-<model>.md` and prints `{ok, findings, errors}`. Exit codes are a **tri-state** contract: `0` when `ok:true` (well-formed, proceed), `2` when `ok:false` (validation failed — a distinct, scriptable outcome, not a crash), `1` (`BAD_ARGS`) for a missing/unreadable file. If a leg's JSON fails validation (`ok:false` / exit 2):
 1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \<errors\>." Keep the first-pass prose. (Solo `start` passes through the **same budget gate** as `fanout`. If launching the wave required `--max-cost <$>` or `--no-cost-gate`, pass the **same flag on every repair re-prompt and on the chair call** — otherwise the gate can refuse a repair or the chair mid-council.)
 2. If still malformed, retry **once more** (cap = **2** re-prompts total).
 3. If still malformed after 2 retries, mark the review `unstructured` and hand-parse its prose into the schema. The review proceeds — never dropped for a formatting miss.
 
 Record per-model **conformance** (`clean` | `repaired` | `unstructured`) for inclusion in the tally input's `runStats` and the Stage-6 MODEL-NOTES note.
 
-Save each leg's full output (prose + findings block) to the run folder as `review-<model>.md`
-(one file per reviewer) before moving on.
-
 **"Claude in the council" (when toggled on):** Claude also produces a **fresh** Stage-1 review on the artifact in the identical findings format — a new structured pass on the artifact, not a formalization of anything said upstream. This review is added to the bundle as one more anonymous entry. Claude does not rank or adjudicate in Stage 2 (it holds the label map), and does not chair in Stage 3. Save it as `review-claude.md`.
 
 **Wave-degrade rules (Stage 1).** Read failures from the wave document — never silently ignore
@@ -210,7 +210,7 @@ amicus fanout --models "<m1,m2,m3>" --prompt-file <run-folder>/_tmp-bundle-stage
 (Background, same JSON handling as Stage 1.) Each judge's leg `summary` is its ranking +
 adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the surviving judges
 (≥ 1) and disclose the reduced bench in `crossreview-matrix.md`; tier definitions are unchanged
-(they already count "judges engaged"). Each judge is asked to do two things on the bundle:
+(they already count "judges engaged").
 
 **Judge-briefing hardening (required).** Open `_tmp-bundle-stage2.md` with this preamble, verbatim, as its first line:
 
@@ -218,6 +218,8 @@ adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the
 
 Plan-agent judges have wandered to tools mid-adjudication (reading files instead of judging and returning only narration), and a tool-capable judge can read the de-anonymized `review-<model>.md` files in the run folder — an anonymization leak. The preamble closes both. **Scratch-cwd (optional second layer):** launch the Stage-2 wave (and the Stage-3 chair call) with `--cwd <run-folder>/_scratch/` — create the empty directory first — so even a wandering agent finds nothing to read. Caveat: those legs' session records then live under `_scratch/.claude/amicus_sessions/`, so any later `amicus read <taskId>` for them needs the same `--cwd`.
 
+Each judge is asked to do two things on the bundle:
+
 **Task A — Rank.** Order the reviews from most to least accurate and insightful. End the response with a parseable block in exactly this format (no other text on those lines):
 
 ```
@@ -242,12 +244,14 @@ As each judge's ranking + adjudication response returns, collect it (the raw per
 
 **Five-keys checklist — verify `tally-input.json` has ALL of:** `meta` (with `meta.models`), `findings`, `adjudications`, `rankings`, `runStats` (`runStats` may be `[]`; the other four are required). Do not call `tally` until all five are present.
 
-Then call:
+Then call, saving the printed `record` to `<run-folder>/tally.json` (Stage 5's `amicus council verdict` reads it back from disk):
 
 ```
-amicus council tally <run-folder>/tally-input.json --json
+amicus council tally <run-folder>/tally-input.json --json > <run-folder>/tally.json
 ```
 
+**Windows PowerShell 5.1 caveat:** that `>` redirect writes UTF-16 under legacy Windows PowerShell 5.1 (fine on pwsh 7+ or bash), which corrupts `tally.json` for Stage 5's `amicus council verdict` and surfaces as a confusing `BAD_ARGS` there instead of here — on 5.1 pipe through `| Out-File -Encoding utf8` (or run under pwsh 7+) instead of a bare `>`.
+
 The output `record` carries the deterministic tiers (Disputed / Confirmed / Contested / Singleton), `confidence` (`solid` | `thin`), both street-cred numbers (`withSelf` and `peersOnly`), the validated `runStats`, and `tierCounts`. **Claude may override a `thin`-confidence tier at the margins** before Stage 4 — record the override in `tierOverride: {from, to, reason}`; the matrix and `verdict.json` surface it. De-anonymize and write the tally results to `crossreview-matrix.md` — the adjudication grid plus the street-cred table. This data feeds Stage 3 (chair briefing) and is never re-anonymized or forwarded to any council model.
 
 ---
@@ -334,7 +338,7 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
 - `review-<model>.md` × N (already saved in Stage 1)
 - `crossreview-matrix.md` — the de-anonymized adjudication grid and street-cred table
 - `verdict.md` (already saved in Stage 3)
-- `verdict.json` — write via `buildVerdict(record, decisions)` (`src/council/verdict.js`): pass the tally `record` from Stage 2 and the Stage-4 decision map (accepted / denied / modified / deferred per finding, plus any `duplicateOf` links Claude identified). This is the schema-stamped machine-readable record of the full run. Write it with an atomic tmp+rename to the run folder.
+- `verdict.json` — write by running `amicus council verdict <run-folder>/tally.json --decisions <run-folder>/decisions.json -o <run-folder>/verdict.json` (a thin CLI wrapper over `buildVerdict(record, decisions)` + `writeVerdictAtomic`, `src/council/verdict.js`). `<run-folder>/tally.json` is the `record` saved from the Stage-2 `amicus council tally` call. `<run-folder>/decisions.json` is a **JSON array**, one object per finding: `{id, decision, applied?, duplicateOf?, tierOverride?}` — `id` is the run-global label id (e.g. `A1`); `decision` is the Stage-4 outcome (accepted / denied / modified / deferred); `applied` (optional bool) marks whether the accepted change was actually applied to the artifact in Stage 5; `duplicateOf` (optional) links to another finding's id when Claude identified a duplicate; `tierOverride` (optional) carries any `{from, to, reason}` override recorded in Stage 2. Save this array to `<run-folder>/decisions.json` first, then run the command — it parses the tally record and the decisions file, calls `buildVerdict`, and writes the schema-stamped machine-readable record to the run folder via the same atomic tmp+rename convention the function always used.
 - `report.md` — the chair's synthesis + the full Stage-4 decision log + a summary of what was
   applied (+ the "How Claude's review fared" readout when "Claude in the council" is on) + a
   **run-stats table**: one row per model call — **stage** (which stage you launched the call for)
@@ -343,15 +347,17 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
   — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
   invent a figure. Add a wave **total cost** row from the wave document's
   `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`; never invent a value.
-  - **Renderer:** once `verdict.json` is written, generate BOTH renderings:
-    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md` and
-    `amicus council report <run-folder>/verdict.json --html > <run-folder>/report.html`.
-    **`report.html` is the default final artifact to hand the user** — a self-contained,
-    shareable page. This emits the
+  - **Renderer:** once `verdict.json` is written, run
+    `amicus council report <run-folder>/verdict.json --html > <run-folder>/report.html` — a
+    **separate, deterministic** artifact, not report.md itself. **`report.html` is the default
+    final artifact to hand the user** — a self-contained, shareable page. This emits the
     adjudication matrix (finding × judge), the peers-only street-cred table, the
     findings-by-tier groupings (Disputed-first), and the per-model + wave cost —
-    deterministic data only. Prefer it over hand-assembling the matrix; reserve
-    prose for the chair's synthesis and the decision log.
+    deterministic data only. To assemble report.md, also run
+    `amicus council report <run-folder>/verdict.json --md` (no redirect — read its stdout) and
+    paste that Markdown into report.md as one section; reserve the rest of report.md's prose for
+    the chair's synthesis and the decision log. Prefer the renderer's Markdown over
+    hand-assembling the matrix by hand.
 
 Tell the user exactly which files were written and where, leading with `report.html`, **and present the verdict inline in chat** — the chair's overall assessment (verbatim or lightly trimmed) plus the tier counts (Confirmed/Disputed/Contested/Singleton) and what was applied. Never hand over only file paths.
 
@@ -465,14 +471,9 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
   - `review-<model>.md` ×N — raw Stage 1 reviews (plus `review-claude.md` when "Claude in the council" is on)
   - `crossreview-matrix.md` — adjudication grid + de-anonymized street-cred table
   - `verdict.md` — the chair's synthesis (prose)
-  - `verdict.json` — schema-stamped machine-readable record: tally output + Stage-4 decisions, written via `buildVerdict(record, decisions)` at Stage 5
-  - `report.md` — synthesis + decision log + what was applied (+ the "How Claude's review fared" readout when the toggle is on) + a
-    **run-stats table**: one row per model call — **stage** (which stage you launched the call for) plus **model, status, durationMs, and cost** read from the wave/run JSON `usage`
-    block. Cost is `usage.cost.amount` (USD); mark it with its `usage.cost.source`
-    — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
-    invent a figure. Add a wave **total cost** row from the wave document's
-    `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`.
-  - `report.html` — the same report rendered as a self-contained page (`amicus council report <verdict.json> --html`); the default artifact to share.
+  - `verdict.json` — schema-stamped machine-readable record: tally output + Stage-4 decisions, written via `amicus council verdict` at Stage 5
+  - `report.md` — Claude-authored; full contract defined once in *Stage 5 → Run-folder artifacts* above (chair's synthesis + Stage-4 decision log + run-stats table).
+  - `report.html` — a **separate, deterministic** artifact generated by the `amicus council report <verdict.json> --html` renderer directly from `verdict.json` (no chair prose, no decision-log narrative — see Stage 5's *Renderer* note); the default artifact to share.
 - Reviewed copy: `<stem>-reviewed.<ext>`, next to the source.
 - Temp working files (`_tmp-*.md`: extracts, stage briefings, red-team brief, bundle, chair packet, proposed
   MODEL-NOTES diff) live in the run folder and are cleaned up at the end of the run — the proposed-diff file

package/skills/sidecar/SKILL.md

@@ -747,13 +747,13 @@ The summary includes:
 
 ### Handling Config Update Notices
 
-When amicus emits `[AMICUS_CONFIG_UPDATE]` on stderr (or the legacy `[SIDECAR_CONFIG_UPDATE]` from older installs — accept either), the user's model aliases have changed (via `amicus setup`). The message contains a hash comment and a markdown alias table.
+When amicus emits `[AMICUS_CONFIG_UPDATE]` on stderr, the user's model aliases have changed (via `amicus setup`). The message contains a hash comment and a markdown alias table.
 
 **Action required:**
 1. Find the "Model Aliases" section in the project's CLAUDE.md
 2. Replace that section's content with the block provided in the message
 3. If no "Model Aliases" section exists, add one after the title line
-4. Do **not** remove the `<!-- amicus-config-hash: ... -->` comment (legacy files may use `<!-- sidecar-config-hash: ... -->` — do not remove whichever is present) — it tracks config changes and prevents duplicate notifications
+4. Do **not** remove the `<!-- amicus-config-hash: ... -->` comment — it tracks config changes and prevents duplicate notifications
 
 The update is purely informational (alias mappings) and safe to apply without user confirmation.
 
@@ -846,7 +846,7 @@ The mutex approach looks correct. Add tests."
 
 ### "Missing Authentication header" in Claude Code or CI
 
-API keys in `~/.zshrc` are not available in non-interactive shells. Resolution order: `process.env` > `~/.config/amicus/.env` (legacy `~/.config/sidecar/.env` still read) > `~/.local/share/opencode/auth.json` (first wins). Fix:
+API keys in `~/.zshrc` are not available in non-interactive shells. Resolution order: `process.env` > `~/.config/amicus/.env` (the legacy `~/.config/sidecar/.env` fallback was removed in v2.0.0 — see `docs/SHIMS.md`) > `~/.local/share/opencode/auth.json` (first wins). Fix:
 1. Run `amicus setup` (stores keys in `~/.config/amicus/.env`)
 2. Or move exports to `~/.zshenv`
 3. Or add credentials to `~/.local/share/opencode/auth.json`