@chllming/wave-orchestration 0.9.0 → 0.9.1

package/docs/plans/sandbox-end-state-architecture.md

@@ -0,0 +1,153 @@
+# Sandbox End-State Architecture
+
+This document is the sandbox-runtime companion to [end-state-architecture.md](./end-state-architecture.md). The core architecture still applies: the canonical authority set remains wave definitions, the coordination log, and the control-plane event log. This page narrows that model to the execution environments that impose short-lived `exec` sessions, process ceilings, or terminal instability.
+
+The goal is straightforward: sandbox client commands must stay short and disposable, while long-running wave ownership moves to a durable supervisor that can survive launcher exit, sandbox timeout, and terminal churn.
+
+For the operator-facing setup flow in LEAPclaw, OpenClaw, Nemoshell, Docker, and similar environments, read [../guides/sandboxed-environments.md](../guides/sandboxed-environments.md). This page is the deeper design and authority-model reference.
+
+---
+
+## Problem Statement
+
+Sandboxed runtimes have failure modes that the generic architecture does not need to describe in detail:
+
+- the sandbox `exec` session may have a wall-clock timeout that is much shorter than a real wave
+- bursty `spawnSync` and `tmux` probes can hit `EAGAIN`, `EMFILE`, or related process pressure limits
+- the launcher process can die before child agents finish, leaving orphaned sessions and ambiguous status
+- a missing `tmux` session is not enough evidence that the actual agent process failed
+
+The shipped runtime now has an initial async supervisor wrapper plus forwarded closure-gap handling, but it does not yet satisfy the full sandbox ownership model described here.
+
+---
+
+## Target Command Model
+
+Sandbox-facing commands should follow an async submit/observe pattern:
+
+- `wave submit [launcher options]`
+  Validate the request, persist a run request, print a `runId`, and exit quickly.
+- `wave supervise`
+  Long-running daemon command that owns launch, monitoring, retry, adoption, and cleanup. This command is not intended to be bound to a short sandbox `exec` lifetime.
+- `wave status --run-id <id>`
+  Read canonical supervisor state for a run.
+- `wave wait --run-id <id> --timeout-seconds <n>`
+  Observe until a state change or timeout. Timing out never cancels the run.
+- `wave attach --run-id <id>`
+  Optional operator projection surface for `tmux` or another terminal UI. This is not a liveness authority.
+
+Compatibility rules:
+
+- `wave launch` remains the canonical full launcher surface for direct local execution and dry-run validation.
+- `wave autonomous` should submit and observe wave execution when it is used in sandbox-oriented flows.
+- `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` are the preferred sandbox-facing surface, even while some internals remain partial.
+
+---
+
+## Canonical Authority In Sandboxed Runs
+
+The canonical authority set does not change, but sandbox supervision adds one more durable runtime layer:
+
+- wave definitions remain authoritative for declared work, closure roles, proof artifacts, and task contracts
+- coordination and control-plane logs remain authoritative for workflow, lifecycle, proof, and blocker state
+- supervisor run state becomes the canonical record of daemon-owned runtime observation for a submitted run
+
+The supervisor-owned state should converge on this per-run structure under `.tmp/<lane>-wave-launcher/supervisor/runs/<runId>/`:
+
+- `request.json`
+  Immutable submitted request.
+- `state.json`
+  Current daemon-owned run snapshot, including `runId`, `status`, `submittedAt`, `startedAt`, `completedAt`, `launcherPid`, `supervisorId`, `leaseExpiresAt`, `terminalDisposition`, and the latest observed launcher status.
+- `events.jsonl`
+  Supervisor-local observation history for adoption, retries, reconciliation, and cleanup decisions.
+- `launcher-status.json`
+  Canonical launcher completion status written atomically by the detached launcher wrapper.
+- `launcher.log`
+  Human-facing log stream only.
+- `agents/<agentId>.runtime.json`
+  Agent runtime observation record with fields such as `pid`, `pgid`, `attempt`, `startedAt`, `lastHeartbeatAt`, `exitCode`, `exitReason`, `statusPath`, and optional projection metadata like `tmuxSessionName`.
+
+Authority rules:
+
+- `tmux` is projection-only
+- dashboards, summaries, inboxes, and board markdown remain projections only
+- missing `tmux` state cannot by itself fail a run and is warning-only telemetry
+- pid checks, heartbeats, and atomic status files outrank terminal presence for liveness
+
+---
+
+## Daemon Ownership, Adoption, And Process Control
+
+The end state requires one daemon-owned control path for long-running work:
+
+1. `wave submit` writes the request and exits.
+2. `wave supervise` claims or renews a lease, launches work, and records observed runtime facts.
+3. `wave status` and `wave wait` read canonical state only.
+4. If the daemon dies, a later daemon instance can adopt active runs after lease expiry and continue observation without relaunching healthy agents.
+
+The daemon must own:
+
+- bounded process launch concurrency
+- async retry with jittered backoff for `EAGAIN`, `EMFILE`, and `ENFILE`
+- orphan adoption after stale lease detection
+- conservative orphan cleanup only after lease expiry, stale heartbeat, and failed pid confirmation
+- reconciliation between launcher status files, live pid state, and control-plane events
+
+The daemon must not depend on:
+
+- repeated `spawnSync("tmux", "list-sessions")` calls in the steady-state wait loop
+- one sandbox client process staying alive for the full wave duration
+- terminal presence as the source of truth for agent or wave health
+
+---
+
+## Closure Semantics For Forwarded Proof Gaps
+
+Closure staging still runs in the normal order:
+
+`implementation + proof -> cont-EVAL -> security/A7 -> integration/A8 -> docs/A9 -> cont-QA/A0`
+
+Sandbox stability does not change closure authority, but the daemon must preserve one special case:
+
+- `wave-proof-gap` from a closure-stage agent is a forwarded soft blocker, not an immediate full-wave stop
+
+Forwarding rules:
+
+- if A7 returns `wave-proof-gap`, the daemon still dispatches A8, A9, and A0 with the gap included as structured input
+- if A8 returns `wave-proof-gap`, the daemon still dispatches A9 and A0
+- if A9 returns `wave-proof-gap`, the daemon still dispatches A0
+- later closure agents must evaluate the currently available artifacts and report what is true; they must not refuse to run only because an earlier closure-stage agent reported `wave-proof-gap`
+- the final wave disposition remains blocked until the forwarded closure gaps are resolved
+
+Non-forwardable closure failures remain hard stops. Examples include malformed outputs, missing proof envelopes, explicit integration blockers, or invalid marker formats.
+
+---
+
+## Current Implementation Status
+
+Already landed:
+
+- `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` exist as a file-backed async wrapper over the existing launcher
+- supervisor state now includes lease-backed daemon ownership, `events.jsonl`, exact lane-scoped lookup, and detached launcher-status reconciliation
+- agent runtime records now capture per-agent pid, heartbeat, runner metadata, terminal disposition, and attach or log-follow metadata for supervisor-owned runs
+- `wave autonomous` now submits and observes single-wave runs through the supervisor surface instead of binding them to one blocking launcher subprocess
+- closure-stage `wave-proof-gap` forwarding now continues later closure stages and records the blocker instead of failing the whole sweep immediately
+- retry planning now invalidates later closure reuse from the earliest forwarded closure-gap stage
+- agent execution now uses detached process runners by default, which lowers tmux session churn and memory pressure in wide fan-outs; tmux remains dashboard-only and `wave attach --agent` falls back to log following when no live session exists
+- launcher progress journaling now lets the supervisor recover finalized runs and safely resume the active wave without a repo-wide rescan
+
+Still missing for the true end state:
+
+- broader resume semantics beyond “restart the active wave with preserved control state”; recovery can now use finalized progress journals and canonical run-state completion, but multi-wave and auto-next recovery is still conservative
+- fully tmux-free live dashboard projection; dashboard attach now falls back to the last written dashboard file, but live dashboard sessions still use tmux today
+- full success inference from canonical runtime facts alone; the daemon still refuses to synthesize success from agent runtime files without either finalized progress or canonical run-state completion
+
+---
+
+## Remaining Gap Plan
+
+1. Implement supervisor lease, heartbeat, and stale-lock reclamation so a restarted daemon can adopt active runs without relaunching healthy work.
+2. Move liveness authority to pid, heartbeat, and atomic status files; keep `tmux` as projection-only and remove sync terminal probes from steady-state monitoring.
+3. Materialize supervisor events and per-agent runtime records as canonical daemon state, not only ad hoc wrapper files.
+4. Extend forwarded closure-gap handling into retry planning so the earliest forwarded gap invalidates later closure outputs for reuse while still preserving them for operator evidence.
+5. Converge sandbox-facing entrypoints so `submit/status/wait` become the default operator path and `autonomous` no longer owns a multi-hour blocking launcher process.

package/docs/reference/cli-reference.md

@@ -13,6 +13,8 @@ When a command targets lane-scoped runtime state, it also accepts `--project <id
 
 - Runtime:
   `wave launch`, `wave autonomous`, and `wave local` cover dry-run validation, live execution, and executor-specific prompt transport.
+- Sandbox async supervision:
+  `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` provide the sandbox-friendly submit-and-observe surface for long-running waves.
 - Operator control:
   `wave control` is the preferred surface for live status, tasks, reruns, proof bundles, and telemetry.
 - Compatibility and inspection:
@@ -43,7 +45,7 @@ Closure-role bindings do not have a CLI override surface. When a wave file decla
 | `--auto-next` | off | Start from next unfinished wave and continue |
 | `--resume-control-state` | off | Preserve the prior auto-generated relaunch plan instead of treating the launch as a fresh wave start |
 | `--executor <id>` | `codex` | Default executor: `codex`, `claude`, `opencode`, `local` |
-| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox isolation level |
+| `--codex-sandbox <mode>` | lane config | Codex sandbox isolation override; falls back to `danger-full-access` only when config is unset |
 | `--timeout-minutes <n>` | `240` | Max minutes to wait per wave |
 | `--max-retries-per-wave <n>` | `1` | Relaunch failed agents per wave |
 | `--agent-rate-limit-retries <n>` | `2` | Per-agent retries for 429 errors |
@@ -51,9 +53,9 @@ Closure-role bindings do not have a CLI override surface. When a wave file decla
 | `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max backoff delay for 429 |
 | `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
 | `--terminal-surface <mode>` | `vscode` | `tmux`, `vscode`, or `none` |
-| `--no-dashboard` | off | Disable per-wave tmux dashboard |
-| `--cleanup-sessions` | on | Kill lane tmux sessions after each wave |
-| `--keep-sessions` | off | Keep lane tmux sessions |
+| `--no-dashboard` | off | Disable the per-wave dashboard projection session |
+| `--cleanup-sessions` | on | Kill lane tmux dashboard and projection sessions after each wave |
+| `--keep-sessions` | off | Keep lane tmux dashboard and projection sessions |
 | `--keep-terminals` | off | Keep temporary terminal entries |
 | `--orchestrator-id <id>` | generated | Stable orchestrator identity |
 | `--orchestrator-board <path>` | default board path | Write coordination-board updates to a specific shared board |
@@ -80,7 +82,7 @@ wave autonomous [options]
 | `--project <id>` | config default | Project id |
 | `--lane <name>` | `main` | Lane name |
 | `--executor <id>` | lane config | `codex`, `claude`, or `opencode` (not `local`) |
-| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox mode |
+| `--codex-sandbox <mode>` | lane config | Codex sandbox override passed to launcher; falls back to `danger-full-access` only when config is unset |
 | `--timeout-minutes <n>` | `240` | Per-wave timeout passed to launcher |
 | `--max-retries-per-wave <n>` | `1` | Per-wave relaunches inside launcher |
 | `--max-attempts-per-wave <n>` | `1` | External attempts per wave |
@@ -91,9 +93,65 @@ wave autonomous [options]
 | `--orchestrator-id <id>` | `<lane>-autonomous` | Orchestrator identity |
 | `--resident-orchestrator` | off | Launch resident orchestrator for each wave |
 | `--dashboard` | off | Enable dashboards |
-| `--keep-sessions` | off | Keep tmux sessions between waves |
+| `--keep-sessions` | off | Keep tmux dashboard and projection sessions between waves |
 | `--keep-terminals` | off | Keep terminal entries between waves |
 
+When you run Wave in a sandbox with short-lived `exec` sessions, prefer the async supervisor surface instead of binding the whole run to one long-lived `wave autonomous` client process. The end-state sandbox model is documented in [../plans/sandbox-end-state-architecture.md](../plans/sandbox-end-state-architecture.md).
+
+## wave submit
+
+Submit a launcher request for daemon-owned execution and return quickly with a `runId`.
+
+``` 
+wave submit [launcher options] [--json]
+```
+
+Current implementation status: this is a file-backed wrapper over `wave-launcher.mjs` with daemon leases, exact-context lookup, launcher-status reconciliation, progress journaling, and process-backed agent execution. It is the preferred sandbox-facing entrypoint for LEAPclaw, OpenClaw, Nemoshell, Docker, and similar short-lived exec environments, even though the broader daemon convergence described in [../plans/sandbox-end-state-architecture.md](../plans/sandbox-end-state-architecture.md) is still conservative in some recovery paths.
+
+`wave submit` accepts the same launcher options you would pass to `wave launch`, for example `--project`, `--lane`, `--start-wave`, `--end-wave`, `--executor`, `--codex-sandbox`, `--timeout-minutes`, `--agent-launch-stagger-ms`, `--resident-orchestrator`, `--no-dashboard`, and `--dry-run`. Use `--json` when you want a structured payload containing `runId`, `project`, `lane`, optional `adhocRunId`, and `statePath`.
+
+For concrete setup guidance, read [../guides/sandboxed-environments.md](../guides/sandboxed-environments.md).
+
+## wave supervise
+
+Run the supervisor loop that claims queued submitted runs and reconciles launcher status.
+
+```
+wave supervise [--project <id>] [--lane <name>] [--once]
+```
+
+Use `--once` for a single reconciliation pass in tests or wrapper scripts. The shipped daemon now renews a lease, reconciles detached launcher status, and can adopt already-running submitted runs from the same lane-scoped supervisor root.
+
+## wave status
+
+Read the current supervisor-owned state for a submitted run.
+
+```
+wave status --run-id <id> --project <id> --lane <name> [--adhoc-run <id>] [--json]
+```
+
+Current implementation status: reads the thin file-backed supervisor state from the exact lane-scoped supervisor root. `--project` and `--lane` are required so status does not guess across unrelated state trees.
+
+## wave wait
+
+Wait for a submitted run to reach terminal state or until the wait timeout expires.
+
+```
+wave wait --run-id <id> --project <id> --lane <name> [--adhoc-run <id>] [--timeout-seconds <n>] [--json]
+```
+
+`wave wait` is observational only. Timing out does not cancel or kill the underlying run.
+
+## wave attach
+
+Attach to a projection for a submitted run.
+
+```
+wave attach --run-id <id> --project <id> --lane <name> [--adhoc-run <id>] (--agent <id> | --dashboard)
+```
+
+`--agent <id>` attaches to a live session only when the runtime record explicitly exposes one; otherwise it follows the recorded log, or prints the recent log tail if the agent is already terminal. `--dashboard` reuses the current lane dashboard attach surface and falls back to the last written dashboard file when no live dashboard session exists. Missing projections are treated as operator errors, not as run-health failures.
+
 ## wave control
 
 Unified operator control surface. Preferred over legacy `wave coord`, `wave retry`, and `wave proof`.
@@ -114,6 +172,10 @@ The JSON payload now includes:
   Versioned wave-level signal state for wrappers and external operators.
 - `signals.agents`
   Versioned per-agent signal state, including `shouldWake` plus any observed ack metadata.
+- `supervisor`
+  The most relevant lane-scoped supervisor run for this wave, including degraded states such as `launcher-lost-agents-running`, recovery fields such as `sessionBackend`, `recoveryState`, and `resumeAction`, plus any recorded per-agent runtime summary.
+- `forwardedClosureGaps`
+  Earliest-first forwarded `wave-proof-gap` records from the relaunch plan, including the stage key, originating agent, attempt, detail, and downstream closure targets.
 
 Starter repos also include `scripts/wave-status.sh` and `scripts/wave-watch.sh` as thin readers over this JSON payload. They use exit `0` for completed, `20` for input-required, `40` for failed, and `30` from `wave-watch.sh --until-change` when the signal changed but the wave stayed active. For the full wrapper contract, read [../guides/signal-wrappers.md](../guides/signal-wrappers.md).
 
@@ -505,6 +567,8 @@ wave dashboard --dashboard-file <path> [--project <id>] [--lane <lane>] [--messa
 wave dashboard --project <id> --lane <lane> --attach current|global
 ```
 
+`wave dashboard --attach current|global` attaches to the live dashboard session when one exists; otherwise it follows the last written dashboard JSON for that target.
+
 ## Workspace Commands
 
 **Initialize workspace:**
@@ -565,7 +629,7 @@ Interactive draft currently offers worker role kinds:
 - `research`
 - `security`
 
-Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.0` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
+Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.1` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
 
 ## Ad-Hoc Task Commands
 

package/docs/reference/coordination-and-closure.md

@@ -134,7 +134,7 @@ Practical rule:
 
 That means a targeted helper request only blocks while it remains open *and* still has blocking severity in coordination state.
 
-For the practical `0.9.0` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.0.md](../guides/recommendations-0.9.0.md).
+For the practical `0.9.1` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.1.md](../guides/recommendations-0.9.1.md).
 
 This page is documenting runtime semantics first. The important contract is that closure follows the durable coordination state, not that a particular human or agent used one exact command path to mutate it.
 

package/docs/reference/github-packages-setup.md

@@ -3,7 +3,7 @@
 Use this page only if you intentionally want the legacy GitHub Packages install path.
 
 GitHub's npm registry still requires authentication for installs from `npm.pkg.github.com`, even when the package and backing repository are public.
-This is now the optional authenticated fallback path. The primary public install path is npmjs. Maintainer npm publishing setup is documented in [npmjs-trusted-publishing.md](./npmjs-trusted-publishing.md).
+This is now the optional authenticated fallback path. The primary public install path is npmjs. Maintainer npm publishing setup is documented in [npmjs-token-publishing.md](./npmjs-token-publishing.md).
 
 ## `.npmrc`
 

