@chllming/wave-orchestration 0.8.3 → 0.8.5

package/scripts/wave-orchestrator/ledger.mjs

@@ -6,6 +6,7 @@ import {
 } from "./config.mjs";
 import {
   validateContEvalSummary,
+  validateDesignSummary,
   validateDocumentationClosureSummary,
   validateContQaSummary,
   validateImplementationSummary,
@@ -13,6 +14,8 @@ import {
 } from "./agent-state.mjs";
 import {
   isContEvalImplementationOwningAgent,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
 } from "./role-helpers.mjs";
 import { openClarificationLinkedRequests } from "./coordination-store.mjs";
@@ -54,6 +57,7 @@ export function buildSeedWaveLedger({
 }) {
   const tasks = [];
   for (const agent of wave.agents) {
+    const hybridDesignAgent = isImplementationOwningDesignAgent(agent);
     const kind =
       agent.agentId === contQaAgentId
         ? "cont-qa"
@@ -63,35 +67,46 @@ export function buildSeedWaveLedger({
           ? "integration"
         : agent.agentId === documentationAgentId
             ? "documentation"
+            : isDesignAgent(agent)
+              ? "design"
             : isSecurityReviewAgent(agent)
               ? "security"
-            : "implementation";
-    tasks.push({
-      id: taskId(kind, agent.agentId),
-      title: `${agent.agentId}: ${agent.title}`,
-      owner: agent.agentId,
-      kind,
-      dependsOn: [],
-      state: "planned",
-      proofState: "pending",
-      docState: "pending",
-      infraState: "n/a",
-      priority:
-        kind === "implementation" ? "normal" : kind === "integration" ? "high" : "high",
-      artifactRefs: agent.ownedPaths || [],
-      runtime: agent.executorResolved
-        ? {
-            executorId: agent.executorResolved.id,
-            role: agent.executorResolved.role,
-            profile: agent.executorResolved.profile,
-            selectedBy: agent.executorResolved.selectedBy,
-            retryPolicy: agent.executorResolved.retryPolicy || null,
-            allowFallbackOnRetry: agent.executorResolved.allowFallbackOnRetry !== false,
-            fallbacks: agent.executorResolved.fallbacks || [],
-            fallbackUsed: agent.executorResolved.fallbackUsed === true,
-          }
-        : null,
-    });
+              : "implementation";
+    const runtime = agent.executorResolved
+      ? {
+          executorId: agent.executorResolved.id,
+          role: agent.executorResolved.role,
+          profile: agent.executorResolved.profile,
+          selectedBy: agent.executorResolved.selectedBy,
+          retryPolicy: agent.executorResolved.retryPolicy || null,
+          allowFallbackOnRetry: agent.executorResolved.allowFallbackOnRetry !== false,
+          fallbacks: agent.executorResolved.fallbacks || [],
+          fallbackUsed: agent.executorResolved.fallbackUsed === true,
+        }
+      : null;
+    const pushTask = (taskKind) => {
+      tasks.push({
+        id: taskId(taskKind, agent.agentId),
+        title: `${agent.agentId}: ${agent.title}`,
+        owner: agent.agentId,
+        kind: taskKind,
+        dependsOn: [],
+        state: "planned",
+        proofState: "pending",
+        docState: "pending",
+        infraState: "n/a",
+        priority:
+          taskKind === "implementation" ? "normal" : taskKind === "integration" ? "high" : "high",
+        artifactRefs: agent.ownedPaths || [],
+        runtime,
+      });
+    };
+    if (hybridDesignAgent && kind === "design") {
+      pushTask("design");
+      pushTask("implementation");
+      continue;
+    }
+    pushTask(kind);
   }
   for (const promotion of wave.componentPromotions || []) {
     tasks.push({
@@ -163,6 +178,11 @@ function derivePhase({
     return blockingHelperTasks.some((task) => task.state === "blocked") ? "blocked" : "running";
   }
   const implementationTasks = tasks.filter((task) => task.kind === "implementation");
+  const designTasks = tasks.filter((task) => task.kind === "design");
+  const allDesignDone = designTasks.every((task) => task.state === "done");
+  if (!allDesignDone && designTasks.length > 0) {
+    return "design";
+  }
   const allImplementationDone = implementationTasks.every((task) => task.state === "done");
   if (!allImplementationDone) {
     return "running";
@@ -221,6 +241,15 @@ export function deriveWaveLedger({
         docState: summary?.docDelta?.state || "pending",
       };
     }
+    if (task.kind === "design" && agent) {
+      const validation = validateDesignSummary(agent, summary);
+      return {
+        ...task,
+        state: taskStateFromValidation(validation),
+        proofState: validation.ok ? "met" : "gap",
+        docState: validation.ok ? "met" : "gap",
+      };
+    }
     if (task.kind === "documentation" && agent) {
       const validation = validateDocumentationClosureSummary(agent, summary);
       return {

package/scripts/wave-orchestrator/local-executor.mjs

@@ -173,6 +173,11 @@ function formatWaveEvalLine(evalMarker, detail) {
   return `[wave-eval] state=satisfied targets=${targetIds.length} benchmarks=${benchmarkIds.length} regressions=0${targetIdSegment}${benchmarkIdSegment} detail=${detail}`;
 }
 
+function isDesignAgentPrompt(rawPrompt) {
+  const text = String(rawPrompt || "");
+  return /\[wave-design\]/i.test(text) || /\bwave design\b/i.test(text);
+}
+
 export function resolveRepoOwnedDeliverablePath(relPath) {
   if (!relPath || path.isAbsolute(relPath)) {
     throw new Error(`Unsafe deliverable path: ${String(relPath || "")}`);
@@ -277,6 +282,8 @@ export function runLocalExecutorCli(argv) {
   const contQaAgent = agentId === contQaAgentId;
   const contEvalAgent = agentId === contEvalAgentId;
   const integrationAgent = agentId === integrationAgentId;
+  const designAgent = isDesignAgentPrompt(rawPrompt);
+  const implementationMarkersRequired = /\[wave-proof\]/i.test(rawPrompt);
   const ownedComponents = extractOwnedComponents(rawPrompt);
   const assignedPrompt = extractAssignedPrompt(rawPrompt);
   const ownedPaths = extractFileOwnershipPaths(assignedPrompt);
@@ -304,6 +311,21 @@ export function runLocalExecutorCli(argv) {
       console.log(
         "[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=local-executor-no-deliverables",
       );
+    } else if (designAgent) {
+      console.log(
+        "[wave-design] state=ready-for-implementation decisions=1 assumptions=1 open_questions=0 detail=local-executor-no-deliverables",
+      );
+      if (implementationMarkersRequired) {
+        console.log(
+          "[wave-proof] completion=contract durability=none proof=unit state=met detail=local-executor-no-deliverables",
+        );
+        console.log("[wave-doc-delta] state=none detail=local-executor-no-deliverables");
+        for (const component of ownedComponents) {
+          console.log(
+            `[wave-component] component=${component.componentId} level=${component.level || "repo-landed"} state=met detail=local-executor-no-deliverables`,
+          );
+        }
+      }
     } else if (agentId === documentationAgentId) {
       console.log("[wave-doc-closure] state=no-change detail=local-executor-no-deliverables");
     } else if (agentId) {
@@ -348,6 +370,21 @@ export function runLocalExecutorCli(argv) {
     console.log(
       "[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=local-executor-smoke",
     );
+  } else if (designAgent) {
+    console.log(
+      "[wave-design] state=ready-for-implementation decisions=2 assumptions=1 open_questions=0 detail=local-executor-smoke",
+    );
+    if (implementationMarkersRequired) {
+      console.log(
+        "[wave-proof] completion=contract durability=none proof=unit state=met detail=local-executor-smoke",
+      );
+      console.log("[wave-doc-delta] state=owned detail=local-executor-smoke");
+      for (const component of ownedComponents) {
+        console.log(
+          `[wave-component] component=${component.componentId} level=${component.level || "repo-landed"} state=met detail=local-executor-smoke`,
+        );
+      }
+    }
   } else if (agentId === documentationAgentId) {
     console.log("[wave-doc-closure] state=no-change detail=local-executor-smoke");
   } else if (agentId) {

package/scripts/wave-orchestrator/planner.mjs

@@ -317,6 +317,9 @@ function defaultTargetLevel(template) {
 }
 
 function defaultExecutorProfile(roleKind) {
+  if (roleKind === "design") {
+    return "design-pass";
+  }
   if (roleKind === "infra" || roleKind === "deploy" || roleKind === "research") {
     return "ops-triage";
   }
@@ -327,7 +330,7 @@ function defaultExecutorProfile(roleKind) {
 }
 
 function defaultExitContract(roleKind) {
-  if (roleKind === "security") {
+  if (roleKind === "security" || roleKind === "design") {
     return null;
   }
   if (roleKind === "infra" || roleKind === "deploy") {
@@ -355,6 +358,9 @@ function defaultExitContract(roleKind) {
 }
 
 function buildDefaultValidationCommand(template, roleKind) {
+  if (roleKind === "design") {
+    return "Manual review of the design packet against the wave scope, constraints, and downstream ownership.";
+  }
   if (roleKind === "security") {
     return "Manual review of the changed security-sensitive surfaces plus required proofs.";
   }
@@ -368,6 +374,9 @@ function buildDefaultValidationCommand(template, roleKind) {
 }
 
 function buildDefaultOutputSummary(template, roleKind) {
+  if (roleKind === "design") {
+    return "Summarize the design packet, key decisions, assumptions, open questions, and exact implementation handoff.";
+  }
   if (roleKind === "security") {
     return "Summarize the threat model, findings, required approvals, requested fixes, and final security disposition.";
   }
@@ -381,6 +390,9 @@ function buildDefaultOutputSummary(template, roleKind) {
 }
 
 function buildDefaultPrimaryGoal(template, roleKind, title) {
+  if (roleKind === "design") {
+    return `Produce an implementation-ready design packet for the ${title.toLowerCase()} slice before coding starts.`;
+  }
   if (roleKind === "security") {
     return `Review the ${title.toLowerCase()} slice for security risks and route exact fixes before integration.`;
   }
@@ -1067,6 +1079,9 @@ function buildWorkerAgentSpec({
   if (roleKind === "research" && !capabilities.includes("research")) {
     capabilities.push("research");
   }
+  if (roleKind === "design" && !capabilities.includes("design")) {
+    capabilities.push("design");
+  }
   return {
     agentId,
     title,
@@ -1075,6 +1090,8 @@ function buildWorkerAgentSpec({
         ? values.rolePromptPaths
         : roleKind === "security"
           ? [lanePaths.securityRolePromptPath]
+          : roleKind === "design"
+            ? [lanePaths.designRolePromptPath]
           : [],
     skills: values.skills || [],
     executor: {
@@ -1934,6 +1951,7 @@ function normalizePlannerContext7Bundle(bundle, bundleIndex) {
 function normalizePlannerWorkerAgent(rawAgent, context) {
   const agentId = cleanText(rawAgent?.agentId) || `A${context.index + 1}`;
   const roleKind = [
+    "design",
     "implementation",
     "qa",
     "infra",
@@ -3067,12 +3085,12 @@ async function collectWorkerAgents({
     const title = cleanText(await prompt.ask(`Worker ${agentId} title`, defaults.title));
     const roleKind = await prompt.askChoice(
       `Worker ${agentId} role kind`,
-      ["implementation", "qa", "infra", "deploy", "research", "security"],
+      ["design", "implementation", "qa", "infra", "deploy", "research", "security"],
       defaultRoleKind,
     );
     const executorProfile = await prompt.askChoice(
       `Worker ${agentId} executor profile`,
-      ["implement-fast", "deep-review", "eval-tuning", "docs-pass", "ops-triage", "security-review"],
+      ["implement-fast", "design-pass", "deep-review", "eval-tuning", "docs-pass", "ops-triage", "security-review"],
       defaultExecutorProfile(roleKind),
     );
     const ownedPaths = normalizeRepoPathList(
@@ -3081,6 +3099,8 @@ async function collectWorkerAgents({
           `Worker ${agentId} owned paths (comma or | separated)`,
           roleKind === "security"
             ? `.tmp/${lane}-wave-launcher/security/wave-${waveNumber}-review.md`
+            : roleKind === "design"
+              ? `docs/plans/waves/design/wave-${waveNumber}-${agentId}.md`
             : template === "infra"
             ? "scripts/,docs/plans/"
             : template === "release"
@@ -3093,7 +3113,7 @@ async function collectWorkerAgents({
     const components = normalizeListText(
       await prompt.ask(
         `Worker ${agentId} component ids (comma or | separated)`,
-        roleKind === "security"
+        roleKind === "security" || roleKind === "design"
           ? ""
           : componentPromotions.map((promotion) => promotion.componentId).join(", "),
       ),

package/scripts/wave-orchestrator/projection-writer.mjs

@@ -0,0 +1,256 @@
+import path from "node:path";
+import {
+  writeAssignmentSnapshot,
+  writeDependencySnapshot,
+} from "./artifact-schemas.mjs";
+import {
+  syncGlobalWaveFromWaveDashboard,
+  writeGlobalDashboard,
+  writeWaveDashboard,
+} from "./dashboard-state.mjs";
+import { writeDocsQueue } from "./docs-queue.mjs";
+import { writeWaveLedger } from "./ledger.mjs";
+import { writeDependencySnapshotMarkdown } from "./routing-state.mjs";
+import {
+  writeCompiledInbox,
+  writeCoordinationBoardProjection,
+  writeJsonArtifact,
+} from "./coordination-store.mjs";
+import { parseStructuredSignalsFromLog } from "./dashboard-state.mjs";
+import { readRunExecutionSummary } from "./gate-engine.mjs";
+import { waveProofRegistryPath } from "./proof-registry.mjs";
+import { relaunchReasonBuckets, writeWaveRelaunchPlan } from "./retry-engine.mjs";
+import { toIsoTimestamp, writeTextAtomic } from "./shared.mjs";
+import { buildQualityMetrics, writeTraceBundle } from "./traces.mjs";
+
+export function writeWaveDerivedProjections({ lanePaths, wave, derivedState }) {
+  if (!derivedState) {
+    return null;
+  }
+  writeAssignmentSnapshot(derivedState.assignmentSnapshotPath, derivedState.capabilityAssignments, {
+    lane: lanePaths.lane,
+    wave: wave.wave,
+  });
+  writeDependencySnapshot(
+    derivedState.dependencySnapshotPath,
+    derivedState.dependencySnapshot,
+    {
+      lane: lanePaths.lane,
+      wave: wave.wave,
+    },
+  );
+  writeDependencySnapshotMarkdown(
+    derivedState.dependencySnapshotMarkdownPath,
+    derivedState.dependencySnapshot,
+  );
+  writeDocsQueue(derivedState.docsQueuePath, derivedState.docsQueue);
+  writeJsonArtifact(derivedState.securitySummaryPath, derivedState.securitySummary);
+  writeTextAtomic(
+    derivedState.securityMarkdownPath,
+    `${derivedState.securitySummary ? renderWaveSecuritySummaryMarkdown(derivedState.securitySummary) : ""}\n`,
+  );
+  writeJsonArtifact(derivedState.integrationSummaryPath, derivedState.integrationSummary);
+  writeTextAtomic(
+    derivedState.integrationMarkdownPath,
+    `${derivedState.integrationSummary ? renderIntegrationSummaryMarkdown(derivedState.integrationSummary) : ""}\n`,
+  );
+  writeWaveLedger(derivedState.ledgerPath, derivedState.ledger);
+  writeCompiledInbox(derivedState.sharedSummaryPath, derivedState.sharedSummaryText);
+  for (const inbox of Object.values(derivedState.inboxesByAgentId || {})) {
+    writeCompiledInbox(inbox.path, inbox.text);
+  }
+  writeCoordinationBoardProjection(derivedState.messageBoardPath, {
+    wave: wave.wave,
+    waveFile: wave.file,
+    agents: wave.agents,
+    state: derivedState.coordinationState,
+    capabilityAssignments: derivedState.capabilityAssignments,
+    dependencySnapshot: derivedState.dependencySnapshot,
+  });
+  return derivedState;
+}
+
+export function writeDashboardProjections({
+  lanePaths,
+  globalDashboard = null,
+  dashboardState = null,
+  dashboardPath = null,
+}) {
+  if (dashboardState && dashboardPath) {
+    writeWaveDashboard(dashboardPath, dashboardState);
+  }
+  if (globalDashboard && dashboardState) {
+    syncGlobalWaveFromWaveDashboard(globalDashboard, dashboardState);
+  }
+  if (globalDashboard) {
+    writeGlobalDashboard(lanePaths.globalDashboardPath, globalDashboard);
+  }
+}
+
+export function writeWaveAttemptTraceProjection({
+  lanePaths,
+  wave,
+  attempt,
+  launcherOptions,
+  derivedState,
+  manifest,
+  agentRuns,
+  gateSnapshot,
+  tracesDir,
+}) {
+  const structuredSignals = Object.fromEntries(
+    agentRuns.map((run) => [run.agent.agentId, parseStructuredSignalsFromLog(run.logPath)]),
+  );
+  const summariesByAgentId = Object.fromEntries(
+    agentRuns
+      .map((run) => [run.agent.agentId, readRunExecutionSummary(run, wave, { mode: "compat" })])
+      .filter(([, summary]) => summary),
+  );
+  const traceDir = writeTraceBundle({
+    tracesDir,
+    lanePaths,
+    launcherOptions,
+    wave,
+    attempt,
+    manifest,
+    coordinationLogPath: derivedState.coordinationLogPath,
+    coordinationState: derivedState.coordinationState,
+    ledger: derivedState.ledger,
+    docsQueue: derivedState.docsQueue,
+    capabilityAssignments: derivedState.capabilityAssignments,
+    dependencySnapshot: derivedState.dependencySnapshot,
+    securitySummary: derivedState.securitySummary,
+    integrationSummary: derivedState.integrationSummary,
+    integrationMarkdownPath: derivedState.integrationMarkdownPath,
+    proofRegistryPath: lanePaths.proofDir ? waveProofRegistryPath(lanePaths, wave.wave) : null,
+    controlPlanePath: path.join(lanePaths.controlPlaneDir, `wave-${wave.wave}.jsonl`),
+    clarificationTriage: derivedState.clarificationTriage,
+    agentRuns,
+    structuredSignals,
+    gateSnapshot,
+    quality: buildQualityMetrics({
+      tracesDir,
+      wave,
+      coordinationState: derivedState.coordinationState,
+      integrationSummary: derivedState.integrationSummary,
+      ledger: derivedState.ledger,
+      docsQueue: derivedState.docsQueue,
+      capabilityAssignments: derivedState.capabilityAssignments,
+      dependencySnapshot: derivedState.dependencySnapshot,
+      summariesByAgentId,
+      agentRuns,
+      gateSnapshot,
+      attempt,
+      coordinationLogPath: derivedState.coordinationLogPath,
+    }),
+  });
+  return {
+    traceDir,
+    structuredSignals,
+    summariesByAgentId,
+  };
+}
+
+export function writeWaveRelaunchProjection({
+  lanePaths,
+  wave,
+  attempt,
+  runs,
+  failures,
+  derivedState,
+}) {
+  writeWaveRelaunchPlan(lanePaths, wave.wave, {
+    wave: wave.wave,
+    attempt,
+    phase: derivedState?.ledger?.phase || null,
+    selectedAgentIds: runs.map((run) => run.agent.agentId),
+    reasonBuckets: relaunchReasonBuckets(runs, failures, derivedState),
+    executorStates: Object.fromEntries(
+      runs.map((run) => [run.agent.agentId, run.agent.executorResolved || null]),
+    ),
+    fallbackHistory: Object.fromEntries(
+      runs.map((run) => [
+        run.agent.agentId,
+        run.agent.executorResolved?.executorHistory || [],
+      ]),
+    ),
+    createdAt: toIsoTimestamp(),
+  });
+}
+
+function renderWaveSecuritySummaryMarkdown(securitySummary) {
+  return [
+    `# Wave ${securitySummary.wave} Security Summary`,
+    "",
+    `- State: ${securitySummary.overallState || "unknown"}`,
+    `- Detail: ${securitySummary.detail || "n/a"}`,
+    `- Total findings: ${securitySummary.totalFindings || 0}`,
+    `- Total approvals: ${securitySummary.totalApprovals || 0}`,
+    `- Reviewers: ${(securitySummary.agents || []).length}`,
+    "",
+    "## Reviews",
+    ...((securitySummary.agents || []).length > 0
+      ? securitySummary.agents.map(
+          (entry) =>
+            `- ${entry.agentId}: state=${entry.state || "unknown"} findings=${entry.findings || 0} approvals=${entry.approvals || 0}${entry.reportPath ? ` report=${entry.reportPath}` : ""}${entry.detail ? ` detail=${entry.detail}` : ""}`,
+        )
+      : ["- None."]),
+    "",
+  ].join("\n");
+}
+
+function renderIntegrationSection(title, items) {
+  return [
+    title,
+    ...((items || []).length > 0 ? items.map((item) => `- ${item}`) : ["- None."]),
+    "",
+  ];
+}
+
+function renderIntegrationSummaryMarkdown(integrationSummary) {
+  return [
+    `# Wave ${integrationSummary.wave} Integration Summary`,
+    "",
+    `- Recommendation: ${integrationSummary.recommendation || "unknown"}`,
+    `- Detail: ${integrationSummary.detail || "n/a"}`,
+    `- Open claims: ${(integrationSummary.openClaims || []).length}`,
+    `- Conflicting claims: ${(integrationSummary.conflictingClaims || []).length}`,
+    `- Unresolved blockers: ${(integrationSummary.unresolvedBlockers || []).length}`,
+    `- Changed interfaces: ${(integrationSummary.changedInterfaces || []).length}`,
+    `- Cross-component impacts: ${(integrationSummary.crossComponentImpacts || []).length}`,
+    `- Proof gaps: ${(integrationSummary.proofGaps || []).length}`,
+    `- Deploy risks: ${(integrationSummary.deployRisks || []).length}`,
+    `- Documentation gaps: ${(integrationSummary.docGaps || []).length}`,
+    `- Security review: ${integrationSummary.securityState || "not-applicable"}`,
+    `- Security findings: ${(integrationSummary.securityFindings || []).length}`,
+    `- Security approvals: ${(integrationSummary.securityApprovals || []).length}`,
+    `- Inbound dependencies: ${(integrationSummary.inboundDependencies || []).length}`,
+    `- Outbound dependencies: ${(integrationSummary.outboundDependencies || []).length}`,
+    `- Helper assignments: ${(integrationSummary.helperAssignments || []).length}`,
+    "",
+    ...renderIntegrationSection("## Open Claims", integrationSummary.openClaims),
+    ...renderIntegrationSection("## Conflicting Claims", integrationSummary.conflictingClaims),
+    ...renderIntegrationSection("## Unresolved Blockers", integrationSummary.unresolvedBlockers),
+    ...renderIntegrationSection("## Changed Interfaces", integrationSummary.changedInterfaces),
+    ...renderIntegrationSection(
+      "## Cross-Component Impacts",
+      integrationSummary.crossComponentImpacts,
+    ),
+    ...renderIntegrationSection("## Proof Gaps", integrationSummary.proofGaps),
+    ...renderIntegrationSection("## Deploy Risks", integrationSummary.deployRisks),
+    ...renderIntegrationSection("## Security Findings", integrationSummary.securityFindings),
+    ...renderIntegrationSection("## Security Approvals", integrationSummary.securityApprovals),
+    ...renderIntegrationSection("## Inbound Dependencies", integrationSummary.inboundDependencies),
+    ...renderIntegrationSection("## Outbound Dependencies", integrationSummary.outboundDependencies),
+    ...renderIntegrationSection("## Helper Assignments", integrationSummary.helperAssignments),
+    "## Runtime Assignments",
+    ...((integrationSummary.runtimeAssignments || []).length > 0
+      ? integrationSummary.runtimeAssignments.map(
+          (assignment) =>
+            `- ${assignment.agentId}: executor=${assignment.executorId || "n/a"} role=${assignment.role || "n/a"} profile=${assignment.profile || "none"} fallback_used=${assignment.fallbackUsed ? "yes" : "no"}`,
+        )
+      : ["- None."]),
+    "",
+    ...renderIntegrationSection("## Documentation Gaps", integrationSummary.docGaps),
+  ].join("\n");
+}

package/scripts/wave-orchestrator/reconcile-format.mjs

@@ -0,0 +1,32 @@
+import { compactSingleLine } from "./shared.mjs";
+
+export function formatReconcileBlockedWaveLine(blockedWave) {
+  const parts = Array.isArray(blockedWave?.reasons)
+    ? blockedWave.reasons
+        .map((reason) => {
+          const code = compactSingleLine(reason?.code || "", 80);
+          const detail = compactSingleLine(reason?.detail || "", 240);
+          return code && detail ? `${code}=${detail}` : "";
+        })
+        .filter(Boolean)
+    : [];
+  return `[reconcile] wave ${blockedWave?.wave ?? "unknown"} not reconstructable: ${
+    parts.join("; ") || "unknown reason"
+  }`;
+}
+
+export function formatReconcilePreservedWaveLine(preservedWave) {
+  const parts = Array.isArray(preservedWave?.reasons)
+    ? preservedWave.reasons
+        .map((reason) => {
+          const code = compactSingleLine(reason?.code || "", 80);
+          const detail = compactSingleLine(reason?.detail || "", 240);
+          return code && detail ? `${code}=${detail}` : "";
+        })
+        .filter(Boolean)
+    : [];
+  const previousState = compactSingleLine(preservedWave?.previousState || "completed", 80);
+  return `[reconcile] wave ${preservedWave?.wave ?? "unknown"} preserved as ${previousState}: ${
+    parts.join("; ") || "unknown reason"
+  }`;
+}