session-peer 0.1.0-preview.0

package/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+This repository follows the PR-based workflow of
+[session-peer](https://github.com/abruption/session-peer), adapted for Node.
+
+## Branches and commits
+
+- `main` is the integration branch. All changes go through a short-lived branch
+  and PR: `feat/<issue>-topic`, `fix/<issue>-topic`, `docs/topic`,
+  `chore/topic`, or `release/<version>` for release preparation.
+- No permanent develop branch. Create `release/X.Y.x` maintenance branches only
+  when a supported backport line is explicitly approved; do not copy Python's
+  `release/0.9.x` or merge it into this repository.
+- New local worktrees belong under `.worktree/`. Preserve unrelated dirty work.
+- English Conventional Commit titles: `feat:`, `fix:`, `docs:`, `chore:`,
+  `refactor:`, `test:`, `perf:`, `ci:`, `build:` or `revert:` (optional scope).
+- Prefer squash merge with a Conventional Commit PR title. Rebase merge is
+  allowed only for a clean conventional history. Protected main requires linear
+  history, so do not create merge commits on main. Never force-push or delete main.
+- Update the PR branch against main, rerun checks and resolve discussions before
+  merging. Main requires the latest aggregate `release gate`. A green old SHA is
+  not sufficient. Reviews are encouraged; the reference repo requires a PR but
+  zero mandatory approving reviews, which is retained here for solo maintenance.
+- Remote branches are cleaned manually after verifying merge and preserving any
+  unmerged work; automatic branch deletion remains off, matching the reference.
+
+## Local verification
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node scripts/check-repository.mjs
+SESSION_PEER_PYTHON_ROOT=/path/to/python-v1.0.2 npm test
+npm run test:package
+npm audit
+```
+
+Python reference commit: `47c23713d0a2a3c11ebde6186afd8c43489b8b65`.
+CI checks it out separately. Python is a development oracle, never a runtime
+fallback. Match Node 22/24, macOS/Linux and the native dependency requirements.
+Keep `package-lock.json` tracked. Do not commit dist, node_modules, local
+worktrees, credentials, agent state, transcripts or real test evidence.
+
+## Safety and documentation
+
+Preserve actual flock/owner evidence, ambiguity rejection, pre-submit revalidation,
+SSH input/host boundaries and no retry after unknown outcomes. Never infer ACK
+from queueing. Fixtures are not real-agent evidence. Live tests require explicit
+authorization, dedicated targets and independent observation; CI never uses live
+accounts, sessions or credentials. Security reports use SECURITY.md.
+
+Synchronize README.md, README.ko.md, README.ja.md and README.zh-CN.md. Keep runtime
+version/support status and install examples consistent. Product/source changes
+do not authorize npm publication, production deployment or service restarts.
+CI exercises release packaging without publishing. The manual publishing
+workflow has separate confirmation and environment-approval gates; see
+RELEASING.md before dispatching it. Never add publish credentials to PR tests.
+Dependabot automatic update PRs are not enabled; dependency changes are manual
+reviewed PRs with lockfile, audit, native-load and platform tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abruption
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,109 @@
+# session-peer (TypeScript)
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
+<!-- docs-contract: preview-candidate; package=session-peer; bin=session-peer; node=22.13+/24; python-reference=1.0.2 -->
+
+実行中の **Claude Code と Codex セッション**に、ローカルまたは SSH 経由でメッセージを送る TypeScript クライアントです。Node.js で動作し、Python は不要です。
+
+**プレビューのリリース候補であり、公開には別途承認が必要です。**パッケージ名は `session-peer`、CLI コマンドは **`session-peer`**。Relay サーバーやホスティングサービスは提供しません。
+
+## 機能と範囲
+
+- ローカルセッションと、明示的に指定した Codex home の検出。
+- `--dry-run` で宛先を確認し、ネイティブ inbox / queue にメッセージを一度だけ提出。Codex は一意かつ安定した live writer が必要です。
+- インストール済みの同じクライアントへの SSH 接続、構造化 Reply-To URI、JSON 出力。
+- 宛先や所有者が曖昧なら拒否。不確実な提出を自動再送しません。
+
+Windows、Relay 通信、MCP、wake/resume、非アクティブ queue、Antigravity、自動更新、暗黙の全エージェント検出、人間向けテキスト出力は未実装です。未対応コマンドは明示的に失敗します。汎用オーケストレーターではありません。
+
+## 必要条件
+
+macOS / Linux、Node **22.x の 22.13 以上、または 24.x**。Node 26 は対象外です。ネイティブ flock 依存には対応する x64/arm64 バイナリが必要で、純 JavaScript パッケージではありません。Codex 送信には `codex`・`lsof`・`ps`、Claude にはアクセス可能な inbox を持つ稼働中 TUI が必要です。SSH は既存の鍵・ホスト信頼と、接続先の**同一バージョン**のクライアントを使います。
+
+## インストール
+
+公式 npm リリースで所有権と来歴を確認するまでは、レジストリの `npm install -g session-peer` や `npx session-peer` を実行しないでください。現在はレビューしたソースをビルドし、必要ならローカル tarball をインストールします。
+
+```sh
+git clone https://github.com/abruption/session-peer-ts.git
+cd session-peer-ts
+npm ci --ignore-scripts
+npm run build
+node dist/cli.js --version
+npm pack --ignore-scripts
+# 任意のグローバルインストール前に PATH の既存コマンドを確認
+npm install --global --ignore-scripts ./session-peer-0.1.0-preview.0.tgz
+session-peer --version
+```
+
+期待値は `session-peer 0.1.0-preview.0 (typescript)`。`./...tgz` を省略しないでください。これは未確認のレジストリではなくローカル成果物を選択します。別途承認された npm 公開後も、パッケージ名とコマンド名は上記のままです。そのリリースのバージョン / dist-tag を確認してください。
+
+### 既存インストールとの共存
+
+インストール前後に `type -a session-peer` と `command -v session-peer` を確認します。他の実装も同名コマンドを提供するため、PATH 上の一つを選ぶか `node /absolute/path/dist/cli.js` を使ってください。`--force` で他の管理ツールのファイルを上書きしないでください。Python パッケージ・スキル・サービスを自動変更しません。削除は `npm uninstall --global session-peer` を使い、PATH を再確認します。
+
+## 使い方
+
+```sh
+session-peer list --agent claude --json
+session-peer list --agent codex --codex-home "$HOME/.codex" --json
+session-peer send --to CLAUDE_PID --message 'Please review the API contract.' --dry-run --json
+session-peer send --to codex:THREAD_UUID --codex-home "$HOME/.codex" --message 'Please review the API contract.' --dry-run --json
+```
+
+実際に送るときだけ `--dry-run` を外します。`--message` の省略または `--message -` は UTF-8 stdin を読みます。`--all` は古い / アーカイブ済み記録の一覧用で、送信許可にはなりません。Claude の宛先は PID、`claude:PID`、一意な ASCII 名（大文字小文字を区別しない）。Unicode 名には PID を使います。Codex は完全な UUID と明示した home が必要です。実行ファイルは `--codex-bin` で指定できます。出力には `--json` または `--output-format json` が必要です。
+
+### SSH
+
+```sh
+session-peer send --host user@machine --remote-bin /absolute/path/session-peer \
+  --to CLAUDE_PID --message 'Please review the API contract.' --dry-run --json
+```
+
+既定のリモートコマンドは PATH の `session-peer`。絶対パスの `--remote-bin` で対応 Node を使うラッパーも指定できます。TypeScript マーカーと正確なバージョンを確認し、異なる実装は拒否します。BatchMode / StrictHostKeyChecking を使い、新しいホスト鍵の自動受理、リモートランタイムのインストール、Python フォールバックはしません。本文はリモートシェル引数ではなく JSON stdin で渡します。任意の `--ssh-opt`、IPv6 リテラル、Tailscale の正規名補完は非対応です。SSH alias / hostname を使ってください。片方向の接続成功は逆方向の接続を保証しません。
+
+### 返信
+
+`session-peer://v1/reply?...` URI を `--to` に指定できます。不明 / 重複フィールド、不正ホスト・エンコード、明示した経路との矛盾は拒否します。`--reply-address URI` は明示的な返信先を付けますが、経路を自動推測・検証しません。新しい返信先なしで返すときは `--no-reply-to`。有効な CODEX_THREAD_ID / CODEX_SESSION_ID は参考用 From 情報になり、`--no-from` で省略できます。不明な送信者は捏造しません。peer 情報は権限ではなく、URI をシェルとして実行しません。
+
+## 成功の意味と安全性
+
+| 結果 | 意味 |
+| --- | --- |
+| `validated`, `submitted:false` | dry-run 成功。未送信。 |
+| `posted` / `queued` | inbox 書き込み / queue 受理。**消費や ACK ではありません**。 |
+| `refused`, `submitted:false` | 提出前の拒否。 |
+| `unknown`, `submitted:null` | 提出済みの可能性あり。自動再送禁止。 |
+
+`consumptionConfirmed` は常に false。実際の ACK は宛先 TUI で別途確認し、queue や transcript polling から推定しません。終了コード 0/1/2 は成功/エラー/用法エラー。エラーは固定コードで、ネイティブ stderr や本文を返しません。Codex は実際の kernel flock、ファイル同一性、同一ユーザーの所有者開始時刻を複数回調べ、提出直前にも再検証します。lock の削除や所有エージェントへのシグナル送信はしません。一覧の名前・パス・ID は共有前に伏せてください。
+
+## 開発と検証
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node scripts/check-repository.mjs
+SESSION_PEER_PYTHON_ROOT=/path/to/python-reference npm test
+npm run test:package
+npm audit
+```
+
+Python は開発時の互換検証基準のみです（v1.0.2、`47c23713d0a2a3c11ebde6186afd8c43489b8b65`）。実行時依存ではありません。テストには C コンパイラーと lsof も必要です。CI は基準コミットを固定し macOS/Linux × Node 22/24 を確認します。SQLite・Unix inbox・実 lock の fixture と、専用実 TUI の証拠 [VALIDATION.md](VALIDATION.md) は別です。fixture 成功は ACK ではありません。パッケージ内容、反復 pack ハッシュ、新規インストール、アンインストールも検証します。ネイティブ依存の通常の install script は実行せず、検証した prebuilt 経路は `--ignore-scripts` を使います。SQLite 読み取り専用接続も WAL 共有メモリー管理に関与し得るため、スナップショットではありません。
+
+[CONTRIBUTING.md](CONTRIBUTING.md)、[RELEASING.md](RELEASING.md)、[SECURITY.md](SECURITY.md) を参照してください。公開には別途承認が必要で、自動 npm 公開はありません。[MIT](LICENSE) ライセンスです。
+
+## npm 公開後のインストール
+
+公式リリースとレジストリの整合性・provenance 検証が完了した後にのみ、次の正確なプレビューバージョンをインストールしてください。安定版 `latest` ではありません。公開前は上記のローカル tarball を使います。
+
+```sh
+npm install --global --ignore-scripts session-peer@0.1.0-preview.0
+session-peer --version
+```
+
+手動ワークフローは初回のみ短期 bootstrap トークンを使用します。以後は Trusted Publisher OIDC で staging し、保守者が 2FA で承認します。staging 成功は公開完了ではありません。[RELEASING.md](RELEASING.md) を参照してください。
+
+## 関連プロジェクト
+
+[Python session-peer](https://github.com/abruption/session-peer) は独立して保守・リリースされ、任意機能や `pipx install session-peer` などの導入方法はそちらで案内します。同じ `session-peer` コマンドなので上記 PATH の注意が必要です。このクライアントはそのインストールに依存せず、全機能・フラグの同等性を約束しません。

package/README.ko.md

@@ -0,0 +1,168 @@
+# session-peer (TypeScript)
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
+<!-- docs-contract: preview-candidate; package=session-peer; bin=session-peer; node=22.13+/24; python-reference=1.0.2 -->
+
+실행 중인 **Claude Code·Codex 세션에 로컬 또는 SSH로 메시지를 전달**하는
+TypeScript 클라이언트입니다. Python 없이 Node.js로 실행합니다.
+
+**프리뷰 릴리스 후보이며 발행에는 별도 승인이 필요합니다.** 패키지명은
+`session-peer`, CLI 명령어는 **`session-peer`**입니다. Relay 서버나 호스팅
+서비스를 제공하는 프로젝트가 아닙니다.
+
+## 주요 기능과 범위
+
+- 로컬 세션과 명시적으로 선택한 Codex 홈 탐색
+- `--dry-run`으로 대상을 검증한 뒤 네이티브 inbox 또는 queue에 메시지 1회 제출
+- 원격에 명시적으로 설치한 같은 버전의 클라이언트로 SSH 전송
+- 구조화된 Reply-To URI와 JSON 결과
+- 모호한 대상·확인할 수 없는 소유권은 거부하고, 불확실한 제출은 자동 재시도하지 않음
+
+Windows, Relay 전송, MCP, wake/resume, 비활성 세션 queue, Antigravity, 자동 업데이트,
+암묵적인 전체 에이전트 탐색, 일반 텍스트 출력은 미지원입니다. 미지원 옵션은 명시적으로
+거부하며 범용 오케스트레이터를 지향하지 않습니다.
+
+## 요구사항
+
+macOS/Linux와 Node **22.x의 22.13 이상 또는 24.x**가 필요합니다. Node 26은
+미지원입니다. 네이티브 flock 의존성에 맞는 사전 빌드 바이너리(x64/arm64)가 필요하므로
+순수 JavaScript 패키지는 아닙니다. Codex 전송에는 `codex`, `lsof`, `ps`와 저장된
+스레드의 유일하고 안정적인 live writer가 필요합니다. Claude는 접근 가능한 inbox가
+있는 실행 중 TUI가 필요합니다. SSH에는 OpenSSH, 기존 키·호스트 신뢰 설정과 원격의
+**동일 버전 클라이언트**가 필요합니다.
+
+## 설치
+
+공식 npm 릴리스에서 소유권·출처가 확인되기 전에는 레지스트리의
+`npm install -g session-peer`나 `npx session-peer`를 실행하지 마세요.
+현재는 검토한 소스를 빌드하고, 필요할 때 로컬 tarball을 설치합니다.
+
+```sh
+git clone https://github.com/abruption/session-peer-ts.git
+cd session-peer-ts
+npm ci --ignore-scripts
+npm run build
+node dist/cli.js --version
+npm pack --ignore-scripts
+# 선택 사항: PATH에서 사용할 구현을 명시적으로 선택한 뒤 전역 설치
+npm install --global --ignore-scripts ./session-peer-0.1.0-preview.0.tgz
+session-peer --version
+```
+
+예상 출력은 `session-peer 0.1.0-preview.0 (typescript)`입니다. 설치 명령의
+`./...tgz`는 검증되지 않은 레지스트리 패키지가 아닌 로컬 산출물을 지정하므로 생략하지
+마세요. 별도 승인된 npm 발행 이후에도 패키지명은 `session-peer`, 명령은
+`session-peer`로 유지하며 해당 릴리스의 버전·dist-tag 안내를 따릅니다.
+
+### 기존 설치본과 PATH
+
+다른 구현도 `session-peer`를 설치할 수 있습니다. 전후에 `type -a session-peer`와
+`command -v session-peer`로 확인하고 PATH에서 하나를 선택하거나
+`node /절대/경로/dist/cli.js`처럼 명시적으로 실행하세요. 다른 설치 관리자의 파일을
+`--force`로 덮어쓰지 마세요. Python 패키지·스킬·서비스는 자동 설치·삭제·설정하지
+않습니다. npm 설치본 제거는 `npm uninstall --global session-peer`로 하고 PATH를
+다시 확인하세요.
+
+## 사용법
+
+```sh
+session-peer list --agent claude --json
+session-peer list --agent codex --codex-home "$HOME/.codex" --json
+session-peer send --to CLAUDE_PID --message 'API 계약을 검토해 주세요.' --dry-run --json
+session-peer send --to codex:THREAD_UUID --codex-home "$HOME/.codex" --message 'API 계약을 검토해 주세요.' --dry-run --json
+```
+
+실제 전달할 때만 `--dry-run`을 제거합니다. `--message`를 생략하거나 `--message -`를
+사용하면 UTF-8 stdin을 읽습니다. `--all`은 오래된·보관된 기록을 목록에 포함할 뿐
+전송을 허용하지 않습니다. Claude 대상은 PID, `claude:PID`, 모호하지 않은 ASCII
+이름(대소문자 무시)입니다. Unicode 이름은 PID로 지정하세요. Codex에는 전체 UUID와
+명시적인 홈이 필요하며 `--codex-bin`으로 실행 파일을 고를 수 있습니다. 출력에는
+`--json` 또는 `--output-format json`이 필요합니다.
+
+### 다른 머신으로 SSH 전송
+
+```sh
+session-peer send --host user@machine --remote-bin /absolute/path/session-peer \
+  --to CLAUDE_PID --message 'API 계약을 검토해 주세요.' --dry-run --json
+```
+
+원격 기본 명령은 PATH의 `session-peer`입니다. `--remote-bin` 절대 경로로 지원되는
+Node를 선택하는 래퍼를 지정할 수 있습니다. TypeScript 표시와 정확한 버전을 확인하므로
+다른 구현을 발견하면 거부합니다. BatchMode·StrictHostKeyChecking을 사용하며 새
+호스트 키 승인, 원격 런타임 설치, Python 대체 실행은 하지 않습니다. 메시지는 원격
+셸 인자가 아닌 JSON stdin 요청으로 전달합니다. 임의의 `--ssh-opt`, IPv6 리터럴,
+Tailscale 정규 이름 보강은 미지원이므로 SSH 별칭·호스트명을 사용하세요. 정방향 접속이
+역방향 접속을 보장하지 않습니다.
+
+### 회신
+
+`session-peer://v1/reply?...` URI를 `--to`로 사용할 수 있습니다. 알 수 없거나 중복된
+필드, 위험한 호스트, 잘못된 인코딩, 명시적 경로와의 충돌은 거부합니다.
+`--reply-address URI`는 명시적인 회신 주소를 추가할 뿐 자동 추론·검증하지 않습니다.
+새 회신 주소를 붙이지 않을 때는 `--no-reply-to`를 사용합니다. 유효한
+CODEX_THREAD_ID/CODEX_SESSION_ID는 참고용 From 정보에 사용하고 `--no-from`으로
+생략합니다. 모르는 발신자를 만들지 않으며 peer 정보는 권한 근거가 아닙니다. URI를
+셸 명령으로 실행하지 않습니다.
+
+## 성공의 의미
+
+| 결과 | 의미 |
+| --- | --- |
+| `validated`, `submitted:false` | dry-run 검증 통과. 전송하지 않음 |
+| `posted` / `queued` | inbox 쓰기 / queue 수락. **소비·ACK 확인 아님** |
+| `refused`, `submitted:false` | 제출 전에 거부 |
+| `unknown`, `submitted:null` | 제출됐을 수 있음. 자동 재전송 금지 |
+
+`consumptionConfirmed`는 항상 false입니다. 실제 ACK는 수신 TUI에서 별도로 확인하며
+queue 결과나 transcript 폴링으로 추정하지 않습니다. 종료 코드는 성공/오류/사용법에
+0/1/2를 사용합니다. 오류는 고정 코드로 반환하며 원문 stderr·메시지를 노출하지 않습니다.
+Codex는 실제 OS flock, 파일 식별자, 동일 사용자 소유 프로세스의 시작 시각을 여러 번
+검사하고 제출 직전에 다시 검증합니다. 잠금을 삭제하거나 소유 프로세스에 신호를 보내지
+않습니다. 탐색 결과의 이름·경로·ID는 공유 전에 익명화하세요.
+
+## 개발·검증
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node scripts/check-repository.mjs
+SESSION_PEER_PYTHON_ROOT=/path/to/python-reference npm test
+npm run test:package
+npm audit
+```
+
+Python은 개발용 호환성 기준(v1.0.2 커밋
+`47c23713d0a2a3c11ebde6186afd8c43489b8b65`)일 뿐 런타임 의존성이 아닙니다. 테스트에는
+C 컴파일러와 lsof도 필요합니다. CI는 참조 커밋을 고정하고 macOS/Linux × Node 22/24를
+검사합니다. 임시 SQLite·Unix inbox·실제 잠금 fixture와 [VALIDATION.md](VALIDATION.md)의
+실제 TUI 증거는 구분합니다. fixture 통과는 ACK가 아닙니다. 패키지 내용·반복 빌드 해시·
+새 환경 설치·삭제도 검사합니다. 네이티브 의존성에는 설치 스크립트가 있지만 검증한 사전
+빌드 경로는 `--ignore-scripts`를 사용합니다. SQLite 읽기 전용 접근도 WAL 공유 메모리
+처리에 참여할 수 있으므로 스냅샷 읽기는 아닙니다.
+
+[CONTRIBUTING.md](CONTRIBUTING.md), [RELEASING.md](RELEASING.md),
+[SECURITY.md](SECURITY.md)를 참고하세요. 발행에는 별도 승인이 필요하며 npm 자동
+발행은 활성화하지 않았습니다. [MIT 라이선스](LICENSE)입니다.
+
+## npm 발행 후 설치
+
+공식 릴리스와 레지스트리 무결성·provenance 검증이 완료된 뒤에만 아래 정확한
+프리뷰 버전을 설치하세요. 안정판 `latest` 채널이 아닙니다. 공개 전에는 위의
+로컬 tarball 설치를 사용합니다.
+
+```sh
+npm install --global --ignore-scripts session-peer@0.1.0-preview.0
+session-peer --version
+```
+
+수동 발행 워크플로우는 최초 1회만 단기 bootstrap 토큰을 사용합니다. 이후에는
+Trusted Publisher OIDC로 staging하고 유지관리자가 2FA로 승인합니다.
+staging 성공은 공개 완료가 아닙니다. [RELEASING.md](RELEASING.md)를 참고하세요.
+
+## 관련 프로젝트
+
+[Python session-peer](https://github.com/abruption/session-peer)는 독립적으로 유지·
+발행합니다. 선택 기능과 설치법(예: `pipx install session-peer`)은 해당 저장소에서
+안내합니다. 명령어가 같은 `session-peer`이므로 위 PATH 안내를 따르세요. 이 클라이언트는
+Python 설치에 의존하지 않으며 전체 기능·플래그 호환성을 주장하지 않습니다.

package/README.md

@@ -0,0 +1,173 @@
+# session-peer (TypeScript)
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
+<!-- docs-contract: preview-candidate; package=session-peer; bin=session-peer; node=22.13+/24; python-reference=1.0.2 -->
+
+Send messages to running **Claude Code and Codex sessions**, locally or on
+another machine over SSH. This TypeScript client runs on Node.js without Python.
+
+**Preview release candidate; publication requires separate approval.** Package name:
+`session-peer`. CLI command: **`session-peer`**. This project does not provide
+a Relay server or hosted service.
+
+## What it does
+
+- Discover local sessions and explicitly selected Codex homes.
+- Validate a destination with `--dry-run`, then submit one message to its native
+  inbox or queue. Codex requires a unique, stable live writer.
+- Use the same commands over SSH to an explicitly installed remote client.
+- Accept structured Reply-To URIs as destinations and provide JSON results.
+- Refuse ambiguous targets and uncertain ownership; never automatically retry
+  an uncertain submission.
+
+Not implemented: Windows, Relay transport, MCP, wake/resume, inactive queueing,
+Antigravity, automatic updates, implicit multi-agent discovery, or human text
+output. Unsupported commands fail explicitly; this is not a general orchestrator.
+
+## Requirements
+
+macOS or Linux; Node **22.13+ within 22.x or 24.x**. Node 26 is not supported.
+The native flock dependency needs a matching prebuilt binary (x64/arm64); this
+is not a pure-JavaScript package. Codex sends also need `codex`, `lsof` and `ps`.
+Claude needs a live TUI with an accessible native inbox. SSH requires OpenSSH,
+existing key/host trust and the **same client version** on the destination.
+
+## Install
+
+Do **not** run registry `npm install -g session-peer` or `npx session-peer`
+until an official npm release verifies ownership and provenance. Today, build
+a reviewed source checkout and optionally install its local tarball:
+
+```sh
+git clone https://github.com/abruption/session-peer-ts.git
+cd session-peer-ts
+npm ci --ignore-scripts
+npm run build
+node dist/cli.js --version
+npm pack --ignore-scripts
+# Optional global install: first check which session-peer your PATH selects.
+npm install --global --ignore-scripts ./session-peer-0.1.0-preview.0.tgz
+session-peer --version
+```
+
+Expected: `session-peer 0.1.0-preview.0 (typescript)`. Keep the `./...tgz` path;
+it selects the locally built artifact, not an unverified registry package.
+After a separately approved npm release, the package will remain `session-peer`
+while the command remains `session-peer`; follow that release's version/dist-tag.
+
+### Existing installations
+
+Other implementations may also install `session-peer`. Check `type -a session-peer`
+and `command -v session-peer` before and after installation. Choose one on PATH,
+or call this build explicitly with `node /absolute/path/dist/cli.js`. Do not use
+`--force` to overwrite another manager's files. No Python package, skill or service
+is installed, removed or reconfigured automatically. To remove this npm install,
+run `npm uninstall --global session-peer` and recheck PATH.
+
+## Use
+
+```sh
+session-peer list --agent claude --json
+session-peer list --agent codex --codex-home "$HOME/.codex" --json
+session-peer send --to CLAUDE_PID --message 'Please review the API contract.' --dry-run --json
+session-peer send --to codex:THREAD_UUID --codex-home "$HOME/.codex" --message 'Please review the API contract.' --dry-run --json
+```
+
+Remove `--dry-run` only when delivery is intended. Omit `--message` or use
+`--message -` for UTF-8 stdin. `--all` includes stale/archived records for listing;
+it does not authorize sending. Claude accepts a PID, `claude:PID`, or an
+unambiguous ASCII name, case-insensitively. Use a PID for Unicode names. Codex
+requires a full UUID and explicit home; `--codex-bin` selects an executable.
+Output requires `--json` or `--output-format json`.
+
+### Another machine over SSH
+
+```sh
+session-peer send --host user@machine --remote-bin /absolute/path/session-peer \
+  --to CLAUDE_PID --message 'Please review the API contract.' --dry-run --json
+```
+
+The default remote command is `session-peer` on remote PATH. An absolute
+`--remote-bin` can select a wrapper using supported Node. The handshake checks
+the TypeScript marker and exact version; a different implementation is refused.
+SSH uses BatchMode and StrictHostKeyChecking. It never accepts new host keys,
+installs a remote runtime or invokes Python as a fallback. Messages travel in a
+JSON stdin request, not remote shell arguments. Arbitrary `--ssh-opt`, IPv6
+literals and Tailscale canonical-name enrichment are not supported; use an SSH
+alias/hostname. Forward access does not establish reverse access.
+
+### Replies
+
+Use a `session-peer://v1/reply?...` URI as `--to`. Unknown/duplicate fields,
+unsafe hosts, malformed encoding and conflicting explicit routes are rejected.
+`--reply-address URI` adds an explicit return address; no route is inferred or
+verified automatically. Use `--no-reply-to` when replying without a new address.
+A valid CODEX_THREAD_ID/CODEX_SESSION_ID supplies informational From metadata;
+`--no-from` omits it. Unknown senders are not invented. Peer metadata is never
+authority, and a Reply-To URI is never executed as shell text.
+
+## What success means
+
+| Result | Meaning |
+| --- | --- |
+| `validated`, `submitted:false` | Dry-run checks passed; nothing sent. |
+| `posted` / `queued` | Native inbox write / queue acceptance, **not consumption or ACK**. |
+| `refused`, `submitted:false` | Rejected before submission. |
+| `unknown`, `submitted:null` | Submission may have happened; do not automatically resend. |
+
+`consumptionConfirmed` is always false. Verify an actual ACK separately in the
+receiver's TUI, not from queueing or transcript polling. Exit codes are 0/1/2
+for success/error/usage. Errors use fixed codes instead of raw native stderr or
+message content. Codex uses real kernel flock, file identity and same-user owner
+start time across samples, then revalidates before queueing. No lock is deleted
+and no owning agent process is signaled. Discovery output still contains local
+names/paths/IDs: redact it before sharing.
+
+## Development and verification
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node scripts/check-repository.mjs
+SESSION_PEER_PYTHON_ROOT=/path/to/python-reference npm test
+npm run test:package
+npm audit
+```
+
+Python is only the development conformance oracle (v1.0.2 commit
+`47c23713d0a2a3c11ebde6186afd8c43489b8b65`), never a runtime dependency. Tests also
+need a C compiler and lsof. CI pins the reference and covers macOS/Linux × Node
+22/24. Temporary SQLite, Unix inbox and real lock fixtures are distinct from
+the dedicated real-TUI evidence in [VALIDATION.md](VALIDATION.md). A green fixture
+test is not an ACK. Package tests inspect contents, repeat-pack hashes, clean
+install and uninstall. The native dependency normally has an install script;
+the verified prebuilt path uses `--ignore-scripts`. SQLite read-only readers may
+participate in WAL shared-memory bookkeeping; they are not snapshots.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [RELEASING.md](RELEASING.md) and
+[SECURITY.md](SECURITY.md). Publication requires separate approval; no automatic
+npm publish is enabled. Licensed under [MIT](LICENSE).
+
+## npm release installation
+
+Only after the official release and registry integrity/provenance verification,
+install the exact preview below. It is not the stable `latest` channel. Before
+publication, keep using the local tarball instructions above.
+
+```sh
+npm install --global --ignore-scripts session-peer@0.1.0-preview.0
+session-peer --version
+```
+
+The manual workflow initially uses a short-lived bootstrap token. Later versions
+use Trusted Publisher OIDC staging and require a maintainer's 2FA approval;
+a staged upload is not a public release. See [RELEASING.md](RELEASING.md).
+
+## Related project
+
+[Python session-peer](https://github.com/abruption/session-peer) is maintained
+and released independently; its own optional features and installation guide
+remain there (for example `pipx install session-peer`). Its command is also
+`session-peer`, so apply the PATH guidance above. This client does not depend on
+that installation or claim complete feature/flag parity.

package/README.zh-CN.md

@@ -0,0 +1,109 @@
+# session-peer (TypeScript)
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
+<!-- docs-contract: preview-candidate; package=session-peer; bin=session-peer; node=22.13+/24; python-reference=1.0.2 -->
+
+向正在运行的 **Claude Code 和 Codex 会话**发送消息，支持本机和跨机器 SSH。这是运行于 Node.js 的 TypeScript 客户端，不需要 Python。
+
+**预览发布候选，正式上传需另行批准。**包名为 `session-peer`，CLI 命令为 **`session-peer`**。本项目不提供 Relay 服务器或托管服务。
+
+## 功能与边界
+
+- 发现本机会话以及显式指定的 Codex home。
+- 先用 `--dry-run` 验证目标，再向原生 inbox / queue 提交一次消息。Codex 要求唯一且稳定的活跃 writer。
+- 通过 SSH 调用远端已安装的同版本客户端，支持结构化 Reply-To URI 和 JSON 输出。
+- 目标或进程归属不明确时拒绝操作；不会自动重试结果不确定的提交。
+
+未实现 Windows、Relay 传输、MCP、wake/resume、非活跃会话排队、Antigravity、自动更新、隐式多代理发现及面向人的文本输出。不支持的命令会明确失败；这不是通用编排器。
+
+## 环境要求
+
+macOS 或 Linux；Node **22.x 中的 22.13 及以上，或 24.x**。不支持 Node 26。原生 flock 依赖需要匹配的 x64/arm64 预编译二进制，本包不是纯 JavaScript 实现。Codex 发送还需要 `codex`、`lsof`、`ps`；Claude 需要运行中的 TUI 及可访问的原生 inbox。SSH 使用已有密钥和主机信任，远端必须安装**同版本**客户端。
+
+## 安装
+
+在正式 npm 发布确认包归属和来源之前，**不要**运行注册表安装 `npm install -g session-peer` 或 `npx session-peer`。目前请构建经审查的源码，并按需安装本地 tarball：
+
+```sh
+git clone https://github.com/abruption/session-peer-ts.git
+cd session-peer-ts
+npm ci --ignore-scripts
+npm run build
+node dist/cli.js --version
+npm pack --ignore-scripts
+# 可选：全局安装前先检查 PATH 选择的现有命令
+npm install --global --ignore-scripts ./session-peer-0.1.0-preview.0.tgz
+session-peer --version
+```
+
+预期输出：`session-peer 0.1.0-preview.0 (typescript)`。保留 `./...tgz` 路径，确保安装的是本地构建产物，而非未验证的注册表包。将来另行批准 npm 发布后，包名和命令名仍如上所示，请按该次发布的版本 / dist-tag 安装。
+
+### 与已有安装共存
+
+安装前后用 `type -a session-peer` 和 `command -v session-peer` 检查实际执行项。其他实现也可能提供同名命令；请选择 PATH 上的一种，或显式运行 `node /absolute/path/dist/cli.js`。不要用 `--force` 覆盖其他管理器的文件。本包不会自动安装、删除或调整 Python 包、技能或服务。卸载使用 `npm uninstall --global session-peer`，随后再次检查 PATH。
+
+## 使用
+
+```sh
+session-peer list --agent claude --json
+session-peer list --agent codex --codex-home "$HOME/.codex" --json
+session-peer send --to CLAUDE_PID --message 'Please review the API contract.' --dry-run --json
+session-peer send --to codex:THREAD_UUID --codex-home "$HOME/.codex" --message 'Please review the API contract.' --dry-run --json
+```
+
+只有确定要投递时才移除 `--dry-run`。省略 `--message` 或使用 `--message -` 会读取 UTF-8 stdin。`--all` 仅让列表包含陈旧 / 已归档记录，不授予发送权限。Claude 支持 PID、`claude:PID` 或唯一的 ASCII 名称（不区分大小写）；Unicode 名称请改用 PID。Codex 需要完整 UUID 和显式 home；`--codex-bin` 可指定可执行文件。输出必须选择 `--json` 或 `--output-format json`。
+
+### 跨机器 SSH
+
+```sh
+session-peer send --host user@machine --remote-bin /absolute/path/session-peer \
+  --to CLAUDE_PID --message 'Please review the API contract.' --dry-run --json
+```
+
+默认远程命令是 PATH 中的 `session-peer`。绝对路径 `--remote-bin` 也可选择使用受支持 Node 的包装器。握手检查 TypeScript 标记及精确版本，不同实现会被拒绝。SSH 使用 BatchMode 和 StrictHostKeyChecking，不自动接受新主机密钥、不安装远程运行时，也不会退回 Python。消息通过 JSON stdin 传输，不放进远程 shell 参数。不支持任意 `--ssh-opt`、IPv6 字面量或 Tailscale 规范名补全，请使用 SSH 别名 / 主机名。正向访问不意味着反向访问已配置。
+
+### 回复
+
+可将 `session-peer://v1/reply?...` URI 用作 `--to`。未知 / 重复字段、不安全主机、错误编码及与显式路由的冲突都会被拒绝。`--reply-address URI` 添加显式回信地址，不自动推断或验证回程。回复时不附加新地址可用 `--no-reply-to`。有效的 CODEX_THREAD_ID / CODEX_SESSION_ID 可提供参考性 From 信息，`--no-from` 可省略；不会虚构未知发送者。peer 元数据不是授权，Reply-To URI 也不会作为 shell 文本执行。
+
+## 成功含义与安全性
+
+| 结果 | 含义 |
+| --- | --- |
+| `validated`, `submitted:false` | dry-run 检查通过，尚未发送。 |
+| `posted` / `queued` | inbox 已写入 / queue 已接受，**不是消费确认或 ACK**。 |
+| `refused`, `submitted:false` | 提交前被拒绝。 |
+| `unknown`, `submitted:null` | 可能已经提交，不要自动重发。 |
+
+`consumptionConfirmed` 始终为 false。必须在目标 TUI 中另行确认实际 ACK，不可由排队或轮询 transcript 推断。退出码 0/1/2 分别表示成功/错误/用法错误。错误只返回固定代码，不返回原生 stderr 或消息内容。Codex 使用真实内核 flock、文件身份和同用户进程开始时间进行多次核验，排队前再次检查。不删除 lock，也不向拥有它的代理进程发送信号。发现结果仍包含本地名称、路径、ID，分享前请脱敏。
+
+## 开发与验证
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node scripts/check-repository.mjs
+SESSION_PEER_PYTHON_ROOT=/path/to/python-reference npm test
+npm run test:package
+npm audit
+```
+
+Python 只用作开发时的兼容性基准（v1.0.2，`47c23713d0a2a3c11ebde6186afd8c43489b8b65`），不是运行时依赖。测试还需要 C 编译器和 lsof。CI 固定基准提交，覆盖 macOS/Linux × Node 22/24。临时 SQLite、Unix inbox、真实锁 fixture 与 [VALIDATION.md](VALIDATION.md) 中专用真实 TUI 的证据分开记录；fixture 通过不是 ACK。包测试检查文件清单、重复打包哈希、全新安装与卸载。原生依赖通常有安装脚本，已验证的预编译路径使用 `--ignore-scripts`。SQLite 只读连接仍可能参与 WAL 共享内存管理，不能视为快照。
+
+参见 [CONTRIBUTING.md](CONTRIBUTING.md)、[RELEASING.md](RELEASING.md) 和 [SECURITY.md](SECURITY.md)。发布需单独批准，未启用自动 npm 发布。采用 [MIT](LICENSE) 许可证。
+
+## npm 发布后的安装
+
+仅在官方发布以及注册表完整性、provenance 验证完成后，安装以下精确预览版本。它不是稳定版 `latest`。公开前继续使用上述本地 tarball 安装。
+
+```sh
+npm install --global --ignore-scripts session-peer@0.1.0-preview.0
+session-peer --version
+```
+
+手动工作流仅在首次发布时使用短期 bootstrap 令牌。以后通过 Trusted Publisher OIDC 上传至 staging，由维护者使用 2FA 批准。staging 成功不代表已经公开发布。参见 [RELEASING.md](RELEASING.md)。
+
+## 相关项目
+
+[Python session-peer](https://github.com/abruption/session-peer) 独立维护和发布，其可选功能与安装指南（例如 `pipx install session-peer`）见该项目。同样使用 `session-peer` 命令，请注意上述 PATH 规则。本客户端不依赖该安装，也不承诺功能和参数完全对等。