pinomad 0.1.0 → 0.2.0

package/README.md

@@ -89,7 +89,7 @@ bun run pair         # 打印配对二维码（一次性，5 分钟过期）
 bun run host -- --remote-port 7422 --public-url https://pinomad.example.com
 ```
 
-远程端口不接受 token：只有完成配对、公钥已登记在设备表里的客户端能连。
+远程端口不接受 token：只有完成配对、公钥已登记在设备表里的客户端能连。不开 `--remote-port` / `--relay` 时 `pair` 打印的是回环链接（回环端口 `/secure` 路径上的安全通道），只能给本机上的客户端用，比如桌面端 App。桌面端 App 可以配对多台宿主，在侧栏底部切换（一次只连一台）。App 会自动检查更新（GitHub Release 上的 `latest-mac.yml`，自动下载、不自动安装），下载完成后侧栏底部出现 "Restart to update"，也可以在菜单里手动 Check for Updates…。
 
 </details>
 
@@ -138,7 +138,39 @@ Restart=always
 WantedBy=multi-user.target
 ```
 
-升级：中继托管的 Web 客户端和宿主版本不一致时，客户端会显示需要更新；两边一起升级——宿主 `pinomad upgrade`，VPS 上 `npm i -g pinomad@latest` 后重启中继。宿主不在中继的 `--allow-host` 里时，宿主日志和 Web 警告会带着要补的 `--allow-host <hostId>`。
+#### 容器平台（Zeabur 等）
+
+镜像在 `deploy/relay/Dockerfile`，装的是锁版本的 npm 发布包（`ARG PINOMAD_VERSION`）。平台终结 TLS 并转发到 `$PORT`（默认 8080），不需要 Caddy。中继把转接状态放在内存里，**只能跑一个实例**，不要开扩容。
+
+| 环境变量 | 含义 |
+|---|---|
+| `PINOMAD_PUBLIC_ORIGIN` | 客户端打开的 https origin，比如 `https://nomad.example.com` |
+| `PINOMAD_ALLOW_HOST` | 允许登记的 hostId，多个用空格分隔（每台宿主上跑 `pinomad relay-id`） |
+| `ZBPACK_DOCKERFILE_PATH=Dockerfile` | **Zeabur 必加**：目录里只有一个 Dockerfile 时，Zeabur 会把它识别成静态站点、用 Caddy 托管文件，中继根本没启动；这个变量强制按 Dockerfile 构建（部署日志里应是 `PLANTYPE=docker`） |
+
+Zeabur 上的步骤（在 Dedicated Server 上部署，用 CLI 上传目录，不接 GitHub）：
+
+```sh
+cd deploy/relay
+zeabur deploy --project-id <项目 id> --create --name pinomad-relay   # 首次：在项目里建出服务
+# 之后重新部署同一个服务：
+zeabur deploy --service-id <服务 id>
+```
+
+然后在服务上配好上面的环境变量（`PORT` 由平台注入，不用自己设），在 Domains 里绑定自定义域名，到 DNS 加一条记录：Dedicated Server 用 **A 记录指向服务器 IP**；Cloudflare 上建议**关掉代理（灰云）**，橙云会让国内访问多绕一圈，证书也由 Zeabur 自己签。域名状态变成 `PROVISIONED` 后，验证：
+
+```sh
+curl -sI https://nomad.example.com/          # 200，中继托管的 Web 客户端
+pinomad service install --relay https://nomad.example.com …   # 宿主接上中继
+```
+
+宿主登记成功会在日志里写一行 `{"event":"relay","status":"registered",…}`，掉线重连时写 `"status":"connecting"`（`pinomad service logs` 查看）；也可以从外面连设备入口 `wss://<origin>/c/<hostId>` 确认：宿主在线时连接保持打开（等握手），没登记会立刻以 `4604`（hostOffline）关闭。
+
+也可以从 GitHub 仓库部署：Root Directory 设 `deploy/relay`、Watch Paths 限 `deploy/relay/**`，其余同上。
+
+#### 升级
+
+中继托管的 Web 客户端和宿主版本不一致时，客户端会显示需要更新；两边一起升级——宿主 `pinomad upgrade`，VPS 上 `npm i -g pinomad@latest` 后重启中继；容器部署则是改 Dockerfile 里的 `PINOMAD_VERSION`，再在 `deploy/relay` 下重新 `zeabur deploy --service-id <服务 id>`（从 GitHub 部署的话合进 main 即触发）。宿主不在中继的 `--allow-host` 里时，宿主日志和 Web 警告会带着要补的 `--allow-host <hostId>`。
 
 npm 装的实例和本机任何开发检出互不相干（各自的数据目录、进程、包路径都独立），所以在同一台机器上开发 PiNomad 不会碰到正在跑的服务。
 
