@miller-tech/uap 1.165.0 → 1.168.0

package/docs/guides/PARALLEL_AGENTS.md

@@ -0,0 +1,209 @@
+# Parallel Agents: Staying Collision-Free and Current
+
+How several agents work one codebase at once without overwriting each other, and
+without drifting away from the branch everything has to merge into.
+
+## The two failure modes
+
+Only one of these is what people mean by "merge conflict", and it is the less
+expensive one.
+
+| | Concurrent collision | Sequential drift |
+|---|---|---|
+| **What happens** | Two agents hold the same file at the same moment | Agent A lands a change; agent B's branch predates it and was never re-synced, so B edits a stale copy |
+| **Who notices** | Git, loudly, at merge time | Nobody. B's merge silently reverts A's work, or a model "resolves" the conflict by keeping its own version |
+| **Covered by** | Live-agent lock in `coordinate-file.sh` | Everything on this page |
+
+This repo currently has **151 worktrees; the worst is ~1242 commits behind
+`origin/master`; 24 hold unmerged commits and 15 have uncommitted files.** A
+worktree created during the audit that produced this system was born 1 commit
+behind, because creation read local `HEAD` and never fetched.
+
+Those numbers are the *starting* state, not a solved problem — the layers below
+stop it getting worse and make it visible. Reconciling the existing backlog is a
+`uap worktree hygiene` / `uap worktree prune` job.
+
+## The layers
+
+Each layer catches what the one before it cannot. All of them fail **open** — no
+remote, no git, or an unavailable coordination DB always allows the edit.
+
+### 1. Fresh at birth
+
+`uap worktree create <slug>` fetches and bases the new branch on
+`origin/<default>`, not on whatever the local checkout happens to have at HEAD.
+
+```bash
+uap worktree create my-feature              # branches from the fetched remote tip
+uap worktree create my-feature --from x     # explicit base still wins
+uap worktree create my-feature --no-fetch   # offline; accepts a possibly stale base
+```
+
+The default branch is resolved from `origin/HEAD`, then `origin/master`, then
+`origin/main`, then the current local branch, with a final literal `master`
+fallback if even that fails.
+
+> If your integration branch is neither `master` nor `main` and `origin/HEAD` is
+> unset (common on `--single-branch` clones), resolution falls through to *the
+> branch you are standing on*. Set it once — `git remote set-head origin -a` — or
+> pass `--from` explicitly.
+
+### 2. Fresh while you work
+
+```bash
+uap worktree sync              # run from INSIDE a worktree — syncs the cwd
+uap worktree sync --id 117     # a specific worktree, from anywhere
+uap worktree sync --all        # every worktree
+```
+
+With no flags it operates on the current directory and does not verify that it is
+a worktree — run it from the main checkout and it merges into whatever branch that
+checkout is on. Worktrees with uncommitted changes are skipped, not merged.
+
+Previously the only sync happened at `uap worktree finish` — the most expensive
+possible moment to discover a conflict. Sync early and often instead.
+
+### 3. Blocked from overwriting landed work
+
+Before any worktree edit, `coordinate-file.sh` checks whether **that specific
+file** changed on the integration branch since your branch's merge-base. If it
+did, the edit is blocked:
+
+```
+STALE FILE: src/cli/worktree.ts has changed on origin/master since your branch
+point (you are 12 commits behind). Editing this copy risks silently reverting
+work that already landed. Run 'uap worktree sync' first.
+```
+
+Scoped to the single file, so a stale branch touching untouched files keeps
+working — no blanket freeze. The check depends only on git, so it still runs when
+the coordination DB is missing. Its `git fetch` is throttled (default 600s) so it
+never turns every edit into a network round-trip.
+
+| Variable | Effect |
+|---|---|
+| `UAP_COORD_DRIFT=warn` | warn instead of block |
+| `UAP_COORD_DRIFT=off` | disable |
+| `UAP_COORD_FETCH_SECONDS` | fetch throttle (default 600) |
+
+An in-progress merge, rebase, cherry-pick or revert is exempt — the files you must
+edit to resolve a conflict are by definition the ones that moved upstream.
+
+### 4. Blocked from drifting too far
+
+The `branch-freshness` enforcer (`src/policies/enforcers/branch_freshness.py`)
+warns at 50 commits behind and blocks at 200 — the backstop for a branch whose
+whole model of the codebase has gone stale, where the eventual merge is a rewrite
+rather than a merge. Where layer 3 is file-precise, this is branch-coarse.
+
+```
+branch-freshness: this worktree is 1242 commits behind origin/master (limit 200).
+Edits here are being written against a codebase that has moved on, and the merge
+will be a rewrite rather than a merge. Run `uap worktree sync` first.
+```
+
+| Variable | Effect |
+|---|---|
+| `UAP_FRESHNESS_WARN` | advisory threshold (default 50) |
+| `UAP_FRESHNESS_BLOCK` | blocking threshold (default 200) |
+| `UAP_NO_FRESHNESS=1` | disable |
+
+Only worktree edits are in scope; the main checkout is governed by
+`worktree-required`. Fails open on a repo with no remote. It is part of the
+`team` policy scenario — `uap policy select` to enable it.
+
+The same 200-commit figure drives the `STALE — safe to prune` marker in
+`uap worktree hygiene`, which is a report, not a gate.
+
+The 200-commit figure also drives the `STALE — safe to prune` marker in
+`uap worktree hygiene`, which is a report, not a gate.
+
+### 5. Serialized landing
+
+Two independently-green PRs can still break each other on merge. That is not
+hypothetical: PR #577 landed a legitimate infra file while a stale test asserting
+its absence lived on master, turning CI red and blocking every version bump.
+
+```bash
+uap merge queue              # prints the plan only — never merges without --yes
+uap merge queue --yes        # land one at a time, re-syncing impacted PRs after each
+uap merge queue --yes --limit 3
+```
+
+Merging is irreversible and unattended, so **`--yes` is required**; the bare
+command is a plan. At most 10 PRs per run by default (`--limit`). `--force` lands
+PRs whose checks are not green — the CI safety this page argues for, deliberately
+switched off.
+
+Priority bands, highest first:
+
+| Band | Matches |
+|---|---|
+| 0 | labels containing `p0`, `critical`, `hotfix`, `security` |
+| 1 | labels containing `bug`, `fix`, `p1`; or branch `fix/…`, `hotfix/…` |
+| 2 | everything else |
+| 3 | branch `chore/…`, `docs/…` |
+
+Note the docs/chore band matches on **branch name**, not title — a PR titled
+`docs: …` on `feature/x` sorts into band 2. Ties break on smaller diff first, then
+least-recently-updated. After each merge, every PR that touches the same files
+**or the same ownership lane** is re-synced onto the new base before the next
+merge. PRs whose checks are still running are skipped rather than waited on, so a
+second run is often needed to drain the queue.
+
+### 6. Prevention: ownership lanes
+
+The layers above react to collisions. Lanes make them avoidable: partition the
+tree so concurrent agents can be pointed at different areas.
+
+`.uap-ownership.json` in the repo root — **tracked on purpose**, since a lane map
+that cannot be committed cannot be shared between agents, clones or CI. An
+untracked `.uap/ownership.json` overrides it for per-machine tweaks.
+
+```json
+{
+  "lanes": {
+    "cli":      ["src/cli/**", "src/bin/**"],
+    "delivery": ["src/delivery/**"],
+    "policy":   ["src/policies/**", "policies/**"]
+  }
+}
+```
+
+```bash
+uap coord ownership                          # show the lane map
+uap coord ownership src/cli/worktree.ts      # which lane, and is it held?
+```
+
+Unmapped paths belong to no lane and are never blocked, so a partial map degrades
+to previous behavior rather than freezing work. Lanes feed the merge queue, where
+they catch the semantic conflict that file-overlap misses entirely: two PRs
+editing *different* files in the same module.
+
+> Lanes are currently **advisory plus merge-queue input**. The scheduling
+> primitive that would hand agents disjoint lanes automatically
+> (`selectDisjoint`) is exported and tested but has no production caller yet — no
+> scheduler consumes it. Today you consult lanes; nothing assigns by them.
+
+### 7. Hygiene
+
+Silent accumulation is how parallel work gets lost.
+
+```bash
+uap worktree hygiene           # per-worktree drift, unmerged commits, dirty files
+uap worktree hygiene --brief   # one-line advisory (used by the session banner)
+uap worktree prune --older-than 30
+```
+
+The session banner surfaces the advisory automatically when anything needs
+attention, and stays silent otherwise.
+
+## Recommended loop
+
+```bash
+uap worktree create my-feature     # fresh base, guaranteed
+# ... work; the drift check blocks you if a file moves under you ...
+uap worktree sync                  # cheap, do it often
+uap worktree pr <id>
+uap merge queue                    # land serialized, re-sync the rest
+```

