tdd-cli 0.1.0__py3-none-any.whl

tddcli/fleet.py

@@ -0,0 +1,128 @@
+"""Fleet view — every agent's progress on this repository, in one summary.
+
+The ledger is one SQLite database per repository, shared by all worktrees, so the
+data already exists in one place; this module only reads it. Read-only is
+structural, not conventional: the database is opened with SQLite's `mode=ro` URI,
+so the command cannot create, migrate, or mutate the ledger that live agents are
+writing mid-run. That is what makes it safe to run — from any worktree, on any
+branch — while runs are in flight, even if this code's schema constant were ever
+to drift from the one on disk.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import leases
+
+
+def open_readonly(path: Path) -> sqlite3.Connection | None:
+    """None when no ledger exists yet — `mode=ro` also refuses to create one."""
+    if not path.is_file():
+        return None
+    conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _age_s(iso: str | None) -> float | None:
+    if not iso:
+        return None
+    stamp = datetime.fromisoformat(iso)
+    if stamp.tzinfo is None:
+        stamp = stamp.replace(tzinfo=timezone.utc)
+    return round((datetime.now(timezone.utc) - stamp).total_seconds(), 1)
+
+
+def _runs(conn: sqlite3.Connection) -> list[dict]:
+    rows = conn.execute(
+        "SELECT r.id, r.worktree_path, r.executor_model, r.started_at,"
+        "       p.plan_path, p.declared_cycles"
+        " FROM run r JOIN plan_contract p ON p.id = r.plan_contract_id"
+        " WHERE r.ended_at IS NULL ORDER BY r.id"
+    ).fetchall()
+    out = []
+    for row in rows:
+        cycle = conn.execute(
+            "SELECT ordinal, phase, title FROM cycle"
+            " WHERE run_id = ? AND closed_at IS NULL ORDER BY ordinal LIMIT 1",
+            (row["id"],),
+        ).fetchone()
+        last = conn.execute(
+            "SELECT MAX(started_at) AS at FROM invocation WHERE run_id = ?",
+            (row["id"],),
+        ).fetchone()
+        out.append(
+            {
+                "run_id": row["id"],
+                "worktree": row["worktree_path"],
+                "plan": row["plan_path"],
+                "executor": row["executor_model"],
+                "started_at": row["started_at"],
+                "cycle": cycle["ordinal"] if cycle else None,
+                "of": len(json.loads(row["declared_cycles"])) or None,
+                "phase": cycle["phase"] if cycle else None,
+                "title": cycle["title"] if cycle else None,
+                # Staleness signal for a wedged agent: age of the newest suite
+                # invocation, falling back to run start when none has landed yet.
+                "last_activity_age_s": _age_s(last["at"] or row["started_at"]),
+            }
+        )
+    return out
+
+
+def _claims(conn: sqlite3.Connection) -> list[dict]:
+    rows = conn.execute("SELECT * FROM baseline_claim ORDER BY id").fetchall()
+    return [
+        {
+            "worktree": r["worktree_path"],
+            "hostname": r["hostname"],
+            "projects_done": r["projects_done"],
+            "projects_total": r["projects_total"],
+            "current_project": r["current_project"],
+            "elapsed_s": _age_s(r["started_at"]),
+        }
+        for r in rows
+    ]
+
+
+def summarise(ledger_db: Path) -> dict:
+    conn = open_readonly(ledger_db)
+    if conn is None:
+        return {"runs": [], "collecting": [], "suites": leases.snapshot()}
+    try:
+        return {
+            "runs": _runs(conn),
+            "collecting": _claims(conn),
+            "suites": leases.snapshot(),
+        }
+    finally:
+        conn.close()
+
+
+def render(summary: dict) -> str:
+    lines = []
+    for r in summary["runs"]:
+        cycle = f"cycle {r['cycle']}/{r['of']}" if r["cycle"] else "between cycles"
+        title = f" ({r['title']})" if r.get("title") else ""
+        lines.append(
+            f"{r['worktree']}  {r['plan']}  {cycle}{title}  {r['phase'] or '-'}"
+            f"  last activity {r['last_activity_age_s']}s ago"
+        )
+    for c in summary["collecting"]:
+        lines.append(
+            f"{c['worktree']}  collecting baseline"
+            f" {c['projects_done']}/{c['projects_total']}"
+            f" (current: {c['current_project'] or '-'}) — {c['elapsed_s']}s elapsed"
+        )
+    s = summary["suites"]
+    lines.append(
+        f"suites executing now: {s['active']}"
+        f" — {s['workers_each']} worker(s) each of {s['total_cores']} cores"
+    )
+    if not summary["runs"] and not summary["collecting"]:
+        lines.insert(0, "no active runs")
+    return "\n".join(lines) + "\n"

tddcli/gitutil.py

@@ -0,0 +1,138 @@
+"""Git access. Every call is explicit about its worktree; nothing is resolved from cwd."""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from pathlib import Path
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def git(worktree: Path, *args: str, check: bool = True) -> str:
+    proc = subprocess.run(
+        ["git", "-C", str(worktree), *args],
+        capture_output=True,
+        text=True,
+    )
+    if check and proc.returncode != 0:
+        raise GitError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def worktree_root(start: Path) -> Path:
+    out = git(start, "rev-parse", "--show-toplevel").strip()
+    if not out:
+        raise GitError(f"not a git worktree: {start}")
+    return Path(out).resolve()
+
+
+def repo_identity(worktree: Path) -> Path:
+    """The canonical repository path — the *common* git dir, shared by all worktrees.
+
+    R13.3: the ledger is keyed by this, not by the worktree, so pruning a worktree
+    never orphans its runs.
+    """
+    common = git(worktree, "rev-parse", "--path-format=absolute", "--git-common-dir").strip()
+    return Path(common).resolve().parent
+
+
+def head(worktree: Path) -> str:
+    return git(worktree, "rev-parse", "HEAD").strip()
+
+
+def blob_sha_at_head(worktree: Path, rel_path: str) -> tuple[str, str]:
+    """(blob_sha, commit_sha) for a path as committed — never the working-tree copy."""
+    commit = head(worktree)
+    out = git(worktree, "rev-parse", f"HEAD:{rel_path}", check=False).strip()
+    if not out or " " in out:
+        raise GitError(f"{rel_path} is not committed at HEAD")
+    return out, commit
+
+
+def show_at_head(worktree: Path, rel_path: str) -> str:
+    return git(worktree, "show", f"HEAD:{rel_path}")
+
+
+def tracked_at_head(worktree: Path, paths: list[str]) -> set[str]:
+    """Which of `paths` exist in the HEAD commit — so a path absent here is a new file."""
+    if not paths:
+        return set()
+    out = git(worktree, "ls-tree", "-r", "--name-only", "-z", "HEAD", "--", *paths)
+    return {p for p in out.split("\0") if p}
+
+
+def status_porcelain(worktree: Path) -> list[tuple[str, str]]:
+    out = git(worktree, "status", "--porcelain=v1", "-uall")
+    entries = []
+    for line in out.splitlines():
+        if not line.strip():
+            continue
+        entries.append((line[:2], line[3:].strip()))
+    return entries
+
+
+def is_dirty(worktree: Path) -> bool:
+    return bool(status_porcelain(worktree))
+
+
+def dirty_paths(worktree: Path) -> set[str]:
+    return {path for _, path in status_porcelain(worktree)}
+
+
+def changed_paths(worktree: Path) -> set[str]:
+    """Tracked modifications plus untracked files, relative to the worktree root."""
+    return dirty_paths(worktree)
+
+
+def diff_text(worktree: Path) -> str:
+    return git(worktree, "diff")
+
+
+def tree_hash(worktree: Path, roots: list[str]) -> str:
+    """Hash of tracked content under the given roots, plus untracked file contents.
+
+    Backs `no_change_since_last_run` (§6) and the refactor-phase skip (§6.1).
+    """
+    h = hashlib.sha256()
+    for root in sorted(roots):
+        h.update(root.encode())
+        h.update(git(worktree, "ls-files", "-s", "--", root).encode())
+        diff = git(worktree, "diff", "--", root)
+        h.update(diff.encode())
+        untracked = git(worktree, "ls-files", "-o", "--exclude-standard", "--", root)
+        for rel in sorted(untracked.split()):
+            h.update(rel.encode())
+            p = worktree / rel
+            if p.is_file():
+                h.update(p.read_bytes())
+    return h.hexdigest()
+
+
+def add(worktree: Path, paths: list[str]) -> None:
+    if paths:
+        git(worktree, "add", "--", *paths)
+
+
+def reset_index(worktree: Path) -> None:
+    git(worktree, "reset", "-q")
+
+
+def commit(worktree: Path, message: str, trailers: dict[str, str]) -> str:
+    body = message
+    if trailers:
+        body += "\n\n" + "\n".join(f"{k}: {v}" for k, v in trailers.items())
+    git(worktree, "commit", "-q", "-m", body)
+    return head(worktree)
+
+
+def checkout_paths(worktree: Path, paths: list[str]) -> None:
+    if paths:
+        git(worktree, "checkout", "--", *paths)
+
+
+def staged_paths(worktree: Path) -> list[str]:
+    out = git(worktree, "diff", "--cached", "--name-only")
+    return [p for p in out.splitlines() if p.strip()]

tddcli/identity.py

@@ -0,0 +1,82 @@
+"""Executor identity resolution (§5.1).
+
+The harness exposes a session id but not the model, so the model is read from the
+session transcript. Agents never supply identity by any path (R5.2) — the human
+fallback exists for hosts where the transcript is unavailable.
+
+Known limit: an in-process subagent inherits its parent's CLAUDE_CODE_SESSION_ID and
+writes no transcript under TRANSCRIPT_ROOT, so a run it starts resolves to the
+parent's model. Model comparisons require executors in top-level sessions.
+
+All harness coupling lives in this one module (R5.1): a transcript format change
+breaks here and nowhere else.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+TRANSCRIPT_ROOT = Path.home() / ".claude" / "projects"
+
+
+@dataclass
+class Executor:
+    model: str
+    session: str | None
+    source: str          # transcript | human | unknown
+
+
+def _slug(path: Path) -> str:
+    return str(path).replace(os.sep, "-")
+
+
+def _find_transcript(session_id: str, project_path: Path | None) -> Path | None:
+    candidates: list[Path] = []
+    if project_path is not None:
+        scoped = TRANSCRIPT_ROOT / _slug(project_path) / f"{session_id}.jsonl"
+        candidates.append(scoped)
+    if TRANSCRIPT_ROOT.is_dir():
+        candidates.extend(TRANSCRIPT_ROOT.glob(f"*/{session_id}.jsonl"))
+    for c in candidates:
+        if c.is_file():
+            return c
+    return None
+
+
+def _model_from_transcript(path: Path) -> str | None:
+    """Last model wins — a session may switch models mid-run."""
+    found = None
+    try:
+        with path.open() as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or '"model"' not in line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                model = rec.get("model") or (rec.get("message") or {}).get("model")
+                if isinstance(model, str) and model:
+                    found = model
+    except OSError:
+        return None
+    return found
+
+
+def resolve(project_path: Path | None = None, human_label: str | None = None) -> Executor:
+    session = os.environ.get("CLAUDE_CODE_SESSION_ID")
+    if session:
+        transcript = _find_transcript(session, project_path)
+        if transcript is not None:
+            model = _model_from_transcript(transcript)
+            if model:
+                return Executor(model=model, session=session, source="transcript")
+
+    if human_label:
+        return Executor(model=human_label, session=session, source="human")
+
+    return Executor(model="unknown", session=session, source="unknown")

