@chllming/wave-orchestration 0.7.0 → 0.7.2

package/scripts/wave-orchestrator/artifact-schemas.mjs

@@ -403,3 +403,84 @@ export function writeWaveControlDeliveryState(filePath, payload, defaults = {})
 export function cloneArtifactPayload(value) {
   return cloneJson(value);
 }
+
+// ── Wave 4: Surface class metadata and additional schema normalizers ──
+
+export const WAVE_STATE_SCHEMA_VERSION = 1;
+export const TASK_ENTITY_SCHEMA_VERSION = 1;
+export const AGENT_RESULT_ENVELOPE_SCHEMA_VERSION = 1;
+export const RESUME_PLAN_SCHEMA_VERSION = 1;
+export const HUMAN_INPUT_WORKFLOW_SCHEMA_VERSION = 1;
+
+export const SURFACE_CLASS_CANONICAL_EVENT = "canonical-event";
+export const SURFACE_CLASS_CANONICAL_SNAPSHOT = "canonical-snapshot";
+export const SURFACE_CLASS_CACHED_DERIVED = "cached-derived";
+export const SURFACE_CLASS_HUMAN_PROJECTION = "human-projection";
+export const SURFACE_CLASSES = new Set([
+  SURFACE_CLASS_CANONICAL_EVENT,
+  SURFACE_CLASS_CANONICAL_SNAPSHOT,
+  SURFACE_CLASS_CACHED_DERIVED,
+  SURFACE_CLASS_HUMAN_PROJECTION,
+]);
+
+export const WAVE_STATE_KIND = "wave-state-snapshot";
+export const TASK_ENTITY_KIND = "wave-task-entity";
+export const AGENT_RESULT_ENVELOPE_KIND = "agent-result-envelope";
+export const RESUME_PLAN_KIND = "wave-resume-plan";
+export const HUMAN_INPUT_WORKFLOW_KIND = "human-input-workflow-state";
+
+export function normalizeWaveStateSnapshot(payload, defaults = {}) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: WAVE_STATE_SCHEMA_VERSION,
+    kind: WAVE_STATE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+    lane: normalizeText(source.lane, normalizeText(defaults.lane, null)),
+    wave: normalizeInteger(source.wave, normalizeInteger(defaults.wave, null)),
+    ...source,
+    schemaVersion: WAVE_STATE_SCHEMA_VERSION,
+    kind: WAVE_STATE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+    generatedAt: normalizeText(source.generatedAt, toIsoTimestamp()),
+  };
+}
+
+export function readWaveStateSnapshot(filePath, defaults = {}) {
+  const payload = readJsonOrNull(filePath);
+  if (!payload) {
+    return null;
+  }
+  return normalizeWaveStateSnapshot(payload, defaults);
+}
+
+export function writeWaveStateSnapshot(filePath, payload, defaults = {}) {
+  const normalized = normalizeWaveStateSnapshot(payload, defaults);
+  writeJsonAtomic(filePath, normalized);
+  return normalized;
+}
+
+export function normalizeAgentResultEnvelope(payload) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: AGENT_RESULT_ENVELOPE_SCHEMA_VERSION,
+    kind: AGENT_RESULT_ENVELOPE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+    ...source,
+    schemaVersion: AGENT_RESULT_ENVELOPE_SCHEMA_VERSION,
+    kind: AGENT_RESULT_ENVELOPE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+  };
+}
+
+export function normalizeResumePlan(payload) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: RESUME_PLAN_SCHEMA_VERSION,
+    kind: RESUME_PLAN_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CACHED_DERIVED },
+    ...source,
+    schemaVersion: RESUME_PLAN_SCHEMA_VERSION,
+    kind: RESUME_PLAN_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CACHED_DERIVED },
+  };
+}

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

@@ -270,16 +270,60 @@ 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) => {
     const statusPath = statusPathForAgent(lanePaths, wave, agent);
     const statusRecord = readStatusRecordIfPresent(statusPath);
+    const logPath = path.join(lanePaths.logsDir, `wave-${wave.wave}-${agent.slug}.log`);
     const summary = augmentSummaryWithProofRegistry(
       agent,
-      readAgentExecutionSummary(statusPath),
+      readAgentExecutionSummary(statusPath, {
+        agent,
+        statusPath,
+        statusRecord,
+        logPath: fs.existsSync(logPath) ? logPath : null,
+      }),
       proofRegistry || { entries: [] },
     );
     const proofValidation =
@@ -301,9 +345,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 +384,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 +397,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 +447,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 +469,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 +481,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 +501,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 +509,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 +575,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 +588,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 +602,9 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
       tasks,
       capabilityAssignments,
       dependencySnapshot,
+      activeAttempt: controlState.activeAttempt,
       rerunRequest,
+      relaunchPlan,
       agentId,
     }),
     logicalAgents: buildLogicalAgents({
@@ -515,7 +613,7 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
       tasks,
       dependencySnapshot,
       capabilityAssignments,
-      rerunRequest,
+      selection,
       proofRegistry,
     }).filter((agent) => !agentId || agent.agentId === agentId),
     tasks,
@@ -533,8 +631,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/coordination.mjs

@@ -269,6 +269,15 @@ export function buildExecutionPrompt({
         "- Use `clear` only when no unresolved findings or approvals remain. Use `blocked` only when the wave must stop before integration.",
       ]
     : [];
+  const coordinationCommand = [
+    "pnpm exec wave coord post",
+    `--lane ${lane}`,
+    `--wave ${wave}`,
+    `--agent ${agent.agentId}`,
+    '--kind "<request|ack|claim|evidence|decision|blocker|handoff|clarification-request|orchestrator-guidance|resolved-by-policy|human-escalation|human-feedback|integration-summary>"',
+    '--summary "<one-line summary>"',
+    '--detail "<short detail>"',
+  ].join(" ");
   const implementationRequirements =
     ![contQaAgentId, documentationAgentId].includes(agent.agentId) &&
     !isSecurityReviewAgent(agent) &&
@@ -281,7 +290,8 @@ export function buildExecutionPrompt({
                 "- Emit one final structured component marker per owned component: `[wave-component] component=<id> level=<level> state=<met|gap> detail=<short-note>`.",
               ]
             : []),
-          "- If you leave any material architecture, integration, durability, ops, or docs gap, emit `[wave-gap] kind=<architecture|integration|durability|ops|docs> detail=<short-note>` and make the gap explicit instead of implying completion.",
+          "- If the work is incomplete, keep the required proof/doc/component markers and set `state=gap` on the relevant final marker instead of narrating completion.",
+          `- Route unresolved architecture, integration, durability, ops, or docs issues through \`${coordinationCommand}\`. Do not append \`[wave-gap]\` lines after the final implementation markers.`,
         ]
       : [];
   const exitContractLines = agent.exitContract
@@ -305,15 +315,6 @@ export function buildExecutionPrompt({
     '--context "<what you tried, options, and impact>"',
     "--timeout-seconds 30",
   ].join(" ");
-  const coordinationCommand = [
-    "pnpm exec wave coord post",
-    `--lane ${lane}`,
-    `--wave ${wave}`,
-    `--agent ${agent.agentId}`,
-    '--kind "<request|ack|claim|evidence|decision|blocker|handoff|clarification-request|orchestrator-guidance|resolved-by-policy|human-escalation|human-feedback|integration-summary>"',
-    '--summary "<one-line summary>"',
-    '--detail "<short detail>"',
-  ].join(" ");
   const context7Selection = context7?.selection || agent?.context7Resolved || null;
   const executorId = agent?.executorResolved?.id || "default";
   const context7LibrarySummary =

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)