@chllming/wave-orchestration 0.7.0 → 0.7.1

package/releases/manifest.json

@@ -2,6 +2,24 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.7.1",
+      "date": "2026-03-23",
+      "summary": "Run-control hardening, completed-with-drift reconcile preservation, live Codex ceiling visibility, and 0.7.1 release-surface alignment.",
+      "features": [
+        "Fresh live launches now clear stale auto-generated relaunch plans by default, so explicit wave starts recompute the implementation fan-out unless `--resume-control-state` is passed.",
+        "`wave control status` now treats the active attempt as the authoritative live fan-out instead of replaying stale rerun intent or unrelated closure blockers.",
+        "Historical `reconcile-status` now preserves previously authoritative completed waves as `completed_with_drift` when the only mismatch is prompt-hash drift.",
+        "Live executor overlays now always write `launch-preview.json`, and Codex summaries record an observed turn ceiling when the runtime reports one.",
+        "Shipped package docs, migration guidance, sample-wave references, and npm publishing instructions now point at the `0.7.1` release surface."
+      ],
+      "manualSteps": [
+        "If you intentionally want to reuse a prior auto-generated relaunch selection on a fresh live start, pass `--resume-control-state` explicitly.",
+        "Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach global` to reattach to live tmux-backed dashboards without resolving sockets or session names by hand.",
+        "If an adopted `0.6.x` repo fails `wave doctor` after the `0.7.x` upgrade, sync the repo-owned planner starter surface (`docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry) before relying on planner-aware validation."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.7.0",
       "date": "2026-03-23",
@@ -12,11 +30,15 @@
         "Wave Control telemetry: local-first event queueing with best-effort batch delivery, configurable report modes, selective artifact upload, and per-category capture toggles.",
         "Live-wave orchestration refresh that keeps coordination surfaces, clarification triage, and dashboard metrics current during active execution.",
         "Resident orchestrator support via `--resident-orchestrator` for long-running non-owning monitoring sessions.",
-        "Native and external benchmark telemetry with failure-review validity classification and config attestation hashing."
+        "Native and external benchmark telemetry with failure-review validity classification and config attestation hashing.",
+        "Stable dashboard reattach via `wave dashboard --attach current|global`, plus live `launch-preview.json` artifacts that preserve observed Codex turn ceilings without pretending Wave set them.",
+        "Historical `reconcile-status` now preserves previously authoritative completed waves as completed-with-drift when the only mismatch is prompt-hash drift.",
+        "Fresh live launches now clear stale auto-generated relaunch plans by default, while `wave control status` treats the active attempt as the authoritative fan-out instead of replaying stale relaunch state."
       ],
       "manualSteps": [
         "Existing `wave coord`, `wave retry`, and `wave proof` commands remain available as compatibility surfaces. No migration required, but new operator docs prefer `wave control`.",
-        "To enable Wave Control telemetry, add a `waveControl` section to `wave.config.json` with at minimum an `endpoint` and `workspaceId`. Pass `--no-telemetry` to disable for a single run."
+        "To enable Wave Control telemetry, add a `waveControl` section to `wave.config.json` with at minimum an `endpoint` and `workspaceId`. Pass `--no-telemetry` to disable for a single run.",
+        "If an adopted `0.6.x` repo fails `wave doctor` after the `0.7.x` upgrade, sync the repo-owned planner starter surface (`docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry) before relying on planner-aware validation."
       ],
       "breaking": false
     },

package/scripts/wave-orchestrator/agent-state.mjs

