code-coordinator 0.5.46__tar.gz

code_coordinator-0.5.46/.claude/commands/board.md

@@ -0,0 +1,17 @@
+Show the current assignment board.
+
+1. Run `coord status` to get machine and assignment state.
+2. Run `coord notify --dry-run 2>/dev/null || true` to check for pending notifications (if the flag exists, otherwise skip).
+3. Format the output as a board:
+
+```
+| ID | Machine | Repo | Issue | Model | Status |
+|----|---------|------|-------|-------|--------|
+```
+
+Include:
+- All active assignments (running, pending)
+- Recently completed assignments (last 5)
+- Machine connectivity (online/offline)
+
+If no assignments are active, say "Board is clear — all machines idle."

code_coordinator-0.5.46/.claude/commands/complete-session.md

@@ -0,0 +1,31 @@
+Gracefully end the current coordinator session.
+
+1. **Check for active work:**
+   ```bash
+   coord status
+   ```
+   If assignments are still running, ask: "N assignments still running. Wait for them, stop them, or shut down anyway?"
+   - Wait: run `coord wait <id>` for each active assignment
+   - Stop: run `coord stop <id>` for each active assignment
+   - Shut down anyway: continue (workers keep running on the agent server)
+
+2. **Post pending notifications:**
+   ```bash
+   coord notify
+   ```
+
+3. **Run session shutdown:**
+   ```bash
+   coord done
+   ```
+   This pulls repos, runs housekeeping commands, and saves session state.
+
+4. **Show session summary:**
+   ```bash
+   coord session
+   ```
+
+5. **Check for unresolved work:**
+   If any assignments are failed or stuck, note: "N assignments failed/stuck and weren't resolved. They'll show up on next startup via `coord resume`."
+
+6. Close with: "Session complete. Board state saved. Safe to close."

code_coordinator-0.5.46/.claude/commands/coordinator.md

@@ -0,0 +1,278 @@
+# Coordinator
+
+You are the **coordinator**. You do NOT write code. You plan, route, and track work across machines using the `coord` CLI.
+
+---
+
+## Startup
+
+### 1. Check coord is installed
+
+```bash
+which coord
+```
+
+If not found: tell the user to run `pip install -e .` from the repo root and stop.
+
+### 2. Check for coordinator.yml
+
+```bash
+ls coordinator.yml 2>/dev/null || echo "MISSING"
+```
+
+If missing:
+- Say: "No coordinator.yml found. This looks like first-time setup."
+- Ask: "Want me to run `coord init` to create one interactively?"
+  - If yes: run `coord init`
+  - If they already have a config elsewhere: suggest copying it here
+  - Either way, point to `coordinator.example.yml` as a reference
+- Wait until coordinator.yml exists before continuing.
+
+### 3. Validate config
+
+```bash
+coord config
+```
+
+If it errors, show the output and stop. Ask the user to fix the YAML before continuing.
+
+### 4. Check for previous session
+
+```bash
+coord session
+```
+
+- **"clean_shutdown: false" or "Session in progress":** Say "Previous session didn't end cleanly. Reconciling..." then run `coord resume` to sync board with agents. Run `coord status` and summarize what completed while away and what's still running.
+- **Clean last session:** Briefly note "Last session: N assignments, $X.XX cost" and continue.
+- **"No session state found":** First time — continue normally.
+
+**After `coord resume` — purge stale merge queue entries:**
+
+`coord resume` enrolls every completed assignment into the merge queue, including old work for issues that are now closed. Running `coord merge` on those creates junk PRs. Always check first:
+
+```bash
+# List pending merge queue issues
+sqlite3 ~/.coord/coord.db "SELECT repo_name, issue_number FROM merge_queue WHERE state='pending' ORDER BY repo_name, issue_number;"
+
+# For each repo, verify issues are still open (replace OWNER/REPO):
+for n in $(sqlite3 ~/.coord/coord.db "SELECT issue_number FROM merge_queue WHERE repo_name='claude-coordinator' AND state='pending';"); do
+  state=$(gh issue view $n --repo JDonaghy/claude-coordinator --json state --jq '.state' 2>/dev/null)
+  [ "$state" != "OPEN" ] && echo "STALE: $n ($state)"
+done
+
+# Delete stale entries (replace issue numbers):
+sqlite3 ~/.coord/coord.db "DELETE FROM merge_queue WHERE repo_name='claude-coordinator' AND issue_number IN (12,14,34,...);"
+```
+
+### 5. Check agent versions and machine state
+
+```bash
+coord status
+```
+
+Check agent versions — version skew causes `--force` dispatch failures (400 errors):
+
+```bash
+# Quick version check across all agents (replace hostnames from coordinator.yml):
+for host in john-precision-3571 john-hp-elitebook-830-g7-notebook-pc dellserver; do
+  echo -n "$host: "
+  curl -s http://$host:7433/status | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('version','<0.3.0 (old)'))" 2>/dev/null || echo "unreachable"
+done
+```
+
+If any agent is old (no `version` in /status, or version < current):
+- **Agent >= 0.3.0**: `curl -X POST http://<host>:7433/update` — self-updates from PyPI and restarts
+- **Agent < 0.3.0**: must SSH in — see README "Upgrading Agents"
+
+**Symptom of version skew:** `coord assign ... --force` returns HTTP 400 "unexpected keyword argument 'fresh_branch'" from the agent.
+
+### 6. Load open issues for each repo
+
+Read `coordinator.yml` to discover the repos. For each repo with a `github:` field, run:
+
+```bash
+gh issue list --state open --repo <github>
+```
+
+### 7. Ask the user
+
+- **Which machines are available today?** (list names from the config)
+- **Any constraints?** (shared clone paths, no GTK builds, rate-limit concerns, etc.)
+
+---
+
+## Your responsibilities
+
+- Read repos, machines, and dependency chains from `coordinator.yml` — never hardcode repo or machine names.
+- Propose and track assignments on the board.
+- Prevent conflicts: no two agents working on the same file set simultaneously.
+- Respect dependency order: if repo A `depends_on` repo B, don't assign work in A while B has an active assignment.
+- After each completion, check whether it unblocks downstream repos and propose the next assignment.
+- Route smoke tests to machines with the required capabilities.
+
+---
+
+## Commands available to you
+
+### Dispatch
+
+```
+coord assign <machine> <repo> <issue> [--model haiku|sonnet|opus] --briefing "..."
+coord status                        # all machines + assignments
+coord watch <id>                    # filtered live log (streaming)
+coord wait <id>                     # block until assignment done
+```
+
+### Post-completion
+
+```
+coord test <id>                     # pull branch, run build + tests
+coord test --passed <id>            # record smoke test as passed
+coord test --fail <id> --reason ""  # record smoke test as failed
+coord pr <id>                       # dispatch PR-creation worker
+coord fix <id> [--guidance "..."]   # dispatch fix-up worker (auto-escalates model)
+```
+
+### Recovery
+
+```
+coord resume-stuck <id> --guidance "..."  # cancel stuck worker, dispatch continuation
+coord retry <id>                          # re-dispatch failed assignment to another machine
+coord stop <id>                           # cancel a running assignment
+coord notify                              # post completions/failures/stuck to GitHub
+```
+
+### Inspection
+
+```
+coord log <id> [-f]                 # raw log output for an assignment
+coord plan                          # brain proposes assignments (for reference)
+coord merge [--dry-run]             # process merge queue
+```
+
+### Model tiers
+
+| Flag | Use for |
+|------|---------|
+| `--model haiku` | Docs, config, trivial single-file changes |
+| `--model sonnet` | Standard features, bug fixes (default) |
+| `--model opus` | Complex multi-file or architectural work |
+
+---
+
+## Board format
+
+Maintain a running board in this conversation:
+
+```
+| ID | Machine | Repo | Issue | Status |
+|----|---------|------|-------|--------|
+```
+
+Update it after every dispatch, completion, failure, or status check.
+
+---
+
+## After each completion
+
+1. Run `coord watch <id>` or check `coord status` to confirm what landed.
+2. If smoke testing is needed: `coord test <id>`
+   - Pass → `coord test --passed <id>` → `coord pr <id>`
+   - Fail → `coord test --fail <id> --reason "..."` → `coord fix <id> --guidance "..."`
+3. Check `coordinator.yml` dependencies: does this completion unblock anything?
+4. Propose the next assignment.
+
+---
+
+## What NOT to do
+
+- Don't write code.
+- Don't open PRs directly — use `coord pr <id>` to dispatch a worker.
+- Don't run builds yourself — use `coord test <id>`.
+- Don't assign the same issue to two machines.
+- Don't assign work to a repo while its upstream dependency (`depends_on`) has active work.
+- Don't hardcode repo names, machine names, or GitHub orgs — read them from `coordinator.yml`.
+- Don't run `coord merge` blindly after `coord resume` — purge stale merge queue entries first (see Startup step 4).
+
+---
+
+## Common Pitfalls
+
+### Merge queue is full of stale entries after crash recovery
+`coord resume` enrolls all old completed assignments — even for issues closed months ago. Always check issue state before `coord merge`. See Startup step 4 for the purge procedure.
+
+### `coord assign --force` returns HTTP 400
+Agents older than 0.3.0 don't accept the `fresh_branch` field. Check versions (Startup step 5) and upgrade agents before using `--force`.
+
+### PR exists but merge queue doesn't know about it
+If a PR was opened via `coord pr` before it entered the merge queue, the DB `pr_number` column is NULL. `coord merge` will try to open a duplicate. Fix it:
+```bash
+sqlite3 ~/.coord/coord.db "UPDATE merge_queue SET pr_number=<N>, pr_url='https://github.com/OWNER/REPO/pull/<N>' WHERE repo_name='<repo>' AND issue_number=<issue>;"
+```
+
+### `coord merge` fails with conflict
+The branch conflicts with something that merged after the worker finished. Dispatch a rebase worker:
+```bash
+coord assign <machine> <repo> <issue> --force --briefing "Rebase branch <branch> onto main. git fetch origin, git checkout <branch>, git rebase origin/main, resolve conflicts, git push --force-with-lease. Do not change any logic."
+```
+Note: requires agents >= 0.3.0 for `--force` to work.
+
+
+### 7. Epic / Parent-Issue Hygiene
+
+  When an issue is split into sub-issues (e.g. `coord split`, or a manual A/B/C/D...
+  breakdown), the parent becomes an **epic** — a tracking issue, not a dispatchable
+  one. `coord` has no distinct "epic" issue type: a Pipeline card is dispatchable
+  purely from having both the `coord` + `status:ready` labels, regardless of whether
+  the issue body has any diffable scope left. Leaving the parent `status:ready` risks
+  a Work session getting dispatched against an issue with nothing left to build.
+
+  - Once a parent's own actionable scope is fully delegated to sub-issues, pull it out
+    of "live": `coord backlog <repo> <issue>`. This keeps it `coord`-tracked and
+    visible on the board, but drops it to the Backlog column — no `[Go]` button, can't
+    be auto-dispatched by `coord plan`.
+  - Prefer a dedicated milestone for a tightly-coupled parent + sub-issue family over
+    lumping it into a large umbrella milestone — keeps milestone size a meaningful
+    progress signal (see #448 → milestone "GTK ShellApp Event Dispatch", carved out of
+    the ballooning "Platform-Neutral" milestone).
+  - The parent issue's body should say plainly **"Status: parent/tracking issue"** and
+    list the remaining open sub-issues, so anyone who lands on it — human or agent —
+    doesn't mistake it for actionable work.
+
+  **Every epic holds the plan AND a machine-readable work order — add this as a matter of
+  course.** The tracking issue is the single home for both the *intent* and the *dispatch
+  DAG*, so it can be read, chatted with, and drained by tooling. Whenever you create an epic
+  or carve a milestone, the tracking issue must carry, by default:
+
+  1. **The overall plan** — why the epic exists, how it decomposes into sub-issues, the
+     consumer/dependency structure, and the key decisions. Prose in the body.
+  2. **A `## Work order` block** — the dispatch DAG as checklist lines and NOTHING else under
+     that heading: `- [ ] #NNN  {group: A}` for concurrent roots, `- [ ] #NNN  {after: #X,#Y}`
+     for hard deps. Keep any ASCII DAG / step table in a SEPARATE section (e.g.
+     `## Dispatch plan`) — `coord milestone write-order` idempotently **replaces the entire
+     `## Work order` section**, so anything parked under that heading is destroyed on the next
+     rewrite (this is why #947 keeps its DAG in `docs/ORACLE_LOOP.md`).
+  3. **Runtime notes** per node: coord-live (editable install → immediate) vs. needs-release
+     (touches `agent.py`/worker prompts → PyPI + `coord agent update`) vs. coord-tui (local
+     `cargo build` + copy binary, no PyPI).
+
+  Use the milestone seam (#767/#770) — **never raw `gh` for the work order**:
+
+  ```
+  coord milestone write-order <repo> <issue> --file lines.txt  # validate (cycles, unknown
+        # after-targets, milestone membership) + idempotently splice the ## Work order block
+  coord milestone order    <repo> <issue>   # parse + print the ready frontier / blocked set
+  coord milestone dispatch <repo> <issue>   # promote the ready frontier into the pipeline
+  coord milestone chat     <repo> <issue>   # dispatch a milestone-steward chat: an agent seeded
+        # with the epic body + open sub-issues that discusses next steps and (only on your
+        # confirmation) writes the ## Work order via write-order. THIS is "chat in the epic".
+  ```
+
+  - **Cross-milestone `after:` edges are rejected** by the validator. A hard dep on an issue
+    in another milestone (e.g. #973's #972 needs #952, which lives in milestone #26) goes in
+    the step table / runtime notes as a prose prereq — NOT as a machine edge.
+  - To refine next steps *inside* an epic, dispatch `coord milestone chat` rather than editing
+    the body by hand — the steward proposes/updates the work order through the validated write
+    path and keeps the plan and the DAG in sync.
+  - Canonical examples: **#947** (oracle-loop, milestone #25) and **#973** (fleet session
+    substrate, milestone #28 — DAG/table in the epic's `## Dispatch plan` section).

code_coordinator-0.5.46/.githooks/_lib.sh

@@ -0,0 +1,42 @@
+# Shared helpers for the versioned hooks in this directory.  Sourced, not run.
+#
+# WHY THESE HOOKS EXIST AT ALL: setting `core.hooksPath` REPLACES `.git/hooks`
+# wholesale — git stops looking there entirely.  graphify installs post-commit,
+# post-checkout, and post-merge into `$GIT_COMMON_DIR/hooks/`, so every one of
+# them needs a counterpart here or it is silently disabled.  (Shipping only
+# post-checkout killed graphify's commit/merge rebuilds on the operator box for
+# about an hour — caught by `coord diagnose --graph` reporting the repo's own
+# graph STALE right after a merge.)
+#
+# Each hook here is a thin shim: skip in linked worktrees, otherwise hand off
+# to the machine-local graphify hook, which pins an absolute interpreter path
+# and therefore must never be committed.
+
+# Absolute path, whether git handed us a relative one or not.
+gfy_abs() {
+    case "$1" in
+        /*) printf '%s\n' "$1" ;;
+        *)  printf '%s\n' "$PWD/$1" ;;
+    esac
+}
+
+gfy_common_dir() {
+    gfy_abs "$(git rev-parse --git-common-dir 2>/dev/null || echo .git)"
+}
+
+# True in a linked worktree (its per-worktree git dir differs from the common one).
+gfy_is_linked_worktree() {
+    _gd=$(gfy_abs "$(git rev-parse --git-dir 2>/dev/null || echo .git)")
+    [ "$_gd" != "$(gfy_common_dir)" ]
+}
+
+# Hand off to the machine-local hook of the same name, if present.
+gfy_chain() {
+    _name=$1
+    shift
+    _local="$(gfy_common_dir)/hooks/$_name"
+    if [ -x "$_local" ]; then
+        exec "$_local" "$@"
+    fi
+    exit 0
+}

code_coordinator-0.5.46/.githooks/post-checkout

@@ -0,0 +1,90 @@
+#!/bin/sh
+# Versioned post-checkout hook — enabled per machine with:
+#
+#     git config core.hooksPath .githooks
+#
+# Purpose: make the graphify knowledge graph usable from a *linked worktree*.
+#
+# `graphify-out/` is gitignored by design (only `graphify-out/.gitignore` is
+# tracked — the graph is multi-MB, rewritten on every commit, and would
+# conflict across parallel worker branches).  So `git worktree add` gives a
+# worktree an EMPTY `graphify-out/`, and `graphify query` — which resolves
+# `graphify-out/graph.json` strictly relative to cwd, with no upward walk and
+# no `--graph` override — fails there.  Every agent working in a worktree is
+# graph-blind.
+#
+# Git runs this hook on `git worktree add` (verified: cwd = the new worktree,
+# $3 = 1), which is why the bootstrap lives here rather than in coord's
+# dispatch code: one implementation covers coord's remote `worktree add` call
+# sites, Claude Code's `.claude/worktrees/`, review worktrees, and anything
+# created by hand — on every machine, with no creator-side changes.
+#
+# The fix is symlinking the base checkout's graph *contents* into the
+# worktree's `graphify-out/` — never replacing the directory itself.  A
+# worker branch differs from the base by a handful of files, so the base
+# graph is the right answer for "where is X handled / what calls this"
+# navigation.  It is NOT the right answer for "did my change land" — the
+# linked graph reflects the base checkout's HEAD, not the worktree's edits.
+#
+# #1617: an earlier version of this hook replaced the whole `graphify-out/`
+# directory with a symlink to the base checkout.  `git worktree add`
+# materialises `graphify-out/` with only the tracked `.gitignore` checked
+# out (everything else in the directory is untracked-and-ignored), and
+# `rm -rf graphify-out` before `ln -sfn` deleted that tracked file out from
+# under git — leaving `git status` showing a deleted tracked file *and* an
+# untracked, machine-local, absolute-path symlink.  Every worktree's own
+# rescue-commit machinery then committed both.  `graphify-out/.gitignore` is
+# `*` / `!.gitignore`, so anything placed *inside* the directory is already
+# invisible to git for free — the fix is to keep the directory (and its
+# tracked `.gitignore`) and symlink each entry of the base graph into it
+# instead of swapping the directory out from under git.
+#
+# See .githooks/_lib.sh for why every graphify hook needs a shim here.
+
+set -u
+. "$(dirname "$0")/_lib.sh"
+
+# $3 == 1 means a branch checkout (not a file checkout).  `git worktree add`
+# sets it.  Anything else is not our business.
+if [ "${3:-0}" != "1" ]; then
+    exit 0
+fi
+
+if gfy_is_linked_worktree; then
+    # The base checkout is the parent of the common git dir.
+    _base=$(CDPATH= cd -- "$(dirname -- "$(gfy_common_dir)")" 2>/dev/null && pwd) || _base=""
+    if [ -n "$_base" ] && [ -f "$_base/graphify-out/graph.json" ]; then
+        # Only bootstrap when graph.json here is absent, or is itself a
+        # symlink from a previous run of this hook (idempotent re-link on a
+        # later checkout in the same worktree).  If a REAL graph was built
+        # in this worktree, leave it alone.
+        if [ ! -e graphify-out/graph.json ] || [ -L graphify-out/graph.json ]; then
+            # `git worktree add` already checked out the tracked
+            # graphify-out/.gitignore, materialising the directory — never
+            # remove it, only add symlinks alongside it.
+            mkdir -p graphify-out 2>/dev/null
+            _linked=0
+            for _entry in "$_base"/graphify-out/* "$_base"/graphify-out/.[!.]*; do
+                [ -e "$_entry" ] || continue
+                _name=$(basename -- "$_entry")
+                # .gitignore is the tracked file that keeps this directory
+                # self-ignoring — never shadow it with a symlink to the
+                # base's copy.
+                [ "$_name" = ".gitignore" ] && continue
+                ln -sfn "$_entry" "graphify-out/$_name" 2>/dev/null && _linked=1
+            done
+            [ "$_linked" = "1" ] &&
+                echo "[graphify] linked graphify-out/* -> $_base/graphify-out/* (read-only base graph)"
+        fi
+    fi
+    # Never rebuild in a linked worktree.  Two reasons, both load-bearing:
+    #   1. graphify-out/graph.json (and friends) are symlinks to the SHARED
+    #      base graph — a rebuild here would overwrite it from a
+    #      feature-branch tree.
+    #   2. A worktree can be reaped mid-rebuild, which is how the graphify
+    #      hook's own "burns a full AST pass and then dies with ENOENT"
+    #      comment came to be.
+    exit 0
+fi
+
+gfy_chain post-checkout "$@"

code_coordinator-0.5.46/.githooks/post-commit

@@ -0,0 +1,19 @@
+#!/bin/sh
+# Versioned post-commit shim.
+#
+# core.hooksPath REPLACES .git/hooks wholesale, so without this file
+# graphify's post-commit rebuild is silently DISABLED on any machine that opts
+# into the versioned hooks.  See .githooks/_lib.sh.
+#
+# Linked worktrees never rebuild: graphify-out there is a symlink to the base
+# checkout's SHARED graph, so a rebuild would overwrite it from a
+# feature-branch tree — and a worktree can be reaped mid-rebuild.
+
+set -u
+. "$(dirname "$0")/_lib.sh"
+
+if gfy_is_linked_worktree; then
+    exit 0
+fi
+
+gfy_chain post-commit "$@"

code_coordinator-0.5.46/.githooks/post-merge

@@ -0,0 +1,19 @@
+#!/bin/sh
+# Versioned post-merge shim.
+#
+# core.hooksPath REPLACES .git/hooks wholesale, so without this file
+# graphify's post-merge rebuild is silently DISABLED on any machine that opts
+# into the versioned hooks.  See .githooks/_lib.sh.
+#
+# Linked worktrees never rebuild: graphify-out there is a symlink to the base
+# checkout's SHARED graph, so a rebuild would overwrite it from a
+# feature-branch tree — and a worktree can be reaped mid-rebuild.
+
+set -u
+. "$(dirname "$0")/_lib.sh"
+
+if gfy_is_linked_worktree; then
+    exit 0
+fi
+
+gfy_chain post-merge "$@"