coxswain-tools 0.1.0b1__tar.gz

coxswain_tools-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Pfenning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

coxswain_tools-0.1.0b1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: coxswain-tools
+Version: 0.1.0b1
+Summary: Provides the `cox` command, the coxswain's operator tools: run records, traces, cleanup, the HUD, plans. `agent-tools` is kept as an alias for one release.
+License: MIT License
+        
+        Copyright (c) 2026 Patrick Pfenning
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/ppfenning/coxswain-tools
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# agent-tools
+
+Deterministic tools the agent seats call **instead of spending tokens**. Anything
+a seat would otherwise do by reading a file wholesale and reasoning about it —
+summing a run's cost, counting what a traced node did, cleaning up after a run,
+posting to the HUD, serving a plan — is a function here that reads it and answers.
+
+The mould, every time: a pure core with no I/O, the filesystem and the network
+at the edges, dry-run by default where a write is involved, and tests that never
+touch a real run.
+
+## The fifth repository
+
+| Repository | Owns |
+|---|---|
+| [`agent-cartridges`](https://github.com/ppfenning/agent-cartridges) | who a run works for |
+| [`agent-graphs`](https://github.com/ppfenning/agent-graphs) | what runs, and the harness that runs it |
+| [`agent-cast`](https://github.com/ppfenning/agent-cast) | who speaks |
+| [`agent-voice-hud`](https://github.com/ppfenning/agent-voice-hud) | where you hear and see it |
+| **`agent-tools`** | what the seats run so they do not have to think |
+
+Tools that read agent-graphs' records and post to agent-voice-hud belong to
+neither; a seat routes to them by name the way it routes to skills. Nothing here
+names an employer, a tracker, or a person — CI refuses it.
+
+## Install
+
+See [`docs/getting-started.md`](docs/getting-started.md) for the full setup, from cloning all three repositories to a verified first run.
+
+Not yet on PyPI: once the first tag ships, this package will be `coxswain-tools`, installable as `pip install coxswain-tools` or `uv tool install coxswain-tools`.
+
+```bash
+git clone https://github.com/ppfenning/coxswain-tools ~/repos/coxswain-tools
+cd ~/repos/coxswain-tools && uv venv && uv pip install -e ".[dev]"
+uv tool install -e .            # `agent-tools` on PATH for every seat
+```
+
+## Commands
+
+Bare `cox`, with no subcommand, opens the coxswain session: a real Claude Code
+session with the `coxswain` plugin loaded, working directory at the profile's
+`workspace_dir`. `agent-tools` still works this release as an alias for `cox`.
+
+```
+cox runs usage RUN [--runs-dir runs] [--json]   cost, turns, cache share — by role and by model
+cox runs trace RUN [--role build] [-v]          per node: turns, cost, tools, reads, whole-file reads, commands
+cox runs clean RUN --repo PATH [--apply]        the run's worktrees and scratch branches; phase branches kept; dry-run by default
+cox runs land RUN --repo PATH [--task T] [--apply] [--no-merge]   plan and land an approved run: pick branch, cherry-pick, PR, merge on green, clean; dry-run by default
+cox runs events [--runs-dir runs] [--follow] [--json]   tail a run's log, trace and usage files as a live event stream
+cox runs top   — live table of runs in flight (next task wires the screen)
+cox epic watch PIDFILE [--log LOG]              block until a detached run exits (or the cap), then the outcome lines
+cox hud ops FILE|-                              replace the HUD's ops list (id, label, status, persona?, detail?)
+cox hud say TEXT [--persona P] [--voice V]      speak a line through the HUD
+cox hud inbox show|arm|clear                    read, wait for, or clear directives
+cox hud cast                                    the seats the HUD's org ring shows
+cox plan serve DIR [--check] [--no-open]        lint, serve through the local bridge, open in Brave
+cox route context [--json]                      what a session reads at start: team, queued intake, runs in flight, initiatives with ready work; exits 0 even with no profile
+cox route status [--json]                       every run with a pidfile or a log: alive or exited, started, the log's outcome lines
+cox route file --repo PATH --title TEXT [--body FILE|-] [--phase NAME] [--intake]   write a one-task initiative, or with --intake an intake item; exit 2 if a target path exists or the profile is missing
+cox route launch epic --initiative DIR [--repo PATH] [--fix-attempts N] [--dry-run]   start the harness detached with a pidfile and log, and AGENT_GRAPHS_TRACE_DIR set to `<runs_dir>/<run-id>-trace` so every node writes a trace; exit 2 on a missing profile or harness venv, a missing initiative.md, a dirty repo, or a live run of the same initiative
+cox route launch decompose --idea FILE --initiative-id ID [--dry-run]   start the harness detached; exit 2 on a missing profile, harness venv, or idea file
+cox route launch cos [--dry-run]   start the chief of staff detached: it reads intake and runs, dispatches within the bound, and consumes what it dispatched
+cox setup   a small terminal UI over setup doctor, setup install and cartridge init (needs a terminal)
+cox setup doctor [--profile PATH] [--json]      read-only: profile, paths, harness venv, cartridge, skills, provider, workspace — a table and an exit code
+cox setup install --root DIR --team T --workspace DIR [--plugins] [--hook] [--force-profile] [--dry-run]   venvs, agent-tools on PATH, the profile, optionally the provider plugin and a session-start hook; dry-run prints the plan
+cox install --root DIR [--manifest PATH] [--provider NAME] [--with FLAG] [--team T] [--workspace DIR] [--dry-run]   the plan over coxswain's manifest.toml: clone, fetch, skip or refuse per component, then setup_install, doctor, desktop; --dry-run only prints it, otherwise it runs each step and exits 0 only if every step ran clean
+cox upgrade --root DIR [--manifest PATH] [--provider NAME] [--with FLAG] [--team T] [--workspace DIR] [--to VERSION] [--dry-run]   same plan as install, but refuses (exit 2, naming the directory) if any present checkout is dirty; --to overrides every component's pinned tag for this run
+cox versions [--root DIR] [--manifest PATH]     pinned vs. installed tag per component, and status: ok, drift, missing, extra
+```
+
+## Maintainers
+
+`cox dev` holds commands a maintainer of the coxswain repositories runs; nothing
+here is needed to use Coxswain. `cox release` is a one-release alias that prints
+`moved: use cox dev release` and exits 2.
+
+```
+cox dev release VERSION [--dry-run] [--manifest PATH] [--root DIR] [--checkout NAME=PATH] [--umbrella PATH]   the lockstep plan: tag every component, bump the manifest (skipped on a first cut of the declared version), notes, tag_self; exit 2 on refuse (bad semver, an existing tag, a lesser version, or a checkout that is not a ppfenning/coxswain remote); without --dry-run, executes only a first-cut plan — tags and pushes every component and the umbrella in turn, refusing before tagging anything if a checkout is dirty, off its default branch, the release note is missing, or the plan still carries a bump_manifest step (bump and commit the manifest by hand first)
+```
+
+Every command that reads a record is pure over parsed data and unit-tested
+against fixtures; every command that writes is dry-run unless `--apply`.
+
+The `route` group reads one profile, `~/.config/agent-tools/profile.yaml`:
+`team`, `cartridges_dir`, `skills_roots`, `provider_profile`, `harness_dir`,
+`workspace_dir`, and `assume`, the gate answer detached runs are started
+with. `--profile PATH` overrides the location for one command,
+`AGENT_TOOLS_PROFILE` overrides it for a shell, and the default path is read
+when neither is set. Without a profile, `route context` prints one line and
+exits 0; `file`, `launch` and `status` exit 2 and name the path they looked
+for. `--dry-run` on either `launch` prints the argv, the pidfile and the log
+path and starts nothing.
+
+## Why this exists
+
+One day of live epics found every defect by reading a usage file or a trace,
+by hand, in a chief-of-staff's own turns: summing costs, counting Bash calls,
+noticing a node read a 1,900-line file whole. Each of those readings cost
+tokens and produced the same answer every time. They are functions now, and
+the steward seat runs them.

coxswain_tools-0.1.0b1/README.md

@@ -0,0 +1,100 @@
+# agent-tools
+
+Deterministic tools the agent seats call **instead of spending tokens**. Anything
+a seat would otherwise do by reading a file wholesale and reasoning about it —
+summing a run's cost, counting what a traced node did, cleaning up after a run,
+posting to the HUD, serving a plan — is a function here that reads it and answers.
+
+The mould, every time: a pure core with no I/O, the filesystem and the network
+at the edges, dry-run by default where a write is involved, and tests that never
+touch a real run.
+
+## The fifth repository
+
+| Repository | Owns |
+|---|---|
+| [`agent-cartridges`](https://github.com/ppfenning/agent-cartridges) | who a run works for |
+| [`agent-graphs`](https://github.com/ppfenning/agent-graphs) | what runs, and the harness that runs it |
+| [`agent-cast`](https://github.com/ppfenning/agent-cast) | who speaks |
+| [`agent-voice-hud`](https://github.com/ppfenning/agent-voice-hud) | where you hear and see it |
+| **`agent-tools`** | what the seats run so they do not have to think |
+
+Tools that read agent-graphs' records and post to agent-voice-hud belong to
+neither; a seat routes to them by name the way it routes to skills. Nothing here
+names an employer, a tracker, or a person — CI refuses it.
+
+## Install
+
+See [`docs/getting-started.md`](docs/getting-started.md) for the full setup, from cloning all three repositories to a verified first run.
+
+Not yet on PyPI: once the first tag ships, this package will be `coxswain-tools`, installable as `pip install coxswain-tools` or `uv tool install coxswain-tools`.
+
+```bash
+git clone https://github.com/ppfenning/coxswain-tools ~/repos/coxswain-tools
+cd ~/repos/coxswain-tools && uv venv && uv pip install -e ".[dev]"
+uv tool install -e .            # `agent-tools` on PATH for every seat
+```
+
+## Commands
+
+Bare `cox`, with no subcommand, opens the coxswain session: a real Claude Code
+session with the `coxswain` plugin loaded, working directory at the profile's
+`workspace_dir`. `agent-tools` still works this release as an alias for `cox`.
+
+```
+cox runs usage RUN [--runs-dir runs] [--json]   cost, turns, cache share — by role and by model
+cox runs trace RUN [--role build] [-v]          per node: turns, cost, tools, reads, whole-file reads, commands
+cox runs clean RUN --repo PATH [--apply]        the run's worktrees and scratch branches; phase branches kept; dry-run by default
+cox runs land RUN --repo PATH [--task T] [--apply] [--no-merge]   plan and land an approved run: pick branch, cherry-pick, PR, merge on green, clean; dry-run by default
+cox runs events [--runs-dir runs] [--follow] [--json]   tail a run's log, trace and usage files as a live event stream
+cox runs top   — live table of runs in flight (next task wires the screen)
+cox epic watch PIDFILE [--log LOG]              block until a detached run exits (or the cap), then the outcome lines
+cox hud ops FILE|-                              replace the HUD's ops list (id, label, status, persona?, detail?)
+cox hud say TEXT [--persona P] [--voice V]      speak a line through the HUD
+cox hud inbox show|arm|clear                    read, wait for, or clear directives
+cox hud cast                                    the seats the HUD's org ring shows
+cox plan serve DIR [--check] [--no-open]        lint, serve through the local bridge, open in Brave
+cox route context [--json]                      what a session reads at start: team, queued intake, runs in flight, initiatives with ready work; exits 0 even with no profile
+cox route status [--json]                       every run with a pidfile or a log: alive or exited, started, the log's outcome lines
+cox route file --repo PATH --title TEXT [--body FILE|-] [--phase NAME] [--intake]   write a one-task initiative, or with --intake an intake item; exit 2 if a target path exists or the profile is missing
+cox route launch epic --initiative DIR [--repo PATH] [--fix-attempts N] [--dry-run]   start the harness detached with a pidfile and log, and AGENT_GRAPHS_TRACE_DIR set to `<runs_dir>/<run-id>-trace` so every node writes a trace; exit 2 on a missing profile or harness venv, a missing initiative.md, a dirty repo, or a live run of the same initiative
+cox route launch decompose --idea FILE --initiative-id ID [--dry-run]   start the harness detached; exit 2 on a missing profile, harness venv, or idea file
+cox route launch cos [--dry-run]   start the chief of staff detached: it reads intake and runs, dispatches within the bound, and consumes what it dispatched
+cox setup   a small terminal UI over setup doctor, setup install and cartridge init (needs a terminal)
+cox setup doctor [--profile PATH] [--json]      read-only: profile, paths, harness venv, cartridge, skills, provider, workspace — a table and an exit code
+cox setup install --root DIR --team T --workspace DIR [--plugins] [--hook] [--force-profile] [--dry-run]   venvs, agent-tools on PATH, the profile, optionally the provider plugin and a session-start hook; dry-run prints the plan
+cox install --root DIR [--manifest PATH] [--provider NAME] [--with FLAG] [--team T] [--workspace DIR] [--dry-run]   the plan over coxswain's manifest.toml: clone, fetch, skip or refuse per component, then setup_install, doctor, desktop; --dry-run only prints it, otherwise it runs each step and exits 0 only if every step ran clean
+cox upgrade --root DIR [--manifest PATH] [--provider NAME] [--with FLAG] [--team T] [--workspace DIR] [--to VERSION] [--dry-run]   same plan as install, but refuses (exit 2, naming the directory) if any present checkout is dirty; --to overrides every component's pinned tag for this run
+cox versions [--root DIR] [--manifest PATH]     pinned vs. installed tag per component, and status: ok, drift, missing, extra
+```
+
+## Maintainers
+
+`cox dev` holds commands a maintainer of the coxswain repositories runs; nothing
+here is needed to use Coxswain. `cox release` is a one-release alias that prints
+`moved: use cox dev release` and exits 2.
+
+```
+cox dev release VERSION [--dry-run] [--manifest PATH] [--root DIR] [--checkout NAME=PATH] [--umbrella PATH]   the lockstep plan: tag every component, bump the manifest (skipped on a first cut of the declared version), notes, tag_self; exit 2 on refuse (bad semver, an existing tag, a lesser version, or a checkout that is not a ppfenning/coxswain remote); without --dry-run, executes only a first-cut plan — tags and pushes every component and the umbrella in turn, refusing before tagging anything if a checkout is dirty, off its default branch, the release note is missing, or the plan still carries a bump_manifest step (bump and commit the manifest by hand first)
+```
+
+Every command that reads a record is pure over parsed data and unit-tested
+against fixtures; every command that writes is dry-run unless `--apply`.
+
+The `route` group reads one profile, `~/.config/agent-tools/profile.yaml`:
+`team`, `cartridges_dir`, `skills_roots`, `provider_profile`, `harness_dir`,
+`workspace_dir`, and `assume`, the gate answer detached runs are started
+with. `--profile PATH` overrides the location for one command,
+`AGENT_TOOLS_PROFILE` overrides it for a shell, and the default path is read
+when neither is set. Without a profile, `route context` prints one line and
+exits 0; `file`, `launch` and `status` exit 2 and name the path they looked
+for. `--dry-run` on either `launch` prints the argv, the pidfile and the log
+path and starts nothing.
+
+## Why this exists
+
+One day of live epics found every defect by reading a usage file or a trace,
+by hand, in a chief-of-staff's own turns: summing costs, counting Bash calls,
+noticing a node read a 1,900-line file whole. Each of those readings cost
+tokens and produced the same answer every time. They are functions now, and
+the steward seat runs them.

coxswain_tools-0.1.0b1/agent_tools/__init__.py

@@ -0,0 +1,9 @@
+"""Deterministic tools the agent seats call instead of spending tokens.
+
+The mould, every time: a pure core with no I/O, the filesystem and the network
+at the edges, dry-run where a write is involved, and tests that never touch a
+real run. Anything a seat would otherwise do by reading a file wholesale and
+reasoning about it belongs here as a function that reads it and answers.
+"""
+
+__version__ = "0.1.0"

coxswain_tools-0.1.0b1/agent_tools/cartridge_screen.py

@@ -0,0 +1,98 @@
+"""The effect runner for the cartridge editor: the only place that touches
+a subprocess, writes a fragment, or rewrites the profile file.
+`editor_model.py` decides which `Effect` to run; this module only runs the
+one it is handed. No curses here — that edge is the next task.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from agent_tools.editor_model import Effect
+from agent_tools.fragments import FragmentError, write_fragment
+from agent_tools.route import parse_profile
+from agent_tools.setup_screen import resolved_argv
+
+
+def _write_fragment(effect: Effect, ctx: dict, write) -> dict:
+    team_dir = Path(ctx["cartridges_dir"]) / ctx["team"]
+    try:
+        write(team_dir, effect.payload["edits"])
+    except (FragmentError, OSError) as exc:
+        return {"provenance_error": str(exc)}
+    return {}
+
+
+def _launch(argv: list[str], run):
+    """Runs `argv`; a binary that cannot launch is a value, never an exception
+    out of the loop (`setup_screen.run_action` makes the same promise)."""
+    try:
+        return run(argv, capture_output=True, text=True), None
+    except OSError as exc:
+        return None, f"{argv[0]}: {exc}"
+
+
+def _run_probe(ctx: dict, run) -> dict:
+    result, failure = _launch(list(ctx["probe_argv"]), run)
+    if failure is not None:
+        return {"provenance_error": failure}
+    if result.returncode != 0:
+        return {"provenance_error": result.stderr or f"probe exited {result.returncode}"}
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        return {"provenance_error": str(exc)}
+
+
+def _init_cartridge(effect: Effect, ctx: dict, run) -> dict:
+    name = effect.payload["name"]
+    venv_cartridge = f"{ctx.get('root', '')}/agent-cartridges/.venv/bin/cartridge"
+    argv = resolved_argv(["cartridge", "init", name, "--cartridges-dir", str(ctx["cartridges_dir"]),
+                          "--extends", effect.payload["extends"]],
+                         cartridge_on_path=shutil.which("cartridge") is not None,
+                         venv_cartridge_exists=Path(venv_cartridge).exists(), venv_cartridge=venv_cartridge)
+    result, failure = _launch(argv, run)
+    if failure is not None:
+        return {"returncode": 127, "team": name, "output": failure}
+    output = "\n".join(((result.stdout or "") + (result.stderr or "")).splitlines()[-5:])
+    return {"returncode": result.returncode, "team": name, "output": output}
+
+
+def _set_profile_team(effect: Effect, ctx: dict) -> dict:
+    team = effect.payload["team"]
+    path = Path(ctx["profile_path"])
+    lines = path.read_text().splitlines() if path.exists() else []
+    rewritten = [f"team: {team}" if line.startswith("team:") else line for line in lines]
+    if not any(line.startswith("team:") for line in lines):
+        rewritten.append(f"team: {team}")
+    path.write_text("\n".join(rewritten) + "\n")
+    return {"returncode": 0, "team": team}
+
+
+def run_effect(effect: Effect, ctx: dict, *, run=subprocess.run, write=write_fragment) -> dict:
+    """Runs one `Effect`, chosen by the caller; every branch returns."""
+    if effect.kind == "write_fragment":
+        return _write_fragment(effect, ctx, write)
+    if effect.kind == "run_probe":
+        return _run_probe(ctx, run)
+    if effect.kind == "init_cartridge":
+        return _init_cartridge(effect, ctx, run)
+    if effect.kind == "set_profile_team":
+        return _set_profile_team(effect, ctx)
+    return {"provenance_error": f"unknown effect kind {effect.kind!r}"}
+
+
+def _expanded(value, home: str):
+    if isinstance(value, str) and (value == "~" or value.startswith("~/")):
+        return home + value[1:]
+    if isinstance(value, list):
+        return [_expanded(item, home) for item in value]
+    return value
+
+
+def profile_fields(text: str, home: str) -> dict:
+    """Profile fields, `~` expanded against `home` — never `$HOME`/`expanduser()`."""
+    return {key: _expanded(value, home) for key, value in parse_profile(text).items()}

coxswain_tools-0.1.0b1/agent_tools/cleanup.py

@@ -0,0 +1,63 @@
+"""Clean up after a harness run: its worktrees and scratch branches, never its phase branches.
+
+Pure planning, then one edge that runs git. Dry-run is the default; nothing is
+removed unless asked. A phase branch (`epic/<initiative>/<phase>`) is what the
+next run stacks on and is never touched; the task branches
+(`agents/<run-id>/<task>`) and the scratch branches (`<phase>--<task>`) belong
+to a finished run and go.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+__all__ = ["apply_cleanup", "git_branches", "git_worktrees", "plan_cleanup"]
+
+
+def _git(repo: Path, *args: str) -> str:
+    return subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True).stdout
+
+
+def git_worktrees(repo: Path) -> list[str]:
+    return [line.split(" ", 1)[1] for line in _git(repo, "worktree", "list", "--porcelain").splitlines() if line.startswith("worktree ")]
+
+
+def git_branches(repo: Path) -> list[str]:
+    return [line.lstrip("*+ ").strip() for line in _git(repo, "branch", "--list").splitlines() if line.strip()]
+
+
+def plan_cleanup(*, run_id: str, worktrees: Sequence[str], branches: Sequence[str], worktree_root: str) -> dict[str, Any]:
+    """Pure: what a run left behind. Phase branches are listed as kept, explicitly."""
+    root = str(Path(worktree_root).expanduser()) + "/" + run_id
+    doomed_worktrees = [w for w in worktrees if w.startswith(root + "/") or w == root]
+    doomed_branches = [b for b in branches if b.startswith(f"agents/{run_id}/") or ("--" in b and b.startswith("epic/"))]
+    kept = [b for b in branches if b.startswith("epic/") and "--" not in b]
+    return {"run_id": run_id, "worktrees": doomed_worktrees, "branches": doomed_branches, "kept_phase_branches": kept, "root": root}
+
+
+def apply_cleanup(repo: Path | str, plan: dict[str, Any], *, dry_run: bool = True) -> list[str]:
+    """The edge. Returns what was (or would be) done, one line each."""
+    repo = Path(repo)
+    lines = []
+    for w in plan["worktrees"]:
+        lines.append(f"{'would remove' if dry_run else 'removed'} worktree {w}")
+        if not dry_run:
+            subprocess.run(["git", "-C", str(repo), "worktree", "remove", "--force", w], capture_output=True)
+    if not dry_run:
+        subprocess.run(["git", "-C", str(repo), "worktree", "prune"], capture_output=True)
+    for b in plan["branches"]:
+        lines.append(f"{'would delete' if dry_run else 'deleted'} branch {b}")
+        if not dry_run:
+            subprocess.run(["git", "-C", str(repo), "branch", "-D", b], capture_output=True)
+    root = Path(plan["root"])
+    if root.exists():
+        lines.append(f"{'would remove' if dry_run else 'removed'} directory {root}")
+        if not dry_run:
+            import shutil
+            shutil.rmtree(root, ignore_errors=True)
+    for b in plan["kept_phase_branches"]:
+        lines.append(f"kept phase branch {b}")
+    return lines