@tt-a1i/hive 1.7.0 → 2.0.2

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable user-facing changes will be documented in this file.
 
+## 2.0.2 - 2026-06-10
+
+Windows Codex terminal scrolling fix.
+
+- Fixes Codex terminal scrolling for Windows installs whose saved launch
+  command still points at `node.exe ...\@openai\codex\bin\codex.js`, so Hive
+  now applies the Codex-specific wheel/PageUp/PageDown input profile instead of
+  treating the session like a plain shell.
+
+## 2.0.1 - 2026-06-09
+
+Team memory, worker-card polish, and release-channel cleanup.
+
+- Adds ambient team memory so Hive can retain useful workspace context and
+  surface it again when you need the team to remember prior decisions,
+  constraints, or project notes.
+- Refines the Memory and Workflows drawers with better desktop/mobile layouts,
+  clearer tabs, and a search field that stays out of the way on wide screens.
+- Redesigns worker cards for stronger scanability: clearer status treatment,
+  higher contrast, cleaner role text, and an in-place rename flow instead of a
+  separate edit dialog.
+- Clarifies pending dispatch status so queued or waiting worker activity is
+  easier to understand while the Orchestrator is coordinating work.
+- Publishes the current remote/mobile build under the original official
+  `@tt-a1i/hive` package name.
+
+## 2.0.0 - 2026-06-07
+
+Remote access, mobile control, and the production gateway.
+
+- Adds optional Remote access so you can open your running Hive from a phone
+  browser. Remote is off by default; when enabled, the phone connects through
+  an end-to-end encrypted tunnel and gets the same authority as the local
+  desktop browser.
+- Ships the Cloudflare Workers gateway stack for identity and routing: GitHub
+  and Google sign-in, Durable Object relay, D1-backed daemon/device records,
+  rate limiting, version-pinned mobile bundles, and deployment runbooks for
+  self-hosting or pointing Hive at an existing gateway.
+- Adds the desktop trust-root pairing flow. The desktop creates a short-lived
+  pairing code, the phone enters it after selecting the machine, both sides
+  show a 6-digit SAS code, and the device is stored only after desktop
+  confirmation.
+- Adds remote device management: list paired devices, revoke them from
+  Settings or the CLI, drop live sessions immediately from the Settings panel,
+  and review an audit trail of remote requests and denials.
+- Adds `hive remote login`, `status`, `logout`, `devices`, and `revoke` for
+  linking the machine to a gateway account and managing paired devices from
+  the host itself.
+- Adds the mobile Hive shell: sign-in/connect screens, machine list, bottom
+  navigation, workspace switching, full-screen team/task panels, and
+  remote-aware reconnect and update prompts.
+- Makes phone terminals writable through the terminal itself. Worker terminals
+  can be opened full-screen, mobile focus mode hides surrounding chrome while
+  you work, and terminal touch scrolling now tracks the finger more closely
+  with smoother normal-buffer glide and faster alternate-screen movement.
+- Preserves local-first behavior: local `127.0.0.1` Hive keeps working without
+  a gateway, remote access is path-whitelisted to Hive's own `/api/*` and
+  `/ws/*`, and paired phones cannot approve new devices or turn Remote access
+  back on after it has been disabled.
+
 ## 1.7.0 - 2026-06-05
 
 Hermes joins the roster.

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 **Hive is a browser-native workbench where a team of agents works together — one orchestrates, the rest execute, all on your laptop.** The orchestrator
-is a real `claude` / `codex` / `opencode` / `gemini` / `hermes` process — not you, and
+is a real `agy` / `claude` / `codex` / `opencode` / `gemini` / `hermes` / `qwen` process — not you, and
 not a script — and so are the workers it dispatches to. Every agent runs as
 a real PTY on your machine, talks through a small `team` protocol that Hive
 injects into each agent's shell, and shares a markdown task graph at
@@ -76,6 +76,12 @@ npm install -g @tt-a1i/hive
 hive
 ```
 
+If npm prints `npm warn allow-scripts` or `prebuild-install@7.1.3 deprecated`
+during install, first check whether the command ends with `added ... packages`.
+Those warnings usually come from npm's install-script review plus native
+binary setup for `node-pty`, `better-sqlite3`, and `esbuild`; they do not mean
+Hive failed to install. The troubleshooting section below breaks them down.
+
 Open the printed local URL, usually `http://127.0.0.1:3000/`. Use
 `hive --port 4010` when you need a specific local port.
 
@@ -172,11 +178,15 @@ Three details matter:
 
 | Preset | Command expected on `PATH` | Default bypass mode | Session resume |
 | --- | --- | --- | --- |
+| Antigravity CLI | `agy` | `--dangerously-skip-permissions` | `--conversation <session_id>` |
 | Claude Code | `claude` | `--dangerously-skip-permissions`, `--permission-mode=bypassPermissions` | `--resume <session_id>` |
 | Codex | `codex` | `--dangerously-bypass-approvals-and-sandbox` | `resume <session_id>` |
 | OpenCode | `opencode` | Config-driven in `~/.config/opencode/opencode.json` | `--session <session_id>` |
 | Gemini | `gemini` | `--yolo` | `--resume <session_id>` |
 | Hermes | `hermes` | `--yolo` | `--resume <session_id>` |
+| Qwen Code | `qwen` | `--approval-mode yolo` | `--resume <session_id>` |
+| Cursor CLI | `cursor` | `--force` | Session id capture not wired yet |
+| Grok Build | `grok` | `--always-approve` | Session id capture not wired yet |
 | Custom | Any executable | User configured | User configured |
 
 Hive does not install these CLIs for you. Install and authenticate them in the
@@ -199,11 +209,46 @@ same shell environment you use to start Hive.
 - `.hive/tasks.md` editor with external-file conflict handling.
 - Background PTY preservation and best-effort native session resume.
 - A What's New dialog after upgrades with curated release highlights.
-- Local SQLite metadata under `~/.config/hive` by default, or `$HIVE_DATA_DIR`
-  when set.
-
-Hive does not provide sandboxing, multi-user auth, cloud hosting, or any
-bundled agent model. It coordinates the CLIs you already run locally.
+- Local SQLite metadata under `%APPDATA%\hive` on Windows and `~/.config/hive`
+  on macOS / Linux by default, or `$HIVE_DATA_DIR` when set.
+
+Hive does not provide sandboxing, multi-user auth, or any bundled agent
+model. It coordinates the CLIs you already run locally.
+
+## Remote Access (optional, off by default)
+
+If you want to reach your running Hive from your phone while you're away,
+turn on the optional **Remote access** feature. Once enabled, a phone browser
+logs in at a gateway with GitHub or Google, pairs once with the desktop, and
+then reaches the **full** Hive web UI over an end-to-end encrypted tunnel — a
+paired phone is a trusted device with the **same authority** as the local
+browser.
+
+A few things to be clear about:
+
+- **Off by default.** With it off there are no outbound connections and
+  nothing listening — behavior is exactly what it is today.
+- **Requires a gateway.** The tunnel is relayed through a gateway (your
+  local daemon dials out to it — no open ports, no router changes). The
+  gateway URL is configurable: **self-host** a Cloudflare Workers gateway,
+  or point at one that's already deployed. There is **no turnkey hosted
+  service** — you stand the gateway up yourself.
+- **Data and execution stay local.** The gateway only does identity (OAuth
+  login) and routing; it never sees plaintext, only relays ciphertext. If the
+  gateway is down, everything on local `127.0.0.1` keeps working.
+- **End-to-end encrypted.** Every data frame between the phone and the daemon
+  is end-to-end encrypted; the gateway sees only ciphertext and routing
+  headers. The honest caveat: the phone's crypto code is served by the gateway
+  (the classic limit of web-delivered E2E, like Proton or WhatsApp Web),
+  mitigated by SRI, versioned bundles, and PWA caching that forms a TOFU
+  baseline. We don't claim "secure even if the gateway is compromised."
+- **Trust root stays on the desktop.** Pairing a new device must be confirmed
+  in person at the computer (a desktop dialog plus a 6-digit SAS check); a
+  paired phone can't approve new devices on its own. Devices can be revoked at
+  any time.
+
+See [docs/remote-access.md](docs/remote-access.md) for the full enable,
+login (`hive remote login`), pairing, revoke, and self-host-gateway walkthrough.
 
 ## Platform Support
 
@@ -211,7 +256,7 @@ bundled agent model. It coordinates the CLIs you already run locally.
 | --- | --- | --- |
 | macOS | Tier 1 | Main development and release verification target. |
 | Linux | Tier 1 | CI verified. Native folder picking expects `zenity`; manual path entry works without it. |
-| Windows | Tier 2 | CI runs a Windows test subset and a packaged-install smoke. Folder picking uses Windows PowerShell and the package includes `team.cmd`. Treat as best-effort — full Windows verification before each release is manual. |
+| Windows | Tier 2 | CI runs a Windows test subset and a packaged-install smoke. Workspace selection uses Hive's in-browser server filesystem picker by default, starting at "This PC" so other drives are visible; the package includes `team.cmd`. Treat as best-effort — full Windows verification before each release is manual. |
 
 All platforms require Node.js 22+. Hive depends on native packages
 (`node-pty` and `better-sqlite3`), so native install tooling may be required
@@ -241,7 +286,7 @@ Read [SECURITY.md](SECURITY.md) before using Hive with sensitive repositories.
 
 | Data | Location |
 | --- | --- |
-| Runtime metadata | `~/.config/hive` or `$HIVE_DATA_DIR` |
+| Runtime metadata | Windows: `%APPDATA%\hive`; macOS / Linux: `~/.config/hive`; or `$HIVE_DATA_DIR` |
 | Workspace tasks | `<workspace>/.hive/tasks.md` |
 | Internal `team` command | Packaged under `dist/bin/`, injected into PTYs |
 | Web UI assets | Served by the runtime from the packaged `web/dist` build |
@@ -267,6 +312,19 @@ Hive depends on `node-pty` and `better-sqlite3`, which use native binaries. Use
 Node.js 22+, keep your package manager cache clean, and verify your platform
 build tools are available.
 
