@interf/compiler 0.13.0 → 0.18.0

package/dist/cli/commands/mcp.js

@@ -0,0 +1,239 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
+import { LOCAL_SERVICE_ROUTES, preparationResourcePath, preparationSubresourcePath, runResourcePath, runSubresourcePath, } from "../../packages/engine/routes.js";
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url ?? null,
+        authTokenOverride: args.token ?? null,
+    });
+    if (!conn) {
+        process.stderr.write(`${CONNECT_OR_ERROR_HINT}\n`);
+        process.exit(1);
+    }
+    return {
+        url: trimTrailingSlash(conn.url),
+        token: conn.auth_token ?? null,
+    };
+}
+async function callApi(conn, path, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (conn.token)
+        headers.set("authorization", `Bearer ${conn.token}`);
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const response = await fetch(`${conn.url}${path}`, { ...init, headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw.length > 0) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = raw;
+        }
+    }
+    return { status: response.status, body, raw };
+}
+function toolResultJson(payload) {
+    const text = typeof payload === "string"
+        ? payload
+        : JSON.stringify(payload, null, 2);
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+function toolErrorJson(message, payload) {
+    const text = payload !== undefined
+        ? `${message}\n${typeof payload === "string" ? payload : JSON.stringify(payload, null, 2)}`
+        : message;
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+async function callAndReturn(conn, path, init = {}) {
+    const response = await callApi(conn, path, init);
+    if (response.status >= 200 && response.status < 300) {
+        return toolResultJson(response.body ?? response.raw);
+    }
+    return toolErrorJson(`Local service responded with HTTP ${response.status}.`, response.body ?? response.raw);
+}
+function registerTools(server, conn) {
+    // ── Preparations ────────────────────────────────────────────────────────
+    server.registerTool("prep_list", {
+        title: "List preparations",
+        description: "List every Preparation registered on the connected Interf instance, "
+            + "with source binding, Method id, and current readiness.",
+        inputSchema: {},
+    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.preparations));
+    server.registerTool("prep_create", {
+        title: "Create a preparation",
+        description: "Create a new Preparation. The Preparation binds a Source Folder "
+            + "to an optional Method and is the saved unit of work for compile runs.",
+        inputSchema: {
+            id: z.string().min(1).describe("Preparation id (kebab-case)."),
+            source_path: z.string().min(1).describe("Absolute or workspace-relative Source Folder path."),
+            method_id: z.string().min(1).optional().describe("Optional Method id to bind. Bind later with prep_set_method if omitted."),
+            about: z.string().min(1).optional().describe("Optional human-readable description."),
+        },
+    }, async (args) => callAndReturn(conn, LOCAL_SERVICE_ROUTES.preparations, {
+        method: "POST",
+        body: JSON.stringify({
+            id: args.id,
+            source: { kind: "local-folder", locator: args.source_path },
+            ...(args.method_id ? { method_id: args.method_id } : {}),
+            ...(args.about ? { about: args.about } : {}),
+        }),
+    }));
+    server.registerTool("prep_show", {
+        title: "Show one preparation",
+        description: "Return the full resource for one Preparation by id.",
+        inputSchema: {
+            id: z.string().min(1).describe("Preparation id."),
+        },
+    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id)));
+    server.registerTool("prep_set_method", {
+        title: "Bind a Method to a preparation",
+        description: "Update the Method binding on a Preparation. Use this to swap "
+            + "Methods between compile runs without rebuilding the Preparation.",
+        inputSchema: {
+            id: z.string().min(1).describe("Preparation id."),
+            method_id: z.string().min(1).describe("Method id to bind."),
+        },
+    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id), {
+        method: "PATCH",
+        body: JSON.stringify({ method_id: args.method_id }),
+    }));
+    server.registerTool("prep_remove", {
+        title: "Remove a preparation",
+        description: "Delete a Preparation. Portable context is removed too.",
+        inputSchema: {
+            id: z.string().min(1).describe("Preparation id."),
+        },
+    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id), {
+        method: "DELETE",
+    }));
+    // ── Compile + verify runs ──────────────────────────────────────────────
+    server.registerTool("prep_compile", {
+        title: "Start a compile run",
+        description: "Kick off a compile run for a Preparation. Returns the new run "
+            + "resource immediately; use runs_status to poll progress and "
+            + "runs_fetch when the run finishes.",
+        inputSchema: {
+            id: z.string().min(1).describe("Preparation id."),
+        },
+    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.id, "compileRuns"), { method: "POST", body: "{}" }));
+    server.registerTool("prep_verify", {
+        title: "Run readiness checks",
+        description: "Run the Preparation's readiness checks against the latest portable "
+            + "context. Verify runs always judge against the compiled output in 0.15+.",
+        inputSchema: {
+            id: z.string().min(1).describe("Preparation id."),
+        },
+    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.id, "verifyRuns"), {
+        method: "POST",
+        body: JSON.stringify({}),
+    }));
+    // ── Methods ─────────────────────────────────────────────────────────────
+    server.registerTool("method_list", {
+        title: "List Methods",
+        description: "List every Method visible to the connected instance: workspace "
+            + "drafts, the user library at ~/.interf/methods/, and bundled Methods.",
+        inputSchema: {},
+    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.methods));
+    server.registerTool("method_draft", {
+        title: "Author a new Method draft",
+        description: "Run the Method-authoring agent for a Preparation. Produces a new "
+            + "Method package draft under <workspace>/methods/<id>/.",
+        inputSchema: {
+            prep_id: z.string().min(1).describe("Preparation id."),
+        },
+    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.prep_id, "methodAuthoringRuns"), { method: "POST", body: "{}" }));
+    server.registerTool("method_improve", {
+        title: "Run Method improvement",
+        description: "Run the Method-improvement agent for a Preparation. Iterates on "
+            + "the bound Method based on the latest readiness-check results.",
+        inputSchema: {
+            prep_id: z.string().min(1).describe("Preparation id."),
+        },
+    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.prep_id, "methodImprovementRuns"), { method: "POST", body: "{}" }));
+    // ── Runs ────────────────────────────────────────────────────────────────
+    server.registerTool("runs_status", {
+        title: "Get run status",
+        description: "Return the run record for one observable run.",
+        inputSchema: {
+            run_id: z.string().min(1).describe("Run id."),
+        },
+    }, async (args) => callAndReturn(conn, runResourcePath(args.run_id)));
+    server.registerTool("runs_watch", {
+        title: "Read run events",
+        description: "Read the events log for one run as a snapshot. Returns the same "
+            + "stream the UI consumes via SSE; agents that need live progress "
+            + "should poll runs_status until the run reaches a terminal state.",
+        inputSchema: {
+            run_id: z.string().min(1).describe("Run id."),
+        },
+    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "events")));
+    server.registerTool("runs_cancel", {
+        title: "Cancel a run",
+        description: "Request cancellation of an in-flight run.",
+        inputSchema: {
+            run_id: z.string().min(1).describe("Run id."),
+        },
+    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "cancel"), { method: "POST", body: "{}" }));
+    server.registerTool("runs_fetch", {
+        title: "Fetch run artifacts",
+        description: "Return the artifact manifest for a finished run (portable context, "
+            + "proof records, logs, run-scoped audit trail).",
+        inputSchema: {
+            run_id: z.string().min(1).describe("Run id."),
+        },
+    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "artifacts")));
+    // ── Instance ────────────────────────────────────────────────────────────
+    server.registerTool("instance_status", {
+        title: "Show instance status",
+        description: "Return the engine's instance resource: started_at, package "
+            + "version, registered preparations, active runs, idle seconds.",
+        inputSchema: {},
+    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.instance));
+}
+async function startStdioServer(args) {
+    const conn = resolveConnection(args);
+    const server = new McpServer({ name: "interf", version: "0.14.0" }, { capabilities: { tools: {} } });
+    registerTools(server, conn);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+export const mcpCommand = {
+    command: "mcp",
+    describe: "Run the Interf Model Context Protocol server (stdio by default).",
+    builder: (yargs) => yargs
+        .option("transport", {
+        type: "string",
+        choices: ["stdio", "http"],
+        default: "stdio",
+        describe: "Transport for the MCP server.",
+    })
+        .option("url", {
+        type: "string",
+        describe: "Override the active connection URL.",
+    })
+        .option("token", {
+        type: "string",
+        describe: "Override the active bearer token.",
+    }),
+    handler: async (args) => {
+        if (args.transport && args.transport !== "stdio") {
+            process.stderr.write("interf mcp: only the stdio transport is implemented today. "
+                + "Open an issue if you need --transport=http.\n");
+            process.exit(2);
+        }
+        await startStdioServer(args);
+    },
+};

package/dist/cli/commands/method.js

@@ -8,7 +8,7 @@
  */
 import chalk from "chalk";
 import { resolve } from "node:path";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,

package/dist/cli/commands/prep.js

@@ -12,8 +12,8 @@
  */
 import { resolve } from "node:path";
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/local-service/connection-config.js";
-import { preparationResourcePath } from "../../packages/local-service/routes.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
+import { preparationResourcePath } from "../../packages/engine/routes.js";
 function requireConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -45,6 +45,52 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+function statusColor(status) {
+    if (status === "ready")
+        return chalk.green;
+    if (status === "failed")
+        return chalk.red;
+    if (status === "skipped")
+        return chalk.dim;
+    return chalk.yellow;
+}
+function renderPreparationSummary(prep) {
+    console.log();
+    console.log(`  ${chalk.bold(prep.name)}`);
+    if (prep.method_id)
+        console.log(chalk.dim(`    method:  ${prep.method_id}`));
+    if (prep.source_path)
+        console.log(chalk.dim(`    source:  ${prep.source_path}`));
+    if (prep.portable_context_path) {
+        console.log(chalk.dim(`    output:  ${prep.portable_context_path}`));
+    }
+    if (prep.readiness?.status) {
+        const aggColor = prep.readiness.ready ? chalk.green : chalk.yellow;
+        console.log(`    readiness: ${aggColor(prep.readiness.status)}${prep.readiness.summary ? chalk.dim(` (${prep.readiness.summary})`) : ""}`);
+    }
+    if (prep.artifacts && prep.artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        const idWidth = Math.max(...prep.artifacts.map((entry) => entry.artifact_id.length), 8);
+        for (const artifact of prep.artifacts) {
+            const colored = statusColor(artifact.status)(artifact.status);
+            const stages = artifact.built_by_stages && artifact.built_by_stages.length > 0
+                ? chalk.dim(` ← ${artifact.built_by_stages.join(", ")}`)
+                : "";
+            console.log(`      ${artifact.artifact_id.padEnd(idWidth)}  ${colored}${stages}`);
+        }
+    }
+    if (prep.latest_compile_run_id) {
+        console.log();
+        console.log(chalk.dim(`    latest compile run: ${prep.latest_compile_run_id}`));
+    }
+    if (prep.latest_test_run_id) {
+        console.log(chalk.dim(`    latest verify run:  ${prep.latest_test_run_id}`));
+    }
+    console.log();
+    console.log(chalk.dim(`  Run with --json for the raw resource record.`));
+    console.log();
+}
 export const prepCommand = {
     command: "prep <subcommand>",
     describe: "Manage preparations on the connected instance",
@@ -78,17 +124,17 @@ export const prepCommand = {
             console.log(chalk.dim(`    readiness: ${readiness}`));
         }
     })
