claude-dev-env 2.7.0 → 2.8.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

@@ -125,7 +125,6 @@ Shape:
       "tool_profile": "readonly",
       "timeout_seconds": 600,
       "is_repo_only": true,
-      "max_turns": 8,
       "agent_name": null
     }
   ]
@@ -141,11 +140,19 @@ Shape:
 | `prompt_parts` | Ordered absolute paths to part files |
 | `cwd` | Working directory for that worker |
 | `tool_profile` | `readonly` or `build` |
-| `timeout_seconds` | Per-worker timeout (default 600) |
+| `timeout_seconds` | Per-worker timeout (default 600, ceiling 5400). A spec asking for more is refused |
 | `is_repo_only` | Readonly only: when true, also pass `--disable-web-search` |
-| `max_turns` | Turn cap (default 8) |
 | `agent_name` | Optional `--agent` name, or `null` |
 
+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`).
 

package/skills/grok-spawn/reference/flag-profiles.md

@@ -20,10 +20,12 @@ The headless runner always passes:
 | `--cwd` | Worker `cwd` from the batch spec |
 | `--output-format` | `json` |
 | `--always-approve` | present (auto-approve tool runs) |
-| `--max-turns` | Worker `max_turns` (default `8`) |
 | `--leader-socket` | Unique per-worker socket path under the run state dir |
 | `--debug-file` | Unique per-worker debug log (batch launcher adds this) |
 
+The runner passes no `--max-turns`. Worker length is bounded by the per-worker
+timeout alone. The preflight ping keeps its own single-turn cap.
+
 Optional:
 
 | Flag | When |

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`.