一条消息的完整路径

七步的文件级展开

第1课 1.5 的旅程图给了七步鸟瞰；这里把每一步落到模块与磁盘文件——crosschat 的全部状态就这几处，别无暗层：

两处时序细节常被问：⑦ 在投递结局之后——failed 不落分片（--to 接续不被失败尝试污染），账本四种结局都记；短柄分配写与⑦合一次——分配柄不单独推进分片的对话线，骑在原有写上顺带完成。

claude 腿的字节

往目标会话的管道写换行分隔的单行 JSON，写一次、关连接、永不重试：

win32：两行                          unix：一行（无 auth）
{"type":"auth","token":"…"}          {"msgV":1,"msg_id":"<uuid>","type":"user",
{"msgV":1,"msg_id":"<uuid>",…}        "message":{"role":"user","content":"…"},
                                     "priority":"next"}

• auth 行的 token 来自 sessions 目录旁的密钥文件，文件名 = <pid>.<sha256(归一化管道路径)>.key——归一化保留 \\.\pipe\ 前缀、其余小写，这是 Claude Code 自己的哈希规则，crosschat 照办。
• unix 为什么省 auth：同一用户的身份由内核凭据担保（管道两端同 uid），无需令牌。
• 写后 250ms 宽限：对端正常会在收到 EOF 后立刻关连接；短宽限让断管以错误浮出——命名管道的写错误可能比写完成回调晚一拍，不等这一下会把断管误报成 delivered。

codex 腿的调用序

一次投递一条全新链，从进程到协议逐层拉起再整体回收：

解析 codex 可执行文件（win：npm 布局/where/daemon 目录三选一）
spawn codex app-server proxy（子进程环境剥掉两族身份变量）
stdio 双工上做 WebSocket 升级（ws://localhost/rpc，帧=ws 文本消息）
initialize（声明 experimentalApi）
thread/resume（目标线程）→ 状态判定：
   idle / busy → 继续（busy 在 ≥0.160 直接入队）
   waiting_approval → 停，CODEX_APPROVAL_REQUIRED（审批永不代答）
   not_loaded / 写者锁拒绝 → 轮询等 ~10s，仍不行 → parked
turn/start（turnTrigger: crosschat）→ 确认 inProgress
thread/unsubscribe → close（先 ws close 帧，再杀自己 spawn 的进程树）

线协议两个硬事实（实测钉死）：响应与通知帧没有 jsonrpc 字段，解析不得要求它；客户端方法白名单封闭，越界即编程错误。每请求 30 秒超时，超时后的迟到响应丢弃不视为故障。

落盘时序与原子性

• 分片写：读旧 → 内存合并 → 写 *.tmp → rename 覆盖——原子性由文件系统 rename 担保，读者永远不会看到半份 JSON。
• 账本写：追加前查大小，超 5MB 先把旧 .old 删掉、当前文件 rename 成 .old，再追加——历史整份保留，不做原地截断；轮转失败不拦追加（下次再试）。
• mailbox：尽力而为的镜像（追加失败不影响队列本体），权威永远是 outbox 的 JSON。
• 三者的顺序：投递结局 → 账本 → 分片。崩溃卡在中间的后果有界：账本缺一行（那条消息状态以回执为准）或分片滞后一轮（下次 send 自愈）。

并发——谁和谁会撞

设计姿态一句话：crosschat 不上跨进程锁阵，靠“原子写 + 自包含引用 + 自愈读“把竞态后果压到一轮以内——比锁便宜，比锁好懂。

跨机腿

ssh 腿在单机路径外再包一层壳，投递内核原样——对端跑的就是一条完整的本机 send：

身份注入（–origin）与错误三层映射的完整语义见2.6 通信机制与ssh 命令详解。