@yemi33/minions 0.1.2424 → 0.1.2425

package/docs/qa-runbook-lifecycle.md

@@ -10,18 +10,18 @@ W-mpdad3mq000m53bb).
 ## Runbook location
 
 `<MINIONS_DIR>/projects/<project-name>/runbooks/<runbook-id>.json`. Each entry:
-`{ id, name, target, steps, expectedArtifacts, createdAt, createdBy }`.
-CRUD via `GET/POST /api/qa/runbooks` (POST returns the new runbook with
-engine-assigned `id`). `target` is a name from `/api/managed-processes` or
+`{ id, name, project, targetName, steps, expectedArtifacts, createdAt, updatedAt }`.
+CRUD via `GET/POST /api/qa/runbooks`; POST accepts the full spec, including the
+caller-supplied kebab-case `id`, and returns the saved record. `targetName` is a name from `/api/managed-processes` or
 `/api/keep-processes` (deduped by `<project>::<name>`, managed wins).
 
 ## Run-record path
 
-The SQL `qa_runs` table stores newest-first, capped run records. Each run:
-`{ id, runbookId, runbookName, target, status, startedAt, completedAt, workItemId, agentId, artifacts }`.
-`status` ∈ `pending|dispatched|running|passed|failed|error`. Created by
-`POST /api/qa/runbooks/run` (`{ id }`), which dispatches a `qa-validate`
-work item and seeds the run with `dispatched`. Read via
+The SQL `qa_runs` table stores capped run records, sorted newest-first on read. Each run:
+`{ id, runbookId, targetName, project, workItemId, status, startedAt, completedAt, artifacts, summary, createdAt }`.
+`status` ∈ `pending|running|passed|failed|errored`. Created by
+`POST /api/qa/runbooks/run` (`{ runbookId, targetName, agent? }`), which dispatches a `qa-validate`
+work item and seeds the run with `pending`. Read via
 `GET /api/qa/runs?limit=50` — UI polls every 5s while the QA page is active
 and clears the interval on page navigation via the `switchPage` wrapper in
 `dashboard/js/qa.js` (matches `_stopPlanPoll`/`_stopMeetingPoll` pattern in
@@ -49,46 +49,53 @@ only), confirms with the user, and surfaces success/error via
 
 ## Artifact contract
 
-`engine/qa-artifacts/<runId>/<file>`, served via
-`GET /api/qa/artifacts/<runId>/<file>`. Files are agent-uploaded screenshots,
-video recordings, and log captures listed in the run record's
-`artifacts: [{ file, kind }]`. UI auto-detects:
+Artifacts live at `<MINIONS_DIR>/engine/qa-artifacts/<runId>/<path>`, served via
+`GET /api/qa/artifacts/<runId>/<path>`. `createRun()` pre-creates the per-run
+directory, and the rendered QA prompt injects its absolute path as
+`qa_artifacts_dir` so project-worktree agents write to the engine-owned
+directory rather than their disposable worktree. The agent lists metadata in
+the result sidecar using paths relative to the run's artifact directory as
+`artifacts: [{ type, path, label, capturedAt }]`. UI auto-detects:
 `screenshot`/`png|jpg|jpeg|gif|webp|svg` → `<img>`;
 `video`/`mp4|webm|ogg|mov` → `<video controls>`; everything else → log
 preview (first 40 lines fetched lazily) with a `View full` link to the same
 endpoint. **No direct filesystem paths are exposed** — every artifact URL
 goes through `/api/qa/artifacts/` so path traversal is server-gated.
-Optional config: `engine.qaArtifactsMaxBytes` caps per-file upload size;
-when set, dashboard Settings exposes a matching toggle (CLAUDE.md
-best-practice #15).
+There is no configurable per-file size cap or completion-time copy step.
 
 ## Agent sidecar shape
 
-The `qa-validate` agent writes `agents/<id>/qa-run.json` before exit:
+The retired draft path `agents/<id>/qa-run.json` is not consumed.
+The `qa-validate` agent writes the injected absolute `qa_result_sidecar` path,
+which resolves to `<MINIONS_DIR>/agents/<id>/qa-run-result.json`, before exit:
 
 ```json
-{ "runId": "qa-run-<id>",
-  "status": "passed|failed|error",
+{ "runId": "qarun-<id>",
+  "status": "passed|failed|errored",
   "summary": "...",
-  "artifacts": [ { "file": "dashboard.png", "kind": "screenshot" },
-                 { "file": "test.log",      "kind": "log" } ],
-  "written_by": "<agentId>", "wi_id": "<workItemId>" }
+  "artifacts": [
+    { "type": "screenshot", "path": "engine/qa-artifacts/<runId>/dashboard.png",
+      "label": "Dashboard", "capturedAt": "2026-05-20T20:42:00.000Z" },
+    { "type": "log", "path": "engine/qa-artifacts/<runId>/test.log",
+      "label": "Test log", "capturedAt": "2026-05-20T20:42:00.000Z" }
+  ] }
 ```
 
-The engine reads the sidecar in `onAgentClose`, copies the listed files into
-`engine/qa-artifacts/<runId>/`, and stamps the run record with `status`,
-`completedAt`, and the recorded `artifacts`. Sidecar validation failure is
-non-retryable (`failure_class: invalid-qa-run`); listed files outside the
-agent worktree or larger than `qaArtifactsMaxBytes` are rejected without
-stamping the run.
+Before spawning a run, the engine removes any prior sidecar for that agent.
+`runPostCompletionHooks` then verifies `runId` matches the current run, consumes
+the file exactly once, and stamps the run record with `status`, `completedAt`,
+`summary`, and normalized artifact metadata. Missing, malformed, stale-run, or
+unknown-status sidecars mark the run `errored`. Lifecycle does not copy
+or size-check artifact files; agents must write them to the injected absolute
+artifact directory before exit.
 
 ## Entry point
 
 `playbooks/qa-validate.md`. Dispatched by `POST /api/qa/runbooks/run`;
-receives `target`, `steps`, `expectedArtifacts` as template vars; required
-to write the sidecar above before exit. Routing line in `routing.md` maps
-the synthetic `qa-validate` task-type to the playbook so manual dispatches
-work too.
+receives `target`, `steps`, `expectedArtifacts`, `qa_artifacts_dir`, and
+`qa_result_sidecar` as template vars; required to write the sidecar above
+before exit. Routing line in `routing.md` maps the synthetic `qa-validate`
+task-type to the playbook so manual dispatches work too.
 
 # QA Sessions (PL-qa-sessions)
 
@@ -182,16 +189,17 @@ routing default):
    metadata via `/api/managed-processes/by-name/qa-session-<id>`, calls the
    resolved runner's `generateBrief({target, flowsRaw, capture})` hook, and
    writes the runner-native test file to
-   `engine/qa-tests/<sessionId>/test.<ext>`. The runner's
-   `validateOutputDir` hook gates DRAFT success — a missing or malformed
-   test file lands the session in `failed`. In `confirm` mode the session
-   parks at `awaiting-approval`; in `auto` mode it auto-chains to EXECUTE.
+   the injected absolute `engine/qa-tests/<sessionId>/test.<ext>` path.
+   The completion report's `testFile` value is stored on the session. In
+   `confirm` mode the session parks at `awaiting-approval`; in `auto` mode
+   it auto-chains to EXECUTE.
 
 3. **EXECUTE** (`playbooks/qa-session-execute.md`) runs the drafted test
    against the live spawn via the runner's `executeBrief` hook, captures
    artifacts per `spec.capture: { video, screenshots, logs }`, and writes
-   `agents/<agentId>/qa-run-result.json` — the same sidecar the
-   `qa-validate` runbook flow uses. The existing
+   the injected absolute `qa_result_sidecar` path — the same single-use sidecar
+   the `qa-validate` runbook flow uses. Artifacts go to the injected absolute
+   `qa_artifacts_dir` keyed by the linked QA run id, not the session id. The
    `engine/lifecycle.js#runPostCompletionHooks` `meta.qaRunId` hook ingests
    the sidecar and marks the linked `qa-runs` record terminal; the
    session-level `handleExecuteComplete` then reads the `qa-run` terminal
@@ -212,20 +220,27 @@ Documented in `dashboard.js`; routes are visible at `GET /api/routes`.
 | POST   | `/api/qa/from-prd`                         | "qa this PRD" bridge. Build a QA Session spec from a completed/approved PRD via `engine/qa-from-prd.js` (pure) then reuse `createSession` + `queueSetup`. Body: `{ prd, mode?, runner? }`. Non-ready / unknown / malformed PRD → **400** (`QaFromPrdError.reason`). Returns `sessionId`, `state`, `setupWorkItemId`, `managedSpawnName`, `projects`, `flowSource`, `warnings[]`, `note` (repo-native-harness copy), and optional `runnerHint`. The test is drafted on the repo's native test harness. |
 | GET    | `/api/qa/sessions`                         | List sessions newest-first. Optional `?limit=N` and `?state=pending\|spawning\|drafting\|awaiting-approval\|executing\|done\|failed\|killed`. |
 | GET    | `/api/qa/sessions/<id>`                    | Fetch a single session record by id.                                                                                      |
-| POST   | `/api/qa/sessions/<id>/approve`            | `awaiting-approval → executing`. Server-side creates the linked `qa-runs` record (synthetic `runbookId='qa-session-<id>'`), queues EXECUTE WI, stamps `qaRunId` on the session. |
+| POST   | `/api/qa/sessions/<id>/approve`            | `awaiting-approval → executing`. Accepts no request body. Server-side creates the linked `qa-runs` record (synthetic `runbookId='qa-session-<id>'`), queues EXECUTE WI, stamps `qaRunId` on the session. |
 | POST   | `/api/qa/sessions/<id>/edit`               | `awaiting-approval → drafting`. Body: `{ feedback }`. Re-fires DRAFT with the reviewer feedback threaded into the prompt. |
 | POST   | `/api/qa/sessions/<id>/cancel`             | Non-terminal → `killed`. Optional `{ reason }`. Does NOT touch the managed-spawn — use `/kill` for that.                  |
-| POST   | `/api/qa/sessions/<id>/kill`               | Non-terminal → `killed` AND `removeManagedSpec(<name>)`. Best-effort on the spawn kill (no-op if no spawn).                |
+| POST   | `/api/qa/sessions/<id>/kill`               | Non-terminal → `killed`, then generation-safely removes the primary and every multi-project co-service managed-spawn. Best-effort when a spawn is absent or concurrently replaced. |
 | POST   | `/api/qa/sessions/<id>/dismiss`            | Non-terminal → `done`. Accept the draft as final; leaves spawn alive. Optional `{ summary }`.                              |
 | GET    | `/api/qa/runners`                          | List registered runner adapters (built-ins + `qa-runners.d/` plugins). Metadata only — hooks (functions) are stripped.    |
-| POST   | `/api/qa/runners/reload`                   | Clear in-process registry, re-register built-ins, re-scan `qa-runners.d/` for plugin edits. Returns the fresh runner list. |
+| POST   | `/api/qa/runners/reload`                   | Accepts no request body. Clears the in-process registry, re-registers built-ins, re-scans `qa-runners.d/` for plugin edits, and returns the fresh runner list. |
 | DELETE | `/api/qa/runs/<id>`                        | Hard-delete a single QA run record (terminal-status runs only) and best-effort wipe its artifact directory under `engine/qa-artifacts/<runId>/`. Returns `{ ok: true, id, artifactsRemoved }` on success, `409 not_terminal` for in-flight runs, `404 not_found` for unknown ids. |
 
+The audited contracts returned by `GET /api/routes` expose the canonical enum,
+length, list, nested-field, path, and lifecycle constraints for these routes.
+Validation failures use field/path-aware details and occur before QA records,
+work items, runbooks, plugins, artifacts, or managed processes are mutated.
+Traversal remains `403`, missing resources `404`, and wrong-state conflicts
+`409`.
+
 The single-session POSTs share `_qaSessionAction` in `dashboard.js`; module
 errors are mapped to HTTP via `_qaSessionsErrorToStatus`:
 
 - `'session not found'` → 404
-- `'unsafe sessionId'` / `'invalid spec'` / `'requires …'` (size cap) → 400
+- `'unsafe sessionId'` / `'invalid spec'` / `'requires …'` / `'exceeds …'` (spec or feedback validation) → 400
 - `'illegal state transition'` / `'requires state …'` / `'requires non-terminal'` → 409
 
 ## File locations
@@ -243,14 +258,14 @@ errors are mapped to HTTP via `_qaSessionsErrorToStatus`:
   session's `cancelSession` if the operator opts for the cancel-without-
   spawn-kill path.
 - **EXECUTE artifacts**: same as runbooks — `engine/qa-artifacts/<runId>/`
-  served via `GET /api/qa/artifacts/<runId>/<file>`.
+  served via `GET /api/qa/artifacts/<runId>/<path>`.
 
 ## Runner adapters (P-c4a9e7f3 / P-b8e1d4a6)
 
 Pluggable test-runner registry at `engine/qa-runners.js`. Built-in
-adapters: `playwright` (priority 100, detects `playwright.config.*`),
-`maestro` (priority 80, detects `.maestro/`). Each adapter exports five
-hooks:
+adapters: `playwright` (priority 50, always-true safe default),
+`maestro` (priority 80, detects `.maestro/` and therefore wins when
+present). Each adapter exports five hooks:
 
 - `detect(target, project)` → `boolean`. Auto-detect for blank-runner
   sessions.
@@ -258,8 +273,9 @@ hooks:
   string. Handed to the DRAFT agent so it emits a runner-native test file.
 - `executeBrief({sessionId, target, capture, project})` → instructions /
   command for the EXECUTE agent.
-- `validateOutputDir(dir)` → `{ ok, errors[] }`. Gates the DRAFT → EXECUTE
-  transition.
+- `validateOutputDir(dir)` → `{ ok, errors[] }`. Available to explicit
+  callers and tests; the production DRAFT transition does not invoke it
+  automatically today.
 - `installHint` → string shown when `detect()` returns true but the
   runner CLI is missing.
 
@@ -399,10 +415,10 @@ maps to `POST /api/qa/from-prd` (see `prompts/cc-system.md`).
   `'managed-spawn-healthcheck-failed'`. The `error` field carries the
   reason; check `engine/managed-logs/qa-session-<sessionId>.log` for the
   failing healthcheck.
-- **DRAFT validateOutputDir rejects** → `failure_class:
-  'qa-session-draft-failed'`. Inspect the drafted file at
-  `engine/qa-tests/<sessionId>/`; the runner's `validateOutputDir.errors`
-  array tells you what's missing.
+- **DRAFT agent reports failure** → inspect the DRAFT completion summary and
+  the injected
+  `engine/qa-tests/<sessionId>/` directory. The session failure class is
+  `qa-session-draft-failed` when the agent reports that contract failure.
 - **EXECUTE qa-run terminal status is `failed`/`errored`** →
   `failure_class: 'qa-session-execute-failed'` /
   `'qa-session-execute-errored'`. The linked `qa-runs` record (joined via

package/docs/qa-runbooks.md

@@ -99,7 +99,7 @@ unlink).
 
 The deferred follow-up items (W-mpeiwz6k0005bf34-b/c/d) have since landed. Brief pointers — see [CLAUDE.md](../CLAUDE.md) → "QA validation runs" for the deep dive:
 
-- **Run dispatch + persistence** (`engine/qa-runs.js`): `POST /api/qa/runbooks/run` creates a SQL QA-run record with `status ∈ pending|dispatched|running|passed|failed|error` and dispatches a `qa-validate` work item against the runbook's `target`. Read via `GET /api/qa/runs?limit=N&status=...` and `GET /api/qa/runs/<id>`.
-- **Artifact contract**: the `qa-validate` agent writes `agents/<id>/qa-run.json` before exit; the engine copies listed files into `engine/qa-artifacts/<runId>/` and serves them via `GET /api/qa/artifacts/<runId>/<file>` (path-traversal-gated, 403 on escape). Per-file size cap: `engine.qaArtifactsMaxBytes`.
+- **Run dispatch + persistence** (`engine/qa-runs.js`): `POST /api/qa/runbooks/run` creates a SQL QA-run record with `status ∈ pending|running|passed|failed|errored` and dispatches a `qa-validate` work item against the runbook's `targetName`. Read via `GET /api/qa/runs?limit=N&status=...` and `GET /api/qa/runs/<id>`.
+- **Artifact contract**: the engine pre-creates `engine/qa-artifacts/<runId>/`; the `qa-validate` agent writes files there and records run-root-relative paths in the injected absolute `agents/<id>/qa-run-result.json` path. The engine clears that sidecar before dispatch, verifies its `runId`, and removes it after consumption. Lifecycle persists the metadata, and `GET /api/qa/artifacts/<runId>/<path>` serves root-level or nested files behind traversal guards (403 on escape). There is no `engine.qaArtifactsMaxBytes` setting or copy-on-completion gate.
 - **UI**: `/qa` dashboard page (`dashboard/pages/qa.html`, `dashboard/js/qa.js`) polls `GET /api/qa/runs` every 5s while active; auto-detects screenshots/videos/logs for inline preview.
 - **Playbook**: `playbooks/qa-validate.md` (routed via the synthetic `qa-validate` task-type in `routing.md`).

package/docs/runtime-adapters.md

@@ -1,7 +1,7 @@
 # Runtime Adapters
 
-How Minions abstracts over CLI runtimes (Claude Code, GitHub Copilot CLI, future
-adapters). Engine code never special-cases a runtime by name — every CLI-specific
+How Minions abstracts over CLI runtimes (Claude Code, GitHub Copilot CLI, Codex,
+and future adapters). Engine code never special-cases a runtime by name — every CLI-specific
 behavior is hidden behind an adapter object resolved through `resolveRuntime()`.
 
 ## What lives in `engine/runtimes/`
@@ -33,18 +33,18 @@ methods that genuinely differ.
 |--------|----------------|---------|
 | `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. |
+| `capabilities` | flag object (see below) | Behavioral and declarative flags (see below). |
 | `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` subcommand fallback. |
 | `capsFile` | absolute path | Cache file for `resolveBinary()` results. |
 | `installHint` | string | Surfaced when `resolveBinary()` returns null. Consumed by `engine/preflight.js` and `engine/spawn-agent.js`. |
 | `listModels()` | `Promise<{id,name,provider}[] | null>` | Model catalog or null when discovery isn't supported. |
 | `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). |
+| `spawnScript` | absolute path | Path to the runtime-agnostic spawn wrapper (currently `engine/spawn-agent.js` for all bundled runtimes). |
 | `buildArgs(opts)` | `string[]` | CLI args excluding the binary itself. |
 | `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. |
+| `buildPrompt(promptText, sysPromptText, opts)` | string | Final prompt delivered to the CLI. Adapters that lack `--system-prompt-file` prepend a `<system>` block on fresh calls and omit that replay when `opts.sessionId` resumes an existing session. |
+| `getUserAssetDirs({ homeDir })` | `string[]` | Runtime-native global asset roots exposed by read-only harness diagnostics. |
 | `getSkillRoots({ homeDir, project? })` | `[{ scope, dir, projectName? }]` | Where `collectSkillFiles` looks for native + project skill markdown. |
 | `getSkillWriteTargets({ homeDir, project? })` | `{ personal, project }` | Where `extractSkillsFromOutput` writes auto-extracted skills. |
 | `getResumeSessionId(...)` | string or null | Pre-spawn resume probe; runtime-agnostic stamp prevents cross-runtime session-ID confusion. |
@@ -58,8 +58,9 @@ methods that genuinely differ.
 | `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. |
+| `hasUnfinishedToolCall(raw)` | boolean | Optional truncation detector: `true` when the raw output holds a tool call that was started and never completed. Lets the engine diagnose an exit-0 mid-turn death as `runtime-truncated-exit` instead of the generic `completion-report-missing`. Defaults to `false` when not implemented. |
 | `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. |
+| `encodePooledOutput(event)` | string | Required with `acpWorkerPool`; translates semantic `model` / `chunk` / `result` 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
@@ -89,10 +90,24 @@ Retirement gates for the temporary compatibility surfaces are tracked in
 `preapprove-workspace-mcps-wrapper`. Calendar dates never override their
 external-usage gates.
 
+### Execution model attribution
+
+Dispatch records keep the normalized model sent to the runtime as
+`requestedModel`. Streaming runtimes then replace that provisional evidence with
+their reported model in `executionModel`; pooled ACP dispatches obtain the same
+authoritative value from `session/new.models.currentModelId` and re-emit it in
+the Copilot JSONL shape. Review attribution resolves evidence in this order:
+completion output, captured session output, requested model, then `unknown`.
+`minions pr comment` uses the active dispatch to stamp the shared GitHub/ADO
+marker and visible sign-off, and lifecycle persists the same value as
+`minionsReview.model`. Model catalogs are never used to guess an implicit
+runtime default.
+
 ## Capability Flags
 
-Engine code branches on flags, never on runtime names. Add a flag whenever a
-real behavioral split appears between adapters.
+Engine code branches on consumed flags, never on runtime names. A capability
+may also begin as declarative metadata; add a consumer when orchestration needs
+to act on that behavioral split.
 
 | Flag | Claude | Copilot | Codex | Gates |
 |------|--------|---------|-------|-------|
@@ -104,15 +119,18 @@ real behavioral split appears between adapters.
 | `costTracking` | ✓ | ✗ | ✗ | USD + token counts in the result event. Copilot only emits `premiumRequests`; Codex accounting is not assumed. |
 | `modelShorthands` | ✓ | ✗ | ✗ | Bare `sonnet`/`opus`/`haiku` accepted by Claude only. |
 | `modelDiscovery` | ✗ | ✓ | ✓ | `listModels()` returns a real catalog when supported (Copilot API, Codex `debug models --bundled`). |
+| `strictModelCatalog` | — | — | ✗ | An explicit false lets the runtime validate IDs missing from its cached catalog; Codex uses this because bundled catalogs can lag staged/custom models. |
 | `promptViaArg` | ✗ | ✗ | ✗ | If true, prompt goes via `--prompt <text>` instead of stdin. False for all current runtimes. |
 | `budgetCap` | ✓ | ✗ | ✗ | `--max-budget-usd <n>`. |
 | `bareMode` | ✓ | ✗ | ✗ | `--bare` (suppresses CLAUDE.md auto-discovery). Other runtimes use their own config/suppression knobs. |
+| `claudeMdNativeDiscovery` | ✓ | ✗ | ✗ | Skip engine-side CLAUDE.md propagation when the runtime already loads it natively. |
 | `fallbackModel` | ✓ | ✗ | ✗ | `--fallback-model <id>` on rate-limit. |
 | `sessionPersistenceControl` | ✓ | ✗ | ✗ | Engine writes `session.json`; Copilot and Codex own their runtime stores, while Minions records IDs only for safe resume. |
 | `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 using adapter-owned transport. When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
