@chllming/wave-orchestration 0.6.3 → 0.7.0

package/scripts/wave-orchestrator/launcher.mjs

@@ -11,12 +11,14 @@ import {
 } from "./config.mjs";
 import {
   appendOrchestratorBoardEntry,
+  buildResidentOrchestratorPrompt,
   ensureOrchestratorBoard,
   feedbackStateSignature,
   readWaveHumanFeedbackRequests,
 } from "./coordination.mjs";
 import {
   appendCoordinationRecord,
+  buildCoordinationResponseMetrics,
   compileAgentInbox,
   compileSharedSummary,
   isOpenCoordinationStatus,
@@ -54,6 +56,8 @@ import {
   DEFAULT_AGENT_RATE_LIMIT_BASE_DELAY_SECONDS,
   DEFAULT_AGENT_RATE_LIMIT_MAX_DELAY_SECONDS,
   DEFAULT_AGENT_RATE_LIMIT_RETRIES,
+  DEFAULT_COORDINATION_ACK_TIMEOUT_MS,
+  DEFAULT_LIVE_COORDINATION_REFRESH_MS,
   DEFAULT_MAX_RETRIES_PER_WAVE,
   DEFAULT_TIMEOUT_MINUTES,
   DEFAULT_WAVE_LANE,
@@ -129,7 +133,21 @@ import {
 } from "./agent-state.mjs";
 import { buildDocsQueue, readDocsQueue, writeDocsQueue } from "./docs-queue.mjs";
 import { deriveWaveLedger, readWaveLedger, writeWaveLedger } from "./ledger.mjs";
+import {
+  augmentSummaryWithProofRegistry,
+  readWaveProofRegistry,
+  waveProofRegistryPath,
+} from "./proof-registry.mjs";
+import {
+  clearWaveRetryOverride,
+  readWaveRelaunchPlanSnapshot,
+  readWaveRetryOverride,
+  resolveRetryOverrideRuns,
+  waveRelaunchPlanPath,
+} from "./retry-control.mjs";
+import { appendWaveControlEvent } from "./control-plane.mjs";
 import { buildQualityMetrics, writeTraceBundle } from "./traces.mjs";
+import { flushWaveControlQueue } from "./wave-control-client.mjs";
 import { triageClarificationRequests } from "./clarification-triage.mjs";
 import { readProjectProfile, resolveDefaultTerminalSurface } from "./project-profile.mjs";
 import {
@@ -149,7 +167,6 @@ import {
   writeDependencySnapshotMarkdown,
 } from "./routing-state.mjs";
 import {
-  readRelaunchPlan,
   writeAssignmentSnapshot,
   writeDependencySnapshot,
   writeRelaunchPlan,
@@ -219,6 +236,9 @@ Options:
                         Disable orchestrator coordination board updates for this run
   --coordination-note <text>
                         Optional startup intent note appended to orchestrator board
+  --resident-orchestrator
+                        Launch an additional long-running resident orchestrator session for the wave
+  --no-telemetry        Disable Wave Control reporting for this launcher run
   --no-context7         Disable launcher-side Context7 prefetch/injection
   --help                 Show this help message
 `);
@@ -249,6 +269,8 @@ function parseArgs(argv) {
     cleanupSessions: true,
     keepTerminals: false,
     context7Enabled: true,
+    telemetryEnabled: true,
+    residentOrchestrator: false,
     orchestratorId: null,
     orchestratorBoardPath: null,
     coordinationNote: "",
@@ -285,6 +307,8 @@ function parseArgs(argv) {
       options.keepTerminals = true;
     } else if (arg === "--no-context7") {
       options.context7Enabled = false;
+    } else if (arg === "--no-telemetry") {
+      options.telemetryEnabled = false;
     } else if (arg === "--no-orchestrator-board") {
       options.orchestratorBoardPath = null;
       orchestratorBoardProvided = true;
@@ -305,6 +329,8 @@ function parseArgs(argv) {
       orchestratorBoardProvided = true;
     } else if (arg === "--coordination-note") {
       options.coordinationNote = String(argv[++i] || "").trim();
+    } else if (arg === "--resident-orchestrator") {
+      options.residentOrchestrator = true;
     } else if (arg === "--state-file") {
       options.runStatePath = path.resolve(REPO_ROOT, argv[++i] || "");
       stateFileProvided = true;
@@ -359,7 +385,18 @@ function parseArgs(argv) {
   if (!executorProvided) {
     options.executorMode = lanePaths.executors.default;
   }
+  if (!options.telemetryEnabled) {
+    lanePaths.waveControl = {
+      ...(lanePaths.waveControl || {}),
+      enabled: false,
+    };
+    lanePaths.laneProfile = {
+      ...(lanePaths.laneProfile || {}),
+      waveControl: lanePaths.waveControl,
+    };
+  }
   options.orchestratorId ||= sanitizeOrchestratorId(`${lanePaths.lane}-orch-${process.pid}`);
+  lanePaths.orchestratorId = options.orchestratorId;
   if (options.agentRateLimitMaxDelaySeconds < options.agentRateLimitBaseDelaySeconds) {
     throw new Error(
       "--agent-rate-limit-max-delay-seconds must be >= --agent-rate-limit-base-delay-seconds",
@@ -530,17 +567,19 @@ function materializeAgentExecutionSummaryForRun(wave, runInfo) {
 }
 
 function readRunExecutionSummary(runInfo, wave = null) {
+  const applyProofRegistry = (summary) =>
+    runInfo?.proofRegistry ? augmentSummaryWithProofRegistry(runInfo.agent, summary, runInfo.proofRegistry) : summary;
   if (runInfo?.summary && typeof runInfo.summary === "object") {
-    return runInfo.summary;
+    return applyProofRegistry(runInfo.summary);
   }
   if (runInfo?.summaryPath && fs.existsSync(runInfo.summaryPath)) {
-    return readAgentExecutionSummary(runInfo.summaryPath);
+    return applyProofRegistry(readAgentExecutionSummary(runInfo.summaryPath));
   }
   if (runInfo?.statusPath && fs.existsSync(agentSummaryPathFromStatusPath(runInfo.statusPath))) {
-    return readAgentExecutionSummary(runInfo.statusPath);
+    return applyProofRegistry(readAgentExecutionSummary(runInfo.statusPath));
   }
   if (wave && runInfo?.statusPath && runInfo?.logPath && fs.existsSync(runInfo.statusPath)) {
-    return materializeAgentExecutionSummaryForRun(wave, runInfo);
+    return applyProofRegistry(materializeAgentExecutionSummaryForRun(wave, runInfo));
   }
   return null;
 }
@@ -594,12 +633,8 @@ function waveIntegrationMarkdownPath(lanePaths, waveNumber) {
   return path.join(lanePaths.integrationDir, `wave-${waveNumber}.md`);
 }
 
-function waveRelaunchPlanPath(lanePaths, waveNumber) {
-  return path.join(lanePaths.statusDir, `relaunch-plan-wave-${waveNumber}.json`);
-}
-
 function readWaveRelaunchPlan(lanePaths, waveNumber) {
-  return readRelaunchPlan(waveRelaunchPlanPath(lanePaths, waveNumber), { wave: waveNumber });
+  return readWaveRelaunchPlanSnapshot(lanePaths, waveNumber);
 }
 
 function writeWaveRelaunchPlan(lanePaths, waveNumber, payload) {
@@ -1377,6 +1412,7 @@ function writeWaveDerivedState({
     capabilityAssignments,
     dependencySnapshot,
   });
+  const responseMetrics = buildCoordinationResponseMetrics(coordinationState);
   const messageBoardPath = path.join(lanePaths.messageboardsDir, `wave-${wave.wave}.md`);
   writeCoordinationBoardProjection(messageBoardPath, {
     wave: wave.wave,
@@ -1398,6 +1434,7 @@ function writeWaveDerivedState({
     integrationMarkdownPath: waveIntegrationMarkdownPath(lanePaths, wave.wave),
     securityMarkdownPath: waveSecurityMarkdownPath(lanePaths, wave.wave),
     ledger,
+    responseMetrics,
     sharedSummaryPath,
     sharedSummaryText: sharedSummary.text,
     inboxesByAgentId,
@@ -1415,6 +1452,23 @@ function applyDerivedStateToDashboard(dashboardState, derivedState) {
   ).length;
   dashboardState.inboundDependenciesOpen = (derivedState.dependencySnapshot?.openInbound || []).length;
   dashboardState.outboundDependenciesOpen = (derivedState.dependencySnapshot?.openOutbound || []).length;
+  dashboardState.coordinationOpen = derivedState.coordinationState?.openRecords?.length || 0;
+  dashboardState.openClarifications =
+    (derivedState.coordinationState?.clarifications || []).filter((record) =>
+      isOpenCoordinationStatus(record.status),
+    ).length;
+  dashboardState.openHumanEscalations =
+    derivedState.responseMetrics?.openHumanEscalationCount ||
+    (derivedState.coordinationState?.humanEscalations || []).filter((record) =>
+      isOpenCoordinationStatus(record.status),
+    ).length;
+  dashboardState.oldestOpenCoordinationAgeMs =
+    derivedState.responseMetrics?.oldestOpenCoordinationAgeMs ?? null;
+  dashboardState.oldestUnackedRequestAgeMs =
+    derivedState.responseMetrics?.oldestUnackedRequestAgeMs ?? null;
+  dashboardState.overdueAckCount = derivedState.responseMetrics?.overdueAckCount || 0;
+  dashboardState.overdueClarificationCount =
+    derivedState.responseMetrics?.overdueClarificationCount || 0;
 }
 
 export function readWaveImplementationGate(wave, agentRuns) {
@@ -1849,6 +1903,198 @@ function listLaneTmuxSessionNames(lanePaths) {
   );
 }
 
+function residentOrchestratorRolePromptPath() {
+  return path.join(REPO_ROOT, "docs", "agents", "wave-orchestrator-role.md");
+}
+
+function loadResidentOrchestratorRolePrompt() {
+  const filePath = residentOrchestratorRolePromptPath();
+  if (!fs.existsSync(filePath)) {
+    return "Monitor the wave, triage clarification timing, and intervene through coordination records only.";
+  }
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function defaultResidentExecutorState(options) {
+  if (options.executorMode === "claude") {
+    return {
+      id: "claude",
+      role: "orchestrator",
+      selectedBy: "resident-orchestrator",
+      budget: { minutes: options.timeoutMinutes },
+      claude: {
+        command: "claude",
+      },
+    };
+  }
+  if (options.executorMode === "opencode") {
+    return {
+      id: "opencode",
+      role: "orchestrator",
+      selectedBy: "resident-orchestrator",
+      budget: { minutes: options.timeoutMinutes },
+      opencode: {
+        command: "opencode",
+      },
+    };
+  }
+  return {
+    id: "codex",
+    role: "orchestrator",
+    selectedBy: "resident-orchestrator",
+    budget: { minutes: options.timeoutMinutes },
+    codex: {
+      command: "codex",
+      sandbox: options.codexSandboxMode,
+    },
+  };
+}
+
+function buildResidentExecutorState(executorTemplate, options) {
+  const source = executorTemplate
+    ? JSON.parse(JSON.stringify(executorTemplate))
+    : defaultResidentExecutorState(options);
+  source.role = "orchestrator";
+  source.selectedBy = "resident-orchestrator";
+  source.budget = {
+    ...(source.budget || {}),
+    minutes: Math.max(
+      Number.parseInt(String(source?.budget?.minutes || 0), 10) || 0,
+      options.timeoutMinutes,
+    ),
+  };
+  if (source.id === "codex") {
+    source.codex = {
+      ...(source.codex || {}),
+      command: source?.codex?.command || "codex",
+      sandbox: source?.codex?.sandbox || options.codexSandboxMode,
+    };
+  } else if (source.id === "claude") {
+    source.claude = {
+      ...(source.claude || {}),
+      command: source?.claude?.command || "claude",
+    };
+  } else if (source.id === "opencode") {
+    source.opencode = {
+      ...(source.opencode || {}),
+      command: source?.opencode?.command || "opencode",
+    };
+  }
+  return source;
+}
+
+function buildResidentOrchestratorRun({
+  lanePaths,
+  wave,
+  agentRuns,
+  derivedState,
+  dashboardPath,
+  runTag,
+  options,
+}) {
+  const executorTemplate =
+    agentRuns.find((run) => run.agent.executorResolved?.id === options.executorMode)?.agent
+      ?.executorResolved ||
+    agentRuns.find((run) => run.agent.executorResolved)?.agent?.executorResolved ||
+    null;
+  const executorResolved = buildResidentExecutorState(executorTemplate, options);
+  if (executorResolved.id === "local") {
+    return {
+      run: null,
+      skipReason: "Resident orchestrator requires codex, claude, or opencode; local executor is not suitable.",
+    };
+  }
+  const agent = {
+    agentId: "ORCH",
+    title: "Resident Orchestrator",
+    slug: `${wave.wave}-resident-orchestrator`,
+    prompt: loadResidentOrchestratorRolePrompt(),
+    executorResolved,
+  };
+  const baseName = `wave-${wave.wave}-resident-orchestrator`;
+  const sessionName = `${lanePaths.tmuxSessionPrefix}${wave.wave}_resident_orchestrator_${runTag}`.replace(
+    /[^a-zA-Z0-9_-]/g,
+    "_",
+  );
+  return {
+    run: {
+      agent,
+      sessionName,
+      promptPath: path.join(lanePaths.promptsDir, `${baseName}.prompt.md`),
+      logPath: path.join(lanePaths.logsDir, `${baseName}.log`),
+      statusPath: path.join(lanePaths.statusDir, `${baseName}.status`),
+      promptOverride: buildResidentOrchestratorPrompt({
+        lane: lanePaths.lane,
+        wave: wave.wave,
+        waveFile: wave.file,
+        orchestratorId: options.orchestratorId,
+        coordinationLogPath: derivedState.coordinationLogPath,
+        messageBoardPath: derivedState.messageBoardPath,
+        sharedSummaryPath: derivedState.sharedSummaryPath,
+        dashboardPath,
+        triagePath: derivedState.clarificationTriage?.triagePath || null,
+        rolePrompt: agent.prompt,
+      }),
+    },
+    skipReason: "",
+  };
+}
+
+function monitorResidentOrchestratorSession({
+  lanePaths,
+  run,
+  waveNumber,
+  recordCombinedEvent,
+  appendCoordination,
+  sessionState,
+}) {
+  if (!run || sessionState?.closed === true) {
+    return false;
+  }
+  if (fs.existsSync(run.statusPath)) {
+    sessionState.closed = true;
+    const exitCode = readStatusCodeIfPresent(run.statusPath);
+    recordCombinedEvent({
+      level: exitCode === 0 ? "info" : "warn",
+      agentId: run.agent.agentId,
+      message:
+        exitCode === 0
+          ? "Resident orchestrator exited; launcher continues as the control plane."
+          : `Resident orchestrator exited with code ${exitCode}; launcher continues as the control plane.`,
+    });
+    appendCoordination({
+      event: "resident_orchestrator_exit",
+      waves: [waveNumber],
+      status: exitCode === 0 ? "resolved" : "warn",
+      details:
+        exitCode === 0
+          ? "Resident orchestrator session ended before wave completion."
+          : `Resident orchestrator session ended with code ${exitCode} before wave completion.`,
+      actionRequested: "None",
+    });
+    return true;
+  }
+  const activeSessions = new Set(listLaneTmuxSessionNames(lanePaths));
+  if (!activeSessions.has(run.sessionName)) {
+    sessionState.closed = true;
+    recordCombinedEvent({
+      level: "warn",
+      agentId: run.agent.agentId,
+      message:
+        "Resident orchestrator session disappeared before writing a status file; launcher continues as the control plane.",
+    });
+    appendCoordination({
+      event: "resident_orchestrator_missing",
+      waves: [waveNumber],
+      status: "warn",
+      details: `tmux session ${run.sessionName} disappeared before ${path.relative(REPO_ROOT, run.statusPath)} was written.`,
+      actionRequested: "None",
+    });
+    return true;
+  }
+  return false;
+}
+
 function isWaveDashboardBackedByLiveSession(lanePaths, dashboardPath, activeSessionNames) {
   const waveMatch = path.basename(dashboardPath).match(/^wave-(\d+)\.json$/);
   if (!waveMatch) {
@@ -2107,12 +2353,14 @@ function monitorWaveHumanFeedback({
     agentIds: agentRuns.map((run) => run.agent.agentId),
     orchestratorId,
   });
+  let changed = false;
   for (const request of requests) {
     const signature = feedbackStateSignature(request);
     if (feedbackStateByRequestId.get(request.id) === signature) {
       continue;
     }
     feedbackStateByRequestId.set(request.id, signature);
+    changed = true;
     const question = request.question || "n/a";
     const context = request.context ? `; context=${request.context}` : "";
     const responseOperator = request.responseOperator || "human-operator";
@@ -2127,14 +2375,14 @@ function monitorWaveHumanFeedback({
         `[human-feedback] wave=${waveNumber} agent=${request.agentId} request=${request.id} pending: ${question}`,
       );
       console.warn(
-        `[human-feedback] respond with: pnpm exec wave-feedback respond --id ${request.id} --response "<answer>" --operator "<name>"`,
+        `[human-feedback] respond with: pnpm exec wave control task act answer --lane ${lanePaths.lane} --wave ${waveNumber} --id ${request.id} --response "<answer>" --operator "<name>"`,
       );
       appendCoordination({
         event: "human_feedback_requested",
         waves: [waveNumber],
         status: "waiting-human",
         details: `request_id=${request.id}; agent=${request.agentId}; question=${question}${context}`,
-        actionRequested: `Launcher operator should ask or answer in the parent session, then run: pnpm exec wave-feedback respond --id ${request.id} --response "<answer>" --operator "<name>"`,
+        actionRequested: `Launcher operator should ask or answer in the parent session, then run: pnpm exec wave control task act answer --lane ${lanePaths.lane} --wave ${waveNumber} --id ${request.id} --response "<answer>" --operator "<name>"`,
       });
       if (coordinationLogPath) {
         appendCoordinationRecord(coordinationLogPath, {
@@ -2225,6 +2473,7 @@ function monitorWaveHumanFeedback({
       }
     }
   }
+  return changed;
 }
 
 function proofCentricReuseBlocked(derivedState) {
@@ -2238,6 +2487,33 @@ function proofCentricReuseBlocked(derivedState) {
   );
 }
 
+function sameAgentIdSet(left = [], right = []) {
+  const leftIds = Array.from(new Set((left || []).filter(Boolean))).toSorted();
+  const rightIds = Array.from(new Set((right || []).filter(Boolean))).toSorted();
+  return leftIds.length === rightIds.length && leftIds.every((agentId, index) => agentId === rightIds[index]);
+}
+
+export function persistedRelaunchPlanMatchesCurrentState(
+  agentRuns,
+  persistedPlan,
+  lanePaths,
+  waveDefinition,
+) {
+  if (!persistedPlan || !Array.isArray(persistedPlan.selectedAgentIds)) {
+    return false;
+  }
+  const componentGate = readWaveComponentGate(waveDefinition, agentRuns, {
+    laneProfile: lanePaths?.laneProfile,
+  });
+  if (componentGate?.statusCode !== "shared-component-sibling-pending") {
+    return true;
+  }
+  return sameAgentIdSet(
+    persistedPlan.selectedAgentIds,
+    componentGate.waitingOnAgentIds || [],
+  );
+}
+
 function applyPersistedRelaunchPlan(agentRuns, persistedPlan, lanePaths, waveDefinition) {
   if (!persistedPlan || !Array.isArray(persistedPlan.selectedAgentIds)) {
     return [];
@@ -2256,6 +2532,42 @@ function applyPersistedRelaunchPlan(agentRuns, persistedPlan, lanePaths, waveDef
     .filter(Boolean);
 }
 
+export function resolveSharedComponentContinuationRuns(
+  currentRuns,
+  agentRuns,
+  failures,
+  derivedState,
+  lanePaths,
+  waveDefinition = null,
+) {
+  if (!Array.isArray(currentRuns) || currentRuns.length === 0 || !Array.isArray(failures) || failures.length === 0) {
+    return [];
+  }
+  if (!failures.every((failure) => failure.statusCode === "shared-component-sibling-pending")) {
+    return [];
+  }
+  const currentRunIds = new Set(currentRuns.map((run) => run.agent.agentId));
+  const waitingAgentIds = new Set(
+    failures.flatMap((failure) => failure.waitingOnAgentIds || []).filter(Boolean),
+  );
+  if (Array.from(currentRunIds).some((agentId) => waitingAgentIds.has(agentId))) {
+    return [];
+  }
+  const relaunchResolution = resolveRelaunchRuns(
+    agentRuns,
+    failures,
+    derivedState,
+    lanePaths,
+    waveDefinition,
+  );
+  if (relaunchResolution.barrier || relaunchResolution.runs.length === 0) {
+    return [];
+  }
+  return relaunchResolution.runs.some((run) => !currentRunIds.has(run.agent.agentId))
+    ? relaunchResolution.runs
+    : [];
+}
+
 function relaunchReasonBuckets(runs, failures, derivedState) {
   const selectedAgentIds = new Set((runs || []).map((run) => run.agent.agentId));
   return {
@@ -2361,7 +2673,10 @@ export function hasReusableSuccessStatus(agent, statusPath, options = {}) {
   if (!summary) {
     return false;
   }
-  if (!validateImplementationSummary(agent, summary).ok) {
+  const effectiveSummary = options.proofRegistry
+    ? augmentSummaryWithProofRegistry(agent, summary, options.proofRegistry)
+    : summary;
+  if (!validateImplementationSummary(agent, effectiveSummary).ok) {
     return false;
   }
   if (proofCentricReuseBlocked(options.derivedState)) {
@@ -2379,6 +2694,28 @@ function isClosureAgentId(agent, lanePaths) {
   ].includes(agent?.agentId) || isSecurityReviewAgent(agent);
 }
 
+export function selectReusablePreCompletedAgentIds(
+  agentRuns,
+  lanePaths,
+  { retryOverride = null, wave = null, derivedState = null, proofRegistry = null } = {},
+) {
+  const retryOverrideClearedAgentIds = new Set(retryOverride?.clearReusableAgentIds || []);
+  return new Set(
+    (agentRuns || [])
+      .filter(
+        (run) =>
+          !retryOverrideClearedAgentIds.has(run.agent.agentId) &&
+          !isClosureAgentId(run.agent, lanePaths) &&
+          hasReusableSuccessStatus(run.agent, run.statusPath, {
+            wave,
+            derivedState,
+            proofRegistry,
+          }),
+      )
+      .map((run) => run.agent.agentId),
+  );
+}
+
 export function selectInitialWaveRuns(agentRuns, lanePaths) {
   const implementationRuns = (agentRuns || []).filter(
     (run) => !isClosureAgentId(run?.agent, lanePaths),
@@ -3008,10 +3345,12 @@ export async function runLauncherCli(argv) {
   ensureDirectory(lanePaths.messageboardsDir);
   ensureDirectory(lanePaths.dashboardsDir);
   ensureDirectory(lanePaths.coordinationDir);
+  ensureDirectory(lanePaths.controlDir);
   ensureDirectory(lanePaths.assignmentsDir);
   ensureDirectory(lanePaths.inboxesDir);
   ensureDirectory(lanePaths.ledgerDir);
   ensureDirectory(lanePaths.integrationDir);
+  ensureDirectory(lanePaths.proofDir);
   ensureDirectory(lanePaths.securityDir);
   ensureDirectory(lanePaths.dependencySnapshotsDir);
   ensureDirectory(lanePaths.docsQueueDir);
@@ -3330,6 +3669,8 @@ export async function runLauncherCli(argv) {
       let dashboardState = null;
       let terminalEntries = [];
       let terminalsAppended = false;
+      let residentOrchestratorRun = null;
+      const residentOrchestratorState = { closed: false };
 
       const flushDashboards = () => {
         if (!dashboardState) {
@@ -3353,6 +3694,13 @@ export async function runLauncherCli(argv) {
           message: `${globalMessagePrefix}${message}`,
         });
       };
+      const flushWaveControlTelemetry = async () => {
+        try {
+          await flushWaveControlQueue(lanePaths);
+        } catch {
+          // Remote telemetry delivery is best-effort only.
+        }
+      };
 
       try {
         terminalEntries = createTemporaryTerminalEntries(
@@ -3392,6 +3740,10 @@ export async function runLauncherCli(argv) {
         });
 
         const refreshDerivedState = (attemptNumber = 0) => {
+          const proofRegistry = readWaveProofRegistry(lanePaths, wave.wave);
+          for (const run of agentRuns) {
+            run.proofRegistry = proofRegistry;
+          }
           const summariesByAgentId = Object.fromEntries(
             agentRuns
               .map((run) => [run.agent.agentId, readRunExecutionSummary(run, wave)])
@@ -3425,7 +3777,8 @@ export async function runLauncherCli(argv) {
         };
 
         refreshDerivedState(0);
-        const persistedRelaunchPlan = readWaveRelaunchPlan(lanePaths, wave.wave);
+        let persistedRelaunchPlan = readWaveRelaunchPlan(lanePaths, wave.wave);
+        let retryOverride = readWaveRetryOverride(lanePaths, wave.wave);
 
         dashboardState = buildWaveDashboardState({
           lane: lanePaths.lane,
@@ -3437,19 +3790,77 @@ export async function runLauncherCli(argv) {
           agentRuns,
         });
         applyDerivedStateToDashboard(dashboardState, derivedState);
+        const feedbackStateByRequestId = new Map();
+        const coordinationAlertState = {
+          overdueAckSignature: "",
+          overdueClarificationSignature: "",
+        };
+        let lastLiveCoordinationRefreshAt = 0;
+        const emitCoordinationAlertEvents = (currentDerivedState = derivedState) => {
+          const responseMetrics =
+            currentDerivedState?.responseMetrics ||
+            buildCoordinationResponseMetrics(currentDerivedState?.coordinationState);
+          const overdueAckSignature = (responseMetrics?.overdueAckRecordIds || []).join(",");
+          if (
+            overdueAckSignature &&
+            overdueAckSignature !== coordinationAlertState.overdueAckSignature
+          ) {
+            recordCombinedEvent({
+              level: "warn",
+              message: `Overdue acknowledgements in coordination state: ${overdueAckSignature}.`,
+            });
+            appendCoordination({
+              event: "coordination_ack_overdue",
+              waves: [wave.wave],
+              status: "warn",
+              details: `records=${overdueAckSignature}; ack_timeout_ms=${DEFAULT_COORDINATION_ACK_TIMEOUT_MS}`,
+              actionRequested:
+                "Assigned owners should acknowledge, resolve, or reroute the targeted coordination items.",
+            });
+          }
+          coordinationAlertState.overdueAckSignature = overdueAckSignature;
+          const overdueClarificationSignature = (responseMetrics?.overdueClarificationIds || []).join(
+            ",",
+          );
+          if (
+            overdueClarificationSignature &&
+            overdueClarificationSignature !== coordinationAlertState.overdueClarificationSignature
+          ) {
+            recordCombinedEvent({
+              level: "warn",
+              message: `Stale clarification chains remain open: ${overdueClarificationSignature}.`,
+            });
+            appendCoordination({
+              event: "clarification_chain_stale",
+              waves: [wave.wave],
+              status: "warn",
+              details: `clarifications=${overdueClarificationSignature}`,
+              actionRequested:
+                "The orchestrator should reroute, resolve, or escalate the stale clarification chain.",
+            });
+          }
+          coordinationAlertState.overdueClarificationSignature = overdueClarificationSignature;
+        };
+        const refreshActiveCoordinationState = (attemptNumber = 0, { force = false } = {}) => {
+          const nowMs = Date.now();
+          if (!force && nowMs - lastLiveCoordinationRefreshAt < DEFAULT_LIVE_COORDINATION_REFRESH_MS) {
+            return false;
+          }
+          refreshDerivedState(attemptNumber);
+          lastLiveCoordinationRefreshAt = nowMs;
+          updateWaveDashboardMessageBoard(dashboardState, messageBoardPath);
+          emitCoordinationAlertEvents(derivedState);
+          flushDashboards();
+          return true;
+        };
 
-        const preCompletedAgentIds = new Set(
-          agentRuns
-            .filter(
-              (run) =>
-                !isClosureAgentId(run.agent.agentId, lanePaths) &&
-                hasReusableSuccessStatus(run.agent, run.statusPath, {
-                  wave,
-                  derivedState,
-                }),
-            )
-            .map((run) => run.agent.agentId),
-        );
+        const proofRegistryForReuse = readWaveProofRegistry(lanePaths, wave.wave);
+        const preCompletedAgentIds = selectReusablePreCompletedAgentIds(agentRuns, lanePaths, {
+          retryOverride,
+          wave,
+          derivedState,
+          proofRegistry: proofRegistryForReuse,
+        });
         for (const agentId of preCompletedAgentIds) {
           setWaveDashboardAgent(dashboardState, agentId, {
             state: "completed",
@@ -3472,6 +3883,7 @@ export async function runLauncherCli(argv) {
           });
         }
         flushDashboards();
+        emitCoordinationAlertEvents(derivedState);
 
         if (options.dashboard && currentWaveDashboardTerminalEntry) {
           launchWaveDashboardSession(lanePaths, {
@@ -3481,28 +3893,162 @@ export async function runLauncherCli(argv) {
           });
         }
 
+        if (options.residentOrchestrator) {
+          const residentSetup = buildResidentOrchestratorRun({
+            lanePaths,
+            wave,
+            agentRuns,
+            derivedState,
+            dashboardPath,
+            runTag,
+            options,
+          });
+          if (residentSetup.skipReason) {
+            recordCombinedEvent({
+              level: "warn",
+              message: residentSetup.skipReason,
+            });
+          } else if (residentSetup.run) {
+            residentOrchestratorRun = residentSetup.run;
+            const launchResult = await launchAgentSession(lanePaths, {
+              wave: wave.wave,
+              waveDefinition: wave,
+              agent: residentOrchestratorRun.agent,
+              sessionName: residentOrchestratorRun.sessionName,
+              promptPath: residentOrchestratorRun.promptPath,
+              logPath: residentOrchestratorRun.logPath,
+              statusPath: residentOrchestratorRun.statusPath,
+              messageBoardPath: derivedState.messageBoardPath,
+              messageBoardSnapshot: derivedState.messageBoardText,
+              sharedSummaryPath: derivedState.sharedSummaryPath,
+              sharedSummaryText: derivedState.sharedSummaryText,
+              inboxPath: null,
+              inboxText: "",
+              promptOverride: residentOrchestratorRun.promptOverride,
+              orchestratorId: options.orchestratorId,
+              agentRateLimitRetries: options.agentRateLimitRetries,
+              agentRateLimitBaseDelaySeconds: options.agentRateLimitBaseDelaySeconds,
+              agentRateLimitMaxDelaySeconds: options.agentRateLimitMaxDelaySeconds,
+              context7Enabled: options.context7Enabled,
+            });
+            residentOrchestratorRun.lastPromptHash = launchResult?.promptHash || null;
+            residentOrchestratorRun.lastExecutorId =
+              launchResult?.executorId || residentOrchestratorRun.agent.executorResolved?.id || null;
+            recordCombinedEvent({
+              agentId: residentOrchestratorRun.agent.agentId,
+              message: `Resident orchestrator launched in tmux session ${residentOrchestratorRun.sessionName}`,
+            });
+            appendCoordination({
+              event: "resident_orchestrator_start",
+              waves: [wave.wave],
+              status: "running",
+              details: `session=${residentOrchestratorRun.sessionName}; executor=${residentOrchestratorRun.lastExecutorId || "unknown"}`,
+              actionRequested: "None",
+            });
+          }
+        }
+
         const availableRuns = agentRuns.filter((run) => !preCompletedAgentIds.has(run.agent.agentId));
+        if (
+          persistedRelaunchPlan &&
+          !persistedRelaunchPlanMatchesCurrentState(
+            agentRuns,
+            persistedRelaunchPlan,
+            lanePaths,
+            wave,
+          )
+        ) {
+          clearWaveRelaunchPlan(lanePaths, wave.wave);
+          persistedRelaunchPlan = null;
+        }
         const persistedRuns = applyPersistedRelaunchPlan(
           availableRuns,
           persistedRelaunchPlan,
           lanePaths,
           wave,
         );
+        const overrideRuns = resolveRetryOverrideRuns(availableRuns, retryOverride, lanePaths, wave);
+        if (overrideRuns.unknownAgentIds.length > 0) {
+          appendCoordination({
+            event: "retry_override_invalid",
+            waves: [wave.wave],
+            status: "warn",
+            details: `unknown_agents=${overrideRuns.unknownAgentIds.join(",")}`,
+            actionRequested:
+              "Retry override references agent ids that do not exist in the current wave definition.",
+          });
+          clearWaveRetryOverride(lanePaths, wave.wave);
+          retryOverride = null;
+        }
         let runsToLaunch =
-          persistedRuns.length > 0 ? persistedRuns : selectInitialWaveRuns(availableRuns, lanePaths);
+          overrideRuns.unknownAgentIds.length === 0 && overrideRuns.runs.length > 0
+            ? overrideRuns.runs
+            : persistedRuns.length > 0
+              ? persistedRuns
+              : selectInitialWaveRuns(availableRuns, lanePaths);
+        if (overrideRuns.runs.length > 0) {
+          appendCoordination({
+            event: "retry_override_applied",
+            waves: [wave.wave],
+            status: "running",
+            details: `agents=${overrideRuns.selectedAgentIds.join(",")}; requested_by=${retryOverride?.requestedBy || "human-operator"}`,
+            actionRequested: "None",
+          });
+          if (retryOverride?.applyOnce !== false) {
+            clearWaveRetryOverride(lanePaths, wave.wave);
+            retryOverride = null;
+          }
+        }
         let attempt = 1;
-        const feedbackStateByRequestId = new Map();
+        let traceAttempt = 1;
         let completionGateSnapshot = null;
         let completionTraceDir = null;
+        const recordAttemptState = (attemptNumber, state, data = {}) =>
+          appendWaveControlEvent(lanePaths, wave.wave, {
+            entityType: "attempt",
+            entityId: `wave-${wave.wave}-attempt-${attemptNumber}`,
+            action: state,
+            source: "launcher",
+            actor: "launcher",
+            data: {
+              attemptId: `wave-${wave.wave}-attempt-${attemptNumber}`,
+              attemptNumber,
+              state,
+              selectedAgentIds: data.selectedAgentIds || [],
+              detail: data.detail || null,
+              updatedAt: toIsoTimestamp(),
+              ...(data.createdAt ? { createdAt: data.createdAt } : {}),
+            },
+          });
+        appendWaveControlEvent(lanePaths, wave.wave, {
+          entityType: "wave_run",
+          entityId: `wave-${wave.wave}`,
+          action: "started",
+          source: "launcher",
+          actor: "launcher",
+          data: {
+            waveId: `wave-${wave.wave}`,
+            waveNumber: wave.wave,
+            agentIds: wave.agents.map((agent) => agent.agentId),
+            runVariant: lanePaths.runVariant || "live",
+          },
+        });
 
         while (attempt <= options.maxRetriesPerWave + 1) {
           refreshDerivedState(attempt - 1);
+          lastLiveCoordinationRefreshAt = Date.now();
           dashboardState.attempt = attempt;
           updateWaveDashboardMessageBoard(dashboardState, messageBoardPath);
+          emitCoordinationAlertEvents(derivedState);
           flushDashboards();
           recordCombinedEvent({
             message: `Attempt ${attempt}/${options.maxRetriesPerWave + 1}; launching agents: ${runsToLaunch.map((run) => run.agent.agentId).join(", ") || "none"}`,
           });
+          recordAttemptState(attempt, "running", {
+            selectedAgentIds: runsToLaunch.map((run) => run.agent.agentId),
+            detail: `Launching ${runsToLaunch.map((run) => run.agent.agentId).join(", ") || "no"} agents.`,
+            createdAt: toIsoTimestamp(),
+          });
 
           const launchedImplementationRuns = runsToLaunch.filter(
             (run) =>
@@ -3593,6 +4139,23 @@ export async function runLauncherCli(argv) {
                 state: "running",
                 detail: "Session launched",
               });
+              appendWaveControlEvent(lanePaths, wave.wave, {
+                entityType: "agent_run",
+                entityId: `wave-${wave.wave}-attempt-${attempt}-agent-${runInfo.agent.agentId}`,
+                action: "started",
+                source: "launcher",
+                actor: runInfo.agent.agentId,
+                attempt,
+                data: {
+                  agentId: runInfo.agent.agentId,
+                  attemptNumber: attempt,
+                  sessionName: runInfo.sessionName,
+                  executorId: runInfo.lastExecutorId,
+                  promptPath: path.relative(REPO_ROOT, runInfo.promptPath),
+                  statusPath: path.relative(REPO_ROOT, runInfo.statusPath),
+                  logPath: path.relative(REPO_ROOT, runInfo.logPath),
+                },
+              });
               recordCombinedEvent({
                 agentId: runInfo.agent.agentId,
                 message: `Launched in tmux session ${runInfo.sessionName}`,
@@ -3627,7 +4190,7 @@ export async function runLauncherCli(argv) {
                   pendingAgentIds,
                   (event) => recordCombinedEvent(event),
                 );
-                monitorWaveHumanFeedback({
+                const feedbackChanged = monitorWaveHumanFeedback({
                   lanePaths,
                   waveNumber: wave.wave,
                   agentRuns: runsToLaunch,
@@ -3637,8 +4200,21 @@ export async function runLauncherCli(argv) {
                   recordCombinedEvent,
                   appendCoordination,
                 });
-                updateWaveDashboardMessageBoard(dashboardState, messageBoardPath);
-                flushDashboards();
+                const residentChanged = monitorResidentOrchestratorSession({
+                  lanePaths,
+                  run: residentOrchestratorRun,
+                  waveNumber: wave.wave,
+                  recordCombinedEvent,
+                  appendCoordination,
+                  sessionState: residentOrchestratorState,
+                });
+                const refreshed = refreshActiveCoordinationState(attempt, {
+                  force: feedbackChanged || residentChanged,
+                });
+                if (!refreshed) {
+                  updateWaveDashboardMessageBoard(dashboardState, messageBoardPath);
+                  flushDashboards();
+                }
               },
             );
             failures = waitResult.failures;
@@ -3646,7 +4222,31 @@ export async function runLauncherCli(argv) {
           }
 
           materializeAgentExecutionSummaries(wave, agentRuns);
+          for (const runInfo of runsToLaunch) {
+            const statusRecord = readStatusRecordIfPresent(runInfo.statusPath);
+            const action = Number(statusRecord?.code) === 0 ? "completed" : "failed";
+            appendWaveControlEvent(lanePaths, wave.wave, {
+              entityType: "agent_run",
+              entityId: `wave-${wave.wave}-attempt-${attempt}-agent-${runInfo.agent.agentId}`,
+              action,
+              source: "launcher",
+              actor: runInfo.agent.agentId,
+              attempt,
+              data: {
+                agentId: runInfo.agent.agentId,
+                attemptNumber: attempt,
+                exitCode: statusRecord?.code ?? null,
+                completedAt: statusRecord?.completedAt || null,
+                promptHash: statusRecord?.promptHash || runInfo.lastPromptHash || null,
+                executorId: runInfo.lastExecutorId || null,
+                logPath: path.relative(REPO_ROOT, runInfo.logPath),
+                statusPath: path.relative(REPO_ROOT, runInfo.statusPath),
+              },
+            });
+          }
           refreshDerivedState(attempt);
+          lastLiveCoordinationRefreshAt = Date.now();
+          emitCoordinationAlertEvents(derivedState);
           failures = reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures);
           for (const failure of failures) {
             if (failure.statusCode === "shared-component-sibling-pending") {
@@ -4075,7 +4675,7 @@ export async function runLauncherCli(argv) {
             lanePaths,
             launcherOptions: options,
             wave,
-            attempt,
+            attempt: traceAttempt,
             manifest: buildManifest(lanePaths, [wave]),
             coordinationLogPath: derivedState.coordinationLogPath,
             coordinationState: derivedState.coordinationState,
@@ -4086,6 +4686,8 @@ export async function runLauncherCli(argv) {
             securitySummary: derivedState.securitySummary,
             integrationSummary: derivedState.integrationSummary,
             integrationMarkdownPath: derivedState.integrationMarkdownPath,
+            proofRegistryPath: waveProofRegistryPath(lanePaths, wave.wave),
+            controlPlanePath: path.join(lanePaths.controlPlaneDir, `wave-${wave.wave}.jsonl`),
             clarificationTriage: derivedState.clarificationTriage,
             agentRuns,
             structuredSignals,
@@ -4102,13 +4704,103 @@ export async function runLauncherCli(argv) {
               summariesByAgentId,
               agentRuns,
               gateSnapshot,
-              attempt,
+              attempt: traceAttempt,
               coordinationLogPath: derivedState.coordinationLogPath,
             }),
           });
           completionTraceDir = traceDir;
+          appendWaveControlEvent(lanePaths, wave.wave, {
+            entityType: "gate",
+            entityId: `wave-${wave.wave}-attempt-${attempt}-gate`,
+            action: "evaluated",
+            source: "launcher",
+            actor: "launcher",
+            attempt,
+            data: {
+              attemptNumber: attempt,
+              traceDir: path.relative(REPO_ROOT, traceDir),
+              gateSnapshot,
+              qualitySummary: {
+                contradictionCount: gateSnapshot?.integration?.conflictingClaims?.length || 0,
+                finalRecommendation: derivedState.integrationSummary?.recommendation || "unknown",
+              },
+            },
+          });
+          await flushWaveControlTelemetry();
+
+          const sharedComponentContinuationRuns = resolveSharedComponentContinuationRuns(
+            runsToLaunch,
+            agentRuns,
+            failures,
+            derivedState,
+            lanePaths,
+            wave,
+          );
+          if (sharedComponentContinuationRuns.length > 0) {
+            recordAttemptState(attempt, "completed", {
+              selectedAgentIds: runsToLaunch.map((run) => run.agent.agentId),
+              detail: `Attempt completed; continuing with sibling owners ${sharedComponentContinuationRuns.map((run) => run.agent.agentId).join(", ")}.`,
+            });
+            runsToLaunch = sharedComponentContinuationRuns;
+            const nextAgentIds = runsToLaunch.map((run) => run.agent.agentId);
+            const nextAgentSummary = nextAgentIds.join(", ");
+            recordCombinedEvent({
+              message: `Shared component closure now depends on sibling owners: ${nextAgentSummary}.`,
+            });
+            appendCoordination({
+              event: "wave_shared_component_continue",
+              waves: [wave.wave],
+              status: "running",
+              details: `attempt=${attempt}/${options.maxRetriesPerWave + 1}; next_agents=${nextAgentSummary}`,
+              actionRequested: `Lane ${lanePaths.lane} owners should let the remaining shared-component owners finish their proof before further retries.`,
+            });
+            for (const run of runsToLaunch) {
+              setWaveDashboardAgent(dashboardState, run.agent.agentId, {
+                state: "pending",
+                detail: "Queued for shared component closure",
+              });
+            }
+            writeWaveRelaunchPlan(lanePaths, wave.wave, {
+              wave: wave.wave,
+              attempt,
+              phase: derivedState?.ledger?.phase || null,
+              selectedAgentIds: nextAgentIds,
+              reasonBuckets: relaunchReasonBuckets(runsToLaunch, failures, derivedState),
+              executorStates: Object.fromEntries(
+                runsToLaunch.map((run) => [run.agent.agentId, run.agent.executorResolved || null]),
+              ),
+              fallbackHistory: Object.fromEntries(
+                runsToLaunch.map((run) => [
+                  run.agent.agentId,
+                  run.agent.executorResolved?.executorHistory || [],
+                ]),
+              ),
+              createdAt: toIsoTimestamp(),
+            });
+            flushDashboards();
+            traceAttempt += 1;
+            continue;
+          }
 
           if (failures.length === 0) {
+            recordAttemptState(attempt, "completed", {
+              selectedAgentIds: runsToLaunch.map((run) => run.agent.agentId),
+              detail: "Wave gates passed for this attempt.",
+            });
+            appendWaveControlEvent(lanePaths, wave.wave, {
+              entityType: "wave_run",
+              entityId: `wave-${wave.wave}`,
+              action: "completed",
+              source: "launcher",
+              actor: "launcher",
+              data: {
+                waveId: `wave-${wave.wave}`,
+                waveNumber: wave.wave,
+                attempts: attempt,
+                traceDir: completionTraceDir ? path.relative(REPO_ROOT, completionTraceDir) : null,
+                gateSnapshot: completionGateSnapshot,
+              },
+            });
             dashboardState.status = "completed";
             recordCombinedEvent({ message: `Wave ${wave.wave} completed successfully.` });
             refreshWaveDashboardAgentStates(dashboardState, agentRuns, new Set(), (event) =>
@@ -4116,10 +4808,36 @@ export async function runLauncherCli(argv) {
             );
             updateWaveDashboardMessageBoard(dashboardState, messageBoardPath);
             flushDashboards();
+            await flushWaveControlTelemetry();
             break;
           }
 
           if (attempt >= options.maxRetriesPerWave + 1) {
+            recordAttemptState(attempt, "failed", {
+              selectedAgentIds: runsToLaunch.map((run) => run.agent.agentId),
+              detail: failures
+                .map((failure) => `${failure.agentId || "wave"}:${failure.statusCode}`)
+                .join(", "),
+            });
+            appendWaveControlEvent(lanePaths, wave.wave, {
+              entityType: "wave_run",
+              entityId: `wave-${wave.wave}`,
+              action: "failed",
+              source: "launcher",
+              actor: "launcher",
+              data: {
+                waveId: `wave-${wave.wave}`,
+                waveNumber: wave.wave,
+                attempts: attempt,
+                traceDir: completionTraceDir ? path.relative(REPO_ROOT, completionTraceDir) : null,
+                gateSnapshot: completionGateSnapshot,
+                failures: failures.map((failure) => ({
+                  agentId: failure.agentId || null,
+                  statusCode: failure.statusCode,
+                  detail: failure.detail || null,
+                })),
+              },
+            });
             dashboardState.status = timedOut ? "timed_out" : "failed";
             for (const failure of failures) {
               setWaveDashboardAgent(dashboardState, failure.agentId, {
@@ -4137,6 +4855,7 @@ export async function runLauncherCli(argv) {
             const error = new Error(
               `Wave ${wave.wave} failed after ${attempt} attempt(s):\n${details}`,
             );
+            await flushWaveControlTelemetry();
             if (
               failures.every(
                 (failure) =>
@@ -4151,6 +4870,12 @@ export async function runLauncherCli(argv) {
 
           const failedAgentIds = new Set(failures.map((failure) => failure.agentId));
           const failedList = Array.from(failedAgentIds).join(", ");
+          recordAttemptState(attempt, "failed", {
+            selectedAgentIds: runsToLaunch.map((run) => run.agent.agentId),
+            detail: failures
+              .map((failure) => `${failure.agentId || "wave"}:${failure.statusCode}`)
+              .join(", "),
+          });
           console.warn(
             `[retry] Wave ${wave.wave} had failures for agents: ${failedList}. Evaluating safe relaunch targets.`,
           );
@@ -4168,7 +4893,38 @@ export async function runLauncherCli(argv) {
             lanePaths,
             wave,
           );
-          if (relaunchResolution.barrier) {
+          retryOverride = readWaveRetryOverride(lanePaths, wave.wave);
+          const overrideResolution = resolveRetryOverrideRuns(
+            agentRuns,
+            retryOverride,
+            lanePaths,
+            wave,
+          );
+          if (overrideResolution.unknownAgentIds.length > 0) {
+            appendCoordination({
+              event: "retry_override_invalid",
+              waves: [wave.wave],
+              status: "warn",
+              details: `unknown_agents=${overrideResolution.unknownAgentIds.join(",")}`,
+              actionRequested:
+                "Retry override references agent ids that do not exist in the current wave definition.",
+            });
+            clearWaveRetryOverride(lanePaths, wave.wave);
+            retryOverride = null;
+          } else if (overrideResolution.runs.length > 0) {
+            runsToLaunch = overrideResolution.runs;
+            appendCoordination({
+              event: "retry_override_applied",
+              waves: [wave.wave],
+              status: "running",
+              details: `agents=${overrideResolution.selectedAgentIds.join(",")}; requested_by=${retryOverride?.requestedBy || "human-operator"}`,
+              actionRequested: "None",
+            });
+            if (retryOverride?.applyOnce !== false) {
+              clearWaveRetryOverride(lanePaths, wave.wave);
+              retryOverride = null;
+            }
+          } else if (relaunchResolution.barrier) {
             clearWaveRelaunchPlan(lanePaths, wave.wave);
             for (const failure of relaunchResolution.barrier.failures) {
               recordCombinedEvent({
@@ -4194,8 +4950,9 @@ export async function runLauncherCli(argv) {
             );
             error.exitCode = 43;
             throw error;
+          } else {
+            runsToLaunch = relaunchResolution.runs;
           }
-          runsToLaunch = relaunchResolution.runs;
           if (runsToLaunch.length === 0) {
             clearWaveRelaunchPlan(lanePaths, wave.wave);
             const error = new Error(
@@ -4229,6 +4986,7 @@ export async function runLauncherCli(argv) {
           });
           flushDashboards();
           attempt += 1;
+          traceAttempt += 1;
         }
 
         clearWaveRelaunchPlan(lanePaths, wave.wave);
@@ -4256,6 +5014,9 @@ export async function runLauncherCli(argv) {
           details: `attempts_used=${dashboardState?.attempt ?? "n/a"}; completed_waves=${runState.completedWaves.join(", ") || "none"}`,
         });
       } finally {
+        if (residentOrchestratorRun) {
+          killTmuxSessionIfExists(lanePaths.tmuxSocketName, residentOrchestratorRun.sessionName);
+        }
         if (terminalsAppended && !options.keepTerminals) {
           removeTerminalEntries(lanePaths.terminalsPath, terminalEntries);
         }