@yemi33/minions 0.1.2447 → 0.1.2449

package/engine.js

@@ -24,13 +24,13 @@
 // Install ISO timestamp prefixes on console.{log,info,warn,error} so
 // engine-stdio.log is diagnosable to the second. Must run BEFORE any other
 // require that might log during module init.
-require('./engine/stdio-timestamps').installIfNotInstalled();
+require('./engine/core/stdio-timestamps').installIfNotInstalled();
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
-const shared = require('./engine/shared');
+const shared = require('./engine/core/shared');
 const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   WI_STATUS, DONE_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, REVIEW_STATUS, DISPATCH_RESULT, AGENT_STATUS,
   FAILURE_CLASS, resolvePollFlag } = shared;
@@ -40,18 +40,24 @@ const {
   buildSpawnFlags,
   prepareWorkspace,
 } = require('./engine/runtimes');
-const { assertStaleHeadOk } = require('./engine/spawn-agent');
+// Cloud dispatch provider registry (Agency / Copilot cloud / ADO assignment).
+// A DIFFERENT registry from ./engine/runtimes: runtimes describe a local CLI
+// process, cloud providers describe a remote session that authors its own PR.
+// Engine code resolves through this facade and never imports a provider.
+const cloudProviders = require('./engine/cloud');
+const { assertStaleHeadOk } = require('./engine/agents/spawn-agent');
 // P-1d8f0b93 — fleet ACP worker pool + its child_process-shaped facade.
-// NOTE: engine/agent-worker-pool.js is a DIFFERENT module from the
+// NOTE: engine/agents/agent-worker-pool.js is a DIFFERENT module from the
 // dashboard's single-tab CC pool (engine.js must never import that one —
 // see the cc-tab-pool wiring regression guard test).
-const agentWorkerPool = require('./engine/agent-worker-pool');
-const { PooledAgentProcess } = require('./engine/pooled-agent-process');
-const { normalizeExecutionModel } = require('./engine/execution-model');
-const adoGitAuth = require('./engine/ado-git-auth');
-const queries = require('./engine/queries');
-const dispatchEvents = require('./engine/dispatch-events');
-const prdStore = require('./engine/prd-store');
+const agentWorkerPool = require('./engine/agents/agent-worker-pool');
+const { PooledAgentProcess } = require('./engine/agents/pooled-agent-process');
+const { normalizeExecutionModel } = require('./engine/core/execution-model');
+const adoGitAuth = require('./engine/ado/git-auth');
+const queries = require('./engine/core/queries');
+const dispatchEvents = require('./engine/orchestration/dispatch-events');
+const prdStore = require('./engine/planning/prd-store');
+const prdResultSidecar = require('./engine/planning/prd-result-sidecar');
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
 
@@ -132,66 +138,67 @@ const CHECKPOINT_CAP_FAIL_REASON = 'Exceeded 3 checkpoint-resumes; manual interv
 // re-aliased here for the existing call sites in this file.
 const READ_ONLY_ROOT_TASK_TYPES = shared.READ_ONLY_ROOT_TASK_TYPES;
 
-// ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
+// ─── Dispatch Management (extracted to engine/orchestration/dispatch.js) ───────────────────
 
 const { mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason,
-  deferDispatchForWorktreeProtection, completeDispatch,
-  writeInboxAlert, updateAgentStatus, pruneStalePrDispatches, pruneStalePrDispatchesAsync } = require('./engine/dispatch');
+  deferDispatchForWorktreeProtection, completeDispatch, deferDispatchToPending,
+  writeInboxAlert, updateAgentStatus, pruneStalePrDispatches, pruneStalePrDispatchesAsync } = require('./engine/orchestration/dispatch');
 
-// ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
+// ─── Timeout / Steering / Idle (extracted to engine/orchestration/timeout.js) ──────────────
 
-const { checkTimeouts, checkSteering, checkIdleThreshold, dropSteeringForPurgedSession } = require('./engine/timeout');
-const steering = require('./engine/steering');
+const { checkTimeouts, checkSteering, checkIdleThreshold, dropSteeringForPurgedSession } = require('./engine/orchestration/timeout');
+const steering = require('./engine/agents/steering');
 
-// ─── Cleanup (extracted to engine/cleanup.js) ────────────────────────────────
+// ─── Cleanup (extracted to engine/orchestration/cleanup.js) ────────────────────────────────
 
-const { runCleanup } = require('./engine/cleanup');
+const { runCleanup } = require('./engine/orchestration/cleanup');
 
 // ─── Worktree pool (W-mp73ya3e000me6c5 — opt-in cross-branch warm reuse) ────
 
-const worktreePool = require('./engine/worktree-pool');
-const worktreePreflight = require('./engine/worktree-preflight');
+const worktreePool = require('./engine/worktrees/pool');
+const worktreePreflight = require('./engine/worktrees/preflight');
 
-// ─── State Readers (delegated to engine/queries.js) ─────────────────────────
+// ─── State Readers (delegated to engine/core/queries.js) ─────────────────────────
 
 const { getConfig, getControl, getDispatch, getNotes,
   getAgentStatus, getInboxFiles,
   collectSkillFiles, getSkillIndex, getKnowledgeBaseIndex,
   getPrs, SKILLS_DIR } = queries;
 
-// ─── Routing (extracted to engine/routing.js) ───────────────────────────────
+// ─── Routing (extracted to engine/orchestration/routing.js) ───────────────────────────────
 
-const routing = require('./engine/routing');
-const reviewLearning = require('./engine/review-learning');
+const routing = require('./engine/orchestration/routing');
+const reviewLearning = require('./engine/memory/review-learning');
 const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
   getAgentErrorRate, isAgentIdle, resolveAgent, resetClaimedAgents,
   resolveAgentReservation, setTempBudget, tempAgents } = routing;
 
-// ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
+// ─── Playbook, system prompt, agent context (extracted to engine/agents/playbook.js) ─
 
 const { renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS,
   buildSystemPrompt, buildAgentContext, selectPlaybook,
   buildBaseVars, buildPrDispatch, resolveTaskContext,
-  getRepoHost, getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
+  getRepoHost, getRepoHostLabel, getRepoHostToolRule } = require('./engine/agents/playbook');
 
 // Per-slug GitHub PAT resolution — mirrors getAdoToken/MINIONS_ADO_TOKEN.
 // Used at agent spawn time to inject GH_TOKEN for GitHub projects so child
 // `gh`/`git push` calls authenticate as the right account without falling
 // through to an interactive `gh auth login` device-code flow.
-const ghToken = require('./engine/gh-token');
+const ghToken = require('./engine/providers/gh-token');
 
-// ─── Lifecycle (extracted to engine/lifecycle.js) ────────────────────────────
+// ─── Lifecycle (extracted to engine/orchestration/lifecycle.js) ────────────────────────────
 
 const { runPostCompletionHooks, handleQaSessionSetupCompletion, updateWorkItemStatus, syncPrdItemStatus, reconcilePrdStatuses, handlePostMerge, checkPlanCompletion,
   syncPrsFromOutput, updatePrAfterReview, updatePrAfterFix, checkForLearnings, extractSkillsFromOutput,
   updateAgentHistory, updateMetrics, parseAgentOutput, syncPrdFromPrs, persistVerifyPrsToPrd,
   isItemCompleted, classifyFailure: classifyFailureFallback, diagnoseEmptyOutput, processPendingRebases, resolveWorkItemScope,
   mergeArtifactNotes, promoteCompletionArtifacts, pruneScopeMismatchDuplicatePrs, collapseAllDuplicatePrRecords,
-  recordWorktreeHeldPause, clearWorktreeHeldPause } = require('./engine/lifecycle');
+  parseCompletionReportFile,
+  recordWorktreeHeldPause, clearWorktreeHeldPause } = require('./engine/orchestration/lifecycle');
 
 // ─── Diagnostics: memory + event-loop + GC sampler (P-a1b2c3d4 / P-b2c3d4e5) ─
 
-const diagnosticsMemory = require('./engine/diagnostics-memory');
+const diagnosticsMemory = require('./engine/observability/diagnostics-memory');
 const DIAGNOSTICS_MEMORY_PATH = path.join(ENGINE_DIR, 'diagnostics-memory.json');
 
 // P-e5f6a7b8 — sentinel consumed each tick; dashboard.js writes it after
@@ -208,7 +215,7 @@ const realActivityMap = new Map(); // dispatchId → timestamp of last agent std
 const SPAWN_ATTEMPT_ABORTED = Symbol('spawn-attempt-aborted');
 const FOREIGN_SPAWN_LEASE_MAX_AGE_MS = 30 * 60 * 1000;
 const _spawnAttemptLeases = new Map(); // dispatchId → in-flight pre-runtime lease
-// tempAgents imported from engine/routing.js
+// tempAgents imported from engine/orchestration/routing.js
 let engineRestartGraceUntil = 0; // timestamp — suppress orphan detection until this time
 const engineRestartGraceExempt = new Set(); // dispatch IDs with confirmed-dead PIDs at restart — bypass grace period
 
