feat(v2): manage session families across worktrees

.github/workflows/pr-build.yml

@@ -213,6 +213,7 @@ jobs:
           packages/ui/src/stores/session-generation-recovery.test.ts
           packages/ui/src/stores/session-pagination.test.ts
           packages/ui/src/stores/session-pending-state.test.ts
+          packages/ui/src/stores/session-tree.test.ts
           packages/ui/src/stores/session-previews.test.ts
           packages/ui/src/stores/workspace-load-readiness.test.ts
           packages/ui/src/types/session.test.ts
@@ -242,6 +243,8 @@ jobs:
           packages/ui/src/stores/session-request-authority.test.ts
           packages/ui/src/stores/session-send-lifecycle.test.ts
           packages/ui/src/stores/session-status.test.ts
+          packages/ui/src/stores/worktree-ready.test.ts
+          packages/ui/src/stores/worktrees-delete.test.ts
 
       - name: Test server
         run: node --import tsx --test "packages/server/src/**/*.test.ts"

AGENTS.md

@@ -56,8 +56,8 @@ Behavior for agents:
 - Run them with `npm run test:browser --workspace @codenomad/ui` after `npx playwright install chromium`. `CODENOMAD_BROWSER_PATH` optionally selects an existing Chromium executable; it does not target the installed application or user sessions.
 
 ## V2 Runtime Launch
-- Launch the release executable from PowerShell with the dedicated WebView2 profile, CDP port, Rust backtraces, and Node source maps described in `MIGRATION_V2.md`.
-- Stop the running CodeNomad instance before rebuilding the same release path, then relaunch it from the independent OpenCode TUI.
+- Enable **Developer Mode** from the session tab bar and fully restart CodeNomad once; do not configure a fixed CDP port or a manual WebView2 profile.
+- Rebuild Electron before calling `codenomad.act({ action: "restart" })`. For Windows Tauri, stop and relaunch the release executable only when the linker cannot replace it; never stop the shared OpenCode daemon.
 
 ## Commit Message Guidelines
 - When creating commits, use detailed commit messages: a concise conventional-style subject followed by body paragraphs that explain the user-visible behavior change, the implementation approach, important edge cases or platform considerations, and the validation or test coverage added.

CONTRIBUTING.md

@@ -112,7 +112,7 @@ Then open a pull request on GitHub targeting the `dev` branch.
 ### OpenCode V2 Boundaries
 
 - Server and UI follow `@opencode-ai/client@beta`. Refresh the client lock before API audits or release validation. The runtime CLI is managed independently, and startup must not reject an otherwise compatible service solely for a different version string. Review current OpenCode documentation, installed declarations, and proxy/API parity whenever the client contract changes.
