@chllming/wave-orchestration 0.9.1 → 0.9.3

package/docs/reference/runtime-config/README.md

@@ -8,6 +8,7 @@ Use it when you need the full supported surface for:
 - `defaultProject` and `projects.<projectId>`
 - `lanes.<lane>.executors`
 - `waveControl`
+- `externalProviders`
 - `executors.profiles.<profile>`
 - per-agent `### Executor` blocks inside a wave file
 
@@ -190,7 +191,7 @@ Practical guidance:
 - prefer `budget.minutes` for normal synthesis, integration, and closure work
 - use generic `budget.turns` as a planning hint, not a hard failure trigger
 - only set `claude.maxTurns` or `opencode.steps` when you deliberately want a hard ceiling for that runtime
-- see [../../guides/recommendations-0.9.1.md](../../guides/recommendations-0.9.1.md) for the recommended `0.9.1` operating stance that combines advisory turn budgets with softer non-proof coordination states
+- see [../../guides/recommendations-0.9.3.md](../../guides/recommendations-0.9.3.md) for the recommended `0.9.3` operating stance that combines advisory turn budgets with softer non-proof coordination states
 
 ## Runtime Pages
 
@@ -202,7 +203,7 @@ Practical guidance:
 
 `wave.config.json` may also declare a `waveControl` block for local-first telemetry delivery.
 
-Packaged defaults in `@chllming/wave-orchestration@0.9.1`:
+Packaged defaults in `@chllming/wave-orchestration@0.9.3`:
 
 - `endpoint`: `https://wave-control.up.railway.app/api/v1`
 - `reportMode`: `metadata-only`
@@ -219,7 +220,10 @@ Supported top-level fields:
 | `endpoint` | string | `https://wave-control.up.railway.app/api/v1` | Base URL for the Railway-hosted `services/wave-control` API |
 | `workspaceId` | string | derived from repo path | Stable workspace identity used across runs |
 | `projectId` | string | resolved project id | Stable project identity used for cross-workspace reporting and filtering |
-| `authTokenEnvVar` | string | `WAVE_CONTROL_AUTH_TOKEN` | Environment variable name holding the bearer token |
+| `authTokenEnvVar` | string | `WAVE_API_TOKEN` | Primary environment variable name holding the bearer token |
+| `authTokenEnvVars` | string[] | `["WAVE_API_TOKEN", "WAVE_CONTROL_AUTH_TOKEN"]` | Ordered fallback env var list consulted when Wave resolves a bearer token for owned Wave Control routes |
+| `credentialProviders` | string[] | `[]` | Allowlisted runtime credential leases requested from an owned Wave Control deployment before executor launch. Supported values: `openai`, `anthropic` |
+| `credentials` | `{ id, envVar }[]` | `[]` | Arbitrary per-user credential leases requested from an owned Wave Control deployment before executor launch |
 | `reportMode` | string | `metadata-only` | `disabled`, `metadata-only`, `metadata-plus-selected`, or `full-artifact-upload` |
 | `uploadArtifactKinds` | string[] | selected proof/trace/benchmark kinds | Artifact classes eligible for body upload when an artifact's upload policy requests a body |
 | `requestTimeoutMs` | integer | `5000` | Per-batch network timeout |
@@ -232,6 +236,8 @@ Supported top-level fields:
 
 Lane overrides may refine the same keys under `lanes.<lane>.waveControl` or `projects.<projectId>.lanes.<lane>.waveControl`.
 
+Wave resolves the Wave Control bearer token from `authTokenEnvVars` when that list is present. Otherwise it resolves `authTokenEnvVar` first and keeps `WAVE_CONTROL_AUTH_TOKEN` as a compatibility fallback.
+
 One-run override:
 
 - `wave launch --no-telemetry` disables Wave Control queueing and remote delivery for that launcher invocation without changing the repo config.
@@ -246,6 +252,8 @@ Example:
     "endpoint": "https://wave-control.up.railway.app/api/v1",
     "workspaceId": "wave-main",
     "projectId": "app",
