版本与发布流程：主仓库 .github/workflows/release.yml（v<version> tag 触发）+ packaging/npm/README.md。所有 GitHub Releases 是发布物的权威来源；本页保留各版本 release notes 的镜像。

发版规则（2026-10-13 起，#88）：发版时机和版本号由 Haisu 决定并执行；PR 不改任何版本号；agent 只做到开 PR，只有在某一次发版被逐次明确授权时才能操作。下文 v0.3.5 记录的 "release-per-merge / 每个 PR 自带版本 bump"（PR #78）是当时的流程，已被取代，原文保留。

当前状态（2026-10-17）：npm latest 与最新 tag 为 v0.3.9；@zuohaisu/viva 与两个 darwin 平台包均为 0.3.9，latest 指向 0.3.9；GitHub Release v0.3.9 含 arm64 / Intel 两个 tarball 及各自 sha256，release workflow run 38936463533 成功。v0.3.9 tag 打在版本 PR #170 的合并提交 ab7feac 上，因此不含其后才合入 main 的 PR #171。

上一次状态（2026-10-16，原文保留）：npm latest 与最新 tag 为 v0.3.8；三包 0.3.8 均已在 registry，latest 指向 0.3.8；npm 平台包里的二进制与 GitHub Release tarball 逐字节一致；macOS arm64 / Intel 冒烟测试由 release workflow 执行（viva --version → 0.3.8）。v0.3.7（2026-10-14）已发布，但本页没有补写它的条目，以 GitHub Release 为准。

更早状态（2026-10-07，原文保留）：npm latest 与最新 tag 为 v0.3.6；三包 0.3.6 均已在 registry，tarball 传播完成，隔离 prefix 干净安装验收通过（viva --version → 0.3.6，arm64 平台包正确解析）。版本号 0.3.1 跳过未发布（npm/GitHub 均无 0.3.1，准备内容随 v0.3.2 发布，见下）。Release notes 的 canonical 位置是本页——自 2026-10-06 起不再在 repo docs/releases/ 维护。

Provenance — Haisu 2026-10-16 在 #156 对应任务上逐次授权发版 0.3.9（任务评论 01a14553）。v0.3.9 tag 打在版本 PR #170 的合并提交 ab7feac 上；release workflow run 38936463533 成功，GitHub Release 于 2026-10-16T17:03:46Z 创建。本页条目为 2026-10-17 追补，依据 #169 / #170 的 diff、release workflow 与 registry 实查。

0.3.8 人工审核不通过：启动后没有 terminal、右键菜单点不动、多处 UI 与 herdr 不同。修复方式是把 herdr 0.9.5 与 viva 并排注入同样的键鼠输入，并读 herdr 源码取参考行为。

• 启动时当前 tab 没有 terminal，就在启动目录开 $SHELL 并进入 terminal 模式；之前只有 overview 占位。
• 缺失的 VIVA_HOME 在打开 server.log 前创建；之前不先 viva init 会报 io error: No such file or directory。
• 新建 tab / 分屏后新 pane 接管键盘（之前输入的键丢失）；新 tab 的第一个终端替换 overview 占位，不再先占半屏（server 的 split_into 用同一规则）。
• 右键菜单：左键也能激活菜单项（与 herdr 一致，之前只有右键）；命中行与标签同行（之前高一行）；菜单高度容得下所有项（之前 zoom 被截断）；菜单外点击只关闭菜单，不再穿透到 pane；右键作用于指针下的 pane；清理过期命中区。
• overlay（help、settings、goto、pane prompt、terminal picker、menu）吞掉鼠标点击，不再穿透到下面的 pane。
• tab 栏改成带编号，聚焦 tab 用强调色，并多了可点的 +。
• 普通 shell pane 不再显示 terminal term-<uuid>；只有用户命名或 agent 徽章才显示标题。
• 状态消息移到底部栏并在 5 秒后消失；之前被侧边栏截断且永不清除。
• 侧边栏收起或变窄后不再在 pane 上留下点击目标。
• server 还没见过的 tab 做 tree op 不再提示 tree update failed：tree op 失败且本地布局为脏时，客户端改为发布布局，发布成功则吞掉该错误（发布也失败才显示）。

版本 PR #170 只改 crates/viva/Cargo.toml 与 Cargo.lock 到 0.3.9，不含其他改动。

• 排除项沿用 0.3.8：插件市场和 herdr.dev、远端 manifest 热更新、Linux logind、Windows、复制 herdr 源码、用屏幕状态关闭任务、第二套命名 session。屏幕规则状态同 0.3.8（Claude Code / Codex 的 done 与 idle 仍为 unknown）。
• PR #171（把 Claude Code / Codex / Pi 会话采集为成员经验）在 tag 之后才合入 main，不在 0.3.9 内。
• 未验证：本机（Linux）没有 Linux 二进制，未在本机跑 viva --version；真实远端 SSH 上的多机器走查；macOS PTY/TUI 人工走查（依赖 release workflow 的 macOS 冒烟测试，以及一次 macOS arm64 干净安装核验）。
• 已知差异：运行 viva 仍不把 cwd 变成 workspace，侧边栏显示 no workspace / local，herdr 显示 alpha · master。这是 workspace 模型差异，本次未改；产品决策待定。

Provenance — Haisu 2026-10-16 在 #156 对应任务上逐次授权本次发版并点名 0.3.8。封板 PR #168（merge 8ecabe1），独立 QA 通过后由 Haisu 合并；v0.3.8 tag 打在合并提交上，main CI 与 release workflow 均通过。能力对照表：主仓库 docs/validation/0.3.8-herdr-capability-matrix.md。

• herdr 对齐的键位和模式（PR #137、#148、#160）：默认 keys.* 与 herdr 0.9.3 --default-config 逐条一致，prefix 为 ctrl+b；有 terminal / prefix / navigate 模式，另有 copy 和 resize；支持 Kitty keyboard 和 OSC 52。旧 workbench 单键（o p d f D h、单独的 q、Ctrl+方向键、Ctrl+]）已经删除；detach 改为 prefix+q。
• server 持有 scene / tab / pane 树（PR #138）：多个客户端共享同一棵树；同一个 tab 上后一次尺寸改动生效，不同 tab 互不影响；侧边栏宽度和正在看的 tab 留在各自客户端。
• agent 徽章与 integration resume（PR #147）：受控报告优先于屏幕识别；viva integration install 为 claude、codex 等写 hook，保存 resume 指针。
• 本地插件（PR #158）：viva plugin install|uninstall|list，只接受本地目录。
• 多机器（PR #159）：viva machine … 和 viva --machine <id>，通过 SSH 聚合多台机器。
• server 重启恢复（PR #164）：server 进程退出后再启动，恢复布局、cwd 和焦点；有效 resume 才拉起 agent，否则在原目录开 shell；不复活旧进程。
• 同期合入的其他改动：原生记忆 FTS / HRR（PR #132、#135、#166）、团队技能版本与回滚（PR #161）、成员技能集（PR #162）、并发首次打开的 WAL 修复（PR #129）。

• resize 模式在默认配置下没有键能用；现在用 h/j/k/l 或方向键，调整包含当前 pane 的那一层分隔。
• 每开一个新 tab 都提示 tree update failed；现在先把新 tab 存到 server，再发分屏。
• server 被杀后 viva 拒绝启动；现在会启动新 server 并认领残留的 socket。
• 改名框把 Ctrl+U 当成字母输入；Ctrl+方向键 还会移动列表选中行。

• Claude Code 和 Codex 的屏幕规则：识别、working、blocked 已用真实屏幕核对；done 和 idle 在真实屏幕上没有固定句子，规则已清空，读数保持 unknown。其他 13 个 CLI 的屏幕规则没有核对，状态以受控报告为准。
• 多机器没有在真实 SSH 主机上走查；本次没有在 macOS 上手动走查（release workflow 在 macOS 上做了冒烟测试）。
• 排除项：插件市场和 herdr.dev、远端 manifest 热更新、Linux logind、Windows、复制 herdr 源码、用屏幕状态关闭任务、第二套命名 session。

Provenance — tag 与 GitHub Release 由发布会话于 2026-10-06 20:32 UTC 创建；Wiki 条目为 2026-10-07 追补（该会话未写本页），依据 PR #82/#83 的 diff 与提交说明。

• Workbench: a moved drag must not arm the double-click reset (PR #82) — every divider grab armed the double-click detector, so grab → nudge → release → re-grab within 500 ms at the same cell reset the split to 50/50 instead of dragging (reads exactly as "the divider won't move"). A drag that actually moved the layout now disarms the double-click on release.
• CI: rustc 1.99 clippy deprecation (PR #83) — the GitHub runner fleet moved to rustc 1.99.0, which deprecates AtomicUsize::fetch_update (renamed try_update; the new name is only stable since 1.95, so the rename would break older local toolchains). The call site in tui/workbench/polling.rs now uses an explicit compare_exchange CAS loop: identical satisfied-or-refuse semantics for the 64 KiB input-queue byte budget, compiles on every Rust version, MSRV stays 1.85.

• #82 is a view-layer interaction fix (client pane tree + persisted workbench layout); Viva data, terminals and execution state untouched. #83 is a like-for-like CAS rewrite with no semantic change.
• Local channel = "stable" toolchains resolved different rustc versions than CI during the fleet rollover (1.95/1.98 vs 1.99), which is why local clippy stayed green while CI failed; the fix deliberately targets the portable intersection.

Provenance — tag 与 GitHub Release 于 2026-10-06 18:32 UTC 创建；Wiki 条目为 2026-10-07 追补，依据 PR #78/#79/#80。

• Terminal scene views, resilient server client, byte-boundary-safe live handoff (PR #80) — terminal scenes render real PTY output with edge-triggered polling; the server client reconnects before the idle timeout instead of going silent; live handoff now carries unfinished escape/UTF-8 byte sequences split across a transfer in a new pending_hex manifest field and replays them at the new host (previously lost or rendered as literal text).
• Process: one-step release flow (PR #78, charter) — release-per-merge with no batching: each delivery PR carries its own version bump, merges are the release trigger, and docs-only merges consume no version and ride the next release's notes (this entry is the first ride-along).
• Process: docs-only fast path for local checks (PR #79, charter) — docs-only diffs validate locally with git diff --check + git status --short and delegate the rest to required CI.

• The binary content of 0.3.5 is PR #80; #78/#79 are charter text only and consume no version number.

• Workbench mouse interaction (herdr parity, PR #73) — the interaction layer behind the 0.3.3 static visuals:
  • Pane dividers are draggable: grab a divider (±1-cell tolerance), drag to resize; the divider follows the pointer without jumping (grab offset), clamps into the never-zero 10–90% band, lights up while dragging, and a double-click resets the split to 50/50. A drag is cancelled instead of resizing the wrong split if the pane topology changes under it.
  • Click a pane to focus it; clicking away from a terminal releases keyboard-forwarding mode so typed keys never keep flowing to the previously focused terminal.
  • The sidebar's right edge is draggable (18–36 columns, herdr's bounds) and double-click resets it to 26; the chosen width persists in the saved workbench layout (older layouts keep the default).
• Layout hit model as pure functions in tui/layout.rs (splits/set_ratio_at_path/ratio_for_divider), asserted cell-for-cell against the drawn chrome.

• The workbench run loop discarded every mouse event while mouse capture was enabled — the terminal delivered them and viva threw them away, stealing even the terminal's native text selection. Mouse events are now routed into the app; scroll wheels and other buttons are not wired yet.

• View-layer only: drags mutate the client pane tree and the persisted workbench layout row; Viva data, terminals and execution state are untouched.
• Mouse events are consumed by the shell, not forwarded into terminal panes (children with mouse reporting keep working; forwarding, wheel scrolling, in-terminal text selection and sidebar row click-select are the next interaction slices).

Provenance — 2026-10-06 从 repo docs/releases/v0.3.3.md（PR #71 随附）迁入本页，原文未删改。

• viva update completes the upgrade by itself: after installing, a running resident server is restarted through the S3 live handoff — the freshly installed entry point takes over as the host and its terminals survive. No more manual viva server-restart after every upgrade; reconnect the TUI when the output asks for it.
• With no server running, the update says so and the next viva start simply uses the new version. A socket nobody answers is left untouched with an honest note — the next start claims it with a recovery record, as before.
• A failed handover never fails the install (which already succeeded): the old generation keeps serving and the output names viva server-restart as the retry.
• New flag --no-restart restores the old split (install now, restart explicitly later).

• The restart step reuses the existing grant-gated handoff protocol; the update command itself remains user-only (member/worker contexts are still rejected) and never opens VIVA_HOME data or touches member/task/history records.
• The resumed host is spawned detached (own process group, output in server.log), exactly like viva server-restart spawns it today; the only difference is the entry point: the freshly installed wrapper or binary instead of the updating process's old executable.
• npm upload acceptance or a green workflow alone is still not proof of a usable release — verify viva --version after installing.

Provenance — 由 repo 内 docs/releases/v0.3.1.md（PR #67 的发布准备）与 v0.3.2 GitHub Release 说明合并而成。版本号 0.3.1 跳过未发布：0.3.1 的准备内容随 v0.3.2 一起发布（tag 载有 crate 0.3.2；npm 无 0.3.1）。

0.3.1 was prepared in PR #67 but was not published to npm; the release shipped as v0.3.2. Includes the changes merged into main after v0.3.0:

• Workbench chrome: a herdr-style workbench with a sidebar, command palette, shared pane borders, and a client-version indicator in the status bar (PR #61).
• Canonical documentation moved to this Wiki (PR #68) — documentation-only, no binary change.

• Pane resizing now checks the minimum size of the pane being kept, and surfaces rollback failures instead of hiding them.
• Workbench QA fixes improve viewport handling, diff overlays, and split guards.
• PTY setup: retain the controlling-terminal fd through fork/exec, report TIOCSCTTY failures, use atomic CLOEXEC fd duplication and RAII cleanup (PR #70).

The Rust package, lockfile, GitHub release tag, npm wrapper, and macOS platform packages are versioned together. The existing tag-triggered release workflow publishes the platform packages before the wrapper; no old release tag or package was overwritten.

Migrated from docs/releases/v0.3.0.md @ 871a00a。

The V15 workbench-deepening series, grown from a day of real herdr use (V15-Workbench-Deepening), plus the QA-hardening fixes it went through.

• File browser (V15-1): f in the workbench opens a worktree's file inventory (porcelain statuses, changed files first). Enter views a modified file as a diff against the worktree's recorded base SHA, or bounded content for clean/untracked files; the binary verdict is honest; paths are validated (relative, no ..); e opens the file with the system opener.
• PR cleanup (V15-2): worktree rows show PR state via gh (60s cache; unknown stays unknown). D twice — naming the exact path — releases and removes a worktree whose PR is MERGED, re-checked live and audited; closed/unknown states refuse.
• Agent handoff (V15-3): h hands a worktree to another agent. The brief carries the task goal, the branch and the departing agent's last controlled summary, delivered into the new terminal; the departing terminal keeps running; the handoff lands in task history and the audit log.
• Auto-sync (V15-4): viva sync auto-pull on|off (default OFF, persists) and viva sync status. When on, active projects' MAIN checkouts fast-forward (--ff-only, clean tree only, 5-minute TTL, off-thread, pause-gated, audited); task worktrees are fetched, never merged; rows show ahead/behind vs origin; failures degrade to a status note.
• Rate-limit recovery (V15-5): agents report rate_limited with a required RFC3339 reset_at; the resident server sweeps due plans once a second and prompts the terminal to continue. Plans persist across restarts; overdue ones expire with a record instead of executing blindly. viva recovery list | schedule --terminal <id> --at <rfc3339> [--task <id>] | cancel --id <n>.

The series went through six QA rounds; notable fixes: char-boundary-safe diffs, single-flight sync and fetch-gate splitting, owner-only toggles, cleanup lock split, protocol timeouts carried through, and a terminal reader that survives EINTR/EAGAIN (the CI high-volume flake root cause).

• All socket-mutating V15 requests sit behind the existing grant gate (ADR-0007); every outcome lands in the append-only event log.
• Auto-sync never merges task worktrees and never runs on dirty trees; member-initiated dispatch and stopping still require a live grant.
• gh-derived PR state is cached for 60s and unknown when gh is absent; cleanup refuses on unknown state.
• No schema migration: existing VIVA_HOME state opens as-is.

Migrated from docs/releases/v0.2.1.md @ 871a00a。设计记录见 CLI-Update-Validation。

• viva update: upgrade this installation to a newer stable version.
• viva update --check: check the installation's release channel without replacing the executable or installing packages.
• Global npm installations upgrade through npm at their original prefix, keeping the wrapper and platform package in sync.
• Standalone macOS installations use official GitHub Release artifacts: bounded HTTPS download, SHA-256 verification, version probe and atomic executable replacement. Failed native validation preserves the old binary; equal/older versions are not installed.

Older binaries do not have viva update; install v0.2.1 once first:

npm install --global @zuohaisu/[email protected]
viva --version
viva update --check

For standalone installations, download viva-macos-arm64.tar.gz (Apple Silicon) or viva-macos-intel.tar.gz (Intel) and its SHA-256 checksum from this release.

• Updates do not open/migrate VIVA_HOME, alter member/task/history records, stop agents or restart servers. Activate the installed server explicitly with viva server-restart, then reconnect the TUI.
• Native updates replace only the executable; refresh bundled Pi extension sources separately if needed. Checksums provide integrity, not an independent publisher signature.
• Local npm installs update with npm install @zuohaisu/viva@latest inside their project. npm owns its installation/failure behavior; native atomic replacement guarantees do not apply to npm package installation.
• No sudo, automatic background upgrades or overwrite of Cargo build outputs.

更早版本：v0.2.0、v0.1.x（notes 以 GitHub Release 页为准）。