-        .command("create <prep-id>", "Create a preparation", (y) => y
+        .command("create <prep-id>", "Create a preparation (method binding optional — set later if you don't have one yet)", (y) => y
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id (lowercase, dash-separated)" })
         .option("source", { type: "string", demandOption: true, describe: "Path to the Source Folder" })
-        .option("method", { type: "string", demandOption: true, describe: "Method id (e.g. interf-default)" })
+        .option("method", { type: "string", describe: "Method id (e.g. interf-default). Optional — bind later via `interf prep set-method`." })
         .option("about", { type: "string", describe: "One-line description of the agent work" }), async (args) => {
         const { url, token } = requireConnection(args);
         const sourceAbs = resolve(process.cwd(), args.source);
         const requestBody = {
             id: args.prepId,
             source: { kind: "local-folder", locator: sourceAbs },
-            method_id: args.method,
+            ...(args.method ? { method_id: args.method } : {}),
             about: args.about,
             checks: [],
         };
@@ -100,11 +146,35 @@ export const prepCommand = {
             process.exit(1);
         }
         console.log(chalk.green(`Created preparation ${chalk.bold(args.prepId)}.`));
+        if (!args.method) {
+            console.log(chalk.dim(`  no method bound yet — pick or draft one before compiling:`));
+            console.log(chalk.dim(`    interf prep set-method ${args.prepId} <method-id>`));
+            console.log(chalk.dim(`    interf method draft ${args.prepId}`));
+        }
         if (body?.portable_context?.value) {
             console.log(chalk.dim(`  portable context (locator): ${body.portable_context.value}`));
         }
     })
-        .command("show <prep-id>", "Show a preparation's full record", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
+        .command("set-method <prep-id> <method-id>", "Bind a method to a preparation (or change which method it uses)", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .positional("method-id", { type: "string", demandOption: true, describe: "Method id to bind" }), async (args) => {
+        const { url, token } = requireConnection(args);
+        const { status, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token, { method: "PATCH", body: JSON.stringify({ method_id: args.methodId }) });
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to set method (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`Bound ${chalk.bold(args.methodId)} to ${chalk.bold(args.prepId)}.`));
+    })
+        .command("show <prep-id>", "Show a preparation's full record", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
         const { url, token } = requireConnection(args);
         const { status, body, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token);
         if (status !== 200) {
@@ -113,7 +183,11 @@ export const prepCommand = {
                 console.error(raw);
             process.exit(1);
         }
-        console.log(JSON.stringify(body, null, 2));
+        if (args.json || !body) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
+        }
+        renderPreparationSummary(body);
     })
         .command("rm <prep-id>", "Delete a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
         const { url, token } = requireConnection(args);

package/dist/cli/commands/reset.js

@@ -5,7 +5,7 @@
  *   interf reset bristol --mode all  # also clear method draft / runs
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,

package/dist/cli/commands/runs.js

@@ -9,7 +9,7 @@
 import chalk from "chalk";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,

package/dist/cli/commands/status.js

@@ -2,7 +2,7 @@
  * `interf status` — print connection state + preparation summary.
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 async function callJson(url, token) {
     const headers = new Headers();
     if (token)

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

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

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

@@ -1,13 +1,17 @@
 /**
- * `interf test <prep-id>` — start a readiness-check (test) run for a preparation.
+ * `interf verify <prep-id>` — verify a preparation's claim-checks via a
+ * judge against the latest compiled portable context (default) or
+ * against the source folder baseline (`--target source-files`). The
+ * source-files target reveals how much value the Method actually adds.
+ * Together with the method's structural checks (auto-run on every
+ * `interf compile`), this feeds the preparation's overall readiness
+ * state.
  *
- *   interf test bristol
- *   interf test bristol --target source-files
- *   interf test bristol --target portable-context
- *   interf test bristol --target both
+ *   interf verify bristol
+ *   interf verify bristol --target source-files
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/local-service/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -38,31 +42,42 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
-export const testCommand = {
-    command: "test <prep-id>",
-    describe: "Run readiness checks for a preparation",
+export const verifyCommand = {
+    command: "verify <prep-id>",
+    describe: "Verify a preparation's claim-checks against its portable context (or source-files baseline)",
     builder: (yargs) => yargs
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
         .option("target", {
         type: "string",
-        choices: ["source-files", "portable-context", "both"],
-        default: "both",
-        describe: "Which surface to test against",
+        choices: ["compiled", "source-files"],
+        default: "compiled",
+        describe: "Judge target: 'compiled' (default) checks the portable context, 'source-files' checks the raw source folder 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);
-        const mode = args.target === "portable-context" ? "compiled" : args.target === "source-files" ? "source-files" : "both";
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/test-runs`, token, { method: "POST", body: JSON.stringify({ mode }) });
+        // 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.
+        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("  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);
+        }
+        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 test run for ${args.prepId} (HTTP ${status}).`));
+            console.error(chalk.red(`Failed to start verify 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

@@ -11,11 +11,11 @@
  */
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
-import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, buildLocalServiceUrl, } from "../../packages/local-service/routes.js";
-import { startLocalService } from "../../packages/local-service/server.js";
-import { createNativeLocalServiceRunHandlers } from "../../packages/local-service/native-run-handlers.js";
-import { CONNECT_OR_ERROR_HINT, clearConnection, readActiveConnection, } from "../../packages/local-service/connection-config.js";
-import { serviceRegistryPath } from "../../packages/local-service/instance-paths.js";
+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 { serviceRegistryPath } from "../../packages/engine/instance-paths.js";
 function packageVersionFromManifest() {
     try {
         const url = new URL("../../../package.json", import.meta.url);
@@ -85,28 +85,81 @@ function findEnginePidByUrl(url) {
         return null;
     }
 }
+function isPidAlive(pid) {
+    try {
+        // Signal 0 is a no-op probe — succeeds if the PID exists and we can
+        // signal it; throws ESRCH otherwise.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan ~/.interf/services.json for engines whose PID is still alive.
+ * Used by `interf web stop` when ~/.interf/connection.json is missing
+ * — the registry tells us which engine processes are actually running
+ * regardless of which one the wizard last connected to.
+ */
+function listLiveEnginesFromRegistry() {
+    try {
+        const raw = readFileSync(serviceRegistryPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return (parsed.services ?? []).filter((entry) => typeof entry.pid === "number" && isPidAlive(entry.pid));
+    }
+    catch {
+        return [];
+    }
+}
 async function runWebStop(args) {
+    // Resolution order: explicit --url override → active connection.json
+    // → fall back to scanning services.json for any live engine. The
+    // last fallback recovers from the case where connection.json was
+    // cleared while an engine was still running (e.g. another `interf
+    // web` attempt failed mid-startup, or `interf logout` was run while
+    // the engine kept going).
     const conn = readActiveConnection({
         urlOverride: args.url,
         authTokenOverride: args.token,
     });
-    if (!conn) {
-        console.error("No active Interf connection to stop.");
-        process.exit(1);
-    }
-    const url = conn.url.replace(/\/+$/, "");
-    const pid = findEnginePidByUrl(url);
-    if (!pid) {
-        console.error(`Could not locate engine PID for ${url}.`);
-        process.exit(1);
+    let urlToStop = conn ? conn.url.replace(/\/+$/, "") : null;
+    let pidToStop = urlToStop ? findEnginePidByUrl(urlToStop) : null;
+    if (!pidToStop) {
+        const liveEngines = listLiveEnginesFromRegistry();
+        if (liveEngines.length === 0) {
+            console.error("No live Interf engine to stop.");
+            console.error("Checked ~/.interf/connection.json and ~/.interf/services.json — neither pointed at a running process.");
+            process.exit(1);
+        }
+        if (liveEngines.length > 1 && !urlToStop) {
+            console.error(`Multiple live Interf engines registered. Pick one with --url:`);
+            for (const entry of liveEngines) {
+                console.error(`  ${entry.url} (pid ${entry.pid})`);
+            }
+            process.exit(1);
+        }
+        const target = urlToStop
+            ? liveEngines.find((entry) => entry.url === urlToStop)
+            : liveEngines[0];
+        if (!target) {
+            console.error(`No live engine matches ${urlToStop ?? "the active connection"} in services.json.`);
+            process.exit(1);
+        }
+        urlToStop = target.url;
+        pidToStop = target.pid;
+        if (!conn) {
+            console.log(chalk.dim(`  No active connection.json — recovering engine pid ${pidToStop} from services.json.`));
+        }
     }
     try {
-        process.kill(pid, "SIGTERM");
-        console.log(chalk.green(`Sent SIGTERM to engine pid ${pid} (${url}).`));
-        clearConnection();
+        process.kill(pidToStop, "SIGTERM");
+        console.log(chalk.green(`Sent SIGTERM to engine pid ${pidToStop} (${urlToStop}).`));
+        if (conn)
+            clearConnection();
     }
     catch (error) {
-        console.error(`Failed to stop engine pid ${pid}: ${error instanceof Error ? error.message : String(error)}`);
+        console.error(`Failed to stop engine pid ${pidToStop}: ${error instanceof Error ? error.message : String(error)}`);
         process.exit(1);
     }
 }