diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c51b4b26..d18ed5c8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -70,7 +70,22 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Run tests
+        run: cargo test --all-features
+
+  test-windows:
+    name: Test (windows-latest)
+    runs-on: windows-latest
     steps:
       - uses: actions/checkout@v4
 
@@ -83,10 +98,7 @@ jobs:
       - name: Run tests
         run: cargo test --all-features
         env:
-          # Windows: link advapi32 for libgit2-sys (needed for test crates that
-          # don't go through build.rs) and increase stack to 8 MB (debug builds
-          # overflow the default 1 MB Windows stack during clap parsing)
-          RUSTFLAGS: ${{ matrix.os == 'windows-latest' && '-C link-arg=advapi32.lib -C link-arg=/STACK:8388608' || '' }}
+          RUSTFLAGS: '-C link-arg=advapi32.lib -C link-arg=/STACK:8388608'
 
   build:
     name: Build Release
@@ -149,14 +161,16 @@ jobs:
       - name: Run spawn integration tests
         run: GR=./target/debug/gr ./tests/spawn_graceful_shutdown.sh
 
-  # Summary job for branch protection - requires all other jobs to pass
+  # Summary job for branch protection - requires all jobs except Windows to pass.
+  # Windows tests run separately (test-windows) and are visible but non-blocking,
+  # since they are significantly slower and should not gate PR merges.
   ci:
     name: CI
     runs-on: ubuntu-latest
     needs: [check, fmt, clippy, test, build, bench, integration]
     if: always()
     steps:
-      - name: Check all jobs passed
+      - name: Check all required jobs passed
         run: |
           if [[ "${{ needs.check.result }}" != "success" ]] || \
              [[ "${{ needs.fmt.result }}" != "success" ]] || \
@@ -165,7 +179,7 @@ jobs:
              [[ "${{ needs.build.result }}" != "success" ]] || \
              [[ "${{ needs.bench.result }}" != "success" ]] || \
              [[ "${{ needs.integration.result }}" != "success" ]]; then
-            echo "One or more jobs failed"
+            echo "One or more required jobs failed"
             exit 1
           fi
-          echo "All jobs passed"
+          echo "All required jobs passed"
diff --git a/Cargo.lock b/Cargo.lock
index d273c8a9..7bba51b8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -826,6 +826,8 @@ dependencies = [
  "futures",
  "git2",
  "gix",
+ "glob",
+ "gr2-cli",
  "indicatif",
  "octocrab",
  "once_cell",
@@ -1586,6 +1588,23 @@ dependencies = [
  "gix-validate 0.9.4",
 ]
 
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
+[[package]]
+name = "gr2-cli"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "chrono",
+ "clap",
+ "serde",
+ "toml",
+]
+
 [[package]]
 name = "h2"
 version = "0.4.13"
diff --git a/Cargo.toml b/Cargo.toml
index 4d178366..09ec58f6 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,6 +13,9 @@ readme = "README.md"
 keywords = ["git", "monorepo", "workflow", "multi-repo", "cli"]
 categories = ["development-tools", "command-line-utilities"]
 
+[workspace]
+members = ["gr2"]
+
 [[bin]]
 name = "gr"
 path = "src/main.rs"
@@ -21,6 +24,10 @@ path = "src/main.rs"
 name = "gitgrip"
 path = "src/main.rs"
 
+[[bin]]
+name = "gr2"
+path = "src/bin/gr2.rs"
+
 [lib]
 name = "gitgrip"
 path = "src/lib.rs"
@@ -40,6 +47,7 @@ release-logs = ["tracing/release_max_level_info"]
 max-perf = ["tracing/max_level_off"]
 
 [dependencies]
+gr2_cli = { package = "gr2-cli", path = "gr2" }
 # Async runtime
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "process", "time", "net", "io-util", "sync"] }
 uuid = { version = "1", features = ["v4"] }
@@ -85,6 +93,9 @@ quick-xml = { version = "0.37", features = ["serialize"] }
 # TOML parsing
 toml = "0.8"
 
+# Glob patterns (for linkfile/copyfile glob expansion)
+glob = "0.3"
+
 # Misc
 once_cell = "1"
 regex = "1"
diff --git a/README.md b/README.md
index bb5751ff..eba83f76 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,7 @@ gr sync
 | `gr branch [name]` | Create or list branches |
 | `gr checkout <branch>` | Checkout branch across repos |
 | `gr checkout -b <branch>` | Create and checkout branch in one command |
+| `gr checkout add <name>` | Create an independent child checkout from cached repos |
 | `gr add [files]` | Stage changes across repos |
 | `gr diff` | Show diff across repos |
 | `gr commit -m "msg"` | Commit across repos |
@@ -183,6 +184,9 @@ gr sync
 | `gr link` | Manage file links |
 | `gr run <script>` | Run workspace scripts |
 | `gr env` | Show environment variables |
+| `gr cache status` | Show machine-level cache state for workspace repos |
+| `gr cache bootstrap` | Materialize missing machine-level repo caches |
+| `gr cache update` | Fetch updates into existing machine-level repo caches |
 | `gr bench` | Run performance benchmarks |
 | `gr completions <shell>` | Generate shell completions |
 
@@ -223,6 +227,34 @@ Pull latest changes from the manifest and all repositories. Syncs in parallel by
 
 Show status of all repositories including branch, changes, and sync state.
 
+#### `gr cache <subcommand>`
+
+Manage the machine-level bare-repo cache used by workspace repos.
+
+By default caches live under `~/.grip/cache/`, keyed by canonical repo identity.
+You can override the cache root with `GRIP_CACHE_DIR` when you need a custom or
+isolated cache location.
+
+| Subcommand | Description |
+|-----------|-------------|
+| `gr cache status` | Show whether each workspace repo has a cache and where it lives |
+| `gr cache bootstrap` | Create missing caches without touching existing ones |
+| `gr cache update` | Fetch updates into existing caches |
+| `gr cache remove <repo>` | Remove one repo cache explicitly |
+
+**Examples:**
+
+```bash
+# See where caches are currently resolved
+gr cache status
+
+# Create missing caches before materializing child checkouts
+gr cache bootstrap
+
+# Use a custom cache root for an isolated environment
+GRIP_CACHE_DIR=/tmp/grip-cache gr cache status
+```
+
 #### `gr checkout <branch>`
 
 Checkout a branch across all repos. Can also create branches with the `-b` flag.
@@ -232,6 +264,59 @@ Checkout a branch across all repos. Can also create branches with the `-b` flag.
 | `-b` | Create branch if it doesn't exist |
 | `--base` | Checkout the griptree base branch (griptree workspaces only) |
 
+#### `gr checkout add <name>`
+
+Create an independent child checkout under `.grip/checkouts/<name>/` using the
+workspace cache as an accelerator.
+
+Unlike `gr tree add`, this creates normal child clones with their own `.git`
+directories. The checkout keeps the canonical remote URL as `origin`; the cache
+is only used to speed up materialization.
+
+| Option | Description |
+|--------|-------------|
+| `--repo <name>` | Only materialize specific repos |
+| `--group <name>` | Only materialize repos in a group |
+
+**Examples:**
+
+```bash
+# Materialize all repos into an independent child checkout
+gr checkout add sandbox
+
+# Materialize only the docs group
+gr checkout add docs-only --group docs
+
+# Materialize just one repo
+gr checkout add app-only --repo app
+```
+
+#### `gr checkout list`
+
+Show the currently materialized child checkouts under
+`.grip/checkouts/`.
+
+**Examples:**
+
+```bash
+# List all materialized child checkouts
+gr checkout list
+```
+
+#### `gr checkout remove <name>`
+
+Remove a materialized child checkout under `.grip/checkouts/<name>/`.
+
+This deletes the child clone only. It does not delete the shared cache under
+`~/.grip/cache/`.
+
+**Examples:**
+
+```bash
+# Remove a disposable child checkout
+gr checkout remove sandbox
+```
+
 #### `gr branch [name]`
 
 Create a new branch across all repositories, or list existing branches. Manifest repo is always included.
diff --git a/docs/ASSESS-gr2-lanes-cross-mode-stress.md b/docs/ASSESS-gr2-lanes-cross-mode-stress.md
new file mode 100644
index 00000000..75872c0f
--- /dev/null
+++ b/docs/ASSESS-gr2-lanes-cross-mode-stress.md
@@ -0,0 +1,257 @@
+# gr2 Lane Model Cross-Mode Stress Matrix
+
+## Purpose
+
+This is the adversarial verification matrix for the lane model itself.
+
+`gr2` is not only a multi-repo tool. It is the operating surface for:
+
+- a solo human
+- a single agent
+- multiple agents working in parallel
+- mixed human + agent collaboration
+
+The lane model is only credible if it holds under all four modes when users
+are interrupted, confused, concurrent, or partially out of sync.
+
+This document is intentionally hostile to the happy path.
+
+## Core Stress Dimensions
+
+Every lane design or implementation change should be tested against at least
+these dimensions:
+
+- recovery after interruption
+- current-context ambiguity
+- cross-lane contamination
+- concurrent mutation
+- private/shared boundary erosion
+- machine-readable status quality
+- wrong-surface choice
+- stale lane cleanup
+- review isolation
+- escalation path to PR or durable implementation
+
+## Solo Human Scenarios
+
+### 1. Multiple active features plus one review lane
+
+Scenario:
+- user has three feature lanes open
+- user switches to a review lane to inspect a PR
+- later they forget which feature lane they were in before the review
+
+What can break:
+- the lane model becomes cognitively expensive
+- review work disrupts the main task
+- users fall back to ad hoc notes or shell history to recover state
+
+What `gr2` must make obvious:
+- current lane
+- most recently active lanes
+- branch intent per lane
+- repo set per lane
+- an explicit "return to previous lane" path
+
+### 2. Human starts a second feature while the first waits on review
+
+Scenario:
+- feature A spans three repos and is waiting on peer review
+- user starts feature B in two of the same repos
+
+What can break:
+- branch confusion across repos
+- fear that new work will disturb the reviewable state of feature A
+
+What `gr2` must guarantee:
+- feature lanes stay isolated
+- branch intent is visible per lane
+- switching lanes does not require understanding cache internals
+
+### 3. Human forgets whether a command should run in home or feature lane
+
+Scenario:
+- user returns after an interruption
+- they know what they want to test, but not which lane owns the work
+
+What can break:
+- commands run in the wrong checkout
+- users stop trusting lane-aware execution
+
+What `gr2` must provide:
+- one obvious lane status surface
+- one obvious execution status surface
+- enough next-step guidance to recover without spelunking the filesystem
+
+## Single-Agent Scenarios
+
+### 4. Agent is interrupted mid-task and must context-switch
+
+Scenario:
+- agent is mid-task in a feature lane
+- a new prompt arrives and requires immediate work in another lane
+
+What can break:
+- agent loses its original working context
+- agent resumes in the wrong lane later
+- machine-readable state is too weak to recover deterministically
+
+What `gr2` must provide:
+- explicit current-lane status
+- explicit recent-lane status
+- machine-readable branch intent and repo membership
+- deterministic lane re-entry
+
+### 5. Agent must decide whether to use a feature lane, review lane, or scratchpad
+
+Scenario:
+- prompt asks for review, design, or implementation work
+- agent has to choose a surface quickly
+
+What can break:
+- wrong-surface choice
+- review work begins in a feature lane
+- implementation begins in a scratchpad
+
+What `gr2` must provide:
+- strong recommendation surface
+- clear distinctions between lane types
+- structured output that can drive agent behavior without free-form guessing
+
+### 6. Agent needs to report status without prose reconstruction
+
+Scenario:
+- supervising human or another agent asks what the current lane state is
+
+What can break:
+- status becomes a prose summary instead of a durable machine-readable fact
+
+What `gr2` must provide:
+- lane state in stable structured output
+- repo set, branch intent, PR association, and execution defaults
+- enough state for another worker to understand the lane without opening it
+
+## Multi-Agent Scenarios
+
+### 7. Two agents create different lanes that touch the same repo
+
+Scenario:
+- Atlas creates `feature/gr2-exec`
+- Apollo creates `feature/gr2-materialize`
+- both lanes include `grip`
+
+What can break:
+- cross-lane interference through shared active workspaces
+- unclear ownership of repo mutations
+- accidental reuse of one agent's private checkout
+
+What `gr2` must guarantee:
+- lane ownership remains explicit
+- each agent gets its own working surface
+- shared cache does not become shared mutable state
+
+### 8. One agent reviews while another implements
+
+Scenario:
+- Apollo is actively implementing in a feature lane
+- Atlas creates a review lane against the same repo/PR stack
+
+What can break:
+- review mutates the implementation lane
+- ownership boundaries blur
+- review lane becomes an unofficial shared worktree
+
+What `gr2` must guarantee:
+- review lane is isolated and disposable
+- workspace-level discovery exists without sharing working directories
+
+### 9. Agent handoff between workers
+
+Scenario:
+- one agent stops mid-lane
+- another agent needs to understand the lane state and continue or review it
+
+What can break:
+- lane is understandable only via chat memory
+- ownership transfer becomes filesystem archaeology
+
+What `gr2` must provide:
+- workspace-level discovery
+- explicit unit ownership
+- machine-readable lane summary
+- explicit distinction between "resume in your own lane" and "inspect theirs"
+
+## Mixed Human + Agent Scenarios
+
+### 10. Human edits in a lane while an agent tries to execute in the same lane
+
+Scenario:
+- human is editing in a feature lane
+- agent tries to run lane-aware exec against that same lane
+
+What can break:
+- hidden concurrent mutation
+- trust collapse around agent actions
+
+What `gr2` must answer explicitly:
+- is same-lane concurrent execution allowed?
+- if not, how is it blocked or redirected?
+- if yes, what safety contract exists?
+
+The default should favor safety and explicit conflict over silent concurrency.
+
+### 11. Human wants help without giving up private working space
+
+Scenario:
+- human is implementing in a lane
+- they want an agent to assist on related docs, verification, or review work
+
+What can break:
+- agent must enter the human's lane to help
+- private-workspace boundaries erode
+
+What `gr2` must provide:
+- shared scratchpad for lightweight collaboration
+- review lane for PR/inspection work
+- clear rule that private implementation lanes stay private
+
+### 12. Human and agent both lose track of the canonical context
+
+Scenario:
+- human thinks feature work lives in lane A
+- agent thinks lane B is current because it was the last machine-visible lane
+
+What can break:
+- conflicting assumptions about where work lives
+- commands and edits target the wrong lane
+
+What `gr2` must provide:
+- explicit current context markers
+- explicit lane summaries for both human-readable and machine-readable use
+- no hidden ambient lane inference that only one side can see
+
+## Failure Criteria
+
+The lane model is not ready if any of these remain fuzzy:
+
+- how a user recovers the lane they were in before an interruption
+- how an agent deterministically reports and resumes lane context
+- how same-repo parallelism across agents stays isolated
+- how mixed human + agent use avoids shared mutable lane state
+- how users distinguish feature lanes, review lanes, and scratchpads under time pressure
+
+If those answers are not obvious in both human-readable and machine-readable
+surfaces, the model still needs prototype work before more build surface lands.
+
+## Verification Gate
+
+Before lane-heavy build work is treated as stable, we should be able to point
+to repeatable prototype checks for:
+
+- solo human recovery
+- single-agent interruption and resume
+- multi-agent same-repo parallelism
+- mixed human + agent same-lane conflict handling
+
+Until then, lane design should still be treated as under verification rather
+than settled.
diff --git a/docs/ASSESS-gr2-shared-scratchpads-stress.md b/docs/ASSESS-gr2-shared-scratchpads-stress.md
new file mode 100644
index 00000000..ef24783a
--- /dev/null
+++ b/docs/ASSESS-gr2-shared-scratchpads-stress.md
@@ -0,0 +1,191 @@
+# gr2 Shared Scratchpads Stress Matrix
+
+## Purpose
+
+This is the break-case matrix for the shared scratchpad prototype.
+
+The prototype is not "verified" because the happy path worked once.
+It is only verified if it survives the scenarios most likely to fail in
+real human + agent workflows.
+
+This document is intentionally adversarial.
+
+## Stress Dimensions
+
+Every new `gr2` surface should be pressured along at least these dimensions:
+
+- concurrency
+- stale metadata
+- ambiguous ownership
+- partial cleanup
+- wrong-surface use
+- escalation path to PR / implementation lane
+- recovery after interruption
+- discoverability under pressure
+
+## Shared Scratchpad Scenarios
+
+### 1. Two users edit at once
+
+Scenario:
+- Atlas and Layne both use the same doc scratchpad
+- both update the same draft in close succession
+
+What can break:
+- participants are recorded, but the workflow gives no clue how to coordinate
+- a scratchpad quietly becomes a conflict zone
+
+What the prototype must answer:
+- does the metadata make shared ownership explicit?
+- is the scratchpad clearly marked as shared rather than private?
+- is there a legible next-step path when coordination is needed?
+
+### 2. Scratchpad goes stale
+
+Scenario:
+- a blog draft scratchpad is created
+- no one touches it for a week
+- a new worker sees it later
+
+What can break:
+- no one knows if it is still active
+- stale drafts clutter the workspace
+
+Required design pressure:
+- lifecycle state must be visible
+- the model needs a pause/done path
+- stale scratchpads must be distinguishable from active ones
+
+### 3. Scratchpad scope creep into implementation
+
+Scenario:
+- users start dropping code or repo-specific implementation into a doc-first scratchpad
+
+What can break:
+- the scratchpad becomes an unofficial shared coding area
+- private-lane boundaries erode
+
+Required design pressure:
+- doc-first scope must stay explicit
+- the system must make it obvious that this is not a private feature lane
+- there should be a clear escalation path into a real lane or PR
+
+### 4. Wrong tool chosen
+
+Scenario:
+- user should have used a review lane, but instead creates a scratchpad
+- or should have used a scratchpad, but opens a PR too early
+
+What can break:
+- the tool surface becomes confusing
+- users stop trusting the model
+
+Required design pressure:
+- next-step guidance should help distinguish:
+  - private lane
+  - review lane
+  - shared scratchpad
+  - PR
+
+### 5. Missing or wrong participants
+
+Scenario:
+- scratchpad is created without the right people listed
+- later a third worker joins
+
+What can break:
+- implied ownership diverges from recorded ownership
+- people edit without being visible in metadata
+
+Required design pressure:
+- participant list must be editable
+- participant visibility must be cheap
+- absence of participants should not imply private ownership
+
+### 6. Scratchpad linked to the wrong issue or no issue
+
+Scenario:
+- scratchpad is linked to the wrong issue
+- or there is no linked issue yet
+
+What can break:
+- scratchpad loses traceability
+- coordination falls back into chat memory
+
+Required design pressure:
+- refs should be optional but visible
+- it should be easy to add or fix refs later
+
+### 7. Scratchpad completed, but content needs to graduate
+
+Scenario:
+- draft blog post is approved
+- now it needs to become a proper repo artifact and PR
+
+What can break:
+- there is no obvious promotion path
+- content gets stranded in the shared scratchpad
+
+Required design pressure:
+- the model needs a clear handoff path:
+  - scratchpad -> repo file -> PR
+
+### 8. Partial cleanup
+
+Scenario:
+- scratchpad metadata is removed, but docs remain
+- or docs are removed, but metadata remains
+
+What can break:
+- orphaned shared state
+- misleading listings
+
+Required design pressure:
+- cleanup needs to be explicit and symmetric
+- the status surface must expose orphaned scratchpads
+
+### 9. Discoverability under time pressure
+
+Scenario:
+- user just wants to collaborate on a blog now
+- they should not have to reverse-engineer the whole workspace model
+
+What can break:
+- the feature is technically correct but too cognitively expensive
+
+Required design pressure:
+- one obvious create path
+- one obvious list path
+- one obvious "what now?" path
+
+### 10. Private-workspace safety regression
+
+Scenario:
+- users begin treating scratchpads as permission to work in each other's spaces again
+
+What can break:
+- the original safety model regresses
+
+Required design pressure:
+- shared scratchpads must be framed as workspace-owned collaboration surfaces
+- they must not blur into private lanes
+
+## Gate Before MVP
+
+Before `grip#553` should be considered ready to build or finalize, we should be
+able to answer these questions clearly:
+
+- how is a scratchpad different from a review lane?
+- how is a scratchpad different from a PR?
+- how is a scratchpad kept from turning into shared implementation sprawl?
+- how does a stale scratchpad become visible and cleanable?
+- how does content graduate from scratchpad to repo artifact?
+
+If those are still fuzzy, the prototype is not ready for MVP.
+
+The prototype should also expose explicit operator surfaces for those cases:
+
+- a recommendation surface when the user is choosing between feature lane,
+  review lane, shared scratchpad, and PR
+- an audit surface for stale, orphaned, or weakly tracked scratchpads
+- a promotion surface that makes the handoff to repo artifact and PR explicit
diff --git a/docs/AUDIT-gr2-current-surface-vs-rulebook.md b/docs/AUDIT-gr2-current-surface-vs-rulebook.md
new file mode 100644
index 00000000..076b72c7
--- /dev/null
+++ b/docs/AUDIT-gr2-current-surface-vs-rulebook.md
@@ -0,0 +1,341 @@
+# Audit: Current gr2 Surface vs Rulebook
+
+## Scope
+
+This audit compares the current `gr2` implementation surface against:
+
+- `docs/PLAN-gr2-needs-and-criteria.md`
+- `docs/PLAN-gr2-repo-maintenance-and-lanes.md`
+
+Implementation reviewed:
+
+- `gr2/src/args.rs`
+- `gr2/src/dispatch.rs`
+- `gr2/src/plan.rs`
+- `gr2/src/spec.rs`
+
+## Executive Summary
+
+Current `gr2` is a useful structural bootstrap, not yet a first-class workspace.
+
+What it does reasonably well:
+
+- initialize a team-workspace skeleton
+- register repos and units
+- emit a basic workspace spec
+- plan and apply structural convergence
+- keep some repo mutation out of plain `apply`
+
+What it does not yet do:
+
+- named lanes
+- shared/private context
+- lane-aware execution
+- explicit repo-maintenance surfaces
+- review-lane isolation
+- durable recovery/state strong enough for multi-agent use
+
+Bottom line:
+
+- as a structural foundation: promising
+- as a human + multi-agent operating surface: incomplete
+
+## Criteria Assessment
+
+### 1. Structural and Repo-State Separation
+
+Status: `Partial`
+
+Strength:
+
+- the current model does separate `plan/apply` from most explicit branch/sync behavior
+
+Weakness:
+
+- `materialize_unit()` clones repos directly during `apply`, which is acceptable as structural convergence
+- but there is still no explicit repo-maintenance read/write surface above it
+- `Apply --autostash` exists, but the user still lacks a separate repo-status model to understand when it would matter
+
+Assessment:
+
+The safety boundary is directionally right, but incomplete because repo-state
+inspection is still missing.
+
+### 2. Named Multi-Repo Lanes
+
+Status: `Fail`
+
+Current surface:
+
+- no lane commands
+- no lane metadata
+- no lane types
+- no lane-local branch/PR/context model
+
+Assessment:
+
+This is the largest missing capability relative to the rulebook.
+
+### 3. Cheap Parallelism
+
+Status: `Partial`
+
+Strength:
+
+- workspace topology is moving toward clone-backed isolation rather than shared worktrees
+
+Weakness:
+
+- cache exists only as a path in spec; there is no active lane/cache model
+- no lane creation surface
+- no disposable review lane concept
+
+Assessment:
+
+The intended direction is there, but the system cannot yet prove cheap
+parallelism in practice.
+
+### 4. Shared and Private Context
+
+Status: `Fail`
+
+Current surface:
+
+- `config/` exists at init time
+- no context model in spec or metadata
+- no unit-private context roots
+- no lane-local context inheritance
+
+Assessment:
+
+This is entirely absent from current `gr2`.
+
+### 5. Lane-Aware Execution
+
+Status: `Fail`
+
+Current surface:
+
+- no `exec` surface
+- no lane scoping
+- no repo-subset execution model
+
+Assessment:
+
+The current implementation offers no first-class answer for build/test/run.
+
+### 6. Dirty Work Preservation
+
+Status: `Partial`
+
+Strength:
+
+- current branch includes explicit dirty repo detection inside unit repo checkouts
+- autostash/preservation hooks exist in `plan.rs`
+
+Weakness:
+
+- preservation is apply-time only
+- no separate repo-maintenance command family
+- no user-facing recovery/status surface yet
+
+Assessment:
+
+This is meaningful progress, but still not a complete preservation story.
+
+### 7. PR and Review Isolation
+
+Status: `Fail`
+
+Current surface:
+
+- no `checkout-pr`
+- no review lanes
+- no durable PR associations
+
+Assessment:
+
+Review remains external to the workspace model.
+
+### 8. Cross-Repo Feature Coherence
+
+Status: `Fail`
+
+Current surface:
+
+- units can list repos
+- no branch map
+- no PR grouping
+- no expected verification set
+
+Assessment:
+
+The workspace knows repo membership, but not feature coherence.
+
+### 9. Deterministic Status Surfaces
+
+Status: `Partial`
+
+Strength:
+
+- `plan` is deterministic for structural operations
+- `spec show/validate` exist
+
+Weakness:
+
+- no JSON/status model for repo state
+- no lane status
+- no execution status
+- no PR-linkage status
+
+Assessment:
+
+Structural visibility exists. Operational visibility does not.
+
+### 10. Multi-Repo Scratchpads
+
+Status: `Fail`
+
+Current surface:
+
+- only one implicit working context per unit path
+- no multiple scratchpads
+- no review or repro lanes
+
+Assessment:
+
+Current `gr2` cannot yet support the core workflow-switching use case.
+
+## Surface-Specific Findings
+
+### `args.rs`
+
+What exists:
+
+- `init`
+- `doctor`
+- `team`
+- `repo`
+- `unit`
+- `spec`
+- `plan`
+- `apply`
+
+Finding:
+
+The command surface is still structural/registry-heavy. There is no runtime
+surface for:
+
+- repo maintenance
+- lane management
+- execution
+- context
+
+### `dispatch.rs`
+
+Finding 1:
+
+`TeamCommands` and `UnitCommands` both materialize directories under `agents/`,
+but they represent different concepts (`agent.toml` vs `unit.toml`) without a
+clear higher-level model.
+
+Why this matters:
+
+- the rulebook needs unit home, lanes, context, and execution roots
+- the current split is likely to confuse future implementation if not unified
+
+Finding 2:
+
+`RepoCommands::Add` creates metadata directories immediately under `repos/`.
+That is acceptable for registration, but it mixes registry behavior with
+materialized path creation before a stronger lane/cache model exists.
+
+### `spec.rs`
+
+Finding 1:
+
+`WorkspaceSpec v1` is intentionally narrow, which is good.
+
+Finding 2:
+
+`WorkspaceSpec::from_workspace()` does not recover the richer intent needed for
+future lanes:
+
+- no branch map
+- no lane state
+- no context roots
+- no execution defaults
+
+Finding 3:
+
+`read_registered_units()` reconstructs units from directory presence and
+currently initializes `repos` as empty.
+
+Why this matters:
+
+- round-tripping from the filesystem loses intent
+- that is acceptable for bootstrap, but not for a durable lane workspace
+
+### `plan.rs`
+
+Finding 1:
+
+The current branch improved real gaps:
+
+- partially materialized unit repos are now detected
+- link planning exists
+- dirty nested repos are detected
+
+Finding 2:
+
+`materialize_unit()` clones repos directly into the unit path.
+
+This is acceptable for now, but it bypasses the future cache/lane model and
+will need refactoring once lanes become first-class.
+
+Finding 3:
+
+Dirty repo detection only considers repos inside units with planned operations.
+
+That is a reasonable apply guard, but it is not the same as a general
+repo-maintenance status surface.
+
+## Practical Gaps to Fix First
+
+### P0
+
+- `gr2 repo status`
+- lane metadata format
+
+These are the minimum requirements to make repo-state and lane-state legible.
+
+### P1
+
+- lane create/status/enter/remove
+- lane-aware execution
+
+These make the workspace usable for actual task switching.
+
+### P2
+
+- `lane checkout-pr`
+- explicit repo sync/pull/fetch surfaces
+
+These complete the review and maintenance story.
+
+## Conclusion
+
+Current `gr2` passes as a structural foundation and fails as a complete
+human/agent workspace.
+
+That is not a criticism of the implementation direction. It is the correct
+reading of where the surface is today.
+
+The good news is that the missing pieces are now sharply defined:
+
+- visibility
+- lane metadata
+- lane-aware execution
+- isolated review/scratch workflows
+
+Those are exactly the right next layers to build.
diff --git a/docs/MANIFESTO-gr2-ux.md b/docs/MANIFESTO-gr2-ux.md
new file mode 100644
index 00000000..315b4224
--- /dev/null
+++ b/docs/MANIFESTO-gr2-ux.md
@@ -0,0 +1,232 @@
+# gr2 UX Manifesto
+
+## Why `gr2` Exists
+
+Developers do not struggle because git is broken.
+
+They struggle because modern work is larger than one checkout:
+
+- one feature spans multiple repositories
+- one review interrupts another active task
+- one human works alongside multiple agents
+- one team needs both private work areas and lightweight shared collaboration
+
+`gr2` exists to make that multi-repo, multi-lane reality simpler, safer, and
+more legible.
+
+## Primary Thesis
+
+`gr2` is not a git replacement.
+
+`gr2` is a multi-repo workspace router.
+
+And for Synapt, it is more than that:
+
+- `gr2` is the workspace infrastructure layer
+- Synapt org shape should compile into `gr2`
+- channels, recall, and agent lanes should feel native to the workspace
+
+It should make it easy to:
+
+- start the right task context
+- see which repos and branches belong to that context
+- switch to another context without losing your place
+- review, collaborate, and execute work in the right scope
+
+Once the user is in the correct checkout, normal git should still feel normal.
+
+## User-First Principles
+
+### 1. The Primary Object Is The Task Context
+
+Users think:
+
+- "I am working on feature X"
+- "I need to review PR Y"
+- "I need a shared place to draft Z"
+
+They do not think:
+
+- "I need to manually coordinate three checkouts and remember which branch is
+  active in each one"
+
+So `gr2` must center:
+
+- feature lanes
+- review lanes
+- shared scratchpads
+
+Repos are part of the context. They are not the context.
+
+Shared repo caches may exist underneath `gr2`, but they are implementation
+substrate, not the user-facing place where work is expected to happen.
+
+### 2. Private Work And Shared Work Must Stay Separate
+
+Users need both:
+
+- private implementation surfaces
+- shared collaboration surfaces
+
+Private lanes protect active work.
+Shared scratchpads make lightweight collaboration possible without violating
+private workspace boundaries or paying the full cost of a PR.
+
+The system must make that distinction explicit.
+
+### 3. Use `gr2` To Choose Context, Use Git To Work
+
+The intended user flow is:
+
+1. use `gr2` to enter the correct lane or review context
+2. use git normally inside the selected checkout
+3. return to `gr2` when changing task, scope, or execution surface
+
+If `gr2` tries to replace normal repo-local git, users will distrust it.
+If `gr2` does not simplify multi-repo context changes, users will route around
+it.
+
+### 3a. Optimization Must Stay Behind The UX
+
+If `gr2 apply` uses shared local repo caches, mirrors, or `git clone
+--reference-if-able`, that should improve speed and disk use without changing
+the user mental model.
+
+Users should not need to understand cache topology to work effectively.
+
+### 4. The Tool Must Never Hide Important State
+
+Users should not have to guess:
+
+- which repos are in scope
+- which branches are intended
+- which paths are active
+- whether a command is structural or mutating
+- whether local work is at risk
+
+`gr2` should prefer explicit status over magical convenience.
+
+### 5. Safety Beats Cleverness
+
+`gr2 apply` must not silently:
+
+- pull
+- merge
+- rebase
+- switch branches
+- discard dirty work
+
+Users will trust `gr2` only if the safety boundary is simple and consistent:
+
+- structural convergence belongs to `apply`
+- repo maintenance belongs to explicit repo commands
+
+## Human UX Requirements
+
+A human should be able to:
+
+- keep feature A active while feature B waits in review
+- inspect PR C without disturbing either one
+- collaborate on a blog post or spec without editing another person's private
+  lane
+- tell, quickly, which repos matter for the current task
+- run the right build/test commands without reconstructing scope manually
+
+The human should not need to care whether a working checkout was materialized
+from:
+
+- a shared local mirror
+- a reference clone
+- a direct remote clone
+
+## Agent UX Requirements
+
+An agent should be able to:
+
+- discover the current task context quickly
+- consume stable machine-readable state
+- know which repos matter without guessing
+- avoid entering another worker's private directory
+- choose the right next command from explicit status surfaces
+
+The agent should be able to trust that optimization layers are invisible unless
+they matter for diagnosis or repair.
+
+This means structured output is not optional polish. It is first-class product
+surface.
+
+## Mixed Human + Agent Requirements
+
+The same model must work for:
+
+- a solo human
+- one agent
+- many agents
+- one human working alongside many agents
+
+That requires:
+
+- one shared vocabulary for lanes, review, and scratchpads
+- one shared status model
+- private lanes by default
+- shared collaboration surfaces when collaboration is the point
+- cache/materialization optimization that speeds up everyone without becoming a
+  new conceptual burden
+
+## Synapt-Native Integration Requirements
+
+`gr2` should work with Synapt out of the box.
+
+That means:
+
+- a Synapt-backed workspace should not treat channels, recall, or agent identity
+  as optional afterthoughts
+- a premium org/control-plane should compile into `WorkspaceSpec` and lane
+  policy rather than bypassing the workspace model
+- the local workspace should materialize the result of org, team, agent, and
+  access policy decisions without leaking premium-only control-plane semantics
+  into the wrong layer
+
+The user should be able to think:
+
+- "init the workspace"
+- "enter the right lane"
+- "use channels and recall in that workspace"
+
+without first assembling plugin wiring manually.
+
+## What Good Looks Like
+
+The user says:
+
+- "start feature auth across app and api"
+- "show me what this lane would run"
+- "open a review lane for PR 548"
+- "create a shared scratchpad for the sprint blog"
+- "switch back to my feature without losing my place"
+
+And the system responds with explicit, trustworthy state.
+
+That is the bar.
+
+## Product Test
+
+When choosing a `gr2` feature, ask:
+
+1. Does this make multi-repo context easier than ad hoc shell plus raw git?
+2. Does this preserve private work while allowing shared collaboration?
+3. Does this make the active task more legible?
+4. Does this reduce guessing for both humans and agents?
+5. Does this keep git normal once the user is in the correct checkout?
+6. Does this improve the Synapt workspace model instead of working around it?
+
+If the answer is not clearly yes, the design should be revised.
+
+The four user modes are not just examples. They are the product test:
+
+- solo human
+- single agent
+- multi-agent
+- mixed human + agent
+
+If a surface works for only one of them, it is not finished.
diff --git a/docs/PLAN-gr2-needs-and-criteria.md b/docs/PLAN-gr2-needs-and-criteria.md
new file mode 100644
index 00000000..a620dee7
--- /dev/null
+++ b/docs/PLAN-gr2-needs-and-criteria.md
@@ -0,0 +1,607 @@
+# gr2 Needs and Criteria Rulebook
+
+## Purpose
+
+This document is the comprehensive criteria set for a first-class `gr2`
+workspace that must work for:
+
+- a solo human working across many repos
+- multiple agents working in parallel
+- mixed human + agent teams
+
+It is not a feature wishlist. It is the rulebook for what the workspace must
+be able to do without unsafe workarounds.
+
+For Synapt, `gr2` is the workspace infrastructure layer, not just a helper
+around multi-repo git state.
+
+## Primary Design Principle
+
+The workspace unit is not a single repo checkout.
+
+The workspace unit is:
+
+- a named lane
+- a selected repo set
+- a branch/PR context
+- a context bundle
+- an execution surface
+
+If `gr2` gets that right, humans and agents can work safely in parallel.
+If it gets that wrong, users will fall back to ad hoc worktrees, raw git, and
+hidden state.
+
+## Tool Boundary Principle
+
+`gr2` is not a replacement for git.
+
+`gr2` should be the first-class surface for multi-repo workspace routing.
+Git should remain the first-class surface for normal repo-local work inside a
+chosen checkout.
+
+If that boundary gets blurred, users and agents will distrust the system for
+opposite reasons:
+
+- if `gr2` does too much, it feels magical and unsafe
+- if `gr2` does too little, users will ignore it and fall back to ad hoc shell
+
+So the system must make this split legible.
+
+## Synapt Infrastructure Principle
+
+`gr2` should be the local workspace substrate that Synapt compiles into.
+
+That means:
+
+- premium org shape compiles into `WorkspaceSpec` and lane policy
+- local workspaces materialize teams, agents, repo scope, and context surfaces
+- channels, recall, and agent lanes should feel native to the workspace model
+
+This is still compatible with the local-first split:
+
+- premium owns org identity, policy, entitlements, and coordination semantics
+- `gr2` owns local workspace materialization and lane execution surfaces
+
+But the user experience should feel integrated rather than patched together.
+
+### `gr2` Must Own
+
+- lane selection and switching
+- review-lane setup
+- shared scratchpads
+- multi-repo status and scope
+- structural workspace planning and apply
+- lane-aware execution planning
+
+### Git Must Still Own
+
+- repo-local `status`, `diff`, `log`
+- staging and committing
+- normal branch work inside one checkout
+- low-level recovery when a user is already in the correct repo
+
+### User Decision Rule
+
+The default user rule should be:
+
+1. use `gr2` to get into the right workspace context
+2. use git to work inside that chosen repo checkout
+3. return to `gr2` when changing context, scope, or execution surface
+
+## User Modes
+
+`gr2` must support all of these without changing its core model.
+
+### Solo Human
+
+The user needs to:
+
+- work across multiple repos as one feature
+- review another PR without disturbing that feature
+- start a second feature while the first waits on review
+- run build/test/verify for the active multi-repo lane
+- know when to use raw git versus `gr2` without second-guessing
+
+The solo human should not need to understand or manage a shared repo cache.
+If clone acceleration exists, it should feel like faster materialization, not a
+second workspace concept.
+
+### Single Agent
+
+The agent needs to:
+
+- discover the correct workspace context quickly
+- understand which repos matter for the task
+- branch and execute commands without guessing
+- report deterministic status
+- avoid clobbering unrelated work
+- prefer the workspace primitives over ad hoc raw git when the task is multi-repo
+
+The agent should receive explicit status about active working checkouts, not be
+forced to reason about cache internals unless a clone/materialization problem
+actually occurs.
+
+### Multi-Agent Team
+
+The team needs to:
+
+- isolate active work per unit
+- share durable context where appropriate
+- preserve private context where appropriate
+- coordinate across linked PRs and sprint lanes
+- switch between tasks without contaminating each other's state
+- avoid entering each other's private directories just to collaborate
+
+The team should benefit from shared clone acceleration, but the optimization
+must not weaken private-workspace boundaries or turn `repos/<repo>` into a
+confusing second place where work might be happening.
+
+### Mixed Human + Agent
+
+The mixed mode is a primary operating mode, not a special case.
+
+The workspace needs to let a human and an agent collaborate without either of
+them needing to enter the other's private lane just to get work done.
+
+That requires:
+
+- private implementation lanes
+- shared scratchpads for lightweight collaboration
+- isolated review lanes
+- status surfaces that work for both humans and machines
+
+## Hard Requirements
+
+### 1. Structural and Repo-State Separation
+
+`gr2 apply` must remain structural only.
+
+It may:
+
+- create directories
+- materialize missing repos
+- attach repos into units
+- converge partially-materialized lanes
+- write metadata
+
+It must not silently:
+
+- pull
+- merge
+- rebase
+- switch active branches
+- discard or obscure dirty work
+
+This is the most important safety boundary in the system.
+
+### 2. Named Multi-Repo Lanes
+
+The system must support named lanes as first-class objects.
+
+Each lane must support:
+
+- a repo set
+- a branch map
+- PR associations
+- context roots
+- execution defaults
+- a lane type
+
+Required lane types:
+
+- `home`
+- `feature`
+- `review`
+- `scratch`
+
+### 3. Cheap Parallelism
+
+Lane creation must be cheap enough that users do not avoid it.
+
+That implies:
+
+- shared cache for repo sources
+- selective lane repo membership
+- fast materialization from cache
+- disposable review lanes
+
+If lane creation is slow or expensive, users will bypass the model.
+
+The cache is an implementation detail. The UX object remains the lane.
+
+### 4. Shared and Private Context
+
+The workspace must support two context scopes:
+
+- shared workspace context
+- unit-private context
+
+Shared context must be durable and visible to all relevant workers.
+Private context must not be treated as common workspace state.
+
+Lane context should inherit both:
+
+- shared workspace context
+- unit-private context
+- optional lane-local additions
+
+### 5. Lane-Aware Execution
+
+The workspace must provide lane-aware execution for:
+
+- build
+- test
+- lint
+- run
+- verify
+
+Execution must be scoped by:
+
+- lane
+- repo selection
+- order/parallelism policy
+- fail-fast or collect-all policy
+
+If execution remains global, the lane model is incomplete.
+
+### 6. Dirty Work Preservation
+
+The system must never silently discard local modifications.
+
+Required behaviors:
+
+- detect dirty work explicitly
+- block by default
+- allow explicit preservation mode
+- log preservation/recovery actions
+- surface failed restore clearly
+
+Autostash is acceptable only as an explicit preservation mechanism.
+
+### 7. PR and Review Isolation
+
+Users must be able to check out a PR without disturbing active feature work.
+
+That means:
+
+- PR checkout creates or updates a review lane
+- review lanes are disposable
+- review lanes can run their own commands
+- review lanes do not mutate the current feature lane
+
+### 8. Cross-Repo Feature Coherence
+
+A cross-repo feature must be representable as one lane record, not merely
+several repos that happen to share a branch name.
+
+The lane must know:
+
+- included repos
+- per-repo branch intent
+- associated PRs
+- expected verification commands
+
+### 9. Deterministic Status Surfaces
+
+Agents and humans need trustworthy read surfaces.
+
+`gr2` must provide explicit status views for:
+
+- workspace structural drift
+- repo sync drift
+- lane metadata
+- dirty state
+- execution status
+- PR linkage
+
+Cache or transport state should only surface when it affects the user's ability
+to materialize or repair a lane.
+
+These should be machine-readable as well as human-readable.
+
+### 9a. Structured Output Must Be First-Class
+
+Machine-readable output should not be treated as an optional afterthought.
+
+Agents routinely need:
+
+- stable field names
+- stable object shapes
+- deterministic exit codes
+- explicit next-step hints
+
+### 10. Materialization Optimization Must Not Become A Second UX Model
+
+`gr2 apply` may use shared local mirrors or reference clones as its materialization
+substrate.
+
+That is desirable for:
+
+- speed
+- disk reuse
+- cheap review lanes
+- adoptability on large workspaces
+
+But the optimization must not become a user-facing mental model.
+
+Required rule:
+
+- users work in unit-local or lane-local checkouts
+- `.grip/cache/repos/` is infrastructure
+- status surfaces should describe active working checkouts first
+
+If the design makes users reason about shared cache topology during normal work,
+the UX has failed.
+- explicit scope metadata
+
+So every status-style surface should support structured output as a first-class
+mode, not a best-effort pretty-print after the human CLI is finished.
+
+Required properties:
+
+- all read surfaces support structured output
+- structured output is versioned
+- field names are stable across patch releases
+- error output is also structured when structured mode is enabled
+- command scope is explicit in the payload
+
+Examples of required structured surfaces:
+
+- `gr2 spec show`
+- `gr2 plan`
+- `gr2 repo status`
+- `gr2 lane list`
+- `gr2 lane show`
+- `gr2 exec status`
+
+The target user problem is simple:
+
+- agents should not have to scrape prose
+- humans should not lose readable output by default
+
+### 10. Strong UX Guidance
+
+The product must teach the user which surface to use.
+
+That means:
+
+- CLI help must state command scope clearly
+- status output should suggest likely next steps
+- docs should include "use `gr2` for this, use git for that"
+- common workflows should be expressed as short procedural paths
+- structured output should be easy to enable and hard to forget
+
+### 11. Multi-Repo Scratchpads
+
+The system must support two or more temporary scratchpads simultaneously.
+
+Examples:
+
+- a feature lane
+- a review lane
+- a reproduction lane
+- a release lane
+
+This is not optional convenience. It is necessary for real workflow switching.
+
+## Command-Surface Criteria
+
+### Spec Surface
+
+The user must be able to inspect and validate workspace intent without mutating
+repo state.
+
+Required surfaces:
+
+- `gr2 spec show`
+- `gr2 spec validate`
+- later: `gr2 spec diff`, `gr2 spec explain`
+
+### Structural Surface
+
+The user must be able to preview and apply structural workspace changes.
+
+Required surfaces:
+
+- `gr2 plan`
+- `gr2 apply`
+
+### Repo-Maintenance Surface
+
+The user must be able to inspect and update repo state explicitly.
+
+Required surfaces:
+
+- `gr2 repo status`
+- `gr2 repo fetch`
+- `gr2 repo sync`
+- `gr2 repo checkout`
+
+This surface must remain explicit enough that users do not confuse it with
+plain repo-local git operations.
+
+### Lane Surface
+
+The user must be able to manage lanes directly.
+
+Required surfaces:
+
+- `gr2 lane list`
+- `gr2 lane create`
+- `gr2 lane status`
+- `gr2 lane enter`
+- `gr2 lane remove`
+- `gr2 lane branch`
+- `gr2 lane checkout-pr`
+
+### Execution Surface
+
+The user must be able to run multi-repo commands against a lane.
+
+Required surfaces:
+
+- `gr2 exec status`
+- `gr2 exec run`
+- `gr2 exec test`
+- `gr2 exec build`
+
+### Context Surface
+
+The user must be able to inspect and manage effective context.
+
+Required surfaces:
+
+- `gr2 context show`
+- `gr2 context shared edit`
+- `gr2 context unit edit`
+
+## Metadata Criteria
+
+### Workspace Metadata
+
+The workspace must persist:
+
+- workspace identity
+- spec version
+- cache location
+- repo registry
+- unit registry
+
+### Lane Metadata
+
+Every lane must persist:
+
+- lane id
+- lane name
+- owner unit
+- lane type
+- included repos
+- branch map
+- PR associations
+- creation source
+- context roots
+- execution defaults
+- recovery state
+
+### Recovery Metadata
+
+The workspace must persist enough state to explain and recover from:
+
+- autostash actions
+- failed restore
+- interrupted sync/apply
+- partially materialized lanes
+
+## Agent-Specific Criteria
+
+### Discoverability
+
+An agent entering the workspace must be able to determine:
+
+- what lane it is in
+- what repos belong to that lane
+- what commands are relevant
+- what shared context applies
+- what private context applies
+
+without scraping ambiguous terminal output.
+
+### Isolation
+
+An agent must not need to infer which directories are safe to touch.
+
+The workspace structure should make it obvious:
+
+- shared context
+- private unit roots
+- lane-local checkouts
+
+### Deterministic Automation
+
+An agent must not have to guess whether:
+
+- a merge succeeded
+- a lane switched correctly
+- a repo is safe to update
+- a command should run in all repos or only some repos
+
+This implies strong status and JSON-capable output surfaces.
+
+## Human-Specific Criteria
+
+### Low Ceremony
+
+Humans should not need to think in terms of internal metadata to do common work.
+
+The happy path should feel like:
+
+- create lane
+- switch into lane
+- branch it
+- run tests
+- open PR
+- switch to another lane
+
+### Recoverability
+
+When something goes wrong, the user must be able to answer:
+
+- what lane am I in
+- what repos are dirty
+- what did the tool change
+- where is my preserved work
+- how do I get back to the prior state
+
+## Criteria for Success
+
+The design is successful if a user can do all of the following without raw git
+or manual directory gymnastics:
+
+1. Start a cross-repo feature in three repos.
+2. Open linked PRs for that feature.
+3. Leave the feature intact while it waits on review.
+4. Check out another PR in a disposable review lane.
+5. Start a second feature in a different lane.
+6. Run build/test only for the correct lane and repo set.
+7. Preserve dirty work safely while switching or syncing.
+8. Return to the original feature lane and continue editing.
+9. Do the same with two or more agents working simultaneously.
+
+## Failure Criteria
+
+The design has failed if users still need to rely on:
+
+- ad hoc raw git worktrees across multiple repos
+- hidden global sync behavior
+- ambiguous context files
+- manual stash/recovery folklore
+- guessing which repo set a command should operate on
+- chat memory instead of workspace state
+
+## Implementation Priority
+
+Build against this criteria set in this order:
+
+1. narrow `apply`
+2. `gr2 repo status`
+3. lane metadata
+4. `gr2 lane create/status/enter/remove`
+5. `gr2 exec` lane-aware command surface
+6. `gr2 lane checkout-pr`
+7. `gr2 repo sync` with explicit preservation policy
+8. richer context tooling
+
+## Bottom Line
+
+The bar for `gr2` is not "better multi-repo git commands."
+
+The bar is:
+
+- a trustworthy multi-repo operating system for humans and agents
+- explicit context
+- explicit execution
+- explicit parallel work surfaces
+- explicit recovery
+
+That is the criteria rulebook. Any `gr2` design or implementation should be
+judged against it.
diff --git a/docs/PLAN-gr2-repo-maintenance-and-lanes.md b/docs/PLAN-gr2-repo-maintenance-and-lanes.md
new file mode 100644
index 00000000..0dab62ef
--- /dev/null
+++ b/docs/PLAN-gr2-repo-maintenance-and-lanes.md
@@ -0,0 +1,694 @@
+# gr2 Repo Maintenance and Lanes
+
+## Problem
+
+`gr` taught us two useful things:
+
+1. multi-repo work is real, not edge-case behavior
+2. hiding repo coordination behind one broad `sync` surface creates avoidable confusion
+
+The current pain points are consistent:
+
+- manifest intent, file projection, and repo mutation are too entangled
+- switching from one feature to another is too global
+- reviewing a PR while keeping local feature work alive is awkward
+- agents need more isolation than shared worktrees provide
+- humans need less ceremony than a full fresh workspace for every task
+
+We need `gr2` to be a first-class multi-repo workspace for both:
+
+- a solo human working across several repos
+- multiple agents working in parallel without stepping on each other
+
+The workspace model needs to support:
+
+- one feature spanning three repos
+- a second feature starting while the first is in review
+- checking out a PR without disturbing ongoing work
+- keeping repo state explicit and recoverable
+- preserving dirty local work by default
+- shared team context plus unit-specific private context
+- multi-repo build, test, and command execution scoped to a lane
+
+And it must hold under adversarial cross-mode pressure:
+
+- solo human recovery after interruption
+- single-agent context switching
+- multi-agent same-repo parallelism
+- mixed human + agent conflict handling
+
+## Design Goals
+
+- make workspace intent explicit
+- make repo state transitions explicit
+- make parallel work cheap
+- make review and temporary work cheap
+- preserve local modifications safely
+- keep agent and human behavior on the same primitives
+- avoid hidden pull/merge/rebase side effects
+- make shared context and unit-private context explicit
+- make multi-repo execution lane-aware
+
+The lane model should be validated with the cross-mode matrix in
+`ASSESS-gr2-lanes-cross-mode-stress.md`, not only by per-mode happy paths.
+
+## Non-Goals
+
+- `gr2 apply` is not a global "make it all right somehow" button
+- `WorkspaceSpec v1` is not the place for full org/policy/runtime state
+- shared repos and active feature sandboxes should not be conflated
+
+## Core Split
+
+`gr2` should separate three concerns.
+
+### 1. Workspace Intent
+
+`WorkspaceSpec` declares:
+
+- which repos exist
+- where they live
+- which units use which repos
+- basic workspace topology
+
+This is the durable declarative layer.
+
+### 2. Structural Convergence
+
+`gr2 apply` should do only structural work:
+
+- create missing directories
+- materialize missing repo checkouts
+- attach repos into units
+- converge partially materialized units
+- write unit metadata
+
+It should not silently:
+
+- pull from remotes
+- merge branches
+- rebase local work
+- switch active branches unexpectedly
+
+Materialization may use a shared cache or local mirror under `.grip/cache/repos`
+to accelerate clone/setup.
+
+That is an implementation strategy, not a separate workspace surface.
+
+### 3. Repo Maintenance
+
+Repo maintenance should be an explicit surface above structural apply:
+
+- fetch
+- fast-forward
+- branch correction
+- PR checkout
+- autostash-based preservation
+- divergence handling
+
+That should become a separate command family, not hidden inside `apply`.
+
+## Proposed Workspace Model
+
+The workspace should have three layers:
+
+```text
+<workspace>/
+├── .grip/
+│   ├── workspace_spec.toml
+│   ├── state/
+│   └── cache/
+│       └── repos/
+├── config/
+├── repos/
+│   └── <shared checkouts>
+├── agents/
+│   └── <unit>/
+│       ├── unit.toml
+│       ├── home/
+│       └── lanes/
+│           ├── <lane-a>/
+│           │   └── repos/
+│           └── <lane-b>/
+│               └── repos/
+└── scratch/
+    └── <review-or-throwaway-lanes>
+```
+
+### Shared Cache
+
+`.grip/cache/repos/` stores reusable repo sources or mirrors.
+
+This is the acceleration layer:
+
+- fetch once
+- materialize many
+- cheap temporary sandboxes
+- reference-clone substrate for `apply`
+
+The likely implementation path is:
+
+- maintain a shared local mirror/cache under `.grip/cache/repos/`
+- materialize unit/lane working clones from that cache with
+  `git clone --reference-if-able` or equivalent
+
+This should improve adoptability on large workspaces without introducing a new
+user-facing concept.
+
+### `repos/` Is Not The Primary Working Surface
+
+The real-git prototype currently shows that active work materializes under
+`agents/<unit>/...`, not under `repos/<repo>`.
+
+That should be treated as the primary UX model unless the implementation
+changes substantially.
+
+So:
+
+- `repos/` should not be presented as where users normally work
+- shared repo state belongs in cache/infrastructure unless a concrete UX need
+  emerges
+- unit-local and lane-local checkouts are the places users and agents actually
+  operate
+
+### Unit Home
+
+`agents/<unit>/home/` is the stable home lane for a person or agent.
+
+This is where "my normal work" lives when not split into a feature lane.
+
+### Lanes
+
+A lane is a multi-repo scratchpad.
+
+A lane contains:
+
+- a selected set of repos
+- a branch map
+- local dirtiness state
+- lane-local checkout paths
+- review metadata if it came from a PR
+- shared and private context references
+- execution defaults for build/test/run commands
+
+This is the multi-repo equivalent of a worktree, but not tied to git's
+single-repo worktree mechanism.
+
+For UX purposes, the important distinction is:
+
+- cache and reference clones exist to make lanes cheap
+- lanes are still the thing the user thinks in
+
+## Context Model
+
+The workspace needs two context scopes.
+
+### Shared Context
+
+Shared context is visible to everyone in the workspace:
+
+- workspace instructions
+- shared prompts
+- release plan
+- shared notes and decisions
+- cross-repo task state
+
+This should live in stable workspace-managed locations such as:
+
+- `config/`
+- `.grip/context/shared/`
+
+This is the context a human or agent should inherit by default when entering
+the workspace or a lane.
+
+### Unit-Private Context
+
+Each unit needs private context that is not treated as shared scratch space:
+
+- local notes
+- pending ideas
+- temporary debugging context
+- agent-specific reminders
+- local execution state
+
+This should live under the unit root, not in shared workspace state:
+
+- `agents/<unit>/home/context/`
+- `agents/<unit>/lanes/<lane>/context/`
+
+The rule should be:
+
+- shared context is workspace-owned
+- private context is unit-owned
+- lane context inherits both, but may add lane-local notes
+
+That gives us the right behavior for both humans and agents:
+
+- the team can share durable operational context
+- each worker can keep private working memory without trampling others
+
+## Execution Model
+
+The workspace also needs a first-class multi-repo execution surface.
+
+Users need to run:
+
+- builds
+- tests
+- linters
+- migrations
+- verification commands
+
+across a selected repo set, inside a selected lane.
+
+### Why This Matters
+
+If lane management exists but execution stays global, users will still be
+forced back into the old failure mode:
+
+- wrong branch
+- wrong checkout
+- wrong repo subset
+- wrong temporary context
+
+So command execution must be lane-aware.
+
+### Proposed Execution Commands
+
+```bash
+gr2 exec status
+gr2 exec run <command>
+gr2 exec test
+gr2 exec build
+```
+
+Each execution should be scoped by:
+
+- lane
+- repo selection
+- execution order or parallelism policy
+- fail-fast vs collect-all behavior
+
+Examples:
+
+```bash
+gr2 exec test --lane feat-auth
+gr2 exec run --lane review-541 --repo grip 'cargo test'
+gr2 exec build --lane feat-billing --repos app,api
+```
+
+### Execution Metadata
+
+Each lane should be able to record:
+
+- default repo set
+- default working directory per repo
+- common scripts or commands
+- last known successful verification set
+
+This should not be a hidden shell convention. It should be lane metadata.
+
+## Lane Metadata
+
+The lane record should be explicit and durable.
+
+At minimum it should contain:
+
+- lane name
+- owner unit
+- lane type: `home`, `feature`, `review`, `scratch`
+- included repos
+- branch map per repo
+- PR associations
+- context roots
+- execution defaults
+- creation source
+- dirty/autostash recovery state
+
+That metadata is what makes lane switching trustworthy.
+
+Without it, `gr2` would just be managing directories and hoping the user
+remembers what each one is for.
+
+## Why Lanes Instead of Plain Worktrees
+
+Git worktrees are repo-local. Our problem is workspace-wide.
+
+One feature often means:
+
+- repo A on `feat/x`
+- repo B on `feat/x`
+- repo C on `feat/x`
+
+and the user wants that set to behave as one working context.
+
+So the first-class unit is not "a checkout of one repo".
+It is:
+
+- one named lane
+- one set of repos
+- one branch intent
+- one local review/edit surface
+
+## User Flows
+
+### 1. Solo Human, One Cross-Repo Feature
+
+User wants to work on a feature spanning `app`, `api`, and `shared`.
+
+```bash
+gr2 lane create feat-auth --repos app,api,shared
+gr2 lane branch feat-auth --name feat/auth
+gr2 lane enter feat-auth
+```
+
+Now the user has one isolated multi-repo context.
+
+### 2. Start Another Feature While the First Is in Review
+
+The first feature is open in PR and waiting on review.
+User wants to start a second feature without disturbing it.
+
+```bash
+gr2 lane create feat-billing --repos app,api
+gr2 lane branch feat-billing --name feat/billing
+gr2 lane enter feat-billing
+```
+
+The first lane stays intact. The second lane starts from cache-backed clones.
+
+### 3. Check Out a PR While Keeping Your Own Work
+
+User needs to review or patch someone else's PR while keeping their own lane.
+
+```bash
+gr2 lane checkout-pr review-541 --repo grip --pr 541
+gr2 lane enter review-541
+```
+
+This should create a separate review lane. It must not disturb the user's
+feature lane or home lane.
+
+### 4. Agent Parallelism
+
+Atlas is working on `feat-a`. Apollo is working on `feat-b`.
+Both need isolated multi-repo state.
+
+They should each have:
+
+- private unit roots
+- private lanes
+- shared cache
+
+That gives:
+
+- low duplication where safe
+- no checkout collisions
+- no "another agent changed my branch" failures
+
+### 5. Temporary Scratchpads
+
+Yes, we should explicitly support two or more temporary scratchpads.
+
+Examples:
+
+- a feature lane
+- a review lane
+- a reproduction lane for a bug
+
+Those should all be first-class, cheap, and disposable.
+
+## Repo Maintenance Model
+
+The prototype suggests this action taxonomy:
+
+- `clone_missing`
+- `block_path_conflict`
+- `block_dirty`
+- `autostash_then_sync`
+- `checkout_branch`
+- `fast_forward`
+- `manual_sync`
+- `no_change`
+
+This is the right design direction because it makes repo state legible.
+
+### Shared Repo Defaults
+
+Shared repos can default to stricter automation:
+
+- fetch allowed
+- fast-forward allowed when clean
+- branch correction allowed when no local work exists
+
+### Lane Repo Defaults
+
+Lane repos should be more conservative:
+
+- no automatic branch movement
+- no automatic merge/rebase
+- stop when dirty unless explicit preservation is requested
+
+This is the right default because lanes are where active work lives.
+
+## Proposed Commands
+
+### Structural
+
+```bash
+gr2 spec show
+gr2 spec validate
+gr2 plan
+gr2 apply
+```
+
+### Repo Maintenance
+
+```bash
+gr2 repo status
+gr2 repo sync
+gr2 repo fetch
+gr2 repo pull
+gr2 repo checkout
+```
+
+### Lane Management
+
+```bash
+gr2 lane list
+gr2 lane create <name>
+gr2 lane enter <name>
+gr2 lane leave
+gr2 lane remove <name>
+gr2 lane branch <lane> --name <branch>
+gr2 lane checkout-pr <lane> --repo <repo> --pr <num>
+gr2 lane status [<lane>]
+```
+
+### Context
+
+```bash
+gr2 context show [--lane <lane>]
+gr2 context shared edit
+gr2 context unit edit [--lane <lane>]
+```
+
+### Execution
+
+```bash
+gr2 exec status [--lane <lane>]
+gr2 exec run --lane <lane> [--repo <repo>] <command>
+gr2 exec test --lane <lane>
+gr2 exec build --lane <lane>
+```
+
+## Branch and PR Behavior
+
+### Branch Switching
+
+Branch switching should be lane-local, not workspace-global.
+
+If the user is in lane `feat-auth`, then:
+
+```bash
+gr2 lane branch feat-auth --name feat/auth
+```
+
+means:
+
+- create or check out `feat/auth` across the repos in that lane
+- do not disturb repos outside that lane
+
+### PR Checkout
+
+Checking out a PR should create or update a review lane.
+
+That review lane should record:
+
+- source repo
+- PR number
+- branch/ref used
+- whether it is disposable
+
+### Linked Cross-Repo Features
+
+A feature spanning three repos should have one lane record that knows:
+
+- which repos are included
+- what branch each repo should be on
+- which PRs belong to that lane
+- what shared and private context applies there
+- what the expected verification commands are
+
+That is the real unit of work. Not "three separate branches that happen to
+share a name."
+
+## Relationship to `gr`
+
+`gr` already has the right lessons:
+
+- linked PRs matter
+- synchronized branch flows matter
+- atomic merge intent matters
+- manifest-driven workspaces matter
+
+But `gr` still carries too much global behavior.
+
+`gr2` should keep the good parts and change the operating unit:
+
+- from global repo sync
+- to explicit workspace intent + lane-local repo maintenance
+
+## Why This Should Hold Up Under Scrutiny
+
+This design holds up if we enforce these rules:
+
+### 1. `apply` stays narrow
+
+If `apply` starts pulling, merging, rebasing, and switching branches, the model
+collapses back into hidden side effects.
+
+This rule is non-negotiable.
+
+### 2. Lanes are cheap
+
+If creating a lane feels expensive, people will go back to mutating one shared
+workspace and the safety model will fail.
+
+That means:
+
+- shared cache
+- fast materialization
+- minimal ceremony
+
+### 3. Lane state is explicit
+
+Every lane needs durable metadata:
+
+- included repos
+- branch map
+- PR associations
+- creation source
+- dirty/preserved state
+- context roots
+- execution defaults
+
+If lane state is inferred ad hoc from the filesystem, users will not trust it.
+
+### 4. Dirty-worktree handling is visible
+
+Autostash is useful, but it is dangerous if hidden.
+
+The system must record:
+
+- stash creation
+- target repo
+- restore attempt
+- restore failure
+
+### 5. Shared repos and active work stay separate
+
+If shared baseline repos and live feature repos share too much behavior, users
+will be surprised by sync results.
+
+### 6. PR workflows are first-class
+
+If checking out a PR is treated as a second-class hack, users will keep opening
+ad hoc worktrees and the multi-repo abstraction will fracture.
+
+### 7. Shared and private context stay separate
+
+If unit-private context leaks into shared context, agents will step on each
+other and humans will stop trusting the workspace.
+
+### 8. Execution is lane-aware
+
+If build/test/run commands are not scoped to lanes, users will still make the
+wrong changes in the wrong place and the workspace model will feel fake.
+
+## Risks
+
+### Disk Usage
+
+Multiple lanes mean more checkouts.
+
+Mitigation:
+
+- shared cache
+- sparse lane repo selection
+- disposable review lanes
+
+### Metadata Complexity
+
+Lane metadata, branch maps, and PR associations can get messy.
+
+Mitigation:
+
+- durable lane manifest/state
+- explicit commands
+- strong status surfaces
+
+### Too Many Abstractions
+
+If we introduce `spec`, `apply`, `repo`, `lane`, `cache`, and `pr` without clear
+boundaries, the UX will feel over-engineered.
+
+Mitigation:
+
+- keep the command split simple
+- optimize the happy path
+- document when to use each surface
+
+## Practical Recommendation
+
+Build `gr2` in this order:
+
+1. finish narrow `apply`
+2. add `gr2 repo status` using the prototype action taxonomy
+3. define lane metadata format, including context and execution defaults
+4. add `gr2 lane create/status/enter/remove`
+5. add `gr2 lane branch`
+6. add lane-aware `gr2 exec` surfaces for build/test/run
+7. add `gr2 lane checkout-pr`
+8. add `gr2 repo sync` with explicit policy and autostash logging
+
+## Bottom Line
+
+Yes, `gr2` should support two temporary scratchpads and more.
+
+That is not optional polish. It is the core answer to:
+
+- human multi-repo feature work
+- agent parallelism
+- review without disruption
+- switching features while another waits in PR
+
+The right foundation is:
+
+- declarative workspace spec
+- narrow structural apply
+- explicit repo maintenance
+- cheap named lanes as multi-repo scratchpads
+
+That is meaningfully better than `gr`, and it uses the actual lessons we
+already paid to learn.
diff --git a/docs/PLAN-gr2-shared-scratchpads.md b/docs/PLAN-gr2-shared-scratchpads.md
new file mode 100644
index 00000000..7d8b0332
--- /dev/null
+++ b/docs/PLAN-gr2-shared-scratchpads.md
@@ -0,0 +1,147 @@
+# gr2 Shared Scratchpads
+
+## Problem
+
+Private lanes are the right default for implementation work, but they leave a
+collaboration gap:
+
+- a PR is too heavy for early drafting
+- another worker's private directory is the wrong place for joint editing
+- ad hoc shared files have weak ownership and poor lifecycle
+
+The blog workflow is the clearest example. Multiple workers may need to draft,
+review, and refine shared content before anyone wants a formal PR.
+
+## User Need
+
+"I need a lightweight shared place to collaborate without crossing into someone
+else's private workspace and without paying the full cost of a PR."
+
+## Principle
+
+Shared scratchpads are a sibling to private lanes, not an exception to them.
+
+- private lanes stay private
+- shared scratchpads are explicit shared workspace objects
+- both should be cheap
+- both should be inspectable
+
+## First Slice
+
+The first slice should be doc-first.
+
+That keeps the initial surface focused on the actual pain:
+
+- blogs
+- RFCs
+- release notes
+- planning docs
+
+It avoids turning "shared scratchpad" into an excuse for ambiguous shared code
+ownership too early.
+
+## Proposed Model
+
+```text
+<workspace>/
+├── agents/
+│   └── <unit>/
+│       └── lanes/
+│           └── ...
+└── shared/
+    └── scratchpads/
+        └── <name>/
+            ├── scratchpad.toml
+            ├── docs/
+            ├── notes/
+            └── context/
+```
+
+## Scratchpad Metadata
+
+Each shared scratchpad should record:
+
+- name
+- kind
+- purpose
+- participants
+- linked issue / PR if any
+- lifecycle state
+- creation source
+- default paths
+
+Suggested kinds for the first pass:
+
+- `doc`
+- `review`
+- `planning`
+
+Suggested lifecycle states:
+
+- `draft`
+- `active`
+- `paused`
+- `done`
+
+## Rules
+
+Shared scratchpads should:
+
+- be workspace-owned
+- support multiple named participants
+- make purpose explicit
+- be easy to create and remove
+- stay separate from private implementation lanes
+
+Shared scratchpads should not:
+
+- replace private feature lanes
+- become the default place for multi-repo coding
+- weaken the "do not enter someone else's private directory" rule
+
+## UX Goals
+
+The user should be able to:
+
+1. create a shared scratchpad quickly
+2. see who it is for
+3. see what it is for
+4. know whether it is still active
+5. know what to do next
+
+That implies explicit read surfaces:
+
+- list scratchpads
+- show one scratchpad
+- audit stale or orphaned scratchpads
+- plan promotion into a repo artifact
+- suggest next step
+
+## Prototype Goal
+
+The prototype should answer:
+
+- does a doc-first shared scratchpad actually reduce coordination friction?
+- does the metadata feel sufficient?
+- do users understand when to use a scratchpad instead of a PR or private lane?
+- does this preserve the private-workspace safety model?
+- can the tool help the user choose between scratchpad, review lane, feature lane,
+  and PR without guesswork?
+- can the tool surface stale or weakly tracked scratchpads before they become
+  clutter or coordination debt?
+- can the tool show a clear graduation path from scratchpad to repo artifact?
+
+## Verification Gate
+
+This prototype is only considered verified if it survives the adversarial
+scenarios in:
+
+- `docs/ASSESS-gr2-shared-scratchpads-stress.md`
+
+That includes pressure around:
+
+- concurrency
+- stale state
+- wrong-surface use
+- lifecycle and cleanup
+- graduation from scratchpad to real repo artifact / PR
diff --git a/gr2/Cargo.toml b/gr2/Cargo.toml
new file mode 100644
index 00000000..6ed9e813
--- /dev/null
+++ b/gr2/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "gr2-cli"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+name = "gr2_cli"
+path = "src/lib.rs"
+
+[dependencies]
+anyhow = "1"
+chrono = { version = "0.4", features = ["serde"] }
+clap = { version = "4", features = ["derive"] }
+serde = { version = "1", features = ["derive"] }
+toml = "0.8"
diff --git a/gr2/prototypes/README.md b/gr2/prototypes/README.md
new file mode 100644
index 00000000..8e8fb5d3
--- /dev/null
+++ b/gr2/prototypes/README.md
@@ -0,0 +1,413 @@
+# gr2 Repo Maintenance + Collaboration Prototypes
+
+This prototype explores a split between:
+
+- `gr2 apply`
+  - structural workspace convergence
+  - create/mount missing repo paths
+  - write unit metadata
+- repo maintenance
+  - fetch, fast-forward, branch correction, dirty-worktree handling
+
+## Why it exists
+
+`WorkspaceSpec v1` is intentionally narrow. It tells us which repos should
+exist and where they should live, but it does not yet define full collaboration
+policy for:
+
+- when to pull
+- when to fast-forward
+- when to refuse because a repo is dirty
+- when autostash is allowed
+- when a branch mismatch is safe to correct automatically
+
+The prototype keeps those decisions explicit instead of burying them inside
+`gr2 apply`.
+
+## Command
+
+```bash
+python3 gr2/prototypes/repo_maintenance_prototype.py /path/to/workspace
+```
+
+Optional policy file:
+
+```bash
+python3 gr2/prototypes/repo_maintenance_prototype.py \
+  /path/to/workspace \
+  --policy /path/to/repo_policy.toml
+```
+
+## Example policy
+
+```toml
+[defaults]
+tracked_branch = "main"
+shared_sync = "ff-only"
+unit_sync = "explicit"
+dirty = "block"
+
+[repos.grip]
+dirty = "autostash"
+```
+
+## Current behavior
+
+The planner classifies each shared repo and each unit-mounted repo into actions
+such as:
+
+- `clone_missing`
+- `fast_forward`
+- `checkout_branch`
+- `block_dirty`
+- `autostash_then_sync`
+- `manual_sync`
+- `no_change`
+
+That gives us a concrete design target for future commands like:
+
+- `gr2 repo status`
+- `gr2 repo sync`
+- `gr2 repo pull`
+
+without turning plain `gr2 apply` into an unsafe catch-all mutation command.
+
+## Lane Workspace Prototype
+
+`lane_workspace_prototype.py` explores the next layer above repo maintenance:
+
+- explicit lane metadata on disk
+- lane-local repo membership and branch map
+- shared + private context roots
+- lane-aware execution planning
+- shared scratchpads for lightweight collaboration
+
+Example:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py create-lane \
+  /path/to/workspace atlas feat-auth --repos app,api --branch feat/auth
+
+python3 gr2/prototypes/lane_workspace_prototype.py plan-exec \
+  /path/to/workspace atlas feat-auth 'cargo test'
+```
+
+Review lane example:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py create-review-lane \
+  /path/to/workspace atlas grip 548
+```
+
+Shared scratchpad example:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py create-shared-scratchpad \
+  /path/to/workspace blog-s17 \
+  --kind doc \
+  --purpose "Sprint 17 blog draft" \
+  --participant atlas \
+  --participant layne \
+  --ref grip#552
+
+python3 gr2/prototypes/lane_workspace_prototype.py list-shared-scratchpads \
+  /path/to/workspace
+```
+
+This prototype still does not execute commands. It proves that lane and
+scratchpad metadata can become the durable source of truth for:
+
+- which repos belong to a lane
+- which branch each repo should use
+- which context roots apply
+- where multi-repo commands should run
+- where lightweight collaboration should happen without violating private
+  workspaces
+
+## UX Focus
+
+This prototype is intentionally trying to answer user-facing questions:
+
+- how do I create a review lane quickly?
+- how do I know what I should do next in this lane?
+- when should I use a shared scratchpad instead of a PR or a private lane?
+
+That is why it includes:
+
+- `list-lanes`
+- `next-step`
+- `create-review-lane`
+- `create-shared-scratchpad`
+
+## Stress Testing
+
+This prototype is not considered verified on the happy path alone.
+
+The break-case matrix lives at:
+
+- `docs/ASSESS-gr2-shared-scratchpads-stress.md`
+
+The MVP should not be finalized until the prototype has been evaluated against:
+
+- concurrent shared editing
+- stale / abandoned scratchpads
+- wrong-surface selection
+- scope creep into shared implementation
+- cleanup and lifecycle handling
+- promotion from scratchpad to real repo artifact / PR
+
+## Real Git Verification
+
+Prototype confidence should not stop at metadata or tempdir-only happy paths.
+
+The next verification phase should use real GitHub repos in `synapt-dev`:
+
+- `synapt-dev/gr2-playground-app`
+- `synapt-dev/gr2-playground-api`
+- `synapt-dev/gr2-playground-web`
+
+These repos exist specifically to pressure the UX against actual git behavior:
+
+- cloning and default branches
+- multi-repo branch switching
+- review-lane isolation
+- dirty-work detection and recovery
+- shared scratchpad usage alongside private lanes
+
+That real-git verification phase is now tracked in:
+
+- `grip#523`
+- `grip#555`
+
+The design standard should be:
+
+- prototype behavior must survive both synthetic stress cases and real-repo
+  workflow checks before the MVP is treated as solid
+
+## Cross-Mode Lane Stress
+
+The lane model also needs adversarial verification across the four primary
+operating modes:
+
+- solo human
+- single agent
+- multi-agent
+- mixed human + agent
+
+Run:
+
+```bash
+python3 gr2/prototypes/cross_mode_lane_stress.py
+```
+
+This harness does not just show happy-path lane creation. It reports where the
+current model:
+
+- holds
+- partially holds
+- still fails
+
+across interruption recovery, same-repo parallelism, mixed-mode conflicts, and
+lane-recovery ambiguity.
+
+The current prototype adds two explicit recovery/safety concepts to support
+that stress loop:
+
+- lane session state
+  - `enter-lane`
+  - `current-lane`
+- lane leases
+  - `acquire-lane-lease`
+  - `release-lane-lease`
+  - `show-lane-leases`
+
+Those are still prototype surfaces, but they let us test whether the lane
+model can survive interruption and mixed human/agent use rather than only
+describe those needs abstractly.
+
+Lease behavior is now explicit in the prototype:
+
+- leases have `ttl_seconds`
+- stale leases are detectable
+- `acquire-lane-lease --force` can break stale conflicting leases
+- the conflict matrix is deliberate:
+  - `edit` conflicts with `edit`, `exec`, and `review`
+  - `exec` conflicts with `edit` and `review`, but not `exec`
+- `review` is exclusive
+
+## Synapt Integration Prototype
+
+The lane prototype now includes a minimal Synapt-native event layer:
+
+- `enter-lane --notify-channel --recall`
+- `exit-lane --notify-channel --recall`
+- append-only event log at `.grip/events/lane_events.jsonl`
+- recall-compatible log at `.grip/events/recall_lane_history.jsonl`
+- `lane-history` to reconstruct a unit's lane timeline
+
+Unit `agent_id` can now flow from `WorkspaceSpec` into:
+
+- lane metadata
+- current-lane state
+- emitted lane events
+
+This is still prototype scope, but it tests the right product direction:
+lane transitions and lease changes should be observable workspace events rather
+than invisible local state.
+
+## Real-Git Same-Repo Multi-Agent Materialization
+
+To verify that unit-local-first is real and not only metadata, run:
+
+```bash
+python3 gr2/prototypes/real_git_lane_materialization.py
+```
+
+This harness:
+
+- creates a local bare remote
+- writes a workspace spec that points at it
+- creates two lanes for two different units that both touch the same repo
+- verifies `plan-exec` produces distinct cwd paths
+- clones into those lane cwd paths
+- makes independent commits in each checkout
+- verifies the checkouts do not interfere
+
+## Concurrent Lease Stress
+
+To verify that lease writes survive contention, run:
+
+```bash
+python3 gr2/prototypes/concurrent_lease_stress.py
+```
+
+This harness runs two phases in one command:
+
+- before locking: `GR2_DISABLE_LEASE_LOCKING=1`
+- after locking: default locking enabled
+
+It reports:
+
+- JSON corruption count
+- rounds where both conflicting edit acquisitions succeeded
+- rounds where the final lease count was wrong
+
+Bootstrap command:
+
+```bash
+python3 gr2/prototypes/real_git_playground.py /tmp/gr2-real-git-demo
+```
+
+If the local environment cannot reach GitHub over SSH, use:
+
+```bash
+python3 gr2/prototypes/real_git_playground.py /tmp/gr2-real-git-demo \
+  --transport https
+```
+
+That harness will:
+
+- initialize a fresh gr2 workspace
+- register the three private playground repos
+- write a real `WorkspaceSpec`
+- run `plan` and `apply`
+- create real local git branches in the cloned repos
+- create multiple lanes and one shared scratchpad
+- print repo, lane, exec, and scratchpad status surfaces
+
+## New UX-Focused Prototype Surfaces
+
+The prototype now includes explicit user-guidance commands for the cases that
+usually break first in real workflows:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py recommend-surface \
+  --kind doc --collaborative --shared-draft
+
+python3 gr2/prototypes/lane_workspace_prototype.py audit-shared-scratchpads \
+  /path/to/workspace --stale-days 3
+
+python3 gr2/prototypes/lane_workspace_prototype.py plan-promote-scratchpad \
+  /path/to/workspace blog-s17 \
+  --target-repo app \
+  --target-path docs/blog/sprint-17.md \
+  --owner-unit atlas
+```
+
+These are intentionally user-first:
+
+- `recommend-surface`
+  - answers "should this be a feature lane, review lane, or shared scratchpad?"
+- `audit-shared-scratchpads`
+  - exposes stale, orphaned, or weakly tracked scratchpads
+- `plan-promote-scratchpad`
+  - makes the graduation path from shared draft to repo artifact explicit
+
+This keeps the prototype from overfitting to happy-path metadata creation while
+ignoring the actual decisions users struggle with.
+
+## Transport/Auth Preflight
+
+Real multi-repo bootstrap fails early if transport or auth is wrong, so the
+prototype now includes a dedicated preflight surface:
+
+```bash
+python3 gr2/prototypes/repo_transport_probe.py \
+  /path/to/workspace/.grip/workspace_spec.toml
+```
+
+This reports, per repo:
+
+- transport type
+- whether the remote looks reachable
+- whether auth is failing
+- the next recommended action
+
+The real-git playground harness now runs this probe before `gr2 apply` so
+transport/auth problems are surfaced as an explicit status surface instead of a
+late clone failure buried inside apply output.
+
+## Layout Model Probe
+
+The real-git playground also needs to answer a harder product question:
+
+- does the observed layout actually match the mental model we are designing?
+
+The prototype now includes:
+
+```bash
+python3 gr2/prototypes/layout_model_probe.py /path/to/workspace --owner-unit atlas
+```
+
+This compares the observed workspace against two candidate models:
+
+- shared-repo-first
+- unit-local-first
+
+It is intentionally blunt. If the workspace behaves like one model while the
+docs imply another, the prototype should say so directly.
+
+## Cache Materialization Probe
+
+The next question is whether shared cache as apply substrate is actually worth
+it in practice.
+
+The prototype now includes:
+
+```bash
+python3 gr2/prototypes/cache_materialization_probe.py --transport ssh
+```
+
+This measures, per playground repo:
+
+- direct remote clone time
+- one-time mirror seed time
+- cache-backed working clone time using `git clone --reference-if-able`
+- whether the resulting working clone actually uses alternates
+
+This keeps the cache discussion grounded in evidence:
+
+- lanes remain the UX
+- cache remains the optimization
+- the prototype should tell us whether the optimization is material enough to
+  justify building it into `apply`
diff --git a/gr2/prototypes/cache_materialization_probe.py b/gr2/prototypes/cache_materialization_probe.py
new file mode 100644
index 00000000..b494e746
--- /dev/null
+++ b/gr2/prototypes/cache_materialization_probe.py
@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Prototype cache-backed materialization for gr2 working clones.
+
+This is not a final implementation. It exists to answer a narrower question:
+
+- if `apply` seeds working clones from a local mirror/reference cache, does that
+  materially improve materialization speed while keeping the user-facing model
+  unchanged?
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+PLAYGROUND_REPOS = {
+    "app": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-app.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-app.git",
+    },
+    "api": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-api.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-api.git",
+    },
+    "web": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-web.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-web.git",
+    },
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Measure direct clone vs cache-backed clone materialization"
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["ssh", "https"],
+        default="ssh",
+        help="remote transport to test",
+    )
+    parser.add_argument(
+        "--repo",
+        action="append",
+        dest="repos",
+        help="repo(s) to test; defaults to all playground repos",
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        help="optional persistent temp root; defaults to a temporary directory",
+    )
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def repo_url(repo_name: str, transport: str) -> str:
+    return PLAYGROUND_REPOS[repo_name][transport]
+
+
+def git_env() -> dict[str, str]:
+    env = dict(os.environ)
+    env.setdefault(
+        "GIT_SSH_COMMAND",
+        "ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new",
+    )
+    return env
+
+
+def run(argv: list[str], *, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        text=True,
+        capture_output=True,
+        check=True,
+        env=git_env(),
+    )
+
+
+def timed_clone(argv: list[str], *, cwd: Path | None = None) -> tuple[float, subprocess.CompletedProcess[str]]:
+    start = time.perf_counter()
+    result = run(argv, cwd=cwd)
+    elapsed = time.perf_counter() - start
+    return (elapsed, result)
+
+
+def verify_working_clone(path: Path) -> dict[str, object]:
+    head = run(["git", "-C", str(path), "rev-parse", "--abbrev-ref", "HEAD"]).stdout.strip()
+    status = run(["git", "-C", str(path), "status", "--short"]).stdout.strip()
+    alternates = path / ".git" / "objects" / "info" / "alternates"
+    return {
+        "head": head,
+        "clean": status == "",
+        "uses_alternates": alternates.exists(),
+        "alternates_path": str(alternates) if alternates.exists() else None,
+    }
+
+
+def probe_repo(root: Path, repo_name: str, transport: str) -> dict[str, object]:
+    url = repo_url(repo_name, transport)
+    repo_root = root / repo_name
+    direct_root = repo_root / "direct"
+    cached_root = repo_root / "cached"
+    cache_root = repo_root / "cache"
+    direct_root.mkdir(parents=True, exist_ok=True)
+    cached_root.mkdir(parents=True, exist_ok=True)
+    cache_root.mkdir(parents=True, exist_ok=True)
+
+    direct_target = direct_root / repo_name
+    cache_mirror = cache_root / f"{repo_name}.git"
+    cached_target = cached_root / repo_name
+
+    direct_seconds, _ = timed_clone(["git", "clone", url, str(direct_target)])
+    mirror_seconds, _ = timed_clone(["git", "clone", "--mirror", url, str(cache_mirror)])
+    cached_seconds, _ = timed_clone(
+        [
+            "git",
+            "clone",
+            "--reference-if-able",
+            str(cache_mirror),
+            url,
+            str(cached_target),
+        ]
+    )
+
+    direct_info = verify_working_clone(direct_target)
+    cached_info = verify_working_clone(cached_target)
+
+    return {
+        "repo": repo_name,
+        "transport": transport,
+        "direct_clone_seconds": round(direct_seconds, 3),
+        "mirror_seed_seconds": round(mirror_seconds, 3),
+        "cached_clone_seconds": round(cached_seconds, 3),
+        "delta_seconds": round(direct_seconds - cached_seconds, 3),
+        "direct_clone": direct_info,
+        "cached_clone": cached_info,
+        "mirror_path": str(cache_mirror),
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    repos = args.repos or list(PLAYGROUND_REPOS.keys())
+    unknown = [repo for repo in repos if repo not in PLAYGROUND_REPOS]
+    if unknown:
+        raise SystemExit("unknown repos: " + ", ".join(unknown))
+
+    if args.workspace_root:
+        root = args.workspace_root.resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        cleanup = False
+    else:
+        root = Path(tempfile.mkdtemp(prefix="gr2-cache-probe."))
+        cleanup = True
+
+    try:
+        rows = [probe_repo(root, repo, args.transport) for repo in repos]
+        if args.json:
+            print(json.dumps({"root": str(root), "results": rows}, indent=2))
+        else:
+            print(f"root: {root}")
+            print("REPO\tTRANSPORT\tDIRECT_S\tMIRROR_S\tCACHED_S\tDELTA_S\tALTERNATES")
+            for row in rows:
+                print(
+                    f"{row['repo']}\t{row['transport']}\t{row['direct_clone_seconds']}\t"
+                    f"{row['mirror_seed_seconds']}\t{row['cached_clone_seconds']}\t"
+                    f"{row['delta_seconds']}\t{str(row['cached_clone']['uses_alternates']).lower()}"
+                )
+            print("notes:")
+            print("- direct clone is a normal working clone from remote")
+            print("- mirror seed is the one-time cache population cost")
+            print("- cached clone is a working clone using --reference-if-able from the local mirror")
+        return 0
+    finally:
+        if cleanup:
+            shutil.rmtree(root)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/prototypes/concurrent_lease_stress.py b/gr2/prototypes/concurrent_lease_stress.py
new file mode 100644
index 00000000..378880ad
--- /dev/null
+++ b/gr2/prototypes/concurrent_lease_stress.py
@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Concurrent lease stress harness with before/after locking results."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import multiprocessing
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run concurrent lease stress before and after file locking"
+    )
+    parser.add_argument("--rounds", type=int, default=50)
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def run(argv: list[str], *, env: dict | None = None, check: bool = True, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(argv, check=check, text=True, capture_output=capture, env=env)
+
+
+def init_workspace(workspace_root: Path) -> None:
+    (workspace_root / ".grip").mkdir(parents=True, exist_ok=True)
+    (workspace_root / "agents").mkdir(exist_ok=True)
+    spec = """schema_version = 1
+workspace_name = "concurrent-lease-stress"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.invalid/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+agent_id = "atlas-agent"
+repos = ["app"]
+"""
+    (workspace_root / ".grip" / "workspace_spec.toml").write_text(spec)
+
+
+def create_lane(root: Path, workspace_root: Path) -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-lane",
+            str(workspace_root),
+            "atlas",
+            "feat-race",
+            "--repos",
+            "app",
+            "--branch",
+            "feat/race",
+        ],
+        capture=True,
+    )
+
+
+def worker(workspace_root: str, actor: str, queue, disable_locking: bool) -> None:
+    root = repo_root()
+    env = os.environ.copy()
+    if disable_locking:
+        env["GR2_DISABLE_LEASE_LOCKING"] = "1"
+        env["GR2_LEASE_TEST_DELAY"] = "0.02"
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "acquire-lane-lease",
+            workspace_root,
+            "atlas",
+            "feat-race",
+            "--actor",
+            actor,
+            "--mode",
+            "edit",
+            "--ttl-seconds",
+            "900",
+        ],
+        env=env,
+        check=False,
+        capture=True,
+    )
+    queue.put(
+        {
+            "actor": actor,
+            "returncode": proc.returncode,
+            "stdout": proc.stdout,
+            "stderr": proc.stderr,
+        }
+    )
+
+
+def read_leases(workspace_root: Path) -> tuple[bool, list[dict] | None]:
+    path = workspace_root / "agents" / "atlas" / "lanes" / "feat-race" / "leases.json"
+    if not path.exists():
+        return True, []
+    try:
+        return True, json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return False, None
+
+
+def release_all(root: Path, workspace_root: Path, disable_locking: bool) -> None:
+    env = os.environ.copy()
+    if disable_locking:
+        env["GR2_DISABLE_LEASE_LOCKING"] = "1"
+    for actor in ("worker:a", "worker:b"):
+        run(
+            [
+                "python3",
+                str(lane_proto(root)),
+                "release-lane-lease",
+                str(workspace_root),
+                "atlas",
+                "feat-race",
+                "--actor",
+                actor,
+            ],
+            env=env,
+            check=False,
+            capture=True,
+        )
+
+
+def run_phase(disable_locking: bool, rounds: int) -> dict:
+    root = repo_root()
+    with tempfile.TemporaryDirectory(prefix="gr2-concurrent-lease-") as tmp:
+        workspace_root = Path(tmp)
+        init_workspace(workspace_root)
+        create_lane(root, workspace_root)
+
+        corruption_count = 0
+        both_succeeded_count = 0
+        unexpected_lease_count = 0
+
+        for _ in range(rounds):
+            queue = multiprocessing.Queue()
+            p1 = multiprocessing.Process(
+                target=worker,
+                args=(str(workspace_root), "worker:a", queue, disable_locking),
+            )
+            p2 = multiprocessing.Process(
+                target=worker,
+                args=(str(workspace_root), "worker:b", queue, disable_locking),
+            )
+            p1.start()
+            p2.start()
+            p1.join()
+            p2.join()
+
+            results = [queue.get(), queue.get()]
+            success_count = sum(1 for item in results if item["returncode"] == 0)
+            if success_count == 2:
+                both_succeeded_count += 1
+
+            valid_json, leases = read_leases(workspace_root)
+            if not valid_json:
+                corruption_count += 1
+            else:
+                expected = 1 if success_count >= 1 else 0
+                if len(leases or []) != expected:
+                    unexpected_lease_count += 1
+
+            release_all(root, workspace_root, disable_locking)
+
+        return {
+            "locking": "disabled" if disable_locking else "enabled",
+            "rounds": rounds,
+            "corruption_count": corruption_count,
+            "both_succeeded_count": both_succeeded_count,
+            "unexpected_lease_count": unexpected_lease_count,
+        }
+
+
+def main() -> int:
+    args = parse_args()
+    before = run_phase(disable_locking=True, rounds=args.rounds)
+    after = run_phase(disable_locking=False, rounds=args.rounds)
+    payload = {"before_locking": before, "after_locking": after}
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print("gr2 concurrent lease stress")
+        print(json.dumps(payload, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/cross_mode_lane_stress.py b/gr2/prototypes/cross_mode_lane_stress.py
new file mode 100644
index 00000000..e66cea5e
--- /dev/null
+++ b/gr2/prototypes/cross_mode_lane_stress.py
@@ -0,0 +1,699 @@
+#!/usr/bin/env python3
+"""Adversarial cross-mode stress harness for the gr2 lane model.
+
+This script pressures the lane prototype across the four primary user modes:
+
+1. solo human
+2. single agent
+3. multi-agent
+4. mixed human + agent
+
+It does not pretend the model is complete. It reports where the current
+prototype holds, where it only partially holds, and where it still falls over.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass
+class ScenarioResult:
+    scenario_id: str
+    user_mode: str
+    title: str
+    verdict: str
+    holds: list[str]
+    gaps: list[str]
+    evidence: list[str]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run adversarial cross-mode lane stress checks"
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        help="optional workspace root; defaults to a temporary workspace",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit structured JSON instead of human-readable text",
+    )
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def run(argv: list[str], *, capture: bool = False, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        check=True,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def init_workspace(workspace_root: Path) -> None:
+    (workspace_root / ".grip").mkdir(parents=True, exist_ok=True)
+    (workspace_root / "agents").mkdir(exist_ok=True)
+    spec = """schema_version = 1
+workspace_name = "lane-cross-mode-stress"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.invalid/app.git"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "https://example.invalid/api.git"
+
+[[repos]]
+name = "web"
+path = "repos/web"
+url = "https://example.invalid/web.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+agent_id = "atlas-agent"
+repos = ["app", "api", "web"]
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+agent_id = "apollo-agent"
+repos = ["app", "api", "web"]
+
+[[units]]
+name = "layne"
+path = "agents/layne"
+agent_id = "layne-human"
+repos = ["app", "api", "web"]
+"""
+    (workspace_root / ".grip" / "workspace_spec.toml").write_text(spec)
+
+
+def create_lane(root: Path, workspace_root: Path, owner_unit: str, lane_name: str, repos: str, branch: str, lane_type: str = "feature") -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-lane",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "--type",
+            lane_type,
+            "--repos",
+            repos,
+            "--branch",
+            branch,
+        ]
+    )
+
+
+def create_review_lane(root: Path, workspace_root: Path, owner_unit: str, repo: str, pr_number: int) -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-review-lane",
+            str(workspace_root),
+            owner_unit,
+            repo,
+            str(pr_number),
+        ]
+    )
+
+
+def plan_exec_json(root: Path, workspace_root: Path, owner_unit: str, lane_name: str, command_text: str) -> list[dict]:
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "plan-exec",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            command_text,
+            "--json",
+        ],
+        capture=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def acquire_lease(root: Path, workspace_root: Path, owner_unit: str, lane_name: str, actor: str, mode: str, ttl_seconds: int = 900, force: bool = False, expect_ok: bool = True) -> subprocess.CompletedProcess[str]:
+    argv = [
+        "python3",
+        str(lane_proto(root)),
+        "acquire-lane-lease",
+        str(workspace_root),
+        owner_unit,
+        lane_name,
+        "--actor",
+        actor,
+        "--mode",
+        mode,
+        "--ttl-seconds",
+        str(ttl_seconds),
+    ]
+    if force:
+        argv.append("--force")
+    proc = subprocess.run(argv, check=False, text=True, capture_output=True)
+    if expect_ok and proc.returncode != 0:
+        raise SystemExit(f"lease acquisition failed unexpectedly: {' '.join(argv)}\n{proc.stdout}\n{proc.stderr}")
+    return proc
+
+
+def show_leases_json(root: Path, workspace_root: Path, owner_unit: str, lane_name: str) -> list[dict]:
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "show-lane-leases",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "--json",
+        ],
+        capture=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def list_lanes_text(root: Path, workspace_root: Path, owner_unit: str | None = None) -> str:
+    argv = [
+        "python3",
+        str(lane_proto(root)),
+        "list-lanes",
+        str(workspace_root),
+    ]
+    if owner_unit:
+        argv.extend(["--owner-unit", owner_unit])
+    proc = run(argv, capture=True)
+    return proc.stdout
+
+
+def scenario_multi_agent_same_repo(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-router", "app", "feat/router")
+    create_lane(root, workspace_root, "apollo", "feat-materialize", "app", "feat/materialize")
+
+    atlas_lane = workspace_root / "agents" / "atlas" / "lanes" / "feat-router" / "lane.toml"
+    apollo_lane = workspace_root / "agents" / "apollo" / "lanes" / "feat-materialize" / "lane.toml"
+
+    holds = []
+    gaps = []
+    evidence = []
+
+    if atlas_lane.exists() and apollo_lane.exists():
+        holds.append("two units can create separate lanes touching the same repo without metadata collision")
+        evidence.append(f"lane files: {atlas_lane.relative_to(workspace_root)}, {apollo_lane.relative_to(workspace_root)}")
+    else:
+        gaps.append("unit-scoped lane metadata was not isolated cleanly")
+
+    atlas_exec = plan_exec_json(root, workspace_root, "atlas", "feat-router", "cargo test")
+    apollo_exec = plan_exec_json(root, workspace_root, "apollo", "feat-materialize", "cargo test")
+    if atlas_exec and apollo_exec and atlas_exec[0]["cwd"] != apollo_exec[0]["cwd"]:
+        holds.append("execution planning stays unit-scoped even when both lanes include the same repo")
+        evidence.append(f"exec cwd atlas={atlas_exec[0]['cwd']} apollo={apollo_exec[0]['cwd']}")
+        verdict = "holds"
+    else:
+        gaps.append("execution planning did not stay unit-scoped for same-repo parallel work")
+        verdict = "fails"
+
+    return ScenarioResult(
+        scenario_id="multi-agent-same-repo",
+        user_mode="multi-agent",
+        title="two agents create lanes that touch the same repo",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_mixed_same_lane_exec(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "layne", "feat-blog", "app", "feat/blog")
+    acquire_lease(root, workspace_root, "layne", "feat-blog", "human:layne", "edit")
+
+    exec_rows = plan_exec_json(root, workspace_root, "layne", "feat-blog", "cargo test")
+
+    holds = []
+    gaps = []
+    evidence = [
+        "human edit lease acquired for layne/feat-blog",
+        json.dumps(exec_rows if isinstance(exec_rows, list) else exec_rows, indent=2),
+    ]
+
+    if isinstance(exec_rows, dict) and exec_rows.get("status") == "blocked":
+        holds.append("same-lane human-edit vs agent-exec is blocked by a lease")
+        holds.append("prototype now models occupancy instead of silently planning through it")
+        verdict = "holds"
+    else:
+        gaps.append("same-lane concurrent human-edit vs agent-exec is not modeled or blocked")
+        verdict = "fails"
+
+    return ScenarioResult(
+        scenario_id="mixed-same-lane-exec",
+        user_mode="mixed-human-agent",
+        title="human edits in a lane while an agent plans exec in the same lane",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_single_agent_interrupt_recovery(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-auth", "app,api", "feat/auth")
+    create_review_lane(root, workspace_root, "atlas", "app", 123)
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "atlas",
+            "feat-auth",
+            "--actor",
+            "agent:atlas",
+        ]
+    )
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "atlas",
+            "review-123",
+            "--actor",
+            "agent:atlas",
+        ]
+    )
+    lane_listing = list_lanes_text(root, workspace_root, "atlas")
+    current_lane_proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "current-lane",
+            str(workspace_root),
+            "atlas",
+            "--json",
+        ],
+        capture=True,
+    )
+    current_lane_doc = json.loads(current_lane_proc.stdout)
+    holds = [
+        "agent can enumerate all of its lanes without guessing filesystem paths",
+        "lane metadata includes repos, type, and PR references",
+    ]
+    gaps = []
+    evidence = [lane_listing.strip(), json.dumps(current_lane_doc, indent=2)]
+
+    current = current_lane_doc.get("current", {})
+    recent = current_lane_doc.get("recent", [])
+    if current.get("lane_name") == "review-123":
+        holds.append("agent can recover current lane after an interruption")
+    else:
+        gaps.append("current-lane surface did not record the lane entered most recently")
+
+    if recent and recent[0].get("lane_name") == "feat-auth":
+        holds.append("agent can recover previous lane from recent history")
+        verdict = "holds"
+    else:
+        gaps.append("prototype still cannot recover previous lane deterministically")
+        verdict = "partial"
+
+    return ScenarioResult(
+        scenario_id="single-agent-interrupt-recovery",
+        user_mode="single-agent",
+        title="agent is interrupted mid-task and needs to recover lane context",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_lease_conflict_matrix(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-matrix", "app", "feat/matrix")
+
+    exec_one = acquire_lease(root, workspace_root, "atlas", "feat-matrix", "agent:atlas", "exec")
+    exec_two = acquire_lease(root, workspace_root, "atlas", "feat-matrix", "agent:apollo", "exec")
+    edit_conflict = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-matrix",
+        "human:layne",
+        "edit",
+        expect_ok=False,
+    )
+
+    create_lane(root, workspace_root, "atlas", "feat-review-lock", "app", "feat/review-lock")
+    acquire_lease(root, workspace_root, "atlas", "feat-review-lock", "agent:atlas", "review")
+    review_conflict = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-review-lock",
+        "agent:apollo",
+        "exec",
+        expect_ok=False,
+    )
+
+    holds = []
+    gaps = []
+    evidence = []
+
+    if exec_one.returncode == 0 and exec_two.returncode == 0:
+        holds.append("exec-vs-exec is allowed for the same lane")
+        evidence.append("two exec leases acquired successfully on atlas/feat-matrix")
+    else:
+        gaps.append("exec-vs-exec was blocked unexpectedly")
+
+    if edit_conflict.returncode != 0:
+        holds.append("edit-vs-exec conflicts as expected")
+        evidence.append(edit_conflict.stdout.strip())
+    else:
+        gaps.append("edit-vs-exec did not conflict")
+
+    if review_conflict.returncode != 0:
+        holds.append("review-vs-anything is exclusive")
+        evidence.append(review_conflict.stdout.strip())
+    else:
+        gaps.append("review-vs-exec did not conflict")
+
+    leases = show_leases_json(root, workspace_root, "atlas", "feat-matrix")
+    evidence.append(json.dumps(leases, indent=2))
+    verdict = "holds" if not gaps else "fails"
+    return ScenarioResult(
+        scenario_id="lease-conflict-matrix",
+        user_mode="cross-mode",
+        title="lease conflict matrix enforces edit/exec/review semantics",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_synapt_lane_events(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-events", "app,api", "feat/events")
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "atlas",
+            "feat-events",
+            "--actor",
+            "agent:atlas",
+            "--notify-channel",
+            "--recall",
+        ]
+    )
+    acquire_lease(root, workspace_root, "atlas", "feat-events", "agent:atlas", "exec")
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "release-lane-lease",
+            str(workspace_root),
+            "atlas",
+            "feat-events",
+            "--actor",
+            "agent:atlas",
+        ]
+    )
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "exit-lane",
+            str(workspace_root),
+            "atlas",
+            "--actor",
+            "agent:atlas",
+            "--notify-channel",
+            "--recall",
+        ]
+    )
+    history_proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "lane-history",
+            str(workspace_root),
+            "atlas",
+            "--json",
+        ],
+        capture=True,
+    )
+    history_rows = json.loads(history_proc.stdout)
+    events_path = workspace_root / ".grip" / "events" / "lane_events.jsonl"
+    recall_path = workspace_root / ".grip" / "events" / "recall_lane_history.jsonl"
+
+    holds = []
+    gaps = []
+    evidence = [json.dumps(history_rows, indent=2)]
+
+    event_types = [row["type"] for row in history_rows]
+    expected = ["lane_enter", "lease_acquire", "lease_release", "lane_exit"]
+    if event_types == expected:
+        holds.append("lane event timeline is reconstructible from append-only event log")
+    else:
+        gaps.append(f"unexpected lane event order: {event_types}")
+
+    if all(row.get("agent_id") == "atlas-agent" for row in history_rows):
+        holds.append("agent_id flows from workspace spec into lane events")
+    else:
+        gaps.append("agent_id did not flow consistently into lane events")
+
+    if events_path.exists() and recall_path.exists():
+        holds.append("channel-compatible and recall-compatible event logs are both written")
+    else:
+        gaps.append("expected event logs were not both written")
+
+    verdict = "holds" if not gaps else "fails"
+    return ScenarioResult(
+        scenario_id="synapt-lane-events",
+        user_mode="single-agent",
+        title="lane enter/lease/exit emits reconstructible synapt-compatible events",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_stale_lease_force_break(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-stale", "app", "feat/stale")
+    stale = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-stale",
+        "human:layne",
+        "edit",
+        ttl_seconds=0,
+    )
+    blocked_exec = plan_exec_json(root, workspace_root, "atlas", "feat-stale", "cargo test")
+    forced = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-stale",
+        "agent:atlas",
+        "exec",
+        ttl_seconds=900,
+        force=True,
+    )
+    leases_after = show_leases_json(root, workspace_root, "atlas", "feat-stale")
+
+    holds = []
+    gaps = []
+    evidence = [stale.stdout.strip(), json.dumps(blocked_exec, indent=2), forced.stdout.strip(), json.dumps(leases_after, indent=2)]
+
+    if isinstance(blocked_exec, dict) and blocked_exec.get("reason") == "stale-conflicting-lease":
+        holds.append("plan-exec detects stale conflicting leases")
+    else:
+        gaps.append("plan-exec did not flag stale conflicting leases")
+
+    actors_after = {lease["actor"] for lease in leases_after}
+    if "human:layne" not in actors_after and "agent:atlas" in actors_after:
+        holds.append("force acquisition breaks stale conflicting lease and installs new lease")
+    else:
+        gaps.append("force acquisition did not replace stale conflicting lease cleanly")
+
+    verdict = "holds" if not gaps else "fails"
+    return ScenarioResult(
+        scenario_id="stale-lease-force-break",
+        user_mode="cross-mode",
+        title="stale leases are detectable and force-breakable",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_solo_human_forgets_lane(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "layne", "feat-auth", "app,api", "feat/auth")
+    create_lane(root, workspace_root, "layne", "feat-web", "web", "feat/web")
+    create_lane(root, workspace_root, "layne", "feat-release", "app,web", "feat/release")
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "layne",
+            "feat-release",
+            "--actor",
+            "human:layne",
+        ]
+    )
+    create_review_lane(root, workspace_root, "layne", "app", 456)
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "layne",
+            "review-456",
+            "--actor",
+            "human:layne",
+        ]
+    )
+
+    lane_listing = list_lanes_text(root, workspace_root, "layne")
+    current_lane_proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "current-lane",
+            str(workspace_root),
+            "layne",
+            "--json",
+        ],
+        capture=True,
+    )
+    current_lane_doc = json.loads(current_lane_proc.stdout)
+    holds = [
+        "user can see all lanes in one listing",
+        "review lane is isolated as its own lane type rather than overwriting feature state",
+    ]
+    gaps = []
+    evidence = [lane_listing.strip(), json.dumps(current_lane_doc, indent=2)]
+
+    if current_lane_doc.get("current", {}).get("lane_name") == "review-456":
+        holds.append("current review lane is visible after switching")
+    else:
+        gaps.append("current lane is not visible after switching to review")
+
+    recent = current_lane_doc.get("recent", [])
+    if recent and recent[0].get("lane_name") == "feat-release":
+        holds.append("previous feature lane is recoverable after entering review")
+        verdict = "holds"
+    else:
+        gaps.append("prototype lacks an obvious return-to-previous-lane recovery path")
+        verdict = "partial"
+
+    return ScenarioResult(
+        scenario_id="solo-human-lane-recovery",
+        user_mode="solo-human",
+        title="solo human has three feature lanes, switches to review, then forgets the prior lane",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def run_scenarios(workspace_root: Path) -> list[ScenarioResult]:
+    root = repo_root()
+    init_workspace(workspace_root)
+    return [
+        scenario_synapt_lane_events(root, workspace_root),
+        scenario_lease_conflict_matrix(root, workspace_root),
+        scenario_stale_lease_force_break(root, workspace_root),
+        scenario_multi_agent_same_repo(root, workspace_root),
+        scenario_mixed_same_lane_exec(root, workspace_root),
+        scenario_single_agent_interrupt_recovery(root, workspace_root),
+        scenario_solo_human_forgets_lane(root, workspace_root),
+    ]
+
+
+def print_human(results: list[ScenarioResult], workspace_root: Path) -> None:
+    print("gr2 cross-mode lane stress results")
+    print(f"workspace: {workspace_root}")
+    print()
+    for result in results:
+        print(f"[{result.verdict}] {result.user_mode}: {result.title}")
+        if result.holds:
+            print("  holds:")
+            for item in result.holds:
+                print(f"    - {item}")
+        if result.gaps:
+            print("  gaps:")
+            for item in result.gaps:
+                print(f"    - {item}")
+        if result.evidence:
+            print("  evidence:")
+            for item in result.evidence:
+                for line in item.splitlines():
+                    print(f"    {line}")
+        print()
+
+
+def main() -> int:
+    args = parse_args()
+
+    if args.workspace_root:
+        workspace_root = args.workspace_root.resolve()
+        workspace_root.mkdir(parents=True, exist_ok=True)
+        results = run_scenarios(workspace_root)
+    else:
+        with tempfile.TemporaryDirectory(prefix="gr2-cross-mode-") as tmp:
+            workspace_root = Path(tmp)
+            results = run_scenarios(workspace_root)
+            if args.json:
+                print(json.dumps([asdict(result) for result in results], indent=2))
+                return 0
+            print_human(results, workspace_root)
+            return 0
+
+    if args.json:
+        print(json.dumps([asdict(result) for result in results], indent=2))
+    else:
+        print_human(results, workspace_root)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/lane_workspace_prototype.py b/gr2/prototypes/lane_workspace_prototype.py
new file mode 100644
index 00000000..678924e8
--- /dev/null
+++ b/gr2/prototypes/lane_workspace_prototype.py
@@ -0,0 +1,1236 @@
+#!/usr/bin/env python3
+"""Prototype lane metadata, execution planning, and shared scratchpads for gr2.
+
+This prototype does not mutate git state. It explores three UX questions:
+
+1. are lane records legible enough to guide multi-repo work?
+2. can lightweight shared scratchpads fill the collaboration gap without
+   violating private-workspace rules?
+3. can the tool tell the user what to do next instead of forcing them to infer
+   the workflow?
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import os
+import json
+import shlex
+import sys
+import time
+import tomllib
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+import fcntl
+
+
+LANE_SCHEMA_VERSION = 1
+SCRATCHPAD_SCHEMA_VERSION = 1
+
+
+@dataclasses.dataclass
+class LaneMetadata:
+    schema_version: int
+    lane_name: str
+    owner_unit: str
+    agent_id: str | None
+    lane_type: str
+    repos: list[str]
+    branch_map: dict[str, str]
+    pr_associations: list[str]
+    shared_context_roots: list[str]
+    private_context_roots: list[str]
+    exec_defaults: dict[str, object]
+    creation_source: str
+
+    def as_toml(self) -> str:
+        lines = [
+            f"schema_version = {self.schema_version}",
+            f'lane_name = "{self.lane_name}"',
+            f'owner_unit = "{self.owner_unit}"',
+            f'agent_id = "{self.agent_id or ""}"',
+            f'lane_type = "{self.lane_type}"',
+            f'creation_source = "{self.creation_source}"',
+            "",
+            f"repos = [{', '.join(f'\"{r}\"' for r in self.repos)}]",
+            "",
+            "[branch_map]",
+        ]
+        for repo, branch in sorted(self.branch_map.items()):
+            lines.append(f'{repo} = "{branch}"')
+
+        lines.extend(["", "[context]", "shared_roots = ["])
+        for root in self.shared_context_roots:
+            lines.append(f'  "{root}",')
+        lines.extend(["]", "private_roots = ["])
+        for root in self.private_context_roots:
+            lines.append(f'  "{root}",')
+
+        lines.extend(["]", "", "[exec_defaults]"])
+        for key, value in self.exec_defaults.items():
+            if isinstance(value, bool):
+                encoded = str(value).lower()
+            elif isinstance(value, int):
+                encoded = str(value)
+            elif isinstance(value, list):
+                encoded = "[" + ", ".join(f'"{item}"' for item in value) + "]"
+            else:
+                encoded = f'"{value}"'
+            lines.append(f"{key} = {encoded}")
+
+        for assoc in self.pr_associations:
+            lines.extend(["", "[[pr_associations]]", f'ref = "{assoc}"'])
+
+        return "\n".join(lines) + "\n"
+
+
+@dataclasses.dataclass
+class SharedScratchpad:
+    schema_version: int
+    name: str
+    kind: str
+    purpose: str
+    participants: list[str]
+    linked_refs: list[str]
+    lifecycle: str
+    creation_source: str
+    docs_root: str
+    notes_root: str
+    context_root: str
+    created_at: str
+    updated_at: str
+
+    def as_toml(self) -> str:
+        lines = [
+            f"schema_version = {self.schema_version}",
+            f'name = "{self.name}"',
+            f'kind = "{self.kind}"',
+            f'purpose = "{self.purpose}"',
+            f'lifecycle = "{self.lifecycle}"',
+            f'creation_source = "{self.creation_source}"',
+            f'created_at = "{self.created_at}"',
+            f'updated_at = "{self.updated_at}"',
+            "",
+            f'participants = [{", ".join(f"\"{p}\"" for p in self.participants)}]',
+            f'linked_refs = [{", ".join(f"\"{r}\"" for r in self.linked_refs)}]',
+            "",
+            "[paths]",
+            f'docs_root = "{self.docs_root}"',
+            f'notes_root = "{self.notes_root}"',
+            f'context_root = "{self.context_root}"',
+        ]
+        return "\n".join(lines) + "\n"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Prototype gr2 lanes + shared scratchpads"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    create = sub.add_parser("create-lane")
+    create.add_argument("workspace_root", type=Path)
+    create.add_argument("owner_unit")
+    create.add_argument("lane_name")
+    create.add_argument("--type", default="feature")
+    create.add_argument("--repos", required=True, help="comma-separated repo names")
+    create.add_argument(
+        "--branch",
+        required=True,
+        help="default branch or repo=branch mappings separated by commas",
+    )
+    create.add_argument("--source", default="manual")
+    create.add_argument(
+        "--command",
+        dest="default_commands",
+        action="append",
+        default=[],
+        help="default lane command",
+    )
+
+    review = sub.add_parser("create-review-lane")
+    review.add_argument("workspace_root", type=Path)
+    review.add_argument("owner_unit")
+    review.add_argument("repo")
+    review.add_argument("pr_number", type=int)
+    review.add_argument("--lane-name")
+    review.add_argument("--branch")
+
+    show = sub.add_parser("show-lane")
+    show.add_argument("workspace_root", type=Path)
+    show.add_argument("owner_unit")
+    show.add_argument("lane_name")
+
+    lane_list = sub.add_parser("list-lanes")
+    lane_list.add_argument("workspace_root", type=Path)
+    lane_list.add_argument("--owner-unit")
+
+    next_step = sub.add_parser("next-step")
+    next_step.add_argument("workspace_root", type=Path)
+    next_step.add_argument("owner_unit")
+    next_step.add_argument("lane_name")
+
+    plan = sub.add_parser("plan-exec")
+    plan.add_argument("workspace_root", type=Path)
+    plan.add_argument("owner_unit")
+    plan.add_argument("lane_name")
+    plan.add_argument("command_text")
+    plan.add_argument("--repos", help="optional comma-separated repo subset")
+    plan.add_argument("--json", action="store_true")
+
+    enter = sub.add_parser("enter-lane")
+    enter.add_argument("workspace_root", type=Path)
+    enter.add_argument("owner_unit")
+    enter.add_argument("lane_name")
+    enter.add_argument("--actor", required=True, help="actor label, e.g. human:layne or agent:atlas")
+    enter.add_argument("--notify-channel", action="store_true")
+    enter.add_argument("--recall", action="store_true")
+
+    exit_lane = sub.add_parser("exit-lane")
+    exit_lane.add_argument("workspace_root", type=Path)
+    exit_lane.add_argument("owner_unit")
+    exit_lane.add_argument("--actor", required=True)
+    exit_lane.add_argument("--notify-channel", action="store_true")
+    exit_lane.add_argument("--recall", action="store_true")
+
+    current = sub.add_parser("current-lane")
+    current.add_argument("workspace_root", type=Path)
+    current.add_argument("owner_unit")
+    current.add_argument("--json", action="store_true")
+
+    history = sub.add_parser("lane-history")
+    history.add_argument("workspace_root", type=Path)
+    history.add_argument("owner_unit")
+    history.add_argument("--json", action="store_true")
+
+    lease = sub.add_parser("acquire-lane-lease")
+    lease.add_argument("workspace_root", type=Path)
+    lease.add_argument("owner_unit")
+    lease.add_argument("lane_name")
+    lease.add_argument("--actor", required=True)
+    lease.add_argument("--mode", choices=["edit", "exec", "review"], required=True)
+    lease.add_argument(
+        "--ttl-seconds",
+        type=int,
+        default=900,
+        help="lease TTL in seconds before it is considered stale",
+    )
+    lease.add_argument(
+        "--force",
+        action="store_true",
+        help="break conflicting stale leases with a warning",
+    )
+
+    release = sub.add_parser("release-lane-lease")
+    release.add_argument("workspace_root", type=Path)
+    release.add_argument("owner_unit")
+    release.add_argument("lane_name")
+    release.add_argument("--actor", required=True)
+
+    show_leases = sub.add_parser("show-lane-leases")
+    show_leases.add_argument("workspace_root", type=Path)
+    show_leases.add_argument("owner_unit")
+    show_leases.add_argument("lane_name")
+    show_leases.add_argument("--json", action="store_true")
+
+    scratch = sub.add_parser("create-shared-scratchpad")
+    scratch.add_argument("workspace_root", type=Path)
+    scratch.add_argument("name")
+    scratch.add_argument("--kind", default="doc")
+    scratch.add_argument("--purpose", required=True)
+    scratch.add_argument("--participant", action="append", default=[])
+    scratch.add_argument("--ref", action="append", default=[])
+    scratch.add_argument("--source", default="manual")
+
+    scratch_show = sub.add_parser("show-shared-scratchpad")
+    scratch_show.add_argument("workspace_root", type=Path)
+    scratch_show.add_argument("name")
+
+    scratch_list = sub.add_parser("list-shared-scratchpads")
+    scratch_list.add_argument("workspace_root", type=Path)
+
+    scratch_audit = sub.add_parser("audit-shared-scratchpads")
+    scratch_audit.add_argument("workspace_root", type=Path)
+    scratch_audit.add_argument(
+        "--stale-days",
+        type=int,
+        default=7,
+        help="mark scratchpads as stale when untouched for this many days",
+    )
+
+    promote = sub.add_parser("plan-promote-scratchpad")
+    promote.add_argument("workspace_root", type=Path)
+    promote.add_argument("name")
+    promote.add_argument("--target-repo", required=True)
+    promote.add_argument("--target-path", required=True)
+    promote.add_argument("--owner-unit", required=True)
+    promote.add_argument("--lane", help="optional lane that should carry the promotion")
+
+    recommend = sub.add_parser("recommend-surface")
+    recommend.add_argument("--kind", choices=["code", "doc", "review", "planning"], required=True)
+    recommend.add_argument("--collaborative", action="store_true")
+    recommend.add_argument("--formal-review", action="store_true")
+    recommend.add_argument("--repos", type=int, default=1)
+    recommend.add_argument("--shared-draft", action="store_true")
+
+    return parser.parse_args()
+
+
+def lane_dir(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return workspace_root / "agents" / owner_unit / "lanes" / lane_name
+
+
+def lane_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return lane_dir(workspace_root, owner_unit, lane_name) / "lane.toml"
+
+
+def shared_scratchpad_dir(workspace_root: Path, name: str) -> Path:
+    return workspace_root / "shared" / "scratchpads" / name
+
+
+def shared_scratchpad_file(workspace_root: Path, name: str) -> Path:
+    return shared_scratchpad_dir(workspace_root, name) / "scratchpad.toml"
+
+
+def current_lane_file(workspace_root: Path, owner_unit: str) -> Path:
+    return workspace_root / ".grip" / "state" / "current_lane" / f"{owner_unit}.json"
+
+
+def lane_leases_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return lane_dir(workspace_root, owner_unit, lane_name) / "leases.json"
+
+
+def lane_leases_lock_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return lane_dir(workspace_root, owner_unit, lane_name) / "leases.lock"
+
+
+def events_dir(workspace_root: Path) -> Path:
+    return workspace_root / ".grip" / "events"
+
+
+def lane_events_file(workspace_root: Path) -> Path:
+    return events_dir(workspace_root) / "lane_events.jsonl"
+
+
+def recall_lane_events_file(workspace_root: Path) -> Path:
+    return events_dir(workspace_root) / "recall_lane_history.jsonl"
+
+
+def load_workspace_spec(workspace_root: Path) -> dict:
+    with (workspace_root / ".grip" / "workspace_spec.toml").open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def find_unit_spec(workspace_root: Path, owner_unit: str) -> dict:
+    spec = load_workspace_spec(workspace_root)
+    for unit in spec.get("units", []):
+        if unit.get("name") == owner_unit:
+            return unit
+    raise SystemExit(f"unit not found in workspace spec: {owner_unit}")
+
+
+def load_lane_doc(workspace_root: Path, owner_unit: str, lane_name: str) -> dict:
+    path = lane_file(workspace_root, owner_unit, lane_name)
+    if not path.exists():
+        raise SystemExit(f"lane not found: {owner_unit}/{lane_name}")
+    return tomllib.loads(path.read_text())
+
+
+def load_shared_scratchpad_doc(workspace_root: Path, name: str) -> dict:
+    path = shared_scratchpad_file(workspace_root, name)
+    if not path.exists():
+        raise SystemExit(f"shared scratchpad not found: {name}")
+    return tomllib.loads(path.read_text())
+
+
+def load_current_lane_doc(workspace_root: Path, owner_unit: str) -> dict:
+    path = current_lane_file(workspace_root, owner_unit)
+    if not path.exists():
+        raise SystemExit(f"no current lane recorded for unit: {owner_unit}")
+    return json.loads(path.read_text())
+
+
+def append_jsonl(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(payload) + "\n")
+
+
+def emit_lane_event(workspace_root: Path, payload: dict) -> None:
+    append_jsonl(lane_events_file(workspace_root), payload)
+
+
+def emit_recall_lane_event(workspace_root: Path, payload: dict) -> None:
+    append_jsonl(recall_lane_events_file(workspace_root), payload)
+
+
+def iter_lane_events(workspace_root: Path) -> list[dict]:
+    path = lane_events_file(workspace_root)
+    if not path.exists():
+        return []
+    items: list[dict] = []
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        items.append(json.loads(line))
+    return items
+
+
+def load_lane_leases(workspace_root: Path, owner_unit: str, lane_name: str) -> list[dict]:
+    path = lane_leases_file(workspace_root, owner_unit, lane_name)
+    if not path.exists():
+        return []
+    return json.loads(path.read_text())
+
+
+def lease_locking_enabled() -> bool:
+    return os.environ.get("GR2_DISABLE_LEASE_LOCKING") != "1"
+
+
+def write_lane_leases(
+    workspace_root: Path,
+    owner_unit: str,
+    lane_name: str,
+    leases: list[dict],
+    *,
+    lock_fh=None,
+) -> None:
+    path = lane_leases_file(workspace_root, owner_unit, lane_name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if lock_fh is None:
+        lock_path = lane_leases_lock_file(workspace_root, owner_unit, lane_name)
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        with lock_path.open("a+", encoding="utf-8") as owned_lock_fh:
+            if lease_locking_enabled():
+                fcntl.flock(owned_lock_fh.fileno(), fcntl.LOCK_EX)
+            tmp = path.with_suffix(".json.tmp")
+            tmp.write_text(json.dumps(leases, indent=2) + "\n")
+            os.replace(tmp, path)
+            if lease_locking_enabled():
+                fcntl.flock(owned_lock_fh.fileno(), fcntl.LOCK_UN)
+        return
+
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(leases, indent=2) + "\n")
+    os.replace(tmp, path)
+
+
+def mutate_lane_leases(
+    workspace_root: Path,
+    owner_unit: str,
+    lane_name: str,
+    mutator,
+):
+    lock_path = lane_leases_lock_file(workspace_root, owner_unit, lane_name)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+", encoding="utf-8") as lock_fh:
+        if lease_locking_enabled():
+            fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
+        path = lane_leases_file(workspace_root, owner_unit, lane_name)
+        if path.exists():
+            leases = json.loads(path.read_text())
+        else:
+            leases = []
+        if not lease_locking_enabled():
+            delay = float(os.environ.get("GR2_LEASE_TEST_DELAY", "0"))
+            if delay > 0:
+                time.sleep(delay)
+        result = mutator(leases)
+        if result.get("write"):
+            write_lane_leases(
+                workspace_root,
+                owner_unit,
+                lane_name,
+                result["leases"],
+                lock_fh=lock_fh,
+            )
+        if lease_locking_enabled():
+            fcntl.flock(lock_fh.fileno(), fcntl.LOCK_UN)
+        return result
+
+
+def iter_lane_files(workspace_root: Path, owner_unit: str | None = None) -> list[Path]:
+    agents_root = workspace_root / "agents"
+    if owner_unit:
+        lane_roots = [agents_root / owner_unit / "lanes"]
+    else:
+        lane_roots = [path / "lanes" for path in agents_root.iterdir() if path.is_dir()]
+
+    files: list[Path] = []
+    for root in lane_roots:
+        if not root.exists():
+            continue
+        files.extend(sorted(root.glob("*/lane.toml")))
+    return files
+
+
+def iter_shared_scratchpad_files(workspace_root: Path) -> list[Path]:
+    root = workspace_root / "shared" / "scratchpads"
+    if not root.exists():
+        return []
+    return sorted(root.glob("*/scratchpad.toml"))
+
+
+def now_utc() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def parse_utc(raw: str) -> datetime:
+    return datetime.fromisoformat(raw)
+
+
+def is_stale_lease(lease: dict) -> bool:
+    expires_at = lease.get("expires_at")
+    if not expires_at:
+        return False
+    return parse_utc(expires_at) <= datetime.now(UTC)
+
+
+def build_lease(actor: str, mode: str, ttl_seconds: int) -> dict:
+    acquired = datetime.now(UTC).replace(microsecond=0)
+    expires = acquired + timedelta(seconds=ttl_seconds)
+    return {
+        "actor": actor,
+        "mode": mode,
+        "ttl_seconds": ttl_seconds,
+        "acquired_at": acquired.isoformat(),
+        "expires_at": expires.isoformat(),
+    }
+
+
+def lease_conflicts(existing_mode: str, requested_mode: str) -> bool:
+    matrix = {
+        "edit": {"edit", "exec", "review"},
+        "exec": {"edit", "review"},
+        "review": {"edit", "exec", "review"},
+    }
+    return requested_mode in matrix.get(existing_mode, set())
+
+
+def conflicting_leases(leases: list[dict], actor: str, requested_mode: str) -> tuple[list[dict], list[dict]]:
+    active: list[dict] = []
+    stale: list[dict] = []
+    for lease in leases:
+        if lease["actor"] == actor:
+            continue
+        if not lease_conflicts(lease["mode"], requested_mode):
+            continue
+        if is_stale_lease(lease):
+            stale.append(lease)
+        else:
+            active.append(lease)
+    return active, stale
+
+
+def age_days(path: Path) -> int:
+    modified = datetime.fromtimestamp(path.stat().st_mtime, UTC)
+    return max(0, int((datetime.now(UTC) - modified).total_seconds() // 86400))
+
+
+def parse_repo_list(raw: str) -> list[str]:
+    return [repo.strip() for repo in raw.split(",") if repo.strip()]
+
+
+def parse_branch_arg(raw: str, repos: list[str]) -> dict[str, str]:
+    if "=" not in raw:
+        return {repo: raw for repo in repos}
+
+    branch_map: dict[str, str] = {}
+    for item in raw.split(","):
+        item = item.strip()
+        if not item:
+            continue
+        repo, branch = item.split("=", 1)
+        repo = repo.strip()
+        branch = branch.strip()
+        if repo not in repos:
+            raise SystemExit(f"branch mapping references repo outside lane: {repo}")
+        if not branch:
+            raise SystemExit(f"empty branch in mapping: {item}")
+        branch_map[repo] = branch
+
+    missing = [repo for repo in repos if repo not in branch_map]
+    if missing:
+        raise SystemExit("missing branch mapping for repos: " + ", ".join(missing))
+
+    return branch_map
+
+
+def create_lane(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    spec = load_workspace_spec(workspace_root)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    repo_names = [item["name"] for item in spec.get("repos", [])]
+    repos = parse_repo_list(args.repos)
+
+    missing = [repo for repo in repos if repo not in repo_names]
+    if missing:
+        raise SystemExit(f"unknown repos for lane: {', '.join(missing)}")
+
+    lane_root = lane_dir(workspace_root, args.owner_unit, args.lane_name)
+    lane_root.mkdir(parents=True, exist_ok=True)
+    (lane_root / "repos").mkdir(exist_ok=True)
+    (lane_root / "context").mkdir(exist_ok=True)
+
+    metadata = LaneMetadata(
+        schema_version=LANE_SCHEMA_VERSION,
+        lane_name=args.lane_name,
+        owner_unit=args.owner_unit,
+        agent_id=unit_spec.get("agent_id"),
+        lane_type=args.type,
+        repos=repos,
+        branch_map=parse_branch_arg(args.branch, repos),
+        pr_associations=[],
+        shared_context_roots=["config", ".grip/context/shared"],
+        private_context_roots=[
+            f"agents/{args.owner_unit}/home/context",
+            f"agents/{args.owner_unit}/lanes/{args.lane_name}/context",
+        ],
+        exec_defaults={
+            "parallelism": "workspace-default",
+            "fail_fast": True,
+            "default_command_family": ["build", "test"],
+            "commands": args.default_commands,
+        },
+        creation_source=args.source,
+    )
+    lane_file(workspace_root, args.owner_unit, args.lane_name).write_text(metadata.as_toml())
+    print(lane_file(workspace_root, args.owner_unit, args.lane_name))
+    return 0
+
+
+def enter_lane(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    path = current_lane_file(workspace_root, args.owner_unit)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    previous: list[dict] = []
+    if path.exists():
+        old = json.loads(path.read_text())
+        previous = old.get("recent", [])
+        current = old.get("current")
+        if current:
+            previous.insert(0, current)
+
+    deduped: list[dict] = []
+    seen: set[tuple[str, str]] = set()
+    for item in previous:
+        key = (item["owner_unit"], item["lane_name"])
+        if key in seen or key == (args.owner_unit, args.lane_name):
+            continue
+        seen.add(key)
+        deduped.append(item)
+    deduped = deduped[:5]
+
+    doc = {
+        "current": {
+            "owner_unit": args.owner_unit,
+            "agent_id": unit_spec.get("agent_id"),
+            "lane_name": args.lane_name,
+            "lane_type": lane_doc["lane_type"],
+            "repos": lane_doc.get("repos", []),
+            "actor": args.actor,
+            "entered_at": now_utc(),
+        },
+        "recent": deduped,
+    }
+    path.write_text(json.dumps(doc, indent=2) + "\n")
+    event = {
+        "type": "lane_enter",
+        "agent": args.actor,
+        "agent_id": unit_spec.get("agent_id"),
+        "owner_unit": args.owner_unit,
+        "lane": args.lane_name,
+        "lane_type": lane_doc["lane_type"],
+        "repos": lane_doc.get("repos", []),
+        "timestamp": now_utc(),
+    }
+    emit_lane_event(workspace_root, event)
+    if args.notify_channel:
+        event["channel_message"] = (
+            f'{args.actor} entered {args.owner_unit}/{args.lane_name} '
+            f'[{lane_doc["lane_type"]}] repos={",".join(lane_doc.get("repos", []))}'
+        )
+    if args.recall:
+        emit_recall_lane_event(
+            workspace_root,
+            {
+                "kind": "lane_transition",
+                "action": "enter",
+                "owner_unit": args.owner_unit,
+                "agent_id": unit_spec.get("agent_id"),
+                "actor": args.actor,
+                "lane": args.lane_name,
+                "lane_type": lane_doc["lane_type"],
+                "repos": lane_doc.get("repos", []),
+                "timestamp": event["timestamp"],
+            },
+        )
+    print(path)
+    return 0
+
+
+def exit_lane(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    doc = load_current_lane_doc(workspace_root, args.owner_unit)
+    current_doc = doc.get("current")
+    if not current_doc:
+        raise SystemExit(f"no current lane to exit for unit: {args.owner_unit}")
+    event = {
+        "type": "lane_exit",
+        "agent": args.actor,
+        "agent_id": current_doc.get("agent_id"),
+        "owner_unit": args.owner_unit,
+        "lane": current_doc["lane_name"],
+        "lane_type": current_doc["lane_type"],
+        "repos": current_doc.get("repos", []),
+        "timestamp": now_utc(),
+    }
+    emit_lane_event(workspace_root, event)
+    if args.notify_channel:
+        event["channel_message"] = (
+            f'{args.actor} exited {args.owner_unit}/{current_doc["lane_name"]} '
+            f'[{current_doc["lane_type"]}]'
+        )
+    if args.recall:
+        emit_recall_lane_event(
+            workspace_root,
+            {
+                "kind": "lane_transition",
+                "action": "exit",
+                "owner_unit": args.owner_unit,
+                "agent_id": current_doc.get("agent_id"),
+                "actor": args.actor,
+                "lane": current_doc["lane_name"],
+                "lane_type": current_doc["lane_type"],
+                "repos": current_doc.get("repos", []),
+                "timestamp": event["timestamp"],
+            },
+        )
+
+    recent = doc.get("recent", [])
+    next_current = recent[0] if recent else None
+    updated = {
+        "current": next_current,
+        "recent": recent[1:] if next_current else [],
+    }
+    current_lane_file(workspace_root, args.owner_unit).write_text(json.dumps(updated, indent=2) + "\n")
+    print(current_lane_file(workspace_root, args.owner_unit))
+    return 0
+
+
+def current_lane(args: argparse.Namespace) -> int:
+    doc = load_current_lane_doc(args.workspace_root.resolve(), args.owner_unit)
+    if args.json:
+        print(json.dumps(doc, indent=2))
+        return 0
+    current_doc = doc["current"]
+    print("gr2 prototype current-lane")
+    print(f'owner={current_doc["owner_unit"]} lane={current_doc["lane_name"]} type={current_doc["lane_type"]} actor={current_doc["actor"]}')
+    print(f'entered_at={current_doc["entered_at"]}')
+    recent = doc.get("recent", [])
+    if recent:
+        print("recent:")
+        for item in recent:
+            print(f'  - {item["owner_unit"]}/{item["lane_name"]} ({item["lane_type"]})')
+    return 0
+
+
+def lane_history(args: argparse.Namespace) -> int:
+    rows = [
+        event for event in iter_lane_events(args.workspace_root.resolve())
+        if event.get("owner_unit") == args.owner_unit
+    ]
+    if args.json:
+        print(json.dumps(rows, indent=2))
+        return 0
+    print("TIMESTAMP\tTYPE\tACTOR\tAGENT_ID\tLANE\tREPOS")
+    for row in rows:
+        print(
+            f'{row.get("timestamp","-")}\t{row.get("type","-")}\t{row.get("agent","-")}\t{row.get("agent_id","-")}\t{row.get("lane","-")}\t{",".join(row.get("repos", []))}'
+        )
+    return 0
+
+
+def acquire_lane_lease(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    result = mutate_lane_leases(
+        workspace_root,
+        args.owner_unit,
+        args.lane_name,
+        lambda leases: _acquire_lane_lease_mutation(leases, args),
+    )
+    if result["status"] == "blocked":
+        print(json.dumps(result["payload"], indent=2))
+        return 1
+    if result["status"] == "warning":
+        print(json.dumps(result["warning"], indent=2))
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    emit_lane_event(
+        workspace_root,
+        {
+            "type": "lease_acquire",
+            "agent": args.actor,
+            "agent_id": unit_spec.get("agent_id"),
+            "owner_unit": args.owner_unit,
+            "lane": args.lane_name,
+            "lane_type": lane_doc["lane_type"],
+            "lease_mode": args.mode,
+            "ttl_seconds": args.ttl_seconds,
+            "repos": lane_doc.get("repos", []),
+            "timestamp": now_utc(),
+        },
+    )
+    print(lane_leases_file(workspace_root, args.owner_unit, args.lane_name))
+    return 0
+
+
+def _acquire_lane_lease_mutation(leases: list[dict], args: argparse.Namespace) -> dict:
+    retained = [lease for lease in leases if lease["actor"] != args.actor]
+    active_conflicts, stale_conflicts = conflicting_leases(retained, args.actor, args.mode)
+
+    if active_conflicts:
+        return {
+            "status": "blocked",
+            "payload": {
+                "status": "blocked",
+                "reason": "conflicting-active-lease",
+                "lane": args.lane_name,
+                "owner_unit": args.owner_unit,
+                "requested": {"actor": args.actor, "mode": args.mode},
+                "conflicting_leases": active_conflicts,
+            },
+            "write": False,
+        }
+
+    if stale_conflicts and not args.force:
+        return {
+            "status": "blocked",
+            "payload": {
+                "status": "blocked",
+                "reason": "stale-conflicting-lease",
+                "lane": args.lane_name,
+                "owner_unit": args.owner_unit,
+                "requested": {"actor": args.actor, "mode": args.mode},
+                "conflicting_leases": stale_conflicts,
+                "hint": "rerun with --force to break stale conflicting leases",
+            },
+            "write": False,
+        }
+
+    warning = None
+    if stale_conflicts and args.force:
+        warning = {
+            "status": "warning",
+            "reason": "breaking-stale-conflicting-leases",
+            "broken_leases": stale_conflicts,
+        }
+        stale_actors = {lease["actor"] for lease in stale_conflicts}
+        retained = [lease for lease in retained if lease["actor"] not in stale_actors]
+
+    retained.append(build_lease(args.actor, args.mode, args.ttl_seconds))
+    return {
+        "status": "warning" if warning else "ok",
+        "warning": warning,
+        "leases": retained,
+        "write": True,
+    }
+
+
+def release_lane_lease(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    mutate_lane_leases(
+        workspace_root,
+        args.owner_unit,
+        args.lane_name,
+        lambda leases: {
+            "status": "ok",
+            "leases": [lease for lease in leases if lease["actor"] != args.actor],
+            "write": True,
+        },
+    )
+    emit_lane_event(
+        workspace_root,
+        {
+            "type": "lease_release",
+            "agent": args.actor,
+            "agent_id": unit_spec.get("agent_id"),
+            "owner_unit": args.owner_unit,
+            "lane": args.lane_name,
+            "lane_type": lane_doc["lane_type"],
+            "repos": lane_doc.get("repos", []),
+            "timestamp": now_utc(),
+        },
+    )
+    print(lane_leases_file(workspace_root, args.owner_unit, args.lane_name))
+    return 0
+
+
+def show_lane_leases(args: argparse.Namespace) -> int:
+    leases = load_lane_leases(args.workspace_root.resolve(), args.owner_unit, args.lane_name)
+    if args.json:
+        print(json.dumps(leases, indent=2))
+        return 0
+    print("ACTOR\tMODE\tTTL\tACQUIRED_AT\tEXPIRES_AT\tSTATE")
+    for lease in leases:
+        state = "stale" if is_stale_lease(lease) else "active"
+        print(
+            f'{lease["actor"]}\t{lease["mode"]}\t{lease.get("ttl_seconds", "-")}\t{lease["acquired_at"]}\t{lease.get("expires_at", "-")}\t{state}'
+        )
+    return 0
+
+
+def create_review_lane(args: argparse.Namespace) -> int:
+    lane_name = args.lane_name or f"review-{args.pr_number}"
+    branch = args.branch or f"pr/{args.pr_number}"
+    create_args = argparse.Namespace(
+        workspace_root=args.workspace_root,
+        owner_unit=args.owner_unit,
+        lane_name=lane_name,
+        type="review",
+        repos=args.repo,
+        branch=f"{args.repo}={branch}",
+        source="pull-request",
+        default_commands=[],
+    )
+    create_lane(create_args)
+    lane_path = lane_file(args.workspace_root.resolve(), args.owner_unit, lane_name)
+    content = lane_path.read_text().rstrip()
+    content += f'\n\n[[pr_associations]]\nref = "{args.repo}#{args.pr_number}"\n'
+    lane_path.write_text(content)
+    print(f"created review lane {args.owner_unit}/{lane_name} for {args.repo}#{args.pr_number}")
+    return 0
+
+
+def create_shared_scratchpad(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    root = shared_scratchpad_dir(workspace_root, args.name)
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "docs").mkdir(exist_ok=True)
+    (root / "notes").mkdir(exist_ok=True)
+    (root / "context").mkdir(exist_ok=True)
+
+    scratchpad = SharedScratchpad(
+        schema_version=SCRATCHPAD_SCHEMA_VERSION,
+        name=args.name,
+        kind=args.kind,
+        purpose=args.purpose,
+        participants=sorted(set(args.participant)),
+        linked_refs=args.ref,
+        lifecycle="draft",
+        creation_source=args.source,
+        docs_root=f"shared/scratchpads/{args.name}/docs",
+        notes_root=f"shared/scratchpads/{args.name}/notes",
+        context_root=f"shared/scratchpads/{args.name}/context",
+        created_at=now_utc(),
+        updated_at=now_utc(),
+    )
+    shared_scratchpad_file(workspace_root, args.name).write_text(scratchpad.as_toml())
+    readme = root / "docs" / "README.md"
+    if not readme.exists():
+        readme.write_text(
+            f"# {args.name}\n\nPurpose: {args.purpose}\n\nParticipants: "
+            + (", ".join(scratchpad.participants) if scratchpad.participants else "unassigned")
+            + "\n"
+        )
+    print(shared_scratchpad_file(workspace_root, args.name))
+    return 0
+
+
+def list_lanes(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    print("OWNER\tLANE\tTYPE\tREPOS\tPRS")
+    for path in iter_lane_files(workspace_root, args.owner_unit):
+        doc = tomllib.loads(path.read_text())
+        refs = ",".join(item["ref"] for item in doc.get("pr_associations", [])) or "-"
+        print(
+            f'{doc["owner_unit"]}\t{doc["lane_name"]}\t{doc["lane_type"]}\t{len(doc.get("repos", []))}\t{refs}'
+        )
+    return 0
+
+
+def show_lane(args: argparse.Namespace) -> int:
+    print(lane_file(args.workspace_root.resolve(), args.owner_unit, args.lane_name).read_text())
+    return 0
+
+
+def show_shared_scratchpad(args: argparse.Namespace) -> int:
+    print(shared_scratchpad_file(args.workspace_root.resolve(), args.name).read_text())
+    return 0
+
+
+def list_shared_scratchpads(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    print("NAME\tKIND\tLIFECYCLE\tAGE_DAYS\tPARTICIPANTS\tPURPOSE")
+    for path in iter_shared_scratchpad_files(workspace_root):
+        doc = tomllib.loads(path.read_text())
+        participants = ",".join(doc.get("participants", [])) or "-"
+        print(
+            f'{doc["name"]}\t{doc["kind"]}\t{doc["lifecycle"]}\t{age_days(path)}\t{participants}\t{doc["purpose"]}'
+        )
+    return 0
+
+
+def audit_shared_scratchpads(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    print("NAME\tSTATUS\tAGE_DAYS\tISSUES")
+    for path in iter_shared_scratchpad_files(workspace_root):
+        doc = tomllib.loads(path.read_text())
+        root = path.parent
+        issues: list[str] = []
+        days = age_days(path)
+        docs_root = root / "docs"
+        notes_root = root / "notes"
+        context_root = root / "context"
+
+        if days >= args.stale_days and doc.get("lifecycle") not in {"done", "paused"}:
+            issues.append("stale-active")
+        if not doc.get("participants"):
+            issues.append("no-participants")
+        if not doc.get("linked_refs"):
+            issues.append("no-refs")
+        if not docs_root.exists():
+            issues.append("missing-docs-root")
+        if not notes_root.exists():
+            issues.append("missing-notes-root")
+        if not context_root.exists():
+            issues.append("missing-context-root")
+        if doc.get("kind") == "doc" and not any(docs_root.iterdir()):
+            issues.append("empty-docs")
+
+        status = "ok" if not issues else "needs-attention"
+        print(f'{doc["name"]}\t{status}\t{days}\t{",".join(issues) or "-"}')
+    return 0
+
+
+def plan_promote_scratchpad(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    doc = load_shared_scratchpad_doc(workspace_root, args.name)
+    lane_name = args.lane or f"promote-{args.name}"
+    print("gr2 prototype scratchpad-promotion plan")
+    print(f'scratchpad: {doc["name"]}')
+    print(f'kind: {doc["kind"]}')
+    print(f'lifecycle: {doc["lifecycle"]}')
+    print(f'target repo: {args.target_repo}')
+    print(f'target path: {args.target_path}')
+    print(f'owner unit: {args.owner_unit}')
+    print(f'suggested lane: {lane_name}')
+    print("recommended:")
+    print(
+        f"  1. create or reuse a feature lane for {args.target_repo} under {args.owner_unit}"
+    )
+    print(
+        f"  2. copy content from shared/scratchpads/{doc['name']}/docs into {args.target_repo}:{args.target_path}"
+    )
+    print(f"  3. branch and commit in lane {lane_name}")
+    print("  4. open a PR once the artifact is ready for formal review")
+    if not doc.get("linked_refs"):
+        print("warning: scratchpad has no linked refs; traceability should be added before promotion")
+    return 0
+
+
+def recommend_surface(args: argparse.Namespace) -> int:
+    recommendation = "feature-lane"
+    rationale: list[str] = []
+
+    if args.kind == "review" or args.formal_review:
+        recommendation = "review-lane"
+        rationale.append("formal review or PR inspection should stay isolated")
+    elif args.kind in {"doc", "planning"} and args.collaborative:
+        recommendation = "shared-scratchpad"
+        rationale.append("shared drafting is lighter than a PR and should not invade private lanes")
+    elif args.shared_draft:
+        recommendation = "shared-scratchpad"
+        rationale.append("explicit shared draft requested")
+    elif args.kind == "code" and args.repos > 1:
+        recommendation = "feature-lane"
+        rationale.append("cross-repo implementation needs one named task context")
+    elif args.kind == "code":
+        recommendation = "feature-lane"
+        rationale.append("private implementation should start in an isolated lane")
+    else:
+        recommendation = "feature-lane"
+        rationale.append("default safe choice is an isolated lane")
+
+    print("gr2 prototype surface recommendation")
+    print(f"recommended: {recommendation}")
+    print(f"why: {'; '.join(rationale)}")
+    print("rules:")
+    print("  - use a review lane for formal PR inspection")
+    print("  - use a shared scratchpad for collaborative drafting")
+    print("  - use a feature lane for implementation work")
+    return 0
+
+
+def next_step(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    print("gr2 prototype next-step")
+    print(f'lane: {args.owner_unit}/{lane_doc["lane_name"]}')
+    print(f'type: {lane_doc["lane_type"]}')
+    print(f'repos: {", ".join(lane_doc["repos"])}')
+    if lane_doc.get("pr_associations"):
+        print("mode: review")
+        print("recommended:")
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py plan-exec {workspace_root} {args.owner_unit} {args.lane_name} 'cargo test'"
+        )
+        print("  inspect the review lane, then return to your feature or home lane")
+    elif lane_doc["lane_type"] == "feature":
+        print("mode: feature")
+        print("recommended:")
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py plan-exec {workspace_root} {args.owner_unit} {args.lane_name} 'cargo test'"
+        )
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py list-shared-scratchpads {workspace_root}"
+        )
+    else:
+        print("mode: general")
+        print("recommended:")
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py show-lane {workspace_root} {args.owner_unit} {args.lane_name}"
+        )
+    return 0
+
+
+def plan_exec(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    leases = load_lane_leases(workspace_root, args.owner_unit, args.lane_name)
+    active_conflicts, stale_conflicts = conflicting_leases(leases, "agent:exec-planner", "exec")
+    if active_conflicts:
+        payload = {
+            "status": "blocked",
+            "reason": "conflicting-active-lease",
+            "lane": lane_doc["lane_name"],
+            "owner_unit": lane_doc["owner_unit"],
+            "requested_mode": "exec",
+            "conflicting_leases": active_conflicts,
+        }
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            print("gr2 lane-exec prototype")
+            print("status=blocked reason=conflicting-active-lease")
+            for lease in active_conflicts:
+                print(f'conflict: actor={lease["actor"]} mode={lease["mode"]} acquired_at={lease["acquired_at"]}')
+        return 0
+    if stale_conflicts:
+        payload = {
+            "status": "blocked",
+            "reason": "stale-conflicting-lease",
+            "lane": lane_doc["lane_name"],
+            "owner_unit": lane_doc["owner_unit"],
+            "requested_mode": "exec",
+            "conflicting_leases": stale_conflicts,
+            "hint": "break stale leases with acquire-lane-lease --force or clean them up first",
+        }
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            print("gr2 lane-exec prototype")
+            print("status=blocked reason=stale-conflicting-lease")
+            for lease in stale_conflicts:
+                print(f'stale-conflict: actor={lease["actor"]} mode={lease["mode"]} expires_at={lease.get("expires_at", "-")}')
+        return 0
+
+    selected_repos = lane_doc["repos"]
+    if args.repos:
+        requested = parse_repo_list(args.repos)
+        selected_repos = [repo for repo in selected_repos if repo in requested]
+
+    command_argv = shlex.split(args.command_text)
+    rows = []
+    for repo in selected_repos:
+        rows.append(
+            {
+                "lane": lane_doc["lane_name"],
+                "owner_unit": lane_doc["owner_unit"],
+                "repo": repo,
+                "branch": lane_doc["branch_map"].get(repo),
+                "cwd": str(
+                    workspace_root
+                    / "agents"
+                    / args.owner_unit
+                    / "lanes"
+                    / args.lane_name
+                    / "repos"
+                    / repo
+                ),
+                "command": command_argv,
+                "shared_context_roots": lane_doc.get("context", {}).get("shared_roots", []),
+                "private_context_roots": lane_doc.get("context", {}).get("private_roots", []),
+                "fail_fast": lane_doc["exec_defaults"]["fail_fast"],
+            }
+        )
+
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        print("gr2 lane-exec prototype")
+        print(
+            f'owner={lane_doc["owner_unit"]} lane={lane_doc["lane_name"]} type={lane_doc["lane_type"]} fail_fast={lane_doc["exec_defaults"]["fail_fast"]}'
+        )
+        print("LANE\tREPO\tBRANCH\tCWD\tCOMMAND")
+        for row in rows:
+            print(
+                f'{row["lane"]}\t{row["repo"]}\t{row["branch"]}\t{row["cwd"]}\t{" ".join(row["command"])}'
+            )
+    return 0
+
+
+def main() -> int:
+    args = parse_args()
+    if args.command == "create-lane":
+        return create_lane(args)
+    if args.command == "enter-lane":
+        return enter_lane(args)
+    if args.command == "exit-lane":
+        return exit_lane(args)
+    if args.command == "current-lane":
+        return current_lane(args)
+    if args.command == "lane-history":
+        return lane_history(args)
+    if args.command == "create-review-lane":
+        return create_review_lane(args)
+    if args.command == "show-lane":
+        return show_lane(args)
+    if args.command == "list-lanes":
+        return list_lanes(args)
+    if args.command == "next-step":
+        return next_step(args)
+    if args.command == "plan-exec":
+        return plan_exec(args)
+    if args.command == "acquire-lane-lease":
+        return acquire_lane_lease(args)
+    if args.command == "release-lane-lease":
+        return release_lane_lease(args)
+    if args.command == "show-lane-leases":
+        return show_lane_leases(args)
+    if args.command == "create-shared-scratchpad":
+        return create_shared_scratchpad(args)
+    if args.command == "show-shared-scratchpad":
+        return show_shared_scratchpad(args)
+    if args.command == "list-shared-scratchpads":
+        return list_shared_scratchpads(args)
+    if args.command == "audit-shared-scratchpads":
+        return audit_shared_scratchpads(args)
+    if args.command == "plan-promote-scratchpad":
+        return plan_promote_scratchpad(args)
+    if args.command == "recommend-surface":
+        return recommend_surface(args)
+    raise SystemExit(f"unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/prototypes/layout_model_probe.py b/gr2/prototypes/layout_model_probe.py
new file mode 100644
index 00000000..939eca61
--- /dev/null
+++ b/gr2/prototypes/layout_model_probe.py
@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Assess which workspace layout model best matches the observed gr2 behavior.
+
+This is a UX prototype. It does not prescribe the final architecture on its own.
+It makes the current mismatch explicit so we can iterate with evidence.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import tomllib
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Probe observed gr2 layout vs candidate models")
+    parser.add_argument("workspace_root", type=Path)
+    parser.add_argument("--owner-unit", required=True)
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def load_spec(workspace_root: Path) -> dict:
+    with (workspace_root / ".grip" / "workspace_spec.toml").open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def repo_names(spec: dict) -> list[str]:
+    return [repo["name"] for repo in spec.get("repos", [])]
+
+
+def probe(workspace_root: Path, owner_unit: str) -> dict:
+    spec = load_spec(workspace_root)
+    repos = repo_names(spec)
+    observations: list[dict[str, object]] = []
+    shared_git_count = 0
+    unit_git_count = 0
+
+    for repo in repos:
+        shared_root = workspace_root / "repos" / repo
+        unit_root = workspace_root / "agents" / owner_unit / repo
+        lane_root = workspace_root / "agents" / owner_unit / "lanes" / "feat-auth" / "repos" / repo
+
+        shared_git = (shared_root / ".git").exists()
+        unit_git = (unit_root / ".git").exists()
+        lane_git = (lane_root / ".git").exists()
+        shared_exists = shared_root.exists()
+        unit_exists = unit_root.exists()
+
+        if shared_git:
+            shared_git_count += 1
+        if unit_git:
+            unit_git_count += 1
+
+        observations.append(
+            {
+                "repo": repo,
+                "shared_path_exists": shared_exists,
+                "shared_git": shared_git,
+                "unit_path_exists": unit_exists,
+                "unit_git": unit_git,
+                "lane_git": lane_git,
+            }
+        )
+
+    shared_first_score = 0
+    unit_first_score = 0
+    reasons: list[str] = []
+
+    if unit_git_count == len(repos):
+        unit_first_score += 3
+        reasons.append("all repos materialized as unit-local git checkouts")
+    if shared_git_count == len(repos):
+        shared_first_score += 3
+        reasons.append("all repos materialized as shared git checkouts")
+    if shared_git_count == 0 and any(item["shared_path_exists"] for item in observations):
+        unit_first_score += 2
+        reasons.append("shared repo paths exist as placeholders rather than active checkouts")
+    if any(item["lane_git"] for item in observations):
+        shared_first_score += 1
+        unit_first_score += 1
+        reasons.append("lane-local repo materialization exists, so a routed model may be emerging")
+    else:
+        unit_first_score += 1
+        reasons.append("lane-local repos are not yet materialized")
+
+    if unit_first_score > shared_first_score:
+        recommendation = "ratify-unit-local-first"
+        summary = (
+            "Current behavior matches a unit-local-first model more closely than a shared-repo-first model."
+        )
+    elif shared_first_score > unit_first_score:
+        recommendation = "push-shared-repo-model"
+        summary = (
+            "Current behavior already resembles a shared-repo-first model strongly enough to continue that direction."
+        )
+    else:
+        recommendation = "hybrid-needs-clarification"
+        summary = "Observed behavior is split enough that the model should be clarified explicitly."
+
+    return {
+        "owner_unit": owner_unit,
+        "recommendation": recommendation,
+        "summary": summary,
+        "shared_first_score": shared_first_score,
+        "unit_first_score": unit_first_score,
+        "reasons": reasons,
+        "observations": observations,
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    result = probe(args.workspace_root.resolve(), args.owner_unit)
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return 0
+
+    print("gr2 prototype layout-model probe")
+    print(f"owner: {result['owner_unit']}")
+    print(f"recommendation: {result['recommendation']}")
+    print(f"summary: {result['summary']}")
+    print(f"score shared-first={result['shared_first_score']} unit-local-first={result['unit_first_score']}")
+    print("reasons:")
+    for reason in result["reasons"]:
+        print(f"- {reason}")
+    print("observations:")
+    print("REPO\tSHARED_PATH\tSHARED_GIT\tUNIT_PATH\tUNIT_GIT\tLANE_GIT")
+    for row in result["observations"]:
+        print(
+            f"{row['repo']}\t{str(row['shared_path_exists']).lower()}\t{str(row['shared_git']).lower()}\t"
+            f"{str(row['unit_path_exists']).lower()}\t{str(row['unit_git']).lower()}\t{str(row['lane_git']).lower()}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/real_git_lane_materialization.py b/gr2/prototypes/real_git_lane_materialization.py
new file mode 100644
index 00000000..7068c176
--- /dev/null
+++ b/gr2/prototypes/real_git_lane_materialization.py
@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Prototype real-git same-repo multi-agent lane materialization."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Verify real-git same-repo lane materialization"
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        help="optional workspace root; defaults to a temporary workspace",
+    )
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def run(
+    argv: list[str],
+    *,
+    cwd: Path | None = None,
+    capture: bool = False,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        check=check,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def init_workspace(workspace_root: Path, bare_remote: Path) -> None:
+    (workspace_root / ".grip").mkdir(parents=True, exist_ok=True)
+    (workspace_root / "agents").mkdir(exist_ok=True)
+    spec = f"""schema_version = 1
+workspace_name = "real-git-lane-materialization"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{bare_remote}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+agent_id = "atlas-agent"
+repos = ["app"]
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+agent_id = "apollo-agent"
+repos = ["app"]
+"""
+    (workspace_root / ".grip" / "workspace_spec.toml").write_text(spec)
+
+
+def seed_bare_remote(root: Path) -> Path:
+    remotes = root / "remotes"
+    work = root / "seed-work"
+    remotes.mkdir(parents=True, exist_ok=True)
+    run(["git", "init", "--bare", str(remotes / "app.git")])
+    run(["git", "init", str(work)])
+    run(["git", "config", "user.name", "Playground User"], cwd=work)
+    run(["git", "config", "user.email", "playground@example.com"], cwd=work)
+    (work / "README.md").write_text("# app\n")
+    run(["git", "add", "README.md"], cwd=work)
+    run(["git", "commit", "-m", "Initial commit"], cwd=work)
+    run(["git", "branch", "-M", "main"], cwd=work)
+    run(["git", "remote", "add", "origin", str(remotes / "app.git")], cwd=work)
+    run(["git", "push", "-u", "origin", "main"], cwd=work)
+    return remotes / "app.git"
+
+
+def create_lane(
+    root: Path, workspace_root: Path, owner_unit: str, lane_name: str, branch: str
+) -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-lane",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "--repos",
+            "app",
+            "--branch",
+            branch,
+        ]
+    )
+
+
+def plan_exec_json(
+    root: Path, workspace_root: Path, owner_unit: str, lane_name: str
+) -> list[dict]:
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "plan-exec",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "git status",
+            "--json",
+        ],
+        capture=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def configure_checkout(repo_path: Path, user_name: str, user_email: str) -> None:
+    run(["git", "config", "user.name", user_name], cwd=repo_path)
+    run(["git", "config", "user.email", user_email], cwd=repo_path)
+
+
+def clone_into_lane(
+    remote: Path, cwd_path: Path, branch: str, user_name: str, user_email: str
+) -> None:
+    cwd_path.parent.mkdir(parents=True, exist_ok=True)
+    run(["git", "clone", str(remote), str(cwd_path)])
+    configure_checkout(cwd_path, user_name, user_email)
+    run(["git", "checkout", "-b", branch], cwd=cwd_path)
+
+
+def commit_lane_change(
+    repo_path: Path, filename: str, contents: str, message: str
+) -> str:
+    (repo_path / filename).write_text(contents)
+    run(["git", "add", filename], cwd=repo_path)
+    run(["git", "commit", "-m", message], cwd=repo_path)
+    proc = run(["git", "rev-parse", "HEAD"], cwd=repo_path, capture=True)
+    return proc.stdout.strip()
+
+
+def verify(workspace_root: Path) -> dict:
+    root = repo_root()
+    remote = seed_bare_remote(workspace_root / ".tmp")
+    init_workspace(workspace_root, remote)
+
+    create_lane(root, workspace_root, "atlas", "feat-router", "feat/router")
+    create_lane(root, workspace_root, "apollo", "feat-materialize", "feat/materialize")
+
+    atlas_plan = plan_exec_json(root, workspace_root, "atlas", "feat-router")
+    apollo_plan = plan_exec_json(root, workspace_root, "apollo", "feat-materialize")
+
+    atlas_cwd = Path(atlas_plan[0]["cwd"])
+    apollo_cwd = Path(apollo_plan[0]["cwd"])
+
+    clone_into_lane(remote, atlas_cwd, "feat/router", "Atlas User", "atlas@example.com")
+    clone_into_lane(
+        remote,
+        apollo_cwd,
+        "feat/materialize",
+        "Apollo User",
+        "apollo@example.com",
+    )
+
+    atlas_commit = commit_lane_change(
+        atlas_cwd, "atlas.txt", "atlas lane change\n", "atlas lane commit"
+    )
+    apollo_commit = commit_lane_change(
+        apollo_cwd, "apollo.txt", "apollo lane change\n", "apollo lane commit"
+    )
+
+    atlas_status = run(["git", "status", "--short"], cwd=atlas_cwd, capture=True).stdout.strip()
+    apollo_status = run(["git", "status", "--short"], cwd=apollo_cwd, capture=True).stdout.strip()
+
+    result = {
+        "atlas_cwd": str(atlas_cwd),
+        "apollo_cwd": str(apollo_cwd),
+        "cwd_collision": atlas_cwd == apollo_cwd,
+        "atlas_commit": atlas_commit,
+        "apollo_commit": apollo_commit,
+        "commit_collision": atlas_commit == apollo_commit,
+        "atlas_has_apollo_file": (atlas_cwd / "apollo.txt").exists(),
+        "apollo_has_atlas_file": (apollo_cwd / "atlas.txt").exists(),
+        "atlas_clean": atlas_status == "",
+        "apollo_clean": apollo_status == "",
+    }
+    result["verdict"] = (
+        "holds"
+        if not result["cwd_collision"]
+        and not result["commit_collision"]
+        and not result["atlas_has_apollo_file"]
+        and not result["apollo_has_atlas_file"]
+        and result["atlas_clean"]
+        and result["apollo_clean"]
+        else "fails"
+    )
+    return result
+
+
+def main() -> int:
+    args = parse_args()
+    if args.workspace_root:
+        workspace_root = args.workspace_root.resolve()
+        if workspace_root.exists():
+            shutil.rmtree(workspace_root)
+        workspace_root.mkdir(parents=True, exist_ok=True)
+        result = verify(workspace_root)
+    else:
+        with tempfile.TemporaryDirectory(prefix="gr2-real-git-lanes-") as tmp:
+            workspace_root = Path(tmp)
+            result = verify(workspace_root)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("gr2 real-git same-repo lane materialization")
+        print(f'workspace: {workspace_root}')
+        print(f'verdict: {result["verdict"]}')
+        print(f'atlas cwd: {result["atlas_cwd"]}')
+        print(f'apollo cwd: {result["apollo_cwd"]}')
+        print(f'cwd collision: {result["cwd_collision"]}')
+        print(f'commit collision: {result["commit_collision"]}')
+        print(f'atlas sees apollo file: {result["atlas_has_apollo_file"]}')
+        print(f'apollo sees atlas file: {result["apollo_has_atlas_file"]}')
+        print(f'atlas clean: {result["atlas_clean"]}')
+        print(f'apollo clean: {result["apollo_clean"]}')
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/real_git_playground.py b/gr2/prototypes/real_git_playground.py
new file mode 100644
index 00000000..e140c883
--- /dev/null
+++ b/gr2/prototypes/real_git_playground.py
@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""Bootstrap and verify a real-git gr2 playground workspace.
+
+This harness is intentionally pragmatic:
+
+- it uses actual GitHub repos in synapt-dev
+- it exercises the current shipped gr2 surfaces against real remotes
+- it combines current gr2 commands with prototype-only scratchpad commands
+
+The goal is not to pretend gr2 is further along than it is. The goal is to
+pressure the UX against real git state so we can iterate with data.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+PLAYGROUND_REPOS = {
+    "app": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-app.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-app.git",
+    },
+    "api": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-api.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-api.git",
+    },
+    "web": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-web.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-web.git",
+    },
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Bootstrap a real-git gr2 playground workspace"
+    )
+    parser.add_argument("workspace_root", type=Path)
+    parser.add_argument("--owner-unit", default="atlas")
+    parser.add_argument("--workspace-name", default="gr2-real-git-playground")
+    parser.add_argument(
+        "--keep-existing",
+        action="store_true",
+        help="reuse an existing workspace root instead of failing",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["ssh", "https"],
+        default="ssh",
+        help="git remote transport to use for playground repos",
+    )
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def gr2_binary(root: Path) -> Path:
+    binary = root / "target" / "debug" / "gr2"
+    if binary.exists():
+        return binary
+    run(["cargo", "build", "--quiet", "--bin", "gr2"], cwd=root)
+    return binary
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def transport_probe(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "repo_transport_probe.py"
+
+
+def layout_probe(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "layout_model_probe.py"
+
+
+def repo_url(repo_name: str, transport: str) -> str:
+    return PLAYGROUND_REPOS[repo_name][transport]
+
+
+def run(
+    argv: list[str],
+    *,
+    cwd: Path | None = None,
+    capture: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    print("+", " ".join(argv))
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        check=True,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def gr2_supports_exec(gr2: Path) -> bool:
+    help_out = run([str(gr2), "--help"], capture=True)
+    return "\n  exec" in help_out.stdout
+
+
+def write_workspace_spec(
+    workspace_root: Path, owner_unit: str, workspace_name: str, transport: str
+) -> None:
+    spec = f"""schema_version = 1
+workspace_name = "{workspace_name}"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{repo_url("app", transport)}"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "{repo_url("api", transport)}"
+
+[[repos]]
+name = "web"
+path = "repos/web"
+url = "{repo_url("web", transport)}"
+
+[[units]]
+name = "{owner_unit}"
+path = "agents/{owner_unit}"
+repos = ["app", "api", "web"]
+"""
+    spec_path = workspace_root / ".grip" / "workspace_spec.toml"
+    spec_path.write_text(spec)
+
+
+def ensure(condition: bool, message: str) -> None:
+    if not condition:
+        raise SystemExit(message)
+
+
+def unit_repo_path(workspace_root: Path, owner_unit: str, repo_name: str) -> Path:
+    return workspace_root / "agents" / owner_unit / repo_name
+
+
+def verify_paths(workspace_root: Path, owner_unit: str) -> None:
+    for rel in [
+        ".grip/workspace.toml",
+        ".grip/workspace_spec.toml",
+        f"agents/{owner_unit}/app/.git",
+        f"agents/{owner_unit}/api/.git",
+        f"agents/{owner_unit}/web/.git",
+        f".grip/state/lanes/{owner_unit}/feat-auth.toml",
+        f".grip/state/lanes/{owner_unit}/feat-web.toml",
+        f".grip/state/lanes/{owner_unit}/review-app-123.toml",
+        "shared/scratchpads/blog-draft/scratchpad.toml",
+    ]:
+        ensure((workspace_root / rel).exists(), f"expected path missing: {rel}")
+
+
+def main() -> int:
+    args = parse_args()
+    root = repo_root()
+    workspace_root = args.workspace_root.resolve()
+
+    if workspace_root.exists() and not args.keep_existing:
+        if any(workspace_root.iterdir()):
+            raise SystemExit(
+                f"workspace root already exists and is not empty: {workspace_root} "
+                "(pass --keep-existing to reuse)"
+            )
+        workspace_root.rmdir()
+
+    gr2 = gr2_binary(root)
+    lane_script = lane_proto(root)
+    probe_script = transport_probe(root)
+    layout_script = layout_probe(root)
+    has_exec = gr2_supports_exec(gr2)
+
+    if not workspace_root.exists():
+        run(
+            [
+                str(gr2),
+                "init",
+                str(workspace_root),
+                "--name",
+                args.workspace_name,
+            ],
+            cwd=root,
+        )
+
+    run([str(gr2), "unit", "add", args.owner_unit], cwd=workspace_root)
+
+    for repo_name in PLAYGROUND_REPOS:
+        run(
+            [str(gr2), "repo", "add", repo_name, repo_url(repo_name, args.transport)],
+            cwd=workspace_root,
+        )
+
+    write_workspace_spec(
+        workspace_root, args.owner_unit, args.workspace_name, args.transport
+    )
+
+    try:
+        probe = run(
+            [
+                sys.executable,
+                str(probe_script),
+                str(workspace_root / ".grip" / "workspace_spec.toml"),
+            ],
+            cwd=root,
+            capture=True,
+        )
+        print(probe.stdout)
+    except subprocess.CalledProcessError as exc:
+        if exc.stdout:
+            print(exc.stdout)
+        raise SystemExit(
+            f"repo transport probe failed before apply.\n"
+            f"transport={args.transport}\n"
+            "The selected remotes are not ready to clone from this environment.\n"
+            "Fix auth/transport first or rerun with a different `--transport`."
+        ) from exc
+
+    run([str(gr2), "spec", "validate"], cwd=workspace_root)
+    run([str(gr2), "plan", "--yes"], cwd=workspace_root)
+    try:
+        run([str(gr2), "apply", "--yes"], cwd=workspace_root)
+    except subprocess.CalledProcessError as exc:
+        raise SystemExit(
+            f"gr2 apply failed during real-git bootstrap.\n"
+            f"transport={args.transport}\n"
+            "Probe output above should indicate whether the failure is due to "
+            "transport reachability or authentication.\n"
+            "This usually means the selected Git transport is not reachable or "
+            "authenticated in the current environment.\n"
+            "Try rerunning with `--transport https` or `--transport ssh` as appropriate."
+        ) from exc
+
+    run(["git", "-C", str(unit_repo_path(workspace_root, args.owner_unit, "app")), "checkout", "-b", "feat/auth"])
+    run(["git", "-C", str(unit_repo_path(workspace_root, args.owner_unit, "api")), "checkout", "-b", "feat/auth"])
+    run(["git", "-C", str(unit_repo_path(workspace_root, args.owner_unit, "web")), "checkout", "-b", "feat/web"])
+
+    app_readme = unit_repo_path(workspace_root, args.owner_unit, "app") / "README.md"
+    app_readme.write_text(app_readme.read_text() + "\nDirty playground change.\n")
+
+    repo_status = run(
+        [str(gr2), "repo", "status"],
+        cwd=workspace_root,
+        capture=True,
+    )
+    print(repo_status.stdout)
+
+    run(
+        [
+            str(gr2),
+            "lane",
+            "create",
+            "feat-auth",
+            "--owner-unit",
+            args.owner_unit,
+            "--repo",
+            "app",
+            "--repo",
+            "api",
+            "--branch",
+            "app=feat/auth",
+            "--branch",
+            "api=feat/auth",
+            "--exec",
+            "cargo test -p app",
+            "--exec",
+            "cargo test -p api",
+        ],
+        cwd=workspace_root,
+    )
+    run(
+        [
+            str(gr2),
+            "lane",
+            "create",
+            "feat-web",
+            "--owner-unit",
+            args.owner_unit,
+            "--repo",
+            "web",
+            "--branch",
+            "web=feat/web",
+            "--exec",
+            "npm test",
+        ],
+        cwd=workspace_root,
+    )
+    run(
+        [
+            str(gr2),
+            "lane",
+            "create",
+            "review-app-123",
+            "--owner-unit",
+            args.owner_unit,
+            "--type",
+            "review",
+            "--repo",
+            "app",
+            "--pr",
+            "app:123",
+            "--branch",
+            "app=review/pr-123",
+        ],
+        cwd=workspace_root,
+    )
+
+    lane_list = run(
+        [str(gr2), "lane", "list", "--owner-unit", args.owner_unit],
+        cwd=workspace_root,
+        capture=True,
+    )
+    print(lane_list.stdout)
+
+    if has_exec:
+        exec_status = run(
+            [
+                str(gr2),
+                "exec",
+                "status",
+                "--lane",
+                "feat-auth",
+                "--owner-unit",
+                args.owner_unit,
+            ],
+            cwd=workspace_root,
+            capture=True,
+        )
+        print(exec_status.stdout)
+    else:
+        print(
+            "note: this branch does not ship `gr2 exec status`; "
+            "real-git exec verification is deferred until the exec surface lands "
+            "on the same branch as the playground flow"
+        )
+
+    run(
+        [
+            sys.executable,
+            str(lane_script),
+            "create-shared-scratchpad",
+            str(workspace_root),
+            "blog-draft",
+            "--kind",
+            "doc",
+            "--purpose",
+            "Real-git shared drafting verification",
+            "--participant",
+            args.owner_unit,
+            "--participant",
+            "layne",
+            "--ref",
+            "grip#552",
+            "--ref",
+            "grip#555",
+        ],
+        cwd=root,
+    )
+    scratchpads = run(
+        [sys.executable, str(lane_script), "list-shared-scratchpads", str(workspace_root)],
+        cwd=root,
+        capture=True,
+    )
+    print(scratchpads.stdout)
+
+    recommendation = run(
+        [
+            sys.executable,
+            str(lane_script),
+            "recommend-surface",
+            "--kind",
+            "doc",
+            "--collaborative",
+            "--shared-draft",
+            "--repos",
+            "1",
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(recommendation.stdout)
+
+    scratchpad_audit = run(
+        [
+            sys.executable,
+            str(lane_script),
+            "audit-shared-scratchpads",
+            str(workspace_root),
+            "--stale-days",
+            "1",
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(scratchpad_audit.stdout)
+
+    promotion_plan = run(
+        [
+            sys.executable,
+            str(lane_script),
+            "plan-promote-scratchpad",
+            str(workspace_root),
+            "blog-draft",
+            "--target-repo",
+            "app",
+            "--target-path",
+            "docs/blog/blog-draft.md",
+            "--owner-unit",
+            args.owner_unit,
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(promotion_plan.stdout)
+
+    layout_assessment = run(
+        [
+            sys.executable,
+            str(layout_script),
+            str(workspace_root),
+            "--owner-unit",
+            args.owner_unit,
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(layout_assessment.stdout)
+
+    verify_paths(workspace_root, args.owner_unit)
+
+    print("\nreal-git playground bootstrap complete")
+    print(f"workspace: {workspace_root}")
+    print("verified:")
+    print("- real remotes cloned into unit-local repo paths")
+    print("- dirty local git state can be observed")
+    print("- multiple lanes can coexist in metadata")
+    print("- the prototype can recommend lane vs review vs shared scratchpad")
+    print("- the prototype can audit scratchpads for stale or weak tracking")
+    print("- the prototype can show a promotion path from scratchpad to repo artifact")
+    print("- the prototype can assess whether the observed layout matches the intended model")
+    if has_exec:
+        print("- exec status stays lane-scoped")
+    else:
+        print("- exec verification is still pending branch convergence with the shipped exec surface")
+    print("- shared scratchpad can exist beside private lanes")
+    print("observation:")
+    print("- current apply converges unit-local checkouts under agents/<unit>/..., not repos/<repo>")
+    if not has_exec:
+        print("- current prototype and shipped lane metadata are not yet unified enough for one exec harness")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/repo_maintenance_prototype.py b/gr2/prototypes/repo_maintenance_prototype.py
new file mode 100644
index 00000000..740ec259
--- /dev/null
+++ b/gr2/prototypes/repo_maintenance_prototype.py
@@ -0,0 +1,443 @@
+#!/usr/bin/env python3
+"""Prototype planner for gr2 repo maintenance policy.
+
+This is intentionally separate from gr2 apply. It answers:
+- which repos are missing and need clone/materialization
+- which repos are safe to fast-forward
+- which repos require explicit human intervention
+- where autostash would be required to proceed
+
+The goal is to keep workspace structure convergence (`gr2 apply`) separate
+from repo state convergence (`gr2 repo sync` / `gr2 repo pull`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoSpec:
+    name: str
+    path: str
+    url: str
+
+
+@dataclasses.dataclass(frozen=True)
+class UnitSpec:
+    name: str
+    path: str
+    repos: list[str]
+
+
+@dataclasses.dataclass(frozen=True)
+class WorkspaceSpec:
+    schema_version: int
+    workspace_name: str
+    repos: list[RepoSpec]
+    units: list[UnitSpec]
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoTarget:
+    scope: str
+    target_name: str
+    repo_name: str
+    path: Path
+    url: str
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoPolicy:
+    sync_mode: str
+    dirty_policy: str
+    tracked_branch: str | None
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoStatus:
+    exists: bool
+    is_git_repo: bool
+    branch: str | None
+    upstream: str | None
+    dirty: bool
+    ahead: int
+    behind: int
+    detached: bool
+
+
+@dataclasses.dataclass(frozen=True)
+class PlannedAction:
+    target: RepoTarget
+    action: str
+    reason: str
+    status: RepoStatus
+    policy: RepoPolicy
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "scope": self.target.scope,
+            "target": self.target.target_name,
+            "repo": self.target.repo_name,
+            "path": str(self.target.path),
+            "action": self.action,
+            "reason": self.reason,
+            "status": dataclasses.asdict(self.status),
+            "policy": dataclasses.asdict(self.policy),
+        }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Prototype gr2 repo maintenance planner")
+    parser.add_argument("workspace_root", type=Path, help="gr2 workspace root")
+    parser.add_argument(
+        "--spec",
+        type=Path,
+        help="path to workspace_spec.toml (defaults to <workspace>/.grip/workspace_spec.toml)",
+    )
+    parser.add_argument(
+        "--policy",
+        type=Path,
+        help="optional TOML policy file for branch/sync defaults",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit machine-readable JSON instead of a table",
+    )
+    return parser.parse_args()
+
+
+def read_workspace_spec(spec_path: Path) -> WorkspaceSpec:
+    with spec_path.open("rb") as fh:
+        raw = tomllib.load(fh)
+
+    repos = [
+        RepoSpec(name=item["name"], path=item["path"], url=item["url"])
+        for item in raw.get("repos", [])
+    ]
+    units = [
+        UnitSpec(
+            name=item["name"],
+            path=item["path"],
+            repos=list(item.get("repos", [])),
+        )
+        for item in raw.get("units", [])
+    ]
+    return WorkspaceSpec(
+        schema_version=raw["schema_version"],
+        workspace_name=raw["workspace_name"],
+        repos=repos,
+        units=units,
+    )
+
+
+def read_policy(policy_path: Path | None) -> dict[str, object]:
+    if policy_path is None:
+        return {}
+    with policy_path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def derive_targets(workspace_root: Path, spec: WorkspaceSpec) -> list[RepoTarget]:
+    shared_targets = [
+        RepoTarget(
+            scope="shared",
+            target_name=repo.name,
+            repo_name=repo.name,
+            path=workspace_root / repo.path,
+            url=repo.url,
+        )
+        for repo in spec.repos
+    ]
+
+    repo_map = {repo.name: repo for repo in spec.repos}
+    unit_targets: list[RepoTarget] = []
+    for unit in spec.units:
+        for repo_name in unit.repos:
+            repo = repo_map[repo_name]
+            unit_targets.append(
+                RepoTarget(
+                    scope="unit",
+                    target_name=unit.name,
+                    repo_name=repo_name,
+                    path=workspace_root / unit.path / repo_name,
+                    url=repo.url,
+                )
+            )
+
+    return shared_targets + unit_targets
+
+
+def policy_for(target: RepoTarget, policy_doc: dict[str, object]) -> RepoPolicy:
+    defaults = policy_doc.get("defaults", {})
+    repos = policy_doc.get("repos", {})
+
+    if not isinstance(defaults, dict):
+        defaults = {}
+    if not isinstance(repos, dict):
+        repos = {}
+
+    repo_overrides = repos.get(target.repo_name, {})
+    if not isinstance(repo_overrides, dict):
+        repo_overrides = {}
+
+    if target.scope == "shared":
+        sync_mode = str(repo_overrides.get("sync", defaults.get("shared_sync", "ff-only")))
+    else:
+        sync_mode = str(repo_overrides.get("sync", defaults.get("unit_sync", "explicit")))
+
+    dirty_policy = str(repo_overrides.get("dirty", defaults.get("dirty", "block")))
+    tracked_branch = repo_overrides.get("tracked_branch", defaults.get("tracked_branch"))
+    tracked_branch = str(tracked_branch) if tracked_branch is not None else None
+
+    return RepoPolicy(
+        sync_mode=sync_mode,
+        dirty_policy=dirty_policy,
+        tracked_branch=tracked_branch,
+    )
+
+
+def run_git(repo_path: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=repo_path,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def inspect_repo(path: Path) -> RepoStatus:
+    if not path.exists():
+        return RepoStatus(
+            exists=False,
+            is_git_repo=False,
+            branch=None,
+            upstream=None,
+            dirty=False,
+            ahead=0,
+            behind=0,
+            detached=False,
+        )
+
+    git_check = run_git(path, "rev-parse", "--is-inside-work-tree")
+    if git_check.returncode != 0 or git_check.stdout.strip() != "true":
+        return RepoStatus(
+            exists=True,
+            is_git_repo=False,
+            branch=None,
+            upstream=None,
+            dirty=False,
+            ahead=0,
+            behind=0,
+            detached=False,
+        )
+
+    branch_proc = run_git(path, "symbolic-ref", "--quiet", "--short", "HEAD")
+    detached = branch_proc.returncode != 0
+    branch = None if detached else branch_proc.stdout.strip()
+
+    upstream_proc = run_git(path, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}")
+    upstream = upstream_proc.stdout.strip() if upstream_proc.returncode == 0 else None
+
+    dirty_proc = run_git(path, "status", "--porcelain")
+    dirty = bool(dirty_proc.stdout.strip())
+
+    ahead = 0
+    behind = 0
+    if upstream:
+        counts_proc = run_git(path, "rev-list", "--left-right", "--count", f"HEAD...{upstream}")
+        if counts_proc.returncode == 0:
+            left, right = counts_proc.stdout.strip().split()
+            ahead = int(left)
+            behind = int(right)
+
+    return RepoStatus(
+        exists=True,
+        is_git_repo=True,
+        branch=branch,
+        upstream=upstream,
+        dirty=dirty,
+        ahead=ahead,
+        behind=behind,
+        detached=detached,
+    )
+
+
+def classify(target: RepoTarget, status: RepoStatus, policy: RepoPolicy) -> PlannedAction:
+    if not status.exists:
+        return PlannedAction(target, "clone_missing", "repo path is absent", status, policy)
+
+    if not status.is_git_repo:
+        return PlannedAction(
+            target,
+            "block_path_conflict",
+            "target path exists but is not a git repo",
+            status,
+            policy,
+        )
+
+    if status.detached:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            "repo is on a detached HEAD; do not move automatically",
+            status,
+            policy,
+        )
+
+    if policy.tracked_branch and status.branch != policy.tracked_branch:
+        if target.scope == "shared" and not status.dirty and status.ahead == 0:
+            return PlannedAction(
+                target,
+                "checkout_branch",
+                f"shared repo should be on {policy.tracked_branch}, found {status.branch}",
+                status,
+                policy,
+            )
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"branch mismatch: expected {policy.tracked_branch}, found {status.branch}",
+            status,
+            policy,
+        )
+
+    if status.dirty:
+        if policy.dirty_policy == "autostash":
+            return PlannedAction(
+                target,
+                "autostash_then_sync",
+                "working tree is dirty and policy allows preservation",
+                status,
+                policy,
+            )
+        return PlannedAction(
+            target,
+            "block_dirty",
+            "working tree is dirty; stop by default",
+            status,
+            policy,
+        )
+
+    if not status.upstream:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            "repo has no upstream tracking branch",
+            status,
+            policy,
+        )
+
+    if status.behind == 0 and status.ahead == 0:
+        return PlannedAction(
+            target,
+            "no_change",
+            "repo is already aligned with upstream",
+            status,
+            policy,
+        )
+
+    if status.behind > 0 and status.ahead == 0:
+        if policy.sync_mode == "ff-only":
+            return PlannedAction(
+                target,
+                "fast_forward",
+                f"repo is behind upstream by {status.behind} commit(s) and can fast-forward",
+                status,
+                policy,
+            )
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"repo is behind upstream by {status.behind} commit(s), but policy requires explicit sync",
+            status,
+            policy,
+        )
+
+    if status.behind > 0 and status.ahead > 0:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"repo diverged from upstream (ahead {status.ahead}, behind {status.behind})",
+            status,
+            policy,
+        )
+
+    if status.ahead > 0:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"repo has {status.ahead} local commit(s) ahead of upstream",
+            status,
+            policy,
+        )
+
+    return PlannedAction(target, "manual_sync", "unclassified repo state", status, policy)
+
+
+def render_table(actions: list[PlannedAction]) -> str:
+    lines = [
+        "gr2 repo-maintenance prototype",
+        "SCOPE\tTARGET\tREPO\tACTION\tBRANCH\tUPSTREAM\tSTATE\tREASON",
+    ]
+    for item in actions:
+        state_bits = []
+        if item.status.dirty:
+            state_bits.append("dirty")
+        if item.status.ahead:
+            state_bits.append(f"ahead={item.status.ahead}")
+        if item.status.behind:
+            state_bits.append(f"behind={item.status.behind}")
+        if item.status.detached:
+            state_bits.append("detached")
+        if not state_bits:
+            state_bits.append("clean")
+
+        lines.append(
+            "\t".join(
+                [
+                    item.target.scope,
+                    item.target.target_name,
+                    item.target.repo_name,
+                    item.action,
+                    item.status.branch or "-",
+                    item.status.upstream or "-",
+                    ",".join(state_bits),
+                    item.reason,
+                ]
+            )
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    args = parse_args()
+    workspace_root = args.workspace_root.resolve()
+    spec_path = (args.spec or workspace_root / ".grip" / "workspace_spec.toml").resolve()
+    spec = read_workspace_spec(spec_path)
+    policy_doc = read_policy(args.policy)
+
+    actions = []
+    for target in derive_targets(workspace_root, spec):
+        status = inspect_repo(target.path)
+        policy = policy_for(target, policy_doc)
+        actions.append(classify(target, status, policy))
+
+    if args.json:
+        print(json.dumps([item.as_dict() for item in actions], indent=2))
+    else:
+        print(render_table(actions))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/prototypes/repo_transport_probe.py b/gr2/prototypes/repo_transport_probe.py
new file mode 100644
index 00000000..b7cceade
--- /dev/null
+++ b/gr2/prototypes/repo_transport_probe.py
@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Probe whether repo remotes are reachable/authenticated before gr2 apply.
+
+This is a UX prototype, not a full transport manager. Its job is to answer:
+
+- will this remote likely clone successfully from this environment?
+- if not, is the problem transport reachability or authentication?
+- what should the user try next?
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+
+SSH_TIMEOUT_SECONDS = 5
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Probe repo transport/auth readiness")
+    parser.add_argument("workspace_spec", type=Path, help="path to workspace_spec.toml")
+    parser.add_argument("--json", action="store_true", help="emit structured JSON")
+    return parser.parse_args()
+
+
+def detect_transport(url: str) -> str:
+    if url.startswith("git@") or url.startswith("ssh://"):
+        return "ssh"
+    if url.startswith("https://") or url.startswith("http://"):
+        return "https"
+    return "unknown"
+
+
+def classify_failure(stderr: str, transport: str) -> tuple[str, str]:
+    text = stderr.lower()
+    if "operation timed out" in text or "connection timed out" in text:
+        return ("transport-unreachable", f"{transport} transport timed out")
+    if "connection refused" in text:
+        return ("transport-unreachable", f"{transport} transport refused connection")
+    if "permission denied (publickey)" in text:
+        return ("auth-failed", "ssh key was rejected")
+    if "could not read username" in text or "authentication failed" in text:
+        return ("auth-failed", "https authentication is missing or invalid")
+    if "repository not found" in text:
+        return ("repo-not-found", "repository not found or not visible to current auth")
+    if "could not resolve host" in text:
+        return ("dns-failed", "host could not be resolved")
+    return ("probe-failed", stderr.strip().splitlines()[-1] if stderr.strip() else "unknown error")
+
+
+def recommendation(status: str, transport: str) -> str:
+    if status == "ok":
+        return "selected transport looks usable"
+    if status == "transport-unreachable" and transport == "ssh":
+        return "try HTTPS or fix SSH network reachability"
+    if status == "transport-unreachable":
+        return "check network access or remote availability"
+    if status == "auth-failed" and transport == "ssh":
+        return "load the correct SSH key or switch to HTTPS"
+    if status == "auth-failed":
+        return "configure GitHub HTTPS auth or switch to SSH"
+    if status == "repo-not-found":
+        return "verify repo visibility and credentials"
+    if status == "dns-failed":
+        return "fix host resolution before retrying"
+    return "inspect stderr and retry with an explicit transport"
+
+
+def probe_url(url: str) -> tuple[str, str]:
+    transport = detect_transport(url)
+    env = None
+    if transport == "ssh":
+        env = {
+            **dict(os.environ),
+            "GIT_SSH_COMMAND": (
+                f"ssh -o BatchMode=yes -o ConnectTimeout={SSH_TIMEOUT_SECONDS} "
+                "-o StrictHostKeyChecking=accept-new"
+            ),
+        }
+
+    result = subprocess.run(
+        ["git", "ls-remote", "--symref", url, "HEAD"],
+        text=True,
+        capture_output=True,
+        env=env,
+    )
+    if result.returncode == 0:
+        head_ref = ""
+        for line in result.stdout.splitlines():
+            match = re.match(r"ref: refs/heads/(.+)\s+HEAD", line)
+            if match:
+                head_ref = match.group(1)
+                break
+        return ("ok", head_ref or "HEAD reachable")
+    status, detail = classify_failure(result.stderr, transport)
+    return (status, detail)
+
+
+def load_spec(path: Path) -> list[dict[str, str]]:
+    with path.open("rb") as fh:
+        doc = tomllib.load(fh)
+    return list(doc.get("repos", []))
+
+
+def main() -> int:
+    args = parse_args()
+    repos = load_spec(args.workspace_spec)
+    rows: list[dict[str, str]] = []
+    exit_code = 0
+    for repo in repos:
+        url = repo["url"]
+        transport = detect_transport(url)
+        status, detail = probe_url(url)
+        if status != "ok":
+            exit_code = 1
+        rows.append(
+            {
+                "repo": repo["name"],
+                "url": url,
+                "transport": transport,
+                "status": status,
+                "detail": detail,
+                "recommendation": recommendation(status, transport),
+            }
+        )
+
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        print("REPO\tTRANSPORT\tSTATUS\tDETAIL\tNEXT")
+        for row in rows:
+            print(
+                f'{row["repo"]}\t{row["transport"]}\t{row["status"]}\t'
+                f'{row["detail"]}\t{row["recommendation"]}'
+            )
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/src/args.rs b/gr2/src/args.rs
new file mode 100644
index 00000000..71fa860f
--- /dev/null
+++ b/gr2/src/args.rs
@@ -0,0 +1,263 @@
+use clap::{Parser, Subcommand};
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "gr2",
+    about = "Clean-break gitgrip CLI for clone-backed team workspaces",
+    long_about = "gr2 is the clean-break gitgrip CLI for the new team-workspace, cache, and checkout model.",
+    version,
+    arg_required_else_help = true
+)]
+pub struct Cli {
+    /// Enable verbose logging
+    #[arg(short, long)]
+    pub verbose: bool,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand, Debug)]
+pub enum Commands {
+    /// Initialize a new team workspace root
+    Init {
+        /// Path to create the workspace in
+        path: String,
+
+        /// Optional logical workspace name
+        #[arg(long)]
+        name: Option<String>,
+    },
+
+    /// Verify the gr2 bootstrap binary is wired correctly
+    Doctor,
+
+    /// Team workspace operations
+    Team {
+        #[command(subcommand)]
+        command: TeamCommands,
+    },
+
+    /// Repo registry operations
+    Repo {
+        #[command(subcommand)]
+        command: RepoCommands,
+    },
+
+    /// Unit registry operations
+    Unit {
+        #[command(subcommand)]
+        command: UnitCommands,
+    },
+
+    /// Lane metadata operations
+    Lane {
+        #[command(subcommand)]
+        command: LaneCommands,
+    },
+
+    /// Lane-aware execution planning and commands
+    Exec {
+        #[command(subcommand)]
+        command: ExecCommands,
+    },
+
+    /// Declarative workspace spec operations
+    Spec {
+        #[command(subcommand)]
+        command: SpecCommands,
+    },
+
+    /// Diff the workspace spec into an execution plan
+    Plan {
+        /// Pre-approve plans with more than 3 operations
+        #[arg(long)]
+        yes: bool,
+    },
+
+    /// Apply the current execution plan to the workspace
+    Apply {
+        /// Pre-approve plans with more than 3 operations
+        #[arg(long)]
+        yes: bool,
+
+        /// Automatically stash and restore uncommitted changes in dirty repos
+        #[arg(long)]
+        autostash: bool,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum TeamCommands {
+    /// Register an agent workspace under agents/
+    Add {
+        /// Agent workspace name
+        name: String,
+    },
+
+    /// List registered agent workspaces
+    List,
+
+    /// Remove a registered agent workspace
+    Remove {
+        /// Agent workspace name
+        name: String,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum RepoCommands {
+    /// Register a repo in the team workspace
+    Add {
+        /// Logical repo name
+        name: String,
+
+        /// Canonical remote URL
+        url: String,
+    },
+
+    /// List registered repos
+    List,
+
+    /// Inspect repo-maintenance state across shared repos and unit repos
+    Status {
+        /// Only show repo state for a specific unit
+        #[arg(long)]
+        unit: Option<String>,
+
+        /// Only show a specific repo name
+        #[arg(long)]
+        repo: Option<String>,
+    },
+
+    /// Remove a registered repo
+    Remove {
+        /// Logical repo name
+        name: String,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum UnitCommands {
+    /// Register a local unit in the workspace materialization model
+    Add {
+        /// Unit name
+        name: String,
+    },
+
+    /// List registered units
+    List,
+
+    /// Remove a registered unit
+    Remove {
+        /// Unit name
+        name: String,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum LaneCommands {
+    /// Create a lane record and scaffold its workspace directories
+    Create {
+        /// Lane name
+        name: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+
+        /// Lane type
+        #[arg(long = "type", default_value = "feature")]
+        lane_type: String,
+
+        /// Repo membership for the lane (defaults to unit repos from workspace spec)
+        #[arg(long = "repo")]
+        repos: Vec<String>,
+
+        /// Branch intent entries in repo=branch form
+        #[arg(long = "branch")]
+        branches: Vec<String>,
+
+        /// Extra shared context roots relative to workspace root
+        #[arg(long = "shared-context")]
+        shared_context: Vec<String>,
+
+        /// Extra private context roots relative to workspace root
+        #[arg(long = "private-context")]
+        private_context: Vec<String>,
+
+        /// Default execution command for the lane (repeatable)
+        #[arg(long = "exec")]
+        exec: Vec<String>,
+
+        /// PR associations in repo:number form
+        #[arg(long = "pr")]
+        prs: Vec<String>,
+
+        /// Creation source label
+        #[arg(long)]
+        source: Option<String>,
+
+        /// Allow execution fan-out across repos by default
+        #[arg(long)]
+        parallel: bool,
+
+        /// Do not fail fast when running multi-repo commands
+        #[arg(long)]
+        no_fail_fast: bool,
+    },
+
+    /// List persisted lanes
+    List {
+        /// Filter to one owner unit
+        #[arg(long = "owner-unit")]
+        owner_unit: Option<String>,
+    },
+
+    /// Print one lane record
+    Show {
+        /// Lane name
+        name: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+    },
+
+    /// Remove one lane record and its scaffolded directories
+    Remove {
+        /// Lane name
+        name: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum ExecCommands {
+    /// Show the execution plan surface for one lane
+    Status {
+        /// Lane name
+        #[arg(long = "lane")]
+        lane: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+
+        /// Filter to one or more repos inside the lane
+        #[arg(long = "repo")]
+        repos: Vec<String>,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum SpecCommands {
+    /// Print the current workspace spec
+    Show,
+
+    /// Validate the current workspace spec against the filesystem
+    Validate,
+}
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
new file mode 100644
index 00000000..b91dd2b5
--- /dev/null
+++ b/gr2/src/dispatch.rs
@@ -0,0 +1,603 @@
+use anyhow::{Context, Result};
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::PathBuf;
+
+use crate::args::{
+    Commands, ExecCommands, LaneCommands, RepoCommands, SpecCommands, TeamCommands, UnitCommands,
+};
+use crate::exec::{ExecStatusFilter, ExecStatusReport};
+use crate::lane::{
+    create_lane, list_lanes, remove_lane, render_lane_table, show_lane, validate_lane_name,
+    LaneCreateRequest, LanePrAssociation, LaneType,
+};
+use crate::plan::ExecutionPlan;
+use crate::repo_status::{RepoStatusFilter, RepoStatusReport};
+use crate::spec::{read_workspace_spec, workspace_spec_path, write_workspace_spec, WorkspaceSpec};
+
+pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
+    match command {
+        Commands::Init { path, name } => {
+            let workspace_root = PathBuf::from(path);
+            let workspace_name = name.unwrap_or_else(|| {
+                workspace_root
+                    .file_name()
+                    .map(|name| name.to_string_lossy().into_owned())
+                    .unwrap_or_else(|| "workspace".to_string())
+            });
+
+            if workspace_root.exists() {
+                anyhow::bail!(
+                    "workspace path already exists: {}",
+                    workspace_root.display()
+                );
+            }
+
+            fs::create_dir_all(workspace_root.join(".grip"))?;
+            fs::create_dir_all(workspace_root.join("config"))?;
+            fs::create_dir_all(workspace_root.join("agents"))?;
+            fs::create_dir_all(workspace_root.join("repos"))?;
+
+            let workspace_toml = format!(
+                "version = 2\nname = \"{}\"\nlayout = \"team-workspace\"\n",
+                workspace_name
+            );
+            fs::write(workspace_root.join(".grip/workspace.toml"), workspace_toml)?;
+
+            println!(
+                "Initialized gr2 team workspace '{}' at {}",
+                workspace_name,
+                workspace_root.display()
+            );
+            Ok(())
+        }
+        Commands::Doctor => {
+            if verbose {
+                println!("gr2 bootstrap OK (verbose)");
+            } else {
+                println!("gr2 bootstrap OK");
+            }
+            Ok(())
+        }
+        Commands::Team { command } => match command {
+            TeamCommands::Add { name } => {
+                let workspace_root = require_workspace_root()?;
+
+                let agent_root = workspace_root.join("agents").join(&name);
+                if agent_root.exists() {
+                    anyhow::bail!("agent '{}' already exists", name);
+                }
+
+                fs::create_dir_all(&agent_root)?;
+                fs::write(
+                    agent_root.join("agent.toml"),
+                    format!("name = \"{}\"\nkind = \"agent-workspace\"\n", name),
+                )?;
+
+                println!("Added gr2 agent workspace '{}'", name);
+                Ok(())
+            }
+            TeamCommands::List => {
+                let workspace_root = require_workspace_root()?;
+                let agents_root = workspace_root.join("agents");
+
+                let mut names = Vec::new();
+                for entry in fs::read_dir(&agents_root)? {
+                    let entry = entry?;
+                    if entry.file_type()?.is_dir() && entry.path().join("agent.toml").exists() {
+                        names.push(entry.file_name().to_string_lossy().into_owned());
+                    }
+                }
+
+                names.sort();
+
+                if names.is_empty() {
+                    println!("No gr2 agent workspaces registered.");
+                } else {
+                    println!("Agent workspaces");
+                    for name in names {
+                        println!("- {}", name);
+                    }
+                }
+
+                Ok(())
+            }
+            TeamCommands::Remove { name } => {
+                let workspace_root = require_workspace_root()?;
+                let agent_root = workspace_root.join("agents").join(&name);
+
+                if !agent_root.join("agent.toml").exists() {
+                    anyhow::bail!("agent '{}' not found", name);
+                }
+
+                fs::remove_dir_all(&agent_root)?;
+                println!("Removed gr2 agent workspace '{}'", name);
+                Ok(())
+            }
+        },
+        Commands::Repo { command } => match command {
+            RepoCommands::Add { name, url } => {
+                let workspace_root = require_workspace_root()?;
+                let repos_root = workspace_root.join("repos");
+                let registry_path = workspace_root.join(".grip/repos.toml");
+                let repo_dir = repos_root.join(&name);
+
+                if repo_dir.exists() {
+                    anyhow::bail!("repo '{}' already exists", name);
+                }
+
+                fs::create_dir_all(&repo_dir)?;
+                fs::write(
+                    repo_dir.join("repo.toml"),
+                    format!("name = \"{}\"\nurl = \"{}\"\n", name, url),
+                )?;
+
+                let mut entries = Vec::new();
+                if registry_path.exists() {
+                    entries.push(fs::read_to_string(&registry_path)?);
+                }
+                entries.push(format!(
+                    "[[repo]]\nname = \"{}\"\nurl = \"{}\"\n",
+                    name, url
+                ));
+                fs::write(&registry_path, entries.join("\n"))?;
+
+                println!("Added gr2 repo '{}' -> {}", name, url);
+                Ok(())
+            }
+            RepoCommands::List => {
+                let workspace_root = require_workspace_root()?;
+                let repos_root = workspace_root.join("repos");
+
+                let mut repos = Vec::new();
+                for entry in fs::read_dir(&repos_root)? {
+                    let entry = entry?;
+                    let repo_toml = entry.path().join("repo.toml");
+                    if entry.file_type()?.is_dir() && repo_toml.exists() {
+                        let content = fs::read_to_string(repo_toml)?;
+                        let fallback_name = entry.file_name().to_string_lossy().into_owned();
+                        let name = content
+                            .lines()
+                            .find_map(|line| line.strip_prefix("name = \""))
+                            .and_then(|line| line.strip_suffix('"'))
+                            .map(str::to_owned)
+                            .unwrap_or(fallback_name);
+                        let url = content
+                            .lines()
+                            .find_map(|line| line.strip_prefix("url = \""))
+                            .and_then(|line| line.strip_suffix('"'))
+                            .unwrap_or("")
+                            .to_string();
+                        repos.push((name, url));
+                    }
+                }
+
+                repos.sort_by(|a, b| a.0.cmp(&b.0));
+
+                if repos.is_empty() {
+                    println!("No gr2 repos registered.");
+                } else {
+                    println!("Repos");
+                    for (name, url) in repos {
+                        println!("- {} -> {}", name, url);
+                    }
+                }
+
+                Ok(())
+            }
+            RepoCommands::Status { unit, repo } => {
+                let workspace_root = require_workspace_root()?;
+                let report =
+                    RepoStatusReport::load(&workspace_root, &RepoStatusFilter { unit, repo })?;
+                println!("{}", report.render_table());
+                Ok(())
+            }
+            RepoCommands::Remove { name } => {
+                let workspace_root = require_workspace_root()?;
+                let repos_root = workspace_root.join("repos");
+                let repo_root = repos_root.join(&name);
+                let repo_toml = repo_root.join("repo.toml");
+
+                if !repo_toml.exists() {
+                    anyhow::bail!("repo '{}' not found", name);
+                }
+
+                fs::remove_dir_all(&repo_root)?;
+
+                let registry_path = workspace_root.join(".grip/repos.toml");
+                if registry_path.exists() {
+                    let registry = fs::read_to_string(&registry_path)?;
+                    let kept_entries = registry
+                        .split("\n[[repo]]\n")
+                        .filter_map(|chunk| {
+                            let chunk = chunk.trim();
+                            if chunk.is_empty() {
+                                return None;
+                            }
+                            let normalized = if chunk.starts_with("[[repo]]") {
+                                chunk.to_string()
+                            } else {
+                                format!("[[repo]]\n{}", chunk)
+                            };
+                            let matches_name = normalized
+                                .lines()
+                                .find_map(|line| line.strip_prefix("name = \""))
+                                .and_then(|line| line.strip_suffix('"'))
+                                .map(|entry_name| entry_name == name)
+                                .unwrap_or(false);
+                            if matches_name {
+                                None
+                            } else {
+                                Some(normalized)
+                            }
+                        })
+                        .collect::<Vec<_>>();
+
+                    if kept_entries.is_empty() {
+                        fs::remove_file(&registry_path)?;
+                    } else {
+                        fs::write(&registry_path, kept_entries.join("\n\n"))?;
+                    }
+                }
+
+                println!("Removed gr2 repo '{}'", name);
+                Ok(())
+            }
+        },
+        Commands::Unit { command } => match command {
+            UnitCommands::Add { name } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&name)?;
+                let units_root = workspace_root.join("agents");
+                let registry_path = workspace_root.join(".grip/units.toml");
+                let unit_root = units_root.join(&name);
+
+                if unit_root.exists() {
+                    anyhow::bail!("unit '{}' already exists", name);
+                }
+
+                fs::create_dir_all(&unit_root)?;
+                fs::write(
+                    unit_root.join("unit.toml"),
+                    format!("name = \"{}\"\nkind = \"unit\"\n", name),
+                )?;
+
+                let mut entries = Vec::new();
+                if registry_path.exists() {
+                    entries.push(fs::read_to_string(&registry_path)?);
+                }
+                entries.push(format!("[[unit]]\nname = \"{}\"\nkind = \"unit\"\n", name));
+                fs::write(&registry_path, entries.join("\n"))?;
+
+                println!("Added gr2 unit '{}'", name);
+                Ok(())
+            }
+            UnitCommands::List => {
+                let workspace_root = require_workspace_root()?;
+                let units_root = workspace_root.join("agents");
+
+                let mut names = Vec::new();
+                for entry in fs::read_dir(&units_root)? {
+                    let entry = entry?;
+                    if entry.file_type()?.is_dir() && entry.path().join("unit.toml").exists() {
+                        names.push(entry.file_name().to_string_lossy().into_owned());
+                    }
+                }
+
+                names.sort();
+
+                if names.is_empty() {
+                    println!("No gr2 units registered.");
+                } else {
+                    println!("Units");
+                    for name in names {
+                        println!("- {}", name);
+                    }
+                }
+
+                Ok(())
+            }
+            UnitCommands::Remove { name } => {
+                let workspace_root = require_workspace_root()?;
+                let units_root = workspace_root.join("agents");
+                let unit_root = units_root.join(&name);
+                let unit_toml = unit_root.join("unit.toml");
+
+                if !unit_toml.exists() {
+                    anyhow::bail!("unit '{}' not found", name);
+                }
+
+                fs::remove_dir_all(&unit_root)?;
+
+                let registry_path = workspace_root.join(".grip/units.toml");
+                if registry_path.exists() {
+                    let registry = fs::read_to_string(&registry_path)?;
+                    let kept_entries = registry
+                        .split("\n[[unit]]\n")
+                        .filter_map(|chunk| {
+                            let chunk = chunk.trim();
+                            if chunk.is_empty() {
+                                return None;
+                            }
+                            let normalized = if chunk.starts_with("[[unit]]") {
+                                chunk.to_string()
+                            } else {
+                                format!("[[unit]]\n{}", chunk)
+                            };
+                            let matches_name = normalized
+                                .lines()
+                                .find_map(|line| line.strip_prefix("name = \""))
+                                .and_then(|line| line.strip_suffix('"'))
+                                .map(|entry_name| entry_name == name)
+                                .unwrap_or(false);
+                            if matches_name {
+                                None
+                            } else {
+                                Some(normalized)
+                            }
+                        })
+                        .collect::<Vec<_>>();
+
+                    if kept_entries.is_empty() {
+                        fs::remove_file(&registry_path)?;
+                    } else {
+                        fs::write(&registry_path, kept_entries.join("\n\n"))?;
+                    }
+                }
+
+                println!("Removed gr2 unit '{}'", name);
+                Ok(())
+            }
+        },
+        Commands::Lane { command } => match command {
+            LaneCommands::Create {
+                name,
+                owner_unit,
+                lane_type,
+                repos,
+                branches,
+                shared_context,
+                private_context,
+                exec,
+                prs,
+                source,
+                parallel,
+                no_fail_fast,
+            } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&name)?;
+
+                let branch_map = parse_branch_map(branches)?;
+                let pr_associations = parse_pr_associations(prs)?;
+                let request = LaneCreateRequest {
+                    name: name.clone(),
+                    owner_unit: owner_unit.clone(),
+                    lane_type: lane_type.parse::<LaneType>()?,
+                    repos,
+                    branch_map,
+                    shared_context,
+                    private_context,
+                    exec_commands: exec,
+                    creation_source: source.unwrap_or_else(|| "manual".to_string()),
+                    pr_associations,
+                    parallel,
+                    fail_fast: !no_fail_fast,
+                };
+
+                let record = create_lane(&workspace_root, request)?;
+                println!(
+                    "Created lane '{}'\n- owner: {}\n- type: {}\n- repos: {}",
+                    record.lane_name,
+                    record.owner_unit,
+                    record.lane_type.as_str(),
+                    record.repos.join(", ")
+                );
+                Ok(())
+            }
+            LaneCommands::List { owner_unit } => {
+                let workspace_root = require_workspace_root()?;
+                if let Some(owner_unit) = &owner_unit {
+                    validate_unit_name(owner_unit)?;
+                }
+                let lanes = list_lanes(&workspace_root, owner_unit.as_deref())?;
+                println!("{}", render_lane_table(&lanes));
+                Ok(())
+            }
+            LaneCommands::Show { name, owner_unit } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&name)?;
+                println!("{}", show_lane(&workspace_root, &owner_unit, &name)?);
+                Ok(())
+            }
+            LaneCommands::Remove { name, owner_unit } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&name)?;
+                remove_lane(&workspace_root, &owner_unit, &name)?;
+                println!("Removed lane '{}' for unit '{}'", name, owner_unit);
+                Ok(())
+            }
+        },
+        Commands::Exec { command } => match command {
+            ExecCommands::Status {
+                lane,
+                owner_unit,
+                repos,
+            } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&lane)?;
+                let report = ExecStatusReport::load(
+                    &workspace_root,
+                    &ExecStatusFilter {
+                        owner_unit,
+                        lane_name: lane,
+                        repos,
+                    },
+                )?;
+                println!("{}", report.render_table());
+                Ok(())
+            }
+        },
+        Commands::Spec { command } => match command {
+            SpecCommands::Show => {
+                let workspace_root = require_workspace_root()?;
+                let spec_path = workspace_spec_path(&workspace_root);
+                let spec = if spec_path.exists() {
+                    read_workspace_spec(&workspace_root)?
+                } else {
+                    let spec = WorkspaceSpec::from_workspace(&workspace_root)?;
+                    write_workspace_spec(&workspace_root, &spec)?;
+                    spec
+                };
+
+                println!("{}", toml::to_string_pretty(&spec)?);
+                Ok(())
+            }
+            SpecCommands::Validate => {
+                let workspace_root = require_workspace_root()?;
+                let spec = read_workspace_spec(&workspace_root)?;
+                spec.validate(&workspace_root)?;
+                println!(
+                    "Workspace spec is valid: {}",
+                    workspace_spec_path(&workspace_root).display()
+                );
+                Ok(())
+            }
+        },
+        Commands::Plan { yes } => {
+            let workspace_root = require_workspace_root()?;
+            let build = ExecutionPlan::from_workspace_spec(&workspace_root)?;
+            let guard_report =
+                build
+                    .plan
+                    .guard_for_apply(&workspace_root, &build.spec, yes, false)?;
+
+            if build.generated_spec {
+                println!(
+                    "Generated workspace spec at {} from current workspace state.",
+                    workspace_spec_path(&workspace_root).display()
+                );
+            }
+            println!("{}", build.plan.render_table());
+            for warning in guard_report.warnings {
+                println!("warning: {}", warning);
+            }
+            if guard_report.requires_confirmation {
+                println!("warning: plan contains more than 3 operations; apply will require --yes");
+            }
+            Ok(())
+        }
+        Commands::Apply { yes, autostash } => {
+            let workspace_root = require_workspace_root()?;
+            let build = ExecutionPlan::from_workspace_spec(&workspace_root)?;
+            let guard_report =
+                build
+                    .plan
+                    .guard_for_apply(&workspace_root, &build.spec, yes, autostash)?;
+
+            if build.generated_spec {
+                println!(
+                    "Generated workspace spec at {} from current workspace state.",
+                    workspace_spec_path(&workspace_root).display()
+                );
+            }
+
+            if guard_report.requires_confirmation {
+                anyhow::bail!("plan contains more than 3 operations; rerun with --yes to apply it");
+            }
+
+            if guard_report.has_dirty_repos && !autostash {
+                anyhow::bail!(
+                    "refusing to apply: units have repos with uncommitted changes; \
+                     rerun with --autostash to stash and restore them automatically"
+                );
+            }
+
+            for warning in &guard_report.warnings {
+                println!("warning: {}", warning);
+            }
+
+            let applied =
+                build
+                    .plan
+                    .apply(&workspace_root, &build.spec, &guard_report.dirty_repos)?;
+            if applied.is_empty() {
+                println!("ExecutionPlan");
+                println!("- no changes required");
+            } else {
+                println!("Applied execution plan");
+                for line in applied {
+                    println!("- {}", line);
+                }
+            }
+            Ok(())
+        }
+    }
+}
+
+fn require_workspace_root() -> Result<PathBuf> {
+    let workspace_root = std::env::current_dir()?;
+    let workspace_toml = workspace_root.join(".grip/workspace.toml");
+    if !workspace_toml.exists() {
+        anyhow::bail!("not in a gr2 workspace: missing .grip/workspace.toml");
+    }
+    Ok(workspace_root)
+}
+
+fn validate_unit_name(name: &str) -> Result<()> {
+    if name.is_empty() {
+        anyhow::bail!("unit name must not be empty");
+    }
+
+    if !name
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-')
+    {
+        anyhow::bail!(
+            "invalid unit name '{}': use only ASCII letters, numbers, '_' or '-'",
+            name
+        );
+    }
+
+    Ok(())
+}
+
+fn parse_branch_map(entries: Vec<String>) -> Result<BTreeMap<String, String>> {
+    let mut branch_map = BTreeMap::new();
+    for entry in entries {
+        let (repo, branch) = entry
+            .split_once('=')
+            .with_context(|| format!("invalid branch mapping '{}': expected repo=branch", entry))?;
+        if repo.trim().is_empty() || branch.trim().is_empty() {
+            anyhow::bail!(
+                "invalid branch mapping '{}': repo and branch must both be non-empty",
+                entry
+            );
+        }
+        branch_map.insert(repo.trim().to_string(), branch.trim().to_string());
+    }
+    Ok(branch_map)
+}
+
+fn parse_pr_associations(entries: Vec<String>) -> Result<Vec<LanePrAssociation>> {
+    let mut prs = Vec::new();
+    for entry in entries {
+        let (repo, number) = entry
+            .split_once(':')
+            .with_context(|| format!("invalid PR association '{}': expected repo:number", entry))?;
+        if repo.trim().is_empty() {
+            anyhow::bail!("invalid PR association '{}': repo must not be empty", entry);
+        }
+        prs.push(LanePrAssociation {
+            repo: repo.trim().to_string(),
+            number: number
+                .trim()
+                .parse::<u64>()
+                .with_context(|| format!("invalid PR number in '{}'", entry))?,
+        });
+    }
+    Ok(prs)
+}
diff --git a/gr2/src/exec.rs b/gr2/src/exec.rs
new file mode 100644
index 00000000..2262c51a
--- /dev/null
+++ b/gr2/src/exec.rs
@@ -0,0 +1,166 @@
+use anyhow::{Context, Result};
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use crate::lane::{lane_root_path, load_lane, LaneRecord};
+use crate::spec::{read_workspace_spec, workspace_spec_path, WorkspaceSpec};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExecStatusFilter {
+    pub owner_unit: String,
+    pub lane_name: String,
+    pub repos: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExecStatusEntry {
+    pub repo: String,
+    pub exec_path: PathBuf,
+    pub path_kind: &'static str,
+    pub branch: Option<String>,
+    pub pr: Option<u64>,
+    pub command_count: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExecStatusReport {
+    pub lane: LaneRecord,
+    pub entries: Vec<ExecStatusEntry>,
+}
+
+impl ExecStatusReport {
+    pub fn load(workspace_root: &Path, filter: &ExecStatusFilter) -> Result<Self> {
+        let spec = load_workspace_spec_for_exec(workspace_root)?;
+        let lane = load_lane(workspace_root, &filter.owner_unit, &filter.lane_name)?;
+
+        let mut requested = filter.repos.clone();
+        requested.sort();
+        requested.dedup();
+
+        for repo in &requested {
+            if !lane.repos.iter().any(|member| member == repo) {
+                anyhow::bail!(
+                    "lane '{}' for unit '{}' does not include repo '{}'",
+                    lane.lane_name,
+                    lane.owner_unit,
+                    repo
+                );
+            }
+        }
+
+        let repo_names = if requested.is_empty() {
+            lane.repos.clone()
+        } else {
+            requested
+        };
+
+        let repo_specs = spec
+            .repos
+            .into_iter()
+            .map(|repo| (repo.name.clone(), repo))
+            .collect::<BTreeMap<_, _>>();
+
+        let lane_root = lane_root_path(workspace_root, &lane.owner_unit, &lane.lane_name);
+        let command_count = lane.exec_defaults.commands.len();
+
+        let mut entries = Vec::new();
+        for repo_name in repo_names {
+            repo_specs
+                .get(&repo_name)
+                .with_context(|| format!("lane references unknown repo '{}'", repo_name))?;
+
+            let lane_repo_path = lane_root.join("repos").join(&repo_name);
+            let (exec_path, path_kind) = if lane_repo_path.exists() {
+                (lane_repo_path, "lane")
+            } else {
+                (lane_repo_path, "missing")
+            };
+
+            let pr = lane
+                .pr_associations
+                .iter()
+                .find(|pr| pr.repo == repo_name)
+                .map(|pr| pr.number);
+
+            entries.push(ExecStatusEntry {
+                repo: repo_name.clone(),
+                exec_path,
+                path_kind,
+                branch: lane.branch_map.get(&repo_name).cloned(),
+                pr,
+                command_count,
+            });
+        }
+
+        Ok(Self { lane, entries })
+    }
+
+    pub fn render_table(&self) -> String {
+        let mut out = String::new();
+        out.push_str("gr2 exec status\n");
+        out.push_str(&format!(
+            "lane: {}/{}\n",
+            self.lane.owner_unit, self.lane.lane_name
+        ));
+        out.push_str(&format!("type: {}\n", self.lane.lane_type.as_str()));
+        out.push_str(&format!(
+            "parallel: {}\n",
+            if self.lane.exec_defaults.parallel {
+                "true"
+            } else {
+                "false"
+            }
+        ));
+        out.push_str(&format!(
+            "fail_fast: {}\n",
+            if self.lane.exec_defaults.fail_fast {
+                "true"
+            } else {
+                "false"
+            }
+        ));
+
+        if self.lane.exec_defaults.commands.is_empty() {
+            out.push_str("commands: none\n");
+        } else {
+            out.push_str("commands:\n");
+            for command in &self.lane.exec_defaults.commands {
+                out.push_str(&format!("- {}\n", command));
+            }
+        }
+
+        if self.entries.is_empty() {
+            out.push_str("repos: none");
+            return out;
+        }
+
+        out.push_str("repos:\n");
+        out.push_str("REPO PATH_KIND EXEC_PATH BRANCH PR COMMANDS\n");
+        for entry in &self.entries {
+            out.push_str(&format!(
+                "{} {} {} {} {} {}\n",
+                entry.repo,
+                entry.path_kind,
+                entry.exec_path.display(),
+                entry.branch.as_deref().unwrap_or("-"),
+                entry
+                    .pr
+                    .map(|pr| pr.to_string())
+                    .unwrap_or_else(|| "-".to_string()),
+                entry.command_count
+            ));
+        }
+        out.trim_end().to_string()
+    }
+}
+
+fn load_workspace_spec_for_exec(workspace_root: &Path) -> Result<WorkspaceSpec> {
+    let spec_path = workspace_spec_path(workspace_root);
+    if !spec_path.exists() {
+        anyhow::bail!(
+            "workspace spec missing at {}; run 'gr2 spec show' or write .grip/workspace_spec.toml first",
+            spec_path.display()
+        );
+    }
+    read_workspace_spec(workspace_root)
+}
diff --git a/gr2/src/lane.rs b/gr2/src/lane.rs
new file mode 100644
index 00000000..18b78c10
--- /dev/null
+++ b/gr2/src/lane.rs
@@ -0,0 +1,408 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, BTreeSet};
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use crate::spec::{read_workspace_spec, workspace_spec_path, WorkspaceSpec};
+
+pub const LANE_SCHEMA_VERSION: u32 = 1;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LaneRecord {
+    pub schema_version: u32,
+    pub lane_id: String,
+    pub lane_name: String,
+    pub owner_unit: String,
+    pub lane_type: LaneType,
+    pub repos: Vec<String>,
+    #[serde(default)]
+    pub branch_map: BTreeMap<String, String>,
+    pub creation_source: String,
+    pub context: LaneContextRoots,
+    pub exec_defaults: LaneExecDefaults,
+    #[serde(default)]
+    pub pr_associations: Vec<LanePrAssociation>,
+    pub recovery: LaneRecoveryState,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum LaneType {
+    Home,
+    Feature,
+    Review,
+    Scratch,
+}
+
+impl LaneType {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Home => "home",
+            Self::Feature => "feature",
+            Self::Review => "review",
+            Self::Scratch => "scratch",
+        }
+    }
+}
+
+impl std::str::FromStr for LaneType {
+    type Err = anyhow::Error;
+
+    fn from_str(value: &str) -> Result<Self> {
+        match value {
+            "home" => Ok(Self::Home),
+            "feature" => Ok(Self::Feature),
+            "review" => Ok(Self::Review),
+            "scratch" => Ok(Self::Scratch),
+            other => anyhow::bail!(
+                "unknown lane type '{}': expected home, feature, review, or scratch",
+                other
+            ),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LaneContextRoots {
+    #[serde(default)]
+    pub shared_roots: Vec<String>,
+    #[serde(default)]
+    pub private_roots: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LaneExecDefaults {
+    #[serde(default)]
+    pub commands: Vec<String>,
+    pub fail_fast: bool,
+    pub parallel: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LanePrAssociation {
+    pub repo: String,
+    pub number: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct LaneRecoveryState {
+    #[serde(default)]
+    pub autostash_refs: BTreeMap<String, String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaneCreateRequest {
+    pub name: String,
+    pub owner_unit: String,
+    pub lane_type: LaneType,
+    pub repos: Vec<String>,
+    pub branch_map: BTreeMap<String, String>,
+    pub shared_context: Vec<String>,
+    pub private_context: Vec<String>,
+    pub exec_commands: Vec<String>,
+    pub creation_source: String,
+    pub pr_associations: Vec<LanePrAssociation>,
+    pub parallel: bool,
+    pub fail_fast: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaneSummary {
+    pub owner_unit: String,
+    pub lane_name: String,
+    pub lane_type: LaneType,
+    pub repo_count: usize,
+}
+
+pub fn create_lane(workspace_root: &Path, request: LaneCreateRequest) -> Result<LaneRecord> {
+    validate_lane_name(&request.name)?;
+    validate_lane_name(&request.owner_unit)?;
+
+    let spec = load_workspace_spec_for_lanes(workspace_root)?;
+    let unit = spec
+        .units
+        .iter()
+        .find(|unit| unit.name == request.owner_unit)
+        .with_context(|| format!("unit '{}' not found in workspace spec", request.owner_unit))?;
+
+    let known_repos = spec
+        .repos
+        .iter()
+        .map(|repo| repo.name.clone())
+        .collect::<BTreeSet<_>>();
+
+    let mut repos = if request.repos.is_empty() {
+        unit.repos.clone()
+    } else {
+        request.repos.clone()
+    };
+    repos.sort();
+    repos.dedup();
+
+    if repos.is_empty() {
+        anyhow::bail!(
+            "lane '{}' has no repo membership; pass --repo or add repos to unit '{}' in workspace spec",
+            request.name,
+            request.owner_unit
+        );
+    }
+
+    for repo in &repos {
+        if !known_repos.contains(repo) {
+            anyhow::bail!("lane '{}' references unknown repo '{}'", request.name, repo);
+        }
+    }
+
+    for repo in request.branch_map.keys() {
+        if !repos.iter().any(|member| member == repo) {
+            anyhow::bail!(
+                "lane '{}' branch map references repo '{}' outside lane membership",
+                request.name,
+                repo
+            );
+        }
+    }
+
+    for pr in &request.pr_associations {
+        if !repos.iter().any(|repo| repo == &pr.repo) {
+            anyhow::bail!(
+                "lane '{}' PR association references repo '{}' outside lane membership",
+                request.name,
+                pr.repo
+            );
+        }
+    }
+
+    let metadata_path = lane_metadata_path(workspace_root, &request.owner_unit, &request.name);
+    if metadata_path.exists() {
+        anyhow::bail!(
+            "lane '{}' for unit '{}' already exists",
+            request.name,
+            request.owner_unit
+        );
+    }
+
+    let lane_root = lane_root_path(workspace_root, &request.owner_unit, &request.name);
+    fs::create_dir_all(lane_root.join("repos"))
+        .with_context(|| format!("create lane repos directory {}", lane_root.display()))?;
+    fs::create_dir_all(lane_root.join("context"))
+        .with_context(|| format!("create lane context directory {}", lane_root.display()))?;
+    fs::create_dir_all(
+        metadata_path
+            .parent()
+            .context("lane metadata parent missing")?,
+    )
+    .with_context(|| format!("create lane state directory {}", metadata_path.display()))?;
+
+    let shared_roots = merge_roots(
+        vec!["config".to_string(), ".grip/context/shared".to_string()],
+        request.shared_context,
+    );
+    let private_roots = merge_roots(
+        vec![
+            format!("agents/{}/home/context", request.owner_unit),
+            format!(
+                "agents/{}/lanes/{}/context",
+                request.owner_unit, request.name
+            ),
+        ],
+        request.private_context,
+    );
+
+    let record = LaneRecord {
+        schema_version: LANE_SCHEMA_VERSION,
+        lane_id: format!("{}:{}", request.owner_unit, request.name),
+        lane_name: request.name,
+        owner_unit: request.owner_unit,
+        lane_type: request.lane_type,
+        repos,
+        branch_map: request.branch_map,
+        creation_source: request.creation_source,
+        context: LaneContextRoots {
+            shared_roots,
+            private_roots,
+        },
+        exec_defaults: LaneExecDefaults {
+            commands: request.exec_commands,
+            fail_fast: request.fail_fast,
+            parallel: request.parallel,
+        },
+        pr_associations: request.pr_associations,
+        recovery: LaneRecoveryState::default(),
+    };
+
+    let content = toml::to_string_pretty(&record).context("serialize lane record")?;
+    fs::write(&metadata_path, content)
+        .with_context(|| format!("write lane metadata to {}", metadata_path.display()))?;
+
+    Ok(record)
+}
+
+pub fn list_lanes(workspace_root: &Path, owner_filter: Option<&str>) -> Result<Vec<LaneSummary>> {
+    let state_root = lane_state_root(workspace_root);
+    if !state_root.exists() {
+        return Ok(Vec::new());
+    }
+
+    let mut lanes = Vec::new();
+    for owner_entry in fs::read_dir(&state_root)? {
+        let owner_entry = owner_entry?;
+        if !owner_entry.file_type()?.is_dir() {
+            continue;
+        }
+
+        let owner_unit = owner_entry.file_name().to_string_lossy().into_owned();
+        if let Some(filter) = owner_filter {
+            if filter != owner_unit {
+                continue;
+            }
+        }
+
+        for lane_entry in fs::read_dir(owner_entry.path())? {
+            let lane_entry = lane_entry?;
+            if !lane_entry.file_type()?.is_file() {
+                continue;
+            }
+
+            if lane_entry.path().extension().and_then(|ext| ext.to_str()) != Some("toml") {
+                continue;
+            }
+
+            let record = load_lane_record_path(&lane_entry.path())?;
+            lanes.push(LaneSummary {
+                owner_unit: record.owner_unit,
+                lane_name: record.lane_name,
+                lane_type: record.lane_type,
+                repo_count: record.repos.len(),
+            });
+        }
+    }
+
+    lanes.sort_by(|left, right| {
+        left.owner_unit
+            .cmp(&right.owner_unit)
+            .then_with(|| left.lane_name.cmp(&right.lane_name))
+    });
+    Ok(lanes)
+}
+
+pub fn show_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<String> {
+    let path = lane_metadata_path(workspace_root, owner_unit, lane_name);
+    fs::read_to_string(&path).with_context(|| format!("read lane metadata from {}", path.display()))
+}
+
+pub fn load_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<LaneRecord> {
+    let path = lane_metadata_path(workspace_root, owner_unit, lane_name);
+    if !path.exists() {
+        anyhow::bail!("lane '{}' for unit '{}' not found", lane_name, owner_unit);
+    }
+    load_lane_record_path(&path)
+}
+
+pub fn remove_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<()> {
+    let metadata_path = lane_metadata_path(workspace_root, owner_unit, lane_name);
+    if !metadata_path.exists() {
+        anyhow::bail!("lane '{}' for unit '{}' not found", lane_name, owner_unit);
+    }
+
+    fs::remove_file(&metadata_path)
+        .with_context(|| format!("remove lane metadata {}", metadata_path.display()))?;
+
+    let owner_state_root = lane_state_root(workspace_root).join(owner_unit);
+    if owner_state_root.exists() && owner_state_root.read_dir()?.next().is_none() {
+        fs::remove_dir(&owner_state_root).with_context(|| {
+            format!(
+                "remove empty lane owner state {}",
+                owner_state_root.display()
+            )
+        })?;
+    }
+
+    let lane_root = lane_root_path(workspace_root, owner_unit, lane_name);
+    if lane_root.exists() {
+        fs::remove_dir_all(&lane_root)
+            .with_context(|| format!("remove lane root {}", lane_root.display()))?;
+    }
+
+    Ok(())
+}
+
+pub fn render_lane_table(lanes: &[LaneSummary]) -> String {
+    if lanes.is_empty() {
+        return "No gr2 lanes registered.".to_string();
+    }
+
+    let mut out = String::from("Lanes\nOWNER NAME TYPE REPOS\n");
+    for lane in lanes {
+        out.push_str(&format!(
+            "{} {} {} {}\n",
+            lane.owner_unit,
+            lane.lane_name,
+            lane.lane_type.as_str(),
+            lane.repo_count
+        ));
+    }
+    out.trim_end().to_string()
+}
+
+fn load_workspace_spec_for_lanes(workspace_root: &Path) -> Result<WorkspaceSpec> {
+    let spec_path = workspace_spec_path(workspace_root);
+    if spec_path.exists() {
+        read_workspace_spec(workspace_root)
+    } else {
+        WorkspaceSpec::from_workspace(workspace_root)
+    }
+}
+
+fn load_lane_record_path(path: &Path) -> Result<LaneRecord> {
+    let content = fs::read_to_string(path)
+        .with_context(|| format!("read lane metadata from {}", path.display()))?;
+    toml::from_str(&content).context("parse lane metadata")
+}
+
+fn merge_roots(defaults: Vec<String>, extras: Vec<String>) -> Vec<String> {
+    let mut merged = defaults;
+    for extra in extras {
+        if !merged.iter().any(|existing| existing == &extra) {
+            merged.push(extra);
+        }
+    }
+    merged
+}
+
+pub fn lane_state_root(workspace_root: &Path) -> PathBuf {
+    workspace_root.join(".grip/state/lanes")
+}
+
+pub fn lane_metadata_path(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> PathBuf {
+    lane_state_root(workspace_root)
+        .join(owner_unit)
+        .join(format!("{}.toml", lane_name))
+}
+
+pub fn lane_root_path(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> PathBuf {
+    workspace_root
+        .join("agents")
+        .join(owner_unit)
+        .join("lanes")
+        .join(lane_name)
+}
+
+pub fn validate_lane_name(name: &str) -> Result<()> {
+    if name.is_empty() {
+        anyhow::bail!("lane name must not be empty");
+    }
+
+    if !name
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-' || ch == '.')
+    {
+        anyhow::bail!(
+            "invalid lane name '{}': use only ASCII letters, numbers, '.', '_' or '-'",
+            name
+        );
+    }
+
+    Ok(())
+}
diff --git a/gr2/src/lib.rs b/gr2/src/lib.rs
new file mode 100644
index 00000000..bd63d9ac
--- /dev/null
+++ b/gr2/src/lib.rs
@@ -0,0 +1,11 @@
+//! gr2 CLI namespace
+//!
+//! This crate is the clean-break CLI surface for the new team-workspace model.
+
+pub mod args;
+pub mod dispatch;
+pub mod exec;
+pub mod lane;
+pub mod plan;
+pub mod repo_status;
+pub mod spec;
diff --git a/gr2/src/plan.rs b/gr2/src/plan.rs
new file mode 100644
index 00000000..bced6892
--- /dev/null
+++ b/gr2/src/plan.rs
@@ -0,0 +1,702 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use crate::spec::{
+    read_workspace_spec, workspace_spec_path, write_workspace_spec, LinkKind, LinkSpec, UnitSpec,
+    WorkspaceSpec,
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ExecutionPlan {
+    pub operations: Vec<PlanOperation>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PlanBuild {
+    pub spec: WorkspaceSpec,
+    pub plan: ExecutionPlan,
+    pub generated_spec: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PlanOperation {
+    pub unit_name: String,
+    pub operation: OperationType,
+    #[serde(default)]
+    pub parameters: BTreeMap<String, String>,
+    pub preview: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum OperationType {
+    Clone,
+    Configure,
+    Link,
+}
+
+/// A repo inside a unit that has uncommitted changes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DirtyRepo {
+    pub unit_name: String,
+    pub repo_name: String,
+    pub repo_path: PathBuf,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PlanGuardReport {
+    pub warnings: Vec<String>,
+    pub requires_confirmation: bool,
+    pub has_dirty_repos: bool,
+    pub dirty_repos: Vec<DirtyRepo>,
+}
+
+impl ExecutionPlan {
+    pub fn from_workspace_spec(workspace_root: &Path) -> Result<PlanBuild> {
+        let spec_path = workspace_spec_path(workspace_root);
+        let (spec, generated_spec) = if spec_path.exists() {
+            (read_workspace_spec(workspace_root)?, false)
+        } else {
+            let generated = WorkspaceSpec::from_workspace(workspace_root)?;
+            write_workspace_spec(workspace_root, &generated)?;
+            (generated, true)
+        };
+
+        spec.validate_for_plan()?;
+
+        let mut operations = Vec::new();
+
+        for unit in &spec.units {
+            let unit_root = workspace_root.join(&unit.path);
+            let unit_toml = unit_root.join("unit.toml");
+
+            if !unit_toml.exists() {
+                let mut parameters = BTreeMap::new();
+                parameters.insert("path".to_string(), unit.path.clone());
+                parameters.insert("repos".to_string(), unit.repos.join(","));
+                operations.push(PlanOperation {
+                    unit_name: unit.name.clone(),
+                    operation: OperationType::Clone,
+                    parameters,
+                    preview: format!("clone unit '{}' into {}", unit.name, unit.path),
+                });
+                // Fall through to check links (they'll all be missing since the unit
+                // doesn't exist yet, but they should be planned alongside the Clone)
+            } else {
+                let expected_path = format!("agents/{}", unit.name);
+                let path_mismatch = unit.path != expected_path;
+
+                // Check for missing repo checkouts inside the unit
+                let missing_repos: Vec<&str> = unit
+                    .repos
+                    .iter()
+                    .filter(|repo_name| !unit_root.join(repo_name).exists())
+                    .map(|s| s.as_str())
+                    .collect();
+
+                if path_mismatch || !missing_repos.is_empty() {
+                    let mut parameters = BTreeMap::new();
+                    parameters.insert("path".to_string(), unit.path.clone());
+                    parameters.insert("repos".to_string(), unit.repos.join(","));
+                    let preview = if !missing_repos.is_empty() {
+                        format!(
+                            "converge unit '{}': clone missing repos [{}]",
+                            unit.name,
+                            missing_repos.join(", ")
+                        )
+                    } else {
+                        format!("reconfigure unit '{}' to match {}", unit.name, unit.path)
+                    };
+                    operations.push(PlanOperation {
+                        unit_name: unit.name.clone(),
+                        operation: OperationType::Configure,
+                        parameters,
+                        preview,
+                    });
+                }
+            }
+
+            // Check declared links against filesystem
+            for link in &unit.links {
+                let dest_path = unit_root.join(&link.dest);
+                if !dest_path.exists() {
+                    let mut parameters = BTreeMap::new();
+                    parameters.insert("src".to_string(), link.src.clone());
+                    parameters.insert("dest".to_string(), link.dest.clone());
+                    parameters.insert("kind".to_string(), link.kind.as_str().to_string());
+                    operations.push(PlanOperation {
+                        unit_name: unit.name.clone(),
+                        operation: OperationType::Link,
+                        parameters,
+                        preview: format!(
+                            "{} {} -> {}/{}",
+                            link.kind.as_str(),
+                            link.src,
+                            unit.path,
+                            link.dest
+                        ),
+                    });
+                }
+            }
+        }
+
+        Ok(PlanBuild {
+            spec,
+            plan: Self { operations },
+            generated_spec,
+        })
+    }
+
+    pub fn apply(
+        &self,
+        workspace_root: &Path,
+        spec: &WorkspaceSpec,
+        dirty_repos: &[DirtyRepo],
+    ) -> Result<Vec<String>> {
+        let mut applied = Vec::new();
+
+        // Autostash: stash dirty repos before operations
+        let stashed = autostash_dirty_repos(dirty_repos)?;
+
+        let result = self.apply_operations(workspace_root, spec, &mut applied);
+
+        // Autostash: pop stashes regardless of operation success
+        let pop_errors = autostash_pop(&stashed);
+
+        // Record stash state if any stashes were created
+        if !stashed.is_empty() {
+            record_stash_state(workspace_root, &stashed, &pop_errors)?;
+        }
+
+        // Propagate operation errors after cleanup
+        result?;
+
+        if !applied.is_empty() {
+            record_apply_state(workspace_root, &applied)?;
+        }
+
+        // Report pop errors as warnings but don't fail
+        for err in &pop_errors {
+            applied.push(format!("warning: stash pop failed: {}", err));
+        }
+
+        Ok(applied)
+    }
+
+    fn apply_operations(
+        &self,
+        workspace_root: &Path,
+        spec: &WorkspaceSpec,
+        applied: &mut Vec<String>,
+    ) -> Result<()> {
+        for operation in &self.operations {
+            let unit_spec = spec
+                .units
+                .iter()
+                .find(|unit| unit.name == operation.unit_name)
+                .with_context(|| {
+                    format!(
+                        "execution plan references unknown unit '{}'",
+                        operation.unit_name
+                    )
+                })?;
+
+            match operation.operation {
+                OperationType::Clone => {
+                    materialize_unit(workspace_root, unit_spec, spec)?;
+                    applied.push(format!(
+                        "cloned unit '{}' into {}",
+                        unit_spec.name, unit_spec.path
+                    ));
+                }
+                OperationType::Configure => {
+                    materialize_unit(workspace_root, unit_spec, spec)?;
+                    applied.push(format!(
+                        "configured unit '{}' at {}",
+                        unit_spec.name, unit_spec.path
+                    ));
+                }
+                OperationType::Link => {
+                    let src = operation
+                        .parameters
+                        .get("src")
+                        .context("link operation missing 'src' parameter")?;
+                    let dest = operation
+                        .parameters
+                        .get("dest")
+                        .context("link operation missing 'dest' parameter")?;
+                    let kind_str = operation
+                        .parameters
+                        .get("kind")
+                        .map(|s| s.as_str())
+                        .unwrap_or("symlink");
+                    let kind = kind_str.parse::<LinkKind>()?;
+
+                    let link_spec = LinkSpec {
+                        src: src.clone(),
+                        dest: dest.clone(),
+                        kind,
+                    };
+                    apply_link(workspace_root, unit_spec, &link_spec)?;
+                    applied.push(format!(
+                        "{} {} -> {}/{}",
+                        kind_str, src, unit_spec.path, dest
+                    ));
+                }
+            }
+        }
+        Ok(())
+    }
+
+    pub fn guard_for_apply(
+        &self,
+        workspace_root: &Path,
+        spec: &WorkspaceSpec,
+        assume_yes: bool,
+        _autostash: bool,
+    ) -> Result<PlanGuardReport> {
+        let mut warnings = Vec::new();
+        let mut dirty_repos = Vec::new();
+
+        // Collect unit names that have planned operations
+        let mut units_with_ops: std::collections::HashSet<&str> = std::collections::HashSet::new();
+        for operation in &self.operations {
+            units_with_ops.insert(&operation.unit_name);
+        }
+
+        for operation in &self.operations {
+            // Resolve the unit's actual path from the spec, not from parameters
+            let unit_path = spec
+                .units
+                .iter()
+                .find(|u| u.name == operation.unit_name)
+                .map(|u| u.path.as_str())
+                .unwrap_or_else(|| {
+                    operation
+                        .parameters
+                        .get("path")
+                        .map(|s| s.as_str())
+                        .unwrap_or("")
+                });
+
+            match operation.operation {
+                OperationType::Link => {
+                    if let Some(dest) = operation.parameters.get("dest") {
+                        let dest_path = workspace_root.join(unit_path).join(dest);
+                        if dest_path.exists() {
+                            anyhow::bail!(
+                                "refusing to apply plan: link destination already exists for unit '{}': {}",
+                                operation.unit_name,
+                                dest_path.display()
+                            );
+                        }
+                    }
+                }
+                _ => {
+                    let path = workspace_root.join(unit_path);
+
+                    if path.join(".git").exists() {
+                        warnings.push(format!(
+                            "unit '{}' has a git checkout at {} with possible uncommitted changes; inspect before apply",
+                            operation.unit_name,
+                            path.display()
+                        ));
+                    }
+                }
+            }
+        }
+
+        // Check for dirty repos in units that have planned operations
+        for unit in &spec.units {
+            if !units_with_ops.contains(unit.name.as_str()) {
+                continue;
+            }
+
+            let unit_root = workspace_root.join(&unit.path);
+            for repo_name in &unit.repos {
+                let repo_checkout = unit_root.join(repo_name);
+                if !repo_checkout.join(".git").exists() {
+                    continue;
+                }
+
+                if is_repo_dirty(&repo_checkout)? {
+                    warnings.push(format!(
+                        "unit '{}' repo '{}' has uncommitted changes at {}",
+                        unit.name,
+                        repo_name,
+                        repo_checkout.display()
+                    ));
+                    dirty_repos.push(DirtyRepo {
+                        unit_name: unit.name.clone(),
+                        repo_name: repo_name.clone(),
+                        repo_path: repo_checkout,
+                    });
+                }
+            }
+        }
+
+        let has_dirty_repos = !dirty_repos.is_empty();
+
+        Ok(PlanGuardReport {
+            warnings,
+            requires_confirmation: self.operations.len() > 3 && !assume_yes,
+            has_dirty_repos,
+            dirty_repos,
+        })
+    }
+
+    pub fn render_table(&self) -> String {
+        if self.operations.is_empty() {
+            return "ExecutionPlan\n- no changes required\n".to_string();
+        }
+
+        let mut lines = vec![
+            "ExecutionPlan".to_string(),
+            "UNIT\tOPERATION\tPREVIEW".to_string(),
+        ];
+        for operation in &self.operations {
+            lines.push(format!(
+                "{}\t{}\t{}",
+                operation.unit_name,
+                operation.operation.as_str(),
+                operation.preview
+            ));
+        }
+        lines.join("\n")
+    }
+}
+
+impl OperationType {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Clone => "clone",
+            Self::Configure => "configure",
+            Self::Link => "link",
+        }
+    }
+}
+
+fn apply_link(workspace_root: &Path, unit: &UnitSpec, link: &LinkSpec) -> Result<()> {
+    let src_path = workspace_root.join(&link.src);
+    let unit_root = workspace_root.join(&unit.path);
+    let dest_path = unit_root.join(&link.dest);
+
+    if !src_path.exists() {
+        anyhow::bail!(
+            "link source does not exist: {} (for unit '{}')",
+            src_path.display(),
+            unit.name
+        );
+    }
+
+    if let Some(parent) = dest_path.parent() {
+        fs::create_dir_all(parent).with_context(|| {
+            format!(
+                "create parent directory for link destination {}",
+                dest_path.display()
+            )
+        })?;
+    }
+
+    match link.kind {
+        LinkKind::Symlink => {
+            let abs_src = fs::canonicalize(&src_path).with_context(|| {
+                format!(
+                    "resolve absolute path for link source {}",
+                    src_path.display()
+                )
+            })?;
+            #[cfg(unix)]
+            std::os::unix::fs::symlink(&abs_src, &dest_path).with_context(|| {
+                format!(
+                    "create symlink {} -> {}",
+                    dest_path.display(),
+                    abs_src.display()
+                )
+            })?;
+            #[cfg(windows)]
+            {
+                if abs_src.is_dir() {
+                    std::os::windows::fs::symlink_dir(&abs_src, &dest_path)
+                } else {
+                    std::os::windows::fs::symlink_file(&abs_src, &dest_path)
+                }
+                .with_context(|| {
+                    format!(
+                        "create symlink {} -> {}",
+                        dest_path.display(),
+                        abs_src.display()
+                    )
+                })?;
+            }
+        }
+        LinkKind::Copy => {
+            if src_path.is_dir() {
+                copy_dir_recursive(&src_path, &dest_path).with_context(|| {
+                    format!(
+                        "copy directory {} -> {}",
+                        src_path.display(),
+                        dest_path.display()
+                    )
+                })?;
+            } else {
+                fs::copy(&src_path, &dest_path).with_context(|| {
+                    format!(
+                        "copy file {} -> {}",
+                        src_path.display(),
+                        dest_path.display()
+                    )
+                })?;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<()> {
+    fs::create_dir_all(dest)?;
+    for entry in fs::read_dir(src)? {
+        let entry = entry?;
+        let entry_dest = dest.join(entry.file_name());
+        if entry.file_type()?.is_dir() {
+            copy_dir_recursive(&entry.path(), &entry_dest)?;
+        } else {
+            fs::copy(entry.path(), &entry_dest)?;
+        }
+    }
+    Ok(())
+}
+
+fn materialize_unit(workspace_root: &Path, unit: &UnitSpec, spec: &WorkspaceSpec) -> Result<()> {
+    let unit_root = workspace_root.join(&unit.path);
+    fs::create_dir_all(&unit_root)
+        .with_context(|| format!("create unit directory {}", unit_root.display()))?;
+    fs::write(unit_root.join("unit.toml"), render_unit_toml(unit))
+        .with_context(|| format!("write unit metadata for '{}'", unit.name))?;
+
+    // Clone repos declared in the unit's repos list
+    for repo_name in &unit.repos {
+        let repo_spec = spec
+            .repos
+            .iter()
+            .find(|r| r.name == *repo_name)
+            .with_context(|| {
+                format!(
+                    "unit '{}' references repo '{}' which is not in the workspace spec",
+                    unit.name, repo_name
+                )
+            })?;
+
+        let clone_dest = unit_root.join(repo_name);
+        if clone_dest.exists() {
+            continue; // Already cloned, skip
+        }
+
+        let output = std::process::Command::new("git")
+            .args(["clone", &repo_spec.url])
+            .arg(&clone_dest)
+            .output()
+            .with_context(|| {
+                format!(
+                    "run git clone for repo '{}' into {}",
+                    repo_name,
+                    clone_dest.display()
+                )
+            })?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            anyhow::bail!(
+                "git clone failed for repo '{}' into {}: {}",
+                repo_name,
+                clone_dest.display(),
+                stderr.trim()
+            );
+        }
+    }
+
+    Ok(())
+}
+
+fn is_repo_dirty(repo_path: &Path) -> Result<bool> {
+    let output = std::process::Command::new("git")
+        .args(["status", "--porcelain"])
+        .current_dir(repo_path)
+        .output()
+        .with_context(|| format!("run git status in {}", repo_path.display()))?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "git status failed in {}: {}",
+            repo_path.display(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    Ok(!output.stdout.is_empty())
+}
+
+/// Stash dirty repos, returning the list of repos that were successfully stashed.
+fn autostash_dirty_repos(dirty_repos: &[DirtyRepo]) -> Result<Vec<DirtyRepo>> {
+    let mut stashed = Vec::new();
+
+    for dirty in dirty_repos {
+        let output = std::process::Command::new("git")
+            .args(["stash", "push", "-m", "gr2-autostash"])
+            .current_dir(&dirty.repo_path)
+            .output()
+            .with_context(|| {
+                format!(
+                    "git stash in {} for unit '{}' repo '{}'",
+                    dirty.repo_path.display(),
+                    dirty.unit_name,
+                    dirty.repo_name
+                )
+            })?;
+
+        if !output.status.success() {
+            anyhow::bail!(
+                "git stash failed in {} for unit '{}' repo '{}': {}",
+                dirty.repo_path.display(),
+                dirty.unit_name,
+                dirty.repo_name,
+                String::from_utf8_lossy(&output.stderr).trim()
+            );
+        }
+
+        stashed.push(dirty.clone());
+    }
+
+    Ok(stashed)
+}
+
+/// Pop stashes for repos that were stashed. Returns errors for repos that
+/// failed to pop (e.g. conflict), but does not abort.
+fn autostash_pop(stashed: &[DirtyRepo]) -> Vec<String> {
+    let mut errors = Vec::new();
+
+    for dirty in stashed {
+        let output = std::process::Command::new("git")
+            .args(["stash", "pop"])
+            .current_dir(&dirty.repo_path)
+            .output();
+
+        match output {
+            Ok(out) if !out.status.success() => {
+                errors.push(format!(
+                    "unit '{}' repo '{}' at {}: {}",
+                    dirty.unit_name,
+                    dirty.repo_name,
+                    dirty.repo_path.display(),
+                    String::from_utf8_lossy(&out.stderr).trim()
+                ));
+            }
+            Err(e) => {
+                errors.push(format!(
+                    "unit '{}' repo '{}' at {}: {}",
+                    dirty.unit_name,
+                    dirty.repo_name,
+                    dirty.repo_path.display(),
+                    e
+                ));
+            }
+            _ => {}
+        }
+    }
+
+    errors
+}
+
+fn record_stash_state(
+    workspace_root: &Path,
+    stashed: &[DirtyRepo],
+    pop_errors: &[String],
+) -> Result<()> {
+    let state_dir = workspace_root.join(".grip/state");
+    fs::create_dir_all(&state_dir)
+        .with_context(|| format!("create state directory {}", state_dir.display()))?;
+
+    let timestamp = chrono::Utc::now().to_rfc3339();
+    let mut content = format!("# Autostash record: {}\n\n", timestamp);
+
+    for dirty in stashed {
+        content.push_str("[[stash]]\n");
+        content.push_str(&format!("timestamp = \"{}\"\n", timestamp));
+        content.push_str(&format!("unit = \"{}\"\n", dirty.unit_name));
+        content.push_str(&format!("repo = \"{}\"\n", dirty.repo_name));
+        content.push_str(&format!("path = \"{}\"\n", dirty.repo_path.display()));
+        let restored = !pop_errors
+            .iter()
+            .any(|e| e.contains(&dirty.unit_name) && e.contains(&dirty.repo_name));
+        content.push_str(&format!("restored = {}\n\n", restored));
+    }
+
+    if !pop_errors.is_empty() {
+        content.push_str("# Pop errors (manual recovery needed):\n");
+        for err in pop_errors {
+            content.push_str(&format!("# {}\n", err));
+        }
+    }
+
+    let stash_path = state_dir.join("stash.toml");
+    fs::write(&stash_path, content)
+        .with_context(|| format!("write stash state to {}", stash_path.display()))?;
+
+    Ok(())
+}
+
+fn record_apply_state(workspace_root: &Path, actions: &[String]) -> Result<()> {
+    let state_dir = workspace_root.join(".grip/state");
+    fs::create_dir_all(&state_dir)
+        .with_context(|| format!("create state directory {}", state_dir.display()))?;
+
+    let timestamp = chrono::Utc::now().to_rfc3339();
+    let mut content = format!("# Last apply: {}\n\n", timestamp);
+    content.push_str("[[applied]]\n");
+    content.push_str(&format!("timestamp = \"{}\"\n", timestamp));
+    content.push_str(&format!(
+        "actions = [{}]\n",
+        actions
+            .iter()
+            .map(|a| format!("\"{}\"", a.replace('"', "\\\"")))
+            .collect::<Vec<_>>()
+            .join(", ")
+    ));
+
+    let state_path = state_dir.join("applied.toml");
+
+    // Append to existing state file
+    if state_path.exists() {
+        let existing = fs::read_to_string(&state_path)?;
+        content = format!("{}\n{}", existing.trim_end(), content);
+    }
+
+    fs::write(&state_path, content)
+        .with_context(|| format!("write apply state to {}", state_path.display()))?;
+
+    Ok(())
+}
+
+fn render_unit_toml(unit: &UnitSpec) -> String {
+    let repos = if unit.repos.is_empty() {
+        "[]".to_string()
+    } else {
+        format!(
+            "[{}]",
+            unit.repos
+                .iter()
+                .map(|repo| format!("\"{}\"", repo))
+                .collect::<Vec<_>>()
+                .join(", ")
+        )
+    };
+
+    format!(
+        "name = \"{}\"\nkind = \"unit\"\nrepos = {}\n",
+        unit.name, repos
+    )
+}
diff --git a/gr2/src/repo_status.rs b/gr2/src/repo_status.rs
new file mode 100644
index 00000000..4b89bc5d
--- /dev/null
+++ b/gr2/src/repo_status.rs
@@ -0,0 +1,329 @@
+use anyhow::{Context, Result};
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use crate::spec::{read_workspace_spec, RepoSpec, UnitSpec};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RepoAction {
+    CloneMissing,
+    BlockPathConflict,
+    BlockDirty,
+    FastForward,
+    ManualSync,
+    NoChange,
+}
+
+impl RepoAction {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::CloneMissing => "clone_missing",
+            Self::BlockPathConflict => "block_path_conflict",
+            Self::BlockDirty => "block_dirty",
+            Self::FastForward => "fast_forward",
+            Self::ManualSync => "manual_sync",
+            Self::NoChange => "no_change",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RepoScope {
+    Shared,
+    Unit,
+}
+
+impl RepoScope {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Shared => "shared",
+            Self::Unit => "unit",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RepoStatusRow {
+    pub scope: RepoScope,
+    pub target: String,
+    pub repo: String,
+    pub path: PathBuf,
+    pub action: RepoAction,
+    pub branch: Option<String>,
+    pub upstream: Option<String>,
+    pub dirty: bool,
+    pub ahead: u32,
+    pub behind: u32,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RepoStatusReport {
+    pub rows: Vec<RepoStatusRow>,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct RepoStatusFilter {
+    pub unit: Option<String>,
+    pub repo: Option<String>,
+}
+
+impl RepoStatusReport {
+    pub fn load(workspace_root: &Path, filter: &RepoStatusFilter) -> Result<Self> {
+        let spec = read_workspace_spec(workspace_root)?;
+        let mut rows = Vec::new();
+
+        for repo in &spec.repos {
+            if filter.repo.as_deref().is_some_and(|name| name != repo.name) {
+                continue;
+            }
+            rows.push(classify_shared_repo(workspace_root, repo)?);
+        }
+
+        for unit in &spec.units {
+            if filter.unit.as_deref().is_some_and(|name| name != unit.name) {
+                continue;
+            }
+            for repo_name in &unit.repos {
+                if filter.repo.as_deref().is_some_and(|name| name != repo_name) {
+                    continue;
+                }
+                let repo = spec
+                    .repos
+                    .iter()
+                    .find(|repo| repo.name == *repo_name)
+                    .with_context(|| {
+                        format!(
+                            "unit '{}' references repo '{}' which is missing from workspace spec",
+                            unit.name, repo_name
+                        )
+                    })?;
+                rows.push(classify_unit_repo(workspace_root, unit, repo)?);
+            }
+        }
+
+        rows.sort_by(|a, b| {
+            a.scope
+                .as_str()
+                .cmp(b.scope.as_str())
+                .then_with(|| a.target.cmp(&b.target))
+                .then_with(|| a.repo.cmp(&b.repo))
+        });
+
+        Ok(Self { rows })
+    }
+
+    pub fn render_table(&self) -> String {
+        if self.rows.is_empty() {
+            return "RepoStatus\n- no repo targets matched\n".to_string();
+        }
+
+        let mut lines = vec![
+            "RepoStatus".to_string(),
+            "SCOPE\tTARGET\tREPO\tACTION\tBRANCH\tUPSTREAM\tSTATE\tREASON".to_string(),
+        ];
+
+        for row in &self.rows {
+            let mut state = Vec::new();
+            if row.dirty {
+                state.push("dirty".to_string());
+            }
+            if row.ahead > 0 {
+                state.push(format!("ahead={}", row.ahead));
+            }
+            if row.behind > 0 {
+                state.push(format!("behind={}", row.behind));
+            }
+            if state.is_empty() {
+                state.push("clean".to_string());
+            }
+
+            lines.push(format!(
+                "{}\t{}\t{}\t{}\t{}\t{}\t{}\t{}",
+                row.scope.as_str(),
+                row.target,
+                row.repo,
+                row.action.as_str(),
+                row.branch.as_deref().unwrap_or("-"),
+                row.upstream.as_deref().unwrap_or("-"),
+                state.join(","),
+                row.reason
+            ));
+        }
+
+        lines.join("\n")
+    }
+}
+
+fn classify_shared_repo(workspace_root: &Path, repo: &RepoSpec) -> Result<RepoStatusRow> {
+    let path = workspace_root.join(&repo.path);
+    let mut row = base_row(
+        RepoScope::Shared,
+        repo.name.clone(),
+        repo.name.clone(),
+        path.clone(),
+    );
+
+    if !path.exists() {
+        row.action = RepoAction::CloneMissing;
+        row.reason = "shared repo path is absent".to_string();
+        return Ok(row);
+    }
+
+    if !is_git_repo(&path)? {
+        row.action = RepoAction::BlockPathConflict;
+        row.reason = "shared repo path exists but is not a git repo".to_string();
+        return Ok(row);
+    }
+
+    fill_git_status(&path, &mut row)?;
+    classify_repo_state(&mut row, true);
+    Ok(row)
+}
+
+fn classify_unit_repo(
+    workspace_root: &Path,
+    unit: &UnitSpec,
+    repo: &RepoSpec,
+) -> Result<RepoStatusRow> {
+    let path = workspace_root.join(&unit.path).join(&repo.name);
+    let mut row = base_row(
+        RepoScope::Unit,
+        unit.name.clone(),
+        repo.name.clone(),
+        path.clone(),
+    );
+
+    if !path.exists() {
+        row.action = RepoAction::CloneMissing;
+        row.reason = "unit repo checkout is absent".to_string();
+        return Ok(row);
+    }
+
+    if !is_git_repo(&path)? {
+        row.action = RepoAction::BlockPathConflict;
+        row.reason = "unit repo path exists but is not a git repo".to_string();
+        return Ok(row);
+    }
+
+    fill_git_status(&path, &mut row)?;
+    classify_repo_state(&mut row, false);
+    Ok(row)
+}
+
+fn base_row(scope: RepoScope, target: String, repo: String, path: PathBuf) -> RepoStatusRow {
+    RepoStatusRow {
+        scope,
+        target,
+        repo,
+        path,
+        action: RepoAction::NoChange,
+        branch: None,
+        upstream: None,
+        dirty: false,
+        ahead: 0,
+        behind: 0,
+        reason: String::new(),
+    }
+}
+
+fn classify_repo_state(row: &mut RepoStatusRow, allow_ff: bool) {
+    if row.dirty {
+        row.action = RepoAction::BlockDirty;
+        row.reason = "working tree is dirty; stop by default".to_string();
+        return;
+    }
+
+    match (row.ahead, row.behind, row.upstream.is_some()) {
+        (_, _, false) => {
+            row.action = RepoAction::ManualSync;
+            row.reason = "repo has no upstream tracking branch".to_string();
+        }
+        (0, 0, true) => {
+            row.action = RepoAction::NoChange;
+            row.reason = "repo is already aligned with upstream".to_string();
+        }
+        (0, behind, true) if behind > 0 && allow_ff => {
+            row.action = RepoAction::FastForward;
+            row.reason = format!("repo is behind upstream by {} commit(s)", behind);
+        }
+        (0, behind, true) if behind > 0 => {
+            row.action = RepoAction::ManualSync;
+            row.reason = format!(
+                "repo is behind upstream by {} commit(s), but unit repos require explicit sync",
+                behind
+            );
+        }
+        (ahead, behind, true) if ahead > 0 && behind > 0 => {
+            row.action = RepoAction::ManualSync;
+            row.reason = format!(
+                "repo diverged from upstream (ahead {}, behind {})",
+                ahead, behind
+            );
+        }
+        (ahead, 0, true) if ahead > 0 => {
+            row.action = RepoAction::ManualSync;
+            row.reason = format!("repo has {} local commit(s) ahead of upstream", ahead);
+        }
+        _ => {
+            row.action = RepoAction::ManualSync;
+            row.reason = "repo requires explicit inspection".to_string();
+        }
+    }
+}
+
+fn fill_git_status(repo_path: &Path, row: &mut RepoStatusRow) -> Result<()> {
+    row.branch = git_stdout(repo_path, &["symbolic-ref", "--quiet", "--short", "HEAD"]).ok();
+    row.upstream = git_stdout(
+        repo_path,
+        &[
+            "rev-parse",
+            "--abbrev-ref",
+            "--symbolic-full-name",
+            "@{upstream}",
+        ],
+    )
+    .ok();
+    row.dirty = !git_stdout(repo_path, &["status", "--porcelain"])?.is_empty();
+
+    if row.upstream.is_some() {
+        let counts = git_stdout(
+            repo_path,
+            &["rev-list", "--left-right", "--count", "HEAD...@{upstream}"],
+        )?;
+        let mut parts = counts.split_whitespace();
+        row.ahead = parts.next().unwrap_or("0").parse().unwrap_or(0);
+        row.behind = parts.next().unwrap_or("0").parse().unwrap_or(0);
+    }
+
+    Ok(())
+}
+
+fn is_git_repo(path: &Path) -> Result<bool> {
+    let output = Command::new("git")
+        .args(["rev-parse", "--is-inside-work-tree"])
+        .current_dir(path)
+        .output()
+        .with_context(|| format!("run git rev-parse in {}", path.display()))?;
+
+    Ok(output.status.success() && String::from_utf8_lossy(&output.stdout).trim() == "true")
+}
+
+fn git_stdout(repo_path: &Path, args: &[&str]) -> Result<String> {
+    let output = Command::new("git")
+        .args(args)
+        .current_dir(repo_path)
+        .output()
+        .with_context(|| format!("run git {:?} in {}", args, repo_path.display()))?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "git {:?} failed in {}: {}",
+            args,
+            repo_path.display(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())
+}
diff --git a/gr2/src/spec.rs b/gr2/src/spec.rs
new file mode 100644
index 00000000..b21c32cf
--- /dev/null
+++ b/gr2/src/spec.rs
@@ -0,0 +1,278 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::HashSet;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+pub const WORKSPACE_SPEC_VERSION: u32 = 1;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct WorkspaceSpec {
+    pub schema_version: u32,
+    pub workspace_name: String,
+    pub cache: CacheSpec,
+    #[serde(default)]
+    pub repos: Vec<RepoSpec>,
+    #[serde(default)]
+    pub units: Vec<UnitSpec>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct CacheSpec {
+    pub root: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RepoSpec {
+    pub name: String,
+    pub path: String,
+    pub url: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct UnitSpec {
+    pub name: String,
+    pub path: String,
+    #[serde(default)]
+    pub repos: Vec<String>,
+    #[serde(default)]
+    pub links: Vec<LinkSpec>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LinkSpec {
+    /// Source path relative to workspace root
+    pub src: String,
+    /// Destination path relative to unit root
+    pub dest: String,
+    #[serde(default)]
+    pub kind: LinkKind,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum LinkKind {
+    #[default]
+    Symlink,
+    Copy,
+}
+
+impl LinkKind {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Symlink => "symlink",
+            Self::Copy => "copy",
+        }
+    }
+}
+
+impl std::str::FromStr for LinkKind {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> anyhow::Result<Self> {
+        match s {
+            "symlink" => Ok(Self::Symlink),
+            "copy" => Ok(Self::Copy),
+            _ => anyhow::bail!("unknown link kind '{}': expected 'symlink' or 'copy'", s),
+        }
+    }
+}
+
+impl WorkspaceSpec {
+    pub fn from_workspace(workspace_root: &Path) -> Result<Self> {
+        let workspace_name = read_workspace_name(workspace_root)?;
+        let repos = read_registered_repos(workspace_root)?;
+        let units = read_registered_units(workspace_root)?;
+
+        Ok(Self {
+            schema_version: WORKSPACE_SPEC_VERSION,
+            workspace_name,
+            cache: CacheSpec {
+                root: ".grip/cache".to_string(),
+            },
+            repos,
+            units,
+        })
+    }
+
+    pub fn validate_for_plan(&self) -> Result<()> {
+        if self.schema_version != WORKSPACE_SPEC_VERSION {
+            anyhow::bail!(
+                "unsupported workspace spec schema_version {}: expected {}",
+                self.schema_version,
+                WORKSPACE_SPEC_VERSION
+            );
+        }
+
+        if self.workspace_name.trim().is_empty() {
+            anyhow::bail!("workspace spec workspace_name must not be empty");
+        }
+
+        let mut repo_names = HashSet::new();
+        for repo in &self.repos {
+            if !repo_names.insert(repo.name.clone()) {
+                anyhow::bail!("workspace spec contains duplicate repo '{}'", repo.name);
+            }
+
+            if repo.path.trim().is_empty() || repo.url.trim().is_empty() {
+                anyhow::bail!("repo '{}' must include non-empty path and url", repo.name);
+            }
+        }
+
+        let mut unit_names = HashSet::new();
+        for unit in &self.units {
+            if !unit_names.insert(unit.name.clone()) {
+                anyhow::bail!("workspace spec contains duplicate unit '{}'", unit.name);
+            }
+
+            if unit.path.trim().is_empty() {
+                anyhow::bail!("unit '{}' must include a non-empty path", unit.name);
+            }
+
+            for repo_name in &unit.repos {
+                if !repo_names.contains(repo_name) {
+                    anyhow::bail!(
+                        "unit '{}' references missing repo '{}'",
+                        unit.name,
+                        repo_name
+                    );
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    pub fn validate(&self, workspace_root: &Path) -> Result<()> {
+        self.validate_for_plan()?;
+
+        for repo in &self.repos {
+            let repo_root = workspace_root.join(&repo.path);
+            if !repo_root.join("repo.toml").exists() {
+                anyhow::bail!(
+                    "workspace spec repo '{}' is missing repo metadata at {}",
+                    repo.name,
+                    repo_root.join("repo.toml").display()
+                );
+            }
+        }
+
+        for unit in &self.units {
+            let unit_root = workspace_root.join(&unit.path);
+            if !unit_root.join("unit.toml").exists() {
+                anyhow::bail!(
+                    "workspace spec unit '{}' is missing unit metadata at {}",
+                    unit.name,
+                    unit_root.join("unit.toml").display()
+                );
+            }
+        }
+
+        Ok(())
+    }
+}
+
+pub fn write_workspace_spec(workspace_root: &Path, spec: &WorkspaceSpec) -> Result<PathBuf> {
+    let spec_path = workspace_spec_path(workspace_root);
+    let content = toml::to_string_pretty(spec).context("serialize workspace spec")?;
+    fs::write(&spec_path, content)
+        .with_context(|| format!("write workspace spec to {}", spec_path.display()))?;
+    Ok(spec_path)
+}
+
+pub fn read_workspace_spec(workspace_root: &Path) -> Result<WorkspaceSpec> {
+    let spec_path = workspace_spec_path(workspace_root);
+    let content = fs::read_to_string(&spec_path)
+        .with_context(|| format!("read workspace spec from {}", spec_path.display()))?;
+    toml::from_str(&content).context("parse workspace spec")
+}
+
+pub fn workspace_spec_path(workspace_root: &Path) -> PathBuf {
+    workspace_root.join(".grip/workspace_spec.toml")
+}
+
+fn read_workspace_name(workspace_root: &Path) -> Result<String> {
+    let workspace_toml = fs::read_to_string(workspace_root.join(".grip/workspace.toml"))
+        .context("read .grip/workspace.toml")?;
+    workspace_toml
+        .lines()
+        .find_map(|line| line.strip_prefix("name = \""))
+        .and_then(|line| line.strip_suffix('"'))
+        .map(str::to_owned)
+        .context("workspace name missing from .grip/workspace.toml")
+}
+
+fn read_registered_repos(workspace_root: &Path) -> Result<Vec<RepoSpec>> {
+    let repos_root = workspace_root.join("repos");
+    let mut repos = Vec::new();
+
+    for entry in fs::read_dir(&repos_root)? {
+        let entry = entry?;
+        if !entry.file_type()?.is_dir() {
+            continue;
+        }
+
+        let repo_root = entry.path();
+        let repo_toml = repo_root.join("repo.toml");
+        if !repo_toml.exists() {
+            continue;
+        }
+
+        let content = fs::read_to_string(&repo_toml)?;
+        let fallback_name = entry.file_name().to_string_lossy().into_owned();
+        let name = content
+            .lines()
+            .find_map(|line| line.strip_prefix("name = \""))
+            .and_then(|line| line.strip_suffix('"'))
+            .map(str::to_owned)
+            .unwrap_or(fallback_name.clone());
+        let url = content
+            .lines()
+            .find_map(|line| line.strip_prefix("url = \""))
+            .and_then(|line| line.strip_suffix('"'))
+            .unwrap_or("")
+            .to_string();
+
+        repos.push(RepoSpec {
+            name,
+            path: format!("repos/{}", fallback_name),
+            url,
+        });
+    }
+
+    repos.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(repos)
+}
+
+fn read_registered_units(workspace_root: &Path) -> Result<Vec<UnitSpec>> {
+    let units_root = workspace_root.join("agents");
+    let mut units = Vec::new();
+
+    if !units_root.exists() {
+        return Ok(units);
+    }
+
+    for entry in fs::read_dir(&units_root)? {
+        let entry = entry?;
+        if !entry.file_type()?.is_dir() {
+            continue;
+        }
+
+        let unit_root = entry.path();
+        let unit_toml = unit_root.join("unit.toml");
+        if !unit_toml.exists() {
+            continue;
+        }
+
+        let fallback_name = entry.file_name().to_string_lossy().into_owned();
+        units.push(UnitSpec {
+            name: fallback_name.clone(),
+            path: format!("agents/{}", fallback_name),
+            repos: Vec::new(),
+            links: Vec::new(),
+        });
+    }
+
+    units.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(units)
+}
diff --git a/src/bin/gr2.rs b/src/bin/gr2.rs
new file mode 100644
index 00000000..344dfd48
--- /dev/null
+++ b/src/bin/gr2.rs
@@ -0,0 +1,22 @@
+//! gr2 CLI entry point
+
+use clap::Parser;
+use gr2_cli::args::Cli;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let cli = Cli::parse();
+
+    if cli.verbose {
+        tracing_subscriber::fmt()
+            .with_env_filter("gitgrip=debug")
+            .with_target(false)
+            .init();
+    } else {
+        tracing_subscriber::fmt()
+            .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+            .init();
+    }
+
+    gr2_cli::dispatch::dispatch_command(cli.command, cli.verbose).await
+}
diff --git a/src/cli/args.rs b/src/cli/args.rs
index b039b61d..1dfa6ff2 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -126,10 +126,16 @@ pub enum Commands {
         #[arg(long, value_delimiter = ',')]
         group: Option<Vec<String>>,
     },
-    /// Checkout a branch across repos
+    #[command(
+        after_help = "Examples:\n  gr checkout feat/login\n  gr checkout --base\n  gr checkout add sandbox\n  gr checkout add docs-only --group docs\n  gr checkout add app-only --repo app\n  gr checkout list\n  gr checkout remove sandbox"
+    )]
+    /// Checkout a branch across repos or manage independent child checkouts
     Checkout {
-        /// Branch name
+        /// Branch name, or `add`/`list`/`remove` for child checkout lifecycle
         name: Option<String>,
+        /// Additional checkout action args (e.g. `add <name>`)
+        #[arg(hide = true)]
+        extra: Vec<String>,
         /// Create branch if it doesn't exist
         #[arg(short = 'b', long)]
         create: bool,
@@ -349,7 +355,7 @@ pub enum Commands {
         #[command(subcommand)]
         action: TargetCommands,
     },
-    /// Manage workspace repo caches (.grip/cache/)
+    /// Manage machine-level repo caches (~/.grip/cache/ by default)
     Cache {
         #[command(subcommand)]
         action: CacheCommands,
diff --git a/src/cli/commands/branch.rs b/src/cli/commands/branch.rs
index 9c5ac4f3..91ddc099 100644
--- a/src/cli/commands/branch.rs
+++ b/src/cli/commands/branch.rs
@@ -4,7 +4,10 @@ use crate::cli::output::Output;
 use crate::core::manifest::Manifest;
 use crate::core::repo::{filter_repos, get_manifest_repo_info, RepoInfo};
 use crate::git::{
-    branch::{branch_exists, create_and_checkout_branch, delete_local_branch, list_local_branches},
+    branch::{
+        branch_exists, checkout_branch, create_and_checkout_branch, delete_local_branch,
+        list_local_branches,
+    },
     get_current_branch, open_repo,
 };
 use std::path::PathBuf;
@@ -473,15 +476,42 @@ pub fn run_branch(opts: BranchOptions<'_>) -> anyhow::Result<()> {
                 match open_repo(&repo.absolute_path) {
                     Ok(git_repo) => {
                         if branch_exists(&git_repo, branch_name) {
-                            if opts.json {
-                                json_results.push(JsonCreateResult {
-                                    repo: repo.name.clone(),
-                                    branch: branch_name.to_string(),
-                                    action: "already_exists".to_string(),
-                                    error: None,
-                                });
-                            } else {
-                                Output::info(&format!("{}: already exists", repo.name));
+                            // Branch exists — switch to it so subsequent commits
+                            // land on this branch, not the previous one (grip#401).
+                            match checkout_branch(&git_repo, branch_name) {
+                                Ok(()) => {
+                                    if opts.json {
+                                        json_results.push(JsonCreateResult {
+                                            repo: repo.name.clone(),
+                                            branch: branch_name.to_string(),
+                                            action: "switched".to_string(),
+                                            error: None,
+                                        });
+                                    } else {
+                                        Output::info(&format!(
+                                            "{}: already exists, switched",
+                                            repo.name
+                                        ));
+                                    }
+                                }
+                                Err(e) => {
+                                    if opts.json {
+                                        json_results.push(JsonCreateResult {
+                                            repo: repo.name.clone(),
+                                            branch: branch_name.to_string(),
+                                            action: "error".to_string(),
+                                            error: Some(format!(
+                                                "exists but failed to switch: {}",
+                                                e
+                                            )),
+                                        });
+                                    } else {
+                                        Output::error(&format!(
+                                            "{}: exists but failed to switch: {}",
+                                            repo.name, e
+                                        ));
+                                    }
+                                }
                             }
                             continue;
                         }
diff --git a/src/cli/commands/cache.rs b/src/cli/commands/cache.rs
index 54c58772..f2d1f182 100644
--- a/src/cli/commands/cache.rs
+++ b/src/cli/commands/cache.rs
@@ -1,6 +1,6 @@
 //! Cache command implementation
 //!
-//! Manages bare-repo caches under `.grip/cache/` for workspace repos.
+//! Manages bare-repo caches under the machine-level cache root for workspace repos.
 
 use crate::cli::args::CacheCommands;
 use crate::cli::output::Output;
@@ -50,7 +50,12 @@ pub fn run_cache(
                 Output::info("Updating all caches...");
             }
 
-            let count = workspace_cache::update_all(workspace_root)?;
+            let repo_pairs: Vec<(&str, &str)> = repos
+                .iter()
+                .map(|r| (r.name.as_str(), r.url.as_str()))
+                .collect();
+
+            let count = workspace_cache::update_all(workspace_root, repo_pairs.into_iter())?;
 
             if !quiet {
                 Output::success(&format!("Updated {} cache(s)", count));
@@ -58,12 +63,6 @@ pub fn run_cache(
         }
 
         CacheCommands::Status => {
-            let cache_dir = workspace_root.join(".grip").join("cache");
-            if !cache_dir.is_dir() {
-                Output::info("No caches exist yet. Run 'gr cache bootstrap' to create them.");
-                return Ok(());
-            }
-
             println!(
                 "{:<20} {:<8} {}",
                 "Repo".bold(),
@@ -73,8 +72,9 @@ pub fn run_cache(
             println!("{}", "─".repeat(70));
 
             for repo in &repos {
-                let exists = workspace_cache::cache_exists(workspace_root, &repo.name);
-                let path = workspace_cache::cache_path(workspace_root, &repo.name);
+                let exists = workspace_cache::cache_exists(workspace_root, &repo.name, &repo.url)?;
+                let path =
+                    workspace_cache::resolve_cache_path(workspace_root, &repo.name, &repo.url)?;
                 let status = if exists {
                     "cached".green().to_string()
                 } else {
@@ -85,7 +85,11 @@ pub fn run_cache(
         }
 
         CacheCommands::Remove { repo } => {
-            let removed = workspace_cache::remove_cache(workspace_root, &repo)?;
+            let Some(repo_info) = repos.iter().find(|r| r.name == repo) else {
+                anyhow::bail!("repo '{}' is not in this manifest", repo);
+            };
+            let removed =
+                workspace_cache::remove_cache(workspace_root, &repo_info.name, &repo_info.url)?;
             if removed {
                 Output::success(&format!("Removed cache for {}", repo));
             } else {
diff --git a/src/cli/commands/checkout.rs b/src/cli/commands/checkout.rs
index ffa10269..9b5dfd40 100644
--- a/src/cli/commands/checkout.rs
+++ b/src/cli/commands/checkout.rs
@@ -3,6 +3,7 @@
 use crate::cli::output::Output;
 use crate::core::manifest::Manifest;
 use crate::core::repo::{filter_repos, get_manifest_repo_info, RepoInfo};
+use crate::core::workspace_checkout;
 use crate::git::{
     branch::{branch_exists, checkout_branch, create_and_checkout_branch},
     open_repo,
@@ -113,3 +114,84 @@ pub fn run_checkout(
 
     Ok(())
 }
+
+/// Materialize an independent child checkout from cached repos.
+///
+/// This reserves `gr checkout add <name>` while preserving the existing
+/// `gr checkout <branch>` behavior for cross-repo branch switching.
+pub fn run_checkout_add(
+    workspace_root: &Path,
+    manifest: &Manifest,
+    checkout_name: &str,
+    repos_filter: Option<&[String]>,
+    group_filter: Option<&[String]>,
+) -> anyhow::Result<()> {
+    let mut repos: Vec<RepoInfo> =
+        filter_repos(manifest, workspace_root, repos_filter, group_filter, false);
+
+    let include_manifest = match repos_filter {
+        None => true,
+        Some(filter) => filter.iter().any(|r| r == "manifest"),
+    };
+    if include_manifest {
+        if let Some(manifest_repo) = get_manifest_repo_info(manifest, workspace_root) {
+            repos.push(manifest_repo);
+        }
+    }
+
+    if repos.is_empty() {
+        anyhow::bail!("no repos matched checkout filters");
+    }
+
+    let repo_specs: Vec<(&str, &str, &str)> = repos
+        .iter()
+        .map(|repo| (repo.name.as_str(), repo.url.as_str(), repo.path.as_str()))
+        .collect();
+
+    let info = workspace_checkout::create_checkout(
+        workspace_root,
+        checkout_name,
+        repo_specs.into_iter(),
+        None,
+    )?;
+
+    Output::success(&format!(
+        "Created checkout '{}' with {} repo(s)",
+        info.name,
+        info.repos.len()
+    ));
+    Output::info(&format!("Path: {}", info.path.display()));
+    Ok(())
+}
+
+/// List cache-backed child checkouts.
+pub fn run_checkout_list(workspace_root: &Path) -> anyhow::Result<()> {
+    Output::header("Checkouts");
+    println!();
+
+    let checkouts = workspace_checkout::list_checkouts(workspace_root)?;
+    if checkouts.is_empty() {
+        println!("No checkouts configured.");
+        return Ok(());
+    }
+
+    for checkout in checkouts {
+        println!("{} -> {}", checkout.name, checkout.path.display());
+    }
+
+    Ok(())
+}
+
+/// Remove a cache-backed child checkout.
+pub fn run_checkout_remove(workspace_root: &Path, checkout_name: &str) -> anyhow::Result<()> {
+    Output::header(&format!("Removing checkout '{}'", checkout_name));
+    println!();
+
+    let removed = workspace_checkout::remove_checkout(workspace_root, checkout_name)?;
+    if removed {
+        Output::success(&format!("Removed checkout '{}'", checkout_name));
+        Ok(())
+    } else {
+        anyhow::bail!("Checkout '{}' not found", checkout_name);
+    }
+}
diff --git a/src/cli/commands/link.rs b/src/cli/commands/link.rs
index b43b3e1c..6e539e93 100644
--- a/src/cli/commands/link.rs
+++ b/src/cli/commands/link.rs
@@ -8,7 +8,104 @@ use crate::core::manifest_paths;
 use crate::core::repo::RepoInfo;
 use crate::files::{process_composefiles, resolve_file_source};
 use crate::git::path_exists;
-use std::path::Path;
+use std::path::{Path, PathBuf};
+
+/// Check if a source path contains glob characters (`*`, `?`, `[`).
+fn is_glob_pattern(src: &str) -> bool {
+    src.contains('*') || src.contains('?') || src.contains('[')
+}
+
+/// Expand a glob source pattern into individual (src, dest) pairs.
+///
+/// Given `src: "prompts/**"` and `dest: ".gitgrip/prompts/"`, this expands to:
+///   - `prompts/opus.md` -> `.gitgrip/prompts/opus.md`
+///   - `prompts/atlas.md` -> `.gitgrip/prompts/atlas.md`
+///
+/// The glob base (the non-glob prefix before the first glob character) is
+/// stripped from each matched path, and the remainder is appended to `dest`.
+fn expand_glob(src_pattern: &str, dest: &str, base_dir: &Path) -> Vec<(PathBuf, PathBuf)> {
+    let full_pattern = base_dir.join(src_pattern);
+    let pattern_str = match full_pattern.to_str() {
+        Some(s) => s.to_string(),
+        None => return Vec::new(),
+    };
+
+    let glob_base = glob_base_dir(src_pattern);
+
+    let entries = match glob::glob(&pattern_str) {
+        Ok(paths) => paths,
+        Err(e) => {
+            Output::warning(&format!("Invalid glob pattern '{}': {}", src_pattern, e));
+            return Vec::new();
+        }
+    };
+
+    let mut result = Vec::new();
+    for entry in entries.flatten() {
+        if entry.is_dir() {
+            continue; // only link/copy files, not directories
+        }
+        // Strip base_dir to get the repo-relative path
+        let rel_path = match entry.strip_prefix(base_dir) {
+            Ok(p) => p,
+            Err(_) => continue,
+        };
+        // Strip the glob base prefix to get the relative portion
+        let suffix = if glob_base.is_empty() {
+            rel_path.to_path_buf()
+        } else {
+            match rel_path.strip_prefix(&glob_base) {
+                Ok(s) => s.to_path_buf(),
+                Err(_) => rel_path.to_path_buf(),
+            }
+        };
+        let dest_path = PathBuf::from(dest).join(&suffix);
+        result.push((entry, dest_path));
+    }
+    result
+}
+
+/// Extract the non-glob directory prefix from a pattern.
+/// e.g. "prompts/**/*.md" -> "prompts", "**" -> "", "config/a*.toml" -> "config"
+fn glob_base_dir(pattern: &str) -> String {
+    let parts: Vec<&str> = pattern.split('/').collect();
+    let mut base_parts = Vec::new();
+    for part in parts {
+        if is_glob_pattern(part) {
+            break;
+        }
+        base_parts.push(part);
+    }
+    base_parts.join("/")
+}
+
+/// Expand a single src/dest pair, handling globs if present.
+/// For non-glob src, returns a single (absolute_source, dest) pair.
+/// For glob src, returns expanded pairs via `expand_glob`.
+fn expand_copy_pairs(src: &str, dest: &str, base_dir: &Path) -> Vec<(PathBuf, PathBuf)> {
+    if is_glob_pattern(src) {
+        expand_glob(src, dest, base_dir)
+    } else {
+        vec![(base_dir.join(src), PathBuf::from(dest))]
+    }
+}
+
+/// Create a symlink, returning (Result, label) for error reporting.
+/// Handles platform differences (unix symlink vs windows symlink_file/symlink_dir).
+fn apply_symlink(source: &Path, dest: &Path) -> (std::io::Result<()>, &'static str) {
+    #[cfg(unix)]
+    {
+        (std::os::unix::fs::symlink(source, dest), "symlink")
+    }
+    #[cfg(windows)]
+    {
+        if source.is_dir() {
+            (std::os::windows::fs::symlink_dir(source, dest), "symlink")
+        } else {
+            (std::os::windows::fs::symlink_file(source, dest), "symlink")
+        }
+    }
+}
 
 /// Run the link command
 pub fn run_link(
@@ -399,123 +496,83 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
             continue;
         }
 
-        // Apply copyfiles
+        // Apply copyfiles (with glob expansion)
         if let Some(ref copyfiles) = config.copyfile {
-            for copyfile in copyfiles {
-                let source = repo
-                    .map(|r| r.absolute_path.join(&copyfile.src))
-                    .unwrap_or_else(|| workspace_root.join(&config.path).join(&copyfile.src));
-                let dest = workspace_root.join(&copyfile.dest);
-
-                if !source.exists() {
-                    Output::warning(&format!("Source not found: {:?}", source));
-                    errors += 1;
-                    continue;
-                }
+            let base_dir = repo
+                .map(|r| r.absolute_path.clone())
+                .unwrap_or_else(|| workspace_root.join(&config.path));
 
-                // Create parent directory if needed
-                if let Some(parent) = dest.parent() {
-                    std::fs::create_dir_all(parent)?;
-                }
-
-                match std::fs::copy(&source, &dest) {
-                    Ok(_) => {
-                        if !quiet {
-                            Output::success(&format!(
-                                "[copy] {} -> {}",
-                                copyfile.src, copyfile.dest
-                            ));
-                        }
-                        applied += 1;
-                    }
-                    Err(e) => {
-                        Output::error(&format!("Failed to copy: {}", e));
+            for copyfile in copyfiles {
+                let pairs = expand_copy_pairs(&copyfile.src, &copyfile.dest, &base_dir);
+                for (source, rel_dest) in &pairs {
+                    let dest = workspace_root.join(rel_dest);
+                    if !source.exists() {
+                        Output::warning(&format!("Source not found: {:?}", source));
                         errors += 1;
+                        continue;
+                    }
+                    if let Some(parent) = dest.parent() {
+                        std::fs::create_dir_all(parent)?;
+                    }
+                    match std::fs::copy(source, &dest) {
+                        Ok(_) => {
+                            if !quiet {
+                                Output::success(&format!(
+                                    "[copy] {} -> {}",
+                                    source.display(),
+                                    rel_dest.display()
+                                ));
+                            }
+                            applied += 1;
+                        }
+                        Err(e) => {
+                            Output::error(&format!("Failed to copy: {}", e));
+                            errors += 1;
+                        }
                     }
                 }
             }
         }
 
-        // Apply linkfiles
+        // Apply linkfiles (with glob expansion)
         if let Some(ref linkfiles) = config.linkfile {
-            for linkfile in linkfiles {
-                let source = repo
-                    .map(|r| r.absolute_path.join(&linkfile.src))
-                    .unwrap_or_else(|| workspace_root.join(&config.path).join(&linkfile.src));
-                let dest = workspace_root.join(&linkfile.dest);
+            let base_dir = repo
+                .map(|r| r.absolute_path.clone())
+                .unwrap_or_else(|| workspace_root.join(&config.path));
 
-                if !source.exists() {
-                    Output::warning(&format!("Source not found: {:?}", source));
-                    errors += 1;
-                    continue;
-                }
-
-                // Create parent directory if needed
-                if let Some(parent) = dest.parent() {
-                    std::fs::create_dir_all(parent)?;
-                }
-
-                // Remove existing link/file if present
-                if dest.exists() || dest.is_symlink() {
-                    let _ = std::fs::remove_file(&dest);
-                }
-
-                #[cfg(unix)]
-                {
-                    match std::os::unix::fs::symlink(&source, &dest) {
+            for linkfile in linkfiles {
+                let pairs = expand_copy_pairs(&linkfile.src, &linkfile.dest, &base_dir);
+                for (source, rel_dest) in &pairs {
+                    let dest = workspace_root.join(rel_dest);
+                    if !source.exists() {
+                        Output::warning(&format!("Source not found: {:?}", source));
+                        errors += 1;
+                        continue;
+                    }
+                    if let Some(parent) = dest.parent() {
+                        std::fs::create_dir_all(parent)?;
+                    }
+                    if dest.exists() || dest.is_symlink() {
+                        let _ = std::fs::remove_file(&dest);
+                    }
+                    let (result, label) = apply_symlink(source, &dest);
+                    match result {
                         Ok(_) => {
                             if !quiet {
                                 Output::success(&format!(
                                     "[link] {} -> {}",
-                                    linkfile.src, linkfile.dest
+                                    source.display(),
+                                    rel_dest.display()
                                 ));
                             }
                             applied += 1;
                         }
                         Err(e) => {
-                            Output::error(&format!("Failed to create symlink: {}", e));
+                            Output::error(&format!("Failed to create {}: {}", label, e));
                             errors += 1;
                         }
                     }
                 }
-
-                #[cfg(windows)]
-                {
-                    // On Windows, use junction for directories, symlink for files
-                    if source.is_dir() {
-                        match std::os::windows::fs::symlink_dir(&source, &dest) {
-                            Ok(_) => {
-                                if !quiet {
-                                    Output::success(&format!(
-                                        "[link] {} -> {}",
-                                        linkfile.src, linkfile.dest
-                                    ));
-                                }
-                                applied += 1;
-                            }
-                            Err(e) => {
-                                Output::error(&format!("Failed to create symlink: {}", e));
-                                errors += 1;
-                            }
-                        }
-                    } else {
-                        match std::os::windows::fs::symlink_file(&source, &dest) {
-                            Ok(_) => {
-                                if !quiet {
-                                    Output::success(&format!(
-                                        "[link] {} -> {}",
-                                        linkfile.src, linkfile.dest
-                                    ));
-                                }
-                                applied += 1;
-                            }
-                            Err(e) => {
-                                Output::error(&format!("Failed to create symlink: {}", e));
-                                errors += 1;
-                            }
-                        }
-                    }
-                }
             }
         }
     }
@@ -526,9 +583,37 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
         let spaces_dir = manifest_paths::spaces_dir(workspace_root);
 
         if manifests_dir.exists() {
-            // Apply manifest copyfiles
+            // Apply manifest copyfiles (with glob expansion)
             if let Some(ref copyfiles) = manifest_config.copyfile {
                 for copyfile in copyfiles {
+                    // Glob expansion only for non-gripspace sources
+                    if !copyfile.src.starts_with("gripspace:") && is_glob_pattern(&copyfile.src) {
+                        let pairs = expand_glob(&copyfile.src, &copyfile.dest, &manifests_dir);
+                        for (source, rel_dest) in &pairs {
+                            let dest = workspace_root.join(rel_dest);
+                            if let Some(parent) = dest.parent() {
+                                std::fs::create_dir_all(parent)?;
+                            }
+                            match std::fs::copy(source, &dest) {
+                                Ok(_) => {
+                                    if !quiet {
+                                        Output::success(&format!(
+                                            "[copy] manifest:{} -> {}",
+                                            source.display(),
+                                            rel_dest.display()
+                                        ));
+                                    }
+                                    applied += 1;
+                                }
+                                Err(e) => {
+                                    Output::error(&format!("Failed to copy: {}", e));
+                                    errors += 1;
+                                }
+                            }
+                        }
+                        continue;
+                    }
+
                     let source =
                         match resolve_file_source(&copyfile.src, &manifests_dir, &spaces_dir) {
                             Ok(p) => p,
@@ -539,24 +624,19 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
                             }
                         };
                     let dest = workspace_root.join(&copyfile.dest);
-
                     if !source.exists() {
                         Output::warning(&format!("Source not found: {:?}", source));
                         errors += 1;
                         continue;
                     }
-
-                    // Create parent directory if needed
                     if let Some(parent) = dest.parent() {
                         std::fs::create_dir_all(parent)?;
                     }
-
                     let label = if copyfile.src.starts_with("gripspace:") {
                         copyfile.src.clone()
                     } else {
                         format!("manifest:{}", copyfile.src)
                     };
-
                     match std::fs::copy(&source, &dest) {
                         Ok(_) => {
                             if !quiet {
@@ -572,9 +652,41 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
                 }
             }
 
-            // Apply manifest linkfiles
+            // Apply manifest linkfiles (with glob expansion)
             if let Some(ref linkfiles) = manifest_config.linkfile {
                 for linkfile in linkfiles {
+                    // Glob expansion only for non-gripspace sources
+                    if !linkfile.src.starts_with("gripspace:") && is_glob_pattern(&linkfile.src) {
+                        let pairs = expand_glob(&linkfile.src, &linkfile.dest, &manifests_dir);
+                        for (source, rel_dest) in &pairs {
+                            let dest = workspace_root.join(rel_dest);
+                            if let Some(parent) = dest.parent() {
+                                std::fs::create_dir_all(parent)?;
+                            }
+                            if dest.exists() || dest.is_symlink() {
+                                let _ = std::fs::remove_file(&dest);
+                            }
+                            let (result, label) = apply_symlink(source, &dest);
+                            match result {
+                                Ok(_) => {
+                                    if !quiet {
+                                        Output::success(&format!(
+                                            "[link] manifest:{} -> {}",
+                                            source.display(),
+                                            rel_dest.display()
+                                        ));
+                                    }
+                                    applied += 1;
+                                }
+                                Err(e) => {
+                                    Output::error(&format!("Failed to create {}: {}", label, e));
+                                    errors += 1;
+                                }
+                            }
+                        }
+                        continue;
+                    }
+
                     let source =
                         match resolve_file_source(&linkfile.src, &manifests_dir, &spaces_dir) {
                             Ok(p) => p,
@@ -585,82 +697,33 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
                             }
                         };
                     let dest = workspace_root.join(&linkfile.dest);
-
                     if !source.exists() {
                         Output::warning(&format!("Source not found: {:?}", source));
                         errors += 1;
                         continue;
                     }
-
-                    // Create parent directory if needed
                     if let Some(parent) = dest.parent() {
                         std::fs::create_dir_all(parent)?;
                     }
-
-                    // Remove existing link/file if present
                     if dest.exists() || dest.is_symlink() {
                         let _ = std::fs::remove_file(&dest);
                     }
-
                     let label = if linkfile.src.starts_with("gripspace:") {
                         linkfile.src.clone()
                     } else {
                         format!("manifest:{}", linkfile.src)
                     };
-
-                    #[cfg(unix)]
-                    {
-                        match std::os::unix::fs::symlink(&source, &dest) {
-                            Ok(_) => {
-                                if !quiet {
-                                    Output::success(&format!(
-                                        "[link] {} -> {}",
-                                        label, linkfile.dest
-                                    ));
-                                }
-                                applied += 1;
-                            }
-                            Err(e) => {
-                                Output::error(&format!("Failed to create symlink: {}", e));
-                                errors += 1;
+                    let (result, sym_label) = apply_symlink(&source, &dest);
+                    match result {
+                        Ok(_) => {
+                            if !quiet {
+                                Output::success(&format!("[link] {} -> {}", label, linkfile.dest));
                             }
+                            applied += 1;
                         }
-                    }
-
-                    #[cfg(windows)]
-                    {
-                        if source.is_dir() {
-                            match std::os::windows::fs::symlink_dir(&source, &dest) {
-                                Ok(_) => {
-                                    if !quiet {
-                                        Output::success(&format!(
-                                            "[link] {} -> {}",
-                                            label, linkfile.dest
-                                        ));
-                                    }
-                                    applied += 1;
-                                }
-                                Err(e) => {
-                                    Output::error(&format!("Failed to create symlink: {}", e));
-                                    errors += 1;
-                                }
-                            }
-                        } else {
-                            match std::os::windows::fs::symlink_file(&source, &dest) {
-                                Ok(_) => {
-                                    if !quiet {
-                                        Output::success(&format!(
-                                            "[link] {} -> {}",
-                                            label, linkfile.dest
-                                        ));
-                                    }
-                                    applied += 1;
-                                }
-                                Err(e) => {
-                                    Output::error(&format!("Failed to create symlink: {}", e));
-                                    errors += 1;
-                                }
-                            }
+                        Err(e) => {
+                            Output::error(&format!("Failed to create {}: {}", sym_label, e));
+                            errors += 1;
                         }
                     }
                 }
@@ -765,7 +828,7 @@ mod tests {
         let manifest = create_test_manifest(None, None);
 
         // Should not error even with no links
-        let result = show_link_status(&temp.path().to_path_buf(), &manifest, false);
+        let result = show_link_status(temp.path(), &manifest, false);
         assert!(result.is_ok());
     }
 
@@ -998,7 +1061,7 @@ mod tests {
         // Verify symlink points to the source file
         let dest_path = workspace.join("linked.config");
         let link_target = std::fs::read_link(&dest_path).unwrap();
-        let expected_source = repo_dir.join("shared.config");
+        let _expected_source = repo_dir.join("shared.config");
 
         // The target should resolve to the source file
         assert!(
@@ -1008,6 +1071,135 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_is_glob_pattern() {
+        assert!(is_glob_pattern("**"));
+        assert!(is_glob_pattern("*.md"));
+        assert!(is_glob_pattern("prompts/**"));
+        assert!(is_glob_pattern("config/?.toml"));
+        assert!(is_glob_pattern("[abc].txt"));
+        assert!(!is_glob_pattern("README.md"));
+        assert!(!is_glob_pattern("prompts/opus.md"));
+    }
+
+    #[test]
+    fn test_glob_base_dir() {
+        assert_eq!(glob_base_dir("**"), "");
+        assert_eq!(glob_base_dir("*.md"), "");
+        assert_eq!(glob_base_dir("prompts/**"), "prompts");
+        assert_eq!(glob_base_dir("config/nested/**/*.md"), "config/nested");
+        assert_eq!(glob_base_dir("a/b/c/*.txt"), "a/b/c");
+    }
+
+    #[test]
+    fn test_expand_glob_basic() {
+        let temp = TempDir::new().unwrap();
+        let base = temp.path();
+
+        // Create files
+        std::fs::create_dir_all(base.join("prompts")).unwrap();
+        std::fs::write(base.join("prompts/opus.md"), "opus").unwrap();
+        std::fs::write(base.join("prompts/atlas.md"), "atlas").unwrap();
+        std::fs::write(base.join("README.md"), "readme").unwrap();
+
+        let pairs = expand_glob("prompts/*", ".gitgrip/prompts/", base);
+        assert_eq!(pairs.len(), 2);
+
+        // Check that dest preserves the file name after stripping base
+        let dests: Vec<String> = pairs.iter().map(|(_, d)| d.display().to_string()).collect();
+        assert!(dests.contains(&".gitgrip/prompts/opus.md".to_string()));
+        assert!(dests.contains(&".gitgrip/prompts/atlas.md".to_string()));
+    }
+
+    #[test]
+    fn test_expand_glob_recursive() {
+        let temp = TempDir::new().unwrap();
+        let base = temp.path();
+
+        std::fs::create_dir_all(base.join("config/sub")).unwrap();
+        std::fs::write(base.join("config/a.toml"), "a").unwrap();
+        std::fs::write(base.join("config/sub/b.toml"), "b").unwrap();
+
+        let pairs = expand_glob("config/**/*.toml", "./", base);
+        assert_eq!(pairs.len(), 2);
+
+        let dests: Vec<String> = pairs.iter().map(|(_, d)| d.display().to_string()).collect();
+        assert!(dests.contains(&"a.toml".to_string()) || dests.contains(&"./a.toml".to_string()));
+    }
+
+    #[test]
+    fn test_expand_glob_skips_directories() {
+        let temp = TempDir::new().unwrap();
+        let base = temp.path();
+
+        std::fs::create_dir_all(base.join("config/subdir")).unwrap();
+        std::fs::write(base.join("config/file.txt"), "content").unwrap();
+
+        let pairs = expand_glob("config/*", "./", base);
+        // Should only include the file, not the directory
+        assert_eq!(pairs.len(), 1);
+    }
+
+    #[test]
+    fn test_apply_copyfile_glob() {
+        let temp = TempDir::new().unwrap();
+        let workspace = temp.path().to_path_buf();
+
+        // Create repo directory with multiple files
+        let repo_dir = workspace.join("test-repo");
+        let prompts_dir = repo_dir.join("prompts");
+        std::fs::create_dir_all(&prompts_dir).unwrap();
+        std::fs::write(prompts_dir.join("opus.md"), "# Opus").unwrap();
+        std::fs::write(prompts_dir.join("atlas.md"), "# Atlas").unwrap();
+
+        let copyfiles = vec![CopyFileConfig {
+            src: "prompts/*.md".to_string(),
+            dest: ".gitgrip/prompts/".to_string(),
+        }];
+
+        let manifest = create_test_manifest(Some(copyfiles), None);
+        let result = apply_links(&workspace, &manifest, true);
+        assert!(result.is_ok());
+
+        // Verify both files were copied
+        assert!(workspace.join(".gitgrip/prompts/opus.md").exists());
+        assert!(workspace.join(".gitgrip/prompts/atlas.md").exists());
+        assert_eq!(
+            std::fs::read_to_string(workspace.join(".gitgrip/prompts/opus.md")).unwrap(),
+            "# Opus"
+        );
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn test_apply_linkfile_glob() {
+        let temp = TempDir::new().unwrap();
+        let workspace = temp.path().to_path_buf();
+
+        let repo_dir = workspace.join("test-repo");
+        let prompts_dir = repo_dir.join("prompts");
+        std::fs::create_dir_all(&prompts_dir).unwrap();
+        std::fs::write(prompts_dir.join("opus.md"), "# Opus").unwrap();
+        std::fs::write(prompts_dir.join("atlas.md"), "# Atlas").unwrap();
+
+        let linkfiles = vec![LinkFileConfig {
+            src: "prompts/*.md".to_string(),
+            dest: ".gitgrip/prompts/".to_string(),
+        }];
+
+        let manifest = create_test_manifest(None, Some(linkfiles));
+        let result = apply_links(&workspace, &manifest, true);
+        assert!(result.is_ok());
+
+        // Verify symlinks were created
+        let opus_dest = workspace.join(".gitgrip/prompts/opus.md");
+        let atlas_dest = workspace.join(".gitgrip/prompts/atlas.md");
+        assert!(opus_dest.exists());
+        assert!(opus_dest.is_symlink());
+        assert!(atlas_dest.exists());
+        assert!(atlas_dest.is_symlink());
+    }
+
     #[test]
     #[cfg(unix)]
     fn test_linkfile_replaces_existing_file() {
diff --git a/src/cli/commands/migrate.rs b/src/cli/commands/migrate.rs
index bb7dbd9c..09448f46 100644
--- a/src/cli/commands/migrate.rs
+++ b/src/cli/commands/migrate.rs
@@ -99,19 +99,9 @@ pub async fn run_migrate_from_repos(
         Vec::new()
     };
 
-    let premium = if interactive {
-        let theme = ColorfulTheme::default();
-        Confirm::with_theme(&theme)
-            .with_prompt("Enable premium features (persistent agents, team sharing)?")
-            .default(false)
-            .interact()?
-    } else {
-        false
-    };
-
     // Generate all files
     let manifest_yaml = generate_manifest_yaml(&parsed_repos, org_str, prefix_str);
-    let claude_md = generate_claude_md(&parsed_repos, prefix_str, &agents, premium);
+    let claude_md = generate_claude_md(&parsed_repos, prefix_str, &agents);
     let agents_toml = generate_agents_toml(prefix_str, &agents);
     let prompts: Vec<(String, String)> = agents
         .iter()
@@ -157,7 +147,6 @@ pub async fn run_migrate_from_repos(
             "target_dir": target_dir.display().to_string(),
             "repos": repos,
             "agents": agents.iter().map(|a| &a.name).collect::<Vec<_>>(),
-            "premium": premium,
             "manifest": ".gitgrip/spaces/main/gripspace.yml",
             "config": "config/",
         });
@@ -277,12 +266,7 @@ fn generate_manifest_yaml(repos: &[(String, String)], org: &str, prefix: &str) -
 }
 
 /// Generate CLAUDE.md with repo table and agent context.
-fn generate_claude_md(
-    repos: &[(String, String)],
-    prefix: &str,
-    agents: &[AgentSpec],
-    premium: bool,
-) -> String {
+fn generate_claude_md(repos: &[(String, String)], prefix: &str, agents: &[AgentSpec]) -> String {
     let mut md = String::new();
     md.push_str(&format!("# {}\n\n", prefix));
     md.push_str("Multi-repo workspace managed by **gitgrip** (`gr`). Always use `gr` — never raw `git` or `gh`.\n\n");
@@ -317,16 +301,6 @@ fn generate_claude_md(
     md.push_str("gr pr merge              # Merge linked PRs\n");
     md.push_str("```\n");
 
-    if premium {
-        md.push_str("\n## Premium Features\n\n");
-        md.push_str("This workspace has premium features enabled:\n");
-        md.push_str("- `recall_identity` — persistent agent identity\n");
-        md.push_str("- `recall_career` — cross-project career memory\n");
-        md.push_str("- `recall_promote` — share knowledge across team\n");
-        md.push_str("- `recall_approve` — approve promoted knowledge\n\n");
-        md.push_str("Use `recall_promote` after learning something reusable across projects.\n");
-    }
-
     md
 }
 
@@ -1068,12 +1042,12 @@ mod tests {
             model: "claude-opus-4-6".to_string(),
             tool: "claude".to_string(),
         }];
-        let md = generate_claude_md(&repos, "myproject", &agents, true);
+        let md = generate_claude_md(&repos, "myproject", &agents);
         assert!(md.contains("# myproject"));
         assert!(md.contains("| **myrepo**"));
         assert!(md.contains("| **atlas**"));
-        assert!(md.contains("Premium Features"));
-        assert!(md.contains("recall_identity"));
+        assert!(!md.contains("Premium Features"));
+        assert!(!md.contains("recall_identity"));
     }
 
     #[test]
diff --git a/src/cli/commands/release.rs b/src/cli/commands/release.rs
index 9ac53267..76f147ee 100644
--- a/src/cli/commands/release.rs
+++ b/src/cli/commands/release.rs
@@ -1160,7 +1160,7 @@ version = "0.2.0"
             clone_strategy: crate::core::manifest::CloneStrategy::Clone,
         }];
 
-        let files = detect_version_files(&dir.path().to_path_buf(), &repos);
+        let files = detect_version_files(dir.path(), &repos);
         assert_eq!(files.len(), 1);
         assert_eq!(files[0].0, "my-repo");
         assert!(files[0].1.ends_with("Cargo.toml"));
@@ -1193,7 +1193,7 @@ version = "0.2.0"
             clone_strategy: crate::core::manifest::CloneStrategy::Clone,
         }];
 
-        let files = detect_version_files(&dir.path().to_path_buf(), &repos);
+        let files = detect_version_files(dir.path(), &repos);
         assert!(files.is_empty());
     }
 }
diff --git a/src/cli/commands/repo.rs b/src/cli/commands/repo.rs
index ecec6753..db59e0f6 100644
--- a/src/cli/commands/repo.rs
+++ b/src/cli/commands/repo.rs
@@ -288,7 +288,6 @@ mod tests {
 
 #[cfg(test)]
 mod yaml_insertion_tests {
-    use super::*;
 
     /// Helper function to extract the insertion logic for testing
     fn test_insert_yaml(content: &str, new_entry: &str) -> String {
diff --git a/src/cli/commands/spawn.rs b/src/cli/commands/spawn.rs
index 3885c788..d0655a85 100644
--- a/src/cli/commands/spawn.rs
+++ b/src/cli/commands/spawn.rs
@@ -852,24 +852,83 @@ pub fn run_spawn_dashboard(_quiet: bool) -> anyhow::Result<()> {
         .args(["new-window", "-t", session, "-n", "dashboard"])
         .status()?;
 
-    // Build capture-loop script for each agent pane
+    // Build capture-loop script for each agent pane.
+    // Uses ANSI cursor-home + clear-to-end instead of `clear` so tmux
+    // scrollback is preserved and copy-mode (prefix+[) works for scrolling.
     let capture_script = |agent: &str| -> String {
         let target = format!("{}:{}", session, agent);
         format!(
-            "while true; do clear; echo '═══ {} ═══'; tmux capture-pane -t {} -p -S -25 2>/dev/null || echo '(not running)'; sleep 1; done",
+            "while true; do printf '\\033[H\\033[J'; echo '═══ {} ═══'; tmux capture-pane -t {} -p -S -40 2>/dev/null || echo '(not running)'; sleep 1; done",
             agent, target
         )
     };
 
-    // Build the #dev input loop using gr channel
+    // Build the #dev input loop with /send, /focus, /back, /zoom commands.
     let gr_path = std::env::current_exe()
         .unwrap_or_else(|_| "gr".into())
         .display()
         .to_string();
+
+    // Detect which agents use codex (need double-Enter when sending)
+    let codex_agents: Vec<&str> = names
+        .iter()
+        .filter(|n| {
+            config
+                .agents
+                .get(n.as_str())
+                .map(|a| a.tool == "codex")
+                .unwrap_or(false)
+        })
+        .map(|s| s.as_str())
+        .collect();
+    let codex_case = codex_agents
+        .iter()
+        .map(|a| format!("{})", a))
+        .collect::<Vec<_>>()
+        .join("|");
+
     let input_script = format!(
-        "cd {} && while IFS= read -rp $'\\033[36m#dev>\\033[0m ' msg; do [ -n \"$msg\" ] && {} channel post \"$msg\"; done",
-        workspace_root.display(),
-        gr_path
+        r#"cd {workspace} && echo '  Commands: /send <agent> <msg> | /focus <agent> | /back | /zoom | /help'
+while IFS= read -rp $'\033[36m#dev>\033[0m ' msg; do
+  case "$msg" in
+    /send\ *)
+      _rest="${{msg#/send }}"
+      _agent="${{_rest%% *}}"
+      _text="${{_rest#* }}"
+      tmux send-keys -t "{session}:$_agent" "$_text" Enter
+      case "$_agent" in {codex_case} sleep 0.3; tmux send-keys -t "{session}:$_agent" Enter ;; esac
+      echo "  -> sent to $_agent"
+      ;;
+    /focus\ *)
+      _agent="${{msg#/focus }}"
+      tmux select-window -t "{session}:$_agent" 2>/dev/null || echo "  agent '$_agent' not found"
+      ;;
+    /back)
+      tmux select-window -t "{session}:dashboard"
+      ;;
+    /zoom)
+      tmux resize-pane -Z
+      ;;
+    /help)
+      echo '  /send <agent> <msg>  — send message to agent (auto double-Enter for codex)'
+      echo '  /focus <agent>       — switch to agent window (full screen, interactive)'
+      echo '  /back                — return to dashboard'
+      echo '  /zoom                — toggle fullscreen on current pane'
+      echo '  <text>               — post to #dev channel'
+      ;;
+    *)
+      [ -n "$msg" ] && {gr} channel post "$msg"
+      ;;
+  esac
+done"#,
+        workspace = workspace_root.display(),
+        session = session,
+        codex_case = if codex_case.is_empty() {
+            "____never_match____)".to_string()
+        } else {
+            codex_case
+        },
+        gr = gr_path,
     );
 
     // Helper: get the active pane ID after a split or window creation.
@@ -949,7 +1008,7 @@ pub fn run_spawn_dashboard(_quiet: bool) -> anyhow::Result<()> {
 
     // Bottom input pane — split the full width at the bottom
     Command::new("tmux")
-        .args(["split-window", "-v", "-l", "3", "-t", &dashboard_target])
+        .args(["split-window", "-v", "-l", "6", "-t", &dashboard_target])
         .status()?;
 
     // Get the input pane ID (the newly created pane after the last split)
@@ -965,7 +1024,7 @@ pub fn run_spawn_dashboard(_quiet: bool) -> anyhow::Result<()> {
         .status()?;
 
     // Attach to the session (select dashboard window first)
-    Output::info("Dashboard opened. Ctrl-b d to detach.");
+    Output::info("Dashboard opened. /help for commands, Ctrl-b [ to scroll, Ctrl-b d to detach.");
 
     Command::new("tmux")
         .args(["select-window", "-t", &dashboard_target])
diff --git a/src/cli/commands/tree.rs b/src/cli/commands/tree.rs
index e53f0f95..bac58717 100644
--- a/src/cli/commands/tree.rs
+++ b/src/cli/commands/tree.rs
@@ -1075,7 +1075,7 @@ fn stash_pop_repo(repo_path: &Path) -> anyhow::Result<()> {
 
 #[cfg(test)]
 mod tests {
-    use super::*;
+
     use tempfile::TempDir;
 
     #[test]
diff --git a/src/cli/dispatch.rs b/src/cli/dispatch.rs
index b18bb3fb..97e269c3 100644
--- a/src/cli/dispatch.rs
+++ b/src/cli/dispatch.rs
@@ -93,30 +93,72 @@ pub async fn dispatch_command(
         }
         Some(Commands::Checkout {
             name,
+            extra,
             create,
             base,
             repo,
             group,
         }) => {
             let ctx = load_workspace_context(quiet, verbose, json)?;
-            let branch = if base {
-                let config = crate::core::griptree::GriptreeConfig::load_from_workspace(
+
+            if matches!(name.as_deref(), Some("add")) {
+                // `add` is reserved for checkout materialization, not branch switching.
+                if create || base {
+                    anyhow::bail!("--create and --base are not valid with 'add'");
+                }
+                if extra.len() > 1 {
+                    anyhow::bail!("unexpected extra arguments after checkout name");
+                }
+                let checkout_name = extra.first().ok_or_else(|| {
+                    anyhow::anyhow!("Checkout name is required: gr checkout add <name>")
+                })?;
+
+                crate::cli::commands::checkout::run_checkout_add(
+                    &ctx.workspace_root,
+                    &ctx.manifest,
+                    checkout_name,
+                    repo.as_deref(),
+                    group.as_deref(),
+                )?;
+            } else if matches!(name.as_deref(), Some("list")) {
+                if create || base || !extra.is_empty() {
+                    anyhow::bail!("`gr checkout list` does not accept extra arguments");
+                }
+                crate::cli::commands::checkout::run_checkout_list(&ctx.workspace_root)?;
+            } else if matches!(name.as_deref(), Some("remove")) {
+                if create || base {
+                    anyhow::bail!("--create and --base are not valid with 'remove'");
+                }
+                if extra.len() > 1 {
+                    anyhow::bail!("unexpected extra arguments after checkout name");
+                }
+                let checkout_name = extra.first().ok_or_else(|| {
+                    anyhow::anyhow!("Checkout name is required: gr checkout remove <name>")
+                })?;
+                crate::cli::commands::checkout::run_checkout_remove(
                     &ctx.workspace_root,
-                )?
-                .ok_or_else(|| anyhow::anyhow!("Not in a griptree workspace"))?;
-                config.branch
+                    checkout_name,
+                )?;
             } else {
-                name.ok_or_else(|| anyhow::anyhow!("Branch name is required"))?
-            };
+                let branch = if base {
+                    let config = crate::core::griptree::GriptreeConfig::load_from_workspace(
+                        &ctx.workspace_root,
+                    )?
+                    .ok_or_else(|| anyhow::anyhow!("Not in a griptree workspace"))?;
+                    config.branch
+                } else {
+                    name.ok_or_else(|| anyhow::anyhow!("Branch name is required"))?
+                };
 
-            crate::cli::commands::checkout::run_checkout(
-                &ctx.workspace_root,
-                &ctx.manifest,
-                &branch,
-                create,
-                repo.as_deref(),
-                group.as_deref(),
-            )?;
+                crate::cli::commands::checkout::run_checkout(
+                    &ctx.workspace_root,
+                    &ctx.manifest,
+                    &branch,
+                    create,
+                    repo.as_deref(),
+                    group.as_deref(),
+                )?;
+            }
         }
         Some(Commands::Add { files, repo, group }) => {
             let ctx = load_workspace_context(quiet, verbose, json)?;
diff --git a/src/core/griptree.rs b/src/core/griptree.rs
index 7dbfc91b..28671f5a 100644
--- a/src/core/griptree.rs
+++ b/src/core/griptree.rs
@@ -355,7 +355,7 @@ mod tests {
     #[test]
     fn test_load_from_workspace_none_when_missing() {
         let temp = tempfile::TempDir::new().unwrap();
-        let result = GriptreeConfig::load_from_workspace(&temp.path().to_path_buf()).unwrap();
+        let result = GriptreeConfig::load_from_workspace(temp.path()).unwrap();
         assert!(result.is_none());
     }
 
@@ -369,7 +369,7 @@ mod tests {
         let config_path = gitgrip_dir.join("griptree.json");
         config.save(&config_path).unwrap();
 
-        let loaded = GriptreeConfig::load_from_workspace(&temp.path().to_path_buf())
+        let loaded = GriptreeConfig::load_from_workspace(temp.path())
             .unwrap()
             .expect("should find config");
         assert_eq!(loaded.branch, "feat/ws");
diff --git a/src/core/repo.rs b/src/core/repo.rs
index 950b3a58..f8bc8880 100644
--- a/src/core/repo.rs
+++ b/src/core/repo.rs
@@ -431,6 +431,22 @@ mod tests {
         assert_eq!(parsed.repo, "test-repo");
     }
 
+    #[test]
+    fn test_parse_github_org_ssh() {
+        // Regression test for grip#429: org URLs must extract owner correctly
+        let parsed = parse_git_url("git@github.com:synapt-dev/grip.git").unwrap();
+        assert_eq!(parsed.owner, "synapt-dev");
+        assert_eq!(parsed.repo, "grip");
+    }
+
+    #[test]
+    fn test_parse_github_org_https() {
+        // Regression test for grip#429: org URLs must extract owner correctly
+        let parsed = parse_git_url("https://github.com/synapt-dev/recall.git").unwrap();
+        assert_eq!(parsed.owner, "synapt-dev");
+        assert_eq!(parsed.repo, "recall");
+    }
+
     #[test]
     fn test_detect_github() {
         assert_eq!(
@@ -664,13 +680,7 @@ mod tests {
         };
 
         let filter = vec!["app".to_string()];
-        let result = filter_repos(
-            &manifest,
-            &temp.path().to_path_buf(),
-            Some(&filter),
-            None,
-            false,
-        );
+        let result = filter_repos(&manifest, temp.path(), Some(&filter), None, false);
         assert_eq!(result.len(), 1);
         assert_eq!(result[0].name, "app");
     }
@@ -732,12 +742,12 @@ mod tests {
             workspace: None,
         };
 
-        let result = filter_repos(&manifest, &temp.path().to_path_buf(), None, None, false);
+        let result = filter_repos(&manifest, temp.path(), None, None, false);
         assert_eq!(result.len(), 1);
         assert_eq!(result[0].name, "normal");
 
         // With include_reference = true
-        let result = filter_repos(&manifest, &temp.path().to_path_buf(), None, None, true);
+        let result = filter_repos(&manifest, temp.path(), None, None, true);
         assert_eq!(result.len(), 2);
     }
 
@@ -799,13 +809,7 @@ mod tests {
         };
 
         let groups = vec!["web".to_string()];
-        let result = filter_repos(
-            &manifest,
-            &temp.path().to_path_buf(),
-            None,
-            Some(&groups),
-            false,
-        );
+        let result = filter_repos(&manifest, temp.path(), None, Some(&groups), false);
         assert_eq!(result.len(), 1);
         assert_eq!(result[0].name, "frontend");
     }
@@ -835,9 +839,7 @@ mod tests {
             clone_strategy: None,
         };
         let settings = ManifestSettings::default();
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.revision, "develop");
 
         // repo omits revision, inherits from settings
@@ -861,16 +863,12 @@ mod tests {
             revision: Some("master".to_string()),
             ..Default::default()
         };
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.revision, "master");
 
         // both omit → falls back to "main"
         let settings = ManifestSettings::default();
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.revision, "main");
     }
 
@@ -899,14 +897,8 @@ mod tests {
 
         // No target → falls back to revision
         let settings = ManifestSettings::default();
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.target, "main");
         assert_eq!(info.target_branch(), "main");
         assert_eq!(info.sync_ref(), "origin/main");
@@ -916,14 +908,8 @@ mod tests {
             target: Some("develop".to_string()),
             ..Default::default()
         };
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.target, "develop");
         assert_eq!(info.target_branch(), "develop");
 
@@ -936,9 +922,7 @@ mod tests {
             target: Some("develop".to_string()),
             ..Default::default()
         };
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.target, "staging");
         assert_eq!(info.target_branch(), "staging");
     }
@@ -968,14 +952,8 @@ mod tests {
 
         // Defaults to "origin"
         let settings = ManifestSettings::default();
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.sync_remote, "origin");
         assert_eq!(info.push_remote, "origin");
 
@@ -985,14 +963,8 @@ mod tests {
             push_remote: Some("myfork".to_string()),
             ..Default::default()
         };
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.sync_remote, "upstream");
         assert_eq!(info.push_remote, "myfork");
 
@@ -1002,9 +974,7 @@ mod tests {
             push_remote: Some("origin".to_string()),
             ..base_config.clone()
         };
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.sync_remote, "other");
         assert_eq!(info.push_remote, "origin");
     }
@@ -1041,14 +1011,8 @@ mod tests {
             clone_strategy: None,
         };
         let settings = ManifestSettings::default();
-        let info = RepoInfo::from_config(
-            "myrepo",
-            &config,
-            &temp.path().to_path_buf(),
-            &settings,
-            Some(&remotes),
-        )
-        .unwrap();
+        let info = RepoInfo::from_config("myrepo", &config, temp.path(), &settings, Some(&remotes))
+            .unwrap();
         assert_eq!(info.url, "git@github.com:org/myrepo.git");
     }
 
@@ -1144,7 +1108,7 @@ repos:
         let info = RepoInfo::from_config(
             "app",
             &manifest.repos["app"],
-            &temp.path().to_path_buf(),
+            temp.path(),
             &manifest.settings,
             manifest.remotes.as_ref(),
         )
diff --git a/src/core/workspace_cache.rs b/src/core/workspace_cache.rs
index c60cae8a..7c2ce6dd 100644
--- a/src/core/workspace_cache.rs
+++ b/src/core/workspace_cache.rs
@@ -1,45 +1,139 @@
 //! Workspace cache — bare-repo cache layer for manifest repos
 //!
-//! Each manifest repo gets a bare clone under `.grip/cache/<name>.git`.
-//! These caches serve as fast local references for creating agent workspaces
-//! and manual checkouts without sharing mutable .git state.
+//! Caches now live at a machine-level root by default (`~/.grip/cache/`),
+//! keyed by normalized remote URL rather than workspace-local repo name.
+//! This lets multiple workspaces reuse the same object store without sharing
+//! mutable `.git` state between checkouts.
 
 use anyhow::{Context, Result};
+use std::env;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
 use crate::util::log_cmd;
 
-/// Directory name under .grip/ where bare caches live.
+const CACHE_ENV_VAR: &str = "GRIP_CACHE_DIR";
+const GRIP_DIR: &str = ".grip";
 const CACHE_DIR: &str = "cache";
 
-/// Resolve the cache path for a repo: `<workspace_root>/.grip/cache/<name>.git`
-pub fn cache_path(workspace_root: &Path, repo_name: &str) -> PathBuf {
+fn home_dir() -> Result<PathBuf> {
+    if let Some(home) = env::var_os("HOME") {
+        return Ok(PathBuf::from(home));
+    }
+    if let Some(profile) = env::var_os("USERPROFILE") {
+        return Ok(PathBuf::from(profile));
+    }
+    anyhow::bail!("could not resolve home directory for global cache root")
+}
+
+/// Resolve the machine-level cache root.
+pub fn cache_root() -> Result<PathBuf> {
+    if let Some(override_dir) = env::var_os(CACHE_ENV_VAR) {
+        return Ok(PathBuf::from(override_dir));
+    }
+    Ok(home_dir()?.join(GRIP_DIR).join(CACHE_DIR))
+}
+
+fn legacy_cache_path(workspace_root: &Path, repo_name: &str) -> PathBuf {
     workspace_root
-        .join(".grip")
+        .join(GRIP_DIR)
         .join(CACHE_DIR)
         .join(format!("{}.git", repo_name))
 }
 
-/// Check whether a bare cache exists for the given repo.
-pub fn cache_exists(workspace_root: &Path, repo_name: &str) -> bool {
-    let path = cache_path(workspace_root, repo_name);
-    // A valid bare repo has a HEAD file
+fn normalize_git_url(url: &str) -> String {
+    let trimmed = url.trim().trim_end_matches('/').trim_end_matches(".git");
+
+    if !trimmed.contains("://") {
+        if let Some((user_host, path)) = trimmed.split_once(':') {
+            let host = user_host.rsplit('@').next().unwrap_or(user_host);
+            if !host.is_empty() && !path.is_empty() {
+                return format!(
+                    "{}:{}",
+                    host.to_ascii_lowercase(),
+                    path.trim_start_matches('/')
+                );
+            }
+        }
+    }
+
+    if let Some((_, rest)) = trimmed.split_once("://") {
+        if let Some((host_user, path)) = rest.split_once('/') {
+            let host = host_user.rsplit('@').next().unwrap_or(host_user);
+            if !host.is_empty() && !path.is_empty() {
+                return format!(
+                    "{}:{}",
+                    host.to_ascii_lowercase(),
+                    path.trim_start_matches('/')
+                );
+            }
+        }
+    }
+
+    trimmed.to_string()
+}
+
+/// Stable filesystem-safe cache key derived from a normalized remote URL.
+pub fn cache_key(url: &str) -> String {
+    let normalized = normalize_git_url(url);
+    let mut key = String::with_capacity(normalized.len());
+    let mut last_was_sep = false;
+
+    for ch in normalized.chars() {
+        if ch.is_ascii_alphanumeric() {
+            key.push(ch.to_ascii_lowercase());
+            last_was_sep = false;
+        } else if !last_was_sep {
+            key.push('_');
+            last_was_sep = true;
+        }
+    }
+
+    key.trim_matches('_').to_string()
+}
+
+/// Resolve the primary global cache path for a repo URL.
+pub fn cache_path(url: &str) -> Result<PathBuf> {
+    Ok(cache_root()?.join(format!("{}.git", cache_key(url))))
+}
+
+fn cache_is_valid(path: &Path) -> bool {
     path.join("HEAD").is_file()
 }
 
+/// Resolve the cache path to use, preferring the global cache but falling back
+/// to an existing legacy workspace-local cache.
+pub fn resolve_cache_path(workspace_root: &Path, repo_name: &str, url: &str) -> Result<PathBuf> {
+    let global = cache_path(url)?;
+    if cache_is_valid(&global) {
+        return Ok(global);
+    }
+
+    let legacy = legacy_cache_path(workspace_root, repo_name);
+    if cache_is_valid(&legacy) {
+        return Ok(legacy);
+    }
+
+    Ok(global)
+}
+
+/// Check whether a cache exists for the given repo.
+pub fn cache_exists(workspace_root: &Path, repo_name: &str, url: &str) -> Result<bool> {
+    Ok(cache_is_valid(&resolve_cache_path(
+        workspace_root,
+        repo_name,
+        url,
+    )?))
+}
+
 /// Bootstrap a bare cache by cloning from the canonical remote.
-///
-/// Creates `.grip/cache/<name>.git` as a bare clone of `url`.
-/// If the cache already exists, this is a no-op (use `update_cache` to fetch).
 pub fn bootstrap_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Result<()> {
-    let path = cache_path(workspace_root, repo_name);
-
-    if cache_exists(workspace_root, repo_name) {
+    let existing = resolve_cache_path(workspace_root, repo_name, url)?;
+    if cache_is_valid(&existing) {
         return Ok(());
     }
 
-    // Ensure parent directory exists
+    let path = cache_path(url)?;
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)
             .with_context(|| format!("creating cache directory: {}", parent.display()))?;
@@ -66,12 +160,10 @@ pub fn bootstrap_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Res
 }
 
 /// Fetch latest refs into an existing bare cache.
-///
-/// Runs `git fetch --all --prune` inside the bare repo to bring it up to date.
-pub fn update_cache(workspace_root: &Path, repo_name: &str) -> Result<()> {
-    let path = cache_path(workspace_root, repo_name);
+pub fn update_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Result<()> {
+    let path = resolve_cache_path(workspace_root, repo_name, url)?;
 
-    if !cache_exists(workspace_root, repo_name) {
+    if !cache_is_valid(&path) {
         anyhow::bail!("cache does not exist for {}: {}", repo_name, path.display());
     }
 
@@ -96,10 +188,14 @@ pub fn update_cache(workspace_root: &Path, repo_name: &str) -> Result<()> {
 }
 
 /// Get the remote URL stored in a bare cache.
-pub fn cache_remote_url(workspace_root: &Path, repo_name: &str) -> Result<Option<String>> {
-    let path = cache_path(workspace_root, repo_name);
+pub fn cache_remote_url(
+    workspace_root: &Path,
+    repo_name: &str,
+    url: &str,
+) -> Result<Option<String>> {
+    let path = resolve_cache_path(workspace_root, repo_name, url)?;
 
-    if !cache_exists(workspace_root, repo_name) {
+    if !cache_is_valid(&path) {
         return Ok(None);
     }
 
@@ -121,16 +217,13 @@ pub fn cache_remote_url(workspace_root: &Path, repo_name: &str) -> Result<Option
 }
 
 /// Bootstrap caches for all repos in a manifest.
-///
-/// Takes an iterator of (name, url) pairs. Skips repos that already have caches.
-/// Returns the count of newly bootstrapped caches.
 pub fn bootstrap_all<'a>(
     workspace_root: &Path,
     repos: impl Iterator<Item = (&'a str, &'a str)>,
 ) -> Result<usize> {
     let mut count = 0;
     for (name, url) in repos {
-        if !cache_exists(workspace_root, name) {
+        if !cache_exists(workspace_root, name, url)? {
             bootstrap_cache(workspace_root, name, url)?;
             count += 1;
         }
@@ -138,24 +231,15 @@ pub fn bootstrap_all<'a>(
     Ok(count)
 }
 
-/// Update all existing caches under `.grip/cache/`.
-///
-/// Returns the count of caches updated.
-pub fn update_all(workspace_root: &Path) -> Result<usize> {
-    let cache_dir = workspace_root.join(".grip").join(CACHE_DIR);
-    if !cache_dir.is_dir() {
-        return Ok(0);
-    }
-
+/// Update all caches for repos in the current manifest.
+pub fn update_all<'a>(
+    workspace_root: &Path,
+    repos: impl Iterator<Item = (&'a str, &'a str)>,
+) -> Result<usize> {
     let mut count = 0;
-    for entry in std::fs::read_dir(&cache_dir)? {
-        let entry = entry?;
-        let name = entry.file_name();
-        let name_str = name.to_string_lossy();
-        // Cache dirs are named <repo>.git
-        if name_str.ends_with(".git") && entry.path().join("HEAD").is_file() {
-            let repo_name = name_str.trim_end_matches(".git");
-            update_cache(workspace_root, repo_name)?;
+    for (name, url) in repos {
+        if cache_exists(workspace_root, name, url)? {
+            update_cache(workspace_root, name, url)?;
             count += 1;
         }
     }
@@ -163,8 +247,8 @@ pub fn update_all(workspace_root: &Path) -> Result<usize> {
 }
 
 /// Remove a single repo cache.
-pub fn remove_cache(workspace_root: &Path, repo_name: &str) -> Result<bool> {
-    let path = cache_path(workspace_root, repo_name);
+pub fn remove_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Result<bool> {
+    let path = resolve_cache_path(workspace_root, repo_name, url)?;
     if path.is_dir() {
         std::fs::remove_dir_all(&path)
             .with_context(|| format!("removing cache: {}", path.display()))?;
@@ -174,22 +258,41 @@ pub fn remove_cache(workspace_root: &Path, repo_name: &str) -> Result<bool> {
     }
 }
 
+#[cfg(test)]
+pub(crate) mod test_support {
+    use once_cell::sync::Lazy;
+    use std::sync::Mutex;
+
+    pub(crate) static ENV_LOCK: Lazy<Mutex<()>> = Lazy::new(|| Mutex::new(()));
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use std::fs;
 
-    /// Helper: create a temporary "remote" repo to clone from
+    fn with_cache_dir<T>(cache_dir: &Path, f: impl FnOnce() -> T) -> T {
+        let _guard = test_support::ENV_LOCK
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let previous = env::var_os(CACHE_ENV_VAR);
+        env::set_var(CACHE_ENV_VAR, cache_dir);
+        let result = f();
+        match previous {
+            Some(value) => env::set_var(CACHE_ENV_VAR, value),
+            None => env::remove_var(CACHE_ENV_VAR),
+        }
+        result
+    }
+
     fn create_test_remote(dir: &Path) -> PathBuf {
         let remote_path = dir.join("remote-repo.git");
-        // Init a bare repo to act as the remote
         Command::new("git")
             .args(["init", "--bare"])
             .arg(&remote_path)
             .output()
             .expect("git init --bare");
 
-        // Create a non-bare repo, add a commit, push to the bare repo
         let work_path = dir.join("work-repo");
         Command::new("git")
             .args(["init"])
@@ -227,7 +330,7 @@ mod tests {
             .args(["push", "origin", "main"])
             .current_dir(&work_path)
             .output()
-            .ok(); // might be master, not main
+            .ok();
         Command::new("git")
             .args(["push", "origin", "master"])
             .current_dir(&work_path)
@@ -238,16 +341,37 @@ mod tests {
     }
 
     #[test]
-    fn test_cache_path() {
-        let root = Path::new("/workspace");
-        let path = cache_path(root, "myrepo");
-        assert_eq!(path, PathBuf::from("/workspace/.grip/cache/myrepo.git"));
+    fn test_cache_key_normalizes_remote_url_forms() {
+        let ssh = cache_key("git@github.com:OpenAI/myrepo.git");
+        let https = cache_key("https://github.com/OpenAI/myrepo.git");
+        assert_eq!(ssh, "github_com_openai_myrepo");
+        assert_eq!(ssh, https);
+    }
+
+    #[test]
+    fn test_cache_path_uses_global_root() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let path = cache_path("git@github.com:OpenAI/myrepo.git").expect("cache path");
+            assert_eq!(path, cache_dir.join("github_com_openai_myrepo.git"));
+        });
     }
 
     #[test]
     fn test_cache_does_not_exist_initially() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        assert!(!cache_exists(tmp.path(), "nonexistent"));
+        let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
+        fs::create_dir_all(&workspace).expect("mkdir workspace");
+        with_cache_dir(&cache_dir, || {
+            assert!(!cache_exists(
+                &workspace,
+                "nonexistent",
+                "git@github.com:user/nonexistent.git"
+            )
+            .expect("cache exists"));
+        });
     }
 
     #[test]
@@ -255,18 +379,20 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        assert!(!cache_exists(&workspace, "testrepo"));
+        with_cache_dir(&cache_dir, || {
+            assert!(!cache_exists(&workspace, "testrepo", &url).expect("cache exists before"));
 
-        bootstrap_cache(&workspace, "testrepo", &url).expect("bootstrap");
-        assert!(cache_exists(&workspace, "testrepo"));
+            bootstrap_cache(&workspace, "testrepo", &url).expect("bootstrap");
+            assert!(cache_exists(&workspace, "testrepo", &url).expect("cache exists after"));
 
-        // Verify it's a bare repo
-        let cp = cache_path(&workspace, "testrepo");
-        assert!(cp.join("HEAD").is_file());
-        assert!(!cp.join(".git").exists()); // bare repos don't have .git subdir
+            let cp = cache_path(&url).expect("cache path");
+            assert!(cp.join("HEAD").is_file());
+            assert!(!cp.join(".git").exists());
+        });
     }
 
     #[test]
@@ -274,12 +400,15 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 1");
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 2"); // no-op
-        assert!(cache_exists(&workspace, "repo"));
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 1");
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 2");
+            assert!(cache_exists(&workspace, "repo", &url).expect("cache exists"));
+        });
     }
 
     #[test]
@@ -287,18 +416,26 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
-        update_cache(&workspace, "repo").expect("update");
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
+            update_cache(&workspace, "repo", &url).expect("update");
+        });
     }
 
     #[test]
     fn test_update_nonexistent_fails() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let result = update_cache(tmp.path(), "nope");
-        assert!(result.is_err());
+        let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
+        fs::create_dir_all(&workspace).expect("mkdir workspace");
+        with_cache_dir(&cache_dir, || {
+            let result = update_cache(&workspace, "nope", "git@github.com:user/nope.git");
+            assert!(result.is_err());
+        });
     }
 
     #[test]
@@ -306,15 +443,18 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
-
-        let stored_url = cache_remote_url(&workspace, "repo")
-            .expect("get url")
-            .expect("has url");
-        assert_eq!(stored_url, url);
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
+
+            let stored_url = cache_remote_url(&workspace, "repo", &url)
+                .expect("get url")
+                .expect("has url");
+            assert_eq!(stored_url, url);
+        });
     }
 
     #[test]
@@ -322,22 +462,31 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
-        assert!(cache_exists(&workspace, "repo"));
-
-        let removed = remove_cache(&workspace, "repo").expect("remove");
-        assert!(removed);
-        assert!(!cache_exists(&workspace, "repo"));
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
+            assert!(cache_exists(&workspace, "repo", &url).expect("cache exists"));
+
+            let removed = remove_cache(&workspace, "repo", &url).expect("remove");
+            assert!(removed);
+            assert!(!cache_exists(&workspace, "repo", &url).expect("cache removed"));
+        });
     }
 
     #[test]
     fn test_remove_nonexistent_returns_false() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let removed = remove_cache(tmp.path(), "nope").expect("remove");
-        assert!(!removed);
+        let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
+        fs::create_dir_all(&workspace).expect("mkdir workspace");
+        with_cache_dir(&cache_dir, || {
+            let removed =
+                remove_cache(&workspace, "nope", "git@github.com:user/nope.git").expect("remove");
+            assert!(!removed);
+        });
     }
 
     #[test]
@@ -345,18 +494,33 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        let repos = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
-        let count = bootstrap_all(&workspace, repos.into_iter()).expect("bootstrap all");
-        assert_eq!(count, 2);
-        assert!(cache_exists(&workspace, "repo1"));
-        assert!(cache_exists(&workspace, "repo2"));
-
-        // Second call: no new bootstraps
-        let repos2 = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
-        let count2 = bootstrap_all(&workspace, repos2.into_iter()).expect("bootstrap all 2");
-        assert_eq!(count2, 0);
+        with_cache_dir(&cache_dir, || {
+            let repos = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
+            let count = bootstrap_all(&workspace, repos.into_iter()).expect("bootstrap all");
+            assert_eq!(count, 1);
+            assert!(cache_exists(&workspace, "repo1", &url).expect("repo1 cached"));
+            assert!(cache_exists(&workspace, "repo2", &url).expect("repo2 cached"));
+
+            let repos2 = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
+            let count2 = bootstrap_all(&workspace, repos2.into_iter()).expect("bootstrap all 2");
+            assert_eq!(count2, 0);
+        });
+    }
+
+    #[test]
+    fn test_resolve_cache_path_falls_back_to_legacy_workspace_cache() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let workspace = tmp.path().join("workspace");
+        let legacy = workspace.join(".grip/cache/repo.git");
+        fs::create_dir_all(&legacy).expect("mkdir legacy cache");
+        fs::write(legacy.join("HEAD"), "ref: refs/heads/main\n").expect("write head");
+
+        let resolved = resolve_cache_path(&workspace, "repo", "git@github.com:org/repo.git")
+            .expect("resolve path");
+        assert_eq!(resolved, legacy);
     }
 }
diff --git a/src/core/workspace_checkout.rs b/src/core/workspace_checkout.rs
index 1e31808b..cc7fe49b 100644
--- a/src/core/workspace_checkout.rs
+++ b/src/core/workspace_checkout.rs
@@ -69,8 +69,8 @@ pub fn materialize_repo(
             .with_context(|| format!("creating checkout dir: {}", parent.display()))?;
     }
 
-    let cache = workspace_cache::cache_path(workspace_root, repo_name);
-    let has_cache = workspace_cache::cache_exists(workspace_root, repo_name);
+    let cache = workspace_cache::resolve_cache_path(workspace_root, repo_name, repo_url)?;
+    let has_cache = workspace_cache::cache_exists(workspace_root, repo_name, repo_url)?;
 
     let mut cmd = Command::new("git");
     cmd.arg("clone");
@@ -200,8 +200,23 @@ pub fn remove_checkout(workspace_root: &Path, name: &str) -> Result<bool> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::core::workspace_cache::test_support;
     use std::fs;
 
+    fn with_cache_dir<T>(cache_dir: &Path, f: impl FnOnce() -> T) -> T {
+        let _guard = test_support::ENV_LOCK
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let previous = std::env::var_os("GRIP_CACHE_DIR");
+        std::env::set_var("GRIP_CACHE_DIR", cache_dir);
+        let result = f();
+        match previous {
+            Some(value) => std::env::set_var("GRIP_CACHE_DIR", value),
+            None => std::env::remove_var("GRIP_CACHE_DIR"),
+        }
+        result
+    }
+
     /// Helper: create a test remote repo and bootstrap its cache
     fn setup_cached_workspace(dir: &Path) -> (PathBuf, PathBuf) {
         let remote_path = dir.join("remote-repo.git");
@@ -279,111 +294,127 @@ mod tests {
     #[test]
     fn test_materialize_single_repo() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let target = materialize_repo(
-            &workspace,
-            "test-checkout",
-            "testrepo",
-            &url,
-            "testrepo",
-            None,
-        )
-        .expect("materialize");
-
-        assert!(target.join(".git").exists());
-        assert!(target.join("README.md").exists());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let target = materialize_repo(
+                &workspace,
+                "test-checkout",
+                "testrepo",
+                &url,
+                "testrepo",
+                None,
+            )
+            .expect("materialize");
+
+            assert!(target.join(".git").exists());
+            assert!(target.join("README.md").exists());
+        });
     }
 
     #[test]
     fn test_materialize_is_independent_clone() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let target = materialize_repo(
-            &workspace,
-            "independent",
-            "testrepo",
-            &url,
-            "testrepo",
-            None,
-        )
-        .expect("materialize");
-
-        // The clone has its own .git directory (not a worktree link)
-        assert!(target.join(".git").is_dir());
-        // Not a file pointing elsewhere (that would be a worktree)
-        assert!(!target.join(".git").is_file());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let target = materialize_repo(
+                &workspace,
+                "independent",
+                "testrepo",
+                &url,
+                "testrepo",
+                None,
+            )
+            .expect("materialize");
+
+            assert!(target.join(".git").is_dir());
+            assert!(!target.join(".git").is_file());
+        });
     }
 
     #[test]
     fn test_materialize_uses_cache_reference() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let target = materialize_repo(&workspace, "ref-test", "testrepo", &url, "testrepo", None)
-            .expect("materialize");
-
-        // Check alternates file exists (proves --reference was used)
-        let alternates = target.join(".git/objects/info/alternates");
-        assert!(alternates.is_file(), "alternates file should exist");
-        let content = fs::read_to_string(&alternates).expect("read alternates");
-        assert!(
-            content.contains("cache/testrepo.git"),
-            "alternates should reference the cache"
-        );
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let target =
+                materialize_repo(&workspace, "ref-test", "testrepo", &url, "testrepo", None)
+                    .expect("materialize");
+
+            let alternates = target.join(".git/objects/info/alternates");
+            assert!(alternates.is_file(), "alternates file should exist");
+            let content = fs::read_to_string(&alternates).expect("read alternates");
+            assert!(
+                content.contains(&workspace_cache::cache_key(&url)),
+                "alternates should reference the global cache path"
+            );
+        });
     }
 
     #[test]
     fn test_create_and_list_checkout() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
 
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
 
-        let info = create_checkout(&workspace, "feat-x", repos.into_iter(), None)
-            .expect("create checkout");
+            let info = create_checkout(&workspace, "feat-x", repos.into_iter(), None)
+                .expect("create checkout");
 
-        assert_eq!(info.name, "feat-x");
-        assert_eq!(info.repos.len(), 1);
-        assert!(checkout_exists(&workspace, "feat-x"));
+            assert_eq!(info.name, "feat-x");
+            assert_eq!(info.repos.len(), 1);
+            assert!(checkout_exists(&workspace, "feat-x"));
 
-        let all = list_checkouts(&workspace).expect("list");
-        assert_eq!(all.len(), 1);
-        assert_eq!(all[0].name, "feat-x");
+            let all = list_checkouts(&workspace).expect("list");
+            assert_eq!(all.len(), 1);
+            assert_eq!(all[0].name, "feat-x");
+        });
     }
 
     #[test]
     fn test_create_duplicate_fails() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
 
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
-        create_checkout(&workspace, "dup", repos.into_iter(), None).expect("first");
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            create_checkout(&workspace, "dup", repos.into_iter(), None).expect("first");
 
-        let repos2 = vec![("testrepo", url.as_str(), "testrepo")];
-        let result = create_checkout(&workspace, "dup", repos2.into_iter(), None);
-        assert!(result.is_err());
+            let repos2 = vec![("testrepo", url.as_str(), "testrepo")];
+            let result = create_checkout(&workspace, "dup", repos2.into_iter(), None);
+            assert!(result.is_err());
+        });
     }
 
     #[test]
     fn test_remove_checkout() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
-        create_checkout(&workspace, "removeme", repos.into_iter(), None).expect("create");
-
-        assert!(checkout_exists(&workspace, "removeme"));
-        let removed = remove_checkout(&workspace, "removeme").expect("remove");
-        assert!(removed);
-        assert!(!checkout_exists(&workspace, "removeme"));
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            create_checkout(&workspace, "removeme", repos.into_iter(), None).expect("create");
+
+            assert!(checkout_exists(&workspace, "removeme"));
+            let removed = remove_checkout(&workspace, "removeme").expect("remove");
+            assert!(removed);
+            assert!(!checkout_exists(&workspace, "removeme"));
+        });
     }
 
     #[test]
@@ -396,19 +427,20 @@ mod tests {
     #[test]
     fn test_cache_survives_checkout_removal() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
 
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
-        create_checkout(&workspace, "ephemeral", repos.into_iter(), None).expect("create");
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            create_checkout(&workspace, "ephemeral", repos.into_iter(), None).expect("create");
 
-        // Remove the checkout
-        remove_checkout(&workspace, "ephemeral").expect("remove");
+            remove_checkout(&workspace, "ephemeral").expect("remove");
 
-        // Cache must still exist — this is a first-class guarantee
-        assert!(
-            workspace_cache::cache_exists(&workspace, "testrepo"),
-            "cache must survive checkout deletion"
-        );
+            assert!(
+                workspace_cache::cache_exists(&workspace, "testrepo", &url).expect("cache exists"),
+                "cache must survive checkout deletion"
+            );
+        });
     }
 }
diff --git a/src/git/branch.rs b/src/git/branch.rs
index 36f8763d..31e00760 100644
--- a/src/git/branch.rs
+++ b/src/git/branch.rs
@@ -374,7 +374,7 @@ mod tests {
 
     #[test]
     fn test_create_and_checkout_branch() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         create_and_checkout_branch(&repo, "feature").unwrap();
 
@@ -384,7 +384,7 @@ mod tests {
 
     #[test]
     fn test_branch_exists() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         assert!(!branch_exists(&repo, "feature"));
 
@@ -394,7 +394,7 @@ mod tests {
 
     #[test]
     fn test_checkout_branch() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         // Create a feature branch
         create_and_checkout_branch(&repo, "feature").unwrap();
@@ -413,7 +413,7 @@ mod tests {
 
     #[test]
     fn test_list_local_branches() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         create_and_checkout_branch(&repo, "feature1").unwrap();
         create_and_checkout_branch(&repo, "feature2").unwrap();
diff --git a/src/git/remote.rs b/src/git/remote.rs
index 7dde7482..a2cae999 100644
--- a/src/git/remote.rs
+++ b/src/git/remote.rs
@@ -725,7 +725,7 @@ mod tests {
 
     #[test]
     fn test_set_remote_url() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         // Create new remote
         set_remote_url(&repo, "origin", "https://github.com/test/repo1.git").unwrap();
diff --git a/src/platform/rate_limit.rs b/src/platform/rate_limit.rs
index c9853d76..fb20bd07 100644
--- a/src/platform/rate_limit.rs
+++ b/src/platform/rate_limit.rs
@@ -238,7 +238,7 @@ mod tests {
         };
         let wait = info.wait_seconds().unwrap();
         // Should be approximately 120 seconds (allow 2s tolerance for test execution)
-        assert!(wait >= 118 && wait <= 122, "wait_seconds was {}", wait);
+        assert!((118..=122).contains(&wait), "wait_seconds was {}", wait);
     }
 
     #[test]
diff --git a/src/telemetry/metrics.rs b/src/telemetry/metrics.rs
index f8a50f61..5d423d94 100644
--- a/src/telemetry/metrics.rs
+++ b/src/telemetry/metrics.rs
@@ -399,7 +399,7 @@ mod tests {
 
         // p50 should be around 50 (rounding may cause slight differences)
         let p50 = hist.p50().unwrap().as_millis();
-        assert!(p50 >= 49 && p50 <= 51, "p50 was {p50}, expected ~50");
+        assert!((49..=51).contains(&p50), "p50 was {p50}, expected ~50");
         assert!(hist.p99().unwrap() >= Duration::from_millis(99));
     }
 
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index 4f8ac0f9..bc8dc413 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -32,84 +32,3641 @@ fn test_version() {
         .stdout(predicate::str::contains(env!("CARGO_PKG_VERSION")));
 }
 
-/// Test that `gr status` fails gracefully outside a workspace
 #[test]
-fn test_status_outside_workspace() {
+fn test_gr2_help() {
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("--help")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "gr2 is the clean-break gitgrip CLI for the new team-workspace, cache, and checkout model.",
+        ))
+        .stdout(predicate::str::contains("doctor"))
+        .stdout(predicate::str::contains("gr2"));
+}
+
+#[test]
+fn test_gr2_version() {
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("--version")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("gr2 0.1.0"));
+}
+
+#[test]
+fn test_gr2_doctor() {
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("doctor")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("gr2 bootstrap OK"));
+}
+
+#[test]
+fn test_gr2_init_scaffolds_team_workspace() {
     let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
 
-    let mut cmd = Command::cargo_bin("gr").unwrap();
-    cmd.current_dir(temp.path())
-        .arg("status")
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Initialized gr2 team workspace 'demo'",
+        ));
+
+    assert!(workspace_root.join(".grip").is_dir());
+    assert!(workspace_root.join("config").is_dir());
+    assert!(workspace_root.join("agents").is_dir());
+    assert!(workspace_root.join("repos").is_dir());
+
+    let workspace_toml =
+        std::fs::read_to_string(workspace_root.join(".grip/workspace.toml")).unwrap();
+    assert!(workspace_toml.contains("version = 2"));
+    assert!(workspace_toml.contains("name = \"demo\""));
+    assert!(workspace_toml.contains("layout = \"team-workspace\""));
+}
+
+#[test]
+fn test_gr2_init_rejects_existing_path() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+    std::fs::create_dir_all(&workspace_root).unwrap();
+
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("init")
+        .arg(&workspace_root)
         .assert()
         .failure()
-        .stderr(predicate::str::contains("Not in a gitgrip workspace"));
+        .stderr(predicate::str::contains("workspace path already exists"));
 }
 
-/// Test that `gr bench --list` works
 #[test]
-fn test_bench_list() {
-    let mut cmd = Command::cargo_bin("gr").unwrap();
-    cmd.arg("bench")
-        .arg("--list")
+fn test_gr2_team_add_registers_agent_workspace() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut team_add = Command::cargo_bin("gr2").unwrap();
+    team_add
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
         .assert()
         .success()
-        .stdout(predicate::str::contains("Available Benchmarks"));
+        .stdout(predicate::str::contains(
+            "Added gr2 agent workspace 'atlas'",
+        ));
+
+    let agent_toml =
+        std::fs::read_to_string(workspace_root.join("agents/atlas/agent.toml")).unwrap();
+    assert!(agent_toml.contains("name = \"atlas\""));
+    assert!(agent_toml.contains("kind = \"agent-workspace\""));
 }
 
-/// Test that `gr bench` runs benchmarks
 #[test]
-fn test_bench_run() {
-    let mut cmd = Command::cargo_bin("gr").unwrap();
-    cmd.arg("bench")
-        .arg("-n")
-        .arg("1")
+fn test_gr2_team_add_rejects_duplicate_agent() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr2").unwrap();
+    duplicate
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("agent 'atlas' already exists"));
+}
+
+#[test]
+fn test_gr2_team_add_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut team_add = Command::cargo_bin("gr2").unwrap();
+    team_add
+        .current_dir(temp.path())
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_team_list_shows_registered_agents() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add_atlas = Command::cargo_bin("gr2").unwrap();
+    add_atlas
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut add_opus = Command::cargo_bin("gr2").unwrap();
+    add_opus
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("opus")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("team")
+        .arg("list")
         .assert()
         .success()
-        .stdout(predicate::str::contains("Benchmark Results"));
+        .stdout(predicate::str::contains("Agent workspaces"))
+        .stdout(predicate::str::contains("- atlas"))
+        .stdout(predicate::str::contains("- opus"));
 }
 
-/// Test that `gr bench --json` outputs JSON
 #[test]
-fn test_bench_json() {
-    let mut cmd = Command::cargo_bin("gr").unwrap();
-    cmd.arg("bench")
-        .arg("-n")
-        .arg("1")
-        .arg("--json")
+fn test_gr2_team_list_reports_empty_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("team")
+        .arg("list")
         .assert()
         .success()
-        .stdout(predicate::str::starts_with("["));
+        .stdout(predicate::str::contains(
+            "No gr2 agent workspaces registered.",
+        ));
 }
 
 #[test]
-fn test_checkout_base_uses_griptree_config() {
-    let ws = WorkspaceBuilder::new()
-        .add_repo("app")
-        .add_repo("lib")
-        .build();
+fn test_gr2_team_list_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
 
-    git_helpers::create_branch(&ws.repo_path("app"), "feat/base");
-    git_helpers::checkout(&ws.repo_path("app"), "main");
-    git_helpers::create_branch(&ws.repo_path("lib"), "feat/base");
-    git_helpers::checkout(&ws.repo_path("lib"), "main");
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(temp.path())
+        .arg("team")
+        .arg("list")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
 
-    let mut config = GriptreeConfig::new("feat/base", &ws.workspace_root.to_string_lossy());
-    let config_path = ws.workspace_root.join(".gitgrip").join("griptree.json");
-    config.save(&config_path).unwrap();
+#[test]
+fn test_gr2_team_remove_deletes_registered_agent() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
 
-    let mut cmd = Command::cargo_bin("gr").unwrap();
-    cmd.current_dir(&ws.workspace_root)
-        .arg("checkout")
-        .arg("--base")
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
         .assert()
         .success();
 
-    assert_eq!(
-        git_helpers::current_branch(&ws.repo_path("app")),
-        "feat/base"
+    let agent_root = workspace_root.join("agents/atlas");
+    assert!(agent_root.join("agent.toml").exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Removed gr2 agent workspace 'atlas'",
+        ));
+
+    assert!(!agent_root.exists());
+}
+
+#[test]
+fn test_gr2_team_remove_rejects_missing_agent() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("agent 'atlas' not found"));
+}
+
+#[test]
+fn test_gr2_team_remove_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(temp.path())
+        .arg("team")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_add_registers_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Added gr2 repo 'app' -> https://github.com/synapt-dev/app.git",
+        ));
+
+    let repo_toml = std::fs::read_to_string(workspace_root.join("repos/app/repo.toml")).unwrap();
+    assert!(repo_toml.contains("name = \"app\""));
+    assert!(repo_toml.contains("url = \"https://github.com/synapt-dev/app.git\""));
+
+    let registry = std::fs::read_to_string(workspace_root.join(".grip/repos.toml")).unwrap();
+    assert!(registry.contains("[[repo]]"));
+    assert!(registry.contains("name = \"app\""));
+}
+
+#[test]
+fn test_gr2_repo_add_rejects_duplicate_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr2").unwrap();
+    duplicate
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("repo 'app' already exists"));
+}
+
+#[test]
+fn test_gr2_repo_add_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(temp.path())
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_list_shows_registered_repos() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add_app = Command::cargo_bin("gr2").unwrap();
+    add_app
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut add_docs = Command::cargo_bin("gr2").unwrap();
+    add_docs
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("docs")
+        .arg("https://github.com/synapt-dev/docs.git")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("repo")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Repos"))
+        .stdout(predicate::str::contains(
+            "- app -> https://github.com/synapt-dev/app.git",
+        ))
+        .stdout(predicate::str::contains(
+            "- docs -> https://github.com/synapt-dev/docs.git",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_list_reports_empty_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("repo")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("No gr2 repos registered."));
+}
+
+#[test]
+fn test_gr2_repo_list_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(temp.path())
+        .arg("repo")
+        .arg("list")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_status_reports_missing_unit_checkout_as_clone_missing() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+        toml_path(&bare)
     );
-    assert_eq!(
-        git_helpers::current_branch(&ws.repo_path("lib")),
-        "feat/base"
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), spec).unwrap();
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\nrepos = [\"app\"]\n",
+    )
+    .unwrap();
+
+    let mut status = Command::cargo_bin("gr2").unwrap();
+    status
+        .current_dir(&workspace_root)
+        .args(["repo", "status"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("RepoStatus"))
+        .stdout(predicate::str::contains("clone_missing"))
+        .stdout(predicate::str::contains("atlas"))
+        .stdout(predicate::str::contains("app"));
+}
+
+#[test]
+fn test_gr2_repo_status_reports_dirty_unit_repo_as_block_dirty() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), spec).unwrap();
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\nrepos = [\"app\"]\n",
+    )
+    .unwrap();
+
+    let clone_dest = workspace_root.join("agents/atlas/app");
+    let status = std::process::Command::new("git")
+        .arg("clone")
+        .arg(&bare)
+        .arg(&clone_dest)
+        .status()
+        .unwrap();
+    assert!(status.success());
+    std::fs::write(clone_dest.join("dirty.txt"), "local change").unwrap();
+
+    let mut repo_status = Command::cargo_bin("gr2").unwrap();
+    repo_status
+        .current_dir(&workspace_root)
+        .args(["repo", "status", "--unit", "atlas"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("block_dirty"))
+        .stdout(predicate::str::contains("working tree is dirty"));
+}
+
+#[test]
+fn test_gr2_repo_status_reports_shared_repo_behind_upstream_as_fast_forward() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+"#,
+        toml_path(&bare)
     );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), spec).unwrap();
+
+    let shared_repo = workspace_root.join("repos/app");
+    let status = std::process::Command::new("git")
+        .arg("clone")
+        .arg(&bare)
+        .arg(&shared_repo)
+        .status()
+        .unwrap();
+    assert!(status.success());
+
+    let staging = temp.path().join("staging");
+    let status = std::process::Command::new("git")
+        .arg("clone")
+        .arg(&bare)
+        .arg(&staging)
+        .status()
+        .unwrap();
+    assert!(status.success());
+    git_helpers::configure_identity(&staging);
+    git_helpers::commit_file(&staging, "later.txt", "upstream", "Add upstream");
+    let branch = git_helpers::current_branch(&staging);
+    git_helpers::push_branch(&staging, "origin", &branch);
+    git_helpers::fetch(&shared_repo, "origin", Some(&branch));
+
+    let mut repo_status = Command::cargo_bin("gr2").unwrap();
+    repo_status
+        .current_dir(&workspace_root)
+        .args(["repo", "status", "--repo", "app"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("fast_forward"))
+        .stdout(predicate::str::contains("shared"))
+        .stdout(predicate::str::contains("behind=1"));
+}
+
+#[test]
+fn test_gr2_repo_remove_deletes_registered_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let repo_root = workspace_root.join("repos/app");
+    assert!(repo_root.join("repo.toml").exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("remove")
+        .arg("app")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Removed gr2 repo 'app'"));
+
+    assert!(!repo_root.exists());
+    assert!(!workspace_root.join(".grip/repos.toml").exists());
+}
+
+#[test]
+fn test_gr2_repo_remove_rejects_missing_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("remove")
+        .arg("app")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("repo 'app' not found"));
+}
+
+#[test]
+fn test_gr2_repo_remove_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(temp.path())
+        .arg("repo")
+        .arg("remove")
+        .arg("app")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_unit_add_registers_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Added gr2 unit 'atlas'"));
+
+    let unit_toml = std::fs::read_to_string(workspace_root.join("agents/atlas/unit.toml")).unwrap();
+    assert!(unit_toml.contains("name = \"atlas\""));
+    assert!(unit_toml.contains("kind = \"unit\""));
+
+    let registry = std::fs::read_to_string(workspace_root.join(".grip/units.toml")).unwrap();
+    assert!(registry.contains("[[unit]]"));
+    assert!(registry.contains("name = \"atlas\""));
+}
+
+#[test]
+fn test_gr2_unit_add_rejects_duplicate_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr2").unwrap();
+    duplicate
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("unit 'atlas' already exists"));
+}
+
+#[test]
+fn test_gr2_unit_add_rejects_invalid_name() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut invalid = Command::cargo_bin("gr2").unwrap();
+    invalid
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas/dev")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "invalid unit name 'atlas/dev': use only ASCII letters, numbers, '_' or '-'",
+        ));
+}
+
+#[test]
+fn test_gr2_unit_list_shows_registered_units() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add_atlas = Command::cargo_bin("gr2").unwrap();
+    add_atlas
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut add_opus = Command::cargo_bin("gr2").unwrap();
+    add_opus
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("opus")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("unit")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Units"))
+        .stdout(predicate::str::contains("- atlas"))
+        .stdout(predicate::str::contains("- opus"));
+}
+
+#[test]
+fn test_gr2_unit_list_reports_empty_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("unit")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("No gr2 units registered."));
+}
+
+#[test]
+fn test_gr2_unit_remove_deletes_registered_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let unit_root = workspace_root.join("agents/atlas");
+    assert!(unit_root.join("unit.toml").exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Removed gr2 unit 'atlas'"));
+
+    assert!(!unit_root.exists());
+    assert!(!workspace_root.join(".grip/units.toml").exists());
+}
+
+#[test]
+fn test_gr2_unit_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(temp.path())
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_spec_show_round_trips_workspace_spec() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("schema_version = 1"))
+        .stdout(predicate::str::contains("workspace_name = \"demo\""))
+        .stdout(predicate::str::contains("name = \"app\""))
+        .stdout(predicate::str::contains("name = \"atlas\""));
+
+    let spec = std::fs::read_to_string(workspace_root.join(".grip/workspace_spec.toml")).unwrap();
+    assert!(spec.contains("schema_version = 1"));
+    assert!(spec.contains("workspace_name = \"demo\""));
+    assert!(spec.contains("path = \"repos/app\""));
+    assert!(spec.contains("path = \"agents/atlas\""));
+
+    let mut validate = Command::cargo_bin("gr2").unwrap();
+    validate
+        .current_dir(&workspace_root)
+        .arg("spec")
+        .arg("validate")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Workspace spec is valid"));
+}
+
+#[test]
+fn test_gr2_spec_validate_detects_missing_repo_metadata() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    std::fs::remove_file(workspace_root.join("repos/app/repo.toml")).unwrap();
+
+    let mut validate = Command::cargo_bin("gr2").unwrap();
+    validate
+        .current_dir(&workspace_root)
+        .arg("spec")
+        .arg("validate")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "workspace spec repo 'app' is missing repo metadata",
+        ));
+}
+
+#[test]
+fn test_gr2_spec_validate_detects_conflicting_unit_names() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    let spec_path = workspace_root.join(".grip/workspace_spec.toml");
+    let spec = std::fs::read_to_string(&spec_path).unwrap();
+    let conflicting = format!(
+        "{}\n[[units]]\nname = \"atlas\"\npath = \"agents/atlas-copy\"\nrepos = []\n",
+        spec.trim_end()
+    );
+    std::fs::write(&spec_path, conflicting).unwrap();
+
+    let mut validate = Command::cargo_bin("gr2").unwrap();
+    validate
+        .current_dir(&workspace_root)
+        .arg("spec")
+        .arg("validate")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "workspace spec contains duplicate unit 'atlas'",
+        ));
+}
+
+#[test]
+fn test_gr2_plan_empty_workspace_produces_clone_all_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://github.com/synapt-dev/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+    std::fs::create_dir_all(workspace_root.join("repos/app")).unwrap();
+    std::fs::write(
+        workspace_root.join("repos/app/repo.toml"),
+        "name = \"app\"\nurl = \"https://github.com/synapt-dev/app.git\"\n",
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("ExecutionPlan"))
+        .stdout(predicate::str::contains("atlas\tclone"))
+        .stdout(predicate::str::contains("apollo\tclone"));
+}
+
+#[test]
+fn test_gr2_plan_fully_materialized_workspace_produces_noop_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"));
+}
+
+#[test]
+fn test_gr2_plan_does_not_flag_repo_attachment_presence_as_drift() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Use a local bare repo so the checkout can actually exist
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    // Simulate a fully-converged unit: clone the repo into the unit directory
+    let unit_repo_dir = workspace_root.join("agents/atlas/app");
+    std::process::Command::new("git")
+        .args(["clone"])
+        .arg(&bare)
+        .arg(&unit_repo_dir)
+        .output()
+        .unwrap();
+
+    let spec = format!(
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"))
+        .stdout(predicate::str::contains("configure").not());
+}
+
+#[test]
+fn test_gr2_plan_missing_unit_produces_single_clone_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    std::fs::create_dir_all(workspace_root.join("agents/apollo")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/apollo/unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec_path = workspace_root.join(".grip/workspace_spec.toml");
+    let spec = std::fs::read_to_string(&spec_path).unwrap();
+    let with_apollo = format!(
+        "{}\n[[units]]\nname = \"apollo\"\npath = \"agents/apollo\"\nrepos = []\n",
+        spec.trim_end()
+    );
+    std::fs::write(&spec_path, with_apollo).unwrap();
+    std::fs::remove_file(workspace_root.join("agents/apollo/unit.toml")).unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("apollo\tclone"))
+        .stdout(predicate::str::contains("clone unit 'apollo'"));
+}
+
+#[test]
+fn test_gr2_plan_rejects_invalid_unit_repo_reference() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://github.com/synapt-dev/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["missing"]
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "unit 'atlas' references missing repo 'missing'",
+        ));
+}
+
+#[test]
+fn test_gr2_plan_reports_when_it_generates_a_missing_workspace_spec() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let spec_path = workspace_root.join(".grip/workspace_spec.toml");
+    assert!(!spec_path.exists());
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Generated workspace spec at"))
+        .stdout(predicate::str::contains("no changes required"));
+
+    assert!(spec_path.exists());
+}
+
+#[test]
+fn test_gr2_apply_materializes_missing_units_from_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a local bare repo to use as the "remote"
+    let bare_repo = temp.path().join("app-bare.git");
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare_repo)
+        .output()
+        .unwrap();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+        toml_path(&bare_repo)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+    std::fs::create_dir_all(workspace_root.join("repos/app")).unwrap();
+    std::fs::write(
+        workspace_root.join("repos/app/repo.toml"),
+        format!("name = \"app\"\nurl = \"{}\"\n", toml_path(&bare_repo)),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Applied execution plan"))
+        .stdout(predicate::str::contains("cloned unit 'atlas'"));
+
+    let unit_toml = std::fs::read_to_string(workspace_root.join("agents/atlas/unit.toml")).unwrap();
+    assert!(unit_toml.contains("name = \"atlas\""));
+    assert!(unit_toml.contains("kind = \"unit\""));
+    assert!(unit_toml.contains("repos = [\"app\"]"));
+
+    // Repo should be cloned into the unit workspace
+    assert!(workspace_root.join("agents/atlas/app/.git").exists());
+}
+
+#[test]
+fn test_gr2_apply_requires_yes_for_large_plans() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+
+[[units]]
+name = "sentinel"
+path = "agents/sentinel"
+repos = []
+
+[[units]]
+name = "opus"
+path = "agents/opus"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "plan contains more than 3 operations; rerun with --yes to apply it",
+        ));
+
+    assert!(!workspace_root.join("agents/atlas/unit.toml").exists());
+    assert!(!workspace_root.join("agents/apollo/unit.toml").exists());
+}
+
+#[test]
+fn test_checkout_help_mentions_add_mode() {
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.arg("checkout")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Checkout a branch across repos or manage independent child checkouts",
+        ))
+        .stdout(predicate::str::contains(
+            "Branch name, or `add`/`list`/`remove` for child checkout lifecycle",
+        ))
+        .stdout(predicate::str::contains("gr checkout add sandbox"))
+        .stdout(predicate::str::contains(
+            "gr checkout add docs-only --group docs",
+        ))
+        .stdout(predicate::str::contains("gr checkout list"))
+        .stdout(predicate::str::contains("gr checkout remove sandbox"));
+}
+
+/// Test that `gr status` fails gracefully outside a workspace
+#[test]
+fn test_status_outside_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(temp.path())
+        .arg("status")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("Not in a gitgrip workspace"));
+}
+
+/// Test that `gr bench --list` works
+#[test]
+fn test_bench_list() {
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.arg("bench")
+        .arg("--list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Available Benchmarks"));
+}
+
+/// Test that `gr bench` runs benchmarks
+#[test]
+fn test_bench_run() {
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.arg("bench")
+        .arg("-n")
+        .arg("1")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Benchmark Results"));
+}
+
+/// Test that `gr bench --json` outputs JSON
+#[test]
+fn test_bench_json() {
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.arg("bench")
+        .arg("-n")
+        .arg("1")
+        .arg("--json")
+        .assert()
+        .success()
+        .stdout(predicate::str::starts_with("["));
+}
+
+#[test]
+fn test_checkout_base_uses_griptree_config() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo("app")
+        .add_repo("lib")
+        .build();
+
+    git_helpers::create_branch(&ws.repo_path("app"), "feat/base");
+    git_helpers::checkout(&ws.repo_path("app"), "main");
+    git_helpers::create_branch(&ws.repo_path("lib"), "feat/base");
+    git_helpers::checkout(&ws.repo_path("lib"), "main");
+
+    let config = GriptreeConfig::new("feat/base", &ws.workspace_root.to_string_lossy());
+    let config_path = ws.workspace_root.join(".gitgrip").join("griptree.json");
+    config.save(&config_path).unwrap();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("--base")
+        .assert()
+        .success();
+
+    assert_eq!(
+        git_helpers::current_branch(&ws.repo_path("app")),
+        "feat/base"
+    );
+    assert_eq!(
+        git_helpers::current_branch(&ws.repo_path("lib")),
+        "feat/base"
+    );
+}
+
+#[test]
+fn test_checkout_add_materializes_independent_child_checkout() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo("app")
+        .add_repo("lib")
+        .build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Created checkout 'sandbox'"));
+
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/sandbox");
+    let app_checkout = checkout_root.join("app");
+    let lib_checkout = checkout_root.join("lib");
+    assert!(app_checkout.join(".git").is_dir());
+    assert!(!app_checkout.join(".git").is_file());
+    assert!(lib_checkout.join(".git").is_dir());
+    assert!(!lib_checkout.join(".git").is_file());
+
+    let origin = std::process::Command::new("git")
+        .args(["remote", "get-url", "origin"])
+        .current_dir(&app_checkout)
+        .output()
+        .expect("git remote get-url");
+    let origin = String::from_utf8_lossy(&origin.stdout).trim().to_string();
+    assert_eq!(origin, ws.remote_url("app"));
+}
+
+#[test]
+fn test_checkout_add_respects_repo_filter() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo("app")
+        .add_repo("lib")
+        .build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("app-only")
+        .arg("--repo")
+        .arg("app")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Created checkout 'app-only' with 1 repo(s)",
+        ));
+
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/app-only");
+    assert!(checkout_root.join("app/.git").is_dir());
+    assert!(!checkout_root.join("lib").exists());
+}
+
+#[test]
+fn test_checkout_add_respects_group_filter() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo_with_groups("app", vec!["product"])
+        .add_repo_with_groups("docs", vec!["docs"])
+        .build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("docs-only")
+        .arg("--group")
+        .arg("docs")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Created checkout 'docs-only' with 1 repo(s)",
+        ));
+
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/docs-only");
+    assert!(checkout_root.join("docs/.git").is_dir());
+    assert!(!checkout_root.join("app").exists());
+}
+
+#[test]
+fn test_checkout_add_requires_name() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "Checkout name is required: gr checkout add <name>",
+        ));
+}
+
+#[test]
+fn test_checkout_add_errors_when_filters_match_no_repos() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("empty")
+        .arg("--repo")
+        .arg("missing")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "no repos matched checkout filters",
+        ));
+}
+
+#[test]
+fn test_checkout_add_rejects_create_and_base_flags() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut create_cmd = Command::cargo_bin("gr").unwrap();
+    create_cmd
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .arg("--create")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "--create and --base are not valid with 'add'",
+        ));
+
+    let mut base_cmd = Command::cargo_bin("gr").unwrap();
+    base_cmd
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .arg("--base")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "--create and --base are not valid with 'add'",
+        ));
+}
+
+#[test]
+fn test_checkout_add_rejects_extra_positional_args() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .arg("extra")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "unexpected extra arguments after checkout name",
+        ));
+}
+
+#[test]
+fn test_checkout_add_rejects_duplicate_checkout_name() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut first = Command::cargo_bin("gr").unwrap();
+    first
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr").unwrap();
+    duplicate
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "checkout 'sandbox' already exists",
+        ));
+}
+
+#[test]
+fn test_checkout_list_shows_materialized_checkouts() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut add = Command::cargo_bin("gr").unwrap();
+    add.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr").unwrap();
+    list.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Checkouts"))
+        .stdout(predicate::str::contains("sandbox ->"));
+}
+
+#[test]
+fn test_checkout_list_reports_empty_state() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut list = Command::cargo_bin("gr").unwrap();
+    list.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("No checkouts configured."));
+}
+
+#[test]
+fn test_checkout_list_rejects_extra_positional_args() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut list = Command::cargo_bin("gr").unwrap();
+    list.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("list")
+        .arg("extra")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "`gr checkout list` does not accept extra arguments",
+        ));
+}
+
+#[test]
+fn test_checkout_remove_deletes_materialized_checkout() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/sandbox");
+
+    let mut add = Command::cargo_bin("gr").unwrap();
+    add.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success();
+
+    assert!(checkout_root.is_dir());
+
+    let mut remove = Command::cargo_bin("gr").unwrap();
+    remove
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("remove")
+        .arg("sandbox")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Removed checkout 'sandbox'"));
+
+    assert!(!checkout_root.exists());
+}
+
+#[test]
+fn test_checkout_remove_errors_for_missing_checkout() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut remove = Command::cargo_bin("gr").unwrap();
+    remove
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("remove")
+        .arg("missing")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("Checkout 'missing' not found"));
+}
+
+#[test]
+fn test_checkout_remove_rejects_extra_positional_args() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut remove = Command::cargo_bin("gr").unwrap();
+    remove
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("remove")
+        .arg("sandbox")
+        .arg("extra")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "unexpected extra arguments after checkout name",
+        ));
+}
+
+// ─── gr2 apply link operations (grip#514) ──────────────────────────────
+
+#[test]
+fn test_gr2_plan_detects_missing_symlink() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a source file that the link will point to
+    std::fs::write(
+        workspace_root.join("config/shared.toml"),
+        "key = \"value\"\n",
+    )
+    .unwrap();
+
+    // Create the unit directory so Clone isn't planned
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("link"))
+        .stdout(predicate::str::contains("config/shared.toml"));
+}
+
+#[test]
+fn test_gr2_apply_creates_symlink() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a source file
+    std::fs::write(
+        workspace_root.join("config/shared.toml"),
+        "key = \"value\"\n",
+    )
+    .unwrap();
+
+    // Create the unit directory
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "symlink config/shared.toml -> agents/atlas/.config/shared.toml",
+        ));
+
+    let link_path = workspace_root.join("agents/atlas/.config/shared.toml");
+    assert!(link_path.exists(), "symlink destination should exist");
+    assert!(
+        link_path
+            .symlink_metadata()
+            .unwrap()
+            .file_type()
+            .is_symlink(),
+        "destination should be a symlink"
+    );
+
+    let content = std::fs::read_to_string(&link_path).unwrap();
+    assert_eq!(content, "key = \"value\"\n");
+}
+
+#[test]
+fn test_gr2_apply_creates_copy() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join("config/env.toml"),
+        "env = \"production\"\n",
+    )
+    .unwrap();
+
+    std::fs::create_dir_all(workspace_root.join("agents/apollo")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/apollo/unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+
+[[units.links]]
+src = "config/env.toml"
+dest = "env.toml"
+kind = "copy"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "copy config/env.toml -> agents/apollo/env.toml",
+        ));
+
+    let dest_path = workspace_root.join("agents/apollo/env.toml");
+    assert!(dest_path.exists(), "copy destination should exist");
+    assert!(
+        !dest_path
+            .symlink_metadata()
+            .unwrap()
+            .file_type()
+            .is_symlink(),
+        "copy destination should NOT be a symlink"
+    );
+
+    let content = std::fs::read_to_string(&dest_path).unwrap();
+    assert_eq!(content, "env = \"production\"\n");
+}
+
+#[test]
+fn test_gr2_apply_link_fails_for_missing_source() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "nonexistent/file.toml"
+dest = "file.toml"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("link source does not exist"));
+}
+
+#[test]
+fn test_gr2_plan_noop_when_link_already_exists() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join("config/shared.toml"),
+        "key = \"value\"\n",
+    )
+    .unwrap();
+
+    std::fs::create_dir_all(workspace_root.join("agents/atlas/.config")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+    // Pre-create the destination so the link is already satisfied
+    std::fs::write(
+        workspace_root.join("agents/atlas/.config/shared.toml"),
+        "existing",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"));
+}
+
+#[test]
+fn test_gr2_apply_records_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    let state_path = workspace_root.join(".grip/state/applied.toml");
+    assert!(state_path.exists(), "apply should record state");
+
+    let state = std::fs::read_to_string(&state_path).unwrap();
+    assert!(
+        state.contains("[[applied]]"),
+        "state should contain applied entries"
+    );
+    assert!(
+        state.contains("cloned unit"),
+        "state should record clone action"
+    );
+}
+
+#[test]
+fn test_gr2_apply_mixed_clone_and_link() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("cloned unit 'atlas'"))
+        .stdout(predicate::str::contains("symlink config/shared.toml"));
+
+    assert!(workspace_root.join("agents/atlas/unit.toml").exists());
+    assert!(workspace_root
+        .join("agents/atlas/.config/shared.toml")
+        .exists());
+}
+
+// ── gr2 apply TDD specs (grip#514, grip#526) ────────────────────────────────
+
+/// gr2 apply is a recognized subcommand (not "error: unrecognized subcommand").
+#[test]
+fn test_gr2_apply_command_recognized() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .stderr(predicate::str::contains("unrecognized subcommand").not());
+}
+
+/// gr2 apply outside a gr2 workspace returns a clear error.
+#[test]
+fn test_gr2_apply_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(temp.path())
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("not in a gr2 workspace"));
+}
+
+/// gr2 apply is idempotent: running twice on a fully-materialized workspace
+/// succeeds without error.
+#[test]
+fn test_gr2_apply_idempotent_on_materialized_workspace() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    let mut second = Command::cargo_bin("gr2").unwrap();
+    second
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+}
+
+// ── gr2 apply: guard correctness + repo materialization (grip#514) ──────────
+
+/// guard_for_apply uses the unit's actual path from the spec, not the
+/// `agents/{name}` fallback, when checking for dirty checkouts.
+/// Regression test for Atlas's review note on grip#531.
+#[test]
+fn test_gr2_guard_uses_actual_unit_path_for_warnings() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a unit at a NON-default path (units/apollo, not agents/apollo)
+    // with a .git directory to trigger the dirty-checkout warning.
+    std::fs::create_dir_all(workspace_root.join("units/apollo/.git")).unwrap();
+    std::fs::write(
+        workspace_root.join("units/apollo/unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "apollo"
+path = "units/apollo"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    // Plan should warn about dirty checkout at units/apollo, NOT agents/apollo.
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("units/apollo"))
+        .stdout(predicate::str::contains("uncommitted changes"));
+}
+
+/// Clone operation materializes repos declared in the unit's `repos` list
+/// by cloning them from their registered URLs.
+#[test]
+fn test_gr2_apply_clone_materializes_unit_repos() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a local bare repo to use as the "remote"
+    let bare_repo = temp.path().join("bare-repo.git");
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare_repo)
+        .output()
+        .unwrap();
+
+    // Register the repo in the workspace
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "test-repo"])
+        .arg(bare_repo.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Write a spec that declares a unit referencing the repo
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "test-repo"
+path = "repos/test-repo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["test-repo"]
+"#,
+        toml_path(&bare_repo)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // The unit directory and unit.toml should exist
+    assert!(workspace_root.join("agents/apollo/unit.toml").exists());
+
+    // The repo should be cloned into the unit's workspace
+    let repo_checkout = workspace_root.join("agents/apollo/test-repo");
+    assert!(
+        repo_checkout.exists(),
+        "repo should be cloned into unit workspace at agents/apollo/test-repo"
+    );
+    assert!(
+        repo_checkout.join(".git").exists(),
+        "cloned repo should have a .git directory"
+    );
+}
+
+/// Plan output shows repo clone operations for units with declared repos.
+#[test]
+fn test_gr2_plan_shows_repo_clone_for_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare_repo = temp.path().join("bare-repo.git");
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare_repo)
+        .output()
+        .unwrap();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "test-repo"])
+        .arg(bare_repo.to_str().unwrap())
+        .assert()
+        .success();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "test-repo"
+path = "repos/test-repo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["test-repo"]
+"#,
+        toml_path(&bare_repo)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("clone"))
+        .stdout(predicate::str::contains("apollo"));
+}
+
+// ── gr2 apply: autostash policy (grip#534) ────────────────────────────────────
+
+/// Helper: create a local bare repo with one committed file, suitable for
+/// cloning into unit workspaces. Returns the path to the bare repo.
+fn create_bare_repo_with_content(parent: &std::path::Path, name: &str) -> std::path::PathBuf {
+    let bare = parent.join(format!("{}.git", name));
+    std::process::Command::new("git")
+        .args(["init", "--bare", "-b", "main"])
+        .arg(&bare)
+        .output()
+        .unwrap();
+
+    // Clone into a temp working copy, add a file, push back
+    let work = parent.join(format!("{}-work", name));
+    std::process::Command::new("git")
+        .args(["clone"])
+        .arg(&bare)
+        .arg(&work)
+        .output()
+        .unwrap();
+    git_helpers::configure_identity(&work);
+    std::fs::write(work.join("README.md"), "# test\n").unwrap();
+    std::process::Command::new("git")
+        .args(["add", "."])
+        .current_dir(&work)
+        .output()
+        .unwrap();
+    std::process::Command::new("git")
+        .args(["commit", "-m", "init"])
+        .current_dir(&work)
+        .output()
+        .unwrap();
+    std::process::Command::new("git")
+        .args(["push"])
+        .current_dir(&work)
+        .output()
+        .unwrap();
+
+    bare
+}
+
+fn toml_path(path: &std::path::Path) -> String {
+    path.display().to_string().replace('\\', "\\\\")
+}
+
+/// Helper: set up a workspace with a unit that has an already-cloned repo.
+/// Returns the workspace root path.
+fn setup_workspace_with_cloned_unit(
+    temp: &TempDir,
+    bare_repo: &std::path::Path,
+) -> std::path::PathBuf {
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Register the repo
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app"])
+        .arg(bare_repo.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Write spec with the unit referencing the repo
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+"#,
+        toml_path(&bare_repo)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Run apply once to materialize the unit + clone the repo
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // Verify the repo is cloned
+    assert!(workspace_root.join("agents/apollo/app/.git").exists());
+
+    workspace_root
+}
+
+/// gr2 apply should block when a unit's cloned repo has uncommitted changes
+/// and --autostash is not provided. Default must be safe: no silent discard.
+#[test]
+fn test_gr2_apply_blocks_dirty_repo_without_autostash() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo: modify the tracked file
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# modified\n").unwrap();
+
+    // Create a shared config file so we can add a link operation to the plan
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+
+    // Rewrite spec to add a link (triggers a Link operation since dest doesn't exist)
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Apply without --autostash should fail because the unit's repo is dirty
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("dirty").or(predicate::str::contains("uncommitted")));
+}
+
+/// gr2 apply --autostash should preserve dirty changes by stashing before
+/// the operation and popping after.
+#[test]
+fn test_gr2_apply_autostash_preserves_dirty_changes() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# modified by agent\n").unwrap();
+
+    // Add a link to trigger an operation
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Apply with --autostash should succeed
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .args(["apply", "--autostash"])
+        .assert()
+        .success();
+
+    // The dirty change should still be present after apply
+    let content = std::fs::read_to_string(repo_checkout.join("README.md")).unwrap();
+    assert!(
+        content.contains("modified by agent"),
+        "autostash should preserve the dirty change; got: {}",
+        content
+    );
+}
+
+/// gr2 plan should report actual dirty state (uncommitted changes detected)
+/// rather than just "possible uncommitted changes" based on .git existence.
+#[test]
+fn test_gr2_plan_shows_actual_dirty_state() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# dirty\n").unwrap();
+
+    // Add a link to trigger an operation in the plan
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Plan should report the dirty state with specifics
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("uncommitted changes"));
+}
+
+/// When --autostash is used, gr2 apply should record the stash action
+/// in .grip/state for recovery and auditability.
+#[test]
+fn test_gr2_autostash_records_state() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# dirty for stash\n").unwrap();
+
+    // Add a link to trigger an operation
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Apply with --autostash
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .args(["apply", "--autostash"])
+        .assert()
+        .success();
+
+    // Stash state should be recorded
+    let stash_state = workspace_root.join(".grip/state/stash.toml");
+    assert!(
+        stash_state.exists(),
+        "autostash should record state in .grip/state/stash.toml"
+    );
+    let content = std::fs::read_to_string(&stash_state).unwrap();
+    assert!(
+        content.contains("apollo") && content.contains("app"),
+        "stash state should reference the unit and repo; got: {}",
+        content
+    );
+}
+
+/// gr2 apply should succeed without --autostash when repos are clean
+/// (no uncommitted changes). Clean workspaces need no special handling.
+#[test]
+fn test_gr2_apply_clean_repo_no_autostash_needed() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Don't dirty anything — the repo is clean
+
+    // Apply without --autostash should succeed on clean workspace
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+}
+
+// ── gr2 apply: partial unit convergence (grip#539) ────────────────────────────
+
+/// When a unit exists (unit.toml present, path correct) but a declared repo
+/// has not been cloned, plan should emit an operation to converge it.
+#[test]
+fn test_gr2_plan_detects_missing_repo_in_existing_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "myrepo");
+
+    // Register the repo
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "myrepo"])
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Manually create the unit directory with unit.toml (simulating a
+    // partially-materialized unit where the unit exists but repos aren't cloned)
+    let unit_root = workspace_root.join("agents/apollo");
+    std::fs::create_dir_all(&unit_root).unwrap();
+    std::fs::write(
+        unit_root.join("unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\nrepos = [\"myrepo\"]\n",
+    )
+    .unwrap();
+
+    // Write a spec declaring the unit with the repo
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "myrepo"
+path = "repos/myrepo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["myrepo"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Plan should detect the missing repo and emit a non-empty plan
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("apollo"))
+        .stdout(predicate::str::contains("no changes required").not());
+}
+
+/// Apply should clone missing repos into an existing unit, converging it
+/// to match the declared spec.
+#[test]
+fn test_gr2_apply_converges_missing_repo_in_existing_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "myrepo");
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "myrepo"])
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Create partially-materialized unit (unit.toml exists, repo not cloned)
+    let unit_root = workspace_root.join("agents/apollo");
+    std::fs::create_dir_all(&unit_root).unwrap();
+    std::fs::write(
+        unit_root.join("unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\nrepos = [\"myrepo\"]\n",
+    )
+    .unwrap();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "myrepo"
+path = "repos/myrepo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["myrepo"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // Apply should converge: clone the missing repo
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // Verify the repo was cloned into the unit
+    let repo_checkout = unit_root.join("myrepo");
+    assert!(
+        repo_checkout.join(".git").exists(),
+        "missing repo should be cloned into existing unit at agents/apollo/myrepo"
+    );
+}
+
+/// Apply is idempotent: running on a fully-converged unit (repos already
+/// cloned) should produce "no changes required".
+#[test]
+fn test_gr2_apply_idempotent_after_repo_convergence() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "myrepo");
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "myrepo"])
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Create partially-materialized unit
+    let unit_root = workspace_root.join("agents/apollo");
+    std::fs::create_dir_all(&unit_root).unwrap();
+    std::fs::write(
+        unit_root.join("unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\nrepos = [\"myrepo\"]\n",
+    )
+    .unwrap();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "myrepo"
+path = "repos/myrepo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["myrepo"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
+
+    // First apply converges
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // Second apply should be a no-op
+    let mut second = Command::cargo_bin("gr2").unwrap();
+    second
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"));
+}
+
+#[test]
+fn test_gr2_lane_create_persists_metadata_and_scaffolds_lane_root() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app", "https://example.com/app.git"])
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-123",
+            "--owner-unit",
+            "atlas",
+            "--type",
+            "feature",
+            "--branch",
+            "app=feat-123",
+            "--exec",
+            "cargo test -p app",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Created lane 'feat-123'"))
+        .stdout(predicate::str::contains("repos: app"));
+
+    let metadata_path = workspace_root.join(".grip/state/lanes/atlas/feat-123.toml");
+    assert!(metadata_path.exists());
+    let metadata = std::fs::read_to_string(&metadata_path).unwrap();
+    assert!(metadata.contains("lane_id = \"atlas:feat-123\""));
+    assert!(metadata.contains("lane_name = \"feat-123\""));
+    assert!(metadata.contains("owner_unit = \"atlas\""));
+    assert!(metadata.contains("lane_type = \"feature\""));
+    assert!(metadata.contains("repos = [\"app\"]"));
+    assert!(metadata.contains("app = \"feat-123\""));
+    assert!(metadata.contains("commands = [\"cargo test -p app\"]"));
+
+    assert!(workspace_root
+        .join("agents/atlas/lanes/feat-123/repos")
+        .is_dir());
+    assert!(workspace_root
+        .join("agents/atlas/lanes/feat-123/context")
+        .is_dir());
+}
+
+#[test]
+fn test_gr2_lane_list_and_show_report_persisted_lane() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app", "https://example.com/app.git"])
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "review-548",
+            "--owner-unit",
+            "atlas",
+            "--type",
+            "review",
+            "--repo",
+            "app",
+            "--pr",
+            "app:548",
+        ])
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .args(["lane", "list"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Lanes"))
+        .stdout(predicate::str::contains("atlas review-548 review 1"));
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .args(["lane", "show", "review-548", "--owner-unit", "atlas"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("lane_name = \"review-548\""))
+        .stdout(predicate::str::contains("number = 548"));
+}
+
+#[test]
+fn test_gr2_lane_remove_deletes_metadata_and_lane_root() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app", "https://example.com/app.git"])
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "scratch-a",
+            "--owner-unit",
+            "atlas",
+            "--type",
+            "scratch",
+        ])
+        .assert()
+        .success();
+
+    let metadata_path = workspace_root.join(".grip/state/lanes/atlas/scratch-a.toml");
+    let lane_root = workspace_root.join("agents/atlas/lanes/scratch-a");
+    assert!(metadata_path.exists());
+    assert!(lane_root.exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .args(["lane", "remove", "scratch-a", "--owner-unit", "atlas"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Removed lane 'scratch-a' for unit 'atlas'",
+        ));
+
+    assert!(!metadata_path.exists());
+    assert!(!lane_root.exists());
+}
+
+#[test]
+fn test_gr2_lane_create_rejects_unknown_repo_membership() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-unknown",
+            "--owner-unit",
+            "atlas",
+            "--repo",
+            "missing",
+        ])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("unknown repo 'missing'"));
+}
+
+#[test]
+fn test_gr2_exec_status_reports_lane_execution_surface() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    for (name, url) in [
+        ("app", "https://example.com/app.git"),
+        ("api", "https://example.com/api.git"),
+    ] {
+        let mut repo_add = Command::cargo_bin("gr2").unwrap();
+        repo_add
+            .current_dir(&workspace_root)
+            .args(["repo", "add", name, url])
+            .assert()
+            .success();
+    }
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "https://example.com/api.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app", "api"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-auth",
+            "--owner-unit",
+            "atlas",
+            "--branch",
+            "app=feat-auth",
+            "--pr",
+            "app:548",
+            "--exec",
+            "cargo test -p app",
+            "--exec",
+            "cargo test -p api",
+        ])
+        .assert()
+        .success();
+
+    let mut exec_status = Command::cargo_bin("gr2").unwrap();
+    exec_status
+        .current_dir(&workspace_root)
+        .args([
+            "exec",
+            "status",
+            "--lane",
+            "feat-auth",
+            "--owner-unit",
+            "atlas",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("gr2 exec status"))
+        .stdout(predicate::str::contains("lane: atlas/feat-auth"))
+        .stdout(predicate::str::contains("parallel: false"))
+        .stdout(predicate::str::contains("fail_fast: true"))
+        .stdout(predicate::str::contains("- cargo test -p app"))
+        .stdout(predicate::str::contains("app missing"))
+        .stdout(predicate::str::contains("feat-auth"))
+        .stdout(predicate::str::contains("548 2"))
+        .stdout(predicate::str::contains("api missing"))
+        .stdout(predicate::str::contains("repos"))
+        .stdout(predicate::str::contains("api"))
+        .stdout(predicate::str::contains(" - - 2"));
+}
+
+#[test]
+fn test_gr2_exec_status_filters_to_selected_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    for (name, url) in [
+        ("app", "https://example.com/app.git"),
+        ("api", "https://example.com/api.git"),
+    ] {
+        let mut repo_add = Command::cargo_bin("gr2").unwrap();
+        repo_add
+            .current_dir(&workspace_root)
+            .args(["repo", "add", name, url])
+            .assert()
+            .success();
+    }
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "https://example.com/api.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app", "api"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-filter",
+            "--owner-unit",
+            "atlas",
+            "--repo",
+            "app",
+            "--repo",
+            "api",
+        ])
+        .assert()
+        .success();
+
+    let mut exec_status = Command::cargo_bin("gr2").unwrap();
+    exec_status
+        .current_dir(&workspace_root)
+        .args([
+            "exec",
+            "status",
+            "--lane",
+            "feat-filter",
+            "--owner-unit",
+            "atlas",
+            "--repo",
+            "api",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("api missing"))
+        .stdout(predicate::str::contains("feat-filter"))
+        .stdout(predicate::str::contains("repos"))
+        .stdout(predicate::str::contains("app").not());
 }
diff --git a/tests/common/mock_platform.rs b/tests/common/mock_platform.rs
index 8b4f5955..b46c6432 100644
--- a/tests/common/mock_platform.rs
+++ b/tests/common/mock_platform.rs
@@ -194,7 +194,7 @@ fn github_pr_json(
     body: &str,
 ) -> Value {
     let repo = github_repo_json("owner", "repo");
-    let api_base = format!("https://api.github.com/repos/owner/repo");
+    let api_base = "https://api.github.com/repos/owner/repo".to_string();
 
     let mut m = Map::new();
     m.insert("id".into(), json!(number));
diff --git a/tests/griptree_tests.rs b/tests/griptree_tests.rs
index 0101905c..4af25c82 100644
--- a/tests/griptree_tests.rs
+++ b/tests/griptree_tests.rs
@@ -82,7 +82,7 @@ fn test_griptree_pointer_new_fields() {
     assert_eq!(pointer.repos.len(), 1);
     assert_eq!(pointer.repos[0].name, "codi");
     assert_eq!(pointer.repos[0].original_branch, "main");
-    assert_eq!(pointer.repos[0].is_reference, false);
+    assert!(!pointer.repos[0].is_reference);
     assert_eq!(
         pointer.manifest_branch,
         Some("griptree-feat-test".to_string())
@@ -206,5 +206,5 @@ fn test_griptree_repo_info_camel_case() {
 
     let deserialized: GriptreeRepoInfo = serde_json::from_str(&json).unwrap();
     assert_eq!(deserialized.original_branch, "develop");
-    assert_eq!(deserialized.is_reference, false);
+    assert!(!deserialized.is_reference);
 }
diff --git a/tests/integration_agent_id.rs b/tests/integration_agent_id.rs
index 54f3cd1b..4e5ae987 100644
--- a/tests/integration_agent_id.rs
+++ b/tests/integration_agent_id.rs
@@ -6,7 +6,6 @@
 //! Conversa migration test in CI.
 
 use std::fs;
-use std::path::PathBuf;
 use tempfile::TempDir;
 
 // Re-export the registry functions we're testing
diff --git a/tests/multi_provider_e2e.rs b/tests/multi_provider_e2e.rs
index 26becef3..19c147fe 100644
--- a/tests/multi_provider_e2e.rs
+++ b/tests/multi_provider_e2e.rs
@@ -151,7 +151,7 @@ mod github_tests {
 
         // Verify manifest
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
         assert!(manifest.contains("repo1"), "repo1 not in manifest");
@@ -339,7 +339,7 @@ mod gitlab_tests {
         );
 
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
         assert!(manifest.contains("repo1"));
@@ -454,7 +454,7 @@ mod gitlab_tests {
 
         // Read and print the manifest
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         if manifest_path.exists() {
             let manifest_content = fs::read_to_string(&manifest_path).unwrap();
@@ -633,7 +633,7 @@ mod azure_tests {
         );
 
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
         assert!(manifest.contains("repo1"));
@@ -853,7 +853,7 @@ mod mixed_platform_tests {
         );
 
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
 
diff --git a/tests/test_add.rs b/tests/test_add.rs
index e05e0c42..de99bb61 100644
--- a/tests/test_add.rs
+++ b/tests/test_add.rs
@@ -2,7 +2,6 @@
 
 mod common;
 
-use common::assertions::assert_repo_clean;
 use common::fixtures::WorkspaceBuilder;
 
 #[test]
diff --git a/tests/test_branch.rs b/tests/test_branch.rs
index ee30a23e..07ff3aec 100644
--- a/tests/test_branch.rs
+++ b/tests/test_branch.rs
@@ -2,9 +2,7 @@
 
 mod common;
 
-use common::assertions::{
-    assert_all_on_branch, assert_branch_exists, assert_branch_not_exists, assert_on_branch,
-};
+use common::assertions::{assert_branch_exists, assert_branch_not_exists, assert_on_branch};
 use common::fixtures::WorkspaceBuilder;
 use common::git_helpers;
 
@@ -300,3 +298,51 @@ fn test_branch_create_then_verify_branches_exist() {
     assert_branch_exists(&ws.repo_path("alpha"), "main");
     assert_branch_exists(&ws.repo_path("beta"), "main");
 }
+
+/// Regression test for grip#401: `gr branch` on an existing branch must
+/// switch to it so subsequent commits land on the correct branch.
+#[test]
+fn test_branch_switches_to_existing_branch() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+    let manifest = ws.load_manifest();
+
+    // Create feat/target and then switch back to main
+    gitgrip::cli::commands::branch::run_branch(gitgrip::cli::commands::branch::BranchOptions {
+        workspace_root: &ws.workspace_root,
+        manifest: &manifest,
+        name: Some("feat/target"),
+        delete: false,
+        move_commits: false,
+        repos_filter: None,
+        group_filter: None,
+        json: false,
+    })
+    .unwrap();
+
+    gitgrip::cli::commands::checkout::run_checkout(
+        &ws.workspace_root,
+        &manifest,
+        "main",
+        false,
+        None,
+        None,
+    )
+    .unwrap();
+    assert_on_branch(&ws.repo_path("app"), "main");
+
+    // Run `gr branch feat/target` again — should switch to it
+    gitgrip::cli::commands::branch::run_branch(gitgrip::cli::commands::branch::BranchOptions {
+        workspace_root: &ws.workspace_root,
+        manifest: &manifest,
+        name: Some("feat/target"),
+        delete: false,
+        move_commits: false,
+        repos_filter: None,
+        group_filter: None,
+        json: false,
+    })
+    .unwrap();
+
+    // Must be on feat/target, not main
+    assert_on_branch(&ws.repo_path("app"), "feat/target");
+}
diff --git a/tests/test_commit.rs b/tests/test_commit.rs
index 6bf2bc48..c207a13b 100644
--- a/tests/test_commit.rs
+++ b/tests/test_commit.rs
@@ -4,7 +4,6 @@ mod common;
 
 use common::assertions::assert_repo_clean;
 use common::fixtures::WorkspaceBuilder;
-use common::git_helpers;
 
 #[test]
 fn test_commit_across_repos() {
diff --git a/tests/test_status.rs b/tests/test_status.rs
index 8d694697..f7b00ba1 100644
--- a/tests/test_status.rs
+++ b/tests/test_status.rs
@@ -2,9 +2,7 @@
 
 mod common;
 
-use common::assertions;
 use common::fixtures::WorkspaceBuilder;
-use common::git_helpers;
 
 #[test]
 fn test_status_clean_workspace() {