@interf/compiler 0.16.0 → 0.21.0

package/dist/cli/commands/status.js

@@ -64,12 +64,14 @@ export const statusCommand = {
         console.log();
         console.log(chalk.bold(`  Preparations (${list.length})`));
         if (list.length === 0) {
-            console.log(chalk.dim("  No preparations yet. `interf prep create <id> --source <path> --method <id>`."));
+            console.log(chalk.dim("  No preparations yet. `interf prep create <id> --source <path>`."));
         }
         else {
             for (const prep of list) {
                 const readiness = prep.readiness?.status ?? "—";
-                console.log(`  ${chalk.bold(prep.id)} ${chalk.dim(`(${prep.method_id} · ${readiness})`)}`);
+                const buildPlan = prep.method_id ?? "no Build Plan";
+                const requested = prep.requested_artifacts?.length ?? 0;
+                console.log(`  ${chalk.bold(prep.id)} ${chalk.dim(`(${buildPlan} · ${requested} requested · ${readiness})`)}`);
                 console.log(chalk.dim(`    source: ${prep.source.locator}`));
             }
         }

package/dist/cli/commands/test.d.ts

@@ -0,0 +1,10 @@
+import type { CommandModule } from "yargs";
+type TestTarget = "compiled" | "source-files";
+interface TestArgs {
+    prepId: string;
+    target?: TestTarget;
+    url?: string;
+    token?: string;
+}
+export declare const testCommand: CommandModule<unknown, TestArgs>;
+export {};

package/dist/cli/commands/{verify.js → test.js}

@@ -1,10 +1,13 @@
 /**
- * `interf verify <prep-id>` — verify a preparation's claim-checks via a
- * judge against the latest compiled portable context. Together with the
- * method's structural checks (auto-run on every `interf compile`), this
- * feeds the preparation's overall readiness state.
+ * `interf test <prep-id>` — run readiness checks for a Preparation via a
+ * judge against the latest portable context (default) or against the source
+ * baseline (`--target source-files`). The source-files target reveals how
+ * much value the Method adds. Together with Method Artifact checks
+ * (auto-run on every `interf compile`), this feeds the Preparation's
+ * overall readiness state.
  *
- *   interf verify bristol
+ *   interf test bristol
+ *   interf test bristol --target source-files
  */
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
@@ -38,37 +41,41 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
-export const verifyCommand = {
-    command: "verify <prep-id>",
-    describe: "Verify a preparation's claim-checks against its portable context",
+export const testCommand = {
+    command: "test <prep-id>",
+    describe: "Run readiness checks against a Preparation's portable context (or source-files baseline)",
     builder: (yargs) => yargs
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("target", {
+        type: "string",
+        choices: ["compiled", "source-files"],
+        default: "compiled",
+        describe: "Judge target: 'compiled' (default) checks the portable context, 'source-files' checks the raw Source baseline",
+    })
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" }),
     handler: async (args) => {
         const { url, token } = resolveConnection(args);
-        // 0.15 hard-error: refuse to start a verify run if the engine has
-        // zero connected agents — verifier-role stages can't run without
-        // one.
+        // 0.15 hard-error: refuse to start a readiness-check run if the engine
+        // has zero connected agents — verifier-role stages can't run without one.
         const instance = await callJson(`${url}/v1/instance`, token);
         if (instance.body && instance.body.agent_count === 0) {
-            console.error(chalk.red("  Cannot verify — no agents available."));
+            console.error(chalk.red("  Cannot run readiness checks — no agents available."));
             console.error("  Install Claude Code, Codex, Gemini, or another agent CLI, or");
             console.error("  register a custom CLI: `interf agents register <name> --command <cmd>`.");
             process.exit(1);
         }
-        // Verify the user's claims against the compiled portable context.
-        // The legacy "source-files" / "both" targets (file-as-is judging)
-        // are gone — claims are evaluated against the compiled output only.
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/verify-runs`, token, { method: "POST", body: JSON.stringify({ mode: "compiled" }) });
+        const target = args.target ?? "compiled";
+        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/verify-runs`, token, { method: "POST", body: JSON.stringify({ target }) });
         if (status !== 201 && status !== 200) {
-            console.error(chalk.red(`Failed to start verify run for ${args.prepId} (HTTP ${status}).`));
+            console.error(chalk.red(`Failed to start readiness-check run for ${args.prepId} (HTTP ${status}).`));
             if (raw)
                 console.error(raw);
             process.exit(1);
         }
         console.log();
         console.log(`  Run ${chalk.bold(body?.run_id ?? "(?)")} ${chalk.dim(`(${body?.status ?? "started"})`)}`);
+        console.log(`  Target: ${target}`);
         if (body?.readiness?.status)
             console.log(`  Readiness: ${body.readiness.status}`);
         if (body?.error)

package/dist/cli/commands/web.js

@@ -2,6 +2,7 @@
  * `interf web` — start the engine in the foreground until Ctrl-C.
  *
  *   interf web                # start on default port; hard error if port busy
+ *   interf web start          # start the engine in the background
  *   interf web stop           # send SIGTERM to the running engine
  *   interf web status         # print engine info via the connected URL
  *
@@ -10,11 +11,13 @@
  * connect without a pointer file.
  */
 import chalk from "chalk";
-import { readFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
 import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, buildLocalServiceUrl, } from "../../packages/engine/routes.js";
 import { startLocalService } from "../../packages/engine/server.js";
 import { createNativeLocalServiceRunHandlers } from "../../packages/engine/native-run-handlers.js";
-import { CONNECT_OR_ERROR_HINT, clearConnection, readActiveConnection, } from "../../packages/engine/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, clearConnection, readActiveConnection, writeConnection, } from "../../packages/engine/connection-config.js";
 import { serviceRegistryPath } from "../../packages/engine/instance-paths.js";
 function packageVersionFromManifest() {
     try {
@@ -53,12 +56,6 @@ async function runWebForeground(args) {
         }
         throw error;
     }
-    console.log();
-    console.log(`  Interf engine: ${chalk.bold(service.url)}`);
-    console.log(`  Compiler UI:   ${service.url}/`);
-    console.log(`  Health:        ${service.url}/health`);
-    console.log(chalk.dim("  Press Ctrl-C to stop."));
-    console.log();
     const shutdown = async () => {
         try {
             await service.close();
@@ -68,12 +65,84 @@ async function runWebForeground(args) {
         }
         process.exit(0);
     };
+    console.log();
+    console.log(`  Interf engine: ${chalk.bold(service.url)}`);
+    console.log(`  Compiler UI:   ${service.url}/`);
+    console.log(`  Health:        ${service.url}/health`);
+    console.log(chalk.dim("  Press Ctrl-C to stop."));
+    console.log();
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     await new Promise(() => {
         /* block forever; signals trigger shutdown */
     });
 }
+async function isEngineReachable(url) {
+    try {
+        const response = await fetch(`${url}/health`);
+        return response.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForEngine(url, timeoutMs) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        if (await isEngineReachable(url))
+            return true;
+        await new Promise((resolveWait) => setTimeout(resolveWait, 150));
+    }
+    return false;
+}
+function managedWebLogPath(port) {
+    return `${dirname(serviceRegistryPath())}/interf-web-${port}.log`;
+}
+async function runWebStart(args) {
+    const host = args.host ?? LOCAL_SERVICE_DEFAULT_HOST;
+    const port = args.port ?? LOCAL_SERVICE_DEFAULT_PORT;
+    const url = buildLocalServiceUrl({ host, port });
+    if (await isEngineReachable(url)) {
+        writeConnection({ url, auth_token: null });
+        console.log(chalk.green(`Interf engine already running at ${chalk.bold(url)}.`));
+        console.log(`Compiler UI: ${url}/`);
+        return;
+    }
+    const binPath = process.argv[1];
+    if (!binPath) {
+        console.error(chalk.red("Cannot locate the Interf CLI entrypoint for managed start."));
+        console.error(`Try running \`interf web\` in a separate terminal instead.`);
+        process.exit(1);
+    }
+    const logPath = args.log ?? managedWebLogPath(port);
+    mkdirSync(dirname(logPath), { recursive: true });
+    const stdoutFd = openSync(logPath, "a");
+    const stderrFd = openSync(logPath, "a");
+    let child;
+    try {
+        child = spawn(process.execPath, [binPath, "web", "--host", host, "--port", String(port)], {
+            detached: true,
+            stdio: ["ignore", stdoutFd, stderrFd],
+            env: process.env,
+        });
+        child.unref();
+    }
+    finally {
+        closeSync(stdoutFd);
+        closeSync(stderrFd);
+    }
+    const ready = await waitForEngine(url, args.timeoutMs ?? 5000);
+    if (!ready) {
+        console.error(chalk.red(`Timed out waiting for Interf engine at ${url}.`));
+        console.error(`Log: ${logPath}`);
+        process.exit(1);
+    }
+    writeConnection({ url, auth_token: null });
+    console.log(chalk.green(`Started Interf engine at ${chalk.bold(url)}.`));
+    console.log(`Compiler UI: ${url}/`);
+    console.log(`Log: ${logPath}`);
+    console.log(chalk.dim(`Stop it with \`interf web stop\`.`));
+}
 function findEnginePidByUrl(url) {
     try {
         const raw = readFileSync(serviceRegistryPath(), "utf8");
@@ -196,6 +265,11 @@ export const webCommand = {
     command: "web [subcommand]",
     describe: "Start / stop / inspect the Interf engine",
     builder: (yargs) => yargs
+        .command("start", "Start the engine in the background", (y) => y
+        .option("host", { type: "string", default: LOCAL_SERVICE_DEFAULT_HOST, describe: "Host to bind" })
+        .option("port", { type: "number", default: LOCAL_SERVICE_DEFAULT_PORT, describe: "Port to bind" })
+        .option("timeout-ms", { type: "number", default: 5000, describe: "How long to wait for startup" })
+        .option("log", { type: "string", describe: "Path to write background engine logs" }), runWebStart)
         .command("stop", "Stop the connected engine", (y) => y
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" }), runWebStop)

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,7 +16,7 @@ import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, resolve } from "node:path";
 import { spawn } from "node:child_process";
-import { readActiveConnection, writeConnection, } from "../../packages/engine/connection-config.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();
@@ -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
@@ -133,6 +146,69 @@ function exitNoEngineConnected(reason) {
     console.log();
     process.exit(1);
 }
+async function promptForConnection(reason) {
+    if (!hasInteractiveTerminal()) {
+        exitNoEngineConnected(reason);
+    }
+    console.log();
+    console.log(chalk.yellow(`  ${reason}`));
+    console.log();
+    const choice = await p.select({
+        message: "How do you want to continue?",
+        options: [
+            { 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-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);
+    }
+    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;
+    }
+    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) {
     const abs = resolve(value);
@@ -170,7 +246,7 @@ async function promptSourcePath() {
     }
     options.push({ value: "__custom__", label: chalk.dim("Type a custom path…") });
     const choice = await p.select({
-        message: "Where's the source folder?",
+        message: "Where are the source files?",
         options,
         initialValue: resolve(cwd),
     });
@@ -178,7 +254,7 @@ async function promptSourcePath() {
         return null;
     if (choice === "__custom__") {
         const typed = await p.text({
-            message: "Custom source folder path",
+            message: "Custom source path",
             placeholder: cwd,
             initialValue: cwd,
             validate: validateSourcePath,
@@ -207,23 +283,22 @@ async function flowCreatePreparation(conn) {
     const sourcePath = await promptSourcePath();
     if (!sourcePath)
         return null;
-    // 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.
+    // Offer saved Build Plans, but keep selection optional. The agent-first
+    // path usually creates the Preparation from requested Artifacts first,
+    // then drafts a custom Build Plan for review.
     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 = 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)" };
+    const skipOption = { value: "__skip__", label: chalk.dim("Skip — pick or draft a Build Plan later") };
+    const customOption = { value: "__custom__", label: "Other (type a Build Plan / Method id)" };
     if (methodOptions.length > 0) {
         const chosen = await p.select({
-            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,
+            message: "Select a Build Plan (optional — you can do this later)",
+            options: [skipOption, ...methodOptions, customOption],
+            initialValue: skipOption.value,
         });
         if (p.isCancel(chosen))
             return null;
@@ -232,7 +307,7 @@ async function flowCreatePreparation(conn) {
         }
         else if (chosen === "__custom__") {
             const typed = await p.text({
-                message: "Method id",
+                message: "Build Plan / Method id",
                 placeholder: "interf-default",
             });
             if (p.isCancel(typed))
@@ -245,17 +320,17 @@ async function flowCreatePreparation(conn) {
     }
     else {
         const choose = await p.select({
-            message: "No methods registered yet — pick a method id?",
+            message: "No saved Build Plans registered yet — pick an id?",
             options: [
-                { value: "__type__", label: "Type a method id" },
                 skipOption,
+                { value: "__type__", label: "Type a Build Plan / Method id" },
             ],
         });
         if (p.isCancel(choose))
             return null;
         if (choose === "__type__") {
             const typed = await p.text({
-                message: "Method id",
+                message: "Build Plan / Method id",
                 initialValue: "interf-default",
             });
             if (p.isCancel(typed))
@@ -287,20 +362,20 @@ async function pickPreparation(conn, message) {
         message,
         options: list.map((prep) => ({
             value: prep.id,
-            label: `${prep.id} ${chalk.dim(`(${prep.method_id} · ${prep.readiness?.status ?? "—"})`)}`,
+            label: `${prep.id} ${chalk.dim(`(${prep.method_id ?? "no Build Plan"} · ${prep.readiness?.status ?? "—"})`)}`,
         })),
     });
     if (p.isCancel(choice))
         return null;
     return String(choice);
 }
-async function showActionMenu(conn, options = { allowCompileVerify: true }) {
-    const compileLabel = options.allowCompileVerify
+async function showActionMenu(conn, options = { allowAgentRuns: true }) {
+    const compileLabel = options.allowAgentRuns
         ? "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 testLabel = options.allowAgentRuns
+        ? "Run readiness checks"
+        : chalk.dim("Readiness checks (no agents available)");
     const action = await p.select({
         message: "What do you want to do?",
         options: [
@@ -309,7 +384,7 @@ async function showActionMenu(conn, options = { allowCompileVerify: true }) {
             { value: "create", label: "Create a new preparation" },
             { value: "agents", label: "Manage agents (list / register / role-map)" },
             { value: "compile", label: compileLabel },
-            { value: "verify", label: verifyLabel },
+            { value: "test", label: testLabel },
             { value: "stop", label: "Stop the local engine" },
             { value: "quit", label: "Quit" },
         ],
@@ -327,7 +402,7 @@ async function showActionMenu(conn, options = { allowCompileVerify: true }) {
     if (action === "create") {
         const newId = await flowCreatePreparation(conn);
         if (newId) {
-            if (!options.allowCompileVerify) {
+            if (!options.allowAgentRuns) {
                 console.log(chalk.dim("  Skipping compile prompt — no agents available. Install one then run `interf compile " +
                     newId +
                     "`."));
@@ -342,7 +417,7 @@ async function showActionMenu(conn, options = { allowCompileVerify: true }) {
         return "continue";
     }
     if (action === "compile") {
-        if (!options.allowCompileVerify) {
+        if (!options.allowAgentRuns) {
             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>`.");
@@ -353,14 +428,14 @@ async function showActionMenu(conn, options = { allowCompileVerify: true }) {
             await spawnInterf(["compile", id]);
         return "continue";
     }
-    if (action === "verify") {
-        if (!options.allowCompileVerify) {
-            console.log(chalk.yellow("  Cannot verify — no agents available."));
+    if (action === "test") {
+        if (!options.allowAgentRuns) {
+            console.log(chalk.yellow("  Cannot run readiness checks — no agents available."));
             return "continue";
         }
-        const id = await pickPreparation(conn, "Which preparation to verify?");
+        const id = await pickPreparation(conn, "Which preparation should Interf test?");
         if (id)
-            await spawnInterf(["verify", id]);
+            await spawnInterf(["test", id]);
         return "continue";
     }
     if (action === "ui") {
@@ -395,14 +470,14 @@ async function showActionMenu(conn, options = { allowCompileVerify: true }) {
  * 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)
+ *   - "skip"  → continue in UI-only mode (no compile/test)
  *   - "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("  Interf needs at least one agent to compile source files and run readiness checks.");
     console.log();
     const choice = await p.select({
         message: "How do you want to proceed?",
@@ -522,25 +597,57 @@ async function fetchAgentSnapshot(conn) {
     };
 }
 async function runWizard(args) {
-    // Connect-or-error: the wizard never auto-starts an engine. If
-    // `~/.interf/connection.json` is missing or unreachable, exit
-    // non-zero and tell the user to run `interf web` (or
-    // `interf login`) explicitly. This keeps the engine lifecycle in
-    // the user's hands — no surprise background processes, no stale
-    // binaries served by a long-lived auto-spawn.
+    // 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) {
-        exitNoEngineConnected("No Interf engine is connected.");
+        if (await probeHealth(DEFAULT_ENGINE_URL)) {
+            try {
+                writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
+            }
+            catch {
+                // best effort
+            }
+            console.log();
+            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.");
+        }
     }
-    const url = initial.url.replace(/\/+$/, "");
-    const probe = await callJson(`${url}/health`, initial.auth_token);
-    if (probe.status === 0) {
-        exitNoEngineConnected(`Connection ${url} is unreachable.`);
+    else {
+        const url = initial.url.replace(/\/+$/, "");
+        const probe = await callJson(`${url}/health`, initial.auth_token);
+        if (probe.status === 0) {
+            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;
     }
-    let conn = { url, token: initial.auth_token };
     const instance = await callJson(`${conn.url}/v1/instance`, conn.token);
     console.log();
     console.log(chalk.bold(`  Connected to ${conn.url}`));
@@ -549,7 +656,7 @@ async function runWizard(args) {
     }
     // 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.
+    // try to compile or run readiness checks.
     let agents = await fetchAgentSnapshot(conn);
     if (agents && !agents.engineSupportsAgents) {
         console.log();
@@ -560,7 +667,7 @@ async function runWizard(args) {
             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: "continue", label: chalk.dim("No — continue with limited features (no agents UI / compile / test)") },
                 { value: "quit", label: "Quit" },
             ],
             initialValue: "restart",
@@ -592,7 +699,7 @@ async function runWizard(args) {
             return 0;
         return snapshot.agents.filter((agent) => agent.available !== false).length;
     }
-    let allowCompileVerify = installedAgentCount(agents) > 0;
+    let allowAgentRuns = installedAgentCount(agents) > 0;
     while (agents &&
         agents.engineSupportsAgents &&
         installedAgentCount(agents) === 0) {
@@ -602,12 +709,12 @@ async function runWizard(args) {
             return;
         }
         if (decision === "skip") {
-            allowCompileVerify = false;
+            allowAgentRuns = false;
             break;
         }
         // decision === "rerun"
         agents = await fetchAgentSnapshot(conn);
-        allowCompileVerify = installedAgentCount(agents) > 0;
+        allowAgentRuns = installedAgentCount(agents) > 0;
     }
     if (agents && agents.engineSupportsAgents && installedAgentCount(agents) > 0) {
         // Always confirm the active agent before the action menu. Pre-select
@@ -664,7 +771,7 @@ async function runWizard(args) {
     }
     for (;;) {
         console.log();
-        const next = await showActionMenu(conn, { allowCompileVerify });
+        const next = await showActionMenu(conn, { allowAgentRuns });
         if (next === "exit")
             break;
     }

package/dist/cli/index.d.ts

@@ -1,6 +1,6 @@
 import { agentsCommand } from "./commands/agents.js";
 import { compileCommand } from "./commands/compile.js";
-import { verifyCommand } from "./commands/verify.js";
+import { testCommand } from "./commands/test.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { methodCommand } from "./commands/method.js";
 import { mcpCommand } from "./commands/mcp.js";
@@ -22,4 +22,4 @@ export declare function runCli(argv?: string[]): {
     _: (string | number)[];
     $0: string;
 }>;
-export { initCommand, compileCommand, verifyCommand, agentsCommand, doctorCommand, methodCommand, mcpCommand, runsCommand, statusCommand, resetCommand, webCommand, prepCommand, loginCommand, logoutCommand, wizardCommand, };
+export { initCommand, compileCommand, testCommand, agentsCommand, doctorCommand, methodCommand, mcpCommand, runsCommand, statusCommand, resetCommand, webCommand, prepCommand, loginCommand, logoutCommand, wizardCommand, };