+When install succeeds but npm prints warnings, read them by source:
+
+| warning | Source | What to do |
+| --- | --- | --- |
+| `allow-scripts @tt-a1i/hive` | Hive's postinstall fixes executable bits for packaged native / PTY helpers. | Safe to ignore after a successful install. |
+| `allow-scripts better-sqlite3` | SQLite native bindings download a prebuilt binary, then fall back to local build. | Safe to ignore after success; check build tools only if install fails. |
+| `allow-scripts node-pty` | The terminal PTY binding prepares platform binaries. | Safe to ignore after success; check build tools only if install fails. |
+| `allow-scripts esbuild` | esbuild verifies/selects the binary package for the current platform. | Safe to ignore after a successful install. |
+
+This is npm 11's install-script review notice. The current npm release still
+treats it as advisory; future npm versions may require explicit approval. To
+review the list yourself, run `npm approve-scripts --allow-scripts-pending`.
+
 If npm prints a deprecated warning for `prebuild-install@7.1.3`, it is safe to
 ignore. The warning comes from `better-sqlite3`'s native binary download chain;
 it is an upstream installer maintenance notice, not a Hive install failure, and
@@ -276,10 +334,14 @@ does not affect runtime behavior.
 
 Install `zenity`, or paste the workspace path manually.
 
-**Folder picker does not open on Windows**
+**Folder picker on Windows**
 
-Verify Windows PowerShell is available as `powershell.exe`, or paste the
-workspace path manually.
+Hive uses the in-browser server filesystem browser by default on Windows
+instead of launching the PowerShell native folder picker. This avoids the
+system dialog getting hidden behind the browser window. The browser starts at
+"This PC" and lists accessible drives, so `C:\`, `D:\`, and other drives are
+reachable. If the target directory is not visible in the browser list, expand
+"Advanced: paste path" and enter the absolute path directly.
 
 **Tasks file conflict banner appears**
 

package/README.md

@@ -8,7 +8,7 @@
   <img src="./assets/hive-hero.png" alt="Hive 本机多 agent 协作工作台" />
 </p>
 
-**Hive 是浏览器里的 Agent 协作工作台——一群 Agent 在你本机各自开工，一个当 Orchestrator 派活、归总进展，其余各司其职。** Orchestrator 本身就是一个真实的 `claude` / `codex` / `opencode` / `gemini` / `hermes` 进程——不是你、也不是脚本——它派单的 Worker 同样是真 CLI agent。所有 agent 都是本机真实的 PTY 进程，通过 Hive 注入到 shell 里的小型 `team` 协议互相通信，共享 `<workspace>/.hive/tasks.md` 这份 markdown 任务图。
+**Hive 是浏览器里的 Agent 协作工作台——一群 Agent 在你本机各自开工，一个当 Orchestrator 派活、归总进展，其余各司其职。** Orchestrator 本身就是一个真实的 `agy` / `claude` / `codex` / `opencode` / `gemini` / `hermes` / `qwen` 进程——不是你、也不是脚本——它派单的 Worker 同样是真 CLI agent。所有 agent 都是本机真实的 PTY 进程，通过 Hive 注入到 shell 里的小型 `team` 协议互相通信，共享 `<workspace>/.hive/tasks.md` 这份 markdown 任务图。
 
 写代码、做调研、起草文档、做翻译——凡是能拆给一群人协作的脑力活，都可以让一群 Agent 合伙干。
 
@@ -58,6 +58,8 @@ npm install -g @tt-a1i/hive
 hive
 ```
 
+安装时如果看到 `npm warn allow-scripts` 或 `prebuild-install@7.1.3 deprecated`，先看最后是否显示 `added ... packages`。这些 warning 多数来自 npm 对安装脚本的安全审查，以及 `node-pty` / `better-sqlite3` / `esbuild` 这类原生依赖的二进制安装链路；不代表 Hive 启动失败。下面的故障排查里有逐项解释。
+
 打开终端打印出来的本机地址，通常是 `http://127.0.0.1:3000/`。如果你想指定端口，可以用 `hive --port 4010`。
 
 升级到最新版本：
@@ -122,11 +124,15 @@ Workspace 任务图：
 
 | 预设 | `PATH` 上的命令 | 默认 bypass 模式 | 会话恢复 |
 | --- | --- | --- | --- |
+| Antigravity CLI | `agy` | `--dangerously-skip-permissions` | `--conversation <session_id>` |
 | Claude Code | `claude` | `--dangerously-skip-permissions`、`--permission-mode=bypassPermissions` | `--resume <session_id>` |
 | Codex | `codex` | `--dangerously-bypass-approvals-and-sandbox` | `resume <session_id>` |
 | OpenCode | `opencode` | 由 `~/.config/opencode/opencode.json` 配置 | `--session <session_id>` |
 | Gemini | `gemini` | `--yolo` | `--resume <session_id>` |
 | Hermes | `hermes` | `--yolo` | `--resume <session_id>` |
+| Qwen Code | `qwen` | `--approval-mode yolo` | `--resume <session_id>` |
+| Cursor CLI | `cursor` | `--force` | 暂未自动捕获 session id |
+| Grok Build | `grok` | `--always-approve` | 暂未自动捕获 session id |
 | 自定义 | 任意可执行文件 | 自己配 | 自己配 |
 
 Hive 不替你安装这些 CLI。请在启动 Hive 的同一个 shell 环境里先装好、登录好。
@@ -142,9 +148,23 @@ Hive 不替你安装这些 CLI。请在启动 Hive 的同一个 shell 环境里
 - `.hive/tasks.md` 编辑器，带外部文件冲突处理。
 - PTY 后台保留 + 尽力使用各 CLI 原生 session 恢复。
 - 升级后的 What's New 弹窗，用简短 release highlights 告诉你新版改了什么。
-- 元数据存在本机 SQLite，默认在 `~/.config/hive`，或者通过 `$HIVE_DATA_DIR` 指定。
+- 元数据存在本机 SQLite，Windows 默认在 `%APPDATA%\hive`，macOS / Linux 默认在 `~/.config/hive`，也可以通过 `$HIVE_DATA_DIR` 指定。
+
+Hive **不**提供 sandbox 隔离、多用户认证，也不自带任何 agent 模型。它只负责调度你已经在用的本机 CLI。
+
+## 远程访问（可选，默认关闭）
+
+如果想在外面用手机查看、操作正在本机跑着的 Hive，可以开启可选的 **Remote access**。开启后，手机浏览器在网关上用 GitHub / Google 登录、跟桌面完成一次配对，就能通过端到端加密隧道访问**完整**的 Hive Web UI——已配对的手机是与本地浏览器**等权**的受信任设备。
+
+需要清楚的几点：
 
-Hive **不**提供 sandbox 隔离、多用户认证、云端托管，也不自带任何 agent 模型。它只负责调度你已经在用的本机 CLI。
+- **默认关闭**。不开就没有任何出站连接、没有监听，行为跟现在一模一样。
+- **需要一个网关**。隧道要经过一个网关中转（你本机的 daemon 主动出站连它，不开端口、不动路由器）。网关地址可配置：可以 **自己 self-host** 一个 Cloudflare Workers 网关，也可以接一个已部署的网关。Hive **没有**现成的一键托管服务——这一步要你自己搭。
+- **数据和执行永远在本机**。网关只做身份（OAuth 登录）和路由，看不到明文——它只转发密文。网关挂了，本机 `127.0.0.1` 上的一切照常。
+- **端到端加密**。手机 ↔ daemon 之间所有数据帧端到端加密，网关只见密文和路由头。诚实的边界：手机端的加密代码由网关分发（web 端 E2E 的经典局限，跟 Proton / WhatsApp Web 同类），缓解手段是 SRI + 版本化 bundle + PWA 缓存形成 TOFU。我们不宣传"网关被攻破也绝对安全"。
+- **信任根在桌面**。新设备配对必须人在电脑前确认（桌面弹窗 + 6 位 SAS 短码校验）；已配对手机不能凭自己批准新设备。设备随时可吊销。
+
+完整的开启、登录（`hive remote login`）、配对、吊销和 self-host 网关步骤见 [docs/remote-access.md](docs/remote-access.md)。
 
 ## 平台支持
 
@@ -167,7 +187,7 @@ Hive 是本机开发工具，**不是**托管服务。
 
 | 数据 | 位置 |
 | --- | --- |
-| Runtime 元数据 | `~/.config/hive` 或 `$HIVE_DATA_DIR` |
+| Runtime 元数据 | Windows: `%APPDATA%\hive`；macOS / Linux: `~/.config/hive`；或 `$HIVE_DATA_DIR` |
 | Workspace 任务图 | `<workspace>/.hive/tasks.md` |
 | 内部 `team` 命令 | 包内 `dist/bin/`，通过 PATH 注入 PTY |
 | Web UI 资源 | 由 runtime 从包内 `web/dist` 直接服务 |
@@ -190,15 +210,26 @@ hive --port 4020
 
 Hive 依赖 `node-pty` 和 `better-sqlite3`，它们用原生二进制。确认 Node.js 22+，清干净 package manager 缓存，并准备好你平台的构建工具（macOS Xcode CLI、Linux build-essential + python3、Windows VS Build Tools）。
 
+安装成功但看到 npm warning 时，可以按来源判断：
+
+| warning | 来源 | 处理 |
+| --- | --- | --- |
+| `allow-scripts @tt-a1i/hive` | Hive 的 postinstall 会修正打包后的 native/PTY helper 权限。 | 安装成功后可忽略。 |
+| `allow-scripts better-sqlite3` | SQLite 原生绑定需要下载预编译二进制，失败时会本机构建。 | 安装成功后可忽略；失败再检查构建工具链。 |
+| `allow-scripts node-pty` | 终端 PTY 原生绑定需要准备平台二进制。 | 安装成功后可忽略；失败再检查构建工具链。 |
+| `allow-scripts esbuild` | esbuild 会校验/选择当前平台的二进制包。 | 安装成功后可忽略。 |
+
+这是 npm 11 的安装脚本审查提示。当前 npm 版本仍是提示性质，未来可能要求用户显式批准这些脚本。你想审查时可以运行 `npm approve-scripts --allow-scripts-pending` 查看待审列表。
+
 安装时如果看到 `prebuild-install@7.1.3` 的 deprecated warning，可以忽略。它来自 `better-sqlite3` 的原生二进制下载链路，只是上游安装器维护状态提示，不代表 Hive 安装失败，也不会影响运行。
 
 **Linux 上目录选择器不弹**
 
 装 `zenity`，或者直接在对话框里粘路径。
 
-**Windows 上目录选择器不弹**
+**Windows 上目录选择器**
 
-确认 `powershell.exe` 在 `PATH` 上，或者直接粘路径。
+Windows 版默认使用浏览器内的服务器文件系统浏览器来添加 Workspace，不再弹 PowerShell 原生目录选择器。浏览器会从“此电脑”开始列出可访问盘符，所以可以进入 `C:\`、`D:\` 等其他盘；如果目标目录不在浏览器列表里，可以展开“高级：粘贴路径”直接输入绝对路径。
 
 **Tasks 文件冲突 banner 出现**
 
@@ -271,9 +302,11 @@ Hive 目前处于 alpha 阶段，核心流程已可用。当前重点是继续
 - **Claude Code 的 [Auto Dream](https://claudefa.st/blog/guide/mechanics/auto-dream)（俗称"做梦"）** 走 **离线批处理** 路线：`/dream` 触发（或 24h 自动），Claude 在云端把 JSONL 会话归并去重抽模式，产出新版本 memory 库给你审查再采纳——像人类的 REM 睡眠，**清醒 / 睡眠二相**。
 - **Hermes Agent** 反过来走 **嵌入式 / 在场** 路线：不睡，每 N 轮对话后台 fork 一个 sub-agent review，结果直接落进本地的 **多层记忆**——`MEMORY.md`（事实/规则）·`USER.md`（用户画像）·SQLite + FTS5（情景检索）·Honcho（第三人称表征）·`skills/`（程序性记忆）——而且 agent 允许边走边改自己的 skill 文件，记忆和能力是一回事。
 
-但 **这些都是单 agent 内部的记忆**。Hive 是多 agent 协作工作台，下一步要做的事是把它们打通：让整支团队 **共享一座长时记忆库**——Worker A 今天踩的坑，明天 Orchestrator 派给 Worker B 时能自动调来当上下文。
+但 **这些都是单 agent 内部的记忆**。Hive 是多 agent 协作工作台，正在把它们打通：让整支团队 **共享一座长时记忆库**——Worker A 今天踩的坑，明天 Orchestrator 派给 Worker B 时能自动调来当上下文。
+
+第一阶段先走本地优先：Hive 用 SQLite 保存协作历史和显式团队记忆，支持 `team recall` / `team memory`、派单和恢复时的自动注入、`<workspace>/.hive/memory.md` 单向导出，以及离线 Dream 整理。Dream 会按 workspace 空闲和增量阈值批处理协议消息，自动应用去重/改写/归档/新增，并保留 diff 报告和整次 run 的回滚入口。
 
-底层我们计划接 **[EverOS](https://github.com/EverMind-AI/EverOS)**（[EverMind](https://evermind.ai/) 出品的开源长时记忆 OS，目前在 LoCoMo / LongMemEval / HaluMem 三个记忆 benchmark 上 SOTA）当跨 agent 的记忆后端。它的四层架构（Agentic / Memory / Index / API+MCP）跟 Hive 的多 PTY 协作模型很搭：每个 agent 各跑各的 CLI session，团队级的事实和模式凝在 EverOS，Orchestrator 派单时一并喂给 worker。
+下一阶段再接 **[EverOS](https://github.com/EverMind-AI/EverOS)**（[EverMind](https://evermind.ai/) 出品的开源长时记忆 OS，目前在 LoCoMo / LongMemEval / HaluMem 三个记忆 benchmark 上 SOTA）这类外部 provider。EverOS 的四层架构（Agentic / Memory / Index / API+MCP）跟 Hive 的多 PTY 协作模型很搭：每个 agent 各跑各的 CLI session，团队级的事实和模式凝在 provider，Orchestrator 派单时一并喂给 worker。
 
 进度跟踪：[#6](https://github.com/tt-a1i/hive/issues/6)——想看进度或提建议，在 issue 留 +1。
 

package/dist/src/cli/hive-remote.d.ts

@@ -0,0 +1,46 @@
+import { DEFAULT_GATEWAY_URL, REMOTE_DAEMON_ID_KEY, REMOTE_DAEMON_TOKEN_KEY, REMOTE_ENABLED_KEY, REMOTE_GATEWAY_URL_KEY } from '../server/remote-config-keys.js';
+import { type RemoteDeviceRecord } from '../server/remote-device-store.js';
+export { DEFAULT_GATEWAY_URL, REMOTE_DAEMON_ID_KEY, REMOTE_DAEMON_TOKEN_KEY, REMOTE_ENABLED_KEY, REMOTE_GATEWAY_URL_KEY, };
+export declare const HIVE_REMOTE_USAGE: string;
+export interface RemoteConfigStore {
+    get(key: string): {
+        value: string | null;
+    } | undefined;
+    set(key: string, value: string | null): void;
+}
+export interface RemoteDeviceListStore {
+    list(includeRevoked?: boolean): RemoteDeviceRecord[];
+    /** Idempotent; false if the device is unknown or already revoked. */
+    revoke(deviceId: string, now?: number): boolean;
+}
+export interface DaemonCodeResponse {
+    code: string;
+    expiresAt: number;
+    pollIntervalMs: number;
+}
+export interface DaemonTokenResponse {
+    daemonId: string;
+    daemonToken: string;
+}
+export interface GatewayClient {
+    requestCode(gatewayUrl: string): Promise<DaemonCodeResponse>;
+    exchangeToken(gatewayUrl: string, code: string, name?: string): Promise<DaemonTokenResponse | null>;
+}
+export declare const defaultGatewayClient: GatewayClient;
+export interface RunHiveRemoteOptions {
+    /** Inject a fake gateway client (tests). */
+    client?: GatewayClient;
+    /** Inject an in-memory config store (tests); defaults to the runtime DB. */
+    config?: RemoteConfigStore;
+    /** Inject a device store (tests); defaults to the runtime DB's device store. */
+    deviceStore?: RemoteDeviceListStore;
+    /** Inject a clock for poll-timeout tests. */
+    now?: () => number;
+    /** Inject the poll delay so tests don't actually wait. */
+    sleep?: (ms: number) => Promise<void>;
+    /** stdout sink (defaults to console.log). */
+    log?: (line: string) => void;
+    /** stderr sink (defaults to console.error). */
+    error?: (line: string) => void;
+}
+export declare const runHiveRemoteCommand: (argv: string[], options?: RunHiveRemoteOptions) => Promise<number>;

package/dist/src/cli/hive-remote.js

@@ -0,0 +1,257 @@
+import { createAppStateStore } from '../server/app-state-store.js';
+import { getMachineName } from '../server/machine-name.js';
+import { DEFAULT_GATEWAY_URL, REMOTE_DAEMON_ID_KEY, REMOTE_DAEMON_TOKEN_KEY, REMOTE_ENABLED_KEY, REMOTE_GATEWAY_URL_KEY, } from '../server/remote-config-keys.js';
+import { createRemoteDeviceStore } from '../server/remote-device-store.js';
+import { openRuntimeDatabase } from '../server/runtime-database.js';
+import { resolveDataDir } from './hive.js';
+// Re-export so existing callers (and the CLI tests) can keep importing the keys
+// from here; the canonical definitions live in remote-config-keys.ts, shared
+// with the daemon-side tunnel so the on-disk contract can't drift between sides.
+export { DEFAULT_GATEWAY_URL, REMOTE_DAEMON_ID_KEY, REMOTE_DAEMON_TOKEN_KEY, REMOTE_ENABLED_KEY, REMOTE_GATEWAY_URL_KEY, };
+// `hive remote` — manage the daemon's connection to the remote-access gateway.
+//
+//   hive remote login [--gateway <url>]   bind this machine to a Hive account
+//   hive remote status                    show connection + enabled state
+//   hive remote logout                    forget the gateway token, disable remote
+//   hive remote devices                   list paired phones/devices
+//   hive remote revoke <deviceId>         revoke a paired device
+//
+// login drives the gateway's daemon-binding flow (gateway/src/daemon.ts):
+//   POST /daemon/code  -> { code, expiresAt, pollIntervalMs }   (print URL + code)
+//   ... human approves in their logged-in browser at /daemon/approve?code=... ...
+//   POST /daemon/token -> 401 not_approved (keep polling) | 200 { daemonId, daemonToken }
+//
+// The token is account-scoped and is local RCE on this machine, so it lands in
+// app_state (the same SQLite the daemon reads) and is NEVER printed back.
+// `enabled` defaults OFF for the whole subsystem; a successful login flips it on.
+// Off == zero behavior change: no token, no outbound tunnel (see remote-tunnel).
+export const HIVE_REMOTE_USAGE = [
+    'Usage:',
+    '  hive remote login [--gateway <url>]   Link this machine to your Hive account.',
+    '  hive remote status                    Show remote-access connection state.',
+    '  hive remote logout                    Forget the gateway token and disable remote.',
+    '  hive remote devices                   List paired devices.',
+    '  hive remote revoke <deviceId>         Revoke a paired device.',
+    '',
+    'Remote access lets you reach this Hive from a phone through the gateway over',
+    'an end-to-end encrypted tunnel. It is OFF until you log in, and `logout`',
+    'turns it off again. The gateway only relays ciphertext — it never sees your',
+    'data or terminals.',
+    '',
+    'Options:',
+    `  --gateway <url>   Gateway base URL (default: ${DEFAULT_GATEWAY_URL}).`,
+    '  -h, --help        Print this help.',
+].join('\n');
+const openConfigStore = () => {
+    const db = openRuntimeDatabase(resolveDataDir());
+    return { store: createAppStateStore(db), close: () => db.close() };
+};
+const readConfig = (store, key) => store.get(key)?.value ?? null;
+const openDeviceStore = () => {
+    const db = openRuntimeDatabase(resolveDataDir());
+    return { store: createRemoteDeviceStore(db), close: () => db.close() };
+};
+const trimSlash = (url) => url.replace(/\/+$/, '');
+const postJson = async (url, body, token) => {
+    const headers = { 'content-type': 'application/json' };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    return fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+};
+// Default client: real fetch against the gateway. The contracts mirror
+// gateway/src/daemon.ts exactly (field names, the 401 not_approved poll signal).
+export const defaultGatewayClient = {
+    async requestCode(gatewayUrl) {
+        const res = await postJson(`${trimSlash(gatewayUrl)}/daemon/code`, {});
+        if (!res.ok)
+            throw new Error(`gateway /daemon/code failed: ${res.status}`);
+        const body = (await res.json());
+        if (typeof body.code !== 'string' || typeof body.expiresAt !== 'number') {
+            throw new Error('gateway /daemon/code returned an unexpected response');
+        }
+        return {
+            code: body.code,
+            expiresAt: body.expiresAt,
+            pollIntervalMs: typeof body.pollIntervalMs === 'number' ? body.pollIntervalMs : 2000,
+        };
+    },
+    async exchangeToken(gatewayUrl, code, name) {
+        const payload = { code };
+        if (name)
+            payload.name = name;
+        const res = await postJson(`${trimSlash(gatewayUrl)}/daemon/token`, payload);
+        // 401 == not yet approved (or expired). 429 == the gateway throttled this poll. Both mean "keep
+        // polling until the code's expiresAt" — a transient 429 mid-wait must NOT kill the login (the
+        // gateway sizes the /daemon/token budget for the poll cadence, but we stay robust if it ever
+        // trips). Any other non-2xx is a hard failure.
+        if (res.status === 401 || res.status === 429)
+            return null;
+        if (!res.ok)
+            throw new Error(`gateway /daemon/token failed: ${res.status}`);
+        const body = (await res.json());
+        if (typeof body.daemonId !== 'string' || typeof body.daemonToken !== 'string') {
+            throw new Error('gateway /daemon/token returned an unexpected response');
+        }
+        return { daemonId: body.daemonId, daemonToken: body.daemonToken };
+    },
+};
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const readGatewayFlag = (argv) => {
+    const index = argv.indexOf('--gateway');
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) {
+        throw new Error('Usage: hive remote login [--gateway <url>]');
+    }
+    return value;
+};
+const approveUrl = (gatewayUrl, code) => `${trimSlash(gatewayUrl)}/daemon/approve?code=${encodeURIComponent(code)}`;
+const runLogin = async (argv, store, client, now, sleep, log) => {
+    const gatewayUrl = readGatewayFlag(argv) ?? readConfig(store, REMOTE_GATEWAY_URL_KEY) ?? DEFAULT_GATEWAY_URL;
+    const { code, expiresAt, pollIntervalMs } = await client.requestCode(gatewayUrl);
+    log('To link this machine, open the approval page in a browser where you are');
+    log('logged in to your Hive account, and confirm the code matches:');
+    log('');
+    log(`  ${approveUrl(gatewayUrl, code)}`);
+    log('');
+    log(`  Code: ${code}`);
+    log('');
+    log('Waiting for approval…');
+    const machineName = getMachineName() ?? undefined;
+    // Poll until the human approves or the code expires. The gateway hands back
+    // null (HTTP 401) until approval flips the code; we never bail early.
+    for (;;) {
+        const token = await client.exchangeToken(gatewayUrl, code, machineName);
+        if (token) {
+            store.set(REMOTE_GATEWAY_URL_KEY, gatewayUrl);
+            store.set(REMOTE_DAEMON_ID_KEY, token.daemonId);
+            store.set(REMOTE_DAEMON_TOKEN_KEY, token.daemonToken);
+            store.set(REMOTE_ENABLED_KEY, 'true');
+            log('');
+            log('This machine is linked. Remote access is now enabled.');
+            log('Restart the Hive runtime (or it will connect on next start) to bring');
+            log('the tunnel online. Pair a phone from Settings → Remote access.');
+            return 0;
+        }
+        if (now() >= expiresAt) {
+            log('');
+            log('The login code expired before it was approved. Run `hive remote login` again.');
+            return 1;
+        }
+        await sleep(pollIntervalMs);
+    }
+};
+const runStatus = (store, log) => {
+    const enabled = readConfig(store, REMOTE_ENABLED_KEY) === 'true';
+    const gatewayUrl = readConfig(store, REMOTE_GATEWAY_URL_KEY);
+    const daemonId = readConfig(store, REMOTE_DAEMON_ID_KEY);
+    const loggedIn = readConfig(store, REMOTE_DAEMON_TOKEN_KEY) !== null;
+    log(`Remote access: ${enabled ? 'enabled' : 'disabled'}`);
+    log(`Logged in: ${loggedIn ? 'yes' : 'no'}`);
+    // The token is secret and is intentionally never printed.
+    if (gatewayUrl)
+        log(`Gateway: ${gatewayUrl}`);
+    if (daemonId)
+        log(`Machine id: ${daemonId}`);
+    if (!loggedIn)
+        log('Run `hive remote login` to link this machine.');
+    return 0;
+};
+const runLogout = (store, log) => {
+    const wasLoggedIn = readConfig(store, REMOTE_DAEMON_TOKEN_KEY) !== null;
+    store.set(REMOTE_DAEMON_TOKEN_KEY, null);
+    store.set(REMOTE_DAEMON_ID_KEY, null);
+    store.set(REMOTE_ENABLED_KEY, 'false');
+    log(wasLoggedIn
+        ? 'Logged out. Remote access is disabled and the gateway token has been forgotten.'
+        : 'Not logged in. Remote access is disabled.');
+    return 0;
+};
+const runDevices = (store, log) => {
+    const devices = store.list(true); // include revoked so the operator sees the full roster
+    if (devices.length === 0) {
+        log('No paired devices. Pair a phone from Settings → Remote access.');
+        return 0;
+    }
+    for (const device of devices) {
+        const lastSeen = device.lastActive ? new Date(device.lastActive).toISOString() : 'never';
+        const status = device.revokedAt ? ' (revoked)' : '';
+        log(`${device.id}  ${device.name}  last active ${lastSeen}${status}`);
+    }
+    return 0;
+};
+const runRevoke = (deviceId, store, log, error) => {
+    if (!deviceId) {
+        error('Usage: hive remote revoke <deviceId>');
+        return 1;
+    }
+    const revoked = store.revoke(deviceId);
+    if (!revoked) {
+        error(`Unknown or already-revoked device: ${deviceId}`);
+        return 1;
+    }
+    // The daemon's provider reads live sessions fresh, so the device is refused on its
+    // next frame. To tear down an IN-PROGRESS session immediately, revoke from
+    // Settings → Remote access (which fires the live closed-loop disconnect).
+    log(`Revoked device ${deviceId}. It is refused on its next connection.`);
+    return 0;
+};
+export const runHiveRemoteCommand = async (argv, options = {}) => {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        const log = options.log ?? console.log;
+        log(HIVE_REMOTE_USAGE);
+        return argv.length === 0 ? 1 : 0;
+    }
+    const [subcommand, ...rest] = argv;
+    const client = options.client ?? defaultGatewayClient;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? defaultSleep;
+    const log = options.log ?? console.log;
+    const error = options.error ?? console.error;
+    // Open the config store lazily so --help / unknown subcommands don't touch
+    // the DB, and always close an owned handle.
+    // Annotated as a possibly-undefined holder so TS doesn't narrow it to `never`
+    // in the finally block (the assignment happens inside resolveStore's closure,
+    // which control-flow analysis can't see executing).
+    const owned = {};
+    const resolveStore = () => {
+        if (options.config)
+            return options.config;
+        const opened = openConfigStore();
+        owned.close = opened.close;
+        return opened.store;
+    };
+    const resolveDeviceStore = () => {
+        if (options.deviceStore)
+            return options.deviceStore;
+        const opened = openDeviceStore();
+        owned.close = opened.close;
+        return opened.store;
+    };
+    try {
+        switch (subcommand) {
+            case 'login':
+                return await runLogin(rest, resolveStore(), client, now, sleep, log);
+            case 'status':
+                return runStatus(resolveStore(), log);
+            case 'logout':
+                return runLogout(resolveStore(), log);
+            case 'devices':
+                return runDevices(resolveDeviceStore(), log);
+            case 'revoke':
+                return runRevoke(rest[0], resolveDeviceStore(), log, error);
+            default:
+                error(`Unknown remote subcommand: ${subcommand}`);
+                error(HIVE_REMOTE_USAGE);
+                return 1;
+        }
+    }
+    catch (err) {
+        error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    finally {
+        owned.close?.();
+    }
+};

package/dist/src/cli/hive-update.js

@@ -173,7 +173,12 @@ export const resolveHiveUpdateInstallArgs = (moduleUrl = import.meta.url) => {
         return [...INSTALL_COMMAND_ARGS];
     return [...INSTALL_COMMAND_ARGS, '--prefix', prefix];
 };
-const formatInstallCommand = (args) => `npm ${args.map(shellQuote).join(' ')}`;
+const windowsQuote = (value) => {
+    if (/^[-A-Za-z0-9_/:=.,@+\\]+$/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '""')}"`;
+};
+const formatInstallCommand = (args, platform = process.platform) => `npm ${args.map(platform === 'win32' ? windowsQuote : shellQuote).join(' ')}`;
 export const runHiveUpdateCommand = async (argv, options = {}) => {
     if (argv.includes('--help') || argv.includes('-h')) {
         console.log(HIVE_UPDATE_USAGE);
@@ -190,7 +195,7 @@ export const runHiveUpdateCommand = async (argv, options = {}) => {
     const run = options.runUpdate ?? defaultRunUpdate;
     const command = getNpmCommand(options.platform);
     const args = resolveHiveUpdateInstallArgs(options.moduleUrl);
-    const displayCommand = formatInstallCommand(args);
+    const displayCommand = formatInstallCommand(args, options.platform);
     console.log(`Running: ${displayCommand}`);
     const result = await run(command, args);
     if (result.spawnError) {