code-coordinator 0.5.46__py3-none-any.whl

coord/deploy/coord-drive-queue.service

@@ -0,0 +1,117 @@
+# coord drive-queue tick — periodic drain of the operator-declared drive
+# queue (#1750/#1754, DQ-4/#1756).
+#
+# A systemd *user* unit (mirrors coord-agent/coord-serve/coord-web/coord-notify),
+# paired with coord-drive-queue.timer. Runs `coord drive-queue tick`, which
+# reconciles the queue against live board state and launches AT MOST ONE
+# `coord drive --tmux` per tick — never more, never past `--max-parallel`.
+# Install ONLY on the box that can see the board (dellserver in production,
+# the same host that runs coord-serve/coord-web/coord-notify): the tick
+# subprocess-launches `coord drive --tmux`, which needs a local tmux server
+# and the repo checkouts under SRC_ROOT, so it belongs on the daemon host, not
+# a thin client.
+#
+# Type=oneshot + `coord drive-queue tick`'s own flock (coord.filelock,
+# drive_queue_lock_path()) means a slow tick cannot stack: if a tick is still
+# running when the timer fires again, the new invocation takes the lock
+# non-blocking, sees it busy, prints "another drive-queue tick is running —
+# skipping", and exits 0 without touching the queue. Nothing here needs to
+# serialize invocations itself.
+#
+# COORD_BIN — the runner's own CLI must be a PINNED, NON-EDITABLE install
+# (#1523): worker branch churn must never be able to rewrite the tool that is
+# driving it, mid-run. On dellserver, ~/.local/bin/coord is a symlink into
+# ~/.coord-venv — the SAME venv deploy/coord-agent.service runs `coord agent`
+# from (see install-agent.sh) — so that already satisfies #1523, and it rides
+# the ordinary agent-venv upgrade lane rather than needing its own. Before
+# relying on a fix landing on this host:
+#
+#   coord agent update --machine dellserver   # or --all; the standard lane
+#   ~/.local/bin/coord --version              # VERIFY it took — an upgrade
+#                                              # silently no-ops more often
+#                                              # than you would think
+#
+# Do NOT confuse this with the epic sequencer's separate, bespoke
+# ~/.coord-cli-venv on elitebook (docs/AGENT_OPERATIONS.md's "fourth lane") —
+# that one has no automatic upgrade path at all and was found three releases
+# stale on 2026-07-29. This unit intentionally does not use that pattern.
+#
+# If you ever install this timer on a DIFFERENT machine, first confirm THAT
+# machine's `coord` is a non-editable install before trusting it unattended:
+#
+#   readlink -f ~/.local/bin/coord
+#   pip show code-coordinator | grep -i editable     # must print NOTHING
+#
+# An editable checkout (e.g. elitebook's dev box, where ~/.local/bin/coord
+# points at ~/src/claude-coordinator) lets a worker's branch churn rewrite the
+# runner's own code out from under a live tick. Do not install this unit
+# there. See docs/DRIVE_QUEUE.md.
+#
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/coord-drive-queue.service deploy/coord-drive-queue.timer \
+#       ~/.config/systemd/user/
+#   loginctl enable-linger "$USER"          # survive logout / reboot
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now coord-drive-queue.timer
+#
+# This is a Type=oneshot service activated BY THE TIMER — do not
+# `systemctl --user enable coord-drive-queue.service` directly (it has no
+# [Install] section; the timer unit is what you enable).
+#
+# Prereqs: same as coord-notify — coordinator.yml at ~/.coord/coordinator.yml,
+# a tmux server the launched `coord drive --tmux` sessions can attach to, and
+# the repo checkouts `coord drive` expects under its default SRC_ROOT.
+#
+# See docs/DRIVE_QUEUE.md for the full runbook (enqueue, install, stop,
+# reading QUEUE: STALLED / QUEUE: BLOCKED, and the operational traps).
+#
+# KillMode=process (#1830) — REQUIRED, do not remove. systemd's default
+# KillMode=control-group would reap this unit's entire cgroup when the tick
+# exits. When the tick launches `coord drive --tmux` and NO tmux server is
+# already running, `tmux new-session` has to spawn the server itself, and
+# that server lands inside THIS unit's cgroup — so the drive it just started
+# dies with the tick, seconds later. The failure is invisible whenever a
+# tmux server already exists (e.g. an operator has a terminal open on the
+# box), because then `tmux new-session` hands off to that pre-existing
+# server, which lives outside this cgroup. That made the queue appear to
+# work in every manual/attended test and fail only unattended — see #1830
+# for the full diagnosis and the repro. KillMode=process kills only the
+# tick's own process on unit stop/exit and leaves everything else it
+# started (the tmux server, the drive loop) alone.
+
+[Unit]
+Description=coord drive-queue tick (#1756)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+KillMode=process
+# --max-parallel 4 (#2012, raised from 3 in #2057) — the global ceiling,
+# ONE SLOT PER REPO IN THE FLEET: claude-coordinator, quadraui, vimcode,
+# coord-portal. It was 3 because the fleet had three repos when #2012 set
+# it; coord-portal joined afterwards and the number was never revisited, so
+# the fourth repo could never drive concurrently no matter what was queued.
+#
+# KEEP THIS EQUAL TO THE REPO COUNT. It is not a tuning knob for how hard
+# the fleet works — that is what the per-repo ceiling and machine capacity
+# decide. Set it lower and a repo silently loses its lane; set it higher
+# and it does nothing, because the per-repo ceiling still admits only one
+# drive per repo.
+#
+# #1972 added the SECOND ceiling, --max-parallel-per-repo (default 1),
+# which is what keeps two drives off the same repo; without raising this
+# outer one the per-repo ceiling can never bind, because the walk stops at
+# the global limit first and never reaches an entry from a different repo.
+#
+# Raise this ONLY on a host whose coord actually enforces the per-repo
+# ceiling (>= the release carrying #1972). A higher global ceiling on an
+# older coord launches two same-repo drives, which stale each other's
+# Test verdicts (#1479) — the exact collision #1972 exists to prevent.
+ExecStart=%h/.local/bin/coord drive-queue tick --max-parallel 4 --config %h/.coord/coordinator.yml
+# Generous relative to the tick's own ~120s launch-subprocess timeout
+# (_LAUNCH_TIMEOUT_SECONDS in coord/commands/drive_queue.py), but well below
+# the timer's 15-minute cadence (coord-drive-queue.timer) so a genuinely
+# wedged tick can't run into the next fire.
+TimeoutStartSec=300

coord/deploy/coord-drive-queue.timer

@@ -0,0 +1,39 @@
+# coord drive-queue tick — fires coord-drive-queue.service (Type=oneshot) on
+# a cadence. See that unit's header for the full rationale and the
+# COORD_BIN / #1523 pinned-runner requirement.
+#
+# 3 minutes (was 15). The earlier rationale — "between launches the tick is
+# only ever OBSERVING ... a tighter interval buys nothing but load" — missed
+# that the tick is ALSO the only thing that notices a drive has finished and
+# launches the next entry. Capacity is 1, so the interval is a hard lower
+# bound on the dead time between issues, not idle observation.
+#
+# Measured 2026-08-07 from the queue journal: #1910's PR merged at 12:47:36,
+# the 12:46:42 tick still saw it alive, and the next tick launched #1834 at
+# 13:02:13 — 14m37s of an idle fleet. Completions land uniformly inside the
+# interval, so the expected loss is HALF of it per issue (~7.5min at 15min).
+# Over a queue of 18 that was ~2.2 hours of nothing happening.
+#
+# Reconcile and launch happen in the SAME tick (13:02:12 reconciled #1910
+# done, 13:02:13 launched #1834), so the cost is one interval, not two.
+#
+# A tick is a /board read plus reconciliation, and #1597 added the /board
+# single-flight guard, so 20 ticks/hour is affordable. `Type=oneshot` + the
+# tick's own flock means it cannot stack even if it fired faster than a tick
+# takes to run. AccuracySec is tightened to 15s to match: systemd's default
+# batching slop of 1min is 33% of a 3min interval.
+#
+# Install: see deploy/coord-drive-queue.service's header, or
+# docs/DRIVE_QUEUE.md.
+
+[Unit]
+Description=Run coord drive-queue tick every 3 minutes (#1756)
+
+[Timer]
+OnBootSec=5min
+OnUnitActiveSec=3min
+AccuracySec=15s
+Persistent=true
+
+[Install]
+WantedBy=timers.target

coord/deploy/coord-notify.service

@@ -0,0 +1,48 @@
+# coord notify — periodic driver for thin-client setups (#1311).
+#
+# A systemd *user* unit (mirrors coord-agent/coord-serve/coord-web), paired
+# with coord-notify.timer. Runs `coord notify` on a schedule: polls each
+# agent for completion, posts the GH completion/failure comments, and
+# triggers the auto-loop (review-on-completion, fix-on-request-changes,
+# re-review-on-fix-completion). Install ONLY on the box that owns
+# ~/.coord/coord.db (dellserver in production — the same host that runs
+# coord-serve/coord-web) — it must NOT run on a thin-client machine, since
+# `coord notify` there would just re-route itself back over HTTP to the
+# daemon anyway (#906, daemon_reroute_target), needlessly.
+#
+# THIS TIMER IS THE SANCTIONED SINGLE DRIVER for thin-client coord-tui/coord
+# setups. Do NOT also hand-roll a `while`/`watch` loop calling `coord notify`
+# alongside it, and do NOT re-enable the TUI's own 30s auto-notify for a
+# thin client (it is deliberately suppressed — `is_remote_board_service()`,
+# tui/src/app/data.rs). Two drivers racing each other is exactly the failure
+# mode that caused the 2026-06-07 incident (duplicate fix workers from a
+# request-changes verdict getting auto-bounced twice) — see #476/#477 and
+# docs/ARCHITECTURE.md's "no orchestration daemon" section.
+#
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/coord-notify.service deploy/coord-notify.timer ~/.config/systemd/user/
+#   loginctl enable-linger "$USER"          # survive logout / reboot
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now coord-notify.timer
+#
+# This is a Type=oneshot service activated BY THE TIMER — do not
+# `systemctl --user enable coord-notify.service` directly (it has no
+# [Install] section; the timer unit is what you enable).
+#
+# Prereqs: same as coord-serve (coordinator.yml at ~/.coord/coordinator.yml,
+# a `gh`-authenticated environment for the GitHub writes `coord notify` makes).
+#
+# See docs/AGENT_OPERATIONS.md → "Periodic coord notify (coord-notify timer)".
+
+[Unit]
+Description=coord notify — periodic pipeline driver (#1311)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=%h/.coord-venv/bin/coord notify --config %h/.coord/coordinator.yml
+# Bounded below the timer's 5-minute cadence (coord-notify.timer) so a slow
+# run can't overlap the next fire.
+TimeoutStartSec=280

coord/deploy/coord-notify.timer

@@ -0,0 +1,24 @@
+# coord notify — periodic driver for thin-client setups (#1311). Fires
+# coord-notify.service (Type=oneshot) on a cadence. See that unit's header
+# for the full rationale ("THIS TIMER IS THE SANCTIONED SINGLE DRIVER").
+#
+# 5 minutes is deliberately coarser than the in-process TUI's 30s cadence —
+# this timer's job is "don't let the pipeline stall unnoticed for the whole
+# session," not sub-minute responsiveness. Tighten OnUnitActiveSec if that
+# proves too slow in practice; there's no correctness reason it needs to be
+# this conservative, just no reason to hammer `gh` harder than necessary.
+#
+# Install: see deploy/coord-notify.service's header, or
+# docs/AGENT_OPERATIONS.md → "Periodic coord notify (coord-notify timer)".
+
+[Unit]
+Description=Run coord notify every few minutes (#1311)
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=5min
+AccuracySec=30s
+Persistent=true
+
+[Install]
+WantedBy=timers.target

coord/deploy/coord-release-propagate.service

@@ -0,0 +1,83 @@
+# coord release propagate — the PROPAGATE half of merge-triggered release
+# (#1835, PKG-7).
+#
+# A systemd *user* unit (mirrors coord-drive-queue), paired with
+# coord-release-propagate.timer. Each fire is one attempt:
+#
+#   1. resolve the released version from PyPI's simple index;
+#   2. ask the drive queue and the board whether the fleet is QUIESCENT;
+#   3. if it is not — record a deferral and exit 0. This is the normal,
+#      expected outcome most of the time and it is NOT a failure;
+#   4. if it is — roll each lane in the daemon-first order, run
+#      `coord release verify` as the final gate, roll back on red, and
+#      release the drive-queue deploy gates (#1757) that were waiting for
+#      exactly this deploy.
+#
+# WHY THIS IS A TIMER AND NOT A GITHUB ACTION
+# -------------------------------------------
+# The *publish* half IS a GitHub Action (.github/workflows/auto-release.yml)
+# because publishing touches no running host. Propagation restarts every
+# agent, and a restart kills every in-flight headless worker — so it must
+# wait for a window where nothing is mid-flight. GitHub cannot see that;
+# only the board can. Hence: publish on merge, propagate on quiescence.
+#
+# WHICH HOST
+# ----------
+# Install ONLY on the daemon host (dellserver in production — the same box
+# that runs coord-serve / coord-drive-queue / coord-notify). This unit reads
+# `/board` and POSTs to every agent, and it releases drive-queue holds, so it
+# belongs where the queue and the board already live. Installing a second
+# copy elsewhere gives the fleet two independent things deciding to restart
+# it, which is the #1440 two-overseers failure in a new costume.
+#
+# COORD_BIN — same #1523 requirement as coord-drive-queue.service: the CLI
+# this unit runs must be a PINNED, NON-EDITABLE install, because it is the
+# thing that upgrades everything else. On dellserver ~/.local/bin/coord is a
+# symlink into ~/.coord-venv, which satisfies that and rides the ordinary
+# agent-venv lane. Do NOT install this unit on a dev box whose
+# ~/.local/bin/coord points at a checkout.
+#
+# SELF-UPDATE ORDERING: this unit's own CLI lives in the venv it is about to
+# swap. That is safe *because* #1241 made the swap atomic (blue/green symlink
+# flip) — a running `coord release propagate` keeps executing the fully-old
+# slot it started from; it can never observe a half-written site-packages.
+# The next fire runs the new one.
+#
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/coord-release-propagate.service \
+#      deploy/coord-release-propagate.timer ~/.config/systemd/user/
+#   loginctl enable-linger "$USER"
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now coord-release-propagate.timer
+#
+# (After the first release carrying #1835, `coord release propagate` installs
+# unit updates itself via each agent's POST /deploy-units — but it only
+# refreshes units a host ALREADY has, so this first install is by hand, once.)
+#
+# This is a Type=oneshot service activated BY THE TIMER — do not
+# `systemctl --user enable coord-release-propagate.service` directly.
+#
+# Read the journal it writes with `coord release history`, not just
+# `journalctl`: the JSONL record survives a half-installed venv and is the
+# thing that makes "the fleet reached that version" checkable after the fact.
+
+[Unit]
+Description=Propagate the released version to the fleet at the next quiescent window (#1835)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+# No --force, ever, from a timer. --force rolls over a BUSY fleet and kills
+# in-flight headless workers — the single thing this whole design exists to
+# avoid. It stays an interactive-operator flag.
+#
+# --verify and --rollback-on-red are the defaults; named explicitly here so
+# the unit reads as the policy it is, and so a future default change cannot
+# silently disarm the fleet's rollback.
+ExecStart=%h/.local/bin/coord release propagate --verify --rollback-on-red --config %h/.coord/coordinator.yml
+# A roll waits up to --timeout (180s) per agent for the new version to be
+# reported, across every machine, plus two full verification sweeps. Generous,
+# but well under the timer's cadence so a wedged run cannot run into the next.
+TimeoutStartSec=1800

coord/deploy/coord-release-propagate.timer

@@ -0,0 +1,38 @@
+# coord release propagate — fires coord-release-propagate.service
+# (Type=oneshot) on a cadence. See that unit's header for the full rationale.
+#
+# 20 minutes. The tick is cheap and almost always a no-op: it reads the board,
+# finds the fleet busy, records a deferral and exits. What the interval
+# actually buys is *latency from quiescence to deployed* — the window between
+# a drive finishing and the next one launching is minutes wide
+# (coord-drive-queue.timer fires every 3 minutes), so a slow propagation
+# cadence would routinely miss the gap and the fleet would sit a release
+# behind for hours.
+#
+# Not tighter than that, for two reasons. Each fire that *does* find a window
+# restarts every agent, so an over-eager cadence turns a transient idle moment
+# into a fleet restart the operator did not ask for. And a propagation run
+# holds the window it found: an interval shorter than a full roll+verify
+# sweep would just queue up runs behind each other.
+#
+# Persistent=true so a host that was asleep or rebooted catches up on the next
+# boot rather than waiting a full interval — the whole point is that the fleet
+# converges on the released version without anyone thinking about it.
+#
+# RandomizedDelaySec spreads fires if this unit is ever (against the advice in
+# the service header) installed on more than one host: two propagations
+# racing would both find the same window and both start restarting agents.
+# The real defence is "install on the daemon host only"; this is the belt.
+
+[Unit]
+Description=Attempt fleet propagation of the released version every 20 minutes (#1835)
+
+[Timer]
+OnBootSec=10min
+OnUnitActiveSec=20min
+RandomizedDelaySec=2min
+AccuracySec=1min
+Persistent=true
+
+[Install]
+WantedBy=timers.target

coord/deploy/coord-release-window.service

@@ -0,0 +1,119 @@
+# coord release nightly-window — guarantee the daemon host rolls instead of
+# waiting for a quiescent window that may never come (#2112).
+#
+# A systemd *user* unit (mirrors coord-drive-queue/coord-release-propagate),
+# paired with coord-release-window.timer. Each fire is one attempt:
+#
+#   1. resolve the released version and the daemon host's own python-lane
+#      version; if the daemon host is already current, STOP — the queue is
+#      never touched (#2112 acceptance 3);
+#   2. otherwise, `systemctl --user stop coord-drive-queue.timer` — no new
+#      drives may launch for the rest of this run;
+#   3. wait (bounded — see TimeoutStartSec below and
+#      `coord release nightly-window --drain-deadline`) for whatever is
+#      already running to finish, reconciling with `coord drive-queue tick
+#      --reconcile-only` on every poll (#2110 — this is what stops the
+#      drain from deadlocking now that the timer that normally does that
+#      reconciliation is stopped);
+#   4. roll with `coord release propagate --daemon-host <derived>
+#      --target <resolved>` — no --force, ever (trap 1);
+#   5. `systemctl --user start coord-drive-queue.timer` — ALWAYS, whatever
+#      happened in 1-4, including a crash;
+#   6. report the outcome: stdout (this unit's journal), the
+#      `~/.coord/release_window.jsonl` journal (`coord release
+#      window-history`), and — for anything short of a clean roll or a
+#      confirmed already-current fleet — the same escalation channel
+#      `coord drive escalations` and the TUI already surface #2101's
+#      drain-deadline escalation through.
+#
+# WHY THIS EXISTS SEPARATELY FROM coord-release-propagate.timer
+# ----------------------------------------------------------------
+# `coord release propagate` already rolls every OTHER host at its own
+# per-host quiescent window (#2067), and cordons a behind host so it drains
+# on its own (#2101). Neither mechanism reaches the daemon host itself: the
+# daemon must lead every roll (the documented 405), so if IT is busy the
+# whole run defers — and dellserver is both the daemon host and the box
+# whose drive-queue tick launches work fleet-wide, so almost any queued
+# drive anywhere keeps it "busy". Cordoning the daemon host would not help:
+# cordoning stops new work from ROUTING there, but does not stop the
+# daemon's own tick from LAUNCHING new drive-queue entries in the first
+# place. The only way to guarantee the daemon host reaches quiescence is to
+# stop the thing that launches work onto it — which is exactly what this
+# unit's `--ensure-queue-running` ExecStopPost= below makes safe to do
+# unattended. See coord/release_window.py's module docstring for the full
+# mechanism and the 2026-08-10 measurement (eleven releases behind, with
+# elitebook idle and rollable the whole time).
+#
+# GATED ON #2110 — HARD PREREQUISITE. Steps 2-3 above are exactly the
+# sequence that deadlocked on 2026-08-10: the reconciler that clears a
+# finished drive's `running` row lives INSIDE `coord drive-queue tick`, so
+# stopping the timer used to stop reconciliation too, and the last drive's
+# row would stay `running` forever — the daemon host would read as busy
+# permanently and this unit would defer every night, unattended, silently,
+# forever. Do not install this unit on a build that predates #2110.
+#
+# WHICH HOST
+# ----------
+# Install ONLY on the daemon host (dellserver in production — the same box
+# that runs coord-serve/coord-drive-queue/coord-release-propagate). This
+# unit stops and restarts coord-drive-queue.timer, which only exists on
+# that host; installing a second copy elsewhere has no queue to stop and
+# would just repeatedly fail `systemctl --user stop coord-drive-queue.timer`
+# — a locally-scoped, harmless-but-noisy failure, not the #1440
+# two-overseers hazard `coord-release-propagate.timer`'s header warns about,
+# but still pointless. Don't.
+#
+# COORD_BIN — same #1523 pinned-non-editable-install requirement as
+# coord-drive-queue.service/coord-release-propagate.service: the CLI this
+# unit runs must not be rewritable out from under a live run. See those
+# units' headers for the full rationale; on dellserver ~/.local/bin/coord
+# already satisfies it.
+#
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/coord-release-window.service \
+#      deploy/coord-release-window.timer ~/.config/systemd/user/
+#   loginctl enable-linger "$USER"
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now coord-release-window.timer
+#
+# Read the journal it writes with `coord release window-history`, not just
+# `journalctl` — the JSONL record survives a half-installed venv, same
+# reason coord-release-propagate.service's does.
+
+[Unit]
+Description=Nightly release window on the daemon host (#2112)
+After=network-online.target coord-drive-queue.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+# No --force, ever (trap 1) — coord/commands/release.py's
+# release_nightly_window never passes it to the `coord release propagate`
+# it shells out to. A drain that has not finished by the deadline is
+# reported and declined, not overridden.
+ExecStart=%h/.local/bin/coord release nightly-window --config %h/.coord/coordinator.yml
+# #2112 trap 4 / acceptance 4: "the queue timer is running after the job in
+# EVERY path, including the failure ones — test by killing the job
+# mid-window." A `finally` block inside ExecStart cannot survive SIGKILL
+# (TimeoutStartSec below, or an operator's own `systemctl --user kill`).
+# ExecStopPost= is systemd's OWN guarantee of exactly that: it runs after
+# the main process exits for ANY reason — clean exit, non-zero exit, or
+# killed by a signal — so this is the backstop the in-process `finally`
+# cannot be. `--ensure-queue-running` does nothing but
+# `systemctl --user start coord-drive-queue.timer` and is idempotent: on
+# the overwhelmingly common path where ExecStart already restarted the
+# timer cleanly, this is a harmless no-op assertion, not a second action.
+ExecStopPost=%h/.local/bin/coord release nightly-window --ensure-queue-running --config %h/.coord/coordinator.yml
+# The drain alone may wait up to its own --drain-deadline (default 1h) on
+# top of the roll+verify sweep `coord release propagate` performs
+# (generous relative to its own 1800s TimeoutStartSec — see
+# coord-release-propagate.service). 2.5h total leaves this unit's own
+# worst case well inside the 22:00-08:00 quiet-hours window even starting
+# at 03:00, per coord-release-window.timer's header.
+TimeoutStartSec=9000
+
+# This is a Type=oneshot service activated BY THE TIMER — do not
+# `systemctl --user enable coord-release-window.service` directly (it has
+# no [Install] section; the timer unit is what you enable — same pattern
+# as coord-release-propagate.service/coord-drive-queue.service).

coord/deploy/coord-release-window.timer

@@ -0,0 +1,36 @@
+# coord release nightly-window — fires coord-release-window.service
+# (Type=oneshot) once a night. See that unit's header for the full
+# rationale (#2112).
+#
+# 03:00 local, inside the 22:00-08:00 quiet hours already used for
+# notifications (see coord-notify's own schedule) — an operator is least
+# likely to be mid-drive at 03:00, and the drain deadline
+# (coord/release_window.py's DEFAULT_DRAIN_DEADLINE_SECONDS, 1h by default)
+# leaves comfortable room to finish and restart the queue timer well before
+# the working day, even in the worst case where the drain times out.
+#
+# RandomizedDelaySec is small and exists only to avoid firing at the exact
+# same wall-clock instant `coord-drive-queue.timer`'s own OnCalendar-free
+# interval schedule might land on, not because two hosts might race this
+# unit — it belongs on the daemon host ONLY (same rule as
+# coord-release-propagate.timer; see that unit's header for why a second
+# copy elsewhere is the #1440 two-overseers failure in a new costume).
+#
+# Persistent=true (#2112 trap 4 / acceptance-adjacent): a host that was
+# asleep or rebooted through 03:00 still catches up on the next boot, rather
+# than silently skipping a whole night. `coord release nightly-window`
+# itself is idempotent — see its module docstring's `needs_roll`: a fleet
+# already current at whatever time this actually fires does not stop the
+# queue at all.
+
+[Unit]
+Description=Nightly release window on the daemon host (#2112)
+
+[Timer]
+OnCalendar=*-*-* 03:00:00
+RandomizedDelaySec=5min
+AccuracySec=1min
+Persistent=true
+
+[Install]
+WantedBy=timers.target

coord/deploy/coord-serve.service

@@ -0,0 +1,82 @@
+# coord serve — portable control-center daemon (#584/#591).
+#
+# A systemd *user* unit (mirrors coord-agent). Runs the read+write daemon that
+# fronts the one shared ~/.coord/coord.db so any Tailscale machine renders/drives
+# the same board. Install on the always-on box that owns the DB (dellserver).
+#
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/coord-serve.service ~/.config/systemd/user/
+#   loginctl enable-linger "$USER"          # survive logout / reboot
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now coord-serve
+#
+# Prereqs on the daemon host:
+#   - ~/.coord-venv has a coord BUILD that includes `coord serve` (a release
+#     >= the #584/#590 cut, or an editable checkout of the branch). PyPI
+#     releases before that do NOT have the command.
+#   - ~/.coord/coordinator.yml exists (canonical location; the daemon serves it
+#     at GET /config so clients need none). Resolution: $COORD_CONFIG →
+#     ~/.coord/coordinator.yml → ./coordinator.yml.
+#   - ~/.coord/coord.db exists (after the one-time cutover/ETL).
+#   - Bearer token (recommended): printf '%s' "<secret>" > ~/.coord/serve_token
+#     && chmod 600 ~/.coord/serve_token   (resolve_serve_token reads it; never
+#     put --token on ExecStart — it would leak via `ps`).
+#
+# See docs/AGENT_OPERATIONS.md → "Control-center daemon (coord serve)".
+
+[Unit]
+Description=coord serve — portable control-center daemon (#584)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# PATH here merges TWO independent, still-load-bearing fixes — #1831 found
+# them landed a month apart, each unaware of the other, and each one alone
+# regresses the other's issue:
+#
+# - #1814 added ~/.cargo/bin. Defence in depth ONLY — never the fix on its
+#   own. A systemd user unit's PATH is systemd's, not a login shell's:
+#   ~/.profile is never sourced, so ~/.cargo/bin is absent and `cargo test`
+#   inside a `coord merge --revalidate` run died with "command not found".
+#   The real fix is in scripts/coord-test-runner.sh, which resolves each
+#   toolchain explicitly and reports a MISSING one as an infrastructure
+#   error rather than a red suite — because a PATH= line here fixes this
+#   host and leaves the next one broken silently, which is the same failure
+#   shape as the bug. Keep both.
+# - #1117 added the repo venv (%h/src/claude-coordinator/.venv/bin) so
+#   acceptance.drivers subprocesses shelled out via
+#   subprocess.run(shell=True) (e.g. the cli-pytest driver's `pytest
+#   tests/acceptance/{ms}`) resolve `pytest`/`python3` with the repo's
+#   runtime deps (e.g. httpx) instead of falling back to bare
+#   /usr/bin/python3, which lacks them -> every acceptance run/record
+#   silently failed with an ImportError, not a real test failure.
+#
+# #1831: putting the repo venv FIRST let a stale editable checkout there
+# shadow the pinned release for every `shutil.which("coord")` resolution
+# (coord_argv(), coord/drive.py) — the daemon ran 0.4.105 while everything
+# it spawned ran 0.4.103 editable code from a checkout nobody was updating.
+# ~/.local/bin goes ahead of it (a symlink to ~/.coord-venv/bin/coord, i.e.
+# the pinned release) so `coord` always resolves there first and a stale
+# checkout can never shadow it again; the repo venv stays LAST, after
+# ~/.local/bin, so pytest/python3 still see it for #1117.  This ordering is
+# the structural fix — see the `coord health`/`coord doctor` unit_drift
+# check (#1831), which flags any unit whose PATH puts a `.venv/bin` entry
+# ahead of ~/.local/bin or ~/.coord-venv/bin.
+Environment=PATH=%h/.cargo/bin:%h/.local/bin:%h/src/claude-coordinator/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
+ExecStart=%h/.coord-venv/bin/coord serve --config %h/.coord/coordinator.yml --host 0.0.0.0 --port 7435
+Restart=on-failure
+RestartSec=3
+# #2095: coord-web (its sibling on the same host, restarted through the same
+# `_restart_sibling_unit` caller) went down for the length of a fleet roll
+# because nothing bounded how long systemd would wait on its stop — an SSE
+# client held it open indefinitely. coord-serve serves no `text/event-stream`
+# endpoint today so it was not the unit that actually hung, but nothing
+# structural stops a future one (a stuck DB write, a wedged client
+# connection) from doing the same thing here, uncapped, for up to systemd's
+# 90s default. Bounding it explicitly costs nothing on the fast path.
+TimeoutStopSec=10
+
+[Install]
+WantedBy=default.target

coord/deploy/coord-web-dist-build.service

@@ -0,0 +1,43 @@
+# coord-web-dist-build — pull merged main and rebuild the React webapp bundle
+# that `coord web --dist` serves (#1543), paired with
+# coord-web-dist-build.timer.
+#
+# A systemd *user* unit, Type=oneshot, mirroring coord-drive-queue.service's
+# tick pattern (timer-fired, its own flock so a slow run can't stack).  Runs
+# deploy/coord-web-dist-build.sh, which:
+#   - fetches origin/main into ~/src/claude-coordinator (read-only — only
+#     `git fetch` + `rev-parse`, never touches that checkout's working tree
+#     or whatever branch an operator has it parked on),
+#   - builds coord/dashboard/webapp from that SHA inside a DEDICATED worktree
+#     (~/.coord-web-checkout, never shared with an operator or `coord drive`),
+#   - atomically repoints ~/coord-web-dist at the new build.
+#
+# Deliberately separate from coord-agent/coord-serve/coord-web's
+# ~/.coord-venv: this unit never runs `pip install`, never touches that venv,
+# and its failure mode (a broken npm build) leaves the PREVIOUS release live
+# — see the script's header for the exact guarantee. Restarting THIS unit
+# does not restart coord-web, coord-serve, or coord-agent, and does not
+# interrupt an attended /ws/terminal session (no process restart happens at
+# all on a normal publish — see the script header).
+#
+# Install: see deploy/coord-web-dist-build.sh's header, or
+# docs/PHONE_WEBAPP.md / docs/AGENT_OPERATIONS.md.
+#
+# This is a Type=oneshot service activated BY THE TIMER — do not
+# `systemctl --user enable coord-web-dist-build.service` directly (it has no
+# [Install] section; the timer unit is what you enable).
+
+[Unit]
+Description=Build coord webapp dist from merged main (#1543)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=%h/.local/bin/coord-web-dist-build.sh
+# The script has its own flock (coord-web-dist-build.lock); this is a
+# generous ceiling for a wedged `npm ci`/`npm run build`, well below the
+# timer's 1-minute cadence so a genuinely stuck run can't run into the next
+# fire indefinitely.
+TimeoutStartSec=300
+Environment=PATH=%h/.local/bin:%h/.cargo/bin:/usr/local/bin:/usr/bin:/bin