amicus 4.3.0 → 4.4.1

package/src/sidecar/fanout-signals.js

@@ -0,0 +1,61 @@
+// src/sidecar/fanout-signals.js
+'use strict';
+
+/**
+ * @module fanout-signals
+ * A fan-out wave's signal-abort handler, extracted from fanout.js for the
+ * 300-line size gate (v4.4.1 fix wave, finding F3 needed room in fanout.js).
+ * Pure move plus the force-exit reaper described below — same markers, same
+ * ordering, same watchdog window.
+ *
+ * The contract fanout.js relies on: mark the wave and every leg aborted, then
+ * let NORMAL control flow finalize. Legs see their abort marker within one poll
+ * (~2s) and settle, so the caller still writes wave.json and emits a parseable
+ * aborted document. The force-exit watchdog is only a backstop for a wedged leg.
+ */
+
+const { logger } = require('../utils/logger');
+const { installSignalAbort, markAborted } = require('../utils/session-abort');
+const { armExitWatchdog, exitReaping } = require('../utils/lifecycle');
+
+/** Force-exit backstop window; comfortably outlives close()'s ~2s escalation. */
+const WAVE_FORCE_EXIT_MS = 10000;
+
+/**
+ * @param {{waveId: string, waveDir: string, legDirs: string[], server: object,
+ *   externalServer: boolean}} args
+ * @returns {{uninstall: Function, signal: () => (string|null)}} `signal()` is a
+ *   GETTER — the handler mutates it between awaits, so a snapshot would miss it.
+ */
+function installWaveAbort({ waveId, waveDir, legDirs, server, externalServer }) {
+  let signalled = null;
+  const uninstall = installSignalAbort({
+    onAbort: (signal) => {
+      const code = signal === 'SIGINT' ? 130 : 143;
+      if (signalled) { process.exit(code); } // second signal: exit NOW
+      signalled = signal;
+      logger.warn('Signal received — aborting wave', { waveId, signal });
+      markAborted(waveDir, signal);
+      for (const dir of legDirs) { markAborted(dir, signal); }
+      // close() is async (B06 escalation); this handler stays sync, so
+      // fire-and-forget with a rejection guard.
+      // ⚠️ close site 1 of 2 — NEVER an injected server: it belongs to the
+      // council run, whose own signal handler tears it down in finalize().
+      // Closing it here would kill every sibling and later wave in the run.
+      if (!externalServer) { try { server.close().catch(() => {}); } catch { /* best-effort */ } }
+      // ⚠️ …but a FORCE exit must not orphan it either (F3). We no longer close
+      // an injected server above, so if this watchdog fires before the owner's
+      // finalize() runs, the OpenCode process outlives the parent — still
+      // holding the SQLite lock this whole task exists to stop contending on.
+      // exitReaping SIGTERMs its Go pid on the way out. An OWNED server needs
+      // no hook: close() above already signalled it.
+      armExitWatchdog(code, WAVE_FORCE_EXIT_MS, {
+        log: (m, meta) => logger.debug(m, meta),
+        ...(externalServer ? { exit: exitReaping(server) } : {}),
+      });
+    },
+  });
+  return { uninstall, signal: () => signalled };
+}
+
+module.exports = { installWaveAbort, WAVE_FORCE_EXIT_MS };

package/src/sidecar/fanout-wave-io.js

