amicus 1.7.3 → 1.7.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "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.",
   "author": { "name": "Christian Wagner" },
   "homepage": "https://bourbondog.github.io/amicus/",

package/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.7.5] - 2026-07-01
+
+A batch of fixes from an independent DeepSeek V4 Pro code review, each verified against source.
+
+### Fixed
+- **Long prompts no longer truncate on Windows.** The `amicus_start` and `amicus_continue` MCP
+  handlers passed the full prompt inline on the spawned command line, which silently truncated once
+  it crossed Windows's ~32 KB argument cap — so a sidecar could run against a corrupted briefing with
+  no error. Both paths now write the prompt to a `briefing.md` in the session directory and pass
+  `--prompt-file`, matching the existing fanout handler; the CLI `continue` command learned
+  `--prompt-file` as well.
+- **`getMessages` no longer masks SDK error responses.** An error-shaped response with no `data`
+  array was indistinguishable from "zero messages" in the poll loop; it now logs a warning carrying
+  the session id and surfaced error while still returning `[]`.
+- **`getSessionDir` rejects path-traversal task ids.** A defense-in-depth containment guard (the same
+  check style used elsewhere in the codebase) throws on a task id that would escape the sessions dir.
+- **Cross-platform `auth.json` discovery.** The one-time OpenCode key-import path was hardcoded to the
+  Unix XDG location; it now probes `$XDG_DATA_HOME`, `~/.local/share`, and `%APPDATA%` (Windows) and
+  uses the first that exists.
+
+### Changed
+- **The fold-completion marker is harder to spoof.** A bare `[SIDECAR_FOLD]` echoed mid-output (e.g. a
+  model reproducing these instructions or summarizing a prior sidecar session) no longer forces a
+  premature fold — the marker now completes a run only when it is the final non-empty line of output,
+  with the existing idle/timeout fallbacks unchanged so a run can never hang.
+- **The conversation-mirror tool-call buffer is bounded.** Capped at 2000 entries with a separate
+  dedup set, so a very long tool-heavy session can't grow it without limit.
+- **Unknown `--no-*` flags are treated as boolean.** They no longer swallow the following positional
+  argument (`--no-x=value` still records its inline value; allowlisted flags are unchanged).
+- **`--prompt-file` validation is order-independent.** `validateStartArgs` now resolves the prompt
+  source itself, so validation no longer depends on the handler having resolved it first.
+
+### Docs
+- **Corrected the `tiktoken` dependency note.** It is declared but unused; token sizing uses a
+  `length/4` heuristic. Added caveat comments at both estimators. (Removing the unused dependency is
+  tracked as a follow-up.)
+
+## [1.7.4] - 2026-06-30
+
+### Fixed
+- **The Electron GUI self-heal survives a stalled `extract-zip` on Node 24.** On some Node 24 boxes the
+  bundled `extract-zip@2.0.1` (its latest release — it cannot be bumped) stalls mid-extract: its promise
+  never resolves *and* never rejects. Because the self-heal `await`s it, the event loop drains and the
+  process exits `0` with a half-extracted `dist/` and **no `electron.exe`** — so the repair looked like it
+  "did nothing." Extraction is now hardened two ways: `extract-zip` is bounded by an idle + max timer (a
+  stall becomes a caught error instead of a silent hang, and the live timer prevents the premature exit),
+  and if it stalls, throws, or produces no files, amicus falls back to a **native OS unzip** (Windows:
+  bundled `bsdtar`, then PowerShell `Expand-Archive`; macOS: `ditto`, then `unzip`; Linux: `unzip`, then
+  `tar`) — each verified to extract the exact Electron zip that `extract-zip` choked on. Success is still
+  reported **only** when the real binary lands on disk (the existing exe-stat verify is unchanged), so no
+  path can claim a false repair.
+
 ## [1.7.3] - 2026-06-30
 
 ### Fixed

package/bin/amicus.js

@@ -215,6 +215,19 @@ async function handleContinue(args) {
     process.exit(1);
   }
 