+| `skillDiscovery` | ✓ | — | — | Currently set only by Claude to declare native `.claude/skills` discovery. It is metadata-only today; core orchestration has no consumer yet. |
 | `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
@@ -120,10 +138,10 @@ a flag if a future runtime might disagree — flags are cheap.
 
 ## ACP Worker Pool (Fleet Agent Dispatch)
 
-Copilot's `acpWorkerPool` capability backs **two** independent opt-in pools that
-avoid cold-spawning a fresh `copilot` CLI process for every turn/dispatch. Both
-share the same spawn + JSON-RPC transport (`engine/acp-transport.js`) but have
-different ownership models:
+The `acpWorkerPool` capability backs **two** independent pools that avoid a
+cold harness spawn for every turn/dispatch. Both share the runtime-neutral
+JSON-RPC transport (`engine/acp-transport.js`); the adapter owns worker argv and
+pooled-output encoding.
 
 | Pool | Module | Ownership model | Config | Default |
 |------|--------|------------------|--------|---------|
@@ -136,14 +154,16 @@ This section covers the fleet agent pool (P-9b3d5f61 / P-1d8f0b93 / P-4c6e8a72).
 
 | Key | Resolver | Chain | Default |
 |-----|----------|-------|---------|
-| `engine.agentUseWorkerPool` | `shared.resolveAgentUseWorkerPool(engine, runtime)` | 1. Hard `false` unless `runtime.capabilities.acpWorkerPool === true` (Copilot only). 2. `engine.agentUseWorkerPool` explicit `true`/`false` override. 3. `ENGINE_DEFAULTS.agentUseWorkerPool`. | `false` |
+| `engine.agentUseWorkerPool` | `shared.resolveAgentUseWorkerPool(engine, runtime)` | 1. Hard `false` unless `runtime.capabilities.acpWorkerPool === true`. 2. `engine.agentUseWorkerPool` explicit `true`/`false` override. 3. `ENGINE_DEFAULTS.agentUseWorkerPool`. | `false` |
 | `engine.agentAcpPoolSize` | `shared.resolveAgentAcpPoolSize(engine)` | 1. `engine.agentAcpPoolSize` (positive number, else ignored). 2. `engine.maxConcurrent` (fleet dispatch concurrency cap). 3. `ENGINE_DEFAULTS.maxConcurrent`. | `ENGINE_DEFAULTS.maxConcurrent` (currently `5`) |
 
-`agentUseWorkerPool` is deliberately **opt-in** (`false` by default), unlike
-`ccUseWorkerPool`'s default-`true` — the fleet dispatch path has a much larger
-MCP-auth-popup / isolation surface than the single CC singleton, so it stays
-off until proven safe in a given operator's environment. `agentAcpPoolSize`
-defaults to the same cap the engine would already use for cold-spawn
+`agentUseWorkerPool` defaults to `false`; `ccUseWorkerPool` remains enabled by
+default for Copilot. Fleet pooling must be explicitly opted into while its
+newer dispatch-lifecycle path stabilizes.
+Work items requesting `meta.keep_processes` always use the cold wrapper, even
+when fleet pooling is enabled, so the established descendant-ownership contract
+remains authoritative.
+`agentAcpPoolSize` defaults to the same cap the engine would already use for cold-spawn
 concurrency (`maxConcurrent`), so enabling the pool never queues more
 concurrent dispatches than the fleet would have run anyway — it only changes
 *how* those dispatches get a CLI process, not how many run at once.
@@ -159,31 +179,65 @@ handlers, PID-file writing, live-output.log, timeout/steering cancel-vs-kill,
 restart-reattach) runs unmodified regardless of whether `proc` is a real OS
 process or a pooled lease. Assignment strategy, in order:
 
-1. A **free** worker whose MCP-server set, process environment, and canonical
-   process cwd already match wins first — reused via a fresh `session/new`, no
-   respawn.
+1. A **free** worker whose MCP-server set and process launch context already
+   match wins first. A persisted session prefers the worker that already owns
+   it; otherwise ACP `session/load` restores it. A dispatch without resume state
+   receives a fresh `session/new`.
 2. Otherwise another free worker is **evicted** (closed) and a replacement is
-   spawned fresh with the requested MCP servers/cwd (MCP servers are resolved
-   at `copilot --acp` process boot, so a changed server set or process cwd
-   requires a full respawn, not just a new session). This prevents a worker OS
-   process rooted in a live operator checkout from carrying that cwd into an
-   isolated worktree dispatch.
+   spawned fresh with the requested MCP servers/cwd/process policy. MCP servers
+   and flags such as `--disable-builtin-mcps`,
+   `--max-autopilot-continues`, and reasoning summaries are process-scoped, so
+   changing them requires a full respawn, not just a new session.
 3. Otherwise, if the pool has room (fewer than `agentAcpPoolSize` workers
    allocated across free + busy + in-flight-spawn), a brand-new worker spawns.
 4. Otherwise the request queues FIFO until a `release()` or worker crash frees
    a slot.
 
+Acquisition is cancellable and the initialize/session handshake is bounded to
+60 seconds. Cancellation quarantines the lease until descendant cleanup
+finishes, then discards that worker so no late response can contaminate another
+dispatch. The engine applies settings every tick: lowering `agentAcpPoolSize`
+immediately closes excess idle workers, and turning `agentUseWorkerPool` off
+closes idle workers while active leases drain.
+
+The facade also mirrors cold-spawn descendant cleanup. It preserves descendants
+that existed before the lease (the worker's MCP subtree), tracks process trees
+created during the lease, validates PID birth identity before killing, honors
+validated `keep_processes` anchors, and reaps the rest before reuse. A worker
+that produced kept descendants is discarded with a root-only kill so those
+anchors survive. Tool-call-triggered snapshots plus a final worktree-CWD holder
+scan catch fast-reparented subprocesses; if cleanup cannot be proven safe, the
+dispatch fails closed.
+The long-lived ACP process itself starts in project-scoped engine scratch while
+each ACP session receives its dispatch worktree as `cwd`; a warm worker therefore
+cannot pin a disposable Windows worktree or mutate the operator checkout through
+its process cwd.
+
 Dispatch records persist `item.pooled = true` in SQLite, not
 just the in-memory `activeProcesses._pooled` flag (which is wiped on engine
 restart) — the on-disk flag is what tells the restart-reattach path
 (`engine/cli.js`) that a live worker PID is a pooled lease, not a resumable
 cold-spawned child process.
+If checkpoint steering hands a pooled dispatch to a detached cold resume,
+the engine clears `pooled` first and replaces the canonical dispatch PID file,
+restoring normal restart reattachment for the resumed process.
+
+On an intentional stop/restart, the fleet pool enters drain mode: new
+acquisitions are rejected, idle workers close immediately, and active leases
+may finish until `engine.shutdownTimeout`. Detached cold-spawn agents are not
+waited on and remain eligible for normal restart reattachment. If the drain
+times out, the engine cancels each pooled facade, awaits its descendant/anchor
+cleanup, and completes its dispatch as a retryable timeout before exiting.
+After an unexpected crash, the persisted
+`pooled` flag still bypasses PID trust and routes the dispatch through orphan
+retry because a replacement engine cannot adopt the old ACP worker's stdio.
 
 ### Isolation tradeoff — read this before enabling `agentUseWorkerPool`
 
-**Enabling the pool bounds the MCP-auth-popup / cross-dispatch isolation risk
-by pool size — it does not eliminate it.** Cold-spawn gives every dispatch its
-own fresh OS process and its own `COPILOT_HOME`; the pool instead keeps up to
+**Enabling the pool bounds cross-dispatch process-state risk by pool size — it
+does not eliminate it.** Lease-created descendants and session state are reset,
+but cold-spawn still gives every dispatch a stronger fresh OS
+process; the pool instead keeps up to
 `agentAcpPoolSize` `copilot --acp` processes warm and reuses them across
 dispatches whenever the MCP-server set matches. Concretely:
 
@@ -199,14 +253,11 @@ dispatches whenever the MCP-server set matches. Concretely:
   size narrows it at the cost of more evictions/respawns (and therefore more
   MCP-auth prompts) when the requested MCP-server set changes between
   dispatches.
-- This mirrors the same tradeoff `engine.ccUseWorkerPool` already accepts for
-  CC tabs (see [docs/command-center.md](./command-center.md)), which is why
-  `agentUseWorkerPool` defaults `false`: the fleet dispatch surface has more,
-  and more varied, work items than a single CC session, so the exposure window
-  per warm worker is larger and the default stays conservative until an
-  operator has evaluated the tradeoff for their own MCP-server set.
-
-Operators enabling `engine.agentUseWorkerPool` should choose `agentAcpPoolSize`
+- This mirrors the same tradeoff `engine.ccUseWorkerPool` accepts for CC tabs
+  (see [docs/command-center.md](./command-center.md)). Operators can explicitly
+  disable either pool when strict per-dispatch process isolation is required.
+
+Operators using `engine.agentUseWorkerPool` should choose `agentAcpPoolSize`
 deliberately: a pool size of `1` gives the strongest isolation (still weaker
 than cold-spawn, since consecutive dispatches on that single worker still
 share process state) at the cost of maximum serialization/respawns; a larger
@@ -314,24 +365,24 @@ if (mappedEffort) args.push('--effort', mappedEffort);
 When `resolveAgentModel` returns undefined the adapter omits `--model` from
 `buildArgs` entirely and the underlying CLI uses its own default.
 
-## Per-Runtime Skill Roots
+## Per-Runtime Native Skill Roots
 
-Skills live in runtime-native directories so a skill placed there is genuinely
-visible to that runtime when invoked outside Minions. The adapter's
-`getSkillRoots()` and `getSkillWriteTargets()` are the discovery and write
-contracts.
+Skills must live in directories the selected CLI natively discovers. The table
+below lists the reliable native roots; adapter diagnostics may inventory
+additional directories, but inventory does not make those directories visible
+to the CLI.
 
 | Adapter | Personal skill root | Project skill roots | Auto-extraction write targets |
 |---------|---------------------|---------------------|-------------------------------|
-| Claude  | `~/.claude/skills`  | `<repo>/.claude/skills` | personal: `~/.claude/skills`; project: `<repo>/.claude/skills` |
-| Copilot | `~/.copilot/skills` (+ `~/.agents/skills`) | `<repo>/.github/skills`, `<repo>/.agents/skills` | personal: `~/.copilot/skills`; project: `<repo>/.github/skills` |
+| Claude  | `~/.claude/skills` | `<repo>/.claude/skills` | personal: `~/.claude/skills`; project: `<repo>/.claude/skills` |
+| Copilot | `~/.copilot/skills`, `~/.agents/skills` | `<repo>/.github/skills`, `<repo>/.claude/skills`, `<repo>/.agents/skills` | personal: `~/.copilot/skills`; project: `<repo>/.github/skills` |
 | Codex | `~/.agents/skills` (+ `/etc/codex/skills`) | `<repo>/.agents/skills` | personal: `~/.agents/skills`; project: `<repo>/.agents/skills` |
 
-`getUserAssetDirs()` returns the union of runtime-native global roots and is
-passed to spawn as `--add-dir` so spawned agents read the same global assets the
-user sees outside Minions. The cross-runtime portable location
-`~/.agents/skills` is included by every adapter that opts into it (Copilot today;
-add it to new adapters when the runtime can read directly from there).
+`getSkillRoots()` feeds the dashboard and `minions doctor --harness` inventory;
+`getSkillWriteTargets()` controls skill auto-extraction. Normal dispatch does not
+turn inventory rows into an engine-computed `--add-dir` list: the selected CLI
+performs native discovery from its cwd and user configuration. In particular,
+Claude does not natively discover `.agents/skills`.
 
 For a full per-runtime survey of which dirs the engine actually surfaces today
 — grouped by scope label and with on-disk-missing flags — run

package/docs/security.md

@@ -139,6 +139,34 @@ previous tick — cannot be silently consumed. Anything in the report body
 itself remains agent-controlled and is treated as such (no `eval`, no shell
 interpolation, schema-validated fields only).
 
+### Review-learning trust boundaries
+
+Structured review learning (see
+[team-memory.md](team-memory.md#security-and-trust-boundaries)) introduces a new
+memory-derived prompt layer, so it observes the same "memory is evidence, not an
+instruction channel" boundary as the rest of retrieval, plus review-specific
+defenses enforced at the persistence boundary in `engine/review-learning.js`:
+
+- **Fenced, bounded injection.** Recalled lessons are wrapped with
+  `engine/untrusted-fence.js` and capped at 4 records / 4 KiB, independent of the
+  generic memory budget. They carry provenance and instruct the agent to verify
+  against live code.
+- **No raw reviewer prose is ever stored.** Candidate/lesson bodies are engine-
+  generated. Raw comment, transcript, reasoning, and chain-of-thought fields are
+  rejected (`assertNoProhibitedReviewPayload`), and secret-shaped values are
+  redacted, so the store never becomes a covert channel for injected reviewer text.
+- **Trusted retrieval-trace binding.** An agent may only report an application or
+  trigger a contradiction for a lesson its own dispatch's persisted retrieval trace
+  actually showed it, and only within its own project. A forged id, an unshown
+  lesson, or a cross-project id is rejected as a diagnostic — it cannot quarantine a
+  lesson it was never given.
+- **Flag-gated, capture-only-safe.** Both flags default off; capture-only changes no
+  rendered prompt, and disabling recall is a complete prompt rollback. Stored
+  records stay auditable through the diagnostics endpoints regardless of flag state.
+- **Injection-flag / nonce gates still apply.** A completion flagged
+  `failure_class: "injection-flagged"` or failing the nonce check never reaches
+  review-learning capture or application processing.
+
 ## 4. Secret management
 
 - **PATs and API tokens live in environment variables only.** GitHub tokens