session-peer 0.1.0-preview.0 → 0.1.0

package/RELEASING.md

@@ -1,153 +1,118 @@
-# Releasing session-peer previews
-
-The package is publication-ready (`private:false`), not automatically published.
-Merging, pushing, tagging or publishing a GitHub release does not run publish.yml.
-Only an explicitly approved manual dispatch can upload. Python session-peer and
-its Relay release train remain independent.
-
-## Before the first dispatch
-
-1. Merge the reviewed preparation PR and require main's exact-commit `cli` CI
-   (`release gate`) to pass. Match versions in package.json, lockfile,
-   src/protocol.ts and four READMEs. Only `X.Y.Z-preview.N` versions and the
-   `preview` dist-tag are supported; stable publication needs another review.
-2. In GitHub Settings → Environments, create **npm** with at least one required
-   reviewer. Restrict deployments to protected main. A solo maintainer may also
-   be the dispatcher: this is explicit approval, not two-person separation.
-   Do not bypass protection. Preflight rejects missing environments or reviewer
-   rules. This PR does not create or relax environment protection.
-3. Confirm npm account 2FA, package-name ownership and creation permissions.
-   A registry 404 does not reserve the name. Review VALIDATION.md and architecture
-   coverage; historical real-TUI ACKs predate the command rename. Do not claim
-   full native-agent architecture coverage from CI fixtures.
-4. For the initial **0.1.0-preview.0 only**, repository secret **NPM_TOKEN** supplies
-   bootstrap authentication. Use a short-expiry, least-privilege granular token
-   permitting this new package. Noninteractive direct publication requires a token
-   allowed to bypass npm's 2FA prompt. Secret existence does not establish its
-   permissions. Do not weaken account policy automatically: stop if unsuitable
-   and use an approved local interactive first publish instead.
-   Never put credentials in files, logs, issues or chat. Builds/tests/packing
-   never receive this secret.
-5. Obtain final approval for the exact main commit, version and mode. A merged
-   preparation PR is not publication approval. Optional GitHub draft release
-   notes must target that same commit; the workflow creates no tag or release.
-   Runtime changes require separate reviewed evidence.
-
-## First package: bootstrap-token
-
-### Initial failed attempt (2026-09-27)
-
-[Run 36308424358](https://github.com/abruption/session-peer-ts/actions/runs/36308424358)
-attempted the old npm name `session-peer-ts@0.1.0-preview.0`. Build and artifact
-checks passed, but the registry refused the PUT with HTTP 403 / E_STAGE_REQUIRED:
-the supplied token could only stage, and the package did not exist. A Sigstore
-provenance entry was created before that rejection; it is not proof of npm
-publication. Both npm names returned 404 during the subsequent read-only check.
-
-The intended npm name is now **session-peer**; the GitHub repository remains
-**abruption/session-peer-ts**. Renaming does not fix the authentication restriction.
-Do not rerun the old workflow or switch it to staging: a new package cannot be
-created by staging. Before an approved new attempt, the owner must resolve the
-initial direct-publication authorization or perform an approved interactive
-first publish with 2FA. Do not disable 2FA, automatically replace credentials or
-assume changing a token option bypasses current npm policy. The stored secret's
-value and settings were not inspected. This PR does not reattempt publication.
-
-### Inputs after authentication is resolved
-
-Actions → **npm preview publication** → Run workflow → **main**:
-
-- mode: `bootstrap-token`
-- version: `0.1.0-preview.0`
-- confirmation: `session-peer@0.1.0-preview.0 bootstrap-token`
-
-Preflight requires current main SHA, successful exact-commit main CI and the
-protected npm environment. Bootstrap refuses **any existing registry package**
-under this name. The prepare job tests without publication credentials, packs
-twice, compares hashes, checks the allowlist and tests installation/uninstallation
-of the exact tarball. Its retained artifact includes tarball and manifest.json
-(commit, SHA-256 and SHA-512 integrity). Actions are pinned by commit; release
-builds use Node 24/npm 11.15.0 without dependency caches or lifecycle scripts.
-
-After environment approval, a fresh job downloads the artifact without rebuilding,
-rechecks main/CI/registry and validates its contents. Only one `npm publish`
-step receives NPM_TOKEN (`--tag preview --access public --provenance
---ignore-scripts`). OIDC permission is also granted for provenance. Upload
-network retries are disabled. Do not rerun failed or uncertain publication.
-
-Verification compares registry integrity and preview tag, rejects accidental
-latest promotion, requires registry attestation metadata, runs `npm audit
-signatures`, and fresh-installs/uninstalls the published version. Only a passed
-verification completes bootstrap release; a successful upload alone does not.
-Bounded read-only propagation checks are not upload retries.
-
-## Register npm Trusted Publisher after the first release
-
-npmjs.com → package **session-peer** → Settings → Trusted publishing:
-
-| Field | Value |
-| --- | --- |
-| Provider | GitHub Actions |
-| Organization or user | `abruption` |
-| Repository | `session-peer-ts` |
-| Workflow filename | `publish.yml` (no directory prefix) |
-| Environment name | `npm` |
-| Allowed actions | Stage-only: `npm stage publish`, not direct `npm publish` |
-
-The workflow must exist on main. npm does not validate the connection on save;
-validate it with the next authorized staged version. GitHub-hosted runners are
-required. Public GitHub + public npm OIDC publishing provides provenance.
-
-After verifying bootstrap and configuring trust, revoke its token in npm and
-remove GitHub NPM_TOKEN. Set npm publishing access to **Require two-factor
-authentication and disallow tokens**. These account changes need owner approval
-and are not performed by this workflow. trusted-stage never references NPM_TOKEN;
-an OIDC failure must not cause token fallback. Remove the bootstrap branch in a
-follow-up PR.
-
-## Later previews: trusted-stage
-
-Prepare a new immutable preview version through a PR. Dispatch main with mode
-`trusted-stage`, its exact version and confirmation
-`session-peer@<version> trusted-stage`. The same gates apply. The package must
-already exist; published versions are refused. One `npm stage publish` runs
-with OIDC and the preview tag.
-
-**A successful staged run is pending approval, not a public release.** Record its
-stage ID from npm output. Review its tarball against the retained manifest and
-approve with 2FA in npmjs.com or interactive `npm stage approve`. OIDC cannot
-approve, list or view stages. Public registry metadata cannot reveal pending
-stages, so collisions fail at the registry and need manual inspection, not retries.
-
-After approval, check out the exact source commit and download that run artifact
-into `release-dist/`. With Node 24 and npm 11.15.0:
+# Releasing session-peer
+
+Publication is manual. Merging, pushing, tagging or creating a GitHub release
+never dispatches `publish.yml`. Python session-peer and its Relay release train
+remain independent. The npm Trusted Publisher for `abruption/session-peer-ts`,
+`publish.yml`, environment `npm` allows `npm stage publish` only. The workflow
+uses OIDC and no npm token. The protected GitHub environment requires a reviewer
+and permits deployments from `main` only.
+
+## Verified preview and stable baseline — 2026-09-27
+
+`session-peer@0.1.0-preview.1` was staged from main commit
+`f65d3ee99cc26ff4a267aef84e31a308d034ac80` in
+[run 36313884100](https://github.com/abruption/session-peer-ts/actions/runs/36313884100)
+and published after a separate 2FA approval. The staged tarball matched the
+retained run artifact byte for byte. Public verification passed registry
+integrity, provenance metadata, `npm audit signatures`, fresh installation and
+uninstallation. The artifact SHA-256 was
+`d154beac93893b60b0695e5a6296e185beb8dbd05188ffe04befb74d29966110`;
+registry integrity is
+`sha512-h4SMvrQ/LWA9osd4EHIs9rSTqv1u+S3MXQAmn+yG/gZ9+7NwYMutq+Oa5K/0ggIq61Wfwdh11Cv+5YdEffiNMA==`.
+The `preview` tag points to preview.1. The existing `latest` tag still points
+to preview.0. No stable version has been published by this preparation PR.
+
+## Prepare 0.1.0 stable
+
+1. Merge the reviewed 0.1.0 preparation PR. Require successful `cli` CI on the
+   exact merged `main` commit, including the release gate and Windows Node 22/24.
+   Match `0.1.0` in package.json, lockfile, src/protocol.ts and all four READMEs.
+   Review [VALIDATION.md](VALIDATION.md): fixture CI and the historical real-TUI
+   ACKs have different scope. The stable candidate changes the version handshake
+   and release controls, not native delivery behavior.
+2. Confirm the `npm` environment still has a required reviewer and permits only
+   protected main. Confirm npm account 2FA, package ownership and the Trusted
+   Publisher's stage-only mapping above. Do not bypass environment protection.
+3. Read the public registry. `0.1.0` must be absent; `preview` must still point
+   to preview.1 and `latest` to preview.0. The published preview.1 integrity and
+   provenance must match the verified baseline above. Inspect pending stages with
+   `npm stage list session-peer` through an authenticated owner session;
+   public registry metadata cannot reveal them.
+4. Obtain final approval for the **exact main SHA**, `0.1.0` version and
+   `stable-stage` mode. A merged PR is not publication approval. The approval
+   must also cover promotion of npm `latest` to `0.1.0` when the stage is
+   approved. GitHub tag, release and fleet installation need separate decisions.
+
+Dispatch Actions → **npm staged publication** → Run workflow → **main**:
+
+- mode: `stable-stage`
+- version: `0.1.0`
+- confirmation: `session-peer@0.1.0 stable-stage`
+
+The prepare job requires exact-main CI and the protected npm environment. It
+checks the registry baseline, tests on Node 24/npm 11.15.0 without publish
+credentials, packs twice, compares hashes, checks the allowlist and installs and
+uninstalls the exact tarball in isolation. The retained `npm-release-<SHA>`
+artifact contains the tarball and manifest.json with commit, SHA-256 and
+SHA-512 integrity. Actions are pinned by commit; no dependency cache or package
+lifecycle scripts are used.
+
+After environment review, the publish job downloads that artifact without
+rebuilding and repeats the main/CI/registry and artifact checks. Only one
+`npm stage publish ... --tag latest --provenance --ignore-scripts` step runs with
+OIDC. Network upload retries are disabled. **A successful staged workflow is
+pending npm approval, not a public release.** Record the stage ID. Download its
+tarball, compare it byte for byte with the retained run artifact, and obtain a
+separate final approval before the owner approves that exact stage with 2FA on
+npmjs.com or through interactive `npm stage approve <stage-id>`. OIDC cannot
+approve, list or view stages.
+
+After 2FA approval, check out the exact source commit and download the run
+artifact into `release-dist/`. With Node 24 and npm 11.15.0:
 
 ```sh
 node scripts/release.mjs artifact
 node scripts/release.mjs verify
 ```
 
-Neither command publishes. verify uses public reads, an isolated no-lifecycle
-install and signature checks; it needs no publish token. Do not announce release
-completion until it passes. Stable promotion and fleet installation remain
-separate decisions.
+Neither command publishes. Verification requires the public 0.1.0 integrity,
+registry provenance metadata, `latest: 0.1.0`, unchanged
+`preview: 0.1.0-preview.1`, npm signature audit, and fresh install/uninstall. Announce
+stable availability only after this passes. Review a Git tag, GitHub release or
+fleet rollout separately.
+
+## Later previews
+
+The manual workflow still accepts `trusted-stage` for a new immutable preview
+version with package `publishConfig.tag: preview`; it stages with OIDC and never
+directly publishes. Preview preflight refuses an already published version and
+requires `latest` to be stable or absent. The historical preview.1 exception
+required its exact legacy `latest: 0.1.0-preview.0` and cannot authorize a
+future version. Every stage needs artifact review and a separate 2FA approval.
 
 ## Failure handling
 
-Missing/invalid token, 2FA challenge, missing environment, bad OIDC mapping,
-non-404 registry errors, stale main, conflicting versions, upload timeout and
-hash mismatch are stop conditions. Never automatically change auth mode, retry
-upload, unpublish, move a tag, reuse a version or promote latest to obtain green
-checks. Inspect registry/staged state and retained evidence first. Read-only
-verification of the exact artifact may be repeated; publication may not.
-A broken/partial public release requires a reviewed new version and approval.
+Missing environment protection, bad OIDC mapping, stale main, failed CI,
+conflicting version or tag state, an existing stage, upload timeout, hash
+mismatch and non-404 registry errors are stop conditions. Do not automatically
+retry an uncertain upload, change authentication mode, move a tag, unpublish,
+reuse a version or approve a stage. Inspect the run, stage and public registry
+first. Registry propagation may lag a successful approval: `verify` performs
+bounded read-only waits, never a second upload. A broken public release needs a
+reviewed new version and its own approval.
+
+The first preview.0 used a bootstrap token, and the registry assigned both
+`preview` and `latest` to it despite `--tag preview`. That bootstrap path is
+closed in this workflow. The repository `NPM_TOKEN` secret and any remaining
+bootstrap credential should be removed through a separate owner-approved account
+operation; this PR neither reads nor changes those credentials.
 
 ## Sources
 
 - [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
 - [npm staged publishing](https://docs.npmjs.com/staged-publishing)
-- [npm stage CLI and token/2FA behavior](https://docs.npmjs.com/cli/v11/commands/npm-stage)
+- [npm stage CLI](https://docs.npmjs.com/cli/v11/commands/npm-stage)
 
-Requirements checked 2026-09-27: OIDC needs npm ≥11.5.1, staging ≥11.15.0, both
-with Node ≥22.14.0. Application support remains Node 22.13+ within 22.x and 24.x;
-release-tool requirements are separate.
+OIDC needs npm >=11.5.1 and staging needs npm >=11.15.0 with Node >=22.14.0.
+Application support remains Node 22.13+ within 22.x and 24.x; release-tool
+requirements are separate.

package/VALIDATION.md

@@ -1,8 +1,47 @@
 # Validation record — 2026-09-27 KST
 
-This is preview evidence, not an npm release or a claim of complete Python parity.
+This record distinguishes historical live-agent evidence, the verified public
+preview and the unpublished 0.1.0 stable candidate. It does not claim complete
+Python parity.
 Python reference: v1.0.2, commit `47c23713d0a2a3c11ebde6186afd8c43489b8b65`.
 
+## Public 0.1.0-preview.1 — 2026-09-27 KST
+
+The preview.1 candidate and exact merged main passed macOS/Linux Node 22/24,
+native Windows Node 22/24 and the release gate. A separate gate change preserved
+the existing `latest: 0.1.0-preview.0` while permitting preview.1 staging.
+[Run 36313884100](https://github.com/abruption/session-peer-ts/actions/runs/36313884100)
+staged the exact main commit `f65d3ee99cc26ff4a267aef84e31a308d034ac80`
+through the stage-only OIDC Trusted Publisher. After separate environment and
+npm 2FA approvals, the public registry showed `preview: 0.1.0-preview.1` and
+unchanged `latest: 0.1.0-preview.0`.
+
+The npm stage tarball matched the retained run artifact byte for byte. Its
+SHA-256 was `d154beac93893b60b0695e5a6296e185beb8dbd05188ffe04befb74d29966110`.
+The public SHA-512 integrity and provenance metadata matched the manifest;
+`npm audit signatures`, fresh version-specific install, CLI version and empty
+Claude discovery checks, and uninstall passed. This verifies package delivery,
+not a new live Claude/Codex message ACK from the published build.
+
+## 0.1.0 stable candidate
+
+This preparation updates the version handshake, package metadata, four README
+languages, release gates and tests. Native delivery logic is unchanged. The
+candidate must pass its PR and exact merged-main CI before a separate decision
+to stage `0.1.0`; staging, npm 2FA approval, public verification and any GitHub
+tag or fleet installation remain separate gates.
+
+## Historical 0.1.0-preview.1 candidate checks
+
+After #7–#10 were merged, the versioned candidate passed the local macOS
+arm64 Node 22 contract suite (23 passed, two Windows-only tests skipped),
+TypeScript test type-check, package/declaration smoke test, four-README
+repository checks and `npm audit` (zero vulnerabilities). The package smoke
+test repeated packing with the same SHA-256 and verified isolated install and
+uninstall. The new candidate was not sent to a live agent and was not published
+by these checks. Windows Node 22/24 and macOS/Linux Node 22/24 must also pass
+on the candidate PR and exact merged `main` commit before publication.
+
 ## Automated checks
 
 - 14 tests pass locally on macOS arm64 / Node 22.14.0.
@@ -17,6 +56,30 @@ Python reference: v1.0.2, commit `47c23713d0a2a3c11ebde6186afd8c43489b8b65`.
 
 ## Real TUI and SSH checks
 
+### Native Windows candidate — 2026-09-27 KST
+
+An isolated prefix under the Windows user's Temp directory was installed from
+this branch's local tarball. The existing Python CLI was not removed or
+overwritten. Node 24.16.0 and npm 11.13.0 were present. Windows native
+`list` found the live Claude inbox; Codex dry-run verified the saved thread,
+kernel lock, single same-user `codex.exe` opener and stable start time. Mac
+mini → Windows SSH preflight used an explicit Windows platform, remote `.cmd`
+path and an already authenticated OpenSSH control socket; no host-key bypass
+or new login was introduced.
+
+One message per target was submitted from this candidate through Windows SSH.
+The CLI returned Claude `posted` and Codex `queued`, with
+`consumptionConfirmed:false`. The user separately confirmed exact response
+lines in both Windows native TUIs:
+
+- Claude: `ACK TS-WIN4-CLAUDE-20260927-A`
+- Codex: `ACK TS-WIN4-CODEX-20260927-B`
+
+These ACKs are user-observed responses, not direct terminal-pane capture by
+the test runner. No retry was made. This is one-shot evidence, not a soak or
+all-architecture qualification. Windows x64 was tested; Windows arm64 and
+Node 22 remain untested in this live check. Python remains installed.
+
 Dedicated, newly created Claude/Codex test TUIs only. The user approved trusting
 the two otherwise empty test folders. Agent permissions were not changed.
 Each route passed discovery and no-delivery dry-run before exactly one send.
@@ -69,9 +132,9 @@ package/release fixtures, not claimed as new live ACK evidence.
 
 ## Not covered / not released
 
-Windows, native x64 agent interaction, IPv6 literals, Relay/MCP/wake, full Python
-CLI parity, automatic reverse-route detection, npm registry publishing and
-provenance are outside this historical evidence. Publication preparation now
-removes the private flag, but actual publishing still needs separate approval
-and the gates in RELEASING.md. Native dependency prebuild availability must be tested
-on each architecture claimed by a future release.
+Windows arm64, IPv6 literals, Relay/MCP/wake, full Python CLI parity and
+automatic reverse-route detection remain outside this evidence. Registry
+publishing and provenance are verified for preview.1 above, but not by the
+historical live-agent ACKs. Stable 0.1.0 publishing still needs the separate
+approvals and gates in RELEASING.md. Native dependency prebuild availability
+must be tested on each architecture claimed by a future release.

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { type Done } from './process.js';
+type Options = {
+    command: 'list' | 'send';
+    values: Map<string, string>;
+    flags: Set<string>;
+};
+export declare function parse(args: string[]): Options;
+export declare function sshPreflightFailure(result: Done, expected: string): string | undefined;
+export {};

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { hostname } from 'node:os';
+import { lstatSync } from 'node:fs';
 import { claude, codex, Refusal } from './discovery.js';
 import { executable, run, UnknownOutcome } from './process.js';
 import { checkMessage, send } from './send.js';
@@ -18,7 +19,7 @@ export function parse(args) {
                 throw new Refusal('invalid_option');
             flags.add(key);
         }
-        else if (['--agent', '--codex-home', '--codex-bin', '--output-format', '--to', '--message', '-m', '--host', '--remote-bin', '--reply-address'].includes(key)) {
+        else if (['--agent', '--codex-home', '--codex-bin', '--output-format', '--to', '--message', '-m', '--host', '--remote-bin', '--remote-platform', '--ssh-control-path', '--reply-address'].includes(key)) {
             const name = key === '-m' ? '--message' : key;
             const value = split > 0 ? token.slice(split + 1) : args[++i];
             if (value === undefined || values.has(name))
@@ -60,8 +61,23 @@ export function parse(args) {
     }
     if (values.has('--host'))
         host(values.get('--host'));
+    if (values.has('--ssh-control-path')) {
+        if (!values.has('--host'))
+            throw new Refusal('inapplicable_option');
+        try {
+            if (!lstatSync(values.get('--ssh-control-path')).isSocket())
+                throw new Error('not_socket');
+        }
+        catch {
+            throw new Refusal('invalid_ssh_control_path');
+        }
+    }
+    if (values.has('--remote-platform') && (!values.has('--host') || !['posix', 'win32'].includes(values.get('--remote-platform'))))
+        throw new Refusal('invalid_remote_platform');
     if (values.has('--remote-bin')) {
-        if (!values.has('--host') || !/^\/[\x20-\x7e]+$/.test(values.get('--remote-bin')))
+        const binary = values.get('--remote-bin');
+        if (!values.has('--host') || (values.get('--remote-platform') === 'win32' ?
+            !/^[A-Za-z]:\\[^\r\n]+$/.test(binary) : !/^\/[\x20-\x7e]+$/.test(binary)))
             throw new Refusal('invalid_remote_bin');
     }
     return { command, values, flags };
@@ -84,15 +100,46 @@ async function input() {
     }
 }
 const quote = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+// Classify only the no-message version preflight. Never expose SSH stderr,
+// which can contain user paths or agent output.
+export function sshPreflightFailure(result, expected) {
+    if (result.interrupted)
+        return 'ssh_preflight_timeout';
+    if (!result.spawned)
+        return 'ssh_unavailable';
+    const detail = result.stderr;
+    if (/host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED|no [^\n]*host key is known/i.test(detail))
+        return 'ssh_host_key_untrusted';
+    if (/permission denied \(|authentication failed|too many authentication failures|tailnet policy does not permit/i.test(detail))
+        return 'ssh_authentication_refused';
+    if (/could not resolve hostname|name or service not known|network is unreachable|no route to host|connection timed out|connection refused|operation timed out/i.test(detail))
+        return 'ssh_unreachable';
+    if (result.code === 127 && /not found|no such file|not recognized/i.test(detail))
+        return 'remote_cli_missing';
+    if (result.code === 0 && result.stdout.trim() !== expected)
+        return 'remote_version_mismatch';
+    if (result.code !== 0)
+        return 'ssh_preflight_failed';
+    return undefined;
+}
 async function remote(options, message) {
     const { values, flags, command } = options;
     const target = host(values.get('--host'));
     const binary = values.get('--remote-bin') ?? 'session-peer';
+    const windows = values.get('--remote-platform') === 'win32';
+    const invoke = (flag) => {
+        if (!windows)
+            return `${quote(binary)} ${flag}`;
+        const code = `& '${binary.replace(/'/g, "''")}' ${flag}`;
+        return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${Buffer.from(code, 'utf16le').toString('base64')}`;
+    };
     const ssh = executable('ssh');
-    const base = ['-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=10', '--', target];
-    const preflight = await run(ssh, [...base, `${quote(binary)} --version`], { timeout: 15000 });
-    if (preflight.interrupted || preflight.code !== 0 || preflight.stdout.trim() !== VERSION_LINE)
-        throw new Refusal('remote_version_unverified', 1);
+    const base = ['-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=10',
+        ...(values.has('--ssh-control-path') ? ['-S', values.get('--ssh-control-path')] : []), '--', target];
+    const preflight = await run(ssh, [...base, invoke('--version')], { timeout: 15000 });
+    const preflightError = sshPreflightFailure(preflight, VERSION_LINE);
+    if (preflightError)
+        throw new Refusal(preflightError, 1);
     const args = [command, '--json'];
     for (const [key, value] of values)
         if (['--agent', '--codex-home', '--codex-bin', '--to'].includes(key))
@@ -103,7 +150,7 @@ async function remote(options, message) {
         args.push('--dry-run');
     if (command === 'send')
         args.push('--message', message, '--no-from', '--no-reply-to');
-    const done = await run(ssh, [...base, `${quote(binary)} --stdio-request`], {
+    const done = await run(ssh, [...base, invoke('--stdio-request')], {
         timeout: 90000, input: JSON.stringify({ schemaVersion: 1, args })
     });
     const uncertain = () => { if (command === 'send' && !flags.has('--dry-run') && done.spawned)
@@ -132,13 +179,13 @@ try {
     const [major, minor] = process.versions.node.split('.').map(Number);
     if (!((major === 22 && minor >= 13) || major === 24))
         throw new Refusal('unsupported_node_version');
-    if (!['darwin', 'linux'].includes(process.platform))
+    if (!['darwin', 'linux', 'win32'].includes(process.platform))
         throw new Refusal('unsupported_platform');
     let args = process.argv.slice(2);
     if (args.length === 1 && args[0] === '--version')
         console.log(VERSION_LINE);
     else if (args.length === 1 && ['--help', '-h'].includes(args[0]))
-        console.log('session-peer (TypeScript preview): list --agent claude|codex --json; send --to TARGET --message TEXT --json [--dry-run] [--host HOST] [--remote-bin ABSOLUTE_PATH]. Codex requires --codex-home. Relay/MCP/wake/Windows unsupported.');
+        console.log('session-peer (TypeScript preview): list --agent claude|codex --json; send --to TARGET --message TEXT --json [--dry-run] [--host HOST] [--remote-bin ABSOLUTE_PATH]. Codex requires --codex-home. Relay/MCP/wake unsupported.');
     else {
         const wire = args.length === 1 && args[0] === '--stdio-request';
         if (wire) {
@@ -156,7 +203,7 @@ try {
         }
         command = ['list', 'send'].includes(args[0] ?? '') ? args[0] : 'unknown';
         const options = parse(args);
-        if (wire && (options.values.has('--host') || options.values.has('--remote-bin')))
+        if (wire && (options.values.has('--host') || options.values.has('--remote-bin') || options.values.has('--remote-platform') || options.values.has('--ssh-control-path')))
             throw new Refusal('nested_transport_forbidden');
         let message;
         if (command === 'send') {

package/dist/discovery.d.ts

@@ -0,0 +1,10 @@
+type Row = Record<string, unknown>;
+export declare class Refusal extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, exitCode?: number);
+}
+export declare function canonical(path: string): string;
+export declare function claude(all: boolean): Row;
+export declare function codex(path: string, all: boolean): Promise<Row>;
+export {};

package/dist/discovery.js

@@ -2,6 +2,7 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { windowsProcessStart } from './windows.js';
 export class Refusal extends Error {
     code;
     exitCode;
@@ -33,6 +34,8 @@ export function canonical(path) {
 function alive(pid) {
     if (pid <= 1)
         return false;
+    if (process.platform === 'win32')
+        return windowsProcessStart(pid) !== undefined;
     try {
         process.kill(pid, 0);
         return true;
@@ -71,20 +74,31 @@ export function claude(all) {
         if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid > 2147483647)
             continue;
         const matches = pid === Number(entry.slice(0, -5));
-        const live = matches && alive(pid);
+        let live = matches && alive(pid);
+        if (live && process.platform === 'win32') {
+            const started = typeof record.startedAt === 'number' && Number.isSafeInteger(record.startedAt) && record.startedAt > 0 ? record.startedAt : NaN;
+            const ticks = windowsProcessStart(pid);
+            const actual = ticks === undefined ? NaN : Number((ticks - 116444736000000000n) / 10000n);
+            live = Number.isFinite(started) && Number.isFinite(actual) && actual <= started + 2000;
+        }
         const socket = typeof record.messagingSocketPath === 'string' ? record.messagingSocketPath : '';
         let inbox = false;
         if (socket) {
-            try {
-                inbox = statSync(socket).isSocket();
-            }
-            catch { /* Inaccessible is not reachable. */ }
+            if (process.platform === 'win32')
+                inbox = /^\\\\\.\\pipe\\[^\r\n]+$/i.test(socket);
+            else
+                try {
+                    inbox = statSync(socket).isSocket();
+                }
+                catch { /* Inaccessible is not reachable. */ }
         }
         const row = { agent: 'claude', pid, socket, alive: live, reachable: live && inbox };
         for (const key of ['name', 'status', 'cwd', 'kind', 'version', 'tmux'])
             row[key] = record[key] ?? null;
         if (!matches)
             row.staleReason = 'record_pid_mismatch';
+        else if (!live && process.platform === 'win32')
+            row.staleReason = 'process_unverified';
         if (all || row.reachable)
             sessions.push(row);
     }

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { VERSION, VERSION_LINE, reply, envelope } from './protocol.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+// Pure protocol helpers; importing this entry point never executes the CLI.
+export { VERSION, VERSION_LINE, reply, envelope } from './protocol.js';

package/dist/process.d.ts

@@ -0,0 +1,16 @@
+export declare class UnknownOutcome extends Error {
+}
+export declare function executable(name: string): string;
+export type Done = {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    spawned: boolean;
+    interrupted: boolean;
+};
+export declare function run(binary: string, args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+    input?: string;
+    timeout?: number;
+    limit?: number;
+}): Promise<Done>;

package/dist/process.js

@@ -5,8 +5,10 @@ import { Refusal } from './discovery.js';
 export class UnknownOutcome extends Error {
 }
 export function executable(name) {
-    const paths = isAbsolute(name) ? [name] : name.includes('/') ? [] :
-        (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(p => join(p, name));
+    const windows = process.platform === 'win32';
+    const names = windows && !/\.(?:exe|cmd|bat)$/i.test(name) ? [name + '.exe', name + '.cmd', name] : [name];
+    const paths = isAbsolute(name) ? [name] : name.includes('/') || name.includes('\\') ? [] :
+        (process.env.PATH ?? '').split(delimiter).filter(Boolean).flatMap(p => names.map(n => join(p, n)));
     for (const path of paths) {
         try {
             accessSync(path, constants.X_OK);
@@ -19,7 +21,7 @@ export function executable(name) {
 }
 export function run(binary, args, options = {}) {
     return new Promise(resolve => {
-        let stdout = '', bytes = 0, spawned = false, interrupted = false;
+        let stdout = '', stderr = '', bytes = 0, spawned = false, interrupted = false;
         const child = spawn(binary, args, { shell: false, env: options.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'] });
         const stop = () => { interrupted = true; child.kill('SIGKILL'); };
         const timer = setTimeout(stop, options.timeout ?? 3000);
@@ -34,10 +36,16 @@ export function run(binary, args, options = {}) {
                 stdout += part;
         });
         // Drain but never report native stderr (it may contain message text/credentials).
-        child.stderr.on('data', (part) => { bytes += part.length; if (bytes > (options.limit ?? 1024 * 1024))
-            stop(); });
+        // Retain stderr only for allowlisted error classification. Never include it in CLI output.
+        child.stderr.on('data', (part) => {
+            bytes += part.length;
+            if (stderr.length < 4096)
+                stderr += part.toString('utf8').slice(0, 4096 - stderr.length);
+            if (bytes > (options.limit ?? 1024 * 1024))
+                stop();
+        });
         child.once('error', () => { interrupted = true; });
-        child.once('close', code => { clearTimeout(timer); resolve({ code, stdout, spawned, interrupted }); });
+        child.once('close', code => { clearTimeout(timer); resolve({ code, stdout, stderr, spawned, interrupted }); });
         child.stdin.end(options.input);
     });
 }