-- Upgrade references: [OpenCode releases](https://github.com/anomalyco/opencode/releases), [OpenCode documentation](https://opencode.ai/docs/), and `node_modules/@opencode-ai/client/dist/promise/`.
+- Upgrade references: the published npm `beta` tags, [OpenCode V2 documentation](https://opencode.ai/v2/docs/), [OpenCode V2 HTTP API](https://opencode.ai/v2/docs/api/), and `node_modules/@opencode-ai/client/dist/promise/`. Public GitHub releases may still describe V1 and are not a V2 compatibility authority.
 - `packages/server/src/workspaces/opencode-service.ts` uses the selected host or WSL CLI's official `service status`, `service start`, and `service get password` lifecycle to connect to one externally owned global daemon. CodeNomad owns no private port, database, registration, or daemon PID and never stops the daemon on backend shutdown.
 - WSL requires Windows localhost forwarding and runs the Linux CLI lifecycle inside the distribution; never inspect or signal Linux PIDs from Windows.
 - OpenCode owns the global daemon's standard state and database. Configured allowed environment variables apply only when CodeNomad starts a missing daemon; an existing daemon is unchanged, and legacy `OPENCODE_DB`/`XDG_STATE_HOME` ownership settings are ignored.

DESKTOP_V2_COMPARISON.md

@@ -4,9 +4,9 @@
 
 This review compares:
 
-- CodeNomad `DEV-v2` at `dea20996` (2026-09-03).
-- Official OpenCode Desktop V2 from `anomalyco/opencode` branch `upstream/beta` at `eb1ac54d73` (2026-08-25).
-- CodeNomad declares `@opencode-ai/client@beta`; UI and server resolve `beta-18999`, while the runtime CLI version is managed independently.
+- CodeNomad `DEV-v2` at `44a1816b` (2026-09-04), merged with the worktree-session changes reviewed here.
+- Published OpenCode V2 `beta-18999` at `887f319769c55718e3e64f64b32c9aafb13c5d66`, including an operation-by-operation and generated-declaration comparison from `beta-18684` at `106629aa118086be7def6123241a9bf056ba77b6`.
+- CodeNomad declares `@opencode-ai/client@beta`; UI and server resolve `beta-18999`, the independently managed runtime CLI reports `beta-18999`, and the official V2 documentation is rooted at <https://opencode.ai/v2/docs/>.
 
 The official reference is `packages/desktop` for the Electron host, `packages/app` for the shared UI, and the V2 client, protocol, schema, server, and core packages for wire behavior. Older `v2`, `opencode-2-0`, and intermediate `desktop-v2-*` branches are historical, not the current Desktop V2 reference.
 
@@ -18,6 +18,17 @@ CodeNomad implements the important V2 architecture rather than emulating the V1
 
 The comparison and subsequent beta-contract audit found concrete CodeNomad defects in pagination, navigation, model projection, inbox delivery, follow behavior, background control, location selectors, and proxy route coverage. Those defects are fixed in the commits accompanying this document. The remaining differences are scoped workflow defects, release hardening, or optional Desktop features. None requires restoring V1 code or replacing native V2 cursors.
 
+## Published Beta 18684 to 18999 Impact
+
+The generated OpenAPI surface grows from 136 to 140 operations. It adds only `plugin.awaitActivation`, `plugin.check`, `plugin.update`, and `rpc.call`; it removes nothing and does not change the session, message, location, worktree, Shell, or PTY operation sets. Session pages retain the `{ data, cursor }` envelope, exclusive opaque cursors, and native ordering semantics.
+
+- **Pagination:** all session continuations now send only the returned cursor. This includes UI inventory, worktree family transactions, proxy validation, and server-side Yolo restoration. Repeated-cursor and bounded-inventory checks remain where destructive worktree operations require a complete snapshot.
+- **Locations:** OpenCode's unavailable-location change is official-app recovery UI, not an API change. CodeNomad preserves unavailable restored tabs and native session locations but does not weaken logical-workspace ownership to recover a session whose source is outside every owned root/worktree.
+- **Moves:** session-aware execution and chained-move continuation improve the native server. CodeNomad still refuses worktree family moves while any member is active, serializes the project transaction, rechecks before each move, verifies the complete inventory, and rolls back on failure.
+- **Events:** the client now isolates cancellation among consumers of its lazy shared stream, which CodeNomad inherits through `OpenCode.make()`. Typed `rpc.*` events require a native location and are routed only to owning logical workspaces. Raw `/api/event`, generic RPC calls, and plugin lifecycle mutations remain blocked by the workspace proxy.
+- **PTY and Shell:** socket detach, post-exit drain, and fast-output fixes are runtime-only. CodeNomad inherits them without changing its HTTP proxy or introducing an embedded terminal; owned running PTYs, persistent PTYs, and Shells continue to block unsafe worktree deletion.
+- **Generated types:** the new plugin state shape is safe because plugin IDs are narrowed before projection. The config update-policy rename is unused, provider/model canonical fields are additive, and native `SessionInfo.location`, `workspaceID`, and durable JSON `metadata` remain preserved.
+
 ## Closed Findings
 
 ### Message history pagination