feat(distribution): evaluate a Node.js/TypeScript client and npm package #186

Goal

Determine whether session-peer should offer a supported npm package for Node.js/TypeScript users and, only after choosing an explicit architecture, implement and publish that package. codex-unlock is already a separate TypeScript/npm product; this issue concerns session-peer.

First decision: what does npm install provide?

Compare and document at least these options before coding a public package:

1. A thin TypeScript adapter that invokes an explicitly installed, version-checked Python session-peer CLI (no hidden Python installation or runtime download).
2. An independently implemented Node.js CLI/client with no Python requirement.
3. No npm package if demand does not justify a second security-sensitive runtime.

The chosen package must state its platform and runtime prerequisites, ownership/update model, and feature scope. Do not label a Python-dependent wrapper as a Python-free implementation. Do not port or replace the hosted Relay service as part of this issue.

Compatibility and safety gates

• Keep Python v1 CLI/JSON compatibility as the reference contract. Define a cross-runtime conformance suite using the existing compatibility fixtures and tests before any native port.
• Preserve the distinction between target discovery, dry-run validation, submission/queueing, actual consumption/ACK, and unknown outcomes. Never retry an uncertain send automatically.
• Preserve target identity and live-writer checks, SSH destination validation, reply-route behavior, output schema and exit semantics, and the local/SSH/paired-device security boundaries for whichever features are claimed supported. Unsupported features must fail explicitly, not silently degrade.
• Exercise macOS, Linux, and Windows only where the package claims support; include real native inbox/queue integration tests rather than only mocks. Keep tokens, keys, and message bodies out of diagnostics.
• If publishing: use a fixed, reproducible npm artifact; verify package contents, clean install, provenance/checksums as applicable, version mapping to the Python runtime, and uninstall behavior. The package must not silently install Python, skills, or operating services.

Release boundary

Start with a bounded prototype or design decision. A full CLI rewrite and simultaneous protocol maintenance are not assumed or approved by opening this issue. Keep the stable Python CLI and Relay service unchanged until conformance evidence and a separate release decision exist.

Context: session-peer v1.0.0 uses a dependency-free Python core CLI that can run on SSH destinations as the same script; optional MCP and encrypted Relay paths have separate dependencies. A parallel Node implementation would introduce a second implementation of the messaging and security contracts, so an npm install path must justify that cost.