@chllming/wave-orchestration 0.6.1 → 0.6.3

package/scripts/wave-orchestrator/launcher.mjs

@@ -81,6 +81,7 @@ import {
   writeTextAtomic,
 } from "./shared.mjs";
 import {
+  createCurrentWaveDashboardTerminalEntry,
   appendTerminalEntries,
   createGlobalDashboardTerminalEntry,
   createTemporaryTerminalEntries,
@@ -97,6 +98,7 @@ import {
   commandForExecutor,
   isExecutorCommandAvailable,
 } from "./executors.mjs";
+import { maybeAnnouncePackageUpdate } from "./package-update-notice.mjs";
 import {
   agentRequiresProofCentricValidation,
   buildRunStateEvidence,
@@ -1449,11 +1451,94 @@ export function readWaveImplementationGate(wave, agentRuns) {
   };
 }
 
+function analyzePromotedComponentOwners(componentId, agentRuns, summariesByAgentId) {
+  const ownerRuns = (agentRuns || []).filter((runInfo) =>
+    runInfo.agent.components?.includes(componentId),
+  );
+  const ownerAgentIds = ownerRuns.map((runInfo) => runInfo.agent.agentId);
+  const satisfiedAgentIds = [];
+  const waitingOnAgentIds = [];
+  const failedOwnContractAgentIds = [];
+  for (const runInfo of ownerRuns) {
+    const summary = summariesByAgentId?.[runInfo.agent.agentId] || null;
+    const implementationValidation = validateImplementationSummary(runInfo.agent, summary);
+    const componentMarkers = new Map(
+      Array.isArray(summary?.components)
+        ? summary.components.map((component) => [component.componentId, component])
+        : [],
+    );
+    const marker = componentMarkers.get(componentId);
+    const expectedLevel = runInfo.agent.componentTargets?.[componentId] || null;
+    const componentSatisfied =
+      marker &&
+      marker.state === "met" &&
+      (!expectedLevel || marker.level === expectedLevel);
+    if (implementationValidation.ok && componentSatisfied) {
+      satisfiedAgentIds.push(runInfo.agent.agentId);
+      continue;
+    }
+    waitingOnAgentIds.push(runInfo.agent.agentId);
+    if (!implementationValidation.ok) {
+      failedOwnContractAgentIds.push(runInfo.agent.agentId);
+    }
+  }
+  return {
+    componentId,
+    ownerRuns,
+    ownerAgentIds,
+    satisfiedAgentIds,
+    waitingOnAgentIds,
+    failedOwnContractAgentIds,
+  };
+}
+
+function buildSharedComponentSiblingPendingFailure(componentState) {
+  if (
+    !componentState ||
+    componentState.satisfiedAgentIds.length === 0 ||
+    componentState.waitingOnAgentIds.length === 0
+  ) {
+    return null;
+  }
+  const landedSummary =
+    componentState.satisfiedAgentIds.length === 1
+      ? `${componentState.satisfiedAgentIds[0]} desired-state slice landed`
+      : `${componentState.satisfiedAgentIds.join(", ")} desired-state slices landed`;
+  const ownerRun =
+    componentState.ownerRuns.find((runInfo) =>
+      componentState.waitingOnAgentIds.includes(runInfo.agent.agentId),
+    ) ||
+    componentState.ownerRuns[0] ||
+    null;
+  return {
+    ok: false,
+    agentId: componentState.waitingOnAgentIds[0] || ownerRun?.agent?.agentId || null,
+    componentId: componentState.componentId || null,
+    statusCode: "shared-component-sibling-pending",
+    detail: `${landedSummary}; shared component closure still depends on ${componentState.waitingOnAgentIds.join("/")}.`,
+    logPath: ownerRun ? path.relative(REPO_ROOT, ownerRun.logPath) : null,
+    ownerAgentIds: componentState.ownerAgentIds,
+    satisfiedAgentIds: componentState.satisfiedAgentIds,
+    waitingOnAgentIds: componentState.waitingOnAgentIds,
+    failedOwnContractAgentIds: componentState.failedOwnContractAgentIds,
+  };
+}
+
 export function readWaveComponentGate(wave, agentRuns, options = {}) {
   const summariesByAgentId = Object.fromEntries(
     agentRuns.map((runInfo) => [runInfo.agent.agentId, readRunExecutionSummary(runInfo, wave)]),
   );
   const validation = validateWaveComponentPromotions(wave, summariesByAgentId, options);
+  const sharedPending = (wave.componentPromotions || [])
+    .map((promotion) =>
+      buildSharedComponentSiblingPendingFailure(
+        analyzePromotedComponentOwners(promotion.componentId, agentRuns, summariesByAgentId),
+      ),
+    )
+    .find(Boolean);
+  if (sharedPending) {
+    return sharedPending;
+  }
   if (validation.ok) {
     return {
       ok: true,
@@ -1464,8 +1549,12 @@ export function readWaveComponentGate(wave, agentRuns, options = {}) {
       logPath: null,
     };
   }
-  const ownerRun =
-    agentRuns.find((runInfo) => runInfo.agent.components?.includes(validation.componentId)) ?? null;
+  const componentState = analyzePromotedComponentOwners(
+    validation.componentId,
+    agentRuns,
+    summariesByAgentId,
+  );
+  const ownerRun = componentState.ownerRuns[0] ?? null;
   return {
     ok: false,
     agentId: ownerRun?.agent?.agentId || null,
@@ -1473,6 +1562,10 @@ export function readWaveComponentGate(wave, agentRuns, options = {}) {
     statusCode: validation.statusCode,
     detail: validation.detail,
     logPath: ownerRun ? path.relative(REPO_ROOT, ownerRun.logPath) : null,
+    ownerAgentIds: componentState.ownerAgentIds,
+    satisfiedAgentIds: componentState.satisfiedAgentIds,
+    waitingOnAgentIds: componentState.waitingOnAgentIds,
+    failedOwnContractAgentIds: componentState.failedOwnContractAgentIds,
   };
 }
 
@@ -1799,6 +1892,38 @@ function removeOrphanWaveDashboards(lanePaths, activeSessionNames) {
   return removedDashboardPaths;
 }
 
+function pruneDryRunExecutorPreviewDirs(lanePaths, waves) {
+  if (!fs.existsSync(lanePaths.executorOverlaysDir)) {
+    return [];
+  }
+  const expectedSlugsByWave = new Map(
+    (waves || []).map((wave) => [wave.wave, new Set((wave.agents || []).map((agent) => agent.slug))]),
+  );
+  const removedPaths = [];
+  for (const entry of fs.readdirSync(lanePaths.executorOverlaysDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^wave-\d+$/.test(entry.name)) {
+      continue;
+    }
+    const waveNumber = Number.parseInt(entry.name.slice("wave-".length), 10);
+    const waveDir = path.join(lanePaths.executorOverlaysDir, entry.name);
+    const expectedSlugs = expectedSlugsByWave.get(waveNumber);
+    if (!expectedSlugs) {
+      fs.rmSync(waveDir, { recursive: true, force: true });
+      removedPaths.push(path.relative(REPO_ROOT, waveDir));
+      continue;
+    }
+    for (const child of fs.readdirSync(waveDir, { withFileTypes: true })) {
+      if (!child.isDirectory() || expectedSlugs.has(child.name)) {
+        continue;
+      }
+      const childPath = path.join(waveDir, child.name);
+      fs.rmSync(childPath, { recursive: true, force: true });
+      removedPaths.push(path.relative(REPO_ROOT, childPath));
+    }
+  }
+  return removedPaths.toSorted();
+}
+
 export function reconcileStaleLauncherArtifacts(lanePaths, options = {}) {
   const outcome = {
     removedLock: false,
@@ -2162,9 +2287,63 @@ function relaunchReasonBuckets(runs, failures, derivedState) {
     closureGate: (failures || []).some(
       (failure) => failure.agentId && selectedAgentIds.has(failure.agentId),
     ),
+    sharedComponentSiblingWait: (failures || []).some(
+      (failure) =>
+        failure.statusCode === "shared-component-sibling-pending" &&
+        (failure.waitingOnAgentIds || []).some((agentId) => selectedAgentIds.has(agentId)),
+    ),
   };
 }
 
+function applySharedComponentWaitStateToDashboard(componentGate, dashboardState) {
+  const waitingSummary = (componentGate?.waitingOnAgentIds || []).join("/");
+  if (!waitingSummary) {
+    return;
+  }
+  for (const agentId of componentGate?.satisfiedAgentIds || []) {
+    setWaveDashboardAgent(dashboardState, agentId, {
+      state: "completed",
+      detail: `Desired-state slice landed; waiting on ${waitingSummary} for shared component closure`,
+    });
+  }
+}
+
+function reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures) {
+  if (!Array.isArray(failures) || failures.length === 0) {
+    return failures;
+  }
+  const summariesByAgentId = Object.fromEntries(
+    (agentRuns || []).map((runInfo) => [runInfo.agent.agentId, readRunExecutionSummary(runInfo, wave)]),
+  );
+  const failureAgentIds = new Set(failures.map((failure) => failure.agentId).filter(Boolean));
+  const consumedSatisfiedAgentIds = new Set();
+  const synthesizedFailures = [];
+  for (const promotion of wave?.componentPromotions || []) {
+    const componentState = analyzePromotedComponentOwners(
+      promotion.componentId,
+      agentRuns,
+      summariesByAgentId,
+    );
+    if (
+      componentState.satisfiedAgentIds.length === 0 ||
+      componentState.waitingOnAgentIds.length === 0 ||
+      !componentState.satisfiedAgentIds.some((agentId) => failureAgentIds.has(agentId))
+    ) {
+      continue;
+    }
+    for (const agentId of componentState.satisfiedAgentIds) {
+      if (failureAgentIds.has(agentId)) {
+        consumedSatisfiedAgentIds.add(agentId);
+      }
+    }
+    synthesizedFailures.push(buildSharedComponentSiblingPendingFailure(componentState));
+  }
+  return [
+    ...synthesizedFailures.filter(Boolean),
+    ...failures.filter((failure) => !consumedSatisfiedAgentIds.has(failure.agentId)),
+  ];
+}
+
 export function hasReusableSuccessStatus(agent, statusPath, options = {}) {
   const statusRecord = readStatusRecordIfPresent(statusPath);
   const basicReuseOk = Boolean(
@@ -2272,7 +2451,11 @@ function buildFallbackExecutorState(executorState, executorId, attempt, reason)
 }
 
 function applyRetryFallbacks(agentRuns, failures, lanePaths, attemptNumber, waveDefinition = null) {
-  const failedAgentIds = new Set(failures.map((failure) => failure.agentId));
+  const failedAgentIds = new Set(
+    failures
+      .filter((failure) => failure.statusCode !== "shared-component-sibling-pending")
+      .map((failure) => failure.agentId),
+  );
   let changed = false;
   const outcomes = new Map();
   for (const run of agentRuns) {
@@ -2733,6 +2916,20 @@ export function resolveRelaunchRuns(agentRuns, failures, derivedState, lanePaths
       barrier: null,
     };
   }
+  const sharedComponentWaitingAgentIds = new Set(
+    (failures || [])
+      .filter((failure) => failure.statusCode === "shared-component-sibling-pending")
+      .flatMap((failure) => failure.waitingOnAgentIds || [])
+      .filter((agentId) => runsByAgentId.has(agentId)),
+  );
+  if (sharedComponentWaitingAgentIds.size > 0) {
+    return {
+      runs: Array.from(sharedComponentWaitingAgentIds)
+        .map((agentId) => runsByAgentId.get(agentId))
+        .filter(Boolean),
+      barrier: null,
+    };
+  }
   const failedAgentIds = new Set(failures.map((failure) => failure.agentId));
   return {
     runs: agentRuns.filter((run) => failedAgentIds.has(run.agent.agentId)),
@@ -2775,10 +2972,15 @@ export async function runLauncherCli(argv) {
     return;
   }
   const { lanePaths, options } = parsed;
+  if (!options.reconcileStatus) {
+    await maybeAnnouncePackageUpdate();
+  }
   let lockHeld = false;
   let globalDashboard = null;
   let globalDashboardTerminalEntry = null;
   let globalDashboardTerminalAppended = false;
+  let currentWaveDashboardTerminalEntry = null;
+  let currentWaveDashboardTerminalAppended = false;
   let selectedWavesForCoordination = [];
 
   const appendCoordination = ({
@@ -2976,6 +3178,7 @@ export async function runLauncherCli(argv) {
     });
 
     if (options.dryRun) {
+      pruneDryRunExecutorPreviewDirs(lanePaths, allWaves);
       for (const wave of filteredWaves) {
         const derivedState = writeWaveDerivedState({
           lanePaths,
@@ -3072,9 +3275,14 @@ export async function runLauncherCli(argv) {
         lanePaths,
         globalDashboard.runId || "global",
       );
+      currentWaveDashboardTerminalEntry = createCurrentWaveDashboardTerminalEntry(lanePaths);
       if (terminalRegistryEnabled) {
-        appendTerminalEntries(lanePaths.terminalsPath, [globalDashboardTerminalEntry]);
+        appendTerminalEntries(lanePaths.terminalsPath, [
+          globalDashboardTerminalEntry,
+          currentWaveDashboardTerminalEntry,
+        ]);
         globalDashboardTerminalAppended = true;
+        currentWaveDashboardTerminalAppended = true;
       }
       launchWaveDashboardSession(lanePaths, {
         sessionName: globalDashboardTerminalEntry.sessionName,
@@ -3152,7 +3360,7 @@ export async function runLauncherCli(argv) {
           wave.wave,
           wave.agents,
           runTag,
-          options.dashboard,
+          false,
         );
         if (terminalRegistryEnabled) {
           appendTerminalEntries(lanePaths.terminalsPath, terminalEntries);
@@ -3265,12 +3473,9 @@ export async function runLauncherCli(argv) {
         }
         flushDashboards();
 
-        const dashboardEntry = terminalEntries.find(
-          (entry) => entry.terminalName === `${lanePaths.dashboardTerminalNamePrefix}${wave.wave}`,
-        );
-        if (options.dashboard && dashboardEntry) {
+        if (options.dashboard && currentWaveDashboardTerminalEntry) {
           launchWaveDashboardSession(lanePaths, {
-            sessionName: dashboardEntry.sessionName,
+            sessionName: currentWaveDashboardTerminalEntry.sessionName,
             dashboardPath,
             messageBoardPath,
           });
@@ -3442,6 +3647,12 @@ export async function runLauncherCli(argv) {
 
           materializeAgentExecutionSummaries(wave, agentRuns);
           refreshDerivedState(attempt);
+          failures = reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures);
+          for (const failure of failures) {
+            if (failure.statusCode === "shared-component-sibling-pending") {
+              applySharedComponentWaitStateToDashboard(failure, dashboardState);
+            }
+          }
 
           if (failures.length > 0) {
             for (const failure of failures) {
@@ -3483,12 +3694,20 @@ export async function runLauncherCli(argv) {
                 laneProfile: lanePaths.laneProfile,
               });
               if (!componentGate.ok) {
+                if (componentGate.statusCode === "shared-component-sibling-pending") {
+                  applySharedComponentWaitStateToDashboard(componentGate, dashboardState);
+                }
                 failures = [
                   {
                     agentId: componentGate.agentId,
                     statusCode: componentGate.statusCode,
                     logPath:
                       componentGate.logPath || path.relative(REPO_ROOT, messageBoardPath),
+                    detail: componentGate.detail,
+                    ownerAgentIds: componentGate.ownerAgentIds || [],
+                    satisfiedAgentIds: componentGate.satisfiedAgentIds || [],
+                    waitingOnAgentIds: componentGate.waitingOnAgentIds || [],
+                    failedOwnContractAgentIds: componentGate.failedOwnContractAgentIds || [],
                   },
                 ];
                 recordCombinedEvent({
@@ -4045,6 +4264,9 @@ export async function runLauncherCli(argv) {
           if (globalDashboardTerminalEntry) {
             excludeSessionNames.add(globalDashboardTerminalEntry.sessionName);
           }
+          if (currentWaveDashboardTerminalEntry) {
+            excludeSessionNames.add(currentWaveDashboardTerminalEntry.sessionName);
+          }
           cleanupLaneTmuxSessions(lanePaths, { excludeSessionNames });
         }
         if (globalWave && globalWave.status === "running") {
@@ -4079,6 +4301,13 @@ export async function runLauncherCli(argv) {
     if (globalDashboardTerminalAppended && globalDashboardTerminalEntry && !options.keepTerminals) {
       removeTerminalEntries(lanePaths.terminalsPath, [globalDashboardTerminalEntry]);
     }
+    if (
+      currentWaveDashboardTerminalAppended &&
+      currentWaveDashboardTerminalEntry &&
+      !options.keepTerminals
+    ) {
+      removeTerminalEntries(lanePaths.terminalsPath, [currentWaveDashboardTerminalEntry]);
+    }
     if (options.cleanupSessions && globalDashboardTerminalEntry) {
       try {
         killTmuxSessionIfExists(lanePaths.tmuxSocketName, globalDashboardTerminalEntry.sessionName);
@@ -4086,6 +4315,16 @@ export async function runLauncherCli(argv) {
         // no-op
       }
     }
+    if (options.cleanupSessions && currentWaveDashboardTerminalEntry) {
+      try {
+        killTmuxSessionIfExists(
+          lanePaths.tmuxSocketName,
+          currentWaveDashboardTerminalEntry.sessionName,
+        );
+      } catch {
+        // no-op
+      }
+    }
     if (lockHeld) {
       releaseLauncherLock(lanePaths.launcherLockPath);
     }

package/scripts/wave-orchestrator/package-update-notice.mjs

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDirectory, readJsonOrNull, REPO_ROOT, writeJsonAtomic } from "./shared.mjs";
+import {
+  compareVersions,
+  readInstalledPackageMetadata,
+  WAVE_PACKAGE_NAME,
+} from "./package-version.mjs";
+
+export const PACKAGE_UPDATE_CHECK_SCHEMA_VERSION = 1;
+export const PACKAGE_UPDATE_CHECK_PATH = path.join(REPO_ROOT, ".wave", "package-update-check.json");
+export const PACKAGE_UPDATE_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
+export const PACKAGE_UPDATE_CHECK_TIMEOUT_MS = 2000;
+export const WAVE_SKIP_UPDATE_CHECK_ENV = "WAVE_SKIP_UPDATE_CHECK";
+export const WAVE_SUPPRESS_UPDATE_NOTICE_ENV = "WAVE_SUPPRESS_UPDATE_NOTICE";
+export const NPM_REGISTRY_LATEST_URL = "https://registry.npmjs.org";
+
+function isTruthyEnvValue(value) {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function parsePackageManagerId(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (normalized.startsWith("pnpm@")) {
+    return "pnpm";
+  }
+  if (normalized.startsWith("npm@")) {
+    return "npm";
+  }
+  if (normalized.startsWith("yarn@")) {
+    return "yarn";
+  }
+  if (normalized.startsWith("bun@")) {
+    return "bun";
+  }
+  return null;
+}
+
+function runtimeSelfUpdateCommand(workspaceRoot = REPO_ROOT) {
+  const workspacePackage = readJsonOrNull(path.join(workspaceRoot, "package.json"));
+  const packageManagerId = parsePackageManagerId(workspacePackage?.packageManager);
+  if (packageManagerId === "pnpm") {
+    return "pnpm exec wave self-update";
+  }
+  if (packageManagerId === "npm") {
+    return "npm exec -- wave self-update";
+  }
+  if (packageManagerId === "yarn") {
+    return "yarn exec wave self-update";
+  }
+  if (packageManagerId === "bun") {
+    return "bun x wave self-update";
+  }
+  if (fs.existsSync(path.join(workspaceRoot, "pnpm-lock.yaml"))) {
+    return "pnpm exec wave self-update";
+  }
+  if (fs.existsSync(path.join(workspaceRoot, "yarn.lock"))) {
+    return "yarn exec wave self-update";
+  }
+  if (fs.existsSync(path.join(workspaceRoot, "bun.lock")) || fs.existsSync(path.join(workspaceRoot, "bun.lockb"))) {
+    return "bun x wave self-update";
+  }
+  return "npm exec -- wave self-update";
+}
+
+function buildPackageLatestUrl(packageName) {
+  return `${NPM_REGISTRY_LATEST_URL}/${encodeURIComponent(String(packageName || WAVE_PACKAGE_NAME)).replace("%40", "@")}/latest`;
+}
+
+function readUpdateCheckCache(cachePath = PACKAGE_UPDATE_CHECK_PATH) {
+  const payload = readJsonOrNull(cachePath);
+  return payload && typeof payload === "object" ? payload : null;
+}
+
+function writeUpdateCheckCache(cachePath, payload) {
+  ensureDirectory(path.dirname(cachePath));
+  writeJsonAtomic(cachePath, payload);
+}
+
+function buildNoticeLines(packageName, currentVersion, latestVersion, workspaceRoot = REPO_ROOT) {
+  return [
+    `[wave:update] newer ${packageName} available: installed ${currentVersion}, latest ${latestVersion}`,
+    `[wave:update] update now with: ${runtimeSelfUpdateCommand(workspaceRoot)}`,
+  ];
+}
+
+function emitNotice(packageName, currentVersion, latestVersion, emit = console.error, workspaceRoot = REPO_ROOT) {
+  for (const line of buildNoticeLines(packageName, currentVersion, latestVersion, workspaceRoot)) {
+    emit(line);
+  }
+}
+
+export async function fetchLatestPackageVersion(
+  packageName = WAVE_PACKAGE_NAME,
+  {
+    fetchImpl = globalThis.fetch,
+    timeoutMs = PACKAGE_UPDATE_CHECK_TIMEOUT_MS,
+  } = {},
+) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Package update check is unavailable in this Node runtime.");
+  }
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(buildPackageLatestUrl(packageName), {
+      signal: abortController.signal,
+      headers: {
+        Accept: "application/json",
+      },
+    });
+    if (!response?.ok) {
+      throw new Error(`Upstream package check failed with status ${response?.status || "unknown"}.`);
+    }
+    const payload = await response.json();
+    const latestVersion = String(payload?.version || "").trim();
+    if (!latestVersion) {
+      throw new Error("Upstream package check returned no version.");
+    }
+    return latestVersion;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function maybeAnnouncePackageUpdate(options = {}) {
+  const env = options.env || process.env;
+  if (
+    isTruthyEnvValue(env[WAVE_SKIP_UPDATE_CHECK_ENV]) ||
+    isTruthyEnvValue(env[WAVE_SUPPRESS_UPDATE_NOTICE_ENV])
+  ) {
+    return {
+      skipped: true,
+      reason: "disabled",
+      updateAvailable: false,
+      latestVersion: null,
+      currentVersion: null,
+    };
+  }
+
+  const metadata = options.packageMetadata || readInstalledPackageMetadata();
+  const packageName = String(metadata.name || WAVE_PACKAGE_NAME);
+  const currentVersion = String(metadata.version || "").trim();
+  const cachePath = options.cachePath || PACKAGE_UPDATE_CHECK_PATH;
+  const workspaceRoot = options.workspaceRoot || REPO_ROOT;
+  const cacheTtlMs = options.cacheTtlMs ?? PACKAGE_UPDATE_CHECK_TTL_MS;
+  const nowMs = options.nowMs ?? Date.now();
+  const emit = options.emit || console.error;
+  const cache = readUpdateCheckCache(cachePath);
+  const cachedCheckedAtMs = Date.parse(String(cache?.checkedAt || ""));
+  const cacheMatchesCurrentVersion = cache?.currentVersion === currentVersion;
+  const cachedUpdateAvailable =
+    cacheMatchesCurrentVersion &&
+    typeof cache?.latestVersion === "string" &&
+    compareVersions(cache.latestVersion, currentVersion) > 0;
+  const cacheFresh =
+    cacheMatchesCurrentVersion &&
+    Number.isFinite(cachedCheckedAtMs) &&
+    nowMs - cachedCheckedAtMs <= cacheTtlMs;
+  let emitted = false;
+
+  if (cachedUpdateAvailable) {
+    emitNotice(packageName, currentVersion, cache.latestVersion, emit, workspaceRoot);
+    emitted = true;
+  }
+
+  if (cacheFresh) {
+    return {
+      skipped: false,
+      source: "cache",
+      updateAvailable: cachedUpdateAvailable,
+      latestVersion: cache?.latestVersion || currentVersion,
+      currentVersion,
+    };
+  }
+
+  try {
+    const latestVersion = await fetchLatestPackageVersion(packageName, options);
+    const updateAvailable = compareVersions(latestVersion, currentVersion) > 0;
+    writeUpdateCheckCache(cachePath, {
+      schemaVersion: PACKAGE_UPDATE_CHECK_SCHEMA_VERSION,
+      packageName,
+      checkedAt: new Date(nowMs).toISOString(),
+      currentVersion,
+      latestVersion,
+      updateAvailable,
+      lastErrorAt: null,
+      lastErrorMessage: null,
+    });
+    if (updateAvailable && !emitted) {
+      emitNotice(packageName, currentVersion, latestVersion, emit, workspaceRoot);
+    }
+    return {
+      skipped: false,
+      source: "network",
+      updateAvailable,
+      latestVersion,
+      currentVersion,
+    };
+  } catch (error) {
+    writeUpdateCheckCache(cachePath, {
+      schemaVersion: PACKAGE_UPDATE_CHECK_SCHEMA_VERSION,
+      packageName,
+      checkedAt: new Date(nowMs).toISOString(),
+      currentVersion,
+      latestVersion:
+        cacheMatchesCurrentVersion && typeof cache?.latestVersion === "string"
+          ? cache.latestVersion
+          : currentVersion,
+      updateAvailable: cachedUpdateAvailable,
+      lastErrorAt: new Date(nowMs).toISOString(),
+      lastErrorMessage: error instanceof Error ? error.message : String(error),
+    });
+    return {
+      skipped: false,
+      source: "error",
+      updateAvailable: cachedUpdateAvailable,
+      latestVersion:
+        cacheMatchesCurrentVersion && typeof cache?.latestVersion === "string"
+          ? cache.latestVersion
+          : currentVersion,
+      currentVersion,
+    };
+  }
+}

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

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { PACKAGE_ROOT, readJsonOrNull } from "./shared.mjs";
+
+export const WAVE_PACKAGE_NAME = "@chllming/wave-orchestration";
+export const PACKAGE_METADATA_PATH = path.join(PACKAGE_ROOT, "package.json");
+
+export function readInstalledPackageMetadata(metadataPath = PACKAGE_METADATA_PATH) {
+  const payload = readJsonOrNull(metadataPath);
+  if (!payload?.name || !payload?.version) {
+    throw new Error(`Invalid package metadata: ${metadataPath}`);
+  }
+  return payload;
+}
+
+function normalizeVersionParts(version) {
+  return String(version || "")
+    .split(".")
+    .map((part) => Number.parseInt(part.replace(/[^0-9].*$/, ""), 10) || 0);
+}
+
+export function compareVersions(a, b) {
+  const left = normalizeVersionParts(a);
+  const right = normalizeVersionParts(b);
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (left[index] || 0) - (right[index] || 0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return 0;
+}