propr-cli 0.8.3 → 0.8.5

package/dist/commands/checkCommands.js

@@ -9,52 +9,126 @@ import { Command } from "commander";
 import { spawnSync } from "node:child_process";
 import { existsSync, accessSync, readFileSync, constants as fsConstants } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { resolveGithubAuthMode, validateRelayUrl } from "../vendor/shared/index.js";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_PROPR_GH_RELAY_URL, resolveGithubAuthMode, resolveGithubEventIntakeMode, validateIntakeModePrerequisites, validateRelayUrl, } from "../vendor/shared/index.js";
 import { createConfigManager } from "../config/index.js";
-import { getHostConfig } from "../orchestrator/index.js";
+import { createApiClient, getSystemStatus } from "../api/index.js";
+import { getHostConfig, loadOrchestrator } from "../orchestrator/index.js";
+import { upsertEnvVars } from "../utils/envFile.js";
 import { printOutput } from "../utils/index.js";
+import { validateAgents, validateAgentFilter, validAgentTypes, agentRowsToChecks, getAgentTankUsage } from "./agentValidation.js";
 function agentDescriptors() {
     const home = homedir();
     return [
         { type: "claude", hostDirKey: "hostClaudeDir", envKey: "HOST_CLAUDE_DIR", defaultDir: join(home, ".claude"), imageKey: "agent-claude", bin: "claude" },
         { type: "codex", hostDirKey: "hostCodexDir", envKey: "HOST_CODEX_DIR", defaultDir: join(home, ".codex"), imageKey: "agent-codex", bin: "codex" },
-        { type: "antigravity", hostDirKey: "hostAntigravityDir", envKey: "HOST_ANTIGRAVITY_DIR", defaultDir: join(home, ".gemini"), imageKey: "agent-antigravity", bin: "gemini" },
+        { type: "antigravity", hostDirKey: "hostAntigravityDir", envKey: "HOST_ANTIGRAVITY_DIR", defaultDir: join(home, ".gemini"), imageKey: "agent-antigravity", bin: "agy" },
         { type: "opencode", hostDirKey: "hostOpencodeXdgDir", envKey: "HOST_OPENCODE_XDG_DIR", defaultDir: join(home, ".config", "opencode"), imageKey: "agent-opencode", bin: "opencode" },
-        { type: "opencode-legacy", hostDirKey: "hostOpencodeLegacyDir", envKey: "HOST_OPENCODE_LEGACY_DIR", defaultDir: join(home, ".opencode"), imageKey: "agent-opencode", bin: "opencode" },
         { type: "opencode-data", hostDirKey: "hostOpencodeDataDir", envKey: "HOST_OPENCODE_DATA_DIR", defaultDir: join(home, ".local", "share", "opencode"), imageKey: "agent-opencode", bin: "opencode" },
         { type: "vibe", hostDirKey: "hostVibeDir", envKey: "HOST_VIBE_DIR", defaultDir: join(home, ".vibe"), imageKey: "agent-vibe", bin: "vibe" },
     ];
 }
 export const STACK_CONFIG_CHECK_NAME = "Stack config (.env)";
 const STATUS_GLYPH = { ok: "✓", warn: "!", fail: "✗" };
