design(ssh): define Python-free remote deployment and version compatibility #23

Superseding roadmap decision — 2026-10-20 KST

The user approved deferring Draft #155 and excluding its deployment harness from 0.5.0. Stop incremental patching and define the minimum qualification contract before replacement implementation: #158. Priority remains P2; this work has no committed release version. #23 remains OPEN and its remaining destination/ownership criteria are not completed by previous partial tests.

Prefer a reviewed operator checklist; evaluate a read-only static reporter only if justified. Do not implicitly require a journal/receipt/lock/caller/recovery engine. Preserve the existing ADR and all dated historical evidence. This decision supersedes earlier 0.5.0 inclusion statements below and grants no new live-host, merge or publication approval.

Current roadmap — 2026-10-13 KST

• Target milestone: 0.5.0 — Cross-platform observation and remote qualification.
• Planning priority: P2 (priority:P2).
• Dependencies/order: Merged ADR; requalify current receipt/recovery rules and operator-check → receipt → unlock ordering.
• Remaining scope: Remote workflow evidence/ownership and remaining platform/runtime cells. No implicit new deploy helper or relaxed version preflight.

This section supersedes older milestone/version/priority statements below. Existing acceptance criteria, evidence limits and historical records remain applicable. Versioned milestones are provisional planning targets, not committed dates or implementation/live-test/merge/release authorization. P1 means a milestone prerequisite/current-release item; P2 a planned extension/research track; P3 later dependent work.

Python streams its standalone program over SSH and only requires remote Python. TS requires an explicitly installed same-version TS CLI, supported Node and a native locking dependency. This intentional boundary creates a real deployment gap; relaxing exact-version preflight without a replacement contract would be unsafe.

Scope and completion criteria

• Write an architecture decision comparing explicit npm installation, isolated artifact provisioning and a portable remote bundle, including native dependency/OS/architecture constraints and offline use.
• Define the remote protocol/capability compatibility contract separately from package SemVer; retain exact-version refusal until an alternative is implemented and verified.
• Document actionable missing-runtime/version/Node/prebuild errors and an operator-invoked deployment workflow with integrity validation, ownership and cleanup/rollback rules.
• No implicit remote installation during list/send, no Python runtime fallback, no host-key relaxation and no overwriting another manager's session-peer executable.
• Validate the selected workflow with isolated POSIX and Windows destinations; split implementation work into follow-up issues if the design selects a new distribution artifact.

Dependencies and priority

Dependencies: None; implement within the existing guarded local/SSH contract.

Planning priority: P2 (P1 = foundational/common workflow; P2 = subsequent or optional capability). Milestone is a planning group, not a release or deployment approval.

Evidence

Compared Python 1.0.2 (47c2371) with TS 0.1.0 (0edc4f8), both main heads verified on 2026-09-27.

• session-peer/session_peer_core/ssh.py
• session-peer/docs/cli-reference.md
• session-peer-ts/src/cli.ts
• session-peer-ts/package.json

Current checkpoint — 2026-10-07

ADR design was merged in PR #83. Preparation PR #111 records published 0.3.1 validation on an authorized Windows x64 destination: administrator/PowerShell5.1/Node24.16, dedicated prefix, offline exact-lock installation, native locking, wrapper and operator SSH doctor/nonexistent-target dry-run; 31 storage/recovery fixtures passed, zero failed. Prefix removal and unchanged pre-existing Python launcher were independently rechecked. Node22.23.3 banner/native-lock smoke is separate from full installation qualification.

Remaining: the earlier Linux run did not execute all current receipt/recovery rules or the exact operator ordering; non-admin/other architecture and Node22 full matrix are unvalidated. F1–F6 follow-up implementation gates, including identity enforcement/capability negotiation/deploy helper, remain proposals rather than shipped commands. Windows server evidence does not qualify Windows-client jump (#20). Keep this issue open; no complete-platform or shipped-helper claim.

Mutual-comparison acceptance refinement — 2026-10-07

• Preserve explicit preprovisioning of exact same TS version, supported absolute Node/runtime/native dependency. Align source-build commits as an operator review rule; do not claim the current wire preflight verifies a commit hash.
• Document manager/operator ownership of remote rollout, repair, rollback and retention; preserve Python/npm/uv/pipx ownership and existing executables. No implicit provisioning during list/send/doctor, Python source-streaming clone/fallback, self updater or update--host is required here.
• Requalify Linux under current receipt/recovery rules and exact operator-check→receipt→unlock ordering: unreceipted fresh-lock recovery, corrupt/mismatched/orphan receipts, .receipts trust, unverifiable-owner override and journal-confirmed rollback.
• Keep bounded Windows evidence distinct: published0.3.1 Win10x64/admin/PS5.1/Node24.16 offline isolated deployment, native wrapper/operator doctor+nonexistent-target dry-run and31 native/local fixtures; Node22.23.3 direct banner/lock smoke is not a full matrix. Other accounts/architectures/runtime/concurrency cells remain unvalidated.
• Keep F2–F6 capability/error/identity/provisioning helpers as proposed follow-ups unless separately implemented/validated; do not close the full criterion from Windows-server success or infer Windows-client jump support.

These are refinements to existing #23, not a new distribution implementation or release approval. #117 tracks migration-summary corrections; #115/#116 ordinary SSH response reliability remains separate. PriorityP2 and existing0.3.0 milestone remain unchanged. Existing dated evidence is preserved; this update ran no new experiment.