@@ -185,23 +185,27 @@ function findLatestComponentMatches(text) {
 
 function detectTermination(agent, logText, statusRecord) {
   const patterns = [
-    { reason: "max-turns", regex: /(Reached max turns \(\d+\))/i },
+    { reason: "max-turns", regex: /Reached max turns \((\d+)\)/i },
     { reason: "timeout", regex: /(timed out(?: after [^\n.]+)?)/i },
     { reason: "session-missing", regex: /(session [^\n]+ disappeared before [^\n]+ was written)/i },
   ];
   for (const pattern of patterns) {
     const match = String(logText || "").match(pattern.regex);
     if (match) {
-      const baseHint = cleanText(match[1] || match[0]);
+      const baseHint = cleanText(match[0]);
+      const observedTurnLimit =
+        pattern.reason === "max-turns" && Number.isFinite(Number(match[1])) ? Number(match[1]) : null;
       if (pattern.reason === "max-turns" && agent?.executorResolved?.id === "codex") {
         return {
           reason: pattern.reason,
           hint: `${baseHint}. Wave does not set a Codex turn-limit flag; inspect launch-preview.json limits for any profile or upstream-runtime ceiling notes.`,
+          observedTurnLimit,
         };
       }
       return {
         reason: pattern.reason,
         hint: baseHint,
+        observedTurnLimit,
       };
     }
   }
@@ -212,6 +216,7 @@ function detectTermination(agent, logText, statusRecord) {
     return {
       reason: "status-detail",
       hint: statusHint,
+      observedTurnLimit: null,
     };
   }
   const exitCode = Number.isFinite(Number(statusRecord?.code)) ? Number(statusRecord.code) : null;
@@ -219,11 +224,13 @@ function detectTermination(agent, logText, statusRecord) {
     return {
       reason: "exit-code",
       hint: `Exit code ${exitCode}.`,
+      observedTurnLimit: null,
     };
   }
   return {
     reason: null,
     hint: "",
+    observedTurnLimit: null,
   };
 }
 
@@ -437,6 +444,8 @@ export function buildAgentExecutionSummary({ agent, statusRecord, logPath, repor
       : null,
     terminationReason: termination.reason,
     terminationHint: termination.hint,
+    terminationObservedTurnLimit:
+      Number.isFinite(Number(termination.observedTurnLimit)) ? Number(termination.observedTurnLimit) : null,
     logPath: path.relative(REPO_ROOT, logPath),
     reportPath: reportPath ? path.relative(REPO_ROOT, reportPath) : null,
   };

package/scripts/wave-orchestrator/control-cli.mjs

@@ -270,8 +270,46 @@ function assignmentRelevantToAgent(assignment, agentId = "") {
   );
 }
 
-function buildLogicalAgents({ lanePaths, wave, tasks, dependencySnapshot, capabilityAssignments, rerunRequest, proofRegistry }) {
-  const rerunSelected = new Set(rerunRequest?.selectedAgentIds || resolveRetryOverrideAgentIds(wave, lanePaths, rerunRequest));
+function buildEffectiveSelection(lanePaths, wave, { activeAttempt = null, rerunRequest = null, relaunchPlan = null } = {}) {
+  const activeAttemptSelected = Array.isArray(activeAttempt?.selectedAgentIds)
+    ? Array.from(new Set(activeAttempt.selectedAgentIds.filter(Boolean)))
+    : [];
+  if (activeAttemptSelected.length > 0) {
+    return {
+      source: "active-attempt",
+      selectedAgentIds: activeAttemptSelected,
+      detail: activeAttempt?.detail || null,
+    };
+  }
+  const rerunSelected = rerunRequest?.selectedAgentIds?.length
+    ? rerunRequest.selectedAgentIds
+    : resolveRetryOverrideAgentIds(wave, lanePaths, rerunRequest);
+  if (rerunSelected.length > 0) {
+    return {
+      source: "rerun-request",
+      selectedAgentIds: rerunSelected,
+      detail: rerunRequest?.reason || null,
+    };
+  }
+  const relaunchSelected = Array.isArray(relaunchPlan?.selectedAgentIds)
+    ? Array.from(new Set(relaunchPlan.selectedAgentIds.filter(Boolean)))
+    : [];
+  if (relaunchSelected.length > 0) {
+    return {
+      source: "relaunch-plan",
+      selectedAgentIds: relaunchSelected,
+      detail: null,
+    };
+  }
+  return {
+    source: "none",
+    selectedAgentIds: [],
+    detail: null,
+  };
+}
+
+function buildLogicalAgents({ lanePaths, wave, tasks, dependencySnapshot, capabilityAssignments, selection, proofRegistry }) {
+  const selectedAgentIds = new Set(selection?.selectedAgentIds || []);
   const helperAssignments = Array.isArray(capabilityAssignments) ? capabilityAssignments : [];
   const openInbound = dependencySnapshot?.openInbound || [];
   return wave.agents.map((agent) => {
@@ -301,9 +339,15 @@ function buildLogicalAgents({ lanePaths, wave, tasks, dependencySnapshot, capabi
     const dependency = openInbound.find((record) => record.assignedAgentId === agent.agentId);
     let state = "planned";
     let reason = "";
-    if (rerunSelected.has(agent.agentId)) {
+    if (selection?.source === "active-attempt" && selectedAgentIds.has(agent.agentId)) {
+      state = "working";
+      reason = selection?.detail || "Selected by the active launcher attempt.";
+    } else if (selectedAgentIds.has(agent.agentId)) {
       state = "needs-rerun";
-      reason = "Selected by active rerun request.";
+      reason =
+        selection?.source === "relaunch-plan"
+          ? "Selected by the persisted relaunch plan."
+          : "Selected by active rerun request.";
     } else if (targetedBlockingTasks.some((task) => task.state === "working")) {
       state = "working";
       reason = targetedBlockingTasks.find((task) => task.state === "working")?.title || "";
@@ -334,7 +378,8 @@ function buildLogicalAgents({ lanePaths, wave, tasks, dependencySnapshot, capabi
       state,
       reason: reason || null,
       taskIds: targetedTasks.map((task) => task.taskId),
-      selectedForRerun: rerunSelected.has(agent.agentId),
+      selectedForRerun: selectedAgentIds.has(agent.agentId) && selection?.source !== "active-attempt",
+      selectedForActiveAttempt: selection?.source === "active-attempt" && selectedAgentIds.has(agent.agentId),
       activeProofBundleIds: (proofRegistry?.entries || [])
         .filter(
           (entry) =>
@@ -346,10 +391,25 @@ function buildLogicalAgents({ lanePaths, wave, tasks, dependencySnapshot, capabi
   });
 }
 
-function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, rerunRequest, agentId = "" }) {
-  const scopedTasks = agentId
+function selectionTargetsAgent(agentId, selectionSet) {
+  return Boolean(agentId) && selectionSet.has(agentId);
+}
+
+function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, activeAttempt, rerunRequest, relaunchPlan, agentId = "" }) {
+  const attemptSelection = new Set(activeAttempt?.selectedAgentIds || []);
+  const scopeToActiveAttempt = !agentId && attemptSelection.size > 0;
+  const scopedTasks = (agentId
     ? tasks.filter((task) => task.ownerAgentId === agentId || task.assigneeAgentId === agentId)
-    : tasks;
+    : tasks
+  ).filter((task) => {
+    if (!scopeToActiveAttempt) {
+      return true;
+    }
+    return (
+      selectionTargetsAgent(task.ownerAgentId, attemptSelection) ||
+      selectionTargetsAgent(task.assigneeAgentId, attemptSelection)
+    );
+  });
   const pendingHuman = scopedTasks.find((task) => task.state === "input-required");
   if (pendingHuman) {
     return {
@@ -381,11 +441,19 @@ function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, r
       detail: clarification.title,
     };
   }
-  const unresolvedAssignment = (capabilityAssignments || []).find(
+  const scopedAssignments = (capabilityAssignments || []).filter((assignment) => {
+    if (!scopeToActiveAttempt) {
+      return assignmentRelevantToAgent(assignment, agentId);
+    }
+    return (
+      selectionTargetsAgent(assignment.assignedAgentId, attemptSelection) ||
+      selectionTargetsAgent(assignment.sourceAgentId, attemptSelection)
+    );
+  });
+  const unresolvedAssignment = scopedAssignments.find(
     (assignment) =>
       assignment.blocking &&
-      !assignment.assignedAgentId &&
-      assignmentRelevantToAgent(assignment, agentId),
+      !assignment.assignedAgentId,
   );
   if (unresolvedAssignment) {
     return {
@@ -395,10 +463,7 @@ function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, r
       detail: unresolvedAssignment.assignmentDetail || unresolvedAssignment.summary || unresolvedAssignment.requestId,
     };
   }
-  const blockingAssignment = (capabilityAssignments || []).find(
-    (assignment) =>
-      assignment.blocking && assignmentRelevantToAgent(assignment, agentId),
-  );
+  const blockingAssignment = scopedAssignments.find((assignment) => assignment.blocking);
   if (blockingAssignment) {
     return {
       kind: "helper-assignment",
@@ -410,7 +475,18 @@ function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, r
   const dependency = [
     ...(dependencySnapshot?.openInbound || []),
     ...(dependencySnapshot?.openOutbound || []),
-  ].find((record) => !agentId || record.assignedAgentId === agentId || record.agentId === agentId);
+  ].find((record) => {
+    if (agentId) {
+      return record.assignedAgentId === agentId || record.agentId === agentId;
+    }
+    if (!scopeToActiveAttempt) {
+      return true;
+    }
+    return (
+      selectionTargetsAgent(record.assignedAgentId, attemptSelection) ||
+      selectionTargetsAgent(record.agentId, attemptSelection)
+    );
+  });
   if (dependency) {
     return {
       kind: "dependency",
@@ -419,7 +495,7 @@ function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, r
       detail: dependency.summary || dependency.detail || dependency.id,
     };
   }
-  if (rerunRequest) {
+  if (!scopeToActiveAttempt && rerunRequest) {
     return {
       kind: "rerun-request",
       id: rerunRequest.requestId || "active-rerun",
@@ -427,6 +503,14 @@ function buildBlockingEdge({ tasks, capabilityAssignments, dependencySnapshot, r
       detail: rerunRequest.reason || "Active rerun request controls next attempt selection.",
     };
   }
+  if (!scopeToActiveAttempt && relaunchPlan) {
+    return {
+      kind: "relaunch-plan",
+      id: `wave-${relaunchPlan.wave ?? "unknown"}-relaunch-plan`,
+      agentId: null,
+      detail: "Persisted relaunch plan controls the next safe launcher selection.",
+    };
+  }
   const blocker = scopedTasks.find(
     (task) => task.taskType === "blocker" && ["open", "working"].includes(task.state),
   );
@@ -485,6 +569,7 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
   }).filter((task) => !agentId || task.ownerAgentId === agentId || task.assigneeAgentId === agentId);
   const controlState = readWaveControlPlaneState(lanePaths, wave.wave);
   const proofRegistry = readWaveProofRegistry(lanePaths, wave.wave) || { entries: [] };
+  const relaunchPlan = readWaveRelaunchPlanSnapshot(lanePaths, wave.wave);
   const rerunRequest = controlState.activeRerunRequest
     ? {
         ...controlState.activeRerunRequest,
@@ -497,6 +582,11 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
               }),
       }
     : null;
+  const selection = buildEffectiveSelection(lanePaths, wave, {
+    activeAttempt: controlState.activeAttempt,
+    rerunRequest,
+    relaunchPlan,
+  });
   return {
     lane: lanePaths.lane,
     wave: wave.wave,
@@ -506,7 +596,9 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
       tasks,
       capabilityAssignments,
       dependencySnapshot,
+      activeAttempt: controlState.activeAttempt,
       rerunRequest,
+      relaunchPlan,
       agentId,
     }),
     logicalAgents: buildLogicalAgents({
@@ -515,7 +607,7 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
       tasks,
       dependencySnapshot,
       capabilityAssignments,
-      rerunRequest,
+      selection,
       proofRegistry,
     }).filter((agent) => !agentId || agent.agentId === agentId),
     tasks,
@@ -533,8 +625,9 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
     proofBundles: (proofRegistry?.entries || []).filter(
       (entry) => !agentId || entry.agentId === agentId,
     ),
+    selectionSource: selection.source,
     rerunRequest,
-    relaunchPlan: readWaveRelaunchPlanSnapshot(lanePaths, wave.wave),
+    relaunchPlan,
     nextTimer: nextTaskDeadline(tasks),
     activeAttempt: controlState.activeAttempt,
   };

package/scripts/wave-orchestrator/dashboard-renderer.mjs

@@ -1,8 +1,11 @@
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { loadWaveConfig } from "./config.mjs";
 import { analyzeMessageBoardCommunication } from "./coordination.mjs";
 import { commsAgeSummary, deploymentSummary } from "./dashboard-state.mjs";
 import {
+  buildLanePaths,
   DEFAULT_REFRESH_MS,
   DEFAULT_WAVE_LANE,
   FINAL_EXIT_DELAY_MS,
@@ -14,12 +17,29 @@ import {
   sleep,
   truncate,
 } from "./shared.mjs";
+import {
+  createCurrentWaveDashboardTerminalEntry,
+  createGlobalDashboardTerminalEntry,
+} from "./terminals.mjs";
+
+const DASHBOARD_ATTACH_TARGETS = ["current", "global"];
+
+function normalizeDashboardAttachTarget(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!DASHBOARD_ATTACH_TARGETS.includes(normalized)) {
+    throw new Error(`--attach must be one of: ${DASHBOARD_ATTACH_TARGETS.join(", ")}`);
+  }
+  return normalized;
+}
 
 export function parseDashboardArgs(argv) {
   const options = {
     lane: DEFAULT_WAVE_LANE,
     dashboardFile: null,
     messageBoard: null,
+    attach: null,
     watch: false,
     refreshMs: DEFAULT_REFRESH_MS,
   };
@@ -39,6 +59,8 @@ export function parseDashboardArgs(argv) {
       options.dashboardFile = path.resolve(REPO_ROOT, argv[++i] || "");
     } else if (arg === "--message-board") {
       options.messageBoard = path.resolve(REPO_ROOT, argv[++i] || "");
+    } else if (arg === "--attach") {
+      options.attach = normalizeDashboardAttachTarget(argv[++i] || "");
     } else if (arg === "--refresh-ms") {
       options.refreshMs = Number.parseInt(String(argv[++i] || ""), 10);
     } else if (arg === "--help" || arg === "-h") {
@@ -47,12 +69,63 @@ export function parseDashboardArgs(argv) {
       throw new Error(`Unknown argument: ${arg}`);
     }
   }
-  if (!options.dashboardFile) {
-    throw new Error("--dashboard-file is required");
+  if (!options.dashboardFile && !options.attach) {
+    throw new Error("--dashboard-file is required unless --attach is used");
   }
   return { help: false, options };
 }
 
+function tmuxSessionExists(socketName, sessionName) {
+  const result = spawnSync("tmux", ["-L", socketName, "has-session", "-t", sessionName], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    env: { ...process.env, TMUX: "" },
+  });
+  if (result.error) {
+    throw new Error(`tmux session lookup failed: ${result.error.message}`);
+  }
+  if (result.status === 0) {
+    return true;
+  }
+  const combined = `${String(result.stderr || "").toLowerCase()}\n${String(result.stdout || "").toLowerCase()}`;
+  if (
+    combined.includes("can't find session") ||
+    combined.includes("no server running") ||
+    combined.includes("error connecting")
+  ) {
+    return false;
+  }
+  throw new Error((result.stderr || result.stdout || "tmux has-session failed").trim());
+}
+
+function attachDashboardSession(lane, target) {
+  const config = loadWaveConfig();
+  const lanePaths = buildLanePaths(lane, { config });
+  const entry =
+    target === "global"
+      ? createGlobalDashboardTerminalEntry(lanePaths, "current")
+      : createCurrentWaveDashboardTerminalEntry(lanePaths);
+  if (!tmuxSessionExists(lanePaths.tmuxSocketName, entry.sessionName)) {
+    const dashboardsRel = path.relative(REPO_ROOT, path.dirname(lanePaths.globalDashboardPath));
+    throw new Error(
+      `No ${target} dashboard session is live for lane ${lanePaths.lane}. Launch a dashboarded run on that lane, then inspect ${dashboardsRel} if you need the last written dashboard state.`,
+    );
+  }
+  const result = spawnSync("tmux", ["-L", lanePaths.tmuxSocketName, "attach", "-t", entry.sessionName], {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    env: { ...process.env, TMUX: "" },
+  });
+  if (result.error) {
+    throw new Error(`tmux attach failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `tmux attach exited ${result.status} for lane ${lanePaths.lane} ${target} dashboard session ${entry.sessionName}.`,
+    );
+  }
+}
+
 function readMessageBoardTail(messageBoardPath, maxLines = 24) {
   if (!messageBoardPath) {
     return ["(message board path unavailable)"];
@@ -379,12 +452,19 @@ Options:
   --lane <name>            Wave lane name (default: ${DEFAULT_WAVE_LANE})
   --dashboard-file <path>  Path to wave/global dashboard JSON
   --message-board <path>   Optional message board path override
+  --attach <current|global>
+                          Attach to the stable tmux-backed dashboard session for the lane
   --watch                  Refresh continuously
   --refresh-ms <n>         Refresh interval in ms (default: ${DEFAULT_REFRESH_MS})
 `);
     return;
   }
 
+  if (options.attach) {
+    attachDashboardSession(options.lane, options.attach);
+    return;
+  }
+
   let terminalStateReachedAt = null;
   while (true) {
     const raw = fs.existsSync(options.dashboardFile)

package/scripts/wave-orchestrator/install.mjs

@@ -92,6 +92,33 @@ const REQUIRED_GITIGNORE_ENTRIES = [
   "docs/research/papers/",
   "docs/research/articles/",
 ];
+const PLANNER_MIGRATION_REQUIRED_SURFACES = [
+  {
+    id: "planner-role",
+    label: "docs/agents/wave-planner-role.md",
+    path: "docs/agents/wave-planner-role.md",
+    kind: "file",
+  },
+  {
+    id: "planner-skill",
+    label: "skills/role-planner/",
+    path: "skills/role-planner",
+    kind: "dir",
+  },
+  {
+    id: "planner-context7",
+    label: "docs/context7/planner-agent/",
+    path: "docs/context7/planner-agent",
+    kind: "dir",
+  },
+  {
+    id: "planner-lessons",
+    label: "docs/reference/wave-planning-lessons.md",
+    path: "docs/reference/wave-planning-lessons.md",
+    kind: "file",
+  },
+];
+const PLANNER_REQUIRED_BUNDLE_ID = "planner-agentic";
 
 function collectDeclaredDeployKinds(waves = []) {
   return Array.from(
@@ -222,6 +249,8 @@ function slugifyVersion(value) {
 }
 
 function formatUpgradeReport(report) {
+  const plannerMigrationErrors = report.doctor.errors.filter((issue) => isPlannerMigrationIssue(issue));
+  const otherDoctorErrors = report.doctor.errors.filter((issue) => !isPlannerMigrationIssue(issue));
   return [
     `# Wave Upgrade Report`,
     "",
@@ -238,12 +267,27 @@ function formatUpgradeReport(report) {
     "",
     "- No repo-owned plans, waves, role prompts, or config files were overwritten.",
     "- New runtime behavior comes from the installed package version.",
+    ...(report.initMode === "adopt-existing" && plannerMigrationErrors.length > 0
+      ? [
+          "",
+          "## Adopted Repo Follow-Up",
+          "",
+          "- This workspace was adopted from an existing repo-owned Wave surface.",
+          "- `wave upgrade` does not copy new planner starter docs, skills, or Context7 bundle entries into adopted repos.",
+          ...plannerMigrationErrors.map((issue) => `- Error: ${issue}`),
+        ]
+      : []),
+    ...(report.initMode === "adopt-existing" && plannerMigrationErrors.length > 0
+      ? [
+          "- After syncing that planner surface, rerun `pnpm exec wave doctor` before relying on `wave draft --agentic` or planner-aware validation.",
+        ]
+      : []),
     ...(report.doctor.errors.length > 0 || report.doctor.warnings.length > 0
       ? [
           "",
           "## Follow-Up",
           "",
-          ...report.doctor.errors.map((issue) => `- Error: ${issue}`),
+          ...otherDoctorErrors.map((issue) => `- Error: ${issue}`),
           ...report.doctor.warnings.map((issue) => `- Warning: ${issue}`),
         ]
       : []),
@@ -275,6 +319,48 @@ function plannerRequiredPaths() {
   ).sort();
 }
 
+function isPlannerMigrationIssue(issue) {
+  return String(issue || "").startsWith("Planner starter surface is incomplete");
+}
+
+function missingPlannerMigrationSurfaceLabels() {
+  const missing = [];
+  for (const surface of PLANNER_MIGRATION_REQUIRED_SURFACES) {
+    const targetPath = path.join(REPO_ROOT, surface.path);
+    if (!fs.existsSync(targetPath)) {
+      missing.push(surface.label);
+      continue;
+    }
+    if (surface.kind === "dir") {
+      try {
+        if (fs.readdirSync(targetPath).length === 0) {
+          missing.push(surface.label);
+        }
+      } catch {
+        missing.push(surface.label);
+      }
+    }
+  }
+  return missing;
+}
+
+function plannerMigrationIssue(config, context7BundleIndex) {
+  const missing = missingPlannerMigrationSurfaceLabels();
+  const bundleId = String(config?.planner?.agentic?.context7Bundle || "").trim();
+  const bundleEntryMissing =
+    bundleId === "" || bundleId === PLANNER_REQUIRED_BUNDLE_ID
+      ? !context7BundleIndex?.bundles?.[PLANNER_REQUIRED_BUNDLE_ID]
+      : false;
+  if (missing.length === 0 && !bundleEntryMissing) {
+    return null;
+  }
+  const remediationItems = missing.slice();
+  if (bundleEntryMissing) {
+    remediationItems.push(`docs/context7/bundles.json#${PLANNER_REQUIRED_BUNDLE_ID}`);
+  }
+  return `Planner starter surface is incomplete for 0.7.x workspaces. Sync ${remediationItems.join(", ")} from the packaged release, then rerun \`pnpm exec wave doctor\`.`;
+}
+
 export function runDoctor() {
   const errors = [];
   const warnings = [];
@@ -320,14 +406,22 @@ export function runDoctor() {
         }
       }
       const context7BundleIndex = loadContext7BundleIndex(lanePaths.context7BundleIndexPath);
+      const plannerMigration = plannerMigrationIssue(config, context7BundleIndex);
+      if (plannerMigration) {
+        errors.push(plannerMigration);
+      }
       const plannerPaths = plannerRequiredPaths();
       for (const relPath of plannerPaths) {
-        if (!fs.existsSync(path.join(REPO_ROOT, relPath))) {
+        if (!fs.existsSync(path.join(REPO_ROOT, relPath)) && !plannerMigration) {
           errors.push(`Missing planner file: ${relPath}`);
         }
       }
       const plannerBundleId = String(config.planner?.agentic?.context7Bundle || "").trim();
-      if (plannerBundleId && !context7BundleIndex.bundles[plannerBundleId]) {
+      if (
+        plannerBundleId &&
+        !context7BundleIndex.bundles[plannerBundleId] &&
+        !(plannerMigration && plannerBundleId === PLANNER_REQUIRED_BUNDLE_ID)
+      ) {
         errors.push(
           `planner.agentic.context7Bundle references unknown bundle "${plannerBundleId}".`,
         );
@@ -484,6 +578,7 @@ export function upgradeWorkspace() {
     previousVersion,
     currentVersion: metadata.version,
     generatedAt,
+    initMode: existingState.initMode || null,
     releases,
     doctor,
   };

package/scripts/wave-orchestrator/launcher-runtime.mjs

@@ -135,16 +135,16 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
     skillProjection: agent.skillsResolved,
   });
   const resolvedExecutorMode = launchSpec.executorId || agent.executorResolved?.id || "codex";
+  writeJsonAtomic(path.join(overlayDir, "launch-preview.json"), {
+    executorId: resolvedExecutorMode,
+    command: launchSpec.command,
+    env: launchSpec.env || {},
+    useRateLimitRetries: launchSpec.useRateLimitRetries === true,
+    invocationLines: launchSpec.invocationLines,
+    limits: launchSpec.limits || null,
+    skills: summarizeResolvedSkills(agent.skillsResolved),
+  });
   if (dryRun) {
-    writeJsonAtomic(path.join(overlayDir, "launch-preview.json"), {
-      executorId: resolvedExecutorMode,
-      command: launchSpec.command,
-      env: launchSpec.env || {},
-      useRateLimitRetries: launchSpec.useRateLimitRetries === true,
-      invocationLines: launchSpec.invocationLines,
-      limits: launchSpec.limits || null,
-      skills: summarizeResolvedSkills(agent.skillsResolved),
-    });
     return {
       promptHash,
       context7,