@@ -367,10 +374,19 @@ async function _checkWorktreeBranchHoldForDispatch(project, type, branch, config
   if (!project?.localPath) return null;
   let spawnPaths;
   try {
-    spawnPaths = shared.resolveSpawnPaths(project, type, MINIONS_DIR);
+    spawnPaths = shared.resolveSpawnPaths(project, type, MINIONS_DIR, {
+      executionSurface: _deps.executionSurface,
+    });
   } catch {
     return null; // spawnAgent owns structural path diagnostics
   }
+  // W-ms5tb6ha016fda10: a control-plane dispatch allocates no worktree, so no
+  // operator checkout can hold "its" branch. A cloud dispatch is covered by the
+  // `!spawnPaths.worktreeRootDir` check on the next line — reachable only
+  // because the caller resolves and forwards the CLOUD surface (see the
+  // `_itemSkipsCheckoutAllocation` block in dispatchPending); a caller that
+  // forwarded `repo` for a cloud item would silently get repo-shaped gating.
+  if (spawnPaths.controlPlane) return notApplicable;
   if (spawnPaths.liveMode || !spawnPaths.worktreeRootDir) return notApplicable;
 
   const listWorktrees = _deps.listWorktrees || (repoDir =>
@@ -477,14 +493,24 @@ function _clearWorktreeBranchHeld(dispatchItem) {
   }
 }
 
-function _checkWorktreeDiskSpaceForDispatch(project, type, config) {
+function _checkWorktreeDiskSpaceForDispatch(project, type, config, options = {}) {
   if (!project?.localPath) return null;
   let spawnPaths;
   try {
-    spawnPaths = shared.resolveSpawnPaths(project, type, MINIONS_DIR);
+    spawnPaths = shared.resolveSpawnPaths(project, type, MINIONS_DIR, {
+      executionSurface: options.executionSurface,
+    });
   } catch {
     return null; // spawnAgent owns structural path diagnostics
   }
+  // W-ms5tb6ha016fda10: a control-plane dispatch never runs `git worktree add`,
+  // so worktree free-space capacity is irrelevant to whether it can run. A
+  // cloud dispatch is covered by the `!spawnPaths.worktreeRootDir` check on the
+  // next line — reachable only because the caller resolves and forwards the
+  // CLOUD surface (see the `_itemSkipsCheckoutAllocation` block in
+  // dispatchPending); a caller that forwarded `repo` for a cloud item would
+  // silently subject it to a disk preflight it can never legitimately fail.
+  if (spawnPaths.controlPlane) return null;
   if (spawnPaths.liveMode || !spawnPaths.worktreeRootDir) return null;
   const worktreeRoot = path.resolve(
     spawnPaths.worktreeRootDir,
@@ -738,11 +764,133 @@ function buildDepConflictFixItem({
     featureBranch: depConflictBranch,
     _branch: depConflictBranch,
     _blockedItem: blockedItem ? blockedItem.id : null,
+    // W-mrzqfozm00035365 — track EVERY downstream item blocked by this dep
+    // conflict (not just the first), so completing the repair can wake all of
+    // them and restart/reconciliation can rebuild the links idempotently.
+    _blockedItems: blockedItem ? [blockedItem.id] : [],
     _isInterDepConflict: !!isInterDepConflict,
     project: projectName || null,
   };
 }
 
+// ─── W-mrzqfozm00035365: recoverable dependency merge-conflict gate ──────────
+// A dependency-branch merge conflict is detected in spawnAgent BEFORE the agent
+// process starts. It is NOT an execution failure of the downstream item and must
+// not burn its retry budget or drive it to terminal `failed` while the
+// deterministic conflict-repair WI is still being worked. Instead the downstream
+// item is stamped with a `_dependencyConflict` marker + `_pendingReason` and
+// held pending; the helpers below make the orchestration decisions pure and
+// unit-testable.
+const DEP_CONFLICT_PENDING_REASON = 'dependency_conflict';            // repair in progress — auto-clears
+const DEP_CONFLICT_UNRESOLVED_PENDING_REASON = 'dependency_conflict_unresolved'; // repair failed/cancelled or still conflicting — actionable block
+const DEP_CONFLICT_FIX_CREATED_BY = 'engine:dep-conflict-fix';
+
+// Build the marker stamped on a downstream WI when its dependency branches
+// conflict. `files` is capped so the persisted record stays small.
+function buildDependencyConflictMarker({
+  repairWiId,
+  conflictBranch,
+  conflictsWith,
+  isInterDep = false,
+  files = [],
+  detectedAt = null,
+}) {
+  return {
+    repairWiId: repairWiId || null,
+    conflictBranch: conflictBranch || null,
+    conflictsWith: conflictsWith || null,
+    isInterDep: !!isInterDep,
+    files: Array.isArray(files) ? files.slice(0, 10) : [],
+    detectedAt: detectedAt || ts(),
+  };
+}
+
+// Locate the deterministic conflict-repair WI for a blocked downstream item.
+// Prefers the id recorded on the marker; falls back to the persisted
+// back-reference (`_blockedItems` / legacy `_blockedItem`) so links survive
+// even when the marker was never written (legacy terminal-failed items).
+function findConflictRepairForBlockedItem(itemId, allItems, markerRepairId = null) {
+  if (!Array.isArray(allItems)) return null;
+  if (markerRepairId) {
+    const byId = allItems.find(w => w && w.id === markerRepairId);
+    if (byId) return byId;
+  }
+  return allItems.find(w =>
+    w && w.createdBy === DEP_CONFLICT_FIX_CREATED_BY
+    && ((Array.isArray(w._blockedItems) && w._blockedItems.includes(itemId)) || w._blockedItem === itemId)
+  ) || null;
+}
+
+// Decide what to do with a downstream item held on a dependency merge conflict,
+// given the current state of its conflict-repair WI. Pure + deterministic.
+//   downstream: the blocked WI (carries `_dependencyConflict`)
+//   repair:     the conflict-fix WI (or null when not yet materialized / pruned)
+//   nowMs:      Date.now() (injectable for tests; unused today but kept for parity)
+// Returns { action, pendingReason, reason }:
+//   'wait'  → keep pending, repair still in progress (never redispatch into the
+//             same conflict)
+//   'wake'  → clear the marker so the item re-runs dependency integration on
+//             freshly-fetched refs
+//   'block' → keep pending with an actionable unresolved reason and DO NOT loop
+function evaluateDependencyConflictGate(downstream, repair, nowMs = Date.now()) {
+  const marker = downstream && downstream._dependencyConflict;
+  if (!marker) {
+    return { action: 'wake', pendingReason: null, reason: 'no active dependency-conflict marker' };
+  }
+  if (!repair) {
+    // Repair not found yet (creation race, or store not visible this tick).
+    // Hold — the detection path (re)creates it; never redispatch blindly.
+    return { action: 'wait', pendingReason: DEP_CONFLICT_PENDING_REASON, reason: 'conflict-repair work item not found yet' };
+  }
+  const st = repair.status;
+  if (st === WI_STATUS.FAILED || st === WI_STATUS.CANCELLED) {
+    return {
+      action: 'block',
+      pendingReason: DEP_CONFLICT_UNRESOLVED_PENDING_REASON,
+      reason: `conflict-repair ${repair.id} is ${st}`,
+    };
+  }
+  if (DONE_STATUSES.has(st)) {
+    // Wake only if the repair completed AFTER we detected THIS conflict. A repair
+    // that completed BEFORE (or exactly at) detection means the freshly-fetched
+    // merge still conflicts despite the repair — block instead of looping.
+    const detectedAtMs = marker.detectedAt ? Date.parse(marker.detectedAt) : NaN;
+    const completedAtMs = repair.completedAt ? Date.parse(repair.completedAt) : NaN;
+    const repairAfterDetection = (Number.isFinite(completedAtMs) && Number.isFinite(detectedAtMs))
+      ? completedAtMs >= detectedAtMs
+      : true; // missing timestamps → wake once (repair is done)
+    if (repairAfterDetection) {
+      return { action: 'wake', pendingReason: null, reason: `conflict-repair ${repair.id} done` };
+    }
+    return {
+      action: 'block',
+      pendingReason: DEP_CONFLICT_UNRESOLVED_PENDING_REASON,
+      reason: `conflict-repair ${repair.id} completed before the conflict was re-detected — dependency branches still conflict`,
+    };
+  }
+  // pending / dispatched / decomposed / paused → still being repaired.
+  return { action: 'wait', pendingReason: DEP_CONFLICT_PENDING_REASON, reason: `conflict-repair ${repair.id} in progress (${st})` };
+}
+
+// Reconciliation (requirement 7): should a terminally-FAILED item be revived to
+// pending because it failed on a dependency merge conflict AND its deterministic
+// repair WI is live (pending/dispatched) or done? Guards against reviving
+// unrelated failures: only fires for MERGE_CONFLICT-class failures linked to a
+// repair WI that is not itself terminal-dead. Pure + deterministic.
+function shouldReviveFailedDependencyConflict(failedItem, repair) {
+  if (!failedItem || failedItem.status !== WI_STATUS.FAILED) return false;
+  const fc = failedItem._failureClass || '';
+  const fr = String(failedItem.failReason || '');
+  const looksLikeDepConflict = fc === FAILURE_CLASS.MERGE_CONFLICT
+    || /\bMERGE_CONFLICT\b/i.test(fr)
+    || /Dependency merge failed/i.test(fr);
+  if (!looksLikeDepConflict) return false;
+  if (!repair) return false;
+  // The repair must be actively repairing or already done — not itself dead.
+  if (repair.status === WI_STATUS.FAILED || repair.status === WI_STATUS.CANCELLED) return false;
+  return true;
+}
+
 // Prune dep branches that are ancestors of other dep branches (#958)
 // When B already contains A's commits, merging both A and B causes conflicts.
 async function pruneAncestorDeps(deps, gitOpts, cwd) {
@@ -821,6 +969,10 @@ function _buildAgentSpawnFlags(runtime, opts = {}) {
 function _syncAgentWorkerPoolConfig(engineConfig = {}) {
   const enabled = (engineConfig.agentUseWorkerPool ?? ENGINE_DEFAULTS.agentUseWorkerPool) === true;
   agentWorkerPool.setEnabled(enabled);
+  // Issue #1105 — cold ACP handshake budget (`initialize` + `session/new` /
+  // `session/load`). Pushed unconditionally so a pool enabled later in the same
+  // process already carries the operator-configured budget.
+  agentWorkerPool.setHandshakeTimeoutMs(shared.resolveAcpHandshakeTimeoutMs(engineConfig));
   if (enabled) agentWorkerPool.setPoolSize(shared.resolveAgentAcpPoolSize(engineConfig));
   return enabled;
 }
@@ -956,7 +1108,18 @@ function _classifyAgentFailure(runtime, code, stdout, stderr) {
 function ackPendingSteeringFiles(agentId, procInfo, rawOutput, observedAtMs = Date.now()) {
   if (!procInfo?._pendingSteeringFiles?.length || !rawOutput) return;
   if (procInfo._steeringMessage || procInfo._steeringNoSession) return;
-  const acked = steering.ackProcessedSteeringMessages(agentId, procInfo._pendingSteeringFiles, rawOutput, { observedAtMs });
+  let acked;
+  try {
+    acked = steering.ackProcessedSteeringMessages(
+      agentId,
+      procInfo._pendingSteeringFiles,
+      rawOutput,
+      { observedAtMs },
+    );
+  } catch (err) {
+    log('warn', `Steering ACK persistence failed for ${agentId}: ${err.message}`);
+    return;
+  }
   if (acked.length === 0) return;
 
   const ackedPaths = new Set(acked.map(entry => entry.path));
@@ -977,17 +1140,21 @@ function captureSessionIdFromStdoutChunk(agentId, dispatchId, branchName, runtim
     if (!sessionId) continue;
     procInfo.sessionId = sessionId;
     if (runtime && typeof runtime.saveSession === 'function') {
-      runtime.saveSession({
-        agentId,
-        dispatchId,
-        branch: branchName,
-        sessionId,
-        agentsDir: AGENTS_DIR,
-        // W-ms0vk9nv000z985b — the directory this session is anchored to. A
-        // later dispatch refuses to --resume it once that directory is gone.
-        cwd: sessionCwd || null,
-        logger: _runtimeLogger(),
-      });
+      try {
+        runtime.saveSession({
+          agentId,
+          dispatchId,
+          branch: branchName,
+          sessionId,
+          agentsDir: AGENTS_DIR,
+          // W-ms0vk9nv000z985b — the directory this session is anchored to. A
+          // later dispatch refuses to --resume it once that directory is gone.
+          cwd: sessionCwd || null,
+          logger: _runtimeLogger(),
+        });
+      } catch (err) {
+        log('warn', `Could not persist runtime session for ${dispatchId}: ${err.message}`);
+      }
     }
 
     return;
@@ -1097,7 +1264,7 @@ function promoteCheckpointSteeringForClose(agentId, procInfo, runtime, liveOutpu
   // 're_spawning' — captures that the engine has committed to deliver
   // these messages via session resume at the natural checkpoint.
   try {
-    const store = require('./engine/steering-store');
+    const store = require('./engine/persistence/steering-store');
     for (const entry of checkpointEntries) {
       if (entry?.steerId) {
         store.updateStatus(entry.steerId, 're_spawning', { runtime: runtime?.name || null });
@@ -1107,6 +1274,85 @@ function promoteCheckpointSteeringForClose(agentId, procInfo, runtime, liveOutpu
   return { status: 'promoted', entries: checkpointEntries };
 }
 
+// W-ms9tcs3o01y03383 — the prompt completion boundary, as one decision.
+//
+// A dispatch is provably finished when BOTH halves hold:
+//   1. the tracked child exited terminally and successfully (`code === 0`, which
+//      the caller only has once the `close` event fired), and
+//   2. a structurally valid completion report exists whose nonce proves it was
+//      written by THIS dispatch (the nonce is minted per spawn and carried
+//      across steering resumes).
+//
+// Fails closed on every other shape: non-zero exit, missing report, malformed
+// report, missing/forged nonce. Those keep the existing failure/timeout paths
+// untouched — nothing here weakens success validation.
+function resolveCloseCompletionBoundary(dispatchItem, code, expectedNonce, readReport = parseCompletionReportFile) {
+  if (code !== 0) return null;
+  try {
+    return shared.acceptCompletionReportForNonce(readReport(dispatchItem), expectedNonce);
+  } catch (e) {
+    log('warn', `close completion-report probe failed for ${dispatchItem?.id}: ${e.message}`);
+    return null;
+  }
+}
+
+// W-ms9tcs3o01y03383 — after a confirmed terminal exit whose completion report
+// is structurally valid AND owned by this dispatch's nonce, the prompt is
+// finished. A steering resume from that point is pure bookkeeping: it cannot
+// change the completed turn, but it CAN hold the dispatch open for a full
+// `engine.resumeHeartbeatTimeout` when the resumed runtime never emits a first
+// heartbeat (observed 310s on lambert-plan-to-prd-ms9skh2q01a91a35 — the whole
+// point of this work item).
+//
+// So we release the resume intent instead of spawning it, and deliberately do
+// NOT ack/consume the steering messages: they stay UNREAD on disk, so the
+// agent's next dispatch picks them up through the normal
+// steering.buildPendingSteeringPrompt path. That is the same durability
+// contract the existing no-sessionId `[steering-pending]` branch relies on, and
+// it matches what the human was already told when the message was deferred
+// ("queued until the agent reaches a resumable checkpoint or the next dispatch").
+//
+// The same rule applies to every other steering disposition that would override
+// durable completion evidence, including the `_steeringNoSession` re-queue.
+function releasePendingSteeringResumeForCompletedTurn(agentId, procInfo, liveOutputPath) {
+  if (!procInfo) return { released: false, deferred: 0, entries: [] };
+  const entries = Array.isArray(procInfo._steeringEntry)
+    ? procInfo._steeringEntry
+    : (procInfo._steeringEntry ? [procInfo._steeringEntry] : []);
+  const released = !!procInfo._steeringMessage || !!procInfo._steeringNoSession;
+  delete procInfo._steeringMessage;
+  delete procInfo._steeringSessionId;
+  delete procInfo._steeringEntry;
+  delete procInfo._steeringDeferredCheckpoint;
+  // The no-session steering kill (#1014) re-queues the dispatch back to pending
+  // so the message rides along on the next attempt. That is right for an agent
+  // that was interrupted mid-work — and wrong for one that provably finished,
+  // because it discards a real success and re-runs completed work. Clearing the
+  // flag lets the report finalize the dispatch; the message is unread either
+  // way, so the next dispatch still delivers it.
+  delete procInfo._steeringNoSession;
+
+  let unread = [];
+  try { unread = steering.listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim()); }
+  catch { /* inbox read is best-effort — the release itself must still happen */ }
+  if (!released && unread.length === 0) return { released: false, deferred: 0, entries: [] };
+
+  // Roll any row we had already moved to `re_spawning` back to `queued` so the
+  // dashboard does not advertise a resume that intentionally never ran.
+  try {
+    const store = require('./engine/persistence/steering-store');
+    for (const entry of entries) {
+      if (entry?.steerId) store.updateStatus(entry.steerId, 'queued');
+    }
+  } catch { /* best-effort */ }
+
+  log('info', `Steering: ${agentId} finished its turn with a valid completion report — ${unread.length} message(s) stay unread for the next dispatch instead of holding the dispatch open for a resume`);
+  try {
+    fs.appendFileSync(liveOutputPath, `\n[steering-pending] Agent completed this task and wrote a valid completion report, so no resume was started. Your message remains unread and will be delivered on the next dispatch.\n`);
+  } catch { /* optional */ }
+  return { released, deferred: unread.length, entries };
+}
+
 // Resolve dependency plan item IDs to their PR branches
 function resolveDependencyBranches(depIds, sourcePlan, project, config) {
   // P-faea3206: each entry now carries projectName + projectRoot + isCrossRepo
@@ -1221,7 +1467,13 @@ async function syncReusedWorktree(rootDir, worktreePath, branchName, gitOpts = {
   // auto-pick-up master mid-flight, so the carve-out is explicit.
   const { mainRef, isSharedBranch } = opts;
   if (mainRef && !isSharedBranch) {
-    try { await shared.shellSafeGit(['fetch', 'origin', mainRef], { ...gitOpts, cwd: rootDir }); }
+    // W-ms5tb6ha016fda10: serialize the shared-ref refresh (see
+    // _fetchWithTransientRetry). Only the fetch is inside the chain — the
+    // merge below is per-worktree work and must NOT be serialized with it.
+    try {
+      await shared.withSerializedRemoteRefRefresh(rootDir, () =>
+        shared.shellSafeGit(['fetch', 'origin', mainRef], { ...gitOpts, cwd: rootDir }));
+    }
     catch (e) { log('warn', `git: failed to fetch origin/${mainRef} during reuse-sync: ${e.message}`); }
     try { await shared.shellSafeGit(['merge', `origin/${mainRef}`, '--no-edit', '--no-ff'], { ...gitOpts, cwd: worktreePath }); }
     catch (e) {
@@ -1336,13 +1588,29 @@ function _isTransientGitNetworkError(err) {
 //
 // `args` is the array passed to git AFTER 'fetch' (e.g. ['origin', branch]).
 // `label` is a short string used in the log line for triage.
+//
+// W-ms5tb6ha016fda10 — every attempt runs inside
+// `shared.withSerializedRemoteRefRefresh(<repo>)`. Concurrent fresh-worktree
+// preparation in the SAME clone used to race on `refs/remotes/origin/<main>`
+// and the loser died with `cannot lock ref ... but expected <sha>`, which then
+// classified as a bogus NETWORK_ERROR. Chaining per repo removes that race at
+// its source; the chain is keyed on `opts.cwd`, so unrelated projects still
+// fetch in parallel. The lock is in-process and covers ONLY the fetch — no
+// worktree add / checkout / merge work is serialized with it. A residual
+// cross-process ref-lock loss (an operator's own git, the dashboard, the CLI)
+// is treated as a transient worth one retry, and is classified as
+// GIT_REF_LOCK rather than a connectivity failure.
 async function _fetchWithTransientRetry(args, opts, label, { throwOnFailure = false } = {}) {
-  const _attempt = async () => shared.shellSafeGit(['fetch', ...args], opts);
+  const _attempt = async () => shared.withSerializedRemoteRefRefresh(
+    opts?.cwd,
+    () => shared.shellSafeGit(['fetch', ...args], opts),
+  );
   try {
     await _attempt();
     return true;
   } catch (e) {
-    if (!_isTransientGitNetworkError(e)) {
+    const refLock = shared.isGitRefLockError(e);
+    if (!refLock && !_isTransientGitNetworkError(e)) {
       // #3045 — log the FULL exec error message (redacted), not just the first
       // line. child_process.exec rejections format as "Command failed: <cmd>"
       // on line 1 and the real stderr ("TF400813 unknown user", "HTTP 401",
@@ -1356,7 +1624,7 @@ async function _fetchWithTransientRetry(args, opts, label, { throwOnFailure = fa
       return false; // swallow non-transient — caller falls back to local ref
     }
     const transientMsg = adoGitAuth.redactBearer(String(e.message || e));
-    log('warn', `git fetch ${label}: transient (${transientMsg}) — retrying once after 1.5s`);
+    log('warn', `git fetch ${label}: ${refLock ? 'ref-lock contention' : 'transient'} (${transientMsg}) — retrying once after 1.5s`);
     await new Promise(r => setTimeout(r, 1500));
     try {
       await _attempt();
@@ -1372,6 +1640,11 @@ async function _fetchWithTransientRetry(args, opts, label, { throwOnFailure = fa
 }
 
 function _classifyFreshBaseFetchFailure(err) {
+  // Order matters: a lost ref-lock race is a LOCAL serialization defect, not
+  // connectivity. Classifying it as NETWORK_ERROR (the historical behavior)
+  // hid the real cause behind a "flaky network" story and burned retries on
+  // maintenance jobs that never needed a checkout at all.
+  if (shared.isGitRefLockError(err)) return FAILURE_CLASS.GIT_REF_LOCK;
   return adoGitAuth.isAdoAuthFailure(err)
     ? FAILURE_CLASS.AUTH
     : FAILURE_CLASS.NETWORK_ERROR;
@@ -1841,32 +2114,34 @@ function _reapProbeTimeoutMs() {
   return ENGINE_DEFAULTS.statusProbeKillTimeoutMs || 12000;
 }
 
-// W-mq5n1zx5 — Layer 2a: on Windows, kill any live `git.exe` descendants
-// whose command line points at the quarantine target path. We never
-// tracked the PID of the `git status --porcelain` child that the probe
-// timed out on, so we can't kill by PID — instead we shell out to
-// PowerShell's CIM cmdlets to find matching processes and Stop-Process
-// them. POSIX is a no-op (the EBUSY race is Windows-specific). Best-effort;
-// failure is logged but never blocks the quarantine.
-function _killGitDescendantsForWorktree(worktreePath) {
+// W-mq5n1zx5 — Layer 2a: on Windows, terminate live `git.exe` processes whose
+// command line proves they target the quarantine path. POSIX is a no-op (the
+// EBUSY race is Windows-specific). Best-effort; failure never blocks quarantine.
+function _killGitDescendantsForWorktree(worktreePath, opts = {}) {
   if (process.platform !== 'win32') return { killed: 0, skipped: true };
   if (!ENGINE_DEFAULTS.statusProbeKillDescendantsWin32) return { killed: 0, skipped: true };
   if (!worktreePath) return { killed: 0, skipped: true };
-  // PowerShell expects single-quoted literals; escape any embedded single
-  // quote by doubling it (PowerShell's standard single-quote escape).
-  const safePath = String(worktreePath).replace(/'/g, "''");
-  const ps = [
-    "$ErrorActionPreference='SilentlyContinue';",
-    `$matches = Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'git.exe' -and $_.CommandLine -like '*${safePath}*' };`,
-    "if ($matches) { $matches | ForEach-Object { Stop-Process -Id $_.ProcessId -Force; $_.ProcessId }; }",
-  ].join(' ');
   try {
-    const out = shared.execSilent(`powershell -NoProfile -Command "${ps.replace(/"/g, '\\"')}"`, { timeout: _reapProbeTimeoutMs(), encoding: 'utf8' });
-    const killed = String(out || '').split(/\r?\n/).map(s => s.trim()).filter(Boolean).length;
+    const target = path.resolve(worktreePath).replace(/\//g, '\\').toLowerCase();
+    const processes = Array.isArray(opts.processes) ? opts.processes : shared.listAllProcesses();
+    const matches = processes
+      .filter(proc => String(proc?.name || '').toLowerCase() === 'git.exe')
+      .filter(proc => String(proc?.cmd || '').replace(/\//g, '\\').toLowerCase().includes(target));
+    const pids = matches.map(proc => proc.pid);
+    const expectedIdentities = new Map(
+      matches.map(proc => [Number(proc.pid), Number(proc.startedAt)]),
+    );
+    let killed = 0;
+    if (pids.length > 0) {
+      const ownership = { expectedIdentities };
+      killed = opts.terminateProcess
+        ? opts.terminateProcess('engine.git-status-probe-cleanup', pids, ownership)
+        : shared.terminateProcess('engine.git-status-probe-cleanup', pids, ownership);
+    }
     if (killed > 0) log('info', `_killGitDescendantsForWorktree: killed ${killed} git.exe descendant(s) holding ${worktreePath}`);
     return { killed };
   } catch (e) {
-    log('warn', `_killGitDescendantsForWorktree: powershell probe failed: ${e.message}`);
+    log('warn', `_killGitDescendantsForWorktree: process probe failed: ${e.message}`);
     return { killed: 0, error: e.message };
   }
 }
@@ -1888,11 +2163,11 @@ function _findTerminalWorktreeOwners(worktreePath, _deps = {}) {
   try {
     const reader = typeof _deps.readDispatchSectioned === 'function'
       ? _deps.readDispatchSectioned
-      : require('./engine/dispatch-store').readDispatchSectioned;
+      : require('./engine/persistence/dispatch-store').readDispatchSectioned;
     sectioned = reader();
   } catch {
     try {
-      sectioned = require(path.join(__dirname, 'engine', 'dispatch-store')).readDispatchSectioned();
+      sectioned = require(path.join(__dirname, 'engine', 'persistence', 'dispatch-store')).readDispatchSectioned();
     } catch { return []; }
   }
   if (!sectioned || typeof sectioned !== 'object') return [];
@@ -1979,7 +2254,7 @@ function _reapWorktreeHolders(worktreePath, opts = {}) {
 
   // Layer 0 — legacy git.exe-by-cmdline sweep. NOT redundant with Layer 2
   // (P-e2a6c9d4, evaluated): Layer 2 (findProcessCwdHolders) matches purely on a
-  // process's CWD resolving at/under THIS worktree (engine/shared.js
+  // process's CWD resolving at/under THIS worktree (engine/core/shared.js
   // _windowsCwdProbeScript + _parseCwdHolderLines filter on cwd only). Layer 0
   // matches `git.exe` by `CommandLine -like '*<worktreePath>*'` regardless of CWD.
   // The case Layer 2 cannot see: a git.exe the engine itself spawns FROM the repo
@@ -3433,7 +3708,17 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
 
   const qaRunId = meta?.qaRunId || meta?.item?.meta?.qaRunId;
   if (qaRunId) {
-    require('./engine/qa-runs').prepareResultSidecar(agentId, qaRunId);
+    require('./engine/qa/runs').prepareResultSidecar(agentId, qaRunId);
+  }
+
+  // W-msb9kgs402813a97-b — same contract for the DRAFT visual-journey
+  // manifest. Load-bearing on the re-draft path (`editDraft` re-queues DRAFT
+  // for the SAME session id): a leftover manifest would pass the session-id
+  // check and be consumed as if it described the new draft.
+  const qaSessionIdForSpawn = meta?.sessionId || meta?.item?.meta?.sessionId;
+  const qaSessionPhaseForSpawn = meta?.sessionPhase || meta?.item?.meta?.sessionPhase;
+  if (qaSessionIdForSpawn && qaSessionPhaseForSpawn === 'draft') {
+    require('./engine/qa/visual-journey').prepareDraftResultSidecar(agentId, qaSessionIdForSpawn);
   }
 
   // W-mp73x32w000l143d: decouple agent cwd from worktree placement.
@@ -3492,10 +3777,100 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   }
   const validatedWorkdir = _wdValidation.value;  // null when unset / empty
 
-  let cwd, worktreeRootDir, liveMode = false, readOnlyWorktree = false;
+  // ── Control-plane execution surface (W-ms5tb6ha016fda10) ──────────────
+  // Explicit, structured opt-out of repository checkout for tasks whose whole
+  // contract is Minions/dashboard REST calls plus external CLIs (`gh`, `az`).
+  // Never inferred from prose. Validation is fail-closed at the ALLOWLIST in
+  // shared.CONTROL_PLANE_ELIGIBLE_TYPES, so a repo-mutating type that declares
+  // `control-plane` is REJECTED here rather than quietly losing its worktree.
+  // The dashboard/scheduler validate on create; this is the defense-in-depth
+  // gate for ad-hoc dispatches and pre-validator work items.
+  const _rawSurface = meta?.item?.meta?.executionSurface ?? meta?.executionSurface;
+  const _surfaceValidation = shared.validateExecutionSurface(_rawSurface, type);
+  if (!_surfaceValidation.valid) {
+    const _wiId = meta?.item?.id || meta?.workItemId || id;
+    log('warn', `spawnAgent: executionSurface validation rejected dispatch ${id} (WI ${_wiId}): ${_surfaceValidation.error}`);
+    try {
+      writeInboxAlert(`invalid-execution-surface-${_wiId}`, [
+        `# Invalid meta.executionSurface on ${_wiId}`,
+        ``,
+        `Dispatch \`${id}\` for agent \`${agentId}\` (type \`${type}\`) was rejected before spawn.`,
+        ``,
+        `**Reason:** ${_surfaceValidation.error}`,
+        ``,
+        `**Submitted value:** \`${typeof _rawSurface === 'string' ? _rawSurface : JSON.stringify(_rawSurface)}\``,
+        ``,
+        `\`meta.executionSurface\` is an explicit declaration, never inferred. Valid values are \`repo\` (default — normal worktree/live checkout), \`control-plane\` (no repository checkout; the task only calls the Minions API / external CLIs), and \`cloud\` (handed to a remote coding agent that authors its own PR). Only these work types may declare \`control-plane\`: ${[...shared.CONTROL_PLANE_ELIGIBLE_TYPES].sort().join(', ')}. Only these may declare \`cloud\`: ${[...shared.CLOUD_ELIGIBLE_TYPES].sort().join(', ')}.`,
+        ``,
+        `Fix the WI's \`meta.executionSurface\` (or remove it) and re-dispatch.`,
+      ].join('\n'));
+    } catch (e) { log('warn', `invalid-execution-surface inbox alert write failed: ${e.message}`); }
+    completeDispatch(
+      id,
+      DISPATCH_RESULT.ERROR,
+      _surfaceValidation.error.slice(0, 800),
+      'meta.executionSurface validation rejected this dispatch — fix or remove the field before re-dispatch.',
+      { failureClass: FAILURE_CLASS.INVALID_EXECUTION_SURFACE, agentRetryable: false },
+    );
+    cleanupTempAgent(agentId);
+    return null;
+  }
+  const executionSurface = _surfaceValidation.value;
+  const isControlPlane = executionSurface === shared.EXECUTION_SURFACE.CONTROL_PLANE;
+
+  // ── Cloud execution surface — fail-closed provider gate ────────────────
+  // A validly-declared `cloud` item is handed to a REMOTE coding agent; it
+  // must never quietly fall through to a local dispatch, because the two
+  // produce different work in different places under different identities.
+  // So the gate refuses the dispatch unless a configured provider resolves,
+  // and (until the hand-off itself lands) refuses it even when one does.
+  //
+  // Every refusal here is STRUCTURAL — an unregistered/undeclared provider or
+  // one that reports itself unconfigured reproduces identically on retry — so
+  // it is non-retryable and must not consume the item's retry budget.
+  if (executionSurface === shared.EXECUTION_SURFACE.CLOUD) {
+    const _wiId = meta?.item?.id || meta?.workItemId || id;
+    const _cloudTarget = cloudProviders.resolveCloudDispatchTarget({
+      item: meta?.item || meta,
+      project,
+      engine: config?.engine,
+      config,
+    });
+    const _cloudReason = _cloudTarget.ok
+      ? `cloud provider "${_cloudTarget.id}" is registered and configured, but the cloud dispatch `
+        + `hand-off is not implemented yet — the engine refuses to run cloud-declared work locally`
+      : _cloudTarget.reason;
+    log('warn', `spawnAgent: cloud dispatch ${id} (WI ${_wiId}) refused: ${_cloudReason}`);
+    try {
+      writeInboxAlert(`cloud-provider-unavailable-${_wiId}`, [
+        `# Cloud dispatch refused for ${_wiId}`,
+        ``,
+        `Dispatch \`${id}\` for agent \`${agentId}\` (type \`${type}\`) declared \`meta.executionSurface: "cloud"\` but was not sent anywhere.`,
+        ``,
+        `**Reason:** ${_cloudReason}`,
+        ``,
+        `**Registered providers:** ${cloudProviders.listCloudProviders().join(', ') || '(none)'}`,
+        ``,
+        `The engine never downgrades a cloud declaration to a local dispatch — a remote agent works in its own checkout, under its own identity, and opens its own PR, so silently running it here would produce different work than was asked for.`,
+        ``,
+        `Either configure a cloud provider (\`meta.cloudProvider\` on the WI, \`cloudProvider\` on the project, or \`engine.cloudProvider\`) or remove \`meta.executionSurface\` to dispatch locally.`,
+      ].join('\n'));
+    } catch (e) { log('warn', `cloud-provider-unavailable inbox alert write failed: ${e.message}`); }
+    completeDispatch(
+      id,
+      DISPATCH_RESULT.ERROR,
+      _cloudReason.slice(0, 800),
+      'Cloud dispatch refused — no usable cloud provider for this work item.',
+      { failureClass: FAILURE_CLASS.CLOUD_PROVIDER_UNAVAILABLE, agentRetryable: false },
+    );
+    cleanupTempAgent(agentId);
+    return null;
+  }
+
+  let cwd, worktreeRootDir, liveMode = false, readOnlyWorktree = false, controlPlane = false;
   try {
-    ({ cwd, worktreeRootDir, liveMode = false, readOnlyWorktree = false } =
-      shared.resolveSpawnPaths(project, type, MINIONS_DIR, { workdir: validatedWorkdir }));
+    ({ cwd, worktreeRootDir, liveMode = false, readOnlyWorktree = false, controlPlane = false } =
+      shared.resolveSpawnPaths(project, type, MINIONS_DIR, { workdir: validatedWorkdir, executionSurface }));
   } catch (rootErr) {
     if (rootErr?.code === 'WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT' || rootErr?.code === 'WORKTREE_ROOTDIR_MISSING_BASE') {
       log('error', `spawnAgent: project rootDir resolution failed for ${id}: ${rootErr.message}`);
@@ -3551,6 +3926,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     ? { name: project.name, localPath: project.localPath }
     : null;
   dispatchItem.checkoutMode = checkoutModeAtDispatch;
+  dispatchItem.executionSurface = executionSurface;
   if (resolvedProjectMeta && dispatchItem.meta) {
     dispatchItem.meta.project = resolvedProjectMeta;
   }
@@ -3560,6 +3936,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         const found = (dispatch?.[queue] || []).find(d => d && d.id === id);
         if (!found) continue;
         found.checkoutMode = checkoutModeAtDispatch;
+        found.executionSurface = executionSurface;
         if (resolvedProjectMeta && found.meta) found.meta.project = resolvedProjectMeta;
       }
       return dispatch;
@@ -3567,6 +3944,13 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   } catch (e) {
     log('warn', `spawnAgent: failed to persist checkout context for ${id}: ${e.message}`);
   }
+  if (controlPlane) {
+    // Observability: the dispatch record itself carries `executionSurface`, so
+    // "how many checkouts did the control-plane surface avoid?" is derived
+    // from dispatch history by GET /api/worktree-inventory — no extra counter
+    // state to migrate or drift.
+    log('info', `${type}: control-plane dispatch ${id} — no repository checkout allocated; cwd ${cwd}`);
+  }
   // Legacy local alias: downstream git ops (worktree add, prune, fetch) and
   // the `cwd === rootDir` safety warn at line ~1387 reference `rootDir`. For
   // read-only rootless tasks (no worktree, no branch) this is null — the
@@ -3578,7 +3962,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   // allocation probe and checkout. This runs before prompt/worktree creation
   // and leaves the existing dispatch pending rather than completing it as an
   // agent failure.
-  const _spawnDiskPreflight = _checkWorktreeDiskSpaceForDispatch(project, type, config);
+  const _spawnDiskPreflight = _checkWorktreeDiskSpaceForDispatch(project, type, config, { executionSurface });
   if (_spawnDiskPreflight && !_spawnDiskPreflight.ok) {
     const pendingReason = _persistWorktreeDiskPreflight(dispatchItem, _spawnDiskPreflight);
     _writeWorktreeDiskPreflightAlert(dispatchItem, project, _spawnDiskPreflight);
@@ -3597,6 +3981,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     type,
     _preBranchName,
     config,
+    { executionSurface },
   );
   if (spawnAttemptLease && !_isSpawnAttemptCurrent(spawnAttemptLease)) {
     return SPAWN_ATTEMPT_ABORTED;
@@ -3651,7 +4036,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   // engine compares report.nonce against the in-memory value below; on
   // mismatch the report is treated as forged (e.g. a prompt-injected agent
   // writing into a sibling agent's completion path) and discarded. See
-  // engine/lifecycle.js:runPostCompletionHooks and docs/completion-reports.md.
+  // engine/orchestration/lifecycle.js:runPostCompletionHooks and docs/completion-reports.md.
   const completionNonce = crypto.randomBytes(16).toString('hex');
   const completionReportInstruction = completionReportPath ? [
     '## Completion Report',
@@ -3890,11 +4275,18 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   };
   _phaseT.afterPrompt = Date.now();
 
-  if (branchName && READ_ONLY_ROOT_TASK_TYPES.has(type)) {
+  if (branchName && (READ_ONLY_ROOT_TASK_TYPES.has(type) || isControlPlane)) {
     // Read-only dispatches never own a branch. Project-bound worktree-mode
     // dispatches still get a detached worktree below; project-less/live tasks
     // keep their resolved cwd.
-    log('info', `${type}: ignoring branch label ${branchName} for read-only dispatch`);
+    //
+    // W-ms5tb6ha016fda10: a validly-declared control-plane dispatch owns no
+    // branch either — it has no checkout to put one in. Dropping the label
+    // here (rather than only at derivation) also covers explicitly-set
+    // `item.branch` and schedule-supplied labels, and keeps the dispatch out
+    // of the branch mutex so independent maintenance jobs don't serialize.
+    const reason = isControlPlane ? 'control-plane' : 'read-only';
+    log('info', `${type}: ignoring branch label ${branchName} for ${reason} dispatch`);
     branchName = null;
   }
 
@@ -3906,7 +4298,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   // target branch. W-mrcifup2000c218a: the dirty/stale-base conditions below
   // are now caught EARLIER, at allocation time, by the pre-dispatch checks in
   // the dispatch-existing-pending loop (`checkLiveCheckoutDirty` /
-  // `checkLiveCheckoutStaleBase` in engine/live-checkout.js) — a positive hit
+  // `checkLiveCheckoutStaleBase` in engine/worktrees/live-checkout.js) — a positive hit
   // there leaves the WI pending with `_pendingReason` stamped and never reaches
   // spawnAgent at all, so this block is now the EXCEPTION path (defense in
   // depth for the race window between that probe and the git operations
@@ -3959,7 +4351,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     // fork off baseline" signal.
     const _liveAllowNonMainBase = !!(meta?.useExistingBranch || meta?.branchStrategy === 'shared-branch');
     const _wiIdForAlert = meta?.item?.id || id;
-    const _liveCheckout = require('./engine/live-checkout');
+    const _liveCheckout = require('./engine/worktrees/live-checkout');
     // W-mrawgw4q000a6bff: stash-before-reset ordering. Resolve BOTH recovery
     // policies here (before the first prepareLiveCheckout call) so we can
     // decide precedence up front instead of letting prepareLiveCheckout's
@@ -4825,7 +5217,11 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
             }
             try {
               const _mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
-              await shared.shellSafeGit(['fetch', 'origin', _mainRef], { ..._gitOpts, cwd: rootDir, timeout: 30000 });
+              // W-ms5tb6ha016fda10: shared remote-tracking ref — serialize the
+              // refresh so a concurrent pool borrow / fresh create in the same
+              // clone cannot lose a `refs/remotes/origin/<main>` lock race.
+              await shared.withSerializedRemoteRefRefresh(rootDir, () =>
+                shared.shellSafeGit(['fetch', 'origin', _mainRef], { ..._gitOpts, cwd: rootDir, timeout: 30000 }));
               // -B force-creates/resets the branch so a stale local ref from a
               // prior occupant does not block the checkout.
               await shared.shellSafeGit(['checkout', '-B', branchName, `origin/${_mainRef}`], { ..._gitOpts, cwd: borrowed.path, timeout: 30000 });
@@ -5374,7 +5770,8 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
           const _depIsSharedBranch = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
           if (!_failedRefCache.has(_depMainRef)) {
             try {
-              await adoGitAuth.runAdoGit(project, ['fetch', 'origin', _depMainRef], { ..._gitOpts, cwd: rootDir });
+              await shared.withSerializedRemoteRefRefresh(rootDir, () =>
+                adoGitAuth.runAdoGit(project, ['fetch', 'origin', _depMainRef], { ..._gitOpts, cwd: rootDir }));
             } catch (mainFetchErr) {
               log('warn', `Failed to fetch origin/${_depMainRef} before dep merge: ${mainFetchErr.message} — proceeding with stale base`);
               if (adoGitAuth.isAdoAuthFailure(mainFetchErr)) _depAuthFailed = true;
@@ -5761,6 +6158,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
             }
             // Build actionable failReason identifying the conflicting branch and files (#958)
             const mainBranch = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
+            const _conflictsWith = (_isInterDepConflict && _preflightConflictPrev) ? _preflightConflictPrev : mainBranch;
             let failReason = 'Dependency merge failed';
             if (depConflictBranch) {
               if (_isInterDepConflict && _preflightConflictPrev) {
@@ -5771,15 +6169,24 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
               if (depConflictFiles.length > 0) failReason += ` in ${depConflictFiles.slice(0, 5).join(', ')}`;
               failReason += ' — dep branch needs updating';
             }
-            completeDispatch(id, DISPATCH_RESULT.ERROR, failReason, '', { failureClass: FAILURE_CLASS.MERGE_CONFLICT });
 
-            // Auto-queue conflict-fix work item when a specific dep branch is identified.
-            // Routes through the shared-branch dispatch path (see buildDepConflictFixItem)
-            // so commits land on the dep's existing PR branch (W-mpcwojgr000a0244).
-            if (depConflictBranch && meta?.item?.id && project) {
+            // W-mrzqfozm00035365 — Recoverable dependency merge-conflict gate.
+            // A specific dependency-branch conflict detected BEFORE the agent
+            // process starts is NOT an execution failure of the downstream item.
+            // When we can identify the blocked downstream WI, create/reuse the
+            // deterministic conflict-repair WI, link the blocked item, hold the
+            // downstream PENDING behind a `_dependencyConflict` marker, and defer
+            // the dispatch (no retry consumed). The discovery gate then wakes the
+            // downstream once the repair is done — instead of burning the
+            // downstream's retry budget to terminal `failed` while the repair is
+            // still being worked. Routes the repair through the shared-branch
+            // dispatch path (see buildDepConflictFixItem) so commits land on the
+            // dep's existing PR branch (W-mpcwojgr000a0244).
+            const _canRecoverDepConflict = !!(depConflictBranch && meta?.item?.id && project);
+            if (_canRecoverDepConflict) {
               try {
                 const wiScope = project.name ? project : 'central';
-                const newItem = buildDepConflictFixItem({
+                const repairItem = buildDepConflictFixItem({
                   depConflictBranch,
                   depConflictFiles,
                   isInterDepConflict: _isInterDepConflict,
@@ -5788,15 +6195,61 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
                   blockedItem: meta.item,
                   projectName: project.name || null,
                 });
+                let repairId = repairItem.id;
                 mutateWorkItems(wiScope, items => {
-                  // Don't create duplicate conflict-fix items
-                  const existing = items.find(i => i.id === newItem.id && i.status !== WI_STATUS.DONE && i.status !== WI_STATUS.FAILED && i.status !== WI_STATUS.CANCELLED);
-                  if (existing) return;
-                  items.push(newItem);
-                  log('info', `Auto-queued conflict-fix work item ${newItem.id} for ${depConflictBranch} (blocked: ${meta.item.id})`);
+                  // Create-or-reuse the deterministic conflict-repair WI. Link
+                  // THIS downstream item into `_blockedItems` idempotently so
+                  // multiple downstream items can share one repair and completing
+                  // it wakes all of them.
+                  const existing = items.find(i => i.id === repairItem.id);
+                  if (!existing) {
+                    items.push(repairItem);
+                    log('info', `Auto-queued conflict-fix work item ${repairItem.id} for ${depConflictBranch} (blocked: ${meta.item.id})`);
+                  } else {
+                    repairId = existing.id;
+                    if (!Array.isArray(existing._blockedItems)) {
+                      existing._blockedItems = existing._blockedItem ? [existing._blockedItem] : [];
+                    }
+                    if (!existing._blockedItems.includes(meta.item.id)) {
+                      existing._blockedItems.push(meta.item.id);
+                    }
+                  }
+                  // Stamp the blocked downstream WI: hold PENDING with the
+                  // recoverable marker + actionable pending reason. No retry
+                  // charged, no terminal failure.
+                  const downstream = items.find(i => i.id === meta.item.id);
+                  if (downstream) {
+                    downstream.status = WI_STATUS.PENDING;
+                    downstream._dependencyConflict = buildDependencyConflictMarker({
+                      repairWiId: repairId,
+                      conflictBranch: depConflictBranch,
+                      conflictsWith: _conflictsWith,
+                      isInterDep: _isInterDepConflict,
+                      files: depConflictFiles,
+                      detectedAt: ts(),
+                    });
+                    downstream._pendingReason = DEP_CONFLICT_PENDING_REASON;
+                    delete downstream.dispatched_at;
+                    delete downstream.dispatched_to;
+                  }
+                  return items;
                 });
-              } catch (e) { log('warn', `Failed to auto-queue conflict-fix: ${e.message}`); }
+                // Tear the dispatch down as a recoverable deferral — NOT a
+                // completion — so no retry is consumed and the downstream WI is
+                // free to re-dispatch once the gate clears.
+                deferDispatchToPending(id, `dependency conflict: ${depConflictBranch} conflicts with ${_conflictsWith} (repair ${repairId})`);
+                log('info', `Dependency conflict on ${depConflictBranch} blocks ${meta.item.id} — held pending behind repair ${repairId} (no retry consumed)`);
+              } catch (e) {
+                log('warn', `Recoverable dep-conflict gate failed for ${meta?.item?.id}: ${e.message} — falling back to failure`);
+                completeDispatch(id, DISPATCH_RESULT.ERROR, failReason, '', { failureClass: FAILURE_CLASS.MERGE_CONFLICT });
+              }
+              cleanupTempAgent(agentId);
+              return;
             }
+
+            // No identifiable downstream item (central / no meta.item) — preserve
+            // the original terminal failure behavior.
+            completeDispatch(id, DISPATCH_RESULT.ERROR, failReason, '', { failureClass: FAILURE_CLASS.MERGE_CONFLICT });
             cleanupTempAgent(agentId);
             return;
           }
@@ -6101,6 +6554,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
 
   // Spawn the selected harness runtime.
   const childEnv = shared.cleanChildEnv();
+  shared.applyAgentTestLoadSafetyEnv(childEnv);
   if (completionReportPath) childEnv.MINIONS_COMPLETION_REPORT = completionReportPath;
   if (completionNonce) childEnv.MINIONS_COMPLETION_NONCE = completionNonce;
   childEnv.MINIONS_REPO_HOST = getRepoHost(project);
@@ -6151,7 +6605,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     // W-mpg54mi2000n7b7e — inject a per-slug GitHub PAT so child `gh`/`git`
     // calls authenticate as the right account without any `gh auth login`
     // interactive flow. Resolution honors config.engine.ghAccounts via
-    // engine/gh-token.js (exact owner → owner-glob → fleet default → null).
+    // engine/providers/gh-token.js (exact owner → owner-glob → fleet default → null).
     // Mirrors the MINIONS_ADO_TOKEN injection above for ADO projects.
     try {
       const slug = shared.getProjectOrg(project) && project?.repoName
@@ -6165,12 +6619,12 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   if (_abortStaleSpawn()) return SPAWN_ATTEMPT_ABORTED;
   // Spawn via wrapper script — node directly (no bash intermediary)
   // spawn-agent.js handles CLAUDECODE env cleanup and claude binary resolution
-  const spawnScript = runtime.spawnScript || path.join(ENGINE_DIR, 'spawn-agent.js');
+  const spawnScript = runtime.spawnScript || path.join(ENGINE_DIR, 'agents', 'spawn-agent.js');
 
   const spawnArgs = [spawnScript, promptPath, sysPromptPath, ...args];
   // P-1d8f0b93 — the pooled-dispatch branch further down (agentWorkerPool
   // acquireWorker) accepts an optional `hermeticDirs` (workspace-manifest
-  // `allowed_repos` beyond the primary cwd — see engine/agent-worker-pool.js
+  // `allowed_repos` beyond the primary cwd — see engine/agents/agent-worker-pool.js
   // header doc). Repository harness discovery (skills/commands/--add-dir) is
   // now delegated entirely to the native runtime CLI (#817), so there is no
   // longer an engine-computed add-dir set to reuse here; leave it empty and
@@ -6178,6 +6632,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   const addDirs = [];
 
   let dispatchActivatedForLaunch = false;
+  let runtimePidObservedAt = 0;
   const _activateDispatchForRuntime = (phase) => {
     let activated = false;
     mutateDispatch((dispatch) => {
@@ -6223,6 +6678,8 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
       item._spawnPhase = 'running';
       if (Number.isInteger(proc?.pid) && proc.pid > 0) {
         item.runtimePid = proc.pid;
+        runtimePidObservedAt = Date.now();
+        item.runtimePidObservedAt = runtimePidObservedAt;
       }
       persisted = true;
       return dispatch;
@@ -6246,6 +6703,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         delete item.pooled;
         delete item.executionCwd;
         delete item.runtimePid;
+        delete item.runtimePidObservedAt;
         delete item._spawnPhase;
         if (!dispatch.pending.some(entry => entry.id === id)) dispatch.pending.push(item);
         return dispatch;
@@ -6304,7 +6762,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
   }
   let pidFilePath, logFd, registeredInActivityMap, registeredInActiveProcesses, proc;
   // The PID file at this path is written asynchronously by the spawned
-  // child (engine/spawn-agent.js:423) once it starts. We compute the path
+  // child (engine/agents/spawn-agent.js:423) once it starts. We compute the path
   // upfront so the catch block can unlink it whether spawn fails before
   // the child wrote it (no-op) or after (real cleanup).
   pidFilePath = promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid');
@@ -6396,7 +6854,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         promptText: fs.readFileSync(promptPath, 'utf8'),
       });
       // The child_process PID file is normally written asynchronously by
-      // spawn-agent.js itself (engine/spawn-agent.js:606) once it starts.
+      // spawn-agent.js itself (engine/agents/spawn-agent.js:606) once it starts.
       // There is no such child process here, so the engine writes the
       // equivalent file itself as soon as the pool hands back a real OS PID
       // (mirrors that write: async, best-effort, same `String(pid)` shape).
@@ -6426,13 +6884,14 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
       startedAt,
       runtimeName,
       sessionId: cachedSessionId,
+      runtimePidObservedAt,
       _completionNonce: completionNonce,
       ...(cachedSessionId ? {
         _runtimeResumeAt: Date.now(),
         _runtimeResumeAwaitingFirstOutput: true,
       } : {}),
       _pendingSteeringFiles: pendingSteering.entries,
-      // P-1d8f0b93 — marks a pooled dispatch so engine/timeout.js's
+      // P-1d8f0b93 — marks a pooled dispatch so engine/orchestration/timeout.js's
       // cancel-vs-kill wiring (P-6e2a4c15, killTrackedProcess /
       // _escalatePlatformKill) can route `.kill()` to cancel+release the
       // ACP worker instead of SIGKILL/taskkill on the shared worker's OS pid.
@@ -6450,7 +6909,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     // banner on tab switch / agent change).
     //
     // ONLY emitted on fresh spawns — re-attach after engine restart goes
-    // through engine/cli.js and does NOT pass through here, so a re-attached
+    // through engine/operations/cli.js and does NOT pass through here, so a re-attached
     // dispatch (procInfo.reattached === true) won't synthesise a spurious
     // started event that could clobber a still-live previous-dispatch
     // banner that the user is mid-read on.
@@ -6476,9 +6935,9 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
       // kill the orphan child so it doesn't run unmonitored. shared.killImmediate
       // recurses into the process tree (footgun #4) — plain proc.kill('SIGKILL')
       // doesn't on Windows.
-      try { shared.killImmediate(proc); } catch { /* already exited */ }
+      try { shared.terminateProcess('engine.spawn-partial-failure', proc); } catch { /* already exited */ }
     } else if (proc && typeof proc.kill === 'function') {
-      try { proc.kill(); } catch { /* already exited */ }
+      try { shared.terminateProcess('engine.spawn-partial-pooled', proc); } catch { /* already exited */ }
     }
     if (registeredInActiveProcesses) {
       activeProcesses.delete(id);
@@ -6618,7 +7077,35 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
 
     const procInfo = activeProcesses.get(id);
     ackPendingSteeringFiles(agentId, procInfo, steeringAckStdout);
-    promoteCheckpointSteeringForClose(agentId, procInfo, runtime, liveOutputPath);
+
+    // W-ms9tcs3o01y03383 — process exit + a valid, dispatch-owned completion
+    // report IS the completion boundary for this prompt.
+    //
+    // `code` here comes from the child's `close` event, so terminal exit is
+    // confirmed by construction, and the report is only accepted when it echoes
+    // the per-spawn nonce (carried across steering resumes). Both halves are
+    // required: a missing/forged report, or a still-live process, keeps every
+    // existing failure/timeout path exactly as it was. This never kills a live
+    // agent for silence — it only short-circuits AFTER the process is gone.
+    //
+    // When both hold, any queued resume bookkeeping is released rather than
+    // spawned, so the dispatch finalizes on this same async continuation
+    // instead of waiting out `engine.resumeHeartbeatTimeout` for a first
+    // heartbeat that a completed turn will never produce.
+    const terminalCompletionReport = resolveCloseCompletionBoundary(
+      dispatchItem,
+      code,
+      procInfo?._completionNonce || completionNonce,
+    );
+    let closeCompletionPath = shared.DISPATCH_COMPLETION_PATH.PROCESS_CLOSE;
+    if (terminalCompletionReport) {
+      const releasedResume = releasePendingSteeringResumeForCompletedTurn(agentId, procInfo, liveOutputPath);
+      if (releasedResume.released || releasedResume.deferred > 0) {
+        closeCompletionPath = shared.DISPATCH_COMPLETION_PATH.REPORT_RECOVERY_IMMEDIATE;
+      }
+    } else {
+      promoteCheckpointSteeringForClose(agentId, procInfo, runtime, liveOutputPath);
+    }
 
     // #853 — the child is gone, so its clean committed state is stable. Push
     // any strictly-ahead dispatch branch before steering resume, pool return,
@@ -6670,7 +7157,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
       // Live-kill flow first lands here; deferred-checkpoint flow
       // also lands here from the natural-close branch above.
       try {
-        const store = require('./engine/steering-store');
+        const store = require('./engine/persistence/steering-store');
         const steerEntries = Array.isArray(steerEntry) ? steerEntry : (steerEntry ? [steerEntry] : []);
         for (const entry of steerEntries) {
           if (entry?.steerId) {
@@ -6726,8 +7213,9 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         return;
       }
 
-      const spawnScript = runtime.spawnScript || path.join(ENGINE_DIR, 'spawn-agent.js');
+      const spawnScript = runtime.spawnScript || path.join(ENGINE_DIR, 'agents', 'spawn-agent.js');
       const childEnv = shared.cleanChildEnv();
+      shared.applyAgentTestLoadSafetyEnv(childEnv);
       if (completionReportPath) childEnv.MINIONS_COMPLETION_REPORT = completionReportPath;
       // P-d2a8f6c1: preserve the per-dispatch nonce across steering resume so
       // the agent's completion JSON still validates after the resumed turn.
@@ -6809,18 +7297,23 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         cleanupTempAgent(agentId);
         return;
       }
+      let resumePidObservedAt = 0;
       const writeResumePid = () => {
         if (!resumeProc.pid) return;
+        resumePidObservedAt = Date.now();
         try { fs.writeFileSync(pidFilePath, String(resumeProc.pid)); } catch { /* best-effort */ }
         try {
           mutateDispatch((dp) => {
             const active = dp.active.find((entry) => entry.id === id);
             if (active) {
               active.runtimePid = resumeProc.pid;
+              active.runtimePidObservedAt = resumePidObservedAt;
               active._spawnPhase = 'running';
             }
             return dp;
           });
+          const tracked = activeProcesses.get(id);
+          if (tracked?.proc === resumeProc) tracked.runtimePidObservedAt = resumePidObservedAt;
         } catch (e) {
           log('warn', `Steering: failed to persist resumed PID for ${agentId}: ${e.message}`);
         }
@@ -6839,6 +7332,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         startedAt: procInfo.startedAt,
         runtimeName,
         sessionId: steerSessionId,
+        runtimePidObservedAt: resumePidObservedAt,
         // P-d2a8f6c1: keep the per-dispatch nonce alive across the steering resume.
         _completionNonce: procInfo._completionNonce || completionNonce,
         _runtimeResumeAt: Date.now(),
@@ -6877,7 +7371,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         if (resumeInfo && !resumeInfo._steeringDeliveredAt) {
           resumeInfo._steeringDeliveredAt = Date.now();
           try {
-            const store = require('./engine/steering-store');
+            const store = require('./engine/persistence/steering-store');
             const pending = Array.isArray(resumeInfo._pendingSteeringFiles) ? resumeInfo._pendingSteeringFiles : [];
             for (const pendingEntry of pending) {
               if (pendingEntry?.steerId) {
@@ -6910,17 +7404,24 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
             try { fs.appendFileSync(liveOutputPath, `\n[steering-failed] Resume exited with code ${resumeCode}. Your message was received but the agent could not continue the session.\n`); } catch {}
           }
           // Don't assume original work completed — run normal close handler to parse output and determine actual result
-          onAgentClose(resumeCode);
+          finalizeAgentClose(resumeCode);
           return;
         }
         // Successful resume — run normal close handler
-        onAgentClose(resumeCode);
+        finalizeAgentClose(resumeCode);
       });
       resumeProc.on('error', (err) => {
-        log('warn', `Steering re-spawn error for ${agentId}: ${err.message}`);
-        try { fs.appendFileSync(liveOutputPath, `\n[steering-failed] Spawn error: ${err.message}. Your message was received but the agent could not resume.\n`); } catch {}
-        activeProcesses.delete(id);
-        completeDispatch(id, DISPATCH_RESULT.ERROR, `Steering re-spawn failed: ${err.message}`);
+        try {
+          log('warn', `Steering re-spawn error for ${agentId}: ${err.message}`);
+          try { fs.appendFileSync(liveOutputPath, `\n[steering-failed] Spawn error: ${err.message}. Your message was received but the agent could not resume.\n`); } catch {}
+          activeProcesses.delete(id);
+          completeDispatch(id, DISPATCH_RESULT.ERROR, `Steering re-spawn failed: ${err.message}`);
+        } catch (handlerErr) {
+          console.error(
+            `[engine] Failed to contain steering re-spawn error for ${id}: ` +
+            `${handlerErr?.stack || handlerErr}`,
+          );
+        }
       });
 
       // Don't run completion hooks — agent is still working
@@ -7065,7 +7566,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
         || !!dispatchItem.meta?.keep_processes_skip_workdir_check;
       if (_kpEnabled) {
         try {
-          const keepProcessSweep = require('./engine/keep-process-sweep');
+          const keepProcessSweep = require('./engine/processes/keep-process-sweep');
           // First evaluate with workdir validation OFF so we always catch
           // schema failures (pids-missing, ttl-too-long, etc.) regardless
           // of whether requireGitWorkdir is enabled or skipped per-WI.
@@ -7168,7 +7669,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
                   parsedSnippet ? '## What you wrote\n\n```json\n' + parsedSnippet + '\n```\n' : '',
                   '## Canonical shape',
                   '',
-                  canonicalHint || '(see `engine/keep-process-sweep.js` `buildKeepProcessesHint` for the canonical shape.)',
+                  canonicalHint || '(see `engine/processes/keep-process-sweep.js` `buildKeepProcessesHint` for the canonical shape.)',
                   '',
                 ].filter(Boolean).join('\n');
               }
@@ -7215,7 +7716,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     {
       if (managedSpawnRequested && lifecycleCompletionAccepted) {
         try {
-          const managedSpawn = require('./engine/managed-spawn');
+          const managedSpawn = require('./engine/processes/managed-spawn');
           const allowedCwdRoot = keepProcessesAllowedCwdRoot;
           const wiId = dispatchItem.meta?.item?.id || '';
           const evalResult = managedSpawn.evaluateManagedSpawnAcceptance(agentId, {
@@ -7265,7 +7766,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
                 parsedSnippet ? '## What you wrote\n\n```json\n' + parsedSnippet + '\n```\n' : '',
                 '## Canonical shape',
                 '',
-                canonicalHint || '(see `engine/managed-spawn.js` `buildManagedSpawnHint` for the canonical shape.)',
+                canonicalHint || '(see `engine/processes/managed-spawn.js` `buildManagedSpawnHint` for the canonical shape.)',
                 '',
               ].filter(Boolean).join('\n');
               writeInboxAlert(`managed-spawn-${agentId}`, alertBody);
@@ -7299,7 +7800,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
             const qaSessionMeta = dispatchItem.meta?.item?.meta;
             if (!spawnFailureReason
                 && qaSessionMeta?.sessionId) {
-              const qaSessions = require('./engine/qa-sessions');
+              const qaSessions = require('./engine/qa/sessions');
               if (qaSessionMeta.sessionPhase === qaSessions.SESSION_PHASE.SETUP) {
                 const qaSession = qaSessions.getSession(qaSessionMeta.sessionId);
                 if (!qaSession || qaSessions.TERMINAL_STATES.has(qaSession.state)) {
@@ -7410,7 +7911,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
           };
         }
       } else if (managedSpawnRequested) {
-        const managedSpawn = require('./engine/managed-spawn');
+        const managedSpawn = require('./engine/processes/managed-spawn');
         const staleSidecar = path.join(AGENTS_DIR, agentId, managedSpawn.MANAGED_SPAWN_FILENAME);
         try { fs.unlinkSync(staleSidecar); } catch (e) {
           if (e.code !== 'ENOENT') log('warn', `managed-spawn: failed to discard untrusted sidecar for ${agentId}: ${e.message}`);
@@ -7431,7 +7932,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     let managedSpawnHealthcheckFailure = null;
     if (managedSpawnSpawned.length > 0) {
       try {
-        const managedSpawn = require('./engine/managed-spawn');
+        const managedSpawn = require('./engine/processes/managed-spawn');
         const items = managedSpawnSpawned;
         // Re-read the specs from the state file (recordManagedBatch normalised
         // them — healthcheck shape lives there now).
@@ -7595,6 +8096,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     });
     const finalCompletionReportPath = structuredCompletion?._path || dispatchItem.meta?.completionReportPath || shared.dispatchCompletionReportPath(id);
     const completionOpts = {
+      completionPath: closeCompletionPath,
       ...(finalCompletionReportPath ? { completionReportPath: finalCompletionReportPath } : {}),
       ...(structuredCompletion ? { structuredCompletion } : {}),
     };
@@ -7696,7 +8198,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     let processAnchorReason = null;
     if (worktreePath) {
       try {
-        const anchorDecision = require('./engine/worktree-gc').shouldGcDispatchWorktree({
+        const anchorDecision = require('./engine/worktrees/gc').shouldGcDispatchWorktree({
           worktreePath,
           agentId,
           managedSpawnSpawnedCount: managedSpawnAliveCount,
@@ -7792,7 +8294,8 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
           await shared.shellSafeGit(['reset', '--hard', 'HEAD'], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
           // -fd preserves gitignored files (node_modules, .vite, .next caches) — that's the whole point.
           await shared.shellSafeGit(['clean', '-fd'], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
-          await shared.shellSafeGit(['fetch', 'origin', _mainRefRet], { ..._gitOpts, cwd: rootDir, timeout: 30000 });
+          await shared.withSerializedRemoteRefRefresh(rootDir, () =>
+            shared.shellSafeGit(['fetch', 'origin', _mainRefRet], { ..._gitOpts, cwd: rootDir, timeout: 30000 }));
           // Detach at origin/<main> — local main is typically checked out in
           // the project root and git refuses two checkouts of the same branch.
           await shared.shellSafeGit(['checkout', '--detach', `origin/${_mainRefRet}`], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
@@ -7842,7 +8345,7 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     // at …` until the 2-hour age sweep in cleanup.js eventually catches up.
     if (worktreePath && rootDir && failedWorktreeProtection.allowRemoval !== false) {
       try {
-        const _wgc = require('./engine/worktree-gc');
+        const _wgc = require('./engine/worktrees/gc');
         const _wtRoot = path.resolve(rootDir, engineConfig.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot);
         const _gcResult = _wgc.gcDispatchWorktreeIfOrphan({
           worktreePath,
@@ -7877,19 +8380,19 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     // ── P-d9e6b2c4 — live-mode dispatch-end auto-restore + terminal-failure
     //    notify. Runs on EVERY terminal result for a live-mode dispatch: the
     //    agent ran in-place in the operator's checkout, so switch the tree back
-    //    to the ref it was on before (see engine/live-checkout.js#
+    //    to the ref it was on before (see engine/worktrees/live-checkout.js#
     //    restoreLiveCheckoutAtDispatchEnd). The worktree-GC block above no-ops
     //    in live mode (worktreePath===null); this is its live-mode counterpart.
     //    originalRef was captured by prepareLiveCheckout and persisted on the
     //    dispatch record at branch-resolution time (P-c5a1f3b8); the in-memory
     //    closure copy is authoritative here. The engine-restart reattach path
-    //    fires the same helper from the persisted record in engine/cli.js. The
+    //    fires the same helper from the persisted record in engine/operations/cli.js. The
     //    restore is a plain `git checkout <originalRef>` — never --force/reset/
     //    clean/stash — and is best-effort: a thrown restore never alters the
     //    dispatch result.
     if (liveMode && branchName && shared.isLiveCheckoutDispatchRecord(dispatchItem, getConfig())) {
       try {
-        const _liveRestore = require('./engine/live-checkout');
+        const _liveRestore = require('./engine/worktrees/live-checkout');
         await _liveRestore.restoreLiveCheckoutAtDispatchEnd({
           localPath: cwd,
           branchName,
@@ -8003,14 +8506,52 @@ async function spawnAgent(dispatchItem, config, spawnAttemptLease = null) {
     }
   }
 
-  proc.on('close', onAgentClose);
+  function finalizeAgentClose(code) {
+    onAgentClose(code).catch(err => {
+      const detail = err instanceof Error ? err.stack || err.message : String(err);
+      const reason = err instanceof Error ? err.message : String(err);
+      try {
+        log('error', `Agent ${agentId} (${id}) close finalization failed: ${detail}`);
+        activeProcesses.delete(id);
+        realActivityMap.delete(id);
+        const dispatchNow = getDispatch();
+        const stillQueued = [...(dispatchNow.active || []), ...(dispatchNow.pending || [])]
+          .some(item => item.id === id);
+        if (stillQueued) {
+          completeDispatch(
+            id,
+            DISPATCH_RESULT.ERROR,
+            `Post-completion lifecycle error: ${reason}`,
+            '',
+            { failureClass: FAILURE_CLASS.UNKNOWN, agentRetryable: true },
+          );
+        }
+      } catch (recoveryErr) {
+        console.error(
+          `[engine] Failed to contain close finalization error for ${id}: ` +
+          `${recoveryErr?.stack || recoveryErr}`,
+        );
+      } finally {
+        try { cleanupTempAgent(agentId); } catch { /* best-effort recovery */ }
+      }
+    });
+  }
+
+  proc.on('close', finalizeAgentClose);
 
   proc.on('error', (err) => {
-    log('error', `Failed to spawn agent ${agentId}: ${err.message}`);
-    activeProcesses.delete(id);
-    realActivityMap.delete(id);
-    completeDispatch(id, DISPATCH_RESULT.ERROR, `Spawn error: ${err.message}`);
-    cleanupTempAgent(agentId);
+    try {
+      log('error', `Failed to spawn agent ${agentId}: ${err.message}`);
+      activeProcesses.delete(id);
+      realActivityMap.delete(id);
+      completeDispatch(id, DISPATCH_RESULT.ERROR, `Spawn error: ${err.message}`);
+    } catch (handlerErr) {
+      console.error(
+        `[engine] Failed to contain spawn error for ${id}: ${handlerErr?.stack || handlerErr}`,
+      );
+    } finally {
+      try { cleanupTempAgent(agentId); } catch { /* best-effort recovery */ }
+    }
   });
 
   // Safety: if process exits immediately (within 3s), log it
@@ -8097,8 +8638,6 @@ function areDependenciesMet(item, config) {
   const deps = item.depends_on;
   if (!deps || deps.length === 0) return true;
   const sourcePlan = item.sourcePlan;
-  if (!sourcePlan) return true;
-  const projects = getProjects(config);
 
   // Collect work items from ALL projects (dependencies can be cross-project)
   const allWorkItems = queries.getWorkItems(config);
@@ -8109,12 +8648,14 @@ function areDependenciesMet(item, config) {
     const depItem = allWorkItems.find(w => w.id === depId);
     if (!depItem) {
       // Fallback: check the PRD store — plan-to-prd agents may pre-set items to done.
-      try {
-        const plan = prdStore.readPrd(sourcePlan);
-        const prdItem = (plan?.missing_features || []).find(f => f.id === depId);
-        if (prdItem && PRD_MET_STATUSES.has(prdItem.status)) continue; // PRD says done — treat as met
-      } catch (e) { log('warn', 'check PRD dep status: ' + e.message); }
-      log('warn', `Dependency ${depId} not found for ${item.id} (plan: ${sourcePlan}) — treating as unmet`);
+      if (sourcePlan) {
+        try {
+          const plan = prdStore.readPrd(sourcePlan);
+          const prdItem = (plan?.missing_features || []).find(f => f.id === depId);
+          if (prdItem && PRD_MET_STATUSES.has(prdItem.status)) continue; // PRD says done — treat as met
+        } catch (e) { log('warn', 'check PRD dep status: ' + e.message); }
+      }
+      log('warn', `Dependency ${depId} not found for ${item.id} (plan: ${sourcePlan || 'none'}) — treating as unmet`);
       return false;
     }
     if (depItem.status === WI_STATUS.FAILED) return 'failed';
@@ -8227,12 +8768,12 @@ function reconcileItemsWithPrs(items, allPrs, { onlyIds } = {}) {
   return reconciled;
 }
 
-// ─── Inbox Consolidation (extracted to engine/consolidation.js) ──────────────
+// ─── Inbox Consolidation (extracted to engine/memory/consolidation.js) ──────────────
 
-const { consolidateInbox } = require('./engine/consolidation');
+const { consolidateInbox } = require('./engine/memory/consolidation');
 const { pollPrStatus, pollPrHumanComments, reconcilePrs, checkLiveReviewStatus: adoCheckLiveReview, checkLiveBuildAndConflict: adoCheckLiveBuildAndConflict, needsAdoPollRetry, getAdoToken, isAdoThrottled, getAdoThrottleState } = require('./engine/ado');
-const { pollPrStatus: ghPollPrStatus, pollPrHumanComments: ghPollPrHumanComments, reconcilePrs: ghReconcilePrs, checkLiveReviewStatus: ghCheckLiveReview, checkLiveBuildAndConflict: ghCheckLiveBuildAndConflict, isGhThrottled } = require('./engine/github');
-const { reconcileSharedBranchPrs } = require('./engine/shared-branch-pr-reconcile');
+const { pollPrStatus: ghPollPrStatus, pollPrHumanComments: ghPollPrHumanComments, reconcilePrs: ghReconcilePrs, checkLiveReviewStatus: ghCheckLiveReview, checkLiveBuildAndConflict: ghCheckLiveBuildAndConflict, isGhThrottled } = require('./engine/providers/github');
+const { reconcileSharedBranchPrs } = require('./engine/providers/shared-branch-pr-reconcile');
 
 // ─── State Snapshot ─────────────────────────────────────────────────────────
 
@@ -8273,12 +8814,12 @@ function updateSnapshot(config) {
   safeWrite(path.join(IDENTITY_DIR, 'now.md'), snapshot);
 }
 
-// ─── Cooldowns (extracted to engine/cooldown.js) ─────────────────────────────
+// ─── Cooldowns (extracted to engine/orchestration/cooldown.js) ─────────────────────────────
 
 const { dispatchCooldowns, loadCooldowns, saveCooldowns,
   isOnCooldown, setCooldown, setCooldownWithContext, drainCoalescedContexts,
   setCooldownFailure, clearCooldown, getPrReviewCooldownKey, clearLegacyPrReviewCooldown,
-  isAlreadyDispatched, isBranchActive } = require('./engine/cooldown');
+  isAlreadyDispatched, isBranchActive } = require('./engine/orchestration/cooldown');
 
 // Auto-clean pending/failed work items for a PRD so they re-materialize with updated plan data
 function autoCleanPrdWorkItems(prdFile, config) {
@@ -8845,7 +9386,7 @@ function materializePlansAsWorkItems(config) {
   }
 }
 
-// buildBaseVars, selectPlaybook, buildPrDispatch extracted to engine/playbook.js
+// buildBaseVars, selectPlaybook, buildPrDispatch extracted to engine/agents/playbook.js
 
 function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   if (!prId) return;
@@ -8865,7 +9406,7 @@ function isPrNoOpFixCauseSuppressed(pr, cause) {
 }
 
 // #639 — distinct suppression check for the build-fix-ineffective pause
-// (see shared.isBuildFixIneffectivePaused / engine/lifecycle.js
+// (see shared.isBuildFixIneffectivePaused / engine/orchestration/lifecycle.js
 // recordBuildFixIneffective). Kept separate from isPrNoOpFixCauseSuppressed
 // so the log line is unambiguous about WHY build-fix automation stopped:
 // repeated attempts genuinely found nothing to change vs. repeated attempts
@@ -9341,8 +9882,8 @@ async function discoverFromPrs(config, project) {
     if (pr.status !== PR_STATUS.ACTIVE) continue;
     // Issue #384: skip tombstoned PRs (user explicitly deleted via dashboard)
     if (pr.userDeleted === true) continue;
-    if (shared.isContextOnlyPrRecord(pr)) {
-      _logPrDispatchSkipOnce(pr, 'context-only');
+    if (!shared.isAutoManagedPrRecord(pr)) {
+      _logPrDispatchSkipOnce(pr, 'not-auto-managed');
       continue;
     }
     if (!shared.isPrCompatibleWithProject(project, pr, pr.url || '')) continue;
@@ -9368,13 +9909,6 @@ async function discoverFromPrs(config, project) {
       log('info', `Branch mutex: skipping PR ${pr.id} dispatch — branch ${prBranchForMutex} locked by another agent`);
       continue;
     }
-    // Auto-managed gate: single source of truth in engine/shared.js. Canonical
-    // `contextOnly` wins over stale legacy flags; legacy `_contextOnly` is only
-    // a fallback for raw pre-migration records.
-    if (!shared.isAutoManagedPrRecord(pr)) {
-      _logPrDispatchSkipOnce(pr, 'not-auto-managed');
-      continue;
-    }
     // #764 — PR-level circuit breaker: a prior dispatch against this PR's
     // branch hit WORKTREE_PREFLIGHT because the branch is held externally
     // (project root or an unreachable sibling worktree). Every dispatch path
@@ -9389,6 +9923,8 @@ async function discoverFromPrs(config, project) {
     // Use reviewStatus as single source of truth (synced from ADO/GitHub votes)
     // minionsReview tracks metadata (reviewer, note) but not the authoritative status
     const reviewStatus = pr.reviewStatus || REVIEW_STATUS.PENDING;
+    const prAutoFixEnabled = shared.isPrAutoFixEnabled(pr);
+    const prAutoReviewEnabled = shared.isPrAutoReviewEnabled(pr);
 
     // Skip fix dispatch if a fix was recently submitted and awaiting re-review.
     // The poller holds reviewStatus at 'waiting' until the reviewer acts on the new code.
@@ -9402,8 +9938,8 @@ async function discoverFromPrs(config, project) {
     let fixDispatched = false;
 
     // PRs needing review: evalLoop gates the entire review+fix cycle; pollEnabled ensures reviewStatus is fresh
-    const reviewEnabled = evalLoopEnabled && pollEnabled && autoReviewPrs;
-    const reReviewEnabled = evalLoopEnabled && pollEnabled && autoReReviewPrs;
+    const reviewEnabled = prAutoReviewEnabled && evalLoopEnabled && pollEnabled && autoReviewPrs;
+    const reReviewEnabled = prAutoReviewEnabled && evalLoopEnabled && pollEnabled && autoReReviewPrs;
     const alreadyReviewed = isPrReviewCurrent(pr);
     const needsReview = reviewEnabled && reviewStatus === REVIEW_STATUS.PENDING && !alreadyReviewed;
     if (needsReview) {
@@ -9473,7 +10009,7 @@ async function discoverFromPrs(config, project) {
     const humanCauseKey = getPrAutomationCauseKey('human-comment', pr);
     const humanFixKey = getPrAutomationDispatchKey(humanFixBaseKey, humanCauseKey);
     const hasCoalescedFeedback = (dispatchCooldowns.get(humanFixKey)?.pendingContexts || []).length > 0;
-    if (pollEnabled && autoFixHumanComments && (pr.humanFeedback?.pendingFix || hasCoalescedFeedback) && !fixDispatched
+    if (prAutoFixEnabled && pollEnabled && autoFixHumanComments && (pr.humanFeedback?.pendingFix || hasCoalescedFeedback) && !fixDispatched
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.HUMAN_FEEDBACK)) {
       // W-mp3bp0ha000997ab-d: skip when the most recent HUMAN-FEEDBACK dispatch
       // already noop'd against the same head SHA AND the same triggering
@@ -9703,7 +10239,7 @@ async function discoverFromPrs(config, project) {
 
     // PRs with changes requested → route back to author for fix.
     // Gate on evalLoopEnabled and provider polling — the review→fix cycle depends on fresh vote state.
-    if (evalLoopEnabled && pollEnabled && autoFixReviewFeedback && reviewStatus === REVIEW_STATUS.CHANGES_REQUESTED && !awaitingReReview && !fixDispatched
+    if (prAutoFixEnabled && evalLoopEnabled && pollEnabled && autoFixReviewFeedback && reviewStatus === REVIEW_STATUS.CHANGES_REQUESTED && !awaitingReReview && !fixDispatched
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.REVIEW_FEEDBACK)) {
       const reviewCauseKey = getPrAutomationCauseKey('review-feedback', pr);
       const key = getPrAutomationDispatchKey(`fix-${project?.name || 'default'}-${prDisplayId}`, reviewCauseKey);
@@ -9759,7 +10295,7 @@ async function discoverFromPrs(config, project) {
       const gracePeriodMs = config.engine?.buildFixGracePeriod ?? ENGINE_DEFAULTS.buildFixGracePeriod;
       if (Date.now() - new Date(pr._buildFixPushedAt).getTime() < gracePeriodMs) continue;
     }
-    if (pollEnabled && autoFixBuilds && pr.status === PR_STATUS.ACTIVE && pr.buildStatus === 'failing'
+    if (prAutoFixEnabled && pollEnabled && autoFixBuilds && pr.status === PR_STATUS.ACTIVE && pr.buildStatus === 'failing'
       && !fixDispatched
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.BUILD_FAILURE)
       && !isBuildFixIneffectiveSuppressed(pr)) {
@@ -9923,7 +10459,7 @@ async function discoverFromPrs(config, project) {
     }
 
     // PRs with merge conflicts — dispatch fix to resolve (gated by provider polling + autoFixConflicts)
-    if (pollEnabled && autoFixConflicts && pr.status === PR_STATUS.ACTIVE && pr._mergeConflict && !fixDispatched
+    if (prAutoFixEnabled && pollEnabled && autoFixConflicts && pr.status === PR_STATUS.ACTIVE && pr._mergeConflict && !fixDispatched
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.MERGE_CONFLICT)) {
       // W-mpritzcr0004afc5 (#2955): "don't fan out a parallel conflict-fix
       // while the review-feedback path owns the PR" is already handled by
@@ -10022,12 +10558,188 @@ async function discoverFromPrs(config, project) {
   return newWork;
 }
 
+/**
+ * Hard cap on the co-service rows a QA-session prompt can carry. Sessions are
+ * already bounded at `qaSessions.LIMITS.projectsMax` (5); this is the
+ * independent render-side bound so a hand-edited session record can never
+ * inflate a dispatch prompt.
+ */
+const QA_SESSION_SERVICES_MAX = 8;
+
+/**
+ * W-msb9kgs402813a97-a — the live co-service inventory for a QA Session.
+ *
+ * A multi-project session owns ONE managed-spawn per project
+ * (`qaSessions.managedSpawnNamesForSession`), but DRAFT/EXECUTE only ever saw
+ * the PRIMARY spawn — so a co-service origin was unaddressable from the test
+ * the agent drafted. This builds a bounded
+ * `{ name, project, primary, health, baseUrl, ports }` row per spawn, which is
+ * surfaced to the playbooks as `{{session_services_json}}` and to runner
+ * adapters as `briefOpts.services`.
+ *
+ * `health` is one of `healthy` | `unhealthy` (alive but failing its
+ * healthcheck) | `down` (registered but not alive) | `missing` (no spec
+ * registered yet — the normal SETUP-phase state). Never throws: an unreadable
+ * managed-process store degrades to `missing` rows, because a render must not
+ * fail over service discovery.
+ *
+ * Exported for testing.
+ */
+function buildQaSessionServices(session) {
+  if (!session || typeof session !== 'object') return [];
+  let names = [];
+  try {
+    names = require('./engine/qa/sessions').managedSpawnNamesForSession(session);
+  } catch (err) {
+    log('warn', `qa-session render: managedSpawnNamesForSession failed: ${err.message}`);
+    return [];
+  }
+  if (!Array.isArray(names) || names.length === 0) return [];
+
+  const specProjects = Array.isArray(session.spec && session.spec.projects)
+    ? session.spec.projects.filter(p => typeof p === 'string' && p)
+    : [];
+  const primaryProject = session.primaryProject
+    || specProjects[0]
+    || (session.spec && session.spec.project)
+    || null;
+
+  const byName = new Map();
+  try {
+    for (const spec of require('./engine/processes/managed-spawn').listManagedSpecs()) {
+      if (spec && typeof spec.name === 'string') byName.set(spec.name, spec);
+    }
+  } catch (err) {
+    log('warn', `qa-session render: managed-spawn inventory unavailable: ${err.message}`);
+  }
+
+  return names.slice(0, QA_SESSION_SERVICES_MAX).map((name, index) => {
+    // managedSpawnNamesForSession maps spec.projects positionally, so index
+    // alignment is its contract; single/central sessions collapse to the one
+    // primary row.
+    const project = specProjects.length > 1
+      ? (specProjects[index] || null)
+      : (primaryProject || null);
+    const record = byName.get(name) || null;
+    let health = 'missing';
+    if (record) {
+      if (record.healthy === true) health = 'healthy';
+      else if (record.alive === true) health = 'unhealthy';
+      else health = 'down';
+    }
+    return {
+      name,
+      project,
+      primary: !project || project === primaryProject,
+      health,
+      baseUrl: (record && record.attrs && typeof record.attrs.base_url === 'string')
+        ? record.attrs.base_url
+        : '',
+      ports: (record && Array.isArray(record.ports)) ? record.ports.slice() : [],
+    };
+  });
+}
+
+/**
+ * Render-time wrapper: resolve the session behind a QA work item and encode its
+ * service inventory. Returns '' for non-QA items and for any lookup failure, so
+ * `{{session_services_json}}` degrades to the PLAYBOOK_OPTIONAL_VARS empty
+ * string rather than breaking the render.
+ */
+function _qaSessionServicesJson(item) {
+  const meta = item && item.meta;
+  if (!meta || !meta.sessionId) return '';
+  try {
+    const session = require('./engine/qa/sessions').getSession(meta.sessionId);
+    if (!session) return '';
+    const services = buildQaSessionServices(session);
+    return services.length ? JSON.stringify(services) : '';
+  } catch (err) {
+    log('warn', `qa-session render: session services lookup failed for ${meta.sessionId}: ${err.message}`);
+    return '';
+  }
+}
+
+/**
+ * Independent render-side cap on the manifest journey rows an EXECUTE prompt
+ * can carry. The DRAFT gate already bounds an accepted manifest at
+ * `visualJourney.LIMITS.journeysMax`, but a hand-edited session record must
+ * never be able to inflate a dispatch prompt.
+ */
+const QA_SESSION_JOURNEYS_MAX = 20;
+
+/**
+ * W-msb9kgs402813a97-c — the DRAFT-accepted visual-journey manifest, projected
+ * into the exact shape EXECUTE has to report back.
+ *
+ * `visualJourney.validateEvidenceCoverage` check (c) requires every journey the
+ * manifest declared to come back as a PASSED `journeyCoverage` entry keyed by
+ * the journey id VERBATIM. Those ids are free-form strings the DRAFT agent
+ * invents (`playbooks/qa-session-draft.md` calls them "short-stable-id"), the
+ * DRAFT sidecar that carried them is read-then-unlinked, and the accepted
+ * manifest is persisted on the session record only. So without this projection
+ * the EXECUTE agent is graded against a value it was never shown, and every
+ * session that requested screenshots or video fails
+ * `qa-session-evidence-incomplete` on a flawless run.
+ *
+ * Field names deliberately mirror the sidecar's coverage entry (`journeyId`,
+ * `projects`, `services`) rather than the manifest's own (`id`, …), so the
+ * contract the agent is handed is copy-shaped for the contract it must emit.
+ *
+ * Pure and never throws — exported for testing.
+ */
+function buildQaExecuteJourneyContract(session) {
+  if (!session || typeof session !== 'object') return [];
+  const manifest = session.visualJourneyManifest;
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) return [];
+  if (!Array.isArray(manifest.journeys)) return [];
+  const boundedList = (value) => (Array.isArray(value)
+    ? value.filter(v => typeof v === 'string' && v).slice(0, QA_SESSION_SERVICES_MAX)
+    : []);
+  return manifest.journeys
+    .filter(j => j && typeof j === 'object' && typeof j.id === 'string' && j.id)
+    .slice(0, QA_SESSION_JOURNEYS_MAX)
+    .map(j => ({
+      journeyId: j.id,
+      name: typeof j.name === 'string' ? j.name : '',
+      kind: typeof j.kind === 'string' ? j.kind : '',
+      projects: boundedList(j.projects),
+      services: boundedList(j.services),
+    }));
+}
+
+/**
+ * Render-time wrapper for `{{visual_journey_manifest_json}}`.
+ *
+ * EXECUTE-only on purpose: the manifest does not exist until DRAFT produces it,
+ * and on the re-draft path (`editDraft` re-queues DRAFT for the same session)
+ * showing the PREVIOUS attempt's manifest to the DRAFT agent would invite it to
+ * copy ids it is supposed to be re-deciding.
+ *
+ * Returns '' for non-QA items, non-EXECUTE phases, logs-only/legacy sessions
+ * with no persisted manifest, and any lookup failure, so the var degrades to
+ * the PLAYBOOK_OPTIONAL_VARS empty string rather than breaking the render.
+ */
+function _qaVisualJourneyManifestJson(item) {
+  const meta = item && item.meta;
+  if (!meta || !meta.sessionId || meta.sessionPhase !== 'execute') return '';
+  try {
+    const session = require('./engine/qa/sessions').getSession(meta.sessionId);
+    if (!session) return '';
+    const journeys = buildQaExecuteJourneyContract(session);
+    return journeys.length ? JSON.stringify(journeys, null, 2) : '';
+  } catch (err) {
+    log('warn', `qa-session render: visual-journey manifest lookup failed for ${meta.sessionId}: ${err.message}`);
+    return '';
+  }
+}
+
 /**
  * P-f9a2e1b4 — Compute runner_brief / runner_execute_brief / test_file for
  * QA Session DRAFT and EXECUTE dispatches.
  *
- * Lazy-requires `./engine/qa-sessions`, `./engine/qa-runners`, and
- * `./engine/managed-spawn` so non-QA dispatches don't pay the load cost
+ * Lazy-requires `./engine/qa/sessions`, `./engine/qa-runners`, and
+ * `./engine/processes/managed-spawn` so non-QA dispatches don't pay the load cost
  * and so test isolation (createTestMinionsDir → ISOLATED_MODULES) gets a
  * fresh module instance per test.
  *
@@ -10049,9 +10761,9 @@ function _buildRunnerBriefVars(item, project, qaRunPaths = {}) {
   const phase = meta.sessionPhase;
   if (phase !== 'draft' && phase !== 'execute') return empty;
   try {
-    const qaSessions = require('./engine/qa-sessions');
+    const qaSessions = require('./engine/qa/sessions');
     const qaRunners = require('./engine/qa-runners');
-    const managedSpawn = require('./engine/managed-spawn');
+    const managedSpawn = require('./engine/processes/managed-spawn');
     const session = qaSessions.getSession(meta.sessionId);
     if (!session) {
       log('warn', `qa-session render: session ${meta.sessionId} not found — runner brief empty`);
@@ -10084,6 +10796,10 @@ function _buildRunnerBriefVars(item, project, qaRunPaths = {}) {
       session,
       sessionId: session.id,
       spawnInfo,
+      // W-msb9kgs402813a97-a — every co-service origin the session owns, not
+      // just the primary `spawnInfo`. Runner adapters address a co-service by
+      // its own baseUrl/ports instead of assuming one origin per session.
+      services: buildQaSessionServices(session),
       flowsRaw: (meta.qaSession && meta.qaSession.flowsRaw) || session.spec.flowsRaw || '',
       capture: (meta.qaSession && meta.qaSession.capture) || session.spec.capture || {},
       testFile,
@@ -10166,13 +10882,24 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     managedSpawnLookupUrl =
       `http://localhost:${dashboardPort}/api/managed-processes/by-name/${encodeURIComponent(managedSpawnName)}`;
   }
-  const qaRuns = qaRunId ? require('./engine/qa-runs') : null;
+  const qaRuns = qaRunId ? require('./engine/qa/runs') : null;
   const qaRunPaths = qaRunId
     ? {
         artifactsDir: qaRuns.qaArtifactsDirForRun(qaRunId),
         resultSidecar: qaRuns.resultSidecarPath(String(agentId)),
       }
     : { artifactsDir: '', resultSidecar: '' };
+  // W-msb9kgs402813a97-b — absolute path of the DRAFT visual-journey manifest
+  // sidecar. Only the DRAFT phase writes one; every other dispatch renders ''
+  // (filtered via PLAYBOOK_OPTIONAL_VARS).
+  let qaDraftResultSidecar = '';
+  if (item.meta && item.meta.sessionId && item.meta.sessionPhase === 'draft') {
+    try {
+      qaDraftResultSidecar = require('./engine/qa/visual-journey').draftResultSidecarPath(String(agentId));
+    } catch (err) {
+      log('warn', `qa-session render: draft result sidecar path for ${item.meta.sessionId}: ${err.message}`);
+    }
+  }
   const vars = {
     ...buildBaseVars(agentId, config, project),
     item_id: item.id,
@@ -10199,7 +10926,7 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     // suppress their own premature PR-creation step the same way via
     // {{#shared_branch}} / {{^shared_branch}} conditional blocks. Truthy only
     // when the item is genuinely on a shared branch (mirrors selectPlaybook's
-    // implement→implement-shared gate at engine/playbook.js). Default '' for
+    // implement→implement-shared gate at engine/agents/playbook.js). Default '' for
     // parallel/PR-targeted dispatches keeps existing per-type PR behavior.
     shared_branch: (item.branchStrategy === 'shared-branch' && item.featureBranch) ? '1' : '',
     // W-mrtdmtwq000kf391 — resolved PR contract flag. Truthy when the work item
@@ -10236,6 +10963,12 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     managed_spawn_ttl_minutes: item.meta && Number.isFinite(Number(item.meta.managed_spawn_ttl_minutes))
       ? Math.floor(Number(item.meta.managed_spawn_ttl_minutes))
       : '',
+    // W-ms5tb6ha016fda10 — declared execution surface. Resolved fail-closed so
+    // only a valid `control-plane` opt-in on an eligible type reaches the
+    // playbook; everything else renders as a normal repo dispatch.
+    execution_surface: shared.isControlPlaneExecution(item, workType)
+      ? shared.EXECUTION_SURFACE.CONTROL_PLANE
+      : shared.EXECUTION_SURFACE.REPO,
     // W-mq5l3f2u000i9045 — opt-out flag for the inlined PR description audit
     // section in fix.md / implement.md. When the dispatcher sets
     // item.meta.skipDescriptionAudit (skill-meta updates, doc-only fixes,
@@ -10254,8 +10987,12 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     qa_target: (item.meta && item.meta.qaTarget) || null,
     qa_artifacts_dir: qaRunPaths.artifactsDir,
     qa_result_sidecar: qaRunPaths.resultSidecar,
+    // W-msb9kgs402813a97-b — where the DRAFT agent writes its visual-journey
+    // manifest. The engine consumes it exactly once in
+    // engine/orchestration/lifecycle.js and gates EXECUTE on it.
+    qa_draft_result_sidecar: qaDraftResultSidecar,
     // P-e6b3c2d8 — QA Session template vars. The qa-sessions chain helpers
-    // (engine/qa-sessions.js#_baseWorkItem) stamp meta.sessionId,
+    // (engine/qa/sessions.js#_baseWorkItem) stamp meta.sessionId,
     // meta.sessionPhase, and meta.qaSession.{target,flowsRaw,mode,capture,runner}
     // on each SETUP/DRAFT/EXECUTE WI; renderProjectWorkItemPromptForAgent
     // surfaces them as named template vars so the qa-session-* playbooks
@@ -10269,6 +11006,18 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
       ? 'qa-session-' + String(item.meta.sessionId)
       : '',
     managed_spawn_lookup_url: managedSpawnLookupUrl,
+    // W-msb9kgs402813a97-a — every managed-spawn the session owns, as
+    // `[{name, project, primary, health, baseUrl, ports}]`. `managed_spawn_name`
+    // stays the PRIMARY (back-compat); this var is what lets DRAFT/EXECUTE
+    // address a co-service origin. Empty string when the item is not a QA
+    // session (filtered via PLAYBOOK_OPTIONAL_VARS).
+    session_services_json: _qaSessionServicesJson(item),
+    // W-msb9kgs402813a97-c — the DRAFT-accepted visual-journey manifest,
+    // projected into the sidecar's coverage-entry shape. EXECUTE's evidence
+    // gate grades the run against these journey ids verbatim, so the agent has
+    // to be shown them; the DRAFT sidecar that carried them is already
+    // consumed. Empty for every non-EXECUTE and non-visual dispatch.
+    visual_journey_manifest_json: _qaVisualJourneyManifestJson(item),
     target_kind: (item.meta && item.meta.qaSession && item.meta.qaSession.target && item.meta.qaSession.target.kind) || '',
     target_pr_id: (item.meta && item.meta.qaSession && item.meta.qaSession.target && item.meta.qaSession.target.kind === 'pr'
       ? String(item.meta.qaSession.target.prId || '')
@@ -10543,12 +11292,56 @@ function discoverFromWorkItems(config, project) {
       }
     }
 
+    // W-mrzqfozm00035365 (requirement 7) — safe reconciliation: revive items
+    // that terminally FAILED solely because a pre-execution dependency merge
+    // conflict exhausted their retries, when the deterministic conflict-repair
+    // WI exists and is still live (pending/dispatched) or done. Guarded by
+    // shouldReviveFailedDependencyConflict so unrelated failures are never
+    // revived. After revival the recoverable gate below governs redispatch, so
+    // there is no immediate retry loop and no retry charge.
+    if (item.status === WI_STATUS.FAILED && !isItemCompleted(item)) {
+      const repair = findConflictRepairForBlockedItem(item.id, items, item._dependencyConflict?.repairWiId);
+      if (shouldReviveFailedDependencyConflict(item, repair)) {
+        // Ensure the repair links back to this item so the gate can find it on
+        // later ticks (legacy repairs only tracked the first blocked item).
+        if (!Array.isArray(repair._blockedItems)) {
+          repair._blockedItems = repair._blockedItem ? [repair._blockedItem] : [];
+        }
+        if (!repair._blockedItems.includes(item.id)) repair._blockedItems.push(item.id);
+        // Re-stamp / preserve the recoverable marker so the discovery gate
+        // governs redispatch instead of an immediate dispatch attempt.
+        if (!item._dependencyConflict) {
+          item._dependencyConflict = buildDependencyConflictMarker({
+            repairWiId: repair.id,
+            conflictBranch: repair.featureBranch || repair._branch || null,
+            conflictsWith: null,
+            isInterDep: !!repair._isInterDepConflict,
+            files: [],
+            detectedAt: item.failedAt || ts(),
+          });
+        } else if (!item._dependencyConflict.repairWiId) {
+          item._dependencyConflict.repairWiId = repair.id;
+        }
+        const prevReason = item.failReason;
+        item.status = WI_STATUS.PENDING;
+        delete item.failReason;
+        delete item.failedAt;
+        delete item._failureClass;
+        delete item._lastDispatchResult;
+        delete item.dispatched_at;
+        delete item.dispatched_to;
+        item._pendingReason = DEP_CONFLICT_PENDING_REASON;
+        needsWrite = true;
+        log('info', `Dependency-conflict reconciliation: revived ${item.id} from failed → pending behind repair ${repair.id} (was: ${prevReason})`);
+      }
+    }
+
     // #2996 follow-up: auto-recover from WORKTREE_DIRTY / WORKTREE_DIVERGENT quarantines.
     // The quarantine is self-healing (dir renamed away, ref backed up, branch reset to
     // origin), so the next dispatch starts from a clean worktree. Auto-flip to pending up
     // to ENGINE_DEFAULTS.quarantineAutoRecoveryMax times so WIs without downstream deps and
     // no human watching don't rot in `failed`. _failureClass is stamped on the WI only by
-    // the force-demote path (engine/dispatch.js); the standard non-retryable path leaves
+    // the force-demote path (engine/orchestration/dispatch.js); the standard non-retryable path leaves
     // it on the dispatch record but embeds the class name in failReason — so detection
     // covers both shapes.
     if (item.status === WI_STATUS.FAILED && !isItemCompleted(item)) {
@@ -10629,6 +11422,37 @@ function discoverFromWorkItems(config, project) {
       }
     }
 
+    // W-mrzqfozm00035365 — recoverable dependency merge-conflict gate. A
+    // downstream item whose dependency branches conflicted during pre-execution
+    // integration carries a `_dependencyConflict` marker instead of a terminal
+    // failure. Decide wait/wake/block from the linked conflict-repair WI's
+    // current status:
+    //   wait  → repair still in progress; keep pending, do NOT redispatch into
+    //           the same conflict (no retry charged).
+    //   wake  → repair done after detection; clear the marker and fall through
+    //           so re-dispatch re-fetches dep refs and recomputes integration.
+    //   block → repair failed/cancelled, or completed before re-detection and
+    //           branches still conflict; keep pending with an actionable
+    //           unresolved reason and DO NOT loop.
+    if (item._dependencyConflict) {
+      const repair = findConflictRepairForBlockedItem(item.id, items, item._dependencyConflict.repairWiId);
+      const gate = evaluateDependencyConflictGate(item, repair);
+      if (gate.action === 'wake') {
+        delete item._dependencyConflict;
+        if (item._pendingReason === DEP_CONFLICT_PENDING_REASON
+            || item._pendingReason === DEP_CONFLICT_UNRESOLVED_PENDING_REASON) {
+          delete item._pendingReason;
+        }
+        needsWrite = true;
+        log('info', `Dependency-conflict gate cleared for ${item.id}: ${gate.reason} — re-running dependency integration on fresh refs`);
+        // fall through to the normal dispatch path.
+      } else {
+        if (item._pendingReason !== gate.pendingReason) { item._pendingReason = gate.pendingReason; needsWrite = true; }
+        skipped.gated++;
+        continue;
+      }
+    }
+
     const key = `work-${project?.name || 'default'}-${item.id}`;
     // Self-heal: collect keys for batched dispatch cleanup.
     selfHealKeys.add(key);
@@ -10795,7 +11619,7 @@ function discoverFromWorkItems(config, project) {
     // extractWorkItemPrRef (title/first-paragraph-of-description text scan),
     // which is fine for prompt-context enrichment (promptItem, above) that
     // downgrades gracefully on a miss. But `dispatch.meta.pr` is a hard signal:
-    // `_isPrBackedDispatch`/`getStalePrDispatchReason` (engine/dispatch.js)
+    // `_isPrBackedDispatch`/`getStalePrDispatchReason` (engine/orchestration/dispatch.js)
     // treat ANY dispatch carrying it as PR-backed and will cancel the source
     // work item outright if the tracked PR turns out to be merged/abandoned/
     // context-only or branch-mismatched. A loose text match against an
@@ -10810,7 +11634,7 @@ function discoverFromWorkItems(config, project) {
     // refactor item whose prose mentioned "PR #3015 for context") and trip
     // the gate even though the item has no real PR target. The dashboard's
     // create-time stamp path keeps using the loose form — gate uses
-    // structured-only; stamp uses loose. See engine/shared.js
+    // structured-only; stamp uses loose. See engine/core/shared.js
     // extractStructuredWorkItemPrRef for the structured-source list.
     if (!linkedPr && getStructuredWorkItemPrRef(item) && (shared.isFixLikeWorkType(workType) || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST)) {
       if (item._pendingReason !== 'pr_not_found') { item._pendingReason = 'pr_not_found'; needsWrite = true; }
@@ -11362,6 +12186,45 @@ function discoverCentralWorkItems(config) {
       continue;
     }
 
+    // W-ms9tcry701xz0389 — pre-spawn PRD result recovery. A previous
+    // plan-to-prd attempt may have produced a perfectly valid sidecar that was
+    // never imported (the dispatch was interrupted, timed out, or its
+    // completion was not accepted). Because `_prdFilename` is now retry-stable
+    // (see the plan-to-prd var block below), that sidecar still declares THIS
+    // work item's expected identity — so import it and finish, instead of
+    // burning another 10-minute model run recreating identical content.
+    // Runs before agent resolution so a recovered item never claims an agent.
+    // consumePrdResultSidecar fails closed: a sidecar belonging to another
+    // work item or source plan is rejected and left untouched.
+    if (workType === WORK_TYPE.PLAN_TO_PRD && item.planFile && item._prdFilename && item.dispatched_to) {
+      const recovery = prdResultSidecar.consumePrdResultSidecar({
+        agentsDir: AGENTS_DIR,
+        agentId: item.dispatched_to,
+        expectedFilename: item._prdFilename,
+        planFile: item.planFile,
+        workItemId: item.id,
+        // W-msa0mrus00mh466f — a recovered revision must normalize exactly like
+        // a completed one, or the sidecar rescue would resurrect the PRD still
+        // flagged revision-requested/stale with its pointers dangling.
+        revisionForPrd: item._revisionForPrd,
+        plansDir: PLANS_DIR,
+      });
+      if (recovery.imported) {
+        mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, {
+          status: WI_STATUS.DONE,
+          completedAt: ts(),
+          _prdFilename: recovery.filename,
+          _artifacts: { ...(item._artifacts || {}), prd: recovery.filename, plan: item.planFile },
+          resultSummary: `Imported the PRD result sidecar left by a prior dispatch attempt (${recovery.filename}) — no re-run needed.`,
+        }));
+        log('info', `plan-to-prd ${item.id}: recovered PRD "${recovery.filename}" from a prior attempt's sidecar — skipping re-dispatch`);
+        continue;
+      }
+      if (recovery.code !== prdResultSidecar.PRD_RESULT_OUTCOME.ABSENT) {
+        log('info', `plan-to-prd ${item.id}: prior sidecar not usable (${recovery.reason}) — dispatching a fresh attempt`);
+      }
+    }
+
     if (isFanOut) {
       // ─── Fan-out: dispatch to ALL idle agents ───────────────────────
       const idleAgents = Object.entries(config.agents)
@@ -11646,13 +12509,29 @@ function discoverCentralWorkItems(config) {
         // `plans/` prefix or separator difference between item.planFile and a
         // PRD's source_plan can't fork a duplicate PRD (#415 class).
         let prdFilename = null;
+        let resolvedPrd = null;
         const planKey = path.basename(String(item.planFile || ''));
         const prdRows = prdStore.listPrdRows();
         const prdFiles = prdRows.filter(row => !row.archived).map(row => row.filename);
+        // Explicit PRD pin (W-msa0mrus00mh466f): a revision / diff-aware regen
+        // work item names the PRD it must rewrite. Honor it before the
+        // source_plan scan so the operation lands on that exact PRD even when
+        // the PRD has no source markdown to match on.
+        if (item._existingPrdFile && prdFiles.includes(item._existingPrdFile)) {
+          const pinned = prdStore.readPrd(item._existingPrdFile);
+          if (pinned && !shared.isPrdArchived(pinned)) {
+            prdFilename = item._existingPrdFile;
+            resolvedPrd = pinned;
+            vars.existing_prd_json = JSON.stringify(pinned, null, 2);
+            log('info', `plan-to-prd: targeting pinned PRD "${prdFilename}" for ${item.id} (_existingPrdFile)`);
+          }
+        }
         for (const pf of prdFiles) {
+          if (prdFilename) break;
           const prd = prdStore.readPrd(pf);
           if (planKey && prd && !shared.isPrdArchived(prd) && shared.prdMatchesSourcePlan(prd.source_plan, planKey)) {
             prdFilename = pf;
+            resolvedPrd = prd;
             vars.existing_prd_json = JSON.stringify(prd, null, 2);
             log('info', `plan-to-prd: reusing existing PRD "${pf}" for plan "${item.planFile}" (#884)`);
             break;
@@ -11664,6 +12543,20 @@ function discoverCentralWorkItems(config) {
         // prepared this same tick — REUSE it so concurrent/repeat plan-to-prd
         // runs for one plan converge to a single PRD instead of splitting into
         // <slug>-<date>.json / -2.json / -3.json. Match by basename.
+        if (!prdFilename && planKey) {
+          // W-ms9tcry701xz0389 — RETRY STABILITY comes first: reuse the
+          // filename THIS item already pinned for THIS plan. The externally
+          // visible result identity (the name the agent is told to declare in
+          // its sidecar) must never be re-derived from transient per-dispatch
+          // state. It used to be: the cross-repo slug is `cross-<uid>` with a
+          // fresh uid per dispatch, so every retry invented a new expected
+          // filename, instantly orphaning the previous attempt's otherwise
+          // valid sidecar and forcing a full regeneration.
+          if (item._prdFilename && (!item._planKey || item._planKey === planKey)) {
+            prdFilename = item._prdFilename;
+            log('info', `plan-to-prd: reusing pinned PRD "${prdFilename}" for ${item.id} (retry-stable identity)`);
+          }
+        }
         if (!prdFilename && planKey) {
           for (const otherItem of items) {
             if (!otherItem || otherItem.id === item.id || !otherItem._prdFilename) continue;
@@ -11715,6 +12608,12 @@ function discoverCentralWorkItems(config) {
           while (prdExisting.has(prdFilename)) { prdFilename = prdBase + '-' + prdCounter + '.json'; prdCounter++; }
         }
         vars.prd_filename = prdFilename;
+        // W-msa0mrus00mh466f — a revision dispatch's ONLY distinguishing input is
+        // the operator's feedback. `planFile` names the source markdown, so
+        // {{plan_content}} renders the plan and the work-item description (which
+        // embeds the feedback) is never spliced into this playbook. Carry the
+        // feedback explicitly, read from the PRD that owns it.
+        vars.revision_feedback = shared.resolvePrdRevisionFeedback(item, resolvedPrd, prdFilename);
         // Pin _planKey alongside _prdFilename so the same-plan in-flight reuse
         // above can recognize a sibling prepared earlier THIS tick by plan.
         mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _prdFilename: prdFilename, _planKey: planKey }));
@@ -11921,10 +12820,10 @@ async function discoverWork(config) {
   // Gated by config.engine?.scheduledWorkDiscoveryEnabled !== false (P-d6f0a2b5).
   if (config.engine?.scheduledWorkDiscoveryEnabled !== false) {
     try {
-      const { discoverScheduledWork } = require('./engine/scheduler');
+      const { discoverScheduledWork } = require('./engine/orchestration/scheduler');
       const scheduledWork = discoverScheduledWork(config);
       if (scheduledWork.length > 0) {
-        const { createMeeting, getMeetings } = require('./engine/meeting');
+        const { createMeeting, getMeetings } = require('./engine/orchestration/meeting');
         // Separate meetings (no work-items write) from task items
         const taskItems = [];
         for (const item of scheduledWork) {
@@ -11982,7 +12881,7 @@ async function discoverWork(config) {
 
   // Meeting work (multi-round team discussions)
   try {
-    const { discoverMeetingWork } = require('./engine/meeting');
+    const { discoverMeetingWork } = require('./engine/orchestration/meeting');
     const meetingWork = discoverMeetingWork(config);
     // #768 — persist immediately, same rationale as the per-project loop above.
     await persistBatch(meetingWork);
@@ -11990,7 +12889,7 @@ async function discoverWork(config) {
 
   // Pipeline orchestration — check stage completions and start ready stages
   try {
-    const { discoverPipelineWork } = require('./engine/pipeline');
+    const { discoverPipelineWork } = require('./engine/orchestration/pipeline');
     await discoverPipelineWork(config);
   } catch (e) { log('warn', 'discover pipeline work: ' + e.message); }
 
@@ -11999,7 +12898,7 @@ async function discoverWork(config) {
   // Throttled to ~10 min (P3 decision) — cadence in ENGINE_DEFAULTS.planCompletionScanEvery
   if (tickCount % (ENGINE_DEFAULTS.planCompletionScanEvery || 60) === 0) {
     try {
-      const lifecycle = require('./engine/lifecycle');
+      const lifecycle = require('./engine/orchestration/lifecycle');
       for (const f of prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename)) {
         if (completedPlanCache.has(f)) continue;
         const plan = prdStore.readPrd(f);
@@ -12322,7 +13221,7 @@ function _resolveTickHardTimeoutMs() {
 // W-mrktrokd — retry default-schedule startup reconciliation until it completes
 // while enabled, then keep the steady-state tick free of config.json work.
 let _scheduleBootstrapDone = false;
-function _runScheduleBootstrapOnce(config, scheduleBootstrap = require('./engine/schedule-bootstrap')) {
+function _runScheduleBootstrapOnce(config, scheduleBootstrap = require('./engine/orchestration/schedule-bootstrap')) {
   if (_scheduleBootstrapDone || !scheduleBootstrap.bootstrapEnabled(config)) return [];
   const reconciled = scheduleBootstrap.ensureBootstrapSchedules();
   if (reconciled === null) return [];
@@ -12343,7 +13242,7 @@ async function tickInner() {
   }
 
   // W-mpcyvff6000pf828 (#2653) — control.heartbeat is written by a dedicated
-  // 15s interval in engine/cli.js (createHeartbeatWriter), decoupled from
+  // 15s interval in engine/operations/cli.js (createHeartbeatWriter), decoupled from
   // tickInner so a slow tick (cold runtime spawn, sequential PR polls, slow
   // worktree create) cannot starve heartbeats and flip the dashboard to STALE
   // on an otherwise healthy engine.
@@ -12357,7 +13256,7 @@ async function tickInner() {
   // dashboard's #engine-quick-stats "Next tick in Xs" countdown has a reliable
   // anchor (control.json carries no separate tick-counter field). Synchronous
   // mutator, no awaits inside the lock — mirrors the writer contract used by
-  // engine/cli.js#writeHeartbeatNow. Distinct from control.heartbeat: this
+  // engine/operations/cli.js#writeHeartbeatNow. Distinct from control.heartbeat: this
   // advances once per tick cadence, not on the 15s heartbeat cadence, so the
   // client can render an accurate "next tick" countdown without coupling to
   // the staleness signal.
@@ -12380,13 +13279,13 @@ async function tickInner() {
   if (_isTickStale(myGeneration)) return;
   safe('checkSteering', () => checkSteering(config));
   safe('checkSpawnPhaseStalls', () => {
-    const { checkSpawnPhaseStalls } = require('./engine/spawn-phase-watchdog');
+    const { checkSpawnPhaseStalls } = require('./engine/agents/spawn-phase-watchdog');
     checkSpawnPhaseStalls(activeProcesses, config);
   });
   safe('checkIdleThreshold', () => checkIdleThreshold(config));
 
   // 1b. Check for meeting round timeouts
-  safe('meetingTimeouts', () => { const { checkMeetingTimeouts } = require('./engine/meeting'); checkMeetingTimeouts(config); });
+  safe('meetingTimeouts', () => { const { checkMeetingTimeouts } = require('./engine/orchestration/meeting'); checkMeetingTimeouts(config); });
 
   // In stopping state, only track agent completions — skip discovery and dispatch
   if (control.state === 'stopping') {
@@ -12418,7 +13317,7 @@ async function tickInner() {
   // disables it; 4h cadence is enforced inside shouldAutoSweep().
   if ((config.engine?.autoConsolidateMemory ?? ENGINE_DEFAULTS.autoConsolidateMemory) === true) {
     safe('autoSweepKb', () => {
-      const { shouldAutoSweep, spawnSweepRunnerDetached } = require('./engine/kb-sweep');
+      const { shouldAutoSweep, spawnSweepRunnerDetached } = require('./engine/memory/kb-sweep');
       const decision = shouldAutoSweep();
       if (!decision.shouldSpawn) return;
       const result = spawnSweepRunnerDetached({
@@ -12447,7 +13346,7 @@ async function tickInner() {
   const keepSweepEvery = Math.max(1, ENGINE_DEFAULTS.keepProcesses?.sweepEvery || 180);
   if (ENGINE_DEFAULTS.keepProcesses?.enabled !== false && tickCount % keepSweepEvery === 0) {
     safe('sweepKeepProcesses', () => {
-      const { sweepKeepProcesses } = require('./engine/keep-process-sweep');
+      const { sweepKeepProcesses } = require('./engine/processes/keep-process-sweep');
       const stats = sweepKeepProcesses();
       if (stats.scanned > 0 && (stats.expiredFiles || stats.deadFiles || stats.malformed)) {
         log('info', `keep-processes sweep: scanned=${stats.scanned} expired=${stats.expiredFiles} dead=${stats.deadFiles} malformed=${stats.malformed} killed=${stats.killedPids}`);
@@ -12465,7 +13364,7 @@ async function tickInner() {
   const managedSweepEvery = Math.max(1, ENGINE_DEFAULTS.managedSpawn?.sweepEvery || 180);
   if (ENGINE_DEFAULTS.managedSpawn?.enabled !== false && tickCount % managedSweepEvery === 0) {
     safe('sweepManagedSpawn', () => {
-      const { sweepManagedSpawn } = require('./engine/managed-spawn');
+      const { sweepManagedSpawn } = require('./engine/processes/managed-spawn');
       const stats = sweepManagedSpawn();
       if (stats.scanned > 0 && (stats.ttlExpired || stats.deadDropped || stats.rotatedLogs || stats.malformed)) {
         log('info', `managed-spawn sweep: scanned=${stats.scanned} ttl=${stats.ttlExpired} dead=${stats.deadDropped} killed=${stats.killedPids} rotated=${stats.rotatedLogs} malformed=${stats.malformed}`);
@@ -12478,7 +13377,7 @@ async function tickInner() {
   // dispatch-end gcDispatchWorktreeIfOrphan couldn't remove (typically Windows
   // file locks: EPERM/EBUSY on lingering spawn-agent.exe handles, AV scans,
   // node_modules\.bin shims). Delegates to `cleanup.runPeriodicWorktreeSweep`,
-  // which runs the two pruners in `engine/worktree-gc.js` against a single
+  // which runs the two pruners in `engine/worktrees/gc.js` against a single
   // shared `dispatchSnap`: (1) in-root `pruneOrphanWorktrees` and (2)
   // out-of-root `pruneOrphanWorktreesFromGitRegistry` (catches `git worktree
   // list` entries outside `worktreeRoot`). Runs at worktreePruneIntervalTicks
@@ -12486,7 +13385,7 @@ async function tickInner() {
   const wtPruneEvery = Math.max(1, ENGINE_DEFAULTS.worktreePruneIntervalTicks || 30);
   if (tickCount % wtPruneEvery === 0) {
     safe('pruneWorktreesPeriodic', () => {
-      const { runPeriodicWorktreeSweep } = require('./engine/cleanup');
+      const { runPeriodicWorktreeSweep } = require('./engine/orchestration/cleanup');
       const stats = runPeriodicWorktreeSweep(config);
       const reportStats = (finalStats) => {
         const removed = finalStats.removed
@@ -12512,8 +13411,8 @@ async function tickInner() {
     safe('checkWatches', () => {
       const { checkWatches } = require('./engine/watches');
       const projects = getProjects(config);
-      const pullRequestStore = require('./engine/pull-requests-store');
-      const workItemStore = require('./engine/work-items-store');
+      const pullRequestStore = require('./engine/persistence/pull-requests-store');
+      const workItemStore = require('./engine/planning/work-items-store');
       const pullRequests = projects.flatMap(p => pullRequestStore.readPullRequestsForScope(p.name));
       const workItems = projects.flatMap(p => workItemStore.readWorkItemsForScope(p.name));
       // Also include central work items
@@ -12523,16 +13422,16 @@ async function tickInner() {
       // best-effort — if a module/file is missing the watch evaluator will
       // simply report "not found" rather than crashing the tick.
       let meetings = [];
-      try { meetings = require('./engine/meeting').getMeetings(); } catch { /* optional */ }
+      try { meetings = require('./engine/orchestration/meeting').getMeetings(); } catch { /* optional */ }
 
-      const plans = require('./engine/prd-store').listPrdRows()
+      const plans = require('./engine/planning/prd-store').listPrdRows()
         .map(({ filename, plan }) => ({ ...plan, _source: filename, _sourcePlan: plan.source_plan || '' }));
 
       let scheduleRuns = {};
-      try { scheduleRuns = require('./engine/small-state-store').readScheduleRuns(); } catch { /* optional */ }
+      try { scheduleRuns = require('./engine/persistence/small-state-store').readScheduleRuns(); } catch { /* optional */ }
 
       let pipelineRuns = {};
-      try { pipelineRuns = require('./engine/pipeline').getPipelineRuns(); } catch { /* optional */ }
+      try { pipelineRuns = require('./engine/orchestration/pipeline').getPipelineRuns(); } catch { /* optional */ }
 
       let dispatch = { pending: [], active: [], completed: [] };
       try { dispatch = queries.getDispatch() || dispatch; } catch { /* optional */ }
@@ -12776,7 +13675,7 @@ async function tickInner() {
                   // W-mrdykpv60005d50d: don't resurrect items whose failure class is explicitly
                   // non-retryable (AUTH, INJECTION_FLAGGED, PRE_DISPATCH_EVAL_STUCK, etc.) — mirrors
                   // the same isRetryableFailureReason() gate used by the dispatch-completion retry path
-                  // (engine/dispatch.js:764) and the quarantine auto-recovery block above (engine.js:8804-8811).
+                  // (engine/orchestration/dispatch.js:764) and the quarantine auto-recovery block above (engine.js:8804-8811).
                   if (!isRetryableFailureReason(item.failReason, item._failureClass)) {
                     log('info', `Stall recovery: skipping ${item.id} — failure class '${item._failureClass || 'unknown'}' is non-retryable`);
                     continue;
@@ -13103,8 +14002,28 @@ async function tickInner() {
     // item itself resolves to live mode — worktree-mode coding items on
     // the same project remain uncapped.
     const itemProjName = item.project || item.meta?.project?.name || null;
+    // W-ms5tb6ha016fda10: resolved fail-closed from the item's own declaration.
+    // An item that allocates NO local checkout — control-plane (API/CLI only)
+    // or cloud (a remote agent owns the workspace) — cannot legitimately be
+    // blocked by any of the checkout-allocation gates below: the live-mode
+    // concurrency cap, the operator branch hold, the worktree free-space
+    // preflight, or the live-checkout dirty/stale-base precheck. Gating on the
+    // resolved SURFACE rather than on control-plane specifically is what keeps
+    // a second no-checkout surface from silently inheriting repo-shaped gates
+    // (and pending as `worktree_low_disk_space` instead of its own honest
+    // reason). Both predicates fail closed, so anything malformed resolves to
+    // `repo` and keeps today's behavior.
+    const _itemIsControlPlane = shared.isControlPlaneExecution(item, item.type);
+    const _itemExecutionSurface = _itemIsControlPlane
+      ? shared.EXECUTION_SURFACE.CONTROL_PLANE
+      : (shared.isCloudExecution(item, item.type)
+        ? shared.EXECUTION_SURFACE.CLOUD
+        : shared.EXECUTION_SURFACE.REPO);
+    const _itemSkipsCheckoutAllocation =
+      _itemExecutionSurface !== shared.EXECUTION_SURFACE.REPO;
     if (
       itemProjName
+      && !_itemSkipsCheckoutAllocation
       && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
       && liveProjectsInUse.has(itemProjName)
     ) {
@@ -13122,7 +14041,7 @@ async function tickInner() {
       const _branchHoldProjCfg = shared.findProjectByName(shared.getProjects(config), itemProjName);
       const _allocationBranchHold = await _checkWorktreeBranchHoldForDispatch(
         _branchHoldProjCfg, item.type, itemBranch, config,
-        { listWorktrees: listAllocationWorktrees },
+        { listWorktrees: listAllocationWorktrees, executionSurface: _itemExecutionSurface },
       );
       if (_isTickStale(myGeneration)) return;
       if (_allocationBranchHold?.held) {
@@ -13142,7 +14061,9 @@ async function tickInner() {
     // filesystem has the minimum free-space reserve.
     if (itemProjName) {
       const _diskProjCfg = shared.findProjectByName(shared.getProjects(config), itemProjName);
-      const _allocationDiskPreflight = _checkWorktreeDiskSpaceForDispatch(_diskProjCfg, item.type, config);
+      const _allocationDiskPreflight = _checkWorktreeDiskSpaceForDispatch(
+        _diskProjCfg, item.type, config, { executionSurface: _itemExecutionSurface },
+      );
       if (_allocationDiskPreflight && !_allocationDiskPreflight.ok) {
         const pendingReason = _persistWorktreeDiskPreflight(item, _allocationDiskPreflight);
         _writeWorktreeDiskPreflightAlert(item, _diskProjCfg, _allocationDiskPreflight);
@@ -13168,12 +14089,13 @@ async function tickInner() {
     // fire rarely, as the exception path rather than the common path.
     if (
       itemProjName
+      && !_itemSkipsCheckoutAllocation
       && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
     ) {
       const _precheckProjCfg = shared.findProjectByName(shared.getProjects(config), itemProjName);
       if (_precheckProjCfg && shared.resolveCheckoutMode(_precheckProjCfg, item.type) === 'live' && _precheckProjCfg.localPath) {
         const _precheckLocalPath = path.resolve(String(_precheckProjCfg.localPath));
-        const _liveCheckoutPrecheck = require('./engine/live-checkout');
+        const _liveCheckoutPrecheck = require('./engine/worktrees/live-checkout');
         const _persistPendingReason = (reason) => {
           item._pendingReason = reason;
           try {
@@ -13303,7 +14225,7 @@ async function tickInner() {
   // rather than awaiting each spawnAgent serially. `spawnAgent` does real
   // wall-clock work per item (prompt build + `git worktree add`, which on a
   // ~250k-file monorepo can take multiple seconds), so the old sequential loop
-  // made eager routing (engine/routing.js already fans work across every idle
+  // made eager routing (engine/orchestration/routing.js already fans work across every idle
   // agent in a single allocation pass) visibly "trickle in" one agent at a time,
   // contradicting the stated eager-dispatch design. `toDispatch` is already
   // bounded by `slotsAvailable` (≤ maxConcurrent — the seed loop above decrements
@@ -13594,7 +14516,7 @@ function emitMemoryBaseline(tickN) {
     `gcPauses=${sample.gcCount}/${sample.gcPausesTotalMs.toFixed(2)}ms tickN=${tickN}`);
 }
 
-// ─── Exports (for engine/cli.js and other modules) ──────────────────────────
+// ─── Exports (for engine/operations/cli.js and other modules) ──────────────────────────
 
 module.exports = {
   // Paths
@@ -13605,13 +14527,15 @@ module.exports = {
   // Utilities
   ts, logTs, dateStamp, log,
   safeJson, safeRead, safeWrite,
+  buildQaSessionServices, // exported for testing (W-msb9kgs402813a97-a)
+  buildQaExecuteJourneyContract, // exported for testing (W-msb9kgs402813a97-c)
 
   // State readers/writers
   getConfig, getControl, getDispatch, getRouting, getNotes,
   getAgentStatus, getInboxFiles, getPrs,
   validateConfig,
 
-  // Dispatch management (re-exported from engine/dispatch.js)
+  // Dispatch management (re-exported from engine/orchestration/dispatch.js)
   mutateDispatch, addToDispatch, addToDispatchWithValidation, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus, pruneStalePrDispatches, pruneStalePrDispatchesAsync,
   activeProcesses, realActivityMap, engineRestartGraceExempt,
   get engineRestartGraceUntil() { return engineRestartGraceUntil; },
@@ -13634,6 +14558,9 @@ module.exports = {
   resolveDependencyBranches, buildCrossRepoDepsSection, // exported for testing (P-faea3206)
   gitOutputToString, gitErrorOutput, classifyDepMergeFailureOutput, listUnmergedFiles, // exported for testing
   buildDepConflictFixItem, deriveConflictFixKey, // exported for testing (W-mpcwojgr000a0244)
+  buildDependencyConflictMarker, findConflictRepairForBlockedItem, // exported for testing (W-mrzqfozm00035365)
+  evaluateDependencyConflictGate, shouldReviveFailedDependencyConflict, // exported for testing (W-mrzqfozm00035365)
+  DEP_CONFLICT_PENDING_REASON, DEP_CONFLICT_UNRESOLVED_PENDING_REASON, // exported for testing (W-mrzqfozm00035365)
   runWorktreeAdd, // exported for testing (W-mqvaxv65000m76f2 — GVFS partial-checkout behavioral test)
   _fetchWithTransientRetry, _classifyFreshBaseFetchFailure, _probeBranchLocally, // exported for testing
   isWorktreeRetryableError, syncReusedWorktree, pushCleanAheadBranch, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
@@ -13650,6 +14577,8 @@ module.exports = {
   _tryAutoResolveLiveCheckoutWorktreeConflict, // exported for testing (W-mr28h2j2000y0de1 review — auto-resolve worktree conflicts)
   _isOutputTruncated, AGENT_OUTPUT_CAP_BYTES, // P-8e4c2a17: exported for testing (OUTPUT_TRUNCATED detection)
   promoteCheckpointSteeringForClose, // exported for testing
+  resolveCloseCompletionBoundary, // exported for testing (W-ms9tcs3o01y03383)
+  releasePendingSteeringResumeForCompletedTurn, // exported for testing (W-ms9tcs3o01y03383)
   normalizePrBranch, resolvePrBranch, prCausePart, getPrCauseHead, getPrCauseBase, getPrAutomationCauseKey, getPrAutomationDispatchKey, // exported for testing
   isPrReviewCurrent, isPrFixedAfterReview, // exported for testing (W-mrej8p740006b0bf — SHA-based review freshness)
   ensurePrBranchForDispatch, isWithinLinkGraceWindow, PR_LINK_GRACE_WINDOW_MS, // exported for testing (W-mphm0kt0000cebc3)
@@ -13661,10 +14590,10 @@ module.exports = {
   resolvePriorExploreContext, // exported for testing (P-mqyp0008v022w3x4 SHERLOC)
   renderProjectWorkItemPromptForAgent, // exported for testing
 
-  // Timeout / Steering / Idle (re-exported from engine/timeout.js)
+  // Timeout / Steering / Idle (re-exported from engine/orchestration/timeout.js)
   checkTimeouts, checkSteering, checkIdleThreshold,
 
-  // Cleanup (re-exported from engine/cleanup.js)
+  // Cleanup (re-exported from engine/orchestration/cleanup.js)
   runCleanup,
 
   // Post-completion / lifecycle
@@ -13750,7 +14679,7 @@ function ensureGitHooksInstalled() {
 
 if (require.main === module) {
   try { ensureGitHooksInstalled(); } catch { /* best-effort */ }
-  const { handleCommand } = require('./engine/cli');
+  const { handleCommand } = require('./engine/operations/cli');
   const [cmd, ...args] = process.argv.slice(2);
   handleCommand(cmd, args);
 }