Historical engineering record

This page preserves the design, plan or acceptance evidence for its recorded implementation stage. Earlier behavior, proposed capabilities and old deployment settings do not supersede the current Workspace guide or release history.

Web-first npm 3.0 Implementation Plan

For agentic workers: Use superpowers:executing-plans; implement inline. User explicitly requests autonomous decisions without questions. Retain changes in the current checkout for review; no release actions.

Goal: A small, independently installable Web npm product with source Plugin compatibility. Architecture: Separate npm/Legacy CLI; shared HTTP transport with Workspace/Inspector data factories and separate operation maps. Exact tracked-source packaging, no generated dist. Tech Stack: Node ESM, existing node-pty and xterm; no new production dependencies. Spec: docs/superpowers/specs/2026-10-08-web-first-v3-design.md

Global Constraints

• npm 3.0.0; Plugin version independent; retain Node >=18 unless real tests justify a change.
• Preserve double terminals, persisted task/session ownership, localhost/token/path/input guards.
• No real model calls; isolated test homes; no publish/push/tag/release/merge/workflow dispatch.

Review Focus

• Executable/script paths and arguments with spaces must remain distinct argv entries.
• Old Plugin installation must find its complete source Legacy runtime rather than npm 3.
• Forgotten dynamic Session Host/helper resources must be present in --ignore-scripts tarballs.
• Cross-project/session targeting must not attach unrelated sessions.
• Server restart must reconnect existing hosts without spawning duplicate agents.

Task 1: Capture baseline and dependency boundaries

• [x] Measure pack metadata, isolated install disk, startup samples and loaded module graph before edits.
• [x] Preserve results in docs/releases and review all listed runtime seams.

Task 2: Separate Web runtime

• [x] Add failing Web distribution/operation/import regression tests and run them.
• [x] Split CLI, HTTP data factories and gateway operations; retain source Legacy paths and Plugin resolver.
• [x] Extract minimal Workspace initialization; retain stable Adapter/PTY lifecycle and guards.
• [x] Run Web/session/message tests; update source-only tests to explicit Legacy entry.

Task 3: npm package and release verification

• [x] Set version/lockfile/explicit payload/exports; reject Legacy commands with migration help.
• [x] Replace Plugin-based tarball checks with independent production installation and mock Workspace acceptance.
• [x] Verify payload absence, all imports/assets and owned-host cleanup; add negative artifact tests.
• [x] Keep manual OIDC release; hand exact verified tarball to publish job; add platform/Node CI.

Task 4: Documentation, measurements and regression

• [x] Update bilingual README, changelog, repository distribution guidance and directly affected docs/tests.
• [x] Execute Web/Legacy/Plugin/MCP regressions and isolated artifact verification.
• [x] Measure final pack/install/startup; record exact comparison, sources of size and platform limits.
• [x] Review changes, fix findings, record release readiness and manual instructions without releasing.

Completion evidence

See docs/releases/v3-web-first.md. Inline implementation retained in the current checkout. Final independent review: Windows loader URL and fixture-environment findings resolved; child-owned IPC change accepted. Final full regression 374/374, focused check 176/176; real isolated tarball acceptance on local Node 18/22/24. Hosted Windows/Linux CI and publishing remain explicitly unexecuted.

Integration follow-up — 2026-10-08

After implementation and verification, the user explicitly requested push, authorizing a source commit and push to the existing branch. npm publishing, version tags, GitHub Releases and release-workflow dispatch remain outside this authorization.