@chllming/wave-orchestration 0.8.5 → 0.8.6

package/scripts/context7-api-check.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-# Minimal Context7 API smoke test (expects CONTEXT7_API_KEY in the environment).
 set -euo pipefail
 
 if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
@@ -7,15 +6,60 @@ if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
   exit 1
 fi
 
-URL='https://context7.com/api/v2/libs/search?libraryName=temporal&query=go%20workflow'
-echo "GET $URL" >&2
-RESP="$(curl -fsS "$URL" -H "Authorization: Bearer ${CONTEXT7_API_KEY}" -H "Accept: application/json")"
-RESP_JSON="$RESP" node -e "
-const j = JSON.parse(process.env.RESP_JSON || '{}');
-const list = Array.isArray(j) ? j : (j.results ?? j.items ?? []);
-const first = list[0];
-if (!first) { console.error('Unexpected response shape:', Object.keys(j)); process.exit(1); }
-const id = first.id ?? first.libraryId;
-const name = first.title ?? first.name;
-console.log('ok — first library:', id || name || JSON.stringify(first).slice(0, 120));
-"
+node <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const apiKey = process.env.CONTEXT7_API_KEY || "";
+const repoRoot = process.cwd();
+const bundlePath = path.join(repoRoot, "docs/context7/bundles.json");
+const payload = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+
+const entries = [];
+for (const [bundleId, bundle] of Object.entries(payload.bundles || {})) {
+  for (const library of bundle.libraries || []) {
+    if (!library.libraryId) {
+      throw new Error(
+        `Bundle "${bundleId}" must pin exact Context7 libraryId values. Found libraryName=${JSON.stringify(library.libraryName || "")}.`,
+      );
+    }
+    entries.push({
+      bundleId,
+      libraryId: String(library.libraryId),
+      queryHint: String(library.queryHint || "overview"),
+    });
+  }
+}
+
+const uniqueEntries = [...new Map(entries.map((entry) => [entry.libraryId, entry])).values()];
+
+async function validate(entry) {
+  const url = new URL("https://context7.com/api/v2/context");
+  url.searchParams.set("libraryId", entry.libraryId);
+  url.searchParams.set("query", entry.queryHint);
+  url.searchParams.set("type", "txt");
+  const response = await fetch(url, {
+    headers: {
+      Authorization: "Bearer " + apiKey,
+      Accept: "text/plain, application/json",
+    },
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`Context7 ${entry.libraryId} failed (${response.status}): ${text.slice(0, 200)}`);
+  }
+  if (text.trim().length === 0) {
+    throw new Error(`Context7 ${entry.libraryId} returned empty context.`);
+  }
+  console.log(`ok -- ${entry.libraryId} (${entry.bundleId})`);
+}
+
+(async () => {
+  for (const entry of uniqueEntries) {
+    await validate(entry);
+  }
+})().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+NODE

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

@@ -36,6 +36,10 @@ import { readWaveRelaunchPlanSnapshot, readWaveRetryOverride, resolveRetryOverri
 import { flushWaveControlQueue, readWaveControlQueueState } from "./wave-control-client.mjs";
 import { readAgentExecutionSummary, validateImplementationSummary } from "./agent-state.mjs";
 import { isContEvalReportOnlyAgent, isSecurityReviewAgent } from "./role-helpers.mjs";
+import {
+  buildSignalStatusLine,
+  syncWaveSignalProjections,
+} from "./signals.mjs";
 
 function printUsage() {
   console.log(`Usage:
@@ -676,6 +680,7 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
     proofBundles: (proofRegistry?.entries || []).filter(
       (entry) => !agentId || entry.agentId === agentId,
     ),
+    feedbackRequests,
     selectionSource: selection.source,
     rerunRequest,
     relaunchPlan,
@@ -690,6 +695,7 @@ function ensureWaveStateDirs(lanePaths) {
   ensureDirectory(lanePaths.controlPlaneDir);
   ensureDirectory(lanePaths.assignmentsDir);
   ensureDirectory(lanePaths.inboxesDir);
+  ensureDirectory(lanePaths.signalsDir);
   ensureDirectory(lanePaths.messageboardsDir);
   ensureDirectory(lanePaths.docsQueueDir);
   ensureDirectory(lanePaths.ledgerDir);
@@ -714,6 +720,9 @@ function printStatus(payload) {
     ? `${payload.blockingEdge.kind} ${payload.blockingEdge.id}: ${payload.blockingEdge.detail}`
     : "none";
   console.log(`lane=${payload.lane} wave=${payload.wave} phase=${payload.phase}`);
+  if (payload.signals?.wave) {
+    console.log(buildSignalStatusLine(payload.signals.wave, payload));
+  }
   console.log(`blocking=${blocking}`);
   if (payload.nextTimer) {
     console.log(`next-timer=${payload.nextTimer.kind} ${payload.nextTimer.taskId} at ${payload.nextTimer.at}`);
@@ -901,6 +910,16 @@ export async function runControlCli(argv) {
       wave,
       agentId: options.agent || "",
     });
+    const signalSync = syncWaveSignalProjections({
+      lanePaths,
+      wave,
+      statusPayload: payload,
+      includeResident: Boolean(options.orchestratorId),
+    });
+    payload.signals = {
+      wave: signalSync.wave?.snapshot || null,
+      agents: (signalSync.agents || []).map((entry) => entry.snapshot),
+    };
     if (options.json) {
       console.log(JSON.stringify(payload, null, 2));
     } else {

package/scripts/wave-orchestrator/coordination.mjs

@@ -203,6 +203,8 @@ export function buildExecutionPrompt({
   sharedPlanDocs = null,
   designPacketPaths = null,
   designExecutionMode = null,
+  signalStatePath = null,
+  signalAckPath = null,
   contQaAgentId = "A0",
   contEvalAgentId = "E0",
   integrationAgentId = "A8",
@@ -213,6 +215,10 @@ export function buildExecutionPrompt({
     ? path.relative(REPO_ROOT, sharedSummaryPath)
     : null;
   const relativeInboxPath = inboxPath ? path.relative(REPO_ROOT, inboxPath) : null;
+  const relativeSignalStatePath = signalStatePath
+    ? path.relative(REPO_ROOT, signalStatePath)
+    : null;
+  const relativeSignalAckPath = signalAckPath ? path.relative(REPO_ROOT, signalAckPath) : null;
   const lanePlansDir = lane === DEFAULT_WAVE_LANE ? "docs/plans" : `docs/${lane}/plans`;
   const resolvedSharedPlanDocs =
     sharedPlanDocs && sharedPlanDocs.length > 0
@@ -531,6 +537,14 @@ export function buildExecutionPrompt({
           `Agent inbox repo-relative path: ${relativeInboxPath}`,
         ]
       : []),
+    ...(signalStatePath
+      ? [
+          `Signal state absolute path: ${signalStatePath}`,
+          `Signal state repo-relative path: ${relativeSignalStatePath}`,
+          `Signal ack absolute path: ${signalAckPath}`,
+          `Signal ack repo-relative path: ${relativeSignalAckPath}`,
+        ]
+      : []),
     "",
     ...(sharedSummaryText
       ? ["Current wave shared summary:", "```markdown", sharedSummaryText, "```", ""]
@@ -538,6 +552,17 @@ export function buildExecutionPrompt({
     ...(inboxText
       ? ["Current agent inbox:", "```markdown", inboxText, "```", ""]
       : []),
+    ...(signalStatePath
+      ? [
+          "Long-running signal loop:",
+          "- If you are operating as a resident or waiting agent, keep watching the signal state JSON instead of exiting early.",
+          "- When the signal `version` increases beyond the version recorded in the signal ack file, immediately write the ack file before acting.",
+          `- Write the ack file as JSON with exactly these keys: \`agentId\`, \`version\`, \`signal\`, and \`observedAt\`. Use \`${agent.agentId}\` as \`agentId\` and an ISO-8601 timestamp for \`observedAt\`.`,
+          "- After writing the ack, re-read the inbox, shared summary, and message board, then handle the new signal once.",
+          "- If the signal version has not changed, stay idle. Do not busy-loop or repeat unchanged work.",
+          "",
+        ]
+      : []),
     ...exitContractLines,
     ...promotedComponentLines,
     ...evalTargetLines,
@@ -564,6 +589,8 @@ export function buildResidentOrchestratorPrompt({
   sharedSummaryPath,
   dashboardPath,
   triagePath = null,
+  signalStatePath = null,
+  signalAckPath = null,
   rolePrompt = "",
 }) {
   const coordinationCommand = [
@@ -612,6 +639,8 @@ export function buildResidentOrchestratorPrompt({
     `- Wave dashboard: ${dashboardPath}`,
     `- Message board projection: ${messageBoardPath}`,
     ...(triagePath ? [`- Feedback triage log: ${triagePath}`] : []),
+    ...(signalStatePath ? [`- Signal state: ${signalStatePath}`] : []),
+    ...(signalAckPath ? [`- Signal ack: ${signalAckPath}`] : []),
     "",
     "Action surface:",
     `- Coordination command: \`${coordinationCommand}\``,
@@ -624,6 +653,12 @@ export function buildResidentOrchestratorPrompt({
     "2. Identify open clarifications, open clarification-linked requests, overdue acknowledgements, and human-feedback state.",
     "3. If action is needed, write a durable coordination update and explain the policy basis for the action.",
     "4. If nothing needs action, continue monitoring. Do not exit until the wave is clearly terminal or the launcher stops the session.",
+    ...(signalStatePath
+      ? [
+          "5. When the signal state `version` increases, immediately write the signal ack file before taking action so the launcher knows you observed the change.",
+          "6. After acknowledging the signal, re-read the shared summary, dashboard, coordination log, and triage artifacts before intervening.",
+        ]
+      : []),
     "",
     ...(roleSection
       ? [

package/scripts/wave-orchestrator/install.mjs

@@ -27,6 +27,8 @@ export const CHANGELOG_MANIFEST_PATH = path.join(PACKAGE_ROOT, "releases", "mani
 export const WORKSPACE_PACKAGE_JSON_PATH = path.join(REPO_ROOT, "package.json");
 export const STARTER_TEMPLATE_PATHS = [
   "wave.config.json",
+  "scripts/wave-status.sh",
+  "scripts/wave-watch.sh",
   "docs/README.md",
   "docs/agents/wave-documentation-role.md",
   "docs/agents/wave-design-role.md",

package/scripts/wave-orchestrator/launcher-runtime.mjs

@@ -20,6 +20,11 @@ import {
   summarizeResolvedSkills,
   writeResolvedSkillArtifacts,
 } from "./skills.mjs";
+import {
+  agentSignalAckPath,
+  agentSignalPath,
+  agentUsesSignalHygiene,
+} from "./signals.mjs";
 
 export function refreshResolvedSkillsForRun(runInfo, waveDefinition, lanePaths) {
   runInfo.agent.skillsResolved = resolveAgentSkills(
@@ -129,6 +134,12 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
         .map((waveAgent) => resolveDesignReportPath(waveAgent))
         .filter(Boolean),
       designExecutionMode,
+      signalStatePath: agentUsesSignalHygiene(agent)
+        ? agentSignalPath(lanePaths, wave, agent.agentId)
+        : null,
+      signalAckPath: agentUsesSignalHygiene(agent)
+        ? agentSignalAckPath(lanePaths, wave, agent.agentId)
+        : null,
     });
   const promptHash = hashAgentPromptFingerprint(agent);
   fs.writeFileSync(promptPath, `${prompt}\n`, "utf8");

package/scripts/wave-orchestrator/launcher.mjs

@@ -209,7 +209,9 @@ import {
   recordAttemptState,
   recordWaveRunState,
   runTmux,
+  syncLiveWaveSignals,
 } from "./session-supervisor.mjs";
+import { buildControlStatusPayload } from "./control-cli.mjs";
 import {
   planInitialWaveAttempt,
   planRetryWaveAttempt,
@@ -624,6 +626,7 @@ export async function runLauncherCli(argv) {
   ensureDirectory(lanePaths.controlDir);
   ensureDirectory(lanePaths.assignmentsDir);
   ensureDirectory(lanePaths.inboxesDir);
+  ensureDirectory(lanePaths.signalsDir);
   ensureDirectory(lanePaths.ledgerDir);
   ensureDirectory(lanePaths.integrationDir);
   ensureDirectory(lanePaths.proofDir);
@@ -1188,6 +1191,19 @@ export async function runLauncherCli(argv) {
           flushDashboards();
           return true;
         };
+        const syncWaveSignals = () =>
+          syncLiveWaveSignals({
+            lanePaths,
+            wave,
+            statusPayload: buildControlStatusPayload({
+              lanePaths,
+              wave,
+            }),
+            agentRuns,
+            residentEnabled: Boolean(residentOrchestratorRun),
+            recordCombinedEvent,
+            appendCoordination,
+          });
 
         const proofRegistryForReuse = readWaveProofRegistry(lanePaths, wave.wave);
         const initialAttemptPlan = planInitialWaveAttempt({
@@ -1217,6 +1233,7 @@ export async function runLauncherCli(argv) {
         }
         flushDashboards();
         emitCoordinationAlertEvents(derivedState);
+        syncWaveSignals();
 
         if (options.dashboard && currentWaveDashboardTerminalEntry) {
           launchWaveDashboardSession(lanePaths, {
@@ -1281,6 +1298,7 @@ export async function runLauncherCli(argv) {
               details: `session=${residentOrchestratorRun.sessionName}; executor=${residentOrchestratorRun.lastExecutorId || "unknown"}`,
               actionRequested: "None",
             });
+            syncWaveSignals();
           }
         }
 
@@ -1487,6 +1505,7 @@ export async function runLauncherCli(argv) {
                   updateWaveDashboardMessageBoard(dashboardState, messageBoardPath);
                   flushDashboards();
                 }
+                syncWaveSignals();
               },
               {
                 controlPlane: {
@@ -1501,6 +1520,7 @@ export async function runLauncherCli(argv) {
 
           materializeAgentExecutionSummaries(wave, agentRuns);
           refreshDerivedState(attempt);
+          syncWaveSignals();
           lastLiveCoordinationRefreshAt = Date.now();
           emitCoordinationAlertEvents(derivedState);
           failures = reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures);

package/scripts/wave-orchestrator/session-supervisor.mjs

@@ -40,6 +40,13 @@ import {
   launchAgentSession as launchAgentSessionImpl,
   waitForWaveCompletion as waitForWaveCompletionImpl,
 } from "./launcher-runtime.mjs";
+import {
+  agentUsesSignalHygiene,
+  buildSignalStatusLine,
+  residentSignalAckPath,
+  residentSignalPath,
+  syncWaveSignalProjections,
+} from "./signals.mjs";
 
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) {
@@ -363,6 +370,8 @@ export function buildResidentOrchestratorRun({
         sharedSummaryPath: derivedState.sharedSummaryPath,
         dashboardPath,
         triagePath: derivedState.clarificationTriage?.triagePath || null,
+        signalStatePath: residentSignalPath(lanePaths, wave.wave),
+        signalAckPath: residentSignalAckPath(lanePaths, wave.wave),
         rolePrompt: agent.prompt,
       }),
     },
@@ -777,3 +786,107 @@ export function monitorWaveHumanFeedback({
   }
   return changed;
 }
+
+export function syncLiveWaveSignals({
+  lanePaths,
+  wave,
+  statusPayload,
+  agentRuns,
+  residentEnabled = false,
+  recordCombinedEvent,
+  appendCoordination,
+}) {
+  const activeSignalAgents = new Set(
+    (Array.isArray(agentRuns) ? agentRuns : [])
+      .filter((run) => agentUsesSignalHygiene(run?.agent))
+      .map((run) => run.agent.agentId),
+  );
+  const syncResult = syncWaveSignalProjections({
+    lanePaths,
+    wave,
+    statusPayload,
+    includeResident: residentEnabled,
+  });
+  if (syncResult.wave?.changed) {
+    appendWaveControlEvent(lanePaths, wave.wave, {
+      entityType: "wave_signal",
+      entityId: `wave-${wave.wave}`,
+      action: "updated",
+      source: "session-supervisor",
+      actor: "session-supervisor",
+      data: syncResult.wave.snapshot,
+    });
+    if (typeof recordCombinedEvent === "function") {
+      recordCombinedEvent({
+        level: syncResult.wave.snapshot.shouldWake ? "warn" : "info",
+        message: `Wave signal updated: ${buildSignalStatusLine(syncResult.wave.snapshot)}`,
+      });
+    }
+  }
+  for (const agentResult of syncResult.agents || []) {
+    if (!agentResult.changed) {
+      continue;
+    }
+    appendWaveControlEvent(lanePaths, wave.wave, {
+      entityType: "agent_signal",
+      entityId: `wave-${wave.wave}-agent-${agentResult.agentId}`,
+      action: "updated",
+      source: "session-supervisor",
+      actor: "session-supervisor",
+      data: agentResult.snapshot,
+    });
+    if (
+      agentResult.snapshot?.shouldWake &&
+      activeSignalAgents.has(agentResult.agentId) &&
+      typeof recordCombinedEvent === "function"
+    ) {
+      recordCombinedEvent({
+        level: "info",
+        agentId: agentResult.agentId,
+        message: `Signal changed: ${buildSignalStatusLine(agentResult.snapshot, {
+          lane: lanePaths.lane,
+          wave: wave.wave,
+          agentId: agentResult.agentId,
+        })}`,
+      });
+    }
+  }
+  if (syncResult.resident?.changed) {
+    appendWaveControlEvent(lanePaths, wave.wave, {
+      entityType: "agent_signal",
+      entityId: `wave-${wave.wave}-agent-resident-orchestrator`,
+      action: "updated",
+      source: "session-supervisor",
+      actor: "session-supervisor",
+      data: syncResult.resident.snapshot,
+    });
+    if (syncResult.resident.snapshot?.shouldWake && typeof recordCombinedEvent === "function") {
+      recordCombinedEvent({
+        level: "info",
+        agentId: "ORCH",
+        message: `Resident orchestrator signal changed: ${buildSignalStatusLine(
+          syncResult.resident.snapshot,
+          {
+            lane: lanePaths.lane,
+            wave: wave.wave,
+            agentId: "resident-orchestrator",
+          },
+        )}`,
+      });
+    }
+    if (
+      syncResult.resident.snapshot?.shouldWake &&
+      typeof appendCoordination === "function"
+    ) {
+      appendCoordination({
+        event: "resident_signal_updated",
+        waves: [wave.wave],
+        status: "running",
+        details: syncResult.resident.snapshot.reason || syncResult.resident.snapshot.signal,
+        actionRequested:
+          "Resident orchestrator should re-read the signal snapshot, shared summary, dashboard, and coordination log.",
+      });
+    }
+  }
+  return syncResult;
+}

package/scripts/wave-orchestrator/shared.mjs

@@ -199,6 +199,7 @@ export function buildLanePaths(laneInput = DEFAULT_WAVE_LANE, options = {}) {
     telemetryDir: path.join(stateDir, "control-plane", "telemetry"),
     assignmentsDir: path.join(stateDir, "assignments"),
     inboxesDir: path.join(stateDir, "inboxes"),
+    signalsDir: path.join(stateDir, "signals"),
     ledgerDir: path.join(stateDir, "ledger"),
     integrationDir: path.join(stateDir, "integration"),
     resultsDir: path.join(stateDir, "results"),