@@ -0,0 +1,75 @@
+// src/sidecar/fanout-wave-io.js
+'use strict';
+
+/**
+ * @module fanout-wave-io
+ * On-disk lifecycle of a WAVE document, split out of fanout.js to keep that
+ * file under the 300-line gate (v4.4.1 Task 0.5, which needed room for the
+ * external-server seam). Pure move — same writes, same order, same atomicity:
+ *
+ *   writeWaveMetadata  metadata.json read-merge-write, abort-wins
+ *   writeWaveDoc       wave.json, atomic (tmp + rename)
+ *   finishWave         the terminal path every completed wave funnels through:
+ *                      persist → checkpoint metadata → emit wave-terminal →
+ *                      fire --on-complete → print
+ *
+ * `finishWave` had two byte-identical copies in fanout.js (the all-legs-failed-
+ * to-route short circuit and the normal aggregation); they are one function here
+ * so a future change to the terminal contract cannot land on only one of them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { writeFileAtomic } = require('../utils/atomic-write');
+
+/**
+ * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
+ * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
+ * to a softer status (same precedence rule as writeLegPatch — a signal/abort
+ * marker must never lose a write race against an in-flight init/finalize).
+ */
+function writeWaveMetadata(waveDir, patch) {
+  const metaPath = path.join(waveDir, 'metadata.json');
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
+  }
+  const safePatch = { ...patch };
+  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
+    delete safePatch.status;
+  }
+  const merged = { ...existing, ...safePatch };
+  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  return merged;
+}
+
+/**
+ * Persist a wave document atomically (tmp + rename).
+ * @returns {string} the wave.json path
+ */
+function writeWaveDoc(waveDir, wave) {
+  const wavePath = path.join(waveDir, 'wave.json');
+  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
+  return wavePath;
+}
+
+/**
+ * Terminal path for a wave that produced leg documents: persist wave.json,
+ * checkpoint metadata.json, emit wave-terminal, fire --on-complete, print.
+ * @param {{wave: object, waveDir: string, waveId: string, project: string,
+ *   exitCode: number, completedAt: string, follow: object|null, emit: Function,
+ *   onComplete?: string, onCompleteDeps?: object}} args
+ * @returns {Promise<{wave: object, exitCode: number}>}
+ */
+async function finishWave({ wave, waveDir, waveId, project, exitCode, completedAt, follow, emit, onComplete, onCompleteDeps }) {
+  const { emitWaveTerminal } = require('../observe/events');
+  const wavePath = writeWaveDoc(waveDir, wave);
+  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
+  emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode }, follow);
+  await require('../observe/on-complete').fireWaveOnComplete(onComplete, wave,
+    { waveId, waveDir, wavePath, exitCode, project }, onCompleteDeps);
+  emit(wave);
+  return { wave, exitCode };
+}
+
+module.exports = { writeWaveMetadata, writeWaveDoc, finishWave };

package/src/sidecar/fanout.js

@@ -16,7 +16,10 @@ const { logger } = require('../utils/logger');
 const { runLeg, buildRoutingFailureLeg } = require('./fanout-leg');
 const { parseModelsList, DEFAULT_MAX_LEGS, validateFanoutModels } = require('./fanout-validate');
 const { ERROR_CODES } = require('../utils/error-doc');
