@yemi33/minions 0.1.2382 → 0.1.2383

package/bin/minions.js

@@ -912,6 +912,7 @@ function init() {
 
   // Copy with smart merge logic
   copyDir(PKG_ROOT, MINIONS_HOME, excludeTop, alwaysUpdate, neverOverwrite, isUpgrade, actions);
+  shared.syncBundledPersonalSkills(path.join(MINIONS_HOME, 'skills'), { homeDir: os.homedir() });
 
   // Create config from template if it doesn't exist
   const configPath = path.join(MINIONS_HOME, 'config.json');

package/dashboard.js

@@ -26,7 +26,7 @@ const fs = require('fs');
 const path = require('path');
 const v8 = require('v8');
 const llm = require('./engine/llm');
-const { resolveRuntime } = require('./engine/runtimes');
+const { resolveRuntime, shouldSuppressPostMutationError } = require('./engine/runtimes');
 
 // Dashboard version stamp — captured at module load so it reflects the code actually running.
 // codeCommit is read via _readGitHeadShort (defined below — function declarations
@@ -1974,11 +1974,19 @@ function _countWorktrees() {
   try {
     const config = queries.getConfig();
     const projects = shared.getProjects(config);
-    let count = 0;
+    const worktreeRoots = new Map();
     for (const p of projects) {
-      const root = p.localPath ? path.resolve(p.localPath) : null;
-      if (!root) continue;
-      const wtRoot = path.resolve(root, config.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot);
+      if (!p.localPath) continue;
+      const wtRoot = path.resolve(
+        p.localPath,
+        config.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot,
+      );
+      const rootKey = shared._normalizeWorktreePath(wtRoot);
+      if (!worktreeRoots.has(rootKey)) worktreeRoots.set(rootKey, wtRoot);
+    }
+
+    let count = 0;
+    for (const wtRoot of worktreeRoots.values()) {
       try {
         for (const dir of fs.readdirSync(wtRoot)) {
           const dirPath = path.join(wtRoot, dir);
@@ -4678,6 +4686,7 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
   (async () => {
     try {
       sessionHandle = await ccWorkerPool.getSession({
+        runtime: llm._resolveRuntimeFor({ engineConfig }),
         tabId: tabKey,
         model,
         effort,
@@ -5345,13 +5354,15 @@ function _recoverPartialDocChatResponse(result, sessionKey) {
 function _shouldSuppressDocChatPostPatchError(ccError, finalize) {
   if (!finalize || finalize.edited !== true) return false;
   if (!ccError) return false;
-  // W-mpmwxni2000c25c7-a — accept both the legacy 'unknown-model' errorClass
-  // (still emitted by the dashboard preflight at _preflightModelCheck) and
-  // the new 'model-unavailable' code returned by copilot.parseError for
-  // invalid-model responses. Suppress in either case — the edit already
-  // landed, so the stale model error shouldn't surface to the user.
-  if (ccError.errorClass !== 'unknown-model' && ccError.errorClass !== 'model-unavailable') return false;
-  return String(ccError.runtime || '').toLowerCase() === 'copilot';
+  try {
+    const runtime = resolveRuntime(ccError.runtime);
+    return shouldSuppressPostMutationError(runtime, {
+      mutationApplied: true,
+      error: ccError,
+    });
+  } catch {
+    return false;
+  }
 }
 
 function _buildDocChatResponsePayload({
@@ -9447,6 +9458,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     if (!shared.resolveCcUseWorkerPool(CONFIG.engine)) return { skipped: 'pool-disabled' };
     if (!tabId) throw new Error('tabId required');
     const result = await ccWorkerPool.warmTab({
+      runtime: resolveRuntime(shared.resolveCcCli(CONFIG.engine)),
       tabId,
       model: CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel,
       effort: CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort,
@@ -9823,6 +9835,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     (async () => {
       try {
         sessionHandle = await ccWorkerPool.getSession({
+          runtime: llm._resolveRuntimeFor({ engineConfig }),
           tabId: resolvedTabId,
           model,
           effort,
@@ -13614,6 +13627,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           status: 'enrolled',
           prId: linkResult.id,
           autoManaged,
+          resurrected: linkResult.resurrected === true,
           contextOnly: false,
           project: linkResult.targetProject?.name || 'central',
           projectName: plan.projectName || linkResult.targetProject?.name || null,

package/docs/completion-reports.md

@@ -90,6 +90,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 |---|---|---|
 | `noop` | boolean | Canonical no-op signal. See [No-op semantics](#no-op-semantics). |
 | `noopReason` | string | Human-readable rationale shown when `noop: true`. Falls back to `summary` if absent. |
+| `reviewFindingResolution` | object | Required when a review-feedback fix leaves the PR branch unchanged. Shape: `{findingId, disposition, currentCodeEvidence}`; see [Review-fix no-op evidence](#review-fix-no-op-evidence). |
 | `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
 | `affected_files` | string[] | Optional array of relative file paths this dispatch touched or plans to touch. Used by the dispatcher to emit a conflict warning (`WI <new-id> may conflict with in-progress <existing-id> on files: [list]`) when a new WI's `affected_files` overlaps with an in-progress WI's `affected_files`. Logging-only — dispatch is never blocked. Stored back onto the work item after completion so re-dispatches can also participate in overlap detection. |
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
@@ -223,7 +224,7 @@ All three classes are **never retryable** — they signal a structural/environme
 
 ## No-op semantics
 
-A no-op completion declares that the agent correctly **declined** to do the work — the change was already shipped on master, the dispatch premise was wrong, the flagged review comment was an author-note, etc.
+A no-op completion declares that the agent correctly **declined** to do the work — the change was already shipped on master, the dispatch premise was wrong, or an exact review finding was proven resolved/invalid with current-code evidence.
 
 To signal a no-op:
 
@@ -245,6 +246,24 @@ Engine behavior when `noop: true` (`engine/lifecycle.js` `parseCompletionNoop` +
 
 Without `noop: true`, an empty PR field will be flagged as a missing-PR-attachment failure and auto-retried up to `ENGINE_DEFAULTS.maxRetries` times.
 
+### Review-fix no-op evidence
+
+Review-feedback fixes have a stricter no-op contract because all agents can share one platform credential. `viewerDidAuthor: true` does not identify the Minions agent that authored a finding, and reviewer/fixer agent equality is allowed.
+
+If the live PR branch did not advance, the completion must set `noop: true` and include:
+
+```json
+{
+  "reviewFindingResolution": {
+    "findingId": "review-0123456789abcdef",
+    "disposition": "already-resolved",
+    "currentCodeEvidence": "engine/lifecycle.js:4600 already enforces the condition; test/unit/example.test.js covers it."
+  }
+}
+```
+
+The `findingId` is injected into the fix playbook from trusted `minionsReview` provenance. `disposition` is `already-resolved` or `invalid`, and `currentCodeEvidence` must cite a current `file:line` or commit. An identity-only no-op is retried and does not increment `_noOpFixes`.
+
 ## PR-comment follow-ups
 
 Fix and review agents can spin off new Minions work items in response to PR

package/docs/runtime-adapters.md

@@ -8,7 +8,8 @@ behavior is hidden behind an adapter object resolved through `resolveRuntime()`.
 
 | File | Role |
 |------|------|
-| `engine/runtimes/index.js` | Adapter registry. `resolveRuntime(name)`, `listRuntimes()`, `registerRuntime()`. Engine code MUST go through these. |
+| `engine/runtimes/contract.js` | Versioned adapter contract, capability gating, opaque invocation-option transport, and optional-hook facades. |
+| `engine/runtimes/index.js` | Adapter registry and the only runtime facade imported by orchestration code. |
 | `engine/runtimes/claude.js` | Claude Code adapter. Owns binary probe, `--system-prompt-file`, JSONL parser, model shorthands, budget cap, bare mode. |
 | `engine/runtimes/copilot.js` | GitHub Copilot CLI adapter. Owns standalone-vs-`gh-copilot` resolution, stdin-only prompt delivery, `https://api.githubcopilot.com/models` discovery, effort `'max' → 'xhigh'` mapping. |
 | `engine/runtimes/codex.js` | OpenAI Codex CLI adapter. Owns `@openai/codex`/native binary resolution, `codex exec --json -` prompt delivery, `codex debug models --bundled` discovery, `.agents/skills` roots, and Codex JSONL parsing. |
@@ -30,6 +31,7 @@ methods that genuinely differ.
 
 | Member | Type / Returns | Purpose |
 |--------|----------------|---------|
+| `apiVersion` | number | Contract version. Bundled adapters use `1`; incompatible versions fail at registration. |
 | `name` | string | Adapter identifier (matches the registry key). |
 | `capabilities` | flag object (see below) | Feature flags consumed by engine code. |
 | `resolveBinary({ env, config? })` | `{ bin, native, leadingArgs }` or null | Probe PATH, npm-globals, package overrides; cached to `engine/<name>-caps.json`. `leadingArgs` is `[]` for direct binaries and `['copilot']` for the `gh copilot` extension fallback. |
@@ -39,7 +41,8 @@ methods that genuinely differ.
 | `modelsCache` | absolute path | Cache file for `listModels()` results. |
 | `spawnScript` | absolute path | Path to the runtime-agnostic spawn wrapper (currently `engine/spawn-agent.js` for both runtimes). |
 | `buildArgs(opts)` | `string[]` | CLI args excluding the binary itself. |
-| `buildSpawnFlags(opts)` | `string[]` | Optional; engine-side flags consumed by `engine/spawn-agent.js` (overrides the default `_buildAgentSpawnFlags`). |
+| `resolveInvocationOptions({ options, engineConfig, config, failureClass })` | object | Optional; maps harness-specific config and retry policy into semantic invocation options. Core code never reads harness-specific invocation keys. |
+| `buildSpawnFlags(opts)` | `string[]` | Optional compatibility flags for older spawn wrappers. New fields travel in the opaque `--runtime-options` bag automatically. |
 | `buildPrompt(promptText, sysPromptText)` | string | Final prompt delivered to the CLI. Adapters that lack `--system-prompt-file` (Copilot) prepend a `<system>` block here. |
 | `getUserAssetDirs({ homeDir })` | `string[]` | Runtime-native global asset roots passed to spawn as `--add-dir` so worktrees still see them. |
 | `getSkillRoots({ homeDir, project? })` | `[{ scope, dir, projectName? }]` | Where `collectSkillFiles` looks for native + project skill markdown. |
@@ -52,11 +55,39 @@ methods that genuinely differ.
 | `parseStreamChunk(line)` | event object or null | Single JSONL line → typed event. |
 | `parseError(rawOutput)` | `{ message, code, retriable }` | Codes: `auth-failure`, `context-limit`, `budget-exceeded`, `model-unavailable` (retriable=true for upstream overload/503; retriable=false for invalid/typo'd model id — Copilot enriches the message via `_warmModelCache()` so it lists the available models), `crash`, null. |
 | `createStreamConsumer(ctx)` | consumer object | Stream accumulator used by `engine/llm.js`. |
-| `detectPermissionGate`, `getPromptDeliveryMode`, `usesSystemPromptFile`, `classifyFailure` | misc | Adapter-owned policy that engine code reads through accessors instead of branching on `runtime.name`. |
-
-The contract surface is documented inline at the top of `engine/runtimes/claude.js`
-(see the JSDoc block at the start of that file). Keep that block authoritative —
-this table is the human-readable mirror.
+| `prepareWorkspace(ctx)` | result object | Optional synchronous hook for harness-owned workspace state, such as trust configuration. |
+| `isSpawnStartupEvent(event)` | boolean | Optional startup-event classifier used by the spawn-phase watchdog. |
+| `shouldSuppressPostMutationError(ctx)` | boolean | Optional harness quirk policy for an error received after a confirmed mutation. |
+| `buildWorkerArgs(opts)` | string[] | Required with `acpWorkerPool`; owns persistent-worker CLI flags. |
+| `encodePooledOutput(event)` | string | Required with `acpWorkerPool`; translates semantic pooled events into the adapter's normal parser format. |
+| `detectPermissionGate`, `getPromptDeliveryMode`, `usesSystemPromptFile`, `classifyFailure` | misc | Adapter-owned policy that orchestration reads through the facade instead of branching on `runtime.name`. |
+
+`engine/runtimes/contract.js` is authoritative. Registration normalizes legacy
+partial test/tooling adapters, validates bundled adapters strictly, and rejects
+an explicit unsupported `apiVersion`.
+
+### Stable invocation boundary
+
+Minions passes semantic values such as `model`, `effort`, and `sessionId`; it
+does not construct harness CLI argv. The selected adapter:
+
+1. maps its config through `resolveInvocationOptions()`;
+2. receives the full options object through an opaque base64url JSON
+   `--runtime-options` channel when the spawn wrapper is used; and
+3. converts those options to real CLI flags only in `buildArgs()`.
+
+Legacy named wrapper flags remain for backward compatibility, but they are no
+longer the extension point. A new harness option can be added entirely inside
+its adapter without teaching `engine.js`, `engine/llm.js`, or
+`engine/spawn-agent.js` another CLI flag. Large image payloads are written to a
+protected per-call sidecar; only its path enters the options argument, and the
+wrapper hydrates then deletes it before invoking the adapter.
+
+Retirement gates for the temporary compatibility surfaces are tracked in
+`docs/deprecated.json`: `legacy-runtime-named-spawn-flags`,
+`versionless-runtime-adapter-compat`, and
+`preapprove-workspace-mcps-wrapper`. Calendar dates never override their
+external-usage gates.
 
 ## Capability Flags
 
@@ -81,7 +112,7 @@ real behavioral split appears between adapters.
 | `resumePromptCarryover` | ✗ | ✓ | ✓ | CC resume turns prepend recent visible Q&A in stdin when the runtime session store is opaque to Minions. |
 | `resumeBookkeepingTurn` | ✓ | — | — | Claude CLI injects a synthetic "Continue from where you left off." meta turn on `--resume`; CC prompts must tell the model not to treat it as user intent. |
 | `streamConsumer` | ✓ | ✓ | ✓ | Adapter implements `createStreamConsumer(ctx)` — required by `engine/llm.js` accumulator. |
-| `imageInput` | ✓ | ✓ | ✗ | Runtime accepts `images: [{mimeType, dataBase64}]` and delivers them to the CLI. Claude: Anthropic Messages base64 content-block envelope via `--input-format stream-json`. Copilot: base64 payloads materialized to tmp files and passed as `--attachment <path>` (W-mqv7324u0021db5d). When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
+| `imageInput` | ✓ | ✓ | ✓ | Runtime accepts `images: [{mimeType, dataBase64}]` and delivers them to the CLI using adapter-owned transport. When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
 | `acpWorkerPool` | ✗ | ✓ | ✗ | Runtime supports `<bin> --acp` (Agent Client Protocol), so it can be routed through a persistent worker pool instead of cold-spawning a fresh CLI process per turn/dispatch. Two independent consumers gate on this flag: `engine/cc-worker-pool.js` (CC/doc-chat tabs, `resolveCcUseWorkerPool`) and `engine/agent-worker-pool.js` (fleet agent dispatch, `resolveAgentUseWorkerPool`). Both resolvers hard-return `false` whenever this flag isn't `true` on the resolved runtime, regardless of any operator override, so a future non-ACP runtime can never be silently pooled. See [ACP Worker Pool](#acp-worker-pool-fleet-agent-dispatch) below. |
 
 When a behavior is genuinely uniform across all current adapters, it still gets
@@ -197,9 +228,9 @@ agent fleet to Copilot, and vice versa. Both paths fall through to
 `engine.defaultCli` (the fleet-wide default), but they never see each other's
 overrides.
 
-Six helpers in `engine/shared.js` are the single source of truth for runtime/model
-resolution. Engine code MUST go through them instead of reading config keys
-directly.
+The helpers in `engine/shared.js` are the single source of truth for
+runtime/model and cross-runtime policy resolution. Engine code MUST go through
+them instead of reading config keys directly.
 
 | Helper | Chain |
 |--------|-------|
@@ -207,6 +238,7 @@ directly.
 | `resolveCcCli(engine)` | `engine.ccCli` → `engine.defaultCli` → `'copilot'` |
 | `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → undefined |
 | `resolveCcModel(engine)` | `engine.ccModel` → `engine.defaultModel` → undefined |
+| `resolveAgentAllowedTools(config)` | Legacy `config.claude.allowedTools` fleet ceiling → undefined. Despite its legacy namespace, it applies to every selected runtime. |
 | `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd`. Honors literal `0`. |
 | `resolveAgentBareMode(agent, engine)` | `agent.bareMode` → `engine.claudeBareMode` → false. Strict null check so per-agent `false` overrides engine `true`. |
 
@@ -285,8 +317,9 @@ codifies are documented in [`docs/harness-propagation.md`](./harness-propagation
 
 ## The "No Runtime-Name Branching" Rule
 
-The whole point of this layer: **engine code MUST gate behavior on
-`runtime.capabilities.*` flags, not on `runtime.name === 'claude'` comparisons.**
+The whole point of this layer: **orchestration code MUST use the runtime facade,
+capabilities, and adapter hooks rather than concrete imports, harness config
+keys, or `runtime.name === 'claude'` comparisons.**
 
 If you find yourself wanting to write `if (runtime.name === 'copilot')` in
 engine code, the correct response is one of:
@@ -296,19 +329,18 @@ engine code, the correct response is one of:
 3. Move the special case into the adapter's `buildArgs` / `buildPrompt` /
    `parseOutput` where it belongs.
 
-Tests in `test/unit/runtime-adapters.test.js` and `test/unit/copilot-adapter.test.js`
-enforce the contract; the source-inspection tests in `test/unit.test.js` look
-for `resolveRuntime(...)` call sites and reject runtime-name comparisons in new
-code.
+Tests in `test/unit/runtime-adapters.test.js` enforce the contract.
+`test/unit/runtime-boundary.test.js` rejects concrete adapter imports,
+runtime-name branches, and harness-specific invocation config in core paths.
 
 ## Adding a New Runtime
 
-1. Create `engine/runtimes/<name>.js` implementing the full adapter contract.
-   Copy `claude.js` as the template and override only the members that differ.
-   Set a useful `installHint`.
+1. Create `engine/runtimes/<name>.js` implementing adapter API version `1`.
+   Keep all CLI flags, output schemas, workspace quirks, and worker behavior in
+   that file. Set a useful `installHint`.
 2. Register it in `engine/runtimes/index.js`:
    ```js
-   registry.set('<name>', require('./<name>'));
+   registerRuntime('<name>', require('./<name>'), { strict: true });
    ```
 3. Add unit coverage modeled on `test/unit/runtime-adapters.test.js`.
 
@@ -324,6 +356,6 @@ flags — never special-case in engine code.
 - `docs/copilot-cli-schema.md` — empirical Copilot CLI behavior captured during
   the spike that produced the Copilot adapter; cite it when changing
   Copilot-specific capability flags.
-- `engine/runtimes/claude.js` JSDoc header — authoritative adapter contract.
+- `engine/runtimes/contract.js` — authoritative adapter contract and facade.
 - `engine/shared.js` `resolveAgentCli` / `resolveCcCli` etc. — the only
   supported way to read runtime / model selection from config.

package/docs/skills.md

@@ -4,6 +4,8 @@ Agents emit a fenced `skill` block when they discover a durable, reusable workfl
 
 The engine extracts valid blocks from agent stdout and from inbox findings (`notes/inbox/*.md`) and writes them into the selected runtime's native personal skills directory (e.g. `~/.claude/skills/<name>/SKILL.md` for Claude, the equivalent personal skills directory for Copilot). Project-scoped skills are landed via PR into the matching project's playbook tree.
 
+Packaged `scope: minions` skills are synchronized into every registered runtime's personal skill directory during `minions init` and upgrades. A packaged skill replaces an existing same-name personal copy so contract fixes take effect immediately.
+
 ## Block format
 
 ````

package/docs/workspace-manifests.md

@@ -54,7 +54,7 @@ A config that never mentions `workspace_manifest` produces the exact same dispat
 | Phase | Location | What it does |
 | ----- | -------- | ------------ |
 | **Dispatch — repo gate** | `engine.js spawnAgent()` (right after project resolution) | Calls `shared.agentCanUseRepo(agent, project)`. Mismatch → `completeDispatch(... FAILURE_CLASS.WORKSPACE_MANIFEST_REPO, agentRetryable: false)` and `cleanupTempAgent` runs. Non-retryable because the structural answer is "widen the manifest or pick a different agent". |
-| **Spawn — tool merge** | `engine.js spawnAgent()` → `_buildAgentSpawnFlags(..., allowedTools)` | `shared.mergeManifestAllowedTools(claudeConfig.allowedTools, manifest.allowed_tools)` produces the intersection of the runtime baseline and the manifest list. Result is passed as `--allowedTools <csv>` to Claude / Copilot / Codex, so the CLI itself enforces the narrowed surface. Empty manifest list (`[]`) = deny-all. Same merge runs on the steering-resume codepath. |
+| **Spawn — tool merge** | `engine.js spawnAgent()` → `_buildAgentSpawnFlags(..., allowedTools)` | `shared.resolveAgentAllowedTools(config)` preserves the legacy fleet baseline for every selected runtime, then `shared.mergeManifestAllowedTools(baseline, manifest.allowed_tools)` produces the intersection. Result is passed through the Claude / Copilot / Codex adapter option path. Empty manifest list (`[]`) = deny-all. Same resolved option bag is reused on the steering-resume codepath. |
 | **Agent context** | Future work (playbook.js) | Manifest can be surfaced into the agent prompt so the agent sees its declared scope. Today, `shared.resolveAgentManifest(agent)` returns the resolved struct any caller can read. |
 | **URL fetch** | Advisory today | `allowed_external_urls` is validated at config load. No runtime helper function — a future runtime adapter hook can wire URL-fetch intercepts against the manifest. |
 | **Memory scope** | Advisory today | `memory_scope` field is stored in the manifest (`private` = agent only sees its own `knowledge/agents/<id>.md`; `shared` = full team knowledge (current default); `read-only-shared` = reads shared memory but should not write inbox/notes). No runtime enforcement helper — full enforcement at the consolidation layer is future work. |

package/docs/worktree-lifecycle.md

@@ -47,6 +47,20 @@ recycle worktree dirs across branches.
   → `git checkout --detach origin/<main>` → mark IDLE.
 - **State** in SQLite (`worktree_pool`); git ops outside the transaction.
 
+## Fresh ordinary branch bases
+
+When the pool is disabled or has no usable entry, a brand-new ordinary mutating
+branch is created only after `git fetch origin <mainBranch>` succeeds, and its
+base is always `origin/<mainBranch>`. A network or authentication failure stops
+before `git worktree add` or agent spawn and leaves the work item retryable; the
+engine never falls back to a potentially stale local `<mainBranch>`.
+
+This fail-closed rule applies only when the requested branch is confirmed absent
+from origin. PR-targeted / `useExistingBranch`, shared-branch, and retry paths
+that intentionally preserve an existing branch continue using that branch
+unchanged. Warm-pool borrowing keeps its existing fetch-and-checkout of
+`origin/<mainBranch>`.
+
 ## Ownership marker is never "dirty" (#284)
 
 The reused-worktree preflight (`assertCleanSharedWorktree`) builds its

package/engine/acp-transport.js

@@ -2,12 +2,12 @@
  * engine/acp-transport.js — Shared ACP (Agent Client Protocol) transport layer
  * (P-4c6e8a72, extracted from engine/cc-worker-pool.js).
  *
- * `copilot --acp` is a long-lived JSON-RPC server over stdin/stdout. This
- * module owns the protocol-level plumbing that is identical regardless of
- * WHO is pooling the worker (a CC/doc-chat tab vs. a fleet agent dispatch):
+ * ACP-capable harnesses expose a long-lived JSON-RPC server over stdin/stdout.
+ * This module owns protocol plumbing that is identical regardless of which
+ * adapter or consumer is using the worker:
  *
- *   - process spawn (`spawnAcp`) — resolves the `copilot` binary via the
- *     runtime adapter and launches it with `--acp`.
+ *   - process spawn (`spawnAcp`) — delegates binary and argv construction to
+ *     the selected runtime adapter.
  *   - newline-delimited JSON-RPC framing, request/response correlation, and
  *     `session/update` notification dispatch (the `Worker` class).
  *   - typed error envelope (`ERROR_CODES` / `typedError`).
@@ -45,6 +45,12 @@
 
 const { spawn } = require('child_process');
 const crypto = require('crypto');
+const { normalizeExecutionModel } = require('./execution-model');
+const {
+  resolveRuntime,
+  resolveRuntimeByCapability,
+  buildWorkerArgs,
+} = require('./runtimes');
 
 // W-mpmwxni2000c25c7-c — typed error codes the transport emits through every
 // failure exit so a consumer (CC streaming handler / doc-chat pool wrapper /
@@ -56,8 +62,7 @@ const ERROR_CODES = Object.freeze({
   // 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
+  // session/new), or session/new returned no
   // sessionId. Retriable: the caller swaps to a fallback model / a re-auth
   // may unblock the next attempt.
   ACP_HANDSHAKE_FAILED: 'acp-handshake-failed',
@@ -89,25 +94,29 @@ function typedError(message, code, retriable = true) {
 // same knob instead of hardcoding their own copy.
 const WARM_MAX_CONCURRENT = 3;
 
-// Real spawn implementation — resolves `copilot` through the runtime adapter
-// so every ACP transport consumer gets the SAME native/leadingArgs contract
-// as the only other spawn site (engine/spawn-agent.js ~line 595). A bare
-// `spawn('copilot', {shell:false})` cannot exec a `.cmd`/`.ps1`/extensionless
-// npm shim on Windows — it ENOENTs instantly (copilot issue #2370 /
-// W-mqid8uev). resolveBinary() resolves the real JS entry
-// (node_modules/@github/copilot/index.js) and reports whether to spawn it
-// directly (native) or under the current Node process (shim).
-function spawnAcp({ cwd, env } = {}) {
-  const copilot = require('./runtimes/copilot');
+function resolveWorkerRuntime(runtime) {
+  const adapter = typeof runtime === 'string'
+    ? resolveRuntime(runtime)
+    : (runtime || resolveRuntimeByCapability('acpWorkerPool'));
+  if (adapter?.capabilities?.acpWorkerPool !== true) {
+    throw new Error(`Runtime "${adapter?.name || '<unknown>'}" does not support ACP workers`);
+  }
+  return adapter;
+}
+
+// Real spawn implementation. Binary resolution and worker argv are both
+// adapter-owned so harness CLI flag changes do not leak into the transport.
+function spawnAcp({ runtime, cwd, env } = {}) {
+  const adapter = resolveWorkerRuntime(runtime);
   const workerEnv = env || process.env;
-  const resolved = copilot.resolveBinary({ env: workerEnv });
+  const resolved = adapter.resolveBinary({ env: workerEnv });
   if (!resolved || !resolved.bin) {
     throw new Error(
-      `copilot binary not resolvable -- ${copilot.installHint || 'install the GitHub Copilot CLI'}`
+      `${adapter.name} binary not resolvable -- ${adapter.installHint || `install the ${adapter.name} CLI`}`
     );
   }
   const { bin, native, leadingArgs = [] } = resolved;
-  const acpArgs = [...leadingArgs, '--acp', '--allow-all', '--max-autopilot-continues', '1'];
+  const acpArgs = [...leadingArgs, ...buildWorkerArgs(adapter, { cwd, env: workerEnv })];
   // Mirror engine/spawn-agent.js: native binaries run directly; a non-native
   // (JS entry / npm shim) runs under process.execPath as `node <bin> ...`.
   const execBin = native ? bin : process.execPath;
@@ -181,6 +190,19 @@ function buildSessionNewParams({ cwd, mcpServers, model, effort }) {
   return params;
 }
 
+function extractSessionModel(result) {
+  for (const value of [
+    result?.models?.currentModelId,
+    result?.currentModelId,
+    result?.modelId,
+    result?.model,
+  ]) {
+    const model = normalizeExecutionModel(value);
+    if (model) return model;
+  }
+  return null;
+}
+
 function extractChunkText(content) {
   if (content == null) return '';
   if (typeof content === 'string') return content;
@@ -246,9 +268,11 @@ function mapAcpToolCallToToolUse(update) {
  */
 class Worker {
   constructor({
+    runtime,
     id, model, effort, mcpServers, mcpServersHash, processEnv, processContextHash,
     systemPromptHash, cwd, internals, trace,
   }) {
+    this.runtime = resolveWorkerRuntime(runtime);
     this.id = id;
     this.model = model;
     this.effort = effort;
@@ -283,13 +307,11 @@ class Worker {
   async _spawnAndInit() {
     let proc;
     try {
-      proc = this._internals.spawnAcp({ cwd: this.cwd, env: this.processEnv });
+      proc = this._internals.spawnAcp({ runtime: this.runtime, cwd: this.cwd, env: this.processEnv });
     } catch (err) {
-      // 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.
+      const hint = this.runtime.workerErrorHint || `${this.runtime.name} persistent worker failed`;
       throw typedError(
-        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`,
+        `${hint} (${err.message})`,
         ERROR_CODES.WORKER_SPAWN_FAILED,
         true
       );
@@ -307,11 +329,9 @@ class Worker {
     const earlyExitPromise = new Promise((_, reject) => {
       earlyExitReject = (code) => {
         this.killed = true;
-        // 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 hint = this.runtime.workerErrorHint || `${this.runtime.name} persistent worker failed`;
         const err = typedError(
-          `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (exit ${code})`,
+          `${hint} (exit ${code})`,
           ERROR_CODES.ACP_HANDSHAKE_FAILED,
           true
         );
@@ -327,8 +347,9 @@ class Worker {
       // 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 hint = this.runtime.workerErrorHint || `${this.runtime.name} persistent worker failed`;
       const wrapped = typedError(
-        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`,
+        `${hint} (${err.message})`,
         ERROR_CODES.WORKER_SPAWN_FAILED,
         true
       );
@@ -350,11 +371,13 @@ class Worker {
         earlyExitPromise,
       ]);
       this.sessionId = result && result.sessionId;
+      this.currentModel = extractSessionModel(result) || normalizeExecutionModel(this.model);
       if (!this.sessionId) {
         // Handshake completed without an error but the daemon didn't hand
         // back a sessionId — protocol violation or partial init failure.
+        const hint = this.runtime.workerErrorHint || `${this.runtime.name} persistent worker failed`;
         throw typedError(
-          'copilot --acp failed -- session/new returned no sessionId',
+          `${hint} (session/new returned no sessionId)`,
           ERROR_CODES.ACP_HANDSHAKE_FAILED,
           true
         );
@@ -369,7 +392,7 @@ class Worker {
       // 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',
+        `${this.runtime.name} persistent worker process exited`,
         ERROR_CODES.WORKER_DIED,
         true
       );
@@ -563,7 +586,8 @@ class Worker {
     this._notify('session/cancel', { sessionId: this.inflight.sessionId });
   }
 
-  async newSession({ mcpServers, systemPromptHash, model, effort, cwd }) {
+  async newSession(options = {}) {
+    const { mcpServers, systemPromptHash, model, effort, cwd } = options;
     // Cancel any inflight before swapping the underlying session.
     if (this.inflight) {
       this.cancel();
@@ -582,8 +606,9 @@ class Worker {
     // Bug B (issue #2479): if the caller is rotating the session because the
     // system prompt changed, they may also be passing a fresh model/effort —
     // update bookkeeping BEFORE session/new so the new fields land on the
-    // daemon. Falls through to whatever we already had when callers omit them.
-    if (model !== undefined) this.model = model;
+    // daemon. An explicit `model: undefined` clears a prior pooled override and
+    // lets the new session select its own default.
+    if (Object.prototype.hasOwnProperty.call(options, 'model')) this.model = model;
     if (effort !== undefined) this.effort = effort;
     // agent-worker-pool.js reuses a warm worker across dispatches with
     // different cwds (unlike cc-worker-pool.js, whose tabs never change
@@ -593,6 +618,7 @@ class Worker {
       cwd: this.cwd, mcpServers: mcpServers || [], model: this.model, effort: this.effort,
     }));
     this.sessionId = result && result.sessionId;
+    this.currentModel = extractSessionModel(result) || normalizeExecutionModel(this.model);
     this.systemPromptHash = systemPromptHash;
     this.firstSystemPromptSent = false;
   }
@@ -623,11 +649,13 @@ module.exports = {
   ERROR_CODES,
   typedError,
   spawnAcp,
+  resolveWorkerRuntime,
   killImmediate,
   hashMcpServers,
   hashProcessContext,
   buildTrustedSessionContext,
   buildSessionNewParams,
+  extractSessionModel,
   extractChunkText,
   mapAcpToolCallToToolUse,
   Worker,

package/engine/ado-comment.js

@@ -106,6 +106,7 @@ async function _defaultAcquireToken() {
  * @param {string} args.agentId        minions agent id (marker)
  * @param {string} args.kind           comment kind (marker)
  * @param {string} [args.workItemId]   originating work-item id (marker)
+ * @param {string} [args.model]        concrete runtime execution model
  * @param {number} [args.timeoutMs=30000]
  * @param {Function} [args.acquireToken]  () => Promise<string> — injectable token source
  * @param {Function} [args.fetchImpl=fetch] injectable fetch
@@ -120,6 +121,7 @@ async function postAdoPrComment({
   agentId,
   kind,
   workItemId,
+  model,
   resolved = false,
   timeoutMs = 30000,
   acquireToken = _defaultAcquireToken,
@@ -131,7 +133,7 @@ async function postAdoPrComment({
   _validatePrNumber(prNumber);
 
   // buildMinionsCommentBody validates marker fields and throws on bad input.
-  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body });
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, model, body });
 
   const token = await acquireToken();
   if (!token || typeof token !== 'string') {