code-coordinator 0.5.46__py3-none-any.whl

coord/filelock.py

@@ -0,0 +1,168 @@
+"""``flock``-based advisory file lock, shared by every coord process (#1616).
+
+Extracted verbatim from :mod:`coord.drive`, where it lived while the drive
+was the only thing that took ``~/.coord/notify.lock``.  #1616 gave the daemon
+its own pipeline clock (:func:`coord.notify.run_drain`), which must serialise
+against a live ``coord drive``'s nudge — and "the same lock" is only a real
+claim if both sides use the same *class* on the same *path*, not two
+independent reimplementations that happen to agree on a filename today.
+
+``coord.drive`` re-exports ``FileLock``/``LockBusy`` from here, so every
+existing ``from coord.drive import FileLock`` keeps working and every existing
+lock keeps its identity.
+
+Why ``flock(2)`` and not a pidfile: ``flock`` is released by the kernel when
+the holding process dies, so a killed drive (or a ``coord-serve`` restart —
+exactly the deploy step #1616 requires) can never strand the pipeline behind
+a lock nobody holds.  The lock is advisory and per-open-file-description, so
+the two callers must both go through this class for it to mean anything.
+
+Cross-platform (#1156): POSIX uses ``fcntl.flock``; Windows has no ``fcntl``,
+so it goes through ``msvcrt.locking`` instead, behind the same non-blocking
+try/timeout/``LockBusy`` contract.  ``msvcrt.locking`` locks a byte range
+rather than the whole file, so both backends lock/unlock the same single byte
+at offset 0 — irrelevant to callers, who never read/write through the lock
+fd, only hold it.  Whichever backend is live, the process-death safety
+property above holds: both OS lock primitives are released when the holding
+process exits, even if it is killed without a chance to call
+:meth:`FileLock.release`.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ``fcntl``/``msvcrt`` are both deferred into the two functions below rather
+# than imported at module level: on POSIX, ``msvcrt`` genuinely doesn't
+# exist; on Windows, ``fcntl`` doesn't.  Deferring means this module (and
+# every top-level importer of it, notably `coord.drive`) loads cleanly on
+# either platform -- only the codepath actually exercised at lock time needs
+# its platform's module to be importable (#1156).
+
+
+class LockBusy(Exception):
+    """Someone else holds the lock."""
+
+
+def _lock_exclusive_nonblocking(fd: int) -> None:
+    """Try to take an exclusive, non-blocking lock on *fd*.
+
+    Raises ``OSError`` with an ``errno`` matching the POSIX "already locked"
+    codes (``EACCES``/``EAGAIN``) on contention, on both backends, so
+    :meth:`FileLock.acquire`'s retry/timeout loop below needs no
+    platform branch of its own.
+    """
+    if sys.platform == "win32":
+        import msvcrt  # stdlib, Windows-only -- deferred for platform safety  # noqa: PLC0415
+
+        try:
+            # ``msvcrt.locking`` locks relative to the file's current
+            # position; ``acquire`` always hands us a freshly-opened fd
+            # positioned at 0, so this locks the single byte at offset 0 —
+            # a stable, single-byte region every caller agrees on.
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError as exc:
+            if exc.errno is not None:
+                # ``msvcrt.locking`` already sets a real errno (contention
+                # maps to EACCES/EAGAIN via CPython's Windows error table,
+                # same as the POSIX path below) -- propagate it untouched
+                # rather than relabelling genuine, non-contention failures
+                # (e.g. disk I/O errors) as lock contention, which would
+                # make FileLock.acquire's retry loop spin forever instead
+                # of surfacing the real error.
+                raise
+            # Defensive fallback only: some failure without an errno
+            # attached at all -- treat conservatively as contention so the
+            # retry/timeout loop above still applies.
+            raise OSError(errno.EACCES, exc.strerror or str(exc)) from exc
+    else:
+        import fcntl  # stdlib, POSIX-only -- deferred for platform safety  # noqa: PLC0415
+
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+
+def _unlock(fd: int) -> None:
+    if sys.platform == "win32":
+        import msvcrt  # stdlib, Windows-only -- deferred for platform safety  # noqa: PLC0415
+
+        os.lseek(fd, 0, os.SEEK_SET)
+        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+    else:
+        import fcntl  # stdlib, POSIX-only -- deferred for platform safety  # noqa: PLC0415
+
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+@dataclass
+class FileLock:
+    """Advisory lock, the Python twin of the bash ``flock -n`` -- ``fcntl.flock``
+    on POSIX, ``msvcrt.locking`` on Windows (see module docstring)."""
+
+    path: Path
+    _fd: int | None = field(default=None, init=False, repr=False)
+
+    def acquire(self, timeout: float | None = 0.0) -> None:
+        """Take the lock.  ``timeout=0`` is non-blocking; ``None`` blocks forever."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self.path, os.O_CREAT | os.O_RDWR, 0o644)
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            try:
+                _lock_exclusive_nonblocking(fd)
+                self._fd = fd
+                return
+            except OSError as exc:
+                if exc.errno not in (errno.EACCES, errno.EAGAIN):
+                    os.close(fd)
+                    raise
+                if deadline is not None and time.monotonic() >= deadline:
+                    os.close(fd)
+                    raise LockBusy(str(self.path)) from exc
+                time.sleep(0.25)
+
+    def release(self) -> None:
+        if self._fd is None:
+            return
+        try:
+            _unlock(self._fd)
+        finally:
+            os.close(self._fd)
+            self._fd = None
+
+    def __enter__(self) -> FileLock:
+        self.acquire(timeout=None)
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.release()
+
+
+def notify_lock_path() -> Path:
+    """The one lock that serialises pipeline-advancing side effects.
+
+    A function rather than a module constant so tests (and a relocated
+    ``$HOME``) resolve it at call time — a constant captured at import would
+    freeze whatever ``Path.home()`` was when the module first loaded, which on
+    the daemon is process start.
+    """
+    return Path.home() / ".coord" / "notify.lock"
+
+
+def drive_queue_lock_path() -> Path:
+    """The lock that keeps ``coord drive-queue tick`` from stacking (#1754).
+
+    Deliberately NOT :func:`notify_lock_path`: a tick fetches the board and
+    may spend several seconds waiting for ``coord drive --tmux`` to confirm a
+    live session, and holding the pipeline's own lock for that would stall
+    ``coord notify``/``run_drain`` for no reason.  A tick advances nothing by
+    itself — it launches a drive, and *that* drive takes the notify lock when
+    it nudges.
+
+    Same call-time resolution rationale as above.
+    """
+    return Path.home() / ".coord" / "drive-queue.lock"

coord/fleet_config_health.py

@@ -0,0 +1,300 @@
+"""Fleet ``coordinator.yml`` provenance: is the live config still the one that
+was reviewed? (#1779)
+
+``coordinator.yml`` used to be a plain file at ``~/.coord/coordinator.yml`` on
+the daemon host, hand-copied from a tracked copy elsewhere — real, and
+undetectable, content drift. That copy has since been replaced by a
+**symlink** into the ``JDonaghy/coord-settings`` checkout
+(``~/src/coord-settings/coord/coordinator.yml`` by default), so the live file
+*is* the tracked file and content drift is structurally impossible. That
+closes one hole and opens three narrower ones, none visible from a running
+fleet:
+
+1. **The symlink gets replaced by a regular file.** ``coord init`` offers to
+   overwrite ``coordinator.yml`` (``coord/commands/setup.py``), and any
+   ``scp``, ``cp``, or editor that writes-and-renames breaks the link. The
+   fleet is then silently back to running an untracked file — this is the
+   highest-value check here, and the loudest finding.
+2. **The checkout is dirty.** A direct edit to the live path writes *through*
+   the symlink into the checkout's working tree — recoverable, but the
+   running config now has uncommitted changes nobody has reviewed.
+3. **The checkout is behind (or ahead of) ``origin``.** Someone pushed a
+   config change that was never pulled onto the daemon host (or committed
+   locally but never pushed), so the reviewed intent and the running fleet
+   disagree.
+
+A fourth state is *not* a problem: **no checkout at all.** The coord-settings
+checkout is deliberately absent from every machine except the daemon host and
+the operator's box (agents, thin clients, and every ephemeral Azure worker
+have no reason to carry it, and — see #1779's cross-repo constraint — a
+dispatched worker must never be able to edit the file governing its own
+concurrency limits and review gates). :func:`config_provenance` reports that
+as a neutral skip, never a warning.
+
+Mirrors :mod:`coord.graph_health`'s shape (``coord diagnose --graph``'s "is
+the artifact current?" check): a single read-only, best-effort probe function
+plus a renderer, wired into ``coord diagnose`` as another local-machine sweep
+alongside ``--graph``/``--orphan-worktrees``. No network access is required —
+sync-vs-``origin`` is judged against the existing remote-tracking ref, never a
+fresh ``git fetch``.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# The tracked config's path inside the coord-settings checkout.
+TRACKED_CONFIG_REL = Path("coord") / "coordinator.yml"
+
+
+def default_settings_dir() -> Path:
+    """``$COORD_SETTINGS_DIR``, defaulting to ``~/src/coord-settings``.
+
+    Computed fresh on every call (not a module-level constant) so a test can
+    override it via ``monkeypatch.setenv`` without also having to fight a
+    value baked in at import time.
+    """
+    env = os.environ.get("COORD_SETTINGS_DIR")
+    return Path(env).expanduser() if env else Path.home() / "src" / "coord-settings"
+
+
+def default_live_config_path() -> Path:
+    """Where the daemon's live ``coordinator.yml`` lives.
+
+    Mirrors the first two steps of :func:`coord.config.resolve_config_path`
+    (``$COORD_CONFIG``, then ``~/.coord/coordinator.yml``), computed fresh at
+    call time rather than reusing ``coord.config.USER_CONFIG_PATH`` — that is
+    a module-level constant fixed at import time against whatever ``$HOME``
+    was then, so it would not follow a test's environment override.
+
+    Deliberately excludes ``resolve_config_path``'s third step
+    (``./coordinator.yml`` in cwd): that is a repo-checkout dev convenience
+    that the running daemon never uses, and folding it in here would let a
+    stray dev ``coordinator.yml`` in whatever directory this check happens to
+    run from masquerade as the fleet's live config.
+    """
+    env = os.environ.get("COORD_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".coord" / "coordinator.yml"
+
+
+@dataclass
+class ConfigProvenance:
+    """Provenance of one machine's live ``coordinator.yml``."""
+
+    live_path: Path
+    checkout_dir: Path
+    # False on every machine with no coord-settings checkout — the expected,
+    # neutral state everywhere except the daemon host / operator box.
+    checkout_present: bool = False
+    live_exists: bool = False
+    is_symlink: bool = False
+    resolved_target: Path | None = None
+    # True only when the symlink resolves to THIS checkout's tracked
+    # coord/coordinator.yml — not just "somewhere inside the checkout".
+    in_checkout: bool = False
+    dirty: bool = False
+    dirty_files: list[str] = field(default_factory=list)
+    ahead: int = 0
+    behind: int = 0
+    upstream: str | None = None
+    sync_unknown_reason: str | None = None
+
+    @property
+    def skip(self) -> bool:
+        """No coord-settings checkout here — nothing to check, not a problem."""
+        return not self.checkout_present
+
+    @property
+    def regression(self) -> bool:
+        """The highest-value finding: the live config is no longer a symlink
+        into the reviewed checkout (#1779's central failure mode)."""
+        return self.checkout_present and not self.in_checkout
+
+    @property
+    def in_sync(self) -> bool:
+        return self.sync_unknown_reason is None and self.ahead == 0 and self.behind == 0
+
+    @property
+    def healthy(self) -> bool:
+        return (
+            self.checkout_present
+            and self.in_checkout
+            and not self.dirty
+            and self.sync_unknown_reason is None
+            and self.behind == 0
+        )
+
+
+def _git(checkout_dir: Path, *args: str) -> subprocess.CompletedProcess | None:
+    try:
+        return subprocess.run(
+            ["git", *args],
+            cwd=str(checkout_dir),
+            capture_output=True,
+            text=True,
+            timeout=10.0,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+
+
+def config_provenance(
+    *, live_path: Path | None = None, checkout_dir: Path | None = None
+) -> ConfigProvenance:
+    """Provenance of *live_path* (default: this machine's live
+    ``coordinator.yml``) against *checkout_dir* (default: the coord-settings
+    checkout).
+
+    Read-only and best-effort: git failures, a missing checkout, or a missing
+    live file all return a populated :class:`ConfigProvenance` rather than
+    raising. Never touches the network — sync-vs-origin is read from the
+    existing remote-tracking ref, never a fresh ``git fetch``.
+    """
+    live_path = live_path or default_live_config_path()
+    checkout_dir = checkout_dir or default_settings_dir()
+    prov = ConfigProvenance(live_path=live_path, checkout_dir=checkout_dir)
+
+    # #1779: the checkout's mere presence is the whole "is this machine in
+    # scope" signal — absent on every machine except the daemon host and the
+    # operator box. Anything past this point only runs where it's present.
+    if not (checkout_dir / ".git").exists():
+        return prov
+    prov.checkout_present = True
+
+    prov.is_symlink = live_path.is_symlink()
+    prov.live_exists = live_path.exists()  # follows the symlink; False if dangling/absent
+
+    tracked_path = checkout_dir / TRACKED_CONFIG_REL
+    if prov.is_symlink:
+        try:
+            prov.resolved_target = live_path.resolve()
+        except OSError:
+            prov.resolved_target = None
+        if prov.resolved_target is not None:
+            prov.in_checkout = prov.resolved_target == tracked_path.resolve()
+
+    if not prov.in_checkout:
+        # Regression case (not a symlink at all, or a symlink pointing
+        # somewhere else) — nothing downstream (dirty/sync) is meaningful
+        # against a file that isn't even the tracked one.
+        return prov
+
+    # ── Checkout clean? ──────────────────────────────────────────────────
+    status = _git(checkout_dir, "status", "--porcelain", "--", str(TRACKED_CONFIG_REL))
+    if status is not None and status.returncode == 0:
+        out = status.stdout.strip()
+        if out:
+            prov.dirty = True
+            prov.dirty_files = [line for line in out.splitlines() if line.strip()]
+
+    # ── In sync with origin? (no fetch — existing remote-tracking ref only) ─
+    upstream = _git(checkout_dir, "rev-parse", "--abbrev-ref", "@{upstream}")
+    if upstream is None or upstream.returncode != 0:
+        prov.sync_unknown_reason = (
+            "no upstream tracking ref configured for the coord-settings checkout"
+        )
+        return prov
+    prov.upstream = upstream.stdout.strip()
+
+    counts = _git(
+        checkout_dir, "rev-list", "--left-right", "--count", f"{prov.upstream}...HEAD"
+    )
+    if counts is None or counts.returncode != 0:
+        prov.sync_unknown_reason = f"could not compare HEAD to {prov.upstream}"
+        return prov
+    parts = counts.stdout.split()
+    if len(parts) != 2:
+        prov.sync_unknown_reason = (
+            f"unexpected `git rev-list` output comparing HEAD to {prov.upstream}"
+        )
+        return prov
+    try:
+        prov.behind, prov.ahead = int(parts[0]), int(parts[1])
+    except ValueError:
+        prov.sync_unknown_reason = (
+            f"unexpected `git rev-list` output comparing HEAD to {prov.upstream}"
+        )
+    return prov
+
+
+def format_provenance_lines(prov: ConfigProvenance) -> list[str]:
+    """Human-readable report lines for *prov* (used by ``coord diagnose
+    --config-provenance``). Each of the three failure modes gets its own,
+    distinctly-worded line — never collapsed into one generic "drift" line."""
+    lines: list[str] = []
+
+    if not prov.checkout_present:
+        lines.append(
+            f"· no coord-settings checkout at {prov.checkout_dir} — skipping "
+            "config provenance (expected on every machine except the daemon "
+            "host and the operator box)"
+        )
+        return lines
+
+    fix = f"ln -sf {prov.checkout_dir / TRACKED_CONFIG_REL} {prov.live_path}"
+    if not prov.is_symlink:
+        exists_note = "exists as a REGULAR FILE" if prov.live_exists else "does not exist"
+        lines.append(
+            f"✗ REGRESSION: {prov.live_path} is NOT a symlink into "
+            f"{prov.checkout_dir} — it {exists_note}. The fleet is running "
+            f"an untracked config again. Fix: {fix}"
+        )
+        return lines
+    if not prov.in_checkout:
+        lines.append(
+            f"✗ REGRESSION: {prov.live_path} is a symlink, but resolves to "
+            f"{prov.resolved_target} — not {prov.checkout_dir / TRACKED_CONFIG_REL}. "
+            f"Fix: {fix}"
+        )
+        return lines
+
+    lines.append(f"✓ {prov.live_path} → {prov.resolved_target} (symlinked into the checkout)")
+
+    if prov.dirty:
+        lines.append(
+            f"⚠ uncommitted changes to {TRACKED_CONFIG_REL} in {prov.checkout_dir} "
+            f"({len(prov.dirty_files)} line(s) of `git status --porcelain`) — the "
+            "running config has changes nobody has reviewed"
+        )
+    else:
+        lines.append(f"✓ {prov.checkout_dir}: checkout is clean (no uncommitted config changes)")
+
+    if prov.sync_unknown_reason:
+        lines.append(f"? sync vs origin unknown — {prov.sync_unknown_reason}")
+    elif prov.behind and prov.ahead:
+        lines.append(
+            f"⚠ diverged from {prov.upstream}: {prov.behind} commit(s) behind, "
+            f"{prov.ahead} ahead — reconcile on the daemon host"
+        )
+    elif prov.behind:
+        lines.append(
+            f"⚠ {prov.behind} commit(s) behind {prov.upstream} — reviewed config "
+            f"not yet deployed. Fix: git -C {prov.checkout_dir} pull"
+        )
+    elif prov.ahead:
+        lines.append(
+            f"⚠ {prov.ahead} commit(s) ahead of {prov.upstream} — local commit(s) "
+            "not yet pushed"
+        )
+    else:
+        lines.append(f"✓ in sync with {prov.upstream}")
+
+    return lines
+
+
+def summary_line(prov: ConfigProvenance) -> str:
+    """The machine-readable trailer ``coord diagnose --config-provenance``
+    prints, mirroring ``GRAPH_HEALTH:``/``DIAGNOSE_RESULT:``."""
+    if not prov.checkout_present:
+        return "CONFIG_PROVENANCE: checkout=absent skip=true"
+    return (
+        "CONFIG_PROVENANCE: checkout=present "
+        f"symlinked={'true' if prov.in_checkout else 'false'} "
+        f"dirty={'true' if prov.dirty else 'false'} "
+        f"behind={prov.behind} ahead={prov.ahead}"
+    )

coord/freshness.py

@@ -0,0 +1,206 @@
+"""Compare agent-reported local repo state against GitHub HEADs.
+
+Pure logic — no IO. Callers pass in the data they fetched from agents and
+GitHub; this module decides what's stale, current, dirty, or unknown.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from coord.config import Config
+from coord.deps import build_dep_graph, transitive_deps
+from coord.models import Proposal
+
+CURRENT = "current"
+STALE = "stale"
+DIRTY = "dirty"
+MISSING = "missing"
+UNKNOWN = "unknown"
+
+# #268: kind of cross-repo relationship a freshness entry came from.
+# `build` = transitive `depends_on` — required for the build.
+# `reference` = `reference_repos` — pulled for context only.
+BUILD = "build"
+REFERENCE = "reference"
+
+
+@dataclass
+class RepoFreshness:
+    repo_name: str
+    state: str  # one of the constants above
+    local_sha: str | None = None
+    remote_sha: str | None = None
+    branch: str | None = None
+    dirty: bool = False
+    error: str | None = None
+    # #268: where this entry came from in `coordinator.yml`.  Drives the
+    # briefing addendum so the worker knows whether to actually USE the
+    # pulled code or just READ it for context.  Defaults to `BUILD` for
+    # back-compat with existing call sites that don't supply a kind.
+    kind: str = BUILD
+
+    @property
+    def needs_pull(self) -> bool:
+        return self.state == STALE
+
+
+def compare(
+    repo_name: str,
+    local_info: dict | None,
+    remote_sha: str | None,
+    *,
+    kind: str = BUILD,
+) -> RepoFreshness:
+    """Classify one repo given its agent-reported local info and the remote SHA.
+
+    `local_info` is the dict returned by `AgentServer.list_repos()[repo_name]`
+    (or None if the agent had no entry). `remote_sha` is the full SHA on
+    GitHub's default branch (or None if lookup failed).
+
+    `kind` (#268) tags the result as either a build dep or a reference
+    repo so the briefing addendum can label each entry appropriately.
+    """
+    if local_info is None:
+        return RepoFreshness(repo_name=repo_name, state=MISSING, remote_sha=remote_sha,
+                             error="agent did not report this repo", kind=kind)
+
+    error = local_info.get("error")
+    if error:
+        return RepoFreshness(
+            repo_name=repo_name,
+            state=MISSING,
+            remote_sha=remote_sha,
+            error=error,
+            kind=kind,
+        )
+
+    local_sha = local_info.get("sha")
+    branch = local_info.get("branch")
+    dirty = bool(local_info.get("dirty"))
+
+    if remote_sha is None:
+        return RepoFreshness(
+            repo_name=repo_name,
+            state=UNKNOWN,
+            local_sha=local_sha,
+            branch=branch,
+            dirty=dirty,
+            error="remote head not available",
+            kind=kind,
+        )
+
+    if dirty:
+        return RepoFreshness(
+            repo_name=repo_name,
+            state=DIRTY,
+            local_sha=local_sha,
+            remote_sha=remote_sha,
+            branch=branch,
+            dirty=True,
+            kind=kind,
+        )
+
+    state = CURRENT if local_sha == remote_sha else STALE
+    return RepoFreshness(
+        repo_name=repo_name,
+        state=state,
+        local_sha=local_sha,
+        remote_sha=remote_sha,
+        branch=branch,
+        kind=kind,
+    )
+
+
+def relevant_repos(proposal: Proposal, config: Config) -> list[tuple[str, str]]:
+    """#268: compute the cross-repo set to freshen for *proposal*.
+
+    Returns ``[(repo_name, kind)]`` pairs covering:
+
+    - **Transitive `depends_on`** of the proposal's repo (tagged `BUILD`).
+      These walk the graph because A depending on B which depends on C
+      means a stale C poisons A's build.
+    - **Direct `reference_repos`** of the proposal's repo (tagged
+      `REFERENCE`).  Reference entries do NOT walk transitively — they
+      describe a flat "you may want to look at these" list, not a build
+      dependency.
+
+    Entries that appear both as a build dep and a reference are
+    de-duplicated and kept as `BUILD` (the stricter constraint wins).
+    Sorted by name for stable output.
+    """
+    graph = build_dep_graph(config.repos)
+    build_set = transitive_deps(proposal.repo_name, graph)
+
+    own = config.repo(proposal.repo_name)
+    ref_set: set[str] = set()
+    if own is not None:
+        # Drop refs that are already build deps so they aren't tagged twice.
+        ref_set = {r for r in own.reference_repos if r not in build_set}
+
+    pairs: list[tuple[str, str]] = []
+    for name in sorted(build_set):
+        pairs.append((name, BUILD))
+    for name in sorted(ref_set):
+        pairs.append((name, REFERENCE))
+    return pairs
+
+
+def dependency_freshness(
+    proposal: Proposal,
+    config: Config,
+    repo_heads: dict[str, dict],
+    github_heads: dict[str, str | None],
+) -> list[RepoFreshness]:
+    """Freshness for every cross-repo entry relevant to *proposal*.
+
+    Covers the transitive `depends_on` set (build deps) AND the direct
+    `reference_repos` set (context, #268).  ``repo_heads`` is what the
+    target agent returned from /repos; ``github_heads`` maps repo_name
+    to remote SHA (None when the lookup failed).
+    """
+    return [
+        compare(name, repo_heads.get(name), github_heads.get(name), kind=kind)
+        for name, kind in relevant_repos(proposal, config)
+    ]
+
+
+def stale_or_dirty(freshness: Iterable[RepoFreshness]) -> list[RepoFreshness]:
+    """Filter to entries that need user attention."""
+    return [f for f in freshness if f.state in (STALE, DIRTY, MISSING)]
+
+
+def format_briefing_addendum(freshness: list[RepoFreshness]) -> str:
+    """Markdown block to append to a worker's briefing when deps are stale.
+
+    #268: build deps are tagged with **(build dep)** so the worker knows
+    to actually pull + build against them; reference repos are tagged
+    **(reference)** so the worker knows it can read them for context but
+    shouldn't expect them to be part of the build.
+    """
+    needs = stale_or_dirty(freshness)
+    if not needs:
+        return ""
+    lines = [
+        "",
+        "### Stale dependencies",
+        "Before building, pull these repos.  Entries tagged "
+        "*(reference)* are not part of this repo's build — they're "
+        "siblings the worker may want to read for context.",
+    ]
+    for f in needs:
+        tag = " *(reference)*" if f.kind == REFERENCE else " *(build dep)*"
+        if f.state == STALE:
+            lines.append(
+                f"- `{f.repo_name}`{tag} (local {f.local_sha[:7] if f.local_sha else '?'} "
+                f"→ remote {f.remote_sha[:7] if f.remote_sha else '?'})"
+            )
+        elif f.state == DIRTY:
+            lines.append(
+                f"- `{f.repo_name}`{tag} is **dirty** on the agent — "
+                "uncommitted changes; do not pull, surface to operator"
+            )
+        else:
+            lines.append(f"- `{f.repo_name}`{tag}: {f.error or 'unknown state'}")
+    return "\n".join(lines)