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

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

@@ -6,6 +6,64 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-23
+
+### Added
+
+- **Where a run's time went** (#147). `tdd metrics` gains a per-run `time` object:
+  `wall_clock_s`, `suite_s`, `suite_share` and `by_phase` (runs and suite seconds for
+  every phase recorded). A live run's wall clock runs to now. The friction log gains a
+  `## Time` section with the same split, a per-phase table and a per-cycle table
+  (wall clock, suite time and suite runs). Nothing new is recorded: these are the
+  ledger's existing timestamps and `invocation.duration_ms`.
+- **Split mode: a ledger the agent's account cannot open** (#142). With
+  `/etc/tdd-cli/runner.toml` in place, a separate runner account owns the ledger
+  in a mode-700 directory. The agent's `tdd` forwards every verb except `docs`
+  and `init` to it through `sudo`, and the runner executes every suite, gate,
+  hook and git command as the agent. Executor identity is recorded as `operator`
+  when the runner's config assigns the calling account a model, and `claimed`
+  otherwise. `tdd runner import <ledger>` brings an existing ledger under the
+  runner, marked `pre_split_import`, which `tdd metrics` reports. Setup and a
+  verification checklist: `tdd docs split`.
+- `tdd doctor` reports `mode` (`single` or `split`). In split mode it probes,
+  live and as the agent, that the uid drop works, that the agent cannot read the
+  ledger, and that it cannot write the install.
+
+### Changed
+
+- **GREEN runs the target first** (#149). An `AWAITING_IMPL` advance whose target
+  still fails now says so after running only the target. A passing target is followed
+  by the whole-suite run that decides GREEN, as before. `tdd metrics` counts
+  `impl_attempts` from each advance's target-only run only, and still counts every
+  `AWAITING_IMPL` run in cycles recorded before this change.
+- `tdd doctor` on a single-user machine no longer lets "ledger outside
+  worktree" stand for isolation: a `ledger isolation` notice says the ledger is
+  owned by the same uid that runs the agent. The README and SECURITY.md say the
+  same. Single-user installs behave exactly as before.
+- **RED runs only the target test** (#148). `AWAITING_TEST`, `AWAITING_PIN` and
+  `tdd sensitivity check` now run the target alone: pytest runs the owning suite's
+  collect command with the node id, and vitest filters to the file and an anchored,
+  escaped `-t` name. A failure elsewhere no longer blocks RED. It is caught at
+  GREEN, which runs the whole suite for **every** adapter. A collection error in
+  the target's own file is still `not_collected`. A target adopted in place of the
+  declared id is run in the same advance. The ledger is now schema 12:
+  `invocation.others_observed` is `0` for a target-only run.
+
+### Fixed
+
+- **GREEN ran only the target on cargo, gradle, xctest and exec** (#153), so a
+  regression elsewhere reached the close sweep unseen, and the sweep could skip the
+  cycle's own project without the whole suite ever running. These adapters now
+  narrow only when asked for a target-only run.
+
+- **The close sweep re-ran a tree that had just passed** (#146): `gitutil.tree_hash` hashed git
+  state (index entries plus the unstaged diff), so the same content hashed differently before
+  and after the GREEN commit, and the §6.1 skip of a cycle's own suites never fired. It now
+  hashes working-tree content through a throwaway index, independent of what is staged or
+  committed. A skipped close sweep still runs the cycle project's lint/typecheck gates; before
+  this fix, the skip would have dropped them too. `--reuse-baselines` cache entries written by
+  earlier versions no longer match and are re-probed once.
+
 ## [0.12.2] - 2026-09-17
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.12.2
+Version: 0.13.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
@@ -48,8 +48,15 @@ stop silently mid-plan; and no record comparable across runs, plans, or models.
 
 This tool removes the agent from the reporting path. It runs the suites itself, computes
 every phase transition from what the tests observably did, and records the whole run in a
-ledger the agent cannot reach — which is also what makes the friction logs and metrics at
-the end trustworthy.
+ledger outside the worktree — which is what the friction logs and metrics at the end rest
+on.
+
+How far out of reach that ledger is depends on the machine. On a single-user install it
+belongs to the same account that runs the agent: an agent that edits files in its checkout
+cannot touch it, but one that goes looking for it can. In **split mode** a separate runner
+account owns the ledger and runs the agent's suites *as the agent*, so the agent's account
+cannot open it at all. `tdd doctor` says which mode a machine is in; `tdd docs split` sets
+the second one up.
 
 ## Install
 
@@ -323,7 +330,8 @@ cycle's RED path empirically, assigns cycle kinds, and authors the contract —
 back to the **planning** process. It reports plan fidelity (declared vs delivered vs
 skipped vs never-reached cycles, human interventions) and, per cycle: the target, suite
 runs by phase, the first-run outcome against expectation, sensitivity checks, commits,
-and integrity events.
+and integrity events. A `## Time` section says where the run's time went: the wall clock,
+suite time and its share, per phase and per cycle.
 
 Every observable fact in it is projected from recorded events. The agent that did the
 work cannot compose it — that is what makes it worth reading, and why the log is
@@ -348,7 +356,8 @@ rendered, never written. Judgement enters in exactly two ways:
   narrative as the agent's opinion.
 
 `tdd metrics` is the quantitative companion: attempts per cycle, RED-first violation
-rate, fidelity, blockers, interventions. Cross-plan aggregates are deliberately labelled
+rate, fidelity, blockers, interventions, and suite time per phase against the run's wall
+clock. Cross-plan aggregates are deliberately labelled
 non-comparable — cycle difficulty varies too much — so compare runs of the same contract
 only (e.g. the same plan executed by two models).
 
@@ -487,7 +496,7 @@ and is never reclassified as a pin.
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
 | `tdd log render [--out]` | project the ledger into a friction log |
-| `tdd metrics` | fidelity, attempts, violations, interventions |
+| `tdd metrics` | fidelity, attempts, violations, interventions, time |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |
 
 ## Scoped baseline capture (R9.5c)
@@ -670,6 +679,24 @@ One SQLite ledger **per repository**, in `~/.local/share/tdd-cli/` (override wit
 from the current directory, never committed. `worktree_path` is a column, so concurrent runs
 in separate worktrees are isolated without a pruned worktree orphaning its history.
 
+That file is owned by whoever runs `tdd`. On a single-user machine that is the agent's own
+account, so "outside the worktree" is all the separation there is, and `tdd doctor` reports
+`mode: single` and says so. **Split mode** gives the ledger to a runner account the agent
+cannot become:
+
+- the agent's `tdd` forwards every verb except `docs` and `init` to the runner, through one
+  `sudoers` line;
+- the runner keeps the ledger in a mode-700 directory of its own and ignores the caller's
+  `TDD_LEDGER_HOME`;
+- suites, gates, hooks and git all run as the agent, in the agent's worktree;
+- executor identity is `operator` when the runner's config assigns the calling account a
+  model, and `claimed` otherwise;
+- `tdd runner import <ledger>` brings an existing ledger under the runner, marked as
+  pre-split history that `tdd metrics` reports.
+
+`tdd docs split` ([docs/split-runner.md](docs/split-runner.md)) has the setup, the
+verification checklist, and what split mode does not protect against.
+
 ## Enforcement boundary
 
 The CLI cannot compel an agent — only the harness can.

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

@@ -20,8 +20,15 @@ stop silently mid-plan; and no record comparable across runs, plans, or models.
 
 This tool removes the agent from the reporting path. It runs the suites itself, computes
 every phase transition from what the tests observably did, and records the whole run in a
-ledger the agent cannot reach — which is also what makes the friction logs and metrics at
-the end trustworthy.
+ledger outside the worktree — which is what the friction logs and metrics at the end rest
+on.
+
+How far out of reach that ledger is depends on the machine. On a single-user install it
+belongs to the same account that runs the agent: an agent that edits files in its checkout
+cannot touch it, but one that goes looking for it can. In **split mode** a separate runner
+account owns the ledger and runs the agent's suites *as the agent*, so the agent's account
+cannot open it at all. `tdd doctor` says which mode a machine is in; `tdd docs split` sets
+the second one up.
 
 ## Install
 
@@ -295,7 +302,8 @@ cycle's RED path empirically, assigns cycle kinds, and authors the contract —
 back to the **planning** process. It reports plan fidelity (declared vs delivered vs
 skipped vs never-reached cycles, human interventions) and, per cycle: the target, suite
 runs by phase, the first-run outcome against expectation, sensitivity checks, commits,
-and integrity events.
+and integrity events. A `## Time` section says where the run's time went: the wall clock,
+suite time and its share, per phase and per cycle.
 
 Every observable fact in it is projected from recorded events. The agent that did the
 work cannot compose it — that is what makes it worth reading, and why the log is
@@ -320,7 +328,8 @@ rendered, never written. Judgement enters in exactly two ways:
   narrative as the agent's opinion.
 
 `tdd metrics` is the quantitative companion: attempts per cycle, RED-first violation
-rate, fidelity, blockers, interventions. Cross-plan aggregates are deliberately labelled
+rate, fidelity, blockers, interventions, and suite time per phase against the run's wall
+clock. Cross-plan aggregates are deliberately labelled
 non-comparable — cycle difficulty varies too much — so compare runs of the same contract
 only (e.g. the same plan executed by two models).
 
@@ -459,7 +468,7 @@ and is never reclassified as a pin.
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
 | `tdd log render [--out]` | project the ledger into a friction log |
-| `tdd metrics` | fidelity, attempts, violations, interventions |
+| `tdd metrics` | fidelity, attempts, violations, interventions, time |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |
 
 ## Scoped baseline capture (R9.5c)
@@ -642,6 +651,24 @@ One SQLite ledger **per repository**, in `~/.local/share/tdd-cli/` (override wit
 from the current directory, never committed. `worktree_path` is a column, so concurrent runs
 in separate worktrees are isolated without a pruned worktree orphaning its history.
 
+That file is owned by whoever runs `tdd`. On a single-user machine that is the agent's own
+account, so "outside the worktree" is all the separation there is, and `tdd doctor` reports
+`mode: single` and says so. **Split mode** gives the ledger to a runner account the agent
+cannot become:
+
+- the agent's `tdd` forwards every verb except `docs` and `init` to the runner, through one
+  `sudoers` line;
+- the runner keeps the ledger in a mode-700 directory of its own and ignores the caller's
+  `TDD_LEDGER_HOME`;
+- suites, gates, hooks and git all run as the agent, in the agent's worktree;
+- executor identity is `operator` when the runner's config assigns the calling account a
+  model, and `claimed` otherwise;
+- `tdd runner import <ledger>` brings an existing ledger under the runner, marked as
+  pre-split history that `tdd metrics` reports.
+
+`tdd docs split` ([docs/split-runner.md](docs/split-runner.md)) has the setup, the
+verification checklist, and what split mode does not protect against.
+
 ## Enforcement boundary
 
 The CLI cannot compel an agent — only the harness can.

{tdd_cli-0.12.2 → tdd_cli-0.13.0}/SECURITY.md

@@ -16,6 +16,16 @@ Other properties worth knowing:
   plain SQLite. It records test ids, file paths, diffs (for sensitivity
   checks), and executor identity — treat it with the same sensitivity as the
   repository itself.
+- **On a single-user install the ledger is writable by the account that runs
+  the agent.** It has no triggers, hash chain or signature: an agent that looks
+  for it can edit it, and nothing records that it did. `tdd doctor` reports
+  this as `mode: single`. Where the record has to hold against the agent
+  itself, use split mode (`tdd docs split`): a separate runner account owns the
+  ledger, reached through one `sudoers` rule, and runs the agent's commands as
+  the agent. Split mode adds a privilege boundary to your machine; review the
+  two sudoers lines it needs as you would any other.
+- Split mode does not make a test report trustworthy. Suites run as the agent,
+  and the runner parses what they write as data.
 - `tdd fleet` opens the ledger read-only and never writes.
 - Worker leases live in `~/.cache/tdd-cli/leases` and contain hostnames and
   pids, nothing else.

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

@@ -134,6 +134,12 @@ visible at the moment it can still be fixed.
 - **R5.2** Agents never supply executor identity by any path. Step 3 is a human affordance.
 - **R5.3** Resolution requires the tool to run on the same host as the agent. Remote or CI
   execution can set `TDD_EXECUTOR_MODEL` to declare the answer explicitly.
+- **R5.3a** In split mode (R13.10) every source above is the agent's to write, and none of it
+  is in the runner's environment or home. The runner therefore records one of two things. If
+  its own config assigns the calling account (`SUDO_USER`) a model, that model with source
+  `operator`. Otherwise the ordinary resolution runs on the agent's side and its answer is
+  recorded with source `claimed`, so a comparison between models can exclude it. `unknown`
+  stays `unknown`. R5.2 holds across the boundary: no verb carries an identity.
 
 ### Cycle
 | Field | Notes |
@@ -155,6 +161,7 @@ One execution of one project's test suite. **Never overwritten; append-only.**
 | `target_failure_excerpt` | truncated |
 | `total_passed`, `total_failed` | |
 | `other_failures` | after baseline subtraction (§9.2) |
+| `others_observed` | `1` when the run could see failures outside the target; `0` for a target-only run (R9.1a), whose `other_failures` is `[]` because nothing else ran, not because nothing else failed |
 | `lint_outcome`, `typecheck_outcome` | per §9.4 |
 | `duration_ms`, `started_at` | |
 
@@ -223,8 +230,8 @@ AWAITING_TEST ──advance──▶ AWAITING_IMPL ──advance──▶ AWAITI
 
 | Phase | Agent's job | `advance` passes when |
 |---|---|---|
-| `AWAITING_TEST` | write exactly one failing test | target **fails**, no new failures elsewhere |
-| `AWAITING_IMPL` | write the minimum implementation | target **passes**, no new failures elsewhere |
+| `AWAITING_TEST` | write exactly one failing test | target **fails**; only the target runs (R9.1a) |
+| `AWAITING_IMPL` | write the minimum implementation | target **passes**, no new failures elsewhere; the target runs first, and the whole suite only once it passes (R9.1b, R9.1e) |
 | `AWAITING_REFACTOR` | refactor, or nothing | lint/typecheck clean and the close sweep green (R9.2). The cycle's own suites are **skipped** when the tree hash is unchanged since the GREEN commit — they just passed on an identical tree. The downstream sweep always runs, having not run yet. |
 
 Outcomes that are not simple advancement:
@@ -343,8 +350,9 @@ Requirements:
 - **R7.8** Generator tools that are not hand-edited during TDD — `codegen` being the motivating
   case — are modelled as artifact regeneration commands, never as projects.
 - **R7.12** A project declares its own suite command (`test_command`, and `collect_command` for
-  collection). Adapters append only reporting flags: parallelism, plugins and markers stay
-  exactly as the project declared, so the suite under TDD is the suite the team trusts.
+  collection). Adapters append only reporting flags — and, for a target-only run (R9.1a),
+  the selector that picks the target: parallelism, plugins and markers stay exactly as the
+  project declared, so the suite under TDD is the suite the team trusts.
 - **R7.13** A project may declare **per-pattern suite overrides**: an alternate `test_command`
   (plus optional `collect_command` and `env`) for files matching a root-relative pattern.
   Collection and suite runs union the default suite with every override suite, so a cycle can
@@ -567,9 +575,34 @@ For the passed-on-arrival case, which occurred in 4 of 8 executed cycles in the
 ## 9. Execution semantics
 
 ### 9.1 Regression scope
-- **R9.1** During `AWAITING_TEST` and `AWAITING_IMPL`, the suites of the **union of projects named
-  by the cycle's targets** run. For an ordinary cycle that is one project; for a contract cycle
-  (§9.3) it is all projects the cycle spans.
+- **R9.1** A cycle's phases run in the **union of projects named by the cycle's targets**. For an
+  ordinary cycle that is one project; for a contract cycle (§9.3) it is all projects the cycle
+  spans. How much of each project's suite runs depends on the phase (R9.1a–R9.1c).
+- **R9.1a** `AWAITING_TEST` and `AWAITING_PIN` run **only the target tests**, for every adapter
+  that can select a single test id. RED asks one question: does the named test fail? A collection
+  error in the target's own file is still caught, because it is reported for the target itself,
+  and it remains `not_collected` (§6.1). Failures elsewhere are **not observed** at RED: the
+  invocation records `others_observed = 0`, and RED is never blocked by failures outside the
+  cycle. A target adopted in place of the declared id (R8.9) is run in the same advance when
+  the target-only run did not execute it.
+- **R9.1b** `AWAITING_IMPL` runs the **whole suite** of each project, for **every** adapter,
+  and reads the target outcome from that run. This is what makes R9.1a safe. A RED that breaks
+  a shared fixture or helper is caught at GREEN, and it is blamed on the same cycle, because the
+  GREEN invocation carries the cycle id. It is also what lets the close sweep skip the cycle's own
+  suites when the tree is unchanged since GREEN (§6.1).
+- **R9.1c** `tdd sensitivity check` runs only the target tests. It asks whether the target fails
+  with the mutation in place, and nothing else.
+- **R9.1d** Rationale: on a 33-second suite, running the whole suite at RED cost 16 minutes of a
+  72-minute run (#145), and the time grows with suite size. The guarantee that every phase sees
+  the whole suite is given up at RED only. GREEN keeps it, because a whole-suite run at GREEN is
+  what blames a regression on a cycle. Decided in #148.
+- **R9.1e** Each `AWAITING_IMPL` advance runs **the targets alone first**. If any target does
+  not pass, the reply is `write_implementation` and nothing else runs: a still-failing target is
+  all a failed attempt has to report. Only when every target passes does the whole-suite run of
+  R9.1b follow, and it alone decides GREEN, so a passing GREEN proves exactly what R9.1b says. That
+  whole-suite run is the attempt's last invocation, which is the one the close sweep's skip
+  compares against (§6.1). A target that fails while something else also broke is reported first;
+  the other breakage is reported once the target passes. Decided in #149.
 - **R9.2** On the transition out of `AWAITING_REFACTOR`, the close sweep runs: the cycle's own
   projects, plus every project **downstream of an artifact the cycle modified** per the
   `consumed_by` edges in §7.1, plus lint and typecheck for each. Projects with
@@ -645,6 +678,8 @@ For the passed-on-arrival case, which occurred in 4 of 8 executed cycles in the
   wrong reused baseline is recoverable via `resume --unblock --accept-failures` (R9.5b),
   which treats a reused baseline row as an ordinary row, for tests that fail at the start sha.
 - **R9.6** Baseline failures are subtracted from `other_failures` in every subsequent invocation.
+  A target-only invocation (R9.1a) has nothing to subtract from: it records `others_observed = 0`,
+  and its empty `other_failures` must not be read as a clean run.
   A baseline row is only ever captured from `run.start_sha`, never from the current tree.
 - **R9.7** A baseline failure that starts passing is recorded, not ignored.
 - **R9.5g** `run start` refuses a baseline whose failure ratio exceeds the implausibility threshold
@@ -835,14 +870,15 @@ Adapter.typecheck(project)               -> GateResult
 | Fact | Source |
 |---|---|
 | RED-first violation | invocation verdict in `AWAITING_TEST` |
-| Implementation attempts | `COUNT(invocation)` where phase = `AWAITING_IMPL` |
+| Implementation attempts | `COUNT(invocation)` where phase = `AWAITING_IMPL` and `others_observed = 0`: the target-only run every attempt starts with (R9.1e). A cycle recorded before R9.1e has none, and counts every `AWAITING_IMPL` invocation |
 | Convergence vs thrash | trajectory of `other_failures` across attempts in a cycle |
 | Implementation written during RED | staged-set classification at the RED commit (R9.14) — exact, both languages |
 | Stub-only *content* during RED | Python: `ast` check that added function bodies are sentinels. TypeScript: line-count heuristic only. **The metric is labelled partial for TS rather than reported as uniform.** Secondary to R9.14 |
 | Tests removed or weakened | `collect()` set diff + assertion-count diff, minus `modifies_tests` |
 | Files outside declared blast radius | `git diff --name-only` vs contract |
 | Commits per cycle | commit trailers (§13.3) |
-| Suite duration, wall clock, cost | invocation records |
+| Suite duration and wall clock | `invocation.duration_ms` summed per phase and per cycle; wall clock from `run.started_at`/`ended_at` (to now while live) and `cycle.opened_at`/`closed_at` — reported by `tdd metrics` (`time`) and the friction log's `## Time` section |
+| Cost | not recorded |
 | Plan fidelity | declared vs executed cycles and tests |
 
 ### 11.2 Contributed by the agent
@@ -905,6 +941,21 @@ depend on any of them being installed.
 - **R13.5** Rationale: keying by worktree path orphans a run's entire history when the worktree is
   pruned — a live condition in the motivating repository. A repo-level ledger also makes
   cross-worktree metrics a `GROUP BY` rather than a merge.
+- **R13.3a** The "per-user data directory" is the directory of whoever runs `tdd`. On a
+  single-user install that is the agent's own account: the ledger is outside the worktree and
+  no further out of reach than that, and `tdd doctor` must say so (`mode: single`, the
+  `ledger isolation` notice) rather than claim isolation.
+- **R13.10** **Split mode.** A machine with `/etc/tdd-cli/runner.toml` has a *runner* account
+  that owns the ledger in a mode-700 directory and ignores the caller's `TDD_LEDGER_HOME`. Every
+  other account is a *client*: its `tdd` answers `docs` and `init` itself and forwards every
+  other verb, verbatim, to the runner through `sudo`. The runner executes every suite, gate,
+  hook and git command as the calling account and observes the results from outside; it never
+  acts as itself in the agent's territory, and with no caller it refuses to act. The config is
+  trusted only when owned by root or by the account reading it and not writable by others.
+  `tdd doctor` verifies, live and as the agent, that the uid drop works, that the agent cannot
+  read the ledger, and that it cannot write the install. `tdd runner import` brings an existing
+  ledger under the runner and marks it `pre_split_import`. Split mode is one machine's
+  arrangement; it adds no daemon, so R13.7 below stands.
 
 ### 13.3 Git integration
 - **R13.6** Commits made during a run carry `TDD-Run`, `TDD-Cycle` and `TDD-Phase` trailers.

{tdd_cli-0.12.2 → tdd_cli-0.13.0}/docs/harness-integration.md

@@ -71,8 +71,8 @@ skill that duplicates any of it will fight the ledger.
 |---|---|---|
 | `write_test` | the cycle needs its test (or the test still fails to fail correctly) | write the declared target test — for a pin cycle, a characterisation test that passes on arrival — then `tdd advance` |
 | `create_stub` | the target test cannot be collected: the module it imports does not exist | create the declared stub file(s) with no logic — the `detail` quotes the language's idiom — then `tdd advance` |
-| `write_implementation` | RED is confirmed and committed | write the minimum code to pass the target, then `tdd advance` |
-| `fix_regression` | tests outside the cycle are failing, or the close sweep / lint / typecheck gates failed | fix them without breaking the target, then `tdd advance` |
+| `write_implementation` | RED is confirmed and committed, or the target still fails at GREEN (only the target ran) | write the minimum code to pass the target, then `tdd advance` |
+| `fix_regression` | tests outside the cycle are failing at GREEN, or the close sweep / lint / typecheck gates failed | fix them without breaking the target, then `tdd advance` |
 | `run_sensitivity_check` | a test passed where proof it *can* fail is required | `tdd sensitivity begin`, mutate the behaviour under test, `tdd sensitivity check`, then `tdd sensitivity end` |
 | `name_target_test` | several new tests appeared; a cycle covers one behaviour | pick the intended one: `tdd target <id>` |
 | `refactor_or_advance` | GREEN is committed, or the tool simply wants `tdd advance` next | refactor only if the plan calls for it, then `tdd advance` |

tdd_cli-0.13.0/docs/split-runner.md

@@ -0,0 +1,187 @@
+# Split mode: a ledger the agent cannot reach
+
+On a single-user machine the ledger is a SQLite file owned by the account that runs
+`tdd`, which is the account the agent runs as. The agent cannot reach it by editing its
+worktree, but it can reach it by looking: `sqlite3 ~/.local/share/tdd-cli/*.sqlite3`
+opens it, and nothing in the file says afterwards that anyone did. `tdd doctor` reports
+this as `mode: single` and says so in its `ledger isolation` check.
+
+Split mode moves the ledger, and the process that observes the tests, to a second
+account:
+
+- A **runner** account owns the ledger, in a directory only it can open (mode 700).
+- The agent's `tdd` does nothing itself except `docs` and `init`. For every other verb
+  it asks the runner, through `sudo`.
+- The runner runs every suite, gate, artifact hook and git command **as the agent**,
+  in the agent's worktree, and reads the results from outside. The agent's code never
+  runs as the account that owns the ledger.
+
+The command surface is unchanged. No verb accepts a phase, a cycle number or an
+identity on either side of the boundary.
+
+This is one machine's arrangement. Each machine has its own runner and its own ledger.
+
+## What it does and does not protect
+
+It stops the agent's account from reading or writing the ledger, and from running code
+as the account that can.
+
+It does not stop:
+
+- **A forged test report.** The suite runs as the agent, so a test can write whatever
+  report it likes. The runner parses reports as data and never executes them, but it
+  cannot know a passing report is honest. This is the same on a single-user machine.
+- **A client-side downgrade.** An agent can point its own `tdd` at a config of its own
+  (`TDD_RUNNER_CONFIG`), or install a second copy of tdd-cli, and record a run in a
+  ledger it owns. Nothing is forged by that: the run is simply absent from the runner's
+  ledger, which is the only one to trust. Read runs from the runner's ledger.
+
+## Setup
+
+You need root for this. Examples use `tdd-runner` for the runner account and `agent1`
+for the agent's.
+
+### 1. The runner account
+
+Create a system account with a home directory and no login shell you hand out.
+On Linux: `useradd --system --create-home --shell /usr/sbin/nologin tdd-runner`.
+On macOS: `sysadminctl -addUser tdd-runner -home /var/tdd-runner` (then hide it if you
+wish).
+
+### 2. Install tdd-cli where the agent cannot write
+
+A runner whose code the agent can edit is the agent. Install for the runner as root:
+
+    python3 -m venv /opt/tdd-cli
+    /opt/tdd-cli/bin/pip install tdd-cli
+
+It must be readable and executable by the agent's account: the runner runs small
+helpers from this install *as the agent* (`python -m tddcli.agentfs`,
+`python -m tddcli.identity`). It must not be writable by it.
+
+The agent's own `tdd` can be this same binary or a separate install; both read the same
+config and become a client.
+
+### 3. sudoers
+
+Two lines, in a file under `/etc/sudoers.d/` (edit with `visudo -f`):
+
+    agent1      ALL=(tdd-runner) NOPASSWD: /opt/tdd-cli/bin/tdd
+    tdd-runner  ALL=(agent1)     NOPASSWD:SETENV: ALL
+
+The first lets the agent ask the runner, and only through that one binary. The second
+lets the runner act as the agent. Add one pair per agent account.
+
+Four things to get right:
+
+- **`SETENV:` is required** on the second line. The runner passes the agent's own
+  environment to the agent's commands with `sudo -E`; without the tag sudo answers
+  "sorry, you are not allowed to preserve the environment" and `tdd doctor` fails its
+  `runs as the agent` check.
+- **`NOPASSWD` is required on both.** `tdd` always passes `-n`, so a rule that would
+  prompt fails at once instead of hanging an unattended agent.
+- **Leave `env_reset` on** (it is sudo's default). It is what strips the agent's
+  `TDD_LEDGER_HOME`, `TDD_RUNNER_CONFIG` and `PYTHONPATH` on the way to the runner.
+- **Nothing to configure for `HOME` or the working directory.** The client passes `-H`,
+  because macOS sudo would otherwise leave `HOME` pointing at the agent's and the
+  runner's ledger home would follow it. sudo keeps the caller's working directory, which
+  is how the runner knows which worktree it was asked about.
+
+### 4. The config file
+
+`/etc/tdd-cli/runner.toml`, owned by root, mode 644:
+
+    [runner]
+    user        = "tdd-runner"
+    command     = "/opt/tdd-cli/bin/tdd"   # the path the first sudoers line names
+    # sudo      = "/usr/bin/sudo"          # the default
+    # ledger_home = "/var/lib/tdd-cli"     # default: ~tdd-runner/.local/share/tdd-cli
+
+    [executor]                             # optional, see "Executor identity"
+    agent1 = "claude-fable-5-1"
+
+A process whose account is `user` is the runner. Every other process on the machine is
+a client. With no file, the machine is single-user and nothing changes.
+
+**The file is trusted only if it is owned by root or by the account reading it, and is
+not group- or world-writable.** Anything else is refused. That is what stops an agent
+handing the runner a config of its own: even if a sudoers rule let `TDD_RUNNER_CONFIG`
+through, the file it named would belong to the agent, and the runner refuses it.
+
+### 5. Let the runner read the worktree
+
+The runner reads the worktree as itself: `tdd.toml`, the test files it globs for, JUnit
+XML under `build/`. The agent's worktree, and the directories above it, must be readable
+and traversable by the runner account (`chmod -R go+rX`, or a shared group). On macOS
+that rules out `~/Desktop`, `~/Documents` and `~/Downloads`, which are mode 700.
+
+The runner never writes there as itself. Commits, the friction log, sensitivity-check
+restores and temporary probe worktrees are all made as the agent.
+
+If a file is unreadable the runner says which, with `reason: "worktree_unreadable"`.
+
+## Verify it
+
+Run these as the agent's account, in a worktree:
+
+1. `tdd doctor` reports `mode: "split"`, `healthy: true`, and these three checks `ok`:
+   - `runs as the agent`: `id -u`, asked through sudo, answered with the agent's uid.
+   - `ledger out of the agent's reach`: `test -r <ledger>`, as the agent, was refused.
+   - `install not writable by the agent`: `test -w <install>`, as the agent, was refused.
+2. `cat ~tdd-runner/.local/share/tdd-cli/*.sqlite3` (or your `ledger_home`) is denied.
+3. Start a run and close a cycle. `git log -1 --format='%an %cn'` shows the agent as
+   author and committer, and `ls -l` on the committed files shows the agent as owner.
+4. `sudo -u tdd-runner /opt/tdd-cli/bin/tdd status`, run by hand from the agent's
+   account, works; the same command naming any other binary is denied.
+
+The project's own test suite cannot do this for you. It runs without root, so it uses a
+stand-in for sudo that does everything except change uid. The three doctor checks are
+the only place the uid change itself is verified, and they run against your real sudo.
+
+## Executor identity
+
+`tdd run start` records which model did the work. Everything it reads on a single-user
+machine (the session id, the transcript, `TDD_EXECUTOR_MODEL`) is the agent's to write,
+so in split mode the runner trusts none of it:
+
+- If the calling account is in `[executor]`, the run records that model with
+  `executor_source: "operator"`. One account per agent slot makes this exact.
+- Otherwise the ordinary resolution runs on the agent's side and the run records what
+  it found with `executor_source: "claimed"`. Leave `claimed` runs out of any comparison
+  between models that has to be defended.
+
+`--executor`, the human label, is a claim like any other in split mode.
+
+## Existing ledgers
+
+A ledger written before the split was reachable by the agent the whole time. The runner
+can keep it, marked as such. From a root shell (so that sudo reports uid 0), or logged
+in as the runner with no sudo at all:
+
+    sudo -u tdd-runner /opt/tdd-cli/bin/tdd runner import /home/agent1/.local/share/tdd-cli/<repo>.sqlite3
+
+The runner must be able to read that file. It copies the ledger into the
+runner's home under the same name, migrates it to the current schema, and records
+`pre_split_import` with the source path, the time, and `last_run_id`. `tdd metrics`
+reports that marker, so anyone comparing runs can see which predate the split.
+
+It refuses when:
+
+- the machine is not split, or the caller is not the runner (`not_split`);
+- an agent's account is the caller (`operator_only`): an agent that could import could
+  hand the runner a history it wrote itself;
+- the runner already holds a ledger of that name (`ledger_exists`). There is no merge.
+  The runner's copy may hold runs recorded out of the agent's reach, and a second import
+  would trade them for ones that were not.
+
+Afterwards, remove the agent's copy so that nothing reads it by mistake.
+
+## Fleet, leases and other details
+
+- Worker leases move with the runner: they live under the runner's `~/.cache/tdd-cli`,
+  so one budget covers every agent account on the machine.
+- `tdd fleet`, `tdd metrics` and `tdd log render` are forwarded like everything else
+  and read the runner's ledger.
+- A runner invoked directly, with no sudo in between, acts for nobody: every verb
+  except `runner import` is refused with `reason: "no_agent"`. It never falls back to
+  running suites as itself.

{tdd_cli-0.12.2 → tdd_cli-0.13.0}/pyproject.toml

@@ -49,6 +49,7 @@ packages = ["src/tddcli"]
 # tests/test_docs_command.py fails if a topic is not included here.
 [tool.hatch.build.targets.wheel.force-include]
 "docs/harness-integration.md" = "tddcli/_docs/docs/harness-integration.md"
+"docs/split-runner.md" = "tddcli/_docs/docs/split-runner.md"
 "examples/plan.md" = "tddcli/_docs/examples/plan.md"
 "examples/skills/tdd-drive/SKILL.md" = "tddcli/_docs/examples/skills/tdd-drive/SKILL.md"
 "examples/skills/tdd-handoff/SKILL.md" = "tddcli/_docs/examples/skills/tdd-handoff/SKILL.md"

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

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