delegate-agent-cli 0.17.0__tar.gz → 0.18.0__tar.gz

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] - 2026-07-19
+
+### Added
+
+- `worktree gc --dry-run` now reports `wouldPruneSourceRoots` and classifies
+  un-prunable worktrees with structured orphan reasons (`source_root_missing`,
+  `worktree_metadata_missing`, `branch_missing`, `detached_backlink`), each
+  with a `safeAction`. GC remains non-destructive and never deletes worktree
+  directories.
+- New `worktrees.poolWarnCount` config knob (default 20): persistent
+  work-mode launches emit a stderr warning when the shared worktree pool
+  holds more worktrees than the threshold. Warn-only; nothing is blocked or
+  deleted.
+
+### Changed
+
+- Text rendering for `worktree gc --dry-run` prints
+  `would prune source roots` instead of a constant zero, and orphan lines now
+  include the worktree path alongside the reason.
+
 ## [0.17.0] - 2026-07-18
 
 ### Added
@@ -463,6 +483,7 @@ Usage-audit fix wave: 82 sessions and 1,241 delegate invocations from one week o
 
 - Releases before 0.1.3 predate this changelog.
 
+[0.18.0]: https://github.com/treygoff24/delegate-agent/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/treygoff24/delegate-agent/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/treygoff24/delegate-agent/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/treygoff24/delegate-agent/compare/v0.14.0...v0.15.0

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delegate-agent-cli
-Version: 0.17.0
+Version: 0.18.0
 Summary: A tiny CLI for delegating bounded agent tasks across coding-agent runtimes.
 Author: Trey Goff
 License-Expression: MIT

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/config.example.json

