tdd-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/CHANGELOG.md

@@ -6,6 +6,19 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-24
+
+### Added
+
+- **`tdd run abandon`: end a run that will not be finished** (#150). `tdd run abandon
+  --reason <text>` ends the worktree's live or blocked run with `outcome = abandoned`;
+  `--run <id>` does the same for a run whose worktree is gone. It records the reason and
+  who did it (account and executor) in a new `abandonment` table, counts as a human
+  intervention, and releases the worktree's claims. `tdd fleet` stops listing the run,
+  `tdd metrics` reports it with an `abandoned: {reason, by}` entry, and a new run can
+  start at the same path. The table is added on open; the ledger schema version is
+  unchanged.
+
 ## [0.13.0] - 2026-09-23
 
 ### Added

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Ledger-backed TDD process controller for autonomous coding agents
 Project-URL: Homepage, https://github.com/geuben/tdd-cli
 Project-URL: Repository, https://github.com/geuben/tdd-cli
@@ -296,6 +296,26 @@ When the last declared cycle closes, the tool gathers every path that appeared i
   emitted (visible in `tdd metrics` and the friction log) and the run completes. The event
   makes a silent drop visible without blocking, since the file is already gone.
 
+### Abandoning a run
+
+A run that will not be finished — stopped on purpose, or blocked for good — is ended with
+`tdd run abandon --reason "<why>"` rather than `resume --unblock`. It takes the worktree's
+live run, else its most recent blocked run. It sets the run's `outcome` to `abandoned`,
+records the reason and who abandoned it (the account, and the executor identity as `run
+start` resolves it; on a split runner the account is the calling agent's `SUDO_USER`),
+records a `human_intervention`, and releases the worktree's baseline and advance claims.
+`tdd fleet` stops listing the run, `tdd metrics` reports it as `abandoned` with an
+`abandoned: {reason, by}` entry, and a new run can start at the same worktree path.
+
+When the worktree is gone, abandon by id from any worktree of the repo: `tdd run abandon
+--run <id> --reason "<why>"`. `--run` is accepted only for a run whose worktree no longer
+exists or is the caller's own, so one agent cannot end another's live run.
+
+Refusals, under `result.reason`, write nothing: `reason_required` (blank reason),
+`no_run` (no live or blocked run here), `run_not_found`, `run_ended` (already complete or
+abandoned), `worktree_exists` (`--run` names another worktree that still exists), and
+`advance_in_flight` (a live `tdd advance` holds the worktree; a stale claim is released).
+
 The gate composes with `ancillary_files`: declared paths never fire `undeclared_file_touched`,
 so they are never seen by the gate.
 
@@ -495,6 +515,7 @@ and is never reclassified as a pin.
 | `tdd note "<text>"` | attach a free-text narrative note to the current cycle or run |
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
+| `tdd run abandon --reason <text> [--run <id>]` | end a run that will not be finished; human only |
 | `tdd log render [--out]` | project the ledger into a friction log |
 | `tdd metrics` | fidelity, attempts, violations, interventions, time |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/README.md

@@ -268,6 +268,26 @@ When the last declared cycle closes, the tool gathers every path that appeared i
   emitted (visible in `tdd metrics` and the friction log) and the run completes. The event
   makes a silent drop visible without blocking, since the file is already gone.
 
+### Abandoning a run
+
+A run that will not be finished — stopped on purpose, or blocked for good — is ended with
+`tdd run abandon --reason "<why>"` rather than `resume --unblock`. It takes the worktree's
+live run, else its most recent blocked run. It sets the run's `outcome` to `abandoned`,
+records the reason and who abandoned it (the account, and the executor identity as `run
+start` resolves it; on a split runner the account is the calling agent's `SUDO_USER`),
+records a `human_intervention`, and releases the worktree's baseline and advance claims.
+`tdd fleet` stops listing the run, `tdd metrics` reports it as `abandoned` with an
+`abandoned: {reason, by}` entry, and a new run can start at the same worktree path.
+
+When the worktree is gone, abandon by id from any worktree of the repo: `tdd run abandon
+--run <id> --reason "<why>"`. `--run` is accepted only for a run whose worktree no longer
+exists or is the caller's own, so one agent cannot end another's live run.
+
+Refusals, under `result.reason`, write nothing: `reason_required` (blank reason),
+`no_run` (no live or blocked run here), `run_not_found`, `run_ended` (already complete or
+abandoned), `worktree_exists` (`--run` names another worktree that still exists), and
+`advance_in_flight` (a live `tdd advance` holds the worktree; a stale claim is released).
+
 The gate composes with `ancillary_files`: declared paths never fire `undeclared_file_touched`,
 so they are never seen by the gate.
 
@@ -467,6 +487,7 @@ and is never reclassified as a pin.
 | `tdd note "<text>"` | attach a free-text narrative note to the current cycle or run |
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
+| `tdd run abandon --reason <text> [--run <id>]` | end a run that will not be finished; human only |
 | `tdd log render [--out]` | project the ledger into a friction log |
 | `tdd metrics` | fidelity, attempts, violations, interventions, time |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/docs/PRD.md

@@ -528,6 +528,7 @@ one has no move left but to re-run doctor and read the same output again.
 | `tdd blocker --kind <k> --detail <text>` | record a typed blocker; set run `outcome = blocked`, releasing the stop hook (H1) |
 | `tdd resume` | reconstruct position from the ledger and emit `next_action` |
 | `tdd resume --unblock --note <text>` | **human only.** Reopen a blocked run, recording a `human_intervention` event with the note |
+| `tdd run abandon --reason <text> [--run <id>]` | **human only.** End a live or blocked run that will not be finished: `outcome = abandoned`, an `abandonment` row (reason, account, executor), a `human_intervention` event, and the worktree's claims released. `--run` only for a run whose worktree is gone or is the caller's own |
 
 - **R8.7** A blocked run is not live. H1 must permit the agent to stop, or a blocker traps it.
 - **R8.8** `human_intervention` events are the input to interventions-per-run, the primary

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/src/tddcli/__init__.py

@@ -3,4 +3,4 @@
 State is derived from observed test execution, never asserted by the caller.
 """
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/src/tddcli/cli.py

@@ -1264,6 +1264,14 @@ def _accept_failures_into_baseline(
     return accepted, refused
 
 
+def _latest_blocked_run(ledger: Ledger, worktree: Path) -> sqlite3.Row | None:
+    return ledger.one(
+        "SELECT * FROM run WHERE worktree_path = ? AND outcome = 'blocked'"
+        " ORDER BY id DESC LIMIT 1",
+        (str(worktree),),
+    )
+
+
 def cmd_resume(args) -> Envelope:
     worktree = _worktree()
     cfg = config_mod.load(worktree)
@@ -1278,11 +1286,7 @@ def cmd_resume(args) -> Envelope:
     if args.unblock:
         if run is not None:
             return failure("run is already live; --unblock applies to a blocked run")
-        blocked = ledger.one(
-            "SELECT * FROM run WHERE worktree_path = ? AND outcome = 'blocked'"
-            " ORDER BY id DESC LIMIT 1",
-            (str(worktree),),
-        )
+        blocked = _latest_blocked_run(ledger, worktree)
         if blocked is None:
             return failure("no blocked run to unblock in this worktree")
         if not args.note:
@@ -1321,6 +1325,68 @@ def cmd_resume(args) -> Envelope:
     )
 
 
+def _calling_account() -> str:
+    """The account that asked. On a split runner that is the agent behind sudo, which
+    sets `SUDO_USER` itself; elsewhere the effective uid. Never `getpass.getuser()`: it
+    trusts `LOGNAME`/`USER`, which the caller controls."""
+    split = runner_mod.load()
+    if split is not None and split.role == "runner" and os.environ.get("SUDO_USER"):
+        return os.environ["SUDO_USER"]
+    return pwd.getpwuid(os.geteuid()).pw_name
+
+
+def cmd_run_abandon(args) -> Envelope:
+    if not args.reason.strip():
+        return failure("--reason must say why the run is abandoned", reason="reason_required")
+    worktree = _worktree()
+    ledger = Ledger(gitutil.repo_identity(worktree))
+    if args.run is not None:
+        run = ledger.one("SELECT * FROM run WHERE id = ?", (args.run,))
+        if run is None:
+            return failure(f"no run {args.run} in this ledger", reason="run_not_found")
+        if run["ended_at"] is not None and run["outcome"] != "blocked":
+            return failure(f"run {args.run} already ended {run['outcome']}", reason="run_ended")
+        # By id only when the worktree is gone or is the caller's own: on a split runner
+        # every agent reaches the same ledger, and one must not end another's live run.
+        if run["worktree_path"] != str(worktree) and Path(run["worktree_path"]).exists():
+            return failure(
+                f"run {args.run}'s worktree {run['worktree_path']} still exists;"
+                " abandon it from there",
+                reason="worktree_exists",
+            )
+    else:
+        run = ledger.active_run(str(worktree)) or _latest_blocked_run(ledger, worktree)
+        if run is None:
+            return failure("no live or blocked run in this worktree", reason="no_run")
+    # A stale claim is released below, not obeyed; a live one means an advance is mid-flight.
+    claim = ledger.active_advance_claim(run["worktree_path"])
+    if claim is not None and not claim["stale"]:
+        return failure(
+            f"an advance is in flight (pid {claim['pid']}); stop it first",
+            reason="advance_in_flight",
+            pid=claim["pid"],
+        )
+    executor = identity.resolve(worktree)
+    at = now()
+    ledger.update("run", run["id"], ended_at=at, outcome="abandoned")
+    ledger.insert(
+        "abandonment",
+        run_id=run["id"],
+        reason=args.reason,
+        account=_calling_account(),
+        executor_model=executor.model,
+        executor_source=executor.source,
+        at=at,
+    )
+    ledger.insert("human_intervention", run_id=run["id"], note=f"abandoned: {args.reason}", at=at)
+    ledger.release_claim(run["worktree_path"])
+    ledger.release_advance_claim(run["worktree_path"])
+    return Envelope(
+        result={"run_id": run["id"]},
+        next_action=NextAction(Verb.COMPLETE, f"Run {run['id']} abandoned."),
+    )
+
+
 def cmd_sensitivity(args) -> Envelope:
     worktree, cfg, ledger, run = _context()
     cycle = ledger.open_cycle(run["id"])
@@ -1709,6 +1775,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     s.set_defaults(fn=cmd_run_start)
 
+    s = run_p.add_parser("abandon", help="end a run that will not be finished; human only")
+    s.add_argument("--reason", required=True)
+    s.add_argument("--run", type=int, default=None, help="a run whose worktree is gone")
+    s.set_defaults(fn=cmd_run_abandon)
+
     s = sub.add_parser("status")
     s.set_defaults(fn=cmd_status)
 

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/src/tddcli/ledger.py

@@ -260,6 +260,16 @@ CREATE TABLE IF NOT EXISTS human_intervention (
     at TEXT NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS abandonment (
+    id INTEGER PRIMARY KEY,
+    run_id INTEGER NOT NULL UNIQUE REFERENCES run(id),
+    reason TEXT NOT NULL,
+    account TEXT NOT NULL,
+    executor_model TEXT NOT NULL,
+    executor_source TEXT NOT NULL,
+    at TEXT NOT NULL
+);
+
 CREATE TABLE IF NOT EXISTS baseline_cache (
     id INTEGER PRIMARY KEY,
     project TEXT NOT NULL,

{tdd_cli-0.13.0 → tdd_cli-0.14.0}/src/tddcli/render.py

@@ -441,4 +441,14 @@ def metrics(ledger: Ledger, worktree: str) -> dict:
                 },
             }
         )
+        abandonment = ledger.one("SELECT * FROM abandonment WHERE run_id = ?", (run["id"],))
+        if abandonment is not None:
+            out["runs"][-1]["abandoned"] = {
+                "reason": abandonment["reason"],
+                "by": {
+                    "account": abandonment["account"],
+                    "executor": abandonment["executor_model"],
+                    "executor_source": abandonment["executor_source"],
+                },
+            }
     return out

tdd_cli-0.14.0/tests/test_run_abandon.py

@@ -0,0 +1,256 @@
+"""`tdd run abandon`: end a run that will not be finished (issue #150)."""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+
+from conftest import current_user, git, run_cli, write_plan
+from tddcli import gitutil
+from tddcli.ledger import Ledger
+
+PLAN = """---
+cycles:
+  - n: 1
+    project: backend
+    title: "adding"
+    test: "tests/test_add.py::test_add_two_numbers"
+---
+# Plan
+"""
+
+
+def ledger(repo):
+    return Ledger(gitutil.repo_identity(repo))
+
+
+def register(repo):
+    plan = write_plan(repo, PLAN)
+    run_cli(repo, "plan", "register", plan)
+    return plan
+
+
+def start(path, plan):
+    out = run_cli(path, "run", "start", "--plan", plan)
+    assert out["ok"], out
+    return out
+
+
+def outcome(repo, run_id):
+    return ledger(repo).one("SELECT outcome FROM run WHERE id = ?", (run_id,))["outcome"]
+
+
+def last_run_id(repo):
+    return ledger(repo).one("SELECT id FROM run ORDER BY id DESC LIMIT 1")["id"]
+
+
+def add_worktree(repo, path):
+    git(repo, "worktree", "add", "-q", "--detach", str(path))
+    return path
+
+
+def remove_worktree(repo, path):
+    git(repo, "worktree", "remove", "--force", str(path))
+
+
+def test_abandon_ends_the_live_run_as_abandoned(repo):
+    plan = register(repo)
+    start(repo, plan)
+
+    run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    row = ledger(repo).one("SELECT outcome, ended_at FROM run")
+    assert (row["outcome"], row["ended_at"] is not None) == ("abandoned", True)
+
+
+def test_metrics_reports_the_reason_and_who_abandoned_the_run(repo):
+    plan = register(repo)
+    start(repo, plan)
+
+    run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    entry = run_cli(repo, "metrics")["result"]["runs"][0]
+    assert entry.get("abandoned") == {
+        "reason": "superseded by #145",
+        "by": {
+            "account": current_user(),
+            "executor": "pytest-executor",
+            "executor_source": "declared",
+        },
+    }
+
+
+def test_abandoning_records_a_human_intervention(repo):
+    plan = register(repo)
+    start(repo, plan)
+
+    run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    notes = [r["note"] for r in ledger(repo).all("SELECT note FROM human_intervention")]
+    assert notes == ["abandoned: superseded by #145"]
+
+
+def test_fleet_stops_listing_an_abandoned_run(repo):
+    plan = register(repo)
+    start(repo, plan)
+
+    run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    assert run_cli(repo, "fleet", "--json")["result"]["runs"] == []
+
+
+def test_abandon_by_id_ends_a_run_whose_worktree_is_gone(repo, tmp_path):
+    plan = register(repo)
+    wt = add_worktree(repo, tmp_path / "wt-a")
+    start(wt, plan)
+    run_id = last_run_id(repo)
+    remove_worktree(repo, wt)
+
+    run_cli(
+        repo,
+        "run",
+        "abandon",
+        "--run",
+        str(run_id),
+        "--reason",
+        "worktree removed; superseded by #145",
+    )
+
+    assert outcome(repo, run_id) == "abandoned"
+
+
+def test_a_new_run_starts_in_a_fresh_worktree_after_abandon(repo, tmp_path):
+    plan = register(repo)
+    wt = add_worktree(repo, tmp_path / "wt-a")
+    start(wt, plan)
+    run_id = last_run_id(repo)
+    remove_worktree(repo, wt)
+    run_cli(repo, "run", "abandon", "--run", str(run_id), "--reason", "superseded by #145")
+
+    add_worktree(repo, wt)
+
+    assert run_cli(wt, "run", "start", "--plan", plan)["ok"] is True
+
+
+def test_abandon_accepts_live_and_blocked_runs_in_every_accepted_form(repo, tmp_path):
+    plan = register(repo)
+
+    # (a) a blocked run in the caller's worktree, without --run
+    start(repo, plan)
+    a_id = last_run_id(repo)
+    run_cli(repo, "blocker", "--kind", "tooling", "--detail", "d")
+    run_cli(repo, "run", "abandon", "--reason", "blocked for good")
+
+    # (b) a blocked run by --run when its worktree is gone
+    wt_b = add_worktree(repo, tmp_path / "wt-b")
+    start(wt_b, plan)
+    b_id = last_run_id(repo)
+    run_cli(wt_b, "blocker", "--kind", "tooling", "--detail", "d")
+    remove_worktree(repo, wt_b)
+    run_cli(repo, "run", "abandon", "--run", str(b_id), "--reason", "blocked and removed")
+
+    # (c) a live run by --run from its own worktree
+    wt_c = add_worktree(repo, tmp_path / "wt-c")
+    start(wt_c, plan)
+    c_id = last_run_id(repo)
+    run_cli(wt_c, "run", "abandon", "--run", str(c_id), "--reason", "own worktree")
+
+    assert [outcome(repo, a_id), outcome(repo, b_id), outcome(repo, c_id)] == [
+        "abandoned",
+        "abandoned",
+        "abandoned",
+    ]
+
+
+def test_abandon_refuses_a_blank_reason(repo):
+    plan = register(repo)
+    start(repo, plan)
+    run_id = last_run_id(repo)
+
+    out = run_cli(repo, "run", "abandon", "--reason", "   ")
+
+    assert (out["result"].get("reason"), outcome(repo, run_id)) == ("reason_required", None)
+
+
+def test_abandon_without_a_live_or_blocked_run_is_refused(repo):
+    plan = register(repo)
+    start(repo, plan)
+    run_cli(repo, "cycle", "skip", "--reason", "r")
+
+    out = run_cli(repo, "run", "abandon", "--reason", "nothing to end")
+
+    assert out["result"].get("reason") == "no_run"
+
+
+def test_abandon_refuses_an_unknown_run_id(repo):
+    register(repo)
+
+    out = run_cli(repo, "run", "abandon", "--run", "999", "--reason", "x")
+
+    assert out["result"].get("reason") == "run_not_found"
+
+
+def test_abandon_refuses_a_run_that_already_ended(repo):
+    plan = register(repo)
+    start(repo, plan)
+    a_id = last_run_id(repo)
+    run_cli(repo, "cycle", "skip", "--reason", "r")
+    start(repo, plan)
+    b_id = last_run_id(repo)
+    run_cli(repo, "run", "abandon", "--reason", "superseded")
+
+    a = run_cli(repo, "run", "abandon", "--run", str(a_id), "--reason", "x")
+    b = run_cli(repo, "run", "abandon", "--run", str(b_id), "--reason", "x")
+
+    assert [a["result"].get("reason"), b["result"].get("reason")] == ["run_ended", "run_ended"]
+
+
+def test_abandon_by_id_refuses_a_run_whose_worktree_still_exists(repo, tmp_path):
+    plan = register(repo)
+    wt = add_worktree(repo, tmp_path / "wt-d")
+    start(wt, plan)
+    run_id = last_run_id(repo)
+
+    out = run_cli(repo, "run", "abandon", "--run", str(run_id), "--reason", "x")
+
+    assert (out["result"].get("reason"), outcome(repo, run_id)) == ("worktree_exists", None)
+
+
+def test_abandoning_releases_the_worktrees_claims(repo):
+    plan = register(repo)
+    start(repo, plan)
+    wt = str(gitutil.worktree_root(repo))
+    dead = subprocess.Popen(["true"])
+    dead.wait()
+    claims = ledger(repo)
+    claims.claim(wt, socket.gethostname(), dead.pid, 1)
+    claims.claim_advance(wt, socket.gethostname(), dead.pid)
+
+    run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    f = run_cli(repo, "fleet", "--json")["result"]
+    assert (f["collecting"], f["advancing"]) == ([], [])
+
+
+def test_abandon_refuses_while_an_advance_is_in_flight(repo):
+    plan = register(repo)
+    start(repo, plan)
+    run_id = last_run_id(repo)
+    wt = str(gitutil.worktree_root(repo))
+    ledger(repo).claim_advance(wt, socket.gethostname(), os.getpid())
+
+    out = run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    assert (out["result"].get("reason"), outcome(repo, run_id)) == ("advance_in_flight", None)
+
+
+def test_a_split_runner_records_the_calling_agent_as_the_account(repo, split_runner, monkeypatch):
+    monkeypatch.setenv("SUDO_USER", "agent-7")
+    plan = register(repo)
+    start(repo, plan)
+
+    run_cli(repo, "run", "abandon", "--reason", "superseded by #145")
+
+    entry = run_cli(repo, "metrics")["result"]["runs"][0]
+    assert entry["abandoned"]["by"]["account"] == "agent-7"