Epic: Make workspace operations transactional and recoverable

[nicksong-z]

Problem

Grove coordinates one logical workspace across several independent Git repositories, the filesystem, and ~/.grove/state.json. Today those layers can diverge when an operation partially fails or two gw processes mutate state concurrently.

That is manageable for an interactive personal tool, but it becomes a trust problem as Grove is used for larger workspaces, scripts, and parallel coding agents. Before adding higher-level automation, the core lifecycle needs explicit safety and recovery guarantees.

Goal

Make every mutating workspace operation either:

1. complete successfully;
2. roll back everything it created; or
3. leave enough durable state for gw doctor/a repair command to explain and finish recovery.

A user should never need to manually inspect .git/worktrees, branches, directories, and state.json to understand a failed Grove operation.

Safety invariants

• State, filesystem paths, and Git worktree registrations agree after successful operations.
• State changes cannot be lost when two gw processes run concurrently.
• Destructive cleanup never falls back to deleting an unexpected path without explicit force.
• Partial failures are surfaced per repository and produce a non-zero exit status.
• Failed cleanup remains discoverable and retryable.
• Recovery operations are idempotent.

Known gaps to address

Creation and addition

• Roll back branches as well as worktrees when workspace creation fails.
• Make multi-repo AddRepos atomic, including failure after one or more repos were added.
• Recover safely when the final state write fails.

Removal and deletion

• Stop swallowing git worktree remove, filesystem removal, and branch cleanup failures.
• Preflight dirty worktrees and verify expected source/path/worktree registration.
• Reserve unconditional filesystem deletion for an explicit --force path.
• Keep incomplete deletions in state as cleanup-pending instead of losing visibility.
• Aggregate multi-workspace deletion results instead of exiting after the first failure.

State consistency

• Add cross-process locking or another lost-update-safe state mutation mechanism.
• Define a single mutation boundary shared by CLI and future plugin/API callers.
• Consider a small operation journal only if locking + rollback cannot provide reliable recovery.

Reconciliation and automation

• Expand gw doctor to compare state, filesystem paths, git worktree list --porcelain, and branch state.
• Add machine-readable repair plans/results.
• Return structured per-repo outcomes and meaningful exit codes from sync, add/remove, create, and delete.

Suggested delivery slices

• Document lifecycle invariants and failure semantics.
• Add cross-process state locking and concurrency tests.
• Fix create/add rollback, with fault-injection tests.
• Make remove/delete safe and retryable, with dirty/unregistered-path tests.
• Add reconciliation and repair support to gw doctor.
• Standardize structured operation results and exit behavior.
• Add race-detector coverage for concurrent workspace operations.
• Align OpenWiki lifecycle documentation with the implemented behavior.

Acceptance criteria

• Fault-injection tests cover failure at each mutation phase.
• Concurrent state mutation tests demonstrate that updates are not lost.
• Interrupted/partial operations can be diagnosed and recovered without manual Git surgery.
• Default deletion does not erase dirty or unexpected paths.
• Automation receives non-zero exit status plus per-repo failure details.
• Unit and e2e suites pass under the race detector.

Non-goals

• Distributed or cloud workspace state.
• A general transaction framework.
• Hiding every Git error: actionable errors are preferable to unsafe automatic recovery.
• Expanding the command surface while lifecycle guarantees are still ambiguous.

Why now

This is the foundation for higher-level flows such as gw grab <task-or-pr-url> and declarative workspace blueprints. Those features increase automation and concurrency, so they should build on a core users can safely trust.

Related

• Epic: Replace MCP with an agent-native CLI #63 — exposes these trustworthy operations through the agent-native CLI contract.
• Epic: Turn a task or PR URL into a ready workspace with gw grab #60 — builds task/PR intake on top of the safe lifecycle.
• Epic: Blueprints — presets as code (Preset 2.0) #61 — applies Preset 2.0 blueprints through the same transaction boundary.
• Epic: Grove Oven — maintain ready-to-claim hot workspaces #62 — requires reliable disposable bake workspaces and cache hydration cleanup.