@yemi33/minions 0.1.2381 → 0.1.2383

package/docs/claude-md-propagation.md

@@ -0,0 +1,118 @@
+# CLAUDE.md propagation to non-Claude runtimes
+
+**Work item:** W-mrdon0pe000l045a
+**Config flag:** `engine.propagateClaudeMdForNonClaudeRuntimes` (default `true`)
+**Per-project override:** `project.propagateClaudeMdForNonClaudeRuntimes`
+**Module:** `engine/claude-md-context.js` · **Injection:** `engine/playbook.js`
+
+## Problem
+
+`CLAUDE.md` auto-discovery is a **Claude-Code-CLI-only** convention — the `claude`
+binary reads repo-authored `CLAUDE.md` files itself at startup (unless `--bare`).
+The **Copilot** and **Codex** runtimes have **no equivalent auto-load** for
+`CLAUDE.md` at all. So repo-authored `CLAUDE.md` files — which frequently carry
+load-bearing "must be kept in sync" instructions and name blessed tooling — are
+structurally invisible to a Copilot/Codex-based fleet.
+
+### Motivating incident
+
+`W-mrdkv6zc00071fef` (a `fluidclientframework.android` dependency bump in
+`office/src`) missed a **third** sync-point file (`settings.gradle.kts:116`) that
+`loop/app/android/android/CLAUDE.md` explicitly warns about, and that
+`updateDeps.bat` (named in that same `CLAUDE.md`) would have caught via its build
+verification step. Neither the implementer nor the reviewer ever saw that file's
+content because Copilot has no `CLAUDE.md` auto-load mechanism. Propagating
+`CLAUDE.md` content directly addresses recurrence of this bug class.
+
+## Relationship to Copilot's native `AGENTS.md` discovery (NOT the same gap)
+
+Copilot has its **own native `AGENTS.md` auto-load**, which (post-#817, "Delegate
+repository harness discovery to native runtimes") Minions leaves to the runtime
+CLI itself rather than suppressing or synthesizing.
+
+`CLAUDE.md` propagation is **independent and additive**:
+
+- `CLAUDE.md` carries **zero split-brain risk** for Copilot/Codex, because those
+  runtimes **never read it themselves** — there is nothing to conflict with.
+- Therefore propagation is **orthogonal** to Copilot's native `AGENTS.md`
+  discovery: whether or not the runtime loads its own `AGENTS.md` has **no
+  effect** on `CLAUDE.md` propagation.
+
+| Concern | Owner | What governs it |
+|---------|-------|-----------------|
+| Copilot's OWN `AGENTS.md` auto-load | the Copilot CLI (native) | delegated to the runtime; Minions does not suppress or synthesize it |
+| Repo `CLAUDE.md` invisible to non-Claude runtimes | `propagateClaudeMdForNonClaudeRuntimes` | injects a "Project instructions (CLAUDE.md)" prompt layer |
+
+## Capability flag
+
+Each runtime adapter (`engine/runtimes/<name>.js`) declares
+`capabilities.claudeMdNativeDiscovery`:
+
+| Runtime | `claudeMdNativeDiscovery` | Propagation |
+|---------|---------------------------|-------------|
+| `claude` | `true` | **skipped** — the Claude CLI already reads CLAUDE.md; re-injecting would double it |
+| `copilot` | `false` | **injected** |
+| `codex` | `false` | **injected** |
+
+Unknown runtimes are treated as **not** auto-discovering (propagate), since an
+unrecognized runtime is far more likely to lack native CLAUDE.md loading than to
+have it. Engine code gates on the capability flag, never on `runtime.name`.
+
+## Bounded discovery algorithm
+
+`office/src` is a huge monorepo — a full tree walk collecting every `CLAUDE.md`
+is not viable. Instead the module mirrors how a human/tool resolves "nearest
+applicable instructions":
+
+1. **Collect path hints** for the dispatch (`engine.js#_deriveClaudeMdPathHints`):
+   `item.meta.workdir` and `item.references[*].path`.
+2. **Walk UP** from each hint directory toward the **project root**, `stat`-ing
+   `CLAUDE.md` at each ancestor level (`discoverClaudeMdFiles`).
+3. **Always include the project-root `CLAUDE.md`** as a fallback — if there are
+   no path hints, at minimum the project root is checked (discovery is never
+   skipped entirely).
+4. **Nearest-wins ordering:** deepest directory first, project root last, so the
+   most specific instructions lead.
+5. **Bounds (cheap by construction):**
+   - `MAX_WALK_DEPTH = 24` ancestor levels per hint (deep-path guard),
+   - `MAX_FILES = 8` total collected files,
+   - path-traversal guard — hints that escape the project root are dropped,
+   - the walk **never ascends above the project root**.
+
+This only `stat`s `CLAUDE.md` at a small number of ancestor directories, so it
+does not meaningfully slow dispatch even in a monorepo.
+
+## Injection & byte cap
+
+`engine/playbook.js#renderPlaybook` adds `CLAUDE.md` propagation as a context
+layer alongside the existing `pinned.md` → `notes.md` →
+`knowledge/agents/<agentId>.md` layers:
+
+- Header: `## Project instructions (CLAUDE.md)`, with a short provenance note so
+  the agent understands why it appears and that "keep in sync" rules are
+  authoritative.
+- Content is wrapped in an `<UNTRUSTED-INPUT>` fence (repo-authored, semi-trusted).
+- Each file is labeled by its repo-relative path (`### <relPath>`).
+- The whole block is capped at `ENGINE_DEFAULTS.maxNotesPromptBytes` (the same
+  budget the sibling notes / agent-memory layers use), so it can never balloon a
+  prompt on a large monorepo. Individual files are truncated with a
+  "read the full file if needed" marker when they exceed the remaining budget.
+
+Injection only happens when **all** hold:
+
+1. the resolved runtime's `claudeMdNativeDiscovery` is falsy (Copilot/Codex),
+2. `resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)` returns true,
+3. the project has a `localPath`, and
+4. at least one non-empty `CLAUDE.md` was discovered.
+
+## Config resolution
+
+`shared.resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)`:
+
+1. per-project boolean `project.propagateClaudeMdForNonClaudeRuntimes`, else
+2. fleet-wide boolean `engine.propagateClaudeMdForNonClaudeRuntimes`, else
+3. hardcoded default `true`.
+
+Only an explicit boolean counts as "set" at either level (undefined/null/string
+fall through). Editable from **Settings → Copilot Tuning → "Propagate CLAUDE.md
+to non-Claude runtimes"** or via `POST /api/settings`.

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/engine-restart.md

@@ -70,6 +70,16 @@ If an agent is killed as an orphan and the work item retries, cooldowns use expo
 
 The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/supervisor.js#checkEngine` (dead-PID), `engine/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
 
+### 7. Exclusive Restart Topology
+
+Managed dashboard spawns must bind the requested port; automatic fallback remains available only for standalone `node dashboard.js` use. Before a supervisor respawn, every matching stale daemon is killed and confirmed dead. If any PID survives, the supervisor skips the replacement and retries on its next tick instead of creating a second engine or a dashboard on another port.
+
+`minions restart` verifies ownership of the exact engine, dashboard, and supervisor PIDs it spawned and rejects duplicate daemon processes. A failed verification tears down the partial stack and leaves `stop-intent.json` set so watchdogs cannot race another replacement into the failed topology.
+
+PID-bearing file locks are reaped immediately when their recorded owner is dead. The five-minute stale threshold remains for legacy locks without owner metadata and the longer safety window remains for live holders.
+
+Dashboard hot polling avoids recurring event-loop stalls: freshness-directory walks are coalesced briefly, plan scans are cached for 30 seconds and processed in cooperative batches, and quarantine-ref Git reads run asynchronously in parallel.
+
 ## Safe Restart Pattern
 
 ```bash

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
@@ -77,6 +91,15 @@ distinguishes the **original worktree-preflight issue** from a
 
 ## Quarantine path (dirty / divergent)
 
+Before quarantine, a reused worktree that is filesystem-clean and strictly
+ahead of `origin/<branch>` is pushed fast-forward to origin. Dispatch close
+and stale-orphan cleanup run the same preservation check before pool return or
+worktree removal. Dirty trees and branches confirmed behind origin retain the
+quarantine fallback; transient probe, fetch, auth, and push failures leave clean
+ahead commits in place for retry. Recoverable
+`refs/minions/quarantine/*` and `refs/minions/quarantine-wip/*` refs are listed
+on Dashboard → Engine under **Quarantined Work**.
+
 When `discoverFromWorkItems` finds a worktree in a `WORKTREE_DIRTY`,
 `WORKTREE_DIVERGENT`, or post-stuck state, `_quarantineDirtyWorktree`
 moves it to `<root>/.quarantined/<basename>-<utc>` and lets the next tick

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') {