+const STATUS_LABEL = { ok: "OK", warn: "WARN", fail: "FAIL" };
+export const CHECK_GROUPS = ["CLI", "Docker", "Stack", "Images", "Agents", "GitHub", "Configuration"];
+// Display titles for section headers — more descriptive than the internal
+// single-word CheckGroup keys (which stay stable for filtering/data).
+export const GROUP_TITLES = {
+    CLI: "ProPR CLI",
+    Docker: "Docker Engine",
+    Stack: "Stack Configuration",
+    Images: "Container Images",
+    Agents: "Agent Credentials",
+    GitHub: "GitHub Authentication",
+    Configuration: "Environment Configuration",
+};
+// One-line, new-user-friendly explanation of what each section verifies.
+export const GROUP_DESCRIPTIONS = {
+    CLI: "Local CLI version",
+    Docker: "Container engine that runs the stack and agents",
+    Stack: "Local stack root and .env configuration",
+    Images: "ProPR service and agent container images",
+    Agents: "Host credential directories mounted into agent containers",
+    GitHub: "Credentials the backend needs to access GitHub",
+    Configuration: "Environment variable validation",
+};
+const ANSI = {
+    reset: "\u001b[0m",
+    bold: "\u001b[1m",
+    dim: "\u001b[2m",
+    red: "\u001b[31m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+    cyan: "\u001b[36m",
+};
+/** Read this CLI's version from package.json across TS source, workspace dist, and published dist layouts. */
+function readCliVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "..", "..", "package.json"),
+        join(here, "..", "..", "..", "package.json"),
+        resolve(process.cwd(), "package.json"),
+    ];
+    try {
+        for (const pkgPath of candidates) {
+            if (!existsSync(pkgPath))
+                continue;
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if ((pkg.name === "@propr/cli" || pkg.name === "propr-cli" || pkg.name === "propr") && pkg.version) {
+                return pkg.version;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return "0.0.0";
+}
+function runCliChecks(emit) {
+    emit({ name: "CLI version", status: "ok", detail: readCliVersion(), group: "CLI" });
+}
 /** Run all checks and return the structured outcome (no printing). */
 export async function runChecks(options = {}) {
     const results = [];
+    // Record a finalized result and notify any live presenter immediately.
+    const emit = (result, opts = {}) => {
+        if (opts.record !== false)
+            results.push(result);
+        options.onResult?.(result);
+    };
     const configManager = await createConfigManager();
+    const skipRemoteImageCheck = Boolean(options.skipRemoteImageCheck || envSkipsRemoteImageCheck());
+    // 0. CLI version (local-only; `propr check` should not phone home by default).
+    runCliChecks(emit);
     // 1. Docker installed
     const dockerVersion = spawnSync("docker", ["--version"], { encoding: "utf-8" });
     if (dockerVersion.status === 0) {
-        results.push({ name: "Docker installed", status: "ok", detail: dockerVersion.stdout.trim() });
+        emit({ name: "Docker installed", status: "ok", detail: dockerVersion.stdout.trim(), group: "Docker" });
     }
     else {
-        results.push({
+        emit({
             name: "Docker installed",
             status: "fail",
             detail: "`docker` command not found",
+            group: "Docker",
             fix: "Install Docker: https://docs.docker.com/get-docker/",
         });
     }
     const { orch, cfg, rootDir } = await getHostConfig({ configManager, root: options.root });
     // 2. Docker daemon running
     const daemonUp = orch.dockerAvailable();
-    results.push(daemonUp
-        ? { name: "Docker daemon", status: "ok", detail: "daemon is reachable" }
+    emit(daemonUp
+        ? { name: "Docker daemon", status: "ok", detail: "daemon is reachable", group: "Docker" }
         : {
             name: "Docker daemon",
             status: "fail",
             detail: "cannot reach the Docker daemon (`docker info` failed)",
+            group: "Docker",
             fix: "Start Docker (e.g. `sudo systemctl start docker`) and ensure your user can access it.",
+            remediation: { kind: "start-docker" },
         });
     // 3. Docker socket (informational — only relevant for the default socket setup)
     const socketPath = "/var/run/docker.sock";
@@ -66,90 +140,184 @@ export async function runChecks(options = {}) {
         catch {
             accessible = false;
         }
-        results.push(accessible
-            ? { name: "Docker socket", status: "ok", detail: socketPath }
+        emit(accessible
+            ? { name: "Docker socket", status: "ok", detail: socketPath, group: "Docker" }
             : {
                 name: "Docker socket",
                 status: "warn",
                 detail: `${socketPath} is not read/write for the current user`,
+                group: "Docker",
                 fix: "Add your user to the `docker` group, or run with sufficient privileges.",
             });
     }
     // 4. Stack root + .env
     const envPath = join(rootDir, ".env");
     if (existsSync(envPath)) {
-        results.push({ name: STACK_CONFIG_CHECK_NAME, status: "ok", detail: envPath });
+        emit({ name: STACK_CONFIG_CHECK_NAME, status: "ok", detail: envPath, group: "Stack" });
     }
     else {
-        results.push({
+        emit({
             name: STACK_CONFIG_CHECK_NAME,
             status: "warn",
             detail: `no .env found at ${rootDir}`,
+            group: "Stack",
             fix: "Run `propr init stack` to scaffold .env, data/, logs/ and repos/.",
+            remediation: { kind: "init-stack", rootDir },
         });
     }
-    // 5. Stack images present locally
+    // 5. Stack images present locally. The remote freshness probe is the slowest
+    // check, so it runs for every image concurrently (off the event loop) instead
+    // of serially — results are emitted live as each settles, then appended to the
+    // outcome in manifest order so non-streaming consumers stay deterministic.
     if (daemonUp) {
-        for (const [key, tag] of Object.entries(cfg.images)) {
-            if (key === "docs" && !cfg.docsEnabled)
-                continue;
-            const present = imagePresent(orch, tag);
-            if (present) {
-                results.push({ name: `Image ${key}`, status: "ok", detail: tag });
+        const missingImageResult = (key, tag) => ({
+            name: `Image ${key}`,
+            status: "warn",
+            detail: `${tag} not present locally`,
+            group: "Images",
+            fix: key.startsWith("agent-")
+                ? "Jobs using this agent fail until the image is pulled. Run `propr images pull`, `propr start`, or build with scripts/build-images.sh."
+                : "Run `propr images pull`, or let `propr start` pull it automatically.",
+            remediation: { kind: "pull-image", imageKey: key, tag },
+        });
+        // ProPR only publishes images in its own registry namespace (propr/*).
+        // Third-party images (e.g. redis:7-alpine) are pinned by tag and not part of
+        // ProPR's update story, so their registry "freshness" is not actionable here
+        // — and the remote digest probe for them is the main source of slow timeouts.
+        const registry = typeof cfg.manifest?.registry === "string" ? cfg.manifest.registry : "propr";
+        const isProprPublished = (tag) => tag.startsWith(`${registry}/`);
+        const freshnessByTag = new Map();
+        const computeImageResult = async (key, tag) => {
+            // Presence-only for third-party images and when remote checks are skipped.
+            if (skipRemoteImageCheck || !isProprPublished(tag)) {
+                if (!imagePresent(orch, tag))
+                    return missingImageResult(key, tag);
+                const detail = skipRemoteImageCheck ? `${tag} (local; remote check skipped)` : `${tag} (present)`;
+                return { name: `Image ${key}`, status: "ok", detail, group: "Images" };
             }
-            else {
-                const isAgent = key.startsWith("agent-");
-                results.push({
+            let freshnessPromise = freshnessByTag.get(tag);
+            if (!freshnessPromise) {
+                freshnessPromise = orch.inspectImageFreshnessAsync(tag);
+                freshnessByTag.set(tag, freshnessPromise);
+            }
+            const freshness = await freshnessPromise;
+            if (freshness.status === "missing")
+                return missingImageResult(key, tag);
+            if (freshness.status === "current") {
+                return { name: `Image ${key}`, status: "ok", detail: `${tag} (current)`, group: "Images" };
+            }
+            if (freshness.status === "stale") {
+                return {
                     name: `Image ${key}`,
                     status: "warn",
-                    detail: `${tag} not present locally`,
-                    fix: isAgent
-                        ? "Jobs using this agent fail until the image is pulled. `propr start` pulls it, or build with scripts/build-images.sh."
-                        : "Will be pulled automatically on `propr start`.",
-                });
+                    detail: `${tag} is stale; remote digest ${freshness.remoteDigest}`,
+                    group: "Images",
+                    fix: "Pull the updated image: `propr images pull`.",
+                    remediation: { kind: "pull-image", imageKey: key, tag },
+                };
+            }
+            if (freshness.localOnly) {
+                return {
+                    name: `Image ${key}`,
+                    status: "warn",
+                    detail: `${tag} is local-only; registry freshness not verified`,
+                    group: "Images",
+                    fix: "Replace the unverifiable local tag with the registry image: `propr images pull`.",
+                    remediation: { kind: "pull-image", imageKey: key, tag },
+                };
             }
+            return {
+                name: `Image ${key}`,
+                status: "warn",
+                detail: `${tag} is present, but freshness could not be verified: ${freshness.error}`,
+                group: "Images",
+                fix: "Check registry access or rerun with --skip-remote-image-check for offline environments.",
+            };
+        };
+        const imageEntries = Object.entries(cfg.images).filter(([key]) => !(key === "docs" && !cfg.docsEnabled));
+        for (const [key] of imageEntries)
+            options.onPending?.({ name: `Image ${key}`, group: "Images" });
+        const computed = new Map();
+        await Promise.all(imageEntries.map(async ([key, tag]) => {
+            const result = await computeImageResult(key, tag);
+            computed.set(key, result);
+            emit(result, { record: false }); // live update in completion order
+        }));
+        // Append in manifest order so outcome.results is stable across runs.
+        for (const [key] of imageEntries) {
+            const result = computed.get(key);
+            if (result)
+                results.push(result);
         }
     }
     // 6. Agent credential dirs
     for (const agent of agentDescriptors()) {
         const configured = cfg[agent.hostDirKey];
         const dir = configured || agent.defaultDir;
-        if (existsSync(dir)) {
-            results.push({ name: `Agent creds: ${agent.type}`, status: "ok", detail: dir });
+        if (configured && existsSync(dir)) {
+            emit({ name: `Agent creds: ${agent.type}`, status: "ok", detail: dir, group: "Agents" });
+        }
+        else if (!configured && existsSync(agent.defaultDir)) {
+            emit({
+                name: `Agent creds: ${agent.type}`,
+                status: "warn",
+                detail: `${agent.defaultDir} detected but ${agent.envKey} is not set in .env`,
+                group: "Agents",
+                fix: `Add ${agent.envKey}=${agent.defaultDir} to .env so containers can mount these credentials.`,
+                remediation: { kind: "add-agent-credential", envKey: agent.envKey, path: agent.defaultDir, agentType: agent.type },
+            });
         }
         else {
-            results.push({
+            emit({
                 name: `Agent creds: ${agent.type}`,
                 status: "warn",
                 detail: `${dir} not found — ${agent.type} will not authenticate`,
+                group: "Agents",
                 fix: `Log in with the ${agent.type} CLI on this host, or set ${agent.envKey} in .env.`,
             });
         }
     }
+    // 6b. Agent Tank (optional subscription-usage monitor). Presence only — the
+    // actual usage refresh (slow PTY /usage calls) runs in `propr check agents`.
+    if (spawnSync("which", ["agent-tank"], { encoding: "utf-8" }).status === 0) {
+        const ver = spawnSync("agent-tank", ["--version"], { encoding: "utf-8", timeout: 10000 });
+        const version = `${ver.stdout ?? ""}${ver.stderr ?? ""}`.match(/\d+\.\d+\.\d+/)?.[0];
+        emit({ name: "Agent Tank", status: "ok", detail: version ? `agent-tank ${version} installed` : "installed", group: "Agents" });
+    }
     // 7. GitHub credentials (the backend hard-exits without a valid auth mode)
     const fileEnv = existsSync(envPath) ? orch.readEnvFile(envPath) : {};
     for (const r of checkGithubAuth(fileEnv, cfg))
-        results.push(r);
+        emit(r);
+    // 7b. Mode-specific GitHub intake prerequisites (the resolved intake mode
+    // needs the right credentials before the daemon/API can serve it).
+    for (const r of checkGithubIntakeMode(fileEnv))
+        emit(r);
+    // 7c. Routing intake diagnostics: routing URL plus live WebSocket state, last
+    // delivery id, and last ACK (when the backend is reachable) for the default
+    // routing_websocket path.
+    for (const r of await checkRoutingDiagnostics(fileEnv))
+        emit(r);
     // 8. User whitelist — warn when no whitelist is configured for non-demo stacks
     const whitelistRaw = process.env.GITHUB_USER_WHITELIST ?? fileEnv.GITHUB_USER_WHITELIST;
     const whitelistEntries = (whitelistRaw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const authMode = (process.env.GH_AUTH_MODE ?? fileEnv.GH_AUTH_MODE ?? "").trim().toLowerCase();
     const isDemo = isTruthy(process.env.PROPR_DEMO_MODE ?? fileEnv.PROPR_DEMO_MODE) || authMode === "demo";
     if (whitelistEntries.length === 0 && !isDemo) {
-        results.push({
+        emit({
             name: "User whitelist",
             status: "warn",
             detail: "GITHUB_USER_WHITELIST is not set — any GitHub user who can authenticate to this instance may trigger processing and use the API (within the App's repository access)",
+            group: "GitHub",
             fix: "Set GITHUB_USER_WHITELIST to a comma-separated list of allowed GitHub usernames in .env.",
         });
     }
     else if (whitelistEntries.length > 0) {
-        results.push({ name: "User whitelist", status: "ok", detail: `${whitelistEntries.length} user(s) allowed` });
+        emit({ name: "User whitelist", status: "ok", detail: `${whitelistEntries.length} user(s) allowed`, group: "GitHub" });
     }
     // 9. Config validation from the orchestrator (bind paths, vibe dirs, etc.)
     const validation = orch.validateEnv(cfg);
     for (const warn of validation.warnings) {
-        results.push({ name: "Config warning", status: "warn", detail: warn });
+        emit({ name: "Config warning", status: "warn", detail: warn, group: "Configuration" });
     }
     for (const err of validation.errors) {
         // env file / data dir absence is already surfaced by steps 4–6 above; skip duplicates.
@@ -157,7 +325,7 @@ export async function runChecks(options = {}) {
             continue;
         if (/data directory.*is not set/i.test(err))
             continue;
-        results.push({ name: "Config error", status: "fail", detail: err });
+        emit({ name: "Config error", status: "fail", detail: err, group: "Configuration" });
     }
     // 10. Deep verify (opt-in): image/CLI smoke test per selected agent
     if (options.verify && daemonUp) {
@@ -167,22 +335,24 @@ export async function runChecks(options = {}) {
         for (const agent of selected) {
             const tag = cfg.images[agent.imageKey];
             if (!tag || !imagePresent(orch, tag)) {
-                results.push({
+                emit({
                     name: `Verify: ${agent.type}`,
                     status: "warn",
                     detail: `image ${tag ?? agent.imageKey} not present — skipped`,
+                    group: "Agents",
                 });
                 continue;
             }
             const run = spawnSync("docker", ["run", "--rm", "--network=none", "--memory=512m", tag, agent.bin, "--version"], { encoding: "utf-8", timeout: 60000 });
             if (run.status === 0) {
-                results.push({ name: `Verify: ${agent.type}`, status: "ok", detail: `image runs (${(run.stdout || "").trim().split("\n")[0]})` });
+                emit({ name: `Verify: ${agent.type}`, status: "ok", detail: `image runs (${(run.stdout || "").trim().split("\n")[0]})`, group: "Agents" });
             }
             else {
-                results.push({
+                emit({
                     name: `Verify: ${agent.type}`,
                     status: "warn",
                     detail: `image/CLI smoke test failed: ${(run.stderr || run.stdout || "").trim().split("\n")[0]}`,
+                    group: "Agents",
                 });
             }
         }
@@ -221,7 +391,10 @@ const RELAY_TOKEN_KEY = "PROPR_GH_RELAY_TOKEN";
 function checkGithubAuth(env, cfg) {
     const val = (k) => process.env[k] ?? env[k];
     const out = [];
-    const relayUrl = val(RELAY_URL_KEY);
+    // PROPR_GH_RELAY_URL defaults to the hosted relay when unset, matching the
+    // backend (githubAuth) and the docs/.env: a token-only stack still infers relay
+    // mode here, so `propr check` cannot drift from boot behavior.
+    const relayUrl = val(RELAY_URL_KEY)?.trim() || DEFAULT_PROPR_GH_RELAY_URL;
     const relayToken = val(RELAY_TOKEN_KEY);
     const { mode, warnings } = resolveGithubAuthMode({
         demoMode: isTruthy(val("PROPR_DEMO_MODE")),
@@ -233,10 +406,10 @@ function checkGithubAuth(env, cfg) {
         installationId: val("GH_INSTALLATION_ID"),
     });
     for (const warning of warnings) {
-        out.push({ name: "GitHub auth", status: "warn", detail: warning });
+        out.push({ name: "GitHub auth", status: "warn", detail: warning, group: "GitHub" });
     }
     if (mode === "demo") {
-        out.push({ name: "GitHub auth", status: "ok", detail: "demo mode — GitHub access disabled" });
+        out.push({ name: "GitHub auth", status: "ok", detail: "demo mode — GitHub access disabled", group: "GitHub" });
         return out;
     }
     if (mode === "none") {
@@ -244,44 +417,48 @@ function checkGithubAuth(env, cfg) {
             name: "GitHub auth mode",
             status: "fail",
             detail: "no GitHub auth configured — the backend will exit at startup",
+            group: "GitHub",
             fix: "Set GH_APP_ID + GH_INSTALLATION_ID + a private key (own App), or PROPR_GH_RELAY_URL + PROPR_GH_RELAY_TOKEN (token relay), or PROPR_DEMO_MODE=true.",
         });
         return out;
     }
     if (mode === "relay") {
-        const urlError = relayUrl ? validateRelayUrl(relayUrl) : `${RELAY_URL_KEY} must be set for relay mode`;
+        // relayUrl is always populated (defaulted to the hosted relay above); this only
+        // catches an explicitly-set but malformed PROPR_GH_RELAY_URL.
+        const urlError = validateRelayUrl(relayUrl);
         out.push(urlError
-            ? { name: "GitHub auth mode", status: "fail", detail: urlError, fix: "Use an https:// relay URL (http only for localhost)." }
-            : { name: "GitHub auth mode", status: "ok", detail: `token relay (${relayUrl})` });
+            ? { name: "GitHub auth mode", status: "fail", detail: urlError, group: "GitHub", fix: "Use an https:// relay URL (http only for localhost)." }
+            : { name: "GitHub auth mode", status: "ok", detail: `token relay (${relayUrl})`, group: "GitHub" });
         if (!relayToken) {
             out.push({
                 name: "Relay credential",
                 status: "fail",
                 detail: `${RELAY_TOKEN_KEY} is not set`,
+                group: "GitHub",
                 fix: `Set ${RELAY_TOKEN_KEY} to the relay credential issued for your installation.`,
             });
         }
         else {
-            out.push({ name: "Relay credential", status: "ok", detail: `${RELAY_TOKEN_KEY} is set` });
+            out.push({ name: "Relay credential", status: "ok", detail: `${RELAY_TOKEN_KEY} is set`, group: "GitHub" });
         }
         return out;
     }
     // App mode (default).
-    out.push({ name: "GitHub auth mode", status: "ok", detail: "GitHub App (own/shared app)" });
+    out.push({ name: "GitHub auth mode", status: "ok", detail: "GitHub App (own/shared app)", group: "GitHub" });
     const appId = val("GH_APP_ID");
     const installationId = val("GH_INSTALLATION_ID");
     out.push(isPlaceholder(appId)
-        ? { name: "GH_APP_ID", status: "fail", detail: "missing or placeholder", fix: "Set GH_APP_ID from your GitHub App settings." }
-        : { name: "GH_APP_ID", status: "ok", detail: appId });
+        ? { name: "GH_APP_ID", status: "fail", detail: "missing or placeholder", group: "GitHub", fix: "Set GH_APP_ID from your GitHub App settings." }
+        : { name: "GH_APP_ID", status: "ok", detail: appId, group: "GitHub" });
     out.push(isPlaceholder(installationId)
-        ? { name: "GH_INSTALLATION_ID", status: "fail", detail: "missing or placeholder", fix: "Set GH_INSTALLATION_ID for the App's installation on your account/org." }
-        : { name: "GH_INSTALLATION_ID", status: "ok", detail: installationId });
+        ? { name: "GH_INSTALLATION_ID", status: "fail", detail: "missing or placeholder", group: "GitHub", fix: "Set GH_INSTALLATION_ID for the App's installation on your account/org." }
+        : { name: "GH_INSTALLATION_ID", status: "ok", detail: installationId, group: "GitHub" });
     // Private key reachability. Prefer the explicit host mount (HOST_GH_PRIVATE_KEY).
     const hostKey = cfg.hostGhPrivateKey;
     const keyPath = val("GH_PRIVATE_KEY_PATH");
     if (hostKey) {
         if (!existsSync(hostKey)) {
-            out.push({ name: "GitHub App key", status: "fail", detail: `HOST_GH_PRIVATE_KEY (${hostKey}) does not exist` });
+            out.push({ name: "GitHub App key", status: "fail", detail: `HOST_GH_PRIVATE_KEY (${hostKey}) does not exist`, group: "GitHub" });
         }
         else {
             let readable = true;
@@ -293,11 +470,12 @@ function checkGithubAuth(env, cfg) {
             }
             const looksLikePem = readable && /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(safeRead(hostKey));
             out.push(readable && looksLikePem
-                ? { name: "GitHub App key", status: "ok", detail: `${hostKey} (mounted read-only)` }
+                ? { name: "GitHub App key", status: "ok", detail: `${hostKey} (mounted read-only)`, group: "GitHub" }
                 : {
                     name: "GitHub App key",
                     status: "fail",
                     detail: readable ? `${hostKey} does not look like a PEM private key` : `${hostKey} is not readable`,
+                    group: "GitHub",
                 });
         }
     }
@@ -306,6 +484,7 @@ function checkGithubAuth(env, cfg) {
             name: "GitHub App key",
             status: "fail",
             detail: "no private key configured",
+            group: "GitHub",
             fix: "Set HOST_GH_PRIVATE_KEY to your .pem host path (recommended), or stage the key under data/ and set GH_PRIVATE_KEY_PATH.",
         });
     }
@@ -314,11 +493,196 @@ function checkGithubAuth(env, cfg) {
             name: "GitHub App key",
             status: "warn",
             detail: `GH_PRIVATE_KEY_PATH=${keyPath} — reachability inside the container not verified`,
+            group: "GitHub",
             fix: "Prefer HOST_GH_PRIVATE_KEY (bind-mounts the key), or ensure this path resolves inside the container (e.g. under data/).",
         });
     }
     return out;
 }
+/**
+ * Validate the prerequisites for the resolved GitHub event intake mode.
+ * Reuses the shared validateIntakeModePrerequisites helper so `propr check`
+ * and the backend boot path agree on what each mode requires.
+ */
+function checkGithubIntakeMode(env) {
+    const val = (k) => process.env[k] ?? env[k];
+    const out = [];
+    // `propr check` is a diagnostic command: a bad value for one variable must
+    // surface as a structured failure, never abort the whole run. Both resolvers
+    // are therefore guarded — resolveGithubAuthMode is side-effect free today, but
+    // guarding it keeps the check resilient if its contract ever changes.
+    // Default the relay URL (token-only stacks rely on the hosted default) so the
+    // resolved auth mode matches the backend; see checkGithubAuth above.
+    const relayUrl = val(RELAY_URL_KEY)?.trim() || DEFAULT_PROPR_GH_RELAY_URL;
+    let authMode;
+    try {
+        ({ mode: authMode } = resolveGithubAuthMode({
+            demoMode: isTruthy(val("PROPR_DEMO_MODE")),
+            ghAuthMode: val("GH_AUTH_MODE"),
+            relayUrl,
+            relayToken: val(RELAY_TOKEN_KEY),
+            appId: val("GH_APP_ID"),
+            privateKeyPath: val("GH_PRIVATE_KEY_PATH"),
+            installationId: val("GH_INSTALLATION_ID"),
+        }));
+    }
+    catch (error) {
+        out.push({
+            name: "GitHub intake mode",
+            status: "fail",
+            detail: error instanceof Error ? error.message : String(error),
+            group: "GitHub",
+            fix: 'Set GH_AUTH_MODE to "app", "relay", or "demo" (or leave it unset to auto-detect).',
+        });
+        return out;
+    }
+    let intakeMode;
+    // Surface the resolver's own warnings (e.g. the ENABLE_GITHUB_WEBHOOKS
+    // deprecation notice the daemon/API log at boot) so `propr check` does not
+    // silently drop the migration feedback the backend would emit.
+    let resolverWarnings = [];
+    try {
+        ({ mode: intakeMode, warnings: resolverWarnings } = resolveGithubEventIntakeMode({
+            eventIntakeMode: val("GITHUB_EVENT_INTAKE_MODE"),
+            enableGithubWebhooks: val("ENABLE_GITHUB_WEBHOOKS"),
+        }));
+    }
+    catch (error) {
+        out.push({
+            name: "GitHub intake mode",
+            status: "fail",
+            detail: error instanceof Error ? error.message : String(error),
+            group: "GitHub",
+            fix: 'Set GITHUB_EVENT_INTAKE_MODE to "routing_websocket", "polling", or "direct_webhook".',
+        });
+        return out;
+    }
+    for (const warning of resolverWarnings) {
+        out.push({ name: "GitHub intake mode", status: "warn", detail: warning, group: "GitHub" });
+    }
+    const { valid, errors, warnings } = validateIntakeModePrerequisites({
+        intakeMode,
+        authMode,
+        routingUrl: val("PROPR_ROUTING_URL"),
+        relayUrl,
+        relayToken: val(RELAY_TOKEN_KEY),
+        webhookSecret: val("GH_WEBHOOK_SECRET"),
+    });
+    for (const warning of warnings) {
+        out.push({ name: "GitHub intake mode", status: "warn", detail: warning, group: "GitHub" });
+    }
+    for (const error of errors) {
+        out.push({ name: "GitHub intake mode", status: "fail", detail: error, group: "GitHub" });
+    }
+    if (valid) {
+        out.push({ name: "GitHub intake mode", status: "ok", detail: intakeMode, group: "GitHub" });
+    }
+    return out;
+}
+/**
+ * Surface the routing intake configuration and, when the backend is reachable,
+ * its live connection state. routing_websocket is the default intake mode, so
+ * `propr check` reports the routing URL plus the daemon's WebSocket connectivity,
+ * last delivery id, and last ACK to make a default deployment diagnosable.
+ *
+ * The live state is best-effort: it comes from GET /api/status (published there
+ * by the daemon), so a host check run before the stack is up simply omits it
+ * rather than failing.
+ */
+async function checkRoutingDiagnostics(env) {
+    const val = (k) => process.env[k] ?? env[k];
+    const out = [];
+    let intakeMode;
+    try {
+        ({ mode: intakeMode } = resolveGithubEventIntakeMode({
+            eventIntakeMode: val("GITHUB_EVENT_INTAKE_MODE"),
+            enableGithubWebhooks: val("ENABLE_GITHUB_WEBHOOKS"),
+        }));
+    }
+    catch {
+        // An invalid mode is already reported by checkGithubIntakeMode; nothing to add.
+        return out;
+    }
+    // Routing diagnostics only apply to the routing_websocket intake path.
+    if (intakeMode !== "routing_websocket")
+        return out;
+    // Config-level routing URL (offline-safe). A missing/invalid URL is already
+    // reported as a failure by the mode prerequisites check, so only show it here
+    // when it is present to avoid duplicating that failure.
+    const routingUrl = val("PROPR_ROUTING_URL");
+    if (routingUrl && routingUrl.trim() !== "") {
+        out.push({ name: "Routing URL", status: "ok", detail: routingUrl, group: "GitHub" });
+    }
+    // Live routing state from the running backend (best-effort, short timeout).
+    // A stopped local backend rejects immediately (ECONNREFUSED); the timeout only
+    // bounds the wait when the configured API URL is reachable but slow, so keep it
+    // tight to avoid a noticeable stall during offline/pre-start checks.
+    try {
+        const client = await createApiClient({ defaultTimeout: 1000 });
+        const status = await getSystemStatus(client);
+        const routing = status.routing;
+        if (routing) {
+            out.push(routing.connected
+                ? { name: "Routing WebSocket", status: "ok", detail: "connected to relay", group: "GitHub" }
+                : {
+                    name: "Routing WebSocket",
+                    status: "warn",
+                    detail: "disconnected — daemon is not connected to the routing relay",
+                    group: "GitHub",
+                    fix: "Check the daemon logs and that PROPR_ROUTING_URL / PROPR_GH_RELAY_TOKEN are valid.",
+                });
+            out.push({
+                name: "Last delivery ID",
+                status: "ok",
+                detail: routing.lastDeliveryId ?? "no deliveries received yet",
+                group: "GitHub",
+            });
+            out.push({
+                name: "Last ACK",
+                status: "ok",
+                detail: formatRoutingTimestamp(routing.lastAckAt),
+                group: "GitHub",
+            });
+        }
+        else {
+            // The backend answered but published no routing state. In routing_websocket
+            // mode that is the *default intake path*, so its absence is not benign: the
+            // daemon's routing publisher is not running (or the daemon is down), which
+            // means events are not being received and the path is not diagnosable. Warn
+            // rather than stay silent so a half-up routing deployment is visible.
+            out.push({
+                name: "Routing WebSocket",
+                status: "warn",
+                detail: "backend reachable but no routing state published — the daemon routing intake/publisher may not be running",
+                group: "GitHub",
+                fix: "Ensure the daemon is running in routing_websocket mode and check its logs and PROPR_ROUTING_URL / PROPR_GH_RELAY_TOKEN.",
+            });
+        }
+    }
+    catch {
+        // Backend not reachable (stack down or not logged in): live routing state is
+        // unavailable. This is the normal case for a pre-start / fresh-install check, so
+        // surface it as informational ("ok") rather than a warning — a valid offline
+        // setup should not light up a yellow routing warning just because the stack is
+        // not running yet. Live WebSocket state appears once the stack is up.
+        out.push({
+            name: "Routing WebSocket",
+            status: "ok",
+            detail: "live state unavailable — start the stack to read routing WebSocket state",
+            group: "GitHub",
+        });
+    }
+    return out;
+}
+// `lastAckAt` comes from a live Redis value the daemon publishes; a stale or
+// malformed entry must not surface as "Invalid Date" in operator output. Parse it
+// and fall back to the raw string when it is not a usable timestamp.
+function formatRoutingTimestamp(value) {
+    if (!value)
+        return "no ACK sent yet";
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleString();
+}
 function safeRead(path) {
     try {
         return readFileSync(path, "utf-8").slice(0, 200);
@@ -327,53 +691,594 @@ function safeRead(path) {
         return "";
     }
 }
-/** Print a human-readable check table. */
+function shouldUseColor() {
+    return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;
+}
+function color(text, enabled, ...codes) {
+    return enabled ? `${codes.join("")}${text}${ANSI.reset}` : text;
+}
+function statusColor(status) {
+    if (status === "ok")
+        return ANSI.green;
+    if (status === "warn")
+        return ANSI.yellow;
+    return ANSI.red;
+}
+function formatStatus(status, colorEnabled) {
+    const text = `${STATUS_GLYPH[status]} ${STATUS_LABEL[status].padEnd(4)}`;
+    return color(text, colorEnabled, statusColor(status), ANSI.bold);
+}
+export function countStatuses(results) {
+    const counts = { ok: 0, warn: 0, fail: 0 };
+    for (const result of results)
+        counts[result.status]++;
+    return counts;
+}
+function envSkipsRemoteImageCheck(env = process.env) {
+    return env.PROPR_SKIP_REMOTE_IMAGE_CHECK === "true" || env.PROPR_SKIP_REMOTE_IMAGE_CHECK === "1";
+}
+function jsonResult(result) {
+    // JSON intentionally stays data-only/stable: UI grouping and remediation
+    // metadata are for human renderers and interactive prompts.
+    const out = {
+        name: result.name,
+        status: result.status,
+        detail: result.detail,
+    };
+    if (result.fix)
+        out.fix = result.fix;
+    return out;
+}
+export function plural(count, singular) {
+    return `${count} ${singular}${count === 1 ? "" : "s"}`;
+}
+function formatSummary(counts, colorEnabled) {
+    const failures = color(plural(counts.fail, "failure"), colorEnabled && counts.fail > 0, ANSI.red, ANSI.bold);
+    const warnings = color(plural(counts.warn, "warning"), colorEnabled && counts.warn > 0, ANSI.yellow, ANSI.bold);
+    const ok = color(`${counts.ok} ok`, colorEnabled, ANSI.green);
+    return `Summary: ${failures}, ${warnings}, ${ok}`;
+}
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function warnBillableValidationJson() {
+    console.error("Warning: agent validation makes real, billable LLM calls even with --json. Restrict with --agents when needed.");
+}
+function printAgentValidationHint() {
+    console.log("");
+    console.log("To validate agents with live, billable LLM calls, run `propr check agents` or `propr check all`.");
+}
+/** Static, non-interactive renderer (pipes, CI, NO_COLOR). */
+function printStaticChecks(outcome, showRemediationHint) {
+    printChecks(outcome);
+    if (showRemediationHint) {
+        console.log("");
+        console.log("Run `propr check --fix` to review interactive remediation options.");
+    }
+}
+/**
+ * Interactive TTY flow: render a live check pass, and (with --fix) loop —
+ * applying the selected remediation outside the Ink tree, then re-rendering a
+ * fresh pass — until the user quits or no actions remain. Falls back to the
+ * static renderer + readline prompts if the terminal can't drive the live UI.
+ */
+async function runChecksInteractive(runOptions, fix, showAgentValidationHint) {
+    try {
+        const { renderLiveChecks } = await import("../tui/app.js");
+        let lastOutcome;
+        while (true) {
+            const { outcome, selectedKey } = await renderLiveChecks(runOptions, {
+                fix,
+                showAgentValidationHint,
+                getActions: collectRemediationActions,
+            });
+            lastOutcome = outcome ?? lastOutcome;
+            if (!fix || !selectedKey || !outcome)
+                return { outcome: lastOutcome };
+            const action = collectRemediationActions(outcome).find((a) => a.key === selectedKey);
+            if (!action)
+                return { outcome: lastOutcome };
+            console.log("");
+            const result = await action.run();
+            if (!result.ok) {
+                console.log("Remediation did not fully complete. Continuing with the current check results.");
+            }
+            if (!result.changed)
+                return { outcome: lastOutcome };
+            // Loop: re-run a fresh live pass to reflect changes and offer more fixes.
+        }
+    }
+    catch (error) {
+        if (!isLiveRendererFallbackError(error))
+            throw error;
+        // The terminal can't support the live UI (e.g. raw mode unavailable): fall
+        // back to the static renderer and readline-based prompts (no Ink to clobber).
+        const outcome = await runChecks(runOptions);
+        if (fix) {
+            printChecks(outcome);
+            return { outcome: await runRemediationPrompts(outcome, runOptions) };
+        }
+        printStaticChecks(outcome, collectRemediationActions(outcome).length > 0);
+        if (showAgentValidationHint)
+            printAgentValidationHint();
+        return { outcome };
+    }
+}
+function isLiveRendererFallbackError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /raw mode|setRawMode|stdin.*tty|not a tty|ink/i.test(message);
+}
+function collectRemediationActions(outcome) {
+    const actions = [];
+    const remediations = outcome.results
+        .filter((result) => result.status !== "ok")
+        .map((result) => result.remediation)
+        .filter((remediation) => Boolean(remediation));
+    if (remediations.some((remediation) => remediation.kind === "init-stack")) {
+        actions.push({
+            key: "init-stack",
+            label: "Show stack initialization guidance",
+            detail: `Create the stack root and .env with: propr init stack --root ${outcome.rootDir}`,
+            confirm: "Show stack initialization guidance?",
+            run: async () => {
+                console.log("");
+                console.log("Stack root/.env is missing. Run:");
+                console.log(`  propr init stack --root ${outcome.rootDir}`);
+                console.log("Then review .env and run `propr check` again.");
+                return { changed: false, ok: true };
+            },
+        });
+    }
+    if (remediations.some((remediation) => remediation.kind === "start-docker")) {
+        actions.push({
+            key: "start-docker",
+            label: "Show Docker daemon guidance",
+            detail: "Print commands and checks for starting Docker or fixing daemon access.",
+            confirm: "Show Docker daemon guidance?",
+            run: async () => {
+                console.log("");
+                console.log("Docker is installed but the daemon is not reachable.");
+                console.log("Start Docker, then make sure this user can run `docker info` without failing.");
+                console.log("Common Linux command:");
+                console.log("  sudo systemctl start docker");
+                console.log("If the socket exists but access fails, add your user to the docker group and start a new shell.");
+                return { changed: false, ok: true };
+            },
+        });
+    }
+    const imageRemediations = remediations
+        .filter((remediation) => remediation.kind === "pull-image")
+        .filter((remediation, index, all) => all.findIndex((other) => other.tag === remediation.tag) === index);
+    if (imageRemediations.length > 0) {
+        actions.push({
+            key: "pull-images",
+            label: `Pull ${plural(imageRemediations.length, "Docker image")}`,
+            detail: imageRemediations.map((remediation) => remediation.tag).join(", "),
+            confirm: `Pull ${plural(imageRemediations.length, "Docker image")} now?`,
+            run: async () => pullMissingImages(imageRemediations),
+        });
+    }
+    const credentialRemediations = remediations
+        .filter((remediation) => remediation.kind === "add-agent-credential")
+        .filter((remediation) => existsSync(remediation.path))
+        .filter((remediation, index, all) => all.findIndex((other) => other.envKey === remediation.envKey) === index);
+    if (credentialRemediations.length > 0 && existsSync(outcome.cfg.envFileLocal)) {
+        actions.push({
+            key: "add-agent-credentials",
+            label: `Add ${plural(credentialRemediations.length, "detected agent credential directory")} to .env`,
+            detail: credentialRemediations.map((remediation) => `${remediation.envKey}=${remediation.path}`).join(", "),
+            confirm: `Write ${plural(credentialRemediations.length, "agent credential directory")} to ${outcome.cfg.envFileLocal}?`,
+            run: async () => addAgentCredentials(outcome, credentialRemediations),
+        });
+    }
+    return actions;
+}
+async function pullMissingImages(remediations) {
+    let changed = false;
+    let ok = true;
+    const orch = await loadOrchestrator();
+    for (const remediation of remediations) {
+        console.log(`Pulling ${remediation.tag}...`);
+        const pulled = orch.docker(["pull", remediation.tag], { capture: true });
+        if (pulled.status === 0) {
+            changed = true;
+            try {
+                orch.tagAgentLatest(remediation.imageKey, remediation.tag);
+                console.log(`  ok: ${remediation.tag}`);
+            }
+            catch (error) {
+                ok = false;
+                console.error(`  failed: ${remediation.tag}: ${error.message}`);
+            }
+        }
+        else {
+            ok = false;
+            const reason = (pulled.stderr || pulled.stdout || "docker pull failed").trim().split("\n")[0];
+            console.error(`  failed: ${remediation.tag}: ${reason}`);
+        }
+    }
+    return { changed, ok };
+}
+async function addAgentCredentials(outcome, remediations) {
+    const vars = {};
+    for (const remediation of remediations) {
+        if (existsSync(remediation.path)) {
+            vars[remediation.envKey] = remediation.path;
+        }
+    }
+    if (Object.keys(vars).length === 0) {
+        console.log("No detected credential directories still exist on this host.");
+        return { changed: false, ok: false };
+    }
+    upsertEnvVars(outcome.cfg.envFileLocal, vars);
+    console.log(`Updated ${outcome.cfg.envFileLocal}:`);
+    for (const [key, value] of Object.entries(vars)) {
+        console.log(`  ${key}=${value}`);
+    }
+    return { changed: true, ok: true };
+}
+async function confirmAction(rl, prompt) {
+    const answer = (await rl.question(`${prompt} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+}
+async function promptForAction(rl, actions) {
+    console.log("");
+    console.log("Available remediations:");
+    actions.forEach((action, index) => {
+        console.log(`  ${index + 1}. ${action.label}`);
+        console.log(`     ${action.detail}`);
+    });
+    console.log("  q. Quit");
+    const answer = (await rl.question("Choose an action: ")).trim().toLowerCase();
+    if (answer === "" || answer === "q" || answer === "quit")
+        return undefined;
+    const selected = Number(answer);
+    if (!Number.isInteger(selected) || selected < 1 || selected > actions.length) {
+        console.log("Invalid selection.");
+        return promptForAction(rl, actions);
+    }
+    return actions[selected - 1];
+}
+async function runRemediationPrompts(outcome, options) {
+    let current = outcome;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        while (true) {
+            const actions = collectRemediationActions(current);
+            if (actions.length === 0) {
+                console.log("");
+                console.log("No actionable remediations found.");
+                return current;
+            }
+            const action = await promptForAction(rl, actions);
+            if (!action)
+                return current;
+            if (!(await confirmAction(rl, action.confirm))) {
+                console.log("Skipped.");
+                continue;
+            }
+            const result = await action.run();
+            if (!result.ok) {
+                console.log("Remediation did not fully complete. Continuing with the current check results.");
+            }
+            if (result.changed) {
+                current = await runChecks(options);
+                printChecks(current);
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Print human-readable checks grouped by subsystem. */
 export function printChecks(outcome) {
+    const colorEnabled = shouldUseColor();
+    const counts = countStatuses(outcome.results);
     console.log("");
-    console.log(`ProPR environment check  (stack root: ${outcome.rootDir})`);
+    console.log(`${color("ProPR environment check", colorEnabled, ANSI.bold)}  ${color(`(stack root: ${outcome.rootDir})`, colorEnabled, ANSI.dim)}`);
+    console.log(formatSummary(counts, colorEnabled));
     console.log("─".repeat(60));
-    for (const r of outcome.results) {
-        const glyph = STATUS_GLYPH[r.status];
-        console.log(`${glyph}  ${r.name.padEnd(24)} ${r.detail}`);
-        if (r.fix && r.status !== "ok") {
-            console.log(`   ↳ ${r.fix}`);
+    let printedGroup = false;
+    for (const group of CHECK_GROUPS) {
+        const groupResults = outcome.results.filter((result) => result.group === group);
+        if (groupResults.length === 0)
+            continue;
+        const groupCounts = countStatuses(groupResults);
+        const nameWidth = Math.max(18, ...groupResults.map((result) => result.name.length));
+        if (printedGroup)
+            console.log("");
+        printedGroup = true;
+        const countSuffix = groupCounts.fail > 0 || groupCounts.warn > 0 ? ` (${plural(groupCounts.fail, "failure")}, ${plural(groupCounts.warn, "warning")})` : "";
+        console.log(color(`${GROUP_TITLES[group]}${countSuffix}`, colorEnabled, ANSI.cyan, ANSI.bold));
+        console.log(color(`  ${GROUP_DESCRIPTIONS[group]}`, colorEnabled, ANSI.dim));
+        for (const r of groupResults) {
+            console.log(`  ${formatStatus(r.status, colorEnabled)} ${r.name.padEnd(nameWidth)}  ${r.detail}`);
+            if (r.fix && r.status !== "ok") {
+                console.log(`         ${color("↳", colorEnabled, ANSI.dim)} ${r.fix}`);
+            }
+        }
+    }
+    const ungrouped = outcome.results.filter((result) => !result.group);
+    if (ungrouped.length > 0) {
+        const nameWidth = Math.max(18, ...ungrouped.map((result) => result.name.length));
+        if (printedGroup)
+            console.log("");
+        console.log(color("Other", colorEnabled, ANSI.cyan, ANSI.bold));
+        for (const r of ungrouped) {
+            console.log(`  ${formatStatus(r.status, colorEnabled)} ${r.name.padEnd(nameWidth)}  ${r.detail}`);
+            if (r.fix && r.status !== "ok") {
+                console.log(`         ${color("↳", colorEnabled, ANSI.dim)} ${r.fix}`);
+            }
         }
     }
     console.log("─".repeat(60));
-    const counts = { ok: 0, warn: 0, fail: 0 };
-    for (const r of outcome.results)
-        counts[r.status]++;
-    console.log(`${counts.ok} ok, ${counts.warn} warning(s), ${counts.fail} failure(s)`);
+    console.log(formatSummary(counts, colorEnabled));
+}
+/** Status badge for an agent cell: plain text + optional ANSI color code. */
+function agentBadge(cell) {
+    if (!cell)
+        return { text: "n/a" };
+    if (cell.status === "ok")
+        return { text: "✓ ok", code: ANSI.green };
+    if (cell.status === "fail")
+        return { text: "✗ fail", code: ANSI.red };
+    return { text: "— skip", code: ANSI.yellow };
+}
+const DASH = "—";
+const driftText = (r) => r.drift ?? (r.hostVersion && r.imageVersion ? "same" : "");
+/** Static (non-TTY) agent table — the live equivalent is AgentTableApp. */
+function printAgentTable(rows, colorEnabled) {
+    const pad = (s, w) => s.padEnd(w);
+    const colored = (text, w, code) => (code ? color(pad(text, w), colorEnabled, code) : pad(text, w));
+    const w = {
+        agent: Math.max("Agent".length, ...rows.map((r) => r.type.length)),
+        host: Math.max("Host ver".length, ...rows.map((r) => (r.hostVersion ?? DASH).length)),
+        image: Math.max("Image ver".length, ...rows.map((r) => (r.imageVersion ?? DASH).length)),
+        drift: Math.max("Drift".length, ...rows.map((r) => driftText(r).length)),
+        hstat: Math.max("Host".length, ...rows.map((r) => agentBadge(r.host).text.length)),
+    };
+    console.log("");
+    console.log(`  ${color([pad("Agent", w.agent), pad("Host ver", w.host), pad("Image ver", w.image), pad("Drift", w.drift), pad("Host", w.hstat), "Image"].join("  "), colorEnabled, ANSI.bold)}`);
+    for (const r of rows) {
+        const hb = agentBadge(r.host);
+        const ib = agentBadge(r.image);
+        const drift = driftText(r);
+        const driftCode = drift === "older" ? ANSI.yellow : drift && drift !== "same" ? ANSI.dim : undefined;
+        console.log(`  ${pad(r.type, w.agent)}  ${pad(r.hostVersion ?? DASH, w.host)}  ${pad(r.imageVersion ?? DASH, w.image)}  ${colored(drift, w.drift, driftCode)}  ${colored(hb.text, w.hstat, hb.code)}  ${colored(ib.text, ib.text.length, ib.code)}`);
+    }
+}
+/** Raw host/image responses (and errors) per agent, for debugging. */
+function printAgentResponses(rows, colorEnabled) {
+    const agentW = Math.max("Agent".length, ...rows.map((r) => r.type.length));
+    const pad = (s, len) => s.padEnd(len);
+    console.log("");
+    console.log(`  ${color("Responses", colorEnabled, ANSI.bold)}`);
+    for (const r of rows) {
+        const entries = [];
+        if (r.host)
+            entries.push(["host", r.host]);
+        entries.push(["image", r.image]);
+        entries.forEach(([level, cell], i) => {
+            console.log(`  ${pad(i === 0 ? r.type : "", agentW)}  ${pad(level, 5)}  ${cell.detail}`);
+            if (cell.fix)
+                console.log(`  ${pad("", agentW)}  ${pad("", 5)}  ${color("↳", colorEnabled, ANSI.dim)} ${cell.fix}`);
+        });
+    }
+}
+/** Render Agent Tank subscription usage (or an install hint when absent). */
+function printAgentTankUsage(usage, colorEnabled) {
+    console.log("");
+    console.log(color("Subscription Usage (Agent Tank)", colorEnabled, ANSI.cyan, ANSI.bold));
+    if (!usage.installed) {
+        console.log(color("  Not installed — track Claude/Codex/Antigravity plan usage per task with:", colorEnabled, ANSI.dim));
+        console.log("  npm install -g agent-tank");
+        return;
+    }
+    console.log(color(`  agent-tank ${usage.version ?? ""}`.trimEnd(), colorEnabled, ANSI.dim));
+    if (usage.error) {
+        console.log(`  ${color("!", colorEnabled, ANSI.yellow)} could not read usage: ${usage.error}`);
+        return;
+    }
+    const agents = Object.keys(usage.usage ?? {});
+    if (agents.length === 0) {
+        console.log(color("  No agents reported.", colorEnabled, ANSI.dim));
+        return;
+    }
+    const nameWidth = Math.max(5, ...agents.map((a) => a.length));
+    for (const name of agents) {
+        const entry = usage.usage[name];
+        if (entry?.error) {
+            console.log(`  ${name.padEnd(nameWidth)}  ${color(entry.error, colorEnabled, ANSI.yellow)}`);
+            continue;
+        }
+        const metrics = Object.values(entry?.usage ?? {});
+        if (metrics.length === 0) {
+            console.log(`  ${name.padEnd(nameWidth)}  (no data)`);
+            continue;
+        }
+        metrics.forEach((m, i) => {
+            const label = m.label ?? "usage";
+            const pct = m.percent ?? m.percentUsed;
+            const resets = m.resetsIn ? ` (resets ${m.resetsIn})` : "";
+            console.log(`  ${(i === 0 ? name : "").padEnd(nameWidth)}  ${label}: ${pct ?? "?"}%${resets}`);
+        });
+    }
+}
+/**
+ * Run agent validation and print results. Uses a live, streaming table on an
+ * interactive terminal; a static table otherwise. Raw responses follow. Returns
+ * true if any agent failed. Loads its own orchestrator/config so it can run
+ * after the main check.
+ */
+async function runAndPrintValidation(runOptions) {
+    const colorEnabled = shouldUseColor();
+    const configManager = await createConfigManager();
+    const { orch, cfg } = await getHostConfig({ configManager, root: runOptions.root });
+    console.log("");
+    console.log(color("Agent Validation", colorEnabled, ANSI.cyan, ANSI.bold));
+    console.log(color("  Live test calls for configured agents (host CLI + image) to confirm auth works", colorEnabled, ANSI.dim));
+    console.log("");
+    // Read Agent Tank subscription usage concurrently with the validation (it is
+    // slow and independent), then render it after the responses.
+    const tankUsagePromise = getAgentTankUsage();
+    let rows;
+    const runStaticValidation = async () => {
+        rows = await validateAgents(orch, cfg, {
+            agents: runOptions.agents,
+            onProgress: (message) => console.log(color(`  … ${message}`, colorEnabled, ANSI.dim)),
+        });
+        if (rows.length > 0)
+            printAgentTable(rows, colorEnabled);
+        return rows;
+    };
+    if (isInteractiveTerminal() && process.env.NO_COLOR === undefined) {
+        try {
+            const { renderAgentValidation } = await import("../tui/app.js");
+            rows = await renderAgentValidation(orch, cfg, runOptions.agents);
+        }
+        catch (error) {
+            if (!isLiveRendererFallbackError(error))
+                throw error;
+            rows = await runStaticValidation();
+        }
+    }
+    else {
+        rows = await runStaticValidation();
+    }
+    if (rows.length === 0)
+        return false;
+    printAgentResponses(rows, colorEnabled);
+    printAgentTankUsage(await tankUsagePromise, colorEnabled);
+    return rows.some((r) => r.host?.status === "fail" || r.image.status === "fail");
 }
 /** Creates the `check` command. */
 export function createCheckCommand() {
     return new Command("check")
-        .description("Verify the host is ready to run a local ProPR stack (Docker, images, agents)")
+        .description("Verify the host is ready to run a local ProPR stack")
+        .argument("[mode]", "what to check: system (default) | agents | all", "system")
         .option("--root <dir>", "Stack root directory (where .env/data/logs/repos live)")
         .option("--verify", "Also run an image/CLI smoke test for each agent (slower)")
-        .option("--agents <list>", "Comma-separated agent types to --verify (default: all)")
+        .option("--agents <list>", "Comma-separated agent types to validate (default: configured stack agents)")
+        .option("--skip-remote-image-check", "Skip registry image freshness checks (also set by PROPR_SKIP_REMOTE_IMAGE_CHECK=1)")
         .option("--json", "Output raw JSON")
+        .option("--fix", "Offer interactive remediation prompts for actionable issues")
+        .option("--validate-agents", "Append live agent validation to a system check (makes billable LLM calls; same as `check all`)")
         .addHelpText("after", `
+Modes:
+  system   Docker, images, stack, agent credentials, GitHub, config (default)
+  agents   Live test calls for configured agents (host CLI + image); makes billable LLM calls
+  all      Everything: system checks followed by billable agent validation
+
 Examples:
-  $ propr check
-  $ propr check --verify
-  $ propr check --verify --agents claude,codex
+  $ propr check                 # system checks
+  $ propr check agents          # only validate agents (billable LLM calls)
+  $ propr check all             # system checks + billable agent validation
+  $ propr check --fix
+  $ propr check agents --agents claude,codex
   $ propr check --json
+
+Notes:
+  "check all", "check agents", and --validate-agents run a real prompt through
+  configured agents' host CLIs and Docker images (mounts credentials, makes
+  billable LLM calls). This is also true with --json. Override with --agents.
+  Use --skip-remote-image-check or PROPR_SKIP_REMOTE_IMAGE_CHECK=1 for offline image checks.
 `)
-        .action(async (options) => {
+        .action(async (mode, options) => {
         try {
-            const outcome = await runChecks({
+            const MODES = ["system", "agents", "all"];
+            if (!MODES.includes(mode)) {
+                console.error(`Error: unknown check mode '${mode}'. Use one of: ${MODES.join(", ")}.`);
+                process.exit(1);
+            }
+            if (options.json && options.fix) {
+                console.error("Error: --json cannot be combined with --fix; JSON output is data-only and never prompts.");
+                process.exit(1);
+            }
+            const runOptions = {
                 root: options.root,
                 verify: options.verify,
                 agents: options.agents ? options.agents.split(",").map((s) => s.trim()).filter(Boolean) : undefined,
-            });
+                skipRemoteImageCheck: options.skipRemoteImageCheck,
+            };
+            const { agents: agentFilter, unknown } = validateAgentFilter(runOptions.agents);
+            if (unknown.length > 0) {
+                console.error(`Error: unknown agent type${unknown.length === 1 ? "" : "s"} '${unknown.join(", ")}'. Valid agents: ${validAgentTypes().join(", ")}.`);
+                process.exit(1);
+            }
+            runOptions.agents = agentFilter.length ? agentFilter : undefined;
+            // `check agents`: only agent validation, no system checks.
+            if (mode === "agents") {
+                if (options.fix && !options.json) {
+                    console.error("Note: --fix has no remediation flow for `propr check agents`; running validation only.");
+                }
+                if (options.json) {
+                    warnBillableValidationJson();
+                    const { cfg, rootDir, orch } = await getHostConfig({ configManager: await createConfigManager(), root: runOptions.root });
+                    const rows = await validateAgents(orch, cfg, { agents: runOptions.agents });
+                    const results = agentRowsToChecks(rows);
+                    printOutput({ rootDir, results: results.map(jsonResult) }, true);
+                    if (results.some((r) => r.status === "fail"))
+                        process.exit(1);
+                    return;
+                }
+                if (await runAndPrintValidation(runOptions))
+                    process.exit(1);
+                return;
+            }
+            if (options.fix && !isInteractiveTerminal()) {
+                console.error("Error: --fix requires an interactive terminal.");
+                process.exit(1);
+            }
+            // `check` / `check system` / `check all`. Agents run when mode=all or --validate-agents.
+            const runAgents = mode === "all" || Boolean(options.validateAgents);
+            // JSON: data-only; agent results merged in when requested.
             if (options.json) {
-                printOutput({ rootDir: outcome.rootDir, results: outcome.results }, true);
+                const outcome = await runChecks(runOptions);
+                let results = outcome.results;
+                if (runAgents) {
+                    warnBillableValidationJson();
+                    const { orch, cfg } = await getHostConfig({ configManager: await createConfigManager(), root: runOptions.root });
+                    const rows = await validateAgents(orch, cfg, { agents: runOptions.agents });
+                    results = [...results, ...agentRowsToChecks(rows)];
+                }
+                printOutput({ rootDir: outcome.rootDir, results: results.map(jsonResult) }, true);
+                if (results.some((r) => r.status === "fail"))
+                    process.exit(1);
+                return;
             }
-            else {
-                printChecks(outcome);
+            // Non-interactive (pipes, CI, NO_COLOR): static one-shot report.
+            // With --fix on a TTY, NO_COLOR only disables Ink/color; readline prompts still run.
+            if (!isInteractiveTerminal() || process.env.NO_COLOR !== undefined) {
+                const outcome = await runChecks(runOptions);
+                if (options.fix) {
+                    printChecks(outcome);
+                    const remediated = await runRemediationPrompts(outcome, runOptions);
+                    let anyFail = remediated.anyFail;
+                    if (runAgents)
+                        anyFail = (await runAndPrintValidation(runOptions)) || anyFail;
+                    if (anyFail)
+                        process.exit(1);
+                    return;
+                }
+                printStaticChecks(outcome, !options.fix && collectRemediationActions(outcome).length > 0);
+                let anyFail = outcome.anyFail;
+                if (runAgents)
+                    anyFail = (await runAndPrintValidation(runOptions)) || anyFail;
+                else
+                    printAgentValidationHint();
+                if (anyFail)
+                    process.exit(1);
+                return;
+            }
+            // Interactive TTY: live, streaming view (+ in-app remediation with --fix,
+            // plus a hint showing how to opt into billable agent validation).
+            const { outcome } = await runChecksInteractive(runOptions, Boolean(options.fix), !options.fix && !runAgents);
+            let anyFail = outcome?.anyFail ?? false;
+            if (runAgents) {
+                anyFail = (await runAndPrintValidation(runOptions)) || anyFail;
             }
-            if (outcome.anyFail)
+            if (anyFail)
                 process.exit(1);
         }
         catch (error) {