npm install of both pkg.pr.new previews hard-fails with ERESOLVE: 0.0.0-preview-<sha> does not satisfy rsc-runtime peer range agent-bundle@^0.1.0

[ScriptedAlchemy]

Channel: pkg.pr.new previews (the documented interim release channel, docs/preview-packages.md), published by .github/workflows/package-preview.yml via pkg-pr-new@0.0.88 publish --previewVersion --no-compact --no-template. Reproduced at preview sha 4e546516.

What happens

docs/preview-packages.md says pkg.pr.new is the way to consume these packages until npm publishing starts, and tells consumers to install both packages from preview URLs. Doing exactly that with npm hard-fails on the second install: previews are versioned 0.0.0-preview-<sha>, which does not satisfy the agent-bundle@"^0.1.0" peer range that @agent-bundle/rsc-runtime ships even in its preview tarball.

Reproduced today in a clean directory:

mkdir preview-repro && cd preview-repro && npm init -y
npm install --save-dev 'https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@4e546516'   # ok
npm install 'https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/rsc-runtime@4e546516' react@19.2.8

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error Found: agent-bundle@0.0.0-preview-4e54651
npm error node_modules/agent-bundle
npm error   dev agent-bundle@"https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@4e546516" from the root project
npm error
npm error Could not resolve dependency:
npm error peer agent-bundle@"^0.1.0" from @agent-bundle/rsc-runtime@0.0.0-preview-4e54651
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps

pnpm reports the same mismatch as a warning and proceeds, so this is an npm-specific hard failure — but npm is the package manager the install docs lead with.

Why it matters

Every npm consumer of the documented install path hits this on their first install of the runtime — it is the very first experience of adopting the framework from its official channel. The consumer that surfaced this (movie-library, a 42-tool plugin port pinning both preview URLs in package.json) had to install with --legacy-peer-deps and commit a lockfile produced under that mode. The escape hatch is also a blunt one: --legacy-peer-deps disables peer resolution for the entire install, so real conflicts (say, against the react@"^19.2.0" peer) get silently accepted too.

Current workaround

Documented in docs/preview-packages.md: add --legacy-peer-deps for npm; pnpm warns and proceeds.

Suggested fix directions (strongest first)

1. Add --peerDeps to preview:publish. The pinned pkg-pr-new@0.0.88 supports it: "handle peerDependencies by setting the workspace version instead of what has been set in the peerDeps itself." That rewrites the preview tarball's peer range to the actual preview version, so a matched pair of previews installs cleanly with stock npm — and a mismatched pair (two different shas) correctly fails, which is a better signal than today. Preview-only; the manifests destined for npm are untouched. One caveat worth checking during implementation: --previewVersion's own help claims "cross-package peerDependencies are updated to match", yet the tarball published without --peerDeps demonstrably still carries ^0.1.0 — if adding the flag doesn't fix it either, that's an upstream pkg.pr.new bug worth reporting.
2. Widen the peer range in packages/rsc-runtime/package.json. Prerelease wildcards are not valid npm semver (0.0.0-preview-* matches nothing), but this verified range works: ">=0.0.0-preview <0.0.1 || ^0.1.0" — it matches 0.0.0-preview-4e546516 and still matches 0.1.3. Tradeoffs: the preview clause ships in the real manifest once npm publishing starts unless stripped at release, and it admits any preview sha, so mixed-sha preview pairs install silently (losing even pnpm's warning).
3. Bless the status quo. Keep --legacy-peer-deps as the documented flow. Weakest: every new consumer still hits the hard ERESOLVE before finding the doc, and the flag's install-wide peer bypass masks unrelated conflicts.

Related: #42, #43, #44 — surfaced by the same consumer port (movie-library on preview 4e546516); this one is the install-time papercut on the channel those issues' repros depend on.

[ScriptedAlchemy]

Closed-issue re-audit (lane G4) — VERIFIED on main c94df11c; stale doc paragraph corrected.

• preview:publish still carries --peerDeps (root package.json), and .github/workflows/package-preview.yml runs it on every PR/main push.
• The peer topology changed since fix(release): rewrite preview peer ranges via --peerDeps so npm installs matched pkg.pr.new pairs cleanly #46: the runtime package is now @agent-bundle/runtime (feat!: rename the renderer package to @agent-bundle/runtime #139) and declares no agent-bundle peer (peers: react, react-dom, @rspack/core). The only cross-workspace peer is agent-bundle's optional "@agent-bundle/runtime": "*" (packages/agent-bundle/package.json L117–125), which --peerDeps rewrites to the exact preview version, so a same-sha pair still installs with stock npm and the original ERESOLVE cannot recur. create-agent-bundle declares no peers.
• docs/preview-packages.md still described the rewrite in the old direction (an agent-bundle peer inside the runtime tarball). PR fix(docs,test): closed-issue audit G4 — stale Claude cwd/preview-peer docs, restore rendered-skill docs, pin the #23 handshake queue #368 (merge c94df11c) corrects that paragraph to the current topology and names the pre-fix(release): rewrite preview peer ranges via --peerDeps so npm installs matched pkg.pr.new pairs cleanly #46 @agent-bundle/rsc-runtime tarballs as the only ones still needing --legacy-peer-deps. Not published here, per lane rules.