+  // BL-1: accept --prompt-file (XOR --prompt) so the MCP handler can pass a long
+  // follow-up prompt via file, dodging the ~32KB Windows command-line cap.
+  if (args['prompt-file'] !== undefined) {
+    const { resolvePromptSource } = require('../src/utils/prompt-source');
+    const promptRes = resolvePromptSource(args);
+    if (promptRes.error) {
+      console.error(promptRes.error);
+      process.exit(1);
+    }
+    args.prompt = promptRes.prompt;
+    delete args['prompt-file'];
+  }
+
   if (!args.prompt && !args.briefing) {
     console.error('Error: --prompt is required for continue');
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "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": [
     "claude",

package/src/cli-handlers-run.js

@@ -28,6 +28,10 @@ async function handleStart(args) {
     const promptRes = resolvePromptSource(args);
     if (promptRes.error) { process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error })); }
     args.prompt = promptRes.prompt;
+    // Drop --prompt-file now that it's resolved: validateStartArgs' self-contained
+    // guard would otherwise re-run resolvePromptSource with both prompt and
+    // prompt-file set and trip its mutually-exclusive branch.
+    delete args['prompt-file'];
   }
   if (args.json && !args['no-ui']) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --json requires --no-ui' }));

package/src/cli.js

@@ -16,6 +16,7 @@ const {
   validateApiKey,
   validateThinkingLevel
 } = require('./utils/validators');
+const { resolvePromptSource } = require('./utils/prompt-source');
 const { logger } = require('./utils/logger');
 
 /**
@@ -78,6 +79,14 @@ function parseArgs(argv) {
         continue;
       }
 
+      // Unknown negation flags: known --no-* flags are already handled by
+      // isBooleanFlag() above; treat any *unregistered* --no-* token as a
+      // boolean so it can never swallow the following positional as a value.
+      if (key.startsWith('no-')) {
+        result[key] = true;
+        continue;
+      }
+
       // Options with values
       if (next && !next.startsWith('--')) {
         result[key] = parseValue(key, next);
@@ -153,6 +162,19 @@ function parseValue(key, value) {
  * @returns {{ valid: boolean, error?: string }}
  */
 function validateStartArgs(args) {
+  // Resolve the prompt source (--prompt XOR --prompt-file) here so validation
+  // is self-contained and order-independent: a caller need not have run
+  // resolvePromptSource() first. Skipped when args.prompt is already a plain
+  // string (the classic path / already-resolved by handleStart), so the empty
+  // '' case still falls through to the presence/content checks below.
+  if (args['prompt-file'] !== undefined || args.prompt === undefined || args.prompt === true) {
+    const res = resolvePromptSource(args);
+    if (res.error) {
+      return { valid: false, code: 'MISSING_PROMPT', error: res.error };
+    }
+    args.prompt = res.prompt;
+  }
+
   // Required: --prompt (presence check)
   if (!args.prompt) {
     return { valid: false, error: 'Error: --prompt is required' };

package/src/context-compression.js

@@ -28,6 +28,8 @@ function estimateTokenCount(text) {
     return 0;
   }
 
+  // Intentional cheap heuristic — not a real BPE tokenizer; under/over-counts
+  // for CJK, code, and punctuation-dense text. (ceil, vs floor in context.js.)
   return Math.ceil(text.length / 4);
 }
 

package/src/context.js

@@ -52,7 +52,8 @@ function estimateTokens(text) {
   if (!text || typeof text !== 'string') {
     return 0;
   }
-  // Spec specifies ~4 chars per token
+  // Intentional cheap heuristic (spec §5.3: ~4 chars/token). Not a real BPE
+  // tokenizer — under/over-counts for CJK, code, and punctuation-dense text.
   return Math.floor(text.length / 4);
 }
 

package/src/headless.js

@@ -21,6 +21,27 @@ const { createMirrorState, mirrorMessages, logMessage } = require('./sidecar/con
 const FOLD_MARKER = '[SIDECAR_FOLD]';
 const COMPLETE_MARKER = FOLD_MARKER; // backward compat
 
+/**
+ * #BL-7: the fold marker is the fixed public string [SIDECAR_FOLD]. A model can
+ * legitimately emit it on its own line mid-output — summarizing a prior sidecar,
+ * reproducing these instructions, or from scraped content — which used to force a
+ * PREMATURE fold. Harden by requiring the marker to be the FINAL non-empty line
+ * of the output: a standalone marker followed by MORE content is treated as
+ * echoed prose, not a completion signal. Only the true trailing marker folds.
+ *
+ * @param {string} output - Accumulated assistant output
+ * @returns {number} char index where the trailing marker line begins, or -1
+ */
+function findTrailingFoldMarker(output) {
+  if (!output) { return -1; }
+  // The marker must be the last non-empty line: it sits alone on its line
+  // (only intra-line whitespace around it) and NOTHING but whitespace follows
+  // to the end of the string. The `(?![\s\S]*\S)` lookahead pins it to the true
+  // end — a bare marker followed by more prose is echoed content, not a signal.
+  const m = /^[^\S\r\n]*\[SIDECAR_FOLD\][^\S\r\n]*$(?![\s\S]*\S)/m.exec(output);
+  return m ? m.index : -1;
+}
+
 /**
  * Default timeout: 15 minutes per spec §6.2
  */
@@ -399,10 +420,11 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           elapsed: Date.now() - startTime
         });
 