package/docs/reference/migration-0.2-to-0.5.md

@@ -1,12 +1,12 @@
 ---
 title: "Wave Orchestration Migration Guide: 0.2 to 0.5"
-summary: "How to migrate a repository from the earlier 0.2 wave baseline to the current post-roadmap Wave model."
+summary: "How to migrate a repository from the earlier 0.2 wave baseline to the current Wave model."
 ---
 
 # Wave Orchestration Migration Guide: 0.2 to 0.5
 
 This guide explains how to migrate a repository from the earlier Wave
-Orchestration 0.2 baseline to the current post-roadmap Wave model.
+Orchestration 0.2 baseline to the current Wave model.
 
 Current mainline note:
 
@@ -20,10 +20,11 @@ It uses two concrete references:
 - the 0.2-style baseline in the sibling `~/slowfast.ai` repo
 - the current target shape in this standalone `wave-orchestration` repo
 
-This is a migration guide for the current architecture described in
-[Roadmap](../roadmap.md), not just a changelog of whatever happens to be landed
-in one point-in-time package build. This document is about the shipped runtime
-shape, not only the semver label.
+This is a migration guide for the current shipped architecture and release
+direction described across [docs/architecture/README.md](../architecture/README.md)
+and [Roadmap](../roadmap.md), not just a changelog of whatever happens to be
+landed in one point-in-time package build. This document is about the shipped
+runtime shape, not only the semver label.
 
 ## Baseline And Target
 
@@ -34,7 +35,8 @@ Use these files as the concrete examples while migrating:
 - 0.2 baseline wave example: `~/slowfast.ai/docs/plans/waves/wave-7.md`
 - current target config: [wave.config.json](../../wave.config.json)
 - current target sample wave: [wave-0.md](../plans/waves/wave-0.md)
-- current target architecture: [roadmap.md](../roadmap.md)
+- current target architecture: [architecture/README.md](../architecture/README.md)
+- current release direction: [roadmap.md](../roadmap.md)
 - current package workflow: [README.md](../../README.md)
 
 The migration is intentionally evolutionary:

package/docs/reference/npmjs-token-publishing.md

@@ -0,0 +1,53 @@
+# npmjs Token Publishing
+
+This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
+
+The current `0.9.1` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+
+## What This Repo Already Does
+
+- `package.json` no longer hardcodes GitHub Packages as the publish registry.
+- `publish-npm.yml` publishes tagged releases to `https://registry.npmjs.org`.
+- `publish-package.yml` still publishes to GitHub Packages explicitly, so both registries can coexist.
+- `publish-npm.yml` expects `NPM_TOKEN` in GitHub Actions secrets.
+- The public install path is already npmjs; GitHub Packages remains the authenticated fallback path.
+
+## One-Time npm Setup
+
+1. Create an npm granular access token with:
+   - package or scope access for `@chllming/wave-orchestration`
+   - `Read and write` permission
+   - `Bypass 2FA` enabled
+2. In the GitHub repo `chllming/agent-wave-orchestrator`, add that token as an Actions secret named `NPM_TOKEN`.
+3. Rotate or revoke the token when no longer needed.
+
+## GitHub Workflow Behavior
+
+The npmjs workflow:
+
+- runs on GitHub-hosted runners
+- requires `contents: read`
+- installs dependencies with `pnpm install --frozen-lockfile`
+- runs `pnpm test`
+- publishes with `pnpm publish --access public --no-git-checks`
+- authenticates with `NODE_AUTH_TOKEN=${{ secrets.NPM_TOKEN }}`
+
+## Security Follow-Up
+
+After a successful npm publish:
+
+1. Keep the token scoped only to this package or scope.
+2. Rotate the token periodically.
+3. Revoke emergency or temporary tokens once they are no longer needed.
+
+If this repo later needs private npm dependencies during CI, consider a separate read-only install token rather than reusing the publish token.
+
+## Release Checklist
+
+1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
+2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
+3. Confirm the package version has been bumped and committed.
+4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
+5. Push the release commit and release tag, for example `v0.9.1`.
+6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
+7. Verify the npmjs publish completes successfully for the tagged source.

