@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/plan-lifecycle.md

@@ -18,12 +18,53 @@ How plans go from idea to verified, running code.
   → human archives the PRD/plan from the dashboard when ready
 ```
 
+## Plan-to-PRD result sidecar
+
+The `plan-to-prd` agent does not write PRD state directly. It writes one
+short-lived envelope to `agents/<agent-id>/prd-result.json`:
+
+```json
+{ "filename": "<engine-pinned>.json", "work_item": "W-…", "prd": { … } }
+```
+
+The whole contract is owned by `engine/planning/prd-result-sidecar.js`, shared by
+both import sites so their validation can never drift.
+
+**Result identity is retry-stable.** The expected filename is generated once and
+pinned on the work item as `_prdFilename` (with `_planKey`); every later dispatch
+of the same work item for the same plan reuses it. It is deliberately *not*
+re-derived per dispatch — for a cross-repo plan the slug is `cross-<uid>-<date>`,
+so re-deriving it on retry silently orphaned the previous attempt's valid result
+and forced a full regeneration (W-ms9tcry701xz0389).
+
+**Import is fail-closed.** A sidecar is imported only when it *declares* the
+expected filename (there is no permissive "assume it's ours" fallback), its
+`prd.source_plan` matches the work item's plan, and — when present — its
+`work_item` matches the dispatched work item. A rejected sidecar is left on disk
+untouched, because it may belong to a sibling work item that has not retried yet.
+
+**Consume is atomic and exactly-once.** The sidecar is claimed with an
+intra-directory rename before the PRD is written and removed after a successful
+import, so one sidecar can never materialize two PRDs and a consumed result can
+never be inherited by a later unrelated dispatch from the same agent.
+
+**Recovery beats re-running.** Because the identity is stable, a valid sidecar
+from an interrupted attempt still matches. `engine.js#discoverCentralWorkItems`
+imports it *before* resolving an agent and completes the work item, instead of
+spending another full conversion run recreating identical content. When no result
+can be imported, the `#893` gate bounces the item back to `pending` with a reason
+that names the plan but never the failed attempt's filename — the reason is
+replayed verbatim into the retry prompt, where only `{{prd_filename}}` is
+authoritative.
+
 ## Dependency Management
 
 ### Dispatch Gating
 
 PRD items can declare `depends_on: ["P001", "P003"]`. The engine won't dispatch an item until all its dependencies have status `done`. This prevents agents from starting work before prerequisite code exists.
 
+A dependency that ends `failed` does **not** cascade. The dependent stays `pending` with `_pendingReason: 'dependency_failed'` and is skipped for that tick — it is never marked `failed` and no retry is charged (W-mpbqhstz001lf518, closes #2627). Cascading used to burn the dependent's retry budget every time the dependency was auto-retried, and left the dependent stuck at `failed` even after the dependency eventually succeeded. Because the dependent stays pending, it dispatches on its own once the dependency reaches `done`.
+
 ### Branch Merging at Spawn
 
 When an agent is spawned for a work item with dependencies, the engine merges same-project dependency PR branches into the worktree **before the agent starts**. Cross-repo dependencies are exposed as advisory refs instead of being merged. This lets later items inspect prerequisite code that has not reached the target repo's main branch.
@@ -130,12 +171,37 @@ Manual archive behavior:
 
 Use unarchive only when the archived PRD/plan should reappear in active views. Reopening completed work should happen before archive, or after unarchive, so the materializer can see the active SQL PRD.
 
+## Revision vs Staleness (W-msa0mrus00mh466f)
+
+Two different things can invalidate a PRD, and they must never offer competing recovery paths at the same time:
+
+| Signal | Meaning | Recovery |
+|--------|---------|----------|
+| `planStale: true` | The source markdown changed under an existing PRD (engine sweep, content-hash gated) | Generic stale banner → `Regenerate PRD` / `Resume as-is` |
+| `status: "revision-requested"` | A human asked for a revision; a `plan-to-prd` agent is rewriting this PRD | `Revision in progress` banner → no regenerate/resume |
+
+`POST /api/plans/revise` persists `revisionWorkItemId` on the PRD and stamps the reverse `_revisionForPrd` link on the work item. That two-way relation — never title text — is the single correlation. `shared.findPrdRevisionWorkItem()` resolves it (pointer first, reverse stamp as fallback) and `shared.derivePrdRevisionState()` reduces it to one of:
+
+- `in-progress` — the revision work item is `pending` / `dispatched` / `queued` / `paused`. The dashboard suppresses `Regenerate PRD`, `Resume as-is`, and the group Pause/Approve/Archive actions so nothing can race the agent. A second `POST /api/plans/revise` is rejected `409 { code: 'revision-in-progress', workItemId }` and enqueues nothing.
+- `failed` — the work item is terminal (`failed`/`cancelled`), finished `done` without updating the PRD, or is missing entirely. The dashboard renders an explicit `Revision failed` banner with `Retry revision` (requeues the same work item via `POST /api/work-items/retry`). Staleness is never silently cleared, and a fresh revise request is accepted so the PRD is not stranded in `revision-requested`.
+- `none` — no revision operation applies; the ordinary stale banner and its actions behave exactly as before.
+
+On a successful revision import, `engine/planning/prd-result-sidecar.js#consumePrdResultSidecar` normalizes the agent's PRD through `shared.applyPrdRevisionCompletion()` and persists it with a **single** `prdStore.writePrd()`: status returns to `awaiting-approval`, `planStale` and the pre-revision approval fields are cleared, `_sourcePlanContentHash` / `sourcePlanModifiedAt` / `lastSyncedFromPlan` are re-baselined against the live markdown, and the revision pointers are dropped. Readers therefore never observe a completed revision paired with stale recovery controls. The rule lives beside the only write — the module that owns the sidecar import — so both callers apply it identically: the post-completion import in `engine/orchestration/lifecycle.js` and the pre-spawn sidecar recovery in `engine.js#discoverCentralWorkItems` each pass the work item's `_revisionForPrd` stamp, and a rescued revision therefore lands in exactly the same state as a completed one.
+
+Derivation happens once, server-side: `engine/core/queries.js#getPrdInfo` publishes it as `progress.planRevisions[<prdFile>]` and `dashboard/js/render-prd.js` only paints the result.
+
+### The revision feedback reaches the agent explicitly
+
+A revision run is an ordinary `plan-to-prd` dispatch whose only distinguishing input is the operator's feedback, so that text needs a real channel. It used to arrive by accident: the work item's `planFile` named the PRD `.json`, the engine's `PLANS_DIR/<planFile>` read failed, and the description (which embeds the feedback) leaked in through the `{{plan_content}}` fallback. Pointing `planFile` at the true source markdown closed that accident, and `playbooks/plan-to-prd.md` has no `{{task_description}}` token — so without a dedicated channel a revision silently degrades into a no-op regeneration that still reports success.
+
+`engine.js` therefore resolves `shared.resolvePrdRevisionFeedback(item, resolvedPrd, prdFilename)` into `vars.revision_feedback`, and `plan-to-prd.md` renders it inside a `{{#revision_feedback}}…{{/revision_feedback}}` "Revision Requested" block. The feedback is read from the PRD (the single source of truth — `handlePlansRevise` writes it, `applyPrdRevisionCompletion` clears it), so a retry that reuses the same work item can never render superseded text. It is gated on the same structural `_revisionForPrd` ⇄ resolved-PRD-filename relation, so a plain regeneration cannot pick up feedback left behind by an earlier failed revision.
+
 ## Human Feedback on PRs
 
 After PRs are created, any new actionable human comment can trigger a fix task;
 an `@minions` mention is optional and is stripped before the feedback reaches
 the agent. Pollers filter bot, CI, preview, and Minions-authored comments. See
-`pollPrHumanComments()` in `engine/ado.js` and `engine/github.js`.
+`pollPrHumanComments()` in `engine/ado/index.js` and `engine/providers/github.js`.
 
 ## Routing
 
@@ -161,5 +227,6 @@ the agent. Pollers filter bot, CI, preview, and Minions-authored comments. See
 | `playbooks/verify.md` | Verification task playbook |
 | `playbooks/implement.md` | Implementation playbook |
 | `playbooks/plan-to-prd.md` | Plan → PRD conversion playbook |
-| `engine/lifecycle.js` | `checkPlanCompletion`, completion hooks, PRD sync |
+| `engine/planning/prd-result-sidecar.js` | One-shot PRD result envelope: validation + atomic exactly-once consume |
+| `engine/orchestration/lifecycle.js` | `checkPlanCompletion`, completion hooks, PRD sync |
 | `engine.js` | `spawnAgent` (dependency merging), `resolveDependencyBranches` |

package/docs/pr-author-identity.md

@@ -0,0 +1,114 @@
+# PR author identity vs. Minions agent attribution
+
+W-mscibegy005e8b74. A tracked pull request now carries **two distinct
+identities** that used to be conflated in the single overloaded `pr.agent`
+field:
+
+| Field       | Meaning | Used for |
+|-------------|---------|----------|
+| `pr.agent`  | The **Minions agent** that created/owns the automated work. | Routing, self-review prevention, fix ownership, metrics, diagnostics. |
+| `pr.author` | The **real individual** on whose behalf the PR exists, linked to an authoritative provider identity. | The Pull Requests table's Author column, author filter/search, and the PR detail panel. |
+
+## The bug this replaced
+
+GitHub and ADO provider sync used to overwrite `pr.agent` with the platform
+author login/display name whenever `agent === 'human'`
+(`engine/providers/github.js`, `engine/ado/index.js`, and the dashboard link
+enrichment). Meanwhile orchestration, routing, and metrics read `pr.agent` as
+the **Minions** author-agent. A human-authored PR therefore encoded a human
+login in a field that self-review prevention and routing treat as a Minions
+agent id. `pr.agent` is now **never** a human login.
+
+## Identity conventions
+
+1. **`pr.agent`** stays the Minions agent id/name. The sentinel
+   `shared.PR_AGENT_HUMAN` (`'human'`) means "no Minions author-agent" (a human
+   or externally created PR). We keep the `'human'` sentinel rather than `null`
+   because `agent === 'human'` checks are embedded across routing and
+   lifecycle. Providers/dashboard never write a login here again.
+2. **`pr.author`** is a structured, provider-linked shape:
+
+   ```js
+   { provider, id, nodeId?, descriptor?, login?, displayName?, url? }
+   ```
+
+   - GitHub: built from the PR `user` object — `id`, `node_id`, `login`,
+     `name` (→ `displayName`), `html_url` (→ `url`).
+   - ADO: built from `createdBy` — `id` (GUID), `descriptor`, `uniqueName`
+     (→ `login`), `displayName`. ADO's `createdBy.url` is an API endpoint, not a
+     browsable profile, so no `url` is surfaced unless a real `http(s)` link is
+     present under `_links.web.href`.
+3. **Shared automation credential.** When the platform credential is a shared
+   bot but Minions has explicit structured provenance for the real human, both
+   the platform creator and the effective author are preserved rather than
+   claiming one is the other. Identity is **never** inferred from title /
+   description / free text — only from structured provider metadata or an
+   existing configured/operator identity seam.
+4. **Unknown / legacy records** render as **Unknown**, never silently borrowing
+   the agent name. Provider reconciliation enriches old rows naturally as they
+   are re-polled; migration 031 backfills what it safely can (below).
+5. **Human-created PRs** no longer encode their login in `agent`; `agent` is the
+   `'human'` sentinel and `author` carries the human identity.
+
+## Canonical helpers (`engine/core/shared.js`)
+
+- `buildGithubAuthorIdentity(user)` / `buildAdoAuthorIdentity(createdBy)` —
+  build the structured shape from a provider response.
+- `normalizePrAuthorIdentity(raw)` — coerce an arbitrary value (structured
+  object or bare login string) into the canonical shape or `null`. Every field
+  is length-capped; `url` accepts only `^https?://` values (dropped otherwise so
+  the dashboard never links an unvalidated href).
+- `mergePrAuthorIdentity(existing, incoming)` — field-by-field merge; a
+  non-empty incoming value wins, otherwise the existing value is preserved, so a
+  **partial provider refresh never erases a richer author already stored**. A
+  provider change trusts the newer identity wholesale.
+- `prAuthorLabel(author)` — human-readable label (displayName → login → id) for
+  the typed SQL column and filter/search text.
+
+`upsertPullRequestRecord` normalizes `author` on the create path and merges it
+via `mergePrAuthorIdentity` on the update path (and in `_mergeDuplicatePrInto`),
+so all ingestion/reconciliation paths — GitHub, ADO, output-based discovery,
+manual link, dashboard enrich, dedup — converge on one merge behavior.
+
+## Persistence — migration 031
+
+`engine/db/migrations/031-pr-author-identity.js` adds a typed `author`
+projection column (plus `idx_pr_author`). The canonical structured identity
+always lives in the row's `data` JSON; the column is a label projection for
+filters/sort. `engine/persistence/pull-requests-store.js` writes it via a local
+`_authorLabel(pr.author)` (displayName → login → id).
+
+Backfill is **fail-closed**. A legacy row whose `agent` is a human login (i.e.
+not `'human'`, not a configured Minions agent id from `config.json`, not
+`temp-*`, not `unknown`/`unassigned`) has that login moved into
+`author = { login }` and `agent` reset to `'human'`. **If the configured
+agent-id set cannot be resolved, the destructive agent→author move is skipped
+entirely** so a real agent row (e.g. `dallas`) is never mistaken for a human
+login. Rows that already carry a structured `data.author` only get the label
+projected into the new column. Rows whose identity cannot be established are
+left untouched (`author` NULL → renders Unknown).
+
+## Snapshot / bridge projection
+
+`engine/api/bridge.js#_projectPullRequest` projects an allowlisted, length-capped
+`author` object (`provider`, `id`, `descriptor`, `login`, `displayName`, `url`)
+alongside the existing `agent` field.
+
+## Dashboard
+
+`dashboard/js/render-prs.js` replaces the Pull Requests table's **Agent** column
+with **Author** (display name + `@login`, safely escaped, linked to the provider
+profile only when a validated `http(s)` URL is present). The Minions agent stays
+visible in the PR detail panel under **Minions agent**, next to a new **Author**
+line, so operators can still answer both "who is this for?" and "which agent
+handled it?". The shared author filter (`dashboard/shared/pr-filters.js`) now
+reads structured `pr.author` only and no longer falls back to `pr.agent`, so the
+filter and the displayed column stay aligned (legacy rows group as Unknown).
+
+## Backward-compatible reads
+
+`normalizePrAuthorIdentity` still accepts a bare author string and coerces it to
+`{ login }`, so any legacy record or external caller that supplied a plain
+author string keeps rendering. This is a tolerant read, not a retained
+compatibility shim — the overloaded `agent = login` write behavior was removed
+outright (no `docs/deprecated.json` entry required).

package/docs/pr-auto-fix-dispatch.md

@@ -17,6 +17,15 @@ All dispatch decisions happen inside `engine.js#discoverFromPrs` once per discov
 
 \* `autoFixPaused` is the auto-**fix** kill-switch. It forces sites 2, 4, 5, and 6 off, but is **not** wired to suppress review dispatch (sites 1 and 3) — review verdicts stay fresh during a fix-storm incident. To halt review dispatch, clear `autoReviewPrs` / `autoReReviewPrs` directly, or set `pollingPaused: true` (which forces every per-PR auto-dispatch gate inert by zeroing `pollEnabled`).
 
+### Per-PR row controls
+
+The Pull Requests table exposes adjacent **Auto Fix** and **Auto Review**
+switches for each tracked PR. Auto Fix gates sites 2, 4, 5, and 6 in the table
+above; Auto Review gates sites 1 and 3. Existing records inherit both switch
+values from `contextOnly` until either switch is changed. The dashboard persists
+the independent booleans through `POST /api/pull-requests/automation`; when both
+are off, it also sets `contextOnly:true`.
+
 ### Provider polling gate
 
 Each PR carries a `repoHost` (`github` / `ado`). Before evaluating any of the six sites, `discoverFromPrs` resolves a `pollEnabled` boolean from that provider's poll gate:
@@ -41,7 +50,13 @@ There are two independent operator-facing master flags:
 
 These compose: setting `pollingPaused: true` plus `autoFixPaused: true` halts *all* automated PR work (review + fix + polling). Setting only `autoFixPaused: true` halts only auto-fix dispatch. Setting only `pollingPaused: true` halts polling *and reconciliation* (all provider network traffic) and effectively halts dispatch (because the per-PR gates rely on cached poll state), while still letting manual `/api/pull-requests/observe` or operator-driven dispatch proceed.
 
-Flip via Dashboard → Settings → Polling (`pollingPaused`) / Auto-fix & Review Loop (`autoFixPaused`), or set `engine.<flag>: true` in `config.json`.
+Flip via Dashboard → Settings → Polling (`pollingPaused`) / Plan & PR Workflow → Monitor (`autoFixPaused`), or set `engine.<flag>: true` in `config.json`.
+
+### What `autoFixPaused` deliberately does NOT cover
+
+`autoFixPaused` gates exactly the four auto-**fix dispatch** decisions above. It is not a general "stop writing to the platform" switch, because the table row's promise — operators keep seeing fresh verdicts *and build status* during a fix-storm — depends on polling-side work continuing.
+
+The clearest example is `adoQueueDraftPrBuilds` (ADO draft-PR branch-policy build queueing, W-ms7kklp8002zad24). It runs inside `pollPrStatus`, POSTs a build queue request, and dispatches **no agent**, so it is gated by `pollingPaused` / `adoPollEnabled` / `adoPrStatusPollEnabled` and not by `autoFixPaused`. Its Settings control therefore lives in the **Polling** pane under "Poll-side actions", *not* in the Monitor per-cause tile grid whose copy promises agent dispatch and Pause-ALL inertness. Any future poll-side action that writes to a provider without dispatching an agent belongs in the same place — putting it in the auto-fix grid advertises a kill-switch that will not fire.
 
 ## Per-PR per-cause pause (different mechanism)
 
@@ -58,9 +73,9 @@ This per-PR per-cause pause is unrelated to `autoFixPaused`. Cause values are va
 | File                      | Role                                                                                              |
 |---------------------------|---------------------------------------------------------------------------------------------------|
 | `engine.js#discoverFromPrs` | Single dispatch site walker — evaluates the six causes per tick in fixed order                  |
-| `engine/shared.js` (`ENGINE_DEFAULTS`) | Default values for every per-cause gate + both kill-switches                         |
-| `engine/lifecycle.js#runPostCompletionHooks` | Wires `autoReReviewPrs` into the closure-loop re-review path (P-e8b1c4d2)         |
-| `dashboard/js/settings.js` | Auto-fix & Review Loop pane (gates + `autoFixPaused`); Polling pane (`pollingPaused` + granular polls) |
+| `engine/core/shared.js` (`ENGINE_DEFAULTS`) | Default values for every per-cause gate + both kill-switches                         |
+| `engine/orchestration/lifecycle.js#runPostCompletionHooks` | Wires `autoReReviewPrs` into the closure-loop re-review path (P-e8b1c4d2)         |
+| `dashboard/js/settings.js` | Plan & PR Workflow → Monitor subsection (gates + `autoFixPaused`); Polling pane (`pollingPaused` + granular polls + poll-side actions like `adoQueueDraftPrBuilds`) |
 | `dashboard/js/render-dispatch.js` | `renderPausedBanner(engine)` — sticky cross-page banner showing both pause states          |
 | `POST /api/pull-requests/clear-paused-cause` | Clears a per-PR per-cause pause record                                          |
 | `POST /api/engine/polling/{pause,resume}`, `POST /api/engine/auto-fix/{pause,resume}` | Convenience endpoints for the two master flags (P-f3c9d0e7) |

package/docs/pr-comment-followup.md

@@ -5,7 +5,7 @@ proposal investigated in CC turn `cct-mpeira1y0001ddff`).
 
 ## Why
 
-`engine/{github,ado}.js` `pollPrHumanComments` routes every actionable human PR
+`engine/providers/github.js` and `engine/ado/index.js` `pollPrHumanComments` route every actionable human PR
 comment into `pr.humanFeedback.pendingFix:true`, which `discover-from-prs`
 turns into a `fix` dispatch on the **same** branch. The `fix.md` playbook then
 forbids broadening the PR or creating a replacement branch. The net result was
@@ -28,7 +28,7 @@ playbook contract. The poller is unchanged; the carve-out is purely additive.
 1. **Human leaves a comment on PR #2400** asking for a related-but-distinct
    refactor: *"Can you also extract the markdown sanitizer into a shared module?
    Probably worth a separate PR though."*
-2. **Engine pollers** (`engine/github.js` `pollPrHumanComments`) flag the
+2. **Engine pollers** (`engine/providers/github.js` `pollPrHumanComments`) flag the
    comment, set `pr.humanFeedback.pendingFix:true`, and `discover-from-prs`
    queues a `fix` dispatch against PR #2400's branch.
 3. **Fix agent (e.g. lambert)** starts working. After fetching the diff and
@@ -102,7 +102,7 @@ playbook contract. The poller is unchanged; the carve-out is purely additive.
      ]
    }
    ```
-   `engine/lifecycle.js processCompletionFollowups` logs each entry at `info`
+   `engine/orchestration/lifecycle.js processCompletionFollowups` logs each entry at `info`
    and warns if the claimed `wi_id` is missing from any project's
    SQL work-item store (catches reverted or non-landing dispatches).
 
@@ -141,7 +141,7 @@ exists; you still reply on the comment thread with the returned id.
 
 ## What does NOT change
 
-- The pollers (`engine/github.js`, `engine/ado.js`) still set
+- The pollers (`engine/providers/github.js`, `engine/ado/index.js`) still set
   `pr.humanFeedback.pendingFix:true` for every actionable human comment.
 - `discover-from-prs` still queues `fix` dispatches against the original
   branch; nothing prevents the in-place fix from proceeding.
@@ -179,7 +179,7 @@ exists; you still reply on the comment thread with the returned id.
 | `dashboard.js` (`validatePrFollowupShape`, `findExistingFollowupForComment`, `extractMinionsAgentHeader`, `extractMinionsOriginWiHeader`, `handleWorkItemsCreate`) | Shape validation, parent_comment_id dedup, header persistence, 200/400/409 responses. |
 | `dashboard/js/render-work-items.js` (`prFollowup` block in `wiRow`) | `↪ from PR #N` chip on follow-up WIs. |
 | `dashboard/js/render-prs.js` (`_countPrFollowups`) | `+N follow-ups` chip on PR rows. |
-| `engine/lifecycle.js` (`processCompletionFollowups`) | Parses the optional `followups` array on completion reports; warns on mismatch. |
+| `engine/orchestration/lifecycle.js` (`processCompletionFollowups`) | Parses the optional `followups` array on completion reports; warns on mismatch. |
 | `docs/completion-reports.md` (`PR-comment follow-ups`) | Schema for the optional `followups` array. |
 
 ## Migration / rollout
@@ -200,7 +200,7 @@ To adopt:
 
 ## Related
 
-- `engine/github.js pollPrHumanComments` (human-comment routing — unchanged)
+- `engine/providers/github.js pollPrHumanComments` (human-comment routing — unchanged)
 - `engine.js HUMAN_FEEDBACK fix dispatch` (in-place fix flow — unchanged)
 - `playbooks/templates/followup-dispatch.md` (the contract agents read)
 - `docs/completion-reports.md` `PR-comment follow-ups` section

package/docs/pr-review-fix-loop.md

@@ -37,12 +37,12 @@ A successful review dispatch that posts no `VERDICT:` comment and is not a recog
 
 When multiple problems coexist, earlier triggers get the first chance to enqueue work. The local `fixDispatched` flag is declared before the initial review trigger and set after first-review, human-feedback, review-feedback, and build-failure dispatches. Each later trigger checks `!fixDispatched`, so those sites suppress all subsequent review/fix work for that PR in the same discovery pass. Re-review is the exception: it checks `!fixDispatched` before enqueueing but does not set the flag afterward. Consequently, a re-review may enqueue alongside a later build-failure fix or, when no build fix is queued, a merge-conflict fix in the same pass.
 
-The engine does not cap review→fix cycles or build-fix attempts. Each trigger evaluates its own gates on every discovery pass; loops stop only when the underlying condition clears (reviewer approves, build passes, conflict resolves, human feedback handled). Operators who need to halt automation on a runaway PR have three escalating tools: (1) clear the relevant per-cause flag (`evalLoop`, `autoFixBuilds`, `autoFixConflicts`, `autoFixHumanComments`, `autoFixReviewFeedback`, `autoReviewPrs`, `autoReReviewPrs`); (2) flip the `autoFixPaused` master kill-switch to halt every auto-**fix** dispatch (sites B, C, D, and human-comment fix) at once while leaving review verdicts and polling fresh — Dashboard → Settings → Auto-fix & Review Loop or `POST /api/engine/auto-fix/pause`; (3) flip `pollingPaused` to halt PR polling entirely, which also forces every per-PR auto-dispatch gate inert. Per-PR per-cause noop pauses (`_noOpFixes[cause].paused`) are an orthogonal recovery surface — see §4E and `POST /api/pull-requests/clear-paused-cause`. See [docs/pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) for the full site × gate × kill-switch reference table.
+The engine does not cap review→fix cycles or build-fix attempts. Each trigger evaluates its own gates on every discovery pass; loops stop only when the underlying condition clears (reviewer approves, build passes, conflict resolves, human feedback handled). Operators who need to halt automation on a runaway PR have three escalating tools: (1) clear the relevant per-cause flag (`evalLoop`, `autoFixBuilds`, `autoFixConflicts`, `autoFixHumanComments`, `autoFixReviewFeedback`, `autoReviewPrs`, `autoReReviewPrs`); (2) flip the `autoFixPaused` master kill-switch to halt every auto-**fix** dispatch (sites B, C, D, and human-comment fix) at once while leaving review verdicts and polling fresh — Dashboard → Settings → Plan & PR Workflow → Monitor or `POST /api/engine/auto-fix/pause`; (3) flip `pollingPaused` to halt PR polling entirely, which also forces every per-PR auto-dispatch gate inert. Per-PR per-cause noop pauses (`_noOpFixes[cause].paused`) are an orthogonal recovery surface — see §4E and `POST /api/pull-requests/clear-paused-cause`. See [docs/pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) for the full site × gate × kill-switch reference table.
 
 ### A. Human comments (`humanFeedback.pendingFix`)
 
 - Gate: `pendingFix || hasCoalescedFeedback` + not already dispatched/on cooldown
-- Agent comments filtered out via `_isNonActionableComment()` (`engine/github.js`, `engine/ado.js`) — composes preview/bot body checks and the structural Minions-author check from `engine/comment-classifier.js`. The structural check matches the `<!-- minions:agent=<id> kind=<kind> -->` HTML marker on the body's first line (`hasMinionsMarker`); on GitHub it must combine with `viewerDidAuthor === true` (anti-spoof), on ADO with a `config.engine.minionsAdoIdentities` author match. Marker presence alone never classifies a comment as agent-authored on either platform.
+- Agent comments filtered out via `_isNonActionableComment()` (`engine/providers/github.js`, `engine/ado/index.js`) — composes preview/bot body checks and the structural Minions-author check from `engine/providers/comment-classifier.js`. Both pollers resolve marker authorship through the shared `classifyMarkerAuthorship()` seam, which combines the `<!-- minions:agent=<id> kind=<kind> -->` HTML marker on the body's first line (`hasMinionsMarker`) with a host identity signal: `viewerDidAuthor` on GitHub, a `config.engine.minionsAdoIdentities` author match on ADO. A marker plus an identity **mismatch** is never agent-authored (spoof guard). A marker with **no usable identity signal** — an unconfigured `minionsAdoIdentities`, the default — fails *safe* and is treated as agent-authored, and ADO logs a one-time warning that the spoof guard is inactive (W-msbf1kf6033f46cb). The previous fail-open reading gave the marker zero filtering power on ADO, so every agent fix-summary re-triggered a fix dispatch on the same PR.
 - Coalesces multiple comments arriving during cooldown into single fix
 - Routes to author
 - Fix agents must treat human comments as claims to verify, not commands. They inspect or reproduce each claimed issue, make the smallest correct fix only when the claim is valid, and otherwise reply with evidence-backed rationale.
@@ -82,11 +82,11 @@ A paused cause **suppresses further auto-dispatch for that cause** until cleared
 2. **Click the red chip on the dashboard** — confirms, then `POST /api/pull-requests/clear-paused-cause` (`dashboard.js`, issue #2969) validates the cause against `shared.PR_FIX_CAUSE`, locates the PR via `mutatePullRequests` across project/central files, and calls `clearPrNoOpFixAttempt` to wipe the cause record.
 3. **Direct API call** — `POST /api/pull-requests/clear-paused-cause` with `{ prId, cause }`.
 
-The exported `recordPrNoOpFixAttempt` / `clearPrNoOpFixAttempt` / `sweepStalePrNoOpFixes` helpers in `engine/lifecycle.js` are the only sanctioned entry points. The dispatch evaluator gates re-dispatch on `shared.isPrNoOpFixCausePaused(pr, cause)` (which re-validates the fingerprint per call), the dashboard chip surface uses `shared.getPrPausedCauses(pr)` (same gate), and the `pollPrStatus` callback in `engine/ado.js` + `engine/github.js` calls `sweepStalePrNoOpFixes(pr)` each tick to GC records whose fingerprint no longer matches the live PR.
+The exported `recordPrNoOpFixAttempt` / `clearPrNoOpFixAttempt` / `sweepStalePrNoOpFixes` helpers in `engine/orchestration/lifecycle.js` are the only sanctioned entry points. The dispatch evaluator gates re-dispatch on `shared.isPrNoOpFixCausePaused(pr, cause)` (which re-validates the fingerprint per call), the dashboard chip surface uses `shared.getPrPausedCauses(pr)` (same gate), and the `pollPrStatus` callback in `engine/ado/index.js` + `engine/providers/github.js` calls `sweepStalePrNoOpFixes(pr)` each tick to GC records whose fingerprint no longer matches the live PR.
 
 #### E2. Build-fix-ineffective tracker (`pr._buildFixIneffective`, issue #639)
 
-A "branch unchanged" no-op report for a `BUILD_FAILURE`-cause fix used to be conflated with the generic `_noOpFixes[BUILD_FAILURE]` counter even when the build was still genuinely red on the unchanged head — silently masking a stuck failure as "handled". `checkBuildStillFailingLive()` re-polls host-specific live CI (`checkLiveBuildAndConflict` in `engine/github.js` / `engine/ado.js`) right after `detectPrFixBranchChange()` reports no branch change for a build-failure fix. If the build is still failing, `recordBuildFixIneffective()` tracks a **separate**, `headSha`-keyed counter (`pr._buildFixIneffective`) instead of bumping `_noOpFixes[BUILD_FAILURE]`, pausing after `prNoOpFixPauseAttempts` on the same head and writing a distinct `build-fix-ineffective-<pr>` inbox alert; `shared.isBuildFixIneffectivePaused()` re-validates the stored `headSha` against the live PR before honoring the pause (same fingerprint-revalidation pattern as `isPrNoOpFixCausePaused`), and `engine.js` wires `isBuildFixIneffectiveSuppressed()` into the `BUILD_FAILURE` dispatch gate alongside the existing no-op check. A real branch-changing fix clears the stale record. The dashboard PR list (`dashboard/js/render-prs.js`) renders a separate, non-interactive "infra issue suspected" chip for a paused `_buildFixIneffective` record (tooltip shows `reason`/`count`/`headSha`/`liveBuildStatus`) alongside the existing `_pausedCauses` chips.
+A "branch unchanged" no-op report for a `BUILD_FAILURE`-cause fix used to be conflated with the generic `_noOpFixes[BUILD_FAILURE]` counter even when the build was still genuinely red on the unchanged head — silently masking a stuck failure as "handled". `checkBuildStillFailingLive()` re-polls host-specific live CI (`checkLiveBuildAndConflict` in `engine/providers/github.js` / `engine/ado/index.js`) right after `detectPrFixBranchChange()` reports no branch change for a build-failure fix. If the build is still failing, `recordBuildFixIneffective()` tracks a **separate**, `headSha`-keyed counter (`pr._buildFixIneffective`) instead of bumping `_noOpFixes[BUILD_FAILURE]`, pausing after `prNoOpFixPauseAttempts` on the same head and writing a distinct `build-fix-ineffective-<pr>` inbox alert; `shared.isBuildFixIneffectivePaused()` re-validates the stored `headSha` against the live PR before honoring the pause (same fingerprint-revalidation pattern as `isPrNoOpFixCausePaused`), and `engine.js` wires `isBuildFixIneffectiveSuppressed()` into the `BUILD_FAILURE` dispatch gate alongside the existing no-op check. A real branch-changing fix clears the stale record. The dashboard PR list (`dashboard/js/render-prs.js`) renders a separate, non-interactive "infra issue suspected" chip for a paused `_buildFixIneffective` record (tooltip shows `reason`/`count`/`headSha`/`liveBuildStatus`) alongside the existing `_pausedCauses` chips.
 
 ## 5. Fix completes
 
@@ -128,12 +128,12 @@ A "branch unchanged" no-op report for a `BUILD_FAILURE`-cause fix used to be con
 | File | Functions |
 |---|---|
 | `engine.js` | `discoverFromPrs()` — discovery + dispatch logic |
-| `engine/lifecycle.js` | `syncPrsFromOutput()`, `updatePrAfterReview()`, `updatePrAfterFix()` |
-| `engine/github.js` | `pollPrStatus()`, `pollPrHumanComments()`, `fetchGhBuildErrorLog()` |
-| `engine/ado.js` | `pollPrStatus()`, `pollPrHumanComments()`, `fetchAdoBuildErrorLog()` |
-| `engine/comment-classifier.js` | Host-agnostic body-only predicates (`isPreviewStatusBody`, `hasMinionsMarker`, `hasVerdictPrefix`) shared by GH + ADO pollers (extracted in F2+F3+F4) |
-| `engine/dispatch.js` | `addToDispatch()` — dedup by work item ID and dispatchKey |
-| `engine/cooldown.js` | `isBranchActive()`, cooldown management |
+| `engine/orchestration/lifecycle.js` | `syncPrsFromOutput()`, `updatePrAfterReview()`, `updatePrAfterFix()` |
+| `engine/providers/github.js` | `pollPrStatus()`, `pollPrHumanComments()`, `fetchGhBuildErrorLog()` |
+| `engine/ado/index.js` | `pollPrStatus()`, `pollPrHumanComments()`, `fetchAdoBuildErrorLog()` |
+| `engine/providers/comment-classifier.js` | Host-agnostic body-only predicates (`isPreviewStatusBody`, `hasMinionsMarker`, `hasVerdictPrefix`) plus the shared marker+identity seam (`classifyMarkerAuthorship`, `isMarkerAuthored`, `MARKER_AUTHORSHIP`) used by GH + ADO pollers (extracted in F2+F3+F4; seam added in W-msbf1kf6033f46cb) |
+| `engine/orchestration/dispatch.js` | `addToDispatch()` — dedup by work item ID and dispatchKey |
+| `engine/orchestration/cooldown.js` | `isBranchActive()`, cooldown management |
 | `playbooks/review.md` | Reviewer playbook |
 | `playbooks/fix.md` | Fix agent playbook |
 
@@ -154,6 +154,54 @@ A "branch unchanged" no-op report for a `BUILD_FAILURE`-cause fix used to be con
 | `humanFeedback` | `pollPrHumanComments()` | `{ pendingFix, feedbackContent, lastProcessedCommentDate }` |
 | `_noOpFixes[cause]` | `recordPrNoOpFixAttempt()` | Per-cause record `{ count, paused, fingerprint, beforeHead, afterHead }` driving the issue #2969 pause loop |
 | `_pausedCauses` | `queries.getPullRequests()` enrichment | Read-only list of currently-paused cause keys for UI rendering (computed from `_noOpFixes`) |
+| `_abandonedAt` | Poller (on every entry into `abandoned`) | Anchor for the bounded abandoned re-probe window (below). Cleared on reopen |
+| `_reconciliation404Confirmed` | Poller + startup reconciliation | Host confirmed the PR is genuinely deleted — closes the re-probe window early |
+
+## Abandoned is not a one-way door (W-msav5edk00g81710)
+
+`abandoned` is the only terminal PR status a record can legitimately **leave**:
+GitHub reopens a closed PR and ADO reactivates an abandoned one. Both pollers
+already implement the reopen transition (`oldStatus === abandoned && newStatus
+=== active` → `P-f5reopenreset` clears the stale review session), but before this
+WI that code was unreachable: `forEachActiveGhPr` / `forEachActivePr` filtered on
+`PR_POLLABLE_STATUSES = {active, linked}`, so an abandoned record left the poll
+loop forever and the only un-flip path was the **boot-only, version-gated**
+`reconcileAbandonedPrs`. Incident: `github:opg-microsoft/minions#1154` was closed
+at 16:07:07Z, reopened at 16:10:07Z, and sat `abandoned` for hours while OPEN and
+approved — invisible to `discoverFromPrs`, misread by `syncPrdFromPrs`, and one
+"remove merged + abandoned PRs" sweep away from a permanent `userDeleted`
+tombstone.
+
+**The contract now:**
+
+- `shared.isPrPollable(pr, { windowMs, now })` is the single pollability
+  predicate. Both providers filter through it — never re-check
+  `PR_POLLABLE_STATUSES` directly, or the two pollers drift again.
+- An `abandoned` record stays pollable for `engine.abandonedPrRepollWindowMs`
+  (`ENGINE_DEFAULTS`, default **7 days**; Settings → *Abandoned PR Re-probe
+  Window*; `0` disables) measured from `_abandonedAt`, falling back to `closedAt`
+  for records stamped before this WI.
+- **Opt-in per call site.** Only `pollPrStatus` passes the window. The comment
+  poller never widens — the reopen signal lives on the status endpoint, so
+  widening it would burn quota for no signal.
+- **Cost controls preserved.** The window is aged (not "re-probe every terminal
+  record forever"); a record with no anchor fails **CLOSED** and is never
+  re-probed; and a host-confirmed deletion sets `_reconciliation404Confirmed`,
+  which drops the record out of the window immediately. On GitHub that marker is
+  now reachable from the normal poll too, after the same
+  `prAbandonConfirmCount` consecutive 404s that the abandon trapdoor requires.
+- `merged` remains genuinely irreversible and is never re-probed.
+- Records older than the window are healed only by the version-gated startup pass
+  (`ENGINE_DEFAULTS.abandonedReconciliationVersion`), which is why this WI bumped
+  it — that boot pass is the one-off repair for pre-existing mis-stamps.
+
+**Implication for the merged/abandoned tracker sweep:** a `status: abandoned`
+stamp is a *sampled observation*, not proof of terminality, so verify at the host
+before tombstoning. `POST /api/pull-requests/delete` sets a permanent
+`userDeleted` marker that pollers must never clear, so a mis-stamp pruned by the
+sweep is unrecoverable. The bounded window shrinks that hazard structurally: a
+mis-stamp now self-heals within one poll cycle instead of persisting until the
+next engine boot.
 
 ## Platform differences
 
@@ -171,4 +219,5 @@ A "branch unchanged" no-op report for a `BUILD_FAILURE`-cause fix used to be con
 - Builds use the merge commit hash as `sourceVersion`, not the source branch commit — compare against `lastMergeCommit.commitId`
 - `partiallySucceeded` counts as passing (warnings, not failures)
 - A stale but passing build is still valid — don't re-trigger builds that already passed
+- `refs/pull/<n>/merge` accumulates builds for EVERY push to the PR (the poller reads `$top=25`), so when no build targets the current merge commit the stale set spans the PR's whole history. `classifyStaleBuilds()` therefore groups by `sourceVersion` via `selectNewestMergeCommitBuilds()` and classifies only the **most recently built merge commit** — OR-ing failures across the full history pinned a PR to `failing` forever once any build had ever failed, burning a build-fix dispatch per poll on an already-green branch (W-msaux21y00g79c48, ADO PR 5531150). When that newest generation is green and the cached status is `failing`, the cached failure is provably older (the current merge commit has no build at all), so it is dropped to `none` — `supersededCachedFailure: true`, which `checkLiveBuildAndConflict()` also surfaces so the pre-dispatch gate skips the fix. Never `passing`: the current merge commit is still unbuilt. Draft PRs hit this path most, since ADO doesn't auto-run branch policies on drafts
 - ADO never auto-clears a reviewer's numeric vote when new commits land, so a hard-reject `-10` vote stays live forever unless the reviewer explicitly re-votes. Both `pollPrStatus()` and the pre-dispatch `checkLiveReviewStatus()` treat a `-10` as **stale/superseded** (resolving to `waiting` instead of `changes-requested`) via `isStaleAdoRejectVote()` once a fix has completed after the vote's last review (`fixedAt > lastReviewedAt`) with no push since (`lastPushedAt <= fixedAt`) — otherwise the auto re-review-after-fix flow can never fire for that PR (issue #633).

package/docs/process-termination.md

@@ -0,0 +1,40 @@
+# Process termination
+
+All Minions-initiated process termination goes through
+`engine/processes/process-utils.js#terminateProcess`. The exported
+`PROCESS_TERMINATION_SITES` object is the authoritative inventory: every entry
+declares its termination mode, ownership proof, and purpose. Unknown sites fail
+closed.
+
+Print the current inventory:
+
+```powershell
+node -e "console.table(Object.entries(require('./engine/processes/process-utils').PROCESS_TERMINATION_SITES).map(([site, policy]) => ({ site, ...policy })))"
+```
+
+`test/unit/process-termination-gateway.test.js` enforces that:
+
+- every production and test-harness `terminateProcess()` call uses a registered site;
+- every non-compatibility inventory entry has a caller;
+- raw process signals, child/facade `.kill()`, and platform kill commands occur
+  only inside `engine/processes/process-utils.js`;
+- production code cannot use the legacy compatibility wrappers or assert
+  `ownershipVerified`; the gateway re-checks script identity, PID birth time,
+  declaration time, tracked-agent command line, or a live child handle itself.
+
+Signal-0 liveness probes (`process.kill(pid, 0)`) do not terminate a process and
+are explicitly exempt. The PowerShell/bash snippets emitted in the managed-spawn
+smoke-test instructions clean up a process launched by that same interactive
+snippet; they are guidance text, not engine-executed termination.
+
+The supervisor's dashboard replacement site requires consecutive ticks where
+neither the port probe nor `/api/health` proves responsiveness. A single loaded-
+host probe miss cannot reach `engine.supervisor.daemon-replace`.
+
+Multi-file unit, integration, and perf runners also fail before spawning workers
+when Windows PID 4 is already above the system-handle safety limit, and stop
+scheduling after an OS resource-exhaustion result. This prevents a damaged host
+from turning one infrastructure failure into process churn and daemon restarts.
+The engine also stamps conservative test concurrency into every cold, pooled,
+and steering-resumed agent environment, so stale PR branches are bounded before
+their repository-local runner code loads.

package/docs/proposals/repo-pool-for-live-checkout.md

@@ -50,13 +50,13 @@ additive.
   (source: `config.json` → projects[] `src`).
 - **Mode resolution.** `shared.resolveCheckoutMode(project, workItemType)`
   returns `'live'|'worktree'`, honoring the legacy `worktreeMode` field and the
-  `liveValidation` hybrid routing (source: `engine/shared.js:2911`).
+  `liveValidation` hybrid routing (source: `engine/core/shared.js:2911`).
   `shared.isLiveCheckoutProject(project)` is the convenience predicate
-  (source: `engine/shared.js:2943`).
+  (source: `engine/core/shared.js:2943`).
 - **Path resolution.** `shared.resolveSpawnPaths(project, type, minionsDir, opts)`
   short-circuits for live mode and returns
   `{ cwd: path.resolve(project.localPath) (+workdir), worktreeRootDir:null, liveMode:true }`
-  (source: `engine/shared.js:6355-6382`). It throws `LIVE_CHECKOUT_NO_LOCALPATH`
+  (source: `engine/core/shared.js:6355-6382`). It throws `LIVE_CHECKOUT_NO_LOCALPATH`
   if `localPath` is falsy. **This is the single point where the enlistment path
   is chosen** — it hard-reads `project.localPath`.
 - **Per-project mutating-concurrency cap of 1.** The allocation loop in the
@@ -69,25 +69,25 @@ additive.
   it is derived from `dispatch.active`, which is SQL-backed** (see persistence
   below). The pool needs this to become a **per-path** claim, not per-project.
 - **In-place checkout + recovery policies.** `spawnAgent` (engine.js) calls
-  `engine/live-checkout.js#prepareLiveCheckout({ localPath: cwd, branchName, … })`
+  `engine/worktrees/live-checkout.js#prepareLiveCheckout({ localPath: cwd, branchName, … })`
   which: runs `git status --porcelain` (dirty gate), mid-operation / detached-HEAD
   preflight, stale-base guard, and branch checkout/creation — all against the one
-  `cwd` (source: `engine.js:2453-2497`, `engine/live-checkout.js:374`). The dirty
+  `cwd` (source: `engine.js:2453-2497`, `engine/worktrees/live-checkout.js:374`). The dirty
   recovery policies resolve per-project-then-fleet-wide:
-  - `liveCheckoutAutoStash` — `resolveLiveCheckoutAutoStash` (source: `engine/live-checkout.js:1248`), applied via `applyLiveCheckoutAutoStash` (source: `engine.js:2509`).
-  - `liveCheckoutAutoReset` — `shared.resolveLiveCheckoutAutoReset` (self-resolves by matching project on `localPath`, source: `docs/live-checkout-mode.md` §2b, `engine/live-checkout.js:332`).
-  - `liveCheckoutAutoBaseRepair` — `_defaultResolveAutoBaseRepair` (source: `engine/live-checkout.js:352`).
+  - `liveCheckoutAutoStash` — `resolveLiveCheckoutAutoStash` (source: `engine/worktrees/live-checkout.js:1248`), applied via `applyLiveCheckoutAutoStash` (source: `engine.js:2509`).
+  - `liveCheckoutAutoReset` — `shared.resolveLiveCheckoutAutoReset` (self-resolves by matching project on `localPath`, source: `docs/live-checkout-mode.md` §2b, `engine/worktrees/live-checkout.js:332`).
+  - `liveCheckoutAutoBaseRepair` — `_defaultResolveAutoBaseRepair` (source: `engine/worktrees/live-checkout.js:352`).
   **All three resolve/match by `localPath`**, so they need to key off the
   selected enlistment path, not the project's canonical `localPath`.
 - **Dispatch-end restore.** `restoreLiveCheckoutAtDispatchEnd` /
   `maybeRestoreLiveCheckoutFromRecord` put the tree back on `originalRef`
-  (source: `engine/live-checkout.js:1009, 1423`). These operate on a recorded
+  (source: `engine/worktrees/live-checkout.js:1009, 1423`). These operate on a recorded
   `localPath` and must record/restore the **selected** enlistment.
 
 ### Persistence (survives restart)
 
 - Dispatch state lives in **SQLite** `engine/state.db` `dispatches` table via
-  `engine/dispatch-store.js` (`readDispatchSectioned` / `applyDispatchMutation`).
+  `engine/persistence/dispatch-store.js` (`readDispatchSectioned` / `applyDispatchMutation`).
   Each active dispatch is one JSON record. **Because `liveProjectsInUse` is
   rebuilt from `dispatch.active` every tick, recording the claimed enlistment
   path on the active dispatch record makes the per-path claim automatically
@@ -99,7 +99,7 @@ additive.
 
 - `meta.workdir` is already a validated relative-POSIX subpath under the spawn
   base; when set, the engine lands the agent at `<base>/<workdir>` and clips
-  harness discovery to that subtree (source: `engine/shared.js:6404-6416`,
+  harness discovery to that subtree (source: `engine/core/shared.js:6404-6416`,
   `validateWorkItemWorkdir`). This is the natural signal for "which subpath does
   this WI need" — subproject validation can reuse/extend it. There is also
   `detectDominantSubproject({ projectPath, changedPaths })` used post-completion
@@ -118,7 +118,7 @@ additive.
 - **Project cards.** `dashboard/js/render-other.js` renders per-project git
   branch/dirty/state pills from `p.gitBranch/p.gitDirty/p.gitState`
   (source: `dashboard/js/render-other.js:103-172`), fed by the per-`localPath`
-  git-status probe cache in `engine/queries.js:2512-2607` (15s TTL, keyed by
+  git-status probe cache in `engine/core/queries.js:2512-2607` (15s TTL, keyed by
   normalized `localPath`). Per-enlistment status reuses this probe per path.
 - **Status payload.** `dashboard.js:2768-2785` emits `checkoutMode`,
   `liveValidationType`, etc. per project — the place to add pool-member status.
@@ -172,7 +172,7 @@ Key design decisions and rationale:
    dispatch record before the agent spawns, closing the double-claim window.
 
 4. **Clean-tree + subpath validation at selection are cheap.** Clean-tree reuses
-   the existing 15s-TTL per-path git-status probe cache (`engine/queries.js`), so
+   the existing 15s-TTL per-path git-status probe cache (`engine/core/queries.js`), so
    selection does not add a fresh `git status` per tick per path. Subpath
    validation is a pure `fs.existsSync(<path>/<subpath>)` (or a `sparseScope`
    prefix match when declared) — no build, no git. Rationale: selection runs every