code-coordinator 0.5.296__tar.gz → 0.5.298__tar.gz

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.296
+Version: 0.5.298
 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.296 → code_coordinator-0.5.298}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.296
+Version: 0.5.298
 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.296 → code_coordinator-0.5.298}/code_coordinator.egg-info/SOURCES.txt

@@ -508,6 +508,7 @@ tests/test_conflict_fix.py
 tests/test_conflict_fix_semantic.py
 tests/test_coord_log_daemon_fallback_2547.py
 tests/test_coord_test.py
+tests/test_coord_test_runner_acceptance_toolchain_2936.py
 tests/test_coord_test_runner_baseline.py
 tests/test_coord_test_runner_populated_home.py
 tests/test_coord_test_runner_routing.py

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/code_coordinator.egg-info/scm_file_list.json

@@ -534,6 +534,7 @@
     "tests/test_conflict_fix_semantic.py",
     "tests/test_coord_log_daemon_fallback_2547.py",
     "tests/test_coord_test.py",
+    "tests/test_coord_test_runner_acceptance_toolchain_2936.py",
     "tests/test_coord_test_runner_baseline.py",
     "tests/test_coord_test_runner_populated_home.py",
     "tests/test_coord_test_runner_routing.py",

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.296",
+  "tag": "0.5.298",
   "distance": 0,
-  "node": "ga711fc248f5a8207d97fdc8ec5709d04beb8f505",
+  "node": "gaa327b0f6d037fbb6df6db3ef4dd15e123624825",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-29"

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/coord/agent.py

@@ -1742,6 +1742,53 @@ def _worker_subprocess_env(
     return env
 
 
+def worker_coord_reachable(base_env: dict[str, str] | None = None) -> tuple[bool, str]:
+    """#2936: does ``coord`` resolve on a WORKER's PATH — not this agent
+    process's own?
+
+    Built on the exact env a real worker is spawned into
+    (:func:`_worker_subprocess_env`, whose #402/#2569 strip removes the
+    fleet's pinned ``~/.coord-venv/bin`` from PATH). A worker that cannot
+    resolve ``coord`` can run its entire suite, PASS, and be structurally
+    unable to record that verdict (``coord test <id> --passed``) — the
+    missing verdict then reads as a TEST FAILURE and walks the
+    ``models.escalation`` ladder, re-dispatching already-correct work on a
+    more expensive model for a PATH gap, not a weak one (#2897 cost one
+    instance of this an extra opus rerun on top of an already-passing
+    sonnet leg).
+
+    Before this, the gap was discovered only when a smoke worker's own
+    final-turn transcript happened to mention it (as #2897's did) — this
+    function exists so the agent can say so ITSELF, at startup, in
+    ``journalctl --user -u coord-agent``, mirroring #1671's PATH diagnostics
+    for capability probes.
+
+    Returns ``(ok, message)`` rather than logging directly, so the check is
+    testable with a synthetic *base_env* with no mocking of ``shutil.which``
+    or the logging module required. ``base_env=None`` (the production
+    default) resolves against this process's real ``os.environ``, exactly
+    like :func:`_worker_subprocess_env` itself.
+    """
+    worker_path = _worker_subprocess_env(base_env).get("PATH", "")
+    resolved = shutil.which("coord", path=worker_path)
+    if resolved:
+        return True, (
+            f"coord agent: worker PATH check OK — 'coord' resolves at {resolved} "
+            "(a smoke/test worker on this machine can record its verdict, #2936)"
+        )
+    return False, (
+        "coord agent: WARNING 'coord' does NOT resolve on a WORKER's PATH — "
+        f"searched: {worker_path!r}. A smoke/test worker on this machine can "
+        "run its whole suite, PASS, and be structurally unable to record the "
+        "verdict via `coord test <id> --passed`; the missing verdict then "
+        "reads as a TEST FAILURE and escalates the model for an "
+        "infrastructure gap, not a weak one (#2936). Fix: re-run "
+        "install-agent.sh on this machine so ~/.local/bin/coord exists and "
+        "symlinks to $HOME/.coord-venv/bin/coord (the blue/green symlink "
+        "itself, never a resolved .blue/.green path)."
+    )
+
+
 def _slugify(text: str, max_len: int = 40) -> str:
     """Convert *text* to a URL/branch-safe slug."""
     slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
@@ -5444,6 +5491,18 @@ class AgentServer:
         self.log_dir.mkdir(parents=True, exist_ok=True)
         self._load_state()
 
+        # #2936: verify AT STARTUP — not a suite-run later — that a worker
+        # this agent spawns will be able to resolve `coord` on its own PATH
+        # to record a test/smoke verdict. Only the failure case is logged:
+        # this file configures no logging handler of its own (`coord agent`
+        # never calls `configure_daemon_logging`, unlike `coord serve` —
+        # #2862), so a bare `_log.info` here would be a silent no-op on the
+        # real daemon while `_log.warning` reaches `journalctl` via Python's
+        # stderr handler-of-last-resort with zero configuration needed.
+        _coord_reachable, _coord_reachable_msg = worker_coord_reachable()
+        if not _coord_reachable:
+            _log.warning(_coord_reachable_msg)
+
     # ── #2299: hot config reload ────────────────────────────────────────────
 
     #: Config-derived state that a reload refreshes, versus the state it must

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/coord/deploy/coord-agent.service

@@ -74,15 +74,40 @@
 #   systemctl --user restart coord-agent
 #
 # See docs/AGENT_OPERATIONS.md → "Install a new agent (first time)".
-
+#
+# #2938: Restart=always, not on-failure. `POST /update` stops this unit's
+# own process so it can come back on the swapped venv — the agent IS its own
+# recovery channel here, via an explicit `systemctl --user restart` the
+# process fires at itself just before exiting (coord/agent_app.py's
+# `_default_exec_restart`). When that explicit restart lands, this process
+# exits 0 either way (a clean stop) and `Restart=on-failure` — correctly, by
+# its own definition — declines to act on a clean exit. If the explicit
+# restart request is ever lost (a dropped systemd/D-Bus call, a race with
+# the process's own exit, anything), NOTHING brings the unit back: it sits
+# `enabled`/`inactive` forever, port 7433 refused, and the fleet has lost
+# its only remote-control channel to that host. `Restart=always` makes
+# systemd itself the backstop for a clean exit, independent of whether the
+# self-restart call landed — dell64, 2026-08-29, ~23 minutes of that exact
+# outage, recovered only because someone could walk to the machine.
+#
+# StartLimitIntervalSec/StartLimitBurst (#2938) bound it: 5 restarts inside
+# 5 minutes and systemd stops trying, landing the unit in `failed` with
+# `Result: start-limit-hit` — visible in `systemctl --user status` and the
+# journal — rather than crash-looping forever. A binary that is genuinely
+# broken (not just "the explicit restart didn't land") must fail loud, not
+# spin silently; `Restart=always` without a limit would trade one silent
+# failure (never restarts) for another (restarts forever with no signal
+# anything is wrong).
 [Unit]
 Description=Coordinator agent server (port <PORT>)
 After=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=%h/.coord-venv/bin/coord agent --machine <MACHINE_NAME> --port <PORT>
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=PATH=%h/.coord-venv/bin:%h/.cargo/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin
 

{code_coordinator-0.5.296 → code_coordinator-0.5.298/coord}/deploy/coord-serve.service

@@ -36,11 +36,23 @@
 #     put --token on ExecStart — it would leak via `ps`).
 #
 # See docs/AGENT_OPERATIONS.md → "Control-center daemon (coord serve)".
-
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-serve restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 [Unit]
 Description=coord serve — portable control-center daemon (#584)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -78,7 +90,7 @@ Type=simple
 # ahead of ~/.local/bin or ~/.coord-venv/bin.
 Environment=PATH=%h/.cargo/bin:%h/.local/bin:%h/src/code-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
+Restart=always
 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

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/coord/deploy/coord-web.service

@@ -92,11 +92,24 @@
 # (#1830), even though the underlying reason differs (that one protects a
 # spawned tmux server from this unit's own cgroup teardown; this one avoids
 # ever having to signal a nonexistent auxiliary process group at all).
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-web restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 
 [Unit]
 Description=coord web — phone/web control-center dashboard (#700)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -118,7 +131,7 @@ ExecStart=%h/.coord-venv/bin/coord web --config %h/.coord/coordinator.yml --host
 # setting it here too ensures any other subprocess spawned by coord web also
 # has a sane terminal type without requiring a code fix for each callsite.
 Environment=TERM=xterm-256color
-Restart=on-failure
+Restart=always
 RestartSec=3
 # #2095 — see the header comment above. Bounds the SSE-drain hang that took
 # the dashboard down during the 2026-08-10 fleet roll.

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/deploy/coord-agent.service

@@ -74,15 +74,40 @@
 #   systemctl --user restart coord-agent
 #
 # See docs/AGENT_OPERATIONS.md → "Install a new agent (first time)".
-
+#
+# #2938: Restart=always, not on-failure. `POST /update` stops this unit's
+# own process so it can come back on the swapped venv — the agent IS its own
+# recovery channel here, via an explicit `systemctl --user restart` the
+# process fires at itself just before exiting (coord/agent_app.py's
+# `_default_exec_restart`). When that explicit restart lands, this process
+# exits 0 either way (a clean stop) and `Restart=on-failure` — correctly, by
+# its own definition — declines to act on a clean exit. If the explicit
+# restart request is ever lost (a dropped systemd/D-Bus call, a race with
+# the process's own exit, anything), NOTHING brings the unit back: it sits
+# `enabled`/`inactive` forever, port 7433 refused, and the fleet has lost
+# its only remote-control channel to that host. `Restart=always` makes
+# systemd itself the backstop for a clean exit, independent of whether the
+# self-restart call landed — dell64, 2026-08-29, ~23 minutes of that exact
+# outage, recovered only because someone could walk to the machine.
+#
+# StartLimitIntervalSec/StartLimitBurst (#2938) bound it: 5 restarts inside
+# 5 minutes and systemd stops trying, landing the unit in `failed` with
+# `Result: start-limit-hit` — visible in `systemctl --user status` and the
+# journal — rather than crash-looping forever. A binary that is genuinely
+# broken (not just "the explicit restart didn't land") must fail loud, not
+# spin silently; `Restart=always` without a limit would trade one silent
+# failure (never restarts) for another (restarts forever with no signal
+# anything is wrong).
 [Unit]
 Description=Coordinator agent server (port <PORT>)
 After=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=%h/.coord-venv/bin/coord agent --machine <MACHINE_NAME> --port <PORT>
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=PATH=%h/.coord-venv/bin:%h/.cargo/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin
 

{code_coordinator-0.5.296/coord → code_coordinator-0.5.298}/deploy/coord-serve.service

@@ -36,11 +36,23 @@
 #     put --token on ExecStart — it would leak via `ps`).
 #
 # See docs/AGENT_OPERATIONS.md → "Control-center daemon (coord serve)".
-
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-serve restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 [Unit]
 Description=coord serve — portable control-center daemon (#584)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -78,7 +90,7 @@ Type=simple
 # ahead of ~/.local/bin or ~/.coord-venv/bin.
 Environment=PATH=%h/.cargo/bin:%h/.local/bin:%h/src/code-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
+Restart=always
 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

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/deploy/coord-web.service

@@ -92,11 +92,24 @@
 # (#1830), even though the underlying reason differs (that one protects a
 # spawned tmux server from this unit's own cgroup teardown; this one avoids
 # ever having to signal a nonexistent auxiliary process group at all).
+#
+# #2938: Restart=always (was on-failure), + a StartLimitIntervalSec/
+# StartLimitBurst backstop — see deploy/coord-agent.service's header for the
+# full incident this closes (a clean stop that Restart=on-failure correctly
+# declines to act on, with no other recovery path, leaving the unit
+# `enabled`/`inactive` forever). coord-web restarts through the same
+# `_restart_sibling_unit` caller as coord-agent's own self-restart
+# (coord/agent_app.py, #2069), so it is exposed to the identical failure
+# shape if that restart request is ever lost. 5 restarts / 5 minutes before
+# systemd gives up and lands the unit in `failed` (`start-limit-hit`) —
+# visible, not a silent crash-loop.
 
 [Unit]
 Description=coord web — phone/web control-center dashboard (#700)
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -118,7 +131,7 @@ ExecStart=%h/.coord-venv/bin/coord web --config %h/.coord/coordinator.yml --host
 # setting it here too ensures any other subprocess spawned by coord web also
 # has a sane terminal type without requiring a code fix for each callsite.
 Environment=TERM=xterm-256color
-Restart=on-failure
+Restart=always
 RestartSec=3
 # #2095 — see the header comment above. Bounds the SSE-drain hang that took
 # the dashboard down during the 2026-08-10 fleet roll.

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/docs/CUSTOMER_FACING_APPS.md

@@ -109,10 +109,23 @@ natal-chart (Preview)  ref=issue-39-transit-page-annual-profections-mock-up
     https://ed9f21ad.natal-chart-3ew.pages.dev
 ```
 
-The hash is not derivable from the branch name, and the branch-alias URL
-Cloudflare also publishes truncates at 28 characters, which these branch names
-exceed. Read it from the forge instead — `cloudflare/pages-action` creates a
-GitHub Deployment per PR whose latest status carries the real URL:
+The hash is not derivable from the branch name, and **there is no branch-alias
+URL to fall back on** — measured 2026-08-29 against this project, aliasing is off
+entirely, `main` included:
+
+```
+404  https://issue-56-transit-chart-add-a.natal-chart-3ew.pages.dev
+404  https://main.natal-chart-3ew.pages.dev
+200  https://f432dd47.natal-chart-3ew.pages.dev
+```
+
+Note the domain too: it is `natal-chart-3ew.pages.dev`, while
+`deploy-cloudflare.yml` says `projectName: natal-chart`. Cloudflare's `-3ew`
+suffix is not derivable from anything coord holds, so a repo's preview host has
+to be *read*, never *constructed* — see #2948, which is this exact assumption
+shipped as a config template. Read it from the forge instead —
+`cloudflare/pages-action` creates a GitHub Deployment per PR whose latest status
+carries the real URL:
 
 ```bash
 gh api "repos/{owner}/{repo}/deployments?ref={branch}" --jq '.[0].id'
@@ -122,21 +135,58 @@ gh api "repos/{owner}/{repo}/deployments/{id}/statuses" --jq '.[0].environment_u
 Match on the **environment name** (`"<project> (Preview)"`), not on recency —
 production deploys are hash URLs too and interleave with previews in that list.
 
-### 2. A `uat` gate between Review and Merge · **NOT BUILT — claude-coordinator#2687**
+### 2. A `uat` gate between Review and Merge · **shipped (#2687) · ON for natal-chart since 2026-08-29**
 
-The gap that lets everything else fail. Today `merge.auto_drain: true` with
-`max_per_tick: 1` means the daemon merges the moment Test + Review + CI go
-green, and the push to `main` fires production. **There is no per-repo,
-pre-merge operator hold anywhere in coord**: `coord pause` only stops agent
-routing, and drive-queue's `--hold-after` (#1757) fires *after* the merge, which
-for an auto-deploying repo is after the customer can already see it.
+This was the gap that let everything else fail, and it is closed. Before it,
+`merge.auto_drain: true` with `max_per_tick: 1` meant the daemon merged the
+moment Test + Review + CI went green and the push to `main` fired production,
+with **no per-repo, pre-merge operator hold anywhere in coord** — `coord pause`
+only stops agent routing, and drive-queue's `--hold-after` (#1757) fires *after*
+the merge, which for an auto-deploying repo is after the customer can already
+see it.
 
-#2687 adds a `uat` gate ordered before `merge`, a
-`coord uat <id> --passed|--failed` verdict modelled on `coord test`, and — the
-part that decides whether it gets used or bypassed — **the preview URL surfaced
-in `coord status` and the TUI**, next to the command that clears the gate. A
-gate that makes the operator go hunting for the link will be routed around
-inside a week.
+`coord merge` now refuses a PR whose UAT verdict is missing or failed, printing
+the preview URL and the exact command to clear it:
+
+```
+uat verdict missing — preview: <url> — run: coord uat <assignment-id> --passed
+```
+
+**Enabling it is a two-part opt-in, and one half alone does nothing:**
+
+```yaml
+pipeline:
+  default_gates: [test, review, uat, merge]   # fleet-wide half — inert on its own
+repos:
+  - name: natal-chart
+    uat_preview: "https://github.com/JDonaghy/natal-chart/pull/{pr_number}"
+```
+
+`coord.merge_queue.requires_uat` demands **both**, so listing `uat` fleet-wide is
+safe: a repo without `uat_preview` never blocks, no matter what `default_gates`
+says. Clear the gate with `coord uat <assignment-id> --passed|--failed` (an
+assignment id, not repo/issue) — modelled on `coord test`.
+
+**Two follow-ups are open, and both matter before you enable this for a second
+repo:**
+
+- **#2948 — `uat_preview` cannot build a working Cloudflare URL.** The
+  `{pr_branch_slug}` placeholder assumes branch aliases that this project does
+  not publish (see §1). It renders a plausible dead link and
+  `resolve_uat_preview_url` never raises, so the failure is silent. natal-chart's
+  template therefore points at the **PR page**, whose timeline carries the live
+  `natal-chart (Preview)` deployment — one click from the real build, and it
+  cannot 404.
+- **#2947 — `coord drive` does not classify the gate.** `_merge_gate_kind`
+  knows `smoke`/`review`/`unknown_head` and returns `None` for a uat block, so an
+  unattended drive spends its merge attempts blind and lands the drive-queue
+  entry in terminal `blocked` rather than parking. Until it lands, expect to
+  `remove` + `add` the queue entry after recording the verdict.
+
+The part #2687 called the deciding one — **the preview URL surfaced in `coord
+status` and the TUI**, next to the command that clears the gate — is what #2947
+and #2948 between them still owe. A gate that makes the operator go hunting for
+the link will be routed around inside a week.
 
 ### 3. Sign-off reaches the customer without you relaying it · **partially built**
 
@@ -148,12 +198,27 @@ explicitly out of scope for #2588 and never filed.
 Until it exists, step 3 is you, by hand, in the runbook below. That is fine at
 one customer and does not survive two.
 
-### 4. Visual regression baselines · **NOT BUILT — natal-chart#47**
+### 4. Visual regression baselines · **shipped (natal-chart#47)**
 
 So the human is the *second* line of defence, not the first. Screenshot the
 core screens against a **fixed fixture** — one hardcoded chart, a frozen clock —
 and diff them in CI.
 
+Built as Playwright screenshot specs in `packages/web/e2e/`, with committed
+baselines beside each spec:
+
+```
+packages/web/playwright.config.ts
+packages/web/e2e/chart-wheel.spec.ts  + chart-wheel.spec.ts-snapshots/chart-wheel-chromium-linux.png
+packages/web/e2e/positions.spec.ts    + positions.spec.ts-snapshots/positions-chromium-linux.png
+packages/web/e2e/zr-tab.spec.ts       + zr-tab.spec.ts-snapshots/zr-tab-chromium-linux.png
+```
+
+**A deliberate restyle of a covered screen therefore fails CI until its baseline
+is re-recorded, and that is the harness working.** Say so in the issue when you
+file one — a worker that reads a red baseline diff as a defect will spend fix
+rounds trying to restore the look you asked it to change.
+
 The honest caveat, worth stating because it is the trap: pixel diffing is flaky
 across font rendering and browser versions, and **font fallback is exactly the
 defect this is meant to catch**, so a tolerance loose enough to ignore font
@@ -206,33 +271,41 @@ the preview" is the control that already failed on 2026-08-23. This file
 documents a *mechanism*; where the mechanism does not exist yet it says so, in
 bold, with the issue number.
 
-## The manual runbook — what to do until #2687 lands
-
-For a customer-facing repo, right now, with no gate to help you:
+## The runbook — a repo with the gate on
 
 1. **Queue the work as normal** (`coord drive-queue add`). Nothing special.
-2. **Watch for the PR.** The work leg completing is your cue — the branch is
-   pushed and the PR opens shortly after.
-3. **Get the preview URL** with the two `gh api` calls in step 1 above. The URL
-   does not exist the instant the PR opens; the preview build has to finish.
+2. **Wait for `coord merge` to refuse.** That refusal *is* the notification —
+   it names the gate, the preview link and the command. You are no longer racing
+   `auto_drain`; the merge cannot happen without your verdict.
+3. **Get the real preview URL** with the two `gh api` calls in §1. Until #2948
+   lands the gate's own link points at the PR, so in practice: open the PR and
+   click the `natal-chart (Preview)` deployment in its timeline. The URL does not
+   exist the instant the PR opens; the preview build has to finish.
 4. **Look at it yourself first.** Walk the screens the change touched. You will
    catch most of it here, and it costs a minute.
-5. **Send the customer the URL** and wait for a yes.
-6. **Then let it merge.**
-
-Step 6 is the weak one and you should know why: **you cannot reliably hold a
-merge today.** `auto_drain` will take the PR as soon as its gates are green,
-whether or not you have heard back. The available holds are all bad in
-different ways — draft the PR on GitHub (targeted, but strands the merge-queue
-entry in `NEEDS_ATTENTION`), or flip `merge.auto_drain: false` in
-`~/.coord/coordinator.remote.yml` (a hard guarantee that stalls auto-merge for
-every other repo in flight, and is easy to forget to switch back).
-
-**This is exactly why #2687 exists.** Until it lands, on a change where the
-customer's opinion genuinely gates the release, the honest options are to pick
-one of those two holds consciously, or to accept that the merge may win the
-race — as it did on 2026-08-24, when natal-chart#42 merged and deployed to
-production during the conversation about how to review it before it shipped.
+5. **Send the customer the URL** and wait for a yes. Through the portal, that is
+   `coord portal enqueue-preview <SUB-ID> <url>` then `coord portal
+   enqueue-status <SUB-ID> quality-check`, both on the daemon host, and her
+   answer arrives as a `preview.approved` / `preview.changes_requested` event
+   (`docs/CUSTOMER_PORTAL.md`).
+6. **Record the verdict and let it merge:** `coord uat <assignment-id> --passed`.
+
+**What is still weak, and why.** Nothing auto-fires off `preview.approved` — it
+is not wired into `coord merge` or the merge queue, so step 6 remains a
+deliberate human act. And per #2947 an unattended drive will have burned its
+merge attempts against the block and parked the queue entry in terminal
+`blocked` by the time you get here, so expect a `remove` + `add` after recording
+the verdict.
+
+**For a repo with the gate off, you cannot reliably hold a merge at all.**
+`auto_drain` takes the PR as soon as its gates are green, whether or not you
+have heard back. The available holds are all bad in different ways — draft the
+PR on GitHub (targeted, but strands the merge-queue entry in
+`NEEDS_ATTENTION`), or flip `merge.auto_drain: false` (a hard guarantee that
+stalls auto-merge for every other repo in flight, and is easy to forget to
+switch back). That is what the gate replaces, and it is not hypothetical: on
+2026-08-24 natal-chart#42 merged and deployed to production *during the
+conversation about how to review it before it shipped*.
 
 ## Adopting this for a new repo
 
@@ -242,7 +315,10 @@ production during the conversation about how to review it before it shipped.
    per-deploy hashes.
 3. Add the repo's visual-regression harness *before* the first customer-visible
    feature, not after the first complaint. Fixed fixture, frozen clock.
-4. Turn on the `uat` gate for the repo once #2687 ships.
+4. Turn on the `uat` gate for the repo — the two-part opt-in in §2. Resolve its
+   `uat_preview` against a **real** deployment before you trust it (§1): a
+   template that renders a dead link is worse than no gate, because the operator
+   learns to waive it.
 5. Point the repo's own `CLAUDE.md` at this file, and make sure its deployment
    section is **true** — natal-chart's said "GitHub Pages" for a week after
    production moved to Cloudflare (fixed in #47).

{code_coordinator-0.5.296 → code_coordinator-0.5.298}/install-agent.sh

@@ -109,14 +109,52 @@ echo "Installed: $("$VENV_DIR/bin/coord" version)"
 
 # The venv is now fully installed and verified working (coord version printed
 # above). Disarm the cleanup trap here: everything from this point on
-# (machine-name detection, the systemd unit, node shims, systemctl,
-# loginctl) is unrelated to venv creation, and a failure in any of it must
-# NOT delete a venv that already works — that would poison the retry with a
-# from-scratch pip re-install just to get back to the same later failure
-# (#2911 review).
+# (machine-name detection, the systemd unit, the coord CLI shim, node shims,
+# systemctl, loginctl) is unrelated to venv creation, and a failure in any of
+# it must NOT delete a venv that already works — that would poison the retry
+# with a from-scratch pip re-install just to get back to the same later
+# failure (#2911 review).
 trap - EXIT
 CREATED_VENV=0
 
+# --- coord CLI shim (#2936) --------------------------------------------------
+# Workers are spawned with THIS agent's own venv stripped from PATH (#402,
+# hardened by #2569's PIP_REQUIRE_VIRTUALENV after an 11h fleet outage — see
+# coord/agent.py's `_worker_subprocess_env`). That strip is correct and must
+# stay: a worker's bare `pip install -e .` must never land in the fleet's
+# live $VENV_DIR. But nothing else guarantees a worker's PATH resolves
+# `coord` itself — and when it doesn't, a smoke/test worker can run its
+# whole suite, pass, and be structurally unable to record the verdict via
+# `coord test <id> --passed`. The missing verdict then reads as a TEST
+# FAILURE and walks the model-escalation ladder for an infrastructure gap,
+# never a weak model (#2936; one instance cost an extra opus rerun of an
+# already-passing sonnet leg).
+#
+# $HOME/.local/bin is (a) already put on the coord-agent unit's PATH below
+# and (b) NOT stripped from a worker's PATH — #2569's strip matches
+# $VENV_DIR/bin by name/realpath only, never $HOME/.local/bin. A plain
+# symlink there closes the gap for every worker this agent spawns.
+#
+# MUST point at $VENV_DIR itself — the blue/green symlink `coord agent
+# update` repoints atomically on every release (docs/AGENT_OPERATIONS.md) —
+# NOT at a `readlink -f`-resolved `.blue`/`.green` path. Resolving it here
+# would freeze the shim on whichever side happens to be live at install
+# time and silently go stale on the very next blue/green swap.
+COORD_SHIM_DIR="$HOME/.local/bin"
+COORD_SHIM_TARGET="$VENV_DIR/bin/coord"
+COORD_SHIM_LINK="$COORD_SHIM_DIR/coord"
+mkdir -p "$COORD_SHIM_DIR"
+if [ -L "$COORD_SHIM_LINK" ] && [ "$(readlink "$COORD_SHIM_LINK")" = "$COORD_SHIM_TARGET" ]; then
+    : # already ours, and already pointed at the unresolved blue/green symlink
+elif [ -e "$COORD_SHIM_LINK" ] || [ -L "$COORD_SHIM_LINK" ]; then
+    echo "warning: $COORD_SHIM_LINK exists and is not the coord shim — left as-is"
+    echo "  A smoke/test worker on this machine cannot record its verdict via"
+    echo "  'coord test <id> --passed' unless 'coord' resolves on ITS PATH (#2936)."
+else
+    ln -s "$COORD_SHIM_TARGET" "$COORD_SHIM_LINK"
+    echo "Installed coord shim: $COORD_SHIM_LINK -> $COORD_SHIM_TARGET"
+fi
+
 # Detect machine name if not provided
 if [ -z "$MACHINE_NAME" ]; then
     MACHINE_NAME=$(hostname -s)
@@ -131,11 +169,21 @@ cat > "$UNIT_DIR/coord-agent.service" << UNIT
 [Unit]
 Description=Coordinator agent server (port $PORT)
 After=network-online.target
+# #2938: bound Restart=always below so a genuinely broken binary fails loud
+# (systemd 'failed'/start-limit-hit) instead of crash-looping silently
+# forever — see deploy/coord-agent.service's header for the full incident.
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
 ExecStart=$VENV_DIR/bin/coord agent --machine $MACHINE_NAME --port $PORT
-Restart=on-failure
+# #2938: was Restart=on-failure. POST /update stops this process cleanly so
+# it can come back on the swapped venv via an explicit self-restart
+# (coord/agent_app.py); if that explicit restart is ever lost, on-failure
+# never fires for a clean exit and the unit is gone for good, port 7433
+# refused, no remote-control channel left. Restart=always is the backstop.
+Restart=always
 RestartSec=5
 # #1671: include ~/.cargo/bin so a rustup-installed toolchain resolves to
 # both this agent process (the "rust" capability probe, coord/prereqs.py)