@minasoft/mina-ai-router 0.1.5 → 0.2.1

package/dist/apps/cli/src/index.js

@@ -6,15 +6,20 @@ const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
 const src_1 = require("../../../packages/core/src");
 const src_2 = require("../../../packages/transports/src");
-const statePath = process.env.MINA_ROUTER_STATE ?? (0, node_path_1.join)(process.cwd(), "data", "router-state.json");
-const version = "0.1.4";
-const serverPidPath = process.env.MINA_SERVER_PID ?? (0, node_path_1.join)(process.cwd(), "data", "mair-server.json");
+const statePath = process.env.MINA_ROUTER_STATE ?? (0, src_1.defaultRouterStatePath)();
+const version = (0, src_1.packageVersion)();
+const serverPidPath = process.env.MINA_SERVER_PID ?? (0, src_1.defaultServerPidPath)();
+const agentStaleAfterMs = Number(process.env.MINA_AGENT_STALE_AFTER_MS ?? 15 * 60 * 1000);
 async function main(argv) {
     const command = argv[2];
     if (!command || command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;
     }
+    if (hasHelpFlag(argv.slice(3))) {
+        printCommandHelp(command);
+        return;
+    }
     const context = createContext();
     switch (command) {
         case "version":
@@ -28,23 +33,29 @@ async function main(argv) {
         case "verify":
             runVerify();
             break;
+        case "doctor":
+            await runDoctor(argv.slice(3), context);
+            break;
+        case "setup":
+            runSetup(argv.slice(3));
+            break;
         case "server":
-            handleServerCommand(argv.slice(3));
+            await handleServerCommand(argv.slice(3));
             break;
         case "codex":
-            startVisibleAgent("codex", "codex --no-alt-screen", argv.slice(3), context);
+            await startVisibleAgent("codex", "codex --no-alt-screen", argv.slice(3), context);
             break;
         case "claude":
-            startVisibleAgent("claude", "claude", argv.slice(3), context);
+            await startVisibleAgent("claude", "claude", argv.slice(3), context);
             break;
         case "register":
-            registerAgent(argv.slice(3), context);
+            await registerAgent(argv.slice(3), context);
             break;
         case "agents":
             await listAgents(context);
             break;
         case "agent":
-            await showAgent(argv.slice(3), context);
+            await handleAgent(argv.slice(3), context);
             break;
         case "attach":
             showAttach(argv.slice(3), context);
@@ -62,18 +73,22 @@ async function main(argv) {
             listRequests(argv.slice(3), context);
             break;
         case "request":
-            showRequest(argv.slice(3), context);
+            await handleRequest(argv.slice(3), context);
             break;
         default:
             throw new Error(`Unknown command "${command}". Run "mair help".`);
     }
 }
-function handleServerCommand(args) {
+async function handleServerCommand(args) {
+    if (hasHelpFlag(args)) {
+        printCommandHelp("server");
+        return;
+    }
     const action = args[0] ?? "status";
     const flags = parseFlags(args.slice(1));
     switch (action) {
         case "start":
-            startServer(flags);
+            await startServer(flags);
             break;
         case "stop":
             stopServer();
@@ -85,7 +100,7 @@ function handleServerCommand(args) {
             throw new Error("Usage: mair server <start|stop|status> [--port 3333] [--host 127.0.0.1]");
     }
 }
-function startServer(flags) {
+async function startServer(flags) {
     const current = serverStatus();
     if (current.running) {
         printJson(current);
@@ -95,10 +110,17 @@ function startServer(flags) {
     const host = flags.host ?? process.env.MINA_HTTP_HOST ?? "127.0.0.1";
     const serverPath = (0, node_path_1.join)(__dirname, "../../http-server/src/index.js");
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(serverPidPath), { recursive: true });
+    try {
+        (0, node_fs_1.unlinkSync)(serverPidPath);
+    }
+    catch {
+        // stale pid file may not exist
+    }
     const logPath = flags.log ?? (0, node_path_1.join)((0, node_path_1.dirname)(serverPidPath), "mair-server.log");
+    const logFd = (0, node_fs_1.openSync)(logPath, "a");
     const child = (0, node_child_process_1.spawn)(process.execPath, [serverPath], {
         detached: true,
-        stdio: "ignore",
+        stdio: ["ignore", logFd, logFd],
         env: {
             ...process.env,
             PORT: port,
@@ -106,12 +128,29 @@ function startServer(flags) {
             MINA_ROUTER_STATE: process.env.MINA_ROUTER_STATE ?? statePath,
         },
     });
-    child.unref();
+    (0, node_fs_1.closeSync)(logFd);
     const pid = child.pid;
     if (!pid) {
         throw new Error("Failed to start Mina HTTP server.");
     }
-    sleep(500);
+    let childExit;
+    child.on("exit", (code) => {
+        childExit = { code, signal: null };
+    });
+    try {
+        await waitForServerReadiness({ host, port, expectedStatePath: process.env.MINA_ROUTER_STATE ?? statePath, logPath, pid, getChildExit: () => childExit });
+    }
+    catch (error) {
+        if (isProcessRunning(pid)) {
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch {
+                // child may already be gone
+            }
+        }
+        throw error;
+    }
     (0, node_fs_1.writeFileSync)(serverPidPath, `${JSON.stringify({
         pid,
         port,
@@ -122,8 +161,67 @@ function startServer(flags) {
         mcpUrl: `http://${host}:${port}/mcp`,
         startedAt: new Date().toISOString(),
     }, null, 2)}\n`);
+    child.unref();
     printJson(serverStatus());
 }
+async function waitForServerReadiness(options) {
+    const url = `http://${options.host}:${options.port}/api/health`;
+    const deadline = Date.now() + 5000;
+    let lastError = "";
+    while (Date.now() < deadline) {
+        const childExit = options.getChildExit();
+        if (childExit || !isProcessRunning(options.pid)) {
+            throw new Error(serverStartFailureMessage({
+                url,
+                logPath: options.logPath,
+                cause: childExit
+                    ? `server process exited before readiness (code=${childExit.code ?? "null"}, signal=${childExit.signal ?? "null"})`
+                    : "server process exited before readiness",
+            }));
+        }
+        try {
+            const response = await fetch(url);
+            const text = await response.text();
+            const parsed = safeJson(text);
+            if (response.ok && parsed && typeof parsed.statePath === "string") {
+                if (resolvePath(parsed.statePath) !== resolvePath(options.expectedStatePath)) {
+                    lastError = `readiness endpoint responded from a Mina server for a different state file: ${parsed.statePath}`;
+                }
+                else {
+                    return;
+                }
+            }
+            else {
+                lastError = parsed
+                    ? `readiness endpoint returned HTTP ${response.status} without Mina health state`
+                    : `readiness endpoint did not return Mina JSON: ${truncateText(text, 160)}`;
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await delay(100);
+    }
+    throw new Error(serverStartFailureMessage({
+        url,
+        logPath: options.logPath,
+        cause: `timed out waiting for Mina readiness${lastError ? `: ${lastError}` : ""}`,
+    }));
+}
+function serverStartFailureMessage(input) {
+    const logExcerpt = readLogExcerpt(input.logPath);
+    return [
+        `Mina HTTP server failed to become ready at ${input.url}: ${input.cause}.`,
+        `Log: ${input.logPath}`,
+        logExcerpt ? `Recent log:\n${logExcerpt}` : "Recent log: <empty>",
+    ].join("\n");
+}
+function readLogExcerpt(logPath) {
+    if (!(0, node_fs_1.existsSync)(logPath)) {
+        return "";
+    }
+    return (0, node_fs_1.readFileSync)(logPath, "utf8").split(/\r?\n/).filter(Boolean).slice(-12).join("\n");
+}
 function stopServer() {
     const status = serverStatus();
     if (!status.pid) {
@@ -165,7 +263,7 @@ function isProcessRunning(pid) {
         return false;
     }
 }
-function startVisibleAgent(agentType, defaultCommand, args, context) {
+async function startVisibleAgent(agentType, defaultCommand, args, context) {
     assertCommandAvailable("tmux");
     const flags = parseFlags(args);
     const root = flags.root ?? process.cwd();
@@ -173,39 +271,123 @@ function startVisibleAgent(agentType, defaultCommand, args, context) {
     const id = flags.id ?? sanitizeName(projectName);
     const sessionId = flags.session ?? `${agentType}-${sanitizeName(projectName)}`;
     const startupCommand = flags.command ?? defaultCommand;
+    const permissionProfile = resolvePermissionProfile(agentType, flags["permission-profile"] ?? "default", root);
+    const mcpUrl = matchingLiveServerStatus()?.mcpUrl
+        ?? `http://${process.env.MINA_HTTP_HOST ?? "127.0.0.1"}:${process.env.MINA_HTTP_PORT ?? "3333"}/mcp`;
+    const mcpName = flags["mcp-name"] ?? "mina-ai-router";
+    const explicitConfiguredUrl = flags["mcp-configured-url"];
+    const detectedConfiguredUrl = explicitConfiguredUrl
+        ?? (flags["mcp-configured"] === "true" ? undefined : detectClientMcpConfiguredUrl(agentType, mcpName, mcpUrl, root));
+    const mcpPreflight = (0, src_1.buildMcpPreflight)({
+        agentType,
+        mcpUrl,
+        mcpName,
+        configured: flags["mcp-configured"] === "true",
+        configuredUrl: detectedConfiguredUrl,
+    });
     assertCommandAvailable(startupCommand.split(/\s+/)[0]);
     const shouldAttach = flags.attach !== "false" && flags["no-attach"] !== "true";
     const shouldPromptRegister = flags.register !== "false" && flags["no-register"] !== "true";
     const registerDelayMs = flags["register-delay-ms"] ? Number(flags["register-delay-ms"]) : 4000;
+    const existing = context.registry.get(id) ?? context.registry.findBySessionFingerprint(sessionId);
+    const registrationAttemptAt = new Date().toISOString();
     const agent = {
         id,
         name: id,
         agentType,
         transport: "tmux",
         sessionId,
+        sessionFingerprint: sessionId,
         projectRoot: root,
         startupCommand,
+        bootstrapStatus: mcpPreflight.canSendSelfRegistrationPrompt ? "created" : "mcp-configuring",
+        registrationSource: "cli",
+        registrationStatus: existing?.registrationStatus === "confirmed" ? "confirmed" : "pending",
+        lastRegistrationAttemptAt: registrationAttemptAt,
+        permissionProfile: permissionProfile.permissionProfile,
+        permissionProfileStatus: permissionProfile.permissionProfileStatus,
+        permissionProfileDetail: permissionProfile.permissionProfileDetail,
+        mcpPreflightStatus: mcpPreflight.mcpPreflightStatus,
+        mcpPreflightDetail: mcpPreflight.mcpPreflightDetail,
+        mcpSetupCommand: mcpPreflight.mcpSetupCommand,
+        mcpVerifyCommand: mcpPreflight.mcpVerifyCommand,
+        mcpRemoveCommand: mcpPreflight.mcpRemoveCommand,
+        mcpUrl: mcpPreflight.mcpUrl,
     };
     const tmux = new src_2.TmuxClient();
     const existed = tmux.hasSession(sessionId);
     tmux.ensureSession(agent);
-    if (shouldPromptRegister && !context.registry.get(id)) {
+    let registeredAgent = await registerThroughLiveOwner(agent, context);
+    let registration = "registration prompt skipped";
+    let nextAction;
+    if (shouldPromptRegister && existing?.registrationStatus !== "confirmed") {
         sleep(registerDelayMs);
-        const prompt = buildSelfRegistrationPrompt(agent);
-        if (agentType === "codex") {
-            tmux.sendCodexText(sessionId, prompt);
+        const bootstrapPrompt = (0, src_2.detectAgentBootstrapPrompt)(agent, tmux.capture(sessionId));
+        if (bootstrapPrompt) {
+            registration = bootstrapPrompt.kind === "client-update"
+                ? "waiting for client update choice"
+                : "waiting for permission approval";
+            nextAction = bootstrapPrompt.action;
+            registeredAgent = await registerThroughLiveOwner({
+                ...registeredAgent,
+                bootstrapStatus: bootstrapPrompt.kind === "client-update" ? "client-update-required" : "permission-required",
+            }, context);
+        }
+        else if (!mcpPreflight.canSendSelfRegistrationPrompt) {
+            registration = "waiting for MCP setup";
+            nextAction = mcpPreflight.nextAction;
+            registeredAgent = await registerThroughLiveOwner({
+                ...registeredAgent,
+                bootstrapStatus: "mcp-configuring",
+            }, context);
         }
         else {
-            tmux.sendText(sessionId, prompt);
+            const prompt = buildSelfRegistrationPrompt(agent);
+            try {
+                if (agentType === "codex") {
+                    tmux.sendCodexText(sessionId, prompt);
+                }
+                else {
+                    tmux.sendText(sessionId, prompt);
+                }
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                registration = "registration prompt failed";
+                nextAction = `Resolve the terminal/session blocker for ${sessionId}, then retry agent registration. ${detail}`;
+                registeredAgent = await registerThroughLiveOwner({
+                    ...registeredAgent,
+                    bootstrapStatus: "failed",
+                    registrationStatus: "failed",
+                    mcpPreflightDetail: detail,
+                }, context);
+                printJson({
+                    agent: registeredAgent,
+                    existed,
+                    attach: `tmux attach -t ${sessionId}`,
+                    registration,
+                    nextAction,
+                    mcpPreflight,
+                    permissionProfile,
+                });
+                return;
+            }
+            registration = "registration prompt sent to agent";
+            registeredAgent = await registerThroughLiveOwner({
+                ...registeredAgent,
+                bootstrapStatus: "registration-pending",
+                registrationStatus: "pending",
+            }, context);
         }
     }
     const summary = {
-        agent,
+        agent: registeredAgent,
         existed,
         attach: `tmux attach -t ${sessionId}`,
-        registration: shouldPromptRegister && !context.registry.get(id)
-            ? "registration prompt sent to agent"
-            : "registration prompt skipped",
+        registration,
+        nextAction,
+        permissionProfile,
+        mcpPreflight,
     };
     if (!shouldAttach) {
         printJson(summary);
@@ -216,6 +398,20 @@ function startVisibleAgent(agentType, defaultCommand, args, context) {
         stdio: "inherit",
     });
 }
+function resolvePermissionProfile(agentType, requestedProfile, projectRoot) {
+    if (requestedProfile !== "direct-workspace-read") {
+        return {
+            permissionProfile: "default",
+            permissionProfileStatus: "not-requested",
+            permissionProfileDetail: "Default CLI startup. Mina will surface permission prompts instead of hiding them.",
+        };
+    }
+    return {
+        permissionProfile: "direct-workspace-read",
+        permissionProfileStatus: "unsupported",
+        permissionProfileDetail: `No known ${agentType} startup flag in Mina is both direct-read and scoped only to ${projectRoot}. Mina will start the default command and surface permission prompts.`,
+    };
+}
 function buildSelfRegistrationPrompt(agent) {
     return [
         "Use Mina AI Router MCP register_agent to register this visible CLI session.",
@@ -225,23 +421,43 @@ function buildSelfRegistrationPrompt(agent) {
         `- agentType: ${agent.agentType}`,
         `- transport: ${agent.transport}`,
         `- sessionId: ${agent.sessionId}`,
+        `- sessionFingerprint: ${agent.sessionFingerprint ?? agent.sessionId}`,
         `- projectRoot: ${agent.projectRoot}`,
         `- startupCommand: ${agent.startupCommand ?? ""}`,
         "",
+        "If Mina already created this agent record, confirm and update that existing id. Do not create a new id for the same session.",
+        "",
         "Before registering, create a concise capability notice for this session:",
         "- Prefer capability docs in this order when present: CLAUDE.md/claude.md, AGENTS.md/agents.md, agent.md, README.md.",
         "- If those files are missing, inspect package metadata and the project file tree to infer what this project/agent can help with.",
         "- Set register_agent capabilitySummary to 2-5 short bullets or one short paragraph under 800 characters.",
         "- Set register_agent capabilitySources to a comma-separated list of the files or project signals you used.",
+        "- Set register_agent sessionFingerprint to the value above.",
         "After registering, call list_agents and confirm this agent is available.",
     ].join("\n");
 }
 async function showHealth(context) {
+    const liveHealth = await getFromMatchingLiveServer("/api/health");
+    if (liveHealth) {
+        printJson({
+            ok: liveHealth.ok,
+            version,
+            statePath: liveHealth.statePath,
+            tmuxAvailable: new src_2.TmuxClient().isAvailable(),
+            agents: liveHealth.agents,
+            requests: liveHealth.requests,
+            mcp: {
+                httpUrl: liveHealth.mcpUrl,
+            },
+        });
+        return;
+    }
     const agents = await context.router.listAgentStatuses();
     const requests = context.router.listRequests();
     const openRequests = requests.filter((request) => ["created", "sent", "waiting"].includes(request.status));
+    const matchingServer = matchingLiveServerStatus();
     printJson({
-        ok: agents.every((agent) => agent.status !== "missing"),
+        ok: agents.every((agent) => !["missing", "stale", "needs-attention"].includes(agent.status)),
         version,
         statePath,
         tmuxAvailable: new src_2.TmuxClient().isAvailable(),
@@ -249,7 +465,9 @@ async function showHealth(context) {
             total: agents.length,
             available: agents.filter((agent) => agent.status === "available").length,
             busy: agents.filter((agent) => agent.status === "busy").length,
+            stale: agents.filter((agent) => agent.status === "stale").length,
             missing: agents.filter((agent) => agent.status === "missing").length,
+            needsAttention: agents.filter((agent) => agent.status === "needs-attention").length,
             unknown: agents.filter((agent) => agent.status === "unknown").length,
         },
         requests: {
@@ -260,16 +478,256 @@ async function showHealth(context) {
             archived: requests.filter((request) => request.status === "archived").length,
         },
         mcp: {
-            httpUrl: `http://${process.env.MINA_HTTP_HOST ?? "127.0.0.1"}:${process.env.MINA_HTTP_PORT ?? "3333"}/mcp`,
+            httpUrl: matchingServer?.mcpUrl
+                ?? `http://${process.env.MINA_HTTP_HOST ?? "127.0.0.1"}:${process.env.MINA_HTTP_PORT ?? "3333"}/mcp`,
         },
     });
 }
 function runVerify() {
-    (0, node_child_process_1.execFileSync)("npm", ["run", "verify"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
+    const root = (0, src_1.packageRoot)();
+    if (!root) {
+        printJson({
+            ok: false,
+            error: "Could not locate @minasoft/mina-ai-router package root.",
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const checkoutVerifyScript = (0, node_path_1.join)(root, "scripts", "core-tests.js");
+    if ((0, node_fs_1.existsSync)(checkoutVerifyScript)) {
+        (0, node_child_process_1.execFileSync)("npm", ["run", "verify"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        printJson({ ok: true, command: "npm run verify", cwd: root });
+        return;
+    }
+    const checks = [
+        verifyInstallCheck("package root", true, "Mina package root found.", `Could not locate ${root}.`),
+        verifyInstallCheck("cli dist", (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "dist", "apps", "cli", "src", "index.js")), "CLI dist found.", "Package is missing CLI dist. Run npm run build before packaging."),
+        verifyInstallCheck("mcp dist", (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "dist", "apps", "mcp-server", "src", "index.js")), "MCP server dist found.", "Package is missing MCP server dist. Run npm run build before packaging."),
+        verifyInstallCheck("http server dist", (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "dist", "apps", "http-server", "src", "index.js")), "HTTP server dist found.", "Package is missing HTTP server dist. Run npm run build before packaging."),
+        verifyInstallCheck("web ui index", (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "dist", "apps", "http-server", "src", "public", "index.html")), "Web UI index found.", "Package is missing built Web UI index. Run npm run build before packaging."),
+        verifyInstallCheck("web ui js asset", hasWebUiAsset(root, ".js"), "Web UI JavaScript asset found.", "Package is missing built Web UI JavaScript assets. Run npm run build before packaging."),
+        verifyInstallCheck("web ui css asset", hasWebUiAsset(root, ".css"), "Web UI CSS asset found.", "Package is missing built Web UI CSS assets. Run npm run build before packaging."),
+        verifyInstallCheck("user guide", (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "docs", "USER-START-GUIDE.md")), "Packaged user documentation found.", "Packaged user documentation is missing."),
+        verifyInstallCheck("registration skill", (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "skills", "mina-ai-router-agent", "SKILL.md")), "Packaged registration skill found.", "Packaged registration skill is missing."),
+    ];
+    const ok = checks.every((check) => check.ok);
+    printJson({
+        ok,
+        command: "mair verify",
+        packageRoot: root,
+        version,
+        checks,
+    });
+    if (!ok) {
+        process.exitCode = 1;
+    }
+}
+function verifyInstallCheck(name, ok, okDetail, failDetail) {
+    return { name, ok, detail: ok ? okDetail : failDetail };
+}
+function hasWebUiAsset(root, extension) {
+    const assetRoot = (0, node_path_1.join)(root, "dist", "apps", "http-server", "src", "public", "assets");
+    if (!(0, node_fs_1.existsSync)(assetRoot)) {
+        return false;
+    }
+    try {
+        return (0, node_fs_1.readdirSync)(assetRoot).some((file) => {
+            const filePath = (0, node_path_1.join)(assetRoot, file);
+            return (0, node_fs_1.statSync)(filePath).isFile() && file.endsWith(extension);
+        });
+    }
+    catch {
+        return false;
+    }
+}
+async function runDoctor(args, context) {
+    const flags = parseFlags(args);
+    const projectRoot = (0, node_path_1.resolve)(flags.project ?? process.cwd());
+    const clientFilter = resolveDoctorClientFilter(args, flags);
+    const scopedDoctor = clientFilter.length !== 2;
+    const ignoreBlockedAgents = flags["ignore-blocked-agents"] === "true";
+    const liveServer = matchingLiveServerStatus();
+    const status = serverStatus();
+    const mcpUrl = resolveMcpUrl(flags);
+    const environmentChecks = [
+        doctorCheck("node", true, process.execPath),
+        doctorCheck("npm", commandAvailable("npm"), "Required for build, verify, and local package workflows."),
+        doctorCheck("tmux", commandAvailable("tmux"), "Required for visible CLI sessions."),
+        doctorCheck("built dist", (0, node_fs_1.existsSync)((0, node_path_1.join)(process.cwd(), "dist", "apps", "cli", "src", "index.js")), "Run npm run build if this is missing."),
+        doctorCheck("matching server", Boolean(liveServer), liveServer ? `MCP ${liveServer.mcpUrl ?? mcpUrl}` : `No running Mina server owns ${statePath}. Run mair server start.`),
+    ];
+    const clients = clientFilter.map((client) => doctorClient(client, projectRoot, mcpUrl));
+    const liveState = await getLiveUiState();
+    const agents = liveState?.agents ?? await context.router.listAgentStatuses();
+    const blockers = agents
+        .filter((agent) => agent.routeReady === false || ["mcp-configuring", "permission-required", "registration-pending"].includes(agent.bootstrapStatus ?? ""))
+        .filter((agent) => !scopedDoctor || agentMatchesDoctorScope(agent, clientFilter, projectRoot))
+        .map((agent) => ({
+        id: agent.id,
+        status: agent.status,
+        routeReady: agent.routeReady,
+        routeBlockedReason: agent.routeBlockedReason,
+        bootstrapStatus: agent.bootstrapStatus,
+        mcpPreflightStatus: agent.mcpPreflightStatus,
+        registrationStatus: agent.registrationStatus,
+        repairAction: doctorRepairAction(agent),
+    }));
+    const checks = [
+        ...environmentChecks,
+        doctorCheck("route-ready agents", ignoreBlockedAgents || blockers.length === 0, blockers.length
+            ? `${blockers.length} agent(s) are blocked. Resolve the listed repairAction values or rerun with --ignore-blocked-agents for environment-only checks.`
+            : scopedDoctor
+                ? "No selected project/client agents are blocked from receiving routed work."
+                : "No known agents are blocked from receiving routed work."),
+    ];
+    const ok = checks.every((check) => check.ok) && clients.every((client) => client.ok);
+    printJson({
+        ok,
+        statePath,
+        projectRoot,
+        mcpUrl,
+        server: status,
+        checks,
+        clients,
+        blockedAgents: blockers,
+    });
+    if (!ok) {
+        process.exitCode = 1;
+    }
+}
+function resolveDoctorClientFilter(args, flags) {
+    const explicit = flags.client ?? flags.clients;
+    if (explicit) {
+        return normalizeSetupClientFilter(explicit);
+    }
+    const positional = args.find((arg) => !arg.startsWith("--") && ["codex", "claude", "all"].includes(arg));
+    return normalizeSetupClientFilter(positional ?? "all");
+}
+function agentMatchesDoctorScope(agent, clientFilter, projectRoot) {
+    const agentClient = agent.agentType === "claude" ? "claude" : agent.agentType === "codex" ? "codex" : undefined;
+    if (!agentClient) {
+        return false;
+    }
+    return clientFilter.includes(agentClient)
+        && projectRootAliases(projectRoot).includes(agent.projectRoot ?? "");
+}
+function projectRootAliases(projectRoot) {
+    const aliases = new Set([projectRoot]);
+    if (projectRoot.startsWith("/tmp/")) {
+        aliases.add(`/private${projectRoot}`);
+    }
+    if (projectRoot.startsWith("/var/")) {
+        aliases.add(`/private${projectRoot}`);
+    }
+    if (projectRoot.startsWith("/private/tmp/")) {
+        aliases.add(projectRoot.replace(/^\/private/, ""));
+    }
+    if (projectRoot.startsWith("/private/var/")) {
+        aliases.add(projectRoot.replace(/^\/private/, ""));
+    }
+    return [...aliases].filter(Boolean);
+}
+function doctorRepairAction(agent) {
+    if (agent.bootstrapStatus === "mcp-configuring" || agent.mcpPreflightStatus === "missing" || agent.mcpPreflightStatus === "stale") {
+        const client = agent.agentType === "claude" ? "claude" : "codex";
+        const projectRoot = shellQuote(agent.projectRoot || process.cwd());
+        return `Run mair setup ${client} --project ${projectRoot}, then rerun mair doctor --client ${client} --project ${projectRoot}.`;
+    }
+    if (agent.bootstrapStatus === "permission-required") {
+        return `Open the terminal for ${agent.id}, approve the CLI trust or permission prompt, then rerun mair doctor.`;
+    }
+    if (agent.bootstrapStatus === "registration-pending" || agent.registrationStatus === "pending") {
+        return `Ask ${agent.id} to register this session with Mina AI Router, then rerun mair doctor.`;
+    }
+    if (agent.routeBlockedReason) {
+        return agent.routeBlockedReason;
+    }
+    return `Open agent ${agent.id} in the Web UI inspector and resolve its readiness blocker.`;
+}
+function runSetup(args) {
+    const client = args[0];
+    if (client !== "codex" && client !== "claude") {
+        throw new Error("Usage: mair setup <codex|claude> [--project <path>] [--mcp-url <url>] [--mcp-name mina-ai-router] [--dry-run]");
+    }
+    setupClient(client, parseFlags(args.slice(1)));
+}
+function setupClient(client, flags) {
+    const projectRoot = (0, node_path_1.resolve)(flags.project ?? process.cwd());
+    const mcpName = flags["mcp-name"] ?? "mina-ai-router";
+    const mcpUrl = resolveMcpUrl(flags);
+    const dryRun = flags["dry-run"] === "true";
+    const source = resolveSkillSourcePath();
+    const target = skillTargetFor(client, projectRoot);
+    const commands = mcpCommandsFor(client, mcpName, mcpUrl);
+    const actions = [];
+    if (!commandAvailable(client)) {
+        throw new Error(`Required command "${client}" is not available on PATH. Install ${client} before running mair setup ${client}.`);
+    }
+    if (!(0, node_fs_1.existsSync)(projectRoot)) {
+        throw new Error(`Project path does not exist: ${projectRoot}`);
+    }
+    if (dryRun) {
+        printJson({
+            ok: true,
+            dryRun,
+            client,
+            projectRoot,
+            mcpUrl,
+            commands: {
+                remove: shellCommand(commands.remove),
+                add: shellCommand(commands.add),
+                verify: shellCommand(commands.verify),
+                list: shellCommand(commands.list),
+            },
+            skill: {
+                source,
+                target,
+                planned: true,
+            },
+        });
+        return;
+    }
+    runOptionalMcpCommand(commands.remove, actions, "remove existing MCP entry", projectRoot);
+    const addOutput = runRequiredMcpCommand(commands.add, actions, "add MCP entry", projectRoot);
+    const verifyOutput = runRequiredMcpCommand(commands.verify, actions, "verify MCP entry", projectRoot);
+    const listOutput = runRequiredMcpCommand(commands.list, actions, "verify MCP visibility", projectRoot);
+    const verified = `${addOutput}\n${verifyOutput}`.includes(mcpUrl) && listOutput.includes(mcpName);
+    actions.push({
+        name: "verify MCP URL",
+        ok: verified,
+        detail: verified ? `MCP URL verified and visible in ${client} mcp list: ${mcpUrl}` : `MCP command output did not prove ${mcpName} is visible for ${mcpUrl}.`,
+    });
+    if (!verified) {
+        throw new Error(`MCP setup for ${client} did not verify ${mcpUrl}. Run ${shellCommand(commands.verify)} to inspect the client config.`);
+    }
+    linkSkill(source, target);
+    actions.push({ name: "install registration skill", ok: true, detail: `${target} -> ${source}` });
+    printJson({
+        ok: true,
+        client,
+        projectRoot,
+        mcpUrl,
+        actions,
+        commands: {
+            remove: shellCommand(commands.remove),
+            add: shellCommand(commands.add),
+            verify: shellCommand(commands.verify),
+            list: shellCommand(commands.list),
+        },
+        skill: {
+            source,
+            target,
+            installed: (0, node_fs_1.existsSync)((0, node_path_1.join)(target, "SKILL.md")),
+        },
+        nextSteps: [
+            `Start a visible ${client} session with mair ${client}.`,
+            "If the UI shows mcp-configuring, rerun mair doctor --client " + client,
+        ],
     });
-    printJson({ ok: true, command: "npm run verify" });
 }
 function serveHttp(args) {
     const flags = parseFlags(args);
@@ -289,8 +747,11 @@ function serveHttp(args) {
 }
 function setupCodexPair(args, context) {
     const options = parseFlags(args);
-    const mainRoot = options["main-root"] ?? "/Users/stevenna/WebstormProjects/minasoftai";
-    const helperRoot = options["helper-root"] ?? "/Users/stevenna/PycharmProjects/mina-ralph-loop-bootstrap-nextjs";
+    const mainRoot = options["main-root"];
+    const helperRoot = options["helper-root"];
+    if (!mainRoot || !helperRoot) {
+        throw new Error("setup-codex-pair is a developer/demo helper. Provide explicit --main-root and --helper-root, or use mair setup codex/claude for normal first-run setup.");
+    }
     const helperId = options["helper-id"] ?? "ralph";
     const sessionId = options.session ?? "mina-ralph-codex";
     const mcpName = options["mcp-name"] ?? "mina-ai-router";
@@ -349,6 +810,204 @@ function setupCodexPair(args, context) {
         ],
     });
 }
+function normalizeSetupClientFilter(value) {
+    if (value === "all") {
+        return ["codex", "claude"];
+    }
+    if (value === "codex" || value === "claude") {
+        return [value];
+    }
+    throw new Error("--client must be codex, claude, or all.");
+}
+function doctorClient(client, projectRoot, mcpUrl) {
+    const binaryOk = commandAvailable(client);
+    const target = skillTargetFor(client, projectRoot);
+    const skillInstalled = (0, node_fs_1.existsSync)((0, node_path_1.join)(target, "SKILL.md"));
+    const mcp = binaryOk ? inspectMcpConfig(client, "mina-ai-router", mcpUrl, projectRoot) : {
+        ok: false,
+        detail: `${client} is not available on PATH.`,
+    };
+    return {
+        client,
+        ok: binaryOk && skillInstalled && mcp.ok,
+        binary: doctorCheck(`${client} binary`, binaryOk, binaryOk ? "available on PATH" : `Install ${client} before setup.`),
+        mcp,
+        skill: {
+            ok: skillInstalled,
+            target,
+            detail: skillInstalled ? "registration skill installed or linked" : `Run mair setup ${client} to install the registration skill.`,
+        },
+    };
+}
+function doctorCheck(name, ok, detail) {
+    return { name, ok, detail };
+}
+function inspectMcpConfig(client, mcpName, mcpUrl, projectRoot) {
+    const commands = mcpCommandsFor(client, mcpName, mcpUrl);
+    try {
+        const getOutput = (0, node_child_process_1.execFileSync)(commands.verify.command, commands.verify.args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const listOutput = (0, node_child_process_1.execFileSync)(commands.list.command, commands.list.args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const output = `${getOutput}\n${listOutput}`;
+        return {
+            ok: getOutput.includes(mcpUrl) && listOutput.includes(mcpName),
+            detail: getOutput.includes(mcpUrl) && listOutput.includes(mcpName)
+                ? `configured for ${mcpUrl}; ${mcpName} is visible in ${client} mcp list`
+                : `MCP entry check did not prove ${mcpName} is visible to ${client}; run mair setup ${client}.`,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            detail: commandFailureMessage(error) || `Run mair setup ${client}.`,
+        };
+    }
+}
+function detectClientMcpConfiguredUrl(client, mcpName, mcpUrl, projectRoot) {
+    if (!commandAvailable(client)) {
+        return undefined;
+    }
+    try {
+        const output = (0, node_child_process_1.execFileSync)(client, ["mcp", "get", mcpName], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const list = (0, node_child_process_1.execFileSync)(client, ["mcp", "list"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (!list.includes(mcpName)) {
+            return undefined;
+        }
+        return extractMcpUrl(output, mcpUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractMcpUrl(output, expectedUrl) {
+    if (output.includes(expectedUrl)) {
+        return expectedUrl;
+    }
+    const match = output.match(/https?:\/\/[^\s"',)]+/);
+    return match?.[0];
+}
+function resolveMcpUrl(flags) {
+    if (flags["mcp-url"]) {
+        return flags["mcp-url"];
+    }
+    const live = matchingLiveServerStatus();
+    if (live?.mcpUrl) {
+        return live.mcpUrl;
+    }
+    return `http://${process.env.MINA_HTTP_HOST ?? "127.0.0.1"}:${process.env.MINA_HTTP_PORT ?? "3333"}/mcp`;
+}
+function mcpCommandsFor(client, mcpName, mcpUrl) {
+    if (client === "codex") {
+        return {
+            remove: { command: "codex", args: ["mcp", "remove", mcpName] },
+            add: { command: "codex", args: ["mcp", "add", mcpName, "--url", mcpUrl] },
+            verify: { command: "codex", args: ["mcp", "get", mcpName] },
+            list: { command: "codex", args: ["mcp", "list"] },
+        };
+    }
+    return {
+        remove: { command: "claude", args: ["mcp", "remove", mcpName] },
+        add: { command: "claude", args: ["mcp", "add", "--transport", "http", mcpName, mcpUrl] },
+        verify: { command: "claude", args: ["mcp", "get", mcpName] },
+        list: { command: "claude", args: ["mcp", "list"] },
+    };
+}
+function runOptionalMcpCommand(command, actions, name, cwd) {
+    try {
+        (0, node_child_process_1.execFileSync)(command.command, command.args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        actions.push({ name, ok: true, detail: shellCommand(command) });
+    }
+    catch (error) {
+        actions.push({ name, ok: true, detail: `No existing entry removed or removal was ignored. ${commandFailureMessage(error)}`.trim() });
+    }
+}
+function runRequiredMcpCommand(command, actions, name, cwd) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)(command.command, command.args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        actions.push({ name, ok: true, detail: shellCommand(command) });
+        return output;
+    }
+    catch (error) {
+        const detail = commandFailureMessage(error);
+        actions.push({ name, ok: false, detail });
+        throw new Error(`${name} failed: ${detail}`);
+    }
+}
+function commandFailureMessage(error) {
+    if (error && typeof error === "object") {
+        const record = error;
+        const text = `${record.stderr ? String(record.stderr) : ""}${record.stdout ? String(record.stdout) : ""}`.trim();
+        return text || record.message || "";
+    }
+    return String(error);
+}
+function resolveSkillSourcePath() {
+    const candidates = [
+        (0, node_path_1.join)(process.cwd(), "skills", "mina-ai-router-agent"),
+        (0, node_path_1.join)(__dirname, "../../../../skills/mina-ai-router-agent"),
+    ];
+    const source = candidates.find((candidate) => (0, node_fs_1.existsSync)((0, node_path_1.join)(candidate, "SKILL.md")));
+    if (!source) {
+        throw new Error("Could not locate skills/mina-ai-router-agent/SKILL.md in this checkout or package.");
+    }
+    return source;
+}
+function skillTargetFor(client, projectRoot) {
+    if (client === "codex") {
+        const home = process.env.HOME;
+        if (!home) {
+            throw new Error("HOME is required to install the Codex registration skill.");
+        }
+        return (0, node_path_1.join)(home, ".codex", "skills", "mina-ai-router-agent");
+    }
+    return (0, node_path_1.join)(projectRoot, ".claude", "skills", "mina-ai-router-agent");
+}
+function linkSkill(source, target) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+    (0, node_child_process_1.execFileSync)("rm", ["-rf", target], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    try {
+        (0, node_child_process_1.execFileSync)("ln", ["-sfn", source, target], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch {
+        (0, node_fs_1.mkdirSync)(target, { recursive: true });
+        (0, node_child_process_1.execFileSync)("cp", ["-R", `${source}/.`, target], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+}
+function shellCommand(command) {
+    return [command.command, ...command.args].map(shellQuote).join(" ");
+}
 function createContext() {
     const fileState = new src_1.FileState(statePath);
     const state = fileState.load();
@@ -372,6 +1031,7 @@ function createContext() {
         registry,
         requestStore,
         transports,
+        agentStaleAfterMs,
         onStateChanged: context.save,
     });
     return {
@@ -380,38 +1040,79 @@ function createContext() {
         router,
     };
 }
-function registerAgent(args, context) {
+async function registerAgent(args, context) {
     const id = args[0];
     if (!id) {
         throw new Error("Usage: mair register <id> --agent <type> --transport <transport> --session <session> --root <path>");
     }
     const options = parseFlags(args.slice(1));
+    const now = new Date().toISOString();
     const agent = {
         id,
         name: options.name ?? id,
         agentType: options.agent ?? "unknown",
         transport: (options.transport ?? "headless"),
         sessionId: options.session ?? id,
+        sessionFingerprint: options["session-fingerprint"] ?? options.session ?? id,
         projectRoot: options.root ?? process.cwd(),
         tmuxTarget: options.target,
         startupCommand: options.command,
         capabilitySummary: options.summary ?? options["capability-summary"],
         capabilitySources: options.sources ?? options["capability-sources"],
+        bootstrapStatus: "ready",
+        registrationSource: "cli",
+        registrationStatus: "confirmed",
+        lastRegistrationAttemptAt: now,
+        confirmedByAgentAt: now,
     };
-    context.registry.register(agent);
+    const proxied = await postToMatchingLiveServer("/api/register", agent);
+    if (proxied) {
+        printJson({ agent: proxied.agent });
+        return;
+    }
+    const registered = context.registry.register(agent, {
+        capabilitySource: agent.capabilitySummary || agent.capabilitySources ? "manual" : undefined,
+    });
     context.save();
-    printJson({ agent });
+    printJson({ agent: registered });
 }
 async function listAgents(context) {
+    const liveState = await getLiveUiState();
+    if (liveState) {
+        printJson({
+            agents: liveState.agents,
+        });
+        return;
+    }
     const agents = await context.router.listAgentStatuses();
     printJson({
         agents,
     });
 }
+async function handleAgent(args, context) {
+    if (args[0] === "refresh-capabilities") {
+        await refreshAgentCapabilities(args.slice(1), context);
+        return;
+    }
+    await showAgent(args, context);
+}
 async function showAgent(args, context) {
     const id = args[0];
     if (!id) {
-        throw new Error("Usage: mair agent <id>");
+        throw new Error("Usage: mair agent <id> | mair agent refresh-capabilities <id> [--timeout-ms 300000]");
+    }
+    const liveState = await getLiveUiState();
+    if (liveState) {
+        const status = liveState.agents.find((candidate) => candidate.id === id);
+        if (!status) {
+            throw new Error(`Agent "${id}" is not registered.`);
+        }
+        printJson({
+            agent: status,
+            status,
+            attach: status.transport === "tmux" ? `tmux attach -t ${status.sessionId}` : undefined,
+        });
+        return;
     }
     const agent = context.registry.require(id);
     const statuses = await context.router.listAgentStatuses();
@@ -421,6 +1122,125 @@ async function showAgent(args, context) {
         attach: agent.transport === "tmux" ? `tmux attach -t ${agent.sessionId}` : undefined,
     });
 }
+async function refreshAgentCapabilities(args, context) {
+    const id = args[0];
+    if (!id) {
+        throw new Error("Usage: mair agent refresh-capabilities <id> [--timeout-ms 300000]");
+    }
+    const flags = parseFlags(args.slice(1));
+    const proxied = await postToMatchingLiveServer(`/api/agents/${encodeURIComponent(id)}/refresh-capabilities`, {
+        timeoutMs: flags["timeout-ms"] ? Number(flags["timeout-ms"]) : undefined,
+    });
+    if (proxied) {
+        printJson({
+            agent: proxied.agent,
+            refresh: proxied.refresh,
+        });
+        return;
+    }
+    const agent = context.registry.require(id);
+    const response = await context.router.callAgent({
+        target: id,
+        task: buildCapabilityRefreshTask(agent),
+        timeoutMs: flags["timeout-ms"] ? Number(flags["timeout-ms"]) : undefined,
+    });
+    const notice = parseCapabilityRefreshAnswer(response.answer);
+    const refreshedAt = new Date().toISOString();
+    const updated = context.registry.updateCapabilities(id, {
+        summary: notice.capabilitySummary,
+        sources: notice.capabilitySources,
+        source: "generated",
+        refreshedAt,
+        profile: notice.capabilityProfile,
+    });
+    context.save();
+    printJson({
+        agent: updated,
+        refresh: {
+            requestId: response.requestId,
+            refreshedAt,
+            capabilitySource: updated.capabilitySource,
+        },
+    });
+}
+function buildCapabilityRefreshTask(agent) {
+    return [
+        "Refresh your Mina AI Router capability registration for this visible local agent.",
+        "",
+        "Inspect local project docs and metadata before answering.",
+        "Prefer capability docs in this order when present: CLAUDE.md/claude.md, AGENTS.md/agents.md, agent.md, README.md.",
+        "If those files are missing, inspect package metadata and the project file tree.",
+        "",
+        "Return only JSON with these string fields:",
+        "{",
+        '  "capabilitySummary": "2-5 short bullets or one short paragraph under 800 characters",',
+        '  "capabilitySources": "comma-separated file paths or project signals used",',
+        '  "capabilityProfile": {',
+        '    "projectPurpose": "what this project implements",',
+        '    "primaryLanguages": ["TypeScript"],',
+        '    "keyAreas": ["router", "MCP endpoint"],',
+        '    "canAnswer": ["specific question domains this agent can answer"],',
+        '    "cannotAnswerYet": ["known limits"],',
+        '    "evidence": ["README.md", "package.json", "src/..."]',
+        "  }",
+        "}",
+        "",
+        "Do not include markdown fences or extra commentary in the JSON body.",
+        "",
+        "Registration context:",
+        `- id: ${agent.id}`,
+        `- agentType: ${agent.agentType}`,
+        `- transport: ${agent.transport}`,
+        `- sessionId: ${agent.sessionId}`,
+        `- projectRoot: ${agent.projectRoot}`,
+    ].join("\n");
+}
+function parseCapabilityRefreshAnswer(answer) {
+    const trimmed = answer.trim();
+    const jsonText = trimmed.startsWith("{") ? trimmed : trimmed.slice(trimmed.indexOf("{"), trimmed.lastIndexOf("}") + 1);
+    if (!jsonText || !jsonText.startsWith("{") || !jsonText.endsWith("}")) {
+        throw new Error("Capability refresh response did not contain a JSON object.");
+    }
+    const parsed = JSON.parse(jsonText);
+    const capabilitySummary = typeof parsed.capabilitySummary === "string" ? parsed.capabilitySummary.trim() : "";
+    const capabilitySources = typeof parsed.capabilitySources === "string" ? parsed.capabilitySources.trim() : "";
+    if (!capabilitySummary || !capabilitySources) {
+        throw new Error("Capability refresh JSON requires non-empty capabilitySummary and capabilitySources strings.");
+    }
+    if (capabilitySummary.length > 800) {
+        throw new Error("Capability refresh JSON capabilitySummary must be under 800 characters.");
+    }
+    return {
+        capabilitySummary,
+        capabilitySources,
+        capabilityProfile: capabilityProfileValue(parsed.capabilityProfile),
+    };
+}
+function capabilityProfileValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    return {
+        projectPurpose: stringObjectValue(record.projectPurpose),
+        primaryLanguages: stringArrayValue(record.primaryLanguages),
+        keyAreas: stringArrayValue(record.keyAreas),
+        canAnswer: stringArrayValue(record.canAnswer),
+        cannotAnswerYet: stringArrayValue(record.cannotAnswerYet),
+        evidence: stringArrayValue(record.evidence),
+    };
+}
+function stringObjectValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function stringArrayValue(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const values = value.filter((item) => typeof item === "string" && Boolean(item.trim()))
+        .map((item) => item.trim());
+    return values.length ? values : undefined;
+}
 function showAttach(args, context) {
     const id = args[0];
     if (!id) {
@@ -442,6 +1262,15 @@ async function askAgent(args, context) {
         throw new Error('Usage: mair ask <target> "question" [--timeout-ms 300000]');
     }
     const flags = parseFlags(args);
+    const proxied = await postToMatchingLiveServer("/api/ask", {
+        target,
+        task: taskFromArgs(args.slice(1)),
+        timeoutMs: flags["timeout-ms"] ? Number(flags["timeout-ms"]) : undefined,
+    });
+    if (proxied) {
+        printJson(proxied.result);
+        return;
+    }
     try {
         const response = await context.router.callAgent({
             target,
@@ -454,6 +1283,17 @@ async function askAgent(args, context) {
         context.save();
     }
 }
+async function registerThroughLiveOwner(agent, context) {
+    const proxied = await postToMatchingLiveServer("/api/register", agent);
+    if (proxied) {
+        return proxied.agent;
+    }
+    const registered = context.registry.register(agent, {
+        capabilitySource: agent.capabilitySummary || agent.capabilitySources ? "manual" : undefined,
+    });
+    context.save();
+    return registered;
+}
 function listRequests(args, context) {
     const flags = parseFlags(args);
     const target = flags.target;
@@ -462,13 +1302,256 @@ function listRequests(args, context) {
         : context.router.listRequests();
     printJson({ requests });
 }
-function showRequest(args, context) {
+async function handleRequest(args, context) {
     const requestId = args[0];
     if (!requestId) {
-        throw new Error("Usage: mair request <request-id>");
+        throw new Error("Usage: mair request <request-id> [retry|cancel|archive|unarchive|interrupt|recover]");
+    }
+    const action = args[1];
+    if (action) {
+        await runRequestAction(requestId, action, context);
+        return;
     }
     printJson(context.router.getRequest(requestId));
 }
+async function runRequestAction(requestId, action, context) {
+    if (isRequestAction(action) && await runServerRequestAction(requestId, action)) {
+        return;
+    }
+    const request = context.router.getRequest(requestId);
+    switch (action) {
+        case "retry": {
+            context.requestStore.assertActionAllowed(request, "retry");
+            try {
+                const result = await context.router.callAgent({
+                    sourceAgent: request.sourceAgent,
+                    target: request.targetAgent,
+                    task: request.task,
+                    retryOfRequestId: request.id,
+                });
+                context.requestStore.recordRetry(request.id, result.requestId);
+                printJson(result);
+            }
+            finally {
+                context.save();
+            }
+            return;
+        }
+        case "cancel": {
+            const updated = context.requestStore.cancel(requestId, "Cancelled by operator from Mina AI Router CLI.", "cli");
+            clearAgentLeaseForRequest(updated, context);
+            context.save();
+            printJson(updated);
+            return;
+        }
+        case "interrupt": {
+            const updated = interruptRequest(requestId, context);
+            context.save();
+            printJson(updated);
+            return;
+        }
+        case "recover": {
+            const updated = context.router.recoverRequestLease(requestId, "cli", "Marked recovered by operator from Mina AI Router CLI.");
+            printJson(updated);
+            return;
+        }
+        case "archive": {
+            const updated = context.router.archiveRequest(requestId, "cli", "Archived by operator from Mina AI Router CLI.");
+            printJson(updated);
+            return;
+        }
+        case "unarchive": {
+            const updated = context.requestStore.unarchive(requestId);
+            context.save();
+            printJson(updated);
+            return;
+        }
+        default:
+            throw new Error(`Unsupported request action "${action}". Use retry, cancel, archive, unarchive, interrupt, or recover.`);
+    }
+}
+function interruptRequest(requestId, context) {
+    const request = context.requestStore.require(requestId);
+    context.requestStore.assertActionAllowed(request, "interrupt");
+    const agentId = request.leaseOwnerAgentId ?? request.targetAgent;
+    const agent = context.registry.require(agentId);
+    if (agent.transport !== "tmux") {
+        throw new Error(`Request "${requestId}" targets ${agent.transport}, not tmux; open the session manually.`);
+    }
+    const target = agent.tmuxTarget ?? agent.sessionId;
+    new src_2.TmuxClient().sendInterrupt(target);
+    return context.requestStore.recordInterrupt(requestId, {
+        source: "cli",
+        terminalTarget: target,
+        message: `Terminal interrupt sent to ${target}.`,
+    });
+}
+function clearAgentLeaseForRequest(request, context) {
+    if (!request.leaseOwnerAgentId) {
+        return;
+    }
+    const agent = context.registry.get(request.leaseOwnerAgentId);
+    if (!agent || agent.activeRequestId !== request.id) {
+        return;
+    }
+    context.registry.register({
+        ...agent,
+        activeRequestId: undefined,
+        leaseStatus: "released",
+        leaseReleasedAt: new Date().toISOString(),
+    });
+}
+function isRequestAction(action) {
+    return action === "retry"
+        || action === "cancel"
+        || action === "archive"
+        || action === "unarchive"
+        || action === "interrupt"
+        || action === "recover";
+}
+async function runServerRequestAction(requestId, action) {
+    const status = matchingLiveServerStatus();
+    if (!status) {
+        return false;
+    }
+    const url = `http://${status.host}:${status.port}/api/requests/${encodeURIComponent(requestId)}/${encodeURIComponent(action)}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: "{}",
+        });
+    }
+    catch (error) {
+        throw new Error(`Mina server is running for this state file, but ${action} could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const body = await parseLiveServerJsonResponse(response, url, `/api/requests/${requestId}/${action}`);
+    if (!response.ok) {
+        throw new Error(body.error ?? `Request action ${action} failed with HTTP ${response.status}.`);
+    }
+    printJson(body.result);
+    return true;
+}
+async function getLiveUiState() {
+    return getFromMatchingLiveServer("/api/state");
+}
+function matchingLiveServerStatus() {
+    const status = serverStatus();
+    if (!status.running || !status.host || !status.port || !status.statePath) {
+        return undefined;
+    }
+    if (resolvePath(status.statePath) !== resolvePath(statePath)) {
+        return undefined;
+    }
+    return status;
+}
+async function getFromMatchingLiveServer(path) {
+    const status = matchingLiveServerStatus();
+    if (!status) {
+        return undefined;
+    }
+    const url = `http://${status.host}:${status.port}${path}`;
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (error) {
+        throw new Error(`Mina server is running for this state file, but CLI live read could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const responseBody = await parseLiveServerJsonResponse(response, url, path);
+    if (!response.ok) {
+        throw new Error(responseBody.error ?? `CLI live read ${path} failed with HTTP ${response.status}.`);
+    }
+    return responseBody;
+}
+async function postToMatchingLiveServer(path, body) {
+    const status = matchingLiveServerStatus();
+    if (!status) {
+        return undefined;
+    }
+    const url = `http://${status.host}:${status.port}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body ?? {}),
+        });
+    }
+    catch (error) {
+        throw new Error(`Mina server is running for this state file, but CLI proxy could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const responseBody = await parseLiveServerJsonResponse(response, url, path);
+    if (!response.ok) {
+        throw new Error(responseBody.error ?? `CLI proxy ${path} failed with HTTP ${response.status}.`);
+    }
+    return responseBody;
+}
+async function parseLiveServerJsonResponse(response, url, path) {
+    const text = await response.text();
+    const parsed = safeJson(text);
+    if (parsed === undefined) {
+        throw new Error(nonMinaPidMessage(url, `response was not Mina JSON: ${truncateText(text, 160)}`));
+    }
+    if (response.ok && !looksLikeMinaResponse(path, parsed)) {
+        throw new Error(nonMinaPidMessage(url, "response JSON did not match Mina server shape"));
+    }
+    return parsed;
+}
+function looksLikeMinaResponse(path, value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    if (path === "/api/health") {
+        return typeof record.statePath === "string"
+            && typeof record.mcpUrl === "string"
+            && Boolean(record.agents && typeof record.agents === "object")
+            && Boolean(record.requests && typeof record.requests === "object");
+    }
+    if (path === "/api/state") {
+        return typeof record.statePath === "string"
+            && typeof record.mcpUrl === "string"
+            && Array.isArray(record.agents)
+            && Array.isArray(record.requests);
+    }
+    if (path === "/api/register") {
+        return Boolean(record.agent && typeof record.agent === "object");
+    }
+    if (path === "/api/ask") {
+        return Boolean(record.result && typeof record.result === "object");
+    }
+    if (/^\/api\/agents\/[^/]+\/refresh-capabilities$/.test(path)) {
+        return Boolean(record.agent && typeof record.agent === "object")
+            && Boolean(record.refresh && typeof record.refresh === "object");
+    }
+    if (/^\/api\/requests\/[^/]+\/[^/]+$/.test(path)) {
+        return "result" in record;
+    }
+    return true;
+}
+function nonMinaPidMessage(url, detail) {
+    return [
+        `Mina server pid file points at ${url}, but ${detail}.`,
+        `Remove stale pid file ${serverPidPath} or restart mair server.`,
+    ].join(" ");
+}
+function resolvePath(value) {
+    return (0, node_path_1.resolve)(value);
+}
+function safeJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function truncateText(value, maxLength) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 1).trim()}...` : normalized;
+}
 function parseFlags(args) {
     const flags = {};
     for (let index = 0; index < args.length; index += 1) {
@@ -476,6 +1559,12 @@ function parseFlags(args) {
         if (!token?.startsWith("--")) {
             continue;
         }
+        const inlineValueIndex = token.indexOf("=");
+        if (inlineValueIndex > 2) {
+            const key = token.slice(2, inlineValueIndex);
+            flags[key] = token.slice(inlineValueIndex + 1);
+            continue;
+        }
         const key = token.slice(2);
         const value = args[index + 1];
         if (!value || value.startsWith("--")) {
@@ -487,15 +1576,25 @@ function parseFlags(args) {
     }
     return flags;
 }
+function hasHelpFlag(args) {
+    return args.includes("--help") || args.includes("-h");
+}
 function assertCommandAvailable(command) {
+    if (commandAvailable(command)) {
+        return;
+    }
+    throw new Error(`Required command "${command}" is not available on PATH.`);
+}
+function commandAvailable(command) {
     try {
         (0, node_child_process_1.execFileSync)("which", [command], {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
         });
+        return true;
     }
     catch {
-        throw new Error(`Required command "${command}" is not available on PATH.`);
+        return false;
     }
 }
 function shellQuote(value) {
@@ -517,6 +1616,9 @@ function sleep(milliseconds) {
     }
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
 function taskFromArgs(args) {
     const taskTokens = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -535,7 +1637,10 @@ function printHelp() {
 Commands:
   mair version
   mair health
-  mair verify
+  mair doctor [--client <codex|claude|all>] [--project <path>] [--json]
+  mair verify  # installed package self-check; use npm run verify in a checkout
+  mair setup codex [--project <path>] [--mcp-url <url>] [--mcp-name mina-ai-router]
+  mair setup claude [--project <path>] [--mcp-url <url>] [--mcp-name mina-ai-router]
   mair server start [--port 3333] [--host 127.0.0.1]
   mair server stop
   mair server status
@@ -544,26 +1649,126 @@ Commands:
   mair register <id> --agent <type> --transport <headless|mock|tmux|zmux> --session <session> --root <path>
   mair agents
   mair agent <id>
+  mair agent refresh-capabilities <id> [--timeout-ms 300000]
   mair attach <id>
-  mair setup-codex-pair [--main-root <path>] [--helper-root <path>] [--helper-id <id>] [--session <tmux-session>]
   mair serve [--port 3333]
   mair ask <target> "question"
   mair requests [--target <id>]
-  mair request <request-id>
+  mair request <request-id> [retry|cancel|archive|unarchive|interrupt|recover]
+
+Developer/demo helper:
+  mair setup-codex-pair --main-root <path> --helper-root <path> [--helper-id <id>] [--session <tmux-session>]
 
 Example:
+  mair server start --port 3333
+  mair setup codex --project ~/work/payment
+  mair doctor --client codex --project ~/work/payment
+  mair setup claude --project ~/work/payment
+  mair doctor --client claude --project ~/work/payment
   mair register payment --agent gemini --transport headless --session payment --root ./payment
   mair register payment --agent gemini --transport tmux --session payment --root ~/work/payment
-  mair setup-codex-pair
   mair serve
-  mair server start --port 3333
   mair codex
   mair claude
   mair ask payment "현재 payment flow를 요약해줘."
 
 State:
-  Set MINA_ROUTER_STATE=/path/to/router-state.json to share state between CLI and MCP.
+  By default, Mina uses ~/.mair for router state, pid, and logs across directories.
+  Set MINA_RUNTIME_DIR, MINA_ROUTER_STATE, or MINA_SERVER_PID only for an isolated runtime.
+`);
+}
+function printCommandHelp(command) {
+    switch (command) {
+        case "doctor":
+            console.log(`Usage: mair doctor [--client <codex|claude|all>] [--project <path>] [--json] [--ignore-blocked-agents]
+
+Checks local server, client MCP setup, registration skill installation, and route readiness.
+`);
+            return;
+        case "setup":
+            console.log(`Usage: mair setup <codex|claude> [--project <path>] [--mcp-url <url>] [--mcp-name mina-ai-router] [--dry-run]
+
+Configures a chosen client MCP profile and installs the Mina registration skill.
+`);
+            return;
+        case "server":
+            console.log(`Usage: mair server <start|stop|status> [--port 3333] [--host 127.0.0.1]
+
+Starts, stops, or inspects the local Mina HTTP/Web UI server.
+`);
+            return;
+        case "codex":
+            console.log(`Usage: mair codex [--id <id>] [--session <tmux-session>] [--root <path>] [--no-attach] [--no-register]
+
+Starts a visible Codex tmux agent and creates a Mina registry placeholder.
+`);
+            return;
+        case "claude":
+            console.log(`Usage: mair claude [--id <id>] [--session <tmux-session>] [--root <path>] [--no-attach] [--no-register]
+
+Starts a visible Claude tmux agent and creates a Mina registry placeholder.
+`);
+            return;
+        case "register":
+            console.log(`Usage: mair register <id> --agent <type> --transport <transport> --session <session> --root <path>
+
+Registers or refreshes an agent in the local Mina router registry.
+`);
+            return;
+        case "agent":
+            console.log(`Usage: mair agent <id> | mair agent refresh-capabilities <id> [--timeout-ms 300000]
+
+Shows agent detail or asks an agent to refresh its capability profile.
+`);
+            return;
+        case "attach":
+            console.log(`Usage: mair attach <id>
+
+Prints the attach command for a tmux-backed agent.
+`);
+            return;
+        case "setup-codex-pair":
+            console.log(`Usage: mair setup-codex-pair --main-root <path> --helper-root <path>
+
+Developer/demo helper. Use mair setup codex or mair setup claude for normal setup.
+`);
+            return;
+        case "serve":
+            console.log(`Usage: mair serve [--port 3333]
+
+Runs the HTTP/Web UI server in the current process.
+`);
+            return;
+        case "ask":
+            console.log(`Usage: mair ask <target> "question" [--timeout-ms 300000]
+
+Routes a question to a route-ready registered agent.
+`);
+            return;
+        case "requests":
+            console.log(`Usage: mair requests [--target <id>]
+
+Lists routed requests from local router state.
+`);
+            return;
+        case "request":
+            console.log(`Usage: mair request <request-id> [retry|cancel|archive|unarchive|interrupt|recover]
+
+Shows or changes a request lifecycle state.
 `);
+            return;
+        case "health":
+            console.log("Usage: mair health\n\nShows router health and readiness counts.");
+            return;
+        case "verify":
+            console.log("Usage: mair verify\n\nRuns checkout verification in a checkout, or installed package self-checks in an installed package.");
+            return;
+        case "version":
+            console.log("Usage: mair version\n\nPrints the installed Mina AI Router package version.");
+            return;
+        default:
+            printHelp();
+    }
 }
 function printJson(value) {
     console.log(JSON.stringify(value, null, 2));