package/docs/reference/npmjs-trusted-publishing.md

@@ -1,53 +1,7 @@
-# npmjs Publishing
+# npmjs Trusted Publishing
 
-This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
+This repo does not currently use npm trusted publishing or OIDC-based publish credentials.
 
-The current `0.9.0` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The live npmjs workflow is token-based and documented in [npmjs-token-publishing.md](./npmjs-token-publishing.md).
 
-## What This Repo Already Does
-
-- `package.json` no longer hardcodes GitHub Packages as the publish registry.
-- `publish-npm.yml` publishes tagged releases to `https://registry.npmjs.org`.
-- `publish-package.yml` still publishes to GitHub Packages explicitly, so both registries can coexist.
-- `publish-npm.yml` expects `NPM_TOKEN` in GitHub Actions secrets.
-- The public install path is already npmjs; GitHub Packages remains the authenticated fallback path.
-
-## One-Time npm Setup
-
-1. Create an npm granular access token with:
-   - package or scope access for `@chllming/wave-orchestration`
-   - `Read and write` permission
-   - `Bypass 2FA` enabled
-2. In the GitHub repo `chllming/agent-wave-orchestrator`, add that token as an Actions secret named `NPM_TOKEN`.
-3. Rotate or revoke the token when no longer needed.
-
-## GitHub Workflow Behavior
-
-The npmjs workflow:
-
-- runs on GitHub-hosted runners
-- requires `contents: read`
-- installs dependencies with `pnpm install --frozen-lockfile`
-- runs `pnpm test`
-- publishes with `pnpm publish --access public --no-git-checks`
-- authenticates with `NODE_AUTH_TOKEN=${{ secrets.NPM_TOKEN }}`
-
-## Security Follow-Up
-
-After a successful npm publish:
-
-1. Keep the token scoped only to this package or scope.
-2. Rotate the token periodically.
-3. Revoke emergency or temporary tokens once they are no longer needed.
-
-If this repo later needs private npm dependencies during CI, consider a separate read-only install token rather than reusing the publish token.
-
-## Release Checklist
-
-1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
-2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
-3. Confirm the package version has been bumped and committed.
-4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
-5. Push the release commit and release tag, for example `v0.9.0`.
-6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
-7. Verify the npmjs publish completes successfully for the tagged source.
+If this repo later migrates to trusted publishing, replace this compatibility stub with the real OIDC procedure in the same change as the workflow update.