@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/README.md

@@ -31,7 +31,9 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [api-errors.md](api-errors.md) — Dashboard API error contract: the stable `{error, code, field, …}` envelope, the 400/404/409/422/5xx status taxonomy, the safe (bounded + secret-redacted) rejected-value policy, alias/enum compatibility rules, and the self-correct-4xx / don't-blindly-retry-5xx behavior. Contracts are discoverable via `GET /api/routes` and the `engine/api-contracts` route-to-validation matrix.
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
+- [ci-runner-canary.md](ci-runner-canary.md) — The hourly hosted-runner canary: why a self-hosted outage produces stalled runs instead of failed ones (so failure-only health checks report "all green" while CI is dark), the properties that keep the canary out of that failure domain, and why the runner-inventory check is unavailable to `GITHUB_TOKEN`.
 - [claude-md-propagation.md](claude-md-propagation.md) — Propagating repo-authored `CLAUDE.md` instructions to runtimes that don't auto-load it (Copilot/Codex): the `claudeMdNativeDiscovery` capability flag, the bounded nearest-applicable walk-up discovery, the `propagateClaudeMdForNonClaudeRuntimes` config knob, and why it's orthogonal to each runtime's native `AGENTS.md` discovery.
+- [cloud-agent-dispatch.md](cloud-agent-dispatch.md) — The `cloud` execution surface: handing a work item to a REMOTE coding agent (Agency / Copilot cloud) that authors its own PR. Covers why a cloud provider is not a runtime adapter, the `engine/cloud` provider contract, the PR-producing eligibility allowlist (and why `review`/`verify` are refused), and the fail-closed gating that refuses a cloud dispatch rather than silently running it locally.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: configured-runtime sessions, resume semantics, system-prompt invalidation, and per-tab session storage.
 - [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
 - [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.
@@ -43,38 +45,41 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
 - [cross-repo-plans.md](cross-repo-plans.md) — Cross-repo plans: a single plan whose work items ship into two or more configured projects — per-item `project` field, per-project work-item fan-out, and one verify work item per touched repo.
 - [dead-code-audit-retractions.md](dead-code-audit-retractions.md) — Retracted dead-code-audit findings (false positives) that future audits MUST read before re-citing.
+- [default-branch-ci.md](default-branch-ci.md) — The post-merge default-branch gate: why a `pull_request` gate cannot catch merge-order defects (two green PRs that break only in combination), why the post-merge workflow *calls* the PR gate rather than copying it or inverting the direction (the ruleset requires the `Unit Tests` context by exact string), the cost controls, and the evaluated-but-rejected merge-queue alternative.
 - [deprecated-process.md](deprecated-process.md) — Schema for `docs/deprecated.json` and the weekly `cleanup-deprecated` audit walk that retires entries past their removal signal.
 - [design-inbox-entries-schema.md](design-inbox-entries-schema.md) — Implemented SQL schema and store contract for the future operator/agent inbox queue, including current indexes, mutators, event emission, and integration status.
+- [design-language.md](design-language.md) — Code-derived Minions design-language specification: color tokens, typography, spacing, component primitives (buttons/badges/tables/modals/Command Center), status→class→color maps, Classic vs Slim shared-vs-different foundations, a migration playbook, and an objective audit rubric — all traceable to `dashboard/` CSS/JS with file+line citations.
 - [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` (accepted; implementation tracked in CHANGELOG.md Phases 0–10).
-- [dev-composite-workflow.md](dev-composite-workflow.md) — The recurring "rebuild the composite branch from all my open PRs and relaunch the dev dashboard" workflow, and the `rebuild-composite` skill + `scripts/rebuild-composite.ps1` that automate it.
 - [harness-mode.md](harness-mode.md) — Tri-Agent Harness Mode (`harness_mode: "tri_agent"` on scheduled tasks): Planner → Generator → Evaluator loop that iterates a shared on-disk artifact until a rubric passes or the iteration cap fires.
 - [harness-propagation.md](harness-propagation.md) — The native runtime
   contract for repository instructions, skills, commands, and MCPs.
 - [kb-dedup-duplicate-pair-investigation.md](kb-dedup-duplicate-pair-investigation.md) — Investigation-only pass diffing suspected duplicate KB filename groups (content-hash dedup for agent-authored reviews/build-reports) to confirm true full-body duplication before any fix is proposed.
 - [kb-pr3223-cascade-archiving.md](kb-pr3223-cascade-archiving.md) — Findings from PR #3223: cascade-archiving PRDs when their linked markdown plan is archived, including the per-concern try/catch pattern and `source_plan` basename-matching invariant in `handlePlansArchive` (`dashboard.js`).
-- [kb-pr696-merge-conflict-docs.md](kb-pr696-merge-conflict-docs.md) — Findings from PR #696: resolving a merge conflict in `docs/kb-sweep.md` with stale line-number citations to `engine/kb-sweep.js`.
-- [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
+- [kb-pr696-merge-conflict-docs.md](kb-pr696-merge-conflict-docs.md) — Findings from PR #696: resolving a merge conflict in `docs/kb-sweep.md` with stale line-number citations to `engine/memory/kb-sweep.js`.
+- [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/processes/keep-process-sweep.js`](../engine/processes/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.
 - [named-agents.md](named-agents.md) — The named-agent roster (Ripley / Dallas / Lambert / Rebecca / Ralph): per-agent `config.json` shape, the per-agent → `engine.*` → runtime resolution chain, how `routing.md` (not the `role`/`skills` metadata) drives dispatch, descriptive vs runtime skills, and per-agent memory files.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) — Short reference table mapping each PR auto-fix / review dispatch site in `engine.js#discoverFromPrs` to its gate flag, plus the `pollingPaused` / `autoFixPaused` master kill-switches and the per-provider polling gates.
+- [pr-author-identity.md](pr-author-identity.md) — Separating a PR's real author identity (`pr.author`, provider-linked) from the Minions agent that owns the automated work (`pr.agent`): the structured author shape, the provider builders, centralized merge, migration 031, and the dashboard Author column.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.
 - [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
+- [process-termination.md](process-termination.md) — The `terminateProcess` gateway: `PROCESS_TERMINATION_SITES` is the authoritative site inventory (mode + ownership proof per entry), how to print it, what the gateway test enforces, and the signal-0 liveness exemption.
 - [proposals/repo-pool-for-live-checkout.md](proposals/repo-pool-for-live-checkout.md) — Review-only artifact reproducing the approved plan + PRD for a repo pool covering live-checkout projects (multi-enlistment dispatch), so the design has a git-tracked surface for human comment before the dependent implementation work items land as code PRs.
 - [qa-runbook-lifecycle.md](qa-runbook-lifecycle.md) — End-to-end QA runbook lifecycle (W-mpeiwz6k0005bf34): runbook + run-record storage, `POST /api/qa/runbooks/run` dispatch into the `qa-validate` playbook, artifact contract, and how the `/qa` page mirrors managed-spawn observability.
 - [qa-runbooks.md](qa-runbooks.md) — Per-project QA runbook schema, storage layout (`projects/<name>/runbooks/<id>.json`), CRUD endpoints, run-record lifecycle, and the `qa-validate` agent sidecar contract.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
 - [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.
 - [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop, including structured review learning (durable, always-on lessons from verified review findings).
-- [shared-lifecycle-module-map.md](shared-lifecycle-module-map.md) — Documentation-only module-boundary audit of `engine/shared.js` / `engine/lifecycle.js`: function inventory, cross-file call graph, and a proposed split map (no code moved).
+- [shared-lifecycle-module-map.md](shared-lifecycle-module-map.md) — Documentation-only module-boundary audit of `engine/core/shared.js` / `engine/orchestration/lifecycle.js`: function inventory, cross-file call graph, and a proposed split map (no code moved).
 - [skills.md](skills.md) — Skill block format: how agents emit reusable `\`\`\`skill` blocks and how the engine extracts them into native personal-skill directories.
 - [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX design notes: simplified surface concepts driving the project picker, inline project link, and decoupled folder picker.
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
 - [team-memory.md](team-memory.md) — End-to-end hybrid memory system: file-backed inputs and consolidation, SQL/FTS5 records, retrieval and fallback, prompt bounds, episodic capture, the review-learning lifecycle (capture/recall/promotion/contradiction/diagnostics) and its rollout history + acceptance measurement, security, APIs, and operations.
 - [timeouts-and-liveness.md](timeouts-and-liveness.md) — What kills (or doesn't kill) a live tracked agent: the wall-clock vs steering kill invariants, spawn-phase watchdog gates, steering safety nets, and stale-orphan detection ladder.
 - [visual-evidence-ci.md](visual-evidence-ci.md) — GitHub Actions before/after dashboard capture: path and label triggers, deterministic base/head fixtures, artifact/comment lifecycle, trust boundary, and local reproduction.
-- [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
+- [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watch-plugins/` extension folder.
 - [workspace-manifests.md](workspace-manifests.md) — Declarative per-agent permission scoping: `allowed_tools` / `allowed_repos` / `allowed_external_urls` / `memory_scope`, dispatch-time repo gate, and runtime `--allowedTools` narrowing.
 - [worktree-lifecycle.md](worktree-lifecycle.md) — Worktree pool recycling, the live-dispatch guard that prevents wiping an agent's unpushed work, the dirty/divergent quarantine path, and the Windows EPERM/EBUSY file-lock retry footgun.
 
@@ -87,7 +92,7 @@ Operational runbooks for engine operators and fleet maintainers.
 - [diagnostics-crash-reports.md](diagnostics-crash-reports.md) — Proactive Node crash-diagnostics reports (`--report-on-fatalerror --report-on-signal --diagnostic-dir=...`) for the engine.js process on Windows: where reports land, config/opt-out, and retention.
 - [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
-- [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
+- [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/memory/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
 - [preflight.md](preflight.md) — `minions doctor` and the internal initialization/startup preflight: what each non-self-explanatory row (permission bypass, runtime detection, drive-root, etc.) is asserting.
 - [security.md](security.md) — Threat model: single-user/loopback deployment assumptions, dashboard Origin gate, data-flow trust boundaries, secret handling, and known residual risks (CSRF sweep, prompt injection, log-redactor audit).
 

package/docs/api-errors.md

@@ -38,7 +38,7 @@ immediately in the plan verification guide.
 ## Stable error envelope
 
 Every rejected request returns a JSON body with a stable shape (built by
-`engine/api-validation.js#toApiErrorResponse` / `exposedEnvelope`):
+`engine/api/api-validation.js#toApiErrorResponse` / `exposedEnvelope`):
 
 ```json
 {
@@ -83,7 +83,7 @@ reach the client.
 ## Safe rejected-value policy
 
 Echoing back the value that was rejected is convenient for debugging but is a
-data-exfiltration and log-poisoning risk. `engine/api-validation.js` enforces a
+data-exfiltration and log-poisoning risk. `engine/api/api-validation.js` enforces a
 uniform **safe rejected-value policy**:
 
 - **Strings** are bounded (default cap) before being echoed.

package/docs/architecture-review-2026-07-09.md

@@ -81,7 +81,7 @@ These require separate focused changes rather than expanding this PR:
    frequently while the runtime is alive.
 6. **Supervisor stale PID reuse (medium).** Startup trusts any live PID in
    `supervisor.pid`. Validate the command line against this checkout's
-   `engine/supervisor.js` before suppressing startup.
+   `engine/recovery/supervisor.js` before suppressing startup.
 
 ## Healthy areas
 

package/docs/architecture.excalidraw

@@ -1268,11 +1268,11 @@
       "versionNonce": 1339287385,
       "fontSize": 13,
       "fontFamily": 3,
-      "text": "PR integrations\n\nengine/github.js \u00b7 engine/ado.js\ngh-token.js \u00b7 ado-token.js\n\n\u2022 status + comment polling\n\u2022 reconciliation\n\u2022 verdict-flip reset",
+      "text": "PR integrations\n\nengine/providers/github.js \u00b7 engine/ado/index.js\nproviders/gh-token.js \u00b7 ado/token.js\n\n\u2022 status + comment polling\n\u2022 reconciliation\n\u2022 verdict-flip reset",
       "textAlign": "center",
       "verticalAlign": "middle",
       "containerId": "P5ocuAQmXTFm8tYonVs7",
-      "originalText": "PR integrations\n\nengine/github.js \u00b7 engine/ado.js\ngh-token.js \u00b7 ado-token.js\n\n\u2022 status + comment polling\n\u2022 reconciliation\n\u2022 verdict-flip reset",
+      "originalText": "PR integrations\n\nengine/providers/github.js \u00b7 engine/ado/index.js\nproviders/gh-token.js \u00b7 ado/token.js\n\n\u2022 status + comment polling\n\u2022 reconciliation\n\u2022 verdict-flip reset",
       "lineHeight": 1.25,
       "autoResize": false
     },

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-07-21 against `engine.js` `tickInner()`, `engine/shared.js`, and `routing.md`.
+> Last verified: 2026-07-21 against `engine.js` `tickInner()`, `engine/core/shared.js`, and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -72,11 +72,11 @@ Skips PRs where `status !== "active"`.
 
 Inside `discoverFromPrs()`, ADO and GitHub projects first resolve their own provider poll gate (`adoPollEnabled` or `ghPollEnabled`). PR-derived automation is inert when that provider's polling is off, so cached build, vote, conflict, and comment state cannot trigger new dispatches. The shared dispatch toggles (`autoReviewPrs`, `autoReReviewPrs`, `autoFixReviewFeedback`, `autoFixHumanComments`, `autoFixBuilds`, and `autoFixConflicts`) apply to both providers. `evalLoop` gates the minion review loop: initial minion reviews, minion re-reviews, and minion review-feedback fixes. Human-feedback fixes are evaluated outside `evalLoop`. Conflict fixes are additionally gated by `!fixDispatched`, so an earlier successful human/review/build fix dispatch in the same PR discovery pass suppresses the conflict fix until a later pass.
 
-**`autoReReviewPrs` gates both re-review paths (`P-e8b1c4d2`).** Re-reviews fire from two places: (1) the open-loop **discovery** path in `engine.js:discoverFromPrs` (PR shows `reviewStatus=waiting` after a fix push), and (2) the **closure-loop** in `engine/lifecycle.js:dispatchReReviewForFix` (a fix WI completes whose meta carries `addresses_review_wi`, queuing the next review against the same PR). The `engine.autoReReviewPrs` toggle is read at BOTH sites so flipping it OFF mutes the entire re-review cycle — not just the discovery sweep. Default ON; flip via Dashboard → Settings → Auto-fix & Review Loop, or `engine.autoReReviewPrs: false` in `config.json`.
+**`autoReReviewPrs` gates both re-review paths (`P-e8b1c4d2`).** Re-reviews fire from two places: (1) the open-loop **discovery** path in `engine.js:discoverFromPrs` (PR shows `reviewStatus=waiting` after a fix push), and (2) the **closure-loop** in `engine/orchestration/lifecycle.js:dispatchReReviewForFix` (a fix WI completes whose meta carries `addresses_review_wi`, queuing the next review against the same PR). The `engine.autoReReviewPrs` toggle is read at BOTH sites so flipping it OFF mutes the entire re-review cycle — not just the discovery sweep. Default ON; flip via Dashboard → Settings → Plan & PR Workflow → Monitor, or `engine.autoReReviewPrs: false` in `config.json`.
 
 **Hard-stop kill-switch (`pollingPaused`).** `engine.pollingPaused: true` is a master override that wins over both `adoPollEnabled` and `ghPollEnabled`. When ON, section 2.6/2.7 of the tick cycle skips `pollPrStatus` and `pollPrHumanComments` for both providers, `discoverFromPrs` forces `pollEnabled=false` for every project so every per-PR auto-dispatch gate (`autoReviewPrs` / `autoFixBuilds` / `autoFixConflicts` / `autoFixReviewFeedback` / `autoFixHumanComments`) becomes inert, and — since W-ms5eljc60090f0d5 — the reconcile tail (`reconcilePrs`, `ghReconcilePrs`, `reconcileSharedBranchPrs`) is skipped too. Reconciliation was previously exempt as a "recovery sweep", but those sweeps walk every tracked PR and issue provider API calls, so the documented emergency pause did not actually stop provider network traffic. The per-provider `*PrReconcileEnabled` flags remain independent whenever the master switch is OFF. The engine logs `[engine] PR polling paused — …` once on the transition from unpaused → paused; routine PR poll log lines resume when cleared. Flip via Dashboard → Settings → Polling, `POST /api/engine/polling/pause`, or set `engine.pollingPaused: true` in `config.json`. Default OFF — fresh installs behave identically to before this knob existed.
 
-**Hard-stop kill-switch (`autoFixPaused`).** `engine.autoFixPaused: true` is a narrower master override that wins over every auto-fix dispatch gate. When ON, `discoverFromPrs` forces `autoFixBuilds` / `autoFixConflicts` / `autoFixReviewFeedback` / `autoFixHumanComments` to false for every project, so no fix agent is auto-dispatched against any PR. Review dispatch (`autoReviewPrs` / `autoReReviewPrs`), PR status / human-comment polling, and reconciliation are intentionally not gated — operators can pause a fix-storm during an incident while still seeing fresh review verdicts and build status. The engine logs `[engine] auto-fix paused — …` once on the transition from unpaused → paused; routine discovery resumes when cleared. Flip via Dashboard → Settings → Auto-fix & Review Loop, or set `engine.autoFixPaused: true` in `config.json`. Default OFF — fresh installs behave identically to before this knob existed.
+**Hard-stop kill-switch (`autoFixPaused`).** `engine.autoFixPaused: true` is a narrower master override that wins over every auto-fix dispatch gate. When ON, `discoverFromPrs` forces `autoFixBuilds` / `autoFixConflicts` / `autoFixReviewFeedback` / `autoFixHumanComments` to false for every project, so no fix agent is auto-dispatched against any PR. Review dispatch (`autoReviewPrs` / `autoReReviewPrs`), PR status / human-comment polling, and reconciliation are intentionally not gated — operators can pause a fix-storm during an incident while still seeing fresh review verdicts and build status. The engine logs `[engine] auto-fix paused — …` once on the transition from unpaused → paused; routine discovery resumes when cleared. Flip via Dashboard → Settings → Plan & PR Workflow → Monitor, or set `engine.autoFixPaused: true` in `config.json`. Default OFF — fresh installs behave identically to before this knob existed.
 
 **Granular per-poller flags (`P-c4d8e1a3`).** The legacy `adoPollEnabled` / `ghPollEnabled` macros are bundle toggles that silence three axes at once (status, comments, reconcile) when set to `false`. To turn off only one axis, set the matching granular flag in `config.engine`:
 
@@ -167,10 +167,19 @@ This means a single work item like "Add telemetry to the document creation pipel
 
 **Reads:** `config.schedules[]` and persistent schedule-run state.
 
-Enabled schedules whose three-field cron expression matches the current minute produce work through `engine/scheduler.js`. Ordinary tasks and tri-agent harness missions are written to the central SQL work-item scope with `_scheduleId` metadata; meeting schedules create meeting records directly. The persisted `lastRun` value prevents a schedule from firing twice in the same calendar minute.
+Enabled schedules whose three-field cron expression matches the current minute produce work through `engine/orchestration/scheduler.js`. Ordinary tasks and tri-agent harness missions are written to the central SQL work-item scope with `_scheduleId` metadata; meeting schedules create meeting records directly. The persisted `lastRun` value prevents a schedule from firing twice in the same calendar minute.
+
+#### Scheduled-failure retention (`pruneSupersededFailedScheduledItems`)
+
+Machine-generated scheduled runs fail routinely (an hourly review/fetch sweep with a transient auth or network error), so without a retention policy their **failed** work items accumulate a week of duplicates. `engine/orchestration/failed-scheduled-cleanup.js` runs a conservative daily sweep inside `runCleanup` (step 21) to age them out:
+
+- **Targets only provable scheduled runs.** An item qualifies via structured provenance (`createdBy === 'scheduler'` **and** `_scheduleId`) or the canonical legacy `sched-<scheduleId>-<ts>` id prefix. Classification is **never** by title/description prose, so a human-authored item that merely mentions "scheduled" is untouched.
+- **Groups failures by originating schedule.** The **newest** failure per schedule is retained long enough to diagnose the current failure; **superseded** (older) failures are pruned once past the diagnostic window (`DIAGNOSTIC_RETENTION_MS`, 24h). A later **successful** run lets the newest failure be pruned too, once that window has elapsed. An absolute threshold (`ABSOLUTE_RETENTION_MS`, 7d) prunes stale failures regardless.
+- **Fails open.** Non-scheduled / human-authored failures, items with plan/PRD/decomposition/followup lineage (`parent_id`, `_prdItemId`), and any item referenced by a live (pending/active/review) dispatch are skipped, never deleted. This is destructive retention and is deliberately separate from the non-destructive navigation-badge age-out for user failures.
+- **Cadence, concurrency, idempotency.** Although `runCleanup` fires every ~10 min, a persisted `lastFailedScheduledPruneAt` marker in the engine small-state store gates the sweep to at most once per `PRUNE_INTERVAL_MS` (daily); the marker is claimed inside a single small-state transaction so overlapping ticks or a restart race cannot double-run it. Deletions go through `mutateWorkItems` and re-validate status/provenance against the fresh SQL row, so a re-run prunes nothing further. Pruned counts are logged once per sweep with the per-schedule breakdown — no per-tick noise. The policy is a documented shared default (no `engine.*` knob), so there is no Settings toggle to configure.
 
 `engine.bootstrapDefaultSchedules` defaults to `true` and is configurable under
-Dashboard → Settings → Workflow Defaults. `engine/schedule-bootstrap.js`
+Dashboard → Settings → Plan & PR Workflow → Monitor. `engine/orchestration/schedule-bootstrap.js`
 idempotently creates a read-only per-project git-fetch schedule (title-derived
 `keep-branch-fresh-git-fetch-origin-…` id, `0 */12 *`, `explore`) and one shared
 `harness-sweep-all-projects` schedule (`0 6 *`, `explore`, low priority).
@@ -202,7 +211,7 @@ Both write to the SQL work-item store and are picked up by Source 2 on the same
 
 ## PR Status Polling (`pollPrStatus`)
 
-**Runs:** On a wall-clock cadence derived from `prPollStatusEvery × engine.tickInterval` (default 72 × 10s, ≈ 12 minutes), independently of work discovery. ADO polling lives in `engine/ado.js`; GitHub polling lives in `engine/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write the shared SQL PR schema. Replaces the retired agent-based `pr-sync`.
+**Runs:** On a wall-clock cadence derived from `prPollStatusEvery × engine.tickInterval` (default 72 × 10s, ≈ 12 minutes), independently of work discovery. ADO polling lives in `engine/ado/index.js`; GitHub polling lives in `engine/providers/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write the shared SQL PR schema. Replaces the retired agent-based `pr-sync`.
 
 The engine directly polls host REST APIs for **all** PR metadata: build/CI status, human review votes, and completion state. No agent dispatch is needed.
 
@@ -220,7 +229,7 @@ The engine directly polls host REST APIs for **all** PR metadata: build/CI statu
 | `buildStatus` | ADO builds or GitHub check-runs | `passing` / `failing` / `running` / `none` |
 | `buildFailReason` | Failed build/check name | Set on failure, cleared otherwise |
 
-**Auth:** Bearer token via shared `engine/ado-token.js`: prefer `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv`, then fall back to `azureauth ado token --mode iwa --mode broker --output token --timeout 1` (cached 30 minutes). The `--timeout 1` flag is required — without it, azureauth can hang indefinitely in headless sessions. GitHub polling resolves a repo-scoped token through `engine/gh-token.js` and threads it as `GH_TOKEN` per call; it never switches global `gh` auth.
+**Auth:** Bearer token via shared `engine/ado/token.js`: prefer `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv`, then fall back to `azureauth ado token --mode iwa --mode broker --output token --timeout 1` (cached 30 minutes). The `--timeout 1` flag is required — without it, azureauth can hang indefinitely in headless sessions. GitHub polling resolves a repo-scoped token through `engine/providers/gh-token.js` and threads it as `GH_TOKEN` per call; it never switches global `gh` auth.
 
 This feeds `discoverFromPrs` — when `buildStatus` flips to `"failing"`, the next discovery tick dispatches a fix agent. When `status` becomes `"merged"`, the PR drops out of active polling.
 
@@ -342,8 +351,8 @@ memory are used. Human/LLM-authored appendices are wrapped as untrusted input.
 The engine resolves `resolveRuntime(resolveAgentCli(...))`; the selected adapter
 owns binary discovery, argv, prompt delivery, workspace preparation, and output
 parsing. Cold agent dispatches use the runtime-neutral
-`engine/spawn-agent.js`; opt-in Copilot fleet dispatch can use the ACP worker
-pool. CC/doc-chat use direct `engine/llm.js` calls.
+`engine/agents/spawn-agent.js`; opt-in Copilot fleet dispatch can use the ACP worker
+pool. CC/doc-chat use direct `engine/agents/llm.js` calls.
 
 - Process runs in the resolved worktree/live checkout (or `MINIONS_DIR` for
   project-less read-only work)

package/docs/branch-derivation.md

@@ -4,7 +4,7 @@ How the engine decides which branch a dispatch is going to push to.
 CLAUDE.md → Branch Naming holds the one-line summary; the structured
 vs. loose-extractor rules and the canonical PR-fix incident live here.
 
-> Source of truth: `engine/shared.js`
+> Source of truth: `engine/core/shared.js`
 > (`deriveWorkItemBranchName`, `extractStructuredWorkItemPrRef`,
 > `extractWorkItemPrRef`, `copyWorkItemPrFields`),
 > `engine.js#getWorkItemPrRef` + `getStructuredWorkItemPrRef`,
@@ -78,9 +78,9 @@ stamping:
 2. **Loose (description/title-scanned) refs on a fix WI** are confirmed via:
    - an already-tracked SQL PR record for the ref (cheap, no
      network), else
-   - a host existence check — `engine/github.js#prExists` (`gh api
-     repos/:owner/:repo/pulls/NNN`; 404 ⇒ issue) or `engine/ado.js#prExists`
-     (`…/pullrequests/NNN`), routed via `engine/gh-token.js` per-account token.
+   - a host existence check — `engine/providers/github.js#prExists` (`gh api
+     repos/:owner/:repo/pulls/NNN`; 404 ⇒ issue) or `engine/ado/index.js#prExists`
+     (`…/pullrequests/NNN`), routed via `engine/providers/gh-token.js` per-account token.
    `shared.classifyPrRefForVerification(prRef, project)` does the pure host/slug
    /number routing; the result is TTL-cached.
 3. **Fail-safe:** when existence can't be confirmed (issue, 404, network/auth

package/docs/capture-demos.js

@@ -3,13 +3,14 @@
  * Capture dashboard screenshots for GitHub Pages.
  * Seeds demo data, captures all pages, then cleans up.
  *
- * Run: node docs/capture-demos.js
- * Requires: dashboard running on :7331, playwright chromium installed
+ * Run: node docs/capture-demos.js --state-dir <isolated-state> --base-url <url>
+ * Requires: an isolated dashboard using the same state dir, and Playwright chromium
  */
 const { chromium } = require('@playwright/test');
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { canonicalPath, pathsOverlap } = require('../.github/scripts/owned-directory');
 
 const DEMO_DIR = path.join(__dirname, 'demo');
 const DEFAULT_BASE_URL = 'http://localhost:7331';
@@ -32,6 +33,7 @@ function parseArgs(argv = process.argv.slice(2)) {
     baseUrl: DEFAULT_BASE_URL,
     outputDir: DEMO_DIR,
     stateDir: null,
+    expectedStateDir: null,
     skipSeed: false,
     fixedTime: null,
   };
@@ -55,6 +57,10 @@ function parseArgs(argv = process.argv.slice(2)) {
         options.stateDir = path.resolve(valueFor(argv[i], i));
         i++;
         break;
+      case '--expected-state-dir':
+        options.expectedStateDir = valueFor(argv[i], i);
+        i++;
+        break;
       case '--fixed-time':
         options.fixedTime = valueFor(argv[i], i);
         if (!Number.isFinite(Date.parse(options.fixedTime))) {
@@ -69,9 +75,33 @@ function parseArgs(argv = process.argv.slice(2)) {
         throw new Error(`Unknown argument: ${argv[i]}`);
     }
   }
+  if (!options.stateDir) {
+    throw new Error('--state-dir is required so capture cannot target live Minions state');
+  }
+  if (!options.expectedStateDir) options.expectedStateDir = options.stateDir;
   return options;
 }
 
+function assertOwnedStateDir(stateDir) {
+  if (pathsOverlap(stateDir, ROOT)) {
+    throw new Error(`Demo state directory must not overlap the source checkout: ${stateDir}`);
+  }
+  const marker = path.join(stateDir, '.minions-test-fixture');
+  if (!fs.existsSync(marker) || !fs.statSync(marker).isFile() || fs.readFileSync(marker, 'utf8') !== '') {
+    throw new Error(`Demo state directory is not marker-owned: ${stateDir}`);
+  }
+}
+
+async function assertDashboardUsesStateDir(baseUrl, expectedStateDir, fetchImpl = globalThis.fetch) {
+  const response = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/api/health`);
+  if (!response.ok) throw new Error(`Dashboard health check failed: HTTP ${response.status}`);
+  const health = await response.json();
+  if (!health.minionsDir) throw new Error('Dashboard health response did not identify its Minions state directory');
+  if (canonicalPath(health.minionsDir) !== canonicalPath(expectedStateDir)) {
+    throw new Error(`Refusing capture: dashboard uses ${health.minionsDir}, not isolated state ${expectedStateDir}`);
+  }
+}
+
 function runSeed({ clean = false, stateDir = null } = {}) {
   const args = [path.join(ROOT, 'test', 'seed-demo-data.js')];
   if (clean) args.push('--clean');
@@ -84,9 +114,14 @@ async function capture(options = {}) {
     baseUrl = DEFAULT_BASE_URL,
     outputDir = DEMO_DIR,
     stateDir = null,
+    expectedStateDir = stateDir,
     skipSeed = false,
     fixedTime = null,
+    fetchImpl = globalThis.fetch,
   } = options;
+  if (!stateDir) throw new Error('stateDir is required so capture cannot target live Minions state');
+  assertOwnedStateDir(stateDir);
+  await assertDashboardUsesStateDir(baseUrl, expectedStateDir, fetchImpl);
   fs.mkdirSync(outputDir, { recursive: true });
 
   let browser;
@@ -287,4 +322,6 @@ module.exports = {
   SCREENSHOT_FILES,
   parseArgs,
   capture,
+  assertOwnedStateDir,
+  assertDashboardUsesStateDir,
 };

package/docs/ci-runner-canary.md

@@ -0,0 +1,123 @@
+# CI runner canary
+
+`.github/workflows/ci-runner-canary.yml` answers one question every hour: **is
+this repository's CI actually able to run anything?**
+
+## The failure it exists for
+
+On 2026-07-30 both self-hosted Windows runners on `yemi33/minions` went
+offline. Every automated workflow on that fork ultimately targets that one host
+label, so the effects cascaded:
+
+- `Publish to npm` could never allocate a runner for its `validate` job. Its
+  run-level concurrency group (`cancel-in-progress: false`) therefore never
+  released, and ~59 runs piled up at `status=pending` with **zero jobs
+  created**. Bringing the runners back online did **not** drain them — they are
+  blocked at RUN level, before a job exists.
+- `PR Tests` sat `queued` for days.
+- The `Rerun stale PR CI` watchdog is itself self-hosted, so the watchdog was
+  dark too.
+
+The critical property: **none of that ever becomes a failure.** A run with no
+job never reaches a `failure` or `startup_failure` conclusion, and GitHub's 24h
+queue timeout cannot fire on a run that never created a job to time out. The
+hourly CI-health check lists only `--status failure` and `--status
+startup_failure`, so it reported "all green" for ~2.5 days while CI was
+completely dark and npm releases were blocked.
+
+A canary that shares any part of that failure domain reports nothing. This one
+is built not to.
+
+## What makes it survivable
+
+| Property | Why |
+| --- | --- |
+| `runs-on: windows-latest` | A GitHub-**hosted** runner, so a self-hosted outage cannot stall it. Not `ubuntu-latest`: the yemi33 account cannot provision Linux hosted runners (dual-CI topology). `windows-latest` is proven on both forks — `publish.yml`'s `publish` job already uses it. |
+| No `needs:` | Waiting on another job re-imports that job's ability to stall. |
+| Its own concurrency group, `cancel-in-progress: true` | Sharing `npm-publish-*` or `windows-test-heavy-*` would make the canary queue behind the stall it reports. Cancelling in progress means a canary can never itself become the stalled run. |
+| Nothing hardcoded to one fork | `.github/workflows/` is excluded from the backport, so the two forks sync this file by hand; every fork-specific literal is a drift surface. The default branch is read from the API (`master` on yemi33, `main` on opg) and the self-hosted label sets are derived from the workflows actually checked in. |
+
+`test/unit/ci-runner-canary.test.js` pins each of these, because every one of
+them is a way the canary could be quietly neutered back into silence.
+
+### Editing the `run:` script
+
+GitHub substitutes `${{ … }}` expressions **anywhere** in a workflow file, a
+`run:` block scalar included, before the script is handed to the shell. This
+workflow parses other workflows' `runs-on:` values, so it has to *talk about*
+that syntax — and therefore must never spell the opening delimiter out. It
+assembles it at runtime instead (`$exprOpen = '$' + '{{'`).
+
+Getting this wrong is silent in both directions:
+
+- A **malformed** expression is rejected at parse time. The run reports
+  `conclusion=failure` with **zero jobs and no check run**, so `gh pr checks`
+  shows all-green and nothing observes that the workflow never ran. That is not
+  hypothetical — it is how [run 30754622581][rejected] shipped through review.
+- A **well-formed** one is substituted, silently rewriting the script.
+
+The unit test covers both: it parses every expression in every workflow the way
+GitHub does, and it fails if the canary's `run:` block contains the literal
+delimiter at all.
+
+[rejected]: https://github.com/opg-microsoft/minions/actions/runs/30754622581
+
+## What it checks
+
+**(a) Self-hosted fleet health.** Applicability is derived from the workflows
+on disk, not from which runners happen to be registered. Registration is the
+wrong source: if the fleet de-registers itself during a host rebuild, the repo
+has zero runners carrying the label, and "no runners registered" would read as
+"not applicable" at the exact moment every self-hosted job hangs forever. For
+each `runs-on` label set containing `self-hosted`, the canary fails when no
+registered runner carrying that whole set is `online`. Label matching is
+case-insensitive, because workflows ask for `windows` while runners register
+`Windows`.
+
+**(b) Stalled runs on the default branch.** Any run `pending` or `queued`
+longer than the threshold fails the canary. This is the load-bearing check: a
+dark fleet always surfaces here, and it needs only `actions: read`.
+
+Both emit an actionable job summary — which runners are offline, and the oldest
+stalled run's id, workflow name, age, and URL.
+
+## Condition (a) is off by default
+
+`GITHUB_TOKEN` **cannot** list self-hosted runners. That endpoint needs
+`administration:read`, and `administration` is not a grantable key in a
+workflow `permissions:` block; the request comes back `404`, which is how
+GitHub masks an unauthorized read here.
+
+So condition (a) reports itself as **UNAVAILABLE** — in the log, as a
+`::warning` annotation, in the job summary, and in the closing verdict. It is
+never treated as a pass. To enable it, add a repository secret
+`RUNNER_STATUS_TOKEN` holding a PAT with repo `administration:read`; the
+workflow prefers it over `GITHUB_TOKEN` automatically.
+
+Until then, condition (b) still catches the outage, because a fleet that cannot
+allocate runners always produces runs stuck pending or queued.
+
+## Tuning and operating
+
+- Threshold: `stall_hours` (`workflow_dispatch` input), default **2**.
+- Cadence: hourly, at `:23`.
+- Manual run: `gh workflow run "CI runner canary" --repo <owner>/<repo>`, or
+  with an override, `-f stall_hours=6`.
+
+### When it goes red
+
+1. **Fleet offline** — the failing repo's runners need an operator on the host;
+   no code change can bring them back. Restart the Actions runner service.
+2. **Stalled runs** — check whether a run-level `concurrency` group is holding
+   the queue. Runs blocked at RUN level do **not** drain on their own once
+   runners return; cancel the backlog explicitly:
+
+   ```bash
+   gh run list --repo <owner>/<repo> --branch <default> --status pending \
+     --limit 100 --json databaseId --jq '.[].databaseId' |
+     xargs -n1 gh run cancel --repo <owner>/<repo>
+   ```
+
+Related: [default-branch-ci.md](default-branch-ci.md) covers the post-merge
+gate, which answers "is the merged tree green?" — a different question from
+"can CI run at all?".

package/docs/claude-md-propagation.md

@@ -3,7 +3,7 @@
 **Work item:** W-mrdon0pe000l045a
 **Config flag:** `engine.propagateClaudeMdForNonClaudeRuntimes` (default `true`)
 **Per-project override:** `project.propagateClaudeMdForNonClaudeRuntimes`
-**Module:** `engine/claude-md-context.js` · **Injection:** `engine/playbook.js`
+**Module:** `engine/agents/claude-md-context.js` · **Injection:** `engine/agents/playbook.js`
 
 ## Problem
 
@@ -84,7 +84,7 @@ does not meaningfully slow dispatch even in a monorepo.
 
 ## Injection & byte cap
 
-`engine/playbook.js#renderPlaybook` adds `CLAUDE.md` propagation as a context
+`engine/agents/playbook.js#renderPlaybook` adds `CLAUDE.md` propagation as a context
 layer alongside the existing `pinned.md` → `notes.md` →
 `knowledge/agents/<agentId>.md` layers: