gitgrip 1.5.0__py3-none-any.whl

gr2/python_cli/migration.py

@@ -0,0 +1,985 @@
+from __future__ import annotations
+
+import json
+import hashlib
+import os
+import re
+import shutil
+import stat
+import tempfile
+import tomllib
+import contextlib
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+import yaml
+
+from . import grip
+from .gitops import git
+from gr2.prototypes import lane_workspace_prototype as lane_proto
+from gr2.prototypes import repo_maintenance_prototype as repo_proto
+
+
+def _transaction_phase_hook(_phase: str) -> None:
+    """Inert production seam; scratch interruption tests replace this callable."""
+    return None
+
+
+def gr1_manifest_path(workspace_root: Path) -> Path:
+    return workspace_root / ".gitgrip" / "spaces" / "main" / "gripspace.yml"
+
+
+def gr1_agents_path(workspace_root: Path) -> Path:
+    return workspace_root / ".gitgrip" / "agents.toml"
+
+
+def gr1_state_paths(workspace_root: Path) -> dict[str, Path]:
+    gitgrip = workspace_root / ".gitgrip"
+    return {
+        "state_json": gitgrip / "state.json",
+        "sync_state_json": gitgrip / "sync-state.json",
+        "griptrees_json": gitgrip / "griptrees.json",
+        "manifest_yaml": gr1_manifest_path(workspace_root),
+    }
+
+
+def detect_gr1_workspace(workspace_root: Path) -> dict[str, object]:
+    manifest_path = gr1_manifest_path(workspace_root)
+    if not manifest_path.exists():
+        return {
+            "detected": False,
+            "workspace_root": str(workspace_root),
+            "reason": f"missing {manifest_path}",
+        }
+
+    manifest = yaml.safe_load(manifest_path.read_text()) or {}
+    repos = manifest.get("repos", {}) or {}
+    agents_doc = _load_agents_doc(workspace_root)
+    agent_names = sorted(((agents_doc.get("agents") or {}) or {}).keys())
+    reference_repos = sorted(name for name, repo in repos.items() if bool((repo or {}).get("reference", False)))
+    writable_repos = sorted(name for name in repos.keys() if name not in reference_repos)
+    state_paths = gr1_state_paths(workspace_root)
+
+    return {
+        "detected": True,
+        "workspace_root": str(workspace_root),
+        "manifest_path": str(manifest_path),
+        "repo_count": len(repos),
+        "reference_repo_count": len(reference_repos),
+        "agent_count": len(agent_names),
+        "repos": sorted(repos.keys()),
+        "reference_repos": reference_repos,
+        "writable_repos": writable_repos,
+        "agents": agent_names,
+        "state_files": {key: str(path) for key, path in state_paths.items() if path.exists()},
+    }
+
+
+def migrate_gr1_workspace(workspace_root: Path, *, force: bool = False) -> dict[str, object]:
+    detection = detect_gr1_workspace(workspace_root)
+    if not detection["detected"]:
+        raise SystemExit(detection["reason"])
+
+    grip_dir = workspace_root / ".grip"
+    spec_path = grip_dir / "workspace_spec.toml"
+    if spec_path.exists() and not force:
+        raise SystemExit(f"refusing to overwrite existing gr2 workspace spec: {spec_path}")
+
+    manifest = yaml.safe_load(Path(str(detection["manifest_path"])).read_text()) or {}
+    agents_doc = _load_agents_doc(workspace_root)
+    compiled = compile_gr1_to_workspace_spec(workspace_root, manifest, agents_doc)
+
+    grip_dir.mkdir(parents=True, exist_ok=True)
+    spec_path.write_text(render_workspace_spec(compiled))
+
+    migration_dir = grip_dir / "migrations" / "gr1"
+    migration_dir.mkdir(parents=True, exist_ok=True)
+    snapshots = preserve_gr1_state(workspace_root, migration_dir)
+    summary_path = migration_dir / "migration-summary.json"
+    summary = {
+        "source": "gr1",
+        "workspace_root": str(workspace_root),
+        "workspace_spec_path": str(spec_path),
+        "repo_count": len(compiled["repos"]),
+        "unit_count": len(compiled["units"]),
+        "snapshots": snapshots,
+    }
+    summary_path.write_text(json.dumps(summary, indent=2) + "\n")
+
+    return {
+        **summary,
+        "units": [unit["name"] for unit in compiled["units"]],
+        "repos": [repo["name"] for repo in compiled["repos"]],
+    }
+
+
+def _compiled_gr1_spec(workspace_root: Path) -> tuple[Path, bytes, bytes, dict[str, object]]:
+    """Compile and parse the generated bytes before a caller mutates state."""
+    manifest_path = gr1_manifest_path(workspace_root)
+    if not manifest_path.is_file():
+        raise SystemExit(f"missing canonical gripspace manifest: {manifest_path}")
+    manifest_bytes = manifest_path.read_bytes()
+    try:
+        manifest = yaml.safe_load(manifest_bytes) or {}
+        if not isinstance(manifest, dict) or not isinstance(manifest.get("repos", {}), dict):
+            raise ValueError("canonical gripspace manifest repos must be a mapping")
+        agents_doc = _load_agents_doc(workspace_root)
+        if not isinstance(agents_doc, dict):
+            raise ValueError("gr1 agents manifest must be a mapping")
+        compiled = compile_gr1_to_workspace_spec(workspace_root, manifest, agents_doc)
+        spec_bytes = render_workspace_spec(compiled).encode()
+        tomllib.loads(spec_bytes.decode())
+    except (yaml.YAMLError, OSError, TypeError, ValueError, KeyError, tomllib.TOMLDecodeError) as exc:
+        raise SystemExit(f"cannot compile canonical gripspace manifest: {exc}") from exc
+    return manifest_path, manifest_bytes, spec_bytes, compiled
+
+
+def bootstrap_gr1_workspace(workspace_root: Path) -> dict[str, object]:
+    """Compile the authoritative gr1 manifest and make its gr2 object store usable.
+
+    This is intentionally narrower than migration: it does not snapshot mutable
+    gr1 state or materialize repositories.  It first builds and parses the
+    exact WorkspaceSpec bytes, so malformed source cannot create ``.grip``.
+    The only persistent result is the git-native grip store plus that generated
+    spec.  Repeating the operation accepts only the identical compiled bytes.
+    """
+    manifest_path, manifest_bytes, spec_bytes, compiled = _compiled_gr1_spec(workspace_root)
+
+    grip_dir = workspace_root / ".grip"
+    spec_path = grip_dir / "workspace_spec.toml"
+    git_dir = grip_dir / ".git"
+    for path, label in ((grip_dir, ".grip"), (git_dir, ".grip/.git"), (spec_path, ".grip/workspace_spec.toml")):
+        _refuse_symlink(path, label)
+
+    grip_dir_existed = grip_dir.exists()
+    git_dir_existed = git_dir.exists()
+    spec_existed = spec_path.exists()
+    if grip_dir.exists() and not grip_dir.is_dir():
+        raise SystemExit(f"refusing bootstrap: {grip_dir} is not a directory")
+    if git_dir.is_file():
+        raise SystemExit(f"refusing bootstrap: {git_dir} is not a directory")
+    if git_dir.is_dir():
+        probe = git(grip_dir, "rev-parse", "--is-inside-work-tree")
+        if probe.returncode != 0 or probe.stdout.strip() != "true":
+            raise SystemExit(f"refusing bootstrap: {grip_dir} is not a valid git object store")
+
+    if spec_path.exists() and spec_path.read_bytes() != spec_bytes:
+        raise SystemExit(f"refusing bootstrap: existing generated spec differs: {spec_path}")
+
+    already_initialized = git_dir.is_dir() and spec_path.exists()
+    if not already_initialized:
+        try:
+            grip.grip_init(workspace_root)
+            if not spec_path.exists():
+                _atomic_write(spec_path, spec_bytes)
+        except grip.GripInitError as exc:
+            _rollback_bootstrap(grip_dir, git_dir, spec_path, grip_dir_existed, git_dir_existed, spec_existed)
+            raise SystemExit(str(exc)) from exc
+        except BaseException:
+            _rollback_bootstrap(grip_dir, git_dir, spec_path, grip_dir_existed, git_dir_existed, spec_existed)
+            raise
+
+    return {
+        "status": "already_initialized" if already_initialized else "initialized",
+        "workspace_root": str(workspace_root),
+        "manifest_path": str(manifest_path),
+        "workspace_spec_path": str(spec_path),
+        "grip_repo_path": str(grip_dir),
+        "repo_count": len(compiled["repos"]),
+        "unit_count": len(compiled["units"]),
+        "manifest_sha256": hashlib.sha256(manifest_bytes).hexdigest(),
+        "workspace_spec_sha256": hashlib.sha256(spec_bytes).hexdigest(),
+    }
+
+
+def regenerate_gr1_workspace(workspace_root: Path, *, expected_spec_sha256: str, receipt_path: Path) -> dict[str, object]:
+    """Atomically replace only an already-generated spec after strict binding."""
+    workspace_root = workspace_root.resolve()
+    if not isinstance(expected_spec_sha256, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_spec_sha256):
+        raise SystemExit("--expected-spec-sha256 must be a lowercase 64-hex SHA-256")
+    manifest_path, manifest_bytes, candidate, compiled = _compiled_gr1_spec(workspace_root)
+    agents_path = gr1_agents_path(workspace_root)
+    _refuse_authority_symlinks(workspace_root, manifest_path, "canonical gripspace manifest")
+    _refuse_authority_symlinks(workspace_root, agents_path, "gr1 agents manifest")
+    agents_bytes = agents_path.read_bytes()
+    grip_dir = workspace_root / ".grip"
+    spec_path = grip_dir / "workspace_spec.toml"
+    git_dir = grip_dir / ".git"
+    for path, label in ((grip_dir, ".grip"), (git_dir, ".grip/.git"), (spec_path, ".grip/workspace_spec.toml"), (grip_dir / "state", ".grip/state")):
+        _refuse_symlink(path, label)
+    if not git_dir.is_dir() or not spec_path.is_file():
+        raise SystemExit("regeneration requires an initialized object store and regular generated spec")
+    _refuse_active_lane_state(workspace_root)
+    _require_clean_regeneration_store(grip_dir)
+    _recover_or_refuse_prepared_marker(receipt_path, workspace_root, spec_path)
+    _require_new_receipt_target(receipt_path)
+
+    lock_path = grip_dir / "state" / "workspace_spec_regeneration.lock"
+    with _regeneration_lock(lock_path):
+        # The compare occurs inside the critical section, so two regenerators
+        # cannot both accept the same old bytes and silently overwrite each other.
+        # A lane can become active while a regenerator waits for the lock, so the
+        # active-lane guard is re-checked HERE, after acquisition, not only before
+        # (the seam lets a test activate a lane at exactly this moment).
+        _transaction_phase_hook("lock_acquired")
+        _refuse_active_lane_state(workspace_root)
+        locked_manifest, locked_manifest_bytes, locked_candidate, locked_compiled = _compiled_gr1_spec(workspace_root)
+        locked_agents = gr1_agents_path(workspace_root)
+        _refuse_authority_symlinks(workspace_root, locked_manifest, "canonical gripspace manifest")
+        _refuse_authority_symlinks(workspace_root, locked_agents, "gr1 agents manifest")
+        locked_agents_bytes = locked_agents.read_bytes()
+        if locked_manifest != manifest_path or locked_manifest_bytes != manifest_bytes or locked_agents_bytes != agents_bytes or locked_candidate != candidate:
+            raise SystemExit("regeneration source authority changed while awaiting lock")
+        old = spec_path.read_bytes()
+        old_hash = hashlib.sha256(old).hexdigest()
+        if old_hash != expected_spec_sha256:
+            raise SystemExit(f"expected old spec hash {expected_spec_sha256}, observed {old_hash}")
+        if old == candidate:
+            raise SystemExit("regeneration candidate is identical to existing generated spec")
+        head = git(grip_dir, "rev-parse", "HEAD").stdout.strip()
+        lane_snapshot = _lane_snapshot(workspace_root)
+        status_snapshot = _store_status(grip_dir)
+        sidecar_path = _sidecar_path(receipt_path, old_hash)
+        _require_new_receipt_target(sidecar_path)
+        _atomic_write(sidecar_path, old)
+        payload = {
+            "schema": "gr2-workspace-regeneration/v2",
+            "status": "regenerated",
+            "workspace_root": str(workspace_root),
+            "manifest_path": str(manifest_path),
+            "workspace_spec_path": str(spec_path),
+            "grip_repo_path": str(grip_dir),
+            "manifest_sha256": hashlib.sha256(manifest_bytes).hexdigest(),
+            "agents_sha256": hashlib.sha256(agents_bytes).hexdigest(),
+            "expected_old_spec_sha256": expected_spec_sha256,
+            "observed_old_spec_sha256": old_hash,
+            "new_spec_sha256": hashlib.sha256(candidate).hexdigest(),
+            "sidecar_relative_path": sidecar_path.name,
+            "sidecar_sha256": old_hash,
+            "object_store_head": head,
+            "object_store_status": status_snapshot,
+            "lane_snapshot": lane_snapshot,
+            "operations": ["atomic_workspace_spec_replace"],
+            "materialization": False,
+            "repo_count": len(compiled["repos"]),
+            "unit_count": len(compiled["units"]),
+        }
+        marker_path = _prepared_marker_path(receipt_path)
+        _require_new_receipt_target(marker_path)
+        marker = {"schema": "gr2-workspace-regeneration-prepared/v1", "phase": "prepared", "forward_receipt": receipt_path.name, "payload": payload}
+        _atomic_write(marker_path, (json.dumps(marker, indent=2, sort_keys=True) + "\n").encode())
+        _transaction_phase_hook("marker_durable")
+        try:
+            _atomic_write(spec_path, candidate)
+            _transaction_phase_hook("spec_replaced")
+            if hashlib.sha256(spec_path.read_bytes()).hexdigest() != hashlib.sha256(candidate).hexdigest():
+                raise SystemExit("atomic generated spec replacement did not bind candidate bytes")
+            if git(grip_dir, "rev-parse", "HEAD").stdout.strip() != head:
+                raise SystemExit("regeneration changed object-store HEAD")
+            _write_new_receipt(receipt_path, payload)
+            _transaction_phase_hook("receipt_durable")
+            marker_path.unlink()
+            _transaction_phase_hook("marker_cleared")
+        except BaseException:
+            try:
+                _atomic_write(spec_path, old)
+                sidecar_path.unlink(missing_ok=True)
+                marker_path.unlink(missing_ok=True)
+                receipt_path.unlink(missing_ok=True)
+            except BaseException as rollback_error:
+                raise SystemExit(f"regeneration publication failed and restore failed: {rollback_error}") from rollback_error
+            raise
+        return payload
+
+
+def _iter_legacy_lane_dirs(workspace_root: Path) -> list[tuple[str, str, Path]]:
+    """Legacy lane trees: ``workspace_root/agents/<unit>/lanes/<lane>/``.
+
+    The unit HOME (``agents/<unit>/home/``) is deliberately NOT enumerated --
+    it is unit identity, not lane state, and stays where the workspace spec
+    places it. Only the ``lanes/`` subtree moves.
+    """
+    legacy_root = workspace_root / "agents"
+    out: list[tuple[str, str, Path]] = []
+    if not legacy_root.is_dir():
+        return out
+    for unit_dir in sorted(legacy_root.iterdir()):
+        lanes_parent = unit_dir / "lanes"
+        if not lanes_parent.is_dir():
+            continue
+        for lane in sorted(lanes_parent.iterdir()):
+            if lane.is_dir():
+                out.append((unit_dir.name, lane.name, lane))
+    return out
+
+
+def _refuse_active_legacy_lane_state(workspace_root: Path) -> None:
+    """Refuse migration while a lane is entered or holds a live lease.
+
+    ``_refuse_active_lane_state`` reads the NEW ``.grip/state/lanes`` path;
+    migration runs BEFORE the move, so the live state is still at the OLD path
+    and must be judged there. current_lane pointers already live at their final
+    ``.grip/state/current_lane`` home (never moved), so that half is shared.
+    """
+    current_root = workspace_root / ".grip" / "state" / "current_lane"
+    if current_root.is_dir():
+        for current_path in current_root.glob("*.json"):
+            _refuse_symlink(current_path, f"{current_path.relative_to(workspace_root)}")
+            try:
+                current = json.loads(current_path.read_text())
+            except (OSError, json.JSONDecodeError) as exc:
+                raise SystemExit(f"lane-state migration cannot read lane state: {current_path}: {exc}") from exc
+            if current.get("current"):
+                raise SystemExit("lane-state migration refuses active lanes")
+    for leases_path in (workspace_root / "agents").glob("*/lanes/*/leases.json"):
+        _refuse_symlink(leases_path, f"{leases_path.relative_to(workspace_root)}")
+        try:
+            leases = json.loads(leases_path.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            raise SystemExit(f"lane-state migration cannot read lane leases: {leases_path}: {exc}") from exc
+        if leases:
+            raise SystemExit("lane-state migration refuses active lane leases")
+
+
+def migrate_lane_state(workspace_root: Path, *, receipt_path: Path) -> dict[str, object]:
+    """Carry legacy ``agents/<unit>/lanes/<lane>/`` trees to
+    ``.grip/state/lanes/<unit>/<lane>/`` ONCE, recording a receipt that names
+    every tree moved (unit, lane, file count) so what the move relocates is
+    explicit -- the receipt is the record of what would be lost if the new home
+    were ever cleared (the ``.grip`` overlay-reset durability follow-on).
+
+    Two-pass and no-clobber: every destination is checked BEFORE anything moves,
+    so a lane already present at the new path refuses the whole migration rather
+    than leaving a half-moved workspace. Idempotent across runs: once the legacy
+    trees are gone a fresh-receipt re-run is a zero-move no-op.
+    """
+    workspace_root = workspace_root.resolve()
+    _require_new_receipt_target(receipt_path)
+    _refuse_active_legacy_lane_state(workspace_root)
+
+    dest_root = lane_proto.lane_state_root(workspace_root)
+    legacy = _iter_legacy_lane_dirs(workspace_root)
+
+    plan: list[tuple[str, str, Path, Path]] = []
+    conflicts: list[str] = []
+    for unit, lane, src in legacy:
+        _refuse_symlink(src, f"agents/{unit}/lanes/{lane}")
+        dest = dest_root / unit / lane
+        if dest.exists():
+            conflicts.append(str(dest.relative_to(workspace_root)))
+        else:
+            plan.append((unit, lane, src, dest))
+    if conflicts:
+        raise SystemExit(
+            "lane-state migration refuses to overwrite existing destinations "
+            f"(both layouts hold these lanes, reconcile by hand): {conflicts}"
+        )
+
+    moved: list[dict[str, object]] = []
+    for unit, lane, src, dest in plan:
+        file_count = sum(1 for p in src.rglob("*") if p.is_file())
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src), str(dest))
+        moved.append(
+            {
+                "unit": unit,
+                "lane": lane,
+                "source": f"agents/{unit}/lanes/{lane}",
+                "dest": str(dest.relative_to(workspace_root)),
+                "files": file_count,
+            }
+        )
+
+    payload: dict[str, object] = {
+        "schema": "gr2-lane-state-migration/v1",
+        "status": "migrated",
+        "workspace_root": str(workspace_root),
+        "from": "agents/<unit>/lanes/<lane>",
+        "to": ".grip/state/lanes/<unit>/<lane>",
+        "moved": moved,
+        "count": len(moved),
+    }
+    _write_new_receipt(receipt_path, payload)
+    return payload
+
+
+def _prepared_marker_path(receipt_path: Path) -> Path:
+    return receipt_path.parent / f"{receipt_path.name}.prepared.json"
+
+
+def _recover_or_refuse_prepared_marker(receipt_path: Path, workspace_root: Path, spec_path: Path) -> None:
+    marker_path = _prepared_marker_path(receipt_path)
+    _refuse_symlink(marker_path, "prepared regeneration marker")
+    if not marker_path.exists():
+        return
+    try:
+        marker = json.loads(marker_path.read_text())
+        payload = marker["payload"]
+        if marker.get("schema") != "gr2-workspace-regeneration-prepared/v1" or marker.get("phase") != "prepared" or marker.get("forward_receipt") != receipt_path.name or payload.get("workspace_root") != str(workspace_root):
+            raise ValueError("marker binding is invalid")
+        if receipt_path.exists():
+            raise ValueError("receipt already exists")
+        if hashlib.sha256(spec_path.read_bytes()).hexdigest() != payload.get("new_spec_sha256"):
+            raise ValueError("generated spec does not match prepared new hash")
+        _write_new_receipt(receipt_path, payload)
+        marker_path.unlink()
+    except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"pending regeneration marker requires manual resolution: {marker_path}: {exc}") from exc
+
+
+def rollback_gr1_workspace(
+    workspace_root: Path,
+    *,
+    rollback_receipt_path: Path,
+    expected_current_spec_sha256: str,
+    receipt_path: Path,
+) -> dict[str, object]:
+    """Restore one receipt-bound generated spec without materializing repos."""
+    if not isinstance(expected_current_spec_sha256, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_current_spec_sha256):
+        raise SystemExit("--expected-current-spec-sha256 must be a lowercase 64-hex SHA-256")
+    workspace_root = workspace_root.resolve()
+    grip_dir, spec_path, git_dir = workspace_root / ".grip", workspace_root / ".grip" / "workspace_spec.toml", workspace_root / ".grip" / ".git"
+    for path, label in ((grip_dir, ".grip"), (git_dir, ".grip/.git"), (spec_path, ".grip/workspace_spec.toml"), (rollback_receipt_path, "rollback receipt")):
+        _refuse_symlink(path, label)
+    if not git_dir.is_dir() or not spec_path.is_file() or not rollback_receipt_path.is_file():
+        raise SystemExit("rollback requires an initialized object store, regular generated spec, and regular receipt")
+    _refuse_active_lane_state(workspace_root)
+    _require_clean_regeneration_store(grip_dir)
+    _require_new_receipt_target(receipt_path)
+    receipt = _load_forward_receipt(rollback_receipt_path, workspace_root, grip_dir, spec_path)
+    manifest_path = gr1_manifest_path(workspace_root)
+    agents_path = gr1_agents_path(workspace_root)
+    _refuse_authority_symlinks(workspace_root, manifest_path, "canonical gripspace manifest")
+    _refuse_authority_symlinks(workspace_root, agents_path, "gr1 agents manifest")
+    if not manifest_path.is_file() or hashlib.sha256(manifest_path.read_bytes()).hexdigest() != receipt["manifest_sha256"]:
+        raise SystemExit("rollback manifest binding differs from receipt")
+    if not agents_path.is_file() or hashlib.sha256(agents_path.read_bytes()).hexdigest() != receipt.get("agents_sha256"):
+        raise SystemExit("rollback agents binding differs from receipt")
+    sidecar_path = _bound_sidecar_path(rollback_receipt_path, receipt)
+    _refuse_symlink(sidecar_path, "rollback sidecar")
+    sidecar = sidecar_path.read_bytes()
+    if hashlib.sha256(sidecar).hexdigest() != receipt["sidecar_sha256"] or hashlib.sha256(sidecar).hexdigest() != receipt["observed_old_spec_sha256"]:
+        raise SystemExit("rollback sidecar hash does not match receipt")
+
+    lock_path = grip_dir / "state" / "workspace_spec_regeneration.lock"
+    with _regeneration_lock(lock_path):
+        _refuse_active_lane_state(workspace_root)
+        _refuse_authority_symlinks(workspace_root, manifest_path, "canonical gripspace manifest")
+        _refuse_authority_symlinks(workspace_root, agents_path, "gr1 agents manifest")
+        if hashlib.sha256(manifest_path.read_bytes()).hexdigest() != receipt["manifest_sha256"] or hashlib.sha256(agents_path.read_bytes()).hexdigest() != receipt.get("agents_sha256"):
+            raise SystemExit("rollback source authority changed while awaiting lock")
+        current = spec_path.read_bytes()
+        current_hash = hashlib.sha256(current).hexdigest()
+        if current_hash != expected_current_spec_sha256 or current_hash != receipt["new_spec_sha256"]:
+            raise SystemExit("rollback current spec hash does not match caller and receipt binding")
+        if _lane_snapshot(workspace_root) != receipt["lane_snapshot"]:
+            raise SystemExit("rollback lane or lease state differs from receipt binding")
+        head = git(grip_dir, "rev-parse", "HEAD").stdout.strip()
+        if head != receipt["object_store_head"] or _store_status(grip_dir) != receipt["object_store_status"]:
+            raise SystemExit("rollback object-store binding differs from receipt")
+        try:
+            _atomic_write(spec_path, sidecar)
+            if hashlib.sha256(spec_path.read_bytes()).hexdigest() != receipt["observed_old_spec_sha256"]:
+                raise SystemExit("rollback replacement did not restore receipt sidecar bytes")
+            if git(grip_dir, "rev-parse", "HEAD").stdout.strip() != head:
+                raise SystemExit("rollback changed object-store HEAD")
+        except BaseException:
+            _atomic_write(spec_path, current)
+            raise
+        payload = {
+            "schema": "gr2-workspace-regeneration-rollback/v1",
+            "status": "rolled_back",
+            "workspace_root": str(workspace_root),
+            "rollback_of_receipt_sha256": hashlib.sha256(rollback_receipt_path.read_bytes()).hexdigest(),
+            "rollback_of_receipt": rollback_receipt_path.name,
+            "expected_current_spec_sha256": expected_current_spec_sha256,
+            "restored_spec_sha256": receipt["observed_old_spec_sha256"],
+            "object_store_head": head,
+            "lane_snapshot": receipt["lane_snapshot"],
+            "operations": ["atomic_workspace_spec_restore"],
+            "materialization": False,
+        }
+        try:
+            _write_new_receipt(receipt_path, payload)
+        except BaseException:
+            try:
+                _atomic_write(spec_path, current)
+                receipt_path.unlink(missing_ok=True)
+            except BaseException as compensation_error:
+                raise SystemExit(f"rollback receipt publication failed and compensation failed: {compensation_error}") from compensation_error
+            raise
+        return payload
+
+
+@contextlib.contextmanager
+def _regeneration_lock(lock_path: Path):
+    """Hold the shared state lock. The lock FILE is KEPT across releases: flock
+    binds an inode, and a path that is unlinked and later re-created is a NEW
+    inode, so a concurrent waiter holding the old inode is not excluded at all
+    (measured: a third party acquired while a second still held). Keeping the
+    file -- no unlink, no rmdir -- is the mutual exclusion; a stale lock file is
+    not dirt (it lives under state/, excluded from the clean-store judgment)."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lane_proto.exclusive_lock(lock_path):
+        yield
+
+
+def _require_clean_regeneration_store(grip_dir: Path) -> None:
+    probe = git(grip_dir, "rev-parse", "--is-inside-work-tree")
+    # The .grip store is PLUMBING-ONLY: grip.py writes objects via
+    # hash-object/mktree/commit-tree/update-ref and never checks out HEAD's
+    # tree. So once HEAD is a real commit (e.g. a review commit), every path in
+    # HEAD's tree is absent from the (unused) worktree and `git status
+    # --porcelain` reports it as a deletion. That is the store's NORMAL state,
+    # not dirt -- judging HEAD-vs-worktree here refuses every store that has
+    # ever held a commit. Regeneration only needs to refuse UNTRACKED files it
+    # would clobber, so judge those alone.
+    status = git(grip_dir, "status", "--porcelain", "--untracked-files=all")
+    if probe.returncode != 0 or probe.stdout.strip() != "true" or status.returncode != 0:
+        raise SystemExit("regeneration requires a valid readable object store")
+    # state/ is the lane control plane, not object-store dirt: inactive lane
+    # files and the regeneration lock file legitimately live there. Active lanes
+    # and leases are refused separately by _refuse_active_lane_state; counting an
+    # inactive lane file (or the held lock) as "dirty" here made a valid
+    # regeneration refuse, and made a second regenerator report "dirty" instead
+    # of waiting on the lock. Exclude the subtree; judge the object store only.
+    dirty = [
+        line for line in status.stdout.splitlines()
+        if line.startswith("??")
+        and line != "?? workspace_spec.toml"
+        and not line.startswith("?? state/")
+    ]
+    if dirty:
+        raise SystemExit("regeneration refuses dirty object store outside generated workspace_spec.toml")
+
+
+def _store_status(grip_dir: Path) -> list[str]:
+    status = git(grip_dir, "status", "--porcelain")
+    if status.returncode != 0:
+        raise SystemExit("regeneration requires a readable object-store status")
+    return status.stdout.splitlines()
+
+
+def _lane_snapshot(workspace_root: Path) -> dict[str, object]:
+    """Bind empty/inactive lane state, rather than merely assuming it remains so."""
+    rows: list[dict[str, str]] = []
+    for root, pattern in ((workspace_root / ".grip" / "state" / "current_lane", "*.json"), (lane_proto.lane_state_root(workspace_root), "*/*/leases.json")):
+        if not root.exists():
+            continue
+        for path in sorted(root.glob(pattern)):
+            _refuse_symlink(path, f"{path.relative_to(workspace_root)}")
+            rows.append({"path": str(path.relative_to(workspace_root)), "sha256": hashlib.sha256(path.read_bytes()).hexdigest()})
+    return {"files": rows}
+
+
+def _refuse_active_lane_state(workspace_root: Path) -> None:
+    """Do not change the control plane while a lane or lease can consume it."""
+    state_root = workspace_root / ".grip" / "state"
+    current_root = state_root / "current_lane"
+    if current_root.exists():
+        for current_path in current_root.glob("*.json"):
+            _refuse_symlink(current_path, f"{current_path.relative_to(workspace_root)}")
+            try:
+                current = json.loads(current_path.read_text())
+            except (OSError, json.JSONDecodeError) as exc:
+                raise SystemExit(f"regeneration cannot read lane state: {current_path}: {exc}") from exc
+            if current.get("current"):
+                raise SystemExit("regeneration refuses active lanes")
+    for leases_path in lane_proto.lane_state_root(workspace_root).glob("*/*/leases.json"):
+        _refuse_symlink(leases_path, f"{leases_path.relative_to(workspace_root)}")
+        try:
+            leases = json.loads(leases_path.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            raise SystemExit(f"regeneration cannot read lane leases: {leases_path}: {exc}") from exc
+        if leases:
+            raise SystemExit("regeneration refuses active lane leases")
+
+
+def _require_new_receipt_target(path: Path) -> None:
+    """Receipt artifacts are append-only authority, never overwriteable state."""
+    _refuse_symlink(path.parent, "receipt directory")
+    _refuse_symlink(path, "regeneration receipt")
+    if not path.parent.is_dir():
+        raise SystemExit(f"receipt parent must already exist: {path.parent}")
+    if path.exists():
+        raise SystemExit(f"refusing to overwrite existing receipt artifact: {path}")
+
+
+def _sidecar_path(receipt_path: Path, old_hash: str) -> Path:
+    relative = f"{receipt_path.name}.old-spec-{old_hash}.toml"
+    if Path(relative).is_absolute() or ".." in Path(relative).parts:
+        raise SystemExit("generated receipt sidecar path is unsafe")
+    return receipt_path.parent / relative
+
+
+def _bound_sidecar_path(receipt_path: Path, receipt: dict[str, object]) -> Path:
+    relative = receipt.get("sidecar_relative_path")
+    if not isinstance(relative, str):
+        raise SystemExit("rollback receipt lacks a relative sidecar path")
+    candidate = Path(relative)
+    if candidate.is_absolute() or ".." in candidate.parts or len(candidate.parts) != 1:
+        raise SystemExit("rollback receipt sidecar path is unsafe")
+    return receipt_path.parent / candidate
+
+
+def _write_new_receipt(receipt_path: Path, payload: dict[str, object]) -> None:
+    _require_new_receipt_target(receipt_path)
+    _atomic_write(receipt_path, (json.dumps(payload, indent=2, sort_keys=True) + "\n").encode())
+
+
+def _load_forward_receipt(receipt_path: Path, workspace_root: Path, grip_dir: Path, spec_path: Path) -> dict[str, object]:
+    try:
+        receipt = json.loads(receipt_path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"rollback cannot parse receipt: {exc}") from exc
+    if not isinstance(receipt, dict) or receipt.get("schema") != "gr2-workspace-regeneration/v2":
+        raise SystemExit("rollback receipt is not a successful regeneration receipt")
+    required = ("workspace_root", "workspace_spec_path", "grip_repo_path", "manifest_sha256", "object_store_head", "object_store_status", "lane_snapshot", "observed_old_spec_sha256", "new_spec_sha256", "sidecar_sha256", "materialization")
+    if any(key not in receipt for key in required) or receipt["materialization"] is not False:
+        raise SystemExit("rollback receipt is missing required immutable bindings")
+    if receipt["workspace_root"] != str(workspace_root) or receipt["workspace_spec_path"] != str(spec_path) or receipt["grip_repo_path"] != str(grip_dir):
+        raise SystemExit("rollback receipt workspace binding differs from requested workspace")
+    if not all(isinstance(receipt[key], str) and re.fullmatch(r"[0-9a-f]{64}", receipt[key]) for key in ("manifest_sha256", "observed_old_spec_sha256", "new_spec_sha256", "sidecar_sha256")):
+        raise SystemExit("rollback receipt has invalid SHA-256 bindings")
+    return receipt
+
+
+def _atomic_write(path: Path, content: bytes) -> None:
+    """Replace one generated control-plane file without exposing partial TOML."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, raw_temp_path = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temp_path = Path(raw_temp_path)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(temp_path, path)
+        directory_fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    except BaseException:
+        temp_path.unlink(missing_ok=True)
+        raise
+
+
+def _refuse_symlink(path: Path, label: str) -> None:
+    """Inspect the entry itself, never the target an attacker could redirect."""
+    try:
+        mode = path.lstat().st_mode
+    except FileNotFoundError:
+        return
+    if stat.S_ISLNK(mode):
+        raise SystemExit(f"refusing bootstrap: {label} must not be a symlink")
+
+
+def _refuse_authority_symlinks(workspace_root: Path, path: Path, label: str) -> None:
+    """Authority must stay physically below the canonical workspace root."""
+    root = workspace_root.resolve()
+    try:
+        relative = path.relative_to(root)
+    except ValueError as exc:
+        raise SystemExit(f"refusing regeneration: {label} escapes workspace") from exc
+    current = root
+    _refuse_symlink(current, "workspace root")
+    for part in relative.parts:
+        current = current / part
+        _refuse_symlink(current, label)
+
+
+def _rollback_bootstrap(
+    grip_dir: Path,
+    git_dir: Path,
+    spec_path: Path,
+    grip_dir_existed: bool,
+    git_dir_existed: bool,
+    spec_existed: bool,
+) -> None:
+    """Remove only control-plane entries created by this bootstrap attempt."""
+    for path, label in ((grip_dir, ".grip"), (git_dir, ".grip/.git"), (spec_path, ".grip/workspace_spec.toml")):
+        _refuse_symlink(path, label)
+    if not spec_existed and spec_path.exists():
+        spec_path.unlink()
+    if not git_dir_existed and git_dir.exists():
+        shutil.rmtree(git_dir)
+    if not grip_dir_existed and grip_dir.exists():
+        shutil.rmtree(grip_dir)
+
+
+def compile_gr1_to_workspace_spec(
+    workspace_root: Path,
+    manifest: dict[str, object],
+    agents_doc: dict[str, object],
+) -> dict[str, object]:
+    repos_doc = manifest.get("repos", {}) or {}
+    if not isinstance(repos_doc, dict):
+        raise ValueError("canonical gripspace manifest repos must be a mapping")
+    repos: list[dict[str, object]] = []
+    writable_repo_names: list[str] = []
+
+    for repo_name, repo_doc in repos_doc.items():
+        safe_repo_name = _safe_workspace_component(repo_name, "repo name")
+        if not isinstance(repo_doc, dict):
+            raise ValueError(f"repository {safe_repo_name!r} must be a mapping")
+        path = repo_doc.get("path", "")
+        normalized_path = _safe_workspace_relative_path(path, f"repository {safe_repo_name!r} path")
+        repo_item = {
+            "name": safe_repo_name,
+            "path": normalized_path,
+            "url": str(repo_doc.get("url", "")).strip(),
+        }
+        if "revision" in repo_doc:
+            repo_item["default_branch"] = str(repo_doc.get("revision") or "").strip()
+        elif "default_branch" in repo_doc:
+            repo_item["default_branch"] = str(repo_doc.get("default_branch") or "").strip()
+        if repo_doc.get("reference", False):
+            repo_item["reference"] = True
+        repos.append(repo_item)
+        if not repo_doc.get("reference", False):
+            writable_repo_names.append(safe_repo_name)
+
+    agents = (agents_doc.get("agents") or {}) or {}
+    if not isinstance(agents, dict):
+        raise ValueError("gr1 agents manifest agents must be a mapping")
+    unit_items = (
+        sorted((_safe_workspace_component(unit_name, "agent unit name"), unit_doc) for unit_name, unit_doc in agents.items())
+        if agents
+        else [("default", {})]
+    )
+    units: list[dict[str, object]] = []
+    for safe_unit_name, unit_doc in unit_items:
+        unit_doc = unit_doc or {}
+        if not isinstance(unit_doc, dict):
+            raise ValueError(f"agent unit {safe_unit_name!r} must be a mapping")
+        units.append(
+            {
+                "name": safe_unit_name,
+                "path": f"agents/{safe_unit_name}/home",
+                "repos": writable_repo_names,
+                "migration_source": {
+                    "worktree": unit_doc.get("worktree"),
+                    "channel": unit_doc.get("channel"),
+                },
+            }
+        )
+
+    return {
+        "workspace_name": workspace_root.name,
+        "repos": repos,
+        "units": units,
+        "workspace_constraints": {
+            "migration_source": "gr1",
+        },
+    }
+
+
+def _safe_workspace_component(value: object, field: str) -> str:
+    """Accept one logical name, never a path fragment or invisible control data."""
+    if not isinstance(value, str) or not value or value in {".", ".."}:
+        raise ValueError(f"{field} must be a non-empty logical name")
+    if "/" in value or "\\" in value or ":" in value or any(ord(char) < 0x20 or ord(char) == 0x7F for char in value):
+        raise ValueError(f"{field} must not contain separators or control characters: {value!r}")
+    return value
+
+
+def _safe_workspace_relative_path(value: object, field: str) -> str:
+    """Normalize only a safe, portable workspace-relative manifest path."""
+    if not isinstance(value, str) or not value or any(ord(char) < 0x20 or ord(char) == 0x7F for char in value):
+        raise ValueError(f"{field} must be a non-empty relative path")
+    if "\\" in value:
+        raise ValueError(f"{field} must use portable '/' separators: {value!r}")
+    posix_path = PurePosixPath(value)
+    windows_path = PureWindowsPath(value)
+    if (
+        posix_path.is_absolute()
+        or windows_path.is_absolute()
+        or windows_path.drive
+        or windows_path.root
+        or ".." in posix_path.parts
+        or str(posix_path) in {".", ""}
+    ):
+        raise ValueError(f"{field} escapes the workspace: {value!r}")
+    return posix_path.as_posix()
+
+
+def preserve_gr1_state(workspace_root: Path, migration_dir: Path) -> dict[str, str]:
+    snapshots: dict[str, str] = {}
+    for name, src in gr1_state_paths(workspace_root).items():
+        if not src.exists():
+            continue
+        dest = migration_dir / src.name
+        shutil.copy2(src, dest)
+        snapshots[name] = str(dest)
+    return snapshots
+
+
+def render_workspace_spec(compiled: dict[str, object]) -> str:
+    lines = [
+        f'workspace_name = "{compiled["workspace_name"]}"',
+        "",
+    ]
+    constraints = compiled.get("workspace_constraints") or {}
+    if constraints:
+        lines.append("[workspace_constraints]")
+        for key, value in constraints.items():
+            lines.append(f'{key} = "{value}"')
+        lines.append("")
+
+    for repo in compiled["repos"]:
+        lines.extend(
+            [
+                "[[repos]]",
+                f'name = "{repo["name"]}"',
+                f'path = "{repo["path"]}"',
+                f'url = "{repo["url"]}"',
+            ]
+        )
+        default_branch = str(repo.get("default_branch", "")).strip()
+        if default_branch:
+            lines.append(f'default_branch = "{default_branch}"')
+        if repo.get("reference", False):
+            lines.append("reference = true")
+        lines.append("")
+
+    for unit in compiled["units"]:
+        lines.extend(
+            [
+                "[[units]]",
+                f'name = "{unit["name"]}"',
+                f'path = "{unit["path"]}"',
+                "repos = [" + ", ".join(f'"{repo}"' for repo in unit["repos"]) + "]",
+            ]
+        )
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_detection(payload: dict[str, object]) -> str:
+    if not payload["detected"]:
+        return "\n".join(["Gr1Detection", "detected = false", f"reason = {payload['reason']}"])
+    lines = [
+        "Gr1Detection",
+        "detected = true",
+        f"workspace_root = {payload['workspace_root']}",
+        f"manifest_path = {payload['manifest_path']}",
+        f"repo_count = {payload['repo_count']}",
+        f"reference_repo_count = {payload['reference_repo_count']}",
+        f"agent_count = {payload['agent_count']}",
+        "REPOS",
+    ]
+    lines.extend(f"- {repo}" for repo in payload["repos"])
+    lines.append("AGENTS")
+    lines.extend(f"- {agent}" for agent in payload["agents"])
+    return "\n".join(lines)
+
+
+def render_migration(payload: dict[str, object]) -> str:
+    lines = [
+        "Gr1Migration",
+        f"workspace_root = {payload['workspace_root']}",
+        f"workspace_spec_path = {payload['workspace_spec_path']}",
+        f"repo_count = {payload['repo_count']}",
+        f"unit_count = {payload['unit_count']}",
+        "UNITS",
+    ]
+    lines.extend(f"- {unit}" for unit in payload["units"])
+    lines.append("SNAPSHOTS")
+    lines.extend(f"- {name}\t{path}" for name, path in payload["snapshots"].items())
+    return "\n".join(lines)
+
+
+def workspace_status(workspace_root: Path) -> dict[str, object]:
+    """Report workspace state: gr1-only, gr2-only, coexistence, or none."""
+    has_gr1 = gr1_manifest_path(workspace_root).exists()
+    gr2_spec_path = workspace_root / ".grip" / "workspace_spec.toml"
+    has_gr2 = gr2_spec_path.exists()
+    migration_dir = workspace_root / ".grip" / "migrations" / "gr1"
+    has_migration = migration_dir.exists() and (migration_dir / "migration-summary.json").exists()
+
+    if has_gr1 and has_gr2:
+        phase = "coexistence"
+    elif has_gr1:
+        phase = "gr1-only"
+    elif has_gr2:
+        phase = "gr2-only"
+    else:
+        phase = "none"
+
+    result: dict[str, object] = {
+        "workspace_root": str(workspace_root),
+        "gr1": has_gr1,
+        "gr2": has_gr2,
+        "coexistence": has_gr1 and has_gr2,
+        "migration_snapshot": has_migration,
+        "phase": phase,
+    }
+
+    if has_gr1:
+        detection = detect_gr1_workspace(workspace_root)
+        result["gr1_repo_count"] = detection.get("repo_count", 0)
+        result["gr1_agents"] = detection.get("agents", [])
+
+    if has_gr2:
+        import tomllib
+        with gr2_spec_path.open("rb") as fh:
+            spec = tomllib.load(fh)
+        repos = spec.get("repos", [])
+        units = spec.get("units", [])
+        result["gr2_repo_count"] = len(repos)
+        result["gr2_unit_count"] = len(units)
+        result["gr2_spec_path"] = str(gr2_spec_path)
+
+        # gr does not support worktree-backed repos (design/worktree-refactor
+        # ruling). `repo status` already flags a hand-made linked worktree
+        # per-repo; this reuses the SAME check (repo_maintenance_prototype's
+        # is_linked_worktree, via derive_targets so shared repos and per-unit
+        # repos are both covered) so `workspace status` reports it too --
+        # the playbook has always claimed both commands do this, and until
+        # now only one actually did.
+        parsed_spec = repo_proto.read_workspace_spec(gr2_spec_path)
+        linked_worktrees = [
+            str(target.path)
+            for target in repo_proto.derive_targets(workspace_root, parsed_spec)
+            if target.path.exists() and repo_proto.is_linked_worktree(target.path)
+        ]
+        result["linked_worktrees"] = linked_worktrees
+
+    return result
+
+
+def render_status(payload: dict[str, object]) -> str:
+    lines = [
+        "WorkspaceStatus",
+        f"phase = {payload['phase']}",
+        f"workspace_root = {payload['workspace_root']}",
+    ]
+    if payload["gr1"]:
+        lines.append(f"gr1 = true (repos: {payload.get('gr1_repo_count', '?')})")
+    if payload["gr2"]:
+        lines.append(f"gr2 = true (repos: {payload.get('gr2_repo_count', '?')}, units: {payload.get('gr2_unit_count', '?')})")
+    if payload["coexistence"]:
+        lines.append("coexistence = true (both .gitgrip and .grip present)")
+    if payload.get("migration_snapshot"):
+        lines.append("migration_snapshot = true (.grip/migrations/gr1/ present)")
+    linked = payload.get("linked_worktrees") or []
+    if linked:
+        lines.append(
+            "linked_worktrees = " + ", ".join(linked)
+            + " -- gr does not support worktree-backed repos; "
+            "run `gr2 workspace convert-clone <path>` on each"
+        )
+    if not payload["gr1"] and not payload["gr2"]:
+        lines.append("No workspace detected. Run `gr2 workspace init` or `gr2 workspace migrate-gr1`.")
+    return "\n".join(lines)
+
+
+def _load_agents_doc(workspace_root: Path) -> dict[str, object]:
+    path = gr1_agents_path(workspace_root)
+    if not path.exists():
+        return {}
+    import tomllib
+
+    with path.open("rb") as fh:
+        return tomllib.load(fh)