+    "credentialProviders": ["openai"],
+    "credentials": [{ "id": "github_pat", "envVar": "GITHUB_TOKEN" }],
     "reportMode": "metadata-only",
     "uploadArtifactKinds": [
       "trace-run-metadata",
@@ -261,6 +269,56 @@ Runtime-emitted Wave Control events also attach:
 - `orchestratorId` from the active launcher or resident orchestrator
 - `runtimeVersion` from the installed Wave package metadata
 
+## External Providers
+
+Wave can resolve third-party auth directly in the repo runtime or through an owned Wave Control broker.
+
+```json
+{
+  "externalProviders": {
+    "context7": {
+      "mode": "direct",
+      "apiKeyEnvVar": "CONTEXT7_API_KEY"
+    },
+    "corridor": {
+      "enabled": false,
+      "mode": "direct",
+      "baseUrl": "https://app.corridor.dev/api",
+      "apiTokenEnvVar": "CORRIDOR_API_TOKEN",
+      "apiKeyFallbackEnvVar": "CORRIDOR_API_KEY",
+      "teamId": "team-id-for-direct-mode",
+      "projectId": "project-id-for-direct-mode",
+      "severityThreshold": "critical",
+      "findingStates": ["open", "potential"],
+      "requiredAtClosure": true
+    }
+  }
+}
+```
+
+- `direct`: use repo/runtime env vars directly
+- `broker`: use the owned Wave Control endpoint with `WAVE_API_TOKEN`
+- `hybrid`: try the broker first, then fall back to direct auth if broker setup fails or a broker request fails at runtime
+- direct Corridor mode requires both `teamId` and `projectId` in config; broker mode instead requires a matching `WAVE_BROKER_CORRIDOR_PROJECT_MAP` entry on the owned Wave Control deployment
+- Wave auto-loads an allowlisted repo-root `.env.local` for `CONTEXT7_API_KEY`, `CORRIDOR_API_TOKEN`, `CORRIDOR_API_KEY`, `WAVE_API_TOKEN`, and `WAVE_CONTROL_AUTH_TOKEN`
+- `wave doctor` now warns or fails early when brokered providers target the packaged default endpoint or no Wave Control auth token is available
+- Context7 remains fail-open
+- Corridor writes `.tmp/<lane>-wave-launcher/security/wave-<n>-corridor.json`, filters findings down to the wave's implementation-owned non-doc, non-`.tmp/`, non-markdown paths, and can fail closure when the fetch fails or matched findings meet the configured threshold
+- Broker mode is intended for self-hosted or team-owned Wave Control only; the packaged default endpoint is rejected as a provider-secret proxy
+- if `findingStates` is omitted or set to `[]`, Wave does not apply a state filter and the provider may return all states
+- for the full Corridor lifecycle, including broker mapping, generated artifact shape, and gate semantics, see [../corridor.md](../corridor.md)
+
+`waveControl.credentialProviders` is related but separate from `externalProviders`:
+
+- use `externalProviders.context7` and `externalProviders.corridor` for brokered or direct API access during planning / closure flows
+- use `waveControl.credentialProviders` only when an executor needs env vars leased into its runtime
+- use `waveControl.credentials` when an executor needs arbitrary user-owned secrets leased into env vars such as `GITHUB_TOKEN` or `NPM_TOKEN`
+- only `openai` and `anthropic` are valid leased providers today
+- `context7` and `corridor` remain broker-only and are never returned as raw env secrets
+- `waveControl.credentials[*].id` must match `/^[a-z0-9][a-z0-9._-]*$/`
+- `waveControl.credentials[*].envVar` must match `/^[A-Z_][A-Z0-9_]*$/`
+- when provider or arbitrary credentials are leased, Wave injects them into the live executor environment and redacts those keys in `launch-preview.json`
+
 Those fields are queryable in the `wave-control` service alongside `workspaceId`,
 `projectId`, `runKind`, `runId`, `lane`, and benchmark ids.
 

package/docs/reference/sample-waves.md

@@ -1,11 +1,11 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the shipped 0.9.1 authored surface, including the optional design-role path."
+summary: "Showcase-first sample waves that demonstrate the shipped 0.9.2 authored surface, including the optional design-role path."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the shipped `0.9.1` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the shipped `0.9.2` authored Wave surface.
 
 The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
 
@@ -17,7 +17,7 @@ All example `.tmp/main-wave-launcher/...` paths assume the implicit default proj
   Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.9.1` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.9.2` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
 - [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
   Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
@@ -46,7 +46,7 @@ All example `.tmp/main-wave-launcher/...` paths assume the implicit default proj
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened through `0.9.1`:
+Together these samples cover the main surfaces added or hardened through `0.9.2`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety
@@ -184,7 +184,7 @@ Adapt more aggressively when:
 ## Suggested Reading Order
 
 1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
-2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.9.1` surface.
+2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.9.2` surface.
 3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
 4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
 5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.

package/docs/reference/skills.md

@@ -124,7 +124,7 @@ Top-level and lane-local skill attachment use the same shape:
 
 Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
 
-Optional design workers in the shipped `0.9.1` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
+Optional design workers in the shipped `0.9.2` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
 
 Long-running agents that should stay resident and react only to orchestrator signal changes can add `signal-hygiene` explicitly in `### Skills`. That bundle is not auto-attached and is not meant for normal one-shot implementation agents.
 

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.