forgexa-cli 1.20.2__tar.gz → 1.20.4__tar.gz

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.20.2
+Version: 1.20.4
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT
@@ -108,6 +108,9 @@ forgexa board --project <project-id>
 | `forgexa daemon start -d` | Start daemon in background |
 | `forgexa daemon status` | Show your daemon statuses |
 | `forgexa daemon stop` | Stop local daemon |
+| `forgexa check` | Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent) |
+| `forgexa check --quick` | Same, but discovery only — no live task, no API calls |
+| `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
@@ -188,6 +191,40 @@ forgexa runtimes list
 forgexa runtimes list --all
 ```
 
+### Agent Health Check
+
+Before starting the daemon (or when tasks keep failing on this machine), verify that every
+installed agent CLI is genuinely usable — not just present on `PATH`. `forgexa check` reuses the
+exact discovery and execution code the daemon uses in production, so a `PASS` means the agent
+really works (auth, quota, and sandbox problems only ever surface on a real invocation).
+
+```bash
+# Discover installed agents, then run one real, minimal task through each to confirm it works
+forgexa check
+
+# Fast pass: discovery only, no live task, no API calls
+forgexa check --quick
+
+# Check a single agent
+forgexa check --agent claude
+```
+
+Example output:
+
+```
+Agent Availability Report
+----------------------------------------------------------------------
+  ✓  claude     v2.1.14 (Claude Code)
+  ✗  codex      not installed
+       'codex' not found on PATH, or found but 'codex --version' failed / did not
+       report a version. Install (or reinstall) the agent CLI and make sure it is
+       on PATH, then re-run 'forgexa check'.
+  ✓  kimi       v0.27.0
+----------------------------------------------------------------------
+2/3 agent(s) available for real platform tasks.
+```
+
+
 ### Supported AI Agents
 
 The daemon automatically discovers these agents if installed on your system:

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/README.md

@@ -76,6 +76,9 @@ forgexa board --project <project-id>
 | `forgexa daemon start -d` | Start daemon in background |
 | `forgexa daemon status` | Show your daemon statuses |
 | `forgexa daemon stop` | Stop local daemon |
+| `forgexa check` | Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent) |
+| `forgexa check --quick` | Same, but discovery only — no live task, no API calls |
+| `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
@@ -156,6 +159,40 @@ forgexa runtimes list
 forgexa runtimes list --all
 ```
 
+### Agent Health Check
+
+Before starting the daemon (or when tasks keep failing on this machine), verify that every
+installed agent CLI is genuinely usable — not just present on `PATH`. `forgexa check` reuses the
+exact discovery and execution code the daemon uses in production, so a `PASS` means the agent
+really works (auth, quota, and sandbox problems only ever surface on a real invocation).
+
+```bash
+# Discover installed agents, then run one real, minimal task through each to confirm it works
+forgexa check
+
+# Fast pass: discovery only, no live task, no API calls
+forgexa check --quick
+
+# Check a single agent
+forgexa check --agent claude
+```
+
+Example output:
+
+```
+Agent Availability Report
+----------------------------------------------------------------------
+  ✓  claude     v2.1.14 (Claude Code)
+  ✗  codex      not installed
+       'codex' not found on PATH, or found but 'codex --version' failed / did not
+       report a version. Install (or reinstall) the agent CLI and make sure it is
+       on PATH, then re-run 'forgexa check'.
+  ✓  kimi       v0.27.0
+----------------------------------------------------------------------
+2/3 agent(s) available for real platform tasks.
+```
+
+
 ### Supported AI Agents
 
 The daemon automatically discovers these agents if installed on your system:

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/forgexa_cli/__init__.py

@@ -1,2 +1,2 @@
 """forgexa-cli — Forgexa command-line client."""
-__version__ = "1.20.2"
+__version__ = "1.20.4"

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/forgexa_cli/daemon.py

@@ -555,7 +555,7 @@ except (ImportError, ModuleNotFoundError):
 # DAEMON_VERSION is the protocol/logic version of the daemon code.
 # Kept in sync with pyproject.toml version via bump-version.sh.
 # CLIENT_TYPE identifies which packaging/distribution this daemon runs in.
-DAEMON_VERSION = "1.20.2"
+DAEMON_VERSION = "1.20.4"
 
 
 def _detect_client_type() -> str:
@@ -8892,9 +8892,46 @@ class RuntimeDaemon:
                 if pending_count >= 10 or (now - _chunk_state["last_flush"]) >= 8.0:
                     await _flush_output_to_server()
 
-            result = await self.process_manager.run_agent(
-                agent, fake_task, workspace_path, on_chunk=on_chunk,
-            )
+            # P1-4 fix: periodic keep-alive heartbeat, independent of output activity.
+            # report_ai_job_progress() on the server unconditionally renews
+            # job.lease_until by AI_JOB_DISPATCHER_LEASE_SECONDS (600s) on every call,
+            # but on_chunk above only POSTs when the agent actually produces new
+            # stdout lines. A long silent stretch (agent "thinking", a quiet
+            # build/test command, etc.) is explicitly tolerated for up to
+            # AGENT_IDLE_TIMEOUT (1200s) before the daemon itself would consider the
+            # agent hung — but the AIJob's server-side lease would already have
+            # expired at 600s with no on_chunk activity, causing the dispatcher's
+            # stale-job recovery to reset the job to pending and re-dispatch it while
+            # this daemon execution is still legitimately running (duplicate
+            # execution / clobbered state). A heartbeat well under the lease
+            # duration closes that gap.
+            _heartbeat_stop = asyncio.Event()
+
+            async def _lease_heartbeat():
+                while not _heartbeat_stop.is_set():
+                    try:
+                        await asyncio.wait_for(_heartbeat_stop.wait(), timeout=60)
+                    except asyncio.TimeoutError:
+                        pass
+                    if _heartbeat_stop.is_set():
+                        break
+                    try:
+                        await conn.client.post(f"{reporter_url}/progress", json={}, timeout=10)
+                    except Exception:
+                        pass  # never let heartbeat errors affect agent execution
+
+            _heartbeat_task = asyncio.create_task(_lease_heartbeat())
+            try:
+                result = await self.process_manager.run_agent(
+                    agent, fake_task, workspace_path, on_chunk=on_chunk,
+                )
+            finally:
+                _heartbeat_stop.set()
+                _heartbeat_task.cancel()
+                try:
+                    await _heartbeat_task
+                except asyncio.CancelledError:
+                    pass
             # Flush any remaining buffered lines after agent finishes
             await _flush_output_to_server()
 
@@ -8925,9 +8962,35 @@ class RuntimeDaemon:
                 agent = _aj_fallback
                 _aj_tried.add(agent.agent_id)
                 fake_task.agent_type = agent.agent_id
-                result = await self.process_manager.run_agent(
-                    agent, fake_task, workspace_path, on_chunk=on_chunk,
-                )
+                # Same lease-renewal heartbeat as the primary run above (P1-4) —
+                # a fallback agent run can also go silent for a while.
+                _fb_heartbeat_stop = asyncio.Event()
+
+                async def _fb_lease_heartbeat():
+                    while not _fb_heartbeat_stop.is_set():
+                        try:
+                            await asyncio.wait_for(_fb_heartbeat_stop.wait(), timeout=60)
+                        except asyncio.TimeoutError:
+                            pass
+                        if _fb_heartbeat_stop.is_set():
+                            break
+                        try:
+                            await conn.client.post(f"{reporter_url}/progress", json={}, timeout=10)
+                        except Exception:
+                            pass
+
+                _fb_heartbeat_task = asyncio.create_task(_fb_lease_heartbeat())
+                try:
+                    result = await self.process_manager.run_agent(
+                        agent, fake_task, workspace_path, on_chunk=on_chunk,
+                    )
+                finally:
+                    _fb_heartbeat_stop.set()
+                    _fb_heartbeat_task.cancel()
+                    try:
+                        await _fb_heartbeat_task
+                    except asyncio.CancelledError:
+                        pass
                 await _flush_output_to_server()
 
             # 4. Capture branch/commit metadata without mutating the repository.

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/forgexa_cli/main.py

@@ -24,6 +24,9 @@ Usage:
     forgexa daemon agents
     forgexa daemon restart
     forgexa daemon stop
+    forgexa check
+    forgexa check --quick
+    forgexa check --agent claude
     forgexa gates pending
     forgexa config show
     forgexa --help
@@ -1324,6 +1327,208 @@ def cmd_daemon_agents(args: argparse.Namespace) -> None:
     )
 
 
+# ── forgexa check ──
+# Verifies locally-installed agent CLIs are genuinely usable, using the exact
+# discovery (AgentDiscovery) and execution (ProcessManager.run_agent) code
+# paths the real daemon uses to run platform tasks. A binary being on PATH or
+# passing `--version` is not sufficient proof it works (auth, quota, sandbox,
+# and config problems only surface on a real invocation) — this command runs
+# one minimal real task per agent to confirm it end-to-end.
+
+_CHECK_TASK_PROMPT = (
+    "This is an automated Forgexa CLI health check, not a real task. "
+    "Do not read, create, or modify any files in this directory. "
+    "Simply reply with the single word: OK"
+)
+
+
+def _check_not_installed_reason(agent_id: str, registry: dict) -> str:
+    spec = registry.get(agent_id, {})
+    cmd = (spec.get("commands") or [agent_id])[0]
+    detect = spec.get("detect", f"{cmd} --version")
+    return (
+        f"'{cmd}' not found on PATH, or found but '{detect}' failed / did not "
+        "report a version. Install (or reinstall) the agent CLI and make sure "
+        "it is on PATH, then re-run 'forgexa check'."
+    )
+
+
+async def _live_check_agent(pm, agent, timeout: int) -> tuple[bool, str]:
+    """Run one real, minimal task through the agent CLI.
+
+    Uses ProcessManager.run_agent() — the exact same method the daemon calls
+    when the platform dispatches a real task — in an isolated scratch
+    directory so nothing in the user's real projects is touched.
+
+    Returns (available, reason). reason is empty on success.
+    """
+    import tempfile
+    from forgexa_cli.daemon import TaskInfo
+
+    workspace = Path(tempfile.mkdtemp(prefix="forgexa-check-"))
+    try:
+        subprocess.run(
+            ["git", "init", "-q"],
+            cwd=workspace, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            check=False,
+        )
+    except Exception:
+        pass
+
+    try:
+        task = TaskInfo(
+            task_id=f"check-{agent.agent_id}",
+            graph_id="forgexa-check",
+            node_type="review",
+            agent_type=agent.agent_id,
+            input_prompt=_CHECK_TASK_PROMPT,
+            input_data={},
+            timeout_seconds=timeout,
+            max_retries=0,
+            retry_count=0,
+            project={},
+            work_item={},
+        )
+        result = await pm.run_agent(agent, task, workspace)
+        if result.status == "success":
+            return True, ""
+        reason = (result.error or "").strip() or f"exited with code {result.exit_code}"
+        if reason.lower().startswith("exited with code") and (result.stderr or "").strip():
+            tail = result.stderr.strip().splitlines()[-1][:300]
+            reason = f"{reason}: {tail}"
+        return False, reason
+    except Exception as exc:
+        return False, f"health check crashed: {exc}"
+    finally:
+        shutil.rmtree(workspace, ignore_errors=True)
+
+
+async def _run_agent_check(agent_ids: list[str], quick: bool, timeout: int, narrate: bool) -> list[dict]:
+    import asyncio
+    from forgexa_cli.daemon import AgentDiscovery, ProcessManager
+
+    registry = AgentDiscovery.AGENT_REGISTRY
+    discovered = await AgentDiscovery().discover()
+    discovered_by_id = {a.agent_id: a for a in discovered}
+
+    results: list[dict] = []
+    live_jobs: dict[str, "asyncio.Task"] = {}
+    pm = ProcessManager()
+
+    for agent_id in agent_ids:
+        agent = discovered_by_id.get(agent_id)
+        results.append({
+            "agent_id": agent_id,
+            "installed": agent is not None,
+            "version": agent.version if agent else "",
+            "available": agent is not None,
+            "reason": "" if agent else _check_not_installed_reason(agent_id, registry),
+        })
+        if agent is not None and not quick:
+            live_jobs[agent_id] = asyncio.create_task(_live_check_agent(pm, agent, timeout))
+
+    if live_jobs:
+        if narrate:
+            print(
+                f"Running a live smoke-test task on {len(live_jobs)} installed agent(s) "
+                f"(per-agent timeout {timeout}s)..."
+            )
+            print()
+        for entry in results:
+            job = live_jobs.get(entry["agent_id"])
+            if job is None:
+                continue
+            ok, reason = await job
+            entry["available"] = ok
+            entry["reason"] = reason
+            if narrate:
+                print(f"  {'PASS' if ok else 'FAIL'}  {entry['agent_id']}")
+
+    return results
+
+
+def _print_check_report(results: list[dict], quick: bool) -> None:
+    fmt = _fmt()
+    if fmt == "json":
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+        return
+    if fmt == "quiet":
+        for r in results:
+            print(f"{r['agent_id']}\t{'available' if r['available'] else 'unavailable'}")
+        return
+
+    print()
+    print("Agent Availability Report")
+    print("-" * 70)
+    for r in results:
+        mark = "✓" if r["available"] else "✗"
+        label = f"v{r['version']}" if r.get("version") else "not installed"
+        print(f"  {mark}  {r['agent_id']:<10} {label}")
+        if r["reason"]:
+            print(f"       {r['reason']}")
+    print("-" * 70)
+
+    usable = sum(1 for r in results if r["available"])
+    total = len(results)
+    print(f"{usable}/{total} agent(s) available for real platform tasks.")
+    if quick:
+        print(
+            "(ran with --quick: discovery only, no live task executed — "
+            "run 'forgexa check' without --quick to confirm agents really work)"
+        )
+    if usable == 0:
+        print()
+        print("No usable agents on this machine — tasks dispatched here will fail.")
+        print("Install at least one supported agent CLI (Claude Code, Codex, OpenCode,")
+        print("Gemini CLI, Kimi Code, or GitHub Copilot CLI), then re-run: forgexa check")
+
+
+def cmd_check(args: argparse.Namespace) -> None:
+    """Verify locally-installed AI agent CLIs are genuinely usable for platform tasks.
+
+    Reuses the exact discovery (AgentDiscovery) and execution
+    (ProcessManager.run_agent) code paths the real daemon uses to run tasks,
+    so a PASS here means the agent actually works end-to-end — not just that
+    a binary happens to exist on PATH.
+    """
+    import asyncio
+
+    os.environ.setdefault("DAEMON_NO_CONSOLE_LOG", "1")
+    from forgexa_cli.daemon import AgentDiscovery
+
+    only_agent = getattr(args, "agent", None)
+    quick = bool(getattr(args, "quick", False))
+    timeout = getattr(args, "timeout", None) or 90
+
+    known_ids = list(AgentDiscovery.AGENT_REGISTRY.keys())
+    if only_agent:
+        if only_agent not in known_ids:
+            print(f"Unknown agent '{only_agent}'. Known agents: {', '.join(known_ids)}", file=sys.stderr)
+            sys.exit(1)
+        agent_ids = [only_agent]
+    else:
+        agent_ids = known_ids
+
+    narrate = _fmt() == "table"
+    if narrate:
+        print("Scanning for installed agent CLIs...")
+        if not quick:
+            print("Each installed agent will run one real, minimal task to confirm it works")
+            print(f"(this performs a live API call per agent; per-agent timeout: {timeout}s).")
+        print()
+
+    try:
+        results = asyncio.run(_run_agent_check(agent_ids, quick, timeout, narrate))
+    except Exception as exc:
+        print(f"Agent check failed unexpectedly: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    _print_check_report(results, quick=quick)
+
+    if not any(r["available"] for r in results):
+        sys.exit(1)
+
+
 def cmd_runtimes_list(args: argparse.Namespace) -> None:
     runtimes = _get_runtimes(include_all=getattr(args, "all", False))
     if not runtimes:
@@ -1737,6 +1942,21 @@ def main() -> None:
     )
     _agents_sc.add_argument("--all", action="store_true", help="Include all users' runtimes (admin only)")
 
