claude-dev-env 2.7.1 → 2.9.0

package/skills/fresh-branch/scripts/create_fresh_branch.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Create a fresh branch in an isolated git worktree under the repository.
+"""Create a fresh branch in an isolated git worktree under a configured root.
 
 ::
 
@@ -9,8 +9,9 @@
 
 Never runs ``git checkout -b`` in the caller's working tree. Fetches the base
 ref, then ``git worktree add -b --no-track`` into
-``<repo-root>/.claude/worktrees/<agent>/<branch>``. Exit 0 prints success JSON;
-any failure prints ``{"error": ...}`` and exits non-zero.
+``<configured-root>/<agent>/<branch>`` (default configured root:
+``<repo-root>/.claude/worktrees``). Exit 0 prints success JSON; any failure
+prints ``{"error": ...}`` and exits non-zero.
 """
 
 from __future__ import annotations
@@ -33,6 +34,8 @@ from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
     AGENT_SLUG_PATTERN,
     ALL_AGENT_DETECTION_MARKERS,
     ALL_REPOSITORY_WORKTREE_ROOT_PARTS,
+    CLI_FLAG_WORKTREE_ROOT,
+    CLI_HELP_WORKTREE_ROOT,
     DEFAULT_AGENT_SLUG,
     DEFAULT_BASE_REF,
     ERROR_AGENT_SLUG_INVALID,
@@ -41,6 +44,7 @@ from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
     ERROR_CLI_ARGUMENTS,
     ERROR_UNIQUE_PATH_EXHAUSTED,
     ERROR_WORKTREE_PATH_OUTSIDE_ROOT,
+    ERROR_WORKTREE_ROOT_NOT_ABSOLUTE,
     EXIT_CODE_FAILURE,
     EXIT_CODE_SUCCESS,
     FRESH_BRANCH_AGENT_ENV_VAR,
@@ -91,26 +95,79 @@ def _detect_agent_slug_from_environment() -> str:
     return DEFAULT_AGENT_SLUG
 
 
-def resolve_agent_worktree_root(repo_root: Path, agent_slug: str) -> Path:
-    """Return the repository's per-agent worktree root.
+def resolve_configured_worktree_root(
+    repo_root: Path,
+    maybe_worktree_root: str | None = None,
+) -> Path:
+    """Return the isolated root that every worktree path must stay under.
+
+    ::
+
+        resolve_configured_worktree_root(Path("/srv/app"))
+        # ok: /srv/app/.claude/worktrees
+        resolve_configured_worktree_root(Path("/srv/app"), "/tmp/isolated")
+        # ok: /tmp/isolated
+        resolve_configured_worktree_root(Path("/srv/app"), "relative/path")
+        # flag: ValueError --worktree-root must be an absolute path
+
+    When ``maybe_worktree_root`` is omitted, the default root is the repository's
+    ``.claude/worktrees`` directory. An explicit root must be absolute; it may
+    sit outside the repository.
+
+    Args:
+        repo_root: Absolute path of the repository the branch comes from.
+        maybe_worktree_root: Optional absolute configured root, or None.
+
+    Returns:
+        Resolved absolute configured root directory.
+
+    Raises:
+        ValueError: When ``maybe_worktree_root`` is set and is not absolute.
+    """
+    if maybe_worktree_root is None:
+        return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS).resolve()
+    cleaned_worktree_root = maybe_worktree_root.strip()
+    if not cleaned_worktree_root:
+        return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS).resolve()
+    configured_root = Path(cleaned_worktree_root)
+    if not configured_root.is_absolute():
+        raise ValueError(ERROR_WORKTREE_ROOT_NOT_ABSOLUTE)
+    return configured_root.resolve()
+
+
+def resolve_agent_worktree_root(
+    repo_root: Path,
+    agent_slug: str,
+    maybe_worktree_root: str | None = None,
+) -> Path:
+    """Return the per-agent directory under the configured worktree root.
 
     ::
 
         # repo_root=/srv/app, agent_slug=grok
         resolve_agent_worktree_root(Path("/srv/app"), "grok")
         # -> /srv/app/.claude/worktrees/grok
+        resolve_agent_worktree_root(
+            Path("/srv/app"), "grok", maybe_worktree_root="/tmp/isolated",
+        )
+        # -> /tmp/isolated/grok
 
-    Every worktree sits under the repository it branches from, so a worktree
-    travels with its repository and each agent keeps its own subdirectory.
+    Each agent keeps its own subdirectory under the configured root so concurrent
+    hosts do not share worktree folders.
 
     Args:
         repo_root: Absolute path of the repository the branch comes from.
         agent_slug: Short host label (one path segment).
+        maybe_worktree_root: Optional absolute configured root, or None.
 
     Returns:
         Directory that should hold per-branch worktree folders.
     """
-    return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS, agent_slug)
+    configured_root = resolve_configured_worktree_root(
+        repo_root,
+        maybe_worktree_root=maybe_worktree_root,
+    )
+    return configured_root / agent_slug
 
 
 def resolve_unique_worktree_path(preferred_path: Path) -> Path:
@@ -170,38 +227,55 @@ def create_fresh_branch(
     repo_path: Path,
     agent_slug: str,
     base_ref: str,
+    maybe_worktree_root: str | None = None,
 ) -> dict[str, str]:
     """Fetch base_ref and create an isolated worktree branch with no upstream.
 
     ::
 
         create_fresh_branch("fix/x", Path("."), "grok", "origin/main")
+        # worktree under <repo>/.claude/worktrees/grok/fix/x
+        create_fresh_branch(
+            "fix/x", Path("."), "grok", "origin/main",
+            maybe_worktree_root="/tmp/isolated",
+        )
+        # worktree under /tmp/isolated/grok/fix/x
 
-    The caller's working tree is never checked out. The worktree lands under
-    the repository's ``.claude/worktrees/<agent>/<branch>``, suffixed ``-2``,
-    ``-3``, … when that path is already taken.
+    The caller's working tree is never checked out. The configured root is
+    validated before any git fetch so a relative ``--worktree-root`` fails
+    closed with no network I/O. The worktree lands under
+    ``<configured-root>/<agent>/<branch>``, suffixed ``-2``, ``-3``, … when
+    that path is already taken. Every allocated path must resolve beneath the
+    configured root.
 
     Args:
         branch_name: Branch to create; must be a safe relative path.
         repo_path: Any path inside the repository the branch comes from.
         agent_slug: Short host label naming the worktree-root subdirectory.
         base_ref: Ref the branch starts from, such as ``origin/main``.
+        maybe_worktree_root: Optional absolute configured root, or None for
+            the default ``<repo>/.claude/worktrees``.
 
     Returns:
         The success payload: branch, worktree_path, base_ref, base_commit,
         agent, and repo_root.
 
     Raises:
-        ValueError: When the branch name or the agent slug is unsafe.
+        ValueError: When the branch name, agent slug, or worktree root is unsafe.
         RuntimeError: When git refuses the fetch or the worktree add.
     """
     cleaned_branch = _require_safe_branch_name(branch_name)
     normalized_agent_slug = _normalize_agent_slug(agent_slug)
-    resolved_base_ref, repo_root, base_commit = _resolve_branch_base(
-        repo_path, base_ref,
+    repo_root = resolve_repo_root(repo_path)
+    configured_root = resolve_configured_worktree_root(
+        repo_root,
+        maybe_worktree_root=maybe_worktree_root,
     )
+    resolved_base_ref, base_commit = _fetch_resolved_base(repo_root, base_ref)
     worktree_path = _allocate_worktree_path(
-        cleaned_branch, normalized_agent_slug, repo_root,
+        cleaned_branch,
+        normalized_agent_slug,
+        configured_root,
     )
     create_worktree_branch(
         repo_root,
@@ -215,15 +289,11 @@ def create_fresh_branch(
     )
 
 
-def _resolve_branch_base(
-    repo_path: Path,
-    base_ref: str,
-) -> tuple[str, Path, str]:
+def _fetch_resolved_base(repo_root: Path, base_ref: str) -> tuple[str, str]:
     resolved_base_ref = normalize_base_ref(base_ref)
-    repo_root = resolve_repo_root(repo_path)
     fetch_base_ref(repo_root, resolved_base_ref)
     base_commit = resolve_base_commit(repo_root, resolved_base_ref)
-    return resolved_base_ref, repo_root, base_commit
+    return resolved_base_ref, base_commit
 
 
 def main() -> int:
@@ -233,14 +303,7 @@ def main() -> int:
         Process exit code (0 success, 1 failure).
     """
     try:
-        parsed_arguments = _parse_arguments()
-        agent_slug = resolve_agent_slug(parsed_arguments.agent)
-        success_payload = create_fresh_branch(
-            branch_name=parsed_arguments.branch_name,
-            repo_path=Path(parsed_arguments.repo).resolve(),
-            agent_slug=agent_slug,
-            base_ref=parsed_arguments.base,
-        )
+        success_payload = _create_fresh_branch_from_cli_arguments()
         print(json.dumps(success_payload))
         return EXIT_CODE_SUCCESS
     except (ValueError, RuntimeError, OSError) as error:
@@ -248,6 +311,18 @@ def main() -> int:
         return EXIT_CODE_FAILURE
 
 
+def _create_fresh_branch_from_cli_arguments() -> dict[str, str]:
+    parsed_arguments = _parse_arguments()
+    agent_slug = resolve_agent_slug(parsed_arguments.agent)
+    return create_fresh_branch(
+        branch_name=parsed_arguments.branch_name,
+        repo_path=Path(parsed_arguments.repo).resolve(),
+        agent_slug=agent_slug,
+        base_ref=parsed_arguments.base,
+        maybe_worktree_root=parsed_arguments.worktree_root,
+    )
+
+
 def _require_safe_branch_name(branch_name: str) -> str:
     cleaned_branch = branch_name.strip()
     if not cleaned_branch:
@@ -257,19 +332,21 @@ def _require_safe_branch_name(branch_name: str) -> str:
 
 
 def _allocate_worktree_path(
-    branch_name: str, agent_slug: str, repo_root: Path,
+    branch_name: str,
+    agent_slug: str,
+    configured_root: Path,
 ) -> Path:
-    agent_worktree_root = resolve_agent_worktree_root(repo_root, agent_slug)
+    agent_worktree_root = configured_root / agent_slug
     agent_worktree_root.mkdir(parents=True, exist_ok=True)
     preferred_path = agent_worktree_root / branch_name
-    _assert_path_is_under_agent_root(
+    _assert_path_is_under_configured_root(
         candidate_path=preferred_path,
-        agent_worktree_root=agent_worktree_root,
+        configured_root=configured_root,
     )
     worktree_path = resolve_unique_worktree_path(preferred_path)
-    _assert_path_is_under_agent_root(
+    _assert_path_is_under_configured_root(
         candidate_path=worktree_path,
-        agent_worktree_root=agent_worktree_root,
+        configured_root=configured_root,
     )
     return worktree_path
 
@@ -309,12 +386,12 @@ def _validate_branch_name_for_worktree_path(branch_name: str) -> None:
     assert_git_accepts_branch_name(branch_name)
 
 
-def _assert_path_is_under_agent_root(
+def _assert_path_is_under_configured_root(
     candidate_path: Path,
-    agent_worktree_root: Path,
+    configured_root: Path,
 ) -> None:
     resolved_candidate = candidate_path.resolve()
-    resolved_root = agent_worktree_root.resolve()
+    resolved_root = configured_root.resolve()
     if resolved_candidate == resolved_root:
         return
     try:
@@ -342,13 +419,19 @@ def _parse_arguments() -> argparse.Namespace:
     parser.add_argument(
         "--agent",
         default=None,
-        help="Host label for .claude/worktrees/<agent>/ (default: detect from environment).",
+        help="Host label for <configured-root>/<agent>/ (default: detect from environment).",
     )
     parser.add_argument(
         "--base",
         default=DEFAULT_BASE_REF,
         help=f"Base ref to fetch and branch from (default: {DEFAULT_BASE_REF}).",
     )
+    parser.add_argument(
+        CLI_FLAG_WORKTREE_ROOT,
+        default=None,
+        dest="worktree_root",
+        help=CLI_HELP_WORKTREE_ROOT,
+    )
     try:
         return parser.parse_args()
     except SystemExit as exit_error:

package/skills/fresh-branch/scripts/fresh_branch_scripts_constants/fresh_branch_cli_constants.py

@@ -1,7 +1,7 @@
 """Constants for the fresh-branch worktree creator.
 
-Groups: default refs, agent detection, path layout, JSON payload keys,
-exit codes, and unique-path suffix limits.
+Groups: default refs, agent detection, path layout, CLI flags, JSON payload
+keys, exit codes, and unique-path suffix limits.
 """
 
 from __future__ import annotations
@@ -25,6 +25,12 @@ PATH_SEGMENT_PARENT = ".."
 
 ALL_REPOSITORY_WORKTREE_ROOT_PARTS = (".claude", "worktrees")
 
+CLI_FLAG_WORKTREE_ROOT = "--worktree-root"
+CLI_HELP_WORKTREE_ROOT = (
+    "Absolute isolated root for worktrees "
+    "(default: <repo>/.claude/worktrees). Agent and branch nest under it."
+)
+
 MAXIMUM_UNIQUE_PATH_ATTEMPTS = 100
 UNIQUE_PATH_SUFFIX_START = 2
 
@@ -60,7 +66,8 @@ ERROR_BRANCH_NAME_REQUIRED = "branch name is required"
 ERROR_BRANCH_NAME_UNSAFE = (
     "branch name must be a relative path without '.' or '..' segments"
 )
-ERROR_WORKTREE_PATH_OUTSIDE_ROOT = "worktree path escapes agent root: %s"
+ERROR_WORKTREE_PATH_OUTSIDE_ROOT = "worktree path escapes configured root: %s"
+ERROR_WORKTREE_ROOT_NOT_ABSOLUTE = "--worktree-root must be an absolute path"
 ERROR_CLI_ARGUMENTS = "invalid or missing command-line arguments"
 ERROR_AGENT_SLUG_INVALID = "agent slug must be lowercase letters, digits, or hyphens"
 ERROR_REPO_NOT_GIT = "path is not inside a git repository: %s"

package/skills/fresh-branch/scripts/test_create_fresh_branch.py

@@ -17,9 +17,12 @@ if str(SCRIPTS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIRECTORY))
 
 from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
+    ALL_REPOSITORY_WORKTREE_ROOT_PARTS,
+    CLI_FLAG_WORKTREE_ROOT,
     DEFAULT_AGENT_SLUG,
     DEFAULT_BASE_REF,
     ERROR_CLI_ARGUMENTS,
+    ERROR_WORKTREE_ROOT_NOT_ABSOLUTE,
     EXIT_CODE_FAILURE,
     EXIT_CODE_SUCCESS,
     FRESH_BRANCH_AGENT_ENV_VAR,
@@ -244,6 +247,40 @@ class TestResolveAgentSlug:
             module.resolve_agent_slug("../evil")
 
 
+class TestResolveConfiguredWorktreeRoot:
+    def should_default_to_repo_claude_worktrees(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        configured_root = module.resolve_configured_worktree_root(tmp_path)
+        expected_root = tmp_path.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS)
+        assert configured_root == expected_root.resolve()
+
+    def should_accept_an_absolute_root_outside_the_repo(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        external_root = (tmp_path / "external-isolated").resolve()
+        configured_root = module.resolve_configured_worktree_root(
+            tmp_path / "repo",
+            maybe_worktree_root=str(external_root),
+        )
+        assert configured_root == external_root
+
+    def should_reject_a_relative_worktree_root(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        with pytest.raises(ValueError, match="absolute path"):
+            module.resolve_configured_worktree_root(
+                tmp_path,
+                maybe_worktree_root="relative/worktrees",
+            )
+
+
 class TestResolveAgentWorktreeRoot:
     def should_nest_under_the_repository_claude_worktrees_directory(
         self,
@@ -263,6 +300,19 @@ class TestResolveAgentWorktreeRoot:
         assert grok_root != claude_root
         assert grok_root.parent == claude_root.parent
 
+    def should_nest_agent_under_an_explicit_configured_root(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        external_root = (tmp_path / "isolated-root").resolve()
+        agent_root = module.resolve_agent_worktree_root(
+            tmp_path / "repo",
+            "grok",
+            maybe_worktree_root=str(external_root),
+        )
+        assert agent_root == external_root / "grok"
+
 
 class TestResolveUniqueWorktreePath:
     def should_return_preferred_when_missing(self, tmp_path: Path) -> None:
@@ -358,6 +408,146 @@ class TestBranchNamePathSafety:
         assert not (tmp_path / "unused-repo").exists()
 
 
+class TestConfiguredWorktreeRootIntegration:
+    def should_create_worktree_under_explicit_absolute_root(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        configured_root = (tmp_path / "isolated-worktrees").resolve()
+        caller_head_before = read_head_branch(repository_path)
+        caller_commit_before = read_head_commit(repository_path)
+        success_payload = module.create_fresh_branch(
+            branch_name="fix/external-root",
+            repo_path=repository_path,
+            agent_slug="grok",
+            base_ref=DEFAULT_BASE_REF,
+            maybe_worktree_root=str(configured_root),
+        )
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        assert worktree_path == configured_root / "grok" / "fix" / "external-root"
+        assert worktree_path.is_dir()
+        assert worktree_path.resolve().is_relative_to(configured_root)
+        assert not (
+            repository_path.resolve()
+            / ".claude"
+            / "worktrees"
+            / "grok"
+            / "fix"
+            / "external-root"
+        ).exists()
+        assert read_head_branch(repository_path) == caller_head_before
+        assert read_head_commit(repository_path) == caller_commit_before
+
+    def should_suffix_when_path_exists_under_configured_root(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        configured_root = (tmp_path / "isolated-worktrees").resolve()
+        occupied_path = configured_root / "claude" / "fix" / "collision"
+        occupied_path.mkdir(parents=True)
+        success_payload = module.create_fresh_branch(
+            branch_name="fix/collision",
+            repo_path=repository_path,
+            agent_slug="claude",
+            base_ref=DEFAULT_BASE_REF,
+            maybe_worktree_root=str(configured_root),
+        )
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        assert worktree_path == configured_root / "claude" / "fix" / "collision-2"
+        assert worktree_path.is_dir()
+
+    def should_reject_relative_worktree_root_without_creating_worktree(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        with pytest.raises(ValueError, match="absolute path") as raised_error:
+            module.create_fresh_branch(
+                branch_name="fix/relative-root",
+                repo_path=repository_path,
+                agent_slug="claude",
+                base_ref=DEFAULT_BASE_REF,
+                maybe_worktree_root="relative/worktrees",
+            )
+        assert str(raised_error.value) == ERROR_WORKTREE_ROOT_NOT_ABSOLUTE
+        assert not (repository_path / ".claude" / "worktrees").exists()
+
+    def should_reject_relative_worktree_root_before_fetch(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        all_fetch_calls: list[str] = []
+
+        def record_fetch(repo_root: Path, base_ref: str) -> None:
+            all_fetch_calls.append(base_ref)
+            raise AssertionError("fetch must not run for a relative worktree root")
+
+        monkeypatch.setattr(module, "fetch_base_ref", record_fetch)
+        with pytest.raises(ValueError, match="absolute path") as raised_error:
+            module.create_fresh_branch(
+                branch_name="fix/relative-root-before-fetch",
+                repo_path=repository_path,
+                agent_slug="claude",
+                base_ref=DEFAULT_BASE_REF,
+                maybe_worktree_root="relative/worktrees",
+            )
+        assert str(raised_error.value) == ERROR_WORKTREE_ROOT_NOT_ABSOLUTE
+        assert all_fetch_calls == []
+
+    def should_fetch_base_before_creating_worktree(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        all_call_names: list[str] = []
+        real_fetch = module.fetch_base_ref
+        real_create = module.create_worktree_branch
+
+        def record_fetch(
+            repo_root: Path,
+            base_ref: str,
+        ) -> None:
+            all_call_names.append("fetch")
+            real_fetch(repo_root, base_ref)
+
+        def record_create(
+            repo_root: Path,
+            branch_name: str,
+            worktree_path: Path,
+            base_ref: str,
+        ) -> None:
+            all_call_names.append("create")
+            real_create(
+                repo_root,
+                branch_name=branch_name,
+                worktree_path=worktree_path,
+                base_ref=base_ref,
+            )
+
+        monkeypatch.setattr(module, "fetch_base_ref", record_fetch)
+        monkeypatch.setattr(module, "create_worktree_branch", record_create)
+        module.create_fresh_branch(
+            branch_name="fix/fetch-order",
+            repo_path=repository_path,
+            agent_slug="claude",
+            base_ref=DEFAULT_BASE_REF,
+        )
+        assert all_call_names == ["fetch", "create"]
+
+
 class TestCreateFreshBranchIntegration:
     def should_create_worktree_branch_without_moving_caller_head(
         self,
@@ -670,3 +860,64 @@ class TestMainCli:
         assert "relative path" in error_payload[PAYLOAD_KEY_ERROR]
         assert not outside_target.exists()
         assert not (tmp_path / "unused-repo").exists()
+
+    def should_print_error_json_for_relative_worktree_root(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "create_fresh_branch.py",
+                "--branch-name",
+                "feat/relative-root",
+                "--repo",
+                str(repository_path),
+                "--agent",
+                "claude",
+                CLI_FLAG_WORKTREE_ROOT,
+                "relative/worktrees",
+            ],
+        )
+        exit_code = module.main()
+        captured = capsys.readouterr()
+        assert exit_code == EXIT_CODE_FAILURE
+        error_payload = json.loads(captured.out)
+        assert error_payload[PAYLOAD_KEY_ERROR] == ERROR_WORKTREE_ROOT_NOT_ABSOLUTE
+
+    def should_print_success_json_for_absolute_worktree_root(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        configured_root = (tmp_path / "cli-isolated").resolve()
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "create_fresh_branch.py",
+                "--branch-name",
+                "feat/cli-root",
+                "--repo",
+                str(repository_path),
+                "--agent",
+                "grok",
+                CLI_FLAG_WORKTREE_ROOT,
+                str(configured_root),
+            ],
+        )
+        exit_code = module.main()
+        captured = capsys.readouterr()
+        assert exit_code == EXIT_CODE_SUCCESS
+        success_payload = json.loads(captured.out)
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        assert worktree_path == configured_root / "grok" / "feat" / "cli-root"
+        assert worktree_path.is_dir()

package/skills/grok-spawn/SKILL.md

@@ -148,6 +148,11 @@ Workers run with no turn cap. The timeout is the only bound on a worker's
 length, and a worker that hits it is killed with its whole process tree and
 reported as `timeout`.
 
+A worker entry accepts these fields and no others. Any other key fails the
+load with an error naming the stray key and listing the accepted set, so a
+misspelled field shows up at startup rather than passing for a setting that
+took effect.
+
 Put the spec file under the run state directory (or any path you pass to
 `--spec`).
 
@@ -226,3 +231,8 @@ Sibling skill: `/grokify` for a single paste-ready interactive Grok Build handof
 
 - `SKILL.md` — hub and process.
 - `reference/` — brief templates and flag profiles.
+
+## Worker advisors
+
+Each grok worker binds a unique Opus-high dvisor_session_id through the lead-supplied dvisor.launcher in the batch spec (committed default is a placeholder). Reports require the same handle\'s ENDORSE (or bounded CORRECTION/PLAN then ENDORSE); STOP or malformed signals end as advisor_blocked.
+

package/skills/orchestrator/SKILL.md

@@ -129,7 +129,10 @@ pending, or when the tool is `CronCreate`.
    whole lifecycle (its Lifecycle ownership section); executors only ever
    message the warm agent or report here, and an executor that finds the
    advisor unreachable reports that upward — it never spawns a
-   replacement itself.
+   replacement itself. A **Fable**-tier attempt carries the exact token
+   `FABLE-SPAWN-AUTHORIZED` in its spawn prompt, as the protocol's
+   warm-up rule states; `hooks/blocking/fable_spawn_gate.py` denies a
+   fable spawn whose prompt lacks it.
 3. **Write the run artifacts** (next section) before the first spawn.
 4. **Activate status_gate** when the first open ledger task exists:
    `python scripts/status_gate.py set --status active`.
@@ -355,3 +358,8 @@ no open work remains, run `set --status done` before any re-arm attempt.
 - `scripts/` — deterministic status_gate.
 - Advisor policy:
   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
+
+## File-backed run ledger
+
+When host task tools are absent, reconcile delegated work through `scripts/grok_run_ledger.py` under the run-state directory (stable task ids, one live owner, unique advisor sessions, dependency blocking, snapshot-drift reopening).
+

package/skills/orchestrator-refresh/SKILL.md

@@ -89,7 +89,11 @@ once, and reports the unreachable advisor.
    - **Claude host:** executors consult the warm `session-advisor` via
      `SendMessage` (ENDORSE / CORRECTION / PLAN / STOP). This session
      routes the same way; keep tool use to orchestration and light
-     verification reads.
+     verification reads. A drift re-spawn at the **Fable** tier carries
+     the exact token `FABLE-SPAWN-AUTHORIZED` in its fresh prompt, as
+     the protocol's warm-up rule states;
+     `hooks/blocking/fable_spawn_gate.py` denies a fable spawn whose
+     prompt lacks it.
    - **Third-party host:** advisor is a max-tier Claude CLI bind owned
      by this session (`claude_chain_runner.py`, Fable high then Opus
      max). Do **not** spawn `session-advisor` via Agent. Executors

package/skills/task-build/reference/tool-routing.md

@@ -17,3 +17,6 @@ Do not invent a tool name. Tool availability means the callable tool is exposed
 ## Reporting
 
 State the selected tool, the number of new items, the number already tracked, and the new task subjects. If the fallback path was used, name the unavailable preferred tools briefly.
+
+4. **File ledger fallback** — when no host task/plan tool is exposed, register work in the durable `grok_run_ledger` under the run-state directory so orchestration stays reconcilable across hosts.
+