package/docs/guides/POLICIES.md

@@ -64,6 +64,7 @@ Each enforcer guards a specific station of the pipeline. The enforcers in
 | `worktree_required` | Edit/Write/MultiEdit must target a `.worktrees/` path |
 | `task_required` | A UAP task must be `in_progress` before mutating work |
 | `coord_overlap` | Checks for in-flight agent path reservations (parallel-agent overlap) |
+| `branch_freshness` | Worktree edits blocked once the branch drifts too far from the integration branch (warn 50, block 200) |
 | `delivery_enforcement` | Route substantive coding through `uap deliver` |
 
 ### Plan discipline

package/docs/guides/WORKTREE_WORKFLOW.md

@@ -43,7 +43,9 @@ uap worktree finish <id>       # 4. land: sync, push, merge the PR, then clean u
 1. **Create** — `create` allocates the next numeric ID from a registry,
    builds the branch name `feature/NNN-<slug>`, and runs
    `git worktree add -b <branch> .worktrees/NNN-<slug> <base>`. The base branch
-   defaults to your current branch (override with `--from`). The new worktree is
+   defaults to the freshly-fetched `origin/<default>` — not your current branch —
+   so a worktree is never born stale (override with `--from`, skip the fetch with
+   `--no-fetch`). See [Parallel Agents](PARALLEL_AGENTS.md). The new worktree is
    recorded in a SQLite registry at `.uap/worktree_registry.db` so concurrent
    `create` calls never race on the same ID.
 2. **Work** — `cd` into the worktree and make changes. Everything stays on the
@@ -104,7 +106,8 @@ Create a new worktree and feature branch for `<slug>`.
 
 | Flag | Description |
 |------|-------------|
-| `-f, --from <branch>` | Base branch (defaults to the current branch) |
+| `-f, --from <branch>` | Base branch (defaults to the fetched `origin/<default>`) |
+| `--no-fetch` | Skip the base fetch (offline; accepts a possibly stale base) |
 | `-d, --description <description>` | Optional worktree description |
 
 ```bash

package/docs/reference/CLI.md

@@ -250,8 +250,10 @@ worktree under `.worktrees/NNN-<slug>/`.
 
 | Subcommand | Key flags | Purpose |
 |------------|-----------|---------|
-| `create <slug>` | `-f, --from <branch>`, `-d, --description` | Create a new worktree for a feature |
+| `create <slug>` | `-f, --from <branch>`, `--no-fetch`, `-d, --description` | Create a worktree, based on the fetched `origin/<default>` |
 | `list` | — | List all worktrees |
+| `sync` | `-i, --id <id>`, `-a, --all` | Merge the integration branch into a worktree (mid-flight re-base) |
+| `hygiene` | `-b, --brief` | Report drift, unmerged work, and stale worktrees |
 | `pr <id>` | `--draft` | Create a PR from a worktree |
 | `finish <id>` | — | Sync, merge PR, and auto-cleanup the worktree |
 | `cleanup <id>` | — | Remove a worktree and delete its branch |
@@ -261,12 +263,33 @@ worktree under `.worktrees/NNN-<slug>/`.
 ```bash
 uap worktree ensure --strict
 uap worktree create add-user-auth
+uap worktree sync                     # re-base this worktree mid-flight
+uap worktree hygiene                  # drift + unmerged work across all worktrees
 uap worktree finish 042
 uap worktree prune --older-than 14 --dry-run
 ```
 
 ---
 
+## `merge`
+
+Serialized landing of concurrent agent PRs. See
+[Parallel Agents](../guides/PARALLEL_AGENTS.md).
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `queue` | `-y, --yes`, `-n, --dry-run`, `-l, --limit <n>` (10), `--force` | Land PRs one at a time, re-syncing every PR each merge invalidates |
+
+Without `--yes` the command only prints its plan — merging is irreversible and
+unattended. `--force` lands PRs whose checks are not green.
+
+```bash
+uap merge queue                 # plan only
+uap merge queue --yes --limit 3
+```
+
+---
+
 ## `sync`
 
 Sync configuration between platforms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.165.0",
+  "version": "1.168.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/src/policies/enforcers/branch_freshness.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""branch-freshness enforcer: a worktree branch must not drift far from the
+integration branch before it is allowed to keep accumulating edits.
+
+The file-level companion (coordinate-file.sh) blocks precisely: only when the
+FILE being edited moved on the integration branch. That is the right default —
+it never freezes work that cannot conflict. This enforcer is the coarse backstop
+for the other failure mode: a branch so far behind that its whole mental model of
+the codebase is wrong, where the eventual merge is a rewrite rather than a merge.
+
+Measured on this repo before the gate existed: 151 worktrees, the worst 1241
+commits behind origin/master, 23 holding unmerged commits. None of that drift was
+visible to any gate.
+
+Env:
+  UAP_NO_FRESHNESS=1        disable entirely
+  UAP_FRESHNESS_WARN=<n>    advisory threshold (default 50)
+  UAP_FRESHNESS_BLOCK=<n>   blocking threshold (default 200)
+"""
+from __future__ import annotations
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _common import emit, parse_cli, run, worktree_root  # noqa: E402
+
+EDIT_OPS = {"Edit", "Write", "MultiEdit", "edit", "write", "multiedit"}
+
+DEFAULT_WARN = 50
+DEFAULT_BLOCK = 200
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+def integration_ref(root: Path) -> str | None:
+    """origin/HEAD -> origin/master -> origin/main, or None when there is no remote."""
+    code, out, _ = run(["git", "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], cwd=root)
+    if code == 0 and out.strip():
+        return out.strip().replace("refs/remotes/", "")
+    for candidate in ("master", "main"):
+        code, _, _ = run(
+            ["git", "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{candidate}"],
+            cwd=root,
+        )
+        if code == 0:
+            return f"origin/{candidate}"
+    return None
+
+
+def commits_behind(root: Path, ref: str) -> int | None:
+    code, out, _ = run(["git", "rev-list", "--count", f"HEAD..{ref}"], cwd=root)
+    if code != 0:
+        return None
+    try:
+        return int(out.strip())
+    except ValueError:
+        return None
+
+
+def main() -> None:
+    op, args = parse_cli()
+    if op not in EDIT_OPS:
+        emit(True, "not a file-edit operation")
+
+    if os.environ.get("UAP_NO_FRESHNESS") == "1":
+        emit(True, "UAP_NO_FRESHNESS override set")
+
+    target = args.get("file_path") or args.get("path") or args.get("target") or ""
+    if not target:
+        emit(True, "no file path in args")
+
+    # Only worktree edits are in scope. Edits in the main checkout are governed by
+    # worktree-required, and non-repo paths are none of our business.
+    if ".worktrees/" not in str(Path(target)):
+        emit(True, "not a worktree edit")
+
+    root = worktree_root()
+    # A linked worktree has .git as a FILE, not a directory — both are valid.
+    git_marker = root / ".git"
+    if not git_marker.exists():
+        emit(True, "not a git working tree — fail open")
+
+    ref = integration_ref(root)
+    if ref is None:
+        emit(True, "no integration ref (no remote) — fail open")
+
+    behind = commits_behind(root, ref)
+    if behind is None:
+        emit(True, "drift not measurable — fail open")
+
+    warn_at = _int_env("UAP_FRESHNESS_WARN", DEFAULT_WARN)
+    block_at = _int_env("UAP_FRESHNESS_BLOCK", DEFAULT_BLOCK)
+    # A warn threshold above the block threshold would silently never fire.
+    if warn_at > block_at:
+        warn_at = block_at
+
+    if behind >= block_at:
+        emit(
+            False,
+            f"branch-freshness: this worktree is {behind} commits behind {ref} "
+            f"(limit {block_at}). Edits here are being written against a codebase that "
+            "has moved on, and the merge will be a rewrite rather than a merge. "
+            "Run `uap worktree sync` first. Override: UAP_NO_FRESHNESS=1.",
+            route="worktree-sync",
+            worktreeHint="uap worktree sync",
+            behind=behind,
+        )
+
+    if behind >= warn_at:
+        emit(
+            True,
+            f"branch-freshness: {behind} commits behind {ref} — consider "
+            "`uap worktree sync` before this grows into a conflict.",
+            behind=behind,
+        )
+
+    # Report `behind` on EVERY path, not just warn/block — callers and tests read
+    # it for observability, and a field that appears only on failure is a field
+    # nobody can build a dashboard on.
+    emit(True, f"fresh ({behind} behind {ref})", behind=behind)
+
+
+if __name__ == "__main__":
+    main()

package/src/policies/enforcers/coord_overlap.py

@@ -1,6 +1,29 @@
 #!/usr/bin/env python3
-"""coord-overlap enforcer: check for in-flight agent path reservations."""
+"""coord-overlap enforcer: don't spawn an agent onto paths a LIVE agent holds.
+
+Rewritten. The previous implementation was effectively decorative:
+
+  * it scraped candidate paths out of the raw prompt STRING by splitting on
+    whitespace and keeping tokens containing "/", so "see src/foo.ts for
+    context" registered as a reservation target while a structured `paths`
+    list was the only input that ever worked properly;
+  * it then iterated EVERY table in the coordination DB looking for a column
+    coincidentally named path/paths/file/scope and substring-matched against it,
+    so an unrelated table could veto a spawn;
+  * it never consulted agent liveness, so a reservation left behind by an agent
+    that died weeks ago blocked new work forever.
+
+This version queries the real `work_announcements` schema, joins
+`agent_registry` for heartbeat liveness (matching coordinate-file.sh's
+semantics), and only considers paths it can defend as actual targets.
+
+Env:
+  UAP_NO_COORD_OVERLAP=1      disable
+  UAP_COORD_LIVE_SECONDS=<n>  liveness window, shared with coordinate-file.sh (default 120)
+"""
 from __future__ import annotations
+import os
+import re
 import sqlite3
 import sys
 from pathlib import Path
@@ -8,73 +31,129 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 from _common import emit, parse_cli, repo_root  # noqa: E402
 
-AGENT_OPS = {"Agent", "spawn-agent", "subagent", "delegate"}
+AGENT_OPS = {"Agent", "spawn-agent", "subagent", "delegate", "task"}
+
+DEFAULT_LIVE_SECONDS = 120
+
+# A path-ish token: has a separator, a file extension or a known source dir, and
+# no spaces. Deliberately conservative — a false positive here BLOCKS work.
+PATH_TOKEN = re.compile(
+    r"(?:^|[\s'\"`(])((?:src|test|tests|lib|scripts|docs|policies|templates)/[\w./-]+"
+    r"|[\w./-]+\.(?:ts|tsx|js|jsx|py|sh|md|json|yaml|yml|sql))(?:[\s'\"`),:;]|$)"
+)
+
+
+def _live_seconds() -> int:
+    raw = os.environ.get("UAP_COORD_LIVE_SECONDS")
+    if not raw:
+        return DEFAULT_LIVE_SECONDS
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_LIVE_SECONDS
+    return value if value > 0 else DEFAULT_LIVE_SECONDS
+
+
+def candidate_paths(args: dict) -> list[str]:
+    """Paths this spawn is going to work on.
+
+    Prefers STRUCTURED input (`paths`, `scope`, `files`). Falls back to a
+    conservative regex over the prompt, which is a hint, not a contract.
+    """
+    for key in ("paths", "scope", "files"):
+        raw = args.get(key)
+        if isinstance(raw, list) and raw:
+            return [str(p).strip() for p in raw if str(p).strip()]
+        if isinstance(raw, str) and raw.strip():
+            return [p for p in re.split(r"[\s,]+", raw.strip()) if p]
+
+    prompt = args.get("prompt") or args.get("description") or ""
+    if not isinstance(prompt, str):
+        return []
+    return sorted({m.group(1) for m in PATH_TOKEN.finditer(prompt)})
 
 
-def overlapping_reservations(root: Path, paths: list[str]) -> list[str]:
+def live_holders(root: Path, paths: list[str]) -> list[tuple[str, str]]:
+    """(holder, resource) pairs for paths held by a LIVE agent other than us."""
     db = root / "agents" / "data" / "coordination" / "coordination.db"
     if not db.exists() or not paths:
         return []
+
+    me = os.environ.get("UAP_AGENT_ID") or ""
+    window = _live_seconds()
+    hits: list[tuple[str, str]] = []
+
     try:
         con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
-        # Best-effort: look for any reservations table with path-like column
-        cur = con.execute(
-            "SELECT name FROM sqlite_master WHERE type='table'"
-        )
-        tables = [r[0] for r in cur.fetchall()]
-        hits: list[str] = []
-        for t in tables:
-            try:
-                cols = [r[1] for r in con.execute(f"PRAGMA table_info({t})")]
-                path_col = next(
-                    (c for c in cols if c.lower() in ("path", "paths", "file", "scope")),
-                    None,
-                )
-                status_col = next(
-                    (c for c in cols if c.lower() in ("status", "state", "active")), None
-                )
-                if not path_col:
-                    continue
-                where = f" WHERE {status_col} IN ('active','in_progress',1)" if status_col else ""
-                rows = con.execute(f"SELECT {path_col} FROM {t}{where}").fetchall()
-                for (v,) in rows:
-                    if not v:
-                        continue
-                    for p in paths:
-                        if p and p in str(v):
-                            hits.append(f"{t}:{v}")
-            except sqlite3.Error:
-                continue
-        con.close()
-        return hits
     except sqlite3.Error:
         return []
 
