oxe-cc 1.8.0 → 1.9.1

package/bin/lib/oxe-operational.cjs

@@ -456,6 +456,61 @@ function reduceCanonicalRunState(projectRoot, activeSession, options = {}) {
   return serializeCanonicalState(reduceCanonicalRunStateLive(projectRoot, activeSession, options));
 }
 
+/**
+ * Static-analysis lints for common pitfalls detectable before execution.
+ * Returns hint strings to be appended to validationErrors (shown at compile time).
+ */
+function lintPlanForCommonPitfalls(parsedPlan, parsedSpec, projectRoot, rawSpecText = '') {
+  const hints = [];
+  const specText = (parsedSpec && parsedSpec.objective ? parsedSpec.objective : '') +
+    JSON.stringify(parsedSpec && parsedSpec.criteria ? parsedSpec.criteria : []) +
+    (rawSpecText || '');
+  const planTasks = parsedPlan && Array.isArray(parsedPlan.tasks) ? parsedPlan.tasks : [];
+
+  // ── Lint 1: HTML/JS SPA sem restrição de file:// ──────────────────────────
+  // Detects: spec mentions HTML/SPA + no files restriction, but no verify command
+  // checks for fetch() absence. Warns to add a fetch-detection verify.
+  const isHtmlApp = /html|spa|browser|page|frontend|estático|static|aplicação web|web app|web page|interface web|\.html/i.test(specText);
+  if (isHtmlApp) {
+    const hasFetchGuard = planTasks.some(t =>
+      t.verifyCommand && /fetch|XMLHttpRequest|file:\/\//i.test(t.verifyCommand)
+    );
+    const specMentionsServer = /servidor|server|http-server|localhost|npx serve|vite|webpack/i.test(specText);
+    const specMentionsFileProtocol = /file:\/\/|sem servidor|without server|no.server/i.test(specText);
+    if (!hasFetchGuard && !specMentionsServer && !specMentionsFileProtocol) {
+      hints.push(
+        'HINT(html-fetch): SPEC não declara se o app precisa de servidor HTTP. ' +
+        'Se abrir em file://, adicione à SPEC: "sem servidor HTTP" e um verify que detecte fetch(): ' +
+        '`node -e "if(require(\'fs\').readFileSync(\'app.js\',\'utf8\').includes(\'fetch(\'))throw new Error(\'fetch not allowed in file://\')"`'
+      );
+    }
+  }
+
+  // ── Lint 2: Verify commands que só verificam existência de função, não comportamento ──
+  const existenceOnlyVerify = planTasks.filter(t =>
+    t.verifyCommand &&
+    /s\.includes\(/.test(t.verifyCommand) &&
+    !/existsSync|readFileSync.*utf8|require\(/.test(t.verifyCommand)
+  );
+  if (existenceOnlyVerify.length > 2) {
+    hints.push(
+      `HINT(verify-depth): ${existenceOnlyVerify.length} tarefa(s) verificam apenas presença de string no código ` +
+      `(s.includes). Considere adicionar verificações de comportamento: executar o código, não só inspecioná-lo.`
+    );
+  }
+
+  // ── Lint 3: Tarefas sem verify command (T-level) ──────────────────────────
+  const noVerify = planTasks.filter(t => !t.verifyCommand && !t.done);
+  if (noVerify.length > 0) {
+    hints.push(
+      `HINT(no-verify): ${noVerify.length} tarefa(s) sem Comando de verificação: ${noVerify.map(t => t.id).join(', ')}. ` +
+      `Tarefas sem verify não serão testadas inline pelo scheduler.`
+    );
+  }
+
+  return hints;
+}
+
 function compileExecutionGraphFromArtifacts(projectRoot, activeSession, options = {}) {
   const runtime = loadRuntimeModule();
   const parsers = loadSdkParsers();
@@ -468,12 +523,17 @@ function compileExecutionGraphFromArtifacts(projectRoot, activeSession, options
   const artifactPaths = resolveRuntimeArtifactPaths(projectRoot, activeSession);
   const specText = readTextIfExists(artifactPaths.spec);
   const planText = readTextIfExists(artifactPaths.plan);
-  if (!specText) throw new Error(`SPEC.md ausente em ${artifactPaths.spec}`);
-  if (!planText) throw new Error(`PLAN.md ausente em ${artifactPaths.plan}`);
+  if (!specText) throw new Error(`SPEC.md ausente em ${artifactPaths.spec}\n  Crie .oxe/SPEC.md com /oxe-spec no seu agente, ou use o template em oxe/templates/SPEC.template.md`);
+  if (!planText) throw new Error(`PLAN.md ausente em ${artifactPaths.plan}\n  Crie .oxe/PLAN.md com /oxe-plan no seu agente (requer SPEC.md), ou use o template em oxe/templates/PLAN.template.md`);
   const parsedSpec = parsers.parseSpec(specText);
   const parsedPlan = parsers.parsePlan(planText);
   const graph = runtime.compile(parsedPlan, parsedSpec, options.compilerOptions || {});
   const validationErrors = typeof runtime.validateGraph === 'function' ? runtime.validateGraph(graph) : [];
+
+  // Static-analysis lints: detect common patterns that cause runtime failures
+  const lintHints = lintPlanForCommonPitfalls(parsedPlan, parsedSpec, projectRoot, specText);
+  if (lintHints.length) validationErrors.push(...lintHints);
+
   const compiledGraph = runtime.toSerializable(graph);
   const current = options.runState || readRunState(projectRoot, activeSession) || {};
   const runId = current.run_id || makeRunId();
@@ -662,24 +722,106 @@ async function resolveRuntimeGate(projectRoot, activeSession, options = {}) {
   };
 }
 
-// Gap 5: route execution to MultiAgentCoordinator when plan-agents.json exists
-async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
-  const runtime = loadRuntimeModule();
-  if (!runtime) throw new Error('Runtime package não está disponível. Rode npm run build:runtime.');
+  // Gap 5: route execution to MultiAgentCoordinator when plan-agents.json exists
+function buildRuntimeExecutePreflight(projectRoot, activeSession, runState) {
+    const health = loadProjectHealth();
+    const blockers = [];
+    const warnings = [];
+    let report = null;
+    if (health && typeof health.buildHealthReport === 'function') {
+      report = health.buildHealthReport(projectRoot);
+      if (report.planSelfEvaluation && report.planSelfEvaluation.executable === false) {
+        const confidence = report.planSelfEvaluation.confidence;
+        const threshold = report.planConfidenceThreshold || 90;
+        blockers.push(`plan_confidence:${confidence == null ? 'missing' : `${confidence}%`}<=${threshold}%`);
+      }
+      if (report.executionRationality && report.executionRationality.applicable && !report.executionRationalityReady) {
+        const gaps = Array.isArray(report.criticalExecutionGaps) ? report.criticalExecutionGaps : [];
+        blockers.push(`execution_rationality:${gaps[0] || 'not_ready'}`);
+      }
+      if (report.fallbackMode && report.fallbackMode !== 'none') {
+        warnings.push(`fallback_mode:${report.fallbackMode}`);
+      }
+    } else {
+      warnings.push('health_report_unavailable');
+    }
+    const runId = runState && runState.run_id ? runState.run_id : null;
+    const queue = readRuntimeGates(projectRoot, activeSession, { runId });
+    if (queue.pending.length > 0) {
+      blockers.push(`pending_gates:${queue.pending.length}`);
+    }
+    return {
+      ok: blockers.length === 0,
+      blockers,
+      warnings,
+      runId,
+      gateQueue: {
+        pending: queue.pending.length,
+        stale: queue.staleCount || 0,
+      },
+      confidence: report && report.planSelfEvaluation ? report.planSelfEvaluation.confidence : null,
+      confidenceThreshold: report ? report.planConfidenceThreshold || 90 : 90,
+      executionRationalityReady: report ? Boolean(report.executionRationalityReady) : false,
+    };
+  }
+
+  async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
+    const runtime = loadRuntimeModule();
+    if (!runtime) throw new Error('Runtime package não está disponível. Rode npm run build:runtime.');
   const parsers = loadSdkParsers();
   if (!parsers) throw new Error('SDK parsers não disponíveis.');
 
+  // Auto-wire LlmTaskExecutor if providerConfig is supplied
+  let executor = options.executor || null;
+  if (!executor && options.providerConfig) {
+    if (typeof runtime.LlmTaskExecutor !== 'function') throw new Error('Runtime não exporta LlmTaskExecutor.');
+    executor = new runtime.LlmTaskExecutor(options.providerConfig, null, options.onProgress || null);
+  }
+  // Auto-wire InplaceWorkspaceManager as default
+  let workspaceManager = options.workspaceManager || null;
+  if (!workspaceManager) {
+    if (typeof runtime.InplaceWorkspaceManager === 'function') {
+      workspaceManager = new runtime.InplaceWorkspaceManager(projectRoot);
+    }
+  }
+
   // Resolve compiled graph from run state or compile on demand
   let current = options.runState || readRunState(projectRoot, activeSession);
-  if (!current || !current.compiled_graph) {
-    current = compileExecutionGraphFromArtifacts(projectRoot, activeSession, { runState: current }).run;
-  }
-  if (!current || !current.compiled_graph) {
-    throw new Error('Nenhum grafo compilado encontrado. Execute oxe-cc runtime compile primeiro.');
-  }
-  const graph = runtime.fromSerializable
-    ? runtime.fromSerializable(current.compiled_graph)
-    : current.compiled_graph;
+    if (!current || !current.compiled_graph) {
+      current = compileExecutionGraphFromArtifacts(projectRoot, activeSession, { runState: current }).run;
+    }
+    if (!current || !current.compiled_graph) {
+      throw new Error('Nenhum grafo compilado encontrado. Execute oxe-cc runtime compile primeiro.');
+    }
+    const preflight = buildRuntimeExecutePreflight(projectRoot, activeSession, current);
+    if (!preflight.ok && !options.skipPreflight) {
+      const reason = preflight.blockers[0] || 'runtime_execute_preflight_failed';
+      appendEvent(projectRoot, activeSession, {
+        type: 'WorkItemBlocked',
+        run_id: current.run_id,
+        payload: {
+          reason: 'runtime_execute_preflight_failed',
+          blockers: preflight.blockers,
+        },
+      });
+      return {
+        mode: 'preflight',
+        agentPlan: null,
+        result: {
+          run_id: current.run_id,
+          status: 'blocked',
+          completed: [],
+          failed: [],
+          blocked: ['runtime_execute_preflight'],
+          reason,
+        },
+        run: current,
+        preflight,
+      };
+    }
+    const graph = runtime.fromSerializable
+      ? runtime.fromSerializable(current.compiled_graph)
+      : current.compiled_graph;
 
   // Detect plan-agents.json (session path takes priority over root)
   const rootAgentPlan = path.join(projectRoot, '.oxe', 'plan-agents.json');
@@ -693,45 +835,53 @@ async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
   // Build ctx with GateManager (Gap 1)
   const ctx = createExecutionContext(projectRoot, activeSession, {
     runId: current.run_id,
-    executor: options.executor || null,
-    workspaceManager: options.workspaceManager || null,
+    executor,
+    workspaceManager,
     pluginRegistry: options.pluginRegistry || buildRuntimePluginRegistry(projectRoot),
     schedulerOptions: options.schedulerOptions || {},
-    onEvent: (event) => appendEvent(projectRoot, activeSession, event),
+    onEvent: (event) => {
+      appendEvent(projectRoot, activeSession, event);
+      options.onProgress?.(event);
+    },
   });
 
   // Gap 5: multi-agent path if plan-agents.json exists
   if (agentPlanPath) {
     let agentPlan;
-    try {
-      agentPlan = JSON.parse(fs.readFileSync(agentPlanPath, 'utf8'));
-    } catch (err) {
-      throw new Error(`plan-agents.json inválido: ${err.message}`);
-    }
-    if (!Array.isArray(agentPlan.agents) || agentPlan.agents.length === 0) {
-      throw new Error('plan-agents.json não contém agentes válidos (campo "agents" vazio ou ausente).');
-    }
-    if (typeof runtime.MultiAgentCoordinator !== 'function') {
-      throw new Error('Runtime não exporta MultiAgentCoordinator. Verifique a versão do runtime.');
-    }
-    const agents = agentPlan.agents.map((spec) => ({
-      id: spec.id,
-      executor: options.executorFactory ? options.executorFactory(spec) : (options.executor || null),
-      workspaceManager: options.workspaceManager || null,
-      assignedTaskIds: Array.isArray(spec.tasks) ? spec.tasks : [],
-    }));
+    try {
+      agentPlan = JSON.parse(fs.readFileSync(agentPlanPath, 'utf8'));
+    } catch (err) {
+      throw new Error(`plan-agents.json inválido: ${err.message}`);
+    }
+    const planErrors = validateMultiAgentPlan(agentPlan);
+    if (planErrors.length > 0) {
+      throw new Error(`plan-agents.json inválido: ${planErrors.join('; ')}`);
+    }
+    if (typeof runtime.MultiAgentCoordinator !== 'function') {
+      throw new Error('Runtime não exporta MultiAgentCoordinator. Verifique a versão do runtime.');
+    }
+    if (typeof runtime.GitWorktreeManager !== 'function' && !options.workspaceManager) {
+      throw new Error('Runtime não exporta GitWorktreeManager. Multi-agent real exige backend git_worktree.');
+    }
+    const agents = agentPlan.agents.map((spec) => ({
+      id: spec.id,
+      executor: options.executorFactory ? options.executorFactory(spec) : (options.executor || executor),
+      workspaceManager: options.workspaceManager || new runtime.GitWorktreeManager(projectRoot),
+      assignedTaskIds: Array.isArray(spec.tasks) ? spec.tasks : [],
+    }));
     const coordinator = new runtime.MultiAgentCoordinator();
     const result = await coordinator.run(graph, {
       mode: agentPlan.mode || 'parallel',
       agents,
       projectRoot,
       sessionId: activeSession || null,
-      runId: current.run_id,
-      heartbeatTimeoutMs: options.heartbeatTimeoutMs ?? 120000,
-      onEvent: ctx.onEvent,
-    });
-    return { mode: agentPlan.mode || 'parallel', agentPlan, result, run: current };
-  }
+      runId: current.run_id,
+      heartbeatTimeoutMs: options.heartbeatTimeoutMs ?? 120000,
+      applyWorkspaceMerges: true,
+      onEvent: ctx.onEvent,
+    });
+      return { mode: agentPlan.mode || 'parallel', agentPlan, result, run: current, preflight };
+    }
 
   // Single-agent fallback
   if (typeof runtime.Scheduler !== 'function') {
@@ -739,8 +889,8 @@ async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
   }
   const scheduler = new runtime.Scheduler();
   const result = await scheduler.run(graph, ctx);
