delegate-agent-cli 0.20.0__tar.gz → 0.21.0__tar.gz

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/CHANGELOG.md

@@ -5,6 +5,123 @@ 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.21.0] - 2026-07-26
+
+### Added
+
+- Added `delegate worktree gc --all`, which scans the machine-wide worktree
+  pool for worktrees whose source repository no longer exists. Such worktrees
+  were previously unreachable by any `gc` invocation, because reaping is driven
+  by the run registry inside each source repository and that registry dies with
+  the repository. The scan adds no catalog or persistent state: it reads each
+  worktree's Git backlink directly, and treats a backlink whose target is gone
+  as the sole orphan signal. The scan removes nothing at all, at any depth: a
+  missing source repository makes a worktree's uncommitted state impossible to
+  inspect, so orphans and empty pool directories alike are reported for
+  deliberate manual cleanup. Because that output invites manual deletion, every
+  uncertainty resolves away from an orphan verdict: a pointer file that cannot
+  be read, a path comparison the filesystem cannot answer, an entry too recently
+  modified to have settled, and a directory whose name does not match the pool's
+  own fingerprint contract are all reported as warnings rather than orphans.
+  That last rule is what keeps a scan of an arbitrary root from labelling
+  somebody else's directories. `--pool PATH` scans a different pool root, which
+  reaches pools stranded by an earlier `worktrees.dataHome`.
+- `capabilities refresh` and `setup` now name each harness on stderr as it is
+  probed, so a harness that hangs is identifiable rather than anonymous
+  silence. Progress output is suppressed under `--json`.
+
+### Changed
+
+- A launch now fails instead of proceeding when the configured binary for a
+  harness identifies itself as a *different* known harness. Delegate re-probes
+  `--version` when a cached capability record has refused a run, and during
+  `capabilities refresh` and `setup` (see Fixed); when that banner positively
+  names another harness — a Codex path replaced in place by Grok, say — the run
+  stops with `harness_identity_mismatch` and exit code 2, naming the configured
+  harness, the harness that answered, and the selector path.
+  Previously the launch continued against that same binary with the same Codex
+  argv, sandbox flags, and approval policy, and only the cached capability
+  metadata was discarded. This fires solely on a banner that NAMES another known
+  harness, never on uncertainty: a probe that errors, times out, exceeds its
+  output bound, or prints an unbranded banner still fails open and launches on
+  the cached record. An unbranded shape — a bare date-and-hash build ID is the
+  clearest case — is deliberately not identification, because wrapper prefixes
+  are a supported configuration and refusing a legitimate launch costs more than
+  carrying a stale record until the next refresh. The selector is scrubbed of
+  credentials before it reaches the message or the diagnostics, since a wrapper
+  prefix can carry a token inline or after a flag. Dry runs do not probe and are
+  unaffected. The refusal also names the discovery cache file for the active
+  auth profile, in its `cachePath` diagnostic and in a next action, because
+  `capabilities refresh` cannot clear this state: a refresh keeps the
+  last-known-good record whenever a probe fails, which is correct for a flaky
+  probe and wrong here, where the record itself is the problem. Without the
+  path, a wrong identification would refuse every launch with no documented way
+  out short of editing configuration.
+- A run whose cached capability record is discarded for version drift now says
+  so, naming `delegate capabilities refresh <engine>`. The record is dropped for
+  that run only and the superseded copy stays on disk, so every later launch
+  repeats the drop and loses the same discovery-sourced models and reasoning
+  levels — previously with no indication that a stale cache was the cause.
+  Selector drift stays silent, since `capabilities` already reports it under
+  `driftedHarnesses`.
+
+### Fixed
+
+- Discovery now detects a harness that was upgraded in place. Cached capability
+  records were invalidated only by comparing the configured selector, so an
+  upgrade behind an unchanged selector left stale capabilities cached
+  indefinitely and a newly supported reasoning level was rejected until a manual
+  `capabilities refresh`. Delegate now re-probes `--version` for the single
+  harness it is about to use and compares it against the version already stored
+  in the record, then rebuilds the run against the refreshed picture. The probe
+  runs only once the cached record has already cost the run something, never on
+  the ordinary path, which therefore spawns no extra process at all — and that
+  matters because the probe costs 26-668ms, worst on the Node and Bun harnesses
+  that are already slow to start. Two things trigger it: an explicit
+  `--reasoning-effort` the record refuses, and a `defaultReasoningEffort` the
+  record silently drops. The second is the one most likely to go unnoticed,
+  since a configured default degrades to a warning rather than failing the
+  launch, and it is set once and then never typed again. A probe that cannot
+  repair the default leaves the run exactly as it was: a launch that succeeded
+  is never turned into a failure. The check fails open — a probe that errors,
+  times out, or prints a banner nothing recognizes keeps the cached record, so a
+  failing probe can never prevent a launch. A banner that positively identifies
+  a *different* known harness is the exception, and it aborts the launch rather
+  than merely invalidating the record — see Changed. Each banner is matched
+  against the expected harness's own pattern before anyone else's, so a banner
+  mentioning more than one tool is read as the harness that was asked for
+  instead of whichever pattern happens to be declared earlier. Banners are read
+  with escape sequences stripped, so a colorized version line no longer freezes
+  a record permanently. A cached selector whose binary no longer exists is also
+  treated as drift.
+- Not covered, deliberately: a harness that *removes* a capability leaves its
+  cached record listing more than the harness now supports, which produces no
+  refusal and so no probe. The child rejects the effort it was handed, which is
+  loud; the one quiet case is Cursor's route table aiming a run at a superseded
+  model id. Catching either would cost a probe on every launch, which is the
+  trade this path exists to refuse. `capabilities refresh` remains the cure.
+- A dry run never probes the harness for its version. Dry run documents that it
+  neither launches a child runtime nor requires the real child binary, and the
+  drift probe is a child runtime; it now runs only on a real launch, leaving dry
+  run with the two filesystem-local checks.
+- A discovery cache carrying a newer schema than the running build is no longer
+  discarded and overwritten. It is left intact while the run degrades to
+  probing without persisting, so an older Delegate can no longer destroy a newer
+  cache. Losing that race mid-probe degrades the same way rather than failing the
+  command: `capabilities refresh` and `setup` both report `cacheWriteSkipped`,
+  `setup` additionally leaving `cacheState` at `unchanged`, and each exits
+  successfully, since only persistence was lost. The
+  schema is re-read immediately before the atomic replacement rather than before
+  the snapshot is serialized, which narrows the window in which a newer cache
+  could be published and then overwritten down to the `os.replace` call itself.
+  POSIX offers no compare-and-swap for a rename, so that last window remains.
+- The test suite no longer writes into the developer's real
+  `~/.delegate/worktrees`. Tests exercising persistent-worktree runs created
+  real pooled worktrees over temporary source repositories and orphaned them
+  permanently, because `worktrees_data_home` falls through to the user's home
+  directory with no seam a test could redirect. `HOME` is now redirected at test
+  collection time, which reaches every such resolver at once.
+
 ## [0.20.0] - 2026-07-25
 
 ### Added