-        // Check for completion marker on its own line (not inline in prose).
-        // Models may mention [SIDECAR_FOLD] when describing code — only treat
-        // it as a signal when it appears as a standalone line.
-        if (/^\s*\[SIDECAR_FOLD\]\s*$/m.test(mirror.output)) {
+        // Check for the completion marker as the FINAL non-empty line (#BL-7).
+        // Models may emit [SIDECAR_FOLD] on its own line mid-output (echoing a
+        // prior sidecar, these instructions, or scraped content) — only treat
+        // it as a completion signal when nothing but blank lines follow it.
+        if (findTrailingFoldMarker(mirror.output) !== -1) {
           completed = true;
           break;
         }
@@ -608,7 +630,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
 }
 
 /**
- * Extract summary from output (everything before [SIDECAR_FOLD])
+ * Extract summary from output (everything before the trailing [SIDECAR_FOLD])
  * Spec Reference: §6.2 - Return summary (everything before [SIDECAR_FOLD])
  *
  * @param {string} output - Raw output from OpenCode
@@ -619,13 +641,13 @@ function extractSummary(output) {
     return '';
   }
 
-  // Split on the fold marker only when it appears on its own line.
-  // Models may mention [SIDECAR_FOLD] inline when describing code —
-  // only treat it as a delimiter when standalone.
-  const markerRegex = /^\s*\[SIDECAR_FOLD\]\s*$/m;
-  const match = output.match(markerRegex);
-  if (match) {
-    return output.slice(0, match.index).trim();
+  // Split on the fold marker only when it is the FINAL non-empty line (#BL-7).
+  // A [SIDECAR_FOLD] echoed mid-output (describing code, reproducing these
+  // instructions, or from scraped content) is NOT a delimiter — keep it as
+  // content. Only the true trailing marker is stripped.
+  const idx = findTrailingFoldMarker(output);
+  if (idx !== -1) {
+    return output.slice(0, idx).trim();
   }
   return output.trim();
 }
@@ -659,6 +681,7 @@ module.exports = {
   waitForServer,
   withTimeout,
   extractSummary,
+  findTrailingFoldMarker,
   formatFoldOutput,
   DEFAULT_TIMEOUT,
   FOLD_MARKER,

package/src/mcp-server.js

@@ -211,7 +211,17 @@ const handlers = {
     const { generateTaskId } = require('./sidecar/start');
     const taskId = generateTaskId();
 
-    const args = ['start', '--prompt', input.prompt, '--task-id', taskId, '--client', 'cowork'];
+    // New session → canonical amicus dir (writes).
+    const sessionDir = getSessionDir(cwd, taskId);
+
+    // BL-1: the prompt goes via file, not inline. A long prompt passed as a CLI
+    // arg silently truncates/corrupts on Windows (~32KB command-line cap). Mirror
+    // the amicus_fanout briefing-file pattern; the spawn command line must NOT
+    // carry the prompt. --prompt-file is resolved by handleStart/resolvePromptSource.
+    // The file itself is written just before the spawn fallback below (the
+    // shared-server path passes the prompt in-process and never reads args).
+    const briefingPath = path.join(sessionDir, 'briefing.md');
+    const args = ['start', '--prompt-file', briefingPath, '--task-id', taskId, '--client', 'cowork'];
     if (resolvedModel) { args.push('--model', resolvedModel); }
     const agent = (input.noUi && (!input.agent || input.agent.toLowerCase() === 'chat'))
       ? 'build' : input.agent;
@@ -229,9 +239,6 @@ const handlers = {
     if (input.windowPosition)   { args.push('--position', input.windowPosition); }
     args.push('--cwd', cwd);
 
-    // New session → canonical amicus dir (writes).
-    const sessionDir = getSessionDir(cwd, taskId);
-
     if (sharedServer.enabled && input.noUi) {
       // Shared server path: headless only, delegates to runHeadless()
       let sessionId;
@@ -349,14 +356,20 @@ const handlers = {
       }
     }
 
-    // Feature flag disabled (or shared server failed): fall back to per-process spawn
+    // Feature flag disabled (or shared server failed): fall back to per-process spawn.
+    // BL-1: create the session dir and write the prompt to briefing.md BEFORE the
+    // spawn so --prompt-file (built above) resolves to a real file, keeping the
+    // full prompt off the ~32KB-capped Windows command line.
     let child;
-    try { child = spawnSidecarProcess(args, sessionDir); } catch (err) {
+    try {
+      fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
+      child = spawnSidecarProcess(args, sessionDir);
+    } catch (err) {
       return textResult(`Failed to start Amicus: ${err.message}`, true);
     }
 
     if (child && child.pid) {
-      fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
       recordSession(taskId, cwd); // #40: global index for cross-project lookup
       const metaPath = path.join(sessionDir, 'metadata.json');
       if (!fs.existsSync(metaPath)) {
@@ -631,14 +644,22 @@ const handlers = {
     // New continuation session → canonical amicus dir (writes).
     const sessionDir = getSessionDir(cwd, newTaskId);
 
-    const args = ['continue', input.taskId, '--prompt', input.prompt,
+    // BL-1: the follow-up prompt goes via file, not inline, so a long prompt is
+    // never truncated by the ~32KB Windows command-line cap. handleContinue reads
+    // --prompt-file. The briefing is written into the NEW session dir below.
+    const briefingPath = path.join(sessionDir, 'briefing.md');
+    const args = ['continue', input.taskId, '--prompt-file', briefingPath,
       '--task-id', newTaskId, '--client', 'cowork', '--cwd', cwd];
     if (input.model) { args.push('--model', input.model); }
     if (input.noUi) { args.push('--no-ui', '--agent', 'build'); }
     if (input.timeout) { args.push('--timeout', String(input.timeout)); }
     if (input.contextTurns)     { args.push('--context-turns', String(input.contextTurns)); }
     if (input.contextMaxTokens) { args.push('--context-max-tokens', String(input.contextMaxTokens)); }
-    try { spawnSidecarProcess(args, sessionDir); } catch (err) {
+    try {
+      fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
+      spawnSidecarProcess(args, sessionDir);
+    } catch (err) {
       return textResult(`Failed to continue: ${err.message}`, true);
     }
     recordSession(newTaskId, cwd); // #40: global index for cross-project lookup

package/src/opencode-client.js

@@ -261,7 +261,21 @@ async function getMessages(client, sessionId, directory) {
     ...directoryQuery(directory)
   });
 
-  return result.data || [];
+  // A well-formed response carries a data array (possibly empty). If it's
+  // absent, the SDK returned an error shape (e.g. a 5xx with { error }) that
+  // would otherwise be indistinguishable from "0 messages" — surface it so the
+  // poll loop's diagnostics aren't blind. Return contract unchanged: an array.
+  if (!Array.isArray(result.data)) {
+    const { logger } = require('./utils/logger');
+    logger.warn('getMessages: SDK response had no data array', {
+      sessionId,
+      status: (result.response && result.response.status) || (result.error && result.error.status),
+      error: result.error && (result.error.message || JSON.stringify(result.error))
+    });
+    return [];
+  }
+
+  return result.data;
 }
 
 /**

package/src/session-manager.js

@@ -37,7 +37,15 @@ const LEGACY_SESSIONS_DIR = 'sidecar_sessions';
  * // Returns: '/path/to/project/.claude/amicus_sessions/abc123'
  */
 function getSessionDir(projectDir, taskId) {
-  return path.join(projectDir, '.claude', SESSIONS_DIR, taskId);
+  const sessionDir = path.join(projectDir, '.claude', SESSIONS_DIR, taskId);
+  // Defense-in-depth: reject a taskId that would escape the sessions dir
+  // (path separators / '..'). Callers pre-validate today; this is a backstop.
+  const base = path.resolve(projectDir, '.claude', SESSIONS_DIR);
+  const resolved = path.resolve(sessionDir);
+  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+    throw new Error('Invalid task ID: path traversal detected');
+  }
+  return sessionDir;
 }
 
 /**

package/src/sidecar/conversation-mirror.js

@@ -9,11 +9,20 @@
  * except the injectable `now`.
  */
 
