@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/cloud-agent-dispatch.md

@@ -0,0 +1,204 @@
+# Cloud agent dispatch (Agency / Copilot cloud)
+
+**Status: Phase 1 — surface + provider seam only. No provider ships yet, so
+every cloud-declared work item is currently refused, loudly and non-retryably.**
+
+## Why this exists
+
+Minions is being wired as a *front-door* to remote coding agents. The observed
+result that motivated it: a one-line intent ("in loop android, the builds rely
+on droidx86 — replace it with droidx64") produces a mediocre cloud PR, but the
+same intent run through a local Minions investigation first — which expands it
+into scoped instructions naming exact files, line numbers, and which references
+to change vs. deliberately leave alone — produces a markedly better one.
+
+So the value is not "run agents in the cloud." It is **local investigation +
+prompt rendering, remote execution**. The prompt Minions already builds is the
+product; the cloud provider is just where it gets sent.
+
+## Why cloud is an execution surface, not a runtime
+
+`engine/runtimes/contract.js` describes a **local CLI process**: argv building,
+prompt-on-stdin, PID tracking, stdout stream parsing, session resume, per-turn
+cost accounting. A remote coding agent has none of that — you submit a task, get
+an opaque handle, poll it, and a PR eventually appears.
+
+Modelling it as a runtime would force every adapter method to lie (`buildArgs`
+for a process that never spawns, `parseStreamChunk` for a stream that does not
+exist) *and* would drag cloud dispatch through the local spawn, timeout, and
+worktree machinery it specifically needs to avoid.
+
+Instead cloud is a third value of the existing `EXECUTION_SURFACE` enum, which
+already answers the load-bearing question "does this dispatch need a checkout?":
+
+| Surface | Checkout | Local process | Branch | Deliverable |
+|---|---|---|---|---|
+| `repo` (default) | worktree or live checkout | yes | `work/<wi-id>` | commits in that checkout |
+| `control-plane` | none | yes (runs at `MINIONS_DIR`) | none | Minions/REST + `gh`/`az` calls |
+| `cloud` | none | **no** | none (remote agent pushes its own) | a PR Minions adopts |
+
+## Declaring it
+
+Structured and fail-closed, exactly like `control-plane` — never inferred from
+prose:
+
+```json
+{
+  "type": "implement",
+  "title": "Replace droidx86 reliance with droidx64 in Loop Android",
+  "meta": {
+    "executionSurface": "cloud",
+    "cloudProvider": "agency"
+  }
+}
+```
+
+`meta.cloudProvider` is optional; resolution is most-specific-first:
+
+```
+item.meta.cloudProvider  →  project.cloudProvider  →  engine.cloudProvider
+```
+
+When none is declared, or the declared id is not registered, or the provider
+reports itself unconfigured for the project, the dispatch is **refused** with
+non-retryable `FAILURE_CLASS.CLOUD_PROVIDER_UNAVAILABLE`.
+
+### Eligible work types
+
+`shared.CLOUD_ELIGIBLE_TYPES` = `implement`, `fix`, `test`, `docs`.
+
+The allowlist asks a different question than the control-plane one. Control-plane
+asks *"can this run with no checkout at all?"*; cloud asks *"does this produce a
+PR that a remote agent can author?"* The two sets are deliberately **disjoint**,
+and a test enforces that.
+
+Notable refusals and why:
+
+- **`review` / `verify`** — their entire deliverable is validation: build the
+  code, run the tests, inspect the tree. A remote agent that cannot run your
+  local validation build produces a *worse* review, not a cheaper one. This is
+  the single most common objection to cloud agents from people who use them, and
+  the allowlist encodes it rather than leaving it to judgment.
+- **`build-fix-complex`** — needs live CI logs and the PR's own branch.
+- **`implement:large`** — decomposed into children first; the *children* may go
+  to the cloud.
+- **`setup`** — produces no PR and usually drives local processes
+  (`managed_spawn`), which a remote agent cannot leave running on this machine.
+- **`ask` / `explore` / `meeting`** — read-only; their value is output text,
+  which the cloud surface does not stream back.
+
+## Fail-closed behavior, end to end
+
+Every gate degrades toward *today's behavior* (a local dispatch) or toward a
+loud refusal — never toward silently shipping work somewhere unexpected:
+
+- An **invalid or ineligible** `executionSurface` declaration is rejected at
+  `POST /api/work-items`, in `validateScheduleDefinition`, and again in
+  `spawnAgent` (`FAILURE_CLASS.INVALID_EXECUTION_SURFACE`, non-retryable).
+- `shared.isCloudExecution()` returns `false` for anything invalid, so a
+  malformed opt-in **degrades to a normal local dispatch** — the behavior the
+  item would have had anyway.
+- A **valid** cloud declaration with no usable provider is **refused**, not
+  downgraded: the engine never runs cloud-declared work locally, because a local
+  agent and a remote agent produce different work, in different checkouts, under
+  different identities.
+- A provider whose `isConfigured()` **throws** is treated as unavailable. One
+  that cannot answer the cheap question is not one we hand a work item to.
+- `normalizeSessionStatus` **rejects** `state: "succeeded"` with no `prUrl` — a
+  cloud dispatch succeeds only when it produced a PR Minions can adopt.
+
+## Allocation-time gating
+
+`engine.js#dispatchPending` resolves the surface once, fail-closed, into
+`_itemSkipsCheckoutAllocation` — *"does this item allocate a local checkout at
+all?"* — rather than testing for control-plane specifically. Every gate that
+exists to protect a local checkout is skipped for both no-checkout surfaces:
+
+| Gate | Why it cannot apply |
+|---|---|
+| live-mode concurrency cap (1 mutating dispatch per project) | consumes no operator checkout |
+| operator branch hold | derives no local branch at all |
+| worktree free-space preflight | never runs `git worktree add` |
+| live-checkout dirty / stale-base precheck | never reads the operator tree |
+
+Keying on the *surface* rather than on one surface's name is deliberate: a
+second no-checkout surface added later cannot inherit repo-shaped gates by
+omission, and a cloud item can never pend as `worktree_low_disk_space` when the
+honest answer is `cloud-provider-unavailable`. A regression test asserts each
+gate is individually guarded, with a proximity bound so a gate that loses its
+guard cannot pass by borrowing a neighbour's.
+
+## Provider contract
+
+`engine/cloud/contract.js`, API version 1. Register through
+`engine/cloud/index.js`; orchestration resolves via `resolveCloudProvider()` /
+`resolveCloudDispatchTarget()` and **never** imports a concrete provider or
+branches on a provider id — same discipline as the runtime registry.
+
+```
+isConfigured({ config, project })                       -> boolean   (sync, no network)
+createSession({ project, repo, baseBranch, prompt,
+                workItem, workdir })                    -> { sessionId, url?, providerRef? }
+pollSession(sessionId, { project })                     -> { state, prUrl?, summary?, error?, raw? }
+cancelSession(sessionId, { reason, project })           -> void      (required iff capabilities.cancel)
+```
+
+`state ∈ queued | running | succeeded | failed | cancelled` — deliberately
+smaller than any provider's native state machine, so orchestration never learns
+provider-specific vocabulary.
+
+Registration is strict: a missing required method, a wrong/absent `apiVersion`,
+or a provider that advertises `capabilities.cancel` without implementing
+`cancelSession()` all throw at registration rather than at dispatch.
+
+## Planned providers
+
+| id | Status | Notes |
+|---|---|---|
+| `ado-assign` | planned, Phase 3 | Automates the current manual flow: create an ADO work item carrying the rendered dispatch instructions, assign it to the Agency identity, poll for the linked PR. Buildable today with the existing `az` / `engine/ado` integration — **no unknown API**. |
+| `agency` | blocked | Native Agency Hub session API. Needs the endpoint, auth model ("a different permissions protocol" per the Agency team), repo/branch binding, and PR linkage. The provider seam means this drops in without touching orchestration. |
+| `github-copilot` | optional | The v1 path — assign a GitHub issue to the Copilot coding agent. The only one testable on a public repo. |
+
+## Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `engine.cloudProvider` | *(unset)* | Fleet-wide default provider id. Unset ⇒ cloud dispatch unavailable fleet-wide. Settings → Agents Runtime & Models → **Cloud dispatch**. |
+| `project.cloudProvider` | *(unset)* | Per-project override. |
+| `meta.cloudProvider` | *(unset)* | Per-work-item override (most specific). |
+
+`engine.cloudProvider` is validated against the **live registry**, not accepted
+as free text — an id that resolves to nothing cannot be saved. The Settings
+control (Agents Runtime & Models → **Cloud dispatch**) is a selector populated
+from `GET /api/cloud-providers`; with no provider registered it disables itself
+and states why, rather than offering a value the server would reject. A stored
+value that is no longer registered stays selectable so an operator can clear it,
+and an unreachable endpoint degrades without touching the stored config.
+
+### Discovery
+
+`GET /api/cloud-providers` → `{ providers: [{ name, capabilities }] }` — the
+cloud counterpart to `GET /api/runtimes`. Read-only, no input.
+
+## Still to come (Phases 2–5)
+
+- **Phase 2 — dispatch + lifecycle.** `spawnAgent` renders the prompt and calls
+  `createSession`; a `pollCloudDispatches` tick phase adopts the resulting PR
+  into the existing PR record so the ADO/GitHub pollers and review/fix loops
+  take over unchanged. Two constraints already identified in the code:
+  `engine/orchestration/timeout.js` treats any processless active dispatch as a
+  stale orphan after `engine.heartbeatTimeout` (5 min), so cloud dispatches must
+  be excluded and given their own `cloudSessionTimeout` → `cancelSession`; and
+  they must not consume `engine.maxConcurrent` local slots.
+- **Phase 3 — the `ado-assign` provider.**
+- **Phase 4 — investigate-then-delegate.** A local `explore` agent runs first and
+  produces the scoped instructions; the engine then creates the cloud WI carrying
+  them. This is the actual product.
+- **Phase 5 — dashboard surfaces + the native `agency` provider.**
+
+## Non-goals
+
+- Cloud never becomes a default or a fallback for local dispatch.
+- No attempt to run validation builds in the cloud. Local `verify` / `test` work
+  items still own validation, and the cloud PR flows into them.
+- No new runtime adapter.

package/docs/command-center.md

@@ -2,7 +2,7 @@
 
 The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about Minions state — through a persistent session on the configured CC runtime.
 
-CC is intentionally a thin wrapper around the runtime CLI: state changes happen via tool-driven calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → runtime session persisted in `engine/state.db` (`cc_sessions`). Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
+CC is intentionally a thin wrapper around the runtime CLI: state changes happen via tool-driven calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/agents/llm.js` `callLLM({ direct: true })` → runtime session persisted in `engine/state.db` (`cc_sessions`). Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
 
 For canonical detail (system prompt, session lifecycle, turn-ID surfacing pipeline, doc-chat integration, and CC API contract), read [`CLAUDE.md`](../CLAUDE.md) — see the **CC API Contract** and **Sessions** sections — and the source in [`dashboard/js/command-center.js`](../dashboard/js/command-center.js), [`dashboard.js`](../dashboard.js) (`handleCommandCenter`), and [`prompts/cc-system.md`](../prompts/cc-system.md).
 
@@ -91,13 +91,13 @@ All bundled runtimes currently enable it; a future adapter without image support
 | copilot | `true` | Images materialized to tmp files and passed as `--attachment <path>` (W-mqv7324u0021db5d). |
 | codex   | `true` | Images materialized to tmp files and passed as repeatable `--image <path>` arguments. |
 
-**Worker-pool interaction (W-mray463s001zcee2).** The opt-in Copilot ACP worker pool (`engine.ccUseWorkerPool: true`, default ON for Copilot CC) is a **separate protocol path** from the table above — `engine/cc-worker-pool.js`'s `session/prompt` call only ever sends a single text content block (`[{ type: 'text', text: prompt }]`) and has no image/attachment content-block support today. This used to mean image turns were silently dropped whenever the pool was active, with a comment incorrectly blaming a Copilot capability gap (`imageInput:false`) that doesn't exist — Copilot's `imageInput` is `true` and fully supports images on the direct spawn path. The fix: `_invokeCcStream` (dashboard.js) now checks for a non-empty `images` array **before** routing through `resolveCcUseWorkerPool` — image-bearing turns bypass the warm pool for that turn only and cold-spawn a one-off CLI process via the working `--attachment` path (same as the non-pooled path always used), while image-less turns keep using the fast warm pool. If `engine/cc-worker-pool.js`'s ACP session protocol is later extended to carry attachments (Option A), this per-turn bypass in `_invokeCcStream` should be revisited/removed.
+**Worker-pool interaction (W-mray463s001zcee2).** The opt-in Copilot ACP worker pool (`engine.ccUseWorkerPool: true`, default ON for Copilot CC) is a **separate protocol path** from the table above — `engine/agents/cc-worker-pool.js`'s `session/prompt` call only ever sends a single text content block (`[{ type: 'text', text: prompt }]`) and has no image/attachment content-block support today. This used to mean image turns were silently dropped whenever the pool was active, with a comment incorrectly blaming a Copilot capability gap (`imageInput:false`) that doesn't exist — Copilot's `imageInput` is `true` and fully supports images on the direct spawn path. The fix: `_invokeCcStream` (dashboard.js) now checks for a non-empty `images` array **before** routing through `resolveCcUseWorkerPool` — image-bearing turns bypass the warm pool for that turn only and cold-spawn a one-off CLI process via the working `--attachment` path (same as the non-pooled path always used), while image-less turns keep using the fast warm pool. If `engine/agents/cc-worker-pool.js`'s ACP session protocol is later extended to carry attachments (Option A), this per-turn bypass in `_invokeCcStream` should be revisited/removed.
 
 Because that bypass can spend tens of seconds starting a one-off process before the first model token, the SSE stream shows a user-focused “Looking at the image…” status instead of exposing the cold-start implementation detail or leaving an apparently stalled spinner. The one-off process does not resume the live worker's process-scoped ACP session ID: it starts a transport-compatible fresh session and receives prior conversation context through the existing transcript carryover. Every parsed direct-runtime event, including startup and reasoning events, resets the five-minute silence watchdog; the safety bound therefore still catches a truly silent process without killing an image turn that is making progress.
 
-`_resolveImageOpts` (in `engine/llm.js`) is pure and unit-tested: it forwards the `images` list only when `runtime.capabilities.imageInput` is truthy, otherwise returns the typed error so CC/doc-chat surface the envelope instead of a silently-text-only reply. `_spawnProcess` re-applies the same gate (`if (!caps.imageInput) adapterOpts.images = undefined`) as defense in depth. Image **filenames** are run through the untrusted-input fence (`buildSource('cc-image-filename', …)`) before they reach prompt text, since they are user-supplied.
+`_resolveImageOpts` (in `engine/agents/llm.js`) is pure and unit-tested: it forwards the `images` list only when `runtime.capabilities.imageInput` is truthy, otherwise returns the typed error so CC/doc-chat surface the envelope instead of a silently-text-only reply. `_spawnProcess` re-applies the same gate (`if (!caps.imageInput) adapterOpts.images = undefined`) as defense in depth. Image **filenames** are run through the untrusted-input fence (`buildSource('cc-image-filename', …)`) before they reach prompt text, since they are user-supplied.
 
-**No new `engine.*` flag.** The limits above are module-level constants in `dashboard.js` (`CC_IMAGE_MAX_COUNT`, `CC_IMAGE_MAX_DECODED_BYTES`, `CC_IMAGE_MIME_ALLOWLIST`), not config keys; `engine/shared.js` `ENGINE_DEFAULTS` was not touched. Per CLAUDE.md Best Practice #9 (Settings parity), no Settings toggle is added because no new `engine.*` flag was introduced. Runtime selection that determines whether images are accepted is the existing `engine.ccCli` / `ccModel` override, which already has a Settings control.
+**No new `engine.*` flag.** The limits above are module-level constants in `dashboard.js` (`CC_IMAGE_MAX_COUNT`, `CC_IMAGE_MAX_DECODED_BYTES`, `CC_IMAGE_MIME_ALLOWLIST`), not config keys; `engine/core/shared.js` `ENGINE_DEFAULTS` was not touched. Per CLAUDE.md Best Practice #9 (Settings parity), no Settings toggle is added because no new `engine.*` flag was introduced. Runtime selection that determines whether images are accepted is the existing `engine.ccCli` / `ccModel` override, which already has a Settings control.
 
 ## Operator-checkout write authority (interactive turns)
 
@@ -112,7 +112,7 @@ The "Create PR" chip offered by CC after a local edit follows the **same checkou
 - **`checkoutMode: 'live'`** (default for live-mode projects): unchanged behavior — the agent commits and pushes directly in the operator's live checkout as the CC system prompt instructs.
 - **`checkoutMode: 'worktree'`** (the default for most projects): the engine routes the changes through an isolated worktree deterministically and server-side so nothing depends on the LLM running git correctly.
 
-For worktree-mode projects the flow uses **`engine/create-pr-worktree.js`**:
+For worktree-mode projects the flow uses **`engine/worktrees/create-pr.js`**:
 
 1. `prepareCreatePrWorktree` captures the live checkout's uncommitted changes (tracked diff via `git diff --binary HEAD` + untracked files) and applies them into a fresh worktree on a `cc-pr/<project>-<uid>` branch. The worktree is populated and verified **before** the live checkout is touched; on apply failure the worktree is removed and the live checkout is left untouched (operator never loses work).
 2. The agent then commits, pushes, and opens the PR from inside the worktree.
@@ -122,8 +122,8 @@ Dashboard endpoints added by this feature:
 - `POST /api/pr-action/prepare-create-pr-worktree` — called before the agent's git operations
 - `POST /api/pr-action/cleanup-create-pr-worktree` — called after the PR is open (or on failure)
 
-The `buildCreatePrFollowups` helper in `engine/pr-action.js` emits worktree-aware instructions for worktree mode and the legacy live-checkout instructions for live mode; `dashboard.js /api/pr-action/offer-create-pr` resolves the checkout mode and passes it through.
+The `buildCreatePrFollowups` helper in `engine/providers/pr-action.js` emits worktree-aware instructions for worktree mode and the legacy live-checkout instructions for live mode; `dashboard.js /api/pr-action/offer-create-pr` resolves the checkout mode and passes it through.
 
 ## Per-turn surfacing pipeline
 
-CC handler generates `ccTurnId = 'cct-' + shared.uid()` per request; injected into sysprompt AND prompt body via `_ccTurnHeaderPart(turnId)` (load-bearing: on resumed sessions `engine/llm.js` skips re-sending the sysprompt, so without body injection CC keeps the stale turn ID). Handler reads via `_readCcTurnIdHeader(req)` and calls `_recordCcTurnCreation(turnId, ...)` on success. End-of-turn: `_buildSyntheticActionResultsForTurn` produces synthetic `{action, result}` pairs (`_serverExecuted: true`). Client renders as standalone `role='action'` messages outside the assistant bubble. TTL: 5 min. Endpoints wired: `/api/work-items`, `/api/notes`, `/api/plan`, `/api/knowledge`, `/api/watches`.
+CC handler generates `ccTurnId = 'cct-' + shared.uid()` per request; injected into sysprompt AND prompt body via `_ccTurnHeaderPart(turnId)` (load-bearing: on resumed sessions `engine/agents/llm.js` skips re-sending the sysprompt, so without body injection CC keeps the stale turn ID). Handler reads via `_readCcTurnIdHeader(req)` and calls `_recordCcTurnCreation(turnId, ...)` on success. End-of-turn: `_buildSyntheticActionResultsForTurn` produces synthetic `{action, result}` pairs (`_serverExecuted: true`). Client renders as standalone `role='action'` messages outside the assistant bubble. TTL: 5 min. Endpoints wired: `/api/work-items`, `/api/notes`, `/api/plan`, `/api/knowledge`, `/api/watches`.

package/docs/completion-reports.md

@@ -13,7 +13,7 @@ The engine delivers the absolute path two ways before spawning each agent:
   spawns
 - The same path appears in the rendered playbook prompt
 
-Path shape (resolved by `shared.dispatchCompletionReportPath()` in `engine/shared.js`):
+Path shape (resolved by `shared.dispatchCompletionReportPath()` in `engine/core/shared.js`):
 
 ```
 <MINIONS_DIR>/engine/completions/<dispatch-id>.json
@@ -39,7 +39,7 @@ nonce never enters reusable process state or untrusted task content. The engine
 generates it with `crypto.randomBytes(16).toString('hex')` in
 `engine.js:spawnAgent()` and stores it on the in-memory active-process record.
 The agent is required to copy the value verbatim into the report's `nonce`
-field. On parse, `engine/lifecycle.js:runPostCompletionHooks()` compares
+field. On parse, `engine/orchestration/lifecycle.js:runPostCompletionHooks()` compares
 `report.nonce` against the in-memory value:
 
 - **Match** — the report is trusted and processed normally.
@@ -60,6 +60,25 @@ Security event log lines are emitted on the `error` channel and are designed to
 
 Do **not** invent, regenerate, or share the nonce across dispatches — each spawn gets a unique value.
 
+### The report is also the completion boundary (W-ms9tcs3o01y03383)
+
+The nonce does more than gate trust after the fact — combined with a confirmed
+terminal process exit it *is* the signal that the prompt is finished.
+`engine.js#resolveCloseCompletionBoundary` accepts a report only when the child
+exited with code `0` **and** `shared.acceptCompletionReportForNonce` matches the
+report's `nonce` to this dispatch's spawn value (carried across steering
+resumes). When both hold, the engine releases any queued steering-resume
+bookkeeping instead of spawning it, so a finished dispatch terminalizes on the
+next event-loop turn rather than waiting out `engine.resumeHeartbeatTimeout`.
+
+This is strictly additive to validation: a non-zero exit, a missing report, a
+malformed report, or a missing/mismatched nonce all fall through to exactly the
+failure and timeout paths described above. The same predicate backs the
+resume-stall watchdog in `engine/orchestration/timeout.js`, so both finalizers
+apply one trust boundary. Completed dispatch records record which path ran in
+`completionPath` (`shared.DISPATCH_COMPLETION_PATH`); see
+[timeouts-and-liveness.md](timeouts-and-liveness.md#completion-boundary-terminal-exit--a-dispatch-owned-report-w-ms9tcs3o01y03383).
+
 ## Top-level schema
 
 ```json
@@ -84,10 +103,10 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | Field | Type | Notes |
 |---|---|---|
 | `status` | string | One of `success`, `partial`, `failed`. Aliases `done` / `complete` are accepted on read for `success`. The engine refuses to mark a work item done without a status. |
-| `summary` | string | Short prose describing what changed and how it was validated. Truncated to 500 chars in dashboard surfaces (`engine/queries.js`). Do not summarize validation as "tests passed" — name the commands that ran. |
+| `summary` | string | Short prose describing what changed and how it was validated. Truncated to 500 chars in dashboard surfaces (`engine/core/queries.js`). Do not summarize validation as "tests passed" — name the commands that ran. |
 | `verdict` | string \| null | Required for review tasks: `approved` or `changes-requested`. `null` for non-review tasks. Aliases: `approve`, `request_changes`, `changes_requested`. |
 | `pr` | string | PR URL, `PR-<number>`, or `N/A`. The engine uses this to attach the PR to the work item; missing-PR detection treats anything other than a recognizable URL/PR id as missing unless `noop: true` is set. |
-| `failure_class` | string | One of the `failure_class` enum values below, or `N/A`. Drives retry policy in `engine/dispatch.js`. |
+| `failure_class` | string | One of the `failure_class` enum values below, or `N/A`. Drives retry policy in `engine/orchestration/dispatch.js`. |
 | `retryable` | boolean | `true` if the engine should auto-retry the dispatch on failure. Overrides the default per-class retry policy when present. |
 | `needs_rerun` | boolean | `true` if the same work needs to be re-dispatched (vs. retried). Used by build-fix and review-fix loops. |
 | `artifacts` | array | Durable artifacts the agent created or updated; surfaces in the dashboard work-item detail modal. See [Artifacts](#artifacts). |
@@ -131,11 +150,11 @@ derive an identity from reviewer prose.
       "project": "minions-opg",
       "authorAgent": "dallas",
       "applicability": "project-team",
-      "files": ["engine/lifecycle.js"],
+      "files": ["engine/orchestration/lifecycle.js"],
       "symbols": ["normalizeReviewLearningCompletionPayload"],
       "tags": ["completion-contract"],
       "evidence": [
-        "engine/lifecycle.js:5742",
+        "engine/orchestration/lifecycle.js:5742",
         "test/unit/structured-completion.test.js:158"
       ],
       "confidence": 0.92,
@@ -146,7 +165,7 @@ derive an identity from reviewer prose.
     {
       "id": "M-review-lesson-1",
       "outcome": "applied",
-      "evidence": "engine/lifecycle.js:5742 validates each optional field independently."
+      "evidence": "engine/orchestration/lifecycle.js:5742 validates each optional field independently."
     }
   ]
 }
@@ -270,11 +289,11 @@ P-mqyp0009y025z6a7. An optional `invalidates: string[]` field in the completion
 - Each cancellation stamps `cancellationReason: "invalidated-by:<source-wi-id>"` and `cancelledAt` on the cancelled WI.
 - A `work_items` state event is emitted for each successful cancellation so the dashboard reflects it.
 
-**Implementation:** `engine/lifecycle.js#applyGoalInvalidation`, called from `runPostCompletionHooks` after the source WI is marked done.
+**Implementation:** `engine/orchestration/lifecycle.js#applyGoalInvalidation`, called from `runPostCompletionHooks` after the source WI is marked done.
 
 ## `failure_class` enum
 
-Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated string.
+Defined in `engine/core/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated string.
 
 | Value | When to use | Default escalation |
 |---|---|---|
@@ -284,6 +303,7 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `merge-conflict` | Git merge conflict in worktree or dependency | Retry same agent |
 | `build-failure` | Compilation, lint, or test failure introduced by the agent | Retry same agent |
 | `timeout` | Hard runtime timeout or stale-orphan timeout | Retry with fresh session |
+| `engine-restart` | Dispatch process ownership was lost across an engine restart | Retry against the bounded infrastructure retry counter, not the semantic agent retry budget |
 | `empty-output` | Agent produced no meaningful output | Flag for human review |
 | `runtime-truncated-exit` | The runtime process exited `0` in the MIDDLE of a turn: its output holds a tool call that was started and never completed (observed: Copilot exiting right after starting a long `npm test`), and no completion report was written. Detected through the optional adapter hook `hasUnfinishedToolCall`. Distinct from `completion-report-missing`, which means the turn ended normally but the agent skipped the report. | Retry — a fresh attempt normally runs to completion |
 | `runtime-session-stale` | A `--resume`d runtime died because its persisted session is unusable: the backing conversation is gone, or its persisted working directory no longer exists (the engine removed/recycled that worktree). Previously surfaced as an opaque `empty-output`. | Retry — the engine clears the cached session first |
@@ -311,6 +331,9 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `live-checkout-stale-base` | Spawn-time defense found local `mainRef` ahead of `origin/<mainRef>`; forking would inherit committed contamination | Never retry — operator reconciles the local base first |
 | `live-checkout-wrong-base` | New-branch fork requested but operator HEAD is on an unrelated branch, not the project base | Never retry — operator checks out `mainRef` first (or enable `liveCheckoutAutoBaseRepair`) |
 | `invalid-workdir` | Dispatch carried a `meta.workdir` override that failed validation (absolute path, `..` segment, escape, etc.) | Never retry until the WI's `meta.workdir` is fixed |
+| `invalid-execution-surface` | `meta.executionSurface` failed fail-closed validation: an unknown/non-string surface, `control-plane` on a work type that reads or mutates repository files, or `cloud` on a work type whose deliverable is not a PR. Each surface is an ALLOWLIST (`shared.CONTROL_PLANE_ELIGIBLE_TYPES` / `shared.CLOUD_ELIGIBLE_TYPES`), never inferred from prose. | Never retry — operator fixes or removes the field |
+| `cloud-provider-unavailable` | The WI validly declared `meta.executionSurface: "cloud"` but no registered **and** configured cloud provider resolved. Structural, not connectivity — the engine never downgrades the refusal to a local dispatch. | Never retry — operator configures a provider or drops the declaration |
+| `git-ref-lock` | `git fetch` lost a **local** ref-lock race on a shared remote-tracking ref (`cannot lock ref 'refs/remotes/origin/<main>'`). A serialization defect, deliberately not `network-error`, which previously hid the cause and burned retries. `shared.withSerializedRemoteRefRefresh` removes the in-process races; this covers the residual cross-process case. | Retry — the ref lock clears in seconds |
 | `model-unavailable` | Requested model returned `overloaded_error` / 503 / service unavailable | Retry — engine swaps in the runtime-appropriate fallback model |
 | `workspace-manifest-repo-forbidden` | Dispatch routed an agent to a repo not in its `workspace_manifest.allowed_repos`. See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
 | `workspace-manifest-tool-forbidden` | Out-of-scope tool call caught by manifest enforcement at the runtime gate | Never retry as-is |
@@ -328,7 +351,7 @@ Use `"N/A"` when `status` is `success` or `partial` without a failure.
 
 A handful of `failure_class` values are written by the **engine at dispatch time**, *before the agent process is ever spawned*. They are emitted from `spawnAgent` (`engine.js`) while it sets up the worktree, validates the checkout, or enforces the workspace manifest — the engine calls `completeDispatch(... DISPATCH_RESULT.ERROR ...)` and returns without launching any runtime. **A completion report carrying one of these classes does not imply the agent ran any work**; no prompt was sent, no edits were attempted, and there is no agent-authored `note` or output to interpret.
 
-| `failure_class` | Pre-spawn trigger | `engine/shared.js` |
+| `failure_class` | Pre-spawn trigger | `engine/core/shared.js` |
 |---|---|---|
 | `worktree-preflight` | Worktree placement validation failed: the worktree would nest inside the project, the resolved root collapsed to a drive root, or the base directory was missing. | `FAILURE_CLASS.WORKTREE_PREFLIGHT` (~`shared.js:4279`) |
 | `live-checkout-dirty` | Live-checkout mode (`project.checkoutMode: 'live'`) found uncommitted changes in `project.localPath`; the engine never `reset`/`clean`s the operator tree, so it refuses to spawn. | `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (~`shared.js:4289`) |
@@ -354,7 +377,7 @@ To signal a no-op:
 }
 ```
 
-Engine behavior when `noop: true` (`engine/lifecycle.js` `parseCompletionNoop` + `runPostCompletionHooks`):
+Engine behavior when `noop: true` (`engine/orchestration/lifecycle.js` `parseCompletionNoop` + `runPostCompletionHooks`):
 
 - The work item is marked `done` with the rationale stored as `_noopReason` (visible in the dashboard).
 - The PR-attachment contract is **skipped**, so an empty `pr` field will not be flagged as a silent failure or auto-retried.
@@ -373,7 +396,7 @@ If the live PR branch did not advance, the completion must set `noop: true` and
   "reviewFindingResolution": {
     "findingId": "review-0123456789abcdef",
     "disposition": "satisfied-elsewhere",
-    "currentCodeEvidence": "engine/lifecycle.js:4600 already enforces the condition; test/unit/example.test.js covers it."
+    "currentCodeEvidence": "engine/orchestration/lifecycle.js:4600 already enforces the condition; test/unit/example.test.js covers it."
   }
 }
 ```
@@ -405,7 +428,7 @@ optional `followups` array on its completion report:
 }
 ```
 
-Engine behavior (`engine/lifecycle.js` `processCompletionFollowups`):
+Engine behavior (`engine/orchestration/lifecycle.js` `processCompletionFollowups`):
 
 - Each entry is logged at `info`: `Followup audit (<agent> wi=<parent>): dispatched <wi_id> — <title> (comment=<id>) — <reason>`.
 - If the claimed `wi_id` does not exist in any project SQL scope at parse time, a `warn` is emitted. This catches dispatches that were deduped to a 409 / 200-duplicate response, reverted, or never actually landed.
@@ -420,7 +443,7 @@ Both default to `false`. Together they let the agent override the engine's defau
 - `retryable: false` — engine should not auto-retry; the failure is terminal for this dispatch.
 - `needs_rerun: true` — even on `status: success`, the same work item should be re-dispatched (used by review-fix and build-fix loops where one pass cannot complete the work).
 
-When the agent sets either field, it overrides the per-`failure_class` default in `isRetryableFailureReason()` (`engine/dispatch.js`).
+When the agent sets either field, it overrides the per-`failure_class` default in `isRetryableFailureReason()` (`engine/orchestration/dispatch.js`).
 
 ## Artifacts
 
@@ -436,11 +459,11 @@ When the agent sets either field, it overrides the per-`failure_class` default i
 | `path` | string | Relative repo path, absolute path, or URL. |
 | `title` | string | Short label used in the dashboard list. |
 
-The dashboard caps the rendered list at 20 artifacts per report (`engine/queries.js`). Include every durable artifact you created or updated — PRs, plan/PRD files, key source files, inbox notes — so the work-item detail modal can show them.
+The dashboard caps the rendered list at 20 artifacts per report (`engine/core/queries.js`). Include every durable artifact you created or updated — PRs, plan/PRD files, key source files, inbox notes — so the work-item detail modal can show them.
 
 ## Validation and source-of-truth precedence
 
-The engine reads completion signals in this order (`engine/lifecycle.js`):
+The engine reads completion signals in this order (`engine/orchestration/lifecycle.js`):
 
 1. The JSON report at `MINIONS_COMPLETION_REPORT` — sole structured-completion source. `parseCompletionReportFile()` requires a well-formed plain-object JSON with a `status` field; anything else is dropped with a warn log.
 2. Runtime result events + the `[process-exit]` sentinel in `live-output.log` — used to confirm the dispatch actually exited and to capture the runtime's own result prose into `resultSummary`. These cannot supply structured fields (`pr`, `failure_class`, `retryable`, `noop`, `verdict`, `artifacts`, …); without a report on disk those signals are simply absent.
@@ -462,7 +485,7 @@ The legacy fenced ` ```completion ` block parser and the `task_complete` prose-s
   "needs_rerun": false,
   "artifacts": [
     {"type": "pr", "path": "https://github.com/opg-microsoft/minions/pull/2360", "title": "PR-2360"},
-    {"type": "file", "path": "engine/spawn-agent.js", "title": "Stale-HEAD guard"},
+    {"type": "file", "path": "engine/agents/spawn-agent.js", "title": "Stale-HEAD guard"},
     {"type": "file", "path": "test/unit/spawn-agent.test.js", "title": "New unit test"}
   ]
 }
