@chllming/wave-orchestration 0.9.1 → 0.9.2

package/docs/reference/wave-control.md

@@ -1,17 +1,48 @@
 ---
 title: "Wave Control"
-summary: "Canonical telemetry, artifact upload policy, and the local-first reporting contract for the Railway-hosted Wave control plane."
+summary: "Canonical telemetry, owned deployment auth, broker routes, credential leasing, and the local-first reporting contract for the Wave control plane."
 ---
 
 # Wave Control
 
-Wave Control is the telemetry and analysis plane for Wave runs.
+Wave Control is the control and observability plane for Wave runs.
 
 The design rule is:
 
 - local canonical state stays authoritative
 - remote reporting is best-effort
-- dashboards and markdown remain projections over typed local state
+- dashboards, summaries, and the browser UI remain projections over typed local or persisted state
+
+The packaged default endpoint is:
+
+- `https://wave-control.up.railway.app/api/v1`
+
+That packaged endpoint is for the default metadata-reporting surface. The owned-deployment features described below, such as provider brokering and runtime credential leasing, are intentionally meant for self-hosted or team-owned `wave-control` deployments.
+
+## Deployment Profiles
+
+### Packaged Default Endpoint
+
+This is the release default in `@chllming/wave-orchestration@0.9.2`.
+
+- receives local-first telemetry uploads
+- supports normal run and benchmark query surfaces
+- uses `reportMode: "metadata-only"` by default
+- does not act as a provider-secret broker for Corridor, Context7, or leased runtime credentials
+
+### Owned Deployment
+
+This is the full control-plane model backed by `services/wave-control/` and, optionally, `services/wave-control-web/`.
+
+An owned deployment can add:
+
+- Stack-authenticated browser access
+- Wave-managed app-user approval states and provider grants
+- personal access tokens for repo runtimes and API clients
+- dedicated service tokens for machine-admin workflows
+- encrypted per-user stored credentials with owner-scoped runtime leasing
+- broker routes for Context7 and Corridor
+- provider env leasing for deployment-owned OpenAI and Anthropic credentials
 
 ## What Gets Reported
 
@@ -90,24 +121,10 @@ Signals to preserve:
 - expert routing:
   targeted assignments, reroutes, and final recommendation ownership should remain visible
 - premature closure prevention:
-  gate snapshots, proof completeness, block reasons, reruns, and cont-QA reversal should be durable
+  gate snapshots, proof completeness, block reasons, reruns, and `cont-QA` reversal should be durable
 - benchmark trust:
   every benchmark item should distinguish capability from validity
 
-## Blocker And Recovery Metadata
-
-Wave Control should preserve the softer runtime policy, not flatten it away.
-
-In practice that means `coordination_record`, `task`, `gate`, `wave_run`, and `rerun_request` payloads should keep fields such as:
-
-- `blocking`
-- `blockerSeverity`
-- `recoverable`
-- `recoveryReason`
-- queued rerun request ids or resume targets
-
-That distinction matters because a wave that is `blocked` by a proof-critical gate is different from a wave that is `blocked` only long enough to surface a targeted recovery after timeout, max-turn, rate-limit, or missing-status failure. The control plane should let operators ask which barriers still stop closure outright and which ones were intentionally downgraded to advisory or stale context.
-
 ## Artifact Contract
 
 Selected artifacts are described with typed descriptors:
@@ -129,10 +146,10 @@ Upload policy meanings:
 
 - `local-only`: keep only the descriptor remotely
 - `metadata-only`: report path, hash, size, and presence only
-- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected` or `full-artifact-upload` **and** the artifact kind is allowed by `waveControl.uploadArtifactKinds`
+- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected` or `full-artifact-upload` and the artifact kind is allowed by `waveControl.uploadArtifactKinds`
 - `full`: upload the artifact body in `full-artifact-upload` flows; if `uploadArtifactKinds` is set, keep the kind allowlist aligned with that policy
 
-## Runtime Config
+## Repo Runtime Config
 
 `wave.config.json` can declare:
 
@@ -142,7 +159,9 @@ Upload policy meanings:
     "endpoint": "https://wave-control.up.railway.app/api/v1",
     "workspaceId": "my-workspace",
     "projectId": "app",
-    "authTokenEnvVar": "WAVE_CONTROL_AUTH_TOKEN",
+    "authTokenEnvVar": "WAVE_API_TOKEN",
+    "credentialProviders": ["openai"],
+    "credentials": [{ "id": "github_pat", "envVar": "GITHUB_TOKEN" }],
     "reportMode": "metadata-only",
     "uploadArtifactKinds": [
       "trace-run-metadata",
@@ -159,8 +178,8 @@ Packaged defaults:
 - enabled: `true`
 - report mode: `metadata-only`
 - identity defaults to the resolved project, lane, wave, run kind, and run id
-
-This package is distributed with the author's personal Wave Control endpoint enabled by default. Repos that do not want telemetry delivered there must explicitly opt out.
+- primary auth token env var: `WAVE_API_TOKEN`
+- compatibility fallback auth token env var: `WAVE_CONTROL_AUTH_TOKEN`
 
 Lane overrides may refine the same surface under `lanes.<lane>.waveControl` or `projects.<projectId>.lanes.<lane>.waveControl`.
 
@@ -182,6 +201,316 @@ Repo or project config may also opt out with:
 
 That suppresses the local telemetry spool and remote delivery for that invocation, while leaving the canonical runtime artifacts and local control-plane state intact.
 
+## API Surfaces
+
+Wave Control exposes five main route families.
+
+### Public
+
+- `GET /api/v1/health`
+- `GET /`
+
+### Ingest And Query
+
+- `POST /api/v1/ingest/batches`
+- `GET /api/v1/runs`
+- `GET /api/v1/run`
+- `GET /api/v1/benchmarks`
+- `GET /api/v1/benchmark`
+- `GET /api/v1/analytics/overview`
+- `GET /api/v1/artifact`
+- `POST /api/v1/artifacts/signed-upload`
+
+### Browser-App Routes
+
+- `GET /api/v1/app/session`
+- `POST /api/v1/app/access-request`
+- `GET /api/v1/app/me`
+- `GET /api/v1/app/overview`
+- `GET /api/v1/app/runs`
+- `GET /api/v1/app/run`
+- `GET /api/v1/app/benchmarks`
+- `GET /api/v1/app/benchmark`
+- `GET /api/v1/app/tokens`
+- `POST /api/v1/app/tokens`
+- `POST /api/v1/app/tokens/:id/revoke`
+- `GET /api/v1/app/admin/users`
+- `POST /api/v1/app/admin/users`
+- `POST /api/v1/app/admin/users/:id/state`
+- `POST /api/v1/app/admin/users/:id/role`
+- `POST /api/v1/app/admin/users/:id/providers`
+- `GET /api/v1/app/admin/users/:id/credentials`
+- `PUT /api/v1/app/admin/users/:id/credentials/:credentialId`
+- `DELETE /api/v1/app/admin/users/:id/credentials/:credentialId`
+
+### Provider And Runtime Lease Routes
+
+- `GET /api/v1/providers/context7/search`
+- `GET /api/v1/providers/context7/context`
+- `POST /api/v1/providers/corridor/context`
+- `POST /api/v1/runtime/provider-env`
+- `POST /api/v1/runtime/credential-env`
+
+### Service-Token Machine Routes
+
+- `GET /api/v1/service/session`
+- `GET /api/v1/service/users`
+- `POST /api/v1/service/users`
+- `POST /api/v1/service/users/:id/state`
+- `POST /api/v1/service/users/:id/role`
+- `POST /api/v1/service/users/:id/providers`
+- `GET /api/v1/service/users/:id/credentials`
+- `PUT /api/v1/service/users/:id/credentials/:credentialId`
+- `DELETE /api/v1/service/users/:id/credentials/:credentialId`
+- `POST /api/v1/service/users/:id/tokens`
+- `POST /api/v1/service/tokens/:id/revoke`
+
+## Access Model
+
+Route access depends on both principal type and scope.
+
+| Principal | How it authenticates | Main routes | Notes |
+| --- | --- | --- | --- |
+| Static env token | `WAVE_CONTROL_API_TOKEN(S)` or `WAVE_API_TOKEN(S)` | ingest, query, provider brokers, provider env leasing | trusted service-to-service path; bypasses provider-grant checks; does not use browser-app or service-token routes |
+| Stack user | `x-stack-access-token` plus internal-team membership | `/api/v1/app/*`; approved users may also call runtime lease routes | Stack proves identity first; Wave Control then applies `pending`, `approved`, `rejected`, or `revoked` plus `member`/`superuser` |
+| PAT | `Authorization: Bearer wave_pat_*` | ingest, provider brokers, provider env leasing, owner-scoped credential leasing | PAT scopes and provider grants are both enforced; owner approval state is re-checked on every request |
+| Service token | `WAVE_CONTROL_SERVICE_TOKENS_JSON` | `/api/v1/service/*` | machine-admin only; cannot use owner-scoped credential leasing |
+
+Two rules matter:
+
+1. scopes and provider grants are separate
+2. browser users do not receive `broker:read`
+
+That means:
+
+- a PAT needs `broker:read` plus the matching provider grant to use Corridor or Context7 broker routes
+- a PAT or approved browser user needs `credential:read` plus the matching provider grant to use `POST /api/v1/runtime/provider-env`
+- `POST /api/v1/runtime/credential-env` is owner-scoped and only works for an approved browser user or the owner's PAT
+- static env tokens can still use ingest, query, broker, and provider-env routes as trusted deployment credentials
+
+If `WAVE_CONTROL_REQUIRE_AUTH_FOR_READS=false`, the read/query routes may be public. Auth requirements for app, broker, lease, and service routes do not change.
+
+## Stack App-User Model
+
+Wave Control uses Stack as the browser login system, but it keeps its own authorization state on top of that identity.
+
+Required backend env for browser auth:
+
+- `WAVE_CONTROL_STACK_ENABLED=true`
+- `WAVE_CONTROL_STACK_PROJECT_ID`
+- `WAVE_CONTROL_STACK_PUBLISHABLE_CLIENT_KEY`
+- `STACK_SECRET_SERVER_KEY`
+- `WAVE_CONTROL_STACK_INTERNAL_TEAM_IDS`
+
+Flow:
+
+1. Stack authenticates the browser user.
+2. Wave Control verifies the user is a confirmed member of `WAVE_CONTROL_STACK_INTERNAL_TEAM_IDS`.
+3. Wave Control resolves or creates its own internal app-user record.
+4. That app-user record carries:
+   - `accessState`: `pending`, `approved`, `rejected`, or `revoked`
+   - `role`: `member` or `superuser`
+   - `providerGrants`: allowlisted provider ids such as `context7`, `corridor`, `openai`, or `anthropic`
+
+Bootstrap behavior:
+
+- `WAVE_CONTROL_BOOTSTRAP_SUPERUSER_EMAILS` auto-provisions approved superusers on first sign-in for listed emails
+- superusers automatically receive all provider grants
+- members receive only the grants explicitly assigned to them
+
+Important distinction:
+
+- Stack identity decides who is a real internal user
+- Wave Control app-user state decides who is approved and what they may do
+
+## Personal Access Tokens
+
+Wave Control PATs are opaque `wave_pat_*` tokens.
+
+The service stores:
+
+- only a SHA-256 hash of the token
+- metadata such as owner, scopes, creation time, last-used time, and revocation time
+
+The plaintext token is shown once at creation time.
+
+PAT rules:
+
+- allowlisted scopes: `broker:read`, `credential:read`, `ingest:write`
+- members may issue PATs for themselves
+- superusers may issue or revoke PATs for any approved user
+- unsupported scopes, including `*`, are rejected
+- PAT owners must be bound to a Stack user
+- PAT requests are clamped to the owner's current approval state and provider grants every time the token is used
+
+PATs are the intended token type for repo runtimes that need broker access or runtime env leasing without using a long-lived deployment-wide env token.
+
+## Service Tokens
+
+`WAVE_CONTROL_SERVICE_TOKENS_JSON` defines dedicated machine-admin tokens with `service:*` scopes.
+
+Example:
+
+```json
+[
+  {
+    "label": "ops-bot",
+    "token": "replace-me",
+    "scopes": ["service:read", "service:user:write", "service:credential:write", "service:token:write"]
+  }
+]
+```
+
+Service tokens are intentionally separate from PATs:
+
+- they access `/api/v1/service/*`
+- they can manage users, provider grants, credentials, and PAT issuance for bound users
+- they cannot impersonate a browser user
+- they cannot use the owner-scoped `POST /api/v1/runtime/credential-env` route
+
+## Credential Leasing
+
+Wave Control supports two different leasing models.
+
+### Provider Env Leasing
+
+`POST /api/v1/runtime/provider-env` returns deployment-owned provider secrets as runtime env vars.
+
+Current supported providers:
+
+- `openai` -> `OPENAI_API_KEY`
+- `anthropic` -> `ANTHROPIC_API_KEY`
+
+Requirements:
+
+- owned deployment only
+- provider is enabled on the deployment
+- caller has `credential:read`
+- caller holds the matching provider grant unless it is a trusted env token
+
+### Arbitrary Per-User Credential Leasing
+
+`POST /api/v1/runtime/credential-env` leases user-owned stored credentials under requested env var names.
+
+Example request:
+
+```json
+{
+  "credentials": [
+    { "id": "github_pat", "envVar": "GITHUB_TOKEN" }
+  ]
+}
+```
+
+Requirements:
+
+- `WAVE_CONTROL_SECRET_ENCRYPTION_KEY` must be configured as a base64-encoded 32-byte AES-256-GCM key
+- the caller must be the approved browser user or that user's PAT
+- service tokens and env tokens are rejected
+- the requested credential id must already exist for that owner
+
+Stored credentials are:
+
+- write-only through the admin and service management APIs
+- encrypted at rest
+- never returned through list endpoints
+- only revealed through explicit lease responses
+
+## Provider Brokers
+
+Broker routes are intended for owned deployments only.
+
+### Context7
+
+- `GET /api/v1/providers/context7/search`
+- `GET /api/v1/providers/context7/context`
+
+Requirements:
+
+- `WAVE_BROKER_OWNED_DEPLOYMENT=true`
+- `WAVE_BROKER_ENABLE_CONTEXT7=true`
+- `WAVE_BROKER_CONTEXT7_API_KEY`
+- PAT or env token with `broker:read`
+- matching `context7` provider grant for PAT callers
+
+### Corridor
+
+- `POST /api/v1/providers/corridor/context`
+
+Requirements:
+
+- `WAVE_BROKER_OWNED_DEPLOYMENT=true`
+- `WAVE_BROKER_ENABLE_CORRIDOR=true`
+- `WAVE_BROKER_CORRIDOR_API_TOKEN`
+- `WAVE_BROKER_CORRIDOR_PROJECT_MAP`
+- PAT or env token with `broker:read`
+- matching `corridor` provider grant for PAT callers
+
+Example project map:
+
+```json
+{
+  "app": {
+    "teamId": "team-uuid",
+    "projectId": "corridor-project-uuid"
+  }
+}
+```
+
+Example request:
+
+```json
+{
+  "projectId": "app",
+  "ownedPaths": ["src/auth", "src/session"],
+  "severityThreshold": "critical",
+  "findingStates": ["open", "potential"]
+}
+```
+
+Broker semantics:
+
+- if `findingStates` is omitted, the service defaults to `open` and `potential`
+- if the caller sends `findingStates: []`, the service queries all states
+- the service returns a normalized summary with `guardrails`, `matchedFindings`, `blockingFindings`, `blocking`, and `error`
+- upstream provider secrets never leave the owned deployment
+
+For the runtime-side lifecycle, owned-path matching, and closure semantics, see [corridor.md](./corridor.md).
+
+## Browser App
+
+The frontend package lives at `services/wave-control-web/`.
+
+It is a Vite/Lit app with Stack browser auth and a static shell.
+
+Frontend env:
+
+- `VITE_WAVE_CONTROL_API_BASE_URL`
+- `VITE_STACK_PROJECT_ID`
+- `VITE_STACK_PUBLISHABLE_CLIENT_KEY`
+- `WAVE_CONTROL_WEB_BASE_PATH` for non-root deploy paths
+
+Compatibility fallbacks:
+
+- `NEXT_PUBLIC_STACK_PROJECT_ID`
+- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
+
+`VITE_WAVE_CONTROL_API_BASE_URL` may point at either:
+
+- the Wave Control origin, such as `https://control.example.test`
+- or the full `/api/v1` base
+
+The frontend normalizes either form before appending route paths.
+
+Runtime behavior:
+
+- persists the Stack browser session across reloads
+- completes OAuth and magic-link callbacks on the same app path
+- only renders sign-in methods enabled in the Stack project
+- loads `/api/v1/app/session` first after sign-in
+- shows the request-access flow for internal users who are not yet approved
+- exposes a superuser-only Users tab for approvals, role changes, provider grants, and write-only user credential rotation
+
 ## Delivery Model
 
 Wave Control reporting should:
@@ -195,8 +524,10 @@ Wave Control reporting should:
 
 The Railway-hosted `services/wave-control` service is an analysis surface, not the scheduler of record.
 
-The service package lives under `services/wave-control/`.
+## Storage And Durability
+
+For durable telemetry retention, attach Railway Postgres to `wave-control` so the service receives `DATABASE_URL`.
+
+Without that variable, the service falls back to the in-memory store and only keeps data until the process restarts.
 
-For durable telemetry retention, attach Railway Postgres to `wave-control` so the
-service receives `DATABASE_URL`. Without that variable, the service falls back to the
-in-memory store and only keeps data until the process restarts.
+Optional object storage may be configured through the `WAVE_CONTROL_BUCKET_*` variables for larger inline artifact bodies and signed-download URLs.

package/docs/roadmap.md

@@ -2,39 +2,33 @@
 
 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.
 
-## Current Release: 0.9.1
+## Current Release: 0.9.2
 
-`0.9.1` is the runtime-hardening release.
+`0.9.2` is the current packaged surface.
 
-It focuses on:
+It includes:
 
 - 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
 
-## Next Release: Final Planned Feature Release On This Line
+## Near-Term Direction On This Node Line
 
-The next planned release after `0.9.1`, aside from bug fixes and release-surface maintenance, is the final feature release for this standalone Node-based line.
-
-That release is focused on Wave Control authentication:
-
-- token-based auth for `wave-control`
-- web auth for the Wave Control operator surface
-- a cleaner control-plane boundary between the local orchestrator runtime and authenticated operator access
-- documentation and setup guidance for protected control surfaces in local, containerized, and hosted environments
-
-After that release, this package should move into maintenance mode:
+This standalone Node line should now be treated as maintenance-oriented:
 
 - bug fixes
 - compatibility updates
+- operational hardening
 - documentation updates
 - release-surface alignment work
 
 ## Strategic Direction: LEAPclaw Execution Model
 
-After the Wave Control auth release, the main execution roadmap moves away from expanding this Node runtime and toward the LEAPclaw execution model.
+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.
 
 The target shape is:
 
@@ -62,7 +56,6 @@ That line is expected to carry:
 
 For this repository, the practical sequence is:
 
-1. Ship `0.9.1` with the sandbox/runtime hardening and aligned docs.
-2. Ship the Wave Control token/web auth release as the last planned feature release on this Node line.
-3. Keep this package maintained for bug fixes, compatibility, and release-surface sync.
-4. Move long-term execution investment to the LEAPclaw + Go + Temporal architecture and the Rust standalone runtime.
+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.1",
+  "version": "0.9.2",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,22 +2,41 @@
   "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, sandbox-safe supervisor hardening, lower memory pressure, and 0.9.1 release-surface alignment.",
+      "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, including Nemoshell and Docker guidance, while README, migration docs, terminal-surface docs, runtime-config docs, coordination docs, and the renamed recommendations guide `docs/guides/recommendations-0.9.1.md` now describe the same sandbox-safe release surface."
+        "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/guides/sandboxed-environments.md`, `docs/guides/terminal-surfaces.md`, and `docs/guides/recommendations-0.9.1.md` so local guidance matches the packaged release."
+        "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
     },

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