coding-os 0.3.23__tar.gz → 0.3.24__tar.gz

{coding_os-0.3.23 → coding_os-0.3.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-os
-Version: 0.3.23
+Version: 0.3.24
 Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
 Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
 License-Expression: Apache-2.0

{coding_os-0.3.23 → coding_os-0.3.24}/coding_os.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-os
-Version: 0.3.23
+Version: 0.3.24
 Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
 Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
 License-Expression: Apache-2.0

{coding_os-0.3.23 → coding_os-0.3.24}/coding_os.egg-info/SOURCES.txt

@@ -100,6 +100,12 @@ src/cli/_init_summary.py
 src/cli/_init_target.py
 src/cli/_init_world.py
 src/cli/_module_rules_cascade.py
+src/cli/_pr_cleanup.py
+src/cli/_pr_inspect.py
+src/cli/_pr_open.py
+src/cli/_pr_publish.py
+src/cli/_pr_reap.py
+src/cli/_pr_shared.py
 src/cli/_render_agents_md.py
 src/cli/_render_ci.py
 src/cli/_render_docker.py
@@ -244,6 +250,7 @@ src/core/graph_os/backends/sqlite_backend.py
 src/core/graph_os/bench/__init__.py
 src/core/graph_os/bench/_baselines.py
 src/core/graph_os/bench/_coverage.py
+src/core/graph_os/bench/_oracle.py
 src/core/graph_os/bench/fixtures.py
 src/core/graph_os/bench/harness.py
 src/core/graph_os/bench/persian_precision.py
@@ -325,6 +332,7 @@ src/core/graph_os/tools/_graph_export_processes.py
 src/core/graph_os/tools/_graph_hygiene.py
 src/core/graph_os/tools/_graph_insights.py
 src/core/graph_os/tools/_graph_lookup.py
+src/core/graph_os/tools/_graph_overview.py
 src/core/graph_os/tools/_graph_paths.py
 src/core/graph_os/tools/_graph_ranking.py
 src/core/graph_os/tools/_graph_read.py
@@ -743,6 +751,9 @@ src/core/thinking_os/_db_pool.py
 src/core/thinking_os/_doc_chunking.py
 src/core/thinking_os/_doc_sources.py
 src/core/thinking_os/_doc_store.py
+src/core/thinking_os/_embeddings_model.py
+src/core/thinking_os/_embeddings_registry.py
+src/core/thinking_os/_embeddings_store.py
 src/core/thinking_os/_formula_signals.py
 src/core/thinking_os/_health_report.py
 src/core/thinking_os/_server_runtime.py

{coding_os-0.3.23 → coding_os-0.3.24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "coding-os"
-version = "0.3.23"
+version = "0.3.24"
 description = "The cognitive operating system that gives AI agents memory, structure, and discipline"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -566,6 +566,9 @@ module = [
     "database",
     "_db_paths",
     "_db_migrations",
+    "_embeddings_model",
+    "_embeddings_registry",
+    "_embeddings_store",
     "_server_runtime",
     "_agent_markers",
     "_board_bridge",

{coding_os-0.3.23 → coding_os-0.3.24}/src/cli/_graph_cli_query.py

@@ -253,6 +253,26 @@ def register_query(cli: click.Group) -> None:
         _, tools = _open_backend()
         _json_echo(tools.cos_graph_test_gap(kind=kind, top=top), pretty=pretty)
 
+    @cli.command(name="graph-overview")
+    @click.option("--max-modules", default=40, type=int)
+    @click.option("--min-edge-weight", default=1, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_overview(max_modules, min_edge_weight, pretty):
+        """Module-level architecture map — directories as weighted nodes."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_overview(max_modules=max_modules, min_edge_weight=min_edge_weight),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-stale-files")
+    @click.option("--top", default=100, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_stale_files(top, pretty):
+        """Indexed files carrying a git commit newer than the index pass."""
+        _, tools = _open_backend()
+        _json_echo(tools.cos_graph_stale_files(top=top), pretty=pretty)
+
     @cli.command(name="graph-dead-code")
     @click.option("--kind", default="")
     @click.option("--top", default=50, type=int)

coding_os-0.3.24/src/cli/_pr_cleanup.py

@@ -0,0 +1,154 @@
+"""Reclaiming one finished worktree: cleanup.
+
+Private module of pr_commands.py — import through that facade.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+try:
+    import fcntl
+except ImportError:  # non-POSIX (Windows) — the reaper lock degrades to a no-op
+    fcntl = None  # type: ignore[assignment]
+
+import click
+
+from cli import _pr_shared as _shared
+from cli._pr_shared import (
+    pr_group,
+)
+
+
+def _pr_state(repo: str, branch: str) -> str:
+    # "merged" | "closed" | "open" | "none" | "unknown" — drives the cleanup
+    # merge-gate so an open PR's worktree isn't destroyed mid-flight.
+    if not _shared._gh_ready():
+        return "unknown"
+    listing = _shared._run(
+        ["gh", "pr", "list", "--head", branch, "--state", "all", "--json", "state,mergedAt"],
+        cwd=repo,
+    )
+    if listing.returncode != 0:
+        return "unknown"
+    try:
+        prs = json.loads(listing.stdout or "[]")
+    except json.JSONDecodeError:
+        return "unknown"
+    if not prs:
+        return "none"
+    if prs[0].get("mergedAt"):
+        return "merged"
+    return str(prs[0].get("state", "")).lower() or "unknown"
+
+
+@pr_group.command(
+    "cleanup",
+    help="Remove the worktree + delete the branch + prune (merge-gated; --force to override).",
+)
+@click.option("--task", "task_id", default=None)
+@click.option("--adhoc", is_flag=True)
+@click.option("--repo", "repo_opt", default=None)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Remove even if the PR is open / the branch is unpushed (human override).",
+)
+@click.option("--json", "as_json", is_flag=True)
+def pr_cleanup(
+    task_id: str | None, adhoc: bool, repo_opt: str | None, force: bool, as_json: bool
+) -> None:
+    repo = _shared._resolve_repo(repo_opt)
+    session = _shared._agent_session()
+    task_slug = "adhoc" if adhoc else _shared._sanitize(task_id) if task_id else None
+    if task_slug is None:
+        raise click.ClickException("cos pr cleanup needs --task <id> or --adhoc.")
+    wt, branch = _shared._resolve_worktree(repo, task_slug, session)
+    _preserved_bundle: str | None = None  # set when a drifted/peer dirty tree is bundled
+
+    # Merge-gate: only destroy the worktree+branch once work has landed
+    # (merged/closed) or is fully on origin; --force is the human override.
+    if not force:
+        # Ownership gate (review finding 2): under session drift the single-candidate
+        # fallback in _resolve_worktree can resolve a live PEER's worktree (same task
+        # slug, different session) — destroying it would wipe active peer work. Refuse
+        # only when the owner session is provably LIVE; a drifted-gone ("unknown") or
+        # dead ("offline") owner still cleans up, preserving the drift path.
+        owner_session = branch.rsplit("/", 1)[-1]
+        if owner_session != session and _shared._session_state(owner_session, repo) == "live":
+            _shared._emit(
+                {
+                    "removed": False,
+                    "branch": branch,
+                    "owner_session": owner_session,
+                    "action": "worktree belongs to another live session — not removing; its owner or 'cos pr reap' will GC it, or re-run with --force",
+                },
+                as_json,
+            )
+            sys.exit(1)
+        state = _pr_state(repo, branch)
+        if state == "open":
+            _shared._emit(
+                {
+                    "removed": False,
+                    "branch": branch,
+                    "pr_state": "open",
+                    "action": "PR still open — not removing; merge/close it, or re-run with --force",
+                },
+                as_json,
+            )
+            sys.exit(1)
+        recoverable = _shared._branch_recoverable(repo, branch, _shared._integration_branch(repo))
+        # Unpushed work with no landing PR: refuse and tell the user to submit, keeping
+        # the branch intact — friendlier than bundle+delete for an interactive cleanup,
+        # and the reaper is the GC path for a genuinely dead owner.
+        if state in {"none", "unknown"} and not recoverable:
+            _shared._emit(
+                {
+                    "removed": False,
+                    "branch": branch,
+                    "pr_state": state,
+                    "action": "branch has local commits not on origin — 'cos pr submit' first, or --force to discard",
+                },
+                as_json,
+            )
+            sys.exit(1)
+        # Preserve-before-destroy net ( H): for any OTHER state (merged/closed)
+        # a branch that is unrecoverable (squash-merge, or extra local commits not on
+        # origin) or has a dirty tree must be bundled before `branch -D`. The old code
+        # bundled only a DIRTY drifted tree, so a CLEAN-tree merged branch with unpushed
+        # commits was discarded with NO bundle. A FAILED status reads as "maybe dirty"
+        # so a transient git error can't pass as clean and wipe work (review finding F).
+        # Mirrors _reap_one's safety arm — cleanup and reap no longer diverge.
+        _status = _shared._git(["status", "--porcelain"], cwd=wt)
+        dirty = _status.returncode != 0 or bool(_status.stdout.strip())
+        if not recoverable or dirty:
+            _preserved_bundle = _shared._preserve_reaped(repo, wt, branch)
+            if _preserved_bundle is None:
+                _shared._emit(
+                    {
+                        "removed": False,
+                        "branch": branch,
+                        "pr_state": state,
+                        "action": "branch has unpushed commits or an uncommitted tree and preservation failed — recover it manually, or --force to discard.",
+                    },
+                    as_json,
+                )
+                sys.exit(1)
+
+    _shared._git(["worktree", "unlock", str(wt)], cwd=repo)  # release the pr-mode live-lock
+    removed_wt = _shared._git(["worktree", "remove", "--force", str(wt)], cwd=repo).returncode == 0
+    deleted_branch = _shared._git(["branch", "-D", branch], cwd=repo).returncode == 0
+    _shared._git(["worktree", "prune"], cwd=repo)
+    _shared._heal_budget_clear(repo, branch)  # branch is done — drop its heal budget (finding 8)
+    _shared._emit(
+        {
+            "worktree_removed": removed_wt,
+            "branch_deleted": deleted_branch,
+            "worktree": str(wt),
+            "forced": force,
+            "preserved_bundle": _preserved_bundle,
+        },
+        as_json,
+    )

coding_os-0.3.24/src/cli/_pr_inspect.py

@@ -0,0 +1,394 @@
+"""Looking at work in flight: status, triage, conflicts.
+
+Private module of pr_commands.py — import through that facade.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+try:
+    import fcntl
+except ImportError:  # non-POSIX (Windows) — the reaper lock degrades to a no-op
+    fcntl = None  # type: ignore[assignment]
+
+import click
+
+from cli import _pr_shared as _shared
+from cli._pr_shared import (
+    pr_group,
+)
+
+
+@pr_group.command("status", help="List this repo's pr-mode worktrees, branches, and open PRs.")
+@click.option("--repo", "repo_opt", default=None)
+@click.option(
+    "--branch",
+    default=None,
+    help="Report one agent branch's CI rollup (merged|red|pending|review-required|passing|passing-unarmed|closed|none) — the driver-loop signal.",
+)
+@click.option("--json", "as_json", is_flag=True)
+def pr_status(repo_opt: str | None, branch: str | None, as_json: bool) -> None:
+    repo = _shared._resolve_repo(repo_opt)
+    if branch:
+        # Single-branch CI signal the pr-mode-driver skill branches on.
+        _shared._emit({"branch": branch, "ci_rollup": _pr_ci_rollup(repo, branch)}, as_json)
+        return
+    wt_root = _shared._worktree_root(repo)
+    worktrees = []
+    if wt_root.is_dir():
+        worktrees = sorted(p.name for p in wt_root.iterdir() if p.is_dir())
+    branches = [
+        b.strip().lstrip("* ").strip()
+        for b in _shared._git_out(["branch", "--list", "agents/*"], cwd=repo).splitlines()
+        if b.strip()
+    ]
+    pr_rows: list[dict] = []
+    if _shared._gh_ready():
+        out = _shared._run(
+            [
+                "gh",
+                "pr",
+                "list",
+                "--search",
+                "head:agents/",
+                "--json",
+                "number,headRefName,state,mergedAt,statusCheckRollup,isDraft,autoMergeRequest,reviewDecision",
+            ],
+            cwd=repo,
+        )
+        if out.returncode == 0:
+            try:
+                pr_rows = json.loads(out.stdout or "[]")
+            except json.JSONDecodeError:
+                pr_rows = []
+    open_prs = ",".join(f"#{r.get('number')}:{r.get('headRefName')}" for r in pr_rows)
+    ci_rollup = ",".join(f"{r.get('headRefName')}={_rollup_state(r)}" for r in pr_rows)
+    _shared._emit(
+        {
+            "worktree_root": str(wt_root),
+            "worktrees": ",".join(worktrees) or "(none)",
+            "agent_branches": ",".join(branches) or "(none)",
+            "open_prs": open_prs or "(none/gh unavailable)",
+            "ci_rollup": ci_rollup or "(none)",
+        },
+        as_json,
+    )
+
+
+def _agent_worktrees(repo: str) -> dict[str, Path]:
+    # Map each live agents/* branch → its worktree path from `git worktree list`.
+    # Only branches with a worktree appear, so this naturally scopes to the
+    # currently-checked-out (i.e. concurrently-active) agents.
+    result: dict[str, Path] = {}
+    cur: str | None = None
+    for line in _shared._git_out(["worktree", "list", "--porcelain"], cwd=repo).splitlines():
+        if line.startswith("worktree "):
+            cur = line[len("worktree ") :].strip()
+        elif line.startswith("branch ") and cur:
+            name = _shared._unqualify_head(line[len("branch ") :].strip())
+            if name.startswith("agents/"):
+                result[name] = Path(cur)
+    return result
+
+
+def _changed_files(repo: str, branch: str, integration: str, wt: Path | None) -> set[str]:
+    # The branch's "touched files" = committed diff since it forked the integration
+    # line (merge-base, so a moving integration head doesn't distort it) UNION the
+    # worktree's still-uncommitted paths (earliest possible pre-detection signal).
+    files: set[str] = set()
+    base = _shared._git_out(["merge-base", integration, branch], cwd=repo) or integration
+    for line in _shared._git_out(
+        ["diff", "--name-only", f"{base}..{branch}"], cwd=repo
+    ).splitlines():
+        if line.strip():
+            files.add(line.strip())
+    if wt is not None and (wt / ".git").exists():
+        for line in _shared._git_out(["status", "--porcelain"], cwd=wt).splitlines():
+            path = line[3:].strip()
+            if " -> " in path:  # rename entry: 'old -> new' — the new path is what's edited
+                path = path.split(" -> ", 1)[1].strip()
+            path = path.strip('"')  # porcelain quotes paths containing special chars
+            if path:
+                files.add(path)
+    return files
+
+
+@pr_group.command(
+    "triage",
+    help="Ranked digest of all open agents/* PRs (ci + review + conflict + age) — review the highest-value, lowest-risk first.",
+)
+@click.option("--repo", "repo_opt", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def pr_triage(repo_opt: str | None, as_json: bool) -> None:
+    repo = _shared._resolve_repo(repo_opt)
+    if not _shared._gh_ready():
+        _shared._emit(
+            {
+                "open": 0,
+                "quick_merge": 0,
+                "prs": [],
+                "action": "gh unavailable — cannot triage open PRs",
+            },
+            as_json,
+        )
+        return
+    out = _shared._run(
+        [
+            "gh",
+            "pr",
+            "list",
+            "--state",
+            "open",
+            "--search",
+            "head:agents/",
+            "--json",
+            "number,headRefName,state,mergedAt,statusCheckRollup,isDraft,autoMergeRequest,"
+            "reviewDecision,mergeable,createdAt",
+            "--limit",
+            "100",
+        ],
+        cwd=repo,
+    )
+    rows: list[dict] = []
+    if out.returncode == 0:
+        try:
+            rows = json.loads(out.stdout or "[]")
+        except json.JSONDecodeError:
+            rows = []
+    agent_rows = [r for r in rows if str(r.get("headRefName", "")).startswith("agents/")]
+    entries = sorted(
+        (_triage_entry(r) for r in agent_rows), key=lambda e: (e["rank"], e["created_at"])
+    )
+    quick = sum(1 for e in entries if e["category"] == "quick-merge")
+    if not entries:
+        _shared._emit(
+            {
+                "open": 0,
+                "quick_merge": 0,
+                "prs": [],
+                "action": "no open agent PRs — nothing to triage",
+            },
+            as_json,
+        )
+        return
+    if as_json:
+        _shared._emit(
+            {
+                "open": len(entries),
+                "quick_merge": quick,
+                "prs": entries,
+                "action": "review in listed order; quick-merge rows are green + conflict-free + no required review",
+            },
+            as_json,
+        )
+        return
+    lines = [f"{len(entries)} open agent PR(s) — review in this order ({quick} safe quick-merge):"]
+    for e in entries:
+        flag = "  ✅ quick-merge" if e["category"] == "quick-merge" else ""
+        lines.append(
+            f"  #{e['number']} {e['branch']} — {e['category']} "
+            f"(ci={e['ci_rollup']}, review_required={e['review_required']}, conflict={e['conflict']}){flag}"
+        )
+    lines.append(
+        "Tip: to leave the hot path entirely, set autonomy_level=auto_merge with a required check "
+        "(docs/playbooks/pr-mode-ci-economics.md)."
+    )
+    click.echo("\n".join(lines))
+
+
+@pr_group.command(
+    "conflicts",
+    help="Advisory: which live peer agent branch also edits your files (early-warning before a land-time conflict).",
+)
+@click.option(
+    "--branch", default=None, help="Target agent branch (default: the current worktree's HEAD)."
+)
+@click.option("--repo", "repo_opt", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def pr_conflicts(branch: str | None, repo_opt: str | None, as_json: bool) -> None:
+    repo = _shared._resolve_repo(repo_opt)
+    integration = _shared._integration_branch(repo)
+    worktrees = _agent_worktrees(repo)
+    target = branch or _shared._git_out(["rev-parse", "--abbrev-ref", "HEAD"], cwd=repo)
+    if not target.startswith("agents/"):
+        raise click.ClickException(
+            "not on an agents/* branch — pass --branch <agents/...> or run from inside an agent worktree."
+        )
+    target_files = _changed_files(repo, target, integration, worktrees.get(target))
+    overlaps: list[dict] = []
+    for peer, peer_wt in sorted(worktrees.items()):
+        if peer == target:
+            continue
+        shared = sorted(target_files & _changed_files(repo, peer, integration, peer_wt))
+        if shared:
+            overlaps.append({"branch": peer, "files": shared})
+    # Advisory ONLY — overlap is a heads-up, never a block: two agents may legitimately
+    # touch one file in different places; the rebase-at-submit + merge queue catch a
+    # real conflict at land. Always exit 0.
+    _shared._emit(
+        {
+            "branch": target,
+            "changed_files": len(target_files),
+            "conflicts": overlaps
+            if as_json
+            else ("; ".join(f"{o['branch']}={','.join(o['files'])}" for o in overlaps) or "(none)"),
+            "advisory": (
+                "peer overlap — coordinate or expect a rebase at land"
+                if overlaps
+                else "no peer overlap"
+            ),
+        },
+        as_json,
+    )
+
+
+def _rollup_state(pr: dict) -> str:
+    # merged|red|queued|pending|review-required|passing|passing-unarmed|closed|none — one
+    # CI signal distilled from gh's statusCheckRollup (+ a GraphQL mergeQueueEntry probe
+    # injected by _pr_ci_rollup) for the autonomous driver loop.
+    if pr.get("mergedAt") or str(pr.get("state", "")).upper() == "MERGED":
+        return "merged"
+    if str(pr.get("state", "")).upper() == "CLOSED":
+        return "closed"
+    checks = pr.get("statusCheckRollup") or []
+    bad = {"FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"}
+    waiting = {"IN_PROGRESS", "QUEUED", "PENDING", "WAITING", "REQUESTED", "EXPECTED"}
+
+    def fields(
+        check: dict,
+    ) -> set[str]:  # CheckRun uses conclusion/status; StatusContext uses state
+        return {str(check.get(k) or "").upper() for k in ("conclusion", "status", "state")}
+
+    if any(bad & fields(c) for c in checks):
+        return "red"
+    # Merge-queue membership (GraphQL mergeQueueEntry; gh pr view --json cannot supply it,
+    # so _pr_ci_rollup injects it). A queued PR's merge_group checks read as `waiting`
+    # below, so this MUST precede the waiting/no-checks arms — the driver waits on the
+    # queue, never re-submits. UNMERGEABLE = the queue will eject it → red, so only this
+    # PR is healed while followers keep merging. Absent entry → byte-unchanged (no queue).
+    mq_state = str((pr.get("mergeQueueEntry") or {}).get("state") or "").upper()
+    if mq_state == "UNMERGEABLE":
+        return "red"
+    if mq_state:  # QUEUED | AWAITING_CHECKS | MERGEABLE | LOCKED — in the queue, just wait
+        return "queued"
+    if not checks:
+        return "pending"
+    if any(waiting & fields(c) for c in checks):
+        return "pending"
+    # Green checks — but a required review (branch protection / ruleset / CODEOWNERS)
+    # still blocks merge until a human approves. Distinct from passing-unarmed so the
+    # driver STOPs for an approval instead of spinning on an auto-merge that has been
+    # armed but can never fire while the review gate is open.
+    if str(pr.get("reviewDecision") or "").upper() in {"REVIEW_REQUIRED", "CHANGES_REQUESTED"}:
+        return "review-required"
+    # Green — but only "passing" (auto-merge will land it) when auto-merge is armed
+    # AND the PR isn't a draft; else "passing-unarmed" so the driver STOPs for a human
+    # merge from the signal alone, never from a remembered submit merge_status.
+    if pr.get("isDraft") or not pr.get("autoMergeRequest"):
+        return "passing-unarmed"
+    return "passing"
+
+
+def _pr_ci_rollup(repo: str, branch: str) -> str:
+    if not _shared._gh_ready():
+        return "unknown"
+    out = _shared._run(
+        [
+            "gh",
+            "pr",
+            "view",
+            branch,
+            "--json",
+            "number,state,mergedAt,statusCheckRollup,isDraft,autoMergeRequest,reviewDecision",
+        ],
+        cwd=repo,
+    )
+    if out.returncode != 0:
+        return "none"  # no PR for this branch (or gh error) → driver opens/submits
+    try:
+        pr = json.loads(out.stdout or "{}")
+    except json.JSONDecodeError:
+        return "unknown"
+    if not pr:
+        return "none"
+    state = _rollup_state(pr)
+    # A PR only enters the merge queue once green/running, so probe mergeQueueEntry only
+    # for the non-final verdicts — a merged/closed/red/review-required result is already
+    # authoritative, and skipping the probe there means a repo with NO merge queue makes
+    # zero extra calls for them (byte-unchanged). _merge_queue_entry fails open to {}.
+    if state in {"pending", "passing", "passing-unarmed"}:
+        entry = _merge_queue_entry(repo, pr.get("number"))
+        if entry:
+            pr["mergeQueueEntry"] = entry
+            return _rollup_state(pr)
+    return state
+
+
+def _merge_queue_entry(repo: str, number: int | None) -> dict:
+    # gh pr view --json has no mergeQueueEntry field (gh 2.95), so read it via GraphQL —
+    # gh resolves {owner}/{repo} from the repo's remote. Returns {} (not queued / no queue
+    # configured / gh error) so _rollup_state stays byte-unchanged where no queue exists.
+    if not number or not _shared._gh_ready():
+        return {}
+    out = _shared._run(
+        [
+            "gh",
+            "api",
+            "graphql",
+            "-F",
+            "owner={owner}",
+            "-F",
+            "name={repo}",
+            "-F",
+            f"number={int(number)}",
+            "-f",
+            "query=query($owner:String!,$name:String!,$number:Int!){"
+            "repository(owner:$owner,name:$name){pullRequest(number:$number){"
+            "mergeQueueEntry{state position}}}}",
+        ],
+        cwd=repo,
+    )
+    if out.returncode != 0:
+        return {}
+    try:
+        data = json.loads(out.stdout or "{}")
+    except json.JSONDecodeError:
+        return {}
+    pull = ((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {}
+    return pull.get("mergeQueueEntry") or {}
+
+
+def _triage_entry(pr: dict) -> dict:
+    # One ranked triage row for an open agents/* PR. Rank orders the human's
+    # review queue to minimise time-to-unblock: safe quick-merges first (just
+    # click merge), then the ones needing a real review, then conflict/red (need
+    # work), then CI still running (no human action yet). created_at breaks ties
+    # oldest-first so the backlog drains FIFO.
+    rollup = _rollup_state(pr)  # already folds a blocking reviewDecision into "review-required"
+    conflict = str(pr.get("mergeable") or "").upper() == "CONFLICTING"
+    review_required = rollup == "review-required"
+    green = rollup in ("passing", "passing-unarmed")
+    if green and not conflict:
+        category, rank = "quick-merge", 0  # green + clean + no required review → safe one-click
+    elif review_required and not conflict:
+        category, rank = "needs-review", 1
+    elif conflict:
+        category, rank = "conflict", 2  # needs a rebase before it can land
+    elif rollup == "red":
+        category, rank = "red", 3
+    elif rollup in ("pending", "queued"):
+        category, rank = "waiting", 4
+    else:
+        category, rank = rollup, 5
+    return {
+        "rank": rank,
+        "category": category,
+        "branch": pr.get("headRefName", ""),
+        "number": pr.get("number"),
+        "ci_rollup": rollup,
+        "review_required": review_required,
+        "conflict": conflict,
+        "created_at": pr.get("createdAt", ""),
+    }