-const { writeFileAtomic } = require('../utils/atomic-write');
+// Wave-document persistence lives in ./fanout-wave-io (size-gate split, v4.4.1
+// Task 0.5). writeWaveMetadata is re-exported below — fanout-retry.js and the
+// fanout tests import it from here.
+const { writeWaveMetadata, writeWaveDoc, finishWave } = require('./fanout-wave-io');
 
 /**
  * Derive leg task IDs: <waveId>-1 .. <waveId>-N (matches TASK_ID_PATTERN).
@@ -28,27 +31,6 @@ function deriveLegIds(waveId, count) {
   return Array.from({ length: count }, (_, i) => `${waveId}-${i + 1}`);
 }
 
-/**
- * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
- * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
- * to a softer status (same precedence rule as writeLegPatch — a signal/abort
- * marker must never lose a write race against an in-flight init/finalize).
- */
-function writeWaveMetadata(waveDir, patch) {
-  const metaPath = path.join(waveDir, 'metadata.json');
-  let existing = {};
-  if (fs.existsSync(metaPath)) {
-    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
-  }
-  const safePatch = { ...patch };
-  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
-    delete safePatch.status;
-  }
-  const merged = { ...existing, ...safePatch };
-  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
-  return merged;
-}
-
 /**
  * Run a fan-out wave. Spec §4.3.
  * @param {object} options - models, prompt, promptMeta, waveId?, project, agent?,
@@ -59,7 +41,11 @@ function writeWaveMetadata(waveDir, patch) {
  *   with routing.prefer, applied per leg), json?, client?, quiet? (suppress
  *   stdout — tests), councilRunId? / councilName? (v4.3 §7.2: stamped onto legs),
  *   fallback? / catalog? (v4.3 Task 18 §6.2: opt-in substitution; off/absent unchanged),
- *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical)
+ *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical),
+ *   server? + serverClient? (v4.4.1 Task 0.5: an ALREADY-STARTED OpenCode server
+ *     to run this wave's legs on. Both or neither. When supplied this wave never
+ *     starts a server and never closes one — see the seam comment in step 4.
+ *     NOT `client`, which is the client TYPE string on this function.)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -70,9 +56,9 @@ async function runFanout(options) {
   const { buildContext } = require('./context-builder');
   const { buildPrompts } = require('../prompt-builder');
   const { generateFoldNonce } = require('../utils/fold-marker');
-  const { installSignalAbort, markAborted } = require('../utils/session-abort');
+  const { installWaveAbort } = require('./fanout-signals');
   const { getSessionDir } = require('../session-manager');
-  const { emitWaveStarted, emitWaveTerminal } = require('../observe/events');
+  const { emitWaveStarted } = require('../observe/events'); // wave-terminal is emitted by finishWave
 
   const project = options.project || process.cwd();
   const createdAt = new Date().toISOString();
@@ -88,9 +74,17 @@ async function runFanout(options) {
       console.log(formatWaveHuman(doc));
     }
   };
-  const errorWave = (waveId, message) => {
+  // v4.4.1 Task 0.5: a wave that dies BEFORE its legs still owes the run a
+  // wave.json. Backlog C1 covered the pre-`try` throw; a server that never
+  // started was its uncovered sibling — run v441plan01's four dead seats left a
+  // `reason` in metadata.json, no wave.json, and stage1 recorded 'complete'.
+  // waveDir is optional (only the post-creation caller has one).
+  const errorWave = (waveId, message, waveDir) => {
     const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, createdAt, completedAt: new Date().toISOString(), status: 'error' });
     doc.error = message;
+    doc.reason = message; // classifier alias, same as fanout-leg.js's run docs
+    // best-effort: an unwritable wave dir must not mask the real error
+    if (waveDir) { try { writeWaveDoc(waveDir, doc); } catch { /* ignore */ } }
     emit(doc);
     return { wave: doc, exitCode: 1 };
   };
@@ -132,17 +126,10 @@ async function runFanout(options) {
 
   // 1b. Budget gate (pre-creation; refuse before spending). Only legs that
   // will actually run cost anything — a leg that never routed never spends.
-  if (!options.noCostGate) {
-    const { checkBudget, formatBudgetError } = require('./budget');
-    const { loadConfig } = require('../utils/config');
-    const cfg = loadConfig() || {};
-    const maxCostPerMtok = options.maxCostPerMtok !== undefined ? options.maxCostPerMtok : cfg.maxCostPerMtok;
-    const promptChars = (options.promptMeta && options.promptMeta.chars) || (options.prompt ? options.prompt.length : 0);
-    const budget = checkBudget(okLegs, { maxCostPerMtok, maxCost: options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost, promptChars });
-    if (!budget.ok) {
-      return failPre(ERROR_CODES.BUDGET_EXCEEDED, 'Error: budget gate refused the wave', formatBudgetError(budget));
-    }
-  }
+  // Lives in ./fanout-budget so the v4.4 concurrency reservation seam has room;
+  // that module's docblock carries the why.
+  const preflight = require('./fanout-budget').preflightBudget(okLegs, options);
+  if (!preflight.ok) { return failPre(ERROR_CODES.BUDGET_EXCEEDED, preflight.message, preflight.hint); }
 
   // 2. Wave record
   const waveId = options.waveId || generateTaskId();
@@ -169,14 +156,9 @@ async function runFanout(options) {
     const wave = buildWaveResult({
       waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt, notices,
     });
-    const wavePath = path.join(waveDir, 'wave.json');
-    writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
-    writeWaveMetadata(waveDir, { status: wave.status, completedAt });
-    const routingExitCode = waveExitCode(wave.status);
-    emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode: routingExitCode }, follow);
-    await require('../observe/on-complete').fireWaveOnComplete(options.onComplete, wave, { waveId, waveDir, wavePath, exitCode: routingExitCode, project }, options.onCompleteDeps);
-    emit(wave);
-    return { wave, exitCode: routingExitCode };
+    return finishWave({ wave, waveDir, waveId, project, completedAt, follow, emit,
+      exitCode: waveExitCode(wave.status),
+      onComplete: options.onComplete, onCompleteDeps: options.onCompleteDeps });
   }
 
   // 3. Context + prompts built ONCE (model-independent)