@@ -514,8 +537,8 @@ The legacy fenced ` ```completion ` block parser and the `task_complete` prose-s
 
 ## Related
 
-- `engine/shared.js` — `FAILURE_CLASS`, `COMPLETION_FIELDS`, `dispatchCompletionReportPath()`
-- `engine/lifecycle.js` — `parseCompletionReportFile()`, `parseCompletionNoop()`, `enforcePrAttachmentContract()`
-- `engine/dispatch.js` — `isRetryableFailureReason()`, `writeFailedAgentReport()`
+- `engine/core/shared.js` — `FAILURE_CLASS`, `COMPLETION_FIELDS`, `dispatchCompletionReportPath()`
+- `engine/orchestration/lifecycle.js` — `parseCompletionReportFile()`, `parseCompletionNoop()`, `enforcePrAttachmentContract()`
+- `engine/orchestration/dispatch.js` — `isRetryableFailureReason()`, `writeFailedAgentReport()`
 - `docs/rfc-completion-json.md` — original RFC describing the protocol's design
 - `playbooks/shared-rules.md` — the per-task "Completion Reports" instruction every playbook inherits

package/docs/constants.md

@@ -1,6 +1,6 @@
 # Constants — No Magic Strings
 
-Cross-cutting status / type / condition values are defined in [`engine/shared.js`](../engine/shared.js). Engine and dashboard code should use these constants instead of raw strings; source-inspection tests enforce the load-bearing comparisons.
+Cross-cutting status / type / condition values are defined in [`engine/core/shared.js`](../engine/core/shared.js). Engine and dashboard code should use these constants instead of raw strings; source-inspection tests enforce the load-bearing comparisons.
 
 ```js
 WI_STATUS = { PENDING, DISPATCHED, DONE, FAILED, PAUSED, QUEUED, DECOMPOSED, CANCELLED }
@@ -20,7 +20,7 @@ WATCH_CONDITION = { MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, STATUS_CH
   STAGE_ADVANCED, STUCK_IN_STAGE }
 WATCH_ABSOLUTE_CONDITIONS = Set([MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, CONCLUDED, APPROVED,
   REJECTED, READY_FOR_MERGE, RETRY_LIMIT_REACHED, ALL_ITEMS_DONE, ITEM_FAILED_N_TIMES])  // fire-once
-WATCH_TARGET_TYPE = { PR, WORK_ITEM, MEETING, PLAN, SCHEDULE, PIPELINE, DISPATCH, AGENT }  // built-ins; watches.d/*.js may register more
+WATCH_TARGET_TYPE = { PR, WORK_ITEM, MEETING, PLAN, SCHEDULE, PIPELINE, DISPATCH, AGENT }  // built-ins; watch-plugins/*.js may register more
 WATCH_ACTION_TYPE = { NOTIFY, DISPATCH_WORK_ITEM, RUN_SKILL, WEBHOOK, MINIONS_API,
   CANCEL_WORK_ITEM, TRIGGER_PIPELINE, ARCHIVE_PLAN, RESUME_PLAN, CC_TRIAGE }
 BUILD_STATUS = { PASSING, FAILING, RUNNING, NONE }
@@ -30,12 +30,19 @@ MEETING_STATUS = { INVESTIGATING, DEBATING, CONCLUDING, COMPLETED, ARCHIVED }
 PIPELINE_STATUS = { PENDING, RUNNING, COMPLETED, FAILED, PAUSED, WAITING_HUMAN, STOPPED }
 STAGE_TYPE = { TASK, MEETING, PLAN, API, MERGE_PRS, SCHEDULE, WAIT, PARALLEL, CONDITION }  // pipelines/*.json stage kinds
 CHECKOUT_MODES = { WORKTREE, LIVE }  // project.checkoutMode; see docs/live-checkout-mode.md
+CONTROL_PLANE_ELIGIBLE_TYPES = Set([setup, ask, explore, meeting])  // meta.executionSurface: 'control-plane' allowlist — fail-closed
+CLOUD_ELIGIBLE_TYPES = Set([implement, fix, test, docs])  // meta.executionSurface: 'cloud' allowlist — deliberately DISJOINT from the control-plane set
+KB_CATEGORIES = [architecture, conventions, project-notes, build-reports, reviews]  // knowledge/<category>/
+WORKTREE_OWNER_MARKER = '.minions-worktree'  // engine-created worktrees; unmarked out-of-root paths are foreign (GC fails open)
+QUARANTINE_REF_RETENTION_MS = 30d  // single source for BOTH quarantine dirs and refs/minions/quarantine-wip/*; resolve overrides via resolveQuarantineRetentionMs(config)
 FAILURE_CLASS = { ... }  // dispatch failure taxonomy — full enum in docs/completion-reports.md
 ```
 
+`PROCESS_TERMINATION_SITES` (46 registered sites) is the one inventory that lives in [`engine/processes/process-utils.js`](../engine/processes/process-utils.js) rather than `shared.js`. Every kill must name a registered site via `shared.terminateProcess(<site>, target, ownership)` — see [docs/process-termination.md](process-termination.md).
+
 ## Engine defaults
 
-Retry/timeout limits, sweep cadences, fleet ceilings, and managed-spawn caps live in `ENGINE_DEFAULTS` (also in `engine/shared.js`). Read defaults from there rather than re-declaring. Some keys resolve a `config.engine.*` override through a helper (`resolveAgentMaxBudget`, etc.); others are source-only, so verify the call site before documenting a Settings/config knob.
+Retry/timeout limits, sweep cadences, fleet ceilings, and managed-spawn caps live in `ENGINE_DEFAULTS` (also in `engine/core/shared.js`). Read defaults from there rather than re-declaring. Some keys resolve a `config.engine.*` override through a helper (`resolveAgentMaxBudget`, etc.); others are source-only, so verify the call site before documenting a Settings/config knob.
 
 ## Invariants