@yemi33/minions 0.1.2045 → 0.1.2046

package/README.md

@@ -11,8 +11,8 @@ Inspired by and initially scaffolded from [Brady Gaster's Squad](https://bradyga
 ## Prerequisites
 
 - **Node.js** 18+ (LTS recommended)
-- **Claude Code CLI** — install with `npm install -g @anthropic-ai/claude-code`
-- **Anthropic API key** or Claude Max subscription (agents spawn Claude Code sessions)
+- **A supported runtime CLI** — Minions defaults to GitHub Copilot CLI (`npm install -g @github/copilot`). Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) is also supported; switch with `minions config set-cli claude` or per-agent `cli` overrides.
+- **Auth for your runtime** — GitHub Copilot subscription (Copilot CLI handles its own auth) or an Anthropic API key / Claude Max subscription
 - **Git** — agents create worktrees for all code changes
 
 > **Note:** you do **not** need to configure your CLI for "autopilot" / "bypass permissions" / "dangerous mode". Minions passes the right bypass flag per spawn (`--dangerously-skip-permissions` for Claude; `--autopilot --allow-all --no-ask-user` for Copilot), independent of your global CLI config. Run `minions doctor` to verify your installed CLI accepts those flags.

package/dashboard/js/fre.js

@@ -80,9 +80,10 @@ function renderFre(statusOrProjects) {
 
   // Resolve the currently-configured runtime CLI for the explainer copy.
   // /api/status surfaces this as autoMode.defaultCli (resolveAgentCli(null, engine)).
-  // Fall back to autoMode.ccCli (also defaultCli-derived when ccCli unset) then 'claude'.
+  // Fall back to autoMode.ccCli (also defaultCli-derived when ccCli unset) then 'copilot'
+  // (matches ENGINE_DEFAULTS.defaultCli — W-mpmwxkk40007c995).
   const auto = (status && status.autoMode) || {};
-  const runtimeCli = String(auto.defaultCli || auto.ccCli || 'claude');
+  const runtimeCli = String(auto.defaultCli || auto.ccCli || 'copilot');
 
   const cardStyle = [
     'margin:12px 24px',

package/dashboard/js/settings.js

@@ -49,7 +49,7 @@ async function openSettings() {
   // Per-agent override placeholders surface the inherited fleet defaults as
   // muted text — operators see exactly what each agent will resolve to without
   // chasing config files. Empty input clears the override → re-inherit fleet.
-  const fleetCliLabel = e.defaultCli || 'claude';
+  const fleetCliLabel = e.defaultCli || 'copilot';
   const fleetModelLabel = e.defaultModel ? String(e.defaultModel) : 'CLI default';
   const agentRows = Object.entries(agents).map(function([id, a]) {
     return '<tr>' +
@@ -406,10 +406,10 @@ async function initRuntimeFleetUI(engineCfg, agentsCfg) {
     runtimes = Array.isArray(d.runtimes) ? d.runtimes : [];
   } catch { /* ignore — we'll surface a free-text-only path below */ }
 
-  // Always include 'claude' as a fallback option even if /api/runtimes is empty;
+  // Always include 'copilot' as a fallback option even if /api/runtimes is empty;
   // legacy installs without the registry endpoint should still see something pickable.
-  const names = runtimes.length ? runtimes.map(rt => rt.name) : ['claude'];
-  const currentDefault = engineCfg.defaultCli || 'claude';
+  const names = runtimes.length ? runtimes.map(rt => rt.name) : ['copilot'];
+  const currentDefault = engineCfg.defaultCli || 'copilot';
   const currentCc = engineCfg.ccCli || '';
   cliSelect.innerHTML = names.map(n =>
     '<option value="' + escHtml(n) + '"' + (n === currentDefault ? ' selected' : '') + '>' + escHtml(n) + '</option>'
@@ -440,7 +440,7 @@ async function initRuntimeFleetUI(engineCfg, agentsCfg) {
   // this the input was free-text and a user could (and did) save an agent
   // with cli=claude + model=<some gpt> — invalid combination that crashed
   // dispatch. Refreshing on CLI change clears stale model values.
-  const fleetDefaultCli = engineCfg.defaultCli || 'claude';
+  const fleetDefaultCli = engineCfg.defaultCli || 'copilot';
   for (const cell of cliCells) {
     const agentId = cell.getAttribute('data-runtime-cli');
     const agent = (agentsCfg || {})[agentId] || {};

package/dashboard.js

@@ -2337,6 +2337,17 @@ const CC_LOG_ERROR_MAX_LEN = 80; // truncate exception messages in [cc-stream] l
 const CC_STREAM_REATTACH_GRACE_MS = 60000; // keep CC job alive briefly after disconnect so the UI can reattach
 const CC_STREAM_DONE_RETENTION_MS = 30000; // retain final payload briefly so reconnect can still receive it
 const CC_LIVE_STREAM_MAX_AGE_MS = shared.ENGINE_DEFAULTS.ccLiveStreamMaxAgeMs;
+// W-mpmwxni2000c25c7-b — CC/doc-chat turn watchdog. Resolves per-call from
+// CONFIG.engine.ccTurnTimeoutMs (defaults to ENGINE_DEFAULTS.ccTurnTimeoutMs)
+// so an operator can shorten/lengthen the wall-clock cap without a code
+// change. callLLM's own `timeout` opt only kills the spawned child after a
+// long idle stretch; this turn-level cap kills WHICHEVER LLM call is in
+// flight inside ccCall/ccCallStreaming (resume → fresh → final retry).
+function _resolveCcTurnTimeoutMs() {
+  const cfg = CONFIG && CONFIG.engine;
+  const candidate = cfg && Number.isFinite(cfg.ccTurnTimeoutMs) ? cfg.ccTurnTimeoutMs : shared.ENGINE_DEFAULTS.ccTurnTimeoutMs;
+  return Number.isFinite(candidate) && candidate > 0 ? candidate : 0;
+}
 // Doc-chat is interactive — long-doc edits with multi-step Read+Write tool use can run
 // well past 5 min on `canEdit:true` paths. Bumped to 1 hour (matching CC) so legitimate
 // edits aren't killed mid-stream and the backend timeout never beats the user's reading
@@ -3391,6 +3402,22 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
   let timeoutTimer = null;
   let resolveResult;
   const promise = new Promise((resolve) => { resolveResult = resolve; });
+  // W-mpmwxni2000c25c7-c — build a single failure envelope shape from a
+  // typed Error (or a plain Error). Reads `.code` / `.retriable` if the
+  // pool stamped them; falls back to safe defaults otherwise so callers
+  // see a consistent `{ ..., errorCode, errorRetriable }` shape. Sub-item
+  // b's SSE writer consumes these to render a structured error event
+  // instead of grepping the stderr string for a code.
+  const _failureEnvelope = (err, defaultCode) => ({
+    text: accumulated,
+    sessionId: sessionHandle ? sessionHandle.sessionId : null,
+    code: 1,
+    usage: {},
+    raw: accumulated,
+    stderr: String((err && err.message) || err || 'cc-worker-pool failure'),
+    errorCode: (err && err.code) || defaultCode || null,
+    errorRetriable: (err && err.retriable !== undefined) ? err.retriable : true,
+  });
   const finalize = (envelope) => {
     if (settled) return;
     settled = true;
@@ -3415,14 +3442,18 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
     timeoutTimer = setTimeout(() => {
       try { sessionHandle && sessionHandle.cancel(); } catch { /* swallow */ }
       try { ccWorkerPool.closeTab(tabKey); } catch { /* swallow */ }
-      finalize({
-        text: accumulated,
-        sessionId: sessionHandle ? sessionHandle.sessionId : null,
-        code: 1,
-        usage: {},
-        raw: accumulated,
-        stderr: `doc-chat-pool: timeout after ${timeoutMs}ms`,
-      });
+      // W-mpmwxni2000c25c7-c — convert the legacy synthesized
+      // `{ code: 1, stderr: 'doc-chat-pool: timeout after Xms' }` shape into
+      // a typed-error envelope so the SSE writer can render the same
+      // structured error event for timeouts as for spawn/handshake/exit
+      // failures. The error code carries `cc-turn-timeout`; consumers
+      // grep on that instead of parsing the stderr string.
+      const timeoutErr = ccWorkerPool._typedError(
+        `doc-chat-pool: timeout after ${timeoutMs}ms`,
+        ccWorkerPool.ERROR_CODES.CC_TURN_TIMEOUT,
+        true
+      );
+      finalize(_failureEnvelope(timeoutErr, ccWorkerPool.ERROR_CODES.CC_TURN_TIMEOUT));
     }, timeoutMs);
     if (typeof timeoutTimer.unref === 'function') timeoutTimer.unref();
   }
@@ -3436,14 +3467,10 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
         systemPromptHash: _docChatPromptHash,
       });
     } catch (err) {
-      return finalize({
-        text: '',
-        sessionId: null,
-        code: 1,
-        usage: {},
-        raw: '',
-        stderr: String((err && err.message) || err || 'cc-worker-pool spawn failed'),
-      });
+      // Pool stamps `.code` (worker-spawn-failed / acp-handshake-failed) on
+      // every error from getSession; fall back to worker-spawn-failed if
+      // the error is a plain Error from somewhere unexpected.
+      return finalize(_failureEnvelope(err, ccWorkerPool.ERROR_CODES.WORKER_SPAWN_FAILED));
     }
     if (cancelled) {
       try { sessionHandle.cancel(); } catch { /* swallow */ }
@@ -3471,14 +3498,15 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
         finalize({ text: accumulated, sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
       },
       onError: (err) => {
-        finalize({
-          text: accumulated,
-          sessionId: sessionHandle.sessionId,
-          code: cancelled ? 0 : 1,
-          usage: {},
-          raw: accumulated,
-          stderr: String((err && err.message) || err || 'cc-worker-pool stream error'),
-        });
+        if (cancelled) {
+          // User-driven cancel — not a real error, treat as a clean exit.
+          finalize({ text: accumulated, sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
+          return;
+        }
+        // Pool stamps `.code` (worker-died for mid-stream proc exit).
+        // Fallback default is worker-died because the stream onError is
+        // overwhelmingly fired from the post-handshake exit handler.
+        finalize(_failureEnvelope(err, ccWorkerPool.ERROR_CODES.WORKER_DIED));
       },
     });
   })();
@@ -3975,12 +4003,65 @@ async function _retryDocChatAfterResumeFailure({ result, initialPass, freshSessi
 // Shape the per-failure debug envelope (raw stderr + classification metadata)
 // shared by hard failures and partial recoveries — keeps the wire shape in lockstep.
 function _buildDocChatErrorEnvelope(result) {
+  // W-mpmwxni2000c25c7-b — also surface the typed `error: {message, code,
+  // retriable}` envelope when llm.callLLM* produced one, so doc-chat clients
+  // get the same shape Command Center handlers emit.
+  const typed = result && result.error;
   return {
     code: result.code ?? null,
     stderr: String(result.stderr || '').slice(-2048),
     errorClass: result.errorClass || null,
     errorMessage: result.errorMessage || null,
     runtime: result.runtime || null,
+    ...(typed ? {
+      typedCode: typed.code || null,
+      typedMessage: typed.message || null,
+      retriable: typed.retriable !== false,
+    } : {}),
+  };
+}
+
+// W-mpmwxni2000c25c7-b — race a ccDocCall* promise against a wall-clock turn
+// timer. On expiry, fires `abortFn` (killing the in-flight CLI) and resolves
+// with a doc-chat-shaped failure payload that flows through the existing
+// _docChatFailureResponse / SSE error event paths. timeoutMs <= 0 disables
+// the watchdog (passthrough).
+async function _raceCcDocChatTimeout(callPromise, timeoutMs, abortFn, label) {
+  if (!timeoutMs || timeoutMs <= 0) return callPromise;
+  let timer = null;
+  let timedOut = false;
+  const timeoutPromise = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      timedOut = true;
+      try { if (abortFn) abortFn(); } catch { /* swallow */ }
+      resolve(null);
+    }, timeoutMs);
+    // NOTE: do NOT unref — Node would exit the event loop while awaiting the
+    // call promise (Promises don't keep the loop open; timers/I/O do). Cleared
+    // immediately on the success path below.
+  });
+  const winner = await Promise.race([callPromise, timeoutPromise]);
+  if (!timedOut) {
+    clearTimeout(timer);
+    return winner;
+  }
+  // Drain the in-flight call so its cleanup runs before we hand back the
+  // synthetic envelope.
+  await callPromise.catch(() => null);
+  const message = `${label || 'doc-chat'} turn timed out after ${timeoutMs}ms`;
+  return {
+    answer: 'Document chat request timed out — try again.',
+    toolUses: [],
+    error: {
+      code: 'cc-turn-timeout',
+      stderr: '',
+      errorClass: 'cc-turn-timeout',
+      errorMessage: message,
+      runtime: null,
+      typedCode: 'cc-turn-timeout',
+      typedMessage: message,
+      retriable: true,
+    },
   };
 }
 
@@ -6729,7 +6810,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const ccTurnId = 'cct-' + shared.uid();
       const turnSystemPrompt = renderDocChatSystemPromptForTurn(ccTurnId);
 
-      let { answer, partial, warning, toolUses, error: ccError } = await ccDocCall({
+      // W-mpmwxni2000c25c7-b — wall-clock turn watchdog. The doc-chat call
+      // can internally spawn resume + fresh + final-retry LLM calls; we want
+      // ONE wall-clock cap that covers the whole turn so a runtime stuck
+      // mid-stream can't outlive ccTurnTimeoutMs. On expiry the watchdog
+      // calls _docAbort (kills the in-flight CLI) and the synthesized payload
+      // below flows through the existing _docChatFailureResponse path.
+      const _docTurnTimeoutMs = _resolveCcTurnTimeoutMs();
+      const _docCallPromise = ccDocCall({
         message: body.message, document: currentContent, title: body.title,
         filePath: body.filePath, selection: body.selection, canEdit, isJson,
         model: body.model || undefined,
@@ -6739,6 +6827,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         systemPrompt: turnSystemPrompt,
         turnId: ccTurnId,
       });
+      const _docCallResult = await _raceCcDocChatTimeout(_docCallPromise, _docTurnTimeoutMs, () => _docAbort && _docAbort(), 'doc-chat');
+      let { answer, partial, warning, toolUses, error: ccError } = _docCallResult;
       const finalize = _finalizeDocChatEdit({
         filePath: body.filePath, fullPath, isJson, canEdit,
         originalContent: currentContent, delimiterContent: null,
@@ -6752,6 +6842,25 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         ccError, partial, warning, toolUses, finalize,
       });
       _docDone = true;
+      // W-mpmwxni2000c25c7-b — track every surfaced doc-chat error code so
+      // /api/metrics reflects silent-error regressions. Hard failures (no
+      // partial recovery, no edited file) graduate to 5xx so the client can
+      // render a real error UI instead of treating the polite "Failed to
+      // process request" string as a successful turn.
+      if (ccError) {
+        const errCode = ccError.typedCode || ccError.errorClass || ccError.code || 'unknown';
+        llm.trackEngineError('doc-chat', errCode);
+        const isHardFailure = !partial && !(finalize && finalize.edited);
+        if (isHardFailure) {
+          const status = errCode === shared.FAILURE_CLASS.CONFIG_ERROR ? 503 : 502;
+          return jsonReply(res, status, {
+            ...payload,
+            error: ccError.typedMessage || ccError.errorMessage || 'Document chat failed',
+            code: errCode,
+            retriable: ccError.retriable !== false,
+          });
+        }
+      }
       return jsonReply(res, 200, payload);
       } finally { _docAbort = null; _docDone = true; docChatInFlight.delete(docKey); }
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
@@ -6840,7 +6949,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const ccTurnId = 'cct-' + shared.uid();
         const turnSystemPrompt = renderDocChatSystemPromptForTurn(ccTurnId);
 
-        let { answer, partial, warning, toolUses, error: ccError } = await ccDocCallStreaming({
+        // W-mpmwxni2000c25c7-b — wall-clock turn watchdog (mirrors the
+        // non-stream handleDocChat path). On expiry _docAbort kills the
+        // in-flight LLM and the synthesized payload below flows through the
+        // SSE done frame the client already expects with `error` set.
+        const _docTurnTimeoutMs = _resolveCcTurnTimeoutMs();
+        const _docStreamCallPromise = ccDocCallStreaming({
           message: body.message, document: currentContent, title: body.title,
           filePath: body.filePath, selection: body.selection, canEdit, isJson,
           model: body.model || undefined,
@@ -6853,6 +6967,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           systemPrompt: turnSystemPrompt,
           turnId: ccTurnId,
         });
+        const _docStreamResult = await _raceCcDocChatTimeout(_docStreamCallPromise, _docTurnTimeoutMs, () => _docAbort && _docAbort(), 'doc-chat-stream');
+        let { answer, partial, warning, toolUses, error: ccError } = _docStreamResult;
         const finalize = _finalizeDocChatEdit({
           filePath: body.filePath, fullPath, isJson, canEdit,
           originalContent: currentContent, delimiterContent: null,
@@ -6865,6 +6981,23 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           actionFeedback: null, actionParseError: null,
           ccError, partial, warning, toolUses, finalize,
         });
+        // W-mpmwxni2000c25c7-b — track surfaced doc-chat error codes for
+        // /api/metrics and emit a named SSE `event: error` frame so the
+        // client can render a typed error instead of treating the polite
+        // fallback string as a normal completion.
+        if (ccError) {
+          const errCode = ccError.typedCode || ccError.errorClass || ccError.code || 'unknown';
+          llm.trackEngineError('doc-chat', errCode);
+          const isHardFailure = !partial && !(finalize && finalize.edited);
+          if (isHardFailure) {
+            const errPayload = {
+              message: ccError.typedMessage || ccError.errorMessage || 'Document chat failed',
+              code: errCode,
+              retriable: ccError.retriable !== false,
+            };
+            try { res.write(`event: error\ndata: ${JSON.stringify(errPayload)}\n\n`); } catch {}
+          }
+        }
         const { answer: finalAnswer, ...donePayload } = payload;
         writeDocEvent({
           type: 'done',
@@ -7461,21 +7594,40 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         // confirmation chips in the assistant reply.
         const ccTurnId = 'cct-' + shared.uid();
         const turnSystemPrompt = renderCcSystemPromptForTurn(ccTurnId);
-        const result = await ccCall(body.message, { store: 'cc', transcript: body.transcript, systemPrompt: turnSystemPrompt, turnId: ccTurnId });
-
-        // Non-zero exit with text = max_turns or partial success — still usable
-        if (!result.text) {
+        // W-mpmwxni2000c25c7-b — wall-clock turn watchdog. On expiry the
+        // in-flight LLM call is aborted and ccCall returns a synthetic
+        // envelope with error.code === 'cc-turn-timeout'.
+        const turnTimeoutMs = _resolveCcTurnTimeoutMs();
+        const result = await llm.withCcTurnTimeout({
+          timeoutMs: turnTimeoutMs, label: 'command-center',
+        }, (registerAbort) => ccCall(body.message, {
+          store: 'cc', transcript: body.transcript, systemPrompt: turnSystemPrompt, turnId: ccTurnId,
+          onAbortReady: registerAbort,
+        }));
+
+        // W-mpmwxni2000c25c7-b — typed-error envelope path. Any failure that
+        // produced no usable text is surfaced to the client as 5xx JSON
+        // `{ error, code, retriable }` instead of a polite 200 "I had trouble
+        // processing that" string that silently halves CC retry signal.
+        if (!result.text || result.error) {
+          const errEnvelope = result.error || (result.errorMessage
+            ? { message: result.errorMessage, code: result.errorClass || 'unknown', retriable: true }
+            : { message: 'Command Center returned no output', code: 'empty-output', retriable: true });
+          llm.trackEngineError('command-center', errEnvelope.code);
           const debugInfo = result.code !== 0 ? `(exit code ${result.code})` : '(empty response)';
           const stderrTail = (result.stderr || '').trim().split('\n').filter(Boolean).slice(-5).join(' | ');
-          console.error(`[CC] LLM failed after retries ${debugInfo}: ${stderrTail}`);
-          try { shared.log('warn', `CC failed ${debugInfo}: ${stderrTail.slice(0, 300)}`); } catch {}
-          const hasSession = !!ccSession.sessionId;
-          const retryHint = hasSession
-            ? 'Your session is still active — just send your message again to retry.'
-            : 'Try clicking **New Session** and sending your message again.';
-          return jsonReply(res, 200, {
-            text: `I had trouble processing that ${debugInfo}. ${stderrTail ? 'Detail: ' + stderrTail : ''}\n\n${retryHint}`,
-            actions: [], sessionId: ccSession.sessionId
+          console.error(`[CC] LLM failed after retries ${debugInfo} code=${errEnvelope.code}: ${stderrTail}`);
+          try { shared.log('warn', `CC failed ${debugInfo} code=${errEnvelope.code}: ${stderrTail.slice(0, 300)}`); } catch {}
+          // Missing-runtime is a 503 (service config); auth-failure also 503; other classes 502.
+          const status = result.missingRuntime ? 503
+            : errEnvelope.code === 'auth-failure' ? 503
+              : 502;
+          return jsonReply(res, status, {
+            error: errEnvelope.message,
+            code: errEnvelope.code,
+            retriable: !!errEnvelope.retriable,
+            sessionId: ccSession.sessionId || null,
+            ...(stderrTail ? { stderr: stderrTail.slice(0, 500) } : {}),
           });
         }
 
@@ -7496,7 +7648,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       } finally {
         _releaseCCTab(tabId);
       }
-    } catch (e) { _releaseCCTab(tabId); return jsonReply(res, e.statusCode || 500, { error: e.message }); }
+    } catch (e) { _releaseCCTab(tabId); return jsonReply(res, e.statusCode || 500, { error: e.message, code: 'handler-exception', retriable: false }); }
   }
 
   /** Build a lightweight input object for SSE tool events — keeps only the fields formatToolSummary needs, with truncated string values. */
@@ -7618,6 +7770,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         });
       } catch (err) {
         _emitTimingLog(null, null, Date.now(), 'spawn-failed');
+        // W-mpmwxni2000c25c7-c — pipe the pool's typed-error fields
+        // (`code`, `retriable`) onto the envelope so the SSE writer can
+        // render a structured error event instead of grepping the stderr
+        // string. Pool stamps `.code` (worker-spawn-failed or
+        // acp-handshake-failed) on every getSession rejection.
         return resolveResult({
           text: '',
           sessionId: null,
@@ -7625,6 +7782,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           usage: {},
           raw: '',
           stderr: String((err && err.message) || err || 'cc-worker-pool spawn failed'),
+          errorCode: (err && err.code) || ccWorkerPool.ERROR_CODES.WORKER_SPAWN_FAILED,
+          errorRetriable: (err && err.retriable !== undefined) ? err.retriable : true,
         });
       }
       const _tSessionReady = Date.now();
@@ -7671,13 +7830,29 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         },
         onError: (err) => {
           _emitTimingLog(_lifecycle, _tSessionReady, Date.now(), cancelled ? 'cancelled' : 'error');
+          if (cancelled) {
+            resolveResult({
+              text: accumulated,
+              sessionId: sessionHandle.sessionId,
+              code: 0,
+              usage: {},
+              raw: accumulated,
+              stderr: '',
+            });
+            return;
+          }
+          // W-mpmwxni2000c25c7-c — pipe the pool's typed-error fields
+          // through. mid-stream worker exits stamp `.code = 'worker-died'`
+          // on the Error before invoking onError.
           resolveResult({
             text: accumulated,
             sessionId: sessionHandle.sessionId,
-            code: cancelled ? 0 : 1,
+            code: 1,
             usage: {},
             raw: accumulated,
             stderr: String((err && err.message) || err || 'cc-worker-pool stream error'),
+            errorCode: (err && err.code) || ccWorkerPool.ERROR_CODES.WORKER_DIED,
+            errorRetriable: (err && err.retriable !== undefined) ? err.retriable : true,
           });
         },
       });
@@ -8032,73 +8207,100 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           : '';
         const prompt = _joinCcPromptParts(preamble, resumeGuard, carryover, turnHeader, projectContextPart, body.message);
 
-        const { trackEngineUsage: trackUsage } = require('./engine/llm');
+        const { trackEngineUsage: trackUsage, trackEngineError: trackErr, withCcTurnTimeout: withTimeout } = require('./engine/llm');
         const streamModel = CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel;
         const streamEffort = CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort;
         const ccMaxTurns = CONFIG.engine?.ccMaxTurns || shared.ENGINE_DEFAULTS.ccMaxTurns;
         let toolUses = [];
-        const llmPromise = _invokeCcStream({
-          prompt, sessionId, liveState, toolUses,
-          model: streamModel, effort: streamEffort, maxTurns: ccMaxTurns,
-          engineConfig: CONFIG.engine,
-          systemPrompt: turnSystemPrompt,
-          tabId,
-        });
-        _ccStreamAbort = llmPromise.abort;
-        liveState.abortFn = _ccStreamAbort;
-        ccInFlightAborts.set(tabId, _ccStreamAbort);
-        const result = await llmPromise;
-        trackUsage('command-center', result.usage);
-
-        if (result.missingRuntime) {
-          finishMissingRuntime(result, liveState);
-          return;
-        }
-
-        // Handle failure — non-zero exit with text = max_turns or partial success, still usable
-        if (!result.text && wasResume && result.code !== 0 && !req.destroyed) {
-          // Resume failed (stale/expired session) — auto-retry as fresh session (skip if client already disconnected)
-          console.log(`[CC-stream] Resume failed (code=${result.code}) — retrying fresh`);
-          const freshPreamble = buildCCStatePreamble();
-          const freshCarryover = _buildTranscriptCarryover(body.transcript, { currentMessage: body.message });
-          const freshPrompt = _joinCcPromptParts(freshPreamble, freshCarryover, turnHeader, projectContextPart, body.message);
-          toolUses = []; // discard stale metadata from the failed resume attempt
-          const retryPromise = _invokeCcStream({
-            prompt: freshPrompt, sessionId: undefined, liveState, toolUses,
+        // W-mpmwxni2000c25c7-b — turn-level watchdog. Wraps the initial
+        // _invokeCcStream PLUS the post-resume-fail retry so the wall clock
+        // covers the entire CC turn (not just one underlying LLM call). On
+        // expiry, whichever call is in flight is aborted; the watchdog
+        // resolves with a synthetic `{ error: { code: 'cc-turn-timeout' } }`
+        // envelope so the SSE error path below kicks in.
+        const turnTimeoutMs = _resolveCcTurnTimeoutMs();
+        const result = await withTimeout({
+          timeoutMs: turnTimeoutMs, label: 'command-center-stream',
+        }, async (registerAbort) => {
+          const llmPromise = _invokeCcStream({
+            prompt, sessionId, liveState, toolUses,
             model: streamModel, effort: streamEffort, maxTurns: ccMaxTurns,
             engineConfig: CONFIG.engine,
             systemPrompt: turnSystemPrompt,
             tabId,
           });
-          _ccStreamAbort = retryPromise.abort;
+          _ccStreamAbort = llmPromise.abort;
           liveState.abortFn = _ccStreamAbort;
           ccInFlightAborts.set(tabId, _ccStreamAbort);
-          const retryResult = await retryPromise;
-          trackUsage('command-center', retryResult.usage);
-          if (retryResult.text) {
-            // Fresh session succeeded — use retryResult from here
-            Object.assign(result, retryResult);
+          registerAbort(_ccStreamAbort);
+          const initial = await llmPromise;
+          trackUsage('command-center', initial.usage);
+
+          if (initial.missingRuntime) return initial;
+
+          // Handle failure — non-zero exit with text = max_turns or partial success, still usable
+          if (!initial.text && wasResume && initial.code !== 0 && !req.destroyed) {
+            // Resume failed (stale/expired session) — auto-retry as fresh session (skip if client already disconnected)
+            console.log(`[CC-stream] Resume failed (code=${initial.code}) — retrying fresh`);
+            const freshPreamble = buildCCStatePreamble();
+            const freshCarryover = _buildTranscriptCarryover(body.transcript, { currentMessage: body.message });
+            const freshPrompt = _joinCcPromptParts(freshPreamble, freshCarryover, turnHeader, projectContextPart, body.message);
+            toolUses = []; // discard stale metadata from the failed resume attempt
+            const retryPromise = _invokeCcStream({
+              prompt: freshPrompt, sessionId: undefined, liveState, toolUses,
+              model: streamModel, effort: streamEffort, maxTurns: ccMaxTurns,
+              engineConfig: CONFIG.engine,
+              systemPrompt: turnSystemPrompt,
+              tabId,
+            });
+            _ccStreamAbort = retryPromise.abort;
+            liveState.abortFn = _ccStreamAbort;
+            ccInFlightAborts.set(tabId, _ccStreamAbort);
+            registerAbort(_ccStreamAbort);
+            const retryResult = await retryPromise;
+            trackUsage('command-center', retryResult.usage);
+            if (retryResult.text) {
+              // Fresh session succeeded — use retryResult from here
+              Object.assign(initial, retryResult);
+              // Clear the error envelope inherited from the failed first attempt
+              // so the success path below doesn't misclassify a recovered turn.
+              if (retryResult.text) { initial.error = null; initial.ok = true; }
+            } else if (retryResult.error) {
+              initial.error = retryResult.error;
+            }
           }
-        }
+          return initial;
+        });
         if (result.missingRuntime) {
           finishMissingRuntime(result, liveState);
           return;
         }
-        if (!result.text) {
+        if (!result.text || result.error) {
           if (req.destroyed) {
             _ccStreamEnded = true;
             _logCcStreamEnd(_ccTelemetry, 'llm-empty-client-gone', { code: result.code });
             return;
           }
-          const debugInfo = result.code !== 0 ? `(exit code ${result.code})` : '(empty response)';
+          // W-mpmwxni2000c25c7-b — surface the typed error envelope as a
+          // distinct SSE `event: error` frame so the client renders a real
+          // error UI (with a retry hint derived from `retriable`) instead of
+          // swallowing a polite 200 "I had trouble processing that" string.
+          const envelope = result.error || (result.errorMessage
+            ? { message: result.errorMessage, code: result.errorClass || 'unknown', retriable: true }
+            : { message: 'Command Center returned no output', code: 'empty-output', retriable: true });
+          trackErr('command-center', envelope.code);
           const stderrTail = (result.stderr || '').trim().split('\n').filter(Boolean).slice(-3).join(' | ');
-          console.error(`[CC-stream] Failed: code=${result.code}, stderr=${(result.stderr || '').slice(0, 500)}, stdout_tail=${(result.raw || '').slice(-500)}`);
-          const retryHint = 'Send your message again to retry.';
-          liveState.donePayload = { type: 'done', text: `I had trouble processing that ${debugInfo}. ${stderrTail ? 'Detail: ' + stderrTail : ''}\n\n${retryHint}`, actions: [], sessionId: null };
+          console.error(`[CC-stream] Failed code=${envelope.code} retriable=${envelope.retriable}: ${(result.stderr || '').slice(0, 500)}; stdout_tail=${(result.raw || '').slice(-500)}`);
+          // Emit `event: error` (named SSE frame), then a `done`-style frame
+          // for clients that only handle the default message channel, then
+          // close cleanly so the EventSource exits its read loop without
+          // throwing a connection-reset.
+          try { res.write(`event: error\ndata: ${JSON.stringify({ message: envelope.message, code: envelope.code, retriable: !!envelope.retriable, ...(stderrTail ? { stderr: stderrTail.slice(0, 500) } : {}) })}\n\n`); } catch {}
+          liveState.donePayload = { type: 'error', error: envelope.message, code: envelope.code, retriable: !!envelope.retriable, sessionId: null };
           if (liveState.writer) liveState.writer(liveState.donePayload);
           if (liveState.endResponse) liveState.endResponse();
           _scheduleCcLiveCleanup(tabId);
-          _logCcStreamEnd(_ccTelemetry, 'llm-failed-fallback-sent', { code: result.code });
+          _logCcStreamEnd(_ccTelemetry, 'llm-failed-error-envelope-sent', { code: result.code, errorCode: envelope.code });
           return;
         }
 
@@ -8670,7 +8872,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           if (_isClear(e.defaultModel)) _deleteEngineConfig('defaultModel');
           else {
             const candidate = String(e.defaultModel);
-            const resolvedCli = config.engine.defaultCli || 'claude';
+            const resolvedCli = config.engine.defaultCli || 'copilot';
             const rejection = await _validateFleetModel(candidate, resolvedCli);
             if (rejection) _clamped.push(`engine.defaultModel: "${candidate}" ${rejection} — kept previous value`);
             else _setEngineConfig('defaultModel', candidate);
@@ -8680,7 +8882,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           if (_isClear(e.ccModel)) _deleteEngineConfig('ccModel');
           else {
             const candidate = String(e.ccModel);
-            const resolvedCli = config.engine.ccCli || config.engine.defaultCli || 'claude';
+            const resolvedCli = config.engine.ccCli || config.engine.defaultCli || 'copilot';
             const rejection = await _validateFleetModel(candidate, resolvedCli);
             if (rejection) _clamped.push(`engine.ccModel: "${candidate}" ${rejection} — kept previous value`);
             else _setEngineConfig('ccModel', candidate);
@@ -8798,7 +9000,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             if (updates.model === '' || updates.model === null) delete config.agents[id].model;
             else {
               const candidate = String(updates.model);
-              const resolvedCli = config.agents[id].cli || config.engine.defaultCli || 'claude';
+              const resolvedCli = config.agents[id].cli || config.engine.defaultCli || 'copilot';
               const runtimeModelStr = _resolveModelForRuntime(candidate, resolvedCli);
               const knownModels = await _modelsFor(resolvedCli);
               // Two validation paths:

package/docs/runtime-adapters.md

@@ -14,7 +14,12 @@ behavior is hidden behind an adapter object resolved through `resolveRuntime()`.
 
 `resolveRuntime(name)` throws when `name` is unknown so misconfigurations surface
 at dispatch time instead of producing silent fallbacks deep inside spawn logic.
-The default name is `'claude'` (matches `engine.defaultCli` fallback).
+When `name` is `null`/omitted, `resolveRuntime()` falls back to `'claude'` for
+parser-routing compatibility (Copilot's `parseOutput` cannot consume the Claude
+JSONL `{type:"result",result:"..."}` shape — see W-mpmwxkk40007c995). The fleet
+default that determines which runtime *new spawns* use is separate:
+`ENGINE_DEFAULTS.defaultCli` (also in W-mpmwxkk40007c995) is now `'copilot'`, so
+operators with no explicit `engine.defaultCli` get Copilot on dispatch.
 
 ## Adapter Interface
 
@@ -93,8 +98,8 @@ directly.
 
 | Helper | Chain |
 |--------|-------|
-| `resolveAgentCli(agent, engine)` | `agent.cli` → `engine.defaultCli` → `'claude'` |
-| `resolveCcCli(engine)` | `engine.ccCli` → `engine.defaultCli` → `'claude'` |
+| `resolveAgentCli(agent, engine)` | `agent.cli` → `engine.defaultCli` → `'copilot'` |
+| `resolveCcCli(engine)` | `engine.ccCli` → `engine.defaultCli` → `'copilot'` |
 | `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → undefined |
 | `resolveCcModel(engine)` | `engine.ccModel` → `engine.defaultModel` → undefined |
 | `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd`. Honors literal `0`. |

package/engine/cc-worker-pool.js

@@ -54,6 +54,45 @@
 const { spawn } = require('child_process');
 const crypto = require('crypto');
 
+// W-mpmwxni2000c25c7-c — typed error codes the pool emits through every
+// failure exit so the consumer (CC streaming handler / doc-chat pool
+// wrapper / SSE writer) can render a structured error envelope instead of
+// parsing the stderr string. Matches the `{ message, code, retriable }`
+// shape sub-item b standardized on for the dashboard's SSE envelope and
+// the runtime adapter parseError() contract (engine/runtimes/*.js).
+const ERROR_CODES = Object.freeze({
+  // spawn() threw synchronously OR the child process emitted an 'error'
+  // event (binary missing on PATH, exec failed, EPERM, etc.). Retriable
+  // because a transient PATH / fs glitch may recover.
+  WORKER_SPAWN_FAILED: 'worker-spawn-failed',
+  // The worker process exited DURING the ACP handshake (initialize or
+  // session/new) — usually `copilot login` is incomplete or the CLI
+  // version is too old. Also fires when session/new returns no
+  // sessionId. Retriable: the engine swaps to a fallback model / a re-auth
+  // may unblock the next attempt.
+  ACP_HANDSHAKE_FAILED: 'acp-handshake-failed',
+  // The worker process exited AFTER a successful handshake (the daemon
+  // died mid-turn). Retriable — the next call cold-spawns a fresh worker.
+  WORKER_DIED: 'worker-died',
+  // The consumer's per-turn timeout fired before the ACP session/prompt
+  // resolved. Owned by the dashboard pool wrappers (cc-worker-pool itself
+  // has no turn timeout) but exported here so all callers stringify the
+  // same constant. Retriable — most timeouts are transient.
+  CC_TURN_TIMEOUT: 'cc-turn-timeout',
+});
+
+// Build a typed Error carrying the `{ message, code, retriable }` envelope
+// fields the consumer expects. Plain Errors flow through unchanged; the
+// helper only stamps the extra metadata. Keep retriable defaulting to
+// `true` so a caller that forgets to set it still gets the safe default
+// (the legacy pre-typed-error code path treated every failure as retriable).
+function _typedError(message, code, retriable = true) {
+  const err = new Error(message);
+  err.code = code;
+  err.retriable = retriable;
+  return err;
+}
+
 // 10 minutes — matches the work-item spec.
 const IDLE_REAPER_MS = 10 * 60 * 1000;
 // Reaper sweep cadence. Not exposed as ENGINE_DEFAULTS to keep the pool
@@ -176,8 +215,13 @@ class Worker {
     try {
       proc = _internals.spawnAcp({ cwd: this.cwd });
     } catch (err) {
-      throw new Error(
-        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`
+      // spawn() threw synchronously — typically ENOENT (copilot binary not
+      // on PATH) or EACCES. Surface as worker-spawn-failed so the consumer
+      // can show "install the CLI / fix PATH" guidance.
+      throw _typedError(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`,
+        ERROR_CODES.WORKER_SPAWN_FAILED,
+        true
       );
     }
     this.proc = proc;
@@ -193,8 +237,13 @@ class Worker {
     const earlyExitPromise = new Promise((_, reject) => {
       earlyExitReject = (code) => {
         this.killed = true;
-        const err = new Error(
-          `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (exit ${code})`
+        // Early exit DURING the handshake = acp-handshake-failed (almost
+        // always missing `copilot login`, stale CLI, or daemon crash on
+        // boot). Retriable so re-auth or a CLI upgrade can recover.
+        const err = _typedError(
+          `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (exit ${code})`,
+          ERROR_CODES.ACP_HANDSHAKE_FAILED,
+          true
         );
         this.spawnError = err;
         this._failAllPending(err);
@@ -205,8 +254,13 @@ class Worker {
     proc.once('exit', earlyExitHandler);
 
     const errorHandler = (err) => {
-      const wrapped = new Error(
-        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`
+      // proc 'error' event fires when the OS can't actually start the child
+      // (ENOENT after a successful spawn() call, etc.). Treat as a spawn
+      // failure even though we made it past the synchronous spawn() above.
+      const wrapped = _typedError(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`,
+        ERROR_CODES.WORKER_SPAWN_FAILED,
+        true
       );
       this.spawnError = wrapped;
       this.killed = true;
@@ -227,7 +281,13 @@ class Worker {
       ]);
       this.sessionId = result && result.sessionId;
       if (!this.sessionId) {
-        throw new Error('copilot --acp failed -- session/new returned no sessionId');
+        // Handshake completed without an error but the daemon didn't hand
+        // back a sessionId — protocol violation or partial init failure.
+        throw _typedError(
+          'copilot --acp failed -- session/new returned no sessionId',
+          ERROR_CODES.ACP_HANDSHAKE_FAILED,
+          true
+        );
       }
     } finally {
       // Either the handshake finished (swap to a persistent exit handler that
@@ -236,7 +296,13 @@ class Worker {
     }
     proc.on('exit', () => {
       this.killed = true;
-      const err = new Error('copilot --acp process exited');
+      // Post-handshake exit = the daemon died mid-conversation. Retriable
+      // because the next call will cold-spawn a fresh worker.
+      const err = _typedError(
+        'copilot --acp process exited',
+        ERROR_CODES.WORKER_DIED,
+        true
+      );
       this._failAllPending(err);
       // Settle inflight too if it's still hanging
       if (this.inflight && !this.inflight.settled) {
@@ -656,9 +722,13 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
     // This is the bug class the ab141995 fix closed; if it ever recurs the
     // engine should fail loudly rather than hand back a half-initialized
     // handle. Throwing here lets the dashboard surface spawn-failed instead
-    // of the silent thinking-dots-forever symptom.
-    throw new Error(
-      `cc-worker-pool: getSession returning handle with null sessionId (tab=${tabId} lifecycle=${lifecycle}) — engine race regression, see W-mpd45blx00072f04 / W-mpdavudb000v8446`
+    // of the silent thinking-dots-forever symptom. Mark non-retriable —
+    // this is a real engine bug, not a transient pool failure; the next
+    // attempt would hit the same race.
+    throw _typedError(
+      `cc-worker-pool: getSession returning handle with null sessionId (tab=${tabId} lifecycle=${lifecycle}) — engine race regression, see W-mpd45blx00072f04 / W-mpdavudb000v8446`,
+      ERROR_CODES.ACP_HANDSHAKE_FAILED,
+      false
     );
   }
 
@@ -766,4 +836,10 @@ module.exports = {
   IDLE_REAPER_MS,
   REAPER_INTERVAL_MS,
   WARM_MAX_CONCURRENT,
+  // W-mpmwxni2000c25c7-c — typed-error envelope contract. Exported so the
+  // dashboard pool wrappers (and their tests) reference the same string
+  // constants and so the doc-chat timeout path can stamp the same
+  // `{ message, code, retriable }` shape the pool itself emits.
+  ERROR_CODES,
+  _typedError,
 };

package/engine/llm.js

@@ -82,6 +82,21 @@ function trackEngineUsage(category, usage) {
   _ensureFlushTimer();
 }
 
+// W-mpmwxni2000c25c7-b — silent-error regression counter. Every CC/doc-chat
+// error surfaced through the handlers bumps `_engine[category].errorsByCode[code]`
+// so /api/metrics reflects new error codes (cc-turn-timeout, empty-output, …)
+// without polluting cost/tokens. Counters flush on the same timer as
+// trackEngineUsage so the dashboard's fast-state mtime gate isn't bypassed.
+function trackEngineError(category, errorCode) {
+  if (!category || !errorCode) return;
+  if (category.startsWith('_test') || category.startsWith('test-')) return;
+  if (!_pendingMetrics.engine[category]) _pendingMetrics.engine[category] = _emptyEngineDelta();
+  const cat = _pendingMetrics.engine[category];
+  if (!cat.errorsByCode) cat.errorsByCode = Object.create(null);
+  cat.errorsByCode[errorCode] = (cat.errorsByCode[errorCode] || 0) + 1;
+  _ensureFlushTimer();
+}
+
 function flushMetricsBuffer() {
   const pending = _pendingMetrics;
   if (!Object.keys(pending.engine).length && !Object.keys(pending.daily).length) return;
@@ -106,6 +121,12 @@ function flushMetricsBuffer() {
           cat.totalDurationMs = (cat.totalDurationMs || 0) + delta.totalDurationMs;
           cat.timedCalls = (cat.timedCalls || 0) + delta.timedCalls;
         }
+        if (delta.errorsByCode) {
+          if (!cat.errorsByCode) cat.errorsByCode = {};
+          for (const [code, count] of Object.entries(delta.errorsByCode)) {
+            cat.errorsByCode[code] = (cat.errorsByCode[code] || 0) + count;
+          }
+        }
       }
       if (!metrics._daily) metrics._daily = {};
       for (const [day, delta] of Object.entries(pending.daily)) {
@@ -129,6 +150,12 @@ function flushMetricsBuffer() {
       c.inputTokens += delta.inputTokens; c.outputTokens += delta.outputTokens;
       c.cacheRead += delta.cacheRead; c.cacheCreation += delta.cacheCreation;
       c.totalDurationMs += delta.totalDurationMs; c.timedCalls += delta.timedCalls;
+      if (delta.errorsByCode) {
+        if (!c.errorsByCode) c.errorsByCode = Object.create(null);
+        for (const [code, count] of Object.entries(delta.errorsByCode)) {
+          c.errorsByCode[code] = (c.errorsByCode[code] || 0) + count;
+        }
+      }
     }
     for (const [day, delta] of Object.entries(pending.daily)) {
       if (!_pendingMetrics.daily[day]) _pendingMetrics.daily[day] = _emptyDailyDelta();
@@ -233,6 +260,8 @@ function _missingRuntimeResult(runtimeName, runtime, reason) {
     errorClass: shared.FAILURE_CLASS.CONFIG_ERROR,
     errorMessage: message,
     missingRuntime: true,
+    error: { message, code: shared.FAILURE_CLASS.CONFIG_ERROR, retriable: false },
+    ok: false,
   };
 }
 
@@ -245,7 +274,7 @@ function _resolvedCallResult(result) {
 function _resolveRuntimeNameFor(callOpts = {}) {
   let runtimeName = callOpts.cli;
   if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
-  return runtimeName || 'claude';
+  return runtimeName || 'copilot';
 }
 
 function _runtimeUnavailableResult(callOpts = {}) {
@@ -566,7 +595,7 @@ function _createStreamAccumulator({
 
 function _resolveRuntimeFor(callOpts) {
   // Explicit `cli` opt wins; otherwise fall to `engineConfig` resolution;
-  // otherwise default to claude (the historical behavior).
+  // otherwise default to copilot (fleet default as of W-mpmwxkk40007c995).
   return resolveRuntime(_resolveRuntimeNameFor(callOpts));
 }
 
@@ -599,6 +628,52 @@ function _resolveRuntimeFeatureOpts({
 
 // ─── Core LLM Call ───────────────────────────────────────────────────────────
 
+// W-mpmwxni2000c25c7-b — typed-error envelope helper. callLLM /
+// callLLMStreaming attach `error: { message, code, retriable }` to every
+// failure resolution so dashboard CC/doc-chat handlers can surface a
+// structured 5xx JSON or SSE `event: error` instead of returning an empty
+// reply that hangs the UI. The shape mirrors the existing `runtime.parseError`
+// contract from sub-item (a) so adapter classifications (auth-failure,
+// context-limit, budget-exceeded, crash, model-unavailable) propagate
+// verbatim. Engine codes added here:
+//   - 'spawn-error'        runFile/proc.on('error') failure (binary missing,
+//                          EACCES, fork bomb, ...)
+//   - 'runtime-exit'       non-zero exit code with no parseError signal
+//   - 'empty-output'       zero exit but no parsed text — runtime returned
+//                          nothing useful (CLI bug or silent timeout)
+//   - 'unparseable-output' bytes streamed but accumulator extracted no text
+//                          (malformed JSONL or unknown event shape)
+//
+// Existing `errorClass` / `errorMessage` fields stay populated for callers
+// that haven't moved to the typed envelope yet.
+function _buildErrorEnvelope(errInfo, code, parsed, fallback) {
+  if (errInfo && errInfo.code) {
+    return { message: errInfo.message || fallback || 'LLM call failed', code: errInfo.code, retriable: errInfo.retriable !== false };
+  }
+  if (code !== 0 && code !== null) {
+    const stderrTail = parsed && parsed.stderr ? String(parsed.stderr).trim().split('\n').slice(-3).join(' | ').slice(0, 500) : '';
+    return {
+      message: stderrTail ? `Runtime exited with code ${code}: ${stderrTail}` : `Runtime exited with code ${code}`,
+      code: 'runtime-exit',
+      retriable: true,
+    };
+  }
+  if (parsed && parsed.text) return null;
+  const rawLen = parsed && parsed.raw ? String(parsed.raw).length : 0;
+  if (rawLen > 0) {
+    return {
+      message: 'Runtime produced output the adapter could not parse',
+      code: 'unparseable-output',
+      retriable: true,
+    };
+  }
+  return {
+    message: fallback || 'Runtime returned no output',
+    code: 'empty-output',
+    retriable: true,
+  };
+}
+
 function callLLM(promptText, sysPromptText, opts = {}) {
   const {
     timeout = 120000, label = 'llm', maxTurns = 1, allowedTools = '',
@@ -670,6 +745,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
       const errInfo = code !== 0
         ? runtime.parseError([parsed.raw, parsed.stderr].filter(Boolean).join('\n'))
         : { message: '', code: null, retriable: true };
+      const errorEnvelope = _buildErrorEnvelope(errInfo, code, parsed, null);
       resolve({
         text: parsed.text || '',
         usage,
@@ -681,6 +757,8 @@ function callLLM(promptText, sysPromptText, opts = {}) {
         runtime: runtime.name,
         errorClass: errInfo.code,
         errorMessage: errInfo.message || null,
+        error: errorEnvelope,
+        ok: !errorEnvelope,
       });
     };
 
@@ -704,6 +782,8 @@ function callLLM(promptText, sysPromptText, opts = {}) {
         text: '', usage: null, sessionId: null, code: 1,
         stderr: err.message, raw: '', toolUses: [],
         runtime: runtime.name, errorClass: null, errorMessage: null,
+        error: { message: `Runtime spawn failed: ${err.message}`, code: 'spawn-error', retriable: true },
+        ok: false,
       });
     });
   });
@@ -784,6 +864,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
       const errInfo = code !== 0
         ? runtime.parseError([parsed.raw, parsed.stderr].filter(Boolean).join('\n'))
         : { message: '', code: null, retriable: true };
+      const errorEnvelope = _buildErrorEnvelope(errInfo, code, parsed, null);
       resolve({
         text: parsed.text || '',
         usage,
@@ -795,6 +876,8 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
         runtime: runtime.name,
         errorClass: errInfo.code,
         errorMessage: errInfo.message || null,
+        error: errorEnvelope,
+        ok: !errorEnvelope,
       });
     };
 
@@ -818,6 +901,8 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
         text: '', usage: null, sessionId: null, code: 1,
         stderr: err.message, raw: '', toolUses: [],
         runtime: runtime.name, errorClass: null, errorMessage: null,
+        error: { message: `Runtime spawn failed: ${err.message}`, code: 'spawn-error', retriable: true },
+        ok: false,
       });
     });
   });
@@ -825,13 +910,74 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
   return promise;
 }
 
+// ─── CC turn watchdog ────────────────────────────────────────────────────────
+//
+// W-mpmwxni2000c25c7-b — wall-clock cap for a single CC/doc-chat turn. CC turns
+// are a higher-level concept than the per-LLM-call `timeout` opt: a turn can
+// internally retry (resume → fresh → final retry) and each retry has its own
+// per-call timer. Without a turn-level watchdog, a runtime stuck mid-stream
+// (no exit, no chunks, no errors) leaves the SSE handler waiting for the
+// per-call timer to fire and the user staring at the typing dots.
+//
+// Usage: `result = await withCcTurnTimeout({ timeoutMs, label, onAbortReady }, (registerAbort) => callerThatReturnsResultPromise(registerAbort))`.
+// The caller plumbs `registerAbort(abortFn)` into every nested LLM call's
+// `onAbortReady` so the watchdog can kill whichever attempt is in flight on
+// expiry. Returns the original result on success or a synthetic envelope
+// `{ text:'', error:{ code:'cc-turn-timeout', retriable:true } }` on expiry.
+async function withCcTurnTimeout({ timeoutMs, label = 'cc-turn', onAbortReady } = {}, callFn) {
+  if (!timeoutMs || timeoutMs <= 0) return callFn(onAbortReady || (() => {}));
+  let currentAbort = null;
+  let timedOut = false;
+  let timer = null;
+  const registerAbort = (abort) => {
+    currentAbort = abort;
+    if (onAbortReady) onAbortReady(abort);
+  };
+  const inflight = Promise.resolve().then(() => callFn(registerAbort));
+  const timeoutPromise = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      timedOut = true;
+      try { if (currentAbort) currentAbort(); } catch { /* swallow */ }
+      resolve(null);
+    }, timeoutMs);
+    // NOTE: do NOT unref this timer. If we did, Node would exit the event
+    // loop while waiting on the inflight promise (Promises themselves don't
+    // hold the loop open — only timers/I/O do). The race below clears the
+    // timer immediately on success, so a still-armed timer never leaks past
+    // the resolution.
+  });
+  const winner = await Promise.race([inflight, timeoutPromise]);
+  if (!timedOut) {
+    clearTimeout(timer);
+    return winner;
+  }
+  // Let the in-flight call settle so its cleanup (cleanupFiles/Dirs, kill
+  // sweeps) actually runs before we hand a synthetic envelope to the caller.
+  const settled = await inflight.catch((err) => ({
+    text: '', usage: null, sessionId: null, code: 1, stderr: String(err && err.message || err), raw: '', toolUses: [],
+  }));
+  const message = `CC turn ${label} timed out after ${timeoutMs}ms`;
+  return {
+    ...settled,
+    text: '',
+    code: settled?.code || 1,
+    errorClass: 'cc-turn-timeout',
+    errorMessage: message,
+    error: { message, code: 'cc-turn-timeout', retriable: true },
+    ok: false,
+  };
+}
+
 module.exports = {
   callLLM,
   callLLMStreaming,
   trackEngineUsage,
+  trackEngineError,
   flushMetricsBuffer,
+  withCcTurnTimeout,
   // Exposed for unit tests — engine code MUST use the runtime adapter contract.
   _buildSpawnAgentFlags,
+  _buildErrorEnvelope,
   _resolveBin,
   _resetBinCache,
   _resetMetricsBufferForTest,

package/engine/preflight.js

@@ -87,17 +87,17 @@ function findClaudeBinary() {
  * `shared.runtimeConfigWarnings` so unknown-CLI warnings and binary checks
  * always cover the same surface.
  *
- * Without a config (legacy callers), returns just `['claude']` — the
- * historical default.
+ * Without a config (legacy callers), returns just `['copilot']` — matches
+ * `ENGINE_DEFAULTS.defaultCli` (W-mpmwxkk40007c995).
  */
 function _distinctRuntimes(config) {
   const set = new Set();
   if (!config || typeof config !== 'object') {
-    set.add('claude');
+    set.add('copilot');
     return Array.from(set);
   }
   const engine = config.engine || {};
-  set.add(engine.defaultCli ? String(engine.defaultCli) : 'claude');
+  set.add(engine.defaultCli ? String(engine.defaultCli) : 'copilot');
   if (engine.ccCli) set.add(String(engine.ccCli));
   for (const agent of Object.values(config.agents || {})) {
     if (agent && agent.cli) set.add(String(agent.cli));
@@ -355,7 +355,7 @@ function _fleetSummaryResults(config) {
   const results = [];
   if (!config || typeof config !== 'object') return results;
   const engine = config.engine || {};
-  const defaultCli = engine.defaultCli ? String(engine.defaultCli) : 'claude';
+  const defaultCli = engine.defaultCli ? String(engine.defaultCli) : 'copilot';
   const defaultModel = engine.defaultModel ? String(engine.defaultModel) : '(runtime default)';
   results.push({ name: 'Fleet', ok: true, message: `defaultCli=${defaultCli}  defaultModel=${defaultModel}` });
 

package/engine/queries.js

@@ -528,7 +528,7 @@ function getAgents(config) {
 
   return roster.map(a => {
     // Resolve which CLI runtime this agent dispatches to: per-agent override
-    // → engine.defaultCli → 'claude'. Surfaced so the dashboard can show a
+    // → engine.defaultCli → 'copilot'. Surfaced so the dashboard can show a
     // runtime tag next to the agent name.
     const runtime = shared.resolveAgentCli(a, config.engine || {});
     const inboxFiles = allInboxFiles.filter(f => f.includes(a.id));
@@ -1770,19 +1770,18 @@ function _projectGitStatusEqual(a, b) {
 function _scheduleProjectGitStatusRefresh(localPath, key, configuredMainBranch) {
   const existing = _projectGitStatusCache.get(key);
   if (existing && existing.promise) return existing.promise;
-  const entry = existing || { ts: 0, value: PROJECT_GIT_STATUS_PENDING, promise: null };
+  const entry = existing || { ts: 0, value: PROJECT_GIT_STATUS_PENDING, promise: null, refMtimes: null };
   const prevValue = entry.value;
-  // Capture probe-start time BEFORE running git, not after. Used as the
-  // baseline for `_projectGitRefsAdvancedSince` on the next call. If we
-  // captured probe-END time, a file written just before the probe started
-  // could end up with `mtimeMs >= entry.ts` on a fast filesystem (NTFS
-  // mtime granularity vs millisecond-precise Date.now()), busting the
-  // cache spuriously on the very next read. Probe-START is the safer
-  // anchor — any file with `mtimeMs > probeStartTs` legitimately changed
-  // at-or-after the probe, so re-probing is correct.
+  // Snapshot ref mtimes BEFORE the probe so the next call compares against
+  // an exact baseline rather than a Date.now() timestamp. On Windows
+  // Date.now() can have ~15ms granularity while NTFS mtime is sub-ms, so
+  // a file written shortly before the probe could appear `mtimeMs > ts`
+  // even when nothing actually changed.
   const probeStartTs = Date.now();
+  const probeStartRefMtimes = _snapshotProjectGitRefMtimes(localPath, configuredMainBranch);
   entry.promise = _probeProjectGitStatus(localPath, configuredMainBranch).then(value => {
     entry.ts = probeStartTs;
+    entry.refMtimes = probeStartRefMtimes;
     entry.value = value;
     entry.promise = null;
     if (_onProjectGitStatusChanged && !_projectGitStatusEqual(prevValue, value)) {
@@ -1857,35 +1856,65 @@ function _resolveCommonGitDir(gitDir) {
   return path.isAbsolute(raw) ? raw : path.resolve(gitDir, raw);
 }
 
-// Return true when any of the per-project git ref files (logs/HEAD,
-// FETCH_HEAD, refs/remotes/origin/<comparator>) have mtimeMs > cachedTs.
-// Lets `getProjectGitStatus` bypass its 15s TTL after `git pull`, `git
-// fetch`, `git checkout`, etc. so the next /api/status reflects the new
-// HEAD / ahead-behind within one SPA poll instead of waiting out the TTL
-// (W-mphdmr8c00030124). Tolerates ENOENT on FETCH_HEAD / refs (never-
-// fetched repos simply haven't moved those files yet). Cost ≤3 statSync
-// per project per /api/status build — well under the 'cheap' budget
-// called out in getStatusFastStateMtimePaths's docstring.
-function _projectGitRefsAdvancedSince(localPath, cachedTs, configuredMainBranch) {
+// Enumerate the per-project git ref files we watch for cache-busting:
+// logs/HEAD (per-worktree gitdir), FETCH_HEAD + refs/remotes/origin/* (common
+// gitdir for linked worktrees). Same paths as the fast-state mtime tracker
+// so callers see a coherent view across surfaces.
+function _projectGitRefFiles(localPath, configuredMainBranch) {
   const gitDir = _resolveGitDir(localPath);
-  if (!gitDir) return false;
-  // logs/HEAD is per-worktree; FETCH_HEAD + refs/remotes/origin/* live in
-  // the COMMON gitdir for linked worktrees. For the main worktree both
-  // resolve to the same place, so this is a no-op there.
+  if (!gitDir) return null;
   const commonGitDir = _resolveCommonGitDir(gitDir);
-  const candidates = [
+  const files = [
     path.join(gitDir, 'logs', 'HEAD'),
     path.join(commonGitDir, 'FETCH_HEAD'),
   ];
   const comparator = configuredMainBranch && String(configuredMainBranch).trim();
   if (comparator) {
-    candidates.push(path.join(commonGitDir, 'refs', 'remotes', 'origin', comparator));
+    files.push(path.join(commonGitDir, 'refs', 'remotes', 'origin', comparator));
   }
-  for (const file of candidates) {
-    try {
-      const st = fs.statSync(file);
-      if (st.mtimeMs > cachedTs) return true;
-    } catch { /* ENOENT / EPERM — file just hasn't moved */ }
+  return files;
+}
+
+// Snapshot mtimeMs for each ref file. Missing files record `null`. Used as
+// the baseline that the next `getProjectGitStatus` call compares against —
+// inequality, not threshold-vs-timestamp, so the result is precision-
+// independent (Windows `Date.now()` can be 15ms coarse while NTFS mtime is
+// sub-millisecond, which used to make threshold checks fire spuriously on
+// freshly-written files).
+function _snapshotProjectGitRefMtimes(localPath, configuredMainBranch) {
+  const files = _projectGitRefFiles(localPath, configuredMainBranch);
+  if (!files) return null;
+  const out = Object.create(null);
+  for (const f of files) {
+    try { out[f] = fs.statSync(f).mtimeMs; }
+    catch { out[f] = null; /* ENOENT recorded as null — flipping to present must bust */ }
+  }
+  return out;
+}
+
+// Return true when ANY tracked ref file's mtime (or existence) differs from
+// the snapshot captured during the last probe. Replaces the older threshold-
+// vs-cachedTs check that suffered from `Date.now()`/`mtimeMs` resolution
+// races on Windows. Lets `getProjectGitStatus` bypass its 15s TTL after
+// `git pull`, `git fetch`, `git checkout`, etc. so the next /api/status
+// reflects the new HEAD / ahead-behind within one SPA poll instead of
+// waiting out the TTL (W-mphdmr8c00030124). Cost: 2-3 statSync per call —
+// well under the 'cheap' budget.
+function _projectGitRefsAdvancedSince(localPath, configuredMainBranch, snapshot) {
+  // No snapshot yet (legacy entry shape OR first call) — preserve the
+  // current cached value so the TTL-only fast-path still works. A real
+  // change still surfaces on the next /api/status because the fast-state
+  // mtime tracker watches the same files and will bust the upstream cache.
+  if (!snapshot) return false;
+  const current = _snapshotProjectGitRefMtimes(localPath, configuredMainBranch);
+  if (!current) return false;
+  for (const file of Object.keys(snapshot)) {
+    if (current[file] !== snapshot[file]) return true;
+  }
+  // Also catch a file that appeared since the snapshot (e.g. first `git
+  // fetch` materialises FETCH_HEAD).
+  for (const file of Object.keys(current)) {
+    if (!(file in snapshot)) return true;
   }
   return false;
 }
@@ -1902,7 +1931,7 @@ function getProjectGitStatus(localPath, configuredMainBranch = null) {
   // user-visible lag) because the rebuilt fast-state still hits this
   // cache and never schedules a refresh until the TTL itself expires.
   if (cached && cached.ts && (now - cached.ts) < PROJECT_GIT_STATUS_TTL
-      && !_projectGitRefsAdvancedSince(localPath, cached.ts, configuredMainBranch)) {
+      && !_projectGitRefsAdvancedSince(localPath, configuredMainBranch, cached.refMtimes)) {
     return cached.value;
   }
   // Cheap synchronous existsSync — short-circuits a path that just disappeared

package/engine/shared.js

@@ -1856,7 +1856,7 @@ const ENGINE_DEFAULTS = {
   // Engine code MUST go through the resolveAgent*/resolveCc* helpers below;
   // never read these fields directly. New runtimes are added by registering
   // an adapter in engine/runtimes/index.js — these defaults stay stable.
-  defaultCli: 'claude',          // fleet-wide CLI runtime (must be a key in engine/runtimes/index.js)
+  defaultCli: 'copilot',         // fleet-wide CLI runtime (must be a key in engine/runtimes/index.js); flipped from 'claude' in W-mpmwxkk40007c995 — Copilot is now the primary runtime, Claude remains supported as an opt-in
   defaultModel: undefined,       // fleet-wide model; undefined = let the runtime adapter pick its own default
   ccCli: undefined,              // CC/doc-chat CLI override; undefined = inherit defaultCli (independent of agent path)
   ccModel: undefined,            // CC/doc-chat model override; undefined = inherit defaultModel
@@ -1879,6 +1879,7 @@ const ENGINE_DEFAULTS = {
   removeWorktreeFailureTtlMs: 24 * 60 * 60 * 1000, // stale failed paths are forgotten after a day
   removeWorktreeFailureMaxEntries: 1000, // bound failed-worktree retry suppression cache
   ccMaxTurns: 50, // max tool-use turns per CC/doc-chat call before CLI stops (per response, not per session)
+  ccTurnTimeoutMs: 300000, // W-mpmwxni2000c25c7-b: wall-clock cap per CC/doc-chat turn; on expiry the in-flight LLM call is aborted and the handler surfaces `{code:'cc-turn-timeout', retriable:true}` instead of hanging the UI
   docSessionMaxEntries: 200, // cap doc-chat session map/disk store by least-recent activity (LRU; sessions are non-expiring otherwise)
   ccLiveStreamMaxAgeMs: 30 * 60 * 1000, // hard cap reconnect buffers if abort/cleanup stalls
   metricsFlushIntervalMs: 10000, // batch trackEngineUsage writes to metrics.json — flushed every 10s instead of per-call to cut lock contention and dashboard mtime churn
@@ -2084,7 +2085,7 @@ function _isMeaningful(v) {
  * Resolve the CLI runtime for a per-agent spawn. Priority:
  *   1. `agent.cli`              — per-agent override
  *   2. `engine.defaultCli`      — fleet default
- *   3. `ENGINE_DEFAULTS.defaultCli` ('claude') — hardcoded fallback
+ *   3. `ENGINE_DEFAULTS.defaultCli` ('copilot') — hardcoded fallback
  *
  * Does NOT fall through to `engine.ccCli`. CC and agents are independent paths.
  */
@@ -2098,7 +2099,7 @@ function resolveAgentCli(agent, engine) {
  * Resolve the CLI runtime for the Command Center / doc-chat. Priority:
  *   1. `engine.ccCli`           — CC-only override
  *   2. `engine.defaultCli`      — fleet default
- *   3. `ENGINE_DEFAULTS.defaultCli` ('claude') — hardcoded fallback
+ *   3. `ENGINE_DEFAULTS.defaultCli` ('copilot') — hardcoded fallback
  *
  * Does NOT inspect any agent overrides. CC has no notion of "which agent" —
  * it's a fleet-wide singleton.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2045",
+  "version": "0.1.2046",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"