@@ -205,37 +187,41 @@ async function runFanout(options) {
     mcp: options.mcp, mcpConfig: options.mcpConfig, clientType: options.client,
     noMcp: options.noMcp, excludeMcp: options.excludeMcp,
   });
+  // ⚠️ v4.4.1 Task 0.5 — the external-server seam runHeadless has carried since
+  // v4.0 (src/headless.js:245): a caller that already owns a server passes it in
+  // and we must NOT close it. Added here because a council run launches its
+  // Stage-1 seat wave and its critic solo under ONE Promise.all (run-stages.js:83)
+  // and two concurrent startOpenCodeServer calls race on OpenCode's SQLite —
+  // run v441plan01 lost four of five seats in 736ms to `database is locked`.
+  // NAME DIVERGENCE, deliberate: runHeadless spells the pair client+server, but
+  // runFanout's `options.client` is ALREADY the client TYPE string (buildMcpConfig
+  // above, buildContext, buildPrompts, cli-handlers-run.js `client: args.client`),
+  // so the SDK client is `options.serverClient`. Both or neither: a half-injection
+  // falls back to owning a server rather than running clientless.
+  const externalServer = !!(options.server && options.serverClient);
   let client, server;
-  try {
-    ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
-  } catch (err) {
-    writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
-    return errorWave(waveId, `Failed to start server: ${err.message}`);
+  if (externalServer) {
+    ({ serverClient: client, server } = options);
+    logger.debug('Using external server (shared server mode)', { waveId, url: server.url });
+  } else {
+    try {
+      ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
+    } catch (err) {
+      writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
+      return errorWave(waveId, `Failed to start server: ${err.message}`, waveDir);
+    }
   }
-  if (server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
+  // Only an OWNED server's pid belongs in this wave's metadata: mcp-server.js's
+  // wave abort SIGTERMs `metadata.goPid` as "the orchestrator + its OWNED
+  // OpenCode server", which on an injected server would kill every sibling wave.
+  if (!externalServer && server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
 
-  // 5. Signal abort: mark wave + all legs aborted, close the server, then let
-  // NORMAL control flow finalize — legs see their abort marker within one poll
-  // (~2s) and settle, so step 7 still writes wave.json and emits a parseable
-  // aborted document. An unref'd force-exit watchdog backstops a wedged leg.
+  // 5. Signal abort (./fanout-signals owns the handler — size gate): mark wave +
+  // all legs aborted, close an OWNED server, then let NORMAL control flow
+  // finalize, so step 7 still writes wave.json and emits a parseable aborted
+  // document. An unref'd force-exit watchdog backstops a wedged leg.
   const legDirs = legIds.map(id => getSessionDir(project, id));
-  let signalled = null;
-  const uninstallSignals = installSignalAbort({
-    onAbort: (signal) => {
-      const code = signal === 'SIGINT' ? 130 : 143;
-      if (signalled) { process.exit(code); } // second signal: exit NOW
-      signalled = signal;
-      logger.warn('Signal received — aborting wave', { waveId, signal });
-      markAborted(waveDir, signal);
-      for (const dir of legDirs) { markAborted(dir, signal); }
-      // close() is async (B06 escalation); this handler stays sync, so
-      // fire-and-forget with a rejection guard. The 10s exit watchdog below
-      // comfortably outlives the ~2s escalation grace inside close().
-      try { server.close().catch(() => {}); } catch { /* best-effort */ }
-      const { armExitWatchdog } = require('../utils/lifecycle');
-      armExitWatchdog(code, 10000, { log: (m, meta) => logger.debug(m, meta) });
-    },
-  });
+  const waveAbort = installWaveAbort({ waveId, waveDir, legDirs, server, externalServer });
 
   // 6. Launch all ROUTABLE legs concurrently (runLeg never rejects). A leg that
   // failed to route (leg.ok === false) resolves to an error run doc in its own
@@ -269,26 +255,24 @@ async function runFanout(options) {
     }));
   } finally {
     heartbeat.stop();
-    uninstallSignals();
-    try { await server.close(); } catch { /* already closed on signal */ }
+    waveAbort.uninstall();
+    // ⚠️ close site 2 of 2 (`grep -n "server.close()" src/sidecar/fanout.js`).
+    // An injected server outlives this wave by design — the owner closes it once.
+    if (!externalServer) { try { await server.close(); } catch { /* already closed on signal */ } }
   }
 
   // 7. Aggregate, persist (atomic: tmp + rename), finalize, emit
   const completedAt = new Date().toISOString();
