env@earendil-works/pi-env

要点Key points

• 支持的远端：Linux、macOS、Android（Termux）与 Windows，x86-64 与 arm64。Windows 上字符串命令像 NodeExecutionEnv 那样通过 Git Bash 运行，argv 命令直接运行。Supported remotes: Linux, macOS, Android (Termux) and Windows, on x86-64 and arm64. On Windows, string commands run through Git Bash as NodeExecutionEnv runs them; argv commands run directly.
• 测试对 RemoteExecutionEnv 跑 Durable 的 env 一致性套件，并把随机操作序列和 Durable 的工具与本机 NodeExecutionEnv 比对（differential 测试）。Tests run Durable's env conformance suite against RemoteExecutionEnv and compare random operation sequences and Durable's tools with NodeExecutionEnv on the same machine (differential tests).
• RemoteExecutionEnv 需要一个 id：相同 id 表示看到同样的文件，Durable 的 edit / write 按 id 加路径串行化修改。RemoteExecutionEnv takes an id: equal ids see the same files, and Durable's edit / write serialize changes by id plus path.

工作原理How it works

1. const { connection } = await connectSsh(target)。const { connection } = await connectSsh(target).
2. new RemoteExecutionEnv({ connection, id: "pi-env:gpu", cwd: "/home/me/project" })。new RemoteExecutionEnv({ connection, id: "pi-env:gpu", cwd: "/home/me/project" }).
3. 交给 Durable：Harness.open(storage, { …, env: () => remoteEnv }, ctx)。Hand it to Durable: Harness.open(storage, { …, env: () => remoteEnv }, ctx).

要点Key points

• docs/semantics.md 记录了标准库不遵守、但这里必须遵守的规则：递归 mkdir 遇到已有文件报 EEXIST；rm 目录不带 recursive 报 ERR_FS_EISDIR；listDir 按字节序；mkdtemp 的前缀用 POSIX path.join……docs/semantics.md records rules the standard libraries do not follow but this must: a recursive mkdir over an existing file fails with EEXIST; rm of a directory without recursive gives ERR_FS_EISDIR; listDir is in byte order; mkdtemp joins its prefix with POSIX path.join…
• tmpdir 按 TMPDIR、TMP、TEMP、/tmp 的顺序（Termux 用 $PREFIX/tmp），与远端 Node 的 os.tmpdir() 一致。tmpdir follows TMPDIR, TMP, TEMP, then /tmp (Termux: $PREFIX/tmp), matching the remote Node's os.tmpdir().
• 命令输出按流解码为 WHATWG UTF-8（encoding_rs），只丢掉开头的 BOM；文件读取保留 BOM——都和 Node 的行为对齐。Command output is decoded per stream as WHATWG UTF-8 (encoding_rs) with only a leading BOM dropped; file reads keep the BOM — both matching Node.

工作原理How it works

1. 改动任何一边的语义，都要跑 test/differential.test.ts：它在两种环境上执行同一串随机操作并比较结果。Changing semantics on either side means running test/differential.test.ts: it runs the same random operation sequence on both environments and compares results.
2. 自定义环境可以用 Durable 的 registerEnvConformance() 自检。A custom environment can check itself with Durable's registerEnvConformance().
3. 真实 SSH：设置 PI_ENV_SSH_HOST 后 test/ssh-external.test.ts 在真正的服务器上跑套件。Real SSH: with PI_ENV_SSH_HOST set, test/ssh-external.test.ts runs the suite against a real server.

要点Key points

• 守护进程放在 ~/.pi/mobile/tools/pi-env-<sha256 前 32 位>：按内容命名，版本之间不会冲突；每次启动前都先校验哈希。The daemon lives at ~/.pi/mobile/tools/pi-env-<first 32 of sha256>: named by content so versions never collide, and its hash is checked before every start.
• 上传写到同目录的 mktemp 临时文件，哈希一致才 chmod 700 并 mv 到位，然后删除其他版本（运行中的保持打开直到退出）。远端没有 sha256sum / shasum / openssl 时直接报错。The upload goes to a mktemp file in the same directory and is chmod 700-ed and mv-ed into place only if its hash matches; other versions are then removed (running ones stay open until they exit). A remote without sha256sum / shasum / openssl is an error.
• ssh 选项锁死：BatchMode=yes、不转发任何东西、ControlMaster=no、RemoteCommand=none、SendEnv=-*、主机密钥按应用自己的 known-hosts 文件严格检查。ssh 配置仍决定路由（别名、跳板机），但加不进提示、转发或命令。ssh options are pinned: BatchMode=yes, no forwarding of any kind, ControlMaster=no, RemoteCommand=none, SendEnv=-*, host keys checked strictly against the application's own known-hosts file. The ssh config still picks the route (aliases, jump hosts) but cannot add prompts, forwarding or commands.
• Windows 远端通过 PowerShell 探测与部署（base64 上传、Get-FileHash），守护进程通过服务器默认 shell 启动。Windows remotes are detected and deployed through PowerShell (base64 upload, Get-FileHash), and the daemon starts through the server's default shell.

工作原理How it works

1. const { lines, fingerprints } = await scanHostKey(target) → 用户确认 → await acceptHostKey(target, lines)。const { lines, fingerprints } = await scanHostKey(target) → the owner confirms → await acceptHostKey(target, lines).
2. 立即连接：await connectSsh(target)；懒连接：sshConnection(target)，第一次操作时才探测、部署、连接，失败只是那次操作的错误。Eager: await connectSsh(target); lazy: sshConnection(target) detects, deploys and connects on the first operation, and a failure is just that operation's error.
3. POSIX 上 loginShell: true 让守护进程经 $SHELL -l 启动，命令能看到 ~/.profile 里的环境。On POSIX, loginShell: true starts the daemon through $SHELL -l so commands see the environment from ~/.profile.

要点Key points

• 文件内容和命令输出走原始字节负载，不做 base64；更大的传输由客户端拆分。File contents and output travel as raw payload bytes, not base64; larger transfers are split by the client.
• 错误是 { code, message, syscall?, path? }，code 是 Node 风格的（ENOENT、ERR_FS_EISDIR…）或执行错误码；只有 code 属于契约，消息只用于诊断。Errors are { code, message, syscall?, path? } with a Node-style code (ENOENT, ERR_FS_EISDIR…) or an execution code; only codes are part of the contract, messages are diagnostic.
• 路径都是绝对路径：客户端先解析相对路径、~ 和 file://。字符串以合法 UTF-8 发送（孤立代理项变成 U+FFFD），和 Node 编码字符串参数的方式一致。Paths are absolute: the client resolves relative paths, ~ and file:// first. Strings are sent as well-formed UTF-8 (lone surrogates become U+FFFD), as Node encodes string arguments.
• 第一个请求是 hello { protocol }，返回 os、arch、home、tmpdir、cwd、Windows 的 driveCwds 和 pid。The first request is hello { protocol }, which returns os, arch, home, tmpdir, cwd, Windows' driveCwds and the pid.

工作原理How it works

1. 客户端：Connection.request(op, json, { payload, signal }) 分配 id、写帧、等 result 或 error。Client: Connection.request(op, json, { payload, signal }) assigns an id, writes the frame, and waits for result or error.
2. 守护进程：serve_frames() 读帧，按 type 分派；request 先登记再执行，所以紧随其后的 cancel 不会丢。Daemon: serve_frames() reads frames and dispatches by type; a request is registered before it runs, so a cancel right after it is never lost.
3. JSON 解析失败的请求得到 EINVAL；帧格式错误直接断开连接。A request whose JSON does not parse gets EINVAL; a framing error ends the connection.

要点Key points

• 丢失时正在进行的变更（写入、改名…）结果未知：可能执行了，也可能没有。For mutations in flight when the link is lost (writes, renames…), the outcome is unknown: they may or may not have happened.
• 句柄属于打开它的那个守护进程：旧句柄上的请求直接失败，绝不会落到新进程上。Handles belong to the daemon that opened them: requests on old handles fail instead of reaching the new one.
• isConnectionLost(err) 区分"断线"与"守护进程拒绝了请求"；丢失的原因可能是进程退出、帧损坏、30 秒静默或协议版本不符。isConnectionLost(err) tells "lost" apart from "the daemon refused the request"; causes are a process exit, a corrupt frame, 30 seconds of silence or a protocol mismatch.

工作原理How it works

1. #start()：启动进程 → 丢弃输出直到 PI-ENV <token> → 发 hello { protocol: 1 } → 检查版本。#start(): spawn → discard output until PI-ENV <token> → send hello { protocol: 1 } → check the version.
2. 定时器每 5 秒发 ping，并检查 lastSeen：超过 30 秒就 #teardown()。A timer pings every 5 seconds and checks lastSeen: after 30 seconds it calls #teardown().
3. 监视器在新守护进程上重新打开并报告一次 overflow（见文件监视一节）。Watchers reopen on the new daemon and report one overflow (see the watching section).

要点Key points

• 调度：结果、错误、ping 和 watch 事件排在命令输出之前，超过 64 KiB 的结果也排到输出后面——慢链路只延迟大块数据，不延迟回复。Scheduling: results, errors, pings and watch events go before queued command output, and results above 64 KiB queue behind output too — a slow link delays bulk data, not replies.
• 没有窗口的命令在未发输出超过 4 MiB 时等待，像写满的管道一样拖慢命令。A command without a window waits while more than 4 MiB of output is unsent, slowing it the way a full pipe would.
• 超时、cancel 与 cleanup() 都用 SIGKILL 杀整个进程组：取消以 aborted 结束；cleanup() 用 { mode: "kill" }，命令以退出码 137 结束。Timeout, cancel and cleanup() all SIGKILL the process group: a cancel settles as aborted; cleanup() uses { mode: "kill" }, so the command settles with exit code 137.
• 进程退出后继续收集输出，直到两个管道都关闭或 100 ms 没有输出；命令结束时管道一定关闭，即使后代进程还开着它们。After the process exits, output is still collected until both pipes end or 100 ms pass silently; the pipes are closed when the command settles, even if a descendant keeps them open.

工作原理How it works

1. env.exec("npm test", { onOutput, timeout, spill, window }, ctx)，或 argv：env.exec(["git", "status"], …)。env.exec("npm test", { onOutput, timeout, spill, window }, ctx), or argv: env.exec(["git", "status"], …).
2. 字符串命令：配置的 shellPath（不存在则 shell_unavailable），否则 /bin/bash、which bash、sh，加 -c。String commands: the configured shellPath (missing → shell_unavailable), else /bin/bash, which bash, sh, with -c.
3. 环境变量：默认 inheritEnv 时依次叠加守护进程环境、shellEnv、env；否则只用 env。Environment: with inheritEnv (the default) the daemon's environment, then shellEnv, then env; without it, only env.

要点Key points

• write 默认像递归 mkdir 那样创建缺失的父目录；带 keep 时返回句柄供后续 writeChunk，一块失败后后续块都报 EBADF。write creates missing parents like a recursive mkdir by default; with keep it returns a handle for later writeChunks, and after a failed chunk later chunks fail with EBADF.
• open 有两种：给 openBinaryReader 的非阻塞、只限普通文件（noFollow 用 O_NOFOLLOW）；以及 mode: "read" 的阻塞打开，和 Node 的 open(path, "r") 一样能读 /dev/null、FIFO。open comes in two kinds: nonblocking and regular files only for openBinaryReader (noFollow uses O_NOFOLLOW), and mode: "read", a blocking open like Node's open(path, "r") that reads /dev/null or a FIFO.
• readdir 的名字按 UTF-8 解码（非法字节换成替换字符），原始字节放在 raw 里用于排序；listDir 每次读最多 1000 项。readdir decodes names as UTF-8 (invalid bytes become replacement characters) and keeps the original bytes in raw for sorting; listDir reads at most 1000 entries at a time.
• 错误映射与 NodeExecutionEnv 相同：ENOENT → not_found，EACCES / EPERM → permission_denied，ENOTDIR、EISDIR、EINVAL 等。Error mapping matches NodeExecutionEnv: ENOENT → not_found, EACCES / EPERM → permission_denied, ENOTDIR, EISDIR, EINVAL and so on.

工作原理How it works

1. env.readTextFile(path, ctx) → open(mode:"read") → 按 512 KiB pread → StringDecoder 解码。env.readTextFile(path, ctx) → open(mode:"read") → pread in 512 KiB → decode with StringDecoder.
2. env.writeFile(path, content, ctx) → write(keep) + 多个 writeChunk，每块之前检查取消。env.writeFile(path, content, ctx) → write(keep) + writeChunks, checking for abort before each.
3. openBinaryReader(path).scanLines({ startLine, endLine }) 在守护进程里数行，只把结果传回来。openBinaryReader(path).scanLines({ startLine, endLine }) counts lines in the daemon and sends back only the result.

要点Key points

• 去抖 50 ms（FSEvents 再等 500 ms 稳定）；轮询默认每 2000 ms；最多 10,000 个目录；≤ 256 KiB 的文件比较哈希。Debounce 50 ms (FSEvents settles another 500 ms); polling every 2000 ms by default; at most 10,000 directories; files ≤ 256 KiB are compared by hash.
• 原生监视用尽时切换到轮询，并报告 { kind: "change", overflow: true, mode: "polling" }。Running out of native watches switches to polling and reports { kind: "change", overflow: true, mode: "polling" }.
• 连接丢失后，客户端的 RemoteWatcher 在新守护进程启动后重新打开监视并报告 overflow；重连退避从 1 秒到 30 秒。After a lost connection, the client's RemoteWatcher reopens the watch once a new daemon starts and reports overflow; reconnect back-off runs from 1 s to 30 s.

工作原理How it works

1. env.watch([{ path, recursive: true, exclude: { hidden, names } }], onChange, ctx)。env.watch([{ path, recursive: true, exclude: { hidden, names } }], onChange, ctx).
2. 收到 overflow 时整体重新读取，不要只依赖路径列表。On overflow, re-read everything rather than trusting the path list.
3. 关闭：watcher.close(ctx) 发 cancel，watch 以 {} 结束。Close: watcher.close(ctx) sends a cancel and the watch finishes with {}.