PyPI - code-coordinator - Versions diffs - 0.5.46__py3-none-any.whl - Mend

code-coordinator 0.5.46__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (295) hide show

code_coordinator-0.5.46.dist-info/METADATA +625 -0
code_coordinator-0.5.46.dist-info/RECORD +295 -0
code_coordinator-0.5.46.dist-info/WHEEL +5 -0
code_coordinator-0.5.46.dist-info/entry_points.txt +2 -0
code_coordinator-0.5.46.dist-info/licenses/LICENSE +110 -0
code_coordinator-0.5.46.dist-info/top_level.txt +1 -0
coord/__init__.py +176 -0
coord/_board_mapping.py +229 -0
coord/acceptance.py +468 -0
coord/acceptance_drivers.py +632 -0
coord/agent.py +7517 -0
coord/agent_app.py +1555 -0
coord/agent_update.py +417 -0
coord/agents/opencode/.gitignore +13 -0
coord/agents/opencode/agents/work.md +129 -0
coord/agents/opencode/routing.jsonc +49 -0
coord/audit.py +301 -0
coord/auto_loop.py +1440 -0
coord/board_bool_guard.py +72 -0
coord/board_service.py +141 -0
coord/board_wire.py +309 -0
coord/brain.py +581 -0
coord/branch_model.py +214 -0
coord/cargo_cache.py +258 -0
coord/ci_github.py +386 -0
coord/ci_store.py +560 -0
coord/claim.py +353 -0
coord/cli.py +454 -0
coord/client.py +610 -0
coord/commands/__init__.py +1 -0
coord/commands/_common.py +329 -0
coord/commands/acceptance.py +916 -0
coord/commands/agent_ops.py +1339 -0
coord/commands/audit.py +131 -0
coord/commands/chat.py +320 -0
coord/commands/dispatch.py +1780 -0
coord/commands/dispatch_workers.py +4894 -0
coord/commands/drive.py +616 -0
coord/commands/drive_queue.py +1203 -0
coord/commands/gate_a.py +217 -0
coord/commands/gates.py +89 -0
coord/commands/issues.py +681 -0
coord/commands/lifecycle.py +513 -0
coord/commands/merge.py +1900 -0
coord/commands/milestone.py +2081 -0
coord/commands/plan_followup.py +1243 -0
coord/commands/plans.py +156 -0
coord/commands/release.py +2232 -0
coord/commands/report.py +341 -0
coord/commands/review.py +1523 -0
coord/commands/scorecard.py +252 -0
coord/commands/sessions.py +1930 -0
coord/commands/setup.py +576 -0
coord/commands/status.py +2089 -0
coord/commands/terminal.py +385 -0
coord/commands/test_gate.py +775 -0
coord/commands/tui.py +288 -0
coord/comments.py +718 -0
coord/config.py +3032 -0
coord/conflict_fix.py +633 -0
coord/dao.py +483 -0
coord/dashboard/__init__.py +0 -0
coord/dashboard/fixture.py +376 -0
coord/dashboard/index.html +658 -0
coord/dashboard/server.py +1894 -0
coord/dashboard/terminal.py +382 -0
coord/dashboard/webapp/.gitignore +9 -0
coord/dashboard/webapp/components.json +17 -0
coord/dashboard/webapp/dist/assets/Gallery-da3qNiIw.js +71 -0
coord/dashboard/webapp/dist/assets/Terminal-9CEnUXvW.css +32 -0
coord/dashboard/webapp/dist/assets/Terminal-skVFCxPU.js +63 -0
coord/dashboard/webapp/dist/assets/index-DltfZR5f.js +184 -0
coord/dashboard/webapp/dist/assets/index-Dq4kwTdw.css +1 -0
coord/dashboard/webapp/dist/assets/workbox-window.prod.es5-BqEJf4Xk.js +2 -0
coord/dashboard/webapp/dist/icons/icon-192.png +0 -0
coord/dashboard/webapp/dist/icons/icon-512.png +0 -0
coord/dashboard/webapp/dist/icons/icon.svg +5 -0
coord/dashboard/webapp/dist/index.html +38 -0
coord/dashboard/webapp/dist/manifest.webmanifest +1 -0
coord/dashboard/webapp/dist/sw.js +1 -0
coord/dashboard/webapp/dist/workbox-e4022e15.js +1 -0
coord/dashboard/webapp/e2e/available-gates-terminal.spec.ts +75 -0
coord/dashboard/webapp/e2e/deep-link.spec.ts +172 -0
coord/dashboard/webapp/e2e/fixtureServer.ts +155 -0
coord/dashboard/webapp/e2e/live-update-fixture.spec.ts +113 -0
coord/dashboard/webapp/e2e/realtime.spec.ts +238 -0
coord/dashboard/webapp/e2e/shell.spec.ts +309 -0
coord/dashboard/webapp/e2e/smoke.spec.ts +191 -0
coord/dashboard/webapp/e2e/terminal.spec.ts +420 -0
coord/dashboard/webapp/e2e/theme.spec.ts +138 -0
coord/dashboard/webapp/eslint.config.js +20 -0
coord/dashboard/webapp/index.html +37 -0
coord/dashboard/webapp/node_modules/flatted/python/flatted.py +144 -0
coord/dashboard/webapp/package-lock.json +10584 -0
coord/dashboard/webapp/package.json +63 -0
coord/dashboard/webapp/playwright.acceptance.config.ts +166 -0
coord/dashboard/webapp/playwright.config.ts +93 -0
coord/dashboard/webapp/postcss.config.js +6 -0
coord/dashboard/webapp/public/icons/icon-192.png +0 -0
coord/dashboard/webapp/public/icons/icon-512.png +0 -0
coord/dashboard/webapp/public/icons/icon.svg +5 -0
coord/dashboard/webapp/src/App.tsx +140 -0
coord/dashboard/webapp/src/api/client.ts +199 -0
coord/dashboard/webapp/src/api/generated.ts +176 -0
coord/dashboard/webapp/src/components/ConnectionBadge.tsx +52 -0
coord/dashboard/webapp/src/components/Detail.tsx +800 -0
coord/dashboard/webapp/src/components/Gallery.tsx +341 -0
coord/dashboard/webapp/src/components/Home.tsx +435 -0
coord/dashboard/webapp/src/components/MobileKeyBar.tsx +280 -0
coord/dashboard/webapp/src/components/PanelHeader.tsx +59 -0
coord/dashboard/webapp/src/components/PipelineCard.tsx +168 -0
coord/dashboard/webapp/src/components/SessionCard.tsx +99 -0
coord/dashboard/webapp/src/components/SessionDetail.tsx +140 -0
coord/dashboard/webapp/src/components/SessionsList.tsx +81 -0
coord/dashboard/webapp/src/components/Terminal.tsx +376 -0
coord/dashboard/webapp/src/components/__tests__/ConnectionBadge.test.tsx +81 -0
coord/dashboard/webapp/src/components/__tests__/Detail.test.tsx +680 -0
coord/dashboard/webapp/src/components/__tests__/Gallery.test.tsx +83 -0
coord/dashboard/webapp/src/components/__tests__/Home.test.tsx +271 -0
coord/dashboard/webapp/src/components/__tests__/MobileKeyBar.test.tsx +197 -0
coord/dashboard/webapp/src/components/__tests__/PipelineCard.test.tsx +143 -0
coord/dashboard/webapp/src/components/__tests__/SessionCard.test.tsx +106 -0
coord/dashboard/webapp/src/components/__tests__/Terminal.test.tsx +504 -0
coord/dashboard/webapp/src/components/ui/badge.tsx +41 -0
coord/dashboard/webapp/src/components/ui/button.tsx +54 -0
coord/dashboard/webapp/src/components/ui/card.tsx +55 -0
coord/dashboard/webapp/src/components/ui/dialog.tsx +99 -0
coord/dashboard/webapp/src/components/ui/dropdown-menu.tsx +189 -0
coord/dashboard/webapp/src/components/ui/empty-state.tsx +35 -0
coord/dashboard/webapp/src/components/ui/sheet.tsx +123 -0
coord/dashboard/webapp/src/components/ui/skeleton.tsx +9 -0
coord/dashboard/webapp/src/components/ui/tabs.tsx +55 -0
coord/dashboard/webapp/src/components/ui/theme-provider.tsx +78 -0
coord/dashboard/webapp/src/components/ui/theme-toggle.tsx +20 -0
coord/dashboard/webapp/src/components/ui/toast.tsx +123 -0
coord/dashboard/webapp/src/components/ui/toaster.tsx +30 -0
coord/dashboard/webapp/src/components/ui/tooltip.tsx +26 -0
coord/dashboard/webapp/src/components/ui/use-toast.ts +134 -0
coord/dashboard/webapp/src/index.css +210 -0
coord/dashboard/webapp/src/lib/pipeline.ts +29 -0
coord/dashboard/webapp/src/lib/utils.ts +6 -0
coord/dashboard/webapp/src/main.tsx +46 -0
coord/dashboard/webapp/src/realtime/RealtimeProvider.tsx +112 -0
coord/dashboard/webapp/src/realtime/__tests__/RealtimeProvider.test.tsx +189 -0
coord/dashboard/webapp/src/realtime/__tests__/connection.test.ts +255 -0
coord/dashboard/webapp/src/realtime/connection.ts +227 -0
coord/dashboard/webapp/src/realtime/events.ts +100 -0
coord/dashboard/webapp/src/routes/__tests__/paths.test.ts +92 -0
coord/dashboard/webapp/src/routes/paths.ts +92 -0
coord/dashboard/webapp/src/shell/ActivityRail.tsx +335 -0
coord/dashboard/webapp/src/shell/AppShell.tsx +276 -0
coord/dashboard/webapp/src/shell/ComingSoon.tsx +33 -0
coord/dashboard/webapp/src/shell/EmptyDetail.tsx +26 -0
coord/dashboard/webapp/src/shell/RouteNotFound.tsx +33 -0
coord/dashboard/webapp/src/shell/ShellLayout.tsx +147 -0
coord/dashboard/webapp/src/shell/StatusBar.tsx +46 -0
coord/dashboard/webapp/src/shell/__tests__/ShellLayout.test.tsx +520 -0
coord/dashboard/webapp/src/shell/__tests__/shellState.test.ts +95 -0
coord/dashboard/webapp/src/shell/__tests__/stubViewport.ts +40 -0
coord/dashboard/webapp/src/shell/breakpoints.ts +87 -0
coord/dashboard/webapp/src/shell/railItems.ts +105 -0
coord/dashboard/webapp/src/shell/shellState.ts +174 -0
coord/dashboard/webapp/src/shell/useRegionFocus.ts +95 -0
coord/dashboard/webapp/src/test-setup.ts +41 -0
coord/dashboard/webapp/src/vite-env.d.ts +2 -0
coord/dashboard/webapp/tailwind.config.js +140 -0
coord/dashboard/webapp/tsconfig.json +25 -0
coord/dashboard/webapp/tsconfig.node.json +11 -0
coord/dashboard/webapp/vite.config.ts +71 -0
coord/db.py +1076 -0
coord/dead_end.py +332 -0
coord/deploy/README.md +33 -0
coord/deploy/coord-agent.service +89 -0
coord/deploy/coord-db-backup.service +60 -0
coord/deploy/coord-db-backup.sh +74 -0
coord/deploy/coord-db-backup.timer +18 -0
coord/deploy/coord-drive-queue.service +117 -0
coord/deploy/coord-drive-queue.timer +39 -0
coord/deploy/coord-notify.service +48 -0
coord/deploy/coord-notify.timer +24 -0
coord/deploy/coord-release-propagate.service +83 -0
coord/deploy/coord-release-propagate.timer +38 -0
coord/deploy/coord-release-window.service +119 -0
coord/deploy/coord-release-window.timer +36 -0
coord/deploy/coord-serve.service +82 -0
coord/deploy/coord-web-dist-build.service +43 -0
coord/deploy/coord-web-dist-build.timer +36 -0
coord/deploy/coord-web.service +125 -0
coord/deploy_manifest.py +80 -0
coord/deploy_units.py +384 -0
coord/deps.py +115 -0
coord/diagnose.py +1623 -0
coord/dispatch.py +1009 -0
coord/dist_name.py +123 -0
coord/drive.py +3101 -0
coord/drive_queue.py +2298 -0
coord/drive_state.py +870 -0
coord/events.py +381 -0
coord/failure_class.py +914 -0
coord/filelock.py +168 -0
coord/fleet_config_health.py +300 -0
coord/freshness.py +206 -0
coord/gate_a.py +469 -0
coord/gate_b.py +411 -0
coord/gate_snapshot.py +385 -0
coord/gates.py +582 -0
coord/github_ops.py +1954 -0
coord/goal.py +125 -0
coord/graph_health.py +348 -0
coord/health/__init__.py +69 -0
coord/health/aggregate.py +129 -0
coord/health/checks/__init__.py +13 -0
coord/health/checks/agent_install.py +280 -0
coord/health/checks/cargo_targets.py +171 -0
coord/health/checks/claude_binary.py +65 -0
coord/health/checks/deploy_lane_facts.py +458 -0
coord/health/checks/disk.py +99 -0
coord/health/checks/fleet_board.py +89 -0
coord/health/checks/fleet_deploy_lanes.py +469 -0
coord/health/checks/fleet_phantom.py +69 -0
coord/health/checks/fleet_unit_drift.py +151 -0
coord/health/checks/graph.py +192 -0
coord/health/checks/plan_usage.py +88 -0
coord/health/checks/repo_state.py +161 -0
coord/health/checks/spawned_coord.py +465 -0
coord/health/checks/timer_active.py +254 -0
coord/health/checks/toolchain.py +547 -0
coord/health/checks/unit_drift.py +648 -0
coord/health/checks/unit_enablement.py +171 -0
coord/health/checks/worktrees.py +96 -0
coord/health/cli.py +121 -0
coord/health/context.py +106 -0
coord/health/fleet_snapshot.py +477 -0
coord/health/models.py +250 -0
coord/health/pypi.py +231 -0
coord/health/registry.py +240 -0
coord/health/render.py +82 -0
coord/health/units.py +60 -0
coord/hooks.py +106 -0
coord/housekeeping.py +204 -0
coord/interactive.py +4286 -0
coord/issue_store.py +1496 -0
coord/liveness_auditor.py +293 -0
coord/machine_pause.py +755 -0
coord/merge_queue.py +4681 -0
coord/milestone_chat.py +600 -0
coord/milestone_dispatch.py +943 -0
coord/milestone_gate.py +709 -0
coord/milestone_order.py +840 -0
coord/mock_author.py +334 -0
coord/models.py +891 -0
coord/network.py +269 -0
coord/new_issue_chat.py +229 -0
coord/notify.py +3226 -0
coord/openapi.py +404 -0
coord/overlap_fence.py +133 -0
coord/parentage.py +200 -0
coord/parentage_github.py +58 -0
coord/pipeline.py +481 -0
coord/plan_parser.py +266 -0
coord/plans.py +543 -0
coord/platform_paths.py +43 -0
coord/pr_body_lint.py +67 -0
coord/prereqs.py +533 -0
coord/progress.py +425 -0
coord/providers/__init__.py +683 -0
coord/providers/base.py +218 -0
coord/providers/claude.py +284 -0
coord/providers/claude_pty.py +610 -0
coord/providers/opencode.py +896 -0
coord/reconcile.py +2233 -0
coord/refine_chat.py +485 -0
coord/release_cordon.py +525 -0
coord/release_propagate.py +1176 -0
coord/release_verify.py +777 -0
coord/release_window.py +322 -0
coord/reports.py +1643 -0
coord/revalidate.py +1101 -0
coord/review.py +3317 -0
coord/scorecard.py +484 -0
coord/serve_app.py +7192 -0
coord/skills/update-issue/SKILL.md +93 -0
coord/smoke.py +1030 -0
coord/split_work.py +210 -0
coord/stage_projection.py +650 -0
coord/state.py +5720 -0
coord/test_author.py +1064 -0
coord/test_chat.py +352 -0
coord/test_orchestrator.py +494 -0
coord/test_report.py +178 -0
coord/tui_release.py +271 -0
coord/usage.py +753 -0
coord/usage_limits.py +358 -0
coord/usage_rollup.py +709 -0
coord/worker_events.py +954 -0

