@chllming/wave-orchestration 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.6.3 - 2026-03-22
+
+- Added a best-effort npmjs update notice on `wave launch`, `wave autonomous`, and `wave adhoc run`, with cached lookup state under `.wave/package-update-check.json` and opt-out via `WAVE_SKIP_UPDATE_CHECK=1`.
+- Added `wave self-update`, which detects the workspace package manager, updates `@chllming/wave-orchestration`, prints the changelog delta since the recorded install, and then runs `wave upgrade`.
+- Suppressed duplicate notices for nested launcher calls so autonomous and ad-hoc runs announce at most once, while keeping JSON-oriented stdout surfaces clean by emitting notices on stderr.
+- Documented the new update flow and added regression coverage for notice caching, package-manager-aware self-update, and nested-launch suppression.
+
 ## 0.6.2 - 2026-03-22
 
 - Added first-class `claude.effort` support across config profiles, lane overrides, and per-agent `### Executor` blocks, and now emit `--effort` in Claude launch previews and live runs.

package/README.md

@@ -75,17 +75,16 @@ Wave is built to mitigate those failures with canonical shared state, generated
 
 Current release:
 
-- `@chllming/wave-orchestration@0.6.2`
-- Release tag: [`v0.6.2`](https://github.com/chllming/wave-orchestration/releases/tag/v0.6.2)
+- `@chllming/wave-orchestration@0.6.3`
+- Release tag: [`v0.6.3`](https://github.com/chllming/wave-orchestration/releases/tag/v0.6.3)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.6.2`:
+Highlights in `0.6.3`:
 
-- Runtime previews and docs now expose first-class Claude effort plus structured limit metadata, making known Claude/OpenCode ceilings explicit and Codex opacity explicit.
-- The global dashboard and VS Code terminal surfaces are easier to read: active vs pending counts are distinct, the current-wave dashboard keeps a stable terminal name, and TTY dashboards now use simple color cues.
-- Dry-run executor preview directories now prune stale agent folders when a wave shrinks.
-- Shared promoted-component retries now preserve already-landed owner slices and relaunch only the sibling owners still needed for closure.
+- Runtime launch entrypoints now check npmjs for a newer published package in the background, cache the result under `.wave/package-update-check.json`, and warn on stderr when the workspace is behind.
+- `wave self-update` now gives downstream repos a one-command update path that detects the workspace package manager, updates the dependency, shows the changelog delta, and records the workspace upgrade report.
+- Autonomous and ad-hoc flows suppress nested notices so operators see at most one update banner per top-level run, and structured stdout remains clean for JSON consumers.
 
 Requirements:
 
@@ -113,6 +112,8 @@ pnpm exec wave init --adopt-existing
 
 Fresh init also seeds a starter `skills/` library plus `docs/evals/benchmark-catalog.json`. The launcher projects those skill bundles into Codex, Claude, OpenCode, and local executor overlays after the final runtime for each agent is resolved, and waves that include `cont-EVAL` can declare `## Eval targets` against that catalog.
 
+When runtime launch commands detect a newer npmjs release, Wave prints a non-blocking update notice on stderr. The fast path is `pnpm exec wave self-update`, which updates the dependency, prints the changelog delta, and then records the workspace upgrade report.
+
 ## Common Commands
 
 ```bash
@@ -129,6 +130,9 @@ pnpm exec wave dep show --lane main --wave 0 --json
 
 # Run autonomous mode after the wave set is stable
 pnpm exec wave autonomous --lane main --executor codex --codex-sandbox danger-full-access
+
+# Pull the latest published package and record the workspace upgrade
+pnpm exec wave self-update
 ```
 
 ## Develop This Package

package/docs/plans/current-state.md

@@ -1,8 +1,9 @@
 # Current State
 
-- The starter workspace in this source repo reflects the `0.6.1` package release surface.
+- The starter workspace in this source repo reflects the `0.6.3` package release surface.
 - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
 - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
+- Runtime launch entrypoints now perform a best-effort npmjs version check, cache the result under `.wave/package-update-check.json`, and point operators at `pnpm exec wave self-update` when a newer published package exists.
 - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.
 - The default lane is `main`.
 - Planner foundation is now shipped:

package/docs/plans/wave-orchestrator.md

@@ -54,6 +54,7 @@ This runbook is the operational view of the architecture:
 - `pnpm exec wave dep show --lane main --wave 0 --json`
 - `pnpm exec wave dep post --owner-lane main --requester-lane release --owner-wave 0 --requester-wave 2 --agent launcher --summary "Need shared-plan reconciliation" --target capability:docs-shared-plan --required`
 - `pnpm exec wave upgrade`
+- `pnpm exec wave self-update`
 
 ## Configuration
 
@@ -151,6 +152,16 @@ Required inbound dependencies block autonomous next-wave start and lane finaliza
 
 ## Upgrade Flow
 
+Fast path:
+
+```bash
+pnpm exec wave self-update
+```
+
+That command updates the dependency through the workspace package manager, prints the changelog delta since the recorded install, and then runs `wave upgrade` to record the new install-state and upgrade report.
+
+Manual path:
+
 1. Upgrade the package version:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,6 +2,21 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.6.3",
+      "date": "2026-03-22",
+      "summary": "Runtime npmjs update notices plus a one-command self-update flow for downstream repos.",
+      "features": [
+        "Top-level runtime entrypoints now perform a best-effort npmjs version check, cache the result under `.wave/package-update-check.json`, and emit a non-blocking stderr notice when a newer `@chllming/wave-orchestration` release is available.",
+        "New `wave self-update` detects the workspace package manager, updates the package dependency to the latest published release, prints the changelog delta since the recorded install, and then runs `wave upgrade`.",
+        "Autonomous and ad-hoc flows now suppress nested update notices so operators see at most one banner per top-level run, while structured stdout such as `wave adhoc run --json` remains parseable."
+      ],
+      "manualSteps": [
+        "No migration is required. If you prefer not to check npmjs at runtime on a workstation, set `WAVE_SKIP_UPDATE_CHECK=1` in that shell environment.",
+        "After upgrading, try `pnpm exec wave self-update` once in an adopted repo to confirm the workspace package manager and install-state workflow behave the way you expect."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.6.2",
       "date": "2026-03-22",

package/scripts/wave-autonomous.mjs

@@ -5,9 +5,7 @@ import { bootstrapWaveArgs } from "./wave-cli-bootstrap.mjs";
 const argv = bootstrapWaveArgs(process.argv.slice(2));
 const { runAutonomousCli } = await import("./wave-orchestrator/autonomous.mjs");
 
-try {
-  runAutonomousCli(argv);
-} catch (error) {
+runAutonomousCli(argv).catch((error) => {
   console.error(`[wave-autonomous] ${error instanceof Error ? error.message : String(error)}`);
   process.exit(1);
-}
+});

package/scripts/wave-orchestrator/adhoc.mjs

@@ -8,6 +8,10 @@ import {
   buildDefaultProjectProfile,
   readProjectProfile,
 } from "./project-profile.mjs";
+import {
+  maybeAnnouncePackageUpdate,
+  WAVE_SUPPRESS_UPDATE_NOTICE_ENV,
+} from "./package-update-notice.mjs";
 import { runLauncherCli } from "./launcher.mjs";
 import { renderWaveMarkdown } from "./planner.mjs";
 import {
@@ -187,6 +191,20 @@ function buildAdhocRunId() {
   return sanitizeAdhocRunId(`adhoc-${stamp}-${random}`);
 }
 
+async function withSuppressedNestedUpdateNotice(fn) {
+  const previousValue = process.env[WAVE_SUPPRESS_UPDATE_NOTICE_ENV];
+  process.env[WAVE_SUPPRESS_UPDATE_NOTICE_ENV] = "1";
+  try {
+    return await fn();
+  } finally {
+    if (previousValue === undefined) {
+      delete process.env[WAVE_SUPPRESS_UPDATE_NOTICE_ENV];
+    } else {
+      process.env[WAVE_SUPPRESS_UPDATE_NOTICE_ENV] = previousValue;
+    }
+  }
+}
+
 function readEffectiveProjectProfile(config) {
   return readProjectProfile({ config }) || buildDefaultProjectProfile(config);
 }
@@ -1135,6 +1153,7 @@ export async function runAdhocCli(argv) {
     if (options.tasks.length === 0) {
       throw new Error("At least one --task is required for `wave adhoc run`.");
     }
+    await maybeAnnouncePackageUpdate();
     const stored = createStoredRun({ config, options });
     const summary = summarizePlan(stored.spec, stored.lanePaths);
     if (options.json) {
@@ -1157,17 +1176,19 @@ export async function runAdhocCli(argv) {
     writeJsonAtomic(stored.lanePaths.adhocResultPath, runningResult);
     upsertAdhocIndexEntry(stored.lanePaths.adhocIndexPath, runningResult);
     try {
-      await runLauncherCli([
-        "--lane",
-        stored.lanePaths.lane,
-        "--adhoc-run",
-        stored.lanePaths.runId,
-        "--start-wave",
-        String(ADHOC_WAVE_NUMBER),
-        "--end-wave",
-        String(ADHOC_WAVE_NUMBER),
-        ...options.launcherArgs,
-      ]);
+      await withSuppressedNestedUpdateNotice(() =>
+        runLauncherCli([
+          "--lane",
+          stored.lanePaths.lane,
+          "--adhoc-run",
+          stored.lanePaths.runId,
+          "--start-wave",
+          String(ADHOC_WAVE_NUMBER),
+          "--end-wave",
+          String(ADHOC_WAVE_NUMBER),
+          ...options.launcherArgs,
+        ]),
+      );
       const completedResult = buildResultRecord(
         stored.lanePaths,
         stored.request,

package/scripts/wave-orchestrator/autonomous.mjs

@@ -21,6 +21,10 @@ import {
   DEFAULT_CODEX_SANDBOX_MODE,
   normalizeCodexSandboxMode,
 } from "./launcher.mjs";
+import {
+  maybeAnnouncePackageUpdate,
+  WAVE_SUPPRESS_UPDATE_NOTICE_ENV,
+} from "./package-update-notice.mjs";
 import { readRunState } from "./wave-files.mjs";
 import { readDependencyTickets } from "./coordination-store.mjs";
 import { readWaveLedger } from "./ledger.mjs";
@@ -155,21 +159,30 @@ export function nextIncompleteWave(allWaves, completed) {
   return null;
 }
 
-function runCommand(args) {
+function runCommand(args, envOverrides = {}) {
   const result = spawnSync("node", args, {
     cwd: REPO_ROOT,
     stdio: "inherit",
-    env: process.env,
+    env: {
+      ...process.env,
+      ...envOverrides,
+    },
   });
   return Number.isInteger(result.status) ? result.status : 1;
 }
 
 function reconcile(lane) {
-  return runCommand([path.join(PACKAGE_ROOT, "scripts", "wave-launcher.mjs"), "--lane", lane, "--reconcile-status"]);
+  return runCommand(
+    [path.join(PACKAGE_ROOT, "scripts", "wave-launcher.mjs"), "--lane", lane, "--reconcile-status"],
+    { [WAVE_SUPPRESS_UPDATE_NOTICE_ENV]: "1" },
+  );
 }
 
 function dryRun(lane) {
-  return runCommand([path.join(PACKAGE_ROOT, "scripts", "wave-launcher.mjs"), "--lane", lane, "--dry-run", "--no-dashboard"]);
+  return runCommand(
+    [path.join(PACKAGE_ROOT, "scripts", "wave-launcher.mjs"), "--lane", lane, "--dry-run", "--no-dashboard"],
+    { [WAVE_SUPPRESS_UPDATE_NOTICE_ENV]: "1" },
+  );
 }
 
 function listPendingFeedback(lane) {
@@ -215,7 +228,7 @@ function launchSingleWave(params) {
   if (params.keepTerminals) {
     args.push("--keep-terminals");
   }
-  return runCommand(args);
+  return runCommand(args, { [WAVE_SUPPRESS_UPDATE_NOTICE_ENV]: "1" });
 }
 
 function requiredInboundDependenciesOpen(lanePaths, lane) {
@@ -291,12 +304,13 @@ export function readAutonomousBarrier(lanePaths, lane, wave = null) {
   return null;
 }
 
-export function runAutonomousCli(argv) {
+export async function runAutonomousCli(argv) {
   const parsed = parseArgs(argv);
   if (parsed.help) {
     printUsage();
     return;
   }
+  await maybeAnnouncePackageUpdate();
   const options = parsed.options;
   const allWaves = getWaveNumbers(options.lane);
   console.log(`[autonomous] lane=${options.lane} orchestrator=${options.orchestratorId}`);

package/scripts/wave-orchestrator/install.mjs

@@ -1,10 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import {
   applyContext7SelectionsToWave,
   loadContext7BundleIndex,
 } from "./context7.mjs";
 import { buildLanePaths, ensureDirectory, PACKAGE_ROOT, readJsonOrNull, REPO_ROOT, writeJsonAtomic } from "./shared.mjs";
+import { fetchLatestPackageVersion } from "./package-update-notice.mjs";
+import {
+  compareVersions,
+  readInstalledPackageMetadata,
+  WAVE_PACKAGE_NAME,
+} from "./package-version.mjs";
 import { loadWaveConfig } from "./config.mjs";
 import { applyExecutorSelectionsToWave, parseWaveFiles, validateWaveDefinition } from "./wave-files.mjs";
 import { validateLaneSkillConfiguration } from "./skills.mjs";
@@ -14,7 +21,7 @@ export const INSTALL_STATE_DIR = ".wave";
 export const INSTALL_STATE_PATH = path.join(REPO_ROOT, INSTALL_STATE_DIR, "install-state.json");
 export const UPGRADE_HISTORY_DIR = path.join(REPO_ROOT, INSTALL_STATE_DIR, "upgrade-history");
 export const CHANGELOG_MANIFEST_PATH = path.join(PACKAGE_ROOT, "releases", "manifest.json");
-export const PACKAGE_METADATA_PATH = path.join(PACKAGE_ROOT, "package.json");
+export const WORKSPACE_PACKAGE_JSON_PATH = path.join(REPO_ROOT, "package.json");
 export const STARTER_TEMPLATE_PATHS = [
   "wave.config.json",
   "docs/README.md",
@@ -69,11 +76,7 @@ function collectDeclaredDeployKinds(waves = []) {
 }
 
 function packageMetadata() {
-  const payload = readJsonOrNull(PACKAGE_METADATA_PATH);
-  if (!payload?.name || !payload?.version) {
-    throw new Error(`Invalid package metadata: ${PACKAGE_METADATA_PATH}`);
-  }
-  return payload;
+  return readInstalledPackageMetadata();
 }
 
 function readInstallState() {
@@ -149,25 +152,6 @@ function nextHistoryRecord(existingState, entry) {
   return history;
 }
 
-function normalizeVersionParts(version) {
-  return String(version || "")
-    .split(".")
-    .map((part) => Number.parseInt(part.replace(/[^0-9].*$/, ""), 10) || 0);
-}
-
-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;
-}
-
 function readChangelogManifest() {
   const payload = readJsonOrNull(CHANGELOG_MANIFEST_PATH);
   if (!payload?.releases || !Array.isArray(payload.releases)) {
@@ -478,6 +462,186 @@ export function upgradeWorkspace() {
   };
 }
 
+function readWorkspacePackageManifest(workspaceRoot = REPO_ROOT) {
+  const payload = readJsonOrNull(path.join(workspaceRoot, "package.json"));
+  if (!payload || typeof payload !== "object") {
+    throw new Error(`Missing package.json at ${path.join(workspaceRoot, "package.json")}`);
+  }
+  return payload;
+}
+
+function readInstallStateForWorkspace(workspaceRoot = REPO_ROOT) {
+  const payload = readJsonOrNull(path.join(workspaceRoot, INSTALL_STATE_DIR, "install-state.json"));
+  return payload && typeof payload === "object" ? payload : null;
+}
+
+function parsePackageManagerId(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  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;
+}
+
+export function detectWorkspacePackageManager(workspaceRoot = REPO_ROOT) {
+  const manifest = readWorkspacePackageManifest(workspaceRoot);
+  const packageManagerFromManifest = parsePackageManagerId(manifest.packageManager);
+  if (packageManagerFromManifest) {
+    return {
+      id: packageManagerFromManifest,
+      source: "packageManager",
+      raw: manifest.packageManager,
+    };
+  }
+  for (const [fileName, id] of [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["npm-shrinkwrap.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lockb", "bun"],
+    ["bun.lock", "bun"],
+  ]) {
+    if (fs.existsSync(path.join(workspaceRoot, fileName))) {
+      return {
+        id,
+        source: "lockfile",
+        raw: fileName,
+      };
+    }
+  }
+  return {
+    id: "npm",
+    source: "default",
+    raw: null,
+  };
+}
+
+function packageManagerCommands(managerId, packageName = WAVE_PACKAGE_NAME) {
+  if (managerId === "pnpm") {
+    return {
+      install: ["pnpm", ["add", "-D", `${packageName}@latest`]],
+      execWave: (args) => ["pnpm", ["exec", "wave", ...args]],
+    };
+  }
+  if (managerId === "npm") {
+    return {
+      install: ["npm", ["install", "--save-dev", `${packageName}@latest`]],
+      execWave: (args) => ["npm", ["exec", "--", "wave", ...args]],
+    };
+  }
+  if (managerId === "yarn") {
+    return {
+      install: ["yarn", ["add", "-D", `${packageName}@latest`]],
+      execWave: (args) => ["yarn", ["exec", "wave", ...args]],
+    };
+  }
+  if (managerId === "bun") {
+    return {
+      install: ["bun", ["add", "-d", `${packageName}@latest`]],
+      execWave: (args) => ["bun", ["x", "wave", ...args]],
+    };
+  }
+  throw new Error(`Unsupported package manager: ${managerId}`);
+}
+
+function runCommandOrThrow(command, args, options = {}) {
+  const spawnImpl = options.spawnImpl || spawnSync;
+  const result = spawnImpl(command, args, {
+    cwd: options.workspaceRoot || REPO_ROOT,
+    stdio: options.stdio || "inherit",
+    env: options.env || process.env,
+    encoding: "utf8",
+  });
+  const status = Number.isInteger(result?.status) ? result.status : 1;
+  if (status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} failed with status ${status}`);
+  }
+  return result;
+}
+
+export async function selfUpdateWorkspace(options = {}) {
+  const workspaceRoot = options.workspaceRoot || REPO_ROOT;
+  const metadata = options.packageMetadata || packageMetadata();
+  const installState = readInstallStateForWorkspace(workspaceRoot);
+  const packageManager = detectWorkspacePackageManager(workspaceRoot);
+  const commands = packageManagerCommands(packageManager.id, metadata.name || WAVE_PACKAGE_NAME);
+  const emit = options.emit || console.log;
+  let latestVersion = null;
+
+  try {
+    latestVersion = await fetchLatestPackageVersion(metadata.name || WAVE_PACKAGE_NAME, {
+      fetchImpl: options.fetchImpl,
+      timeoutMs: options.timeoutMs,
+    });
+  } catch {
+    latestVersion = null;
+  }
+
+  const currentVersion = String(metadata.version || "").trim();
+  const recordedVersion = String(installState?.installedVersion || "").trim() || null;
+  const needsUpgradeOnly = recordedVersion && compareVersions(currentVersion, recordedVersion) !== 0;
+
+  emit(`[wave:self-update] package_manager=${packageManager.id}`);
+
+  if (latestVersion && compareVersions(latestVersion, currentVersion) <= 0) {
+    if (!needsUpgradeOnly) {
+      emit(`[wave:self-update] ${metadata.name} is already current at ${currentVersion}.`);
+      return {
+        mode: "already-current",
+        packageManager: packageManager.id,
+        currentVersion,
+        latestVersion,
+      };
+    }
+    emit(
+      `[wave:self-update] dependency is already at ${currentVersion}; recording workspace upgrade state.`,
+    );
+    const [upgradeCommand, upgradeArgs] = commands.execWave(["upgrade"]);
+    runCommandOrThrow(upgradeCommand, upgradeArgs, options);
+    return {
+      mode: "upgrade-only",
+      packageManager: packageManager.id,
+      currentVersion,
+      latestVersion,
+    };
+  }
+
+  emit(
+    `[wave:self-update] updating ${metadata.name} from ${currentVersion}${latestVersion ? ` to ${latestVersion}` : " to the latest published version"}.`,
+  );
+  const [installCommand, installArgs] = commands.install;
+  runCommandOrThrow(installCommand, installArgs, options);
+
+  emit("[wave:self-update] release notes since the recorded install:");
+  const [changelogCommand, changelogArgs] = commands.execWave(["changelog", "--since-installed"]);
+  runCommandOrThrow(changelogCommand, changelogArgs, options);
+
+  emit("[wave:self-update] recording install-state and upgrade report:");
+  const [upgradeCommand, upgradeArgs] = commands.execWave(["upgrade"]);
+  runCommandOrThrow(upgradeCommand, upgradeArgs, options);
+
+  return {
+    mode: "updated",
+    packageManager: packageManager.id,
+    currentVersion,
+    latestVersion,
+  };
+}
+
 function printJson(payload) {
   console.log(JSON.stringify(payload, null, 2));
 }
@@ -486,6 +650,7 @@ function printHelp() {
   console.log(`Usage:
   wave init [--adopt-existing] [--json]
   wave upgrade [--json]
+  wave self-update
   wave changelog [--since-installed] [--json]
   wave doctor [--json]
 `);
@@ -562,6 +727,14 @@ export async function runInstallCli(argv) {
     return;
   }
 
+  if (subcommand === "self-update") {
+    if (options.json) {
+      throw new Error("`wave self-update` does not support --json.");
+    }
+    await selfUpdateWorkspace();
+    return;
+  }
+
   if (subcommand === "changelog") {
     const result = readChangelog({ sinceInstalled: options.sinceInstalled });
     if (options.json) {

package/scripts/wave-orchestrator/launcher.mjs

@@ -98,6 +98,7 @@ import {
   commandForExecutor,
   isExecutorCommandAvailable,
 } from "./executors.mjs";
+import { maybeAnnouncePackageUpdate } from "./package-update-notice.mjs";
 import {
   agentRequiresProofCentricValidation,
   buildRunStateEvidence,
@@ -2971,6 +2972,9 @@ export async function runLauncherCli(argv) {
     return;
   }
   const { lanePaths, options } = parsed;
+  if (!options.reconcileStatus) {
+    await maybeAnnouncePackageUpdate();
+  }
   let lockHeld = false;
   let globalDashboard = null;
   let globalDashboardTerminalEntry = null;

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;
+}

package/scripts/wave.mjs

@@ -12,6 +12,7 @@ function printHelp() {
   console.log(`Usage:
   wave init [options]
   wave upgrade [options]
+  wave self-update
   wave changelog [options]
   wave doctor [options]
   wave project setup [options]
@@ -25,6 +26,7 @@ function printHelp() {
   wave local [local executor options]
   wave coord [coordination options]
   wave dep [dependency options]
+  wave benchmark [benchmark options]
 
 Global options:
   --repo-root <path>   Run the command against a target workspace root
@@ -36,7 +38,7 @@ if (!subcommand || subcommand === "--help" || subcommand === "-h" || subcommand
   process.exit(0);
 }
 
-if (["init", "upgrade", "changelog", "doctor"].includes(subcommand)) {
+if (["init", "upgrade", "self-update", "changelog", "doctor"].includes(subcommand)) {
   try {
     const { runInstallCli } = await import("./wave-orchestrator/install.mjs");
     await runInstallCli([subcommand, ...rest]);
@@ -71,7 +73,7 @@ if (["init", "upgrade", "changelog", "doctor"].includes(subcommand)) {
 } else if (subcommand === "autonomous") {
   const { runAutonomousCli } = await import("./wave-orchestrator/autonomous.mjs");
   try {
-    runAutonomousCli(rest);
+    await runAutonomousCli(rest);
   } catch (error) {
     console.error(`[wave] ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
@@ -116,6 +118,14 @@ if (["init", "upgrade", "changelog", "doctor"].includes(subcommand)) {
     console.error(`[wave] ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
   }
+} else if (subcommand === "benchmark") {
+  try {
+    const { runBenchmarkCli } = await import("./wave-orchestrator/benchmark.mjs");
+    await runBenchmarkCli(rest);
+  } catch (error) {
+    console.error(`[wave] ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
 } else {
   console.error(`[wave] Unknown subcommand: ${subcommand}`);
   printHelp();