chore: finalize release docs and harden release flow

9 files changed, 364 insertions, 11 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 60d9479f..4d27c244 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,10 +76,13 @@ Default release flow:
 
 ```bash
 just check
-just release 0.x.y
+just release-prepare 0.x.y
+just release-publish 0.x.y
 ```
 
-`just release 0.x.y` prepares the changelog entry, bumps `Cargo.toml`, runs tests, commits, tags, and pushes. GitHub Actions builds the binaries after the tag is pushed, creates the GitHub release, uploads all four binary assets, then updates `website/latest.json` on `master` automatically.
+`just release-prepare 0.x.y` prepares the changelog entry, bumps `Cargo.toml`, updates `Cargo.lock`, refreshes `nix/package.nix` `cargoHash`, runs tests, and commits the release. `just release-publish 0.x.y` verifies the prepared clean tree, rechecks the committed `cargoHash` without patching, pushes the release commit to `origin/master` if needed, then tags and pushes the tag. `just release 0.x.y` runs both steps. GitHub Actions builds the binaries after the tag is pushed, creates the GitHub release, uploads all four binary assets, then updates `website/latest.json` on `master` automatically.
+
+If the release will change `Cargo.lock` or the package version, refresh `nix/package.nix` after the release version bump and before tagging. `just release-prepare` runs `just refresh-nix-cargo-hash`, which forces `cargoHash = lib.fakeHash`, captures the `got:` hash from Nix, writes it back to `nix/package.nix`, and reruns the Nix flake checks. A stale hash fails both the `Nix` workflow and the release workflow's `flake-check` job with a fixed-output derivation mismatch.
 
 The release workflow must publish these four assets:
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03bae097..39604731 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+### Added
+- Custom command keybindings now accept an optional `description` field to provide user-defined descriptions shown in the keybind help panel instead of the default `'custom command'` label. (#362)
+
+### Fixed
+- The OpenCode integration no longer treats `session.created` or `session.updated` plugin events as idle signals, so active sessions stay marked working until OpenCode reports `session.status` or `session.idle`. (#351)
+- New interactive panes now use login-shell startup on macOS by default so Homebrew and other login PATH setup is available, with `terminal.shell_mode = "non_login"` as an opt-out. (#350)
+- Claude Code panes no longer stay blocked after stale permission-prompt reports when the visible screen has returned to idle or working state. (#349)
+- Codex panes no longer stay working because stale `esc to interrupt` text remains above a visible idle prompt, and visible approval-review work is now preserved as working. (#352)
+- Sidebar Git status refresh now deduplicates workspaces from the same checkout and reuses cached ahead/behind results when refs have not changed, reducing idle CPU from repeated `git` polling. (#353)
+- Update prompts, toasts, and docs now distinguish installing a new binary from stopping or reattaching a running Herdr session to use it.
+- Large restored sessions no longer leave restored or newly split panes without shells after startup, and live handoff keeps PTY ownership bounded to one master fd per pane. (#357)
+- Pane shutdown no longer warns that a pane is still alive after the direct child has already exited and been reaped. (#338)
+- Closing the last pane or tab in a parent worktree workspace now shows the existing confirmation before closing the whole worktree group. (#369)
+
 ## [0.6.5] - 2026-05-29
 
 ### Added
diff --git a/README.md b/README.md
index 60887456..537377a8 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ Press `ctrl+b q` to detach the client. The server and pane processes keep runnin
 
 **Copy.** Herdr copies pane text, not the sidebar. Drag-select inside a pane, double-click a word or token, or press `prefix+[` for keyboard copy mode. In copy mode, move with `h/j/k/l`, `w/b/e`, and `{`/`}`, start selection with `v` or Space, copy with `y` or Enter, and leave with `q` or Esc. In PuTTY and some SSH terminals, hold `Shift` while dragging to use the terminal's own selection, and `Shift` + right click to paste.
 
-**Update and restore.** `herdr update` installs a new binary, but a running server keeps using the old process until it is stopped or handed off. Run `herdr server stop` for the default session, or `herdr session stop <name>` for a named session, then start Herdr again. `herdr update --handoff` is experimental and tries to move live panes, including foreground processes such as dev servers, from the old server to the new one. If `[session] resume_agents_on_restore = true` is enabled and current official integrations are installed, supported agent panes can restart from their native agent sessions after a server restart or update.
+**Update and restore.** `herdr update` installs a new binary, but a running server keeps using the old process until it is stopped or handed off. Stop the old server to use the new version. Stopping exits pane processes. Run `herdr server stop`, then run `herdr` again for the default session. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again. `herdr update --handoff` is experimental and tries to move live panes, including foreground processes such as dev servers, from the old server to the new one. If `[session] resume_agents_on_restore = true` is enabled and current official integrations are installed, supported agent panes can restart from their native agent sessions after a server restart or update.
 
 **Keybindings.** Herdr uses explicit keybinding strings. `prefix+n` means press the configured prefix, then `n`. `ctrl+alt+n`, `cmd+k`, `alt+1`, and function-key chords are direct terminal-mode shortcuts and do not need the prefix. Plain direct printable keys such as `n` steal normal typing, so use `prefix+n` unless you intentionally want a modifier-gated direct binding.
 
@@ -67,7 +67,7 @@ Herdr notifies you when a new version is available. Run manually:
 herdr update
 ```
 
-`herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs update through `brew upgrade herdr` or your Nix workflow. See [install docs](https://herdr.dev/docs/install/) and [session state docs](https://herdr.dev/docs/session-state/) for the full update, restart, restore, and handoff matrix.
+`herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs update through `brew upgrade herdr` or your Nix workflow, then use the same stop-and-run-again flow if a session is still running the old server. See [install docs](https://herdr.dev/docs/install/) and [session state docs](https://herdr.dev/docs/session-state/) for the full update, restart, restore, and handoff matrix.
 
 ## how it compares
 
diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index 90e3e35c..39604731 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -8,6 +8,13 @@
 ### Fixed
 - The OpenCode integration no longer treats `session.created` or `session.updated` plugin events as idle signals, so active sessions stay marked working until OpenCode reports `session.status` or `session.idle`. (#351)
 - New interactive panes now use login-shell startup on macOS by default so Homebrew and other login PATH setup is available, with `terminal.shell_mode = "non_login"` as an opt-out. (#350)
+- Claude Code panes no longer stay blocked after stale permission-prompt reports when the visible screen has returned to idle or working state. (#349)
+- Codex panes no longer stay working because stale `esc to interrupt` text remains above a visible idle prompt, and visible approval-review work is now preserved as working. (#352)
+- Sidebar Git status refresh now deduplicates workspaces from the same checkout and reuses cached ahead/behind results when refs have not changed, reducing idle CPU from repeated `git` polling. (#353)
+- Update prompts, toasts, and docs now distinguish installing a new binary from stopping or reattaching a running Herdr session to use it.
+- Large restored sessions no longer leave restored or newly split panes without shells after startup, and live handoff keeps PTY ownership bounded to one master fd per pane. (#357)
+- Pane shutdown no longer warns that a pane is still alive after the direct child has already exited and been reaped. (#338)
+- Closing the last pane or tab in a parent worktree workspace now shows the existing confirmation before closing the whole worktree group. (#369)
 
 ## [0.6.5] - 2026-05-29
 
diff --git a/justfile b/justfile
index 8922e2fe..1f5a475a 100644
--- a/justfile
+++ b/justfile
@@ -20,7 +20,7 @@ ci: lint
 
 # Check formatting + run unit tests + maintenance script tests
 check: ci
-    python3 -m unittest scripts.test_changelog scripts.test_vendor_libghostty_vt
+    python3 -m unittest scripts.test_changelog scripts.test_nix_cargo_hash scripts.test_vendor_libghostty_vt
     @echo "docs reminder: if this changes user-facing behavior, make sure the relevant release docs are updated or called out before release."
 
 # Install repo-local git hooks
@@ -75,8 +75,16 @@ release-docs-check:
         fi; \
     done
 
-# Finalize changelog, bump version, commit, tag, push, and trigger the GitHub Release workflow (usage: just release 0.1.1)
-release version:
+# Refresh nix/package.nix cargoHash after Cargo.toml or Cargo.lock changes
+refresh-nix-cargo-hash:
+    python3 scripts/nix_cargo_hash.py refresh
+
+# Check nix/package.nix cargoHash without patching
+check-nix-cargo-hash:
+    python3 scripts/nix_cargo_hash.py check
+
+# Prepare the release commit without tagging or pushing (usage: just release-prepare 0.1.1)
+release-prepare version:
     @if [ -n "$(git status --porcelain)" ]; then \
         echo "error: commit your changes first"; \
         exit 1; \
@@ -90,13 +98,56 @@ release version:
     cp CHANGELOG.md docs/next/CHANGELOG.md
     sed -i.bak 's/^version = ".*"/version = "{{version}}"/' Cargo.toml && rm -f Cargo.toml.bak
     cargo update -p herdr --offline
+    just refresh-nix-cargo-hash
     just check
-    git add CHANGELOG.md docs/next/CHANGELOG.md Cargo.toml Cargo.lock
+    git add CHANGELOG.md docs/next/CHANGELOG.md Cargo.toml Cargo.lock nix/package.nix
     git diff --cached --quiet || git commit -m "release: v{{version}}"
+    @echo "v{{version}} release commit prepared. Review it, then run: just release-publish {{version}}"
+
+# Tag and push an already-prepared release commit (usage: just release-publish 0.1.1)
+release-publish version:
+    @if [ -n "$(git status --porcelain)" ]; then \
+        echo "error: working tree must be clean before publishing"; \
+        exit 1; \
+    fi
+    @branch="$(git branch --show-current)"; \
+    if [ "$branch" != "master" ]; then \
+        echo "error: release-publish must run from master, got $branch"; \
+        exit 1; \
+    fi
+    @git fetch origin master --tags
+    @if git rev-parse "v{{version}}" >/dev/null 2>&1; then \
+        echo "error: tag v{{version}} already exists"; \
+        exit 1; \
+    fi
+    @cargo_version="$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)"; \
+    if [ "$cargo_version" != "{{version}}" ]; then \
+        echo "error: Cargo.toml version $cargo_version does not match {{version}}"; \
+        exit 1; \
+    fi
+    just release-docs-check
+    python3 scripts/changelog.py extract --version {{version}} --output /tmp/herdr-release-notes-check.md
+    rm -f /tmp/herdr-release-notes-check.md
+    just check-nix-cargo-hash
+    @local_head="$(git rev-parse HEAD)"; \
+    remote_head="$(git rev-parse origin/master)"; \
+    if ! git merge-base --is-ancestor "$remote_head" "$local_head"; then \
+        echo "error: origin/master is not an ancestor of HEAD; pull or rebase before publishing"; \
+        exit 1; \
+    fi; \
+    if [ "$local_head" != "$remote_head" ]; then \
+        echo "pushing release commit to origin/master"; \
+        git push origin HEAD:master; \
+    fi
     git tag -a v{{version}} -m "v{{version}}"
-    git push --follow-tags
+    git push origin v{{version}}
     @echo "v{{version}} released — GitHub Actions building binaries and updating website/latest.json"
 
+# Prepare, verify, tag, push, and trigger the GitHub Release workflow (usage: just release 0.1.1)
+release version:
+    just release-prepare {{version}}
+    just release-publish {{version}}
+
 # Print default config
 default-config:
     cargo run --release --locked -- --default-config
diff --git a/scripts/nix_cargo_hash.py b/scripts/nix_cargo_hash.py
new file mode 100644
index 00000000..1e9a28f6
--- /dev/null
+++ b/scripts/nix_cargo_hash.py
@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+class NixCargoHashError(ValueError):
+    pass
+
+
+CARGO_HASH_RE = re.compile(
+    r"(?m)^(\s*cargoHash\s*=\s*)(\"sha256-[^\"]+\"|lib\.fakeHash)(;\s*)$"
+)
+GOT_HASH_RE = re.compile(r"\bgot:\s*(sha256-[A-Za-z0-9+/=]+)")
+
+
+def find_cargo_hash_assignment(package_text: str) -> str:
+    matches = list(CARGO_HASH_RE.finditer(package_text))
+    if len(matches) != 1:
+        raise NixCargoHashError(
+            f"expected exactly one cargoHash assignment, found {len(matches)}"
+        )
+    return matches[0].group(2)
+
+
+def replace_cargo_hash_assignment(package_text: str, replacement: str) -> str:
+    matches = list(CARGO_HASH_RE.finditer(package_text))
+    if len(matches) != 1:
+        raise NixCargoHashError(
+            f"expected exactly one cargoHash assignment, found {len(matches)}"
+        )
+    return CARGO_HASH_RE.sub(
+        lambda match: f"{match.group(1)}{replacement}{match.group(3)}",
+        package_text,
+    )
+
+
+def parse_got_hash(output: str) -> str:
+    hashes = GOT_HASH_RE.findall(output)
+    if len(hashes) != 1:
+        raise NixCargoHashError(
+            f"expected exactly one got: sha256-... hash, found {len(hashes)}"
+        )
+    return hashes[0]
+
+
+def run_capture(command: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        check=False,
+    )
+
+
+def run_checked(command: list[str]) -> None:
+    subprocess.run(command, check=True)
+
+
+def discover_cargo_hash(package_path: Path) -> tuple[str, str]:
+    if shutil.which("nix") is None:
+        raise NixCargoHashError("nix is required to refresh nix/package.nix cargoHash")
+    if not package_path.exists():
+        raise NixCargoHashError(f"{package_path} does not exist")
+
+    original_text = package_path.read_text(encoding="utf-8")
+    original_assignment = find_cargo_hash_assignment(original_text)
+    discovered_hash: str | None = None
+
+    try:
+        package_path.write_text(
+            replace_cargo_hash_assignment(original_text, "lib.fakeHash"),
+            encoding="utf-8",
+        )
+
+        system = run_capture(
+            ["nix", "eval", "--impure", "--raw", "--expr", "builtins.currentSystem"]
+        )
+        if system.returncode != 0:
+            raise NixCargoHashError(
+                system.stdout.strip() or "failed to read Nix currentSystem"
+            )
+
+        build_attr = f".#packages.{system.stdout.strip()}.herdr"
+        print(f"building {build_attr} with lib.fakeHash to discover cargoHash")
+        result = run_capture(["nix", "build", build_attr, "--no-link", "--print-build-logs"])
+        if result.returncode == 0:
+            raise NixCargoHashError(
+                "nix build succeeded with lib.fakeHash; could not discover cargoHash"
+            )
+
+        discovered_hash = parse_got_hash(result.stdout)
+    finally:
+        package_path.write_text(original_text, encoding="utf-8")
+
+    return discovered_hash, original_assignment
+
+
+def refresh_cargo_hash(package_path: Path) -> None:
+    discovered_hash, original_assignment = discover_cargo_hash(package_path)
+
+    new_assignment = f'"{discovered_hash}"'
+    if new_assignment == original_assignment:
+        print(f"nix/package.nix cargoHash is unchanged: {discovered_hash}")
+    else:
+        print(f"updating nix/package.nix cargoHash to {discovered_hash}")
+    package_path.write_text(
+        replace_cargo_hash_assignment(package_path.read_text(encoding="utf-8"), new_assignment),
+        encoding="utf-8",
+    )
+
+    print("verifying Nix flake checks")
+    run_checked(["nix", "flake", "check", "--print-build-logs"])
+    run_checked(["nix", "flake", "check", "--all-systems", "--no-build", "--print-build-logs"])
+    print("nix/package.nix cargoHash is ready")
+
+
+def check_cargo_hash(package_path: Path) -> None:
+    discovered_hash, current_assignment = discover_cargo_hash(package_path)
+    expected_assignment = f'"{discovered_hash}"'
+    if current_assignment != expected_assignment:
+        raise NixCargoHashError(
+            "nix/package.nix cargoHash is stale: "
+            f"expected {expected_assignment}, found {current_assignment}"
+        )
+    print(f"nix/package.nix cargoHash matches discovered hash: {discovered_hash}")
+
+
+def cmd_refresh(args: argparse.Namespace) -> int:
+    refresh_cargo_hash(Path(args.package))
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    check_cargo_hash(Path(args.package))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Refresh nix/package.nix cargoHash")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    check = subparsers.add_parser("check", help="Check cargoHash without patching")
+    check.add_argument("--package", default="nix/package.nix")
+    check.set_defaults(func=cmd_check)
+
+    refresh = subparsers.add_parser("refresh", help="Refresh cargoHash using Nix")
+    refresh.add_argument("--package", default="nix/package.nix")
+    refresh.set_defaults(func=cmd_refresh)
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        return args.func(args)
+    except (NixCargoHashError, subprocess.CalledProcessError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/test_nix_cargo_hash.py b/scripts/test_nix_cargo_hash.py
new file mode 100644
index 00000000..c00b1a6c
--- /dev/null
+++ b/scripts/test_nix_cargo_hash.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import unittest
+
+from scripts.nix_cargo_hash import (
+    NixCargoHashError,
+    check_cargo_hash,
+    find_cargo_hash_assignment,
+    parse_got_hash,
+    replace_cargo_hash_assignment,
+)
+
+
+PACKAGE_TEXT = """
+rustPlatform.buildRustPackage {
+  pname = "herdr";
+  cargoHash = "sha256-oldHash=";
+}
+"""
+
+
+class NixCargoHashTests(unittest.TestCase):
+    def test_find_cargo_hash_assignment_reads_single_hash(self) -> None:
+        self.assertEqual(find_cargo_hash_assignment(PACKAGE_TEXT), '"sha256-oldHash="')
+
+    def test_replace_cargo_hash_assignment_updates_single_hash(self) -> None:
+        updated = replace_cargo_hash_assignment(PACKAGE_TEXT, '"sha256-newHash="')
+
+        self.assertIn('cargoHash = "sha256-newHash=";', updated)
+        self.assertNotIn("sha256-oldHash", updated)
+
+    def test_replace_cargo_hash_assignment_accepts_fake_hash(self) -> None:
+        updated = replace_cargo_hash_assignment(PACKAGE_TEXT, "lib.fakeHash")
+
+        self.assertIn("cargoHash = lib.fakeHash;", updated)
+
+    def test_replace_cargo_hash_assignment_rejects_missing_hash(self) -> None:
+        with self.assertRaisesRegex(NixCargoHashError, "found 0"):
+            replace_cargo_hash_assignment('pname = "herdr";\n', "lib.fakeHash")
+
+    def test_replace_cargo_hash_assignment_rejects_multiple_hashes(self) -> None:
+        text = PACKAGE_TEXT + PACKAGE_TEXT
+
+        with self.assertRaisesRegex(NixCargoHashError, "found 2"):
+            replace_cargo_hash_assignment(text, "lib.fakeHash")
+
+    def test_parse_got_hash_reads_nix_hash_mismatch(self) -> None:
+        output = """
+        specified: sha256-oldHash=
+             got: sha256-newHash123+/=
+        """
+
+        self.assertEqual(parse_got_hash(output), "sha256-newHash123+/=")
+
+    def test_parse_got_hash_rejects_missing_hash(self) -> None:
+        with self.assertRaisesRegex(NixCargoHashError, "found 0"):
+            parse_got_hash("error: no hash here")
+
+    def test_parse_got_hash_rejects_multiple_hashes(self) -> None:
+        output = "got: sha256-one=\ngot: sha256-two=\n"
+
+        with self.assertRaisesRegex(NixCargoHashError, "found 2"):
+            parse_got_hash(output)
+
+    def test_check_cargo_hash_restores_file_on_failure(self) -> None:
+        import contextlib
+        import io
+        import tempfile
+        from pathlib import Path
+        from unittest import mock
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            package = Path(temp_dir) / "package.nix"
+            package.write_text(PACKAGE_TEXT, encoding="utf-8")
+
+            with mock.patch("scripts.nix_cargo_hash.shutil.which", return_value="/nix/bin/nix"):
+                with mock.patch("scripts.nix_cargo_hash.run_capture") as run_capture:
+                    run_capture.side_effect = [
+                        mock.Mock(returncode=0, stdout="x86_64-linux"),
+                        mock.Mock(returncode=1, stdout="error without got hash"),
+                    ]
+
+                    with contextlib.redirect_stdout(io.StringIO()):
+                        with self.assertRaisesRegex(NixCargoHashError, "found 0"):
+                            check_cargo_hash(package)
+
+            self.assertIn("--no-link", run_capture.call_args_list[1].args[0])
+            self.assertEqual(package.read_text(encoding="utf-8"), PACKAGE_TEXT)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx
index 936cc3ac..189e2121 100644
--- a/website/src/content/docs/configuration.mdx
+++ b/website/src/content/docs/configuration.mdx
@@ -56,6 +56,15 @@ default_shell = "nu"
 
 When unset or empty, Herdr uses `$SHELL`, then `/bin/sh`. This is an executable name or path, not a shell command line. Existing panes keep their current shell until they are recreated. Command panes still run through `/bin/sh -c`; detached custom command keybindings use Herdr's existing `/bin/sh -lc` path.
 
+Set how Herdr starts newly created interactive pane shells:
+
+```toml
+[terminal]
+shell_mode = "auto"
+```
+
+`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup, or `"non_login"` to opt out. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
+
 Set the working directory policy for new panes, tabs, and workspaces:
 
 ```toml
@@ -180,12 +189,15 @@ Custom commands use the same keybinding syntax.
 key = "prefix+alt+g"
 type = "pane"
 command = "lazygit"
+description = "run lazygit"
 ```
 
 `type = "pane"` opens a temporary pane and closes it when the command exits.
 
 `type = "shell"` runs detached in the background.
 
+An optional `description` can be provided. When specified, this description is displayed in the keybind help panel (opened with `prefix+?`) in place of the default `'custom command'` label.
+
 Custom commands receive `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ACTIVE_WORKSPACE_ID`, `HERDR_ACTIVE_TAB_ID`, `HERDR_ACTIVE_PANE_ID`, and `HERDR_ACTIVE_PANE_CWD` when those values are available. Shell commands run from the focused pane's working directory when Herdr can detect it.
 
 ## Theme
diff --git a/website/src/content/docs/install.mdx b/website/src/content/docs/install.mdx
index 434b5149..409b0d50 100644
--- a/website/src/content/docs/install.mdx
+++ b/website/src/content/docs/install.mdx
@@ -43,13 +43,15 @@ herdr update
 
 `herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs are updated through those package managers instead.
 
-By default, `herdr update` installs the new binary and leaves compatible running sessions alone, or asks before stopping sessions that must restart. To opt into experimental live server handoff for supported running sessions, run:
+By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
+
+To opt into experimental live server handoff for supported running sessions, run:
 
 ```bash
 herdr update --handoff
 ```
 
-Live handoff does not apply to Homebrew or Nix package-manager updates. For those installs, update with the package manager, then restart any running Herdr servers that need the new binary.
+Live handoff does not apply to Homebrew or Nix package-manager updates. For those installs, update with the package manager, then restart that Herdr session when you are ready to use the new server. If a running session still uses the old server, stop it with `herdr server stop` or `herdr session stop <name>`, then run Herdr again.
 
 ## Install with Nix