coord/comments.py ADDED Viewed

@@ -0,0 +1,718 @@
+"""Format and parse coordinator-authored issue comments.
+Comments are the message bus between the coordinator and human reviewers. They
+need to be readable in GitHub's UI *and* parseable by future automation, so
+each comment carries an HTML-comment marker with key=value metadata.
+Marker grammar: `<!-- coord:event=<event> assignment=<id> ... -->`
+"""
+from __future__ import annotations
+import json
+import re
+from dataclasses import dataclass
+from typing import Iterable
+EVENT_BRIEFING = "briefing"
+EVENT_COMPLETION = "completion"
+EVENT_FAILURE = "failure"
+EVENT_STUCK = "stuck"
+EVENT_PLAN = "plan"
+EVENT_ADVISORY = "advisory"
+# #846: an assignment running past its wall-clock threshold, or thrashing
+# through fix/review rounds without converging. Distinct from EVENT_STUCK
+# (a worker self-reported STATUS/STUCK line) — this fires from time/round
+# based detection, which also catches the "silently burned budget, looked
+# productive the whole time" failure mode STUCK: lines miss (see #448).
+EVENT_NEEDS_ATTENTION = "needs_attention"
+# #1441: a pipeline row whose auto-loop TRANSITION already fired (a review
+# completed, a fix completed) but which is now stuck on a precondition that
+# landed too late for that one-shot reaction to see — e.g. a test verdict
+# that arrives after the review it should have unblocked was already
+# processed. Distinct from EVENT_NEEDS_ATTENTION (which watches *running*
+# assignments for a wall-clock/convergence signal) — this watches *done*
+# work chains for a downstream step that should have happened by now and
+# didn't.
+EVENT_STALLED = "stalled_pipeline"
+# #2048: N consecutive BLOCKED verdicts from the cheap per-turn liveness
+# auditor (coord/liveness_auditor.py). Distinct from EVENT_STUCK (self-
+# reported) and EVENT_NEEDS_ATTENTION (wall-clock/round-count, no
+# judgment) — this is an independent small-model *opinion* raised on a
+# per-turn cadence, cheap enough to run continuously. Detection +
+# surfacing only, exactly like EVENT_NEEDS_ATTENTION/EVENT_STALLED: never
+# gates status/review_state/test_state.
+EVENT_LIVENESS_STALL = "liveness_stall"
+@dataclass
+class CommentMarker:
+    event: str
+    fields: dict[str, str]
+_MARKER_RE = re.compile(r"<!--\s*coord:(?P<body>[^>]*?)\s*-->")
+_FIELD_RE = re.compile(r"(\w+)=(\S+)")
+# ── Review-findings block ────────────────────────────────────────────────────
+# The FULL review body, embedded in a completion comment under a parseable
+# marker so a fix worker can recover it from the GitHub message bus on ANY
+# machine (no shared DB required) — keyed by the review assignment id.
+FINDINGS_BEGIN = "coord:review-findings"
+FINDINGS_END = "coord:review-findings-end"
+def format_findings_block(assignment_id: str, verdict: str | None, body: str) -> str:
+    """Render the full review findings as a marked, GitHub-readable block."""
+    v = f" verdict={verdict}" if verdict else ""
+    return (
+        f"<!-- {FINDINGS_BEGIN} assignment={assignment_id}{v} -->\n"
+        f"### Review findings\n\n{body.strip()}\n"
+        f"<!-- {FINDINGS_END} -->"
+    )
+def extract_findings_block(
+    comment_body: str, assignment_id: str
+) -> tuple[str | None, str] | None:
+    """Return ``(verdict, body)`` from a comment carrying the marked findings
+    block for ``assignment_id``, or ``None`` when absent.  ``verdict`` is read
+    from the marker and may be ``None`` if it wasn't recorded."""
+    pat = re.compile(
+        r"<!--\s*" + re.escape(FINDINGS_BEGIN) + r"\s+assignment="
+        + re.escape(assignment_id) + r"(?P<attrs>[^>]*)-->\s*(?P<body>.*?)\s*<!--\s*"
+        + re.escape(FINDINGS_END) + r"\s*-->",
+        re.DOTALL,
+    )
+    m = pat.search(comment_body or "")
+    if not m:
+        return None
+    vm = re.search(r"verdict=(\S+)", m.group("attrs") or "")
+    verdict = vm.group(1) if vm else None
+    body = re.sub(r"^#+\s*Review findings\s*\n+", "", m.group("body").strip(), count=1)
+    body = body.strip()
+    if not body:
+        return None
+    return (verdict, body)
+# ── Milestone Outcome Audit scorecard (#886 Phase 2) ────────────────────────
+# The structured, versioned verdict from a `--audit-of` run (#885), embedded
+# under a parseable marker so ANY machine can recover the full goal-by-goal
+# JSON from the GitHub message bus alone — the same "no shared DB required"
+# design as the review-findings block above.
+AUDIT_BEGIN = "coord:audit-scorecard"
+AUDIT_END = "coord:audit-scorecard-end"
+def format_audit_scorecard(
+    *,
+    assignment_id: str,
+    run_number: int,
+    bottom_line: str,
+    goals: list[dict],
+    diff: dict[str, list[str]] | None = None,
+) -> str:
+    """Render a milestone-audit scorecard: a human-readable table + delta vs
+    the prior run, with the raw goal JSON tucked in a collapsible section so
+    a future agent (or `extract_audit_scorecard`) can recover it exactly."""
+    def _cell(v: object) -> str:
+        return str(v if v is not None else "").replace("|", "\\|").replace("\n", " ")
+    table = ["| Goal | Before | After | Verdict | Evidence |", "|---|---|---|---|---|"]
+    for g in goals:
+        table.append(
+            f"| {_cell(g.get('goal'))} | {_cell(g.get('metric_before'))} | "
+            f"{_cell(g.get('metric_after'))} | {_cell(g.get('verdict'))} | "
+            f"{_cell(g.get('evidence'))} |"
+        )
+    lines = [
+        f"### Milestone outcome audit — run v{run_number}",
+        f"<!-- {AUDIT_BEGIN} assignment={assignment_id} run={run_number} -->",
+        "",
+        f"**Bottom line:** {bottom_line or '(none provided)'}",
+        "",
+        *table,
+    ]
+    if diff and any(diff.get(k) for k in ("closed", "regressed", "still_open", "new")):
+        lines.append("")
+        lines.append(f"**Delta vs run v{run_number - 1}:**")
+        if diff.get("closed"):
+            lines.append(f"- ✅ closed: {', '.join(diff['closed'])}")
+        if diff.get("regressed"):
+            lines.append(f"- ⚠️ regressed: {', '.join(diff['regressed'])}")
+        if diff.get("still_open"):
+            lines.append(f"- still open: {', '.join(diff['still_open'])}")
+        if diff.get("new"):
+            lines.append(f"- new goals: {', '.join(diff['new'])}")
+    lines.append("")
+    lines.append("<details><summary>Structured verdict (JSON)</summary>")
+    lines.append("")
+    lines.append("```json")
+    lines.append(json.dumps(goals, indent=2))
+    lines.append("```")
+    lines.append("")
+    lines.append("</details>")
+    lines.append(f"<!-- {AUDIT_END} -->")
+    return "\n".join(lines)
+def extract_audit_scorecard(comment_body: str) -> dict | None:
+    """Parse a marked audit scorecard back into
+    ``{"assignment_id", "run_number", "bottom_line", "goals"}``, or ``None``
+    if the comment carries no scorecard block. Round-trip counterpart to
+    :func:`format_audit_scorecard`."""
+    pat = re.compile(
+        r"<!--\s*" + re.escape(AUDIT_BEGIN)
+        + r"\s+assignment=(?P<aid>\S+)\s+run=(?P<run>\d+)\s*-->"
+        r"(?P<body>.*?)<!--\s*" + re.escape(AUDIT_END) + r"\s*-->",
+        re.DOTALL,
+    )
+    m = pat.search(comment_body or "")
+    if not m:
+        return None
+    body = m.group("body")
+    bl_m = re.search(r"\*\*Bottom line:\*\*\s*(.+)", body)
+    bottom_line = bl_m.group(1).strip() if bl_m else ""
+    json_m = re.search(r"```json\s*(\[.*?\])\s*```", body, re.DOTALL)
+    try:
+        goals = json.loads(json_m.group(1)) if json_m else []
+    except (TypeError, ValueError):
+        goals = []
+    return {
+        "assignment_id": m.group("aid"),
+        "run_number": int(m.group("run")),
+        "bottom_line": bottom_line,
+        "goals": goals,
+    }
+def _marker(event: str, **fields: str | int | None) -> str:
+    parts = [f"event={event}"]
+    for k, v in fields.items():
+        if v is None or v == "":
+            continue
+        parts.append(f"{k}={v}")
+    return f"<!-- coord:{' '.join(parts)} -->"
+def parse_marker(body: str) -> CommentMarker | None:
+    """Return the first coord marker in a comment body, or None."""
+    m = _MARKER_RE.search(body)
+    if not m:
+        return None
+    raw = m.group("body")
+    fields = dict(_FIELD_RE.findall(raw))
+    event = fields.pop("event", "")
+    if not event:
+        return None
+    return CommentMarker(event=event, fields=fields)
+# ── Unified parse for durable storage (#873) ─────────────────────────────────
+# coord.review posts a differently-shaped header — `<!-- coord:review
+# verdict=... -->` (no `event=` token) — which parse_marker() above doesn't
+# recognise (it requires `event=`). A self-contained regex is duplicated here
+# rather than importing coord.review, to avoid a circular import: github_ops
+# (the #873 capture-at-write choke point) needs coord.state, and coord.review
+# already imports coord.github_ops.
+_REVIEW_MARKER_RE = re.compile(r"<!--\s*coord:review\s+([^>]+?)\s*-->")
+def parse_coord_comment_marker(body: str) -> dict[str, str | None] | None:
+    """Unified marker parse across all coord comment grammars, for the
+    ``issue_comments`` durable mirror (#873).
+    Tries the generic ``coord:event=...`` marker first (covers
+    briefing/completion/failure/stuck/plan/advisory/needs_attention), then
+    falls back to the ``coord:review verdict=...`` header format used by
+    posted review bodies. Returns ``{"event", "assignment_id", "machine",
+    "verdict"}`` (any value may be ``None``), or ``None`` when *body* carries
+    no recognisable coord marker at all.
+    """
+    marker = parse_marker(body)
+    if marker is not None:
+        return {
+            "event": marker.event,
+            "assignment_id": marker.fields.get("assignment"),
+            "machine": marker.fields.get("machine"),
+            "verdict": marker.fields.get("verdict"),
+        }
+    m = _REVIEW_MARKER_RE.search(body or "")
+    if not m:
+        return None
+    fields = dict(_FIELD_RE.findall(m.group(1)))
+    if "verdict" not in fields:
+        return None
+    return {
+        "event": "review",
+        "assignment_id": fields.get("assignment"),
+        "machine": fields.get("reviewer"),
+        "verdict": fields.get("verdict"),
+    }
+def _fmt_files(files: Iterable[str]) -> str:
+    files = list(files)
+    if not files:
+        return "(unspecified)"
+    return ", ".join(f"`{f}`" for f in files)
+def _fmt_duration(seconds: float | None) -> str:
+    if seconds is None:
+        return "—"
+    seconds = int(seconds)
+    if seconds < 60:
+        return f"{seconds}s"
+    m, s = divmod(seconds, 60)
+    if m < 60:
+        return f"{m}m {s}s"
+    h, m = divmod(m, 60)
+    return f"{h}h {m}m"
+def format_briefing(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    briefing: str,
+    files_likely: Iterable[str] = (),
+    do_not_touch: Iterable[tuple[str, str]] = (),
+) -> str:
+    """Build the issue comment posted when an assignment is dispatched.
+    `do_not_touch` is a sequence of (file_path, reason) pairs describing files
+    other workers are currently touching.
+    """
+    marker = _marker(
+        EVENT_BRIEFING,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        issue=issue_number,
+    )
+    lines = [
+        "## Coordinator Assignment",
+        marker,
+        f"**Machine:** {machine_name}",
+        f"**Repo:** {repo_name}",
+        f"**Files:** {_fmt_files(files_likely)}",
+    ]
+    dnt = list(do_not_touch)
+    if dnt:
+        rendered = ", ".join(f"`{path}` ({reason})" for path, reason in dnt)
+        lines.append(f"**Do not touch:** {rendered}")
+    else:
+        lines.append("**Do not touch:** (nothing else in flight)")
+    lines.append("")
+    lines.append("### Briefing")
+    lines.append(briefing.strip() or "(no briefing provided)")
+    return "\n".join(lines)
+def format_completion(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    exit_code: int,
+    duration_seconds: float | None = None,
+    log_path: str | None = None,
+    summary: str = "",
+) -> str:
+    marker = _marker(
+        EVENT_COMPLETION,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        issue=issue_number,
+        exit_code=exit_code,
+    )
+    lines = [
+        "## Coordinator: Assignment Complete",
+        marker,
+        f"**Machine:** {machine_name}",
+        f"**Status:** done",
+        f"**Exit code:** {exit_code}",
+        f"**Duration:** {_fmt_duration(duration_seconds)}",
+    ]
+    if log_path:
+        lines.append(f"**Log:** `{log_path}`")
+    if summary.strip():
+        lines.append("")
+        lines.append("### Summary")
+        lines.append(summary.strip())
+    return "\n".join(lines)
+def format_stuck(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    stuck_message: str,
+) -> str:
+    marker = _marker(
+        EVENT_STUCK,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+    )
+    lines = [
+        marker,
+        f"## ⚠️ Worker STUCK",
+        f"**Machine:** {machine_name}",
+        f"**Assignment:** {assignment_id}",
+        f"**Issue:** #{issue_number}",
+        "",
+        stuck_message.strip(),
+        "",
+        "The worker has stopped and is waiting for guidance. Use:",
+        f"`coord resume-stuck {assignment_id} --guidance \"your answer here\"`",
+    ]
+    return "\n".join(lines)
+def format_needs_attention(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    reason: str,
+    detail: str,
+) -> str:
+    """Format a "needs attention" comment (#846) — a time/round-based signal
+    that an assignment is running long or thrashing, distinct from a
+    worker's self-reported ``STUCK:`` line.
+    *reason* is ``"wall_clock"`` or ``"non_convergence"``; *detail* is a
+    human-readable one-liner (e.g. "running 52m, threshold 45m" or
+    "4 fix/review rounds without a green test + approved review").
+    """
+    marker = _marker(
+        EVENT_NEEDS_ATTENTION,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        reason=reason,
+    )
+    lines = [
+        marker,
+        "## ⏱ Needs attention",
+        f"**Machine:** {machine_name}",
+        f"**Assignment:** {assignment_id}",
+        f"**Issue:** #{issue_number}",
+        f"**Reason:** {'Running too long' if reason == 'wall_clock' else 'Not converging'}",
+        "",
+        detail.strip(),
+        "",
+        "Detection + surfacing only — nothing was killed or reassigned. A "
+        "human should take a look; use `coord log <id>` to see what it's "
+        "doing, or `coord retry`/`coord stop` to intervene.",
+    ]
+    return "\n".join(lines)
+def format_liveness_stall(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    consecutive_blocked: int,
+) -> str:
+    """Format a "liveness auditor" comment (#2048) — *consecutive_blocked*
+    independent per-turn audits in a row judged this worker's latest turn
+    as showing no progress toward the objective.
+    This is a cheap small-model *opinion*, not a correctness check — it
+    complements, and is deliberately weaker than, an adversarial review or
+    the sealed oracle suite. See ``coord/liveness_auditor.py``'s module
+    docstring.
+    """
+    marker = _marker(
+        EVENT_LIVENESS_STALL,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        strikes=consecutive_blocked,
+    )
+    lines = [
+        marker,
+        "## 🐢 Liveness auditor: possible stall",
+        f"**Machine:** {machine_name}",
+        f"**Assignment:** {assignment_id}",
+        f"**Issue:** #{issue_number}",
+        f"**Consecutive BLOCKED verdicts:** {consecutive_blocked}",
+        "",
+        (
+            "An independent, cheap small-model auditor judged this "
+            "worker's last few turns as showing no progress toward the "
+            "objective — repeating itself, confused, or spinning. It saw "
+            "only the objective and each turn's own output, never the "
+            "transcript or the worker's self-reported status."
+        ),
+        "",
+        "This is a tripwire, not a verdict: nothing was killed, gated, or "
+        "reassigned, and no board status changed. It runs continuously "
+        "for pennies and is meant to be wrong sometimes — a human should "
+        "take a look with `coord log <id>` and decide whether to "
+        "intervene.",
+    ]
+    return "\n".join(lines)
+_STALLED_REASON_LABELS = {
+    "review_request_changes_no_fix": "Review requested changes, no fix dispatched",
+    "review_done_no_verdict": "Review finished with no verdict ever captured (#812)",
+    "done_no_review": "Work done, no review ever dispatched",
+    "approved_not_queued": "Approved + tested, but not queued for merge",
+    "merge_conflict_unresolved": "Merge entry stuck in CONFLICT, no fix attempted",
+    "review_failed_no_verdict": "Review worker failed before producing a verdict",
+}
+def format_stalled_pipeline(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    reason: str,
+    detail: str,
+) -> str:
+    """Format a "stalled pipeline row" comment (#1441).
+    *reason* is one of ``"review_request_changes_no_fix"``,
+    ``"done_no_review"``, ``"approved_not_queued"``,
+    ``"merge_conflict_unresolved"``, or ``"review_failed_no_verdict"``
+    (#1584); *detail* is a human-readable one-liner naming the unmet
+    precondition.
+    """
+    marker = _marker(
+        EVENT_STALLED,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        reason=reason,
+    )
+    label = _STALLED_REASON_LABELS.get(reason, reason)
+    lines = [
+        marker,
+        "## 🧊 Pipeline row stalled",
+        f"**Machine:** {machine_name}",
+        f"**Assignment:** {assignment_id}",
+        f"**Issue:** #{issue_number}",
+        f"**Reason:** {label}",
+        "",
+        detail.strip(),
+        "",
+        "Detection + surfacing only — nothing was dispatched automatically. "
+        "This row's auto-loop transition already fired once and won't fire "
+        "again on its own; a human should look at `coord status` and "
+        "decide whether to dispatch a fix/review manually or drop it with "
+        "`coord backlog`.",
+    ]
+    return "\n".join(lines)
+def format_stalled_pipeline_dispatch(
+    *,
+    assignment_id: str,
+    repo_name: str,
+    issue_number: int,
+    reason: str,
+    action_kind: str,
+    action_detail: str,
+) -> str:
+    """Format the #1478 auto-dispatch outcome comment for a stalled row.
+    Posted INSTEAD OF :func:`format_stalled_pipeline`'s diagnostic-only
+    comment when ``pipeline.auto_dispatch_stalled`` is on and
+    ``coord.notify.dispatch_stalled_pipeline_action`` actually dispatched
+    something for this row — posting both would leave a directly
+    contradictory "nothing was dispatched automatically" comment sitting
+    right above this one on the same issue thread.
+    """
+    marker = _marker(
+        EVENT_STALLED,
+        assignment=assignment_id,
+        repo=repo_name,
+        reason=reason,
+        auto_dispatch=action_kind,
+    )
+    label = _STALLED_REASON_LABELS.get(reason, reason)
+    lines = [
+        marker,
+        "## ⚙️ Stalled pipeline row auto-dispatched",
+        f"**Assignment:** {assignment_id}",
+        f"**Issue:** #{issue_number}",
+        f"**Stall reason:** {label}",
+        f"**Action taken:** `{action_kind}`",
+        "",
+        action_detail.strip(),
+        "",
+        "The coordinator's stalled-pipeline sweep (#1478, "
+        "`pipeline.auto_dispatch_stalled`) dispatched the action the "
+        "original auto-loop transition would have taken. This is "
+        "best-effort automation — check `coord status` if the outcome "
+        "looks wrong.",
+    ]
+    return "\n".join(lines)
+def format_failure(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    exit_code: int | None,
+    duration_seconds: float | None = None,
+    log_path: str | None = None,
+    error: str = "",
+) -> str:
+    marker = _marker(
+        EVENT_FAILURE,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        issue=issue_number,
+        exit_code=exit_code if exit_code is not None else "",
+    )
+    lines = [
+        "## Coordinator: Assignment Failed",
+        marker,
+        f"**Machine:** {machine_name}",
+        f"**Status:** failed",
+        f"**Exit code:** {exit_code if exit_code is not None else '—'}",
+        f"**Duration:** {_fmt_duration(duration_seconds)}",
+    ]
+    if log_path:
+        lines.append(f"**Log:** `{log_path}`")
+    if error.strip():
+        lines.append("")
+        lines.append("### Error")
+        lines.append(error.strip())
+    return "\n".join(lines)
+def format_advisory(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    duration_seconds: float | None = None,
+    log_path: str | None = None,
+    reason: str = "",
+) -> str:
+    """Format an advisory comment for a 0-commit clean exit.
+    Distinct from both completion (no code was produced) and failure (the
+    worker exited cleanly — exit_code 0 — so no error occurred).  Human
+    review is needed to decide next steps.
+    """
+    marker = _marker(
+        EVENT_ADVISORY,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        issue=issue_number,
+    )
+    lines = [
+        "## Coordinator: Advisory — Worker Exited With 0 Commits",
+        marker,
+        f"**Machine:** {machine_name}",
+        f"**Status:** advisory",
+        f"**Duration:** {_fmt_duration(duration_seconds)}",
+    ]
+    if log_path:
+        lines.append(f"**Log:** `{log_path}`")
+    lines.append("")
+    lines.append(
+        "The worker exited cleanly (exit code 0) but pushed **no commits**. "
+        "This typically means the feature was already implemented or no change "
+        "was needed. Human review is required to decide the next step."
+    )
+    if reason.strip():
+        lines.append("")
+        lines.append("### Worker note")
+        lines.append(reason.strip())
+    return "\n".join(lines)
+def format_plan(
+    *,
+    assignment_id: str,
+    machine_name: str,
+    repo_name: str,
+    issue_number: int,
+    plan: object,  # coord.plan_parser.WorkerPlan (untyped to avoid circular import)
+    duration_seconds: float | None = None,
+) -> str:
+    """Build the issue comment posted when a plan-only assignment completes.
+    *plan* should be a :class:`coord.plan_parser.WorkerPlan` instance, but the
+    parameter is typed as ``object`` to avoid a circular import — callers that
+    already have the dataclass can pass it directly.
+    """
+    marker = _marker(
+        EVENT_PLAN,
+        assignment=assignment_id,
+        machine=machine_name,
+        repo=repo_name,
+        issue=issue_number,
+    )
+    lines = [
+        "## Coordinator: Implementation Plan",
+        marker,
+        f"**Machine:** {machine_name}",
+        f"**Duration:** {_fmt_duration(duration_seconds)}",
+        "",
+    ]
+    plan_text: str = getattr(plan, "plan", "") or ""
+    files_read: list[str] = getattr(plan, "files_read", []) or []
+    files_modify: list[str] = getattr(plan, "files_modify", []) or []
+    approach: str = getattr(plan, "approach", "") or ""
+    risks: str = getattr(plan, "risks", "") or ""
+    estimate: str = getattr(plan, "estimate", "") or ""
+    if plan_text.strip():
+        lines.append("### Summary")
+        lines.append(plan_text.strip())
+        lines.append("")
+    if files_read:
+        lines.append("### Files Read")
+        lines.append(", ".join(f"`{f}`" for f in files_read))
+        lines.append("")
+    if files_modify:
+        lines.append("### Files to Modify")
+        lines.append(", ".join(f"`{f}`" for f in files_modify))
+        lines.append("")
+    if approach.strip():
+        lines.append("### Approach")
+        lines.append(approach.strip())
+        lines.append("")
+    if risks.strip():
+        lines.append("### Risks")
+        lines.append(risks.strip())
+        lines.append("")
+    if estimate.strip():
+        lines.append("### Estimate")
+        lines.append(estimate.strip())
+    return "\n".join(lines)