tddcli/leases.py

@@ -0,0 +1,118 @@
+"""Machine-wide test-worker budget.
+
+Several agents run tdd-cli concurrently on one machine, each in its own worktree.
+With no coordination each had to pin its suite to `-n 1` — the only setting that
+never oversubscribes the box — which serialises every suite even when the agent is
+alone. This module gives each in-flight suite invocation an even share of the
+machine's cores instead: a lease file per invocation in a directory shared across
+worktrees, `workers = max(1, cores // live_leases)`.
+
+Deliberate properties:
+
+* The split is computed once, at lease acquisition. An agent that arrives mid-run
+  gets the smaller share immediately; the earlier agent's share corrects on its
+  next invocation. Suites are short relative to a run, so the imbalance is
+  transient and never oversubscribes by more than one suite's worth.
+* No lock file. Each lease is its own uniquely-named file, created before
+  counting, so two simultaneous arrivals each see the other. The remaining race
+  (counting before the other's create lands) costs one transiently generous
+  split, not a corrupted state.
+* Stale leases must not throttle a machine forever: a lease whose pid is dead is
+  swept, and so is one older than STALE_AFTER_S — a suite invocation cannot
+  legitimately outlive run_command's timeout, so twice that bounds a live lease.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import time
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+
+LEASE_DIR_ENV = "TDD_LEASE_DIR"
+CORE_BUDGET_ENV = "TDD_CORE_BUDGET"
+
+#: run_command's timeout is 1800s; no live suite invocation can be older than that.
+STALE_AFTER_S = 3600
+
+
+def lease_dir() -> Path:
+    env = os.environ.get(LEASE_DIR_ENV)
+    if env:
+        return Path(env)
+    return Path.home() / ".cache" / "tdd-cli" / "leases"
+
+
+def _total_cores() -> int:
+    """CORE_BUDGET lets an operator reserve headroom (agents themselves need CPU)."""
+    with contextlib.suppress(ValueError):
+        budget = int(os.environ.get(CORE_BUDGET_ENV, "0"))
+        if budget > 0:
+            return budget
+    return os.cpu_count() or 1
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists, owned by someone else
+    return True
+
+
+def _is_live(path: Path) -> bool:
+    try:
+        if time.time() - path.stat().st_mtime > STALE_AFTER_S:
+            return False
+        payload = json.loads(path.read_text())
+        pid = int(payload["pid"])
+    except (OSError, ValueError, KeyError, json.JSONDecodeError):
+        return False
+    return _pid_alive(pid)
+
+
+def _live_count(directory: Path) -> int:
+    """Count live leases, sweeping the rest so a crash never throttles the machine."""
+    live = 0
+    for path in directory.glob("*.json"):
+        if _is_live(path):
+            live += 1
+        else:
+            with contextlib.suppress(OSError):
+                path.unlink()
+    return live
+
+
+def snapshot() -> dict:
+    """Observe the budget without participating in it — counts live leases but
+    sweeps nothing and takes nothing, so a fleet view never perturbs the split."""
+    directory = lease_dir()
+    total = _total_cores()
+    live = 0
+    if directory.is_dir():
+        live = sum(1 for path in directory.glob("*.json") if _is_live(path))
+    return {
+        "active": live,
+        "total_cores": total,
+        "workers_each": max(1, total // max(1, live)),
+    }
+
+
+@contextlib.contextmanager
+def worker_lease(total_cores: int | None = None) -> Iterator[int]:
+    """Hold a lease for one suite invocation; yields the worker count to use."""
+    directory = lease_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    total = total_cores or _total_cores()
+    mine = directory / f"{os.getpid()}-{uuid.uuid4().hex}.json"
+    mine.write_text(json.dumps({"pid": os.getpid(), "started_at": time.time()}))
+    try:
+        yield max(1, total // max(1, _live_count(directory)))
+    finally:
+        with contextlib.suppress(OSError):
+            mine.unlink()