+// Bound the unbounded toolCalls accumulator (BL-4). This array holds {id,name,input}
+// objects whose `input` can be large; it is the only mirror-state member that grows
+// per tool call with no natural bound and carries heavy payloads. Keep the most recent
+// N, dropping the oldest. Dedup identity lives in the separate seenToolCallIds Set so
+// dropping an old array entry never causes a re-append or a spurious toolCalls.length
+// bump in the headless idle detector.
+const MAX_TOOL_CALLS = 2000;
+
 /** Fresh cursor for a session's mirror. */
 function createMirrorState() {
   return {
     seenTextParts: new Map(),   // partId -> last captured text length
-    toolCalls: [],              // [{id,name,input}]
+    toolCalls: [],              // [{id,name,input}] — capped at MAX_TOOL_CALLS (most-recent-N)
+    seenToolCallIds: new Set(), // stable dedup identity for tool calls (survives the cap)
     seenToolResultIds: new Set(),
     receivingReported: false,
     output: '',                 // accumulated assistant text
@@ -75,9 +84,13 @@ function mirrorMessages(messages, state, opts = {}) {
             progressUpdates.push({ stage: 'receiving', extra: { messagesReceived: 1 } });
           }
         }
-      } else if ((part.type === 'tool_use' || part.type === 'tool') && !state.toolCalls.find(t => t.id === part.id)) {
+      } else if ((part.type === 'tool_use' || part.type === 'tool') && !state.seenToolCallIds.has(part.id)) {
         const toolCall = { id: part.id, name: part.name, input: part.input };
+        state.seenToolCallIds.add(part.id);
         state.toolCalls.push(toolCall);
+        // Bound growth: keep the most recent N tool-call payloads (BL-4). Dedup is the
+        // Set above, so dropping the oldest here never causes a re-append.
+        if (state.toolCalls.length > MAX_TOOL_CALLS) { state.toolCalls.shift(); }
         appendLines.push({ role: 'assistant', type: 'tool_use', toolCall, timestamp: now() });
 
         // Update progress on tool_use detection

package/src/sidecar/electron-install.js

@@ -27,6 +27,12 @@ const { spawnSync } = require('child_process');
 const { resolveCacheRoots } = require('./electron-cache');
 const { avHint, verifyExtractOutcome: verifyQuarantine } = require('./electron-quarantine');
 const { acquireRepairLock } = require('./electron-lock');
+const { robustExtract } = require('./unzip');
+
+/** Self-heal progress line to stderr (visible during first-GUI provision). */
+function stderrLog(msg) {
+  try { process.stderr.write(`${msg}\n`); } catch { /* stderr closed */ }
+}
 
 /** Default on-disk location of the installed electron package. */
 function defaultElectronDir() {
@@ -199,7 +205,9 @@ async function repairElectron({
   deps = {},
 } = {}) {
   const fs = deps.fs || fsDefault;
-  const extract = deps.extract || require('extract-zip');
+  // Default extract: extract-zip bounded (idle/max) + native-unzip fallback (extract-zip-node24 stall).
+  const extract = deps.extract
+    || ((zipPath, o) => robustExtract(zipPath, { ...o, platform, deps: { fs, log: stderrLog } }));
   // Default-bound the last-resort installer spawn (8 min) so a first-GUI-use
   // provision that reaches runInstaller without an explicit timeoutMs can't hang
   // the holder — the caller's timeoutMs still wins when provided.

package/src/sidecar/unzip.js

@@ -0,0 +1,231 @@
+/**
+ * Robust unzip for the electron self-heal (#53 follow-up; extract-zip-node24).
+ *
+ * FIELD BUG: on some Node 24 boxes `extract-zip@2.0.1` STALLS mid-extract — its
+ * promise never resolves AND never rejects. Because the self-heal `await`s it,
+ * when the event loop drains Node exits 0 with a partial extract and no
+ * electron.exe, so `repairElectron` silently no-ops. extract-zip 2.0.1 is the
+ * LATEST published release, so "just bump it" is impossible.
+ *
+ * robustExtract() survives that with three independent layers, none of which
+ * can report a false success:
+ *   1. BOUND extract-zip with an idle timer (reset on each onEntry) + a hard max
+ *      timer, so a stall becomes a catchable outcome — and the live timer keeps
+ *      the event loop alive so the process can't exit 0 before we fall back.
+ *   2. FALL BACK to a native OS unzip (tar / Expand-Archive on Windows,
+ *      ditto / unzip on macOS, unzip / tar on Linux) — each confirmed to extract
+ *      the exact electron zip the field box choked on.
+ *   3. Only report success when files actually landed on disk. The electron
+ *      exe-stat verify stays upstream (electron-quarantine.verifyExtractOutcome).
+ *
+ * Everything network/spawn/timer-facing is dependency-INJECTABLE so tests never
+ * hit the real clock, spawn a real process, or extract a real binary.
+ */
+
+'use strict';
+
+const path = require('path');
+const fsDefault = require('fs');
+const { spawnSync } = require('child_process');
+
+// No-progress window: if extract-zip reports no new entry for this long AND has
+// not settled, treat it as the silent stall. Reset on every onEntry so a slow-
+// but-progressing extract is never falsely aborted.
+const IDLE_MS = 30_000;
+// Hard cap so a "drips one entry forever" pathology can't run unbounded.
+const MAX_MS = 240_000;
+
+/** PowerShell single-quoted string literal, injection-safe (double any quote). */
+function psQuote(s) {
+  return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Native OS unzip strategies, tried in order per platform. Each writes the
+ * zip's entries at the ROOT of `dir` — the SAME on-disk layout extract-zip
+ * produces (electron.exe, resources/, locales/, ...). Confirmed on the field
+ * box (Expand-Archive) and locally (tar/bsdtar + Expand-Archive, both <1s).
+ * @returns {Array<{name:string, cmd:string, args:string[]}>}
+ */
+function nativeUnzipPlan(zip, dir, platform = process.platform) {
+  if (platform === 'win32') {
+    // ABSOLUTE path to System32 bsdtar (Win10 1803+/11). A bare "tar" resolves
+    // to GNU tar when git-bash/MSYS is on PATH — GNU tar reads "C:\..." as a
+    // remote host ("Cannot connect to C:") and can't read zips at all. path.win32
+    // keeps this a valid Windows path even when the plan is built off-Windows.
+    const winTar = path.win32.join(process.env.SystemRoot || process.env.windir || 'C:\\Windows', 'System32', 'tar.exe');
+    return [
+      // bsdtar — fast, auto-detects zip format. If absent (rare/WOW64), the
+      // spawn errors ENOENT and we fall through to Expand-Archive below.
+      { name: 'tar', cmd: winTar, args: ['-xf', zip, '-C', dir] },
+      // Universal Windows fallback; silence progress so stdio:'ignore' is clean.
+      {
+        name: 'Expand-Archive',
+        cmd: 'powershell',
+        args: ['-NoProfile', '-NonInteractive', '-Command',
+          `$ProgressPreference='SilentlyContinue'; Expand-Archive -LiteralPath ${psQuote(zip)} -DestinationPath ${psQuote(dir)} -Force`],
+      },
+    ];
+  }
+  if (platform === 'darwin') {
+    return [
+      { name: 'ditto', cmd: 'ditto', args: ['-x', '-k', zip, dir] },
+      { name: 'unzip', cmd: 'unzip', args: ['-o', '-q', zip, '-d', dir] },
+    ];
+  }
+  return [
+    { name: 'unzip', cmd: 'unzip', args: ['-o', '-q', zip, '-d', dir] },
+    { name: 'tar', cmd: 'tar', args: ['-xf', zip, '-C', dir] },
+  ];
+}
+
+/** True if `dir` exists and holds at least one entry. */
+function dirNonEmpty(fs, dir) {
+  try {
+    return fs.readdirSync(dir).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Remove everything inside `dir` (best-effort) so the next strategy starts clean. */
+function cleanDir(fs, dir) {
+  try {
+    for (const entry of fs.readdirSync(dir)) {
+      fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Run extract-zip bounded by an idle timer (reset on each onEntry) and a hard
+ * max timer. NEVER rejects — resolves {ok:true} on completion, {ok:false,reason}
+ * on stall/throw. The timers keep the event loop alive so a stalled extract
+ * can't let the process exit 0 before we fall back. NOTE: a stalled extract-zip
+ * promise is abandoned (2.0.1 has no cancel API); it holds a fd until the short-
+ * lived process exits — acceptable versus a wedged, no-op self-heal.
+ */
+function runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, setTimer, clearTimer }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let idleTimer = null;
+    let maxTimer = null;
+    const done = (val) => {
+      if (settled) { return; }
+      settled = true;
+      if (idleTimer !== null) { clearTimer(idleTimer); }
+      if (maxTimer !== null) { clearTimer(maxTimer); }
+      resolve(val);
+    };
+    const armIdle = () => {
+      if (idleTimer !== null) { clearTimer(idleTimer); }
+      idleTimer = setTimer(() => done({ ok: false, reason: `stalled: no extract progress for ${idleMs}ms` }), idleMs);
+    };
+    maxTimer = setTimer(() => done({ ok: false, reason: `stalled: exceeded ${maxMs}ms` }), maxMs);
+    armIdle();
+    try {
+      const result = extractZip(zip, {
+        dir,
+        onEntry: (entry, zipfile) => {
+          armIdle(); // progress → restart the idle window
+          if (onEntry) {
+            try { onEntry(entry, zipfile); } catch { /* caller onEntry must not break extraction */ }
+          }
+        },
+      });
+      Promise.resolve(result).then(
+        () => done({ ok: true }),
+        (e) => done({ ok: false, reason: (e && e.message) || 'extract-zip threw' }),
+      );
+    } catch (e) {
+      done({ ok: false, reason: (e && e.message) || 'extract-zip threw synchronously' });
+    }
+  });
+}
+
+/**
+ * Extract `zip` into `dir`, surviving a stalled or broken extract-zip.
+ *
+ * CONTRACT: a returned {strategy} means files LANDED in `dir` — NOT that any
+ * specific payload (e.g. electron.exe) is present. Callers needing a usable
+ * binary MUST still stat it (electron-quarantine.verifyExtractOutcome does).
+ *
+ * @param {string} zip absolute path to the .zip
+ * @param {object} opts
+ * @param {string}   opts.dir destination dir (created if absent)
+ * @param {function} [opts.onEntry] forwarded to extract-zip's onEntry
+ * @param {string}   [opts.platform] override process.platform (native plan)
+ * @param {number}   [opts.idleMs] no-progress window before treating as stalled
+ * @param {number}   [opts.maxMs] hard cap for both extract-zip and each spawn
+ * @param {object}   [opts.deps] injected { fs, extractZip, spawn, setTimeout, clearTimeout, log }
+ * @returns {Promise<{strategy:string, fallback?:boolean, extractZipReason?:string}>}
+ * @throws {Error} code 'UNZIP_ALL_FAILED' when no strategy produced files.
+ */
+async function robustExtract(zip, opts = {}) {
+  const {
+    dir,
+    onEntry,
+    platform = process.platform,
+    idleMs = IDLE_MS,
+    maxMs = MAX_MS,
+    deps = {},
+  } = opts;
+  const fs = deps.fs || fsDefault;
+  const extractZip = deps.extractZip || require('extract-zip');
+  const spawn = deps.spawn || spawnSync;
+  const setTimer = deps.setTimeout || setTimeout;
+  const clearTimer = deps.clearTimeout || clearTimeout;
+  const log = deps.log || (() => {});
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Strategy 1: extract-zip, bounded. Trust it only if it RESOLVED and files landed.
+  const z = await runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, setTimer, clearTimer });
+  if (z.ok && dirNonEmpty(fs, dir)) {
+    return { strategy: 'extract-zip' };
+  }
+
+  // extract-zip stalled / threw / produced nothing → clean partial output, go native.
+  const zipReason = z.ok ? 'extract-zip produced no files' : z.reason;
+  cleanDir(fs, dir);
+  log(`[amicus] extract-zip did not complete (${zipReason}); falling back to native unzip.`);
+
+  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 });
+    } catch (e) {
+      failures.push(`${strat.name}: spawn ${(e && e.code) || (e && e.message) || 'threw'}`);
+      continue;
+    }
+    // A spawn error OR an external signal-kill (status:null, e.g. SIGKILL/OOM,
+    // possibly leaving partial files) is a FAILURE — never trust dirNonEmpty here.
+    if (res && (res.error || res.signal)) {
+      failures.push(`${strat.name}: ${res.error ? (res.error.code || res.error.message) : `killed by ${res.signal}`}`);
+      cleanDir(fs, dir);
+      continue;
+    }
+    if (res && typeof res.status === 'number' && res.status !== 0) {
+      failures.push(`${strat.name}: exit ${res.status}`);
+      cleanDir(fs, dir);
+      continue;
+    }
+    if (dirNonEmpty(fs, dir)) {
+      log(`[amicus] recovered via native unzip (${strat.name}).`);
+      return { strategy: strat.name, fallback: true, extractZipReason: zipReason };
+    }
+    failures.push(`${strat.name}: produced no files`);
+    cleanDir(fs, dir);
+  }
+
+  const err = new Error(
+    `unzip failed for ${zip} (extract-zip: ${zipReason}; native: ${failures.join('; ') || 'no native strategy available'})`,
+  );
+  err.code = 'UNZIP_ALL_FAILED';
+  throw err;
+}
+
+module.exports = { robustExtract, nativeUnzipPlan, IDLE_MS, MAX_MS };