-  return { mode: 'single', agentPlan: null, result, run: current };
-}
+    return { mode: 'single', agentPlan: null, result, run: current, preflight };
+  }
 
 function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
   const runtime = loadRuntimeModule();
@@ -755,23 +905,32 @@ function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
       workspaceIsolationEnforced: false,
       agents: [],
       ownership: [],
-      orphanReassignments: [],
-      handoffs: [],
-      arbitrationResults: [],
-      summary: null,
-    };
+      orphanReassignments: [],
+      handoffs: [],
+      arbitrationResults: [],
+      workspaceMergeReport: null,
+      worktrees: [],
+      mergeBlockers: [],
+      mergeReadiness: null,
+      arbitrationRequired: false,
+      summary: null,
+    };
   }
   const runDir = path.join(projectRoot, '.oxe', 'runs', runId);
   const statePath = path.join(runDir, 'multi-agent-state.json');
-  const summaryPath = path.join(runDir, 'multi-agent-summary.json');
-  const handoffsPath = path.join(runDir, 'handoffs.json');
-  const arbitrationPath = path.join(runDir, 'arbitration-results.json');
+  const summaryPath = path.join(runDir, 'multi-agent-summary.json');
+  const handoffsPath = path.join(runDir, 'handoffs.json');
+  const arbitrationPath = path.join(runDir, 'arbitration-results.json');
+  const workspaceMergePath = path.join(runDir, 'workspace-merge-report.json');
   const state = runtime && typeof runtime.loadMultiAgentState === 'function'
     ? runtime.loadMultiAgentState(projectRoot, runId)
     : readJsonIfExists(statePath);
-  const summary = runtime && typeof runtime.loadMultiAgentSummary === 'function'
-    ? runtime.loadMultiAgentSummary(projectRoot, runId)
-    : readJsonIfExists(summaryPath);
+  const summary = runtime && typeof runtime.loadMultiAgentSummary === 'function'
+    ? runtime.loadMultiAgentSummary(projectRoot, runId)
+    : readJsonIfExists(summaryPath);
+  const workspaceMergeReport = runtime && typeof runtime.loadWorkspaceMergeReport === 'function'
+    ? runtime.loadWorkspaceMergeReport(projectRoot, runId)
+    : readJsonIfExists(workspaceMergePath);
   const handoffs = readJsonIfExists(handoffsPath);
   const arbitrationResults = readJsonIfExists(arbitrationPath);
   return {
@@ -784,10 +943,41 @@ function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
     ownership: state && Array.isArray(state.ownership) ? state.ownership : [],
     orphanReassignments: state && Array.isArray(state.orphan_reassignments) ? state.orphan_reassignments : [],
     handoffs: Array.isArray(handoffs) ? handoffs : [],
-    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
-    summary: summary || null,
-  };
-}
+    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
+    workspaceMergeReport: workspaceMergeReport || null,
+    worktrees: workspaceMergeReport && Array.isArray(workspaceMergeReport.records) ? workspaceMergeReport.records : [],
+    mergeBlockers: workspaceMergeReport && Array.isArray(workspaceMergeReport.blockers) ? workspaceMergeReport.blockers : [],
+    mergeReadiness: workspaceMergeReport && workspaceMergeReport.merge_readiness ? workspaceMergeReport.merge_readiness : null,
+    arbitrationRequired: Boolean(workspaceMergeReport && workspaceMergeReport.arbitration_required),
+    summary: summary || null,
+  };
+}
+
+function validateMultiAgentPlan(agentPlan) {
+  const errors = [];
+  const allowedModes = new Set(['parallel', 'competitive', 'cooperative']);
+  const mode = agentPlan && agentPlan.mode ? String(agentPlan.mode) : 'parallel';
+  if (!allowedModes.has(mode)) errors.push(`mode inválido: ${mode}`);
+  if (!Array.isArray(agentPlan && agentPlan.agents) || agentPlan.agents.length === 0) {
+    errors.push('campo "agents" vazio ou ausente');
+    return errors;
+  }
+  const schemaVersion = Number(agentPlan.schema_version || agentPlan.schema || 0);
+  const seen = new Set();
+  for (const [idx, spec] of agentPlan.agents.entries()) {
+    const id = spec && spec.id ? String(spec.id) : '';
+    if (!id) errors.push(`agents[${idx}].id ausente`);
+    if (id && seen.has(id)) errors.push(`agent duplicado: ${id}`);
+    if (id) seen.add(id);
+    if (schemaVersion >= 3 && !spec.persona) errors.push(`${id || `agents[${idx}]`}.persona ausente`);
+    if (schemaVersion >= 3 && !spec.model_hint) errors.push(`${id || `agents[${idx}]`}.model_hint ausente`);
+    if (spec.tasks != null && !Array.isArray(spec.tasks)) errors.push(`${id || `agents[${idx}]`}.tasks deve ser array`);
+  }
+  if ((mode === 'competitive' || mode === 'cooperative') && agentPlan.agents.length < 2) {
+    errors.push(`${mode} exige pelo menos 2 agentes`);
+  }
+  return errors;
+}
 
 function loadRuntimeVerificationArtifacts(projectRoot, runState) {
   const runtime = loadRuntimeModule();
@@ -813,7 +1003,7 @@ function loadRuntimeVerificationArtifacts(projectRoot, runState) {
   return { manifest, residualRisks, evidenceCoverage };
 }
 
-function countVerificationEvidenceRefs(runState, verificationArtifacts) {
+function countVerificationEvidenceRefs(runState, verificationArtifacts) {
   if (verificationArtifacts && verificationArtifacts.manifest && Array.isArray(verificationArtifacts.manifest.checks)) {
     return verificationArtifacts.manifest.checks.reduce((sum, check) => {
       return sum + (Array.isArray(check.evidence_refs) ? check.evidence_refs.length : 0);
@@ -825,7 +1015,26 @@ function countVerificationEvidenceRefs(runState, verificationArtifacts) {
     }, 0);
   }
   return 0;
-}
+}
+
+function detectOrphanWorktrees(projectRoot, runId) {
+  const workspacesDir = path.join(projectRoot, '.oxe', 'workspaces');
+  if (!fs.existsSync(workspacesDir)) return [];
+  const active = new Set();
+  const mergeReport = readJsonIfExists(path.join(projectRoot, '.oxe', 'runs', runId, 'workspace-merge-report.json'));
+  for (const record of (mergeReport && Array.isArray(mergeReport.records) ? mergeReport.records : [])) {
+    if (record && record.workspace_id) active.add(String(record.workspace_id));
+  }
+  return fs.readdirSync(workspacesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => !active.has(name))
+    .map((name) => ({
+      workspace_id: name,
+      path: path.join(workspacesDir, name),
+      next_action: 'inspecione o worktree órfão; depois remova com git worktree remove --force se não houver diffs úteis',
+    }));
+}
 
 function buildRuntimeModeStatus(runState) {
   if (!runState) {
@@ -906,6 +1115,11 @@ function buildRecoveryConsistency(projectRoot, activeSession, runState, journal,
   const runDir = runState && runState.run_id ? path.join(projectRoot, '.oxe', 'runs', runState.run_id) : null;
   const allEvents = readEvents(projectRoot, activeSession);
   const runEvents = runState && runState.run_id ? allEvents.filter((event) => event.run_id === runState.run_id) : [];
+  // Detect if execution has ever started (at least one attempt recorded)
+  const attemptCount = runState && runState.canonical_state && runState.canonical_state.summary
+    ? (runState.canonical_state.summary.attempt_count || 0)
+    : 0;
+  const executionStarted = attemptCount > 0;
   const issues = [];
   if (!activeRunRef || activeRunRef.run_id !== (runState && runState.run_id)) {
     issues.push('ACTIVE-RUN.json não referencia o mesmo run persistido em .oxe/runs/.');
@@ -913,10 +1127,12 @@ function buildRecoveryConsistency(projectRoot, activeSession, runState, journal,
   if (!runFile || !fs.existsSync(runFile)) {
     issues.push('Arquivo canónico da run ausente em .oxe/runs/<run>.json.');
   }
-  if (!journal) {
+  // Journal is only created after execution starts — skip this check pre-execution
+  if (!journal && executionStarted) {
     issues.push('Journal ausente para recover/replay.');
   }
-  if (runEvents.length === 0) {
+  // Events for this run only exist after execution — skip pre-execution
+  if (runEvents.length === 0 && executionStarted) {
     issues.push('Nenhum evento NDJSON encontrado para a run ativa.');
   }
   if (!runState || !runState.canonical_state) {
@@ -990,11 +1206,17 @@ function writeRecoverySummaryMarkdown(projectRoot, activeSession, runState, reco
     '',
     '## Work items órfãos',
     '',
-    ...(Array.isArray(recoverySummary.orphan_work_items) && recoverySummary.orphan_work_items.length
-      ? recoverySummary.orphan_work_items.map((item) => `- ${item}`)
-      : ['- Nenhum']),
-    '',
-    '## Tentativas incompletas',
+    ...(Array.isArray(recoverySummary.orphan_work_items) && recoverySummary.orphan_work_items.length
+      ? recoverySummary.orphan_work_items.map((item) => `- ${item}`)
+      : ['- Nenhum']),
+    '',
+    '## Worktrees órfãos',
+    '',
+    ...(Array.isArray(recoverySummary.orphan_worktrees) && recoverySummary.orphan_worktrees.length
+      ? recoverySummary.orphan_worktrees.map((item) => `- ${item.workspace_id} · ${item.next_action}`)
+      : ['- Nenhum']),
+    '',
+    '## Tentativas incompletas',
     '',
     ...(recoverySummary.consistency && Array.isArray(recoverySummary.consistency.incomplete_attempts) && recoverySummary.consistency.incomplete_attempts.length
       ? recoverySummary.consistency.incomplete_attempts.map((item) => `- ${item.work_item_id} · ${item.attempt_id || 'attempt'} · ${item.outcome || 'unknown'}`)
@@ -1146,7 +1368,7 @@ function projectRuntimeArtifacts(projectRoot, activeSession, options = {}) {
   const paths = resolveRuntimeArtifactPaths(projectRoot, activeSession);
   const op = operationalPaths(projectRoot, activeSession);
   const projectionRefs = {
-    plan_ref: path.relative(projectRoot, paths.plan).replace(/\\/g, '/'),
+    plan_ref: path.relative(projectRoot, paths.plan.replace(/PLAN\.md$/, 'PLAN-STATUS.md')).replace(/\\/g, '/'),
     verify_ref: path.relative(projectRoot, paths.verify).replace(/\\/g, '/'),
     state_ref: path.relative(projectRoot, paths.state).replace(/\\/g, '/'),
     run_summary_ref: path.relative(projectRoot, path.join(op.executionRoot, 'RUN-SUMMARY.md')).replace(/\\/g, '/'),
@@ -1156,10 +1378,12 @@ function projectRuntimeArtifacts(projectRoot, activeSession, options = {}) {
     generated_at: new Date().toISOString(),
   };
   if (options.write !== false) {
-    ensureDirForFile(paths.plan);
+    // Write plan projection to PLAN-STATUS.md — never overwrite the source PLAN.md
+    const planStatusPath = paths.plan.replace(/PLAN\.md$/, 'PLAN-STATUS.md');
+    ensureDirForFile(planStatusPath);
     ensureDirForFile(paths.verify);
     ensureDirForFile(paths.state);
-    fs.writeFileSync(paths.plan, projections.plan + '\n', 'utf8');
+    fs.writeFileSync(planStatusPath, projections.plan + '\n', 'utf8');
     fs.writeFileSync(paths.verify, projections.verify + '\n', 'utf8');
     fs.writeFileSync(paths.state, projections.state + '\n', 'utf8');
     fs.writeFileSync(path.join(op.executionRoot, 'RUN-SUMMARY.md'), projections.runSummary + '\n', 'utf8');
@@ -1355,13 +1579,14 @@ function recoverRuntimeState(projectRoot, activeSession, options = {}) {
     journal,
     verificationArtifacts
   );
-  const recoverySummary = {
-    recovered_at: new Date().toISOString(),
-    journal_state: journal.scheduler_state,
-    orphan_work_items: orphanWorkItems,
-    pending_gates: readRuntimeGates(projectRoot, activeSession, { runId: current.run_id }).pending.map((gate) => gate.gate_id),
-    consistency,
-  };
+  const recoverySummary = {
+    recovered_at: new Date().toISOString(),
+    journal_state: journal.scheduler_state,
+    orphan_work_items: orphanWorkItems,
+    orphan_worktrees: detectOrphanWorktrees(projectRoot, current.run_id),
+    pending_gates: readRuntimeGates(projectRoot, activeSession, { runId: current.run_id }).pending.map((gate) => gate.gate_id),
+    consistency,
+  };
   const runDir = path.join(projectRoot, '.oxe', 'runs', current.run_id);
   ensureDir(runDir);
   const recoverySummaryPath = path.join(runDir, 'recovery-summary.json');
@@ -2243,8 +2468,9 @@ module.exports = {
   buildRecoveryConsistency,
   readRuntimeGates,
   resolveRuntimeGate,
-  createExecutionContext,
-  runRuntimeExecute,
+  createExecutionContext,
+  buildRuntimeExecutePreflight,
+  runRuntimeExecute,
   runRuntimeVerify,
   projectRuntimeArtifacts,
   runRuntimeCiChecks,