code-coordinator 0.5.75__tar.gz → 0.5.76__tar.gz

code_coordinator-0.5.76/CLAUDE.md

@@ -0,0 +1,253 @@
+# claude-coordinator
+
+CLI tool + per-machine agent server that coordinates Claude Code workers across multiple machines and repos over Tailscale.
+
+> **Scope of this file (#2195).** This is the **worker- and reviewer-facing** rulebook: it is
+> loaded into every worker leg, every review leg, and every coordinator session, so it holds
+> only what someone *editing this repo* must act on. Operator runbooks live in
+> [`docs/`](docs/) — see [Operational guides](#operational-guides--operator-facing) at the
+> bottom. Settled design rationale lives in
+> [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
+> Keep it that way: if a new rule does not change what a worker does, it belongs in `docs/`.
+
+## Current Goal — read first
+
+**[`GOAL.md`](GOAL.md) holds the current north-star objective** — the living, cross-repo / cross-machine goal that should bias all planning, triage, and dispatch. It is meta-level (above any single issue, repo, or session) and changes as priorities evolve: read it first, plan against it, and keep it current. `coordinator.yml` is the source of truth for *topology*; `GOAL.md` is the source of truth for *intent*.
+
+## Codebase navigation — query the graph first
+
+This repo ships a **graphify** knowledge graph in `graphify-out/` (`graph.json`,
+`GRAPH_REPORT.md`), kept current on a best-effort basis by `post-commit` /
+`post-checkout` git hooks. For any architecture / "where is this handled" / "what
+calls this" / file-relationship question, **query the graph first** (the `graphify`
+skill, or the graphify CLI) before reaching for grep/Read. Grep/Read are for
+exact-string or line-level confirmation — not the first move.
+
+**In a worktree the graph is the base checkout's, not yours.** `graphify-out/` is
+gitignored (only its `.gitignore` is tracked), so `git worktree add` yields an empty
+one — and `graphify query` resolves `graphify-out/graph.json` strictly relative to
+cwd, with no upward walk and no `--graph` override. `.githooks/post-checkout`
+therefore symlinks the *contents* of a worktree's `graphify-out/` (`graph.json`,
+`manifest.json`, `cache/`, ...) at the base checkout's graph — the directory
+itself, and its tracked `.gitignore`, are left alone so the worktree stays
+`git status`-clean.
+Consequences worth knowing while working in one: the graph reflects the **base
+checkout's HEAD, not your edits** — trust it for *"where is X handled"*, never for
+*"did my change land"* — and rebuilds are deliberately disabled inside worktrees
+(a rebuild there would overwrite the shared graph from a feature branch). The
+bootstrap only runs where `core.hooksPath` is set: `git config core.hooksPath
+.githooks`, once per machine.
+
+**The graph drifts, and the hooks cannot prevent it.** They `exit 0` during
+rebase/merge/cherry-pick (so the merge agent's proactive rebase never rebuilds),
+nothing fires at all for `git reset --hard`, every failure path is a silent
+`exit 0` behind a detached 600s-timeout background process, concurrent triggers
+coalesce, and their `[ ! -f graphify-out/graph.json ]` guard is a permanent
+off-switch once the graph is purged. Treat the hooks as an optimization and check
+freshness instead — `GRAPH_REPORT.md` records its source commit, and
+**`coord diagnose --graph`** compares that to HEAD for every local checkout (and
+flags an unset `core.hooksPath`). If it reports STALE, `graphify update .` in that
+checkout.
+
+Setting this up on a new machine: [`docs/GRAPHIFY_SETUP.md`](docs/GRAPHIFY_SETUP.md).
+
+## Architecture
+
+```
+coordinator.yml           — Single config file: repos, machines, dependencies
+coord CLI                  — User-facing commands (plan, approve, assign, status, etc.)
+coord agent (per-machine)  — HTTP server (port 7433) that runs claude -p
+coord serve                — Board daemon (port 7435): canonical board state for thin clients
+coord web                  — Lightweight dashboard (port 7434)
+claude -p                  — The actual worker (runs locally on each machine)
+GitHub issues              — Work source + message bus (via issue comments)
+Tailscale                  — Networking between machines
+```
+
+Full walkthrough — the agent HTTP API, where each subcommand actually runs, the auto-loop end
+to end: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Project Structure
+
+Query the **graphify graph** (`graphify-out/`) for the full module map + relationships — it's authoritative and auto-updated. Key entry points: `coord/cli.py` (Click CLI + all subcommands), `coord/agent.py` (`AgentServer`: `claude -p` subprocess mgmt) + `coord/agent_app.py` / `coord/serve_app.py` (agent + board-daemon HTTP apps), `coord/brain.py` (planning), `coord/dispatch.py` (routing: POST to agents, briefings), `coord/review.py` (adversarial review), `coord/merge_queue.py` (merge sequencing) + `coord/reconcile.py` (board↔agent), `coord/state.py` (board persistence in `~/.coord/`), `coord/models.py` (dataclasses), `coord/config.py` (`coordinator.yml` parsing), `coord/dashboard/` (web dashboard + `webapp/` phone PWA). Tests: `tests/test_<module>.py` (pytest; fixtures in `conftest.py`).
+
+## Commands
+
+`coord <cmd> --help` documents every command + flags. The core loop:
+
+```bash
+coord plan                 # Brain proposes assignments for idle machines
+coord approve 1,3          # Dispatch approved proposals (comma-separated IDs)
+coord assign <machine> <repo> <issue> [--briefing TEXT | --briefing-file F] [--dry-run]  # Direct dispatch
+coord status [--freshness] # Machines, assignments, connectivity (+ repo freshness vs GitHub HEADs)
+coord log <id> [-f] [--machine NAME]            # claude -p output (remote logs need --machine)
+coord notify               # Poll agents, post completion/failure comments to GitHub
+coord test --passed|--fail|--skipped <id>       # Record the Test-gate verdict (bare `coord test <id>` builds+tests locally)
+coord merge [--dry-run] [--repo NAME] [--method rebase|squash|merge] [--order IDs] [--force-merge]
+coord reconcile-merges     # Backfill missing branches + record out-of-band merges (#609/#611)
+coord retry|stop|resume <id>                    # Recovery; `coord done` ends the session
+```
+
+Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier`, `coord repo add` / `coord repo doctor`.
+
+## Development
+
+Always work in a virtualenv. Agent workers are spawned with the agent's own
+venv stripped from `PATH` (#402), so a bare `pip install` resolves to system
+Python (PEP 668) — and must **never** target the agent's runtime venv. Create
+your own venv in the checkout (`.venv/` is gitignored):
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+coord plan --dry-run
+coord approve --dry-run 1,2
+coord assign --dry-run precision claude-coordinator 42
+```
+
+**Workers: scope your test run to your diff, never `pytest` bare (#2169).**
+The full suite exceeds Claude Code's 600s Bash ceiling on this repo and
+duplicates the Test stage + CI, which both run it against your pushed SHA
+regardless. Run just the file(s) that mirror what you changed — `pytest
+tests/test_<module>.py` for a `coord/<module>.py` change, `cargo test` from
+`tui/` scoped with a test-name filter for a `tui/**` change. To see what
+the Test stage itself would run for your diff (and confirm you're not
+missing a suite), `scripts/coord-test-runner.sh <worktree> --print-routing`
+computes the routing without actually building or testing anything.
+
+## Working on `tui/` — the `quadraui` pin
+
+**`coord-tui` pins `quadraui` to a git rev in `tui/Cargo.toml`**
+(`quadraui = { git = "https://github.com/JDonaghy/quadraui", rev = "<sha>" }`, #1973). This
+replaced the old relative-path dependency (`../../quadraui/quadraui`), which built against
+whatever branch happened to be checked out in `~/src/quadraui` — a quadraui merge could break
+coord-tui's build/merge with **zero coord-tui commits and no warning** (it already happened
+once). `cargo build`/`cargo test` from `tui/` now fetch quadraui straight from GitHub at the
+pinned rev and never touch `~/src/quadraui`, so the local checkout's branch is irrelevant.
+
+- **Bumping the pin** (deliberate, reviewable, its own coord-tui commit): pick the target
+  quadraui rev — normally the tip of `origin/develop` (quadraui's default/integration branch,
+  per quadraui's CLAUDE.md) — edit the `rev = "..."` in `tui/Cargo.toml`, then run
+  `cargo build && cargo test` from `tui/` and confirm EXIT=0 before committing.
+  `cargo update -p quadraui` alone will **not** move a `rev`-pinned git dependency; the
+  `Cargo.toml` edit is the actual bump.
+- **Co-developing against an unmerged quadraui branch/PR:** if a `tui/` task consumes a
+  not-yet-merged quadraui feature, the briefing **must** name the quadraui PR/branch. The
+  worker builds against a local `~/src/quadraui` checkout **without editing
+  `tui/Cargo.toml`**, via cargo's local-paths override:
+  `cp tui/cargo-config-local-quadraui.toml.example tui/.cargo/config.toml` (git-ignored — see
+  the example file's header) after checking out the target branch in `~/src/quadraui`. Delete
+  `tui/.cargo/config.toml` (or don't create it) to build against the pinned rev again — this
+  is the default and what CI/other workers use. **Verify build EXIT=0 from `tui/` both with
+  the override active (proves the feature works) and, before finishing, confirm the committed
+  `tui/Cargo.toml` still points at the pinned rev** (the override file itself is never
+  committed).
+
+## Key Design Decisions
+
+One line each — the reasoning behind them is in
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
+
+- **No API key needed.** Everything uses `claude -p`, which runs on a Max/Pro subscription via OAuth.
+- **Agent servers are dumb dispatchers.** They spawn `claude -p` and track the subprocess; all intelligence is in the coordinator brain.
+- **GitHub issue comments are the message bus.** Briefings, completion notices and failure reports are comments, carrying `<!-- coord:... -->` markers for machine parsing.
+- **`coordinator.yml` is the single source of truth** for repo topology, machine capabilities, dependencies, concurrency limits, review settings, smoke-test rules, and the pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo checkout.
+- **User approves everything.** `coord plan` proposes, the user reviews, `coord approve` dispatches. No autonomous dispatch.
+- **Claim detection prevents duplicate work.** Before dispatching, the coordinator checks the board for active assignments and the remote for `issue-{N}-*` branches.
+- **Conflict rules are inferred, not configured.** The brain reads issue bodies and infers which files will be touched.
+- **Adversarial reviews are rule-enforcing, not rubber-stamping.** On worker completion a fresh `claude -p` session on a *different* machine reviews the PR diff against this file and the review checklist, with zero shared context with the worker — that's the whole point.
+- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the headless auto-loop holds review dispatch until there is a `passed`/`skipped` test verdict.
+- **Merge is gated on CI checks (#240).** `coord merge` refuses when a check failed or is still running — and a PR with *zero* reported checks is not automatically clear either (#1904).
+- **Mechanical merge conflicts auto-rebase (#241).** A `type="conflict-fix"` worker rebases and resolves additive merges; semantic conflicts are left for a human.
+- **Smoke tests validate on capable hardware.** `smoke_tests.capability_rules` map changed files to required machine capabilities (e.g. GTK changes → a machine with GTK).
+- **Progress streaming from workers.** Workers emit `STATUS:` and `STUCK:` lines; the coordinator parses these for real-time progress in `coord status` and the dashboard.
+- **The notifier tells you when NOBODY IS COMING — and nothing else (#1632).** Advisory, isolated, off by default; it is not an error channel and not a progress feed.
+
+## Review Prompt Assembly
+
+The reviewer gets a prompt built from:
+1. **Repo's CLAUDE.md** — the project rules (source of truth, not duplicated)
+2. **Generic checklist** — "did you add tests?", "did you stay in file scope?", "any security issues?"
+3. **Repo overrides** — project-specific patterns from `coordinator.yml` `reviews.repo_overrides`
+4. **The diff** — `gh pr diff` of the worker's branch vs base
+5. **The issue** — title and body for intent verification
+
+The reviewer reads the rules and enforces them against the diff. It does not have the worker's session context — genuinely independent.
+
+## Rules for workers
+
+- **Only the coordinator writes docs.** Workers must **not** update README, CHANGELOG, or shared documentation files — parallel doc edits cause merge conflicts. If a briefing lists docs in `files_forbidden`, respect it. An issue whose *entire* deliverable is a doc edit is coordinator work and should never have been dispatched; say so and stop rather than editing the doc.
+- **Never edit `tests/acceptance/**`.** Those suites are sealed and delivered read-only / run-only. Write your own unit and internal tests instead.
+- **Stay in file scope.** If you must touch a file outside your briefing, note it in your final message.
+- **Commit and push before your final message** — even if the build is broken or you ran out of time. Uncommitted work is destroyed when the session ends.
+- **`gh` is on the deny-list.** The coordinator owns all GitHub interaction; use plain `git`.
+
+The operator-side counterparts to these rules (dispatch economics, what to send to a worker
+versus keep in the coordinator session) are in
+[`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md).
+
+## Testing — black-box coverage is the acceptance bar
+
+**Every PR that changes user-visible behavior must ship a black-box test** that drives the *running app* and asserts on its rendered output — not just unit tests on internal functions. The adversarial reviewer reads this file and **rejects behavior-changing PRs that lack one** (pure refactors / internal-only changes are exempt — say so in the PR if that applies). Build the **harness once per repo**; add **tests incrementally, one (or a few) per behavior-changing issue** — do *not* big-bang a full suite. Coverage then grows with churn and ratchets up (PRs add coverage, never remove it). Keep a thin **core smoke set** over the few most-trafficked screens so critical flows stay guarded even by unrelated changes.
+
+> **The acceptance suite is becoming an independent, sealed *oracle* (2026-07-04, [`docs/ORACLE_LOOP.md`](docs/ORACLE_LOOP.md)).** In an oracle-loop milestone the worker **no longer authors** the acceptance tests — an independent `test-author` agent writes them from a mock-first Gate-A contract, and they are delivered to the worker **read-only / run-only** (`coord acceptance run --issue N`). The worker iterates against them **in its own warm session** until green (the tight loop), then the coordinator re-runs the sealed suite **externally** against the pushed SHA as the trust gate. The runner sits above **pluggable framework drivers**, declared per repo in `acceptance.drivers` and routed to a capability-matched machine. **Implemented today: `tui-tuidriver`** (quadraui `TuiDriver`, the coord-tui case below), **`cli-pytest`**, and **`web-playwright`** (#1539) — see `SUPPORTED_KINDS` in `coord/acceptance_drivers.py`, which is the source of truth. **Native is NOT implemented**: a kind may be *declared* in `coordinator.yml` ahead of its adapter, but `run_driver()` rejects it with a "not yet implemented" `DriverError` rather than silently no-opping. What still gates the webapp is **not** the driver but its inputs — the deterministic fixture server (#1538) and a machine whose `browser` capability actually probes as met (#1678); both milestone #51 / epic #1537 ([`docs/WEB_CONTROL_CENTER.md`](docs/WEB_CONTROL_CENTER.md)). Workers still write their **own unit/internal tests**; they must **never** edit `tests/acceptance/**`.
+
+**How it runs:** black-box tests are part of the repo's normal test command, so the **Test stage** executes them on a capability-matched machine — `smoke_tests.capability_rules` route platform-specific suites to capable hardware (a GTK box; a machine with a browser). Favor the automated pre-review gate; the point is to trust the suite so manual/interactive smoke (incl. driving from a phone) is rarely needed.
+
+### coord-tui — quadraui `TuiDriver` (harness shipped: #690 / #691)
+- Drives the whole app through the real `event → handle → render` path against ratatui's headless `TestBackend` and asserts on the screen grid. `cargo test`-native, deterministic, no TTY.
+- `CoordApp` implements quadraui's `ShellApp`, so use `quadraui::tui::testing::driver_with_shell(app, CoordApp::shell_config(), w, h)`. API: `find("text")` → coords, `click(x, y)`, `press`, `type_char`, `screen()`, `screen_contains(needle)`. **Locate targets with `find` — never hardcode coordinates.**
+- **Reuse the existing fixtures** — `make_test_app(data: BoardData) -> CoordApp` (and `make_app_with_assignments`, `make_app_with_one_completed_issue`, …) in `tui/src/app.rs` build a full app from in-memory `BoardData`, no live daemon. Put the tests **in-crate** (`#[cfg(test)]`), **not** in `tui/tests/` — the fixtures are `#[cfg(test)]`/private and an integration-test crate can't see them.
+- Limit: `TuiDriver` renders to `TestBackend`, so it does **not** parse real ANSI — terminal-protocol bugs (raw-mode, SGR mouse, the embedded `claude` PTY pane) are out of reach and still need a live smoke. A native pty + vt100 tier is tracked in quadraui#302 (unbuilt).
+
+### coord web (Phone Control Center) — shipped v1 (#700–#703); browser E2E forthcoming
+- The phone web app lives in `coord/dashboard/webapp/` (React / Vite / TS PWA, served by `coord/dashboard/server.py`). **v1 milestone (#700–#703) is shipped.** See [`docs/PHONE_WEBAPP.md`](docs/PHONE_WEBAPP.md) for the full runbook (build → serve → phone access over Tailscale).
+- **Build the React bundle before first use** — `dist/` is gitignored. From `coord/dashboard/webapp/`: `npm install && npm run build`. Re-run after pulling changes to `src/`. The server falls back to the legacy `index.html` when `dist/` is absent so existing behaviour is unchanged without a build.
+- **Run on the always-on host:** `coord web` binds `0.0.0.0:7434`. Reach it from a phone via the Tailscale MagicDNS name: `http://dellserver:7434` (replace with your host's name). Install as a PWA via "Add to Home Screen" in Safari / Chrome.
+- **Vitest unit tests** ship in `coord/dashboard/webapp/src/components/__tests__/` — run with `npm test` inside `coord/dashboard/webapp/`.
+- **Playwright E2E tests** are the acceptance bar: start the dashboard server against a seeded board (the web parallel of `make_test_app(BoardData)`), drive a real headless browser, assert on the rendered DOM. Browsers headless-test more cleanly than terminals, so the webapp should lean almost entirely on this automated gate rather than interactive smoke.
+  - **Shipped:** `playwright.config.ts` + specs in `coord/dashboard/webapp/e2e/` (`npm run test:e2e`), and `smoke_tests.capability_rules` already routes `coord/dashboard/webapp/**` → the `browser` capability, so the **Test stage** lands on a browser-capable machine.
+  - **Shipped:** the `web-playwright` acceptance driver (#1539) — it is in `SUPPORTED_KINDS`, so `coord acceptance run/record` can drive the webapp.
+  - **Not shipped:** the seeded-board fixture server (#1538) — today's specs run against whatever the live fleet is doing, so they are a smoke net, **not** a deterministic oracle. Milestone #51 / epic #1537.
+  - **`browser` is advertised by one machine (elitebook)** until #1541 adds it to dellserver — so all web testing currently funnels through the dev box. **And as of 2026-08-01 that machine's `browser` probe reads UNMET (#1678)**, so `dispatch_smoke` refuses to route any `coord/dashboard/webapp/**` change and the Test stage silently retries forever — check `coord doctor` before assuming a webapp change can be tested at all.
+
+## Conventions
+
+- Python 3.12+, type hints everywhere
+- Click for CLI
+- httpx for HTTP client, Starlette + uvicorn for HTTP server
+- PyYAML for config
+- No Anthropic SDK — all Claude interaction is via `claude -p` subprocess
+- Tests use pytest with fixtures in conftest.py
+- State files go in `~/.coord/` — including `coordinator.yml` (canonical: `~/.coord/coordinator.yml`; override with `$COORD_CONFIG` or `--config`; `./coordinator.yml` is a dev fallback)
+- Agent server port: 7433, dashboard port: 7434, board daemon port: 7435
+- GitHub issue comments carry `<!-- coord:event=... assignment=... -->` markers for machine parsing
+
+## Operational guides — operator-facing
+
+**Not needed to work on this repo.** These are runbooks for driving the fleet; a worker or
+reviewer can stop reading here.
+
+**Read before operating the fleet:**
+
+- [`docs/OPERATING_GOTCHAS.md`](docs/OPERATING_GOTCHAS.md) — **READ BEFORE OPERATING.** Traps that each cost a real dispatch, real money, or real lost work, and are invisible from the code. The headline: **a merged fix is not a live fix.**
+- [`docs/AGENT_OPERATIONS.md`](docs/AGENT_OPERATIONS.md) — releases, propagation, the deploy lanes, agent installs, and the **`~/.coord-venv` must-be-PyPI invariant**. **Read end-to-end before touching any agent install** — don't re-derive it.
+- [`docs/DRIVE_QUEUE.md`](docs/DRIVE_QUEUE.md) — the durable, board-backed driver (`coord drive-queue`, #1750). **Read the top section before queuing more than ~2 issues on one repo.**
+
+**Reference:**
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how it all fits together, plus the settled design rationale. Two diagnostic entry points: [why a merge/review isn't happening](docs/ARCHITECTURE.md#when-a-merge-isnt-happening) (**check here first when "Go does nothing"**) and [why an issue is in the Pipeline you never dispatched](docs/ARCHITECTURE.md#when-an-issue-is-sitting-in-the-pipeline-you-never-dispatched).
+- [`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md) — dispatch economics; what to send to a worker versus keep in the coordinator session.
+- [`docs/NOTIFIER.md`](docs/NOTIFIER.md) — the "nobody is coming" push channel (`coord notifier`).
+- [`docs/ORACLE_LOOP.md`](docs/ORACLE_LOOP.md) — sealed acceptance suites, Gate-A contracts, the test-author agent.
+- [`docs/PHONE_WEBAPP.md`](docs/PHONE_WEBAPP.md) — Phone Control Center v1 runbook and the `/api/pipeline` surface.
+- [`docs/GRAPHIFY_SETUP.md`](docs/GRAPHIFY_SETUP.md) — installing the knowledge graph on a new machine (four layers, all of which fail *silently*).
+- [`docs/EPHEMERAL_WORKERS.md`](docs/EPHEMERAL_WORKERS.md) — on-demand Azure worker VMs per epic. **The tailnet ACL is the security boundary** — `agent_app.py` has no authentication.
+- [`docs/MAC_MINI.md`](docs/MAC_MINI.md) — adding a Mac mini; sizing, provisioning, and what non-macOS work routes there. The port itself is [`docs/CROSS_PLATFORM.md`](docs/CROSS_PLATFORM.md) (milestone #39).
+- [`docs/FORGE_MIGRATION.md`](docs/FORGE_MIGRATION.md) — surviving a forge outage (cheap) versus leaving a forge (expensive); milestone #58 / epic #1902.
+
+**Two deploy facts that bite most often:**
+
+- **`coord-tui` ships as a locally-built binary, not via PyPI.** After a `tui/` PR merges, rebuild and reinstall locally: `cd tui && cargo build && cp target/debug/coord-tui ~/.local/bin/coord-tui`. Workers should not bump versions for tui-only changes.
+- **Turn off Claude Code's Agent View when driving the fleet** — set `"disableAgentView": true` in `~/.claude/settings.json` (the Claude-Code *client* config, not `~/.coord/`; restart to apply), or its cross-session roster pops up mid-type when another session changes stage. Full note in [`docs/AGENT_OPERATIONS.md`](docs/AGENT_OPERATIONS.md#operator-claude-code-settings-driving-the-fleet).

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.75
+Version: 0.5.76
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.75
+Version: 0.5.76
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/code_coordinator.egg-info/SOURCES.txt

@@ -359,6 +359,7 @@ docs/ARCHITECTURE.md
 docs/ARCH_SECURITY_GATES.md
 docs/COCKPIT.md
 docs/CONTROL_CENTER.md
+docs/COST_DISCIPLINE.md
 docs/CROSS_PLATFORM.md
 docs/CUSTOMER_PORTAL.md
 docs/DRIVE_QUEUE.md
@@ -571,6 +572,7 @@ tests/test_gate_a.py
 tests/test_gate_b.py
 tests/test_gate_snapshot_staleness.py
 tests/test_gates.py
+tests/test_gather_fleet_tmux_sessions.py
 tests/test_generated_types_fixture.py
 tests/test_github_ops.py
 tests/test_goal.py

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/code_coordinator.egg-info/scm_file_list.json

@@ -337,6 +337,7 @@
     "docs/ARCH_SECURITY_GATES.md",
     "docs/COCKPIT.md",
     "docs/CONTROL_CENTER.md",
+    "docs/COST_DISCIPLINE.md",
     "docs/CROSS_PLATFORM.md",
     "docs/CUSTOMER_PORTAL.md",
     "docs/DRIVE_QUEUE.md",
@@ -601,6 +602,7 @@
     "tests/test_gate_b.py",
     "tests/test_gate_snapshot_staleness.py",
     "tests/test_gates.py",
+    "tests/test_gather_fleet_tmux_sessions.py",
     "tests/test_generated_types_fixture.py",
     "tests/test_github_ops.py",
     "tests/test_goal.py",

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.75",
+  "tag": "0.5.76",
   "distance": 0,
-  "node": "g73af79d5b857f3191b459e4fa74599e9d5f6e319",
+  "node": "gdd3b9581f5fd9462b2fb9a85757ee783e3b09911",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-14"

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/coord/commands/release.py

@@ -311,6 +311,66 @@ def _fetch_board() -> tuple[dict, str | None]:
         return {}, f"{type(exc).__name__}: {exc}"
 
 
+def _interactive_session_busy(config) -> list:
+    """Live interactive tmux sessions as host-pinned `Busy` signals (#2228).
+
+    `release_propagate.assess_quiescence`'s ``extra_busy`` seam was built
+    for exactly this — its own docstring names "an interactive tmux
+    session" as the seam's purpose — but until now nothing ever fed it one.
+    An interactive session is invisible to the board *by construction*
+    (``coord assign --interactive`` launches into tmux; the tmux session
+    never POSTs ``/assign``), so without this a host running one reads as
+    idle and rolls out from under a human, restarting `coord-serve` on the
+    daemon host mid-session.
+
+    Reuses the same discovery `coord sessions --remote` renders
+    (:func:`coord.interactive.gather_fleet_tmux_sessions`) rather than
+    inventing a second way to look.
+
+    Fails OPEN, not closed: a probe error is logged and DROPPED, never
+    turned into a host-less `Busy` — an unattributable signal blocks EVERY
+    host by design (`Quiescence.fleet_wide_busy`), and an unreadable
+    session list must not silently escalate into that.
+    """
+    from coord import release_propagate as rp  # noqa: PLC0415
+    from coord.interactive import gather_fleet_tmux_sessions  # noqa: PLC0415
+
+    try:
+        sessions, errors = gather_fleet_tmux_sessions(config)
+    except Exception as exc:  # noqa: BLE001 — fail open, see docstring
+        click.echo(
+            f"warning: could not probe interactive sessions ({exc}) — "
+            "quiescence is blind to them this run",
+            err=True,
+        )
+        return []
+
+    for machine in errors:
+        click.echo(
+            f"warning: could not probe {machine} for live interactive "
+            "sessions — quiescence is blind to that host this run",
+            err=True,
+        )
+
+    busy = []
+    for s in sessions:
+        if s.get("pane_dead") == "1":
+            continue  # claude exited; tmux is up but nobody is driving it
+        machine = s.get("machine")
+        if not machine:
+            continue  # no coordinator.yml host to pin it to (#2228: never invent one)
+        busy.append(
+            rp.Busy(
+                kind="interactive session",
+                subject=f"{machine}:{s['session_name']}",
+                detail="`coord assign --interactive` never POSTs /assign, "
+                "so the board cannot see this",
+                host=machine,
+            )
+        )
+    return busy
+
+
 def _daemon_machine_name(
     config, override: str | None, machine_health: dict | None = None
 ) -> str | None:
@@ -550,6 +610,11 @@ def release_propagate(  # noqa: PLR0912, PLR0915 — a pipeline; the decisions a
         extra_busy.append(
             rp.Busy(kind="board unreadable", subject="/board", detail=board_error)
         )
+    # #2228: the board can't see an interactive session (no /assign POST) —
+    # feed assess_quiescence's extra_busy seam from the same fleet-wide tmux
+    # probe `coord sessions --remote` uses, so a live session defers a roll
+    # exactly like a live headless assignment does.
+    extra_busy.extend(_interactive_session_busy(config))
     quiescence = rp.assess_quiescence(
         queue_entries=board.get("drive_queue") or [],
         assignments=board.get("assignments") or [],
@@ -1933,8 +1998,10 @@ def _drain(
     config_path: Path,
     deadline: float,
     poll_interval: float,
+    config=None,
     reconcile=None,
     board_fetch=None,
+    extra_busy_fetch=None,
     now=None,
     sleep=None,
 ):
@@ -1945,7 +2012,21 @@ def _drain(
     may lead a roll — rather than a second definition of "busy" (#2096's
     "two surfaces, one function" rule). ``now``/``sleep`` are injectable so
     this loop is unit-testable without a real clock; ``reconcile``/
-    ``board_fetch`` default to the real subprocess/board calls.
+    ``board_fetch``/``extra_busy_fetch`` default to the real subprocess/
+    board/tmux-probe calls.
+
+    #2228: ``extra_busy_fetch`` re-probes live interactive sessions on
+    every poll (not just once) — a session that ends mid-drain should let
+    the daemon host clear within THIS wait, not only on the next `coord
+    release propagate` tick. Deliberately keyed off the explicit *config*
+    param, never an implicit ``_load_config(config_path)`` fallback: this
+    function is called with ``config_path=None`` from unit tests that
+    inject their own clock/board — silently resolving a real
+    ``coordinator.yml`` (and then SSH-probing whatever machines it names)
+    the moment ``config`` is omitted would make this loop non-hermetic by
+    default. No *config* simply means "no interactive-session signal this
+    call" — the caller opts in by passing one, as the real
+    ``coord release nightly-window`` call site does.
     """
     import time as _time  # noqa: PLC0415
 
@@ -1956,6 +2037,11 @@ def _drain(
     sleep_fn = sleep or _time.sleep
     reconcile_fn = reconcile or (lambda: _run_reconcile_tick(config_path))
     fetch_fn = board_fetch or _fetch_board
+    if extra_busy_fetch is None:
+        if config is not None:
+            extra_busy_fetch = lambda: _interactive_session_busy(config)  # noqa: E731
+        else:
+            extra_busy_fetch = lambda: []  # noqa: E731
 
     start = now_fn()
     while True:
@@ -1966,6 +2052,7 @@ def _drain(
             extra_busy.append(
                 rp.Busy(kind="board unreadable", subject="/board", detail=board_error)
             )
+        extra_busy.extend(extra_busy_fetch())
         quiescence = rp.assess_quiescence(
             queue_entries=board.get("drive_queue") or [],
             assignments=board.get("assignments") or [],
@@ -2327,6 +2414,7 @@ def release_nightly_window(  # noqa: PLR0912, PLR0915 — a pipeline; see module
             outcome = _drain(
                 daemon_host=daemon_name, config_path=config_path,
                 deadline=drain_deadline, poll_interval=poll_interval,
+                config=config,
             )
             record.drained = outcome.drained
             record.drain_seconds = outcome.elapsed_seconds

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/coord/interactive.py

@@ -90,7 +90,7 @@ from typing import TYPE_CHECKING, Sequence
 if TYPE_CHECKING:
     from coord.agent import MergeVerify
     from coord.config import Config
-    from coord.models import Board
+    from coord.models import Board, Machine
 
 from coord.providers.claude_pty import (
     BRACKETED_PASTE_ENABLE,
@@ -118,6 +118,7 @@ __all__ = [
     "tmux_session_alive",
     "tmux_pane_dead",
     "list_coord_tmux_sessions",
+    "gather_fleet_tmux_sessions",
     "TMUX_ATTACH_WARNING",
     "PTY_RELAY_NO_DETACH_WARNING",
 ]
@@ -469,6 +470,76 @@ def list_coord_tmux_sessions(
         return []
 
 
+def gather_fleet_tmux_sessions(
+    config: "Config",
+    *,
+    max_workers: int = 8,
+) -> tuple[list[dict], list[str]]:
+    """Enumerate live ``coord-*`` tmux sessions across every machine in *config*.
+
+    Mirrors the local+remote discovery ``coord sessions --remote`` renders
+    (#2228): local sessions via a plain :func:`list_coord_tmux_sessions`
+    call, remote sessions via one SSH probe per non-local configured
+    machine, run in parallel — bounded by :func:`list_coord_tmux_sessions`'s
+    own 5s per-host subprocess timeout so one unreachable host cannot stall
+    the caller.
+
+    Returns ``(sessions, probe_errors)``:
+
+    * ``sessions`` — one dict per tmux session found (dead or alive; the
+      caller filters), each carrying ``session_name``/``pane_dead``/
+      ``attached`` (see :func:`list_coord_tmux_sessions`) plus ``machine``
+      — the ``coordinator.yml`` machine name the session was found on. A
+      local session whose host has no ``coordinator.yml`` entry gets
+      ``machine=None``: there is no name to pin it to, and no configured
+      host it could block either.
+    * ``probe_errors`` — machine names whose remote probe *raised* (as
+      opposed to returning "no sessions", which is what an unreachable
+      host or a dead tmux server already look like —
+      :func:`list_coord_tmux_sessions` collapses both into ``[]`` with no
+      way to tell them apart). Callers must treat this the same as an
+      empty result for that host — never as a reason to defer everything
+      — but should still log it: an unreadable session list failing open
+      and failing *silently* are two different things (#2228).
+    """
+    import concurrent.futures as _cf  # noqa: PLC0415
+
+    local_hn = _get_local_short_hostname()
+
+    def _is_local(machine: "Machine") -> bool:
+        return (
+            machine.name.lower() == local_hn
+            or machine.host.split(".")[0].lower() == local_hn
+        )
+
+    local_machine = next((m.name for m in config.machines if _is_local(m)), None)
+
+    sessions: list[dict] = [
+        {**s, "machine": local_machine} for s in list_coord_tmux_sessions()
+    ]
+
+    remotes = [m for m in config.machines if not _is_local(m)]
+    errors: list[str] = []
+    if remotes:
+        def _probe(machine: "Machine") -> tuple[str, list[dict], BaseException | None]:
+            try:
+                found = list_coord_tmux_sessions(
+                    host=TmuxHost(ssh_target=machine.host, batch=True)
+                )
+                return machine.name, found, None
+            except Exception as exc:  # noqa: BLE001 — reported via probe_errors
+                return machine.name, [], exc
+
+        with _cf.ThreadPoolExecutor(max_workers=min(max_workers, len(remotes))) as ex:
+            for mname, found, err in ex.map(_probe, remotes):
+                if err is not None:
+                    errors.append(mname)
+                    continue
+                sessions.extend({**s, "machine": mname} for s in found)
+
+    return sessions, errors
+
+
 def _inject_briefing_into_tmux_session(
     session_name: str,
     briefing: str,

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/coord/release_propagate.py

@@ -720,6 +720,10 @@ def assess_quiescence(
     ``extra_busy`` is the seam for host-local signals the board cannot see
     (an interactive tmux session, a machine paused by an operator); the
     shell passes them in rather than this module growing a way to look.
+    #2228: the interactive-session half is wired from
+    ``coord.commands.release._interactive_session_busy``, fed by the same
+    fleet-wide tmux sweep ``coord sessions --remote`` renders — until then
+    this half of the seam existed but nothing ever fed it.
 
     #2110: a ``running`` queue row is not, on its own, proof of anything —
     the reconciler that would have moved it to ``done`` lives inside

{code_coordinator-0.5.75 → code_coordinator-0.5.76}/docs/AGENT_OPERATIONS.md

@@ -253,6 +253,54 @@ is now "plus the next quiescent window".
   units, which must themselves be installed by hand **once**, on the daemon
   host, to bootstrap the loop.
 
+## INVARIANT: every remote agent's `~/.coord-venv` is a PyPI install, never editable
+
+Moved here from `CLAUDE.md` by #2195 so it sits with the rest of the install runbook. **Read
+this section end-to-end before touching any agent install — don't re-derive it.**
+
+This is the single most-recurring fleet failure.
+
+- **PyPI install** → `coord agent update` runs `pip install --upgrade` and a released
+  `vX.Y.Z` lands cleanly.
+- **Editable install** → the update silently `git pull`s a local checkout instead, so version
+  bumps never propagate and the agent often "did not come back."
+
+**Root cause:** someone ran `pip install -e .` into `~/.coord-venv`. The editable **install**
+is the problem, **not** the `~/src/<repo>` checkout. #402's PATH-strip only stops *workers'*
+bare-pip, not a deliberate editable install.
+
+### DO NOT delete `~/src/<repo>` to "fix" drift
+
+It is the **worker worktree base** — `git worktree add` runs from it, and the worktrees in
+`~/.coord/worktrees/` are worktrees *of* it. Deleting it breaks every task for that repo on
+that machine. Fix **only the install**.
+
+### Detect
+
+```bash
+ssh <host> '~/.coord-venv/bin/pip show code-coordinator | grep -i "editable\|location"'
+```
+
+Any `Editable project location:` line ⇒ drift. A PyPI install shows only a site-packages
+`Location:`.
+
+### Fix (keeping the checkout)
+
+```bash
+# in ~/.coord-venv on the affected host
+pip uninstall -y code-coordinator && pip install --upgrade code-coordinator
+XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart coord-agent
+```
+
+The restart is not optional: the `/update` endpoint's `os.execv` self-restart does **not**
+take under systemd (#404 — it leaves the same PID and a stale version).
+
+### `✗ did not come back` is usually a FALSE NEGATIVE
+
+The agent is generally online and the restart simply didn't take. Check the running
+version/PID first, then choose between a drift-fix and a plain
+`systemctl --user restart coord-agent`.
+
 ## Install a new agent (first time)
 
 On the target machine: