code-coordinator 0.5.46__py3-none-any.whl

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

@@ -0,0 +1,36 @@
+# coord-web-dist-build — fires coord-web-dist-build.service (Type=oneshot) on
+# a cadence. See that unit's header, and deploy/coord-web-dist-build.sh's
+# header, for the full rationale.
+#
+# 1 minute — the #1543 acceptance target ("live... within a minute").  This
+# is safe at a tight cadence for two reasons a 15-minute cadence (like
+# coord-drive-queue.timer) doesn't need to justify:
+#
+#   1. Most fires are a no-op: the script compares origin/main's resolved SHA
+#      against the currently-published release and exits immediately if
+#      nothing merged since the last run — no npm invocation, no I/O beyond
+#      one `git fetch` + `rev-parse`.
+#   2. The script's own flock means a slow build (network hiccup during
+#      `npm ci`, etc.) can't stack with the next fire — a busy run is
+#      detected and the new invocation exits 0 immediately, exactly like
+#      coord-drive-queue's tick.
+#
+# A build that actually runs (something under coord/dashboard/webapp/**
+# merged) takes on the order of tens of seconds; that run and the next may
+# overlap the flock, in which case the next fire simply retries a minute
+# later — still within the acceptance target on average.
+#
+# Install: see deploy/coord-web-dist-build.sh's header, or
+# docs/PHONE_WEBAPP.md / docs/AGENT_OPERATIONS.md.
+
+[Unit]
+Description=Rebuild coord webapp dist from merged main every minute (#1543)
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=1min
+AccuracySec=10s
+Persistent=false
+
+[Install]
+WantedBy=timers.target

coord/deploy/coord-web.service

@@ -0,0 +1,125 @@
+# coord web — phone/web control-center dashboard (#700/#703).
+#
+# A systemd *user* unit (mirrors coord-serve). Serves the board dashboard +
+# the React/Vite phone PWA on port 7434. It is the THIRD always-on user
+# service, after coord-agent (every worker box) and coord-serve (the DB host).
+#
+# Install on the SAME always-on box that owns ~/.coord/coord.db (dellserver):
+# `coord web` reads the LOCAL board (state.load_board/build_board) — it does
+# NOT yet go through the coord serve daemon — so it MUST run where the DB
+# lives. Do not run it on a thin-client machine (it would render an empty
+# board). Routing it through the daemon so it can run anywhere — like the
+# CLI/TUI thin clients — is tracked in #749 (the BoardService facade).
+#
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/coord-web.service ~/.config/systemd/user/
+#   loginctl enable-linger "$USER"          # survive logout / reboot
+#   # First build the dist dir BEFORE starting the service — the assets
+#   # Mount/SPA catch-all routes are registered once at process start, so
+#   # they need something to point at (see coord-web-dist-build.sh):
+#   ~/.local/bin/coord-web-dist-build.sh
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now coord-web
+#   # ...and the timer that keeps the dist dir tracking merged main (#1543):
+#   cp deploy/coord-web-dist-build.service deploy/coord-web-dist-build.timer \
+#       ~/.config/systemd/user/
+#   systemctl --user enable --now coord-web-dist-build.timer
+#
+# Prereqs on the dashboard host (== the DB host):
+#   - ~/.coord-venv has code-coordinator installed via PyPI (`coord`
+#     itself — the daemon/CLI binary; unrelated to the webapp bundle below).
+#   - ~/.coord/coordinator.yml exists (canonical location; same resolution as
+#     the daemon: $COORD_CONFIG → ~/.coord/coordinator.yml → ./coordinator.yml).
+#   - ~/.coord/coord.db exists (this box owns it).
+#   - ~/coord-web-dist exists — a symlink that coord-web-dist-build.sh /
+#     .timer keep pointed at a fresh build of coord/dashboard/webapp from
+#     merged main (#1543; see deploy/coord-web-dist-build.sh's header for the
+#     full mechanism). This is intentionally decoupled from ~/.coord-venv: a
+#     merged webapp PR goes live within ~1 minute via that timer, with no
+#     `pip install`, no PyPI release, and no restart of coord-web,
+#     coord-agent, or coord-serve.
+#
+#     #1543 CORRECTION (2026-08-04): earlier revisions of this file said
+#     ~/.coord-venv's wheel bundles the built webapp (#758, landed
+#     2026-08-03) and that upgrading the venv was how a webapp change went
+#     live. That is still TRUE of the wheel, but is no longer how this unit
+#     serves the webapp — the --dist override below reads from
+#     ~/coord-web-dist instead, specifically so shipping a webapp change
+#     does not require upgrading the venv that coord-agent/coord-serve also
+#     run from. If ~/coord-web-dist is ever missing (fresh install before
+#     the first build, or the timer disabled), --dist falls back to the
+#     bundled coord/dashboard/webapp/dist inside the venv, same legacy
+#     fallback as before.
+#
+# Reach it from a phone on the tailnet: http://<dellserver-host>:7434
+# (same-origin API, so the phone needs no config; Add to Home Screen installs
+# the PWA).
+#
+# Restart over SSH needs the runtime-dir prefix (same #404 caveat as the agent):
+#   XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart coord-web
+#
+# Restarting coord-web (or its dist rebuilding) never touches ~/.coord-venv,
+# so it cannot disturb coord-serve (7435) or coord-agent (7433) — see
+# docs/PHONE_WEBAPP.md's "Going live automatically (#1543)" section for the
+# before/after version proof this was verified against.
+#
+# See docs/AGENT_OPERATIONS.md → "Web dashboard (coord web)".
+#
+# TimeoutStopSec / KillMode (#2095): coord-web serves `text/event-stream`
+# endpoints (coord/dashboard/server.py), and uvicorn's graceful shutdown
+# waits for every open connection to drain. An SSE stream does not close on
+# its own — a browser tab or the phone PWA left open holds the stop open
+# INDEFINITELY, past any timeout a restart caller is willing to wait. During
+# the 2026-08-10 0.5.15 -> 0.5.26 roll that left the unit `deactivating` for
+# the run's entire wait, which the caller (coord/agent_app.py's
+# `_restart_sibling_unit`, at the time a blocking `systemctl restart` under
+# a hard 15s subprocess timeout) turned into an abandoned mid-stop unit:
+# not restarted — STOPPED — while still being reported a success one layer
+# up. Bounding the stop HERE, at the unit, means systemd escalates to
+# SIGKILL on its own after TimeoutStopSec regardless of what any caller's
+# own timeout is doing, instead of leaving an open-ended wait for a client
+# that may never disconnect. KillMode=process (rather than the default
+# control-group) targets only the main uvicorn process — sidestepping the
+# same recovery failure the incident hit by hand afterwards
+# (`systemctl --user kill -s SIGKILL coord-web` refused with "Failed to send
+# signal SIGKILL to auxiliary processes: Invalid argument") — and follows
+# the KillMode precedent already established on coord-drive-queue.service
+# (#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).
+
+[Unit]
+Description=coord web — phone/web control-center dashboard (#700)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=%h/.coord-venv/bin/coord web --config %h/.coord/coordinator.yml --host 0.0.0.0 --port 7434 --dist %h/coord-web-dist
+# #2095: the `--port` above is the ONLY declaration of this dashboard's port.
+# `coord/agent_app.py`'s `_probe_liveness` — the post-restart liveness check
+# `_restart_sibling_unit` runs (from inside the coord-agent process) before
+# trusting coord-web's restart — reads it back off this very line via
+# `systemctl --user show coord-web --property=ExecStart`, so changing the port
+# here needs no matching edit anywhere else and cannot desync the probe from
+# the listener. An earlier revision declared `Environment=COORD_WEB_PORT=7434`
+# here instead; that could never work, because systemd does not share
+# `Environment=` across units and the process that reads it runs under
+# coord-agent.service. Do not re-add it (here or there): a second declaration
+# that has to agree with this one by hand is the failure mode, not the fix.
+# Belt-and-suspenders for #1229: systemd user units have no controlling TTY so
+# TERM is absent from the process environment.  The terminal bridge code now
+# calls env.setdefault("TERM", "xterm-256color") before spawning tmux, but
+# 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
+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.
+TimeoutStopSec=10
+KillMode=process
+
+[Install]
+WantedBy=default.target

coord/deploy_manifest.py

@@ -0,0 +1,80 @@
+"""Per-role systemd unit manifest — which units a host runs (#2098).
+
+`deploy/` ships every packaged unit and `coord release verify` /
+`deploy_units.install_units` both deliberately decline to guess which of
+them a given host should run — *"a release does not decide which services
+a host runs"* (`coord/deploy_units.py`'s module docstring). That refusal is
+correct, but it left the actual decision nowhere: not in a file, not in
+code, only as `~/.config/systemd/user/timers.target.wants/` symlinks on
+dellserver. Losing dellserver would have meant rebuilding that list from
+memory.
+
+This module is that list, in code instead of folklore. It mirrors
+`docs/AGENT_OPERATIONS.md`'s "Daemon-host unit inventory" table — keep both
+in sync; `tests/test_deploy_manifest.py` cross-checks the doc table against
+:data:`ROLE_UNITS` so the two cannot quietly drift apart the way the
+propagate-timer enable step did.
+
+Each name is the unit that should actually be `systemctl --user enable
+--now`'d. For a timer-backed lane that is always the `.timer`, never the
+oneshot `.service` it fires — enabling the oneshot does nothing; only the
+timer's own `[Install]` section wires anything into
+`timers.target.wants/`. `coord-agent`, `coord-serve` and `coord-web` have
+no timer and are listed as `.service` because they ARE the long-running
+unit.
+
+Consumed by :mod:`coord.health.checks.unit_enablement` (#2098), which
+reads :func:`all_manifest_units` to decide which *installed* units it is
+entitled to expect `enabled`. It does not use this module to guess which
+role a given host plays — same "don't infer topology" boundary as
+`unit_drift` and `deploy_units`: an installed-but-unlisted unit is not this
+module's business, and an uninstalled manifest unit is not a fault (most
+hosts are workers, and are not supposed to run the daemon lanes).
+"""
+
+from __future__ import annotations
+
+ROLE_WORKER = "worker"
+ROLE_DAEMON = "daemon"
+
+#: role -> unit names that role's host should have running, in the order
+#: they appear in docs/AGENT_OPERATIONS.md's "Daemon-host unit inventory"
+#: table. `coord-agent.service` is listed under both roles because every
+#: machine — daemon host included — runs it.
+ROLE_UNITS: dict[str, tuple[str, ...]] = {
+    ROLE_WORKER: (
+        "coord-agent.service",
+    ),
+    ROLE_DAEMON: (
+        "coord-agent.service",
+        "coord-serve.service",
+        "coord-web.service",
+        "coord-web-dist-build.timer",
+        "coord-notify.timer",
+        "coord-drive-queue.timer",
+        "coord-release-propagate.timer",
+        "coord-db-backup.timer",
+    ),
+}
+
+
+def units_for_role(role: str) -> tuple[str, ...]:
+    """The units *role* should run, or `()` for an unknown role."""
+    return ROLE_UNITS.get(role, ())
+
+
+def all_manifest_units() -> tuple[str, ...]:
+    """Every unit named by any role, deduped and sorted.
+
+    What :mod:`coord.health.checks.unit_enablement` iterates: it does not
+    need to know *which* role this host plays, only whether an installed
+    unit is one this manifest ever expects to be enabled somewhere.
+    """
+    seen: set[str] = set()
+    out: list[str] = []
+    for units in ROLE_UNITS.values():
+        for name in units:
+            if name not in seen:
+                seen.add(name)
+                out.append(name)
+    return tuple(sorted(out))

coord/deploy_units.py

@@ -0,0 +1,384 @@
+"""The `deploy/**` lane's missing *deploy step* (#1831, wired up by #1835).
+
+#1831 gave `deploy/**` a **detector** — ``coord.health.checks.unit_drift``
+diffs each host's installed unit under ``~/.config/systemd/user/`` against
+the units packaged in the wheel (``coord/deploy/``, #1927) — and a printed
+remedy that a human then runs by hand. That was the right first half. It is
+not a deploy lane: cutting v0.4.106 still meant installing five files into
+``~/.config/systemd/user/`` and ``~/.local/bin/`` on dellserver, plus a
+``daemon-reload``, plus retiring a machine-local drop-in.
+
+#1835 cannot claim "the fleet reaches that version" while a whole lane needs
+a human with ``cp`` and ``systemctl``, and this is not a corner case: #1543's
+actual mechanism was three unit files and a shell script, while its Python
+change was a single ``--dist`` flag. A release that propagated only the
+Python lane would have shipped the flag and none of the behaviour.
+
+So this module applies what ``unit_drift`` reports.
+
+THREE SAFETY PROPERTIES, ALL DELIBERATE
+---------------------------------------
+1. **Refresh only units this host already runs.** Which services a host runs
+   is a *topology* decision (``coordinator.yml``), not a release decision. A
+   packaged unit with no installed counterpart is reported as ``new`` and
+   left alone — installing ``coord-web.service`` onto a machine that never
+   wanted a web server, because a release happened to contain the file, is a
+   far worse failure than a human running one ``cp``. The report names them
+   so the human action is visible rather than implicit.
+
+2. **Templates are rendered, never copied verbatim (#1928).** Several units
+   carry ``<MACHINE_NAME>`` / ``<PORT>`` placeholders. Copying one verbatim
+   installs the placeholder as literal text and the unit then refuses to
+   start — the exact hazard #1928 documented. Placeholders with no known
+   substitution abort *that unit* (reported, not written); they never get
+   guessed.
+
+3. **The previous content is kept.** Every overwrite writes
+   ``<name>.pre-<version>.bak`` next to the unit first, so the rollback for
+   this lane is a file copy the operator can see and `diff`, not a re-run of
+   an install script whose inputs have moved on.
+
+The write itself is atomic per file (temp file + ``os.replace``), so a unit
+is never observed half-written by a ``daemon-reload`` racing this.
+
+Pure-ish by construction: every path is a parameter, so the whole thing is
+testable against ``tmp_path`` with no systemd, no fleet, and no root.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+# Reuse #1831's own definitions rather than re-spelling them. Two
+# definitions of "which files are units" or "what a placeholder looks like"
+# would let the detector and the deployer disagree — and a deployer that
+# disagrees with its detector reports clean while shipping nothing.
+from coord.health.checks.unit_drift import (
+    _KNOWN_PLACEHOLDER_VALUES,
+    _PLACEHOLDER_RE,
+    _SYSTEMD_USER_DIR,
+    _UNIT_GLOBS,
+    packaged_unit_dir,
+)
+
+#: Placeholder -> how to fill it, given the host facts we actually know.
+#: ``unit_drift`` renders these as *shell* text for a copy-pasteable remedy
+#: (``$(hostname -s)``); here they must be real values, so the mapping is
+#: from placeholder name to the keyword of :func:`install_units`.
+_PLACEHOLDER_SOURCES = {
+    "MACHINE_NAME": "machine_name",
+    "PORT": "port",
+}
+
+#: Outcome of one unit's deploy step.
+ACTION_UNCHANGED = "unchanged"
+ACTION_UPDATED = "updated"
+ACTION_NEW = "new"
+ACTION_SKIPPED = "skipped"
+ACTION_FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class UnitOutcome:
+    name: str
+    action: str
+    detail: str = ""
+    backup: str | None = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class InstallReport:
+    """What the deploy step did, per unit."""
+
+    units: list[UnitOutcome] = field(default_factory=list)
+    reference: str | None = None
+    error: str | None = None
+    #: True once at least one unit's bytes changed — the only case that
+    #: needs a ``systemctl --user daemon-reload``.
+    @property
+    def changed(self) -> bool:
+        return any(u.action == ACTION_UPDATED for u in self.units)
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and not any(
+            u.action == ACTION_FAILED for u in self.units
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "reference": self.reference,
+            "error": self.error,
+            "changed": self.changed,
+            "ok": self.ok,
+            "units": [u.to_dict() for u in self.units],
+        }
+
+    def summary(self) -> str:
+        counts: dict[str, int] = {}
+        for unit in self.units:
+            counts[unit.action] = counts.get(unit.action, 0) + 1
+        if self.error:
+            return f"units: {self.error}"
+        if not counts:
+            return "units: nothing packaged to install"
+        return "units: " + ", ".join(
+            f"{count} {action}" for action, count in sorted(counts.items())
+        )
+
+
+def systemd_user_dir(home: Path | None = None) -> Path:
+    base = home or Path.home()
+    return Path(str(_SYSTEMD_USER_DIR).replace("~", str(base), 1))
+
+
+def _packaged_units(reference_dir: Path) -> list[Path]:
+    seen: set[str] = set()
+    out: list[Path] = []
+    for pattern in _UNIT_GLOBS:
+        for path in sorted(reference_dir.glob(pattern)):
+            if path.name in seen:
+                continue
+            seen.add(path.name)
+            out.append(path)
+    return sorted(out, key=lambda p: p.name)
+
+
+def render_unit(text: str, *, machine_name: str | None, port: int | str | None) -> tuple[str | None, str]:
+    """Fill ``<PLACEHOLDER>`` tokens. Returns ``(rendered_or_None, note)``.
+
+    ``None`` means "this unit is a template with a placeholder we cannot
+    fill" — the caller must skip it and say so. Guessing a value here is how
+    a unit lands with ``<MACHINE_NAME>`` as literal text and then refuses to
+    start (#1928).
+    """
+    names = sorted(set(_PLACEHOLDER_RE.findall(text)))
+    if not names:
+        return text, ""
+    values = {"machine_name": machine_name, "port": port}
+    filled: dict[str, str] = {}
+    for name in names:
+        key = _PLACEHOLDER_SOURCES.get(name)
+        value = values.get(key) if key else None
+        if value in (None, ""):
+            fallback = _KNOWN_PLACEHOLDER_VALUES.get(name)
+            return None, (
+                f"template placeholder <{name}> has no value for this host"
+                + (f" (unit_drift's documented default is {fallback})" if fallback else "")
+                + " — refusing to install it verbatim (#1928); install this "
+                "unit by hand"
+            )
+        filled[name] = str(value)
+
+    def _sub(match: re.Match[str]) -> str:
+        return filled[match.group(1)]
+
+    return _PLACEHOLDER_RE.sub(_sub, text), f"rendered {', '.join(names)}"
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    tmp = path.with_name(path.name + ".coord-tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def install_units(
+    *,
+    target_dir: Path | None = None,
+    reference_dir: Path | None = None,
+    machine_name: str | None = None,
+    port: int | str | None = None,
+    version: str | None = None,
+    dry_run: bool = False,
+    home: Path | None = None,
+) -> InstallReport:
+    """Refresh this host's installed systemd user units from the wheel.
+
+    *reference_dir* defaults to :func:`~coord.health.checks.unit_drift.
+    packaged_unit_dir` — ``coord/deploy/`` inside the *installed*
+    distribution, i.e. the released artifact, which cannot drift with the
+    host's checkout (#1927). Only units already present in *target_dir* are
+    rewritten; see the module docstring for why.
+    """
+    report = InstallReport()
+    ref = reference_dir or packaged_unit_dir()
+    if ref is None:
+        report.error = (
+            "this install ships no coord/deploy/ — it predates #1927, so "
+            "there is no released unit set to deploy from. Upgrade the "
+            "Python lane first."
+        )
+        return report
+    report.reference = str(ref)
+
+    dest_dir = target_dir or systemd_user_dir(home)
+    suffix = f".pre-{version}" if version else ".pre-update"
+
+    for source in _packaged_units(ref):
+        installed = dest_dir / source.name
+        if not installed.exists():
+            report.units.append(
+                UnitOutcome(
+                    source.name,
+                    ACTION_NEW,
+                    "packaged but not installed on this host — a release does "
+                    "not decide which services a host runs; install and enable "
+                    "it by hand if this host should have it",
+                )
+            )
+            continue
+
+        try:
+            source_text = source.read_text(encoding="utf-8")
+        except OSError as exc:
+            report.units.append(
+                UnitOutcome(source.name, ACTION_FAILED, f"unreadable reference: {exc}")
+            )
+            continue
+
+        rendered, note = render_unit(
+            source_text, machine_name=machine_name, port=port
+        )
+        if rendered is None:
+            report.units.append(UnitOutcome(source.name, ACTION_SKIPPED, note))
+            continue
+
+        try:
+            current = installed.read_text(encoding="utf-8")
+        except OSError as exc:
+            report.units.append(
+                UnitOutcome(source.name, ACTION_FAILED, f"unreadable installed unit: {exc}")
+            )
+            continue
+
+        if current == rendered:
+            report.units.append(UnitOutcome(source.name, ACTION_UNCHANGED, note))
+            continue
+
+        if dry_run:
+            report.units.append(
+                UnitOutcome(source.name, ACTION_UPDATED, f"would rewrite ({note})".strip())
+            )
+            continue
+
+        backup = installed.with_name(installed.name + suffix + ".bak")
+        try:
+            shutil.copy2(installed, backup)
+            _atomic_write(installed, rendered)
+        except OSError as exc:
+            report.units.append(
+                UnitOutcome(source.name, ACTION_FAILED, f"write failed: {exc}")
+            )
+            continue
+        report.units.append(
+            UnitOutcome(
+                source.name,
+                ACTION_UPDATED,
+                note or "content refreshed from the packaged release",
+                backup=str(backup),
+            )
+        )
+
+    return report
+
+
+def daemon_reload(*, runner=None, timeout: float = 30.0) -> tuple[bool, str]:
+    """``systemctl --user daemon-reload``. Returns ``(ok, output)``.
+
+    Split out and injectable so :func:`install_units` stays a pure filesystem
+    operation testable without systemd — and so a host with no systemd (a
+    macOS worker) degrades to a reported skip rather than a traceback.
+    """
+    import subprocess  # noqa: PLC0415
+
+    run = runner or subprocess.run
+    try:
+        proc = run(
+            ["systemctl", "--user", "daemon-reload"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError:
+        return False, "systemctl not found (no systemd on this host)"
+    except Exception as exc:  # noqa: BLE001 — a reload must never crash a roll
+        return False, f"{type(exc).__name__}: {exc}"
+    ok = getattr(proc, "returncode", 1) == 0
+    out = (getattr(proc, "stderr", "") or getattr(proc, "stdout", "") or "").strip()
+    return ok, out or ("daemon-reload ok" if ok else "daemon-reload failed")
+
+
+#: Which of :func:`install_units`'s outcomes mean "this unit is actually
+#: present on this host right now" — the only units eligible to be enabled
+#: below. ``ACTION_NEW`` (never installed here — safety property 1: a
+#: release does not decide which services a host runs) and
+#: ``ACTION_SKIPPED``/``ACTION_FAILED`` (this write did not land) are
+#: deliberately excluded.
+_PRESENT_ACTIONS = frozenset({ACTION_UNCHANGED, ACTION_UPDATED})
+
+
+def enable_timers(
+    report: InstallReport, *, runner=None, timeout: float = 30.0,
+) -> dict[str, tuple[bool, str]]:
+    """``systemctl --user enable --now <unit>`` for every installed timer in
+    *report* (#2082).
+
+    #2082: ``coord-release-propagate.timer`` reached three hosts'
+    ``~/.config/systemd/user/`` and sat there — :func:`install_units`
+    refreshed its *content* on every release, but nothing ever ran
+    ``enable --now`` on it, and nothing noticed because a disabled timer's
+    file looks byte-for-byte identical to an active one's (see
+    :mod:`coord.health.checks.timer_active`, the detector for exactly this).
+
+    A ``.timer`` unit is different from a ``.service`` here: which
+    *services* a host runs is a one-time topology choice
+    (``install-agent.sh``, or a human at machine setup — see this module's
+    docstring), never something a routine refresh should override. A timer
+    that exists at all has no reason to exist disabled — its whole job is to
+    fire on a schedule with nobody watching, so "installed but not enabled"
+    is invisible from the outside and would otherwise self-heal never.
+    Applying this on every deploy makes enablement an assertion this lane
+    re-checks every time it runs, the same way :func:`install_units`
+    re-asserts content every time it runs.
+
+    Both ``enable`` and ``--now`` are idempotent — an already-enabled,
+    already-active timer is untouched — so calling this on every deploy is a
+    correctness check, not a state change, in the common case. Scoped to
+    units *this* report found actually installed (:data:`_PRESENT_ACTIONS`),
+    matching the deploy step's own "only touch what this host already runs"
+    rule.
+    """
+    import subprocess  # noqa: PLC0415
+
+    run = runner or subprocess.run
+    out: dict[str, tuple[bool, str]] = {}
+    timers = sorted(
+        u.name
+        for u in report.units
+        if u.name.endswith(".timer") and u.action in _PRESENT_ACTIONS
+    )
+    for name in timers:
+        try:
+            proc = run(
+                ["systemctl", "--user", "enable", "--now", name],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except FileNotFoundError:
+            out[name] = (False, "systemctl not found (no systemd on this host)")
+            continue
+        except Exception as exc:  # noqa: BLE001 — must never crash a deploy
+            out[name] = (False, f"{type(exc).__name__}: {exc}")
+            continue
+        ok = getattr(proc, "returncode", 1) == 0
+        detail = (getattr(proc, "stderr", "") or getattr(proc, "stdout", "") or "").strip()
+        out[name] = (ok, detail or ("enabled" if ok else "enable failed"))
+    return out