@@ -116,6 +116,7 @@
   },
   "worktrees": {
     "dataHome": null,
+    "poolWarnCount": 20,
     "autoPrune": {
       "enabled": false,
       "mergedOlderThanDays": 7

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/docs/cli-reference.md

@@ -933,7 +933,7 @@ delegate worktree prune [--merged] [--older-than DAYS] [--harness HARNESS] [--gr
 delegate worktree gc [--dry-run]
 ```
 
-`worktree show --latest HARNESS` selects the latest persistent worktree for the harness, not merely the latest run overall. `worktree list` JSON includes a `summary` with status counts, registry drift counts, warning counts, `autoPruneMode`, and whether the returned operation was read-only; `summary.totalPersistentWorktrees` is always registry-wide, while `allStatusCounts` is scoped to the `--harness` / `--group` filters (pre-status-filter) and `statusCounts` to the visible entries. `worktree remove --group NAME` removes all matching persistent worktrees with the same safety checks as single-handle removal. `worktree prune --group NAME` limits prune candidates to the group. `worktree gc` JSON includes `mode`, `effects`, per-entry `action`, and orphan `safeAction` fields to distinguish dry-run inspection from registry reconciliation; `gc` never deletes worktree directories.
+`worktree show --latest HARNESS` selects the latest persistent worktree for the harness, not merely the latest run overall. `worktree list` JSON includes a `summary` with status counts, registry drift counts, warning counts, `autoPruneMode`, and whether the returned operation was read-only; `summary.totalPersistentWorktrees` is always registry-wide, while `allStatusCounts` is scoped to the `--harness` / `--group` filters (pre-status-filter) and `statusCounts` to the visible entries. `worktree remove --group NAME` removes all matching persistent worktrees with the same safety checks as single-handle removal. `worktree prune --group NAME` limits prune candidates to the group. `worktree gc --dry-run` reports `wouldPruneSourceRoots` and structured orphan reasons; `worktree gc` JSON also includes `mode`, `effects`, per-entry `action`, and orphan `safeAction` fields. `gc` never deletes worktree directories.
 
 List/show entry fields include `branchMergedIntoSource` (branch graph only), `mergedIntoSource` (backward-compatible branch graph state), `fullyIntegrated` (branch merged and worktree clean), `hasUncommittedChanges`, `integrationStatus`, and `uncommittedChangesIntegrated`. `workSummary` is included on `worktree show` and run completion payloads when Delegate can inspect the worktree; `worktree list` omits the deep summary for responsiveness. Consumers that need safe retirement should require `fullyIntegrated: true` or inspect `integrationStatus`. When `integrationStatus` is `branch-merged-worktree-dirty`, merge/cherry-pick suggestions are suppressed because commit integration is already complete and only uncommitted edits remain.
 

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/docs/configuration.md

@@ -578,6 +578,7 @@ Embedded defaults:
 {
   "worktrees": {
     "dataHome": null,
+    "poolWarnCount": 20,
     "autoPrune": {
       "enabled": false,
       "mergedOlderThanDays": 7
@@ -587,6 +588,7 @@ Embedded defaults:
 ```
 
 - `dataHome`: persistent-worktree root. `null` means `~/.delegate/worktrees`.
+- `poolWarnCount`: non-negative worktree-count threshold for a launch-time warning when the shared persistent-worktree pool holds more worktrees. The default is 20. The warning does not block or delete anything.
 - `autoPrune.enabled`: if true, `delegate worktree list` opportunistically prunes clean, fully merged worktrees older than `mergedOlderThanDays`.
 - `autoPrune.mergedOlderThanDays`: non-negative integer.
 

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/docs/worktrees.md

@@ -214,7 +214,7 @@ delegate worktree gc
 
 `gc` reconciles registry metadata with the filesystem and Git worktree list. It does not delete paths by itself.
 
-In dry-run mode, `gc` only reports what it would mark. Without `--dry-run`, it may update Delegate registry status (for example, marking missing paths as `missing` or inconsistent metadata as `unknown`) and may run `git worktree prune` to clean Git administrative metadata for already-missing paths, but it does not delete worktree directories. JSON output includes an `effects` object that makes those mutation boundaries explicit.
+In dry-run mode, `gc` reports `wouldPruneSourceRoots` and classifies un-prunable worktrees with reasons such as `source_root_missing`, `worktree_metadata_missing`, `branch_missing`, and `detached_backlink`. Without `--dry-run`, it may update Delegate registry status (for example, marking missing paths as `missing` or inconsistent metadata as `unknown`) and may run `git worktree prune` to clean Git administrative metadata for already-missing paths, but it does not delete worktree directories. JSON output includes an `effects` object that makes those mutation boundaries explicit.
 
 ## Security boundary
 

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "delegate-agent-cli"
-version = "0.17.0"
+version = "0.18.0"
 description = "A tiny CLI for delegating bounded agent tasks across coding-agent runtimes."
 readme = "README.md"
 requires-python = ">=3.11"

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/__init__.py

@@ -1,5 +1,5 @@
 """Delegate Agent CLI package."""
 
-VERSION = "0.17.0"
+VERSION = "0.18.0"
 
 __all__ = ["VERSION"]

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/command_help.py

@@ -1370,13 +1370,16 @@ COMMAND_SPECS: dict[str, CommandSpec] = {
         usage=("delegate [--cwd PATH] [--json] worktree gc [--dry-run]",),
         options=(
             OptionSpec(
-                "--dry-run", None, "Report what would be collected without changing anything."
+                "--dry-run",
+                None,
+                "Report source roots that would be pruned and un-prunable worktree reasons without changing anything.",
             ),
         ),
         examples=(
             "delegate worktree gc",
             "delegate worktree gc --dry-run",
         ),
+        notes=("GC reconciles registry and Git metadata; it never removes worktree paths.",),
         see_also=("worktree list", "worktree prune", "worktree remove"),
         unsupported_global_options=("--isolation", "--auth-profile"),
     ),

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/config.py

@@ -161,6 +161,7 @@ _EMBEDDED_DEFAULT_CONFIG: JsonObject = {
     },
     "worktrees": {
         "dataHome": None,
+        "poolWarnCount": 20,
         "autoPrune": {
             "enabled": False,
             "mergedOlderThanDays": 7,
@@ -416,6 +417,12 @@ def _validate_worktrees_section(worktrees: JsonValue) -> None:
                 "invalid_worktrees_config",
                 "worktrees.dataHome must be an absolute path or start with ~/.",
             )
+    if "poolWarnCount" in worktrees:
+        _validate_required_non_negative_int(
+            worktrees["poolWarnCount"],
+            path="worktrees.poolWarnCount",
+            error="invalid_worktrees_config",
+        )
     auto_prune = worktrees.get("autoPrune")
     if auto_prune is not None:
         if not isinstance(auto_prune, dict):

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/describe_payload.py

@@ -889,6 +889,7 @@ def describe_payload(
         },
         "worktrees": {
             "dataHome": config["worktrees"]["dataHome"],
+            "poolWarnCount": config["worktrees"]["poolWarnCount"],
             "autoPrune": config["worktrees"]["autoPrune"],
             "dirtySource": {
                 "behavior": "Persistent worktree work runs auto-include tracked edits and untracked non-ignored files before child launch.",

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/rendering.py

@@ -554,7 +554,13 @@ def render_worktree_prune_text(payload: JsonObject, stdout: TextIO) -> None:
 
 def render_worktree_gc_text(payload: JsonObject, stdout: TextIO) -> None:
     print(f"reconciled: {payload.get('reconciled', 0)}", file=stdout)
-    print(f"pruned source roots: {payload.get('prunedSourceRoots', 0)}", file=stdout)
+    if payload.get("dryRun") is True:
+        print(
+            f"would prune source roots: {payload.get('wouldPruneSourceRoots', 0)}",
+            file=stdout,
+        )
+    else:
+        print(f"pruned source roots: {payload.get('prunedSourceRoots', 0)}", file=stdout)
     warnings = payload.get("warnings")
     if isinstance(warnings, list) and warnings:
         print("warnings:", file=stdout)
@@ -569,7 +575,8 @@ def render_worktree_gc_text(payload: JsonObject, stdout: TextIO) -> None:
         for orphan in orphans:
             if isinstance(orphan, dict):
                 print(
-                    f"  - {orphan.get('alias') or orphan.get('runId')} {orphan.get('reason')}",
+                    f"  - {orphan.get('alias') or orphan.get('runId')} "
+                    f"{orphan.get('reason')} {orphan.get('executionCwd')}",
                     file=stdout,
                 )
 

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/worktree_execution.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import shlex
 import subprocess  # nosec B404 - persistent worktree cleanup intentionally runs fixed git argv with shell=False.
 from collections.abc import Callable
@@ -30,7 +31,7 @@ from delegate_agent.isolation import (
     target_contains_source_root,
     worktrees_data_home,
 )
-from delegate_agent.json_types import JsonObject
+from delegate_agent.json_types import JsonObject, is_non_negative_int
 from delegate_agent.prompt_transport import (
     DEVIN_AGENT_CONFIG_ARG_PLACEHOLDER,
     PROMPT_FILE_ARG_PLACEHOLDER,
@@ -108,11 +109,53 @@ def execute_persistent_worktree(
 ) -> tuple[int, JsonObject | None]:
     """Launch a work-mode child in a preserved Delegate-managed git worktree."""
     preflight = _validate_persistent_worktree_request(execution)
+    _warn_if_worktree_pool_large(execution.config, execution.stderr)
     registration = _register_persistent_worktree_run(execution, preflight)
     _create_persistent_worktree_or_record_failure(execution, preflight, registration)
     return _launch_child_in_persistent_worktree(execution, preflight, registration)
 
 
+def _worktree_pool_count(data_home: Path) -> int:
+    # ponytail: count-based guardrail only — a full-tree byte walk was slowest
+    # exactly when the pool was large, the case the warning exists to catch.
+    if not data_home.is_dir():
+        return 0
+    worktree_count = 0
+    try:
+        with os.scandir(data_home) as repositories:
+            for repository in repositories:
+                if not repository.is_dir(follow_symlinks=False):
+                    continue
+                with os.scandir(repository.path) as worktrees:
+                    worktree_count += sum(
+                        entry.is_dir(follow_symlinks=False) for entry in worktrees
+                    )
+    except OSError:
+        pass
+    return worktree_count
+
+
+def _warn_if_worktree_pool_large(config: JsonObject, stderr: TextIO) -> None:
+    worktrees = config.get("worktrees")
+    if not isinstance(worktrees, dict):
+        return
+    threshold = worktrees.get("poolWarnCount")
+    if not is_non_negative_int(threshold):
+        return
+    data_home = worktrees_data_home(config)
+    worktree_count = _worktree_pool_count(data_home)
+    if worktree_count <= threshold:
+        return
+    noun = "worktree" if worktree_count == 1 else "worktrees"
+    print(
+        "WARNING: persistent worktree pool "
+        f"{data_home} holds {worktree_count} {noun}; "
+        f"worktrees.poolWarnCount={threshold}. Reclaim retained work with "
+        "`delegate worktree remove` or `delegate worktree prune`.",
+        file=stderr,
+    )
+
+
 def _validate_persistent_worktree_request(
     execution: PersistentWorktreeExecution,
 ) -> PersistentWorktreePreflight:

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent/worktree_gc.py

@@ -241,8 +241,10 @@ def _gc_orphan_entry(
     if message:
         entry["message"] = message
     safe_actions = {
+        "source_root_missing": "restore_source_root_or_inspect_path_before_manual_cleanup",
         "worktree_metadata_missing": "inspect_path_before_manual_cleanup",
         "branch_missing": "inspect_branch_metadata_before_manual_cleanup",
+        "detached_backlink": "inspect_path_before_manual_cleanup",
         "worktree_list_failed": "retry_after_git_worktree_list_succeeds",
     }
     if reason in safe_actions:
@@ -261,7 +263,12 @@ def _gc_reconcile_missing_path(
 ) -> bool:
     if Path(execution).exists():
         return False
+    source = record.get("sourceGitRoot")
+    if isinstance(source, str) and not Path(source).exists():
+        return False
     if dry_run:
+        if isinstance(source, str):
+            prune_roots.add(source)
         reconciled.append(_gc_missing_entry(record, execution, dry_run=True))
         return True
 
@@ -294,28 +301,57 @@ def _gc_reconcile_list_failure(
 ) -> bool:
     if listed_paths is not None:
         return False
+    source = record.get("sourceGitRoot")
+    reason = (
+        "source_root_missing"
+        if isinstance(source, str) and not Path(source).exists()
+        else "worktree_list_failed"
+    )
     if dry_run:
-        orphans.append(_gc_orphan_entry(record, execution, "worktree_list_failed", list_warning))
+        orphans.append(_gc_orphan_entry(record, execution, reason, list_warning))
         return True
 
     def mark_unknown(
-        fresh: PersistentWorktreeRecord, _fresh_source: str, fresh_execution: str
+        fresh: PersistentWorktreeRecord, fresh_source: str, fresh_execution: str
     ) -> None:
-        if not Path(fresh_execution).exists():
+        source_missing = not Path(fresh_source).exists()
+        if not source_missing and not Path(fresh_execution).exists():
             return
+        fresh_reason = "source_root_missing" if source_missing else "worktree_list_failed"
         run_registry.set_worktree_status_locked(
             registry_root,
             str(fresh["runId"]),
             STATUS_UNKNOWN,
         )
-        orphans.append(
-            _gc_orphan_entry(fresh, fresh_execution, "worktree_list_failed", list_warning)
-        )
+        orphans.append(_gc_orphan_entry(fresh, fresh_execution, fresh_reason, list_warning))
 
     _with_locked_fresh_gc_candidate(registry_root, record, mark_unknown)
     return True
 
 
+def _resolved_git_common_dir(worktree: str) -> Path | None:
+    result = wm._run_git(worktree, ["rev-parse", "--git-common-dir"])
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    common_dir = Path(result.stdout.strip())
+    if not common_dir.is_absolute():
+        common_dir = Path(worktree) / common_dir
+    try:
+        return common_dir.resolve()
+    except (OSError, RuntimeError):
+        return None
+
+
+def _has_detached_backlink(source: str, execution: str) -> bool:
+    source_common_dir = _resolved_git_common_dir(source)
+    execution_common_dir = _resolved_git_common_dir(execution)
+    return (
+        source_common_dir is not None
+        and execution_common_dir is not None
+        and source_common_dir != execution_common_dir
+    )
+
+
 def _gc_reconcile_missing_metadata(
     registry_root: Path,
     record: PersistentWorktreeRecord,
@@ -329,7 +365,13 @@ def _gc_reconcile_missing_metadata(
     if listed_paths is None or _registered_worktree_path_matches(listed_paths, execution):
         return False
     if dry_run:
-        orphans.append(_gc_orphan_entry(record, execution, "worktree_metadata_missing"))
+        source = record.get("sourceGitRoot")
+        reason = (
+            "detached_backlink"
+            if isinstance(source, str) and _has_detached_backlink(source, execution)
+            else "worktree_metadata_missing"
+        )
+        orphans.append(_gc_orphan_entry(record, execution, reason))
         return True
 
     def mark_unknown_if_still_orphaned(
@@ -345,12 +387,17 @@ def _gc_reconcile_missing_metadata(
             and fresh_paths is not None
             and not _registered_worktree_path_matches(fresh_paths, fresh_execution)
         ):
+            fresh_reason = (
+                "detached_backlink"
+                if _has_detached_backlink(fresh_source, fresh_execution)
+                else "worktree_metadata_missing"
+            )
             run_registry.set_worktree_status_locked(
                 registry_root,
                 str(fresh["runId"]),
                 STATUS_UNKNOWN,
             )
-            orphans.append(_gc_orphan_entry(fresh, fresh_execution, "worktree_metadata_missing"))
+            orphans.append(_gc_orphan_entry(fresh, fresh_execution, fresh_reason))
 
     _with_locked_fresh_gc_candidate(registry_root, record, mark_unknown_if_still_orphaned)
     return True
@@ -478,6 +525,7 @@ def gc_worktrees(registry_root: Path, *, dry_run: bool = False) -> JsonObject:
             "runsGitWorktreePrune": (not dry_run and bool(prune_roots)),
         },
         "prunedSourceRoots": 0 if dry_run else len(prune_roots),
+        "wouldPruneSourceRoots": len(prune_roots) if dry_run else 0,
         "reconciled": len(reconciled),
         "reconciledEntries": reconciled,
         "orphans": orphans,

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/src/delegate_agent_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delegate-agent-cli
-Version: 0.17.0
+Version: 0.18.0
 Summary: A tiny CLI for delegating bounded agent tasks across coding-agent runtimes.
 Author: Trey Goff
 License-Expression: MIT

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/tests/test_delegate_validation.py

@@ -745,6 +745,20 @@ class ValidationTests(unittest.TestCase):
         self.assertEqual(ctx.exception.error, "invalid_worktrees_config")
         self.assertIn("mergedOlderThanDays", ctx.exception.message)
 
+    def test_worktrees_pool_warn_count_rejects_bad_values(self):
+        config_mod = load_config_module()
+        for value in (None, -1, True, "1024"):
+            with self.subTest(value=value):
+                with self.assertRaises(config_mod.ConfigError) as ctx:
+                    config_mod.validate_config(
+                        config_mod.deep_merge(
+                            config_mod.DEFAULT_CONFIG,
+                            {"worktrees": {"poolWarnCount": value}},
+                        )
+                    )
+                self.assertEqual(ctx.exception.error, "invalid_worktrees_config")
+                self.assertIn("poolWarnCount", ctx.exception.message)
+
     def test_isolation_and_worktrees_valid_does_not_raise(self):
         config_mod = load_config_module()
         config_mod.validate_config(

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/tests/test_execution_worktree_run.py

@@ -18,6 +18,71 @@ from delegate_agent import worktree_summary  # noqa: E402
 
 
 class ExecutionWorktreeRunTests(ExecutionTestBase):
+    def test_persistent_worktree_launch_checks_pool_guardrail(self):
+        execution = mock.Mock(config={"worktrees": {}}, stderr=io.StringIO())
+        preflight = mock.sentinel.preflight
+        with (
+            mock.patch.object(
+                self.delegate.worktree_execution,
+                "_validate_persistent_worktree_request",
+                return_value=preflight,
+            ),
+            mock.patch.object(
+                self.delegate.worktree_execution,
+                "_warn_if_worktree_pool_large",
+            ) as warn,
+            mock.patch.object(
+                self.delegate.worktree_execution,
+                "_register_persistent_worktree_run",
+                side_effect=RuntimeError("stop after guardrail"),
+            ),
+            self.assertRaisesRegex(RuntimeError, "stop after guardrail"),
+        ):
+            self.delegate.worktree_execution.execute_persistent_worktree(execution)
+
+        warn.assert_called_once_with(execution.config, execution.stderr)
+
+    def test_worktree_pool_guardrail_below_threshold_emits_no_warning(self):
+        with tempfile.TemporaryDirectory() as fake_home:
+            pool = Path(fake_home) / "pool"
+            worktree = pool / "fingerprint" / "old-worktree"
+            worktree.mkdir(parents=True)
+            config = dict(self.delegate.DEFAULT_CONFIG)
+            config["worktrees"] = {
+                **config["worktrees"],
+                "dataHome": str(pool),
+                "poolWarnCount": 1,
+            }
+            stderr = io.StringIO()
+
+            self.delegate.worktree_execution._warn_if_worktree_pool_large(config, stderr)
+
+            self.assertEqual(stderr.getvalue(), "")
+
+    def test_worktree_pool_guardrail_exceeded_warns_with_path_and_threshold(self):
+        with tempfile.TemporaryDirectory() as fake_home:
+            pool = Path(fake_home) / "pool"
+            for name in ("old-worktree", "new-worktree"):
+                (pool / "fingerprint" / name).mkdir(parents=True)
+            config = dict(self.delegate.DEFAULT_CONFIG)
+            config["worktrees"] = {
+                **config["worktrees"],
+                "dataHome": str(pool),
+                "poolWarnCount": 1,
+            }
+            stderr = io.StringIO()
+
+            self.delegate.worktree_execution._warn_if_worktree_pool_large(config, stderr)
+
+            warning = stderr.getvalue()
+            self.assertIn("WARNING", warning)
+            self.assertIn(str(pool), warning)
+            self.assertIn("2 worktrees", warning)
+            self.assertIn("poolWarnCount=1", warning)
+            self.assertIn("delegate worktree remove", warning)
+            self.assertIn("delegate worktree prune", warning)
+            self.assertNotIn("gc --all", warning)
+
     # -- Persistent worktree: cursor work runs in isolated worktree -----------
 
     def test_cursor_work_persistent_worktree_runs_in_worktree(self):

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/tests/test_snapshot_rendering.py

@@ -130,6 +130,31 @@ class SnapshotRenderingTests(SnapshotCommandTestBase):
         self.assertIn("warnings:", output)
         self.assertIn("/repo: fatal: worktree list failed", output)
 
+    def test_render_worktree_gc_dry_run_reports_would_prune_and_reasons(self):
+        stdout = io.StringIO()
+        self.rendering.render_worktree_gc_text(
+            {
+                "dryRun": True,
+                "reconciled": 1,
+                "prunedSourceRoots": 0,
+                "wouldPruneSourceRoots": 1,
+                "orphans": [
+                    {
+                        "alias": "cursor-1",
+                        "executionCwd": "/pool/cursor-1",
+                        "reason": "detached_backlink",
+                    }
+                ],
+                "warnings": [],
+            },
+            stdout,
+        )
+
+        output = stdout.getvalue()
+        self.assertIn("would prune source roots: 1", output)
+        self.assertIn("cursor-1 detached_backlink", output)
+        self.assertIn("/pool/cursor-1", output)
+
 
 if __name__ == "__main__":
     unittest.main()

{delegate_agent_cli-0.17.0 → delegate_agent_cli-0.18.0}/tests/test_worktree_prune_gc.py

@@ -170,6 +170,86 @@ class WorktreePruneGcTests(WorktreeMgmtTestBase):
             self.assertEqual(state["worktreeStatus"], "missing")
             self.assertNotIn("worktreeRemovedAt", state)
 
+    def test_worktree_gc_dry_run_reports_would_prune_source_roots(self):
+        _repo, path = self._make_repo()
+        with tempfile.TemporaryDirectory() as fake_home:
+            wt_path = str(Path(fake_home) / "wt" / "missing")
+            self._seed_persistent_run(path, execution_cwd=wt_path)
+
+            code, out, _err = self._run_cli(
+                ["--cwd", path, "--json", "worktree", "gc", "--dry-run"],
+                home=fake_home,
+            )
+
+            self.assertEqual(code, 0)
+            payload = json.loads(out)
+            self.assertEqual(payload["wouldPruneSourceRoots"], 1)
+            self.assertEqual(payload["prunedSourceRoots"], 0)
+            self.assertFalse(payload["effects"]["deletesWorktreePaths"])
+
+    def test_worktree_gc_classifies_missing_source_root(self):
+        _repo, path = self._make_repo()
+        with tempfile.TemporaryDirectory() as fake_home:
+            execution = Path(fake_home) / "wt" / "orphan"
+            run_id, _alias = self._seed_persistent_run(path, execution_cwd=str(execution))
+            registry_root = self._registry_root(path)
+            manifest = self.delegate.run_registry.load_run_manifest(registry_root, run_id)
+            manifest["sourceGitRoot"] = str(Path(fake_home) / "missing-source")
+            self.delegate.run_registry.write_json_atomic(
+                self.delegate.run_registry.run_directory(registry_root, run_id) / "manifest.json",
+                manifest,
+            )
+
+            result = self.delegate.worktree_mgmt.gc_worktrees(registry_root, dry_run=True)
+
+            self.assertEqual(result["orphans"][0]["reason"], "source_root_missing")
+            result = self.delegate.worktree_mgmt.gc_worktrees(registry_root)
+            self.assertEqual(result["orphans"][0]["reason"], "source_root_missing")
+            state = self.delegate.run_registry.load_run_state(registry_root, run_id)
+            self.assertEqual(state["worktreeStatus"], "unknown")
+
+    def test_worktree_gc_classifies_detached_backlink(self):
+        _repo, path = self._make_repo()
+        with tempfile.TemporaryDirectory() as fake_home:
+            execution = Path(fake_home) / "standalone"
+            subprocess.run(
+                ["git", "init", str(execution)],
+                check=True,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            self._seed_persistent_run(path, execution_cwd=str(execution))
+
+            result = self.delegate.worktree_mgmt.gc_worktrees(
+                self._registry_root(path), dry_run=True
+            )
+
+            self.assertEqual(result["orphans"][0]["reason"], "detached_backlink")
+
+    def test_worktree_gc_classifies_missing_branch(self):
+        _repo, path = self._make_repo()
+        with tempfile.TemporaryDirectory() as fake_home:
+            execution = Path(fake_home) / "wt" / "missing-branch"
+            execution.mkdir(parents=True)
+            self._seed_persistent_run(path, execution_cwd=str(execution))
+            with (
+                mock.patch.object(
+                    self.delegate.worktree_mgmt,
+                    "_worktree_list_paths_with_warning",
+                    return_value=({str(execution)}, None),
+                ),
+                mock.patch.object(
+                    self.delegate.worktree_mgmt,
+                    "_branch_exists",
+                    return_value=False,
+                ),
+            ):
+                result = self.delegate.worktree_mgmt.gc_worktrees(
+                    self._registry_root(path), dry_run=True
+                )
+
+            self.assertEqual(result["orphans"][0]["reason"], "branch_missing")
+
     def test_worktree_gc_existing_orphan_path_is_not_deleted_and_marked_unknown(self):
         _repo, path = self._make_repo()
         with tempfile.TemporaryDirectory() as fake_home: