code-coordinator 0.5.154__tar.gz → 0.5.158__tar.gz

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/CLAUDE.md

@@ -135,30 +135,14 @@ computes the routing without actually building or testing anything.
 ## Working on `tui/` — the `quadraui` pin
 
 **`coord-tui` pins `quadraui` to a git rev in `tui/Cargo.toml`**
-(`quadraui = { git = "https://github.com/JDonaghy/quadraui", rev = "<sha>" }`, #1973). This
-replaced the old relative-path dependency (`../../quadraui/quadraui`), which built against
-whatever branch happened to be checked out in `~/src/quadraui` — a quadraui merge could break
-coord-tui's build/merge with **zero coord-tui commits and no warning** (it already happened
-once). `cargo build`/`cargo test` from `tui/` now fetch quadraui straight from GitHub at the
-pinned rev and never touch `~/src/quadraui`, so the local checkout's branch is irrelevant.
-
-- **Bumping the pin** (deliberate, reviewable, its own coord-tui commit): pick the target
-  quadraui rev — normally the tip of `origin/develop` (quadraui's default/integration branch,
-  per quadraui's CLAUDE.md) — edit the `rev = "..."` in `tui/Cargo.toml`, then run
-  `cargo build && cargo test` from `tui/` and confirm EXIT=0 before committing.
-  `cargo update -p quadraui` alone will **not** move a `rev`-pinned git dependency; the
-  `Cargo.toml` edit is the actual bump.
-- **Co-developing against an unmerged quadraui branch/PR:** if a `tui/` task consumes a
-  not-yet-merged quadraui feature, the briefing **must** name the quadraui PR/branch. The
-  worker builds against a local `~/src/quadraui` checkout **without editing
-  `tui/Cargo.toml`**, via cargo's local-paths override:
-  `cp tui/cargo-config-local-quadraui.toml.example tui/.cargo/config.toml` (git-ignored — see
-  the example file's header) after checking out the target branch in `~/src/quadraui`. Delete
-  `tui/.cargo/config.toml` (or don't create it) to build against the pinned rev again — this
-  is the default and what CI/other workers use. **Verify build EXIT=0 from `tui/` both with
-  the override active (proves the feature works) and, before finishing, confirm the committed
-  `tui/Cargo.toml` still points at the pinned rev** (the override file itself is never
-  committed).
+(`quadraui = { git = "https://github.com/JDonaghy/quadraui", rev = "<sha>" }`, #1973) —
+never edit that `rev` as a shortcut for co-development, and never build `tui/` against
+whatever happens to be checked out in `~/src/quadraui`; a quadraui merge broke coord-tui's
+build with zero coord-tui commits and no warning once already, which is exactly what the pin
+prevents. Bumping the pin deliberately, and building against an unmerged quadraui branch/PR
+without touching the pin, are both procedures — see the `tui-quadraui-workflow` skill
+(`coord/skills/tui-quadraui-workflow/SKILL.md`) for the steps; install it with `coord
+install-skills` if it isn't already on this machine.
 
 ## Key Design Decisions
 

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/PKG-INFO

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

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

@@ -344,7 +344,14 @@ coord/providers/base.py
 coord/providers/claude.py
 coord/providers/claude_pty.py
 coord/providers/opencode.py
+coord/skills/coord-dispatch-verbs/SKILL.md
+coord/skills/drive-queue-preflight/SKILL.md
+coord/skills/fleet-restart-safety/SKILL.md
+coord/skills/merge-stuck-triage/SKILL.md
+coord/skills/pipeline-limbo-triage/SKILL.md
 coord/skills/portal-followup/SKILL.md
+coord/skills/review-verdict-recovery/SKILL.md
+coord/skills/tui-quadraui-workflow/SKILL.md
 coord/skills/update-issue/SKILL.md
 deploy/coord-agent.service
 deploy/coord-db-backup.service
@@ -442,6 +449,7 @@ tests/test_agent_push_failure.py
 tests/test_agent_reap.py
 tests/test_agent_repos_and_pull.py
 tests/test_agent_restart_services_endpoint.py
+tests/test_agent_skills_self_heal.py
 tests/test_agent_startup_diagnostics.py
 tests/test_agent_update.py
 tests/test_agent_update_bluegreen.py
@@ -795,6 +803,7 @@ tests/acceptance/ms-51/mocks/home-active.html
 tests/acceptance/ms-65/board_tabs_2282.rs
 tests/acceptance/ms-65/board_tabs_close_2283.rs
 tests/acceptance/ms-65/contract.md
+tests/acceptance/ms-65/detail_substate_2285.rs
 tests/acceptance/ms-65/manifest.yml
 tests/acceptance/ms-65/pipeline_tabs_2284.rs
 tests/acceptance/ms-65/mocks/board-baseline-no-tabs.screen

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/code_coordinator.egg-info/scm_file_list.json

@@ -307,7 +307,14 @@
     "coord/review.py",
     "coord/scorecard.py",
     "coord/serve_app.py",
+    "coord/skills/coord-dispatch-verbs/SKILL.md",
+    "coord/skills/drive-queue-preflight/SKILL.md",
+    "coord/skills/fleet-restart-safety/SKILL.md",
+    "coord/skills/merge-stuck-triage/SKILL.md",
+    "coord/skills/pipeline-limbo-triage/SKILL.md",
     "coord/skills/portal-followup/SKILL.md",
+    "coord/skills/review-verdict-recovery/SKILL.md",
+    "coord/skills/tui-quadraui-workflow/SKILL.md",
     "coord/skills/update-issue/SKILL.md",
     "coord/smoke.py",
     "coord/spend_ceiling.py",
@@ -436,6 +443,7 @@
     "tests/acceptance/ms-65/board_tabs_2282.rs",
     "tests/acceptance/ms-65/board_tabs_close_2283.rs",
     "tests/acceptance/ms-65/contract.md",
+    "tests/acceptance/ms-65/detail_substate_2285.rs",
     "tests/acceptance/ms-65/manifest.yml",
     "tests/acceptance/ms-65/mocks/board-baseline-no-tabs.screen",
     "tests/acceptance/ms-65/mocks/board-pinned-3-tabs.screen",
@@ -486,6 +494,7 @@
     "tests/test_agent_reap.py",
     "tests/test_agent_repos_and_pull.py",
     "tests/test_agent_restart_services_endpoint.py",
+    "tests/test_agent_skills_self_heal.py",
     "tests/test_agent_startup_diagnostics.py",
     "tests/test_agent_update.py",
     "tests/test_agent_update_bluegreen.py",

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.154",
+  "tag": "0.5.158",
   "distance": 0,
-  "node": "g318d3f718e0a8945e4363a00807cd76278153173",
+  "node": "g4e440181f25b4e02cfc8fc64b76c584c7e63a197",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/coord/agent.py

@@ -4504,6 +4504,24 @@ class AgentServer:
         self._graph_heal_last_skip_at: float | None = None
         self._graph_heal_passes: int = 0
 
+        # Skills self-heal (#319 follow-up): `coord install-skills` was a
+        # real fix (coord/skills/*/SKILL.md) for a real problem, but was a
+        # 100%-manual step nothing in provisioning ever ran — so a skill
+        # added or updated in a coordinator release could sit uninstalled on
+        # a worker machine indefinitely, unnoticed, the same "silent gap"
+        # shape already known from the graphify hooks and the browser
+        # capability probe. Rides the same cached health-check tick as the
+        # graph self-heal above rather than adding a new timer — syncing a
+        # handful of small text files is cheap enough to need none of that
+        # pass's guards (no idle-gate, no in-flight dedup, no retry budget).
+        # In-memory only, resets on agent restart, same rationale as
+        # `_graph_heal_passes` above: it exists to answer "is this machine's
+        # skill set current", not to be a durable metric.
+        self._skills_heal_passes: int = 0
+        self._skills_heal_last_run_at: float | None = None
+        self._skills_heal_last_synced: list[dict[str, str]] = []
+        self._skills_heal_last_error: str | None = None
+
         self.state_dir.mkdir(parents=True, exist_ok=True)
         self.log_dir.mkdir(parents=True, exist_ok=True)
         self._load_state()
@@ -4888,6 +4906,21 @@ class AgentServer:
                 "skipped_active": self._graph_heal_skipped_active,
                 "last_skip_at": self._graph_heal_last_skip_at,
             },
+            # Same idea as `graph_self_heal` above, for the bundled
+            # `coord/skills/*/SKILL.md` sync: `coord install-skills` existed
+            # as a real fix but was a 100%-manual step nothing in
+            # provisioning ever ran, so a skill added in a coordinator
+            # release could sit uninstalled on a worker machine
+            # indefinitely, unnoticed. `last_synced` names whichever skills
+            # actually changed on the most recent pass (empty on the common
+            # "already current" tick) so `coord doctor` can show something
+            # more useful than a bare pass count.
+            "skills_self_heal": {
+                "passes": self._skills_heal_passes,
+                "last_run_at": self._skills_heal_last_run_at,
+                "last_synced": self._skills_heal_last_synced,
+                "last_error": self._skills_heal_last_error,
+            },
             # #2299: is this agent actually watching a coordinator.yml, and
             # has it picked anything up? `watching` is None for a
             # config-free/thin-client agent (nothing local to re-read), which
@@ -4953,6 +4986,12 @@ class AgentServer:
                 self._self_heal_stale_graphs(ctx, report)
             except Exception as exc:  # noqa: BLE001 — self-heal is best-effort
                 _log.warning("graph self-heal pass failed: %s", exc)
+            try:
+                # Same isolation as the graph pass above: a skills-sync bug
+                # must never blind this whole health block.
+                self._self_heal_missing_skills()
+            except Exception as exc:  # noqa: BLE001 — self-heal is best-effort
+                _log.warning("skills self-heal pass failed: %s", exc)
             report_dict = report.to_dict()
             payload = {
                 "schema": report_dict["schema"],
@@ -5169,6 +5208,59 @@ class AgentServer:
             if replacement is not None:
                 report.results[i] = replacement
 
+    def _self_heal_missing_skills(self) -> None:
+        """Sync bundled `coord/skills/*/SKILL.md` into ``~/.claude/skills/``
+        on this machine, riding the same cached health-check tick as
+        `_self_heal_stale_graphs` above.
+
+        `coord install-skills` (#319) was a real fix for a real problem, but
+        it was a 100%-manual step — nothing in agent provisioning or this
+        health tick ever ran it, so a skill added or updated in a
+        coordinator release could sit uninstalled on a worker machine
+        indefinitely, unnoticed. That is the same "silent gap" shape as the
+        graphify hooks and the browser-capability probe this codebase
+        already knows about.
+
+        Unlike the graph rebuild, this needs none of that pass's four
+        guards: syncing a handful of small text files is cheap file I/O, not
+        a CPU-heavy subprocess, so there is no idle-gate, no in-flight
+        dedup, and no retry budget — `sync_bundled_skills` is already
+        idempotent (content-identical files are left untouched, so a
+        no-op tick costs a handful of reads, nothing more).
+        """
+        from coord.commands.setup import (  # noqa: PLC0415
+            list_bundled_skill_dirs,
+            sync_bundled_skills,
+        )
+
+        target_root = Path.home() / ".claude" / "skills"
+        try:
+            skill_dirs = list_bundled_skill_dirs()
+        except Exception as exc:  # noqa: BLE001 — recorded, never raised further
+            self._skills_heal_last_error = f"{type(exc).__name__}: {exc}"
+            return
+
+        self._skills_heal_passes += 1
+        self._skills_heal_last_run_at = time.time()
+        self._skills_heal_last_error = None
+        if not skill_dirs:
+            self._skills_heal_last_synced = []
+            return
+
+        target_root.mkdir(parents=True, exist_ok=True)
+        results = sync_bundled_skills(target_root, skill_dirs)
+        changed = [
+            {"skill": name, "action": action}
+            for name, action in results
+            if action != "unchanged"
+        ]
+        self._skills_heal_last_synced = changed
+        if changed:
+            _log.info(
+                "skills self-heal: %s",
+                ", ".join(f"{c['skill']} {c['action']}" for c in changed),
+            )
+
     @staticmethod
     def _graph_failure_result(result: Any, values: dict, detail: str) -> Any:
         """Guard 4's WARN replacement, shared by the attempt and the

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/coord/commands/issues.py

@@ -683,6 +683,9 @@ def backlog(repo: str, issue: int, config_path: Path) -> None:
         "Stage a Pipeline issue as \"next up\" by tagging it with "
         "`status:queued` — moves a Pipeline:New card into "
         "In-progress:`ready` with no dispatch (display + intent only).\n\n"
+        "NOT the driver queue: this command never dispatches anything. To "
+        "actually get an issue worked end-to-end, use `coord drive-queue "
+        "add <repo> <issue>` instead — see the coord-dispatch-verbs skill.\n\n"
         "Deliberately a separate label from `status:ready`: that one is "
         "already applied automatically by `coord track` / the refinement "
         "finalize step for every issue sent to the Pipeline, so it carries "

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/coord/commands/setup.py

@@ -482,6 +482,60 @@ def _build_init_yaml(
     return "\n".join(lines) + "\n"
 
 
+def list_bundled_skill_dirs() -> list[tuple[str, object]]:
+    """Enumerate bundled `coord/skills/*/SKILL.md` directories (#319).
+
+    Returns ``(skill_name, entry)`` pairs, sorted by name, for every
+    sub-directory of the installed `coord.skills` package that contains a
+    readable ``SKILL.md``. Raises ``ModuleNotFoundError``/``TypeError`` if
+    the package itself can't be located, or ``FileNotFoundError``/
+    ``NotADirectoryError`` if its directory listing can't be read — callers
+    decide how to surface that (``install_skills`` below exits 1; the
+    agent-side self-heal in `agent.py` logs and moves on, since a skills
+    hiccup must never block `/health`).
+    """
+    import importlib.resources as _ilr  # noqa: PLC0415
+
+    skills_ref = _ilr.files("coord").joinpath("skills")
+    skill_dirs: list[tuple[str, object]] = []
+    for entry in skills_ref.iterdir():
+        skill_name = entry.name  # type: ignore[attr-defined]
+        skill_file = entry.joinpath("SKILL.md")
+        try:
+            skill_file.read_text(encoding="utf-8")
+            skill_dirs.append((skill_name, entry))
+        except (FileNotFoundError, IsADirectoryError, TypeError):
+            pass
+    return sorted(skill_dirs)
+
+
+def sync_bundled_skills(
+    target_root: Path, skill_dirs: list[tuple[str, object]]
+) -> list[tuple[str, str]]:
+    """Write each ``(skill_name, entry)`` from *skill_dirs* into
+    *target_root* (normally ``~/.claude/skills/``) if missing or changed
+    (#319 / agent self-heal).
+
+    Returns ``(skill_name, action)`` pairs, ``action`` one of ``"installed"``,
+    ``"updated"``, or ``"unchanged"`` — content-identical skills are left
+    untouched (no rewrite, no mtime bump) so a periodic caller can run this
+    every tick without churn. Does not create *target_root* itself; callers
+    create it first once they know there is something to write.
+    """
+    results: list[tuple[str, str]] = []
+    for skill_name, skill_dir_ref in skill_dirs:
+        skill_file_dest = target_root / skill_name / "SKILL.md"
+        src_text = skill_dir_ref.joinpath("SKILL.md").read_text(encoding="utf-8")  # type: ignore[attr-defined]
+        if skill_file_dest.exists() and skill_file_dest.read_text(encoding="utf-8") == src_text:
+            results.append((skill_name, "unchanged"))
+            continue
+        action = "updated" if skill_file_dest.exists() else "installed"
+        skill_file_dest.parent.mkdir(parents=True, exist_ok=True)
+        skill_file_dest.write_text(src_text, encoding="utf-8")
+        results.append((skill_name, action))
+    return results
+
+
 @click.command(
     "install-skills",
     help=(
@@ -490,8 +544,6 @@ def _build_init_yaml(
         "No repo clone required — reads from the installed PyPI package."
     ),
 )
-
-
 @click.option(
     "--list",
     "do_list",
@@ -499,43 +551,24 @@ def _build_init_yaml(
     default=False,
     help="Show bundled skills and their installed status without copying.",
 )
-
-
 @click.option(
     "--dry-run",
     is_flag=True,
     default=False,
     help="Print what would be installed without writing any files.",
 )
-
-
 def install_skills(do_list: bool, dry_run: bool) -> None:  # noqa: FBT001
     """Install bundled coordinator skills to ~/.claude/skills/ (#319)."""
-    import importlib.resources as _ilr  # noqa: PLC0415
-
     if do_list and dry_run:
         click.echo("warning: --dry-run has no effect when --list is used", err=True)
 
     target_root = Path.home() / ".claude" / "skills"
 
-    # Locate the skills directory inside the installed package.
     try:
-        skills_ref = _ilr.files("coord").joinpath("skills")
+        skill_dirs = list_bundled_skill_dirs()
     except (TypeError, ModuleNotFoundError) as e:
         click.echo(f"error: cannot locate bundled skills: {e}", err=True)
         sys.exit(1)
-
-    # Enumerate skill directories (each sub-directory that contains SKILL.md).
-    skill_dirs: list[tuple[str, object]] = []
-    try:
-        for entry in skills_ref.iterdir():
-            skill_name = entry.name  # type: ignore[attr-defined]
-            skill_file = entry.joinpath("SKILL.md")
-            try:
-                skill_file.read_text(encoding="utf-8")
-                skill_dirs.append((skill_name, entry))
-            except (FileNotFoundError, IsADirectoryError, TypeError):
-                pass
     except (FileNotFoundError, NotADirectoryError) as e:
         click.echo(f"error: bundled skills directory not readable: {e}", err=True)
         sys.exit(1)
@@ -546,31 +579,26 @@ def install_skills(do_list: bool, dry_run: bool) -> None:  # noqa: FBT001
 
     if do_list:
         click.echo("Bundled skills:")
-        for skill_name, _ in sorted(skill_dirs):
+        for skill_name, _ in skill_dirs:
             installed_path = target_root / skill_name / "SKILL.md"
             status = "installed" if installed_path.exists() else "not installed"
             click.echo(f"  {skill_name:30s}  {status}")
         return
 
-    # Install / update each skill.
-    if not dry_run:
-        target_root.mkdir(parents=True, exist_ok=True)
-    for skill_name, skill_dir_ref in sorted(skill_dirs):
-        skill_dest = target_root / skill_name
-        skill_file_dest = skill_dest / "SKILL.md"
-        if dry_run:
+    if dry_run:
+        for skill_name, _ in skill_dirs:
+            skill_file_dest = target_root / skill_name / "SKILL.md"
             action = "update" if skill_file_dest.exists() else "install"
             click.echo(f"  would {action}: {skill_file_dest}")
-            continue
+        return
 
-        skill_dest.mkdir(parents=True, exist_ok=True)
-        src_text = skill_dir_ref.joinpath("SKILL.md").read_text(encoding="utf-8")
-        action = "updated" if skill_file_dest.exists() else "installed"
-        skill_file_dest.write_text(src_text, encoding="utf-8")
-        click.echo(f"  {action}: {skill_file_dest}")
+    target_root.mkdir(parents=True, exist_ok=True)
+    for skill_name, action in sync_bundled_skills(target_root, skill_dirs):
+        if action == "unchanged":
+            continue
+        click.echo(f"  {action}: {target_root / skill_name / 'SKILL.md'}")
 
-    if not dry_run:
-        installed_names = sorted(name for name, _ in skill_dirs)
-        cmd_list = "  ".join(f"/{n}" for n in installed_names)
-        click.echo(f"\nDone. Available skills: {cmd_list}")
-        click.echo("Type a skill name inside a Claude Code session to use it.")
+    installed_names = sorted(name for name, _ in skill_dirs)
+    cmd_list = "  ".join(f"/{n}" for n in installed_names)
+    click.echo(f"\nDone. Available skills: {cmd_list}")
+    click.echo("Type a skill name inside a Claude Code session to use it.")

{code_coordinator-0.5.154 → code_coordinator-0.5.158}/coord/drive_queue.py

@@ -1920,6 +1920,51 @@ def _retry_backoff_reason(
     )
 
 
+def _augment_backoff_reason(previous_reason: str, backoff_text: str) -> str:
+    """#2411: fold the real death cause into the mechanical backoff text.
+
+    Before this, `plan_tick`'s waiting walk persisted `_retry_backoff_reason`'s
+    return value as the entry's WHOLE `last_reason` on every tick it spent
+    backing off — the purely mechanical "next attempt permitted in Ns"
+    sentence, deliberately recomputed fresh each tick (see that function's
+    docstring). That overwrote the rich `own_reason` (plus the #2273
+    dispatch note and #2363 empty-branch note) `_reconcile_running`'s
+    `retry` branch had just recorded at the moment of death — visible for
+    exactly one tick, then gone. An operator reading `coord drive-queue
+    list` — or anything else that reads `last_reason`, like `coord
+    drive-queue diagnose` — saw only the spacing text and had no live way to
+    tell WHY the entry kept dying, only that it would try again later.
+
+    Fix: keep the FIRST LINE of whatever reason is already on record — the
+    real cause, written once at death — and put the fresh backoff sentence
+    on a second line under it. `last_reason` was already documented as
+    "possibly multi-line" (see `_ROW_CAUSE_MAX_CHARS`'s comment in
+    `coord.commands.drive_queue`) precisely so a summary render can show
+    line one on the row and the full text on the `last:` continuation line
+    — this reuses that convention rather than inventing a new field or
+    column.
+
+    Using only the first line (not the full previous text) keeps this
+    idempotent across ticks: called again next tick against ITS OWN
+    two-line output, the first line is still the original cause, never
+    last tick's backoff sentence, so the stored text never grows past two
+    lines no matter how many ticks the entry spends backing off.
+
+    Falls back to *backoff_text* alone when there is nothing to keep — a
+    row with no prior `last_reason` (a fresh entry, or one hand-built in a
+    test) — which is exactly today's pre-#2411 text for that case.
+    """
+    stripped = previous_reason.strip()
+    if not stripped:
+        return backoff_text
+    base = stripped.splitlines()[0]
+    # 3-space continuation indent — the same convention `coord/drive.py`'s
+    # own multi-line exit reasons already use for their "inspect: coord log
+    # ..." follow-up lines, so a combined reason reads as one paragraph
+    # rather than a mismatched second line flush against the left margin.
+    return f"{base}\n   {backoff_text}"
+
+
 def _reconcile_running(
     entry: QueueEntry,
     board: BoardView,
@@ -3054,6 +3099,15 @@ def plan_tick(
     # this falls back to (the post-review #2273 "moving target" fix).
     effective_attempts: dict[str, int] = {e.key: e.attempts for e in ordered}
     retry_backoff_at_map: dict[str, float] = {}
+    # #2411: same "prefer this tick's fresh write" rule, this time for the
+    # real death cause `_backoff_reason` below folds into its combined
+    # `last_reason` — see `_augment_backoff_reason`. Without this, an entry
+    # that dies and hits the backoff check in the SAME tick (step 1 above,
+    # then step 4 below) would combine against its STALE pre-tick
+    # `entry.last_reason` — one tick behind the death this walk just
+    # recorded — instead of the `own_reason`-based text `reconcile.reason`
+    # carries fresh, right below.
+    effective_last_reason: dict[str, str] = {e.key: e.last_reason for e in ordered}
 
     reconciles: list[Reconcile] = []
     blocked: list[Blocked] = []
@@ -3112,6 +3166,14 @@ def plan_tick(
             # for a backoff check reached later in this SAME tick, not the
             # entry's stale pre-tick `retry_backoff_at`.
             retry_backoff_at_map[entry.key] = now
+        if reconcile.outcome == "retry":
+            # #2411: `reconcile.reason` IS `reconcile.updates["last_reason"]`
+            # (the retry branch of `_reconcile_running` builds both from the
+            # same local `reason`) — the real death cause, `own_reason` plus
+            # its #2273 dispatch-note/#2363 empty-branch-note. Recorded here
+            # so a backoff check reached later in THIS tick combines against
+            # it instead of the pre-tick `entry.last_reason`.
+            effective_last_reason[entry.key] = reconcile.reason
         if block is not None:
             blocked.append(block)
             states[entry.key] = STATE_BLOCKED
@@ -3535,14 +3597,25 @@ def plan_tick(
         see that function's docstring for why neither can be read straight
         off `candidate`, and why the fallback is `candidate.retry_backoff_at`
         rather than `candidate.reason_at`.
+
+        #2411: the mechanical spacing text that comes back is never returned
+        bare — :func:`_augment_backoff_reason` folds in the real death cause
+        (resolved the same "prefer this tick's fresh write" way, off
+        `effective_last_reason`) so both call sites below — the report-only
+        dry-run pass and the persisted `last_reason` write — get the combined
+        text for free, with no change needed at either site.
         """
-        return _retry_backoff_reason(
+        backoff = _retry_backoff_reason(
             candidate,
             board.facts(candidate.key),
             now,
             effective_attempts.get(candidate.key, candidate.attempts),
             retry_backoff_at_map.get(candidate.key, candidate.retry_backoff_at),
         )
+        if not backoff:
+            return ""
+        previous = effective_last_reason.get(candidate.key, candidate.last_reason)
+        return _augment_backoff_reason(previous, backoff)
 
     # #1972's projection of per-repo occupancy AS THE WALK SEES IT: the board
     # reading above, plus this tick's own launch once one is chosen.  Kept

code_coordinator-0.5.158/coord/skills/coord-dispatch-verbs/SKILL.md

@@ -0,0 +1,76 @@
+# coord-dispatch-verbs skill
+
+**Trigger:** About to run a `coord` command to enqueue, dispatch, stage, or
+otherwise move a GitHub issue forward through the coordinator — from any repo,
+including agents working *inside* a coordinator-managed repo, not just the
+operator's own coordinator session — especially when unsure of the exact
+subcommand name, or when a command exited 0 / printed a success message but
+the expected effect (an entry in the queue, an assignment, a dispatch) didn't
+show up.
+
+**Purpose:** `coord`'s CLI has roughly 70 top-level commands, and several have
+names that sound interchangeable but do very different things — picking the
+wrong one usually does **not** error, it silently does something else. This is
+the disambiguation table for the pairs that have actually cost real time,
+plus the one rule that would catch a wrong guess before it's mistaken for
+success.
+
+---
+
+## The incident this skill exists for
+
+An agent working in coord-portal wanted to queue issue #119 for the
+coordinator to pick up. It ran:
+
+```
+coord queue coord-portal 119
+```
+
+This command **exists**, exited 0, and printed a success-looking message — so
+nothing signaled a mistake. But `coord queue` is **not** the driver queue. It
+only tags the issue with a `status:queued` **label** — "next up" staging,
+display + intent only, no dispatch (#1500; it's what the TUI's right-click
+"Mark ready" fires). The issue never entered `coord drive-queue`'s actual
+`waiting` list, so nothing ever picked it up.
+
+**The command that was needed:** `coord drive-queue add coord-portal 119` —
+the durable, board-backed driver queue (#1750) that a periodic tick actually
+walks and dispatches from. See `docs/DRIVE_QUEUE.md` and the
+`drive-queue-preflight` skill.
+
+## Disambiguation table — commands whose names collide but whose effects don't
+
+| If you want to... | Use | NOT | Why the wrong one is dangerous |
+|---|---|---|---|
+| Actually get an issue worked, end-to-end, unattended | `coord drive-queue add <repo> <issue>` | `coord queue <repo> <issue>` | `queue` only applies a label — no dispatch, ever. A silent no-op relative to what you wanted. |
+| Dispatch one issue's Work stage right now, interactively | `coord assign <machine> <repo> <issue>` | `coord drive <repo> <issue> --tmux` outside the queue, while the queue timer is active | `--tmux` drives correctly but is invisible to the queue panel and can race a live `coord-drive-queue.timer` tick — see `docs/OPERATING_GOTCHAS.md` #9. |
+| Un-stage an issue you `coord queue`'d by mistake | `coord unqueue <repo> <issue>` | `coord drive-queue remove <repo> <issue>` | These touch two different systems (a label vs. a queue row) — running the wrong one leaves the other system's state untouched and the symptom persists. |
+| Retry a failed **queue entry** | remove + re-add (`coord drive-queue remove` then `add`) | `coord retry <assignment_id>` | `retry` operates on a board *assignment*, not a drive-queue row — there is deliberately no `coord drive-queue reset` (see `drive-queue-preflight` / `docs/DRIVE_QUEUE.md` §4). |
+| Check whether an issue is actually queued | `coord drive-queue list` / `coord drive-queue status` | trusting the exit code of whatever command you just ran | `coord queue`, `coord assign`, and `coord drive-queue add` all print a success line on their own happy path — only `coord drive-queue list` proves the entry exists as `waiting`. |
+
+## The one rule
+
+**A `coord` command exiting 0 is proof it did what *that command* does — not
+proof it did what you intended.** Before reporting a dispatch/queue/staging
+action as done, confirm the effect directly:
+
+```bash
+coord drive-queue list          # is my issue actually a waiting/running row?
+coord status                    # does an assignment exist for it?
+coord gates <repo> <issue>      # what stage does the board think it's in?
+```
+
+If unsure which of two similarly-named commands does what you want, run
+`coord <command> --help` first — every command's help text states its exact
+effect (`coord queue --help` says so explicitly: "no dispatch, display +
+intent only"). Guessing from the name alone is how this incident happened.
+
+## Rules
+
+- Never assume `coord queue` enqueues work for dispatch — it only labels. The
+  only real dispatch queue is `coord drive-queue`.
+- After any dispatch/queue command, verify with `coord drive-queue list` or
+  `coord status` before reporting the action as done — don't trust a clean
+  exit code alone.
+- When unsure between two `coord` subcommands with similar names, run
+  `--help` on the one you're about to use before running it.