@chllming/wave-orchestration 0.8.9 → 0.9.0

package/scripts/wave-orchestrator/config.mjs

@@ -17,6 +17,7 @@ const REPO_ROOT = WORKSPACE_ROOT;
 
 export const DEFAULT_WAVE_CONFIG_PATH = path.join(REPO_ROOT, "wave.config.json");
 export const DEFAULT_WAVE_LANE = "main";
+export const DEFAULT_PROJECT_ID = "default";
 export const DEFAULT_CONT_QA_AGENT_ID = "A0";
 export const DEFAULT_CONT_EVAL_AGENT_ID = "E0";
 export const DEFAULT_INTEGRATION_AGENT_ID = "A8";
@@ -73,7 +74,8 @@ export const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full
 export const DEFAULT_CLAUDE_COMMAND = "claude";
 export const DEFAULT_OPENCODE_COMMAND = "opencode";
 export const DEFAULT_WAVE_CONTROL_AUTH_TOKEN_ENV_VAR = "WAVE_CONTROL_AUTH_TOKEN";
-export const DEFAULT_WAVE_CONTROL_REPORT_MODE = "metadata-plus-selected";
+export const DEFAULT_WAVE_CONTROL_ENDPOINT = "https://wave-control.up.railway.app/api/v1";
+export const DEFAULT_WAVE_CONTROL_REPORT_MODE = "metadata-only";
 export const DEFAULT_WAVE_CONTROL_REQUEST_TIMEOUT_MS = 5000;
 export const DEFAULT_WAVE_CONTROL_FLUSH_BATCH_SIZE = 25;
 export const DEFAULT_WAVE_CONTROL_MAX_PENDING_EVENTS = 1000;
@@ -137,6 +139,22 @@ function sanitizeLaneName(value) {
   return lane;
 }
 
+export function sanitizeProjectId(value) {
+  const projectId = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!projectId) {
+    throw new Error("Project id is required");
+  }
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(projectId)) {
+    throw new Error(`Invalid project id: ${value}`);
+  }
+  return projectId;
+}
+
 function readJsonOrNull(filePath) {
   try {
     return JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -185,6 +203,26 @@ function normalizeOptionalString(value, fallback = null) {
   return normalized || fallback;
 }
 
+function joinRepoPath(basePath, childPath) {
+  const base = String(basePath || "")
+    .replaceAll("\\", "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+/g, "/")
+    .replace(/\/$/, "");
+  const child = String(childPath || "")
+    .replaceAll("\\", "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+/g, "/")
+    .replace(/\/$/, "");
+  if (!base || base === ".") {
+    return child;
+  }
+  if (!child) {
+    return base;
+  }
+  return `${base}/${child}`.replace(/\/+/g, "/");
+}
+
 function normalizeOptionalPositiveInt(value, label, fallback = null) {
   if (value === null || value === undefined || value === "") {
     return fallback;
@@ -282,11 +320,11 @@ function normalizeThreshold(value, fallback) {
   return parsed;
 }
 
-function defaultDocsDirForLane(lane, defaultLane, repoMode) {
+function defaultDocsDirForLane(lane, defaultLane, repoMode, projectDocsDir = DEFAULT_DOCS_DIR) {
   if (repoMode === "single-repo" && lane === defaultLane) {
-    return DEFAULT_DOCS_DIR;
+    return projectDocsDir;
   }
-  return `${DEFAULT_DOCS_DIR}/${lane}`;
+  return joinRepoPath(projectDocsDir, lane);
 }
 
 function defaultPlansDir(docsDir) {
@@ -549,7 +587,7 @@ function normalizeWaveControl(rawWaveControl = {}, label = "waveControl") {
     reportMode !== "disabled" && normalizeOptionalBoolean(waveControl.enabled, true);
   return {
     enabled,
-    endpoint: normalizeOptionalString(waveControl.endpoint, null),
+    endpoint: normalizeOptionalString(waveControl.endpoint, DEFAULT_WAVE_CONTROL_ENDPOINT),
     workspaceId: normalizeOptionalString(waveControl.workspaceId, null),
     projectId: normalizeOptionalString(waveControl.projectId, null),
     authTokenEnvVar:
@@ -931,6 +969,7 @@ export function loadWaveConfig(configPath = DEFAULT_WAVE_CONFIG_PATH) {
     throw new Error(`Unsupported repoMode in ${path.relative(REPO_ROOT, configPath)}: ${repoMode}`);
   }
   const defaultLane = sanitizeLaneName(rawConfig.defaultLane || DEFAULT_WAVE_LANE);
+  const defaultProject = sanitizeProjectId(rawConfig.defaultProject || DEFAULT_PROJECT_ID);
   const paths = {
     docsDir: normalizeRepoRelativePath(rawConfig.paths?.docsDir || DEFAULT_DOCS_DIR, "paths.docsDir"),
     stateRoot: normalizeRepoRelativePath(
@@ -966,17 +1005,122 @@ export function loadWaveConfig(configPath = DEFAULT_WAVE_CONFIG_PATH) {
   };
   const sharedPlanDocs =
     normalizeOptionalPathArray(rawConfig.sharedPlanDocs, "sharedPlanDocs") || null;
-  const lanes = Object.fromEntries(
+  const legacyLanes = Object.fromEntries(
     Object.entries(rawConfig.lanes || {}).map(([laneName, laneConfig]) => [
       sanitizeLaneName(laneName),
       laneConfig || {},
     ]),
   );
+  const rawProjects =
+    rawConfig.projects && typeof rawConfig.projects === "object" && !Array.isArray(rawConfig.projects)
+      ? rawConfig.projects
+      : null;
+  const projects = Object.fromEntries(
+    Object.entries(
+      rawProjects || {
+        [defaultProject]: {
+          projectName: rawConfig.projectName,
+          rootDir: ".",
+          sharedPlanDocs: rawConfig.sharedPlanDocs,
+          lanes: legacyLanes,
+        },
+      },
+    ).map(([projectId, projectConfig]) => {
+      const normalizedProjectId = sanitizeProjectId(projectId);
+      const rawProject =
+        projectConfig && typeof projectConfig === "object" && !Array.isArray(projectConfig)
+          ? projectConfig
+          : {};
+      const rootDir = normalizeRepoRelativePath(
+        rawProject.rootDir || ".",
+        `projects.${projectId}.rootDir`,
+      );
+      const projectSharedPlanDocs =
+        normalizeOptionalPathArray(
+          rawProject.sharedPlanDocs,
+          `projects.${projectId}.sharedPlanDocs`,
+        ) || null;
+      const projectDocsDir = normalizeRepoRelativePath(
+        rawProject.paths?.docsDir || joinRepoPath(rootDir, rawConfig.paths?.docsDir || DEFAULT_DOCS_DIR),
+        `projects.${projectId}.paths.docsDir`,
+      );
+      const projectPaths = {
+        docsDir: projectDocsDir,
+        stateRoot: normalizeRepoRelativePath(
+          rawProject.paths?.stateRoot || rawConfig.paths?.stateRoot || DEFAULT_STATE_ROOT,
+          `projects.${projectId}.paths.stateRoot`,
+        ),
+        orchestratorStateDir: normalizeRepoRelativePath(
+          rawProject.paths?.orchestratorStateDir ||
+            rawConfig.paths?.orchestratorStateDir ||
+            DEFAULT_ORCHESTRATOR_STATE_DIR,
+          `projects.${projectId}.paths.orchestratorStateDir`,
+        ),
+        terminalsPath: normalizeRepoRelativePath(
+          rawProject.paths?.terminalsPath || rawConfig.paths?.terminalsPath || DEFAULT_TERMINALS_PATH,
+          `projects.${projectId}.paths.terminalsPath`,
+        ),
+        context7BundleIndexPath: normalizeRepoRelativePath(
+          rawProject.paths?.context7BundleIndexPath ||
+            rawConfig.paths?.context7BundleIndexPath ||
+            DEFAULT_CONTEXT7_BUNDLE_INDEX_PATH,
+          `projects.${projectId}.paths.context7BundleIndexPath`,
+        ),
+        benchmarkCatalogPath: normalizeRepoRelativePath(
+          rawProject.paths?.benchmarkCatalogPath ||
+            rawConfig.paths?.benchmarkCatalogPath ||
+            DEFAULT_BENCHMARK_CATALOG_PATH,
+          `projects.${projectId}.paths.benchmarkCatalogPath`,
+        ),
+        componentCutoverMatrixDocPath: normalizeRepoRelativePath(
+          rawProject.paths?.componentCutoverMatrixDocPath ||
+            rawConfig.paths?.componentCutoverMatrixDocPath ||
+            defaultComponentCutoverMatrixDocPath(defaultPlansDir(projectDocsDir)),
+          `projects.${projectId}.paths.componentCutoverMatrixDocPath`,
+        ),
+        componentCutoverMatrixJsonPath: normalizeRepoRelativePath(
+          rawProject.paths?.componentCutoverMatrixJsonPath ||
+            rawConfig.paths?.componentCutoverMatrixJsonPath ||
+            defaultComponentCutoverMatrixJsonPath(defaultPlansDir(projectDocsDir)),
+          `projects.${projectId}.paths.componentCutoverMatrixJsonPath`,
+        ),
+      };
+      const projectLanes = Object.fromEntries(
+        Object.entries(rawProject.lanes || {}).map(([laneName, laneConfig]) => [
+          sanitizeLaneName(laneName),
+          laneConfig || {},
+        ]),
+      );
+      return [
+        normalizedProjectId,
+        {
+          projectId: normalizedProjectId,
+          projectName: String(
+            rawProject.projectName || rawConfig.projectName || normalizedProjectId,
+          ).trim(),
+          rootDir,
+          sharedPlanDocs: projectSharedPlanDocs,
+          paths: projectPaths,
+          roles: rawProject.roles || {},
+          validation: rawProject.validation || {},
+          executors: rawProject.executors || {},
+          planner: rawProject.planner || {},
+          skills: rawProject.skills || {},
+          capabilityRouting: rawProject.capabilityRouting || {},
+          runtimePolicy: rawProject.runtimePolicy || {},
+          waveControl: rawProject.waveControl || {},
+          lanes: projectLanes,
+          explicit: Boolean(rawProjects),
+        },
+      ];
+    }),
+  );
   return {
     version: Number.parseInt(String(rawConfig.version ?? "1"), 10) || 1,
     projectName: String(rawConfig.projectName || "Wave Orchestrator").trim(),
     repoMode,
     defaultLane,
+    defaultProject,
     paths,
     roles: normalizeRoles(rawConfig.roles),
     validation: normalizeValidation(rawConfig.validation),
@@ -987,16 +1131,82 @@ export function loadWaveConfig(configPath = DEFAULT_WAVE_CONFIG_PATH) {
     runtimePolicy: normalizeRuntimePolicy(rawConfig.runtimePolicy),
     waveControl: normalizeWaveControl(rawConfig.waveControl, "waveControl"),
     sharedPlanDocs,
-    lanes,
+    lanes: legacyLanes,
+    projects,
     configPath,
   };
 }
 
-export function resolveLaneProfile(config, laneInput = config.defaultLane) {
+export function resolveProjectProfile(config, projectInput = config.defaultProject) {
+  const projectId = sanitizeProjectId(projectInput || config.defaultProject || DEFAULT_PROJECT_ID);
+  const projectConfig = config.projects?.[projectId];
+  if (!projectConfig) {
+    throw new Error(`Unknown project: ${projectInput}`);
+  }
+  const paths = {
+    ...config.paths,
+    ...(projectConfig.paths || {}),
+  };
+  return {
+    projectId,
+    projectName: projectConfig.projectName || config.projectName,
+    rootDir: projectConfig.rootDir || ".",
+    paths,
+    sharedPlanDocs: projectConfig.sharedPlanDocs || null,
+    roles: normalizeRoles({
+      ...config.roles,
+      ...(projectConfig.roles || {}),
+    }),
+    validation: normalizeValidation({
+      ...config.validation,
+      ...(projectConfig.validation || {}),
+    }),
+    executors: normalizeExecutors(
+      mergeExecutors(config.executors, projectConfig.executors || {}),
+    ),
+    planner: normalizePlanner({
+      ...config.planner,
+      ...(projectConfig.planner || {}),
+    }),
+    skills: mergeSkillsConfig(
+      config.skills || emptySkillsConfig(),
+      normalizeLaneSkills(projectConfig.skills || {}, `${projectId}.skills`, {
+        preserveOmittedDir: true,
+      }),
+    ),
+    capabilityRouting: normalizeCapabilityRouting({
+      ...config.capabilityRouting,
+      ...(projectConfig.capabilityRouting || {}),
+    }),
+    runtimePolicy: normalizeRuntimePolicy({
+      ...config.runtimePolicy,
+      ...(projectConfig.runtimePolicy || {}),
+    }),
+    waveControl: normalizeWaveControl(
+      {
+        ...config.waveControl,
+        projectId,
+        ...(projectConfig.waveControl || {}),
+      },
+      `projects.${projectId}.waveControl`,
+    ),
+    lanes: projectConfig.lanes || {},
+    explicit: projectConfig.explicit === true,
+  };
+}
+
+export function resolveLaneProfile(config, laneInput = config.defaultLane, projectInput = config.defaultProject) {
+  const projectProfile = resolveProjectProfile(config, projectInput);
   const lane = sanitizeLaneName(laneInput || config.defaultLane);
-  const laneConfig = config.lanes[lane] || {};
+  const laneConfig = projectProfile.lanes[lane] || config.lanes[lane] || {};
   const docsDir = normalizeRepoRelativePath(
-    laneConfig.docsDir || defaultDocsDirForLane(lane, config.defaultLane, config.repoMode),
+    laneConfig.docsDir ||
+      defaultDocsDirForLane(
+        lane,
+        config.defaultLane,
+        config.repoMode,
+        projectProfile.paths.docsDir,
+      ),
     `${lane}.docsDir`,
   );
   const plansDir = normalizeRepoRelativePath(
@@ -1008,28 +1218,28 @@ export function resolveLaneProfile(config, laneInput = config.defaultLane) {
     `${lane}.wavesDir`,
   );
   const roles = normalizeRoles({
-    ...config.roles,
+    ...projectProfile.roles,
     ...(laneConfig.roles || {}),
   });
   const validation = normalizeValidation({
-    ...config.validation,
+    ...projectProfile.validation,
     ...(laneConfig.validation || {}),
   });
   const executors = normalizeExecutors(
-    mergeExecutors(config.executors, laneConfig.executors),
+    mergeExecutors(projectProfile.executors, laneConfig.executors),
   );
   const skills = mergeSkillsConfig(
-    config.skills || emptySkillsConfig(),
+    projectProfile.skills || emptySkillsConfig(),
     normalizeLaneSkills(laneConfig.skills, `${lane}.skills`, {
       preserveOmittedDir: true,
     }),
   );
   const capabilityRouting = normalizeCapabilityRouting({
-    ...config.capabilityRouting,
+    ...projectProfile.capabilityRouting,
     ...(laneConfig.capabilityRouting || {}),
   });
   const runtimePolicy = normalizeRuntimePolicy({
-    ...config.runtimePolicy,
+    ...projectProfile.runtimePolicy,
     ...(laneConfig.runtimePolicy || {}),
     ...(laneConfig.runtimeMixTargets ? { runtimeMixTargets: laneConfig.runtimeMixTargets } : {}),
     ...(laneConfig.defaultExecutorByRole
@@ -1041,18 +1251,23 @@ export function resolveLaneProfile(config, laneInput = config.defaultLane) {
   });
   const waveControl = normalizeWaveControl(
     {
-      ...config.waveControl,
+      ...projectProfile.waveControl,
       ...(laneConfig.waveControl || {}),
     },
     `${lane}.waveControl`,
   );
   return {
+    projectId: projectProfile.projectId,
+    projectName: projectProfile.projectName,
+    projectRootDir: projectProfile.rootDir,
+    explicitProject: projectProfile.explicit === true,
     lane,
     docsDir,
     plansDir,
     wavesDir,
     sharedPlanDocs:
       normalizeOptionalPathArray(laneConfig.sharedPlanDocs, `${lane}.sharedPlanDocs`) ||
+      projectProfile.sharedPlanDocs ||
       config.sharedPlanDocs ||
       defaultSharedPlanDocs(plansDir),
     roles,
@@ -1064,34 +1279,34 @@ export function resolveLaneProfile(config, laneInput = config.defaultLane) {
     waveControl,
     paths: {
       terminalsPath: normalizeRepoRelativePath(
-        laneConfig.terminalsPath || config.paths.terminalsPath,
+        laneConfig.terminalsPath || projectProfile.paths.terminalsPath,
         `${lane}.terminalsPath`,
       ),
       stateRoot: normalizeRepoRelativePath(
-        laneConfig.stateRoot || config.paths.stateRoot,
+        laneConfig.stateRoot || projectProfile.paths.stateRoot,
         `${lane}.stateRoot`,
       ),
       orchestratorStateDir: normalizeRepoRelativePath(
-        laneConfig.orchestratorStateDir || config.paths.orchestratorStateDir,
+        laneConfig.orchestratorStateDir || projectProfile.paths.orchestratorStateDir,
         `${lane}.orchestratorStateDir`,
       ),
       context7BundleIndexPath: normalizeRepoRelativePath(
-        laneConfig.context7BundleIndexPath || config.paths.context7BundleIndexPath,
+        laneConfig.context7BundleIndexPath || projectProfile.paths.context7BundleIndexPath,
         `${lane}.context7BundleIndexPath`,
       ),
       benchmarkCatalogPath: normalizeRepoRelativePath(
-        laneConfig.benchmarkCatalogPath || config.paths.benchmarkCatalogPath,
+        laneConfig.benchmarkCatalogPath || projectProfile.paths.benchmarkCatalogPath,
         `${lane}.benchmarkCatalogPath`,
       ),
       componentCutoverMatrixDocPath: normalizeRepoRelativePath(
         laneConfig.componentCutoverMatrixDocPath ||
-          config.paths.componentCutoverMatrixDocPath ||
+          projectProfile.paths.componentCutoverMatrixDocPath ||
           defaultComponentCutoverMatrixDocPath(plansDir),
         `${lane}.componentCutoverMatrixDocPath`,
       ),
       componentCutoverMatrixJsonPath: normalizeRepoRelativePath(
         laneConfig.componentCutoverMatrixJsonPath ||
-          config.paths.componentCutoverMatrixJsonPath ||
+          projectProfile.paths.componentCutoverMatrixJsonPath ||
           defaultComponentCutoverMatrixJsonPath(plansDir),
         `${lane}.componentCutoverMatrixJsonPath`,
       ),

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

@@ -19,10 +19,9 @@ import {
   DEFAULT_COORDINATION_ACK_TIMEOUT_MS,
   DEFAULT_COORDINATION_RESOLUTION_STALE_MS,
   ensureDirectory,
+  findAdhocRunRecord,
   parseNonNegativeInt,
-  readJsonOrNull,
   readStatusRecordIfPresent,
-  REPO_ROOT,
   sanitizeAdhocRunId,
   sanitizeLaneName,
   toIsoTimestamp,
@@ -51,23 +50,23 @@ import {
 
 function printUsage() {
   console.log(`Usage:
-  wave control status --lane <lane> --wave <n> [--agent <id>] [--json]
-  wave control telemetry status --lane <lane> [--run <id>] [--json]
-  wave control telemetry flush --lane <lane> [--run <id>] [--json]
+  wave control status --project <id> --lane <lane> --wave <n> [--agent <id>] [--json]
+  wave control telemetry status --project <id> --lane <lane> [--run <id>] [--json]
+  wave control telemetry flush --project <id> --lane <lane> [--run <id>] [--json]
 
-  wave control task create --lane <lane> --wave <n> --agent <id> --kind <request|blocker|clarification|handoff|evidence|claim|decision|human-input> --summary <text> [options]
-  wave control task list --lane <lane> --wave <n> [--agent <id>] [--json]
-  wave control task get --lane <lane> --wave <n> --id <task-id> [--json]
-  wave control task act <start|resolve|dismiss|cancel|reassign|answer|escalate|defer|mark-advisory|mark-stale|resolve-policy> --lane <lane> --wave <n> --id <task-id> [options]
+  wave control task create --project <id> --lane <lane> --wave <n> --agent <id> --kind <request|blocker|clarification|handoff|evidence|claim|decision|human-input> --summary <text> [options]
+  wave control task list --project <id> --lane <lane> --wave <n> [--agent <id>] [--json]
+  wave control task get --project <id> --lane <lane> --wave <n> --id <task-id> [--json]
+  wave control task act <start|resolve|dismiss|cancel|reassign|answer|escalate|defer|mark-advisory|mark-stale|resolve-policy> --project <id> --lane <lane> --wave <n> --id <task-id> [options]
 
-  wave control rerun request --lane <lane> --wave <n> [--agent <id> ...] [--resume-cursor <cursor>] [--reuse-attempt <id> ...] [--reuse-proof <id> ...] [--reuse-derived-summaries <true|false>] [--invalidate-component <id> ...] [--clear-reuse <id> ...] [--preserve-reuse <id> ...] [--requested-by <name>] [--reason <text>] [--json]
-  wave control rerun get --lane <lane> --wave <n> [--json]
-  wave control rerun clear --lane <lane> --wave <n>
+  wave control rerun request --project <id> --lane <lane> --wave <n> [--agent <id> ...] [--resume-cursor <cursor>] [--reuse-attempt <id> ...] [--reuse-proof <id> ...] [--reuse-derived-summaries <true|false>] [--invalidate-component <id> ...] [--clear-reuse <id> ...] [--preserve-reuse <id> ...] [--requested-by <name>] [--reason <text>] [--json]
+  wave control rerun get --project <id> --lane <lane> --wave <n> [--json]
+  wave control rerun clear --project <id> --lane <lane> --wave <n>
 
-  wave control proof register --lane <lane> --wave <n> --agent <id> --artifact <path> [--artifact <path> ...] [--component <id[:level]> ...] [--authoritative] [--satisfy-owned-components] [--completion <level>] [--durability <level>] [--proof-level <level>] [--doc-delta <state>] [--operator <name>] [--detail <text>] [--json]
-  wave control proof get --lane <lane> --wave <n> [--agent <id>] [--id <bundle-id>] [--json]
-  wave control proof supersede --lane <lane> --wave <n> --id <bundle-id> --agent <id> --artifact <path> [--artifact <path> ...] [options]
-  wave control proof revoke --lane <lane> --wave <n> --id <bundle-id> [--operator <name>] [--detail <text>] [--json]
+  wave control proof register --project <id> --lane <lane> --wave <n> --agent <id> --artifact <path> [--artifact <path> ...] [--component <id[:level]> ...] [--authoritative] [--satisfy-owned-components] [--completion <level>] [--durability <level>] [--proof-level <level>] [--doc-delta <state>] [--operator <name>] [--detail <text>] [--json]
+  wave control proof get --project <id> --lane <lane> --wave <n> [--agent <id>] [--id <bundle-id>] [--json]
+  wave control proof supersede --project <id> --lane <lane> --wave <n> --id <bundle-id> --agent <id> --artifact <path> [--artifact <path> ...] [options]
+  wave control proof revoke --project <id> --lane <lane> --wave <n> --id <bundle-id> [--operator <name>] [--detail <text>] [--json]
 `);
 }
 
@@ -91,6 +90,7 @@ function parseArgs(argv) {
   const operation = String(args[1] || "").trim().toLowerCase();
   const action = String(args[2] || "").trim().toLowerCase();
   const options = {
+    project: "",
     lane: "main",
     wave: null,
     runId: "",
@@ -144,7 +144,9 @@ function parseArgs(argv) {
     if (i < startIndex) {
       continue;
     }
-    if (arg === "--lane") {
+    if (arg === "--project") {
+      options.project = String(args[++i] || "").trim();
+    } else if (arg === "--lane") {
       options.lane = sanitizeLaneName(args[++i]);
     } else if (arg === "--run") {
       options.runId = sanitizeAdhocRunId(args[++i]);
@@ -228,11 +230,12 @@ function parseArgs(argv) {
   return { help: false, surface, operation, action, options };
 }
 
-function resolveLaneForRun(runId, fallbackLane) {
-  return (
-    readJsonOrNull(path.join(REPO_ROOT, ".wave", "adhoc", "runs", runId, "result.json"))?.lane ||
-    fallbackLane
-  );
+function resolveRunContext(runId, fallbackProject, fallbackLane) {
+  const record = findAdhocRunRecord(runId);
+  return {
+    project: record?.project || fallbackProject,
+    lane: record?.result?.lane || fallbackLane,
+  };
 }
 
 function loadWave(lanePaths, waveNumber) {
@@ -955,9 +958,12 @@ export async function runControlCli(argv) {
     throw new Error("Expected control surface: status | telemetry | task | rerun | proof");
   }
   if (options.runId) {
-    options.lane = resolveLaneForRun(options.runId, options.lane);
+    const context = resolveRunContext(options.runId, options.project, options.lane);
+    options.project = context.project;
+    options.lane = context.lane;
   }
   const lanePaths = buildLanePaths(options.lane, {
+    project: options.project || undefined,
     runVariant: options.dryRun ? "dry-run" : undefined,
     adhocRunId: options.runId || null,
   });

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

@@ -35,22 +35,21 @@ import { writeAssignmentSnapshot, writeDependencySnapshot } from "./artifact-sch
 import {
   buildLanePaths,
   ensureDirectory,
+  findAdhocRunRecord,
   parseNonNegativeInt,
-  readJsonOrNull,
-  REPO_ROOT,
   sanitizeAdhocRunId,
 } from "./shared.mjs";
 import { parseWaveFiles } from "./wave-files.mjs";
 
 function printUsage() {
   console.log(`Usage:
-  wave coord post --lane <lane> --wave <n> --agent <id> --kind <kind> --summary <text> [--dry-run] [options]
-  wave coord show --lane <lane> --wave <n> [--dry-run] [--json]
-  wave coord render --lane <lane> --wave <n> [--dry-run]
-  wave coord inbox --lane <lane> --wave <n> --agent <id> [--dry-run]
-  wave coord explain --lane <lane> --wave <n> [--agent <id>] [--json]
-  wave coord act <resolve|dismiss|reroute|reassign|escalate|answer-human> --lane <lane> --wave <n> [options]
-  wave coord <subcommand> --run <id> [--wave 0] ...
+  wave coord post --project <id> --lane <lane> --wave <n> --agent <id> --kind <kind> --summary <text> [--dry-run] [options]
+  wave coord show --project <id> --lane <lane> --wave <n> [--dry-run] [--json]
+  wave coord render --project <id> --lane <lane> --wave <n> [--dry-run]
+  wave coord inbox --project <id> --lane <lane> --wave <n> --agent <id> [--dry-run]
+  wave coord explain --project <id> --lane <lane> --wave <n> [--agent <id>] [--json]
+  wave coord act <resolve|dismiss|reroute|reassign|escalate|answer-human> --project <id> --lane <lane> --wave <n> [options]
+  wave coord <subcommand> --run <id> [--project <id>] [--wave 0] ...
 `);
 }
 
@@ -58,6 +57,7 @@ function parseArgs(argv) {
   const args = argv[0] === "--" ? argv.slice(1) : argv;
   const subcommand = String(args[0] || "").trim().toLowerCase();
   const options = {
+    project: "",
     lane: "main",
     wave: null,
     runId: "",
@@ -85,7 +85,9 @@ function parseArgs(argv) {
   }
   for (let i = startIndex; i < args.length; i += 1) {
     const arg = args[i];
-    if (arg === "--lane") {
+    if (arg === "--project") {
+      options.project = String(args[++i] || "").trim();
+    } else if (arg === "--lane") {
       options.lane = String(args[++i] || "").trim();
     } else if (arg === "--run") {
       options.runId = sanitizeAdhocRunId(args[++i]);
@@ -131,9 +133,12 @@ function parseArgs(argv) {
   return { subcommand, options };
 }
 
-function resolveLaneForRun(runId, fallbackLane) {
-  const resultPath = path.join(REPO_ROOT, ".wave", "adhoc", "runs", runId, "result.json");
-  return readJsonOrNull(resultPath)?.lane || fallbackLane;
+function resolveRunContext(runId, fallbackProject, fallbackLane) {
+  const record = findAdhocRunRecord(runId);
+  return {
+    project: record?.project || fallbackProject,
+    lane: record?.result?.lane || fallbackLane,
+  };
 }
 
 function loadWave(lanePaths, waveNumber) {
@@ -329,9 +334,12 @@ export async function runCoordinationCli(argv) {
   }
   const { subcommand, options } = parseArgs(argv);
   if (options.runId) {
-    options.lane = resolveLaneForRun(options.runId, options.lane);
+    const context = resolveRunContext(options.runId, options.project, options.lane);
+    options.project = context.project;
+    options.lane = context.lane;
   }
   const lanePaths = buildLanePaths(options.lane, {
+    project: options.project || undefined,
     runVariant: options.dryRun ? "dry-run" : undefined,
     adhocRunId: options.runId || null,
   });

package/scripts/wave-orchestrator/coordination-store.mjs

@@ -242,8 +242,11 @@ export function normalizeCoordinationRecord(rawRecord, defaults = {}) {
         : Number.parseInt(String(rawRecord.attempt), 10),
     source: normalizeString(rawRecord.source ?? defaults.source, "launcher"),
     executorId: normalizeString(rawRecord.executorId ?? defaults.executorId, ""),
+    project: normalizeString(rawRecord.project ?? defaults.project, ""),
     requesterLane: normalizeString(rawRecord.requesterLane ?? defaults.requesterLane, ""),
     ownerLane: normalizeString(rawRecord.ownerLane ?? defaults.ownerLane, ""),
+    requesterProject: normalizeString(rawRecord.requesterProject ?? defaults.requesterProject, ""),
+    ownerProject: normalizeString(rawRecord.ownerProject ?? defaults.ownerProject, ""),
     requesterWave:
       rawRecord.requesterWave === null || rawRecord.requesterWave === undefined || rawRecord.requesterWave === ""
         ? defaults.requesterWave ?? null
@@ -264,8 +267,10 @@ export function appendCoordinationRecord(filePath, rawRecord, defaults = {}) {
   ensureDirectory(path.dirname(filePath));
   fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, "utf8");
   const runIdHint = normalizeString(rawRecord?.runId ?? defaults.runId, "");
+  const projectHint = normalizeString(rawRecord?.project ?? defaults.project, "");
   try {
     const lanePaths = buildLanePaths(record.lane, {
+      ...(projectHint ? { project: projectHint } : {}),
       ...(runIdHint ? { adhocRunId: runIdHint } : {}),
     });
     if (lanePaths?.waveControl?.captureCoordinationRecords !== false) {
@@ -301,8 +306,11 @@ export function appendCoordinationRecord(filePath, rawRecord, defaults = {}) {
           closureCondition: record.closureCondition,
           required: record.required,
           executorId: record.executorId || null,
+          project: record.project || null,
           requesterLane: record.requesterLane || null,
           ownerLane: record.ownerLane || null,
+          requesterProject: record.requesterProject || null,
+          ownerProject: record.ownerProject || null,
         },
       });
     }

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

@@ -36,6 +36,7 @@ function normalizeDashboardAttachTarget(value) {
 
 export function parseDashboardArgs(argv) {
   const options = {
+    project: null,
     lane: DEFAULT_WAVE_LANE,
     dashboardFile: null,
     messageBoard: null,
@@ -50,6 +51,8 @@ export function parseDashboardArgs(argv) {
     }
     if (arg === "--watch") {
       options.watch = true;
+    } else if (arg === "--project") {
+      options.project = String(argv[++i] || "").trim() || null;
     } else if (arg === "--lane") {
       options.lane =
         String(argv[++i] || "")
@@ -98,9 +101,12 @@ function tmuxSessionExists(socketName, sessionName) {
   throw new Error((result.stderr || result.stdout || "tmux has-session failed").trim());
 }
 
-function attachDashboardSession(lane, target) {
+function attachDashboardSession(project, lane, target) {
   const config = loadWaveConfig();
-  const lanePaths = buildLanePaths(lane, { config });
+  const lanePaths = buildLanePaths(lane, {
+    config,
+    project: project || config.defaultProject,
+  });
   const entry =
     target === "global"
       ? createGlobalDashboardTerminalEntry(lanePaths, "current")
@@ -449,6 +455,7 @@ export async function runDashboardCli(argv) {
     console.log(`Usage: pnpm exec wave dashboard --dashboard-file <path> [options]
 
 Options:
+  --project <id>          Project id (default: config default)
   --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
@@ -461,7 +468,7 @@ Options:
   }
 
   if (options.attach) {
-    attachDashboardSession(options.lane, options.attach);
+    attachDashboardSession(options.project, options.lane, options.attach);
     return;
   }