gitgrip 2.0.0a1__tar.gz → 2.0.0a3__tar.gz

gitgrip-2.0.0a3/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: gitgrip
+Version: 2.0.0a3
+Summary: Workspace layer for multi-repo work: workspaces, isolated lanes, and one grouped review per slice
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9
+Requires-Dist: tomli_w>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# gr2
+
+**gr2 is the workspace layer for multi-repo work.** One repository is just git; when a change spans repositories — a feature slice, a release, several agents touching several repos — gr2 gives you a workspace over them, isolated lanes to work in, and one grouped review/PR set for the slice. It is the Python successor to the Rust `gr` (1.x, called gr1 below); both ship from this repository, and `gr2` is the command for the workspace and the slice.
+
+## Install
+
+```bash
+uv tool install --pre gitgrip    # the PyPI package is "gitgrip"; the command is "gr2"
+gr2 --version
+```
+
+Without uv, a venv and pip do the same:
+
+```bash
+python3 -m venv ~/gr2-venv && source ~/gr2-venv/bin/activate
+pip install --pre gitgrip
+gr2 --version
+```
+
+`--pre` is required while every gr2 release is an alpha: 1.5.0 and 1.5.1 were pre-alpha builds and are yanked, so without `--pre` there is nothing to install.
+
+Already installed 1.5.0 or 1.5.1? The install commands above leave it in place, because an installed version already satisfies them. Upgrade explicitly: `uv tool upgrade --prerelease allow gitgrip`, or `pip install --pre -U gitgrip`. To run unreleased development code instead, install from a checkout: `pip install -e gr2/` from the repository root.
+
+The Rust `gr` (gr1, 1.x) installs with `brew install synapt-dev/tap/gitgrip` or `cargo install gitgrip`. The two do not collide; you can have both installed.
+
+## First five minutes
+
+Every command below was run, in this order, in a clean virtualenv against a throwaway workspace of two repositories. Put two clones side by side in one folder, say `~/ws/repo-a` and `~/ws/repo-b`.
+
+```bash
+cd ~/ws
+gr2 workspace init ~/ws                 # scans the folder; writes .grip/workspace_spec.toml
+gr2 workspace materialize ~/ws --yes    # builds the .grip layout and a default unit
+gr2 workspace status ~/ws               # what kind of workspace this is
+gr2 store init ~/ws                     # the workspace snapshot store (needed before review)
+```
+
+A **unit** is one worker — you, or one agent — and `default` is created for you. A **lane** is one piece of work spanning repos, with its own clones, so two lanes never step on each other:
+
+```bash
+gr2 lane create ~/ws default feat-x --repos repo-a,repo-b --branch feat/x
+gr2 lane enter  ~/ws default feat-x --actor human:you
+```
+
+Both commands print, per repo, the absolute directory you work in:
+
+```
+repo-a: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
+repo-b: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-b
+```
+
+Edit there — not in your original clones. Stage and commit across the lane's repos:
+
+```bash
+gr2 add . --repo-path ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
+gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
+```
+
+`commit` with the lane flags commits every lane repo that has staged changes and names the repos it skipped. If every repo was skipped it exits non-zero with one sentence naming where it looked — and, when it can see them, where your staged changes actually are. Run one command across every lane repo, then turn the lane into one reviewable object:
+
+```bash
+gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
+gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
+gr2 lane current ~/ws default                              # where am I?
+gr2 lane exit ~/ws default --actor human:you
+```
+
+`exec run` and `lane exit` require `--actor`. Every group and verb takes `--help`; `gr2 --help` lists them all.
+
+## What works today, and what is not there yet
+
+Alpha 2 is a working local workspace layer. Verified by running the walk above:
+
+- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, snapshot, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
+- Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
+- A lane commit that commits nothing anywhere refuses loudly instead of reporting success.
+
+Not there yet:
+
+- The full walk with **remote** PRs (`gr2 push`, `gr2 pr create`) is documented in `--help` but was not exercised in a clean environment for this README; treat those two as alpha.
+- `gr2 --help` and some verb output still say "prototype" in places; the wording is being cleaned up as verbs land.
+- The Rust `gr` (gr1) still owns `spawn`, `fleet`, and `manifest` until their gr2 ports land. Everything else — workspace sync, lanes, the multi-repo slice, its review — is gr2's job; if a verb is missing or wrong there, that is a bug worth reporting, not a reason to reach for gr1.
+
+## Commands
+
+| Group | Verbs |
+|---|---|
+| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1 |
+| `spec` | show, validate |
+| `lane` | create, enter, exit, current, resolve, bind, lease |
+| (top level) | branch, add, commit, push, prune |
+| `sync` | status, run |
+| `pr` | create, status, checks, merge |
+| `review` | open, close, checkout-pr, run, requirements, bind, verify, rebind, create-project |
+| `exec` | status, run |
+| `repo` | status, hooks, hook-run, projection-run |
+| `store` | init, snapshot, log, diff, checkout |
+| `target`, `config`, `plan`, `apply` | stored PR target; config overlays; show/apply the materialization plan |
+
+## Overlay substrate
+
+gr2 also carries the config-overlay substrate (capture, compose, and materialize configuration layers over a workspace): see [docs/OVERLAY-SUBSTRATE.md](docs/OVERLAY-SUBSTRATE.md).
+
+## Development
+
+```bash
+pip install -e "gr2[dev]"    # from the repository root
+cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
+cd gr2 && ruff check .       # lint, same config as CI
+```

gitgrip-2.0.0a3/README.md

@@ -0,0 +1,110 @@
+# gr2
+
+**gr2 is the workspace layer for multi-repo work.** One repository is just git; when a change spans repositories — a feature slice, a release, several agents touching several repos — gr2 gives you a workspace over them, isolated lanes to work in, and one grouped review/PR set for the slice. It is the Python successor to the Rust `gr` (1.x, called gr1 below); both ship from this repository, and `gr2` is the command for the workspace and the slice.
+
+## Install
+
+```bash
+uv tool install --pre gitgrip    # the PyPI package is "gitgrip"; the command is "gr2"
+gr2 --version
+```
+
+Without uv, a venv and pip do the same:
+
+```bash
+python3 -m venv ~/gr2-venv && source ~/gr2-venv/bin/activate
+pip install --pre gitgrip
+gr2 --version
+```
+
+`--pre` is required while every gr2 release is an alpha: 1.5.0 and 1.5.1 were pre-alpha builds and are yanked, so without `--pre` there is nothing to install.
+
+Already installed 1.5.0 or 1.5.1? The install commands above leave it in place, because an installed version already satisfies them. Upgrade explicitly: `uv tool upgrade --prerelease allow gitgrip`, or `pip install --pre -U gitgrip`. To run unreleased development code instead, install from a checkout: `pip install -e gr2/` from the repository root.
+
+The Rust `gr` (gr1, 1.x) installs with `brew install synapt-dev/tap/gitgrip` or `cargo install gitgrip`. The two do not collide; you can have both installed.
+
+## First five minutes
+
+Every command below was run, in this order, in a clean virtualenv against a throwaway workspace of two repositories. Put two clones side by side in one folder, say `~/ws/repo-a` and `~/ws/repo-b`.
+
+```bash
+cd ~/ws
+gr2 workspace init ~/ws                 # scans the folder; writes .grip/workspace_spec.toml
+gr2 workspace materialize ~/ws --yes    # builds the .grip layout and a default unit
+gr2 workspace status ~/ws               # what kind of workspace this is
+gr2 store init ~/ws                     # the workspace snapshot store (needed before review)
+```
+
+A **unit** is one worker — you, or one agent — and `default` is created for you. A **lane** is one piece of work spanning repos, with its own clones, so two lanes never step on each other:
+
+```bash
+gr2 lane create ~/ws default feat-x --repos repo-a,repo-b --branch feat/x
+gr2 lane enter  ~/ws default feat-x --actor human:you
+```
+
+Both commands print, per repo, the absolute directory you work in:
+
+```
+repo-a: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
+repo-b: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-b
+```
+
+Edit there — not in your original clones. Stage and commit across the lane's repos:
+
+```bash
+gr2 add . --repo-path ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
+gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
+```
+
+`commit` with the lane flags commits every lane repo that has staged changes and names the repos it skipped. If every repo was skipped it exits non-zero with one sentence naming where it looked — and, when it can see them, where your staged changes actually are. Run one command across every lane repo, then turn the lane into one reviewable object:
+
+```bash
+gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
+gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
+gr2 lane current ~/ws default                              # where am I?
+gr2 lane exit ~/ws default --actor human:you
+```
+
+`exec run` and `lane exit` require `--actor`. Every group and verb takes `--help`; `gr2 --help` lists them all.
+
+## What works today, and what is not there yet
+
+Alpha 2 is a working local workspace layer. Verified by running the walk above:
+
+- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, snapshot, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
+- Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
+- A lane commit that commits nothing anywhere refuses loudly instead of reporting success.
+
+Not there yet:
+
+- The full walk with **remote** PRs (`gr2 push`, `gr2 pr create`) is documented in `--help` but was not exercised in a clean environment for this README; treat those two as alpha.
+- `gr2 --help` and some verb output still say "prototype" in places; the wording is being cleaned up as verbs land.
+- The Rust `gr` (gr1) still owns `spawn`, `fleet`, and `manifest` until their gr2 ports land. Everything else — workspace sync, lanes, the multi-repo slice, its review — is gr2's job; if a verb is missing or wrong there, that is a bug worth reporting, not a reason to reach for gr1.
+
+## Commands
+
+| Group | Verbs |
+|---|---|
+| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1 |
+| `spec` | show, validate |
+| `lane` | create, enter, exit, current, resolve, bind, lease |
+| (top level) | branch, add, commit, push, prune |
+| `sync` | status, run |
+| `pr` | create, status, checks, merge |
+| `review` | open, close, checkout-pr, run, requirements, bind, verify, rebind, create-project |
+| `exec` | status, run |
+| `repo` | status, hooks, hook-run, projection-run |
+| `store` | init, snapshot, log, diff, checkout |
+| `target`, `config`, `plan`, `apply` | stored PR target; config overlays; show/apply the materialization plan |
+
+## Overlay substrate
+
+gr2 also carries the config-overlay substrate (capture, compose, and materialize configuration layers over a workspace): see [docs/OVERLAY-SUBSTRATE.md](docs/OVERLAY-SUBSTRATE.md).
+
+## Development
+
+```bash
+pip install -e "gr2[dev]"    # from the repository root
+cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
+cd gr2 && ruff check .       # lint, same config as CI
+```

gitgrip-2.0.0a3/gitgrip.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: gitgrip
+Version: 2.0.0a3
+Summary: Workspace layer for multi-repo work: workspaces, isolated lanes, and one grouped review per slice
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9
+Requires-Dist: tomli_w>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# gr2
+
+**gr2 is the workspace layer for multi-repo work.** One repository is just git; when a change spans repositories — a feature slice, a release, several agents touching several repos — gr2 gives you a workspace over them, isolated lanes to work in, and one grouped review/PR set for the slice. It is the Python successor to the Rust `gr` (1.x, called gr1 below); both ship from this repository, and `gr2` is the command for the workspace and the slice.
+
+## Install
+
+```bash
+uv tool install --pre gitgrip    # the PyPI package is "gitgrip"; the command is "gr2"
+gr2 --version
+```
+
+Without uv, a venv and pip do the same:
+
+```bash
+python3 -m venv ~/gr2-venv && source ~/gr2-venv/bin/activate
+pip install --pre gitgrip
+gr2 --version
+```
+
+`--pre` is required while every gr2 release is an alpha: 1.5.0 and 1.5.1 were pre-alpha builds and are yanked, so without `--pre` there is nothing to install.
+
+Already installed 1.5.0 or 1.5.1? The install commands above leave it in place, because an installed version already satisfies them. Upgrade explicitly: `uv tool upgrade --prerelease allow gitgrip`, or `pip install --pre -U gitgrip`. To run unreleased development code instead, install from a checkout: `pip install -e gr2/` from the repository root.
+
+The Rust `gr` (gr1, 1.x) installs with `brew install synapt-dev/tap/gitgrip` or `cargo install gitgrip`. The two do not collide; you can have both installed.
+
+## First five minutes
+
+Every command below was run, in this order, in a clean virtualenv against a throwaway workspace of two repositories. Put two clones side by side in one folder, say `~/ws/repo-a` and `~/ws/repo-b`.
+
+```bash
+cd ~/ws
+gr2 workspace init ~/ws                 # scans the folder; writes .grip/workspace_spec.toml
+gr2 workspace materialize ~/ws --yes    # builds the .grip layout and a default unit
+gr2 workspace status ~/ws               # what kind of workspace this is
+gr2 store init ~/ws                     # the workspace snapshot store (needed before review)
+```
+
+A **unit** is one worker — you, or one agent — and `default` is created for you. A **lane** is one piece of work spanning repos, with its own clones, so two lanes never step on each other:
+
+```bash
+gr2 lane create ~/ws default feat-x --repos repo-a,repo-b --branch feat/x
+gr2 lane enter  ~/ws default feat-x --actor human:you
+```
+
+Both commands print, per repo, the absolute directory you work in:
+
+```
+repo-a: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
+repo-b: ~/ws/.grip/state/lanes/default/feat-x/repos/repo-b
+```
+
+Edit there — not in your original clones. Stage and commit across the lane's repos:
+
+```bash
+gr2 add . --repo-path ~/ws/.grip/state/lanes/default/feat-x/repos/repo-a
+gr2 commit -m "my change" --workspace-root ~/ws --owner-unit default
+```
+
+`commit` with the lane flags commits every lane repo that has staged changes and names the repos it skipped. If every repo was skipped it exits non-zero with one sentence naming where it looked — and, when it can see them, where your staged changes actually are. Run one command across every lane repo, then turn the lane into one reviewable object:
+
+```bash
+gr2 exec run ~/ws default --actor human:you -- pytest -q   # one command, every lane repo
+gr2 review create-project ~/ws default feat-x              # prints gr:<sha>: one object to review
+gr2 lane current ~/ws default                              # where am I?
+gr2 lane exit ~/ws default --actor human:you
+```
+
+`exec run` and `lane exit` require `--actor`. Every group and verb takes `--help`; `gr2 --help` lists them all.
+
+## What works today, and what is not there yet
+
+Alpha 2 is a working local workspace layer. Verified by running the walk above:
+
+- `workspace` (init, materialize, status, migrate-gr1 from a gr1 gripspace), `lane` (create, enter, exit, current, lease), `store` (init, snapshot, log, diff, checkout), `exec run`, `repo status`, `sync status`, `review create-project`.
+- Lanes are independent clones: two lanes, or two agents, never share refs, an index, or a working tree.
+- A lane commit that commits nothing anywhere refuses loudly instead of reporting success.
+
+Not there yet:
+
+- The full walk with **remote** PRs (`gr2 push`, `gr2 pr create`) is documented in `--help` but was not exercised in a clean environment for this README; treat those two as alpha.
+- `gr2 --help` and some verb output still say "prototype" in places; the wording is being cleaned up as verbs land.
+- The Rust `gr` (gr1) still owns `spawn`, `fleet`, and `manifest` until their gr2 ports land. Everything else — workspace sync, lanes, the multi-repo slice, its review — is gr2's job; if a verb is missing or wrong there, that is a bug worth reporting, not a reason to reach for gr1.
+
+## Commands
+
+| Group | Verbs |
+|---|---|
+| `workspace` | init, init-from-topology, materialize, status, convert-clone, detect-gr1, migrate-gr1, migrate-lane-state, bootstrap-gr1 |
+| `spec` | show, validate |
+| `lane` | create, enter, exit, current, resolve, bind, lease |
+| (top level) | branch, add, commit, push, prune |
+| `sync` | status, run |
+| `pr` | create, status, checks, merge |
+| `review` | open, close, checkout-pr, run, requirements, bind, verify, rebind, create-project |
+| `exec` | status, run |
+| `repo` | status, hooks, hook-run, projection-run |
+| `store` | init, snapshot, log, diff, checkout |
+| `target`, `config`, `plan`, `apply` | stored PR target; config overlays; show/apply the materialization plan |
+
+## Overlay substrate
+
+gr2 also carries the config-overlay substrate (capture, compose, and materialize configuration layers over a workspace): see [docs/OVERLAY-SUBSTRATE.md](docs/OVERLAY-SUBSTRATE.md).
+
+## Development
+
+```bash
+pip install -e "gr2[dev]"    # from the repository root
+cd gr2 && pytest             # the gr2 suite (tests + overlay tests)
+cd gr2 && ruff check .       # lint, same config as CI
+```