@@ -160,8 +192,9 @@ pinomad upgrade [--force]
 - `restart` 先连上宿主读任务图，有未结束的任务就等它们跑完再重启（Ctrl-C 取消）；`--force` 立即重启，交给 Durable 恢复。打包安装时 `upgrade` 把 `pinomad@latest` 装进运行包所在的 npm 全局前缀（非全局安装会拒绝执行）+ 同样的 restart；源码检出里（`bun run upgrade`）依次 `git pull --ff-only`、`bun install`、`bun run build`，工作区有未提交改动时拒绝执行。前面任何一步失败都直接停下，不重启，服务继续跑旧代码。
 - `uninstall` 只卸载服务，不动数据目录。
 - macOS：宿主以登录会话运行，机器重启后要能自动起来需在系统设置里打开自动登录，并为这台机器关掉睡眠。日志写到 `<数据目录>/logs/host.log`。
-- Linux：要在未登录时也运行需自己执行 `loginctl enable-linger`（install 检测到没开会提示）；日志走 `journalctl --user`。
-- 服务模式下**回环端口也用 HTTP 提供构建好的 Web 客户端**。`pinomad link` 打印的链接按顺序探测：正在跑的 vite 开发服务器（5199）优先；否则宿主自己提供 Web 的端口；都没有则仍是 5199。开发时 `bun run start` + vite 照旧。
+- Linux：要在未登录时也运行需自己执行 `loginctl enable-linger`（install 检测到没开会提示）；日志走 `journalctl --user`。开着 ufw 时，局域网设备访问 `--remote-port` 要先放行，比如 `sudo ufw allow from 192.168.0.0/24 to any port 7422 proto tcp`（只走中继就不用开）。
+- **服务绑定安装时的 node 路径**：单元里写的是 node 和包的绝对路径。用 mise / nvm 管理 Node 时，路径里带着具体版本号（`…/node/26.8.2/…`）；换了 Node 版本、旧目录被删后服务就起不来，要用新版本重新 `npm i -g pinomad`，再跑一次 `pinomad service install …`。`pinomad upgrade` 只升 pinomad，装回原来的前缀，不受影响。
+- 服务模式下**回环端口也用 HTTP 提供构建好的 Web 客户端**。npm 安装时 `pinomad link` 总是指向宿主自己提供的 Web；源码检出里按顺序探测：正在跑的 vite 开发服务器（5199）优先，否则宿主提供 Web 的端口，都没有则仍是 5199。开发时 `bun run start` + vite 照旧。
 - 服务在跑时 `bun run start` 会因为目录锁拿不到而失败（同一数据目录只有一个宿主）；开发时用另一个 `--data-dir`，或先 `uninstall`。
 
 Windows 不在支持范围；其他平台跑 `service` 会直接报错退出。
@@ -173,3 +206,17 @@ bun run typecheck
 bun run test    # vitest + Playwright，首次跑前先 bunx playwright install chromium
 bun run build
 ```
+
+## 发布（ADR-0016）
+
+推 `v*` tag 触发 `.github/workflows/release.yml`，三个 job：`verify` 跑 typecheck / test / build、打包、`npm pack`、装包冒烟；`macos`（macos-15）签名 + 公证出 arm64 的 dmg/zip，挂镜像验证签名和公证票据，再跑一遍 `desktop:e2e`；`publish` 先把两者做成 **draft** GitHub Release（`PiNomad <version>`，自动生成 release notes，预发布 tag 打 `--prerelease`），上传 dmg / zip / blockmap / `latest-mac.yml` / `SHA256SUMS.txt`，然后 `npm publish`，全成了才解除 draft。`latest-mac.yml` 就是桌面端自动更新的更新源。带 `-` 的预发布 tag（`v0.2.0-beta.1`）发到 `next` 且不是 latest release，正式版发到 `latest`。发布用 npm trusted publishing（OIDC），仓库里没有 npm token。
+
+macOS 签名和公证需要这些仓库 secrets：`MAC_CSC_LINK`（开发者证书的 base64 .p12）、`MAC_CSC_KEY_PASSWORD`（p12 密码）、`APPLE_API_KEY`（App Store Connect 的 .p8 内容）、`APPLE_API_KEY_ID`、`APPLE_API_ISSUER`、`APPLE_TEAM_ID`。`workflow_dispatch` 手动触发也跑完整签名公证（版本号 `0.0.0-dryrun`），只是不会走 `publish` job，方便干跑验证发布链。
+
+```sh
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+- 手动发布（流水线不可用时）：`bun run build && bun run package -- --version <v>`，再在 `apps/cli/out` 里 `npm publish`。终端里的 npm 要先 `npm login`（`npm whoami` 能报出用户名）；没登录时 npm 回的是 `404 Not Found` 而不是 401，容易误判成包名问题。
+- 发布后几分钟内 registry 可能还没处理完（新包还会先出现一个 `0.0.0-stage` 占位版本）；这期间查过的机器缓存了旧元数据，安装报 `ETARGET` / "No matching version" 时加 `--prefer-online`。

package/dist/{chunk-jew71ysz.js → chunk-5712fvyp.js}

@@ -2,10 +2,10 @@
 import {
   main,
   restartService
-} from "./chunk-928atme2.js";
-import"./chunk-v7yf5752.js";
-import"./chunk-y73t2jmc.js";
-import"./chunk-wgn3cx5q.js";
+} from "./chunk-d9q0dz8s.js";
+import"./chunk-rkfdsacq.js";
+import"./chunk-5h97zxag.js";
+import"./chunk-h35fermn.js";
 import"./chunk-cjfmfyjb.js";
 import"./chunk-df32avw6.js";
 export {

package/dist/{chunk-y73t2jmc.js → chunk-5h97zxag.js}

@@ -1,9 +1,10 @@
 import {
-  PROTOCOL_VERSION,
+  INVALID_FRAME_CLOSE_CODE,
+  PROTOCOL,
   UNAUTHORIZED_CLOSE_CODE,
   conversationStream,
   docStream
-} from "./chunk-wgn3cx5q.js";
+} from "./chunk-h35fermn.js";
 
 // packages/protocol/src/remote-durable.ts
 import { applyImmutable } from "@earendil-works/chord/delta";
@@ -125,13 +126,19 @@ class UnauthorizedError extends Error {
 }
 
 class ProtocolMismatchError extends Error {
-  host;
-  client;
-  constructor(host, client) {
-    super(`Host protocol mismatch: host speaks ${host}, this client speaks ${client}`);
+  hostMajor;
+  clientMajor;
+  hostVersion;
+  direction;
+  constructor(hostMajor, clientMajor, hostVersion) {
+    const direction = hostMajor > clientMajor ? "client-older" : "host-older";
+    super(direction === "client-older" ? `Client out of date: the host speaks protocol major ${hostMajor}, this client speaks ${clientMajor}` : `Host out of date: this client speaks protocol major ${clientMajor}, the host speaks ${hostMajor}`);
     this.name = "ProtocolMismatchError";
-    this.host = host;
-    this.client = client;
+    this.hostMajor = hostMajor;
+    this.clientMajor = clientMajor;
+    if (hostVersion !== undefined)
+      this.hostVersion = hostVersion;
+    this.direction = direction;
   }
 }
 
@@ -141,6 +148,7 @@ class RemoteClient {
   #listeners = new Set;
   #values = new Map;
   #wanted = new Set(["conversations", "index", "devices", "mcp"]);
+  #fresh = new Set;
   #docs = [];
   #toolPresentations = {};
   #snapshotWaiters = new Map;
@@ -149,6 +157,7 @@ class RemoteClient {
   #connection;
   #state;
   #current;
+  #side;
   #nextCall = 1;
   #nextNotice = 1;
   #attempt = 0;
@@ -192,10 +201,16 @@ class RemoteClient {
       return;
     if (code === UNAUTHORIZED_CLOSE_CODE) {
       this.#closed = true;
-      this.#update({ connection: "closed" });
+      this.#update({ connection: "closed", unauthorized: true });
       this.#notice("error", new UnauthorizedError().message);
       return;
     }
+    if (code === INVALID_FRAME_CLOSE_CODE) {
+      this.#closed = true;
+      this.#update({ connection: "closed" });
+      this.#notice("error", `The host rejected a malformed frame from this client${reason === undefined ? "" : `: ${reason}`}`);
+      return;
+    }
     this.#update({ connection: "reconnecting" });
     const { min, max } = this.#options.reconnectDelayMs ?? { min: 200, max: 2000 };
     const delay = Math.min(max, min * 2 ** this.#attempt++);
@@ -208,15 +223,27 @@ class RemoteClient {
     this.#connection?.send(JSON.stringify(frame));
   }
   #receive(frame) {
+    if (frame === null || typeof frame !== "object")
+      return;
     switch (frame.type) {
       case "hello": {
-        if (frame.protocol !== PROTOCOL_VERSION) {
-          const mismatch = new ProtocolMismatchError(frame.protocol, PROTOCOL_VERSION);
+        const announced = frame.protocol;
+        const hostMajor = typeof announced === "number" ? announced : announced !== null && typeof announced === "object" ? announced.major : undefined;
+        if (hostMajor !== PROTOCOL.major) {
+          const mismatch = new ProtocolMismatchError(typeof hostMajor === "number" ? hostMajor : Number.NaN, PROTOCOL.major, frame.hostVersion);
           this.#closed = true;
           if (this.#state === undefined) {
             this.#rejectReady(mismatch);
           } else {
-            this.#update({ connection: "outdated" });
+            this.#update({
+              connection: "outdated",
+              protocolMismatch: {
+                hostMajor: mismatch.hostMajor,
+                clientMajor: mismatch.clientMajor,
+                ...mismatch.hostVersion === undefined ? {} : { hostVersion: mismatch.hostVersion },
+                direction: mismatch.direction
+              }
+            });
             this.#notice("error", mismatch.message);
           }
           this.#connection?.close();
@@ -225,9 +252,13 @@ class RemoteClient {
         this.#attempt = 0;
         this.#docs = frame.docs;
         this.#toolPresentations = frame.toolPresentations;
+        this.#fresh.clear();
         if (this.#current !== undefined)
           for (const stream of this.#conversationStreams(this.#current))
             this.#wanted.add(stream);
+        if (this.#side !== undefined)
+          for (const stream of this.#conversationStreams(this.#side))
+            this.#wanted.add(stream);
         for (const stream of this.#wanted)
           this.#send({ type: "subscribe", stream });
         if (this.#state !== undefined) {
@@ -246,6 +277,7 @@ class RemoteClient {
         if (!this.#wanted.has(frame.stream))
           return;
         this.#values.set(frame.stream, frame.value);
+        this.#fresh.add(frame.stream);
         this.#refresh();
         for (const waiter of this.#snapshotWaiters.get(frame.stream)?.splice(0) ?? [])
           waiter.resolve();
@@ -259,6 +291,7 @@ class RemoteClient {
       case "ended":
         this.#wanted.delete(frame.stream);
         this.#values.delete(frame.stream);
+        this.#fresh.delete(frame.stream);
         for (const waiter of this.#snapshotWaiters.get(frame.stream)?.splice(0) ?? []) {
           waiter.reject(new Error(`Stream ${frame.stream} ended: ${frame.reason}`));
         }
@@ -306,26 +339,66 @@ class RemoteClient {
   #conversationStreams(id) {
     return [conversationStream(id), ...this.#docs.map((doc) => docStream(doc.kind, id))];
   }
+  async#acquire(id) {
+    const missing = this.#conversationStreams(id).filter((stream) => !this.#wanted.has(stream));
+    const stale = this.#conversationStreams(id).filter((stream) => this.#wanted.has(stream) && !this.#fresh.has(stream));
+    const shown = Promise.all([...missing, ...stale].map((stream) => this.#snapshot(stream)));
+    for (const stream of missing) {
+      this.#wanted.add(stream);
+      this.#send({ type: "subscribe", stream });
+    }
+    await shown;
+  }
+  #release(id, other) {
+    const keep = new Set(other === undefined ? [] : this.#conversationStreams(other));
+    for (const stream of this.#conversationStreams(id)) {
+      if (keep.has(stream))
+        continue;
+      this.#wanted.delete(stream);
+      this.#values.delete(stream);
+      this.#fresh.delete(stream);
+      this.#send({ type: "unsubscribe", stream });
+    }
+  }
+  #descendsFrom(id, ancestor) {
+    const summaries = this.#values.get("conversations") ?? [];
+    const parentOf = new Map(summaries.map((summary) => [summary.id, summary.parent]));
+    let cursor = id;
+    for (let depth = 0;cursor !== undefined && depth < 8; depth++) {
+      if (cursor === ancestor)
+        return true;
+      cursor = parentOf.get(cursor);
+    }
+    return false;
+  }
+  #docsOf(id) {
+    return this.#docs.flatMap((doc) => {
+      const stream = docStream(doc.kind, id);
+      return this.#values.has(stream) ? [{ kind: doc.kind, presentation: doc.presentation, value: this.#values.get(stream) }] : [];
+    });
+  }
   #refresh() {
     if (this.#state === undefined)
       return;
     const current = this.#current;
+    const side = this.#side;
     const conversation = current === undefined ? undefined : this.#values.get(conversationStream(current));
     const summaries = this.#values.get("conversations") ?? [];
     const index = this.#values.get("index") ?? { projects: [], conversations: [] };
     const devices = this.#values.get("devices")?.devices ?? [];
     const tasks = this.#wanted.has("tasks") ? this.#values.get("tasks") : undefined;
-    const docs = current === undefined ? [] : this.#docs.flatMap((doc) => {
-      const stream = docStream(doc.kind, current);
-      return this.#values.has(stream) ? [{ kind: doc.kind, presentation: doc.presentation, value: this.#values.get(stream) }] : [];
-    });
     this.#update({
       conversation,
       organized: organize(index, summaries),
       home: current === undefined ? undefined : homeOf(index, summaries, current),
       checkout: current === undefined ? undefined : checkoutOf(index, summaries, current),
       tasks,
-      docs,
+      docs: current === undefined ? [] : this.#docsOf(current),
+      side: side === undefined ? undefined : {
+        id: side,
+        conversation: this.#values.get(conversationStream(side)),
+        docs: this.#docsOf(side)
+      },
       devices,
       mcp: this.#values.get("mcp") ?? null
     });
@@ -396,15 +469,18 @@ class RemoteClient {
         await this.#call("archive", { conversationId: id, archived });
         if (archived && id === this.#current)
           this.#unshow();
+        if (archived && this.#side !== undefined && this.#descendsFrom(this.#side, id))
+          await this.#showSide(undefined);
       }),
-      submit: (text, whenBusy) => this.#command(() => this.#call("submit", { conversationId: conversationId(), text, whenBusy, requestId: newRequestId() })),
+      submit: (text, whenBusy, target) => this.#command(() => this.#call("submit", { conversationId: target ?? conversationId(), text, whenBusy, requestId: newRequestId() })),
       compact: (instructions) => this.#command(() => this.#call("compact", { conversationId: conversationId(), ...instructions === undefined ? {} : { instructions } })),
-      abort: () => {
-        if (this.#current === undefined) {
+      abort: (target) => {
+        const targetConversation = target ?? this.#current;
+        if (targetConversation === undefined) {
           this.#notice("error", "No conversation selected");
           return Promise.resolve();
         }
-        return this.#call("abort", { conversationId: conversationId() }).then(() => {}, (error) => this.#notice("error", error instanceof Error ? error.message : String(error)));
+        return this.#call("abort", { conversationId: targetConversation }).then(() => {}, (error) => this.#notice("error", error instanceof Error ? error.message : String(error)));
       },
       setThinkingLevel: (level) => this.#command(() => this.#call("setThinkingLevel", { conversationId: conversationId(), level })),
       setModel: (model) => this.#command(() => this.#call("setModel", { conversationId: conversationId(), model })),
@@ -421,16 +497,20 @@ class RemoteClient {
         await shown;
       }),
       switchConversation: (id) => this.#command(() => this.#switch(id)),
-      fork: (entryId, prompt, removeTools) => this.#command(async () => {
+      showSide: (id) => this.#command(() => this.#showSide(id)),
+      fork: (entryId, prompt, removeTools, options) => this.#command(async () => {
         const { conversationId: forked } = await this.#call("fork", {
           conversationId: conversationId(),
           entryId,
           ...removeTools === undefined ? {} : { removeTools }
         });
-        await this.#switch(forked);
+        if (options?.show === "side")
+          await this.#showSide(forked);
+        else
+          await this.#switch(forked);
         await this.#call("submit", { conversationId: forked, text: prompt, whenBusy: "followUp", requestId: newRequestId() });
       }),
-      answer: (kind, requestId, answers) => this.#command(() => this.#call("answer", { conversationId: conversationId(), kind, requestId, answers })),
+      answer: (kind, requestId, answers, target) => this.#command(() => this.#call("answer", { conversationId: target ?? conversationId(), kind, requestId, answers })),
       changes: () => {
         const call = this.#commands.then(() => this.#call("changes", { conversationId: conversationId() }));
         this.#commands = call.then(() => {}, () => {});
@@ -448,19 +528,10 @@ class RemoteClient {
     const previous = this.#current;
     if (id === previous)
       return;
-    const next = this.#conversationStreams(id);
-    for (const stream of next)
-      this.#wanted.add(stream);
-    const shown = Promise.all(next.map((stream) => this.#snapshot(stream)));
-    for (const stream of next)
-      this.#send({ type: "subscribe", stream });
-    await shown;
+    await this.#acquire(id);
     this.#current = id;
-    for (const stream of previous === undefined ? [] : this.#conversationStreams(previous)) {
-      this.#wanted.delete(stream);
-      this.#values.delete(stream);
-      this.#send({ type: "unsubscribe", stream });
-    }
+    if (previous !== undefined)
+      this.#release(previous, this.#side);
     this.#refresh();
   }
   #unshow() {
@@ -468,11 +539,18 @@ class RemoteClient {
     if (previous === undefined)
       return;
     this.#current = undefined;
-    for (const stream of this.#conversationStreams(previous)) {
-      this.#wanted.delete(stream);
-      this.#values.delete(stream);
-      this.#send({ type: "unsubscribe", stream });
-    }
+    this.#release(previous, this.#side);
+    this.#refresh();
+  }
+  async#showSide(id) {
+    const previous = this.#side;
+    if (id === previous)
+      return;
+    if (id !== undefined)
+      await this.#acquire(id);
+    this.#side = id;
+    if (previous !== undefined)
+      this.#release(previous, this.#current);
     this.#refresh();
   }
   #close() {

package/dist/{chunk-928atme2.js → chunk-d9q0dz8s.js}

@@ -2,10 +2,10 @@ import {
   commandHint,
   hostEntry,
   packagedVersion
-} from "./chunk-v7yf5752.js";
+} from "./chunk-rkfdsacq.js";
 import {
   connectRemoteDurable
-} from "./chunk-y73t2jmc.js";
+} from "./chunk-5h97zxag.js";
 import {
   DEFAULT_DATA_DIR,
   hostAddress