@chllming/wave-orchestration 0.9.0 → 0.9.2

package/scripts/wave-orchestrator/terminals.mjs

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -7,10 +6,11 @@ import {
   REPO_ROOT,
   TERMINAL_COLOR,
   TERMINAL_ICON,
-  TMUX_COMMAND_TIMEOUT_MS,
   ensureDirectory,
+  shellQuote,
   writeJsonAtomic,
 } from "./shared.mjs";
+import { killSessionIfExists } from "./tmux-adapter.mjs";
 
 export const TERMINAL_SURFACES = ["vscode", "tmux", "none"];
 
@@ -95,13 +95,15 @@ export function createWaveAgentSessionName(lanePaths, wave, agentSlug) {
 export function createTemporaryTerminalEntries(
   lanePaths,
   wave,
-  agents,
+  agentRuns,
   runTag,
   includeDashboard = false,
 ) {
-  const agentEntries = agents.map((agent) => {
+  const agentEntries = (agentRuns || []).map((run) => {
+    const agent = run?.agent || run;
     const terminalName = `${lanePaths.terminalNamePrefix}${wave}-${agent.slug}`;
-    const sessionName = createWaveAgentSessionName(lanePaths, wave, agent.slug);
+    const sessionName = run?.sessionName || createWaveAgentSessionName(lanePaths, wave, agent.slug);
+    const logPath = String(run?.logPath || "").trim();
     return {
       terminalName,
       sessionName,
@@ -109,7 +111,9 @@ export function createTemporaryTerminalEntries(
         name: terminalName,
         icon: TERMINAL_ICON,
         color: TERMINAL_COLOR,
-        command: `TMUX= tmux -L ${lanePaths.tmuxSocketName} new -As ${sessionName}`,
+        command: logPath
+          ? `bash -lc "mkdir -p ${shellQuote(path.dirname(logPath))} && touch ${shellQuote(logPath)} && tail -n 200 -F ${shellQuote(logPath)}"`
+          : `TMUX= tmux -L ${lanePaths.tmuxSocketName} new -As ${sessionName}`,
       },
     };
   });
@@ -221,30 +225,6 @@ export function pruneOrphanLaneTemporaryTerminalEntries(
   };
 }
 
-export function killTmuxSessionIfExists(socketName, sessionName) {
-  const result = spawnSync("tmux", ["-L", socketName, "kill-session", "-t", sessionName], {
-    cwd: REPO_ROOT,
-    encoding: "utf8",
-    env: { ...process.env, TMUX: "" },
-    timeout: TMUX_COMMAND_TIMEOUT_MS,
-  });
-  if (result.error) {
-    if (result.error.code === "ETIMEDOUT") {
-      throw new Error(`kill existing session ${sessionName} failed: tmux command timed out`);
-    }
-    throw new Error(`kill existing session ${sessionName} failed: ${result.error.message}`);
-  }
-  if (result.status === 0) {
-    return;
-  }
-  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("no current target") ||
-    combined.includes("error connecting")
-  ) {
-    return;
-  }
-  throw new Error(`kill existing session ${sessionName} failed: ${(result.stderr || "").trim()}`);
+export async function killTmuxSessionIfExists(socketName, sessionName) {
+  await killSessionIfExists(socketName, sessionName);
 }

package/scripts/wave-orchestrator/tmux-adapter.mjs

@@ -0,0 +1,300 @@
+import { spawn } from "node:child_process";
+import {
+  REPO_ROOT,
+  TMUX_COMMAND_TIMEOUT_MS,
+  sleep,
+} from "./shared.mjs";
+
+const RETRYABLE_TMUX_ERROR_CODES = new Set(["EAGAIN", "EMFILE", "ENFILE"]);
+const MISSING_SESSION_MARKERS = [
+  "can't find session",
+  "no current target",
+];
+const NO_SERVER_MARKERS = [
+  "no server running",
+  "failed to connect",
+  "error connecting",
+];
+const DEFAULT_TMUX_RETRY_ATTEMPTS = 4;
+
+function tmuxCombinedOutput(stdout = "", stderr = "") {
+  return `${String(stderr || "").toLowerCase()}\n${String(stdout || "").toLowerCase()}`;
+}
+
+function classifyTmuxOutput(stdout = "", stderr = "") {
+  const combined = tmuxCombinedOutput(stdout, stderr);
+  return {
+    combined,
+    missingSession: MISSING_SESSION_MARKERS.some((marker) => combined.includes(marker)),
+    noServer: NO_SERVER_MARKERS.some((marker) => combined.includes(marker)),
+  };
+}
+
+function buildTmuxError(message, details = {}) {
+  const error = new Error(message);
+  Object.assign(error, details);
+  return error;
+}
+
+function retryDelayMs(attemptIndex) {
+  const baseDelay = Math.min(250, 25 * (2 ** attemptIndex));
+  return baseDelay + Math.floor(Math.random() * 25);
+}
+
+async function defaultSpawnTmux(socketName, args, { stdio = "pipe", timeoutMs = TMUX_COMMAND_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("tmux", ["-L", socketName, ...args], {
+      cwd: REPO_ROOT,
+      env: { ...process.env, TMUX: "" },
+      stdio,
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    if (child.stdout) {
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      reject(
+        buildTmuxError(`tmux process failed: ${error.message}`, {
+          code: error?.code || null,
+          stdout,
+          stderr,
+        }),
+      );
+    });
+    child.once("close", (status) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(
+          buildTmuxError(`tmux command timed out after ${timeoutMs}ms`, {
+            code: "ETIMEDOUT",
+            status,
+            stdout,
+            stderr,
+            tmuxTimedOut: true,
+          }),
+        );
+        return;
+      }
+      resolve({
+        status: typeof status === "number" ? status : 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+export function createTmuxAdapter({
+  spawnTmuxFn = defaultSpawnTmux,
+  sleepFn = sleep,
+  retryAttempts = DEFAULT_TMUX_RETRY_ATTEMPTS,
+} = {}) {
+  let mutationQueue = Promise.resolve();
+
+  const enqueueMutation = (callback) => {
+    const run = mutationQueue.then(callback, callback);
+    mutationQueue = run.catch(() => {});
+    return run;
+  };
+
+  const runWithRetry = async (callback, { description = "tmux command" } = {}) => {
+    for (let attemptIndex = 0; attemptIndex < retryAttempts; attemptIndex += 1) {
+      try {
+        return await callback();
+      } catch (error) {
+        if (!RETRYABLE_TMUX_ERROR_CODES.has(String(error?.code || "")) || attemptIndex === retryAttempts - 1) {
+          throw error;
+        }
+        await sleepFn(retryDelayMs(attemptIndex));
+      }
+    }
+    throw new Error(`${description} failed after ${retryAttempts} attempts.`);
+  };
+
+  const runTmuxCommand = async (
+    socketName,
+    args,
+    { description = "tmux command", stdio = "pipe", mutate = false } = {},
+  ) => {
+    const invoke = async () => {
+      try {
+        const result = await spawnTmuxFn(socketName, args, { stdio, timeoutMs: TMUX_COMMAND_TIMEOUT_MS });
+        if (result.status === 0) {
+          return result;
+        }
+        const classification = classifyTmuxOutput(result.stdout, result.stderr);
+        throw buildTmuxError(
+          `${description} failed: ${(result.stderr || result.stdout || "tmux command failed").trim() || "tmux command failed"}`,
+          {
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            tmuxMissingSession: classification.missingSession,
+            tmuxNoServer: classification.noServer,
+          },
+        );
+      } catch (error) {
+        if (error?.tmuxTimedOut || error?.tmuxMissingSession || error?.tmuxNoServer) {
+          throw error;
+        }
+        if (error?.code === "ENOENT") {
+          throw buildTmuxError(`${description} failed: tmux is not installed or not on PATH`, {
+            code: "ENOENT",
+            tmuxMissingBinary: true,
+          });
+        }
+        if (error?.code === "ETIMEDOUT") {
+          throw buildTmuxError(
+            `${description} failed: tmux command timed out after ${TMUX_COMMAND_TIMEOUT_MS}ms`,
+            {
+              code: "ETIMEDOUT",
+              tmuxTimedOut: true,
+            },
+          );
+        }
+        if (error instanceof Error) {
+          throw buildTmuxError(`${description} failed: ${error.message}`, {
+            code: error?.code || null,
+            stdout: error?.stdout || "",
+            stderr: error?.stderr || "",
+          });
+        }
+        throw error;
+      }
+    };
+    const runner = () => runWithRetry(invoke, { description });
+    return mutate ? enqueueMutation(runner) : runner();
+  };
+
+  const listSessions = async (socketName) => {
+    try {
+      const result = await runTmuxCommand(socketName, ["list-sessions", "-F", "#{session_name}"], {
+        description: "list tmux sessions",
+      });
+      return String(result.stdout || "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    } catch (error) {
+      if (error?.tmuxMissingBinary || error?.tmuxNoServer) {
+        return [];
+      }
+      throw error;
+    }
+  };
+
+  const hasSession = async (socketName, sessionName, { allowMissingBinary = true } = {}) => {
+    try {
+      await runTmuxCommand(socketName, ["has-session", "-t", sessionName], {
+        description: `lookup tmux session ${sessionName}`,
+      });
+      return true;
+    } catch (error) {
+      if (error?.tmuxMissingSession || error?.tmuxNoServer) {
+        return false;
+      }
+      if (error?.tmuxMissingBinary && allowMissingBinary) {
+        return false;
+      }
+      throw error;
+    }
+  };
+
+  const killSessionIfExists = async (socketName, sessionName) => {
+    try {
+      await runTmuxCommand(socketName, ["kill-session", "-t", sessionName], {
+        description: `kill existing session ${sessionName}`,
+        mutate: true,
+      });
+      return true;
+    } catch (error) {
+      if (error?.tmuxMissingBinary || error?.tmuxMissingSession || error?.tmuxNoServer) {
+        return false;
+      }
+      throw error;
+    }
+  };
+
+  const createSession = async (socketName, sessionName, command, { description = `launch session ${sessionName}` } = {}) => {
+    await runTmuxCommand(socketName, ["new-session", "-d", "-s", sessionName, command], {
+      description,
+      mutate: true,
+    });
+    return sessionName;
+  };
+
+  const attachSession = async (socketName, sessionName) => {
+    const exists = await hasSession(socketName, sessionName, { allowMissingBinary: false });
+    if (!exists) {
+      throw buildTmuxError(`No live tmux session named ${sessionName}.`, {
+        tmuxMissingSession: true,
+      });
+    }
+    try {
+      await runTmuxCommand(socketName, ["attach", "-t", sessionName], {
+        description: `attach tmux session ${sessionName}`,
+        stdio: "inherit",
+      });
+    } catch (error) {
+      if (error?.tmuxMissingBinary) {
+        throw error;
+      }
+      const stillExists = await hasSession(socketName, sessionName);
+      if (!stillExists || error?.tmuxMissingSession || error?.tmuxNoServer) {
+        throw buildTmuxError(`No live tmux session named ${sessionName}.`, {
+          tmuxMissingSession: true,
+        });
+      }
+      throw error;
+    }
+  };
+
+  return {
+    runTmuxCommand,
+    createSession,
+    killSessionIfExists,
+    listSessions,
+    hasSession,
+    attachSession,
+  };
+}
+
+const defaultTmuxAdapter = createTmuxAdapter();
+
+export function runTmuxCommand(socketName, args, options = {}) {
+  return defaultTmuxAdapter.runTmuxCommand(socketName, args, options);
+}
+
+export function createSession(socketName, sessionName, command, options = {}) {
+  return defaultTmuxAdapter.createSession(socketName, sessionName, command, options);
+}
+
+export function killSessionIfExists(socketName, sessionName) {
+  return defaultTmuxAdapter.killSessionIfExists(socketName, sessionName);
+}
+
+export function listSessions(socketName) {
+  return defaultTmuxAdapter.listSessions(socketName);
+}
+
+export function hasSession(socketName, sessionName, options = {}) {
+  return defaultTmuxAdapter.hasSession(socketName, sessionName, options);
+}
+
+export function attachSession(socketName, sessionName) {
+  return defaultTmuxAdapter.attachSession(socketName, sessionName);
+}

package/scripts/wave-orchestrator/traces.mjs

@@ -798,6 +798,8 @@ export function writeTraceBundle({
   capabilityAssignments = [],
   dependencySnapshot = null,
   securitySummary = null,
+  corridorSummary = null,
+  corridorSummaryPath = null,
   integrationSummary,
   integrationMarkdownPath,
   proofRegistryPath = null,
@@ -860,6 +862,28 @@ export function writeTraceBundle({
     "json",
     true,
   );
+  const corridorArtifact =
+    corridorSummaryPath || corridorSummary
+      ? corridorSummaryPath
+        ? copyArtifactDescriptor(
+            dir,
+            corridorSummaryPath,
+            path.join(dir, "corridor.json"),
+            false,
+          )
+        : writeArtifactDescriptor(
+            dir,
+            path.join(dir, "corridor.json"),
+            corridorSummary || {},
+            "json",
+            false,
+          )
+      : {
+          path: "corridor.json",
+          required: false,
+          present: false,
+          sha256: null,
+        };
   const integrationArtifact = writeArtifactDescriptor(
     dir,
     path.join(dir, "integration.json"),
@@ -1023,6 +1047,7 @@ export function writeTraceBundle({
       capabilityAssignments: capabilityAssignmentsArtifact,
       dependencySnapshot: dependencySnapshotArtifact,
       security: securityArtifact,
+      corridor: corridorArtifact,
       integration: integrationArtifact,
       integrationMarkdown: integrationMarkdownArtifact,
       proofRegistry: proofRegistryArtifact,

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

@@ -154,6 +154,19 @@ function resolveWaveControlConfig(lanePaths, overrides = {}) {
   };
 }
 
+function resolveWaveControlAuthToken(config) {
+  const authVars = Array.isArray(config.authTokenEnvVars)
+    ? config.authTokenEnvVars
+    : [config.authTokenEnvVar].filter(Boolean);
+  for (const envVar of authVars) {
+    const value = envVar ? String(process.env[envVar] || "").trim() : "";
+    if (value) {
+      return value;
+    }
+  }
+  return "";
+}
+
 function buildWorkspaceId(lanePaths, config) {
   return normalizeText(config.workspaceId, buildWorkspaceTmuxToken(REPO_ROOT));
 }
@@ -505,7 +518,7 @@ export async function flushWaveControlQueue(lanePaths, options = {}) {
 
   try {
     const ingestUrl = resolveIngestUrl(config.endpoint);
-    const authToken = config.authTokenEnvVar ? process.env[config.authTokenEnvVar] || "" : "";
+    const authToken = resolveWaveControlAuthToken(config);
     await postBatch(
       ingestUrl,
       authToken,

package/scripts/wave-orchestrator/wave-files.mjs

@@ -68,6 +68,8 @@ import {
   resolveDesignReportPath,
   isSecurityRolePromptPath,
   isSecurityReviewAgent,
+  resolveAgentClosureRoleKeys,
+  resolveWaveRoleBindings,
   resolveSecurityReviewReportPath,
 } from "./role-helpers.mjs";
 import {
@@ -107,6 +109,13 @@ const COMPONENT_MATURITY_ORDER = Object.fromEntries(
 );
 const PROOF_CENTRIC_COMPONENT_LEVEL = "pilot-live";
 const RETRY_POLICY_VALUES = new Set(["sticky", "fallback-allowed"]);
+const CLOSURE_ROLE_LABELS = {
+  "cont-eval": "cont-EVAL",
+  "security-review": "security review",
+  integration: "integration steward",
+  documentation: "documentation steward",
+  "cont-qa": "cont-QA",
+};
 
 function resolveLaneProfileForOptions(options = {}) {
   if (options.laneProfile) {
@@ -1209,7 +1218,11 @@ function isImplementationOwningWaveAgent(
   );
 }
 
-function resolveAgentSummaryReportPath(wave, agentId, { contQaAgentId, contEvalAgentId } = {}) {
+function resolveAgentSummaryReportPath(
+  wave,
+  agentId,
+  { contQaAgentId, contEvalAgentId, securityRolePromptPath } = {},
+) {
   if (agentId === contQaAgentId && wave.contQaReportPath) {
     return path.resolve(REPO_ROOT, wave.contQaReportPath);
   }
@@ -1223,7 +1236,7 @@ function resolveAgentSummaryReportPath(wave, agentId, { contQaAgentId, contEvalA
       return path.resolve(REPO_ROOT, designReportPath);
     }
   }
-  if (isSecurityReviewAgent(agent)) {
+  if (isSecurityReviewAgent(agent, { securityRolePromptPath })) {
     const securityReportPath = resolveSecurityReviewReportPath(agent);
     if (securityReportPath) {
       return path.resolve(REPO_ROOT, securityReportPath);
@@ -1240,6 +1253,7 @@ function materializeLiveExecutionSummaryIfMissing({
   logsDir,
   contQaAgentId,
   contEvalAgentId,
+  securityRolePromptPath = null,
 }) {
   const logPath = logsDir ? path.join(logsDir, `wave-${wave.wave}-${agent.slug}.log`) : null;
   const existing = readAgentExecutionSummary(statusPath, {
@@ -1250,6 +1264,7 @@ function materializeLiveExecutionSummaryIfMissing({
     reportPath: resolveAgentSummaryReportPath(wave, agent.agentId, {
       contQaAgentId,
       contEvalAgentId,
+      securityRolePromptPath,
     }),
   });
   if (existing) {
@@ -1265,6 +1280,7 @@ function materializeLiveExecutionSummaryIfMissing({
     reportPath: resolveAgentSummaryReportPath(wave, agent.agentId, {
       contQaAgentId,
       contEvalAgentId,
+      securityRolePromptPath,
     }),
   });
   writeAgentExecutionSummary(statusPath, summary);
@@ -1746,6 +1762,19 @@ export function validateWaveDefinition(wave, options = {}) {
       errors.push(`Design agent ${designAgent.agentId} must stay docs/spec-only unless it explicitly owns implementation files`);
     }
   }
+  const closureRoleBindings = resolveWaveRoleBindings(wave, laneProfile.roles, wave.agents);
+  for (const agent of wave.agents) {
+    const closureRoles = resolveAgentClosureRoleKeys(
+      agent,
+      closureRoleBindings,
+      laneProfile.roles,
+    );
+    if (closureRoles.length > 1) {
+      errors.push(
+        `Agent ${agent.agentId} must not overlap closure roles (${closureRoles.map((role) => CLOSURE_ROLE_LABELS[role] || role).join(", ")})`,
+      );
+    }
+  }
   if (integrationRuleActive) {
     const integrationStewards = wave.agents.filter((agent) =>
       agent.rolePromptPaths?.includes(laneProfile.roles.integrationRolePromptPath),
@@ -2006,7 +2035,9 @@ function inferAgentRuntimeRole(agent, laneProfile) {
   ) {
     return "design";
   }
-  if (isSecurityReviewAgent(agent)) {
+  if (isSecurityReviewAgent(agent, {
+    securityRolePromptPath: laneProfile?.roles?.securityRolePromptPath,
+  })) {
     return "security";
   }
   const capabilities = Array.isArray(agent?.capabilities)
@@ -2203,7 +2234,7 @@ export function resolveAgentExecutor(agent, options = {}) {
         profile?.codex?.sandbox ||
         (executorId === "codex"
           ? normalizeCodexSandboxMode(
-              options.codexSandboxMode || laneProfile.executors.codex.sandbox,
+              options.codexSandboxMode ?? laneProfile.executors.codex.sandbox ?? DEFAULT_CODEX_SANDBOX_MODE,
               "executor.codex.sandbox",
             )
           : laneProfile.executors.codex.sandbox || DEFAULT_CODEX_SANDBOX_MODE),
@@ -2924,6 +2955,7 @@ function analyzeWaveCompletionFromStatusFiles(wave, statusDir, options = {}) {
   const componentThreshold =
     options.requireComponentPromotionsFromWave ??
     laneProfile.validation.requireComponentPromotionsFromWave;
+  const securityRolePromptPath = resolveSecurityRolePromptPath(laneProfile);
 
   const reasons = [];
   const summariesByAgentId = {};
@@ -2980,6 +3012,7 @@ function analyzeWaveCompletionFromStatusFiles(wave, statusDir, options = {}) {
       logsDir,
       contQaAgentId,
       contEvalAgentId,
+      securityRolePromptPath,
     });
     summariesByAgentId[agent.agentId] = summary;
     if (agent.agentId === contQaAgentId) {
@@ -3021,7 +3054,7 @@ function analyzeWaveCompletionFromStatusFiles(wave, statusDir, options = {}) {
       }
       continue;
     }
-    if (isSecurityReviewAgent(agent)) {
+    if (isSecurityReviewAgent(agent, { securityRolePromptPath })) {
       const validation = validateSecuritySummary(agent, summary);
       if (!validation.ok) {
         pushWaveCompletionReason(

package/scripts/wave.mjs

@@ -20,6 +20,11 @@ function printHelp() {
   wave draft [draft options]
   wave adhoc [adhoc options]
   wave launch [launcher options]
+  wave submit [launcher options]
+  wave supervise [supervisor options]
+  wave status --run-id <id> [--json]
+  wave wait --run-id <id> [--timeout-seconds <n>] [--json]
+  wave attach --run-id <id> (--agent <id> | --dashboard)
   wave autonomous [autonomous options]
   wave feedback [feedback options]
   wave dashboard [dashboard options]
@@ -73,6 +78,14 @@ if (["init", "upgrade", "self-update", "changelog", "doctor"].includes(subcomman
     console.error(`[wave] ${error instanceof Error ? error.message : String(error)}`);
     process.exit(Number.isInteger(error?.exitCode) ? error.exitCode : 1);
   }
+} else if (["submit", "supervise", "status", "wait", "attach"].includes(subcommand)) {
+  try {
+    const { runSupervisorCli } = await import("./wave-orchestrator/supervisor-cli.mjs");
+    await runSupervisorCli(subcommand, rest);
+  } catch (error) {
+    console.error(`[wave] ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(Number.isInteger(error?.exitCode) ? error.exitCode : 1);
+  }
 } else if (subcommand === "autonomous") {
   const { runAutonomousCli } = await import("./wave-orchestrator/autonomous.mjs");
   try {