@@ -631,6 +748,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.21.0]: https://github.com/treygoff24/delegate-agent/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/treygoff24/delegate-agent/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/treygoff24/delegate-agent/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/treygoff24/delegate-agent/compare/v0.17.0...v0.18.0

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/PKG-INFO

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

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/docs/cli-reference.md

@@ -803,7 +803,31 @@ records independently. If one current probe fails, its last-known-good record
 is retained and the refresh response lists that harness in `staleHarnesses`.
 If the configured executable selector changes, cached reads mark that harness
 stale and ordinary launches ignore only that harness's record until refresh.
-Cached reads never run `--version` merely to test staleness.
+Cached reads never run `--version` merely to test staleness, and neither does an
+ordinary launch: a cached record can only be short of what the harness now
+supports, never claim more, so one that satisfies the run is used as-is.
+
+A launch re-probes `--version` for its own harness only when the cached record
+has already cost the run something: it refused an explicit `--reasoning-effort`,
+or it silently dropped a configured `defaultReasoningEffort` (a configured
+default degrades to a warning instead of failing the launch, so nothing else
+would signal it). An in-place upgrade behind an unchanged selector is the reason
+either can be wrong, so the probe compares the live banner against the version
+stored in the record, and a mismatch drops the record and rebuilds the run
+against config and bundled capabilities. If the refreshed picture cannot satisfy
+a configured default either, the run proceeds as it already had — a probe never
+turns a launch that succeeded into one that fails.
+
+The reverse case is not covered: a harness that *removes* a capability leaves
+its record listing more than the harness now supports, which produces no refusal
+and therefore no probe. Run `capabilities refresh` after an upgrade that narrows
+what a harness accepts. The result carries a warning naming
+`capabilities refresh <engine>`, because the superseded record stays on disk
+until a refresh rewrites it. The probe fails open — an error, a timeout, or an
+unrecognized banner leaves the original refusal standing — except when the
+banner positively names a *different* known harness, which fails the run with
+`harness_identity_mismatch` rather than handing one harness's argv and sandbox
+policy to another. Dry runs never probe at all.
 
 All automatic probes run with `shell=False`, stdin closed, a neutral temporary
 working directory, bounded output, and a timeout. They pass the active profile
@@ -1079,11 +1103,13 @@ delegate worktree show <handle>
 delegate worktree show --latest HARNESS
 delegate worktree remove <handle|--group NAME> [--discard-uncommitted] [--force-branch] [--force] [--keep-branch]
 delegate worktree prune [--merged] [--older-than DAYS] [--harness HARNESS] [--group NAME] [--include-detached] [--dry-run] [--discard-uncommitted] [--force-branch] [--force]
-delegate worktree gc [--dry-run]
+delegate worktree gc [--dry-run] [--all] [--pool PATH]
 ```
 
 `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.
 
+`worktree gc --all` additionally scans the machine-wide worktree pool (`worktrees.dataHome`, default `~/.delegate/worktrees`) and adds a `pool` object with `dataHome`, `scannedWorktrees`, `orphans`, `emptyFingerprintDirs`, and `warnings`. A pool orphan is a pooled worktree whose Git admin directory no longer serves it, classified `source_root_missing` or `worktree_metadata_missing` with the same `safeAction` vocabulary as registry orphans, plus `worktreePath`, `fingerprint`, `sourceGitRoot`, and `gitdir` (null when the backlink is absent). This is the only way to see worktrees whose source repository was deleted along with its `.delegate/` registry, so `--all` is accepted outside a Delegate registry. The pool scan removes nothing at all: orphans are reported because uncommitted work in them is undetectable once the source repository is gone, and empty fingerprint directories are reported for the same hand-clearing rather than reclaimed. Only a settled absence produces an orphan — metadata that could not be read (a symlinked, non-regular, oversized, or unreadable `.git` entry, or an admin directory that could not be inspected) is treated as live and reported in `pool.warnings`, and so is any pool entry modified within the last 15 minutes, since worktree creation writes the directory before its metadata and a concurrent scan would otherwise call a worktree being born an orphan (`worktree_unsettled`, `fingerprint_dir_unsettled`). `pool.warnings` also covers first-level directories whose names are not repository fingerprints, fingerprint directories that hold loose files rather than being empty, and unlistable fingerprint directories. `--pool PATH` scans a specific pool root instead of the configured one, which finds pools left behind by an earlier `worktrees.dataHome`; an explicit `--pool` path that is missing, not a directory, or unreadable is an `invalid_pool_root` error.
+
 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.
 
 Unknown persistent-worktree handles return suggestions scoped to persistent

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/docs/worktrees.md

@@ -216,6 +216,28 @@ delegate worktree gc
 
 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.
 
