@chllming/wave-orchestration 0.9.0 → 0.9.2

package/docs/roadmap.md

@@ -1,226 +1,61 @@
 # Wave Orchestrator Roadmap
 
-Wave Orchestrator should keep wave markdown as the authored plan surface, but it needs a higher planning-fidelity bar and a better authoring loop.
+This roadmap is intentionally short and current. The older planner-foundation and ad-hoc-run phase list has been removed because that work no longer describes the actual shipping direction for this package.
 
-The same planning and execution substrate should also support ad-hoc operator requests without forcing every one-off task into the long-lived numbered roadmap sequence.
+## Current Release: 0.9.2
 
-The target is the level of specificity shown in [Wave 7](/home/coder/slowfast.ai/docs/plans/waves/wave-7.md): explicit sequencing, hard requirements, exact validation commands, earlier-wave inputs, concrete ownership, and clear closure rules. This roadmap focuses on how to get this repo there without replacing the current architecture.
+`0.9.2` is the current packaged surface.
 
-## Current Position
+It includes:
 
-The repository already has the right runtime substrate:
+- detached process-backed agent execution instead of tmux-heavy live execution
+- lower steady-state memory pressure and less terminal churn during long runs
+- better behavior in constrained sandboxes such as LEAPclaw, OpenClaw, Nemoshell, and Docker-based operator environments
+- a safer `submit -> supervise -> status/wait -> attach` control path for long-running agentic orchestration
+- tighter supervisor recovery, progress journaling, and closure/retry correctness
+- the current protected Wave Control model: Stack-authenticated browser access, Wave-managed approval states and provider grants, PATs, service tokens, encrypted per-user credentials, and runtime env leasing
+- owned Context7 and Corridor broker routes plus the Corridor-backed security context that can gate closure before integration
 
-- lane-scoped state under `.tmp/`
-- wave parsing and validation
-- role-based execution with cont-qa, integration, and documentation stewards
-- executor profiles and lane runtime policy
-- compiled inboxes, ledgers, docs queues, dependency snapshots, and trace bundles
-- orchestrator-first clarification handling and human feedback workflows
+## Near-Term Direction On This Node Line
 
-The biggest remaining gap is not runtime execution. It is authored planning quality, the tooling around planning, and a lower-friction entry point for ad-hoc work that still preserves the same coordination and trace surfaces.
+This standalone Node line should now be treated as maintenance-oriented:
 
-## Planning Fidelity Target
+- bug fixes
+- compatibility updates
+- operational hardening
+- documentation updates
+- release-surface alignment work
 
-Every serious wave should be able to answer these questions before launch:
+## Strategic Direction: LEAPclaw Execution Model
 
-- What earlier waves or artifacts are prerequisites?
-- What exact components are being promoted and why now?
-- What is the required runtime mix and fallback policy?
-- Which deploy environment or infra substrate is in scope?
-- Is the run `oversight` or `dark-factory`?
-- What exact validation commands must pass?
-- What exact artifact closes the role?
+With the authenticated Wave Control surface now present, the main execution roadmap moves away from expanding this Node runtime and toward the LEAPclaw execution model.
 
-Generated waves and transient ad-hoc runs should default to these sections when relevant:
+The target shape is:
 
-- sequencing note
-- reference rule or source-of-truth note
-- project bootstrap context
-- deploy environments
-- component promotions
-- Context7 defaults
-- per-agent required context
-- earlier-wave outputs to read
-- requirements
-- validation
-- output or closure contract
+- LEAPclaw-native execution semantics for agent orchestration and management
+- Go-based runtime ownership for the long-running execution layer
+- Temporal-backed workflow and recovery coordination
+- LEAPclaw nodes as the durable execution substrate for orchestrated agent work
+- Wave Control acting as an authenticated control and observability surface rather than the long-term primary execution engine
 
-## Phase 1: Planner Foundation
+This direction matches the broader local platform work in the sibling `slowfast.ai` repository, where the support-service and runtime direction already points toward LEAPclaw support services, Go runtime ownership, and Temporal-backed orchestration.
 
-Status: shipped in `0.5.4`.
+## Future Standalone Runtime Direction
 
-- Add saved project bootstrap memory in `.wave/project-profile.json` for the implicit default project, with project-scoped profiles under `.wave/projects/<projectId>/project-profile.json` for explicit monorepo projects.
-- Ask once whether the repo is a new project and keep that answer for future drafts.
-- Add `wave project setup` and `wave project show`.
-- Add interactive `wave draft` that writes:
-  - `docs/plans/waves/specs/wave-<n>.json`
-  - `docs/plans/waves/wave-<n>.md`
-- Treat the JSON draft spec as the canonical authoring artifact and render markdown from it.
-- Keep generated waves fully compatible with the current parser and launcher.
-- Add `wave launch --terminal-surface vscode|tmux|none`.
-- Support a tmux-only operator mode that never touches `.vscode/terminals.json`.
+For future standalone Wave Orchestrator versions, the preferred implementation direction is the Rust runtime at:
 
-Why first:
+- `https://github.com/chllming/agent-wave-orchestrator`
 
-- Better planning is the highest-leverage missing piece.
-- The repo already has strong runtime and closure machinery.
-- Project memory removes repeated setup questions and gives future planner steps a durable baseline.
+That line is expected to carry:
 
-## Phase 2: Ad-Hoc Task Runs
+- its own runtime implementation
+- its own terminal-native/TUI operator surface
+- the longer-term standalone execution model once the Node package settles into maintenance mode
 
-The orchestrator should support operator-driven one-off requests without requiring the user to author or commit a numbered roadmap wave first.
+## Practical Guidance
 
-CLI target:
+For this repository, the practical sequence is:
 
-- `wave adhoc plan --task "..."`
-- `wave adhoc run --task "..." [--task "..."]`
-- `wave adhoc list`
-- `wave adhoc show --run <id>`
-- `wave adhoc promote --run <id> --wave <n>`
-
-Behavior:
-
-- accept one or more free-form task requests
-- normalize them into a single transient plan or spec
-- synthesize the worker roles needed for the request while still preserving cont-qa, integration, and documentation closure when relevant
-- run that transient plan through the existing launcher, coordination, inbox, ledger, docs queue, integration, and trace machinery
-- keep ad-hoc runs logged, inspectable, and replayable with the same basic operator surfaces as roadmap waves
-- route shared-plan documentation deltas into the canonical shared docs queue, plus an ad-hoc closure report for the run
-- treat only repo-local paths as ownership hints and ignore external references such as URLs
-
-Storage model:
-
-- do not write ad-hoc runs into the canonical numbered wave sequence under `docs/plans/waves/`
-- store the original request, generated spec, rendered markdown, and final result under `.wave/adhoc/<projectId>/runs/<run-id>/` for explicit projects, while the implicit default project keeps the legacy layout
-- keep runtime state isolated under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/`
-- extend trace metadata with `runKind: adhoc` and `runId`
-
-Design constraints:
-
-- reuse the planner and launcher instead of building a second runtime
-- treat ad-hoc as a transient single-run execution unit, not a fake roadmap wave
-- do not let ad-hoc completion mutate normal `completedWaves` lane state
-- give `wave coord`, `wave feedback`, and future replay or reporting flows a way to target `--run <id>`
-- promote numbered roadmap artifacts from the stored ad-hoc spec instead of recomputing them from the current project profile
-
-Why this matters:
-
-- many real operator requests are one-off bugfix, investigation, doc, infra, or release tasks
-- the framework's coordination, closure, and traceability should apply to ad-hoc work too
-- isolated ad-hoc runs preserve auditability without polluting the long-lived roadmap
-
-## Phase 3: Forward Replanning
-
-Add `wave update --from-wave <n>`.
-
-Rules:
-
-- closed waves are immutable
-- the current open wave and later waves may be regenerated
-- replanning must record what changed and why
-- new repo state, new user intent, and refreshed research may all trigger a replan
-
-Outputs:
-
-- updated draft JSON specs
-- regenerated markdown waves
-- a short replan summary for operator review
-
-Why this matters:
-
-- multi-wave plans drift as code lands
-- research and infra assumptions change
-- forward-only replanning preserves auditability without pretending older waves never existed
-
-## Phase 4: Infra and Deploy-Aware Planning
-
-Infra and deploy roles need typed environment context, not free-form prompt notes only.
-
-Project profile should support typed deploy providers with a `custom` escape hatch:
-
-- `railway-mcp`
-- `railway-cli`
-- `docker-compose`
-- `kubernetes`
-- `ssh-manual`
-- `custom`
-
-Planner-generated infra or deploy roles should know:
-
-- which environment they own
-- which substrate is authoritative
-- what credentials or executors are expected
-- what validation commands prove readiness
-- what rollback or recovery guidance applies
-
-This is especially important for `dark-factory` mode. Fully autonomous infra work should require stronger environment modeling than human-overseen work.
-
-## Phase 5: Oversight and Dark-Factory Modes
-
-Execution posture must be explicit plan data.
-
-Default:
-
-- `oversight`
-
-Opt-in:
-
-- `dark-factory`
-
-`oversight` means:
-
-- human checkpoints remain normal for live mutation, deploy, release, or risky infra work
-- the planner should generate explicit review gates
-
-`dark-factory` means:
-
-- the wave is intended to run end-to-end without routine human approvals
-- deploy environment, validation, rollback, and closure signals must be stricter
-- missing environment context is a planning error, not a runtime surprise
-
-## Phase 6: Coordination and Integration Upgrades
-
-The runtime already has strong coordination primitives, but the roadmap should still push these areas:
-
-- keep the canonical authority set explicit and the markdown board as a rendered view
-- keep compiled per-agent inboxes and shared summaries central to prompt construction
-- strengthen the integration steward output as the single closure-ready synthesis artifact
-- add `wave lint` for ownership, component promotion, runtime mix, deploy environment, and closure completeness
-- expand replay scenarios for replanning, autonomy modes, and infra-heavy waves
-
-## Additional Features Worth Scheduling
-
-- template packs for common wave shapes: implementation, QA, infra, release, migration
-- doc-delta extraction plus changelog or release-note queues when waves change public behavior
-- executor and credential preflight checks before launch
-- project-profile-aware defaults for lane, template, terminal surface, and oversight mode
-- richer branch and PR guidance in draft specs when the wave is release or deploy oriented
-- benchmark scenarios that compare oversight vs dark-factory outcomes
-
-## Research Notes
-
-The direction above is consistent with the local source set and the current external references:
-
-- OpenAI, “Harness engineering: leveraging Codex in an agent-first world”
-  - repository-local plans and environment design matter more than prompt-only control
-- Anthropic, “Effective harnesses for long-running agents”
-  - first-run initialization and durable progress artifacts are critical
-- DOVA
-  - deliberation-first orchestration and transparent intermediate state support better refinement loops
-- Silo-Bench
-  - communication alone is not enough; integration quality is the real bottleneck
-- Evaluating AGENTS.md
-  - repository-level context files help, but they should complement executable and versioned planning artifacts rather than replace them
-
-## Immediate Recommendation
-
-The next shipping sequence should be:
-
-1. planner foundation
-2. ad-hoc task runs on the same substrate
-3. forward replanning
-4. typed infra and deploy planning
-5. explicit oversight vs dark-factory workflows
-6. stronger linting, replay, and benchmark coverage
-
-That sequence keeps the current harness intact while making planning, execution posture, and infra ownership much more explicit and durable.
+1. Ship `0.9.2` with the sandbox/runtime hardening and aligned docs.
+2. Maintain this Node package for bug fixes, compatibility, operational hardening, and release-surface sync rather than a broad new feature wave.
+3. Move long-term execution investment to the LEAPclaw + Go + Temporal architecture and the Rust standalone runtime.

package/package.json

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

package/releases/manifest.json

@@ -2,6 +2,44 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.9.2",
+      "date": "2026-03-29",
+      "summary": "0.9.2 release cut for the documented Corridor and Wave Control surface, plus aligned publish artifacts.",
+      "features": [
+        "The packaged version now advances to `0.9.2` so the documented Corridor, Wave Control auth, and security surfaces can be tagged and published without colliding with the existing `0.9.1` npm release and git tag.",
+        "Release docs, migration guidance, runtime-config docs, coordination docs, Wave Control docs, package publishing docs, tracked install-state fixtures, and the release manifest now all point at the same `0.9.2` surface.",
+        "The shipped versioned operating guide is now `docs/guides/recommendations-0.9.2.md`, and starter install seeding plus install regression coverage now use that exact path.",
+        "Planner migration guidance and the `planner-agentic` bundle placeholder remain part of the shipped current-surface docs so adopted repos still have one aligned upgrade target."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.9.2` release surface.",
+        "Push the `v0.9.2` tag after the release commit so the GitHub publish workflow can publish the matching npm package version.",
+        "If your repo copied starter docs or runbooks, sync `README.md`, `docs/README.md`, `docs/plans/current-state.md`, `docs/plans/migration.md`, `docs/reference/coordination-and-closure.md`, `docs/reference/runtime-config/README.md`, `docs/reference/corridor.md`, `docs/reference/wave-control.md`, and `docs/guides/recommendations-0.9.2.md` so local guidance matches the packaged release."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.9.1",
+      "date": "2026-03-29",
+      "summary": "Detached process-backed agent execution, authenticated Wave Control, Corridor-backed security context, and 0.9.1 release-surface alignment.",
+      "features": [
+        "Live agent execution now uses detached process runners by default instead of per-agent tmux execution sessions, which reduces tmux churn and lowers memory use during wide orchestration bursts while keeping tmux as an optional dashboard projection layer.",
+        "The sandbox-facing path is now `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach`, with exact-context lookup, read-side launcher-status reconciliation, progress journaling, degraded-run handling, and log-follow attach behavior suited to LEAPclaw, OpenClaw, Nemoshell, and similar short-lived exec environments.",
+        "Supervisor recovery now relies on run-owned terminal artifacts and finalized progress instead of lane-global completion history, preserving the correct remaining wave range and final active wave during multi-wave reruns and launcher-loss recovery.",
+        "Ordinary runs, closure runs, and resident orchestrator runs now all preserve process-runtime metadata for timeout and cleanup, while process-backed resident orchestrators terminate cleanly and rate-limit retry detection stays scoped to the current attempt output.",
+        "Owned `wave-control` deployments now expose the shipped auth surface: Stack-backed browser access, Wave-managed approval states and provider grants, PATs, dedicated service tokens, encrypted per-user credential storage, runtime env leasing, and the separate `services/wave-control-web` frontend.",
+        "Corridor is now documented as a first-class security input with `direct`, `broker`, and `hybrid` runtime modes, normalized per-wave security artifacts, owned-path matching rules, and closure gating that can fail before integration on fetch failures or matched blocking findings.",
+        "Planner migration guidance and the `planner-agentic` bundle placeholder remain part of the shipped current-surface docs so adopted repos still have one aligned upgrade target.",
+        "A dedicated setup guide now ships for sandboxed and containerized operation, and README, migration docs, terminal-surface docs, runtime-config docs, coordination docs, Wave Control docs, the new Corridor reference, and the renamed recommendations guide `docs/guides/recommendations-0.9.1.md` now describe the same current release surface."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.9.1` release surface.",
+        "If your repo runs Wave inside LEAPclaw, OpenClaw, Nemoshell, Docker, or another short-lived exec sandbox, move long-running orchestration to `wave supervise`, use `wave submit/status/wait/attach` from disposable clients, and set Codex sandbox defaults in `wave.config.json` instead of relying on per-command overrides.",
+        "If your repo copied starter docs or runbooks, sync `README.md`, `docs/README.md`, `docs/plans/current-state.md`, `docs/plans/migration.md`, `docs/reference/coordination-and-closure.md`, `docs/reference/runtime-config/README.md`, `docs/reference/corridor.md`, `docs/reference/wave-control.md`, `docs/guides/sandboxed-environments.md`, `docs/guides/terminal-surfaces.md`, and `docs/guides/recommendations-0.9.1.md` so local guidance matches the packaged release."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.9.0",
       "date": "2026-03-28",

package/scripts/wave-cli-bootstrap.mjs

@@ -1,4 +1,13 @@
 import path from "node:path";
+import fs from "node:fs";
+
+const ALLOWLISTED_ENV_FILE_KEYS = new Set([
+  "CONTEXT7_API_KEY",
+  "CORRIDOR_API_TOKEN",
+  "CORRIDOR_API_KEY",
+  "WAVE_API_TOKEN",
+  "WAVE_CONTROL_AUTH_TOKEN",
+]);
 
 function stripRepoRootArg(argv) {
   const normalizedArgs = [];
@@ -22,6 +31,48 @@ function stripRepoRootArg(argv) {
   return normalizedArgs;
 }
 
+function parseEnvLine(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return null;
+  }
+  const exportPrefix = trimmed.startsWith("export ") ? trimmed.slice("export ".length).trim() : trimmed;
+  const equalsIndex = exportPrefix.indexOf("=");
+  if (equalsIndex <= 0) {
+    return null;
+  }
+  const key = exportPrefix.slice(0, equalsIndex).trim();
+  let value = exportPrefix.slice(equalsIndex + 1).trim();
+  if (!ALLOWLISTED_ENV_FILE_KEYS.has(key)) {
+    return null;
+  }
+  if (
+    (value.startsWith("\"") && value.endsWith("\"")) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1);
+  }
+  return { key, value };
+}
+
+function loadRepoLocalEnv() {
+  const repoRoot = path.resolve(process.env.WAVE_REPO_ROOT || process.cwd());
+  const envPath = path.join(repoRoot, ".env.local");
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+  const lines = fs.readFileSync(envPath, "utf8").split(/\r?\n/);
+  for (const line of lines) {
+    const entry = parseEnvLine(line);
+    if (!entry || process.env[entry.key]) {
+      continue;
+    }
+    process.env[entry.key] = entry.value;
+  }
+}
+
 export function bootstrapWaveArgs(argv) {
-  return stripRepoRootArg(Array.isArray(argv) ? argv : []);
+  const normalizedArgs = stripRepoRootArg(Array.isArray(argv) ? argv : []);
+  loadRepoLocalEnv();
+  return normalizedArgs;
 }