agentshore 0.3.2__py3-none-any.whl

agentshore/__init__.py

@@ -0,0 +1,10 @@
+"""AgentShore — RL-based multi-agent coding orchestrator."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agentshore")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

agentshore/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running as `python -m agentshore`."""
+
+from __future__ import annotations
+
+from agentshore.cli import main
+
+main()

agentshore/agents/__init__.py

@@ -0,0 +1,14 @@
+"""Agent manager — lifecycle and CLI subprocess management."""
+
+from __future__ import annotations
+
+from agentshore.agents.capabilities import AGENT_CAPABILITIES
+from agentshore.agents.handle import AgentHandle, AgentInvocationResult
+from agentshore.agents.manager import AgentManager
+
+__all__ = [
+    "AGENT_CAPABILITIES",
+    "AgentHandle",
+    "AgentInvocationResult",
+    "AgentManager",
+]

agentshore/agents/_jsonl.py

@@ -0,0 +1,117 @@
+"""Shared JSONL / usage-accounting primitives for the CLI agent adapters.
+
+The CLI agents (Claude Code, Codex, Gemini, Grok) all emit JSONL on stdout and
+share the same token-usage bookkeeping. These primitives used to live in
+``cli_agent``; ``cli_grok`` imported them from there while ``cli_agent``
+lazily imported ``cli_grok`` back — a circular edge that forced two
+lazy-import wrappers (issue: TNQA finding #6). Hoisting the shared pieces into
+this leaf module breaks the cycle: both adapters import from here, and neither
+imports the other for these helpers.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+@dataclass(frozen=True, slots=True)
+class _UsageTotals:
+    tokens_in: int = 0
+    tokens_out: int = 0
+    cached_tokens_in: int = 0
+    cache_write_tokens_in: int = 0
+    turn_count: int = 0
+    max_turn_input_tokens: int = 0
+
+
+def _iter_json_events(raw: str) -> Iterator[dict[str, object]]:
+    """Yield each non-blank, JSON-decodable line of *raw* as a dict event.
+
+    The CLI agents all emit JSONL on stdout; this is the single scan loop they
+    share (skip blank lines, ``json.loads``, drop ``JSONDecodeError`` and
+    non-dict payloads) so the per-format parsers only express their own event
+    semantics.
+    """
+    for line in map(str.strip, raw.splitlines()):
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(event, dict):
+            yield event
+
+
+def _usage_totals_from_dict(
+    usage: dict[str, object], *, input_includes_cache: bool
+) -> _UsageTotals:
+    total_usage = usage.get("total_token_usage")
+    last_usage = usage.get("last_token_usage")
+    turn_usage: dict[str, object] | None = None
+    if isinstance(total_usage, dict):
+        if isinstance(last_usage, dict):
+            turn_usage = last_usage
+        usage = total_usage
+        input_includes_cache = True
+    elif isinstance(last_usage, dict):
+        usage = last_usage
+        turn_usage = last_usage
+        input_includes_cache = True
+
+    input_tokens = _first_int(usage, "input_tokens")
+    cache_read_tokens = _safe_int(usage.get("cached_input_tokens")) + _safe_int(
+        usage.get("cache_read_input_tokens")
+    )
+    cache_write_tokens = _first_int(usage, "cache_creation_input_tokens")
+    output_tokens = _first_int(usage, "output_tokens")
+    reasoning_tokens = _first_int(usage, "reasoning_output_tokens")
+
+    tokens_in = input_tokens if input_includes_cache else input_tokens + cache_read_tokens
+    if not input_includes_cache:
+        tokens_in += cache_write_tokens
+
+    tokens_out = output_tokens if output_tokens > 0 else reasoning_tokens
+    max_turn_input_tokens = _safe_int(turn_usage.get("input_tokens")) if turn_usage else tokens_in
+    return _UsageTotals(
+        tokens_in=tokens_in,
+        tokens_out=tokens_out,
+        cached_tokens_in=cache_read_tokens,
+        cache_write_tokens_in=cache_write_tokens,
+        max_turn_input_tokens=max_turn_input_tokens,
+    )
+
+
+def _max_usage(left: _UsageTotals, right: _UsageTotals) -> _UsageTotals:
+    return _UsageTotals(
+        tokens_in=max(left.tokens_in, right.tokens_in),
+        tokens_out=max(left.tokens_out, right.tokens_out),
+        cached_tokens_in=max(left.cached_tokens_in, right.cached_tokens_in),
+        cache_write_tokens_in=max(left.cache_write_tokens_in, right.cache_write_tokens_in),
+        turn_count=max(left.turn_count, right.turn_count),
+        max_turn_input_tokens=max(left.max_turn_input_tokens, right.max_turn_input_tokens),
+    )
+
+
+def _first_int(values: dict[str, object], *keys: str) -> int:
+    for key in keys:
+        parsed = _safe_int(values.get(key))
+        if parsed:
+            return parsed
+    return 0
+
+
+def _safe_int(value: object) -> int:
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int | float | str):
+        try:
+            return int(value)
+        except ValueError:
+            return 0
+    return 0

agentshore/agents/_selection.py

@@ -0,0 +1,247 @@
+"""Agent selection helpers — pure rule chain for the AgentManager.
+
+Rule chain (applied in order):
+  0a. Required-id pin (hard): if ``target_agent_id`` is set, narrow to that
+      single handle. Used by the resolver to pin code-review dispatch to a
+      specific agent whose GH identity has been verified upstream.
+  0b. Required-type pin (hard): if ``target_agent_type`` is set (and no id pin),
+      narrow to that type. Used by ``instantiate_agent`` and similar
+      type-specific plays.
+  1. Anti-confirmation bias (hard): exclude the PR author from CodeReview.
+     QA runs against the merged trunk and has no anti-confirmation; any
+     can_test agent may execute it.
+  2. Exclude list (hard): drop agent types listed in ``preferences.exclude``
+     for this play type.
+  3. Tier eligibility (hard): drop agents whose ``model_tier`` isn't in the
+     allowed set for this play type. Small tier is blocked from any coding
+     or strategic play; large tier is blocked from cheap mechanical plays
+     where the play is explicitly tier-limited.
+  4. AntiConfirmationViolation if no candidates remain after hard filters.
+  5. Branch exposure affinity (soft): promote agents with prior exposure to *branch*.
+  6. Type affinity (soft): promote agents whose type matches
+     ``preferences.affinity`` for this play type.
+  7. Tier cost (soft): prefer cheaper eligible tiers when affinity is tied.
+  8. Least-busy tiebreaker: sort by ascending task history length.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import structlog
+
+from agentshore.agents.model_tiers import DEFAULT_MODEL_TIER
+from agentshore.errors import AntiConfirmationViolation
+from agentshore.identity_names import same_identity
+from agentshore.state import AgentStatus, PlayType, is_agent_circuit_broken
+
+if TYPE_CHECKING:
+    from agentshore.agents.handle import AgentHandle
+    from agentshore.config import AgentPreferencesConfig
+
+_logger = structlog.get_logger(__name__)
+
+_REVIEW_PLAYS: frozenset[PlayType] = frozenset({PlayType.CODE_REVIEW})
+
+# Per-play tier eligibility. Plays not listed here accept any tier.
+# Three bands:
+#   - Cheap mechanical work (small ∪ medium): browser checks and
+#     merging already-approved PRs.
+#   - Universal (small ∪ medium ∪ large): cleanup — it's the bootstrap
+#     first-play when the backlog is large, and at that moment only the
+#     large agent has spawned. Excluding large here used to cause the
+#     bootstrap-cleanup to get skip:staffing'd on every fresh open-stocks-
+#     mcp session (seen 2026-05-22). Per the broad-bands philosophy let
+#     PPO learn tier affinity rather than pre-committing.
+#   - Coding & strategic work (medium ∪ large): anything that writes code,
+#     restructures local work, or interprets test failures. Small is too
+#     risky for downstream cost.
+#   - Heavyweight strategic / validation (large only): seed/design audits,
+#     final QA, and global calibration where medium's judgement isn't trusted
+#     to set or certify the trajectory.
+# Medium is the universal fallback for the first three bands.
+_PLAY_ALLOWED_TIERS: dict[PlayType, frozenset[str]] = {
+    PlayType.CLEANUP: frozenset({"small", "medium", "large"}),
+    PlayType.MERGE_PR: frozenset({"small", "medium"}),
+    # Medium ∪ large — coding & strategic
+    PlayType.ISSUE_PICKUP: frozenset({"medium", "large"}),
+    PlayType.UNBLOCK_PR: frozenset({"large", "medium"}),
+    PlayType.CODE_REVIEW: frozenset({"medium", "large"}),
+    PlayType.REFINE_TASK_BREAKDOWN: frozenset({"medium", "large"}),
+    PlayType.RUN_QA: frozenset({"large"}),
+    PlayType.WRITE_IMPLEMENTATION_PLAN: frozenset({"large"}),
+    PlayType.SYSTEMATIC_DEBUGGING: frozenset({"medium", "large"}),
+    # Large only — beads/design-doc audits and final validation.
+    PlayType.SEED_PROJECT: frozenset({"large"}),
+    PlayType.DESIGN_AUDIT: frozenset({"large"}),
+    PlayType.GROOM_BACKLOG: frozenset({"medium", "large"}),
+    PlayType.CALIBRATE_ALIGNMENT: frozenset({"large"}),
+    # RECONCILE_STATE — log-parse + targeted local remediation. Doesn't need
+    # large-tier reasoning; medium suffices and is cheaper when it fires.
+    PlayType.RECONCILE_STATE: frozenset({"medium", "large"}),
+}
+
+
+def allowed_tiers_for(play_type: PlayType) -> frozenset[str] | None:
+    """Return the allowed tier set for *play_type*, or None if unrestricted."""
+    return _PLAY_ALLOWED_TIERS.get(play_type)
+
+
+def select_agent_for(
+    play_type: PlayType,
+    handles: dict[str, AgentHandle],
+    *,
+    pr_github_author: str | None = None,
+    branch_exposure: dict[str, str] | None = None,
+    preferences: AgentPreferencesConfig | None = None,
+    branch: str | None = None,
+    required_agent_type: str | None = None,
+    required_agent_id: str | None = None,
+) -> AgentHandle:
+    """Return the best available handle for *play_type* using the rule chain.
+
+    Raises ``AntiConfirmationViolation`` if all candidates are blocked by
+    hard constraints (anti-confirmation or exclude rules).
+
+    Raises ``AntiConfirmationViolation`` (with a distinct message) if there
+    are no IDLE agents at all.
+    """
+    branch_exposure = branch_exposure or {}
+
+    # -- Step 0: pool of IDLE handles ----------------------------------------
+    candidates: list[AgentHandle] = [h for h in handles.values() if h.status == AgentStatus.IDLE]
+
+    if not candidates:
+        raise AntiConfirmationViolation("No IDLE agents available for selection")
+
+    # -- Step 0a: required-id pin (resolver-chosen reviewer) -----------------
+    # The resolver picks a specific agent for code_review based on GH identity.
+    # When that handle is no longer IDLE (raced with another dispatch), the
+    # play is requeued by the executor — we don't silently fall through to a
+    # different agent that might violate the identity invariant.
+    if required_agent_id is not None:
+        candidates = [h for h in candidates if h.agent_id == required_agent_id]
+        if not candidates:
+            raise AntiConfirmationViolation(f"Pinned agent {required_agent_id!r} is no longer IDLE")
+
+    # -- Step 0b: required-type constraint (instantiate_agent and similar) ---
+    elif required_agent_type is not None:
+        candidates = [h for h in candidates if h.agent_type.value == required_agent_type]
+        if not candidates:
+            raise AntiConfirmationViolation(
+                f"No IDLE agents of required type {required_agent_type!r} available"
+            )
+
+    initial_count = len(candidates)
+
+    # Track which rule eliminated each candidate. Order of keys reflects
+    # filter precedence so a single log line reveals the dominant blocker.
+    eliminated: dict[str, list[str]] = {
+        "anti_confirmation": [],
+        "exclude": [],
+        "tier": [],
+    }
+
+    # -- Step 1: anti-confirmation hard filter --------------------------------
+    # CODE_REVIEW only: block any agent whose GH identity matches the PR author.
+    # QA runs against the merged trunk; any can_test agent is eligible.
+    # When pr_github_author is None (unknown — pre-session PR not yet refreshed),
+    # all candidates pass here and the executor's identity check acts as backstop.
+    blocked_ids: set[str] = set()
+
+    if play_type in _REVIEW_PLAYS and pr_github_author is not None:
+        for h in candidates:
+            if same_identity(h.github_identity, pr_github_author):
+                blocked_ids.add(h.agent_id)
+
+    survivors: list[AgentHandle] = []
+    for h in candidates:
+        if h.agent_id in blocked_ids:
+            eliminated["anti_confirmation"].append(h.agent_id)
+        else:
+            survivors.append(h)
+    candidates = survivors
+
+    # -- Step 2: exclude list hard filter ------------------------------------
+    excluded_types: set[str] = set()
+    if preferences is not None:
+        for exc_type in preferences.exclude.get(play_type.value, []):
+            excluded_types.add(exc_type)
+
+    if excluded_types:
+        survivors = []
+        for h in candidates:
+            if h.agent_type.value in excluded_types:
+                eliminated["exclude"].append(h.agent_id)
+            else:
+                survivors.append(h)
+        candidates = survivors
+
+    # -- Step 3: tier eligibility hard filter --------------------------------
+    allowed_tiers = _PLAY_ALLOWED_TIERS.get(play_type)
+    if allowed_tiers is not None:
+        survivors = []
+        for h in candidates:
+            if (h.model_tier or DEFAULT_MODEL_TIER) not in allowed_tiers:
+                eliminated["tier"].append(h.agent_id)
+            else:
+                survivors.append(h)
+        candidates = survivors
+
+    if not candidates:
+        _logger.warning(
+            "agent_selection_blocked",
+            play_type=play_type.value,
+            eliminated=eliminated,
+            candidate_count_in=initial_count,
+        )
+        raise AntiConfirmationViolation(
+            f"All agents blocked for {play_type.value!r} — "
+            "anti-confirmation, exclude, or tier-eligibility rules eliminated all candidates"
+        )
+
+    # -- Step 3: soft scoring (stable sort; lower score = more preferred) ----
+    preferred_type: str | None = None
+    if preferences is not None:
+        preferred_type = preferences.affinity.get(play_type.value)
+
+    branch_exposed_ids: set[str] = set()
+    if branch is not None:
+        exposed = branch_exposure.get(branch)
+        if exposed:
+            branch_exposed_ids.add(exposed)
+
+    tier_rank = {"small": 0, "medium": 1, "large": 2}
+
+    def _score(h: AgentHandle) -> tuple[int, int, int, int, int]:
+        # Circuit breaker (#22): strongly deprioritize a known-dead agent (0
+        # successes + a timeout or repeated failures) so a healthy peer always
+        # wins. Soft, not a hard filter — if every IDLE candidate is broken we
+        # still pick one rather than wedge (the play-availability gate already
+        # masks the play when no healthy capable agent exists).
+        task_history = h.task_history
+        successes = sum(1 for t in task_history if t.success)
+        failures = len(task_history) - successes
+        circuit_broken_score = (
+            1
+            if is_agent_circuit_broken(
+                tasks_completed=successes,
+                tasks_failed=failures,
+                timeout_count=h.timeout_count,
+                consecutive_timeouts=h.consecutive_timeouts,
+            )
+            else 0
+        )
+        # Branch exposure affinity: 0 if exposed to this branch, 1 otherwise
+        branch_exposure_score = 0 if h.agent_id in branch_exposed_ids else 1
+        # Type affinity: 0 if preferred type matches, 1 otherwise
+        type_score = 0 if (preferred_type and h.agent_type.value == preferred_type) else 1
+        # Tier cost: when a play accepts multiple tiers, preserve larger agents
+        # for plays that truly require them.
+        tier_score = tier_rank.get(h.model_tier or DEFAULT_MODEL_TIER, tier_rank["medium"])
+        # Least busy: ascending task count
+        busy_score = len(h.task_history)
+        return (circuit_broken_score, branch_exposure_score, type_score, tier_score, busy_score)
+
+    candidates.sort(key=_score)
+    return candidates[0]

