amicus 3.1.1 → 3.2.1

package/src/utils/config.js

@@ -419,6 +419,60 @@ function markMigrationNotified(vendor) {
   }
 }
 
+/**
+ * Existing-user one-time onboarding offer (Part 2, Task 9). Mirrors
+ * markMigrationNotified's flag pattern: a single boolean persisted at
+ * config.routing.tier_onboarded once the notice has fired, so it never
+ * repeats.
+ * @returns {boolean} true once the notice has fired
+ */
+function hasTierOnboarded() {
+  const config = loadConfig() || {};
+  return !!(config.routing && config.routing.tier_onboarded === true);
+}
+
+/**
+ * Persist the one-time onboarding-notice flag, preserving any other routing
+ * keys (prefer, tier, migration_notified). Best-effort: swallows any
+ * saveConfig failure so a persistence hiccup never breaks the command that
+ * triggered it (mirrors markMigrationNotified).
+ */
+function markTierOnboarded() {
+  try {
+    const config = loadConfig() || {};
+    if (!config.routing || typeof config.routing !== 'object') { config.routing = {}; }
+    config.routing.tier_onboarded = true;
+    saveConfig(config);
+  } catch (_err) {
+    // best-effort: never fail the command over a persistence error
+  }
+}
+
+/** Global cost-tier preference (Part 2, Task 1) — priciest-to-cheapest. */
+const COST_TIERS = ['frontier', 'balanced', 'economy'];
+
+/** @returns {'frontier'|'balanced'|'economy'} config.routing.tier, defaulting/coercing to 'balanced' */
+function getCostTier() {
+  const config = loadConfig() || {};
+  const tier = config.routing && config.routing.tier;
+  return COST_TIERS.includes(tier) ? tier : 'balanced';
+}
+
+/**
+ * Persist the global cost-tier preference under routing.tier, preserving any
+ * other routing keys (prefer, migration_notified).
+ * @param {string} tier one of COST_TIERS
+ * @throws {Error} when tier is not a recognized cost tier
+ */
+function setCostTier(tier) {
+  if (!COST_TIERS.includes(tier)) {
+    throw new Error(`Invalid cost tier '${tier}'. Must be one of: ${COST_TIERS.join(', ')}`);
+  }
+  const config = loadConfig() || {};
+  config.routing = { ...(config.routing || {}), tier };
+  saveConfig(config);
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -440,4 +494,9 @@ module.exports = {
   getRoutingConfig,
   resolveGatewayMode,
   markMigrationNotified,
+  COST_TIERS,
+  getCostTier,
+  setCostTier,
+  hasTierOnboarded,
+  markTierOnboarded,
 };

package/src/utils/curated-models.js

@@ -160,8 +160,10 @@ function listCuratedRoutes() {
  * versioning, distinct model names, etc.). NEVER derive a direct form for
  * these — derivation would emit the wrong (dot) id, or invent a direct id
  * for a model that is OpenRouter-only today (e.g. fable).
+ * Frozen so consumers can only read it (`.has()`) — a frozen Set still
+ * supports lookups, it just can't be `.add()`/`.delete()`/`.clear()`-ed.
  */
-const DIVERGENT_VENDORS = new Set(['anthropic']);
+const DIVERGENT_VENDORS = Object.freeze(new Set(['anthropic']));
 
 /**
  * @param {string} orRoute e.g. 'openrouter/anthropic/claude-sonnet-5'
@@ -212,5 +214,5 @@ function toGatewayRoutes() {
 }
 
 module.exports = {
-  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes
+  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes, DIVERGENT_VENDORS
 };

package/src/utils/doctor-engine-check.js

@@ -0,0 +1,71 @@
+/**
+ * @module utils/doctor-engine-check
+ * The `engine-mcp` doctor check ("OpenCode engine (MCP launch path)"), split out
+ * of src/cli-handlers-doctor.js to keep that file under the 300-line gate
+ * (mirrors doctor-mcp-checks.js).
+ *
+ * The existing `opencode-bin` check verifies the engine in the RUNNING install.
+ * This one verifies the copies the MCP actually launches from — the npx-cache
+ * installs `npx -y amicus@latest mcp` resolves to — so a green doctor can no
+ * longer hide a broken npx copy (bug report #1). Reporting only; no self-heal.
+ */
+
+'use strict';
+
+const HINTS = require('./remediation-hints');
+
+const plural = (n, one, many) => (n === 1 ? one : many);
+
+/**
+ * @param {{scanEngineInstalls: () => {installs:Array, mcpLaunch:string}}} d
+ * @returns {{id,name,status,message,hint}}
+ */
+function evaluateEngineInstalls(d) {
+  const id = 'engine-mcp';
+  const name = 'OpenCode engine (MCP launch path)';
+  const { installs, mcpLaunch } = d.scanEngineInstalls();
+
+  if (mcpLaunch === 'none') {
+    return { id, name, status: 'ok', message: 'no amicus MCP registered — not checked', hint: null };
+  }
+  if (mcpLaunch === 'path') {
+    return {
+      id, name, status: 'ok',
+      message: 'MCP launches from a fixed path — covered by the OpenCode binary check', hint: null,
+    };
+  }
+
+  // 'npx' (and the 'unknown' fallback): verify the npx-cache copies, the ones
+  // subject to optional-dependency skips and AV quarantine on every re-resolve.
+  const npxCopies = installs.filter((i) => i.kind === 'npx');
+  if (npxCopies.length === 0) {
+    return {
+      id, name, status: 'warn',
+      message: 'MCP launches via npx; no cached copy to inspect yet — run one fanout, then re-run doctor',
+      hint: null,
+    };
+  }
+
+  const broken = npxCopies.filter((i) => !i.engineOk);
+  if (broken.length === 0) {
+    return {
+      id, name, status: 'ok',
+      message: `engine present in ${npxCopies.length} npx-cache ${plural(npxCopies.length, 'copy', 'copies')}`,
+      hint: null,
+    };
+  }
+
+  const detail = broken
+    .map((i) => `${i.pkgDir} (searched: ${(i.roots || []).join(', ')})`)
+    .join('; ');
+  // Exactly one npx copy and it is broken → unambiguous: that IS the copy the
+  // MCP will launch, and every call will fail. Elsewhere the hash npx selects is
+  // ambiguous, so warn (still naming the exact broken path) rather than error.
+  const status = npxCopies.length === 1 ? 'error' : 'warn';
+  const lead = status === 'error'
+    ? 'engine missing from the npx-cache copy the MCP launches'
+    : `engine missing from ${broken.length}/${npxCopies.length} npx-cache copies`;
+  return { id, name, status, message: `${lead}: ${detail}`, hint: HINTS.reinstallEngineAv };
+}
+
+module.exports = { evaluateEngineInstalls };

package/src/utils/engine-install-scan.js

@@ -0,0 +1,142 @@
+/**
+ * @module utils/engine-install-scan
+ * Discover + probe every amicus install that could serve the MCP (running,
+ * global, npx-cache), so `amicus doctor` verifies the copy the MCP actually
+ * launches — not just the copy doctor happens to run from.
+ *
+ * The MCP is registered as `npx -y amicus@latest mcp` (scripts/postinstall.js),
+ * so it runs from an npx-cache copy, while `amicus doctor` typically inspects the
+ * global install on PATH. When those diverge, doctor can report the engine
+ * "found" (global) while the npx copy the MCP launches is broken and every call
+ * fails — the bug report's green-while-broken defect (#1). This enumerates
+ * running + global + each npx-cache copy and probes the opencode engine in each
+ * via the #69 dual-root resolver.
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+/** Default npm cache dir: %LocalAppData%/npm-cache on win32, else ~/.npm. */
+function defaultNpmCacheDir(platform) {
+  if (platform === 'win32') {
+    const local = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(local, 'npm-cache');
+  }
+  return path.join(os.homedir(), '.npm');
+}
+
+/** Best-effort `npm root -g`. Never throws; returns null on any failure. */
+function defaultNpmRootG() {
+  try {
+    const { execFileSync } = require('child_process');
+    const out = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return String(out).trim() || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Run fn, swallowing any throw and returning fallback. */
+function safe(fn, fallback) {
+  try { return fn(); } catch (_e) { return fallback; }
+}
+
+/** Drop installs whose pkgDir resolves to the same real path; keep the first. */
+function dedupByRealpath(installs, fs) {
+  const seen = new Set();
+  const out = [];
+  for (const inst of installs) {
+    const real = safe(() => fs.realpathSync(inst.pkgDir), inst.pkgDir);
+    const key = path.normalize(real);
+    if (seen.has(key)) { continue; }
+    seen.add(key);
+    out.push(inst);
+  }
+  return out;
+}
+
+/**
+ * The amicus installs that could serve the MCP, highest-priority first
+ * (running, global, then npx-cache copies). All I/O behind seams.
+ *
+ * @param {object} [deps]
+ * @param {object} [deps.fs] - fs module (existsSync/readdirSync/realpathSync)
+ * @param {string} [deps.platform] - process.platform override
+ * @param {string} [deps.runningPkgDir] - this process's amicus package root
+ * @param {string} [deps.npmCacheDir] - npm cache dir holding _npx/
+ * @param {() => (string|null)} [deps.npmRootG] - resolver for `npm root -g`
+ * @returns {Array<{kind:string, pkgDir:string}>}
+ */
+function listAmicusInstalls(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const platform = deps.platform || process.platform;
+  const runningPkgDir = deps.runningPkgDir || path.join(__dirname, '..', '..');
+  const npmCacheDir = deps.npmCacheDir || defaultNpmCacheDir(platform);
+  const npmRootG = deps.npmRootG || defaultNpmRootG;
+
+  const raw = [{ kind: 'running', pkgDir: runningPkgDir }];
+
+  // Global — best-effort; `npm root -g` → <root>/amicus. Never fails the scan.
+  const gRoot = safe(() => npmRootG(), null);
+  if (gRoot) {
+    const gDir = path.join(gRoot, 'amicus');
+    if (safe(() => fs.existsSync(gDir), false)) {
+      raw.push({ kind: 'global', pkgDir: gDir });
+    }
+  }
+
+  // npx caches — <cache>/_npx/<hash>/node_modules/amicus for each hash present.
+  const npxRoot = path.join(npmCacheDir, '_npx');
+  for (const hash of safe(() => fs.readdirSync(npxRoot), [])) {
+    const pkgDir = path.join(npxRoot, hash, 'node_modules', 'amicus');
+    if (safe(() => fs.existsSync(pkgDir), false)) {
+      raw.push({ kind: 'npx', pkgDir });
+    }
+  }
+
+  return dedupByRealpath(raw, fs);
+}
+
+/**
+ * Classify the MCP launch method from the amicus registration config.
+ * @param {{command?:string, args?:unknown[]}|null|undefined} config
+ * @returns {'npx'|'path'|'none'|'unknown'}
+ */
+function classifyLaunch(config) {
+  const { isAmicusMcpConfig, normalizeToken } = require('./mcp-self-identity');
+  if (!config || typeof config !== 'object') { return 'none'; }
+  if (config.command && normalizeToken(config.command) === 'npx') { return 'npx'; }
+  if (isAmicusMcpConfig(config)) { return 'path'; }
+  return 'unknown';
+}
+
+/**
+ * Enumerate serving installs, probe the engine in each, and classify how the
+ * MCP launches.
+ *
+ * @param {object} [deps] - listAmicusInstalls seams, plus:
+ * @param {(d:{pkgDir:string}) => boolean} [deps.hasOpencodeBinary]
+ * @param {(d:{pkgDir:string}) => string[]} [deps.opencodeRoots]
+ * @param {() => (object|null)} [deps.readAmicusMcpConfig]
+ * @returns {{installs: Array<{kind,pkgDir,engineOk,roots}>, mcpLaunch: string}}
+ */
+function scanEngineInstalls(deps = {}) {
+  const hasOpencodeBinary = deps.hasOpencodeBinary || require('./path-setup').hasOpencodeBinary;
+  const opencodeRoots = deps.opencodeRoots || require('./path-setup').opencodeRoots;
+  const readAmicusMcpConfig = deps.readAmicusMcpConfig
+    || (() => require('./mcp-discovery').readAmicusMcpConfig());
+
+  const installs = listAmicusInstalls(deps).map((i) => ({
+    ...i,
+    engineOk: !!hasOpencodeBinary({ pkgDir: i.pkgDir }),
+    roots: opencodeRoots({ pkgDir: i.pkgDir }),
+  }));
+  const mcpLaunch = classifyLaunch(safe(() => readAmicusMcpConfig(), null));
+  return { installs, mcpLaunch };
+}
+
+module.exports = { listAmicusInstalls, scanEngineInstalls, classifyLaunch };

package/src/utils/mcp-discovery.js

@@ -226,6 +226,32 @@ function discoverCoworkMcps(configDir) {
   }
 }
 
+/**
+ * The RAW amicus MCP registration config (never stripped) from either client —
+ * the first entry keyed 'amicus' or whose command/args resolve to an amicus MCP
+ * launch (isAmicusMcpConfig). Used by the doctor engine-scan to classify HOW the
+ * MCP launches (npx vs a fixed path). Distinct from hasAmicusRegistration (which
+ * returns only a boolean and reads Claude Code alone).
+ *
+ * @param {string} [claudeDir] - ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - ~/.claude.json path (for testing)
+ * @param {string} [coworkConfigDir] - Claude Desktop config dir (for testing)
+ * @returns {object|null} The amicus server config, or null if none is registered
+ */
+function readAmicusMcpConfig(claudeDir, claudeJsonPath, coworkConfigDir) {
+  const sources = [
+    readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath),
+    discoverCoworkMcps(coworkConfigDir),
+  ];
+  for (const servers of sources) {
+    if (!servers || typeof servers !== 'object') { continue; }
+    for (const [name, config] of Object.entries(servers)) {
+      if (name === 'amicus' || isAmicusMcpConfig(config)) { return config; }
+    }
+  }
+  return null;
+}
+
 /**
  * Discover MCP servers from the parent LLM's configuration.
  *
@@ -248,5 +274,6 @@ module.exports = {
   discoverClaudeCodeMcps,
   discoverCoworkMcps,
   hasAmicusRegistration,
+  readAmicusMcpConfig,
   normalizeMcpJson
 };

package/src/utils/model-tiers.js

@@ -0,0 +1,120 @@
+/**
+ * Per-vendor cost tiers (economy/balanced/frontier) + resolution against the
+ * live model catalog.
+ *
+ * Tier ordering: frontier = MOST expensive/capable, economy = CHEAPEST,
+ * balanced = the middle ground.
+ *
+ * Mirrors quick-picks.pickCurrent's "newest live-catalog id matching a
+ * pattern in a vendor namespace" approach rather than reinventing it: each
+ * tier's regex is matched over the model segment in BOTH the direct
+ * namespace (`<vendor>/<model>`) and the OpenRouter namespace
+ * (`openrouter/<vendor>/<model>`); the direct-namespace pick wins when both
+ * exist, since storage is direct-first (see gateway-router.js).
+ *
+ * Gateway-only vendors (no direct API integration — provider-registry
+ * `isDirectProvider` false) have no tier regexes here: OpenRouter is their
+ * only route, and curated-models' CARDLESS/family-fallback entries don't
+ * carry a per-alias match pattern the way FAMILIES does, so there is no
+ * live-catalog rule to reuse for them. All three tiers resolve to the same
+ * curated flagship — the static canonical pin `toDefaultAliases()` already
+ * maintains for that vendor's alias (the same pin `resolveQuickPicks` falls
+ * back to when live resolution is unavailable).
+ */
+
+'use strict';
+
+const { pickCurrent } = require('./quick-picks');
+const { isDirectProvider } = require('./provider-registry');
+const { toDefaultAliases, listCuratedRoutes } = require('./curated-models');
+
+/** Tier regex table: pattern matches the model segment after `<vendor>/` (or `openrouter/<vendor>/`). */
+const TIERS = {
+  anthropic: {
+    economy: /^claude-haiku-/,
+    balanced: /^claude-sonnet-/,
+    frontier: /^claude-opus-/,
+  },
+  openai: {
+    economy: /^gpt-[\d.]+-mini$/,
+    balanced: /^gpt-[\d.]+$/,
+    frontier: /^gpt-[\d.]+-pro$/,
+  },
+  google: {
+    economy: /^gemini-[\d.]+-flash-lite/,
+    balanced: /^gemini-[\d.]+-flash(?!-lite)/,
+    frontier: /^gemini-[\d.]+-pro/,
+  },
+  deepseek: {
+    economy: /^deepseek-v[\d.]+$/,
+    balanced: /^deepseek-v[\d.]+$/,
+    frontier: /^deepseek-v[\d.]+-pro$/,
+  },
+};
+
+/** Fallback preference order when the requested tier's pattern matches nothing. */
+const TIER_ORDER = ['economy', 'balanced', 'frontier'];
+
+/**
+ * vendor -> curated alias, for vendors with no direct integration and no
+ * TIERS entry. Built once from curated-models' OpenRouter-routed entries;
+ * the first alias found per vendor wins (e.g. 'qwen' over its
+ * 'qwen-coder'/'qwen-flash' siblings, since CARDLESS lists it first).
+ * @returns {Object<string,string>}
+ */
+function buildGatewayOnlyAliasMap() {
+  const map = {};
+  for (const { alias, provider, model } of listCuratedRoutes()) {
+    if (provider !== 'openrouter' || !model.startsWith('openrouter/')) { continue; }
+    const rest = model.slice('openrouter/'.length); // '<vendor>/<rest...>'
+    const slash = rest.indexOf('/');
+    const vendor = slash > 0 ? rest.slice(0, slash) : null;
+    if (!vendor || isDirectProvider(vendor) || TIERS[vendor] || map[vendor]) { continue; }
+    map[vendor] = alias;
+  }
+  return map;
+}
+
+const GATEWAY_ONLY_ALIAS = buildGatewayOnlyAliasMap();
+
+/** Newest catalog id matching `regex` under `vendor`; direct namespace preferred over OpenRouter's. */
+function pickForTier(catalog, vendor, regex) {
+  return pickCurrent(catalog, '', vendor, regex) || pickCurrent(catalog, 'openrouter/', vendor, regex);
+}
+
+/** True when the catalog has ANY row (any tier) under this vendor's namespace, in either gateway. */
+function vendorHasModels(catalog, vendor) {
+  return Boolean(pickForTier(catalog, vendor, /./));
+}
+
+/**
+ * @param {string} vendor
+ * @param {'economy'|'balanced'|'frontier'} tier
+ * @param {Array<{id:string}>} catalog
+ * @returns {string|null} current live-catalog full id for vendor+tier
+ *   (e.g. `anthropic/claude-sonnet-5`), or null when the vendor is unknown
+ *   or absent from the catalog.
+ */
+function resolveTier(vendor, tier, catalog) {
+  if (typeof vendor !== 'string' || !vendor) { return null; }
+  if (!TIER_ORDER.includes(tier)) { return null; }
+
+  const gatewayAlias = GATEWAY_ONLY_ALIAS[vendor];
+  if (gatewayAlias) { return toDefaultAliases()[gatewayAlias] || null; }
+
+  const table = TIERS[vendor];
+  if (!table) { return null; }
+
+  const direct = pickForTier(catalog, vendor, table[tier]);
+  if (direct) { return direct; }
+
+  if (!vendorHasModels(catalog, vendor)) { return null; }
+
+  for (const t of TIER_ORDER) {
+    const pick = pickForTier(catalog, vendor, table[t]);
+    if (pick) { return pick; }
+  }
+  return null;
+}
+
+module.exports = { TIERS, resolveTier };

package/src/utils/path-setup.js

@@ -1,39 +1,84 @@
 const path = require('path');
 const os = require('os');
 
+/**
+ * The node_modules roots that may hold the opencode engine sub-packages.
+ *
+ * npm only NESTS a dependency under <pkg>/node_modules when it cannot hoist it.
+ * `npm i -g amicus` nests opencode-windows-*; `npx -y amicus@latest` — which is
+ * exactly how postinstall registers the MCP server — HOISTS it to a sibling of
+ * amicus/, leaving <pkg>/node_modules nonexistent. Both are valid installs, so
+ * probe both roots rather than assuming a layout. Assuming the nested one made a
+ * present, runnable engine read as missing and threw engineMissing on every
+ * fanout leg under npx (#69).
+ *
+ * Order is search priority: nested (amicus's own copy) before hoisted.
+ *
+ * @param {object} [deps] - test seams
+ * @param {string} [deps.nodeModulesRoot] - exact root override (wins outright)
+ * @param {string} [deps.pkgDir] - amicus package dir override
+ * @returns {string[]} candidate node_modules roots
+ */
+function opencodeRoots(deps = {}) {
+  if (deps.nodeModulesRoot) {
+    return [deps.nodeModulesRoot];
+  }
+  const pkgDir = deps.pkgDir || path.join(__dirname, '..', '..');
+  return [
+    path.join(pkgDir, 'node_modules'), // nested  — npm i -g
+    path.dirname(pkgDir), // hoisted — npx/pnpm: the node_modules holding amicus
+  ];
+}
+
 /**
  * Ensures that the project's node_modules/.bin directory is included in the PATH,
  * and on Windows also adds the platform-specific native opencode binary directory
  * so that `spawn('opencode', ...)` without shell:true can resolve the .exe.
  * The OpenCode SDK spawns the 'opencode' command, and this ensures it can be found.
+ * Walks every candidate root so hoisted installs resolve too (#69).
+ *
+ * PATH is a first-match search, so the array below IS the priority order — built
+ * highest-priority-first, then prepended as ONE group. Two orderings matter and
+ * both were once inverted by prepending one dir at a time (LIFO reverses intent):
+ *   - default (AVX2) before -baseline: an AVX2 machine must run the fast build,
+ *     with baseline only as the older-CPU fallback.
+ *   - every native .exe dir before any .bin: on Windows .bin holds a .cmd shim
+ *     that bare spawn() cannot execute, so a real .exe must always win — even a
+ *     .exe in the other candidate root beats a shim in this one.
+ * Hence the three tiers: all defaults, then all baselines, then all .bin — each
+ * tier spanning every root in opencodeRoots() priority order.
+ *
+ * @param {object} [deps] - test seams, forwarded to opencodeRoots()
+ * @param {string} [deps.nodeModulesRoot] - exact root override (wins outright)
+ * @param {string} [deps.pkgDir] - amicus package dir override
  */
-function ensureNodeModulesBinInPath() {
-  const nodeModulesRoot = path.join(__dirname, '..', '..', 'node_modules');
-  const nodeModulesBin = path.join(nodeModulesRoot, '.bin');
+function ensureNodeModulesBinInPath(deps = {}) {
+  const roots = opencodeRoots(deps);
+  const dirs = [];
 
-  if (!process.env.PATH.includes(nodeModulesBin)) {
-    process.env.PATH = `${nodeModulesBin}${path.delimiter}${process.env.PATH}`;
-  }
-
-  // On Windows, Node's spawn() does not execute .cmd shims without shell:true.
-  // Add the platform-specific native binary directory so `opencode` resolves
-  // to opencode.exe directly (Windows searches PATHEXT-aware when .exe is present).
   if (os.platform() === 'win32') {
     const archMap = { x64: 'x64', arm64: 'arm64' };
     const arch = archMap[os.arch()] || os.arch();
-    const nativeBin = path.join(nodeModulesRoot, `opencode-windows-${arch}`, 'bin');
-    if (!process.env.PATH.includes(nativeBin)) {
-      process.env.PATH = `${nativeBin}${path.delimiter}${process.env.PATH}`;
+    // Tier 1: default (AVX2) build in every root.
+    for (const root of roots) {
+      dirs.push(path.join(root, `opencode-windows-${arch}`, 'bin'));
     }
-    // Baseline variant: the default build needs AVX2; opencode ships a
-    // -baseline (pre-AVX2) build for older CPUs. Windows resolves the first
-    // PATH entry containing a real opencode.exe, so default-before-baseline
-    // order matters — do not delete this block as "dead code".
-    const nativeBinBaseline = path.join(nodeModulesRoot, `opencode-windows-${arch}-baseline`, 'bin');
-    if (!process.env.PATH.includes(nativeBinBaseline)) {
-      process.env.PATH = `${nativeBinBaseline}${path.delimiter}${process.env.PATH}`;
+    // Tier 2: -baseline (pre-AVX2) fallback in every root — searched only after
+    // every default build. Do not delete these entries as "dead code".
+    for (const root of roots) {
+      dirs.push(path.join(root, `opencode-windows-${arch}-baseline`, 'bin'));
     }
   }
+  // Tier 3: node_modules/.bin in every root, last (its shims spawn() cannot run).
+  for (const root of roots) {
+    dirs.push(path.join(root, '.bin'));
+  }
+
+  // Prepend the not-yet-present dirs as one group, preserving the order above.
+  const missing = dirs.filter((dir) => !process.env.PATH.includes(dir));
+  if (missing.length > 0) {
+    process.env.PATH = `${missing.join(path.delimiter)}${path.delimiter}${process.env.PATH}`;
+  }
 }
 
 /**
@@ -48,6 +93,8 @@ function ensureNodeModulesBinInPath() {
  *
  * Mirrors the PATH resolution order: on Windows the platform sub-package (and
  * its -baseline variant) bin/opencode.exe; elsewhere node_modules/.bin/opencode.
+ * Probes every candidate root (nested AND hoisted — see opencodeRoots), so a
+ * layout npm chose for us can never masquerade as a missing engine (#69).
  * Never throws — a probe failure reads as not-found.
  *
  * @param {object} [deps] - test seams
@@ -55,19 +102,24 @@ function ensureNodeModulesBinInPath() {
  * @param {string} [deps.platform] - process.platform override
  * @param {string} [deps.arch] - os.arch() override
  * @param {string} [deps.nodeModulesRoot] - node_modules root override
+ * @param {string} [deps.pkgDir] - amicus package dir override
  * @returns {boolean} true only when a real opencode binary resolves on disk
  */
 function hasOpencodeBinary(deps = {}) {
   const fs = deps.fs || require('fs');
   const platform = deps.platform || process.platform;
   const arch = deps.arch || os.arch();
-  const root = deps.nodeModulesRoot || path.join(__dirname, '..', '..', 'node_modules');
 
   const a = arch === 'arm64' ? 'arm64' : 'x64';
-  const candidates = platform === 'win32'
-    ? [path.join(root, `opencode-windows-${a}`, 'bin', 'opencode.exe'),
-       path.join(root, `opencode-windows-${a}-baseline`, 'bin', 'opencode.exe')]
-    : [path.join(root, '.bin', 'opencode')];
+  const candidates = [];
+  for (const root of opencodeRoots(deps)) {
+    if (platform === 'win32') {
+      candidates.push(path.join(root, `opencode-windows-${a}`, 'bin', 'opencode.exe'));
+      candidates.push(path.join(root, `opencode-windows-${a}-baseline`, 'bin', 'opencode.exe'));
+    } else {
+      candidates.push(path.join(root, '.bin', 'opencode'));
+    }
+  }
 
   return candidates.some((p) => { try { return fs.existsSync(p); } catch (_e) { return false; } });
 }
@@ -75,4 +127,5 @@ function hasOpencodeBinary(deps = {}) {
 module.exports = {
   ensureNodeModulesBinInPath,
   hasOpencodeBinary,
+  opencodeRoots,
 };