fix: require explicit workspace group close

[akbash-bot]

Summary

• reject implicit workspace.close of a primary checkout while linked-worktree workspaces remain open
• add CLI --group and raw API close_group: true for explicit group closure
• emit one final workspace.closed event per workspace removed by a group close
• preserve existing TUI confirmation and confirmation-disabled group-close behavior through the public API path
• add adversarial identity-state coverage for noncontiguous group removal
• bump the client/server protocol to 21 because protocol 20 was published before this request contract changed

Supersedes #2876 after rebasing onto current master; that PR's canonical head branch is no longer writable by akbash-bot.

Checks

• cargo test api_workspace_close_noncontiguous_group_preserves_adversarial_identity_state -- --nocapture
• just ci 'all() - test(live_server_holds_one_pty_master_fd_per_pane)' (3522 passed; excluded test has a checkout-local target/debug/herdr PID-discovery assumption incompatible with Kennel's required external CARGO_TARGET_DIR)
• just windows-lint
• maintenance tests (98 passed)

refs #2874

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ae1ee9b-6760-4a07-a67c-d95f1540d065

📥 Commits

Reviewing files that changed from the base of the PR and between 7ad6f56 and f90311f.

📒 Files selected for processing (6)

• src/app/actions.rs
• src/app/api/workspaces.rs
• src/app/input/modal.rs
• src/app/input/mouse.rs
• src/app/mod.rs
• src/app/state.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The workspace.close API now accepts close_group. The CLI adds --group. Parent workspaces with open linked worktrees require explicit group closure. Group closure removes all members and emits one event per workspace. The wire protocol version changes to 21.

Changes

Workspace group closure

Layer / File(s)	Summary
Close request contract and protocol version docs/next/api/herdr-api.schema.json, src/api/schema/..., src/protocol/wire.rs, tests/api_ping.rs, tests/cli/sessions.rs, tests/support/mod.rs	workspace.close uses WorkspaceCloseParams with an optional close_group flag. The protocol version changes to 21.
Group selection and API closure src/app/api/workspaces.rs	The API rejects implicit parent-group closure, removes selected group members when requested, and emits one WorkspaceClosed event per removed workspace.
CLI, runtime, and interface integration src/cli/..., src/app/runtime_mutations.rs, src/app/input/..., src/app/actions.rs	The CLI parses --group. Runtime, navigation, and modal flows use grouped closure. Confirmation stores the original workspace target.
CLI and socket API documentation docs/next/website/src/content/docs/...	CLI and socket API references document --group, workspace_group_close_required, and per-workspace close events.

Application event compatibility

Layer / File(s)	Summary
Event and hyperlink handling src/app/actions.rs	Direct terminal hyperlink metadata is returned without HTTP(S)-only validation. Manifest update events accept additional fields.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to f9031

The PR changes workspace group-close behavior and the protocol contract, but no actionable merge-blocking risk remains at the current head. It is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Runtime
  participant WorkspaceAPI
  participant WorkspaceState
  participant EventStream
  CLI->>Runtime: workspace ID and optional --group
  Runtime->>WorkspaceAPI: WorkspaceCloseParams
  WorkspaceAPI->>WorkspaceState: validate and select worktree group
  WorkspaceState-->>WorkspaceAPI: selected workspace snapshots
  WorkspaceAPI->>WorkspaceState: remove group workspaces
  WorkspaceAPI->>EventStream: emit WorkspaceClosed for each workspace

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 44.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 58 functions across 18 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: requiring explicit intent for workspace group closure.
Description check	✅ Passed	The description directly explains the workspace close behavior, new CLI and API options, event changes, protocol bump, tests, and compatibility behavior.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c8acc22e-5a53-4cb7-a917-45f0cb4db9b5

📥 Commits

Reviewing files that changed from the base of the PR and between 7d56b4c and 812c14a.

📒 Files selected for processing (23)

• docs/next/CHANGELOG.md
• docs/next/api/herdr-api.schema.json
• docs/next/website/src/content/docs/cli-reference.mdx
• docs/next/website/src/content/docs/ja/cli-reference.mdx
• docs/next/website/src/content/docs/ja/socket-api.mdx
• docs/next/website/src/content/docs/socket-api.mdx
• docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
• docs/next/website/src/content/docs/zh-cn/socket-api.mdx
• src/api/schema.rs
• src/api/schema/tests.rs
• src/api/schema/workspaces.rs
• src/app/actions.rs
• src/app/api/workspaces.rs
• src/app/input/modal.rs
• src/app/input/navigate.rs
• src/app/runtime_mutations.rs
• src/cli/runtime.rs
• src/cli/workspace.rs
• src/protocol/wire.rs
• tests/api_ping.rs
• tests/cli/sessions.rs
• tests/cli/workspace.rs
• tests/support/mod.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

[akbash-bot]

@greptileai

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ed68b7c9-d22b-4096-8aac-58096bc86312

📥 Commits

Reviewing files that changed from the base of the PR and between 812c14a and abcf10b.

📒 Files selected for processing (3)

• docs/next/website/src/content/docs/ja/socket-api.mdx
• docs/next/website/src/content/docs/socket-api.mdx
• docs/next/website/src/content/docs/zh-cn/socket-api.mdx

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

[greptile-apps]

Greptile Summary

This PR makes closure of a primary workspace with open linked-worktree workspaces require explicit group intent.

• Adds close_group to the socket request and --group to the CLI.
• Routes TUI confirmations and confirmation-disabled closure through the explicit group-close API path.
• Preserves terminal, plugin, focus, identity, and lifecycle-event cleanup while removing noncontiguous group members.
• Publishes the updated API schema and increments the client/server protocol to 21.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/app/api/workspaces.rs	Enforces explicit group-close intent, snapshots group members before mutation, performs cleanup, and publishes final closure events.
src/app/actions.rs	Centralizes group membership selection and safely removes potentially noncontiguous members in descending index order.
src/app/input/modal.rs	Routes confirmed context-menu and modal group closures through the public API mutation path.
src/app/input/navigate.rs	Preserves confirmation behavior for workspace and last-tab actions while explicitly requesting group closure when appropriate.
src/api/schema/workspaces.rs	Adds the backward-decodable close_group request field with an omitted-value default of false.
src/cli/workspace.rs	Adds the documented workspace close <id> --group command form and forwards explicit group intent.
src/protocol/wire.rs	Increments the exact-match client/server protocol constant from 20 to 21.
docs/next/api/herdr-api.schema.json	Publishes the protocol increment and updated workspace.close request schema.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[workspace.close request] --> B{Primary with linked workspaces?}
  B -->|No| C[Close target workspace]
  B -->|Yes| D{Explicit close_group?}
  D -->|No| E[Return workspace_group_close_required]
  D -->|Yes| F[Snapshot every group member]
  F --> G[Remove group members in reverse index order]
  G --> H[Shut down detached terminal runtimes]
  H --> I[Emit one workspace.closed event per removed workspace]

Loading

_{Reviews (3): Last reviewed commit: "fix: require explicit workspace group cl..." | Re-trigger Greptile}

[akbash-bot]

@greptileai