+## Find pooled worktrees whose repository is gone
+
+```bash
+delegate worktree gc --all
+delegate worktree gc --all --dry-run
+delegate worktree gc --pool ~/.delegate/worktrees
+```
+
+Persistent worktrees live in a machine-global pool under `worktrees.dataHome` (default `~/.delegate/worktrees`), but they are tracked in a run registry inside the source repository. Delete the source repository and its registry goes with it, leaving a pooled worktree that no per-repository `gc` can reach. `--all` finds these by walking the pool directly and reading each worktree's `.git` backlink file as text — the ordinary Git-based checks cannot classify them, because every `git` command fails inside a worktree whose repository is gone. Because a live worktree always has a live backlink, the walk is safe to run across every repository on the machine at once. `--all` works outside a Delegate registry for the same reason.
+
+The scan adds a `pool` object to the JSON with `dataHome`, `scannedWorktrees`, `orphans`, `emptyFingerprintDirs`, and `warnings`. Each orphan carries `worktreePath`, `fingerprint`, the recovered `sourceGitRoot` (null when the layout does not reveal it), `gitdir` (null when the worktree has no `.git` backlink), a `reason`, and a `safeAction`.
+
+A worktree counts as an orphan only when two things are settled. Its `.git` backlink must be definitely gone or definitely unusable — absent, or readable and holding no usable `gitdir:` line. And its Git admin directory must no longer serve it: the admin directory must exist and hold a `gitdir` backfile naming this worktree. Anything that merely *could not be checked* — a `.git` entry that is a symlink, a directory, a FIFO, oversized, or unreadable; an admin directory that could not be inspected — is reported as live and surfaced in `warnings` with reason `worktree_metadata_unverifiable`. A false orphan invites someone to delete real work by hand, while a false live only under-reports, so every unresolved case resolves toward live.
+
+Absence also has to have lasted. Creating a persistent worktree is several steps — Delegate makes the fingerprint directory, then `git worktree add` creates the worktree directory, its `.git` pointer, and the admin directory's backfile — and a scan that lands inside that window sees exactly what a deleted repository leaves behind. Since the scan runs in a different process from the one creating the worktree, and often for a different repository, it has nothing to wait on and judges by age instead: a pool entry modified within the last 15 minutes is reported in `warnings` (`worktree_unsettled`, or `fingerprint_dir_unsettled` for an empty directory) and classified on a later run. An entry whose age cannot be read at all is treated the same way. This delays reporting a genuine orphan by one run at most, since a real orphan's metadata never comes back.
+
+Only first-level directories named like a repository fingerprint (12 lowercase hex characters, as written by `plan_worktree_path`) are treated as Delegate's. The root is whatever you passed, so anything else is skipped without being descended, and is summarized in `warnings` with reason `not_a_pool_fingerprint_dir` — pointing `--pool` at an ordinary directory yields warnings, never orphans or cleanup candidates.
+
+The pool scan removes nothing. With the source repository gone there is no way to tell whether an orphan holds uncommitted work, so removal is a deliberate manual decision — inspect the reported path, rescue anything you need, then delete it yourself. Empty fingerprint directories, left behind when a fingerprint's last worktree was removed, are reported in `emptyFingerprintDirs` for the same hand-clearing; `gc` does not remove those either. "Empty" means the directory holds nothing at all: a fingerprint directory with loose files in it is reported in `warnings` (`fingerprint_dir_not_empty`) instead. Fingerprint directories that could not be listed also appear in `warnings` rather than being reported as empty.
+
+Use `--pool PATH` to scan a pool root that is no longer the configured `dataHome`. An explicitly named `--pool` path must exist and be a readable directory; anything else is an `invalid_pool_root` error rather than a successful scan of nothing, including a root that becomes unreadable between validation and the walk. A configured `dataHome` that does not exist yet is not an error — it just means no pool has been created — and is reported in `pool.warnings`.
+
 ## Security boundary
 
 Worktree isolation is source-checkout isolation, not a full sandbox. The child process may still use credentials, network access, external tools, and absolute paths according to its runtime and host permissions. See [Security model](security-model.md).

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "delegate-agent-cli"
-version = "0.20.0"
+version = "0.21.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.20.0 → delegate_agent_cli-0.21.0}/src/delegate_agent/__init__.py

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

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/src/delegate_agent/capability_commands.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TextIO
@@ -138,9 +139,12 @@ def _refresh_payload(
     *,
     profile: profiles.ProfileResolution,
     engines: tuple[str, ...] | None = None,
+    progress: Callable[[str], None] | None = None,
 ) -> JsonObject:
     try:
-        result = harness_discovery.refresh_discovery(config, profile=profile, engines=engines)
+        result = harness_discovery.refresh_discovery(
+            config, profile=profile, engines=engines, progress=progress
+        )
     except OSError as exc:
         raise CapabilitiesError(
             "capability_refresh_failed",
@@ -215,6 +219,8 @@ def _refresh_payload(
     }
     if drifted_harnesses:
         payload["driftedHarnesses"] = drifted_harnesses
+    if result.get("futureSchemaCache") is True:
+        payload["cacheWriteSkipped"] = harness_discovery.FUTURE_SCHEMA_CACHE_WARNING
     _add_legacy_cache_fields(payload, legacy_path, reasoning_payload)
     return redaction.scrub_public_projection(payload)
 
@@ -229,6 +235,7 @@ def emit(
     profile: profiles.ProfileResolution | None = None,
     discovery: JsonObject | None = None,
     stdout: TextIO,
+    stderr: TextIO | None = None,
 ) -> int:
     active_profile = profile or profiles.resolve_active_profile(
         config,
@@ -236,8 +243,16 @@ def emit(
         cli_override=auth_profile_override,
     )
     if command.refresh:
+        # JSON callers get a clean stdout document and a quiet stderr; the
+        # per-harness line exists for a human watching a cold refresh.
         payload = _refresh_payload(
-            config, workspace, profile=active_profile, engines=command.engines
+            config,
+            workspace,
+            profile=active_profile,
+            engines=command.engines,
+            progress=(
+                None if command.json_mode else harness_discovery.stderr_probe_progress(stderr)
+            ),
         )
     else:
         payload = capabilities_payload(
@@ -252,6 +267,9 @@ def emit(
         delegate_rendering.print_json(payload, stdout)
     else:
         print(f"reasoning capabilities: {payload['cachePath']}", file=stdout)
+        skipped = payload.get("cacheWriteSkipped")
+        if isinstance(skipped, str):
+            print(skipped, file=stdout)
         drifted = payload.get("driftedHarnesses")
         if isinstance(drifted, list) and drifted:
             print(

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/src/delegate_agent/cli.py

@@ -1087,6 +1087,7 @@ def main(
                 json_mode=global_options.json_mode,
                 auth_profile_override=global_options.auth_profile,
                 stdout=stdout,
+                stderr=stderr,
             )
 
         # For run --input-json, pre-read the JSON to discover config from the
@@ -1177,6 +1178,7 @@ def main(
                 profile=discovery_profile,
                 discovery=discovery_snapshot,
                 stdout=stdout,
+                stderr=stderr,
             )
 
         if parsed.subcommand in {

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/src/delegate_agent/cli_parser.py

@@ -2013,6 +2013,8 @@ WORKTREE_OPTION_SPECS: dict[str, dict[str, WorktreeOptionSpec]] = {
     },
     "gc": {
         "--dry-run": ("flag", "dry_run"),
+        "--all": ("flag", "all_pools"),
+        "--pool": ("str", "pool"),
     },
 }
 
@@ -2090,6 +2092,8 @@ def parse_worktree(rest: list[str], json_mode: bool, cwd: str | None) -> ParsedC
         raise DelegateError(
             "unexpected_argument", f"worktree {action} does not accept positional arguments."
         )
+    if action == "gc" and options.get("pool") == "":
+        raise DelegateError("invalid_option_value", "worktree gc --pool requires a path.")
     if action == "show":
         if options.get("latest_harness") is not None:
             if positional:

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.21.0}/src/delegate_agent/command_help.py

@@ -1408,19 +1408,36 @@ COMMAND_SPECS: dict[str, CommandSpec] = {
     "worktree gc": CommandSpec(
         name="worktree gc",
         summary="Garbage-collect orphaned worktree metadata and stale registry entries.",
-        usage=("delegate [--cwd PATH] [--json] worktree gc [--dry-run]",),
+        usage=("delegate [--cwd PATH] [--json] worktree gc [--dry-run] [--all] [--pool PATH]",),
         options=(
             OptionSpec(
                 "--dry-run",
                 None,
                 "Report source roots that would be pruned and un-prunable worktree reasons without changing anything.",
             ),
+            OptionSpec(
+                "--all",
+                None,
+                "Also scan the machine-wide worktree pool for worktrees whose source repository is gone. Reports them; never removes them.",
+            ),
+            OptionSpec(
+                "--pool",
+                "PATH",
+                "Scan this worktree pool root instead of the configured worktrees.dataHome (finds pools left behind by an earlier dataHome). The path must exist and be a readable directory.",
+            ),
         ),
         examples=(
             "delegate worktree gc",
             "delegate worktree gc --dry-run",
+            "delegate worktree gc --all",
+            "delegate worktree gc --all --dry-run",
+        ),
+        notes=(
+            "GC reconciles registry and Git metadata; it never removes worktree paths.",
+            "--all works outside a Delegate registry, since pooled worktrees outlive the repositories that created them.",
+            "Pool orphans are reported, never removed: their uncommitted state cannot be inspected once the source repository is gone.",
+            "The pool scan removes nothing at all, including empty pool directories — it reports them so you can clear them yourself.",
         ),
-        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"),
     ),