@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{shared.js → core/shared.js}

@@ -1,5 +1,5 @@
 /**
- * engine/shared.js — Shared utilities for Minions engine, dashboard, and LLM modules.
+ * engine/core/shared.js — Shared utilities for Minions engine, dashboard, and LLM modules.
  * Extracted from engine.js and dashboard.js to eliminate duplication.
  */
 
@@ -11,11 +11,29 @@ const crypto = require('crypto');
 // enumeration, cwd-holder detection) live in process-utils.js
 // (P-mrb8yg9x001k1401-b). Re-exported below via `...processUtils` so no
 // caller of require('./shared') needs to change.
-const processUtils = require('./process-utils');
+const processUtils = require('../processes/process-utils');
 
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
 const DEFAULT_MINIONS_HOME = path.join(os.homedir(), '.minions');
-const ROOT_POINTER_PATH = path.join(os.homedir(), '.minions-root');
+
+function _resolveRootPointerPath() {
+  const processRoot = process.env.MINIONS_TEST_PROCESS_ROOT;
+  const requested = process.env.MINIONS_TEST_ROOT_POINTER_PATH;
+  if (processRoot && requested) {
+    try {
+      const root = path.resolve(processRoot);
+      const target = path.resolve(requested);
+      const relative = path.relative(root, target);
+      if (fs.existsSync(path.join(root, '.minions-test-process'))
+          && relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+        return target;
+      }
+    } catch { /* fall through to the operator home */ }
+  }
+  return path.join(os.homedir(), '.minions-root');
+}
+
+const ROOT_POINTER_PATH = _resolveRootPointerPath();
 
 function isInstalledRoot(dir) {
   if (!dir) return false;
@@ -40,6 +58,11 @@ function saveMinionsRootPointer(root) {
 }
 
 function resolveMinionsHome(forInit = false, options = {}) {
+  const testHome = process.env.MINIONS_TEST_DIR
+    ? path.resolve(process.env.MINIONS_TEST_DIR)
+    : null;
+  if (testHome) return testHome;
+
   const envHome = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : null;
   if (envHome) return envHome;
 
@@ -63,6 +86,40 @@ const MINIONS_DIR = process.env.MINIONS_TEST_DIR || resolveMinionsHome(false, {
   preferSourceCheckout: true,
 });
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
+
+// W-ms6wdokc00051a14 — Definition directories (playbooks/, prompts/, dashboard/)
+// belong to the runtime root. The ONE exception is the process-isolation
+// baseline runtime root created by test/process-isolation.js: it is seeded with
+// runtime-state directories only, so it opts into a package-root fallback by
+// carrying this marker. The fallback is deliberately scoped to that single
+// directory — a test that swaps in its own MINIONS_TEST_DIR sandbox must stay
+// sandboxed, or "this definition file is absent" assertions would silently read
+// the real repository copy instead.
+const TEST_PROCESS_RUNTIME_MARKER = '.minions-test-process-runtime';
+
+function _definitionFallbackRootFor(runtimeRoot) {
+  const processRoot = process.env.MINIONS_TEST_PROCESS_ROOT;
+  if (!processRoot) return null;
+  try {
+    if (!fs.existsSync(path.join(path.resolve(processRoot), '.minions-test-process'))) return null;
+    if (!fs.existsSync(path.join(runtimeRoot, TEST_PROCESS_RUNTIME_MARKER))) return null;
+  } catch { return null; }
+  return PACKAGE_ROOT;
+}
+
+function resolveDefinitionDir(name) {
+  if (!/^[A-Za-z0-9._-]+$/.test(String(name || ''))) {
+    throw new Error(`Invalid definition directory: ${name}`);
+  }
+  const runtimeDir = path.join(MINIONS_DIR, name);
+  if (fs.existsSync(runtimeDir)) return runtimeDir;
+  const fallbackRoot = _definitionFallbackRootFor(MINIONS_DIR);
+  if (fallbackRoot) {
+    const packageDir = path.join(fallbackRoot, name);
+    if (fs.existsSync(packageDir)) return packageDir;
+  }
+  return runtimeDir;
+}
 // W-mr2c4i8m0004da94: Node's built-in `--diagnostic-dir` target for the
 // engine.js process's crash-diagnostics report (see
 // getEngineCrashDiagnosticsEnv / pruneCrashDiagnosticsReports below and
@@ -150,22 +207,36 @@ function writeDashboardPortFile({ port, pid, minionsHome } = {}) {
     boundAt: new Date().toISOString(),
   };
   try {
-    fs.mkdirSync(path.dirname(fp), { recursive: true });
-    const tmp = fp + '.tmp';
-    fs.writeFileSync(tmp, JSON.stringify(payload));
-    fs.renameSync(tmp, fp);
+    withFileLock(`${fp}.lock`, () => {
+      fs.mkdirSync(path.dirname(fp), { recursive: true });
+      const tmp = fp + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(payload));
+      fs.renameSync(tmp, fp);
+    });
     return { ok: true, path: fp };
   } catch (err) {
     return { ok: false, error: err };
   }
 }
 
-/** Delete the runtime dashboard-port.json beacon. Called on graceful
- *  dashboard shutdown so the next CLI status check doesn't probe a stale
- *  port. Best-effort. */
-function clearDashboardPortFile(minionsHome) {
+/** Delete the runtime dashboard-port.json beacon. An expected PID makes stale
+ * dashboard shutdowns preserve a newer process's beacon. Best-effort. */
+function clearDashboardPortFile(minionsHome, { expectedPid = null } = {}) {
   const fp = _dashboardPortPath(minionsHome);
-  try { fs.unlinkSync(fp); return { ok: true }; } catch { return { ok: false }; }
+  try {
+    return withFileLock(`${fp}.lock`, () => {
+      if (Number.isInteger(expectedPid)) {
+        const current = readDashboardPortFile(minionsHome);
+        if (!current || current.pid !== expectedPid) {
+          return { ok: false, reason: 'owner-changed' };
+        }
+      }
+      try { fs.unlinkSync(fp); return { ok: true }; }
+      catch { return { ok: false, reason: 'missing' }; }
+    });
+  } catch (error) {
+    return { ok: false, error };
+  }
 }
 
 /**
@@ -244,7 +315,7 @@ function nodeSqliteRemediationLine(version = process.versions.node) {
 }
 
 // ── F6 (P-f6commentedit): Comment-edit dedup helpers ────────────────────────
-// Shared by engine/github.js + engine/ado.js pollPrHumanComments so a comment
+// Shared by engine/providers/github.js + engine/ado/index.js pollPrHumanComments so a comment
 // EDITED after first observation triggers a single re-dispatch (and only one).
 // MANDATORY TZ NORMALIZATION: GH `updated_at` is always UTC (Z-suffix), but
 // ADO `lastUpdatedDate` is inconsistent — sometimes `+00:00`, sometimes naive
@@ -465,7 +536,7 @@ function log(level, msg, meta = {}) {
   // Capture the SQL state.db path too — same write-time semantics so a
   // deferred buffer flush after the test ends still routes the entry to
   // the test's state.db (not the production one). Path resolution mirrors
-  // engine/db.js but inlined to avoid the require cycle that loading the
+  // engine/db/index.js but inlined to avoid the require cycle that loading the
   // db module here would create on module init.
   Object.defineProperty(entry, '_dbPath', {
     value: _currentLogDbPath(),
@@ -496,7 +567,7 @@ function _currentLogDbPath() {
   if (process.env.MINIONS_TEST_DIR) {
     return path.join(path.resolve(process.env.MINIONS_TEST_DIR), 'engine', 'state.db');
   }
-  const root = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : path.resolve(__dirname, '..');
+  const root = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : PACKAGE_ROOT;
   return path.join(root, 'engine', 'state.db');
 }
 
@@ -632,7 +703,7 @@ function _flushLogBuffer() {
   // state.db files stay isolated; logging must never crash the caller, so
   // appendLogsToDbFile already swallows its own errors.
   try {
-    const store = require('./logs-store');
+    const store = require('../observability/logs-store');
     for (const [dbPath, entries] of byDbPath) {
       store.appendLogsToDbFile(dbPath, entries);
     }
@@ -1240,10 +1311,10 @@ function deleteDispatchPromptSidecar(item) {
 
 // ── Stop-intent flag (engine/stop-intent.json) ──────────────────────────────
 //
-// File-presence signal used by the external supervisor (engine/supervisor.js)
+// File-presence signal used by the external supervisor (engine/recovery/supervisor.js)
 // to know when a user explicitly asked Minions to be down (`minions stop`,
 // `minions uninstall`, `engine.js stop`, mid-`minions restart`). Centralized
-// here so dashboard.js, bin/minions.js, engine/cli.js, and supervisor.js all
+// here so dashboard.js, bin/minions.js, engine/operations/cli.js, and supervisor.js all
 // honor the same contract:
 //
 //   - Set by every stop/kill code path BEFORE killing.
@@ -1295,7 +1366,7 @@ const LOCK_STALE_MS = 300000; // 5 minutes — force-remove locks older than thi
 
 // P-8a4d6f29 — single helper for detached-process stdio capture with
 // rotate-on-open. Used by bin/minions.js (engine + dashboard stdio logs) and
-// engine/managed-spawn.js openManagedLog. Centralising replaces the previous
+// engine/processes/managed-spawn.js openManagedLog. Centralising replaces the previous
 // _openStdioLog in bin/minions.js so rotation is uniform across every long-
 // running log Minions writes.
 //
@@ -1364,7 +1435,7 @@ function openAppendLogFd(name, dir, opts) {
 // Windows) without installing anything (e.g. Sysinternals ProcDump).
 //
 // Callers: bin/minions.js (CLI `start`/`restart` spawn) and
-// engine/supervisor.js (respawn-on-death). Both spawn engine.js as a fresh
+// engine/recovery/supervisor.js (respawn-on-death). Both spawn engine.js as a fresh
 // process before any config is loaded into memory, so this reads config.json
 // directly rather than expecting an already-parsed config object — pass the
 // parsed object in if the caller already has it (e.g. from its own
@@ -1392,7 +1463,7 @@ function getEngineCrashDiagnosticsEnv(config, baseEnv) {
 // mtime, mirroring dashboard.js's `_heapSnapshotPrune` retention pattern so
 // a leak-hunt session (or a genuine crash-loop) doesn't fill the disk with
 // reports unbounded. Best-effort: missing dir / unreadable stat / failed
-// unlink are swallowed. Called from engine/cleanup.js#runCleanup (fires
+// unlink are swallowed. Called from engine/orchestration/cleanup.js#runCleanup (fires
 // every ENGINE_DEFAULTS.cleanupEvery ticks, ~10 min at default tick
 // interval) so retention happens automatically without a dedicated sweep.
 function pruneCrashDiagnosticsReports(config) {
@@ -1762,9 +1833,19 @@ function mutateJsonFileLocked(filePath, mutateFn, {
           }
           cleanupClaim();
         } else {
+          // W-ms811bme000n475a — refresh the `.backup` sidecar AFTER the primary
+          // write, from the content we just committed. safeWrite is atomic
+          // (tmp file + rename), so a pre-write snapshot bought no torn-write
+          // protection; all it did was leave the sidecar one revision stale.
+          // safeJson's restore-on-missing/corrupt path then silently REVERTS
+          // the last committed change and rewrites it to the primary — which is
+          // how a project removed via removeProject() reappeared in config.json
+          // and survived dashboard refreshes, engine ticks, and restart.
+          // Copying after the write also stops a corrupt primary from being
+          // copied over the last known-good backup.
           const backupPath = filePath + '.backup';
-          try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
           safeWrite(filePath, finalData);
+          try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
         }
         // Side-effect hook fired only when an actual write happened. Callers
         // use this to emit cache-invalidation signals (events table row) so
@@ -1811,7 +1892,7 @@ function mutateControl(mutator) {
 
 // ── Crash-loop detection (W-mr2c46590003e3ee) ──────────────────────────────
 // Three independent mechanisms can respawn a dead/frozen engine process:
-// engine/supervisor.js#checkEngine / #checkEngineHung, engine/watchdog.js
+// engine/recovery/supervisor.js#checkEngine / #checkEngineHung, engine/recovery/watchdog.js
 // (OS-scheduled external recovery), and dashboard.js's in-process 30s
 // watchdog. None of them counted or throttled repeated crashes, so a genuine
 // crash-loop (engine dying every few minutes) silently self-healed forever
@@ -1890,7 +1971,7 @@ function recordEngineRespawn(source) {
 }
 
 function mutateEngineState(mutator) {
-  const store = require('./small-state-store');
+  const store = require('../persistence/small-state-store');
   const { result } = store.applyEngineStateMutation((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
     return mutator(data) || data;
@@ -1899,19 +1980,19 @@ function mutateEngineState(mutator) {
 }
 
 function readEngineState() {
-  const data = require('./small-state-store').readEngineState();
+  const data = require('../persistence/small-state-store').readEngineState();
   if (!data || typeof data !== 'object' || Array.isArray(data)) return {};
   return data;
 }
 
 function mutateCooldowns(mutator) {
-  const store = require('./small-state-store');
+  const store = require('../persistence/small-state-store');
   const { wrote, result } = store.applyCooldownsMutation((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
     return mutator(data) || data;
   });
   if (wrote) {
-    try { require('./db-events').emitStateEvent('cooldowns'); } catch { /* optional */ }
+    try { require('../persistence/db-events').emitStateEvent('cooldowns'); } catch { /* optional */ }
   }
   return result;
 }
@@ -2229,7 +2310,7 @@ function validateGhSlug(slug) {
 }
 
 // P-f2-gh-shell (F2): validators for `gh api` endpoint paths and numeric IDs.
-// Used by engine/github.js to gate argv-form shell-out calls (shellSafeGh)
+// Used by engine/providers/github.js to gate argv-form shell-out calls (shellSafeGh)
 // against poisoned PR JSON that could carry shell metacharacters or non-numeric
 // IDs through to child_process. All validators throw a structured Error on
 // rejection — callers must let it propagate so the shell-out never happens.
@@ -2418,7 +2499,7 @@ function shellSafeGh(args, opts = {}) {
 
 // W-mr3tayu4 — shared, age-gated stale `.git/index.lock` remover. Previously
 // lived only in engine.js and was called from the worktree-mode `git worktree
-// add` retry paths; it is now shared so engine/live-checkout.js#prepareLiveCheckout
+// add` retry paths; it is now shared so engine/worktrees/live-checkout.js#prepareLiveCheckout
 // (checkoutMode:'live' projects) can self-heal the same failure without a
 // circular import. Removes `<rootDir>/.git/index.lock` ONLY when it is older
 // than STALE_INDEX_LOCK_MAX_AGE_MS (5 min) — deliberately conservative so a lock
@@ -2590,11 +2671,117 @@ function cleanChildEnv() {
   return { ..._cleanEnvCache };
 }
 
+// Engine-owned defaults also protect PR branches that predate runner safeguards.
+function applyAgentTestLoadSafetyEnv(env) {
+  if (!env || typeof env !== 'object') return env;
+  env.MINIONS_TEST_HOST_RUNTIME_PRESENT = '1';
+  if (!(Number(env.MINIONS_TEST_CONCURRENCY) > 0)) {
+    env.MINIONS_TEST_CONCURRENCY = '1';
+  }
+  if (!(Number(env.MINIONS_TEST_GLOBAL_CONCURRENCY_CAP) > 0)) {
+    env.MINIONS_TEST_GLOBAL_CONCURRENCY_CAP = '3';
+  }
+  return env;
+}
+
 // Environment for git commands — prevents credential manager from opening browser
 function gitEnv() {
   return { ...process.env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' };
 }
 
+// ── Shared remote-ref refresh serialization (W-ms5tb6ha016fda10) ─────────────
+//
+// Two dispatches preparing FRESH worktrees in the SAME clone during the same
+// tick both run `git fetch origin <mainBranch>`, and both target the SAME
+// `refs/remotes/origin/<mainBranch>`. Git takes a `<ref>.lock` for the update,
+// so the loser dies with `cannot lock ref 'refs/remotes/origin/main': is at
+// <sha> but expected <sha>`. That is a purely LOCAL serialization defect: it
+// has nothing to do with connectivity, and laundering it into
+// FAILURE_CLASS.NETWORK_ERROR hid the real cause behind a "flaky network"
+// story while burning dispatch retries.
+//
+// Two complementary mitigations live here:
+//
+//   1. `withSerializedRemoteRefRefresh` — an in-process, per-repository async
+//      mutex. The engine daemon is the process that actually issues the
+//      concurrent fresh-worktree fetches, so chaining them per resolved repo
+//      path removes the race at its source. It is deliberately NOT a file
+//      lock: a file lock here would be held across a network round-trip,
+//      which the concurrency rules in CLAUDE.md forbid. The chain is keyed on
+//      the repo, so unrelated projects still fetch in parallel and no
+//      unrelated work is serialized.
+//
+//   2. `isGitRefLockError` — classification for the residual cross-process
+//      case (an operator's own `git fetch`, the dashboard, or the CLI racing
+//      the daemon), which maps to the retryable FAILURE_CLASS.GIT_REF_LOCK.
+const GIT_REF_LOCK_PATTERNS = [
+  /cannot lock ref/i,
+  /unable to lock ref/i,
+  /cannot lock the ref/i,
+  /unable to update local ref/i,
+  /unable to create '[^']*\.lock'/i,
+  /ref\b[^\n]*\bis at\b[^\n]*\bbut expected\b/i,
+];
+
+/**
+ * True when a git failure is a LOCAL ref-lock contention loss rather than a
+ * network/auth failure. Accepts an Error, a string, or anything stringifiable;
+ * inspects `stderr` and `stdout` too because `child_process.exec` rejections
+ * put the actionable git text there rather than in `message`.
+ */
+function isGitRefLockError(err) {
+  if (!err) return false;
+  const parts = [];
+  if (typeof err === 'string') parts.push(err);
+  else {
+    if (err.message) parts.push(String(err.message));
+    if (err.stderr) parts.push(String(err.stderr));
+    if (err.stdout) parts.push(String(err.stdout));
+    if (parts.length === 0) parts.push(String(err));
+  }
+  const text = parts.join('\n');
+  return GIT_REF_LOCK_PATTERNS.some(re => re.test(text));
+}
+
+// resolved repo key -> tail promise of the currently queued refresh chain
+const _remoteRefRefreshChains = new Map();
+
+/**
+ * Serialize `fn` against every other remote-ref refresh for the same
+ * repository within this process. Returns whatever `fn` resolves/rejects with
+ * — the queue never swallows errors, and a rejected refresh does not poison
+ * the chain for the next caller.
+ *
+ * Keep `fn` scoped to the ref refresh itself. Do NOT wrap worktree creation,
+ * checkout, or merge work in it: those are unrelated expensive operations and
+ * serializing them would convert a narrow correctness fix into a throughput
+ * regression.
+ */
+function withSerializedRemoteRefRefresh(repoKey, fn) {
+  if (typeof fn !== 'function') {
+    return Promise.reject(new TypeError('withSerializedRemoteRefRefresh requires a function'));
+  }
+  let key;
+  try { key = _normalizeWorktreePath(path.resolve(String(repoKey || ''))); }
+  catch { key = null; }
+  if (!key) key = '<no-repo>';
+  const previous = _remoteRefRefreshChains.get(key) || Promise.resolve();
+  // `previous` is already error-swallowed (see `tail`), but guard both settle
+  // paths so a future refactor cannot deadlock the chain on a rejection.
+  const run = previous.then(() => fn(), () => fn());
+  const tail = run.then(() => {}, () => {});
+  _remoteRefRefreshChains.set(key, tail);
+  tail.then(() => {
+    if (_remoteRefRefreshChains.get(key) === tail) _remoteRefRefreshChains.delete(key);
+  });
+  return run;
+}
+
+/** Test-only: drop every queued refresh chain. */
+function _resetRemoteRefRefreshChainsForTesting() {
+  _remoteRefRefreshChains.clear();
+}
+
 // ── Stream-JSON Output Parsing (runtime-aware delegator) ────────────────────
 
 /**
@@ -2607,7 +2794,7 @@ function gitEnv() {
  *
  * Signatures supported:
  *   parseStreamJsonOutput(raw)
- *   parseStreamJsonOutput(raw, optsObj)         ← legacy form (engine/llm.js still uses this)
+ *   parseStreamJsonOutput(raw, optsObj)         ← legacy form (engine/agents/llm.js still uses this)
  *   parseStreamJsonOutput(raw, runtimeName)
  *   parseStreamJsonOutput(raw, runtimeName, optsObj)
  *
@@ -2622,7 +2809,7 @@ function parseStreamJsonOutput(raw, runtimeName, opts) {
   }
   // Lazy require to avoid a circular dep at module init (runtimes/claude.js
   // doesn't import shared, but downstream adapters might).
-  const { resolveRuntime } = require('./runtimes');
+  const { resolveRuntime } = require('../runtimes');
   return resolveRuntime(runtimeName).parseOutput(raw, opts || {});
 }
 
@@ -2702,7 +2889,7 @@ const KB_CATEGORIES = ['architecture', 'conventions', 'project-notes', 'build-re
 // authoring populate but that aren't destinations for inbox classification:
 //
 //   agents          — per-agent personal memory (knowledge/agents/<id>.md),
-//                     loaded by engine/consolidation.js + engine/playbook.js.
+//                     loaded by engine/memory/consolidation.js + engine/agents/playbook.js.
 //   consolidated /
 //   consolidation /
 //   consolidations  — three historical names the consolidation pipeline has
@@ -2740,7 +2927,7 @@ const KB_READABLE_CATEGORIES = Object.freeze([
  * duplicate-titled knowledge/project-notes/*.md entries on a single day) and
  * the sibling W-mr3lokxs fix for live-checkout-dirty alerts.
  *
- * `engine/dispatch.js#writeInboxAlert` names every file `engine-alert-<slug>-
+ * `engine/orchestration/dispatch.js#writeInboxAlert` names every file `engine-alert-<slug>-
  * <date>.md`, so the filename prefix is one signal. `shared.js#_writeWorktree
  * SkipLiveInboxNote` (and any other engine-authored note) stamps frontmatter
  * `agent: engine`, accepted as a second signal so alerts written under a
@@ -2980,7 +3167,7 @@ function isDispatchExecutionPathSafe(item, config) {
 // otherwise `false`. Only an explicit boolean counts as "set" at either level —
 // anything else (undefined / null / string) is treated as unset so the next
 // tier (or the `false` default) decides. When ON and a live-checkout tree is
-// dirty, `engine/live-checkout.js#prepareLiveCheckout` runs
+// dirty, `engine/worktrees/live-checkout.js#prepareLiveCheckout` runs
 // `git reset --hard HEAD` + `git clean -fd` instead of refusing with
 // LIVE_CHECKOUT_DIRTY. This discards uncommitted tracked and untracked work but
 // preserves the current branch and committed history, so it is opt-in. Sibling
@@ -3116,6 +3303,39 @@ function resolveCodexCcSandbox(engine) {
   return validateCodexSandbox(configured);
 }
 
+// W-ms87lj8j018j2572 — SINGLE SOURCE OF TRUTH for the quarantine recovery
+// window. Quarantine recovery REFS (`refs/minions/quarantine/*` and
+// `refs/minions/quarantine-wip/*`, pruned by
+// `engine/worktrees/quarantine-refs.js`) and PROTECTED quarantine DIRECTORIES
+// (swept by `engine/worktrees/gc.js` at
+// `ENGINE_DEFAULTS.worktreeProtectedQuarantineRetentionMs`) govern the SAME
+// operator recovery story, so they MUST expire together. They previously drifted
+// (10d vs 30d) because each side owned its own literal. The constant lives here —
+// the lowest dependency-free layer — because `engine/worktrees/quarantine-refs.js`
+// already `require`s this module, so shared.js cannot import from it at load time.
+// Consumers must reference these bindings; never re-derive the number.
+const QUARANTINE_REF_RETENTION_DAYS = 30;
+const QUARANTINE_REF_RETENTION_MS = QUARANTINE_REF_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+
+/**
+ * Resolve the operator-visible quarantine recovery window in ms.
+ *
+ * W-ms87rbe601a66d13 — aligning the two DEFAULTS (above) is only half the
+ * story: `engine.worktreeProtectedQuarantineRetentionMs` is an operator knob,
+ * and until both sweeps read it the directory sweep alone honored an override
+ * while the REF sweep stayed pinned to the built-in constant. That reintroduces
+ * the exact divergence at runtime that the shared constant removes at build
+ * time. This resolver is the single seam both sweeps go through, so lowering,
+ * raising, or disabling retention always moves them together.
+ *
+ * A non-positive value means INDEFINITE retention on both sides (the documented
+ * `0` opt-out) — never "everything is already expired".
+ */
+function resolveQuarantineRetentionMs(config) {
+  const configured = Number(config?.engine?.worktreeProtectedQuarantineRetentionMs);
+  return Number.isFinite(configured) ? Math.max(0, configured) : QUARANTINE_REF_RETENTION_MS;
+}
+
 const ENGINE_DEFAULTS = {
   // W-mpxpckey000laa4f: tick interval lowered 60s → 10s so the shipped default
   // matches what operators already run at (live boxes have had `tickInterval:
@@ -3165,7 +3385,7 @@ const ENGINE_DEFAULTS = {
   // [1000, 120000] in dashboard.js POST /api/settings.
   assertCleanStatusTimeoutMs: 10000,
   // W-mqpx0tpi — cold-start health budget for `minions restart` / post-update
-  // restart verification (engine/restart-health.js#waitForRestartHealth). The
+  // restart verification (engine/recovery/restart-health.js#waitForRestartHealth). The
   // dashboard runs node:sqlite migrations + SPA HTML assembly + initial state
   // reads SYNCHRONOUSLY before server.listen(), so right after `npm install`
   // on a slow/loaded box the PID is alive but port 7331 is unbound well past
@@ -3190,6 +3410,16 @@ const ENGINE_DEFAULTS = {
   decomposeZeroChildrenStaleMinutes: 30,
   autoApprovePlans: false, // auto-approve PRDs without waiting for human approval
   autoArchive: false, // opt-in: auto-archive plans after verify completes (false = mark ready, user archives manually)
+  // W-msal3ser01q4ccb3 — opt-in: after a PRD's verify work item(s) complete
+  // SUCCESSFULLY and the canonical prd/guides/verify-<plan>.md has been
+  // persisted, auto-create a PRD-driven QA Session (mode 'auto', so
+  // SETUP→DRAFT→EXECUTE runs without approval) through the SAME
+  // buildQaSessionSpecFromPrd + createSession + queueSetup path that backs
+  // POST /api/qa/from-prd. Deliberately NOT keyed off the PRD's top-level
+  // `status: completed` flip — that happens before verification finishes.
+  // Resolved via shared.resolveAutoQaCompletedPrds(engine). Default false =
+  // behavior-identical to today.
+  autoQaCompletedPrds: false,
   autoFixConflicts: true, // auto-dispatch fix agents when a PR has merge conflicts
   autoFixBuilds: true, // auto-dispatch fix agents when a PR build fails
   autoReviewPrs: true, // auto-dispatch review agents for newly opened agent PRs
@@ -3222,7 +3452,7 @@ const ENGINE_DEFAULTS = {
   // to before this knob existed. Flip via Dashboard → Settings → Auto-fix
   // & Review Loop, or set `engine.autoFixPaused: true` in config.json.
   autoFixPaused: false, // hard-stop kill-switch / master override (see comment above)
-  autoConsolidateMemory: true, // default-on: periodically spawn engine/kb-sweep-runner.js from the tick loop (4h cadence). Explicit false disables it; inbox→notes consolidation is independent.
+  autoConsolidateMemory: true, // default-on: periodically spawn engine/memory/kb-sweep-runner.js from the tick loop (4h cadence). Explicit false disables it; inbox→notes consolidation is independent.
   // W-mrktrokd — batteries-included default schedules. When true (default),
   // adding a project auto-creates its per-project git-fetch-freshness schedule
   // (`keep-branch-fresh-git-fetch-origin-<slug>`, cron `0 */12 *`, explore) and
@@ -3232,7 +3462,7 @@ const ENGINE_DEFAULTS = {
   // Bootstrap is idempotent + non-destructive — it never duplicates or
   // overwrites a schedule an operator has already created/customized (matched
   // by schedule id). Set false to opt every install out. See
-  // engine/schedule-bootstrap.js and Dashboard → Settings → Workflow Defaults.
+  // engine/orchestration/schedule-bootstrap.js and Dashboard → Settings → Workflow Defaults.
   bootstrapDefaultSchedules: true,
   // W-mr48yth5 — per-category age-based TTL (in days) for the KB sweep's expiry
   // pass. During runKbSweep, an entry in a listed category whose authored date
@@ -3361,8 +3591,8 @@ const ENGINE_DEFAULTS = {
   evalMaxCost: null, // USD ceiling per work item across all eval iterations; null = no limit (gather baseline data first)
   maxRetries: 3, // max dispatch retries before marking work item as failed
   maxRetriesPerAgent: 2, // W-mpmwxn1j — per-agent retry cap. When the SAME agent fails the same WI this many times, the next retry MUST reassign to a different eligible agent (consults routing.md + agent availability). Falls back to the same agent only when no alternate is available. Counted separately from `maxRetries` (which caps total retries across all agents) and tracked on the WI as `_retriesByAgent: { agentId: count }`. Hard-pinned agents bypass reassignment (operator intent wins).
-  maxPhantomRetries: 3, // max retries for "phantom completion" (runtime crashed before emitting type:"result"); tracked separately from _retryCount so phantom retries don't pollute the normal PR-attachment retry budget. See engine/lifecycle.markMissingPrAttachment + detectNonTerminalResultSummary.
-  maxReviewVerdictMissingRetries: 2, // W-mr9sy3j700076967 — bounded retry budget for a review dispatch that completes ("success") without posting a VERDICT: comment. Below the budget, engine/lifecycle.updatePrAfterReview leaves `lastReviewedAt` unset so the normal needsReview gate re-dispatches a fresh review; at/above budget it stamps `lastReviewedAt` (stops auto-retry) but keeps `_reviewVerdictMissing: true` so the PR is dashboard-flagged for a human instead of looking like an ordinary still-pending review.
+  maxPhantomRetries: 3, // max retries for "phantom completion" (runtime crashed before emitting type:"result"); tracked separately from _retryCount so phantom retries don't pollute the normal PR-attachment retry budget. See engine/orchestration/lifecycle.markMissingPrAttachment + detectNonTerminalResultSummary.
+  maxReviewVerdictMissingRetries: 2, // W-mr9sy3j700076967 — bounded retry budget for a review dispatch that completes ("success") without posting a VERDICT: comment. Below the budget, engine/orchestration/lifecycle.updatePrAfterReview leaves `lastReviewedAt` unset so the normal needsReview gate re-dispatches a fresh review; at/above budget it stamps `lastReviewedAt` (stops auto-retry) but keeps `_reviewVerdictMissing: true` so the PR is dashboard-flagged for a human instead of looking like an ordinary still-pending review.
   minRetryGapMs: 120000, // 2min — minimum gap between retry dispatches for the same work item; prevents tight retry loops when an idempotent agent (e.g. review bailing out on a duplicate) cannot produce the expected output (#1770)
   pipelineApiRetries: 2, // max attempts for pipeline API calls
   pipelineApiRetryDelay: 2000, // ms delay between pipeline API retries
@@ -3446,7 +3676,7 @@ const ENGINE_DEFAULTS = {
   memoryBaselineEveryTicks: 6,
   // W-mr2c4i8m0004da94: proactive crash diagnostics for the engine.js
   // node.exe process. When enabled (default), every spawn of engine.js
-  // (bin/minions.js `start`/`restart` AND engine/supervisor.js respawn-on-
+  // (bin/minions.js `start`/`restart` AND engine/recovery/supervisor.js respawn-on-
   // death) gets NODE_OPTIONS += `--report-on-fatalerror --report-on-signal
   // --diagnostic-dir=<CRASH_REPORTS_DIR>` so a fatal V8 error (OOM, stack
   // overflow, native-addon crash) or an operator-sent signal
@@ -3466,6 +3696,19 @@ const ENGINE_DEFAULTS = {
   // → no flip), so the constant is GitHub-only today but lives in shared defaults so a future
   // ADO change can adopt the same semantics.
   prAbandonConfirmCount: 3,
+  // W-msav5edk00g81710: bounded re-probe window for `abandoned` PR records. A PR can
+  // legitimately leave `abandoned` — GitHub and ADO both allow reopening a closed PR —
+  // but `PR_POLLABLE_STATUSES` excludes terminal statuses, so before this constant the
+  // abandoned stamp was a one-way door and the poller could never observe the reopen
+  // (incident: github:opg-microsoft/minions#1154, closed 16:07:07Z and reopened
+  // 16:10:07Z, stuck `abandoned` for hours while OPEN and one hourly-sweep run away
+  // from a permanent `userDeleted` tombstone). `isPrPollable` keeps an abandoned record
+  // in the STATUS poll for this long after it was abandoned, then drops it again. The
+  // window is what keeps the cost bounded: re-probing every terminal record forever
+  // would burn API quota linearly in tracker size. Records with no abandonment anchor
+  // fail CLOSED (never re-probed), and a host-confirmed deletion
+  // (`_reconciliation404Confirmed`) closes the window early. `0` disables re-probing.
+  abandonedPrRepollWindowMs: 7 * 24 * 60 * 60 * 1000, // 7 days
   // W-mp60tw0u000j3931: One-shot startup reconciliation pass for `abandoned` PRs runs
   // exactly once per bump of this constant. The engine compares this value against
   // the persisted lastAbandonedReconciliationVersion at boot; if the version
@@ -3474,24 +3717,43 @@ const ENGINE_DEFAULTS = {
   // hardening in W-mp5trwh60008386d shipped) are flipped back to active/merged/closed
   // based on their live API state. Bump this when reconciliation logic itself changes
   // and we want it to re-run once on every install.
-  abandonedReconciliationVersion: 1,
+  //
+  // Bumped to 2 by W-msav5edk00g81710: that WI changed abandonment bookkeeping
+  // (records now carry an `_abandonedAt` anchor) and added the bounded re-probe
+  // window. Records abandoned BEFORE the bump have no anchor beyond `closedAt`,
+  // and anything older than the window is out of the poller's reach entirely —
+  // this boot pass is their one-off repair, including the #1154 incident record.
+  abandonedReconciliationVersion: 2,
   watchesIncludeBehindBy: false, // opt-in: when true, GitHub PR poll calls /compare/{base}...{head} once per pr per pollPrStatusEvery cadence to populate pr.behindBy (powers the `behind-master` watch predicate). Off by default to avoid the extra API call. ADO PRs always get null (no commit-graph walk yet).
   autoCompletePrs: false, // auto-merge PRs when builds green + review approved (opt-in)
+  // W-ms7kklp8002zad24 — ADO-only: proactively queue the required PR-validation
+  // (branch-policy) builds for DRAFT pull requests. On Azure DevOps, branch build
+  // policies do NOT run automatically while a PR is a draft, so a Minions-managed
+  // draft PR never gets a build status and the build-fix loop has nothing to act
+  // on. When ON (default), pollPrStatus discovers the required Build policies from
+  // the target branch's policy configurations and queues a fresh build per distinct
+  // definition against refs/pull/<n>/merge (rate-limited via _lastBuildRequeueAt).
+  // GitHub already fires CI on drafts, so this is inert for GitHub PRs.
+  adoQueueDraftPrBuilds: true,
   prMergeMethod: 'squash', // merge method: squash, merge, rebase
   ignoredCommentAuthors: [], // comments from these authors are auto-closed and never trigger fixes
   // P-f23classifier (F3, security note): ADO Minions identity allow-list for
-  // the marker spoof guard in engine/ado.js pollPrHumanComments. ADO has no
+  // the marker spoof guard in engine/ado/index.js pollPrHumanComments. ADO has no
   // viewerDidAuthor equivalent, so a human pasting the <!-- minions:agent=... -->
   // marker would otherwise be misclassified as agent-authored. The poller
   // combines marker-presence with comment.author.{uniqueName|displayName|id|
   // descriptor} matching one of these (case-insensitive) before treating a
-  // body as agent-authored. Empty array (default) means marker-presence alone
-  // NEVER classifies as agent on ADO — the body still has to match one of
-  // the legacy patterns (Minions(...), by Minions, [minions], VERDICT:).
+  // body as agent-authored.
+  // W-msbf1kf6033f46cb: an empty array (default) means the identity signal is
+  // UNAVAILABLE, not mismatched, so the marker alone classifies as agent
+  // (fail-safe) and the poller logs a one-time warning that the spoof guard is
+  // inactive. Populating this list re-enables the cross-check. The previous
+  // fail-OPEN reading gave the marker zero filtering power on ADO and let every
+  // agent fix-summary re-trigger a fix dispatch on the same PR.
   minionsAdoIdentities: [],
   botCommentLogins: [], // P-a3f9b2c1: opt-in shared-minions GH login list — comments from these logins are suppressed ONLY when body matches positive-signal markers (Verification SUCCESS / VERDICT:APPROVE / noop:true). Narrower than ignoredCommentAuthors which suppresses all comments by login.
   // W-mp76pw7a001da7c1 — Per-slug GitHub PAT routing. Map of `<owner>` (or `<owner>/*`,
-  // or `*` for fleet default) to a `gh auth` account name. `engine/gh-token.js`
+  // or `*` for fleet default) to a `gh auth` account name. `engine/providers/gh-token.js`
   // resolves the right token via `gh auth token --user <account> --hostname github.com`
   // and threads it as `GH_TOKEN` for that one shell-out, so the engine never depends
   // on which gh account is globally active. Empty `{}` (default) preserves legacy
@@ -3500,7 +3762,7 @@ const ENGINE_DEFAULTS = {
   ghAccounts: {},
   agentBusyReassignMs: 600000, // 10min — reassign work item to another agent if preferred agent is busy beyond this threshold
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
-  enablePreDispatchEval: true, // P-d2a9f6e5: cheap LLM gate before queueing — on by default. See engine/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review). Validates from acceptance_criteria when present, falls back to description when criteria are absent but description is rich (≥80 chars). Fail-open on any validator error.
+  enablePreDispatchEval: true, // P-d2a9f6e5: cheap LLM gate before queueing — on by default. See engine/orchestration/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review). Validates from acceptance_criteria when present, falls back to description when criteria are absent but description is rich (≥80 chars). Fail-open on any validator error.
   // W-mq9acoo800177bcb — bounded-concurrency for the pre-dispatch validator. The
   // discoverWork loop in engine.js used to run validateAcceptanceCriteria
   // sequentially, costing ~25-30s per item × N items per tick (an 11-item
@@ -3533,7 +3795,7 @@ const ENGINE_DEFAULTS = {
   preDispatchEvalMaxRejections: 5,
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
   autoApplyReviewVote: false, // Master gate for platform vote mutations; local verdicts remain informational when false.
-  createPrsAsDraft: false, // W-mrtdy7xv — when true, the playbook PR-creation guidance (engine/playbook.js#getPrCreateInstructions) tells agents to open normal Minions-created PRs as DRAFT (GitHub `gh pr create --draft`; ADO `az repos pr create --draft true`). Default false = behave exactly as today. Per-project-overridable via `project.createPrsAsDraft` (explicit boolean), resolved through `shared.resolveCreatePrsAsDraft(project, engine)` — a project can opt IN or OUT independent of this fleet-wide default. Aggregate/E2E verify PRs already open as draft via verify.md regardless of this flag; the engine-opened shared-branch aggregate PR is outside the playbook seam and unaffected.
+  createPrsAsDraft: false, // W-mrtdy7xv — when true, the playbook PR-creation guidance (engine/agents/playbook.js#getPrCreateInstructions) tells agents to open normal Minions-created PRs as DRAFT (GitHub `gh pr create --draft`; ADO `az repos pr create --draft true`). Default false = behave exactly as today. Per-project-overridable via `project.createPrsAsDraft` (explicit boolean), resolved through `shared.resolveCreatePrsAsDraft(project, engine)` — a project can opt IN or OUT independent of this fleet-wide default. Aggregate/E2E verify PRs already open as draft via verify.md regardless of this flag; the engine-opened shared-branch aggregate PR is outside the playbook seam and unaffected.
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.
@@ -3556,13 +3818,13 @@ const ENGINE_DEFAULTS = {
   // projects.<worktreePath>.enabledMcpjsonServers (the field Claude Code actually reads — see live ~/.claude.json
   // shape) means the workspace MCPs are connected on first call. Best-effort: failures NEVER block dispatch.
   // Engine-scoped per the CLAUDE.md rule against `runtime.name === ...` branches at call sites — the runtime check
-  // lives inside the helper (engine/spawn-agent.js#preApproveWorkspaceMcps) which no-ops for non-Claude runtimes.
+  // lives inside the helper (engine/agents/spawn-agent.js#preApproveWorkspaceMcps) which no-ops for non-Claude runtimes.
   claudePreApproveWorkspaceMcps: true,
   // W-mrdon0pe000l045a — propagate repo-authored CLAUDE.md instructions to
   // runtimes that do NOT auto-discover CLAUDE.md natively (Copilot, Codex).
   // When TRUE (default), the engine bounded-discovers the nearest applicable
   // CLAUDE.md files for a dispatch and injects them as a "Project instructions
-  // (CLAUDE.md)" context layer (engine/playbook.js → engine/claude-md-context.js).
+  // (CLAUDE.md)" context layer (engine/agents/playbook.js → engine/agents/claude-md-context.js).
   // Claude is always skipped — its own CLI already reads CLAUDE.md, so injecting
   // it again would double the instructions. CLAUDE.md carries no split-brain
   // risk for Copilot/Codex because those runtimes never read it themselves, so
@@ -3573,12 +3835,12 @@ const ENGINE_DEFAULTS = {
   propagateClaudeMdForNonClaudeRuntimes: true,
   // W-mrtdmtwq000kf391 — surface the repo HARNESS assets in effect for a
   // dispatch (runtime + project) in the Minions-authored PR body. When TRUE
-  // (default), engine/playbook.js injects a PR-body appendix instructing the
+  // (default), engine/agents/playbook.js injects a PR-body appendix instructing the
   // agent to append a fenced "## Repo harnesses used" section listing the
   // dispatch's runtime, injected CLAUDE.md files, AGENTS.md discovery, MCP
   // servers, and skills. Pure reporting via the read-only harness-diagnostics
-  // source (engine/harness-context.js → engine/preflight._runtimeHarnessRows +
-  // engine/claude-md-context.js); it never propagates or attests any asset.
+  // source (engine/agents/harness-context.js → engine/agents/preflight._runtimeHarnessRows +
+  // engine/agents/claude-md-context.js); it never propagates or attests any asset.
   includeHarnessSectionInPrBody: true,
   copilotStreamMode: 'on',           // Copilot --stream <on|off>: 'on' streams assistant.message_delta events live; 'off' batches them
   copilotReasoningSummaries: false,  // Copilot --enable-reasoning-summaries (Anthropic-family models only)
@@ -3586,7 +3848,7 @@ const ENGINE_DEFAULTS = {
   // P-9b3d5f61 (Pool copilot agent dispatches through a shared ACP worker pool):
   // when true AND the resolved runtime declares `capabilities.acpWorkerPool`,
   // engine.js spawnAgent routes per-agent dispatches through
-  // engine/agent-worker-pool.js (persistent `copilot --acp` workers) instead of
+  // engine/agents/agent-worker-pool.js (persistent `copilot --acp` workers) instead of
   // cold-spawning a fresh CLI per dispatch. Opt-in while fleet-pool lifecycle
   // hardening remains newer than the established cold-spawn path. Structurally
   // Copilot-only, same as
@@ -3594,7 +3856,7 @@ const ENGINE_DEFAULTS = {
   // resolved runtime's capability flag isn't true, regardless of this override.
   agentUseWorkerPool: false,
   // P-9b3d5f61 — max concurrent ACP workers the per-agent pool
-  // (engine/agent-worker-pool.js) will keep warm. `undefined` = fall back to
+  // (engine/agents/agent-worker-pool.js) will keep warm. `undefined` = fall back to
   // the fleet's `maxConcurrent` dispatch cap via resolveAgentAcpPoolSize, so
   // the pool never queues more than the engine would have dispatched anyway.
   agentAcpPoolSize: undefined,
@@ -3686,7 +3948,8 @@ const ENGINE_DEFAULTS = {
   liveCheckoutAutoFreshen: false,
   orphanHolderScanTimeoutMs: 5000,          // 5s ceiling for the cross-platform holder scan (PowerShell / /proc walk / lsof)
   ccMaxTurns: 50, // max tool-use turns per CC/doc-chat call before CLI stops (per response, not per session)
-  ccWorkerIdleTimeoutMs: 30 * 60 * 1000, // W-mr0qs0vw: idle-reaper window for the persistent `copilot --acp` worker pool (engine/cc-worker-pool.js). After this much inactivity with no in-flight turn the warm ACP process is killed; the next message cold-spawns a fresh session with NO memory of prior turns (CC shows a "context cleared after inactivity" notice). Tradeoff: shorter = less idle memory/process footprint, longer = more context durability across gaps between messages. Wired into the pool via ccWorkerPool.setIdleTimeoutMs() on every reloadConfig(); clamped to [60000, 28800000] (1min–8h) in the settings POST handler. W-mr1qbj90000d30bd: `0` is an explicit "never idle-reap" sentinel that bypasses the clamp — cc-worker-pool.js maps it to an Infinity window so only an explicit closeTab kills the warm worker; Settings page exposes this as the "Never idle-reap CC workers" toggle.
+  ccWorkerIdleTimeoutMs: 30 * 60 * 1000, // W-mr0qs0vw: idle-reaper window for the persistent `copilot --acp` worker pool (engine/agents/cc-worker-pool.js). After this much inactivity with no in-flight turn the warm ACP process is killed; the next message cold-spawns a fresh session with NO memory of prior turns (CC shows a "context cleared after inactivity" notice). Tradeoff: shorter = less idle memory/process footprint, longer = more context durability across gaps between messages. Wired into the pool via ccWorkerPool.setIdleTimeoutMs() on every reloadConfig(); clamped to [60000, 28800000] (1min–8h) in the settings POST handler. W-mr1qbj90000d30bd: `0` is an explicit "never idle-reap" sentinel that bypasses the clamp — cc-worker-pool.js maps it to an Infinity window so only an explicit closeTab kills the warm worker; Settings page exposes this as the "Never idle-reap CC workers" toggle.
+  acpHandshakeTimeoutMs: 180000, // issue #1105: budget for the cold ACP worker handshake (`initialize` + `session/new` / `session/load`) in engine/agents/acp-transport.js, shared by the CC worker pool (engine/agents/cc-worker-pool.js) and the agent worker pool (engine/agents/agent-worker-pool.js). A cold `copilot --acp` start that loads the user's MCP configuration routinely exceeds the old hardcoded 60s, which surfaced as "Command Center returned no output / handshake timed out after 60000ms". Pushed into each pool via setHandshakeTimeoutMs() on config load; clamped to [10000, 900000] (10s–15min) in the settings POST handler. Timeout still raises the typed, retriable ACP_HANDSHAKE_FAILED error.
   ccTurnTimeoutMs: 300000, // W-mpmwxni2000c25c7-b/-d: 5min per-turn no-progress watchdog. The window resets on every liveness signal — token chunk, tool-call notification, tool-update — so an actively-streaming CC/doc-chat turn (long shell command, deep search, sub-agent loop) survives indefinitely up to the outer CC_CALL_TIMEOUT_MS (~1h) ceiling. Only true silence past this window with no progress fires the cancel: the in-flight LLM call is aborted and the handler surfaces `{code:'cc-turn-timeout', retryable:true}` via the typed error envelope so the UI can stop the spinner and offer Retry. Clamped to [10000, 3600000] in the settings POST handler. Independent of CC_CALL_TIMEOUT_MS. Non-streaming doc-chat is the lone wall-clock exception (no progress hooks); see _raceCcDocChatTimeout in dashboard.js for the dual factory/promise shape.
   docSessionMaxEntries: 200, // cap doc-chat session map/disk store by least-recent activity (LRU; sessions are non-expiring otherwise)
   ccLiveStreamMaxAgeMs: 30 * 60 * 1000, // hard cap reconnect buffers if abort/cleanup stalls
@@ -3718,7 +3981,7 @@ const ENGINE_DEFAULTS = {
   memoryRetrievalMaxBytes: 8 * 1024, // hard byte budget for the Relevant Memory prompt appendix
   memoryRetrievalCandidateLimit: 50, // bounded FTS5 candidate pool before deterministic re-ranking
   memoryEpisodicCapture: false, // opt-in capture of compact task outcomes; never stores transcripts or chain-of-thought
-  untrustedFenceMaxBytes: 64 * 1024, // F5 (W-mpeklod3000we69c): per-block cap for `<UNTRUSTED-INPUT>` fences in engine/untrusted-fence.js. 64KB is long enough for realistic PR comments / pinned notes / agent memory sections, short enough that a megabyte-bomb comment cannot blow up the prompt. Content above the cap is truncated INSIDE the fence with a `[truncated N more bytes]` marker so the agent still sees the provenance attribute.
+  untrustedFenceMaxBytes: 64 * 1024, // F5 (W-mpeklod3000we69c): per-block cap for `<UNTRUSTED-INPUT>` fences in engine/core/untrusted-fence.js. 64KB is long enough for realistic PR comments / pinned notes / agent memory sections, short enough that a megabyte-bomb comment cannot blow up the prompt. Content above the cap is truncated INSIDE the fence with a `[truncated N more bytes]` marker so the agent still sees the provenance attribute.
   maxMeetingPromptBytes: 16 * 1024, // cap meeting findings/debate context injected into prompts
   maxMeetingHumanNotesBytes: 2 * 1024, // cap human note bullet lists injected into meeting prompts
   maxPipelineMeetingContextBytes: 16 * 1024, // cap aggregated meeting/dependency context for pipeline plan generation
@@ -3730,10 +3993,24 @@ const ENGINE_DEFAULTS = {
   // for the same project. Saves the cold install/build cost on heavy projects
   // (constellation: bun install + Vite warmup; minions: npm install + test cache).
   // Default off — opt-in fleet-wide via engine.worktreePoolSize or per-project
-  // via projects[].worktreePoolSize. See engine/worktree-pool.js + CLAUDE.md
+  // via projects[].worktreePoolSize. See engine/worktrees/pool.js + CLAUDE.md
   // "Worktree pool" section for the lifecycle and edge cases.
   worktreePoolSize: 0,                        // 0 = disabled (default); per-project override beats this
   worktreePoolIdleTtlMs: 6 * 3600 * 1000,     // 6h — idle entries past TTL are evicted by cleanup
+  // W-ms5tb6ha016fda10 — PROTECTED quarantine directories (those whose dirty
+  // WIP could NOT be snapshotted to a durable `refs/minions/quarantine-wip/*`
+  // ref) were previously kept FOREVER, so a busy install accumulated
+  // quarantine residue without bound (20 such dirs observed on 2026-07-29).
+  // They remain the longest-lived worktree artifact, but retention is now
+  // finite and is DERIVED from the single shared `QUARANTINE_REF_RETENTION_MS`
+  // constant above (30 days) — the same window
+  // `engine/worktrees/quarantine-refs.js` prunes recovery refs at — so the
+  // operator recovery window for quarantine DIRECTORIES and quarantine REFS
+  // expires together instead of one outliving the other. Do NOT replace this
+  // with a literal: the two windows drifted (10d vs 30d) exactly because each
+  // side owned its own number.
+  // Set to 0 to restore indefinite retention.
+  worktreeProtectedQuarantineRetentionMs: QUARANTINE_REF_RETENTION_MS,
   // ── keep_processes (W-mp68q6ke0010de68) ────────────────────────────────────
   // Opt-in per-WI (`meta.keep_processes: true`) feature that lets an agent
   // declare specific descendant PIDs the engine MUST NOT reap on close. The
@@ -3759,7 +4036,7 @@ const ENGINE_DEFAULTS = {
   // P-7a3b1c92 / plan W-mp7k1r760003b5dd — managed-spawn primitive: agents
   // describe long-running services in agents/<id>/managed-spawn.json and the
   // engine owns the spawn + healthcheck lifecycle. These defaults gate the
-  // validator (engine/managed-spawn.js) and later the engine-side spawn loop,
+  // validator (engine/processes/managed-spawn.js) and later the engine-side spawn loop,
   // per-tick sweep, playbook hint, and dashboard endpoints. Mirrors the
   // `keepProcesses` block intentionally — symmetry with the keep-pids
   // primitive is the documented design convention.
@@ -3857,10 +4134,35 @@ const ENGINE_DEFAULTS = {
   constellationBridge: {
     enabled: false,
   },
+  // ── Constellation companion probe (P-e93c85a1) ──────────────────────────────
+  // Read-only detection of whether a COMPATIBLE Constellation companion is
+  // present on this host. Reporting only: Minions never downloads, executes, or
+  // installs Constellation, and companion absence is a visible degraded state,
+  // never fatal. Surfaced by `minions doctor`, `minions bridge health`, and as
+  // informational output from `minions init` / `minions update`.
+  //
+  //   probeEnabled    Documented opt-out for managed deployments. `false`
+  //                   suppresses the probe ENTIRELY (no marker read, no health
+  //                   request). `MINIONS_DISABLE_COMPANION_PROBE=1` does the
+  //                   same from the environment and wins over config.
+  //   probeTimeoutMs  Hard bound on the optional loopback health request, so a
+  //                   hung companion can never stall doctor/init/update/start.
+  //                   Clamped to [250, 15000] ms at read time.
+  //   healthUrl       Operator override for the companion's health endpoint.
+  //                   `null` (default) means "use whatever the companion's own
+  //                   marker declares, if anything". LOOPBACK-ONLY: a remote
+  //                   host is refused without being requested.
+  //
+  // See engine/api/companion.js and docs/constellation-bridge.md.
+  constellationCompanion: {
+    probeEnabled: true,
+    probeTimeoutMs: 2000,
+    healthUrl: null,
+  },
   // ── Operator identity (W-mpejf0fq000e84d6) ──────────────────────────────────
   // Explicit override for the human operator's platform login used in branch
   // names (see `deriveWorkItemBranchName`). `null` (default) means auto-resolve
-  // via `engine/operator-identity.js` (gh → git email localpart → os user).
+  // via `engine/core/operator-identity.js` (gh → git email localpart → os user).
   // Settings UI exposes this as a free-text input; clearing the field deletes
   // the override and falls back to auto-resolution.
   operatorLogin: null,
@@ -3963,7 +4265,7 @@ function resolveCcCli(engine) {
 function resolveCcUseWorkerPool(engine) {
   let runtime;
   try {
-    runtime = require('./runtimes').resolveRuntime(resolveCcCli(engine));
+    runtime = require('../runtimes').resolveRuntime(resolveCcCli(engine));
   } catch {
     return false;
   }
@@ -3976,7 +4278,7 @@ function resolveCcUseWorkerPool(engine) {
 
 /**
  * P-9b3d5f61 — Resolve whether a per-agent spawn should route through the
- * persistent ACP worker pool (engine/agent-worker-pool.js). Mirrors
+ * persistent ACP worker pool (engine/agents/agent-worker-pool.js). Mirrors
  * resolveCcUseWorkerPool's shape but takes the already-resolved runtime
  * adapter (as returned by `resolveRuntime(resolveAgentCli(agent, engine))`)
  * rather than re-deriving it, since callers on the agent-spawn path already
@@ -3998,9 +4300,33 @@ function resolveAgentUseWorkerPool(engine, runtime) {
   return ENGINE_DEFAULTS.agentUseWorkerPool;
 }
 
+// Issue #1105 — clamp bounds for engine.acpHandshakeTimeoutMs. Mirrored by the
+// settings POST validator so the UI and the resolver agree on the legal range.
+const ACP_HANDSHAKE_TIMEOUT_MIN_MS = 10000;
+const ACP_HANDSHAKE_TIMEOUT_MAX_MS = 900000;
+
+/**
+ * Issue #1105 — Resolve the ACP worker handshake budget (`initialize` plus
+ * `session/new` / `session/load`) used by both ACP worker pools. Priority:
+ *   1. `engine.acpHandshakeTimeoutMs`          — operator override
+ *   2. `ENGINE_DEFAULTS.acpHandshakeTimeoutMs` — 180s default
+ *
+ * Non-numeric or non-positive overrides fall through to the default; valid
+ * values are clamped to [10s, 15min] so a bad Settings/env value can neither
+ * make the handshake un-cancellable nor fire before a cold start can finish.
+ */
+function resolveAcpHandshakeTimeoutMs(engine) {
+  const raw = engine ? engine.acpHandshakeTimeoutMs : undefined;
+  const n = typeof raw === 'number' ? raw : Number(raw);
+  if (raw === undefined || raw === null || raw === '' || !Number.isFinite(n) || n <= 0) {
+    return ENGINE_DEFAULTS.acpHandshakeTimeoutMs;
+  }
+  return Math.min(ACP_HANDSHAKE_TIMEOUT_MAX_MS, Math.max(ACP_HANDSHAKE_TIMEOUT_MIN_MS, Math.round(n)));
+}
+
 /**
  * P-9b3d5f61 — Resolve the max concurrent ACP workers the per-agent pool
- * (engine/agent-worker-pool.js) should keep warm. Priority:
+ * (engine/agents/agent-worker-pool.js) should keep warm. Priority:
  *   1. `engine.agentAcpPoolSize` — explicit operator override
  *   2. `engine.maxConcurrent`    — fleet dispatch concurrency cap (so the
  *      pool never queues more than the engine would have dispatched anyway)
@@ -4133,7 +4459,7 @@ function resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine) {
 // "set" at either level — undefined/null/absent falls through to the next tier
 // so operators can enable draft PRs fleet-wide while opting a specific project
 // OUT (or vice-versa). Pure, no I/O. Consumed by
-// engine/playbook.js#getPrCreateInstructions.
+// engine/agents/playbook.js#getPrCreateInstructions.
 function resolveCreatePrsAsDraft(project, engine) {
   if (project && typeof project === 'object' && typeof project.createPrsAsDraft === 'boolean') {
     return project.createPrsAsDraft;
@@ -4144,6 +4470,18 @@ function resolveCreatePrsAsDraft(project, engine) {
   return ENGINE_DEFAULTS.createPrsAsDraft;
 }
 
+// W-msal3ser01q4ccb3 — canonical resolution seam for the auto-QA-after-verify
+// flag. Only an explicit boolean on `engine` counts as "set"; anything else
+// (undefined/null/'true'/0) falls through to ENGINE_DEFAULTS so a malformed
+// config.json cannot silently enable an automatic dispatch. Pure, no I/O.
+// Consumed by engine/qa/auto-prd-qa.js.
+function resolveAutoQaCompletedPrds(engine) {
+  if (engine && typeof engine === 'object' && typeof engine.autoQaCompletedPrds === 'boolean') {
+    return engine.autoQaCompletedPrds;
+  }
+  return ENGINE_DEFAULTS.autoQaCompletedPrds;
+}
+
 // ─── Legacy ccModel → defaultModel Migration ─────────────────────────────────
 //
 // Pre-P-3b8e5f1d, `engine.ccModel` was the single fleet-wide model knob (it
@@ -4194,7 +4532,7 @@ function _resetLegacyCcModelMigrationFlag() {
 // ─── Runtime Config Preflight Warnings ──────────────────────────────────────
 //
 // Emit non-fatal warnings about runtime/CLI configuration drift. Consumed by
-// engine/preflight.js (which converts the entries to `{ name, ok: 'warn',
+// engine/agents/preflight.js (which converts the entries to `{ name, ok: 'warn',
 // message }` shape) and surfaced via `minions doctor`.
 //
 // The function is pure: takes the config and the list of registered runtime
@@ -4271,7 +4609,7 @@ function runtimeConfigWarnings(config, registeredRuntimes) {
   if (engine.claudeBareMode === true) {
     const ccCli = resolveCcCli(engine);
     let ccRuntime = null;
-    try { ccRuntime = require('./runtimes').resolveRuntime(ccCli); } catch { /* unknown runtime — skip */ }
+    try { ccRuntime = require('../runtimes').resolveRuntime(ccCli); } catch { /* unknown runtime — skip */ }
     if (ccRuntime?.capabilities?.bareMode === true && !(engine.ccSystemPrompt !== undefined && engine.ccSystemPrompt !== null && engine.ccSystemPrompt !== '')) {
       warnings.push({
         id: 'bare-mode-misconfig',
@@ -4526,6 +4864,182 @@ const WORKTREE_REQUIRING_TYPES = new Set([
   WORK_TYPE.DOCS,
 ]);
 
+// ── Execution surface (W-ms5tb6ha016fda10) ──────────────────────────────────
+//
+// Some scheduled/maintenance work has NOTHING to do with a repository
+// checkout: "merge approved PRs", "sweep the PR tracker", "one-time review
+// external PRs", "CI health check". Its entire contract is Minions dashboard
+// API calls plus external CLIs (`gh`, `az`). Historically those still ran as
+// `setup`/`explore` dispatches, so the engine allocated a full project
+// worktree for them — pure cost, and worse: concurrent fresh-worktree
+// preparation raced on `refs/remotes/origin/<main>` and failed jobs that never
+// needed a checkout at all.
+//
+// `meta.executionSurface` makes that EXPLICIT rather than inferred. There is
+// deliberately no prose sniffing ("does the description mention curl?") — the
+// operator/schedule declares the surface as structured data and the engine
+// validates it fail-closed:
+//
+//   'repo'          (default) — today's behavior: worktree / live checkout.
+//   'control-plane'           — no repository checkout is allocated at all.
+//                               cwd is MINIONS_DIR; project context is still
+//                               carried in the prompt.
+//   'cloud'                   — the work is handed to a REMOTE coding agent
+//                               (Agency / Copilot cloud). No local checkout,
+//                               no local process: the remote agent owns its
+//                               own workspace and produces a PR that Minions
+//                               then adopts into its normal PR record and
+//                               review/fix loops.
+//
+// Fail-closed by construction: the opt-in is an ALLOWLIST of work types
+// (`CONTROL_PLANE_ELIGIBLE_TYPES`), not a denylist. A repo-mutating type
+// (fix/implement/review/test/verify/decompose/docs/build-fix-complex) can
+// never declare control-plane, and an unknown surface string is rejected
+// rather than defaulted. `cloud` carries its own, separate allowlist
+// (`CLOUD_ELIGIBLE_TYPES`) because its eligibility question is the inverse
+// one — not "can this run without a checkout?" but "does this produce a PR a
+// remote agent can author?".
+const EXECUTION_SURFACE = {
+  REPO: 'repo',
+  CONTROL_PLANE: 'control-plane',
+  CLOUD: 'cloud',
+};
+const EXECUTION_SURFACE_VALUES = Object.freeze(Object.values(EXECUTION_SURFACE));
+
+// Only these types may declare `control-plane`. Every one of them is a type
+// that never creates a branch, never commits, and never opens a PR, so
+// removing its checkout cannot silently change what the dispatch produces.
+// `setup` is the important entry: the built-in maintenance schedules use it.
+const CONTROL_PLANE_ELIGIBLE_TYPES = new Set([
+  WORK_TYPE.SETUP,
+  WORK_TYPE.ASK,
+  WORK_TYPE.EXPLORE,
+  WORK_TYPE.MEETING,
+]);
+
+function isControlPlaneEligibleType(type) {
+  return CONTROL_PLANE_ELIGIBLE_TYPES.has(String(type || '').trim().toLowerCase());
+}
+
+// Only these types may declare `cloud`. A cloud dispatch is a hand-off: Minions
+// renders the same playbook prompt it would have given a local agent, ships it
+// to a remote coding agent, and adopts the PR that comes back. That only makes
+// sense for types whose deliverable IS a pull request against a single repo.
+//
+// Deliberately excluded, and why:
+//   review / verify        — their job is to build, run tests, and inspect a
+//                            checkout; a remote agent that cannot run the local
+//                            validation build produces a worse review, not a
+//                            cheaper one.
+//   build-fix-complex      — needs live CI logs and the PR's own branch.
+//   decompose              — pure planning; it mutates Minions state, not a repo.
+//   implement:large        — decomposed into child items first; the CHILDREN are
+//                            what may go to the cloud.
+//   setup                  — produces no PR and usually drives local processes
+//                            (managed_spawn), which a remote agent cannot leave
+//                            running on this machine.
+//   ask / explore / meeting — read-only; their value is the output text, which
+//                            the cloud surface does not stream back.
+const CLOUD_ELIGIBLE_TYPES = new Set([
+  WORK_TYPE.IMPLEMENT,
+  WORK_TYPE.FIX,
+  WORK_TYPE.TEST,
+  WORK_TYPE.DOCS,
+]);
+
+function isCloudEligibleType(type) {
+  return CLOUD_ELIGIBLE_TYPES.has(String(type || '').trim().toLowerCase());
+}
+
+/**
+ * Validate a declared execution surface against the work type.
+ *
+ * @returns {{valid: true, value: string}|{valid: false, error: string, code: string}}
+ *   Unset/empty normalizes to EXECUTION_SURFACE.REPO (back-compat default).
+ */
+function validateExecutionSurface(value, type) {
+  if (value === undefined || value === null) return { valid: true, value: EXECUTION_SURFACE.REPO };
+  if (typeof value !== 'string') {
+    return {
+      valid: false,
+      code: 'invalid-execution-surface',
+      error: `meta.executionSurface must be a string (got ${typeof value})`,
+    };
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return { valid: true, value: EXECUTION_SURFACE.REPO };
+  if (!EXECUTION_SURFACE_VALUES.includes(normalized)) {
+    return {
+      valid: false,
+      code: 'invalid-execution-surface',
+      error: `meta.executionSurface must be one of ${EXECUTION_SURFACE_VALUES.join(', ')} (got "${value}")`,
+    };
+  }
+  if (normalized === EXECUTION_SURFACE.CONTROL_PLANE && !isControlPlaneEligibleType(type)) {
+    return {
+      valid: false,
+      code: 'invalid-execution-surface',
+      error: `work type "${type}" may not declare meta.executionSurface "control-plane" — `
+        + `it reads or mutates repository files and requires a checkout. `
+        + `Eligible types: ${[...CONTROL_PLANE_ELIGIBLE_TYPES].sort().join(', ')}.`,
+    };
+  }
+  if (normalized === EXECUTION_SURFACE.CLOUD && !isCloudEligibleType(type)) {
+    return {
+      valid: false,
+      code: 'invalid-execution-surface',
+      error: `work type "${type}" may not declare meta.executionSurface "cloud" — `
+        + `a cloud dispatch hands the task to a remote coding agent and adopts the pull `
+        + `request it authors, so only PR-producing types qualify. `
+        + `Eligible types: ${[...CLOUD_ELIGIBLE_TYPES].sort().join(', ')}.`,
+    };
+  }
+  return { valid: true, value: normalized };
+}
+
+/**
+ * Read the declared surface off a work item (`meta.executionSurface`, with the
+ * top-level `executionSurface` accepted for ad-hoc dispatch payloads). Returns
+ * the RAW declared value so callers can run `validateExecutionSurface` and
+ * surface a precise rejection; use `isControlPlaneExecution` when you only need
+ * the fail-closed boolean.
+ */
+function readDeclaredExecutionSurface(item) {
+  if (!item || typeof item !== 'object') return undefined;
+  const fromMeta = item.meta && typeof item.meta === 'object' ? item.meta.executionSurface : undefined;
+  return fromMeta !== undefined ? fromMeta : item.executionSurface;
+}
+
+/**
+ * Fail-closed predicate: true ONLY when the item explicitly and validly
+ * declares control-plane for an eligible type. Any invalid, unknown, or
+ * ineligible declaration returns false, so a malformed opt-in degrades to a
+ * normal repo dispatch rather than silently skipping the checkout.
+ */
+function isControlPlaneExecution(item, type) {
+  const declared = readDeclaredExecutionSurface(item);
+  if (declared === undefined || declared === null) return false;
+  const resolvedType = type !== undefined && type !== null ? type : item?.type;
+  const result = validateExecutionSurface(declared, resolvedType);
+  return result.valid && result.value === EXECUTION_SURFACE.CONTROL_PLANE;
+}
+
+/**
+ * Fail-closed predicate: true ONLY when the item explicitly and validly
+ * declares the `cloud` surface for an eligible type. Any invalid, unknown, or
+ * ineligible declaration returns false, so a malformed opt-in degrades to a
+ * normal local repo dispatch rather than silently shipping the work to a
+ * remote agent (the strictly safer default — local dispatch is the behavior
+ * every existing work item already has).
+ */
+function isCloudExecution(item, type) {
+  const declared = readDeclaredExecutionSurface(item);
+  if (declared === undefined || declared === null) return false;
+  const resolvedType = type !== undefined && type !== null ? type : item?.type;
+  const result = validateExecutionSurface(declared, resolvedType);
+  return result.valid && result.value === EXECUTION_SURFACE.CLOUD;
+}
+
 // Hybrid routing is meaningful only for work types that would otherwise need
 // an isolated project worktree. Read-only root tasks already run from the
 // project/root path and therefore gain nothing from a live-validation entry.
@@ -4613,15 +5127,266 @@ const PLAN_STATUS = {
 };
 const PRD_ITEM_STATUS = { MISSING: 'missing', UPDATED: 'updated', DONE: 'done' };
 const PRD_MATERIALIZABLE = new Set([PRD_ITEM_STATUS.MISSING, PRD_ITEM_STATUS.UPDATED]);
+
+// ── PRD revision lifecycle (W-msa0mrus00mh466f) ──────────────────────────────
+// `revision-requested` (an agent is actively rewriting the PRD) and `planStale`
+// (the source markdown changed under an existing PRD) are two DIFFERENT recovery
+// paths that could previously be true at the same time, so the dashboard offered
+// "Regenerate PRD" / "Resume as-is" while a revision agent was already in flight.
+// These helpers are the single place that derivation happens: the dashboard
+// renders what the server returns and never re-derives it.
+const PRD_REVISION_STATE = {
+  NONE: 'none',
+  IN_PROGRESS: 'in-progress',
+  FAILED: 'failed',
+};
+// A revision operation still owns the PRD while its work item can make progress.
+// Anything outside this set is terminal, so the PRD needs an explicit recovery
+// state rather than a permanent "revision in progress".
+const PRD_REVISION_ACTIVE_WI_STATUSES = new Set([
+  WI_STATUS.PENDING, WI_STATUS.DISPATCHED, WI_STATUS.QUEUED, WI_STATUS.PAUSED,
+]);
+
+/**
+ * Resolve the work item backing a PRD's revision request.
+ *
+ * Primary key is the `revisionWorkItemId` pointer persisted on the PRD. The
+ * reverse `_revisionForPrd` stamp on the work item is the fallback so a PRD
+ * whose pointer write raced (or predates the pointer) still correlates to its
+ * operation — never by matching title text.
+ *
+ * @param {object|null} plan       PRD object
+ * @param {string} prdFile         PRD filename (e.g. `foo-2026-08-01.json`)
+ * @param {Array<object>} workItems Work items to search (central scope)
+ * @returns {object|null}
+ */
+function findPrdRevisionWorkItem(plan, prdFile, workItems) {
+  const items = Array.isArray(workItems) ? workItems : [];
+  const pinnedId = (plan && typeof plan === 'object') ? String(plan.revisionWorkItemId || '').trim() : '';
+  if (pinnedId) {
+    const byId = items.find(w => w && w.id === pinnedId);
+    if (byId) return byId;
+  }
+  const file = String(prdFile || '').trim();
+  if (!file) return null;
+  let fallback = null;
+  for (const w of items) {
+    if (!w || w.type !== WORK_TYPE.PLAN_TO_PRD || w._revisionForPrd !== file) continue;
+    if (PRD_REVISION_ACTIVE_WI_STATUSES.has(w.status)) return w;
+    if (!fallback || String(w.created || '') > String(fallback.created || '')) fallback = w;
+  }
+  return fallback;
+}
+
+/**
+ * Canonical revision state for a PRD. Pure — callers resolve the work item with
+ * `findPrdRevisionWorkItem` first.
+ *
+ * @param {object|null} plan
+ * @param {object|null} workItem
+ * @returns {{state:string, active:boolean, workItemId:string, workItemStatus:string,
+ *            requestedAt:string, requestedBy:string, feedback:string, failReason:string}}
+ */
+function derivePrdRevisionState(plan, workItem) {
+  const out = {
+    state: PRD_REVISION_STATE.NONE, active: false,
+    workItemId: '', workItemStatus: '',
+    requestedAt: '', requestedBy: '', feedback: '', failReason: '',
+  };
+  if (!plan || typeof plan !== 'object') return out;
+  if (plan.status !== PLAN_STATUS.REVISION_REQUESTED) return out;
+  out.requestedAt = plan.revisionRequestedAt || '';
+  out.requestedBy = plan.revisionRequestedBy || '';
+  out.feedback = plan.revision_feedback || '';
+  const wi = (workItem && typeof workItem === 'object') ? workItem : null;
+  out.workItemId = String((wi && wi.id) || plan.revisionWorkItemId || '').trim();
+  if (!wi) {
+    // No operation backs the request. Surface it as recoverable instead of
+    // pinning a permanent, misleading "in progress".
+    out.state = PRD_REVISION_STATE.FAILED;
+    out.failReason = 'Revision work item not found';
+    return out;
+  }
+  out.workItemStatus = String(wi.status || '');
+  if (PRD_REVISION_ACTIVE_WI_STATUSES.has(wi.status)) {
+    out.state = PRD_REVISION_STATE.IN_PROGRESS;
+    out.active = true;
+    return out;
+  }
+  out.state = PRD_REVISION_STATE.FAILED;
+  out.failReason = wi.failReason
+    || (DONE_STATUSES.has(wi.status)
+      ? 'Revision agent finished without updating this PRD'
+      : `Revision work item ended as "${out.workItemStatus || 'unknown'}"`);
+  return out;
+}
+
+/**
+ * Operator feedback to inject into a revision dispatch's prompt.
+ *
+ * A revision run is a plan-to-prd run whose ONLY distinguishing input is the
+ * operator's feedback, so that text has to reach the agent explicitly. 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 real source markdown closed that accident, and
+ * `plan-to-prd.md` has no `{{task_description}}` token, so the feedback needs
+ * its own channel.
+ *
+ * The PRD is the single source of truth for the feedback (`handlePlansRevise`
+ * writes it, `applyPrdRevisionCompletion` clears it), which also keeps a retry
+ * that reuses the same work item from rendering superseded text.
+ *
+ * Gated on the structural `_revisionForPrd` ⇄ resolved-PRD-filename relation —
+ * never title text — so a plain regeneration cannot pick up feedback left on a
+ * PRD by an earlier failed revision.
+ *
+ * @param {object|null} workItem  plan-to-prd work item being dispatched
+ * @param {object|null} prd       PRD the engine resolved for this dispatch
+ * @param {string} prdFile        filename of that resolved PRD
+ * @returns {string} feedback text, or '' when this is not a revision dispatch
+ */
+function resolvePrdRevisionFeedback(workItem, prd, prdFile) {
+  if (!workItem || typeof workItem !== 'object') return '';
+  if (!prd || typeof prd !== 'object' || Array.isArray(prd)) return '';
+  const target = String(workItem._revisionForPrd || '').trim();
+  const resolved = String(prdFile || '').trim();
+  if (!target || target !== resolved) return '';
+  return String(prd.revision_feedback || '').trim();
+}
+
+/**
+ * Normalize an imported revision PRD so the completed revision and the stale
+ * recovery controls can never be observed together: status returns to
+ * awaiting-approval, staleness is cleared, the source-plan sync fields are
+ * re-baselined against the live markdown, and the revision pointers are dropped.
+ *
+ * Returns a NEW object so the caller can persist it in a single store write.
+ *
+ * @param {object} prd                 PRD produced by the revision agent
+ * @param {{plansDir?:string, previous?:object}} [opts]
+ * @returns {object}
+ */
+function applyPrdRevisionCompletion(prd, { plansDir, previous } = {}) {
+  if (!prd || typeof prd !== 'object' || Array.isArray(prd)) {
+    throw new TypeError('applyPrdRevisionCompletion requires a PRD object');
+  }
+  const next = { ...prd };
+  if (!next.source_plan && previous && previous.source_plan) next.source_plan = previous.source_plan;
+  next.status = PLAN_STATUS.AWAITING_APPROVAL;
+  const now = new Date().toISOString();
+  next.revisionCompletedAt = now;
+  next.lastSyncedFromPlan = now;
+  delete next.planStale;
+  delete next.revision_feedback;
+  delete next.revisionRequestedAt;
+  delete next.revisionRequestedBy;
+  delete next.revisionWorkItemId;
+  // Approval was granted for the pre-revision content — it does not carry over.
+  delete next.approvedAt;
+  delete next.approvedBy;
+  const resolved = next.source_plan ? resolveSourcePlanPath(plansDir, next.source_plan) : null;
+  if (resolved) {
+    const hash = computeSourcePlanContentHash(resolved);
+    if (hash) next._sourcePlanContentHash = hash;
+    try {
+      next.sourcePlanModifiedAt = new Date(Math.floor(fs.statSync(resolved).mtimeMs)).toISOString();
+    } catch { /* markdown may have been archived/removed — keep the recorded baseline */ }
+  }
+  return next;
+}
+
 const PR_STATUS = { ACTIVE: 'active', MERGED: 'merged', ABANDONED: 'abandoned', CLOSED: 'closed', LINKED: 'linked' };
 // PRs eligible for polling (status/build/comment checks) — excludes terminal statuses
 const PR_POLLABLE_STATUSES = new Set([PR_STATUS.ACTIVE, PR_STATUS.LINKED]);
+
+// ─── Bounded re-probe of abandoned PRs (W-msav5edk00g81710) ─────────────────
+//
+// `abandoned` is the one terminal status a PR can legitimately leave: both
+// GitHub and ADO allow reopening a closed PR. Filtering the poll loop on
+// PR_POLLABLE_STATUSES alone made the stamp a one-way door — the reopen handler
+// in engine/providers/github.js and engine/ado/index.js (P-f5reopenreset) was
+// unreachable because the record never got polled again, and the only un-flip
+// path was a boot-only, version-gated reconciliation pass.
+//
+// The seam below is the fix: an abandoned record stays pollable for a bounded
+// window measured from when it was abandoned, so the HOST gets to un-flip it.
+// Every caller funnels through `isPrPollable` so the two providers cannot drift.
+
+/** Operator override for the bounded window; honors a literal 0 (disable). */
+function resolveAbandonedPrRepollWindowMs(config) {
+  const raw = config?.engine?.abandonedPrRepollWindowMs;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= 0) return n;
+  return ENGINE_DEFAULTS.abandonedPrRepollWindowMs;
+}
+
+/**
+ * Instant (ms) a record entered `abandoned`, or null when unknown.
+ * `_abandonedAt` is stamped at every abandon site; `closedAt` is the fallback
+ * for records stamped before this WI shipped (the 404 trapdoor never set it).
+ */
+function getPrAbandonedAtMs(pr) {
+  for (const raw of [pr?._abandonedAt, pr?.closedAt]) {
+    if (!raw) continue;
+    const parsed = Date.parse(raw);
+    if (!Number.isNaN(parsed)) return parsed;
+  }
+  return null;
+}
+
+/**
+ * Single pollability predicate for both PR pollers.
+ *
+ * @param {object} pr
+ * @param {object} [options]
+ * @param {number} [options.windowMs] — bounded abandoned re-probe window. Defaults
+ *   to 0 (strict PR_POLLABLE_STATUSES) so widening is an explicit per-call-site
+ *   opt-in: only the STATUS poll needs the reopen signal, never the comment poll.
+ * @param {number} [options.now]
+ */
+function isPrPollable(pr, options = {}) {
+  if (!pr || typeof pr !== 'object') return false;
+  if (PR_POLLABLE_STATUSES.has(pr.status)) return true;
+  if (pr.status !== PR_STATUS.ABANDONED) return false;
+
+  const windowMs = Number(options.windowMs) || 0;
+  if (!(windowMs > 0)) return false;
+  // Already proven gone at the host — re-probing a deleted PR is pure waste.
+  if (pr._reconciliation404Confirmed) return false;
+
+  const abandonedAt = getPrAbandonedAtMs(pr);
+  // Fail CLOSED: without an anchor the age is unbounded, and an unbounded age
+  // would turn a bounded window into unbounded re-probing of every historical
+  // record. Those are healed by the version-gated startup pass instead.
+  if (abandonedAt === null) return false;
+
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  return (now - abandonedAt) <= windowMs;
+}
+
+/** Stamp the anchor the re-probe window is measured from. Returns true if changed. */
+function stampPrAbandonedAt(pr, at) {
+  if (!pr || typeof pr !== 'object') return false;
+  const iso = at || new Date().toISOString();
+  if (pr._abandonedAt === iso) return false;
+  pr._abandonedAt = iso;
+  return true;
+}
+
+/** Drop the anchor when a record leaves `abandoned`. Returns true if changed. */
+function clearPrAbandonedAt(pr) {
+  if (!pr || typeof pr !== 'object') return false;
+  if (!Object.prototype.hasOwnProperty.call(pr, '_abandonedAt')) return false;
+  delete pr._abandonedAt;
+  return true;
+}
 const PR_PENDING_REASON = {
   MISSING_BRANCH: 'missing_pr_branch',
 };
 // PR build-status enum — single source of truth for the literal strings written to
-// PR `buildStatus`. Previously drifted across engine/ado.js,
-// engine/github.js, engine/lifecycle.js, engine/watches.js, engine/queries.js, engine/cli.js
+// PR `buildStatus`. Previously drifted across engine/ado/index.js,
+// engine/providers/github.js, engine/orchestration/lifecycle.js, engine/watches/index.js, engine/core/queries.js, engine/operations/cli.js
 // (P-bfa3d-constants-eslint, audit items #68-#82).
 const BUILD_STATUS = {
   PASSING: 'passing',
@@ -4630,8 +5395,8 @@ const BUILD_STATUS = {
   NONE: 'none',
 };
 // PR review-status enum — single source of truth for the literal strings written to
-// PR `reviewStatus`. Previously drifted across engine/ado.js,
-// engine/github.js, engine/lifecycle.js, engine/watches.js, engine/queries.js, engine/cli.js
+// PR `reviewStatus`. Previously drifted across engine/ado/index.js,
+// engine/providers/github.js, engine/orchestration/lifecycle.js, engine/watches/index.js, engine/core/queries.js, engine/operations/cli.js
 // (P-bfa3d-constants-eslint, audit items #68-#82).
 const REVIEW_STATUS = {
   APPROVED: 'approved',
@@ -4644,15 +5409,15 @@ const REVIEW_STATUS = {
 // the migrated sites read self-documentingly and drift is grep-able.
 // (P-bfa3d-constants-eslint, audit items #68-#82).
 const FETCH_TIMEOUT_MS = {
-  ADO_API: 4000,        // engine/ado.js — ADO REST API single-shot fetches
-  GH_CLI: 15000,        // engine/github.js, engine/lifecycle.js — `gh pr/api` shell-outs
-  GH_COMMENT: 30000,    // engine/gh-comment.js — comment/review posts (slower endpoint)
+  ADO_API: 4000,        // engine/ado/index.js — ADO REST API single-shot fetches
+  GH_CLI: 15000,        // engine/providers/github.js, engine/orchestration/lifecycle.js — `gh pr/api` shell-outs
+  GH_COMMENT: 30000,    // engine/providers/gh-comment.js — comment/review posts (slower endpoint)
 };
-// Retry delay between auto-link fallback attempts in engine/lifecycle.js#resolvePrLinkFallback.
+// Retry delay between auto-link fallback attempts in engine/orchestration/lifecycle.js#resolvePrLinkFallback.
 // Previously a bare `3000` magic number; named so the cadence is grep-able and consistent
 // if other retry paths need the same backoff. (P-bfa3d-constants-eslint).
 const RETRY_DELAY_MS = 3000;
-// Max retries for ADO token-refresh inside engine/ado.js#adoFetch.
+// Max retries for ADO token-refresh inside engine/ado/index.js#adoFetch.
 // Distinct from ENGINE_DEFAULTS.maxRetries (dispatch-level cap) — this is the
 // per-request token-refresh ceiling and is intentionally separate.
 // (P-bfa3d-constants-eslint).
@@ -4664,7 +5429,7 @@ const WATCH_STATUS = { ACTIVE: 'active', PAUSED: 'paused', TRIGGERED: 'triggered
 // engine/watches.registerTargetType — this object lists the types shipped in
 // the engine for use in switch statements and constants comparisons. The
 // actual allowlist for createWatch/dashboard validation is the registry in
-// engine/watches.js (see getTargetTypes()).
+// engine/watches/index.js (see getTargetTypes()).
 const WATCH_TARGET_TYPE = {
   PR: 'pr',
   WORK_ITEM: 'work-item',
@@ -4695,14 +5460,14 @@ const WATCH_CONDITION = {
   DISABLED: 'disabled',             // schedule disabled
   ACTIVITY_CHANGE: 'activity-change', // agent transitioned status (e.g. idle → working)
   // ── P-w4e2f6a1 — Phase 2.1: PR predicate conditions ──────────────────────
-  // See engine/watches.js PR target type for trigger semantics.
+  // See engine/watches/index.js PR target type for trigger semantics.
   HEAD_COMMIT_CHANGE: 'head-commit-change', // PR headRefOid advanced (new push)
   MERGEABLE_FLIPPED: 'mergeable-flipped',   // mergeable transitioned between true↔false (NOT involving null)
   READY_FOR_MERGE: 'ready-for-merge',       // canonical compound: active+approved+passing+mergeable+!draft
   BEHIND_MASTER: 'behind-master',           // pr.behindBy > 0 (treats null/undefined as not-behind)
   DRAFT_FLIPPED: 'draft-flipped',           // isDraft transitioned between true↔false
   // ── P-w5b8d2c9 — Phase 2.2: work-item / plan / pipeline predicates ───────
-  // See engine/watches.js for trigger semantics. Counters (_unchangedTicks,
+  // See engine/watches/index.js for trigger semantics. Counters (_unchangedTicks,
   // _stuckStageTicks) are computed inside captureState by comparing the
   // freshly-captured snapshot against prevState — see _captureState which
   // now passes prevState as the 2nd arg.
@@ -4740,7 +5505,7 @@ const WATCH_ABSOLUTE_CONDITIONS = new Set([
   WATCH_CONDITION.ITEM_FAILED_N_TIMES,
 ]);
 // Built-in follow-up action types invoked by the engine when a watch fires.
-// The action registry in engine/watch-actions.js is the source of truth; these
+// The action registry in engine/watches/actions.js is the source of truth; these
 // constants exist so engine/dashboard code can reference action keys without
 // magic strings. New action types can be registered at runtime via
 // registerActionType() — unknown keys here are fine if registered elsewhere.
@@ -4772,10 +5537,10 @@ const WATCH_ACTION_TYPE = {
  */
 function _smallStateMutator({ applyMutation, topic }) {
   return (mutator) => {
-    const store = require('./small-state-store');
+    const store = require('../persistence/small-state-store');
     const { wrote, result } = store[applyMutation]((obj) => mutator(obj) || obj);
     if (wrote) {
-      try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+      try { require('../persistence/db-events').emitStateEvent(topic); } catch { /* optional */ }
     }
     return result;
   };
@@ -4808,13 +5573,13 @@ const mutateWorktreePool = _smallStateMutator({
 /** Route QA array mutations through their SQL stores. */
 function _qaMutator({ applyMutation, topic }) {
   return (mutator) => {
-    const store = require('./small-state-store');
+    const store = require('../persistence/small-state-store');
     const { wrote, result } = store[applyMutation]((arr) => {
       if (!Array.isArray(arr)) arr = [];
       return mutator(arr) || arr;
     });
     if (wrote) {
-      try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+      try { require('../persistence/db-events').emitStateEvent(topic); } catch { /* optional */ }
     }
     return result;
   };
@@ -4837,26 +5602,26 @@ const mutateQaSessions = _qaMutator({
  * diffs by id. SQL-canonical (Phase 9.4); SQLite failures propagate.
  */
 function mutateWatches(mutator) {
-  const store = require('./watches-store');
+  const store = require('../watches/store');
   const { wrote, result } = store.applyWatchesMutation((arr) => {
     if (!Array.isArray(arr)) arr = [];
     return mutator(arr) || arr;
   });
   if (wrote) {
-    try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
+    try { require('../persistence/db-events').emitStateEvent('watches'); } catch { /* optional */ }
   }
   return result;
 }
 
 /** Route a metrics object mutation through the SQL store. */
 function mutateMetrics(mutator) {
-  const store = require('./metrics-store');
+  const store = require('../observability/metrics-store');
   const { wrote, result } = store.applyMetricsMutation((m) => {
     if (!m || typeof m !== 'object') m = {};
     return mutator(m) || m;
   });
   if (wrote) {
-    try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
+    try { require('../persistence/db-events').emitStateEvent('metrics'); } catch { /* optional */ }
   }
   return result;
 }
@@ -5004,6 +5769,7 @@ const FAILURE_CLASS = {
   MERGE_CONFLICT: 'merge-conflict',       // Git merge conflict in worktree or dependency
   BUILD_FAILURE: 'build-failure',         // Compilation, lint, or test failure
   TIMEOUT: 'timeout',                     // Hard runtime timeout or stale-orphan timeout
+  ENGINE_RESTART: 'engine-restart',       // Dispatch process ownership was lost across an engine restart; use the infrastructure retry budget
   EMPTY_OUTPUT: 'empty-output',           // Agent produced no meaningful output
   SPAWN_ERROR: 'spawn-error',             // Process failed to start or crashed immediately
   NETWORK_ERROR: 'network-error',         // API rate limit, DNS, connectivity
@@ -5031,6 +5797,9 @@ const FAILURE_CLASS = {
   LIVE_CHECKOUT_STALE_BASE: 'live-checkout-stale-base', // W-mr98op8w000ma4ad (live-checkout dispatch mode, STALE-BASE GUARD): spawnAgent was about to fork a NEW branch off the operator's current HEAD while HEAD sits on the project base ref (mainRef), but the LOCAL mainRef tip has DIVERGED from origin/<mainRef> with unpushed commit(s) (`git rev-list --count origin/<mainRef>..<mainRef>` > 0). Forking would silently inherit that COMMITTED contamination into the new branch and its PR — the exact scope-contamination class first seen on ADO PR 5411214 and recurring on AB#12016662 / ADO PR 5419146. Survives the dirty check (contamination is committed, not uncommitted) and cannot be caught by a headBranch !== mainRef check (headBranch IS mainRef here). Detected WITHOUT a fetch (issue #226) via the existing origin/<mainRef> remote-tracking ref. Distinct from LIVE_CHECKOUT_FAILED (transient) because the contaminated local base does NOT change on retry — it reproduces identically until a human reconciles the local base branch. Non-retryable — the engine NEVER resets/cleans the operator's local mainRef; the operator must reconcile it (push/reset/rebase their own way), then re-dispatch. The guard SKIPS (proceeds normally) when HEAD is not on mainRef, when no local origin/<mainRef> ref exists (local-only/no-remote repo), or when the divergence count cannot be computed.
   LIVE_CHECKOUT_WRONG_BASE: 'live-checkout-wrong-base', // W-mr3lunnq000o9f41 (live-checkout dispatch mode): a NEW-branch fork was requested but the operator's checkout HEAD is on an unrelated topic/feature branch, NOT the project base (mainRef), and prepareLiveCheckout could not switch to a LOCAL base ref (no `refs/heads/<mainRef>`, or the local checkout itself failed). Forking off the stale HEAD would silently bake every commit already on that branch into the new branch AND its PR — committed-history scope contamination that survives the dirty/mid-operation preflights (the ADO PR 5411214 incident: ~22 unrelated OCM files, author-disavowed). The engine never fetches origin/<mainRef> in live mode (issue #226) so it cannot self-heal a missing local base. Non-retryable — the operator must `git checkout <mainRef>` in the operator checkout before re-dispatch. Does NOT fire for PR-targeted fixes or shared-branch continuations (those pass allowNonMainBase, intentionally continuing a non-main branch), nor when HEAD is already on mainRef, nor when a local mainRef ref exists (the guard switches to it and forks cleanly). OPT-IN AUTO-RECOVERY (`liveCheckoutAutoBaseRepair`, per-project > fleet-wide, default OFF): when enabled AND a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local `<mainRef>` branch from it (a LOCAL ref op — still no `git fetch`, issue #226 preserved; origin/<mainRef> IS the base so no contamination) and forks cleanly instead of failing — eliminating the manual `git checkout <mainRef>` step. Still fails closed when neither a local base nor an origin-tracking base ref exists, or when the base checkout itself fails/hangs.
   INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
+  INVALID_EXECUTION_SURFACE: 'invalid-execution-surface', // W-ms5tb6ha016fda10: the dispatch declared `meta.executionSurface` that failed fail-closed validation — an unknown surface string, a non-string value, `control-plane` on a work type that reads/mutates repository files (fix/implement/review/test/verify/decompose/docs/build-fix-complex), or `cloud` on a work type whose deliverable is not a pull request (review/verify/explore/ask/setup/decompose/build-fix-complex). Each surface's opt-in is an ALLOWLIST (shared.CONTROL_PLANE_ELIGIBLE_TYPES / shared.CLOUD_ELIGIBLE_TYPES), never inferred from prose, so a repo-mutating task can never silently lose its checkout and a validation task can never silently be shipped to a remote agent that cannot build it. Non-retryable — the operator must fix or remove the field before re-dispatch.
+  CLOUD_PROVIDER_UNAVAILABLE: 'cloud-provider-unavailable', // Cloud dispatch surface: the work item validly declared `meta.executionSurface: "cloud"` but no usable cloud provider could be resolved — the id is not registered, the provider is registered but reports `isConfigured() === false` for this project (missing credentials, no repo binding, disabled in config), or provider resolution threw. Structural, NOT connectivity: retrying the same dispatch reproduces it identically until an operator configures the provider or removes the surface declaration. Non-retryable. Deliberately distinct from a provider call that reached the service and failed — that is a session-level failure classified by the provider, not this.
+  GIT_REF_LOCK: 'git-ref-lock',           // W-ms5tb6ha016fda10: `git fetch` lost a LOCAL ref-lock race on a shared remote-tracking ref (`cannot lock ref 'refs/remotes/origin/<main>': is at <sha> but expected <sha>`) — two dispatches preparing fresh worktrees in the SAME clone at the same time, or an operator/dashboard git command racing the daemon. This is a local serialization defect, NOT connectivity: classifying it as NETWORK_ERROR hid the real cause and burned retries. In-process races are removed at the source by shared.withSerializedRemoteRefRefresh; this class covers the residual cross-process case. Retryable — the ref lock clears in seconds.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).
   WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.
   WORKSPACE_MANIFEST_TOOL: 'workspace-manifest-tool-forbidden', // W-mq07avbk000m5543: out-of-scope tool call (manifest enforcement at the runtime gate). Non-retryable as-is.
@@ -5095,6 +5864,44 @@ function resolveTerminalWorkerState({ code, effectiveResult, errorReason } = {})
   };
 }
 
+// W-ms9tcs3o01y03383 — how a dispatch reached its terminal state. Persisted on
+// the completed dispatch record so "finished normally", "recovered from a
+// durable report" and "a live resume genuinely stalled" are distinguishable
+// after the fact instead of all reading as a plain success/timeout.
+const DISPATCH_COMPLETION_PATH = {
+  // The tracked process closed and the normal close handler finalized it.
+  PROCESS_CLOSE: 'process-close',
+  // The process had provably exited and a dispatch-owned completion report was
+  // already on disk, so the close handler skipped queued resume bookkeeping and
+  // finalized straight away.
+  REPORT_RECOVERY_IMMEDIATE: 'report-recovery-immediate',
+  // The engine lost/never had the close event and recovered the outcome from
+  // the [process-exit] sentinel in live-output.log (restart reattachment).
+  OUTPUT_DETECTION: 'output-detection',
+  // A still-live resumed runtime blew its first-output heartbeat budget, but a
+  // dispatch-owned report proved the turn had already succeeded.
+  RESUME_STALL_REPORT: 'resume-stall-report',
+  // A still-live resumed runtime blew its heartbeat budget with no report.
+  RESUME_STALL_TIMEOUT: 'resume-stall-timeout',
+};
+
+// W-ms9tcs3o01y03383 — the completion-report trust boundary, expressed once.
+//
+// A completion report is only evidence about THIS dispatch when it echoes the
+// per-spawn nonce the engine minted (and carries across steering resumes). This
+// is the pure half of the check — callers supply the parsed report, so the same
+// decision is made by the close handler, the resume-stall watchdog, and the
+// output-detection recovery path without any of them re-deriving the rule.
+//
+// Deliberately fails closed: no expected nonce, no report, or a
+// missing/non-matching `nonce` field all return null.
+function acceptCompletionReportForNonce(report, expectedNonce) {
+  if (!expectedNonce || typeof expectedNonce !== 'string') return null;
+  if (!isPlainObject(report)) return null;
+  if (typeof report.nonce !== 'string' || report.nonce !== expectedNonce) return null;
+  return report;
+}
+
 const _dispatchFinalizationOwners = new Map();
 const _dispatchFinalizationWaiters = new Map();
 
@@ -5155,7 +5962,7 @@ const DEFAULT_CLAUDE = {
 
 // Bump rolling-daily strip counter for docs/deprecated.json#prune-default-claude-config
 // removal gate (>=30 consecutive days of zero strips). Best-effort; mirrors
-// engine/cleanup.js:1200-1213 _engine.legacyStatusMigrations.
+// engine/orchestration/cleanup.js:1200-1213 _engine.legacyStatusMigrations.
 function _bumpPruneDefaultClaudeStrip() {
   try {
     const dateKey = new Date().toISOString().slice(0, 10);
@@ -5662,8 +6469,8 @@ function initializeProjectState(project) {
   projectStateDirEnsure(project);
   // SQL scopes need no empty sentinel rows. Touch both stores so migrations
   // and schema validation still happen at project setup time.
-  require('./work-items-store').readWorkItemsForScope(project.name);
-  require('./pull-requests-store').readPullRequestsForScope(project.name);
+  require('../planning/work-items-store').readWorkItemsForScope(project.name);
+  require('../persistence/pull-requests-store').readPullRequestsForScope(project.name);
   return result;
 }
 
@@ -5691,6 +6498,62 @@ function realPathForComparison(filePath) {
   }
 }
 
+/**
+ * Async twin of `realPathForComparison`, for callers that resolve MANY paths on
+ * a latency-sensitive event loop (the dashboard's worktree inventory refresh).
+ * Same missing-path walk, same error contract.
+ *
+ * Consistency rule: resolve every side of a comparison with the SAME twin.
+ * `fs.realpathSync.native` can canonicalize case on a case-insensitive volume
+ * where the promises API does not, so mixing the two could make an
+ * already-resolved path miscompare on macOS.
+ */
+async function realPathForComparisonAsync(filePath) {
+  const resolved = path.resolve(filePath);
+  try {
+    return await fs.promises.realpath(resolved);
+  } catch (err) {
+    if (!err || (err.code !== 'ENOENT' && err.code !== 'ENOTDIR')) throw err;
+  }
+
+  let existing = resolved;
+  const missingParts = [];
+  while (true) {
+    const parent = path.dirname(existing);
+    missingParts.unshift(path.basename(existing));
+    if (parent === existing) return resolved;
+    existing = parent;
+    try {
+      return path.join(await fs.promises.realpath(existing), ...missingParts);
+    } catch (err) {
+      if (!err || (err.code !== 'ENOENT' && err.code !== 'ENOTDIR')) throw err;
+    }
+  }
+}
+
+/**
+ * Run `worker` over `items` with at most `limit` in flight. The engine's
+ * canonical bounded-concurrency mapper — use this instead of adding another
+ * private copy of the promise-pool pattern.
+ */
+async function mapWithConcurrency(items, limit, worker) {
+  const list = Array.isArray(items) ? items : [];
+  if (list.length === 0) return [];
+  const results = new Array(list.length);
+  let next = 0;
+  const runners = Array.from(
+    { length: Math.max(1, Math.min(Number(limit) || 1, list.length)) },
+    async () => {
+      while (next < list.length) {
+        const index = next++;
+        results[index] = await worker(list[index], index);
+      }
+    },
+  );
+  await Promise.all(runners);
+  return results;
+}
+
 // ── ID Generation ────────────────────────────────────────────────────────────
 
 function nextWorkItemId(items, prefix) {
@@ -5864,17 +6727,37 @@ function _xmlEscapeForPrompt(s) {
 }
 
 // Render a list of skills as an <available_skills> XML block matching the
-// shape Copilot CLI's default system prompt injects. When `skills` is empty
-// we still emit the block (with a sentinel comment) so the agent learns the
-// path exists rather than silently inferring nothing's there.
-function buildAvailableSkillsBlock(skills) {
-  const list = Array.isArray(skills) ? skills : [];
+// shape Copilot CLI's default system prompt injects. When both lists are empty
+// we still emit the block (with a sentinel comment naming every source that was
+// searched — user, plugin, and project checkouts) so the agent learns the paths
+// exist rather than silently inferring nothing's there.
+//
+// `skills` are the runtime-native user/plugin skills (from listCopilotSkills).
+// `projectSkills` (optional) are project-embedded skills discovered under the
+// configured project checkouts (incl. deeply-nested `.claude/skills` dirs) so a
+// request like "run my weekly maintenance skill" resolves from the registry
+// instead of an ad-hoc filesystem grep. User/plugin skills win a name collision
+// (mirrors listCopilotSkills' user-wins precedence); each entry may carry a
+// `path` that is rendered as a `<path>` element so the agent can open it directly.
+function buildAvailableSkillsBlock(skills, projectSkills) {
+  const userList = Array.isArray(skills) ? skills : [];
+  const projList = Array.isArray(projectSkills) ? projectSkills : [];
+  const byName = new Map();
+  for (const s of userList) if (s && s.name && !byName.has(s.name)) byName.set(s.name, s);
+  for (const s of projList) if (s && s.name && !byName.has(s.name)) byName.set(s.name, s);
+  const list = Array.from(byName.values());
   if (list.length === 0) {
-    return '<available_skills>\n  <!-- No skills found in ~/.copilot/skills/ or ~/.copilot/installed-plugins/<marketplace>/<plugin>/skills/ -->\n</available_skills>';
-  }
-  const items = list.map(s =>
-    `<skill>\n  <name>${_xmlEscapeForPrompt(s.name)}</name>\n  <description>${_xmlEscapeForPrompt(s.description)}</description>\n  <location>${_xmlEscapeForPrompt(s.location)}</location>\n</skill>`
-  ).join('\n');
+    return '<available_skills>\n  <!-- No skills found in ~/.copilot/skills/, ~/.copilot/installed-plugins/<marketplace>/<plugin>/skills/, or any configured project checkout -->\n</available_skills>';
+  }
+  const items = list.map(s => {
+    const parts = [
+      `  <name>${_xmlEscapeForPrompt(s.name)}</name>`,
+      `  <description>${_xmlEscapeForPrompt(s.description)}</description>`,
+      `  <location>${_xmlEscapeForPrompt(s.location)}</location>`,
+    ];
+    if (s.path) parts.push(`  <path>${_xmlEscapeForPrompt(s.path)}</path>`);
+    return `<skill>\n${parts.join('\n')}\n</skill>`;
+  }).join('\n');
   return `<available_skills>\n${items}\n</available_skills>`;
 }
 
@@ -5893,10 +6776,15 @@ function renderCcSystemPrompt(raw, opts) {
   // Available-skills enumeration walks two directory trees and reads each
   // SKILL.md's frontmatter — only do it when the template asks for it.
   // Tests pass `opts.skillsHomeDir` to redirect the scan at a fixture dir.
+  // `opts.projectSkills` (optional) carries project-embedded skills discovered
+  // under configured project checkouts so they appear in the CC registry
+  // alongside user/plugin skills (the caller computes them from the cached
+  // queries skill inventory — this stays off the /api/status hot path).
   if (out.includes('{{available_skills}}')) {
     const skillsOpts = (opts && typeof opts.skillsHomeDir === 'string')
       ? { homeDir: opts.skillsHomeDir } : undefined;
-    out = out.replace(/\{\{available_skills\}\}/g, buildAvailableSkillsBlock(listCopilotSkills(skillsOpts)));
+    const projectSkills = (opts && Array.isArray(opts.projectSkills)) ? opts.projectSkills : [];
+    out = out.replace(/\{\{available_skills\}\}/g, buildAvailableSkillsBlock(listCopilotSkills(skillsOpts), projectSkills));
   }
   return out
     .replace(/\{\{cc_turn_id\}\}/g, turnId)
@@ -5950,7 +6838,7 @@ function isLiveCommandCenterPath(absPath, opts) {
   if (rel === '' || rel === '.') return false; // root itself is not a "file"
   const relForMatch = rel.toLowerCase();
   if (_CC_PROTECTED_BASENAMES.includes(relForMatch)) return true;
-  if (/^(?:engine|bin)\/[^/]+\.js$/.test(relForMatch)) return true;
+  if (/^engine\/.+\.js$/.test(relForMatch) || /^bin\/[^/]+\.js$/.test(relForMatch)) return true;
   for (const prefix of _CC_PROTECTED_PREFIXES) {
     if (relForMatch === prefix.slice(0, -1) /* exact dir */ || relForMatch.startsWith(prefix)) return true;
   }
@@ -6080,7 +6968,7 @@ function sanitizeBranch(name) {
 // gone from engine.js. PR-targeted dispatches and `shared-branch` plans bypass
 // this helper entirely (they reuse the existing branch).
 //
-// `getOperatorLogin` is a thin shim around `engine/operator-identity` so other
+// `getOperatorLogin` is a thin shim around `engine/core/operator-identity` so other
 // modules don't need a second require. Required lazily to keep shared.js free
 // of side-effecting child_process imports at module load.
 
@@ -6098,6 +6986,18 @@ function deriveWorkItemBranchName(item, config) {
   // `config` are intentionally unused here but retained for callers that
   // may still inspect them.
   void config;
+  // W-ms5tb6ha016fda10 — a validly-declared control-plane item owns no branch:
+  // it never checks out a repository, so stamping `work/<wi-id>` on it would
+  // both mislead the dashboard and put it in the branch mutex, needlessly
+  // serializing maintenance jobs that share nothing. Fail-closed by
+  // construction (isControlPlaneExecution rejects ineligible types), so a
+  // repo-mutating item still derives its branch exactly as before.
+  if (isControlPlaneExecution(item)) return null;
+  // A cloud-dispatched item owns no LOCAL branch either: the remote agent
+  // creates and pushes its own. Stamping `work/<wi-id>` here would put the
+  // item in the local branch mutex (serializing dispatches that share no
+  // checkout) and would advertise a branch that never exists locally.
+  if (isCloudExecution(item)) return null;
   const wid = String(item?.id || '').trim();
   if (!wid) return null;
   return sanitizeBranch(`work/${wid}`);
@@ -6127,7 +7027,7 @@ function buildWorktreeDirName({
   // so the dir name is a single basename. Without this, `path.join(parent,
   // dirName)` creates `parent/work/W-…/` on Linux for a `work/W-…` branch,
   // and `readdirSync(parent)` returns `work` (not the full name) — breaking
-  // engine/worktree-gc.js's globalLiveDirNames lookup and evicting live
+  // engine/worktrees/gc.js's globalLiveDirNames lookup and evicting live
   // worktrees on boot.
   const branchSlug = sanitizeBranch(branchName || 'worktree').replace(/\//g, '-');
   return `${projectSlug}-${branchSlug}-${suffix}`;
@@ -6153,6 +7053,40 @@ function _pathForComparison(filePath) {
   return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
 }
 
+/**
+ * Public name for the comparison form of a path: fully symlink-resolved and
+ * case-folded on Windows. Callers that must compare many paths off the event
+ * loop resolve once with `pathForComparisonAsync` and then compare with
+ * `isResolvedPathInsideOrEqual`, instead of paying a realpath syscall inside
+ * every containment test.
+ */
+function pathForComparison(filePath) {
+  return _pathForComparison(filePath);
+}
+
+async function pathForComparisonAsync(filePath) {
+  const resolved = await realPathForComparisonAsync(String(filePath));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+/**
+ * The containment rule, over paths that are ALREADY in comparison form.
+ *
+ * This is the single definition of "inside or equal" — `isPathInside` and
+ * `isPathInsideOrEqual` both delegate here after normalizing, so a caller that
+ * pre-resolves paths asynchronously applies exactly the same rule and there is
+ * no second copy to drift.
+ */
+function isResolvedPathInsideOrEqual(childAbs, parentAbs) {
+  if (!childAbs || !parentAbs) return false;
+  if (childAbs === parentAbs) return true;
+  const rel = path.relative(parentAbs, childAbs);
+  if (rel === '') return false;
+  if (rel.startsWith('..')) return false;
+  if (path.isAbsolute(rel)) return false;
+  return true;
+}
+
 /**
  * True when `childPath` is strictly nested within `parentPath` (descendant,
  * NOT the same path). Cross-platform via `path.relative`; resilient to mixed
@@ -6163,11 +7097,8 @@ function isPathInside(childPath, parentPath) {
   if (!childPath || !parentPath) return false;
   const childAbs = _pathForComparison(childPath);
   const parentAbs = _pathForComparison(parentPath);
-  const rel = path.relative(parentAbs, childAbs);
-  if (rel === '') return false;
-  if (rel.startsWith('..')) return false;
-  if (path.isAbsolute(rel)) return false;
-  return true;
+  if (childAbs === parentAbs) return false;
+  return isResolvedPathInsideOrEqual(childAbs, parentAbs);
 }
 
 /**
@@ -6182,10 +7113,10 @@ function isPathInside(childPath, parentPath) {
  */
 function isPathInsideOrEqual(childPath, parentPath) {
   if (!childPath || !parentPath) return false;
-  const childAbs = _pathForComparison(childPath);
-  const parentAbs = _pathForComparison(parentPath);
-  if (childAbs === parentAbs) return true;
-  return isPathInside(childAbs, parentAbs);
+  return isResolvedPathInsideOrEqual(
+    _pathForComparison(childPath),
+    _pathForComparison(parentPath),
+  );
 }
 
 function pathsOverlap(firstPath, secondPath) {
@@ -6366,7 +7297,7 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * NOTE (W-mp8ho6w500034a58): Pipeline branches no longer override this.
  * Read-only pipeline stages don't commit, so a `pipeline/...` branch is a
  * meaningless label for them — the dispatcher short-circuits read-only WIs
- * regardless of branch name, and `engine/pipeline.js` now omits the branch
+ * regardless of branch name, and `engine/orchestration/pipeline.js` now omits the branch
  * field for read-only stages. Only code-mutating pipeline stages need a
  * worktree, and they take the normal code-mutating path below.
  *
@@ -6402,8 +7333,9 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * @param {{ localPath?: string|null, checkoutMode?: string|null, worktreeMode?: string|null }|null|undefined} project
  * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
  * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
- * @param {{ workdir?: string|null }} [options] — optional per-WI overrides
- * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, readOnlyWorktree?: boolean, workdir?: string|null }}
+ * @param {{ workdir?: string|null, executionSurface?: string|null }} [options] — optional per-WI overrides
+ * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, readOnlyWorktree?: boolean, controlPlane?: boolean, workdir?: string|null }}
+ *   - For control-plane surface (any project): { cwd: <MINIONS_DIR[/workdir]>, worktreeRootDir: null, controlPlane: true }
  *   - For live mode (any type): { cwd: <abs localPath[/workdir]>, worktreeRootDir: null, liveMode: true }
  *   - For project-bound isolated read-only types:
  *     { cwd: null, worktreeRootDir: <project root>, readOnlyWorktree: true, workdir }
@@ -6424,6 +7356,63 @@ function resolveSpawnPaths(project, type, minionsDir, options) {
     ? options.workdir
     : null;
 
+  // ── Cloud short-circuit (Agency / Copilot cloud dispatch) ─────────────
+  // A cloud dispatch allocates NO local checkout at all: the remote agent
+  // owns its own workspace, its own branch, and authors its own PR. The
+  // engine still needs a local cwd for the provider call itself (`az`, `gh`,
+  // or an HTTPS request), so it runs from MINIONS_DIR — the same anchor
+  // control-plane uses.
+  //
+  // `workdir` is deliberately echoed back UNAPPLIED. For a repo surface it is
+  // a subpath of the checkout; here there is no checkout, so resolving it
+  // against MINIONS_DIR would be meaningless (and would fail containment for
+  // no reason). The caller forwards it to the provider as a repo-relative
+  // scope hint for the remote agent.
+  //
+  // Ordered ahead of live-checkout and the read-only / mutating split for the
+  // same reason control-plane is: "does this need a checkout?" must be one
+  // decision in one place. As with control-plane, the caller is responsible
+  // for having validated the surface fail-closed via `validateExecutionSurface`.
+  if (options && typeof options === 'object'
+      && options.executionSurface === EXECUTION_SURFACE.CLOUD) {
+    if (!minionsDir) {
+      const err = new Error('Cannot resolve cwd for cloud spawn: no MINIONS_DIR provided.');
+      err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
+      throw err;
+    }
+    return {
+      cwd: path.resolve(String(minionsDir)),
+      worktreeRootDir: null,
+      cloud: true,
+      workdir,
+    };
+  }
+
+  // ── Control-plane short-circuit (W-ms5tb6ha016fda10) ───────────────────
+  // Runs BEFORE live-checkout and before the read-only / code-mutating split
+  // so "this task needs no repository checkout" is a single, explicit
+  // decision made in exactly one place. Deliberately ordered ahead of live
+  // mode too: a control-plane job must not enter the operator's checkout, and
+  // must not consume the one-mutating-dispatch-per-project live slot.
+  //
+  // The caller is responsible for having validated the surface (fail-closed)
+  // via `validateExecutionSurface`; this resolver only honors the already-
+  // validated boolean so the eligibility rule cannot fork.
+  if (options && typeof options === 'object'
+      && options.executionSurface === EXECUTION_SURFACE.CONTROL_PLANE) {
+    if (!minionsDir) {
+      const err = new Error('Cannot resolve cwd for control-plane spawn: no MINIONS_DIR provided.');
+      err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
+      throw err;
+    }
+    const cpBase = path.resolve(String(minionsDir));
+    return {
+      cwd: _applyWorkdirOrThrow(cpBase, workdir),
+      worktreeRootDir: null,
+      controlPlane: true,
+    };
+  }
+
   // ── Live-checkout mode short-circuit (P-a3f9b202) ──────────────────────
   // Runs BEFORE the read-only / code-mutating split so live mode is the
   // single decision point regardless of task type — read-only tasks in
@@ -6784,7 +7773,7 @@ function syncBundledPersonalSkills(skillsDir, opts = {}) {
   if (!skillsDir || !fs.existsSync(skillsDir)) return result;
 
   const homeDir = opts.homeDir || os.homedir();
-  const { listRuntimes, resolveRuntime } = require('./runtimes');
+  const { listRuntimes, resolveRuntime } = require('../runtimes');
   const personalRoots = new Set();
   for (const runtimeName of listRuntimes()) {
     const runtime = resolveRuntime(runtimeName);
@@ -7589,10 +8578,10 @@ function findPrRecord(prs, prRef, project = null) {
 //   - the link-time "...(polling...)" placeholder
 //   - serialized-JSON / agent-output leakage (contains {}"[] chars)
 //   - bare hex/uuid-ish ids (>= 8 hex/dash chars)
-//   - the fallback WRITER shapes "PR created by <agent>" (engine/lifecycle.js)
-//     and bare "PR #<n>" (engine/ado.js central poller)
-// The WRITER (engine/lifecycle.js) and the DETECTORS (engine/github.js,
-// engine/ado.js) MUST agree — route every site through this helper so they
+//   - the fallback WRITER shapes "PR created by <agent>" (engine/orchestration/lifecycle.js)
+//     and bare "PR #<n>" (engine/ado/index.js central poller)
+// The WRITER (engine/orchestration/lifecycle.js) and the DETECTORS (engine/providers/github.js,
+// engine/ado/index.js) MUST agree — route every site through this helper so they
 // cannot drift apart again (the github poller previously never backfilled a
 // frozen "PR created by Ripley" title because its detector didn't know the shape).
 function isPlaceholderPrTitle(title) {
@@ -7613,6 +8602,113 @@ function snapshotPrRecord(pr) {
   return JSON.parse(JSON.stringify(pr));
 }
 
+// ── PR author identity (separate from `pr.agent`) ────────────────────────────
+//
+// `pr.agent`  = the Minions agent that created/owns the automated work. Used for
+//               routing, self-review prevention, fix ownership, and metrics. The
+//               sentinel `PR_AGENT_HUMAN` ('human') means "no Minions author-agent"
+//               (a human/externally created PR). `agent` is NEVER a human login.
+// `pr.author` = the real individual on whose behalf the PR exists, linked to an
+//               authoritative provider identity. Structured shape:
+//                 { provider, id, nodeId?, descriptor?, login?, displayName?, url? }
+//               Unknown/legacy records leave `author` unset and render "Unknown".
+//
+// See docs/pr-author-identity.md.
+const PR_AGENT_HUMAN = 'human';
+
+const _PR_AUTHOR_FIELDS = ['provider', 'id', 'nodeId', 'descriptor', 'login', 'displayName', 'url'];
+
+function _authorField(value, max) {
+  if (value == null) return '';
+  const s = String(value).trim();
+  return s ? s.slice(0, max) : '';
+}
+
+// Accept only real http(s) profile links; anything else is dropped so the
+// dashboard never renders an unvalidated href.
+function _authorProfileUrl(value) {
+  const s = _authorField(value, 400);
+  if (!s) return '';
+  return /^https?:\/\/[^\s]+$/i.test(s) ? s : '';
+}
+
+// Build a structured author identity from a GitHub PR `user` object.
+function buildGithubAuthorIdentity(user) {
+  if (!user || typeof user !== 'object') return null;
+  const out = { provider: 'github' };
+  const id = _authorField(user.id, 64);
+  const nodeId = _authorField(user.node_id, 128);
+  const login = _authorField(user.login, 120);
+  const displayName = _authorField(user.name, 200);
+  const url = _authorProfileUrl(user.html_url);
+  if (id) out.id = id;
+  if (nodeId) out.nodeId = nodeId;
+  if (login) out.login = login;
+  if (displayName) out.displayName = displayName;
+  if (url) out.url = url;
+  return (out.id || out.nodeId || out.login || out.displayName) ? out : null;
+}
+
+// Build a structured author identity from an ADO PR `createdBy` object. ADO's
+// createdBy.url is an API endpoint (not a browsable profile page), so no url is
+// surfaced unless a real http(s) profile link is present in _links.
+function buildAdoAuthorIdentity(createdBy) {
+  if (!createdBy || typeof createdBy !== 'object') return null;
+  const out = { provider: 'ado' };
+  const id = _authorField(createdBy.id, 64);
+  const descriptor = _authorField(createdBy.descriptor, 256);
+  const login = _authorField(createdBy.uniqueName, 200);
+  const displayName = _authorField(createdBy.displayName, 200);
+  const url = _authorProfileUrl(createdBy._links && createdBy._links.web && createdBy._links.web.href);
+  if (id) out.id = id;
+  if (descriptor) out.descriptor = descriptor;
+  if (login) out.login = login;
+  if (displayName) out.displayName = displayName;
+  if (url) out.url = url;
+  return (out.id || out.descriptor || out.login || out.displayName) ? out : null;
+}
+
+// Normalize an arbitrary author value (structured object or bare string) into
+// the canonical structured shape, or null when nothing usable is present.
+function normalizePrAuthorIdentity(raw) {
+  if (!raw) return null;
+  if (typeof raw === 'string') {
+    const login = raw.trim().slice(0, 200);
+    return login ? { login } : null;
+  }
+  if (typeof raw !== 'object') return null;
+  const out = {};
+  for (const key of _PR_AUTHOR_FIELDS) {
+    const value = key === 'url' ? _authorProfileUrl(raw[key]) : _authorField(raw[key], 256);
+    if (value) out[key] = value;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+// Centralized merge so a partial provider refresh cannot erase a richer author
+// identity already stored. Field-by-field: a non-empty incoming value wins,
+// otherwise the existing value is preserved. A provider change trusts the newer
+// identity wholesale (the person the platform now reports authored the PR).
+function mergePrAuthorIdentity(existing, incoming) {
+  const cur = normalizePrAuthorIdentity(existing);
+  const inc = normalizePrAuthorIdentity(incoming);
+  if (!inc) return cur;
+  if (!cur) return inc;
+  if (cur.provider && inc.provider && cur.provider !== inc.provider) return inc;
+  const out = { ...cur };
+  for (const key of _PR_AUTHOR_FIELDS) {
+    if (inc[key]) out[key] = inc[key];
+  }
+  return out;
+}
+
+// Human-readable label for a PR author (typed SQL column + filter/search text).
+function prAuthorLabel(author) {
+  const a = normalizePrAuthorIdentity(author);
+  if (!a) return '';
+  return a.displayName || a.login || a.id || '';
+}
+
 function _jsonEqual(a, b) {
   return JSON.stringify(a) === JSON.stringify(b);
 }
@@ -7684,17 +8780,28 @@ function normalizePrLinkItems(value) {
   return [...new Set(items.filter(item => typeof item === 'string' && item))];
 }
 
-// Canonical `contextOnly` gate — reads only the canonical field.
-// All records are expected to carry `contextOnly` after the 2026-06-24
-// on-disk sweep confirmed no live `_contextOnly`/`_autoObserve`/`_manual`
-// keys remain (and the boot migration has been removed).
+// Canonical context-only flag retained for API/backward compatibility.
 function isContextOnlyPrRecord(pr) {
   if (!pr || typeof pr !== 'object') return false;
   return pr.contextOnly === true;
 }
 
+function isPrAutoFixEnabled(pr) {
+  if (!pr || typeof pr !== 'object') return false;
+  return typeof pr.autoFixEnabled === 'boolean'
+    ? pr.autoFixEnabled
+    : !isContextOnlyPrRecord(pr);
+}
+
+function isPrAutoReviewEnabled(pr) {
+  if (!pr || typeof pr !== 'object') return false;
+  return typeof pr.autoReviewEnabled === 'boolean'
+    ? pr.autoReviewEnabled
+    : !isContextOnlyPrRecord(pr);
+}
+
 function isAutoManagedPrRecord(pr) {
-  return !!pr && typeof pr === 'object' && !isContextOnlyPrRecord(pr);
+  return isPrAutoFixEnabled(pr) || isPrAutoReviewEnabled(pr);
 }
 
 /**
@@ -7717,7 +8824,7 @@ const EXPLICIT_WORK_ITEM_ORIGIN_ROOTS = new Set([
   'dashboard',      // dashboard UI + POST /api/work-items, incl. CC/agent API callers
                     // (dashboard.js hard-codes createdBy:'dashboard'; also
                     // dashboard:execute, dashboard:revision, dashboard:promotion:…)
-  'human',          // engine/meeting.js
+  'human',          // engine/orchestration/meeting.js
   'operator',
   'watch',          // operator-authored watch rule (watch:<watchId>)
   'scheduler',      // operator-authored schedule (scheduler, scheduler:harness)
@@ -7730,7 +8837,7 @@ const EXPLICIT_WORK_ITEM_ORIGIN_ROOTS = new Set([
  * Normalize a work item's `createdBy` to its namespace root so the allowlist
  * above stays short. Creators namespace themselves as `<root>:<detail>`
  * (`dashboard:execute`, `pipeline:<id>`, `watch:<id>`, `scheduler:harness`);
- * `qa-session-<phase>` (engine/qa-sessions.js) uses a hyphen instead.
+ * `qa-session-<phase>` (engine/qa/sessions.js) uses a hyphen instead.
  */
 function workItemOriginRoot(createdBy) {
   const raw = typeof createdBy === 'string' ? createdBy.trim().toLowerCase() : '';
@@ -7798,7 +8905,7 @@ function getPrLinks() {
   // normalization.
   const projectsByName = new Map(getProjects().map(project => [project.name || path.basename(project.localPath || ''), project]));
   try {
-    const store = require('./pull-requests-store');
+    const store = require('../persistence/pull-requests-store');
     const allPrs = store.readAllPullRequests() || [];
     for (const pr of allPrs) {
       if (!pr?.id) continue;
@@ -7813,7 +8920,7 @@ function getPrLinks() {
   // Static PR links are stored in SQLite.
   let static_ = null;
   try {
-    const store = require('./small-state-store');
+    const store = require('../persistence/small-state-store');
     static_ = store.readPrLinks();
   } catch { static_ = null; }
   if (static_ && typeof static_ === 'object' && !Array.isArray(static_)) {
@@ -7867,9 +8974,9 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
     links[effectivePrId] = [...mergedCurrent];
     return links;
   };
-  const { wrote } = require('./small-state-store').applyPrLinksMutation(mutator);
+  const { wrote } = require('../persistence/small-state-store').applyPrLinksMutation(mutator);
   if (wrote) {
-    try { require('./db-events').emitStateEvent('pr_links'); } catch { /* optional */ }
+    try { require('../persistence/db-events').emitStateEvent('pr_links'); } catch { /* optional */ }
   }
 
   if (!project) return;
@@ -7895,7 +9002,8 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
 const _DEDUP_MERGE_SCALAR_KEYS = [
   'url', 'title', 'agent', 'branch', 'description', 'sourcePlan', 'itemType',
   'mergedAt', 'closedAt', 'created', 'reviewStatus',
-  'minionsReview', '_automationFixCauses',
+  'minionsReview', 'contextOnly', 'autoFixEnabled', 'autoReviewEnabled',
+  '_automationFixCauses',
 ];
 
 // Pick the "most complete" record from a list of duplicates.
@@ -7921,6 +9029,10 @@ function _mergeDuplicatePrInto(winner, loser) {
       winner[key] = loser[key];
     }
   }
+  // Author is a structured identity — merge field-by-field so the winner keeps
+  // the richest identity across duplicates rather than an arbitrary one.
+  const mergedAuthor = mergePrAuthorIdentity(winner.author, loser.author);
+  if (mergedAuthor) winner.author = mergedAuthor;
   winner.prdItems = normalizePrLinkItems([...(winner.prdItems || []), ...(loser.prdItems || [])]);
   if (winner.userDeleted === true || loser.userDeleted === true) {
     winner.userDeleted = true;
@@ -7985,7 +9097,7 @@ function _clearPrTombstonesForIdentity(identity) {
   if (!identity) return 0;
   const projectsByName = new Map(getProjects().map(project => [project.name, project]));
   const scopes = new Map();
-  const store = require('./pull-requests-store');
+  const store = require('../persistence/pull-requests-store');
   for (const pr of store.readAllPullRequests() || []) {
     if (pr?.userDeleted !== true) continue;
     const project = pr._scope && pr._scope !== 'central'
@@ -8076,6 +9188,11 @@ function upsertPullRequestRecord(source, entry, { project = null, itemId = null,
   if (normalizedEntry.contextOnly != null) {
     normalizedEntry.contextOnly = normalizedEntry.contextOnly === true;
   }
+  // Canonicalize the author identity on the create path (the update path merges
+  // via mergePrAuthorIdentity). A null result is stored as-is → renders Unknown.
+  if (Object.prototype.hasOwnProperty.call(normalizedEntry, 'author')) {
+    normalizedEntry.author = normalizePrAuthorIdentity(normalizedEntry.author);
+  }
 
   let created = false;
   let linked = false;
@@ -8121,7 +9238,7 @@ function upsertPullRequestRecord(source, entry, { project = null, itemId = null,
     // silently clearing the tombstone. Check globally before inserting.
     if (!target && !allowResurrect) {
       try {
-        const store = require('./pull-requests-store');
+        const store = require('../persistence/pull-requests-store');
         const projectsByName = new Map(getProjects().map(candidate => [candidate.name, candidate]));
         const globalMatch = (store.readAllPullRequests() || []).find(pr => {
           if (!pr || pr.userDeleted !== true) return false;
@@ -8148,6 +9265,14 @@ function upsertPullRequestRecord(source, entry, { project = null, itemId = null,
       target.id = canonicalId;
       if (prNumber != null) target.prNumber = prNumber;
       const targetWasAutoManaged = isAutoManagedPrRecord(target);
+      // Author identity merges through mergePrAuthorIdentity so a partial
+      // provider refresh (which may omit author entirely) never erases a richer
+      // author already stored. This is intentionally separate from the
+      // fill-if-empty scalar loop below because author is a structured object.
+      if (normalizedEntry.author != null) {
+        const mergedAuthor = mergePrAuthorIdentity(target.author, normalizedEntry.author);
+        if (mergedAuthor) target.author = mergedAuthor;
+      }
       for (const key of ['url', 'title', 'description', 'agent', 'branch', 'reviewStatus', 'status', 'created', 'sourcePlan', 'itemType', 'prdItemId']) {
         if (normalizedEntry[key] != null && normalizedEntry[key] !== '' && (target[key] == null || target[key] === '')) {
           target[key] = normalizedEntry[key];
@@ -8159,6 +9284,14 @@ function upsertPullRequestRecord(source, entry, { project = null, itemId = null,
       if (normalizedEntry.contextOnly != null) {
         const wouldDemoteManagedPr = normalizedEntry.contextOnly === true && targetWasAutoManaged;
         target.contextOnly = wouldDemoteManagedPr ? false : normalizedEntry.contextOnly === true;
+        if (!wouldDemoteManagedPr) {
+          if (typeof normalizedEntry.autoFixEnabled === 'boolean') {
+            target.autoFixEnabled = normalizedEntry.autoFixEnabled;
+          }
+          if (typeof normalizedEntry.autoReviewEnabled === 'boolean') {
+            target.autoReviewEnabled = normalizedEntry.autoReviewEnabled;
+          }
+        }
       }
     }
     target.prdItems = normalizePrLinkItems(target.prdItems || []);
@@ -8293,7 +9426,7 @@ function autoEnrollPrFromWorkItem(item, project, minionsDir) {
       prNumber: prNum,
       title: `PR #${prNum != null ? prNum : '?'} (polling...)`,
       description: '',
-      agent: 'human',
+      agent: PR_AGENT_HUMAN,
       branch: '',
       reviewStatus: 'pending',
       status: 'active',
@@ -8314,7 +9447,7 @@ const autoEnrollPrFromFixWorkItem = autoEnrollPrFromWorkItem;
 
 // Cross-platform process-management helpers (kill trees, PID liveness,
 // process-table enumeration, cwd-holder detection, descendant/reachability
-// BFS) were extracted to engine/process-utils.js (P-mrb8yg9x001k1401-b) and
+// BFS) were extracted to engine/processes/process-utils.js (P-mrb8yg9x001k1401-b) and
 // are re-exported below via `...processUtils`.
 
 // W-mq6f2fe0000557fa — clear the per-path failure cooldown entry so the
@@ -8331,7 +9464,7 @@ function clearWorktreeFailureCache(wtPath) {
 
 // Cross-platform process-management helpers (kill trees, PID liveness,
 // process-table enumeration, cwd-holder detection, descendant/reachability
-// BFS) were extracted to engine/process-utils.js (P-mrb8yg9x001k1401-b) and
+// BFS) were extracted to engine/processes/process-utils.js (P-mrb8yg9x001k1401-b) and
 // are re-exported below via `...processUtils`.
 
 // ─── Work Items & Pull Requests Mutation Helpers ────────────────────────────
@@ -8352,11 +9485,11 @@ function stateScope(source) {
 }
 
 function readWorkItems(source = null) {
-  return require('./work-items-store').readWorkItemsForScope(stateScope(source));
+  return require('../planning/work-items-store').readWorkItemsForScope(stateScope(source));
 }
 
 function mutateWorkItems(source, mutator, opts = {}) {
-  const store = require('./work-items-store');
+  const store = require('../planning/work-items-store');
   const scope = stateScope(source);
   const normalizedOpts = { ...opts };
   if (Array.isArray(opts.readScopes)) {
@@ -8367,7 +9500,7 @@ function mutateWorkItems(source, mutator, opts = {}) {
     return mutator(items, comparisonItems) || items;
   }, normalizedOpts);
   if (wrote) {
-    try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+    try { require('../persistence/db-events').emitStateEvent('work_items'); } catch { /* optional */ }
     try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
   }
   return result;
@@ -8387,17 +9520,17 @@ function reopenWorkItem(wi) {
 }
 
 function readPullRequests(source = null) {
-  return require('./pull-requests-store').readPullRequestsForScope(stateScope(source));
+  return require('../persistence/pull-requests-store').readPullRequestsForScope(stateScope(source));
 }
 
 function mutatePullRequests(source, mutator) {
-  const store = require('./pull-requests-store');
+  const store = require('../persistence/pull-requests-store');
   const { wrote, result } = store.applyPullRequestsMutation(stateScope(source), (prs) => {
     if (!Array.isArray(prs)) prs = [];
     return mutator(prs) || prs;
   });
   if (wrote) {
-    try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
+    try { require('../persistence/db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
   }
   return result;
 }
@@ -8525,16 +9658,16 @@ function getPrFixAutomationCause({ dispatchKey = '', source = '', task = '' } =
 }
 
 // Source-branch head SHA, normalized across hosts. GitHub PRs carry
-// `headSha`/`headRefOid` (engine/github.js:718-742 keeps both in sync); ADO PRs
-// carry `_adoSourceCommit`/`headRefOid` (engine/ado.js:1083-1129) and a legacy
-// `_adoHeadCommit`. Mirrors engine/lifecycle.js:1849 getPrFixBaselineHead.
+// `headSha`/`headRefOid` (engine/providers/github.js:718-742 keeps both in sync); ADO PRs
+// carry `_adoSourceCommit`/`headRefOid` (engine/ado/index.js:1083-1129) and a legacy
+// `_adoHeadCommit`. Mirrors engine/orchestration/lifecycle.js:1849 getPrFixBaselineHead.
 function _prHeadSha(pr) {
   return String(pr?.headRefOid || pr?.headSha || pr?._adoSourceCommit || pr?._adoHeadCommit || '').trim();
 }
 
 // Target-branch base SHA, normalized across hosts. GitHub PRs carry `baseSha`
-// (engine/github.js:746-749); ADO PRs carry `_adoTargetCommit`
-// (engine/ado.js:1168-1172, inline in pollPrStatus).
+// (engine/providers/github.js:746-749); ADO PRs carry `_adoTargetCommit`
+// (engine/ado/index.js:1168-1172, inline in pollPrStatus).
 function _prBaseSha(pr) {
   return String(pr?.baseSha || pr?._adoTargetCommit || '').trim();
 }
@@ -8769,7 +9902,7 @@ function isWorktreePathLive(worktreePath, opts = {}) {
   const excludeSpawnLeaseId = opts.excludeSpawnLeaseId ? String(opts.excludeSpawnLeaseId) : null;
   let db = opts.db || null;
   if (!db) {
-    try { db = require('./db').getDb(); }
+    try { db = require('../db').getDb(); }
     catch (e) {
       log('warn', `isWorktreePathLive: SQL unavailable for ${worktreePath} (${e.message}) — fail-open (assume live)`);
       return true;
@@ -8803,6 +9936,52 @@ function isWorktreePathLive(worktreePath, opts = {}) {
   return false;
 }
 
+// W-ms9q3dql00vxd4a8 — batched, READ-ONLY sibling of `isWorktreePathLive` for
+// reporting paths that classify a whole worktree root at once (the worktree
+// inventory and the dashboard's lifecycle count). The per-path guard runs a
+// full pending+active scan for EVERY path, which is right for the handful of
+// destructive sites but is O(directories) queries for a 150-directory root.
+//
+// Deliberately NOT used by any wipe site: those keep the per-path guard and its
+// `excludeDispatchId` / `excludeSpawnLeaseId` semantics. The failure contract
+// mirrors the guard — `{ ok: false }` means "could not determine", and callers
+// MUST fail OPEN (treat every path as live) exactly as the guard does.
+function listLiveWorktreePaths(opts = {}) {
+  let db = opts.db || null;
+  if (!db) {
+    try { db = require('../db').getDb(); }
+    catch (e) {
+      log('warn', `listLiveWorktreePaths: SQL unavailable (${e.message}) — fail-open (assume live)`);
+      return { ok: false, paths: new Set() };
+    }
+  }
+  if (!db) {
+    log('warn', 'listLiveWorktreePaths: no db handle — fail-open (assume live)');
+    return { ok: false, paths: new Set() };
+  }
+  let rows;
+  try {
+    rows = db.prepare(`
+      SELECT json_extract(data, '$.worktreePath') AS top_wt,
+             json_extract(data, '$.meta.worktreePath') AS meta_wt
+      FROM dispatches
+      WHERE status IN ('pending', 'active')
+    `).all();
+  } catch (e) {
+    log('warn', `listLiveWorktreePaths: query threw (${e.message}) — fail-open (assume live)`);
+    return { ok: false, paths: new Set() };
+  }
+  const paths = new Set();
+  for (const row of rows || []) {
+    for (const raw of [row?.top_wt, row?.meta_wt]) {
+      if (!raw) continue;
+      const normalized = _normalizeWorktreePath(raw);
+      if (normalized) paths.add(normalized);
+    }
+  }
+  return { ok: true, paths };
+}
+
 // P-1d6b1aa7 — separate, best-effort lookup of the specific dispatch row
 // that is blocking a wipe, so callers can fold self-diagnosing detail (id,
 // status, age-in-non-terminal-state) into the skip-live inbox note instead
@@ -8822,7 +10001,7 @@ function getWorktreeBlockingDispatchInfo(worktreePath, opts = {}) {
     const excludeSpawnLeaseId = opts.excludeSpawnLeaseId ? String(opts.excludeSpawnLeaseId) : null;
     let db = opts.db || null;
     if (!db) {
-      try { db = require('./db').getDb(); }
+      try { db = require('../db').getDb(); }
       catch { return null; }
     }
     if (!db) return null;
@@ -8906,6 +10085,36 @@ function _writeWorktreeSkipLiveInboxNote(worktreePath, callerTag, blockingInfo)
   } catch { /* best-effort — never throw from the skip-note writer */ }
 }
 
+// W-ms9q3dql00vxd4a8 — a removal that REPORTS success but leaves the directory
+// behind is how an install accumulates unclassifiable residue. `git worktree
+// remove --force`, `fs.rmSync` and `rd /s /q` all clear the CONTENTS first —
+// including `.git` and the `.minions-worktree` ownership marker — and can then
+// still fail to unlink the top directory when something holds it open (a
+// process CWD, AV, Explorer). The husk left behind has no marker, no `gitdir:`
+// pointer and no registration, so every safe GC classifies it as FOREIGN and
+// keeps it forever: the observed 107 empty `W-*` directories on this install.
+//
+// So verify instead of assuming. When the path survives: finish the job if it
+// is now empty, otherwise re-stamp ownership so the residue stays reclaimable
+// by the ordinary orphan sweep, and report the truth to the caller.
+// Returns true only when the path is genuinely gone.
+function _verifyWorktreeRemoved(resolved, hadOwnerMarker) {
+  let exists;
+  try { exists = fs.existsSync(resolved); }
+  catch { return true; } // unreadable — nothing further we can safely do
+  if (!exists) return true;
+  try {
+    if (fs.readdirSync(resolved).length === 0) fs.rmdirSync(resolved);
+  } catch { /* still occupied or unreadable — fall through to the re-stamp */ }
+  let survived = true;
+  try { survived = fs.existsSync(resolved); } catch { survived = true; }
+  if (!survived) return true;
+  _restoreWorktreeOwnerMarkerAfterFailedRemoval(resolved, hadOwnerMarker);
+  log('warn', `removeWorktree: removal reported success but ${resolved} still exists — ownership re-stamped so the orphan sweep can reclaim it`);
+  try { bumpWorktreeGcMetric('survivedRemoval'); } catch { /* metric optional */ }
+  return false;
+}
+
 // P-c7e2b405 — INTENTIONAL divergence from worktree-gc.reapAndRemoveWorktree:
 // this is the low-level `git worktree remove --force` → fs.rmSync → rd /s /q
 // removal primitive WITH its own EBUSY/_retryFsOp backoff loop. The engine-side
@@ -8997,6 +10206,31 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   const prior = _removeWorktreeFailures.get(resolved);
   if (prior && prior.count >= 3 && Date.now() - prior.lastAttempt < 3600000) return false;
 
+  const _recordRemovalFailure = (message) => {
+    const fail = _removeWorktreeFailures.get(resolved) || { count: 0, lastAttempt: 0 };
+    fail.count++;
+    fail.lastAttempt = Date.now();
+    fail.lastError = message || 'unknown';
+    _removeWorktreeFailures.set(resolved, fail);
+    _pruneRemoveWorktreeFailures();
+    bumpWorktreeGcMetric('totalFailure');
+    if (fail.count <= 3) log('warn', `removeWorktree: failed for ${wtPath} (attempt ${fail.count}/3): ${fail.lastError}`);
+    return false;
+  };
+  // W-ms9q3dql00vxd4a8 — every "success" exit funnels through here so a stage
+  // that cleared the contents but could not unlink the directory is reported as
+  // the failure it is, with ownership re-stamped, instead of leaking an
+  // unclassifiable husk that no GC will ever be allowed to reclaim.
+  const _settleRemoval = (stage, extraMetric) => {
+    if (!_verifyWorktreeRemoved(resolved, hadOwnerMarker)) {
+      return _recordRemovalFailure(`${stage} reported success but the directory survived`);
+    }
+    _removeWorktreeFailures.delete(resolved);
+    bumpWorktreeGcMetric('success');
+    if (extraMetric) bumpWorktreeGcMetric(extraMetric);
+    return true;
+  };
+
   // Windows: purge reserved-name pseudo-files (NUL, CON, etc.) that block normal deletion
   if (process.platform === 'win32') {
     _purgeReservedFiles(resolved);
@@ -9006,9 +10240,7 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   try {
     // P-1d7a4f80 — argv form (shell:false) so wtPath can never be re-parsed by a shell.
     shellSafeGitSync(['worktree', 'remove', wtPath, '--force'], { cwd: gitRoot, timeout: 15000 });
-    _removeWorktreeFailures.delete(resolved);
-    bumpWorktreeGcMetric('success');
-    return true;
+    return _settleRemoval('git worktree remove --force');
   } catch (gitErr) {
     try {
       // P-b3d9a162 — re-run the real-repo refusal: a lock that released only
@@ -9026,10 +10258,7 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
         `fs.rmSync(${resolved})`
       );
       try { shellSafeGitSync(['worktree', 'prune'], { cwd: gitRoot, timeout: 10000 }); } catch {}
-      _removeWorktreeFailures.delete(resolved);
-      bumpWorktreeGcMetric('success');
-      if (attempt > 1) bumpWorktreeGcMetric('successAfterRetry');
-      return true;
+      return _settleRemoval('fs.rmSync', attempt > 1 ? 'successAfterRetry' : null);
     } catch (rmErr) {
       // Windows: try cmd /c rd /s /q for any error — handles reserved device names,
       // locked files, and partially-deleted directories (not just EPERM)
@@ -9040,23 +10269,13 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
           // argv element rather than interpolated into a shell string.
           _execFileSync('cmd', ['/c', 'rd', '/s', '/q', resolved], { stdio: 'pipe', timeout: 15000, windowsHide: true });
           try { shellSafeGitSync(['worktree', 'prune'], { cwd: gitRoot, timeout: 10000 }); } catch {}
-          _removeWorktreeFailures.delete(resolved);
-          bumpWorktreeGcMetric('success');
-          return true;
+          return _settleRemoval('rd /s /q');
         } catch (rdErr) {
           log('warn', `removeWorktree: rd /s /q fallback failed for ${wtPath}: ${rdErr.message}`);
         }
       }
       _restoreWorktreeOwnerMarkerAfterFailedRemoval(resolved, hadOwnerMarker);
-      const fail = _removeWorktreeFailures.get(resolved) || { count: 0, lastAttempt: 0 };
-      fail.count++;
-      fail.lastAttempt = Date.now();
-      fail.lastError = rmErr && rmErr.message ? rmErr.message : 'unknown';
-      _removeWorktreeFailures.set(resolved, fail);
-      _pruneRemoveWorktreeFailures();
-      bumpWorktreeGcMetric('totalFailure');
-      if (fail.count <= 3) log('warn', `removeWorktree: failed for ${wtPath} (attempt ${fail.count}/3): ${rmErr.message}`);
-      return false;
+      return _recordRemovalFailure(rmErr && rmErr.message ? rmErr.message : 'unknown');
     }
   }
 }
@@ -9107,6 +10326,19 @@ function hasWorktreeOwnerMarker(worktreePath) {
   }
 }
 
+// Async twin of `hasWorktreeOwnerMarker`, for read-only reporting that must not
+// hold the event loop for one syscall per directory. Identical fail-closed
+// contract — keep the two in step.
+async function hasWorktreeOwnerMarkerAsync(worktreePath) {
+  if (!worktreePath) return false;
+  try {
+    await fs.promises.access(path.join(path.resolve(worktreePath), WORKTREE_OWNER_MARKER));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function hasProtectedQuarantineMarker(worktreePath) {
   if (!worktreePath) return false;
   try {
@@ -9125,6 +10357,34 @@ function hasProtectedQuarantineMarker(worktreePath) {
   }
 }
 
+// Async twin of `hasProtectedQuarantineMarker`, including the fail-SAFE `true`
+// on error: an unreadable ancestor chain must read as "protected", never as
+// "free to delete". Keep the two in step — note the sync twin probes with
+// `fs.existsSync`, which NEVER throws, so an unreadable ancestor reads as
+// "marker absent" and the walk continues. Matching that exactly is what keeps
+// the async pre-read from classifying a directory differently than the
+// synchronous fallback would.
+async function hasProtectedQuarantineMarkerAsync(worktreePath) {
+  if (!worktreePath) return false;
+  try {
+    let current = path.resolve(worktreePath);
+    while (true) {
+      if (path.basename(current).includes(WORKTREE_QUARANTINE_PROTECTED_PATH_TOKEN)) return true;
+      let markerExists = false;
+      try {
+        await fs.promises.access(path.join(current, WORKTREE_QUARANTINE_PROTECTION_MARKER));
+        markerExists = true;
+      } catch { markerExists = false; }
+      if (markerExists) return true;
+      const parent = path.dirname(current);
+      if (parent === current) return false;
+      current = parent;
+    }
+  } catch {
+    return true;
+  }
+}
+
 function _restoreWorktreeOwnerMarkerAfterFailedRemoval(worktreePath, hadOwnerMarker) {
   if (!hadOwnerMarker || !worktreePath) return false;
   let exists = false;
@@ -9326,7 +10586,7 @@ function createThrottleTracker({ label, baseBackoffMs = 60000, maxBackoffMs = 32
 
 // ── Backoff Tracker Factory ─────────────────────────────────────────────────
 // Generic graduated-backoff tracker for retryable *acquisition* failures (e.g.
-// ADO token minting via engine/ado-token.js). Distinct from
+// ADO token minting via engine/ado/token.js). Distinct from
 // createThrottleTracker on three points so callers don't reach for the wrong
 // one: (1) the FIRST failure backs off `baseMs`, not `baseMs*2` — a single
 // transient blip must not blackout for the full cap; (2) recordSuccess RESETS
@@ -9370,7 +10630,7 @@ function createBackoffTracker({ baseMs = 30000, maxMs = 10 * 60 * 1000 } = {}) {
 
 // ── npm package identity (W-ms1j8m54000g4a4a) ───────────────────────────────
 // Minions is published to more than one npm distribution channel: the public
-// `@yemi33/minions` and internal builds renamed by tools/prepare-package.js
+// `@yemi33/minions` and internal builds renamed by scripts/prepare-package.js
 // (`INTERNAL_PACKAGE_NAME`, default `@yemishin_microsoft/minions`). Anything
 // that shells out to `npm view` / `npm install -g` / `npm uninstall -g` must
 // target the package that is ACTUALLY installed — hardcoding the public name
@@ -9416,6 +10676,37 @@ function resolvePackageName(pkgRoot) {
   return PUBLIC_PACKAGE_NAME;
 }
 
+// W-ms6b7prf006tef7f-b: install-channel marker. `minions init` records the
+// runtime's version (`.minions-version`) and source commit (`.minions-commit`);
+// this marker records WHICH npm distribution produced the runtime root, so an
+// internal (`@opg-microsoft/minions`) root and a public (`@yemi33/minions`) one
+// are distinguishable on disk. Written by bin/minions.js#saveInstalledVersion.
+const RUNTIME_CHANNEL_MARKER = '.minions-package';
+
+// Read the install-channel marker from a runtime root. Returns
+// `{ name, version }` or null. A MISSING marker is "unknown", never an error:
+// every runtime root initialized before this marker existed has none, and a
+// legacy root must keep working. A marker whose name we would not be willing to
+// put on an npm command line is treated as unknown for the same reason
+// resolvePackageName falls back — a channel identity is only useful if it is
+// safe to act on.
+//
+// The name is validated EXACTLY as read, never trimmed first: this value is
+// compared against a name that gets interpolated into a shell command, so
+// normalizing junk into something acceptable is the wrong direction. A marker
+// name with surrounding whitespace is a marker we do not understand.
+// The version is advisory (it only ever reaches an operator-facing message), so
+// an unparseable one degrades to null rather than voiding the channel identity.
+function readRuntimeChannel(runtimeRoot) {
+  if (typeof runtimeRoot !== 'string' || !runtimeRoot) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(runtimeRoot, RUNTIME_CHANNEL_MARKER), 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    if (!isValidNpmPackageName(raw.name)) return null;
+    return { name: raw.name, version: isValidNpmVersion(raw.version) ? raw.version : null };
+  } catch { return null; }
+}
+
 function assertNpmPackageName(pkgName) {
   if (!isValidNpmPackageName(pkgName)) {
     throw new Error(`Refusing to run npm against an invalid package name: ${JSON.stringify(pkgName)}`);
@@ -9439,9 +10730,138 @@ function buildNpmGlobalUninstallCommand(pkgName) {
   return `npm uninstall -g ${assertNpmPackageName(pkgName)}`;
 }
 
+// ── Update channel authority (W-ms6b7prf006tef7f-d) ─────────────────────────
+// `resolvePackageName(PKG_ROOT)` answers "which package would an update
+// install?" — it does NOT answer "which channel is this runtime on?". Those
+// diverge in exactly the case that hurts: the opg repo's own package.json is
+// named `@yemi33/minions`, and a still-public global shim can sit in front of an
+// internal runtime. Either way PKG_ROOT resolves PUBLIC while the runtime is
+// INTERNAL, and an unguarded `npm view` → `npm install -g` then drops a stale
+// public build on top of a newer internal one.
+//
+// The RUNTIME ROOT is therefore the channel authority: `minions init` records
+// the installing distribution in `<runtimeRoot>/.minions-package`, and every
+// update is gated against it. A root with no marker is a legacy install — it
+// falls back to the previous behavior with a warning, never a refusal.
+
+/**
+ * The supported way to move an internal runtime forward. Returned as lines
+ * (never executed here) so the CLI can print them verbatim on a refusal. Every
+ * form pins `--runtime-root` so the installer cannot re-resolve to a different
+ * root than the one we just refused to overwrite.
+ *
+ * The root is always double-quoted: runtime roots routinely live under paths
+ * with spaces (`C:\Users\First Last\.minions`), and an unquoted path would make
+ * the printed command fail as `unknown argument`. `--runtime-root` is a real
+ * flag on all three entry points (`bin/install-internal-minions.js#parseArgs`) —
+ * a refusal must print something the operator can paste and run.
+ *
+ * Each line uses the invocation form that actually RUNS on its platform, and
+ * matches the entry points documented in docs/internal-install.md: POSIX needs
+ * the `./` prefix (a bare `scripts/x.sh` is not resolved from a shell), while
+ * PowerShell takes the native backslash path.
+ */
+function buildInternalInstallRemediation({ runtimeRoot, packageName } = {}) {
+  const root = typeof runtimeRoot === 'string' && runtimeRoot ? runtimeRoot : '<runtime root>';
+  const pkg = isValidNpmPackageName(packageName) ? packageName : '<internal package>';
+  const args = `--runtime-root "${root}" --package ${pkg}`;
+  return [
+    `Windows (PowerShell):  scripts\\install-internal-minions.ps1 ${args}`,
+    `Linux / macOS:         ./scripts/install-internal-minions.sh ${args}`,
+    `Any platform:          node bin/install-internal-minions.js ${args}`,
+  ];
+}
+
+/**
+ * Decide whether `minions update` may install `resolvePackageName(pkgRoot)` on
+ * top of the runtime at `runtimeRoot`. Pure: reads two files, shells out to
+ * nothing, and is safe to call before any npm work.
+ *
+ * Returns `{ pkgName, runtimeName, runtimeVersion, allowed, reason, warning,
+ * remediation }` where `reason` is one of:
+ *   - `match`                          — same channel; proceed silently
+ *   - `unknown-runtime-channel`        — legacy root, no marker; proceed + warn
+ *   - `cross-channel`                  — channels differ but the target is not
+ *                                        the public package; proceed + warn
+ *   - `internal-runtime-public-package` — REFUSE: this is the public downgrade
+ */
+function resolveUpdateChannel({ pkgRoot, runtimeRoot } = {}) {
+  const pkgName = resolvePackageName(pkgRoot);
+  const runtime = readRuntimeChannel(runtimeRoot);
+  const runtimeName = runtime ? runtime.name : null;
+  const base = { pkgName, runtimeName, runtimeVersion: runtime ? runtime.version : null, remediation: [] };
+
+  if (!runtimeName) {
+    return {
+      ...base,
+      allowed: true,
+      reason: 'unknown-runtime-channel',
+      warning: `Runtime channel is unknown (no ${RUNTIME_CHANNEL_MARKER} marker) — updating as ${pkgName}; re-run \`minions init\` to record the channel.`,
+    };
+  }
+  if (runtimeName === pkgName) {
+    return { ...base, allowed: true, reason: 'match', warning: null };
+  }
+  // The one unrecoverable direction: an internal runtime being overwritten by
+  // the public package. Never attempt it — the public build is a different,
+  // and typically older, distribution of the same `minions` bin.
+  if (runtimeName !== PUBLIC_PACKAGE_NAME && pkgName === PUBLIC_PACKAGE_NAME) {
+    return {
+      ...base,
+      allowed: false,
+      reason: 'internal-runtime-public-package',
+      warning: null,
+      remediation: buildInternalInstallRemediation({ runtimeRoot, packageName: runtimeName }),
+    };
+  }
+  // Any other mismatch (public runtime → internal package, or internal →
+  // a different internal) is a legitimate cutover. Proceed, but say so.
+  return {
+    ...base,
+    allowed: true,
+    reason: 'cross-channel',
+    warning: `Runtime channel is ${runtimeName} but this update would install ${pkgName} — proceeding with a cross-channel install.`,
+  };
+}
+
+/**
+ * In-channel downgrade guard. `npm view <pkg> version` can resolve BACKWARDS off
+ * a stale local packument (same root cause as the post-install version-advance
+ * check), which silently reinstalls an older build over a newer one. Refuse
+ * unless the operator opts in.
+ *
+ * Numeric comparison via compareDottedVersions — '1.0.9' must not look newer
+ * than '1.0.76'. An unknown installed version can never produce a refusal.
+ */
+function evaluateUpdateDowngrade({ installedVersion, targetVersion, allowDowngrade = false } = {}) {
+  const known = (v) => typeof v === 'string' && isValidNpmVersion(v);
+  if (!known(installedVersion) || !known(targetVersion)) {
+    return { allowed: true, isDowngrade: false, message: null };
+  }
+  if (compareDottedVersions(targetVersion, installedVersion) >= 0) {
+    return { allowed: true, isDowngrade: false, message: null };
+  }
+  if (allowDowngrade) {
+    return { allowed: true, isDowngrade: true, message: `Installing ${targetVersion} over ${installedVersion} (downgrade allowed by --allow-downgrade).` };
+  }
+  return {
+    allowed: false,
+    isDowngrade: true,
+    message: [
+      `The registry resolved ${targetVersion}, which is OLDER than the installed ${installedVersion}.`,
+      'This usually means npm resolved a stale local registry-metadata cache.',
+      'Try:   npm cache clean --force',
+      'Then:  minions update',
+      'To install the older version anyway:  minions update --allow-downgrade',
+    ].join('\n'),
+  };
+}
+
 module.exports = {
+  ROOT_POINTER_PATH,
   MINIONS_DIR,
   ENGINE_DIR,
+  resolveDefinitionDir,
   CRASH_REPORTS_DIR,
   getEngineCrashDiagnosticsEnv,
   pruneCrashDiagnosticsReports,
@@ -9476,9 +10896,16 @@ module.exports = {
   isValidNpmPackageName,
   isValidNpmVersion,
   resolvePackageName,
+  // Install-channel marker (W-ms6b7prf006tef7f-b)
+  RUNTIME_CHANNEL_MARKER,
+  readRuntimeChannel,
   buildNpmViewVersionCommand,
   buildNpmGlobalInstallCommand,
   buildNpmGlobalUninstallCommand,
+  // Update channel authority (W-ms6b7prf006tef7f-d)
+  buildInternalInstallRemediation,
+  resolveUpdateChannel,
+  evaluateUpdateDowngrade,
   nodeSupportsBuiltinSqlite,
   nodeSqliteRemediationLine,
   log,
@@ -9554,6 +10981,7 @@ module.exports = {
   run,
   runFile,
   cleanChildEnv,
+  applyAgentTestLoadSafetyEnv,
   gitEnv,
   parseStreamJsonOutput,
   isStaleResumeSessionSignal, // W-ms0vk9nv000z985b — stale `--resume` session/cwd detection
@@ -9563,24 +10991,36 @@ module.exports = {
   classifyInboxItem,
   isEngineSystemAlert,
   ENGINE_DEFAULTS,
+  QUARANTINE_REF_RETENTION_DAYS, // W-ms87lj8j018j2572 — single source of truth; quarantine-refs.js re-exports these
+  QUARANTINE_REF_RETENTION_MS,
+  resolveQuarantineRetentionMs, // W-ms87rbe601a66d13 — the one seam both quarantine sweeps read the operator override through
   CODEX_SANDBOX_MODES,
   validateCodexSandbox,
   resolveCodexCcSandbox,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
+  resolveAcpHandshakeTimeoutMs, ACP_HANDSHAKE_TIMEOUT_MIN_MS, ACP_HANDSHAKE_TIMEOUT_MAX_MS,
   resolveAgentAllowedTools, resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,
   resolveCreatePrsAsDraft,
+  resolveAutoQaCompletedPrds,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
   WORK_ITEM_PRIORITY, WORK_ITEM_PRIORITY_VALUES, WORK_ITEM_PRIORITY_ERROR_CODE, validateWorkItemPriority,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, isFixLikeWorkType, WORKTREE_REQUIRING_TYPES, LIVE_VALIDATION_WORK_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, isFixLikeWorkType, WORKTREE_REQUIRING_TYPES, LIVE_VALIDATION_WORK_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, isPrPollable, resolveAbandonedPrRepollWindowMs, getPrAbandonedAtMs, stampPrAbandonedAt, clearPrAbandonedAt, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
+  // W-ms5tb6ha016fda10 — explicit, fail-closed control-plane execution surface
+  EXECUTION_SURFACE, EXECUTION_SURFACE_VALUES, CONTROL_PLANE_ELIGIBLE_TYPES, CLOUD_ELIGIBLE_TYPES,
+  isControlPlaneEligibleType, validateExecutionSurface, readDeclaredExecutionSurface, isControlPlaneExecution,
+  isCloudEligibleType, isCloudExecution,
+  // W-ms5tb6ha016fda10 — shared remote-ref refresh serialization + classification
+  isGitRefLockError, withSerializedRemoteRefRefresh, _resetRemoteRefRefreshChainsForTesting,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, COMPLETION_FIELDS,
   resolveTerminalDispatchResult, resolveTerminalWorkerState,
+  DISPATCH_COMPLETION_PATH, acceptCompletionReportForNonce,
   claimDispatchFinalization, releaseDispatchFinalization, waitForDispatchFinalization,
   DEFAULT_AGENT_METRICS,
   DEFAULT_AGENTS,
@@ -9607,6 +11047,10 @@ module.exports = {
   initializeProjectState,
   sameResolvedPath,
   realPathForComparison, // exported for testing
+  realPathForComparisonAsync,
+  pathForComparison,
+  pathForComparisonAsync,
+  mapWithConcurrency,
   getPrLinks,
   addPrLink,
   normalizePrScopeSegment, // exported for testing
@@ -9637,12 +11081,20 @@ module.exports = {
   findPrRecord,
   isPlaceholderPrTitle,
   snapshotPrRecord,
+  PR_AGENT_HUMAN,
+  buildGithubAuthorIdentity,
+  buildAdoAuthorIdentity,
+  normalizePrAuthorIdentity,
+  mergePrAuthorIdentity,
+  prAuthorLabel,
   applyPrFieldDelta,
   normalizePrRecord,
   normalizePrRecords,
   normalizePrLinkItems, // exported for testing
   mergePrLinkItems, // exported for testing
   isContextOnlyPrRecord,
+  isPrAutoFixEnabled,
+  isPrAutoReviewEnabled,
   shouldAdoptPlatformCreated, // W-mrezh0yb0007f733 — platform creationDate authority
   upsertPullRequestRecord,
   collapseDuplicatePrRecords, // P-e9f0a2b4 — one-time repair helper
@@ -9663,6 +11115,11 @@ module.exports = {
 
   computeSourcePlanContentHash, // W-mqfevwr60018bd09 — sha256 of source plan markdown body
   isSourcePlanContentStale, // W-mqfevwr60018bd09 — gate destructive PRD resync on actual content change
+  PRD_REVISION_STATE, // W-msa0mrus00mh466f — canonical revision-requested ⇄ planStale state machine
+  findPrdRevisionWorkItem,
+  derivePrdRevisionState,
+  resolvePrdRevisionFeedback,
+  applyPrdRevisionCompletion,
   sanitizeBranch,
   getOperatorLogin,
   deriveWorkItemBranchName,
@@ -9671,6 +11128,7 @@ module.exports = {
   isWorktreeRootInfraEntry,
   WORKTREE_SCRATCH_DIR_NAME,
   isPathInside,
+  isResolvedPathInsideOrEqual,
   isPathInsideOrEqual,
   pathsOverlap,
   parseWorktreePorcelain,
@@ -9731,6 +11189,7 @@ module.exports = {
   clearWorktreeFailureCache,
   removeWorktree,
   isWorktreePathLive,
+  listLiveWorktreePaths,
   getWorktreeBlockingDispatchInfo,
   WORKTREE_OWNER_MARKER,
   WORKTREE_RETRY_PATH_MARKER,
@@ -9738,8 +11197,11 @@ module.exports = {
   WORKTREE_QUARANTINE_PROTECTED_PATH_TOKEN,
   writeWorktreeOwnerMarker,
   hasWorktreeOwnerMarker,
+  hasWorktreeOwnerMarkerAsync,
   hasProtectedQuarantineMarker,
+  hasProtectedQuarantineMarkerAsync,
   _restoreWorktreeOwnerMarkerAfterFailedRemoval, // exported for testing
+  _verifyWorktreeRemoved, // exported for testing
   isWorktreeOwnerMarkerStatusLine,
   _normalizeWorktreePath, // exported for testing
   _writeWorktreeSkipLiveInboxNote, // exported for testing
@@ -9765,7 +11227,7 @@ module.exports = {
   backfillPrPrdItems,
 };
 
-// Re-export process-management helpers extracted to engine/process-utils.js
+// Re-export process-management helpers extracted to engine/processes/process-utils.js
 // (P-mrb8yg9x001k1401-b) so every existing require('./shared') call keeps
 // working unchanged.
 module.exports = { ...module.exports, ...processUtils };