package/src/utils/auth-json.js

@@ -11,7 +11,43 @@ const os = require('os');
 const path = require('path');
 const { logger } = require('./logger');
 
-const AUTH_JSON_PATH = path.join(os.homedir(), '.local', 'share', 'opencode', 'auth.json');
+/**
+ * Ordered, de-duplicated candidate locations for OpenCode's auth.json, most
+ * specific first. OpenCode uses XDG-style data dirs; on Windows it still writes
+ * to ~/.local/share/opencode (verified), so that path stays FIRST after XDG.
+ * Mirrors the cross-platform precedence pattern in src/sidecar/electron-cache.js.
+ * @param {NodeJS.ProcessEnv} [env] - Environment (injectable for tests)
+ * @returns {string[]}
+ */
+function authJsonCandidates(env = process.env) {
+  const home = os.homedir();
+  const candidates = [];
+  if (env.XDG_DATA_HOME) { candidates.push(path.join(env.XDG_DATA_HOME, 'opencode', 'auth.json')); }
+  candidates.push(path.join(home, '.local', 'share', 'opencode', 'auth.json'));
+  if (process.platform === 'win32') {
+    const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    candidates.push(path.join(appData, 'opencode', 'auth.json'));
+  }
+  return [...new Set(candidates)];
+}
+
+/**
+ * Resolve the auth.json path to use: first existing candidate, else the primary
+ * (~/.local/share) path so callers/writers have a stable default.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+function resolveAuthJsonPath(env = process.env) {
+  const candidates = authJsonCandidates(env);
+  for (const c of candidates) {
+    if (fs.existsSync(c)) { return c; }
+  }
+  const localShare = path.join('.local', 'share');
+  return candidates.find((c) => c.includes(localShare)) || candidates[0];
+}
+
+// Backward-compat export: the resolved path at module load time.
+const AUTH_JSON_PATH = resolveAuthJsonPath();
 
 /** Known provider IDs that map to sidecar's PROVIDER_ENV_MAP */
 const KNOWN_PROVIDERS = ['openrouter', 'google', 'openai', 'anthropic', 'deepseek'];
@@ -37,10 +73,11 @@ function extractKey(entry) {
  * @returns {Object<string, string>} Map of provider -> key string (only providers with keys)
  */
 function readAuthJsonKeys() {
-  if (!fs.existsSync(AUTH_JSON_PATH)) { return {}; }
+  const authPath = resolveAuthJsonPath();
+  if (!fs.existsSync(authPath)) { return {}; }
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(AUTH_JSON_PATH, 'utf-8'));
+    parsed = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
   } catch (_err) {
     logger.debug('auth.json is malformed, skipping import');
     return {};
@@ -89,11 +126,12 @@ function checkAuthJson(provider) {
  */
 function removeFromAuthJson(provider) {
   try {
-    if (!fs.existsSync(AUTH_JSON_PATH)) { return; }
-    const parsed = JSON.parse(fs.readFileSync(AUTH_JSON_PATH, 'utf-8'));
+    const authPath = resolveAuthJsonPath();
+    if (!fs.existsSync(authPath)) { return; }
+    const parsed = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
     if (!parsed[provider]) { return; }
     delete parsed[provider];
-    fs.writeFileSync(AUTH_JSON_PATH, JSON.stringify(parsed, null, 2), 'utf-8');
+    fs.writeFileSync(authPath, JSON.stringify(parsed, null, 2), 'utf-8');
   } catch (_err) {
     logger.debug('Failed to remove provider from auth.json', { provider });
   }
@@ -105,5 +143,7 @@ module.exports = {
   checkAuthJson,
   removeFromAuthJson,
   AUTH_JSON_PATH,
-  KNOWN_PROVIDERS
+  KNOWN_PROVIDERS,
+  resolveAuthJsonPath,
+  authJsonCandidates
 };