feat(handoff): add private correlation ledger and evidence CLI

PARITY.md

@@ -1039,3 +1039,23 @@ automated ACK support in the TS implementation. Cross-runtime execution,
 receipt bootstrap, original generation and platform acceptance remain #69–72
 implementation gates. This design-identity record alone does not repin a runtime
 reference or establish runtime conformance.
+
+
+## Unreleased handoff implementation — #70
+
+The frozen #69 design pin is unchanged. Source-only private POSIX ledger and
+strict protocol helpers now implement prepare, at-most-once sender fencing,
+status, bounded wait records and explicit receipt/operator-confirmation
+validation. [CLI details](docs/api.md#unreleased-opt-in-handoff-cli--040-work)
+separate current source support from the published 0.3.5 runtime. Automated ACK
+bootstrap, Windows private ACL support and original-sender SSH coordination are
+still implementation gates. Fixture passes are not live receipt/injection
+qualification. Default output and the historical Python runtime parity pin stay
+unchanged; no future Python runtime is claimed shipped.
+
+The journal encrypts its private message-binding digest with a separate
+mode-0600 `ledger.key`; missing/changed/untrusted keys and plaintext journals
+are refused without automatic key recovery or history migration. This is an
+at-rest journal boundary, not protection against a reader of both private
+files. Duplicate committed operator confirmation returns the original receipt
+without rewriting its wait classification or journal.

README.ja.md

@@ -114,6 +114,8 @@ session-peer --version
 
 - [0.4.0 handoff 設計（共同合意・未実装）](PARITY.md#handoff-v1-design-candidate--69).
 
+- [開発中の private handoff CLI と制限](docs/api.md#unreleased-opt-in-handoff-cli--040-work).
+
 ## License
 
 [MIT ライセンス](LICENSE)で公開しています。

README.ko.md

@@ -128,6 +128,8 @@ session-peer --version
 
 - [0.4.0 handoff 설계(공동 확정·미구현)](PARITY.md#handoff-v1-design-candidate--69).
 
+- [개발 중인 private handoff CLI와 지원 한계](docs/api.md#unreleased-opt-in-handoff-cli--040-work).
+
 <a id="license"></a>
 ## 라이선스
 

README.md

@@ -114,6 +114,8 @@ does not install a skill. Review its pinned-source instructions in the guide.
 
 - [0.4.0 handoff design (jointly agreed, unimplemented)](PARITY.md#handoff-v1-design-candidate--69).
 
+- [Unreleased private handoff CLI and limitations](docs/api.md#unreleased-opt-in-handoff-cli--040-work).
+
 ## License
 
 Licensed under the [MIT License](LICENSE).

README.zh-CN.md

@@ -110,6 +110,8 @@ session-peer --version
 
 - [0.4.0 handoff 设计（联合确认、未实现）](PARITY.md#handoff-v1-design-candidate--69).
 
+- [开发中的 private handoff CLI 与限制](docs/api.md#unreleased-opt-in-handoff-cli--040-work).
+
 ## License
 
 采用 [MIT 许可证](LICENSE)。

docs/api.md

@@ -33,3 +33,52 @@ not package subpath exports. Use the [CLI guide](guide.md#use) for sending and
 
 
 The ordinary SSH response correction is documented separately as the [0.3.3 ordinary SSH response correction](design/ordinary-ssh-responses.md); its internal parser is not a package-root export.
+
+## Unreleased opt-in handoff CLI — 0.4.0 work
+
+This source adds an explicit private POSIX sender ledger. The published 0.3.5
+package does not contain these commands. Default sends retain their native
+status, optional fields and exit behavior. The frozen design is tracked in #69;
+this implementation does not change its exact vendored document or fixture.
+
+Initialize once with `session-peer handoff init --json`. The optional absolute
+`SESSION_PEER_HANDOFF_HOME` selects its directory; commands never auto-initialize
+missing or corrupt history. `handoff prepare --to TARGET --message-file FILE
+--json` reserves a fresh correlation ID without sending. Use a private regular
+UTF-8 file (POSIX mode 0600), then pass the retained ID with
+`send --correlation-id UUID --message-file FILE --json`. A changed destination,
+original generation or message binding is rejected. An unknown supplied ID is
+not accepted. Ordinary opted-in sends can automatically prepare a fresh ID.
+
+Only opted-in results add `handoff`. The inert correlation metadata in a native
+message is not authentication. Durable intent is fenced before native effect;
+crash recovery, `handoff status`, `handoff wait`, `ack` and `handoff confirm`
+never submit again. Retention/quota limits preserve epoch-bound fences rather
+than evicting old authority. Clone/rollback protection assumes intact, retained,
+non-rolled-back history. Native local/SSH retry permission remains false.
+
+Keep `ledger.key` with the private ledger: the journal stores an authenticated
+encrypted message-binding digest, using that separate mode-0600 key. The raw
+digest is not stored in the journal. Missing, changed or untrusted keys and old
+plaintext journals fail closed; commands do not regenerate a key or migrate
+history automatically. This does not protect against a same-user reader who
+can obtain both files. Lost history never authorizes resubmission.
+
+`--request-ack`, `--observe-delivery` and `--wait-for delivered|acknowledged`
+select separate evidence goals. A required unsupported goal refuses before
+submission; best-effort mode may submit while reporting the channel unsupported.
+`--wait-timeout` is an ASCII integer 1..60 (default 30); its total operation
+budget includes a 5-second cleanup reserve. Budgets 1..5 are syntactically valid
+but cannot authorize an effect. A successful submission is preserved when
+subsequent ledger/evidence operations fail. Best-effort sends keep their native
+success exit and may add `handoffWarning: persistence_failed`; required waits
+fail without erasing independently established native submission facts. No body, transcript, raw native
+stderr, payload digest or receipt secret appears in handoff JSON.
+
+Automated receipt producer/bootstrap, Windows ledger and original-sender SSH
+handoff coordination remain unsupported. `ack --receipt -` and `handoff confirm
+--receipt -` consume at most 4096 raw UTF-8 bytes from private stdin; no receipt
+secret is accepted in argv/URI/environment. Receipt ACK means receipt only, not
+ownership, completed work or permission to act. Operator confirmation is
+explicitly labeled and must match retained original context. No arbitrary
+message/transcript scan manufactures ACK. Ordinary generated Reply-To stays v1.

docs/guide.ja.md

@@ -338,3 +338,10 @@ npm `--ignore-scripts` は利用でき、postinstall は Skills CLI を呼び出
 
 任意の `sp` 短縮名は 0.3.0 以降に含まれ（0.2.1 以前にはありません）、自動では有効になりません。
 [明示的な有効化・衝突・解除(英語)](shorthand.md)を参照してください。
+
+
+## Unreleased handoff
+
+開発中の 0.4.0 ソースには opt-in private POSIX handoff ledger が追加されます。公開 0.3.1 にこのコマンドはありません。必須の証拠が unsupported の場合は提出前に拒否し、best-effort の提出は ACK を証明しません。自動 receipt bootstrap、Windows ledger、SSH handoff は未対応です。
+
+[CLI](api.md#unreleased-opt-in-handoff-cli--040-work)

docs/guide.ko.md

@@ -592,3 +592,9 @@ npm `--ignore-scripts`로 설치해도 되며, 설치 후 Skills CLI를 호출
 
 선택적 `sp` 단축 이름은 0.3.0 이상에 포함되며(0.2.1 이하에는 없음) 자동으로 켜지지 않습니다.
 [명시적 활성화와 이름 충돌 안내(영문)](shorthand.md)를 참고하세요.
+
+## Unreleased handoff
+
+개발 중인 0.4.0 소스에는 opt-in private POSIX handoff ledger가 추가됩니다. 공개 0.3.1에는 이 명령이 없습니다. 필수 증거 채널이 unsupported이면 제출 전에 거절하며, best-effort 제출은 ACK를 증명하지 않습니다. 자동 receipt bootstrap, Windows ledger 및 SSH handoff는 아직 미지원입니다.
+
+[CLI](api.md#unreleased-opt-in-handoff-cli--040-work)

docs/guide.md

@@ -618,3 +618,10 @@ install a runtime. See [compatibility and validation](../PARITY.md#source-ts-ski
 
 Optional `sp` shorthand ships with 0.3.0 and later (not 0.2.1 or earlier) and is
 never enabled automatically. See [explicit activation and collisions](shorthand.md).
+
+
+## Unreleased handoff
+
+Unreleased 0.4.0 source adds an opt-in private POSIX handoff ledger. Published 0.3.1 has no handoff commands. Required unsupported evidence refuses before submission; best-effort unsupported evidence never proves ACK. Automated receipt bootstrap, Windows ledger and SSH handoff remain unsupported.
+
+[CLI](api.md#unreleased-opt-in-handoff-cli--040-work)

docs/guide.zh-CN.md

@@ -322,3 +322,10 @@ postinstall 不会调用 Skills CLI，安装此技能不会覆盖 Python 技能
 
 可选的 `sp` 简写包含在 0.3.0 及更高版本中（0.2.1 及更早版本没有），不会自动启用。
 请参阅[显式启用、冲突与停用(英文)](shorthand.md)。
+
+
+## Unreleased handoff
+
+开发中的 0.4.0 源码加入 opt-in private POSIX handoff ledger。已发布的 0.3.1 不含这些命令。所需证据通道 unsupported 时在提交前拒绝；best-effort 提交并不证明 ACK。自动 receipt bootstrap、Windows ledger 和 SSH handoff 尚不支持。
+
+[CLI](api.md#unreleased-opt-in-handoff-cli--040-work)

scripts/release.mjs

@@ -19,7 +19,7 @@ export const packageFiles = ['UNICODE-LICENSE.txt', 'dist/casefold.js', 'dist/ca
   'dist/cli.js', 'dist/discovery.js', 'dist/diagnostics.js', 'dist/skill-metadata.js', 'dist/process.js', 'dist/protocol.js', 'dist/replies.js', 'dist/send.js', 'dist/ssh.js', 'dist/ssh-response.js',
   'dist/windows.js', 'dist/writer.js', 'dist/index.js', 'dist/index.d.ts', 'dist/cli.d.ts',
   'dist/discovery.d.ts', 'dist/diagnostics.d.ts', 'dist/skill-metadata.d.ts', 'dist/process.d.ts', 'dist/protocol.d.ts',
-  'dist/replies.d.ts', 'dist/send.d.ts', 'dist/ssh.d.ts', 'dist/ssh-response.d.ts', 'dist/windows.d.ts', 'dist/writer.d.ts', 'dist/updates.js', 'dist/updates.d.ts', 'package.json'].sort();
+  'dist/replies.d.ts', 'dist/send.d.ts', 'dist/ssh.d.ts', 'dist/ssh-response.d.ts', 'dist/windows.d.ts', 'dist/writer.d.ts', 'dist/updates.js', 'dist/updates.d.ts', 'dist/handoff.js', 'dist/handoff.d.ts', 'dist/handoff-ledger.js', 'dist/handoff-ledger.d.ts', 'dist/handoff-operations.js', 'dist/handoff-operations.d.ts', 'package.json'].sort();
 const json = path => JSON.parse(readFileSync(path, 'utf8'));
 const digest = (bytes, algorithm, encoding = 'hex') => createHash(algorithm).update(bytes).digest(encoding);
 const npm = args => execFileSync('npm', args, { encoding: 'utf8', timeout: 120000 });