+  const signalled = waveAbort.signal();
   const wave = buildWaveResult({
     waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt,
     status: signalled ? 'aborted' : null, notices,
   });
-  const wavePath = path.join(waveDir, 'wave.json');
-  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
-  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
   const exitCode = signalled
     ? (signalled === 'SIGINT' ? 130 : 143)
     : waveExitCode(wave.status);
-  emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode }, follow);
-  await require('../observe/on-complete').fireWaveOnComplete(options.onComplete, wave, { waveId, waveDir, wavePath, exitCode, project }, options.onCompleteDeps);
-  emit(wave);
-  return { wave, exitCode };
+  return finishWave({ wave, waveDir, waveId, project, exitCode, completedAt, follow, emit,
+    onComplete: options.onComplete, onCompleteDeps: options.onCompleteDeps });
 }
 
 module.exports = {

package/src/sidecar/progress-fields.js

@@ -10,6 +10,23 @@
 /** Coarse stages surfaced to agents. */
 const COARSE_STAGES = ['starting', 'generating', 'folding', 'terminal'];
 
+/**
+ * The stages src/headless.js can write on its ONE terminal progress record.
+ *
+ * ⚠️ v4.4.1 LC-3: this list must stay byte-identical to resolveTerminalState's
+ * status vocabulary (src/sidecar/session-finalize.js), because headless.js
+ * derives the terminal stage straight from that function. A drift pin in
+ * tests/sidecar/progress-fields.test.js asserts it.
+ *
+ * Before LC-3 the terminal record hardcoded 'complete' on every path, so this
+ * set had exactly one member and deriveStage could match the literal. Widening
+ * the writer without widening this set would have been the WORSE bug: an
+ * aborted/errored/timed-out leg would fall through to 'starting' and a finished
+ * leg would read as barely begun for the whole window before metadata.json
+ * lands.
+ */
+const TERMINAL_PROGRESS_STAGES = new Set(['complete', 'error', 'timed-out', 'aborted']);
+
 /**
  * Collapse whitespace and defang fence/tag characters so the preview can be
  * embedded in a one-line JSON status without opening a code fence or tag
@@ -42,8 +59,10 @@ function latestAssistantPreview(entries) {
  * Map (metadata.status, progress.stage) to the coarse agent-facing stage.
  *  - terminal metadata status -> 'terminal'
  *  - progress 'receiving' -> 'generating'
- *  - progress 'complete' while metadata still says running -> 'folding'
- *    (mirror stopped; summary/conflict finalize in flight)
+ *  - a TERMINAL progress stage while metadata still says running -> 'folding'
+ *    (mirror stopped; summary/conflict finalize in flight). v4.4.1 LC-3: that is
+ *    any of TERMINAL_PROGRESS_STAGES, not just 'complete' — an aborted or
+ *    errored leg is every bit as "done streaming, finalizing" as a clean one.
  *  - anything else -> 'starting'
  * @param {string|undefined} metadataStatus @param {string|undefined} progressStage
  * @returns {string}
@@ -53,8 +72,11 @@ function deriveStage(metadataStatus, progressStage) {
     return 'terminal';
   }
   if (progressStage === 'receiving') { return 'generating'; }
-  if (progressStage === 'complete') { return 'folding'; }
+  if (TERMINAL_PROGRESS_STAGES.has(progressStage)) { return 'folding'; }
   return 'starting';
 }
 
-module.exports = { sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES };
+module.exports = {
+  sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES,
+  TERMINAL_PROGRESS_STAGES,
+};

package/src/sidecar/progress.js

@@ -19,7 +19,14 @@ const STAGE_LABELS = {
   session_created: 'Session created',
   prompt_sent: 'Briefing delivered, waiting for response...',
   receiving: 'Generating response...',
-  complete: 'Complete'
+  complete: 'Complete',
+  // v4.4.1 LC-3: the terminal record is no longer always 'complete' — headless.js
+  // derives it from resolveTerminalState, so these three are now reachable. Without
+  // a label, readProgress's `latest` (which falls back to stageLabel when the leg
+  // has no assistant messages yet) would read the raw id: "aborted", not "Aborted".
+  aborted: 'Aborted',
+  error: 'Failed',
+  'timed-out': 'Timed out'
 };
 
 /**

package/src/sidecar/session-utils.js

@@ -229,13 +229,14 @@ async function executeMode(options) {
  *   has no single default `config.model`, so this registers ALL of them in provider.models
  *   instead. Additive alongside the single-model `options.model` path used by owned-server
  *   callers (start/continue); see opencode-client.js's buildServerOptions.
+ * @param {number} [options.retryDelayMs] - Test seam: collapse the lock-race backoff.
  * @returns {Promise<{client: object, server: object}>}
  * @throws {Error} If server fails to start or health check fails
  */
 async function startOpenCodeServer(mcpConfig, options = {}) {
   const { checkHealth, startServer } = require('../opencode-client');
   const { ensureNodeModulesBinInPath } = require('../utils/path-setup');
-  const { ensurePortAvailable } = require('../utils/server-setup');
+  const { ensurePortAvailable, retryOnLockRace } = require('../utils/server-setup');
   const { waitForServer } = require('../headless');
 
   ensureNodeModulesBinInPath();
@@ -253,20 +254,28 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
 
-  const { client, server } = await startServer(serverOptions);
-  logger.debug('OpenCode server started', { url: server.url });
-
-  const ready = await waitForServer(client, checkHealth);
-  if (!ready) {
-    // Fire-and-forget: today close() is sync (Promise.resolve wraps a
-    // non-promise harmlessly); once close() becomes async (bounded
-    // kill-escalation poll) this guard prevents an unhandled rejection
-    // from racing the throw below.
-    Promise.resolve(server.close()).catch(() => {});
-    throw new Error('OpenCode server failed to become ready');
-  }
+  // v4.4.1 Task 0.5: a LOCK-CLASS start failure is retried (5 attempts,
+  // 250/500/1000/2000ms — widened from 3/750ms by Step 10.5, see server-setup).
+  // The per-run shared server removes the races a single amicus process creates;
+  // this covers the ones it cannot — two amicus processes, or a CLI run beside a
+  // live MCP server, sharing one OpenCode SQLite database. Nothing else retries:
+  // see isLockClassStartFailure in ../utils/server-setup.
+  return retryOnLockRace(async () => {
+    const { client, server } = await startServer(serverOptions);
+    logger.debug('OpenCode server started', { url: server.url });
+
+    const ready = await waitForServer(client, checkHealth);
+    if (!ready) {
+      // Fire-and-forget: today close() is sync (Promise.resolve wraps a
+      // non-promise harmlessly); once close() becomes async (bounded
+      // kill-escalation poll) this guard prevents an unhandled rejection
+      // from racing the throw below.
+      Promise.resolve(server.close()).catch(() => {});
+      throw new Error('OpenCode server failed to become ready');
+    }
 
-  return { client, server };
+    return { client, server };
+  }, { retryDelayMs: options.retryDelayMs });
 }
 
 module.exports = {