agentshore/agents/auth_probe.py

@@ -0,0 +1,241 @@
+"""Pre-launch CLI-agent backend auth probing.
+
+``preflight_identities`` validates the *GitHub* identity tokens a session will
+commit/merge with. It does NOT validate the *backend* auth each CLI agent uses
+to reach its model provider — e.g. the Codex CLI's cached ``chatgpt.com``
+session token, which carries a TTL and expires mid-run. When it expires the
+Codex CLI prints ``failed to renew cache TTL`` / ``failed to refresh available
+models`` to stderr and then hangs reading from stdin, so every dispatch runs to
+the full ``stream_idle_timeout`` before being killed — observed burning 16
+plays in a single session.
+
+This module is the single source of truth for "is agent <type>'s backend auth
+currently valid?", shared by three call sites so a green badge on the desktop
+setup screen provably means the launch gate will pass:
+
+* the CLI launch gate (``preflight_cli_agent_auth`` in ``session/bootstrap.py``),
+* the desktop ``session.start`` gate (a phase in ``sidecar/session_lifecycle``),
+* the desktop agents/identities setup screen (``agents.check_auth`` RPC).
+
+The probe is intentionally conservative: only agent types with a reliable,
+non-mutating auth-status command are probed; everything else returns
+``UNPROBEABLE`` and never blocks a launch, so this can never introduce a
+false-negative startup failure.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from agentshore import subprocess_env
+from agentshore.state import CLI_AGENT_TYPES, AgentType
+
+if TYPE_CHECKING:
+    from agentshore.config.models import AgentConfig, RuntimeConfig
+
+# Shared status vocabulary. The desktop setup screen and the launch gate both
+# consume these exact strings, so a status here maps 1:1 to a frontend badge.
+AUTH_OK = "ok"
+AUTH_EXPIRED = "expired"
+AUTH_TIMEOUT = "timeout"
+AUTH_ERROR = "error"
+AUTH_UNPROBEABLE = "unprobeable"
+
+# Only these statuses gate a launch. ``error`` (binary missing / unexpected
+# non-zero with no auth marker) and ``timeout`` are surfaced but NOT blocking:
+# a transient probe hiccup must never strand an otherwise-fine session, and the
+# runtime auth-suppression backstop (ErrorClass.AUTH parking) catches a genuine
+# failure that slips through.
+_BLOCKING_STATUSES = frozenset({AUTH_EXPIRED})
+
+# Default probe timeout. Auth-status is a local credential read; 10s is ample
+# and keeps the setup screen / launch gate responsive.
+DEFAULT_PROBE_TIMEOUT_S = 10.0
+
+# Per-type auth-status command (args appended to the resolved binary). Only the
+# Codex CLI exposes a reliable, non-interactive, non-mutating status verb today;
+# the others fall through to UNPROBEABLE until a trustworthy command is
+# confirmed (a wrong probe that blocks launch is worse than no probe).
+_PROBE_ARGV: dict[AgentType, tuple[str, ...]] = {
+    AgentType.CODEX: ("login", "status"),
+}
+
+_DEFAULT_BINARY: dict[AgentType, str] = {
+    AgentType.CLAUDE_CODE: "claude",
+    AgentType.CODEX: "codex",
+    AgentType.GEMINI: "gemini",
+    AgentType.GROK: "grok",
+}
+
+# Output markers indicating the backend is NOT authenticated / the cached
+# session is dead. Matched case-insensitively against stdout+stderr. Includes
+# the Codex TTL-expiry signatures so the same vocabulary that classifies a
+# mid-run hang (ErrorClass.AUTH) also classifies a pre-launch probe.
+_NOT_AUTHED_MARKERS: tuple[str, ...] = (
+    "not logged in",
+    "not authenticated",
+    "logged out",
+    "no credentials",
+    "please run",
+    "run `codex login`",
+    "run 'codex login'",
+    "failed to renew cache ttl",
+    "failed to refresh available models",
+)
+
+
+@dataclass(frozen=True)
+class AuthProbeResult:
+    """Outcome of probing one agent type's backend auth."""
+
+    agent_type: AgentType
+    status: str
+    detail: str
+
+    @property
+    def ok(self) -> bool:
+        """True when auth is valid or the type can't be probed (non-blocking)."""
+        return self.status in (AUTH_OK, AUTH_UNPROBEABLE)
+
+    @property
+    def blocks_launch(self) -> bool:
+        """True only for a definitive, launch-gating auth failure."""
+        return self.status in _BLOCKING_STATUSES
+
+
+def _first_meaningful_line(text: str) -> str:
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped[:200]
+    return ""
+
+
+def probe_cli_auth(
+    agent_type: AgentType,
+    env: dict[str, str] | None = None,
+    *,
+    binary: str | None = None,
+    timeout: float = DEFAULT_PROBE_TIMEOUT_S,
+) -> AuthProbeResult:
+    """Probe one CLI agent type's backend auth via its status command.
+
+    Runs a short, non-mutating auth-status subprocess under the ambient
+    environment overlaid with *env*. Never raises — every failure mode maps to
+    an :class:`AuthProbeResult`. Blocking in nature (uses ``subprocess.run``);
+    async callers should wrap it in ``asyncio.to_thread``.
+    """
+    argv_tail = _PROBE_ARGV.get(agent_type)
+    if argv_tail is None:
+        return AuthProbeResult(
+            agent_type, AUTH_UNPROBEABLE, "no auth-status probe for this agent type"
+        )
+
+    exe = binary or _DEFAULT_BINARY.get(agent_type, agent_type.value)
+    resolved = shutil.which(exe)
+    if resolved is None:
+        return AuthProbeResult(agent_type, AUTH_ERROR, f"{exe!r} not found on PATH")
+
+    full_env = {**os.environ, **(env or {})}
+    try:
+        # Popen (not subprocess.run) so a timeout can tree-kill: the probed CLIs
+        # (codex) are node shims that spawn children; subprocess.run's own
+        # timeout kill reaps only the direct child and leaves the node subtree
+        # alive. CREATE_NO_WINDOW + new process group (Windows; 0 elsewhere)
+        # suppresses the console flash / AV window-hooking latency this module
+        # exists to avoid and roots the child in a killable group, matching the
+        # dispatch path in cli_agent and the hardened runner in command.py.
+        proc = subprocess.Popen(  # noqa: S603 — fixed argv, resolved binary
+            [resolved, *argv_tail],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            # Pin stdin (never inherit the parent's): the desktop sidecar's
+            # stdin is the live Tauri JSON-RPC pipe, and the very CLIs we probe
+            # (codex) wedge on a contended/empty stdin. Enforced by
+            # tests/test_subprocess_stdin_guard.py.
+            stdin=subprocess.DEVNULL,
+            text=True,
+            env=full_env,
+            creationflags=subprocess_env.no_window_creationflags(),
+        )
+    except OSError as exc:
+        return AuthProbeResult(agent_type, AUTH_ERROR, str(exc)[:200])
+
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        # Kill the whole tree (codex → node), not just the direct child, so
+        # nothing lingers past the probe.
+        if proc.pid is not None:
+            subprocess_env.kill_tree_sync(proc.pid)
+        proc.kill()
+        proc.communicate()
+        return AuthProbeResult(agent_type, AUTH_TIMEOUT, f"auth probe timed out after {timeout:g}s")
+
+    stdout = stdout or ""
+    stderr = stderr or ""
+    combined = f"{stdout}\n{stderr}".lower()
+    if any(marker in combined for marker in _NOT_AUTHED_MARKERS):
+        detail = _first_meaningful_line(stderr) or _first_meaningful_line(stdout)
+        return AuthProbeResult(
+            agent_type, AUTH_EXPIRED, detail or "backend session not authenticated"
+        )
+    if proc.returncode != 0:
+        detail = _first_meaningful_line(stderr) or _first_meaningful_line(stdout)
+        return AuthProbeResult(
+            agent_type,
+            AUTH_ERROR,
+            f"auth probe exited {proc.returncode}: {detail}"
+            if detail
+            else f"auth probe exited {proc.returncode}",
+        )
+    return AuthProbeResult(agent_type, AUTH_OK, "authenticated")
+
+
+def configured_cli_agent_types(cfg: RuntimeConfig) -> list[tuple[AgentType, AgentConfig]]:
+    """Return (type, config) for each enabled, probeable CLI agent in *cfg*.
+
+    API agents (keys like ``api_gpt`` that don't resolve to an
+    :class:`AgentType`) and disabled agents are skipped. One entry per type —
+    a backend session token is shared across instances of a type, so probing it
+    once is sufficient.
+    """
+    seen: set[AgentType] = set()
+    out: list[tuple[AgentType, AgentConfig]] = []
+    for name, agent_cfg in cfg.agents.items():
+        try:
+            agent_type = AgentType(name)
+        except ValueError:
+            continue
+        if agent_type not in CLI_AGENT_TYPES or not agent_cfg.enabled:
+            continue
+        if agent_type in seen:
+            continue
+        seen.add(agent_type)
+        out.append((agent_type, agent_cfg))
+    return out
+
+
+def probe_configured_cli_auth(cfg: RuntimeConfig) -> list[AuthProbeResult]:
+    """Probe every enabled CLI agent type configured in *cfg*.
+
+    Each probe runs under the agent's resolved GitHub identity env overlay (for
+    parity with how the Agent Manager spawns it) and its configured ``binary``
+    override. Shared by the CLI and desktop launch gates.
+    """
+    from agentshore.agents.identity import resolve_identity_env
+
+    results: list[AuthProbeResult] = []
+    for agent_type, agent_cfg in configured_cli_agent_types(cfg):
+        try:
+            env = resolve_identity_env(cfg, agent_cfg)
+        except Exception:
+            # Identity resolution failures are a GitHub-token concern surfaced by
+            # preflight_identities; don't let one block the backend-auth probe.
+            env = {}
+        results.append(probe_cli_auth(agent_type, env, binary=agent_cfg.binary))
+    return results