+    # check
+    check_p = sub.add_parser(
+        "check",
+        help="Verify locally-installed agent CLIs are genuinely usable for platform tasks",
+    )
+    check_p.add_argument("--agent", default=None, help="Check only this agent (e.g. claude, codex, kimi)")
+    check_p.add_argument(
+        "--quick", action="store_true",
+        help="Discovery only — skip the live task execution test (no API calls)",
+    )
+    check_p.add_argument(
+        "--timeout", type=int, default=90, metavar="SECONDS",
+        help="Per-agent timeout for the live execution test (default: 90)",
+    )
+
     # runtimes
     rt_p = sub.add_parser("runtimes", help="Runtime management")
     rt_sub = rt_p.add_subparsers(dest="rt_cmd")
@@ -1857,6 +2077,7 @@ def main() -> None:
         "status":  cmd_daemon_status,
         "logs":    cmd_daemon_logs,
         "agents":  cmd_daemon_agents,
+        "check":   cmd_check,
         "runtimes": lambda a: {
             "list": cmd_runtimes_list,
         }.get(a.rt_cmd, lambda _: rt_p.print_help())(a),

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/forgexa_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.20.2
+Version: 1.20.4
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT
@@ -108,6 +108,9 @@ forgexa board --project <project-id>
 | `forgexa daemon start -d` | Start daemon in background |
 | `forgexa daemon status` | Show your daemon statuses |
 | `forgexa daemon stop` | Stop local daemon |
+| `forgexa check` | Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent) |
+| `forgexa check --quick` | Same, but discovery only — no live task, no API calls |
+| `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
@@ -188,6 +191,40 @@ forgexa runtimes list
 forgexa runtimes list --all
 ```
 
+### Agent Health Check
+
+Before starting the daemon (or when tasks keep failing on this machine), verify that every
+installed agent CLI is genuinely usable — not just present on `PATH`. `forgexa check` reuses the
+exact discovery and execution code the daemon uses in production, so a `PASS` means the agent
+really works (auth, quota, and sandbox problems only ever surface on a real invocation).
+
+```bash
+# Discover installed agents, then run one real, minimal task through each to confirm it works
+forgexa check
+
+# Fast pass: discovery only, no live task, no API calls
+forgexa check --quick
+
+# Check a single agent
+forgexa check --agent claude
+```
+
+Example output:
+
+```
+Agent Availability Report
+----------------------------------------------------------------------
+  ✓  claude     v2.1.14 (Claude Code)
+  ✗  codex      not installed
+       'codex' not found on PATH, or found but 'codex --version' failed / did not
+       report a version. Install (or reinstall) the agent CLI and make sure it is
+       on PATH, then re-run 'forgexa check'.
+  ✓  kimi       v0.27.0
+----------------------------------------------------------------------
+2/3 agent(s) available for real platform tasks.
+```
+
+
 ### Supported AI Agents
 
 The daemon automatically discovers these agents if installed on your system:

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/forgexa_cli.egg-info/SOURCES.txt

@@ -11,4 +11,5 @@ forgexa_cli.egg-info/dependency_links.txt
 forgexa_cli.egg-info/entry_points.txt
 forgexa_cli.egg-info/requires.txt
 forgexa_cli.egg-info/top_level.txt
-tests/test_auth_and_runtime_commands.py
+tests/test_auth_and_runtime_commands.py
+tests/test_check_command.py

{forgexa_cli-1.20.2 → forgexa_cli-1.20.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forgexa-cli"
-version = "1.20.2"
+version = "1.20.4"
 description = "Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform"
 requires-python = ">=3.9"
 license = "MIT"

forgexa_cli-1.20.4/tests/test_check_command.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from forgexa_cli import daemon, main
+
+
+def _small_registry() -> dict:
+    """A small subset of AGENT_REGISTRY, isolated from the real one so these
+    tests don't depend on (or break from) future registry additions."""
+    return {
+        "claude": {"commands": ["claude"], "detect": "claude --version"},
+        "kimi": {"commands": ["kimi"], "detect": "kimi --version"},
+        "codex": {"commands": ["codex"], "detect": "codex --version"},
+    }
+
+
+def _agent(agent_id: str, version: str = "1.0.0") -> daemon.DiscoveredAgent:
+    return daemon.DiscoveredAgent(
+        agent_id=agent_id,
+        command=agent_id,
+        version=version,
+        invoke_modes=["cli"],
+        compatibility_level="L2",
+    )
+
+
+def test_check_quick_reports_installed_and_missing_agents(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("claude"), _agent("kimi")]),
+    )
+    run_agent_mock = AsyncMock()
+    monkeypatch.setattr(daemon.ProcessManager, "run_agent", run_agent_mock)
+
+    main.cmd_check(SimpleNamespace(agent=None, quick=True, timeout=90))
+
+    # --quick must never invoke the live execution path.
+    run_agent_mock.assert_not_called()
+
+    out = capsys.readouterr().out
+    assert "✓  claude" in out
+    assert "✓  kimi" in out
+    assert "✗  codex" in out
+    assert "not installed" in out
+    assert "2/3 agent(s) available" in out
+
+
+def test_check_live_mode_passes_on_success(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("claude")]),
+    )
+    run_agent_mock = AsyncMock(
+        return_value=daemon.TaskResult(status="success", exit_code=0, stdout="OK", stderr="")
+    )
+    monkeypatch.setattr(daemon.ProcessManager, "run_agent", run_agent_mock)
+
+    main.cmd_check(SimpleNamespace(agent="claude", quick=False, timeout=5))
+
+    run_agent_mock.assert_awaited_once()
+    called_agent, called_task, _called_workspace = run_agent_mock.await_args.args
+    assert called_agent.agent_id == "claude"
+    assert called_task.input_prompt == main._CHECK_TASK_PROMPT
+    assert called_task.timeout_seconds == 5
+
+    out = capsys.readouterr().out
+    assert "PASS  claude" in out
+    assert "✓  claude" in out
+    assert "1/1 agent(s) available" in out
+
+
+def test_check_live_mode_reports_failure_reason_and_exits_nonzero(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("kimi")]),
+    )
+    monkeypatch.setattr(
+        daemon.ProcessManager, "run_agent",
+        AsyncMock(return_value=daemon.TaskResult(
+            status="failed", exit_code=-1, stdout="", stderr="",
+            error="Kimi authentication required: please run 'kimi' and log in.",
+        )),
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        main.cmd_check(SimpleNamespace(agent="kimi", quick=False, timeout=5))
+
+    assert exc_info.value.code == 1
+    out = capsys.readouterr().out
+    assert "✗  kimi" in out
+    assert "Kimi authentication required" in out
+    assert "0/1 agent(s) available" in out
+
+
+def test_check_unknown_agent_exits_with_error(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+
+    with pytest.raises(SystemExit) as exc_info:
+        main.cmd_check(SimpleNamespace(agent="bogus", quick=True, timeout=90))
+
+    assert exc_info.value.code == 1
+    err = capsys.readouterr().err
+    assert "Unknown agent 'bogus'" in err
+
+
+def test_check_json_output_is_parseable(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(daemon.AgentDiscovery, "AGENT_REGISTRY", _small_registry())
+    monkeypatch.setattr(
+        daemon.AgentDiscovery, "discover",
+        AsyncMock(return_value=[_agent("claude", version="2.0.0")]),
+    )
+    monkeypatch.setattr(main, "_output_format", "json")
+
+    main.cmd_check(SimpleNamespace(agent="claude", quick=True, timeout=90))
+
+    out = capsys.readouterr().out
+    payload = json.loads(out)
+    assert payload == [{
+        "agent_id": "claude",
+        "installed": True,
+        "version": "2.0.0",
+        "available": True,
+        "reason": "",
+    }]