@interf/compiler 0.13.0 → 0.18.0

package/dist/cli/commands/wizard.js

@@ -2,7 +2,8 @@
  * `interf` (no subcommand) and `interf init` — the wizard.
  *
  * Casual-user entry point. End-to-end onboarding:
- *   - If no connection → offer to start a local engine inline (or connect remote, or quit).
+ *   - If no connection → connect to an already-running local engine, or ask
+ *     whether to start the foreground local engine, connect remote, or quit.
  *   - Once connected → action menu (list / create / compile / test / open UI / stop engine / quit).
  *   - Each action loops back to the menu instead of exiting.
  *
@@ -15,8 +16,8 @@ import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, resolve } from "node:path";
 import { spawn } from "node:child_process";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection, writeConnection, } from "../../packages/local-service/connection-config.js";
-import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT } from "../../packages/local-service/routes.js";
+import { ConnectionRecordSchema, readActiveConnection, writeConnection, } from "../../packages/engine/connection-config.js";
+import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT } from "../../packages/engine/routes.js";
 async function callJson(url, token) {
     const headers = new Headers();
     if (token)
@@ -46,6 +47,18 @@ function spawnInterf(args) {
     });
 }
 const DEFAULT_ENGINE_URL = `http://${LOCAL_SERVICE_DEFAULT_HOST}:${LOCAL_SERVICE_DEFAULT_PORT}`;
+function hasInteractiveTerminal() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+function isHttpUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Probe a URL's `/health` endpoint and return whether the engine is up.
  * Used as a fallback when `connection.json` may be missing (e.g. older
@@ -61,12 +74,25 @@ async function probeHealth(url) {
     }
 }
 /**
- * Spawn `interf web` detached and wait until it's reachable. Tries two
- * signals in parallel: the new `~/.interf/connection.json` record AND a
- * direct probe of the default engine URL — so we can connect even when
- * the running engine is an older binary that didn't write the record.
+ * Connect to an engine. Either an existing one already running on the
+ * default port (with a `wasAlreadyRunning` flag so the caller can tell
+ * the user honestly) or a fresh one we spawn here.
+ *
+ * Returns null on timeout / error.
  */
 async function startLocalEngineInBackground() {
+    // First: check whether an engine is ALREADY running on the default
+    // port. If so, don't pretend to start a new one — just connect.
+    if (await probeHealth(DEFAULT_ENGINE_URL)) {
+        try {
+            writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
+        }
+        catch {
+            // best effort
+        }
+        console.log(chalk.dim(`  Engine already running at ${DEFAULT_ENGINE_URL} — connecting.`));
+        return { url: DEFAULT_ENGINE_URL, token: null, wasAlreadyRunning: true };
+    }
     const spinner = p.spinner();
     spinner.start("Starting local Interf engine…");
     const child = spawn(process.argv[1] ?? "interf", ["web"], {
@@ -78,105 +104,110 @@ async function startLocalEngineInBackground() {
     const timeoutMs = 30_000;
     while (Date.now() - startedAt < timeoutMs) {
         await new Promise((r) => setTimeout(r, 250));
-        // Path A: connection.json written by 0.13 server.
+        // Path A: connection.json written by the spawned 0.13+ server.
         const conn = readActiveConnection();
         if (conn) {
             const url = conn.url.replace(/\/+$/, "");
             if (await probeHealth(url)) {
                 spinner.stop(chalk.green(`Engine ready at ${url}`));
-                return { url, token: conn.auth_token };
+                return { url, token: conn.auth_token, wasAlreadyRunning: false };
             }
         }
-        // Path B: direct probe of the default engine URL. Works for any
-        // engine version, including older `interf` binaries that don't
-        // write connection.json.
+        // Path B: spawned engine is ready on the default URL.
         if (await probeHealth(DEFAULT_ENGINE_URL)) {
-            // Recover the connection record so subsequent commands work.
             try {
                 writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
             }
             catch {
-                // best effort — wizard can still proceed using the URL inline
+                // best effort
             }
             spinner.stop(chalk.green(`Engine ready at ${DEFAULT_ENGINE_URL}`));
-            return { url: DEFAULT_ENGINE_URL, token: null };
+            return { url: DEFAULT_ENGINE_URL, token: null, wasAlreadyRunning: false };
         }
     }
     spinner.stop(chalk.red("Timed out waiting for engine to start."));
     return null;
 }
-/** Prompt the user to either start a local engine, log in to a remote one, or quit. */
-async function offerEngineSetup() {
+/**
+ * Print the canonical connect-or-error hint and exit non-zero. Used
+ * whenever the wizard needs an engine but no reachable connection
+ * exists. The wizard does NOT auto-start an engine — `interf web` is
+ * the explicit, foreground way to run one.
+ */
+function exitNoEngineConnected(reason) {
+    console.log();
+    console.log(chalk.yellow(`  ${reason}`));
+    console.log();
+    console.log("  Start one in another terminal:");
+    console.log(chalk.bold("    interf web"));
+    console.log();
+    console.log("  Or connect to a remote engine:");
+    console.log(chalk.bold("    interf login --url <https://…>"));
+    console.log();
+    process.exit(1);
+}
+async function promptForConnection(reason) {
+    if (!hasInteractiveTerminal()) {
+        exitNoEngineConnected(reason);
+    }
     console.log();
-    console.log(chalk.yellow("  No Interf engine is connected."));
+    console.log(chalk.yellow(`  ${reason}`));
     console.log();
     const choice = await p.select({
-        message: "How do you want to connect?",
+        message: "How do you want to continue?",
         options: [
-            { value: "start", label: "Start a local engine now" },
-            { value: "remote", label: "Connect to a remote engine" },
-            { value: "quit", label: "Quit" },
+            { value: "start-local", label: "Start local engine (serves Compiler UI)" },
+            { value: "connect-remote", label: "Connect to remote engine" },
+            { value: "quit", label: chalk.dim("Exit") },
         ],
+        initialValue: "start-local",
     });
     if (p.isCancel(choice) || choice === "quit") {
         p.outro("Bye.");
         return null;
     }
-    if (choice === "start") {
-        const started = await startLocalEngineInBackground();
-        if (started)
-            return started;
-        // Fall through to retry / custom URL fallback.
-        const retry = await p.select({
-            message: "Engine didn't come up. What now?",
-            options: [
-                { value: "probe", label: `Try connecting to ${DEFAULT_ENGINE_URL} (maybe an older engine is already running)` },
-                { value: "remote", label: "Connect to a different URL" },
-                { value: "quit", label: "Quit" },
-            ],
-        });
-        if (p.isCancel(retry) || retry === "quit")
-            return null;
-        if (retry === "probe") {
-            if (await probeHealth(DEFAULT_ENGINE_URL)) {
-                try {
-                    writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
-                }
-                catch { /* best effort */ }
-                return { url: DEFAULT_ENGINE_URL, token: null };
-            }
-            console.log(chalk.red(`  No engine reachable at ${DEFAULT_ENGINE_URL}.`));
-            return null;
-        }
-        // retry === "remote" falls through to the remote-URL block below
+    if (choice === "start-local") {
+        console.log();
+        console.log(chalk.dim("  Starting `interf web` in this terminal. Press Ctrl-C to stop the engine."));
+        console.log();
+        const code = await spawnInterf(["web"]);
+        process.exit(code);
     }
-    if (choice === "remote" || choice === "start") {
-        const remoteUrl = await p.text({
-            message: "Remote engine URL",
-            placeholder: "https://your-instance.example.com",
-            validate: (v) => (v.startsWith("http://") || v.startsWith("https://") ? undefined : "Must start with http:// or https://"),
-        });
-        if (p.isCancel(remoteUrl))
-            return null;
-        const remoteToken = await p.password({
-            message: "Bearer token (leave blank if none)",
-        });
-        if (p.isCancel(remoteToken))
-            return null;
-        const exitCode = await spawnInterf([
-            "login",
-            "--url",
-            String(remoteUrl),
-            ...(remoteToken ? ["--token", String(remoteToken)] : []),
-        ]);
-        if (exitCode !== 0)
-            return null;
-        const conn = readActiveConnection();
-        if (!conn)
-            return null;
-        return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
+    const urlValue = await p.text({
+        message: "Remote engine URL",
+        placeholder: "https://api.interf.cloud",
+        validate: (value) => {
+            const trimmed = String(value ?? "").trim();
+            if (!trimmed)
+                return "URL is required.";
+            const parsed = ConnectionRecordSchema.safeParse({ url: trimmed, auth_token: null });
+            return parsed.success && isHttpUrl(trimmed) ? undefined : "Enter a valid http(s) URL.";
+        },
+    });
+    if (p.isCancel(urlValue)) {
+        p.outro("Bye.");
+        return null;
     }
-    return null;
+    const tokenValue = await p.password({
+        message: "Bearer token (optional)",
+        mask: "*",
+    });
+    if (p.isCancel(tokenValue)) {
+        p.outro("Bye.");
+        return null;
+    }
+    const record = ConnectionRecordSchema.parse({
+        url: String(urlValue).trim(),
+        auth_token: String(tokenValue ?? "").trim() || null,
+    });
+    const url = record.url.replace(/\/+$/, "");
+    const probe = await callJson(`${url}/health`, record.auth_token);
+    if (probe.status === 0) {
+        return promptForConnection(`Connection ${url} is unreachable.`);
+    }
+    writeConnection(record);
+    console.log(chalk.green("Connection saved."));
+    return { url, token: record.auth_token };
 }
 /** Validate that a path exists and is a directory. */
 function validateSourcePath(value) {
@@ -242,25 +273,40 @@ async function flowCreatePreparation(conn) {
     });
     if (p.isCancel(prepId))
         return null;
+    const about = await p.text({
+        message: "What is this preparation for? (one line — the agent task intent)",
+        placeholder: "Prepare these notes so an agent can answer questions about them.",
+    });
+    if (p.isCancel(about))
+        return null;
+    const aboutText = String(about ?? "").trim();
     const sourcePath = await promptSourcePath();
     if (!sourcePath)
         return null;
-    // Offer the methods that the connected instance knows about.
+    // Offer the methods that the connected instance knows about. Method
+    // binding is OPTIONAL at create time — the agent first creates the
+    // preparation (the unit of agent work) and may pick or draft a method
+    // for it later.
     const methodsResp = await callJson(`${conn.url}/v1/methods`, conn.token);
     const methods = methodsResp.body?.methods ?? [];
     const methodOptions = methods
         .map((m) => ({ value: m.method_id ?? m.id ?? "", label: `${m.method_id ?? m.id ?? "(?)"}${m.label ? ` — ${m.label}` : ""}` }))
         .filter((opt) => opt.value !== "");
-    let methodId;
+    let methodId = null;
+    const skipOption = { value: "__skip__", label: chalk.dim("Skip — pick or draft a method later") };
+    const customOption = { value: "__custom__", label: "Other (type a method id)" };
     if (methodOptions.length > 0) {
         const chosen = await p.select({
-            message: "Which method?",
-            options: [...methodOptions, { value: "__custom__", label: "Other (type a method id)" }],
+            message: "Pick a method (optional — you can do this later)",
+            options: [...methodOptions, customOption, skipOption],
             initialValue: methodOptions.find((o) => o.value === "interf-default")?.value ?? methodOptions[0]?.value,
         });
         if (p.isCancel(chosen))
             return null;
-        if (chosen === "__custom__") {
+        if (chosen === "__skip__") {
+            methodId = null;
+        }
+        else if (chosen === "__custom__") {
             const typed = await p.text({
                 message: "Method id",
                 placeholder: "interf-default",
@@ -274,13 +320,24 @@ async function flowCreatePreparation(conn) {
         }
     }
     else {
-        const typed = await p.text({
-            message: "Method id (no methods registered yet)",
-            initialValue: "interf-default",
+        const choose = await p.select({
+            message: "No methods registered yet — pick a method id?",
+            options: [
+                { value: "__type__", label: "Type a method id" },
+                skipOption,
+            ],
         });
-        if (p.isCancel(typed))
+        if (p.isCancel(choose))
             return null;
-        methodId = String(typed);
+        if (choose === "__type__") {
+            const typed = await p.text({
+                message: "Method id",
+                initialValue: "interf-default",
+            });
+            if (p.isCancel(typed))
+                return null;
+            methodId = String(typed);
+        }
     }
     const exitCode = await spawnInterf([
         "prep",
@@ -288,8 +345,8 @@ async function flowCreatePreparation(conn) {
         String(prepId),
         "--source",
         resolve(String(sourcePath)),
-        "--method",
-        methodId,
+        ...(methodId ? ["--method", methodId] : []),
+        ...(aboutText ? ["--about", aboutText] : []),
     ]);
     if (exitCode !== 0)
         return null;
@@ -313,15 +370,22 @@ async function pickPreparation(conn, message) {
         return null;
     return String(choice);
 }
-async function showActionMenu(conn) {
+async function showActionMenu(conn, options = { allowCompileVerify: true }) {
+    const compileLabel = options.allowCompileVerify
+        ? "Compile a preparation"
+        : chalk.dim("Compile a preparation (no agents available)");
+    const verifyLabel = options.allowCompileVerify
+        ? "Verify a preparation's claim-checks"
+        : chalk.dim("Verify (no agents available)");
     const action = await p.select({
         message: "What do you want to do?",
         options: [
+            { value: "ui", label: "Open Compiler UI" },
             { value: "ls", label: "List preparations" },
             { value: "create", label: "Create a new preparation" },
-            { value: "compile", label: "Compile a preparation" },
-            { value: "test", label: "Run readiness checks (test) for a preparation" },
-            { value: "ui", label: "Open Compiler UI" },
+            { value: "agents", label: "Manage agents (list / register / role-map)" },
+            { value: "compile", label: compileLabel },
+            { value: "verify", label: verifyLabel },
             { value: "stop", label: "Stop the local engine" },
             { value: "quit", label: "Quit" },
         ],
@@ -332,26 +396,47 @@ async function showActionMenu(conn) {
         await spawnInterf(["prep", "ls"]);
         return "continue";
     }
+    if (action === "agents") {
+        await spawnInterf(["agents", "ls"]);
+        return "continue";
+    }
     if (action === "create") {
         const newId = await flowCreatePreparation(conn);
         if (newId) {
-            const compileNow = await p.confirm({ message: `Compile ${newId} now?`, initialValue: true });
-            if (!p.isCancel(compileNow) && compileNow) {
-                await spawnInterf(["compile", newId]);
+            if (!options.allowCompileVerify) {
+                console.log(chalk.dim("  Skipping compile prompt — no agents available. Install one then run `interf compile " +
+                    newId +
+                    "`."));
+            }
+            else {
+                const compileNow = await p.confirm({ message: `Compile ${newId} now?`, initialValue: true });
+                if (!p.isCancel(compileNow) && compileNow) {
+                    await spawnInterf(["compile", newId]);
+                }
             }
         }
         return "continue";
     }
     if (action === "compile") {
+        if (!options.allowCompileVerify) {
+            console.log(chalk.yellow("  Cannot compile — no agents available."));
+            console.log("  Install Claude Code, Codex, Gemini, or another agent CLI, or");
+            console.log("  register a custom CLI: `interf agents register <name> --command <cmd>`.");
+            return "continue";
+        }
         const id = await pickPreparation(conn, "Which preparation to compile?");
         if (id)
             await spawnInterf(["compile", id]);
         return "continue";
     }
-    if (action === "test") {
-        const id = await pickPreparation(conn, "Which preparation to test?");
+    if (action === "verify") {
+        if (!options.allowCompileVerify) {
+            console.log(chalk.yellow("  Cannot verify — no agents available."));
+            return "continue";
+        }
+        const id = await pickPreparation(conn, "Which preparation to verify?");
         if (id)
-            await spawnInterf(["test", id]);
+            await spawnInterf(["verify", id]);
         return "continue";
     }
     if (action === "ui") {
@@ -382,42 +467,312 @@ async function showActionMenu(conn) {
     }
     return "continue";
 }
+/**
+ * Agent install-cards menu shown when the connected engine has zero
+ * detected + registered agents. Returns:
+ *   - "rerun" → user installed an agent and wants to retry detection
+ *   - "skip"  → continue in UI-only mode (no compile/verify)
+ *   - "quit"  → exit
+ */
+async function showAgentInstallCards() {
+    console.log();
+    console.log(chalk.yellow("  No agents detected."));
+    console.log();
+    console.log("  Interf needs at least one agent to compile and verify preparations.");
+    console.log();
+    const choice = await p.select({
+        message: "How do you want to proceed?",
+        options: [
+            {
+                value: "claude-code",
+                label: `Install Claude Code  ${chalk.dim("(opens install docs)")}`,
+            },
+            {
+                value: "codex",
+                label: `Install OpenAI Codex ${chalk.dim("(opens install docs)")}`,
+            },
+            {
+                value: "gemini",
+                label: `Install Gemini CLI   ${chalk.dim("(opens install docs)")}`,
+            },
+            {
+                value: "custom",
+                label: "Register a custom CLI as an agent",
+            },
+            {
+                value: "skip",
+                label: chalk.dim("Skip — UI-only mode (browse existing portable contexts only)"),
+            },
+            { value: "quit", label: chalk.dim("Quit") },
+        ],
+    });
+    if (p.isCancel(choice) || choice === "quit")
+        return "quit";
+    if (choice === "skip")
+        return "skip";
+    if (choice === "custom") {
+        const name = await p.text({
+            message: "Agent name (lowercase identifier)",
+            placeholder: "opencode",
+            validate: (value) => /^[a-z0-9][a-z0-9-]*$/.test(value)
+                ? undefined
+                : "Lowercase letters, numbers, and dashes only.",
+        });
+        if (p.isCancel(name))
+            return "quit";
+        const command = await p.text({
+            message: "Command to invoke",
+            placeholder: "opencode --prompt",
+        });
+        if (p.isCancel(command))
+            return "quit";
+        const displayName = await p.text({
+            message: `Display name (defaults to "${name}")`,
+            placeholder: String(name),
+        });
+        if (p.isCancel(displayName))
+            return "quit";
+        const cliDisplayName = String(displayName).trim() || String(name);
+        const exitCode = await spawnInterf([
+            "agents",
+            "register",
+            String(name),
+            "--command",
+            String(command),
+            "--display-name",
+            cliDisplayName,
+        ]);
+        return exitCode === 0 ? "rerun" : "quit";
+    }
+    // Print install instructions + offer to copy the install command.
+    const installCommands = {
+        "claude-code": {
+            command: "npm install -g @anthropic-ai/claude-code",
+            docs: "https://docs.claude.com/claude-code",
+        },
+        codex: {
+            command: "npm install -g @openai/codex",
+            docs: "https://github.com/openai/codex",
+        },
+        gemini: {
+            command: "npm install -g @google/gemini-cli",
+            docs: "https://github.com/google-gemini/gemini-cli",
+        },
+    };
+    const target = installCommands[String(choice)];
+    if (target) {
+        console.log();
+        console.log(`  Install command: ${chalk.bold(target.command)}`);
+        console.log(`  Docs:            ${chalk.dim(target.docs)}`);
+        console.log();
+        const next = await p.select({
+            message: "What now?",
+            options: [
+                { value: "rerun", label: "I installed it — re-detect" },
+                { value: "skip", label: chalk.dim("Skip — continue in UI-only mode") },
+                { value: "quit", label: chalk.dim("Quit") },
+            ],
+        });
+        if (p.isCancel(next) || next === "quit")
+            return "quit";
+        if (next === "skip")
+            return "skip";
+        return "rerun";
+    }
+    return "rerun";
+}
+async function fetchAgentSnapshot(conn) {
+    const instance = await callJson(`${conn.url}/v1/instance`, conn.token);
+    const agentsResponse = await callJson(`${conn.url}/v1/agents`, conn.token);
+    if (instance.status !== 200)
+        return null;
+    // Engines pre-0.15 don't expose /v1/agents. Surface the gap explicitly
+    // so the wizard can tell the user to restart instead of silently going
+    // through the install-cards flow.
+    const engineSupportsAgents = agentsResponse.status === 200 && instance.body?.agent_count !== undefined;
+    return {
+        agentCount: instance.body?.agent_count ?? 0,
+        defaultAgent: instance.body?.default_agent ?? null,
+        agents: agentsResponse.body?.agents ?? [],
+        engineSupportsAgents,
+    };
+}
 async function runWizard(args) {
-    let conn;
+    // The wizard is the human entry point, so it can ask how to connect.
+    // It still never auto-starts an engine: starting `interf web` is an
+    // explicit foreground choice, and script/agent commands keep the
+    // connect-or-error behavior.
     const initial = readActiveConnection({
         urlOverride: args.url,
         authTokenOverride: args.token,
     });
+    let conn = null;
     if (!initial) {
-        conn = await offerEngineSetup();
-        if (!conn) {
+        if (await probeHealth(DEFAULT_ENGINE_URL)) {
+            try {
+                writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
+            }
+            catch {
+                // best effort
+            }
             console.log();
-            console.log(CONNECT_OR_ERROR_HINT);
-            process.exit(1);
+            console.log(chalk.dim(`  Engine already running at ${DEFAULT_ENGINE_URL} — connecting.`));
+            conn = { url: DEFAULT_ENGINE_URL, token: null };
+        }
+        else {
+            conn = await promptForConnection("No Interf engine is connected.");
         }
     }
     else {
         const url = initial.url.replace(/\/+$/, "");
         const probe = await callJson(`${url}/health`, initial.auth_token);
         if (probe.status === 0) {
-            console.log(chalk.yellow(`  Connection ${url} is unreachable.`));
-            conn = await offerEngineSetup();
-            if (!conn)
-                process.exit(1);
+            if (!args.url && await probeHealth(DEFAULT_ENGINE_URL)) {
+                try {
+                    writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
+                }
+                catch {
+                    // best effort
+                }
+                console.log();
+                console.log(chalk.dim(`  Saved connection ${url} is unreachable; using local engine at ${DEFAULT_ENGINE_URL}.`));
+                conn = { url: DEFAULT_ENGINE_URL, token: null };
+            }
+            else {
+                conn = await promptForConnection(`Connection ${url} is unreachable.`);
+            }
         }
         else {
             conn = { url, token: initial.auth_token };
         }
     }
+    if (!conn) {
+        return;
+    }
     const instance = await callJson(`${conn.url}/v1/instance`, conn.token);
     console.log();
     console.log(chalk.bold(`  Connected to ${conn.url}`));
     if (instance.body?.package_version) {
         console.log(chalk.dim(`  v${instance.body.package_version} · ${instance.body.preparation_count ?? 0} preparation(s)`));
     }
+    // 0.15 — surface the connected agents up front. When zero are
+    // detected, run the install-cards menu before letting the user
+    // try to compile / verify.
+    let agents = await fetchAgentSnapshot(conn);
+    if (agents && !agents.engineSupportsAgents) {
+        console.log();
+        console.log(chalk.yellow("  ⚠  The connected engine is older than this CLI."));
+        console.log(chalk.dim("     /v1/agents is not available — agent management is disabled."));
+        console.log();
+        const choice = await p.select({
+            message: "Restart the engine now to pick up new features?",
+            options: [
+                { value: "restart", label: "Yes — stop old engine, start new one" },
+                { value: "continue", label: chalk.dim("No — continue with limited features (no agents UI / compile / verify)") },
+                { value: "quit", label: "Quit" },
+            ],
+            initialValue: "restart",
+        });
+        if (p.isCancel(choice) || choice === "quit") {
+            p.outro("Bye.");
+            return;
+        }
+        if (choice === "restart") {
+            console.log();
+            console.log(chalk.dim("  Stopping old engine…"));
+            await spawnInterf(["web", "stop"]);
+            // Small grace period for the OS to release the port.
+            await new Promise((r) => setTimeout(r, 800));
+            const restarted = await startLocalEngineInBackground();
+            if (!restarted) {
+                console.log(chalk.red("  Could not start the new engine. Try manually: interf web"));
+                process.exit(1);
+            }
+            conn = restarted;
+            agents = await fetchAgentSnapshot(conn);
+        }
+    }
+    // Treat "all registered agents are unavailable" the same as "no agents
+    // detected" — the install-cards menu lets the user install or register
+    // a real one before the active-agent picker runs.
+    function installedAgentCount(snapshot) {
+        if (!snapshot)
+            return 0;
+        return snapshot.agents.filter((agent) => agent.available !== false).length;
+    }
+    let allowCompileVerify = installedAgentCount(agents) > 0;
+    while (agents &&
+        agents.engineSupportsAgents &&
+        installedAgentCount(agents) === 0) {
+        const decision = await showAgentInstallCards();
+        if (decision === "quit") {
+            p.outro("Bye.");
+            return;
+        }
+        if (decision === "skip") {
+            allowCompileVerify = false;
+            break;
+        }
+        // decision === "rerun"
+        agents = await fetchAgentSnapshot(conn);
+        allowCompileVerify = installedAgentCount(agents) > 0;
+    }
+    if (agents && agents.engineSupportsAgents && installedAgentCount(agents) > 0) {
+        // Always confirm the active agent before the action menu. Pre-select
+        // the current default; user presses Enter to keep it, Up/Down to
+        // change. Customizing per-stage (role-map) is opt-in advanced —
+        // accessible via `interf agents map <role> <agent>`.
+        //
+        // Custom agents whose CLI is no longer on PATH carry `available: false`
+        // — show them in a hint instead of as selectable choices so the picker
+        // does not let the user pick something the engine cannot run.
+        const stale = agents.agents.filter((agent) => agent.available === false);
+        if (stale.length > 0) {
+            const names = stale.map((agent) => agent.display_name || agent.name).join(", ");
+            console.log();
+            console.log(chalk.yellow(`  ⚠  Registered but not installed: ${names}`));
+            console.log(chalk.dim(`     Reinstall the CLI or run \`interf agents unregister <name>\` to remove the stale entry.`));
+        }
+        const installed = agents.agents.filter((agent) => agent.available !== false);
+        const options = installed.map((agent) => ({
+            value: agent.name,
+            label: `${agent.display_name || agent.name}${agent.name === agents.defaultAgent ? chalk.green("  (current active)") : ""}${agent.source === "user" ? chalk.dim("  [custom]") : ""}`,
+        }));
+        options.push({ value: "__register__", label: chalk.dim("Register a custom CLI as an agent…") });
+        const installedDefault = installed.some((agent) => agent.name === agents.defaultAgent)
+            ? agents.defaultAgent
+            : null;
+        const choice = await p.select({
+            message: "Active agent for this session (will run every role unless overridden)",
+            options,
+            initialValue: installedDefault ?? options[0]?.value,
+        });
+        if (p.isCancel(choice)) {
+            p.outro("Bye.");
+            return;
+        }
+        if (choice === "__register__") {
+            const decision = await showAgentInstallCards();
+            if (decision === "quit") {
+                p.outro("Bye.");
+                return;
+            }
+            agents = await fetchAgentSnapshot(conn);
+        }
+        else if (choice !== agents.defaultAgent) {
+            // Switch active agent before proceeding. Reuse the existing CLI to
+            // sweep the role-map's `general` row + any role pinned to the
+            // previous active.
+            await spawnInterf(["agents", "use", String(choice)]);
+            agents = await fetchAgentSnapshot(conn);
+        }
+        if (agents && agents.defaultAgent) {
+            console.log(chalk.dim(`  Active: ${agents.defaultAgent} · roles default to ${agents.defaultAgent}`));
+        }
+    }
     for (;;) {
         console.log();
-        const next = await showActionMenu(conn);
+        const next = await showActionMenu(conn, { allowCompileVerify });
         if (next === "exit")
             break;
     }