{gitgrip-2.0.0a1 → gitgrip-2.0.0a3}/gitgrip.egg-info/SOURCES.txt

@@ -84,6 +84,7 @@ python_cli/spec_apply.py
 python_cli/staging_cleanup.py
 python_cli/syncops.py
 python_cli/target.py
+python_cli/workspace_guidance.py
 python_cli/workspace_snapshot.py
 tests/test_add.py
 tests/test_agent_manifest_overlay_source.py
@@ -91,6 +92,7 @@ tests/test_app_event_outcomes.py
 tests/test_apply_convergence.py
 tests/test_branch.py
 tests/test_channel_bridge.py
+tests/test_cli_adapter_error_boundary.py
 tests/test_clone_materialization.py
 tests/test_commit.py
 tests/test_config_base_path_guard.py
@@ -103,10 +105,14 @@ tests/test_event_log_integrity.py
 tests/test_event_outcome_policy.py
 tests/test_events.py
 tests/test_events_torn_line.py
+tests/test_exec_apostrophe_and_oserror.py
+tests/test_exec_single_string_and_materialize_plan.py
 tests/test_execops.py
 tests/test_failure_event_outcome.py
+tests/test_first_five_minutes.py
 tests/test_foreground_launch_runtime.py
 tests/test_git_review.py
+tests/test_gr1_first_run_guidance.py
 tests/test_gr2_packaging.py
 tests/test_gr2_review_receipt.py
 tests/test_grip_cli.py
@@ -117,8 +123,10 @@ tests/test_hook_events.py
 tests/test_hook_hardening.py
 tests/test_jsonl_store.py
 tests/test_lane_create_fork_base_cli.py
+tests/test_lane_create_refuses_own_branch.py
 tests/test_lane_lease_show_json.py
 tests/test_lane_lifecycle_safety.py
+tests/test_lane_repo_paths_and_all_skipped.py
 tests/test_lane_toml_serialization.py
 tests/test_launch_primitive.py
 tests/test_m2_overlay_hindsight.py
@@ -129,6 +137,7 @@ tests/test_merge_evidence.py
 tests/test_merge_parent_verification.py
 tests/test_migration.py
 tests/test_migration_overlay_compatibility.py
+tests/test_migration_unadopted_notice.py
 tests/test_no_bare_python_cli_imports.py
 tests/test_null_current_lane_refusal.py
 tests/test_open_gr_enter.py
@@ -165,6 +174,7 @@ tests/test_propagation_daemon.py
 tests/test_propagation_state_machine.py
 tests/test_prune.py
 tests/test_push.py
+tests/test_readme_verbs_exist.py
 tests/test_repo_status_linked_worktree.py
 tests/test_repo_status_schema_version.py
 tests/test_repo_status_symlinked_git_dir.py
@@ -184,6 +194,7 @@ tests/test_review_run_rerun_and_refusal_receipt.py
 tests/test_review_runners.py
 tests/test_review_verify_inside.py
 tests/test_rmtree_or_refuse.py
+tests/test_single_repo_cwd_refusal.py
 tests/test_snapshot_id_prefix_resolution.py
 tests/test_spec_apply_event_outcomes.py
 tests/test_sprint21_sync_platform.py
@@ -208,4 +219,5 @@ tests/test_workspace_convert_clone.py
 tests/test_workspace_edit_lease_cap.py
 tests/test_workspace_identity_boundary.py
 tests/test_workspace_init_from_topology.py
+tests/test_workspace_init_local_repos.py
 tests/test_workspace_snapshot.py

{gitgrip-2.0.0a1 → gitgrip-2.0.0a3}/prototypes/lane_workspace_prototype.py

@@ -195,6 +195,7 @@ class LaneTransitionOutcome:
     current_lane: str | None
     state_path: Path
     status: str = "ok"
+    repo_paths: dict[str, str] = dataclasses.field(default_factory=dict)
 
     @property
     def exit_code(self) -> int:
@@ -208,6 +209,7 @@ class LaneTransitionOutcome:
             "previous_lane": self.previous_lane,
             "current_lane": self.current_lane,
             "state_path": str(self.state_path),
+            "repo_paths": dict(self.repo_paths),
         }
 
 
@@ -921,6 +923,97 @@ def _validate_bound_worktree(bind_path: Path, workspace_root: Path) -> tuple[str
     return head, branch
 
 
+#: How long the origin may take to report its default branch before the answer is
+#: "cannot tell". Generous for a symref read, and short enough that an origin which
+#: accepts and never replies cannot block `lane create` with no output. Without it,
+#: an offline laptop or a blackholed origin hangs the verb where it used to create a
+#: lane without any network call at all.
+_LS_REMOTE_TIMEOUT_SECONDS = 5.0
+
+
+def _origin_default_branch(repo_path: Path, url: str | None = None) -> str | None:
+    """The repo's integration branch, or None when it cannot be determined.
+
+    A clone records it as `origin/HEAD`. That symref is ABSENT in a clone made
+    before the remote had any refs — which is the normal state of a repo cloned
+    empty and pushed later, and it is exactly the state in which a lane created on
+    the default branch looks harmless. So when the local record is missing, ask the
+    origin itself (`ls-remote --symref`), which is the same remote the lane is about
+    to clone from anyway. A remote that cannot be reached gives None: "cannot tell"
+    is never allowed to become a refusal. Unreachable includes UNANSWERED — the call
+    is bounded, and an expiry is None on the same channel as any other git failure
+    rather than an exception the caller has to remember to catch separately.
+    """
+    proc = gitops.git(repo_path, "rev-parse", "--abbrev-ref", "origin/HEAD")
+    if proc.returncode == 0:
+        ref = proc.stdout.strip()
+        if ref.startswith("origin/"):
+            return ref.split("/", 1)[1]
+    if not url:
+        return None
+    remote = gitops.git(
+        repo_path, "ls-remote", "--symref", url, "HEAD", timeout=_LS_REMOTE_TIMEOUT_SECONDS
+    )
+    if remote.returncode != 0:
+        # A git that never returned is the same answer as a git that refused:
+        # "cannot tell". The bound above is what makes that reachable at all — an
+        # origin that accepts and says nothing used to block the verb outright.
+        return None
+    for line in remote.stdout.splitlines():
+        if line.startswith("ref:") and line.rstrip().endswith("HEAD"):
+            ref = line.split()[1]
+            # Strip the PREFIX, never split on every slash: a default branch whose
+            # name contains one (`release/1.x`) came back as its last segment, so the
+            # guard compared the requested branch against a string the origin never
+            # reported and the no-isolation lane was created in silence.
+            if not ref.startswith("refs/heads/"):
+                return None
+            return ref.removeprefix("refs/heads/")
+    return None
+
+
+def _lane_branch_refusal(workspace_root: Path, spec: dict, repo: str, branch: str) -> str | None:
+    """The one sentence that refuses a lane branch with no isolation, or None.
+
+    A lane is the isolation primitive. A lane whose branch IS the repository's own
+    branch has no isolation at all: work committed there and pushed with `gr2 push`
+    lands on the branch the lane was supposed to be forked from, and the first
+    refusal arrived at `pr create` — after the remote had already been written
+    (measured on the released 2.0.0a2: `lane create --branch main`, push exit 0
+    "Pushed main", then `pr create` exit 1 "head branch main is the same as base
+    branch main"). Nothing refused at the point the choice was made.
+
+    The comparison is against what is CHECKED OUT here and what the origin says its
+    default is. A repo with no local checkout, or one whose origin cannot be
+    reached, is skipped rather than refused: this guard may not invent a conflict it
+    cannot see.
+    """
+    entry = next((row for row in spec.get("repos", []) if row.get("name") == repo), None)
+    if entry is None:
+        return None
+    rel = entry.get("path")
+    if not rel:
+        return None
+    checkout = workspace_root / str(rel)
+    if not gitops.is_git_repo(checkout):
+        return None
+    matched: str | None = None
+    if branch == gitops.current_branch(checkout):
+        matched = f"the branch checked out at {rel}"
+    else:
+        default = _origin_default_branch(checkout, str(entry.get("url") or "") or None)
+        if default and branch == default:
+            matched = f"the repo's integration branch ({default})"
+    if matched is None:
+        return None
+    return (
+        f"lane branch '{branch}' for repo '{repo}' is {matched}: a lane forked from the branch it will "
+        f"land on has no isolation, and a push would go straight to '{branch}'. Pass a lane branch that is "
+        f"neither the repo's checked-out nor its integration branch (e.g. feat/<name>), or use --bind to "
+        f"label an existing worktree."
+    )
+
+
 def create_lane(args: argparse.Namespace) -> int:
     workspace_root = args.workspace_root.resolve()
     validate_lane_path_component(args.owner_unit, "owner_unit")
@@ -961,6 +1054,14 @@ def create_lane(args: argparse.Namespace) -> int:
         branch_map = {repos[0]: branch}
     else:
         branch_map = parse_branch_arg(args.branch, repos)
+        # A materialized lane's branch may not be the repo's own branch: the lane
+        # would have no isolation and its push would land on the integration
+        # branch. Refused HERE, where the choice is made, rather than at the first
+        # `pr create` after the remote had been written.
+        for _repo in repos:
+            refusal = _lane_branch_refusal(workspace_root, spec, _repo, branch_map[_repo])
+            if refusal:
+                raise SystemExit(refusal)
 
     # Fork base: record what the caller supplies, do not derive.
     # Each entry names a repo IN the lane and carries a 40-hex integration-branch tip.
@@ -1038,6 +1139,18 @@ def create_lane(args: argparse.Namespace) -> int:
         (lane_root / "context").mkdir()
         atomic_replace_text(metadata_path, expected)
     print(metadata_path)
+    # The human line names where the actor works, per repo, absolute: a
+    # materialized lane's repos live under its lane tree, a bound lane's one
+    # repo IS the bound worktree. (The stranger's F2 finding: enter/create
+    # used to point at lane.toml only, so the actor never learned where the
+    # lane's repos are.)
+    if lane_kind == "bound" and bound_worktree:
+        for repo in repos:
+            print(f"{repo}: {bound_worktree}")
+    else:
+        lane_root = lane_dir(workspace_root, args.owner_unit, args.lane_name)
+        for repo in repos:
+            print(f"{repo}: {lane_root / 'repos' / repo}")
     return 0
 
 
@@ -1222,6 +1335,17 @@ def enter_lane(args: argparse.Namespace) -> LaneTransitionOutcome:
                 previous_lane = current.get("lane_name")
                 previous.insert(0, current)
 
+        lane_kind = lane_doc.get("lane_kind", "materialized")
+        if lane_kind == "bound" and lane_doc.get("bound_worktree"):
+            repo_paths = {
+                r: str(lane_doc["bound_worktree"]) for r in lane_doc.get("repos", [])
+            }
+        else:
+            lane_root = lane_dir(workspace_root, args.owner_unit, args.lane_name)
+            repo_paths = {
+                r: str(lane_root / "repos" / r) for r in lane_doc.get("repos", [])
+            }
+
         deduped: list[dict] = []
         seen: set[tuple[str, str]] = set()
         for item in previous:
@@ -1237,6 +1361,7 @@ def enter_lane(args: argparse.Namespace) -> LaneTransitionOutcome:
                 "lane_name": args.lane_name,
                 "lane_type": lane_doc["lane_type"],
                 "repos": lane_doc.get("repos", []),
+                "repo_paths": repo_paths,
                 "actor": args.actor,
                 "entered_at": now_utc(),
             },
@@ -1270,7 +1395,10 @@ def enter_lane(args: argparse.Namespace) -> LaneTransitionOutcome:
                 "timestamp": event["timestamp"],
             },
         )
-    return LaneTransitionOutcome("enter", args.owner_unit, previous_lane, args.lane_name, path)
+    return LaneTransitionOutcome(
+        "enter", args.owner_unit, previous_lane, args.lane_name, path,
+        repo_paths=repo_paths,
+    )
 
 
 def exit_lane(args: argparse.Namespace) -> LaneTransitionOutcome: