workstate-bootstrap 0.7.1__tar.gz → 0.7.3__tar.gz

{workstate_bootstrap-0.7.1 → workstate_bootstrap-0.7.3}/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## Unreleased
 
+## [0.7.3] — 2026-06-03
+
+### Changed
+
+- TODO: summarize this release.
+
+
+## [0.7.2] — 2026-06-02
+
+> Ships the linked-worktree overlay self-heal (implementation note) **and** its deferred
+> follow-ups (implementation note), both of which landed after 0.7.1 was published.
+
+### Added
+
+- **Linked-worktree overlay self-heal (implementation note):** `adopt-worktree` re-runs the
+  install materializer against a linked worktree with `clone=<primary>/.workstate/remote`;
+  worktree-aware `doctor`/`repair` short-circuit emits a single `unadopted_worktree`
+  finding; a managed sentinel-delimited `.gitignore` block keeps an adopted
+  worktree's `git status` clean.
+
+### Changed
+
+- **Apply and `--check` share one surface enumeration (implementation note S1,
+  `revB-install-private-symbol-coupling`):** new `iter_expected_surface_targets`
+  is the single source of the surface/carve/exclusion rule consumed by both the
+  materializer and `adopt._compute_drift`, so the drift guard can no longer
+  desync from apply; the `_materialize_surfaces_copy` (package-install) path is
+  single-sourced through the same helper. `adopt` drops the `importlib` shim for
+  explicit imports.
+- **Overlay-root resolver prefers a materialized overlay (implementation note S3,
+  `revA-overlay-root-unbounded-walk`):** the upward walk skips an unmaterialized
+  stray ancestor marker, falling back to the nearest marker so a genuinely
+  un-materialized primary still fails loudly.
+- **Relocation repoint (implementation note S3b, `revB-relocation-dangling-symlink-no-repoint`):**
+  a dangling bootstrap-owned surface link (e.g. a relocated primary) is repointed
+  to the live clone via a shared, segment-anchored repoint predicate used by both
+  apply and `--check`.
+
+### Notes
+
+- `.claude-plugin/marketplace.json` continues to resolve via the tracked file +
+  the adopted `.workstate/generated` symlink; `adopt` does not materialize it
+  (implementation note S2 locks this contract). Consumers that gitignore `.claude-plugin`
+  need a separate `install` pass.
+
+
 ## [0.7.1] — 2026-06-02
 
 ### Fixed

{workstate_bootstrap-0.7.1 → workstate_bootstrap-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-bootstrap
-Version: 0.7.1
+Version: 0.7.3
 Summary: Bootstrap CLI that hoists the shared workstate-system surface into consumer repos.
 Project-URL: Homepage, https://github.com/darce/workstate
 Project-URL: Source, https://github.com/darce/workstate/tree/main/packages/workstate-bootstrap
@@ -12,7 +12,7 @@ Requires-Python: >=3.11
 Requires-Dist: pyyaml>=6
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: workstate-protocol<0.2.0,>=0.1.7
-Requires-Dist: workstate-system<0.2.0,>=0.1.1
+Requires-Dist: workstate-system<0.2.0,>=0.1.3
 Provides-Extra: dev
 Requires-Dist: mcp-workstate-handoff; (python_version >= '3.12') and extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
@@ -84,6 +84,7 @@ workstate-bootstrap update  --target <path> --remote-ref <tag>
 workstate-bootstrap status  --target <path>
 workstate-bootstrap doctor  --target <path> [--mcp-servers <default|path>]
 workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <default|path>]
+workstate-bootstrap adopt-worktree [--target <linked-worktree>] [--primary <root>] [--check] [--json]
 ```
 
 - `install`: Clone the monorepo, materialize SHARED + GENERATED
@@ -101,7 +102,39 @@ workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <defa
   initialized-state surfaces. Flags missing `.task-state/handoff.db`
   as `state_drift` only when the manifest recorded `.mcp.json`. Exit
   `1` when drift exists.
-- `repair`: Restore drifted surfaces flagged by `doctor`.
+- `repair`: Restore drifted surfaces flagged by `doctor`. For an
+  unadopted linked worktree this routes to `adopt-worktree` (below).
+- `adopt-worktree`: Materialize the overlay into a **linked git
+  worktree** by redirecting its surfaces at the primary's
+  `.workstate/remote` clone (one hop, relative links). `--target`
+  defaults to the current directory; the primary is resolved by the
+  `.workstate-bootstrap.json` marker unless `--primary` is given.
+  `--check` reports drift without writing and exits `1` when the
+  worktree is unadopted. A no-op on the primary worktree.
+
+### Linked worktrees
+
+A linked worktree (`git worktree add`, or an IDE/agent auto-worktree)
+shares the primary's `.git` but **not** gitignored files, so the
+overlay starts absent — the plugin is enabled (tracked
+`.claude/settings.json`) but unresolvable. Self-heal works as follows:
+
+- **`make task-start`** (the supported flow) adopts the overlay into the
+  new worktree automatically, so it works out of the box. In source
+  checkouts, the lifecycle uses the freshly provisioned worktree `.venv`
+  `workstate-bootstrap` command when available, then falls back to `uvx`.
+  Set `WORKSTATE_ADOPT_CMD=""` to disable auto-adopt, or set it to a custom
+  command to override that default.
+- **Raw `git worktree add` / auto-worktrees** are healed on demand:
+
+  ```bash
+  uvx workstate-bootstrap adopt-worktree --target <worktree>
+  # or, as a steady-state guard (exit 1 on drift):
+  uvx workstate-bootstrap adopt-worktree --target <worktree> --check
+  ```
+
+`.task-state/`, `DASHBOARD.txt`, and `CURRENT_TASK.json` are **never**
+adopted — they stay per-worktree (the handoff DB is primary-rooted).
 
 See [`docs/CONSUMER.md`](https://github.com/darce/workstate/blob/main/docs/CONSUMER.md)
 for the consumer-facing walkthrough (upgrade, drift handling, skill

{workstate_bootstrap-0.7.1 → workstate_bootstrap-0.7.3}/README.md

@@ -64,6 +64,7 @@ workstate-bootstrap update  --target <path> --remote-ref <tag>
 workstate-bootstrap status  --target <path>
 workstate-bootstrap doctor  --target <path> [--mcp-servers <default|path>]
 workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <default|path>]
+workstate-bootstrap adopt-worktree [--target <linked-worktree>] [--primary <root>] [--check] [--json]
 ```
 
 - `install`: Clone the monorepo, materialize SHARED + GENERATED
@@ -81,7 +82,39 @@ workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <defa
   initialized-state surfaces. Flags missing `.task-state/handoff.db`
   as `state_drift` only when the manifest recorded `.mcp.json`. Exit
   `1` when drift exists.
-- `repair`: Restore drifted surfaces flagged by `doctor`.
+- `repair`: Restore drifted surfaces flagged by `doctor`. For an
+  unadopted linked worktree this routes to `adopt-worktree` (below).
+- `adopt-worktree`: Materialize the overlay into a **linked git
+  worktree** by redirecting its surfaces at the primary's
+  `.workstate/remote` clone (one hop, relative links). `--target`
+  defaults to the current directory; the primary is resolved by the
+  `.workstate-bootstrap.json` marker unless `--primary` is given.
+  `--check` reports drift without writing and exits `1` when the
+  worktree is unadopted. A no-op on the primary worktree.
+
+### Linked worktrees
+
+A linked worktree (`git worktree add`, or an IDE/agent auto-worktree)
+shares the primary's `.git` but **not** gitignored files, so the
+overlay starts absent — the plugin is enabled (tracked
+`.claude/settings.json`) but unresolvable. Self-heal works as follows:
+
+- **`make task-start`** (the supported flow) adopts the overlay into the
+  new worktree automatically, so it works out of the box. In source
+  checkouts, the lifecycle uses the freshly provisioned worktree `.venv`
+  `workstate-bootstrap` command when available, then falls back to `uvx`.
+  Set `WORKSTATE_ADOPT_CMD=""` to disable auto-adopt, or set it to a custom
+  command to override that default.
+- **Raw `git worktree add` / auto-worktrees** are healed on demand:
+
+  ```bash
+  uvx workstate-bootstrap adopt-worktree --target <worktree>
+  # or, as a steady-state guard (exit 1 on drift):
+  uvx workstate-bootstrap adopt-worktree --target <worktree> --check
+  ```
+
+`.task-state/`, `DASHBOARD.txt`, and `CURRENT_TASK.json` are **never**
+adopted — they stay per-worktree (the handoff DB is primary-rooted).
 
 See [`docs/CONSUMER.md`](https://github.com/darce/workstate/blob/main/docs/CONSUMER.md)
 for the consumer-facing walkthrough (upgrade, drift handling, skill

{workstate_bootstrap-0.7.1 → workstate_bootstrap-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workstate-bootstrap"
-version = "0.7.1"
+version = "0.7.3"
 description = "Bootstrap CLI that hoists the shared workstate-system surface into consumer repos."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,7 +14,7 @@ dependencies = [
 	"tomlkit>=0.13",
 	"pyyaml>=6",
 	"workstate-protocol>=0.1.7,<0.2.0",
-	"workstate-system>=0.1.1,<0.2.0",
+	"workstate-system>=0.1.3,<0.2.0",
 ]
 
 [project.scripts]

workstate_bootstrap-0.7.3/src/workstate_bootstrap/adopt.py

@@ -0,0 +1,296 @@
+"""Adopt the bootstrap overlay into a linked git worktree (implementation note, Slice S1).
+
+A linked worktree shares the primary's ``.git`` but not gitignored files, so the
+bootstrap overlay is absent until it is adopted. ``adopt_worktree`` re-runs the
+*existing* install materialization passes against the worktree, but with
+``clone = <primary>/.workstate/remote`` — reusing the battle-tested carve logic,
+foreign-file precedence, relative-link computation (links point one hop at the
+primary's real clone), and the lifecycle real-file hoist.
+
+Isolation is safe-by-construction rather than via a runtime allow-list (decision
+``adopt-drop-runtime-allowlist-for-materializer-scope-invariant``):
+
+* The materializer only ever touches the recorded shared/generated/lifecycle
+  surfaces + the clone — the per-worktree mutable set (``.task-state``,
+  ``DASHBOARD.txt``, ``CURRENT_TASK.json``, ``state-backups`` …) is never a
+  surface, so it is never adopted.
+* ``.workstate/`` is kept a real *local* directory; only its ``remote`` and
+  ``generated`` children are symlinked to the primary, so sibling per-worktree
+  state under ``.workstate/`` stays local.
+* ``_run_init_state`` / MCP presync are intentionally NOT run — the worktree uses
+  the primary-rooted MCP server; adopt never fabricates a second ``.task-state``.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+# ``workstate_bootstrap.__init__`` re-exports the install *function*, which
+# shadows the submodule only under *attribute* access (``import ... as`` and
+# ``getattr(pkg, "install")`` both yield the function). A direct
+# ``from workstate_bootstrap.install import ...`` submodule import is
+# unaffected — no importlib indirection needed. adopt reuses the install
+# materializer's surface enumeration + apply passes (shared so apply and
+# ``--check`` cannot desync); the private names below are install internals it
+# orchestrates.
+from workstate_bootstrap.install import (
+    GITIGNORE_SENTINEL_BEGIN,
+    HOOKS_PATH_VALUE,
+    LEGACY_LIFECYCLE_INCLUDE_SENTINEL_BEGIN,
+    LIFECYCLE_HOISTS,
+    LIFECYCLE_INCLUDE_SENTINEL_BEGIN,
+    RUNTIME_ROOT_DIRNAME,
+    _ensure_consumer_gitignore_block,
+    _ensure_consumer_makefile_include,
+    _git,
+    _install_lifecycle_profile,
+    _is_repointable_bootstrap_symlink,
+    _materialize_surfaces,
+    _overlay_surfaces_self_managed,
+    _prepare_generated_surfaces,
+    _raw_symlink_target_path,
+    _resolve_in_clone,
+    _set_git_hooks_path,
+    iter_expected_surface_targets,
+)
+from workstate_bootstrap.worktree import (
+    WorktreeError,
+    is_linked_worktree,
+    overlay_is_materialized,
+    primary_overlay_root,
+)
+
+_RUNTIME = RUNTIME_ROOT_DIRNAME  # ".workstate"
+_WORKSTATE_CHILDREN = ("remote", "generated")
+
+
+class OverlayNotMaterializedError(WorktreeError):
+    """The resolved primary has no materialized overlay to adopt from."""
+
+
+def _materialize_workstate_child(target: Path, primary: Path, child: str) -> bool:
+    """Symlink ``target/.workstate/<child>`` -> ``primary/.workstate/<child>``.
+
+    ``.workstate/`` itself stays a real local directory (created if absent) so
+    sibling per-worktree state does not leak across worktrees. The child link is
+    relative for relocation safety. Foreign/real local content at the child path
+    is left untouched (overlay precedence). Returns True when the source exists.
+    """
+    src = primary / _RUNTIME / child
+    if not src.exists():
+        return False
+    ws = target / _RUNTIME
+    if ws.is_symlink():
+        # A pre-existing .workstate SYMLINK would route the remote/generated
+        # child links THROUGH it (into the primary or a foreign dir) — exactly
+        # the cross-worktree contamination the isolation invariant forbids.
+        # Replace it with a real local directory before materializing children.
+        ws.unlink()
+    ws.mkdir(parents=True, exist_ok=True)
+    dest = ws / child
+    rel = os.path.relpath(src, ws)
+    if dest.is_symlink():
+        if dest.resolve(strict=False) == src.resolve():
+            return True
+        dest.unlink()
+    elif dest.exists():
+        return True  # foreign/real local content wins
+    dest.symlink_to(rel, target_is_directory=src.is_dir())
+    return True
+
+
+def _hooks_path_value(target: Path) -> str:
+    try:
+        return _git("config", "core.hooksPath", cwd=target)
+    except subprocess.CalledProcessError:
+        return ""
+
+
+def _link_drifts(
+    target_path: Path,
+    expected_src: Path,
+    clone_resolved: Path,
+    remote_subtree_prefix: str,
+) -> bool:
+    """True iff a bootstrap-owned surface link is missing or stale.
+
+    Shares the repoint rule with apply via
+    ``install._is_repointable_bootstrap_symlink`` so ``--check`` and apply cannot
+    disagree: a correct symlink (resolves to ``expected_src``) is clean; a
+    repointable bootstrap-owned link (stale in-tree pointer, or a dangling link
+    naming a relocated ``.workstate/remote`` clone) is drift; a foreign symlink
+    (resolving, or dangling but not naming our clone) and real local content keep
+    local precedence; an absent target is drift.
+    """
+    if target_path.is_symlink():
+        if target_path.resolve(strict=False) == expected_src.resolve():
+            return False
+        raw = _raw_symlink_target_path(target_path)
+        return _is_repointable_bootstrap_symlink(
+            target_path, raw, clone_resolved, remote_subtree_prefix
+        )
+    if target_path.exists():
+        return False  # real local content — overlay precedence
+    return True  # absent
+
+
+def _compute_drift(target: Path, primary: Path, clone: Path) -> list[str]:
+    """Report what an adopt would materialize, without writing anything.
+
+    Shares the materializer's exclusion sets and foreign-precedence rule so the
+    guard cannot desync from apply: carved-surface children are checked
+    individually, and foreign/local content is never reported as drift.
+    """
+    drift: list[str] = []
+    clone_resolved = clone.resolve()
+    remote_subtree_prefix = str(clone_resolved) + os.sep
+
+    # Clone + generated child redirects.
+    for child in _WORKSTATE_CHILDREN:
+        src = primary / _RUNTIME / child
+        if not src.exists():
+            continue
+        dest = target / _RUNTIME / child
+        if not (dest.is_symlink() and dest.resolve(strict=False) == src.resolve()):
+            drift.append(f"{_RUNTIME}/{child}")
+
+    # Shared surfaces: enumerated by the SAME helper the materializer uses
+    # (install.iter_expected_surface_targets), so the guard cannot desync from
+    # apply. Each expected target — a whole-dir plain surface or a carved
+    # per-child link — drifts iff it is missing or a stale bootstrap-owned link
+    # (foreign/local content is never drift; see _link_drifts).
+    for expected in iter_expected_surface_targets(target, clone):
+        if _link_drifts(
+            expected.target_path,
+            expected.remote_path,
+            clone_resolved,
+            remote_subtree_prefix,
+        ):
+            drift.append(expected.rel)
+
+    # Lifecycle hoists: expect a real file/dir at the destination.
+    for src_rel, dest_rel in LIFECYCLE_HOISTS:
+        if not _resolve_in_clone(clone, src_rel).exists():
+            continue
+        if not (target / dest_rel).exists():
+            drift.append(dest_rel)
+
+    # Consumer Makefile include sentinel.
+    makefile = target / "Makefile"
+    text = makefile.read_text() if makefile.exists() else ""
+    if not (
+        LIFECYCLE_INCLUDE_SENTINEL_BEGIN in text
+        or LEGACY_LIFECYCLE_INCLUDE_SENTINEL_BEGIN in text
+    ):
+        drift.append("Makefile")
+
+    # Managed overlay-ignore block (keeps git status clean). apply writes it, so
+    # --check must verify it too, else a missing block silently regresses. But a
+    # self-hosting source repo manages the surfaces itself (tracked or already
+    # ignored): apply skips the block there, so --check must too — otherwise the
+    # block is reported as perpetual, unsatisfiable drift.
+    gitignore = target / ".gitignore"
+    gitignore_text = gitignore.read_text() if gitignore.exists() else ""
+    if (
+        GITIGNORE_SENTINEL_BEGIN not in gitignore_text
+        and not _overlay_surfaces_self_managed(target)
+    ):
+        drift.append(".gitignore")
+
+    # core.hooksPath (resolved against this worktree's config).
+    if _hooks_path_value(target) != HOOKS_PATH_VALUE:
+        drift.append("core.hooksPath")
+
+    return drift
+
+
+def adopt_worktree(
+    *, target: Path, primary: Path | None = None, check: bool = False
+) -> dict[str, object]:
+    """Adopt (or check) the bootstrap overlay into a linked worktree.
+
+    Args:
+        target: The linked worktree to adopt. Adoption is a no-op when ``target``
+            is the primary worktree (or otherwise not a linked worktree).
+        primary: The primary overlay root. Resolved from ``target`` by marker when
+            omitted (:func:`primary_overlay_root`).
+        check: When True, report drift (``ok``/``drift``) without writing.
+
+    Returns:
+        A receipt dict with ``adopted``, ``check``, ``ok``, ``drift``, ``reason``,
+        ``target``, ``primary``, and (on apply) ``surfaces``.
+
+    Raises:
+        OverlayNotMaterializedError: the resolved primary has no overlay to adopt.
+        OverlayMarkerNotFoundError / NotAGitRepositoryError: from resolution.
+    """
+    target = Path(target).resolve()
+
+    if not is_linked_worktree(target):
+        return {
+            "adopted": False,
+            "check": check,
+            "ok": True,
+            "drift": [],
+            "reason": "not_a_linked_worktree",
+            "target": str(target),
+            "primary": None,
+            "surfaces": [],
+        }
+
+    primary = (
+        primary_overlay_root(target) if primary is None else Path(primary).resolve()
+    )
+    if not overlay_is_materialized(primary):
+        raise OverlayNotMaterializedError(
+            f"primary overlay is not materialized at {primary}; "
+            f"run `workstate-bootstrap install` (or repair) there first"
+        )
+    clone = primary / _RUNTIME / "remote"
+
+    if check:
+        drift = _compute_drift(target, primary, clone)
+        return {
+            "adopted": False,
+            "check": True,
+            "ok": not drift,
+            "drift": drift,
+            "reason": None,
+            "target": str(target),
+            "primary": str(primary),
+            "surfaces": [],
+        }
+
+    # Apply — order mirrors install() under profile=all + lifecycle.
+    for child in _WORKSTATE_CHILDREN:
+        _materialize_workstate_child(target, primary, child)
+
+    surfaces: list[dict[str, str]] = []
+    surfaces.extend(_materialize_surfaces(target, clone))
+    surfaces.extend(_prepare_generated_surfaces(target, clone))
+    surfaces.extend(_install_lifecycle_profile(target, clone))
+    makefile_include = _ensure_consumer_makefile_include(target)
+    # _set_git_hooks_path is worktree-aware: for a linked worktree (.git is a
+    # file) it writes core.hooksPath with --worktree, never touching the primary.
+    hooks = _set_git_hooks_path(target)
+    # implementation note S4: ensure the overlay-ignore block exists so the adopted
+    # worktree's `git status` is clean even when the primary's tracked
+    # .gitignore predates the managed block (idempotent / already_present).
+    gitignore = _ensure_consumer_gitignore_block(target)
+
+    return {
+        "adopted": True,
+        "check": False,
+        "ok": True,
+        "drift": [],
+        "reason": None,
+        "target": str(target),
+        "primary": str(primary),
+        "clone": str(clone),
+        "surfaces": surfaces,
+        "makefile_include": makefile_include,
+        "hooks": hooks,
+        "gitignore": gitignore,
+    }

{workstate_bootstrap-0.7.1 → workstate_bootstrap-0.7.3}/src/workstate_bootstrap/cli.py

@@ -27,7 +27,11 @@ from workstate_bootstrap.subcommands import doctor, repair, status, update
 # implementation note: CLI default flips to ``minimal``. The library
 # ``install()`` API keeps ``profile="all"`` for back-compat with
 # pre-Plan-0009 callers.
-INSTALL_PROFILE_CHOICES: tuple[str, ...] = (PROFILE_MINIMAL, PROFILE_LIFECYCLE, PROFILE_ALL)
+INSTALL_PROFILE_CHOICES: tuple[str, ...] = (
+    PROFILE_MINIMAL,
+    PROFILE_LIFECYCLE,
+    PROFILE_ALL,
+)
 # WORKSTATE-REF-56 implementation note: flipped from PROFILE_MINIMAL back to PROFILE_ALL so
 # a no-argument ``workstate-bootstrap install`` materializes the full
 # surface set out of the box. ``--profile minimal`` and
@@ -137,7 +141,7 @@ def _build_parser() -> argparse.ArgumentParser:
             "Either the literal 'default' (or omit the flag) to register the "
             "monorepo's two managed MCP servers (mcp-workstate-handoff, "
             "mcp-workstate-orchestrator) via uvx, or a path to a JSON file "
-            "carrying a custom mapping. Accepts {\"mcpServers\": {...}} or a "
+            'carrying a custom mapping. Accepts {"mcpServers": {...}} or a '
             "flat mapping. Writes .mcp.json / .vscode/mcp.json / "
             ".codex/config.toml. Use --no-mcp-servers to opt out entirely."
         ),
@@ -368,7 +372,7 @@ def _build_parser() -> argparse.ArgumentParser:
         required=True,
         help=(
             "Either 'default' for the monorepo's managed-server map, or a "
-            "path to a JSON file. Accepts {\"mcpServers\": {...}} or a flat "
+            'path to a JSON file. Accepts {"mcpServers": {...}} or a flat '
             "mapping."
         ),
     )
@@ -377,8 +381,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "--check",
         action="store_true",
         help=(
-            "Report drift without writing. Exit 0 if clean, 1 if any "
-            "surface drifts."
+            "Report drift without writing. Exit 0 if clean, 1 if any surface drifts."
         ),
     )
     mode.add_argument(
@@ -407,9 +410,7 @@ def _build_parser() -> argparse.ArgumentParser:
         choices=sorted(SUPPORTED_SURFACES),
         default=list(DEFAULT_SURFACES),
         metavar="SURFACE",
-        help=(
-            "Subset of surfaces to reconcile. Default: claude vscode codex."
-        ),
+        help=("Subset of surfaces to reconcile. Default: claude vscode codex."),
     )
     p_mcp_sync.add_argument(
         "--json",
@@ -459,6 +460,40 @@ def _build_parser() -> argparse.ArgumentParser:
             "workstate-overrides/workstate-system/."
         ),
     )
+
+    p_adopt = sub.add_parser(
+        "adopt-worktree",
+        help=(
+            "Adopt the bootstrap overlay into a linked git worktree by "
+            "redirecting its surfaces at the primary's clone."
+        ),
+    )
+    p_adopt.add_argument(
+        "--target",
+        type=Path,
+        default=None,
+        help="Linked worktree to adopt. Defaults to the current directory.",
+    )
+    p_adopt.add_argument(
+        "--primary",
+        type=Path,
+        default=None,
+        help=(
+            "Primary overlay root to adopt from. Defaults to resolving it by "
+            "the .workstate-bootstrap.json marker."
+        ),
+    )
+    p_adopt.add_argument(
+        "--check",
+        action="store_true",
+        help="Report drift without writing. Exit 1 when the worktree has drift.",
+    )
+    p_adopt.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="Emit the adoption receipt as JSON.",
+    )
     return parser
 
 
@@ -500,7 +535,9 @@ def main(argv: list[str] | None = None) -> int:
                 file=sys.stdout,
             )
         if isinstance(manifest.get("override_backup_path"), str):
-            print(f"override backup: {manifest['override_backup_path']}", file=sys.stdout)
+            print(
+                f"override backup: {manifest['override_backup_path']}", file=sys.stdout
+            )
         if isinstance(manifest.get("state_backup_path"), str):
             print(f"state backup: {manifest['state_backup_path']}", file=sys.stdout)
         return 0
@@ -552,7 +589,9 @@ def main(argv: list[str] | None = None) -> int:
             file=sys.stdout,
         )
         if isinstance(manifest.get("override_backup_path"), str):
-            print(f"override backup: {manifest['override_backup_path']}", file=sys.stdout)
+            print(
+                f"override backup: {manifest['override_backup_path']}", file=sys.stdout
+            )
         return 0
 
     if args.command == "repair":
@@ -578,6 +617,39 @@ def main(argv: list[str] | None = None) -> int:
             print("repair: no drift detected.", file=sys.stdout)
         return 0
 
+    if args.command == "adopt-worktree":
+        from workstate_bootstrap.adopt import adopt_worktree
+        from workstate_bootstrap.worktree import WorktreeError
+
+        target = args.target if args.target is not None else Path.cwd()
+        try:
+            receipt: dict[str, Any] = adopt_worktree(
+                target=target, primary=args.primary, check=args.check
+            )
+        except WorktreeError as exc:
+            print(f"adopt-worktree: {exc}", file=sys.stderr)
+            return 1
+
+        if args.as_json:
+            print(json.dumps(receipt, indent=2), file=sys.stdout)
+        elif args.check:
+            if receipt["ok"]:
+                print("adopt-worktree: no drift detected.", file=sys.stdout)
+            else:
+                for entry in receipt["drift"]:
+                    print(f"drift: {entry}", file=sys.stdout)
+        elif receipt["adopted"]:
+            print(
+                f"adopt-worktree: adopted overlay from {receipt['primary']}.",
+                file=sys.stdout,
+            )
+        else:
+            print(f"adopt-worktree: no-op ({receipt['reason']}).", file=sys.stdout)
+
+        if args.check and not receipt["ok"]:
+            return 1
+        return 0
+
     if args.command == "mcp-sync":
         try:
             servers = _resolve_managed_servers(args.target, args.mcp_servers)
@@ -641,9 +713,7 @@ def _print_sync_report(report: SyncReport, *, check_only: bool) -> None:
     if report.pruned_managed:
         print(f"  pruned removed-managed: {', '.join(report.pruned_managed)}")
     if not check_only and report.ledger_mcp_servers:
-        print(
-            f"  ledger mcp_servers: {', '.join(report.ledger_mcp_servers)}"
-        )
+        print(f"  ledger mcp_servers: {', '.join(report.ledger_mcp_servers)}")
 
 
 if __name__ == "__main__":  # pragma: no cover