+    try:
+        # Schema guard: if work_announcements is absent this DB predates the
+        # coordination system — fail open rather than guessing at other tables.
+        exists = con.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='work_announcements'"
+        ).fetchone()
+        if not exists:
+            return []
+
+        rows = con.execute(
+            """
+            SELECT wa.resource,
+                   COALESCE(wa.agent_name, wa.agent_id) AS holder,
+                   wa.agent_id
+            FROM work_announcements wa
+            LEFT JOIN agent_registry ar ON ar.id = wa.agent_id
+            WHERE wa.completed_at IS NULL
+              AND COALESCE(ar.status, 'active') = 'active'
+              AND (strftime('%s','now')
+                   - strftime('%s', COALESCE(ar.last_heartbeat, wa.announced_at))) < ?
+            """,
+            (window,),
+        ).fetchall()
+    except sqlite3.Error:
+        return []
+    finally:
+        con.close()
+
+    for resource, holder, agent_id in rows:
+        if not resource or (me and agent_id == me):
+            continue
+        res = str(resource)
+        for p in paths:
+            # Match on path containment in EITHER direction: reserving a
+            # directory covers files under it, and reserving a file conflicts
+            # with a spawn scoped to its directory.
+            if res == p or res.startswith(p.rstrip("/") + "/") or p.startswith(res.rstrip("/") + "/"):
+                hits.append((str(holder), res))
+                break
+
+    return hits
+
 
 def main() -> None:
     op, args = parse_cli()
     if op not in AGENT_OPS:
         emit(True, "not an agent-spawn op")
 
-    paths_raw = (
-        args.get("paths")
-        or args.get("scope")
-        or args.get("prompt", "")
-    )
-    if isinstance(paths_raw, list):
-        paths = [str(p) for p in paths_raw]
-    else:
-        paths = [p for p in str(paths_raw).split() if "/" in p]
-
-    hits = overlapping_reservations(repo_root(), paths)
+    if os.environ.get("UAP_NO_COORD_OVERLAP") == "1":
+        emit(True, "UAP_NO_COORD_OVERLAP override set")
+
+    paths = candidate_paths(args)
+    if not paths:
+        emit(True, "no resolvable target paths")
+
+    hits = live_holders(repo_root(), paths)
     if hits:
+        detail = ", ".join(f"{holder} holds {res}" for holder, res in hits[:5])
         emit(
             False,
-            f"coord-overlap: active reservations on: {', '.join(hits[:5])}. "
-            "Run `uap coordination check` before spawning.",
+            f"coord-overlap: {detail}. Spawning onto the same paths risks two agents "
+            "diverging on one file. Narrow the spawn's scope, wait for them to finish, "
+            "or check `uap coord board`. Override: UAP_NO_COORD_OVERLAP=1.",
         )
 
-    emit(True, "no overlapping reservations")
+    emit(True, f"no live holders for {len(paths)} path(s)")
 
 
 if __name__ == "__main__":