@yemi33/minions 0.1.2177 → 0.1.2178

package/dashboard.js

@@ -182,6 +182,27 @@ function mutateDashboardConfig(mutator) {
   }, { defaultValue: { projects: [], agents: {}, engine: {} }, skipWriteIfUnchanged: true });
 }
 
+// P-f3c9d0e7 — shared body for the four convenience pause/resume endpoints
+// (`/api/engine/polling/{pause,resume}` and `/api/engine/auto-fix/{pause,resume}`).
+// Persists `config.engine[key] = paused`, busts the in-memory CONFIG so the
+// dashboard sees the new value immediately, invalidates the status cache so
+// the SPA's next poll picks it up, and replies `{ paused, at: <iso> }` per
+// the plan's wire contract. Idempotent — repeating the same call writes the
+// same value (mutateDashboardConfig short-circuits when unchanged) and
+// returns the same shape.
+function _setEnginePauseFlag(res, key, paused) {
+  mutateDashboardConfig(config => {
+    if (!config.engine || typeof config.engine !== 'object' || Array.isArray(config.engine)) {
+      config.engine = {};
+    }
+    config.engine[key] = paused;
+    return config;
+  });
+  reloadConfig();
+  invalidateStatusCache();
+  return jsonReply(res, 200, { paused, at: new Date().toISOString() });
+}
+
 function mergeSettingsConfigUpdate(current, candidate, body, patch = {}) {
   if (!current || typeof current !== 'object' || Array.isArray(current)) current = {};
   if (body.engine) {
@@ -1907,6 +1928,11 @@ function _buildStatusFastState() {
         && hbAge > ENGINE_HEARTBEAT_STALE_MS
         && tickAge > tickStaleThresholdMs),
       tickInterval: tickInterval,
+      // P-g7a2b4c5 — surface the two operator kill-switches on every status
+      // payload so the cross-page sticky banner can render without a second
+      // round-trip. Both default to false when unset in config.engine.
+      pollingPaused: !!CONFIG?.engine?.pollingPaused,
+      autoFixPaused: !!CONFIG?.engine?.autoFixPaused,
     },
     adoThrottle: ado.getAdoThrottleState(),
     ghThrottle: gh.getGhThrottleState(),
@@ -6700,9 +6726,50 @@ const server = http.createServer(async (req, res) => {
           try {
             const plan = JSON.parse(content);
             const status = plan.status || 'active';
+            // W-mqacrzis0003df4a Bug 2 — fresh staleness from plans/*.md mtime.
+            // plan.planStale lags by an engine tick; stat the source plan here
+            // so the Plans tab does not silently mirror a stale-but-cached false.
+            let freshStale = false;
+            if (!archived && plan.source_plan) {
+              try {
+                const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
+                const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
+                if (recorded && sourceMtime > recorded) freshStale = true;
+              } catch { /* source plan may have been deleted/renamed */ }
+            }
+            // P-e8d49105 — _projects rollup feeds the plan-card multi-badge
+            // path in dashboard/js/render-plans.js. For PRD JSONs, walk
+            // missing_features[].project (order-preserving dedup) and fall
+            // back to plan.project for items that omit it. Single-project
+            // plans collapse to a single-element array, identical to today's
+            // single `p.project` badge.
+            const _projects = [];
+            const _seen = new Set();
+            for (const it of (plan.missing_features || [])) {
+              const proj = (it && it.project) || plan.project || '';
+              if (proj && !_seen.has(proj)) { _seen.add(proj); _projects.push(proj); }
+            }
+            if (_projects.length === 0 && plan.project) _projects.push(plan.project);
+            // P-66b1faec — _perProjectProgress feeds the per-project status
+            // pills in the plan card meta line (dashboard/js/render-plans.js
+            // renderPlanCard). Group missing_features by item.project (with
+            // fallback to plan.project) and count `status === 'done'` per
+            // bucket. Keys are first-seen order so the rendered pill row is
+            // stable. Always emitted on PRD JSON records (possibly empty);
+            // MD drafts omit it since they carry no item-level statuses.
+            const _perProjectProgress = {};
+            for (const it of (plan.missing_features || [])) {
+              const proj = (it && it.project) || plan.project || '';
+              if (!proj) continue;
+              if (!_perProjectProgress[proj]) _perProjectProgress[proj] = { complete: 0, total: 0 };
+              _perProjectProgress[proj].total += 1;
+              if (it && it.status === 'done') _perProjectProgress[proj].complete += 1;
+            }
             return {
               file: f, format: 'prd', archived,
               project: plan.project || '',
+              _projects,
+              _perProjectProgress,
               summary: plan.plan_summary || '',
               status,
               branchStrategy: plan.branch_strategy || 'parallel',
@@ -6717,7 +6784,7 @@ const server = http.createServer(async (req, res) => {
               sourcePlan: plan.source_plan || null,
               archiveReady: plan._archiveReady || false,
               archiveReadyAt: plan._archiveReadyAt || null,
-              planStale: plan.planStale || false,
+              planStale: freshStale || plan.planStale || false,
             };
           } catch { return null; /* JSON parse fallback */ }
         } else {
@@ -6726,9 +6793,19 @@ const server = http.createServer(async (req, res) => {
           const authorMatch = content.match(/\*\*Author:\*\*\s*(.+)/m);
           const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/m);
           const versionMatch = f.match(/-v(\d+)/);
+          // P-e8d49105 — for MD drafts, the cross-repo marker / **Projects:**
+          // line is the source of truth (parsed by shared.extractPlanTargetProjects).
+          // If neither is present, fall back to the singular **Project:** header
+          // so single-project drafts render the same badge as today.
+          const declaredProject = projectMatch ? projectMatch[1].trim() : '';
+          const targetProjects = shared.extractPlanTargetProjects(content);
+          const _projects = targetProjects.length > 0
+            ? targetProjects
+            : (declaredProject ? [declaredProject] : []);
           return {
             file: f, format: 'draft', archived,
-            project: projectMatch ? projectMatch[1].trim() : '',
+            project: declaredProject,
+            _projects,
             summary: titleMatch ? titleMatch[1].trim() : f.replace('.md', ''),
             status: archived ? 'completed' : completedPrdFiles.has(f) ? 'converted' : 'draft',
             branchStrategy: '',
@@ -6842,6 +6919,22 @@ const server = http.createServer(async (req, res) => {
         return data;
       }, { defaultValue: {} });
 
+      // W-mqacrzis0003df4a — Fresh source-plan staleness check. Approve is the
+      // last gate before materialization, and the diff-aware regen block below
+      // gates on `wasStale`. The persisted `data.planStale` flag lags by an
+      // engine tick (~10s); without this fresh stat a fast user can Approve
+      // within the tick window, `wasStale` stays false, the diff-aware regen
+      // is silently skipped, and items materialize from the OLD PRD. Mirrors
+      // the staleness logic in engine/queries.js#getPrdInfo + the /api/plans
+      // handler above so all three readers agree.
+      if (!wasStale && plan && plan.source_plan && plan.sourcePlanModifiedAt) {
+        try {
+          const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
+          const recorded = new Date(plan.sourcePlanModifiedAt).getTime();
+          if (recorded && sourceMtime > recorded) wasStale = true;
+        } catch { /* source plan may have been deleted/renamed — fall through with wasStale=false */ }
+      }
+
       // Resume paused work items across all projects
       let resumed = 0;
       const resumedItemIds = [];
@@ -7193,7 +7286,9 @@ const server = http.createServer(async (req, res) => {
 
       let archivedSource = null;
       let plan = {};
-      let archiveWarnings = [];
+      const archiveWarnings = [];
+      let archivedPrd = null;
+      const archivedPrds = [];
       if (isPrd) {
         const result = _archivePrdPostProcess({
           planFile: body.file,
@@ -7202,8 +7297,75 @@ const server = http.createServer(async (req, res) => {
           plansDir: PLANS_DIR,
         });
         archivedSource = result.archivedSource;
-        archiveWarnings = result.archiveWarnings;
+        archiveWarnings.push(...result.archiveWarnings);
         plan = result.plan;
+      } else {
+        // W-mqa27r9b0004c055 — symmetric cascade: archiving a .md must also
+        // archive any PRD whose `source_plan` points back at it. Without this,
+        // the dashboard still renders the PRD as a status-completed plan card
+        // forever (real incident: killswitches-and-granular-controls.md →
+        // minions-opg-2026-06-10-2.json). The per-PRD status-flip / sidecar /
+        // source-plan-move steps are delegated to _archivePrdPostProcess so
+        // both branches share the per-concern try/catch granularity Dallas
+        // shipped for the PRD branch in W-mqa13ulk0002def5 (PR #3222) — the
+        // helper's source-plan move is a safe no-op here because the outer
+        // handler already renamed body.file into plans/archive/.
+        let prdFiles = [];
+        try {
+          prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json'));
+        } catch (e) {
+          // ENOENT on prd/ is expected for projects without a PRD dir yet —
+          // don't surface as a user-visible warning. Other errors (EACCES,
+          // EIO) get logged + warned.
+          if (e.code !== 'ENOENT') {
+            const warning = `Archive could not enumerate ${PRD_DIR}: ${e.message}`;
+            archiveWarnings.push(warning);
+            console.warn(warning);
+          }
+        }
+        for (const prdFile of prdFiles) {
+          const prdLivePath = path.join(PRD_DIR, prdFile);
+          let prd = null;
+          try {
+            prd = safeJsonObj(prdLivePath);
+          } catch (e) {
+            const warning = `Archive could not read PRD ${prdFile}: ${e.message}`;
+            archiveWarnings.push(warning);
+            console.warn(warning);
+            continue;
+          }
+          if (!prd || prd.source_plan !== body.file) continue;
+
+          const prdArchiveDir = path.join(PRD_DIR, 'archive');
+          try {
+            if (!fs.existsSync(prdArchiveDir)) fs.mkdirSync(prdArchiveDir, { recursive: true });
+          } catch (e) {
+            const warning = `Archive could not create PRD archive dir for ${prdFile}: ${e.message}`;
+            archiveWarnings.push(warning);
+            console.warn(warning);
+            continue;
+          }
+          const prdArchivePath = path.join(prdArchiveDir, prdFile);
+          try {
+            fs.renameSync(prdLivePath, prdArchivePath);
+          } catch (e) {
+            const warning = `Archive could not move PRD ${prdFile}: ${e.message}`;
+            archiveWarnings.push(warning);
+            console.warn(warning);
+            continue;
+          }
+          // Delegate status-flip + sidecar cleanup + (no-op) source-plan move
+          // to the shared helper so both branches stay in lockstep.
+          const cascadeResult = _archivePrdPostProcess({
+            planFile: prdFile,
+            archivePath: prdArchivePath,
+            planPath: prdLivePath,
+            plansDir: PLANS_DIR,
+          });
+          archiveWarnings.push(...cascadeResult.archiveWarnings);
+          archivedPrds.push(prdFile);
+        }
+        if (archivedPrds.length > 0) archivedPrd = archivedPrds[0];
       }
 
       // Cancel pending work items linked to this plan so the engine stops
@@ -7233,6 +7395,8 @@ const server = http.createServer(async (req, res) => {
       invalidateStatusCache();
       invalidatePlansCache();
       const payload = { ok: true, archived: body.file, archivedSource, cancelledItems };
+      if (archivedPrd) payload.archivedPrd = archivedPrd;
+      if (archivedPrds.length > 1) payload.archivedPrds = archivedPrds;
       if (archiveWarnings.length > 0) payload.warnings = archiveWarnings;
       return jsonReply(res, 200, payload);
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
@@ -9501,6 +9665,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // larger models); max 1h (matches CC_CALL_TIMEOUT_MS so the watchdog
           // never outlives the outer abort).
           ccTurnTimeoutMs: [10000, 3600000],
+          // W-mq9acoo800177bcb — bounded-concurrency for pre-dispatch validator.
+          // 1 floor (sequential fallback) and 20 ceiling (above this the LLM
+          // provider's per-second rate limits dominate; throughput gains taper).
+          preDispatchEvalConcurrency: [1, 20],
         };
         for (const [key, [min, max]] of Object.entries(numericFields)) {
           if (e[key] !== undefined) {
@@ -9624,6 +9792,17 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           else if (valid.includes(e.copilotStreamMode)) _setEngineConfig('copilotStreamMode', e.copilotStreamMode);
           else _clamped.push(`copilotStreamMode: "${e.copilotStreamMode}" not in [on, off] (kept previous value)`);
         }
+        // P-mcp-storm — MCP server names to disable for autonomous Copilot agents
+        // (--disable-mcp-server). Accept an array OR a comma/whitespace string;
+        // normalize to a deduped array of trimmed names. Empty clears (inherit all).
+        if (e.copilotAgentDisabledMcpServers !== undefined) {
+          const src = Array.isArray(e.copilotAgentDisabledMcpServers)
+            ? e.copilotAgentDisabledMcpServers
+            : String(e.copilotAgentDisabledMcpServers || '').split(/[\s,]+/);
+          const names = [...new Set(src.map(s => String(s == null ? '' : s).trim()).filter(Boolean))];
+          if (names.length) _setEngineConfig('copilotAgentDisabledMcpServers', names);
+          else _deleteEngineConfig('copilotAgentDisabledMcpServers');
+        }
         // W-mpmwxkrw000872ec — fontSize allowlist. Clamps invalid values
         // (rather than silently failing) so the dashboard bootstrap never
         // ends up with an unknown data-font-size attribute.
@@ -11746,6 +11925,37 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return jsonReply(res, 200, { ok: true, cleared: cause, prId });
     }},
 
+    // ─── P-f3c9d0e7: convenience pause/resume endpoints ─────────────────────
+    // Single-call wrappers over `POST /api/settings { engine: { <flag>: bool } }`
+    // for the two operator kill-switches:
+    //   - engine.pollingPaused (P-a1f3c2d4) — pauses all PR polling
+    //   - engine.autoFixPaused (P-b2e5d8c7) — pauses auto-fix dispatch
+    //
+    // These exist so the dashboard "Emergency Stop" buttons and any future
+    // `minions pause` / `minions autopause` CLI commands are one-line
+    // implementations (no JSON body construction needed).
+    //
+    // Engine pickup contract: engine.js calls reloadConfig() each tick and
+    // reads `config.engine.<flag> === true` at every gate site, so the next
+    // tick observes the change. Setting the flag to `false` on resume is
+    // enough — the engine has its own log-throttle reset
+    // (`_resetPollingPausedLogState`, `_resetAutoFixPausedLogState`) that
+    // fires automatically when the gate reads `!paused`. The engine and
+    // dashboard run in separate processes, so the dashboard can't (and
+    // doesn't need to) scrub engine-process module state directly.
+    { method: 'POST', path: '/api/engine/polling/pause', desc: 'Pause all PR polling — sets engine.pollingPaused=true (P-f3c9d0e7 convenience over POST /api/settings)', handler: async (req, res) => {
+      return _setEnginePauseFlag(res, 'pollingPaused', true);
+    }},
+    { method: 'POST', path: '/api/engine/polling/resume', desc: 'Resume PR polling — sets engine.pollingPaused=false', handler: async (req, res) => {
+      return _setEnginePauseFlag(res, 'pollingPaused', false);
+    }},
+    { method: 'POST', path: '/api/engine/auto-fix/pause', desc: 'Pause auto-fix dispatch — sets engine.autoFixPaused=true', handler: async (req, res) => {
+      return _setEnginePauseFlag(res, 'autoFixPaused', true);
+    }},
+    { method: 'POST', path: '/api/engine/auto-fix/resume', desc: 'Resume auto-fix dispatch — sets engine.autoFixPaused=false', handler: async (req, res) => {
+      return _setEnginePauseFlag(res, 'autoFixPaused', false);
+    }},
+
     { method: 'POST', path: '/api/plans/create', desc: 'Create a plan from user-provided content', params: 'title, content, project?', handler: async (req, res) => {
       const body = await readBody(req);
       const { title, content, project: projectName, meetingId } = body;
@@ -11758,6 +11968,29 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         return jsonReply(res, 400, { error: 'Plan content must start with a markdown heading (#), bold text (**), or a list item' });
       }
 
+      // P-2e9b54d1: `project` may be a string (today's behavior) OR an array
+      // of project names (cross-repo plan). Normalize to a deduped, trimmed
+      // string[]. Empty values are dropped; ≥2 entries triggers the cross-
+      // repo plan shape (no singular `**Project:**` header, plural
+      // `**Projects:**` line + `<!-- minions:targetProjects=... -->` marker).
+      const rawProjects = Array.isArray(body.project)
+        ? body.project
+        : (body.project ? [body.project] : []);
+      const projectNames = [];
+      for (const raw of rawProjects) {
+        const name = String(raw || '').trim();
+        if (name && !projectNames.includes(name)) projectNames.push(name);
+      }
+      if (projectNames.length > 0) {
+        reloadConfig();
+        const projects = shared.getProjects(CONFIG);
+        for (const name of projectNames) {
+          if (!findProjectByName(projects, name)) {
+            return jsonReply(res, 400, { error: formatUnknownProjectError(name, projects) });
+          }
+        }
+      }
+
       const plansDir = path.join(MINIONS_DIR, 'plans');
       if (!fs.existsSync(plansDir)) fs.mkdirSync(plansDir, { recursive: true });
       const slug = shared.slugify(title);
@@ -11765,8 +11998,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const filename = `${slug}-${date}.md`;
       const filePath = shared.uniquePath(path.join(plansDir, filename));
 
+      const projectLines = projectNames.length >= 2
+        ? `**Projects:** ${projectNames.join(', ')}\n` +
+          `<!-- minions:targetProjects=${projectNames.join(',')} -->\n`
+        : (projectNames.length === 1 ? `**Project:** ${projectNames[0]}\n` : '');
       const header = `# ${title}\n\n` +
-        (projectName ? `**Project:** ${projectName}\n` : '') +
+        projectLines +
         (meetingId ? `**Source Meeting:** ${meetingId}\n` : '') +
         `**Created:** ${date}\n**By:** human teammate\n\n---\n\n`;
       safeWrite(filePath, header + content);

package/docs/README.md

@@ -7,12 +7,13 @@ A navigable index of every Markdown file under `docs/`. Entries are grouped by a
 Hands-on stories and distribution guides for people running or evaluating Minions.
 
 - [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
-- [distribution.md](distribution.md) — How Minions is published as the `@yemi33/minions` npm package and what the two-repo (origin / personal) sync strips.
+- [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
 
 ## Contributor-facing
 
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
+- [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.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
 - [constants.md](constants.md) — Cross-cutting status / type / condition constants (`WI_STATUS`, `WORK_TYPE`, `PR_STATUS`, `WATCH_CONDITION`, …) and the no-magic-strings invariant.
@@ -21,14 +22,17 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [cooldown-merge-semantics.md](cooldown-merge-semantics.md) — Scoping deliverable defining merge semantics for `saveCooldowns` (longer-of TTL merge, key-level upserts, gitignored on-disk format).
 - [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).
 - [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.
+- [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-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target (accepted; implementation tracked in CHANGELOG.md Phases 0–9).
 - [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.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [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.
+- [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `worktreeMode: '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.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [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.
+- [project-skills.md](project-skills.md) — Project-local skill discovery (`.claude/skills/`, `.claude/commands/`, `CLAUDE.md` / `.github/copilot-instructions.md` slash-command mentions): how dispatched agents see and steer toward purpose-built tooling the project ships, plus the intent-vocabulary contract.
 - [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.
@@ -38,8 +42,10 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [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) — Per-agent memory layer (`knowledge/agents/<id>.md`) and the consolidation/routing rules that populate it from `notes/inbox/`.
+- [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.
 - [watches.md](watches.md) — Persistent monitoring jobs (`engine/watches.json`): target-type registry, conditions, follow-up actions, and the `watches.d/` plugin 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.
 
 ## Operations
 
@@ -50,6 +56,7 @@ Operational runbooks for engine operators and fleet maintainers.
 - [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`.
 - [onboarding.md](onboarding.md) — First-30-minutes walkthrough for a new operator: install, init, dispatch a first work item, watch it land.
+- [preflight.md](preflight.md) — `minions doctor` and the lighter per-CLI `minions preflight` checks: 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/auto-discovery.md

@@ -57,6 +57,46 @@ 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`.
+
+**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, and `discoverFromPrs` forces `pollEnabled=false` for every project so every per-PR auto-dispatch gate (`autoReviewPrs` / `autoFixBuilds` / `autoFixConflicts` / `autoFixReviewFeedback` / `autoFixHumanComments`) becomes inert. Reconciliation (the recovery sweep that follows section 2.7) is intentionally not gated. 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, 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.
+
+**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`:
+
+| Flag | Default | Phase | Composes with `pollingPaused`? |
+|------|---------|-------|--------------------------------|
+| `adoPrStatusPollEnabled` | `true` | Section 2.6 (ADO `pollPrStatus`) | Yes — status polls honor the master killswitch |
+| `adoPrCommentsPollEnabled` | `true` | Section 2.7 (ADO `pollPrHumanComments`) | Yes |
+| `adoPrReconcileEnabled` | `true` | Section 2.7 tail (ADO `reconcilePrs`) | No — reconcile is a recovery sweep |
+| `ghPrStatusPollEnabled` | `true` | Section 2.6 (GitHub `ghPollPrStatus`) | Yes |
+| `ghPrCommentsPollEnabled` | `true` | Section 2.7 (GitHub `ghPollPrHumanComments`) | Yes |
+| `ghPrReconcileEnabled` | `true` | Section 2.7 tail (GitHub `ghReconcilePrs`) | No — reconcile is a recovery sweep |
+| `processPendingRebasesEnabled` | `true` | Section 2.6 tail (`processPendingRebases`) | No — rebase processor has no legacy macro |
+
+Resolution order (`shared.resolvePollFlag(engineCfg, granularKey, legacyMacroKey)`): (1) granular flag explicitly set → wins; (2) legacy macro is `false` → propagates `false` to all three axes of that provider (including reconcile); (3) otherwise → `ENGINE_DEFAULTS[granularKey]` (`true`).
+
+**Breaking change vs. legacy semantics:** Before P-c4d8e1a3, the legacy `adoPollEnabled: false` / `ghPollEnabled: false` silenced only status + comments polls, leaving reconcile running. The new `resolvePollFlag` contract propagates the legacy `false` to reconcile too. Operators who want the old behavior (status + comments OFF, reconcile ON) must now set `adoPrReconcileEnabled: true` / `ghPrReconcileEnabled: true` explicitly alongside the legacy macro. Default-config installs (no overrides) and installs that flip only the new granular flags are unaffected.
+
+Flip via Dashboard → Settings → Polling → "Granular per-poller controls" collapsible, or set the keys directly in `config.engine`.
+
+**Granular work-discovery flags (`P-d6f0a2b5`).** Each phase inside `engine.discoverWork()` is independently gateable, so operators can silence a single discovery source without disabling the other phases or touching the per-project `project.workSources.*.enabled` toggles. The two layers compose: a `false` at either the global flag or the per-project `workSources.*.enabled` level skips the matching call.
+
+| Flag | Default | Phase inside `discoverWork()` |
+|------|---------|--------------------------------|
+| `prDiscoveryEnabled` | `true` | Per-project `discoverFromPrs(config, project)` — PR-derived fix / review / build-test work |
+| `workItemsDiscoveryEnabled` | `true` | Per-project `discoverFromWorkItems(config, project)` — project-local `work-items.json` scan |
+| `centralWorkDiscoveryEnabled` | `true` | `discoverCentralWorkItems(config)` — top-level project-agnostic `work-items.json` scan |
+| `scheduledWorkDiscoveryEnabled` | `true` | `discoverScheduledWork(config)` — cron-style scheduled tasks + scheduled meetings |
+| `planMaterializationEnabled` | `true` | `reconcilePrdStatuses(config)` + `materializePlansAsWorkItems(config)` (paired side-effect passes) |
+
+Resolution is intentionally simpler than the granular per-poller flags above: each call site uses the inline check `if (config.engine?.<flag> !== false) { ... }`, so a missing or `true` value runs the phase and an explicit `false` skips it. There is no legacy macro to fall back to, and `shared.resolvePollFlag` is **not** used here. Default-config installs (no overrides) behave identically to before this knob existed.
+
+Composition with per-project gates: setting `workItemsDiscoveryEnabled: false` skips `discoverFromWorkItems` even for projects whose own `workSources.workItems.enabled` is `true`; setting it back to `true` restores the per-project gate that `discoverFromWorkItems` already honors internally. Same pattern for `prDiscoveryEnabled` vs. `workSources.pullRequests.enabled`. `scheduledWorkDiscoveryEnabled: false` stops cron-style scheduled tasks from firing without touching the scheduler config; `planMaterializationEnabled: false` suppresses the `reconcilePrdStatuses` + `materializePlansAsWorkItems` pair atomically (useful during a long migration that must not auto-create work items).
+
+Flip via Dashboard → Settings → Polling → "Granular work-discovery controls (P-d6f0a2b5)" collapsible, or set the keys directly in `config.engine`.
+
 ### Source 2: PRD Gap Analysis (via `materializePlansAsWorkItems`)
 
 PRD items flow through `materializePlansAsWorkItems()`, which scans `~/.minions/prd/*.json` for PRD files with `missing` / `updated` / `planned` items and creates work items in the target project's queue.